akm-cli 0.9.0-beta.9 → 0.9.0-rc.1

package/dist/workflows/runtime/runs.js

@@ -2,25 +2,89 @@
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 import { randomUUID } from "node:crypto";
-import fs from "node:fs";
 import { parseAssetRef } from "../../core/asset/asset-ref.js";
-import { loadConfig } from "../../core/config/config.js";
+import { canonicalizeWorkflowName } from "../../core/asset/asset-spec.js";
+import { getDefaultLlmConfig, loadConfig } from "../../core/config/config.js";
 import { NotFoundError, UsageError } from "../../core/errors.js";
 import { appendEvent } from "../../core/events.js";
-import { getDbPath } from "../../core/paths.js";
-import { closeDatabase, openExistingDatabase } from "../../indexer/db/db.js";
-import { resolveSourceEntries } from "../../indexer/search/search-source.js";
-import { resolveSourcesForOrigin } from "../../registry/origin-resolve.js";
-import { resolveAssetPath } from "../../sources/resolve.js";
+import { warn } from "../../core/warn.js";
 import { withWorkflowRunsRepo, } from "../../storage/repositories/workflow-runs-repository.js";
-import { formatWorkflowErrors } from "../authoring/authoring.js";
 import { getCurrentWorkflowScopeKey } from "../authoring/scope-key.js";
-import { parseWorkflow } from "../parser.js";
+import { detectSecretShapedParams } from "../exec/param-secrets.js";
+import { collectProgramWarnings } from "../ir/compile.js";
+import { validateWorkflowParams } from "../ir/params.js";
+import { canonicalPlanJson, computePlanHash } from "../ir/plan-hash.js";
 import { validateStepSummary } from "../validate-summary.js";
 import { resolveAgentIdentity } from "./agent-identity.js";
 import { evaluateCheckin } from "./checkin.js";
+import { evaluateStaleUnits } from "./unit-checkin.js";
+import { compileWorkflowAssetPlan, loadWorkflowAsset, resolveWorkflowEntryId } from "./workflow-asset-loader.js";
+/** Clip bound for a unit's `result_json` on the `--units` diagnostic surface. */
+const UNIT_DIAGNOSTIC_CLIP = 2000;
+function toUnitDiagnostic(row, stale) {
+    let diagnostic = null;
+    if (row.result_json !== null) {
+        // `result_json` is a JSON-encoded value: a bare JSON string for a free-text
+        // unit, an object/array for a schema unit. Render the decoded string as-is
+        // (no surrounding quotes) and other shapes as compact JSON, then clip so a
+        // large artifact can't flood the diagnostic surface.
+        let text = row.result_json;
+        try {
+            const parsed = JSON.parse(row.result_json);
+            text = typeof parsed === "string" ? parsed : JSON.stringify(parsed);
+        }
+        catch {
+            /* leave the raw journaled text */
+        }
+        diagnostic = text.length > UNIT_DIAGNOSTIC_CLIP ? `${text.slice(0, UNIT_DIAGNOSTIC_CLIP)}…` : text;
+    }
+    return {
+        unitId: row.unit_id,
+        nodeId: row.node_id,
+        stepId: row.step_id,
+        phase: row.phase,
+        status: row.status,
+        attempts: row.attempts,
+        tokens: row.tokens,
+        failureReason: row.failure_reason,
+        sessionId: row.session_id,
+        diagnostic,
+        startedAt: row.started_at,
+        finishedAt: row.finished_at,
+        stale: stale !== undefined,
+        staleIdleMs: stale ? (Number.isFinite(stale.idleMs) ? stale.idleMs : null) : null,
+        claimHolder: row.claim_holder,
+        claimExpiresAt: row.claim_expires_at,
+    };
+}
 export async function startWorkflowRun(ref, params = {}, options) {
     const asset = await loadWorkflowAsset(ref);
+    // Frozen plan (redesign addendum, R1): compile the plan ONCE at start and
+    // persist it on the run row in the same transaction as the insert. Every
+    // later invocation executes this snapshot — the asset file is never re-read
+    // for an in-flight run; re-planning is an explicit new run.
+    const plan = compileWorkflowAssetPlan(asset);
+    // Non-fatal WARNINGS (redesign addendum): a YAML program's untyped-step and
+    // undeclared-param advisories surface as `warn()` lines at start (stderr,
+    // consistent with the repo's other author-facing warnings) without blocking
+    // the run. Markdown workflows carry no `program` and warn about nothing.
+    if (asset.program) {
+        for (const w of collectProgramWarnings(asset.program)) {
+            warn(`workflow start: ${asset.path}:${w.line} — ${w.message}`);
+        }
+    }
+    // Reviewer #12: validate supplied `--params` against the frozen param
+    // schemas BEFORE creating the run, so a type-mismatched param (e.g. a string
+    // for a `{ type: array }` param) is rejected with actionable errors instead
+    // of flowing silently into a unit prompt. Programs without declared param
+    // schemas (and every Markdown workflow) validate trivially.
+    const paramErrors = validateWorkflowParams(plan, params);
+    if (paramErrors.length > 0) {
+        throw new UsageError(`Cannot start ${asset.ref}: the supplied --params do not satisfy the workflow's declared parameter schemas:\n` +
+            paramErrors.map((e) => `  - ${e}`).join("\n"), "INVALID_JSON_ARGUMENT");
+    }
+    const planJson = canonicalPlanJson(plan);
+    const planHash = computePlanHash(plan);
     return withWorkflowRunsRepo(async (repo) => {
         const now = new Date().toISOString();
         const runId = randomUUID();
@@ -72,21 +136,49 @@ export async function startWorkflowRun(ref, params = {}, options) {
                 completionJson: step.completionCriteria ? JSON.stringify(step.completionCriteria) : null,
                 sequenceIndex: step.sequenceIndex ?? 0,
             })));
