akm-cli 0.9.0-rc.8 → 0.9.0

package/dist/workflows/exec/step-work.js

@@ -3,14 +3,13 @@
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 /**
  * Shared step semantics — the ONE implementation of a step's orchestration
- * decisions, consumed by BOTH the engine loop (`run-workflow.ts` +
- * `native-executor.ts`) and, from R3 on, the harness-neutral driver protocol
- * (`workflow brief` / `workflow report`). The cardinal rule of the driver
- * protocol (redesign addendum R3) is *no duplicated semantics*: work-list
- * computation, prompt assembly, reducer/artifact promotion, output-schema
- * validation, artifact-judged gate summaries, gate-feedback recovery, and
- * route evaluation live here so an engine-driven run and a brief/report-driven
- * run of the same frozen plan produce byte-identical unit graphs.
+ * decisions, consumed by the engine loop (`run-workflow.ts` +
+ * `native-executor.ts`) on both the fresh-execution and the resume/replay path.
+ * The cardinal rule here is *no duplicated semantics*: work-list computation,
+ * prompt assembly, reducer/artifact promotion, output-schema validation,
+ * artifact-judged gate summaries, gate-feedback recovery, and route evaluation
+ * live here so a first run and a resumed run of the same frozen plan produce
+ * byte-identical unit graphs.
  *
  * ## What is PURE here
  *
@@ -19,8 +18,9 @@
  * recovered feedback) — is a pure function: same inputs ⇒ same unit ids, input
  * hashes, and fully-resolved prompts. It takes NO clock, NO IO, and NO journal
  * (journal-derived state, i.e. the recovered gate feedback, is passed in). This
- * is the load-bearing guarantee that `brief` can predict exactly the units the
- * engine would dispatch. So are the reducer/artifact helpers
+ * is the load-bearing guarantee that a resumed run recomputes exactly the units
+ * the original run dispatched, so journaled rows can be reused instead of
+ * re-executed. So are the reducer/artifact helpers
  * ({@link buildEvidence}, {@link projectStepOutput}, {@link validateStepArtifact},
  * {@link buildArtifactSummary}), the gate-feedback recovery
  * ({@link recoverGateFeedback} / {@link activeGateLoop}), and route evaluation
@@ -31,8 +31,8 @@
  * The gate-evaluation journaling ({@link journalGateEvaluationStart} /
  * {@link journalGateEvaluationFinish}) writes `workflow_run_units` rows through
  * the serialized writer queue — an engine-driven judge call is an LLM call and
- * is journaled like a unit. It lives here (not in the engine loop) so the
- * report path journals gate evaluations through the identical writer.
+ * is journaled like a unit. It lives here (not in the engine loop) so every
+ * caller journals gate evaluations through the identical writer.
  *
  * This module NEVER dispatches a unit and NEVER writes step rows: dispatch is
  * the executor's job (`native-executor.ts`), advancing the gated spine is the
@@ -44,19 +44,17 @@ import { UsageError } from "../../core/errors.js";
 import { appendEvent } from "../../core/events.js";
 import { validateJsonSchemaSubset } from "../../core/json-schema.js";
 import { withWorkflowRunsRepo } from "../../storage/repositories/workflow-runs-repository.js";
-import { canonicalJson as canonicalJsonString, decodeCanonicalPlan } from "../ir/plan-hash.js";
-import { parseTemplate, resolveTemplate, resolveWholeValue, } from "../program/expressions.js";
+import { canonicalJson as canonicalJsonString } from "../ir/plan-hash.js";
+import { resolveReferenceString } from "../program/expressions.js";
 import { WORKFLOW_MAX_MAP_EXPANSION } from "../resource-limits.js";
 import { requireExecutableWorkflowPlan } from "../runtime/plan-classifier.js";
 import { completeWorkflowStep } from "../runtime/runs.js";
 import { GATE_EVALUATION_PHASE } from "../runtime/unit-phases.js";
 import { enqueueUnitWrite } from "./unit-writer.js";
 /**
- * Default per-unit timeout. Deliberately NOT the 60 s agent default
- * (`DEFAULT_AGENT_TIMEOUT_MS`) — workflow units routinely run real coding
- * tasks on slow local models; 10 minutes matches the LLM-path default
- * (`tryLlmFeature`). A unit's `timeout` declaration overrides this; `none`
- * disables.
+ * Default per-unit timeout for workflow units. A unit's `timeout` declaration
+ * overrides this; `none` disables it. Direct agent dispatch has no timeout by
+ * default, while workflow units retain an independent safety ceiling.
  */
 export const DEFAULT_UNIT_TIMEOUT_MS = 600_000;
 /** How much raw unit output is retained in step evidence (full text lives on the unit row). */
@@ -68,14 +66,54 @@ const GATE_ARTIFACT_CLIP = 4_000;
  * inputs: resolve the fan-out list, derive content-derived unit ids, assemble
  * each unit's prompt (preamble + interpolated instructions + gate feedback +
  * schema directive), and hash the resolved input. Same inputs ⇒ byte-identical
- * ids/hashes/prompts — the invariant `brief` relies on to predict the engine.
+ * ids/hashes/prompts — the invariant resume/replay relies on to recognize the
+ * units an earlier run already journaled.
  *
- * Whole-list failures (missing subgraph, template parse error, unresolvable /
- * non-array `over`, duplicate fan-out items) return `{ ok: false }`; a per-unit
- * expression-resolution failure is carried on that unit's `resolved` field so
- * the caller fails just that unit (mirroring the engine's `expression_error`
- * outcome), never the whole step.
+ * Whole-list failures (missing subgraph, unresolvable / non-array `over`,
+ * null or duplicate fan-out items) return `{ ok: false }`. The per-unit
+ * `resolved: { ok: false }` branch is STRUCTURALLY UNREACHABLE in the unified
+ * format — prose is never scanned for references, and everything that CAN
+ * fail (map.over / route.input / inputs:) resolves once per step, failing the
+ * whole list above. The branch is retained because every consumer of the work
+ * list shares the shape and defensively handles it; if a future unit kind
+ * reintroduces per-unit resolution (e.g. an exec/shell unit with real
+ * substitution), the failure plumbing is already in place.
  */
