patchwork-os 0.2.0-alpha.8 → 0.2.0-beta.0

package/dist/recipes/yamlRunner.js

@@ -24,17 +24,110 @@ import { spawnSync } from "node:child_process";
 import { appendFileSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync, } from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { fileURLToPath } from "node:url";
 import { parse as parseYaml } from "yaml";
+import { captureFixture } from "../connectors/fixtureRecorder.js";
+import { loadConfig as loadPatchworkConfigSync } from "../patchworkConfig.js";
+import { findYamlRecipePath } from "../recipesHttp.js";
+import { executeAgent as _executeAgent, } from "./agentExecutor.js";
+import { defaultDeprecationWarn, normalizeRecipeForRuntime, } from "./legacyRecipeCompat.js";
+import { resolveRecipePath } from "./resolveRecipePath.js";
+import { detectSilentFail } from "./stepObservation.js";
+// Import tool registry and trigger tool self-registration
+import { applyToolOutputContext, executeTool, getTool, hasTool, registerPluginTools, } from "./toolRegistry.js";
+import "./tools/index.js";
+/**
+ * Bundled-templates directory used as a third allowed root for nested-recipe
+ * lookups (`recipe:` references with explicit paths). Resolved once at module
+ * load — `__dirname` equivalent points at `dist/recipes/` in the npm tarball
+ * (or `src/recipes/` in dev) so the relative `../../templates/recipes` lifts
+ * out of the source tree to the package root regardless of build layout.
+ *
+ * See dogfood A-PR2 / R2 M-5 — the third jail root is captured here, not at
+ * call time, so a runtime CWD change cannot relocate it.
+ */
+const BUNDLED_TEMPLATES_DIR = (() => {
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    // dist/recipes/yamlRunner.js → ../../templates/recipes
+    // src/recipes/yamlRunner.ts → ../../templates/recipes
+    return path.resolve(here, "..", "..", "templates", "recipes");
+})();
+export function evaluateExpect(result, expect) {
+    const failures = [];
+    if (expect.stepsRun !== undefined && result.stepsRun !== expect.stepsRun) {
+        failures.push({
+            assertion: "stepsRun",
+            expected: expect.stepsRun,
+            actual: result.stepsRun,
+            message: `Expected stepsRun=${expect.stepsRun}, got ${result.stepsRun}`,
+        });
+    }
+    if (expect.errorMessage !== undefined) {
+        const expected = expect.errorMessage ?? null;
+        const actual = result.errorMessage ?? null;
+        if (expected !== actual) {
+            failures.push({
+                assertion: "errorMessage",
+                expected,
+                actual,
+                message: expected === null
+                    ? `Expected clean run (no error), got: ${actual}`
+                    : `Expected error "${expected}", got: ${actual === null ? "(none)" : actual}`,
+            });
+        }
+    }
+    if (expect.outputs !== undefined) {
+        for (const key of expect.outputs) {
+            if (!result.outputs.includes(key)) {
+                failures.push({
+                    assertion: "outputs",
+                    expected: key,
+                    actual: result.outputs,
+                    message: `Expected output key "${key}" not found in [${result.outputs.join(", ")}]`,
+                });
+            }
+        }
+    }
+    if (expect.context !== undefined) {
+        for (const [key, expectedVal] of Object.entries(expect.context)) {
+            const actual = result.context[key];
+            if (actual === undefined) {
+                failures.push({
+                    assertion: `context.${key}`,
+                    expected: expectedVal,
+                    actual: undefined,
+                    message: `Expected context key "${key}" to equal "${expectedVal}", but key is missing`,
+                });
+            }
+            else if (!actual.includes(expectedVal)) {
+                failures.push({
+                    assertion: `context.${key}`,
+                    expected: expectedVal,
+                    actual,
+                    message: `Expected context["${key}"] to contain "${expectedVal}", got "${actual}"`,
+                });
+            }
+        }
+    }
+    return failures;
+}
+// Strip tool-call narration some models (e.g. Gemini) prepend before the markdown block.
+function stripLeadingNarration(text) {
+    const lines = text.split("\n");
+    const firstMarkdown = lines.findIndex((l) => /^(#|>|`|\||[-*+] |\d+\. |\*\*)/.test(l.trimStart()));
+    return firstMarkdown > 0 ? lines.slice(firstMarkdown).join("\n") : text;
+}
 export function loadYamlRecipe(filePath) {
     const text = readFileSync(filePath, "utf-8");
     const raw = parseYaml(text);
     return validateYamlRecipe(raw);
 }
 export function validateYamlRecipe(raw) {
-    if (typeof raw !== "object" || raw === null) {
+    const normalized = normalizeRecipeForRuntime(raw, defaultDeprecationWarn);
+    if (typeof normalized !== "object" || normalized === null) {
         throw new Error("recipe must be an object");
     }
-    const r = raw;
+    const r = normalized;
     if (typeof r.name !== "string" || !r.name) {
         throw new Error("recipe.name required");
     }
@@ -44,124 +137,706 @@ export function validateYamlRecipe(raw) {
     if (!Array.isArray(r.steps) || r.steps.length === 0) {
         throw new Error("recipe.steps must be a non-empty array");
     }
+    if (r.servers !== undefined &&
+        (!Array.isArray(r.servers) ||
+            r.servers.some((s) => typeof s !== "string"))) {
+        throw new Error("recipe.servers must be an array of strings if present");
+    }
     return r;
 }
+/** Track already-loaded plugin specs to avoid double-loading within a process. */
+const loadedPluginSpecs = new Set();
+/**
+ * Load plugin specs declared in `recipe.servers` and register their tools into
+ * the recipe tool registry. Errors per-spec are logged as warnings — never fatal.
+ */
+export async function loadRecipeServers(specs) {
+    const toLoad = specs.filter((s) => !loadedPluginSpecs.has(s));
+    if (toLoad.length === 0)
+        return;
+    let loadPluginsFull;
+    try {
+        ({ loadPluginsFull } = await import("../pluginLoader.js"));
+    }
+    catch (err) {
+        console.warn(`[recipe servers] failed to import pluginLoader: ${err instanceof Error ? err.message : String(err)}`);
+        return;
+    }
+    const minimalConfig = {
+        workspace: process.cwd(),
+        workspaceFolders: [process.cwd()],
+        commandTimeout: 30_000,
+        maxResultSize: 1_048_576,
+    };
+    const minimalLogger = {
+        info: (msg) => console.info(`[recipe servers] ${msg}`),
+        warn: (msg) => console.warn(`[recipe servers] ${msg}`),
+        error: (msg) => console.error(`[recipe servers] ${msg}`),
+        debug: (_msg) => { },
+    };
+    for (const spec of toLoad) {
+        try {
+            const loaded = await loadPluginsFull([spec], minimalConfig, minimalLogger);
+            let toolCount = 0;
+            for (const plugin of loaded) {
+                const pluginTools = plugin.tools.map((t) => ({
+                    name: t.schema.name,
+                    handler: t.handler,
+                    schema: t.schema,
+                }));
+                toolCount += registerPluginTools(pluginTools);
+            }
+            loadedPluginSpecs.add(spec);
+            if (toolCount > 0) {
+                console.info(`[recipe servers] loaded "${spec}" — ${toolCount} tool(s) registered`);
+            }
+        }
+        catch (err) {
+            console.warn(`[recipe servers] failed to load "${spec}": ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+}
 export async function runYamlRecipe(recipe, deps = {}, seedContext = {}) {
+    if (recipe.servers?.length) {
+        await loadRecipeServers(recipe.servers);
+    }
     const now = deps.now ? deps.now() : new Date();
+    // Resolve recipe-level context blocks (type: env) into seed context
+    const envCtx = {};
+    if (Array.isArray(recipe.context)) {
+        for (const block of recipe
+            .context ?? []) {
+            const b = block;
+            if (b.type === "env" && Array.isArray(b.keys)) {
+                for (const key of b.keys) {
+                    const v = process.env[key];
+                    if (v !== undefined)
+                        envCtx[key] = v;
+                }
+            }
+        }
+    }
     const ctx = {
         date: now.toISOString().slice(0, 10),
         time: now.toTimeString().slice(0, 5),
+        ...envCtx,
         ...seedContext,
     };
-    const readFile = deps.readFile ?? ((p) => readFileSync(expandHome(p), "utf-8"));
-    const writeFile = deps.writeFile ??
-        ((p, content) => {
-            const abs = expandHome(p);
-            mkdirSync(path.dirname(abs), { recursive: true });
-            writeFileSync(abs, content);
-        });
-    const appendFile = deps.appendFile ??
-        ((p, content) => {
-            const abs = expandHome(p);
-            mkdirSync(path.dirname(abs), { recursive: true });
-            appendFileSync(abs, content);
-        });
-    const mkdir = deps.mkdir ??
-        ((p) => mkdirSync(expandHome(p), { recursive: true }));
+    const stepDeps = resolveStepDeps(deps);
+    // 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
+    // path. Skip in test mode.
+    const recipeStartedAt = now.getTime();
+    const recipeTriggerKind = recipe.trigger?.type ?? "manual";
+    const yamlTriggerKind = (["cron", "webhook", "recipe"].includes(recipeTriggerKind)
+        ? recipeTriggerKind
+        : "recipe");
+    let runSeq;
+    if (deps.runLog && !stepDeps.testMode) {
+        try {
+            runSeq = deps.runLog.startRun({
+                taskId: `yaml:${recipe.name}:${recipeStartedAt}`,
+                recipeName: recipe.name,
+                trigger: yamlTriggerKind,
+                createdAt: recipeStartedAt,
+                startedAt: recipeStartedAt,
+            });
+        }
+        catch {
+            // Non-fatal — run-log failures must never break recipe execution.
+        }
+    }
     const outputs = [];
+    const stepResults = [];
     let stepsRun = 0;
-    const workdir = deps.workdir ?? process.cwd();
-    const stepDeps = {
-        readFile,
-        writeFile,
-        appendFile,
-        mkdir,
-        workdir,
-        gitLogSince: deps.gitLogSince ?? defaultGitLogSince,
-        gitStaleBranches: deps.gitStaleBranches ?? defaultGitStaleBranches,
-        getDiagnostics: deps.getDiagnostics ?? (() => ""),
-        fetchFn: deps.fetchFn ?? globalThis.fetch,
-        claudeFn: deps.claudeFn ?? defaultClaudeFn,
-        claudeCodeFn: deps.claudeCodeFn ?? defaultClaudeCodeFn,
-        getGmailToken: deps.getGmailToken ??
-            (async () => {
-                const { getValidAccessToken } = await import("../connectors/gmail.js");
-                return getValidAccessToken();
-            }),
-    };
+    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 model = agentCfg.model ?? "claude-haiku-4-5-20251001";
             const intoKey = agentCfg.into ?? "agent_output";
+            const stepId = intoKey;
+            const stepStart = Date.now();
             let agentResult;
-            if (agentCfg.driver === "claude-code") {
-                agentResult = await stepDeps.claudeCodeFn(renderedPrompt);
-            }
-            else if (agentCfg.driver === "api") {
-                agentResult = await stepDeps.claudeFn(renderedPrompt, model);
-            }
-            else {
-                // Default driver: use API path. If no ANTHROPIC_API_KEY and caller did not provide a
-                // custom claudeFn (i.e. using the built-in default that returns a skip message), probe
-                // for the claude CLI and fall back automatically.
-                const usingDefaultClaudeFn = deps.claudeFn === undefined;
-                if (!process.env.ANTHROPIC_API_KEY && usingDefaultClaudeFn) {
-                    const probe = spawnSync("claude", ["--version"], {
-                        encoding: "utf-8",
-                        timeout: 5000,
+            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;
+                    runError = runError ?? reason;
+                    stepResults.push({
+                        id: stepId,
+                        tool: "agent",
+                        status: "error",
+                        error: reason,
+                        durationMs: Date.now() - stepStart,
                     });
-                    if (!probe.error) {
-                        agentResult = await stepDeps.claudeCodeFn(renderedPrompt);
+                }
+                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;
+                        stepResults.push({
+                            id: stepId,
+                            tool: "agent",
+                            status: "error",
+                            error: errMsg,
+                            durationMs: Date.now() - stepStart,
+                        });
                     }
                     else {
-                        agentResult = await stepDeps.claudeFn(renderedPrompt, model);
+                        // Try to parse as JSON so dot-notation ({{meeting.field}}) works
+                        try {
+                            const jsonMatch = /```(?:json)?\s*([\s\S]*?)```/.exec(stripped) ?? [null, stripped];
+                            const parsed = JSON.parse((jsonMatch[1] ?? "").trim());
+                            ctx[intoKey] = parsed;
+                        }
+                        catch {
+                            ctx[intoKey] = stripped;
+                        }
+                        outputs.push(intoKey);
+                        stepResults.push({
+                            id: stepId,
+                            tool: "agent",
+                            status: "ok",
+                            durationMs: Date.now() - stepStart,
+                        });
                     }
                 }
-                else {
-                    agentResult = await stepDeps.claudeFn(renderedPrompt, model);
-                }
             }
-            ctx[intoKey] = agentResult;
-            outputs.push(intoKey);
+            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,
+                    durationMs: Date.now() - stepStart,
+                });
+            }
             stepsRun++;
             continue;
         }
-        const result = await executeStep(step, ctx, stepDeps);
-        stepsRun++;
-        if (result !== null) {
-            if (step.into) {
-                ctx[step.into] = result;
-                // For Gmail steps, also expose flat dot-notation keys for render()
-                const isGmailStep = step.tool === "gmail.fetch_unread" ||
-                    step.tool === "gmail.search" ||
-                    step.tool === "gmail.fetch_thread";
-                if (isGmailStep) {
+        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);
-                        for (const [k, v] of Object.entries(parsed)) {
-                            if (typeof v === "string" || typeof v === "number") {
-                                ctx[`${step.into}.${k}`] = String(v);
-                            }
-                        }
-                        // Also expose messages array as JSON string for agent prompts
-                        if (Array.isArray(parsed.messages)) {
-                            ctx[`${step.into}.json`] = JSON.stringify(parsed.messages);
+                        if (parsed.ok === false && typeof parsed.error === "string") {
+                            stepError = parsed.error;
                         }
                     }
                     catch {
-                        // non-JSON result, skip
+                        /* 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}`;
                     }
                 }
             }
+            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}`;
+                }
+                else if (fallbackFailOpen && !step.optional) {
+                    console.warn(`step ${stepId} failed but on_error.fallback=${fallback} — treating as non-fatal: ${stepError}`);
+                }
+            }
+        }
+        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") {
-                outputs.push(render(step.path, ctx));
+                // 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,
+                }));
             }
         }
     }
-    return { recipe: recipe.name, stepsRun, outputs, context: ctx };
+    // 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).
+    if (!stepDeps.testMode) {
+        try {
+            const doneAt = Date.now();
+            const outputTail = stepResults
+                .map((s) => `[${s.status}] ${s.tool ?? s.id}${s.error ? `: ${s.error}` : ""}`)
+                .join("\n")
+                .slice(0, 2000);
+            const finalStepResults = stepResults.map((s) => ({
+                id: s.id,
+                tool: s.tool,
+                status: s.status,
+                error: s.error,
+                durationMs: s.durationMs,
+            }));
+            if (deps.runLog && runSeq !== undefined) {
+                deps.runLog.completeRun(runSeq, {
+                    status: runError ? "error" : "done",
+                    doneAt,
+                    durationMs: doneAt - recipeStartedAt,
+                    stepResults: finalStepResults,
+                    outputTail,
+                    ...(runError !== undefined && { errorMessage: runError }),
+                    ...(assertionFailures.length > 0 ? { assertionFailures } : {}),
+                });
+            }
+            else {
+                const { RecipeRunLog } = await import("../runLog.js");
+                const { homedir } = await import("node:os");
+                const resolvedLogDir = deps.logDir ?? path.join(homedir(), ".patchwork");
+                const log = new RecipeRunLog({ dir: resolvedLogDir });
+                log.appendDirect({
+                    taskId: `yaml:${recipe.name}:${recipeStartedAt}`,
+                    recipeName: recipe.name,
+                    trigger: yamlTriggerKind,
+                    status: runError ? "error" : "done",
+                    createdAt: recipeStartedAt,
+                    startedAt: recipeStartedAt,
+                    doneAt,
+                    durationMs: doneAt - recipeStartedAt,
+                    outputTail,
+                    errorMessage: runError,
+                    stepResults: finalStepResults,
+                    ...(assertionFailures.length > 0 ? { assertionFailures } : {}),
+                });
+            }
+        }
+        catch {
+            // Non-fatal — run log write failure should never break recipe execution
+        }
+    }
+    // Notify via Slack if any step failed
+    if (runError && !stepDeps.testMode) {
+        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";
+                try {
+                    const cfgPath = path.join(os.homedir(), ".patchwork", "config.json");
+                    const cfg = JSON.parse(readFileSync(cfgPath, "utf-8"));
+                    const notifications = cfg.notifications;
+                    if (typeof notifications?.slackChannel === "string") {
+                        notifyChannel = notifications.slackChannel;
+                    }
+                }
+                catch {
+                    /* use default */
+                }
+                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 {
+            // Non-fatal — notification failure should never mask the original error
+        }
+    }
+    return {
+        recipe: recipe.name,
+        stepsRun,
+        outputs,
+        context: ctx,
+        stepResults,
+        errorMessage: runError,
+        ...(assertionFailures.length > 0 ? { assertionFailures } : {}),
+    };
+}
+export async function executeStep(step, ctx, deps) {
+    const toolId = step.tool;
+    if (!toolId) {
+        return null;
+    }
+    // Check if tool is registered in the new registry
+    if (hasTool(toolId)) {
+        const tool = getTool(toolId);
+        // Build params with template rendering for string values
+        const params = {};
+        for (const [key, value] of Object.entries(step)) {
+            if (key === "tool" || key === "agent" || key === "into")
+                continue;
+            params[key] = deepRender(value, ctx);
+        }
+        // Check if mock connector is available for this tool
+        if (deps.mockConnectors?.[toolId]) {
+            return deps.mockConnectors[toolId].invoke("execute", params);
+        }
+        if (tool &&
+            deps.recordFixturesDir &&
+            tool.namespace !== "file" &&
+            tool.namespace !== "git" &&
+            tool.namespace !== "diagnostics") {
+            return captureFixture(path.join(deps.recordFixturesDir, `${tool.namespace}.json`), tool.namespace, toolId.split(".")[1] ?? toolId, params, async () => executeTool(toolId, { params, step, ctx, deps }));
+        }
+        return executeTool(toolId, { params, step, ctx, deps });
+    }
+    // Unknown tool — skip, don't throw (forward compat)
+    return null;
+}
+/** Minimal `{{ expr }}` renderer — flat keys and dot-notation paths. */
+export function render(template, ctx) {
+    return template.replace(/\{\{\s*([^}]+?)\s*\}\}/g, (_, expr) => {
+        const key = expr.trim();
+        const coerce = (v) => {
+            if (v == null)
+                return "";
+            if (typeof v === "object")
+                return JSON.stringify(v);
+            return String(v);
+        };
+        // Fast path: flat key exists
+        if (Object.hasOwn(ctx, key))
+            return coerce(ctx[key]);
+        // Dot-notation: resolve nested path into ctx values (JSON-parse string intermediates)
+        const parts = key.split(".");
+        // biome-ignore lint/suspicious/noExplicitAny: resolved values are dynamic JSON shapes
+        let val = ctx;
+        for (const part of parts) {
+            if (val == null)
+                return "";
+            if (typeof val === "string") {
+                try {
+                    val = JSON.parse(val);
+                }
+                catch {
+                    return "";
+                }
+            }
+            if (typeof val !== "object")
+                return "";
+            // Object.hasOwn — bracket access on a Record walks the prototype chain,
+            // which would expose Object.prototype members (toString, constructor,
+            // etc.) to attacker-controllable template paths. String(toString)
+            // renders the function source and leaks it into recipe output.
+            const obj = val;
+            val = Object.hasOwn(obj, part) ? obj[part] : undefined;
+        }
+        return val == null
+            ? ""
+            : typeof val === "object"
+                ? JSON.stringify(val)
+                : String(val);
+    });
+}
+/** Recursively render all string leaves in a value (for nested params like blocks). */
+function deepRender(value, ctx) {
+    if (typeof value === "string")
+        return render(value, ctx);
+    if (Array.isArray(value))
+        return value.map((v) => deepRender(v, ctx));
+    if (value !== null && typeof value === "object") {
+        const out = {};
+        for (const [k, v] of Object.entries(value)) {
+            out[k] = deepRender(v, ctx);
+        }
+        return out;
+    }
+    return value;
+}
+function parseSinceToGitArg(since) {
+    const m = /^(\d+)(h|d)$/i.exec(since.trim());
+    if (!m)
+        return since;
+    const [, num, unit = "h"] = m;
+    return unit.toLowerCase() === "h" ? `${num} hours ago` : `${num} days ago`;
+}
+// Exported for test coverage of the regression fix (was returning the
+// `(git log unavailable)` placeholder string on any failure, which
+// silently looked like success to pre-#72 runners).
+export function defaultGitLogSince(since, workdir) {
+    // Same antipattern that broke `defaultGitStaleBranches` (PR #70): on
+    // any error this used to return `(git log unavailable)`. The runner
+    // saw that as success-with-empty-data and downstream agents
+    // summarized "no recent commits" — false signal.
+    //
+    // Fix: return a JSON `{ok: false, error}` shape on failure so the
+    // runner's existing JSON-error detection (yamlRunner step-error
+    // block) flags the step as `error`. Successful runs still return
+    // bare git output text.
+    try {
+        const sinceArg = parseSinceToGitArg(since);
+        const result = spawnSync("git", ["log", "--oneline", `--since=${sinceArg}`], {
+            cwd: workdir ?? process.cwd(),
+            encoding: "utf-8",
+            timeout: 5000,
+        });
+        if (result.error) {
+            return JSON.stringify({
+                ok: false,
+                error: `git log failed: ${result.error.message}`,
+            });
+        }
+        if (result.status !== 0) {
+            const stderr = (result.stderr ?? "").toString().trim().slice(0, 200);
+            return JSON.stringify({
+                ok: false,
+                error: `git log exited ${result.status}${stderr ? `: ${stderr}` : ""}`,
+            });
+        }
+        return (result.stdout ?? "").trim();
+    }
+    catch (err) {
+        return JSON.stringify({
+            ok: false,
+            error: `git log threw: ${err instanceof Error ? err.message : String(err)}`,
+        });
+    }
+}
+// Exported for test coverage of the regression fix (was using `git branch
+// --since=<date>` which isn't a real flag).
+export function defaultGitStaleBranches(days, workdir) {
+    // Two bugs were caught dogfooding the `branch-health` recipe:
+    //   1) `git branch --since=<date>` is NOT a valid flag — git exits 129
+    //      with "unknown option `since=...`". The function used to ALWAYS
+    //      fall through to the "(git branches unavailable)" placeholder.
+    //   2) Even if `--since` had been a real flag, its semantics ("commits
+    //      since") would have produced the OPPOSITE list of what
+    //      "stale_branches" implies — branches with recent activity, not
+    //      ones that have gone quiet.
+    //
+    // Fix: use `git for-each-ref` with a `committerdate` format, parse the
+    // ISO date in JS, and emit branches whose last commit is OLDER than
+    // the cutoff. Output is one per line: `<short-name>  <YYYY-MM-DD>`.
+    try {
+        const cutoffMs = Date.now() - days * 86_400_000;
+        const r = spawnSync("git", [
+            "for-each-ref",
+            "--sort=committerdate",
+            "--format=%(refname:short)\t%(committerdate:iso-strict)",
+            "refs/heads/",
+        ], {
+            cwd: workdir ?? process.cwd(),
+            encoding: "utf-8",
+            timeout: 5000,
+        });
+        if (r.error || r.status !== 0)
+            return "(git branches unavailable)";
+        const lines = (r.stdout ?? "").split("\n").filter(Boolean);
+        const stale = [];
+        for (const line of lines) {
+            const tab = line.indexOf("\t");
+            if (tab < 0)
+                continue;
+            const name = line.slice(0, tab);
+            const dateStr = line.slice(tab + 1);
+            const ts = Date.parse(dateStr);
+            if (Number.isNaN(ts))
+                continue;
+            if (ts < cutoffMs) {
+                stale.push(`${name}\t${dateStr.slice(0, 10)}`);
+            }
+        }
+        if (stale.length === 0) {
+            return `(no branches inactive >${days}d)`;
+        }
+        return stale.join("\n");
+    }
+    catch {
+        return "(git branches unavailable)";
+    }
+}
+/** Resolve all RunnerDeps to concrete StepDeps with production defaults filled in. */
+function resolveStepDeps(deps) {
+    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
+    // jail the path before touching the filesystem (G-security F-01 / R2 C-1
+    // chained-runner third-substitution-site coverage).
+    return {
+        readFile: deps.readFile ??
+            ((p) => readFileSync(resolveRecipePath(p, { workspace: workdir }), "utf-8")),
+        writeFile: deps.writeFile ??
+            ((p, content) => {
+                const abs = resolveRecipePath(p, { workspace: workdir, write: true });
+                mkdirSync(path.dirname(abs), { recursive: true });
+                writeFileSync(abs, content);
+            }),
+        appendFile: deps.appendFile ??
+            ((p, content) => {
+                const abs = resolveRecipePath(p, { workspace: workdir, write: true });
+                mkdirSync(path.dirname(abs), { recursive: true });
+                appendFileSync(abs, content);
+            }),
+        mkdir: deps.mkdir ??
+            ((p) => mkdirSync(resolveRecipePath(p, { workspace: workdir, write: true }), {
+                recursive: true,
+            })),
+        workdir,
+        gitLogSince: deps.gitLogSince ?? defaultGitLogSince,
+        gitStaleBranches: deps.gitStaleBranches ?? defaultGitStaleBranches,
+        // The `diagnostics.get` recipe tool is registered (src/recipes/tools/
+        // diagnostics.ts) but only meaningful when the bridge wires a real
+        // `getDiagnostics` impl backed by the LSP / extension client. CLI runs
+        // and tests have no bridge to ask, so the default returns a JSON error
+        // shape that the step-error detector flags as `error` instead of the
+        // pre-fix empty string that silently passed as success.
+        getDiagnostics: deps.getDiagnostics ??
+            (() => JSON.stringify({
+                ok: false,
+                error: "diagnostics.get unavailable (no bridge / no `deps.getDiagnostics` injected)",
+            })),
+        fetchFn: deps.fetchFn ?? globalThis.fetch,
+        claudeFn: deps.claudeFn ?? defaultClaudeFn,
+        claudeCodeFn: deps.claudeCodeFn ?? defaultClaudeCodeFn,
+        localFn: deps.localFn ?? defaultLocalFn,
+        providerDriverFn: deps.providerDriverFn ?? makeProviderDriverFn(),
+        mockConnectors: deps.mockConnectors ?? {},
+        recordFixturesDir: deps.recordFixturesDir,
+        getGmailToken: deps.getGmailToken ??
+            (async () => {
+                const { getValidAccessToken } = await import("../connectors/gmail.js");
+                return getValidAccessToken();
+            }),
+        getDriveToken: deps.getDriveToken ??
+            (async () => {
+                const { getValidAccessToken } = await import("../connectors/googleDrive.js");
+                return getValidAccessToken();
+            }),
+        logDir: deps.logDir,
+        testMode: deps.testMode ?? false,
+    };
+}
+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),
+        probeClaudeCli: () => {
+            if (runnerDeps.claudeFn !== undefined)
+                return false;
+            const probe = spawnSync("claude", ["--version"], {
+                encoding: "utf-8",
+                timeout: 5000,
+            });
+            return !probe.error;
+        },
+        loadPatchworkConfig: () => {
+            // Synchronous static import — earlier `require()` form silently failed
+            // under "type": "module" and returned {}, dropping config-driven
+            // model/driver preferences for no-driver agent steps.
+            try {
+                return loadPatchworkConfigSync();
+            }
+            catch {
+                return {};
+            }
+        },
+    };
 }
 function defaultClaudeCodeFn(prompt) {
     try {
@@ -188,6 +863,51 @@ function defaultClaudeCodeFn(prompt) {
         return Promise.resolve(`[agent step failed: ${err instanceof Error ? err.message : String(err)}]`);
     }
 }
+/** Returns a providerDriverFn with a per-run driver cache (not shared across runs). */
+function makeProviderDriverFn() {
+    const cache = new Map();
+    return async function defaultProviderDriverFn(driverName, prompt, model) {
+        try {
+            let driver = cache.get(driverName);
+            if (!driver) {
+                const { createDriver } = await import("../drivers/index.js");
+                const d = createDriver(driverName, { binary: "claude", antBinary: "ant" }, () => { });
+                if (!d)
+                    return `[agent step failed: ${driverName} driver returned null]`;
+                driver = d;
+                cache.set(driverName, driver);
+            }
+            const controller = new AbortController();
+            const timeoutMs = 300_000;
+            const startupTimeoutMs = 30_000;
+            const timeout = setTimeout(() => controller.abort(), timeoutMs);
+            try {
+                const result = await driver.run({
+                    prompt,
+                    workspace: process.cwd(),
+                    timeoutMs,
+                    startupTimeoutMs,
+                    signal: controller.signal,
+                    model,
+                });
+                if (result.exitCode !== undefined && result.exitCode !== 0) {
+                    const detail = result.stderrTail ?? result.text ?? "";
+                    return `[agent step failed: ${driverName} exited ${result.exitCode}${detail ? ` — ${detail.slice(0, 200)}` : ""}]`;
+                }
+                if (!result.text) {
+                    return `[agent step failed: ${driverName} returned empty output (possible timeout or auth error)]`;
+                }
+                return result.text;
+            }
+            finally {
+                clearTimeout(timeout);
+            }
+        }
+        catch (err) {
+            return `[agent step failed: ${err instanceof Error ? err.message : String(err)}]`;
+        }
+    };
+}
 async function defaultClaudeFn(prompt, model) {
     const apiKey = process.env.ANTHROPIC_API_KEY;
     if (!apiKey)
@@ -222,338 +942,217 @@ async function defaultClaudeFn(prompt, model) {
         return `[agent step failed: ${err instanceof Error ? err.message : String(err)}]`;
     }
 }
-async function executeStep(step, ctx, deps) {
-    switch (step.tool) {
-        case "file.read": {
-            const p = render(step.path, ctx);
-            try {
-                return deps.readFile(p);
-            }
-            catch {
-                if (step.optional)
-                    return "";
-                throw new Error(`file.read: could not read ${p}`);
-            }
+async function defaultLocalFn(prompt, model) {
+    try {
+        const { createLocalAdapter } = await import("../adapters/local.js");
+        const { loadConfig: loadPatchworkConfig } = await import("../patchworkConfig.js");
+        const cfg = loadPatchworkConfig();
+        const adapter = createLocalAdapter({
+            endpoint: cfg.localEndpoint,
+            defaultModel: cfg.localModel ?? model,
+        });
+        const result = await adapter.complete({
+            systemPrompt: "",
+            messages: [{ role: "user", content: prompt }],
+        });
+        return result.text ?? "[agent step failed: empty response from local LLM]";
+    }
+    catch (err) {
+        return `[agent step failed: ${err instanceof Error ? err.message : String(err)}]`;
+    }
+}
+/**
+ * Build ExecutionDeps for ChainedRecipeRunner backed by the yamlRunner step
+ * handlers. This lets chained recipes use the same tool set (file.*, git.*,
+ * gmail.*, github.*, linear.*, diagnostics.*) as simple YAML recipes.
+ *
+ * Pass the result as `chainedDeps` when calling `dispatchRecipe` or
+ * `runChainedRecipe` so that `executeTool` is properly wired.
+ */
+export function buildChainedDeps(runnerDeps, claudeCodeFnOverride) {
+    const stepDeps = resolveStepDeps(runnerDeps);
+    function normalizeNestedRecipeLookupName(ref) {
+        return ref.trim().replace(/\.ya?ml$/i, "");
+    }
+    function tryLoadRecipeFile(filePath) {
+        if (!existsSync(filePath))
+            return null;
+        try {
+            const recipe = loadYamlRecipe(filePath);
+            return { recipe, sourcePath: filePath };
         }
-        case "file.write": {
-            const p = render(step.path, ctx);
-            const content = render(step.content, ctx);
-            deps.writeFile(p, content);
-            return content;
-        }
-        case "file.append": {
-            const p = render(step.path, ctx);
-            const content = render(step.content, ctx);
-            const when = step.when;
-            if (when && !evalWhen(when, ctx))
-                return null;
-            deps.appendFile(p, content);
-            return content;
-        }
-        case "git.log_since": {
-            const since = render(String(step.since ?? "24h"), ctx);
-            return deps.gitLogSince(since, deps.workdir);
-        }
-        case "git.stale_branches": {
-            const days = typeof step.days === "number" ? step.days : 30;
-            return deps.gitStaleBranches(days, deps.workdir);
-        }
-        case "diagnostics.get": {
-            const uri = render(String(step.uri ?? ""), ctx);
-            return deps.getDiagnostics(uri);
-        }
-        case "gmail.fetch_unread": {
-            const since = render(String(step.since ?? "24h"), ctx);
-            const MAX_GMAIL_RESULTS = 50;
-            const max = Math.min(typeof step.max === "number" ? step.max : 20, MAX_GMAIL_RESULTS);
-            const query = `is:unread newer_than:${sinceToGmailQuery(since)}`;
-            return gmailSearch(query, max, deps);
-        }
-        case "gmail.search": {
-            const query = render(String(step.query ?? ""), ctx);
-            const MAX_GMAIL_RESULTS = 50;
-            const max = Math.min(typeof step.max === "number" ? step.max : 10, MAX_GMAIL_RESULTS);
-            return gmailSearch(query, max, deps);
-        }
-        case "gmail.fetch_thread": {
-            const id = render(String(step.id ?? ""), ctx);
-            return gmailFetchThread(id, deps);
-        }
-        case "github.list_issues": {
-            const { listIssues } = await import("../connectors/github.js");
-            const repo = step.repo ? render(String(step.repo), ctx) : undefined;
-            const assignee = step.assignee
-                ? render(String(step.assignee), ctx)
-                : "@me";
-            const limit = typeof step.max === "number" ? step.max : 20;
-            const issues = await listIssues({ repo, assignee, limit });
-            return JSON.stringify({ count: issues.length, issues });
-        }
-        case "github.list_prs": {
-            const { listPRs } = await import("../connectors/github.js");
-            const repo = step.repo ? render(String(step.repo), ctx) : undefined;
-            const author = step.author ? render(String(step.author), ctx) : "@me";
-            const limit = typeof step.max === "number" ? step.max : 20;
-            const prs = await listPRs({ repo, author, limit });
-            return JSON.stringify({ count: prs.length, prs });
-        }
-        case "linear.list_issues": {
-            const { loadTokens, listIssues: listLinearIssues } = await import("../connectors/linear.js");
-            if (!loadTokens()) {
-                return JSON.stringify({
-                    count: 0,
-                    issues: [],
-                    error: "Linear not connected",
-                });
-            }
-            const teamKey = step.team ? render(String(step.team), ctx) : undefined;
-            const assigneeMe = step.assignee === "@me" || step.assignee === undefined;
-            const stateFilter = step.state
-                ? render(String(step.state), ctx)
-                : "started,unstarted";
-            const limit = typeof step.max === "number" ? step.max : 20;
-            const states = stateFilter
-                .split(",")
-                .map((s) => s.trim())
-                .filter(Boolean);
-            try {
-                const issues = await listLinearIssues({
-                    team: teamKey,
-                    assigneeMe,
-                    states,
-                    limit,
-                });
-                return JSON.stringify({ count: issues.length, issues });
-            }
-            catch (err) {
-                return JSON.stringify({
-                    count: 0,
-                    issues: [],
-                    error: err instanceof Error ? err.message : String(err),
-                });
+        catch {
+            return null;
+        }
+    }
+    const executeTool = async (tool, params) => {
+        // R2 C-1 third-substitution-site coverage: the chained runner has its
+        // own template-resolution path (`chainedRunner.ts:194-205`). By the
+        // time we reach this dispatch point the params have been rendered
+        // *and* JSON-parsed, so a `path` field that survived the chained
+        // substitution may have just been promoted from inside-jail to
+        // outside-jail. Re-jail any `path` field on file.* tools here so that
+        // chained sub-recipes can't bypass the per-tool jail in `tools/file.ts`
+        // by injecting `..` segments via outer-recipe vars.
+        if ((tool === "file.read" ||
+            tool === "file.write" ||
+            tool === "file.append") &&
+            typeof params.path === "string") {
+            params = {
+                ...params,
+                path: resolveRecipePath(params.path, {
+                    workspace: stepDeps.workdir,
+                    write: tool !== "file.read",
+                }),
+            };
+        }
+        // Construct a YamlStep-compatible object so we can reuse executeStep.
+        const step = { tool, ...params };
+        // executeStep uses a RunContext for {{}} rendering — by the time executeTool
+        // is called the chained runner has already resolved templates, so we pass
+        // an empty context (no double-rendering).
+        const result = await executeStep(step, {}, stepDeps);
+        return result ?? "";
+    };
+    const executeAgent = async (prompt, model, driver) => _executeAgent({ prompt, model, driver }, buildAgentExecutorDeps(stepDeps, runnerDeps, claudeCodeFnOverride));
+    // ---------------------------------------------------------------------
+    // BEGIN A-PR2 EDIT BLOCK — `loadNestedRecipe` jail (dogfood F-04).
+    //
+    // Path-shaped recipe references (`recipe: ./inner.yaml`, `recipe: /abs.yaml`)
+    // are restricted to three allowed roots:
+    //   1. parent recipe's directory (`path.dirname(parentSourcePath)`)
+    //   2. user recipes dir (`~/.patchwork/recipes/`)
+    //   3. bundled templates dir (`BUNDLED_TEMPLATES_DIR`, captured at boot)
+    //
+    // Resolved candidates that escape all three (e.g. `/etc/passwd.yaml`) are
+    // rejected with `null` — same shape as a not-found lookup so the chained
+    // runner reports its existing "nested_recipe_not_found" error rather than
+    // surfacing a security-implementation detail to the recipe author.
+    //
+    // Coordination note (A-PR1 may also touch this file): the helper
+    // `pathIsWithin` below is local to this module — A-PR1 is changing
+    // unrelated `vars` validation paths and should not collide here. If a merge
+    // conflict surfaces, keep BOTH the jail AND the A-PR1 vars validation.
+    // ---------------------------------------------------------------------
+    const pathIsWithin = (candidate, base) => {
+        const resolvedCandidate = path.resolve(candidate);
+        const resolvedBase = path.resolve(base);
+        if (resolvedCandidate === resolvedBase)
+            return true;
+        return resolvedCandidate.startsWith(`${resolvedBase}${path.sep}`);
+    };
+    const loadNestedRecipe = async (name, parentSourcePath) => {
+        const lookupName = normalizeNestedRecipeLookupName(name);
+        const { homedir: nestedHomedir } = await import("node:os");
+        const userRecipesDir = path.join(nestedHomedir(), ".patchwork", "recipes");
+        if (parentSourcePath) {
+            const parentDir = path.dirname(parentSourcePath);
+            const pathLike = path.isAbsolute(name) ||
+                name.startsWith("./") ||
+                name.startsWith("../") ||
+                /[\\/]/.test(name) ||
+                /\.ya?ml$/i.test(name);
+            if (pathLike) {
+                const resolvedBase = path.isAbsolute(name)
+                    ? path.resolve(name)
+                    : path.resolve(parentDir, name);
+                const candidates = /\.ya?ml$/i.test(resolvedBase)
+                    ? [resolvedBase]
+                    : [`${resolvedBase}.yaml`, `${resolvedBase}.yml`, resolvedBase];
+                // Jail: every candidate must live inside one of the three allowed
+                // roots (parent dir, user recipes, bundled templates). Reject silently
+                // — null mirrors the existing not-found path so error messages stay
+                // generic and don't leak the jail boundaries.
+                const allowedRoots = [parentDir, userRecipesDir, BUNDLED_TEMPLATES_DIR];
+                for (const candidate of candidates) {
+                    const inJail = allowedRoots.some((root) => pathIsWithin(candidate, root));
+                    if (!inJail)
+                        continue;
+                    const loaded = tryLoadRecipeFile(candidate);
+                    if (loaded)
+                        return loaded;
+                }
             }
         }
-        case "calendar.list_events": {
-            const { listEvents } = await import("../connectors/googleCalendar.js");
-            const daysAhead = typeof step.days_ahead === "number" ? step.days_ahead : 7;
-            const maxResults = typeof step.max === "number" ? step.max : 20;
-            const calendarId = step.calendar_id
-                ? render(String(step.calendar_id), ctx)
-                : undefined;
+        // END A-PR2 EDIT BLOCK
+        // Reuses `userRecipesDir` already resolved above for the jail check.
+        const recipesDir = userRecipesDir;
+        // Check for manifest-based package directory first.
+        // Supports both plain names ("morning-brief") and scoped names ("@acme/morning-brief").
+        const pkgDirCandidates = [
+            path.join(recipesDir, lookupName),
+            // scoped: @acme/morning-brief → recipesDir/@acme/morning-brief
+        ];
+        for (const pkgDir of pkgDirCandidates) {
             try {
-                const events = await listEvents({ daysAhead, maxResults, calendarId });
-                return JSON.stringify({ count: events.length, events });
+                const { loadManifestFromDir } = await import("./manifest.js");
+                const manifest = loadManifestFromDir(pkgDir);
+                if (manifest) {
+                    const mainPath = path.join(pkgDir, manifest.recipes.main);
+                    const loaded = tryLoadRecipeFile(mainPath);
+                    if (loaded)
+                        return loaded;
+                }
             }
-            catch (err) {
-                return JSON.stringify({
-                    count: 0,
-                    events: [],
-                    error: err instanceof Error ? err.message : String(err),
-                });
+            catch {
+                // not a manifest dir — try flat file candidates
             }
         }
-        default:
-            // Unknown tool — skip, don't throw (forward compat)
-            return null;
-    }
-}
-/** Minimal `{{ expr }}` renderer — replaces against flat context map. */
-export function render(template, ctx) {
-    return template.replace(/\{\{\s*([^}]+?)\s*\}\}/g, (_, expr) => {
-        const key = expr.trim();
-        return Object.hasOwn(ctx, key) ? (ctx[key] ?? "") : "";
-    });
+        const candidate = findYamlRecipePath(recipesDir, lookupName);
+        if (candidate) {
+            const loaded = tryLoadRecipeFile(candidate);
+            if (loaded)
+                return loaded;
+        }
+        return null;
+    };
+    return { executeTool, executeAgent, loadNestedRecipe };
 }
 /**
- * Evaluate simple `N > 0 || M > 0` guards after template rendering.
- * Supports: numeric literals, >, <, >=, <=, ==, !=, ||, &&, !.
- * Returns true (run step) for anything it can't parse.
+ * Dispatch a loaded recipe to the appropriate runner.
+ *
+ * Recipes with `trigger.type: "chained"` are routed to the ChainedRecipeRunner
+ * (parallel execution, template variables, nested recipes, dry-run).
+ * All other recipes use the existing synchronous yamlRunner path.
+ *
+ * `chainedDeps` is only required when the recipe is chained; omit for simple recipes.
  */
-function evalWhen(when, ctx) {
-    try {
-        const expanded = render(when, ctx).trim();
-        // Only handle the `N op M` and `expr || expr` / `expr && expr` patterns.
-        const orParts = expanded.split("||");
-        if (orParts.length > 1) {
-            return orParts.some((p) => evalWhen(p.trim(), {}));
-        }
-        const andParts = expanded.split("&&");
-        if (andParts.length > 1) {
-            return andParts.every((p) => evalWhen(p.trim(), {}));
-        }
-        const m = /^(-?[\d.]+)\s*(>|<|>=|<=|==|!=)\s*(-?[\d.]+)$/.exec(expanded);
-        if (!m)
-            return true;
-        const [, lhs, op, rhs] = m;
-        const l = Number(lhs);
-        const r = Number(rhs);
-        switch (op) {
-            case ">":
-                return l > r;
-            case "<":
-                return l < r;
-            case ">=":
-                return l >= r;
-            case "<=":
-                return l <= r;
-            case "==":
-                return l === r;
-            case "!=":
-                return l !== r;
-            default:
-                return true;
+export async function dispatchRecipe(recipe, deps, seedContext = {}) {
+    const triggerType = recipe.trigger
+        ?.type;
+    if (triggerType === "chained") {
+        const { runChainedRecipe } = await import("./chainedRunner.js");
+        const chainedRecipe = recipe;
+        const now = deps.now ? deps.now() : new Date();
+        const options = {
+            env: {
+                ...process.env,
+                DATE: now.toISOString().slice(0, 10),
+                TIME: now.toTimeString().slice(0, 5),
+                ...seedContext,
+            },
+            maxConcurrency: chainedRecipe.maxConcurrency ?? 4,
+            maxDepth: chainedRecipe.maxDepth ?? 3,
+            dryRun: deps.chainedOptions?.dryRun ?? false,
+            sourcePath: deps.chainedOptions?.sourcePath,
+            onStepStart: deps.chainedOptions?.onStepStart,
+            onStepComplete: deps.chainedOptions?.onStepComplete,
+            runLogDir: deps.chainedOptions?.runLogDir,
+            runLog: deps.chainedOptions?.runLog,
+            activityLog: deps.chainedOptions?.activityLog,
+            mockedOutputs: deps.chainedOptions?.mockedOutputs,
+            taskIdPrefix: deps.chainedOptions?.taskIdPrefix,
+        };
+        if (!deps.chainedDeps) {
+            throw new Error("chainedDeps required for chained recipes (provide executeTool, executeAgent, loadNestedRecipe)");
         }
+        return runChainedRecipe(chainedRecipe, options, deps.chainedDeps);
     }
-    catch {
-        return true;
-    }
-}
-function sinceToGmailQuery(since) {
-    // "24h" → "1d", "7d" → "7d", "1h" → "1d" (round up)
-    const m = /^(\d+)(h|d)$/.exec(since.trim().toLowerCase());
-    if (!m)
-        return "1d";
-    const [, num, unit] = m;
-    if (unit === "d")
-        return `${num}d`;
-    // hours → round up to days (min 1d)
-    const days = Math.max(1, Math.ceil(Number(num) / 24));
-    return `${days}d`;
-}
-function getHeader(headers, name) {
-    return (headers.find((h) => h.name.toLowerCase() === name.toLowerCase())?.value ??
-        "");
-}
-async function gmailSearch(query, max, deps) {
-    const errorResult = (msg) => JSON.stringify({ count: 0, messages: [], error: msg });
-    let token;
-    try {
-        token = await deps.getGmailToken();
-    }
-    catch {
-        return errorResult("Gmail not connected");
-    }
-    try {
-        const listUrl = `https://gmail.googleapis.com/gmail/v1/users/me/messages?q=${encodeURIComponent(query)}&maxResults=${max}`;
-        const listRes = await deps.fetchFn(listUrl, {
-            headers: { Authorization: `Bearer ${token}` },
-        });
-        if (!listRes.ok)
-            return errorResult("Gmail API error");
-        const listJson = (await listRes.json());
-        const ids = listJson.messages ?? [];
-        const messages = await Promise.all(ids.slice(0, max).map(async (m) => {
-            const detailUrl = `https://gmail.googleapis.com/gmail/v1/users/me/messages/${m.id}?format=metadata&metadataHeaders=Subject,From,Date`;
-            const detailRes = await deps.fetchFn(detailUrl, {
-                headers: { Authorization: `Bearer ${token}` },
-            });
-            if (!detailRes.ok)
-                return { id: m.id, subject: "", from: "", date: "", snippet: "" };
-            const detail = (await detailRes.json());
-            const hdrs = detail.payload?.headers ?? [];
-            return {
-                id: detail.id,
-                subject: getHeader(hdrs, "Subject"),
-                from: getHeader(hdrs, "From"),
-                date: getHeader(hdrs, "Date"),
-                snippet: detail.snippet ?? "",
-            };
-        }));
-        const result = { count: messages.length, messages };
-        return JSON.stringify(result);
-    }
-    catch {
-        return errorResult("Gmail fetch failed");
-    }
-}
-async function gmailFetchThread(id, deps) {
-    const errorResult = (msg) => JSON.stringify({ subject: "", messages: [], error: msg });
-    let token;
-    try {
-        token = await deps.getGmailToken();
-    }
-    catch {
-        return errorResult("Gmail not connected");
-    }
-    try {
-        const url = `https://gmail.googleapis.com/gmail/v1/users/me/threads/${id}?format=metadata&metadataHeaders=Subject,From,Date`;
-        const res = await deps.fetchFn(url, {
-            headers: { Authorization: `Bearer ${token}` },
-        });
-        if (!res.ok)
-            return errorResult("Gmail API error");
-        const thread = (await res.json());
-        const msgs = thread.messages ?? [];
-        const firstHdrs = msgs[0]?.payload?.headers ?? [];
-        const subject = getHeader(firstHdrs, "Subject");
-        const messages = msgs.map((m) => {
-            const hdrs = m.payload?.headers ?? [];
-            return {
-                from: getHeader(hdrs, "From"),
-                date: getHeader(hdrs, "Date"),
-                body_snippet: m.snippet ?? "",
-            };
-        });
-        const result = { subject, messages };
-        return JSON.stringify(result);
-    }
-    catch {
-        return errorResult("Gmail fetch failed");
-    }
-}
-function expandHome(p) {
-    if (p.startsWith("~/"))
-        return path.join(os.homedir(), p.slice(2));
-    return p;
-}
-function parseSinceToGitArg(since) {
-    const m = /^(\d+)(h|d)$/i.exec(since.trim());
-    if (!m)
-        return since;
-    const [, num, unit = "h"] = m;
-    return unit.toLowerCase() === "h" ? `${num} hours ago` : `${num} days ago`;
-}
-function defaultGitLogSince(since, workdir) {
-    try {
-        const sinceArg = parseSinceToGitArg(since);
-        const result = spawnSync("git", ["log", "--oneline", `--since=${sinceArg}`], {
-            cwd: workdir ?? process.cwd(),
-            encoding: "utf-8",
-            timeout: 5000,
-        });
-        if (result.error || result.status !== 0)
-            return "(git log unavailable)";
-        return (result.stdout ?? "").trim();
-    }
-    catch {
-        return "(git log unavailable)";
-    }
-}
-function defaultGitStaleBranches(days, workdir) {
-    try {
-        const cutoff = new Date(Date.now() - days * 86_400_000)
-            .toISOString()
-            .slice(0, 10);
-        const r = spawnSync("git", ["branch", "--format=%(refname:short) %(committerdate:short)"], {
-            cwd: workdir ?? process.cwd(),
-            encoding: "utf-8",
-            timeout: 5000,
-        });
-        const branches = r.error || r.status !== 0 ? "" : (r.stdout ?? "").trim();
-        if (!branches)
-            return "(no local branches)";
-        return (branches
-            .split("\n")
-            .filter((line) => {
-            const parts = line.trim().split(/\s+/);
-            const dateStr = parts[1];
-            return dateStr && dateStr < cutoff;
-        })
-            .join("\n") || "(none older than 30 days)");
-    }
-    catch {
-        return "(git unavailable)";
-    }
+    // 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);
 }
 /** List all YAML recipes in a directory. Returns names. */
 export function listYamlRecipes(recipesDir) {