@bridge_gpt/mcp-server 0.2.68 → 0.2.70

package/build/executor/integration-job.js

@@ -24,6 +24,14 @@
  *   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
  *   push authority and no operational database.
+ * * `post_handoff_report` (BAPI-1497) — posts a quiescent run's ONE report. It
+ *   validates the server-built payload, finds the integration PR (opening it as
+ *   a DRAFT only when code landed and none exists), re-reads the PR, and upserts
+ *   the single comment marked `<!-- bridge-epic-handoff: <KEY> -->` that the
+ *   configured actor authored. It comments on an open draft or ready PR without
+ *   changing its state, skips a closed or merged PR, and reads the comment back
+ *   after an uncertain write instead of writing twice. It never marks ready and
+ *   never merges.
  *
  * None of them merges a pull request.
  *
@@ -31,8 +39,12 @@
  *
  * Every provider write runs with the child environment
  * {@link buildLocalMergeChildEnv} builds from the credential
- * {@link resolveLocalMergeCredential} resolves (`BAPI_LOCAL_MERGE_TOKEN`, or
- * `BAPI_MACHINE_MERGE_TOKEN` for a machine-token run). Inherited `GH_TOKEN`,
+ * {@link resolveMergeCredentialAtAction} resolves (`GITHUB_MERGE_TOKEN`, with the
+ * deprecated `BAPI_LOCAL_MERGE_TOKEN` still read as its alias, or
+ * `BAPI_MACHINE_MERGE_TOKEN` for a machine-token run; BAPI-1452). BAPI-1461: for
+ * the local kind only, and only in an executor that did not declare itself a
+ * durable host, the stored `github-merge:` entry for the action's repository is
+ * the last rung. Inherited `GH_TOKEN`,
  * `GITHUB_TOKEN`, and an ambient `gh` login are stripped from that environment,
  * so they cannot rescue a missing configured credential: a missing credential is
  * reported as `authority_unavailable` and nothing is written. The credential
@@ -50,10 +62,11 @@
  * repository itself; nothing reported here completes a run or passes a gate,
  * and this module chooses no next ticket and no gate.
  */
-import { buildLocalMergeChildEnv, resolveLocalMergeCredential, sanitizeLocalMergeOutput, } from "../conductor/local-merge.js";
+import { buildLocalMergeChildEnv, sanitizeLocalMergeOutput, } from "../conductor/local-merge.js";
+import { resolveMergeCredentialAtAction } from "../conductor/stored-merge-credential.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";
+import { HANDOFF_REPORT_DETAIL_CODES, HANDOFF_REPORT_PAYLOAD_VERSION, HANDOFF_REPORT_SHAPES, INTEGRATION_ACTION_OPERATIONS, INTEGRATION_ACTION_OUTCOMES, INTEGRATION_ACTION_PROTOCOL_VERSION, MAX_HANDOFF_REPORT_COMMENT_CHARS, } from "./types.js";
 /** The route prefix, mirrored from `api/routes/__init__.py`. */
 export const INTEGRATION_ACTION_ROUTE_PREFIX = "/epic-integration-actions";
 /** Heartbeat cadence. The server lease is three minutes. */
@@ -515,6 +528,269 @@ async function performMarkReady(action, deps, credential, env, seams) {
         return { outcome: "already_satisfied", pr_number: pr };
     return { outcome: "already_satisfied", pr_number: pr, detail_code: WORKAROUNDS_PRESENT_DETAIL_CODE };
 }
