@farmslot/recipe-runner 0.23.0

package/dist/core/runner.js

@@ -0,0 +1,738 @@
+import { mkdir, mkdtemp, rm, stat } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { digestRecipeDocument, getRecipeActionManifestActionNames, validateRecipeArtifactPackage, } from '@farmslot/protocol';
+import { JsonArtifactWriter, JsonSummaryWriter, JsonTraceWriter } from '../node/writers.js';
+import { createCaptureHelperVideoRecorder, errorMessage, manifestTarget, } from '../recording/capture-helper.js';
+import { writeRecordingTimeline } from '../recording/timeline.js';
+import { RECIPE_RUNNER_VERSION } from '../version.js';
+import { resolveRecipeDependencies, rootResolutionRef, validateRecipeDependencyParams, } from './compose.js';
+import { executeRecipe } from './execution.js';
+import { RecipeExecutionError, recipeFailureCause } from './failure.js';
+import { extractWorkflowGraph } from './graph.js';
+import { buildHudNode } from './hud.js';
+import { createRecipeInvocation } from './invocation.js';
+import { isRecord, normalizeRelativePath, readJsonFile } from './json.js';
+import { loadRecipeLibraries, logRecipeLibraryShadows, logRecipeLibrarySources, } from './library.js';
+import { resolveRecipeParams } from './parameters.js';
+import { defaultObserverRefsFromManifest } from './passive-observations.js';
+import { copyFileWithinRoots, statFileWithinRoot } from './path.js';
+import { cleanupAbortedRunVideoRecording, removePartialRunVideoOutput, } from './recording-cleanup.js';
+import { RecipeResolutionError } from './resolution-error.js';
+import { buildRecipeExecutionPlan, enforceRecipeExecutionPlan, recipeSourceForRequest, verifyExecutableSource, } from './trust.js';
+import { RECIPE_TRUST_ENV } from './trust-input.js';
+import { assertManifestIsValid, assertRecipeMatchesManifest } from './validation.js';
+const RUNNER_BUILT_IN_ACTIONS = new Set(['call', 'end']);
+const noopLogger = {
+    info() { },
+    warn() { },
+    error() { },
+};
+export function defineActionAdapter(adapter) {
+    if (!adapter.action.trim())
+        throw new Error('Action adapter action must be a non-empty string.');
+    return adapter;
+}
+export function createRecipeRunner(options) {
+    assertManifestIsValid(options.actionManifest);
+    const declaredActions = new Set(getRecipeActionManifestActionNames(options.actionManifest));
+    const adapterMap = new Map();
+    for (const adapter of options.adapters) {
+        if (!adapter.action.trim())
+            throw new Error('Action adapter action must be a non-empty string.');
+        if (!declaredActions.has(adapter.action) && adapter.testOnly !== true) {
+            throw new Error(`Adapter ${adapter.action} is not declared by the recipe action manifest.`);
+        }
+        if (adapterMap.has(adapter.action)) {
+            throw new Error(`Adapter ${adapter.action} is registered more than once.`);
+        }
+        adapterMap.set(adapter.action, adapter);
+    }
+    for (const action of declaredActions) {
+        if (!adapterMap.has(action) && !RUNNER_BUILT_IN_ACTIONS.has(action)) {
+            throw new Error(`Manifest action ${action} has no registered adapter.`);
+        }
+    }
+    return new DefaultRecipeRunner(options.actionManifest, adapterMap, options.logger ?? noopLogger, options.hud, options.runner, options.recording, options.defaultSource, options.blockedCapabilities);
+}
+function collectWatchLogPaths(paths, nodes) {
+    for (const node of Object.values(nodes)) {
+        if (!isRecord(node) || node.action !== 'watch_logs' || typeof node.path !== 'string')
+            continue;
+        paths.add(normalizeRelativePath(node.path).split(path.sep).join('/'));
+    }
+}
+async function collectRunFileOffsets({ graph, recipes, projectRoot, }) {
+    const offsets = new Map();
+    const paths = new Set();
+    collectWatchLogPaths(paths, graph.nodes);
+    for (const recipe of recipes.values()) {
+        if (recipe.aliasFor)
+            continue;
+        collectWatchLogPaths(paths, extractWorkflowGraph(recipe.document).nodes);
+    }
+    for (const relativePath of paths) {
+        try {
+            const info = await statFileWithinRoot(projectRoot, relativePath);
+            offsets.set(relativePath, info.size);
+        }
+        catch (error) {
+            if (!isNodeFileMissingError(error))
+                throw error;
+            offsets.set(relativePath, 0);
+        }
+    }
+    return offsets;
+}
+function isNodeFileMissingError(error) {
+    return isRecord(error) && error.code === 'ENOENT';
+}
+class DefaultRecipeRunner {
+    #actionManifest;
+    #adapters;
+    #logger;
+    #defaultObserverRefs;
+    #hud;
+    #runnerProvenance;
+    #recording;
+    #defaultSource;
+    #blockedCapabilities;
+    constructor(actionManifest, adapters, logger, hud, runnerProvenance, recording, defaultSource, blockedCapabilities) {
+        this.#actionManifest = actionManifest;
+        this.#adapters = adapters;
+        this.#logger = logger;
+        this.#defaultObserverRefs = defaultObserverRefsFromManifest(actionManifest);
+        this.#hud = hud;
+        this.#runnerProvenance = runnerProvenance;
+        this.#recording = recording;
+        this.#defaultSource = defaultSource;
+        this.#blockedCapabilities = blockedCapabilities;
+    }
+    async preflight(request) {
+        const { executionPlan } = await this.#resolveRequest(request);
+        enforceRecipeExecutionPlan(executionPlan, request, this.#blockedCapabilities);
+        return executionPlan;
+    }
+    async #resolveRequest(request) {
+        if (!request.recipePath && request.recipeDocument == null) {
+            throw new Error('Recipe run requires recipePath or recipeDocument.');
+        }
+        const projectRoot = path.resolve(request.projectRoot ?? process.cwd());
+        const artifactsDir = path.resolve(request.artifactsDir);
+        const env = {
+            ...(request.inheritProcessEnv === false ? {} : process.env),
+            ...(request.env ?? {}),
+        };
+        const trustEnv = new Set(Object.values(RECIPE_TRUST_ENV));
+        for (const [key, value] of Object.entries(env)) {
+            if (value === undefined || trustEnv.has(key))
+                delete env[key];
+        }
+        const sourceRecipePath = request.recipePath ? path.resolve(request.recipePath) : undefined;
+        const recipe = request.recipeDocument ?? (await readJsonFile(sourceRecipePath));
+        if (!isRecord(recipe))
+            throw new Error('Recipe document must be an object.');
+        const recipeSource = recipeSourceForRequest(request, recipe, sourceRecipePath, this.#defaultSource);
+        const libraryResolution = request.librarySources && request.librarySources.length > 0
+            ? await loadRecipeLibraries(request.librarySources, {
+                adapter: request.adapter,
+                ...(request.packageVersions ? { packageVersions: request.packageVersions } : {}),
+            })
+            : undefined;
+        if (libraryResolution)
+            logRecipeLibrarySources(this.#logger, libraryResolution);
+        const recipes = libraryResolution?.recipes ?? new Map();
+        const externalRecipeIds = new Set(recipes.keys());
+        assertRecipeMatchesManifest(recipe, this.#actionManifest, {
+            externalRecipeIds,
+            adapter: request.adapter,
+        });
+        const graph = extractWorkflowGraph(recipe);
+        if (request.stopAfterNode !== undefined) {
+            const stoppable = [...graph.mainNodeIds].filter((nodeId) => graph.nodes[nodeId]?.action !== 'end');
+            if (!stoppable.includes(request.stopAfterNode)) {
+                throw new RecipeResolutionError('RECIPE_STOP_AFTER_NODE_INVALID', `stop-after-node ${request.stopAfterNode} is not a non-terminal node reachable from workflow.entry.`, `choose one of: ${stoppable.join(', ')}`);
+            }
+        }
+        const rootRef = rootRecipeRef(sourceRecipePath, recipes, recipeSource.digest);
+        const dependencyResolution = resolveRecipeDependencies({
+            rootRef,
+            root: recipe,
+            rootSource: recipeSource,
+            recipes,
+        });
+        if (libraryResolution) {
+            // Warn only about shadowed refs this run executes, not every winner in the libraries.
+            logRecipeLibraryShadows(this.#logger, libraryResolution, new Set([rootRef, ...dependencyResolution.recipes.keys()]));
+        }
+        if (request.selection) {
+            const { name, resolvedBy, source, file } = request.selection;
+            this.#logger.info(`Recipe ${name} selected by ${resolvedBy}: ${source} · ${file}`);
+        }
+        for (const resolved of dependencyResolution.recipes.values()) {
+            assertRecipeMatchesManifest(resolved.document, this.#actionManifest, {
+                externalRecipeIds,
+                adapter: request.adapter,
+            });
+        }
+        const params = resolveRecipeParams(rootRef, recipe, request.params ?? {});
+        validateRecipeDependencyParams({
+            root: recipe,
+            params,
+            recipes: dependencyResolution.recipes,
+        });
+        const executionPlan = buildRecipeExecutionPlan({
+            recipe,
+            params,
+            source: recipeSource,
+            recipes: dependencyResolution.recipes,
+            adapters: this.#adapters,
+            actionManifest: this.#actionManifest,
+            defaultObserverRefs: this.#defaultObserverRefs,
+            projectRoot,
+            artifactsDir,
+            env,
+            hud: this.#hud,
+            recordVideo: request.recordVideo,
+        });
+        return {
+            projectRoot,
+            artifactsDir,
+            sourceRecipePath,
+            recipe,
+            rootRef,
+            params,
+            recipeSource,
+            env,
+            libraryResolution,
+            graph,
+            recipes: dependencyResolution.recipes,
+            dependencyResolution,
+            executionPlan,
+        };
+    }
+    async run(request) {
+        const { projectRoot, artifactsDir, recipe, rootRef, params, env, libraryResolution, graph, recipes, dependencyResolution, executionPlan, } = await this.#resolveRequest(request);
+        enforceRecipeExecutionPlan(executionPlan, request, this.#blockedCapabilities);
+        const startedAt = new Date();
+        await mkdir(artifactsDir, { recursive: true });
+        const runFileOffsets = await collectRunFileOffsets({
+            graph,
+            recipes,
+            projectRoot,
+        });
+        const artifactWriter = new JsonArtifactWriter(artifactsDir);
+        const traceWriter = new JsonTraceWriter(artifactsDir, this.#runnerProvenance);
+        const summaryWriter = new JsonSummaryWriter(artifactsDir);
+        let outputs = new Map();
+        const recipePath = await artifactWriter.copyRecipe(recipe);
+        const invocation = createRecipeInvocation(recipe, params, startedAt.toISOString());
+        await artifactWriter.writeInvocation(invocation);
+        for (const dependency of dependencyResolution.recipes.values()) {
+            await artifactWriter.copyResolvedRecipe(dependency.provenance.digest, dependency.document);
+        }
+        await artifactWriter.writeRecipeResolution(dependencyResolution.document);
+        let status = 'unknown';
+        const videoOptions = normalizeVideoRecordingOptions(request.recordVideo);
+        const videoRecorder = videoOptions.mode !== 'off' ? this.#videoRecorder() : undefined;
+        let runRecording;
+        let canExecute = true;
+        if (videoRecorder) {
+            try {
+                runRecording = await this.#startRunVideoRecording({
+                    recorder: videoRecorder,
+                    videoOptions,
+                    recipe,
+                    projectRoot,
+                    artifactsDir,
+                    env,
+                });
+            }
+            catch (error) {
+                const message = errorMessage(error);
+                const causeClass = recipeFailureCause(error, 'harness');
+                traceWriter.record({
+                    nodeId: 'recipe-run:video',
+                    action: 'record.video',
+                    startedAt: startedAt.toISOString(),
+                    endedAt: new Date().toISOString(),
+                    durationMs: Date.now() - startedAt.getTime(),
+                    ok: false,
+                    cause_class: causeClass,
+                    error: message,
+                });
+                this.#logger.error(`record.video start failed: ${message}`);
+                status = 'fail';
+                canExecute = false;
+            }
+        }
+        try {
+            if (canExecute) {
+                const execution = await executeRecipe({
+                    ref: rootRef,
+                    adapter: request.adapter,
+                    recipe,
+                    params,
+                    recipes,
+                    actionManifest: this.#actionManifest,
+                    adapters: this.#adapters,
+                    traceWriter,
+                    logger: this.#logger,
+                    defaultObserverRefs: this.#defaultObserverRefs,
+                    createContext: (nodeId, activeRecipe, activeOutputs, getOutput) => this.#createExecutionContext({
+                        nodeId,
+                        recipe: activeRecipe,
+                        projectRoot,
+                        artifactsDir,
+                        env,
+                        outputs: activeOutputs,
+                        getOutput,
+                        artifactWriter,
+                        runFileOffsets,
+                        recording: runRecording,
+                    }),
+                    registerArtifacts: (artifacts) => {
+                        for (const artifact of artifacts)
+                            artifactWriter.register(artifact);
+                    },
+                    publishHudProgress: (hudStatus, event) => this.#publishHudProgressOrRecord(traceWriter, hudStatus, event),
+                    ...(request.stopAfterNode !== undefined ? { stopAfterNode: request.stopAfterNode } : {}),
+                });
+                status = execution.status;
+                outputs = execution.outputs;
+            }
+            artifactWriter.register({
+                path: 'summary.json',
+                type: 'summary',
+                label: 'Run summary',
+                category: 'system',
+            });
+            artifactWriter.register({
+                path: 'trace.json',
+                type: 'trace',
+                label: 'Execution trace',
+                category: 'system',
+            });
+            if (status === 'pass') {
+                const runHudStartedAt = new Date();
+                try {
+                    await this.#publishRunHud(status, {
+                        recipe,
+                        projectRoot,
+                        artifactsDir,
+                        env,
+                        outputs,
+                    });
+                }
+                catch (error) {
+                    const message = error instanceof Error ? error.message : String(error);
+                    traceWriter.record({
+                        nodeId: 'recipe-complete:hud',
+                        action: 'app.hud',
+                        startedAt: runHudStartedAt.toISOString(),
+                        endedAt: new Date().toISOString(),
+                        durationMs: Date.now() - runHudStartedAt.getTime(),
+                        ok: false,
+                        cause_class: 'harness',
+                        error: message,
+                    });
+                    this.#logger.error(`app.hud complete update failed: ${message}`);
+                    status = 'fail';
+                }
+            }
+            if (runRecording) {
+                const recordingToStop = runRecording;
+                runRecording = undefined;
+                try {
+                    const videoArtifact = await this.#stopRunVideoRecording(recordingToStop, traceWriter.list(), artifactWriter);
+                    artifactWriter.register(videoArtifact);
+                    if (videoArtifact.timelinePath)
+                        artifactWriter.register({
+                            path: videoArtifact.timelinePath,
+                            type: 'json',
+                            category: 'system',
+                            label: 'Recording frames and action markers',
+                        });
+                }
+                catch (error) {
+                    const message = errorMessage(error);
+                    await removePartialRunVideoOutput(recordingToStop.outputPath, this.#logger);
+                    await rm(recordingToStop.stagingRoot, { recursive: true, force: true });
+                    traceWriter.record({
+                        nodeId: 'recipe-run:video',
+                        action: 'record.video',
+                        startedAt: startedAt.toISOString(),
+                        endedAt: new Date().toISOString(),
+                        durationMs: Date.now() - startedAt.getTime(),
+                        ok: false,
+                        cause_class: recipeFailureCause(error, 'harness'),
+                        error: message,
+                    });
+                    this.#logger.error(`record.video failed: ${message}`);
+                    status = 'fail';
+                }
+            }
+        }
+        finally {
+            if (runRecording) {
+                const recordingToCleanup = runRecording;
+                runRecording = undefined;
+                await cleanupAbortedRunVideoRecording(recordingToCleanup, this.#logger);
+            }
+        }
+        const endedAt = new Date();
+        const tracePath = await traceWriter.write();
+        const trace = traceWriter.list();
+        const causeCounts = {
+            subject: trace.filter((entry) => !entry.ok && entry.cause_class === 'subject').length,
+            harness: trace.filter((entry) => !entry.ok && entry.cause_class === 'harness').length,
+            environment: trace.filter((entry) => !entry.ok && entry.cause_class === 'environment').length,
+            unknown: trace.filter((entry) => !entry.ok && entry.cause_class === 'unknown').length,
+        };
+        const summary = {
+            invocationDigest: digestRecipeDocument(invocation),
+            status,
+            total: trace.length,
+            passed: trace.filter((entry) => entry.ok).length,
+            failed: trace.filter((entry) => !entry.ok).length,
+            cause_counts: causeCounts,
+            startedAt: startedAt.toISOString(),
+            endedAt: endedAt.toISOString(),
+            durationMs: endedAt.getTime() - startedAt.getTime(),
+            harness: {
+                name: '@farmslot/recipe-runner',
+                version: RECIPE_RUNNER_VERSION,
+                action_manifest_schema: this.#actionManifest.$schema,
+            },
+            ...(this.#runnerProvenance ? { runner: this.#runnerProvenance } : {}),
+            ...(libraryResolution
+                ? { recipeLibraries: buildRecipeLibrarySummary(libraryResolution) }
+                : {}),
+            ...(request.selection ? { recipeSelection: request.selection } : {}),
+            ...(request.stopAfterNode !== undefined ? { stopAfterNode: request.stopAfterNode } : {}),
+        };
+        const summaryPath = await summaryWriter.write(summary);
+        const artifactManifestPath = await artifactWriter.write(status, this.#runnerProvenance);
+        const packageValidation = validateRecipeArtifactPackage({
+            recipe,
+            resolvedRecipes: Object.fromEntries([...dependencyResolution.recipes.values()].map((entry) => [
+                entry.provenance.digest,
+                entry.document,
+            ])),
+            recipeResolution: dependencyResolution.document,
+            trace,
+            summary,
+            manifest: {
+                version: 1,
+                runStatus: status,
+                ...(this.#runnerProvenance ? { provenance: { runner: this.#runnerProvenance } } : {}),
+                artifacts: artifactWriter.list(),
+            },
+            artifactPaths: [
+                'recipe.json',
+                'summary.json',
+                'trace.json',
+                'artifact-manifest.json',
+                'recipe-resolution.json',
+                ...artifactWriter.list().map((entry) => entry.path),
+            ],
+        });
+        if (packageValidation.status === 'invalid') {
+            throw new Error(`Generated artifact package is invalid: ${packageValidation.findings
+                .map((finding) => `${finding.code} ${finding.path}`)
+                .join(', ')}`);
+        }
+        return { status, summaryPath, tracePath, artifactManifestPath, recipePath };
+    }
+    #createExecutionContext({ nodeId, recipe, projectRoot, artifactsDir, env, outputs, getOutput, artifactWriter, runFileOffsets, recording, }) {
+        return {
+            nodeId,
+            recipe,
+            projectRoot,
+            artifactsDir,
+            env,
+            outputs,
+            getOutput,
+            ...(recording?.recording.snapshot
+                ? {
+                    captureRecordingSnapshot: async (relativePath) => {
+                        const relative = normalizeRelativePath(relativePath);
+                        if (!relative.endsWith('.png'))
+                            throw new Error('Recording snapshots must use a PNG artifact path.');
+                        const dir = await mkdtemp(path.join(recording.stagingRoot, 'snapshot-'));
+                        const staged = path.join(dir, 'frame.png');
+                        const evidence = await recording.recording.snapshot(staged);
+                        await copyFileWithinRoots(dir, 'frame.png', artifactsDir, relative);
+                        // Keep the provider's source path in its raw sidecar; the action output
+                        // maps it to the published artifact path without rewriting capture facts.
+                        return { ...evidence, sourceOutput: evidence.output, output: relative };
+                    },
+                }
+                : {}),
+            resolveProjectPath(relativePath) {
+                return path.join(projectRoot, normalizeRelativePath(relativePath));
+            },
+            resolveArtifactPath(relativePath) {
+                return path.join(artifactsDir, normalizeRelativePath(relativePath));
+            },
+            getRunFileOffset(relativePath) {
+                return runFileOffsets.get(normalizeRelativePath(relativePath).split(path.sep).join('/'));
+            },
+            registerArtifact(entry) {
+                artifactWriter.register(entry);
+            },
+            logger: this.#logger,
+        };
+    }
+    #videoRecorder() {
+        return this.#recording?.videoRecorder ?? createCaptureHelperVideoRecorder();
+    }
+    async #startRunVideoRecording({ recorder, videoOptions, recipe, projectRoot, artifactsDir, env, }) {
+        const doctor = await recorder.doctor?.();
+        if (doctor && !doctor.ok) {
+            throw new RecipeExecutionError('environment', `${recorder.name} doctor ${doctor.code}: ${doctor.message}${doctor.suggestedFix ? ` Suggested fix: ${doctor.suggestedFix}` : ''}`);
+        }
+        const node = {
+            action: 'record.video',
+            intent: 'Record the recipe run when motion proof is useful',
+        };
+        const target = videoOptions.target ??
+            (await this.#recording?.targetProvider?.resolveRecordingTarget({
+                nodeId: 'recipe-run',
+                node,
+                recipe,
+                projectRoot,
+                artifactsDir,
+                env,
+                scope: 'run',
+            }));
+        if (!target) {
+            throw new Error('--record-video requires a recording target. Provide a project RecordingTargetProvider or CLI target flags.');
+        }
+        const relativePath = 'videos/recipe-run.mp4';
+        const stagingRoot = await mkdtemp(path.join(os.tmpdir(), 'farmslot-recipe-video-'));
+        const stagingRelativePath = 'recipe-run.mp4';
+        const outputPath = path.join(stagingRoot, stagingRelativePath);
+        let recording;
+        try {
+            recording = await recorder.start({
+                outputPath,
+                target,
+                maxFps: videoOptions.maxFps,
+                maxSize: videoOptions.maxSize,
+                nodeId: 'recipe-run',
+                record: 'full_run',
+            });
+        }
+        catch (error) {
+            await removePartialRunVideoOutput(outputPath, this.#logger);
+            await rm(stagingRoot, { recursive: true, force: true });
+            throw error;
+        }
+        const entry = {
+            path: relativePath,
+            type: 'video',
+            mimeType: 'video/mp4',
+            category: 'proof',
+            label: 'Recipe run video',
+            record: 'full_run',
+            recorder: {
+                name: recorder.name,
+                ...(recorder.version ? { version: recorder.version } : {}),
+                ...(recorder.platform ? { platform: recorder.platform } : {}),
+                target: manifestTarget(target),
+            },
+            ...(videoOptions.maxFps != null ? { maxFps: videoOptions.maxFps } : {}),
+        };
+        return {
+            recording,
+            entry,
+            outputPath,
+            stagingRoot,
+            stagingRelativePath,
+            artifactsDir,
+        };
+    }
+    async #stopRunVideoRecording(runRecording, trace, artifactWriter) {
+        const result = await runRecording.recording.stop();
+        await assertVideoOutputReady(runRecording.outputPath);
+        await copyFileWithinRoots(runRecording.stagingRoot, runRecording.stagingRelativePath, runRecording.artifactsDir, runRecording.entry.path);
+        if (result.timingEvidencePath && result.timing) {
+            const evidencePath = `${runRecording.entry.path}.capture.json`;
+            await copyFileWithinRoots(runRecording.stagingRoot, result.timingEvidencePath, runRecording.artifactsDir, evidencePath);
+            artifactWriter.register({
+                path: evidencePath,
+                type: 'json',
+                category: 'system',
+                label: 'Native recording and snapshot timing',
+            });
+        }
+        await rm(runRecording.stagingRoot, { recursive: true, force: true });
+        const entry = {
+            ...runRecording.entry,
+            ...(result.recorder ? { recorder: result.recorder } : {}),
+        };
+        if (result.timing) {
+            try {
+                entry.timelinePath = await writeRecordingTimeline(runRecording.artifactsDir, entry.path, result.timing, trace);
+            }
+            catch (error) {
+                // Video is retained; its optional timing capability failed explicitly.
+                entry.timelineUnavailableReason = errorMessage(error);
+            }
+        }
+        else
+            entry.timelineUnavailableReason =
+                result.timingUnavailableReason ?? 'Recorder does not provide timeline alignment.';
+        return entry;
+    }
+    #hudAction() {
+        if (this.#hud === false || this.#hud?.enabled === false)
+            return undefined;
+        return this.#adapters.has('app.hud') ? 'app.hud' : undefined;
+    }
+    async #publishHudProgressOrRecord(traceWriter, status, event) {
+        const startedAt = new Date();
+        try {
+            await this.#publishHudProgress(status, event);
+            return true;
+        }
+        catch (error) {
+            // HUD is first-class when advertised, so rendering failures fail the run.
+            // They are still recorded instead of aborting artifact package writing.
+            const message = error instanceof Error ? error.message : String(error);
+            traceWriter.record({
+                nodeId: `${event.nodeId}:hud:${status}`,
+                action: 'app.hud',
+                startedAt: startedAt.toISOString(),
+                endedAt: new Date().toISOString(),
+                durationMs: Date.now() - startedAt.getTime(),
+                ok: false,
+                cause_class: 'harness',
+                error: message,
+            });
+            this.#logger.error(`app.hud ${status} update failed for ${event.nodeId}: ${message}`);
+            return false;
+        }
+    }
+    async #publishHudProgress(status, event) {
+        const hudAction = this.#hudAction();
+        if (!hudAction || event.action === hudAction)
+            return;
+        const adapter = this.#adapters.get(hudAction);
+        if (!adapter)
+            return;
+        await verifyExecutableSource(adapter, `Action ${hudAction}`);
+        await adapter.execute(buildHudNode(status, event, this.#hud), event.context);
+    }
+    async #publishRunHud(status, request) {
+        const hudAction = this.#hudAction();
+        if (!hudAction)
+            return;
+        const adapter = this.#adapters.get(hudAction);
+        if (!adapter)
+            return;
+        await verifyExecutableSource(adapter, `Action ${hudAction}`);
+        const context = {
+            nodeId: 'recipe-complete',
+            recipe: request.recipe,
+            projectRoot: request.projectRoot,
+            artifactsDir: request.artifactsDir,
+            env: request.env,
+            outputs: request.outputs,
+            getOutput(nodeId) {
+                if (!request.outputs.has(nodeId))
+                    throw new Error(`No output recorded for node ${nodeId}.`);
+                return request.outputs.get(nodeId);
+            },
+            resolveProjectPath(relativePath) {
+                return path.join(request.projectRoot, normalizeRelativePath(relativePath));
+            },
+            resolveArtifactPath(relativePath) {
+                return path.join(request.artifactsDir, normalizeRelativePath(relativePath));
+            },
+            getRunFileOffset() {
+                return undefined;
+            },
+            registerArtifact() { },
+            logger: this.#logger,
+        };
+        await adapter.execute({
+            action: hudAction,
+            title: this.#hudTitle(request.recipe),
+            status,
+            node_id: 'recipe-complete',
+            phase: 'complete',
+            flow: 'run',
+            detail: status === 'pass' ? 'Recipe completed' : 'Recipe failed',
+            text: status === 'pass' ? 'Recipe completed' : 'Recipe failed',
+            progress: { complete: true },
+        }, context);
+    }
+    #hudTitle(recipe) {
+        if (this.#hud && this.#hud.title)
+            return this.#hud.title;
+        if (isRecord(recipe) && typeof recipe.title === 'string')
+            return recipe.title;
+        return 'Recipe run';
+    }
+}
+function buildRecipeLibrarySummary(resolution) {
+    return {
+        sources: resolution.sources,
+        shadowed: collectShadowedRecipes(resolution),
+    };
+}
+function collectShadowedRecipes(resolution) {
+    return [...resolution.recipes.values()]
+        .filter((recipe) => !recipe.aliasFor)
+        .filter((recipe) => recipe.shadows.length > 0)
+        .map((recipe) => ({
+        ref: recipe.ref,
+        source: recipe.source,
+        file: recipe.file,
+        shadows: recipe.shadows,
+    }));
+}
+function rootRecipeRef(sourceRecipePath, recipes, digest) {
+    if (sourceRecipePath) {
+        const resolvedPath = path.resolve(sourceRecipePath);
+        const match = [...recipes.values()].find((recipe) => !recipe.aliasFor && path.resolve(recipe.path) === resolvedPath);
+        if (match)
+            return match.ref;
+        return rootResolutionRef(digest);
+    }
+    return rootResolutionRef(digest);
+}
+function normalizeVideoRecordingOptions(input) {
+    if (!input)
+        return { mode: 'off' };
+    if (input === true)
+        return { mode: 'full-run' };
+    if (typeof input === 'string')
+        return normalizeVideoRecordingMode(input);
+    const mode = input.mode ?? 'full-run';
+    return { ...input, mode: normalizeVideoRecordingMode(mode).mode };
+}
+function normalizeVideoRecordingMode(mode) {
+    if (mode === 'off')
+        return { mode: 'off' };
+    if (mode === 'full-run')
+        return { mode: 'full-run' };
+    if (mode === 'proof-window' || mode === 'proof_window') {
+        throw new Error('recordVideo proof-window mode is reserved for future focused clips; use full-run for phase 1.');
+    }
+    throw new Error(`recordVideo mode must be full-run or off, got ${JSON.stringify(mode)}.`);
+}
+async function assertVideoOutputReady(outputPath) {
+    let stats;
+    try {
+        stats = await stat(outputPath);
+    }
+    catch {
+        throw new Error(`Recording output is missing: ${outputPath}`);
+    }
+    if (stats.size <= 0)
+        throw new Error(`Recording output is empty: ${outputPath}`);
+}
+//# sourceMappingURL=runner.js.map