@bridge_gpt/mcp-server 0.2.66 → 0.2.68

package/build/executor/integration-job.js

@@ -14,7 +14,12 @@
  *   epic branch through the provider's merge API. No checkout, no force.
  * * `mark_ready` — finds the ONE open pull request from the epic branch to the
  *   base (creating it only after conclusive absence), confirms its head is the
- *   expected epic head, and takes it out of draft.
+ *   expected epic head, and takes it out of draft. BAPI-1399: first it lists the
+ *   workaround folder `.bridge/epic-workarounds/` (the canonical path, imported
+ *   from `../epic-workarounds-path.ts`) at the expected epic head. While the folder is
+ *   present it only finds or creates the draft and reports `already_satisfied`
+ *   with `detail_code: "workarounds_present"`, so a stale coordinator
+ *   observation can never take the pull request out of draft.
  * * `correct` — runs ONE worker through the executor's existing locked spawn
  *   path under a driver that prepares the epic branch, verifies the worker's
  *   edits, makes the one commit, and performs the one push. The worker has no
@@ -46,7 +51,8 @@
  * and this module chooses no next ticket and no gate.
  */
 import { buildLocalMergeChildEnv, resolveLocalMergeCredential, sanitizeLocalMergeOutput, } from "../conductor/local-merge.js";
-import { createProductionEpicIntegrationGhRunner, ensureEpicIntegrationPullRequest, } from "../epic-integration-pr.js";
+import { EPIC_INTEGRATION_PR_READ_TIMEOUT_MS, createProductionEpicIntegrationGhRunner, ensureEpicIntegrationPullRequest, } from "../epic-integration-pr.js";
+import { EPIC_WORKAROUNDS_DIR_PATH } from "../epic-workarounds-path.js";
 import { INTEGRATION_ACTION_OPERATIONS, INTEGRATION_ACTION_OUTCOMES, INTEGRATION_ACTION_PROTOCOL_VERSION, } from "./types.js";
 /** The route prefix, mirrored from `api/routes/__init__.py`. */
 export const INTEGRATION_ACTION_ROUTE_PREFIX = "/epic-integration-actions";
@@ -386,20 +392,128 @@ function mapPullRequestOutcome(outcome) {
             return { outcome: "indeterminate", detail_code: safeDetail(outcome.reason) };
     }
 }
