@bridge_gpt/mcp-server 0.2.50 → 0.2.51

package/build/conduct-epic/cut-protocol.js

@@ -277,6 +277,53 @@ export const SCOPE_LIFECYCLE_LABELS = Object.freeze({
     ready: "Ready",
     failed: "Failed",
 });
+/**
+ * The fixed lifecycle label a heartbeat uses when the status READ itself failed
+ * (BAPI-963).
+ *
+ * A read failure is not a lifecycle state, and the raw error is deliberately not
+ * interpolated into a heartbeat: a per-poll line repeated for twenty minutes is
+ * the worst possible place to smuggle unbounded server text.
+ */
+export const SCOPE_BOOTSTRAP_UNREADABLE_STATE = "unreadable";
+/**
+ * Format one bootstrap heartbeat line (BAPI-963).
+ *
+ * Shared with `setup-epic` at this seam so both conductors compute progress the
+ * same way; RENDERING stays with each caller, because the pilot writes to its own
+ * stderr advisory channel and v2 reports progress server-side.
+ *
+ * The shape is fixed and grep-friendly — elapsed first, state second — because a
+ * ~30-minute seed that printed nothing was externally indistinguishable from a
+ * hang (sleeping process, 0% CPU, a frozen `updated_at`). Elapsed seconds are
+ * clamped at zero so a clock adjustment cannot render a negative age.
+ */
+export function formatScopeBootstrapHeartbeat(elapsedMs, state) {
+    const seconds = Math.max(0, Math.floor(elapsedMs / 1000));
+    // `lifecycle_state` is a required non-empty string on the wire, not a closed
+    // set. Bounding it to the known labels (plus the fixed `unreadable` and a
+    // catch-all) keeps an unvalidated server string out of a line that repeats
+    // every interval for up to twenty minutes.
+    const bounded = state === SCOPE_BOOTSTRAP_UNREADABLE_STATE || state in SCOPE_LIFECYCLE_LABELS
+        ? state
+        : "unknown";
+    return `Seeding scope: elapsed=${seconds}s state=${bounded}`;
+}
+/**
+ * Describe the nominal polling window up front (BAPI-963).
+ *
+ * Computed from the interval and cap rather than hard-coded, so a change to
+ * either constant cannot leave the operator-facing duration claim stale. The
+ * window is NOMINAL: the observed pilot seed outran even this bound, which is
+ * why the wording promises a poll cadence rather than a completion time.
+ */
+export function describeScopeBootstrapWindow(intervalMs = SCOPE_BOOTSTRAP_POLL_INTERVAL_MS, maxPolls = SCOPE_BOOTSTRAP_MAX_POLLS) {
+    const intervalSeconds = Math.max(1, Math.round(intervalMs / 1000));
+    const windowMinutes = Math.max(1, Math.round((intervalMs * maxPolls) / 60_000));
+    return (`Seeding the epic's index scope. This copies the repository's whole parse cache and ` +
+        `verifies it, and commonly takes many minutes. Progress is reported every ` +
+        `${intervalSeconds}s; the poll gives up after about ${windowMinutes} minutes.`);
+}
 /**
  * Poll a scope's lifecycle until it is `ready`, `failed`, or the bounded wait
  * elapses, reporting each NEWLY observed lifecycle transition exactly once, in
@@ -296,6 +343,8 @@ export async function pollIndexScopeLifecycle(deps, access, scopeId, options = {
     const sleep = deps.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
     const maxPolls = options.maxPolls ?? SCOPE_BOOTSTRAP_MAX_POLLS;
     const intervalMs = options.intervalMs ?? SCOPE_BOOTSTRAP_POLL_INTERVAL_MS;
+    const now = options.now ?? (() => new Date());
+    const startedAtMs = now().getTime();
     let lastState = "unknown";
     let lastStatus = null;
     let lastReportedState = null;
@@ -304,10 +353,12 @@ export async function pollIndexScopeLifecycle(deps, access, scopeId, options = {
         const status = await getIndexScopeStatus(access, scopeId, deps.fetchImpl);
         if (!status.ok) {
             lastState = `unreadable (${status.error})`;
+            options.onPoll?.(now().getTime() - startedAtMs, SCOPE_BOOTSTRAP_UNREADABLE_STATE);
             continue;
         }
         lastStatus = status.value;
         lastState = status.value.lifecycle_state;
+        options.onPoll?.(now().getTime() - startedAtMs, lastState);
         if (lastState !== lastReportedState) {
             lastReportedState = lastState;
             options.onTransition?.(lastState, status.value);

package/build/doctor.js

@@ -28,6 +28,7 @@ import { createBridgeApiUrls } from "./bridge-api-urls.js";
 import { probeToolSurface } from "./tool-surface-gating.js";
 import { resolveBapiCredentials } from "./credential-store.js";
 import { resolveConductorBridgeApiAccess } from "./conductor/bridge-api-client.js";
+import { getLiveRepositoryConductors, getParseDispatcherHealth, } from "./conduct-epic/bridge-client.js";
 import { resolveConductEpicStateDirectory } from "./conduct-epic/checkpoint-store.js";
 import { isConductEpicLockOwnerAlive, parseConductEpicLock, } from "./conduct-epic/lock.js";
 import { resolveRequiredStartTicketsRepoName } from "./start-tickets-repo.js";
@@ -1401,6 +1402,151 @@ export function formatConductEpicDiagnosticReport(diagnostic) {
     lines.push("           lock, rewrites no checkpoint, and never changes the exit code.");
     return lines.join("\n");
 }
+/**
+ * Collect the operational advisories, read-only.
+ *
+ * Local pilot conductors are identified from the SAME checkpoint-directory and
+ * lock inspection `conduct-epic readiness` uses — `parseConductEpicLock` plus the
+ * injected liveness seam — never from the process table. Only a lock proven live
+ * on THIS host counts; malformed, unreadable, dead, and remote-host locks are
+ * excluded from the live set, with the indeterminate ones counted separately.
+ */
+export async function collectOperationalAdvisories(deps) {
+    const isAlive = deps.isProcessAlive ?? isConductEpicLockOwnerAlive;
+    const now = deps.now ?? (() => new Date());
+    const resolveAccess = deps.resolveAccess ?? resolveConductorBridgeApiAccess;
+    let dispatcher = null;
+    let conductorObservation = "unavailable";
+    const conductors = [];
+    let repo = null;
+    let access = null;
+    try {
+        access = await resolveAccess({
+            env: deps.env,
+            cwd: deps.cwd,
+            homedir: deps.homedir,
+            platform: deps.platform,
+            readFile: deps.readFile,
+            stat: deps.stat,
+        });
+    }
+    catch {
+        access = null;
+    }
+    if (access !== null && access.ok) {
+        repo = access.access.repoName;
+        const fetchImpl = deps.fetchImpl ?? globalThis.fetch;
+        const health = await getParseDispatcherHealth(access.access, fetchImpl);
+        dispatcher = health.ok
+            ? health.value
+            : { observation: "unavailable", heartbeatState: null, respondingSchedulerRunning: false };
+        const live = await getLiveRepositoryConductors(access.access, now(), fetchImpl);
+        if (live.ok) {
+            conductorObservation = live.value.observation;
+            conductors.push(...live.value.conductors);
+        }
+    }
+    // Local pilot locks. Read through the same path the readiness section uses; a
+    // failure to read the directory is silence, not a claim that none are held.
+    let indeterminateLocks = 0;
+    if (repo !== null) {
+        const stateDirectory = resolveConductEpicStateDirectory(repo, {
+            env: deps.env,
+            homedir: deps.homedir,
+        });
+        let entries = [];
+        try {
+            entries = await deps.readdir(stateDirectory);
+        }
+        catch {
+            entries = [];
+        }
+        for (const entry of entries) {
+            if (!entry.endsWith(".lock"))
+                continue;
+            const epic = entry.slice(0, -".lock".length);
+            let raw;
+            try {
+                raw = await deps.readFile(path.join(stateDirectory, entry));
+            }
+            catch {
+                indeterminateLocks += 1;
+                continue;
+            }
+            const owner = parseConductEpicLock(raw);
+            if (owner === null) {
+                indeterminateLocks += 1;
+                continue;
+            }
+            const local = owner.host === deps.env.HOSTNAME || owner.host === os.hostname();
+            if (!local) {
+                indeterminateLocks += 1;
+                continue;
+            }
+            if (!isAlive(owner.owner_pid))
+                continue;
+            // A pilot lock and a v2 run are two DISTINCT conductor authorities. Even
+            // when both name the same epic they are not deduplicated — that pairing is
+            // precisely the overlap an operator most needs to see.
+            //
+            // The key comes from a FILENAME, so it is bounded against the epic-key shape
+            // before it is rendered; an unrecognized name reports `unknown` rather than
+            // putting arbitrary filesystem text into a diagnostic line.
+            conductors.push({
+                kind: "pilot",
+                epicKey: validateTicketKey(epic, "epic key").ok ? epic : null,
+                state: "lock held",
+                livenessSource: "lock",
+            });
+        }
+        if (conductors.length > 0 && conductorObservation !== "observed") {
+            conductorObservation = "observed";
+        }
+    }
+    return { dispatcher, conductorObservation, conductors, indeterminateLocks };
+}
+/** Render the operational-advisories section. Advisory: never changes the exit code. */
+export function formatOperationalAdvisoryReport(diagnostic) {
+    const lines = ["", "operational advisories (advisory)"];
+    const dispatcher = diagnostic.dispatcher;
+    if (dispatcher === null) {
+        lines.push("  SKIP     Parse dispatcher: not checked (no Bridge credential resolved).");
+    }
+    else if (dispatcher.observation === "observed") {
+        lines.push("  OK       Parse dispatcher: observable — queued repository parses are being swept.");
+    }
+    else if (dispatcher.observation === "absent") {
+        lines.push("  WARN     Parse dispatcher: NOT observed. Queued repository parses wait for the\n" +
+            "           `worker:` dyno's parse-queue sweep; nothing else dispatches them.");
+    }
+    else {
+        lines.push("  SKIP     Parse dispatcher: unavailable — the liveness read produced no verdict.\n" +
+            "           This is not evidence that no dispatcher is running.");
+    }
+    if (diagnostic.conductorObservation === "unavailable") {
+        lines.push("  SKIP     Concurrent conductors: unavailable — the repository-scoped read produced\n" +
+            "           no verdict.");
+    }
+    else if (diagnostic.conductors.length === 0) {
+        lines.push("  OK       Concurrent conductors: none live on this repository.");
+    }
+    else {
+        lines.push(`  WARN     Concurrent conductors: ${diagnostic.conductors.length} live on this repository.`);
+        for (const conductor of diagnostic.conductors) {
+            lines.push(`           ${conductor.kind}  epic=${conductor.epicKey ?? "unknown"}  ` +
+                `state=${conductor.state}  liveness=${conductor.livenessSource}`);
+        }
+        lines.push("           A distinct-epic overlap is informational and may be legitimate: separately\n" +
+            "           scoped epics do not share transition authority.");
+    }
+    if (diagnostic.indeterminateLocks > 0) {
+        lines.push(`           ${diagnostic.indeterminateLocks} local lock(s) could not be judged (remote host,\n` +
+            "           malformed, or unreadable) and are excluded from the live count.");
+    }
+    lines.push("           Read-only: this section issues two Bridge GETs and reads local lock state. It");
+    lines.push("           runs NO command probe, repairs no scheduler, and never changes the exit code.");
+    return lines.join("\n");
+}
 /**
  * CLI entry for the read-only `doctor` subcommand. Returns a process exit code.
  * Help returns 0; parser errors return 1; otherwise it prints the report and
@@ -1701,6 +1847,50 @@ export async function runDoctorCli(argv, overrides = {}) {
             }));
         }
     }
+    // Advisory operational-advisories section (BAPI-963), placed immediately after
+    // `conduct-epic readiness` because both are read by the same operator at the
+    // same moment — "can I conduct?" then "what else is already running?".
+    //
+    // Gated on `collection.ok` for the same reason the section above is: an
+    // unsupported platform reports nothing. That gate is belt-and-braces here,
+    // because this section issues NO command probe on any path — the two facts it
+    // reports come from read-only Bridge GETs and from local lock state. The
+    // "unsupported platform runs zero probes" pin is therefore untouched by it.
+    //
+    // Advisory with respect to the EXIT CODE: an absent dispatcher, a concurrent
+    // conductor, and an unavailable read all leave doctor's pass/fail exactly as
+    // the required prerequisites computed it.
+    if (overrides.operationalAdvisories !== false && collection.ok) {
+        try {
+            const injectedFs = deps;
+            const advisoryDeps = {
+                env: overrides.operationalAdvisories?.env ?? deps.env,
+                cwd: overrides.operationalAdvisories?.cwd ?? deps.cwd,
+                platform: overrides.operationalAdvisories?.platform ?? deps.platform,
+                homedir: overrides.operationalAdvisories?.homedir ?? injectedFs.homedir ?? os.homedir,
+                readFile: overrides.operationalAdvisories?.readFile ??
+                    injectedFs.readFile ??
+                    ((p) => readFile(p, "utf-8")),
+                stat: overrides.operationalAdvisories?.stat ?? injectedFs.stat ?? ((p) => stat(p)),
+                readdir: overrides.operationalAdvisories?.readdir ?? ((p) => readdir(p)),
+                resolveAccess: overrides.operationalAdvisories?.resolveAccess,
+                isProcessAlive: overrides.operationalAdvisories?.isProcessAlive,
+                fetchImpl: overrides.operationalAdvisories?.fetchImpl,
+                now: overrides.operationalAdvisories?.now,
+            };
+            log(formatOperationalAdvisoryReport(await collectOperationalAdvisories(advisoryDeps)));
+        }
+        catch {
+            // Any unexpected failure still renders a sanitized advisory section rather
+            // than dropping it or leaking exception text.
+            log(formatOperationalAdvisoryReport({
+                dispatcher: null,
+                conductorObservation: "unavailable",
+                conductors: [],
+                indeterminateLocks: 0,
+            }));
+        }
+    }
     // Opt-in stale-ticket-branch section (BAPI-948). Gated on argv, not on platform
     // support: it runs ONLY when the operator named at least one `--stale-branch`
     // ticket, so an ordinary `doctor` run issues zero extra command probes and

package/build/epic-integration-pr.js

@@ -0,0 +1,280 @@
+/**
+ * Shared, non-throwing helper that ensures a draft epic-integration PR exists
+ * (BAPI-951).
+ *
+ * Local `gh` is used deliberately here: the Bridge/server pull-request seam has
+ * no `draft` parameter and cannot distinguish GitHub's "no commits between
+ * branches" 422 from a credential or provider failure — both of which this
+ * helper must classify without throwing.
+ *
+ * A draft PR still receives the `conductor-ci / gate` required check (BAPI-949's
+ * trigger has no draft exclusion), while `claude-review.yml` excludes drafts
+ * until the PR is marked ready. So opening the integration PR as a draft earns
+ * the epic branch its required CI immediately, without paying for a paid review
+ * nobody can act on until a human decides the epic is ready.
+ */
+import { execFile as nodeExecFile } from "node:child_process";
+/** Bounded read timeout — matches the existing 5s GitHub probe limit (pr-discovery.ts). */
+export const EPIC_INTEGRATION_PR_READ_TIMEOUT_MS = 5_000;
+/** Separate, larger bounded timeout for the two write operations (`pr create`, `pr ready`). */
+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";
+/** The production call sites this helper is invoked from. */
+export const EPIC_INTEGRATION_PR_COMMANDS = [
+    "setup-epic",
+    "conduct-epic init",
+    "conduct-epic catch-up",
+    "conduct-epic finish",
+    "executor merge",
+];
+/** Only the sanctioned safe fields. Never raw command output. */
+export function formatEpicIntegrationPullRequestOutcome(outcome) {
+    if (outcome.kind === "already_open" || outcome.kind === "created") {
+        return {
+            kind: outcome.kind,
+            reason: outcome.reason,
+            pr_number: outcome.prNumber,
+            readiness: outcome.readiness,
+        };
+    }
+    return { kind: outcome.kind, reason: outcome.reason };
+}
+/** A concise, epic-specific PR title. Does not depend on `gh`. */
+export function buildEpicIntegrationPullRequestTitle(epicKey) {
+    return `${epicKey}: epic integration branch`;
+}
+/** A non-empty, epic-specific PR body. Does not depend on `gh`. */
+export function buildEpicIntegrationPullRequestBody(epicKey, command) {
+    return [
+        `\`${command}\` opened this pull request automatically.`,
+        "",
+        `It exists so the \`conductor-ci / gate\` required check runs for the ${epicKey} ` +
+            "epic integration branch (BAPI-949). Draft status postpones the paid Claude " +
+            "review until a human marks this pull request ready for review.",
+        "",
+        "Only a human merges an epic integration branch — the conductor never merges it.",
+    ].join("\n");
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** Bounded diagnostics to distinguish "no local gh", "not authenticated", and "inconclusive". */
+async function classifyGhUnavailable(gh, cwd) {
+    let version;
+    try {
+        version = await gh(["--version"], { cwd, timeoutMs: EPIC_INTEGRATION_PR_READ_TIMEOUT_MS });
+    }
+    catch {
+        return "gh_unavailable";
+    }
+    if (version.exitCode !== 0)
+        return "gh_unavailable";
+    let auth;
+    try {
+        auth = await gh(["auth", "status"], { cwd, timeoutMs: EPIC_INTEGRATION_PR_READ_TIMEOUT_MS });
+    }
+    catch {
+        return "probe_inconclusive";
+    }
+    if (auth.exitCode !== 0)
+        return "gh_unauthenticated";
+    return "probe_inconclusive";
+}
+/**
+ * Existence probe: `gh pr list` constrained by BOTH head and base. Only a
+ * successful, valid, empty JSON array is confirmed absence — anything else
+ * (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.
+ */
+async function probeMatchingOpenPr(gh, epicBranch, baseBranch, cwd) {
+    const args = [
+        "pr",
+        "list",
+        "--state",
+        "open",
+        "--head",
+        epicBranch,
+        "--base",
+        baseBranch,
+        "--json",
+        PR_LIST_JSON_FIELDS,
+        "--limit",
+        String(LIST_LIMIT),
+    ];
+    let result;
+    try {
+        result = await gh(args, { cwd, timeoutMs: EPIC_INTEGRATION_PR_READ_TIMEOUT_MS });
+    }
+    catch {
+        return { kind: "unavailable", reason: await classifyGhUnavailable(gh, cwd) };
+    }
+    if (result.exitCode !== 0) {
+        return { kind: "unavailable", reason: await classifyGhUnavailable(gh, cwd) };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(result.stdout);
+    }
+    catch {
+        return { kind: "unavailable", reason: "probe_malformed" };
+    }
+    if (!Array.isArray(parsed)) {
+        return { kind: "unavailable", reason: "probe_malformed" };
+    }
+    if (parsed.length === 0) {
+        return { kind: "absent" };
+    }
+    for (const item of parsed) {
+        if (!isRecord(item))
+            continue;
+        const number = item.number;
+        const head = item.headRefName;
+        const base = item.baseRefName;
+        const isDraft = item.isDraft;
+        if (typeof number === "number" &&
+            Number.isInteger(number) &&
+            number > 0 &&
+            head === epicBranch &&
+            base === baseBranch &&
+            typeof isDraft === "boolean") {
+            return { kind: "found", number, isDraft };
+        }
+    }
+    // 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" };
+}
+const NO_COMMITS_BETWEEN_PATTERN = /no commits between/i;
+/** Strict positive numeric suffix of a normal `https://…/pull/<n>` URL, else `null`. */
+function extractPrNumberFromCreateOutput(stdout) {
+    const match = stdout.trim().match(/\/pull\/(\d+)\s*$/);
+    if (!match)
+        return null;
+    const n = Number(match[1]);
+    return Number.isInteger(n) && n > 0 ? n : null;
+}
+async function createDraftPr(gh, epicKey, epicBranch, baseBranch, command, cwd) {
+    const title = buildEpicIntegrationPullRequestTitle(epicKey);
+    const body = buildEpicIntegrationPullRequestBody(epicKey, command);
+    const args = [
+        "pr",
+        "create",
+        "--draft",
+        "--base",
+        baseBranch,
+        "--head",
+        epicBranch,
+        "--title",
+        title,
+        "--body",
+        body,
+    ];
+    let result;
+    try {
+        result = await gh(args, { cwd, timeoutMs: EPIC_INTEGRATION_PR_WRITE_TIMEOUT_MS });
+    }
+    catch {
+        return { kind: "create_failed" };
+    }
+    if (result.exitCode === 0) {
+        return { kind: "created", numberHint: extractPrNumberFromCreateOutput(result.stdout) };
+    }
+    const combined = `${result.stdout}\n${result.stderr}`;
+    if (NO_COMMITS_BETWEEN_PATTERN.test(combined)) {
+        return { kind: "no_commits" };
+    }
+    return { kind: "create_failed" };
+}
+async function maybeMakeReady(gh, prNumber, isDraft, requestReady, cwd) {
+    if (!requestReady)
+        return "not_requested";
+    if (prNumber === null)
+        return "ready_failed";
+    if (!isDraft)
+        return "already_ready";
+    try {
+        const result = await gh(["pr", "ready", String(prNumber)], {
+            cwd,
+            timeoutMs: EPIC_INTEGRATION_PR_WRITE_TIMEOUT_MS,
+        });
+        return result.exitCode === 0 ? "made_ready" : "ready_failed";
+    }
+    catch {
+        return "ready_failed";
+    }
+}
+async function ensureEpicIntegrationPullRequestInner(options) {
+    const { epicKey, epicBranch, baseBranch, command, gh, cwd, requestReady } = options;
+    const probe = await probeMatchingOpenPr(gh, epicBranch, baseBranch, cwd);
+    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);
+        return { kind: "already_open", reason: "already_open", prNumber: probe.number, readiness };
+    }
+    // Confirmed absent: create.
+    const created = await createDraftPr(gh, epicKey, epicBranch, baseBranch, command, cwd);
+    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 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);
+        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);
+    if (race.kind === "found") {
+        const readiness = await maybeMakeReady(gh, race.number, race.isDraft, requestReady, cwd);
+        return { kind: "already_open", reason: "already_open", prNumber: race.number, readiness };
+    }
+    return { kind: "unavailable", reason: "create_unavailable" };
+}
+/**
+ * Ensure a matching draft epic-integration pull request exists. Idempotent and
+ * never throws or rejects — every internal failure, including an injected
+ * runner throwing, resolves to `{ kind: "unavailable", ... }`.
+ */
+export async function ensureEpicIntegrationPullRequest(options) {
+    try {
+        return await ensureEpicIntegrationPullRequestInner(options);
+    }
+    catch {
+        return { kind: "unavailable", reason: "probe_inconclusive" };
+    }
+}
+/**
+ * Build the production `gh` runner. Uses `execFile` (never a shell, never
+ * interpolated argv), ignores stdin, captures stdout/stderr, and bounds both
+ * the timeout and the output buffer. Every process-level failure (missing
+ * binary, timeout, spawn error) resolves a non-zero/timed-out result rather
+ * than rejecting.
+ */
+export function createProductionEpicIntegrationGhRunner(execFileImpl = nodeExecFile) {
+    return (args, options) => new Promise((resolve) => {
+        execFileImpl("gh", args, {
+            cwd: options.cwd,
+            timeout: options.timeoutMs,
+            maxBuffer: 4 * 1024 * 1024,
+            encoding: "utf-8",
+            shell: false,
+            stdio: ["ignore", "pipe", "pipe"],
+        }, (error, stdout, stderr) => {
+            if (error) {
+                const timedOut = error.killed === true;
+                const code = typeof error.code === "number" ? error.code : null;
+                resolve({ exitCode: code, stdout: stdout ?? "", stderr: stderr ?? "", timedOut });
+                return;
+            }
+            resolve({ exitCode: 0, stdout: stdout ?? "", stderr: stderr ?? "", timedOut: false });
+        });
+    });
+}

