patchwork-os 0.2.0-beta.0 → 0.2.0-beta.10

package/dist/recipes/yamlRunner.js

@@ -14,7 +14,10 @@
  *   file.read     — read file into `into` variable (optional: true ok)
  *   git.log_since — run git log --oneline --since=<since> (injected for tests)
  *   git.stale_branches — list branches with no activity in N days
- *   diagnostics.get — stub: returns empty string (bridge not required)
+ *   diagnostics.get — returns the bridge's LSP diagnostics; in CLI runs
+ *                     (no bridge available) returns a JSON {ok:false,error}
+ *                     payload that the step-error detector flags so the
+ *                     recipe halts rather than silently succeeding.
  *
  * Supported trigger types (for `patchwork recipe run`):
  *   manual, cron — both run immediately via CLI
@@ -27,14 +30,29 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { parse as parseYaml } from "yaml";
 import { captureFixture } from "../connectors/fixtureRecorder.js";
+import { sanitizeEnv } from "../drivers/claude/envSanitizer.js";
 import { loadConfig as loadPatchworkConfigSync } from "../patchworkConfig.js";
 import { findYamlRecipePath } from "../recipesHttp.js";
+/**
+ * Local alias for `sanitizeParsedJson` from `src/sanitizeParsedJson.ts`.
+ * Kept under the old name so the existing callsites in this file don't
+ * need to be renamed. The shared module is the canonical home for the
+ * prototype-pollution scrub — see PR #568 + audit 2026-05-17 + the
+ * comment in that file for full rationale.
+ */
+import { sanitizeParsedJson as sanitizeParsed } from "../sanitizeParsedJson.js";
+import { ensureCmdShim } from "../winShim.js";
 import { executeAgent as _executeAgent, } from "./agentExecutor.js";
-import { defaultDeprecationWarn, normalizeRecipeForRuntime, } from "./legacyRecipeCompat.js";
+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 { resolveRecipePath } from "./resolveRecipePath.js";
+import { RunBudget } from "./runBudget.js";
 import { detectSilentFail } 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";
 import "./tools/index.js";
 /**
  * Bundled-templates directory used as a third allowed root for nested-recipe
@@ -111,7 +129,128 @@ export function evaluateExpect(result, expect) {
     }
     return failures;
 }
+/**
+ * Lazy AJV for `step.expect.schema`. Initialised on first use so recipes
+ * without schema assertions don't pay the import/compile cost.
+ */
+let _stepExpectAjv;
+async function getStepExpectAjv() {
+    if (!_stepExpectAjv) {
+        const { createAjv2020 } = await import("../ajv2020.js");
+        _stepExpectAjv = createAjv2020({ strict: false, allErrors: true });
+    }
+    return _stepExpectAjv;
+}
+/**
+ * Stringify a step value for assertion purposes. Strings pass through;
+ * other values JSON.stringify so `matches`/`contains` see something stable.
+ */
+function stringifyForAssert(value) {
+    if (typeof value === "string")
+        return value;
+    try {
+        return JSON.stringify(value);
+    }
+    catch {
+        return String(value);
+    }
+}
+/**
+ * Evaluate a per-step `expect` block against the step's output value.
+ * Returns the list of failure messages (empty = all assertions passed).
+ *
+ * Slice 2 of the agentic-workflow primitives. v1 supports
+ * schema/equals/matches/contains; `on_fail: judge` deliberately omitted —
+ * see comment on `StepExpect`.
+ */
+export async function evaluateStepExpect(expect, value) {
+    const failures = [];
+    const asString = stringifyForAssert(value);
+    if (expect.equals !== undefined) {
+        const expected = expect.equals;
+        const expectedStr = typeof expected === "string" ? expected : stringifyForAssert(expected);
+        if (asString !== expectedStr) {
+            failures.push(`equals: expected ${JSON.stringify(expectedStr)}, got ${JSON.stringify(asString)}`);
+        }
+    }
+    if (expect.contains !== undefined) {
+        const needles = Array.isArray(expect.contains)
+            ? expect.contains
+            : [expect.contains];
+        for (const needle of needles) {
+            if (!asString.includes(needle)) {
+                failures.push(`contains: missing ${JSON.stringify(needle)}`);
+            }
+        }
+    }
+    if (expect.matches !== undefined) {
+        // Guard against ReDoS: limit pattern and input string length before
+        // compiling / executing user-supplied regex.
+        const MAX_PATTERN = 500;
+        const MAX_INPUT = 65_536; // 64 KB
+        if (expect.matches.length > MAX_PATTERN) {
+            failures.push(`matches: regex pattern too long (${expect.matches.length} chars, max ${MAX_PATTERN})`);
+            return failures;
+        }
+        let re;
+        try {
+            re = new RegExp(expect.matches);
+        }
+        catch (err) {
+            failures.push(`matches: invalid regex ${JSON.stringify(expect.matches)} (${err instanceof Error ? err.message : String(err)})`);
+            return failures;
+        }
+        const testInput = asString.length > MAX_INPUT ? asString.slice(0, MAX_INPUT) : asString;
+        if (!re.test(testInput)) {
+            failures.push(`matches: ${JSON.stringify(expect.matches)} did not match output`);
+        }
+    }
+    if (expect.schema !== undefined) {
+        let parsed;
+        try {
+            parsed = typeof value === "string" ? JSON.parse(value) : value;
+        }
+        catch {
+            failures.push(`schema: output is not valid JSON`);
+            return failures;
+        }
+        try {
+            const ajv = await getStepExpectAjv();
+            const validate = ajv.compile(expect.schema);
+            if (!validate(parsed)) {
+                const errs = (validate.errors ?? [])
+                    .map((e) => `${e.instancePath || "/"} ${e.message ?? "invalid"}`)
+                    .join("; ");
+                failures.push(`schema: ${errs || "validation failed"}`);
+            }
+        }
+        catch (err) {
+            failures.push(`schema: compile error (${err instanceof Error ? err.message : String(err)})`);
+        }
+    }
+    return failures;
+}
 // Strip tool-call narration some models (e.g. Gemini) prepend before the markdown block.
