@intx/workflow-host 0.2.2

package/dist/seams/signal-channel.js

@@ -0,0 +1,304 @@
+// Production workflow-host signal channel (Seam 3, log-tail wait).
+//
+// The signal channel is constructed per run by the host's runtime
+// wiring. Its `deliver` commits a `SignalReceived` blob to the run's
+// event log; commit-success is the dedup gate (the state machine's
+// `observedSignalIds` rejects a duplicate `signalId` on the next
+// transition). `awaitNext` consults the state-machine `RunState` for
+// signals that were committed and reduced into `unconsumedSignals`
+// before the awaiter subscribed, then falls back to a per-name
+// `subscribeKind` tail of the run's events ref.
+//
+// Per-name FIFO across concurrent awaiters: the channel maintains an
+// awaiter queue per signal name. A single `subscribeKind` loop per
+// name pulls events from the substrate; each matching event resolves
+// the head of that queue. The loop starts on first `awaitNext` for a
+// name and tears down when the queue empties or `stop()` is called.
+//
+// Commit-ordering invariant: `deliver` commits the `SignalReceived`
+// event blob first, then returns. Resolution of an awaiter happens
+// from the `subscribeKind` loop only after the substrate has surfaced
+// the commit. The awaiter is never resolved from inside `deliver`'s
+// call site, so resume-after-crash sees a coherent log: an awaiter
+// that resolved must have a corresponding committed `SignalReceived`.
+import { type } from "arktype";
+import { subscribeKind } from "@intx/hub-sessions/substrate";
+/**
+ * Substrate-shape envelope for the `SignalReceived` event blob
+ * committed to `runs/<runId>/events/<seq>.json`. The validator covers
+ * the single event type the signal channel both reads (live tail) and
+ * writes (deliver). Fields ride at the top level so the shape is
+ * symmetric with the runtime body's append shape -- a downstream
+ * reader that hydrates the envelope as a state-machine `WorkflowEvent`
+ * sees `signalName`/`signalId`/`payload` regardless of whether the
+ * commit came from the signal channel's `deliver` or the runtime
+ * body's `commit` of a SignalReceived after `awaitNext`. Non-signal
+ * blobs at the same path prefix do not match the kinds filter inside
+ * `subscribeKind`.
+ */
+export const SignalReceivedEnvelope = type({
+    type: "'SignalReceived'",
+    signalName: "string",
+    signalId: "string",
+    payload: "unknown",
+});
+export function createWorkflowHostSignalChannel(opts) {
+    const awaiters = new Map();
+    const subscriptions = new Map();
+    let stopped = false;
+    function peekState(name) {
+        const state = opts.readState();
+        const queue = state.unconsumedSignals.get(name);
+        if (queue === undefined || queue.length === 0)
+            return null;
+        const head = queue[0];
+        if (head === undefined)
+            return null;
+        // The state-machine `unconsumedSignals` is drained by the
+        // runtime body's next `SignalAwaited` reduction, not by the
+        // channel. The channel reads the head; the caller commits the
+        // SignalAwaited that consumes it. This separation keeps the
+        // channel free of state-machine mutation responsibilities.
+        return { payload: head.payload, signalId: head.id };
+    }
+    function matchesAwaiter(entry, name) {
+        if (entry.runId !== opts.runId)
+            return false;
+        if (entry.event.type !== "SignalReceived")
+            return false;
+        return entry.event.signalName === name;
+    }
+    function shiftAwaiter(name) {
+        const queue = awaiters.get(name);
+        if (queue === undefined || queue.length === 0)
+            return null;
+        const head = queue.shift();
+        if (head === undefined)
+            return null;
+        if (head.signal !== undefined && head.onAbort !== undefined) {
+            head.signal.removeEventListener("abort", head.onAbort);
+        }
+        if (queue.length === 0)
+            awaiters.delete(name);
+        return head;
+    }
+    function awaiterCount(name) {
+        const queue = awaiters.get(name);
+        if (queue === undefined)
+            return 0;
+        return queue.length;
+    }
+    function startNameSubscription(name) {
+        if (subscriptions.has(name))
+            return;
+        const abort = new AbortController();
+        // The teardown must run synchronously *before* the awaiter wakes
+        // when this loop drains, otherwise the awaiter's continuation
+        // (which often calls awaitNext again on the same name) sees the
+        // leaked subscription entry and short-circuits in
+        // startNameSubscription, stranding the new awaiter on a dead
+        // subscribeKind loop. Removing the entry from `subscriptions` and
+        // aborting *before* resolving the awaiter keeps the per-name
+        // invariant intact across multi-round resolution cycles.
+        const teardown = () => {
+            if (subscriptions.get(name)?.abort === abort) {
+                subscriptions.delete(name);
+            }
+            abort.abort();
+        };
+        const done = (async () => {
+            try {
+                const iter = subscribeKind(opts.repoStore, opts.principal, opts.repoId, opts.ref, SignalReceivedEnvelope, {
+                    signal: abort.signal,
+                    from: "head",
+                    kinds: ["SignalReceived"],
+                });
+                for await (const entry of iter) {
+                    if (stopped)
+                        break;
+                    if (!matchesAwaiter(entry, name))
+                        continue;
+                    const observed = opts.readState().observedSignalIds;
+                    if (observed.has(entry.event.signalId))
+                        continue;
+                    const next = shiftAwaiter(name);
+                    if (next === null) {
+                        // No awaiter left -- the queue was drained between the
+                        // event landing and this loop reaching it. The reduced
+                        // state machine queues the event into
+                        // `unconsumedSignals`; the next `awaitNext` for the same
+                        // name picks it up via the state-reader path.
+                        break;
+                    }
+                    if (awaiterCount(name) === 0) {
+                        // Resolving the last awaiter on this subscription. Tear
+                        // down before the resolve so any awaitNext call inside
+                        // the awaiter's continuation installs a fresh
+                        // subscription instead of joining a dead one.
+                        teardown();
+                        next.resolve({
+                            payload: entry.event.payload,
+                            signalId: entry.event.signalId,
+                        });
+                        return;
+                    }
+                    next.resolve({
+                        payload: entry.event.payload,
+                        signalId: entry.event.signalId,
+                    });
+                }
+            }
+            finally {
+                // Catches the queue-drained natural break, the `stopped`
+                // bail, and any error escaping the loop. The abort path
+                // through `stopSubscription` already deleted the Map entry;
+                // the get(...)?.abort guard makes this idempotent.
+                teardown();
+            }
+        })();
+        subscriptions.set(name, { abort, done });
+    }
+    async function stopSubscription(name) {
+        const sub = subscriptions.get(name);
+        if (sub === undefined)
+            return;
+        subscriptions.delete(name);
+        sub.abort.abort();
+        await sub.done.catch(() => {
+            /* swallow aborted-iterator surface */
+        });
+    }
+    return {
+        async deliver(name, payload, signalId) {
+            if (stopped) {
+                throw new Error("signal channel: deliver after stop");
+            }
+            const id = signalId ?? opts.newId();
+            const at = opts.clock().toISOString();
+            const prefix = `runs/${opts.runId}/events/`;
+            await opts.repoStore.writeTreePreservingPrefix(opts.principal, opts.repoId, opts.ref, {
+                preservePrefix: prefix,
+                merge: async (existing) => {
+                    let maxSeq = -1;
+                    let duplicate = false;
+                    for (const [filepath, contents] of existing) {
+                        const fname = filepath.slice(prefix.length);
+                        const match = /^(0|[1-9][0-9]*)\.json$/.exec(fname);
+                        if (match === null)
+                            continue;
+                        const seqStr = match[1];
+                        if (seqStr === undefined)
+                            continue;
+                        const seq = Number.parseInt(seqStr, 10);
+                        if (seq > maxSeq)
+                            maxSeq = seq;
+                        try {
+                            const parsed = JSON.parse(new TextDecoder().decode(contents));
+                            if (isMatchingSignalId(parsed, id)) {
+                                duplicate = true;
+                            }
+                        }
+                        catch {
+                            // A corrupt blob is rejected by validatePush at write
+                            // time. Treat as non-matching here.
+                        }
+                    }
+                    const out = {};
+                    for (const [filepath, contents] of existing) {
+                        out[filepath] = new TextDecoder().decode(contents);
+                    }
+                    if (duplicate)
+                        return out;
+                    const nextSeq = maxSeq + 1;
+                    // The workflow-run kind handler's `EventEnvelope`
+                    // validator requires `seq: number` on every event blob;
+                    // the same `nextSeq` we use to mint the filename also
+                    // carries into the body so a reader that hydrates the
+                    // envelope (state-machine resume, audit reads) sees a
+                    // self-describing event without consulting the filename.
+                    out[`${prefix}${String(nextSeq)}.json`] = JSON.stringify({
+                        type: "SignalReceived",
+                        seq: nextSeq,
+                        signalName: name,
+                        signalId: id,
+                        payload,
+                        at,
+                    });
+                    return out;
+                },
+                message: `SignalReceived ${id} (${name}) for run ${opts.runId}`,
+            });
+        },
+        async awaitNext(name, signal) {
+            if (stopped) {
+                throw new Error("signal channel: awaitNext after stop");
+            }
+            if (signal !== undefined && signal.aborted) {
+                throw new Error("aborted");
+            }
+            // Drain the state-machine queue first. A signal that was
+            // committed before the awaiter subscribed lives in
+            // `unconsumedSignals` after log replay.
+            const queued = peekState(name);
+            if (queued !== null)
+                return queued;
+            return new Promise((resolve, reject) => {
+                const awaiter = {
+                    resolve,
+                    reject,
+                    ...(signal !== undefined ? { signal } : {}),
+                };
+                if (signal !== undefined) {
+                    const onAbort = () => {
+                        const list = awaiters.get(name);
+                        if (list !== undefined) {
+                            const idx = list.indexOf(awaiter);
+                            if (idx >= 0)
+                                list.splice(idx, 1);
+                            if (list.length === 0) {
+                                awaiters.delete(name);
+                                void stopSubscription(name);
+                            }
+                        }
+                        reject(new Error("aborted"));
+                    };
+                    awaiter.onAbort = onAbort;
+                    signal.addEventListener("abort", onAbort, { once: true });
+                }
+                let list = awaiters.get(name);
+                if (list === undefined) {
+                    list = [];
+                    awaiters.set(name, list);
+                }
+                list.push(awaiter);
+                startNameSubscription(name);
+            });
+        },
+        async stop() {
+            if (stopped)
+                return;
+            stopped = true;
+            for (const list of awaiters.values()) {
+                for (const awaiter of list) {
+                    if (awaiter.signal !== undefined && awaiter.onAbort !== undefined) {
+                        awaiter.signal.removeEventListener("abort", awaiter.onAbort);
+                    }
+                    awaiter.reject(new Error("signal channel stopped"));
+                }
+            }
+            awaiters.clear();
+            const names = [...subscriptions.keys()];
+            for (const name of names) {
+                await stopSubscription(name);
+            }
+        },
+    };
+}
+function isMatchingSignalId(parsed, signalId) {
+    if (typeof parsed !== "object" || parsed === null)
+        return false;
+    const obj = parsed;
+    if (obj.type !== "SignalReceived")
+        return false;
+    return obj.signalId === signalId;
+}

