akm-cli 0.9.2-alpha.4 → 0.9.2

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

@@ -3,44 +3,18 @@
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 /**
  * The `exec` unit runner — the ONE place a frozen workflow spawns a shell
- * command as a unit. The invariants it exists to hold:
+ * command as a unit: argv-only (never a shell string), non-blocking,
+ * detached with a SIGTERM→SIGKILL ladder against the whole process group,
+ * cwd-contained by a resolved-path recheck, resource-bounded (timeout,
+ * output bytes, context size), and allowlisted-environment (see
+ * {@link childEnv}). `env` values reaching this module are already resolved
+ * from `env:` bindings by NAME — the caller scrubs the outcome with
+ * `redactUnitOutcome` before anything is journaled. A LEAF module by
+ * layering (Node built-ins, `core/spawn-env`, `core/subprocess`, `core/warn`,
+ * the import-free `workflows/resource-limits` only).
  *
- *   - ARGV, NEVER A SHELL STRING. {@link IrExecSpec.command} is an argv ARRAY
- *     and the format has no shell-string spelling at all; the child is spawned
- *     directly, so `;`, `|`, `&&`, `$(…)`, backticks, `>` and `*` are inert
- *     literal argument BYTES. A workflow that wants a pipeline names the
- *     interpreter itself (`["bash", "-lc", "a | b"]`), visibly in frontmatter.
- *   - NON-BLOCKING. Everything on this path is async. A synchronous call here
- *     blocks the event loop and with it every concurrently-scheduled unit, the
- *     run's lease heartbeat, and abort handling.
- *   - NO LEAKED CHILDREN. {@link runManagedSubprocess} spawns DETACHED and runs
- *     a SIGTERM→SIGKILL ladder against the whole process group, so `--timeout`
- *     and Ctrl-C really do stop a running command and its descendants.
- *   - CONTAINMENT. `exec.cwd` is relative and `..`-free by construction (parser
- *     and frozen-plan decoder), which is necessary but not sufficient: a
- *     subdirectory can be a symlink. The RESOLVED path is therefore re-checked
- *     against the RESOLVED base immediately before spawning.
- *   - BOUNDED SPEND. A command is arbitrary code with no resource discipline of
- *     its own, so each resource it spends on akm's behalf has a ceiling in
- *     `workflows/resource-limits.ts`: wall clock ({@link DEFAULT_EXEC_TIMEOUT_MS}
- *     or the authored `timeout:`), retained output
- *     ({@link WORKFLOW_MAX_EXEC_OUTPUT_BYTES} per pipe) and the context
- *     environment ({@link execContextLimits}, checked BEFORE the spawn so an
- *     oversized artifact yields an actionable akm error, not a bare `E2BIG`).
- *   - ALLOWLISTED ENVIRONMENT. The child does NOT inherit akm's environment: it
- *     starts EMPTY and receives exactly {@link EXEC_DEFAULT_ENV_PASSTHROUGH}
- *     plus the unit's `exec.passEnv`, then the resolved `env:` bindings, then
- *     the engine-authored `AKM_*` context. See {@link childEnv}.
- *
- * Secrets: `env` values reaching this module are already resolved from `env:`
- * bindings by NAME (`resolveEnvBinding`) — the plan never carries inline secrets
- * and the input hash only ever carries names. The caller scrubs the outcome with
- * `redactUnitOutcome` BEFORE anything is journaled, which is why this module may
- * return raw stdout/stderr diagnostics without knowing anything about redaction.
- *
- * Layering: a LEAF. Node built-ins, `core/spawn-env`, `core/subprocess`,
- * `core/warn` and the import-free `workflows/resource-limits` (plus erased
- * types) only, so the executor can consume it without opening an import cycle.
+ * See docs/architecture/decisions/0003-child-env-allowlist-and-provenance.md
+ * for the full per-invariant design history.
  *
  * @module workflows/exec/exec-unit
  */
