@sweny-ai/core 0.1.157 → 0.1.158

package/dist/budget.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Spend budgets (#449): token and cost ceilings per node and per run.
+ *
+ * Pure and browser-safe. `budget: { tokens, cost_usd }` on a node caps one visit
+ * to that node (every retry attempt included); on the workflow it caps the whole
+ * run, and is the ceiling for every node. The CLI's `--max-tokens` and
+ * `--max-cost` tighten the run ceiling further (the lowest wins).
+ *
+ * Tokens are input + output tokens as the harness reports them (cache reads and
+ * writes are not counted, matching the run receipt). Cost is the harness's own
+ * reported USD, never estimated. Only agent node runs are counted: judge,
+ * routing and retry-reflection completions report no usage and are not metered.
+ *
+ * Enforcement, per unit the harness can report:
+ * - live: the harness calls `onUsage` during the node; crossing a limit aborts
+ *   the attempt's signal, which stops the agent (harness cancel).
+ * - between nodes: usage on the finished result is checked; a crossing fails the
+ *   node, and the run halts before the next node starts.
+ */
+import type { NodeUsage } from "./types.js";
+/** The `budget` field of a node or workflow. */
+export interface Budget {
+    /** Max input + output tokens. */
+    tokens?: number;
+    /** Max reported cost in USD. */
+    cost_usd?: number;
+}
+/** Spend limits in the units the executor works in. Absent = unlimited. */
+export interface SpendLimits {
+    tokens?: number;
+    costUsd?: number;
+}
+export interface Spend {
+    tokens: number;
+    costUsd: number;
+}
+export type BudgetUnit = "tokens" | "cost_usd";
+/** Recorded on the node whose spend crossed a budget (`NodeResult.budget`). */
+export interface BudgetOverrun {
+    /** Which ceiling was crossed: the node's own, or the run's. */
+    scope: "node" | "run";
+    unit: BudgetUnit;
+    limit: number;
+    /** Spend at the moment of the stop (live) or at the end of the node. */
+    spent: number;
+}
+export declare function toLimits(b: Budget | undefined): SpendLimits;
+/** The tighter of two limit sets, per unit. */
+export declare function minLimits(a: SpendLimits, b: SpendLimits): SpendLimits;
+export declare function hasLimits(l: SpendLimits): boolean;
+/** Tokens and cost a usage report carries. A field the harness did not report stays undefined. */
+export declare function spendOf(u: NodeUsage | undefined): {
+    tokens?: number;
+    costUsd?: number;
+};
+/** One line for the log, the node's `data.error` and the receipt. */
+export declare function describeOverrun(o: BudgetOverrun, nodeId?: string): string;
+/**
+ * Tracks spend for one run. `node()` opens a visit to a node; `attempt()` opens
+ * one agent run inside it. Spend is committed when an attempt finishes.
+ */
+export declare class BudgetGuard {
+    readonly runLimits: SpendLimits;
+    private spent;
+    constructor(runLimits: SpendLimits);
+    get totals(): Spend;
+    /** True when any limit exists at all, so the executor can skip the machinery. */
+    active(nodeLimits: SpendLimits): boolean;
+    /** The run ceiling is already reached: no further attempt may start. */
+    runExhausted(): BudgetOverrun | undefined;
+    node(nodeLimits: SpendLimits): NodeBudget;
+    /** @internal */
+    commit(s: Spend): void;
+}
+export declare class NodeBudget {
+    private readonly guard;
+    readonly limits: SpendLimits;
+    private spent;
+    constructor(guard: BudgetGuard, limits: SpendLimits);
+    /** A limit is already reached before the next attempt (a retry after a spend-heavy attempt, or a spent run). */
+    exhausted(): BudgetOverrun | undefined;
+    attempt(outer?: AbortSignal): BudgetAttempt;
+    /** @internal */
+    get committed(): Spend;
+    /** @internal */
+    commit(s: Spend): void;
+}
+/** One agent run. Its `signal` is the caller's signal plus a budget stop. */
+export declare class BudgetAttempt {
+    private readonly guard;
+    private readonly node;
+    private readonly outer?;
+    private readonly controller;
+    private live;
+    private liveUsage;
+    private stopped;
+    private readonly onOuterAbort;
+    constructor(guard: BudgetGuard, node: NodeBudget, outer?: AbortSignal | undefined);
+    get signal(): AbortSignal;
+    /** The breach that stopped this attempt live, if any. */
+    get breach(): BudgetOverrun | undefined;
+    /** Latest usage the harness reported during the run (cumulative for the attempt). */
+    get lastUsage(): NodeUsage | undefined;
+    /** Handed to the harness as `onUsage`. Reports are cumulative for this attempt. */
+    readonly onUsage: (u: NodeUsage) => void;
+    private check;
+    /**
+     * The attempt is over. Commit its spend (the larger of what the result
+     * reports and what was seen live) and return the breach, if any: the live
+     * stop, else a crossing visible only in the final usage.
+     */
+    finish(finalUsage: NodeUsage | undefined): BudgetOverrun | undefined;
+    /** Release the outer-signal listener when the run threw before `finish`. */
+    dispose(): void;
+}

package/dist/budget.js

@@ -0,0 +1,191 @@
+/**
+ * Spend budgets (#449): token and cost ceilings per node and per run.
+ *
+ * Pure and browser-safe. `budget: { tokens, cost_usd }` on a node caps one visit
+ * to that node (every retry attempt included); on the workflow it caps the whole
+ * run, and is the ceiling for every node. The CLI's `--max-tokens` and
+ * `--max-cost` tighten the run ceiling further (the lowest wins).
+ *
+ * Tokens are input + output tokens as the harness reports them (cache reads and
+ * writes are not counted, matching the run receipt). Cost is the harness's own
+ * reported USD, never estimated. Only agent node runs are counted: judge,
+ * routing and retry-reflection completions report no usage and are not metered.
+ *
+ * Enforcement, per unit the harness can report:
+ * - live: the harness calls `onUsage` during the node; crossing a limit aborts
+ *   the attempt's signal, which stops the agent (harness cancel).
+ * - between nodes: usage on the finished result is checked; a crossing fails the
+ *   node, and the run halts before the next node starts.
+ */
+const isNum = (v) => typeof v === "number" && Number.isFinite(v);
+export function toLimits(b) {
+    return {
+        ...(b?.tokens !== undefined ? { tokens: b.tokens } : {}),
+        ...(b?.cost_usd !== undefined ? { costUsd: b.cost_usd } : {}),
+    };
+}
+/** The tighter of two limit sets, per unit. */
+export function minLimits(a, b) {
+    const pick = (x, y) => (x === undefined ? y : y === undefined ? x : Math.min(x, y));
+    const tokens = pick(a.tokens, b.tokens);
+    const costUsd = pick(a.costUsd, b.costUsd);
+    return { ...(tokens !== undefined ? { tokens } : {}), ...(costUsd !== undefined ? { costUsd } : {}) };
+}
+export function hasLimits(l) {
+    return l.tokens !== undefined || l.costUsd !== undefined;
+}
+/** Tokens and cost a usage report carries. A field the harness did not report stays undefined. */
+export function spendOf(u) {
+    if (!u)
+        return {};
+    const tokens = isNum(u.inputTokens) || isNum(u.outputTokens) ? (u.inputTokens ?? 0) + (u.outputTokens ?? 0) : undefined;
+    return { ...(tokens !== undefined ? { tokens } : {}), ...(isNum(u.costUsd) ? { costUsd: u.costUsd } : {}) };
+}
+function over(spent, limit, strictlyOver) {
+    if (limit === undefined)
+        return false;
+    return strictlyOver ? spent > limit : spent >= limit;
+}
+function breachOf(scope, limits, spent, strictlyOver) {
+    if (over(spent.tokens, limits.tokens, strictlyOver)) {
+        return { scope, unit: "tokens", limit: limits.tokens, spent: spent.tokens };
+    }
+    if (over(spent.costUsd, limits.costUsd, strictlyOver)) {
+        return { scope, unit: "cost_usd", limit: limits.costUsd, spent: spent.costUsd };
+    }
+    return undefined;
+}
+/** One line for the log, the node's `data.error` and the receipt. */
+export function describeOverrun(o, nodeId) {
+    const fmt = (n) => o.unit === "cost_usd" ? `$${n < 0.01 ? n.toFixed(4) : n.toFixed(2)}` : String(Math.round(n));
+    const what = o.scope === "run" ? "run budget" : `node budget${nodeId ? ` for '${nodeId}'` : ""}`;
+    return `${what} exceeded: ${o.unit} ${fmt(o.spent)} of ${fmt(o.limit)}`;
+}
+/**
+ * Tracks spend for one run. `node()` opens a visit to a node; `attempt()` opens
+ * one agent run inside it. Spend is committed when an attempt finishes.
+ */
+export class BudgetGuard {
+    runLimits;
+    spent = { tokens: 0, costUsd: 0 };
+    constructor(runLimits) {
+        this.runLimits = runLimits;
+    }
+    get totals() {
+        return { ...this.spent };
+    }
+    /** True when any limit exists at all, so the executor can skip the machinery. */
+    active(nodeLimits) {
+        return hasLimits(this.runLimits) || hasLimits(nodeLimits);
+    }
+    /** The run ceiling is already reached: no further attempt may start. */
+    runExhausted() {
+        return breachOf("run", this.runLimits, this.spent, false);
+    }
+    node(nodeLimits) {
+        return new NodeBudget(this, nodeLimits);
+    }
+    /** @internal */
+    commit(s) {
+        this.spent = { tokens: this.spent.tokens + s.tokens, costUsd: this.spent.costUsd + s.costUsd };
+    }
+}
+export class NodeBudget {
+    guard;
+    limits;
+    spent = { tokens: 0, costUsd: 0 };
+    constructor(guard, limits) {
+        this.guard = guard;
+        this.limits = limits;
+    }
+    /** A limit is already reached before the next attempt (a retry after a spend-heavy attempt, or a spent run). */
+    exhausted() {
+        return breachOf("node", this.limits, this.spent, false) ?? this.guard.runExhausted();
+    }
+    attempt(outer) {
+        return new BudgetAttempt(this.guard, this, outer);
+    }
+    /** @internal */
+    get committed() {
+        return this.spent;
+    }
+    /** @internal */
+    commit(s) {
+        this.spent = { tokens: this.spent.tokens + s.tokens, costUsd: this.spent.costUsd + s.costUsd };
+        this.guard.commit(s);
+    }
+}
+/** One agent run. Its `signal` is the caller's signal plus a budget stop. */
+export class BudgetAttempt {
+    guard;
+    node;
+    outer;
+    controller = new AbortController();
+    live = { tokens: 0, costUsd: 0 };
+    liveUsage;
+    stopped;
+    onOuterAbort = () => this.controller.abort();
+    constructor(guard, node, outer) {
+        this.guard = guard;
+        this.node = node;
+        this.outer = outer;
+        if (outer?.aborted)
+            this.controller.abort();
+        else
+            outer?.addEventListener("abort", this.onOuterAbort, { once: true });
+    }
+    get signal() {
+        return this.controller.signal;
+    }
+    /** The breach that stopped this attempt live, if any. */
+    get breach() {
+        return this.stopped;
+    }
+    /** Latest usage the harness reported during the run (cumulative for the attempt). */
+    get lastUsage() {
+        return this.liveUsage;
+    }
+    /** Handed to the harness as `onUsage`. Reports are cumulative for this attempt. */
+    onUsage = (u) => {
+        if (this.stopped)
+            return;
+        this.liveUsage = { ...this.liveUsage, ...u };
+        const s = spendOf(u);
+        // Reports are cumulative; never let a partial report move spend backwards.
+        this.live = {
+            tokens: Math.max(this.live.tokens, s.tokens ?? 0),
+            costUsd: Math.max(this.live.costUsd, s.costUsd ?? 0),
+        };
+        const b = this.check(this.live);
+        if (b) {
+            this.stopped = b;
+            this.controller.abort();
+        }
+    };
+    check(attempt) {
+        const n = this.node.committed;
+        const r = this.guard.totals;
+        return (breachOf("node", this.node.limits, { tokens: n.tokens + attempt.tokens, costUsd: n.costUsd + attempt.costUsd }, true) ??
+            breachOf("run", this.guard.runLimits, { tokens: r.tokens + attempt.tokens, costUsd: r.costUsd + attempt.costUsd }, true));
+    }
+    /**
+     * The attempt is over. Commit its spend (the larger of what the result
+     * reports and what was seen live) and return the breach, if any: the live
+     * stop, else a crossing visible only in the final usage.
+     */
+    finish(finalUsage) {
+        this.outer?.removeEventListener("abort", this.onOuterAbort);
+        const f = spendOf(finalUsage);
+        const spent = {
+            tokens: Math.max(this.live.tokens, f.tokens ?? 0),
+            costUsd: Math.max(this.live.costUsd, f.costUsd ?? 0),
+        };
+        const b = this.stopped ?? this.check(spent);
+        this.node.commit(spent);
+        return b;
+    }
+    /** Release the outer-signal listener when the run threw before `finish`. */
+    dispose() {
+        this.outer?.removeEventListener("abort", this.onOuterAbort);
+    }
+}

package/dist/cli/main.d.ts

@@ -9,6 +9,8 @@ export declare function workflowRunAction(file: string | undefined, options: Rec
     verbose?: boolean;
     timeout?: string;
     maxSteps?: string;
+    maxTokens?: string;
+    maxCost?: string;
     yes?: boolean;
 }): Promise<void>;
 export declare function workflowExportAction(name: string): void;