package/dist/supervisor/cancel-signing.d.ts

@@ -0,0 +1,68 @@
+import type { RepoId, RepoStore as SubstrateRepoStore } from "@intx/hub-sessions/substrate";
+import type { CancelOrigin } from "@intx/workflow";
+import type { PrincipalSigner, SignedPayload, WorkflowSupervisorPrincipalKind } from "./types.js";
+/**
+ * The supervisor's stable principal kind used for every supervisor-
+ * authored commit (CancelRequested for `self`/`supervisor-drain`/
+ * `supervisor-operator` origins, plus drain audit frames in later
+ * commits). The kind handler reads this off the substrate's per-
+ * push principal and enforces the principal-vs-origin map.
+ */
+export declare const SUPERVISOR_PRINCIPAL_KIND: WorkflowSupervisorPrincipalKind;
+export type CommitCancelRequestedOpts = {
+    /** 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 id whose event log receives the CancelRequested entry. */
+    runId: string;
+    /** Cancellation origin from the Q3 map. */
+    origin: CancelOrigin;
+    /**
+     * Human-readable reason. For `self`-origin requests the supervisor
+     * forwards the workflow-process's stated reason verbatim; the
+     * other origins carry the supervisor's own source of truth.
+     */
+    reason: string;
+    /**
+     * ISO-8601 commit timestamp the event carries. The supervisor
+     * controls this so tests can pin to a deterministic value.
+     */
+    at: string;
+    /**
+     * Host-supplied per-principal signing callback. Invoked here with
+     * `"supervisor"` and the canonical event-payload bytes; never with
+     * the supervisor's private key visible to the supervisor module.
+     */
+    signAsPrincipal: PrincipalSigner;
+};
+/**
+ * Result of a successful CancelRequested commit. The committed
+ * payload (including the attached signature envelope) is surfaced so
+ * callers that need to audit the exact on-disk bytes have them
+ * without re-reading the repo.
+ */
+export type CommitCancelRequestedResult = {
+    /** Substrate-assigned commit SHA the append produced. */
+    commitSha: string;
+    /** Per-run sequence number the append landed at. */
+    seq: number;
+    /** Signature the supervisor attached to the event. */
+    signature: SignedPayload;
+};
+declare const OnDiskEnvelope: import("arktype/internal/variants/object.ts").ObjectType<{
+    seq: number;
+    type: string;
+}, {}>;
+/**
+ * Commit a CancelRequested event signed by the supervisor on behalf
+ * of the named origin. The `self`-origin path is identical to the
+ * other supervisor origins from the substrate's perspective; the
+ * caller passes the workflow-process's stated reason through.
+ */
+export declare function commitCancelRequested(opts: CommitCancelRequestedOpts): Promise<CommitCancelRequestedResult>;
+export { OnDiskEnvelope as CancelRequestedOnDiskEnvelopeForTest };

