@intx/workflow-host 0.2.2

package/dist/supervisor/recycle.js

@@ -0,0 +1,440 @@
+// =============================================================
+// RECYCLE -- workflow-process supervisor library code
+// =============================================================
+//
+// Recycle is the supervisor's "same deploy tree, fresh process" path.
+// It tears the existing workflow-process child down and stands a new
+// one up against the SAME deploy tree (same `workflow.json`, same
+// per-step credential repos). It is STRICTLY ORTHOGONAL TO REDEPLOY:
+//
+//   - Recycle  = same deploy tree, fresh process.
+//   - Redeploy = new deploy tree.
+//
+// Recycle does not refetch the deploy tree, does not consult an
+// updated workflow definition, does not re-resolve agents. If a
+// deploy-tree change is needed the host runs redeploy, which is a
+// different code path with different authorization and a different
+// rollback shape. The recycle module must never grow a "maybe also
+// refetch the deploy tree" mode -- that would erase the orthogonality
+// and let a recycle silently turn into a redeploy.
+//
+// Six-step sequence (locked):
+//
+//   1. `drain` -- send the existing drain control mail. Wait for
+//      in-flight runs to drain per each step's `drainBehavior`.
+//      `drainTimeout` escalation applies normally; the drain-timeout
+//      accumulator and its `CancelRequested{origin: "supervisor-drain"}`
+//      commit path are unchanged from the standalone-drain case.
+//   2. `kill` -- terminate the workflow-process child cleanly. SIGTERM
+//      first; if the child does not exit within the kill-timeout, the
+//      handle's `kill(SIGKILL)` lands the hard stop. The supervisor's
+//      injected subprocess spawner returns the child-handle API used
+//      here; the recycle path does not reach into Node primitives.
+//   3. `respawn` -- mint a new 16-byte hex channelId (the same shape
+//      the initial spawn uses, per `generateChannelId`), generate a
+//      fresh 32-byte HMAC key, re-read per-step credentials via the
+//      injected `RepoStore`, and spawn a new Bun child via the same
+//      subprocess-spawner binding. The new IPC anchors flow through
+//      spawn-time env exactly as the initial spawn's anchors did.
+//   4. `self-discover` -- the new child runs its existing self-
+//      discovery on spawn. The recycle path does not coordinate this
+//      step; it is the child's responsibility.
+//   5. `resume` -- self-discovery resumes any in-flight runs from the
+//      workflow-run log. The runtime body's seed-events path re-arms
+//      timers, pending awaits, and uncancelled children.
+//   6. Buffered mail is the supervisor's FIFO inbox claim-check queue
+//      (the new child's dispatch loop picks up entries that arrived
+//      during the kill/respawn gap once it starts). The recycle path
+//      does NOT drain an in-memory mail buffer; every inbound message
+//      enqueues into the substrate-backed inbox regardless of phase.
+//
+// Mail-address ownership across the gap: the supervisor holds the
+// mail-bus registration across the recycle via the injected mail-bus
+// binding. No re-register, no unregister. Inbound mail during the
+// gap commits to the substrate-backed inbox; the new child's dispatch
+// loop dequeues in arrival order (the envelope's `receivedAt` prefix
+// preserves FIFO discipline across the gap).
+//
+// Before the kill lands the recycle path calls
+// `ctx.replayProcessingToInbox()` so any in-flight `processing/`
+// entries that the dying cohort's dispatch loop did not reach
+// `markConsumed` for get moved back to `inbox/` under their original
+// `<receivedAt>-<messageId>` keys. Without this step the dying child
+// would leave an orphaned processing entry that no live dispatch
+// loop owns.
+//
+// Three trigger origins funnel through `triggerRecycle(reason, ctx)`:
+//
+//   - Operator command -- the host receives a `recycle` request via
+//     its caller-facing API and routes it to the supervisor's
+//     `recycle()` method, which delegates here.
+//   - Supervisor policy -- a periodic check (every ~minute) consults
+//     configurable bounds (max-uptime, max-rss, grants-staleness;
+//     defaults unlimited). On a threshold trip the policy calls
+//     `triggerRecycle` with a reason tagged with the tripped bound.
+//   - Workflow-process self-initiated -- the child sends a
+//     `recycle.request` payload over control IPC. The supervisor's
+//     upstream control-channel reader recognises the variant and
+//     funnels it here.
+//
+// All three origins land in the same code path. The reason string is
+// the only origin-specific data the path carries forward.
+import { getLogger } from "@intx/log";
+import { generateKeyPair } from "@intx/crypto";
+import { createControlChannelSender, generateChannelId, generateHmacKey, receiveControlChannel, receiveEventChannel, } from "../ipc/index.js";
+import { assembleCredentialsSnapshot, } from "./credentials.js";
+import { buildChildSpawnEnv } from "./spawn-env.js";
+import { DEFAULT_KILL_TIMEOUT_MS, DEFAULT_READY_TIMEOUT_MS, defaultClearTimer, defaultSetTimer, killChildHandle, waitDeadline, } from "./child-termination.js";
+const logger = getLogger(["workflow-host", "supervisor", "recycle"]);
+/**
+ * Bound on the supervisor's mail buffer across the kill/respawn gap.
+ * A real workflow's inbound rate is well below this; saturation
+ * indicates either an upstream stuck on the deployment or a recycle
+ * stuck partway through. Either case is one the operator must see.
+ */
+export const MAX_BUFFERED_MAIL = 256;
+/**
+ * Default supervisor-policy check interval. The policy thread wakes
+ * roughly every minute, evaluates the configured bounds against the
+ * live child, and triggers a recycle if any threshold has been
+ * crossed. Operator-overridable via the supervisor's policy bindings.
+ */
+export const DEFAULT_POLICY_INTERVAL_MS = 60_000;
+/**
+ * Run the six-step recycle sequence. The function returns once the
+ * new child has emitted `ready` and the supervisor has drained its
+ * buffered mail into it; the supervisor installs the new wiring via
+ * `ctx.installNewChild` before that point.
+ */
+export async function triggerRecycle(ctx, opts) {
+    const drainDeadlineMs = ctx.drainDeadlineMs ?? 60_000;
+    const killTimeoutMs = ctx.killTimeoutMs ?? DEFAULT_KILL_TIMEOUT_MS;
+    const previousChannelId = ctx.current.channelId;
+    logger.info `recycle ${opts.origin} requested: ${opts.reason} (previousChannelId=${previousChannelId})`;
+    // Step 1: drain. The supervisor's drain primitive is the same one
+    // the standalone-drain path uses; the recycle path does not
+    // reimplement the drain control mail or the drainTimeout
+    // accumulator. The `drainBehavior` of each in-flight step decides
+    // whether it aborts or continues; `drainTimeout` escalation lands
+    // through the existing supervisor-drain origin.
+    await ctx.drain(drainDeadlineMs);
+    // After drain settles and BEFORE the kill lands, replay any
+    // in-flight `processing/` entries back to `inbox/`. Without this
+    // replay, a child whose run was mid-dispatch when drain expired
+    // would leave its `processing/` entry orphaned -- the dispatch
+    // loop for the dying cohort already aborted on cohort teardown
+    // and will not reach its `markConsumed` step. The new child's
+    // dispatch loop dequeues the recovered entries in arrival order
+    // (the envelope's `receivedAt` prefix preserves FIFO discipline).
+    try {
+        await ctx.replayProcessingToInbox();
+    }
+    catch (cause) {
+        const message = cause instanceof Error ? cause.message : String(cause);
+        logger.warn `recycle: replayProcessingToInbox before kill failed: ${message}`;
+    }
+    // Abort the prior cohort here -- after drain and replay have run
+    // against a live cohort, before the kill drops the child. Aborting
+    // up front (in the supervisor wrapper) would starve drain
+    // accumulators of live terminal events and force every recycle to
+    // pay the full drainTimeout budget. Aborting after the kill would
+    // race the dispatch loop's next iteration against the
+    // controlSender that is about to disappear.
+    ctx.abortPriorCohort();
+    // Step 2: kill. SIGTERM first; if the child does not exit within
+    // `killTimeoutMs`, the handle's hard kill lands. The injected
+    // spawner's `SubprocessHandle.kill()` is the surface the recycle
+    // path touches; the spawner owns the Node primitives.
+    await killChildHandle(ctx.current.handle, killTimeoutMs, {
+        logger,
+        ...(ctx.setTimer !== undefined ? { setTimer: ctx.setTimer } : {}),
+        ...(ctx.clearTimer !== undefined ? { clearTimer: ctx.clearTimer } : {}),
+    });
+    // Step 3: respawn. Fresh channelId, fresh HMAC key, fresh Ed25519
+    // IPC keypair. Per-step credentials are re-read so a grants update
+    // that landed since the original spawn is reflected in the new
+    // child's snapshot. The deploy tree (`workflow.json`, agents,
+    // workflow-asset repo) is UNCHANGED.
+    const channelId = generateChannelId();
+    const hmacKey = generateHmacKey();
+    const ipcKeypair = await (ctx.bindings.ipcKeyPairFactory ?? generateKeyPair)();
+    const env = buildChildSpawnEnv({
+        substrateEnv: ctx.bindings.substrateEnv,
+        dynamicSpawnEnv: ctx.bindings.dynamicSpawnEnv,
+        channelId,
+        hmacKey,
+        hostPublicKey: ipcKeypair.publicKey,
+        deploymentId: ctx.bindings.deploymentId,
+        deploymentMailAddress: ctx.bindings.deploymentMailAddress,
+        stepCount: ctx.bindings.stepCount,
+        definitionHash: ctx.definitionHash,
+        warmKeep: ctx.warmKeep,
+    });
+    const handle = ctx.bindings.subprocessSpawner({
+        binaryPath: ctx.bindings.binaryPath,
+        env,
+    });
+    const controlSender = createControlChannelSender({
+        privateKeySeed: ipcKeypair.privateKey,
+        channelId,
+        writer: handle.controlWriter,
+    });
+    const controlIncoming = receiveControlChannel({
+        publicKey: { bootstrapFromReady: true },
+        channelId,
+        reader: handle.controlReader,
+        onCrash: ctx.onCrash,
+    });
+    const readyPromise = waitForReady(controlIncoming);
+    // Attach a benign handler at creation, before the fold below consumes
+    // the rejection: `readyPromise` is created here but not raced until
+    // after `assembleCredentialsSnapshot` awaits. A child that exits during
+    // that window rejects `readyPromise` with no handler yet attached -- an
+    // unhandled rejection across the await boundary. Mirrors the spawn
+    // path's identical guard. Attaching `.catch` here and `.then` at the
+    // race is fine; both observe the same settled value.
+    void readyPromise.catch(() => undefined);
+    const eventIter = receiveEventChannel({
+        hmacKey,
+        channelId,
+        reader: handle.eventReader,
+        onCrash: ctx.onCrash,
+    });
+    const eventPump = pumpEvents(eventIter, ctx.onInferenceEvent);
+    // The child handshake below is deadline-bounded and needs these timer
+    // bindings; the pre-handshake credentials-read reap needs them too, so
+    // derive them before that read.
+    const setTimer = ctx.setTimer ?? defaultSetTimer;
+    const clearTimer = ctx.clearTimer ?? defaultClearTimer;
+    // Re-read per-step credentials. A grants update that landed during
+    // the previous child's lifetime is picked up here -- the recycle
+    // doubles as the supervisor's grant-refresh path. The deploy tree
+    // is not consulted; this read is against the `agent-state` repos
+    // alone, whose contents are independent of `workflow.json`.
+    //
+    // This is a substrate read that can reject -- a grants file that
+    // became malformed is precisely the recycle's grant-refresh path. The
+    // new child is already spawned and wired but not yet installed on
+    // `state`, so the supervisor's recycle-failure teardown (which reaps
+    // the PRIOR cohort) cannot see it; reap it here on failure or it
+    // leaks. The spawn path routes this same throw through its teardown
+    // owner. The try wraps only the awaited read: the handle and pumps it
+    // reaps are all constructed above, so the reap always has live
+    // handles.
+    let credentialsSnapshot;
+    try {
+        credentialsSnapshot = await assembleCredentialsSnapshot({
+            repoStore: ctx.bindings.repoStore,
+            principal: ctx.bindings.readPrincipal,
+            stepOrder: ctx.stepOrder,
+            deploymentId: ctx.bindings.deploymentId,
+            deriveStepAddress: ctx.bindings.deriveStepAddress,
+            ...(ctx.bindings.deriveStepRepoId !== undefined
+                ? { deriveStepRepoId: ctx.bindings.deriveStepRepoId }
+                : {}),
+        });
+    }
+    catch (cause) {
+        await reapUnreadyChild(handle, eventPump, controlIncoming, {
+            killTimeoutMs,
+            setTimer,
+            clearTimer,
+            phase: "credentials read failure",
+        });
+        throw cause;
+    }
+    // Steps 4 + 5: self-discover + resume. These run inside the child
+    // before it emits `ready`; the supervisor waits, but bounded -- a child
+    // that neither readies nor exits must not park the recycle (and thus
+    // the supervisor) in `recycling` forever. Bound the handshake exactly
+    // as the spawn path bounds its own: fold ready/failed into values, race
+    // a resolve-only deadline, clear the timer on every path.
+    //
+    // NOTE: `assembleCredentialsSnapshot` above is a substrate read that
+    // sits OUTSIDE this deadline; a wedged substrate is a supervisor-side
+    // fault bounded at its own layer, not by overloading this handshake
+    // timer. The respawn is deadline-bounded on the child handshake, not on
+    // that read.
+    const readyTimeoutMs = ctx.readyTimeoutMs ?? DEFAULT_READY_TIMEOUT_MS;
+    const readyOutcome = readyPromise.then((info) => ({ kind: "ready", info }), (err) => ({ kind: "failed", err }));
+    const readyDeadline = waitDeadline(setTimer, readyTimeoutMs);
+    const readyRace = await Promise.race([
+        readyOutcome,
+        readyDeadline.promise.then(() => ({ kind: "timeout" })),
+    ]);
+    clearTimer(readyDeadline.handle);
+    if (readyRace.kind !== "ready") {
+        // The new child was never installed on `state`, so the supervisor's
+        // recycle-failure teardown (which reaps the PRIOR cohort) would leak
+        // it. Reap it here. `killChildHandle` on an already-dead handle is a
+        // cheap no-op, so the `failed` path (a control-channel end does not
+        // guarantee the process died, since the event channel is separate)
+        // is reaped too, not just the timeout.
+        await reapUnreadyChild(handle, eventPump, controlIncoming, {
+            killTimeoutMs,
+            setTimer,
+            clearTimer,
+            phase: "handshake failure",
+        });
+        if (readyRace.kind === "timeout") {
+            throw new Error(`workflow-host supervisor recycle: child did not emit ready within ${String(readyTimeoutMs)}ms; killed`);
+        }
+        throw readyRace.err;
+    }
+    const readyInfo = readyRace.info;
+    logger.info `recycle ${opts.origin}: child ready (pid=${String(readyInfo.childPid)}, newChannelId=${channelId})`;
+    const newWiring = {
+        handle,
+        controlSender,
+        channelId,
+        eventPump,
+    };
+    ctx.installNewChild({
+        wiring: newWiring,
+        credentialsSnapshot,
+        controlIncoming,
+    });
+    // Step 6: the FIFO inbox claim-check queue holds any mail that
+    // arrived during the kill/respawn gap (every inbound message
+    // enqueues into the substrate-backed inbox regardless of phase).
+    // The new dispatch loop that `installNewChild` started dequeues
+    // those entries in arrival order; the recycle path does not need
+    // an in-memory drain step.
+    return {
+        origin: opts.origin,
+        reason: opts.reason,
+        newChannelId: channelId,
+        previousChannelId,
+    };
+}
+/**
+ * Reap a respawned child that was spawned and wired but never installed
+ * on `state`. Such a child is invisible to the supervisor's
+ * recycle-failure teardown -- that path reaps the PRIOR cohort
+ * (`state.handle` during `recycling`) -- so a respawn that fails after
+ * the spawn must reap the new child here or it leaks its OS process and
+ * both IPC channels.
+ *
+ * Kill FIRST, then finalize the pumps: process death drives EOF on both
+ * channels, which unparks `waitForReady`'s in-flight `iter.next()`
+ * (letting `controlIncoming.return` complete) and ends `pumpEvents`.
+ * Awaiting either finalizer before the kill would hang behind the
+ * still-open channels. `killChildHandle` on an already-dead handle is a
+ * cheap no-op, so a child that died on its own -- not just one killed on
+ * timeout -- is reaped safely too.
+ */
+async function reapUnreadyChild(handle, eventPump, controlIncoming, deps) {
+    await killChildHandle(handle, deps.killTimeoutMs, {
+        logger,
+        setTimer: deps.setTimer,
+        clearTimer: deps.clearTimer,
+    });
+    void eventPump.catch((cause) => {
+        const message = cause instanceof Error ? cause.message : String(cause);
+        logger.warn `recycle: reaped child eventPump failed after ${deps.phase}: ${message}`;
+    });
+    void controlIncoming.return(undefined).catch((cause) => {
+        const message = cause instanceof Error ? cause.message : String(cause);
+        logger.warn `recycle: reaped child controlIncoming.return failed after ${deps.phase}: ${message}`;
+    });
+}
+/**
+ * Iterate the new child's control-receive iterator until the `ready`
+ * frame lands. Identical shape to the supervisor's spawn-time helper;
+ * factored here so the recycle path does not depend on the
+ * supervisor's private function.
+ */
+async function waitForReady(iter) {
+    // Explicit `next()` instead of `for await ... return` so the
+    // generator is not finalized when ready lands. The supervisor's
+    // upstream-control pump continues iterating the same generator
+    // after the recycle path returns; finalizing it here would silently
+    // drop any subsequent child-initiated upstream frames.
+    while (true) {
+        const next = await iter.next();
+        if (next.done === true) {
+            throw new Error("workflow-host supervisor recycle: control channel ended before child emitted ready");
+        }
+        const payload = next.value;
+        if (payload.type === "ready") {
+            return { childPid: payload.data.childPid };
+        }
+        // Other upstream control payloads encountered before `ready` are
+        // dropped silently; the receiver iterator already verified them
+        // and any later upstream traffic flows through the supervisor's
+        // pump once recycle returns.
+    }
+}
+async function pumpEvents(iter, onInferenceEvent) {
+    for await (const event of iter) {
+        onInferenceEvent(event);
+    }
+}
+/**
+ * Start the supervisor-policy periodic recycle check. Returns a
+ * handle the supervisor calls `stop()` on at shutdown. The policy is
+ * single-trigger per tick: even if multiple bounds are tripped on the
+ * same tick, exactly one `trigger` invocation lands with a reason
+ * naming the first tripped bound.
+ */
+export function createRecyclePolicy(opts) {
+    const intervalMs = opts.intervalMs ?? DEFAULT_POLICY_INTERVAL_MS;
+    let stopped = false;
+    let timerHandle = null;
+    async function tick() {
+        if (stopped)
+            return;
+        const reason = evaluateBounds(opts);
+        if (reason !== null) {
+            try {
+                await opts.trigger(reason);
+            }
+            catch (cause) {
+                const message = cause instanceof Error ? cause.message : String(cause);
+                logger.error `recycle policy trigger failed: ${message}`;
+            }
+        }
+    }
+    function arm() {
+        if (stopped)
+            return;
+        timerHandle = opts.setTimer(() => {
+            void tick().finally(() => arm());
+        }, intervalMs);
+    }
+    arm();
+    return {
+        stop() {
+            if (stopped)
+                return;
+            stopped = true;
+            if (timerHandle !== null)
+                opts.clearTimer(timerHandle);
+            timerHandle = null;
+        },
+        tick,
+    };
+}
+function evaluateBounds(opts) {
+    if (opts.bounds.maxUptimeMs !== undefined) {
+        const uptimeMs = opts.now() - opts.spawnedAt;
+        if (uptimeMs >= opts.bounds.maxUptimeMs) {
+            return `max-uptime: uptime ${String(uptimeMs)}ms >= threshold ${String(opts.bounds.maxUptimeMs)}ms`;
+        }
+    }
+    if (opts.bounds.maxRssBytes !== undefined &&
+        opts.readRssBytes !== undefined) {
+        const rss = opts.readRssBytes();
+        if (rss !== undefined && rss >= opts.bounds.maxRssBytes) {
+            return `max-rss: rss ${String(rss)} bytes >= threshold ${String(opts.bounds.maxRssBytes)} bytes`;
+        }
+    }
+    if (opts.bounds.maxGrantsAgeMs !== undefined &&
+        opts.readGrantsAgeMs !== undefined) {
+        const ageMs = opts.readGrantsAgeMs();
+        if (ageMs !== undefined && ageMs >= opts.bounds.maxGrantsAgeMs) {
+            return `grants-staleness: age ${String(ageMs)}ms >= threshold ${String(opts.bounds.maxGrantsAgeMs)}ms`;
+        }
+    }
+    return null;
+}

