patchwork-os 0.2.0-beta.1 → 0.2.0-beta.10.canary.100

package/dist/commands/recipe.js

@@ -11,10 +11,12 @@ import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
 import "../recipes/tools/index.js";
 import { loadFixtureLibrary } from "../connectors/fixtureLibrary.js";
 import { MockConnector } from "../connectors/mockConnector.js";
-import { defaultDeprecationWarn, normalizeRecipeForRuntime, } from "../recipes/legacyRecipeCompat.js";
+import { detectRequiredConnectors, findMissingConnectors, } from "../recipes/connectorPreflight.js";
+import { HALT_CATEGORY_HINTS, HALT_CATEGORY_LABELS, } from "../recipes/haltCategory.js";
+import { defaultDeprecationWarn, normalizeRecipeForRuntime, } from "../recipes/migrations/index.js";
 import { tryResolveRecipePath } from "../recipes/resolveRecipePath.js";
 import { generateSchemaSet, writeSchemas } from "../recipes/schemaGenerator.js";
-import { getTool, isConnectorNamespace, seedToolOutputPreviewContext, } from "../recipes/toolRegistry.js";
+import { getTool, isConnectorNamespace, listConnectorNamespaces, listTools, seedToolOutputPreviewContext, } from "../recipes/toolRegistry.js";
 import { validateRecipeDefinition, } from "../recipes/validation.js";
 import { buildChainedDeps, dispatchRecipe, loadYamlRecipe, render, runYamlRecipe, } from "../recipes/yamlRunner.js";
 import { findYamlRecipePath } from "../recipesHttp.js";