package/dist/supervisor/cancel-signing.js

@@ -0,0 +1,144 @@
+// `CancelRequested` signing path for the per-deployment supervisor.
+//
+// Every CancelRequested origin flows through the supervisor's
+// signing identity -- including the
+// `self`-origin case where the workflow-process passes its stated
+// reason to the supervisor via the control IPC and the supervisor
+// wraps it into a signed event. The child has no asymmetric keypair
+// of its own; routing all four origins through the same supervisor-
+// signed path keeps the trust anchor inventory at one signing key
+// per deployment (plus the hub's, for `hub-admin`).
+//
+// The supervisor owns the Ed25519 signing key (held in closure by
+// the `signAsPrincipal` callback the host injects); this module
+// composes the call sequence:
+//   1. Build the CancelRequested event payload from the requested
+//      origin and reason.
+//   2. Serialize a canonical byte representation the signing
+//      callback signs.
+//   3. Attach the signature to the on-the-wire event and append it
+//      to the workflow-run repo via the substrate handle.
+// The substrate-side workflow-run kind handler enforces the
+// principal-vs-origin map at push validation (a `self`/`supervisor-
+// drain`/`supervisor-operator` origin must arrive carried by a
+// `supervisor`-kind principal), which is the cross-check the
+// supervisor's runtime-side signing keeps coherent.
+import { type } from "arktype";
+import { hexEncode } from "@intx/types";
+/**
+ * Path inside the workflow-run repo each `CancelRequested` event
+ * lands under. Matches the layout the workflow-run kind handler
+ * validates: `runs/<runId>/events/<seq>.json`.
+ */
+const RUNS_PREFIX = "runs";
+const EVENTS_DIR = "events";
+/**
+ * The supervisor's stable principal kind used for every supervisor-
+ * authored commit (CancelRequested for `self`/`supervisor-drain`/
+ * `supervisor-operator` origins, plus drain audit frames in later
+ * commits). The kind handler reads this off the substrate's per-
+ * push principal and enforces the principal-vs-origin map.
+ */
+export const SUPERVISOR_PRINCIPAL_KIND = "supervisor";
+const EVENT_FILENAME_RE = /^(0|[1-9][0-9]*)\.json$/;
+const OnDiskEnvelope = type({
+    seq: "number >= 0",
+    type: "string",
+    "+": "ignore",
+});
+/**
+ * Build the canonical bytes the supervisor signs for a
+ * CancelRequested event. The on-wire shape carries the same fields
+ * the workflow-run kind handler validates plus a `signature`
+ * sub-object the supervisor populates after this byte string is
+ * signed. Signing the payload *without* the signature field keeps
+ * the verifier's reconstruction trivial: strip `signature` from the
+ * blob, canonicalize, verify against `signature.sig`.
+ */
+function buildPayloadBytes(args) {
+    const canonical = {
+        type: "CancelRequested",
+        seq: args.seq,
+        runId: args.runId,
+        at: args.at,
+        reason: args.reason,
+        origin: args.origin,
+    };
+    return new TextEncoder().encode(JSON.stringify(canonical));
+}
+/**
+ * Commit a CancelRequested event signed by the supervisor on behalf
+ * of the named origin. The `self`-origin path is identical to the
+ * other supervisor origins from the substrate's perspective; the
+ * caller passes the workflow-process's stated reason through.
+ */
+export async function commitCancelRequested(opts) {
+    const prefix = `${RUNS_PREFIX}/${opts.runId}/${EVENTS_DIR}/`;
+    const principal = {
+        kind: SUPERVISOR_PRINCIPAL_KIND,
+        deploymentId: opts.deploymentId,
+    };
+    let resolved = null;
+    const { commitSha } = await opts.substrate.writeTreePreservingPrefix(principal, opts.repoId, opts.ref, {
+        preservePrefix: prefix,
+        merge: async (existing) => {
+            let maxSeq = -1;
+            for (const filepath of existing.keys()) {
+                const name = filepath.slice(prefix.length);
+                const match = EVENT_FILENAME_RE.exec(name);
+                if (match === null)
+                    continue;
+                const seqStr = match[1];
+                if (seqStr === undefined)
+                    continue;
+                const seq = Number.parseInt(seqStr, 10);
+                if (seq > maxSeq)
+                    maxSeq = seq;
+            }
+            const nextSeq = maxSeq + 1;
+            const payloadBytes = buildPayloadBytes({
+                seq: nextSeq,
+                runId: opts.runId,
+                reason: opts.reason,
+                origin: opts.origin,
+                at: opts.at,
+            });
+            const signature = await opts.signAsPrincipal(SUPERVISOR_PRINCIPAL_KIND, payloadBytes);
+            resolved = { seq: nextSeq, signature };
+            const onDisk = {
+                type: "CancelRequested",
+                seq: nextSeq,
+                runId: opts.runId,
+                at: opts.at,
+                reason: opts.reason,
+                origin: opts.origin,
+                signature: serializeSignedPayload(signature),
+            };
+            const files = {};
+            for (const [k, v] of existing)
+                files[k] = v;
+            files[`${prefix}${String(nextSeq)}.json`] = JSON.stringify(onDisk);
+            return files;
+        },
+        message: `append CancelRequested ${opts.origin} for run ${opts.runId}`,
+    });
+    if (resolved === null) {
+        throw new Error(`supervisor cancel-signing: merge callback did not assign a sequence number for run ${opts.runId}`);
+    }
+    const final = resolved;
+    return { commitSha, seq: final.seq, signature: final.signature };
+}
+/**
+ * Wire shape for a SignedPayload inside a CancelRequested event
+ * blob. The signature bytes are hex-encoded for JSON-safety; the
+ * principal kind rides alongside so an audit-log walker can verify
+ * the signature without consulting a sidecar manifest for which key
+ * to load.
+ */
+function serializeSignedPayload(signed) {
+    return {
+        principalKind: signed.principalKind,
+        sig: hexEncode(signed.sig),
+    };
+}
+export { OnDiskEnvelope as CancelRequestedOnDiskEnvelopeForTest };