package/dist/supervisor/run-event-compaction.d.ts

@@ -0,0 +1,34 @@
+import type { RepoId, RepoStore as SubstrateRepoStore } from "@intx/hub-sessions/substrate";
+export type CompactRunEventsOpts = {
+    /** Substrate handle the supervisor writes through. */
+    substrate: SubstrateRepoStore;
+    /** Workflow-run repo for this deployment. */
+    repoId: RepoId;
+    /** Events ref the workflow-run repo writes to. */
+    ref: string;
+    /** Deployment id used to construct the supervisor principal. */
+    deploymentId: string;
+    /** Run to seal. */
+    runId: string;
+};
+/**
+ * Fold a terminated run's per-event `events/<seq>.json` blobs into one
+ * combined `events.jsonl`, dropping the per-event files. This shrinks the
+ * repo's file count -- and so every per-commit cost that scales with it --
+ * without losing any event.
+ *
+ * Idempotent and terminal-only: a run already sealed (no `events/` subtree)
+ * or one whose latest event is not terminal is left untouched, so the call
+ * is safe to repeat. The live caller fires it once per run, right after the
+ * run terminates; a bounded recovery sweep that would re-fire it to seal a
+ * run whose fold a crash interrupted is not yet implemented.
+ *
+ * The combined file is the verbatim byte concatenation of the per-event
+ * blobs in seq order (`encodeCombinedEventLog`), the exact shape the
+ * workflow-run kind handler's compaction validation requires. It is written
+ * as a sibling of `events/`, so returning it from the merge while omitting
+ * the per-event files lets the substrate's prefix clear drop them.
+ */
+export declare function compactRunEvents(opts: CompactRunEventsOpts): Promise<{
+    compacted: boolean;
+}>;

