@bridge_gpt/mcp-server 0.2.20 → 0.2.23

package/build/executor/base-branch.js

@@ -0,0 +1,50 @@
+/**
+ * Per-job base-branch resolution (BAPI-586).
+ *
+ * The executor has one global `--base-branch` (`ExecutorOptions.baseBranch`,
+ * default `main`), but Epic Conductor runs can be based on a custom branch
+ * (e.g. `develop`, `release/2026.07`) and multi-repository executors may serve
+ * repos with different bases. This helper makes the persisted RUN base
+ * (`job.payload.base_branch`) authoritative for each job while keeping the CLI
+ * value as a legacy fallback.
+ *
+ * A malformed present value fails CLOSED (contract error) rather than silently
+ * falling back — a wrong base is exactly the BAPI-586 defect. An OMITTED value
+ * (legacy / older-Conductor jobs) degrades gracefully to the CLI base.
+ */
+import { validateBranchName } from "../base-ref.js";
+/**
+ * Resolve the effective logical base branch for one executor job.
+ *
+ * - `payload.base_branch` ABSENT (`undefined`) → legacy job → `fallbackBaseBranch`.
+ * - present and a valid branch name → authoritative for this job, even when it
+ *   differs from the executor-wide `--base-branch`.
+ * - present but malformed (`null`, non-string, empty/whitespace, `..`, `.lock`,
+ *   control chars, leading `-`) → contract failure. The diagnostic names the
+ *   base-branch contract WITHOUT echoing arbitrary payload contents.
+ */
+export function resolveExecutorJobBaseBranch(job, fallbackBaseBranch) {
+    const payload = job.payload;
+    const raw = payload && typeof payload === "object"
+        ? payload.base_branch
+        : undefined;
+    // Omitted field: legacy / older-Conductor job → CLI fallback (backward compat).
+    if (raw === undefined) {
+        return { ok: true, baseBranch: fallbackBaseBranch };
+    }
+    // Present but not a string (null, number, object, …): fail closed, no echo.
+    if (typeof raw !== "string") {
+        return {
+            ok: false,
+            error: "job payload base_branch is present but is not a string branch name.",
+        };
+    }
+    const validationError = validateBranchName(raw);
+    if (validationError) {
+        return {
+            ok: false,
+            error: `job payload base_branch is not a valid branch name: ${validationError}`,
+        };
+    }
+    return { ok: true, baseBranch: raw };
+}

package/build/executor/env.js

@@ -8,6 +8,7 @@
  * keys — it never copies arbitrary `process.env`, so credentials/tokens/headers
  * cannot leak into the spawned `claude` process.
  */
