@bridge_gpt/mcp-server 0.2.68 → 0.2.70

package/build/conductor/local-merge.js

@@ -112,45 +112,16 @@ 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",
-};
+// BAPI-1452: the credential kinds, keys, and resolver live in a dependency-free
+// module so read-only callers need not import this executor; re-exported here
+// so this module's public surface is unchanged.
+import { LOCAL_MERGE_CREDENTIAL_ALIAS_ENV_KEY, LOCAL_MERGE_CREDENTIAL_ENV_KEYS, resolveLocalMergeCredential, resolveLocalMergeCredentialDetailed, } from "./merge-credential.js";
+export { LOCAL_MERGE_CREDENTIAL_ALIAS_ENV_KEY, LOCAL_MERGE_CREDENTIAL_ENV_KEYS, resolveLocalMergeCredential, resolveLocalMergeCredentialDetailed, };
 /** 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.
  *
@@ -205,6 +176,8 @@ const CHILD_ENV_ALLOWLIST = [
 const CHILD_ENV_DENYLIST = new Set([
     "GH_TOKEN",
     "GITHUB_TOKEN",
+    // BAPI-1452: the canonical local key, alongside its deprecated alias.
+    "GITHUB_MERGE_TOKEN",
     "BAPI_LOCAL_MERGE_TOKEN",
     "BAPI_MACHINE_MERGE_TOKEN",
 ]);
@@ -1013,19 +986,141 @@ async function resolveProbeRepository(run, ghEnv, supplied) {
     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. */
