@bridge_gpt/mcp-server 0.2.59 → 0.2.60

package/build/conductor/local-merge.js

@@ -31,6 +31,27 @@
  * Subprocess safety: argument arrays (never a shell string), a validated numeric
  * PR number, a merge method from a fixed allowlist, `GH_PROMPT_DISABLED` to avoid
  * interactive hangs, and no token/secret ever logged. Default OFF everywhere.
+ *
+ * BAPI-1136 de-personalization:
+ *  - The merge no longer authenticates as whoever happens to be logged into `gh`
+ *    on the machine running this process. It authenticates with ONE explicitly
+ *    configured, customer-held scoped credential — either a configured local
+ *    credential or a machine-user credential — supplied through
+ *    {@link LocalMergeDeps.credential}. Bridge never stores either one.
+ *  - The child environment is now built from an ALLOWLIST rather than inherited
+ *    wholesale. `GH_TOKEN`, `GITHUB_TOKEN`, and both Bridge configuration keys
+ *    are excluded from the inherited base, so an ambient login cannot leak in
+ *    through the back door after the front door was closed.
+ *  - No credential means no privileged subprocess. The guard lives inside the
+ *    shared executor, so an overlooked caller fails closed with a named reason
+ *    instead of running `gh` unauthenticated.
+ *  - Captured stdout/stderr is sanitized before it leaves the runner, so a `gh`
+ *    message that echoes an environment assignment or a token cannot reach a
+ *    ledger event, an MCP envelope, or a dry-run serialization.
+ *
+ * The decision ladder itself is UNCHANGED: which credential authenticates the
+ * subprocess is a different question from what the executor decides, and this
+ * module answers only the first.
  */
 import { spawn } from "child_process";
 import { pollCiChecksForCommit, ConductorBridgeApiError, safeDiagnosticMessage, } from "./bridge-api-client.js";
@@ -91,6 +112,163 @@ export function resolveLocalMergeMethod(value) {
         ? value
         : "squash";
 }
