@bridge_gpt/mcp-server 0.1.14 → 0.1.17

package/build/chain-orchestrator.js

@@ -0,0 +1,1150 @@
+/**
+ * Chain orchestrator — server-side sequential execution for the new
+ * ``run_full_automation`` / ``resume_full_automation`` MCP tools (BAPI-326).
+ *
+ * Design rules (mirrors pipeline-orchestrator.ts):
+ *   - Never imports ``mcp_server/src/index.ts``. All runtime dependencies are
+ *     injected through ``ChainOrchestratorDeps`` (which extends
+ *     ``PipelineOrchestratorDeps`` with the chain-recipe registry).
+ *   - Chain runs are persisted server-side via the Bridge API routes at
+ *     ``/jira/chain-runs/runs``. Every state transition extends the idle TTL.
+ *   - The chain drives existing child pipelines via ``runPipeline`` /
+ *     ``resumePipeline``. Only compact per-stage metadata + heuristic
+ *     (no-LLM) summaries are persisted in ``chain_runs.stages`` — never the
+ *     full child pipeline ``results`` arrays.
+ *   - Stage 3 (start-tickets) is special-cased: the orchestrator does NOT call
+ *     ``runPipeline``; it emits an ``agent_task`` envelope naming the exact
+ *     ``/start-tickets ...`` command for the host agent to invoke in-session.
+ *   - Cross-stage variables (created_ticket_keys -> review fan-out ->
+ *     reviewed_ticket_keys -> start-tickets) are resolved server-side. Missing
+ *     cross-stage variables produce a typed ``VALIDATION`` failure — never a
+ *     placeholder value.
+ */
+import { runPipeline, resumePipeline, peekPipelineRun } from "./pipeline-orchestrator.js";
+import { toStringVariable, substituteChainValue } from "./chain-utils.js";
+const CHAIN_NAME = "full-automation";
+const START_TICKETS_PIPELINE = "start-tickets";
+// Display titles for preambles, keyed by child pipeline name.
+const STAGE_TITLES = {
+    "idea-to-ticket": "Idea to ticket",
+    "review-ticket": "Review ticket",
+    "start-tickets": "Start tickets",
+};
+export class ChainPersistenceError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+export function createChainPersistenceClient(deps) {
+    const headers = {
+        "X-API-Key": deps.apiKey,
+        "Content-Type": "application/json",
+    };
+    const base = deps.baseUrl.replace(/\/+$/, "");
+    function urlFor(suffix, query) {
+        const u = new URL(`${base}/jira/chain-runs${suffix}`);
+        if (query) {
+            for (const [k, v] of Object.entries(query)) {
+                u.searchParams.set(k, v);
+            }
+        }
+        return u.toString();
+    }
+    async function readError(resp) {
+        const raw = await resp.text();
+        let codeFromBody = null;
+        let messageFromBody = null;
+        try {
+            const parsed = JSON.parse(raw);
+            const detail = parsed?.detail;
+            if (detail && typeof detail === "object") {
+                if (typeof detail.error_code === "string") {
+                    codeFromBody = detail.error_code;
+                }
+                if (typeof detail.error === "string") {
+                    messageFromBody = detail.error;
+                }
+            }
+        }
+        catch {
+            // not JSON
+        }
+        const codeFromStatus = resp.status === 404
+            ? "NOT_FOUND"
+            : resp.status === 410
+                ? "EXPIRED"
+                : resp.status === 403
+                    ? "REPO_MISMATCH"
+                    : resp.status === 400 || resp.status === 422
+                        ? "VALIDATION"
+                        : "TOOL_ERROR";
+        return {
+            code: codeFromBody ?? codeFromStatus,
+            message: messageFromBody ?? (raw || `HTTP ${resp.status}`),
+        };
+    }
+    async function createRun(input) {
+        const resp = await fetch(urlFor("/runs"), {
+            method: "POST",
+            headers,
+            body: JSON.stringify({
+                repo_name: deps.repoName,
+                chain_name: input.chain_name,
+                args: input.args,
+                current_stage_index: input.current_stage_index,
+                stages: input.stages,
+                status: input.status,
+                ttl_seconds: input.ttl_seconds,
+            }),
+        });
+        if (!resp.ok) {
+            const err = await readError(resp);
+            throw new ChainPersistenceError(err.code, err.message);
+        }
+        return (await resp.json());
+    }
+    async function getRun(chainRunId) {
+        const resp = await fetch(urlFor(`/runs/${encodeURIComponent(chainRunId)}`, {
+            repo_name: deps.repoName,
+        }), { headers: { "X-API-Key": deps.apiKey } });
+        if (!resp.ok) {
+            const err = await readError(resp);
+            throw new ChainPersistenceError(err.code, err.message);
+        }
+        return (await resp.json());
+    }
+    async function patchRun(chainRunId, body) {
+        const resp = await fetch(urlFor(`/runs/${encodeURIComponent(chainRunId)}`), {
+            method: "PATCH",
+            headers,
+            body: JSON.stringify({ repo_name: deps.repoName, ...body }),
+        });
+        if (!resp.ok) {
+            const err = await readError(resp);
+            throw new ChainPersistenceError(err.code, err.message);
+        }
+        return (await resp.json());
+    }
+    async function listRuns(status) {
+        const query = { repo_name: deps.repoName };
+        if (status)
+            query.status = status;
+        const resp = await fetch(urlFor("/runs", query), {
+            headers: { "X-API-Key": deps.apiKey },
+        });
+        if (!resp.ok) {
+            const err = await readError(resp);
+            throw new ChainPersistenceError(err.code, err.message);
+        }
+        const body = (await resp.json());
+        return body.runs ?? [];
+    }
+    async function deleteRun(chainRunId) {
+        const resp = await fetch(urlFor(`/runs/${encodeURIComponent(chainRunId)}`, {
+            repo_name: deps.repoName,
+        }), {
+            method: "DELETE",
+            headers: { "X-API-Key": deps.apiKey },
+        });
+        if (!resp.ok) {
+            const err = await readError(resp);
+            throw new ChainPersistenceError(err.code, err.message);
+        }
+    }
+    return { createRun, getRun, patchRun, listRuns, deleteRun };
+}
+// ---------------------------------------------------------------------------
+// Pure helpers
+// ---------------------------------------------------------------------------
+function normalizeAutoApprove(value) {
+    if (value === true || value === "true")
+        return true;
+    return false;
+}
+const JIRA_KEY_EXACT = /^[A-Z][A-Z0-9]+-\d+$/;
+/**
+ * Extract created Jira ticket keys from a STRUCTURED payload (an object/array
+ * holding `created_ticket_keys` / `ticket_key` / etc.). Collects values from the
+ * preferred key fields in a fixed preference order, validates each against
+ * `JIRA_KEY_EXACT`, and de-dupes in encounter order. There is deliberately NO
+ * free-text regex fallback: pass the parsed upload-step payload (via
+ * `extractCreatedKeysFromCompletedChild`), never a whole pipeline transcript, so
+ * keys merely *mentioned* by an earlier step (e.g. duplicate-detection search
+ * hits) can never be mistaken for this run's creations. A string / no-field
+ * input returns `[]`, which the caller treats as fail-closed.
+ */
+export function extractCreatedTicketKeys(source) {
+    const preferredKeys = [
+        "created_ticket_keys",
+        "ticket_keys",
+        "child_ticket_keys",
+        "epic_key",
+        "ticket_key",
+    ];
+    const buckets = {};
+    for (const k of preferredKeys)
+        buckets[k] = [];
+    const visit = (value) => {
+        if (Array.isArray(value)) {
+            for (const item of value)
+                visit(item);
+            return;
+        }
+        if (value && typeof value === "object") {
+            const obj = value;
+            for (const key of preferredKeys) {
+                if (key in obj) {
+                    const v = obj[key];
+                    if (typeof v === "string") {
+                        buckets[key].push(v);
+                    }
+                    else if (Array.isArray(v)) {
+                        for (const elem of v) {
+                            if (typeof elem === "string")
+                                buckets[key].push(elem);
+                        }
+                    }
+                }
+            }
+            for (const v of Object.values(obj))
+                visit(v);
+        }
+    };
+    visit(source);
+    const ordered = [];
+    for (const key of preferredKeys) {
+        for (const candidate of buckets[key]) {
+            if (JIRA_KEY_EXACT.test(candidate))
+                ordered.push(candidate);
+        }
+    }
+    const seen = new Set();
+    const result = [];
+    for (const key of ordered) {
+        if (!seen.has(key)) {
+            seen.add(key);
+            result.push(key);
+        }
+    }
+    return result;
+}
+/**
+ * Pull a JSON object out of an agent's free-text result. Prefers the LAST fenced
+ * ```json … ``` block (the structured payload the upload step is told to emit as
+ * its final content); otherwise tries the last balanced `{ … }` slice that
+ * `JSON.parse`s. Returns the parsed value or `null`.
+ */
+export function parseStructuredAgentResult(text) {
+    if (typeof text !== "string" || text.trim() === "")
+        return null;
+    // Prefer fenced ```json blocks; take the last one.
+    const fences = [...text.matchAll(/```(?:json)?\s*([\s\S]*?)```/gi)];
+    for (let i = fences.length - 1; i >= 0; i--) {
+        const parsed = tryParseJson(fences[i][1]);
+        if (parsed !== undefined)
+            return parsed;
+    }
+    // Fallback: try each `{ … }` candidate. For each opening brace (last first),
+    // walk closing braces from the last back toward it, so a balanced object is
+    // found even when a stray `}` trails the valid JSON (using the loop-local
+    // `end`, not a single text-wide `lastIndexOf("}")`).
+    for (let start = text.lastIndexOf("{"); start >= 0; start = text.lastIndexOf("{", start - 1)) {
+        for (let end = text.lastIndexOf("}"); end > start; end = text.lastIndexOf("}", end - 1)) {
+            const parsed = tryParseJson(text.slice(start, end + 1));
+            if (parsed !== undefined)
+                return parsed;
+        }
+    }
+    return null;
+}
+function tryParseJson(raw) {
+    try {
+        return JSON.parse(raw.trim());
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Derive the keys created by a completed idea-to-ticket child run AUTHORITATIVELY
+ * from the upload step's structured output — never by scanning the whole
+ * transcript. The upload step (`upload-and-track.md`) is the LAST step of the
+ * idea-to-ticket pipeline and the chain never passes `skip_steps`, so it is the
+ * final entry of `results`. Its `result` is parsed for a `{ created_ticket_keys }`
+ * payload. Returns `[]` (→ caller fails closed) if the payload is absent or
+ * malformed, so dedup-search hits from earlier steps can never become targets.
+ */
+export function extractCreatedKeysFromCompletedChild(childEnv) {
+    const results = childEnv.results;
+    if (!Array.isArray(results) || results.length === 0)
+        return [];
+    const uploadResult = results[results.length - 1]?.result;
+    const payload = typeof uploadResult === "string"
+        ? parseStructuredAgentResult(uploadResult)
+        : uploadResult;
+    return extractCreatedTicketKeys(payload);
+}
+/**
+ * True when ``token`` appears in a failed child envelope's failure-text fields:
+ * the top-level ``error`` message and each step result's ``error`` / string
+ * ``result``. Deliberately does NOT scan echoed input, args, or other free-form
+ * fields, so a coincidental token elsewhere cannot misclassify the failure.
+ */
+function failedEnvelopeMentions(env, token) {
+    if (env.status !== "failed")
+        return false;
+    if (typeof env.error === "string" && env.error.includes(token))
+        return true;
+    for (const r of env.results ?? []) {
+        if (typeof r.error === "string" && r.error.includes(token))
+            return true;
+        if (typeof r.result === "string" && r.result.includes(token))
+            return true;
+    }
+    return false;
+}
+/** Heuristic, no-LLM one-line stage summary. */
+export function summarizeStageCompletion(pipelineName, keys) {
+    const joined = keys.join(", ");
+    if (pipelineName === "idea-to-ticket") {
+        return `Created tickets: ${joined}`;
+    }
+    if (pipelineName === "review-ticket") {
+        return `Reviewed tickets: ${joined}`;
+    }
+    if (pipelineName === START_TICKETS_PIPELINE) {
+        return `Spawned worktrees for ${keys.length} ticket(s): ${joined}`;
+    }
+    return `Completed ${pipelineName}: ${joined}`;
+}
+function stageTitle(pipelineName) {
+    return STAGE_TITLES[pipelineName] ?? pipelineName;
+}
+/** Build the markdown preamble for the active (or final) stage. */
+export function buildPreamble(recipe, stageIndex, stages) {
+    const total = recipe.stages.length;
+    const lines = [];
+    if (stageIndex >= total) {
+        lines.push(`### Full automation complete (${total} of ${total} stages)`);
+    }
+    else {
+        const title = stageTitle(recipe.stages[stageIndex].pipeline_name);
+        lines.push(`### Stage ${stageIndex + 1} of ${total} — ${title}`);
+    }
+    const priorSummaries = [];
+    const upTo = Math.min(stageIndex, stages.length);
+    for (let i = 0; i < upTo; i++) {
+        const s = stages[i];
+        if (s && typeof s.summary === "string" && s.summary.trim() !== "") {
+            priorSummaries.push(`- ${s.summary}`);
+        }
+    }
+    if (priorSummaries.length > 0) {
+        lines.push("", "Completed so far:", ...priorSummaries);
+    }
+    return lines.join("\n");
+}
+const PRIOR_RESULT_MAX_CHARS = 2000;
+/**
+ * Build a compact, read-only appendix surfacing the OUTPUTS of prior server-side
+ * `mcp_call` steps (e.g. `get_project_standards`) so the chain's driving agent
+ * can see context it would otherwise miss — the chain forwards only the
+ * agent_task `instruction`, unlike the standalone pipeline path whose envelope
+ * carries `results`. Skips agent_task results (the agent produced those) and
+ * failed steps; truncates each output. Returns "" when there is nothing to add,
+ * so the appendix is purely additive.
+ */
+function buildPriorResultsAppendix(results) {
+    if (!Array.isArray(results))
+        return "";
+    const lines = [];
+    for (const r of results) {
+        if (r.type !== "mcp_call" || !r.ok)
+            continue;
+        const raw = typeof r.result === "string" ? r.result : stringifyResult(r.result);
+        if (raw.trim() === "")
+            continue;
+        const truncated = raw.length > PRIOR_RESULT_MAX_CHARS
+            ? `${raw.slice(0, PRIOR_RESULT_MAX_CHARS)}… [truncated]`
+            : raw;
+        lines.push(`- \`${r.tool ?? r.description}\`: ${truncated}`);
+    }
+    if (lines.length === 0)
+        return "";
+    return (`\n\n## Prior step outputs (read-only context)\n` +
+        `Server-side step outputs from earlier in this pipeline run that you cannot ` +
+        `fetch yourself:\n${lines.join("\n")}`);
+}
+function stringifyResult(value) {
+    if (value === undefined || value === null)
+        return "";
+    try {
+        return JSON.stringify(value);
+    }
+    catch {
+        return String(value);
+    }
+}
+// ---------------------------------------------------------------------------
+// Envelope builders
+// ---------------------------------------------------------------------------
+function failedEnvelope(code, message, extras = {}) {
+    return {
+        status: "failed",
+        error_code: code,
+        error: message,
+        ...extras,
+    };
+}
+function buildNeedsAgentTaskEnvelope(args) {
+    const env = {
+        status: "needs_agent_task",
+        chain_run_id: args.chainRunId,
+        chain_stage: args.chainStage,
+        chain_step: args.chainStep,
+        chain_total: args.chainTotal,
+        preamble: args.preamble,
+        next_action: { kind: "agent_task", instruction: args.instruction },
+    };
+    if (args.pipelineRunId)
+        env.pipeline_run_id = args.pipelineRunId;
+    if (typeof args.pipelineStep === "number")
+        env.pipeline_step = args.pipelineStep;
+    if (typeof args.pipelineTotal === "number")
+        env.pipeline_total = args.pipelineTotal;
+    return env;
+}
+function buildCompletedEnvelope(recipe, row) {
+    const total = recipe.stages.length;
+    return {
+        status: "completed",
+        chain_run_id: row.chain_run_id,
+        chain_stage: CHAIN_NAME,
+        chain_step: total,
+        chain_total: total,
+        preamble: buildPreamble(recipe, total, row.stages),
+        next_action: { kind: "complete" },
+    };
+}
+/** Patch the chain + current stage as failed and return a VALIDATION envelope. */
+async function failChainValidation(persistence, recipe, row, message) {
+    const idx = row.current_stage_index;
+    const stages = cloneStages(row.stages);
+    if (stages[idx])
+        stages[idx].status = "failed";
+    try {
+        await persistence.patchRun(row.chain_run_id, {
+            stages,
+            status: "failed",
+        });
+    }
+    catch {
+        // best-effort — the failure is what matters
+    }
+    return failedEnvelope("VALIDATION", message, {
+        chain_run_id: row.chain_run_id,
+        chain_stage: recipe.stages[idx]?.pipeline_name,
+        chain_step: idx + 1,
+        chain_total: recipe.stages.length,
+    });
+}
+function cloneStages(stages) {
+    return stages.map((s) => ({ ...s }));
+}
+/** True when ``value`` is a string whose trimmed content is non-empty. */
+function isNonEmpty(value) {
+    return typeof value === "string" && value.trim() !== "";
+}
+const SLUG_STOP_WORDS = new Set([
+    "the", "a", "an", "of", "to", "and", "or", "for", "in", "on", "with",
+]);
+/**
+ * Derive a kebab-case ``slug`` from an idea — the same shape the standalone
+ * idea-to-ticket command produces (lowercase, ~6-8 meaningful words, stop-words
+ * skipped, non-alphanumerics dropped, truncated to ~60 chars). Pure and
+ * deterministic so the chain can supply idea-to-ticket's required ``slug``
+ * variable without consulting the agent.
+ */
+export function deriveSlug(idea) {
+    const words = idea
+        .toLowerCase()
+        .replace(/[^a-z0-9\s-]/g, " ")
+        .split(/[\s-]+/)
+        .filter((w) => w.length > 0 && !SLUG_STOP_WORDS.has(w));
+    let slug = words.slice(0, 8).join("-");
+    if (slug.length > 60) {
+        slug = slug.slice(0, 60).replace(/-+$/g, "");
+    }
+    return slug || "idea";
+}
+/**
+ * Derive idea-to-ticket's required ``run_id`` (the per-run artifact-directory
+ * id) from the already-unique ``chain_run_id``. Deterministic — no clock or RNG
+ * — so the value is stable across any re-derivation within a chain run.
+ */
+export function deriveRunId(chainRunId) {
+    return isNonEmpty(chainRunId) ? `fa-${chainRunId}` : "fa-run";
+}
+/** Build the string variable map for a stage's child pipeline. */
+function buildStageVariables(stage, args, extra = {}) {
+    const baseVars = {
+        idea: toStringVariable(args.idea),
+        auto_approve: toStringVariable(args.auto_approve),
+        scheduled_at: toStringVariable(args.scheduled_at),
+        max_children: toStringVariable(args.max_children),
+        allow_duplicate: toStringVariable(args.allow_duplicate),
+        agent: toStringVariable(args.agent),
+        ...extra,
+    };
+    const resolved = {};
+    for (const [k, template] of Object.entries(stage.variables ?? {})) {
+        resolved[k] = toStringVariable(substituteChainValue(template, baseVars));
+    }
+    return resolved;
+}
+/** Resolve a fan-out / cross-stage input list from prior stage outputs. */
+function resolveCrossStageList(row, stageIndex, key) {
+    for (let i = stageIndex - 1; i >= 0; i--) {
+        const outputs = row.stages[i]?.outputs;
+        if (outputs && Array.isArray(outputs[key])) {
+            return outputs[key].filter((v) => typeof v === "string");
+        }
+    }
+    return null;
+}
+// ---------------------------------------------------------------------------
+// Child-pipeline envelope handling
+// ---------------------------------------------------------------------------
+/**
+ * Process a child pipeline envelope (from runPipeline/resumePipeline) for the
+ * current stage. Returns a StageOutcome:
+ *   - pause: child needs an agent task — chain paused.
+ *   - fail: child failed (or produced no usable cross-stage data).
+ *   - advanced: child completed; chain row was patched to reflect progress.
+ *
+ * For single-child stages (idea-to-ticket), "advanced" finalizes the stage and
+ * bumps current_stage_index. For fan-out stages (review-ticket), "advanced"
+ * only records the completed child and increments current_child_index; the
+ * caller's loop decides when the whole stage is finished.
+ */
+async function handleChildPipelineEnvelope(persistence, recipe, row, childEnv, opts) {
+    const idx = row.current_stage_index;
+    const stageRecipe = recipe.stages[idx];
+    const total = recipe.stages.length;
+    if (childEnv.status === "needs_agent_task") {
+        const stages = cloneStages(row.stages);
+        const stage = stages[idx];
+        stage.status = "paused";
+        stage.pipeline_run_id = childEnv.pipeline_run_id;
+        if (opts.fanOut) {
+            stage.current_child_index = opts.childIndex ?? stage.current_child_index ?? 0;
+            stage.child_runs = upsertChildRun(stage.child_runs, {
+                ticket_key: opts.ticketKey,
+                pipeline_run_id: childEnv.pipeline_run_id,
+                status: "paused",
+            });
+        }
+        let updated;
+        try {
+            updated = await persistence.patchRun(row.chain_run_id, {
+                stages,
+                status: "paused",
+            });
+        }
+        catch (err) {
+            return { kind: "fail", envelope: persistenceFailEnvelope(err, row, recipe) };
+        }
+        const instruction = `${childEnv.instruction}` +
+            `${buildPriorResultsAppendix(childEnv.results)}\n\n` +
+            `When done, call \`resume_full_automation\` with \`chain_run_id\` ` +
+            `"${row.chain_run_id}" and \`agent_result\` set to the result described above.`;
+        return {
+            kind: "pause",
+            envelope: buildNeedsAgentTaskEnvelope({
+                chainRunId: updated.chain_run_id,
+                chainStage: stageRecipe.pipeline_name,
+                chainStep: idx + 1,
+                chainTotal: total,
+                preamble: buildPreamble(recipe, idx, updated.stages),
+                instruction,
+                pipelineRunId: childEnv.pipeline_run_id,
+                pipelineStep: childEnv.step_index,
+                pipelineTotal: childEnv.total_steps,
+            }),
+        };
+    }
+    if (childEnv.status === "failed") {
+        // Stage 0 vagueness or no-keys produced => VALIDATION. Anchor the sentinel
+        // check to the failure-text fields (the halt error + per-step error/result
+        // strings) rather than the whole stringified envelope, so an echoed input,
+        // agent_result, or arg that happens to contain the token can't misclassify.
+        if (idx === 0 && failedEnvelopeMentions(childEnv, "too_vague_to_ticket")) {
+            return {
+                kind: "fail",
+                envelope: await failChainValidation(persistence, recipe, row, "Idea was too vague to produce a ticket (too_vague_to_ticket)."),
+            };
+        }
+        const code = isChainErrorCode(childEnv.error_code)
+            ? childEnv.error_code
+            : "TOOL_ERROR";
+        const stages = cloneStages(row.stages);
+        if (stages[idx])
+            stages[idx].status = "failed";
+        try {
+            await persistence.patchRun(row.chain_run_id, { stages, status: "failed" });
+        }
+        catch {
+            // best-effort
+        }
+        return {
+            kind: "fail",
+            envelope: failedEnvelope(code, childEnv.error, {
+                chain_run_id: row.chain_run_id,
+                chain_stage: stageRecipe.pipeline_name,
+                chain_step: idx + 1,
+                chain_total: total,
+            }),
+        };
+    }
+    // childEnv.status === "completed"
+    if (opts.fanOut) {
+        const stages = cloneStages(row.stages);
+        const stage = stages[idx];
+        const childIndex = opts.childIndex ?? stage.current_child_index ?? 0;
+        stage.child_runs = upsertChildRun(stage.child_runs, {
+            ticket_key: opts.ticketKey,
+            pipeline_run_id: childEnv.pipeline_run_id,
+            status: "completed",
+        });
+        stage.current_child_index = childIndex + 1;
+        stage.pipeline_run_id = null;
+        stage.status = "running";
+        let updated;
+        try {
+            updated = await persistence.patchRun(row.chain_run_id, {
+                stages,
+                status: "running",
+            });
+        }
+        catch (err) {
+            return { kind: "fail", envelope: persistenceFailEnvelope(err, row, recipe) };
+        }
+        return { kind: "advanced", row: updated };
+    }
+    // Single-child stage (idea-to-ticket): finalize. Derive created keys ONLY from
+    // the upload step's structured payload — never the whole transcript — so
+    // duplicate-detection search hits cannot become review/start-tickets targets.
+    const keys = extractCreatedKeysFromCompletedChild(childEnv);
+    if (keys.length === 0) {
+        return {
+            kind: "fail",
+            envelope: await failChainValidation(persistence, recipe, row, "idea-to-ticket produced no structured created_ticket_keys payload; cannot continue the chain."),
+        };
+    }
+    const stages = cloneStages(row.stages);
+    const stage = stages[idx];
+    stage.status = "completed";
+    stage.pipeline_run_id = null;
+    stage.outputs = { created_ticket_keys: keys };
+    stage.summary = summarizeStageCompletion(stageRecipe.pipeline_name, keys);
+    let updated;
+    try {
+        updated = await persistence.patchRun(row.chain_run_id, {
+            stages,
+            current_stage_index: idx + 1,
+            status: "running",
+            expected_status: "running",
+            expected_current_stage_index: idx,
+        });
+    }
+    catch (err) {
+        return { kind: "fail", envelope: persistenceFailEnvelope(err, row, recipe) };
+    }
+    return { kind: "advanced", row: updated };
+}
+function upsertChildRun(existing, entry) {
+    const list = existing ? [...existing] : [];
+    const i = list.findIndex((c) => c.ticket_key !== undefined && c.ticket_key === entry.ticket_key);
+    if (i >= 0) {
+        list[i] = { ...list[i], ...entry };
+    }
+    else {
+        list.push(entry);
+    }
+    return list;
+}
+function isChainErrorCode(value) {
+    return (value === "VALIDATION" ||
+        value === "NOT_FOUND" ||
+        value === "EXPIRED" ||
+        value === "REPO_MISMATCH" ||
+        value === "TOOL_ERROR");
+}
+function persistenceFailEnvelope(err, row, recipe) {
+    const idx = row.current_stage_index;
+    if (err instanceof ChainPersistenceError) {
+        return failedEnvelope(err.code, err.message, {
+            chain_run_id: row.chain_run_id,
+            chain_stage: recipe.stages[idx]?.pipeline_name,
+            chain_step: idx + 1,
+            chain_total: recipe.stages.length,
+        });
+    }
+    return failedEnvelope("TOOL_ERROR", "An unexpected persistence error occurred.", {
+        chain_run_id: row.chain_run_id,
+        chain_stage: recipe.stages[idx]?.pipeline_name,
+        chain_step: idx + 1,
+        chain_total: recipe.stages.length,
+    });
+}
+// ---------------------------------------------------------------------------
+// Stage starters
+// ---------------------------------------------------------------------------
+async function startOrContinueIdeaToTicketStage(deps, persistence, recipe, row, autoApprove) {
+    const idx = row.current_stage_index;
+    const stageRecipe = recipe.stages[idx];
+    const resolved = buildStageVariables(stageRecipe, row.args);
+    // idea-to-ticket declares [idea, slug, run_id, docs_dir, allow_duplicate,
+    // auto_approve_external, max_children]. `docs_dir` is auto-injected by the
+    // pipeline runner; the rest must be supplied here. `slug`/`run_id` are
+    // DERIVED (not chain inputs), so they cannot be recipe templates — inject
+    // them in code. We also backfill sane defaults so an omitted/empty chain
+    // input still satisfies the child pipeline's required-variable contract.
+    const variables = {
+        ...resolved,
+        slug: deriveSlug(toStringVariable(row.args.idea)),
+        run_id: deriveRunId(row.chain_run_id),
+        auto_approve_external: isNonEmpty(resolved.auto_approve_external)
+            ? resolved.auto_approve_external
+            : toStringVariable(row.args.auto_approve) || "false",
+        allow_duplicate: isNonEmpty(resolved.allow_duplicate)
+            ? resolved.allow_duplicate
+            : "false",
+        max_children: isNonEmpty(resolved.max_children)
+            ? resolved.max_children
+            : "10",
+    };
+    const stages = cloneStages(row.stages);
+    stages[idx].status = "running";
+    stages[idx].input_values = variables;
+    try {
+        row = await persistence.patchRun(row.chain_run_id, { stages, status: "running" });
+    }
+    catch (err) {
+        return { kind: "fail", envelope: persistenceFailEnvelope(err, row, recipe) };
+    }
+    const childEnv = await runPipeline(deps, {
+        pipeline: stageRecipe.pipeline_name,
+        variables,
+        auto_approve: autoApprove,
+        ttl_seconds: numericArg(row.args.ttl_seconds),
+    });
+    return handleChildPipelineEnvelope(persistence, recipe, row, childEnv, {
+        fanOut: false,
+    });
+}
+async function startOrContinueReviewTicketStage(deps, persistence, recipe, row, autoApprove) {
+    const idx = row.current_stage_index;
+    const stageRecipe = recipe.stages[idx];
+    const fanOutInput = stageRecipe.fan_out_input ?? "created_ticket_keys";
+    const keys = resolveCrossStageList(row, idx, fanOutInput);
+    if (!keys || keys.length === 0) {
+        return {
+            kind: "fail",
+            envelope: await failChainValidation(persistence, recipe, row, `Missing cross-stage variable "${fanOutInput}" for review fan-out.`),
+        };
+    }
+    const childIndex = row.stages[idx].current_child_index ?? 0;
+    if (childIndex >= keys.length) {
+        // All children reviewed — finalize the stage.
+        const stages = cloneStages(row.stages);
+        const stage = stages[idx];
+        stage.status = "completed";
+        stage.pipeline_run_id = null;
+        stage.outputs = { reviewed_ticket_keys: keys };
+        stage.summary = summarizeStageCompletion(stageRecipe.pipeline_name, keys);
+        let updated;
+        try {
+            updated = await persistence.patchRun(row.chain_run_id, {
+                stages,
+                current_stage_index: idx + 1,
+                status: "running",
+                expected_status: "running",
+                expected_current_stage_index: idx,
+            });
+        }
+        catch (err) {
+            return { kind: "fail", envelope: persistenceFailEnvelope(err, row, recipe) };
+        }
+        return { kind: "advanced", row: updated };
+    }
+    // Start the next pending child review.
+    const ticketKey = keys[childIndex];
+    const fanOutVariable = stageRecipe.fan_out_variable ?? "ticket_key";
+    const variables = buildStageVariables(stageRecipe, row.args, {
+        item: ticketKey,
+        [fanOutVariable]: ticketKey,
+    });
+    const stages = cloneStages(row.stages);
+    const stage = stages[idx];
+    stage.status = "running";
+    stage.current_child_index = childIndex;
+    stage.input_values = variables;
+    try {
+        row = await persistence.patchRun(row.chain_run_id, { stages, status: "running" });
+    }
+    catch (err) {
+        return { kind: "fail", envelope: persistenceFailEnvelope(err, row, recipe) };
+    }
+    const childEnv = await runPipeline(deps, {
+        pipeline: stageRecipe.pipeline_name,
+        variables,
+        auto_approve: autoApprove,
+        ttl_seconds: numericArg(row.args.ttl_seconds),
+    });
+    return handleChildPipelineEnvelope(persistence, recipe, row, childEnv, {
+        fanOut: true,
+        ticketKey,
+        childIndex,
+    });
+}
+async function startStartTicketsStage(persistence, recipe, row) {
+    const idx = row.current_stage_index;
+    const stageRecipe = recipe.stages[idx];
+    const total = recipe.stages.length;
+    const fanOutInput = stageRecipe.fan_out_input ?? "reviewed_ticket_keys";
+    const keys = resolveCrossStageList(row, idx, fanOutInput);
+    if (!keys || keys.length === 0) {
+        return failChainValidation(persistence, recipe, row, `Missing cross-stage variable "${fanOutInput}" for start-tickets.`);
+    }
+    // Hands-off chain runs (auto_approve=true, the default) spawn the
+    // implementation agents auto-approved too, so they don't stall on approval
+    // gates. A --require-approval run (auto_approve=false) spawns them interactive.
+    const autoApproveFlag = row.args.auto_approve === true ? " --auto-approve" : "";
+    const command = `/start-tickets ${keys.join(" ")}${autoApproveFlag}`;
+    const stages = cloneStages(row.stages);
+    stages[idx].status = "paused";
+    stages[idx].pipeline_run_id = null;
+    stages[idx].input_values = { reviewed_ticket_keys: keys.join(" ") };
+    let updated;
+    try {
+        updated = await persistence.patchRun(row.chain_run_id, {
+            stages,
+            status: "paused",
+        });
+    }
+    catch (err) {
+        return persistenceFailEnvelope(err, row, recipe);
+    }
+    const instruction = `Invoke the start-tickets command in this same session to spawn one ` +
+        `worktree per reviewed ticket:\n\n${command}\n\n` +
+        `When the worktrees have been spawned, call \`resume_full_automation\` with ` +
+        `\`chain_run_id\` "${row.chain_run_id}" and \`agent_result\` set to a short ` +
+        `summary of what start-tickets reported.`;
+    return buildNeedsAgentTaskEnvelope({
+        chainRunId: updated.chain_run_id,
+        chainStage: START_TICKETS_PIPELINE,
+        chainStep: idx + 1,
+        chainTotal: total,
+        preamble: buildPreamble(recipe, idx, updated.stages),
+        instruction,
+    });
+}
+function numericArg(value) {
+    if (typeof value === "number" && Number.isFinite(value))
+        return value;
+    return undefined;
+}
+// ---------------------------------------------------------------------------
+// Chain driver
+// ---------------------------------------------------------------------------
+/**
+ * Drive the chain forward by starting the current stage's next unit of work.
+ * Called after a fresh create, or after a child completes and we advance.
+ * Stops at: a child pipeline pause, the start-tickets seam, completion, a
+ * typed validation failure, or a child pipeline failure.
+ */
+async function continueChainExecution(deps, persistence, recipe, row, autoApprove) {
+    // Bounded by total stages * (max children + 1); guard against runaway loops.
+    let guard = 0;
+    const guardMax = 10000;
+    while (guard++ < guardMax) {
+        const idx = row.current_stage_index;
+        const total = recipe.stages.length;
+        if (idx >= total) {
+            try {
+                row = await persistence.patchRun(row.chain_run_id, { status: "completed" });
+            }
+            catch (err) {
+                return persistenceFailEnvelope(err, row, recipe);
+            }
+            return buildCompletedEnvelope(recipe, row);
+        }
+        const stageRecipe = recipe.stages[idx];
+        let outcome = null;
+        if (stageRecipe.pipeline_name === START_TICKETS_PIPELINE) {
+            return startStartTicketsStage(persistence, recipe, row);
+        }
+        else if (stageRecipe.fan_out_input) {
+            outcome = await startOrContinueReviewTicketStage(deps, persistence, recipe, row, autoApprove);
+        }
+        else {
+            outcome = await startOrContinueIdeaToTicketStage(deps, persistence, recipe, row, autoApprove);
+        }
+        if (outcome.kind === "pause" || outcome.kind === "fail") {
+            return outcome.envelope;
+        }
+        row = outcome.row;
+    }
+    return failedEnvelope("TOOL_ERROR", "Chain execution exceeded its step guard.", {
+        chain_run_id: row.chain_run_id,
+        chain_total: recipe.stages.length,
+    });
+}
+// ---------------------------------------------------------------------------
+// Public entry points
+// ---------------------------------------------------------------------------
+export async function runFullAutomation(deps, input) {
+    try {
+        if (typeof input.idea !== "string" || input.idea.trim() === "") {
+            return failedEnvelope("VALIDATION", "idea must be a non-empty string.");
+        }
+        const agent = input.agent ?? "claude";
+        if (agent !== "claude") {
+            return failedEnvelope("VALIDATION", `Unsupported agent "${String(input.agent)}". Only "claude" is supported.`);
+        }
+        const recipe = deps.chainRecipes[CHAIN_NAME];
+        if (!recipe) {
+            return failedEnvelope("VALIDATION", `Chain recipe "${CHAIN_NAME}" not found.`);
+        }
+        // Full automation is hands-off by default: when the caller omits
+        // auto_approve, run without approval gates. The /full-automation command
+        // sends an explicit boolean (false only for --require-approval); this
+        // default governs direct run_full_automation callers.
+        const autoApprove = input.auto_approve === undefined
+            ? true
+            : normalizeAutoApprove(input.auto_approve);
+        const args = {
+            idea: input.idea,
+            auto_approve: autoApprove,
+            scheduled_at: input.scheduled_at ?? "",
+            max_children: input.max_children,
+            allow_duplicate: input.allow_duplicate,
+            agent,
+            ttl_seconds: input.ttl_seconds,
+        };
+        const initialStages = recipe.stages.map((stage) => ({
+            pipeline_name: stage.pipeline_name,
+            status: "pending",
+        }));
+        const persistence = createChainPersistenceClient({
+            baseUrl: deps.baseUrl,
+            apiKey: deps.apiKey,
+            repoName: deps.repoName,
+        });
+        let row;
+        try {
+            row = await persistence.createRun({
+                chain_name: CHAIN_NAME,
+                args,
+                current_stage_index: 0,
+                stages: initialStages,
+                status: "running",
+                ttl_seconds: input.ttl_seconds,
+            });
+        }
+        catch (err) {
+            if (err instanceof ChainPersistenceError) {
+                return failedEnvelope(err.code, err.message);
+            }
+            return failedEnvelope("TOOL_ERROR", "An unexpected error occurred while creating the chain run.");
+        }
+        return continueChainExecution(deps, persistence, recipe, row, autoApprove);
+    }
+    catch (err) {
+        // The public envelope is intentionally sanitized (no stack traces), but
+        // log to stderr so smoke-testers / operators have a forensic trail (the
+        // MCP server runs outside Sentry).
+        console.error("[chain-orchestrator] unexpected error in runFullAutomation:", err);
+        return failedEnvelope("TOOL_ERROR", "An unexpected error occurred while executing the full-automation chain.");
+    }
+}
+export async function resumeFullAutomation(deps, input) {
+    try {
+        const recipe = deps.chainRecipes[CHAIN_NAME];
+        if (!recipe) {
+            return failedEnvelope("VALIDATION", `Chain recipe "${CHAIN_NAME}" not found.`, { chain_run_id: input.chain_run_id });
+        }
+        const persistence = createChainPersistenceClient({
+            baseUrl: deps.baseUrl,
+            apiKey: deps.apiKey,
+            repoName: deps.repoName,
+        });
+        let row;
+        try {
+            row = await persistence.getRun(input.chain_run_id);
+        }
+        catch (err) {
+            if (err instanceof ChainPersistenceError) {
+                return failedEnvelope(err.code, err.message, {
+                    chain_run_id: input.chain_run_id,
+                });
+            }
+            return failedEnvelope("TOOL_ERROR", "An unexpected error occurred while fetching the chain run.", { chain_run_id: input.chain_run_id });
+        }
+        if (row.status === "expired") {
+            return failedEnvelope("EXPIRED", "Chain run has expired.", {
+                chain_run_id: row.chain_run_id,
+                chain_total: recipe.stages.length,
+            });
+        }
+        const autoApprove = normalizeAutoApprove(row.args.auto_approve);
+        const idx = row.current_stage_index;
+        const stageRecipe = recipe.stages[idx];
+        const total = recipe.stages.length;
+        if (!stageRecipe) {
+            return failedEnvelope("VALIDATION", `Chain run has no active stage at index ${idx}.`, { chain_run_id: row.chain_run_id, chain_total: total });
+        }
+        // Stage-3 start-tickets seam: complete the chain on a non-empty result.
+        if (stageRecipe.pipeline_name === START_TICKETS_PIPELINE) {
+            if (typeof input.agent_result !== "string" ||
+                input.agent_result.trim() === "") {
+                return failedEnvelope("VALIDATION", "agent_result must be a non-empty string to complete the start-tickets stage.", {
+                    chain_run_id: row.chain_run_id,
+                    chain_stage: START_TICKETS_PIPELINE,
+                    chain_step: idx + 1,
+                    chain_total: total,
+                });
+            }
+            const startedKeys = resolveCrossStageList(row, idx, stageRecipe.fan_out_input ?? "reviewed_ticket_keys") ?? [];
+            const stages = cloneStages(row.stages);
+            stages[idx].status = "completed";
+            stages[idx].pipeline_run_id = null;
+            stages[idx].outputs = { started_ticket_keys: startedKeys };
+            stages[idx].summary = summarizeStageCompletion(START_TICKETS_PIPELINE, startedKeys);
+            let updated;
+            try {
+                updated = await persistence.patchRun(row.chain_run_id, {
+                    stages,
+                    current_stage_index: idx + 1,
+                    status: "completed",
+                    expected_status: "paused",
+                    expected_current_stage_index: idx,
+                });
+            }
+            catch (err) {
+                return persistenceFailEnvelope(err, row, recipe);
+            }
+            return buildCompletedEnvelope(recipe, updated);
+        }
+        // Otherwise resume the active paused child pipeline.
+        const activePipelineRunId = row.stages[idx]?.pipeline_run_id;
+        if (!activePipelineRunId) {
+            return failedEnvelope("VALIDATION", `No active child pipeline to resume for stage ${idx + 1}.`, {
+                chain_run_id: row.chain_run_id,
+                chain_stage: stageRecipe.pipeline_name,
+                chain_step: idx + 1,
+                chain_total: total,
+            });
+        }
+        // Snapshot the inner pipeline run before touching anything. This lets us
+        // resume the normal `paused` case, recover idempotently when the inner run
+        // already reached a terminal state on a prior (failed-to-advance) resume,
+        // and refuse cleanly when it is in an indeterminate state.
+        const peek = await peekPipelineRun(deps, activePipelineRunId);
+        if ("error_code" in peek) {
+            return failedEnvelope(peek.error_code, peek.error, {
+                chain_run_id: row.chain_run_id,
+                chain_stage: stageRecipe.pipeline_name,
+                chain_step: idx + 1,
+                chain_total: total,
+            });
+        }
+        if (peek.status !== "paused" &&
+            peek.status !== "completed" &&
+            peek.status !== "failed") {
+            // running / expired — results are not known-final, so we can neither
+            // resume (only paused runs resume) nor safely synthesize an advance.
+            return {
+                status: "failed",
+                error_code: "VALIDATION",
+                error: `Inner pipeline run is in status "${peek.status}" and cannot be ` +
+                    `safely resumed or recovered. Inspect pipeline_run_id ` +
+                    `${activePipelineRunId}.`,
+                chain_run_id: row.chain_run_id,
+                chain_stage: stageRecipe.pipeline_name,
+                chain_step: idx + 1,
+                chain_total: total,
+                pipeline_run_id: activePipelineRunId,
+                resumable: false,
+            };
+        }
+        // Mirror the start path's invariant: the chain row must be "running" while
+        // its inner pipeline is being advanced. The approval-gate pause left the
+        // chain "paused"; flip it back BEFORE the completed-advance patch (which
+        // asserts expected_status "running"). Idempotent (no expected_status) so a
+        // recovery resume of an already-"running" chain does not conflict.
+        try {
+            row = await persistence.patchRun(row.chain_run_id, { status: "running" });
+        }
+        catch (err) {
+            return persistenceFailEnvelope(err, row, recipe);
+        }
+        let childEnv;
+        if (peek.status === "paused") {
+            childEnv = await resumePipeline(deps, {
+                pipeline_run_id: activePipelineRunId,
+                agent_result: input.agent_result,
+            });
+        }
+        else if (peek.status === "completed") {
+            // Idempotent recovery: the inner pipeline already completed on a prior
+            // resume; synthesize its completed envelope (no re-execution) so the
+            // stage advances from the persisted results.
+            childEnv = {
+                status: "completed",
+                pipeline_run_id: peek.pipeline_run_id,
+                pipeline: peek.pipeline,
+                total_steps: peek.total_steps,
+                results: peek.results,
+            };
+        }
+        else {
+            // peek.status === "failed" — let handleChildPipelineEnvelope map it to a
+            // stage failure from the persisted results. The pipeline run row does NOT
+            // persist a top-level error_code (only `status: "failed"` + per-step
+            // results), so the original code cannot be reconstructed here; surface the
+            // failed step's recorded error text for diagnostics and default the code
+            // to TOOL_ERROR.
+            const failedStepError = peek.results.find((r) => !r.ok && typeof r.error === "string")?.error;
+            childEnv = {
+                status: "failed",
+                error_code: "TOOL_ERROR",
+                error: failedStepError
+                    ? `Inner pipeline run failed before the chain could advance: ${failedStepError}`
+                    : "Inner pipeline run failed before the chain could advance.",
+                pipeline_run_id: peek.pipeline_run_id,
+                pipeline: peek.pipeline,
+                results: peek.results,
+            };
+        }
+        const fanOut = !!stageRecipe.fan_out_input;
+        const childIndex = row.stages[idx]?.current_child_index ?? 0;
+        const ticketKey = fanOut
+            ? (resolveCrossStageList(row, idx, stageRecipe.fan_out_input) ?? [])[childIndex]
+            : undefined;
+        const outcome = await handleChildPipelineEnvelope(persistence, recipe, row, childEnv, { fanOut, ticketKey, childIndex });
+        if (outcome.kind === "pause" || outcome.kind === "fail") {
+            return outcome.envelope;
+        }
+        return continueChainExecution(deps, persistence, recipe, outcome.row, autoApprove);
+    }
+    catch (err) {
+        // Sanitized public envelope; log to stderr for a forensic trail (see
+        // runFullAutomation's catch — the MCP server runs outside Sentry).
+        console.error("[chain-orchestrator] unexpected error in resumeFullAutomation:", err);
+        return failedEnvelope("TOOL_ERROR", "An unexpected error occurred while resuming the full-automation chain.", { chain_run_id: input.chain_run_id });
+    }
+}