@bridge_gpt/mcp-server 0.2.16 → 0.2.18

package/build/conductor/errors.js

@@ -10,6 +10,43 @@
  * generic message.
  */
 import { redactSecretString } from "./redaction.js";
+/**
+ * Redact a diagnostic string destined for BACKEND LOGS ONLY (never the client
+ * envelope): strip secret-shaped material (tokens, keys, bearer creds) via
+ * {@link redactSecretString}, then additionally mask user home-dir path segments
+ * (`/Users/<name>/…`, `/home/<name>/…`) which leak usernames and credential-bearing
+ * locations. The rest of a stack trace is preserved so operators can still diagnose.
+ */
+function redactDiagnostic(value) {
+    return redactSecretString(value).replace(/(\/(?:Users|home)\/)[^/\s:]+/g, "$1[REDACTED_USER]");
+}
+/**
+ * FINDING 5 (BAPI-463): surface an unexpected (INTERNAL_ERROR) error with its
+ * class + message (redacted so no secret or credential-bearing path leaks) so
+ * operators can root-cause the underlying fault that the sanitized client
+ * envelope intentionally hides (e.g. the recurring `check_messages` failure).
+ *
+ * Emitted as a SINGLE LINE with NO stack frames: the conductor's `console.error`
+ * IS the CLI's stderr surface, which a committed security invariant requires to
+ * stay stack-trace-free (`security-regressions.test.ts`). The error class +
+ * message is the diagnostic essence the acceptance criterion calls for; a raw
+ * stack would both violate that invariant and risk leaking internal file paths.
+ * Best-effort: a logging failure must never mask the original error, and NOTHING
+ * here is returned to the MCP/CLI caller.
+ */
+function logInternalErrorDiagnostic(error) {
+    try {
+        const name = error instanceof Error ? error.name : typeof error;
+        const rawMessage = error instanceof Error ? error.message : String(error);
+        // Collapse any newlines so the single-line diagnostic can never resemble a
+        // multi-line stack trace to the CLI-surface guard.
+        const message = redactDiagnostic(rawMessage).replace(/\s*\n\s*/g, " ");
+        console.error(`[conductor:INTERNAL_ERROR] [${name}] ${message}`);
+    }
+    catch {
+        /* diagnostic logging must never throw */
+    }
+}
 /** Raised when caller input violates a conductor validation rule. */
 export class ConductorValidationError extends Error {
     constructor(message) {
@@ -89,6 +126,10 @@ export function toConductorErrorEnvelope(error) {
             message: "Conductor ledger is busy; retry shortly.",
         };
     }
+    // Unexpected error: log the redacted class + message + stack to backend logs so
+    // the real cause is diagnosable, then return the fixed generic client envelope
+    // (no trace context, no secret material) to the MCP/CLI caller.
+    logInternalErrorDiagnostic(error);
     return {
         error: "INTERNAL_ERROR",
         status: 500,

package/build/conductor/event-accessors.js

@@ -0,0 +1,234 @@
+/**
+ * Canonical conductor event payload model + typed, fail-closed read accessors
+ * (BAPI-493).
+ *
+ * The stored ledger envelope is deliberately loose (`ConductorEventData.details?:
+ * unknown`), so every consumer historically re-parsed `data.details` by hand and
+ * producers/consumers silently drifted on field location and nesting. This module
+ * makes the read side type-enforced:
+ *
+ *   - {@link EventDetailsByType} maps EVERY {@link SemanticEventType} to an explicit
+ *     details payload shape (details-less families get a conservative empty payload),
+ *     with `never`-based exhaustiveness guards that fail the TypeScript build if a
+ *     new semantic type is added without a payload member.
+ *   - {@link getEventDetails} is discriminant-constrained (E-27): it validates
+ *     `event.type === expectedType` at RUNTIME before narrowing and returns `null`
+ *     on mismatch, so a caller can never obtain a payload for the wrong type.
+ *   - {@link getHeadSha} / {@link getMergeIdentity} are the behavior-critical
+ *     accessors that fail closed (a head/identity that cannot be proven is never
+ *     treated as valid), matching the pre-refactor `extractEventHeadSha` /
+ *     `extractMergeActionIdentityFromGateEvent` behavior byte-for-byte.
+ *
+ * This is READ-SIDE typing only: the stored `data_json` envelope shape is unchanged
+ * and there is NO ledger migration. The module depends only on lower-level,
+ * dependency-light modules (`taxonomy`, `types`, `git-ci-types`, `merge-identity`)
+ * so it can be imported by both `epic-state.ts` and `merge-ledger.ts` without a
+ * cycle. It is NEVER applied to backend HTTP response envelopes (which use a
+ * `detail` wrapper, not `data.details`) — those keep their own normalizers.
+ */
+import { normalizePrNumber, normalizeRepoName, normalizeSha, } from "./git-ci-types.js";
+import { buildGateIdentity, makeMergeActionKey, } from "./merge-identity.js";
+// Re-export the merge identity primitives so downstream consumers can import the
+// whole merge-identity surface from a single typed-accessor entry point.
+export { buildGateIdentity, makeMergeActionKey };
+// ---------------------------------------------------------------------------
+// Small structural helpers
+// ---------------------------------------------------------------------------
+/** Narrow an unknown value to a plain, indexable object. */
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** Runtime exhaustiveness guard for switch/dispatch fall-through. */
+export function assertNever(value) {
+    throw new Error(`Unexpected value: ${String(value)}`);
+}
+/**
+ * Normalize a PR head SHA read from a conductor ledger event's
+ * `data.details.head_sha`. Preserves the exact behavior of the pre-refactor
+ * `epic-state.extractEventHeadSha`: accept only a trimmed 7–40 character
+ * hexadecimal string and return it lowercased; every other shape yields `null`.
+ * Deliberately looser than {@link normalizeSha} (which requires a full 40/64-char
+ * object id) because head observations may carry an abbreviated SHA.
+ */
+export function normalizeEventHeadSha(value) {
+    if (typeof value !== "string")
+        return null;
+    const trimmed = value.trim();
+    if (!/^[0-9a-f]{7,40}$/i.test(trimmed))
+        return null;
+    return trimmed.toLowerCase();
+}
+/** Read ONLY `event.data.details` as a plain object, or `null`. */
+function getRawEventDetails(event) {
+    const details = event.data?.details;
+    return isPlainObject(details) ? details : null;
+}
+// ---------------------------------------------------------------------------
+// Per-type parsers
+// ---------------------------------------------------------------------------
+/** The conservative empty payload shared by all details-less families. */
+const EMPTY_DETAILS = Object.freeze({});
+/** Parse a head-observation payload: read only `details.head_sha`, fail closed. */
+function parseHeadObservation(event) {
+    const details = getRawEventDetails(event);
+    return { head_sha: details ? normalizeEventHeadSha(details.head_sha) : null };
+}
+/** Parse a `merge.*` lifecycle payload: `action_key` string or null. */
+function parseMergeLifecycle(event) {
+    const details = getRawEventDetails(event);
+    const actionKey = details && typeof details.action_key === "string" && details.action_key.trim().length > 0
+        ? details.action_key.trim()
+        : null;
+    return { action_key: actionKey };
+}
+/**
+ * Parse the canonical `gate.met` payload. `head_sha`/`repo`/`pr_number` use the
+ * STRICT normalizers (a merge binding requires a full SHA); `required_checks`
+ * preserves the top-level → nested `ci_check_status.required_checks` dual path.
+ */
+function parseGateMet(event) {
+    const details = getRawEventDetails(event);
+    if (!details) {
+        return {
+            head_sha: null,
+            repo: null,
+            pr_number: null,
+            gate_name: null,
+            config_hash: null,
+            required_checks: [],
+        };
+    }
+    const gateName = typeof details.gate_name === "string" && details.gate_name.trim().length > 0
+        ? details.gate_name.trim()
+        : null;
+    const configHash = typeof details.config_hash === "string" && details.config_hash.trim().length > 0
+        ? details.config_hash.trim()
+        : null;
+    const ciCheckStatus = isPlainObject(details.ci_check_status) ? details.ci_check_status : null;
+    const rawRequiredChecks = Array.isArray(details.required_checks)
+        ? details.required_checks
+        : ciCheckStatus && Array.isArray(ciCheckStatus.required_checks)
+            ? ciCheckStatus.required_checks
+            : [];
+    const requiredChecks = rawRequiredChecks.filter((c) => typeof c === "string" && c.trim().length > 0);
+    return {
+        head_sha: normalizeSha(details.head_sha),
+        repo: normalizeRepoName(details.repo),
+        pr_number: normalizePrNumber(details.pr_number),
+        gate_name: gateName,
+        config_hash: configHash,
+        required_checks: requiredChecks,
+    };
+}
+/** Parse a spec-review verdict payload (conservative head read). */
+function parseSpecReview(event) {
+    const details = getRawEventDetails(event);
+    return { head_sha: details ? normalizeEventHeadSha(details.head_sha) : null };
+}
+/** Return the shared conservative empty payload for details-less families. */
+function parseEmpty() {
+    return EMPTY_DETAILS;
+}
+/**
+ * Exhaustive parser table keyed by every {@link SemanticEventType}. There is no
+ * catch-all default branch that returns raw `data.details` for an unrecognized
+ * type — a missing key breaks the `satisfies` check and fails the build.
+ */
+const EVENT_PARSERS = {
+    "run.started": parseEmpty,
+    "run.heartbeat": parseEmpty,
+    "run.stopped": parseEmpty,
+    "agent.notification": parseEmpty,
+    "tool.intent": parseEmpty,
+    "worktree.changed": parseEmpty,
+    "git.commit_created": parseEmpty,
+    "git.pr_opened": parseHeadObservation,
+    "ci.passed": parseHeadObservation,
+    "ci.failed": parseHeadObservation,
+    "gate.met": parseGateMet,
+    "supervisor.assessment": parseEmpty,
+    "message.sent": parseEmpty,
+    "message.delivered": parseEmpty,
+    "message.acked": parseEmpty,
+    "merge.dry_run": parseMergeLifecycle,
+    "merge.attempted": parseMergeLifecycle,
+    "merge.succeeded": parseHeadObservation,
+    "merge.failed": parseMergeLifecycle,
+    "merge.conflict": parseHeadObservation,
+    "merge.pending_approval": parseMergeLifecycle,
+    "review.passed": parseHeadObservation,
+    "review.changes_requested": parseHeadObservation,
+    "spec_review.passed": parseSpecReview,
+    "spec_review.changes_requested": parseSpecReview,
+    "parse.triggered": parseEmpty,
+};
+// ---------------------------------------------------------------------------
+// Public accessors
+// ---------------------------------------------------------------------------
+/**
+ * Typed, discriminant-constrained details accessor (E-27). Returns the parsed
+ * payload for `expectedType` ONLY when `event.type === expectedType` at runtime;
+ * returns `null` on any discriminant mismatch so a caller can never obtain a
+ * `PayloadFor<T>` by passing the wrong expected type. Details-less families return
+ * a conservative empty payload (never the raw `unknown` details).
+ */
+export function getEventDetails(event, expectedType) {
+    if (event.type !== expectedType)
+        return null;
+    const parser = EVENT_PARSERS[expectedType];
+    return parser(event);
+}
+/**
+ * Read and normalize a PR head SHA from the CANONICAL `event.data.details.head_sha`
+ * path only. No fallback locations are consulted — a valid-looking head at
+ * `data.head_sha` or a nested snapshot is deliberately ignored. Returns a lowercased
+ * 7–40 char hex SHA, or `null` for missing/non-object details, non-string,
+ * malformed, or out-of-range values. Fail-closed: a head that cannot be proven is
+ * never treated as valid.
+ */
+export function getHeadSha(event) {
+    const details = getRawEventDetails(event);
+    if (!details)
+        return null;
+    return normalizeEventHeadSha(details.head_sha);
+}
+/**
+ * Resolve the immutable {@link MergeActionIdentity} from a worker-scoped `gate.met`
+ * event. Returns `null` unless the event is a `gate.met` carrying a complete PR
+ * binding (repo, pr_number, head_sha, gate_name) and a non-empty `worker_id`.
+ * Run-level or incomplete events yield `null`. Preserves the historical
+ * `required_checks` dual path (top-level then nested `ci_check_status`) and never
+ * throws. Branch-name fields, if present, are ignored.
+ */
+export function getMergeIdentity(event) {
+    if (event.type !== "gate.met")
+        return null;
+    // Worker scope is required — a run-level gate.met never binds a specific worker.
+    if (typeof event.worker_id !== "string" || event.worker_id.trim().length === 0) {
+        return null;
+    }
+    const details = getEventDetails(event, "gate.met");
+    if (details === null)
+        return null;
+    const { repo, pr_number: prNumber, head_sha: headSha, gate_name: gateName } = details;
+    if (repo === null || prNumber === null || headSha === null || gateName === null) {
+        return null;
+    }
+    const gateIdentity = buildGateIdentity(gateName, details.config_hash);
+    const actionKey = makeMergeActionKey(repo, prNumber, headSha, gateIdentity);
+    return {
+        repo,
+        pr_number: prNumber,
+        head_sha: headSha,
+        gate_name: gateName,
+        config_hash: details.config_hash,
+        required_checks: details.required_checks,
+        gate_identity: gateIdentity,
+        action_key: actionKey,
+        gate_event: {
+            id: typeof event.id === "string" ? event.id : undefined,
+            seq: typeof event.seq === "number" ? event.seq : undefined,
+            time: typeof event.time === "string" ? event.time : undefined,
+        },
+    };
+}

package/build/conductor/file-scope-guard.js

@@ -0,0 +1,201 @@
+/**
+ * BAPI-507 (N-2): warn-only worker file-scope guard.
+ *
+ * Compares a branch's changed files against the planner-declared touched-file
+ * set (delivered to the worker via `BAPI_CONDUCTOR_DECLARED_TOUCHED_FILES_JSON`)
+ * and warns when the diff strays outside that set. It is strictly warn-only /
+ * fail-open: it NEVER blocks PR creation, mutates the branch, or exits non-zero.
+ * A worker that implements a sibling's files (the N-2 over-reach observed in the
+ * BAPI-488 run) surfaces here as a bounded, secret-free warning rather than a
+ * silent clobber.
+ *
+ * Byte-identical false-positive protection: the guard analyzes ONLY the
+ * branch-local diff against `origin/main` (`git diff --name-only
+ * origin/main...HEAD`), which excludes files that are byte-identical to
+ * `origin/main`. So a legitimate `git merge origin/main` that carries
+ * sibling-owned files in branch history but does not change them at the tip
+ * produces no false positive.
+ *
+ * All subprocess calls are list-based `spawnSync` with `shell: false` — no shell
+ * string is ever constructed.
+ */
+import { spawnSync } from "node:child_process";
+/** Env var carrying the compact JSON array of declared repo-relative paths. */
+export const DECLARED_TOUCHED_FILES_ENV = "BAPI_CONDUCTOR_DECLARED_TOUCHED_FILES_JSON";
+/** Env var carrying the dispatched ticket key (used only to label warnings). */
+export const FILE_SCOPE_GUARD_TICKET_KEY_ENV = "BAPI_CONDUCTOR_TICKET_KEY";
+/** Base ref the branch diff is computed against. */
+export const FILE_SCOPE_GUARD_BASE_REF = "origin/main";
+/**
+ * Normalize a single declared/changed path to a repo-relative POSIX path, or
+ * `null` when it is unsafe/unusable. Rejects blank paths, POSIX- and
+ * Windows-absolute paths, and any parent traversal (`..`). Converts `\` → `/`
+ * and strips a single leading `./`. Never consults the filesystem.
+ */
+export function normalizeRepoRelativePath(input) {
+    if (typeof input !== "string")
+        return null;
+    const trimmed = input.trim();
+    if (trimmed.length === 0)
+        return null;
+    // Reject absolute paths (POSIX `/…`, `\…`, or Windows drive `C:\…` / `C:/…`)
+    // BEFORE separator normalization so both separator styles are caught.
+    if (trimmed.startsWith("/") ||
+        trimmed.startsWith("\\") ||
+        /^[A-Za-z]:[\\/]/.test(trimmed)) {
+        return null;
+    }
+    let p = trimmed.replace(/\\/g, "/");
+    if (p.startsWith("./"))
+        p = p.slice(2);
+    const segments = p.split("/");
+    if (segments.some((s) => s === ".."))
+        return null;
+    const cleaned = segments.filter((s) => s !== "" && s !== ".").join("/");
+    return cleaned.length > 0 ? cleaned : null;
+}
+/**
+ * Normalize a raw list of declared paths: drop non-strings and unsafe paths,
+ * dedupe, and sort. Anything that is not an array yields an empty list. This is
+ * the single source of truth for the declared-file normalization contract shared
+ * by the env producer (`buildEpicIdentityEnv`), the runtime plan mapper, and the
+ * guard's env parser.
+ */
+export function normalizeDeclaredTouchedFiles(list) {
+    if (!Array.isArray(list))
+        return [];
+    const out = new Set();
+    for (const item of list) {
+        const norm = normalizeRepoRelativePath(item);
+        if (norm)
+            out.add(norm);
+    }
+    return Array.from(out).sort();
+}
+/**
+ * Parse `BAPI_CONDUCTOR_DECLARED_TOUCHED_FILES_JSON` into a normalized
+ * declaration. Returns an "unspecified" result on a missing, blank, invalid-JSON,
+ * non-array, or empty (after normalization) value — the guard no-ops in every
+ * such case.
+ */
+export function parseDeclaredTouchedFilesFromEnv(env = process.env) {
+    const raw = env[DECLARED_TOUCHED_FILES_ENV];
+    if (typeof raw !== "string" || raw.trim().length === 0) {
+        return { specified: false };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return { specified: false };
+    }
+    if (!Array.isArray(parsed))
+        return { specified: false };
+    const files = normalizeDeclaredTouchedFiles(parsed);
+    if (files.length === 0)
+        return { specified: false };
+    return { specified: true, files };
+}
+const defaultSpawnSync = (command, args, options) => spawnSync(command, args, options);
+/**
+ * Collect the files changed on the current branch relative to `origin/main`
+ * using a list-based `git diff --name-only origin/main...HEAD` invocation with
+ * `shell: false`. Byte-identical files (unchanged at the branch tip) are excluded
+ * by git itself. Any spawn error / non-zero exit yields `{ ok: false }` so the
+ * caller can fail open. Never spawns a shell.
+ */
+export function collectBranchChangedFiles(opts = {}) {
+    const baseRef = opts.baseRef ?? FILE_SCOPE_GUARD_BASE_REF;
+    const spawn = opts.spawnSyncFn ?? defaultSpawnSync;
+    let result;
+    try {
+        result = spawn("git", ["diff", "--name-only", `${baseRef}...HEAD`], {
+            cwd: opts.cwd,
+            encoding: "utf-8",
+            shell: false,
+        });
+    }
+    catch {
+        return { ok: false, files: [] };
+    }
+    if (result.error || result.status !== 0) {
+        return { ok: false, files: [] };
+    }
+    const stdout = typeof result.stdout === "string"
+        ? result.stdout
+        : result.stdout?.toString("utf-8") ?? "";
+    const files = [];
+    const seen = new Set();
+    for (const line of stdout.split("\n")) {
+        const norm = normalizeRepoRelativePath(line);
+        if (norm && !seen.has(norm)) {
+            seen.add(norm);
+            files.push(norm);
+        }
+    }
+    return { ok: true, files };
+}
+/**
+ * Compare `changedFiles` against a declaration using EXACT-PATH matching (v1: no
+ * directory-ownership inference). Returns `checked:false`/no warning when the
+ * declaration is unspecified. Otherwise flags every changed file not in the
+ * declared set as out-of-scope and builds a bounded, secret-free warning naming
+ * the ticket, the out-of-scope files, and the declared set size.
+ */
+export function analyzeDiffScope(input) {
+    if (!input.declared.specified) {
+        return { checked: false, outOfScopeFiles: [], warning: null };
+    }
+    const declaredSet = new Set(input.declared.files);
+    const outOfScope = input.changedFiles
+        .filter((f) => !declaredSet.has(f))
+        .sort();
+    if (outOfScope.length === 0) {
+        return { checked: true, outOfScopeFiles: [], warning: null };
+    }
+    const ticket = input.ticketKey && input.ticketKey.trim().length > 0
+        ? input.ticketKey.trim()
+        : "unknown-ticket";
+    const warning = `[file-scope-guard] ${ticket}: ${outOfScope.length} file(s) changed outside the ` +
+        `declared touched-file set (${input.declared.files.length} declared): ` +
+        `${outOfScope.join(", ")}. Warn-only — PR creation continues.`;
+    return { checked: true, outOfScopeFiles: outOfScope, warning };
+}
+/**
+ * CLI entrypoint: parse the declaration from the env, collect the branch diff,
+ * analyze scope, and print a warning for an out-of-scope diff. ALWAYS returns
+ * exit code `0` — an unspecified declaration, a git failure, or an out-of-scope
+ * diff all leave PR creation unblocked (warn-only / fail-open). Output is bounded
+ * and secret-free; the scope warning goes to stdout (explicit CLI-mode output),
+ * the fail-open diagnostic to stderr.
+ */
+export function runFileScopeGuardCli(deps = {}) {
+    const env = deps.env ?? process.env;
+    const writeOut = deps.writeOut ?? ((m) => process.stdout.write(`${m}\n`));
+    const writeErr = deps.writeErr ?? ((m) => process.stderr.write(`${m}\n`));
+    const ticketKey = env[FILE_SCOPE_GUARD_TICKET_KEY_ENV];
+    const declared = parseDeclaredTouchedFilesFromEnv(env);
+    if (!declared.specified) {
+        // No/blank/invalid/empty declaration → nothing to check (fail-open no-op).
+        return 0;
+    }
+    const collected = collectBranchChangedFiles({
+        cwd: deps.cwd,
+        spawnSyncFn: deps.spawnSyncFn,
+    });
+    if (!collected.ok) {
+        writeErr(`[file-scope-guard] ${ticketKey ?? "unknown-ticket"}: unable to check file ` +
+            `scope (git diff failed); continuing — PR creation is not blocked.`);
+        return 0;
+    }
+    const analysis = analyzeDiffScope({
+        ticketKey,
+        declared,
+        changedFiles: collected.files,
+    });
+    if (analysis.warning) {
+        writeOut(analysis.warning);
+    }
+    return 0;
+}

package/build/conductor/github-mergeability.js

@@ -0,0 +1,85 @@
+/**
+ * Shared GitHub PR mergeability normalization + conflict classification (BAPI-494).
+ *
+ * The conductor gained ZERO mergeability awareness before this ticket: a sibling
+ * PR left `CONFLICTING`/`DIRTY` by an overlapping merge would sit at
+ * `ready_for_review` forever (catalog A4 / run-report F3). This module is the
+ * single, dependency-light source of truth for reading GitHub's
+ * `mergeable`/`mergeStateStatus` fields and deciding whether a PR is un-mergeable,
+ * so PR discovery, the done-gate binding resolution, and the local merge executor
+ * all classify a conflict the SAME way.
+ *
+ * Every helper is PURE, NON-THROWING, and FAIL-CLOSED: an unknown/missing/malformed
+ * mergeability value is treated as non-conflicting/unknown, never as a conflict, and
+ * raw `gh` process output is only ever matched against sanitized text — it is never
+ * returned, logged, or copied into event data.
+ */
+/**
+ * Normalize a raw GitHub mergeability field. Returns a trimmed, uppercased string
+ * for a non-empty string value, and `null` for every other shape (missing, empty,
+ * whitespace-only, non-string). Never throws.
+ */
+export function normalizeGhMergeabilityValue(value) {
+    if (typeof value !== "string")
+        return null;
+    const trimmed = value.trim();
+    if (trimmed.length === 0)
+        return null;
+    return trimmed.toUpperCase();
+}
+/**
+ * Read `mergeable` and `mergeStateStatus` from an already-parsed `gh pr view`
+ * JSON record and return a normalized {@link GhPrMergeability}. Unknown/malformed
+ * fields become `null` (fail-closed) so a valid PR with an unreadable mergeability
+ * value is never mistaken for a conflict.
+ */
+export function parseGhPrMergeabilityFields(record) {
+    return {
+        mergeable: normalizeGhMergeabilityValue(record.mergeable),
+        mergeStateStatus: normalizeGhMergeabilityValue(record.mergeStateStatus),
+    };
+}
+/**
+ * True only for the two authoritative conflict signals GitHub exposes:
+ * `mergeable === "CONFLICTING"` or `mergeStateStatus === "DIRTY"`. Every other
+ * combination — mergeable/clean, unknown, or null — is NOT a conflict. Fail-closed.
+ */
+export function isPrMergeConflict(mergeability) {
+    return mergeability.mergeable === "CONFLICTING" || mergeability.mergeStateStatus === "DIRTY";
+}
+/**
+ * Sanitized signatures that a `gh pr merge` failure was caused by a merge
+ * conflict / non-fast-forward condition (rather than an auth, rate-limit, network,
+ * or not-found failure). Matched case-insensitively against the sanitized failure
+ * text; the raw output itself is never returned or logged.
+ */
+const MERGE_CONFLICT_OUTPUT_SIGNATURES = [
+    "merge conflict",
+    "merge conflicts",
+    "conflicting",
+    "conflict with the base branch",
+    "not possible to fast-forward",
+    "non-fast-forward",
+    "not mergeable",
+    "is not mergeable",
+    "cannot be cleanly created",
+    "would create a merge conflict",
+];
+/**
+ * Classify raw `gh pr merge` failure output as a LIKELY merge-conflict /
+ * non-fast-forward failure. Reads only `stdout`/`stderr` text for defensive
+ * substring matching and returns a boolean — it never returns, logs, or otherwise
+ * exposes the raw process output. Returns `false` for unrelated failures
+ * (authentication, rate limit, network timeout, repository not found, generic
+ * GraphQL errors).
+ */
+export function isLikelyGhMergeConflictOutput(output) {
+    if (!output)
+        return false;
+    const stdout = typeof output.stdout === "string" ? output.stdout : "";
+    const stderr = typeof output.stderr === "string" ? output.stderr : "";
+    const haystack = `${stdout}\n${stderr}`.toLowerCase();
+    if (haystack.trim().length === 0)
+        return false;
+    return MERGE_CONFLICT_OUTPUT_SIGNATURES.some((sig) => haystack.includes(sig));
+}

package/build/conductor/local-merge.js

@@ -18,6 +18,7 @@
  */
 import { spawnSync } from "child_process";
 import { pollCiChecksForCommit, } from "./bridge-api-client.js";
+import { isLikelyGhMergeConflictOutput, isPrMergeConflict, parseGhPrMergeabilityFields, } from "./github-mergeability.js";
 const MERGE_METHODS = new Set(["squash", "merge", "rebase"]);
 /**
  * Hard wall-clock cap on every `gh` subprocess. The epic-tick runs in a single
@@ -180,7 +181,52 @@ export function makeLocalMergeExecutor(options = {}, deps = {}) {
         // 4. Provider merge.
         const merge = run("gh", ["pr", "merge", String(pr), `--${method}`, "--match-head-commit", expectedSha], ghEnv);
         if (merge.status !== 0) {
-            const mergeFailReason = merge.timedOut ? "gh_merge_timeout" : "gh_merge_failed";
+            // A hung `gh` (killed by the wall-clock timeout) is operationally distinct
+            // from a permission/conflict failure — keep it mapped to gh_merge_timeout.
+            if (merge.timedOut) {
+                const reason = "gh_merge_timeout";
+                return buildResponse(request, "failed", reason, false, [
+                    { type: "merge.attempted", status: "attempted", details: baseDetails },
+                    { type: "merge.failed", status: "failed", reason, details: baseDetails },
+                ]);
+            }
+            // BAPI-494: classify a conflict / non-fast-forward failure distinctly so it
+            // folds to `blocked` and remediates instead of hiding behind gh_merge_failed.
+            // First match the sanitized failure output; if inconclusive, do ONE follow-up
+            // mergeability re-read (only AFTER a merge failure — never before a successful
+            // or guarded merge) and check it. Raw stdout/stderr is used only for defensive
+            // classification and is never copied into event data or logs.
+            let mergeability = { mergeable: null, mergeStateStatus: null };
+            let isConflict = isLikelyGhMergeConflictOutput(merge);
+            if (!isConflict) {
+                const recheck = run("gh", ["pr", "view", String(pr), "--json", "mergeable,mergeStateStatus"], ghEnv);
+                if (recheck.status === 0) {
+                    try {
+                        mergeability = parseGhPrMergeabilityFields(JSON.parse(recheck.stdout));
+                        isConflict = isPrMergeConflict(mergeability);
+                    }
+                    catch {
+                        /* best-effort classification only */
+                    }
+                }
+            }
+            if (isConflict) {
+                const reason = "gh_merge_conflict";
+                // Head-scoped to the attempted head SHA so the fold blocks the exact head; a
+                // later rebase clears it via the stale-head logic. mergeable/mergeStateStatus
+                // are included only when known.
+                const conflictDetails = {
+                    ...baseDetails,
+                    head_sha: expectedSha,
+                    ...(mergeability.mergeable ? { mergeable: mergeability.mergeable } : {}),
+                    ...(mergeability.mergeStateStatus ? { mergeStateStatus: mergeability.mergeStateStatus } : {}),
+                };
+                return buildResponse(request, "failed", reason, false, [
+                    { type: "merge.attempted", status: "attempted", details: baseDetails },
+                    { type: "merge.conflict", status: "failed", reason, details: conflictDetails },
+                ]);
+            }
+            const mergeFailReason = "gh_merge_failed";
             return buildResponse(request, "failed", mergeFailReason, false, [
                 { type: "merge.attempted", status: "attempted", details: baseDetails },
                 { type: "merge.failed", status: "failed", reason: mergeFailReason, details: baseDetails },

package/build/conductor/merge-identity.js

@@ -0,0 +1,41 @@
+/**
+ * Low-level merge-identity primitives (BAPI-493).
+ *
+ * Extracted from `merge-ledger.ts` so the typed event-accessor layer
+ * (`event-accessors.ts`) can build a canonical {@link MergeActionIdentity}
+ * without importing the merge-ledger store/emit surface (which would create an
+ * import cycle: merge-ledger → event-accessors → merge-ledger).
+ *
+ * This module depends ONLY on the pure boundary validators in `git-ci-types.ts`.
+ * It performs no I/O and holds no VCS write credentials. The deterministic action
+ * key `merge:{repo}:{pr}:{head_sha}:{gate}` is kept in lock-step with the Python
+ * `build_merge_action_key`; the gate-identity segment mirrors the Python
+ * `normalize_gate_identity`.
+ */
+import { normalizePrNumber, normalizeRepoName, normalizeSha } from "./git-ci-types.js";
+/**
+ * Compose the stable gate-identity segment, mirroring the Python
+ * `normalize_gate_identity`: `{name}@{config_hash}` when a hash is present
+ * (lower-cased), otherwise just the gate name.
+ */
+export function buildGateIdentity(gateName, configHash) {
+    const name = gateName.trim();
+    const hash = typeof configHash === "string" ? configHash.trim() : "";
+    return hash ? `${name}@${hash.toLowerCase()}` : name;
+}
+/**
+ * Build the deterministic action key. Normalizes repo / PR / head SHA exactly as
+ * the Python side does (lower-cased SHA, trimmed repo, positive integer PR) so the
+ * conductor-computed key and the API-recomputed key are byte-identical. Throws on
+ * any invalid component. The branch name is never part of the key.
+ */
+export function makeMergeActionKey(repo, prNumber, headSha, gateIdentity) {
+    const r = normalizeRepoName(repo);
+    const pr = normalizePrNumber(prNumber);
+    const sha = normalizeSha(headSha);
+    const gate = (gateIdentity ?? "").trim();
+    if (r === null || pr === null || sha === null || gate.length === 0) {
+        throw new Error("invalid merge action key component");
+    }
+    return `merge:${r}:${pr}:${sha}:${gate}`;
+}