@bridge_gpt/mcp-server 0.2.9 → 0.2.10

package/build/index.js

@@ -21,29 +21,26 @@ import { writeFile, mkdir, readFile, stat, rename, chmod, unlink } from "fs/prom
 import path from "path";
 import os from "os";
 import { fileURLToPath } from "url";
-import { execSync } from "child_process";
-import { createRequire } from "module";
 import { PIPELINES as BUNDLED_PIPELINES, INSTRUCTIONS as BUNDLED_INSTRUCTIONS, CHAIN_RECIPES } from "./pipelines.generated.js";
-import { COMMANDS } from "./commands.generated.js";
-import { AGENTS } from "./agents.generated.js";
 import { VERSION } from "./version.generated.js";
 import { README } from "./readme.generated.js";
 import { checkForUpdate } from "./update-check.js";
-import { reconstructAgentMarkdown, translateAgentToCopilot } from "./agent-utils.js";
 import { resolveRecipe, loadCustomPipelines } from "./pipeline-utils.js";
+import { runInit } from "./init.js";
 import { runStartTicketsCli } from "./start-tickets.js";
 import { runReviewTicketsCli } from "./review-tickets.js";
 import { runDoctorCli } from "./doctor.js";
 import { runScheduleRunCli } from "./schedule-run.js";
 import { runMcpInvokeCli } from "./mcp-invoke.js";
 import { runAgentCapabilitiesCli } from "./agent-capabilities/cli.js";
-import { validateRepoName } from "./bridge-config.js";
-import { ensureGitignored as ensureGitignoredShared } from "./git-ignore-utils.js";
+import { runInstallBridgeCli } from "./install-bridge.js";
+import { runUpgradeCli } from "./upgrade-cli.js";
 import { resolveBapiCredentials, upsertBapiCredential, getPrimaryCredentialStorePath, } from "./credential-store.js";
 import { runCredentialsCli } from "./credentials-cli.js";
 import { registerConductorTools } from "./conductor/tools.js";
+import { resolveProfile, profileIncludes } from "./mcp-profile.js";
 import { runConductorCli } from "./conductor/cli.js";
-import { observePrCiFromPollResponse } from "./conductor/pr-ci-producer.js";
+import { observePrCiFromPollResponse, resolveDispatchRunIdForBinding } from "./conductor/pr-ci-producer.js";
 import { generateDecisionPageHtml } from "./decision-page-template.js";
 import { DecisionPageInputShape } from "./decision-page-schema.js";
 import { slugify, saveBrainstormResultsToDir, } from "./brainstorm-files.js";