+/**
+ * The one process-launch configuration key each credential kind reads.
+ *
+ * There is NO fallback between them and no fallback to anything else: not to an
+ * inherited `GH_TOKEN` or `GITHUB_TOKEN`, not to a `gh auth` session, and not to
+ * the Bridge credential store. A merge mode that silently borrowed the other
+ * mode's credential would make "which identity performed this write" unanswerable
+ * from the run's own configuration, which is the property this whole change
+ * exists to establish.
+ *
+ * Neither key is ever routed through `resolveBapiCredentials`,
+ * `resolveCredentialBundle`, project configuration, or install state. A GitHub
+ * merge credential is not a Bridge credential and must not acquire Bridge's
+ * persistence.
+ */
+export const LOCAL_MERGE_CREDENTIAL_ENV_KEYS = {
+    local: "BAPI_LOCAL_MERGE_TOKEN",
+    machine_token: "BAPI_MACHINE_MERGE_TOKEN",
+};
+/** The named, mode-specific refusal when the configured credential is absent. */
+export const LOCAL_MERGE_CREDENTIAL_MISSING_REASONS = {
+    local: "local_merge_credential_missing",
+    machine_token: "machine_merge_credential_missing",
+};
+/**
+ * Resolve the one credential a kind is allowed to read.
+ *
+ * Returns `null` for an absent or blank value — never the other kind's value and
+ * never an inherited one.
+ */
+export function resolveLocalMergeCredential(env, kind) {
+    const raw = env[LOCAL_MERGE_CREDENTIAL_ENV_KEYS[kind]];
+    if (typeof raw !== "string")
+        return null;
+    const token = raw.trim();
+    if (token.length === 0)
+        return null;
+    return { kind, token };
+}
+/**
+ * Environment variables the `gh` child is allowed to inherit.
+ *
+ * An allowlist, not a denylist. `gh` needs a working PATH, a home directory, a
+ * temporary directory, a locale, certificate configuration, and proxy settings;
+ * it needs nothing else this process happens to be carrying. Inheriting the
+ * whole environment is how an ambient login survives every attempt to remove it,
+ * and it is also how an unrelated secret ends up in a subprocess that writes to
+ * a public repository.
+ */
+const CHILD_ENV_ALLOWLIST = [
+    // Resolution and platform basics.
+    "PATH",
+    "Path",
+    "PATHEXT",
+    "HOME",
+    "USERPROFILE",
+    "SystemRoot",
+    "SYSTEMROOT",
+    "windir",
+    "COMSPEC",
+    "ComSpec",
+    // Temporary directories.
+    "TMPDIR",
+    "TEMP",
+    "TMP",
+    // Locale.
+    "LANG",
+    "LC_ALL",
+    "LC_CTYPE",
+    // TLS trust.
+    "SSL_CERT_FILE",
+    "SSL_CERT_DIR",
+    "CURL_CA_BUNDLE",
+    "NODE_EXTRA_CA_CERTS",
+    // Proxies.
+    "HTTP_PROXY",
+    "HTTPS_PROXY",
+    "NO_PROXY",
+    "http_proxy",
+    "https_proxy",
+    "no_proxy",
+];
+/**
+ * Keys that must never reach the child from an inherited environment, even if a
+ * future edit widens the allowlist above.
+ *
+ * `GH_TOKEN` appears here AND is injected explicitly below. That is not a
+ * contradiction: the inherited one is an ambient identity and is dropped, while
+ * the injected one is the resolved credential this run was configured with.
+ */
+const CHILD_ENV_DENYLIST = new Set([
+    "GH_TOKEN",
+    "GITHUB_TOKEN",
+    "BAPI_LOCAL_MERGE_TOKEN",
+    "BAPI_MACHINE_MERGE_TOKEN",
+]);
+/**
+ * Build the complete `gh` child environment.
+ *
+ * Exactly three sources, in this order: the allowlisted operational base, the
+ * non-interactive pins, and the one resolved credential as `GH_TOKEN`. A caller
+ * cannot add a fourth — `extra` is filtered through the same denylist, so an
+ * overlooked call site passing `{ ...process.env }` or an explicit
+ * `GITHUB_TOKEN` contributes neither.
+ */
+export function buildLocalMergeChildEnv(base, credential, extra = {}) {
+    const child = {};
+    for (const key of CHILD_ENV_ALLOWLIST) {
+        if (CHILD_ENV_DENYLIST.has(key))
+            continue;
+        const value = base[key];
+        if (typeof value === "string")
+            child[key] = value;
+    }
+    for (const [key, value] of Object.entries(extra)) {
+        if (CHILD_ENV_DENYLIST.has(key))
+            continue;
+        if (typeof value === "string")
+            child[key] = value;
+    }
+    // The pins come after `extra` so a caller cannot re-enable an interactive
+    // prompt that would hang a merge nobody is watching.
+    child.GH_PROMPT_DISABLED = "1";
+    child.GH_NO_UPDATE_NOTIFIER = "1";
+    if (credential)
+        child.GH_TOKEN = credential.token;
+    return child;
+}
+/** Fixed replacement for anything redacted out of captured output. */
+const REDACTED = "[redacted]";
+/**
+ * Strip credential-shaped material from captured subprocess output.
+ *
+ * Applied before a {@link LocalCommandResult} leaves the runner, so every
+ * downstream consumer — ledger events, MCP envelopes, dry-run serializations,
+ * diagnostic strings — is working from already-sanitized text rather than each
+ * remembering to sanitize for itself.
+ *
+ * Two passes. First, any `KEY=value` assignment for a known credential key,
+ * because `gh` and git both echo environment in some error paths. Second, the
+ * literal credential values this run holds, which catches a token echoed without
+ * its key.
+ */
+export function sanitizeLocalMergeOutput(text, credentials = []) {
+    if (typeof text !== "string" || text.length === 0)
+        return "";
+    let out = text;
+    for (const key of CHILD_ENV_DENYLIST) {
+        out = out.split(new RegExp(`${key}=\\S*`, "g")).join(`${key}=${REDACTED}`);
+    }
+    for (const value of credentials) {
+        if (typeof value === "string" && value.length >= 8) {
+            out = out.split(value).join(REDACTED);
+        }
+    }
+    return out;
+}
 /**
  * Async, abort-aware default command runner. Uses `spawn` (never a synchronous
  * runner) so a slow/hung `gh` does not block the Node event loop — the heartbeat
@@ -100,12 +278,18 @@ export function resolveLocalMergeMethod(value) {
  * never logs raw stdout/stderr.
  */
 async function defaultRunCommand(cmd, args, env, signal) {
+    // BAPI-1136: `env` arrives ALREADY built by `buildLocalMergeChildEnv` and is
+    // the complete child environment. The former `{ ...process.env, ...env }`
+    // merge is gone — it re-inherited the ambient identity the caller had just
+    // finished excluding, which made every de-personalization upstream cosmetic.
+    const childEnv = env ?? buildLocalMergeChildEnv(process.env, null);
+    const credentialValues = [childEnv.GH_TOKEN];
     return await new Promise((resolve) => {
         let settled = false;
         let timedOut = false;
         let stdout = "";
         let stderr = "";
-        const child = spawn(cmd, args, { env: { ...process.env, ...env } });
+        const child = spawn(cmd, args, { env: childEnv });
         const killChild = () => {
             try {
                 child.kill("SIGKILL");
@@ -129,7 +313,13 @@ async function defaultRunCommand(cmd, args, env, signal) {
             clearTimeout(timer);
             if (signal)
                 signal.removeEventListener("abort", onAbort);
-            resolve(result);
+            // Sanitize HERE, at the single point every path resolves through, so no
+            // downstream consumer has to remember to do it.
+            resolve({
+                ...result,
+                stdout: sanitizeLocalMergeOutput(result.stdout, credentialValues),
+                stderr: sanitizeLocalMergeOutput(result.stderr, credentialValues),
+            });
         };
         if (signal) {
             if (signal.aborted)
@@ -486,13 +676,11 @@ export function makeLocalMergeExecutor(options = {}, deps = {}) {
     const signal = deps.signal;
     const ciWaitTimeoutMs = sanitizeWaitMs(options.ciWaitTimeoutMs, DEFAULT_CI_WAIT_TIMEOUT_MS);
     const ciWaitPollIntervalMs = sanitizeWaitMs(options.ciWaitPollIntervalMs, DEFAULT_CI_WAIT_POLL_INTERVAL_MS);
-    // Non-interactive + no-noise env for gh; the caller's env (incl. any token)
-    // is overlaid first, then the safety pins.
-    const ghEnv = {
-        ...deps.env,
-        GH_PROMPT_DISABLED: "1",
-        GH_NO_UPDATE_NOTIFIER: "1",
-    };
+    // BAPI-1136: an allowlisted operational base plus exactly one resolved
+    // credential. The caller's environment contributes PATH and friends; it
+    // contributes no identity.
+    const credential = deps.credential ?? null;
+    const ghEnv = buildLocalMergeChildEnv(deps.env ?? process.env, credential);
     return async (access, request) => {
         const pr = request.pr_number;
         const expectedSha = request.expected_head_sha;
@@ -523,6 +711,15 @@ export function makeLocalMergeExecutor(options = {}, deps = {}) {
                 { type: "merge.failed", status: "failed", reason, details },
             ]);
         };
+        // BAPI-1136, defense in depth. The credential is resolved by the CALLER, and
+        // every production caller now does so explicitly — but a caller that forgot
+        // must not reach a privileged `gh` subprocess unauthenticated, silently
+        // falling back to whatever identity the runner happens to carry. Refusing
+        // here, before the first read, makes that structural rather than a
+        // convention every future call site has to remember.
+        if (!credential) {
+            return fail(LOCAL_MERGE_CREDENTIAL_MISSING_REASONS.local);
+        }
         /**
          * Re-check the merged state after an AMBIGUOUS `gh` failure (a `gh` timeout,
          * an unparseable/failed view, a CI poll failure, or a generic non-conflict
@@ -784,15 +981,79 @@ function buildRefMismatchResponse(request, baseDetails, mismatch) {
         { type: "merge.failed", status: "failed", reason, details },
     ]);
 }
+// --------------------------------------------------------------------------- //
+// BAPI-832: local execution of a server-approved merge
+// --------------------------------------------------------------------------- //
+/** A provider repository identity: exactly one `/`, no whitespace or globbing. */
+const OWNER_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*\/[A-Za-z0-9][A-Za-z0-9._-]*$/;
 /**
- * Probe whether this host can merge with `gh` at all, BEFORE any merge is
- * attempted.
+ * Resolve the `owner/name` the permission probe should ask about.
  *
- * 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".
+ * Prefers a caller-supplied identity, falls back to asking `gh` which repository
+ * it resolves here, and returns `null` when neither produces a well-formed
+ * value. `null` SKIPS the probe rather than failing it: not knowing which
+ * repository to ask about is not evidence that the credential lacks permission,
+ * and refusing on it would break every host whose working directory is not a
+ * checkout. The merge's own guards still refuse an actually-unpermitted token —
+ * only the finer diagnosis is unavailable.
+ */
+async function resolveProbeRepository(run, ghEnv, supplied) {
+    if (typeof supplied === "string" && OWNER_NAME_PATTERN.test(supplied.trim())) {
+        return supplied.trim();
+    }
+    let view;
+    try {
+        view = await run("gh", ["repo", "view", "--json", "nameWithOwner", "--jq", ".nameWithOwner"], ghEnv);
+    }
+    catch {
+        return null;
+    }
+    if (view.status !== 0)
+        return null;
+    const resolved = view.stdout.trim();
+    return OWNER_NAME_PATTERN.test(resolved) ? resolved : null;
+}
+/** Mode-specific reason triples, so no call site re-derives a spelling. */
+const PREFLIGHT_REASONS = {
+    local: {
+        missing: "local_merge_credential_missing",
+        invalid: "local_merge_credential_invalid",
+        unpermitted: "local_merge_credential_unpermitted",
+    },
+    machine_token: {
+        missing: "machine_merge_credential_missing",
+        invalid: "machine_merge_credential_invalid",
+        unpermitted: "machine_merge_credential_unpermitted",
+    },
+};
+/**
+ * Probe whether this host can merge with the CONFIGURED credential, before any
+ * merge is attempted.
+ *
+ * Without this the operator-fixable failures are invisible: a missing `gh`, an
+ * unconfigured credential, an expired one, and one that authenticates but lacks
+ * write access to this repository all make `gh pr view` exit non-zero, which
+ * this module would otherwise report as `gh_pr_view_failed` — a reason that
+ * names no fix.
+ *
+ * BAPI-1136 changed the QUESTION this asks. It used to ask "is the ambient `gh`
+ * logged in", which is the wrong question once the merge no longer uses an
+ * ambient identity: a host with a logged-in operator and no configured
+ * credential would pass a probe and then fail the merge. It now asks "is the
+ * credential this run was configured with usable HERE, for THIS repository",
+ * which is the question whose answer predicts the merge.
+ *
+ * Four outcomes, each fail-closed:
+ *
+ *   1. `gh` cannot be invoked -> `local_gh_unavailable`.
+ *   2. No credential configured -> the kind's `*_credential_missing`, returned
+ *      BEFORE any privileged subprocess runs.
+ *   3. `gh auth status` rejects the credential -> the kind's `*_credential_invalid`.
+ *   4. The repository permission probe does not prove write access -> the kind's
+ *      `*_credential_unpermitted`.
+ *
+ * A network failure or an unparseable capability response is bounded and lands
+ * on (4) rather than passing: an unprovable permission is not permission.
  *
  * Deliberately async and built on the same `run` seam as the merge itself. The
  * read-only equivalent in `conductor/doctor.ts` (`inspectLocalMerge`) probes
@@ -801,7 +1062,8 @@ function buildRefMismatchResponse(request, baseDetails, mismatch) {
  * (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) {
+export async function preflightLocalGh(run, ghEnv, context = { kind: "local" }) {
+    const reasons = PREFLIGHT_REASONS[context.kind] ?? PREFLIGHT_REASONS.local;
     let version;
     try {
         version = await run("gh", ["--version"], ghEnv);
@@ -811,15 +1073,41 @@ export async function preflightLocalGh(run, ghEnv) {
     }
     if (version.status !== 0)
         return { ok: false, reason: "local_gh_unavailable" };
+    // The credential check comes AFTER the capability check and BEFORE every
+    // privileged call: "gh is missing" and "gh is fine but nothing configured it"
+    // are different fixes, and neither should cost an authenticated request.
+    const credentialPresent = context.credentialPresent ?? (typeof ghEnv.GH_TOKEN === "string" && ghEnv.GH_TOKEN.length > 0);
+    if (!credentialPresent)
+        return { ok: false, reason: reasons.missing };
     let auth;
     try {
         auth = await run("gh", ["auth", "status"], ghEnv);
     }
     catch {
-        return { ok: false, reason: "local_gh_unauthenticated" };
+        return { ok: false, reason: reasons.invalid };
     }
     if (auth.status !== 0)
-        return { ok: false, reason: "local_gh_unauthenticated" };
+        return { ok: false, reason: reasons.invalid };
+    // A credential can authenticate and still be unable to merge — a read-scoped
+    // token, or a machine user who was never granted write on this repository.
+    // That distinction is the difference between "rotate the token" and "grant the
+    // account access", so it is worth one read-only request to establish.
+    const repository = await resolveProbeRepository(run, ghEnv, context.repository);
+    if (repository !== null) {
+        let probe;
+        try {
+            probe = await run("gh", ["api", `repos/${repository}`, "--jq", ".permissions.push"], ghEnv);
+        }
+        catch {
+            return { ok: false, reason: reasons.unpermitted };
+        }
+        if (probe.status !== 0)
+            return { ok: false, reason: reasons.unpermitted };
+        // Bounded parse. Anything that is not an explicit `true` fails closed; raw
+        // `gh` output is never surfaced, only this verdict.
+        if (probe.stdout.trim() !== "true")
+            return { ok: false, reason: reasons.unpermitted };
+    }
     return { ok: true };
 }
 /**
@@ -840,14 +1128,19 @@ export async function preflightLocalGh(run, ghEnv) {
  * 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",
-    };
+    // BAPI-1136: one allowlisted child environment carrying exactly one resolved
+    // credential — never the caller's environment spread in wholesale.
+    const credential = deps.credential ?? null;
+    const ghEnv = buildLocalMergeChildEnv(deps.env ?? process.env, credential);
     const rawRun = deps.runCommand ?? defaultRunCommand;
     const run = (cmd, args, env) => Promise.resolve(rawRun(cmd, args, env, deps.signal));
-    const preflight = await preflightLocalGh(run, ghEnv);
+    // `request.repo_name` is Bridge's own repository name, NOT `owner/name`, so it
+    // is deliberately not passed here — the probe resolves the provider identity
+    // itself, or skips.
+    const preflight = await preflightLocalGh(run, ghEnv, {
+        kind: credential?.kind ?? "local",
+        credentialPresent: credential !== null,
+    });
     if (!preflight.ok) {
         return buildResponse(request, "failed", preflight.reason, false, [
             {
@@ -864,7 +1157,7 @@ export async function runApprovedLocalMerge(request, options = {}, deps = {}) {
             },
         ]);
     }
-    const executor = makeLocalMergeExecutor({ method: options.method, skipCiWait: true }, deps);
+    const executor = makeLocalMergeExecutor({ method: options.method, skipCiWait: true }, { ...deps, credential });
     // `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

package/build/conductor/merge-execution-contract.js

@@ -0,0 +1,61 @@
+/**
+ * The TypeScript MIRROR of the shared merge-execution contract (BAPI-1135).
+ *
+ * The Python original is `api/library/epic_implementer/merge_execution_contract.py`
+ * (plus `pre_create_refusal.py` for the refusal code). The two runtimes do not
+ * share code, so the contract is mirrored VALUE FOR VALUE here and every
+ * spelling below must match its Python twin byte for byte.
+ *
+ * ## Why literals, not client aliases
+ *
+ * Each constant is an exported literal rather than a re-export of a parsed
+ * server field. A refusal message built from a server-echoed string would be a
+ * second spelling the moment the server stopped echoing it; a message built from
+ * THIS constant is the same string the server's own refusal carries. The closed
+ * refusal-reason union in `setup-epic.ts` is likewise derived from
+ * {@link MERGE_EXECUTION_INELIGIBLE} rather than re-typed, so the union cannot
+ * drift through a third handwritten spelling.
+ *
+ * ## What this module does not do
+ *
+ * It performs no probe, no repository read, and no dispatch. Every fact it is
+ * compared against arrives from the SERVER's readiness report. A client that
+ * inspected a local checkout to decide merge eligibility would be answering a
+ * different question from the one the server's before-merge preflight answers.
+ *
+ * ## Deferred remedy
+ *
+ * {@link MERGE_WORKFLOW_REMEDY_COMMAND} names the generate-and-PR command epic
+ * child 4 ships. Until child 4 lands, a refusal may name a command that is not
+ * yet an executable entry point on the operator's machine. That residual risk,
+ * its three containments, and who owns escalation are recorded once, in the
+ * Python module's docstring; this mirror does not restate them.
+ */
+/** The one `RunPolicy.merge_execution_mode` value this contract governs. */
+export const MERGE_EXECUTION_MODE_GITHUB_ACTIONS = "github_actions";
+/**
+ * The server-owned pre-create refusal code.
+ *
+ * Mirrors `api/library/epic_implementer/pre_create_refusal.py`. The client adds
+ * remediation TEXT around this code and invents no alias.
+ */
+export const MERGE_EXECUTION_INELIGIBLE = "merge_execution_ineligible";
+/** The canonical merge workflow's repository-relative path on the default branch. */
+export const MERGE_WORKFLOW_PATH = ".github/workflows/epic-implementer-merge.yml";
+/** The workflow's stable file-name identifier, as the Actions API accepts it. */
+export const MERGE_WORKFLOW_IDENTIFIER = "epic-implementer-merge.yml";
+/** The top-level workflow key carrying the machine-readable contract version. */
+export const MERGE_WORKFLOW_VERSION_MARKER_KEY = "x-bridge-merge-contract-version";
+/**
+ * The ONLY workflow contract version this CLI understands.
+ *
+ * Exact equality. A newer version is a workflow this build has never been taught
+ * to reason about, so it is NOT eligible — see
+ * {@link classifyMergeExecutionEligibility}.
+ */
+export const MERGE_WORKFLOW_EXPECTED_VERSION = 1;
+/**
+ * The single command that generates the merge workflow and opens its pull
+ * request. Every refusal, remediation, and readiness line imports this constant.
+ */
+export const MERGE_WORKFLOW_REMEDY_COMMAND = "install-bridge conductor --merge-workflow";

package/build/conductor/merge-execution-eligibility.js

@@ -0,0 +1,129 @@
+/**
+ * The ONE client-side merge-execution eligibility classifier (BAPI-1135).
+ *
+ * Three surfaces act on repository merge eligibility — the readiness sections,
+ * the `drive-epic` v2 readiness requirement, and the `setup-epic` pre-create
+ * refusal. If each read the server block itself they would drift, and an
+ * operator told "ready" by one and refused by another would have no way to tell
+ * which was right. So the classification lives here and each surface only
+ * renders it, exactly as `bring-up-facts.ts` does for the bring-up facts.
+ *
+ * PURE. No probe, network call, filesystem access, or spawn. It reads an
+ * already-parsed readiness response and returns a closed verdict. In particular
+ * it never inspects a local checkout: a client that decided merge eligibility
+ * from local files would be answering a different question from the one the
+ * server's before-merge preflight answers.
+ *
+ * ## The three decisive states, and why unknown is its own state
+ *
+ * `eligible` / `not_eligible` / `could_not_verify`. The third is not a
+ * convenience — it is the whole safety property. "The workflow is absent" and
+ * "the probe failed" produce the same *blocking* outcome but completely
+ * different operator actions: one installs a workflow, the other fixes
+ * credentials or connectivity. Collapsing them sends half of all operators to do
+ * work that changes nothing. `could_not_verify` is never treated as eligible.
+ *
+ * ## Exact version, always
+ *
+ * Eligibility requires {@link MERGE_WORKFLOW_EXPECTED_VERSION} exactly. A NEWER
+ * version is not eligible either: it is a workflow this build has never been
+ * taught to reason about, and "newer is probably fine" is a guess about a merge
+ * actuator.
+ */
+import { MERGE_WORKFLOW_EXPECTED_VERSION, MERGE_WORKFLOW_REMEDY_COMMAND, } from "./merge-execution-contract.js";
+/**
+ * Remediation for a verdict that could not be established.
+ *
+ * Retry-oriented on purpose: it directs the operator at credentials,
+ * permissions, and connectivity, and it never claims the capability is absent.
+ * Telling someone to install a workflow that is already installed is the failure
+ * mode this wording exists to avoid.
+ */
+export const MERGE_EXECUTION_UNVERIFIABLE_REMEDIATION = "re-run once the Bridge API is reachable and repository credentials resolve; merge " +
+    "eligibility is UNKNOWN here, not confirmed missing. If the server reports no " +
+    "merge-execution block at all, upgrade the Bridge API deploy.";
+/**
+ * Remediation for a CONFIRMED insufficiency. Names the one command that fixes it.
+ *
+ * Built from the shared constant rather than written out, so a rename in the
+ * contract lands here without an edit and no surface can spell the command a
+ * second way.
+ */
+export const MERGE_EXECUTION_INELIGIBLE_REMEDIATION = `run \`${MERGE_WORKFLOW_REMEDY_COMMAND}\` to generate the merge workflow and open its ` +
+    "pull request, then re-run once it is merged to the default branch.";
+function unverifiable(reason, detail) {
+    return {
+        status: "could_not_verify",
+        reason,
+        detail,
+        remediation: MERGE_EXECUTION_UNVERIFIABLE_REMEDIATION,
+    };
+}
+function ineligible(reason, detail) {
+    return {
+        status: "not_eligible",
+        reason,
+        detail,
+        remediation: MERGE_EXECUTION_INELIGIBLE_REMEDIATION,
+    };
+}
+/**
+ * Classify this repository's merge-execution eligibility, FAIL-CLOSED.
+ *
+ * Reads only the parsed server report and re-derives nothing. The order below is
+ * "could not tell" before "confirmed bad", fact by fact, so an operator is never
+ * told to repair a condition that could not even be read.
+ *
+ * `eligible` requires the FULL truth table simultaneously: both probes
+ * succeeded, the workflow is present and enabled at the exact expected version,
+ * the App holds `actions: write`, the workflow token holds write authority, the
+ * branch policy was readable, and the workflow actor is admitted. Any one of
+ * them missing is decisive.
+ *
+ * The shared remedy command appears only as remediation METADATA. Nothing here
+ * executes it, and nothing infers repository state locally to decide whether it
+ * is needed.
+ */
+export function classifyMergeExecutionEligibility(readiness) {
+    const m = readiness.merge_execution;
+    if (m === null || m === undefined) {
+        return unverifiable("block_unreported", "this Bridge API deploy does not report merge-execution eligibility");
+    }
+    const gh = readiness.github;
+    // The App permission probe comes first: without it, "actions: write denied"
+    // below cannot be distinguished from "never checked".
+    if (!gh.actions_probe_succeeded) {
+        return unverifiable("app_actions_probe_failed", "the GitHub App actions permission could not be checked");
+    }
+    if (!m.merge_workflow_probe_succeeded) {
+        return unverifiable("workflow_probe_failed", "the merge workflow's metadata could not be read");
+    }
+    if (!m.branch_protection_probe_succeeded) {
+        return unverifiable("branch_policy_unreadable", `the branch policy on the ${m.branch_scope.replace("_", " ")} could not be read`);
+    }
+    if (!m.merge_workflow_present) {
+        return ineligible("workflow_absent", "the merge workflow is not present");
+    }
+    if (!m.merge_workflow_enabled) {
+        return ineligible("workflow_disabled", "the merge workflow is present but disabled");
+    }
+    if (m.merge_workflow_version !== MERGE_WORKFLOW_EXPECTED_VERSION) {
+        // A newer version lands here too — see the module docstring.
+        return ineligible("workflow_version_mismatch", `merge workflow version ${m.merge_workflow_version ?? "unset"} ` +
+            `(expected ${MERGE_WORKFLOW_EXPECTED_VERSION})`);
+    }
+    if (!gh.actions_write) {
+        return ineligible("app_actions_write_denied", `the GitHub App holds actions: ${gh.actions_permission_level}`);
+    }
+    if (!m.merge_workflow_token_write_authority) {
+        return ineligible("workflow_token_write_denied", "the merge workflow's own token does not hold write authority");
+    }
+    if (!m.branch_protection_actions_bot_admitted) {
+        return ineligible("actor_not_admitted", "the branch policy does not admit the workflow actor");
+    }
+    return {
+        status: "eligible",
+        detail: `merge workflow present, enabled, version ${MERGE_WORKFLOW_EXPECTED_VERSION}; ` +
+            "App actions: write, workflow token write authority, workflow actor admitted",
+    };
+}