+/**
+ * Validate a fan-out item list BEFORE any identity/dispatch work: expansion
+ * within the resource limit, no null/undefined items, no canonical duplicates.
+ * Returns the failure message, or undefined when the list is dispatchable.
+ *
+ * Null items: producer garbage — there is nothing to hand the unit as its work
+ * item. The pre-unification format rejected them incidentally (substituting
+ * `${{ item }}` failed); with items attached as context instead of spliced,
+ * nothing later would stop a unit from being dispatched with "Item: null", so
+ * the rejection is explicit here. Duplicates: content-derived unit identity
+ * makes canonical duplicates collide on id — an authoring error caught
+ * deterministically, before dispatch.
+ */
+function validateFanOutItems(stepId, items) {
+    if (items.length > WORKFLOW_MAX_MAP_EXPANSION) {
+        return `Step "${stepId}" fan-out expands to ${items.length} units, exceeding the ${WORKFLOW_MAX_MAP_EXPANSION}-unit resource limit.`;
+    }
+    const nullIndex = items.findIndex((item) => item === null || item === undefined);
+    if (nullIndex !== -1) {
+        return (`Step "${stepId}" fan-out list contains a null item (index ${nullIndex}). ` +
+            `Every item must be a concrete value — fix the producing step's output.`);
+    }
+    const firstIndexByCanonical = new Map();
+    for (let i = 0; i < items.length; i++) {
+        const canonical = canonicalJson(items[i]) ?? "null";
+        const firstIndex = firstIndexByCanonical.get(canonical);
+        if (firstIndex !== undefined) {
+            return (`Step "${stepId}" fan-out list contains duplicate items (indices ${firstIndex} and ${i}: ` +
+                `${clip(canonical, 200)}). Content-derived unit identity requires distinct items — ` +
+                `deduplicate the list this workflow fans out over.`);
+        }
+        firstIndexByCanonical.set(canonical, i);
+    }
+    return undefined;
+}
 export function computeStepWorkList(plan, input) {
     const root = plan.root;
     // Route-only steps (YAML `route:`) carry no execution subgraph.
@@ -88,30 +126,29 @@ export function computeStepWorkList(plan, input) {
     const template = root.kind === "map" ? root.template : root;
     const reducer = root.kind === "map" ? root.reducer : "collect";
     const scope = { params: input.params, stepOutputs: input.stepOutputs };
-    // Parse the instruction template ONCE (deterministic; resolution is a single
-    // pass per unit — substituted content is never re-scanned). Only nodes the
-    // frontend marked `templating: "expressions"` carry the `${{ … }}` grammar;
-    // classic linear markdown is opaque verbatim text.
-    let instructionSegments;
-    if (template.templating === "expressions") {
-        const parsedInstructions = parseTemplate(template.instructions);
-        if (!parsedInstructions.ok) {
+    // Instructions are ALWAYS the step's body prose, byte-exact — never
+    // templated, never scanned for reference syntax (workflow-format-
+    // unification, spec §2.3). Only `map.over` / `route.input` / `inputs[]`
+    // carry the closed reference grammar.
+    // Resolve the step's declared `inputs:` ONCE (shared by every unit in this
+    // step — map items differ, declared inputs do not): prior-step artifacts
+    // attached to every dispatched unit as structured context.
+    const resolvedInputs = [];
+    for (const reference of template.inputs ?? []) {
+        const resolved = resolveReferenceString(reference, scope);
+        if (!resolved.ok) {
             return {
                 ok: false,
-                error: `Step "${plan.stepId}" instructions template failed to parse: ` +
-                    parsedInstructions.errors.map((e) => e.message).join(" "),
+                error: `Step "${plan.stepId}" declared input "${reference}" failed to resolve: ${resolved.error.message}`,
             };
         }
-        instructionSegments = parsedInstructions.segments;
+        resolvedInputs.push({ reference, value: resolved.value });
     }
-    else {
-        instructionSegments = [{ kind: "literal", text: template.instructions }];
-    }
-    // Resolve fan-out items: `over` is a single whole-value `${{ … }}` reference
-    // naming its producer explicitly — no ambient key search.
+    // Resolve fan-out items: `over` is a single whole-value reference naming
+    // its producer explicitly — no ambient key search.
     let items;
     if (root.kind === "map") {
-        const source = resolveWholeValue(root.over, scope);
+        const source = resolveReferenceString(root.over, scope);
         if (!source.ok) {
             return {
                 ok: false,
@@ -130,31 +167,12 @@ export function computeStepWorkList(plan, input) {
         items = [undefined];
     }
     const isFanOut = root.kind === "map";
-    if (isFanOut && items.length > WORKFLOW_MAX_MAP_EXPANSION) {
-        return {
-            ok: false,
-            error: `Step "${plan.stepId}" fan-out expands to ${items.length} units, exceeding the ${WORKFLOW_MAX_MAP_EXPANSION}-unit resource limit.`,
-        };
-    }
-    // Content-derived unit identity: compute every id up front. Duplicate items
-    // collide on identity — an authoring error caught HERE, deterministically.
+    const fanOutProblem = isFanOut ? validateFanOutItems(plan.stepId, items) : undefined;
+    if (fanOutProblem)
+        return { ok: false, error: fanOutProblem };
+    // Content-derived unit identity: compute every id up front (duplicate items
+    // were rejected above — identity requires distinct items).
     const unitIds = items.map((item) => unitIdFor(template.id, item, isFanOut));
-    if (isFanOut) {
-        const firstIndexByCanonical = new Map();
-        for (let i = 0; i < items.length; i++) {
-            const canonical = canonicalJson(items[i]) ?? "null";
-            const firstIndex = firstIndexByCanonical.get(canonical);
-            if (firstIndex !== undefined) {
-                return {
-                    ok: false,
-                    error: `Step "${plan.stepId}" fan-out list contains duplicate items (indices ${firstIndex} and ${i}: ` +
-                        `${clip(canonical, 200)}). Content-derived unit identity requires distinct items — ` +
-                        `deduplicate the list this workflow fans out over.`,
-                };
-            }
-            firstIndexByCanonical.set(canonical, i);
-        }
-    }
     const gateLoop = input.gateLoop ?? 1;
     const frozenInvocation = template.invocation;
     if (!frozenInvocation)
@@ -171,66 +189,80 @@ export function computeStepWorkList(plan, input) {
         // never clobbered; the content-derived identity (and the prompt's
         // {{UNIT_ID}}) stays the base id.
         const journalBaseId = gateLoop > 1 ? `${unitId}~l${gateLoop}` : unitId;
-        // Single-pass resolution of the pre-parsed template against this unit's
-        // scope. A resolution failure is deterministic authoring/data breakage.
-        const unitScope = isFanOut ? { ...scope, item, itemIndex: index } : scope;
-        const resolvedInstr = resolveTemplate(instructionSegments, unitScope);
-        let resolved;
-        if (!resolvedInstr.ok) {
-            resolved = {
-                ok: false,
-                error: `instructions failed to resolve: ${resolvedInstr.errors.map((e) => e.message).join(" ")}`,
-            };
-        }
-        else {
-            const prompt = buildUnitPrompt({
-                runId: input.runId,
-                stepId: plan.stepId,
-                unitId,
-                params: input.params,
-                ...(input.gateFeedback ? { gateFeedback: input.gateFeedback } : {}),
-                ...(template.schema ? { schema: template.schema } : {}),
-                instructions: resolvedInstr.text,
-            });
-            // Canonical dispatch-input envelope (reviewer finding #1). Every field
-            // here is a PLAN-FROZEN input that changes what the backend is actually
-            // asked to do, so a completed unit is reused ONLY when all of them match;
-            // a change to any of them re-dispatches. Key order is FIXED — it is the
-            // hash preimage (JSON.stringify preserves insertion order) — and shared
-            // by ALL surfaces, since this is the ONE place a unit's inputHash is
-            // computed (engine, brief, and report all call computeStepWorkList), so
-            // the byte-identical hash across surfaces is structural, not coincidental.
-            //
-            // Included beyond the R4 baseline (prompt/runner/model/schema): resolved
-            // timeoutMs, the env asset ref NAMES, and isolation — each
-            // reaches dispatch (native-executor's UnitDispatchRequest) and a changed
-            // one yields a materially different call. `env` carries NAMES ONLY, never
-            // resolved values: hashing a resolved secret would leak it into a
-            // durable hash oracle and would spuriously re-dispatch on every secret
-            // rotation. `retry`/`onError` are DELIBERATELY excluded — they govern
-            // failed-unit re-dispatch and step-level failure reduction, not a
-            // COMPLETED unit's inputs/output, so a completed row stays valid across
-            // policy changes.
-            //
-            // Ambient config is DELIBERATELY excluded — the model-alias table, the
-            // resolved backend/connection, and the working directory (`ctx.workDir` /
-            // process.cwd()) are NOT plan-frozen. The frozen plan is the identity
-            // boundary (redesign addendum determinism bar #2): config drift under an
-            // in-flight run is out of scope by design.
-            const dispatch = transitiveDispatchSnapshot(frozenEngine, input.engines ?? {});
-            const inputHash = createHash("sha256")
-                .update(canonicalJsonString({
-                hashVersion: 3,
-                prompt,
-                dispatch,
-                invocation: frozenInvocation,
-                schema: template.schema ?? null,
-                env: template.env ?? null,
-                isolation: template.isolation ?? "none",
-            }))
-                .digest("hex");
-            resolved = { ok: true, prompt, inputHash };
-        }
+        // Context attachment (workflow-format-unification, spec §4): every unit
+        // receives the run params (already in the preamble), its item + index if
+        // it is a map unit, and the artifacts named by its step's `inputs:`.
+        // Instructions reach the unit byte-exact — never interpolated.
+        const prompt = buildUnitPrompt({
+            runId: input.runId,
+            stepId: plan.stepId,
+            unitId,
+            params: input.params,
+            ...(isFanOut ? { item, itemIndex: index } : {}),
+            ...(resolvedInputs.length > 0 ? { inputs: resolvedInputs } : {}),
+            ...(input.gateFeedback ? { gateFeedback: input.gateFeedback } : {}),
+            ...(template.schema ? { schema: template.schema } : {}),
+            instructions: template.instructions,
+        });
+        // Canonical dispatch-input envelope (reviewer finding #1). Every field
+        // here is a PLAN-FROZEN input that changes what the backend is actually
+        // asked to do, so a completed unit is reused ONLY when all of them match;
+        // a change to any of them re-dispatches. Key order is FIXED — it is the
+        // hash preimage (JSON.stringify preserves insertion order) — and this is
+        // the ONE place a unit's inputHash is computed (every caller goes through
+        // computeStepWorkList), so a hash that is byte-identical across a fresh
+        // run and a resume is structural, not coincidental.
+        //
+        // Unit identity (workflow-format-unification, spec §2.3/§4) hashes the
+        // FROZEN TEMPLATE BYTES (`template.instructions`, byte-exact, never an
+        // instantiated/interpolated string) + the canonical item JSON + the
+        // declared-input artifact hashes + the params snapshot — instead of a
+        // resolved/spliced prompt string, since there is no more splicing. The
+        // assembled `prompt` above is what the harness SEES; the hash is over the
+        // plan-frozen INPUTS that determine it, which is the same replay contract
+        // the old resolved-prompt hash gave (same inputs ⇒ same hash) with the
+        // interpolation step removed.
+        //
+        // Included beyond the R4 baseline (template/runner/model/schema): resolved
+        // timeoutMs, the env asset ref NAMES, and isolation — each reaches
+        // dispatch (native-executor's UnitDispatchRequest) and a changed one
+        // yields a materially different call. `env` carries NAMES ONLY, never
+        // resolved values: hashing a resolved secret would leak it into a durable
+        // hash oracle and would spuriously re-dispatch on every secret rotation.
+        // `retry`/`onError` are DELIBERATELY excluded — they govern failed-unit
+        // re-dispatch and step-level failure reduction, not a COMPLETED unit's
+        // inputs/output, so a completed row stays valid across policy changes.
+        //
+        // `gateFeedback` IS included (conditionally, so a no-feedback unit's
+        // preimage is byte-identical to before): it is appended to the prompt by
+        // `buildUnitPrompt`, so a gate loop's retry is materially a different ask
+        // than the rejected attempt — omitting it made loop 1 and loop 2 journal
+        // identical hashes for different prompts, breaking the "changed inputs ⇒
+        // changed hash" audit contract. Replay-safe: feedback is re-derived from
+        // the journaled gate decision, so a resumed retry re-hashes identically.
+        //
+        // Ambient config is DELIBERATELY excluded — the model-alias table, the
+        // resolved backend/connection, and the working directory (`ctx.workDir` /
+        // process.cwd()) are NOT plan-frozen. The frozen plan is the identity
+        // boundary (redesign addendum determinism bar #2): config drift under an
+        // in-flight run is out of scope by design.
+        const dispatch = transitiveDispatchSnapshot(frozenEngine, input.engines ?? {});
+        const inputHash = createHash("sha256")
+            .update(canonicalJsonString({
+            hashVersion: 4,
+            template: template.instructions,
+            item: isFanOut ? (item ?? null) : null,
+            inputs: resolvedInputs,
+            params: input.params,
+            dispatch,
+            invocation: frozenInvocation,
+            schema: template.schema ?? null,
+            env: template.env ?? null,
+            isolation: template.isolation ?? "none",
+            ...(input.gateFeedback ? { gateFeedback: input.gateFeedback } : {}),
+        }))
+            .digest("hex");
+        const resolved = { ok: true, prompt, inputHash };
         return {
             unitId,
             nodeId: template.id,
@@ -265,13 +297,16 @@ export function computeStepWorkList(plan, input) {
     };
 }
 /**
- * Assemble the final prompt: engine preamble + resolved instructions
- * (+ gate feedback on loop re-executions, + schema directive). Workflow-
- * authored interpolation happened upstream via the expression module; only
- * the ENGINE's own preamble placeholders are substituted here.
+ * Assemble the final prompt: engine preamble (run params + item/index +
+ * declared-input artifacts, all as structured JSON context) + the step's
+ * BYTE-EXACT prose instructions (+ gate feedback on loop re-executions, +
+ * schema directive). Instructions are NEVER interpolated (workflow-format-
+ * unification, spec §2.3) — data reaches the unit as attached context, not
+ * string splices; only the ENGINE's own preamble placeholders are substituted
+ * here.
  */
 export function buildUnitPrompt(input) {
-    const { runId, stepId, unitId, params, gateFeedback, schema, instructions } = input;
+    const { runId, stepId, unitId, params, itemIndex, item, inputs, gateFeedback, schema, instructions } = input;
     // Function replacements throughout: a string replacement would interpret
     // GetSubstitution patterns ($&, $$, $', $`) inside VALUES and silently
     // corrupt the prompt (e.g. a param value containing "$&").
@@ -280,6 +315,15 @@ export function buildUnitPrompt(input) {
         .replaceAll("{{STEP_ID}}", () => stepId)
         .replaceAll("{{UNIT_ID}}", () => unitId)
         .replaceAll("{{PARAMS_JSON}}", () => safeJson(params));
+    // Map-unit context: the item this unit was given, plus its index. Attached
+    // as structured JSON — the engine never splices it into the instructions.
+    const itemBlock = itemIndex !== undefined
+        ? `\n\n## Item (index ${itemIndex})\nYou were given this item from the fan-out list:\n${safeJson(item)}`
+        : "";
+    // Declared `inputs:` context: the prior-step artifacts this step named.
+    const inputsBlock = inputs && inputs.length > 0
+        ? `\n\n## Declared inputs\n${inputs.map((i) => `### ${i.reference}\n${safeJson(i.value)}`).join("\n\n")}`
+        : "";
     // Gate-loop feedback (R2 max_loops): the judge's rejection is appended so
     // the re-executed unit can address it — and so the input hash changes,
     // making the loop's re-dispatch natural instead of a durable-row reuse.
@@ -294,7 +338,7 @@ export function buildUnitPrompt(input) {
     const schemaDirective = schema
         ? `\n\nRespond with ONLY a JSON value matching this JSON Schema (no prose, no code fences):\n${safeJson(schema)}`
         : "";
-    return `${preamble}\n${instructions}${gateBlock}${schemaDirective}`;
+    return `${preamble}\n${instructions}${itemBlock}${inputsBlock}${gateBlock}${schemaDirective}`;
 }
 /**
  * Content-derived unit identity (module doc): `<node_id>:<hash12>` for a
@@ -376,18 +420,17 @@ function unitOutputValue(unit) {
     return unit.text ?? null;
 }
 export function buildEvidence(units, reducer, isFanOut) {
-    // Per-unit evidence is the DURABLE, surface-independent projection the two
-    // driver surfaces (engine + brief/report) must agree on byte-for-byte (R4
-    // conformance, "identical unit graph"). It therefore carries ONLY fields both
-    // surfaces can reproduce from the journal:
+    // Per-unit evidence is the DURABLE projection of the unit graph — a fresh run
+    // and a resumed run of the same plan must agree on it byte-for-byte. It
+    // therefore carries ONLY fields that can be reproduced from the journal alone:
     //   - a SUCCESS keeps its promoted contribution (structured `result` or clipped
-    //     `text`) — the report path rehydrates exactly these from the unit row;
+    //     `text`) — the reuse path rehydrates exactly these from the unit row;
     //   - a FAILURE keeps only its `failureReason` (the durable, journaled failure
-    //     vocabulary). The engine's in-memory dispatch diagnostic (`error`) and any
-    //     residual `text` on a failed unit are NOT persisted here: a driver-reported
-    //     failure carries neither, so persisting them on the engine surface alone
-    //     would diverge the durable graph. The full raw text/reason still lives on
-    //     the unit row for engine-side diagnostics; this is the shared graph.
+    //     vocabulary). The in-memory dispatch diagnostic (`error`) and any residual
+    //     `text` on a failed unit are NOT persisted here: they do not survive a
+    //     restart, so persisting them on the live-dispatch path alone would make
+    //     the durable graph depend on WHEN it was built. The full raw text/reason
+    //     still lives on the unit row for diagnostics; this is the shared graph.
     const collected = units.map((u) => u.ok
         ? {
             unitId: u.unitId,
@@ -478,13 +521,11 @@ export function reduceStepOutcomes(plan, reducer, isFanOut, onError, units) {
  * resolution rather than silently reading the envelope). Even the degenerate
  * artifact must honor the step's declared `outputSchema` before it can complete.
  *
- * Shared by native dispatch (`executeStepPlan`'s `items.length === 0` branch)
- * and the R3 driver protocol (`report` auto-completes an empty step the spine
- * reaches, since no `report --unit` can ever advance a zero-unit step) so both
- * surfaces promote the SAME artifact and apply the SAME schema verdict — the
- * anti-drift guarantee. Deliberately does NOT run the reducer/vote-tie logic:
- * an empty step has no successful results to count, and a vote-tie "failure"
- * would diverge from the engine's long-standing empty-list semantics.
+ * Used by native dispatch (`executeStepPlan`'s `items.length === 0` branch): a
+ * zero-unit step can never be advanced by a unit completion, so it is promoted
+ * here instead. Deliberately does NOT run the reducer/vote-tie logic: an empty
+ * step has no successful results to count, and a vote-tie "failure" would
+ * diverge from the engine's long-standing empty-list semantics.
  */
 export function reduceEmptyStep(plan, reducer) {
     const evidence = { units: [], itemCount: 0, output: reducer === "collect" ? [] : null };
@@ -498,12 +539,13 @@ export function reduceEmptyStep(plan, reducer) {
     };
 }
 /**
- * Rehydrate a journaled unit row into a {@link UnitOutcome}. Shared by the
- * executor's durable-row reuse (`native-executor.ts`, completed rows only) and
- * the R3 report path (which reduces completed AND failed rows replayed from the
- * journal). A completed row's text unit journals its output as a JSON string; a
- * schema unit journals the validated structure. A failed row carries its
- * `failure_reason`; any journaled text is surfaced too.
+ * Rehydrate a journaled unit row into a {@link UnitOutcome}. The executor's
+ * durable-row reuse (`native-executor.ts`) calls it for completed rows; the
+ * failed-row branch keeps the mapping TOTAL, so any reduction driven off the
+ * journal yields the same outcome the live dispatch produced. A completed row's
+ * text unit journals its output as a JSON string; a schema unit journals the
+ * validated structure. A failed row carries its `failure_reason`; any journaled
+ * text is surfaced too.
  */
 export function unitOutcomeFromRow(unitId, row, hasSchema) {
     let parsed;
@@ -536,97 +578,6 @@ export function unitOutcomeFromRow(unitId, row, hasSchema) {
         ...(row.tokens !== null ? { tokens: row.tokens } : {}),
     };
 }
-/**
- * Select the journaled attempt row that determines a unit's TERMINAL outcome on
- * a REPLAY surface — the engine's durable-row reuse AND the harness-neutral
- * brief/report driver protocol — given the run's dispatch rows indexed by
- * unit_id. This is the ONE place all surfaces resolve "which journaled row IS
- * this unit's outcome," so they cannot drift from each other or from the engine.
- *
- * It mirrors the executor's {@link classifyUnitReuse} attempt scan
- * (native-executor.ts): among the base attempt and its `~r<n>` retries — all
- * stacked on `journalBaseId`, which already carries the active `~l<loop>` gate
- * suffix — the FIRST completed attempt is the effective result. So a unit whose
- * base attempt FAILED but whose later retry COMPLETED reduces as COMPLETED,
- * exactly like an engine resume reusing the `~r1` row (Codex round-3 finding C);
- * reading only the base row would reduce it as failed and diverge the two
- * surfaces. With no completed attempt the HIGHEST journaled attempt stands (a
- * terminal failure, or a still-running row); no attempt row at all ⇒ `undefined`
- * (the unit is still outstanding).
- */
-export function selectUnitAttemptRow(workUnit, dispatchRows) {
-    const base = workUnit.journalBaseId;
-    const maxAttempts = 1 + Math.max(0, workUnit.retry?.max ?? 0);
-    let fallback;
-    for (let attempt = 0; attempt < maxAttempts; attempt++) {
-        const row = dispatchRows.get(attempt === 0 ? base : `${base}~r${attempt}`);
-        if (!row)
-            continue;
-        if (row.status === "completed")
-            return row;
-        fallback = row; // remember the highest journaled (non-completed) attempt
-    }
-    return fallback;
-}
-/**
- * Is a FAILED unit still RETRY-ELIGIBLE — i.e. NOT terminal, because a driver
- * could still re-run it via the `--rerun` form (the engine's automatic
- * `<baseId>~r<n>` retry)? A unit whose declared `retry.on` matches the recorded
- * failure reason AND whose attempt budget (`1 + retry.max`) is not yet spent can
- * still be re-run. No `retry`, an off-list reason, or an exhausted attempt budget
- * ⇒ the failure IS terminal. Shared by the report fail-fast decision, the
- * `--settle` refusal, and `brief`'s fully-terminal detection so all three agree
- * on when a failed unit is genuinely done vs. still re-runnable. The normalized
- * failure reason is compared against `retry.on` directly (a canonical taxonomy
- * reason is stored verbatim; an `external:*` reason is by construction outside
- * the taxonomy `retry.on` lists).
- */
-export function isRetryEligibleFailure(workUnit, row, failureReason) {
-    const retry = workUnit.retry;
-    if (!retry || failureReason === null || !retry.on.includes(failureReason))
-        return false;
-    const attempts = row?.attempts ?? 1;
-    return attempts < 1 + Math.max(0, retry.max);
-}
-/**
- * Does a resolvable unit still need a driver to execute + report it (or re-run
- * it)? True for a unit with no terminal row (pending), a still-`running` row (a
- * live/stale claim another driver holds), or a FAILED row that is still
- * retry-eligible. False for a COMPLETED row, a terminal non-retry-eligible
- * FAILURE, or an UNRESOLVABLE unit (the engine's immediate `expression_error` —
- * never reportable). The best terminal attempt (base + `~r<n>` retries) is the
- * one consulted, the SAME reuse the engine and reducer apply.
- */
-export function unitStillNeedsReport(workUnit, dispatchRows) {
-    if (!workUnit.resolved.ok)
-        return false;
-    const row = selectUnitAttemptRow(workUnit, dispatchRows);
-    if (!row)
-        return true; // no journal row → pending
-    if (row.status === "running")
-        return true; // a live/stale claim is still in flight
-    if (row.status === "failed")
-        return isRetryEligibleFailure(workUnit, row, row.failure_reason);
-    return false; // completed (or a non-retry-eligible failure) → terminal
-}
-/**
- * Is the active step's work-list FULLY TERMINAL — every resolvable unit run to a
- * terminal (done, or non-retry-eligible failed) state with nothing left to
- * execute or per-unit report — yet still needing finalization? This is the
- * driver-recovery state after a required-gate block is resumed, or a crash
- * between the last unit write and the step's completion (owner manual-validation
- * finding 3): the work-list is done but the step never advanced. `brief`
- * surfaces it with a single `report --settle` command and `--settle` runs the
- * shared completion path for it. A list with ANY outstanding unit (pending,
- * in-flight, or retry-eligible failed) is NOT fully terminal — the driver
- * `report --unit`s those. A route-only / empty / all-unresolvable list (no
- * resolvable units) is a DIFFERENT non-dispatching state, handled separately.
- */
-export function isWorkListFullyTerminal(workList, dispatchRows) {
-    if (!workList.units.some((u) => u.resolved.ok))
-        return false;
-    return workList.units.every((u) => !unitStillNeedsReport(u, dispatchRows));
-}
 /** Stable stringify (sorted object keys, recursively) so equal values vote together. */
 export function canonicalJson(value) {
     return JSON.stringify(sortKeys(value));
@@ -647,9 +598,9 @@ function sortKeys(value) {
 // `{ complete: false, missing, feedback }` (see journalGateEvaluationFinish).
 // The feedback stored there is BYTE-IDENTICAL to what the engine threads into
 // the next loop's prompts — both are the same `rejection.feedback`/`.missing`.
-// `brief` recovers it from the journal so its loop-N work-list matches the
-// engine's (redesign addendum R3, task item 2). `native-executor.test.ts`
-// asserts the round-trip identity.
+// A resume recovers it from the journal so its loop-N work-list (and therefore
+// every unit id and input hash in it) matches the one the original run built.
+// `native-executor.test.ts` asserts the round-trip identity.
 // GATE_EVALUATION_PHASE moved to ../runtime/unit-phases.ts (leaf) so
 // unit-checkin can key on it without closing the exec ↔ runtime cycle.
 /** The unit id of a step's gate-evaluation row for a given 1-based loop. */
@@ -714,9 +665,10 @@ function gateLoopOf(unitId, stepId) {
 /**
  * Classify a gate-evaluation row's journaled verdict, failing LOUDLY on a
  * corrupt one (reviewer #17). A NULL `result_json` is the LEGITIMATE
- * errored-judge / in-flight shape (`journalGateEvaluationFinish` writes null for
- * an errored judge, and a `running` row has no verdict yet) and classifies as
- * `empty`. But a PRESENT `result_json` that does not parse as JSON, or parses to
+ * completion-error / in-flight shape (`journalGateEvaluationFinish` writes null
+ * if completion itself throws after judge invocation, and a `running` row has no
+ * verdict yet) and classifies as `empty`. But a PRESENT `result_json` that does
+ * not parse as JSON, or parses to
  * anything other than an object with a boolean `complete` field, is corruption —
  * a truncated or hand-edited row — and MUST NOT be silently treated as absent
  * (which would reset an active step's gate loop to 1 and re-dispatch work whose
@@ -764,7 +716,7 @@ export async function journalGateEvaluationStart(gate) {
         // Marks the row as a judge call, NOT a dispatch: the budget/lifetime
         // seed in `driveRun` skips these so resume accounting matches live.
         phase: GATE_EVALUATION_PHASE,
-        runner: "llm",
+        runner: gate.runner,
         engine: gate.invocation.engine,
         model: gate.invocation.model,
         inputHash: gate.inputHash,
@@ -780,17 +732,14 @@ export async function journalGateEvaluationStart(gate) {
  * Finish the gate-evaluation unit row with the verdict as observed from the
  * completion outcome: a rejection journals `{ complete: false, missing,
  * feedback }`; a pass journals `{ complete: true, missing: [] }`; a judge that
- * threw (or, on a required gate, returned an unparseable verdict) journals a
- * failed row with a NULL verdict. A NON-required errored gate then fails OPEN
- * inside `validateStepSummary`; a REQUIRED errored gate BLOCKS the step
- * (`finalizeExecutedStep`, Codex round-3 finding A).
+ * threw journals a failed row with the synthesized fail-closed rejection.
  */
 export async function journalGateEvaluationFinish(gate, errored, rejection) {
     const unitId = gateUnitId(gate.stepId, gate.loop);
-    const verdict = errored
-        ? null
-        : rejection
-            ? { complete: false, missing: rejection.missing, feedback: rejection.feedback }
+    const verdict = rejection
+        ? { complete: false, missing: rejection.missing, feedback: rejection.feedback }
+        : errored
+            ? null
             : { complete: true, missing: [] };
     const status = errored ? "failed" : "completed";
     await enqueueUnitWrite(() => withWorkflowRunsRepo((repo) => repo.finishUnit({
@@ -814,7 +763,7 @@ export async function journalGateEvaluationFinish(gate, errored, rejection) {
  * comparison is exact string equality against the declared `when:` matches.
  */
 export function evaluateRoute(route, scope) {
-    const resolved = resolveWholeValue(route.input, scope);
+    const resolved = resolveReferenceString(route.input, scope);
     if (!resolved.ok) {
         return { ok: false, error: `route input ${route.input} failed to resolve: ${resolved.error.message}` };
     }
@@ -910,26 +859,6 @@ function assertRouteTargetDeclared(route, stepId, selected, runId) {
             `apply a bogus route decision that would skip the real branch targets. Start a new run.`);
     }
 }
-/**
- * Validate every COMPLETED route step's journaled selection against its declared
- * targets (reviewer #7). Read-only: it throws on a PRESENT-but-invalid selection
- * and is silent on an absent one, so it never false-positives on a healthy run —
- * making it safe to call from the read-only `brief` surface as well as the
- * resume/report surfaces that already re-apply the decisions.
- */
-export function assertJournaledRouteSelectionsValid(plan, state) {
-    for (const stepPlan of plan.steps) {
-        if (!stepPlan.route)
-            continue;
-        const stepState = state.workflow.steps.find((s) => s.id === stepPlan.stepId);
-        if (!stepState || stepState.status !== "completed")
-            continue;
-        const selected = journaledRouteSelection(stepState.evidence);
-        if (selected !== undefined) {
-            assertRouteTargetDeclared(stepPlan.route, stepPlan.stepId, selected, state.run.id);
-        }
-    }
-}
 /**
  * Replay journaled route decisions into the skip bookkeeping (resume path).
  * For every COMPLETED route step of the frozen plan, in spine order: the
@@ -972,7 +901,7 @@ export function seedJournaledRouteDecisions(plan, state, routeSelected, routeUns
         if (selected === undefined) {
             throw new UsageError(`Workflow run ${state.run.id} has a completed route step "${stepPlan.stepId}" with no journaled route ` +
                 `decision, and the decision cannot be re-derived from the journaled evidence. Refusing to guess which ` +
-                `branch was selected — advance the remaining steps manually with \`akm workflow complete\`.`);
+                `branch was selected. The run journal is inconsistent; abandon this run and start a new one.`);
         }
         applyRouteDecision(stepPlan.route, stepPlan.stepId, selected, routeSelected, routeUnselected);
     }
@@ -1020,23 +949,6 @@ export async function finalizeExecutedStep(input) {
     // A frozen plan either supplies its judge at the dispatch boundary or has no
     // judge. Re-selecting defaults here would let config drift change a run.
     const innerJudge = input.summaryJudge ?? null;
-    // Reviewer #18: a REQUIRED completion gate must actually be judged. When the
-    // gate carries criteria but no judge is available, `validateStepSummary` would
-    // fail OPEN and silently pass the gate — exactly the offline/misconfigured
-    // bypass a required gate exists to prevent. BLOCK the step instead (a human
-    // resolves it via the documented manual path), rather than advance the spine
-    // on an unjudged gate. `gate.required` rides the frozen plan (both surfaces);
-    // `requireGates` is the engine's run-wide `--require-gates` override. Checked
-    // BEFORE route evaluation so a blocked step journals no route decision.
-    const gateRequired = stepPlan.gate.required === true || input.requireGates === true;
-    if (gateRequired && completionCriteria.length > 0 && innerJudge === null) {
-        const notes = `Step "${stepId}" has a REQUIRED completion gate but no summary-validation judge is available ` +
-            `(no LLM is configured, or default LLM resolution failed). A required gate must be judged — refusing to fail ` +
-            `open and silently pass it. The step is BLOCKED: configure an LLM, then \`akm workflow resume ${runId}\` to ` +
-            `re-evaluate the gate, or advance the step manually with \`akm workflow complete\`.`;
-        await completeWorkflowStep({ runId, stepId, status: "blocked", notes, evidence: result.evidence, ...lease });
-        return { kind: "blocked", summary: notes };
-    }
     // Route evaluation BEFORE completion: an unroutable value is an
     // authoring/config failure that must fail the step deterministically.
     let summaryOverride;
@@ -1065,9 +977,9 @@ export async function finalizeExecutedStep(input) {
     const summary = stepPlan.root && completionCriteria.length > 0
         ? buildArtifactSummary(stepId, result.units, result.evidence)
         : (summaryOverride ?? result.summary);
-    // Journal engine-driven judge calls as unit rows (they are LLM calls). The
-    // wrapper's `invoked` stays false when the gate is fail-open (no criteria / no
-    // judge) — nothing is journaled, and human approvals are never cached.
+    // Journal engine-driven judge calls as unit rows. With no criteria there is
+    // no judge invocation or row; a criteria-bearing plan without a judge is a
+    // configuration error rather than a silent bypass.
     const frozenGate = innerJudge
         ? await withWorkflowRunsRepo((repo) => {
             const row = repo.getRunById(runId);
@@ -1091,6 +1003,7 @@ export async function finalizeExecutedStep(input) {
                     stepId,
                     loop: gateLoop,
                     invocation: gateInvocation,
+                    runner: frozenGate?.engine?.kind === "agent" ? frozenGate.engine.runnerKind : "llm",
                     inputHash: createHash("sha256")
                         .update(canonicalJsonString({
                         hashVersion: 3,
@@ -1114,8 +1027,7 @@ export async function finalizeExecutedStep(input) {
     // Reviewer #6: once the judge is invoked, its gate row is journaled `running`
     // (journalGateEvaluationStart) and MUST be finished on every exit. The
     // already-fixed window is the judge itself throwing (caught inside
-    // validateStepSummary — `judgeState.errored` records it; a non-required gate
-    // fails open, a required gate blocks below). The remaining
+    // validateStepSummary — `judgeState.errored` records it). The remaining
     // window is `completeWorkflowStep` throwing AFTER the judge ran — a stolen
     // lease, a concurrent state change, a DB error — which would otherwise skip the
     // finish and strand the gate row in `running`. Finish it as an errored row (the
@@ -1129,10 +1041,7 @@ export async function finalizeExecutedStep(input) {
             summary,
             evidence: result.evidence,
             summaryJudge,
-            // Codex round-3 finding A: mark this completion's gate REQUIRED so
-            // `validateStepSummary` does NOT fail open when the judge throws / is
-            // unreachable / returns garbage — it flags `errored` and we block below.
-            ...(gateRequired ? { requireGate: true } : {}),
+            ...(input.signal ? { signal: input.signal } : {}),
             ...lease,
         });
     }
@@ -1142,25 +1051,8 @@ export async function finalizeExecutedStep(input) {
         throw err;
     }
     const rejection = "ok" in completion && completion.ok === false ? completion : undefined;
-    // A required gate whose judge could not be evaluated is an errored gate, not a
-    // real rejection: journal the gate row as errored (verdict null) so the
-    // observed outcome is honest, driven by EITHER the wrapper catching a throw OR
-    // validateStepSummary flagging an unparseable verdict.
-    const gateErrored = judgeState.errored || rejection?.errored === true;
     if (gateUnit) {
-        await journalGateEvaluationFinish(gateUnit, gateErrored, rejection);
-    }
-    // Codex round-3 finding A: a REQUIRED gate that could not be judged (the judge
-    // threw, was unreachable, or returned an unparseable verdict) must NOT fail
-    // open and advance. The gate row is journaled errored above; BLOCK the step (a
-    // human resolves it) instead of silently passing an unjudged required gate.
-    if (rejection?.errored) {
-        const notes = `Step "${stepId}" has a REQUIRED completion gate but its summary-validation judge failed to return a verdict ` +
-            `(the LLM threw, was unreachable, or returned an unparseable response). A required gate must be judged — refusing ` +
-            `to fail open and silently pass it. The step is BLOCKED: fix the LLM/connection, then \`akm workflow resume ${runId}\` ` +
-            `to re-evaluate the gate, or advance the step manually with \`akm workflow complete\`.`;
-        await completeWorkflowStep({ runId, stepId, status: "blocked", notes, evidence: result.evidence, ...lease });
-        return { kind: "blocked", summary: notes };
+        await journalGateEvaluationFinish(gateUnit, judgeState.errored, rejection);
     }
     if (!rejection) {
         return { kind: "advanced", ...(summaryOverride !== undefined ? { summaryOverride } : {}) };
@@ -1173,25 +1065,6 @@ export async function finalizeExecutedStep(input) {
         gateRejection: { stepId, missing: rejection.missing, feedback: rejection.feedback },
     };
 }
-// ── Frozen plan parse + integrity check (shared) ─────────────────────────────
-/**
- * Parse and integrity-check a run's frozen plan JSON (migration 006). Shared by
- * the engine loop's plan loader (`run-workflow.ts`) and the R3 brief/report
- * surfaces so all three apply the SAME corruption + hash checks — the frozen
- * plan the engine executes is the exact plan brief describes and report
- * validates against. A NULL `plan_json` is the CALLER's decision (the engine
- * warns and compiles from the asset; brief/report error), so this helper only
- * handles a PRESENT plan string.
- */
-export function parseFrozenPlan(runId, planJson, planHash) {
-    try {
-        return decodeCanonicalPlan(runId, planJson, planHash);
-    }
-    catch (cause) {
-        throw new UsageError(`Workflow run ${runId} has a corrupt frozen plan: ${cause instanceof Error ? cause.message : String(cause)}. ` +
-            `The journaled plan cannot be executed — abandon it and start a new run.`);
-    }
-}
 // ── Small helpers ────────────────────────────────────────────────────────────
 function safeJson(value) {
     try {