package/dist/supervisor/run-event-compaction.js

@@ -0,0 +1,115 @@
+// Run-event compaction path for the per-deployment supervisor.
+//
+// Once a workflow run terminates, the supervisor folds that run's
+// per-event `events/<seq>.json` blobs into one combined `events.jsonl`
+// and drops the per-event files. This shrinks the workflow-run repo's
+// file count -- and every per-commit cost that scales with it --
+// without losing any event. The fold writes under the substrate's
+// per-repo lock as the `supervisor` principal, whose `deploymentId`
+// the workflow-run kind handler checks against `repoId.id`.
+import { WORKFLOW_RUN_EVENTS_FILE, encodeCombinedEventLog, } from "@intx/hub-sessions/substrate";
+import { SUPERVISOR_PRINCIPAL_KIND } from "./cancel-signing.js";
+const RUNS_PREFIX = "runs";
+const EVENTS_DIR = "events";
+const EVENT_FILENAME_RE = /^(0|[1-9][0-9]*)\.json$/;
+const TERMINAL_EVENT_TYPES = new Set([
+    "RunCompleted",
+    "RunFailed",
+    "RunCancelled",
+]);
+/**
+ * Fold a terminated run's per-event `events/<seq>.json` blobs into one
+ * combined `events.jsonl`, dropping the per-event files. This shrinks the
+ * repo's file count -- and so every per-commit cost that scales with it --
+ * without losing any event.
+ *
+ * Idempotent and terminal-only: a run already sealed (no `events/` subtree)
+ * or one whose latest event is not terminal is left untouched, so the call
+ * is safe to repeat. The live caller fires it once per run, right after the
+ * run terminates; a bounded recovery sweep that would re-fire it to seal a
+ * run whose fold a crash interrupted is not yet implemented.
+ *
+ * The combined file is the verbatim byte concatenation of the per-event
+ * blobs in seq order (`encodeCombinedEventLog`), the exact shape the
+ * workflow-run kind handler's compaction validation requires. It is written
+ * as a sibling of `events/`, so returning it from the merge while omitting
+ * the per-event files lets the substrate's prefix clear drop them.
+ */
+export async function compactRunEvents(opts) {
+    const fs = await import("node:fs/promises");
+    const path = await import("node:path");
+    const dir = opts.substrate.getRepoDir(opts.repoId);
+    const eventsDir = path.join(dir, RUNS_PREFIX, opts.runId, EVENTS_DIR);
+    // Cheap pre-check off the working tree to skip an empty commit when there
+    // is nothing to seal (already combined, or not yet terminal). The merge
+    // re-reads the prefix under the per-repo lock, so the seal stays
+    // consistent if another writer raced in between.
+    let filenames;
+    try {
+        filenames = await fs.readdir(eventsDir);
+    }
+    catch (cause) {
+        if (isErrnoNotFound(cause))
+            return { compacted: false };
+        throw cause;
+    }
+    const seqs = [];
+    for (const name of filenames) {
+        const match = EVENT_FILENAME_RE.exec(name);
+        if (match === null || match[1] === undefined)
+            continue;
+        seqs.push(Number.parseInt(match[1], 10));
+    }
+    if (seqs.length === 0)
+        return { compacted: false };
+    const lastRaw = await fs.readFile(path.join(eventsDir, `${String(Math.max(...seqs))}.json`), "utf8");
+    let parsed;
+    try {
+        parsed = JSON.parse(lastRaw);
+    }
+    catch {
+        return { compacted: false };
+    }
+    if (typeof parsed !== "object" || parsed === null || !("type" in parsed)) {
+        return { compacted: false };
+    }
+    const lastType = parsed.type;
+    if (typeof lastType !== "string" || !TERMINAL_EVENT_TYPES.has(lastType)) {
+        return { compacted: false };
+    }
+    const prefix = `${RUNS_PREFIX}/${opts.runId}/${EVENTS_DIR}/`;
+    const combinedPath = `${RUNS_PREFIX}/${opts.runId}/${WORKFLOW_RUN_EVENTS_FILE}`;
+    const principal = {
+        kind: SUPERVISOR_PRINCIPAL_KIND,
+        deploymentId: opts.deploymentId,
+    };
+    let sealed = false;
+    await opts.substrate.writeTreePreservingPrefix(principal, opts.repoId, opts.ref, {
+        preservePrefix: prefix,
+        merge: async (existing) => {
+            const entries = [];
+            for (const [filepath, bytes] of existing) {
+                const name = filepath.slice(prefix.length);
+                const match = EVENT_FILENAME_RE.exec(name);
+                if (match === null || match[1] === undefined) {
+                    throw new Error(`supervisor run-event-compaction: unexpected non-event file ${filepath} under run ${opts.runId}; refusing to compact`);
+                }
+                entries.push({ seq: Number.parseInt(match[1], 10), bytes });
+            }
+            if (entries.length === 0)
+                return {};
+            entries.sort((a, b) => a.seq - b.seq);
+            sealed = true;
+            return {
+                [combinedPath]: encodeCombinedEventLog(entries.map((e) => e.bytes)),
+            };
+        },
+        message: `compact run ${opts.runId} events`,
+    });
+    return { compacted: sealed };
+}
+function isErrnoNotFound(cause) {
+    if (cause === null || typeof cause !== "object")
+        return false;
+    return cause.code === "ENOENT";
+}