+            // Same transaction as the insert: a run row never exists without its
+            // frozen plan (rows with NULL plan_json are pre-006 legacy runs).
+            repo.setRunPlan(runId, planJson, planHash);
         });
         const result = await getWorkflowStatus(runId);
+        // #13: params are declared non-secret (they are copied verbatim into every
+        // unit prompt and hashed into the unit identity, so they cannot be redacted
+        // without breaking the driver protocol). Surface a loud, best-effort warning
+        // when a param LOOKS like a credential so the author moves it to an env
+        // binding. Advisory only — never blocks the start.
+        const secretWarnings = detectSecretShapedParams(params);
+        if (secretWarnings.length > 0)
+            result.warnings = [...(result.warnings ?? []), ...secretWarnings];
+        // 07 P1-B: emit only the run id + status — NOT the raw workflowTitle (which
+        // comes verbatim from the workflow asset's frontmatter and is therefore
+        // attacker-influenceable). Keeping raw titles out of the events stream
+        // shrinks the injectable footprint for any consumer that re-surfaces events
+        // into agent context.
         appendEvent({
             eventType: "workflow_started",
             ref: ref,
-            metadata: { runId: result.run.id, title: result.run.workflowTitle },
+            metadata: { runId: result.run.id, status: result.run.status },
         });
         return result;
     });
 }
