@intx/workflow-host 0.3.0 → 0.4.0

package/dist/child/mailbox-mutation-bridge.js

@@ -0,0 +1,101 @@
+// Child-side mailbox-mutation bridge (INBOUND half of mailbox ownership,
+// §3b).
+//
+// The supervisor is the sole mail owner: it holds the long-lived
+// substrate mailbox store and is the only writer to the workflow-run
+// ref. A step agent reads its INBOX locally (the supervisor-backed
+// transport's read surface opens fresh committed snapshots), but every
+// MUTATION of the mailbox -- flag writes (`\Seen`, `\Deleted`, ...) and
+// `expunge` -- routes up to the supervisor through this bridge rather
+// than being flushed from the child. A second writer flushing the same
+// ref from the child would race the supervisor's in-memory mirror and
+// break uid / modseq monotonicity, so the child never writes the
+// mailbox directly.
+//
+// Lifecycle of one mutation:
+//
+//   1. The agent's mail tool (flag or expunge) calls the
+//      supervisor-backed transport's `setFlags` / `clearFlags` /
+//      `expunge`. The transport calls `bridge.submit(mutation)`.
+//   2. `submit` mints a `requestId`, registers a pending awaiter, and
+//      emits `mailbox.mutate.request` upstream carrying the op and its
+//      operands.
+//   3. The supervisor applies the op to its owned mailbox store,
+//      flushes, and replies with `mailbox.mutate.response`. The reply is
+//      sent only after the flush, so the child's next committed read
+//      observes the mutation (the same flush-before-signal ordering
+//      `mailbox.notify` relies on).
+//   4. The bridge resolves / rejects the pending awaiter; the
+//      transport method returns to the mail tool. A supervisor-side
+//      failure (unknown uid, substrate fault) surfaces as a rejection so
+//      the agent's mail-tool call fails loudly rather than silently
+//      dropping the mutation.
+import { getLogger } from "@intx/log";
+import { createPendingRequestCore } from "./pending-request.js";
+const logger = getLogger(["workflow-host", "child", "mailbox-mutation-bridge"]);
+/**
+ * Construct the child-side mailbox-mutation bridge. Pending mutations
+ * live in the shared pending-request core keyed by `requestId`; the
+ * bridge resolves the awaiter when the supervisor's matching
+ * `mailbox.mutate.response` lands.
+ */
+export function createChildMailboxMutationBridge(opts) {
+    const pending = createPendingRequestCore({
+        label: "workflow-child mailbox mutation",
+        allocatorPrefix: "mm",
+        allocateRequestId: opts.allocateRequestId,
+    });
+    return {
+        get pendingCount() {
+            return pending.pendingCount;
+        },
+        async submit(mutation) {
+            const { requestId, promise } = pending.register(undefined);
+            const data = mutation.op === "expunge"
+                ? {
+                    requestId,
+                    runId: mutation.runId,
+                    mailbox: mutation.mailbox,
+                    op: mutation.op,
+                }
+                : {
+                    requestId,
+                    runId: mutation.runId,
+                    mailbox: mutation.mailbox,
+                    op: mutation.op,
+                    uid: mutation.uid,
+                    flags: mutation.flags,
+                };
+            try {
+                await opts.upstreamSender.send({
+                    type: "mailbox.mutate.request",
+                    data,
+                });
+            }
+            catch (cause) {
+                pending.discard(requestId);
+                throw pending.sendFailedError(requestId, cause);
+            }
+            return promise;
+        },
+        handleResult(data) {
+            const entry = pending.settle(data.requestId);
+            if (entry === undefined) {
+                logger.warn `mailbox.mutate.response landed with no pending entry; requestId=${data.requestId} dropped`;
+                return;
+            }
+            if (data.result.ok) {
+                const result = {};
+                if (data.result.expungedUids !== undefined) {
+                    result.expungedUids = data.result.expungedUids;
+                }
+                entry.resolve(result);
+                return;
+            }
+            entry.reject(pending.rejectedError(data.requestId, data.result.reason));
+        },
+        cancelAll(reason) {
+            pending.cancelAll(reason);
+        },
+    };
+}