+import { PR_BASE_BRANCH_ENV_VAR } from "../pr-base-contract.js";
 /** Non-secret operational keys forwarded to the worker when present. */
 const ALLOWED_ENV_KEYS = [
     "PATH",
@@ -63,8 +64,15 @@ export function isExecutorEnvKeyAllowed(key) {
  * anyway, and the delay was observed causing a worker to background the push and
  * exit before it landed. `BAPI_CONDUCTOR_*` identity keys remain intentionally
  * absent from the worker env (TDD §7) — this literal does not change that.
+ *
+ * BAPI-586: when `effectiveBaseBranch` is provided (the validated run base for
+ * this job), it is injected as `BAPI_BASE_BRANCH` so the worker can run
+ * `gh pr create --base "$BAPI_BASE_BRANCH"` deterministically. It is set from the
+ * EXPLICIT job value, NOT copied from `parentEnv` (`BAPI_BASE_BRANCH` is not in
+ * the allowlist), so any inherited value cannot override the run base and no
+ * unrelated `BAPI_*` / secret value can leak in via this key.
  */
-export function buildExecutorWorkerEnv(parentEnv) {
+export function buildExecutorWorkerEnv(parentEnv, effectiveBaseBranch) {
     const env = {};
     for (const key of ALLOWED_ENV_KEYS) {
         if (!isExecutorEnvKeyAllowed(key))
@@ -75,5 +83,8 @@ export function buildExecutorWorkerEnv(parentEnv) {
         }
     }
     env.BRIDGE_SKIP_PREPUSH = "1";
+    if (typeof effectiveBaseBranch === "string" && effectiveBaseBranch.length > 0) {
+        env[PR_BASE_BRANCH_ENV_VAR] = effectiveBaseBranch;
+    }
     return env;
 }

package/build/executor/job-errors.js

@@ -3,6 +3,7 @@ export const MissingVerdictArtifact = "MissingVerdictArtifact";
 export const WorktreeLostBeforePush = "WorktreeLostBeforePush";
 export const BranchMismatch = "BranchMismatch";
 export const WorkerFinalizationMissingRemoteBranchAndPr = "WorkerFinalizationMissingRemoteBranchAndPr";
+export const WorkerFinalizationPrBaseMismatch = "WorkerFinalizationPrBaseMismatch";
 /** Bound a failure message so no unbounded/secret-bearing text is posted. */
 const ERROR_MESSAGE_MAX_CHARS = 300;
 /**

package/build/executor/job-runner.js

@@ -30,9 +30,11 @@ import { isVerdictJobType, readVerdictArtifact } from "./verdict-artifact.js";
 import { createWorkerLogTee, closeWorkerLogTee, teeAsyncIterable, } from "./worker-log.js";
 import { registerExecutorJobLog, markExecutorJobLogFinished, } from "./job-log-registry.js";
 import { executorViewerTabsEnabled, openExecutorViewerTab } from "./viewer-tabs.js";
-import { isRecoveryJobType, isSpawnJobType } from "./job-types.js";
+import { isImplementationStyleJobType, isRecoveryJobType, isSpawnJobType } from "./job-types.js";
+import { resolveExecutorJobBaseBranch } from "./base-branch.js";
 import { validateWorkerFinalization } from "./worker-finalization.js";
 import { ensureExecutorWorktree } from "./worktree.js";
+import { buildPrBaseContractLaunchInstruction } from "../pr-base-contract.js";
 import { buildClaudeExecutorArgv, CLAUDE_EXECUTABLE, resolveExecutorModelAlias, resolveExecutorPrompt, } from "./worker-command.js";
 import { collectGitTelemetry } from "./observation.js";
 /** Default runtime for the no-op smoke process (ms). */
@@ -553,11 +555,37 @@ async function prepareSpawn(job, httpClient, options, deps, seams) {
     }
 }
 async function runSpawnJob(job, httpClient, options, deps, ownership, observation, seams) {
+    // --- Per-job base branch (BAPI-586) ----------------------------------
+    // Resolve the effective logical base BEFORE any side effect: the persisted
+    // run base (`payload.base_branch`) is authoritative, falling back to the
+    // executor CLI base for legacy jobs. A present-but-malformed value fails
+    // CLOSED with `ContractError.BaseBranch` and never spawns. The resulting
+    // job-scoped options carry that base through worktree seeding, prompt
+    // rendering, deny layer, telemetry, env, and finalization so they cannot
+    // disagree about the base.
+    const baseResolution = resolveExecutorJobBaseBranch(job, options.baseBranch);
+    if (!baseResolution.ok) {
+        await httpClient.fail(job, {
+            error_kind: "ContractError.BaseBranch",
+            error_message: baseResolution.error,
+            classification: "crashed",
+        });
+        return { status: "failed", reason: "base_branch_contract" };
+    }
+    const effectiveBaseBranch = baseResolution.baseBranch;
+    const jobOptions = { ...options, baseBranch: effectiveBaseBranch };
     // --- Worktree + prompt (resume pre-spawn protocol or standard) -------
-    const prep = await prepareSpawn(job, httpClient, options, deps, seams);
+    const prep = await prepareSpawn(job, httpClient, jobOptions, deps, seams);
     if (!prep.ok)
         return prep.result;
-    const { worktreePath, branch, prompt } = prep;
+    const { worktreePath, branch } = prep;
+    // BAPI-586: PR-producing spawn jobs (implement/resume/remediate/ci_fix/rebase)
+    // are told to open the PR against the injected run base. Verdict-only
+    // `spec_review` produces no PR, so it is excluded from the instruction while
+    // still using the pinned base for its fresh worktree.
+    const prompt = isImplementationStyleJobType(job.job_type)
+        ? `${prep.prompt} ${buildPrBaseContractLaunchInstruction()}`
+        : prep.prompt;
     // --- Timeout contract ------------------------------------------------
     const timeout = resolveJobTimeoutSeconds(job, options.defaultJobTimeoutSeconds);
     if (!timeout.ok) {
@@ -569,7 +597,7 @@ async function runSpawnJob(job, httpClient, options, deps, ownership, observatio
         return { status: "failed", reason: "timeout_contract" };
     }
     // --- Deny layer (fail-open) ------------------------------------------
-    const deny = await provisionExecutorDenyLayer(worktreePath, { baseBranch: options.baseBranch }, {
+    const deny = await provisionExecutorDenyLayer(worktreePath, { baseBranch: effectiveBaseBranch }, {
         readFile: deps.readFile,
         writeFile: deps.writeFile,
         mkdir: deps.mkdir,
@@ -643,7 +671,9 @@ async function runSpawnJob(job, httpClient, options, deps, ownership, observatio
     // --- Spawn -----------------------------------------------------------
     const alias = resolveExecutorModelAlias(job.payload);
     const argv = buildClaudeExecutorArgv(prompt, alias);
-    const env = buildExecutorWorkerEnv(deps.env);
+    // BAPI-586: inject the validated run base as BAPI_BASE_BRANCH so the worker
+    // can target it via `gh pr create --base "$BAPI_BASE_BRANCH"`.
+    const env = buildExecutorWorkerEnv(deps.env, effectiveBaseBranch);
     let proc;
     try {
         proc = deps.spawnProcess(CLAUDE_EXECUTABLE, argv, { cwd: worktreePath, env });
@@ -666,11 +696,11 @@ async function runSpawnJob(job, httpClient, options, deps, ownership, observatio
             stderr: proc.stderr ? teeAsyncIterable(proc.stderr, tee, "stderr") : null,
         }
         : proc;
-    const collectTelemetry = () => collectGitTelemetry({ runCommand: deps.runCommand, now: deps.now }, worktreePath, options.baseBranch);
+    const collectTelemetry = () => collectGitTelemetry({ runCommand: deps.runCommand, now: deps.now }, worktreePath, effectiveBaseBranch);
     const procResult = await superviseProcess({
         job,
         httpClient,
-        options,
+        options: jobOptions,
         deps,
         ownership,
         observation,
@@ -765,6 +795,7 @@ async function runSpawnJob(job, httpClient, options, deps, ownership, observatio
             result,
             runCommand: deps.runCommand,
             headSha: git.last_commit_sha,
+            expectedBaseBranch: effectiveBaseBranch,
         });
         if (!finalization.ok) {
             await finalizeRegistry();

package/build/executor/test-clock.js

@@ -28,7 +28,12 @@ export class VirtualClock {
     }
 }
 async function flushMicrotasks() {
-    for (let i = 0; i < 12; i++)
+    // BAPI-586: the fresh executor worktree path now awaits a `git fetch` +
+    // `git rev-parse` (base pin) and a post-create head verification BEFORE the
+    // worker spawn, adding several microtask turns. Drain generously so a
+    // `tickUntil` flush still reaches the spawn/exit in one pass (draining an
+    // already-empty queue is a harmless no-op).
+    for (let i = 0; i < 64; i++)
         await Promise.resolve();
 }
 /** A controllable fake owned process for `implement` spawn tests. */

package/build/executor/worker-finalization.js

@@ -23,7 +23,7 @@
  * branch tip SHA against the worker's own HEAD commit (`headSha`, from git
  * telemetry) whenever that comparison is available.
  */
-import { secretFreeErrorMessage, WorkerFinalizationMissingRemoteBranchAndPr } from "./job-errors.js";
+import { secretFreeErrorMessage, WorkerFinalizationMissingRemoteBranchAndPr, WorkerFinalizationPrBaseMismatch, } from "./job-errors.js";
 import { isImplementationStyleJobType } from "./job-types.js";
 /** Bounded settling re-check defaults for the authoritative origin-tip lookup. */
 const DEFAULT_ORIGIN_FINALIZATION_ATTEMPTS = 3;
@@ -111,6 +111,66 @@ async function resolveOriginBranchShaForFinalization(runCommand, worktreePath, b
     }
     return remoteSha;
 }
+/**
+ * BAPI-586: resolve the base branch of the PR for `branch` via `gh pr view`.
+ * Fail-open on any unavailability (gh missing, non-zero exit, unparseable JSON)
+ * → `{ found: false }`, so a wrong-base guard never blocks a job on transport
+ * failure; the reconciliation observation (epic-runtime) is the second layer.
+ * When a PR IS visible, `baseRef` is the trimmed `baseRefName`, or null if that
+ * field is absent/non-string (which the caller treats as a fail-closed mismatch —
+ * missing base evidence is never a match). Never copies raw stderr.
+ */
+async function resolvePrBaseRef(runCommand, worktreePath, branch) {
+    const args = ["pr", "view"];
+    if (branch)
+        args.push(branch);
+    args.push("--json", "number,baseRefName");
+    let result;
+    try {
+        result = await runCommand("gh", args, { cwd: worktreePath });
+    }
+    catch {
+        return { found: false, baseRef: null };
+    }
+    if (result.exitCode !== 0)
+        return { found: false, baseRef: null };
+    let parsed;
+    try {
+        parsed = JSON.parse(result.stdout);
+    }
+    catch {
+        return { found: false, baseRef: null };
+    }
+    if (!parsed || typeof parsed !== "object")
+        return { found: false, baseRef: null };
+    const obj = parsed;
+    const prNumber = typeof obj.number === "number" ? obj.number : undefined;
+    const rawBase = obj.baseRefName;
+    const baseRef = typeof rawBase === "string" && rawBase.trim().length > 0 ? rawBase.trim() : null;
+    return { found: true, prNumber, baseRef };
+}
+/**
+ * BAPI-586: bounded, secret-free failure for a PR that targets a branch other
+ * than the run base. Details are limited to ticket key, PR number, expected base,
+ * and actual base (all public identifiers). The operator guidance names cherry-pick
+ * rebuild as the remedy and explicitly warns against a GitHub-UI retarget (a branch
+ * built on a squash-merged dependency goes CONFLICTING when retargeted). This guard
+ * is OBSERVATIONAL: it performs no `gh pr edit`, reset, force-push, or branch
+ * reconstruction.
+ */
+function prBaseMismatchFailure(job, prNumber, expectedBase, actualBase) {
+    const label = job.ticket_key ? `${job.ticket_key} (job ${job.id})` : `job ${job.id}`;
+    const prLabel = typeof prNumber === "number" ? `PR #${prNumber}` : "its PR";
+    return {
+        error_kind: WorkerFinalizationPrBaseMismatch,
+        error_message: `${label} opened ${prLabel} against base '${actualBase}', but the run base is '${expectedBase}'. ` +
+            `A PR that does not target '${expectedBase}' never triggers code review and would strand the ticket. ` +
+            `Recovery: rebuild the feature branch from a fresh origin/${expectedBase} and cherry-pick only this ` +
+            `ticket's own commits, then force-push. Do NOT merely retarget the PR base in the GitHub UI — a branch ` +
+            `built on a squash-merged dependency goes CONFLICTING when retargeted.`,
+        classification: "crashed",
+    };
+}
 function missingBranchAndPrFailure(job, detail) {
     const label = job.ticket_key ? `${job.ticket_key} (job ${job.id})` : `job ${job.id}`;
     return {
@@ -129,6 +189,33 @@ export async function validateWorkerFinalization(input) {
     if (!isImplementationStyleJobType(job.job_type)) {
         return { ok: true };
     }
+    // BAPI-586: a wrong-base PR (opened against a dependency's feature branch or the
+    // repo default instead of the run base) never fires `claude-review.yml` and
+    // strands the ticket at `code_review`. When the run base is known, query the
+    // PR's `baseRefName` and fail loud on any mismatch BEFORE accepting the clean
+    // exit — even when a `pr_url` is present (a PR existing is not proof of a
+    // correct base). Fail-open when no PR is visible (gh unavailable / no PR):
+    // reconciliation is the backstop. A PR with absent/malformed base data is a
+    // fail-CLOSED mismatch — missing base evidence is never treated as a match.
+    const expectedBase = typeof input.expectedBaseBranch === "string" ? input.expectedBaseBranch.trim() : "";
+    if (expectedBase) {
+        const branchForPr = typeof branch === "string" ? branch.trim() : "";
+        const prBase = await resolvePrBaseRef(runCommand, worktreePath, branchForPr);
+        if (prBase.found) {
+            if (prBase.baseRef === null) {
+                return {
+                    ok: false,
+                    failure: prBaseMismatchFailure(job, prBase.prNumber, expectedBase, "(unresolved)"),
+                };
+            }
+            if (prBase.baseRef !== expectedBase) {
+                return {
+                    ok: false,
+                    failure: prBaseMismatchFailure(job, prBase.prNumber, expectedBase, prBase.baseRef),
+                };
+            }
+        }
+    }
     if (extractPrUrl(result)) {
         return { ok: true };
     }

package/build/executor/worktree.js

@@ -6,6 +6,7 @@
  * construction or Worktrunk JSON path parsing here. Per-job create failures are
  * returned as structured job failures (→ `/fail`), never thrown.
  */
+import { fetchAndResolveBaseSha } from "../base-ref.js";
 import { commandSucceeded } from "../start-tickets-prereqs.js";
 import { createWorktreeForTicket } from "../worktree-core.js";
 /**
@@ -95,7 +96,26 @@ export async function ensureExecutorWorktree(job, options, deps, policy = {}) {
         }
         return { ok: false, error: row.error ?? `worktree creation failed for branch '${branch}'` };
     }
-    const row = await createWorktreeForTicket(toWorktreeCoreDeps(deps), key, { [key]: branch }, options.worktrunkBinary, baseStartPoint, guardStaleWorktree);
+    // BAPI-586 (fresh dispatch): a fresh implementation-style job must start from
+    // the CURRENT remote base — never a stale local `main`, another local base
+    // branch, or a sibling/dependency feature branch. Fetch `origin/<base>` and
+    // pin its immutable SHA (serialized per repo by the shared helper so
+    // concurrent fresh jobs don't collide on git lock files), then:
+    //   - cut an absent branch directly from that SHA (Worktrunk `-b <sha>`),
+    //   - align a guard-approved pre-existing branch exactly to that SHA, and
+    //   - verify the created worktree head equals that SHA before spawning.
+    // If the refresh fails, fail CLOSED with a structured, secret-free error —
+    // continuing from a cached local base would silently omit a merged dependency
+    // and reproduce the BAPI-586 wrong-base strand.
+    const resolvedBase = await fetchAndResolveBaseSha(deps, options.baseBranch);
+    if (!resolvedBase.ok) {
+        return {
+            ok: false,
+            error: `failed to resolve remote base '${options.baseBranch}' for a fresh worktree: ${resolvedBase.error}`,
+        };
+    }
+    const baseSha = resolvedBase.base_sha;
+    const row = await createWorktreeForTicket(toWorktreeCoreDeps(deps), key, { [key]: branch }, options.worktrunkBinary, baseSha, guardStaleWorktree, { alignExistingBranchTo: baseSha, verifyHeadMatches: baseSha });
     if (row.status === "created" && typeof row.path === "string") {
         return { ok: true, worktreePath: row.path, branch };
     }