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

package/dist/recipeRoutes.js

@@ -29,12 +29,33 @@
 import os from "node:os";
 import path from "node:path";
 import { computeSummary as computeActivationSummary, loadMetrics as loadActivationMetrics, } from "./activationMetrics.js";
+import { isWriteKillSwitchActive } from "./featureFlags.js";
 import { consumeToken, refillBucket, } from "./fp/tokenBucket.js";
+import { respondIfUnknownBodyKeys } from "./httpBodyValidation.js";
+import { respond500 } from "./httpErrorResponse.js";
 import { validateSafeUrl } from "./ssrfGuard.js";
 // 5-minute cache of the public template registry from the patchworkos/recipes
 // GitHub repo. Process-wide; hoisted out of Server class state.
+// Sentinel `false` marks a negative-cache entry (fetch failed) — distinct from
+// `null` (never fetched) so the timestamp-based retry window is respected.
 let templatesCache = null;
 let templatesCacheTs = 0;
+/**
+ * #605: shape-validate the upstream templates payload before caching.
+ * The minimal contract used by the dashboard marketplace is `{recipes:
+ * Array}` (other fields are optional). Anything else (an error page
+ * JSON, a tampered file with a flipped key, a future GitHub schema
+ * change) is rejected so we don't serve garbage for 5 minutes to every
+ * dashboard client.
+ */
+function isWellFormedTemplatesPayload(raw) {
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+        // Some legacy callers used a bare array; accept that too.
+        return Array.isArray(raw);
+    }
+    const r = raw;
+    return Array.isArray(r.recipes);
+}
 /**
  * Per-process token bucket guarding `/recipes/generate`. Every call to the
  * route enqueues a Claude subprocess via the orchestrator — without a cap a
@@ -62,6 +83,26 @@ export function _resetGenerateRateLimitForTests() {
         lastRefill: 0,
     };
 }
+/**
+ * Phase 2A: separate cooldown bucket for `/recipes/repair`. Repair
+ * costs the same per-call tokens as generate but a user dogfooding the
+ * "Fix with AI" button may legitimately click it 2-3× back-to-back
+ * (preview a fix, discard, ask again). Giving repair its own 10/min
+ * bucket avoids starving generate when a user is iterating on repair,
+ * and the loop-hazard cap I flagged in plan-review applies here
+ * separately.
+ */
+const RECIPE_REPAIR_LIMIT_PER_MIN = 10;
+let recipeRepairBucket = {
+    tokens: RECIPE_REPAIR_LIMIT_PER_MIN,
+    lastRefill: 0,
+};
+export function _resetRepairRateLimitForTests() {
+    recipeRepairBucket = {
+        tokens: RECIPE_REPAIR_LIMIT_PER_MIN,
+        lastRefill: 0,
+    };
+}
 // G-security R2 C-3 / I-3 / F-02: HTTP `vars` validation.
 //
 // The post-render path jail in `src/recipes/resolveRecipePath.ts` is the