@@ -65,58 +39,17 @@ import { execContextLimits, utf8Bytes, WORKFLOW_EXEC_OUTPUT_TRUNCATED_MARKER, WO
 const EXEC_STDERR_DIAGNOSTIC_CLIP = WORKFLOW_UNIT_DIAGNOSTIC_CLIP - 500;
 /**
  * The DEFAULT environment allowlist for an exec unit's child — the single
- * definition of the EXEC list (the docs describe it, the tests assert against
- * it, and `exec.passEnv` extends it per unit). The win32 process-creation
- * names are not re-spelled here: they are spread from
- * {@link WIN32_SPAWN_ENV_FLOOR}, which owns them.
- *
- * The child starts from an EMPTY environment and receives only these names,
- * matching how an agent harness child is already built
- * (`profile.envPassthrough` → `collectAllowlistedEnv`) — and literally
- * extending the same {@link COMMON_SPAWN_ENV_PASSTHROUGH} baseline those
- * profiles start from, so the two child-spawn allowlists share one floor.
- * Every entry earns its place by being load-bearing for ordinary commands on
- * some supported platform:
- *
- *   - `PATH`        — command resolution. Without it only an absolute `argv[0]`
- *                     can ever be spawned.
- *   - `HOME`        — the config/cache root essentially every toolchain reads
- *                     (git, npm, bun, cargo, ssh). Absent, tools fall back to
- *                     `/` or fail outright.
- *   - `USER`, `LOGNAME` — process identity; git and ssh read them to attribute
- *                     and authenticate.
- *   - `SHELL`       — read by tools that re-exec a login shell for the user's
- *                     own environment (an explicit `["bash", "-lc", …]` argv
- *                     does not need it, but `git`'s pagers/editors do).
- *   - `LANG`, `LC_ALL`, `LC_CTYPE` — text encoding. Without a locale a command
- *                     falls back to the C locale and mangles non-ASCII stdout,
- *                     which IS this unit's artifact.
- *   - `TERM`        — some CLIs abort or emit raw escape bytes with no TERM.
- *   - `TZ`          — timestamps a command prints would otherwise silently
- *                     switch to the host default.
- *   - `TMPDIR`      — POSIX scratch space; absent, tools write to `/tmp` or
- *                     fail on read-only hosts.
- *   - {@link WIN32_SPAWN_ENV_FLOOR} — what Windows itself requires of any
- *                     child (process creation, command resolution, and the
- *                     win32 analogues of `HOME`/`TMPDIR`). Spread in rather
- *                     than re-spelled: `spawnEnvNamesFor` appends the same
- *                     names on win32, and two hand-written copies of one OS
- *                     requirement is exactly how a floor drifts.
- *   - `APPDATA`, `LOCALAPPDATA` — Windows config/cache roots (npm, bun, git).
- *   - `ProgramData`, `ProgramFiles` — machine-wide install roots that Windows
- *                     toolchain shims resolve against. These four are NOT on
- *                     the floor (a child is creatable without them), so an
- *                     arbitrary shell command asks for them here.
- *   - `AKM_EVENT_SOURCE` — provenance, never a secret: an exec unit that calls
- *                     `akm` must record machine traffic rather than user
- *                     demand, exactly as the agent passthrough list does
- *                     (`integrations/agent/profiles.ts`, DRIFT-6).
+ * definition of the EXEC list; `exec.passEnv` extends it per unit. Extends
+ * {@link COMMON_SPAWN_ENV_PASSTHROUGH} (the same baseline agent-harness
+ * children use) plus POSIX/Windows names load-bearing for ordinary commands
+ * (PATH, HOME, USER/LOGNAME, SHELL, locale, TERM, TZ, TMPDIR, the
+ * {@link WIN32_SPAWN_ENV_FLOOR}, Windows toolchain roots) and
+ * `AKM_EVENT_SOURCE` (provenance, DRIFT-6). Deliberately ABSENT and reachable
+ * only through `exec.passEnv` / `env:`: credentials, cloud/CI vars, and the
+ * proxy family.
  *
- * Deliberately ABSENT and reachable only through `exec.passEnv` / `env:`:
- * credentials of every kind, cloud/CI vars, and the proxy
- * family (`HTTP_PROXY` & friends) — proxy URLs routinely embed credentials,
- * which is why akm's redaction policy already treats URL-shaped passthrough
- * values as credential-bearing.
+ * See docs/architecture/decisions/0003-child-env-allowlist-and-provenance.md
+ * for the per-entry rationale and why the default is an allowlist at all.
  */
 export const EXEC_DEFAULT_ENV_PASSTHROUGH = [
     // PATH, HOME, USER, LANG, LC_ALL, TERM, TMPDIR, AKM_EVENT_SOURCE
@@ -139,57 +72,19 @@ export const EXEC_DEFAULT_ENV_PASSTHROUGH = [
 /**
  * Run one exec unit and map its process outcome onto the dispatch vocabulary:
  * non-zero exit → `non_zero_exit`, wall-clock expiry → `timeout`, cancellation
- * → `aborted`, a child that never started → `spawn_failed`. All four are
- * pre-existing `AgentFailureReason` members, so `retry.on` keeps working
- * unchanged. The out-of-taxonomy `exec_cwd_escape`, `exec_output_limit`,
- * `exec_context_too_large` and `exec_capture_incomplete` are deliberate: each is
- * tampering, a runaway, an authoring bug, or work that ALREADY RAN — never a
- * transient — so no `retry.on` value can ever re-dispatch one.
- *
- * ## An INCOMPLETE STDOUT capture is a failure, never a partial artifact
- *
- * `exitCode === 0` is not on its own proof that stdout was fully read: a pipe
- * can error, and the stream-drain timeout can fire while the command LEADER has
- * already exited 0 because a background descendant still holds the stdout fd
- * open. Both leave a PREFIX, and promoting it would hand the next step, the gate
- * judge and `steps.<id>.output` a silently truncated artifact. So the unit fails
- * instead, through the same shared classifier (`streamCaptureFailure`) the agent
- * spawn path uses.
- *
- * Only STDOUT is fatal here. stderr is a diagnostic channel that never
- * contributes to the artifact, so a stderr drain that did not finish leaves the
- * unit's actual result — a completed command, a fully captured stdout — intact;
- * failing it would throw away a valid artifact over a lost log tail. The agent
- * path classifies both pipes because there stderr genuinely feeds its
- * diagnostics; the difference lives in the CALLERS, not in the shared
- * classifier.
- *
- * The stdout reason is `exec_capture_incomplete`, deliberately OUTSIDE the
- * `retry.on` taxonomy, for the same reason `journal_write_failed` is: the
- * command RAN TO COMPLETION and exited 0 — what failed is akm's record of it. A
- * retryable reason here would let `retry.on: [spawn_failed]` re-dispatch
- * byte-identical argv for a command that already deployed, already published,
- * already migrated. `spawn_failed` keeps its documented meaning — the child
- * never started.
+ * → `aborted`, a child that never started → `spawn_failed` (all pre-existing
+ * `AgentFailureReason` members, so `retry.on` keeps working). The
+ * out-of-taxonomy `exec_cwd_escape`, `exec_output_limit`,
+ * `exec_context_too_large` and `exec_capture_incomplete` are deliberate: each
+ * is tampering, a runaway, an authoring bug, or work that ALREADY RAN — never
+ * a transient — so no `retry.on` value can ever re-dispatch one. An
+ * INCOMPLETE stdout capture is always a failure, never a partial artifact;
+ * output OVERFLOW past {@link WORKFLOW_MAX_EXEC_OUTPUT_BYTES} does not fail a
+ * command that otherwise passed unless the unit declared an `output:` schema
+ * (a truncated JSON prefix cannot parse).
  *
- * ## Output OVERFLOW does not fail a command that passed
- *
- * Crossing {@link WORKFLOW_MAX_EXEC_OUTPUT_BYTES} is a different condition: the
- * reader DID drain the pipe to its end, it just stopped RETAINING, so the child
- * never blocked and its exit code is real. Failing a passing-but-chatty test
- * suite over its log volume would be a tripwire, so overflow splits by what the
- * unit PROMISED about its output:
- *
- *   - NO declared `output:` schema → success, with the artifact carrying a
- *     {@link WORKFLOW_EXEC_OUTPUT_TRUNCATED_MARKER} block naming both byte
- *     counts, so truncated text can never pass for complete text.
- *   - a declared `output:` schema → `exec_output_limit`: stdout must parse as
- *     EXACTLY one JSON value, a truncated prefix cannot, and promoting it would
- *     corrupt every downstream reference to the typed artifact.
- *
- * stderr overflow never fails anything: stderr is a diagnostic channel, and
- * {@link EXEC_STDERR_DIAGNOSTIC_CLIP} already bounds and marks what reaches the
- * journal.
+ * See docs/architecture/decisions/0003-child-env-allowlist-and-provenance.md
+ * for the full capture/overflow reasoning.
  */
 export async function runExecUnit(input) {
     const cwd = await resolveExecCwd(input);
@@ -201,7 +96,7 @@ export async function runExecUnit(input) {
     const result = await runManagedSubprocess([...input.exec.command], {
         capture: true,
         cwd: cwd.path,
-        env: childEnv(input.exec, input.env, input.context),
+        env: childEnv(input.exec, input.env, input.context, input.eventSource),
         timeoutMs: input.timeoutMs,
         // stdout IS this unit's artifact, so RETENTION is BOUNDED: an unbounded
         // capture is memory the akm process spends on a command's behalf with no
@@ -457,40 +352,25 @@ async function isExistingDirectory(candidate) {
     }
 }
 /**
- * The child's environment, in three layers with fixed precedence:
- *
- *   1. the BASE — {@link EXEC_DEFAULT_ENV_PASSTHROUGH} plus the unit's
- *      `exec.passEnv` names;
- *   2. the unit's resolved `env:` bindings;
- *   3. the engine-authored `AKM_*` context, LAST so a workflow-supplied binding
- *      can never shadow the ids/item the engine is telling the command the
- *      truth about.
- *
- * ## Why the default is an allowlist
- *
- * Not because it stops an attacker: a command that runs at all can read the
- * same credentials off disk that the environment would have handed it, and a
- * workflow source is executed code either way (`docs/guides/run-workflows.md`,
- * "workflow sources are executed code"). The allowlist earns its place for
- * three narrower, real reasons:
- *
- *   - it bounds ACCIDENTAL exposure — the ambient shell of whoever ran
- *     `akm workflow run` (or the CI job that did) routinely carries tokens for
- *     unrelated services, and a third-party workflow step that merely prints
- *     its environment, or a tool that ships one in a crash report, should not
- *     get them for free;
- *   - it makes the environment surface EXPLICIT and REVIEWABLE — what a
- *     command can see is this constant plus lines in the frontmatter diff,
- *     rather than "whatever the invoking shell happened to export";
- *   - it matches the convention akm already applies to spawned children —
- *     `profile.envPassthrough` in `integrations/agent/spawn.ts` has always
- *     built agent-harness children this way, and the SAME
- *     {@link collectAllowlistedEnv} does it here, so there is one mechanism to
- *     review instead of two.
+ * The child's environment, in three layers with fixed precedence: (1) the
+ * BASE — {@link EXEC_DEFAULT_ENV_PASSTHROUGH} plus the unit's `exec.passEnv`
+ * names; (2) the unit's resolved `env:` bindings; (3) the engine-authored
+ * `AKM_*` context, LAST so a workflow-supplied binding can never shadow the
+ * ids/item the engine is telling the command the truth about.
  *
+ * See docs/architecture/decisions/0003-child-env-allowlist-and-provenance.md
+ * for why the default is an allowlist rather than full inheritance.
  */
-function childEnv(exec, bindings, context) {
+function childEnv(exec, bindings, context, eventSource) {
     const env = collectAllowlistedEnv(execAllowlist(exec));
+    // F-1 (spec §5.2 point 2): applied to the allowlisted BASE only when the
+    // ambient passthrough above left the name absent — an ambient
+    // AKM_EVENT_SOURCE already collected into `env` still wins, and this runs
+    // strictly BEFORE the bindings/context overlays below, so an authored
+    // `env:` binding (or the engine-authored context) still wins too.
+    if (eventSource !== undefined && env.AKM_EVENT_SOURCE === undefined) {
+        env.AKM_EVENT_SOURCE = eventSource;
+    }
     for (const [name, value] of Object.entries(bindings ?? {}))
         env[name] = value;
     for (const [name, value] of Object.entries(context ?? {}))

package/dist/workflows/exec/frozen-judge.js

@@ -67,8 +67,24 @@ function warnLoweringNotices(...groups) {
         }
     }
 }
-/** Build a gate judge from the normalized frozen target without consulting live config. */
-export function frozenSummaryJudge(target, signal, dispatcher, owner) {
+/**
+ * Build a gate judge from the normalized frozen target without consulting live
+ * config.
+ *
+ * `eventSource` (P1b spec §5.2 point 2, gap closed — code review): the task
+ * runner's resolved provenance event source, threaded through exactly like
+ * `executeStepSubgraph`'s units so a workflow-task run's judge dispatch is not
+ * the one dispatch left silently unstamped. Spread onto the built
+ * {@link UnitDispatchRequest} the same way every other optional field here is
+ * — `undefined` for the manual `akm workflow step complete` judge
+ * (`runtime/runs.ts`, which passes no 5th argument) and for `akm workflow run`
+ * (no task context), so both stay byte-identical. When present, it flows
+ * through the same `forwardedDispatchEventSource` precedence gate every other
+ * "command"-kind dispatch uses (`unit-dispatch.ts`): the module doc above
+ * already establishes a judge request never carries an authored `env:`
+ * binding, so the gate always forwards it here.
+ */
+export function frozenSummaryJudge(target, signal, dispatcher, owner, eventSource) {
     if (!target)
         return null;
     const dispatch = withDispatchRedaction(dispatcher ?? dispatchWorkflowExecution);
@@ -89,6 +105,7 @@ export function frozenSummaryJudge(target, signal, dispatcher, owner) {
             ...commonRequest,
             frozenTarget: target,
             timeoutMs: target.runner.timeoutMs ?? null,
+            ...(eventSource !== undefined ? { eventSource } : {}),
         };
         // Lowering and authorization precede every live credential/passthrough
         // sample. The injected dispatcher may be a test seam, but it receives the

package/dist/workflows/exec/native-executor.js

@@ -8,31 +8,12 @@
  * persistence through the serialized writer queue, and `workflow_unit_*`
  * events for observability.
  *
- * Data flow (workflow-format-unification, spec §2.3): there is NO
- * interpolation language. A unit's instructions are the step's body prose
- * BYTE-EXACT — prose is never scanned for reference syntax, so a literal `${{`
- * in a body is content, not grammar. Data reaches the unit as ATTACHED
- * STRUCTURED CONTEXT rather than string splices: `buildUnitPrompt`
- * (`exec/step-work.ts`) wraps the verbatim instructions with JSON blocks for
- * the run params, a map unit's item + index, and the artifacts named by the
- * step's `inputs:`. Because nothing is ever substituted INTO the prose, the P1
- * `{{item}}` re-scan injection class is structurally impossible.
- *
- * References survive only in the three whole-value FRONTMATTER positions the
- * closed two-root grammar occupies (`program/expressions.ts`): `map.over`,
- * `route.input`, and each `inputs[]` entry. They resolve ONCE per step against
- * `{ params, stepOutputs }`. There is NO ambient key search: a
- * `steps.<id>.output.<path>` reference addresses INTO that step's recorded
- * output explicitly.
- *
- * Step outputs (`steps.<id>.output…`): every engine-executed step journals a
- * promoted ARTIFACT under `evidence.output` — the solo unit's result/text, the
- * collect reducer's per-item array, or the vote reducer's winner — and that
- * artifact is what the reference scope exposes ({@link projectStepOutput}).
- * The documented addressing (`steps.discover.output.files`) therefore resolves
- * against real step results, never the raw evidence envelope (peer review R1).
- * Steps completed manually (no `output` key in their evidence) expose their
- * recorded evidence object as-is.
+ * Data flow: there is no interpolation language — a unit's instructions are
+ * the step's body prose byte-exact, and data reaches it as attached
+ * structured context instead. References resolve once per step, only in the
+ * closed frontmatter positions, against the promoted step-output artifact.
+ * See docs/architecture/decisions/0001-no-interpolation-attached-structured-context.md
+ * for the full design history (peer review R1, the P1 injection class it closes).
  *
  * Empty free-text outputs (peer review): a SUCCESSFUL schemaless unit that
  * returns the empty string is normalized to "no output" — {@link dispatchUnit}
@@ -139,6 +120,10 @@ import { assertFrozenExecutableIdentity } from "../../execution/executable-ident
 import { withWorkflowRunsConnection, withWorkflowRunsRepo, } from "../../storage/repositories/workflow-runs-repository.js";
 import { materializeFrozenWorkflowEnvironment } from "../ir/environment-v4.js";
 import { WORKFLOW_UNIT_DIAGNOSTIC_CLIP } from "../resource-limits.js";
+// The ONE child-workflow drive (P3b §3.2) — publishes and drives a
+// `child-workflow`-targeted unit; this module's dispatch seam is its only
+// production caller.
+import { driveChildWorkflowUnit } from "./child-workflow.js";
 // The ONE dispatch redaction contract, shared with the gate-judge path
 // (exec/frozen-judge.ts). Consumers import the leaf directly — this module is
 // not a second front door onto the seam.
@@ -563,6 +548,11 @@ async function runUnit(input) {
         ...(env ? { env } : {}),
         ...(sensitiveValues ? { sensitiveValues } : {}),
         ...(input.signal ? { signal: input.signal } : {}),
+        // F-1 (spec §5.2 point 2): forwarded to exec-unit.ts's childEnv for a
+        // "script"/"shell" unit, and to dispatchWorkflowExecution's
+        // dispatchLoweredExecutionRequest eventSource option (unit-dispatch.ts)
+        // for a "command" unit — both arms observe it.
+        ...(ctx.eventSource !== undefined ? { eventSource: ctx.eventSource } : {}),
     };
     // One content-derived unit id is retained across every retry; the append-only
     // attempt table supplies the 1-based attempt identity.
@@ -700,7 +690,17 @@ function journaledUnitResultJson(outcome) {
 async function prepareAttemptWorktree(input) {
     if (input.worktreeBase === undefined)
         return { ok: true, request: input.request };
-    const created = await createUnitWorktree(input.worktreeBase, input.ctx.runId, input.attemptId, input.workUnit.frozenTarget.gitCommitOid);
+    const created = await createUnitWorktree(input.worktreeBase, input.ctx.runId, input.attemptId, 
+    // A child-workflow target (P3a, schema-v4.ts) carries no gitCommitOid of
+    // its own — it is a composition target, never a worktree-isolated exec
+    // one. This arm IS reachable — a step that composes a child workflow and
+    // also declares `isolation: worktree` gets a worktree prepared here
+    // (worktree prep runs ahead of dispatch), but the child executor
+    // (child-workflow.ts, P3b §3.2) never dispatches through it: driving a
+    // child publishes and drives a RUN, not a command/exec unit, so the
+    // prepared worktree is simply unused by the drive. This ternary keeps the
+    // field access total over the frozen-target union either way.
+    input.workUnit.frozenTarget.kind === "child-workflow" ? undefined : input.workUnit.frozenTarget.gitCommitOid);
     if (created.preservedLeftover !== undefined) {
         warn(`Workflow unit ${input.attemptId}: a previous attempt left uncollected work in its isolation worktree; ` +
             `preserved at ${created.preservedLeftover}`);
@@ -831,7 +831,27 @@ async function dispatchJournaledAttempt(input) {
         attempt: durableAttempt.attempt,
         dispatchId: durableAttempt.dispatch_id,
     };
-    const dispatched = await dispatchUnit(request, dispatcher);
+    // P3b §3.2: the ONE dispatch-seam branch. A `child-workflow`-targeted unit
+    // never reaches `UnitDispatcher` — it is routed to the child executor
+    // instead (src/workflows/exec/child-workflow.ts), which publishes the
+    // child idempotently and drives it with the SAME engine
+    // (`runWorkflowSteps`) the top-level path uses. Placed HERE — after
+    // `reserveJournaledDispatch` claims this attempt row, before
+    // `finishJournaledDispatch`/the worktree epilogue below — so a
+    // child-workflow unit is journaled exactly like any other unit, and a
+    // crash between reservation and child publication leaves a `running`
+    // parent row with no child, recovered by resume (which re-dispatches the
+    // parent unit and republishes the child idempotently).
+    const dispatched = request.frozenTarget.kind === "child-workflow"
+        ? await driveChildWorkflowUnit({
+            request,
+            target: request.frozenTarget,
+            ctx,
+            childParams: workUnit.childParams ?? {},
+            inputHash: input.inputHash,
+            dispatcher,
+        })
+        : await dispatchUnit(request, dispatcher);
     // Credential and passthrough values are intentionally sampled only AFTER
     // the default dispatcher has authorized/lowered the frozen request and
     // materialized credentials at its terminal dispatch boundary. Custom test
@@ -1070,6 +1090,7 @@ export const defaultUnitDispatcher = async (request, feedback) => {
                 ...(request.schema ? { hasOutputSchema: true } : {}),
                 timeoutMs: request.timeoutMs,
                 ...(request.signal ? { signal: request.signal } : {}),
+                ...(request.eventSource !== undefined ? { eventSource: request.eventSource } : {}),
             });
         }
         finally {
@@ -1094,6 +1115,7 @@ export const defaultUnitDispatcher = async (request, feedback) => {
             ...(request.schema ? { hasOutputSchema: true } : {}),
             timeoutMs: request.timeoutMs,
             ...(request.signal ? { signal: request.signal } : {}),
+            ...(request.eventSource !== undefined ? { eventSource: request.eventSource } : {}),
         });
     }
     return dispatchWorkflowExecution(request, feedback);

package/dist/workflows/exec/param-secrets.js

@@ -23,6 +23,18 @@
  * strings. It is purely advisory — it NEVER blocks a run and NEVER mutates
  * params — and is surfaced when a run starts. False positives and false
  * negatives are expected; it is a nudge, not a scanner.
+ *
+ * ## Reused as `akm task explain`'s redaction check
+ *
+ * `src/commands/tasks/explain.ts` reuses this same heuristic (via its own
+ * `isSecretShapedValue` wrapper) to decide which task-input values to print
+ * as `"<redacted>"` instead of in full. That reuse does NOT upgrade this
+ * detector into a hard guarantee: `explain`'s redaction is exactly as
+ * best-effort as the warnings above — a short, low-entropy, or
+ * unusually-named credential that this function does not flag prints
+ * UNREDACTED there too. Do not describe either surface as "secret-free by
+ * construction"; describe it as "secret-shaped values are redacted on a
+ * best-effort basis."
  */
 /**
  * Substrings that, when present in a param KEY (case-insensitive), suggest the

package/dist/workflows/exec/run-workflow.js

@@ -4,63 +4,15 @@
 /**
  * Engine-driven workflow execution — the `akm workflow run`
  * start/resume/execute path, and the single execution surface for a run: akm
- * walks the frozen plan and dispatches every unit itself.
+ * walks the frozen plan and dispatches every unit itself. Every step
+ * advances through `completeWorkflowStep` (never a direct step-row write),
+ * the plan is read from its frozen `plan_json` row rather than live source,
+ * a run lease enforces one driving engine invocation at a time, gate loops
+ * are bounded, and the SDK dispatch registry is drained in a `finally` on
+ * every exit path so no child process keeps the event loop open.
  *
- * Invariant (plan §*Never bypass the gate spine*): every step advances
- * through `completeWorkflowStep`, never by writing step rows directly, so the
- * summary-validation gate and run-state derivation stay authoritative. A gate
- * rejection (SummaryValidationFailure) STOPS the engine and surfaces the
- * corrective feedback — a gate is a gate, even for the engine.
- *
- * Artifact-judging gates (redesign addendum, R2): when a step declares
- * completion criteria, the engine hands the gate a summary BUILT FROM the
- * step's promoted artifact (canonical JSON, clipped, prefixed with a one-line
- * unit count — `buildArtifactSummary`) instead of the machine-prose execution
- * summary, so the judge evaluates real results. Each engine-driven judge call
- * is journaled as a unit row (`node_id "<stepId>.gate"`, `unit_id
- * "<stepId>.gate:l<loop>"`, runner "llm", result_json = the verdict) through
- * the writer queue — it is an LLM call like any other. Human approvals are
- * never cached: a blocked gate stays blocked.
- *
- * Bounded gate loops (`gate.max_loops`, addendum R2): a rejection on a step
- * with maxLoops > 1 re-executes the step subgraph with the judge's feedback +
- * missing[] threaded into every unit prompt (`gateFeedback` on
- * StepExecutionContext) — the feedback changes each unit's input hash, so the
- * loop re-dispatches naturally instead of reusing the rejected rows. After
- * maxLoops rejections the engine stops with the gate feedback, exactly like
- * the one-shot case. A typed-artifact schema mismatch feeds the same loop
- * (the validation errors are the feedback; no judge ran, so no gate unit is
- * journaled for that attempt) — only the FINAL loop's mismatch fails the run.
- * A step whose subgraph is an `exec` unit is judged but NEVER looped
- * (`effectiveGateMaxLoops`): its argv cannot read the feedback, so a second
- * loop would only re-run the identical side effect.
- *
- * Frozen plan (redesign addendum, R1): the plan graph is read from the run
- * row (`plan_json`, persisted by `startWorkflowRun` under migration 006) with
- * a `plan_hash` integrity check — the workflow asset file is NEVER re-read
- * for an in-flight run, so a mid-run asset edit cannot change behavior.
- * Durable-row resume: re-invoking a partially-executed run re-dispatches only
- * work that never completed.
- *
- * Run lease (redesign addendum, R2): exactly one engine invocation drives a
- * run at a time. The lease (random holder id + 90s expiry on the run row) is
- * acquired before any dispatch, renewed between steps, and released in a
- * `finally` unless a failed run retains it as forensic state; a second
- * `workflow run` on a live-leased run refuses up front,
- * and an expired lease is claimable (crash recovery). While the lease is
- * live, any competing spine advance is refused — the engine owns the run while
- * driving (enforced inside `completeWorkflowStep`).
- *
- * Process-lifecycle contract (owner finding 4 — no leaked handles): the SDK
- * dispatch path caches `opencode serve` CHILD PROCESSES in a per-env registry
- * for reuse across units. Each live child is an OS handle that keeps Bun's
- * event loop open; the registry's own teardown is wired only to
- * `process.once('exit')`, which never fires while a child holds the loop open.
- * That deadlock hangs a one-shot CLI (`akm workflow run` has no `process.exit`
- * on success — it relies on the loop draining). The engine therefore DRAINS
- * the dispatch registry ({@link disposeDispatchResources}) in its run `finally`,
- * on EVERY exit path, so the process exits cleanly the moment the run resolves.
- * The drain is synchronous, idempotent, and a no-op when no SDK server started.
+ * See docs/architecture/decisions/0011-engine-run-loop-invariants.md for the
+ * full design history behind each of these invariants.
  */
 import { randomUUID } from "node:crypto";
 import { UsageError } from "../../core/errors.js";
@@ -373,7 +325,11 @@ function workflowSummaryJudge(options, stepPlan, signal, owner) {
         return options.summaryJudge;
     // The judge dispatches under the REAL run/step identity; the per-loop gate row
     // identity is threaded in per call by the completion path that journals it.
-    return frozenSummaryJudge(stepPlan.gate.frozenJudge, signal, options.dispatcher ?? defaultUnitDispatcher, owner);
+    // eventSource (gap closed, code review): the judge's dispatch is a "command"
+    // request like any other exec/agent/sdk unit, so it goes through the same
+    // provenance thread `executeStepSubgraph` uses below — undefined for every
+    // non-task caller, byte-identical.
+    return frozenSummaryJudge(stepPlan.gate.frozenJudge, signal, options.dispatcher ?? defaultUnitDispatcher, owner, options.eventSource);
 }
 /**
  * Seed the lifetime unit cap AND the budget ceilings from the journal so
@@ -477,7 +433,10 @@ async function recoverGateLoopState(runId, stepPlan) {
  * The kinds that FINISHED the step (completed / failed / gate-exhausted) — the
  * ONE `maxSteps` consumption for its whole gate loop. An abort and a judge
  * outage leave the step unfinished and consume nothing: the next invocation
- * still owes the work.
+ * still owes the work. A blocked child is the SAME shape as a judge outage
+ * (P3b §3.4) — a gate is a gate for a child workflow too, so it is likewise
+ * NOT in this set: `akm workflow resume` is what clears it, never an
+ * automatic in-step re-dispatch.
  */
 const STEP_FINISHED_KINDS = new Set(["advanced", "failed", "gate-exhausted"]);
 /**
@@ -510,6 +469,9 @@ async function executeStepSubgraph(ctx, loop) {
             ...(plan.budget ? { budget: plan.budget } : {}),
             gateLoop,
             ...(gateFeedback ? { gateFeedback } : {}),
+            // F-1 (spec §5.2 point 2): threaded to an exec unit's child env;
+            // undefined for every non-task caller (byte-identical, RunWorkflowOptions doc).
+            ...(options.eventSource !== undefined ? { eventSource: options.eventSource } : {}),
             // The heartbeat's signal is the effective dispatch signal: a lost
             // lease (or a caller abort) aborts in-flight units promptly.
             ...(dispatchSignal ? { signal: dispatchSignal } : {}),
@@ -633,6 +595,29 @@ async function runStepGateLoop(ctx, gate, totals) {
             executed[executed.length - 1] = { ...executed[executed.length - 1], summary: finalize.summary };
             return outcome({ kind: "judge-failed", judgeFailure: { stepId: step.id, message: finalize.summary } });
         }
+        if (finalize.kind === "child-blocked") {
+            // P3b §3.4: a composed child workflow is blocked. Like judge-failed,
+            // NO gate loop was consumed and the step does not count against
+            // maxSteps. `result.childBlocked` (set by reduceStepOutcomes off the
+            // failed unit's live-only childRun field) carries the identity
+            // finalizeExecutedStep's own return value deliberately omits.
+            executed[executed.length - 1] = { ...executed[executed.length - 1], summary: finalize.summary };
+            const child = result.childBlocked;
+            return outcome({
+                kind: "child-blocked",
+                ...(child
+                    ? {
+                        childBlocked: {
+                            stepId: step.id,
+                            childRunId: child.childRunId,
+                            childRef: child.childRef,
+                            resume: `akm workflow resume ${child.childRunId}`,
+                            resumeParentCommand: `akm workflow resume ${next.run.id} && akm workflow run ${next.run.id}`,
+                        },
+                    }
+                    : {}),
+            });
+        }
         if (finalize.kind === "failed") {
             // A route-failure was pushed as ok:true (the units succeeded); reflect
             // the deterministic route failure in the executed report.
@@ -679,6 +664,7 @@ liveEvidence) {
     const executed = [];
     let gateRejection;
     let judgeFailure;
+    let childBlocked;
     let aborted = false;
     const maxSteps = options.maxSteps ?? Number.POSITIVE_INFINITY;
     // The `maxSteps` budget counts DISTINCT spine steps that finished processing
@@ -820,10 +806,12 @@ liveEvidence) {
             gateRejection = outcome.gateRejection;
         if (outcome.judgeFailure)
             judgeFailure = outcome.judgeFailure;
+        if (outcome.childBlocked)
+            childBlocked = outcome.childBlocked;
         if (STEP_FINISHED_KINDS.has(outcome.kind))
             stepsProcessed += 1;
         // Only an advance leaves the spine walkable; every other kind ends this
-        // invocation (failure, exhausted gate, judge outage, abort).
+        // invocation (failure, exhausted gate, judge outage, blocked child, abort).
         if (outcome.kind !== "advanced")
             break;
         next = await getNextWorkflowStep(next.run.id);
@@ -839,6 +827,7 @@ liveEvidence) {
         ...(finalState.run.status === "completed" ? { done: true } : {}),
         ...(gateRejection ? { gateRejection } : {}),
         ...(judgeFailure ? { judgeFailure } : {}),
+        ...(childBlocked ? { childBlocked } : {}),
         ...(aborted ? { aborted: true } : {}),
     };
 }