@bridge_gpt/mcp-server 0.2.41 → 0.2.43

package/build/conductor/local-merge.js

@@ -485,38 +485,42 @@ export function makeLocalMergeExecutor(options = {}, deps = {}) {
         }
         // 3. Revalidate required CI green for the EXACT expected head, waiting briefly
         //    for transient post-remediation CI to turn green before failing ci_not_green.
-        const ciWait = await waitForRequiredChecksGreen(pollCi, access, expectedSha, requiredChecks, ciWaitTimeoutMs, ciWaitPollIntervalMs, sleep, now, signal);
-        if (!ciWait.ok) {
-            // Any `ci_poll_*` reason (the legacy `ci_poll_failed` plus the distinct
-            // BAPI-577 kinds) is an AMBIGUOUS infrastructure read failure — a merge that
-            // GitHub already accepted could be masked by a flaky poll. Re-verify the
-            // merged state before reporting. ci_not_green and merge_aborted are
-            // deterministic (CI is red / the job was aborted); they never verify and
-            // never proceed to a provider merge.
-            if (isAmbiguousCiPollFailureReason(ciWait.reason)) {
+        //    Skipped under `skipCiWait` (BAPI-832), where the server's approval tail
+        //    revalidated these same checks for this same head moments ago.
+        if (!options.skipCiWait) {
+            const ciWait = await waitForRequiredChecksGreen(pollCi, access, expectedSha, requiredChecks, ciWaitTimeoutMs, ciWaitPollIntervalMs, sleep, now, signal);
+            if (!ciWait.ok) {
+                // Any `ci_poll_*` reason (the legacy `ci_poll_failed` plus the distinct
+                // BAPI-577 kinds) is an AMBIGUOUS infrastructure read failure — a merge that
+                // GitHub already accepted could be masked by a flaky poll. Re-verify the
+                // merged state before reporting. ci_not_green and merge_aborted are
+                // deterministic (CI is red / the job was aborted); they never verify and
+                // never proceed to a provider merge.
+                if (isAmbiguousCiPollFailureReason(ciWait.reason)) {
+                    const verified = await verifyMergedStateAfterAmbiguousFailure();
+                    if (verified)
+                        return verified;
+                }
+                return fail(ciWait.reason, ciWait.pollFailure);
+            }
+            // 3b. Re-read PR head/state after the CI wait — the head can drift, the PR can
+            //     close, or the merge can already have landed while we waited for CI.
+            const secondRead = await readPrMergeState(run, ghEnv, pr);
+            if (!secondRead.ok) {
                 const verified = await verifyMergedStateAfterAmbiguousFailure();
                 if (verified)
                     return verified;
+                return fail(secondRead.reason);
+            }
+            if (isMergedAtExpectedHead(secondRead.state, secondRead.headOid, expectedSha)) {
+                return buildAlreadyMergedResponse(request, baseDetails, secondRead.mergeCommitOid);
+            }
+            if (typeof secondRead.headOid !== "string" || secondRead.headOid.toLowerCase() !== expectedSha.toLowerCase()) {
+                return fail("head_drift");
+            }
+            if (typeof secondRead.state === "string" && secondRead.state.toUpperCase() !== "OPEN") {
+                return fail("pr_not_open");
             }
-            return fail(ciWait.reason, ciWait.pollFailure);
-        }
-        // 3b. Re-read PR head/state after the CI wait — the head can drift, the PR can
-        //     close, or the merge can already have landed while we waited for CI.
-        const secondRead = await readPrMergeState(run, ghEnv, pr);
-        if (!secondRead.ok) {
-            const verified = await verifyMergedStateAfterAmbiguousFailure();
-            if (verified)
-                return verified;
-            return fail(secondRead.reason);
-        }
-        if (isMergedAtExpectedHead(secondRead.state, secondRead.headOid, expectedSha)) {
-            return buildAlreadyMergedResponse(request, baseDetails, secondRead.mergeCommitOid);
-        }
-        if (typeof secondRead.headOid !== "string" || secondRead.headOid.toLowerCase() !== expectedSha.toLowerCase()) {
-            return fail("head_drift");
-        }
-        if (typeof secondRead.state === "string" && secondRead.state.toUpperCase() !== "OPEN") {
-            return fail("pr_not_open");
         }
         // 4. Provider merge. Final abort guard: if the overall timeout / ownership
         //    abandonment fired during the CI wait or the post-CI re-read, do NOT fire
@@ -619,3 +623,101 @@ function buildConflictResponse(request, baseDetails, expectedSha, mergeability)
         { type: "merge.conflict", status: "failed", reason, details: conflictDetails },
     ]);
 }
