@intx/workflow-host 0.2.2 → 0.4.0

package/dist/child/run-child.js

@@ -25,7 +25,8 @@
 //      each one whose log lacks a terminal event.
 //   4. Emit `ready` on the control channel.
 //   5. Loop on control-channel frames:
-//        - `trigger.fired` -> open a new run via `runtimeRun`.
+//        - `trigger.fired` -> first-fire the deployment's top-level run via
+//          `runtimeRun` (the supervisor only sends this for an absent log).
 //        - `grants-updated` -> replace the credentialsSnapshot.
 //        - `drain` -> forward to the drain controller (no-op here).
 //        - `shutdown` -> stop accepting new triggers and exit the
@@ -47,24 +48,27 @@
 // classifies each in-flight step as cancel-mode or wait-mode. The
 // supervisor's recycle policy is OS-driven (drain, SIGTERM, SIGKILL,
 // respawn) and does not require a child-side control frame.
-import { type } from "arktype";
 import { getLogger } from "@intx/log";
 import { generateKeyPair } from "@intx/crypto";
-import { base64Decode, hexEncode } from "@intx/types";
-import { readProcessingEntry, workflowDefinitionEnvelopeSchema, } from "@intx/hub-sessions/substrate";
-import { extractPartByPath, parseHeaderSection, parseMimePart, } from "@intx/mime";
-import { createDefaultDirectorRegistry } from "@intx/agent";
-import { emptyState, runtimeRun } from "@intx/workflow";
+import { hexEncode } from "@intx/types";
+import { rewriteInlineOnTriggerBodies, rewriteInlineChildWorkflowBodies, enumerateInlineLoopBodies, eagerlyResolveLoopFns, } from "@intx/workflow";
+import { baseStepId, createDefaultActionInvoker, createInMemoryEffectLedger, createLoopIterationHandle, emptyState, runtimeRun, } from "@intx/workflow";
 import { createWorkflowHostDrainController, } from "../drain-controller.js";
 import { createWorkflowRunRepoStore } from "../adapters/repo-store.js";
 import { createWorkflowRunBlobSubstrate } from "../adapters/blob-substrate.js";
+import { createMailPartReader } from "../adapters/mail-part-store.js";
+import { createInMemorySpawnSuspendableChild, createInMemorySpawnChild, } from "../adapters/spawn-child.js";
 import { createControlChannelSender, createEventChannelSender, receiveControlChannel, } from "../ipc/index.js";
+import { runBodyThenCleanup } from "../run-body-then-cleanup.js";
 import { createWorkflowHostSignalChannel } from "../seams/signal-channel.js";
 import { hashGrants } from "../supervisor/credentials.js";
+import { loadVerifiedWorkflowDefinitionFromClosure } from "./verified-definition-loader.js";
+import { loadWorkflowActionHandlersFromClosure, loadWorkflowDirectorRegistryFromClosure, loadWorkflowLoopFnsFromClosure, } from "../workflow-definition-loader.js";
 import { discoverInFlightRuns } from "./self-discovery.js";
+import { collectParkedApprovalCorrelations, } from "./parked-correlations.js";
 import { createWarmAgentCache } from "./warm-agent-cache.js";
+import { mergeCredentialDelivery } from "./credential-cell.js";
 const logger = getLogger(["workflow-host", "child"]);