-async function performMarkReady(action, deps, env, seams) {
+// ---------------------------------------------------------------------------
+// BAPI-1399: the workaround folder re-check
+// ---------------------------------------------------------------------------
+/** The `detail_code` a held `mark_ready` reports on its `already_satisfied` outcome. */
+export const WORKAROUNDS_PRESENT_DETAIL_CODE = "workarounds_present";
+/**
+ * Classify one contents-API answer for `.bridge/epic-workarounds/`. Pure, and
+ * the twin of `classify_workaround_listing` in
+ * `api/library/github/github_webhooks_lib.py`; both suites read the shared
+ * parity vectors. `absent` needs a 404 AND proof that the repository and the
+ * epic head were readable with the same credential; anything the reader cannot
+ * establish — an unproven 404, any other status, no status, an empty array, an
+ * object, or entries that are not directory records — is `failed`.
+ */
+export function classifyWorkaroundListing(status, body, accessProven) {
+    if (status === 404)
+        return accessProven === true ? "absent" : "failed";
+    if (status !== 200)
+        return "failed";
+    if (!Array.isArray(body) || body.length === 0)
+        return "failed";
+    for (const entry of body) {
+        if (typeof entry !== "object" || entry === null || Array.isArray(entry))
+            return "failed";
+        const name = entry.name;
+        if (typeof name !== "string" || name.length === 0)
+            return "failed";
+    }
+    return "present";
+}
+/**
+ * List the workaround folder at the expected epic head through the restricted
+ * credentialed `gh` environment, with a bounded timeout. `accessProven` is true
+ * only when the caller read the epic head with this same credential in this
+ * attempt. Never throws; a failure is `failed`, never absence.
+ */
+async function listEpicWorkarounds(deps, credential, env, repository, expectedEpicHeadSha, accessProven) {
+    if (!PROVIDER_REPOSITORY_RE.test(repository) || !SHA_RE.test(expectedEpicHeadSha))
+        return "failed";
+    const r = await runCredentialed(deps, credential, env, "gh", [
+        "api", "--include",
+        `repos/${repository}/contents/${EPIC_WORKAROUNDS_DIR_PATH}?ref=${expectedEpicHeadSha}`,
+    ], { timeoutMs: READ_TIMEOUT_MS });
+    const status = parseGhHttpStatus(r.stdout, r.stderr);
+    if (status === 200 && r.exitCode !== 0)
+        return "failed";
+    return classifyWorkaroundListing(status, status === 200 ? parseIncludedBody(r.stdout) : null, accessProven);
+}
+/**
+ * Read one pull request's draft flag, branches, and head, bounded. The draft-only
+ * path of {@link ensureEpicIntegrationPullRequest} does not bind the head, so the
+ * held path proves the binding itself before it reports a hold. `null` when the
+ * read fails or the answer is not well formed.
+ */
+async function readPullRequestBinding(gh, prNumber, repository, cwd) {
+    try {
+        const r = await gh([
+            "pr", "view", String(prNumber), "--repo", repository,
+            "--json", "isDraft,headRefName,baseRefName,headRefOid",
+        ], { cwd, timeoutMs: EPIC_INTEGRATION_PR_READ_TIMEOUT_MS });
+        if (r.exitCode !== 0)
+            return null;
+        const parsed = JSON.parse(r.stdout);
+        if (typeof parsed !== "object" || parsed === null)
+            return null;
+        const { isDraft, headRefName, baseRefName, headRefOid } = parsed;
+        if (typeof isDraft !== "boolean" || typeof headRefName !== "string" || typeof baseRefName !== "string") {
+            return null;
+        }
+        const sha = typeof headRefOid === "string" ? headRefOid.toLowerCase() : "";
+        return { isDraft, headRefName, baseRefName, headSha: SHA_RE.test(sha) ? sha : null };
+    }
+    catch {
+        return null;
+    }
+}
+async function performMarkReady(action, deps, credential, env, seams) {
     const createGh = seams.createGhRunner ?? ((e) => createProductionEpicIntegrationGhRunner(undefined, e));
-    const outcome = await ensureEpicIntegrationPullRequest({
+    const gh = createGh(env);
+    const ensure = (requestReady) => ensureEpicIntegrationPullRequest({
         epicKey: action.epic_key,
         epicBranch: action.epic_branch,
         baseBranch: action.base_branch,
         command: "executor integration",
-        gh: createGh(env),
+        gh,
         cwd: deps.cwd,
-        requestReady: true,
+        requestReady,
         expectedHeadSha: action.expected_epic_head_sha,
         repo: action.provider_repository,
     });
-    return mapPullRequestOutcome(outcome);
+    // The caller read the live epic head with this same credential immediately
+    // before this call, so a 404 here can only mean the folder is absent.
+    const listing = await listEpicWorkarounds(deps, credential, env, action.provider_repository, action.expected_epic_head_sha, true);
+    if (listing === "failed") {
+        // Unreadable is never absence: report indeterminate, which spends one
+        // reconciliation probe exactly as any other unreadable observation does.
+        return { outcome: "indeterminate", detail_code: "probe_inconclusive" };
+    }
+    if (listing === "absent")
+        return mapPullRequestOutcome(await ensure(true));
+    // Present: find or create the draft and leave it a draft. `not_requested` is
+    // never passed through `mapPullRequestOutcome`, which would read it as failed.
+    const outcome = await ensure(false);
+    if (outcome.kind !== "already_open" && outcome.kind !== "created") {
+        return mapPullRequestOutcome(outcome);
+    }
+    if (outcome.prNumber === null)
+        return { outcome: "indeterminate", detail_code: "probe_inconclusive" };
+    const pr = outcome.prNumber;
+    const binding = await readPullRequestBinding(gh, pr, action.provider_repository, deps.cwd);
+    if (binding === null)
+        return { outcome: "indeterminate", pr_number: pr, detail_code: "probe_inconclusive" };
+    if (binding.headRefName !== action.epic_branch || binding.baseRefName !== action.base_branch) {
+        return { outcome: "pr_ambiguous", pr_number: pr, detail_code: "probe_ambiguous" };
+    }
+    if (binding.headSha !== action.expected_epic_head_sha) {
+        return { outcome: "head_drift", pr_number: pr, detail_code: "pr_head_moved" };
+    }
+    // A non-draft PR is never claimed as held: it is already ready, as today.
+    if (!binding.isDraft)
+        return { outcome: "already_satisfied", pr_number: pr };
+    return { outcome: "already_satisfied", pr_number: pr, detail_code: WORKAROUNDS_PRESENT_DETAIL_CODE };
 }
 /**
  * Perform one claimed integration action and report its facts.
@@ -469,7 +583,7 @@ export async function runIntegrationAction(action, client, deps, seams = {}) {
                 report = await performSyncBase(action, deps, credential, env, reads);
             }
             else if (action.operation === "mark_ready") {
-                report = await performMarkReady(action, deps, env, seams);
+                report = await performMarkReady(action, deps, credential, env, seams);
             }
             else if (seams.runCorrection === undefined) {
                 report = { outcome: "failed", detail_code: "correction_unsupported" };

package/build/executor/job-errors.js

@@ -39,8 +39,13 @@
  *    origin, but not this worker's latest commit. Distinct from
  *    `WorkerFinalizationMissingRemoteBranchAndPr` (which covers "no evidence any
  *    work reached origin") because this case has positive proof of recoverable
- *    state: an operator can resume/finalize from the existing branch rather than
+ *    state: an operator can preserve the newer local worktree commit rather than
  *    re-running from scratch; see `worker-finalization.ts`.
+ *  - `WorkerFinalizationOriginUnverifiable` — an implementation-style job
+ *    (BAPI-1357) exited cleanly, but the origin branch lookup could not be
+ *    trusted (a throw, an expired bound, an unexpected exit, or unusable output).
+ *    The branch was NOT observed absent, so this is distinct from
+ *    `WorkerFinalizationMissingRemoteBranchAndPr`; see `worker-finalization.ts`.
  *  - `ContractError.WorkerConfigIsolation` — a per-job isolated Claude config
  *    directory could not be established (unsupported platform, unsupported auth
  *    layout, unseedable directory, or a missing required MCP registration), so
@@ -141,6 +146,31 @@ export const WorkerFinalizationSavedButUnfinalized = "WorkerFinalizationSavedBut
  * verdict is `unknown`, never `unmet` and never `ok`.
  */
 export const WorkerFinalizationPublicationUnverified = "WorkerFinalizationPublicationUnverified";
+/**
+ * BAPI-1357: the origin branch lookup could not be TRUSTED — the command threw,
+ * its call bound expired, it exited with anything other than "found" (0) or "no
+ * matching ref" (2), or it exited 0 without a usable SHA for the exact ref. The
+ * branch was not observed absent, so this is distinct from
+ * `WorkerFinalizationMissingRemoteBranchAndPr`, which is reserved for an
+ * observed absence. The process itself exited clean. Nothing command-derived
+ * (stderr, error text, host, credentials) is carried by this kind.
+ */
+export const WorkerFinalizationOriginUnverifiable = "WorkerFinalizationOriginUnverifiable";
+/**
+ * BAPI-1364: a LEGACY (non-covered) worker exited cleanly while the structured
+ * stream still showed a required background command with no terminal
+ * notification. The headless session had no later turn, so the command's result
+ * could never reach the worker. Carries only {@link WORKER_ENDED_WITH_PENDING_BACKGROUND_WORK_MESSAGE};
+ * no event text, command, path, or output.
+ */
+export const WorkerEndedWithPendingBackgroundWork = "WorkerEndedWithPendingBackgroundWork";
+/**
+ * BAPI-1392: a recognized Bridge command's packaged recipe could not be delivered
+ * to the worker. Refused before spawn rather than silently running the committed
+ * copy, which may be stale. The message carries a fixed `reason=<code>` token and
+ * a command name only — never prompt text, arguments, or recipe bytes.
+ */
+export const PackagedRecipeUndeliverable = "ContractError.PackagedRecipeUndeliverable";
 export const WorkerConfigIsolation = "ContractError.WorkerConfigIsolation";
 export const PreSpawnVerification = "ContractError.PreSpawnVerification";
 export const BridgeCredentialUnavailable = "ContractError.BridgeCredentialUnavailable";
@@ -282,6 +312,8 @@ export function formatMcpSurfaceMismatch(expected, observed) {
         "Check that the installed Claude CLI supports --strict-mcp-config and that nothing adds MCP " +
         "servers outside the worktree registration.");
 }
+/** The fixed message posted with {@link WorkerEndedWithPendingBackgroundWork}. */
+export const WORKER_ENDED_WITH_PENDING_BACKGROUND_WORK_MESSAGE = "the worker ended its session while a background command was still running";
 /**
  * The fixed message posted with {@link WorkerStartupFatal}.
  *