package/build/executor/job-runner.js

@@ -392,7 +392,7 @@ async function checkAdapterMcpAdvisoryForPreparedWorktree(worktreePath, deps, ad
  * `controls.signal` (overall-timeout abort) is threaded into local merge deps
  * without changing the local `gh` credential model.
  */
-export async function defaultRunMergeForClaimed(job, deps, _options, controls) {
+export async function defaultRunMergeForClaimed(job, deps, options, controls) {
     const accessResult = await buildConductorMergeAccessForExecutorJob({
         env: deps.env,
         cwd: deps.cwd,
@@ -419,6 +419,12 @@ export async function defaultRunMergeForClaimed(job, deps, _options, controls) {
         // Thread the overall-timeout abort signal into local merge deps WITHOUT
         // changing the local `gh` credential model (the signal is not a credential).
         localMergeDeps: buildDefaultMergeLocalDeps(deps, controls?.signal),
+        // BAPI-951: the executor's own configured base — resolveExecutorJobBaseBranch
+        // (called inside runExecutorMergeJob) resolves the CHILD PR's base from the
+        // job's persisted run base, falling back to this value for a legacy job.
+        repositoryBaseBranch: options.baseBranch,
+        epicIntegrationAdvisoryLog: deps.errorLog,
+        cwd: deps.cwd,
     });
 }
 /** An in-memory owned process for the no-op `smoke` acceptance job. */

package/build/executor/merge-job.js

@@ -23,7 +23,11 @@
  */
 import { makeLocalMergeExecutor, resolveLocalMergeMethod, } from "../conductor/local-merge.js";
 import { resolveConductorBridgeApiAccess, } from "../conductor/bridge-api-client.js";
+import { createProductionEpicIntegrationGhRunner, ensureEpicIntegrationPullRequest, formatEpicIntegrationPullRequestOutcome, } from "../epic-integration-pr.js";
 import { secretFreeErrorMessage } from "./job-errors.js";
+import { resolveExecutorJobBaseBranch } from "./base-branch.js";
+/** `epic/<KEY>` prefix a child PR's base branch carries under BAPI-949/BAPI-950. */
+const EPIC_BRANCH_PREFIX = "epic/";
 function positiveIntOrNull(value) {
     return typeof value === "number" && Number.isInteger(value) && value > 0 ? value : null;
 }
@@ -173,6 +177,43 @@ export function buildMergeJobFailure(response) {
         classification: "crashed",
     };
 }
+/**
+ * Post-merge draft epic-integration-PR retry (BAPI-951). Invoked ONLY after a
+ * successful ticket-bound merge whose child PR based on `epic/<EPIC>` — never
+ * for a `main`/other-based merge, and never for any failed merge. Wrapped in
+ * its own try/catch (the shared helper is already non-throwing, but this
+ * guards against a future/injected implementation replacing an already-decided
+ * merge outcome). NEVER changes the returned result, the `error_kind`, or the
+ * `/complete` payload — only emits a sanitized advisory line.
+ */
+async function tryEnsurePostMergeEpicIntegrationPr(job, seams) {
+    if (seams.repositoryBaseBranch === undefined)
+        return;
+    try {
+        const baseResolution = resolveExecutorJobBaseBranch(job, seams.repositoryBaseBranch);
+        if (!baseResolution.ok)
+            return;
+        const childBaseBranch = baseResolution.baseBranch;
+        if (!childBaseBranch.startsWith(EPIC_BRANCH_PREFIX))
+            return;
+        const epicKey = childBaseBranch.slice(EPIC_BRANCH_PREFIX.length);
+        if (epicKey.length === 0)
+            return;
+        const gh = seams.epicIntegrationGh ?? createProductionEpicIntegrationGhRunner();
+        const outcome = await ensureEpicIntegrationPullRequest({
+            epicKey,
+            epicBranch: childBaseBranch,
+            baseBranch: seams.repositoryBaseBranch,
+            command: "executor merge",
+            gh,
+            cwd: seams.cwd,
+        });
+        seams.epicIntegrationAdvisoryLog?.(`epic integration pr: ${JSON.stringify(formatEpicIntegrationPullRequestOutcome(outcome))}`);
+    }
+    catch {
+        // Advisory-only: never allowed to affect the already-decided merge outcome.
+    }
+}
 /**
  * Run the deterministic merge. NEVER ensures/recreates a worktree and NEVER
  * spawns a worker. Returns a completion result on a succeeded merge, else a
@@ -213,7 +254,11 @@ export async function runExecutorMergeJob(job, seams) {
         };
     }
     if (response.status === "succeeded") {
-        return { ok: true, result: buildMergeJobResult(response, fields) };
+        // Build the successful outcome COMPLETELY first — enrichment can only ever
+        // add an advisory log line, never alter what is returned.
+        const result = buildMergeJobResult(response, fields);
+        await tryEnsurePostMergeEpicIntegrationPr(job, seams);
+        return { ok: true, result };
     }
     return { ok: false, failure: buildMergeJobFailure(response) };
 }