package/dist/supervisor/spawn-env.d.ts

@@ -0,0 +1,39 @@
+export interface ChildSpawnEnvParts {
+    /**
+     * The deployment's stable substrate env (DATA_DIR, the adapter manifest,
+     * and so on), frozen for the deployment's lifetime. Layered UNDER the
+     * dynamic env fragment (so a host revision wins) and the per-spawn anchors
+     * (so a required key is never shadowed).
+     */
+    substrateEnv: Record<string, string>;
+    /**
+     * Host-supplied dynamic env fragment, recomputed for every spawn and
+     * respawn. Its keys layer OVER `substrateEnv` (so a value the host revised
+     * between spawns wins) and UNDER the required anchors. Returns `{}` when
+     * the host has no dynamic entries.
+     */
+    dynamicSpawnEnv: () => Record<string, string>;
+    /** Supervisor-minted IPC channel id for this spawn. */
+    channelId: string;
+    /** Shared HMAC key for the event channel, minted for this spawn. */
+    hmacKey: Uint8Array;
+    /** Supervisor's Ed25519 public key for this spawn's control channel. */
+    hostPublicKey: Uint8Array;
+    /** Deployment identity the supervisor manages. */
+    deploymentId: string;
+    /** Mail address the deployment registered on the bus. */
+    deploymentMailAddress: string;
+    /** Step count of the deployed workflow (`stepOrder.length`). */
+    stepCount: number;
+    /** Content hash of the deployed workflow definition. */
+    definitionHash: string;
+    /** Whether this deployment's agent is warm-kept across messages. */
+    warmKeep: boolean;
+}
+/**
+ * Build the spawn-time env for a workflow-process child. The single
+ * producer of what `parseSpawnTimeEnv` consumes; the initial spawn and
+ * every recycle respawn both call it, so neither can drift from the
+ * required-key contract.
+ */
+export declare function buildChildSpawnEnv(parts: ChildSpawnEnvParts): Record<string, string>;