@@ -141,6 +182,12 @@ export const RECIPE_ROUTE_BODY_CAPS = {
     run: 32 * 1024,
     /** /recipes (POST), PUT/PATCH /recipes/:name, /recipes/lint — yaml content. */
     content: 256 * 1024,
+    /**
+     * /recipes/repair — `{ currentYaml: string, lintIssues: LintIssue[] }`.
+     * Cap matches `content` since the body carries the full recipe YAML
+     * (256 KB matches the existing PUT/POST/lint caps).
+     */
+    repair: 256 * 1024,
 };
 /**
  * Read an HTTP request body up to `max` bytes. Returns the raw string or
@@ -187,7 +234,11 @@ export function readBodyWithCap(req, max) {
         const onEnd = () => {
             if (aborted)
                 return;
-            resolve({ ok: true, body: Buffer.concat(chunks).toString("utf-8") });
+            const bytes = Buffer.concat(chunks);
+            // `bytes` is the raw on-the-wire body; `body` is the utf-8 decode used
+            // by JSON parsers. HMAC consumers must use `bytes` to avoid the
+            // utf-8 round-trip changing the signed payload.
+            resolve({ ok: true, body: bytes.toString("utf-8"), bytes });
         };
         const onError = () => {
             if (aborted)
@@ -253,6 +304,24 @@ function respondInvalidJson(res) {
     res.writeHead(400, { "Content-Type": "application/json" });
     res.end(JSON.stringify({ ok: false, error: "Invalid JSON body" }));
 }
+/**
+ * Best-effort fire of the recipe-changed notification. Wraps the
+ * callback in try/catch + console.error so a misbehaving notifier
+ * (most likely scheduler.start() throwing) cannot turn a successful
+ * disk-write into a failed-looking HTTP response. Used by install /
+ * save / delete / archive / duplicate / setEnabled / saveContent
+ * routes after their respective success paths.
+ */
+function fireOnRecipesChanged(deps) {
+    if (!deps.onRecipesChangedFn)
+        return;
+    try {
+        deps.onRecipesChangedFn();
+    }
+    catch (err) {
+        console.error(`[recipeRoutes] onRecipesChangedFn threw:`, err);
+    }
+}
 /**
  * Try to handle a recipe / run-audit / template route. Returns true if
  * the route was dispatched (caller should `return` from the request
@@ -280,6 +349,8 @@ export function tryHandleRecipeRoute(req, res, parsedUrl, deps) {
             }
             try {
                 const parsed = parsedBody.value ?? {};
+                if (respondIfUnknownBodyKeys(res, parsed, ["vars", "inputs"]))
+                    return;
                 const varsRaw = parsed.vars ?? parsed.inputs;
                 const varsErr = validateRecipeVars(varsRaw);
                 if (varsErr) {
@@ -294,7 +365,7 @@ export function tryHandleRecipeRoute(req, res, parsedUrl, deps) {
                     res.writeHead(503, { "Content-Type": "application/json" });
                     res.end(JSON.stringify({
                         ok: false,
-                        error: "Recipe execution unavailable — requires --claude-driver subprocess",
+                        error: "Recipe execution unavailable — requires --driver subprocess",
                     }));
                     return;
                 }
@@ -325,17 +396,19 @@ export function tryHandleRecipeRoute(req, res, parsedUrl, deps) {
             }
             try {
                 const parsed = parsedBody.value ?? {};
+                if (respondIfUnknownBodyKeys(res, parsed, ["name", "vars", "inputs"]))
+                    return;
                 const name = parsed.name;
-                const varsErr = validateRecipeVars(parsed.vars);
+                // #605 symmetry — accept `inputs` here like /recipes/:name/run does.
+                const varsRaw = parsed.vars ?? parsed.inputs;
+                const varsErr = validateRecipeVars(varsRaw);
                 if (varsErr) {
                     res.writeHead(400, { "Content-Type": "application/json" });
                     res.end(JSON.stringify(varsErr));
                     return;
                 }
-                const vars = parsed.vars &&
-                    typeof parsed.vars === "object" &&
-                    !Array.isArray(parsed.vars)
-                    ? parsed.vars
+                const vars = varsRaw && typeof varsRaw === "object" && !Array.isArray(varsRaw)
+                    ? varsRaw
                     : undefined;
                 if (typeof name !== "string" || !name) {
                     res.writeHead(400, { "Content-Type": "application/json" });
@@ -346,7 +419,7 @@ export function tryHandleRecipeRoute(req, res, parsedUrl, deps) {
                     res.writeHead(503, { "Content-Type": "application/json" });
                     res.end(JSON.stringify({
                         ok: false,
-                        error: "Recipe execution unavailable — requires --claude-driver subprocess",
+                        error: "Recipe execution unavailable — requires --driver subprocess",
                     }));
                     return;
                 }
@@ -370,10 +443,7 @@ export function tryHandleRecipeRoute(req, res, parsedUrl, deps) {
             res.end(JSON.stringify({ metrics, summary }));
         }
         catch (err) {
-            res.writeHead(500, { "Content-Type": "application/json" });
-            res.end(JSON.stringify({
-                error: err instanceof Error ? err.message : String(err),
-            }));
+            respond500(res, err);
         }
         return true;
     }
@@ -385,6 +455,7 @@ export function tryHandleRecipeRoute(req, res, parsedUrl, deps) {
             const trigger = sp.get("trigger");
             const status = sp.get("status");
             const recipe = sp.get("recipe");
+            const manualRunId = sp.get("manualRunId");
             const limit = limitRaw ? Number.parseInt(limitRaw, 10) : Number.NaN;
             const after = afterRaw ? Number.parseInt(afterRaw, 10) : Number.NaN;
             const runs = deps.runsFn?.({
@@ -392,19 +463,127 @@ export function tryHandleRecipeRoute(req, res, parsedUrl, deps) {
                 ...(trigger && { trigger }),
                 ...(status && { status }),
                 ...(recipe && { recipe }),
+                ...(manualRunId && { manualRunId }),
                 ...(Number.isFinite(after) && { after }),
             }) ?? [];
             res.writeHead(200, { "Content-Type": "application/json" });
             res.end(JSON.stringify({ runs }));
         }
         catch (err) {
-            res.writeHead(500, { "Content-Type": "application/json" });
-            res.end(JSON.stringify({
-                error: err instanceof Error ? err.message : String(err),
-            }));
+            respond500(res, err);
+        }
+        return true;
+    }
+    // GET /runs/halt-summary — aggregated halt categories over recent runs.
+    // Drives the dashboard /runs page header widget that answers "is the
+    // haltReason work surfacing real signal, or is everything 'unknown'?".
+    if (parsedUrl.pathname === "/runs/halt-summary" && req.method === "GET") {
+        try {
+            const sp = parsedUrl.searchParams;
+            const sinceMsRaw = sp.get("sinceMs");
+            const limitRaw = sp.get("limit");
+            const recipe = sp.get("recipe");
+            const sinceMs = sinceMsRaw ? Number.parseInt(sinceMsRaw, 10) : Number.NaN;
+            const limit = limitRaw ? Number.parseInt(limitRaw, 10) : Number.NaN;
+            const summary = deps.haltSummaryFn?.({
+                ...(Number.isFinite(sinceMs) && { sinceMs }),
+                ...(Number.isFinite(limit) && { limit }),
+                ...(recipe && { recipe }),
+            }) ?? { total: 0, byCategory: {}, recent: [] };
+            res.writeHead(200, { "Content-Type": "application/json" });
+            res.end(JSON.stringify(summary));
+        }
+        catch (err) {
+            respond500(res, err);
+        }
+        return true;
+    }
+    // GET /runs/judge-summary — PR3b sibling of /runs/halt-summary.
+    // Same query shape (sinceMs, limit, recipe), returns JudgeSummary.
+    if (parsedUrl.pathname === "/runs/judge-summary" && req.method === "GET") {
+        try {
+            const sp = parsedUrl.searchParams;
+            const sinceMsRaw = sp.get("sinceMs");
+            const limitRaw = sp.get("limit");
+            const recipe = sp.get("recipe");
+            const sinceMs = sinceMsRaw ? Number.parseInt(sinceMsRaw, 10) : Number.NaN;
+            const limit = limitRaw ? Number.parseInt(limitRaw, 10) : Number.NaN;
+            const summary = deps.judgeSummaryFn?.({
+                ...(Number.isFinite(sinceMs) && { sinceMs }),
+                ...(Number.isFinite(limit) && { limit }),
+                ...(recipe && { recipe }),
+            }) ?? { total: 0, byVerdict: {}, recent: [] };
+            res.writeHead(200, { "Content-Type": "application/json" });
+            res.end(JSON.stringify(summary));
+        }
+        catch (err) {
+            respond500(res, err);
         }
         return true;
     }
+    // GET /recipes/doctor?recipe=<name> — one-call recipe health diagnosis.
+    // Server-side home for the `recipe doctor` CLI: composes the static
+    // preflight check (lint + write-policy + plan) with the recipe-scoped
+    // runtime halt summary (reusing deps.haltSummaryFn in-process — no lock
+    // walk), each finding mapped to a fix hint. Read-only; fail-soft.
+    if (parsedUrl.pathname === "/recipes/doctor" && req.method === "GET") {
+        void (async () => {
+            try {
+                const recipe = parsedUrl.searchParams.get("recipe");
+                if (!recipe) {
+                    res.writeHead(400, { "Content-Type": "application/json" });
+                    res.end(JSON.stringify({
+                        error: "missing_recipe",
+                        message: "?recipe= is required",
+                    }));
+                    return;
+                }
+                // Name-only over HTTP — the dashboard always sends an installed
+                // recipe name. Reject path separators / traversal so this endpoint
+                // can't be coaxed into linting an arbitrary file off disk (the CLI
+                // path-resolution affordance stays CLI-only).
+                if (/[\\/]/.test(recipe) || recipe.includes("..")) {
+                    res.writeHead(400, { "Content-Type": "application/json" });
+                    res.end(JSON.stringify({
+                        error: "invalid_recipe",
+                        message: "recipe must be a bare name",
+                    }));
+                    return;
+                }
+                const { runRecipeDoctor } = await import("./commands/recipe.js");
+                const SEVEN_DAYS_MS = 7 * 24 * 60 * 60 * 1000;
+                const fetchHalts = deps.haltSummaryFn
+                    ? async (recipeName) => 
+                    // deps.haltSummaryFn is sync; the doctor contract is async.
+                    deps.haltSummaryFn?.({
+                        sinceMs: Date.now() - SEVEN_DAYS_MS,
+                        recipe: recipeName,
+                    }) ?? null
+                    : undefined;
+                const result = await runRecipeDoctor(recipe, { fetchHalts });
+                res.writeHead(200, { "Content-Type": "application/json" });
+                res.end(JSON.stringify(result));
+            }
+            catch (err) {
+                // resolveRecipePath throws "recipe ... not found" for unknown
+                // names — map that to 404; anything else is a real 500. Never echo
+                // err.message back to the client: it embeds the absolute recipes
+                // path (info-exposure / js/stack-trace-exposure). Return a static
+                // message; respond500 handles logging the detail server-side.
+                const msg = err instanceof Error ? err.message : String(err);
+                if (/not found/i.test(msg)) {
+                    res.writeHead(404, { "Content-Type": "application/json" });
+                    res.end(JSON.stringify({
+                        error: "recipe_not_found",
+                        message: "recipe not found",
+                    }));
+                    return;
+                }
+                respond500(res, err);
+            }
+        })();
+        return true;
+    }
     // GET /runs/:seq — single run detail (includes stepResults if present)
     const runDetailMatch = req.method === "GET" ? /^\/runs\/(\d+)$/.exec(parsedUrl.pathname) : null;
     if (runDetailMatch?.[1]) {
@@ -421,10 +600,7 @@ export function tryHandleRecipeRoute(req, res, parsedUrl, deps) {
             }
         }
         catch (err) {
-            res.writeHead(500, { "Content-Type": "application/json" });
-            res.end(JSON.stringify({
-                error: err instanceof Error ? err.message : String(err),
-            }));
+            respond500(res, err);
         }
         return true;
     }
@@ -458,9 +634,7 @@ export function tryHandleRecipeRoute(req, res, parsedUrl, deps) {
                 res.end(JSON.stringify(result));
             }
             catch (err) {
-                const msg = err instanceof Error ? err.message : String(err);
-                res.writeHead(500, { "Content-Type": "application/json" });
-                res.end(JSON.stringify({ error: msg }));
+                respond500(res, err, "runs/:seq detail");
             }
         })();
         return true;
@@ -491,10 +665,19 @@ export function tryHandleRecipeRoute(req, res, parsedUrl, deps) {
                 res.end(JSON.stringify({ plan }));
             }
             catch (err) {
-                const msg = err instanceof Error ? err.message : String(err);
-                const status = msg.includes("not found") || msg.includes("ENOENT") ? 404 : 500;
-                res.writeHead(status, { "Content-Type": "application/json" });
-                res.end(JSON.stringify({ error: msg }));
+                // #605: classify by error code, not message substring.
+                // Previously `msg.includes("not found")` would mis-map any
+                // deep error coincidentally containing that phrase (e.g. a
+                // connector returning "credential not found") to 404. Use the
+                // structured `code` on Node fs / our explicit error.code.
+                const code = err?.code;
+                if (code === "ENOENT" || code === "RECIPE_NOT_FOUND") {
+                    res.writeHead(404, { "Content-Type": "application/json" });
+                    res.end(JSON.stringify({ error: "Run not found" }));
+                }
+                else {
+                    respond500(res, err, "recipes plan");
+                }
             }
         })();
         return true;
@@ -545,22 +728,160 @@ export function tryHandleRecipeRoute(req, res, parsedUrl, deps) {
                 res.writeHead(503, { "Content-Type": "application/json" });
                 res.end(JSON.stringify({
                     ok: false,
-                    error: "Recipe generation unavailable — requires --claude-driver subprocess",
+                    error: "Recipe generation unavailable — requires --driver subprocess",
                     unavailable: true,
                 }));
                 return;
             }
             try {
                 const result = await deps.generateRecipeFn(prompt.trim());
+                // #605: stop collapsing every failure to 422. The dashboard
+                // can't distinguish 'driver crashed' from 'user prompt refused'
+                // from 'generated YAML failed lint' when everything maps to one
+                // status. Use the result.errorKind discriminant when present;
+                // fall back to 422 for the unstructured case.
+                let status;
+                if (result.ok) {
+                    status = 200;
+                }
+                else if (result.unavailable) {
+                    status = 503;
+                }
+                else {
+                    const kind = result.errorKind;
+                    if (kind === "driver_error" || kind === "timeout") {
+                        status = 502; // upstream failure
+                    }
+                    else if (kind === "refused" || kind === "rate_limited") {
+                        status = 429;
+                    }
+                    else if (kind === "lint_failed" || kind === "invalid_yaml") {
+                        status = 422; // semantic generation failure
+                    }
+                    else {
+                        status = 422; // unknown — preserve legacy
+                    }
+                }
+                res.writeHead(status, { "Content-Type": "application/json" });
+                res.end(JSON.stringify(result));
+            }
+            catch (err) {
+                console.error(`[recipes/generate] internal error:`, err);
+                res.writeHead(500, { "Content-Type": "application/json" });
+                res.end(JSON.stringify({
+                    ok: false,
+                    error: "Internal server error",
+                }));
+            }
+        })();
+        return true;
+    }
+    if (parsedUrl.pathname === "/recipes/repair" && req.method === "POST") {
+        // Phase 2A: LLM-driven repair of a broken recipe. Gated behind
+        // the `recipe.repair-ai` feature flag (default off) — the input
+        // body carries arbitrary YAML which may have been marketplace-
+        // installed (= untrusted), and the orchestrator-bound prompt
+        // costs API tokens per call. Same shape as /recipes/generate
+        // (rate limit + body cap + sanitization + post-lint) but a
+        // distinct token bucket so back-to-back repair clicks don't
+        // starve generate.
+        void (async () => {
+            // Flag gate first — fail fast before consuming a bucket token.
+            const { isEnabled, FLAG_REPAIR_AI } = await import("./featureFlags.js");
+            if (!isEnabled(FLAG_REPAIR_AI)) {
+                res.writeHead(503, { "Content-Type": "application/json" });
+                res.end(JSON.stringify({
+                    ok: false,
+                    code: "feature_disabled",
+                    error: "Recipe repair is gated behind the `recipe.repair-ai` feature flag (default off). Enable via the dashboard Settings → Feature flags or POST /feature-flags.",
+                    unavailable: true,
+                }));
+                return;
+            }
+            const now = Date.now();
+            const refilled = refillBucket(recipeRepairBucket, now, RECIPE_REPAIR_LIMIT_PER_MIN);
+            const consumed = consumeToken(refilled);
+            recipeRepairBucket = consumed.nextState;
+            if (!consumed.allowed) {
+                const secondsToOneToken = Math.ceil(((1 - consumed.nextState.tokens) / RECIPE_REPAIR_LIMIT_PER_MIN) * 60);
+                res.writeHead(429, {
+                    "Content-Type": "application/json",
+                    "Retry-After": String(Math.max(1, secondsToOneToken)),
+                });
+                res.end(JSON.stringify({
+                    ok: false,
+                    error: `Rate limit exceeded — max ${RECIPE_REPAIR_LIMIT_PER_MIN} repair calls per minute`,
+                    retryAfterSeconds: Math.max(1, secondsToOneToken),
+                }));
+                return;
+            }
+            const parsedBody = await readJsonBody(req, RECIPE_ROUTE_BODY_CAPS.repair);
+            if (!parsedBody.ok) {
+                if (parsedBody.code === "too_large") {
+                    respond413(res, RECIPE_ROUTE_BODY_CAPS.repair);
+                }
+                else {
+                    respondInvalidJson(res);
+                }
+                return;
+            }
+            const body = parsedBody.value;
+            const currentYaml = body?.currentYaml;
+            if (typeof currentYaml !== "string" || !currentYaml.trim()) {
+                res.writeHead(400, { "Content-Type": "application/json" });
+                res.end(JSON.stringify({
+                    ok: false,
+                    error: "currentYaml must be a non-empty string",
+                }));
+                return;
+            }
+            // Coarse shape guard on lintIssues — accept array or default to
+            // empty. Each item is structurally checked (level + message
+            // strings); unknown extras are stripped to keep the prompt
+            // surface small.
+            const rawIssues = Array.isArray(body?.lintIssues) ? body.lintIssues : [];
+            const lintIssues = [];
+            for (const raw of rawIssues) {
+                if (raw &&
+                    typeof raw === "object" &&
+                    typeof raw.message === "string" &&
+                    (raw.level === "error" ||
+                        raw.level === "warning")) {
+                    const r = raw;
+                    lintIssues.push({
+                        level: r.level,
+                        message: r.message,
+                        ...(typeof r.line === "number" && { line: r.line }),
+                        ...(typeof r.column === "number" && { column: r.column }),
+                        ...(typeof r.code === "string" && { code: r.code }),
+                        ...(typeof r.path === "string" && { path: r.path }),
+                    });
+                }
+            }
+            if (!deps.repairRecipeFn) {
+                res.writeHead(503, { "Content-Type": "application/json" });
+                res.end(JSON.stringify({
+                    ok: false,
+                    error: "Recipe repair unavailable — requires --driver subprocess",
+                    unavailable: true,
+                }));
+                return;
+            }
+            try {
+                const result = await deps.repairRecipeFn({
+                    currentYaml: currentYaml.trim(),
+                    lintIssues,
+                });
                 const status = result.ok ? 200 : result.unavailable ? 503 : 422;
                 res.writeHead(status, { "Content-Type": "application/json" });
                 res.end(JSON.stringify(result));
             }
             catch (err) {
+                console.error(`[recipes/repair] internal error:`, err);
                 res.writeHead(500, { "Content-Type": "application/json" });
                 res.end(JSON.stringify({
                     ok: false,
-                    error: err instanceof Error ? err.message : String(err),
+                    error: "Internal server error",
                 }));
             }
         })();
@@ -595,6 +916,8 @@ export function tryHandleRecipeRoute(req, res, parsedUrl, deps) {
                     return;
                 }
                 const result = deps.saveRecipeFn(draft);
+                if (result.ok)
+                    fireOnRecipesChanged(deps);
                 res.writeHead(result.ok ? 201 : 400, {
                     "Content-Type": "application/json",
                 });
@@ -623,6 +946,8 @@ export function tryHandleRecipeRoute(req, res, parsedUrl, deps) {
                 }
                 return;
             }
+            if (respondIfUnknownBodyKeys(res, parsedBody.value, ["level"]))
+                return;
             const level = parsedBody.value
                 ?.level;
             if (typeof level !== "string" || !level) {
@@ -674,6 +999,11 @@ export function tryHandleRecipeRoute(req, res, parsedUrl, deps) {
                     return;
                 }
                 const result = deps.setRecipeEnabledFn(name, body.enabled);
+                // Enable/disable changes which cron triggers should fire — the
+                // RecipeScheduler honours the disabled set on every start(), so
+                // re-priming after a toggle picks up the change without a restart.
+                if (result.ok)
+                    fireOnRecipesChanged(deps);
                 res.writeHead(result.ok ? 200 : 400, {
                     "Content-Type": "application/json",
                 });
@@ -746,10 +1076,15 @@ export function tryHandleRecipeRoute(req, res, parsedUrl, deps) {
                 res.end(JSON.stringify({ plan }));
             }
             catch (err) {
-                const msg = err instanceof Error ? err.message : String(err);
-                const status = msg.includes("not found") || msg.includes("ENOENT") ? 404 : 500;
-                res.writeHead(status, { "Content-Type": "application/json" });
-                res.end(JSON.stringify({ error: msg }));
+                // #605: classify by code, not substring (see /runs/:seq/plan).
+                const code = err?.code;
+                if (code === "ENOENT" || code === "RECIPE_NOT_FOUND") {
+                    res.writeHead(404, { "Content-Type": "application/json" });
+                    res.end(JSON.stringify({ error: "Recipe not found" }));
+                }
+                else {
+                    respond500(res, err, "recipes plan");
+                }
             }
         })();
         return true;
@@ -805,6 +1140,11 @@ export function tryHandleRecipeRoute(req, res, parsedUrl, deps) {
                     return;
                 }
                 const result = deps.saveRecipeContentFn(name, body.content);
+                // Editing recipe YAML can change cron schedule, webhook path,
+                // or trigger type entirely — re-prime the scheduler so the new
+                // shape takes effect without a bridge restart.
+                if (result.ok)
+                    fireOnRecipesChanged(deps);
                 res.writeHead(result.ok ? 200 : 400, {
                     "Content-Type": "application/json",
                 });
@@ -827,6 +1167,33 @@ export function tryHandleRecipeRoute(req, res, parsedUrl, deps) {
             return true;
         }
         const result = deps.deleteRecipeContentFn(name);
+        // Deleting a cron recipe leaves an orphaned interval in the scheduler
+        // until the next start() — re-prime so it goes away.
+        if (result.ok)
+            fireOnRecipesChanged(deps);
+        const status = result.ok
+            ? 200
+            : result.error === "Recipe not found"
+                ? 404
+                : 400;
+        res.writeHead(status, { "Content-Type": "application/json" });
+        res.end(JSON.stringify(result));
+        return true;
+    }
+    // POST /recipes/:name/archive — move recipe (+ sidecar) into <recipesDir>/.archive/
+    const archiveMatch = /^\/recipes\/([^/]+)\/archive$/.exec(parsedUrl.pathname);
+    if (archiveMatch && req.method === "POST") {
+        const name = decodeURIComponent(archiveMatch[1] ?? "");
+        if (!deps.archiveRecipeFn) {
+            res.writeHead(503, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ ok: false, error: "Recipe archive unavailable" }));
+            return true;
+        }
+        const result = deps.archiveRecipeFn(name);
+        // Archiving moves the recipe under .archive/ where the scheduler
+        // ignores it — same orphan-interval cleanup needed as for delete.
+        if (result.ok)
+            fireOnRecipesChanged(deps);
         const status = result.ok
             ? 200
             : result.error === "Recipe not found"
@@ -846,6 +1213,10 @@ export function tryHandleRecipeRoute(req, res, parsedUrl, deps) {
             return true;
         }
         const result = deps.duplicateRecipeFn(name);
+        // Duplication adds a new recipe file to the dir — re-prime so any
+        // cron trigger inside the duplicate starts firing immediately.
+        if (result.ok)
+            fireOnRecipesChanged(deps);
         const status = result.ok
             ? 201
             : result.error === "Recipe not found"
@@ -863,10 +1234,21 @@ export function tryHandleRecipeRoute(req, res, parsedUrl, deps) {
         void (async () => {
             const parsedBody = await readJsonBody(req, RECIPE_ROUTE_BODY_CAPS.content);
             if (!parsedBody.ok) {
-                respondInvalidJson(res);
+                // #605: distinguish too_large (413) from invalid JSON (400) —
+                // sibling routes already do this; promote was the only handler
+                // collapsing both to 400.
+                if (parsedBody.code === "too_large") {
+                    respond413(res, RECIPE_ROUTE_BODY_CAPS.content);
+                }
+                else {
+                    respondInvalidJson(res);
+                }
                 return;
             }
-            const { targetName, force } = parsedBody.value ?? {};
+            const promoteBody = parsedBody.value ?? {};
+            if (respondIfUnknownBodyKeys(res, promoteBody, ["targetName", "force"]))
+                return;
+            const { targetName, force } = promoteBody;
             if (typeof targetName !== "string" || !targetName.trim()) {
                 res.writeHead(400, { "Content-Type": "application/json" });
                 res.end(JSON.stringify({ ok: false, error: "targetName required" }));
@@ -881,6 +1263,10 @@ export function tryHandleRecipeRoute(req, res, parsedUrl, deps) {
                 const result = await deps.promoteRecipeVariantFn(variantName, targetName, {
                     force: force === true,
                 });
+                // Promotion overwrites the canonical file with the variant's
+                // contents — same scheduler refresh story as save/edit.
+                if (result.ok)
+                    fireOnRecipesChanged(deps);
                 const httpStatus = result.ok
                     ? 200
                     : result.targetExists
@@ -892,10 +1278,11 @@ export function tryHandleRecipeRoute(req, res, parsedUrl, deps) {
                 res.end(JSON.stringify(result));
             }
             catch (err) {
+                console.error(`[recipes/install] internal error:`, err);
                 res.writeHead(500, { "Content-Type": "application/json" });
                 res.end(JSON.stringify({
                     ok: false,
-                    error: err instanceof Error ? err.message : String(err),
+                    error: "Internal server error",
                 }));
             }
         })();
@@ -908,10 +1295,7 @@ export function tryHandleRecipeRoute(req, res, parsedUrl, deps) {
             res.end(JSON.stringify(data));
         }
         catch (err) {
-            res.writeHead(500, { "Content-Type": "application/json" });
-            res.end(JSON.stringify({
-                error: err instanceof Error ? err.message : String(err),
-            }));
+            respond500(res, err);
         }
         return true;
     }
@@ -919,22 +1303,46 @@ export function tryHandleRecipeRoute(req, res, parsedUrl, deps) {
         void (async () => {
             try {
                 const now = Date.now();
-                if (!templatesCache || now - templatesCacheTs > 5 * 60 * 1000) {
+                if (templatesCache === null || now - templatesCacheTs > 5 * 60 * 1000) {
                     const ghRes = await fetch("https://raw.githubusercontent.com/patchworkos/recipes/main/index.json");
                     if (!ghRes.ok) {
                         throw new Error(`GitHub returned ${ghRes.status}`);
                     }
-                    templatesCache = (await ghRes.json());
+                    // #605: validate content-type AND shape before caching.
+                    // Previously we just `await ghRes.json()` and cached whatever
+                    // came back for 5 minutes — any error page (HTML/text JSON),
+                    // any MITM-tampered payload, or any future GitHub schema
+                    // change would poison the cache for every dashboard client.
+                    const ct = ghRes.headers.get("content-type") ?? "";
+                    if (!ct.includes("application/json") && !ct.includes("text/plain")) {
+                        throw new Error(`GitHub returned non-JSON content-type: ${ct}`);
+                    }
+                    const raw = (await ghRes.json());
+                    if (!isWellFormedTemplatesPayload(raw)) {
+                        throw new Error("GitHub payload failed shape validation");
+                    }
+                    templatesCache = raw;
                     templatesCacheTs = now;
                 }
+                if (templatesCache === false) {
+                    res.writeHead(502, { "Content-Type": "application/json" });
+                    res.end(JSON.stringify({ ok: false, error: "Upstream fetch failed" }));
+                    return;
+                }
                 res.writeHead(200, { "Content-Type": "application/json" });
                 res.end(JSON.stringify(templatesCache));
             }
             catch (err) {
+                console.error(`[recipes/templates] upstream error:`, err);
+                // #605: negative cache — short window so an upstream 502 doesn't
+                // pile up requests; clients see a fast 502 instead of waiting
+                // for the next GH round-trip.
+                templatesCache = false; // negative-cache sentinel — prevents !templatesCache bypass
+                templatesCacheTs = Date.now() - 5 * 60 * 1000 + 30_000; // 30s before next try
                 res.writeHead(502, { "Content-Type": "application/json" });
                 res.end(JSON.stringify({
                     ok: false,
-                    error: err instanceof Error ? err.message : String(err),
+                    error: "Upstream fetch failed",
                 }));
             }
         })();
@@ -953,6 +1361,23 @@ export function tryHandleRecipeRoute(req, res, parsedUrl, deps) {
         // an explicitly-allowlisted hostname STILL has to clear the SSRF check
         // (so an admin can't accidentally allowlist `localhost`).
         // ---------------------------------------------------------------------
+        //
+        // Marketplace trust Wave 0 (#782 follow-up): gate the route on the
+        // global write kill-switch. Install writes recipe files to disk;
+        // when an operator engages `PATCHWORK_FLAG_KILL_SWITCH_WRITES` or
+        // flips the `kill-switch.writes` flag, this previously kept writing
+        // anyway — a latent trust gap. Returns 503 with a code the
+        // dashboard can match against to render the right banner.
+        if (isWriteKillSwitchActive()) {
+            res.writeHead(503, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({
+                ok: false,
+                code: "kill_switch_blocked",
+                error: "Recipe install blocked by kill switch (PATCHWORK_FLAG_KILL_SWITCH_WRITES / kill-switch.writes). " +
+                    "Unset the env var or POST /kill-switch with {engaged:false} to restore.",
+            }));
+            return true;
+        }
         void (async () => {
             const parsedBody = await readJsonBody(req, RECIPE_ROUTE_BODY_CAPS.install);
             if (!parsedBody.ok) {
@@ -974,58 +1399,59 @@ export function tryHandleRecipeRoute(req, res, parsedUrl, deps) {
                 // -----------------------------------------------------------------
                 // BUNDLE INSTALL DISPATCH (#130 PR A).
                 //
-                // `github:patchworkos/recipes/bundles/<name>` installs every recipe
+                // `github:<owner>/<repo>/bundles/<name>` installs every recipe
                 // listed in the bundle's `patchwork-bundle.json`. Plugin (`plugin`)
                 // and policy template (`policy_template`) declared in the manifest
                 // are surfaced as advisory-only — wiring those needs separate
                 // decisions (npm-install surface, policy application UX) tracked
-                // outside this PR. See the #130 scoping comment.
+                // outside this PR.
+                //
+                // Org allowlist (#audit-thread): historically the path was hard-
+                // coded to `patchworkos/recipes`. Now any allowlisted org/repo
+                // can host a bundle; parse + validate via the shared helper so
+                // single-recipe and bundle install share one source-of-truth.
                 // -----------------------------------------------------------------
-                const bundlePrefix = "github:patchworkos/recipes/bundles/";
-                if (source.startsWith(bundlePrefix)) {
-                    const bundleName = source.slice(bundlePrefix.length);
-                    const { isSafeBasename } = await import("./commands/recipeInstall.js");
-                    if (!isSafeBasename(bundleName)) {
-                        res.writeHead(400, { "Content-Type": "application/json" });
-                        res.end(JSON.stringify({
-                            ok: false,
-                            error: "Invalid bundle name in source",
-                            code: "invalid_bundle_name",
-                        }));
-                        return;
-                    }
-                    const manifestUrl = `https://raw.githubusercontent.com/patchworkos/recipes/main/bundles/${bundleName}/patchwork-bundle.json`;
+                const bundleParse = source.startsWith("github:")
+                    ? await (async () => {
+                        const { parseGithubInstallSource } = await import("./recipes/githubInstallSource.js");
+                        return parseGithubInstallSource(source);
+                    })()
+                    : null;
+                if (bundleParse?.ok && bundleParse.parsed.kind === "bundle") {
+                    const { buildGithubRawUrl, fetchGithubInstallFile, SEGMENT_RE } = await import("./recipes/githubInstallSource.js");
+                    const bundleName = bundleParse.parsed.name;
+                    const bundleOwner = bundleParse.parsed.owner;
+                    const bundleRepo = bundleParse.parsed.repo;
+                    const manifestUrl = buildGithubRawUrl(bundleParse.parsed);
                     const ctl = new AbortController();
                     const timeout = setTimeout(() => ctl.abort(), 30_000);
-                    let manifestRes;
-                    try {
-                        manifestRes = await fetch(manifestUrl, {
-                            signal: ctl.signal,
-                            redirect: "follow",
-                        });
-                    }
-                    catch (err) {
-                        clearTimeout(timeout);
-                        res.writeHead(502, { "Content-Type": "application/json" });
-                        res.end(JSON.stringify({
-                            ok: false,
-                            error: `Bundle manifest fetch failed: ${err instanceof Error ? err.message : String(err)}`,
-                            code: "bundle_fetch_network_error",
-                        }));
-                        return;
-                    }
+                    // Raw-first / api.github.com-fallback: raw.githubusercontent.com
+                    // is blocked on many corporate / proxied networks.
+                    const manifestFetched = await fetchGithubInstallFile(bundleParse.parsed, { signal: ctl.signal });
                     clearTimeout(timeout);
-                    if (!manifestRes.ok) {
-                        const outStatus = manifestRes.status === 404 ? 404 : 502;
+                    if (!manifestFetched.ok) {
+                        if (manifestFetched.kind === "network_error") {
+                            console.error(`[recipes/install] bundle manifest fetch failed (raw + api):`, manifestFetched.error);
+                            res.writeHead(502, { "Content-Type": "application/json" });
+                            res.end(JSON.stringify({
+                                ok: false,
+                                error: "Bundle manifest fetch failed",
+                                code: "bundle_fetch_network_error",
+                            }));
+                            return;
+                        }
+                        const failRes = manifestFetched.response;
+                        const outStatus = failRes.status === 404 ? 404 : 502;
                         res.writeHead(outStatus, { "Content-Type": "application/json" });
                         res.end(JSON.stringify({
                             ok: false,
-                            error: `Bundle manifest at ${manifestUrl} returned ${manifestRes.status}`,
+                            error: `Bundle manifest at ${manifestUrl} returned ${failRes.status}`,
                             code: "bundle_fetch_upstream_error",
-                            upstreamStatus: manifestRes.status,
+                            upstreamStatus: failRes.status,
                         }));
                         return;
                     }
+                    const manifestRes = manifestFetched.response;
                     // 64 KB hard cap on manifest body — real `patchwork-bundle.json`
                     // is single-digit KB; anything past 64 KB is hostile or malformed.
                     const manifestBuf = await manifestRes.arrayBuffer();
@@ -1043,14 +1469,19 @@ export function tryHandleRecipeRoute(req, res, parsedUrl, deps) {
                         manifest = JSON.parse(Buffer.from(manifestBuf).toString("utf-8"));
                     }
                     catch (err) {
+                        console.error(`[recipes/install] bundle manifest invalid JSON:`, err);
                         res.writeHead(502, { "Content-Type": "application/json" });
                         res.end(JSON.stringify({
                             ok: false,
-                            error: `Bundle manifest is not valid JSON: ${err instanceof Error ? err.message : String(err)}`,
+                            error: "Bundle manifest is not valid JSON",
                             code: "bundle_manifest_invalid_json",
                         }));
                         return;
                     }
+                    // Validate each declared recipe basename to block traversal +
+                    // junk segments. `isSafeBasename` lives in the legacy recipe-
+                    // install command but the predicate is the right shape here.
+                    const { isSafeBasename } = await import("./commands/recipeInstall.js");
                     if (!Array.isArray(manifest.recipes) ||
                         manifest.recipes.length === 0 ||
                         !manifest.recipes.every((r) => typeof r === "string" && isSafeBasename(r))) {
@@ -1067,27 +1498,57 @@ export function tryHandleRecipeRoute(req, res, parsedUrl, deps) {
                     // all-or-nothing when one of N recipes is broken.
                     const installed = [];
                     const failures = [];
-                    const { writeFileSync, mkdirSync, unlinkSync } = await import("node:fs");
+                    // Wave 1 fix: aggregate connector preflight across every
+                    // bundle-installed recipe so the dashboard can surface a
+                    // single "you need to connect Gmail + Slack + Calendar before
+                    // running these" notice, matching the single-recipe install's
+                    // missingConnectors behaviour. Previously bundle installs
+                    // returned no preflight hint → users hit first-run "no Slack
+                    // token" surprise on every recipe.
+                    const aggregatedMissingConnectors = new Set();
+                    const { writeFileSync, mkdirSync, unlinkSync, readFileSync } = await import("node:fs");
                     const { installRecipeFromFile } = await import("./recipes/installer.js");
                     const recipesDir = path.join(os.homedir(), ".patchwork", "recipes");
                     mkdirSync(recipesDir, { recursive: true });
                     for (const r of manifest.recipes) {
-                        const recipeUrl = `https://raw.githubusercontent.com/patchworkos/recipes/main/recipes/${r}/${r}.yaml`;
+                        // The recipe name comes from the bundle manifest's JSON body
+                        // (GitHub-hosted, but still external input). Validate it
+                        // before it reaches URL construction in fetchGithubInstallFile
+                        // — the `github:` source path gets this check via
+                        // parseGithubInstallSource, but the bundle loop builds the
+                        // struct directly and would otherwise bypass it.
+                        if (typeof r !== "string" || !SEGMENT_RE.test(r.toLowerCase())) {
+                            failures.push({
+                                name: String(r),
+                                error: "invalid recipe name in bundle manifest",
+                            });
+                            continue;
+                        }
+                        // Bundle's manifest is allowed to declare recipes that
+                        // live in the same repo as the bundle. Fetch with the
+                        // parsed owner/repo via the raw-first / api.github.com
+                        // fallback (raw host blocked on many proxied networks).
                         const recipeCtl = new AbortController();
                         const recipeTimeout = setTimeout(() => recipeCtl.abort(), 30_000);
                         try {
-                            const recipeRes = await fetch(recipeUrl, {
-                                signal: recipeCtl.signal,
-                                redirect: "follow",
-                            });
+                            const recipeFetched = await fetchGithubInstallFile({
+                                kind: "recipe",
+                                owner: bundleOwner,
+                                repo: bundleRepo,
+                                name: r,
+                            }, { signal: recipeCtl.signal });
                             clearTimeout(recipeTimeout);
-                            if (!recipeRes.ok) {
+                            if (!recipeFetched.ok) {
+                                if (recipeFetched.kind === "network_error") {
+                                    throw recipeFetched.error;
+                                }
                                 failures.push({
                                     name: r,
-                                    error: `Upstream returned ${recipeRes.status}`,
+                                    error: `Upstream returned ${recipeFetched.response.status}`,
                                 });
                                 continue;
                             }
+                            const recipeRes = recipeFetched.response;
                             const recipeBuf = await recipeRes.arrayBuffer();
                             if (recipeBuf.byteLength > 1024 * 1024) {
                                 failures.push({
@@ -1097,13 +1558,47 @@ export function tryHandleRecipeRoute(req, res, parsedUrl, deps) {
                                 continue;
                             }
                             const yamlText = Buffer.from(recipeBuf).toString("utf-8");
-                            const tmpFile = path.join(os.tmpdir(), `patchwork-bundle-install-${Date.now()}-${r}.yaml`);
+                            // #605: same race-fix as /recipes/install — embed pid +
+                            // randomBytes so concurrent bundle installs of the same
+                            // recipe inside one millisecond don't collide.
+                            const { randomBytes: randomBytesFn } = await import("node:crypto");
+                            const tmpFile = path.join(os.tmpdir(), `patchwork-bundle-install-${process.pid}-${Date.now()}-${randomBytesFn(6).toString("hex")}-${r}.yaml`);
                             writeFileSync(tmpFile, yamlText, "utf-8");
                             try {
                                 const installResult = installRecipeFromFile(tmpFile, {
                                     recipesDir,
                                 });
                                 installed.push({ name: r, action: installResult.action });
+                                // Per-recipe connector preflight — same shape as the
+                                // single-recipe path (lines ~2005+). Defensive: any
+                                // failure must not roll back the install.
+                                try {
+                                    const installedJson = readFileSync(installResult.installedPath, "utf-8");
+                                    const recipeForPreflight = JSON.parse(installedJson);
+                                    if (Array.isArray(recipeForPreflight.steps)) {
+                                        const { detectRequiredConnectors, findMissingConnectors } = await import("./recipes/connectorPreflight.js");
+                                        const required = detectRequiredConnectors(recipeForPreflight);
+                                        if (required.length > 0) {
+                                            const { handleConnectionsList } = await import("./connectors/gmail.js");
+                                            const connsResult = await handleConnectionsList();
+                                            let connections = [];
+                                            try {
+                                                const body = JSON.parse(connsResult.body);
+                                                connections = body.connectors ?? [];
+                                            }
+                                            catch {
+                                                /* malformed body — treat as no connections */
+                                            }
+                                            const missing = findMissingConnectors(required, connections);
+                                            for (const id of missing) {
+                                                aggregatedMissingConnectors.add(id);
+                                            }
+                                        }
+                                    }
+                                }
+                                catch (preflightErr) {
+                                    console.warn(`[recipes/install] bundle preflight for "${r}" failed (non-blocking):`, preflightErr);
+                                }
                             }
                             finally {
                                 try {
@@ -1116,9 +1611,10 @@ export function tryHandleRecipeRoute(req, res, parsedUrl, deps) {
                         }
                         catch (err) {
                             clearTimeout(recipeTimeout);
+                            console.error(`[recipes/install] recipe "${r}" failed:`, err);
                             failures.push({
                                 name: r,
-                                error: err instanceof Error ? err.message : String(err),
+                                error: "Recipe install failed",
                             });
                         }
                     }
@@ -1133,6 +1629,14 @@ export function tryHandleRecipeRoute(req, res, parsedUrl, deps) {
                     // 200 if any recipe installed; 502 otherwise. Always include both
                     // arrays so callers (CLI + dashboard) can render partial-success.
                     const status = installed.length > 0 ? 200 : 502;
+                    // Notify the scheduler so cron-trigger recipes in the bundle
+                    // start firing without a bridge restart. Fired once per bundle
+                    // (not per recipe inside) since scheduler.start() reads the
+                    // whole recipes dir anyway. Guarded by the partial-success
+                    // check — no point waking up the scheduler for a 0-installed
+                    // failure.
+                    if (installed.length > 0)
+                        fireOnRecipesChanged(deps);
                     res.writeHead(status, { "Content-Type": "application/json" });
                     res.end(JSON.stringify({
                         ok: installed.length > 0,
@@ -1140,28 +1644,54 @@ export function tryHandleRecipeRoute(req, res, parsedUrl, deps) {
                         bundleName,
                         installed,
                         failures,
+                        ...(aggregatedMissingConnectors.size > 0 && {
+                            missingConnectors: Array.from(aggregatedMissingConnectors),
+                        }),
                         ...(Object.keys(advisory).length > 0 && { advisory }),
                     }));
                     return;
                 }
-                const githubPrefix = "github:patchworkos/recipes/recipes/";
                 let fetchUrl;
                 let recipeName;
-                if (source.startsWith(githubPrefix)) {
-                    recipeName = source.slice(githubPrefix.length);
-                    // The constructed URL is internal — recipeName must be a safe
-                    // single-segment so we don't end up encoding `../etc/passwd` into
-                    // the path. Reuse the strict basename predicate from `recipeInstall`.
-                    const { isSafeBasename } = await import("./commands/recipeInstall.js");
-                    if (!isSafeBasename(recipeName)) {
+                // When the source is a `github:` shorthand we keep the parsed
+                // form around so the fetch leg below can use the raw-first /
+                // api.github.com-fallback strategy (raw is blocked on many
+                // corporate / proxied networks). Non-github `https://` sources
+                // fetch the URL directly, unchanged.
+                let githubParsed = null;
+                if (source.startsWith("github:")) {
+                    // Parse the new generalised shape (any allowlisted org/repo)
+                    // instead of only `github:patchworkos/recipes/recipes/<name>`.
+                    // Distinguishes bad shape (400) from not-on-allowlist (403)
+                    // so operators can spot a config error vs. a typo.
+                    const { parseGithubInstallSource, buildGithubRawUrl } = await import("./recipes/githubInstallSource.js");
+                    const parsed = parseGithubInstallSource(source);
+                    if (!parsed.ok) {
+                        const status = parsed.code === "not_allowlisted" ? 403 : 400;
+                        res.writeHead(status, { "Content-Type": "application/json" });
+                        res.end(JSON.stringify({
+                            ok: false,
+                            error: parsed.error,
+                            code: parsed.code,
+                        }));
+                        return;
+                    }
+                    // Bundle shape on /recipes/install (single-recipe path) is a
+                    // mistake — surface it explicitly rather than silently fetching
+                    // an unrelated URL. Bundle installs have their own code path
+                    // above this block.
+                    if (parsed.parsed.kind === "bundle") {
                         res.writeHead(400, { "Content-Type": "application/json" });
                         res.end(JSON.stringify({
                             ok: false,
-                            error: "Invalid recipe name in source",
+                            error: "Bundle source on single-recipe install. Use the bundle install path.",
+                            code: "bad_shape",
                         }));
                         return;
                     }
-                    fetchUrl = `https://raw.githubusercontent.com/patchworkos/recipes/main/recipes/${recipeName}/${recipeName}.yaml`;
+                    recipeName = parsed.parsed.name;
+                    githubParsed = parsed.parsed;
+                    fetchUrl = buildGithubRawUrl(parsed.parsed);
                 }
                 else if (source.startsWith("https://")) {
                     // Non-github source: must clear the env-var allowlist AND the SSRF
@@ -1231,42 +1761,88 @@ export function tryHandleRecipeRoute(req, res, parsedUrl, deps) {
                 const fetchCtl = new AbortController();
                 const fetchTimeout = setTimeout(() => fetchCtl.abort(), 30_000);
                 let yamlRes;
-                try {
-                    yamlRes = await fetch(fetchUrl, {
+                if (githubParsed) {
+                    // github: source — try raw.githubusercontent.com first, then
+                    // fall back to api.github.com/contents (raw host is blocked on
+                    // many corporate / proxied networks). The fallback collapses
+                    // back into the SAME error contract as the direct path below.
+                    const { fetchGithubInstallFile } = await import("./recipes/githubInstallSource.js");
+                    const fetched = await fetchGithubInstallFile(githubParsed, {
                         signal: fetchCtl.signal,
-                        redirect: "follow",
                     });
-                }
-                catch (err) {
                     clearTimeout(fetchTimeout);
-                    // Network-level error → 502 (upstream unreachable), not 500.
-                    res.writeHead(502, { "Content-Type": "application/json" });
-                    res.end(JSON.stringify({
-                        ok: false,
-                        error: `Fetch failed: ${err instanceof Error ? err.message : String(err)}`,
-                        code: "fetch_network_error",
-                    }));
-                    return;
+                    if (!fetched.ok) {
+                        if (fetched.kind === "network_error") {
+                            console.error(`[recipes/install] fetch failed (raw + api):`, fetched.error);
+                            // Network-level error → 502 (upstream unreachable), not 500.
+                            res.writeHead(502, { "Content-Type": "application/json" });
+                            res.end(JSON.stringify({
+                                ok: false,
+                                error: "Fetch failed",
+                                code: "fetch_network_error",
+                            }));
+                            return;
+                        }
+                        // not_found / upstream_error — translate the HTTP status the
+                        // same way the direct path does.
+                        const failRes = fetched.response;
+                        let outStatus = 502;
+                        if (failRes.status === 404)
+                            outStatus = 404;
+                        else if (failRes.status === 403)
+                            outStatus = 403;
+                        else if (failRes.status >= 400 && failRes.status < 500)
+                            outStatus = 400;
+                        res.writeHead(outStatus, { "Content-Type": "application/json" });
+                        res.end(JSON.stringify({
+                            ok: false,
+                            error: `Upstream returned ${failRes.status} ${failRes.statusText}`,
+                            code: "fetch_upstream_error",
+                            upstreamStatus: failRes.status,
+                        }));
+                        return;
+                    }
+                    yamlRes = fetched.response;
                 }
-                clearTimeout(fetchTimeout);
-                if (!yamlRes.ok) {
-                    // Translate upstream HTTP into proper status — 404→404, 403→403,
-                    // 5xx→502 (don't leak the upstream 500 as our 500). R2 H-routes Bug 2.
-                    let outStatus = 502;
-                    if (yamlRes.status === 404)
-                        outStatus = 404;
-                    else if (yamlRes.status === 403)
-                        outStatus = 403;
-                    else if (yamlRes.status >= 400 && yamlRes.status < 500)
-                        outStatus = 400;
-                    res.writeHead(outStatus, { "Content-Type": "application/json" });
-                    res.end(JSON.stringify({
-                        ok: false,
-                        error: `Upstream returned ${yamlRes.status} ${yamlRes.statusText}`,
-                        code: "fetch_upstream_error",
-                        upstreamStatus: yamlRes.status,
-                    }));
-                    return;
+                else {
+                    try {
+                        yamlRes = await fetch(fetchUrl, {
+                            signal: fetchCtl.signal,
+                            redirect: "follow",
+                        });
+                    }
+                    catch (err) {
+                        clearTimeout(fetchTimeout);
+                        console.error(`[recipes/install] fetch failed:`, err);
+                        // Network-level error → 502 (upstream unreachable), not 500.
+                        res.writeHead(502, { "Content-Type": "application/json" });
+                        res.end(JSON.stringify({
+                            ok: false,
+                            error: "Fetch failed",
+                            code: "fetch_network_error",
+                        }));
+                        return;
+                    }
+                    clearTimeout(fetchTimeout);
+                    if (!yamlRes.ok) {
+                        // Translate upstream HTTP into proper status — 404→404, 403→403,
+                        // 5xx→502 (don't leak the upstream 500 as our 500). R2 H-routes Bug 2.
+                        let outStatus = 502;
+                        if (yamlRes.status === 404)
+                            outStatus = 404;
+                        else if (yamlRes.status === 403)
+                            outStatus = 403;
+                        else if (yamlRes.status >= 400 && yamlRes.status < 500)
+                            outStatus = 400;
+                        res.writeHead(outStatus, { "Content-Type": "application/json" });
+                        res.end(JSON.stringify({
+                            ok: false,
+                            error: `Upstream returned ${yamlRes.status} ${yamlRes.statusText}`,
+                            code: "fetch_upstream_error",
+                            upstreamStatus: yamlRes.status,
+                        }));
+                        return;
+                    }
                 }
                 // Streamed read with 1 MB cap (mirrors `httpClient` pattern).
                 const MAX_RECIPE_BYTES = 1024 * 1024;
@@ -1303,7 +1879,13 @@ export function tryHandleRecipeRoute(req, res, parsedUrl, deps) {
                     return;
                 }
                 const yamlText = Buffer.concat(chunks.map((c) => Buffer.from(c))).toString("utf-8");
-                const tmpFile = path.join(os.tmpdir(), `patchwork-install-${Date.now()}-${recipeName}.yaml`);
+                // #605: temp path must be unique per process+request. Previous
+                // form was `Date.now()-${recipeName}` — two concurrent installs
+                // of the same recipe inside one millisecond produced identical
+                // paths → writeFileSync interleaved bytes, and the first finally
+                // block unlinked the file the second still needed.
+                const { randomBytes } = await import("node:crypto");
+                const tmpFile = path.join(os.tmpdir(), `patchwork-install-${process.pid}-${Date.now()}-${randomBytes(6).toString("hex")}-${recipeName}.yaml`);
                 const { writeFileSync, mkdirSync, unlinkSync } = await import("node:fs");
                 writeFileSync(tmpFile, yamlText, "utf-8");
                 let result;
@@ -1314,7 +1896,46 @@ export function tryHandleRecipeRoute(req, res, parsedUrl, deps) {
                     const installResult = installRecipeFromFile(tmpFile, {
                         recipesDir,
                     });
-                    result = { action: installResult.action, name: recipeName };
+                    // Soft preflight: detect which connectors the recipe uses
+                    // and surface the unconfigured ones as a warning. The recipe
+                    // is already on disk — this is a hint for the dashboard to
+                    // prompt "you'll need to connect Slack + Gmail to run this",
+                    // not a gate on the install itself. Defensive: any failure
+                    // here MUST NOT roll the install back, so the whole block is
+                    // wrapped in try/catch.
+                    let missingConnectors;
+                    try {
+                        const { readFileSync } = await import("node:fs");
+                        const installedJson = readFileSync(installResult.installedPath, "utf-8");
+                        const recipe = JSON.parse(installedJson);
+                        if (Array.isArray(recipe.steps)) {
+                            const { detectRequiredConnectors, findMissingConnectors } = await import("./recipes/connectorPreflight.js");
+                            const required = detectRequiredConnectors(recipe);
+                            if (required.length > 0) {
+                                const { handleConnectionsList } = await import("./connectors/gmail.js");
+                                const connsResult = await handleConnectionsList();
+                                let connections = [];
+                                try {
+                                    const body = JSON.parse(connsResult.body);
+                                    connections = body.connectors ?? [];
+                                }
+                                catch {
+                                    /* malformed body — treat as no connections */
+                                }
+                                const missing = findMissingConnectors(required, connections);
+                                if (missing.length > 0)
+                                    missingConnectors = missing;
+                            }
+                        }
+                    }
+                    catch (preflightErr) {
+                        console.warn(`[recipes/install] connector preflight failed (non-blocking):`, preflightErr);
+                    }
+                    result = {
+                        action: installResult.action,
+                        name: recipeName,
+                        ...(missingConnectors ? { missingConnectors } : {}),
+                    };
                 }
                 finally {
                     try {
@@ -1324,15 +1945,47 @@ export function tryHandleRecipeRoute(req, res, parsedUrl, deps) {
                         // best-effort cleanup
                     }
                 }
+                // Notify the scheduler so the new recipe's cron/webhook trigger
+                // starts firing without a bridge restart. The recipe file is
+                // already on disk (`writeFileSync` above), so the next
+                // `scheduler.start()` will pick it up via its directory scan.
+                // Errors here are logged but never surface to the caller — the
+                // install itself succeeded; a scheduler restart bug must not
+                // make the response look failed.
+                fireOnRecipesChanged(deps);
                 res.writeHead(200, { "Content-Type": "application/json" });
                 res.end(JSON.stringify({ ok: true, ...result }));
             }
             catch (err) {
-                // Truly unexpected — installer crash, manifest validation throw, etc.
+                // Distinguish "the recipe YAML is malformed" (user-actionable, 400)
+                // from "the installer itself crashed" (server bug, 500). Before this
+                // every parser error came back as the same opaque 500 — dashboards
+                // surfaced "Internal server error" with no way to know what was wrong.
+                const errName = err instanceof Error ? err.name : "";
+                const errMsg = err instanceof Error ? err.message : String(err);
+                const isParseError = errName === "RecipeParseError" ||
+                    // js-yaml / the `yaml` package both throw YAMLException / YAMLParseError.
+                    errName === "YAMLException" ||
+                    errName === "YAMLParseError" ||
+                    /yaml/i.test(errName);
+                if (isParseError) {
+                    // Return only the first line of the parser message — strips any
+                    // embedded file path or stack frame that downstream parsers
+                    // sometimes include (CodeQL: js/stack-trace-exposure).
+                    const safeMsg = errMsg.split("\n", 1)[0]?.slice(0, 500) ?? "invalid recipe";
+                    res.writeHead(400, { "Content-Type": "application/json" });
+                    res.end(JSON.stringify({
+                        ok: false,
+                        error: safeMsg,
+                        code: "invalid_recipe",
+                    }));
+                    return;
+                }
+                console.error(`[recipes/install] internal install error:`, err);
                 res.writeHead(500, { "Content-Type": "application/json" });
                 res.end(JSON.stringify({
                     ok: false,
-                    error: err instanceof Error ? err.message : String(err),
+                    error: "Internal server error",
                     code: "install_internal_error",
                 }));
             }