@bridge_gpt/mcp-server 0.2.60 → 0.2.62

package/build/epic-integration-pr.js

@@ -20,7 +20,7 @@ export const EPIC_INTEGRATION_PR_READ_TIMEOUT_MS = 5_000;
 export const EPIC_INTEGRATION_PR_WRITE_TIMEOUT_MS = 20_000;
 /** Bounded result count for the existence probe. */
 const LIST_LIMIT = 20;
-const PR_LIST_JSON_FIELDS = "number,headRefName,baseRefName,isDraft";
+const PR_LIST_JSON_FIELDS = "number,headRefName,baseRefName,isDraft,headRefOid";
 /**
  * `epic/<KEY>` prefix a child PR's base branch carries under BAPI-949/BAPI-950.
  * Exported (BAPI-1010) so every call site that derives an epic key from a base
@@ -40,6 +40,9 @@ export const EPIC_INTEGRATION_PR_COMMANDS = [
     // "executor merge" so the generated PR body and diagnostics never mislabel
     // a done-state readiness request as a ticket merge enrichment.
     "executor wind-down",
+    // BAPI-1259: a durable `mark_ready` integration action performed by a local or
+    // repo-wide executor under explicitly configured customer authority.
+    "executor integration",
 ];
 /** Only the sanctioned safe fields. Never raw command output. */
 export function formatEpicIntegrationPullRequestOutcome(outcome) {
@@ -69,6 +72,10 @@ export function buildEpicIntegrationPullRequestBody(epicKey, command) {
         "Only a human merges an epic integration branch — the conductor never merges it.",
     ].join("\n");
 }
