patchwork-os 0.2.0-beta.9.canary.92 → 1.1.0-beta.1

package/dist/recipes/chainedRunner.js

@@ -6,14 +6,22 @@
  *   - Conditional step execution (when)
  *   - Dry-run mode
  */
+import { classifyTool } from "../riskTier.js";
 import { buildDependencyGraph, executeWithDependencies, } from "./dependencyGraph.js";
 import { categoriseHaltReason, deriveHaltReasonFromError, } from "./haltCategory.js";
 import { mockNestedRecipe, resolveNestedVars, validateNestedRecipe, } from "./nestedRecipeStep.js";
 import { createOutputRegistry } from "./outputRegistry.js";
+import { loadPriceTable } from "./pricing/priceTable.js";
 import { resolveRecipePath } from "./resolveRecipePath.js";
-import { captureForRunlog, detectSilentFail } from "./stepObservation.js";
+import { RunBudget } from "./runBudget.js";
+import { registerRun, unregisterRun } from "./runRegistry.js";
+import { captureForRunlog, detectSilentFail, redactSecretsForPrompt, } from "./stepObservation.js";
 import { compileTemplate } from "./templateEngine.js";
-import { evaluateStepExpect } from "./yamlRunner.js";
+import { computeAgentCallUsage, declaredRecipeEnv, evaluateStepExpect, resolveRouting, } from "./yamlRunner.js";
+/** Normalise the union AgentExecutor return into an AgentResult. */
+function toChainedAgentResult(v) {
+    return typeof v === "string" ? { text: v } : v;
+}
 function nestedRecipeRef(step) {
     return typeof step.recipe === "string"
         ? step.recipe
@@ -26,7 +34,7 @@ export function buildTemplateContext(registry, env) {
     return registry.toTemplateContext(env);
 }
 /** Resolve all template strings in a step */
-export function resolveStepTemplates(step, context) {
+export function resolveStepTemplates(step, context, secretKeys) {
     const resolved = {};
     const errors = [];
     // W3: keys that are recipe metadata, not tool params
@@ -46,6 +54,12 @@ export function resolveStepTemplates(step, context) {
         "retry",
         "retryDelay",
         "parallel",
+        // Runner-meta declared on ChainedStep — must NOT be forwarded as tool
+        // params (the `expect` AJV schema object + numeric timeout especially leak
+        // internal runner config into tools that log their raw params).
+        "expect",
+        "timeout_ms",
+        "silentFailDetection",
     ]);
     // Resolve tool params
     for (const [key, value] of Object.entries(step)) {
@@ -89,10 +103,20 @@ export function resolveStepTemplates(step, context) {
         // assert on err.code without needing to inspect step results).
         resolveRecipePath(resolved.path, { write: toolId !== "file.read" });
     }
-    // Resolve agent prompt if present
+    // Resolve agent prompt if present.
     if (step.agent && typeof step.agent.prompt === "string") {
         const compiled = compileTemplate(step.agent.prompt);
-        const result = compiled.evaluate(context);
+        // Tier-1 #5 (audit 2026-06-22): redact recipe-declared secrets (`type: env`
+        // vars) from the LLM-facing prompt. Their raw values still flow to TOOL
+        // params above (an http header / DB password legitimately needs the
+        // secret), but must never reach the model verbatim. Mirrors the flat runner.
+        const promptContext = secretKeys && secretKeys.size > 0
+            ? {
+                ...context,
+                env: redactSecretsForPrompt(context.env, secretKeys),
+            }
+            : context;
+        const result = compiled.evaluate(promptContext);
         if ("error" in result) {
             errors.push(result.error);
         }
@@ -102,34 +126,86 @@ export function resolveStepTemplates(step, context) {
     }
     // Evaluate when condition
     let conditionResult = true;
-    if (step.when) {
-        const compiled = compileTemplate(step.when);
-        const result = compiled.evaluate(context);
-        if ("error" in result) {
-            errors.push(result.error);
+    if (step.when !== undefined) {
+        // M25: YAML may deliver `when: false` as a boolean even though the TS type
+        // says string — cast to unknown before comparing to silence the type error.
+        if (step.when === false) {
             conditionResult = false;
         }
-        else {
-            // Simple truthiness check (empty string, "0", "false" are falsy)
-            const val = result.value.trim().toLowerCase();
-            conditionResult =
-                !!val &&
-                    val !== "0" &&
-                    val !== "false" &&
-                    val !== "null" &&
-                    val !== "undefined";
+        else if (step.when) {
+            const compiled = compileTemplate(step.when);
+            const result = compiled.evaluate(context);
+            if ("error" in result) {
+                errors.push(result.error);
+                conditionResult = false;
+            }
+            else {
+                // Falsy if the WHOLE value is a falsy token OR its LAST token is — so a
+                // `when` fed an agent's free-text decision (prose ending in "true"/"false")
+                // gates on the verdict, not on "non-empty ⇒ truthy". Single-token guards
+                // are unchanged (last token === whole value). Kept in lockstep with
+                // yamlRunner.ts's guard (runner behavioral parity).
+                const val = result.value.trim().toLowerCase();
+                const FALSY = new Set(["", "0", "false", "null", "undefined"]);
+                const lastToken = (val.split(/\s+/).pop() ?? "").replace(/[^a-z0-9]/g, "");
+                conditionResult = !!val && !FALSY.has(val) && !FALSY.has(lastToken);
+            }
         }
     }
     return { resolved, conditionResult, errors };
 }
+/**
+ * Race `work` against a per-step timeout. Returns `work` unchanged when no
+ * positive timeout is set. On expiry the returned promise rejects with a
+ * `step_timeout` error (executeChainedStep's catch turns that into a step
+ * failure). The underlying call is not cancellable here — it keeps running but
+ * its result is ignored — matching the flat runner's documented behaviour.
+ */
+function raceStepTimeout(work, timeoutMs, label, signal) {
+    const hasTimeout = typeof timeoutMs === "number" && timeoutMs > 0;
+    if (!hasTimeout && !signal)
+        return work;
+    // Run-cancel: reject promptly when the run is aborted so an in-flight
+    // tool/agent step doesn't block the run from draining (the underlying call
+    // keeps running but its result is ignored — same contract as the timeout).
+    if (signal?.aborted) {
+        return Promise.reject(new Error(`step_cancelled: run aborted before step "${label}" completed`));
+    }
+    const racers = [];
+    let timer;
+    if (hasTimeout) {
+        racers.push(new Promise((_, reject) => {
+            timer = setTimeout(() => {
+                reject(new Error(`step_timeout: exceeded ${timeoutMs}ms in step "${label}"`));
+            }, timeoutMs);
+        }));
+    }
+    let onAbort;
+    if (signal) {
+        racers.push(new Promise((_, reject) => {
+            onAbort = () => reject(new Error(`step_cancelled: run aborted during step "${label}"`));
+            signal.addEventListener("abort", onAbort, { once: true });
+        }));
+    }
+    return Promise.race([work, ...racers]).finally(() => {
+        if (timer)
+            clearTimeout(timer);
+        if (signal && onAbort)
+            signal.removeEventListener("abort", onAbort);
+    });
+}
 /** Execute a single step */
 export async function executeChainedStep(ctx, deps) {
-    const { registry, step, options, depth } = ctx;
+    const { registry, step, options, depth, recipe } = ctx;
     const { dryRun } = options;
     // Build template context
     const templateContext = buildTemplateContext(registry, options.env);
+    // Tier-1 #5 (audit 2026-06-22): keys declared via a recipe-level `type: env`
+    // block are secrets — redacted from the LLM-facing agent prompt (but kept
+    // real for tool params). Mirrors the flat runner's `secretKeys`.
+    const secretKeys = new Set(Object.keys(declaredRecipeEnv(recipe, options.env)));
     // Resolve templates
-    const { resolved, conditionResult, errors } = resolveStepTemplates(step, templateContext);
+    const { resolved, conditionResult, errors } = resolveStepTemplates(step, templateContext, secretKeys);
     if (errors.length > 0) {
         return {
             success: false,
@@ -212,6 +288,60 @@ export async function executeChainedStep(ctx, deps) {
     }
     // Execute based on step type
     try {
+        // Tier-1 #6 (audit 2026-06-22): budget admission BEFORE dispatch, gating
+        // ALL step types — not just agent steps. The admission check used to live
+        // inside the `if (step.agent)` branch, so a breached budget kept executing
+        // tool / nested-recipe steps unbounded. admit() is a pure read-only breach
+        // check (no counter side-effects), so gating every step is safe;
+        // subscription drivers report no usage and fail open inside RunBudget, so
+        // this is a no-op until a measured agent step breaches the cap. Mirrors the
+        // flat runner ("Bug (3)").
+        const budget = ctx.budget;
+        if (budget) {
+            const admission = budget.admit();
+            if (!admission.admitted) {
+                return {
+                    success: false,
+                    error: admission.reason ?? "Run exceeded its budget — budget_exceeded.",
+                    resolvedParams: resolved,
+                };
+            }
+        }
+        // Tier-1 #4 (audit 2026-06-22): approval gate, mirroring the flat runner.
+        // Engages only when the bridge injected `requireApprovalFn` (approvalGate
+        // != "off"), respects the per-recipe `requireApproval: false` opt-out, and
+        // gates only the TOP-LEVEL run (depth === 0). Safe-by-default rationale: a
+        // chained recipe always has `trigger.type: "chained"` (that's how
+        // dispatchRecipe routes it), so cron/webhook can never fire one directly —
+        // they route to the flat runner. A top-level chained run is therefore the
+        // user-dispatched (interactive) case the flat runner gates as "manual"; a
+        // NESTED chained recipe (depth > 0) runs under a parent whose own gating
+        // already governed admission, so re-gating every nested step would block
+        // automated parents mid-flight. The injected fn applies the tier threshold
+        // itself and returns `true` for steps that don't need sign-off; a `false`
+        // result is an explicit human rejection → halt the step (and, via the
+        // dependency graph, its dependents). Only agent/tool steps are gated;
+        // nested-recipe steps are gated through their own inner steps.
+        if (deps.requireApprovalFn &&
+            depth === 0 &&
+            (step.agent || step.tool) &&
+            recipe.requireApproval !== false) {
+            const approvalToolId = step.agent ? "agent" : (step.tool ?? "unknown");
+            const approved = await deps.requireApprovalFn({
+                toolId: approvalToolId,
+                tier: classifyTool(approvalToolId),
+                summary: step.agent ? "agent step" : `tool ${approvalToolId}`,
+                params: step.agent ? undefined : resolved,
+                ...(options.signal && { signal: options.signal }), // L1
+            });
+            if (!approved) {
+                return {
+                    success: false,
+                    error: "Step rejected by approval gate — approval_rejected.",
+                    resolvedParams: resolved,
+                };
+            }
+        }
         const recipeRef = nestedRecipeRef(step);
         if (recipeRef) {
             // Nested recipe call
@@ -264,6 +394,8 @@ export async function executeChainedStep(ctx, deps) {
                 maxDepth: options.maxDepth,
                 sourcePath: nestedRecipe.sourcePath,
                 env: { ...options.env, ...resolvedVars }, // Merge resolved vars into env
+                budget: ctx.budget, // share the single per-run budget across the tree
+                priceTable: ctx.priceTable, // reuse the once-loaded price table
             };
             const childResult = await runChainedRecipe(nestedRecipe.recipe, childOptions, deps, childRegistry, depth + 1);
             return {
@@ -278,16 +410,89 @@ export async function executeChainedStep(ctx, deps) {
         else if (step.agent) {
             // Agent step
             const prompt = resolved.agentPrompt ?? step.agent.prompt;
-            let result = await deps.executeAgent(prompt, step.agent.model, step.agent.driver);
+            // Budget admission already happened at the top of this try block
+            // (Tier-1 #6) — it now gates every step type, so the agent-only check
+            // that used to live here was removed. `budget` is the try-scoped const.
+            // Phase 4: opt-in cost-aware routing. No-op when the step has no
+            // `downshift` list or no USD cap is set on the run budget.
+            let dispatchDriver = step.agent.driver;
+            let dispatchModel = step.agent.model;
+            if (budget && step.agent.downshift?.length) {
+                const routed = resolveRouting({ driver: step.agent.driver, model: step.agent.model }, step.agent.downshift, prompt, budget);
+                dispatchDriver = routed.driver === "api" ? "anthropic" : routed.driver;
+                dispatchModel = routed.model;
+            }
+            const agentReturn = toChainedAgentResult(await raceStepTimeout(deps.executeAgent(prompt, dispatchModel, dispatchDriver, {
+                ...(step.agent.mcpAccess !== undefined && {
+                    mcpAccess: step.agent.mcpAccess,
+                }),
+                ...(step.agent.sandbox !== undefined && {
+                    sandbox: step.agent.sandbox,
+                }),
+                ...(step.agent.tools !== undefined && {
+                    allowedTools: step.agent.tools,
+                }),
+                ...(step.agent.disallowedTools !== undefined && {
+                    disallowedTools: step.agent.disallowedTools,
+                }),
+            }), step.timeout_ms, step.id, options.signal));
+            // Reconcile REAL usage after dispatch (the closure now surfaces it
+            // instead of discarding it). Subscription drivers report no usage →
+            // RunBudget fails open with a one-time warning.
+            if (budget) {
+                // Resolve the driver this call should be BILLED against, mirroring the
+                // flat runner exactly (#850 parity):
+                //   1. Prefer the driver `_executeAgent` actually resolved+stamped
+                //      (`servedBy.driver`) — the single source of auto-detect truth.
+                //   2. Normalize the "api" alias to "anthropic" (the downshift branch
+                //      already does this) so a metered call with `agent.driver: "api"`
+                //      and no `servedBy` is charged, not silently dropped.
+                //   3. When the step declares NO driver and the call left no
+                //      `servedBy`, default to "anthropic" — the same API path
+                //      `_executeAgent`'s auto-detect lands on for an unspecified
+                //      driver. The flat runner reaches this default via `servedBy`
+                //      (it always routes through `_executeAgent`); the chained runner
+                //      may be handed an injected `executeAgent` that returns measured
+                //      usage without a `servedBy`, so it must apply the same default
+                //      here or usdMax would be enforced on one runner and not the
+                //      other for identical recipes. A subscription/CLI call that
+                //      genuinely incurs no metered cost stamps `servedBy.driver:
+                //      "subprocess"` via `_executeAgent`, so it never reaches this
+                //      default and stays correctly fail-open.
+                const reconcileDriver = agentReturn.servedBy?.driver ??
+                    (dispatchDriver === "api" || dispatchDriver === undefined
+                        ? "anthropic"
+                        : dispatchDriver);
+                budget.reconcile(reconcileDriver, agentReturn.usage, agentReturn.servedBy?.model ?? dispatchModel, {
+                    inputChars: prompt.length,
+                    outputChars: agentReturn.text.length,
+                });
+            }
+            // P1: per-step agent token usage (chained = one agent call per step).
+            // Attached to every return below so it lands on the persisted step row
+            // regardless of success / failure. Absent for unmeasured drivers.
+            // Thread the once-loaded price table to avoid per-step disk I/O.
+            const usage = computeAgentCallUsage(agentReturn.usage, agentReturn.servedBy, ctx.priceTable);
+            let result = agentReturn.text;
             // Detect failure signals returned as sentinel strings (mirrors flat runner)
             if (typeof result === "string" &&
                 result.startsWith("[agent step failed:")) {
-                return { success: false, error: result, resolvedParams: resolved };
+                return {
+                    success: false,
+                    error: result,
+                    resolvedParams: resolved,
+                    ...(usage ? { usage } : {}),
+                };
             }
             const agentSilentFail = step.silentFailDetection !== false ? detectSilentFail(result) : null;
             if (agentSilentFail) {
                 const reason = `silent-fail detected (${agentSilentFail.reason}): ${agentSilentFail.matched}`;
-                return { success: false, error: reason, resolvedParams: resolved };
+                return {
+                    success: false,
+                    error: reason,
+                    resolvedParams: resolved,
+                    ...(usage ? { usage } : {}),
+                };
             }
             if (step.transform) {
                 try {
@@ -297,21 +502,34 @@ export async function executeChainedStep(ctx, deps) {
                     console.warn(`transform failed for step ${step.id}: ${err}`);
                 }
             }
+            let agentExpectWarnings;
             if (step.expect) {
                 const failures = await evaluateStepExpect(step.expect, result);
-                if (failures.length > 0 && (step.expect.on_fail ?? "halt") === "halt") {
-                    return {
-                        success: false,
-                        error: `expect failed: ${failures.join("; ")}`,
-                        resolvedParams: resolved,
-                    };
+                if (failures.length > 0) {
+                    if ((step.expect.on_fail ?? "halt") === "halt") {
+                        return {
+                            success: false,
+                            error: `expect failed: ${failures.join("; ")}`,
+                            resolvedParams: resolved,
+                            ...(usage ? { usage } : {}),
+                        };
+                    }
+                    // on_fail: "warn" — keep going but surface the failures (mirrors
+                    // the flat runner's `last.expectWarnings`); previously dropped.
+                    agentExpectWarnings = failures;
                 }
             }
-            return { success: true, data: result, resolvedParams: resolved };
+            return {
+                success: true,
+                data: result,
+                resolvedParams: resolved,
+                ...(usage ? { usage } : {}),
+                ...(agentExpectWarnings ? { expectWarnings: agentExpectWarnings } : {}),
+            };
         }
         else if (step.tool) {
             // Tool step
-            let result = await deps.executeTool(step.tool, resolved);
+            let result = await raceStepTimeout(deps.executeTool(step.tool, resolved), step.timeout_ms, step.id, options.signal);
             // Detect tool-level errors reported as JSON {ok: false, error: ...} (mirrors flat runner)
             if (typeof result === "string") {
                 try {
@@ -341,17 +559,28 @@ export async function executeChainedStep(ctx, deps) {
                     console.warn(`transform failed for step ${step.id}: ${err}`);
                 }
             }
+            let toolExpectWarnings;
             if (step.expect) {
                 const failures = await evaluateStepExpect(step.expect, result);
-                if (failures.length > 0 && (step.expect.on_fail ?? "halt") === "halt") {
-                    return {
-                        success: false,
-                        error: `expect failed: ${failures.join("; ")}`,
-                        resolvedParams: resolved,
-                    };
+                if (failures.length > 0) {
+                    if ((step.expect.on_fail ?? "halt") === "halt") {
+                        return {
+                            success: false,
+                            error: `expect failed: ${failures.join("; ")}`,
+                            resolvedParams: resolved,
+                        };
+                    }
+                    // on_fail: "warn" — keep going but surface the failures (mirrors
+                    // the flat runner's `last.expectWarnings`); previously dropped.
+                    toolExpectWarnings = failures;
                 }
             }
-            return { success: true, data: result, resolvedParams: resolved };
+            return {
+                success: true,
+                data: result,
+                resolvedParams: resolved,
+                ...(toolExpectWarnings ? { expectWarnings: toolExpectWarnings } : {}),
+            };
         }
         else {
             return { success: false, error: "Step has no tool, agent, or recipe" };
@@ -362,15 +591,40 @@ export async function executeChainedStep(ctx, deps) {
         return { success: false, error: msg };
     }
 }
+/** Upper bound on retries — clamps absurd/misconfigured values so a recipe
+ *  can't spin a step unboundedly. Mirrors the `maximum` on `retry` in the
+ *  recipe JSON schema. */
+const MAX_RETRIES = 20;
 async function withRetry(fn, maxRetries, delayMs) {
+    // Audit 2026-06-03 (HIGH #8): clamp the retry count. A negative value (typo
+    // like `retry: -1`) made `attempt <= maxRetries` immediately false, so the
+    // step NEVER ran and silently reported as failed. A non-finite or huge value
+    // would spin unboundedly. Floor to an integer in [0, MAX_RETRIES]; non-finite
+    // → 0 (run once, no retries).
+    const safeRetries = Number.isFinite(maxRetries)
+        ? Math.min(MAX_RETRIES, Math.max(0, Math.floor(maxRetries)))
+        : 0;
     let last = { success: false };
-    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    for (let attempt = 0; attempt <= safeRetries; attempt++) {
         if (attempt > 0) {
             await new Promise((r) => setTimeout(r, delayMs));
         }
         last = await fn();
         if (last.success)
             return last;
+        // Audit 2026-06-10 recipe-runners-2: do NOT retry on a step_timeout. The
+        // timed-out attempt's tool/agent call keeps running in the background
+        // (raceStepTimeout only abandons the wait, it does not cancel the call);
+        // re-issuing the step is pointless for write tools (the in-flight
+        // idempotency ledger short-circuits the retry to the same promise) and a
+        // duplicate-side-effect hazard for any tool the ledger cannot dedup. A
+        // true cancel needs an AbortSignal threaded through every tool/connector,
+        // which is out of scope; refusing to retry on timeout is the safe contract.
+        if (last.error?.startsWith("step_timeout:"))
+            return last;
+        // Do not retry cancelled steps — the run was aborted intentionally.
+        if (last.error?.startsWith("step_cancelled:"))
+            return last;
     }
     return last;
 }
@@ -398,6 +652,14 @@ export function expandParallelSteps(steps) {
         if (Array.isArray(step.parallel) && step.parallel.length > 0) {
             // Generate a stable group id from position if the group has no id.
             const groupId = step.id ?? `parallel_${i}`;
+            // Track the group container id too — otherwise a later flat step reusing
+            // the same id passes the duplicate check and silently corrupts the
+            // dependency graph (dependents `awaits: [groupId]` are rewritten to the
+            // group's children, never the shadowed flat step).
+            if (seenIds.has(groupId)) {
+                throw new Error(`expandParallelSteps: duplicate step id "${groupId}" — each step id must be unique`);
+            }
+            seenIds.add(groupId);
             const groupAwaits = step.awaits ?? [];
             const childIds = [];
             for (let j = 0; j < step.parallel.length; j++) {
@@ -422,6 +684,22 @@ export function expandParallelSteps(steps) {
             }
             groupChildren.set(groupId, childIds);
         }
+        else if (typeof step.parallel === "object" &&
+            step.parallel !== null &&
+            !Array.isArray(step.parallel) &&
+            "each" in step.parallel) {
+            // parallel: { each, as, steps } — runtime map-reduce over an array that a
+            // PRIOR step produces. Real support needs dynamic agent fan-out (per-iter
+            // budget/judge/silent-fail) the chained engine doesn't have yet, and the
+            // array isn't known at plan-expansion time. This object form used to fall
+            // through to the flat-step branch below and execute ZERO iterations —
+            // silent data loss with no signal. Fail loud instead. (audit
+            // recipe-chained-1)
+            throw new Error(`Step "${step.id ?? `parallel_${i}`}" uses parallel:{ each } ` +
+                `(runtime map-reduce), which is not yet implemented in chained ` +
+                "recipes. Use the `fan_out` tool step for tool-only loops; agent " +
+                "fan-out over a runtime-produced array is not yet supported.");
+        }
         else {
             if (step.id && seenIds.has(step.id)) {
                 throw new Error(`expandParallelSteps: duplicate step id "${step.id}" — each step id must be unique`);
@@ -463,6 +741,20 @@ export async function runChainedRecipe(recipe, options, deps, existingRegistry,
         }
     }
     const registry = existingRegistry ?? createOutputRegistry();
+    // Per-run budget: build once at the top level from `recipe.budget`; nested
+    // recipe calls inherit the SAME instance via `options.budget` so the whole
+    // tree shares one cap (mirrors the flat path's single RunBudget per run).
+    // Absent `recipe.budget` → an empty RunBudget whose admit/reconcile are
+    // no-ops, so there's no behaviour change for budget-less recipes.
+    const budget = options.budget ?? new RunBudget(recipe.budget);
+    // True only when THIS call constructed the budget — used to gate
+    // refreshPrices() so an injected (unit-test) budget keeps its stable prices
+    // and nested calls don't double-refresh the shared parent budget.
+    const ownsBudget = options.budget === undefined;
+    // Load the price table ONCE per run (inherited by nested recipe calls via
+    // options.priceTable) so each agent step's computeAgentCallUsage avoids a
+    // synchronous existsSync/readFileSync round-trip — mirrors the flat runner.
+    const priceTable = options.priceTable ?? loadPriceTable();
     // Expand parallel: sugar into flat steps before building the dependency graph.
     const steps = expandParallelSteps(recipe.steps);
     // Build dependency graph
@@ -496,7 +788,17 @@ export async function runChainedRecipe(recipe, options, deps, existingRegistry,
             // Non-fatal — run-log failures must never break recipe execution.
         }
     }
-    if (depGraph.hasCycles) {
+    // A phantom `awaits:` target (one matching no real step) is invisible to
+    // cycle detection but would silently drop the awaiting step and its
+    // dependents from execution while the run still reports success. Reject
+    // the run with a descriptive error BEFORE executing any step, mirroring
+    // the circular-dependency guard below.
+    const fatalGraphError = depGraph.unknownAwaitTargets.length > 0
+        ? `Recipe has steps that await unknown step(s): ${depGraph.unknownAwaitTargets.join(", ")}`
+        : depGraph.hasCycles
+            ? "Recipe has circular dependencies"
+            : undefined;
+    if (fatalGraphError) {
         if (depth === 0) {
             const doneAt = Date.now();
             const durationMs = doneAt - runStartedAt;
@@ -507,7 +809,7 @@ export async function runChainedRecipe(recipe, options, deps, existingRegistry,
                         doneAt,
                         durationMs,
                         stepResults: [],
-                        errorMessage: "Recipe has circular dependencies",
+                        errorMessage: fatalGraphError,
                     });
                 }
                 else if (options.runLogDir) {
@@ -522,7 +824,7 @@ export async function runChainedRecipe(recipe, options, deps, existingRegistry,
                         startedAt: runStartedAt,
                         doneAt,
                         durationMs,
-                        errorMessage: "Recipe has circular dependencies",
+                        errorMessage: fatalGraphError,
                         stepResults: [],
                     });
                 }
@@ -535,7 +837,7 @@ export async function runChainedRecipe(recipe, options, deps, existingRegistry,
             success: false,
             stepResults: new Map(),
             summary: { total: 0, succeeded: 0, failed: 0, skipped: 0 },
-            errorMessage: "Recipe has circular dependencies",
+            errorMessage: fatalGraphError,
             context: {},
         };
     }
@@ -553,6 +855,13 @@ export async function runChainedRecipe(recipe, options, deps, existingRegistry,
     // Populated at the `registry.set(...)` site during step execution and
     // attached to the final `RunStepResult` written via `completeRun`.
     const capturedStepData = new Map();
+    // P1 cost/token corpus — per-step agent usage, keyed by stepId. Populated
+    // for every depth-0 agent step (independent of the VD-2 runLog-gated
+    // capture above) so both the bridge and CLI persistence paths get it.
+    const capturedUsage = new Map();
+    // `expect` warnings (on_fail: "warn") per depth-0 step, keyed by stepId, so
+    // they land on the persisted step row instead of being silently dropped.
+    const capturedExpectWarnings = new Map();
     // VD-1 live-tail: when an `activityLog` is provided AND we have a `runSeq`
     // (depth 0, runLog supplied), broadcast `recipe_step_start` /
     // `recipe_step_done` events so the dashboard `/runs/[seq]` page can
@@ -636,21 +945,45 @@ export async function runChainedRecipe(recipe, options, deps, existingRegistry,
         }
         : options.onStepComplete;
     // Execute with dependency tracking
+    // Run-level cancellation. The top-level run (depth 0) registers its own
+    // AbortController keyed by the RunLog seq so `POST /runs/:seq/cancel` can
+    // abort it; nested recipes inherit the parent's signal. Combine both so
+    // either source cancels. (run-cancel)
+    const runController = depth === 0 && runSeq !== undefined ? registerRun(runSeq) : undefined;
+    const cancelSignals = [options.signal, runController?.signal].filter((s) => !!s);
+    const effectiveSignal = cancelSignals.length === 0
+        ? undefined
+        : cancelSignals.length === 1
+            ? cancelSignals[0]
+            : AbortSignal.any(cancelSignals);
+    // Expose the combined signal on the options that flow into executeChainedStep
+    // so an in-flight tool/agent step (via raceStepTimeout) also aborts on cancel,
+    // not just not-yet-started steps. Safe no-op when undefined. (run-cancel)
+    options.signal = effectiveSignal;
     const execOptions = {
         maxConcurrency: options.maxConcurrency,
         onStepStart: wrappedOnStepStart,
         onStepComplete: wrappedOnStepComplete,
+        signal: effectiveSignal,
     };
     const stepExecutor = async (stepId) => {
         const step = stepMap.get(stepId);
         if (!step)
             throw new Error(`Step ${stepId} not found`);
+        // Honour the refreshPrices() contract for long-running recipes: pick up a
+        // mid-run ~/.patchwork/prices.json update for budget enforcement. No-op
+        // unless a usdMax cap is set; gated on ownsBudget so an injected
+        // (unit-test) budget keeps its stable prices.
+        if (ownsBudget)
+            budget.refreshPrices();
         const ctx = {
             registry,
             step,
             options,
             recipe,
             depth,
+            budget,
+            priceTable,
         };
         const retryCount = step.retry ?? recipe.on_error?.retry ?? 0;
         const retryDelay = step.retryDelay ?? recipe.on_error?.retryDelay ?? 1000;
@@ -660,6 +993,15 @@ export async function runChainedRecipe(recipe, options, deps, existingRegistry,
             durationMs: Date.now() - stepStart,
             skipped: result.skipped,
         });
+        // P1: stash this step's agent token usage (depth-0 persistence reads it).
+        if (depth === 0 && result.usage) {
+            capturedUsage.set(stepId, result.usage);
+        }
+        // Stash on_fail:"warn" expect failures so the persisted step row + the
+        // dashboard surface them (previously silently dropped in chained runs).
+        if (depth === 0 && result.expectWarnings?.length) {
+            capturedExpectWarnings.set(stepId, result.expectWarnings);
+        }
         // Recipe-level on_error.fallback: "log_only" and "deliver_original" both
         // treat step failures as non-fatal (fail-open) — same semantics as
         // step-level optional: true. "abort" is the default (propagate failure).
@@ -711,7 +1053,17 @@ export async function runChainedRecipe(recipe, options, deps, existingRegistry,
             throw new Error(result.error ?? `Step ${stepId} failed`);
         }
     };
-    const stepResults = await executeWithDependencies(depGraph, stepExecutor, execOptions);
+    let stepResults;
+    try {
+        stepResults = await executeWithDependencies(depGraph, stepExecutor, execOptions);
+    }
+    finally {
+        // Drop the run from the registry as soon as execution finishes (success,
+        // failure, or cancel) so the seq can't be cancelled post-hoc and the map
+        // doesn't leak. Only the top-level run registered one. (run-cancel)
+        if (runController && runSeq !== undefined)
+            unregisterRun(runSeq);
+    }
     // Merge timings into step results
     const enrichedResults = new Map();
     let failed = 0;
@@ -756,6 +1108,9 @@ export async function runChainedRecipe(recipe, options, deps, existingRegistry,
         try {
             const doneAt = Date.now();
             const stepResultsList = [];
+            // P1: run-level token aggregate, summed from per-step agent usage.
+            const runTok = { inputTokens: 0, outputTokens: 0, measured: false };
+            let runCostUsd;
             for (const [id, r] of enrichedResults) {
                 const step = stepMap.get(id);
                 const captured = capturedStepData.get(id);
@@ -771,6 +1126,16 @@ export async function runChainedRecipe(recipe, options, deps, existingRegistry,
                     status,
                     error: errorMsg,
                 });
+                const expectWarnings = capturedExpectWarnings.get(id);
+                const usage = capturedUsage.get(id);
+                if (usage) {
+                    runTok.measured = true;
+                    runTok.inputTokens += usage.inputTokens;
+                    runTok.outputTokens += usage.outputTokens;
+                    if (typeof usage.costUsd === "number") {
+                        runCostUsd = (runCostUsd ?? 0) + usage.costUsd;
+                    }
+                }
                 stepResultsList.push({
                     id,
                     tool: step?.tool,
@@ -788,12 +1153,36 @@ export async function runChainedRecipe(recipe, options, deps, existingRegistry,
                     ...(captured?.startedAt !== undefined && {
                         startedAt: captured.startedAt,
                     }),
+                    // P1: per-step token usage (absent for tool / unmeasured steps).
+                    ...(usage
+                        ? {
+                            inputTokens: usage.inputTokens,
+                            outputTokens: usage.outputTokens,
+                            ...(typeof usage.costUsd === "number"
+                                ? { costUsd: usage.costUsd }
+                                : {}),
+                        }
+                        : {}),
+                    ...(expectWarnings?.length ? { expectWarnings } : {}),
                 });
             }
+            // P1: assemble run-level totals (only when any step reported usage) +
+            // budget totals (only when a budget was configured).
+            const tokenTotals = runTok.measured
+                ? {
+                    inputTokens: runTok.inputTokens,
+                    outputTokens: runTok.outputTokens,
+                    ...(typeof runCostUsd === "number" ? { costUsd: runCostUsd } : {}),
+                }
+                : undefined;
+            const budgetTotals = recipe.budget ? budget.totals() : undefined;
             const outputTail = stepResultsList
                 .map((s) => `[${s.status}] ${s.tool ?? s.id}${s.error ? `: ${s.error}` : ""}`)
                 .join("\n")
                 .slice(0, 2000);
+            // Budget warnings/spend — record like the flat path so chained runs
+            // surface spend + fail-open notices on the same dashboard surfaces.
+            const budgetWarnings = budget.finalWarnings();
             if (options.runLog && runSeq !== undefined) {
                 options.runLog.completeRun(runSeq, {
                     status: result.success ? "done" : "error",
@@ -801,9 +1190,12 @@ export async function runChainedRecipe(recipe, options, deps, existingRegistry,
                     durationMs: doneAt - runStartedAt,
                     stepResults: stepResultsList,
                     outputTail,
+                    ...(budgetWarnings.length > 0 && { budgetWarnings }),
                     ...(result.errorMessage !== undefined && {
                         errorMessage: result.errorMessage,
                     }),
+                    ...(tokenTotals ? { tokenTotals } : {}),
+                    ...(budgetTotals ? { budgetTotals } : {}),
                 });
                 if (broadcastActivity && broadcastSeq !== undefined) {
                     try {
@@ -839,6 +1231,9 @@ export async function runChainedRecipe(recipe, options, deps, existingRegistry,
                     outputTail,
                     errorMessage: result.errorMessage,
                     stepResults: stepResultsList,
+                    ...(budgetWarnings.length > 0 && { budgetWarnings }),
+                    ...(tokenTotals ? { tokenTotals } : {}),
+                    ...(budgetTotals ? { budgetTotals } : {}),
                 });
             }
         }