+/**
+ * Probe whether this host can merge with `gh` at all, BEFORE any merge is
+ * attempted.
+ *
+ * Without this the two operator-fixable failures are invisible: a missing `gh`
+ * and a logged-out `gh` both make `gh pr view` exit non-zero, which this module
+ * reports as `gh_pr_view_failed` — a reason that names no fix. Splitting them
+ * out is the difference between "run `gh auth login`" and "something went wrong
+ * reading the pull request".
+ *
+ * Deliberately async and built on the same `run` seam as the merge itself. The
+ * read-only equivalent in `conductor/doctor.ts` (`inspectLocalMerge`) probes
+ * synchronously, which is fine for a diagnostic command but would block the MCP
+ * server's event loop for up to its full timeout in the middle of a tool call.
+ * (This module's static contract forbids synchronous process execution outright,
+ * so the token itself cannot appear here — not even in a comment.)
+ */
+export async function preflightLocalGh(run, ghEnv) {
+    let version;
+    try {
+        version = await run("gh", ["--version"], ghEnv);
+    }
+    catch {
+        return { ok: false, reason: "local_gh_unavailable" };
+    }
+    if (version.status !== 0)
+        return { ok: false, reason: "local_gh_unavailable" };
+    let auth;
+    try {
+        auth = await run("gh", ["auth", "status"], ghEnv);
+    }
+    catch {
+        return { ok: false, reason: "local_gh_unauthenticated" };
+    }
+    if (auth.status !== 0)
+        return { ok: false, reason: "local_gh_unauthenticated" };
+    return { ok: true };
+}
+/**
+ * Execute a merge the server has ALREADY approved, using the operator's `gh`.
+ *
+ * This is the local half of BAPI-832's split: the server ran the whole
+ * deterministic decision tail (action key, lease, head-SHA drift guard, review
+ * gate, workflow-file guard, CI revalidation) and returned
+ * `approved_for_local_execution` because its GitHub App installation is
+ * `contents: read` and cannot perform the write. Only the write happens here.
+ *
+ * It reuses {@link makeLocalMergeExecutor} rather than reimplementing the merge,
+ * so the head-drift guard, the `--match-head-commit` binding, and the entire
+ * ambiguity-resolution ladder are the same proven code v2's `merge` job runs.
+ * `skipCiWait` is set because the server revalidated CI moments ago.
+ *
+ * This function grants no authority of its own. It must only ever be called with
+ * a request built from a live approval for that exact PR and head SHA.
+ */
+export async function runApprovedLocalMerge(request, options = {}, deps = {}) {
+    const ghEnv = {
+        ...deps.env,
+        GH_PROMPT_DISABLED: "1",
+        GH_NO_UPDATE_NOTIFIER: "1",
+    };
+    const rawRun = deps.runCommand ?? defaultRunCommand;
+    const run = (cmd, args, env) => Promise.resolve(rawRun(cmd, args, env, deps.signal));
+    const preflight = await preflightLocalGh(run, ghEnv);
+    if (!preflight.ok) {
+        return buildResponse(request, "failed", preflight.reason, false, [
+            {
+                type: "merge.failed",
+                status: "failed",
+                reason: preflight.reason,
+                details: {
+                    action_key: request.action_key,
+                    repo: request.repo_name,
+                    pr_number: request.pr_number,
+                    expected_head_sha: request.expected_head_sha,
+                    executor: "local",
+                },
+            },
+        ]);
+    }
+    const executor = makeLocalMergeExecutor({ method: options.method, skipCiWait: true }, deps);
+    // `access` is only ever used by the CI poll, which `skipCiWait` bypasses. The
+    // throwing stub makes that structural, not a comment: if a future edit ever
+    // reaches the poll from this path, it fails loudly in tests instead of
+    // silently polling with an unusable access record.
+    const unusedAccess = {
+        get baseUrl() {
+            throw new Error("runApprovedLocalMerge must not poll CI");
+        },
+        get apiKey() {
+            throw new Error("runApprovedLocalMerge must not poll CI");
+        },
+        get repoName() {
+            throw new Error("runApprovedLocalMerge must not poll CI");
+        },
+    };
+    return executor(unusedAccess, request);
+}

package/build/conductor/recovery-cli.js

