@boardwalk-labs/runner 0.1.10 → 0.1.12

package/binding.gyp

@@ -0,0 +1,12 @@
+{
+  "targets": [
+    {
+      "target_name": "bw_reseed",
+      "sources": ["native/reseed.c"],
+      "include_dirs": ["<(node_root_dir)/deps/openssl/openssl/include"],
+      "conditions": [
+        ["OS=='linux'", { "cflags": ["-fvisibility=hidden"] }]
+      ]
+    }
+  ]
+}

package/dist/runtime/agent/budget.d.ts

@@ -74,7 +74,7 @@ export declare class BudgetMeter {
     constructor(opts: BudgetMeterOptions);
     /**
      * Add a usage delta to the accumulator + recompute USD. `realCostUsd`, when provided, is the EXACT
-     * upstream cost the broker observed for this turn (OpenRouter's per-request `usage.cost`) — used
+     * upstream cost the broker observed for this turn (the managed provider's per-request cost) — used
      * verbatim so the `max_usd` cap tracks ACTUAL spend (already cache-discounted, model-correct).
      * Omitted for a BYO turn (no upstream price) or a managed turn whose cost the broker couldn't read,
      * which fall back to the representative-rate {@link costFor} estimate. Token counts accumulate on
@@ -83,7 +83,7 @@ export declare class BudgetMeter {
     addUsage(delta: UsageDelta, realCostUsd?: number): void;
     /**
      * THIS SESSION's accumulator snapshot (excludes prior-session usage). Read by per-session token
-     * metering — which reports token deltas to Stripe (deferred; not yet wired into the brokered
+     * metering — which reports token deltas to the platform (deferred; not yet wired into the brokered
      * loop) — and by audit/post-run cost rollups. Cap enforcement uses {@link cumulative} instead.
      */
     snapshot(): BudgetSnapshot;
@@ -92,7 +92,7 @@ export declare class BudgetMeter {
      * construction. Cap enforcement ({@link assertWithinCaps}) and checkpoint persistence use
      * this so a run that resumes after a sleep/wait/crash is bounded by its declared caps across
      * the whole run — not once per session. `snapshot()` stays session-local because
-     * per-session token metering reports token deltas; seeding it would double-report to Stripe.
+     * per-session token metering reports token deltas; seeding it would double-report usage.
      */
     cumulative(): BudgetSnapshot;
     /**
@@ -116,8 +116,8 @@ export declare class BudgetMeter {
     /**
      * USD cost for a single delta — the representative-rate ESTIMATE used only when the broker reports
      * no real upstream cost for the turn (a BYO-provider turn, or a managed turn whose cost tap missed).
-     * Managed turns instead carry OpenRouter's exact `usage.cost` through to {@link addUsage}. Public so
-     * the loop can stamp the per-step `cost_usd` column on `run_steps` without re-deriving the rate table.
+     * Managed turns instead carry the managed provider's exact per-request cost through to {@link addUsage}. Public so
+     * the loop can stamp the per-step cost without re-deriving the rate table.
      */
     costFor(delta: UsageDelta): number;
 }

package/dist/runtime/agent/budget.js

@@ -5,12 +5,12 @@
 // `AppError(BUDGET_EXCEEDED)` and the loop tears down with a `turn_ended
 // reason='error'` event.
 //
-// USD here tracks the bill closely: for a MANAGED turn the meter is fed OpenRouter's exact per-request
-// `usage.cost` (already cache-discounted + model-correct), so the `max_usd` cap reflects real spend —
+// USD here tracks the bill closely: for a MANAGED turn the meter is fed the managed provider's exact
+// per-request cost (already cache-discounted + model-correct), so the `max_usd` cap reflects real spend —
 // not a hand-rolled token estimate. Only a BYO turn (no upstream price) or a managed turn whose cost
 // the broker couldn't read falls back to a single flat representative rate
 // (`model_rates.ts::BUDGET_GUARDRAIL_RATE`), since a per-`agent()`-model run has no one model. Actual
-// billing remains per-request cost pass-through via Stripe meters (the platform spec). The meter takes
+// billing is metered by the platform, not by the runner. The meter takes
 // the fallback rate as a constructor arg so tests inject a fixed rate.
 import { AppError, ErrorCode } from "../support/index.js";
 const ZERO_PRIOR = {
@@ -44,7 +44,7 @@ export class BudgetMeter {
     }
     /**
      * Add a usage delta to the accumulator + recompute USD. `realCostUsd`, when provided, is the EXACT
-     * upstream cost the broker observed for this turn (OpenRouter's per-request `usage.cost`) — used
+     * upstream cost the broker observed for this turn (the managed provider's per-request cost) — used
      * verbatim so the `max_usd` cap tracks ACTUAL spend (already cache-discounted, model-correct).
      * Omitted for a BYO turn (no upstream price) or a managed turn whose cost the broker couldn't read,
      * which fall back to the representative-rate {@link costFor} estimate. Token counts accumulate on
@@ -59,7 +59,7 @@ export class BudgetMeter {
     }
     /**
      * THIS SESSION's accumulator snapshot (excludes prior-session usage). Read by per-session token
-     * metering — which reports token deltas to Stripe (deferred; not yet wired into the brokered
+     * metering — which reports token deltas to the platform (deferred; not yet wired into the brokered
      * loop) — and by audit/post-run cost rollups. Cap enforcement uses {@link cumulative} instead.
      */
     snapshot() {
@@ -78,7 +78,7 @@ export class BudgetMeter {
      * construction. Cap enforcement ({@link assertWithinCaps}) and checkpoint persistence use
      * this so a run that resumes after a sleep/wait/crash is bounded by its declared caps across
      * the whole run — not once per session. `snapshot()` stays session-local because
-     * per-session token metering reports token deltas; seeding it would double-report to Stripe.
+     * per-session token metering reports token deltas; seeding it would double-report usage.
      */
     cumulative() {
         const s = this.snapshot();
@@ -159,8 +159,8 @@ export class BudgetMeter {
     /**
      * USD cost for a single delta — the representative-rate ESTIMATE used only when the broker reports
      * no real upstream cost for the turn (a BYO-provider turn, or a managed turn whose cost tap missed).
-     * Managed turns instead carry OpenRouter's exact `usage.cost` through to {@link addUsage}. Public so
-     * the loop can stamp the per-step `cost_usd` column on `run_steps` without re-deriving the rate table.
+     * Managed turns instead carry the managed provider's exact per-request cost through to {@link addUsage}. Public so
+     * the loop can stamp the per-step cost without re-deriving the rate table.
      */
     costFor(delta) {
         const inputCost = ((delta.inputTokens ?? 0) * this.rate.inputPerMillion) / 1_000_000;

package/dist/runtime/agent/model_rates.js

@@ -1,17 +1,16 @@
 // The flat budget-guardrail rate — the FALLBACK basis for the in-run `max_usd` cap (BudgetMeter).
 //
-// A MANAGED turn now caps on OpenRouter's EXACT per-request `usage.cost`, forwarded from the broker to
+// A MANAGED turn now caps on the managed provider's EXACT per-request cost, forwarded from the broker to
 // the worker (inference_proxy result frame → BudgetMeter.addUsage `realCostUsd`), so the cap tracks
 // real spend — already cache-discounted + model-correct. This flat rate is used ONLY when a turn has
 // no upstream cost: a BYO-provider turn (the org pays its own key), or a managed turn whose cost the
-// broker couldn't read. It bounds runaway loops; it is NOT the bill. Actual billing is per-request
-// COST PASS-THROUGH (OpenRouter's reported cost × margin) via Stripe meters (domain/billing +
-// run_usage_service). the platform spec
+// broker couldn't read. It bounds runaway loops; it is NOT the bill. Actual billing is metered by the
+// platform, not by the runner.
 //
 // Deliberately NOT a per-model table with a silent fallback: a lookup that returns a Sonnet-class
 // default for any unknown id only created the ILLUSION of precision. The real per-request cost (above)
 // is the precise path; this rate is just the model-agnostic backstop. Un-metered managed models are
-// rejected fail-closed at resolution (domain/inference/model_resolver), so the cap never has to price
+// rejected fail-closed at resolution by the broker, so the cap never has to price
 // a model we don't support.
 /**
  * The flat representative rate (USD / million tokens) the BudgetMeter applies to the `max_usd` cap

package/dist/runtime/agent/secret_redactor.js

@@ -1,4 +1,4 @@
-// SecretRedactor — scrubs known secret values from everything bound for an LLM (the platform spec).
+// SecretRedactor — scrubs known secret values from everything bound for an LLM.
 //
 // The architectural guarantee is structural: secrets live ONLY in the workflow PROGRAM (the trusted
 // deterministic tool layer), which holds them via `secrets.get` / `ctx.secrets.resolve`. The

package/dist/runtime/cancel_watcher.js

@@ -1,4 +1,4 @@
-// CancelWatcher — stops a run when the user cancels it mid-flight (the platform spec).
+// CancelWatcher — stops a run when the user cancels it mid-flight.
 //
 // The user-cancel counterpart to CreditWatcher. One per run session. On a timer it asks — through the
 // broker (`GET /cancel`, since the runner holds no DB/Redis credential) — whether the run has been

package/dist/runtime/credit_watcher.d.ts

@@ -4,7 +4,7 @@ export interface CreditWatcherDeps {
     /** The run being watched (for correlation/logging). */
     runId: string;
     /** Resolves true while the org can keep spending; false once it's out of credit. Brokered
-     *  (`RunnerControlClient.checkCredit` → `GET /credit`), so the runner never reads Stripe. */
+     *  (`RunnerControlClient.checkCredit` → `GET /credit`), so the runner never reads billing state directly. */
     isFunded: () => Promise<boolean>;
     /** Fired exactly once when the org is first seen to be out of credit. */
     onExhausted: () => void;

package/dist/runtime/credit_watcher.js

@@ -1,14 +1,14 @@
-// CreditWatcher — stops a run when its org runs out of prepaid credit mid-flight (the platform spec).
+// CreditWatcher — stops a run when its org runs out of prepaid credit mid-flight.
 //
 // One per run session. On a timer it asks — through the broker (`GET /credit`, since the runner holds
-// no Stripe credential) — whether the org is still funded; the FIRST time it isn't, it fires
+// no billing credential) — whether the org is still funded; the FIRST time it isn't, it fires
 // `onExhausted` once (the orchestrator wires this to `AbortController.abort`, which the WorkflowHost
 // honors cooperatively) and stops checking. This is the org-level counterpart to the per-run
-// BudgetMeter cap: the run can't see Stripe balances, so funding is enforced here, out of band,
+// BudgetMeter cap: the run can't see its billing balance, so funding is enforced here, out of band,
 // against the live balance that incremental token metering keeps fresh.
 //
-// "Prompt, not instant": Stripe meter aggregation is eventually-consistent and the host honors the
-// abort at the next hook boundary, so a run stops within ~one check interval (plus Stripe's lag) of
+// "Prompt, not instant": the platform's usage metering is eventually-consistent and the host honors the
+// abort at the next hook boundary, so a run stops within ~one check interval (plus metering lag) of
 // going unfunded — bounding overshoot, not eliminating it. Applies to MANAGED and BYOK runs alike,
 // since runtime always burns credit (the gate requires the runtime floor regardless of token billing).
 import { createLogger } from "./support/index.js";

package/dist/runtime/freeze_coordinator.d.ts

@@ -0,0 +1,124 @@
+import { z } from "zod";
+import type { RelayChannel } from "./identity_relay.js";
+import type { SuspendSignal } from "./suspension.js";
+/** First retry delay after a suspend_abort (doubles per attempt, capped below). */
+export declare const ABORT_RETRY_INITIAL_MS = 30000;
+export declare const ABORT_RETRY_MAX_MS: number;
+/** The wake value inside a wake injection — `kind` echoes the parked seam's reason; the
+ *  per-kind fields are opaque to the coordinator and interpreted by the seam. */
+export declare const wakeValueSchema: z.ZodObject<{
+    kind: z.ZodEnum<{
+        sleep: "sleep";
+        human_input: "human_input";
+        workflow_call: "workflow_call";
+    }>;
+    answers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    child: z.ZodOptional<z.ZodObject<{
+        run_id: z.ZodString;
+        status: z.ZodString;
+        output: z.ZodUnknown;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type WakeValue = z.infer<typeof wakeValueSchema>;
+/** The wake-injection payload as init relays it (snake_case, the platform env contract's
+ *  sibling): fresh tokens — the frozen ones expired while suspended — plus the
+ *  authoritative wall clock (the guest's own clock was stopped) and the wake value. */
+export declare const wakePayloadSchema: z.ZodObject<{
+    run_token: z.ZodString;
+    api_token: z.ZodOptional<z.ZodString>;
+    wall_clock_ms: z.ZodNumber;
+    wake: z.ZodObject<{
+        kind: z.ZodEnum<{
+            sleep: "sleep";
+            human_input: "human_input";
+            workflow_call: "workflow_call";
+        }>;
+        answers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        child: z.ZodOptional<z.ZodObject<{
+            run_id: z.ZodString;
+            status: z.ZodString;
+            output: z.ZodUnknown;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type WakePayload = z.infer<typeof wakePayloadSchema>;
+/** What a suspending wait resolves to: the wake (the normal path), or — for a `sleep` seam
+ *  only — the abort that tells it to hold its remainder in-process (other reasons retry the
+ *  freeze internally and never surface an abort). */
+export type FreezeOutcome = {
+    kind: "wake";
+    wake: WakeValue;
+} | {
+    kind: "aborted";
+    reason: string;
+}
+/** The caller withdrew the wait via its abort signal BEFORE it froze (register-without-release:
+ *  a held gate got its answer during the hold, so it resolves in-process instead of freezing). */
+ | {
+    kind: "withdrawn";
+};
+export interface FreezeCoordinatorHooks {
+    /** Runs at quiescence, immediately before the freeze is requested: flush billable runtime
+     *  (suspended time must never appear billed) and persist the workspace. Its own failure
+     *  aborts THIS freeze attempt (the seam holds/retries) — never the run. */
+    onBeforeFreeze?: () => Promise<void>;
+    /** Runs when a wake lands, before the seam resolves: swap the run/api tokens onto the
+     *  broker client and rebase the runtime meter past the frozen window. */
+    onAfterWake?: (wake: WakePayload) => void | Promise<void>;
+}
+export interface FreezeCoordinatorDeps {
+    channel: RelayChannel;
+    now?: () => number;
+    /** Injected delay (tests). Defaults to a real timer. */
+    delay?: (ms: number) => Promise<void>;
+}
+export declare class FreezeCoordinator {
+    private readonly deps;
+    private readonly now;
+    private readonly delay;
+    private hooks;
+    /** Non-suspending runtime work in flight (the quiescence gate's count). */
+    private inFlight;
+    private quiescenceWaiters;
+    /** True from freeze request until wake/abort — new runtime work queues behind it. */
+    private freezePending;
+    private gateWaiters;
+    /** The parked suspending wait (at most one — waits serialize). */
+    private parked;
+    /** Serializes suspending waits. */
+    private chain;
+    constructor(deps: FreezeCoordinatorDeps);
+    /** Late-bound per-run hooks (the flusher/broker/redactor exist only once a run is claimed). */
+    setHooks(hooks: FreezeCoordinatorHooks): void;
+    /**
+     * Run one unit of non-suspending runtime work under the gate: queue while a freeze is
+     * pending (the work never starts, so nothing can be torn by the pause), then count it
+     * in-flight so a suspending wait holds until it drains. The gate check and the count
+     * increment share one synchronous segment — a freeze requested in between cannot miss us.
+     */
+    trackWork<T>(fn: () => Promise<T>): Promise<T>;
+    /** A suspending seam's own wait is NOT "work" — it decrements around its park so the gate
+     *  sees true quiescence. (The host wraps every hook in trackWork; the suspending seams
+     *  call these around their freeze wait.) */
+    beginWork(): void;
+    endWork(): void;
+    /**
+     * The suspending wait: hold until quiescence, run the pre-freeze hook, request the
+     * freeze, and park. The next thing this promise sees is a wake (possibly epochs later,
+     * through a restored heap) or a suspend_abort. Returns the wake, or — for `sleep` only —
+     * the abort (the seam then holds in-process); other reasons retry the freeze after a
+     * backoff. Concurrent suspending waits serialize through an internal chain.
+     */
+    suspendingWait(signal: SuspendSignal, abort?: AbortSignal): Promise<FreezeOutcome>;
+    /** Relay handler: a wake injection landed. Validates, runs the after-wake hook (token
+     *  swap + meter rebase), confirms to init, and resolves the parked seam. A wake with no
+     *  parked seam is a duplicate delivery — re-confirm (idempotent), never crash. */
+    onWake(payload: unknown): void;
+    /** Relay handler: the snapshot attempt failed; the parked seam falls back to holding. */
+    onSuspendAbort(payload: unknown): void;
+    private awaitQuiescence;
+    private releaseGate;
+    /** The host-readable wake summary on the wire (logs/metrics/placement) — the opaque
+     *  broker_signal beside it carries the full condition. */
+    private wakeConditionOf;
+}

package/dist/runtime/freeze_coordinator.js

@@ -0,0 +1,276 @@
+// FreezeCoordinator — the runtime's half of snapshot suspension on the microVM substrate.
+//
+// On this substrate the worker process NEVER exits to suspend: a suspending seam (a long
+// sleep, a human-input gate, a child-run wait) BLOCKS on a real promise, the platform
+// freezes the whole VM into a snapshot, and a later restore resolves that same promise with
+// the wake value — the heap is the literal heap, nothing replays. This coordinator owns the
+// two policies that make freezing safe and predictable:
+//
+// 1. THE QUIESCENCE GATE: never freeze while non-suspending runtime work (an agent leaf, a
+//    tool call, an artifact write) is in flight — a snapshot must not capture a live
+//    platform stream that would be dead on restore. A suspending wait created during such
+//    work HOLDS until the work drains; new runtime work that arrives while a freeze is
+//    pending QUEUES (it never started, so nothing is torn) and runs after the wake.
+// 2. SNAPSHOT-FIRST FALLBACK: a `suspend_abort` from the platform (snapshot/store/broker
+//    failure) means the seam falls back to HOLDING — a sleep waits in-process for its
+//    remainder; a human-input or child wait retries the freeze after a backoff (the host
+//    may throttle repeated attempts).
+//
+// Concurrent suspending waits SERIALIZE: the first to reach quiescence freezes with its own
+// wake condition; after its wake, the next takes its turn. (A compound wake condition —
+// one freeze covering several waits — is a future optimization, not a correctness need:
+// the heap survives every cycle.)
+//
+// The wire below this is the guest init's relay (identity_relay `openChannel`); the policy
+// above it is decided platform-side. The coordinator never interprets the wake VALUE — it
+// validates the envelope and hands `wake` to the seam that parked.
+import { z } from "zod";
+import { createLogger } from "./support/index.js";
+const log = createLogger("FreezeCoordinator");
+/** First retry delay after a suspend_abort (doubles per attempt, capped below). */
+export const ABORT_RETRY_INITIAL_MS = 30_000;
+export const ABORT_RETRY_MAX_MS = 5 * 60_000;
+/** The wake value inside a wake injection — `kind` echoes the parked seam's reason; the
+ *  per-kind fields are opaque to the coordinator and interpreted by the seam. */
+export const wakeValueSchema = z.object({
+    kind: z.enum(["sleep", "human_input", "workflow_call"]),
+    /** human_input: EVERY gate this suspension raised, keyed by gate key / tool-call id. */
+    answers: z.record(z.string(), z.unknown()).optional(),
+    /** workflow_call: the finalized child. */
+    child: z
+        .object({
+        run_id: z.string().min(1),
+        status: z.string().min(1),
+        output: z.unknown(),
+    })
+        .optional(),
+});
+/** The wake-injection payload as init relays it (snake_case, the platform env contract's
+ *  sibling): fresh tokens — the frozen ones expired while suspended — plus the
+ *  authoritative wall clock (the guest's own clock was stopped) and the wake value. */
+export const wakePayloadSchema = z.object({
+    run_token: z.string().min(1),
+    api_token: z.string().optional(),
+    wall_clock_ms: z.number(),
+    wake: wakeValueSchema,
+});
+const suspendAbortSchema = z.object({ reason: z.string().optional() });
+export class FreezeCoordinator {
+    deps;
+    now;
+    delay;
+    hooks = {};
+    /** Non-suspending runtime work in flight (the quiescence gate's count). */
+    inFlight = 0;
+    quiescenceWaiters = [];
+    /** True from freeze request until wake/abort — new runtime work queues behind it. */
+    freezePending = false;
+    gateWaiters = [];
+    /** The parked suspending wait (at most one — waits serialize). */
+    parked = null;
+    /** Serializes suspending waits. */
+    chain = Promise.resolve();
+    constructor(deps) {
+        this.deps = deps;
+        this.now = deps.now ?? Date.now;
+        // A pending retry delay legitimately keeps the process alive — the run isn't done.
+        this.delay =
+            deps.delay ??
+                ((ms) => new Promise((resolve) => {
+                    setTimeout(resolve, ms);
+                }));
+    }
+    /** Late-bound per-run hooks (the flusher/broker/redactor exist only once a run is claimed). */
+    setHooks(hooks) {
+        this.hooks = hooks;
+    }
+    /**
+     * Run one unit of non-suspending runtime work under the gate: queue while a freeze is
+     * pending (the work never starts, so nothing can be torn by the pause), then count it
+     * in-flight so a suspending wait holds until it drains. The gate check and the count
+     * increment share one synchronous segment — a freeze requested in between cannot miss us.
+     */
+    async trackWork(fn) {
+        while (this.freezePending) {
+            await new Promise((resolve) => {
+                this.gateWaiters.push(resolve);
+            });
+        }
+        this.beginWork();
+        try {
+            return await fn();
+        }
+        finally {
+            this.endWork();
+        }
+    }
+    /** A suspending seam's own wait is NOT "work" — it decrements around its park so the gate
+     *  sees true quiescence. (The host wraps every hook in trackWork; the suspending seams
+     *  call these around their freeze wait.) */
+    beginWork() {
+        this.inFlight += 1;
+    }
+    endWork() {
+        this.inFlight -= 1;
+        if (this.inFlight === 0) {
+            const waiters = this.quiescenceWaiters;
+            this.quiescenceWaiters = [];
+            for (const w of waiters)
+                w();
+        }
+    }
+    /**
+     * The suspending wait: hold until quiescence, run the pre-freeze hook, request the
+     * freeze, and park. The next thing this promise sees is a wake (possibly epochs later,
+     * through a restored heap) or a suspend_abort. Returns the wake, or — for `sleep` only —
+     * the abort (the seam then holds in-process); other reasons retry the freeze after a
+     * backoff. Concurrent suspending waits serialize through an internal chain.
+     */
+    suspendingWait(signal, abort) {
+        const turn = this.chain;
+        let release = () => undefined;
+        this.chain = new Promise((resolve) => {
+            release = resolve;
+        });
+        return (async () => {
+            await turn;
+            try {
+                let backoff = ABORT_RETRY_INITIAL_MS;
+                for (;;) {
+                    // Withdraw window: the abort can cancel the wait any time BEFORE it sends
+                    // suspend_request (once sent, the VM freezes and the abort is moot — the process is
+                    // paused). This is register-without-release: a held gate answered during the hold.
+                    // awaitQuiescence short-circuits when already aborted, so one check after it covers
+                    // both loop entry and a mid-hold abort.
+                    await this.awaitQuiescence(abort);
+                    if (abort?.aborted === true)
+                        return { kind: "withdrawn" };
+                    try {
+                        await this.hooks.onBeforeFreeze?.();
+                    }
+                    catch (err) {
+                        // A failed pre-freeze flush must not strand the seam: treat it like an abort.
+                        log.warn("freeze_prepare_failed", {
+                            error: err instanceof Error ? err.message : String(err),
+                        });
+                        if (signal.reason === "sleep")
+                            return { kind: "aborted", reason: "prepare_failed" };
+                        await this.delay(backoff);
+                        backoff = Math.min(backoff * 2, ABORT_RETRY_MAX_MS);
+                        continue;
+                    }
+                    this.freezePending = true;
+                    const outcome = await new Promise((resolve) => {
+                        this.parked = resolve;
+                        this.deps.channel.sendSuspendRequest({
+                            reason: signal.reason,
+                            wake: this.wakeConditionOf(signal),
+                            broker_signal: signal,
+                        });
+                        // ← the VM freezes while this promise is pending; the wake resolves it with the
+                        //   heap (and this very closure) restored.
+                    });
+                    this.freezePending = false;
+                    this.releaseGate();
+                    if (outcome.kind === "wake")
+                        return outcome;
+                    // The park only ever resolves wake or aborted (never withdrawn — that returns before the
+                    // park). Narrow explicitly so `.reason` is safe and a stray outcome propagates.
+                    if (outcome.kind !== "aborted")
+                        return outcome;
+                    if (signal.reason === "sleep")
+                        return outcome;
+                    log.warn("suspend_aborted_retrying", {
+                        reason: outcome.reason,
+                        seamReason: signal.reason,
+                        backoffMs: backoff,
+                    });
+                    await this.delay(backoff);
+                    backoff = Math.min(backoff * 2, ABORT_RETRY_MAX_MS);
+                }
+            }
+            finally {
+                release();
+            }
+        })();
+    }
+    /** Relay handler: a wake injection landed. Validates, runs the after-wake hook (token
+     *  swap + meter rebase), confirms to init, and resolves the parked seam. A wake with no
+     *  parked seam is a duplicate delivery — re-confirm (idempotent), never crash. */
+    onWake(payload) {
+        const parsed = wakePayloadSchema.safeParse(payload);
+        if (!parsed.success) {
+            // Unanswerable garbage: init will retry, time out, and the platform's crash path owns
+            // recovery. Log loudly — this is a control-plane/init bug, not author code.
+            log.error("wake_payload_invalid", { issues: parsed.error.message });
+            return;
+        }
+        if (this.parked === null) {
+            log.warn("duplicate_wake_ignored", {});
+            this.deps.channel.sendWakeAccepted();
+            return;
+        }
+        const resolve = this.parked;
+        this.parked = null;
+        void (async () => {
+            try {
+                await this.hooks.onAfterWake?.(parsed.data);
+            }
+            catch (err) {
+                // Token swap / meter rebase failing is survivable only loudly — the run continues
+                // on the old token and fails fast if it truly expired.
+                log.error("after_wake_hook_failed", {
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            }
+            this.deps.channel.sendWakeAccepted();
+            resolve({ kind: "wake", wake: parsed.data.wake });
+        })();
+    }
+    /** Relay handler: the snapshot attempt failed; the parked seam falls back to holding. */
+    onSuspendAbort(payload) {
+        const parsed = suspendAbortSchema.safeParse(payload);
+        const reason = parsed.success ? (parsed.data.reason ?? "unknown") : "unknown";
+        if (this.parked === null) {
+            log.warn("suspend_abort_without_parked_seam", { reason });
+            return;
+        }
+        const resolve = this.parked;
+        this.parked = null;
+        resolve({ kind: "aborted", reason });
+    }
+    awaitQuiescence(abort) {
+        if (this.inFlight === 0 || abort?.aborted === true)
+            return Promise.resolve();
+        return new Promise((resolve) => {
+            // Resolve on quiescence OR abort (a held wait wakes immediately to withdraw). Resolving
+            // twice is harmless; endWork may still call the queued waiter later.
+            this.quiescenceWaiters.push(resolve);
+            abort?.addEventListener("abort", () => resolve(), { once: true });
+        });
+    }
+    releaseGate() {
+        const waiters = this.gateWaiters;
+        this.gateWaiters = [];
+        for (const w of waiters)
+            w();
+    }
+    /** The host-readable wake summary on the wire (logs/metrics/placement) — the opaque
+     *  broker_signal beside it carries the full condition. */
+    wakeConditionOf(signal) {
+        switch (signal.reason) {
+            case "sleep":
+                return { kind: "sleep", wake_at_ms: this.now() + (signal.durationMs ?? 0) };
+            case "human_input":
+                return {
+                    kind: "human_input",
+                    ...(signal.humanInput !== undefined ? { request_keys: [signal.humanInput.key] } : {}),
+                };
+            case "workflow_call":
+                return {
+                    kind: "workflow_call",
+                    ...(signal.childRunId !== undefined ? { child_run_id: signal.childRunId } : {}),
+                };
+        }
+    }
+}

package/dist/runtime/identity_relay.d.ts

@@ -3,6 +3,11 @@ import { z } from "zod";
 /** Env var naming the inherited relay fd. Set by the guest init; absent everywhere else
  *  (Fargate, self-hosted daemon), where the worker env-boots as always. */
 export declare const RELAY_FD_ENV = "BOARDWALK_IDENTITY_RELAY_FD";
+/** Max bytes of one relay line — the wire protocol's 32 MiB frame cap, mirrored in-guest.
+ *  An oversized line costs the connection (LF framing cannot resynchronize past it), which
+ *  for this relay means a hard bootstrap failure. Measured in UTF-16 code units, which for
+ *  this ASCII-JSON wire is the byte count; the cap is a guard, not exact accounting. */
+export declare const MAX_RELAY_LINE_BYTES: number;
 /** The identity payload — the env contract's fields, as JSON instead of env vars. */
 export declare const relayIdentitySchema: z.ZodObject<{
     run_id: z.ZodString;
@@ -14,6 +19,19 @@ export declare const relayIdentitySchema: z.ZodObject<{
     env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
 }, z.core.$strip>;
 export type RelayIdentity = z.infer<typeof relayIdentitySchema>;
+/** The init→worker halves of the post-identity relay: `wake` resolves a frozen suspending
+ *  seam (payload: the wake-inject body, verbatim), `suspend_abort` tells a parked seam the
+ *  snapshot attempt failed and it should fall back to holding. */
+export interface RelayChannelHandlers {
+    onWake(payload: unknown): void;
+    onSuspendAbort(payload: unknown): void;
+}
+/** The worker→init halves: ask to be frozen (payload: the suspend-request body — reason,
+ *  wake summary, opaque broker signal), and confirm a wake landed (init then acks its host). */
+export interface RelayChannel {
+    sendSuspendRequest(payload: unknown): void;
+    sendWakeAccepted(): void;
+}
 /**
  * Read the relay fd from `env`, deleting the key (bootstrap-only plumbing; run code has no
  * business seeing it). Returns null when unset — the normal env-boot path.
@@ -24,15 +42,30 @@ export declare function relayFdFromEnv(env: NodeJS.ProcessEnv): number | null;
  * the platform keys LAST, so nothing user-supplied can shadow a platform value.
  */
 export declare function applyIdentityToEnv(identity: RelayIdentity, env: NodeJS.ProcessEnv): void;
+/** The worker_ready diagnostics — supplied by the worker (init cannot know these),
+ *  forwarded verbatim by the guest init. Best-effort, never load-bearing. */
+export interface WorkerDiagnostics {
+    worker_version?: string;
+    node_version: string;
+    sdk_version?: string;
+}
+/** Collect the worker_ready diagnostics. Version lookups are best-effort: the runner's own
+ *  package.json sits two levels above this module in both the src and published dist
+ *  layouts; the SDK's is reachable only if its exports expose ./package.json. */
+export declare function workerDiagnostics(): WorkerDiagnostics;
 /** One end of the init↔worker relay. Wraps any Duplex so tests run over in-memory streams. */
 export declare class IdentityRelay {
     private readonly stream;
     private buffer;
     private closed;
+    private failure;
     private wake;
+    private readonly onData;
     constructor(stream: Duplex);
-    /** Announce the pre-identity park. Init forwards this as the base-snapshot gate. */
-    announceReady(): void;
+    private fail;
+    /** Announce the pre-identity park (with the diagnostics payload when provided).
+     *  Init forwards this as the base-snapshot gate. */
+    announceReady(diagnostics?: WorkerDiagnostics): void;
     /**
      * Block until init relays the run identity. THIS is the point the base snapshot freezes:
      * everything before it is generic warm-up shared by every run; everything after belongs
@@ -43,6 +76,16 @@ export declare class IdentityRelay {
     awaitIdentity(): Promise<RelayIdentity>;
     /** Confirm capture. Init acks its host only after this arrives. */
     acceptIdentity(): void;
+    /**
+     * Attach the post-identity consumer: the suspend/wake channel (the same fd, the same JSON
+     * lines). From here the relay dispatches init→worker messages to the handlers —
+     * `wake` (resolve a frozen seam) and `suspend_abort` (the seam falls back to holding) —
+     * and the returned channel sends the worker→init halves (`suspend_request`,
+     * `wake_accepted`). Unknown types are ignored (forward-compatible); malformed lines are
+     * logged and skipped, exactly as pre-identity. Call once, after {@link acceptIdentity}.
+     */
+    openChannel(handlers: RelayChannelHandlers): RelayChannel;
+    private pumpChannel;
     private writeLine;
     private readLine;
 }