akm-cli 0.9.2-alpha.4 → 0.9.2

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

@@ -4,44 +4,21 @@
 /**
  * Shared step semantics — the ONE implementation of a step's orchestration
  * 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.
+ * `native-executor.ts`) on both the fresh-execution and the resume/replay
+ * path, so a first run and a resumed run of the same frozen plan produce
+ * byte-identical unit graphs. `computeStepWorkList` and its reducer/gate/route
+ * helpers are PURE (no clock, no IO, no journal read); the gate-evaluation
+ * journaling functions are the one deliberate exception. This module never
+ * dispatches a unit and never writes step rows.
  *
- * ## What is PURE here
- *
- * {@link computeStepWorkList} — given the frozen step plan and a
- * {@link WorkListInput} (params, prior step outputs, gate-loop number + its
- * 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 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
- * ({@link evaluateRoute} and its bookkeeping).
- *
- * ## What does IO here
- *
- * 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 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
- * engine loop's job (`run-workflow.ts` via `completeWorkflowStep`).
+ * See docs/architecture/decisions/0002-unit-reuse-and-input-hash-scope.md for
+ * the full purity-contract design history.
  */
 import { createHash, randomUUID } from "node:crypto";
 import unitPreambleTemplate from "../../assets/prompts/workflow-unit-preamble.md" with { type: "text" };
 import { UsageError } from "../../core/errors.js";
 import { validateJsonSchemaSubset } from "../../core/json-schema.js";
+import { canonicalInputJson, validateInputs } from "../../execution/input-contract.js";
 import { withWorkflowRunsRepo, } from "../../storage/repositories/workflow-runs-repository.js";
 import { canonicalJson as canonicalJsonString } from "../ir/plan-hash.js";
 import { parseReference, resolveReferenceString, } from "../program/expressions.js";
@@ -157,6 +134,54 @@ function truncatedReferenceTarget(reference, scope, resolved) {
     }
     return isTruncatedEvidence(current) ? current : undefined;
 }
+/**
+ * Pre-attempt resolution of a task-composing step's frozen `inputBindings`
+ * (spec docs/plans/specs/p2b-input-bindings.md §3.6, B-31..B-34): a
+ * `{kind:"literal"}` passes through unchanged — its schema was already
+ * checked at FREEZE (`freezeTaskInputBindings`,
+ * `src/workflows/freeze/task-bindings.ts`), so it is never re-validated. A
+ * `{kind:"reference"}` resolves via the SAME {@link resolveStepReference}
+ * every other whole-value position uses, then validates the resolved value
+ * against the binding's own frozen `schema` — a mismatch (or a reference that
+ * fails to resolve at all) fails the WHOLE step here, before
+ * `reserveUnitAttempt` is ever called by the native executor. Absent
+ * `bindings` (the overwhelmingly common case — no `with:` on this step's
+ * target) resolves trivially to `{}` with no scope access at all.
+ */
+function resolveTaskInputBindings(bindings, stepId, scope) {
+    if (!bindings || bindings.length === 0)
+        return { ok: true, values: {} };
+    const values = {};
+    for (const binding of bindings) {
+        if (binding.kind === "literal") {
+            values[binding.name] = binding.value;
+            continue;
+        }
+        const resolved = resolveStepReference(binding.from, scope);
+        if (!resolved.ok) {
+            return {
+                ok: false,
+                error: `Step "${stepId}" input "${binding.name}" reference ${binding.from} failed to resolve: ` +
+                    resolved.error.message,
+            };
+        }
+        const errors = validateInputs({ [binding.name]: { schema: binding.schema, required: false } }, { [binding.name]: resolved.value }, 
+        // Fixed neutral namespace (matches `checkScheduleEntryRunnable`'s
+        // `pathRoot: "inputs"` and the `contractViolation` diagnostics' own
+        // `$`-strip) — NOT `binding.name`, which would double the input name
+        // (`count.count: ...`) since the outer message below already names it.
+        { pathRoot: "inputs" });
+        if (errors.length > 0) {
+            return {
+                ok: false,
+                error: `Step "${stepId}" input "${binding.name}" reference ${binding.from} resolved to a value violating its ` +
+                    `declared schema: ${errors.join("; ")}`,
+            };
+        }
+        values[binding.name] = resolved.value;
+    }
+    return { ok: true, values };
+}
 export function computeStepWorkList(plan, input) {
     const root = plan.root;
     // Route-only steps (YAML `route:`) carry no execution subgraph.
@@ -187,6 +212,19 @@ export function computeStepWorkList(plan, input) {
         }
         resolvedInputs.push({ reference, value: resolved.value });
     }
