@intx/workflow-host 0.2.2 → 0.4.0

package/dist/ipc/control-channel.js

@@ -35,7 +35,8 @@
 // prevented at the type level by the disjoint discriminated union.
 import { type } from "arktype";
 import { hexDecode, hexEncode } from "@intx/types";
-import { InferenceSource, InterchangeType } from "@intx/types/runtime";
+import { BoundedApprovalSnapshot, ControlParkKind, InferenceSource, InterchangeType, } from "@intx/types/runtime";
+import { CredentialDelivery } from "@intx/types/sidecar";
 import { decodeEnvelope, encodeEnvelope, FrameEnvelope, SignedEnvelope, } from "./envelope.js";
 import { signEd25519, verifyEd25519 } from "./crypto.js";
 /**
@@ -126,10 +127,43 @@ export const OutboundMessagePayload = type({
     "summary?": "string",
     "attachments?": OutboundAttachmentPayload.array(),
     "inReplyTo?": "string",
+    "references?": "string[]",
     "correlationId?": "string",
     "sessionId?": "string",
     "tenantId?": "string",
 });
+/**
+ * Wire shape of the parsed `MessageHeaders` the supervisor rides inline on a
+ * `mailbox.notify` frame. Mirrors `@intx/types/runtime`'s `MessageHeaders`
+ * field-for-field so a child watcher gets the arrived message's envelope for
+ * its `exists` `MailboxEvent` without a substrate round-trip. The four
+ * unconditionally-dereferenced fields (`from`, `to`, `date`, `messageId`) are
+ * required; the rest are optional, matching the runtime type.
+ *
+ * Duplicated here as an arktype validator (rather than importing the TypeScript
+ * `MessageHeaders` type) so the IPC module validates the header block at the
+ * wire boundary, exactly as `OutboundMessagePayload` does for outbound mail.
+ */
+export const MailboxNotifyHeaders = type({
+    from: "string",
+    to: "string[]",
+    "cc?": "string[]",
+    date: "string",
+    messageId: "string",
+    "inReplyTo?": "string",
+    "references?": "string[]",
+    "subject?": "string",
+    "listId?": "string",
+    "interchangeType?": InterchangeType,
+    "interchangeCorrelationId?": "string",
+    "interchangeTenantId?": "string",
+    "interchangeAgentId?": "string",
+    "interchangeSessionId?": "string",
+    "interchangeOfferingId?": "string",
+    "interchangeSchemaVersion?": "string",
+    "traceparent?": "string",
+    "tracestate?": "string",
+});
 /**
  * Discriminated union of every control-channel payload kind. The
  * `type` discriminator namespaces the control-plane vocabulary so a
@@ -137,35 +171,47 @@ export const OutboundMessagePayload = type({
  * union and not by widening the envelope shape. Inference events
  * NEVER appear here; they ride the event channel.
  */
