@bridge_gpt/mcp-server 0.1.13 → 0.1.16

package/build/index.js

@@ -23,8 +23,11 @@ import { VERSION } from "./version.generated.js";
 import { checkForUpdate } from "./update-check.js";
 import { reconstructAgentMarkdown, translateAgentToCopilot } from "./agent-utils.js";
 import { resolveRecipe, loadCustomPipelines } from "./pipeline-utils.js";
+import { runStartTicketsCli } from "./start-tickets.js";
+import { runDoctorCli } from "./doctor.js";
 import { generateDecisionPageHtml } from "./decision-page-template.js";
 import { DecisionPageInputShape } from "./decision-page-schema.js";
+import { runPipeline, resumePipeline, listPipelineRuns, deletePipelineRun, } from "./pipeline-orchestrator.js";
 // Mutable pipeline/instruction state — starts with bundled, merged with user at startup
 const PIPELINES = { ...BUNDLED_PIPELINES };
 const INSTRUCTIONS = { ...BUNDLED_INSTRUCTIONS };
@@ -49,6 +52,9 @@ const POST_HEADERS = {
 function buildUrl(path) {
     return `${BASE_URL.replace(/\/+$/, "")}/jira${path}`;
 }
+function buildApiUrl(path) {
+    return `${BASE_URL.replace(/\/+$/, "")}${path}`;
+}
 function buildGetUrl(path, params) {
     const url = new URL(buildUrl(path));
     for (const [key, value] of Object.entries(params)) {
@@ -518,6 +524,32 @@ automatically provided by the server.
 
 - \`"halt"\` (default) — stop the pipeline immediately on failure
 - \`"warn_and_continue"\` — log a warning and proceed to the next step
+
+## Executing Pipelines
+
+Pipelines defined here can be executed end-to-end via the \`run_pipeline\` MCP
+tool. \`run_pipeline\` returns a unified envelope keyed on \`status\`:
+
+- \`completed\` — the pipeline finished and \`results\` holds the per-step output.
+- \`needs_agent_task\` — the orchestrator paused on an \`agent_task\` step (or an
+  approval-gated \`mcp_call\` when \`auto_approve\` was false). Perform the task
+  described by \`instruction\`, then call \`resume_pipeline\` with the
+  \`pipeline_run_id\` and the resulting string as \`agent_result\`.
+- \`failed\` — terminal failure; \`error_code\` is one of \`VALIDATION\`,
+  \`NOT_FOUND\`, \`EXPIRED\`, \`REPO_MISMATCH\`, or \`TOOL_ERROR\`.
+
+Paused runs auto-expire after an idle TTL (default 24 hours, override via
+\`ttl_seconds\` on \`run_pipeline\`). The TTL is reset on every state transition.
+Use \`list_pipeline_runs\` to recover a \`pipeline_run_id\` if the prior
+\`needs_agent_task\` envelope is no longer in scope.
+
+## \`agent_task\` Instruction Files
+
+When you reference an instruction file (\`instruction_file: "…"\`), the file
+markdown MUST end with a terminal \`## Return\` H2 section describing what the
+agent should pass back as \`resume_pipeline.agent_result\`. The return value
+is a string — do NOT ask the agent to wrap it in JSON unless the instruction
+body explicitly says to serialize structured output.
 `;
     const exampleContent = JSON.stringify({
         name: "Example Pipeline",
@@ -580,41 +612,54 @@ automatically provided by the server.
     }
 }
 // ---------------------------------------------------------------------------
-// CLI: --init
+// CLI subcommand dispatch
 // ---------------------------------------------------------------------------
-if (process.argv.includes("--init")) {
+//
+// `--init`, `--upgrade`, and the positional `start-tickets` subcommand are all
+// routed through a single ``dispatchCliSubcommand`` guard that runs and exits
+// BEFORE the MCP server is constructed and connected. This keeps the single
+// existing ``bridge-api-mcp-server`` bin and leaves a clean seam for future
+// subcommands.
+/**
+ * Ensure a ``package.json`` exists in ``cwd`` for CLI commands that scaffold
+ * into a project. Returns ``null`` on success, or the exact user-facing error
+ * string (preserved verbatim from the previous standalone guards).
+ */
+async function ensurePackageJsonForCliCommand(flagName, cwd) {
     try {
-        await stat(path.join(process.cwd(), "package.json"));
+        await stat(path.join(cwd, "package.json"));
+        return null;
     }
     catch {
-        console.error("Error: No package.json found in current directory.\n" +
-            "--init must be run from your project root (the directory containing package.json).");
-        process.exit(1);
+        return ("Error: No package.json found in current directory.\n" +
+            `${flagName} must be run from your project root (the directory containing package.json).`);
+    }
+}
+/** Run the ``--init`` scaffolding flow. Returns a process exit code. */
+async function runInitCli(cwd) {
+    const guardError = await ensurePackageJsonForCliCommand("--init", cwd);
+    if (guardError) {
+        console.error(guardError);
+        return 1;
     }
     try {
-        await runInit(process.cwd());
-        process.exit(0);
+        await runInit(cwd);
+        return 0;
     }
     catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
         console.error(`Bridge API --init failed: ${msg}`);
-        process.exit(1);
+        return 1;
     }
 }
-// ---------------------------------------------------------------------------
-// CLI: --upgrade
-// ---------------------------------------------------------------------------
-if (process.argv.includes("--upgrade")) {
-    try {
-        await stat(path.join(process.cwd(), "package.json"));
-    }
-    catch {
-        console.error("Error: No package.json found in current directory.\n" +
-            "--upgrade must be run from your project root (the directory containing package.json).");
-        process.exit(1);
+/** Run the ``--upgrade`` flow (npm install latest + re-scaffold). */
+async function runUpgradeCli(cwd) {
+    const guardError = await ensurePackageJsonForCliCommand("--upgrade", cwd);
+    if (guardError) {
+        console.error(guardError);
+        return 1;
     }
     try {
-        const cwd = process.cwd();
         const oldVersion = VERSION;
         console.log("Upgrading @bridge_gpt/mcp-server to latest...\n");
         execSync("npm i @bridge_gpt/mcp-server@latest", { stdio: "inherit" });
@@ -630,14 +675,52 @@ if (process.argv.includes("--upgrade")) {
         console.log("\nRefreshing scaffolded artifacts...\n");
         await runInit(cwd);
         console.log("\nUpgrade complete.");
-        process.exit(0);
+        return 0;
     }
     catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
         console.error(`Bridge API --upgrade failed: ${msg}`);
-        process.exit(1);
+        return 1;
     }
 }
+/**
+ * Route CLI subcommands before MCP server startup. Returns an exit code to
+ * exit the process with, or ``null`` to continue to normal MCP server startup.
+ *
+ * ``--init`` takes precedence over ``--upgrade`` (both are position-independent
+ * flags); ``start-tickets`` is a positional subcommand. Any other unknown,
+ * non-flag positional first token is rejected.
+ */
+async function dispatchCliSubcommand(argv) {
+    const cwd = process.cwd();
+    // A positional subcommand owns the rest of argv, so e.g. `start-tickets --init`
+    // is a start-tickets invocation, not an --init one. Check it before the
+    // position-independent --init / --upgrade flag guards.
+    if (argv[0] === "start-tickets") {
+        return runStartTicketsCli(argv.slice(1));
+    }
+    // The read-only `doctor` subcommand is routed beside start-tickets, before the
+    // flag guards and well before MCP server construction (it never starts the server).
+    if (argv[0] === "doctor") {
+        return runDoctorCli(argv.slice(1));
+    }
+    // --init takes precedence over --upgrade; both are position-independent flags.
+    if (argv.includes("--init")) {
+        return runInitCli(cwd);
+    }
+    if (argv.includes("--upgrade")) {
+        return runUpgradeCli(cwd);
+    }
+    if (argv.length > 0 && !argv[0].startsWith("-")) {
+        console.error(`Error: Unknown subcommand '${argv[0]}'. Run with --help for usage, or omit subcommands to start the MCP server.`);
+        return 1;
+    }
+    return null;
+}
+const cliExitCode = await dispatchCliSubcommand(process.argv.slice(2));
+if (cliExitCode !== null) {
+    process.exit(cliExitCode);
+}
 // ---------------------------------------------------------------------------
 // Server
 // ---------------------------------------------------------------------------
@@ -646,9 +729,70 @@ const server = new McpServer({
     version: "1.0.0",
 });
 // ---------------------------------------------------------------------------
+// Tool registration wrapper (BAPI-275)
+// ---------------------------------------------------------------------------
+//
+// Every MCP tool registered through ``registerTool`` is also recorded in
+// ``TOOL_HANDLERS`` so the new pipeline orchestrator can dispatch existing
+// tools in-process (without round-tripping through stdio). The wrapper
+// preserves the exact return value of ``server.registerTool`` — including
+// its ``.enable()`` / ``.disable()`` methods — and keeps a closure-local
+// ``active`` flag in sync with them, so disabling a tool through the SDK
+// also blocks in-process dispatch through ``TOOL_HANDLERS``.
+const TOOL_HANDLERS = new Map();
+// The wrapper preserves the SDK's generic type signature so existing call
+// sites keep their per-tool input-type inference.
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const registerTool = ((name, config, handler) => {
+    let active = true;
+    const wrappedHandler = async (args, extra) => {
+        if (!active) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            error: "TOOL_DISABLED",
+                            status: 503,
+                            message: `Tool "${name}" is currently disabled.`,
+                        }),
+                    },
+                ],
+            };
+        }
+        return await handler(args, extra);
+    };
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const sdkRegister = server.registerTool.bind(server);
+    const toolHandle = sdkRegister(name, config, wrappedHandler);
+    const inProcessHandler = async (params) => {
+        return await wrappedHandler(params);
+    };
+    TOOL_HANDLERS.set(name, {
+        handler: inProcessHandler,
+        isEnabled: () => active,
+    });
+    // Wrap enable/disable to keep the closure flag in sync with SDK state.
+    if (toolHandle && typeof toolHandle.enable === "function") {
+        const sdkEnable = toolHandle.enable.bind(toolHandle);
+        toolHandle.enable = () => {
+            active = true;
+            return sdkEnable();
+        };
+    }
+    if (toolHandle && typeof toolHandle.disable === "function") {
+        const sdkDisable = toolHandle.disable.bind(toolHandle);
+        toolHandle.disable = () => {
+            active = false;
+            return sdkDisable();
+        };
+    }
+    return toolHandle;
+});
+// ---------------------------------------------------------------------------
 // Tools
 // ---------------------------------------------------------------------------