+/** Map a preflight result to its kind-independent verdict (BAPI-1452). */
+export function classifyLocalGhPreflight(result) {
+    if (result.ok)
+        return "passed";
+    switch (result.reason) {
+        case "local_gh_unavailable":
+            return "gh_unavailable";
+        case "local_merge_credential_missing":
+        case "machine_merge_credential_missing":
+            return "credential_missing";
+        case "local_merge_credential_invalid":
+        case "machine_merge_credential_invalid":
+            return "credential_invalid";
+        case "local_merge_credential_unpermitted":
+        case "machine_merge_credential_unpermitted":
+            return "no_access";
+        case "local_merge_probe_unavailable":
+        case "machine_merge_probe_unavailable":
+            return "probe_unavailable";
+    }
+}
+/** Mode-specific reason sets, 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",
+        unavailable: "local_merge_probe_unavailable",
     },
     machine_token: {
         missing: "machine_merge_credential_missing",
         invalid: "machine_merge_credential_invalid",
         unpermitted: "machine_merge_credential_unpermitted",
+        unavailable: "machine_merge_probe_unavailable",
     },
 };
+// --------------------------------------------------------------------------- //
+// BAPI-1452: bounded parsing of one `gh api --include` response
+// --------------------------------------------------------------------------- //
+/** Status line of an `--include` response: anchored, first line only. */
+const HTTP_STATUS_LINE_PATTERN = /^HTTP\/\S+ ([0-9]{3})(?:\s|$)/;
+/** `gh`'s own error suffix, e.g. `gh: Not Found (HTTP 404)`. Bounded digits. */
+const GH_STDERR_STATUS_PATTERN = /\(HTTP ([0-9]{3})\)/;
+/** One response header line. Anything else in the header block is malformed. */
+const HTTP_HEADER_LINE_PATTERN = /^[!#$%&'*+.^_`|~0-9A-Za-z-]+:[^\n]*$/;
+/**
+ * Hard cap on the output a probe will parse. A repository record or a one-item
+ * pull-request page is tens of kilobytes; anything near this is not a response
+ * this probe understands.
+ */
+const MAX_PROBE_OUTPUT_CHARS = 2_000_000;
+/** Bounded prefix of stderr searched for the fallback status. */
+const MAX_PROBE_STDERR_SCAN_CHARS = 4_096;
+/** Parse a JSON body, returning `undefined` when it is not valid JSON. */
+function parseProbeBody(body) {
+    try {
+        return JSON.parse(body);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Run one `gh api --include` read and reduce it to a status plus parsed body.
+ *
+ * The status comes ONLY from stdout's first line. When a non-zero command left
+ * no usable stdout status, the bounded `(HTTP nnn)` suffix on the (already
+ * sanitized) stderr is the single permitted fallback, and it yields no body. A
+ * non-2xx status needs no body; a 200 must carry a parseable JSON body or the
+ * read is malformed.
+ */
+async function readProbeResponse(run, ghEnv, endpoint) {
+    let result;
+    try {
+        result = await run("gh", ["api", "--include", endpoint], ghEnv);
+    }
+    catch {
+        return { kind: "unavailable", reason: "probe_transport_failed" };
+    }
+    if (result.timedOut === true)
+        return { kind: "unavailable", reason: "probe_timed_out" };
+    const stdout = typeof result.stdout === "string" ? result.stdout : "";
+    if (stdout.length > MAX_PROBE_OUTPUT_CHARS) {
+        return { kind: "unavailable", reason: "probe_response_malformed" };
+    }
+    const normalized = stdout.replace(/\r\n/g, "\n");
+    const firstLineEnd = normalized.indexOf("\n");
+    const firstLine = firstLineEnd === -1 ? normalized : normalized.slice(0, firstLineEnd);
+    const statusMatch = HTTP_STATUS_LINE_PATTERN.exec(firstLine);
+    if (!statusMatch) {
+        if (result.status !== 0 && normalized.trim().length === 0) {
+            const stderr = sanitizeLocalMergeOutput(typeof result.stderr === "string" ? result.stderr : "", [ghEnv.GH_TOKEN]).slice(0, MAX_PROBE_STDERR_SCAN_CHARS);
+            const fallback = GH_STDERR_STATUS_PATTERN.exec(stderr);
+            if (fallback)
+                return { kind: "status", status: Number(fallback[1]), body: undefined };
+            // A failed command that produced no status anywhere is a transport-level
+            // failure, never evidence of denied access.
+            return { kind: "unavailable", reason: "probe_transport_failed" };
+        }
+        // Unexpected non-empty output, or an exit-0 read with nothing to parse.
+        return { kind: "unavailable", reason: "probe_response_malformed" };
+    }
+    const status = Number(statusMatch[1]);
+    const separator = normalized.indexOf("\n\n");
+    const headerBlock = separator === -1 ? normalized.slice(firstLine.length) : normalized.slice(firstLine.length, separator);
+    for (const line of headerBlock.split("\n")) {
+        if (line.length === 0)
+            continue;
+        if (!HTTP_HEADER_LINE_PATTERN.test(line)) {
+            return { kind: "unavailable", reason: "probe_response_malformed" };
+        }
+    }
+    const bodyText = separator === -1 ? "" : normalized.slice(separator + 2).trim();
+    if (status !== 200)
+        return { kind: "status", status, body: undefined };
+    const body = parseProbeBody(bodyText);
+    if (body === undefined)
+        return { kind: "unavailable", reason: "probe_response_malformed" };
+    return { kind: "status", status, body };
+}
+/** The repository-metadata decision: push, proven no-push, or unusable. */
+function readPushPermission(body) {
+    if (body === null || typeof body !== "object" || Array.isArray(body))
+        return "malformed";
+    const permissions = body.permissions;
+    if (permissions === null || typeof permissions !== "object" || Array.isArray(permissions)) {
+        return "malformed";
+    }
+    const push = permissions.push;
+    if (push === true)
+        return "push";
+    if (push === false)
+        return "no_push";
+    return "malformed";
+}
 /**
  * Probe whether this host can merge with the CONFIGURED credential, before any
  * merge is attempted.
@@ -1043,17 +1138,24 @@ const PREFLIGHT_REASONS = {
  * 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:
+ * Five outcomes, each fail-closed for a merge:
  *
  *   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`.
+ *   4. PROVEN no access -> the kind's `*_credential_unpermitted`.
+ *   5. BAPI-1452: no usable evidence -> the kind's `*_probe_unavailable`, with a
+ *      closed {@link LocalGhProbeUnavailableReason}.
  *
- * A network failure or an unparseable capability response is bounded and lands
- * on (4) rather than passing: an unprovable permission is not permission.
+ * BAPI-1452 made the capability probe two bounded reads with `--include`:
+ * `repos/{owner}/{name}` (the push permission is read ONLY here) and
+ * `repos/{owner}/{name}/pulls?per_page=1` (proves pull requests are readable).
+ * Only a 404 on either read, or a well-formed 200 metadata record whose
+ * `permissions.push` is `false`, proves no access. 401, 403, 429, 5xx, any
+ * other status, a transport failure, a timeout, and malformed output are all
+ * `probe_unavailable` — a non-zero exit alone is never read as denial. No read
+ * is retried; each runs under the runner's existing wall-clock timeout.
  *
  * Deliberately async and built on the same `run` seam as the merge itself. The
  * read-only equivalent in `conductor/doctor.ts` (`inspectLocalMerge`) probes
@@ -1076,6 +1178,8 @@ export async function preflightLocalGh(run, ghEnv, context = { kind: "local" })
     // 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.
+    if (context.credentialInvalid === true)
+        return { ok: false, reason: reasons.invalid };
     const credentialPresent = context.credentialPresent ?? (typeof ghEnv.GH_TOKEN === "string" && ghEnv.GH_TOKEN.length > 0);
     if (!credentialPresent)
         return { ok: false, reason: reasons.missing };
@@ -1091,25 +1195,106 @@ export async function preflightLocalGh(run, ghEnv, context = { kind: "local" })
     // 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.
+    // account access", so it is worth two read-only requests 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 };
-    }
+    if (repository === null)
+        return { ok: true };
+    const unavailable = (probeReason) => ({
+        ok: false,
+        reason: reasons.unavailable,
+        probe_unavailable_reason: probeReason,
+    });
+    const metadata = await readProbeResponse(run, ghEnv, `repos/${repository}`);
+    if (metadata.kind === "unavailable")
+        return unavailable(metadata.reason);
+    if (metadata.status === 404)
+        return { ok: false, reason: reasons.unpermitted };
+    if (metadata.status !== 200)
+        return unavailable("probe_provider_status_inconclusive");
+    const push = readPushPermission(metadata.body);
+    if (push === "malformed")
+        return unavailable("probe_response_malformed");
+    if (push === "no_push")
+        return { ok: false, reason: reasons.unpermitted };
+    const pulls = await readProbeResponse(run, ghEnv, `repos/${repository}/pulls?per_page=1`);
+    if (pulls.kind === "unavailable")
+        return unavailable(pulls.reason);
+    if (pulls.status === 404)
+        return { ok: false, reason: reasons.unpermitted };
+    if (pulls.status !== 200)
+        return unavailable("probe_provider_status_inconclusive");
+    // Push permission is read only from the repository record above; the pull
+    // request page only has to have the expected shape.
+    if (!Array.isArray(pulls.body))
+        return unavailable("probe_response_malformed");
     return { ok: true };
 }
+/**
+ * BAPI-1452 — the launch-time capability probe, with the SAME credential
+ * resolution and the SAME `gh` runner a merge uses.
+ *
+ * Resolves the kind's credential from `env` (canonical key, then — for the
+ * local kind only — the deprecated alias), builds the allowlisted child
+ * environment, and runs {@link preflightLocalGh} against an explicit,
+ * validated `owner/name`. Returns only the verdict and closed reason; the
+ * token and every byte of subprocess output stay inside this call.
+ *
+ * Read-only: `gh --version`, `gh auth status`, and two `gh api` GETs.
+ */
+export async function probeLocalMergeCapability(context, deps = {}) {
+    const env = deps.env ?? process.env;
+    let credential;
+    let invalid;
+    if (context.resolved !== undefined) {
+        credential = context.resolved.credential;
+        invalid = context.resolved.invalid;
+    }
+    else {
+        const resolution = resolveLocalMergeCredentialDetailed(env, context.kind);
+        credential = resolution.status === "resolved" ? resolution.credential : null;
+        invalid = resolution.status === "invalid";
+    }
+    const ghEnv = buildLocalMergeChildEnv(env, credential);
+    const rawRun = deps.runCommand ?? defaultRunCommand;
+    const run = (cmd, args, childEnv) => Promise.resolve(rawRun(cmd, args, childEnv, deps.signal));
+    return preflightLocalGh(run, ghEnv, {
+        kind: context.kind,
+        repository: context.repository,
+        credentialPresent: credential !== null,
+        credentialInvalid: invalid,
+    });
+}
+/**
+ * BAPI-1453 — re-run the capability probe for the merge-job path, with the
+ * EXACT credential, environment base, runner, and abort signal a failed merge
+ * just used (the {@link LocalMergeDeps} it was built from).
+ *
+ * Unlike {@link probeLocalMergeCapability} this resolves no credential of its
+ * own: the question is whether the credential that just failed `gh pr view` can
+ * see the repository, so asking about any other credential would answer the
+ * wrong question. `repository` must be the server-carried provider `owner/name`;
+ * there is no `gh repo view` fallback on this path, so a caller without one
+ * must not call this at all.
+ *
+ * Read-only and value-free: returns only the verdict and closed reason.
+ */
+export async function probeLocalMergeRepositoryAccess(repository, deps) {
+    const credential = deps.credential ?? null;
+    const reasons = PREFLIGHT_REASONS[credential?.kind ?? "local"];
+    // `preflightLocalGh` falls back to `gh repo view` for a value it cannot use.
+    // That fallback is forbidden here, so an unusable value is "no evidence".
+    if (typeof repository !== "string" || !OWNER_NAME_PATTERN.test(repository)) {
+        return { ok: false, reason: reasons.unavailable, probe_unavailable_reason: "probe_response_malformed" };
+    }
+    const ghEnv = buildLocalMergeChildEnv(deps.env ?? process.env, credential);
+    const rawRun = deps.runCommand ?? defaultRunCommand;
+    const run = (cmd, args, childEnv) => Promise.resolve(rawRun(cmd, args, childEnv, deps.signal));
+    return preflightLocalGh(run, ghEnv, {
+        kind: credential?.kind ?? "local",
+        repository,
+        credentialPresent: credential !== null,
+    });
+}
 /**
  * Execute a merge the server has ALREADY approved, using the operator's `gh`.
  *

package/build/conductor/merge-credential.js

@@ -0,0 +1,172 @@
+/**
+ * Merge credential configuration keys and their resolution (BAPI-1452).
+ *
+ * Split out of `local-merge.ts` so read-only callers — `doctor`, the shared
+ * readiness requirements, and installer guidance — can name the keys and
+ * resolve presence WITHOUT importing the merge executor and its process
+ * runner. Dependency-free: no `child_process`, no filesystem, no network.
+ * `local-merge.ts` re-exports everything here, so its public surface is
+ * unchanged.
+ *
+ * BAPI-1461 adds {@link resolveLocalMergeCredentialDetailedAsync}: the same
+ * ladder plus ONE more rung for the local kind only — a token stored once in
+ * the user-scoped credential store under `github-merge:github.com/<owner>/<repo>`.
+ * The store is read through an injected reader, so this module still has no
+ * filesystem, process, or network dependency. The two synchronous resolvers
+ * below are unchanged, so every caller that stays env-only keeps its exact
+ * behavior, and machine-user mode never gains persistence.
+ */
+/**
+ * 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.
+ *
+ * BAPI-1452: the local kind's canonical key is now `GITHUB_MERGE_TOKEN`. The
+ * pre-BAPI-1452 spelling survives ONLY as {@link LOCAL_MERGE_CREDENTIAL_ALIAS_ENV_KEY},
+ * a same-kind alias read after the canonical key. It is still never a fallback
+ * between kinds: the machine kind reads only `BAPI_MACHINE_MERGE_TOKEN`, which
+ * has no alias and is not deprecated.
+ */
+export const LOCAL_MERGE_CREDENTIAL_ENV_KEYS = {
+    local: "GITHUB_MERGE_TOKEN",
+    machine_token: "BAPI_MACHINE_MERGE_TOKEN",
+};
+/**
+ * BAPI-1452: the deprecated, still-supported spelling of the LOCAL credential
+ * key. Read only when the canonical {@link LOCAL_MERGE_CREDENTIAL_ENV_KEYS}.local
+ * value is absent or blank — a non-empty canonical value that fails validation
+ * is NOT rescued by it. There is no removal date.
+ */
+export const LOCAL_MERGE_CREDENTIAL_ALIAS_ENV_KEY = "BAPI_LOCAL_MERGE_TOKEN";
+/**
+ * BAPI-1452: the shape a configured credential value must have to be used.
+ *
+ * Printable, non-whitespace ASCII of bounded length — every GitHub token format
+ * fits, and a value carrying an embedded space, a control character, or a pasted
+ * multi-line blob does not. Deliberately not a token-format check: a shape this
+ * loose can reject only values that cannot possibly authenticate.
+ */
+const MERGE_CREDENTIAL_VALUE_PATTERN = /^[\x21-\x7E]{1,4096}$/;
+/** Classify one raw environment value without exposing it. */
+function classifyCredentialValue(raw) {
+    if (typeof raw !== "string")
+        return "absent";
+    const token = raw.trim();
+    if (token.length === 0)
+        return "absent";
+    return MERGE_CREDENTIAL_VALUE_PATTERN.test(token) ? token : "invalid";
+}
+/**
+ * Resolve one credential kind and report where it came from (BAPI-1452).
+ *
+ * Local kind: `GITHUB_MERGE_TOKEN` first, then the deprecated
+ * `BAPI_LOCAL_MERGE_TOKEN`. An absent or whitespace-only canonical value permits
+ * the alias; a non-empty canonical value that fails validation returns
+ * `invalid` and the alias is not consulted. Machine kind: only
+ * `BAPI_MACHINE_MERGE_TOKEN`. Never the other kind's key, never an inherited
+ * `GH_TOKEN`/`GITHUB_TOKEN`.
+ */
+export function resolveLocalMergeCredentialDetailed(env, kind) {
+    const primaryKey = LOCAL_MERGE_CREDENTIAL_ENV_KEYS[kind];
+    const keys = kind === "local" ? [primaryKey, LOCAL_MERGE_CREDENTIAL_ALIAS_ENV_KEY] : [primaryKey];
+    for (const key of keys) {
+        const classified = classifyCredentialValue(env[key]);
+        if (classified === "absent")
+            continue;
+        if (classified === "invalid")
+            return { status: "invalid", source_key: key };
+        return {
+            status: "resolved",
+            credential: { kind, token: classified },
+            source_key: key,
+            via_alias: key === LOCAL_MERGE_CREDENTIAL_ALIAS_ENV_KEY,
+        };
+    }
+    return { status: "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. BAPI-1452: also `null` for a value that fails
+ * validation, so no privileged subprocess ever runs with it; callers that must
+ * tell "invalid" from "missing" use {@link resolveLocalMergeCredentialDetailed}.
+ */
+export function resolveLocalMergeCredential(env, kind) {
+    const resolution = resolveLocalMergeCredentialDetailed(env, kind);
+    return resolution.status === "resolved" ? resolution.credential : null;
+}
+/** BAPI-1461: whether a value has the shape a merge credential must have. */
+export function isUsableMergeCredentialValue(raw) {
+    const classified = classifyCredentialValue(raw);
+    return classified !== "absent" && classified !== "invalid";
+}
+/** The `source_key` reported for a credential that came from the store. */
+export const STORED_MERGE_CREDENTIAL_SOURCE_KEY = "store";
+/**
+ * BAPI-1461: resolve one kind with the stored-entry fallback.
+ *
+ * The order for the local kind is fixed: `GITHUB_MERGE_TOKEN`, then
+ * `BAPI_LOCAL_MERGE_TOKEN`, then the stored entry. The synchronous resolver
+ * runs first and its answer wins whenever it resolves or reports an invalid
+ * value, so an invalid canonical value is never rescued by the alias or the
+ * store. `machine_token` returns the synchronous answer unchanged. The store is
+ * consulted only when `allowStoredEntry === true` and a reader was supplied.
+ * Nothing here reads `gh auth`, `GH_TOKEN`, `GITHUB_TOKEN`, or a Bridge key.
+ */
+export async function resolveLocalMergeCredentialDetailedAsync(env, kind, options = {}) {
+    const sync = resolveLocalMergeCredentialDetailed(env, kind);
+    if (sync.status === "resolved") {
+        return {
+            status: "resolved",
+            credential: sync.credential,
+            source: sync.via_alias ? "alias" : "env",
+            source_key: sync.source_key,
+            via_alias: sync.via_alias,
+        };
+    }
+    if (sync.status === "invalid") {
+        return {
+            status: "invalid",
+            source: sync.source_key === LOCAL_MERGE_CREDENTIAL_ALIAS_ENV_KEY ? "alias" : "env",
+            source_key: sync.source_key,
+        };
+    }
+    if (kind !== "local" || options.allowStoredEntry !== true || !options.readStoredEntry) {
+        return { status: "missing" };
+    }
+    let stored;
+    try {
+        stored = await options.readStoredEntry();
+    }
+    catch {
+        return { status: "store-unavailable" };
+    }
+    if (stored.status === "unavailable")
+        return { status: "store-unavailable" };
+    if (stored.status === "absent")
+        return { status: "missing" };
+    const classified = classifyCredentialValue(stored.token);
+    if (classified === "absent")
+        return { status: "missing" };
+    if (classified === "invalid") {
+        return { status: "invalid", source: "store", source_key: STORED_MERGE_CREDENTIAL_SOURCE_KEY };
+    }
+    return {
+        status: "resolved",
+        credential: { kind, token: classified },
+        source: "store",
+        source_key: STORED_MERGE_CREDENTIAL_SOURCE_KEY,
+        via_alias: false,
+    };
+}

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

@@ -42,7 +42,7 @@ import { MERGE_WORKFLOW_CHILD_MERGE_COMPATIBLE_VERSIONS, MERGE_WORKFLOW_CODEOWNE
  */
 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.";
+    "merge-execution block at all, email info@bridgegpt.ai.";
 /**
  * Remediation for a CONFIRMED insufficiency. Names the one command that fixes it.
  *

package/build/conductor/merged-child-check.js

@@ -0,0 +1,95 @@
+/**
+ * Already-merged child detection and skip selection for `drive-epic` (BAPI-1510).
+ *
+ * Pure helpers plus one injected classification call. Nothing here prints, reads a
+ * file, or touches the network except through the injected `classify` function.
+ *
+ * The posture is conservative: only a current server verdict of `done` (completed
+ * delivery binding, confirmed merge commit, covered by the indexed cut) is ever
+ * skipped on its own. `probably_done` needs the operator's explicit `--skip-child`.
+ * Every uncertain, failed, or malformed result keeps the child in the plan.
+ */
+/** The server's per-request bound on child keys. */
+export const CHILD_MERGE_STATUS_BATCH_SIZE = 100;
+/**
+ * Classify every plan child against one previously resolved cut, in batches of at
+ * most {@link CHILD_MERGE_STATUS_BATCH_SIZE}. Any failed or malformed batch fails
+ * the WHOLE check: a partial result must never feed a skip set.
+ */
+export async function classifyPlanChildren(classify, epicKey, childKeys, cutCommitSha) {
+    const results = [];
+    try {
+        for (let i = 0; i < childKeys.length; i += CHILD_MERGE_STATUS_BATCH_SIZE) {
+            const batch = childKeys.slice(i, i + CHILD_MERGE_STATUS_BATCH_SIZE);
+            const response = await classify({ epicKey, childKeys: batch, cutCommitSha });
+            if (response.cut_commit_sha !== cutCommitSha ||
+                response.children.length !== batch.length ||
+                response.children.some((child, index) => child.ticket_key !== batch[index])) {
+                return { ok: false };
+            }
+            results.push(...response.children);
+        }
+    }
+    catch {
+        return { ok: false };
+    }
+    return { ok: true, results };
+}
+/**
+ * Decide the skip set from current verdicts.
+ *
+ * - Automatic: `done` and not named by `--keep-child`.
+ * - Explicit: `--skip-child`, honored only for `done` or `probably_done`.
+ * - `results === null` means the check could not run: no automatic skips, and every
+ *   explicit skip is a refusal.
+ */
+export function selectSkips(input) {
+    const planKeys = new Set(input.planKeys);
+    const keep = new Set(input.keepChildren);
+    const refusals = [];
+    const skipKeys = new Set();
+    const confirmedKeys = new Set();
+    for (const key of input.skipChildren) {
+        if (!planKeys.has(key))
+            refusals.push({ ticketKey: key, reason: "not_in_plan" });
+    }
+    if (input.results === null) {
+        for (const key of input.skipChildren) {
+            if (planKeys.has(key))
+                refusals.push({ ticketKey: key, reason: "check_unavailable" });
+        }
+        return { skipKeys, confirmedKeys, refusals };
+    }
+    const byKey = new Map(input.results.map((result) => [result.ticket_key, result]));
+    const explicit = new Set(input.skipChildren);
+    for (const key of input.planKeys) {
+        const verdict = byKey.get(key)?.classification;
+        if (explicit.has(key)) {
+            if (verdict === "done" || verdict === "probably_done") {
+                skipKeys.add(key);
+                confirmedKeys.add(key);
+            }
+            else {
+                refusals.push({ ticketKey: key, reason: "not_skippable" });
+            }
+            continue;
+        }
+        if (verdict === "done" && !keep.has(key))
+            skipKeys.add(key);
+    }
+    return { skipKeys, confirmedKeys, refusals };
+}
+/**
+ * The preview entries: every `done` and `probably_done` child, every `unknown`
+ * child, and every proven-merged child that merged after the index. A child that
+ * simply has no merged PR is left out. `will_skip` is true only for children in
+ * the skip set.
+ */
+export function buildAlreadyDoneEntries(results, skipKeys) {
+    return results
+        .filter((result) => result.classification === "done" ||
+        result.classification === "probably_done" ||
+        result.classification === "unknown" ||
+        result.reason === "merged_after_index")
+        .map((result) => ({ ...result, will_skip: skipKeys.has(result.ticket_key) }));
+}

package/build/conductor/plan-trim.js

@@ -0,0 +1,30 @@
+/**
+ * Immutable trimming of already-merged children out of an epic plan DAG (BAPI-1510).
+ *
+ * Pure: returns newly constructed data and never mutates the caller's plan, so the
+ * operator's plan sidecar stays byte-identical. A skipped node is removed together
+ * with every reference to it — `depends_on` entries and edges naming it on either
+ * end — so the trimmed plan has no dangling dependency and still passes server-side
+ * plan validation. Node order and retained edge order are preserved, and every other
+ * property (status, automations, touched files, unknown metadata) is carried over.
+ */
+function cloneJson(value) {
+    return JSON.parse(JSON.stringify(value));
+}
+export function trimDonePlanNodes(plan, skipKeys) {
+    const trimmed = cloneJson(plan);
+    const nodes = [];
+    for (const node of trimmed.nodes ?? []) {
+        if (skipKeys.has(node.ticket_key))
+            continue;
+        if (Array.isArray(node.depends_on)) {
+            node.depends_on = node.depends_on.filter((key) => !skipKeys.has(key));
+        }
+        nodes.push(node);
+    }
+    trimmed.nodes = nodes;
+    if (Array.isArray(trimmed.edges)) {
+        trimmed.edges = trimmed.edges.filter((edge) => !skipKeys.has(edge.from) && !skipKeys.has(edge.to));
+    }
+    return trimmed;
+}