+    // P2b Lane A2 — pre-attempt resolution of a task-composing step's frozen
+    // `inputBindings` (spec §3.6, B-31..B-34): a `{kind:"literal"}` passes
+    // through unchanged (its schema was already checked at freeze, B-34); a
+    // `{kind:"reference"}` resolves against this SAME scope, then its resolved
+    // value is validated against the binding's own frozen `schema` — a
+    // mismatch fails the WHOLE step here, before `reserveUnitAttempt` is ever
+    // reached (B-32). This runs for every target kind (command/shell/script);
+    // Lane B's delivery consumes the result via `StepWorkUnitContext.taskInputs`
+    // / `taskInputsJson` below.
+    const taskInputsResolution = resolveTaskInputBindings(template.frozenTarget.inputBindings, plan.stepId, scope);
+    if (!taskInputsResolution.ok)
+        return taskInputsResolution;
+    const hasTaskInputs = Object.keys(taskInputsResolution.values).length > 0;
     // Resolve fan-out items: `over` is a single whole-value reference naming
     // its producer explicitly — no ambient key search.
     let items;
@@ -235,7 +273,18 @@ export function computeStepWorkList(plan, input) {
     // An exec unit's budget is frozen on its exec spec (there is no engine to
     // inherit one from); `ir/freeze.ts` resolved it once from unit `timeout:` →
     // `defaults.timeout` → DEFAULT_EXEC_TIMEOUT_MS.
-    const timeoutMs = target.kind === "command" ? (target.runner.timeoutMs ?? null) : target.exec.timeoutMs;
+    const timeoutMs = target.kind === "command"
+        ? (target.runner.timeoutMs ?? null)
+        : target.kind === "child-workflow"
+            ? // A child-workflow target carries no exec spec of its own (§3.5).
+                // computeStepWorkList still builds this unit's context
+                // unconditionally — the child executor (child-workflow.ts,
+                // reached from native-executor.ts's dispatch seam, P3b §3.2) is
+                // what actually drives a child-workflow unit, not this line, so
+                // `null` only needs to be a value this layer can carry, never one
+                // an engine acts on.
+                null
+            : target.exec.timeoutMs;
     // Step-constant exec context: `AKM_PARAMS` / `AKM_INPUTS` depend only on
     // step-level values, so they are serialized ONCE here and shared by every
     // unit. Building them inside the per-unit loop deep-cloned and re-stringified
@@ -245,6 +294,11 @@ export function computeStepWorkList(plan, input) {
     const execInputsJson = frozenExec && resolvedInputs.length > 0
         ? (canonicalJson(Object.fromEntries(resolvedInputs.map((entry) => [entry.reference, entry.value]))) ?? "{}")
         : undefined;
+    // P2b Lane A2 (§3.6): the resolved effective task-composition inputs,
+    // serialized ONCE here (mirrors execParamsJson/execInputsJson above) —
+    // Lane B's delivery (buildUnitPrompt's "## Task inputs" block,
+    // buildExecContextEnv's AKM_TASK_INPUTS) reads both back per unit.
+    const taskInputsJson = hasTaskInputs ? (canonicalJson(taskInputsResolution.values) ?? "{}") : undefined;
     const ctx = {
         plan,
         input,
@@ -258,6 +312,7 @@ export function computeStepWorkList(plan, input) {
         ...(frozenExec ? { frozenExec } : {}),
         ...(execParamsJson !== undefined ? { execParamsJson } : {}),
         ...(execInputsJson !== undefined ? { execInputsJson } : {}),
+        ...(hasTaskInputs ? { taskInputs: taskInputsResolution.values, taskInputsJson } : {}),
     };
     const units = items.map((item, index) => buildStepWorkUnit(ctx, unitIds[index], item, index));
     const concurrency = root.kind === "map" ? root.concurrency : 1;
@@ -277,7 +332,7 @@ export function computeStepWorkList(plan, input) {
  * repo's 220-line function bar.
  */
 function buildStepWorkUnit(ctx, unitId, item, index) {
-    const { plan, input, template, isFanOut, resolvedInputs, target, frozenExec } = ctx;
+    const { plan, input, template, isFanOut, resolvedInputs, target, frozenExec, taskInputs } = ctx;
     // Gate loops (>= 2) journal under `<unitId>~l<loop>` so loop 1's rows are
     // never clobbered; the content-derived identity (and the prompt's
     // {{UNIT_ID}}) stays the base id.
@@ -302,6 +357,9 @@ function buildStepWorkUnit(ctx, unitId, item, index) {
             params: input.params,
             ...(isFanOut ? { item, itemIndex: index } : {}),
             ...(resolvedInputs.length > 0 ? { inputs: resolvedInputs } : {}),
+            // P2b Lane B (§4.2, B-38/B-39): the composed task's resolved
+            // `inputBindings`, when non-empty — see StepWorkUnitContext.taskInputs.
+            ...(taskInputs && Object.keys(taskInputs).length > 0 ? { taskInputs } : {}),
             ...(input.gateFeedback ? { gateFeedback: input.gateFeedback } : {}),
             ...(template.schema ? { schema: template.schema } : {}),
             instructions: template.instructions,
@@ -324,6 +382,10 @@ function buildStepWorkUnit(ctx, unitId, item, index) {
         ...(template.retry ? { retry: template.retry } : {}),
         onError: template.onError,
         ...(template.isolation ? { isolation: template.isolation } : {}),
+        // P3b §3.3 step 2: the SAME resolved `with:` bindings `taskInputs` already
+        // carries, exposed under the name `child-workflow.ts`'s drive contract
+        // reads. Absent (never `{}`) when the step binds nothing.
+        ...(taskInputs && Object.keys(taskInputs).length > 0 ? { childParams: taskInputs } : {}),
         prompt,
         inputHash,
     };
@@ -345,7 +407,8 @@ function buildStepWorkUnit(ctx, unitId, item, index) {
  *
  * SIZE is not bounded here, on purpose. A workflow artifact has no bound
  * comparable to an OS environment entry, so `AKM_INPUTS` (and `AKM_PARAMS` /
- * `AKM_ITEM`) can serialize past what `execve` accepts and make PROCESS CREATION
+ * `AKM_ITEM` / `AKM_TASK_INPUTS`) can serialize past what `execve` accepts and
+ * make PROCESS CREATION
  * fail with a bare `E2BIG`. The check belongs at the spawn boundary, where the
  * failure can be journaled as a unit outcome with an actionable message naming
  * the variable: `checkExecContextSize` in `exec/exec-unit.ts`, against
@@ -369,54 +432,42 @@ function buildExecContextEnv(args) {
     }
     if (ctx.execInputsJson !== undefined)
         env.AKM_INPUTS = ctx.execInputsJson;
+    // P2b Lane B (spec §4.1, B-35/B-36/B-39, B-N1): ONE variable carrying the
+    // composed task's effective `inputBindings` as canonical JSON — never one
+    // var per input. Absent when the frozen target carries no `inputBindings`
+    // or every resolved value is empty. Sizing is enforced by the SAME generic
+    // `checkExecContextSize` loop as every other `AKM_*` entry (exec-unit.ts) —
+    // no change there, the roster is just longer by one name (B-37).
+    if (ctx.taskInputsJson !== undefined)
+        env.AKM_TASK_INPUTS = ctx.taskInputsJson;
     return env;
 }
 /**
- * The 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. `canonicalJsonString` sorts keys recursively, so the
- * preimage is order-independent, and this is the ONE place a unit's inputHash
- * is computed (every caller goes through {@link computeStepWorkList}) — 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 artifacts + the params snapshot — instead of a
- * resolved/spliced prompt string, since there is no more splicing.
+ * The canonical dispatch-input envelope: every field here is an input that
+ * changes what the backend is actually asked to do, so a completed unit is
+ * reused ONLY when all of them match. `env` carries names only, never
+ * resolved secret values. `retry`/`onError` are deliberately excluded — they
+ * govern failed-unit re-dispatch, not a completed unit's inputs/output.
+ * `gateFeedback` is included conditionally (a gate retry is a materially
+ * different ask). `taskInputs` is likewise included conditionally (R-R15,
+ * `hashVersion` 7): a reference binding's RESOLVED value reaches the unit's
+ * prompt / `AKM_TASK_INPUTS` / `childParams`, so a changed upstream value is a
+ * materially different ask even though the binding's authored shape inside
+ * `frozenTarget` is unchanged — hashing it makes a resume whose journaled
+ * upstream output was altered fail loudly as replay divergence instead of
+ * silently reusing the stale row. The key is absent for a unit whose target
+ * carries no `inputBindings`, so a binding-free unit's preimage keeps the same
+ * shape it had (only the version fields moved 6 → 7). This is the ONE place a
+ * unit's inputHash is computed.
  *
- * Included beyond the template/runner/model/schema baseline: resolved
- * timeoutMs, named environment bindings, and isolation —
- * each reaches dispatch 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. Replay-safe: feedback is re-derived from the journaled
- * gate decision, so a resumed retry re-hashes identically.
- *
- * Command targets carry their frozen argv/script/cwd/timeout identity in the
- * same target slot used by agent, SDK, and direct-LLM work. The complete
- * current target is hashed once, so a completed unit is reused only for the
- * exact durable request that originally produced it.
- *
- * Ambient config is deliberately excluded because it is not consulted during
- * execution. The frozen target and named environment bindings are the runtime
- * identity boundary; only the values behind those names remain live.
+ * See docs/architecture/decisions/0002-unit-reuse-and-input-hash-scope.md for
+ * the full field-by-field inclusion/exclusion rationale (reviewer finding #1).
  */
 function computeUnitInputHash(ctx, item) {
     return createHash("sha256")
-        .update("akm.workflow.unit\0v5\0")
+        .update("akm.workflow.unit\0v7\0")
         .update(canonicalJsonString({
-        hashVersion: 5,
+        hashVersion: 7,
         role: "unit",
         stepId: ctx.plan.stepId,
         nodeId: ctx.template.id,
@@ -428,6 +479,7 @@ function computeUnitInputHash(ctx, item) {
         environment: ctx.template.environment,
         schema: ctx.template.schema ?? null,
         isolation: ctx.template.isolation ?? "none",
+        ...(ctx.taskInputs !== undefined ? { taskInputs: ctx.taskInputs } : {}),
         ...(ctx.input.gateFeedback ? { gateFeedback: ctx.input.gateFeedback } : {}),
     }))
         .digest("hex");
@@ -442,7 +494,7 @@ function computeUnitInputHash(ctx, item) {
  * here.
  */
 export function buildUnitPrompt(input) {
-    const { runId, stepId, unitId, params, itemIndex, item, inputs, gateFeedback, schema, instructions } = input;
+    const { runId, stepId, unitId, params, itemIndex, item, inputs, taskInputs, 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 "$&").
@@ -460,6 +512,15 @@ export function buildUnitPrompt(input) {
     const inputsBlock = inputs && inputs.length > 0
         ? `\n\n## Declared inputs\n${inputs.map((i) => `### ${i.reference}\n${safeJson(i.value)}`).join("\n\n")}`
         : "";
+    // P2b Lane B (spec §4.2, B-38/B-39, B-N2): the composed task's resolved
+    // `inputBindings`, as a structured fenced JSON block — the same "attached
+    // context, never a splice" mechanism as itemBlock/inputsBlock above.
+    // `canonicalInputJson` (sorted keys) matches the AKM_TASK_INPUTS env var's
+    // own serialization, so the effective-inputs value reads identically on
+    // every delivery surface. Absent (or empty) appends nothing (B-39).
+    const taskInputsBlock = taskInputs && Object.keys(taskInputs).length > 0
+        ? `\n\n## Task inputs\nThe composed task's declared inputs resolved to:\n\`\`\`json\n${canonicalInputJson(taskInputs)}\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.
@@ -474,7 +535,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}${itemBlock}${inputsBlock}${gateBlock}${schemaDirective}`;
+    return `${preamble}\n${instructions}${itemBlock}${inputsBlock}${taskInputsBlock}${gateBlock}${schemaDirective}`;
 }
 /**
  * Content-derived unit identity (module doc): `<node_id>:<sha256>` for a
@@ -706,7 +767,28 @@ export function reduceStepOutcomes(plan, reducer, isFanOut, onError, units) {
             artifactSchemaFailure = true;
         }
     }
-    return { ok, units, evidence, summary, ...(artifactSchemaFailure ? { artifactSchemaFailure: true } : {}) };
+    // P3b §3.4: a composed child workflow that blocked is carried on the
+    // failed unit's LIVE-ONLY `childRun` field (child-workflow.ts's
+    // driveChildWorkflowUnit). Surfaced here, unconditionally on the unit
+    // list, so `finalizeExecutedStep` can check it before deciding whether
+    // this step's failure is retryable — an `onError: "continue"` step that
+    // tolerates the failure (`ok` stays true) never reaches that check at all.
+    const blockedChildUnit = failed.find((u) => u.failureReason === "child_workflow_blocked" && u.childRun !== undefined);
+    const childBlocked = blockedChildUnit?.childRun
+        ? {
+            childRunId: blockedChildUnit.childRun.runId,
+            childRef: blockedChildUnit.childRun.ref,
+            childStepId: blockedChildUnit.childRun.currentStepId,
+        }
+        : undefined;
+    return {
+        ok,
+        units,
+        evidence,
+        summary,
+        ...(artifactSchemaFailure ? { artifactSchemaFailure: true } : {}),
+        ...(childBlocked ? { childBlocked } : {}),
+    };
 }
 /**
  * The reduced outcome of a step whose fan-out list resolved to EMPTY (`over: []`
@@ -1183,6 +1265,56 @@ async function blockFinalizedStep(input, cause) {
     });
     return { kind: "judge-failed", summary };
 }
+/**
+ * §3.4's exact `blockStepForChildWorkflow` notes — the ONE place the
+ * blocked-child resume sequence is worded, mirroring {@link judgeFailureNotes}.
+ * Two properties this wording pins (each its own test): the CHILD is resumed
+ * FIRST, and the PARENT's own re-drive is what advances it (the child drive
+ * never calls `resumeWorkflowRun` itself, row A-22); the notes name the child
+ * run id and both commands verbatim, so the text renderer needs no change
+ * (B-N15 — Lane A touches no output module).
+ */
+function childWorkflowBlockedNotes(runId, stepId, childRunId, childRef, childStepId) {
+    return (`Step "${stepId}" composes child workflow run ${childRunId} (${childRef}), ` +
+        `which is blocked at its own step "${childStepId ?? "(unknown)"}". Nothing in this run advances ` +
+        `until the child does — a gate is a gate for a child workflow too, so \`akm\` will ` +
+        `not resume it for you. Clear it with \`akm workflow resume ${childRunId}\`, then ` +
+        `\`akm workflow resume ${runId}\` and \`akm workflow run ${runId}\` to ` +
+        `continue: re-driving the parent drives the resumed child.`);
+}
+/**
+ * Complete a step `blocked` because the child workflow it composes is
+ * blocked, and return the notes written (P3b §3.4). Sits beside
+ * {@link blockStepForJudgeFailure} — the SAME shape of "infrastructure-like"
+ * block: the step is completed `blocked`, and `akm workflow resume` is what
+ * clears it (of the CHILD first, then the parent) rather than an automatic
+ * in-step re-dispatch.
+ */
+export async function blockStepForChildWorkflow(input) {
+    const notes = childWorkflowBlockedNotes(input.runId, input.stepId, input.childRunId, input.childRef, input.childStepId);
+    await completeWorkflowStep({
+        runId: input.runId,
+        stepId: input.stepId,
+        status: "blocked",
+        notes,
+        ...(input.evidence !== undefined ? { evidence: input.evidence } : {}),
+        ...(input.leaseHolder !== undefined ? { leaseHolder: input.leaseHolder } : {}),
+    });
+    return notes;
+}
+/** The finalize path's child-blocked write: the executed units' evidence (the composing unit) is preserved. */
+async function blockFinalizedStepForChildWorkflow(input, childBlocked) {
+    const summary = await blockStepForChildWorkflow({
+        runId: input.runId,
+        stepId: input.stepId,
+        childRunId: childBlocked.childRunId,
+        childRef: childBlocked.childRef,
+        childStepId: childBlocked.childStepId,
+        evidence: input.result.evidence,
+        ...(input.leaseHolder !== undefined ? { leaseHolder: input.leaseHolder } : {}),
+    });
+    return { kind: "child-blocked", summary };
+}
 /**
  * Perform ONE completion attempt for an executed step:
  *
@@ -1210,6 +1342,12 @@ export async function finalizeExecutedStep(input) {
     const { runId, workflowRef, stepId, stepPlan, completionCriteria, gateLoop, loopsRemaining, result } = input;
     const lease = input.leaseHolder !== undefined ? { leaseHolder: input.leaseHolder } : {};
     if (!result.ok) {
+        // P3b §3.4: a composed child workflow that blocked is never fed into the
+        // bounded gate loop — a gate is a gate for a child workflow too. Checked
+        // FIRST, before the artifactSchemaFailure retry branch below.
+        if (result.childBlocked) {
+            return blockFinalizedStepForChildWorkflow(input, result.childBlocked);
+        }
         // Typed-artifact mismatch with loop budget left: regenerate-with-errors
         // (the validation errors become the next loop's feedback). No judge ran, so
         // no gate row is journaled for this attempt.
@@ -1290,10 +1428,14 @@ export async function finalizeExecutedStep(input) {
                     engine: engineName,
                     model: gateTarget.request.model?.resolved ?? null,
                     runner: gateTarget.runner.kind,
+                    // The gate prefix rides the unit prefix's version — unit and gate
+                    // hashVersion are one vocabulary (p3a §0.1; the R-R15 fix moved
+                    // both 6 → 7 in lockstep even though the gate preimage's own
+                    // fields are unchanged).
                     inputHash: createHash("sha256")
-                        .update("akm.workflow.gate\0v5\0")
+                        .update("akm.workflow.gate\0v7\0")
                         .update(canonicalJsonString({
-                        hashVersion: 5,
+                        hashVersion: 7,
                         dispatch: gateTarget,
                         invocation: null,
                         prompt,

package/dist/workflows/exec/unit-dispatch.js

@@ -35,12 +35,71 @@ export function prepareWorkflowExecution(request, prompt = request.prompt) {
 function message(err) {
     return err instanceof Error ? err.message : String(err);
 }
+/**
+ * The `eventSource` value `dispatchWorkflowExecution` should forward into
+ * `dispatchLoweredExecutionRequest`'s options, or `undefined` to forward
+ * nothing.
+ *
+ * Precedence fix (P1b Lane C code review, round 2). The gap-fix originally
+ * forwarded `request.eventSource` unconditionally.
+ * `dispatchLoweredExecutionRequest` applies a forwarded value as `env: {
+ * ...lowered.options.env, AKM_EVENT_SOURCE: eventSource }`
+ * (execution-lowering.ts:998-1001) — an unconditional override of that one
+ * key — and `lowered.options.env` IS the unit's own authored/resolved `env:`
+ * binding (`request.env`, folded in by `prepareWorkflowExecution` above via
+ * `request.runtime.environment`), so the unconditional forward let the
+ * provenance stamp win over an authored `env: { AKM_EVENT_SOURCE: ... }`
+ * binding. That inverts the precedence pre-P1b had (the child env was built
+ * from ambient passthrough with `options.env` — the authored binding —
+ * applied AFTER it, at highest precedence, in `buildChildEnv`/`spawn.ts`) and
+ * disagrees with the sibling "script"/"shell" arm: `exec-unit.ts`'s own
+ * `childEnv` stamps its allowlisted base only when the name is absent there,
+ * strictly BEFORE the bindings overlay runs, so an authored binding always
+ * wins there. Gating the forward on `request.env` not already binding the
+ * name restores agreement: an authored binding leaves `eventSource`
+ * unforwarded (so the merge above never touches the key, and the authored
+ * value in `lowered.options.env` stands), while an absent binding still
+ * forwards the resolved value exactly as before.
+ *
+ * Exported so this precedence rule is pinned directly:
+ * `dispatchWorkflowExecution` itself has no injectable
+ * `runAgent`/`executeRunner`/`chat` seam to exercise the decision end-to-end
+ * without a live agent/LLM dispatch (see the P1b spec's Review log, which
+ * records the same constraint for the gap-fix this corrects).
+ */
+export function forwardedDispatchEventSource(request) {
+    if (request.eventSource === undefined)
+        return undefined;
+    if (request.env?.AKM_EVENT_SOURCE !== undefined)
+        return undefined;
+    return request.eventSource;
+}
 /**
  * Dispatch one frozen workflow engine call through the common prepared/lowered
  * seam. Credential materialization happens inside the final dispatch only.
  */
 export async function dispatchWorkflowExecution(request, feedback) {
     const prompt = feedback ? `${request.prompt}\n\n${feedback}` : request.prompt;
+    // B-N11 (P3b, spec docs/plans/specs/p3b-child-executor.md §1.6): an
+    // internal-invariant guard, not a user-facing one. `dispatchJournaledAttempt`
+    // (native-executor.ts, P3b §3.2) routes a `child-workflow` unit to the child
+    // executor (child-workflow.ts) BEFORE dispatch is ever reached, so arriving
+    // HERE with one means that seam was BYPASSED — an engine routing bug, never
+    // a not-yet-implemented feature (that premise, P3a Review log R8's, is gone
+    // now that P3b ships a production caller). A plain `Error` naming the seam
+    // that should have been reached instead, not a `UsageError`: nothing a user
+    // can author reaches this line once the seam exists, so there is no
+    // user-facing code to carry. Kept here, rather than deleted outright, so a
+    // bypassed seam still fails closed instead of falling into the generic
+    // `kind !== "command"` guard below, which would blame a legitimate target
+    // kind as "not a command target" — the exact false, unhelpful message R8
+    // was opened to remove.
+    if (request.frozenTarget.kind === "child-workflow") {
+        throw new Error(`unit ${JSON.stringify(request.unitId)} targets child workflow ${JSON.stringify(request.frozenTarget.ref)}, ` +
+            "but reached dispatchWorkflowExecution directly. The child-workflow dispatch seam " +
+            "(src/workflows/exec/child-workflow.ts) should have routed it before dispatch was ever reached — " +
+            "this is an engine routing bug, not a problem with the workflow itself.");
+    }
     if (request.frozenTarget.kind !== "command") {
         throw new ConfigError(`unit ${JSON.stringify(request.unitId)} is not a command target.`, "INVALID_CONFIG_FILE");
     }
@@ -68,12 +127,25 @@ export async function dispatchWorkflowExecution(request, feedback) {
     }
     let result;
     try {
+        const eventSource = forwardedDispatchEventSource(request);
         result = await dispatchLoweredExecutionRequest(lowered, {
             runOptions: {
                 stdio: "captured",
                 parseOutput: "text",
                 ...(request.signal ? { signal: request.signal } : {}),
             },
+            // Gap fix (P1b Lane C code review, spec §5.2(2)); precedence-gated
+            // (round 2, see forwardedDispatchEventSource above): forward the
+            // resolved provenance event source so an "agent"/"sdk" unit's
+            // dispatched child env carries AKM_EVENT_SOURCE too, not only a
+            // "script"/"shell" unit's — but only when the unit's own authored
+            // `env:` binding does not already set the name, so an authored binding
+            // still wins, mirroring exec-unit.ts's childEnv guard.
+            // dispatchLoweredExecutionRequest applies a forwarded value as exactly
+            // one child-env key (execution-lowering.ts:998-1001) — the same
+            // mechanism the R-07 command-arm fix (command-execution.ts) already
+            // uses.
+            ...(eventSource !== undefined ? { eventSource } : {}),
         });
     }
     catch (err) {

package/dist/workflows/freeze/child-output-references.js

@@ -0,0 +1,94 @@
+// 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/.
+/**
+ * The freeze-time child-output reference check (P3b, spec docs/plans/specs/
+ * p3b-child-executor.md §4.4, rows B-28…B-32).
+ *
+ * A parent step may read `steps.<child>.output(.<name>)*` where step
+ * `<child>`'s frozen target is `kind: "child-workflow"`. Only the FIRST path
+ * segment is a freeze-time concern: it must name one of the child's declared
+ * `outputs:` names, or — when the child declares none — `runId` or `status`
+ * (the default `workflowRunExportedResult` shape, `runtime/run-outputs.ts`).
+ * A reference AT `steps.<child>.output` with no further segment always
+ * accepts — it names the whole exported object. Anything deeper resolves (and,
+ * if wrong, fails) at pre-attempt through the existing, unchanged resolver —
+ * the value's shape past the first segment is unconstrained unless the
+ * output declares a `schema:`.
+ *
+ * Pure over the frozen step list — no IO, no config.
+ */
+import { UsageError } from "../../core/errors.js";
+import { formatReference, parseReference } from "../program/expressions.js";
+/** The frozen target a step's root unit (or map template) dispatches, if any. */
+function stepFrozenTarget(step) {
+    const root = step?.root;
+    if (!root)
+        return undefined;
+    const unit = root.kind === "map" ? root.template : root;
+    return unit.frozenTarget;
+}
+/** Every reference string a step's `inputs[]`, `map.over`, `route.input`, and reference-kind `inputBindings[].from` carry. */
+function collectReferenceSites(step) {
+    const sites = [];
+    const push = (reference) => {
+        sites.push({ stepId: step.stepId, reference });
+    };
+    if (step.route)
+        push(step.route.input);
+    const root = step.root;
+    if (root) {
+        const unit = root.kind === "map" ? root.template : root;
+        if (root.kind === "map")
+            push(root.over);
+        for (const reference of unit.inputs ?? [])
+            push(reference);
+        const bindings = unit.frozenTarget.inputBindings ?? [];
+        for (const binding of bindings) {
+            if (binding.kind === "reference")
+                push(binding.from);
+        }
+    }
+    return sites;
+}
+/** The names a `child-workflow` target's own exported result carries at its first segment. */
+function acceptedFirstSegments(target) {
+    const declared = target.frozenPlan.outputs;
+    return declared ? Object.keys(declared) : ["runId", "status"];
+}
+function exportsDescription(target) {
+    const declared = target.frozenPlan.outputs;
+    return declared ? `outputs: ${Object.keys(declared).join(", ")}` : "only {runId, status} — it declares no `outputs:`";
+}
+function checkSite(site, stepsById) {
+    const parsed = parseReference(site.reference);
+    if (!parsed.ok || parsed.expr.kind !== "stepOutput")
+        return;
+    const targetStep = stepsById.get(parsed.expr.stepId);
+    const frozenTarget = stepFrozenTarget(targetStep);
+    if (!frozenTarget || frozenTarget.kind !== "child-workflow")
+        return;
+    const first = parsed.expr.path[0];
+    if (first === undefined)
+        return; // bare steps.<child>.output — the whole exported object, always accepted.
+    const accepted = acceptedFirstSegments(frozenTarget);
+    if (typeof first === "string" && accepted.includes(first))
+        return;
+    throw new UsageError(`Workflow step ${site.stepId} reads "${formatReference(parsed.expr)}", but child workflow ${frozenTarget.ref} ` +
+        `exports ${exportsDescription(frozenTarget)}. Declare the output in the child's \`outputs:\` frontmatter, or ` +
+        `reference one of the names above.`, "COMPOSITION_INVALID", `Fix the reference to name one of: ${accepted.join(", ")} — or add the missing name to ${frozenTarget.ref}'s ` +
+        "own `outputs:` frontmatter.");
+}
+/**
+ * Assert every reference into a `child-workflow`-targeted step's output
+ * names an output the child actually exports. Throws `UsageError`
+ * (`COMPOSITION_INVALID`) on the first violation found.
+ */
+export function assertChildOutputReferences(steps) {
+    const stepsById = new Map(steps.map((step) => [step.stepId, step]));
+    for (const step of steps) {
+        for (const site of collectReferenceSites(step)) {
+            checkSite(site, stepsById);
+        }
+    }
+}