-const WORKFLOW_JSON_PATH = "workflow.json";
 export function createCredentialsBackedAuthorize(ref, evaluate) {
     return async (resource, action, ctx) => {
         const stepId = ctx?.stepId;
@@ -75,9 +79,17 @@ export function createCredentialsBackedAuthorize(ref, evaluate) {
         if (snapshot === null) {
             throw new Error("workflow-child authorize: no credentialsSnapshot active; the supervisor must push one before any step runs");
         }
-        const entry = snapshot.steps.find((s) => s.stepId === stepId);
+        // The credentials snapshot is keyed per base step; a map iteration's
+        // scoped id `<base>[<index>]` resolves to its base entry so every
+        // iteration shares the base step's grants. `baseStepId` is the identity
+        // on an unscoped id, so a plain step is unaffected.
+        const lookupStepId = baseStepId(stepId);
+        const entry = snapshot.steps.find((s) => s.stepId === lookupStepId);
         if (entry === undefined) {
-            throw new Error(`workflow-child authorize: credentialsSnapshot has no entry for stepId ${stepId}`);
+            const scopedNote = lookupStepId === stepId
+                ? ""
+                : ` (normalized from scoped invocation id ${stepId})`;
+            throw new Error(`workflow-child authorize: credentialsSnapshot has no entry for stepId ${lookupStepId}${scopedNote}`);
         }
         return evaluate({
             resource,
@@ -101,7 +113,28 @@ export async function runWorkflowChild(opts) {
     const sourcesRef = {
         current: opts.bindings.initialSources ?? {},
     };
-    const directors = opts.bindings.directors ?? createDefaultDirectorRegistry();
+    const credentialMaterialRef = {
+        current: opts.bindings.initialCredentialMaterial ?? null,
+    };
+    // The per-run credential wiring the top-level step invoker carries to the
+    // substrate: the live material cell and a resolver for a step's grants from
+    // the same credentials snapshot `authorize` reads. Built once over the two
+    // refs; every step build reads them live, so a rotation -- or a revoking
+    // re-push that swaps a ref -- is reflected without rebuilding the wiring.
+    const credentialWiring = {
+        materialRef: credentialMaterialRef,
+        resolveStepGrants: (stepId) => {
+            const snapshot = credentialsRef.current;
+            if (snapshot === null) {
+                throw new Error(`workflow-child credential wiring: no credentials snapshot for step ${stepId}; a tool-bearing step cannot resolve its grants before the run carries any`);
+            }
+            const entry = snapshot.steps.find((step) => step.stepId === baseStepId(stepId));
+            if (entry === undefined) {
+                throw new Error(`workflow-child credential wiring: credentials snapshot has no entry for step ${baseStepId(stepId)}`);
+            }
+            return entry.grants;
+        },
+    };
     const clock = opts.bindings.clock ?? defaultClock;
     const newId = opts.bindings.newId ?? defaultNewId;
     // Mint the child's own upstream-signing keypair. The private half
@@ -120,7 +153,160 @@ export async function runWorkflowChild(opts) {
         channelId: opts.env.channelId,
         writer: opts.eventWriter,
     });
-    const definition = await loadWorkflowDefinition(opts.bindings);
+    // Re-verify barrier at the load boundary. Source-ref is the only deploy
+    // lineage: the inert projection is a non-executable approval surface (agents
+    // carry `modelSources`/no `inference`, tool factories are plain data), so the
+    // child EVALUATES the pinned code closure to a live definition and re-verifies
+    // by projecting it back to inert and hashing (`computeLiveDefinitionHash`)
+    // against `opts.env.definitionHash`; a divergent closure fails closed. The
+    // load happens once before both the resume loop and the trigger loop, so the
+    // same verified definition serves every fresh trigger AND every resume.
+    //
+    // Post-verify structural rewrite: the re-verify above hashed the closure's
+    // INLINE onTrigger bodies (matching the frozen approval); now lift each to a
+    // `{ ref }` so the runtime dispatches to the body child, and keep the
+    // extracted body definitions in an in-memory map. The suspendable-child
+    // resolver runs each body from THIS map -- the parent's already-re-verified
+    // closure -- with no disk read and no separate per-body re-verify. The rewrite
+    // MUST follow the re-verify: rewriting first would diverge from the frozen
+    // inline-body hash.
+    const verifiedDefinition = await loadVerifiedWorkflowDefinitionFromClosure({
+        packageDir: opts.env.closurePackageDir,
+        approvedHash: opts.env.definitionHash,
+    });
+    const { workflow, bodies } = rewriteInlineOnTriggerBodies(verifiedDefinition);
+    let definition = workflow;
+    const bodiesMap = new Map(bodies.map((b) => [b.ref, b.definition]));
+    // An owned `childWorkflow` import embeds its child inline in the parent's
+    // definition (folded into the parent's hash and approval), so it is already
+    // covered by the re-verify above. Lift each inline child to an internal
+    // `{ ref }` -- the form the runtime dispatches -- and keep the lifted
+    // definitions in an in-memory map. The terminal childWorkflow resolver below
+    // runs each child from THIS map, with no on-disk asset read and no separate
+    // per-child re-verify.
+    const childRewrite = rewriteInlineChildWorkflowBodies(definition);
+    definition = childRewrite.workflow;
+    const childBodiesMap = new Map(childRewrite.bodies.map((b) => [b.ref, b.definition]));
+    // A loop iteration runs its body as a suspendable child through the same seam
+    // an onTrigger body uses, so register each top-level loop body in `bodiesMap`
+    // under its `<workflowId>__<stepId>` ref. Unlike an onTrigger or childWorkflow
+    // body, a loop keeps its body INLINE on the primitive -- both hash layers
+    // project the body inline, so rewriting the primitive would change every
+    // existing loop's hash. `enumerateInlineLoopBodies` mints a ref-keyed COPY and
+    // leaves the primitive untouched, and a given step is exactly one primitive
+    // kind, so a loop ref never collides with an onTrigger or childWorkflow ref.
+    //
+    // A loop body may itself contain a `childWorkflow` grandchild: rewrite the
+    // COPY's inline children to `{ ref }` (the primitive, and thus the hash, is
+    // untouched) and fold the extracted grandchildren into `childBodiesMap` HERE
+    // -- before the eager loop-fn/handler resolution and the terminal-childWorkflow
+    // host selection below, both of which read `childBodiesMap`. Merging later
+    // would resolve a grandchild's refs mid-run instead of at establish, and would
+    // leave `childBodiesMap` empty for a deployment whose only child is a
+    // loop-body grandchild, so its spawn would find no wired terminal host.
+    // Keep each loop body's PRE-rewrite form (its childWorkflow grandchild still
+    // inline) keyed by ref: the grants cap for a loop iteration re-walks it, and
+    // capping the rewritten `{ ref }` form would skip -- and so under-authorize --
+    // the grandchild's declared resources.
+    const loopBodyPreRewrite = new Map();
+    for (const loopBody of enumerateInlineLoopBodies(definition)) {
+        loopBodyPreRewrite.set(loopBody.ref, loopBody.definition);
+        const bodyRewrite = rewriteInlineChildWorkflowBodies(loopBody.definition);
+        bodiesMap.set(loopBody.ref, bodyRewrite.workflow);
+        for (const grandchild of bodyRewrite.bodies) {
+            childBodiesMap.set(grandchild.ref, grandchild.definition);
+        }
+    }
+    // Directors resolve from the pinned closure so a custom director authored in
+    // the workflow's own package runs. Loading directors OUTSIDE the
+    // definition-hash re-verify is safe: the approved hash pins each director's
+    // id + config (which director runs cannot change post-approval) and the
+    // closure's SRI pins its module bytes. Folding directors into the hash would
+    // be redundant, so it is deliberately not done -- see
+    // `loadWorkflowDirectorRegistryFromClosure`.
+    const directors = await loadWorkflowDirectorRegistryFromClosure({
+        packageDir: opts.env.closurePackageDir,
+    });
+    // Loop `while`/`carry` functions resolve from the pinned closure's
+    // `interchange.loops` module, loaded alongside the directors and OUTSIDE the
+    // definition-hash re-verify for the same reason: the approved hash pins each
+    // ref string and the closure's SRI pins the module bytes. Resolve every loop
+    // ref reachable from the definition (its own loop bodies, and the lifted
+    // onTrigger/childWorkflow bodies, which share this same registry at runtime)
+    // eagerly here, so a deployment that declares a loop whose fn the closure
+    // does not export fails at establish rather than mid-run.
+    const loopFns = await loadWorkflowLoopFnsFromClosure({
+        packageDir: opts.env.closurePackageDir,
+    });
+    eagerlyResolveLoopFns([definition, ...bodiesMap.values(), ...childBodiesMap.values()], loopFns);
+    // Action handlers resolve from the pinned closure's `interchange.actions`
+    // module, on the same terms as loop fns. Resolve every action handler ref
+    // reachable from the definition eagerly here (recursing into loop bodies,
+    // where an action body is the common case), so a deployment that declares an
+    // action whose handler the closure does not export fails at establish rather
+    // than mid-run.
+    const actionResolver = await loadWorkflowActionHandlersFromClosure({
+        packageDir: opts.env.closurePackageDir,
+    });
+    eagerlyResolveActionHandlers([definition, ...bodiesMap.values(), ...childBodiesMap.values()], actionResolver);
+    // Suspendable-child resolver (onTrigger section bodies and loop bodies),
+    // selected ONCE per deployment: the bodies map is immutable and the per-run
+    // `onEvent` is injected later in `buildRuntimeEnv`. Resolve each body from the
+    // parent's in-memory closure (already re-verified above) via the raw executor
+    // binding. A deployment that carries bodies but whose host wired no executor is
+    // a misconfiguration -- fail loud at startup rather than silently falling back
+    // to a disk read (the exact behaviour this arm exists to avoid). A deployment
+    // with no suspendable body leaves the host undefined; its slot is never
+    // invoked.
+    let suspendableChildHost;
+    if (bodiesMap.size > 0) {
+        const executor = opts.bindings.runSuspendableChild;
+        if (executor === undefined) {
+            throw new Error("workflow-child: source-ref deployment carries suspendable bodies " +
+                "(onTrigger sections or loop bodies) but the host wired no " +
+                "runSuspendableChild executor; cannot resolve bodies in-memory");
+        }
+        suspendableChildHost = createInMemorySpawnSuspendableChild({
+            bodies: bodiesMap,
+            runSuspendableChild: executor,
+        });
+    }
+    // Terminal childWorkflow resolver, selected ONCE per deployment. When the
+    // definition embeds any inline child (the lifted map is non-empty), resolve
+    // each from that in-memory map via the raw terminal executor -- the parent's
+    // own re-verified closure -- so an owned child spawns with no disk read. A
+    // deployment that embeds a childWorkflow but whose host wired no executor is
+    // a misconfiguration and fails loud at startup rather than falling back to a
+    // disk read. A definition with no inline child keeps the injected binding (a
+    // test seam); its childWorkflow slot is never invoked.
+    // `HostSpawnChild` (a call-arg `onEvent`) like the suspendable host: the
+    // resolver is deployment-scoped but each run injects its own event sink in
+    // `buildRuntimeEnv`. The two fallback arms ignore the sink.
+    let spawnChild;
+    if (childBodiesMap.size > 0) {
+        const executor = opts.bindings.runChild;
+        if (executor === undefined) {
+            throw new Error("workflow-child: deployment embeds childWorkflow imports but the " +
+                "host wired no runChild executor; cannot resolve children in-memory");
+        }
+        spawnChild = createInMemorySpawnChild({
+            bodies: childBodiesMap,
+            runChild: executor,
+        });
+    }
+    else if (opts.bindings.spawnChild !== undefined) {
+        const injected = opts.bindings.spawnChild;
+        spawnChild = (input, _onEvent) => injected(input);
+    }
+    else {
+        // No inline child and no injected binding: a workflow that nonetheless
+        // reaches a childWorkflow spawn fails loud here rather than silently
+        // completing against a child that never ran.
+        spawnChild = async ({ definitionRef }, _onEvent) => {
+            throw new Error(`workflow-child: childWorkflow ${definitionRef} reached the runtime ` +
+                `but no child executor is wired`);
+        };
+    }
     const authorize = createCredentialsBackedAuthorize(credentialsRef, opts.bindings.evaluateGrants);
     const drainController = createWorkflowHostDrainController({ definition });
     // Warm-agent cache (design §3b). Built only when the deployment is a
@@ -174,16 +360,24 @@ export async function runWorkflowChild(opts) {
             runtimeRepoStore,
             authorize,
             directors,
+            suspendableChildHost,
+            bodiesMap,
+            loopBodyPreRewrite,
+            spawnChild,
+            loopFns,
+            actionResolver,
             clock,
             newId,
             drainController,
             warmCache,
             sourcesRef,
+            credentialWiring,
             onEvent: (event) => {
                 void eventSender.send(event).catch((cause) => {
                     logger.error `event-channel send failed during resume run ${run.runId}: ${String(cause)}`;
                 });
             },
+            upstreamSender,
         });
         const handle = runtimeRun(definition, env, {
             runId: run.runId,
@@ -202,13 +396,12 @@ export async function runWorkflowChild(opts) {
                 cleanupRunStorage: opts.bindings.cleanupRunStorage,
                 runId: run.runId,
             });
+            runsInFlight.delete(run.runId);
             return emitTerminalEvent(upstreamSender, result);
         })
             .catch((cause) => {
-            logger.error `resumed run ${run.runId} failed: ${String(cause)}`;
-        })
-            .finally(() => {
             runsInFlight.delete(run.runId);
+            logger.error `resumed run ${run.runId} failed: ${String(cause)}`;
         });
         resumedRunIds.push(run.runId);
     }
@@ -231,6 +424,12 @@ export async function runWorkflowChild(opts) {
             childPublicKey: hexEncode(childKeyPair.publicKey),
         },
     });