package/dist/supervisor/child-termination.d.ts

@@ -0,0 +1,51 @@
+import { getLogger } from "@intx/log";
+import type { SubprocessHandle } from "./types.js";
+/**
+ * Default kill-timeout between SIGTERM and SIGKILL. Used when a caller
+ * supplies no override; the recycle path exposes it as a per-deployment
+ * override and the spawn ready-timeout teardown uses it directly.
+ */
+export declare const DEFAULT_KILL_TIMEOUT_MS = 5000;
+/**
+ * Default deadline for a child's `ready` handshake -- the window a freshly
+ * spawned child has to emit `ready` before the supervisor kills it and
+ * treats the spawn (or recycle respawn) as failed. Used when a caller
+ * supplies no override. Shared here, alongside the kill default, so both
+ * the spawn path and the recycle path bound the handshake identically
+ * without either re-declaring the constant.
+ */
+export declare const DEFAULT_READY_TIMEOUT_MS = 30000;
+/**
+ * Injected dependencies for `killChildHandle`. `setTimer`/`clearTimer`
+ * default to the real `setTimeout`/`clearTimeout` when omitted so tests
+ * can substitute a deterministic timer. `logger` is supplied by the
+ * caller so the SIGKILL-escalation warning is attributed to the path that
+ * initiated the kill (recycle vs. spawn) rather than a single shared
+ * namespace.
+ */
+export interface KillChildHandleDeps {
+    setTimer?: (cb: () => void, ms: number) => unknown;
+    clearTimer?: (handle: unknown) => void;
+    logger: ReturnType<typeof getLogger>;
+}
+/**
+ * Issue SIGTERM and wait for the child to exit. If the exit does not land
+ * within `killTimeoutMs`, escalate to SIGKILL and wait again. SIGKILL is
+ * unignorable, so `exited` is guaranteed to settle -- a child that traps
+ * or never services SIGTERM cannot wedge this call. The supervisor's
+ * spawner returns the `exited` promise; this helper does not consult OS
+ * primitives directly.
+ */
+export declare function killChildHandle(handle: SubprocessHandle, killTimeoutMs: number, deps: KillChildHandleDeps): Promise<void>;
+/**
+ * A resolve-only deadline: a promise that resolves after `ms` via the
+ * injected `setTimer`, plus the timer handle so the caller can cancel it
+ * with the matching `clearTimer` once the race settles. It only ever
+ * resolves, so it contributes no rejection of its own to a race.
+ */
+export declare function waitDeadline(setTimer: (cb: () => void, ms: number) => unknown, ms: number): {
+    promise: Promise<void>;
+    handle: unknown;
+};
+export declare function defaultSetTimer(cb: () => void, ms: number): unknown;
+export declare function defaultClearTimer(handle: unknown): void;