@@ -113,6 +115,355 @@ export function runNew(options) {
 export function listTemplates() {
     return Object.keys(TEMPLATES);
 }
+// ============================================================================
+// patchwork recipe new --interactive
+//
+// Connector-aware prompt tree. Writes a valid recipe YAML based on
+// user choices. Use a `node:readline/promises` adapter in real CLI;
+// tests inject a stub `InteractivePromptDeps`.
+// ============================================================================
+const RECIPE_NAME_RE = /^[a-z0-9][a-z0-9_-]{1,63}$/;
+const CRON_SHAPE_RE = /^(@every\s+\d+\s*(ms|s|m|h)|\S+\s+\S+\s+\S+\s+\S+\s+\S+)$/i;
+async function askWithValidation(deps, question, validate) {
+    for (let attempt = 0; attempt < 5; attempt++) {
+        const answer = await deps.ask(question);
+        const error = validate(answer);
+        if (!error)
+            return answer;
+        // Surface error and re-ask via the question prompt itself.
+        question = `${error} ${question}`;
+    }
+    throw new Error("Too many invalid answers");
+}
+function yamlScalar(value) {
+    // Quote unless the string is a simple identifier-ish token. Conservative
+    // — when in doubt, JSON-encode (always parses as a YAML string).
+    if (/^[A-Za-z0-9_.\-/:]+$/.test(value))
+        return value;
+    return JSON.stringify(value);
+}
+/**
+ * Prompt the user for the tool's required JSON Schema fields. Optional
+ * properties are skipped — the user can hand-edit the YAML afterwards
+ * if they want to set defaults. `into` is excluded since the generator
+ * supplies its own name.
+ *
+ * Returns an ordered list of `[key, value]` pairs so the YAML output is
+ * stable across runs (insertion order of object keys is sufficient in
+ * V8 for string keys, but an array makes the contract explicit).
+ */
+async function collectRequiredParams(deps, tool) {
+    const schema = tool.paramsSchema;
+    if (!schema || typeof schema !== "object")
+        return [];
+    const required = Array.isArray(schema.required)
+        ? schema.required.filter((k) => typeof k === "string" && k !== "into")
+        : [];
+    if (required.length === 0)
+        return [];
+    const out = [];
+    const properties = schema.properties ?? {};
+    for (const key of required) {
+        const propMeta = properties[key];
+        const hint = propMeta?.description ? ` — ${propMeta.description}` : "";
+        const value = await askWithValidation(deps, `${tool.id} → ${key}${hint}`, (a) => (a.trim().length > 0 ? null : "required, cannot be empty."));
+        out.push([key, value.trim()]);
+    }
+    return out;
+}
+/**
+ * AI-suggest path. Discovers the running bridge via lock file, POSTs
+ * the user's natural-language goal to `/recipes/generate`, writes the
+ * bridge's raw YAML response to disk (no form normalization — per
+ * memory project_recipe_audit_2026_05_06_part2), and validates
+ * post-hoc as warnings only.
+ *
+ * Failure modes:
+ *   - No bridge running    → clear actionable error
+ *   - Bridge returns 503   → "AI generation unavailable — start the
+ *                            bridge with --driver subprocess"
+ *   - Bridge returns 4xx   → surface server error message
+ *   - Bridge returns 200 but `result.yaml` is empty → write nothing,
+ *                            throw with the raw refusal text
+ */
+async function runNewAiSuggest(options) {
+    const { deps } = options;
+    const name = await askWithValidation(deps, "Recipe name", (a) => RECIPE_NAME_RE.test(a)
+        ? null
+        : 'must match /^[a-z0-9][a-z0-9_-]{1,63}$/ (e.g. "morning-brief").');
+    const goal = await askWithValidation(deps, "Describe what the recipe should do (one-paragraph natural language)", (a) => (a.trim().length > 0 ? null : "goal cannot be empty."));
+    // Resolve bridge discovery + fetch — production defaults or test injection.
+    const findBridge = options.aiSuggest?.findBridge ??
+        (() => {
+            // Lazy import so non-AI paths don't pay the cost.
+            // eslint-disable-next-line @typescript-eslint/no-require-imports
+            const mod = require("../bridgeLockDiscovery.js");
+            return mod.findBridgeLock();
+        });
+    const doFetch = options.aiSuggest?.fetch ?? globalThis.fetch;
+    const lock = findBridge();
+    if (!lock) {
+        throw new Error("AI generation requires a running bridge. Start one with `patchwork start` " +
+            "(or `claude-ide-bridge --driver subprocess` for the bridge-only mode), " +
+            "then retry.");
+    }
+    let response;
+    try {
+        response = await doFetch(`http://127.0.0.1:${lock.port}/recipes/generate`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Authorization: `Bearer ${lock.authToken}`,
+            },
+            body: JSON.stringify({ prompt: goal.trim() }),
+        });
+    }
+    catch (err) {
+        throw new Error(`Could not reach the bridge at port ${lock.port}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    let payload;
+    try {
+        payload = (await response.json());
+    }
+    catch {
+        throw new Error(`Bridge returned non-JSON response (status ${response.status})`);
+    }
+    if (response.status === 503 || payload.unavailable) {
+        throw new Error("AI generation unavailable — start the bridge with `--driver subprocess`.");
+    }
+    if (!payload.ok) {
+        throw new Error(payload.error ?? `Bridge returned ${response.status}`);
+    }
+    const yamlBody = (payload.yaml ?? "").trim();
+    if (!yamlBody) {
+        throw new Error("Bridge returned empty YAML — try a more specific goal.");
+    }
+    // Ensure the SchemaStore pragma is present at line 1 so the file
+    // gets autocomplete on first open. If the bridge already prepended
+    // one, leave it.
+    const hasPragma = /^#\s*yaml-language-server:/.test(yamlBody);
+    const content = hasPragma
+        ? `${yamlBody}\n`
+        : `${RECIPE_SCHEMA_HEADER}\n${yamlBody}\n`;
+    if (deps.preview)
+        deps.preview(content);
+    const shouldWrite = await deps.confirm("Write to disk?");
+    if (!shouldWrite) {
+        throw new Error("Cancelled by user");
+    }
+    const outputDir = options.outputDir ?? RECIPES_DIR;
+    if (!existsSync(outputDir)) {
+        mkdirSync(outputDir, { recursive: true });
+    }
+    const outputPath = join(outputDir, `${name}.yaml`);
+    if (existsSync(outputPath)) {
+        throw new Error(`Recipe already exists: ${outputPath}`);
+    }
+    writeFileSync(outputPath, content);
+    // Lint post-hoc. Surface as warnings; never block — the user asked
+    // for a draft, the bridge produced it, the file is on disk.
+    let warnings = [];
+    try {
+        const parsed = parseYaml(content);
+        const lintResult = validateRecipeDefinition(parsed);
+        warnings = lintResult.issues ?? [];
+    }
+    catch (err) {
+        warnings = [
+            {
+                level: "warning",
+                message: `AI-generated YAML did not parse cleanly: ${err instanceof Error ? err.message : String(err)}`,
+            },
+        ];
+    }
+    return { path: outputPath, content, warnings };
+}
+export async function runNewInteractive(options) {
+    const { deps } = options;
+    // Mode pick — Guided (full prompt tree), Template (existing runNew
+    // templates: minimal | daily | inbox), or AI-suggest (asks the running
+    // bridge's /recipes/generate endpoint and writes the raw response).
+    //
+    // AI-suggest skips the form normalizer per memory
+    // project_recipe_audit_2026_05_06_part2 — applyAiYaml on the dashboard
+    // was lossy. Here we writeFileSync the bridge's `result.yaml` verbatim
+    // (only the SchemaStore pragma is prepended if absent) and validate
+    // post-hoc as warnings, never blocking the write.
+    const templates = listTemplates();
+    const modeChoices = [
+        "Guided — full prompt tree (recommended)",
+        `Template — pick from ${templates.length} starters (${templates.join(", ")})`,
+        "AI suggest — describe what you want; the bridge drafts a YAML",
+    ];
+    const modeIdx = await deps.pickFromList("How do you want to start?", modeChoices);
+    // AI-suggest mode: route through the running bridge's /recipes/generate.
+    if (modeIdx === 3) {
+        return runNewAiSuggest(options);
+    }
+    // Template mode: re-use the existing runNew() flow with the picked template.
+    if (modeIdx === 2) {
+        const name = await askWithValidation(deps, "Recipe name", (a) => RECIPE_NAME_RE.test(a)
+            ? null
+            : 'must match /^[a-z0-9][a-z0-9_-]{1,63}$/ (e.g. "morning-brief").');
+        const description = await askWithValidation(deps, "One-line description", (a) => (a.trim().length > 0 ? null : "cannot be empty."));
+        const templateIdx = await deps.pickFromList("Pick a template", templates);
+        const template = templates[templateIdx - 1];
+        if (!template)
+            throw new Error("Invalid template selection");
+        const result = runNew({
+            name,
+            description,
+            template,
+            ...(options.outputDir ? { outputDir: options.outputDir } : {}),
+        });
+        if (deps.preview)
+            deps.preview(result.content);
+        const shouldWrite = await deps.confirm("Keep this recipe?");
+        if (!shouldWrite) {
+            // runNew already wrote the file — clean up to honor "cancel."
+            try {
+                if (existsSync(result.path)) {
+                    const { unlinkSync } = await import("node:fs");
+                    unlinkSync(result.path);
+                }
+            }
+            catch {
+                // best effort
+            }
+            throw new Error("Cancelled by user");
+        }
+        return { path: result.path, content: result.content, warnings: [] };
+    }
+    // Guided mode (default — modeIdx === 1).
+    const name = await askWithValidation(deps, "Recipe name", (a) => RECIPE_NAME_RE.test(a)
+        ? null
+        : 'must match /^[a-z0-9][a-z0-9_-]{1,63}$/ (e.g. "morning-brief").');
+    const description = await askWithValidation(deps, "One-line description", (a) => (a.trim().length > 0 ? null : "cannot be empty."));
+    const triggerTypes = ["manual", "cron"];
+    const triggerIdx = await deps.pickFromList("Trigger type", triggerTypes.slice());
+    const triggerType = triggerTypes[triggerIdx - 1];
+    if (!triggerType)
+        throw new Error("Invalid trigger selection");
+    const triggerLines = [`trigger:`, `  type: ${triggerType}`];
+    if (triggerType === "cron") {
+        const cron = await askWithValidation(deps, "Cron expression (e.g. '0 8 * * *' for 8am daily)", (a) => CRON_SHAPE_RE.test(a.trim())
+            ? null
+            : 'expected 5-field cron or "@every Ns|Nm|Nh".');
+        triggerLines.push(`  at: ${yamlScalar(cron.trim())}`);
+    }
+    // Step loop. The user adds tool / agent steps until they pick "done".
+    // Each tool pick reads its paramsSchema and prompts for required fields,
+    // so the generated recipe is closer to runnable than the MVP slice.
+    const namespaces = listConnectorNamespaces();
+    const stepLines = ["steps:"];
+    const intoNames = [];
+    let lastAgentInto = null;
+    let toolStepCount = 0;
+    let agentStepCount = 0;
+    const stepKindChoices = [
+        "Add a tool step (calls a registered tool — gmail.fetch_unread, github.list_issues, …)",
+        "Add an agent step (LLM prompt — drafts, classifies, summarizes)",
+        "Done — preview and write",
+    ];
+    for (let stepIdx = 0; stepIdx < 20; stepIdx++) {
+        const kind = await deps.pickFromList(stepIdx === 0
+            ? "Build steps — what's next?"
+            : "Add another step? (or pick Done)", stepKindChoices);
+        if (kind === 3)
+            break;
+        if (kind === 1) {
+            // Tool step
+            const nsIdx = await deps.pickFromList("Pick a connector", namespaces.slice());
+            const ns = namespaces[nsIdx - 1];
+            if (!ns)
+                throw new Error("Invalid connector selection");
+            const tools = listTools(ns);
+            const labels = tools.map((t) => `${t.id} — ${t.description}`);
+            const toolIdx = await deps.pickFromList(`Pick a ${ns} tool`, labels);
+            const tool = tools[toolIdx - 1];
+            if (!tool)
+                throw new Error(`Invalid tool selection for ${ns}`);
+            toolStepCount += 1;
+            const intoName = toolStepCount === 1 ? `${ns}_result` : `${ns}_result_${toolStepCount}`;
+            intoNames.push(intoName);
+            stepLines.push(`  - tool: ${tool.id}`);
+            // Prompt for required params from the tool's JSON schema.
+            const params = await collectRequiredParams(deps, tool);
+            for (const [key, value] of params) {
+                stepLines.push(`    ${key}: ${yamlScalar(value)}`);
+            }
+            stepLines.push(`    into: ${intoName}`);
+        }
+        else if (kind === 2) {
+            // Agent step
+            const prompt = await askWithValidation(deps, "Agent prompt", (a) => a.trim().length > 0 ? null : "cannot be empty.");
+            agentStepCount += 1;
+            const intoName = agentStepCount === 1
+                ? "agent_output"
+                : `agent_output_${agentStepCount}`;
+            lastAgentInto = intoName;
+            stepLines.push(`  - agent: true`);
+            stepLines.push(`    prompt: |`);
+            for (const line of prompt.split("\n")) {
+                stepLines.push(`      ${line}`);
+            }
+            stepLines.push(`    into: ${intoName}`);
+        }
+    }
+    // Always tail with file.write to inbox so the user sees output somewhere.
+    // Reference the most recent agent output when one exists, otherwise fall
+    // back to the most recent tool result (or a TODO comment if neither).
+    const tailRef = lastAgentInto ?? intoNames[intoNames.length - 1] ?? null;
+    stepLines.push(`  - tool: file.write`);
+    stepLines.push(`    path: "~/.patchwork/inbox/${name}-{{date}}.md"`);
+    stepLines.push(`    content: |`);
+    stepLines.push(`      # ${name} — {{date}}`);
+    stepLines.push(``);
+    if (tailRef) {
+        stepLines.push(`      {{${tailRef}}}`);
+    }
+    else {
+        stepLines.push(`      (no steps configured — fill in)`);
+    }
+    const content = `${RECIPE_SCHEMA_HEADER}\n` +
+        `version: 1.0.0\n` +
+        `name: ${name}\n` +
+        `description: ${yamlScalar(description)}\n` +
+        `${triggerLines.join("\n")}\n` +
+        `${stepLines.join("\n")}\n`;
+    // Lint pre-write. validateRecipeDefinition expects parsed YAML.
+    let warnings = [];
+    try {
+        const parsed = parseYaml(content);
+        const lintResult = validateRecipeDefinition(parsed);
+        warnings = lintResult.issues ?? [];
+    }
+    catch {
+        // Parse failure here is a bug in the generator — surface but don't block.
+        warnings = [
+            {
+                level: "error",
+                message: "Generated YAML failed to parse — please report this.",
+            },
+        ];
+    }
+    if (deps.preview)
+        deps.preview(content);
+    const shouldWrite = await deps.confirm("Write to disk?");
+    if (!shouldWrite) {
+        throw new Error("Cancelled by user");
+    }
+    const outputDir = options.outputDir ?? RECIPES_DIR;
+    if (!existsSync(outputDir)) {
+        mkdirSync(outputDir, { recursive: true });
+    }
+    const outputPath = join(outputDir, `${name}.yaml`);
+    if (existsSync(outputPath)) {
+        throw new Error(`Recipe already exists: ${outputPath}`);
+    }
+    writeFileSync(outputPath, content);
+    return { path: outputPath, content, warnings };
+}
 export async function runSchema(outputDir) {
     const resolvedOutputDir = resolve(outputDir);
     const schemas = generateSchemaSet();
@@ -183,8 +534,12 @@ export function runLint(recipePath) {
     const chainIssues = lintChainRefs(parsed, recipePath);
     if (chainIssues.length > 0) {
         result.issues.push(...chainIssues);
-        result.errors += chainIssues.filter((i) => i.level === "error").length;
-        result.warnings += chainIssues.filter((i) => i.level === "warning").length;
+        for (const i of chainIssues) {
+            if (i.level === "error")
+                result.errors++;
+            else if (i.level === "warning")
+                result.warnings++;
+        }
         if (result.errors > 0) {
             result.valid = false;
         }
@@ -420,6 +775,8 @@ export async function runRecipe(recipeRef, options = {}) {
     const runnerDeps = {
         ...options.deps,
         workdir: options.workdir ?? options.deps?.workdir ?? process.cwd(),
+        ...(options.manualRunId && { manualRunId: options.manualRunId }),
+        ...(options.ledgerDir && { ledgerDir: options.ledgerDir }),
     };
     if (options.dryRun) {
         throw new Error("runRecipeDryPlan must be used for dry-run execution");
@@ -832,7 +1189,16 @@ export async function runPreflight(recipeRef, options = {}) {
     }
     const plan = await runRecipeDryPlan(recipeRef, options);
     const requireWriteAck = options.requireWriteAck ?? true;
-    const allowlist = new Set(options.allowWrites ?? []);
+    // Merge the recipe's declared allowWrites (YAML) with any caller-supplied
+    // entries (e.g. --allow-write CLI flag). Either source is sufficient.
+    const recipeForWrites = loadYamlRecipe(recipePath);
+    const recipeAllowWrites = Array.isArray(recipeForWrites.allowWrites)
+        ? recipeForWrites.allowWrites.filter((entry) => typeof entry === "string")
+        : [];
+    const allowlist = new Set([
+        ...recipeAllowWrites,
+        ...(options.allowWrites ?? []),
+    ]);
     for (const step of plan.steps) {
         if (step.type === "tool" && step.tool && step.resolved === false) {
             issues.push({
@@ -898,6 +1264,270 @@ export function runPreflightWatch(options) {
     };
     return runWatch(watchOptions);
 }
+/**
+ * Map a loaded `YamlRecipe`'s steps into the schema `Step` shape that
+ * `detectRequiredConnectors` consumes. The authoring YAML and the
+ * connector-detection helper disagree on step shape — YAML carries
+ * `tool?: string` plus a nested `agent?: { prompt }` object, while the
+ * detector expects the flat schema form (`agent: false` carries `tool`,
+ * `agent: true` carries `prompt` + optional `tools[]`). This adapter lets
+ * the CLI reuse the exact helper the dashboard install preflight uses
+ * (same `TOOL_NAMESPACE_TO_CONNECTOR` map, same prompt-scan) rather than
+ * re-implementing detection. Tool steps feed the namespace path; agent
+ * steps feed the prompt-scan path (YAML agent steps have no `tools[]`).
+ */
+function detectConnectorsForYamlRecipe(recipe) {
+    const steps = recipe.steps.map((step, i) => {
+        const id = typeof step.id === "string" ? step.id : `step-${i}`;
+        if (typeof step.tool === "string") {
+            return { id, agent: false, tool: step.tool, params: {} };
+        }
+        if (step.agent && typeof step.agent.prompt === "string") {
+            return { id, agent: true, prompt: step.agent.prompt };
+        }
+        // Steps with neither a tool nor an agent prompt contribute nothing —
+        // model them as an empty agent step so the detector skips them cleanly.
+        return { id, agent: true, prompt: "" };
+    });
+    return detectRequiredConnectors({
+        ...recipe,
+        steps,
+    });
+}
+/**
+ * One-command fix hint for an unauthorized connector. Phrasing matches the
+ * runtime `auth_failure` halt hint ("reconnect from /connections") so the
+ * doctor's static and runtime advice line up.
+ */
+function connectorFixHint(connectorId) {
+    return `authorize from /connections (or run \`patchwork recipe preflight\` after connecting "${connectorId}")`;
+}
+/**
+ * `recipe doctor` — one-screen "why is this recipe unhealthy + how do I
+ * fix it" diagnosis. Composes the static `preflight` check (lint + policy
+ * + plan) and static connector detection with the recipe-scoped runtime
+ * halt summary, mapping every finding to an actionable hint. Fail-soft: a
+ * missing bridge degrades to static-only rather than erroring.
+ */
+export async function runRecipeDoctor(recipeRef, options = {}) {
+    const { fetchHalts, ...preflightOptions } = options;
+    const recipePath = resolveRecipePath(recipeRef);
+    // Lint first — it never throws and returns structured issues even for
+    // recipes that can't load. Then attempt the fuller preflight (policy +
+    // plan); if the recipe is too broken to load/plan, `runPreflight`
+    // throws — fall back to a lint-only static result so doctor still
+    // produces a clean diagnosis instead of a stack trace.
+    const lint = runLint(recipePath);
+    let staticResult;
+    try {
+        const pf = await runPreflight(recipePath, preflightOptions);
+        staticResult = { ok: pf.ok, recipe: pf.recipe, issues: pf.issues };
+    }
+    catch (err) {
+        const issues = lint.issues.map((i) => ({
+            level: i.level,
+            code: i.level === "error" ? "lint-error" : "lint-warning",
+            message: i.message,
+        }));
+        // Guarantee at least one error so the verdict is unhealthy — the
+        // load failure itself is the signal even if lint surfaced only
+        // warnings (or nothing it could attribute to a line).
+        if (!issues.some((i) => i.level === "error")) {
+            issues.push({
+                level: "error",
+                code: "lint-error",
+                message: err instanceof Error ? err.message : String(err),
+            });
+        }
+        staticResult = {
+            ok: false,
+            recipe: basename(recipePath).replace(/\.(ya?ml|json)$/i, ""),
+            issues,
+            planSkipped: true,
+        };
+    }
+    const recipeName = staticResult.recipe;
+    // --- Connector authorization ---------------------------------------
+    // Static detection always runs (no bridge needed). When the recipe was
+    // too broken to load above, fall back to an empty required-set rather
+    // than crashing the whole diagnosis — the lint errors are the signal in
+    // that case.
+    let required = [];
+    if (!staticResult.planSkipped) {
+        try {
+            required = detectConnectorsForYamlRecipe(loadYamlRecipe(recipePath));
+        }
+        catch {
+            // A recipe that lints clean but fails to load here is unusual;
+            // treat connector detection as best-effort and move on.
+            required = [];
+        }
+    }
+    const { fetchConnections } = options;
+    let connectors;
+    if (required.length === 0) {
+        connectors = {
+            required,
+            missing: [],
+            authorized: [],
+            connectionsChecked: false,
+            note: staticResult.planSkipped
+                ? "connector detection skipped — recipe could not be loaded"
+                : "recipe requires no Patchwork connectors",
+        };
+    }
+    else if (fetchConnections) {
+        try {
+            const connections = await fetchConnections();
+            if (connections === null) {
+                connectors = {
+                    required,
+                    missing: [],
+                    authorized: [],
+                    connectionsChecked: false,
+                    note: "no running bridge — connector auth check skipped",
+                };
+            }
+            else {
+                const missing = findMissingConnectors(required, connections);
+                const missingSet = new Set(missing);
+                connectors = {
+                    required,
+                    missing,
+                    authorized: required.filter((id) => !missingSet.has(id)),
+                    connectionsChecked: true,
+                };
+            }
+        }
+        catch (err) {
+            connectors = {
+                required,
+                missing: [],
+                authorized: [],
+                connectionsChecked: false,
+                note: `connector auth check failed: ${err instanceof Error ? err.message : String(err)}`,
+            };
+        }
+    }
+    else {
+        connectors = {
+            required,
+            missing: [],
+            authorized: [],
+            connectionsChecked: false,
+            note: "connector auth check not requested",
+        };
+    }
+    let runtime = null;
+    let runtimeNote;
+    if (fetchHalts) {
+        try {
+            runtime = await fetchHalts(recipeName);
+            if (runtime === null) {
+                runtimeNote = "no running bridge — runtime halt check skipped";
+            }
+        }
+        catch (err) {
+            runtime = null;
+            runtimeNote = `runtime halt check failed: ${err instanceof Error ? err.message : String(err)}`;
+        }
+    }
+    else {
+        runtimeNote = "runtime halt check not requested";
+    }
+    const ok = staticResult.ok &&
+        connectors.missing.length === 0 &&
+        (runtime?.total ?? 0) === 0;
+    return {
+        recipe: recipeName,
+        recipePath,
+        static: staticResult,
+        connectors,
+        runtime,
+        runtimeNote,
+        ok,
+    };
+}
+/**
+ * Render a `RecipeDoctorResult` as a one-screen human report. Returns the
+ * text so the CLI handler can write it (and tests can assert on it)
+ * without coupling to process.stdout.
+ */
+export function formatRecipeDoctorReport(result) {
+    const lines = [];
+    const verdict = result.ok ? "✓ healthy" : "✗ needs attention";
+    lines.push(`Recipe doctor — ${result.recipe}  (${verdict})`);
+    lines.push(`  ${result.recipePath}`);
+    lines.push("");
+    // --- Static: lint + policy + plan ---
+    const s = result.static;
+    const staticErrors = s.issues.filter((i) => i.level === "error");
+    const staticWarnings = s.issues.filter((i) => i.level === "warning");
+    if (s.issues.length === 0) {
+        lines.push("Static checks: ✓ lint + policy clean");
+    }
+    else {
+        const planNote = s.planSkipped
+            ? " (could not plan — lint-only; fix the errors below first)"
+            : "";
+        lines.push(`Static checks: ${staticErrors.length} error(s), ${staticWarnings.length} warning(s)${planNote}`);
+        for (const issue of s.issues) {
+            const icon = issue.level === "error" ? "✗" : "⚠";
+            const where = issue.stepId ? ` [step "${issue.stepId}"]` : "";
+            lines.push(`  ${icon} (${issue.code})${where} ${issue.message}`);
+        }
+    }
+    lines.push("");
+    // --- Connectors: required vs authorized ---
+    const c = result.connectors;
+    if (c.required.length === 0) {
+        lines.push(`Connectors: ✓ none required${c.note ? ` (${c.note})` : ""}`);
+    }
+    else if (!c.connectionsChecked) {
+        // Couldn't classify auth state (no bridge / not requested) — still tell
+        // the user which connectors the recipe needs so they can pre-authorize.
+        lines.push(`Connectors: ${c.required.length} required — auth state unknown (${c.note ?? "unavailable"})`);
+        lines.push(`  needs: ${c.required.join(", ")}`);
+    }
+    else if (c.missing.length === 0) {
+        lines.push(`Connectors: ✓ all ${c.required.length} authorized (${c.required.join(", ")})`);
+    }
+    else {
+        lines.push(`Connectors: ${c.missing.length} of ${c.required.length} not authorized`);
+        for (const id of c.missing) {
+            lines.push(`  ✗ ${id} — not authorized  → ${connectorFixHint(id)}`);
+        }
+        if (c.authorized.length > 0) {
+            lines.push(`  ✓ authorized: ${c.authorized.join(", ")}`);
+        }
+    }
+    lines.push("");
+    // --- Runtime: recent halts ---
+    if (result.runtime === null) {
+        lines.push(`Runtime halts: — (${result.runtimeNote ?? "unavailable"})`);
+    }
+    else if (result.runtime.total === 0) {
+        lines.push("Runtime halts: ✓ none in the recent window");
+    }
+    else {
+        lines.push(`Runtime halts: ${result.runtime.total} in the recent window`);
+        const entries = Object.entries(result.runtime.byCategory).sort(([, a], [, b]) => (b ?? 0) - (a ?? 0));
+        for (const [cat, count] of entries) {
+            const category = cat;
+            const label = HALT_CATEGORY_LABELS[category] ?? cat;
+            const hint = HALT_CATEGORY_HINTS[category] ?? "open run trace";
+            lines.push(`  ✗ ${label}: ${count}  → ${hint}`);
+        }
+        if (result.runtime.recent.length > 0) {
+            lines.push("  most recent:");
+            for (const r of result.runtime.recent.slice(0, 5)) {
+                const reason = r.reason.length > 100 ? `${r.reason.slice(0, 99)}…` : r.reason;
+                lines.push(`    · [run #${r.runSeq}] ${reason}`);
+            }
+        }
+    }
+    return `${lines.join("\n")}\n`;
+}
 /**
  * Exported for the cli-warns-when-out-of-jail.test regression suite —
  * the warn path is what we assert on, not the path-resolution behaviour.
@@ -1088,8 +1718,13 @@ export async function runRecord(recipePath, options = {}) {
             });
         }
     }
-    const errors = issues.filter((issue) => issue.level === "error").length;
-    const warnings = issues.filter((issue) => issue.level === "warning").length;
+    let errors = 0, warnings = 0;
+    for (const issue of issues) {
+        if (issue.level === "error")
+            errors++;
+        else if (issue.level === "warning")
+            warnings++;
+    }
     return {
         valid: errors === 0,
         issues,
@@ -1200,8 +1835,13 @@ export async function runTest(recipePath, options = {}) {
             });
         }
     }
-    const errors = issues.filter((issue) => issue.level === "error").length;
-    const warnings = issues.filter((issue) => issue.level === "warning").length;
+    let errors = 0, warnings = 0;
+    for (const issue of issues) {
+        if (issue.level === "error")
+            errors++;
+        else if (issue.level === "warning")
+            warnings++;
+    }
     return {
         valid: errors === 0,
         issues,