+/** `--repo owner/name` when an explicit repository is bound, else nothing. */
+function repoArgs(repo) {
+    return repo !== undefined ? ["--repo", repo] : [];
+}
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -100,9 +107,16 @@ async function classifyGhUnavailable(gh, cwd) {
  * (non-zero exit, unparseable output, a non-array shape, an item with an
  * invalid number, or a record whose head/base do not match) is `unavailable`,
  * never treated as absence.
+ *
+ * BAPI-1259: the probe is also CONCLUSIVE only about exactly one PR. More than
+ * one matching record is `probe_ambiguous`, and a page that fills the whole
+ * limit is `probe_inconclusive` (there may be more records than it shows) —
+ * the old "first matching record wins" rule could bind readiness to an
+ * arbitrary pull request.
  */
-async function probeMatchingOpenPr(gh, epicBranch, baseBranch, cwd) {
+async function probeMatchingOpenPr(gh, epicBranch, baseBranch, cwd, repo) {
     const args = [
+        ...repoArgs(repo),
         "pr",
         "list",
         "--state",
@@ -139,6 +153,11 @@ async function probeMatchingOpenPr(gh, epicBranch, baseBranch, cwd) {
     if (parsed.length === 0) {
         return { kind: "absent" };
     }
+    if (parsed.length >= LIST_LIMIT) {
+        // A saturated page may be hiding more records; nothing here is conclusive.
+        return { kind: "unavailable", reason: "probe_inconclusive" };
+    }
+    const matches = [];
     for (const item of parsed) {
         if (!isRecord(item))
             continue;
@@ -152,9 +171,17 @@ async function probeMatchingOpenPr(gh, epicBranch, baseBranch, cwd) {
             head === epicBranch &&
             base === baseBranch &&
             typeof isDraft === "boolean") {
-            return { kind: "found", number, isDraft };
+            const oid = item.headRefOid;
+            const headSha = typeof oid === "string" && /^[0-9a-f]{40}$/i.test(oid) ? oid.toLowerCase() : null;
+            matches.push({ number, isDraft, headSha });
         }
     }
+    if (matches.length > 1) {
+        return { kind: "unavailable", reason: "probe_ambiguous" };
+    }
+    if (matches.length === 1) {
+        return { kind: "found", ...matches[0] };
+    }
     // Records exist but none matches both head and base exactly, or the shape is
     // unexpected — never treated as absence.
     return { kind: "unavailable", reason: "probe_malformed" };
@@ -168,10 +195,11 @@ function extractPrNumberFromCreateOutput(stdout) {
     const n = Number(match[1]);
     return Number.isInteger(n) && n > 0 ? n : null;
 }
-async function createDraftPr(gh, epicKey, epicBranch, baseBranch, command, cwd) {
+async function createDraftPr(gh, epicKey, epicBranch, baseBranch, command, cwd, repo) {
     const title = buildEpicIntegrationPullRequestTitle(epicKey);
     const body = buildEpicIntegrationPullRequestBody(epicKey, command);
     const args = [
+        ...repoArgs(repo),
         "pr",
         "create",
         "--draft",
@@ -200,15 +228,23 @@ async function createDraftPr(gh, epicKey, epicBranch, baseBranch, command, cwd)
     }
     return { kind: "create_failed" };
 }
-async function maybeMakeReady(gh, prNumber, isDraft, requestReady, cwd) {
+async function maybeMakeReady(gh, prNumber, isDraft, requestReady, cwd, headBinding = {
+    observedHeadSha: null,
+}, repo) {
     if (!requestReady)
         return "not_requested";
     if (prNumber === null)
         return "ready_failed";
+    if (headBinding.expectedHeadSha !== undefined) {
+        // Bound readiness: an unknown observed head is not the expected head.
+        if (headBinding.observedHeadSha !== headBinding.expectedHeadSha.toLowerCase()) {
+            return "ready_refused_head_drift";
+        }
+    }
     if (!isDraft)
         return "already_ready";
     try {
-        const result = await gh(["pr", "ready", String(prNumber)], {
+        const result = await gh([...repoArgs(repo), "pr", "ready", String(prNumber)], {
             cwd,
             timeoutMs: EPIC_INTEGRATION_PR_WRITE_TIMEOUT_MS,
         });
@@ -219,33 +255,34 @@ async function maybeMakeReady(gh, prNumber, isDraft, requestReady, cwd) {
     }
 }
 async function ensureEpicIntegrationPullRequestInner(options) {
-    const { epicKey, epicBranch, baseBranch, command, gh, cwd, requestReady } = options;
-    const probe = await probeMatchingOpenPr(gh, epicBranch, baseBranch, cwd);
+    const { epicKey, epicBranch, baseBranch, command, gh, cwd, requestReady, expectedHeadSha, repo } = options;
+    const bind = (observedHeadSha) => expectedHeadSha === undefined ? undefined : { expectedHeadSha, observedHeadSha };
+    const probe = await probeMatchingOpenPr(gh, epicBranch, baseBranch, cwd, repo);
     if (probe.kind === "unavailable") {
         return { kind: "unavailable", reason: probe.reason };
     }
     if (probe.kind === "found") {
-        const readiness = await maybeMakeReady(gh, probe.number, probe.isDraft, requestReady, cwd);
+        const readiness = await maybeMakeReady(gh, probe.number, probe.isDraft, requestReady, cwd, bind(probe.headSha), repo);
         return { kind: "already_open", reason: "already_open", prNumber: probe.number, readiness };
     }
     // Confirmed absent: create.
-    const created = await createDraftPr(gh, epicKey, epicBranch, baseBranch, command, cwd);
+    const created = await createDraftPr(gh, epicKey, epicBranch, baseBranch, command, cwd, repo);
     if (created.kind === "no_commits") {
         return { kind: "deferred", reason: "no_commits_between_branches" };
     }
     if (created.kind === "created") {
         // Resolve the number through a fresh matching probe first; fall back to the
         // strict URL-derived hint only when the probe cannot confirm it.
-        const reprobe = await probeMatchingOpenPr(gh, epicBranch, baseBranch, cwd);
+        const reprobe = await probeMatchingOpenPr(gh, epicBranch, baseBranch, cwd, repo);
         const prNumber = reprobe.kind === "found" ? reprobe.number : created.numberHint;
         const isDraft = reprobe.kind === "found" ? reprobe.isDraft : true;
-        const readiness = await maybeMakeReady(gh, prNumber, isDraft, requestReady, cwd);
+        const readiness = await maybeMakeReady(gh, prNumber, isDraft, requestReady, cwd, bind(reprobe.kind === "found" ? reprobe.headSha : null), repo);
         return { kind: "created", reason: "created", prNumber, readiness };
     }
     // Generic create failure: resolve a possible concurrent creator once, never more.
-    const race = await probeMatchingOpenPr(gh, epicBranch, baseBranch, cwd);
+    const race = await probeMatchingOpenPr(gh, epicBranch, baseBranch, cwd, repo);
     if (race.kind === "found") {
-        const readiness = await maybeMakeReady(gh, race.number, race.isDraft, requestReady, cwd);
+        const readiness = await maybeMakeReady(gh, race.number, race.isDraft, requestReady, cwd, bind(race.headSha), repo);
         return { kind: "already_open", reason: "already_open", prNumber: race.number, readiness };
     }
     return { kind: "unavailable", reason: "create_unavailable" };
@@ -270,9 +307,18 @@ export async function ensureEpicIntegrationPullRequest(options) {
  * binary, timeout, spawn error) resolves a non-zero/timed-out result rather
  * than rejecting.
  */
-export function createProductionEpicIntegrationGhRunner(execFileImpl = nodeExecFile) {
+export function createProductionEpicIntegrationGhRunner(execFileImpl = nodeExecFile, 
+/**
+ * BAPI-1259: an EXPLICIT child environment. A durable integration action
+ * passes the restricted environment `buildLocalMergeChildEnv` builds from the
+ * configured customer credential, so an ambient `gh` login, `GH_TOKEN`, or
+ * `GITHUB_TOKEN` can never authorize the write. Omitted, the child inherits
+ * the parent environment exactly as before (the wind-down observer).
+ */
+env) {
     return (args, options) => new Promise((resolve) => {
         execFileImpl("gh", args, {
+            ...(env ? { env } : {}),
             cwd: options.cwd,
             timeout: options.timeoutMs,
             maxBuffer: 4 * 1024 * 1024,

package/build/epic-launch-profile.js

@@ -0,0 +1,455 @@
+/**
+ * Host-local epic-launch profiles (BAPI-1260).
+ *
+ * A profile is the approved, reusable binding guided setup produces for one
+ * epic launch target: WHICH Bridge API endpoint, WHICH repository, WHICH
+ * execution host and mode, HOW the packaged CLI is invoked, and REFERENCES to the
+ * run policy and the credential. It is what lets the launch command printed at
+ * the end of setup run unchanged in a fresh shell — no `export BAPI_BASE_URL`,
+ * no remembered working shell, no database repair.
+ *
+ * ## What it is not
+ *
+ *  - **Not a secret store.** A profile holds references only. The credential
+ *    reference names a `bapi:<repo>` entry in the user-scoped credential store;
+ *    the key itself stays there. Validation rejects any field this module does
+ *    not know, so a secret cannot be smuggled in under a new name.
+ *  - **Not project configuration.** Profiles live beside the credential store in
+ *    the USER's config directory (`$XDG_CONFIG_HOME/bridge/` or
+ *    `~/.config/bridge/`), never in the repository, so committed configuration
+ *    stays secret-free and host-neutral.
+ *  - **Not an authority.** A profile selects a target; the server still decides
+ *    admission. Changing a profile's target is a guided-setup act (it re-verifies
+ *    access at the new target); a command-line override alone never rebinds one.
+ *
+ * Every exported operation returns a typed result and never throws.
+ */
+import os from "node:os";
+import path from "node:path";
+import { chmod, mkdir, open, readFile, rename, unlink, writeFile } from "node:fs/promises";
+import { durablyReplaceCredentialStoreJson, getPrimaryCredentialStorePath, withCredentialStoreLock, } from "./credential-store.js";
+import { validateHttpBaseUrl, describeBaseUrlRejection } from "./base-url.js";
+import { MCP_PACKAGE_NAME } from "./mcp-identity.js";
+import { isTransientNpxEntryPath } from "./mcp-server-invocation.js";
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+/** The only profile schema this build reads or writes. */
+export const EPIC_LAUNCH_PROFILE_VERSION = 1;
+/** File name of the host-local profile store, beside `credentials.json`. */
+export const EPIC_LAUNCH_PROFILE_STORE_FILENAME = "epic-launch-profiles.json";
+/** Selector shape: short, lowercase, shell-safe without quoting. */
+export const EPIC_LAUNCH_PROFILE_NAME_PATTERN = /^[a-z0-9][a-z0-9._-]{0,62}$/;
+/** Where the executor that serves this launch runs. */
+export const EPIC_LAUNCH_EXECUTION_MODES = ["local", "durable"];
+/** One-time migration guidance for a profile this build cannot read. */
+export function epicLaunchProfileSetupGuidance(name) {
+    return (`Re-run guided setup to (re)write it: npx -y ${MCP_PACKAGE_NAME} install conductor ` +
+        `--launch-profile ${EPIC_LAUNCH_PROFILE_NAME_PATTERN.test(name) ? name : "<name>"} --base-url <url> ...`);
+}
+// ---------------------------------------------------------------------------
+// Validation (pure)
+// ---------------------------------------------------------------------------
+const PROFILE_KEYS = new Set([
+    "version",
+    "name",
+    "baseUrl",
+    "repoName",
+    "executionMode",
+    "host",
+    "runtime",
+    "policyRef",
+    "credentialRef",
+    "approvedAt",
+]);
+const NPM_CHANNEL_SPEC = new RegExp(`^${MCP_PACKAGE_NAME.replace(/[.*+?^${}()|[\]\\/]/g, "\\$&")}@[A-Za-z0-9][A-Za-z0-9.+-]{0,63}$`);
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function nonEmptyString(value, max = 512) {
+    return typeof value === "string" && value.trim().length > 0 && value.length <= max && !/[\0\n\r]/.test(value);
+}
+function malformed(name, field, why) {
+    return {
+        ok: false,
+        kind: "profile-malformed",
+        message: `Epic launch profile '${name}' is unusable: ${field} ${why}. ${epicLaunchProfileSetupGuidance(name)}`,
+    };
+}
+function validateRuntime(name, raw) {
+    if (!isPlainObject(raw))
+        return malformed(name, "runtime", "is not an object");
+    if (raw.kind === "packaged") {
+        const keys = Object.keys(raw);
+        if (keys.some((k) => !["kind", "executable", "entryPath"].includes(k))) {
+            return malformed(name, "runtime", "carries an unknown field");
+        }
+        if (!nonEmptyString(raw.executable) || !path.isAbsolute(raw.executable)) {
+            return malformed(name, "runtime.executable", "is not an absolute path");
+        }
+        if (!nonEmptyString(raw.entryPath) || !path.isAbsolute(raw.entryPath)) {
+            return malformed(name, "runtime.entryPath", "is not an absolute path");
+        }
+        if (isTransientNpxEntryPath(raw.entryPath)) {
+            return malformed(name, "runtime.entryPath", "lives in a transient npx cache that can be pruned");
+        }
+        return { kind: "packaged", executable: raw.executable, entryPath: raw.entryPath };
+    }
+    if (raw.kind === "npm-channel") {
+        if (Object.keys(raw).some((k) => !["kind", "spec"].includes(k))) {
+            return malformed(name, "runtime", "carries an unknown field");
+        }
+        if (typeof raw.spec !== "string" || !NPM_CHANNEL_SPEC.test(raw.spec)) {
+            return malformed(name, "runtime.spec", `is not ${MCP_PACKAGE_NAME}@<channel-or-version>`);
+        }
+        return { kind: "npm-channel", spec: raw.spec };
+    }
+    return malformed(name, "runtime.kind", "is not 'packaged' or 'npm-channel'");
+}
+/**
+ * Validate one decoded profile. Strict: unknown fields, a GitHub or non-`bapi:`
+ * credential reference, a transient runtime, a relative policy path, or a
+ * durable-mode profile without a packaged runtime are all refused.
+ */
+export function validateEpicLaunchProfile(raw, selector = "<unnamed>") {
+    if (!isPlainObject(raw))
+        return malformed(selector, "the entry", "is not an object");
+    if (raw.version !== EPIC_LAUNCH_PROFILE_VERSION) {
+        return {
+            ok: false,
+            kind: "profile-unsupported-version",
+            message: `Epic launch profile '${selector}' uses an unsupported schema version; this build reads ` +
+                `version ${EPIC_LAUNCH_PROFILE_VERSION} only. ${epicLaunchProfileSetupGuidance(selector)}`,
+        };
+    }
+    for (const key of Object.keys(raw)) {
+        if (!PROFILE_KEYS.has(key))
+            return malformed(selector, `field '${key.slice(0, 40)}'`, "is not recognized");
+    }
+    if (typeof raw.name !== "string" || !EPIC_LAUNCH_PROFILE_NAME_PATTERN.test(raw.name) || raw.name !== selector) {
+        return malformed(selector, "name", "does not match its selector");
+    }
+    const url = validateHttpBaseUrl(typeof raw.baseUrl === "string" ? raw.baseUrl : undefined);
+    if (!url.ok)
+        return malformed(selector, "baseUrl", `is invalid (${describeBaseUrlRejection("baseUrl", url.reason)})`);
+    if (url.baseUrl !== raw.baseUrl)
+        return malformed(selector, "baseUrl", "is not normalized");
+    if (!nonEmptyString(raw.repoName, 200))
+        return malformed(selector, "repoName", "is missing");
+    if (!EPIC_LAUNCH_EXECUTION_MODES.includes(raw.executionMode)) {
+        return malformed(selector, "executionMode", "is not 'local' or 'durable'");
+    }
+    if (!nonEmptyString(raw.host, 255))
+        return malformed(selector, "host", "is missing");
+    const runtime = validateRuntime(selector, raw.runtime);
+    if ("ok" in runtime)
+        return runtime;
+    if (raw.executionMode === "durable" && runtime.kind !== "packaged") {
+        return malformed(selector, "runtime", "must be a packaged absolute path for durable execution");
+    }
+    let policyRef = null;
+    if (raw.policyRef !== null && raw.policyRef !== undefined) {
+        const p = raw.policyRef;
+        if (!isPlainObject(p) || p.kind !== "file" || Object.keys(p).some((k) => k !== "kind" && k !== "path")) {
+            return malformed(selector, "policyRef", "is not a file reference");
+        }
+        if (!nonEmptyString(p.path) || !path.isAbsolute(p.path)) {
+            return malformed(selector, "policyRef.path", "is not an absolute path");
+        }
+        policyRef = { kind: "file", path: p.path };
+    }
+    const c = raw.credentialRef;
+    if (!isPlainObject(c) ||
+        c.store !== "bridge-credentials" ||
+        Object.keys(c).some((k) => k !== "store" && k !== "target") ||
+        c.target !== `bapi:${raw.repoName}`) {
+        // Refused rather than generalized: a launch uses exactly one Bridge
+        // credential, and a `github:*` (or any other) reference here would be the
+        // first step toward a standing code-host credential on the launch path.
+        return malformed(selector, "credentialRef", "must reference exactly bapi:<repoName>");
+    }
+    if (!nonEmptyString(raw.approvedAt, 64))
+        return malformed(selector, "approvedAt", "is missing");
+    return {
+        ok: true,
+        profile: {
+            version: EPIC_LAUNCH_PROFILE_VERSION,
+            name: raw.name,
+            baseUrl: url.baseUrl,
+            repoName: raw.repoName,
+            executionMode: raw.executionMode,
+            host: raw.host,
+            runtime,
+            policyRef,
+            credentialRef: { store: "bridge-credentials", target: `bapi:${raw.repoName}` },
+            approvedAt: raw.approvedAt,
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Store I/O
+// ---------------------------------------------------------------------------
+/** The profile store path, beside the primary credential store. */
+export function getEpicLaunchProfileStorePath(deps) {
+    return path.join(path.dirname(getPrimaryCredentialStorePath(deps)), EPIC_LAUNCH_PROFILE_STORE_FILENAME);
+}
+async function readStoreDocument(deps) {
+    const storePath = getEpicLaunchProfileStorePath(deps);
+    let raw;
+    try {
+        raw = await deps.readFile(storePath);
+    }
+    catch (err) {
+        const code = err && typeof err === "object" ? err.code : undefined;
+        if (code === "ENOENT") {
+            return { ok: true, present: false, document: { version: EPIC_LAUNCH_PROFILE_VERSION, profiles: {} } };
+        }
+        return { ok: false, kind: "store-unreadable", message: `Unable to read ${storePath}.` };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return { ok: false, kind: "store-unreadable", message: `${storePath} is not valid JSON.` };
+    }
+    if (!isPlainObject(parsed) || !isPlainObject(parsed.profiles)) {
+        return { ok: false, kind: "store-unreadable", message: `${storePath} has no profiles object.` };
+    }
+    if (parsed.version !== EPIC_LAUNCH_PROFILE_VERSION) {
+        return {
+            ok: false,
+            kind: "profile-unsupported-version",
+            message: `${storePath} uses an unsupported schema version; this build reads version ` +
+                `${EPIC_LAUNCH_PROFILE_VERSION} only. ${epicLaunchProfileSetupGuidance("<name>")}`,
+        };
+    }
+    return { ok: true, present: true, document: { version: EPIC_LAUNCH_PROFILE_VERSION, profiles: parsed.profiles } };
+}
+/**
+ * Read and validate one profile by selector. Read-only: a missing, malformed, or
+ * unsupported profile is reported with guidance and never repaired here.
+ *
+ * `host`, when supplied, must match the profile's approved host — a profile
+ * copied to another machine names a runtime and a credential store that do not
+ * exist there.
+ */
+export async function readEpicLaunchProfile(name, deps) {
+    if (!EPIC_LAUNCH_PROFILE_NAME_PATTERN.test(name)) {
+        return {
+            ok: false,
+            kind: "invalid-name",
+            message: "An epic launch profile name must match [a-z0-9][a-z0-9._-]{0,62}.",
+        };
+    }
+    const store = await readStoreDocument(deps);
+    if (!store.ok)
+        return store;
+    if (!Object.prototype.hasOwnProperty.call(store.document.profiles, name)) {
+        return {
+            ok: false,
+            kind: "profile-missing",
+            message: `No epic launch profile named '${name}' exists on this host. ${epicLaunchProfileSetupGuidance(name)}`,
+        };
+    }
+    const validated = validateEpicLaunchProfile(store.document.profiles[name], name);
+    if (!validated.ok)
+        return validated;
+    if (deps.host !== undefined && validated.profile.host !== deps.host) {
+        return {
+            ok: false,
+            kind: "profile-host-mismatch",
+            message: `Epic launch profile '${name}' was approved on a different host. Profiles are host-local; ` +
+                epicLaunchProfileSetupGuidance(name),
+        };
+    }
+    return validated;
+}
+export async function listEpicLaunchProfiles(deps) {
+    const store = await readStoreDocument(deps);
+    if (!store.ok)
+        return store;
+    if (!store.present)
+        return { ok: true, present: false };
+    const entries = Object.keys(store.document.profiles)
+        .sort()
+        .map((name) => ({ name, validation: validateEpicLaunchProfile(store.document.profiles[name], name) }));
+    return { ok: true, present: true, entries };
+}
+/**
+ * Persist one validated profile: locked (the shared credential-store lock) and
+ * durable (temp → fsync → rename). Every other profile in the store is kept,
+ * including ones this build cannot validate — a newer build's profile is never
+ * deleted by an older one.
+ */
+export async function writeEpicLaunchProfile(profile, deps) {
+    const validated = validateEpicLaunchProfile(profile, profile.name);
+    if (!validated.ok)
+        return validated;
+    const storePath = getEpicLaunchProfileStorePath(deps);
+    return withCredentialStoreLock(deps, async () => {
+        const store = await readStoreDocument(deps);
+        if (!store.ok)
+            return store;
+        const existing = store.document.profiles[profile.name];
+        const serialized = JSON.parse(JSON.stringify(validated.profile));
+        if (existing !== undefined && JSON.stringify(existing) === JSON.stringify(serialized)) {
+            return { ok: true, path: storePath, action: "unchanged" };
+        }
+        const next = {
+            version: EPIC_LAUNCH_PROFILE_VERSION,
+            profiles: { ...store.document.profiles, [profile.name]: serialized },
+        };
+        // The durable writer is typed for the credential store, but it serializes
+        // any JSON value the same way (2-space indent, 0600, fsync, rename).
+        const written = await durablyReplaceCredentialStoreJson(storePath, next, deps);
+        if (!written.ok) {
+            return { ok: false, kind: "store-write-failed", message: `Failed to durably write ${storePath}.` };
+        }
+        return { ok: true, path: storePath, action: existing === undefined ? "created" : "updated" };
+    }, (error) => ({ ok: false, kind: "store-write-failed", message: error }));
+}
+/**
+ * Normalize every applicable target source and decide ONE target, before any
+ * credential is resolved and before any request is made.
+ *
+ *  - With a selected profile, the profile's target wins, and a `--base-url` or
+ *    `BAPI_BASE_URL` that names a DIFFERENT endpoint is a conflict — an override
+ *    alone never rebinds a profile; guided setup does that.
+ *  - Without one, `--base-url` and `BAPI_BASE_URL` must agree when both are set.
+ *  - Nothing set is `target-missing`. There is no production default here:
+ *    production is supported, but only as a deliberate selection.
+ *
+ * Messages name the source and the rule only — never a URL, which can carry
+ * userinfo.
+ */
+export function resolveEpicLaunchTarget(inputs) {
+    const normalize = (raw, label) => {
+        if (raw === undefined || raw.trim() === "")
+            return { ok: true, value: null };
+        const v = validateHttpBaseUrl(raw);
+        if (!v.ok)
+            return { ok: false, message: describeBaseUrlRejection(label, v.reason) };
+        return { ok: true, value: v.baseUrl };
+    };
+    const flag = normalize(inputs.flagBaseUrl, "--base-url");
+    if (!flag.ok)
+        return { ok: false, kind: "target-invalid", message: flag.message };
+    const env = normalize(inputs.env.BAPI_BASE_URL, "BAPI_BASE_URL");
+    if (!env.ok)
+        return { ok: false, kind: "target-invalid", message: env.message };
+    const profile = inputs.profile;
+    if (profile !== null) {
+        if (flag.value !== null && flag.value !== profile.baseUrl) {
+            return {
+                ok: false,
+                kind: "target-conflict",
+                message: `--base-url names a different endpoint than launch profile '${profile.name}'. An override ` +
+                    "does not rebind a profile; re-run guided setup to change its target.",
+            };
+        }
+        if (env.value !== null && env.value !== profile.baseUrl) {
+            return {
+                ok: false,
+                kind: "target-conflict",
+                message: `BAPI_BASE_URL names a different endpoint than launch profile '${profile.name}'. Unset it, ` +
+                    "or re-run guided setup to change the profile's target.",
+            };
+        }
+        const flagRepo = inputs.flagRepo?.trim();
+        if (flagRepo && flagRepo !== profile.repoName) {
+            return {
+                ok: false,
+                kind: "repository-conflict",
+                message: `--repo names a different repository than launch profile '${profile.name}'.`,
+            };
+        }
+        return { ok: true, baseUrl: profile.baseUrl, source: "profile", repoName: profile.repoName };
+    }
+    if (flag.value !== null && env.value !== null && flag.value !== env.value) {
+        return {
+            ok: false,
+            kind: "target-conflict",
+            message: "--base-url and BAPI_BASE_URL name different endpoints. Keep one, or make them agree.",
+        };
+    }
+    if (flag.value !== null)
+        return { ok: true, baseUrl: flag.value, source: "flag" };
+    if (env.value !== null)
+        return { ok: true, baseUrl: env.value, source: "env" };
+    return {
+        ok: false,
+        kind: "target-missing",
+        message: "No Bridge API target is selected for this epic launch. Pass --launch-profile <name> (created by " +
+            `\`npx -y ${MCP_PACKAGE_NAME} install conductor --launch-profile <name> --base-url <url>\`), or ` +
+            "--base-url <url>. Nothing defaults to production.",
+    };
+}
+// ---------------------------------------------------------------------------
+// Command rendering (pure)
+// ---------------------------------------------------------------------------
+/** POSIX single-quote a word unless it is already shell-safe. */
+export function shellQuote(word) {
+    if (/^[A-Za-z0-9_@%+=:,./-]+$/.test(word))
+        return word;
+    return `'${word.replace(/'/g, `'\\''`)}'`;
+}
+/** The argv prefix that invokes the packaged CLI for a runtime. */
+export function epicLaunchRuntimeArgv(runtime) {
+    return runtime.kind === "packaged"
+        ? [runtime.executable, runtime.entryPath]
+        : ["npx", "-y", runtime.spec];
+}
+/**
+ * Render the one reusable `drive-epic` command for a profile: shell-safe,
+ * secret-free (a profile holds no secret and nothing here reads the
+ * environment), and complete — the profile selector, the plan, and the policy —
+ * so it runs unchanged in a fresh shell.
+ */
+export function renderEpicLaunchCommand(profile, inputs) {
+    const policy = inputs.policyFile ?? profile.policyRef?.path;
+    const argv = [
+        ...epicLaunchRuntimeArgv(profile.runtime),
+        "drive-epic",
+        inputs.epicKey,
+        "--launch-profile",
+        profile.name,
+        "--plan-file",
+        inputs.planFile,
+        ...(policy ? ["--policy-file", policy] : []),
+        ...(inputs.featureBranch ? ["--feature-branch", inputs.featureBranch] : []),
+        ...(inputs.intoBase ? ["--into-base"] : []),
+        ...(inputs.attended ? ["--attended"] : []),
+    ];
+    return argv.map(shellQuote).join(" ");
+}
+// ---------------------------------------------------------------------------
+// Production I/O
+// ---------------------------------------------------------------------------
+/**
+ * Real-filesystem write deps for the profile store and the credential binding:
+ * `fs/promises` plus the `open` primitive that gives the shared lock and the
+ * fsync'd replacement. Built here rather than imported from `index.ts`, whose
+ * import runs the CLI dispatcher.
+ */
+export function createNodeEpicLaunchStoreDeps(env = process.env) {
+    return {
+        env,
+        homedir: os.homedir,
+        platform: process.platform,
+        readFile: (p) => readFile(p, "utf-8"),
+        mkdir: (p, options) => mkdir(p, options),
+        writeFile: (p, data, options) => writeFile(p, data, options),
+        rename: (oldPath, newPath) => rename(oldPath, newPath),
+        chmod: (p, mode) => chmod(p, mode),
+        unlink: (p) => unlink(p),
+        open: async (p, flags, mode) => {
+            const handle = await open(p, flags, mode);
+            return {
+                writeFile: (data) => handle.writeFile(data, { encoding: "utf-8" }),
+                sync: () => handle.sync(),
+                close: () => handle.close(),
+            };
+        },
+    };
+}

package/build/executor/cli.js

@@ -16,6 +16,7 @@ import { createDefaultExecutorDeps } from "./deps.js";
 import { scrubExecutorProcessGithubCredentials } from "./env.js";
 import { resolveBaseUrl, resolveExecutorApiAccess, EXECUTOR_BASE_URL_REQUIRED_MESSAGE, } from "./credentials.js";
 import { createExecutorHttpClient } from "./http-client.js";
+import { createIntegrationActionHttpClient, } from "./integration-job.js";
 import { startExecutorSleepAssertion } from "./platform.js";
 import { runExecutor } from "./runner.js";
 import { runExecutorWatchCli } from "./watch-cli.js";
@@ -397,8 +398,16 @@ export async function runExecutorCli(argv, overrides = {}) {
         clearTimer: deps.clearTimer,
         errorLog,
     });
+    const createIntegrationClient = overrides.createIntegrationClient ?? createIntegrationActionHttpClient;
     const runnerSeams = {
         onSignal: overrides.onSignal ?? defaultSignalRegistrar,
+        integrationActions: createIntegrationClient({
+            baseUrl,
+            apiKey: apiKeyByRepo[options.repoName],
+            apiKeyByRepo,
+            mcpVersion: VERSION,
+            fetch: deps.fetch,
+        }),
     };
     try {
         return await run(runtimeOptions, deps, httpClient, runnerSeams);