package/dist/supervisor/child-termination.js

@@ -0,0 +1,76 @@
+// Child termination plus the resolve-only deadline / injectable-timer
+// primitives its escalation drives. Two supervisor paths need to bound a
+// wait on a workflow-process child with a timer and then force the child
+// down: the recycle path (SIGTERM -> deadline -> SIGKILL between cohorts)
+// and the spawn path's ready-handshake timeout (a child that spawns but
+// never emits `ready`). Both need the same `killChildHandle` escalation
+// and the same resolve-only `waitDeadline` raced against a child event,
+// and both need injectable timers so tests can drive the deadline
+// deterministically. Factoring them here keeps one implementation instead
+// of a copy per path.
+import { getLogger } from "@intx/log";
+/**
+ * Default kill-timeout between SIGTERM and SIGKILL. Used when a caller
+ * supplies no override; the recycle path exposes it as a per-deployment
+ * override and the spawn ready-timeout teardown uses it directly.
+ */
+export const DEFAULT_KILL_TIMEOUT_MS = 5_000;
+/**
+ * Default deadline for a child's `ready` handshake -- the window a freshly
+ * spawned child has to emit `ready` before the supervisor kills it and
+ * treats the spawn (or recycle respawn) as failed. Used when a caller
+ * supplies no override. Shared here, alongside the kill default, so both
+ * the spawn path and the recycle path bound the handshake identically
+ * without either re-declaring the constant.
+ */
+export const DEFAULT_READY_TIMEOUT_MS = 30_000;
+/**
+ * Issue SIGTERM and wait for the child to exit. If the exit does not land
+ * within `killTimeoutMs`, escalate to SIGKILL and wait again. SIGKILL is
+ * unignorable, so `exited` is guaranteed to settle -- a child that traps
+ * or never services SIGTERM cannot wedge this call. The supervisor's
+ * spawner returns the `exited` promise; this helper does not consult OS
+ * primitives directly.
+ */
+export async function killChildHandle(handle, killTimeoutMs, deps) {
+    const setTimer = deps.setTimer ?? defaultSetTimer;
+    const clearTimer = deps.clearTimer ?? defaultClearTimer;
+    handle.kill("SIGTERM");
+    const sigTermDeadline = waitDeadline(setTimer, killTimeoutMs);
+    const exitedFirst = await Promise.race([
+        handle.exited.then(() => "exited"),
+        sigTermDeadline.promise.then(() => "deadline"),
+    ]);
+    if (exitedFirst === "exited") {
+        clearTimer(sigTermDeadline.handle);
+        return;
+    }
+    clearTimer(sigTermDeadline.handle);
+    deps.logger
+        .warn `child termination: SIGTERM did not land within ${String(killTimeoutMs)}ms; escalating to SIGKILL`;
+    handle.kill("SIGKILL");
+    await handle.exited.catch(() => {
+        /* swallowed: a non-zero exit on SIGKILL is the expected outcome;
+           termination treats handle exit as success regardless of code. */
+    });
+}
+/**
+ * A resolve-only deadline: a promise that resolves after `ms` via the
+ * injected `setTimer`, plus the timer handle so the caller can cancel it
+ * with the matching `clearTimer` once the race settles. It only ever
+ * resolves, so it contributes no rejection of its own to a race.
+ */
+export function waitDeadline(setTimer, ms) {
+    let h;
+    const promise = new Promise((resolve) => {
+        h = setTimer(() => resolve(), ms);
+    });
+    return { promise, handle: h };
+}
+export function defaultSetTimer(cb, ms) {
+    return setTimeout(cb, ms);
+}
+export function defaultClearTimer(handle) {
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- production wiring; the handle is the value `setTimeout` returned, narrowed back at the boundary
+    clearTimeout(handle);
+}