@boardwalk-labs/runner 0.2.17 → 0.3.0

package/README.md

@@ -86,7 +86,7 @@ pnpm lint && pnpm typecheck && pnpm build
 ## The Boardwalk repos
 
 - [`boardwalk`](https://github.com/boardwalk-labs/boardwalk) — the open-source single-node engine: cron scheduling, webhooks, durable runs, run history
-- [`sdk`](https://github.com/boardwalk-labs/sdk) — `@boardwalk-labs/workflow`, the TypeScript API a workflow program imports
+- [`sdk-typescript`](https://github.com/boardwalk-labs/sdk-typescript) — `@boardwalk-labs/workflow`, the TypeScript API a workflow program imports
 - [`cli`](https://github.com/boardwalk-labs/cli) — `boardwalk`: scaffold, validate, run locally, deploy
 - [`examples`](https://github.com/boardwalk-labs/examples) — copyable workflow templates (`boardwalk init --template`)
 - [`plugins`](https://github.com/boardwalk-labs/plugins) — coding-agent skills (Claude Code, Codex, Cursor, OpenClaw, OpenCode) + a control-plane MCP server

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

@@ -1,4 +1,8 @@
+import type { UsageSnapshot } from "@boardwalk-labs/workflow/runtime";
 import type { Budget } from "../wire/manifest.js";
+/** The three capped budget dimensions. Each parks at the budget gate on breach (SUSPEND_POLICY
+ *  Decision 3); `capBreachReason()` reports the first breached one. */
+export type BudgetDimension = "usd" | "tokens" | "compute";
 /** Per-million-token rates. */
 export interface ModelRate {
     /** USD per million input tokens. */
@@ -30,8 +34,8 @@ export interface PriorUsage {
     totalUsd: number;
     /**
      * Active execution time from prior sessions (ms). Only on-CPU turn time counts toward the
-     * duration cap — sleep/wait pauses don't burn it (a run intentionally parked for a day must
-     * not blow its duration budget on resume).
+     * compute cap — sleep/wait pauses don't burn it (a run intentionally parked for a day must
+     * not blow its `max_compute_seconds` budget on resume).
      */
     activeMs: number;
 }
@@ -41,10 +45,6 @@ export interface BudgetMeterOptions {
     rate: ModelRate;
     /** This SESSION's start time (ms). Per-session active duration is measured from here. */
     startedAt: number;
-    /** The RUN's original start time (ms) — the basis for `deadline_seconds`, a WALL-CLOCK cap that
-     *  INCLUDES suspended idle (unlike max_duration_seconds, which is active compute). Omit to leave
-     *  the deadline cap unenforced (e.g. a run that hasn't started yet). */
-    deadlineStartedAt?: number;
     /** Cumulative usage from prior sessions of this run (resume). Defaults to zero. */
     priorUsage?: PriorUsage;
     /** Injected clock for tests. */
@@ -60,13 +60,16 @@ export interface BudgetSnapshot {
     elapsedMs: number;
 }
 export declare class BudgetMeter {
-    /** NOT readonly: a budget gate (docs/SUSPEND_POLICY.md Decision 3) raises `max_usd` in place when a
-     *  responder approves more spend. The meter lives in the frozen heap, so the wake mutates this
-     *  instance and the blocked model call proceeds against the new cap. */
+    /** NOT readonly: the budget gate (docs/SUSPEND_POLICY.md Decision 3) raises a breached cap in
+     *  place when a responder approves more spend — on any dimension. The meter lives in the frozen
+     *  heap, so the wake mutates this instance and the blocked call proceeds against the new cap. */
     private budget;
+    /** Wall-clock ms excluded from the compute cap — time the run spent PARKED at the budget gate
+     *  (frozen or held). Parked time burns no `max_compute_seconds` (SUSPEND_POLICY Decision 3.4);
+     *  without this exclusion a compute park would instantly re-breach on wake, forever. */
+    private excludedIdleMs;
     private readonly rate;
     private readonly startedAt;
-    private readonly deadlineStartedAt;
     private readonly prior;
     private readonly now;
     private inputTokens;
@@ -90,6 +93,11 @@ export declare class BudgetMeter {
      * loop) — and by audit/post-run cost rollups. Cap enforcement uses {@link cumulative} instead.
      */
     snapshot(): BudgetSnapshot;
+    /** Exclude `ms` of wall-clock from the compute cap — the budget gate's park window (mirrors
+     *  RuntimeFlusher.excludeIdle for billing). Called by the gate after every park, whichever
+     *  substrate: on the snapshot fleet the guest clock resyncs on wake so the measured park spans
+     *  the frozen window; on a hold substrate it spans the register-and-poll wait. */
+    excludeIdle(ms: number): void;
     /**
      * RUN-CUMULATIVE snapshot: this session's usage PLUS the prior sessions' usage seeded at
      * construction. Cap enforcement ({@link assertWithinCaps}) and checkpoint persistence use
@@ -98,6 +106,12 @@ export declare class BudgetMeter {
      * per-session token metering reports token deltas; seeding it would double-report usage.
      */
     cumulative(): BudgetSnapshot;
+    /**
+     * The first breached cap (in the tokens → usd → compute order the assert has always used) with
+     * the numbers + message the `BUDGET_EXCEEDED` error carries, or null while within every cap.
+     * The one probe both {@link assertWithinCaps} and {@link capBreachReason} read from.
+     */
+    private firstBreach;
     /**
      * Throws `AppError(BUDGET_EXCEEDED)` when any cap is breached. Call BETWEEN
      * turns (after `addUsage` reflects the latest delta) — that way the meter
@@ -105,27 +119,32 @@ export declare class BudgetMeter {
      */
     assertWithinCaps(): void;
     /**
-     * Predicate variant for callers that prefer to handle the cap-hit path
-     * inline (e.g., the sleep tool rejects a sleep that would breach the
-     * duration cap). Returns the first breach reason or null.
-     */
-    /**
-     * Raise the `max_usd` cap to `usd` — the budget gate's approval path (docs/SUSPEND_POLICY.md
+     * Raise `dimension`'s cap to `value` — the budget gate's approval path (docs/SUSPEND_POLICY.md
      * Decision 3). Only ever RAISES: a value at or below the current cap is ignored, so an approval
      * can't silently tighten a cap and re-park the run on the very next call. A no-op when the
      * workflow declared no budget (nothing to breach). Returns the cap now in force, or null when
      * there is no budget.
      */
-    raiseUsdCap(usd: number): number | null;
-    /** The `max_usd` cap in force, or null when unset. The gate prompt reports it alongside spend. */
-    usdCap(): number | null;
-    capBreachReason(): "tokens" | "usd" | "duration" | "deadline" | null;
+    raiseCap(dimension: BudgetDimension, value: number): number | null;
+    /** The cap in force for `dimension`, or null when unset. The gate prompt reports it beside spend. */
+    cap(dimension: BudgetDimension): number | null;
+    /** What `dimension` has consumed so far, on the SAME run-cumulative basis cap enforcement uses
+     *  (usd = real-cost dollars, tokens = conversation tokens, compute = active seconds). */
+    spent(dimension: BudgetDimension): number;
+    /**
+     * Predicate variant of {@link assertWithinCaps} for callers that handle the cap-hit path inline
+     * (the budget gate parks on it; the legacy no-gate path throws on it). Returns the first breach
+     * dimension or null.
+     */
+    capBreachReason(): BudgetDimension | null;
     /**
-     * The declared `max_duration_seconds` cap, or null when unset. Lets callers that
-     * reason about wall-clock ahead of time (e.g. the sleep tool rejecting a sleep that
-     * would overrun the run) read the cap without reaching into the meter's internals.
+     * Live budget state in the host protocol's `usage.get` shape: every dimension always present
+     * as `{spent, cap, remaining}`, with `cap`/`remaining` null when uncapped. RUN-CUMULATIVE (the
+     * same basis cap enforcement uses), so a program polling it sees the numbers the platform's
+     * budget pause would act on. `tokens.spent` is conversation tokens (input + output) — the same
+     * basis as the `max_tokens` cap.
      */
-    durationCapSeconds(): number | null;
+    usageSnapshot(): UsageSnapshot;
     /**
      * 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).

package/dist/runtime/agent/budget.js

@@ -1,4 +1,4 @@
-// BudgetMeter — enforces token / USD / duration caps declared in the manifest.
+// BudgetMeter — enforces token / USD / compute-time caps declared in the manifest.
 //
 // One meter per run. The agent loop calls `addUsage()` after each LLM turn and
 // `assertWithinCaps()` between turns. When a cap is exceeded the meter throws
@@ -13,6 +13,12 @@
 // 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";
+/** The manifest budget field each dimension caps. */
+const CAP_FIELD = {
+    usd: "max_usd",
+    tokens: "max_tokens",
+    compute: "max_compute_seconds",
+};
 const ZERO_PRIOR = {
     inputTokens: 0,
     outputTokens: 0,
@@ -22,13 +28,16 @@ const ZERO_PRIOR = {
     activeMs: 0,
 };
 export class BudgetMeter {
-    /** NOT readonly: a budget gate (docs/SUSPEND_POLICY.md Decision 3) raises `max_usd` in place when a
-     *  responder approves more spend. The meter lives in the frozen heap, so the wake mutates this
-     *  instance and the blocked model call proceeds against the new cap. */
+    /** NOT readonly: the budget gate (docs/SUSPEND_POLICY.md Decision 3) raises a breached cap in
+     *  place when a responder approves more spend — on any dimension. The meter lives in the frozen
+     *  heap, so the wake mutates this instance and the blocked call proceeds against the new cap. */
     budget;
+    /** Wall-clock ms excluded from the compute cap — time the run spent PARKED at the budget gate
+     *  (frozen or held). Parked time burns no `max_compute_seconds` (SUSPEND_POLICY Decision 3.4);
+     *  without this exclusion a compute park would instantly re-breach on wake, forever. */
+    excludedIdleMs = 0;
     rate;
     startedAt;
-    deadlineStartedAt;
     prior;
     now;
     inputTokens = 0;
@@ -41,7 +50,6 @@ export class BudgetMeter {
             this.budget = opts.budget;
         this.rate = opts.rate;
         this.startedAt = opts.startedAt;
-        this.deadlineStartedAt = opts.deadlineStartedAt ?? null;
         this.prior = opts.priorUsage ?? ZERO_PRIOR;
         this.now = opts.now ?? Date.now;
     }
@@ -73,9 +81,17 @@ export class BudgetMeter {
             cacheWriteTokens: this.cacheWriteTokens,
             totalTokens: this.inputTokens + this.outputTokens,
             totalUsd: this.totalUsd,
-            elapsedMs: this.now() - this.startedAt,
+            elapsedMs: Math.max(0, this.now() - this.startedAt - this.excludedIdleMs),
         };
     }
+    /** Exclude `ms` of wall-clock from the compute cap — the budget gate's park window (mirrors
+     *  RuntimeFlusher.excludeIdle for billing). Called by the gate after every park, whichever
+     *  substrate: on the snapshot fleet the guest clock resyncs on wake so the measured park spans
+     *  the frozen window; on a hold substrate it spans the register-and-poll wait. */
+    excludeIdle(ms) {
+        if (ms > 0)
+            this.excludedIdleMs += ms;
+    }
     /**
      * RUN-CUMULATIVE snapshot: this session's usage PLUS the prior sessions' usage seeded at
      * construction. Cap enforcement ({@link assertWithinCaps}) and checkpoint persistence use
@@ -96,88 +112,123 @@ export class BudgetMeter {
         };
     }
     /**
-     * Throws `AppError(BUDGET_EXCEEDED)` when any cap is breached. Call BETWEEN
-     * turns (after `addUsage` reflects the latest delta) — that way the meter
-     * tears the loop down before another LLM call is dispatched.
+     * The first breached cap (in the tokens → usd → compute order the assert has always used) with
+     * the numbers + message the `BUDGET_EXCEEDED` error carries, or null while within every cap.
+     * The one probe both {@link assertWithinCaps} and {@link capBreachReason} read from.
      */
-    assertWithinCaps() {
+    firstBreach() {
         if (this.budget === undefined)
-            return;
+            return null;
         // Cumulative across resume sessions — caps bound the whole run, not each session.
         const snap = this.cumulative();
         // `max_tokens` deliberately bounds CONVERSATION tokens (input + output) only; cache-read /
         // cache-write tokens are tracked + fully billed via costFor() and are bounded by `max_usd`,
         // not by this cap. totalTokens (snapshot/cumulative) reflects that choice.
         if (this.budget.max_tokens !== undefined && snap.totalTokens > this.budget.max_tokens) {
-            throw new AppError(ErrorCode.BUDGET_EXCEEDED, `Token cap exceeded: ${snap.totalTokens.toString()} > ${this.budget.max_tokens.toString()}`, { kind: "tokens", used: snap.totalTokens, cap: this.budget.max_tokens });
+            return {
+                kind: "tokens",
+                used: snap.totalTokens,
+                cap: this.budget.max_tokens,
+                message: `Token cap exceeded: ${snap.totalTokens.toString()} > ${this.budget.max_tokens.toString()}`,
+            };
         }
         if (this.budget.max_usd !== undefined && snap.totalUsd > this.budget.max_usd) {
-            throw new AppError(ErrorCode.BUDGET_EXCEEDED, `USD cap exceeded: $${snap.totalUsd.toFixed(4)} > $${this.budget.max_usd.toFixed(4)}`, { kind: "usd", used: snap.totalUsd, cap: this.budget.max_usd });
+            return {
+                kind: "usd",
+                used: snap.totalUsd,
+                cap: this.budget.max_usd,
+                message: `USD cap exceeded: $${snap.totalUsd.toFixed(4)} > $${this.budget.max_usd.toFixed(4)}`,
+            };
         }
-        if (this.budget.max_duration_seconds !== undefined) {
+        // max_compute_seconds bounds ACTIVE compute (turn time) — a long sleep / human-input wait
+        // doesn't burn it. There is deliberately no wall-clock deadline cap (deadline_seconds was
+        // deleted with the workflow-format redesign; nothing replaces it).
+        if (this.budget.max_compute_seconds !== undefined) {
             const elapsedSeconds = Math.floor(snap.elapsedMs / 1000);
-            if (elapsedSeconds > this.budget.max_duration_seconds) {
-                throw new AppError(ErrorCode.BUDGET_EXCEEDED, `Duration cap exceeded: ${elapsedSeconds.toString()}s > ${this.budget.max_duration_seconds.toString()}s`, { kind: "duration", used: elapsedSeconds, cap: this.budget.max_duration_seconds });
-            }
-        }
-        // deadline_seconds: WALL-CLOCK from the run's original start, INCLUDING suspended idle (a run
-        // resumed past its deadline trips on its first cap check; a long-running one trips per turn).
-        // Distinct from max_duration_seconds (active compute) — a long sleep / human-input wait does not
-        // burn that, but DOES count here.
-        if (this.budget.deadline_seconds !== undefined && this.deadlineStartedAt !== null) {
-            const wallSeconds = Math.floor((this.now() - this.deadlineStartedAt) / 1000);
-            if (wallSeconds > this.budget.deadline_seconds) {
-                throw new AppError(ErrorCode.BUDGET_EXCEEDED, `Deadline exceeded: ${wallSeconds.toString()}s > ${this.budget.deadline_seconds.toString()}s (wall-clock)`, { kind: "deadline", used: wallSeconds, cap: this.budget.deadline_seconds });
+            if (elapsedSeconds > this.budget.max_compute_seconds) {
+                return {
+                    kind: "compute",
+                    used: elapsedSeconds,
+                    cap: this.budget.max_compute_seconds,
+                    message: `Compute cap exceeded: ${elapsedSeconds.toString()}s > ${this.budget.max_compute_seconds.toString()}s`,
+                };
             }
         }
+        return null;
     }
     /**
-     * Predicate variant for callers that prefer to handle the cap-hit path
-     * inline (e.g., the sleep tool rejects a sleep that would breach the
-     * duration cap). Returns the first breach reason or null.
+     * Throws `AppError(BUDGET_EXCEEDED)` when any cap is breached. Call BETWEEN
+     * turns (after `addUsage` reflects the latest delta) — that way the meter
+     * tears the loop down before another LLM call is dispatched.
      */
+    assertWithinCaps() {
+        const breach = this.firstBreach();
+        if (breach === null)
+            return;
+        throw new AppError(ErrorCode.BUDGET_EXCEEDED, breach.message, {
+            kind: breach.kind,
+            used: breach.used,
+            cap: breach.cap,
+        });
+    }
     /**
-     * Raise the `max_usd` cap to `usd` — the budget gate's approval path (docs/SUSPEND_POLICY.md
+     * Raise `dimension`'s cap to `value` — the budget gate's approval path (docs/SUSPEND_POLICY.md
      * Decision 3). Only ever RAISES: a value at or below the current cap is ignored, so an approval
      * can't silently tighten a cap and re-park the run on the very next call. A no-op when the
      * workflow declared no budget (nothing to breach). Returns the cap now in force, or null when
      * there is no budget.
      */
-    raiseUsdCap(usd) {
+    raiseCap(dimension, value) {
         if (this.budget === undefined)
             return null;
-        const current = this.budget.max_usd;
-        if (current !== undefined && usd <= current)
+        const field = CAP_FIELD[dimension];
+        const current = this.budget[field];
+        if (current !== undefined && value <= current)
             return current;
-        this.budget = { ...this.budget, max_usd: usd };
-        return usd;
+        this.budget = { ...this.budget, [field]: value };
+        return value;
     }
-    /** The `max_usd` cap in force, or null when unset. The gate prompt reports it alongside spend. */
-    usdCap() {
-        return this.budget?.max_usd ?? null;
+    /** The cap in force for `dimension`, or null when unset. The gate prompt reports it beside spend. */
+    cap(dimension) {
+        return this.budget?.[CAP_FIELD[dimension]] ?? null;
+    }
+    /** What `dimension` has consumed so far, on the SAME run-cumulative basis cap enforcement uses
+     *  (usd = real-cost dollars, tokens = conversation tokens, compute = active seconds). */
+    spent(dimension) {
+        const snap = this.cumulative();
+        if (dimension === "usd")
+            return snap.totalUsd;
+        if (dimension === "tokens")
+            return snap.totalTokens;
+        return Math.floor(snap.elapsedMs / 1000);
     }
+    /**
+     * Predicate variant of {@link assertWithinCaps} for callers that handle the cap-hit path inline
+     * (the budget gate parks on it; the legacy no-gate path throws on it). Returns the first breach
+     * dimension or null.
+     */
     capBreachReason() {
-        try {
-            this.assertWithinCaps();
-            return null;
-        }
-        catch (err) {
-            if (err instanceof AppError &&
-                typeof err.detail === "object" &&
-                err.detail !== null &&
-                "kind" in err.detail) {
-                return err.detail.kind;
-            }
-            throw err;
-        }
+        return this.firstBreach()?.kind ?? null;
     }
     /**
-     * The declared `max_duration_seconds` cap, or null when unset. Lets callers that
-     * reason about wall-clock ahead of time (e.g. the sleep tool rejecting a sleep that
-     * would overrun the run) read the cap without reaching into the meter's internals.
+     * Live budget state in the host protocol's `usage.get` shape: every dimension always present
+     * as `{spent, cap, remaining}`, with `cap`/`remaining` null when uncapped. RUN-CUMULATIVE (the
+     * same basis cap enforcement uses), so a program polling it sees the numbers the platform's
+     * budget pause would act on. `tokens.spent` is conversation tokens (input + output) — the same
+     * basis as the `max_tokens` cap.
      */
-    durationCapSeconds() {
-        return this.budget?.max_duration_seconds ?? null;
+    usageSnapshot() {
+        const snap = this.cumulative();
+        const dimension = (spent, cap) => ({
+            spent,
+            cap: cap ?? null,
+            remaining: cap === undefined ? null : Math.max(0, cap - spent),
+        });
+        return {
+            usd: dimension(snap.totalUsd, this.budget?.max_usd),
+            tokens: dimension(snap.totalTokens, this.budget?.max_tokens),
+            compute_seconds: dimension(Math.floor(snap.elapsedMs / 1000), this.budget?.max_compute_seconds),
+        };
     }
     /**
      * USD cost for a single delta — the representative-rate ESTIMATE used only when the broker reports

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

@@ -38,7 +38,7 @@ export interface TurnEventSink {
  * Identity of one agent() leaf — stamped on its `turn_started`/`turn_ended` frames so a stream
  * consumer can tell concurrent agents apart. `agentId` is stable + run-unique (worker-assigned);
  * `agentName` is the author's `AgentOptions.name`, present only when set. Mirrors the engine's
- * `AgentIdentity` shape so the platform's wire matches `boardwalk dev` and the self-hosted server.
+ * `AgentIdentity` shape so the platform's wire matches the self-hosted server.
  */
 export interface AgentIdentity {
     agentId: string;

package/dist/runtime/broker_child_dispatcher.d.ts

@@ -1,5 +1,5 @@
 import type { CallOptions } from "@boardwalk-labs/workflow/runtime";
-import type { ChildDispatcher, ChildResult, ScheduleOptions } from "./workflow_host.js";
+import type { ChildCallOutput, ChildDispatcher, ChildResult, ScheduleOptions } from "./workflow_host.js";
 import type { RunnerControlClient } from "./runner_control_client.js";
 export interface BrokerChildDispatcherDeps {
     client: RunnerControlClient;
@@ -14,7 +14,10 @@ export declare class BrokerChildDispatcher implements ChildDispatcher {
     constructor(deps: BrokerChildDispatcherDeps);
     /** Create (or re-attach to) the child, then hold + poll to terminal and return its output. An
      *  abort (`signal`) stops the hold within one poll interval and throws RunAbortedError. */
-    call(slug: string, input: unknown, _opts: CallOptions | undefined, signal?: AbortSignal): Promise<unknown>;
+    call(slug: string, input: unknown, _opts: CallOptions | undefined, signal?: AbortSignal): Promise<ChildCallOutput>;
+    /** Poll a child's current state (the freeze-wake path uses this to fetch the callee's output
+     *  schema); null = not this run's child. */
+    poll(childRunId: string): Promise<ChildResult | null>;
     /** Start (or idempotently re-attach to) the child and resolve its CURRENT state — no hold. The
      *  durable callWorkflow seam decides whether to suspend (non-terminal) or return (terminal). */
     start(slug: string, input: unknown, _opts: CallOptions | undefined, signal?: AbortSignal): Promise<ChildResult>;

package/dist/runtime/broker_child_dispatcher.js

@@ -24,16 +24,34 @@ export class BrokerChildDispatcher {
         throwIfAborted(signal);
         const child = await this.deps.client.startChild(slug, input);
         if (TERMINAL_CHILD_STATUSES.has(child.status)) {
-            return this.childOutput(slug, child.childRunId, child.status, child.output);
+            return this.childOutput(slug, child.childRunId, child.status, child.output, child.outputSchema);
         }
         return this.pollToCompletion(slug, child.childRunId, signal);
     }
+    /** Poll a child's current state (the freeze-wake path uses this to fetch the callee's output
+     *  schema); null = not this run's child. */
+    async poll(childRunId) {
+        const child = await this.deps.client.getChild(childRunId);
+        if (child === null)
+            return null;
+        return {
+            childRunId: child.id,
+            status: child.status,
+            output: child.output,
+            outputSchema: child.outputSchema ?? null,
+        };
+    }
     /** Start (or idempotently re-attach to) the child and resolve its CURRENT state — no hold. The
      *  durable callWorkflow seam decides whether to suspend (non-terminal) or return (terminal). */
     async start(slug, input, _opts, signal) {
         throwIfAborted(signal);
         const child = await this.deps.client.startChild(slug, input);
-        return { childRunId: child.childRunId, status: child.status, output: child.output };
+        return {
+            childRunId: child.childRunId,
+            status: child.status,
+            output: child.output,
+            outputSchema: child.outputSchema ?? null,
+        };
     }
     /** Fire-and-forget: create (or re-attach to) the child and return its id without holding. */
     async run(slug, input, _opts) {
@@ -64,7 +82,7 @@ export class BrokerChildDispatcher {
                 throw new AppError(ErrorCode.INTERNAL_ERROR, `Called workflow's child run ${childRunId} vanished`);
             }
             if (TERMINAL_CHILD_STATUSES.has(child.status)) {
-                return this.childOutput(slug, child.id, child.status, child.output);
+                return this.childOutput(slug, child.id, child.status, child.output, child.outputSchema);
             }
             await this.sleep(this.pollIntervalMs);
             // Re-check after the wait so an abort during the inter-poll sleep stops within one interval.
@@ -72,10 +90,10 @@ export class BrokerChildDispatcher {
         }
     }
     /** A completed child returns its output; a failed/cancelled child rejects the parent's await. */
-    childOutput(slug, childRunId, status, output) {
+    childOutput(slug, childRunId, status, output, outputSchema) {
         if (status === "completed")
-            return output;
-        log.warn("child_workflow_nonterminal_output", { slug, childRunId, status });
+            return { output, outputSchema: outputSchema ?? null };
+        log.warn("child_workflow_did_not_complete", { slug, childRunId, status });
         throw new AppError(ErrorCode.INTERNAL_ERROR, `Called workflow "${slug}" ${status} (run ${childRunId})`, { childRunId, status });
     }
 }

package/dist/runtime/budget_gate.d.ts

@@ -1,11 +1,10 @@
-import type { BudgetMeter } from "./agent/budget.js";
+import type { BudgetDimension, BudgetMeter } from "./agent/budget.js";
 import type { HumanInputResult } from "@boardwalk-labs/workflow";
 /** The stable key a responder answers a budget gate by (`boardwalk respond <runId> budget …`). */
 export declare const BUDGET_GATE_KEY = "budget";
-/** Preset approvals, plus the two open-ended answers. Kept small: the point is a fast decision. */
-export declare const BUDGET_CHOICE_ADD_10 = "+$10";
-export declare const BUDGET_CHOICE_ADD_25 = "+$25";
-export declare const BUDGET_CHOICE_ADD_100 = "+$100";
+/** Preset approvals per dimension, plus the open-ended `other` answer. Kept small: the point is a
+ *  fast decision. These strings ARE the wire options — backend/web render them verbatim. */
+export declare const BUDGET_PRESETS: Record<BudgetDimension, readonly [string, string, string]>;
 export declare const BUDGET_CHOICE_CANCEL = "cancel";
 /** The port the gate needs from the host — narrowed so tests don't build a whole WorkflowHost. */
 export interface BudgetClearancePort {
@@ -20,32 +19,70 @@ export declare class BudgetGateCancelled extends Error {
 }
 /**
  * The gate's question. It states the two numbers that matter (spent vs. cap) so the responder can
- * decide without opening the dashboard, and names the run's own `max_usd` so it's obvious WHICH cap
- * was hit (not the org's credit balance — a different failure with a different fix).
+ * decide without opening the dashboard, and names the run's own manifest cap field so it's obvious
+ * WHICH cap was hit (not the org's credit balance — a different failure with a different fix).
  */
-export declare function budgetGatePrompt(spentUsd: number, capUsd: number): string;
+export declare function budgetGatePrompt(dimension: BudgetDimension, spent: number, cap: number): string;
 /** The gate's response form — a choice, so the common answers are one click / one word. */
-export declare function budgetGateInputSpec(): unknown;
+export declare function budgetGateInputSpec(dimension: BudgetDimension): unknown;
 /**
- * Interpret an answer as the NEW absolute `max_usd`, or null to cancel the run.
+ * Interpret an answer as the NEW absolute cap for `dimension`, or null to cancel the run.
  *
- * `+$N` is an INCREMENT on the current cap (the presets); a bare number is an ABSOLUTE new cap (the
- * "set a cap" escape hatch, via the choice's `other` entry). Anything unrecognized is treated as
- * cancel rather than guessed at — silently resuming a run on a misread answer spends real money.
+ * `+<amount>` is an INCREMENT on the current cap (the presets); a bare amount is an ABSOLUTE new
+ * cap (the "set a cap" escape hatch, via the choice's `other` entry). Anything unrecognized is
+ * treated as cancel rather than guessed at — silently resuming a run on a misread answer spends
+ * real money. See the module header for the full per-dimension grammar.
  */
-export declare function resolveBudgetAnswer(answer: string, currentCapUsd: number): number | null;
+export declare function resolveBudgetAnswer(dimension: BudgetDimension, answer: string, currentCap: number): number | null;
 /**
- * Budget clearance, awaited before every model call. Fast path: no breach ⇒ resolve immediately (the
- * overwhelming majority of calls). On a `usd` breach: park at a gate, then apply the answer to the
- * live meter and let the call proceed.
+ * Budget clearance, awaited at every park point (see the module header). Fast path: no breach ⇒
+ * resolve immediately (the overwhelming majority of calls). On a breach of ANY dimension: park at
+ * a gate, then apply the answer to the live meter and let the call proceed.
  *
- * Scope (slice 1): ONLY the `usd` cap parks. A `tokens` / `duration` / `deadline` breach still fails
- * the run through the leaf executor's existing throw — those dimensions have no "approve more" story
- * yet, and `deadline` is wall-clock, which a park cannot pause by definition.
+ * The park's own wall-clock is EXCLUDED from the compute cap (`meter.excludeIdle`): parked time is
+ * not compute (SUSPEND_POLICY Decision 3.4), and on the snapshot fleet the guest clock resyncs
+ * across the frozen window — without the exclusion a compute park would re-breach the instant it
+ * woke, forever. `usage.get()` polled DURING a park may transiently show the parked wall-clock as
+ * compute spend; the exclusion lands when the park resolves.
  */
 export declare class BudgetGate {
     private readonly meter;
     private readonly host;
-    constructor(meter: BudgetMeter, host: BudgetClearancePort);
+    private readonly now;
+    constructor(meter: BudgetMeter, host: BudgetClearancePort, now?: () => number);
     clear(): Promise<void>;
 }
+/** How often the watcher samples the meter. Coarse is fine: compute presets are minutes. */
+export declare const DEFAULT_COMPUTE_WATCH_INTERVAL_MS = 15000;
+/**
+ * Detects a `max_compute_seconds` breach BETWEEN park points. `usd`/`tokens` only move at the
+ * `streamModel` seam, but compute burns continuously — a breach can land mid-shell, mid-turn, or
+ * mid-program-compute, far from any model call.
+ *
+ * WHY THIS ONLY DETECTS AND DOES NOT PARK — true park-anywhere needs fleet-host work. The freeze
+ * machinery is quiescence-gated: `budgetClearance` may only be entered from a work-tracked seam
+ * (its `freezeWait` steps the CALLER out of the work count; from a timer context that corrupts the
+ * count and could freeze around live in-flight work, which SUSPEND_POLICY Decision 1 forbids). A
+ * timer-initiated park would need (a) a host-agent-initiated out-of-band VM pause that does not
+ * require runner quiescence, plus a wake path that re-arms the runner-side gate and applies the
+ * answer to the meter, and (b) on hold-only substrates a program-process stop (SIGSTOP) in the
+ * program runner. Until that lands, the honest contract is: the watcher logs the breach the moment
+ * it happens, and the run PARKS AT ITS NEXT SEAM (`streamModel`, `sleep`, `shell`,
+ * `workflows.call`) via the same {@link BudgetGate.clear} every park point awaits.
+ */
+export declare class ComputeBreachWatcher {
+    private readonly meter;
+    private readonly opts;
+    private timer;
+    private announced;
+    constructor(meter: BudgetMeter, opts?: {
+        runId: string;
+        intervalMs?: number;
+    });
+    /** True while a compute breach is standing (sampled; resets when an approval clears it). */
+    get breachDetected(): boolean;
+    start(): void;
+    stop(): void;
+    /** One sample tick (exposed for tests — real ticks come from the interval). */
+    sample(): void;
+}