+// ---------------------------------------------------------------------------
+// BAPI-1497: the quiescent hand-off report
+// ---------------------------------------------------------------------------
+const DIGEST_RE = /^[0-9a-f]{64}$/;
+const EPIC_KEY_RE = /^[A-Z][A-Z0-9_]{0,19}-[0-9]+$/;
+const GITHUB_LOGIN_RE = /^[A-Za-z0-9](?:[A-Za-z0-9-]{0,38})(?:\[bot\])?$/;
+/** The exact marker line, keyed by the EPIC key. Mirrors `handoff_report_contract.py`. */
+export function handoffReportMarker(epicKey) {
+    return `<!-- bridge-epic-handoff: ${epicKey} -->`;
+}
+/** The digest line that says WHICH report a comment carries. */
+export function handoffReportDigestMarker(digest) {
+    return `<!-- bridge-epic-handoff-digest: ${digest} -->`;
+}
+/**
+ * Validate the server-built report before any provider call. A no-delivery
+ * payload never becomes an action server-side; one arriving here is refused
+ * without a side effect, exactly like a malformed one.
+ */
+export function validateHandoffReportPayload(action) {
+    const payload = action.report_payload;
+    const invalid = { ok: false, detail: HANDOFF_REPORT_DETAIL_CODES.payloadInvalid };
+    if (typeof payload !== "object" || payload === null)
+        return invalid;
+    if (payload.version !== HANDOFF_REPORT_PAYLOAD_VERSION)
+        return invalid;
+    if (typeof payload.digest !== "string" || !DIGEST_RE.test(payload.digest))
+        return invalid;
+    if (!HANDOFF_REPORT_SHAPES.includes(payload.shape))
+        return invalid;
+    if (payload.epic_key !== action.epic_key || !EPIC_KEY_RE.test(action.epic_key))
+        return invalid;
+    const counts = [
+        payload.delivered_count,
+        payload.done_without_change_count,
+        payload.parked_count,
+        payload.blocked_count,
+        payload.handoff_count,
+        payload.omitted_count,
+    ];
+    if (!counts.every((n) => Number.isInteger(n) && n >= 0))
+        return invalid;
+    if (payload.shape === "no_delivery" || payload.delivered_count < 1) {
+        return { ok: false, detail: HANDOFF_REPORT_DETAIL_CODES.noDelivery };
+    }
+    const body = payload.comment_body;
+    if (typeof body !== "string" || body.length === 0 || body.length > MAX_HANDOFF_REPORT_COMMENT_CHARS) {
+        return invalid;
+    }
+    const lines = body.split("\n");
+    if (!lines.includes(handoffReportMarker(action.epic_key)))
+        return invalid;
+    if (!lines.includes(handoffReportDigestMarker(payload.digest)))
+        return invalid;
+    return { ok: true, payload };
+}
+/** The authenticated login of the configured credential, or `null`. */
+async function readActorLogin(deps, credential, env) {
+    const r = await runCredentialed(deps, credential, env, "gh", ["api", "user", "--jq", ".login"], { timeoutMs: READ_TIMEOUT_MS });
+    const login = r.stdout.trim();
+    return r.exitCode === 0 && GITHUB_LOGIN_RE.test(login) ? login : null;
+}
+/**
+ * Every comment on the PR authored by `login` whose body holds the EXACT marker
+ * line, newest (highest id) first. `null` when the listing cannot be read.
+ */
+async function listMarkerComments(deps, credential, env, repository, prNumber, login, marker) {
+    const r = await runCredentialed(deps, credential, env, "gh", [
+        "api", "--paginate", `repos/${repository}/issues/${prNumber}/comments`,
+        "--jq", ".[] | {id: .id, login: .user.login, body: .body}",
+    ], { timeoutMs: READ_TIMEOUT_MS });
+    if (r.exitCode !== 0)
+        return null;
+    const found = [];
+    for (const line of r.stdout.split("\n")) {
+        const text = line.trim();
+        if (text === "")
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch {
+            return null;
+        }
+        if (typeof parsed !== "object" || parsed === null)
+            return null;
+        const { id, login: author, body } = parsed;
+        if (typeof id !== "number" || !Number.isInteger(id) || id <= 0)
+            return null;
+        if (author !== login || typeof body !== "string")
+            continue;
+        if (!body.split("\n").includes(marker))
+            continue;
+        found.push({ id, body });
+    }
+    found.sort((a, b) => b.id - a.id);
+    return found;
+}
+/** A full page may hide more records, so it is never read as conclusive. */
+const PR_HISTORY_LIMIT = 30;
+/**
+ * Every PR from `epicBranch` into `baseBranch`, in any state. `null` when the
+ * listing cannot be read or is not conclusive.
+ */
+async function readEpicPullRequestHistory(gh, epicBranch, baseBranch, repository, cwd) {
+    try {
+        const r = await gh([
+            "--repo", repository, "pr", "list", "--state", "all",
+            "--head", epicBranch, "--base", baseBranch,
+            "--json", "number,state,headRefName,baseRefName", "--limit", String(PR_HISTORY_LIMIT),
+        ], { cwd, timeoutMs: EPIC_INTEGRATION_PR_READ_TIMEOUT_MS });
+        if (r.exitCode !== 0)
+            return null;
+        const parsed = JSON.parse(r.stdout);
+        if (!Array.isArray(parsed) || parsed.length >= PR_HISTORY_LIMIT)
+            return null;
+        const found = [];
+        for (const item of parsed) {
+            if (typeof item !== "object" || item === null)
+                return null;
+            const { number, state, headRefName, baseRefName } = item;
+            if (headRefName !== epicBranch || baseRefName !== baseBranch)
+                continue;
+            if (typeof number !== "number" || !Number.isInteger(number) || number <= 0)
+                return null;
+            if (state !== "OPEN" && state !== "CLOSED" && state !== "MERGED")
+                return null;
+            found.push({ number, state });
+        }
+        return found;
+    }
+    catch {
+        return null;
+    }
+}
+/** The PR's open/closed/merged state, read immediately before commenting. */
+async function readPullRequestState(gh, prNumber, repository, cwd) {
+    try {
+        const r = await gh(["pr", "view", String(prNumber), "--repo", repository, "--json", "state,headRefName,baseRefName"], { 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 { state, headRefName, baseRefName } = parsed;
+        if (state !== "OPEN" && state !== "CLOSED" && state !== "MERGED")
+            return null;
+        if (typeof headRefName !== "string" || typeof baseRefName !== "string")
+            return null;
+        return { state, headRefName, baseRefName };
+    }
+    catch {
+        return null;
+    }
+}
+async function performHandoffReport(action, client, deps, credential, env, seams, lease) {
+    const valid = validateHandoffReportPayload(action);
+    if (!valid.ok)
+        return { outcome: "failed", detail_code: valid.detail };
+    const payload = valid.payload;
+    const createGh = seams.createGhRunner ?? ((e) => createProductionEpicIntegrationGhRunner(undefined, e));
+    const gh = createGh(env);
+    // A PR the owner closed, or one already merged, is never replaced: `ensure`
+    // only sees open PRs and would open a fresh draft for either. Read the PR
+    // history first and create nothing unless it is conclusively empty.
+    const history = await readEpicPullRequestHistory(gh, action.epic_branch, action.base_branch, action.provider_repository, deps.cwd);
+    if (history === null) {
+        return { outcome: "failed", detail_code: HANDOFF_REPORT_DETAIL_CODES.prUnavailable };
+    }
+    if (!history.some((p) => p.state === "OPEN")) {
+        const merged = history.find((p) => p.state === "MERGED");
+        if (merged !== undefined) {
+            return { outcome: "already_satisfied", pr_number: merged.number, detail_code: HANDOFF_REPORT_DETAIL_CODES.prMerged };
+        }
+        const closed = history.find((p) => p.state === "CLOSED");
+        if (closed !== undefined) {
+            return { outcome: "already_satisfied", pr_number: closed.number, detail_code: HANDOFF_REPORT_DETAIL_CODES.prClosed };
+        }
+    }
+    // Look up before creating; a missing PR is opened as a DRAFT and left one.
+    // `requestReady: false` means this path can never take a PR out of draft.
+    const ensured = await ensureEpicIntegrationPullRequest({
+        epicKey: action.epic_key,
+        epicBranch: action.epic_branch,
+        baseBranch: action.base_branch,
+        command: "executor integration",
+        gh,
+        cwd: deps.cwd,
+        requestReady: false,
+        repo: action.provider_repository,
+    });
+    if (ensured.kind === "unavailable") {
+        if (ensured.reason === "probe_ambiguous")
+            return { outcome: "pr_ambiguous", detail_code: "probe_ambiguous" };
+        if (ensured.reason === "gh_unauthenticated" || ensured.reason === "gh_unavailable") {
+            return { outcome: "authority_unavailable", detail_code: HANDOFF_REPORT_DETAIL_CODES.prUnavailable };
+        }
+        return { outcome: "failed", detail_code: HANDOFF_REPORT_DETAIL_CODES.prUnavailable };
+    }
+    if (ensured.kind === "deferred" || ensured.prNumber === null) {
+        return { outcome: "failed", detail_code: HANDOFF_REPORT_DETAIL_CODES.prUnavailable };
+    }
+    const pr = ensured.prNumber;
+    // Re-read the PR immediately before commenting: open draft or ready only.
+    const prState = await readPullRequestState(gh, pr, action.provider_repository, deps.cwd);
+    if (prState === null) {
+        return { outcome: "failed", pr_number: pr, detail_code: HANDOFF_REPORT_DETAIL_CODES.prUnavailable };
+    }
+    if (prState.headRefName !== action.epic_branch || prState.baseRefName !== action.base_branch) {
+        return { outcome: "pr_ambiguous", pr_number: pr, detail_code: "probe_ambiguous" };
+    }
+    if (prState.state === "CLOSED") {
+        return { outcome: "already_satisfied", pr_number: pr, detail_code: HANDOFF_REPORT_DETAIL_CODES.prClosed };
+    }
+    if (prState.state === "MERGED") {
+        return { outcome: "already_satisfied", pr_number: pr, detail_code: HANDOFF_REPORT_DETAIL_CODES.prMerged };
+    }
+    const login = await readActorLogin(deps, credential, env);
+    if (login === null) {
+        return { outcome: "failed", pr_number: pr, detail_code: HANDOFF_REPORT_DETAIL_CODES.actorUnknown };
+    }
+    const marker = handoffReportMarker(action.epic_key);
+    const digestMarker = handoffReportDigestMarker(payload.digest);
+    const existing = await listMarkerComments(deps, credential, env, action.provider_repository, pr, login, marker);
+    if (existing === null) {
+        return { outcome: "failed", pr_number: pr, detail_code: HANDOFF_REPORT_DETAIL_CODES.commentWriteFailed };
+    }
+    const newest = existing[0];
+    if (newest !== undefined && newest.body === payload.comment_body) {
+        return { outcome: "already_satisfied", pr_number: pr, detail_code: HANDOFF_REPORT_DETAIL_CODES.published };
+    }
+    // Freshness, immediately before the write: the lease must still be ours and
+    // the server must still hand us this exact work (a newer digest supersedes an
+    // unclaimed older one, so an obsolete writer stops here).
+    if (lease.lost())
+        return { outcome: "authority_lost", pr_number: pr, detail_code: "lease_lost" };
+    const fresh = await client.fetch(action);
+    if (fresh.kind !== "ok" || !sameWork(action, fresh.work)) {
+        return { outcome: "authority_lost", pr_number: pr, detail_code: "lease_not_held" };
+    }
+    const write = newest !== undefined
+        ? await runCredentialed(deps, credential, env, "gh", [
+            "api", "--method", "PATCH",
+            `repos/${action.provider_repository}/issues/comments/${newest.id}`,
+            "-f", `body=${payload.comment_body}`,
+        ], { timeoutMs: WRITE_TIMEOUT_MS })
+        : await runCredentialed(deps, credential, env, "gh", [
+            "api", "--method", "POST",
+            `repos/${action.provider_repository}/issues/${pr}/comments`,
+            "-f", `body=${payload.comment_body}`,
+        ], { timeoutMs: WRITE_TIMEOUT_MS });
+    if (write.exitCode === 0) {
+        return { outcome: "applied", pr_number: pr, detail_code: HANDOFF_REPORT_DETAIL_CODES.published };
+    }
+    // An uncertain write: read the marker comment back before anything retries.
+    const readBack = await listMarkerComments(deps, credential, env, action.provider_repository, pr, login, marker);
+    const landed = readBack?.[0];
+    if (landed !== undefined && landed.body.split("\n").includes(digestMarker) && landed.body === payload.comment_body) {
+        return { outcome: "applied", pr_number: pr, detail_code: HANDOFF_REPORT_DETAIL_CODES.published };
+    }
+    return { outcome: "failed", pr_number: pr, detail_code: HANDOFF_REPORT_DETAIL_CODES.commentWriteFailed };
+}
 /**
  * Perform one claimed integration action and report its facts.
  *
@@ -547,7 +823,17 @@ export async function runIntegrationAction(action, client, deps, seams = {}) {
     if (!valid.ok)
         return finish({ outcome: "failed", detail_code: valid.reason });
     const kind = action.credential_kind === "machine_token" ? "machine_token" : "local";
-    const credential = resolveLocalMergeCredential(deps.env, kind);
+    // BAPI-1461: resolved here, when the action runs, so a token stored after the
+    // executor started is still found. The stored rung is local-kind only and only
+    // for an eligible executor; the server-carried repository names the entry.
+    const resolution = await resolveMergeCredentialAtAction(deps.env, kind, {
+        allowStoredEntry: deps.allowStoredMergeEntry === true,
+        providerRepository: action.provider_repository,
+        ...(deps.homedir && deps.readFile
+            ? { storeDeps: { env: deps.env, homedir: deps.homedir, readFile: deps.readFile } }
+            : {}),
+    });
+    const credential = resolution.status === "resolved" ? resolution.credential : null;
     if (credential === null) {
         // An ambient gh login, GH_TOKEN, or GITHUB_TOKEN does NOT substitute.
         return finish({ outcome: "authority_unavailable", detail_code: `${kind}_merge_credential_missing` });
@@ -568,6 +854,13 @@ export async function runIntegrationAction(action, client, deps, seams = {}) {
         else if (!sameWork(action, refetched.work)) {
             report = { outcome: "authority_lost", detail_code: "work_changed" };
         }
+        else if (action.operation === "post_handoff_report") {
+            // A report describes the run, not one epic head: a moved head is not a
+            // reason to withhold it. It never reaches the ready or merge paths below.
+            report = lease.lost()
+                ? { outcome: "authority_lost", detail_code: "lease_lost" }
+                : await performHandoffReport(action, client, deps, credential, env, seams, lease);
+        }
         else {
             const live = await reads.branchHead(action.epic_branch);
             if (live === null) {

package/build/executor/job-errors.js

@@ -179,6 +179,16 @@ export const WorkerStartupFatal = "ContractError.WorkerStartupFatal";
 export const RequiredMcpRegistration = "ContractError.RequiredMcpRegistration";
 export const ClaudeNotAuthenticated = "ContractError.ClaudeNotAuthenticated";
 export const WorktreeBusy = "ContractError.WorktreeBusy";
+/**
+ * BAPI-1530 — the executor's DELIBERATE refusal to prepare a worktree: a confirmed
+ * stale feature branch, a completed negative ancestry proof, or another
+ * non-destructive setup refusal (held lock, expired preparation authority, an
+ * occupied rename destination). Decided from structured results only, never from
+ * rendered Git or Worktrunk text. The server maps this exact kind to
+ * `worktree_setup_refused` and parks immediately; every other worktree failure
+ * stays `WorktreeError` with the `crashed` classification.
+ */
+export const WorktreeSetupRefused = "WorktreeSetupRefused";
 export const ExecutorAdapterUnavailable = "ContractError.ExecutorAdapterUnavailable";
 /**
  * BAPI-814/D1: a previous attempt's `.conductor/result.json` / `critique.md`
@@ -431,14 +441,34 @@ export function toExecutorFailure(error) {
  */
 export function secretFreeErrorMessage(error) {
     const raw = error instanceof Error ? error.message : String(error);
-    const redacted = raw
+    const bounded = redactSecretShapes(raw).slice(0, ERROR_MESSAGE_MAX_CHARS).trim();
+    return bounded.length > 0
+        ? `unexpected executor failure: ${bounded}`
+        : "unexpected executor failure";
+}
+/**
+ * The redaction shared by {@link secretFreeErrorMessage} and
+ * {@link secretFreeWorktreeMessage} (BAPI-1530). Token-shaped and
+ * credential-shaped substrings are stripped; full 40-hex SHAs are long opaque
+ * tokens too, which is why worktree diagnostics render 12-character short SHAs.
+ */
+function redactSecretShapes(raw) {
+    return (raw
         // `key=value` / `token: value` credential pairs → drop the value.
         .replace(/\b(token|password|passwd|pwd|secret|api[_-]?key|apikey|authorization|auth|bearer)\b\s*[:=]\s*\S+/gi, "$1=[REDACTED]")
         // Standalone secret-shaped tokens (GitHub PATs, long opaque strings).
         .replace(/\bgh[posru]_[A-Za-z0-9]{16,}\b/g, "[REDACTED_TOKEN]")
-        .replace(/\b[A-Za-z0-9_-]{40,}\b/g, "[REDACTED_TOKEN]");
-    const bounded = redacted.slice(0, ERROR_MESSAGE_MAX_CHARS).trim();
-    return bounded.length > 0
-        ? `unexpected executor failure: ${bounded}`
-        : "unexpected executor failure";
+        .replace(/\b[A-Za-z0-9_-]{40,}\b/g, "[REDACTED_TOKEN]"));
+}
+/**
+ * BAPI-1530: a bounded, secret-free worktree preparation message for a `/fail`
+ * payload or a diagnostic log line. Shares the redaction regexes and
+ * {@link ERROR_MESSAGE_MAX_CHARS} with {@link secretFreeErrorMessage} but does
+ * NOT prepend "unexpected executor failure": a deliberate setup refusal is not
+ * unexpected, and raw Worktrunk stderr must never cross the boundary.
+ */
+export function secretFreeWorktreeMessage(message) {
+    const raw = typeof message === "string" ? message : String(message ?? "");
+    const bounded = redactSecretShapes(raw).slice(0, ERROR_MESSAGE_MAX_CHARS).trim();
+    return bounded.length > 0 ? bounded : "worktree preparation failed";
 }