package/dist/cli/main.js

@@ -20,7 +20,7 @@ import { buildAutoMcpServers, buildSkillMcpServers, buildProviderContext } from
 import { loadAdditionalContext } from "../templates.js";
 import { loadAndValidateWorkflow } from "../loader.js";
 import { validateRuntimeInput } from "../inputs.js";
-import { mergeDryRunIntoInput, parseInputFlag, parseRunBudgetFlags } from "./workflow-input.js";
+import { mergeDryRunIntoInput, parseInputFlag, parseRunBudgetFlags, parseSpendFlags } from "./workflow-input.js";
 import { stringify as stringifyYaml } from "yaml";
 import { buildWorkflow, refineWorkflow } from "../workflow-builder.js";
 import { toMermaidBlock } from "../mermaid.js";
@@ -730,8 +730,10 @@ export async function workflowRunAction(file, options) {
     // Reject junk --timeout/--max-steps up front (both paths) instead of
     // silently falling back to a default.
     let budget;
+    let spendBudget;
     try {
         budget = parseRunBudgetFlags(options.timeout, options.maxSteps, DEFAULT_WORKFLOW_TIMEOUT_MS);
+        spendBudget = parseSpendFlags(options.maxTokens, options.maxCost);
     }
     catch (err) {
         console.error(chalk.red(`\n  ${err instanceof Error ? err.message : String(err)}\n`));
@@ -1000,6 +1002,8 @@ export async function workflowRunAction(file, options) {
             signal,
             max_steps: wfMaxSteps,
             stageOutputs: options.stage === true,
+            ...(spendBudget ? { budget: spendBudget } : {}),
+            harnessPolicy: resolveHarnessPolicy(process.env, typeof options.harnessPolicy === "string" ? options.harnessPolicy : undefined, runLogger),
         }), wfTimeoutMs, `Workflow ${workflow.name}`);
         const wfDurationMs = Date.now() - runStart;
         const wfHasFailed = [...results.values()].some((r) => r.status === "failed");

