patchwork-os 0.2.0-beta.10.canary.99 → 0.2.0-beta.11

package/dist/recipes/yamlRunner.js

@@ -48,9 +48,11 @@ import { categoriseHaltReason } from "./haltCategory.js";
 import { assertValidManualRunId, deriveScopeKey, WriteEffectLedger, } from "./idempotencyKey.js";
 import { buildJudgeArtefactBlock, JUDGE_PROMPT_SUFFIX, parseJudgeVerdict, } from "./judgeVerdict.js";
 import { defaultDeprecationWarn, normalizeRecipeForRuntime, } from "./migrations/index.js";
+import { costRouter } from "./pricing/costRouter.js";
+import { loadPriceTable, costUsd as priceCostUsd, } from "./pricing/priceTable.js";
 import { resolveRecipePath } from "./resolveRecipePath.js";
 import { RunBudget } from "./runBudget.js";
-import { detectSilentFail } from "./stepObservation.js";
+import { detectSilentFail, redactSecretsForPrompt } from "./stepObservation.js";
 // Import tool registry and trigger tool self-registration
 import { applyToolOutputContext, executeTool, getTool, hasTool, registerPluginTools, } from "./toolRegistry.js";
 import { resolveWorkspaceRoot } from "./workspaceRoot.js";
@@ -336,6 +338,103 @@ export async function loadRecipeServers(specs) {
         }
     }
 }