@@ -0,0 +1,313 @@
+/**
+ * `conductor` operator recovery verbs (BAPI-872): `stop-run`, `abandon-run`,
+ * `unpark`, `adopt-current-head-and-unpark`.
+ *
+ * CLI-only by design — this is an explicit ticket non-goal, not an oversight:
+ * none of these four command names is ever registered as an MCP tool, tool
+ * description, or generated tool-schema input (`index-static.test.ts` guards
+ * this). They exist so an operator (or `plane down`, via
+ * `recovery-operations.ts`) can recover a stuck run or ticket WITHOUT
+ * hand-rolling an HTTP request — the exact thing setup-epic's old raw-PATCH
+ * guidance used to ask for.
+ *
+ * Every ticket command's `row_version` CAS handling is entirely internal to
+ * `recovery-operations.ts`. This surface never accepts, echoes, or asks the
+ * operator for a version counter — see {@link REJECTED_VERSION_FLAGS}.
+ */
+import { ConductorValidationError, toConductorErrorEnvelope } from "./errors.js";
+// ---------------------------------------------------------------------------
+// Flag parsing
+// ---------------------------------------------------------------------------
+const RUN_VALUE_FLAGS = new Set(["--epic-run-id"]);
+const TICKET_VALUE_FLAGS = new Set(["--epic-run-id", "--ticket-key"]);
+const RECOVERY_BOOL_FLAGS = new Set(["--json", "--help"]);
+/**
+ * Every spelling of an operator-supplied version counter this surface must
+ * refuse outright (BAPI-872) — row_version handling is internal to
+ * {@link module:./recovery-operations}, and no ticket command may accept one.
+ */
+const REJECTED_VERSION_FLAGS = new Set([
+    "--row-version",
+    "--expected-row-version",
+    "--row_version",
+    "--expected_row_version",
+]);
+/**
+ * Tokenize `--flag value` / `--flag=value` / boolean flags for the recovery
+ * verbs. A rejected version flag throws BEFORE its value (if any) is ever
+ * read, so the offending value is never echoed, normalized, or invited.
+ */
+function tokenizeRecoveryFlags(argv, valueFlags, boolFlags) {
+    const values = new Map();
+    const bools = new Set();
+    for (let i = 0; i < argv.length; i += 1) {
+        const token = argv[i];
+        if (token === "-h") {
+            bools.add("--help");
+            continue;
+        }
+        if (!token.startsWith("--")) {
+            throw new ConductorValidationError(`Unexpected argument "${token}".`);
+        }
+        const eq = token.indexOf("=");
+        const name = eq >= 0 ? token.slice(0, eq) : token;
+        if (REJECTED_VERSION_FLAGS.has(name)) {
+            throw new ConductorValidationError(`Flag "${name}" is not supported here — row-version handling is internal to ` +
+                "recovery and cannot be supplied by the operator. Omit it; recovery reads the " +
+                "current version itself.");
+        }
+        if (boolFlags.has(name)) {
+            bools.add(name);
+            continue;
+        }
+        if (!valueFlags.has(name)) {
+            throw new ConductorValidationError(`Unknown flag "${name}".`);
+        }
+        let value;
+        if (eq >= 0) {
+            value = token.slice(eq + 1);
+        }
+        else {
+            const next = argv[i + 1];
+            if (next === undefined) {
+                throw new ConductorValidationError(`Flag "${name}" requires a value.`);
+            }
+            value = next;
+            i += 1;
+        }
+        values.set(name, value);
+    }
+    return { values, bools };
+}
+function parseRunRecoveryArgs(argv) {
+    const { values, bools } = tokenizeRecoveryFlags(argv, RUN_VALUE_FLAGS, RECOVERY_BOOL_FLAGS);
+    if (bools.has("--help")) {
+        return { epicRunId: "", json: bools.has("--json"), help: true };
+    }
+    const epicRunId = values.get("--epic-run-id");
+    if (epicRunId === undefined || epicRunId.trim().length === 0) {
+        throw new ConductorValidationError('Flag "--epic-run-id" is required and must be non-empty.');
+    }
+    return { epicRunId: epicRunId.trim(), json: bools.has("--json"), help: false };
+}
+function parseTicketRecoveryArgs(argv) {
+    const { values, bools } = tokenizeRecoveryFlags(argv, TICKET_VALUE_FLAGS, RECOVERY_BOOL_FLAGS);
+    if (bools.has("--help")) {
+        return { epicRunId: "", ticketKey: "", json: bools.has("--json"), help: true };
+    }
+    const epicRunId = values.get("--epic-run-id");
+    if (epicRunId === undefined || epicRunId.trim().length === 0) {
+        throw new ConductorValidationError('Flag "--epic-run-id" is required and must be non-empty.');
+    }
+    const ticketKey = values.get("--ticket-key");
+    if (ticketKey === undefined || ticketKey.trim().length === 0) {
+        throw new ConductorValidationError('Flag "--ticket-key" is required and must be non-empty.');
+    }
+    return {
+        epicRunId: epicRunId.trim(),
+        ticketKey: ticketKey.trim(),
+        json: bools.has("--json"),
+        help: false,
+    };
+}
+// ---------------------------------------------------------------------------
+// Shared access resolution
+// ---------------------------------------------------------------------------
+/**
+ * Resolve Bridge API access through the shared credential-store resolution
+ * (never `BAPI_API_KEY` read directly). Prints the sanitized failure itself
+ * and returns `null` on failure so the caller can return exit code `1`
+ * without duplicating the rendering.
+ */
+async function resolveRecoveryAccess(json) {
+    const { resolveConductorBridgeApiAccess } = await import("./bridge-api-client.js");
+    const result = await resolveConductorBridgeApiAccess();
+    if (!result.ok) {
+        if (json) {
+            console.log(JSON.stringify({ ok: false, kind: "unauthorized", error: result.error }));
+        }
+        else {
+            console.error(`Error: ${result.error}`);
+        }
+        return null;
+    }
+    return result.access;
+}
+// ---------------------------------------------------------------------------
+// stop-run
+// ---------------------------------------------------------------------------
+const STOP_RUN_USAGE = [
+    "Usage: conductor stop-run --epic-run-id <id> [--json]",
+    "",
+    "Stop an epic run: block new dispatch and cancel its queued work. The run",
+    "record is preserved (never deleted) so its history stays inspectable.",
+    "Idempotent — repeating it once stopped is a safe no-op.",
+].join("\n");
+function renderStopRunResult(result, json) {
+    if (json) {
+        console.log(JSON.stringify(result));
+        return result.ok ? 0 : 1;
+    }
+    if (result.ok && result.kind === "committed") {
+        console.log(`Run ${result.epicRunId}: stopped. Its queued work was cancelled; the run record ` +
+            "remains available for inspection.");
+        return 0;
+    }
+    if (result.ok && result.kind === "already-stopped") {
+        console.log(`Run ${result.epicRunId}: already stopped; no further action.`);
+        return 0;
+    }
+    if (!result.ok && result.kind === "terminal") {
+        console.error(`Run ${result.epicRunId}: terminal (${result.status}) and cannot be stopped.`);
+        return 1;
+    }
+    console.error(`Run ${result.epicRunId}: could not be stopped — ${result.message}.`);
+    return 1;
+}
+export async function runStopRunCommand(argv) {
+    try {
+        const parsed = parseRunRecoveryArgs(argv);
+        if (parsed.help) {
+            console.log(STOP_RUN_USAGE);
+            return 0;
+        }
+        const access = await resolveRecoveryAccess(parsed.json);
+        if (!access)
+            return 1;
+        const { stopEpicRunRecovery } = await import("./recovery-operations.js");
+        const result = await stopEpicRunRecovery(access, { epicRunId: parsed.epicRunId });
+        return renderStopRunResult(result, parsed.json);
+    }
+    catch (error) {
+        console.error(`Error: ${toConductorErrorEnvelope(error).message}`);
+        return 1;
+    }
+}
+// ---------------------------------------------------------------------------
+// abandon-run
+// ---------------------------------------------------------------------------
+const ABANDON_RUN_USAGE = [
+    "Usage: conductor abandon-run --epic-run-id <id> [--json]",
+    "",
+    "Abandon an epic run — a TERMINAL, IRREVERSIBLE transition. An abandoned run",
+    "can never resume or be reused; start a new run instead. Idempotent —",
+    "repeating it on an already-abandoned run is a safe no-op.",
+].join("\n");
+function renderAbandonRunResult(result, json) {
+    if (json) {
+        console.log(JSON.stringify(result));
+        return result.ok ? 0 : 1;
+    }
+    if (result.ok && result.kind === "abandoned") {
+        console.log(`Run ${result.epicRunId}: abandoned (terminal).`);
+        return 0;
+    }
+    if (result.ok && result.kind === "already-abandoned") {
+        console.log(`Run ${result.epicRunId}: already abandoned (terminal); no further action.`);
+        return 0;
+    }
+    console.error(`Run ${result.epicRunId}: could not be abandoned — ${result.message}.`);
+    return 1;
+}
+export async function runAbandonRunCommand(argv) {
+    try {
+        const parsed = parseRunRecoveryArgs(argv);
+        if (parsed.help) {
+            console.log(ABANDON_RUN_USAGE);
+            return 0;
+        }
+        const access = await resolveRecoveryAccess(parsed.json);
+        if (!access)
+            return 1;
+        const { abandonEpicRunRecovery } = await import("./recovery-operations.js");
+        const result = await abandonEpicRunRecovery(access, { epicRunId: parsed.epicRunId });
+        return renderAbandonRunResult(result, parsed.json);
+    }
+    catch (error) {
+        console.error(`Error: ${toConductorErrorEnvelope(error).message}`);
+        return 1;
+    }
+}
+// ---------------------------------------------------------------------------
+// unpark / adopt-current-head-and-unpark (shared rendering)
+// ---------------------------------------------------------------------------
+const UNPARK_USAGE = [
+    "Usage: conductor unpark --epic-run-id <id> --ticket-key <key> [--json]",
+    "",
+    "Move a parked (needs_human) ticket back into its gate machine, once the",
+    "operator has resolved what parked it. Retries a bounded number of times on",
+    "its own if the ticket changes concurrently — never accepts a version counter.",
+].join("\n");
+const ADOPT_CURRENT_HEAD_USAGE = [
+    "Usage: conductor adopt-current-head-and-unpark --epic-run-id <id> --ticket-key <key> [--json]",
+    "",
+    "Recover a ticket parked because a human/external push drifted the PR head",
+    "off its anchored commit: adopt the CURRENT PR head and unpark in one step.",
+    "Retries a bounded number of times on its own if the ticket changes",
+    "concurrently — never accepts a version counter.",
+].join("\n");
+function renderTicketRecoveryResult(result, json) {
+    if (json) {
+        console.log(JSON.stringify(result));
+        return result.ok ? 0 : 1;
+    }
+    if (result.ok) {
+        console.log(`Ticket ${result.ticketKey} (run ${result.epicRunId}): unparked — status: ${result.status}.`);
+        return 0;
+    }
+    if (result.kind === "ticket-not-found") {
+        console.error(`Ticket ${result.ticketKey}: not found in run ${result.epicRunId}.`);
+        return 1;
+    }
+    if (result.kind === "concurrent-change-exhausted") {
+        console.error(`Ticket ${result.ticketKey} (run ${result.epicRunId}): could not recover — it kept ` +
+            "changing concurrently. Re-check the run/ticket status and try again.");
+        return 1;
+    }
+    console.error(`Ticket ${result.ticketKey} (run ${result.epicRunId}): could not recover — ${result.message}.`);
+    return 1;
+}
+export async function runUnparkCommand(argv) {
+    try {
+        const parsed = parseTicketRecoveryArgs(argv);
+        if (parsed.help) {
+            console.log(UNPARK_USAGE);
+            return 0;
+        }
+        const access = await resolveRecoveryAccess(parsed.json);
+        if (!access)
+            return 1;
+        const { unparkEpicTicketWithRetry } = await import("./recovery-operations.js");
+        const result = await unparkEpicTicketWithRetry(access, {
+            epicRunId: parsed.epicRunId,
+            ticketKey: parsed.ticketKey,
+        });
+        return renderTicketRecoveryResult(result, parsed.json);
+    }
+    catch (error) {
+        console.error(`Error: ${toConductorErrorEnvelope(error).message}`);
+        return 1;
+    }
+}
+export async function runAdoptCurrentHeadAndUnparkCommand(argv) {
+    try {
+        const parsed = parseTicketRecoveryArgs(argv);
+        if (parsed.help) {
+            console.log(ADOPT_CURRENT_HEAD_USAGE);
+            return 0;
+        }
+        const access = await resolveRecoveryAccess(parsed.json);
+        if (!access)
+            return 1;
+        const { adoptCurrentHeadAndUnparkWithRetry } = await import("./recovery-operations.js");
+        const result = await adoptCurrentHeadAndUnparkWithRetry(access, {
+            epicRunId: parsed.epicRunId,
+            ticketKey: parsed.ticketKey,
+        });
+        return renderTicketRecoveryResult(result, parsed.json);
+    }
+    catch (error) {
+        console.error(`Error: ${toConductorErrorEnvelope(error).message}`);
+        return 1;
+    }
+}