package/dist/child/mailbox-watch-registry.d.ts

@@ -0,0 +1,17 @@
+import type { MailboxEvent, Unsubscribe } from "@intx/types/runtime";
+export interface MailboxWatchRegistry {
+    /**
+     * Register a callback for a mailbox. Returns an `Unsubscribe` that removes
+     * it; after unsubscribe the callback observes no further events, including
+     * one whose `fire` preceded the unsubscribe but whose asynchronous delivery
+     * had not yet run.
+     */
+    watch(mailbox: string, callback: (event: MailboxEvent) => void): Unsubscribe;
+    /**
+     * Deliver a `MailboxEvent` to every callback currently registered for the
+     * mailbox, each on its own microtask. A no-op when no callback is registered
+     * for the mailbox.
+     */
+    fire(mailbox: string, event: MailboxEvent): void;
+}
+export declare function createMailboxWatchRegistry(): MailboxWatchRegistry;

package/dist/child/mailbox-watch-registry.js

@@ -0,0 +1,61 @@
+// Child-side mailbox watch registry (INBOUND half of mailbox ownership,
+// design §3b).
+//
+// The supervisor is the sole mail owner: it commits an arrived message to the
+// workflow-run substrate mailbox and fires a `mailbox.notify` control frame.
+// The child's control loop routes that frame to this registry's `fire`, which
+// delivers a typed `exists` `MailboxEvent` to every callback registered for the
+// mailbox through `watch`. The step agent's supervisor-backed transport
+// implements `MessageTransport.watch` over this registry, so `mail_wait`
+// unblocks when new mail lands -- decoupled from the FIFO trigger dispatch that
+// resolves a run's first input.
+//
+// Delivery is ASYNCHRONOUS. A `fire` never invokes a callback synchronously on
+// the delivering call stack: it schedules each callback on a microtask, per the
+// IMAP IDLE contract the `MailboxEvent` watcher models (MESSAGE.md § Real-Time
+// Notification). Delivery re-checks registration at the microtask, so a watcher
+// that unsubscribes between `fire` and delivery observes no event.
+export function createMailboxWatchRegistry() {
+    const watchers = new Map();
+    return {
+        watch(mailbox, callback) {
+            let set = watchers.get(mailbox);
+            if (set === undefined) {
+                set = new Set();
+                watchers.set(mailbox, set);
+            }
+            set.add(callback);
+            let active = true;
+            return () => {
+                // Idempotent: a double-unsubscribe must not remove a same-identity
+                // callback a later `watch` re-registered.
+                if (!active)
+                    return;
+                active = false;
+                const current = watchers.get(mailbox);
+                if (current === undefined)
+                    return;
+                current.delete(callback);
+                if (current.size === 0)
+                    watchers.delete(mailbox);
+            };
+        },
+        fire(mailbox, event) {
+            const set = watchers.get(mailbox);
+            if (set === undefined)
+                return;
+            // Snapshot the callbacks registered at fire time, then deliver each on
+            // its own microtask so no callback runs synchronously on this call
+            // stack. Re-check membership at delivery so a callback unsubscribed
+            // between now and its microtask does not receive the event.
+            for (const callback of [...set]) {
+                queueMicrotask(() => {
+                    const current = watchers.get(mailbox);
+                    if (current === undefined || !current.has(callback))
+                        return;
+                    callback(event);
+                });
+            }
+        },
+    };
+}

package/dist/child/outbound-mail-bridge.d.ts

@@ -30,7 +30,8 @@ export interface CreateChildOutboundMailBridgeOpts {
 }
 /**
  * Construct the child-side outbound-mail bridge. Pending sends live in
- * a map keyed by `requestId`; the bridge resolves the awaiter when the
- * supervisor's matching `outbound.result` lands.
+ * the shared pending-request core keyed by `requestId`; the bridge
+ * resolves the awaiter when the supervisor's matching `outbound.result`
+ * lands.
  */
 export declare function createChildOutboundMailBridge(opts: CreateChildOutboundMailBridgeOpts): ChildOutboundMailBridge;