package/dist/supervisor/spawn-env.js

@@ -0,0 +1,36 @@
+// Supervisor-side producer of the workflow-process child's spawn-time env.
+//
+// Both the initial spawn and every recycle respawn route the env through
+// this single builder, so the required-key contract the child-side parser
+// (`parseSpawnTimeEnv`) enforces has exactly one producer. A divergence
+// between the two paths -- the recycle env once omitted `STEP_COUNT` and
+// broke every recycle -- is no longer expressible: the required keys are
+// built as an exactly-typed record, so omitting one is a compile error.
+import { hexEncode } from "@intx/types";
+/**
+ * Build the spawn-time env for a workflow-process child. The single
+ * producer of what `parseSpawnTimeEnv` consumes; the initial spawn and
+ * every recycle respawn both call it, so neither can drift from the
+ * required-key contract.
+ */
+export function buildChildSpawnEnv(parts) {
+    // Exactly-typed so omitting a required key fails the type-check rather
+    // than surfacing as a child env-parse abort in production.
+    const required = {
+        IPC_CHANNEL_ID: parts.channelId,
+        IPC_HMAC_KEY: hexEncode(parts.hmacKey),
+        HOST_PUBKEY: hexEncode(parts.hostPublicKey),
+        DEPLOYMENT_ID: parts.deploymentId,
+        DEFINITION_HASH: parts.definitionHash,
+        MAILBOX_ADDRESS: parts.deploymentMailAddress,
+        STEP_COUNT: String(parts.stepCount),
+    };
+    return {
+        ...parts.substrateEnv,
+        // Host-revised entries win over the frozen substrate env; the required
+        // anchors below still win over everything.
+        ...parts.dynamicSpawnEnv(),
+        ...required,
+        WARM_KEEP: parts.warmKeep ? "true" : "false",
+    };
+}