@bridge_gpt/mcp-server 0.2.67 → 0.2.68

package/build/install-bridge-conductor-gate.js

@@ -0,0 +1,1372 @@
+/**
+ * `install-bridge conductor` — the owner-confirmed repository gate (BAPI-1391).
+ *
+ * Before this module, the conductor installer refused to run without at least
+ * one `--required-check`, so a repository whose CI used other names, ran outside
+ * GitHub Actions, gated on local commands, or had no CI at all could not be set
+ * up without reshaping it. BAPI-1390 stores an owner-confirmed GATE PROFILE —
+ * provider checks, executor-run local commands, both (`mixed`), or `none` — and
+ * makes admission prove it. This module is how the installer proposes a gate,
+ * how the owner confirms or edits it, and how a local gate gets its first proof.
+ *
+ * Five properties are load-bearing:
+ *
+ * 1. **Discovery never confirms.** The deterministic collector
+ *    (`conductor/gate-discovery.ts`) reads the working tree and the provider's
+ *    real check history and PROPOSES a typed gate. A proposal is stored only
+ *    after the owner confirms it at a prompt, or supplies explicit gate flags,
+ *    which are owner input. No LLM ever writes a gate.
+ * 2. **The capability probe precedes every gate write.** A server that does not
+ *    advertise `gate_profile.v1` gets "Bridge API update required" and nothing
+ *    is written — including the qualification enqueue, and the short-lived
+ *    executor whose claim carries `job_types` (an older server answers that key
+ *    with 422). The probe is a read and runs after the base-URL consent.
+ * 3. **Removals are visible.** The stored and proposed gates are shown side by
+ *    side before any write; a confirm that removes a member says so, and a
+ *    flag-driven removal needs `--confirm-gate` or an explicit yes.
+ * 4. **A refused write changes nothing.** BAPI-1390's PUT is admin-only and
+ *    compare-and-swaps the revision; on a refusal the installer shows the PRIOR
+ *    gate, never the proposal, as what is in force.
+ * 5. **Qualification is reported from the server, never from the shell.** The
+ *    short-lived executor's exit code proves nothing; only the job state and
+ *    BAPI-1390's qualification reading do. A failed qualification warns and the
+ *    install still succeeds — the local gate simply stays unqualified, so
+ *    admission keeps refusing with `local_command_unqualified`.
+ *
+ * BAPI-1405 adds an epic-branch CI step after the gate (see the last section).
+ * It keeps property 1: it inspects workflow triggers and epic-branch rules on
+ * GitHub, explains them, and records only an explicit include/decline choice.
+ * It never confirms a gate, authorizes a merge, or changes an approval rule
+ * without an explicit typed "yes".
+ */
+import { ConductorBridgeApiError, GATE_PROFILE_CAPABILITY_TOKEN, enqueueConductorGateQualification, fetchConductorGateCheckHistory, fetchConductorGateProfile, fetchConductorGateQualificationJob, probeConductorGateProfileCapability, putConductorGateProfile, putEpicBranchCiDecision, } from "./conductor/bridge-api-client.js";
+import { applyApprovalExemption, assessApprovalExemptionScope, buildEpicBranchCiEvidence, exemptionManualSteps, inspectEpicBranchWorkflowCoverage, readEpicBranchRulesViaGh, } from "./conductor/epic-branch-ci-inspection.js";
+import { describeEvidence, discoverGate, LOCAL_COMMAND_TIMEOUT_SECONDS, } from "./conductor/gate-discovery.js";
+import { PRINTED_EXECUTOR_INSTALL_SERVICE_COMMAND, PRINTED_EXECUTOR_ID_INSTRUCTION, PRINTED_QUALIFY_GATE_COMMAND, PRINTED_REPO_WIDE_EXECUTOR_COMMAND, } from "./printed-remedy-commands.js";
+export function emptyConductorGateFlags() {
+    return {
+        providerChecks: [],
+        localCommands: [],
+        gateNone: false,
+        confirmGate: false,
+        clearGate: false,
+        qualifyGate: false,
+    };
+}
+/** Flags that NAME the gate's members. */
+export function hasExplicitGateMembers(flags) {
+    return flags.providerChecks.length > 0 || flags.localCommands.length > 0 || flags.gateNone;
+}
+/** Any flag that is explicit owner input about the stored gate. */
+export function hasExplicitGateInput(flags) {
+    return (hasExplicitGateMembers(flags) ||
+        flags.migrationGuard !== undefined ||
+        flags.customizedCommands !== undefined);
+}
+/** A literal command name; the same shape the discovery collector produces. */
+const LITERAL_COMMAND_NAME_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+/**
+ * A literal argv word. Plain words only: quoting, globbing, redirection,
+ * substitution, and every other piece of shell syntax are refused, because a
+ * gate command is run as an argv list and never through a shell. Splitting a
+ * quoted string would mean guessing at a shell's parse.
+ */
+const LITERAL_ARGV_WORD_RE = /^[A-Za-z0-9_./:=@%+,-]+$/;
+/** A discovery candidate id (`npm:test`, `make:check`, `python:pytest`, `tox`). */
+const CANDIDATE_ID_RE = /^[a-z0-9]+(?::[a-z0-9_-]+)?$/;
+const MAX_LITERAL_ARGV = 32;
+const MAX_CHECK_NAME_LENGTH = 200;
+/** Parse one `--local-command` value. Errors are fixed text naming the rule. */
+export function parseLocalCommandFlag(raw) {
+    const eq = raw.indexOf("=");
+    if (eq === -1) {
+        if (!CANDIDATE_ID_RE.test(raw)) {
+            return {
+                ok: false,
+                error: "--local-command takes a discovered candidate id (for example npm:test) or " +
+                    "<name>=<command words> (for example unit=pytest -q).",
+            };
+        }
+        return { ok: true, value: { form: "candidate", id: raw } };
+    }
+    const name = raw.slice(0, eq).trim();
+    const words = raw
+        .slice(eq + 1)
+        .split(/\s+/)
+        .filter((w) => w.length > 0);
+    if (!LITERAL_COMMAND_NAME_RE.test(name)) {
+        return {
+            ok: false,
+            error: "--local-command name must be 1-64 letters, digits, '.', '_' or '-', starting with a letter or digit.",
+        };
+    }
+    if (words.length === 0 || words.length > MAX_LITERAL_ARGV) {
+        return { ok: false, error: `--local-command needs between 1 and ${MAX_LITERAL_ARGV} command words.` };
+    }
+    if (words.some((w) => !LITERAL_ARGV_WORD_RE.test(w))) {
+        return {
+            ok: false,
+            error: "--local-command words must be plain words: quotes, globs, pipes, redirection, " +
+                "variables, and other shell syntax are not supported, because the command runs " +
+                "without a shell.",
+        };
+    }
+    return { ok: true, value: { form: "literal", name, argv: words } };
+}
+/** Parse one `--migration-guard provider:<check>` / `local:<command>` value. */
+export function parseMigrationGuardFlag(raw) {
+    const colon = raw.indexOf(":");
+    const kind = colon === -1 ? "" : raw.slice(0, colon);
+    const ref = colon === -1 ? "" : raw.slice(colon + 1).trim();
+    if ((kind !== "provider" && kind !== "local") || ref.length === 0) {
+        return {
+            ok: false,
+            error: "--migration-guard must be provider:<exact check name> or local:<command name or id>.",
+        };
+    }
+    return { ok: true, value: { kind, ref } };
+}
+/** Whether a provider check name is renderable and storable. */
+export function isValidCheckName(name) {
+    return (name.trim() === name &&
+        name.length > 0 &&
+        name.length <= MAX_CHECK_NAME_LENGTH &&
+        !/[\u0000-\u001F\u007F]/.test(name));
+}
+/**
+ * Validate flag COMBINATIONS before any effect. Returns fixed error text, or
+ * null. Member references are resolved later, against discovery and the stored
+ * profile; this only refuses combinations that can never be right.
+ */
+export function validateConductorGateFlags(flags, context) {
+    for (const check of flags.providerChecks) {
+        if (!isValidCheckName(check)) {
+            return `Invalid provider check name: it must be 1-${MAX_CHECK_NAME_LENGTH} characters with no control characters.`;
+        }
+    }
+    if (flags.gateNone && (flags.providerChecks.length > 0 || flags.localCommands.length > 0)) {
+        return "--gate-none is exclusive: it cannot be combined with --provider-check, --required-check, or --local-command.";
+    }
+    if (flags.gateNone && flags.migrationGuard !== undefined) {
+        return "--gate-none has no members, so it cannot take a --migration-guard.";
+    }
+    if (flags.clearGate && (hasExplicitGateInput(flags) || flags.confirmGate || flags.qualifyGate)) {
+        return "--clear-gate runs on its own: it cannot be combined with gate flags, --confirm-gate, or --qualify-gate.";
+    }
+    if (flags.clearGate && context.replaceDoneGate) {
+        return "--clear-gate cannot be combined with --replace-done-gate.";
+    }
+    if (flags.confirmGate && !hasExplicitGateInput(flags)) {
+        return ("--confirm-gate confirms explicit gate flags. Supply --provider-check, --local-command, " +
+            "--gate-none, --migration-guard, or --customized-command, or run without it to confirm " +
+            "the discovered proposal at a prompt.");
+    }
+    if (flags.migrationGuard?.kind === "provider" && flags.providerChecks.length > 0 &&
+        !flags.providerChecks.includes(flags.migrationGuard.ref)) {
+        return "--migration-guard provider:<check> must name one of the supplied provider checks exactly.";
+    }
+    if (context.replaceDoneGate && (flags.gateNone ||
+        (flags.localCommands.length > 0 && flags.providerChecks.length === 0))) {
+        return "--replace-done-gate rebuilds the CI gate from provider checks, so it needs at least one --provider-check.";
+    }
+    return null;
+}
+/** The job types the short-lived qualifying executor may claim — exactly one. */
+export const QUALIFICATION_EXECUTOR_JOB_TYPES = ["gate_qualification"];
+/**
+ * The production short-lived qualifying executor, built on the EXISTING
+ * executor CLI so credentials resolve through the same bundle path, the base
+ * URL stays explicit, and the repository-wide scope passes the CLI's own claim
+ * scope validation. This is the `runExecutorCli` `runExecutor` OVERRIDE route
+ * (the ticket's second option): the CLI parses an ordinary `--repo-wide --once`
+ * invocation, and the override narrows the parsed options to
+ * `jobTypes: ["gate_qualification"]` and `once: true` before the loop starts,
+ * so its claims carry `job_types: ["gate_qualification"]` and it can never
+ * take an implement or merge job. No new CLI flag is added.
+ */
+export function createQualificationExecutorRunner(seams) {
+    return async ({ repoName, baseUrl }) => {
+        let started = false;
+        const exitCode = await seams.runExecutorCli(["--repo", repoName, "--repo-wide", "--once", "--base-url", baseUrl], {
+            errorLog: seams.errorLog,
+            runExecutor: async (options, deps, httpClient, runnerSeams) => {
+                started = true;
+                return seams.runExecutor({ ...options, jobTypes: QUALIFICATION_EXECUTOR_JOB_TYPES, once: true }, deps, httpClient, runnerSeams);
+            },
+        });
+        return { started, exitCode };
+    };
+}
+const YES = new Set(["y", "yes"]);
+async function ask(io, promptText) {
+    if (!io.promptLine)
+        return false;
+    const answer = await io.promptLine(promptText);
+    return YES.has((answer ?? "").trim().toLowerCase());
+}
+/** The fixed update-required refusal (property 2). */
+export const GATE_UPDATE_REQUIRED_MESSAGE = `Bridge API update required: this server does not advertise ${GATE_PROFILE_CAPABILITY_TOKEN}, so ` +
+    "it cannot store a confirmed repository gate. Nothing was written. Upgrade the Bridge API " +
+    "deployment, then re-run.";
+/** Probe `gate_profile.v1`; print the refusal and return false when absent. */
+export async function requireGateProfileCapability(io, access) {
+    const probe = await probeConductorGateProfileCapability(access, io.fetchJson);
+    if (probe.supported)
+        return true;
+    io.errorLog(GATE_UPDATE_REQUIRED_MESSAGE);
+    if (probe.reason === "unauthorized") {
+        io.errorLog("  (the capability probe was refused: check the repository API key.)");
+    }
+    else if (probe.reason === "unreachable") {
+        io.errorLog("  (the capability probe could not reach the Bridge API.)");
+    }
+    return false;
+}
+export function kindForMembers(providerChecks, localCommands) {
+    if (providerChecks.length > 0 && localCommands.length > 0)
+        return "mixed";
+    if (providerChecks.length > 0)
+        return "provider";
+    if (localCommands.length > 0)
+        return "local";
+    return "none";
+}
+/** The stored (or legacy) profile as a desired gate. */
+export function desiredFromStored(profile) {
+    const guard = profile.migration_guard;
+    let migrationGuard = null;
+    if (guard?.kind === "provider")
+        migrationGuard = { kind: "provider", name: guard.id };
+    if (guard?.kind === "local") {
+        const command = profile.local_commands.find((c) => c.id === guard.id || c.name === guard.id);
+        if (command)
+            migrationGuard = { kind: "local", name: command.name };
+    }
+    return {
+        kind: profile.kind,
+        providerChecks: [...profile.provider_checks],
+        localCommands: profile.local_commands.map((c) => ({
+            name: c.name,
+            argv: [...c.argv],
+            timeout_seconds: c.timeout_seconds,
+        })),
+        migrationGuard,
+        customizedCommands: [...profile.customized_commands],
+    };
+}
+function sameCommand(a, b) {
+    return (a.name === b.name &&
+        a.timeout_seconds === b.timeout_seconds &&
+        a.argv.length === b.argv.length &&
+        a.argv.every((w, i) => w === b.argv[i]));
+}
+/** Whether `desired` is exactly what `stored` already holds (no write needed). */
+export function gateMatchesStored(desired, stored) {
+    const sameGuard = desired.migrationGuard === null
+        ? stored.migrationGuard === null
+        : stored.migrationGuard !== null &&
+            desired.migrationGuard.kind === stored.migrationGuard.kind &&
+            desired.migrationGuard.name === stored.migrationGuard.name;
+    const sameCustomized = desired.customizedCommands === undefined ||
+        (stored.customizedCommands !== undefined &&
+            desired.customizedCommands.length === stored.customizedCommands.length &&
+            desired.customizedCommands.every((c, i) => c === stored.customizedCommands?.[i]));
+    return (desired.kind === stored.kind &&
+        desired.providerChecks.length === stored.providerChecks.length &&
+        desired.providerChecks.every((c, i) => c === stored.providerChecks[i]) &&
+        desired.localCommands.length === stored.localCommands.length &&
+        desired.localCommands.every((c, i) => sameCommand(c, stored.localCommands[i])) &&
+        sameGuard &&
+        sameCustomized);
+}
+/** Human descriptions of every member `next` removes from `prior`. */
+export function gateRemovals(prior, next) {
+    if (prior === null)
+        return [];
+    const removed = [];
+    for (const check of prior.providerChecks) {
+        if (!next.providerChecks.includes(check))
+            removed.push(`provider check "${check}"`);
+    }
+    for (const command of prior.localCommands) {
+        if (!next.localCommands.some((c) => sameCommand(c, command))) {
+            removed.push(`local command ${command.name}`);
+        }
+    }
+    if (prior.migrationGuard !== null && next.migrationGuard === null) {
+        removed.push(`migration guard (${prior.migrationGuard.kind} ${prior.migrationGuard.name})`);
+    }
+    return removed;
+}
+/** The PUT body for a confirm of `desired` against the revision the server reported. */
+export function confirmRequestFor(desired, expectedRevision) {
+    const guard = desired.migrationGuard === null ? null : { kind: desired.migrationGuard.kind, id: desired.migrationGuard.name };
+    return {
+        action: "confirm",
+        confirm: true,
+        expected_revision: expectedRevision,
+        kind: desired.kind,
+        provider_checks: desired.providerChecks.map((name) => ({ name })),
+        local_commands: desired.localCommands.map((c) => ({
+            name: c.name,
+            argv: [...c.argv],
+            timeout_seconds: c.timeout_seconds,
+        })),
+        migration_guard: guard,
+        ...(desired.customizedCommands !== undefined ? { customized_commands: desired.customizedCommands } : {}),
+    };
+}
+function resolveLocalCommand(flag, proposal) {
+    if (flag.form === "literal") {
+        return { name: flag.name, argv: [...flag.argv], timeout_seconds: LOCAL_COMMAND_TIMEOUT_SECONDS };
+    }
+    const candidate = proposal?.localCandidates.find((c) => c.id === flag.id);
+    if (!candidate)
+        return null;
+    return { name: candidate.name, argv: [...candidate.argv], timeout_seconds: candidate.timeoutSeconds };
+}
+/**
+ * Build the desired gate from explicit flags over the current confirmed gate.
+ *
+ * Member flags (`--provider-check`/`--required-check`, `--local-command`,
+ * `--gate-none`) replace the members entirely — the flags ARE the gate. Without
+ * them the current members are kept and only the guard or customized commands
+ * change. A guard whose member was removed is dropped (and shown as a removal).
+ */
+export function desiredFromFlags(flags, current, proposal) {
+    let providerChecks;
+    let localCommands;
+    if (hasExplicitGateMembers(flags)) {
+        providerChecks = [...flags.providerChecks];
+        localCommands = [];
+        for (const flag of flags.localCommands) {
+            const resolved = resolveLocalCommand(flag, proposal);
+            if (resolved === null) {
+                return {
+                    ok: false,
+                    error: `--local-command ${flag.form === "candidate" ? flag.id : flag.name} is not a command ` +
+                        "discovery found in this repository. Use a listed candidate id, or <name>=<command words>.",
+                };
+            }
+            if (localCommands.some((c) => c.name === resolved.name)) {
+                return { ok: false, error: `--local-command ${resolved.name} is supplied twice.` };
+            }
+            localCommands.push(resolved);
+        }
+    }
+    else if (current !== null) {
+        providerChecks = [...current.providerChecks];
+        localCommands = current.localCommands.map((c) => ({ ...c, argv: [...c.argv] }));
+    }
+    else {
+        return {
+            ok: false,
+            error: "There is no confirmed gate to change. Name its members with --provider-check, " +
+                "--local-command, or --gate-none.",
+        };
+    }
+    let migrationGuard = null;
+    if (flags.migrationGuard !== undefined) {
+        const { kind, ref } = flags.migrationGuard;
+        if (kind === "provider") {
+            if (!providerChecks.includes(ref)) {
+                return { ok: false, error: "--migration-guard provider:<check> must name a provider check of the gate exactly." };
+            }
+            migrationGuard = { kind, name: ref };
+        }
+        else {
+            const byCandidate = proposal?.localCandidates.find((c) => c.id === ref)?.name;
+            const member = localCommands.find((c) => c.name === ref || c.name === byCandidate);
+            if (!member) {
+                return { ok: false, error: "--migration-guard local:<command> must name a local command of the gate." };
+            }
+            migrationGuard = { kind, name: member.name };
+        }
+    }
+    else if (current?.migrationGuard) {
+        const keep = current.migrationGuard.kind === "provider"
+            ? providerChecks.includes(current.migrationGuard.name)
+            : localCommands.some((c) => c.name === current.migrationGuard?.name);
+        migrationGuard = keep ? current.migrationGuard : null;
+    }
+    return {
+        ok: true,
+        desired: {
+            kind: kindForMembers(providerChecks, localCommands),
+            providerChecks,
+            localCommands,
+            migrationGuard,
+            customizedCommands: flags.customizedCommands,
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Rendering
+// ---------------------------------------------------------------------------
+const KIND_CONSEQUENCE = Object.freeze({
+    provider: "every check must have actually reported on this repository before an unattended run is admitted",
+    local: "the executor runs these commands before each auto-merge; they must pass once under the executor " +
+        "(qualification) before an unattended run is admitted",
+    mixed: "BOTH legs gate every merge: each provider check must report green AND each local command must pass",
+    none: "no gate: an unattended run is admitted, but every child merge waits for your approval",
+});
+function quoted(names) {
+    return names.map((n) => `"${n}"`).join(", ");
+}
+/** One-gate description lines (members, conjunction, guard, customized). */
+export function describeGate(gate, indent = "    ") {
+    const lines = [];
+    const members = [];
+    if (gate.providerChecks.length > 0)
+        members.push(`provider checks ${quoted(gate.providerChecks)}`);
+    if (gate.localCommands.length > 0) {
+        members.push(`local commands ${gate.localCommands.map((c) => `${c.name} (${c.argv.join(" ")})`).join(", ")}`);
+    }
+    lines.push(`${indent}${gate.kind}` +
+        (members.length > 0 ? ` — ${members.join(gate.kind === "mixed" ? " AND " : "; ")}` : ""));
+    lines.push(`${indent}  ${KIND_CONSEQUENCE[gate.kind]}`);
+    if (gate.migrationGuard !== null) {
+        lines.push(`${indent}  migration guard: ${gate.migrationGuard.kind} ${gate.migrationGuard.name}`);
+    }
+    if (gate.customizedCommands !== undefined && gate.customizedCommands.length > 0) {
+        lines.push(`${indent}  customized commands: ${gate.customizedCommands.join(", ")}`);
+    }
+    return lines;
+}
+function describeHistory(proposal) {
+    switch (proposal.history.status) {
+        case "available":
+            return proposal.providerCandidates.length === 0 && proposal.unreportedProviderNames.length > 0
+                ? "available — none of the looked-up names has reported recently"
+                : `available${proposal.history.complete ? "" : " (partial walk)"}`;
+        case "unavailable":
+            return "UNAVAILABLE — provider check history could not be read";
+        default:
+            return "not queried — no CI check names were found to look up";
+    }
+}
+/**
+ * Render the discovery proposal as the prominent "Proposed repository gate"
+ * section. Returns the numbered candidates in display order.
+ */
+export function renderGateProposal(io, proposal) {
+    const numbered = [];
+    io.log("");
+    io.log("Proposed repository gate");
+    io.log("────────────────────────");
+    io.log("  Discovery read this working tree and the provider's recent check history.");
+    io.log("  It saved nothing: a gate is stored only after you confirm it.");
+    io.log(`  provider history: ${describeHistory(proposal)}`);
+    if (proposal.history.status === "unavailable") {
+        io.log("  ⚠ Provider history is unavailable, so no provider check can be proposed. That is " +
+            "unknown, not absent: type exact check names below, or retry later.");
+    }
+    if (proposal.noCandidates) {
+        io.log("  No candidates found.");
+    }
+    else {
+        io.log("  Candidates:");
+        for (const candidate of proposal.providerCandidates) {
+            numbered.push({ kind: "provider", name: candidate.name });
+            io.log(`    [${numbered.length}] provider check "${candidate.name}" — reported on this repository ` +
+                `(confidence ${candidate.confidence})`);
+            for (const e of candidate.evidence)
+                io.log(`          evidence: ${describeEvidence(e)}`);
+        }
+        for (const candidate of proposal.localCandidates) {
+            numbered.push({ kind: "local", candidate });
+            io.log(`    [${numbered.length}] local command ${candidate.name} (${candidate.argv.join(" ")}) ` +
+                `id ${candidate.id} (confidence ${candidate.confidence})`);
+            for (const e of candidate.evidence)
+                io.log(`          evidence: ${describeEvidence(e)}`);
+        }
+    }
+    if (proposal.unreportedProviderNames.length > 0) {
+        io.log("  Not proposed — never seen reporting, or unknown:");
+        for (const candidate of proposal.unreportedProviderNames) {
+            const status = candidate.outcome === "unseen"
+                ? "not seen on recent default-branch commits or merged pull requests"
+                : "history unknown";
+            io.log(`    - "${candidate.name}": ${status}`);
+        }
+    }
+    const varying = proposal.evidence.filter((e) => e.nameMayVary);
+    if (varying.length > 0) {
+        io.log("  Names that may vary (a matrix or expression job reports a different exact name):");
+        for (const e of varying)
+            io.log(`    - ${describeEvidence(e)}`);
+        io.log("    Type the exact reported name below if you want one in the gate.");
+    }
+    const contextOnly = proposal.evidence.filter((e) => e.kind === "husky_hook" ||
+        e.kind === "pre_commit_config" ||
+        e.kind === "git_pre_push_hook" ||
+        e.kind === "buildkite" ||
+        e.kind === "jenkinsfile" ||
+        (e.kind === "circleci_job" && !e.nameMayVary));
+    if (contextOnly.length > 0) {
+        io.log("  Other evidence (context only; never run by the gate):");
+        for (const e of contextOnly)
+            io.log(`    - ${describeEvidence(e)}`);
+    }
+    const proposedDesired = desiredFromProposalSelection(proposal, proposal.proposed.providerChecks, proposal.proposed.localCommandIds);
+    io.log("  Proposal:");
+    for (const line of describeGate(proposedDesired))
+        io.log(line);
+    return numbered;
+}
+function desiredFromProposalSelection(proposal, providerChecks, localIds) {
+    const localCommands = localIds
+        .map((id) => proposal.localCandidates.find((c) => c.id === id))
+        .filter((c) => c !== undefined)
+        .map((c) => ({ name: c.name, argv: [...c.argv], timeout_seconds: c.timeoutSeconds }));
+    return {
+        kind: kindForMembers(providerChecks, localCommands),
+        providerChecks: [...providerChecks],
+        localCommands,
+        migrationGuard: null,
+        customizedCommands: undefined,
+    };
+}
+function describeStoredHeading(current) {
+    if (!current.confirmed || current.profile === null) {
+        return current.stored_malformed
+            ? "Stored gate: a stored value could not be read, so it is NOT confirmed"
+            : "Stored gate: none confirmed";
+    }
+    return current.source === "legacy"
+        ? "Stored gate (legacy --required-check setup, treated as confirmed):"
+        : `Stored gate (revision ${current.revision}):`;
+}
+/** The side-by-side comparison shown before every gate write (property 3). */
+export function renderGateComparison(io, current, desired, removals) {
+    io.log("");
+    io.log(`  ${describeStoredHeading(current)}`);
+    if (current.confirmed && current.profile !== null) {
+        for (const line of describeGate(desiredFromStored(current.profile)))
+            io.log(line);
+    }
+    io.log("  Proposed gate:");
+    for (const line of describeGate(desired))
+        io.log(line);
+    if (removals.length > 0) {
+        io.log(`  ⚠ This REMOVES ${removals.length} member(s) from the confirmed gate: ${removals.join("; ")}.`);
+        io.log("    Unattended runs then merge with fewer checks.");
+    }
+}
+// ---------------------------------------------------------------------------
+// Discovery + interactive editing
+// ---------------------------------------------------------------------------
+function historyLookupFor(io, access) {
+    return async (names) => {
+        try {
+            const history = await fetchConductorGateCheckHistory(access, names, io.fetchJson);
+            return {
+                ok: true,
+                complete: history.complete,
+                unavailableReason: history.unavailable_reason,
+                outcomes: Object.fromEntries(history.checks.map((c) => [c.name, c.outcome])),
+            };
+        }
+        catch {
+            // Sanitized and bounded: an unreadable history is "unavailable", never empty.
+            return { ok: false };
+        }
+    };
+}
+/** Run discovery, or an explicit empty proposal when no discovery seam exists. */
+export async function runGateDiscovery(io, access, gateDeps) {
+    const fs = gateDeps?.discoveryFs;
+    if (!fs) {
+        return {
+            providerCandidates: [],
+            unreportedProviderNames: [],
+            localCandidates: [],
+            evidence: [],
+            history: { status: "not_queried" },
+            proposed: { kind: "none", providerChecks: [], localCommandIds: [] },
+            noCandidates: true,
+        };
+    }
+    return discoverGate({ fs, lookupHistory: historyLookupFor(io, access) });
+}
+const MAX_SELECTION_ATTEMPTS = 3;
+const MAX_TYPED_CHECKS = 32;
+/**
+ * Let the owner accept or edit the proposal, then ask the explicit
+ * confirmation. Returns the confirmed gate, or null when the owner declined
+ * (nothing is stored then).
+ */
+async function editProposalInteractively(io, proposal, numbered, gateDeps) {
+    const prompt = io.promptLine;
+    if (!prompt)
+        return null;
+    let providerChecks = [...proposal.proposed.providerChecks];
+    let localIds = [...proposal.proposed.localCommandIds];
+    let chosen = false;
+    for (let attempt = 0; attempt < MAX_SELECTION_ATTEMPTS && !chosen; attempt++) {
+        const answer = (await prompt('Gate members — press Enter to accept the proposal, type numbers (e.g. 1,3) to choose, or "none" for no gate: ')).trim();
+        if (answer === "") {
+            chosen = true;
+        }
+        else if (answer.toLowerCase() === "none") {
+            providerChecks = [];
+            localIds = [];
+            chosen = true;
+        }
+        else {
+            const picks = answer.split(",").map((p) => Number.parseInt(p.trim(), 10));
+            if (picks.every((n) => Number.isInteger(n) && n >= 1 && n <= numbered.length)) {
+                providerChecks = [];
+                localIds = [];
+                for (const n of picks) {
+                    const entry = numbered[n - 1];
+                    if (entry.kind === "provider" && !providerChecks.includes(entry.name))
+                        providerChecks.push(entry.name);
+                    if (entry.kind === "local" && !localIds.includes(entry.candidate.id))
+                        localIds.push(entry.candidate.id);
+                }
+                chosen = true;
+            }
+            else {
+                io.log(`  Choose numbers between 1 and ${numbered.length}, "none", or press Enter.`);
+            }
+        }
+    }
+    if (!chosen)
+        return null;
+    // An exact owner-typed check name is allowed (E-15): a matrix job's reported
+    // name, or a check that has not reported yet. It is stored verbatim and
+    // admission refuses it until it really reports.
+    while (providerChecks.length < MAX_TYPED_CHECKS) {
+        const typed = (await prompt("Exact provider check name to add (Enter to finish): ")).trim();
+        if (typed === "")
+            break;
+        if (!isValidCheckName(typed)) {
+            io.log("  That name cannot be stored (empty, over 200 characters, or control characters).");
+            continue;
+        }
+        if (!providerChecks.includes(typed))
+            providerChecks.push(typed);
+        io.log(`  Added "${typed}". Admission refuses it until it has actually reported on this ` +
+            "repository's default branch or a merged pull request — run CI once if it has not.");
+    }
+    const desired = desiredFromProposalSelection(proposal, providerChecks, localIds);
+    // A migration guard matters only when the repository carries Alembic
+    // migrations; BAPI-1390's admission then requires one.
+    const hasAlembic = gateDeps?.discoveryFs ? await gateDeps.discoveryFs.exists("alembic.ini") : false;
+    if (hasAlembic && desired.kind !== "none") {
+        const members = [
+            ...desired.providerChecks.map((name) => ({ kind: "provider", name })),
+            ...desired.localCommands.map((c) => ({ kind: "local", name: c.name })),
+        ];
+        io.log("  This repository has alembic.ini, so admission requires a migration guard member:");
+        members.forEach((m, i) => io.log(`    [${i + 1}] ${m.kind} ${m.name}`));
+        const pick = Number.parseInt((await prompt("Migration guard member number (Enter for none): ")).trim(), 10);
+        if (Number.isInteger(pick) && pick >= 1 && pick <= members.length) {
+            desired.migrationGuard = members[pick - 1];
+        }
+    }
+    return desired;
+}
+/**
+ * Decide the repository gate for this run (BEFORE any write).
+ *
+ * 1. The capability probe (property 2) — refused ⇒ exit 1, nothing written.
+ * 2. Read the stored gate (BAPI-1390 GET; a legacy `--required-check` setup
+ *    reads as confirmed).
+ * 3. Explicit gate flags ⇒ owner input, shown against the stored gate.
+ *    No flags and a confirmed gate ⇒ use it unchanged (no write).
+ *    No flags and no confirmed gate ⇒ discovery proposal, then the owner
+ *    confirms or edits it at a prompt; without a prompt, exit 1 having saved
+ *    nothing.
+ */
+export async function resolveConductorGate(io, access, flags, gateDeps, options) {
+    io.log("");
+    io.log("Repository gate — what must pass before a child merges…");
+    if (!(await requireGateProfileCapability(io, access)))
+        return { kind: "exit", code: 1 };
+    let current;
+    try {
+        current = await fetchConductorGateProfile(access, io.fetchJson);
+    }
+    catch {
+        io.errorLog("The stored repository gate could not be read. Nothing was written; retry shortly.");
+        return { kind: "exit", code: 1 };
+    }
+    const currentDesired = current.confirmed && current.profile !== null ? desiredFromStored(current.profile) : null;
+    if (hasExplicitGateInput(flags)) {
+        const needsDiscovery = flags.localCommands.some((c) => c.form === "candidate") ||
+            (flags.migrationGuard?.kind === "local" && CANDIDATE_ID_RE.test(flags.migrationGuard.ref) &&
+                flags.migrationGuard.ref.includes(":"));
+        const proposal = needsDiscovery ? await runGateDiscovery(io, access, gateDeps) : null;
+        const built = desiredFromFlags(flags, currentDesired, proposal);
+        if (!built.ok) {
+            io.errorLog(`Error: ${built.error}`);
+            io.errorLog("Nothing was written.");
+            return { kind: "exit", code: 1 };
+        }
+        const desired = built.desired;
+        const removals = gateRemovals(currentDesired, desired);
+        const unchanged = current.source === "stored" && currentDesired !== null && gateMatchesStored(desired, currentDesired);
+        io.log("  Gate flags supplied: they are your explicit gate input.");
+        renderGateComparison(io, current, desired, removals);
+        if (unchanged) {
+            io.log("  The confirmed gate already matches — no gate write is needed.");
+            return { kind: "plan", plan: { current, desired: currentDesired, write: null, removals: [], origin: "stored" } };
+        }
+        if (removals.length > 0 && !flags.confirmGate && !options.dryRun) {
+            const ok = await ask(io, "Confirm this gate, including the removals above? [y/N]: ");
+            if (!ok) {
+                io.errorLog("Gate change not confirmed — nothing was written, and the stored gate is unchanged.");
+                io.errorLog("Pass --confirm-gate to confirm a removal from a script.");
+                return { kind: "exit", code: 1 };
+            }
+        }
+        return {
+            kind: "plan",
+            plan: { current, desired, write: confirmRequestFor(desired, current.revision), removals, origin: "flags" },
+        };
+    }
+    if (currentDesired !== null) {
+        io.log(current.source === "legacy"
+            ? "  Using the confirmed gate from this repository's existing --required-check setup."
+            : `  Using the confirmed gate (revision ${current.revision}).`);
+        for (const line of describeGate(currentDesired))
+            io.log(line);
+        return { kind: "plan", plan: { current, desired: currentDesired, write: null, removals: [], origin: "stored" } };
+    }
+    const proposal = await runGateDiscovery(io, access, gateDeps);
+    const numbered = renderGateProposal(io, proposal);
+    if (options.dryRun) {
+        io.log("  Dry run — a real run asks you to confirm or edit this proposal. Nothing was stored.");
+        return { kind: "unconfirmed-preview", current };
+    }
+    if (!io.promptLine) {
+        io.errorLog("");
+        io.errorLog("No confirmed gate is stored, and discovery alone never stores one. Re-run in a terminal to " +
+            "confirm or edit the proposal, or pass explicit gate flags (--provider-check, --local-command, " +
+            "or --gate-none). Nothing was written.");
+        return { kind: "exit", code: 1 };
+    }
+    const desired = await editProposalInteractively(io, proposal, numbered, gateDeps);
+    if (desired === null) {
+        io.errorLog("No gate was chosen. Nothing was written.");
+        return { kind: "exit", code: 1 };
+    }
+    renderGateComparison(io, current, desired, []);
+    const confirmed = await ask(io, "Store this repository gate? [y/N]: ");
+    if (!confirmed) {
+        io.errorLog("Gate not confirmed — nothing was written. A confirmed gate is required to continue.");
+        return { kind: "exit", code: 1 };
+    }
+    return {
+        kind: "plan",
+        plan: { current, desired, write: confirmRequestFor(desired, current.revision), removals: [], origin: "interactive" },
+    };
+}
+const GATE_WRITE_REFUSAL_TEXT = Object.freeze({
+    "stale-revision": "the stored gate changed since it was read. Re-run to see the current gate.",
+    unauthorized: "the API key was rejected, or it is not an admin key for this repository.",
+    validation: "the server refused the gate as invalid (for example an unknown customized command).",
+    "unknown-stored-state": "the stored done gate cannot be read with certainty, so its CI checks cannot be updated.",
+    "state-unavailable": "the server could not read or lock the gate right now. Retry shortly.",
+    "unsupported-protocol": "the server answered in a form this installer cannot verify.",
+    network: "the Bridge API could not be reached.",
+    timeout: "the Bridge API did not answer in time.",
+    server: "the Bridge API reported an internal error.",
+    rejected: "the Bridge API rejected the request.",
+});
+/**
+ * Send the plan's PUT. On a refusal, print the reason and the PRIOR gate as
+ * what is in force (property 4) and return null.
+ */
+export async function storeConductorGate(io, access, plan) {
+    if (plan.write === null)
+        return plan.current;
+    const outcome = await putConductorGateProfile(access, plan.write, io.postJson);
+    if (!outcome.ok) {
+        io.errorLog(`Repository gate not stored (${outcome.refusal}): ${GATE_WRITE_REFUSAL_TEXT[outcome.refusal]}`);
+        io.errorLog(`  Nothing was written. ${describeStoredHeading(plan.current)}`);
+        if (plan.current.confirmed && plan.current.profile !== null) {
+            for (const line of describeGate(desiredFromStored(plan.current.profile)))
+                io.errorLog(line);
+        }
+        return null;
+    }
+    io.log(`  stored repository gate: ${outcome.profile.profile?.kind ?? "none"} (revision ${outcome.profile.revision})`);
+    return outcome.profile;
+}
+// ---------------------------------------------------------------------------
+// Qualification (property 5)
+// ---------------------------------------------------------------------------
+/** How long to keep reading the job after the short-lived executor returns. */
+export const QUALIFICATION_OBSERVATION_BUDGET_MS = 60_000;
+export const QUALIFICATION_OBSERVATION_INTERVAL_MS = 3_000;
+function executorRemedy(io) {
+    io.errorLog("  Start a repository-wide executor to run it:");
+    io.errorLog(`    ${PRINTED_REPO_WIDE_EXECUTOR_COMMAND}`);
+    io.errorLog(`    or ${PRINTED_EXECUTOR_INSTALL_SERVICE_COMMAND}`);
+    io.errorLog(`  ${PRINTED_EXECUTOR_ID_INSTRUCTION}`);
+}
+function isTerminal(job) {
+    return job.job_status !== "queued" && job.job_status !== "running";
+}
+async function readJob(io, access, jobId) {
+    try {
+        return await fetchConductorGateQualificationJob(access, jobId, io.fetchJson);
+    }
+    catch {
+        return null;
+    }
+}
+/** Print the verified outcome. Every message is fixed text; nothing echoes command output. */
+function reportJob(io, job) {
+    if (job.qualification_state === "stale" || job.failure === "stale") {
+        io.errorLog(`  Stale after gate edit — the gate changed while job ${job.job_id} ran, so nothing was ` +
+            "recorded for the current gate. Qualify it again:");
+        io.errorLog(`    ${PRINTED_QUALIFY_GATE_COMMAND}`);
+        return "stale";
+    }
+    if (job.job_status === "queued") {
+        io.errorLog(`  Queued — job ${job.job_id} is waiting for a repository-wide executor (verified).`);
+        executorRemedy(io);
+        return "queued";
+    }
+    if (job.job_status === "running") {
+        io.log(`  Running — job ${job.job_id} is running on an executor (verified). Re-check readiness later.`);
+        return "running";
+    }
+    if (job.job_status === "succeeded" && job.qualification_state === "qualified") {
+        io.log(`  Qualified — the local gate passed under the executor at revision ${job.revision}.`);
+        return "qualified";
+    }
+    if (job.job_status === "succeeded") {
+        io.errorLog("  Failed — a confirmed command did not pass under the executor. The installation itself " +
+            "succeeded, but the local gate stays unqualified, so unattended auto-merge stays closed.");
+        io.errorLog(`  Fix the command, then qualify again: ${PRINTED_QUALIFY_GATE_COMMAND}`);
+        return "failed";
+    }
+    io.errorLog(`  Failed — the executor could not run job ${job.job_id} (no clean default-branch checkout, ` +
+        "or it was interrupted). The local gate stays unqualified.");
+    io.errorLog(`  Qualify again: ${PRINTED_QUALIFY_GATE_COMMAND}`);
+    return "could_not_run";
+}
+/**
+ * Enqueue the qualification for `revision` and drain it with the short-lived
+ * executor, reporting ONLY verified state. Never fatal to the install.
+ */
+export async function runConductorGateQualification(io, access, gateDeps, input) {
+    io.log("");
+    io.log("Gate qualification — running the confirmed local commands once under the executor…");
+    // Re-probed immediately before the enqueue and the executor start (E-6): the
+    // executor's claim carries `job_types`, which an older server answers with 422.
+    if (!(await requireGateProfileCapability(io, access)))
+        return "refused";
+    const enqueued = await enqueueConductorGateQualification(access, { expectedRevision: input.revision }, io.postJson);
+    if (enqueued.kind === "refused") {
+        const text = {
+            "profile-not-confirmed": "no confirmed gate is stored for this repository.",
+            "no-local-commands": "the confirmed gate has no local commands, so there is nothing to qualify.",
+            "stale-revision": "the gate changed since it was confirmed. Re-run to qualify the current gate.",
+            "state-unavailable": "the server could not enqueue it right now. Nothing was queued; retry shortly.",
+            unauthorized: "the API key was rejected for this repository.",
+            "unsupported-protocol": "the server does not support gate qualification.",
+        };
+        io.errorLog(`  Not queued: ${text[enqueued.refusal] ?? "the Bridge API rejected the request."}`);
+        return enqueued.refusal === "no-local-commands" ? "not_applicable" : "refused";
+    }
+    if (enqueued.kind === "uncertain") {
+        io.errorLog("  The enqueue did not answer clearly, so this run cannot say whether a job is queued. " +
+            "Check readiness, or qualify again:");
+        io.errorLog(`    ${PRINTED_QUALIFY_GATE_COMMAND}`);
+        executorRemedy(io);
+        return "unverified";
+    }
+    const verified = await readJob(io, access, enqueued.jobId);
+    if (verified === null) {
+        io.errorLog(`  The server accepted job ${enqueued.jobId}, but its state could not be verified, so this run ` +
+            "does not report it as queued.");
+        executorRemedy(io);
+        return "unverified";
+    }
+    if (isTerminal(verified))
+        return reportJob(io, verified);
+    const runExecutor = gateDeps?.runQualificationExecutor;
+    if (!runExecutor) {
+        return reportJob(io, verified);
+    }
+    io.log(`  Starting a short-lived repository-wide executor for job ${verified.job_id} ` +
+        "(qualification jobs only; command output appears below, on this terminal only)…");
+    let run;
+    try {
+        run = await runExecutor({ repoName: access.repoName, baseUrl: input.baseUrl });
+    }
+    catch {
+        run = { started: false, exitCode: 1 };
+    }
+    if (!run.started) {
+        io.errorLog("  The short-lived executor could not start on this host.");
+    }
+    // The executor's exit code proves nothing (property 5): read the server.
+    const now = gateDeps?.now ?? (() => Date.now());
+    const sleep = gateDeps?.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const deadline = now() + QUALIFICATION_OBSERVATION_BUDGET_MS;
+    let latest = null;
+    while (true) {
+        const read = await readJob(io, access, verified.job_id);
+        if (read !== null)
+            latest = read;
+        if (latest !== null && isTerminal(latest))
+            break;
+        // A queued job after the executor returned will not move on its own here.
+        if (latest !== null && latest.job_status === "queued")
+            break;
+        const remaining = deadline - now();
+        if (remaining <= 0)
+            break;
+        await sleep(Math.min(QUALIFICATION_OBSERVATION_INTERVAL_MS, remaining));
+    }
+    if (latest === null) {
+        io.errorLog(`  Job ${verified.job_id}'s state could not be read after the executor returned.`);
+        executorRemedy(io);
+        return "unverified";
+    }
+    return reportJob(io, latest);
+}
+// ---------------------------------------------------------------------------
+// Standalone actions: --clear-gate and --qualify-gate
+// ---------------------------------------------------------------------------
+/** `--clear-gate`: BAPI-1390's clear action under the revision compare-and-swap. */
+export async function runClearConductorGate(io, access, options) {
+    if (!(await requireGateProfileCapability(io, access)))
+        return 1;
+    let current;
+    try {
+        current = await fetchConductorGateProfile(access, io.fetchJson);
+    }
+    catch {
+        io.errorLog("The stored repository gate could not be read. Nothing was written; retry shortly.");
+        return 1;
+    }
+    io.log("");
+    io.log(`  ${describeStoredHeading(current)}`);
+    if (current.confirmed && current.profile !== null) {
+        for (const line of describeGate(desiredFromStored(current.profile)))
+            io.log(line);
+    }
+    if (current.source === "unconfirmed" && !current.stored_malformed) {
+        io.log("  There is no stored gate to clear. Nothing was written.");
+        return 0;
+    }
+    io.log("  Clearing removes the confirmed gate, its qualification, and its CI-check projection; " +
+        "unattended runs then need a newly confirmed gate.");
+    if (options.dryRun) {
+        io.log("  Dry run — would send the clear action. Nothing was written.");
+        return 0;
+    }
+    if (!(await ask(io, "Clear the confirmed repository gate? [y/N]: "))) {
+        io.log("  Not cleared — nothing was written.");
+        return 0;
+    }
+    const outcome = await putConductorGateProfile(access, { action: "clear", confirm: true, expected_revision: current.revision }, io.postJson);
+    if (!outcome.ok) {
+        io.errorLog(`Repository gate not cleared (${outcome.refusal}): ${GATE_WRITE_REFUSAL_TEXT[outcome.refusal]}`);
+        return 1;
+    }
+    io.log(`  repository gate cleared (${outcome.profile.outcome ?? "cleared"}).`);
+    return 0;
+}
+/** `--qualify-gate` on its own: qualify the CURRENT confirmed gate. */
+export async function runQualifyConductorGate(io, access, gateDeps, options) {
+    if (!(await requireGateProfileCapability(io, access)))
+        return 1;
+    let current;
+    try {
+        current = await fetchConductorGateProfile(access, io.fetchJson);
+    }
+    catch {
+        io.errorLog("The stored repository gate could not be read. Nothing was queued; retry shortly.");
+        return 1;
+    }
+    if (!current.confirmed || current.profile === null) {
+        io.errorLog("No confirmed repository gate is stored, so there is nothing to qualify. Confirm one first " +
+            "with install-bridge conductor. Nothing was queued.");
+        return 1;
+    }
+    const profile = current.profile;
+    io.log("");
+    io.log(`  Confirmed gate (revision ${current.revision}):`);
+    for (const line of describeGate(desiredFromStored(profile)))
+        io.log(line);
+    if (profile.local_commands.length === 0) {
+        io.log(`  Qualification is not applicable: a ${profile.kind} gate has no local commands. Nothing was queued.`);
+        return 0;
+    }
+    if (options.dryRun) {
+        io.log("  Dry run — would enqueue one qualification job and start a short-lived executor. Nothing was queued.");
+        return 0;
+    }
+    await runConductorGateQualification(io, access, gateDeps, {
+        revision: current.revision,
+        baseUrl: options.baseUrl,
+    });
+    // A failed qualification warns; it never fails the command (property 5).
+    return 0;
+}
+// ---------------------------------------------------------------------------
+// BAPI-1405: epic-branch CI inspection, advice, and the explicit decision
+// ---------------------------------------------------------------------------
+//
+// An unattended epic run merges each child into `epic/<EPIC>` through a pull
+// request. Whether any CI runs on that pull request depends on the repository's
+// workflow triggers, and whether a human approval is needed depends on its
+// branch rules. This step READS both, explains what it found in plain words, and
+// asks the owner to choose `include` or `decline`. It keeps property 1: the
+// inspection only reports and proposes. It never confirms a gate, never
+// authorizes a merge, and never turns an unreadable answer into `decline`.
+//
+// The approval-rule exemption is a separate, warning-toned offer. Only an
+// explicit typed "yes" lets it change a ruleset, and only through the owner's
+// own `gh` login. The `--epic-branch-ci-decision` flag never grants that consent.
+/** The two values `--epic-branch-ci-decision` accepts. */
+export const EPIC_BRANCH_CI_DECISION_FLAG_VALUES = ["include", "decline"];
+/**
+ * Parse one `--epic-branch-ci-decision` value. Exact and lower-case only:
+ * anything else is refused at parse time, before install starts.
+ */
+export function parseEpicBranchCiDecisionFlag(raw) {
+    if (EPIC_BRANCH_CI_DECISION_FLAG_VALUES.includes(raw)) {
+        return { ok: true, value: raw };
+    }
+    return {
+        ok: false,
+        error: "--epic-branch-ci-decision must be include or decline.",
+    };
+}
+/**
+ * The never-created branch name used for the rules read when no real epic
+ * branch is known locally.
+ *
+ * GitHub's "rules for a branch" endpoint answers for a branch NAME, so a name
+ * that matches `epic/**` shows which rulesets would apply to an epic branch.
+ * GitHub documents that the branch need not exist, so the rules reader trusts
+ * an empty list on an unproven branch as "no approvals", reported `inferred`
+ * until that behavior is verified live. A placeholder
+ * shaped like a real key (for example `epic/BAPI-0`) is deliberately avoided:
+ * it could collide with a real branch and be mistaken for one.
+ */
+export const EPIC_BRANCH_CI_PROBE_BRANCH = "epic/bridge-install-probe";
+/** The concrete `epic/<EPIC>` shape: one path segment after `epic/`. */
+const EPIC_BRANCH_NAME_RE = /^epic\/[A-Za-z0-9][A-Za-z0-9._-]{0,99}$/;
+/** The three coverage conclusions, printed first and verbatim. */
+export const EPIC_BRANCH_CI_COVERAGE_CONCLUSION = Object.freeze({
+    covers: "A pull_request trigger covers epic-branch PRs.",
+    does_not_cover: "No inspected trigger covers epic-branch PRs.",
+    could_not_tell: "Could not tell whether a pull_request trigger covers epic-branch PRs.",
+});
+/** One next step per bounded reason token. Unknown tokens get the generic step. */
+const COVERAGE_NEXT_STEP = Object.freeze({
+    no_pr_trigger: "add a pull_request trigger whose branches list includes 'epic/**'.",
+    branch_filter_excludes_epic: "add 'epic/**' to this workflow's pull_request branches list.",
+    branch_filter_uncertain: "make the pull_request branches list name 'epic/**' directly, so it clearly matches epic branches.",
+    path_filter: "a paths filter decides per change whether the workflow starts; check it matches what children change, " +
+        "or add 'epic/**' to a pull_request trigger without a paths filter.",
+    types_filter: "include opened and synchronize in the pull_request types, or remove the types list.",
+    indirect_trigger: "confirm the workflow that triggers this one runs on pull requests into 'epic/**'.",
+    reusable_workflow_job: "confirm the calling workflow runs on pull requests into 'epic/**'.",
+    unparseable: "check the file is valid YAML with a top-level on: key.",
+    unsupported_structure: "write the pull_request trigger as a plain mapping with a branches list that includes 'epic/**'.",
+    listing_failed: "check that .github/workflows is readable, then re-run the install.",
+    file_limit_reached: "too many workflow files to inspect; confirm by hand that one includes 'epic/**'.",
+    read_failed: "check the workflow file is readable and not unusually large, then re-run the install.",
+    no_workflows: "add a workflow with a pull_request trigger whose branches list includes 'epic/**'.",
+});
+const GENERIC_COVERAGE_NEXT_STEP = "check by hand that a pull_request trigger includes 'epic/**'.";
+function coverageNextStep(reason) {
+    return COVERAGE_NEXT_STEP[reason] ?? GENERIC_COVERAGE_NEXT_STEP;
+}
+/** Wrap a runner so a spawn failure (for example `gh` not installed) is an exit code, never a throw. */
+function safeGhRunner(run) {
+    return async (args, opts) => {
+        try {
+            return await run(args, opts);
+        }
+        catch {
+            return { exitCode: 127, stdout: "", stderr: "gh could not be started" };
+        }
+    };
+}
+/**
+ * The default branch's classic protection, labelled as CONTEXT. It is evidence
+ * about the repository, never the epic-branch answer. Null when not read.
+ */
+export function defaultBranchContextLine(rules) {
+    const ctx = rules?.defaultBranchClassicApprovals;
+    if (ctx === undefined)
+        return null;
+    const name = rules?.defaultBranch ? rules.defaultBranch : "the default branch";
+    let finding;
+    if (ctx === "yes") {
+        const n = rules?.defaultBranchClassicApprovalCount;
+        finding =
+            typeof n === "number"
+                ? `classic protection requires ${n} approval${n === 1 ? "" : "s"} on ${name}`
+                : `classic protection requires approvals (count unknown) on ${name}`;
+    }
+    else if (ctx === "no") {
+        finding = `classic protection requires no approvals on ${name}`;
+    }
+    else {
+        finding = `could not tell whether classic protection requires approvals on ${name}`;
+    }
+    return `  Default branch (context): ${finding} — this is not the epic-branch answer.`;
+}
+/**
+ * Print the findings in decision-support order: the coverage conclusion, the
+ * approval-rule finding, the recommendation, then indented evidence for each
+ * unresolved workflow with its reason and one next step.
+ */
+export function renderEpicBranchCiFindings(io, coverage, rules) {
+    io.log(`  ${EPIC_BRANCH_CI_COVERAGE_CONCLUSION[coverage.coverage]}`);
+    const approvals = rules?.approvalsRequired ?? "could_not_tell";
+    if (approvals === "yes") {
+        const count = rules?.requiredApprovingReviewCount;
+        io.log("  Approval rules apply to epic-branch PRs: yes" +
+            (typeof count === "number" ? ` (${count} required approval${count === 1 ? "" : "s"}).` : " (count unknown)."));
+    }
+    else if (approvals === "no") {
+        io.log("  Approval rules apply to epic-branch PRs: no.");
+    }
+    else {
+        io.log("  Approval rules apply to epic-branch PRs: could not tell" +
+            (rules?.reason ? ` (${rules.reason}).` : "."));
+    }
+    const contextLine = defaultBranchContextLine(rules);
+    if (contextLine !== null)
+        io.log(contextLine);
+    if (coverage.coverage === "covers") {
+        io.log("  Recommended: include epic-branch CI. Trigger coverage means a workflow should start on " +
+            "epic-branch PRs; it is not proof that a check runs or passes there.");
+    }
+    else {
+        io.log("  Recommended: add 'epic/**' to the pull_request base-branch filter, for example:");
+        io.log("      on:");
+        io.log("        pull_request:");
+        io.log("          branches: [main, 'epic/**']");
+        io.log("    Then include epic-branch CI below.");
+    }
+    const unresolved = coverage.workflows.filter((w) => w.coverage !== "covers");
+    if (coverage.coverage !== "covers" && unresolved.length > 0) {
+        io.log("  Workflows that do not clearly cover epic-branch PRs:");
+        for (const w of unresolved) {
+            io.log(`    ${w.path}: ${w.coverage} (${w.reason}) — next step: ${coverageNextStep(w.reason)}`);
+        }
+    }
+    else if (coverage.coverage !== "covers") {
+        io.log(`    (${coverage.reason}) — next step: ${coverageNextStep(coverage.reason)}`);
+    }
+}
+/**
+ * Decide include/decline for this run. Never guesses:
+ *
+ * * an explicit `--epic-branch-ci-decision` flag is owner input and wins;
+ * * otherwise, at a prompt, only a typed `include` or `decline` counts —
+ *   Include is the displayed default, but a blank or other answer records
+ *   nothing;
+ * * without a prompt, nothing is recorded and the owner is told how to record
+ *   one.
+ *
+ * Returns the decision, or null when none was made.
+ */
+export async function resolveEpicBranchCiDecision(io, flag) {
+    io.log("  Include: each child waits for the checks that run on its epic-branch PR before it merges.");
+    io.log("  Decline: children merge into the epic branch without waiting for checks that never run there. " +
+        "Problems then surface only at the human-gated integration PR into the base branch.");
+    if (flag !== null) {
+        io.log(`  Using --epic-branch-ci-decision=${flag}.`);
+        return flag;
+    }
+    if (!io.promptLine) {
+        io.log("  No epic-branch CI decision was recorded: this run cannot prompt. Re-run in a terminal, or pass " +
+            "--epic-branch-ci-decision=include or --epic-branch-ci-decision=decline. Until one is recorded, " +
+            "runs behave as include.");
+        return null;
+    }
+    const answer = (await io.promptLine('Epic-branch CI — type "include" (default) or "decline": ')).trim().toLowerCase();
+    if (answer === "include" || answer === "decline")
+        return answer;
+    io.log("  No epic-branch CI decision was recorded: type include or decline to choose. Re-run to choose, or " +
+        "pass --epic-branch-ci-decision=include or --epic-branch-ci-decision=decline. Until one is " +
+        "recorded, runs behave as include.");
+    return null;
+}
+function printExemptionManualSteps(io, ownerRepo, branch) {
+    io.log("    To exclude epic/** from the approval rule yourself:");
+    // The never-created probe name is not a real branch, so the steps keep the
+    // `epic/<EPIC>` placeholder for it.
+    const steps = branch === EPIC_BRANCH_CI_PROBE_BRANCH
+        ? exemptionManualSteps(ownerRepo)
+        : exemptionManualSteps(ownerRepo, branch);
+    for (const line of steps)
+        io.log(`      ${line}`);
+}
+/**
+ * The approval-rule exemption offer (requirement 6). Separate from the
+ * include/decline choice and warning-toned. A ruleset is changed only after an
+ * explicit typed "yes", a passed scope check, and a confirming re-read.
+ */
+export async function offerApprovalExemption(io, seams, run, ownerRepo, branch, rules) {
+    const approvals = rules?.approvalsRequired ?? "could_not_tell";
+    if (approvals === "no")
+        return "not_needed";
+    if (approvals === "could_not_tell") {
+        io.log("");
+        io.log("  Could not tell whether an approval rule applies to epic-branch PRs, so no exemption was offered " +
+            "and nothing was changed.");
+        printExemptionManualSteps(io, ownerRepo, branch);
+        return "could_not_tell";
+    }
+    io.log("");
+    io.log("  Warning: an approval rule applies to epic-branch PRs.");
+    io.log("    Each child merge waits for a human approval unless the merging account can bypass the rule. " +
+        "Whether it can is unknown: check the ruleset's bypass list.");
+    io.log("    Bridge can exclude epic/** from this approval rule with your own gh login. It changes only the " +
+        "ruleset's excluded branches, and only for a repository ruleset that holds nothing but the approval rule.");
+    if (!io.promptLine) {
+        io.log("    This run cannot prompt, so nothing was changed. The --epic-branch-ci-decision flag never grants this.");
+        printExemptionManualSteps(io, ownerRepo, branch);
+        return "printed_steps";
+    }
+    const consent = await ask(io, "Exclude epic/** from the approval rule now? Type yes to change it [y/N]: ");
+    if (!consent) {
+        io.log("    Not changed.");
+        printExemptionManualSteps(io, ownerRepo, branch);
+        return "declined";
+    }
+    const assess = seams.assessExemption ?? assessApprovalExemptionScope;
+    let assessment;
+    try {
+        assessment = await assess(run, ownerRepo, branch);
+    }
+    catch {
+        assessment = { eligible: false, reason: "scope_unreadable", rulesetIds: [] };
+    }
+    if (!assessment.eligible) {
+        io.log(`    Not changed: the approval rule is not safe to change automatically (${assessment.reason}).`);
+        printExemptionManualSteps(io, ownerRepo, branch);
+        return "printed_steps";
+    }
+    const apply = seams.applyExemption ?? applyApprovalExemption;
+    let applied;
+    try {
+        applied = await apply(run, ownerRepo, branch, assessment);
+    }
+    catch {
+        applied = { confirmed: false, reason: "apply_uncertain" };
+    }
+    if (applied.confirmed) {
+        io.log("    Excluded epic/** from the approval rule. A re-read confirmed no approval rule remains and required checks are unchanged.");
+        return "applied";
+    }
+    io.log(`    Could not confirm the change (${applied.reason}). Check the ruleset yourself; nothing else will be attempted.`);
+    printExemptionManualSteps(io, ownerRepo, branch);
+    return "could_not_tell";
+}
+/**
+ * Run the epic-branch CI step: detect the provider, inspect workflow triggers
+ * and epic-branch rules, print findings, resolve include/decline, offer the
+ * approval exemption, and record an explicit decision with its evidence.
+ *
+ * Never blocks the install: a failed read or write prints a warning and the
+ * step returns. It never writes `decline` unless the owner chose it.
+ */
+export async function runEpicBranchCiInspection(io, access, gateDeps, options) {
+    const result = {
+        status: "completed",
+        coverage: null,
+        rules: null,
+        exemptionOutcome: null,
+        decision: null,
+        evidence: null,
+        recorded: false,
+        manualAction: null,
+    };
+    io.log("");
+    io.log("Epic-branch CI — do checks run on pull requests into epic branches?");
+    const seams = gateDeps?.epicBranchCi;
+    if (!seams) {
+        io.log("  skipped — this caller supplied no epic-branch CI inspection seams. Nothing was recorded.");
+        return { ...result, status: "skipped_no_seams" };
+    }
+    if (options.dryRun) {
+        io.log("  Dry run — would inspect workflow triggers and epic-branch rules, then ask include or decline. Nothing was recorded.");
+        return { ...result, status: "skipped_dry_run" };
+    }
+    let provider;
+    try {
+        provider = await seams.detectProvider();
+    }
+    catch {
+        provider = { kind: "unknown" };
+    }
+    if (provider.kind !== "github") {
+        io.log("  The epic-branch CI inspection is GitHub-only, and this repository's remote is not on github.com" +
+            (provider.kind === "unknown" ? " (or could not be read)" : "") +
+            ". No epic-branch CI decision was recorded.");
+        return { ...result, status: "skipped_not_github" };
+    }
+    const ownerRepo = provider.ownerRepo;
+    const run = safeGhRunner(seams.runGh);
+    let branch = EPIC_BRANCH_CI_PROBE_BRANCH;
+    try {
+        const found = seams.findExampleEpicBranch ? await seams.findExampleEpicBranch() : null;
+        if (found !== null && EPIC_BRANCH_NAME_RE.test(found))
+            branch = found;
+    }
+    catch {
+        // Keep the probe name: the rules reader reports could_not_tell for it.
+    }
+    let coverage;
+    try {
+        coverage = await (seams.inspectCoverage ?? inspectEpicBranchWorkflowCoverage)(seams.fs);
+    }
+    catch {
+        coverage = { coverage: "could_not_tell", reason: "read_failed", workflows: [] };
+    }
+    let rules;
+    try {
+        rules = await (seams.readRules ?? readEpicBranchRulesViaGh)(run, ownerRepo, branch);
+    }
+    catch {
+        rules = null;
+    }
+    result.coverage = coverage.coverage;
+    result.rules = rules;
+    renderEpicBranchCiFindings(io, coverage, rules);
+    const decision = await resolveEpicBranchCiDecision(io, options.decisionFlag);
+    const exemptionOutcome = await offerApprovalExemption(io, seams, run, ownerRepo, branch, rules);
+    const evidence = buildEpicBranchCiEvidence(coverage.coverage, rules, exemptionOutcome);
+    result.decision = decision;
+    result.exemptionOutcome = exemptionOutcome;
+    result.evidence = evidence;
+    // No decision is not a failure: nothing recorded behaves like include, and
+    // the reason was already printed. It is not added to the manual steps.
+    if (decision === null)
+        return result;
+    const record = seams.recordDecision ??
+        ((acc, request) => putEpicBranchCiDecision(acc, acc.repoName, request, io.postJson));
+    try {
+        await record(access, { decision, evidence });
+        result.recorded = true;
+        io.log(`  recorded epic-branch CI decision: ${decision}`);
+    }
+    catch (err) {
+        const kind = err instanceof ConductorBridgeApiError ? err.kind : "error";
+        io.errorLog(`Warning: the epic-branch CI decision could not be recorded (${kind}). The install continues; ` +
+            "re-run it to record the decision.");
+        result.manualAction =
+            `epic-branch CI: the ${decision} decision was not recorded; re-run with ` +
+                `--epic-branch-ci-decision=${decision}.`;
+    }
+    return result;
+}