@boardwalk-labs/runner 0.1.10 → 0.1.12

package/dist/runtime/program_worker.d.ts

@@ -24,7 +24,7 @@ export interface ProgramVersionReader {
         program: ProgramRef;
     } | null>;
 }
-/** Books the run's RUNTIME usage as periodic deltas (the worker's RuntimeFlusher; §10.7 + §15). The
+/** Books the run's RUNTIME usage as periodic deltas (the worker's RuntimeFlusher). The
  *  orchestrator drives the lifecycle: the timer flushes mid-run, `stop()` halts it at the body's end,
  *  and `flushFinal()` books the tail on a clean terminal (skipped on a `lease_lost` handoff — the new
  *  owner books its own runtime). Replaces the old single terminal runtime charge. */
@@ -51,7 +51,7 @@ export interface RunFinalizer {
 export interface RunSuspender {
     suspend(signal: SuspendSignal, workerId: string): Promise<void>;
 }
-/** Restores/snapshots the workflow's persistent `/workspace` (§5). Best-effort — both no-op when the
+/** Restores/snapshots the workflow's persistent `/workspace`. Best-effort — both no-op when the
  *  run isn't eligible (not opted-in / self-hosted), and neither throws. */
 export interface WorkspaceHandle {
     hydrate(): Promise<void>;
@@ -155,7 +155,7 @@ export interface ProgramWorkerDeps {
     /** Emit the program's `console.*` output as `log` run-events while the body runs (optional —
      *  absent disables capture). Wired by the entrypoint to the batched telemetry publisher. */
     onProgramLog?: (stream: LogStream, text: string) => void;
-    /** ECS task ARN (or any stable worker identity). */
+    /** Task ARN (or any stable worker identity). */
     workerId: string;
     /** Drain any buffered telemetry before the worker exits (brokered path's BrokerEventPublisher).
      *  Called by the worker entrypoint's cleanup; the orchestrator itself never invokes it. */

package/dist/runtime/program_worker.js

@@ -11,12 +11,12 @@
 //      aborted mid-flight — credit exhaustion — finalize failed with the abort reason).
 //
 // While the program runs, two per-session loops watch it (both brokered): a UsageFlusher meters token
-// deltas (§10.7) and a CreditWatcher polls the org's funding (§15). When credit hits zero the watcher
+// deltas and a CreditWatcher polls the org's funding. When credit hits zero the watcher
 // aborts the run's AbortSignal, which the WorkflowHost honors at every hook (cooperative
 // cancellation, run_abort.ts) — `signal.aborted` is authoritative for the terminal status.
 //
 // What's gone vs. the old worker: no checkpoint load/pause, no resume, no sleep/wait_for_child
-// pause outcomes (the program holds), no per-turn transcript. The Strands loop now lives one
+// pause outcomes (the program holds), no per-turn transcript. The agent loop now lives one
 // level down, behind the host's agent() leaf.
 //
 // v0 deferral (a clear seam): run-level outcome validation (needs program output capture).
@@ -130,16 +130,16 @@ export async function runProgramWorker(runId, deps) {
     if (workspace !== undefined)
         await workspace.hydrate();
     // Token metering is PER-LEAF: each agent() leaf reports its own tokens + model to the broker, which
-    // decides `billed_by_boardwalk` per model + meters to Stripe (see leaf_executor `meterUsage`). A
+    // decides `billed_by_boardwalk` per model + meters usage to the platform (see leaf_executor `meterUsage`). A
     // workflow has no run-level model, so there is no run-level token metering here.
-    // Mid-run credit watching (§15): when the org runs out of credit, abort the run cooperatively.
+    // Mid-run credit watching: when the org runs out of credit, abort the run cooperatively.
     const credit = deps.startCreditWatch?.({
         run: claimed,
         onExhausted: () => {
             controller.abort(new RunAbortedError("credit_exhausted"));
         },
     });
-    // Mid-run user-cancel watching (§6): when the user cancels, abort the run cooperatively. The host
+    // Mid-run user-cancel watching: when the user cancels, abort the run cooperatively. The host
     // honors the abort at the next hook boundary (a `sleep` hold wakes immediately); the broker then
     // upgrades the terminal write to `cancelled` because the run was flipped to `cancelling`.
     const cancel = deps.startCancelWatch?.({
@@ -148,7 +148,7 @@ export async function runProgramWorker(runId, deps) {
             controller.abort(new RunAbortedError("cancelled"));
         },
     });
-    // Lease renewal (§6): heartbeat the lease so a long run isn't reclaimed mid-flight. If the lease is
+    // Lease renewal: heartbeat the lease so a long run isn't reclaimed mid-flight. If the lease is
     // definitively lost (another worker reclaimed it), abort `lease_lost` — the run stops without
     // finalizing (the new owner owns the terminal write; see the lease_lost guard after the body).
     const lease = deps.startLeaseRenew?.({
@@ -157,7 +157,7 @@ export async function runProgramWorker(runId, deps) {
             controller.abort(new RunAbortedError("lease_lost"));
         },
     });
-    // Runtime metering (§15): flush runtime as periodic deltas from the claim, so a long/perpetual run
+    // Runtime metering: flush runtime as periodic deltas from the claim, so a long/perpetual run
     // bills as it burns (and the credit watcher sees it) instead of only at terminal. The tail is booked
     // by `flushFinal()` after the body (on every path except a lease_lost handoff).
     const runtimeFlush = deps.startRuntimeFlush?.({ run: claimed, startedAtMs: sessionStartMs });

package/dist/runtime/recording_secret_resolver.js

@@ -1,4 +1,4 @@
-// RecordingSecretResolver — the redaction feeder (the platform spec).
+// RecordingSecretResolver — the redaction feeder.
 //
 // Decorates any SecretResolver so EVERY value a run resolves — whether the workflow program asked
 // via `secrets.get(name)` or a tool asked via `ctx.secrets.resolve(ref)` — is recorded into the

package/dist/runtime/run_abort.js

@@ -1,11 +1,11 @@
 // run_abort — the provider-agnostic cooperative-cancellation substrate for a run (the Runner Credential Broker model).
 //
-// The cancellation primitive is a Web-standard `AbortSignal` — NOT a Strands/model concept. The worker
+// The cancellation primitive is a Web-standard `AbortSignal` — NOT a framework/model concept. The worker
 // owns one `AbortController` per run session; a watcher (credit, later user-cancel) calls
 // `controller.abort(new RunAbortedError(reason))`. The WorkflowHost honors that signal at every hook
 // boundary (`agent`/`sleep`/`workflows.call`/…), unwinding the program. The ONLY place that translates
-// the signal into a model-specific stop is the Strands leaf (signal → `agent.cancel()`); a future
-// non-Strands leaf honors the SAME `AbortSignal` its own way. So nothing here, in the host, or in the
+// the signal into a model-specific stop is the agent leaf (signal → the leaf's cancel path); a different
+// leaf implementation honors the SAME `AbortSignal` its own way. So nothing here, in the host, or in the
 // program-facing SDK depends on the model backend.
 //
 // `signal.aborted` is AUTHORITATIVE at the orchestrator: a program that catches RunAbortedError and

package/dist/runtime/runner_control_client.d.ts

@@ -13,6 +13,10 @@ export interface RunnerControlClientConfig {
     runId: string;
     /** Injected fetch (defaults to global fetch). */
     fetchImpl?: typeof fetch;
+    /** Per-call ceiling for short control calls (default 30s) — bounds a poll frozen mid-flight. */
+    controlTimeoutMs?: number;
+    /** Per-call ceiling for bulk artifact/workspace transfers (default 5 min). */
+    bulkTimeoutMs?: number;
 }
 /** The pinned program's download reference (the worker fetches + verifies + extracts it). */
 export interface BrokerProgram {
@@ -44,7 +48,27 @@ export declare class RunnerControlClient {
     private readonly cfg;
     private readonly base;
     private readonly fetchImpl;
+    /** The live bearer. Mutable: on the snapshot substrate a wake carries a FRESH run token (the
+     *  frozen one expired while suspended) and the worker swaps it at runtime. */
+    private runToken;
+    private readonly controlTimeoutMs;
+    private readonly bulkTimeoutMs;
     constructor(cfg: RunnerControlClientConfig);
+    /** Swap the bearer for a fresh run token (the wake path). Every subsequent call uses it. */
+    swapRunToken(token: string): void;
+    /**
+     * Every SHORT control call (claim / renew / cancel / credit / journal / …) goes through here so
+     * it carries a hard timeout. Without one, a poll frozen mid-flight on the snapshot substrate
+     * hangs FOREVER on restore (the socket is dead but never reset), and since a watcher serializes
+     * its ticks, one hung tick wedges that watcher — the dead-connections gotcha for the
+     * background pollers (lease/cancel/credit), which run on untracked timers the quiescence gate
+     * doesn't cover. Also plain robustness: no broker call should hang on a network blip. The
+     * streaming inference call is the ONE exception (long-lived NDJSON) and bypasses this.
+     */
+    private controlFetch;
+    /** Bulk transfers (artifact + workspace up/download over presigned S3) — a much larger ceiling
+     *  than a control call, but still bounded so a dead socket can't hang the run. */
+    private bulkFetch;
     /** Claim the run's lease. Returns the run on success, or null when it isn't claimable (409 —
      *  another worker has it, or it isn't pending), which the worker treats as "claim lost". */
     claim(workerId: string, leaseSeconds: number): Promise<{
@@ -84,8 +108,8 @@ export declare class RunnerControlClient {
      *  retried/duplicate flush idempotent; distinct per-flush ids sum into the run's runtime total. */
     reportUsage(runtimeSeconds: number, identifier: string): Promise<void>;
     /** Report a token-usage delta for incremental in-run metering (the usage flusher → broker). The
-     *  broker gates on the run's per-connection `billed_by_boardwalk` server-side + meters to Stripe;
-     *  `identifier` makes a retried/duplicate flush idempotent. Satisfies {@link TokenUsageReporter}. */
+     *  broker gates on the run's per-connection `billed_by_boardwalk` server-side + meters usage to the
+     *  platform; `identifier` makes a retried/duplicate flush idempotent. Satisfies {@link TokenUsageReporter}. */
     meterTokens(input: {
         inputTokens: number;
         outputTokens: number;
@@ -96,14 +120,20 @@ export declare class RunnerControlClient {
         cachedWriteTokens?: number;
     }): Promise<void>;
     /** Check whether the run's org is still funded (the CreditWatcher → broker). The broker reads the
-     *  live Stripe balance server-side; `false` means out of credit (the watcher then aborts the run). */
+     *  live billing balance server-side; `false` means out of credit (the watcher then aborts the run). */
     checkCredit(): Promise<boolean>;
     /** Check whether the run has been asked to cancel (the CancelWatcher → broker). `true` once the user
      *  cancelled the run (the broker flipped it to `cancelling`/`cancelled`); the watcher then aborts the
      *  run. Brokered because the runner holds no DB/Redis — this replaces the unreachable Redis channel. */
     checkCancelled(): Promise<boolean>;
+    /** Register-without-release: register a HELD HITL gate's request row
+     *  so it is answerable while the run keeps running — no suspend. Idempotent. Returns whether a new
+     *  gate was registered. */
+    registerInput(seq: number, gate: unknown): Promise<boolean>;
+    /** Poll the resolved answers for a held gate at `seq` (empty until a human responds). */
+    pollInputAnswers(seq: number): Promise<Record<string, unknown>>;
     /** Mint a presigned GET URL to restore this workflow's last `/workspace` snapshot (workspace
-     *  persistence, §5). `null` when the run isn't eligible (not opted-in, or self-hosted). */
+     *  persistence). `null` when the run isn't eligible (not opted-in, or self-hosted). */
     workspaceHydrateUrl(): Promise<string | null>;
     /** Mint a presigned PUT URL to snapshot this workflow's `/workspace` (the worker uploads the tarball
      *  straight to S3). `null` when the run isn't eligible. `sizeBytes` is the archive's on-disk size

package/dist/runtime/runner_control_client.js

@@ -16,15 +16,44 @@ export class RunnerControlClient {
     cfg;
     base;
     fetchImpl;
+    /** The live bearer. Mutable: on the snapshot substrate a wake carries a FRESH run token (the
+     *  frozen one expired while suspended) and the worker swaps it at runtime. */
+    runToken;
+    controlTimeoutMs;
+    bulkTimeoutMs;
     constructor(cfg) {
         this.cfg = cfg;
         this.base = cfg.baseUrl.replace(/\/+$/, "");
         this.fetchImpl = cfg.fetchImpl ?? fetch;
+        this.runToken = cfg.runToken;
+        this.controlTimeoutMs = cfg.controlTimeoutMs ?? 30_000;
+        this.bulkTimeoutMs = cfg.bulkTimeoutMs ?? 300_000;
+    }
+    /** Swap the bearer for a fresh run token (the wake path). Every subsequent call uses it. */
+    swapRunToken(token) {
+        this.runToken = token;
+    }
+    /**
+     * Every SHORT control call (claim / renew / cancel / credit / journal / …) goes through here so
+     * it carries a hard timeout. Without one, a poll frozen mid-flight on the snapshot substrate
+     * hangs FOREVER on restore (the socket is dead but never reset), and since a watcher serializes
+     * its ticks, one hung tick wedges that watcher — the dead-connections gotcha for the
+     * background pollers (lease/cancel/credit), which run on untracked timers the quiescence gate
+     * doesn't cover. Also plain robustness: no broker call should hang on a network blip. The
+     * streaming inference call is the ONE exception (long-lived NDJSON) and bypasses this.
+     */
+    controlFetch(url, init) {
+        return this.fetchImpl(url, { ...init, signal: AbortSignal.timeout(this.controlTimeoutMs) });
+    }
+    /** Bulk transfers (artifact + workspace up/download over presigned S3) — a much larger ceiling
+     *  than a control call, but still bounded so a dead socket can't hang the run. */
+    bulkFetch(url, init) {
+        return this.fetchImpl(url, { ...init, signal: AbortSignal.timeout(this.bulkTimeoutMs) });
     }
     /** Claim the run's lease. Returns the run on success, or null when it isn't claimable (409 —
      *  another worker has it, or it isn't pending), which the worker treats as "claim lost". */
     async claim(workerId, leaseSeconds) {
-        const res = await this.fetchImpl(this.url("claim"), {
+        const res = await this.controlFetch(this.url("claim"), {
             method: "POST",
             headers: this.headers(true),
             body: JSON.stringify({ workerId, leaseSeconds }),
@@ -46,7 +75,7 @@ export class RunnerControlClient {
      *  `leaseUntil`, or null when the lease was lost (409 — another worker reclaimed the run), which
      *  the worker treats as "stop". */
     async renewLease(workerId, leaseSeconds) {
-        const res = await this.fetchImpl(this.url("renew"), {
+        const res = await this.controlFetch(this.url("renew"), {
             method: "POST",
             headers: this.headers(true),
             body: JSON.stringify({ workerId, leaseSeconds }),
@@ -62,7 +91,7 @@ export class RunnerControlClient {
      *  whose lease expired and whose run was reclaimed + re-dispatched to a new owner), so a
      *  hung/partitioned worker that later recovers can't clobber the live run or revive a terminal one. */
     async finalize(status, output, workerId) {
-        const res = await this.fetchImpl(this.url("finalize"), {
+        const res = await this.controlFetch(this.url("finalize"), {
             method: "POST",
             headers: this.headers(true),
             body: JSON.stringify({ status, output, workerId }),
@@ -73,7 +102,7 @@ export class RunnerControlClient {
     /** Look up a durable-seam journal entry by its seq (the durable-suspension design), or null on a replay miss
      *  (404). The broker joins a parked agent leaf's answers into the result server-side. */
     async journalGet(seq) {
-        const res = await this.fetchImpl(this.url(`journal/${encodeURIComponent(String(seq))}`), {
+        const res = await this.controlFetch(this.url(`journal/${encodeURIComponent(String(seq))}`), {
             method: "GET",
             headers: this.headers(false),
         });
@@ -86,7 +115,7 @@ export class RunnerControlClient {
     /** Record a RESOLVED seam result (idempotent on the run + seq server-side; a resolved entry is
      *  immutable). The broker writes the memoized value the next replay returns. */
     async journalPut(entry) {
-        const res = await this.fetchImpl(this.url("journal"), {
+        const res = await this.controlFetch(this.url("journal"), {
             method: "POST",
             headers: this.headers(true),
             body: JSON.stringify(entry),
@@ -98,7 +127,7 @@ export class RunnerControlClient {
      *  entry + a human-input request row for HITL, or the wake time for a long sleep), flips the run to
      *  its suspended status, and releases the lease — transactionally. No finalize; a wake re-dispatches. */
     async suspend(signal, workerId) {
-        const res = await this.fetchImpl(this.url("suspend"), {
+        const res = await this.controlFetch(this.url("suspend"), {
             method: "POST",
             headers: this.headers(true),
             body: JSON.stringify({ ...signal, workerId }),
@@ -115,7 +144,7 @@ export class RunnerControlClient {
     }
     /** Fetch the run's pinned manifest + program source, or null when the version is missing (404). */
     async getVersion() {
-        const res = await this.fetchImpl(this.url("version"), {
+        const res = await this.controlFetch(this.url("version"), {
             method: "GET",
             headers: this.headers(false),
         });
@@ -128,7 +157,7 @@ export class RunnerControlClient {
     /** Book a runtime-seconds DELTA (the worker's RuntimeFlusher → broker). `identifier` makes a
      *  retried/duplicate flush idempotent; distinct per-flush ids sum into the run's runtime total. */
     async reportUsage(runtimeSeconds, identifier) {
-        const res = await this.fetchImpl(this.url("usage"), {
+        const res = await this.controlFetch(this.url("usage"), {
             method: "POST",
             headers: this.headers(true),
             body: JSON.stringify({ runtimeSeconds, identifier }),
@@ -137,10 +166,10 @@ export class RunnerControlClient {
             throw await brokerError(res, "usage");
     }
     /** Report a token-usage delta for incremental in-run metering (the usage flusher → broker). The
-     *  broker gates on the run's per-connection `billed_by_boardwalk` server-side + meters to Stripe;
-     *  `identifier` makes a retried/duplicate flush idempotent. Satisfies {@link TokenUsageReporter}. */
+     *  broker gates on the run's per-connection `billed_by_boardwalk` server-side + meters usage to the
+     *  platform; `identifier` makes a retried/duplicate flush idempotent. Satisfies {@link TokenUsageReporter}. */
     async meterTokens(input) {
-        const res = await this.fetchImpl(this.url("usage/tokens"), {
+        const res = await this.controlFetch(this.url("usage/tokens"), {
             method: "POST",
             headers: this.headers(true),
             body: JSON.stringify(input),
@@ -149,9 +178,9 @@ export class RunnerControlClient {
             throw await brokerError(res, "usage/tokens");
     }
     /** Check whether the run's org is still funded (the CreditWatcher → broker). The broker reads the
-     *  live Stripe balance server-side; `false` means out of credit (the watcher then aborts the run). */
+     *  live billing balance server-side; `false` means out of credit (the watcher then aborts the run). */
     async checkCredit() {
-        const res = await this.fetchImpl(this.url("credit"), {
+        const res = await this.controlFetch(this.url("credit"), {
             method: "GET",
             headers: this.headers(false),
         });
@@ -163,7 +192,7 @@ export class RunnerControlClient {
      *  cancelled the run (the broker flipped it to `cancelling`/`cancelled`); the watcher then aborts the
      *  run. Brokered because the runner holds no DB/Redis — this replaces the unreachable Redis channel. */
     async checkCancelled() {
-        const res = await this.fetchImpl(this.url("cancel"), {
+        const res = await this.controlFetch(this.url("cancel"), {
             method: "GET",
             headers: this.headers(false),
         });
@@ -171,10 +200,33 @@ export class RunnerControlClient {
             throw await brokerError(res, "cancel");
         return (await res.json()).cancelRequested;
     }
+    /** Register-without-release: register a HELD HITL gate's request row
+     *  so it is answerable while the run keeps running — no suspend. Idempotent. Returns whether a new
+     *  gate was registered. */
+    async registerInput(seq, gate) {
+        const res = await this.controlFetch(this.url("inputs"), {
+            method: "POST",
+            headers: this.headers(true),
+            body: JSON.stringify({ seq, humanInput: gate }),
+        });
+        if (res.status !== 200)
+            throw await brokerError(res, "register-input");
+        return (await res.json()).registered;
+    }
+    /** Poll the resolved answers for a held gate at `seq` (empty until a human responds). */
+    async pollInputAnswers(seq) {
+        const res = await this.controlFetch(this.url(`inputs/${encodeURIComponent(String(seq))}`), {
+            method: "GET",
+            headers: this.headers(false),
+        });
+        if (res.status !== 200)
+            throw await brokerError(res, "poll-inputs");
+        return (await res.json()).answers;
+    }
     /** Mint a presigned GET URL to restore this workflow's last `/workspace` snapshot (workspace
-     *  persistence, §5). `null` when the run isn't eligible (not opted-in, or self-hosted). */
+     *  persistence). `null` when the run isn't eligible (not opted-in, or self-hosted). */
     async workspaceHydrateUrl() {
-        const res = await this.fetchImpl(this.url("workspace/hydrate-url"), {
+        const res = await this.controlFetch(this.url("workspace/hydrate-url"), {
             method: "POST",
             headers: this.headers(false),
         });
@@ -187,7 +239,7 @@ export class RunnerControlClient {
      *  (the worker tars BEFORE requesting the URL) — the broker records it for the org storage counter +
      *  daily meter; the snapshot overwrites one per-workflow key, so it's the workflow's full footprint. */
     async workspacePersistUrl(sizeBytes) {
-        const res = await this.fetchImpl(this.url("workspace/persist-url"), {
+        const res = await this.controlFetch(this.url("workspace/persist-url"), {
             method: "POST",
             headers: this.headers(true),
             body: JSON.stringify({ sizeBytes }),
@@ -200,7 +252,7 @@ export class RunnerControlClient {
     /** Download bytes from a presigned S3 URL (workspace hydrate). `null` on 404 (no snapshot yet —
      *  e.g. the workflow's first run); throws on any other non-2xx. Goes straight to S3, not the broker. */
     async downloadBytes(url) {
-        const res = await this.fetchImpl(url, { method: "GET" });
+        const res = await this.bulkFetch(url, { method: "GET" });
         if (res.status === 404)
             return null;
         if (!res.ok)
@@ -211,7 +263,7 @@ export class RunnerControlClient {
      *  third-party-verifiable token (gated server-side on `permissions.id_token: "write"`) — used to
      *  federate into the org's OWN cloud (AWS/GCP). DIFFERENT from this client's run token. */
     async requestOidcToken(audience) {
-        const res = await this.fetchImpl(this.url("oidc/token"), {
+        const res = await this.controlFetch(this.url("oidc/token"), {
             method: "POST",
             headers: this.headers(true),
             body: JSON.stringify({ audience }),
@@ -223,7 +275,7 @@ export class RunnerControlClient {
     /** Publish a batch of live agent-event frames (the SSE live-tail source) — the broker publishes
      *  them to the run's Redis channel server-side, so the runner holds no Redis credential. */
     async publishTelemetry(frames) {
-        const res = await this.fetchImpl(this.url("telemetry"), {
+        const res = await this.controlFetch(this.url("telemetry"), {
             method: "POST",
             headers: this.headers(true),
             body: JSON.stringify({ frames }),
@@ -234,7 +286,7 @@ export class RunnerControlClient {
     /** Store a run artifact through the broker (which holds the S3 credential + neutralizes the served
      *  content type server-side). Returns the catalog id + a signed download URL. */
     async writeArtifact(input) {
-        const res = await this.fetchImpl(this.url("artifacts"), {
+        const res = await this.controlFetch(this.url("artifacts"), {
             method: "POST",
             headers: this.headers(true),
             body: JSON.stringify(input),
@@ -247,7 +299,7 @@ export class RunnerControlClient {
      *  broker derives the S3 key + neutralizes/pins the served content type; it returns the upload URL +
      *  required headers + the `s3Key` to echo back at commit. No catalog row exists yet. */
     async presignArtifact(input) {
-        const res = await this.fetchImpl(this.url("artifacts/presign"), {
+        const res = await this.controlFetch(this.url("artifacts/presign"), {
             method: "POST",
             headers: this.headers(true),
             body: JSON.stringify(input),
@@ -260,7 +312,7 @@ export class RunnerControlClient {
      *  presign response and MUST be sent verbatim — the content type is pinned into the signature, so
      *  S3 rejects a mismatch. This call goes straight to S3, not the broker. */
     async uploadBytes(url, headers, body) {
-        const res = await this.fetchImpl(url, { method: "PUT", headers, body });
+        const res = await this.bulkFetch(url, { method: "PUT", headers, body });
         if (!res.ok)
             throw await brokerError(res, "artifacts-upload");
     }
@@ -269,7 +321,7 @@ export class RunnerControlClient {
      *  broker re-validates the run prefix + re-neutralizes the content type, then returns the catalog id
      *  + a signed download URL. */
     async commitArtifact(input) {
-        const res = await this.fetchImpl(this.url("artifacts/commit"), {
+        const res = await this.controlFetch(this.url("artifacts/commit"), {
             method: "POST",
             headers: this.headers(true),
             body: JSON.stringify(input),
@@ -280,7 +332,7 @@ export class RunnerControlClient {
     }
     /** List the artifacts this run has produced. */
     async listArtifacts() {
-        const res = await this.fetchImpl(this.url("artifacts"), {
+        const res = await this.controlFetch(this.url("artifacts"), {
             method: "GET",
             headers: this.headers(false),
         });
@@ -290,7 +342,7 @@ export class RunnerControlClient {
     }
     /** Mint a fresh signed download URL for one of this run's artifacts. */
     async signArtifactUrl(artifactId, ttlSeconds) {
-        const res = await this.fetchImpl(this.url(`artifacts/${encodeURIComponent(artifactId)}/signed-url`), {
+        const res = await this.controlFetch(this.url(`artifacts/${encodeURIComponent(artifactId)}/signed-url`), {
             method: "POST",
             headers: this.headers(true),
             body: JSON.stringify({ ttlSeconds }),
@@ -302,7 +354,7 @@ export class RunnerControlClient {
     /** Resolve an org secret the run's manifest allows (the program's `secrets.get`). The broker
      *  enforces the allowlist + returns the value; a forbidden/missing secret surfaces as a throw. */
     async resolveSecret(name) {
-        const res = await this.fetchImpl(this.url("secrets/resolve"), {
+        const res = await this.controlFetch(this.url("secrets/resolve"), {
             method: "POST",
             headers: this.headers(true),
             body: JSON.stringify({ name }),
@@ -317,7 +369,7 @@ export class RunnerControlClient {
      *  A 403 (no active connection / non-allowlisted host) degrades to `{ accessToken: null, hint }` so
      *  the engine surfaces a clean failure instead of a thrown 500 mid-run; the token is never logged. */
     async mcpToken(serverUrl, invalidateToken) {
-        const res = await this.fetchImpl(this.url("mcp/token"), {
+        const res = await this.controlFetch(this.url("mcp/token"), {
             method: "POST",
             headers: this.headers(true),
             body: JSON.stringify({
@@ -336,7 +388,7 @@ export class RunnerControlClient {
     /** Proxy a web_search through the broker (which holds the Tavily key) — the runner sends the
      *  query, the broker calls Tavily and returns the results. */
     async webSearch(input) {
-        const res = await this.fetchImpl(this.url("tools/web_search"), {
+        const res = await this.controlFetch(this.url("tools/web_search"), {
             method: "POST",
             headers: this.headers(true),
             body: JSON.stringify(input),
@@ -347,7 +399,7 @@ export class RunnerControlClient {
     }
     /** Create (or idempotently re-attach to) a child run for `workflows.call`. */
     async startChild(slug, input) {
-        const res = await this.fetchImpl(this.url("children"), {
+        const res = await this.controlFetch(this.url("children"), {
             method: "POST",
             headers: this.headers(true),
             body: JSON.stringify({ slug, input }),
@@ -359,7 +411,7 @@ export class RunnerControlClient {
     }
     /** Provision a durable schedule for `workflows.schedule`; returns the new schedule's id. */
     async scheduleWorkflow(slug, input, spec) {
-        const res = await this.fetchImpl(this.url("schedules"), {
+        const res = await this.controlFetch(this.url("schedules"), {
             method: "POST",
             headers: this.headers(true),
             body: JSON.stringify({ slug, input, ...spec }),
@@ -370,7 +422,7 @@ export class RunnerControlClient {
     }
     /** Poll a child run's status/output, or null when it isn't this run's child (404). */
     async getChild(childRunId) {
-        const res = await this.fetchImpl(this.url(`children/${encodeURIComponent(childRunId)}`), {
+        const res = await this.controlFetch(this.url(`children/${encodeURIComponent(childRunId)}`), {
             method: "GET",
             headers: this.headers(false),
         });
@@ -409,7 +461,7 @@ export class RunnerControlClient {
     }
     headers(json) {
         const h = {
-            authorization: `Bearer ${this.cfg.runToken}`,
+            authorization: `Bearer ${this.runToken}`,
             accept: "application/json",
         };
         if (json)

package/dist/runtime/runtime_flusher.d.ts

@@ -26,7 +26,16 @@ export declare class RuntimeFlusher {
     private flushedSeconds;
     /** Per-flush sequence — advances only on a successful flush, so a retry reuses the same id. */
     private seq;
+    /** Wall-clock ms excluded from billing — frozen (suspended) time on the snapshot substrate. */
+    private excludedMs;
     constructor(deps: RuntimeFlusherDeps);
+    /** Book everything unbilled right now (the pre-freeze flush: suspended time must never appear as
+     *  billed runtime, so the tail is booked BEFORE the snapshot — the suspension billing rule). */
+    flushNow(): Promise<void>;
+    /** Exclude `ms` of wall-clock from billing — the frozen window on a wake (computed from the wake's
+     *  authoritative wall clock, since the guest's own clock was stopped). Never lets elapsed go
+     *  negative. */
+    excludeIdle(ms: number): void;
     /** Begin periodic delta flushing. */
     start(): void;
     /** Stop the periodic timer and drain any in-flight flush. Does NOT book the final tail — call

package/dist/runtime/runtime_flusher.js

@@ -1,10 +1,10 @@
 // RuntimeFlusher — meters a run's held-task runtime as periodic DELTAS, instead of one charge at
-// terminal (the platform spec). The heartbeat counterpart to the credit / cancel
+// terminal. The heartbeat counterpart to the credit / cancel
 // / lease watchers.
 //
 // Why: runtime used to be booked once, at terminal (`now - sessionStart`). That left two holes — a run
 // that never terminates (a perpetual loop) NEVER billed its runtime (and the credit watcher, reading
-// Stripe, never saw the burn so it couldn't stop it); and a session that crashed before finalizing had
+// the billing balance, never saw the burn so it couldn't stop it); and a session that crashed before finalizing had
 // its whole runtime lost. Metering on a timer closes both: runtime is billed as it accrues, the credit
 // watcher sees it, and a crashed session keeps the deltas it already flushed (the fresh session bills
 // its own — distinct ids sum, so the restart isn't double-charged or under-charged for the overlap-free
@@ -30,9 +30,23 @@ export class RuntimeFlusher {
     flushedSeconds = 0;
     /** Per-flush sequence — advances only on a successful flush, so a retry reuses the same id. */
     seq = 0;
+    /** Wall-clock ms excluded from billing — frozen (suspended) time on the snapshot substrate. */
+    excludedMs = 0;
     constructor(deps) {
         this.deps = deps;
     }
+    /** Book everything unbilled right now (the pre-freeze flush: suspended time must never appear as
+     *  billed runtime, so the tail is booked BEFORE the snapshot — the suspension billing rule). */
+    async flushNow() {
+        await this.flush(false);
+    }
+    /** Exclude `ms` of wall-clock from billing — the frozen window on a wake (computed from the wake's
+     *  authoritative wall clock, since the guest's own clock was stopped). Never lets elapsed go
+     *  negative. */
+    excludeIdle(ms) {
+        if (ms > 0)
+            this.excludedMs += ms;
+    }
     /** Begin periodic delta flushing. */
     start() {
         if (this.timer !== null)
@@ -67,7 +81,7 @@ export class RuntimeFlusher {
         // vCPU-seconds = wall-clock seconds × vCPUs (billed per vCPU-second). Rounding the cumulative
         // product (not per-delta) keeps the booked total aligned with wall-clock×vcpus over many flushes.
         const vcpus = this.deps.vcpus ?? 1;
-        const total = Math.max(0, Math.round(((this.deps.now() - this.deps.startedAtMs) / 1000) * vcpus));
+        const total = Math.max(0, Math.round(((this.deps.now() - this.deps.startedAtMs - this.excludedMs) / 1000) * vcpus));
         const delta = total - this.flushedSeconds;
         if (delta < 1)
             return;

package/dist/runtime/support/index.js

@@ -1,11 +1,10 @@
 // SPDX-License-Identifier: Apache-2.0
-// Runtime support shims — the small slice of the platform's `@boardwalk/common` +
-// `domain/authz` the worker runtime depends on, ported verbatim where it matters
-// (AppError taxonomy) and minimally where it doesn't (the logger: structured JSON to
-// stdout, same call surface as the platform's Powertools child logger).
+// Runtime support shims — a small, self-contained slice of the error taxonomy and logging the
+// worker runtime depends on. The AppError taxonomy mirrors the platform's error codes so brokered
+// responses map cleanly; the logger emits structured JSON to stdout.
 import { randomUUID } from "node:crypto";
-// ---- errors (ported from boardwalk-backend src/common/errors.ts; keep in sync until the
-// backend consumes this package and the copy there is deleted) ----
+// ---- errors (the shared AppError taxonomy — mirrors the platform's error codes so brokered
+// responses deserialize to the same shape) ----
 export var ErrorCode;
 (function (ErrorCode) {
     ErrorCode["VALIDATION_FAILED"] = "VALIDATION_FAILED";

package/dist/runtime/tools/artifacts.js

@@ -1,4 +1,4 @@
-// artifacts — persist + reference run outputs (the platform spec). Available to any agent
+// artifacts — persist + reference run outputs. Available to any agent
 // (no sandbox required). Three operations:
 //   * write(name, content_type, body)   → store a file under the run's prefix; returns id + a signed URL.
 //   * list()                            → artifacts produced in THIS run.

package/dist/runtime/tools/types.d.ts

@@ -3,7 +3,7 @@ import type { AuthContext } from "../support/index.js";
 import type { SecretRefManifest } from "../wire/manifest.js";
 /**
  * Per-invocation context the worker threads through to a tool. Equivalent to
- * Strands' `ToolContext` but typed in Boardwalk's idiom (AuthContext + run id +
+ * a tool framework's `ToolContext` but typed in Boardwalk's idiom (AuthContext + run id +
  * secret resolver scoped to this run's permissions).
  */
 export interface ToolContext {
@@ -27,7 +27,7 @@ export interface SecretResolver {
  *   * Return a `ToolReturn` body — synchronous "normal" tools (echo, http,
  *     web_search). The body lands in the conversation as the assistant's
  *     tool-result block.
- *   * Return a `ToolControlSignal` — the legacy Strands-level sleep/workflows.call path. The
+ *   * Return a `ToolControlSignal` — the legacy tool-level sleep/workflows.call path. The
  *     current JS-body worker exposes these as program SDK hooks instead; agent() leaves strip
  *     control-flow tools before registering model-callable tools.
  */
@@ -41,8 +41,8 @@ export interface BoardwalkTool<TInput = unknown, TOutput = unknown> {
     /**
      * Zod schema for the tool's SUCCESS output (the `TOutput` shape — never the
      * control-signal branch). The adapter validates the tool's return value
-     * against this before it lands in the LLM conversation, per the code standards
-     * §2.1/§8.3 (LLM-facing output is treated like untrusted external input).
+     * against this before it lands in the LLM conversation
+     * (LLM-facing output is treated like untrusted external input).
      */
     readonly outputSchema: z.ZodType<TOutput>;
     /**
@@ -64,7 +64,7 @@ export interface BoardwalkTool<TInput = unknown, TOutput = unknown> {
     normalizeInput?(raw: unknown): unknown;
     /**
      * Invoke the tool. `input` (LLM-supplied) comes first, `ctx` (worker-supplied)
-     * second — see the `Tool` naming note in SPEC §9. Returns either the typed
+     * second — see the `Tool` naming note in SPEC.md. Returns either the typed
      * `TOutput` body or a `ToolControlSignal` (sleep / workflows.call) the worker
      * intercepts before serialization.
      */