+    // Report self-discovered runs so the supervisor seeds its cohort
+    // tracking before the dispatch loop starts.
+    await upstreamSender.send({
+        type: "resumed.runs",
+        data: { runIds: resumedRunIds },
+    });
     const triggeredRunIds = [];
     // Control-loop. The receiver iterator yields one verified payload
     // per call; any signature/channelId/seq violation crashes the
@@ -243,7 +442,14 @@ export async function runWorkflowChild(opts) {
             logger.error `workflow-child control channel crash: ${reason}`;
         },
     });
-    try {
+    // Resolve the mailbox watch registry the control loop routes `mailbox.notify`
+    // frames to. Production wires it on the bindings (the substrate factory builds
+    // one instance and shares it with the warm agent's supervisor-backed
+    // transport); a test may inject one directly through the opts, which wins.
+    // Both absent leaves inbound `mailbox.notify` frames logged and dropped -- a
+    // deploy with no wired mail surface.
+    const mailboxWatchRegistry = opts.mailboxWatchRegistry ?? opts.bindings.mailboxWatchRegistry;
+    const runControlLoop = async () => {
         for await (const payload of iter) {
             if (await handleControlPayload(payload, {
                 env: opts.env,
@@ -253,6 +459,12 @@ export async function runWorkflowChild(opts) {
                 definition,
                 authorize,
                 directors,
+                suspendableChildHost,
+                bodiesMap,
+                loopBodyPreRewrite,
+                spawnChild,
+                loopFns,
+                actionResolver,
                 clock,
                 newId,
                 eventSender,
@@ -262,20 +474,28 @@ export async function runWorkflowChild(opts) {
                 runsInFlight,
                 warmCache,
                 sourcesRef,
+                credentialMaterialRef,
+                credentialWiring,
                 ...(opts.substrateWriteBridge !== undefined
                     ? { substrateWriteBridge: opts.substrateWriteBridge }
                     : {}),
                 ...(opts.outboundMailBridge !== undefined
                     ? { outboundMailBridge: opts.outboundMailBridge }
                     : {}),
+                ...(opts.mailboxMutationBridge !== undefined
+                    ? { mailboxMutationBridge: opts.mailboxMutationBridge }
+                    : {}),
+                ...(mailboxWatchRegistry !== undefined
+                    ? { mailboxWatchRegistry }
+                    : {}),
             })) {
                 // shutdown received; the shutdown case already cancelled any
                 // pending substrate writes before returning true.
                 break;
             }
         }
-    }
-    finally {
+    };
+    const cleanupControlLoop = async () => {
         // Any exit path -- clean (iterator end), dirty (thrown error),
         // shutdown (already cancelled, repeat is a no-op on an empty map)
         // -- cancels every still-pending substrate write so the runtime
@@ -292,6 +512,13 @@ export async function runWorkflowChild(opts) {
         if (opts.outboundMailBridge !== undefined) {
             opts.outboundMailBridge.cancelAll("workflow-child control loop exited");
         }
+        // Same contract for mailbox mutations: a step agent's flag or
+        // `expunge` still awaiting the supervisor's `mailbox.mutate.response`
+        // when the control loop exits must surface a structured rejection
+        // rather than hang on a torn-down channel.
+        if (opts.mailboxMutationBridge !== undefined) {
+            opts.mailboxMutationBridge.cancelAll("workflow-child control loop exited");
+        }
         // Evict the warm-agent cache (design §3b) on every exit path:
         // graceful (shutdown frame -> iterator end), dirty (thrown error),
         // or the control channel closing. Eviction runs the wrapped
@@ -303,7 +530,12 @@ export async function runWorkflowChild(opts) {
         if (warmCache !== undefined) {
             await warmCache.evictAll("workflow-child control loop exited");
         }
-    }
+    };
+    // Run the control loop, then always run the cleanup above. A failing
+    // eviction (the wrapped agent close rejects when a plugin/LSP disposer
+    // fails) surfaces on a clean exit, but must not mask a control-loop
+    // error already unwinding -- so it is logged, not rethrown, in that case.
+    await runBodyThenCleanup(runControlLoop, cleanupControlLoop, (cause) => logger.error `workflow-child: warm-agent eviction failed while unwinding a control-loop error; surfacing the control-loop error, eviction failure: ${cause instanceof Error ? cause.message : String(cause)}`);
     return {
         resumedRunIds,
         triggeredRunIds,
@@ -320,16 +552,16 @@ async function handleControlPayload(payload, ctx) {
         case "trigger.fire": {
             // One driver per runId. If this child is already driving this
             // runId -- self-discovery resumed it, or an earlier trigger opened
-            // it -- the supervisor's re-fire (which carries `runId = messageId`
-            // and no resumeFromEvents) must NOT spawn a second `runtimeRun`. A
+            // it -- a duplicate/stale trigger frame (which carries the local part
+            // of the deployment's mail address as the runId and no resumeFromEvents)
+            // must NOT spawn a second `runtimeRun`. A
             // second concurrent driver would race the live one to settle the
             // same residual and the loser throws an uncaught TransitionError,
             // and even a driver that avoided the throw would double-emit the
             // terminal. The live driver's completion continuation owns the
             // single terminal emission; the supervisor's terminal-event-driven
-            // `markConsumed` consumes the message off that one terminal, so no
-            // work is dropped by declining here. Record the runId (the
-            // supervisor did fire a trigger and it was accepted) and signal
+            // `markConsumed` consumes the original message off that one terminal,
+            // so no work is dropped by declining here. Record the runId and signal
             // "handled, not shutdown" the same way the normal trigger case
             // returns, without awaiting the live handle's `complete` inline
             // (that would block the control loop).
@@ -337,39 +569,39 @@ async function handleControlPayload(payload, ctx) {
                 ctx.triggeredRunIds.push(payload.data.runId);
                 return false;
             }
-            // Resolve the inbound mail bytes for this messageId from the
-            // claim-check processing entry the supervisor created when it
-            // dequeued the message. The bytes become the run's trigger
-            // payload; the one-step workflow's first step defaults its input
-            // selector to `trigger.payload` (defineWorkflow's default-input
-            // convention), so the step input resolves to the inbound message
-            // and `agent.send` receives it. A missing or unreadable entry
-            // surfaces loudly -- the run cannot proceed without its input,
-            // and silently running the agent with empty input would mask a
-            // real mailbox-ownership failure.
-            const triggerPayload = await resolveTriggerPayload({
-                substrate: ctx.bindings.substrate,
-                principal: ctx.bindings.principal,
-                workflowRunRepoId: ctx.bindings.workflowRunRepoId,
-                mailboxAddress: ctx.env.mailboxAddress,
-                messageId: payload.data.messageId,
-            });
+            // The supervisor resolved the inbound mail to the run's input (the
+            // conversation text plus references to attachment bytes it committed to
+            // the workflow-run substrate) and shipped it in the frame. It becomes
+            // the run's trigger payload; the one-step workflow's first step defaults
+            // its input selector to `trigger.payload` (defineWorkflow's default-input
+            // convention), so the step input resolves to the inbound message and
+            // `agent.send` receives it once its attachment references are resolved to
+            // bytes at send time.
+            const triggerPayload = payload.data.payload;
             const env = buildRuntimeEnv({
                 runId: payload.data.runId,
                 bindings: ctx.bindings,
                 runtimeRepoStore: ctx.runtimeRepoStore,
                 authorize: ctx.authorize,
                 directors: ctx.directors,
+                suspendableChildHost: ctx.suspendableChildHost,
+                bodiesMap: ctx.bodiesMap,
+                loopBodyPreRewrite: ctx.loopBodyPreRewrite,
+                spawnChild: ctx.spawnChild,
+                loopFns: ctx.loopFns,
+                actionResolver: ctx.actionResolver,
                 clock: ctx.clock,
                 newId: ctx.newId,
                 drainController: ctx.drainController,
                 warmCache: ctx.warmCache,
                 sourcesRef: ctx.sourcesRef,
+                credentialWiring: ctx.credentialWiring,
                 onEvent: (event) => {
                     void ctx.eventSender.send(event).catch((cause) => {
                         logger.error `event-channel send failed during run ${payload.data.runId}: ${String(cause)}`;
                     });
                 },
+                upstreamSender: ctx.upstreamSender,
             });
             const handle = runtimeRun(ctx.definition, env, {
                 runId: payload.data.runId,
@@ -392,13 +624,12 @@ async function handleControlPayload(payload, ctx) {
                     cleanupRunStorage: ctx.bindings.cleanupRunStorage,
                     runId: payload.data.runId,
                 });
+                ctx.runsInFlight.delete(payload.data.runId);
                 return emitTerminalEvent(ctx.upstreamSender, result);
             })
                 .catch((cause) => {
-                logger.error `triggered run ${payload.data.runId} failed: ${String(cause)}`;
-            })
-                .finally(() => {
                 ctx.runsInFlight.delete(payload.data.runId);
+                logger.error `triggered run ${payload.data.runId} failed: ${String(cause)}`;
             });
             ctx.triggeredRunIds.push(payload.data.runId);
             return false;
@@ -432,7 +663,30 @@ async function handleControlPayload(payload, ctx) {
             ctx.credentialsRef.current = snapshot;
             return false;
         }
+        case "credentials-updated": {
+            // Merge the delivery into the live cell (see `mergeCredentialDelivery`):
+            // materials upsert by credentialId, bindings by (consumer, handle), and
+            // `revoke` drops named credentialIds plus any binding referencing them.
+            // Merge rather than wholesale-replace because the cell has several
+            // independently-scoped producers, so a swap would evict another
+            // producer's credentials. The result is assigned in one atomic
+            // whole-object swap, so a concurrent reader never observes a torn cell.
+            // The secret stays on this ref only; nothing here copies it into a
+            // snapshot, event, or state.
+            ctx.credentialMaterialRef.current = mergeCredentialDelivery(ctx.credentialMaterialRef.current, payload.data.delivery, payload.data.revoke);
+            return false;
+        }
         case "signal.deliver": {
+            // Drop a delivery for a run this child is not driving. The dispatch path
+            // only ever targets a live run id, but a stale or mis-routed frame -- a
+            // synthetic body-child id, or a run that crashed and has not been
+            // re-discovered -- must not commit an orphan `SignalReceived` to a log no
+            // awaiter is tailing. `runsInFlight` is the one-driver authority on which
+            // runs this child drives.
+            if (!ctx.runsInFlight.has(payload.data.runId)) {
+                logger.warn `signal.deliver for run ${payload.data.runId} which is not in flight; dropping (signalName=${payload.data.signalName})`;
+                return false;
+            }
             // Land the signal as a `SignalReceived` commit on the run's
             // event log. The signal-channel substrate's `subscribeKind`
             // peer (the per-run signal channel installed at run start) is
@@ -566,6 +820,13 @@ async function handleControlPayload(payload, ctx) {
             // `ready` or `recycle.request`.
             throw new Error("workflow-child received a `terminal.event` frame on its inbound control channel; this is a child-only upstream payload");
         }
+        case "park.notify": {
+            // `park.notify` is the child->supervisor suspension-notification
+            // frame; receiving one on the child's downstream side is a
+            // protocol violation in the same shape as a downstream
+            // `terminal.event`.
+            throw new Error("workflow-child received a `park.notify` frame on its inbound control channel; this is a child-only upstream payload");
+        }
         case "outbound.message": {
             // `outbound.message` is the child->supervisor outbound-mail
             // request frame; receiving one on the child's downstream side is a
@@ -585,6 +846,43 @@ async function handleControlPayload(payload, ctx) {
             ctx.outboundMailBridge.handleResult(payload.data);
             return false;
         }
+        case "mailbox.notify": {
+            // Route the supervisor's new-mail notification to the child's watch
+            // registry so a step agent's `watch`/`mail_wait` observes the arrival.
+            // A notify that lands without a registry means no watcher on the child
+            // side asked for inbound events; log and drop rather than throwing so
+            // the runtime keeps progressing (mirrors the `outbound.result` arm).
+            if (ctx.mailboxWatchRegistry === undefined) {
+                logger.warn `workflow-child mailbox.notify received without a watch registry wired; mailbox=${payload.data.mailbox} uid=${String(payload.data.uid)} dropped`;
+                return false;
+            }
+            ctx.mailboxWatchRegistry.fire(payload.data.mailbox, {
+                type: "exists",
+                uid: payload.data.uid,
+                headers: payload.data.headers,
+            });
+            return false;
+        }
+        case "mailbox.mutate.request": {
+            // `mailbox.mutate.request` is the child->supervisor mailbox-mutation
+            // request frame; receiving one on the child's downstream side is a
+            // protocol violation in the same shape as a downstream
+            // `outbound.message`.
+            throw new Error("workflow-child received a `mailbox.mutate.request` frame on its inbound control channel; this is a child-only upstream payload");
+        }
+        case "mailbox.mutate.response": {
+            // Route the supervisor's applied-mutation result to the
+            // mailbox-mutation bridge if one is wired. A response that lands
+            // without an active bridge means a stale supervisor frame for which
+            // no awaiter exists; log and drop rather than throwing so the
+            // runtime keeps progressing (mirrors the `outbound.result` arm).
+            if (ctx.mailboxMutationBridge === undefined) {
+                logger.warn `workflow-child mailbox.mutate.response received without a bridge wired; requestId=${payload.data.requestId} dropped`;
+                return false;
+            }
+            ctx.mailboxMutationBridge.handleResult(payload.data);
+            return false;
+        }
         case "substrate.merge.request": {
             // Route the request to the substrate-write bridge if one is
             // wired. A request that lands without an active bridge means a
@@ -609,6 +907,42 @@ async function handleControlPayload(payload, ctx) {
             ctx.substrateWriteBridge.handleWriteResponse(payload.data);
             return false;
         }
+        case "parked-correlations.request": {
+            // Answer the supervisor's re-registration enumeration from durable
+            // state. Awaiting inline is safe -- unlike `signal.deliver`, this
+            // reads (self-discovery + the snapshot binding) and sends one upstream
+            // reply without awaiting any downstream frame, so it cannot deadlock
+            // the iterator against a response it is itself blocking. A store
+            // inconsistency (an enumerated park with no durable snapshot, or no
+            // binding to recover one) throws out of the loop like the other
+            // invariant-violation arms rather than dropping a correlation the hub
+            // is waiting to register.
+            const parked = await collectParkedApprovalCorrelations({
+                substrate: ctx.bindings.substrate,
+                repoId: ctx.bindings.workflowRunRepoId,
+                runtimeRepoStore: ctx.runtimeRepoStore,
+                ...(ctx.bindings.loadParkedApproval !== undefined
+                    ? { loadParkedApproval: ctx.bindings.loadParkedApproval }
+                    : {}),
+            });
+            await ctx.upstreamSender.send({
+                type: "parked-correlations.response",
+                data: { requestId: payload.data.requestId, parked },
+            });
+            return false;
+        }
+        case "resumed.runs": {
+            // `resumed.runs` is the child->supervisor self-discovery report;
+            // receiving one on the child's downstream side is a protocol
+            // violation in the same shape as a downstream `ready`.
+            throw new Error("workflow-child received a `resumed.runs` frame on its inbound control channel; this is a child-only upstream payload");
+        }
+        case "parked-correlations.response": {
+            // `parked-correlations.response` is the child->supervisor reply frame;
+            // receiving one on the child's downstream side is a protocol violation
+            // in the same shape as a downstream `substrate.merge.response`.
+            throw new Error("workflow-child received a `parked-correlations.response` frame on its inbound control channel; this is a child-only upstream payload");
+        }
     }
 }
 /**
@@ -617,6 +951,28 @@ async function handleControlPayload(payload, ctx) {
  * shape; the substrate handle and per-deployment `RepoStore` adapter
  * are shared across runs.
  */
+/**
+ * Force-resolve every `action` handler ref reachable from these definitions
+ * against the resolver, so a missing action handler surfaces at establish
+ * rather than when the action is first invoked mid-run. Recurses into loop
+ * bodies (an action body is the common loop shape). The caller passes the
+ * lifted onTrigger/childWorkflow bodies separately, as with loop fns.
+ */
+function eagerlyResolveActionHandlers(definitions, actionResolver) {
+    const visit = (def) => {
+        for (const step of Object.values(def.steps)) {
+            if (step.kind === "action") {
+                // Throws (fail closed) if the handler names no export, or a non-function.
+                actionResolver(step.handler);
+            }
+            else if (step.kind === "loop") {
+                visit(step.body);
+            }
+        }
+    };
+    for (const def of definitions)
+        visit(def);
+}
 function buildRuntimeEnv(args) {
     const signalChannel = createWorkflowHostSignalChannel({
         repoStore: args.bindings.substrate,
@@ -635,6 +991,17 @@ function buildRuntimeEnv(args) {
         runId: args.runId,
         ref: args.bindings.workflowRunRef,
     });
+    // Reader for inbound-mail parts, a sibling of `blobs` over the same
+    // workflow-run repo. The step invoker resolves a `Mail` part's `ref` to its
+    // bytes through it at `agent.send` time; the supervisor committed the bytes
+    // before the trigger. Deployment-scoped (the ref encodes the owning run), so
+    // one reader resolves any run's parts.
+    const mailPartReader = createMailPartReader({
+        substrate: args.bindings.substrate,
+        repoId: args.bindings.workflowRunRepoId,
+        principal: args.bindings.principal,
+        ref: args.bindings.workflowRunRef,
+    });
     // Wrap the step invoker so every `InferenceEvent` the harness emits
     // funnels through the per-run `onEvent` closure, which forwards
     // the event up the HMAC-authenticated event channel. The wrap is
@@ -643,9 +1010,27 @@ function buildRuntimeEnv(args) {
     // `ChildStepInvoker` shape (carries onEvent), so the workflow-
     // runtime never has to know an event firehose exists.
     const invokeStep = async (req) => {
-        return args.bindings.invokeStep(req, args.onEvent, args.authorize, args.warmCache, args.sourcesRef);
+        return args.bindings.invokeStep(req, args.onEvent, args.authorize, args.warmCache, args.sourcesRef, args.credentialWiring, mailPartReader);
     };
-    return {
+    // Adapt the host binding (which takes the run's `onEvent` sink) down to the
+    // runtime's narrow `SpawnSuspendableChild` by injecting THIS run's event
+    // funnel -- the same closure `invokeStep` forwards -- so a body's live
+    // inference events ride the parent run's event channel to the hub stream
+    // (and inherit its loud-on-failure logging), while the runtime env keeps the
+    // narrow contract with no event slot. The run's live credential-material cell
+    // rides the same seam so the body's inference resolves its source secret
+    // against the parent's current delivery, reached live on a rotation.
+    const hostSuspendable = args.suspendableChildHost;
+    const spawnSuspendableChild = hostSuspendable === undefined
+        ? undefined
+        : (spawnInput) => hostSuspendable(spawnInput, args.onEvent, args.credentialWiring.materialRef);
+    // Same adaptation for the terminal childWorkflow seam: inject THIS run's event
+    // funnel so a child's live inference events ride the parent run's channel, and
+    // the live credential-material cell so the child's inference resolves its
+    // source secret against the parent's current delivery, while the runtime env
+    // keeps the narrow `SpawnChildWorkflow` (no event slot).
+    const spawnChild = (spawnInput) => args.spawnChild(spawnInput, args.onEvent, args.credentialWiring.materialRef);
+    const env = {
         repoStore: args.runtimeRepoStore,
         scheduler: args.bindings.scheduler,
         signalChannel,
@@ -653,11 +1038,148 @@ function buildRuntimeEnv(args) {
         directors: args.directors,
         authorize: args.authorize,
         invokeStep,
-        spawnChild: args.bindings.spawnChild,
+        spawnChild,
+        // The deployment's addressable run. Its parks are registered with the hub
+        // through the notify sink below, and a resolved decision is delivered back
+        // onto this run's own channel.
+        hasUpstreamSignalResolver: true,
+        // Resolve a loop's `while`/`carry` refs against the closure's loop module.
+        // Every ref was force-resolved at establish, so a lookup here cannot fail
+        // for a definition that passed startup.
+        loopFns: args.loopFns,
+        // Wire the suspendable-child seam only when the host supplied it; a child
+        // that never runs an onTrigger section omits the binding, and the runtime
+        // body fails loud if a workflow reaches a section the env did not wire.
+        ...(spawnSuspendableChild !== undefined ? { spawnSuspendableChild } : {}),
         clock: args.clock,
         newId: args.newId,
         drain: args.drainController,
+        // Forward a control-plane suspension up the same upstream control
+        // channel `terminal.event` rides, so the supervisor can stamp the
+        // deployment identity and register the correlation at the hub. The
+        // runtime body fires this once per fresh park on a reserved
+        // `signalName(correlationId)` channel.
+        onPark: (park) => {
+            void emitParkNotify(args.upstreamSender, park);
+        },
+        // Let the resume classifier recover a step that crashed across the park
+        // boundary. Absent (tests, the recursive child-workflow adapter) leaves a
+        // crashed invocation a terminal failure.
+        ...(args.bindings.readParkedApprovalOps !== undefined
+            ? { readParkedApprovalOps: args.bindings.readParkedApprovalOps }
+            : {}),
     };
+    // The suspendable-loop executor runs each iteration's body under THIS run's
+    // inherited env (its real tool-bearing invokeStep, invokeAction, credentials
+    // authorize, effect ledger, and durable shared repoStore/blobs), giving the
+    // body only its own substrate-backed signal channel -- the inherited-env
+    // iteration model plus park capability, distinct from an onTrigger body's
+    // fresh capped env. Resolved from the bodies map by ref (loop
+    // bodies were registered there at establish) and wrapped with this run's
+    // event funnel. Assigned AFTER env construction because it closes over `env`.
+    const loopIterationHost = createInMemorySpawnSuspendableChild({
+        bodies: args.bodiesMap,
+        runSuspendableChild: async (loopInput, _onEvent) => {
+            // Materialize this iteration's own grants file BEFORE the body runs (i.e.
+            // before `createLoopIterationHandle` drives the iteration's first event
+            // append), so a `childWorkflow` grandchild spawned from the body reads it
+            // as authority (the sidecar's runChild fails closed on a missing parent
+            // grants file). This ordering is LOAD-BEARING: the grants write is
+            // write-once and its shallow-prefix rebuild is safe only while the
+            // iteration run's subtree is still empty -- see `capAndPersistChildGrants`.
+            // The cap must walk the PRE-rewrite loop body (grandchild still inline);
+            // the rewritten body in `bodiesMap` would skip the grandchild's resources.
+            // Every loop body is registered in `loopBodyPreRewrite` at establish under
+            // the same ref the runtime dispatches, so a miss is a defect -- fail loud
+            // rather than silently skip, which would re-open the fail-closed
+            // grandchild spawn. The BINDING is a separate sidecar-only seam: `runLocal`
+            // keeps no per-run grants file (its grandchild spawn never fails closed),
+            // so it omits the binding, and an absent binding leaves the iteration's
+            // grants unmaterialized -- matching the in-process model with no disk
+            // authority.
+            const preRewriteBody = args.loopBodyPreRewrite.get(loopInput.definitionRef);
+            if (preRewriteBody === undefined) {
+                throw new Error(`workflow-child: loop iteration ${loopInput.childRunId} has no ` +
+                    `pre-rewrite body registered for ref ${loopInput.definitionRef}`);
+            }
+            await args.bindings.materializeLoopIterationGrants?.({
+                parentRunId: loopInput.parentRunId,
+                childRunId: loopInput.childRunId,
+                definition: preRewriteBody,
+            });
+            const childSignalChannel = createWorkflowHostSignalChannel({
+                repoStore: args.bindings.substrate,
+                principal: args.bindings.principal,
+                repoId: args.bindings.workflowRunRepoId,
+                ref: args.bindings.workflowRunRef,
+                runId: loopInput.childRunId,
+                readState: () => emptyState(loopInput.childRunId),
+                newId: () => args.newId("sig"),
+                clock: args.clock,
+            });
+            return createLoopIterationHandle(env, {
+                definition: loopInput.definition,
+                childRunId: loopInput.childRunId,
+                input: loopInput.input,
+                depth: loopInput.depth,
+                maxChildSpawnDepth: loopInput.maxChildSpawnDepth,
+                ...(loopInput.resumeFromEvents !== undefined
+                    ? { resumeFromEvents: loopInput.resumeFromEvents }
+                    : {}),
+                signal: loopInput.signal,
+                signalChannel: childSignalChannel,
+                cleanup: () => childSignalChannel.stop(),
+            });
+        },
+    });
+    env.spawnLoopIteration = (spawnInput) => loopIterationHost(spawnInput, args.onEvent);
+    // Action handlers run against a per-run effect ledger. The ledger is
+    // IN-MEMORY, and that is correct -- not a shortcut -- on the deployed store:
+    // appends are immediate-durable single-ref commits, `runAction` flushes
+    // StepStarted durably before the effect, and the runtime never re-invokes a
+    // crashed action (a mid-action crash settles the step failed; a loop-body
+    // action leaves a non-empty child log that fails the iteration loud rather
+    // than re-running). So the ledger is never consulted across a crash; its
+    // cross-crash exactly-once rests on that store-consistency invariant, which
+    // the store layer owns. A durable ledger here would re-enforce a constraint
+    // a lower layer already guarantees. Within a single invocation the ledger
+    // still dedups a handler that performs the same effect twice.
+    const effects = createInMemoryEffectLedger();
+    env.effects = effects;
+    env.invokeAction = createDefaultActionInvoker(args.authorize, effects, args.actionResolver);
+    return env;
+}
+/**
+ * Forward a control-plane suspension to the supervisor over the upstream
+ * control channel. Fired from `env.onPark` each time a workflow agent step
+ * parks on a reserved `signalName(correlationId)` channel. The supervisor's
+ * `park.notify` arm stamps the deployment identity it owns and sends a
+ * `signal.correlation.register` frame to the hub.
+ *
+ * Best-effort like `emitTerminalEvent`'s send: a transport failure is logged,
+ * not rethrown. A lost frame means the correlation is not registered and the
+ * parked run cannot be resumed until it is re-registered; the failure surfaces
+ * structurally as a run that never resumes rather than a silent lifecycle
+ * corruption. The register at the hub is idempotent, so a re-park resume's
+ * re-emit is safe.
+ */
+export function emitParkNotify(upstreamSender, park) {
+    return upstreamSender
+        .send({
+        type: "park.notify",
+        data: {
+            runId: park.runId,
+            correlationId: park.correlationId,
+            parkKind: park.parkKind,
+            ...(park.approvalSnapshot !== undefined
+                ? { snapshot: park.approvalSnapshot }
+                : {}),
+        },
+    })
+        .catch((cause) => {
+        const message = cause instanceof Error ? cause.message : String(cause);
+        logger.error `park.notify upstream send failed for runId=${park.runId} correlationId=${park.correlationId}: ${message}`;
+    });
 }
 /**
  * Mirror a run's terminal status back to the supervisor over the
@@ -780,114 +1302,6 @@ function reclaimRunStorageIfCold(opts) {
         logger.warn `workflow-step-state cleanup failed for runId=${opts.runId}: ${message}`;
     });
 }
-/**
- * Resolve the run's trigger payload from the inbound mail message the
- * supervisor moved to the claim-check processing queue. Reads the
- * processing entry by messageId (a read-only snapshot of the
- * `refs/heads/events` tip that cannot race the supervisor's
- * `markConsumed` write), decodes the inlined raw MIME bytes, and
- * extracts the conversation text the agent's `agent.send` receives.
- *
- * Defensive: a missing processing entry, an entry with no inlined
- * bytes, or unparseable mail all throw. The run cannot proceed without
- * its input, and a placeholder would mask a mailbox-ownership failure.
- */
-async function resolveTriggerPayload(args) {
-    const entry = await readProcessingEntry(args.substrate, args.principal, args.workflowRunRepoId, args.mailboxAddress, args.messageId);
-    if (entry === null) {
-        throw new Error(`workflow-child trigger.fire: no claim-check processing entry for messageId ${args.messageId} at ${args.mailboxAddress}; the run has no input to deliver to the agent`);
-    }
-    const rawMessageBase64 = entry.envelope.rawMessage;
-    if (rawMessageBase64 === undefined) {
-        throw new Error(`workflow-child trigger.fire: processing entry for messageId ${args.messageId} carries no inlined rawMessage; the supervisor must inline the inbound mail bytes for the child to deliver them as the step input`);
-    }
-    const raw = base64Decode(rawMessageBase64);
-    return extractConversationText(raw, args.messageId);
-}
-/**
- * Extract the conversation body text from a raw inbound MIME message.
- *
- * Three on-wire shapes are handled, matching every producer the mail
- * bus accepts:
- *   1. The Interchange assembler's `multipart/signed` envelope whose
- *      first part is a `multipart/mixed` body carrying the text at part
- *      path `1.1`.
- *   2. A `multipart/signed` envelope wrapping a bare `text/plain` part
- *      (a sender that signs without the `multipart/mixed` wrapper); the
- *      text is at part path `1`.
- *   3. A flat top-level `text/plain` message (no multipart structure at
- *      all); the body is the bytes after the header section.
- *
- * The top-level `Content-Type` selects the shape: only a `multipart/*`
- * root walks into parts; anything else reads the single body directly.
- * This mirrors the conversation branch of mail-memory's `fetchFull`
- * while also tolerating the flat single-part case the in-process agent
- * accepts, so a non-standard inbound mail still delivers its text to
- * the agent rather than crashing the run.
- */
-function extractConversationText(raw, messageId) {
-    const { headers, bodyOffset } = parseHeaderSection(raw);
-    const rootMime = (headers.get("content-type") ?? "")
-        .split(";")[0]
-        ?.trim()
-        .toLowerCase();
-    if (rootMime === undefined || !rootMime.startsWith("multipart/")) {
-        // Flat single-part message: the body is everything after the
-        // header section.
-        return new TextDecoder("utf-8", { fatal: false }).decode(raw.subarray(bodyOffset));
-    }
-    let part1;
-    try {
-        part1 = parseMimePart(extractPartByPath(raw, "1"));
-    }
-    catch (cause) {
-        throw new Error(`workflow-child trigger.fire: cannot parse inbound mail part 1 for messageId ${messageId}`, { cause });
-    }
-    const part1Mime = (part1.contentType.split(";")[0] ?? "")
-        .trim()
-        .toLowerCase();
-    const bodyBytes = part1Mime.startsWith("multipart/")
-        ? parseMimePart(extractPartByPath(raw, "1.1")).body
-        : part1.body;
-    return new TextDecoder("utf-8", { fatal: false }).decode(bodyBytes);
-}
-/**
- * Load the `WorkflowDefinition` from the workflow asset repo's deploy
- * ref. Mirrors the sibling `spawn-child` adapter's working-tree-read
- * pattern -- the deploy orchestrator's `writeTree` materializes
- * `workflow.json` under the substrate's repo dir, so a flat
- * `fs.readFile` returns the bytes without round-tripping through git.
- */
-async function loadWorkflowDefinition(bindings) {
-    const fs = await import("node:fs/promises");
-    const path = await import("node:path");
-    const dir = bindings.substrate.getRepoDir(bindings.workflowDefinitionRepoId);
-    const workflowPath = path.join(dir, WORKFLOW_JSON_PATH);
-    let raw;
-    try {
-        raw = await fs.readFile(workflowPath, "utf8");
-    }
-    catch (cause) {
-        throw new Error(`workflow-child: cannot read ${WORKFLOW_JSON_PATH} for ${bindings.workflowDefinitionRepoId.kind}/${bindings.workflowDefinitionRepoId.id} on ${bindings.workflowDefinitionRef}`, { cause });
-    }
-    let parsed;
-    try {
-        parsed = JSON.parse(raw);
-    }
-    catch (cause) {
-        throw new Error(`workflow-child: ${WORKFLOW_JSON_PATH} for ${bindings.workflowDefinitionRepoId.kind}/${bindings.workflowDefinitionRepoId.id} on ${bindings.workflowDefinitionRef} is not valid JSON`, { cause });
-    }
-    const validated = workflowDefinitionEnvelopeSchema(parsed);
-    if (validated instanceof type.errors) {
-        throw new Error(`workflow-child: ${WORKFLOW_JSON_PATH} for ${bindings.workflowDefinitionRepoId.kind}/${bindings.workflowDefinitionRepoId.id} on ${bindings.workflowDefinitionRef} failed envelope validation: ${validated.summary}`);
-    }
-    // The envelope schema enforces the structural shape; the
-    // discriminated narrow over every primitive variant lives downstream
-    // in the runtime body. The sibling `spawn-child` adapter follows the
-    // same pattern at the same boundary.
-    // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- envelope schema enforces structural shape; primitive narrows live downstream in the runtime body
-    return validated;
-}
 function defaultClock() {
     return new Date();
 }