-server.registerTool("ping", {
+registerTool("ping", {
     description: "Test connectivity to Bridge API. Validates that the API key is accepted and the configured repository is accessible. " +
         "Returns JSON with {status: 'ok', repo_name: '<configured repo>'}. " +
         "Use this as a quick health check before other operations, or to verify your Bridge API configuration is working. " +
@@ -661,7 +805,42 @@ server.registerTool("ping", {
     const text = await handleResponse(resp);
     return { content: [{ type: "text", text }] };
 });
-server.registerTool("get_project_standards", {
+registerTool("second_opinion", {
+    description: "Consult a different LLM model family for a sanity check or technical pushback on a recommendation, plan, or analysis you have already produced. " +
+        "Use this when you want a second, independent opinion before acting on a non-trivial decision — for example, when committing to an implementation approach, a risky refactor, an architectural trade-off, or a recommendation you would otherwise present to a user with no further validation. " +
+        "Pick a provider from a DIFFERENT model family than the one you are running on so the response is genuinely independent (e.g. if you are an OpenAI agent, ask 'anthropic' or 'gemini'). " +
+        "Pick a model tier appropriate for the depth of pushback you want: CHEAP_MODEL for a quick sanity check, BASIC_MODEL for a focused review, PREMIUM_MODEL for serious architectural pushback. " +
+        "The 'prompt' you supply should be a complete, self-contained brief: the full plan, recommendation, or question you want challenged, along with whatever context is needed to evaluate it. The server adds a system prompt that frames the responder as an independent senior engineer and injects lightweight project context. " +
+        "Returns the responding model's reply text plus the resolved provider, tier, and model id. The reply is returned to you as-is; you decide whether to incorporate the feedback. " +
+        "Project authorization uses the standard repo access check; per-project provider gating is intentionally not enforced for this tool.",
+    inputSchema: {
+        prompt: z
+            .string()
+            .describe("The complete, self-contained brief to send to the second-opinion model. " +
+            "Include the full plan, recommendation, analysis, or question you want challenged, plus enough context for the responder to evaluate it independently. " +
+            "This is sent as the user message; the server constructs the system prompt."),
+        provider: z
+            .enum(["anthropic", "openai", "gemini"])
+            .describe("LLM provider family for the second opinion. Choose a family DIFFERENT from the one you are running on so the response is genuinely independent."),
+        model: z
+            .enum(["CHEAP_MODEL", "BASIC_MODEL", "PREMIUM_MODEL"])
+            .describe("Model tier within the chosen provider. CHEAP_MODEL for quick sanity checks, BASIC_MODEL for focused reviews, PREMIUM_MODEL for serious architectural pushback."),
+    },
+}, async ({ prompt, provider, model }) => {
+    const resp = await fetch(buildApiUrl("/llm/second-opinion"), {
+        method: "POST",
+        headers: POST_HEADERS,
+        body: JSON.stringify({
+            repo_name: REPO_NAME,
+            prompt,
+            provider,
+            model,
+        }),
+    });
+    const text = await handleResponse(resp);
+    return { content: [{ type: "text", text }] };
+});
+registerTool("get_project_standards", {
     description: "Retrieve project-specific coding standards, architecture guidelines, testing standards, code review standards, and project context (platform, version, project description) for the configured repository. " +
         "Returns structured markdown with sections for project context, architecture instructions, code review correctness standards, testing stack information, and build analysis. " +
         "Only sections with configured values are included. Returns 404 if no standards are configured. " +
@@ -673,7 +852,7 @@ server.registerTool("get_project_standards", {
     const text = await handleResponse(resp);
     return { content: [{ type: "text", text }] };
 });
-server.registerTool("get_tickets", {
+registerTool("get_tickets", {
     description: "Search for and list Jira tickets from the configured project. " +
         "Filters by query text, status name, or date. Returns up to 'limit' tickets ordered by most recently updated. " +
         "All data is fetched live from Jira. Use get_ticket to retrieve full details for a specific ticket.",
@@ -720,10 +899,11 @@ server.registerTool("get_tickets", {
     const text = await handleResponse(resp);
     return { content: [{ type: "text", text }] };
 });
-server.registerTool("get_ticket", {
+registerTool("get_ticket", {
     description: "Retrieve full details for a single Jira ticket by its key. " +
         "Returns summary, status, type, assignee, reporter, description, and timestamps. " +
-        "All data is fetched live from Jira. Use get_tickets to search/list multiple tickets.",
+        "All data is fetched live from Jira. Use get_tickets to search/list multiple tickets. " +
+        "Use get_comments to fetch comments on the ticket.",
     inputSchema: {
         ticket_number: z
             .string()
@@ -735,7 +915,24 @@ server.registerTool("get_ticket", {
     const text = await handleResponse(resp);
     return { content: [{ type: "text", text }] };
 });
-server.registerTool("create_ticket", {
+registerTool("get_comments", {
+    description: "Retrieve all comments on a Jira ticket, oldest-first. " +
+        "Returns an array of {id, author, body, created, updated}. " +
+        "Comment bodies are Markdown (converted from Jira wiki markup). " +
+        "Use this to read what a developer or stakeholder has said on a ticket. " +
+        "Use add_comment to post a new comment.",
+    inputSchema: {
+        ticket_number: z
+            .string()
+            .describe("Jira ticket key in PROJECT-NUMBER format (e.g. PROJ-123)"),
+    },
+}, async ({ ticket_number }) => {
+    const url = buildGetUrl(`/tickets/${encodeURIComponent(ticket_number)}/comments`, { repo_name: REPO_NAME });
+    const resp = await fetch(url, { headers: GET_HEADERS });
+    const text = await handleResponse(resp);
+    return { content: [{ type: "text", text }] };
+});
+registerTool("create_ticket", {
     description: "Create a new Jira ticket in the configured project. Requires either description or file_path (or both — file_path takes precedence). " +
         "Returns JSON with {ticket_key: 'PROJ-123', url: 'https://...'}. " +
         "The ticket is created immediately in Jira — confirm details with the user before calling. " +
@@ -777,7 +974,7 @@ server.registerTool("create_ticket", {
     const text = await createTicketRequest({ summary, description: resolved.text, issue_type, priority, labels, assignee });
     return { content: [{ type: "text", text: text + resolved.note }] };
 });
-server.registerTool("get_plan", {
+registerTool("get_plan", {
     description: "Retrieve the AI-generated implementation plan for a Jira ticket. " +
         "Returns the full plan as markdown text — present it verbatim without summarizing. " +
         "The plan includes step-by-step implementation guidance with code file references. " +
@@ -805,7 +1002,7 @@ server.registerTool("get_plan", {
     }
     return { content: [{ type: "text", text }] };
 });
-server.registerTool("get_architecture", {
+registerTool("get_architecture", {
     description: "Retrieve the AI-generated architecture plan for a Jira ticket. " +
         "Returns the full architecture plan as markdown text — present it verbatim without summarizing. " +
         "The plan includes high-level architectural decisions, component design, and integration guidance. " +
@@ -833,7 +1030,7 @@ server.registerTool("get_architecture", {
     }
     return { content: [{ type: "text", text }] };
 });
-server.registerTool("get_clarifying_questions", {
+registerTool("get_clarifying_questions", {
     description: "Retrieve AI-generated clarifying questions (for feature/task tickets) or debugging guidance (for bug tickets) for a Jira ticket. " +
         "Returns markdown text with questions that should be resolved before implementation begins. " +
         "Returns 404 if no questions have been generated yet. " +
@@ -860,7 +1057,7 @@ server.registerTool("get_clarifying_questions", {
     }
     return { content: [{ type: "text", text }] };
 });
-server.registerTool("parse_repository", {
+registerTool("parse_repository", {
     description: "Queue a background job to parse and index the repository for Bridge API's AI agents. " +
         "This should be run after major codebase changes so that plans and questions reflect the latest code. " +
         "Returns 202 with {message: 'Repository parsing queued'} on success, " +
@@ -886,7 +1083,7 @@ server.registerTool("parse_repository", {
     const text = await handleResponse(resp);
     return { content: [{ type: "text", text }] };
 });
-server.registerTool("regenerate_directory_map", {
+registerTool("regenerate_directory_map", {
     description: "Regenerate the repository directory map and return the result. " +
         "Unlike parse_repository (which is async), this tool is synchronous — it blocks until " +
         "the directory map is generated and returns the full map text directly. " +
@@ -910,7 +1107,7 @@ server.registerTool("regenerate_directory_map", {
         clearTimeout(timeout);
     }
 });
-server.registerTool("get_parse_status", {
+registerTool("get_parse_status", {
     description: "Check whether a repository parse job is currently running. " +
         "Returns {status: 'in_progress', started_at: '<ISO timestamp>'} if a parse is active, " +
         "or {status: 'idle'} if no parse is running. " +
@@ -923,7 +1120,7 @@ server.registerTool("get_parse_status", {
     const text = await handleResponse(resp);
     return { content: [{ type: "text", text }] };
 });
-server.registerTool("add_comment", {
+registerTool("add_comment", {
     description: "Post a comment on a Jira ticket. The comment appears immediately in Jira. " +
         "Supports markdown formatting. " +
         "For long comments (over ~2000 characters), set attach_as_file to true — " +
@@ -977,7 +1174,7 @@ server.registerTool("add_comment", {
     const text = await handleResponse(resp);
     return { content: [{ type: "text", text: text + resolved.note }] };
 });
-server.registerTool("update_ticket_description", {
+registerTool("update_ticket_description", {
     description: "Update the description of an existing Jira ticket. This is a direct, synchronous update that overwrites the existing description with the provided text. " +
         "The description should be in markdown format — it will be automatically converted to Jira wiki markup. " +
         "This does NOT create a new ticket. Use create_ticket for that. " +
@@ -1009,7 +1206,7 @@ server.registerTool("update_ticket_description", {
     const text = await handleResponse(resp);
     return { content: [{ type: "text", text: text + resolved.note }] };
 });
-server.registerTool("upload_attachment", {
+registerTool("upload_attachment", {
     description: "Upload a local file as an attachment to a Jira ticket. " +
         "Supports text/UTF-8 files only (markdown, plain text, etc.). " +
         "Optionally syncs the content to Bridge API's tickets_links table so retrieval endpoints " +
@@ -1072,7 +1269,7 @@ server.registerTool("upload_attachment", {
     const text = await handleResponse(resp);
     return { content: [{ type: "text", text: text + resolved.note }] };
 });
-server.registerTool("list_attachments", {
+registerTool("list_attachments", {
     description: "List attachments on a Jira ticket. " +
         "Returns metadata (ID, filename, MIME type, size, created date) for each attachment. " +
         "By default, AI-generated attachments are excluded. " +
@@ -1097,7 +1294,7 @@ server.registerTool("list_attachments", {
     return { content: [{ type: "text", text }] };
 });
 const MAX_INLINE_TEXT_LENGTH = 50_000;
-server.registerTool("download_attachment", {
+registerTool("download_attachment", {
     description: "Download an attachment from a Jira ticket and save it to disk. " +
         "Specify either attachment_id or filename (not both). " +
         "For text files, the content is returned inline (truncated at ~50KB) and also saved to disk. " +
@@ -1185,7 +1382,7 @@ server.registerTool("download_attachment", {
     }
     return { content: [{ type: "text", text: resultText }] };
 });
-server.registerTool("request_plan_generation", {
+registerTool("request_plan_generation", {
     description: "Request AI-generated implementation plan for a Jira ticket. " +
         "This triggers an asynchronous background job — results are NOT immediate. " +
         "Processing typically takes 1-5 minutes depending on ticket complexity and number of attachments. " +
@@ -1254,7 +1451,7 @@ server.registerTool("request_plan_generation", {
         `Use get_plan with ticket_number "${ticket_number}" to retrieve the plan once processing completes.`;
     return { content: [{ type: "text", text: confirmationText }] };
 });
-server.registerTool("request_architecture", {
+registerTool("request_architecture", {
     description: "Request AI-generated architecture plan for a Jira ticket. " +
         "This triggers an asynchronous background job — results are NOT immediate. " +
         "Processing typically takes 2-4 minutes depending on ticket complexity. " +
@@ -1323,7 +1520,7 @@ server.registerTool("request_architecture", {
         `Use get_architecture with ticket_number "${ticket_number}" to retrieve the architecture plan once processing completes.`;
     return { content: [{ type: "text", text: confirmationText }] };
 });
-server.registerTool("request_clarifying_questions", {
+registerTool("request_clarifying_questions", {
     description: "Request AI-generated clarifying questions or debugging guidance for a Jira ticket. " +
         "This triggers an asynchronous background job — results are NOT immediate. " +
         "Processing typically takes 1-5 minutes. " +
@@ -1396,7 +1593,7 @@ server.registerTool("request_clarifying_questions", {
 // ---------------------------------------------------------------------------
 // Ticket Quality Critique
 // ---------------------------------------------------------------------------
-server.registerTool("get_ticket_critique", {
+registerTool("get_ticket_critique", {
     description: "Retrieve AI-generated ticket quality critique for a Jira ticket. " +
         "Returns markdown text with a structured critique covering Standards Conformance Analysis, " +
         "Standards Deviations, and Suggested Improvements. " +
@@ -1424,7 +1621,7 @@ server.registerTool("get_ticket_critique", {
     }
     return { content: [{ type: "text", text }] };
 });
-server.registerTool("request_ticket_critique", {
+registerTool("request_ticket_critique", {
     description: "Request AI-generated ticket critique for a Jira ticket. " +
         "This triggers an asynchronous background job — results are NOT immediate. " +
         "Processing typically takes 1-5 minutes. " +
@@ -1496,7 +1693,7 @@ server.registerTool("request_ticket_critique", {
 // ---------------------------------------------------------------------------
 // Combined Ticket Review (clarify + critique)
 // ---------------------------------------------------------------------------
-server.registerTool("request_ticket_review", {
+registerTool("request_ticket_review", {
     description: "Request a combined ticket review that generates BOTH clarifying questions (or debugging guidance for bug tickets) " +
         "AND a ticket quality critique in parallel on the server, halving wall-clock latency vs. running the two " +
         "requests sequentially. This triggers an asynchronous background job — results are NOT immediate. " +
@@ -1603,7 +1800,7 @@ server.registerTool("request_ticket_review", {
 // ---------------------------------------------------------------------------
 // Reimplement Context
 // ---------------------------------------------------------------------------
-server.registerTool("request_reimplement_context", {
+registerTool("request_reimplement_context", {
     description: "Request processing of new attachments and context assembly for a previously-implemented Jira ticket. " +
         "Use this for follow-up requests on tickets that have already been through the plan+implement cycle. " +
         "This triggers an asynchronous background job to process new attachments/images. " +
@@ -1669,7 +1866,7 @@ server.registerTool("request_reimplement_context", {
         `Use get_reimplement_context with ticket_number "${ticket_number}" to retrieve the results once processing completes.`;
     return { content: [{ type: "text", text: confirmationText }] };
 });
-server.registerTool("get_reimplement_context", {
+registerTool("get_reimplement_context", {
     description: "Retrieve the assembled reimplement context for a Jira ticket. " +
         "Returns a markdown document with new/changed information diffed against stored state, " +
         "the original ticket description, and the existing implementation plan. " +
@@ -1710,7 +1907,7 @@ server.registerTool("get_reimplement_context", {
 // ---------------------------------------------------------------------------
 // Ticket Lifecycle Tracking
 // ---------------------------------------------------------------------------
-server.registerTool("track_ticket", {
+registerTool("track_ticket", {
     description: "Insert a ticket into Bridge API's database for lifecycle tracking. This registers the ticket so that workflow state timestamps (critique, clarify, plan, implement) can be tracked. " +
         "If the ticket is already tracked, this is a safe no-op — it upserts the description and repo_name without error. " +
         "Call this after creating a ticket with create_ticket to enable state tracking. " +
@@ -1731,7 +1928,7 @@ server.registerTool("track_ticket", {
     const text = await handleResponse(resp);
     return { content: [{ type: "text", text }] };
 });
-server.registerTool("update_ticket_state", {
+registerTool("update_ticket_state", {
     description: "Update workflow state timestamps on a tracked ticket. Each specified field is set to the current UTC timestamp on the server. " +
         "Valid field names: 'critique_called', 'critique_answered', 'clarify_called', 'clarify_answered', 'plan_generated', 'implemented', 'reimplement_called'. " +
         "The ticket must already be tracked (via track_ticket) or a 404 error is returned. " +
@@ -1751,7 +1948,7 @@ server.registerTool("update_ticket_state", {
     const text = await handleResponse(resp);
     return { content: [{ type: "text", text }] };
 });
-server.registerTool("get_ticket_state", {
+registerTool("get_ticket_state", {
     description: "Retrieve workflow state timestamps and artifact existence flags for a tracked ticket. " +
         "Returns timestamps for each state field (critique_called, critique_answered, clarify_called, clarify_answered, plan_generated, implemented, reimplement_called) " +
         "and boolean flags indicating whether artifacts exist (has_clarifying_questions, has_critique, has_plan). " +
@@ -1769,7 +1966,7 @@ server.registerTool("get_ticket_state", {
 // ---------------------------------------------------------------------------
 // Jira Transitions
 // ---------------------------------------------------------------------------
-server.registerTool("get_jira_transitions", {
+registerTool("get_jira_transitions", {
     description: "List available Jira workflow transitions for a ticket. Returns each transition's id, name, and target status. " +
         "Use this to discover what status changes are possible for a given ticket. " +
         "The repo_name is automatically injected from the configured environment.",
@@ -1782,7 +1979,7 @@ server.registerTool("get_jira_transitions", {
     const text = await handleResponse(resp);
     return { content: [{ type: "text", text }] };
 });
-server.registerTool("update_jira_status", {
+registerTool("update_jira_status", {
     description: "Transition a Jira ticket to a specified target status by executing a workflow transition. " +
         "Provide either target_status (matched case-insensitively against available transitions) or transition_id (used directly). " +
         "If transition_id is provided, it takes precedence over target_status. " +
@@ -1809,7 +2006,7 @@ server.registerTool("update_jira_status", {
     const text = await handleResponse(resp);
     return { content: [{ type: "text", text }] };
 });
-server.registerTool("resolve_target_status", {
+registerTool("resolve_target_status", {
     description: "Resolve the post-PR target Jira status for the configured repository using an LLM agent. " +
         "The agent selects the workflow status that best represents 'code committed via PR but not yet tested.' " +
         "Results are cached per-project — subsequent calls return the cached value unless force_rerun is true. " +
@@ -1840,12 +2037,15 @@ server.registerTool("resolve_target_status", {
 const VALID_CONFIG_FIELDS = [
     "review_instructions", "documentation_instructions", "architecture_instructions",
     "unit_testing_instructions", "e2e_testing_instructions",
+    "unit_testing_stack", "e2e_testing_stack",
     "frontend_correctness_standards", "backend_correctness_standards",
     "template_correctness_standards", "style_correctness_standards",
     "design_principles",
-    "post_pr_target_status", "ci_check_config",
+    "post_pr_target_status", "ci_check_config", "ci_followup_config",
+    "allow_mutating_smoke_ops",
+    "selected_mcp_slugs",
 ].join(", ");
-server.registerTool("list_config_fields", {
+registerTool("list_config_fields", {
     description: "List all configurable fields available for reading and updating via the Bridge API. " +
         "Returns each field's name and a description of its purpose. No database values are returned — " +
         "use get_config_field to read a specific field's current value. " +
@@ -1857,7 +2057,7 @@ server.registerTool("list_config_fields", {
     const text = await handleResponse(resp);
     return { content: [{ type: "text", text }] };
 });
-server.registerTool("get_my_role", {
+registerTool("get_my_role", {
     description: "Check the role and auth source for the current API key. " +
         "Returns JSON with {role: \"admin\" | \"member\" | null, source: \"user_access\" | \"legacy\"}. " +
         "Use this to check if the current key has admin permissions before attempting configuration updates " +
@@ -1869,7 +2069,7 @@ server.registerTool("get_my_role", {
     const text = await handleResponse(resp);
     return { content: [{ type: "text", text }] };
 });
-server.registerTool("get_config_field", {
+registerTool("get_config_field", {
     description: "Read the current value and metadata for a specific configuration field. " +
         "Returns the field's current database value (or null if not set), along with a description of its purpose and examples of helpful content. " +
         "Use this before update_config_field to understand the current state and build upon it rather than overwriting blindly.",
@@ -1882,25 +2082,108 @@ server.registerTool("get_config_field", {
     const text = await handleResponse(resp);
     return { content: [{ type: "text", text }] };
 });
-server.registerTool("update_config_field", {
+registerTool("update_config_field", {
     description: "Update a specific configuration field in the Bridge database. " +
         "These fields control LLM behavior during code review, planning, and documentation. " +
         "Always call get_config_field first to read the current value and build upon it. " +
         "Returns 400 if the field name is invalid, 404 if the repository has no configuration row yet.",
     inputSchema: {
         field_name: z.string().describe(`The configuration field to update. Valid options: ${VALID_CONFIG_FIELDS}`),
-        value: z.string().optional().describe("The new value for the configuration field. Provide either value or file_path, not both. " +
-            "Omit both value and file_path to set the field to NULL (clearing it)."),
+        value: z.union([z.string(), z.boolean(), z.array(z.string())]).optional().describe("The new value for the configuration field. Provide either value or file_path, not both. " +
+            "Most fields take a string; scalar boolean fields (e.g. allow_mutating_smoke_ops) take true/false. " +
+            "The selected_mcp_slugs field takes a JSON array of supported MCP validation manual slug strings " +
+            "(e.g. [\"b2c-commerce-developer\", \"playwright-mcp\", \"pwa-kit-mcp\"]) — pass an array of strings, " +
+            "not a comma-delimited string; an empty array clears the selection. " +
+            "For string fields, omit both value and file_path to set the field to NULL (clearing it). " +
+            "Scalar boolean fields are NOT NULL and have no clear/null state: omitting the value writes false " +
+            "(matching the API-layer coercion), so pass true/false explicitly."),
         file_path: z.string().optional().describe("Path to a local file whose contents will be used as the new value. " +
             "Useful for large configuration values like detailed review instructions. " +
-            "The file must be UTF-8 encoded and under 1MB."),
+            "The file must be UTF-8 encoded and under 1MB. " +
+            "Not supported for scalar boolean fields like allow_mutating_smoke_ops."),
     },
 }, async ({ field_name, value, file_path }) => {
+    // JSONB array config fields (e.g. selected_mcp_slugs): forward the array value
+    // as JSON. Never join into a comma-delimited string — the backend expects a
+    // real JSON array and validates each slug against the mcp_docs allowlist.
+    const ARRAY_CONFIG_FIELDS = ["selected_mcp_slugs"];
+    if (ARRAY_CONFIG_FIELDS.includes(field_name)) {
+        if (file_path) {
+            return {
+                isError: true,
+                content: [{
+                        type: "text",
+                        text: JSON.stringify({
+                            error: `'${field_name}' is a JSON array field; file_path updates are not supported. Pass value as an array of slug strings.`,
+                        }),
+                    }],
+            };
+        }
+        // An omitted value clears the selection (empty array). Any defined value is
+        // forwarded verbatim as JSON so the backend can validate/reject it.
+        const arrayValue = value === undefined ? [] : value;
+        const resp = await fetch(buildUrl(`/config-field/${encodeURIComponent(field_name)}`), {
+            method: "PUT",
+            headers: POST_HEADERS,
+            body: JSON.stringify({ repo_name: REPO_NAME, value: arrayValue }),
+        });
+        const text = await handleResponse(resp);
+        return { content: [{ type: "text", text }] };
+    }
+    // Scalar boolean config fields: reject file-path updates and normalize boolean
+    // true/false and string "true"/"false" to a real boolean before persisting.
+    const BOOLEAN_CONFIG_FIELDS = ["allow_mutating_smoke_ops"];
+    if (BOOLEAN_CONFIG_FIELDS.includes(field_name)) {
+        if (file_path) {
+            return {
+                isError: true,
+                content: [{
+                        type: "text",
+                        text: JSON.stringify({
+                            error: `'${field_name}' is a scalar boolean field; file_path updates are not supported. Pass value: true or value: false.`,
+                        }),
+                    }],
+            };
+        }
+        // NOT NULL boolean column: an omitted value writes false (no clear/null state),
+        // intentionally aligned with the API-layer coercion in update_config_field_endpoint.
+        let boolValue = false;
+        if (typeof value === "boolean") {
+            boolValue = value;
+        }
+        else if (typeof value === "string") {
+            const normalized = value.trim().toLowerCase();
+            if (normalized === "true") {
+                boolValue = true;
+            }
+            else if (normalized === "false" || normalized === "") {
+                boolValue = false;
+            }
+            else {
+                return {
+                    isError: true,
+                    content: [{
+                            type: "text",
+                            text: JSON.stringify({
+                                error: `Invalid value for '${field_name}': '${value}'. Expected true or false.`,
+                            }),
+                        }],
+                };
+            }
+        }
+        const resp = await fetch(buildUrl(`/config-field/${encodeURIComponent(field_name)}`), {
+            method: "PUT",
+            headers: POST_HEADERS,
+            body: JSON.stringify({ repo_name: REPO_NAME, value: boolValue }),
+        });
+        const text = await handleResponse(resp);
+        return { content: [{ type: "text", text }] };
+    }
     // Allow omitting both value and file_path to set NULL
     let finalValue = null;
     let note = "";
     if (value || file_path) {
-        const resolved = await resolveTextOrFile(value, file_path, "value");
+        const resolved = await resolveTextOrFile(typeof value === "string" ? value : undefined, file_path, "value");
         if (!resolved.ok)
             return resolved.errorResponse;
         finalValue = resolved.text;
@@ -1914,10 +2197,63 @@ server.registerTool("update_config_field", {
     const text = await handleResponse(resp);
     return { content: [{ type: "text", text: text + note }] };
 });
-// ---------------------------------------------------------------------------
-// Deep Research
-// ---------------------------------------------------------------------------
-server.registerTool("request_deep_research", {
+function formatDeepResearchProviderReason(meta) {
+    if (!meta)
+        return "";
+    const parts = [];
+    const reason = meta.incomplete_details?.reason;
+    if (reason) {
+        parts.push(`provider reason: ${reason}`);
+    }
+    const errMsg = meta.error?.message;
+    const errCode = meta.error?.code;
+    if (errMsg || errCode) {
+        if (errCode && errMsg) {
+            parts.push(`provider error: ${errCode}: ${errMsg}`);
+        }
+        else if (errMsg) {
+            parts.push(`provider error: ${errMsg}`);
+        }
+        else if (errCode) {
+            parts.push(`provider error: ${errCode}`);
+        }
+    }
+    return parts.length ? ` (${parts.join("; ")})` : "";
+}
+function _safeIsoMs(value) {
+    if (!value)
+        return null;
+    const ms = new Date(value).getTime();
+    if (Number.isNaN(ms))
+        return null;
+    return ms;
+}
+function formatDeepResearchElapsed(createdAt, lastPollAt) {
+    const createdMs = _safeIsoMs(createdAt);
+    if (createdMs === null)
+        return "";
+    const now = Date.now();
+    const startedMs = Math.max(0, now - createdMs);
+    const startedMin = Math.floor(startedMs / 60_000);
+    const lastPollMs = _safeIsoMs(lastPollAt);
+    let pollSuffix = "";
+    if (lastPollMs !== null) {
+        const ageSec = Math.max(0, Math.floor((now - lastPollMs) / 1000));
+        pollSuffix = `, last poll ${ageSec}s ago`;
+    }
+    return ` (running ${startedMin}m${pollSuffix})`;
+}
+function formatDeepResearchFailure(body) {
+    const kind = body.error_kind || body.error_message || "Unknown error";
+    const reason = formatDeepResearchProviderReason(body.provider_status_meta);
+    return `Deep research failed: ${kind}${reason}. Consider using standard web searches to gather the information incrementally.`;
+}
+function formatDeepResearchStatus(body, taskId) {
+    const elapsed = formatDeepResearchElapsed(body.created_at, body.last_poll_at);
+    const reason = formatDeepResearchProviderReason(body.provider_status_meta);
+    return `Status: ${body.status}${elapsed}${reason} (task_id: ${taskId}). Try again in a minute.`;
+}
+registerTool("request_deep_research", {
     description: "Submit a deep research request on a technical topic using AI-powered web search. " +
         "Returns a task_id for tracking the research progress. " +
         "\n\n" +
@@ -1981,6 +2317,7 @@ server.registerTool("request_deep_research", {
     const MAX_TIMEOUT_MS = 15 * 60 * 1000; // 15 minutes
     let pollIntervalMs = 15_000; // start at 15 seconds
     let lastStatus = "queued";
+    let latestStatusBody = null;
     while (Date.now() - startTime < MAX_TIMEOUT_MS) {
         await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
         const elapsed = Math.round((Date.now() - startTime) / 1000);
@@ -1993,15 +2330,15 @@ server.registerTool("request_deep_research", {
         }
         const statusBody = (await statusResp.json());
         lastStatus = statusBody.status;
+        latestStatusBody = statusBody;
         if (lastStatus === "completed") {
             break;
         }
         if (lastStatus === "failed") {
-            const errorMsg = statusBody.error_message || "Unknown error";
             return {
                 content: [{
                         type: "text",
-                        text: JSON.stringify({ error: "INTERNAL_ERROR", status: 500, message: `Deep research failed: ${errorMsg}. Consider using standard web searches to gather the information incrementally.` }),
+                        text: formatDeepResearchFailure(statusBody),
                     }],
             };
         }
@@ -2011,10 +2348,13 @@ server.registerTool("request_deep_research", {
         }
     }
     if (lastStatus !== "completed") {
+        const statusSuffix = latestStatusBody
+            ? ` ${formatDeepResearchStatus(latestStatusBody, taskId)}`
+            : "";
         return {
             content: [{
                     type: "text",
-                    text: JSON.stringify({ error: "GATEWAY_TIMEOUT", status: 504, message: `Deep research timed out after 15 minutes (task_id: ${taskId}). The task may still be processing on the server. Use get_deep_research with this task_id to check later, or use standard web searches to gather the information incrementally.` }),
+                    text: `Deep research timed out after 15 minutes (task_id: ${taskId}).${statusSuffix} The task may still be processing on the server. Use get_deep_research with this task_id to check later, or use standard web searches to gather the information incrementally.`,
                 }],
         };
     }
@@ -2034,7 +2374,7 @@ server.registerTool("request_deep_research", {
     }
     return { content: [{ type: "text", text: resultText }] };
 });
-server.registerTool("get_deep_research", {
+registerTool("get_deep_research", {
     description: "Retrieve the result of a previously submitted deep research request. " +
         "Returns the full markdown research report if the task is completed, " +
         "or a structured status response if still processing or failed. " +
@@ -2055,11 +2395,10 @@ server.registerTool("get_deep_research", {
     }
     const statusBody = (await statusResp.json());
     if (statusBody.status === "failed") {
-        const errorMsg = statusBody.error_message || "Unknown error";
         return {
             content: [{
                     type: "text",
-                    text: JSON.stringify({ error: "INTERNAL_ERROR", status: 500, message: `Deep research failed: ${errorMsg}. Consider using standard web searches to gather the information incrementally.` }),
+                    text: formatDeepResearchFailure(statusBody),
                 }],
         };
     }
@@ -2067,7 +2406,7 @@ server.registerTool("get_deep_research", {
         return {
             content: [{
                     type: "text",
-                    text: JSON.stringify({ status: statusBody.status, task_id, message: `Deep research is still ${statusBody.status}. Try again in a minute.` }),
+                    text: formatDeepResearchStatus(statusBody, task_id),
                 }],
         };
     }
@@ -2087,10 +2426,219 @@ server.registerTool("get_deep_research", {
     }
     return { content: [{ type: "text", text: resultText }] };
 });
+const BRAINSTORM_TERMINAL_STATUSES = new Set([
+    "completed",
+    "failed",
+    "skipped",
+]);
+function isBrainstormTerminalStatus(status) {
+    return BRAINSTORM_TERMINAL_STATUSES.has(status);
+}
+function sanitizeProviderForFilename(provider) {
+    // Defensive: allow letters/digits/hyphen/underscore only; collapse runs and
+    // trim trailing punctuation. Falls back to "provider" for an empty result.
+    const cleaned = provider
+        .toLowerCase()
+        .replace(/[^a-z0-9_-]+/g, "-")
+        .replace(/-+/g, "-")
+        .replace(/^-+|-+$/g, "");
+    return cleaned || "provider";
+}
+async function pollBrainstormUntilTerminal(brainstormId, repoName) {
+    const startTime = Date.now();
+    const MAX_TIMEOUT_MS = 15 * 60 * 1000;
+    let pollIntervalMs = 15_000;
+    let latest = null;
+    while (Date.now() - startTime < MAX_TIMEOUT_MS) {
+        await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
+        const statusUrl = buildGetUrl(`/brainstorms/${brainstormId}/status`, { repo_name: repoName });
+        const statusResp = await fetch(statusUrl, { headers: GET_HEADERS });
+        if (!statusResp.ok) {
+            return latest;
+        }
+        latest = (await statusResp.json());
+        const allTerminal = latest.rows.every((row) => isBrainstormTerminalStatus(row.status));
+        if (allTerminal) {
+            return latest;
+        }
+        if (Date.now() - startTime > 60_000) {
+            pollIntervalMs = 30_000;
+        }
+    }
+    return latest;
+}
+async function saveBrainstormResultsLocally(envelope) {
+    const dir = getDocsPath("brainstorm");
+    const savedPaths = [];
+    for (const row of envelope.results) {
+        const markdown = row.markdown;
+        if (!markdown) {
+            continue;
+        }
+        const providerSegment = sanitizeProviderForFilename(row.provider);
+        const filename = `${envelope.brainstorm_id}-${providerSegment}.md`;
+        const filePath = path.join(dir, filename);
+        try {
+            await mkdir(dir, { recursive: true });
+            await writeFile(filePath, markdown, "utf-8");
+            savedPaths.push(filePath);
+        }
+        catch {
+            // Skip rows that fail to write — never block the response.
+        }
+    }
+    return savedPaths;
+}
+function formatBrainstormToolResponse(envelope, savedPaths) {
+    const lines = [];
+    lines.push(`# Brainstorm ${envelope.brainstorm_id}`);
+    lines.push(`Repo: ${envelope.repo_name}`);
+    lines.push("");
+    for (const row of envelope.results) {
+        lines.push(`## ${row.provider} — status: ${row.status}`);
+        lines.push(`error_kind: ${row.error_kind ?? "null"}`);
+        if (row.error_message) {
+            lines.push(`error_message: ${row.error_message}`);
+        }
+        if (row.markdown) {
+            lines.push("");
+            lines.push(row.markdown);
+        }
+        lines.push("");
+    }
+    if (savedPaths.length > 0) {
+        lines.push("---");
+        lines.push("Saved files:");
+        for (const p of savedPaths) {
+            lines.push(`- ${p}`);
+        }
+    }
+    return lines.join("\n");
+}
+registerTool("request_brainstorm", {
+    description: "Submit a brainstorm request that fans out the task to two opinion-provider LLMs " +
+        "(default: OpenAI + Gemini) and then runs a synthesizer pass over the completed opinions. " +
+        "Returns a brainstorm_id you can use with get_brainstorm. " +
+        "\n\n" +
+        "BEHAVIOR: By default, returns immediately with a brainstorm_id. Set wait_for_result=true " +
+        "to poll for terminal status (up to 15 minutes), then retrieve and optionally save the result. " +
+        "When save_locally=true (default), each provider's markdown is written to " +
+        "BAPI_DOCS_DIR/brainstorm/{brainstorm_id}-{provider}.md, including {brainstorm_id}-synthesizer.md.",
+    inputSchema: {
+        task_description: z.string().describe("Free-form description of the task to brainstorm about. Sent verbatim — " +
+            "this tool does NOT read task_description from a file."),
+        repo_name: z.string().optional().describe("Repository name. Defaults to BAPI_REPO_NAME from the environment."),
+        ticket_number: z.string().optional().describe("Optional Jira ticket key (e.g. PROJ-123) to associate with the brainstorm. " +
+            "Ticket 1 only stores this for cross-reference — no Jira writes happen."),
+        providers: z.array(z.string()).optional().describe("Opinion-provider LLMs. Defaults to ['openai', 'gemini']. " +
+            "A single-provider request still inserts a synthesizer row but pre-skips it."),
+        concerns: z.string().optional().describe("Optional caller-supplied concerns to surface to the brainstorm agents."),
+        wait_for_result: z.boolean().optional().describe("When true, polls until every row reaches a terminal status (max 15 minutes), " +
+            "then returns the full result envelope. When false (default), returns immediately."),
+        save_locally: z.boolean().optional().describe("When true (default), writes each provider's markdown to BAPI_DOCS_DIR/brainstorm/ " +
+            "after the result is fetched."),
+        prior_brainstorm_id: z.string().optional().describe("Optional brainstorm_id from an earlier brainstorm to refine. " +
+            "When provided, the new brainstorm receives the prior brainstorm's " +
+            "synthesizer markdown, or a completed opinion-provider fallback, as prior context."),
+    },
+}, async ({ task_description, repo_name, ticket_number, providers, concerns, wait_for_result, save_locally, prior_brainstorm_id, }) => {
+    const effectiveRepo = repo_name && repo_name.length > 0 ? repo_name : REPO_NAME;
+    const effectiveProviders = providers !== undefined ? providers : ["openai", "gemini"];
+    const shouldWait = wait_for_result === true;
+    const shouldSave = save_locally !== false;
+    const submitPayload = {
+        repo_name: effectiveRepo,
+        task_description,
+        providers: effectiveProviders,
+    };
+    if (ticket_number)
+        submitPayload.ticket_number = ticket_number;
+    if (concerns)
+        submitPayload.concerns = concerns;
+    if (prior_brainstorm_id) {
+        submitPayload.prior_brainstorm_request_id = prior_brainstorm_id;
+    }
+    const submitResp = await fetch(buildUrl("/brainstorms"), {
+        method: "POST",
+        headers: POST_HEADERS,
+        body: JSON.stringify(submitPayload),
+    });
+    if (!submitResp.ok) {
+        const errorText = await handleResponse(submitResp);
+        return { content: [{ type: "text", text: errorText }] };
+    }
+    const submitBody = (await submitResp.json());
+    if (!shouldWait) {
+        const confirmation = `Brainstorm submitted (brainstorm_id: ${submitBody.brainstorm_id}). ` +
+            `Providers: ${submitBody.providers.join(", ")}. ` +
+            `Synthesizer status: ${submitBody.synthesizer_status}. ` +
+            `Use get_brainstorm with brainstorm_id ${submitBody.brainstorm_id} to retrieve results.`;
+        return { content: [{ type: "text", text: confirmation }] };
+    }
+    const finalStatus = await pollBrainstormUntilTerminal(submitBody.brainstorm_id, effectiveRepo);
+    if (!finalStatus) {
+        return {
+            content: [{
+                    type: "text",
+                    text: `Brainstorm timed out before reaching terminal status ` +
+                        `(brainstorm_id: ${submitBody.brainstorm_id}). Use get_brainstorm later.`,
+                }],
+        };
+    }
+    const resultUrl = buildGetUrl(`/brainstorms/${submitBody.brainstorm_id}/result`, { repo_name: effectiveRepo });
+    const resultResp = await fetch(resultUrl, { headers: GET_HEADERS });
+    if (!resultResp.ok) {
+        const errorText = await handleResponse(resultResp);
+        return { content: [{ type: "text", text: errorText }] };
+    }
+    const envelope = (await resultResp.json());
+    let savedPaths = [];
+    if (shouldSave) {
+        savedPaths = await saveBrainstormResultsLocally(envelope);
+    }
+    return {
+        content: [{
+                type: "text",
+                text: formatBrainstormToolResponse(envelope, savedPaths),
+            }],
+    };
+});
+registerTool("get_brainstorm", {
+    description: "Retrieve the result envelope for a previously submitted brainstorm by brainstorm_id. " +
+        "Returns all rows (opinion providers + synthesizer), including error_kind for every row. " +
+        "When save_locally=true (default), writes each provider's markdown to " +
+        "BAPI_DOCS_DIR/brainstorm/{brainstorm_id}-{provider}.md (including the synthesizer file). " +
+        "DB-only retrieval — never falls back to Jira attachments.",
+    inputSchema: {
+        brainstorm_id: z.string().describe("The brainstorm_id (UUID) returned by request_brainstorm."),
+        repo_name: z.string().optional().describe("Repository name. Defaults to BAPI_REPO_NAME from the environment."),
+        save_locally: z.boolean().optional().describe("When true (default), writes each provider's markdown to BAPI_DOCS_DIR/brainstorm/."),
+    },
+}, async ({ brainstorm_id, repo_name, save_locally }) => {
+    const effectiveRepo = repo_name && repo_name.length > 0 ? repo_name : REPO_NAME;
+    const shouldSave = save_locally !== false;
+    const resultUrl = buildGetUrl(`/brainstorms/${brainstorm_id}/result`, { repo_name: effectiveRepo });
+    const resultResp = await fetch(resultUrl, { headers: GET_HEADERS });
+    if (!resultResp.ok) {
+        const errorText = await handleResponse(resultResp);
+        return { content: [{ type: "text", text: errorText }] };
+    }
+    const envelope = (await resultResp.json());
+    let savedPaths = [];
+    if (shouldSave) {
+        savedPaths = await saveBrainstormResultsLocally(envelope);
+    }
+    return {
+        content: [{
+                type: "text",
+                text: formatBrainstormToolResponse(envelope, savedPaths),
+            }],
+    };
+});
 // ---------------------------------------------------------------------------
 // VCS & CI Tools
 // ---------------------------------------------------------------------------
-server.registerTool("create_pull_request", {
+registerTool("create_pull_request", {
     description: "Create a pull request on the configured VCS provider (GitHub or Bitbucket). " +
         "Returns a structured response with {available, reason, action, detail}. " +
         "If a PR already exists for the head branch, returns it with created=false. " +
@@ -2119,7 +2667,7 @@ server.registerTool("create_pull_request", {
     const text = await handleResponse(resp);
     return { content: [{ type: "text", text }] };
 });
-const resolveCiChecksTool = server.registerTool("resolve_ci_checks", {
+const resolveCiChecksTool = registerTool("resolve_ci_checks", {
     description: "Discover and classify CI checks for the configured repository. " +
         "Queries GitHub Check Runs + Commit Statuses APIs (or Bitbucket Build Statuses), " +
         "then uses Branch Protection API or LLM to determine which checks are required for merging. " +
@@ -2155,7 +2703,7 @@ const resolveCiChecksTool = server.registerTool("resolve_ci_checks", {
     }
     return { content: [{ type: "text", text }] };
 });
-const pollCiChecksTool = server.registerTool("poll_ci_checks", {
+const pollCiChecksTool = registerTool("poll_ci_checks", {
     description: "Poll the current status of CI checks for a specific commit. " +
         "Requires that resolve_ci_checks has been called first to populate the check configuration. " +
         "Returns per-check status, all_complete, all_passed, and unknown_checks fields. " +
@@ -2204,9 +2752,30 @@ async function checkCiConfigAndDisablePoll() {
 // Check config before connecting
 await checkCiConfigAndDisablePoll();
 // ---------------------------------------------------------------------------
+// Custom pipeline loading (BAPI-275)
+// ---------------------------------------------------------------------------
+//
+// Custom user pipelines must be merged into PIPELINES + INSTRUCTIONS BEFORE
+// the run_pipeline tool is registered so its embedded catalog includes both
+// bundled and user entries. The merge result is also used by list_pipelines
+// and get_pipeline_recipe below — every caller must see the same final
+// objects.
+{
+    const instructionsDir = path.join(path.dirname(BAPI_PIPELINES_DIR), "instructions");
+    const customResult = await loadCustomPipelines(BAPI_PIPELINES_DIR, instructionsDir, BUNDLED_INSTRUCTIONS);
+    for (const [key, pipeline] of Object.entries(customResult.pipelines)) {
+        if (key in BUNDLED_PIPELINES) {
+            console.error(`Warning: user pipeline "${key}" overrides bundled pipeline.`);
+        }
+        PIPELINES[key] = pipeline;
+    }
+    Object.assign(INSTRUCTIONS, customResult.instructions);
+    userPipelineKeys = customResult.userPipelineKeys;
+}
+// ---------------------------------------------------------------------------
 // Pipeline Recipe Tools
 // ---------------------------------------------------------------------------
-server.registerTool("get_docs_dir", {
+registerTool("get_docs_dir", {
     description: "Return the locally configured docs directory path (BAPI_DOCS_DIR, default docs/tmp). " +
         "No parameters. Use this instead of reading the BAPI_DOCS_DIR environment variable directly, " +
         "which requires shell access and may be blocked on some AI coding platforms.",
@@ -2214,7 +2783,7 @@ server.registerTool("get_docs_dir", {
 }, async () => {
     return { content: [{ type: "text", text: BAPI_DOCS_DIR }] };
 });
-server.registerTool("list_pipelines", {
+registerTool("list_pipelines", {
     description: "List all available pipeline recipes with their names, descriptions, and required variables. " +
         "No parameters. Use this to discover available pipelines before calling get_pipeline_recipe.",
     inputSchema: {},
@@ -2229,7 +2798,7 @@ server.registerTool("list_pipelines", {
         content: [{ type: "text", text: JSON.stringify(list, null, 2) }],
     };
 });
-server.registerTool("get_pipeline_recipe", {
+registerTool("get_pipeline_recipe", {
     description: "Retrieve a fully resolved pipeline recipe by name. Substitutes variables, resolves instruction " +
         "file references to inline content, and returns an ordered array of executable steps. " +
         "Each step is either an mcp_call (with tool name and params) or an agent_task (with instruction text). " +
@@ -2247,8 +2816,16 @@ server.registerTool("get_pipeline_recipe", {
             .array(z.string())
             .optional()
             .describe("Step tool names or descriptions to omit from the recipe"),
+        auto_approve: z
+            .boolean()
+            .optional()
+            .describe("When true, automatically approve all approval-gated steps. " +
+            "For implement-ticket this skips the commit/push approval pause; " +
+            "for review-ticket this skips the HTML decision page and selects " +
+            "each item's recommended option. Pass via this top-level parameter, " +
+            "not via the variables map."),
     },
-}, async ({ pipeline: pipelineName, variables, skip_steps }) => {
+}, async ({ pipeline: pipelineName, variables, skip_steps, auto_approve }) => {
     const pipelineDef = PIPELINES[pipelineName];
     if (!pipelineDef) {
         const available = Object.keys(PIPELINES).join(", ");
@@ -2263,9 +2840,27 @@ server.registerTool("get_pipeline_recipe", {
                 }],
         };
     }
+    if (variables && "auto_approve" in variables) {
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify({
+                        error: ERROR_CODES[400] ?? "BAD_REQUEST",
+                        status: 400,
+                        message: "Pass auto_approve via the top-level parameter, not via the variables map.",
+                    }),
+                }],
+        };
+    }
     try {
-        const mergedVariables = { docs_dir: BAPI_DOCS_DIR, provider: "", second_opinion: "", ...(variables ?? {}) };
-        const recipe = resolveRecipe(pipelineDef, INSTRUCTIONS, mergedVariables, skip_steps);
+        const mergedVariables = {
+            docs_dir: BAPI_DOCS_DIR,
+            provider: "",
+            second_opinion: "",
+            auto_approve: auto_approve ? "true" : "",
+            ...(variables ?? {}),
+        };
+        const recipe = resolveRecipe(pipelineDef, INSTRUCTIONS, mergedVariables, skip_steps, !!auto_approve);
         return {
             content: [{
                     type: "text",
@@ -2287,9 +2882,148 @@ server.registerTool("get_pipeline_recipe", {
     }
 });
 // ---------------------------------------------------------------------------
+// Pipeline Execution Tools (BAPI-275)
+// ---------------------------------------------------------------------------
+//
+// run_pipeline / resume_pipeline / list_pipeline_runs promote pipelines from
+// declarative JSON recipes into first-class callable operations. They share
+// a unified response envelope (status: completed | needs_agent_task | failed)
+// with a strict error_code enum (VALIDATION | NOT_FOUND | EXPIRED |
+// REPO_MISMATCH | TOOL_ERROR). Pipeline state is persisted server-side; the
+// idle TTL defaults to 24 hours and is auto-extended on every state
+// transition.
+function buildPipelineCatalogDescription() {
+    const lines = [];
+    for (const [key, pipeline] of Object.entries(PIPELINES)) {
+        const source = userPipelineKeys.has(key) ? " (user)" : "";
+        const desc = pipeline.description ?? "";
+        lines.push(`- ${key}${source} — ${desc}`);
+    }
+    return lines.join("\n");
+}
+function buildPipelineOrchestratorDeps() {
+    return {
+        baseUrl: BASE_URL,
+        apiKey: API_KEY,
+        repoName: REPO_NAME,
+        docsDir: BAPI_DOCS_DIR,
+        pipelines: PIPELINES,
+        instructions: INSTRUCTIONS,
+        toolHandlers: TOOL_HANDLERS,
+    };
+}
+registerTool("run_pipeline", {
+    description: "Execute a Bridge API pipeline by name. The orchestrator runs steps sequentially, " +
+        "dispatching mcp_call steps in-process and pausing on agent_task steps with a " +
+        "needs_agent_task envelope. Returns a unified envelope keyed on `status`: " +
+        "`completed` (terminal success with `results`), `needs_agent_task` (pause — read " +
+        "`instruction`, perform the task, then call `resume_pipeline` with the resulting " +
+        "string as `agent_result`), or `failed` (terminal error — check `error_code`: " +
+        "VALIDATION | NOT_FOUND | EXPIRED | REPO_MISMATCH | TOOL_ERROR). " +
+        "Paused runs auto-expire after an idle TTL (default 24 hours; override with " +
+        "`ttl_seconds`). The TTL is reset on every state transition.\n\n" +
+        "Available pipelines:\n" +
+        buildPipelineCatalogDescription(),
+    inputSchema: {
+        pipeline: z
+            .string()
+            .describe("Pipeline name (e.g. 'review-ticket', 'implement-ticket')"),
+        variables: z
+            .record(z.string())
+            .optional()
+            .describe("Key-value pairs for variable substitution (e.g. { ticket_key: 'BAPI-123' }). " +
+            "Do NOT pass `auto_approve` here — use the top-level parameter."),
+        auto_approve: z
+            .union([z.boolean(), z.literal("true"), z.literal("false")])
+            .optional()
+            .describe("When true, approval-gated mcp_call steps execute directly. When false or " +
+            "omitted, the orchestrator synthesises a needs_agent_task pause so the agent " +
+            "can confirm with the user before resuming. Accepts boolean or 'true'/'false' " +
+            "strings for MCP clients that serialize booleans as strings."),
+        ttl_seconds: z
+            .number()
+            .int()
+            .positive()
+            .optional()
+            .describe("Override the default 24-hour idle TTL for this run. Must be a positive integer."),
+    },
+}, async (input) => {
+    const result = await runPipeline(buildPipelineOrchestratorDeps(), input);
+    return {
+        content: [
+            { type: "text", text: JSON.stringify(result, null, 2) },
+        ],
+    };
+});
+registerTool("resume_pipeline", {
+    description: "Resume a paused pipeline run with the result of the agent_task. Provide the " +
+        "`pipeline_run_id` returned by the prior needs_agent_task envelope, and the string " +
+        "the instruction's `## Return` section asked you to produce as `agent_result`. " +
+        "`agent_result` is always a string — do not wrap it in JSON unless the instruction " +
+        "explicitly asked you to serialize structured output. Returns the same unified " +
+        "envelope shape as `run_pipeline`.",
+    inputSchema: {
+        pipeline_run_id: z
+            .string()
+            .describe("The pipeline_run_id returned by a prior needs_agent_task envelope"),
+        agent_result: z
+            .string()
+            .describe("The string the paused instruction's ## Return section asked you to produce"),
+    },
+}, async (input) => {
+    const result = await resumePipeline(buildPipelineOrchestratorDeps(), input);
+    return {
+        content: [
+            { type: "text", text: JSON.stringify(result, null, 2) },
+        ],
+    };
+});
+registerTool("list_pipeline_runs", {
+    description: "List recent pipeline runs for the configured repository, newest first. Returns " +
+        "metadata only — `resolved_recipe`, resolved params, instruction text, results, " +
+        "and agent outputs are intentionally excluded. Use this to recover a " +
+        "`pipeline_run_id` when an earlier needs_agent_task envelope is no longer in " +
+        "scope (e.g. after compaction or a client restart). " +
+        "Optionally filter by `status`: running | paused | completed | failed | expired.",
+    inputSchema: {
+        status: z
+            .enum(["running", "paused", "completed", "failed", "expired"])
+            .optional()
+            .describe("Optional status filter"),
+    },
+}, async (input) => {
+    const result = await listPipelineRuns(buildPipelineOrchestratorDeps(), input);
+    return {
+        content: [
+            { type: "text", text: JSON.stringify(result, null, 2) },
+        ],
+    };
+});
+registerTool("delete_pipeline_run", {
+    description: "Delete a pipeline run row (any status). Use this to discard orphaned `running` " +
+        "rows from a previous session that can't be resumed (resume_pipeline only accepts " +
+        "`paused`), to clean up after a failed run, or to remove a no-longer-needed paused " +
+        "session. Returns `{ status: 'completed', deleted: true, pipeline_run_id }` on " +
+        "success, or a `failed` envelope with error_code in (VALIDATION | NOT_FOUND | " +
+        "REPO_MISMATCH | TOOL_ERROR). Repo-scoped: the row's stored repo_name must match " +
+        "the caller's repo.",
+    inputSchema: {
+        pipeline_run_id: z
+            .string()
+            .describe("UUID of the pipeline run to delete."),
+    },
+}, async (input) => {
+    const result = await deletePipelineRun(buildPipelineOrchestratorDeps(), input);
+    return {
+        content: [
+            { type: "text", text: JSON.stringify(result, null, 2) },
+        ],
+    };
+});
+// ---------------------------------------------------------------------------
 // generate_decision_page
 // ---------------------------------------------------------------------------
-server.registerTool("generate_decision_page", {
+registerTool("generate_decision_page", {
     description: "Generate a local HTML decision page for capturing user decisions on ticket review findings. " +
         "Renders recommendation-driven review decisions sourced from the combined review-and-resolution " +
         "document, with per-option consequence lines, a closed-by-default codebase-evidence disclosure, " +
@@ -2385,17 +3119,6 @@ server.registerTool("generate_decision_page", {
 // ---------------------------------------------------------------------------
 // Entry point
 // ---------------------------------------------------------------------------
-// Load custom user pipelines before accepting connections
-const instructionsDir = path.join(path.dirname(BAPI_PIPELINES_DIR), "instructions");
-const customResult = await loadCustomPipelines(BAPI_PIPELINES_DIR, instructionsDir, BUNDLED_INSTRUCTIONS);
-for (const [key, pipeline] of Object.entries(customResult.pipelines)) {
-    if (key in BUNDLED_PIPELINES) {
-        console.error(`Warning: user pipeline "${key}" overrides bundled pipeline.`);
-    }
-    PIPELINES[key] = pipeline;
-}
-Object.assign(INSTRUCTIONS, customResult.instructions);
-userPipelineKeys = customResult.userPipelineKeys;
 const transport = new StdioServerTransport();
 await server.connect(transport);
 console.error("Bridge API MCP server running on stdio");