@mingchuno/agent-workflows 0.1.0 → 0.3.0

package/dist/src/runner.js

@@ -1,15 +1,21 @@
 import { randomUUID } from "node:crypto";
+import { realpathSync, statSync } from "node:fs";
 import { mkdir, realpath } from "node:fs/promises";
 import { resolve } from "node:path";
 import { DBOS } from "@dbos-inc/dbos-sdk";
 import { configSchema } from "./config.js";
 import { BlockedError, isBlockedError, } from "./domain.js";
+import { assertEvidenceDirectory } from "./evidence.js";
 import { defaultWorkflow, Operations } from "./operations.js";
+import { projectPrompts } from "./prompts.js";
+import { executionFingerprint, verifyPublicationRecovery } from "./recovery.js";
 import { createQueuedRun } from "./run-record.js";
 import { assertProcessesStopped, CheckoutOwnership, } from "./runtime/ownership.js";
 import { createRedactor, runtimeLogger } from "./runtime/redaction.js";
 import { Store } from "./store.js";
 import { ExistingCheckout } from "./workspace.js";
+const runnerPollIntervalMs = 100;
+const shutdownPollIntervalMs = 20;
 export class Runner {
     options;
     store;
@@ -17,6 +23,7 @@ export class Runner {
     controllers = new Map();
     active = new Map();
     hosting = new Map();
+    promptBaseDirectory;
     workflow;
     ownership = new CheckoutOwnership();
     stopping = false;
@@ -28,6 +35,16 @@ export class Runner {
     constructor(options) {
         this.options = options;
         this.config = configSchema.parse(options.config);
+        const pathBaseDirectory = canonicalDirectory(options.pathBaseDirectory ?? process.cwd(), "Configuration path base");
+        this.config.stateDirectory = resolve(pathBaseDirectory, this.config.stateDirectory);
+        for (const project of this.config.projects)
+            project.checkout = resolve(pathBaseDirectory, project.checkout);
+        const promptBaseDirectory = options.promptBaseDirectory
+            ? resolve(options.promptBaseDirectory)
+            : pathBaseDirectory;
+        this.promptBaseDirectory = promptBaseDirectory;
+        for (const project of this.config.projects)
+            projectPrompts(project, promptBaseDirectory);
         this.store = new Store(options.databaseUrl, this.config.id, this.redact);
     }
     queue(id) {
@@ -42,6 +59,7 @@ export class Runner {
         const ids = new Set();
         for (const project of this.config.projects) {
             project.checkout = await realpath(project.checkout);
+            this.config.stateDirectory = await assertEvidenceDirectory(project.checkout, this.config.stateDirectory);
             if (canonical.has(project.checkout) || ids.has(project.id))
                 throw new Error("Duplicate project identity or canonical checkout");
             canonical.add(project.checkout);
@@ -69,7 +87,7 @@ export class Runner {
         DBOS.setConfig({
             name: `agent-workflows-${this.config.id}`,
             systemDatabaseUrl: this.options.databaseUrl,
-            applicationVersion: `${this.config.id}-${this.options.workflowVersion ?? "phase1-v1"}`,
+            applicationVersion: `${this.config.id}-${this.options.workflowVersion ?? "phase1-v2"}`,
             executorID: this.config.id,
             listenQueues: this.config.projects.map((p) => this.queue(p.id)),
             logger: runtimeLogger(this.redact),
@@ -80,13 +98,13 @@ export class Runner {
             await DBOS.registerQueue(this.queue(project.id), {
                 globalConcurrency: 1,
                 workerConcurrency: 1,
-                minPollingIntervalMs: 100,
+                minPollingIntervalMs: runnerPollIntervalMs,
             });
         this.timer = setInterval(() => {
             void this.tick().catch((error) => this.store.emit(null, "runner-error", {
                 error: this.redact(String(error)),
             }));
-        }, 100);
+        }, runnerPollIntervalMs);
         await this.tick();
     }
     redact = (text) => createRedactor([
@@ -162,6 +180,8 @@ export class Runner {
                     await this.stop(request.target);
                 else if (request.kind === "retry")
                     await this.retry(request.target, request.id);
+                else if (request.kind === "recover")
+                    await this.recover(request.target, request.id);
                 else
                     throw new Error("Unknown command");
                 await this.store.finishCommand(request.id);
@@ -197,10 +217,7 @@ export class Runner {
                 (r.outcome === "queued" || r.outcome === "running"));
             if (!run || this.active.has(run.id))
                 continue;
-            const handle = await DBOS.startWorkflow(this.workflow, {
-                workflowID: run.id,
-                queueName: this.queue(project.id),
-            })(run.id);
+            const handle = await this.dispatch(run, project);
             const result = handle
                 .getResult()
                 .catch(async (error) => {
@@ -210,18 +227,40 @@ export class Runner {
             this.active.set(run.id, result);
         }
     }
+    async dispatch(run, project) {
+        const execution = run.executions?.at(-1);
+        if (execution?.recoveryOf) {
+            // Intent is committed first. On restart, adopt an existing fork instead of
+            // creating it twice after an uncertain DBOS response.
+            if (await DBOS.getWorkflowStatus(execution.id))
+                return DBOS.retrieveWorkflow(execution.id);
+            return DBOS.forkWorkflow(execution.recoveryOf, execution.startStep, {
+                newWorkflowID: execution.id,
+                queueName: this.queue(project.id),
+                applicationVersion: `${this.config.id}-${this.options.workflowVersion ?? "phase1-v2"}`,
+            });
+        }
+        return DBOS.startWorkflow(this.workflow, {
+            workflowID: run.id,
+            queueName: this.queue(project.id),
+        })(run.id);
+    }
     async recordWorkflowFailure(run, error) {
         const message = this.redact(String(error));
-        await this.store.emit(run.id, "workflow-error", { error: message });
+        const executionId = run.executions?.at(-1)?.id ?? run.id;
+        await this.store.emit(run.id, "workflow-error", {
+            executionId,
+            error: message,
+        });
         const current = await this.store.run(run.id);
+        if ((current.executions?.at(-1)?.id ?? current.id) !== executionId)
+            return;
         if (["queued", "running"].includes(current.outcome)) {
             await this.store.patchRun(run.id, {
                 outcome: "blocked",
                 error: message,
             });
-            await this.store.setProject(run.projectId, {
-                blocked: `DBOS execution failed for ${run.id}; inspect recovery evidence`,
-            });
+            await this.store.blockProject(run.projectId, `DBOS execution failed for ${run.id}; inspect recovery evidence`);
         }
     }
     async execute(runId) {
@@ -230,6 +269,8 @@ export class Runner {
             controller.abort();
         this.controllers.set(runId, controller);
         try {
+            if (DBOS.workflowID !== runId && this.options.workflow)
+                throw new BlockedError("Publication recovery supports the default workflow only");
             await this.executeOwned(runId, controller);
         }
         finally {
@@ -237,14 +278,16 @@ export class Runner {
         }
     }
     async executeOwned(runId, controller) {
-        const run = await DBOS.runStep(() => this.store.run(runId), {
+        const run = await DBOS.runStep(() => this.initializeExecution(runId), {
             name: "load-run",
         });
         const project = this.config.projects.find((p) => p.id === run.projectId);
         if (!project)
             throw new Error("Project removed from configuration");
         const workspace = this.options.workspace ?? new ExistingCheckout();
+        let recoveryChecked = false;
         const operations = new Operations(runId, {
+            promptBaseDirectory: this.promptBaseDirectory,
             store: this.store,
             project,
             workspace,
@@ -253,6 +296,36 @@ export class Runner {
             artifacts: resolve(this.config.stateDirectory),
             signal: controller.signal,
             redact: this.redact,
+            executionFingerprint: () => executionFingerprint(project, this.options.workflowVersion ?? "phase1-v2", controller.signal),
+            beforeStep: async () => {
+                if (recoveryChecked)
+                    return;
+                const current = await this.store.run(runId);
+                const execution = current.executions?.at(-1);
+                if (!execution?.recoveryOf) {
+                    await this.store.patchRun(runId, { outcome: "running" });
+                    recoveryChecked = true;
+                    return;
+                }
+                if (execution.id !== DBOS.workflowID)
+                    throw new BlockedError("Execution has been superseded");
+                if (DBOS.stepID < execution.startStep)
+                    throw new BlockedError("A reused checkpoint is missing; recovery refused");
+                // This runs inside the first non-replayed step, so copied start-gate
+                // checkpoints cannot bypass today's pause or checkout checks.
+                while (true) {
+                    controller.signal.throwIfAborted();
+                    const state = await this.store.project(project.id);
+                    if (state.blocked)
+                        throw new BlockedError(state.blocked);
+                    if (!state.paused)
+                        break;
+                    await new Promise((resolve) => setTimeout(resolve, runnerPollIntervalMs));
+                }
+                await this.store.patchRun(runId, { outcome: "running" });
+                await this.checkRecoveryState(current, project, controller.signal);
+                recoveryChecked = true;
+            },
         });
         try {
             while (true) {
@@ -293,9 +366,7 @@ export class Runner {
                     error: this.redact(String(error)),
                 });
                 if (unsafe || isBlockedError(error))
-                    await this.store.setProject(project.id, {
-                        blocked: `Run ${runId} requires recovery: ${this.redact(String(error))}`,
-                    });
+                    await this.store.blockProject(project.id, `Run ${runId} requires recovery: ${this.redact(String(error))}`);
             }, { name: "record-failure", retriesAllowed: false });
         }
         finally {
@@ -306,6 +377,27 @@ export class Runner {
         await this.store.project(projectId);
         await this.store.setProject(projectId, { paused: true });
     }
+    async initializeExecution(runId) {
+        const run = await this.store.run(runId);
+        if (run.executions?.length)
+            return run;
+        const project = this.config.projects.find((item) => item.id === run.projectId);
+        if (!project)
+            throw new Error("Project removed from configuration");
+        return this.store.patchRun(runId, {
+            executions: [
+                {
+                    id: run.id,
+                    // Capture inputs after prepare fetches and checks out the actual base.
+                    fingerprint: "",
+                    recoverySupported: !this.options.workflow,
+                    createdAt: run.createdAt,
+                    outcome: run.outcome,
+                    phase: run.phase,
+                },
+            ],
+        });
+    }
     async resume(projectId) {
         const state = await this.store.project(projectId);
         if (state.blocked)
@@ -318,11 +410,11 @@ export class Runner {
         if (controller) {
             controller.abort();
             while (this.controllers.has(runId))
-                await new Promise((resolve) => setTimeout(resolve, 20));
+                await new Promise((resolve) => setTimeout(resolve, shutdownPollIntervalMs));
             return;
         }
         if (run.outcome === "queued") {
-            await DBOS.cancelWorkflow(runId);
+            await DBOS.cancelWorkflow(run.executions?.at(-1)?.id ?? runId);
             await this.store.patchRun(runId, { outcome: "cancelled" });
             return;
         }
@@ -347,6 +439,51 @@ export class Runner {
             },
         });
     }
+    async recover(runId, commandId) {
+        return this.store.admitRecovery(runId, {
+            commandId,
+            checkSafety: async (run) => {
+                if (!this.ownsRuntime || this.stopping)
+                    throw new Error("Recovery requires an active runner");
+                if (this.options.workflow)
+                    throw new Error("Publication recovery currently supports the default workflow only");
+                if (this.controllers.has(runId))
+                    throw new Error("Work has not stopped");
+                const project = this.config.projects.find((item) => item.id === run.projectId);
+                if (!project)
+                    throw new Error("Project removed from configuration");
+                const execution = run.executions.at(-1);
+                const status = await DBOS.getWorkflowStatus(execution.id);
+                if (!status || !["SUCCESS", "ERROR"].includes(status.status))
+                    throw new Error("Source execution has not finished");
+                if (status.applicationVersion !==
+                    `${this.config.id}-${this.options.workflowVersion ?? "phase1-v2"}`)
+                    throw new Error("Workflow version changed; use retry");
+                const steps = await DBOS.listWorkflowSteps(execution.id);
+                const failed = steps?.find((step) => step.functionID === execution.failedStep);
+                if (!failed?.error || failed.name !== run.phase)
+                    throw new Error("Failed publication checkpoint is unavailable");
+                const prefix = steps.filter((step) => step.functionID < failed.functionID);
+                if (prefix.length !== failed.functionID ||
+                    prefix.some((step, index) => step.error || step.functionID !== index) ||
+                    !prefix.some((step) => step.name === "commit"))
+                    throw new Error("Completed publication checkpoints are unavailable");
+                await this.checkRecoveryState(run, project);
+                return prefix.map((step) => step.name);
+            },
+        });
+    }
+    async checkRecoveryState(run, project, signal) {
+        await verifyPublicationRecovery(run, {
+            project,
+            signal,
+            store: this.store,
+            workspace: this.options.workspace ?? new ExistingCheckout(),
+            hosting: this.hosting.get(project.id),
+            stateDirectory: this.config.stateDirectory,
+            workflowVersion: this.options.workflowVersion ?? "phase1-v2",
+        });
+    }
     async shutdown() {
         this.stopping = true;
         if (this.timer)
@@ -354,7 +491,7 @@ export class Runner {
         for (const controller of this.controllers.values())
             controller.abort();
         while (this.controllers.size || this.tickBusy)
-            await new Promise((resolve) => setTimeout(resolve, 20));
+            await new Promise((resolve) => setTimeout(resolve, shutdownPollIntervalMs));
         await Promise.all(this.active.values());
         await Promise.allSettled(this.polling.values());
         if (this.ownsRuntime) {
@@ -368,3 +505,18 @@ export class Runner {
         await this.store.close();
     }
 }
+function canonicalDirectory(path, label) {
+    const resolved = resolve(path);
+    let canonical;
+    try {
+        canonical = realpathSync(resolved);
+    }
+    catch (error) {
+        throw new Error(`${label} is not an existing directory: ${resolved}`, {
+            cause: error,
+        });
+    }
+    if (!statSync(canonical).isDirectory())
+        throw new Error(`${label} is not an existing directory: ${resolved}`);
+    return canonical;
+}

package/dist/src/runtime/process.d.ts

@@ -1,3 +1,4 @@
+export declare const maxCapturedOutputBytes: number;
 export interface CommandOptions {
     cwd: string;
     processFile?: string;
@@ -7,6 +8,7 @@ export interface CommandOptions {
     env?: NodeJS.ProcessEnv;
     allowFailure?: boolean;
     captureOutput?: boolean;
+    strictUtf8?: boolean;
     onOutput?: (chunk: string) => void;
 }
 export interface CommandResult {

package/dist/src/runtime/process.js

@@ -1,5 +1,6 @@
 import { spawn } from "node:child_process";
 import { unlinkSync, writeFileSync } from "node:fs";
+export const maxCapturedOutputBytes = 32 * 1024 * 1024;
 /** Resolves only after the child closes. Cancellation terminates its process group. */
 export function command(executable, args, options) {
     options.signal?.throwIfAborted();
@@ -23,10 +24,14 @@ export function command(executable, args, options) {
             }
             catch (error) {
                 if (error.code !== "ESRCH")
-                    failure = error;
+                    failure = failure
+                        ? new AggregateError([failure, error], `${String(failure)}; process group termination failed: ${String(error)}`)
+                        : error;
             }
         };
         const stop = () => {
+            if (cancelled)
+                return;
             cancelled = true;
             kill("SIGTERM");
             killTimer ??= setTimeout(() => kill("SIGKILL"), options.killGraceMs ?? 2000);
@@ -43,27 +48,51 @@ export function command(executable, args, options) {
         }
         const timeout = setTimeout(stop, options.timeoutMs ?? 300_000);
         options.signal?.addEventListener("abort", stop, { once: true });
-        const collect = (target, chunk) => {
-            const value = chunk.toString();
+        const decoders = {
+            stdout: new TextDecoder("utf-8", {
+                fatal: options.strictUtf8,
+                ignoreBOM: true,
+            }),
+            stderr: new TextDecoder("utf-8", {
+                fatal: options.strictUtf8,
+                ignoreBOM: true,
+            }),
+        };
+        let capturedBytes = 0;
+        const decodeOutput = (target, chunk) => {
             try {
-                options.onOutput?.(value);
+                const value = decoders[target].decode(chunk, {
+                    stream: chunk !== undefined,
+                });
+                if (value)
+                    options.onOutput?.(value);
+                if (options.captureOutput !== false) {
+                    if (target === "stdout")
+                        stdout += value;
+                    else
+                        stderr += value;
+                }
             }
             catch (error) {
-                failure = error;
+                failure ??= error;
                 stop();
             }
-            if (options.captureOutput !== false &&
-                stdout.length + stderr.length <= 32 * 1024 * 1024) {
-                if (target === "stdout")
-                    stdout += value;
-                else
-                    stderr += value;
-                if (stdout.length + stderr.length > 32 * 1024 * 1024)
+        };
+        const collect = (target, chunk) => {
+            if (options.captureOutput !== false) {
+                capturedBytes += chunk.length;
+                if (capturedBytes > maxCapturedOutputBytes) {
+                    failure ??= new Error(`Command output size ${capturedBytes} bytes exceeds capture limit ${maxCapturedOutputBytes} bytes`);
                     stop();
+                    return;
+                }
             }
+            decodeOutput(target, chunk);
         };
         child.stdout.on("data", (chunk) => collect("stdout", chunk));
         child.stderr.on("data", (chunk) => collect("stderr", chunk));
+        child.stdout.on("end", () => decodeOutput("stdout"));
+        child.stderr.on("end", () => decodeOutput("stderr"));
         const cleanup = () => {
             clearTimeout(timeout);
             if (killTimer)

package/dist/src/store.d.ts

@@ -25,7 +25,12 @@ export interface InvocationRecord {
     requested: unknown;
     effective: unknown;
     prompt: string;
-    skills: unknown;
+    /** Historical records only. New stages use runtime-managed skills. */
+    skills?: unknown;
+    taskPrompt?: import("./prompts.js").ResolvedPrompt;
+    outputContract?: string;
+    evidence?: import("./evidence.js").ChangeEvidence;
+    validationError?: string;
     outcome: string;
     startedAt: string;
     finishedAt?: string;
@@ -38,6 +43,10 @@ interface RetryAdmission {
         branchTemplate: string;
     }>;
 }
+interface RecoveryAdmission {
+    commandId?: string;
+    checkSafety: (run: RunRecord) => Promise<string[]>;
+}
 /** Public persisted query surface. All queries work without a running executor. */
 export declare class Store {
     readonly scope: string;
@@ -58,11 +67,21 @@ export declare class Store {
         blocked?: string | null;
     }): Promise<void>;
     insertRun(run: RunRecord): Promise<boolean>;
+    blockProject(id: string, reason: string): Promise<void>;
     /**
      * Admit a retry and its events atomically. Safety checks run under the project
      * lock only for new admissions; they must not write through this Store.
      */
     admitRetry(runId: string, admission: RetryAdmission): Promise<string>;
+    /** Persist recovery intent before dispatch; the command ID is its durable DBOS ID. */
+    admitRecovery(runId: string, admission: RecoveryAdmission): Promise<string>;
+    recoveryPlan(runId: string): Promise<{
+        eligible: boolean;
+        reason: string | null;
+        fromStep: string;
+        reuses: string;
+        checks: string;
+    }>;
     run(id: string): Promise<RunRecord>;
     runs(): Promise<RunRecord[]>;
     patchRun(id: string, patch: Partial<RunRecord>): Promise<RunRecord>;
@@ -74,7 +93,7 @@ export declare class Store {
         after?: number;
         intervalMs?: number;
     }): () => void;
-    request(kind: "pause" | "resume" | "stop" | "retry", target: string): Promise<string>;
+    request(kind: "pause" | "resume" | "stop" | "retry" | "recover", target: string): Promise<string>;
     commands(): Promise<Array<{
         id: string;
         kind: string;

package/dist/src/store.js

@@ -1,10 +1,11 @@
 import { randomUUID } from "node:crypto";
-import { and, eq, gt, Param, SQL } from "drizzle-orm";
+import { and, eq, gt, isNull, Param, SQL } from "drizzle-orm";
 import { drizzle } from "drizzle-orm/node-postgres";
 import { Pool } from "pg";
 import { tryLock, unlockAll } from "./db/locks.js";
 import { migrateDatabase } from "./db/migrations.js";
 import * as tables from "./db/schema.js";
+import { recoveryUnavailable } from "./recovery.js";
 import { createQueuedRun } from "./run-record.js";
 import { redactValue } from "./runtime/redaction.js";
 /** Public persisted query surface. All queries work without a running executor. */
@@ -113,6 +114,16 @@ export class Store {
             await this.emit(run.id, "run", run);
         return inserted.length > 0;
     }
+    async blockProject(id, reason) {
+        const { projects } = tables;
+        const updated = await this.db
+            .update(projects)
+            .set({ blocked: this.redact(reason) })
+            .where(and(eq(projects.scope, this.scope), eq(projects.id, id), isNull(projects.blocked)))
+            .returning({ id: projects.id });
+        if (updated.length)
+            await this.emit(null, "project", { id, blocked: reason });
+    }
     /**
      * Admit a retry and its events atomically. Safety checks run under the project
      * lock only for new admissions; they must not write through this Store.
@@ -192,6 +203,104 @@ export class Store {
             return id;
         });
     }
+    /** Persist recovery intent before dispatch; the command ID is its durable DBOS ID. */
+    async admitRecovery(runId, admission) {
+        const original = await this.run(runId);
+        const { projects, runs, events } = tables;
+        const projectPredicate = and(eq(projects.scope, this.scope), eq(projects.id, original.projectId));
+        return this.db.transaction(async (tx) => {
+            const [project] = await tx
+                .select()
+                .from(projects)
+                .where(projectPredicate)
+                .for("update");
+            if (!project)
+                throw new Error(`Unknown project: ${original.projectId}`);
+            const history = await tx
+                .select({ record: runs.record })
+                .from(runs)
+                .where(and(eq(runs.scope, this.scope), eq(runs.taskKey, original.taskKey)))
+                .orderBy(runs.id)
+                .for("update");
+            const previous = history.find(({ record }) => record.id === runId)?.record;
+            if (!previous)
+                throw new Error(`Unknown run: ${runId}`);
+            if (admission.commandId) {
+                const records = await tx
+                    .select({ record: runs.record })
+                    .from(runs)
+                    .where(eq(runs.scope, this.scope));
+                const owner = records.find(({ record }) => record.id === admission.commandId ||
+                    record.executions?.some((item) => item.id === admission.commandId))?.record;
+                if (owner) {
+                    if (owner.id !== runId ||
+                        !owner.executions?.some((item) => item.id === admission.commandId && item.recoveryOf))
+                        throw new Error("Recovery command identity belongs to a different execution");
+                    return admission.commandId;
+                }
+            }
+            const unavailable = recoveryUnavailable(previous);
+            if (unavailable)
+                throw new Error(unavailable);
+            if (history.some(({ record }) => record.attempt > previous.attempt ||
+                (record.id !== runId &&
+                    ["queued", "running"].includes(record.outcome))))
+                throw new Error("A newer attempt has superseded this run");
+            // Recovery must never remove a block imposed by a different operation.
+            if (project.blocked)
+                throw new Error(project.blocked);
+            const reusedSteps = await admission.checkSafety(previous);
+            const source = previous.executions.at(-1);
+            const id = admission.commandId ?? randomUUID();
+            const now = new Date().toISOString();
+            const execution = {
+                id,
+                recoveryOf: source.id,
+                startStep: source.failedStep,
+                reusedSteps,
+                fingerprint: source.fingerprint,
+                createdAt: now,
+                outcome: "queued",
+                phase: previous.phase,
+                recoverySupported: source.recoverySupported,
+            };
+            const recovered = {
+                ...previous,
+                outcome: "queued",
+                updatedAt: now,
+                executions: [...previous.executions, execution],
+            };
+            delete recovered.error;
+            delete recovered.failedStep;
+            const persisted = redactValue(recovered, this.redact);
+            await tx
+                .update(runs)
+                .set({ record: persisted })
+                .where(and(eq(runs.scope, this.scope), eq(runs.id, runId)));
+            await tx.insert(events).values({
+                scope: this.scope,
+                runId,
+                kind: "recovery",
+                payload: redactValue(execution, this.redact),
+            });
+            return id;
+        });
+    }
+    async recoveryPlan(runId) {
+        const run = await this.run(runId);
+        const reason = recoveryUnavailable(run) ??
+            ((await this.runs()).some((item) => item.taskKey === run.taskKey && item.attempt > run.attempt)
+                ? "A newer attempt has superseded this run"
+                : undefined) ??
+            (await this.project(run.projectId)).blocked;
+        return {
+            eligible: !reason,
+            reason: reason ?? null,
+            fromStep: run.phase,
+            reuses: "Completed steps before the failed publication step, including implementation, validation and commit",
+            checks: "Runner verifies checkpoints, configuration, artifacts and checkout before recovery",
+        };
+    }
     async run(id) {
         const { runs } = tables;
         const [row] = await this.db
@@ -232,6 +341,18 @@ export class Store {
             // Match JSON serialization: undefined patch fields leave stored fields intact.
             const persistedChange = JSON.parse(JSON.stringify(redactValue(change, this.redact)));
             const merged = { ...row.record, ...persistedChange };
+            const execution = merged.executions?.at(-1);
+            if (execution) {
+                execution.outcome = merged.outcome;
+                if (merged.outcome === "running" && !execution.startedAt)
+                    execution.startedAt = change.updatedAt;
+                execution.phase = merged.phase;
+                execution.error = merged.error;
+                execution.failedStep = merged.failedStep;
+                if (!execution.finishedAt &&
+                    !["queued", "running"].includes(merged.outcome))
+                    execution.finishedAt = change.updatedAt;
+            }
             await tx.update(runs).set({ record: merged }).where(predicate);
             return merged;
         });

package/dist/src/tui/actions.d.ts

@@ -0,0 +1,16 @@
+import type { RunRecord } from "../domain.js";
+import type { ProjectState } from "../store.js";
+/** Display eligibility only; the runner still validates command admission. */
+export declare function actionAvailability({ run, project, projectRuns, pending, }: {
+    run?: RunRecord;
+    project?: ProjectState;
+    projectRuns: RunRecord[];
+    pending: boolean;
+}): {
+    recoveryReason: string | undefined;
+    available: {
+        stop: boolean;
+        retry: boolean;
+        recover: boolean;
+    };
+};