+/**
+ * Phase 0β — separator-agnostic inbox-path detector. Extracted so the
+ * Windows path-separator behaviour can be unit-tested by injecting
+ * `path.win32` / `path.posix` without booting a real recipe runner.
+ *
+ * Returns true when `candidate` resolves to a direct child of
+ * `inboxDirAbs`, isn't a dotfile, and lives in (not above) the inbox
+ * dir. Both arguments must already be platform-appropriate absolute
+ * paths (resolve them with the same path module before calling).
+ */
+export function isInboxPathFor(candidate, inboxDirAbs, pathMod) {
+    const target = pathMod.resolve(candidate);
+    const rel = pathMod.relative(inboxDirAbs, target);
+    if (!rel || rel.startsWith("..") || pathMod.isAbsolute(rel))
+        return false;
+    if (pathMod.basename(target).startsWith("."))
+        return false;
+    // Only direct children — `~/.patchwork/inbox/foo.md`, not nested.
+    return !rel.includes(pathMod.sep);
+}
 function stripLeadingNarration(text) {
     const lines = text.split("\n");
     const firstMarkdown = lines.findIndex((l) => /^(#|>|`|\||[-*+] |\d+\. |\*\*)/.test(l.trimStart()));
@@ -222,7 +361,88 @@ export async function runYamlRecipe(recipe, deps = {}, seedContext = {}) {
         ...envCtx,
         ...seedContext,
     };
-    const stepDeps = resolveStepDeps(deps);
+    const stepDeps = resolveStepDeps(deps, { recipeName: recipe.name });
+    // Phase 0β — inbox provenance. When a recipe `file.write` / `file.append`
+    // step targets `~/.patchwork/inbox/`, prepend a YAML frontmatter block
+    // (first write only) recording recipe + run + trigger, and accumulate the
+    // delivered filename onto the run record's `inboxOutputs`. Old recipes /
+    // non-inbox paths pass through unchanged.
+    //
+    // Windows path-separator fix (CI repro 2026-05-20): the original
+    // implementation built the prefix as `${os.homedir()}/.patchwork/inbox/`
+    // and compared with `startsWith`, which failed on Windows where
+    // resolved absolute paths use `\` separators and `os.homedir()` returns
+    // `C:\Users\...`. Now we resolve both sides through `path.resolve()`
+    // and use `path.relative()` to detect containment so the comparison is
+    // separator-agnostic. Also case-insensitive on Win32 (NTFS).
+    const inboxDirAbs = path.resolve(path.join(os.homedir(), ".patchwork", "inbox"));
+    const inboxOutputs = [];
+    const isInboxPath = (abs) => isInboxPathFor(abs, inboxDirAbs, path);
+    const buildFrontmatter = () => {
+        const triggerKindAtWrite = yamlTriggerKind;
+        const lines = ["---", `recipe: ${recipe.name}`];
+        if (runSeq !== undefined)
+            lines.push(`runSeq: ${runSeq}`);
+        lines.push(`trigger: ${triggerKindAtWrite}`, `deliveredAt: ${new Date().toISOString()}`, "---", "", "");
+        return lines.join("\n");
+    };
+    const recordInboxDelivery = (abs) => {
+        inboxOutputs.push({
+            filename: path.basename(abs),
+            deliveredAt: Date.now(),
+        });
+    };
+    // Atomic read-or-default: a single `readFileSync` in a try/catch. No
+    // `existsSync`/`statSync` probe around the write — on Windows a stat
+    // immediately before write can race a concurrent fd holder and surface
+    // `EBUSY`/`EPERM`. The read either succeeds (file present) or throws
+    // ENOENT (treated as new file). Either way we never stat the same path
+    // we're about to write.
+    const readExistingOrEmpty = (abs) => {
+        try {
+            return readFileSync(abs, "utf-8");
+        }
+        catch {
+            return "";
+        }
+    };
+    const originalWrite = stepDeps.writeFile;
+    const originalAppend = stepDeps.appendFile;
+    stepDeps.writeFile = (p, content) => {
+        if (isInboxPath(p)) {
+            // First-write detection by content shape, not by stat. Empty string
+            // (ENOENT) and any file that does NOT already begin with `---\n`
+            // gets frontmatter; pre-frontmattered files are overwritten as-is
+            // so consumers can replay a recipe without doubling the header.
+            const existing = readExistingOrEmpty(p);
+            const hasFm = existing.startsWith("---\n");
+            const final = hasFm ? content : buildFrontmatter() + content;
+            originalWrite(p, final);
+            recordInboxDelivery(p);
+            return;
+        }
+        originalWrite(p, content);
+    };
+    stepDeps.appendFile = (p, content) => {
+        if (isInboxPath(p)) {
+            // file.append: never re-prepend. If file is brand-new, seed one
+            // frontmatter block so an append-only recipe still gets
+            // provenance. Same atomic read-or-default — no stat probe.
+            const existing = readExistingOrEmpty(p);
+            if (existing.length === 0) {
+                originalWrite(p, buildFrontmatter() + content);
+            }
+            else {
+                originalAppend(p, content);
+            }
+            recordInboxDelivery(p);
+            return;
+        }
+        originalAppend(p, content);
+    };
+    // PR2b: one per-run budget shared across all agent steps. Absent
+    // `recipe.budget` → no enforcement, no overhead.
+    const runBudget = new RunBudget(recipe.budget);
     // Open a `running`-state run-log entry so the dashboard sees the recipe
     // as in flight. Only when a long-lived `runLog` is provided (bridge path);
     // CLI runs fall back to `appendDirect` at end via the existing logDir
@@ -241,6 +461,9 @@ export async function runYamlRecipe(recipe, deps = {}, seedContext = {}) {
                 trigger: yamlTriggerKind,
                 createdAt: recipeStartedAt,
                 startedAt: recipeStartedAt,
+                ...(deps.manualRunId !== undefined && {
+                    manualRunId: deps.manualRunId,
+                }),
             });
         }
         catch {
@@ -251,218 +474,512 @@ export async function runYamlRecipe(recipe, deps = {}, seedContext = {}) {
     const stepResults = [];
     let stepsRun = 0;
     let runError;
-    for (const step of recipe.steps) {
-        // Handle agent steps separately
-        if (step.agent) {
-            const agentCfg = step.agent;
-            const renderedPrompt = render(agentCfg.prompt, ctx);
-            const intoKey = agentCfg.into ?? "agent_output";
-            const stepId = intoKey;
-            const stepStart = Date.now();
-            let agentResult;
-            try {
-                agentResult = await _executeAgent({
-                    prompt: renderedPrompt,
-                    driver: agentCfg.driver === "api" ? "anthropic" : agentCfg.driver,
-                    model: agentCfg.model,
-                }, buildAgentExecutorDeps(stepDeps, deps));
-                // 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`.
-                const agentSilentFail = step.silentFailDetection !== false
-                    ? detectSilentFail(agentResult)
-                    : null;
-                if (agentResult.startsWith("[agent step failed:") || agentSilentFail) {
-                    const reason = agentSilentFail
-                        ? `silent-fail detected (${agentSilentFail.reason}): ${agentSilentFail.matched}`
-                        : agentResult;
+    // Live-tail SSE broadcaster. Wrapped in a try/catch on every call so a
+    // misbehaving listener can never break the run (mirrors chainedRunner).
+    // No-ops when `activityLog` isn't wired (CLI runs, tests, mocks).
+    const broadcast = deps.activityLog;
+    const emit = (event, metadata) => {
+        if (!broadcast || runSeq === undefined || stepDeps.testMode)
+            return;
+        try {
+            broadcast.recordEvent(event, metadata);
+        }
+        catch {
+            /* live-tail must not break a recipe run */
+        }
+    };
+    // Emit recipe_started as soon as we have a runSeq. The dashboard
+    // RecipeRunInline component watches for this event to flip a row
+    // from "queued" to "running" without waiting for the first step.
+    emit("recipe_started", {
+        runSeq,
+        recipeName: recipe.name,
+        trigger: yamlTriggerKind,
+        totalSteps: recipe.steps.length,
+        ts: recipeStartedAt,
+    });
+    // Push live step results into the run-log ring so the dashboard's
+    // `/runs/[seq]` page surfaces verdicts + haltReasons mid-flight,
+    // instead of waiting for the whole recipe to finish via
+    // `completeRun`. The runLog ignores non-running entries; cron/webhook
+    // runs through the orchestrator path (where `runSeq` is undefined)
+    // skip this entirely.
+    const persistLiveStepResults = () => {
+        if (!deps.runLog || runSeq === undefined || stepDeps.testMode)
+            return;
+        try {
+            deps.runLog.updateRunSteps(runSeq, stepResults);
+        }
+        catch {
+            /* live-tail is best-effort; never break a recipe run for it */
+        }
+    };
+    // Track per-step start timestamps so done events carry durationMs
+    // without a second roundtrip.
+    const stepStartTs = new Map();
+    // Emit recipe_step_done for the step result just pushed onto
+    // `stepResults`. Every loop branch (skip / budget / agent / tool)
+    // pushes exactly one result before it ends, so the last element is
+    // always the current step. `stepId` mirrors recipe_step_start's
+    // `stepIdForEmit` so live consumers can correlate start↔done — the
+    // pushed result's own id can diverge for agent steps without `into`.
+    const emitStepDone = (stepIdForEmit) => {
+        const justPushed = stepResults[stepResults.length - 1];
+        if (!justPushed)
+            return;
+        const haltReason = justPushed.haltReason;
+        emit("recipe_step_done", {
+            runSeq,
+            recipeName: recipe.name,
+            stepId: stepIdForEmit,
+            tool: justPushed.tool,
+            status: justPushed.status,
+            durationMs: justPushed.durationMs,
+            ...(justPushed.error !== undefined && { error: justPushed.error }),
+            ...(haltReason !== undefined && {
+                haltReason,
+                haltCategory: justPushed.haltCategory ?? categoriseHaltReason(haltReason),
+            }),
+            ts: Date.now(),
+        });
+    };
+    // 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
+    // run-log entry at "running" forever. On throw we capture the
+    // message into `runError` and fall through to the normal
+    // finalization path, which marks the run "error".
+    try {
+        for (const step of recipe.steps) {
+            const stepIdForEmit = step.into ?? step.agent?.into ?? `step_${stepsRun}`;
+            const stepTs = Date.now();
+            stepStartTs.set(stepIdForEmit, stepTs);
+            emit("recipe_step_start", {
+                runSeq,
+                recipeName: recipe.name,
+                stepId: stepIdForEmit,
+                tool: step.agent ? "agent" : step.tool,
+                ts: stepTs,
+            });
+            // Evaluate `when` guard before running anything. Mirrors
+            // chainedRunner.ts:248-266 — render the template, then truthy-check the
+            // result (empty string, "0", "false", "null", "undefined" are falsy).
+            // A falsy guard records the step as `skipped`, increments stepsRun, and
+            // continues — it is NOT a failure. Bridge-dev iMessage recipes rely on
+            // this to suppress the iMessage agent step when phone is empty.
+            if (typeof step.when === "string" && step.when.length > 0) {
+                const rendered = render(step.when, ctx).trim().toLowerCase();
+                const truthy = !!rendered &&
+                    rendered !== "0" &&
+                    rendered !== "false" &&
+                    rendered !== "null" &&
+                    rendered !== "undefined";
+                if (!truthy) {
+                    const skipId = step.into ?? step.agent?.into ?? `step_${stepsRun}`;
+                    stepResults.push({
+                        id: skipId,
+                        tool: step.agent ? "agent" : step.tool,
+                        status: "skipped",
+                        durationMs: 0,
+                    });
+                    stepsRun++;
+                    persistLiveStepResults();
+                    emit("recipe_step_done", {
+                        runSeq,
+                        recipeName: recipe.name,
+                        stepId: skipId,
+                        tool: step.agent ? "agent" : step.tool,
+                        status: "skipped",
+                        durationMs: 0,
+                        ts: Date.now(),
+                    });
+                    continue;
+                }
+            }
+            // Handle agent steps separately
+            if (step.agent) {
+                const agentCfg = step.agent;
+                const isJudge = agentCfg.kind === "judge";
+                // 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);
+                if (isJudge) {
+                    if (agentCfg.reviews) {
+                        renderedPrompt += buildJudgeArtefactBlock(ctx[agentCfg.reviews]);
+                    }
+                    renderedPrompt += JUDGE_PROMPT_SUFFIX;
+                }
+                const intoKey = agentCfg.into ?? "agent_output";
+                const stepId = intoKey;
+                const stepStart = Date.now();
+                let agentResult;
+                // PR2b: per-recipe token budget. Admission check before dispatch;
+                // reconcile actual consumption after. Subscription drivers
+                // (Claude CLI, provider subprocess) report `usage === undefined`
+                // — `RunBudget.reconcile` records a fail-open warning per driver
+                // per run and continues.
+                const admission = runBudget.admit();
+                if (!admission.admitted) {
+                    const reason = admission.reason ??
+                        "Run exceeded its token budget — budget_exceeded.";
                     runError = runError ?? reason;
                     stepResults.push({
                         id: stepId,
                         tool: "agent",
                         status: "error",
                         error: reason,
-                        durationMs: Date.now() - stepStart,
+                        haltReason: reason,
+                        haltCategory: "budget_exceeded",
+                        durationMs: 0,
                     });
+                    stepsRun++;
+                    persistLiveStepResults();
+                    emitStepDone(stepIdForEmit);
+                    continue;
                 }
-                else {
-                    const stripped = stripLeadingNarration(agentResult);
-                    if (!stripped.trim()) {
-                        const errMsg = `[agent step failed: ${agentCfg.driver ?? "agent"} returned only narration or whitespace — no content]`;
-                        runError = runError ?? errMsg;
+                try {
+                    const agentReturn = await _executeAgent({
+                        prompt: renderedPrompt,
+                        driver: agentCfg.driver === "api" ? "anthropic" : agentCfg.driver,
+                        model: agentCfg.model,
+                        ...(agentCfg.mcpAccess !== undefined && {
+                            mcpAccess: agentCfg.mcpAccess,
+                        }),
+                    }, buildAgentExecutorDeps(stepDeps, deps));
+                    agentResult = agentReturn.text;
+                    runBudget.reconcile(agentCfg.driver === "api"
+                        ? "anthropic"
+                        : (agentCfg.driver ?? "auto"), agentReturn.usage);
+                    // 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`.
+                    const agentSilentFail = step.silentFailDetection !== false
+                        ? detectSilentFail(agentResult)
+                        : null;
+                    if (agentResult.startsWith("[agent step failed:") ||
+                        agentSilentFail) {
+                        const reason = agentSilentFail
+                            ? `silent-fail detected (${agentSilentFail.reason}): ${agentSilentFail.matched}`
+                            : agentResult;
+                        runError = runError ?? reason;
                         stepResults.push({
                             id: stepId,
                             tool: "agent",
                             status: "error",
-                            error: errMsg,
+                            error: reason,
+                            haltReason: agentSilentFail
+                                ? `Agent step "${stepId}" returned no usable output (silent-fail: ${agentSilentFail.reason}).`
+                                : `Agent step "${stepId}" reported failure.`,
+                            haltCategory: "agent_silent_fail",
                             durationMs: Date.now() - stepStart,
                         });
                     }
                     else {
-                        // Try to parse as JSON so dot-notation ({{meeting.field}}) works
+                        const stripped = stripLeadingNarration(agentResult);
+                        if (!stripped.trim()) {
+                            const errMsg = `[agent step failed: ${agentCfg.driver ?? "agent"} returned only narration or whitespace — no content]`;
+                            runError = runError ?? errMsg;
+                            stepResults.push({
+                                id: stepId,
+                                tool: "agent",
+                                status: "error",
+                                error: errMsg,
+                                haltReason: `Agent step "${stepId}" returned only narration or whitespace — no content.`,
+                                haltCategory: "agent_narration_only",
+                                durationMs: Date.now() - stepStart,
+                            });
+                        }
+                        else {
+                            // Try to parse as JSON so dot-notation ({{meeting.field}}) works
+                            try {
+                                const jsonMatch = /```(?:json)?\s*([\s\S]*?)```/.exec(stripped) ?? [null, stripped];
+                                const parsed = sanitizeParsed(JSON.parse((jsonMatch[1] ?? "").trim()));
+                                ctx[intoKey] = parsed;
+                            }
+                            catch {
+                                ctx[intoKey] = stripped;
+                            }
+                            outputs.push(intoKey);
+                            // PR3a: parse + stash the judge verdict on the step result.
+                            // Augment-only: a `request_changes` verdict still yields
+                            // `status: "ok"`. The verdict surfaces via the runlog +
+                            // future PR3b dashboard panel, but never gates the run.
+                            const judgeVerdict = isJudge
+                                ? parseJudgeVerdict(stripped)
+                                : undefined;
+                            stepResults.push({
+                                id: stepId,
+                                tool: "agent",
+                                status: "ok",
+                                ...(judgeVerdict !== undefined && { judgeVerdict }),
+                                durationMs: Date.now() - stepStart,
+                            });
+                            // 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
+                            // steps don't see a value the recipe author rejected.
+                            if (step.expect) {
+                                const failures = await evaluateStepExpect(step.expect, ctx[intoKey]);
+                                if (failures.length > 0) {
+                                    const onFail = step.expect.on_fail ?? "halt";
+                                    const last = stepResults[stepResults.length - 1];
+                                    if (last) {
+                                        if (onFail === "halt") {
+                                            last.status = "error";
+                                            last.error = `expect_failed: ${failures.join("; ")}`;
+                                            last.haltReason = `expect_failed in step "${stepId}": ${failures.join("; ")}`;
+                                            last.haltCategory = "expect_failed";
+                                            const fbk = recipe.on_error?.fallback;
+                                            const fbkOpen = fbk === "log_only" || fbk === "deliver_original";
+                                            const failOpenAgent = step.optional === true || fbkOpen;
+                                            if (!failOpenAgent) {
+                                                runError = runError ?? last.haltReason;
+                                            }
+                                            delete ctx[intoKey];
+                                        }
+                                        else {
+                                            last.expectWarnings = failures;
+                                        }
+                                    }
+                                }
+                            }
+                        }
+                    }
+                }
+                catch (err) {
+                    const msg = err instanceof Error ? err.message : String(err);
+                    runError = runError ?? `agent step "${stepId}" failed: ${msg}`;
+                    stepResults.push({
+                        id: stepId,
+                        tool: "agent",
+                        status: "error",
+                        error: msg,
+                        haltReason: `Agent step "${stepId}" threw before completing: ${msg}`,
+                        haltCategory: "agent_threw",
+                        durationMs: Date.now() - stepStart,
+                    });
+                }
+                stepsRun++;
+                persistLiveStepResults();
+                emitStepDone(stepIdForEmit);
+                continue;
+            }
+            const stepStart = Date.now();
+            const stepId = step.into ?? `step_${stepsRun}`;
+            // Resolve retry policy: step-level overrides recipe-level.
+            const retryCount = step.retry ?? recipe.on_error?.retry ?? 0;
+            const retryDelayMs = step.retryDelay ?? recipe.on_error?.retryDelay ?? 1000;
+            let result = null;
+            let stepError;
+            let thrownError;
+            let thrownErrorCode;
+            for (let attempt = 0; attempt <= retryCount; attempt++) {
+                if (attempt > 0) {
+                    await new Promise((r) => setTimeout(r, retryDelayMs));
+                }
+                stepError = undefined;
+                thrownError = undefined;
+                thrownErrorCode = undefined;
+                try {
+                    // Slice (sandbox-alternative): per-step wall-clock timeout via
+                    // Promise.race. The underlying tool keeps running in the
+                    // background — this is a halt signal for the runner, not a
+                    // process kill. The thrown error carries a `step_timeout`
+                    // prefix so categoriseHaltReason maps it correctly.
+                    const timeoutMs = typeof step.timeout_ms === "number" && step.timeout_ms > 0
+                        ? step.timeout_ms
+                        : 0;
+                    if (timeoutMs > 0) {
+                        let timer;
+                        const timeoutPromise = new Promise((_, reject) => {
+                            timer = setTimeout(() => {
+                                reject(new Error(`step_timeout: exceeded ${timeoutMs}ms in step "${step.into ?? step.tool ?? "?"}"`));
+                            }, timeoutMs);
+                        });
+                        try {
+                            result = await Promise.race([
+                                executeStep(step, ctx, stepDeps),
+                                timeoutPromise,
+                            ]);
+                        }
+                        finally {
+                            if (timer)
+                                clearTimeout(timer);
+                        }
+                    }
+                    else {
+                        result = await executeStep(step, ctx, stepDeps);
+                    }
+                    // Detect tool-level errors reported as JSON {ok: false, error: ...}
+                    if (result !== null) {
                         try {
-                            const jsonMatch = /```(?:json)?\s*([\s\S]*?)```/.exec(stripped) ?? [null, stripped];
-                            const parsed = JSON.parse((jsonMatch[1] ?? "").trim());
-                            ctx[intoKey] = parsed;
+                            const parsed = JSON.parse(result);
+                            if (parsed.ok === false && typeof parsed.error === "string") {
+                                stepError = parsed.error;
+                            }
                         }
                         catch {
-                            ctx[intoKey] = stripped;
+                            /* non-JSON result is fine */
+                        }
+                    }
+                    // Silent-fail detection: tools that return string placeholders
+                    // (`(git branches unavailable)`, `[agent step skipped: ...]`)
+                    // or empty list-tool error shapes (`{count:0,error:"..."}`)
+                    // succeed with bad data — flag them as `error` so the runner
+                    // doesn't quietly hand garbage to a downstream agent. Per-step
+                    // opt-out via `silentFailDetection: false`.
+                    if (!stepError &&
+                        result !== null &&
+                        step.silentFailDetection !== false) {
+                        const detected = detectSilentFail(result);
+                        if (detected) {
+                            stepError = `silent-fail detected (${detected.reason}): ${detected.matched}`;
                         }
-                        outputs.push(intoKey);
-                        stepResults.push({
-                            id: stepId,
-                            tool: "agent",
-                            status: "ok",
-                            durationMs: Date.now() - stepStart,
-                        });
                     }
                 }
+                catch (err) {
+                    thrownError = err instanceof Error ? err.message : String(err);
+                    // Preserve structured error codes (e.g. recipe_path_jail_escape)
+                    // so callers and tests can branch on `err.code` per R2 M-4
+                    // without scraping the message string.
+                    const code = err?.code;
+                    if (typeof code === "string")
+                        thrownErrorCode = code;
+                    result = null;
+                }
+                if (!stepError && !thrownError)
+                    break;
             }
-            catch (err) {
-                const msg = err instanceof Error ? err.message : String(err);
-                runError = runError ?? `agent step "${stepId}" failed: ${msg}`;
+            // Recipe-level fallback: log_only / deliver_original treat step failure
+            // as non-fatal (fail-open) — same semantics as step-level optional: true.
+            const fallback = recipe.on_error?.fallback;
+            const fallbackFailOpen = fallback === "log_only" || fallback === "deliver_original";
+            const failOpen = step.optional === true || fallbackFailOpen;
+            if (thrownError) {
+                const retryNote = retryCount > 0 ? ` after ${retryCount + 1} attempts` : "";
                 stepResults.push({
                     id: stepId,
-                    tool: "agent",
+                    tool: step.tool,
                     status: "error",
-                    error: msg,
+                    error: thrownError,
+                    ...(thrownErrorCode ? { errorCode: thrownErrorCode } : {}),
+                    haltReason: `Tool "${step.tool ?? "?"}" in step "${stepId}" threw${retryNote}: ${thrownError}`,
+                    haltCategory: thrownErrorCode === "kill_switch_blocked"
+                        ? "kill_switch"
+                        : "tool_threw",
                     durationMs: Date.now() - stepStart,
                 });
+                if (!failOpen) {
+                    runError = runError ?? `${step.tool} failed: ${thrownError}`;
+                }
+                else if (fallbackFailOpen && !step.optional) {
+                    console.warn(`step ${stepId} failed but on_error.fallback=${fallback} — treating as non-fatal: ${thrownError}`);
+                }
             }
-            stepsRun++;
-            continue;
-        }
-        const stepStart = Date.now();
-        const stepId = step.into ?? `step_${stepsRun}`;
-        // Resolve retry policy: step-level overrides recipe-level.
-        const retryCount = step.retry ?? recipe.on_error?.retry ?? 0;
-        const retryDelayMs = step.retryDelay ?? recipe.on_error?.retryDelay ?? 1000;
-        let result = null;
-        let stepError;
-        let thrownError;
-        let thrownErrorCode;
-        for (let attempt = 0; attempt <= retryCount; attempt++) {
-            if (attempt > 0) {
-                await new Promise((r) => setTimeout(r, retryDelayMs));
+            else {
+                const finalStatus = result === null ? "skipped" : stepError ? "error" : "ok";
+                const retryNote = retryCount > 0 ? ` after ${retryCount + 1} attempts` : "";
+                stepResults.push({
+                    id: stepId,
+                    tool: step.tool,
+                    status: finalStatus,
+                    error: stepError,
+                    ...(finalStatus === "error" && stepError
+                        ? {
+                            haltReason: `Tool "${step.tool ?? "?"}" in step "${stepId}" reported an error${retryNote}: ${stepError}`,
+                            haltCategory: "tool_error",
+                        }
+                        : {}),
+                    durationMs: Date.now() - stepStart,
+                });
+                if (stepError) {
+                    if (!failOpen) {
+                        runError = runError ?? `${step.tool} failed: ${stepError}`;
+                    }
+                    else if (fallbackFailOpen && !step.optional) {
+                        console.warn(`step ${stepId} failed but on_error.fallback=${fallback} — treating as non-fatal: ${stepError}`);
+                    }
+                }
             }
-            stepError = undefined;
-            thrownError = undefined;
-            thrownErrorCode = undefined;
-            try {
-                result = await executeStep(step, ctx, stepDeps);
-                // Detect tool-level errors reported as JSON {ok: false, error: ...}
-                if (result !== null) {
+            stepsRun++;
+            if (result !== null) {
+                // Apply transform if present — render template with $result injected
+                if (step.transform) {
                     try {
-                        const parsed = JSON.parse(result);
-                        if (parsed.ok === false && typeof parsed.error === "string") {
-                            stepError = parsed.error;
-                        }
+                        result = render(step.transform, { ...ctx, $result: result });
                     }
-                    catch {
-                        /* non-JSON result is fine */
+                    catch (err) {
+                        // warn but fall through with original result
+                        console.warn(`transform failed for step ${step.into ?? step.tool ?? "?"}: ${err}`);
                     }
                 }
-                // Silent-fail detection: tools that return string placeholders
-                // (`(git branches unavailable)`, `[agent step skipped: ...]`)
-                // or empty list-tool error shapes (`{count:0,error:"..."}`)
-                // succeed with bad data — flag them as `error` so the runner
-                // doesn't quietly hand garbage to a downstream agent. Per-step
-                // opt-out via `silentFailDetection: false`.
-                if (!stepError &&
-                    result !== null &&
-                    step.silentFailDetection !== false) {
-                    const detected = detectSilentFail(result);
-                    if (detected) {
-                        stepError = `silent-fail detected (${detected.reason}): ${detected.matched}`;
+                // Slice 2 — per-step expect eval. Runs on the post-transform value
+                // (what would land in ctx) and only when the step otherwise succeeded.
+                // Halt failure flips the just-pushed result to error and suppresses
+                // the ctx commit by nulling `result` so the downstream `if (step.into)`
+                // block skips. Composes with `optional: true` / `on_error.fallback`.
+                if (step.expect && !thrownError && !stepError && result !== null) {
+                    const failures = await evaluateStepExpect(step.expect, result);
+                    if (failures.length > 0) {
+                        const onFail = step.expect.on_fail ?? "halt";
+                        const last = stepResults[stepResults.length - 1];
+                        if (last) {
+                            if (onFail === "halt") {
+                                last.status = "error";
+                                last.error = `expect_failed: ${failures.join("; ")}`;
+                                last.haltReason = `expect_failed in step "${stepId}": ${failures.join("; ")}`;
+                                last.haltCategory = "expect_failed";
+                                if (!failOpen) {
+                                    runError = runError ?? last.haltReason;
+                                }
+                                result = null;
+                            }
+                            else {
+                                last.expectWarnings = failures;
+                            }
+                        }
                     }
                 }
-            }
-            catch (err) {
-                thrownError = err instanceof Error ? err.message : String(err);
-                // Preserve structured error codes (e.g. recipe_path_jail_escape)
-                // so callers and tests can branch on `err.code` per R2 M-4
-                // without scraping the message string.
-                const code = err?.code;
-                if (typeof code === "string")
-                    thrownErrorCode = code;
-                result = null;
-            }
-            if (!stepError && !thrownError)
-                break;
-        }
-        // Recipe-level fallback: log_only / deliver_original treat step failure
-        // as non-fatal (fail-open) — same semantics as step-level optional: true.
-        const fallback = recipe.on_error?.fallback;
-        const fallbackFailOpen = fallback === "log_only" || fallback === "deliver_original";
-        const failOpen = step.optional === true || fallbackFailOpen;
-        if (thrownError) {
-            stepResults.push({
-                id: stepId,
-                tool: step.tool,
-                status: "error",
-                error: thrownError,
-                ...(thrownErrorCode ? { errorCode: thrownErrorCode } : {}),
-                durationMs: Date.now() - stepStart,
-            });
-            if (!failOpen) {
-                runError = runError ?? `${step.tool} failed: ${thrownError}`;
-            }
-            else if (fallbackFailOpen && !step.optional) {
-                console.warn(`step ${stepId} failed but on_error.fallback=${fallback} — treating as non-fatal: ${thrownError}`);
-            }
-        }
-        else {
-            stepResults.push({
-                id: stepId,
-                tool: step.tool,
-                status: result === null ? "skipped" : stepError ? "error" : "ok",
-                error: stepError,
-                durationMs: Date.now() - stepStart,
-            });
-            if (stepError) {
-                if (!failOpen) {
-                    runError = runError ?? `${step.tool} failed: ${stepError}`;
+                if (result !== null && step.into) {
+                    ctx[step.into] = result;
+                    if (step.tool) {
+                        applyToolOutputContext(step.tool, step.into, result, ctx);
+                    }
                 }
-                else if (fallbackFailOpen && !step.optional) {
-                    console.warn(`step ${stepId} failed but on_error.fallback=${fallback} — treating as non-fatal: ${stepError}`);
+                if (step.tool === "file.write" || step.tool === "file.append") {
+                    // R2 C-1 / F-02: re-validate the rendered path against the jail so a
+                    // template substitution that survived earlier checks (e.g. via a
+                    // chained sub-recipe deps override) cannot smuggle an out-of-jail
+                    // path into the run log / dashboard outputs list.
+                    const renderedPath = render(step.path, ctx);
+                    outputs.push(resolveRecipePath(renderedPath, {
+                        workspace: stepDeps.workdir,
+                        write: true,
+                    }));
                 }
             }
+            persistLiveStepResults();
+            emitStepDone(stepIdForEmit);
         }
-        stepsRun++;
-        if (result !== null) {
-            // Apply transform if present — render template with $result injected
-            if (step.transform) {
-                try {
-                    result = render(step.transform, { ...ctx, $result: result });
-                }
-                catch (err) {
-                    // warn but fall through with original result
-                    console.warn(`transform failed for step ${step.into ?? step.tool ?? "?"}: ${err}`);
-                }
-            }
-            if (step.into) {
-                ctx[step.into] = result;
-                if (step.tool) {
-                    applyToolOutputContext(step.tool, step.into, result, ctx);
-                }
-            }
-            if (step.tool === "file.write" || step.tool === "file.append") {
-                // R2 C-1 / F-02: re-validate the rendered path against the jail so a
-                // template substitution that survived earlier checks (e.g. via a
-                // chained sub-recipe deps override) cannot smuggle an out-of-jail
-                // path into the run log / dashboard outputs list.
-                const renderedPath = render(step.path, ctx);
-                outputs.push(resolveRecipePath(renderedPath, {
-                    workspace: stepDeps.workdir,
-                    write: true,
-                }));
-            }
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        runError = runError ?? `recipe run aborted: ${msg}`;
+    }
+    // Evaluate expect block before persisting so failures are stored in the
+    // run log. Guarded: a throw here must not skip finalization and strand
+    // the run at "running".
+    let assertionFailures = [];
+    if (recipe.expect) {
+        try {
+            assertionFailures = evaluateExpect({ stepsRun, outputs, context: ctx, errorMessage: runError }, recipe.expect);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            runError = runError ?? `expect evaluation failed: ${msg}`;
         }
     }
-    // Evaluate expect block before persisting so failures are stored in the run log
-    const assertionFailures = recipe.expect
-        ? evaluateExpect({ stepsRun, outputs, context: ctx, errorMessage: runError }, recipe.expect)
-        : [];
     // Write to RecipeRunLog so the dashboard Runs page shows this execution.
     // Bridge path: completeRun on the running entry opened above (live-tail).
     // CLI path: construct a local log + appendDirect (no live-tail).
@@ -478,6 +995,9 @@ export async function runYamlRecipe(recipe, deps = {}, seedContext = {}) {
                 tool: s.tool,
                 status: s.status,
                 error: s.error,
+                ...(s.haltReason ? { haltReason: s.haltReason } : {}),
+                ...(s.haltCategory ? { haltCategory: s.haltCategory } : {}),
+                ...(s.judgeVerdict ? { judgeVerdict: s.judgeVerdict } : {}),
                 durationMs: s.durationMs,
             }));
             if (deps.runLog && runSeq !== undefined) {
@@ -489,6 +1009,23 @@ export async function runYamlRecipe(recipe, deps = {}, seedContext = {}) {
                     outputTail,
                     ...(runError !== undefined && { errorMessage: runError }),
                     ...(assertionFailures.length > 0 ? { assertionFailures } : {}),
+                    ...(inboxOutputs.length > 0 ? { inboxOutputs } : {}),
+                });
+                emit("recipe_done", {
+                    runSeq,
+                    recipeName: recipe.name,
+                    status: runError ? "error" : "done",
+                    durationMs: doneAt - recipeStartedAt,
+                    stepCount: finalStepResults.length,
+                    // A `done` run can still carry step errors — the runner
+                    // continues past a non-fatal step failure. Surface it so
+                    // live consumers can show "completed with errors".
+                    hadStepErrors: finalStepResults.some((s) => s.status === "error"),
+                    ...(runError !== undefined && { errorMessage: runError }),
+                    ...(assertionFailures.length > 0 && {
+                        assertionFailureCount: assertionFailures.length,
+                    }),
+                    ts: doneAt,
                 });
             }
             else {
@@ -509,6 +1046,7 @@ export async function runYamlRecipe(recipe, deps = {}, seedContext = {}) {
                     errorMessage: runError,
                     stepResults: finalStepResults,
                     ...(assertionFailures.length > 0 ? { assertionFailures } : {}),
+                    ...(inboxOutputs.length > 0 ? { inboxOutputs } : {}),
                 });
             }
         }
@@ -516,13 +1054,13 @@ export async function runYamlRecipe(recipe, deps = {}, seedContext = {}) {
             // Non-fatal — run log write failure should never break recipe execution
         }
     }
-    // Notify via Slack if any step failed
-    if (runError && !stepDeps.testMode) {
+    // Notify via Slack if any step failed and on_error.notify is not explicitly disabled
+    if (runError && !stepDeps.testMode && recipe.on_error?.notify !== false) {
         try {
             const { isConnected, postMessage } = await import("../connectors/slack.js");
             if (isConnected()) {
-                // Read notification channel from ~/.patchwork/config.json, fallback to first available
-                let notifyChannel = "all-massappealdesigns";
+                // Read notification channel from ~/.patchwork/config.json
+                let notifyChannel = "";
                 try {
                     const cfgPath = path.join(os.homedir(), ".patchwork", "config.json");
                     const cfg = JSON.parse(readFileSync(cfgPath, "utf-8"));
@@ -532,13 +1070,15 @@ export async function runYamlRecipe(recipe, deps = {}, seedContext = {}) {
                     }
                 }
                 catch {
-                    /* use default */
+                    /* config unreadable — skip notification */
+                }
+                if (notifyChannel) {
+                    const failedSteps = stepResults
+                        .filter((s) => s.status === "error")
+                        .map((s) => `• ${s.tool ?? s.id}: ${s.error ?? "unknown error"}`)
+                        .join("\n");
+                    await postMessage(notifyChannel, `⚠️ *Recipe failed: ${recipe.name}*\n\n${failedSteps}\n\n_${new Date().toISOString()}_`);
                 }
-                const failedSteps = stepResults
-                    .filter((s) => s.status === "error")
-                    .map((s) => `• ${s.tool ?? s.id}: ${s.error ?? "unknown error"}`)
-                    .join("\n");
-                await postMessage(notifyChannel, `⚠️ *Recipe failed: ${recipe.name}*\n\n${failedSteps}\n\n_${new Date().toISOString()}_`);
             }
         }
         catch {
@@ -563,11 +1103,19 @@ export async function executeStep(step, ctx, deps) {
     // Check if tool is registered in the new registry
     if (hasTool(toolId)) {
         const tool = getTool(toolId);
-        // Build params with template rendering for string values
+        // Build params with template rendering for string values.
+        // `do` is left raw: it carries a nested sub-step template (used by
+        // `fan_out`) whose `{{item.*}}` placeholders must be rendered per-iter
+        // with the loop variable in scope, not pre-rendered against the outer
+        // ctx (which would resolve them to empty strings).
         const params = {};
         for (const [key, value] of Object.entries(step)) {
             if (key === "tool" || key === "agent" || key === "into")
                 continue;
+            if (key === "do") {
+                params[key] = value;
+                continue;
+            }
             params[key] = deepRender(value, ctx);
         }
         // Check if mock connector is available for this tool
@@ -609,7 +1157,7 @@ export function render(template, ctx) {
                 return "";
             if (typeof val === "string") {
                 try {
-                    val = JSON.parse(val);
+                    val = sanitizeParsed(JSON.parse(val));
                 }
                 catch {
                     return "";
@@ -749,7 +1297,7 @@ export function defaultGitStaleBranches(days, workdir) {
     }
 }
 /** Resolve all RunnerDeps to concrete StepDeps with production defaults filled in. */
-function resolveStepDeps(deps) {
+function resolveStepDeps(deps, scope) {
     const workdir = deps.workdir ?? process.cwd();
     // Defense-in-depth: even if a file.* tool somehow forgets to call
     // resolveRecipePath in its execute(), the default StepDeps file ops will
@@ -807,19 +1355,44 @@ function resolveStepDeps(deps) {
             }),
         logDir: deps.logDir,
         testMode: deps.testMode ?? false,
+        // PR5a/b: per-attempt idempotency ledger. Disk-backed when
+        // `ledgerDir` + `manualRunId` + recipe name are all available so a
+        // retry of the same logical attempt re-uses prior records (resume
+        // semantics). Falls back to pure in-memory dedup otherwise.
+        writeEffectLedger: deps.ledgerDir && deps.manualRunId && scope?.recipeName
+            ? new WriteEffectLedger({
+                dir: deps.ledgerDir,
+                // Hash both fields together — `${recipeName}:${manualRunId}`
+                // is ambiguous when recipe names contain colons (which
+                // RecipeRunLog.parseTrigger explicitly allows).
+                scopeKey: deriveScopeKey(scope.recipeName, assertValidManualRunId(deps.manualRunId)),
+            })
+            : new WriteEffectLedger(),
     };
 }
+/**
+ * Normalise the union return of a RunnerDeps caller into an `AgentResult`.
+ * Test mocks / CLI overrides typically return a plain string; bridge
+ * wrappers + real adapter paths return `{text, usage}` so PR2b's token
+ * budget enforcer can read usage. Both shapes converge here.
+ */
+function toAgentResult(v) {
+    return typeof v === "string" ? { text: v } : v;
+}
 function buildAgentExecutorDeps(stepDeps, runnerDeps, claudeCodeFnOverride) {
     const claudeCliFn = claudeCodeFnOverride ?? stepDeps.claudeCodeFn;
     return {
-        anthropicFn: (prompt, model) => stepDeps.claudeFn(prompt, model),
-        providerDriverFn: (driver, prompt, model) => stepDeps.providerDriverFn(driver, prompt, model),
-        claudeCliFn: (prompt) => claudeCliFn(prompt),
-        localFn: (prompt, model) => stepDeps.localFn(prompt, model),
+        anthropicFn: async (prompt, model) => toAgentResult(await stepDeps.claudeFn(prompt, model)),
+        providerDriverFn: async (driver, prompt, model) => toAgentResult(await stepDeps.providerDriverFn(driver, prompt, model)),
+        claudeCliFn: async (prompt, opts) => toAgentResult(await claudeCliFn(prompt, opts)),
+        localFn: async (prompt, model) => toAgentResult(await stepDeps.localFn(prompt, model)),
         probeClaudeCli: () => {
             if (runnerDeps.claudeFn !== undefined)
                 return false;
-            const probe = spawnSync("claude", ["--version"], {
+            // Use the same resolution as defaultClaudeCodeFn so the auto-detect
+            // branch in agentExecutor.ts doesn't probe "claude" via PATH and
+            // then later fail to spawn the configured override (or vice versa).
+            const probe = spawnSync(resolveClaudeBinary(), ["--version"], {
                 encoding: "utf-8",
                 timeout: 5000,
             });
@@ -838,21 +1411,78 @@ function buildAgentExecutorDeps(stepDeps, runnerDeps, claudeCodeFnOverride) {
         },
     };
 }
-function defaultClaudeCodeFn(prompt) {
+/**
+ * Resolve the `claude` binary path with override precedence:
+ *   1. PATCHWORK_CLAUDE_BINARY env var (set by the bridge LaunchAgent
+ *      or any wrapper script)
+ *   2. `~/.patchwork/config.json` `claudeBinary` field
+ *   3. plain `"claude"` (PATH lookup — pre-existing default)
+ *
+ * Resolved per-call, not memoised, so config edits + env-var changes
+ * take effect on the next agent step without a bridge restart.
+ */
+export function resolveClaudeBinary() {
+    const envOverride = process.env.PATCHWORK_CLAUDE_BINARY;
+    if (envOverride && envOverride.length > 0)
+        return ensureCmdShim(envOverride);
+    try {
+        const cfg = loadPatchworkConfigSync();
+        if (cfg.claudeBinary && cfg.claudeBinary.length > 0)
+            return ensureCmdShim(cfg.claudeBinary);
+    }
+    catch {
+        // ignore — fall through to the "claude" default
+    }
+    return ensureCmdShim("claude");
+}
+export function defaultClaudeCodeFn(prompt, opts) {
+    const binary = resolveClaudeBinary();
+    // Resolve a workspace cwd so the spawned `claude -p` doesn't inherit the
+    // bridge LaunchAgent's `$HOME` (P2 from the 2026-05-20 research run).
+    // When nothing resolves, surface a typed reason instead of silently
+    // shelling out from the wrong directory.
+    const workspace = resolveWorkspaceRoot();
+    if (!workspace) {
+        return Promise.resolve(`[agent step failed: recipe_no_workspace — no .git ancestor of "${process.cwd()}" and PATCHWORK_WORKSPACE not set. Set PATCHWORK_WORKSPACE in the bridge environment or add a 'workspace:' field to the recipe.]`);
+    }
+    // mcpAccess is plumbed through executeAgent → buildChainedDeps → here.
+    // The default fn has no bridge MCP endpoint resolver (SubprocessDriver
+    // owns that). Surface mcpAccess=true as a typed error rather than
+    // silently falling back to no-MCP spawn — the recipe explicitly asked
+    // for bridge tools and should be routed through SubprocessDriver via
+    // the runtime injector instead.
+    if (opts?.mcpAccess === true) {
+        return Promise.resolve("[agent step failed: recipe_mcp_unsupported — defaultClaudeCodeFn does not support mcpAccess:true; route via SubprocessDriver or unset the mcpAccess flag on this step]");
+    }
     try {
-        const result = spawnSync("claude", [
+        const result = spawnSync(binary, [
             "-p",
             prompt,
+            // --strict-mcp-config: never load ~/.claude.json or .mcp.json. Recipes
+            // are sandboxed by default (mcpAccess defaults to false above). This
+            // also prevents accidental session attachment when the parent process
+            // had a bridge MCP entry in ~/.claude.json.
+            "--strict-mcp-config",
             "--system-prompt",
             "You are a helpful assistant processing a recipe task. Use ONLY the data explicitly provided in the user message — treat it as ground truth. Do not call tools to look up git history, emails, or any other information; all necessary data is already included.",
             "--no-session-persistence",
         ], {
+            cwd: workspace.path,
+            // sanitizeEnv strips CLAUDECODE / CLAUDE_CODE_* / MCP_* from the
+            // child so the spawn doesn't re-authenticate as, or nest under,
+            // the parent Claude Code session. Mirrors SubprocessDriver.run
+            // hygiene. Preserves CLAUDE_CODE_OAUTH_TOKEN (subscription auth).
+            env: sanitizeEnv(process.env),
             encoding: "utf-8",
-            timeout: 120_000,
+            timeout: 600_000,
             maxBuffer: 10 * 1024 * 1024,
         });
         if (result.error) {
-            return Promise.resolve("[agent step failed: claude CLI not found — install Claude Code or set ANTHROPIC_API_KEY]");
+            // Surface the configured binary path in the error so users diagnosing
+            // ENOENT can see whether resolveClaudeBinary picked up their override.
+            // Hint includes the env var + config field names so the fix is one
+            // click away.
+            return Promise.resolve(`[agent step failed: claude CLI not found at "${binary}" — install Claude Code, set PATCHWORK_CLAUDE_BINARY, or set ANTHROPIC_API_KEY]`);
         }
         if (result.status !== 0) {
             return Promise.resolve(`[agent step failed: claude exited ${result.status}: ${result.stderr?.slice(0, 200) ?? ""}]`);
@@ -881,10 +1511,11 @@ function makeProviderDriverFn() {
             const timeoutMs = 300_000;
             const startupTimeoutMs = 30_000;
             const timeout = setTimeout(() => controller.abort(), timeoutMs);
+            const resolvedWorkspace = process.cwd();
             try {
                 const result = await driver.run({
                     prompt,
-                    workspace: process.cwd(),
+                    workspace: resolvedWorkspace,
                     timeoutMs,
                     startupTimeoutMs,
                     signal: controller.signal,
@@ -911,7 +1542,7 @@ function makeProviderDriverFn() {
 async function defaultClaudeFn(prompt, model) {
     const apiKey = process.env.ANTHROPIC_API_KEY;
     if (!apiKey)
-        return "[agent step skipped: ANTHROPIC_API_KEY not set]";
+        return { text: "[agent step skipped: ANTHROPIC_API_KEY not set]" };
     try {
         const res = await fetch("https://api.anthropic.com/v1/messages", {
             method: "POST",
@@ -933,13 +1564,25 @@ async function defaultClaudeFn(prompt, model) {
         });
         if (!res.ok) {
             const text = await res.text().catch(() => res.statusText);
-            return `[agent step failed: ${text}]`;
+            return { text: `[agent step failed: ${text}]` };
         }
+        // PR2a: forward Anthropic API token counts so PR2b's RunBudget can
+        // reconcile actual consumption. Optional both upstream (older API
+        // versions) and downstream (subscription/CLI driver returns
+        // undefined here).
         const data = (await res.json());
-        return data.content?.[0]?.text ?? "[agent step failed: empty response]";
+        const text = data.content?.[0]?.text ?? "[agent step failed: empty response]";
+        const inputTokens = data.usage?.input_tokens;
+        const outputTokens = data.usage?.output_tokens;
+        if (typeof inputTokens === "number" && typeof outputTokens === "number") {
+            return { text, usage: { inputTokens, outputTokens } };
+        }
+        return { text };
     }
     catch (err) {
-        return `[agent step failed: ${err instanceof Error ? err.message : String(err)}]`;
+        return {
+            text: `[agent step failed: ${err instanceof Error ? err.message : String(err)}]`,
+        };
     }
 }
 async function defaultLocalFn(prompt, model) {
@@ -955,10 +1598,18 @@ async function defaultLocalFn(prompt, model) {
             systemPrompt: "",
             messages: [{ role: "user", content: prompt }],
         });
-        return result.text ?? "[agent step failed: empty response from local LLM]";
+        const text = result.text ?? "[agent step failed: empty response from local LLM]";
+        // PR2a: local adapters carry usage when the backing API (Ollama / LM
+        // Studio) surfaces it; otherwise undefined.
+        if (result.usage) {
+            return { text, usage: result.usage };
+        }
+        return { text };
     }
     catch (err) {
-        return `[agent step failed: ${err instanceof Error ? err.message : String(err)}]`;
+        return {
+            text: `[agent step failed: ${err instanceof Error ? err.message : String(err)}]`,
+        };
     }
 }
 /**
@@ -1014,7 +1665,18 @@ export function buildChainedDeps(runnerDeps, claudeCodeFnOverride) {
         const result = await executeStep(step, {}, stepDeps);
         return result ?? "";
     };
-    const executeAgent = async (prompt, model, driver) => _executeAgent({ prompt, model, driver }, buildAgentExecutorDeps(stepDeps, runnerDeps, claudeCodeFnOverride));
+    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({
+            prompt,
+            model,
+            driver,
+            ...(mcpAccess !== undefined && { mcpAccess }),
+        }, buildAgentExecutorDeps(stepDeps, runnerDeps, claudeCodeFnOverride));
+        return result.text;
+    };
     // ---------------------------------------------------------------------
     // BEGIN A-PR2 EDIT BLOCK — `loadNestedRecipe` jail (dogfood F-04).
     //
@@ -1131,7 +1793,7 @@ export async function dispatchRecipe(recipe, deps, seedContext = {}) {
                 TIME: now.toTimeString().slice(0, 5),
                 ...seedContext,
             },
-            maxConcurrency: chainedRecipe.maxConcurrency ?? 4,
+            maxConcurrency: Math.max(1, chainedRecipe.maxConcurrency ?? 4),
             maxDepth: chainedRecipe.maxDepth ?? 3,
             dryRun: deps.chainedOptions?.dryRun ?? false,
             sourcePath: deps.chainedOptions?.sourcePath,
@@ -1148,11 +1810,17 @@ export async function dispatchRecipe(recipe, deps, seedContext = {}) {
         }
         return runChainedRecipe(chainedRecipe, options, deps.chainedDeps);
     }
-    // For non-chained recipes, lift `runLog` from chainedOptions onto the
-    // RunnerDeps so runYamlRecipe gets the bridge's singleton too.
-    return runYamlRecipe(recipe, deps.chainedOptions?.runLog
-        ? { ...deps, runLog: deps.chainedOptions.runLog }
-        : deps, seedContext);
+    // For non-chained recipes, lift `runLog` AND `activityLog` from
+    // chainedOptions onto the RunnerDeps so runYamlRecipe gets the
+    // bridge's singletons too. The activityLog is what powers
+    // recipe_started / recipe_step_start / recipe_step_done /
+    // recipe_done SSE emission to dashboard subscribers.
+    const lifted = { ...deps };
+    if (deps.chainedOptions?.runLog)
+        lifted.runLog = deps.chainedOptions.runLog;
+    if (deps.chainedOptions?.activityLog)
+        lifted.activityLog = deps.chainedOptions.activityLog;
+    return runYamlRecipe(recipe, lifted, seedContext);
 }
 /** List all YAML recipes in a directory. Returns names. */
 export function listYamlRecipes(recipesDir) {