-export const ControlPayload = type({
+export const ControlPayload = type.or({
     type: "'trigger.fire'",
     data: {
         runId: "string",
         messageId: "string",
         receivedAt: "number",
+        // The run's inbound-mail input, resolved by the supervisor (the sole
+        // mail owner) before the frame: a decoded `Mail` (headers plus part
+        // descriptors that reference the part bytes committed to the workflow-run
+        // substrate). The child hands this straight to the runtime as the trigger
+        // payload. Refs, not raw mail bytes, ride here; the committed part files
+        // stay in the substrate. Typed `unknown` -- `Mail` is a nested structural
+        // type validated at the consumption boundary by `isMail`.
+        payload: "unknown",
     },
-}, "|", {
+}, {
     type: "'signal.deliver'",
     data: {
         runId: "string",
         signalName: "string",
         signalId: "string",
+        // The resume decision in FINAL form -- the child commits it as the
+        // SignalReceived payload verbatim. Each sender owns any
+        // provenance-specific preparation BEFORE this frame: the dispatch loop
+        // resolves an inbound mail to a decoded `Mail` (headers plus part
+        // references, like the turn-1 trigger), while `deliverSignal` ships a
+        // structured signal payload unchanged -- so this field stays
+        // polymorphic. Do NOT ship raw inbound mail bytes through here.
         payload: "unknown",
     },
-})
-    .or({
+}, {
     type: "'drain'",
     data: {
         deadlineMs: "number",
     },
-})
-    .or({
+}, {
     type: "'shutdown'",
     data: {
         reason: "string",
     },
-})
-    .or({
+}, {
     type: "'grants-updated'",
     data: {
         /**
@@ -187,12 +233,28 @@ export const ControlPayload = type({
          */
         "stepHashes?": "Record<string, string>",
     },
-})
-    .or({
+}, {
     type: "'sources-updated'",
     data: SourcesUpdatedData,
-})
-    .or({
+}, {
+    // Refreshed credential material for the deployment's inference sources and
+    // tools. The child MERGES this into its in-memory cell (see
+    // `mergeCredentialDelivery`): `delivery.materials` upsert by credentialId
+    // and `delivery.bindings` upsert by (consumer, handle); `revoke` names
+    // credentialIds to drop, and dropping one drops every binding referencing
+    // it. Merge rather than wholesale-replace because the cell has several
+    // independently-scoped producers (the deploy frame, an inference rotation,
+    // a tool-grant push), each carrying only its own slice -- a swap would let
+    // one evict another's credentials. Revocation is therefore explicit, never
+    // by omission. Carried inline like the grants and sources snapshots. The
+    // secret rides this frame and the in-memory cell only; it is never
+    // persisted.
+    type: "'credentials-updated'",
+    data: {
+        delivery: CredentialDelivery,
+        "revoke?": "string[]",
+    },
+}, {
     type: "'ready'",
     data: {
         childPid: "number",
@@ -204,8 +266,7 @@ export const ControlPayload = type({
          */
         childPublicKey: "string",
     },
-})
-    .or({
+}, {
     // Child-initiated request to recycle the workflow-process. The
     // child emits this when its own self-check decides it needs to be
     // recycled (an internal consistency error it can't recover from,
@@ -219,8 +280,7 @@ export const ControlPayload = type({
     data: {
         reason: "string",
     },
-})
-    .or({
+}, {
     // Child-initiated `writeTreePreservingPrefix` request. The child
     // does not hold a substrate write authority for the workflow-run
     // repo (single-writer at the ref tip belongs to the supervisor);
@@ -243,8 +303,7 @@ export const ControlPayload = type({
         preservePrefix: "string > 0",
         message: "string > 0",
     },
-})
-    .or({
+}, {
     // Supervisor-initiated request for the child's merge bytes. Fired
     // from inside the supervisor's `writeTreePreservingPrefix` merge
     // callback while the per-repo lock is held; the child receives the
@@ -261,8 +320,7 @@ export const ControlPayload = type({
             contentBase64: "string",
         }).array(),
     },
-})
-    .or({
+}, {
     // Child's merge result. `requestId` correlates with the
     // `substrate.write.request` that started the write; the supervisor
     // resumes its merge callback with the supplied entries (or
@@ -281,8 +339,7 @@ export const ControlPayload = type({
             reason: "string > 0",
         }),
     },
-})
-    .or({
+}, {
     // Supervisor's terminal reply to a child's `substrate.write.request`.
     // The `requestId` echoes the child's allocated correlation id so
     // the child's pending-id map resolves the awaiter. A successful
@@ -302,8 +359,7 @@ export const ControlPayload = type({
             reason: "string > 0",
         }),
     },
-})
-    .or({
+}, {
     // Child-initiated outbound-mail request (OUTBOUND half of mailbox
     // ownership, §3a). The workflow-process child never holds the
     // agent's signing key and never calls `transport.send` itself. When
@@ -329,8 +385,7 @@ export const ControlPayload = type({
         "mailbox?": "string",
         message: OutboundMessagePayload,
     },
-})
-    .or({
+}, {
     // Supervisor's terminal reply to a child's `outbound.message`. The
     // `requestId` echoes the child's correlation id so the child's
     // pending mail-tool awaiter resolves. A successful send surfaces the
@@ -350,8 +405,7 @@ export const ControlPayload = type({
             reason: "string > 0",
         }),
     },
-})
-    .or({
+}, {
     // Child-initiated terminal-run notification. The workflow-process
     // child emits this when one of its runs reaches a terminal phase
     // (`RunCompleted`, `RunFailed`, `RunCancelled`) so the supervisor's
@@ -377,6 +431,145 @@ export const ControlPayload = type({
             message: "string",
         },
     },
+}, {
+    // Child-initiated control-plane suspension notification. The
+    // workflow-process child emits this when a workflow agent step parks
+    // on a reserved `signalName(correlationId)` channel (`env.onPark`),
+    // so the supervisor can register the correlation out-of-band before
+    // the parked run can be resumed. The supervisor stamps the
+    // deployment identity it owns (`runId` + `agentAddress`) and
+    // forwards a `signal.correlation.register` frame to the hub, which
+    // co-writes the run's routing + approval rows. Mirrors
+    // `terminal.event`: a peer-channel notification the supervisor fans
+    // out, distinct from the substrate commit the run also produces.
+    //
+    // `signalName` is deliberately NOT carried: it is a pure function of
+    // `correlationId` (`signalName(correlationId)`), recomputed by every
+    // consumer that needs it, so the two cannot drift.
+    type: "'park.notify'",
+    data: {
+        runId: "string > 0",
+        correlationId: "string > 0",
+        parkKind: ControlParkKind,
+        // Approver-facing snapshot of the parked tool call, size-capped at this
+        // process boundary. Optional: only an ask-rail suspension carries one.
+        "snapshot?": BoundedApprovalSnapshot,
+    },
+}, {
+    // Supervisor-initiated request: enumerate the child's currently-parked
+    // approval correlations. The supervisor fires this after a
+    // re-establishment (child respawn, or hub-link reconnect fanned out to
+    // this deployment) so it can re-register at the hub every correlation
+    // whose original `park.notify`-driven register may have been lost while
+    // the hub was down. Modeled on `substrate.merge.request`: a
+    // supervisor->child request the child answers on `parked-correlations.
+    // response`, correlated by `requestId`. Carries no filter -- one child
+    // owns one deployment, so the child enumerates everything parked and the
+    // supervisor re-emits all; the hub co-write is idempotent.
+    type: "'parked-correlations.request'",
+    data: {
+        requestId: "string > 0",
+    },
+}, {
+    // Child's reply to `parked-correlations.request`. Each entry mirrors
+    // `park.notify`'s data -- the child-supplied half of a
+    // `SuspensionRegistration` the supervisor stamps its deployment identity
+    // onto -- so the supervisor's re-emit path shares one transform with the
+    // `park.notify` arm. Only reduced-state approval parks appear here: the
+    // child enumerates steps whose reduced phase is `awaiting-signal` on a
+    // control-plane `signalName(correlationId)` channel, each of which carries
+    // a durable snapshot by construction (a snapshot-less correlated suspend
+    // reduces to `failed`, not `awaiting-signal`). `snapshot` is therefore
+    // required, and size-capped at this process boundary like `park.notify`.
+    type: "'parked-correlations.response'",
+    data: {
+        requestId: "string > 0",
+        parked: type({
+            runId: "string > 0",
+            correlationId: "string > 0",
+            parkKind: ControlParkKind,
+            // Snapshot is required for approval parks and absent for input parks.
+            "snapshot?": BoundedApprovalSnapshot,
+        }).array(),
+    },
+}, {
+    // Child reports self-discovered runs after reconnect or recycle.
+    // The supervisor seeds its cohort tracking from these runIds so
+    // drain accumulators and dispatch routing account for runs the
+    // supervisor did not personally trigger.fire.
+    type: "'resumed.runs'",
+    data: {
+        runIds: type("string > 0").array(),
+    },
+}, {
+    // Supervisor-to-child one-way notification that new mail landed in a
+    // deployment mailbox (INBOUND half of mailbox ownership, §3b). One-way
+    // like `grants-updated`/`sources-updated`: no correlation id, no response.
+    // The supervisor -- the sole mail owner -- commits the arrived message to
+    // the workflow-run substrate mailbox, then fires this frame so the child's
+    // warm-agent `watch`/`mail_wait` observes the arrival decoupled from the
+    // FIFO trigger dispatch that resolves a run's first input. `headers` rides
+    // inline so a watcher gets the `exists` `MailboxEvent`'s envelope without a
+    // substrate round-trip. The child reads the latest committed mailbox state
+    // regardless, so the frame carries no commit pin.
+    type: "'mailbox.notify'",
+    data: {
+        runId: "string > 0",
+        mailbox: "string > 0",
+        uid: "number >= 1",
+        headers: MailboxNotifyHeaders,
+    },
+}, {
+    // Child-initiated mailbox-mutation request (INBOUND half of mailbox
+    // ownership, §3b). The supervisor is the sole writer to the
+    // workflow-run mailbox: a step agent reads its INBOX locally but
+    // every mutation -- flag writes and `expunge` -- routes up here so
+    // the supervisor applies it to its owned store. A child flushing the
+    // same ref would race the supervisor's in-memory mirror and break
+    // uid / modseq monotonicity.
+    //
+    // `data` is discriminated on `op`: an `addFlags` / `removeFlags`
+    // carries the target `uid` and the `flags` to change, so the wire
+    // boundary rejects a flag frame that omits them; an `expunge` sweeps
+    // every `\Deleted` message in the mailbox and the child constructs it
+    // with neither. `requestId` correlates the supervisor's
+    // `mailbox.mutate.response` reply.
+    type: "'mailbox.mutate.request'",
+    data: type({
+        requestId: "string > 0",
+        runId: "string > 0",
+        mailbox: "string > 0",
+        op: "'addFlags' | 'removeFlags'",
+        uid: "number >= 1",
+        flags: "string[]",
+    }, "|", {
+        requestId: "string > 0",
+        runId: "string > 0",
+        mailbox: "string > 0",
+        op: "'expunge'",
+    }),
+}, {
+    // Supervisor's terminal reply to a child's `mailbox.mutate.request`.
+    // The `requestId` echoes the child's correlation id so the child's
+    // pending mail-tool awaiter resolves. The reply is sent only after
+    // the supervisor flushes the mutation, so the child's next committed
+    // read observes it -- the same flush-before-signal ordering
+    // `mailbox.notify` relies on. A successful `expunge` carries the
+    // `expungedUids` it swept so the agent tool can report the count; a
+    // flag write carries no operand echo. A failed mutation (unknown
+    // uid, substrate fault) surfaces a structured `{ ok: false, reason }`
+    // the child's bridge rethrows so the mail-tool call fails loudly.
+    type: "'mailbox.mutate.response'",
+    data: {
+        requestId: "string > 0",
+        result: type({
+            ok: "true",
+            "expungedUids?": "number[]",
+        }, "|", {
+            ok: "false",
+            reason: "string > 0",
+        }),
+    },
 });
 /**
  * Construct the supervisor-side control-channel sender. The

package/dist/ipc/event-channel.d.ts

@@ -29,7 +29,7 @@ export declare const EventPayload: import("arktype/internal/variants/object.ts")
         index?: number;
     };
 } | {
-    type: "inference.thinking.signature";
+    type: "inference.block.signature";
     seq: number;
     data: {
         signature: string;
@@ -155,6 +155,7 @@ export declare const EventPayload: import("arktype/internal/variants/object.ts")
             content: ({
                 type: "text";
                 text: string;
+                signature?: string;
             } | {
                 type: "image";
                 source: {
@@ -170,6 +171,7 @@ export declare const EventPayload: import("arktype/internal/variants/object.ts")
                     mimeType: string;
                     url: string;
                 };
+                signature?: string;
             } | {
                 type: "audio";
                 source: {
@@ -215,6 +217,8 @@ export declare const EventPayload: import("arktype/internal/variants/object.ts")
                     mimeType: string;
                     url: string;
                 };
+                title?: string;
+                context?: string;
             } | {
                 type: "thinking";
                 thinking: string;
@@ -230,6 +234,7 @@ export declare const EventPayload: import("arktype/internal/variants/object.ts")
                 id: string;
                 name: string;
                 arguments: Record<string, unknown>;
+                signature?: string;
             } | {
                 type: "citation";
                 citedText: string;
@@ -249,11 +254,15 @@ export declare const EventPayload: import("arktype/internal/variants/object.ts")
                     start: number;
                     end: number;
                 };
+            } | {
+                type: "safety_rating";
+                blockReason: string;
             } | {
                 type: "code_execution_request";
                 id: string;
                 code: string;
                 language?: string;
+                signature?: string;
             } | {
                 type: "code_execution_result";
                 requestId: string;
@@ -269,6 +278,7 @@ export declare const EventPayload: import("arktype/internal/variants/object.ts")
                 content: ({
                     type: "text";
                     text: string;
+                    signature?: string;
                 } | {
                     type: "image";
                     source: {
@@ -284,6 +294,7 @@ export declare const EventPayload: import("arktype/internal/variants/object.ts")
                         mimeType: string;
                         url: string;
                     };
+                    signature?: string;
                 } | {
                     type: "audio";
                     source: {
@@ -329,6 +340,8 @@ export declare const EventPayload: import("arktype/internal/variants/object.ts")
                         mimeType: string;
                         url: string;
                     };
+                    title?: string;
+                    context?: string;
                 })[];
                 detail?: unknown;
                 isError?: boolean;
@@ -411,6 +424,15 @@ export declare const EventPayload: import("arktype/internal/variants/object.ts")
         };
         index?: number;
     };
+} | {
+    type: "inference.safety_rating";
+    seq: number;
+    data: {
+        safetyRating: {
+            type: "safety_rating";
+            blockReason: string;
+        };
+    };
 } | {
     type: "inference.code_execution.start";
     seq: number;
@@ -420,6 +442,7 @@ export declare const EventPayload: import("arktype/internal/variants/object.ts")
             id: string;
             code: string;
             language?: string;
+            signature?: string;
         };
         index?: number;
     };
@@ -466,6 +489,7 @@ export declare const EventPayload: import("arktype/internal/variants/object.ts")
                 mimeType: string;
                 url: string;
             };
+            signature?: string;
         };
         index?: number;
     };
@@ -574,6 +598,13 @@ export declare const EventPayload: import("arktype/internal/variants/object.ts")
     data: {
         reason: "approval" | "payment" | "credential" | "budget" | "child_completion" | "message_response";
         gateId: string;
+        correlationId?: string;
+        approvalSnapshot?: {
+            name: string;
+            description: string;
+            inputSchema: Record<string, unknown>;
+            arguments: Record<string, unknown>;
+        };
     };
 } | {
     type: "reactor.gate.cleared";

package/dist/ipc/index.d.ts

@@ -1,4 +1,4 @@
-export { ControlPayload, OutboundAttachmentPayload, OutboundMessagePayload, SourcesUpdatedData, createControlChannelSender, receiveControlChannel, type ControlChannelSender, type ControlChannelSenderOpts, type ControlChannelReceiverOpts, type NdjsonReader, type NdjsonWriter, } from "./control-channel.js";
+export { ControlPayload, MailboxNotifyHeaders, OutboundAttachmentPayload, OutboundMessagePayload, SourcesUpdatedData, createControlChannelSender, receiveControlChannel, type ControlChannelSender, type ControlChannelSenderOpts, type ControlChannelReceiverOpts, type NdjsonReader, type NdjsonWriter, } from "./control-channel.js";
 export { DEFAULT_EVENT_BUFFER_LIMIT, EventPayload, createEventChannelSender, receiveEventChannel, type EventChannelSender, type EventChannelSenderOpts, type EventChannelReceiverOpts, type FrameReader, type FrameWriter, } from "./event-channel.js";
 export { FrameEnvelope, MacedEnvelope, SignedEnvelope, decodeEnvelope, encodeEnvelope, } from "./envelope.js";
 export { IPC_CRYPTO, generateChannelId, generateHmacKey, signEd25519, signHmac, verifyEd25519, verifyHmac, } from "./crypto.js";

package/dist/ipc/index.js

@@ -137,7 +137,7 @@
 //    from env, the supervisor enforces.
 //
 // =============================================================
-export { ControlPayload, OutboundAttachmentPayload, OutboundMessagePayload, SourcesUpdatedData, createControlChannelSender, receiveControlChannel, } from "./control-channel.js";
+export { ControlPayload, MailboxNotifyHeaders, OutboundAttachmentPayload, OutboundMessagePayload, SourcesUpdatedData, createControlChannelSender, receiveControlChannel, } from "./control-channel.js";
 export { DEFAULT_EVENT_BUFFER_LIMIT, EventPayload, createEventChannelSender, receiveEventChannel, } from "./event-channel.js";
 export { FrameEnvelope, MacedEnvelope, SignedEnvelope, decodeEnvelope, encodeEnvelope, } from "./envelope.js";
 export { IPC_CRYPTO, generateChannelId, generateHmacKey, signEd25519, signHmac, verifyEd25519, verifyHmac, } from "./crypto.js";

package/dist/mail-bus/hub-transport-adapter.d.ts

@@ -10,14 +10,19 @@ import type { MailBusBindings } from "../supervisor/types.js";
  */
 export interface HubTransportMailBusAdapter extends MailBusBindings {
     /**
-     * Fan a delivered message out to every handler subscribed at
-     * `address`. Returns immediately if no handler is registered --
-     * the supervisor's lifecycle (`subscribeMailForAddress` returns a
-     * disposer the supervisor calls on teardown) is the authoritative
-     * source of which addresses are live; addresses without an active
-     * subscriber drop the message silently.
+     * Fan a delivered message out to every handler subscribed at `address` and
+     * return the combined durable settlement: the promise resolves once every
+     * subscribed handler has durably accepted the message and rejects if any
+     * handler rejected. The host propagates that settlement to the wire, so
+     * resolution is the durable-receipt ACK signal and rejection is WITHHOLD.
+     *
+     * An address with NO active subscriber rejects rather than resolving. The
+     * supervisor's lifecycle (`subscribeMailForAddress` returns a disposer it
+     * calls on teardown) is the authoritative source of which addresses are
+     * live; a message routed to an address with no live handler was not
+     * durably accepted, so it must withhold-and-be-redelivered, never ack.
      */
-    routeInbound(address: string, message: Uint8Array): void;
+    routeInbound(address: string, message: Uint8Array): Promise<void>;
 }
 /**
  * Wrap an existing `HubTransport` instance as the supervisor-facing

package/dist/mail-bus/hub-transport-adapter.js

@@ -50,12 +50,16 @@ export function wrapHubTransportAsMailBus(transport) {
                 current?.delete(handler);
             };
         },
-        routeInbound(address, message) {
+        async routeInbound(address, message) {
             const set = subscribers.get(address);
-            if (set === undefined)
-                return;
-            for (const handler of set)
-                handler(message);
+            if (set === undefined || set.size === 0) {
+                // No live handler accepted the message, so it was not durably
+                // received. Reject so the caller withholds the ack and the hub
+                // redelivers, rather than silently dropping (which under the ack
+                // model would be an acked loss).
+                throw new Error(`no active mail subscriber for ${address}; message not durably accepted`);
+            }
+            await Promise.all([...set].map((handler) => handler(message)));
         },
         async sendOutbound(senderAddress, message) {
             // OUTBOUND half of mailbox ownership (§3a): route the agent's

package/dist/run-body-then-cleanup.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Run `body`, then always run `cleanup`, without letting a `cleanup`
+ * failure mask a `body` failure.
+ *
+ * When `body` throws, `cleanup` still runs and a `cleanup` failure is
+ * handed to `onCleanupErrorAfterBodyError` (to log) and then dropped, so
+ * the original `body` error is what propagates. When `body` succeeds, a
+ * `cleanup` failure propagates -- there is no primary error to protect, so
+ * a failing teardown is the error worth surfacing.
+ *
+ * This exists so teardown in a `finally` (agent close, warm-cache
+ * eviction) can surface its own failure without a `throw` inside a
+ * `finally` block, which `no-unsafe-finally` forbids precisely because it
+ * silently swallows the in-flight exception -- the masking bug this guards
+ * against.
+ */
+export declare function runBodyThenCleanup<T>(body: () => Promise<T>, cleanup: () => Promise<void>, onCleanupErrorAfterBodyError: (cause: unknown) => void): Promise<T>;

package/dist/run-body-then-cleanup.js

@@ -0,0 +1,38 @@
+/**
+ * Run `body`, then always run `cleanup`, without letting a `cleanup`
+ * failure mask a `body` failure.
+ *
+ * When `body` throws, `cleanup` still runs and a `cleanup` failure is
+ * handed to `onCleanupErrorAfterBodyError` (to log) and then dropped, so
+ * the original `body` error is what propagates. When `body` succeeds, a
+ * `cleanup` failure propagates -- there is no primary error to protect, so
+ * a failing teardown is the error worth surfacing.
+ *
+ * This exists so teardown in a `finally` (agent close, warm-cache
+ * eviction) can surface its own failure without a `throw` inside a
+ * `finally` block, which `no-unsafe-finally` forbids precisely because it
+ * silently swallows the in-flight exception -- the masking bug this guards
+ * against.
+ */
+export async function runBodyThenCleanup(body, cleanup, onCleanupErrorAfterBodyError) {
+    let outcome;
+    try {
+        outcome = { ok: true, value: await body() };
+    }
+    catch (error) {
+        outcome = { ok: false, error };
+    }
+    try {
+        await cleanup();
+    }
+    catch (cleanupError) {
+        if (outcome.ok) {
+            throw cleanupError;
+        }
+        onCleanupErrorAfterBodyError(cleanupError);
+    }
+    if (!outcome.ok) {
+        throw outcome.error;
+    }
+    return outcome.value;
+}

package/dist/seams/scheduler.d.ts

@@ -11,12 +11,10 @@ import type { Principal, RepoId, RepoStore } from "@intx/hub-sessions/substrate"
 export declare const TimerEventEnvelope: import("arktype/internal/variants/object.ts").ObjectType<{
     seq: number;
     type: "TimerSet" | "TimerFired";
-    data: {
-        timerId: string;
-        fireAt?: string;
-        stepId?: string | null;
-        cron?: string | null;
-    };
+    timerId: string;
+    fireAt?: string;
+    stepId?: string | null;
+    cron?: string | null;
 }, {}>;
 export type TimerEventEnvelope = typeof TimerEventEnvelope.infer;
 export type SchedulerOpts = {
@@ -54,6 +52,18 @@ export type SchedulerOpts = {
      * callbacks and to skip past-due cron entries on recovery.
      */
     clock: () => Date;
+    /**
+     * Arms a one-shot timer and returns its canceller. Defaults to the global
+     * timer, which is what production wants.
+     *
+     * The clock above decides WHEN a timer should fire; this decides what
+     * actually fires it. Without both, a caller can compute a deterministic
+     * delay and still have to wait out the real interval to observe the
+     * firing -- which left this module's own tests waiting past a `fireAt`,
+     * and, in one case, waiting longer than a cancelled timer's delay to argue
+     * from silence that the cancel had worked.
+     */
+    scheduleTimeout?: (handler: () => void, ms: number) => () => void;
 };
 export type SchedulerHandle = {
     /**