@@ -77,6 +74,10 @@ function parseDefaultOnEnvFlag(value) {
 // authoritative for whether advice exists and for its exact wording
 // (compute_upgrade()). Defaults to enabled; fail-open on any unexpected value.
 const UPGRADE_ADVICE_SURFACING_ENABLED = parseDefaultOnEnvFlag(process.env.BAPI_MCP_UPGRADE_ADVICE_ENABLED);
+// BAPI-434 Phase 2a: startup-time profile gating. Resolved once at module load;
+// unknown / blank / undefined values fail safe to "core" (smallest surface).
+// Dynamic mid-session switching via tools/list_changed is intentionally unsupported.
+const BRIDGE_MCP_PROFILE = resolveProfile(process.env.BRIDGE_MCP_PROFILE);
 // ---------------------------------------------------------------------------
 // Resolved-once credential + path accessors (BAPI-338)
 //
@@ -911,451 +912,6 @@ async function requestTicketReview(args) {
     return { content: [{ type: "text", text }] };
 }
 // ---------------------------------------------------------------------------
-// CLI: --init scaffolds slash commands and MCP configs into the current project
-// ---------------------------------------------------------------------------
-function buildBridgeApiEntry(cwd) {
-    // Secret-free by design: BAPI_API_KEY is NEVER scaffolded into generated MCP
-    // config. The server self-resolves the key from the environment or the
-    // home-dir credential store (~/.config/bridge/credentials.json) at runtime.
-    return {
-        command: "npx",
-        args: ["-y", "@bridge_gpt/mcp-server"],
-        env: {
-            BAPI_BASE_URL: "https://bridgegpt-api.com",
-            BAPI_REPO_NAME: "YOUR_REPO_NAME",
-            BAPI_DOCS_DIR: "docs/tmp",
-            BAPI_PROJECT_ROOT: cwd,
-        },
-    };
-}
-/**
- * Choose the `repo_name` written into a scaffolded `.bridge/config`. Uses the
- * cwd basename when it passes manifest repo-name validation; otherwise falls
- * back to the `YOUR_REPO_NAME` placeholder for the user to edit.
- */
-export function chooseScaffoldRepoName(cwd) {
-    const validated = validateRepoName(path.basename(cwd));
-    return validated.ok ? validated.value : "YOUR_REPO_NAME";
-}
-/** Build the secret-free `.bridge/config` TOML scaffolded by `--init`. */
-export function buildBridgeConfigManifest(repoName) {
-    return [
-        "# Bridge API repository MCP manifest (committed, secret-free, machine-agnostic).",
-        "#",
-        "# Inherited by every git worktree; start-tickets worktree provisioning reads it",
-        "# to decide which Bridge API MCP registrations to write. Do not add credentials,",
-        "# connection URLs, or machine-specific paths here — those are resolved at runtime.",
-        "",
-        `repo_name = "${repoName}"`,
-        "",
-        "[[mcp]]",
-        'target = "bapi"',
-        "",
-        "# Optional: declare additional (Tier-2) MCP targets here. Each non-bapi target",
-        "# names the real command/args to launch and the credential-store bundle that",
-        "# supplies its secrets — never the secrets themselves. Uncomment and adapt:",
-        "#",
-        "# [[mcp]]",
-        '# target = "sfcc"',
-        '# command = "npx"',
-        '# args = ["-y", "@salesforce/b2c-dx-mcp"]',
-        '# secret_bundle = "sfcc:YOUR_SANDBOX_ID"',
-        "",
-    ].join("\n");
-}
-async function ensureGitignored(cwd, filePath) {
-    await ensureGitignoredShared(cwd, filePath, {
-        readFile: (p) => readFile(p, "utf-8"),
-        writeFile: (p, data) => writeFile(p, data, "utf-8"),
-        mkdir: (p, options) => mkdir(p, options),
-    });
-}
-/**
- * Core initialization logic shared by --init and --upgrade.
- * Runs all scaffolding phases without calling process.exit().
- */
-async function runInit(cwd) {
-    // ---- Phase 1: IDE Detection ----
-    const ideDetection = {
-        claude: true,
-        vscode: false,
-        cursor: false,
-        windsurf: false,
-    };
-    try {
-        await stat(path.join(cwd, ".vscode"));
-        ideDetection.vscode = true;
-    }
-    catch { }
-    try {
-        await stat(path.join(cwd, ".cursor"));
-        ideDetection.cursor = true;
-    }
-    catch { }
-    if (!ideDetection.cursor && process.env.CURSOR_TRACE_DIR)
-        ideDetection.cursor = true;
-    try {
-        await stat(path.join(cwd, ".windsurf"));
-        ideDetection.windsurf = true;
-    }
-    catch { }
-    if (!ideDetection.windsurf) {
-        try {
-            await stat(path.join(cwd, ".windsurfrules"));
-            ideDetection.windsurf = true;
-        }
-        catch { }
-    }
-    const detectedIDEs = Object.entries(ideDetection)
-        .filter(([, v]) => v)
-        .map(([k]) => k);
-    console.log(`Bridge API --init: detected IDEs: ${detectedIDEs.join(", ")}`);
-    // ---- Phase 2: Windsurf manual instructions ----
-    if (ideDetection.windsurf) {
-        const windsurfSnippet = JSON.stringify({ mcpServers: { "bridge-api": buildBridgeApiEntry(cwd) } }, null, 2);
-        console.log("\n⚠ Windsurf does not support project-local MCP configuration.\n" +
-            "Add the following to ~/.codeium/windsurf/mcp_config.json:\n\n" +
-            windsurfSnippet + "\n");
-    }
-    // ---- Phase 3: Config file handling ----
-    const configTargets = [
-        { path: ".mcp.json", topLevelKey: "mcpServers", shouldCreate: true },
-        { path: ".vscode/mcp.json", topLevelKey: "servers", shouldCreate: ideDetection.vscode },
-        { path: ".cursor/mcp.json", topLevelKey: "mcpServers", shouldCreate: ideDetection.cursor },
-    ];
-    const configActions = [];
-    let anyCreatedOrAdded = false;
-    for (const target of configTargets) {
-        const fullPath = path.join(cwd, target.path);
-        let fileExists = false;
-        try {
-            await stat(fullPath);
-            fileExists = true;
-        }
-        catch { }
-        if (!target.shouldCreate && !fileExists) {
-            configActions.push({ path: target.path, action: "skipped — IDE not detected" });
-            continue;
-        }
-        if (fileExists) {
-            // Read and parse existing file
-            const raw = await readFile(fullPath, "utf-8");
-            let parsed;
-            try {
-                parsed = JSON.parse(raw);
-            }
-            catch {
-                console.warn(`  ${target.path} skipped — invalid JSON format`);
-                configActions.push({ path: target.path, action: "skipped — invalid JSON" });
-                continue;
-            }
-            const topLevel = parsed[target.topLevelKey];
-            if (topLevel && topLevel["bridge-api"]) {
-                // Entry exists — update BAPI_PROJECT_ROOT only
-                if (!topLevel["bridge-api"].env)
-                    topLevel["bridge-api"].env = {};
-                topLevel["bridge-api"].env.BAPI_PROJECT_ROOT = cwd;
-                await writeFile(fullPath, JSON.stringify(parsed, null, 2) + "\n", "utf-8");
-                configActions.push({ path: target.path, action: "updated BAPI_PROJECT_ROOT" });
-            }
-            else {
-                // Entry missing — add it, preserving existing content
-                if (!parsed[target.topLevelKey])
-                    parsed[target.topLevelKey] = {};
-                parsed[target.topLevelKey]["bridge-api"] = buildBridgeApiEntry(cwd);
-                await writeFile(fullPath, JSON.stringify(parsed, null, 2) + "\n", "utf-8");
-                configActions.push({ path: target.path, action: "added entry" });
-                anyCreatedOrAdded = true;
-            }
-        }
-        else {
-            // Create new file
-            await mkdir(path.dirname(fullPath), { recursive: true });
-            const content = { [target.topLevelKey]: { "bridge-api": buildBridgeApiEntry(cwd) } };
-            await writeFile(fullPath, JSON.stringify(content, null, 2) + "\n", "utf-8");
-            await ensureGitignored(cwd, target.path);
-            configActions.push({ path: target.path, action: "created" });
-            anyCreatedOrAdded = true;
-        }
-    }
-    console.log("\nMCP config files:");
-    for (const entry of configActions) {
-        console.log(`  ${entry.path}: ${entry.action}`);
-    }
-    // ---- Phase 4: Scaffold slash command directories ----
-    const commandDirs = [path.join(cwd, ".claude", "commands")];
-    if (ideDetection.cursor) {
-        commandDirs.push(path.join(cwd, ".cursor", "commands"));
-    }
-    const writtenFiles = new Set();
-    const skippedFiles = new Set();
-    const overwrittenFiles = new Set();
-    for (const dir of commandDirs) {
-        await mkdir(dir, { recursive: true });
-        for (const [filename, content] of Object.entries(COMMANDS)) {
-            const target = path.join(dir, filename);
-            try {
-                const existing = await readFile(target, "utf-8");
-                if (existing === content) {
-                    skippedFiles.add(filename);
-                    continue;
-                }
-                overwrittenFiles.add(filename);
-            }
-            catch { /* file doesn't exist */ }
-            await writeFile(target, content, "utf-8");
-            writtenFiles.add(filename);
-        }
-    }
-    // A file written in any directory takes priority over skipped
-    for (const f of writtenFiles)
-        skippedFiles.delete(f);
-    const total = Object.keys(COMMANDS).length;
-    const dirNames = commandDirs.map((d) => path.relative(cwd, d)).join(" and ");
-    console.log(`\nSlash commands: scaffolded ${total} commands into ${commandDirs.length} director${commandDirs.length === 1 ? "y" : "ies"}`);
-    if (writtenFiles.size > 0)
-        console.log(`  Written: ${writtenFiles.size}`);
-    if (overwrittenFiles.size > 0)
-        console.log(`  Overwritten (content changed): ${overwrittenFiles.size}`);
-    if (skippedFiles.size > 0)
-        console.log(`  Skipped (unchanged): ${skippedFiles.size}`);
-    console.log(`  ${dirNames}`);
-    // ---- Phase 5: Scaffold agent directories ----
-    const agentWritten = new Set();
-    const agentSkipped = new Set();
-    const agentOverwritten = new Set();
-    // Always scaffold to .claude/agents/
-    const claudeAgentsDir = path.join(cwd, ".claude", "agents");
-    await mkdir(claudeAgentsDir, { recursive: true });
-    for (const [key, agent] of Object.entries(AGENTS)) {
-        const filename = `${key}.md`;
-        const content = reconstructAgentMarkdown(agent.frontmatter, agent.body);
-        const target = path.join(claudeAgentsDir, filename);
-        try {
-            const existing = await readFile(target, "utf-8");
-            if (existing === content) {
-                agentSkipped.add(filename);
-                continue;
-            }
-            agentOverwritten.add(filename);
-        }
-        catch { /* file doesn't exist */ }
-        await writeFile(target, content, "utf-8");
-        agentWritten.add(filename);
-    }
-    // Scaffold to .github/agents/ for VS Code / Copilot
-    if (ideDetection.vscode) {
-        const copilotAgentsDir = path.join(cwd, ".github", "agents");
-        await mkdir(copilotAgentsDir, { recursive: true });
-        for (const [key, agent] of Object.entries(AGENTS)) {
-            const filename = `${key}.agent.md`;
-            const content = translateAgentToCopilot(agent.frontmatter, agent.body);
-            const target = path.join(copilotAgentsDir, filename);
-            try {
-                const existing = await readFile(target, "utf-8");
-                if (existing === content) {
-                    agentSkipped.add(filename);
-                    continue;
-                }
-                agentOverwritten.add(filename);
-            }
-            catch { /* file doesn't exist */ }
-            await writeFile(target, content, "utf-8");
-            agentWritten.add(filename);
-        }
-    }
-    // TODO: Add Cursor agent scaffolding when Cursor publishes a formal agent spec
-    // A file written in any directory takes priority over skipped
-    for (const f of agentWritten)
-        agentSkipped.delete(f);
-    const agentTotal = Object.keys(AGENTS).length;
-    console.log(`\nAgents: scaffolded ${agentTotal} agent${agentTotal === 1 ? "" : "s"}`);
-    if (agentWritten.size > 0)
-        console.log(`  Written: ${agentWritten.size}`);
-    if (agentOverwritten.size > 0)
-        console.log(`  Overwritten (content changed): ${agentOverwritten.size}`);
-    if (agentSkipped.size > 0)
-        console.log(`  Skipped (unchanged): ${agentSkipped.size}`);
-    // ---- Phase 6: Scaffold custom pipeline directories ----
-    const pipelinesDir = path.resolve(cwd, process.env.BAPI_PIPELINES_DIR ?? ".bridge/pipelines");
-    const instrDir = path.join(path.dirname(pipelinesDir), "instructions");
-    await mkdir(pipelinesDir, { recursive: true });
-    await mkdir(instrDir, { recursive: true });
-    const readmePath = path.join(pipelinesDir, "README.md");
-    const examplePath = path.join(pipelinesDir, "example-pipeline.json");
-    const readmeContent = `# Custom Pipelines
-
-Place custom pipeline JSON files in this directory. They will be loaded at
-server startup and available alongside the bundled pipelines.
-
-## JSON Schema
-
-Each pipeline file must be a JSON object with these fields:
-
-| Field         | Type       | Required | Description                              |
-|---------------|------------|----------|------------------------------------------|
-| \`name\`        | string     | yes      | Display name of the pipeline             |
-| \`description\`  | string     | no       | Short description shown in list_pipelines |
-| \`variables\`    | string[]   | no       | Variable names for substitution          |
-| \`steps\`        | Step[]     | yes      | Ordered list of steps to execute         |
-
-## Step Types
-
-### mcp_call
-Calls an MCP tool with specific parameters.
-\`\`\`json
-{
-  "type": "mcp_call",
-  "tool": "tool_name",
-  "params": { "key": "value" },
-  "description": "What this step does",
-  "on_error": "halt",
-  "requires_approval": false
-}
-\`\`\`
-
-### agent_task
-Gives the agent a free-form instruction to execute.
-\`\`\`json
-{
-  "type": "agent_task",
-  "instruction": "Do something specific",
-  "description": "What this step does",
-  "on_error": "warn_and_continue"
-}
-\`\`\`
-
-Or reference an instruction file from \`.bridge/instructions/\`:
-\`\`\`json
-{
-  "type": "agent_task",
-  "instruction_file": "my-instructions.md",
-  "description": "What this step does"
-}
-\`\`\`
-
-## Variables
-
-Declare variables in the \`variables\` array and reference them with \`{variable_name}\`
-in step params, instructions, and descriptions. The \`docs_dir\` variable is
-automatically provided by the server.
-
-## on_error
-
-- \`"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",
-        description: "A sample pipeline demonstrating all step types and features.",
-        variables: ["ticket_key"],
-        steps: [
-            {
-                type: "mcp_call",
-                tool: "get_ticket",
-                params: { ticket_number: "{ticket_key}" },
-                description: "Fetch the ticket details from Jira",
-                on_error: "halt",
-            },
-            {
-                type: "agent_task",
-                instruction: "Read the ticket details above and summarize the key requirements in 3 bullet points.",
-                description: "Summarize ticket requirements",
-                on_error: "halt",
-            },
-            {
-                type: "agent_task",
-                instruction: "Search the codebase for files related to the ticket and list the top 5 most relevant files.",
-                description: "Find relevant source files",
-                on_error: "warn_and_continue",
-            },
-            {
-                type: "mcp_call",
-                tool: "add_comment",
-                params: {
-                    ticket_number: "{ticket_key}",
-                    comment_text: "Pipeline analysis complete. See agent output for details.",
-                },
-                description: "Post a summary comment to the ticket",
-                on_error: "warn_and_continue",
-                requires_approval: true,
-            },
-        ],
-    }, null, 2) + "\n";
-    try {
-        await stat(readmePath);
-        console.log(`  ${path.relative(cwd, readmePath)} (skipped — already exists)`);
-    }
-    catch {
-        await writeFile(readmePath, readmeContent, "utf-8");
-        console.log(`  ${path.relative(cwd, readmePath)} (written)`);
-    }
-    try {
-        await stat(examplePath);
-        console.log(`  ${path.relative(cwd, examplePath)} (skipped — already exists)`);
-    }
-    catch {
-        await writeFile(examplePath, exampleContent, "utf-8");
-        console.log(`  ${path.relative(cwd, examplePath)} (written)`);
-    }
-    console.log(`  ${path.relative(cwd, instrDir)}/ (ensured)`);
-    // ---- Phase 6b: Scaffold the committed secret-free `.bridge/config` ----
-    // This manifest is committed and inherited by every worktree; it is the
-    // input to start-tickets worktree MCP provisioning. It is intentionally
-    // NOT gitignored (unlike the .mcp.json configs above). Credentials are
-    // resolved at runtime, never written here.
-    const bridgeConfigPath = path.join(cwd, ".bridge", "config");
-    let bridgeConfigExists = false;
-    try {
-        await stat(bridgeConfigPath);
-        bridgeConfigExists = true;
-    }
-    catch { }
-    if (bridgeConfigExists) {
-        console.log(`\n.bridge/config: skipped — already exists`);
-    }
-    else {
-        await mkdir(path.dirname(bridgeConfigPath), { recursive: true });
-        await writeFile(bridgeConfigPath, buildBridgeConfigManifest(chooseScaffoldRepoName(cwd)), "utf-8");
-        console.log(`\n.bridge/config: written`);
-    }
-    console.log("  Credentials are resolved at runtime from BAPI_API_KEY or " +
-        "~/.config/bridge/credentials.json (no secrets are written to .bridge/config).");
-    // ---- Phase 7: Final summary ----
-    if (anyCreatedOrAdded) {
-        console.log("\nSet BAPI_REPO_NAME in your config files. Do NOT put BAPI_API_KEY in the " +
-            "generated MCP config — supply it via the BAPI_API_KEY environment variable, " +
-            "or store it under \"bapi:<repo_name>\" in ~/.config/bridge/credentials.json. " +
-            "Get your values from the Bridge API setup UI at https://bridgegpt-api.com");
-    }
-}
-// ---------------------------------------------------------------------------
 // CLI subcommand dispatch
 // ---------------------------------------------------------------------------
 //
@@ -1396,37 +952,6 @@ async function runInitCli(cwd) {
         return 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 oldVersion = VERSION;
-        console.log("Upgrading @bridge_gpt/mcp-server to latest...\n");
-        execSync("npm i @bridge_gpt/mcp-server@latest", { stdio: "inherit" });
-        // Read the newly installed version from node_modules
-        const require = createRequire(cwd + "/");
-        const newPkgPath = require.resolve("@bridge_gpt/mcp-server/package.json");
-        const newPkg = JSON.parse(await readFile(newPkgPath, "utf-8"));
-        const newVersion = newPkg.version;
-        console.log(`\n@bridge_gpt/mcp-server: ${oldVersion} -> ${newVersion}`);
-        if (oldVersion === newVersion) {
-            console.log("Already up-to-date.");
-        }
-        console.log("\nRefreshing scaffolded artifacts...\n");
-        await runInit(cwd);
-        console.log("\nUpgrade complete.");
-        return 0;
-    }
-    catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
-        console.error(`Bridge API --upgrade failed: ${msg}`);
-        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.
@@ -1486,12 +1011,32 @@ async function dispatchCliSubcommand(argv) {
     if (argv[0] === "conductor") {
         return runConductorCli(argv.slice(1));
     }
+    // The `install-bridge` subcommand (BAPI-429) is the one-command project
+    // bootstrap: it scaffolds (`runInit`), writes the per-host MCP config with real
+    // values, verifies connectivity, persists the routing credential, then spawns a
+    // fresh agent session for the agentic remainder. Like the others it is a
+    // positional subcommand routed before the --init / --upgrade flag guards and
+    // well before MCP server construction so it never falls through to startup.
+    if (argv[0] === "install-bridge") {
+        return runInstallBridgeCli(argv.slice(1));
+    }
+    // The `upgrade` subcommand (BAPI-430) is the one-command upgrade path: re-exec
+    // from @latest, reconcile stale layers, rewrite the launcher pin, and reconnect.
+    if (argv[0] === "upgrade") {
+        return runUpgradeCli(argv.slice(1));
+    }
+    // --version exits immediately with the current version string (no server start).
+    if (argv.includes("--version")) {
+        console.log(VERSION);
+        return 0;
+    }
     // --init takes precedence over --upgrade; both are position-independent flags.
     if (argv.includes("--init")) {
         return runInitCli(cwd);
     }
+    // --upgrade fallback passes all args so flags like --dry-run are forwarded.
     if (argv.includes("--upgrade")) {
-        return runUpgradeCli(cwd);
+        return runUpgradeCli(argv);
     }
     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.`);
@@ -1594,6 +1139,23 @@ const registerTool = ((name, config, handler) => {
     return toolHandle;
 });
 // ---------------------------------------------------------------------------
+// Shared Zod schema fragments (BAPI-433 Phase 1)
+// Centralizes common parameter definitions to eliminate redundant describe() prose.
+// The MCP SDK serializes these per-tool, so the savings come from shorter text,
+// not from object reuse in the wire payload.
+// ---------------------------------------------------------------------------
+const commonFields = {
+    ticket_number: z.string(),
+    repo_name: z.string().optional(),
+    save_locally: z.boolean().optional().default(true),
+    wait_for_result: z.boolean().optional().default(false).describe("When true, blocks and polls until ready, returning full content directly. " +
+        "When false (default), returns immediately with confirmation/handle. " +
+        "Use the corresponding get_* tool to retrieve results."),
+    second_opinion: z.string().optional().describe("Provider routing override for THIS request. NOT the standalone second_opinion tool. " +
+        "Takes precedence over provider."),
+    provider: z.string().optional().describe("Use a specific LLM provider (openai, anthropic, gemini) without triggering second-opinion semantics."),
+};
+// ---------------------------------------------------------------------------
 // Conductor event-ledger tools (BAPI-393)
 // ---------------------------------------------------------------------------
 //
@@ -1602,7 +1164,9 @@ const registerTool = ((name, config, handler) => {
 // ~/.config/bridge/events.db and intentionally do NOT route through the Bridge
 // API HTTP helpers. They are registered through the same `registerTool` wrapper
 // as every other tool so they share enable/disable + in-process dispatch.
-registerConductorTools(registerTool);
+if (profileIncludes(BRIDGE_MCP_PROFILE, "conductor")) {
+    registerConductorTools(registerTool);
+}
 registerTool("ping", {
     annotations: {
         readOnlyHint: true,
@@ -1636,7 +1200,8 @@ registerTool("ping", {
             { type: "text", text: JSON.stringify(body, null, 2) },
         ];
         if (typeof body.upgrade_advice === "string" && body.upgrade_advice.length > 0) {
-            content.push({ type: "text", text: body.upgrade_advice });
+            const actionableAdvice = `Update available: running ${body.mcp_version}, latest ${body.latest_mcp_version} — run npx -y @bridge_gpt/mcp-server@latest --upgrade`;
+            content.push({ type: "text", text: actionableAdvice });
         }
         return { content };
     }
@@ -1652,15 +1217,9 @@ registerTool("second_opinion", {
         idempotentHint: false, // each call submits a fresh LLM request
         openWorldHint: true,
     },
-    description: "Get an IMMEDIATE, ad hoc independent critique or pushback on a plan, recommendation, or analysis you ALREADY HAVE in hand, from a different LLM model family. " +
-        "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. " +
-        "This tool does NOT create or retrieve any Bridge artifact: it does not generate or fetch plans, ticket critiques, clarifying questions, architecture docs, deep research, brainstorms, or reimplementation context, and it persists only an internal request-tracking row, no retrievable artifact. It simply returns the other model's reply to your prompt right now. " +
-        "If instead you want a Bridge ARTIFACT (a plan, critique, clarifying questions, architecture doc, reimplementation context, etc.) generated by a different provider, do NOT use this tool — call the matching `request_*` tool and set that tool's own `second_opinion` or `provider` parameter to route its generation to another provider. " +
-        "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.",
+    description: "Use to get an immediate, ad hoc independent critique on a plan or analysis you already have. " +
+        "Returns the responding model's reply text plus the resolved provider. " +
+        "This does NOT create or retrieve a Bridge artifact (use request_* tools for that).",
     inputSchema: {
         prompt: z
             .string()
@@ -2009,9 +1568,7 @@ registerTool("get_ticket", {
         "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()
-            .describe("Jira ticket key in PROJECT-NUMBER format (e.g. PROJ-123)"),
+        ticket_number: commonFields.ticket_number,
     },
 }, async ({ ticket_number }) => {
     const url = buildGetUrl(`/tickets/${encodeURIComponent(ticket_number)}`, { repo_name: REPO_NAME });
@@ -2038,9 +1595,7 @@ registerTool("get_ticket_model_tier", {
         "the tier->model mapping is owned by the start-tickets CLI. A null tier (source=\"fallback\") means the " +
         "model could not be resolved and callers should use the agent's default model.",
     inputSchema: {
-        ticket_number: z
-            .string()
-            .describe("Jira ticket key in PROJECT-NUMBER format (e.g. PROJ-123)"),
+        ticket_number: commonFields.ticket_number,
     },
 }, async ({ ticket_number }) => {
     const url = buildGetUrl(`/tickets/${encodeURIComponent(ticket_number)}/model-tier`, { repo_name: REPO_NAME });
@@ -2061,9 +1616,7 @@ registerTool("get_comments", {
         "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)"),
+        ticket_number: commonFields.ticket_number,
     },
 }, async ({ ticket_number }) => {
     const url = buildGetUrl(`/tickets/${encodeURIComponent(ticket_number)}/comments`, { repo_name: REPO_NAME });
@@ -2144,15 +1697,8 @@ registerTool("get_plan", {
         "Returns a 404 / not-found response when no plan is ready yet — that means generation has not run, not that this tool failed. " +
         "Tip: call get_clarifying_questions for the same ticket to get the full context for implementation.",
     inputSchema: {
-        ticket_number: z
-            .string()
-            .describe("Jira ticket key in PROJECT-NUMBER format (e.g. PROJ-123, BAPI-42)"),
-        save_locally: z
-            .boolean()
-            .optional()
-            .default(true)
-            .describe("Whether to save the retrieved plan to a local file. Saves to BAPI_DOCS_DIR/plans/{ticket}-plan.md. " +
-            "Defaults to true. Set to false to skip saving."),
+        ticket_number: commonFields.ticket_number,
+        save_locally: commonFields.save_locally,
     },
 }, async (args) => {
     return getTicketArtifact("plan", args);
@@ -2170,15 +1716,8 @@ registerTool("get_architecture", {
         "The plan includes high-level architectural decisions, component design, and integration guidance. " +
         "Returns a 404 / not-found response when no architecture plan is ready yet — that means generation has not run, not that this tool failed.",
     inputSchema: {
-        ticket_number: z
-            .string()
-            .describe("Jira ticket key in PROJECT-NUMBER format (e.g. PROJ-123, BAPI-42)"),
-        save_locally: z
-            .boolean()
-            .optional()
-            .default(true)
-            .describe("Whether to save the architecture plan to a local file in the BAPI_DOCS_DIR/architecture/ directory. " +
-            "Defaults to true. Set to false to skip saving."),
+        ticket_number: commonFields.ticket_number,
+        save_locally: commonFields.save_locally,
     },
 }, async (args) => {
     return getTicketArtifact("architecture", args);
@@ -2196,15 +1735,8 @@ registerTool("get_prd", {
         "The PRD is product/stakeholder-facing: problem framing, goals, success metrics, scope, and product requirements. " +
         "Returns a 404 / not-found response when no PRD is ready yet — that means generation has not run, not that this tool failed.",
     inputSchema: {
-        ticket_number: z
-            .string()
-            .describe("Jira ticket key in PROJECT-NUMBER format (e.g. PROJ-123, BAPI-42)"),
-        save_locally: z
-            .boolean()
-            .optional()
-            .default(true)
-            .describe("Whether to save the PRD to a local file in the BAPI_DOCS_DIR/prd/ directory. " +
-            "Defaults to true. Set to false to skip saving."),
+        ticket_number: commonFields.ticket_number,
+        save_locally: commonFields.save_locally,
     },
 }, async (args) => {
     return getTicketArtifact("prd", args);
@@ -2222,15 +1754,8 @@ registerTool("get_clarifying_questions", {
         "Returns a 404 / not-found response when no questions are ready yet — that means generation has not run, not that this tool failed. " +
         "Tip: call get_plan for the same ticket to get the implementation plan alongside these questions.",
     inputSchema: {
-        ticket_number: z
-            .string()
-            .describe("Jira ticket key in PROJECT-NUMBER format (e.g. PROJ-123, BAPI-42)"),
-        save_locally: z
-            .boolean()
-            .optional()
-            .default(true)
-            .describe("Whether to save the clarifying questions to a local file in the BAPI_DOCS_DIR/clarifying-questions/ directory. " +
-            "Defaults to true. Set to false to skip saving."),
+        ticket_number: commonFields.ticket_number,
+        save_locally: commonFields.save_locally,
     },
 }, async (args) => {
     return getTicketArtifact("clarifying_questions", args);
@@ -2330,9 +1855,7 @@ registerTool("add_comment", {
         "Tip: To generate plans, clarifying questions, or ticket critiques, use the dedicated " +
         "request_plan_generation, request_clarifying_questions, or request_ticket_critique tools.",
     inputSchema: {
-        ticket_number: z
-            .string()
-            .describe("Jira ticket key in PROJECT-NUMBER format (e.g. PROJ-123, BAPI-42)"),
+        ticket_number: commonFields.ticket_number,
         comment: z
             .string()
             .optional()
@@ -2388,9 +1911,7 @@ registerTool("update_ticket_description", {
         "This does NOT create a new ticket. Use create_ticket for that. " +
         "Returns a success message with the ticket number, or an error if the update fails.",
     inputSchema: {
-        ticket_number: z
-            .string()
-            .describe("Jira ticket key in PROJECT-NUMBER format (e.g. PROJ-123)"),
+        ticket_number: commonFields.ticket_number,
         description: z
             .string()
             .optional()
@@ -2431,9 +1952,7 @@ registerTool("upload_attachment", {
         "Note: link_type is text-only; cannot be used with base64 uploads. " +
         "⚠️ SECURITY: Binary bytes cannot be secret-redacted by automated text scrubbers; review sensitive visual content before upload.",
     inputSchema: {
-        ticket_number: z
-            .string()
-            .describe("Jira ticket key in PROJECT-NUMBER format (e.g. PROJ-123, BAPI-42)"),
+        ticket_number: commonFields.ticket_number,
         file_path: z
             .string()
             .optional()
@@ -2502,9 +2021,7 @@ registerTool("list_attachments", {
         "By default, AI-generated attachments are excluded. " +
         "Use this to discover available attachments before downloading.",
     inputSchema: {
-        ticket_number: z
-            .string()
-            .describe("Jira ticket key in PROJECT-NUMBER format (e.g. PROJ-123)"),
+        ticket_number: commonFields.ticket_number,
         include_ai_generated: z
             .boolean()
             .optional()
@@ -2539,9 +2056,7 @@ registerTool("download_attachment", {
         "For binary files, the file is saved to disk and the path is returned. " +
         "Default save location: {BAPI_DOCS_DIR}/attachments/{ticket_number}/{filename}.",
     inputSchema: {
-        ticket_number: z
-            .string()
-            .describe("Jira ticket key in PROJECT-NUMBER format (e.g. PROJ-123)"),
+        ticket_number: commonFields.ticket_number,
         attachment_id: z
             .string()
             .optional()
@@ -2635,35 +2150,11 @@ registerTool("request_plan_generation", {
         "or 403 if the API key is unauthorized. " +
         "Set wait_for_result to true to block until the result is ready (typically 1-5 minutes) instead of returning immediately.",
     inputSchema: {
-        ticket_number: z
-            .string()
-            .describe("Jira ticket key in PROJECT-NUMBER format (e.g. PROJ-123) to generate a plan for"),
-        wait_for_result: z
-            .boolean()
-            .optional()
-            .default(false)
-            .describe("When true, the tool blocks and polls until the plan is ready (typically 1-5 minutes), " +
-            "then returns the full plan content directly. When false (default), returns immediately " +
-            "with a confirmation message — use get_plan later to retrieve results."),
-        save_locally: z
-            .boolean()
-            .optional()
-            .default(true)
-            .describe("When wait_for_result is true, whether to save the plan to a local file in the " +
-            "BAPI_DOCS_DIR/plans/ directory. Defaults to true. Ignored when wait_for_result is false."),
-        second_opinion: z
-            .string()
-            .optional()
-            .describe("Provider routing override for THIS artifact-generation request " +
-            "(e.g. 'anthropic', 'openai', 'gemini'). When set, the artifact is " +
-            "generated by the named provider and, where supported, a cross-provider " +
-            "second-opinion pass is applied to this request only. " +
-            "This is NOT the standalone `second_opinion` tool — it does not return " +
-            "an ad hoc critique; it only changes which provider produces this " +
-            "request's artifact. Takes precedence over `provider` when both are set."),
-        provider: z.string().optional().describe("Pure provider switch — use a specific LLM provider (openai, anthropic, gemini) without " +
-            "triggering second-opinion semantics. If both provider and second_opinion are set, " +
-            "second_opinion takes precedence."),
+        ticket_number: commonFields.ticket_number,
+        wait_for_result: commonFields.wait_for_result,
+        save_locally: commonFields.save_locally,
+        second_opinion: commonFields.second_opinion,
+        provider: commonFields.provider,
     },
 }, async (args) => {
     return requestTicketArtifact("plan", args);
@@ -2683,35 +2174,11 @@ registerTool("request_architecture", {
         "or 403 if the API key is unauthorized. " +
         "Set wait_for_result to true to block until the result is ready (typically 2-4 minutes) instead of returning immediately.",
     inputSchema: {
-        ticket_number: z
-            .string()
-            .describe("Jira ticket key in PROJECT-NUMBER format (e.g. PROJ-123) to generate an architecture plan for"),
-        wait_for_result: z
-            .boolean()
-            .optional()
-            .default(false)
-            .describe("When true, the tool blocks and polls until the architecture plan is ready (typically 2-4 minutes), " +
-            "then returns the full plan content directly. When false (default), returns immediately " +
-            "with a confirmation message — use get_architecture later to retrieve results."),
-        save_locally: z
-            .boolean()
-            .optional()
-            .default(true)
-            .describe("When wait_for_result is true, whether to save the architecture plan to a local file in the " +
-            "BAPI_DOCS_DIR/architecture/ directory. Defaults to true. Only takes effect when wait_for_result is true."),
-        second_opinion: z
-            .string()
-            .optional()
-            .describe("Provider routing override for THIS artifact-generation request " +
-            "(e.g. 'anthropic', 'openai', 'gemini'). When set, the artifact is " +
-            "generated by the named provider and, where supported, a cross-provider " +
-            "second-opinion pass is applied to this request only. " +
-            "This is NOT the standalone `second_opinion` tool — it does not return " +
-            "an ad hoc critique; it only changes which provider produces this " +
-            "request's artifact. Takes precedence over `provider` when both are set."),
-        provider: z.string().optional().describe("Pure provider switch — use a specific LLM provider (openai, anthropic, gemini) without " +
-            "triggering second-opinion semantics. If both provider and second_opinion are set, " +
-            "second_opinion takes precedence."),
+        ticket_number: commonFields.ticket_number,
+        wait_for_result: commonFields.wait_for_result,
+        save_locally: commonFields.save_locally,
+        second_opinion: commonFields.second_opinion,
+        provider: commonFields.provider,
     },
 }, async (args) => {
     return requestTicketArtifact("architecture", args);
@@ -2731,35 +2198,11 @@ registerTool("request_prd", {
         "or 403 if the API key is unauthorized. " +
         "Set wait_for_result to true to block until the result is ready (typically 2-4 minutes) instead of returning immediately.",
     inputSchema: {
-        ticket_number: z
-            .string()
-            .describe("Jira ticket key in PROJECT-NUMBER format (e.g. PROJ-123) to generate a PRD for"),
-        wait_for_result: z
-            .boolean()
-            .optional()
-            .default(false)
-            .describe("When true, the tool blocks and polls until the PRD is ready (typically 2-4 minutes), " +
-            "then returns the full PRD content directly. When false (default), returns immediately " +
-            "with a confirmation message — use get_prd later to retrieve results."),
-        save_locally: z
-            .boolean()
-            .optional()
-            .default(true)
-            .describe("When wait_for_result is true, whether to save the PRD to a local file in the " +
-            "BAPI_DOCS_DIR/prd/ directory. Defaults to true. Only takes effect when wait_for_result is true."),
-        second_opinion: z
-            .string()
-            .optional()
-            .describe("Provider routing override for THIS artifact-generation request " +
-            "(e.g. 'anthropic', 'openai', 'gemini'). When set, the artifact is " +
-            "generated by the named provider and, where supported, a cross-provider " +
-            "second-opinion pass is applied to this request only. " +
-            "This is NOT the standalone `second_opinion` tool — it does not return " +
-            "an ad hoc critique; it only changes which provider produces this " +
-            "request's artifact. Takes precedence over `provider` when both are set."),
-        provider: z.string().optional().describe("Pure provider switch — use a specific LLM provider (openai, anthropic, gemini) without " +
-            "triggering second-opinion semantics. If both provider and second_opinion are set, " +
-            "second_opinion takes precedence."),
+        ticket_number: commonFields.ticket_number,
+        wait_for_result: commonFields.wait_for_result,
+        save_locally: commonFields.save_locally,
+        second_opinion: commonFields.second_opinion,
+        provider: commonFields.provider,
     },
 }, async (args) => {
     return requestTicketArtifact("prd", args);
@@ -2771,35 +2214,17 @@ registerTool("create_doc", {
         idempotentHint: false,
         openWorldHint: true,
     },
-    description: "START (or refresh) async generation of a design document for a Jira ticket, routed by doc_type. " +
-        "Use doc_type 'tdd' for a Technical Design Document (architecture-focused, for engineers), 'fsd' for a " +
-        "Functional Specification Document (product/functional-focused, for PMs, designers, and QA), or 'prd' for a " +
-        "Product Requirements Document (product-requirements-focused: problem, goals, and success metrics). " +
-        "This triggers an asynchronous background job — results are NOT immediate. " +
-        "Processing typically takes 2-4 minutes depending on ticket complexity. " +
-        "The matching get_doc tool retrieves the generated document later (call get_doc with the same ticket_number and doc_type) — unless you set wait_for_result, in which case this call blocks and returns it directly. " +
-        "Returns 202 if the request was accepted, 404 if the ticket does not exist in Jira, or 403 if the API key is unauthorized.",
+    description: "Use to start async generation of a design document (tdd, fsd, or prd) for a Jira ticket. " +
+        "Returns confirmation immediately (or the full document if wait_for_result is true). " +
+        "Use get_doc to retrieve. Generates and persists a retrievable artifact.",
     inputSchema: {
-        ticket_number: z
-            .string()
-            .describe("Jira ticket key in PROJECT-NUMBER format (e.g. PROJ-123) to generate a design document for"),
+        ticket_number: commonFields.ticket_number,
         doc_type: z.enum(["tdd", "fsd", "prd"])
             .describe("Which design document to generate: 'tdd' (Technical Design Document, engineer audience), " +
             "'fsd' (Functional Specification Document, product/functional audience), or " +
             "'prd' (Product Requirements Document, product-requirements focused: problem, goals, success metrics)."),
-        wait_for_result: z
-            .boolean()
-            .optional()
-            .default(false)
-            .describe("When true, the tool blocks and polls until the document is ready (typically 2-4 minutes), " +
-            "then returns the full content directly. When false (default), returns immediately " +
-            "with a confirmation message — use get_doc later to retrieve results."),
-        save_locally: z
-            .boolean()
-            .optional()
-            .default(true)
-            .describe("When wait_for_result is true, whether to save the generated document to a local file under " +
-            "BAPI_DOCS_DIR. Defaults to true. Only takes effect when wait_for_result is true."),
+        wait_for_result: commonFields.wait_for_result,
+        save_locally: commonFields.save_locally,
         second_opinion: z
             .string()
             .optional()
@@ -2830,18 +2255,11 @@ registerTool("get_doc", {
         "Returns the full document as markdown text — present it verbatim without summarizing. " +
         "Returns a 404 / not-found response when no document is ready yet — that means generation has not run, not that this tool failed.",
     inputSchema: {
-        ticket_number: z
-            .string()
-            .describe("Jira ticket key in PROJECT-NUMBER format (e.g. PROJ-123, BAPI-42)"),
+        ticket_number: commonFields.ticket_number,
         doc_type: z.enum(["tdd", "fsd", "prd"])
             .describe("Which design document to retrieve: 'tdd' (Technical Design Document), " +
             "'fsd' (Functional Specification Document), or 'prd' (Product Requirements Document)."),
-        save_locally: z
-            .boolean()
-            .optional()
-            .default(true)
-            .describe("Whether to save the retrieved document to a local file under BAPI_DOCS_DIR. " +
-            "Defaults to true. Set to false to skip saving."),
+        save_locally: commonFields.save_locally,
     },
 }, async (args) => {
     return getTicketArtifact(resolveDesignDocArtifactType(args.doc_type), args);
@@ -2862,35 +2280,11 @@ registerTool("request_clarifying_questions", {
         "or 403 if the API key is unauthorized. " +
         "Set wait_for_result to true to block until the result is ready (typically 1-5 minutes) instead of returning immediately.",
     inputSchema: {
-        ticket_number: z
-            .string()
-            .describe("Jira ticket key in PROJECT-NUMBER format (e.g. PROJ-123) to generate clarifying questions for"),
-        wait_for_result: z
-            .boolean()
-            .optional()
-            .default(false)
-            .describe("When true, the tool blocks and polls until the clarifying questions are ready (typically 1-5 minutes), " +
-            "then returns the full content directly. When false (default), returns immediately " +
-            "with a confirmation message — use get_clarifying_questions later to retrieve results."),
-        save_locally: z
-            .boolean()
-            .optional()
-            .default(true)
-            .describe("When wait_for_result is true, whether to save the clarifying questions to a local file in the " +
-            "BAPI_DOCS_DIR/clarifying-questions/ directory. Defaults to true. Ignored when wait_for_result is false."),
-        second_opinion: z
-            .string()
-            .optional()
-            .describe("Provider routing override for THIS artifact-generation request " +
-            "(e.g. 'anthropic', 'openai', 'gemini'). When set, the artifact is " +
-            "generated by the named provider and, where supported, a cross-provider " +
-            "second-opinion pass is applied to this request only. " +
-            "This is NOT the standalone `second_opinion` tool — it does not return " +
-            "an ad hoc critique; it only changes which provider produces this " +
-            "request's artifact. Takes precedence over `provider` when both are set."),
-        provider: z.string().optional().describe("Pure provider switch — use a specific LLM provider (openai, anthropic, gemini) without " +
-            "triggering second-opinion semantics. If both provider and second_opinion are set, " +
-            "second_opinion takes precedence."),
+        ticket_number: commonFields.ticket_number,
+        wait_for_result: commonFields.wait_for_result,
+        save_locally: commonFields.save_locally,
+        second_opinion: commonFields.second_opinion,
+        provider: commonFields.provider,
     },
 }, async (args) => {
     return requestTicketArtifact("clarifying_questions", args);
@@ -2911,15 +2305,8 @@ registerTool("get_ticket_critique", {
         "Standards Deviations, and Suggested Improvements. " +
         "Returns a 404 / not-found response when no critique is ready yet — that means generation has not run, not that this tool failed.",
     inputSchema: {
-        ticket_number: z
-            .string()
-            .describe("Jira ticket key in PROJECT-NUMBER format (e.g. PROJ-123, BAPI-42)"),
-        save_locally: z
-            .boolean()
-            .optional()
-            .default(true)
-            .describe("Whether to save the critique to a local file in the BAPI_DOCS_DIR/ticket-critiques/ directory. " +
-            "Defaults to true. Set to false to skip saving."),
+        ticket_number: commonFields.ticket_number,
+        save_locally: commonFields.save_locally,
     },
 }, async (args) => {
     return getTicketArtifact("ticket_critique", args);
@@ -2939,35 +2326,11 @@ registerTool("request_ticket_critique", {
         "or 403 if the API key is unauthorized. " +
         "Set wait_for_result to true to block until the result is ready (typically 1-5 minutes) instead of returning immediately.",
     inputSchema: {
-        ticket_number: z
-            .string()
-            .describe("Jira ticket key in PROJECT-NUMBER format (e.g. PROJ-123) to generate a ticket critique for"),
-        wait_for_result: z
-            .boolean()
-            .optional()
-            .default(false)
-            .describe("When true, the tool blocks and polls until the ticket critique is ready (typically 1-5 minutes), " +
-            "then returns the full content directly. When false (default), returns immediately " +
-            "with a confirmation message — use get_ticket_critique later to retrieve results."),
-        save_locally: z
-            .boolean()
-            .optional()
-            .default(true)
-            .describe("When wait_for_result is true, whether to save the ticket critique to a local file in the " +
-            "BAPI_DOCS_DIR/ticket-critiques/ directory. Defaults to true. Ignored when wait_for_result is false."),
-        second_opinion: z
-            .string()
-            .optional()
-            .describe("Provider routing override for THIS artifact-generation request " +
-            "(e.g. 'anthropic', 'openai', 'gemini'). When set, the artifact is " +
-            "generated by the named provider and, where supported, a cross-provider " +
-            "second-opinion pass is applied to this request only. " +
-            "This is NOT the standalone `second_opinion` tool — it does not return " +
-            "an ad hoc critique; it only changes which provider produces this " +
-            "request's artifact. Takes precedence over `provider` when both are set."),
-        provider: z.string().optional().describe("Pure provider switch — use a specific LLM provider (openai, anthropic, gemini) without " +
-            "triggering second-opinion semantics. If both provider and second_opinion are set, " +
-            "second_opinion takes precedence."),
+        ticket_number: commonFields.ticket_number,
+        wait_for_result: commonFields.wait_for_result,
+        save_locally: commonFields.save_locally,
+        second_opinion: commonFields.second_opinion,
+        provider: commonFields.provider,
     },
 }, async (args) => {
     return requestTicketArtifact("ticket_critique", args);
@@ -2990,35 +2353,11 @@ registerTool("request_ticket_review", {
         "or 403 if the API key is unauthorized. " +
         "Set wait_for_result to true to block until both documents are ready and receive them concatenated.",
     inputSchema: {
-        ticket_number: z
-            .string()
-            .describe("Jira ticket key in PROJECT-NUMBER format (e.g. PROJ-123) to generate a combined review for"),
-        wait_for_result: z
-            .boolean()
-            .optional()
-            .default(false)
-            .describe("When true, the tool blocks and polls until both documents are ready (typically 2-6 minutes), " +
-            "then returns the concatenated markdown directly. When false (default), returns immediately " +
-            "with a confirmation message — use get_clarifying_questions and get_ticket_critique later to retrieve results."),
-        save_locally: z
-            .boolean()
-            .optional()
-            .default(true)
-            .describe("When wait_for_result is true, whether to save each generated document to its canonical local path under " +
-            "BAPI_DOCS_DIR (clarifying-questions/ or ticket-critiques/). Defaults to true. Ignored when wait_for_result is false."),
-        second_opinion: z
-            .string()
-            .optional()
-            .describe("Provider routing override for THIS artifact-generation request " +
-            "(e.g. 'anthropic', 'openai', 'gemini'). When set, the artifact is " +
-            "generated by the named provider and, where supported, a cross-provider " +
-            "second-opinion pass is applied to this request only. " +
-            "This is NOT the standalone `second_opinion` tool — it does not return " +
-            "an ad hoc critique; it only changes which provider produces this " +
-            "request's artifact. Takes precedence over `provider` when both are set."),
-        provider: z.string().optional().describe("Pure provider switch — use a specific LLM provider (openai, anthropic, gemini) without " +
-            "triggering second-opinion semantics. If both provider and second_opinion are set, " +
-            "second_opinion takes precedence."),
+        ticket_number: commonFields.ticket_number,
+        wait_for_result: commonFields.wait_for_result,
+        save_locally: commonFields.save_locally,
+        second_opinion: commonFields.second_opinion,
+        provider: commonFields.provider,
     },
 }, async (args) => {
     return requestTicketReview(args);
@@ -3039,34 +2378,11 @@ registerTool("request_reimplement_context", {
         "The matching get_reimplement_context tool retrieves the assembled context later (call get_reimplement_context with the same ticket_number) — unless you set wait_for_result, in which case this call blocks and returns it directly. " +
         "Set wait_for_result to true to block until the context is ready instead of returning immediately.",
     inputSchema: {
-        ticket_number: z
-            .string()
-            .describe("Jira ticket key in PROJECT-NUMBER format (e.g. PROJ-123)"),
-        wait_for_result: z
-            .boolean()
-            .optional()
-            .default(false)
-            .describe("When true, POST then poll the GET endpoint until the context is ready. " +
-            "When false (default), return immediately with a confirmation — use get_reimplement_context later."),
-        save_locally: z
-            .boolean()
-            .optional()
-            .default(true)
-            .describe("When wait_for_result is true, save the context markdown to " +
-            "BAPI_DOCS_DIR/reimplementations/{ticket_number}-context.md. Defaults to true."),
-        second_opinion: z
-            .string()
-            .optional()
-            .describe("Provider routing override for THIS artifact-generation request " +
-            "(e.g. 'anthropic', 'openai', 'gemini'). When set, the artifact is " +
-            "generated by the named provider and, where supported, a cross-provider " +
-            "second-opinion pass is applied to this request only. " +
-            "This is NOT the standalone `second_opinion` tool — it does not return " +
-            "an ad hoc critique; it only changes which provider produces this " +
-            "request's artifact. Takes precedence over `provider` when both are set."),
-        provider: z.string().optional().describe("Pure provider switch — use a specific LLM provider (openai, anthropic, gemini) without " +
-            "triggering second-opinion semantics. If both provider and second_opinion are set, " +
-            "second_opinion takes precedence."),
+        ticket_number: commonFields.ticket_number,
+        wait_for_result: commonFields.wait_for_result,
+        save_locally: commonFields.save_locally,
+        second_opinion: commonFields.second_opinion,
+        provider: commonFields.provider,
     },
 }, async (args) => {
     return requestTicketArtifact("reimplement_context", args);
@@ -3084,14 +2400,8 @@ registerTool("get_reimplement_context", {
         "the original ticket description, and the existing implementation plan. " +
         "Returns a 404 / not-found response when processing is not yet complete — that means processing has not finished, not that this tool failed.",
     inputSchema: {
-        ticket_number: z
-            .string()
-            .describe("Jira ticket key in PROJECT-NUMBER format (e.g. PROJ-123)"),
-        save_locally: z
-            .boolean()
-            .optional()
-            .default(true)
-            .describe("Save the context to BAPI_DOCS_DIR/reimplementations/{ticket_number}-context.md. Defaults to true."),
+        ticket_number: commonFields.ticket_number,
+        save_locally: commonFields.save_locally,
     },
 }, async (args) => {
     return getTicketArtifact("reimplement_context", args);
@@ -3113,7 +2423,7 @@ registerTool("track_ticket", {
         "For Jira mutations use a different tool instead: `update_ticket_description` to replace the Jira description, `add_comment` to post a Jira comment, and `update_jira_status` to move the Jira workflow status. " +
         "The repo_name is automatically injected from the configured environment.",
     inputSchema: {
-        ticket_number: z.string().describe("Jira ticket key in PROJECT-NUMBER format (e.g. PROJ-123)"),
+        ticket_number: commonFields.ticket_number,
         description: z.string().optional().describe("Ticket description text. Optional — used to store a local copy of the description for reference."),
     },
 }, async ({ ticket_number, description }) => {
@@ -3141,7 +2451,7 @@ registerTool("update_ticket_state", {
         "Returns 400 if any field name is invalid. " +
         "The repo_name is automatically injected from the configured environment.",
     inputSchema: {
-        ticket_number: z.string().describe("Jira ticket key in PROJECT-NUMBER format (e.g. PROJ-123)"),
+        ticket_number: commonFields.ticket_number,
         fields: z.array(z.string()).describe("List of state field names to set to the current UTC timestamp. Valid values: 'critique_called', 'critique_answered', 'clarify_called', 'clarify_answered', 'plan_generated', 'implemented', 'reimplement_called'"),
     },
 }, async ({ ticket_number, fields }) => {
@@ -3167,7 +2477,7 @@ registerTool("get_ticket_state", {
         "The ticket must be tracked via track_ticket first, or a 404 is returned. " +
         "The repo_name is automatically injected from the configured environment.",
     inputSchema: {
-        ticket_number: z.string().describe("Jira ticket key in PROJECT-NUMBER format (e.g. PROJ-123)"),
+        ticket_number: commonFields.ticket_number,
     },
 }, async ({ ticket_number }) => {
     const url = buildGetUrl(`/ticket/${encodeURIComponent(ticket_number)}/state`, { repo_name: REPO_NAME });
@@ -3189,7 +2499,7 @@ registerTool("get_jira_transitions", {
         "Use this to discover what status changes are possible for a given ticket. " +
         "The repo_name is automatically injected from the configured environment.",
     inputSchema: {
-        ticket_number: z.string().describe("Jira ticket key in PROJECT-NUMBER format (e.g. PROJ-123)"),
+        ticket_number: commonFields.ticket_number,
     },
 }, async ({ ticket_number }) => {
     const url = buildGetUrl(`/tickets/${encodeURIComponent(ticket_number)}/jira-transitions`, { repo_name: REPO_NAME });
@@ -3212,7 +2522,7 @@ registerTool("update_jira_status", {
         "Returns the from/to status on success, or an error listing available transitions if no match is found. " +
         "The repo_name is automatically injected from the configured environment.",
     inputSchema: {
-        ticket_number: z.string().describe("Jira ticket key in PROJECT-NUMBER format (e.g. PROJ-123)"),
+        ticket_number: commonFields.ticket_number,
         target_status: z.string().optional().describe('Target status name to transition to (case-insensitive match). Pass "auto" to resolve the target status server-side via LLM agent.'),
         transition_id: z.string().optional().describe("Specific transition ID to execute (takes precedence over target_status)"),
     },
@@ -3245,7 +2555,7 @@ registerTool("resolve_target_status", {
         "Requires a ticket_number to fetch available transitions from Jira. " +
         "The repo_name is automatically injected from the configured environment.",
     inputSchema: {
-        ticket_number: z.string().describe("Jira ticket key to fetch available transitions from (e.g. PROJ-123)"),
+        ticket_number: commonFields.ticket_number,
         force_rerun: z.boolean().optional().describe("Set to true to bypass the cache and re-resolve the target status via LLM"),
     },
 }, async ({ ticket_number, force_rerun }) => {
@@ -3534,7 +2844,7 @@ registerTool("get_install_manifest", {
         "snapshot_token. Pass that exact snapshot_token to apply_install_manifest. " +
         "Prefer this over many individual get_config_field reads during install bootstrap.",
     inputSchema: {
-        save_locally: z.boolean().optional().default(true).describe("When true (default), also save the full JSON manifest under BAPI_DOCS_DIR/install/."),
+        save_locally: commonFields.save_locally,
     },
 }, async ({ save_locally }) => {
     const url = buildGetUrl("/config/install-manifest", { repo_name: REPO_NAME });
@@ -3733,24 +3043,9 @@ registerTool("request_deep_research", {
         idempotentHint: false,
         openWorldHint: true,
     },
-    description: "START async deep research on a technical topic using AI-powered web search. " +
-        "Returns a task_id for tracking the research progress; the matching get_deep_research tool retrieves the finished report later (unless you set wait_for_result). " +
-        "\n\n" +
-        "WHEN TO USE: Use this tool when you need to investigate unfamiliar technologies, " +
-        "gather implementation guidance across multiple sources, research best practices for a complex topic, " +
-        "or when the depth of information needed exceeds what a single web search can provide. " +
-        "Example: 'What are the best practices for implementing WebSocket connection pooling in Python asyncio, " +
-        "including error handling, reconnection strategies, and load balancing across multiple servers?' " +
-        "\n\n" +
-        "WHEN NOT TO USE: Do NOT use this for quick factual lookups, single-question searches, " +
-        "or anything a standard web search could answer in seconds. " +
-        "Bad example: 'websocket python' — use a web search instead. " +
-        "\n\n" +
-        "BEHAVIOR: By default, returns immediately with a task_id. Use get_deep_research to retrieve the result " +
-        "once processing completes (typically 2-10 minutes). " +
-        "Set wait_for_result to true to block until the report is ready (up to 15 minutes). " +
-        "On failure, do not retry automatically — the underlying issue (provider outage, rate limit) " +
-        "is unlikely to resolve immediately. Fall back to standard web searches to gather the information incrementally.",
+    description: "Use to start async deep research on a technical topic using AI-powered web search. " +
+        "Returns a task_id immediately (or the full report if wait_for_result is true). " +
+        "Use get_deep_research to retrieve. Generates and persists a retrievable artifact.",
     inputSchema: {
         query: z.string().describe("The research query. Be specific and detailed about what you need to learn. " +
             "Good: 'What are the tradeoffs between Redis, Memcached, and DynamoDB DAX for caching in a Python FastAPI " +
@@ -3759,13 +3054,9 @@ registerTool("request_deep_research", {
         context: z.string().optional().describe("Optional context to focus the research scope. Describe your current task, tech stack, and constraints. " +
             "Example: 'I am building a FastAPI application that uses PostgreSQL and needs to implement real-time " +
             "notifications. Focus on Python-specific solutions compatible with async frameworks.'"),
-        ticket_number: z.string().optional().describe("Optional Jira ticket key (e.g. PROJ-123) to associate this research with a specific ticket. " +
-            "Helps trace research results back to the ticket that prompted the investigation."),
-        wait_for_result: z.boolean().optional().default(false).describe("When true, blocks and polls until the research is ready (up to 15 minutes), " +
-            "then returns the full report directly. When false (default), returns immediately " +
-            "with a task_id — use get_deep_research later to retrieve results."),
-        save_locally: z.boolean().optional().default(true).describe("Whether to save the research report to the BAPI_DOCS_DIR/deep-research/ directory. " +
-            "Defaults to true. When wait_for_result is false, saving happens when you call get_deep_research instead."),
+        ticket_number: commonFields.ticket_number.optional(),
+        wait_for_result: commonFields.wait_for_result,
+        save_locally: commonFields.save_locally,
     },
 }, async ({ query, context, ticket_number, wait_for_result, save_locally }) => {
     // 1. Submit the deep research request
@@ -3869,7 +3160,7 @@ registerTool("get_deep_research", {
         task_id: z.number().describe("The task ID returned by request_deep_research."),
         query_slug: z.string().optional().describe("Optional slug derived from the original query, used for the saved filename. " +
             "If omitted, the file is saved as 'research-{task_id}.md'."),
-        save_locally: z.boolean().optional().default(true).describe("Whether to save the research report to the BAPI_DOCS_DIR/deep-research/ directory. Defaults to true."),
+        save_locally: commonFields.save_locally,
     },
 }, async ({ task_id, query_slug, save_locally }) => {
     // 1. Check status
@@ -3988,39 +3279,20 @@ registerTool("request_brainstorm", {
         idempotentHint: false,
         openWorldHint: true,
     },
-    description: "START an async brainstorm that fans out the task to two opinion-provider LLMs " +
-        "(default: OpenAI + Gemini) and returns each provider's opinion directly (no synthesizer pass). " +
-        "Returns a brainstorm_id; the matching get_brainstorm tool retrieves the finished result later (unless you set wait_for_result). " +
-        "\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 with a semantic " +
-        "filename derived from task_description: " +
-        "BAPI_DOCS_DIR/brainstorm/{slugified-task-description}-{short_brainstorm_id}-{provider}.md. " +
-        "(If task_description is empty or slugifies to nothing, it falls back to {brainstorm_id}-{provider}.md.) " +
-        "\n\n" +
-        "MODES: Set mode to pick the brainstorm style. 'technical' (default) runs the implementation/" +
-        "architecture brainstorm. 'design' runs web-page/UI design ideation focused on visual appeal and " +
-        "conversion. 'discovery' generates stakeholder discovery questions for early/vague tasks, grouped " +
-        "into 'Technical Discovery Questions' and 'Business / Stakeholder Discovery Questions' and tagged " +
-        "[HUMAN], [CODE], or [TICKET]; discovery needs no extra configuration. " +
-        "The legacy boolean design=true still works and maps to mode='design'; prefer the explicit mode " +
-        "selector for new callers.",
+    description: "Use to start an async brainstorm that fans out a task to opinion-provider LLMs. " +
+        "Returns a brainstorm_id immediately (or the full result envelope if wait_for_result is true). " +
+        "Use get_brainstorm to retrieve. Generates and persists a retrievable artifact.",
     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."),
+        repo_name: commonFields.repo_name,
+        ticket_number: commonFields.ticket_number.optional(),
         providers: z.array(z.string()).optional().describe("Opinion-provider LLMs. Defaults to ['openai', 'gemini']. " +
             "A single-provider request runs one opinion provider and returns that " +
             "provider's markdown directly."),
         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. Request-time saves use semantic filenames derived from " +
-            "task_description (slugified) plus a short brainstorm-id segment."),
+        wait_for_result: commonFields.wait_for_result,
+        save_locally: commonFields.save_locally,
         prior_brainstorm_id: z.string().optional().describe("Optional brainstorm_id from an earlier brainstorm to refine. " +
             "When provided, the prior brainstorm's completed opinion-provider " +
             "markdowns are concatenated and supplied as prior context."),
@@ -4115,21 +3387,14 @@ registerTool("get_brainstorm", {
         idempotentHint: true,
         openWorldHint: true,
     },
-    description: "RETRIEVE the result envelope for a previously submitted brainstorm by brainstorm_id. This tool only fetches an existing/in-progress result — it does NOT start or trigger a new brainstorm. " +
-        "If you have not submitted a brainstorm yet (or you need a new one), call `request_brainstorm` first; it starts the async brainstorm and returns the brainstorm_id this `get_brainstorm` tool retrieves by. " +
-        "Returns opinion-provider rows only, including error_kind for every row; a not-found / still-processing response means the brainstorm has not completed, not that this tool failed. " +
-        "When save_locally=true (default), writes each provider's markdown to " +
-        "BAPI_DOCS_DIR/brainstorm/{brainstorm_id}-{provider}.md. " +
-        "Retrieval uses this UUID-only filename (not the semantic task-description name that " +
-        "request_brainstorm uses) because the original task description is not available in the " +
-        "result envelope on retrieval. " +
-        "DB-only retrieval — never falls back to Jira attachments.",
+    description: "Use to retrieve the result envelope for a previously submitted brainstorm by brainstorm_id. " +
+        "Returns opinion-provider rows only (including error_kind for each row). " +
+        "Does NOT start a new brainstorm — use request_brainstorm first if none exists. " +
+        "Returns not-found when still processing.",
     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/. " +
-            "Retrieval-time saves intentionally use the UUID-only fallback filename " +
-            "({brainstorm_id}-{provider}.md), not a task-description-derived semantic name."),
+        repo_name: commonFields.repo_name,
+        save_locally: commonFields.save_locally,
     },
 }, async ({ brainstorm_id, repo_name, save_locally }) => {
     const effectiveRepo = repo_name && repo_name.length > 0 ? repo_name : REPO_NAME;
@@ -4269,7 +3534,7 @@ const pollCiChecksTool = registerTool("poll_ci_checks", {
             !("error" in parsed) &&
             (Array.isArray(parsed.checks) || typeof parsed.all_complete === "boolean");
         if (looksLikePollStatus) {
-            void observePrCiFromPollResponse(commit_ref, parsed).catch(() => { });
+            void observePrCiFromPollResponse(commit_ref, parsed, { resolveRunId: resolveDispatchRunIdForBinding }).catch(() => { });
         }
     }
     catch {
@@ -4334,28 +3599,54 @@ registerTool("get_docs_dir", {
 }, async () => {
     return { content: [{ type: "text", text: await getDocsDir() }] };
 });
-registerTool("list_pipelines", {
-    annotations: {
-        readOnlyHint: true,
-        destructiveHint: false,
-        idempotentHint: true,
-        openWorldHint: false,
-    },
-    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: {},
-}, async () => {
+// ---------------------------------------------------------------------------
+// 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.
+async function buildPipelineOrchestratorDeps() {
+    await ensureCustomPipelinesLoaded();
+    return {
+        baseUrl: BASE_URL,
+        apiKey: await getResolvedApiKey(),
+        repoName: REPO_NAME,
+        docsDir: await getDocsDir(),
+        pipelines: PIPELINES,
+        instructions: INSTRUCTIONS,
+        toolHandlers: TOOL_HANDLERS,
+        includeUpgradeAdviceSurfacing: UPGRADE_ADVICE_SURFACING_ENABLED,
+    };
+}
+// BAPI-326: dependency injection for the full-automation chain orchestrator.
+// Same shape as the pipeline deps plus the bundled chain-recipe registry. The
+// chain orchestrator never imports index.ts; everything flows through here.
+async function buildChainOrchestratorDeps() {
     await ensureCustomPipelinesLoaded();
-    const list = Object.entries(PIPELINES).map(([key, pipeline]) => ({
-        name: key,
-        description: pipeline.description ?? "",
-        variables: (pipeline.variables ?? []).filter((v) => v !== "docs_dir" && v !== "idea_hash"),
-        source: userPipelineKeys.has(key) ? "user" : "bundled",
-    }));
     return {
-        content: [{ type: "text", text: JSON.stringify(list, null, 2) }],
+        baseUrl: BASE_URL,
+        apiKey: await getResolvedApiKey(),
+        repoName: REPO_NAME,
+        docsDir: await getDocsDir(),
+        pipelines: PIPELINES,
+        chainRecipes: CHAIN_RECIPES,
+        instructions: INSTRUCTIONS,
+        toolHandlers: TOOL_HANDLERS,
+        includeUpgradeAdviceSurfacing: UPGRADE_ADVICE_SURFACING_ENABLED,
     };
-});
+}
+// get_pipeline_recipe is the entry point for every recipe-driven slash command
+// (/review-ticket, /implement-ticket, /idea-to-ticket, /plan-epic,
+// /learn-repository): each calls it as its first/only direct MCP call and then
+// follows the returned agent_instructions (which use non-gated core tools). It
+// must therefore be available in the default "core" profile, so it is registered
+// unconditionally here — OUTSIDE the pipeline-authoring gate below. The remaining
+// 5 pipeline-authoring/admin tools stay gated (BAPI-434 Phase 2a token savings).
 registerTool("get_pipeline_recipe", {
     annotations: {
         readOnlyHint: true,
@@ -4451,179 +3742,167 @@ 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.
-async function buildPipelineOrchestratorDeps() {
-    await ensureCustomPipelinesLoaded();
-    return {
-        baseUrl: BASE_URL,
-        apiKey: await getResolvedApiKey(),
-        repoName: REPO_NAME,
-        docsDir: await getDocsDir(),
-        pipelines: PIPELINES,
-        instructions: INSTRUCTIONS,
-        toolHandlers: TOOL_HANDLERS,
-        includeUpgradeAdviceSurfacing: UPGRADE_ADVICE_SURFACING_ENABLED,
-    };
-}
-// BAPI-326: dependency injection for the full-automation chain orchestrator.
-// Same shape as the pipeline deps plus the bundled chain-recipe registry. The
-// chain orchestrator never imports index.ts; everything flows through here.
-async function buildChainOrchestratorDeps() {
-    await ensureCustomPipelinesLoaded();
-    return {
-        baseUrl: BASE_URL,
-        apiKey: await getResolvedApiKey(),
-        repoName: REPO_NAME,
-        docsDir: await getDocsDir(),
-        pipelines: PIPELINES,
-        chainRecipes: CHAIN_RECIPES,
-        instructions: INSTRUCTIONS,
-        toolHandlers: TOOL_HANDLERS,
-        includeUpgradeAdviceSurfacing: UPGRADE_ADVICE_SURFACING_ENABLED,
-    };
-}
-registerTool("run_pipeline", {
-    annotations: {
-        readOnlyHint: false,
-        destructiveHint: false,
-        idempotentHint: false,
-        openWorldHint: true,
-    },
-    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" +
-        "Call list_pipelines for the current resolved catalog of available pipeline " +
-        "names (bundled plus any custom user pipelines).",
-    inputSchema: {
-        pipeline: z
-            .string()
-            .describe("Pipeline name (e.g. 'review-ticket', 'implement-ticket')"),
-        variables: z
-            .record(z.string(), 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(await buildPipelineOrchestratorDeps(), input);
-    return {
-        content: [
-            { type: "text", text: JSON.stringify(result, null, 2) },
-        ],
-    };
-});
-registerTool("resume_pipeline", {
-    annotations: {
-        readOnlyHint: false,
-        destructiveHint: false,
-        idempotentHint: false,
-        openWorldHint: true,
-    },
-    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(await buildPipelineOrchestratorDeps(), input);
-    return {
-        content: [
-            { type: "text", text: JSON.stringify(result, null, 2) },
-        ],
-    };
-});
-registerTool("list_pipeline_runs", {
-    annotations: {
-        readOnlyHint: true,
-        destructiveHint: false,
-        idempotentHint: true,
-        openWorldHint: true,
-    },
-    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(await buildPipelineOrchestratorDeps(), input);
-    return {
-        content: [
-            { type: "text", text: JSON.stringify(result, null, 2) },
-        ],
-    };
-});
-registerTool("delete_pipeline_run", {
-    annotations: {
-        readOnlyHint: false,
-        destructiveHint: true,
-        idempotentHint: true,
-        openWorldHint: true,
-    },
-    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(await buildPipelineOrchestratorDeps(), input);
-    return {
-        content: [
-            { type: "text", text: JSON.stringify(result, null, 2) },
-        ],
-    };
-});
+// BAPI-434 Phase 2a: the remaining pipeline-authoring/admin tools are excluded
+// from the default "core" profile. These 5 tools are registered only when the
+// active profile is "pipeline-authoring" or "full". (get_pipeline_recipe is
+// intentionally registered above, in core, because the recipe-driven slash
+// commands depend on it.)
+if (profileIncludes(BRIDGE_MCP_PROFILE, "pipeline-authoring")) {
+    registerTool("list_pipelines", {
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+        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: {},
+    }, async () => {
+        await ensureCustomPipelinesLoaded();
+        const list = Object.entries(PIPELINES).map(([key, pipeline]) => ({
+            name: key,
+            description: pipeline.description ?? "",
+            variables: (pipeline.variables ?? []).filter((v) => v !== "docs_dir" && v !== "idea_hash"),
+            source: userPipelineKeys.has(key) ? "user" : "bundled",
+        }));
+        return {
+            content: [{ type: "text", text: JSON.stringify(list, null, 2) }],
+        };
+    });
+    registerTool("run_pipeline", {
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
+        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" +
+            "Call list_pipelines for the current resolved catalog of available pipeline " +
+            "names (bundled plus any custom user pipelines).",
+        inputSchema: {
+            pipeline: z
+                .string()
+                .describe("Pipeline name (e.g. 'review-ticket', 'implement-ticket')"),
+            variables: z
+                .record(z.string(), 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(await buildPipelineOrchestratorDeps(), input);
+        return {
+            content: [
+                { type: "text", text: JSON.stringify(result, null, 2) },
+            ],
+        };
+    });
+    registerTool("resume_pipeline", {
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
+        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(await buildPipelineOrchestratorDeps(), input);
+        return {
+            content: [
+                { type: "text", text: JSON.stringify(result, null, 2) },
+            ],
+        };
+    });
+    registerTool("list_pipeline_runs", {
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+        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(await buildPipelineOrchestratorDeps(), input);
+        return {
+            content: [
+                { type: "text", text: JSON.stringify(result, null, 2) },
+            ],
+        };
+    });
+    registerTool("delete_pipeline_run", {
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+        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(await buildPipelineOrchestratorDeps(), input);
+        return {
+            content: [
+                { type: "text", text: JSON.stringify(result, null, 2) },
+            ],
+        };
+    });
+} // end if (profileIncludes(BRIDGE_MCP_PROFILE, "pipeline-authoring"))
 // ---------------------------------------------------------------------------
 // Full Automation Chain Tools (BAPI-326)
 // ---------------------------------------------------------------------------
@@ -4830,17 +4109,8 @@ registerTool("generate_decision_page", {
         idempotentHint: true,
         openWorldHint: true,
     },
-    description: "Generate a local, reusable, review-shaped HTML decision page for capturing user decisions. " +
-        "Renders recommendation-driven decision cards with per-option consequence lines, optional " +
-        "original-question and closed-by-default codebase-evidence display, and an optional confirmed-" +
-        "improvements list. Presentation labels (title, intro, section/improvements headings) are " +
-        "overridable, and the output location under the docs directory is configurable, so automations " +
-        "beyond ticket review can reuse it. Pass artifact_type=\"pre_ticket_planning\" to additionally " +
-        "render read-only system_goals (business goal, desired end-state, system behavior, classified " +
-        "NFRs) and a read-only implementation_order section for pre-ticket epic/task framing; open NFRs " +
-        "still go in actionable_items so the human can decide them. The default artifact_type " +
-        "\"review_decisions\" is unchanged. The user opens the HTML file in a browser, makes selections, " +
-        "and copies the resulting JSON output back to the agent.",
+    description: "Use to generate a local, review-shaped HTML decision page for capturing user decisions. " +
+        "Returns the local file path and a summary of the rendered items.",
     inputSchema: DecisionPageInputShape,
 }, async (input) => {
     // Returned messages travel through JSON.stringify in the MCP envelope below,
@@ -4972,7 +4242,7 @@ await server.connect(transport);
 // Record that the server has connected so project-root resolution may now query
 // MCP `roots/list` (it falls through to CLAUDE_PROJECT_DIR / cwd before this).
 serverConnected = true;
-console.error("Bridge API MCP server running on stdio");
+console.error(`Bridge API MCP server ${VERSION} running on stdio`);
 // Fire-and-forget update check — delay to let MCP client attach listeners
 (async () => {
     await new Promise((r) => setTimeout(r, 2000));
@@ -4981,7 +4251,7 @@ console.error("Bridge API MCP server running on stdio");
         server.server.sendLoggingMessage({
             level: "notice",
             logger: "bridge-api",
-            data: `Update available: @bridge_gpt/mcp-server ${result.currentVersion} -> ${result.latestVersion}. Run: npx -y @bridge_gpt/mcp-server --upgrade`,
+            data: `Update available: running ${result.currentVersion}, latest ${result.latestVersion} — run npx -y @bridge_gpt/mcp-server@latest --upgrade`,
         });
     }
 })().catch(() => { });