-export async function getWorkflowStatus(runId) {
+export async function getWorkflowStatus(runId, opts) {
     return withWorkflowRunsRepo((repo) => {
         const run = readWorkflowRun(repo, runId);
         const steps = readWorkflowRunSteps(repo, run.id);
-        return buildWorkflowRunDetail(run, steps);
+        const detail = buildWorkflowRunDetail(run, steps);
+        if (opts?.includeUnits) {
+            // The honest diagnostic surface (#22): read the unit journal straight and
+            // project each row, INCLUDING failures whose diagnostic text the
+            // deterministic evidence graph drops. Read-only; never mutates the run.
+            const rows = repo.getUnitsForRun(run.id);
+            // Codex round-3 finding B: run the SAME pure stale-claim evaluator `brief`
+            // uses (`now` injected for deterministic tests) so a dead driver's claimed
+            // `running` unit surfaces as stale here too, not just as raw `running`.
+            const staleById = new Map(evaluateStaleUnits(rows, opts.now ?? Date.now()).map((u) => [u.unitId, u]));
+            detail.units = rows.map((row) => toUnitDiagnostic(row, staleById.get(row.unit_id)));
+        }
+        return detail;
     });
 }
 export async function hasWorkflowRun(runId) {
@@ -101,7 +193,7 @@ export async function listWorkflowRuns(input) {
             if (parsed.type !== "workflow") {
                 throw new UsageError(`Expected a workflow ref (workflow:<name>), got "${input.workflowRef}".`);
             }
-            workflowRef = `${parsed.origin ? `${parsed.origin}//` : ""}workflow:${parsed.name}`;
+            workflowRef = `${parsed.origin ? `${parsed.origin}//` : ""}workflow:${canonicalizeWorkflowName(parsed.name)}`;
         }
         const rows = repo.listRuns({
             scopeKey,
@@ -115,31 +207,58 @@ export async function getNextWorkflowStep(specifier, params) {
     return withWorkflowRunsRepo(async (repo) => {
         const { run, autoStarted } = await resolveRunSpecifier(repo, specifier, params);
         const steps = readWorkflowRunSteps(repo, run.id);
-        const currentStep = resolveCurrentStep(run, steps);
-        const done = run.status === "completed" ? true : undefined;
-        // #506: surface a check-in directive through the normal command output when
-        // the run looks stalled. Pure timestamp evaluation — no background thread.
-        const checkin = evaluateCheckin({
-            status: run.status,
-            updatedAt: run.updated_at,
-            checkinArmedAt: run.checkin_armed_at,
-            agentHarness: run.agent_harness,
-            agentSessionId: run.agent_session_id,
-        }) ?? undefined;
-        return {
-            run: toWorkflowRunSummary(run),
-            workflow: {
-                ref: run.workflow_ref,
-                title: run.workflow_title,
-                steps: steps.map(toWorkflowRunStepState),
-            },
-            step: currentStep ? toWorkflowRunStepState(currentStep) : null,
-            ...(done ? { done } : {}),
-            ...(autoStarted ? { autoStarted } : {}),
-            ...(checkin ? { checkin } : {}),
-        };
+        return { ...projectNextResult(run, steps), ...(autoStarted ? { autoStarted: true } : {}) };
     });
 }
+/**
+ * Project a run row + its step rows into a {@link WorkflowNextResult}. The pure
+ * read-shaping half of {@link getNextWorkflowStep}, extracted so the driver
+ * snapshot below reproduces the exact same projection without re-running the
+ * auto-start-capable {@link resolveRunSpecifier}.
+ */
+function projectNextResult(run, steps) {
+    const currentStep = resolveCurrentStep(run, steps);
+    const done = run.status === "completed" ? true : undefined;
+    // #506: surface a check-in directive through the normal command output when
+    // the run looks stalled. Pure timestamp evaluation — no background thread.
+    const checkin = evaluateCheckin({
+        status: run.status,
+        updatedAt: run.updated_at,
+        checkinArmedAt: run.checkin_armed_at,
+        agentHarness: run.agent_harness,
+        agentSessionId: run.agent_session_id,
+    }) ?? undefined;
+    return {
+        run: toWorkflowRunSummary(run),
+        workflow: {
+            ref: run.workflow_ref,
+            title: run.workflow_title,
+            steps: steps.map(toWorkflowRunStepState),
+        },
+        step: currentStep ? toWorkflowRunStepState(currentStep) : null,
+        ...(done ? { done } : {}),
+        ...(checkin ? { checkin } : {}),
+    };
+}
+/**
+ * A consistent point-in-time snapshot of a run for the harness-neutral driver
+ * protocol (PR #714 review round 2, #14). `brief`/`report` previously read the
+ * spine (`getNextWorkflowStep`) and then, in a SEPARATE connection, the run row
+ * + unit journal — so a concurrent `report`/`run`/manual completion could change
+ * the active step BETWEEN the two reads, leaving the described work-list
+ * inconsistent with the run row it was stamped against. This reads the run row,
+ * its steps, AND its unit rows inside ONE transaction (one connection, one
+ * snapshot) so all three agree. It never auto-starts — `runId` must already
+ * resolve to a concrete run — because the driver protocol never mutates on read.
+ */
+export async function snapshotRunForDriver(runId) {
+    return withWorkflowRunsRepo((repo) => repo.transaction(() => {
+        const run = readWorkflowRun(repo, runId);
+        const steps = readWorkflowRunSteps(repo, run.id);
+        const units = repo.getUnitsForRun(run.id);
+        return { next: projectNextResult(run, steps), run, units };
+    }));
+}
 export async function resumeWorkflowRun(runId) {
     return withWorkflowRunsRepo((repo) => {
         const run = readWorkflowRun(repo, runId);
@@ -164,6 +283,42 @@ export async function resumeWorkflowRun(runId) {
         return buildWorkflowRunDetail(updated, steps);
     });
 }
+/**
+ * Give up on a run (08-F6): flip it to `failed` so it stops counting as
+ * active — the run-level verb the concurrency-guard message in
+ * {@link startWorkflowRun} advertises. Terminal-state runs are refused;
+ * {@link resumeWorkflowRun} can reopen an abandoned run if it was a mistake.
+ */
+export async function abandonWorkflowRun(runId) {
+    return withWorkflowRunsRepo((repo) => {
+        const run = readWorkflowRun(repo, runId);
+        if (run.status === "completed" || run.status === "failed") {
+            throw new UsageError(`Workflow run ${run.id} is already ${run.status}.`);
+        }
+        const now = new Date().toISOString();
+        repo.updateRunState({
+            status: "failed",
+            currentStepId: run.current_step_id,
+            updatedAt: now,
+            completedAt: now,
+            checkinArmedAt: now,
+            runId: run.id,
+        });
+        const updated = {
+            ...run,
+            status: "failed",
+            updated_at: now,
+            completed_at: now,
+            checkin_armed_at: now,
+        };
+        const steps = readWorkflowRunSteps(repo, run.id);
+        const detail = buildWorkflowRunDetail(updated, steps);
+        // Same injectable-footprint rule as workflow_started (07 P1-B): ids and
+        // status only, never the frontmatter-derived title.
+        appendEvent({ eventType: "workflow_abandoned", ref: run.workflow_ref, metadata: { runId: run.id } });
+        return detail;
+    });
+}
 export async function completeWorkflowStep(input) {
     // Read the step (read-only) up front so the LLM validation gate runs OUTSIDE
     // the write transaction — a slow/hung LLM must never hold a db write lock.
@@ -172,6 +327,7 @@ export async function completeWorkflowStep(input) {
         if (run.status !== "active") {
             throw new UsageError(`Workflow run ${run.id} is ${run.status} and cannot be updated.`);
         }
+        assertLeaseAllowsSpineAdvance(run, input.leaseHolder);
         const existing = repo.getStep(run.id, input.stepId);
         if (!existing) {
             throw new NotFoundError(`Step "${input.stepId}" was not found in workflow run ${run.id}.`);
@@ -195,7 +351,7 @@ export async function completeWorkflowStep(input) {
     if (input.status === "completed" && summary) {
         const criteria = parseJsonArray(preflight.existing.completion_json) ?? [];
         const judge = input.summaryJudge === undefined ? buildDefaultSummaryJudge() : input.summaryJudge;
-        const verdict = await validateStepSummary({ stepTitle: preflight.existing.step_title, completionCriteria: criteria, summary }, judge ?? undefined);
+        const verdict = await validateStepSummary({ stepTitle: preflight.existing.step_title, completionCriteria: criteria, summary }, judge ?? undefined, { required: input.requireGate === true });
         if (!verdict.complete) {
             // Re-arm the check-in so a subsequent stall is still nudged, but leave the
             // step pending and return corrective feedback instead of completing.
@@ -208,6 +364,9 @@ export async function completeWorkflowStep(input) {
                 stepId: input.stepId,
                 missing: verdict.missing,
                 feedback: verdict.feedback ?? "The summary does not satisfy the step's completion criteria.",
+                // A REQUIRED gate that could not be judged (finding A): the caller BLOCKS
+                // rather than treating this as a normal, retryable gate rejection.
+                ...(verdict.errored ? { errored: true } : {}),
             };
         }
     }
@@ -219,6 +378,10 @@ export async function completeWorkflowStep(input) {
             if (run.status !== "active") {
                 throw new UsageError(`Workflow run ${run.id} is ${run.status} and cannot be updated.`);
             }
+            // Re-checked inside the write transaction (like every other preflight
+            // condition): an engine may have claimed the run while the summary gate
+            // above was awaiting its LLM judge.
+            assertLeaseAllowsSpineAdvance(run, input.leaseHolder);
             const existing = repo.getStep(run.id, input.stepId);
             if (!existing) {
                 throw new NotFoundError(`Step "${input.stepId}" was not found in workflow run ${run.id}.`);
@@ -261,10 +424,16 @@ export async function completeWorkflowStep(input) {
             };
         });
         const detail = buildWorkflowRunDetail(updatedRun, refreshedSteps);
+        // #11: emit `workflow_step_completed` ONLY for a genuine `completed`
+        // transition; every other non-pending status (failed/skipped/blocked)
+        // carries the honest `workflow_step_updated` name. The status is ALWAYS
+        // in metadata so consumers never infer it from the event name. Raw `notes`
+        // are workflow/model-authored content — an event-stream prompt-injection
+        // surface — and never enter the events log; they live on the step row only.
         appendEvent({
-            eventType: "workflow_step_completed",
+            eventType: input.status === "completed" ? "workflow_step_completed" : "workflow_step_updated",
             ref: detail.run.workflowRef,
-            metadata: { runId: input.runId, stepId: input.stepId, notes: input.notes },
+            metadata: { runId: input.runId, stepId: input.stepId, status: input.status },
         });
         if (detail.run.status === "completed") {
             appendEvent({ eventType: "workflow_finished", ref: detail.run.workflowRef, metadata: { runId: input.runId } });
@@ -287,7 +456,7 @@ async function resolveRunSpecifier(repo, specifier, params) {
     if (parsed.type !== "workflow") {
         throw new UsageError(`Expected a workflow ref or workflow run id, got "${specifier}".`);
     }
-    const ref = `${parsed.origin ? `${parsed.origin}//` : ""}workflow:${parsed.name}`;
+    const ref = `${parsed.origin ? `${parsed.origin}//` : ""}workflow:${canonicalizeWorkflowName(parsed.name)}`;
     const scopeKey = getCurrentWorkflowScopeKey();
     const active = repo.getActiveRunRowForScope(ref, scopeKey);
     if (active) {
@@ -299,115 +468,6 @@ async function resolveRunSpecifier(repo, specifier, params) {
     const started = await startWorkflowRun(ref, params ?? {});
     return { run: readWorkflowRun(repo, started.run.id), autoStarted: true };
 }
-async function loadWorkflowAsset(ref) {
-    const parsed = parseAssetRef(ref);
-    if (parsed.type !== "workflow") {
-        throw new UsageError(`Expected a workflow ref (workflow:<name>), got "${ref}".`);
-    }
-    const config = loadConfig();
-    const allSources = resolveSourceEntries(undefined, config);
-    const searchSources = resolveSourcesForOrigin(parsed.origin, allSources);
-    let assetPath;
-    let sourcePath;
-    for (const source of searchSources) {
-        try {
-            assetPath = await resolveAssetPath(source.path, "workflow", parsed.name);
-            sourcePath = source.path;
-            break;
-        }
-        catch {
-            /* continue */
-        }
-    }
-    if (!assetPath) {
-        throw new NotFoundError(`Workflow not found for ref: workflow:${parsed.name}`);
-    }
-    const resolvedSourcePath = sourcePath ?? config.stashDir ?? assetPath;
-    const fullRef = `${parsed.origin ? `${parsed.origin}//` : ""}workflow:${parsed.name}`;
-    const cached = readWorkflowDocumentFromIndex(resolvedSourcePath, fullRef);
-    const document = cached ?? loadWorkflowDocumentFromDisk(assetPath);
-    return projectAsset(document, fullRef, assetPath, resolvedSourcePath);
-}
-function loadWorkflowDocumentFromDisk(assetPath) {
-    const content = fs.readFileSync(assetPath, "utf8");
-    const result = parseWorkflow(content, { path: assetPath });
-    if (!result.ok) {
-        throw new UsageError(formatWorkflowErrors(assetPath, result.errors));
-    }
-    return result.document;
-}
-function readWorkflowDocumentFromIndex(sourcePath, ref) {
-    const dbPath = getDbPath();
-    if (!fs.existsSync(dbPath))
-        return null;
-    const db = openExistingDatabase(dbPath);
-    try {
-        const parsed = parseAssetRef(ref);
-        const entryKey = `${sourcePath}:${parsed.type}:${parsed.name}`;
-        const row = db
-            .prepare(`SELECT wd.document_json AS document_json
-           FROM workflow_documents wd
-           JOIN entries e ON e.id = wd.entry_id
-          WHERE e.entry_type = 'workflow' AND e.entry_key = ?
-          LIMIT 1`)
-            .get(entryKey);
-        if (!row)
-            return null;
-        try {
-            return JSON.parse(row.document_json);
-        }
-        catch {
-            return null;
-        }
-    }
-    finally {
-        closeDatabase(db);
-    }
-}
-function projectAsset(doc, ref, assetPath, sourcePath) {
-    return {
-        ref,
-        path: assetPath,
-        sourcePath,
-        title: doc.title,
-        ...(doc.parameters
-            ? {
-                parameters: doc.parameters.map((p) => ({
-                    name: p.name,
-                    ...(p.description ? { description: p.description } : {}),
-                })),
-            }
-            : {}),
-        steps: doc.steps.map((s) => ({
-            id: s.id,
-            title: s.title,
-            instructions: s.instructions.text,
-            ...(s.completionCriteria ? { completionCriteria: s.completionCriteria.map((c) => c.text) } : {}),
-            sequenceIndex: s.sequenceIndex,
-        })),
-    };
-}
-function resolveWorkflowEntryId(sourcePath, ref) {
-    const dbPath = getDbPath();
-    if (!fs.existsSync(dbPath))
-        return null;
-    const db = openExistingDatabase(dbPath);
-    try {
-        const parsed = parseAssetRef(ref);
-        const entryKey = `${sourcePath}:${parsed.type}:${parsed.name}`;
-        const row = db
-            .prepare(`SELECT id
-         FROM entries
-         WHERE entry_type = 'workflow'
-            AND entry_key = ?
-          LIMIT 1`)
-            .get(entryKey);
-        return row?.id ?? null;
-    }
-    finally {
-        closeDatabase(db);
-    }
-}
 function readWorkflowRun(repo, runId) {
     const run = repo.getRunById(runId);
     if (!run) {
@@ -419,6 +479,16 @@ function readWorkflowRunSteps(repo, runId) {
     return repo.getStepsForRun(runId);
 }
 function buildWorkflowRunDetail(run, steps) {
+    // Review M1: `workflow status` (and every other detail-shaped response) now
+    // evaluates the check-in, not just `workflow next`. Pure timestamp check —
+    // no background thread (see checkin.ts).
+    const checkin = evaluateCheckin({
+        status: run.status,
+        updatedAt: run.updated_at,
+        checkinArmedAt: run.checkin_armed_at,
+        agentHarness: run.agent_harness,
+        agentSessionId: run.agent_session_id,
+    });
     return {
         run: toWorkflowRunSummary(run),
         workflow: {
@@ -426,6 +496,7 @@ function buildWorkflowRunDetail(run, steps) {
             title: run.workflow_title,
             steps: steps.map(toWorkflowRunStepState),
         },
+        ...(checkin ? { checkin } : {}),
     };
 }
 function toWorkflowRunSummary(run) {
@@ -443,8 +514,31 @@ function toWorkflowRunSummary(run) {
         params: parseJsonObject(run.params_json),
         agentHarness: run.agent_harness ?? null,
         agentSessionId: run.agent_session_id ?? null,
+        // Surface the engine lease (holder id + expiry — never workflow-authored
+        // content) so `workflow next`/`status` show who is driving the run.
+        ...(run.engine_lease_holder && run.engine_lease_until
+            ? { engineLease: { holder: run.engine_lease_holder, until: run.engine_lease_until } }
+            : {}),
     };
 }
+/**
+ * Single-driver enforcement (R2 run lease): while a LIVE (unexpired) engine
+ * lease is held, only the holding engine may advance the gate spine. Manual
+ * `akm workflow complete` (no `leaseHolder`) — or a stale engine invocation
+ * whose lease was claimed by another — is refused with the holder + expiry.
+ * An EXPIRED lease never blocks: the engine that held it is presumed dead.
+ */
+function assertLeaseAllowsSpineAdvance(run, leaseHolder) {
+    if (!run.engine_lease_holder || !run.engine_lease_until)
+        return;
+    if (leaseHolder === run.engine_lease_holder)
+        return;
+    if (run.engine_lease_until < new Date().toISOString())
+        return; // expired ⇒ claimable, not live
+    throw new UsageError(`Workflow run ${run.id} is being driven by engine ${run.engine_lease_holder} ` +
+        `(run lease expires ${run.engine_lease_until}). The engine owns the step spine while it runs — ` +
+        `wait for it to finish or for the lease to expire before advancing steps manually.`);
+}
 function toWorkflowRunStepState(step) {
     return {
         id: step.step_id,
@@ -485,17 +579,18 @@ function deriveRunState(steps) {
         .at(-1);
     return { status: "completed", currentStepId: null, completedAt: completedAt ?? null };
 }
-/**
 /**
  * Build the default summary-validation judge from the configured LLM, or return
  * `null` when no LLM is configured (gate is then skipped — fail-open). Lazily
  * imports the client/config so the workflow engine has no hard LLM dependency.
+ *
+ * Exported for the engine loop (`exec/run-workflow.ts`), which wraps the judge
+ * to journal engine-driven gate evaluations as unit rows (addendum R2).
  */
-function buildDefaultSummaryJudge() {
+export function buildDefaultSummaryJudge() {
     let llm;
     try {
         const config = loadConfig();
-        const { getDefaultLlmConfig } = require("../../core/config/config");
         llm = getDefaultLlmConfig(config);
     }
     catch {
@@ -505,7 +600,7 @@ function buildDefaultSummaryJudge() {
         return null;
     const resolved = llm;
     return async ({ system, user }) => {
-        const { chatCompletion } = require("../../llm/client");
+        const { chatCompletion } = await import("../../llm/client.js");
         return chatCompletion(resolved, [
             { role: "system", content: system },
             { role: "user", content: user },

package/dist/workflows/runtime/unit-checkin.js

@@ -0,0 +1,45 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+import { GATE_EVALUATION_PHASE } from "../exec/step-work.js";
+/**
+ * Default staleness window. A unit claimed `running` whose last heartbeat (or,
+ * absent any heartbeat, its first claim) is older than this is surfaced as
+ * stale. Matches the run-level {@link ../runtime/checkin.CHECKIN_STALL_MS}.
+ */
+export const UNIT_STALE_MS = 90_000;
+function parseIso(value) {
+    if (!value)
+        return null;
+    const ms = Date.parse(value);
+    return Number.isNaN(ms) ? null : ms;
+}
+/**
+ * Pure stale-unit evaluator. Returns every `running` DISPATCH unit whose last
+ * heartbeat (`last_checkin_at`, else the first-claim `started_at`) is older than
+ * `staleMs`. Gate-evaluation rows (`phase = "gate"`) are excluded — they are
+ * synchronous engine judge calls, never driver-claimed work. A running row with
+ * no usable timestamp at all is treated as stale (a claim we can no longer age).
+ * Deterministic in `now` — free of timer flakiness.
+ */
+export function evaluateStaleUnits(rows, now = Date.now(), staleMs = UNIT_STALE_MS) {
+    const stale = [];
+    for (const row of rows) {
+        if (row.status !== "running")
+            continue;
+        if (row.phase === GATE_EVALUATION_PHASE)
+            continue;
+        const lastSeenAt = row.last_checkin_at ?? row.started_at;
+        const lastSeen = parseIso(lastSeenAt);
+        const idleMs = lastSeen === null ? Number.POSITIVE_INFINITY : now - lastSeen;
+        if (idleMs < staleMs)
+            continue;
+        stale.push({
+            unitId: row.unit_id,
+            stepId: row.step_id,
+            idleMs,
+            lastSeenAt: lastSeenAt ?? null,
+        });
+    }
+    return stale;
+}