patchwork-os 0.2.0-alpha.34 → 0.2.0-alpha.36

package/dist/recipes/yamlRunner.js

@@ -24,14 +24,33 @@ 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 { findYamlRecipePath } from "../recipesHttp.js";
 import { executeAgent as _executeAgent, } from "./agentExecutor.js";
+import { detectSilentFail } from "./detectSilentFail.js";
 import { defaultDeprecationWarn, normalizeRecipeForRuntime, } from "./legacyRecipeCompat.js";
+import { resolveRecipePath } from "./resolveRecipePath.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) {
@@ -181,12 +200,52 @@ export async function runYamlRecipe(recipe, deps = {}, seedContext = {}) {
         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 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;
@@ -206,13 +265,22 @@ export async function runYamlRecipe(recipe, deps = {}, seedContext = {}) {
                     driver: agentCfg.driver === "api" ? "anthropic" : agentCfg.driver,
                     model: agentCfg.model,
                 }, buildAgentExecutorDeps(stepDeps, deps));
-                if (agentResult.startsWith("[agent step failed:")) {
-                    runError = runError ?? agentResult;
+                // 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: agentResult,
+                        error: reason,
                         durationMs: Date.now() - stepStart,
                     });
                 }
@@ -230,7 +298,15 @@ export async function runYamlRecipe(recipe, deps = {}, seedContext = {}) {
                         });
                     }
                     else {
-                        ctx[intoKey] = stripped;
+                        // 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,
@@ -256,19 +332,21 @@ export async function runYamlRecipe(recipe, deps = {}, seedContext = {}) {
             continue;
         }
         const stepStart = Date.now();
-        const stepId = step.into ?? step.tool ?? `step_${stepsRun}`;
+        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: ...}
@@ -283,9 +361,29 @@ export async function runYamlRecipe(recipe, deps = {}, seedContext = {}) {
                         /* 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)
@@ -302,6 +400,7 @@ export async function runYamlRecipe(recipe, deps = {}, seedContext = {}) {
                 tool: step.tool,
                 status: "error",
                 error: thrownError,
+                ...(thrownErrorCode ? { errorCode: thrownErrorCode } : {}),
                 durationMs: Date.now() - stepStart,
             });
             if (!failOpen) {
@@ -347,7 +446,15 @@ export async function runYamlRecipe(recipe, deps = {}, seedContext = {}) {
                 }
             }
             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,
+                }));
             }
         }
     }
@@ -355,42 +462,54 @@ export async function runYamlRecipe(recipe, deps = {}, seedContext = {}) {
     const assertionFailures = recipe.expect
         ? evaluateExpect({ stepsRun, outputs, context: ctx, errorMessage: runError }, recipe.expect)
         : [];
-    // Write to RecipeRunLog so the dashboard Runs page shows this execution
+    // 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 { 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 });
-            const trigger = recipe.trigger?.type ?? "manual";
-            const createdAt = now.getTime();
             const doneAt = Date.now();
             const outputTail = stepResults
                 .map((s) => `[${s.status}] ${s.tool ?? s.id}${s.error ? `: ${s.error}` : ""}`)
                 .join("\n")
                 .slice(0, 2000);
-            log.appendDirect({
-                taskId: `yaml:${recipe.name}:${createdAt}`,
-                recipeName: recipe.name,
-                trigger: (["cron", "webhook", "recipe"].includes(trigger)
-                    ? trigger
-                    : "recipe"),
-                status: runError ? "error" : "done",
-                createdAt,
-                startedAt: createdAt,
-                doneAt,
-                durationMs: doneAt - createdAt,
-                outputTail,
-                errorMessage: runError,
-                stepResults: stepResults.map((s) => ({
-                    id: s.id,
-                    tool: s.tool,
-                    status: s.status,
-                    error: s.error,
-                    durationMs: s.durationMs,
-                })),
-                ...(assertionFailures.length > 0 ? { assertionFailures } : {}),
-            });
+            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
@@ -448,12 +567,7 @@ export async function executeStep(step, ctx, deps) {
         for (const [key, value] of Object.entries(step)) {
             if (key === "tool" || key === "agent" || key === "into")
                 continue;
-            if (typeof value === "string") {
-                params[key] = render(value, ctx);
-            }
-            else {
-                params[key] = value;
-            }
+            params[key] = deepRender(value, ctx);
         }
         // Check if mock connector is available for this tool
         if (deps.mockConnectors?.[toolId]) {
@@ -471,17 +585,60 @@ export async function executeStep(step, ctx, deps) {
     // Unknown tool — skip, don't throw (forward compat)
     return null;
 }
-/** Minimal `{{ expr }}` renderer — replaces against flat context map. */
+/** 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();
-        return Object.hasOwn(ctx, key) ? (ctx[key] ?? "") : "";
+        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 "";
+            val = val[part];
+        }
+        return val == null
+            ? ""
+            : typeof val === "object"
+                ? JSON.stringify(val)
+                : String(val);
     });
 }
-function expandHome(p) {
-    if (p.startsWith("~/"))
-        return path.join(os.homedir(), p.slice(2));
-    return p;
+/** 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());
@@ -490,7 +647,19 @@ function parseSinceToGitArg(since) {
     const [, num, unit = "h"] = m;
     return unit.toLowerCase() === "h" ? `${num} hours ago` : `${num} days ago`;
 }
-function defaultGitLogSince(since, workdir) {
+// 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}`], {
@@ -498,25 +667,50 @@ function defaultGitLogSince(since, workdir) {
             encoding: "utf-8",
             timeout: 5000,
         });
-        if (result.error || result.status !== 0)
-            return "(git log unavailable)";
+        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 {
-        return "(git log unavailable)";
+    catch (err) {
+        return JSON.stringify({
+            ok: false,
+            error: `git log threw: ${err instanceof Error ? err.message : String(err)}`,
+        });
     }
 }
-function defaultGitStaleBranches(days, workdir) {
+// 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 cutoff = new Date(Date.now() - days * 86_400_000)
-            .toISOString()
-            .slice(0, 10);
+        const cutoffMs = Date.now() - days * 86_400_000;
         const r = spawnSync("git", [
-            "branch",
-            "--no-column",
-            "--sort=-committerdate",
-            "--format=%(refname:short)",
-            `--since=${cutoff}`,
+            "for-each-ref",
+            "--sort=committerdate",
+            "--format=%(refname:short)\t%(committerdate:iso-strict)",
+            "refs/heads/",
         ], {
             cwd: workdir ?? process.cwd(),
             encoding: "utf-8",
@@ -524,7 +718,25 @@ function defaultGitStaleBranches(days, workdir) {
         });
         if (r.error || r.status !== 0)
             return "(git branches unavailable)";
-        return (r.stdout ?? "").trim();
+        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)";
@@ -533,26 +745,43 @@ function defaultGitStaleBranches(days, workdir) {
 /** 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(expandHome(p), "utf-8")),
+        readFile: deps.readFile ??
+            ((p) => readFileSync(resolveRecipePath(p, { workspace: workdir }), "utf-8")),
         writeFile: deps.writeFile ??
             ((p, content) => {
-                const abs = expandHome(p);
+                const abs = resolveRecipePath(p, { workspace: workdir, write: true });
                 mkdirSync(path.dirname(abs), { recursive: true });
                 writeFileSync(abs, content);
             }),
         appendFile: deps.appendFile ??
             ((p, content) => {
-                const abs = expandHome(p);
+                const abs = resolveRecipePath(p, { workspace: workdir, write: true });
                 mkdirSync(path.dirname(abs), { recursive: true });
                 appendFileSync(abs, content);
             }),
         mkdir: deps.mkdir ??
-            ((p) => mkdirSync(expandHome(p), { recursive: true })),
+            ((p) => mkdirSync(resolveRecipePath(p, { workspace: workdir, write: true }), {
+                recursive: true,
+            })),
         workdir,
         gitLogSince: deps.gitLogSince ?? defaultGitLogSince,
         gitStaleBranches: deps.gitStaleBranches ?? defaultGitStaleBranches,
-        getDiagnostics: deps.getDiagnostics ?? (() => ""),
+        // 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,
@@ -565,6 +794,11 @@ function resolveStepDeps(deps) {
                 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,
     };
@@ -746,6 +980,26 @@ export function buildChainedDeps(runnerDeps, claudeCodeFnOverride) {
         }
     }
     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
@@ -755,8 +1009,36 @@ export function buildChainedDeps(runnerDeps, claudeCodeFnOverride) {
         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) ||
@@ -771,15 +1053,24 @@ export function buildChainedDeps(runnerDeps, claudeCodeFnOverride) {
                 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;
                 }
             }
         }
-        const { homedir } = await import("node:os");
-        const recipesDir = path.join(homedir(), ".patchwork", "recipes");
+        // 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 = [
@@ -841,13 +1132,21 @@ export async function dispatchRecipe(recipe, deps, seedContext = {}) {
             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);
     }
-    return runYamlRecipe(recipe, deps, seedContext);
+    // 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) {