patchwork-os 0.2.0-beta.5.canary.13 → 0.2.0-beta.5.canary.131

package/dist/recipes/yamlRunner.js

@@ -42,6 +42,7 @@ import { findYamlRecipePath } from "../recipesHttp.js";
 import { sanitizeParsedJson as sanitizeParsed } from "../sanitizeParsedJson.js";
 import { ensureCmdShim } from "../winShim.js";
 import { executeAgent as _executeAgent, } from "./agentExecutor.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";
@@ -127,6 +128,26 @@ export function evaluateExpect(result, expect) {
     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()));
@@ -238,6 +259,84 @@ export async function runYamlRecipe(recipe, deps = {}, seedContext = {}) {
         ...seedContext,
     };
     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);
@@ -272,6 +371,30 @@ export async function runYamlRecipe(recipe, deps = {}, seedContext = {}) {
     const stepResults = [];
     let stepsRun = 0;
     let runError;
+    // 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
@@ -288,305 +411,380 @@ export async function runYamlRecipe(recipe, deps = {}, seedContext = {}) {
             /* live-tail is best-effort; never break a recipe run for it */
         }
     };
-    for (const step of recipe.steps) {
-        // 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();
-                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]);
+    // 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: 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;
                 }
-                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,
-                    haltReason: reason,
-                    durationMs: 0,
-                });
-                stepsRun++;
-                persistLiveStepResults();
-                continue;
-            }
-            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;
+            // 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,
-                        haltReason: agentSilentFail
-                            ? `Agent step "${stepId}" returned no usable output (silent-fail: ${agentSilentFail.reason}).`
-                            : `Agent step "${stepId}" reported failure.`,
-                        durationMs: Date.now() - stepStart,
+                        haltReason: reason,
+                        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,
-                            haltReason: `Agent step "${stepId}" returned only narration or whitespace — no content.`,
+                            error: reason,
+                            haltReason: agentSilentFail
+                                ? `Agent step "${stepId}" returned no usable output (silent-fail: ${agentSilentFail.reason}).`
+                                : `Agent step "${stepId}" reported failure.`,
                             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.`,
+                                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,
+                            });
+                        }
+                    }
+                }
+                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}`,
+                        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 {
+                    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 = sanitizeParsed(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 */
                         }
-                        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,
-                        });
                     }
+                    // 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}`;
+                        }
+                    }
+                }
+                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,
-                    haltReason: `Agent step "${stepId}" threw before completing: ${msg}`,
+                    error: thrownError,
+                    ...(thrownErrorCode ? { errorCode: thrownErrorCode } : {}),
+                    haltReason: `Tool "${step.tool ?? "?"}" in step "${stepId}" threw${retryNote}: ${thrownError}`,
                     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++;
-            persistLiveStepResults();
-            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 {
-                result = await executeStep(step, ctx, stepDeps);
-                // Detect tool-level errors reported as JSON {ok: false, error: ...}
-                if (result !== null) {
-                    try {
-                        const parsed = JSON.parse(result);
-                        if (parsed.ok === false && typeof parsed.error === "string") {
-                            stepError = parsed.error;
+            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}`,
                         }
+                        : {}),
+                    durationMs: Date.now() - stepStart,
+                });
+                if (stepError) {
+                    if (!failOpen) {
+                        runError = runError ?? `${step.tool} failed: ${stepError}`;
                     }
-                    catch {
-                        /* non-JSON result is fine */
+                    else if (fallbackFailOpen && !step.optional) {
+                        console.warn(`step ${stepId} failed but on_error.fallback=${fallback} — treating as non-fatal: ${stepError}`);
                     }
                 }
-                // 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}`;
+            }
+            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}`);
                     }
                 }
-            }
-            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) {
-            const retryNote = retryCount > 0 ? ` after ${retryCount + 1} attempts` : "";
-            stepResults.push({
-                id: stepId,
-                tool: step.tool,
-                status: "error",
-                error: thrownError,
-                ...(thrownErrorCode ? { errorCode: thrownErrorCode } : {}),
-                haltReason: `Tool "${step.tool ?? "?"}" in step "${stepId}" threw${retryNote}: ${thrownError}`,
-                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 {
-            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}`,
+                if (step.into) {
+                    ctx[step.into] = result;
+                    if (step.tool) {
+                        applyToolOutputContext(step.tool, step.into, result, ctx);
                     }
-                    : {}),
-                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}`);
+                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}`;
         }
-        persistLiveStepResults();
     }
-    // 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).
@@ -615,6 +813,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 {
@@ -635,6 +850,7 @@ export async function runYamlRecipe(recipe, deps = {}, seedContext = {}) {
                     errorMessage: runError,
                     stepResults: finalStepResults,
                     ...(assertionFailures.length > 0 ? { assertionFailures } : {}),
+                    ...(inboxOutputs.length > 0 ? { inboxOutputs } : {}),
                 });
             }
         }
@@ -1359,11 +1575,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) {