+/**
+ * P1 cost/token corpus — drivers that incur real, metered, per-token API
+ * billing (the only ones whose spend is real money and thus priceable here).
+ * Mirrors `BILLABLE_DRIVERS` in runBudget.ts (kept local — that set is private
+ * and runBudget.ts is enforcement-critical / must not be modified for P1).
+ * `local` reports usage but costs no real money, so it is NOT billable.
+ */
+const COST_BILLABLE_DRIVERS = new Set([
+    "anthropic",
+    "openai",
+    "grok",
+    "gemini",
+]);
+function newStepUsageAccumulator() {
+    return { inputTokens: 0, outputTokens: 0, measured: false };
+}
+/**
+ * Fold one agent call's usage into a per-step accumulator. Adds tokens when
+ * `usage` is present; adds USD only when the served model is billable AND
+ * present in the price table (NEVER a `0` placeholder for the unpriced case).
+ */
+function accumulateAgentUsage(acc, usage, servedBy, priceTable) {
+    if (!usage)
+        return;
+    acc.measured = true;
+    acc.inputTokens += usage.inputTokens;
+    acc.outputTokens += usage.outputTokens;
+    const driver = servedBy?.driver;
+    const model = servedBy?.model;
+    if (driver && model && COST_BILLABLE_DRIVERS.has(driver)) {
+        const cost = priceCostUsd(model, usage, priceTable);
+        if (typeof cost === "number") {
+            acc.costUsd = (acc.costUsd ?? 0) + cost;
+        }
+    }
+}
+/**
+ * Build the optional token fields for a step result from its accumulator.
+ * Returns an empty object (no fields) when the step reported no usage, so a
+ * tool step or unmeasured-driver step round-trips with the fields ABSENT.
+ */
+function stepUsageFields(acc) {
+    if (!acc.measured)
+        return {};
+    return {
+        inputTokens: acc.inputTokens,
+        outputTokens: acc.outputTokens,
+        ...(typeof acc.costUsd === "number" ? { costUsd: acc.costUsd } : {}),
+    };
+}
+/**
+ * P1 — single-call usage → persisted-step usage fields. Exported for the
+ * chained runner, whose agent steps make exactly one agent call (no
+ * judge→refine loop), so a per-call computation suffices. Returns undefined
+ * when the driver reported no usage (fields stay ABSENT). `costUsd` set only
+ * for a billable driver + priced model; never a `0` placeholder.
+ */
+export function computeAgentCallUsage(usage, servedBy, priceTable = loadPriceTable()) {
+    if (!usage)
+        return undefined;
+    const driver = servedBy?.driver;
+    const model = servedBy?.model;
+    let cost;
+    if (driver && model && COST_BILLABLE_DRIVERS.has(driver)) {
+        const c = priceCostUsd(model, usage, priceTable);
+        if (typeof c === "number")
+            cost = c;
+    }
+    return {
+        inputTokens: usage.inputTokens,
+        outputTokens: usage.outputTokens,
+        ...(typeof cost === "number" ? { costUsd: cost } : {}),
+    };
+}
+function newRunUsageAccumulator() {
+    return { inputTokens: 0, outputTokens: 0, measured: false };
+}
+function foldStepIntoRun(run, step) {
+    if (!step.measured)
+        return;
+    run.measured = true;
+    run.inputTokens += step.inputTokens;
+    run.outputTokens += step.outputTokens;
+    if (typeof step.costUsd === "number") {
+        run.costUsd = (run.costUsd ?? 0) + step.costUsd;
+    }
+}
+/** Build the optional `tokenTotals` for a run, or undefined when none measured. */
+function runTokenTotals(run) {
+    if (!run.measured)
+        return undefined;
+    return {
+        inputTokens: run.inputTokens,
+        outputTokens: run.outputTokens,
+        ...(typeof run.costUsd === "number" ? { costUsd: run.costUsd } : {}),
+    };
+}
 export async function runYamlRecipe(recipe, deps = {}, seedContext = {}) {
     if (recipe.servers?.length) {
         await loadRecipeServers(recipe.servers);
@@ -343,6 +442,12 @@ export async function runYamlRecipe(recipe, deps = {}, seedContext = {}) {
     const now = deps.now ? deps.now() : new Date();
     // Resolve recipe-level context blocks (type: env) into seed context
     const envCtx = {};
+    // SECRETS-IN-VARS: track which ctx keys came from a `type: env` block so the
+    // agent (LLM-facing) prompt can redact them. Their raw values still flow to
+    // TOOL steps (an http header / DB password legitimately needs the secret),
+    // but they must never reach the model verbatim — the secure default is
+    // redaction. See PR body / docs/recipe-feature-investigation-2026-06-05.md.
+    const secretKeys = new Set();
     if (Array.isArray(recipe.context)) {
         for (const block of recipe
             .context ?? []) {
@@ -350,8 +455,10 @@ export async function runYamlRecipe(recipe, deps = {}, seedContext = {}) {
             if (b.type === "env" && Array.isArray(b.keys)) {
                 for (const key of b.keys) {
                     const v = process.env[key];
-                    if (v !== undefined)
+                    if (v !== undefined) {
                         envCtx[key] = v;
+                        secretKeys.add(key);
+                    }
                 }
             }
         }
@@ -473,6 +580,13 @@ export async function runYamlRecipe(recipe, deps = {}, seedContext = {}) {
     }
     const outputs = [];
     const stepResults = [];
+    // P1 cost/token corpus. The price table is loaded once per run (fail-open).
+    // `currentStepUsage` accumulates usage across all agent calls of the CURRENT
+    // agent step (including judge→refine re-runs via `runAgentText`); `runUsage`
+    // sums measured steps into the run-level total.
+    const priceTable = loadPriceTable();
+    const runUsage = newRunUsageAccumulator();
+    let currentStepUsage = newStepUsageAccumulator();
     let stepsRun = 0;
     let runError;
     // Bug (2): the flat runner historically recorded the first non-optional
@@ -553,6 +667,179 @@ export async function runYamlRecipe(recipe, deps = {}, seedContext = {}) {
             ts: Date.now(),
         });
     };
+    // ── OPT-IN judge → refine loop (helper closure) ──────────────────────────
+    //
+    // ⚠️ INVARIANT DEPARTURE — this drives a bounded revise→re-judge loop and
+    // MAY gate the run on exhaustion. It departs the augment-only invariant in
+    // judgeVerdict.ts, but is reachable ONLY when the judge step opts in via
+    // `agent.max_revisions > 0`. The augment-only PR3a path is untouched.
+    //
+    // `runAgentText` mirrors the main agent path's text processing exactly
+    // (strip leading narration, then JSON-fence parse + sanitize, else use the
+    // raw string) so a revised draft commits to ctx the same way a first-pass
+    // agent step would. It returns `{ value, ok }`; `ok: false` signals a
+    // failed / silent-fail / empty agent response — the caller stops the loop
+    // and treats it as exhausted (we don't re-judge a non-result).
+    const runAgentText = async (prompt, driver, model, mcpAccess, downshift) => {
+        // Phase 4: route revisions too, so a downshift on the reviewed step also
+        // applies to its refine-loop re-runs (no-op when downshift is absent).
+        const routed = resolveRouting({ driver, model }, downshift, prompt, runBudget);
+        const agentReturn = await _executeAgent({
+            prompt,
+            driver: routed.driver === "api" ? "anthropic" : routed.driver,
+            model: routed.model,
+            ...(mcpAccess !== undefined && { mcpAccess }),
+        }, buildAgentExecutorDeps(stepDeps, deps));
+        runBudget.reconcile(
+        // Prefer the driver executeAgent actually resolved+ran; fall back to
+        // the routed value only when servedBy is absent (non-executeAgent
+        // callers). Stops auto-detected runs being mis-attributed to "auto".
+        agentReturn.servedBy?.driver ??
+            (routed.driver === "api" ? "anthropic" : (routed.driver ?? "auto")), agentReturn.usage, 
+        // Resolved model for USD pricing (Phase 3). Absent → unpriced → the USD
+        // cap fails open for this call.
+        agentReturn.servedBy?.model, 
+        // Char counts for the opt-in unmeasured-driver ≈$ estimate (warn-only).
+        { inputChars: prompt.length, outputChars: agentReturn.text.length });
+        // P1: fold this refine-loop agent call into the current step's usage.
+        accumulateAgentUsage(currentStepUsage, agentReturn.usage, agentReturn.servedBy, priceTable);
+        const text = agentReturn.text;
+        // Same failure detection as the main agent branch: explicit failure
+        // marker or silent-fail patterns ⇒ not a usable result.
+        if (text.startsWith("[agent step failed:") || detectSilentFail(text)) {
+            return { value: text, ok: false };
+        }
+        const stripped = stripLeadingNarration(text);
+        if (!stripped.trim()) {
+            return { value: stripped, ok: false };
+        }
+        try {
+            const jsonMatch = /```(?:json)?\s*([\s\S]*?)```/.exec(stripped) ?? [
+                null,
+                stripped,
+            ];
+            const parsed = sanitizeParsed(JSON.parse((jsonMatch[1] ?? "").trim()));
+            return { value: parsed, ok: true };
+        }
+        catch {
+            return { value: stripped, ok: true };
+        }
+    };
+    const runJudgeRefineLoop = async (params) => {
+        const { agentCfg, reviewsKey, maxRevisions, judgeStepId, firstVerdict, judgeStepResult, failOpenAgent, } = params;
+        // Find the agent step whose output the judge reviews. A judge that
+        // reviews a tool step or a seed var (no agent to re-run) cannot be
+        // refined — skip the loop gracefully, leaving the augment-only verdict
+        // already stashed on the judge step result untouched.
+        const reviewedStep = recipe.steps.find((s) => s.agent && (s.agent.into ?? "agent_output") === reviewsKey);
+        if (!reviewedStep?.agent) {
+            return { haltAfterFailure: false };
+        }
+        const reviewedAgent = reviewedStep.agent;
+        let currentVerdict = firstVerdict;
+        let revisions = 0;
+        while (revisions < maxRevisions &&
+            currentVerdict.verdict === "request_changes") {
+            // Budget gate: never exceed the run's token budget. If admission is
+            // refused, stop early (treat as exhausted) — the budget halt is
+            // surfaced by the next top-of-loop admission check for later steps.
+            const admission = runBudget.admit();
+            if (!admission.admitted) {
+                break;
+            }
+            // REVISE: re-run the reviewed agent with the prior draft + fixList.
+            const priorDraft = ctx[reviewsKey];
+            const fixList = currentVerdict.fixList ?? [];
+            const revisionBlock = `\n\n<revision-request>\n` +
+                `A reviewer requested changes to your previous draft. Address every` +
+                ` item, then return the full revised draft only.\n\n` +
+                `<previous-draft>\n${typeof priorDraft === "string" ? priorDraft : JSON.stringify(priorDraft, null, 2)}\n</previous-draft>\n\n` +
+                `<fix-list>\n${fixList.length > 0 ? fixList.map((f) => `- ${f}`).join("\n") : "- (no explicit fix list provided)"}\n</fix-list>\n` +
+                `</revision-request>`;
+            const revisionPrompt = render(reviewedAgent.prompt, redactSecretsForPrompt(ctx, secretKeys)) +
+                revisionBlock;
+            const revised = await runAgentText(revisionPrompt, reviewedAgent.driver, reviewedAgent.model, reviewedAgent.mcpAccess, reviewedAgent.downshift);
+            if (!revised.ok) {
+                // A failed / empty revision can't be re-judged — stop and treat the
+                // loop as exhausted with the last good verdict still in place.
+                break;
+            }
+            // R4 #1 (HIGH): stage the revised draft locally — do NOT commit to ctx
+            // yet. Committing before the verdict resolves leaves an UNAPPROVED draft
+            // in ctx on any loop break (unparseable verdict, budget denial, failed
+            // re-judge), so downstream steps treat it as approved. The revised value
+            // is only promoted to ctx once a verdict accepts it (approve, or
+            // exhaustion with on_exhausted: "proceed").
+            const pendingRevised = revised.value;
+            // RE-JUDGE: rebuild the judge prompt against the revised artefact. The
+            // judge reviews the STAGED draft, not ctx (which still holds the prior
+            // accepted value).
+            const reJudgePrompt = render(agentCfg.prompt, redactSecretsForPrompt(ctx, secretKeys)) +
+                buildJudgeArtefactBlock(pendingRevised) +
+                JUDGE_PROMPT_SUFFIX;
+            const judged = await runAgentText(reJudgePrompt, agentCfg.driver, agentCfg.model, agentCfg.mcpAccess);
+            if (!judged.ok) {
+                // Audit 2026-06-03 (MEDIUM #17): a failed / silent-fail / empty
+                // RE-JUDGE can't yield a trustworthy verdict. Mirror the revise-
+                // failure break above: stop and KEEP the last good verdict. Parsing
+                // the failure/empty text would have produced a bogus verdict (usually
+                // "unparseable"), silently dropping the request_changes signal and
+                // skipping the on_exhausted gate — the run would proceed as if the
+                // (unvalidated) revised draft had been approved.
+                break;
+            }
+            const judgedText = typeof judged.value === "string"
+                ? judged.value
+                : JSON.stringify(judged.value);
+            currentVerdict = parseJudgeVerdict(stripLeadingNarration(judgedText));
+            revisions++;
+            // R4 #2 (HIGH): an UNPARSEABLE verdict exits the while-loop (only
+            // "request_changes" continues it), but the exhaustion gate below fires
+            // ONLY on "request_changes" — so an unparseable verdict would leave the
+            // run 'ok' with the unvalidated draft never committed and no error.
+            // Treat it as a hard, non-ok stop (distinct from the failed-re-judge
+            // break above, which keeps the prior good verdict). Do NOT promote the
+            // staged draft.
+            if (currentVerdict.verdict === "unparseable") {
+                const reason = `judge "${judgeStepId}" returned an unparseable verdict after revision`;
+                judgeStepResult.judgeVerdict = currentVerdict;
+                judgeStepResult.revisions = revisions;
+                judgeStepResult.status = "error";
+                judgeStepResult.error = reason;
+                judgeStepResult.haltReason = reason;
+                judgeStepResult.haltCategory = "judge_revisions_exhausted";
+                return {
+                    runError: reason,
+                    haltAfterFailure: !failOpenAgent,
+                };
+            }
+            // R4 #1: verdict accepted the revision (approve, or non-exhausted
+            // continuation). Promote the staged draft to ctx so downstream steps and
+            // the next iteration see the improved, judged value.
+            ctx[reviewsKey] = pendingRevised;
+        }
+        // Record the FINAL verdict + the revision count on the judge step result.
+        judgeStepResult.judgeVerdict = currentVerdict;
+        judgeStepResult.revisions = revisions;
+        // EXHAUSTION: still requesting changes after the loop.
+        if (currentVerdict.verdict === "request_changes") {
+            const onExhausted = agentCfg.on_exhausted ?? "halt";
+            if (onExhausted === "halt") {
+                const reason = `judge "${judgeStepId}" did not approve after ${maxRevisions} revisions`;
+                judgeStepResult.status = "error";
+                judgeStepResult.error = reason;
+                judgeStepResult.haltReason = reason;
+                judgeStepResult.haltCategory = "judge_revisions_exhausted";
+                return {
+                    runError: reason,
+                    // Respect fail-open like other agent failures.
+                    haltAfterFailure: !failOpenAgent,
+                };
+            }
+            // "proceed": leave status ok, keep the recorded (unapproved) verdict.
+        }
+        return { haltAfterFailure: false };
+    };
     // The step loop is wrapped so an uncaught throw from any unguarded
     // call site (a `when`/prompt render on a malformed step, a path-jail
     // re-check, etc.) cannot escape `runYamlRecipe` and strand the
@@ -650,7 +937,7 @@ export async function runYamlRecipe(recipe, deps = {}, seedContext = {}) {
                 // PR3a: judge prompt convention. Append the structured-verdict
                 // suffix and, when `reviews: <stepId>` is set, inject the
                 // upstream step's output as an <artefact> block.
-                let renderedPrompt = render(agentCfg.prompt, ctx);
+                let renderedPrompt = render(agentCfg.prompt, redactSecretsForPrompt(ctx, secretKeys));
                 if (isJudge) {
                     if (agentCfg.reviews) {
                         renderedPrompt += buildJudgeArtefactBlock(ctx[agentCfg.reviews]);
@@ -660,6 +947,9 @@ export async function runYamlRecipe(recipe, deps = {}, seedContext = {}) {
                 const intoKey = agentCfg.into ?? "agent_output";
                 const stepId = intoKey;
                 const stepStart = Date.now();
+                // P1: fresh per-step usage accumulator for this agent step (and any
+                // judge→refine re-runs it spawns via runAgentText, which share it).
+                currentStepUsage = newStepUsageAccumulator();
                 let agentResult;
                 // Bug (2): fail-open semantics for THIS agent step. Mirrors the
                 // tool-branch `failOpen` (step.optional OR recipe-level
@@ -677,18 +967,35 @@ export async function runYamlRecipe(recipe, deps = {}, seedContext = {}) {
                 // `RunBudget.reconcile` records a fail-open warning per driver per
                 // run and continues.
                 try {
+                    // Phase 4: opt-in cost-aware routing. No-op (returns preferred) when
+                    // the step has no `downshift` list or no USD cap is set.
+                    const routed = resolveRouting({ driver: agentCfg.driver, model: agentCfg.model }, agentCfg.downshift, renderedPrompt, runBudget);
                     const agentReturn = await _executeAgent({
                         prompt: renderedPrompt,
-                        driver: agentCfg.driver === "api" ? "anthropic" : agentCfg.driver,
-                        model: agentCfg.model,
+                        driver: routed.driver === "api" ? "anthropic" : routed.driver,
+                        model: routed.model,
                         ...(agentCfg.mcpAccess !== undefined && {
                             mcpAccess: agentCfg.mcpAccess,
                         }),
                     }, buildAgentExecutorDeps(stepDeps, deps));
                     agentResult = agentReturn.text;
-                    runBudget.reconcile(agentCfg.driver === "api"
-                        ? "anthropic"
-                        : (agentCfg.driver ?? "auto"), agentReturn.usage);
+                    runBudget.reconcile(
+                    // Prefer the driver executeAgent actually resolved+ran; the routed
+                    // value is only the fallback for non-executeAgent callers (it is
+                    // often undefined → previously logged "auto").
+                    agentReturn.servedBy?.driver ??
+                        (routed.driver === "api"
+                            ? "anthropic"
+                            : (routed.driver ?? "auto")), agentReturn.usage, 
+                    // Resolved model for USD pricing (Phase 3); absent → fail open.
+                    agentReturn.servedBy?.model, 
+                    // Char counts for the opt-in unmeasured-driver ≈$ estimate.
+                    {
+                        inputChars: renderedPrompt.length,
+                        outputChars: agentReturn.text.length,
+                    });
+                    // P1: fold this primary agent call into the current step's usage.
+                    accumulateAgentUsage(currentStepUsage, agentReturn.usage, agentReturn.servedBy, priceTable);
                     // Catch both `[agent step failed: ...]` (existing) and the
                     // silent-fail patterns `[agent step skipped: ...]` etc. via the
                     // shared detector. Per-step opt-out via `silentFailDetection: false`.
@@ -750,13 +1057,43 @@ export async function runYamlRecipe(recipe, deps = {}, seedContext = {}) {
                             const judgeVerdict = isJudge
                                 ? parseJudgeVerdict(stripped)
                                 : undefined;
-                            stepResults.push({
+                            const judgeStepResult = {
                                 id: stepId,
                                 tool: "agent",
                                 status: "ok",
                                 ...(judgeVerdict !== undefined && { judgeVerdict }),
                                 durationMs: Date.now() - stepStart,
-                            });
+                            };
+                            stepResults.push(judgeStepResult);
+                            // ── OPT-IN judge → refine loop ───────────────────────────────
+                            // ⚠️ INVARIANT DEPARTURE: when the judge step opts in via
+                            // `max_revisions > 0`, a `request_changes` verdict now DRIVES a
+                            // bounded revise→re-judge loop instead of merely stashing the
+                            // verdict. This deliberately departs the augment-only invariant
+                            // (see judgeVerdict.ts) — but ONLY when the opt-in fields are
+                            // present. With them absent the block below is skipped entirely
+                            // and behavior is byte-identical to the PR3a augment-only path.
+                            if (isJudge &&
+                                agentCfg.reviews &&
+                                typeof agentCfg.max_revisions === "number" &&
+                                agentCfg.max_revisions > 0 &&
+                                judgeVerdict?.verdict === "request_changes") {
+                                const loopOutcome = await runJudgeRefineLoop({
+                                    agentCfg,
+                                    reviewsKey: agentCfg.reviews,
+                                    maxRevisions: agentCfg.max_revisions,
+                                    judgeStepId: stepId,
+                                    firstVerdict: judgeVerdict,
+                                    judgeStepResult,
+                                    failOpenAgent,
+                                });
+                                if (loopOutcome.runError !== undefined) {
+                                    runError = runError ?? loopOutcome.runError;
+                                }
+                                if (loopOutcome.haltAfterFailure) {
+                                    haltAfterFailure = true;
+                                }
+                            }
                             // Slice 2 — per-step expect eval. Runs on the value just
                             // committed to ctx[intoKey]. Halt failure flips the just-pushed
                             // result to error and rolls back the ctx commit so downstream
@@ -802,6 +1139,14 @@ export async function runYamlRecipe(recipe, deps = {}, seedContext = {}) {
                         durationMs: Date.now() - stepStart,
                     });
                 }
+                // P1: attach this agent step's summed token usage (across primary +
+                // any judge→refine re-runs) to the result just pushed, and fold it
+                // into the run-level total. Fields are ABSENT when no usage measured.
+                const pushedAgentResult = stepResults[stepResults.length - 1];
+                if (pushedAgentResult) {
+                    Object.assign(pushedAgentResult, stepUsageFields(currentStepUsage));
+                }
+                foldStepIntoRun(runUsage, currentStepUsage);
                 stepsRun++;
                 persistLiveStepResults();
                 emitStepDone(stepIdForEmit);
@@ -1059,8 +1404,21 @@ export async function runYamlRecipe(recipe, deps = {}, seedContext = {}) {
                 ...(s.haltReason ? { haltReason: s.haltReason } : {}),
                 ...(s.haltCategory ? { haltCategory: s.haltCategory } : {}),
                 ...(s.judgeVerdict ? { judgeVerdict: s.judgeVerdict } : {}),
+                // P1: carry per-step token usage through to the persisted run row.
+                // Absent for tool / unmeasured-driver steps (round-trips unchanged).
+                ...(typeof s.inputTokens === "number"
+                    ? { inputTokens: s.inputTokens }
+                    : {}),
+                ...(typeof s.outputTokens === "number"
+                    ? { outputTokens: s.outputTokens }
+                    : {}),
+                ...(typeof s.costUsd === "number" ? { costUsd: s.costUsd } : {}),
                 durationMs: s.durationMs,
             }));
+            // P1: run-level token aggregate + budget totals (latter only when a
+            // budget was configured — never persist all-zero no-budget totals).
+            const tokenTotals = runTokenTotals(runUsage);
+            const budgetTotals = recipe.budget ? runBudget.totals() : undefined;
             if (deps.runLog && runSeq !== undefined) {
                 deps.runLog.completeRun(runSeq, {
                     status: runError ? "error" : "done",
@@ -1071,6 +1429,11 @@ export async function runYamlRecipe(recipe, deps = {}, seedContext = {}) {
                     ...(runError !== undefined && { errorMessage: runError }),
                     ...(assertionFailures.length > 0 ? { assertionFailures } : {}),
                     ...(inboxOutputs.length > 0 ? { inboxOutputs } : {}),
+                    ...(runBudget.finalWarnings().length > 0
+                        ? { budgetWarnings: runBudget.finalWarnings() }
+                        : {}),
+                    ...(tokenTotals ? { tokenTotals } : {}),
+                    ...(budgetTotals ? { budgetTotals } : {}),
                 });
                 emit("recipe_done", {
                     runSeq,
@@ -1108,6 +1471,8 @@ export async function runYamlRecipe(recipe, deps = {}, seedContext = {}) {
                     stepResults: finalStepResults,
                     ...(assertionFailures.length > 0 ? { assertionFailures } : {}),
                     ...(inboxOutputs.length > 0 ? { inboxOutputs } : {}),
+                    ...(tokenTotals ? { tokenTotals } : {}),
+                    ...(budgetTotals ? { budgetTotals } : {}),
                 });
             }
         }
@@ -1154,6 +1519,14 @@ export async function runYamlRecipe(recipe, deps = {}, seedContext = {}) {
         stepResults,
         errorMessage: runError,
         ...(assertionFailures.length > 0 ? { assertionFailures } : {}),
+        ...(runBudget.finalWarnings().length > 0
+            ? { budgetWarnings: runBudget.finalWarnings() }
+            : {}),
+        // P1: forward run-level token aggregate to callers / persisters.
+        ...(() => {
+            const tt = runTokenTotals(runUsage);
+            return tt ? { tokenTotals: tt } : {};
+        })(),
     };
 }
 export async function executeStep(step, ctx, deps) {
@@ -1554,6 +1927,43 @@ export function defaultClaudeCodeFn(prompt, opts) {
         return Promise.resolve(`[agent step failed: ${err instanceof Error ? err.message : String(err)}]`);
     }
 }
+/**
+ * Map a driver's `providerMeta` to AgentUsage. Returns undefined unless BOTH
+ * token counts are present as numbers — a half-populated count would mislead
+ * RunBudget. Pure + exported for tests.
+ */
+export function providerMetaToUsage(meta) {
+    if (!meta)
+        return undefined;
+    const inputTokens = meta.inputTokens;
+    const outputTokens = meta.outputTokens;
+    if (typeof inputTokens === "number" && typeof outputTokens === "number") {
+        return { inputTokens, outputTokens };
+    }
+    return undefined;
+}
+const ROUTER_CHARS_PER_TOKEN = 4;
+/**
+ * Apply opt-in cost-aware routing (Phase 4) to choose the driver/model for an
+ * agent dispatch. Returns `preferred` UNCHANGED when there is no downshift list
+ * or no USD cap is set (byte-identical to no routing). The output-token figure
+ * is a deliberately-rough 1:1-of-input pre-dispatch estimate — enough to pick a
+ * gear; the real cost is reconciled after the call (see the cost-routing ADR).
+ * Exported for unit testing.
+ */
+export function resolveRouting(preferred, downshift, promptText, budget) {
+    if (!downshift || downshift.length === 0)
+        return preferred;
+    const remainingUsd = budget.remainingUsd();
+    if (remainingUsd === undefined)
+        return preferred; // no USD cap → no routing
+    const estInputTokens = Math.ceil(promptText.length / ROUTER_CHARS_PER_TOKEN);
+    const estOutputTokens = estInputTokens; // rough 1:1 assumption (documented)
+    return costRouter(preferred, downshift, {
+        remainingUsd,
+        quote: (driver, model) => budget.quoteUsd(driver, model, estInputTokens, estOutputTokens),
+    });
+}
 /** Returns a providerDriverFn with a per-run driver cache (not shared across runs). */
 export function makeProviderDriverFn() {
     const cache = new Map();
@@ -1599,6 +2009,26 @@ export function makeProviderDriverFn() {
                 if (!result.text) {
                     return `[agent step failed: ${driverName} returned empty output (possible timeout or auth error)]`;
                 }
+                // Forward token usage (when the driver reported it) so RunBudget can
+                // enforce a real budget for openai/grok/gemini instead of failing
+                // open. No usage → bare string, normalised to {text} downstream.
+                const usage = providerMetaToUsage(result.providerMeta);
+                // Carry the model the driver ACTUALLY resolved+billed (providerMeta.
+                // model, e.g. openai's "gpt-4o" default when the step omitted model) so
+                // RunBudget prices the real model. executeAgent's stamp() is idempotent
+                // — it preserves this servedBy rather than re-deriving from raw input.
+                const resolvedModel = typeof result.providerMeta?.model === "string"
+                    ? result.providerMeta.model
+                    : undefined;
+                if (usage || resolvedModel) {
+                    return {
+                        text: result.text,
+                        ...(usage ? { usage } : {}),
+                        ...(resolvedModel
+                            ? { servedBy: { driver: driverName, model: resolvedModel } }
+                            : {}),
+                    };
+                }
                 return result.text;
             }
             finally {
@@ -1610,13 +2040,30 @@ export function makeProviderDriverFn() {
         }
     };
 }
-async function defaultClaudeFn(prompt, model) {
+/** Default Anthropic API request timeout. Mirrors the provider path (300s). */
+const DEFAULT_CLAUDE_API_TIMEOUT_MS = 300_000;
+/**
+ * R4 #4 (HIGH): default max output tokens. The old hard-coded 1024 silently
+ * truncated structured JSON (judge verdicts, multi-field agent outputs).
+ */
+const DEFAULT_CLAUDE_MAX_TOKENS = 4096;
+export async function defaultClaudeFn(prompt, model, opts) {
     const apiKey = process.env.ANTHROPIC_API_KEY;
     if (!apiKey)
         return { text: "[agent step skipped: ANTHROPIC_API_KEY not set]" };
+    const maxTokens = typeof opts?.maxTokens === "number" && opts.maxTokens > 0
+        ? opts.maxTokens
+        : DEFAULT_CLAUDE_MAX_TOKENS;
+    // R4 #3 (HIGH): abort a stalled gateway instead of hanging the run forever.
+    const timeoutMs = typeof opts?.timeoutMs === "number" && opts.timeoutMs > 0
+        ? opts.timeoutMs
+        : DEFAULT_CLAUDE_API_TIMEOUT_MS;
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), timeoutMs);
     try {
         const res = await fetch("https://api.anthropic.com/v1/messages", {
             method: "POST",
+            signal: controller.signal,
             headers: {
                 "x-api-key": apiKey,
                 "anthropic-version": "2023-06-01",
@@ -1624,7 +2071,7 @@ async function defaultClaudeFn(prompt, model) {
             },
             body: JSON.stringify({
                 model,
-                max_tokens: 1024,
+                max_tokens: maxTokens,
                 messages: [
                     {
                         role: "user",
@@ -1642,7 +2089,12 @@ async function defaultClaudeFn(prompt, model) {
         // versions) and downstream (subscription/CLI driver returns
         // undefined here).
         const data = (await res.json());
-        const text = data.content?.[0]?.text ?? "[agent step failed: empty response]";
+        let text = data.content?.[0]?.text ?? "[agent step failed: empty response]";
+        // R4 #4: detect+warn when the response was cut off at the token cap so a
+        // truncated (likely unparseable) JSON payload isn't silently trusted.
+        if (data.stop_reason === "max_tokens") {
+            text = `[warning: response truncated at max_tokens=${maxTokens}; raise max_tokens]\n${text}`;
+        }
         const inputTokens = data.usage?.input_tokens;
         const outputTokens = data.usage?.output_tokens;
         if (typeof inputTokens === "number" && typeof outputTokens === "number") {
@@ -1651,10 +2103,20 @@ async function defaultClaudeFn(prompt, model) {
         return { text };
     }
     catch (err) {
+        const aborted = controller.signal.aborted ||
+            (err instanceof Error && err.name === "AbortError");
+        if (aborted) {
+            return {
+                text: `[agent step failed: Anthropic API request timed out after ${timeoutMs}ms]`,
+            };
+        }
         return {
             text: `[agent step failed: ${err instanceof Error ? err.message : String(err)}]`,
         };
     }
+    finally {
+        clearTimeout(timeout);
+    }
 }
 export async function defaultLocalFn(prompt, model) {
     try {
@@ -1749,16 +2211,17 @@ export function buildChainedDeps(runnerDeps, claudeCodeFnOverride) {
         return result ?? "";
     };
     const executeAgent = async (prompt, model, driver, mcpAccess) => {
-        // chainedRunner's AgentExecutor contract still returns a plain string —
-        // PR2b's token-budget consumer will plug in here as well, but for now
-        // we discard `.usage`.
-        const result = await _executeAgent({
+        // Surface the FULL AgentResult (text + usage + servedBy) so the chained
+        // runner can reconcile real spend against the run budget — alignment with
+        // the flat path, which already reads `.usage`. (Previously this closure
+        // discarded everything but `.text`, leaving the chained path's budget
+        // unenforced — the S1 SECURITY finding.)
+        return _executeAgent({
             prompt,
             model,
-            driver,
+            driver: driver === "api" ? "anthropic" : driver,
             ...(mcpAccess !== undefined && { mcpAccess }),
         }, buildAgentExecutorDeps(stepDeps, runnerDeps, claudeCodeFnOverride));
-        return result.text;
     };
     // ---------------------------------------------------------------------
     // BEGIN A-PR2 EDIT BLOCK — `loadNestedRecipe` jail (dogfood F-04).