package/dist/child/outbound-mail-bridge.js

@@ -32,24 +32,26 @@
 //      send.
 import { getLogger } from "@intx/log";
 import { base64Encode } from "@intx/types";
+import { createPendingRequestCore } from "./pending-request.js";
 const logger = getLogger(["workflow-host", "child", "outbound-mail-bridge"]);
 /**
  * Construct the child-side outbound-mail bridge. Pending sends live in
- * a map keyed by `requestId`; the bridge resolves the awaiter when the
- * supervisor's matching `outbound.result` lands.
+ * the shared pending-request core keyed by `requestId`; the bridge
+ * resolves the awaiter when the supervisor's matching `outbound.result`
+ * lands.
  */
 export function createChildOutboundMailBridge(opts) {
-    const pending = new Map();
-    const allocate = opts.allocateRequestId ?? defaultRequestIdAllocator();
+    const pending = createPendingRequestCore({
+        label: "workflow-child outbound mail",
+        allocatorPrefix: "om",
+        allocateRequestId: opts.allocateRequestId,
+    });
     return {
         get pendingCount() {
-            return pending.size;
+            return pending.pendingCount;
         },
         async submit(senderAddress, message) {
-            const requestId = allocate();
-            const resultPromise = new Promise((resolve, reject) => {
-                pending.set(requestId, { resolve, reject });
-            });
+            const { requestId, promise } = pending.register(undefined);
             try {
                 await opts.upstreamSender.send({
                     type: "outbound.message",
@@ -61,19 +63,17 @@ export function createChildOutboundMailBridge(opts) {
                 });
             }
             catch (cause) {
-                pending.delete(requestId);
-                const reason = cause instanceof Error ? cause.message : String(cause);
-                throw new Error(`workflow-child outbound mail: upstream send failed for requestId ${requestId}: ${reason}`, { cause });
+                pending.discard(requestId);
+                throw pending.sendFailedError(requestId, cause);
             }
-            return resultPromise;
+            return promise;
         },
         handleResult(data) {
-            const entry = pending.get(data.requestId);
+            const entry = pending.settle(data.requestId);
             if (entry === undefined) {
                 logger.warn `outbound.result landed with no pending entry; requestId=${data.requestId} dropped`;
                 return;
             }
-            pending.delete(data.requestId);
             if (data.result.ok) {
                 entry.resolve({
                     messageId: data.result.messageId,
@@ -81,13 +81,10 @@ export function createChildOutboundMailBridge(opts) {
                 });
                 return;
             }
-            entry.reject(new Error(`workflow-child outbound mail (requestId=${data.requestId}) rejected by supervisor: ${data.result.reason}`));
+            entry.reject(pending.rejectedError(data.requestId, data.result.reason));
         },
         cancelAll(reason) {
-            for (const [requestId, entry] of pending) {
-                entry.reject(new Error(`workflow-child outbound mail (requestId=${requestId}) cancelled: ${reason}`));
-            }
-            pending.clear();
+            pending.cancelAll(reason);
         },
     };
 }
@@ -114,6 +111,8 @@ function projectOutboundMessage(message) {
         payload.summary = message.summary;
     if (message.inReplyTo !== undefined)
         payload.inReplyTo = message.inReplyTo;
+    if (message.references !== undefined)
+        payload.references = message.references;
     if (message.correlationId !== undefined) {
         payload.correlationId = message.correlationId;
     }
@@ -125,19 +124,8 @@ function projectOutboundMessage(message) {
         payload.attachments = message.attachments.map((a) => ({
             name: a.name,
             contentType: a.contentType,
-            dataBase64: bytesToBase64(a.data),
+            dataBase64: base64Encode(a.data),
         }));
     }
     return payload;
 }
-function bytesToBase64(bytes) {
-    return base64Encode(bytes);
-}
-function defaultRequestIdAllocator() {
-    let counter = 0;
-    return () => {
-        counter += 1;
-        const rand = Math.random().toString(36).slice(2, 10);
-        return `om-${String(counter)}-${rand}`;
-    };
-}

package/dist/child/pending-request.d.ts

@@ -0,0 +1,89 @@
+/**
+ * A live pending entry as returned by {@link PendingRequestCore.get} and
+ * {@link PendingRequestCore.settle}. `meta` is the per-bridge payload the
+ * entry was registered with (e.g. the substrate-write request whose merge
+ * closure the merge round-trip invokes).
+ */
+export type PendingEntryHandle<Value, Meta> = {
+    meta: Meta;
+    resolve: (value: Value) => void;
+    reject: (err: Error) => void;
+};
+/**
+ * Options for {@link createPendingRequestCore}. `label` prefixes every
+ * error the core builds (`<label>: upstream send failed for requestId
+ * <id>: ...`, `<label> (requestId=<id>) rejected by supervisor: ...`,
+ * `<label> (requestId=<id>) cancelled: ...`, `<label>: no pending entry
+ * for requestId <id>`), so each bridge's observable error strings stay
+ * its own. `allocatorPrefix` seeds the default requestId allocator
+ * (`<prefix>-<counter>-<rand>`); tests inject `allocateRequestId` for a
+ * deterministic id.
+ */
+export type PendingRequestCoreOptions = {
+    label: string;
+    allocatorPrefix: string;
+    /** `undefined` is accepted explicitly so callers can forward an optional option verbatim. */
+    allocateRequestId?: (() => string) | undefined;
+};
+/**
+ * The pending-request lifecycle surface a bridge composes into its own
+ * `submit` / `handle*` / `cancelAll` methods.
+ */
+export type PendingRequestCore<Value, Meta = undefined> = {
+    /** Number of registered-but-unsettled requests. */
+    readonly pendingCount: number;
+    /**
+     * Mint a requestId, register an awaiter keyed by it, and return the id
+     * plus the promise the bridge returns from its `submit`. The entry
+     * stays pending until `settle` or `cancelAll` acts on it, or `discard`
+     * removes it without settling (the upstream-send-failure path).
+     */
+    register(meta: Meta): {
+        requestId: string;
+        promise: Promise<Value>;
+    };
+    /**
+     * Remove a pending entry without settling its promise. Used when the
+     * upstream send itself fails, so the abandoned awaiter does not leak.
+     */
+    discard(requestId: string): void;
+    /**
+     * Look up a pending entry WITHOUT removing it. Used by the
+     * substrate-write bridge's merge round-trip, which must reach the
+     * entry's merge closure while the entry stays alive for the terminal
+     * write response.
+     */
+    get(requestId: string): PendingEntryHandle<Value, Meta> | undefined;
+    /**
+     * Look up a pending entry and remove it. Used by the response-frame
+     * handlers: the entry is gone before its promise resolves/rejects, so
+     * a later stale response or `cancelAll` finds nothing to act on.
+     */
+    settle(requestId: string): PendingEntryHandle<Value, Meta> | undefined;
+    /**
+     * Reject every pending entry with `<label> (requestId=<id>) cancelled:
+     * <reason>` and clear the map. The control loop invokes this on any
+     * exit path so no awaiter leaks when the supervisor has torn the IPC
+     * down.
+     */
+    cancelAll(reason: string): void;
+    /** `<label>: upstream send failed for requestId <id>: <cause message>` with `{ cause }`. */
+    sendFailedError(requestId: string, cause: unknown): Error;
+    /** `<label> (requestId=<id>) rejected by supervisor: <reason>`. */
+    rejectedError(requestId: string, reason: string): Error;
+    /** `<label>: no pending entry for requestId <id>` (substrate merge failure reply). */
+    noPendingError(requestId: string): Error;
+};
+/**
+ * Construct a pending-request core for one bridge. Pending entries live in
+ * a map keyed by `requestId`; the bridge's response handler settles the
+ * awaiter when the matching response frame lands.
+ */
+export declare function createPendingRequestCore<Value, Meta = undefined>(opts: PendingRequestCoreOptions): PendingRequestCore<Value, Meta>;
+/**
+ * Default `requestId` allocator: a per-instance monotonic counter plus a
+ * random suffix, so ids are unique across bridge instances without any
+ * cross-instance coordination. The `prefix` names the owning bridge
+ * (`sw-`, `om-`, `mm-`) for triage in supervisor logs.
+ */
+export declare function defaultRequestIdAllocator(prefix: string): () => string;

package/dist/child/pending-request.js

@@ -0,0 +1,80 @@
+// Generic pending-request core shared by the three child-side control-IPC
+// bridges (substrate-write, outbound-mail, mailbox-mutation).
+//
+// Every bridge runs the same request/response round-trip over the control
+// channel: `submit` mints a `requestId`, registers a pending awaiter keyed
+// by that id, emits a request frame upstream, and resolves/rejects the
+// awaiter when the supervisor's matching response frame lands. The three
+// bridges differ only in the request payload they send, the value they
+// resolve, the label their error messages carry, and (for the
+// substrate-write bridge) an intermediate merge round-trip that must peek
+// at the pending entry without settling it.
+//
+// This core owns that lifecycle in one place so the per-bridge files
+// contain only their wire-specific parts. It never touches the control
+// channel itself: each bridge performs its own `upstreamSender.send` so
+// the frame payloads stay byte-identical to what the supervisor's
+// `ControlPayload` validator expects.
+/**
+ * Construct a pending-request core for one bridge. Pending entries live in
+ * a map keyed by `requestId`; the bridge's response handler settles the
+ * awaiter when the matching response frame lands.
+ */
+export function createPendingRequestCore(opts) {
+    const pending = new Map();
+    const allocate = opts.allocateRequestId ?? defaultRequestIdAllocator(opts.allocatorPrefix);
+    return {
+        get pendingCount() {
+            return pending.size;
+        },
+        register(meta) {
+            const requestId = allocate();
+            const promise = new Promise((resolve, reject) => {
+                pending.set(requestId, { meta, resolve, reject });
+            });
+            return { requestId, promise };
+        },
+        discard(requestId) {
+            pending.delete(requestId);
+        },
+        get(requestId) {
+            return pending.get(requestId);
+        },
+        settle(requestId) {
+            const entry = pending.get(requestId);
+            if (entry !== undefined)
+                pending.delete(requestId);
+            return entry;
+        },
+        cancelAll(reason) {
+            for (const [requestId, entry] of pending) {
+                entry.reject(new Error(`${opts.label} (requestId=${requestId}) cancelled: ${reason}`));
+            }
+            pending.clear();
+        },
+        sendFailedError(requestId, cause) {
+            const reason = cause instanceof Error ? cause.message : String(cause);
+            return new Error(`${opts.label}: upstream send failed for requestId ${requestId}: ${reason}`, { cause });
+        },
+        rejectedError(requestId, reason) {
+            return new Error(`${opts.label} (requestId=${requestId}) rejected by supervisor: ${reason}`);
+        },
+        noPendingError(requestId) {
+            return new Error(`${opts.label}: no pending entry for requestId ${requestId}`);
+        },
+    };
+}
+/**
+ * Default `requestId` allocator: a per-instance monotonic counter plus a
+ * random suffix, so ids are unique across bridge instances without any
+ * cross-instance coordination. The `prefix` names the owning bridge
+ * (`sw-`, `om-`, `mm-`) for triage in supervisor logs.
+ */
+export function defaultRequestIdAllocator(prefix) {
+    let counter = 0;
+    return () => {
+        counter += 1;
+        const rand = Math.random().toString(36).slice(2, 10);
+        return `${prefix}-${String(counter)}-${rand}`;
+    };
+}

package/dist/child/run-child.d.ts

@@ -1,8 +1,8 @@
 import type { Principal, RepoId, RepoStore as SubstrateRepoStore } from "@intx/hub-sessions/substrate";
 import type { AuthzCallResult } from "@intx/inference";
-import type { RunResult, Scheduler, ReadParkedApprovalOps, StepInvokeRequest, StepInvokeResult, SpawnChildWorkflow, WorkflowAuthorizeFn, WorkflowPark } from "@intx/workflow";
+import type { RunResult, Scheduler, ReadParkedApprovalOps, StepInvokeRequest, StepInvokeResult, SpawnChildWorkflow, WorkflowAuthorizeFn, WorkflowDefinition, WorkflowPark } from "@intx/workflow";
 import { type WorkflowHostDrainController } from "../drain-controller.js";
-import type { InferenceSource } from "@intx/types/runtime";
+import type { InferenceSource, MailPartReader } from "@intx/types/runtime";
 import type { CredentialDelivery } from "@intx/types/sidecar";
 import type { RunSuspendableChild, RunChildWorkflow } from "../adapters/spawn-child.js";
 import { type ControlChannelSender, type ControlPayload, type EventPayload, type FrameWriter, type NdjsonReader, type NdjsonWriter } from "../ipc/index.js";
@@ -11,6 +11,8 @@ import { hashGrants } from "../supervisor/credentials.js";
 import type { SpawnTimeEnv } from "./env-bootstrap.js";
 import { type LoadParkedApproval } from "./parked-correlations.js";
 import type { ChildOutboundMailBridge } from "./outbound-mail-bridge.js";
+import type { ChildMailboxMutationBridge } from "./mailbox-mutation-bridge.js";
+import type { MailboxWatchRegistry } from "./mailbox-watch-registry.js";
 import { type WarmAgentCache } from "./warm-agent-cache.js";
 /**
  * `WorkflowAuthorize` closure factory shape. The child's authorize
@@ -31,10 +33,12 @@ export type CredentialsSnapshotRef = {
 };
 /**
  * The deployment's decrypted credential material and per-handle descriptors,
- * held through a mutable reference and swapped wholesale on a rotation push (a
- * revoked credential arrives by omission, so the swap evicts it). The secret
- * lives ONLY here -- read at tool-invoke time through the gated capability --
- * and is never copied into a snapshot, event, or state.
+ * held through a mutable reference. A `credentials-updated` frame MERGES into
+ * this cell (materials by credentialId, bindings by (consumer, handle); an
+ * explicit `revoke` list drops entries) rather than replacing it wholesale,
+ * because the cell has several independently-scoped producers. The secret lives
+ * ONLY here -- read at tool-invoke time through the gated capability -- and is
+ * never copied into a snapshot, event, or state.
  */
 export type CredentialMaterialRef = {
     current: CredentialDelivery | null;
@@ -121,7 +125,7 @@ export interface CredentialWiring {
     readonly materialRef: CredentialMaterialRef;
     readonly resolveStepGrants: (stepId: string) => readonly unknown[];
 }
-export type ChildStepInvoker = (req: StepInvokeRequest, onEvent: (event: EventPayload) => void, authorize: WorkflowAuthorizeFn, warmCache: WarmAgentCache | undefined, sourcesRef: SourcesSnapshotRef, credentialWiring: CredentialWiring) => Promise<StepInvokeResult>;
+export type ChildStepInvoker = (req: StepInvokeRequest, onEvent: (event: EventPayload) => void, authorize: WorkflowAuthorizeFn, warmCache: WarmAgentCache | undefined, sourcesRef: SourcesSnapshotRef, credentialWiring: CredentialWiring, mailPartReader: MailPartReader) => Promise<StepInvokeResult>;
 /**
  * Bindings the binary owns: per-deployment substrate identity,
  * principal credentials, the runtime-supplied callbacks the
@@ -180,6 +184,24 @@ export interface RunWorkflowChildBindings {
      * that runs no onTrigger section omits it.
      */
     runSuspendableChild?: RunSuspendableChild;
+    /**
+     * Materialize a loop iteration run's own `runs/<childRunId>/grants.json`,
+     * inheriting the parent (container) run's grants capped to the loop body's
+     * declared resources. A loop iteration runs through the workflow-host-local
+     * loop executor (the inherited env), NOT the sidecar's `buildChildRunEnv`, so
+     * it is the one body birth path that does not otherwise write its own grants
+     * file -- and without it the body's `childWorkflow` grandchild spawn is
+     * refused as under-authorized. Wired by the sidecar (the grant-cap helpers
+     * live there); optional so a test or an in-process host that never spawns a
+     * grandchild from a loop body can omit it. `definition` MUST be the PRE-rewrite
+     * loop body (grandchild still inline) so the cap keeps the grandchild's
+     * declared resources.
+     */
+    materializeLoopIterationGrants?: (args: {
+        parentRunId: string;
+        childRunId: string;
+        definition: WorkflowDefinition;
+    }) => Promise<void>;
     /** Host-process scheduler singleton. The child consumes the same instance. */
     scheduler: Scheduler;
     /** Grant evaluator wired against the host's grant-rule grammar. */
@@ -225,6 +247,19 @@ export interface RunWorkflowChildBindings {
      * invocation step settles as a terminal failure, the pre-recovery behavior.
      */
     readParkedApprovalOps?: ReadParkedApprovalOps;
+    /**
+     * Mailbox watch registry backing the warm agent's `mail_wait` (INBOUND half
+     * of mailbox ownership, §3b). The host's substrate factory builds ONE
+     * instance at child boot, shares it with the step agent's supervisor-backed
+     * transport (whose `watch` registers callbacks into it), and exposes it here
+     * so the control loop routes each `mailbox.notify` frame to the same
+     * registry's `fire`. Optional: a deploy that wires no mail surface (and the
+     * recursive child-workflow adapter) omits it, and an inbound `mailbox.notify`
+     * frame is then logged and dropped. A test may instead inject a registry
+     * directly through `RunWorkflowChildOpts.mailboxWatchRegistry`, which takes
+     * precedence.
+     */
+    mailboxWatchRegistry?: MailboxWatchRegistry;
     /** Optional clock override; production wires `() => new Date()`. */
     clock?: () => Date;
     /** Optional id generator override; production wires a monotonic one. */
@@ -328,6 +363,33 @@ export interface RunWorkflowChildOpts {
      * but no agent on the child side asked for an outbound send.
      */
     outboundMailBridge?: ChildOutboundMailBridge;
+    /**
+     * Optional mailbox-mutation bridge (INBOUND half of mailbox ownership,
+     * §3b). The step agent's mail tools mutate the INBOX -- flag writes and
+     * `expunge` -- through a transport whose write methods route through
+     * this bridge: it emits a `mailbox.mutate.request` upstream control
+     * frame and resolves once the supervisor's matching
+     * `mailbox.mutate.response` lands. The control loop routes the
+     * downstream response frame to the bridge's `handleResult` and invokes
+     * `cancelAll` on any exit path so a pending mutation does not leak an
+     * awaiter after the supervisor tears the IPC down. When omitted,
+     * inbound `mailbox.mutate.response` frames are logged at warn-level and
+     * dropped -- the wire shape is well-formed but no agent on the child
+     * side asked for a mutation.
+     */
+    mailboxMutationBridge?: ChildMailboxMutationBridge;
+    /**
+     * Optional mailbox watch registry (INBOUND half of mailbox ownership,
+     * design §3b). The supervisor -- the sole mail owner -- commits an arrived
+     * message to the workflow-run substrate mailbox and fires a `mailbox.notify`
+     * control frame; the control loop routes that frame to this registry's
+     * `fire`, which delivers a typed `exists` `MailboxEvent` to the callbacks the
+     * step agent's supervisor-backed transport registered through `watch`
+     * (backing `mail_wait`). When omitted, an inbound `mailbox.notify` frame is
+     * logged at warn-level and dropped -- the wire shape is well-formed but no
+     * watcher on the child side asked for inbound events.
+     */
+    mailboxWatchRegistry?: MailboxWatchRegistry;
 }
 /**
  * Narrow interface the child's control loop calls when downstream