package/dist/cli/run-output.d.ts

@@ -25,6 +25,14 @@ export interface RunSummary {
      * (`max_turns`, `egress allowlist`, `deny [write]`). Absent when none.
      */
     degraded?: string[];
+    /** The spend budget a node crossed (#449). Absent when none was. */
+    budget?: {
+        node: string;
+        scope: "node" | "run";
+        unit: "tokens" | "cost_usd";
+        limit: number;
+        spent: number;
+    };
 }
 /** The short key of a `degraded` entry: the text before its first colon. */
 export declare function degradedKey(entry: string): string;
@@ -33,6 +41,8 @@ export declare function summarizeRun(results: Map<string, NodeResult>, durationM
 export declare function formatReceiptDuration(ms: number): string;
 export declare function formatTokenCount(n: number): string;
 export declare function formatCost(usd: number): string;
+/** `budget exceeded: tokens 52k of 50k (run, at node gather)`. */
+export declare function formatBudgetOverrun(b: NonNullable<RunSummary["budget"]>): string;
 /**
  * One plain line: `✓ 3/3 nodes · 41 tool calls · 2m10s · 12k tokens · $0.18`.
  * Token and cost segments are omitted when the SDK reported none. A harness

package/dist/cli/run-output.js

@@ -24,8 +24,11 @@ export function summarizeRun(results, durationMs, crashed = false) {
     let costUsd;
     let harness;
     const degraded = new Set();
+    let budget;
     const isNum = (v) => typeof v === "number" && Number.isFinite(v);
-    for (const r of results.values()) {
+    for (const [nodeId, r] of results) {
+        if (r.budget && !budget)
+            budget = { node: nodeId, ...r.budget };
         harness ??= r.harness?.id;
         for (const d of r.degraded ?? [])
             degraded.add(degradedKey(d));
@@ -57,6 +60,7 @@ export function summarizeRun(results, durationMs, crashed = false) {
         ...(costUsd !== undefined ? { costUsd } : {}),
         ...(harness !== undefined ? { harness } : {}),
         ...(degraded.size > 0 ? { degraded: [...degraded] } : {}),
+        ...(budget ? { budget } : {}),
     };
 }
 export function formatReceiptDuration(ms) {
@@ -81,6 +85,12 @@ export function formatCost(usd) {
         return "<$0.01";
     return `$${usd.toFixed(2)}`;
 }
+/** `budget exceeded: tokens 52k of 50k (run, at node gather)`. */
+export function formatBudgetOverrun(b) {
+    const amount = (n) => b.unit === "cost_usd" ? (n < 0.01 ? `$${n.toFixed(4)}` : formatCost(n)) : formatTokenCount(n);
+    const unit = b.unit === "cost_usd" ? "cost" : "tokens";
+    return `budget exceeded: ${unit} ${amount(b.spent)} of ${amount(b.limit)} (${b.scope}, at node ${b.node})`;
+}
 /**
  * One plain line: `✓ 3/3 nodes · 41 tool calls · 2m10s · 12k tokens · $0.18`.
  * Token and cost segments are omitted when the SDK reported none. A harness
@@ -98,6 +108,7 @@ export function formatReceipt(s) {
         ...(s.costUsd !== undefined ? [formatCost(s.costUsd)] : []),
         ...(s.harness !== undefined && s.harness !== "claude-code" ? [s.harness] : []),
         ...(s.degraded && s.degraded.length > 0 ? [`degraded: ${s.degraded.join(", ")}`] : []),
+        ...(s.budget ? [formatBudgetOverrun(s.budget)] : []),
     ];
     return parts.join(" · ");
 }
@@ -193,6 +204,14 @@ export const WORKFLOW_RUN_OPTIONS = [
         "--max-steps <n>",
         "Hard cap on total node executions for a single workflow file, including eval-failure retries (default: 200)",
     ],
+    [
+        "--max-tokens <n>",
+        "Run-wide token budget (input plus output) for a single workflow file. The lowest of this and the workflow's budget.tokens wins. A crossing stops the agent, fails the node and halts the run",
+    ],
+    [
+        "--max-cost <usd>",
+        "Run-wide cost budget in US dollars for a single workflow file, from harness-reported cost (never estimated). The lowest of this and the workflow's budget.cost_usd wins",
+    ],
     ["-y, --yes", "Skip the batch confirmation prompt (for CI)"],
     [
         "--dry-run",

package/dist/cli/workflow-input.d.ts

@@ -39,6 +39,15 @@ export declare function parseRunBudgetFlags(timeout: string | undefined, maxStep
     timeoutMs: number;
     maxSteps: number | undefined;
 };
+/**
+ * Parse `--max-tokens <n>` and `--max-cost <usd>` (#449) into a run budget.
+ * Both are optional; junk is rejected up front instead of silently running
+ * with no ceiling. Returns `undefined` when neither flag is set.
+ */
+export declare function parseSpendFlags(maxTokens: string | undefined, maxCost: string | undefined): {
+    tokens?: number;
+    cost_usd?: number;
+} | undefined;
 /**
  * Parse the `--input` flag (#339). The old catch printed only "--input must be
  * valid JSON" and dropped the parser's reason, so a stray quote from shell

package/dist/cli/workflow-input.js

@@ -54,6 +54,27 @@ export function parseRunBudgetFlags(timeout, maxSteps, defaultTimeoutMs) {
         maxSteps: maxSteps === undefined ? undefined : parse(maxSteps, "--max-steps", 1),
     };
 }
+/**
+ * Parse `--max-tokens <n>` and `--max-cost <usd>` (#449) into a run budget.
+ * Both are optional; junk is rejected up front instead of silently running
+ * with no ceiling. Returns `undefined` when neither flag is set.
+ */
+export function parseSpendFlags(maxTokens, maxCost) {
+    const parse = (raw, flag, integer) => {
+        const t = raw.trim();
+        const n = t === "" ? Number.NaN : Number(t);
+        if (!Number.isFinite(n) || n <= 0 || (integer && !Number.isInteger(n))) {
+            throw new Error(`${flag} must be a positive ${integer ? "integer" : "number"}, got "${raw}"` +
+                (integer ? " (input plus output tokens)" : " (US dollars, for example 2.50)"));
+        }
+        return n;
+    };
+    const tokens = maxTokens === undefined ? undefined : parse(maxTokens, "--max-tokens", true);
+    const cost = maxCost === undefined ? undefined : parse(maxCost, "--max-cost", false);
+    if (tokens === undefined && cost === undefined)
+        return undefined;
+    return { ...(tokens !== undefined ? { tokens } : {}), ...(cost !== undefined ? { cost_usd: cost } : {}) };
+}
 /**
  * Parse the `--input` flag (#339). The old catch printed only "--input must be
  * valid JSON" and dropped the parser's reason, so a stray quote from shell

package/dist/executor.d.ts

@@ -13,7 +13,9 @@
  * This replaces ~8k lines of engine + recipe step code.
  */
 import type { Workflow, Skill, Tool, Claude, Observer, Logger, ExecutionResult } from "./types.js";
+import type { HarnessPolicyMode } from "./harness/policy.js";
 import type { AgentHarness } from "./harness/types.js";
+import type { Budget } from "./budget.js";
 import { type ActorInfo } from "./safe-outputs.js";
 export interface ExecuteOptions {
     /** Registered skills (id → Skill) */
@@ -85,6 +87,16 @@ export interface ExecuteOptions {
      * association in the `GITHUB_EVENT_PATH` payload.
      */
     actor?: ActorInfo;
+    /**
+     * Run-wide spend ceiling (#449), tightening `workflow.budget` (the lowest of
+     * the two wins per unit). CLI: `--max-tokens`, `--max-cost`. Default: none.
+     */
+    budget?: Budget;
+    /**
+     * `strict` refuses a node whose spend budget the harness cannot enforce at
+     * all (cost on Codex). Default: {@link resolveHarnessPolicy} from the run env.
+     */
+    harnessPolicy?: HarnessPolicyMode;
 }
 /**
  * Default workflow-level step budget. Counts total node executions across the

package/dist/executor.js

@@ -23,7 +23,8 @@ import { validateWorkflow } from "./schema.js";
 import { resolveAgentAccess } from "./agent-env.js";
 import { fenceUntrusted } from "./untrusted.js";
 import { asClaude } from "./harness/compat.js";
-import { isToolClass, policyGate } from "./harness/policy.js";
+import { budgetGate, isToolClass, policyGate, resolveHarnessPolicy } from "./harness/policy.js";
+import { BudgetGuard, describeOverrun, minLimits, toLimits } from "./budget.js";
 import { buildNodePolicy, resolveNodePermissions } from "./node-policy.js";
 import { applySafeOutputs, createEmitOutputTool, createWriteStageState, resolveActor, safeOutputsInstruction, unresolvedOutputs, SAFE_OUTPUT_SCREEN_INSTRUCTION, } from "./safe-outputs.js";
 /**
@@ -82,6 +83,10 @@ export async function execute(workflow, input, options) {
     const actor = usesOutputs ? resolveActor(runEnv, options.actor) : {};
     // The run input, for `number: { input }` issue pins on outputs.
     const runInput = input && typeof input === "object" ? input : undefined;
+    // Spend budgets (#449): the run ceiling is the lower of the workflow's
+    // `budget` and the caller's (`--max-tokens`, `--max-cost`).
+    const budgetGuard = new BudgetGuard(minLimits(toLimits(workflow.budget), toLimits(options.budget)));
+    const harnessPolicy = options.harnessPolicy ?? resolveHarnessPolicy(runEnv);
     // Build an eval-time alias table from the loaded skills. Each skill owns
     // its own mapping between skill-tool names and equivalent MCP names. Core
     // stays vendor-neutral; this call just unions what the skills declare.
@@ -312,39 +317,98 @@ export async function execute(workflow, input, options) {
         const gate = nodePolicy && options.harness
             ? policyGate(options.harness.capabilities, { ...nodePolicy, egress: [] })
             : undefined;
+        // Spend budgets (#449): this node's own limits plus what is left of the
+        // run's. The gate says whether the harness can keep them; a strict policy
+        // refuses the node when it cannot report the budgeted unit at all.
+        const nodeBudget = budgetGuard.node(toLimits(node.budget));
+        const budgetOn = budgetGuard.active(nodeBudget.limits);
+        const budgetCheck = budgetOn && options.harness
+            ? budgetGate(options.harness.capabilities, minLimits(nodeBudget.limits, budgetGuard.runLimits), permissions.strict || harnessPolicy === "strict")
+            : undefined;
+        // A budget stop: fail_soft and on_fail: continue never apply, the run halts.
+        let budgetStop;
+        let previous;
         while (true) {
-            if (gate?.refuse) {
+            const refusal = gate?.refuse ?? budgetCheck?.refuse;
+            if (refusal) {
                 // Not an agent failure: fail_soft never softens a policy refusal.
-                logger.warn(`  harness refused the node: ${gate.refuse}`, { node: currentId });
+                logger.warn(`  harness refused the node: ${refusal}`, { node: currentId });
                 result = {
                     status: "failed",
-                    data: { error: gate.refuse, refused: true },
+                    data: { error: refusal, refused: true },
                     toolCalls: [],
-                    degraded: gate.degraded,
+                    degraded: [...(gate?.degraded ?? []), ...(budgetCheck?.degraded ?? [])],
+                };
+                break;
+            }
+            // No attempt may start once a ceiling is reached (the run's budget spent
+            // by earlier nodes, or this node's by an earlier attempt).
+            const spent = budgetOn ? nodeBudget.exhausted() : undefined;
+            if (spent) {
+                const error = describeOverrun(spent, currentId);
+                logger.warn(`  ${error}; not starting the node`, { node: currentId });
+                result = {
+                    ...(previous ?? { toolCalls: [] }),
+                    status: "failed",
+                    data: { ...(previous?.data ?? {}), error, budget_exceeded: true },
+                    budget: spent,
                 };
+                agentRunFailed = true;
+                budgetStop = spent;
                 break;
             }
             // Only the final attempt's intents may be applied.
             intents.length = 0;
-            result = await claude.run({
-                instruction: currentInstruction,
-                context,
-                tools: trackedTools,
-                outputSchema: node.output,
-                maxTurns: node.max_turns,
-                disallowedTools: node.disallowed_tools,
-                ...(denyClasses.length > 0 ? { deny: denyClasses } : {}),
-                model: nodeModel,
-                signal,
-                timeoutMs,
-                agentAccess,
-                ...(nodePolicy ? { policy: nodePolicy } : {}),
-                ...(readOnlyNode ? {} : { mcpServers: skillMcpServers }),
-                ...(readOnlyNode ? { readOnly: true } : {}),
-                onProgress: (message) => {
-                    safeObserve(observer, { type: "node:progress", node: currentId, message }, logger);
-                },
-            });
+            const attemptBudget = budgetOn ? nodeBudget.attempt(signal) : undefined;
+            try {
+                result = await claude.run({
+                    instruction: currentInstruction,
+                    context,
+                    tools: trackedTools,
+                    outputSchema: node.output,
+                    maxTurns: node.max_turns,
+                    disallowedTools: node.disallowed_tools,
+                    ...(denyClasses.length > 0 ? { deny: denyClasses } : {}),
+                    model: nodeModel,
+                    signal: attemptBudget?.signal ?? signal,
+                    timeoutMs,
+                    agentAccess,
+                    ...(nodePolicy ? { policy: nodePolicy } : {}),
+                    ...(readOnlyNode ? {} : { mcpServers: skillMcpServers }),
+                    ...(readOnlyNode ? { readOnly: true } : {}),
+                    ...(attemptBudget ? { onUsage: attemptBudget.onUsage } : {}),
+                    onProgress: (message) => {
+                        safeObserve(observer, { type: "node:progress", node: currentId, message }, logger);
+                    },
+                });
+            }
+            finally {
+                attemptBudget?.dispose();
+            }
+            previous = result;
+            if (budgetCheck && budgetCheck.degraded.length > 0) {
+                result = { ...result, degraded: [...new Set([...(result.degraded ?? []), ...budgetCheck.degraded])] };
+            }
+            if (attemptBudget) {
+                // Commit this attempt's spend; a live stop, or a crossing visible only
+                // in the final usage, fails the node whatever else it did.
+                const breach = attemptBudget.finish(result.usage);
+                if (breach) {
+                    const error = describeOverrun(breach, currentId);
+                    logger.warn(`  ${error}`, { node: currentId });
+                    const usage = result.usage ?? attemptBudget.lastUsage;
+                    result = {
+                        ...result,
+                        status: "failed",
+                        data: { ...result.data, error, budget_exceeded: true },
+                        ...(usage ? { usage } : {}),
+                        budget: breach,
+                    };
+                    agentRunFailed = true;
+                    budgetStop = breach;
+                    break;
+                }
+            }
             // Opinions the harness could not honor natively: said once per node, never silently dropped.
             if (!degradedLogged && result.degraded && result.degraded.length > 0) {
                 degradedLogged = true;
@@ -450,7 +514,7 @@ export async function execute(workflow, input, options) {
         // observers. Eval failures never take this path (agentRunFailed guards it).
         // A strict-policy refusal (#331) is not an agent failure: fail_soft never softens it.
         const refused = result.data?.refused === true;
-        if (agentRunFailed && result.status === "failed" && node.fail_soft === true && !refused) {
+        if (agentRunFailed && result.status === "failed" && node.fail_soft === true && !refused && !budgetStop) {
             const failError = result.data?.error;
             logger.warn(`  fail_soft: node failed (${String(failError ?? "unknown error")}); continuing with partial output`, {
                 node: currentId,
@@ -516,9 +580,10 @@ export async function execute(workflow, input, options) {
         // the back of a failure. The failed result stays in `results`, so the run
         // surfaces as failed to callers (CLI exit code, cloud status). Authors who
         // want the legacy fall-through opt in per-node with `on_fail: "continue"`.
-        if (result.status === "failed" && (node.on_fail ?? "halt") === "halt") {
-            logger.warn(`  node failed; halting workflow (on_fail: halt)`, { node: currentId });
-            safeObserve(observer, { type: "route", from: currentId, to: "(end)", reason: "node failed (on_fail: halt)" }, logger);
+        if (result.status === "failed" && ((node.on_fail ?? "halt") === "halt" || budgetStop)) {
+            const why = budgetStop ? "budget exceeded" : "on_fail: halt";
+            logger.warn(`  node failed; halting workflow (${why})`, { node: currentId });
+            safeObserve(observer, { type: "route", from: currentId, to: "(end)", reason: `node failed (${why})` }, logger);
             break;
         }
         // Dry run gate + routing — shared with requires path via advanceFromNode helper.