@bridge_gpt/mcp-server 0.2.67 → 0.2.68

package/build/conductor/gate-discovery.js

@@ -0,0 +1,890 @@
+/**
+ * Deterministic, read-only CI gate discovery (BAPI-1391).
+ *
+ * The installer has to propose a CI gate for a repository it has never seen:
+ * which provider check runs must pass, or, when the repository has no provider
+ * CI, which local commands stand in for them. This module gathers that proposal
+ * from two sources only — the repository's WORKING TREE, read through an
+ * injected {@link GateDiscoveryFs}, and the provider's check history, asked
+ * through an injected {@link ProviderHistoryLookup}. No LLM is involved, so the
+ * same tree and the same history always yield the same proposal.
+ *
+ * ## Why a declared name is never a proposed name
+ *
+ * A workflow file says what a job is CALLED, not what the provider REPORTS. A
+ * matrix job reports `<name> (<values>)`, an expression name is evaluated at run
+ * time, a reusable-workflow job reports `<caller> / <callee>`, and a CircleCI or
+ * Jenkins status name is a convention, not a guarantee. A gate built on a name
+ * that never reports would wait forever. So configuration only ever produces
+ * LOOKUP names; a provider candidate exists only when the history lookup said
+ * `reported` for that exact name. Names whose shape may vary are recorded as
+ * evidence and never looked up at all.
+ *
+ * ## Why "no history" and "empty history" stay distinct
+ *
+ * A lookup that succeeded and saw nothing is a FACT ("these names never
+ * reported"); a lookup that failed is an ABSENCE of facts. Collapsing the two
+ * would let an outage masquerade as "this repository has no CI". The history
+ * state therefore has three values — `available`, `unavailable`, and
+ * `not_queried` — and a successful empty answer is always `available`.
+ *
+ * ## Invariants
+ *
+ * - Read-only and bounded: at most {@link MAX_WORKFLOW_FILES} workflow files and
+ *   {@link MAX_DISCOVERY_FILE_BYTES} per file. The node seam refuses absolute
+ *   paths and `..` segments and resolves symlinks before reading, so nothing
+ *   outside the repository root is opened.
+ * - Hooks (`.husky/`, `.pre-commit-config.yaml`, `.git/hooks/pre-push`) are
+ *   evidence only. Their bodies are shell, and shell is never turned into a
+ *   command.
+ * - Local commands are argv arrays, never shell strings. A declaration that is
+ *   ambiguous or unsupported is omitted rather than guessed at.
+ * - Customer names are kept verbatim (trimmed only). Nothing here assumes the
+ *   Bridge API repository's own layout.
+ * - Deterministic order everywhere: file names sorted by code unit, jobs in file
+ *   order, local candidates in a fixed order.
+ */
+import fs from "node:fs/promises";
+import path from "node:path";
+// ---------------------------------------------------------------------------
+// Bounds and fixed vocabularies
+// ---------------------------------------------------------------------------
+/** Workflow files read per discovery, after sorting by name. */
+export const MAX_WORKFLOW_FILES = 64;
+/** Largest file the collector will read; larger files are treated as absent. */
+export const MAX_DISCOVERY_FILE_BYTES = 256 * 1024;
+/** Names sent to the provider-history lookup (the server's cap). */
+export const MAX_LOOKUP_NAMES = 32;
+/** Timeout carried by every local command candidate. */
+export const LOCAL_COMMAND_TIMEOUT_SECONDS = 1800;
+/** Shape every local command `name` must match. */
+export const GATE_COMMAND_NAME_PATTERN = /^[a-z0-9][a-z0-9-]{0,63}$/;
+/** Jenkins' multibranch status names, asked of history when a Jenkinsfile exists. */
+export const JENKINS_LOOKUP_NAMES = [
+    "continuous-integration/jenkins/branch",
+    "continuous-integration/jenkins/pr-merge",
+];
+/** The script body `npm init` writes; it is a placeholder, not a test command. */
+export const NPM_PLACEHOLDER_TEST_SCRIPT = 'echo "Error: no test specified" && exit 1';
+const WORKFLOWS_DIR = ".github/workflows";
+const CIRCLECI_CONFIG = ".circleci/config.yml";
+/**
+ * Client-side git hook names recognised under `.husky/`. Restricting to known
+ * names keeps husky's own `_` helper directory and dotfiles out of the evidence.
+ */
+const GIT_CLIENT_HOOK_NAMES = [
+    "applypatch-msg",
+    "commit-msg",
+    "post-checkout",
+    "post-commit",
+    "post-merge",
+    "post-rewrite",
+    "pre-applypatch",
+    "pre-commit",
+    "pre-merge-commit",
+    "pre-push",
+    "pre-rebase",
+    "prepare-commit-msg",
+];
+// ---------------------------------------------------------------------------
+// Node filesystem seam
+// ---------------------------------------------------------------------------
+const PATH_REFUSED = "gate discovery refuses a path outside the repository root";
+/**
+ * Split a repository-relative path into safe segments, or throw. Absolute
+ * paths (POSIX or Windows), backslashes, NUL bytes, and `..` segments are all
+ * refused: the seam's callers only ever pass fixed names and directory entries,
+ * so any of these signals a bug, and a bug must not become an escape.
+ */
+function safeSegments(relPath) {
+    if (typeof relPath !== "string" ||
+        relPath.includes("\0") ||
+        relPath.includes("\\") ||
+        path.posix.isAbsolute(relPath) ||
+        path.win32.isAbsolute(relPath)) {
+        throw new Error(PATH_REFUSED);
+    }
+    const segments = relPath.split("/").filter((s) => s !== "" && s !== ".");
+    if (segments.some((s) => s === ".."))
+        throw new Error(PATH_REFUSED);
+    return segments;
+}
+function isWithin(root, candidate) {
+    const rel = path.relative(root, candidate);
+    return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
+}
+/**
+ * The real {@link GateDiscoveryFs}, over `node:fs/promises`.
+ *
+ * Every access resolves the target with `realpath` and re-checks containment
+ * against the resolved root, so a symlink inside the repository cannot lead a
+ * read outside it. Every I/O failure reads as "absent" (null / false); only an
+ * invalid path argument throws.
+ */
+export function createNodeGateDiscoveryFs(repoRoot) {
+    let realRoot = null;
+    const root = () => {
+        realRoot ??= fs.realpath(repoRoot).catch(() => null);
+        return realRoot;
+    };
+    /** The contained real path for `relPath`, or null when absent or escaping. */
+    const resolve = async (relPath) => {
+        const segments = safeSegments(relPath);
+        const base = await root();
+        if (base === null)
+            return null;
+        try {
+            const real = await fs.realpath(path.join(base, ...segments));
+            return isWithin(base, real) ? real : null;
+        }
+        catch {
+            return null;
+        }
+    };
+    return {
+        async readText(relPath) {
+            const target = await resolve(relPath);
+            if (target === null)
+                return null;
+            let handle = null;
+            try {
+                handle = await fs.open(target, "r");
+                const stat = await handle.stat();
+                if (!stat.isFile() || stat.size > MAX_DISCOVERY_FILE_BYTES)
+                    return null;
+                // Read one byte past the cap so a file that grew after fstat is still refused.
+                const buffer = Buffer.alloc(MAX_DISCOVERY_FILE_BYTES + 1);
+                const { bytesRead } = await handle.read(buffer, 0, buffer.length, 0);
+                if (bytesRead > MAX_DISCOVERY_FILE_BYTES)
+                    return null;
+                return buffer.subarray(0, bytesRead).toString("utf8");
+            }
+            catch {
+                return null;
+            }
+            finally {
+                await handle?.close().catch(() => undefined);
+            }
+        },
+        async listDir(relPath) {
+            const target = await resolve(relPath);
+            if (target === null)
+                return null;
+            try {
+                const stat = await fs.stat(target);
+                if (!stat.isDirectory())
+                    return null;
+                return await fs.readdir(target);
+            }
+            catch {
+                return null;
+            }
+        },
+        async exists(relPath) {
+            return (await resolve(relPath)) !== null;
+        },
+    };
+}
+/** Non-blank, non-comment lines with their indentation measured in spaces. */
+function significantLines(text) {
+    const out = [];
+    for (const raw of text.split(/\r?\n/)) {
+        const trimmed = raw.trim();
+        if (trimmed === "" || trimmed.startsWith("#"))
+            continue;
+        const indent = raw.length - raw.trimStart().length;
+        const leading = raw.slice(0, indent);
+        out.push({ indent, text: trimmed, tabIndent: leading.includes("\t") });
+    }
+    return out;
+}
+/** Characters that start a YAML construct this scanner deliberately does not read. */
+const UNSUPPORTED_SCALAR_STARTS = new Set(["|", ">", "&", "*", "!", "{", "[", "%", "@", "`"]);
+const UNSUPPORTED_KEY_STARTS = new Set([...UNSUPPORTED_SCALAR_STARTS, "-", "?", ":", ",", "]", "}", "#"]);
+/** Split `key: rest` (key optionally quoted). Null when the line is not a mapping entry. */
+function splitKeyLine(text) {
+    let key;
+    let after;
+    const quote = text[0];
+    if (quote === '"' || quote === "'") {
+        const close = text.indexOf(quote, 1);
+        if (close < 0)
+            return null;
+        key = text.slice(1, close);
+        after = text.slice(close + 1).trimStart();
+        if (!after.startsWith(":"))
+            return null;
+        after = after.slice(1);
+        if (after !== "" && !/^\s/.test(after))
+            return null;
+    }
+    else {
+        if (UNSUPPORTED_KEY_STARTS.has(text[0] ?? ""))
+            return null;
+        let colon = -1;
+        for (let i = 0; i < text.length; i++) {
+            const next = text[i + 1];
+            if (text[i] === ":" && (next === undefined || next === " " || next === "\t")) {
+                colon = i;
+                break;
+            }
+            if (text[i] === "#" && i > 0 && /\s/.test(text[i - 1] ?? ""))
+                return null;
+        }
+        if (colon < 0)
+            return null;
+        key = text.slice(0, colon).trimEnd();
+        after = text.slice(colon + 1);
+    }
+    if (key === "")
+        return null;
+    let rest = after.trim();
+    if (rest.startsWith("#"))
+        rest = "";
+    return { key, rest };
+}
+/** True when what follows a closed quoted scalar is nothing or a comment. */
+function onlyCommentAfter(remainder) {
+    const r = remainder.trim();
+    return r === "" || r.startsWith("#");
+}
+/**
+ * Read a single-line YAML scalar. Plain, single-quoted, and double-quoted
+ * scalars with simple escapes are understood; anything else (block scalars,
+ * anchors, aliases, tags, flow collections, unknown escapes) is `unclear`.
+ */
+export function parseInlineScalar(rest) {
+    const text = rest.trim();
+    if (text === "" || text.startsWith("#"))
+        return { kind: "empty" };
+    if (text[0] === '"') {
+        let value = "";
+        for (let i = 1; i < text.length; i++) {
+            const ch = text[i];
+            if (ch === "\\") {
+                const next = text[i + 1];
+                if (next === '"' || next === "\\" || next === "/") {
+                    value += next;
+                    i++;
+                    continue;
+                }
+                return { kind: "unclear" };
+            }
+            if (ch === '"') {
+                return onlyCommentAfter(text.slice(i + 1)) ? { kind: "value", value: value.trim() } : { kind: "unclear" };
+            }
+            value += ch;
+        }
+        return { kind: "unclear" };
+    }
+    if (text[0] === "'") {
+        let value = "";
+        for (let i = 1; i < text.length; i++) {
+            const ch = text[i];
+            if (ch === "'") {
+                if (text[i + 1] === "'") {
+                    value += "'";
+                    i++;
+                    continue;
+                }
+                return onlyCommentAfter(text.slice(i + 1)) ? { kind: "value", value: value.trim() } : { kind: "unclear" };
+            }
+            value += ch;
+        }
+        return { kind: "unclear" };
+    }
+    if (UNSUPPORTED_SCALAR_STARTS.has(text[0] ?? "") || /^[-?:](\s|$)/.test(text)) {
+        return { kind: "unclear" };
+    }
+    const comment = text.search(/\s#/);
+    const value = (comment >= 0 ? text.slice(0, comment) : text).trim();
+    // A plain scalar may not contain `: ` — seeing one means this is not a scalar.
+    if (value === "" || /:(\s|$)/.test(value))
+        return { kind: "unclear" };
+    return { kind: "value", value };
+}
+/**
+ * Scan the top-level `jobs:` map of a CI YAML file.
+ *
+ * Line based and indentation tracked: only a column-0 `jobs:` is honoured, job
+ * keys are read at the first nested indentation, and `name:` / `strategy:` /
+ * `matrix:` / `uses:` at each job's direct-child indentation (a `matrix:` is
+ * also recognised anywhere beneath `strategy:`). Anything the scanner cannot
+ * read confidently marks the job `unclear` rather than guessing a name.
+ */
+export function scanJobsBlock(text) {
+    const lines = significantLines(text);
+    const start = lines.findIndex((l) => {
+        if (l.indent !== 0)
+            return false;
+        const kv = splitKeyLine(l.text);
+        return kv !== null && kv.key === "jobs";
+    });
+    if (start < 0)
+        return { found: false, unclear: false, jobs: [] };
+    if (splitKeyLine(lines[start].text)?.rest !== "") {
+        // Flow-style or aliased `jobs:` — not something a line scanner can read.
+        return { found: true, unclear: true, jobs: [] };
+    }
+    const jobs = [];
+    let unclear = false;
+    let jobIndent = null;
+    let current = null;
+    let childIndent = null;
+    let inStrategy = false;
+    let afterName = false;
+    for (let i = start + 1; i < lines.length; i++) {
+        const line = lines[i];
+        if (line.indent === 0)
+            break;
+        if (line.tabIndent) {
+            unclear = true;
+            if (current)
+                current.unclear = true;
+            continue;
+        }
+        jobIndent ??= line.indent;
+        if (line.indent < jobIndent) {
+            unclear = true;
+            if (current)
+                current.unclear = true;
+            continue;
+        }
+        if (line.indent === jobIndent) {
+            const kv = splitKeyLine(line.text);
+            childIndent = null;
+            inStrategy = false;
+            afterName = false;
+            if (kv === null) {
+                unclear = true;
+                current = null;
+                continue;
+            }
+            current = { key: kv.key, name: null, matrix: false, expression: false, reusable: false, unclear: kv.rest !== "" };
+            jobs.push(current);
+            continue;
+        }
+        if (current === null)
+            continue;
+        childIndent ??= line.indent;
+        if (line.indent < childIndent) {
+            current.unclear = true;
+            continue;
+        }
+        if (line.indent === childIndent) {
+            inStrategy = false;
+            afterName = false;
+            const kv = splitKeyLine(line.text);
+            if (kv === null) {
+                current.unclear = true;
+                continue;
+            }
+            if (kv.key === "name") {
+                const parsed = parseInlineScalar(kv.rest);
+                if (parsed.kind === "value") {
+                    current.name = parsed.value;
+                    if (parsed.value.includes("${{"))
+                        current.expression = true;
+                }
+                else {
+                    current.unclear = true;
+                }
+                afterName = true;
+            }
+            else if (kv.key === "strategy") {
+                // An inline strategy (typically `${{ fromJSON(...) }}`) may carry a matrix.
+                if (kv.rest !== "")
+                    current.matrix = true;
+                else
+                    inStrategy = true;
+            }
+            else if (kv.key === "matrix") {
+                current.matrix = true;
+            }
+            else if (kv.key === "uses") {
+                current.reusable = true;
+            }
+            continue;
+        }
+        // Deeper than the job's direct children.
+        if (afterName) {
+            // A plain scalar continued onto the next line: the name read so far is partial.
+            current.unclear = true;
+            afterName = false;
+        }
+        if (inStrategy && splitKeyLine(line.text)?.key === "matrix")
+            current.matrix = true;
+    }
+    return {
+        found: true,
+        unclear,
+        jobs: jobs.map((j) => ({
+            key: j.key,
+            name: j.name,
+            variance: j.unclear
+                ? "unclear"
+                : j.matrix
+                    ? "matrix"
+                    : j.expression
+                        ? "expression"
+                        : j.reusable
+                            ? "reusable_workflow"
+                            : null,
+        })),
+    };
+}
+/**
+ * A GitHub Actions workflow's jobs. The check-run name a job reports is its
+ * `name:` when present, else its key — exact only when `variance` is null.
+ */
+export function scanWorkflowJobs(text) {
+    const scan = scanJobsBlock(text);
+    return {
+        ...scan,
+        jobs: scan.jobs.map((j) => j.variance === null && (j.name ?? j.key).trim() === "" ? { ...j, variance: "unclear" } : j),
+    };
+}
+/** A CircleCI config's job keys. A CircleCI job has no reported-name override. */
+export function scanCircleCiJobs(text) {
+    const scan = scanJobsBlock(text);
+    return { ...scan, jobs: scan.jobs.map((j) => ({ ...j, name: null })) };
+}
+/** The exact reported check name for a workflow job, or null when it may vary. */
+export function workflowJobReportedName(job) {
+    if (job.variance !== null)
+        return null;
+    const name = (job.name ?? job.key).trim();
+    return name === "" ? null : name;
+}
+/** The status CircleCI reports for a job — a LOOKUP name, never proposed unless reported. */
+export function circleCiStatusName(jobKey) {
+    return `ci/circleci: ${jobKey.trim()}`;
+}
+const MAKE_GATE_TARGETS = ["test", "check", "lint"];
+/**
+ * Makefile targets named exactly `test`, `check`, or `lint`, in that fixed
+ * order. A rule line (`test:` or `test::`) counts; a variable assignment
+ * (`test := ...`, `test ::= ...`) does not.
+ */
+export function scanMakefileTargets(text) {
+    const found = new Set();
+    for (const line of text.split(/\r?\n/)) {
+        const m = /^(test|check|lint)\s*:(?!=|:=)/.exec(line);
+        if (m)
+            found.add(m[1]);
+    }
+    return MAKE_GATE_TARGETS.filter((t) => found.has(t));
+}
+/** True when an INI/TOML file has a section header line exactly equal to `header`. */
+export function hasIniSection(text, header) {
+    return text.split(/\r?\n/).some((line) => line.replace(/\s+[#;].*$/, "").trim() === header);
+}
+/** Argv for a package.json script under a package manager. Never a shell string. */
+export function packageScriptArgv(pm, script) {
+    if (pm === "yarn")
+        return ["yarn", script];
+    if (pm === "npm" && script === "test")
+        return ["npm", "test"];
+    return [pm, "run", script];
+}
+/** True when a package.json script value is a usable command (not empty, not the npm placeholder). */
+export function isUsablePackageScript(value) {
+    if (typeof value !== "string")
+        return false;
+    const trimmed = value.trim();
+    return trimmed !== "" && trimmed !== NPM_PLACEHOLDER_TEST_SCRIPT;
+}
+/** True when `name` is a valid local command name. */
+export function isGateCommandName(name) {
+    return GATE_COMMAND_NAME_PATTERN.test(name);
+}
+// ---------------------------------------------------------------------------
+// Rendering and proposal helpers
+// ---------------------------------------------------------------------------
+const VARIANCE_TEXT = {
+    matrix: "matrix",
+    expression: "expression",
+    reusable_workflow: "reusable workflow",
+    unclear: "unclear structure",
+};
+/**
+ * A short, renderer-neutral one-line description, e.g.
+ * `.github/workflows/ci.yml job "unit-tests" (name may vary: matrix)`.
+ */
+export function describeEvidence(e) {
+    let text = e.detail ? `${e.source} ${e.detail}` : e.source;
+    if (e.nameMayVary && !text.includes("name may vary"))
+        text += " (name may vary)";
+    return text;
+}
+/** The proposal kind implied by a selection; `none` when nothing is selected. */
+export function deriveProposalKind(providerChecks, localCommandIds) {
+    if (providerChecks.length > 0 && localCommandIds.length > 0)
+        return "mixed";
+    if (providerChecks.length > 0)
+        return "provider";
+    if (localCommandIds.length > 0)
+        return "local";
+    return "none";
+}
+const PROVIDER_OUTCOMES = new Set(["reported", "unseen", "evidence_unavailable"]);
+/**
+ * Classify a lookup response into a history state. A successful answer with no
+ * reported names is `available`; only a failed lookup or a stated
+ * `unavailableReason` is `unavailable`. Malformed responses read as unavailable.
+ */
+export function historyStateFrom(response) {
+    if (typeof response !== "object" || response === null)
+        return { status: "unavailable" };
+    const r = response;
+    if (r.ok !== true)
+        return { status: "unavailable" };
+    if (r.unavailableReason !== null)
+        return { status: "unavailable" };
+    if (typeof r.outcomes !== "object" || r.outcomes === null)
+        return { status: "unavailable" };
+    return { status: "available", complete: r.complete === true };
+}
+/** The outcome the lookup reported for exactly `name`, or null when it said nothing valid. */
+function outcomeFor(outcomes, name) {
+    if (typeof outcomes !== "object" || outcomes === null)
+        return null;
+    // Own-property only, so names like `constructor` never read the prototype.
+    if (!Object.prototype.hasOwnProperty.call(outcomes, name))
+        return null;
+    const value = outcomes[name];
+    return typeof value === "string" && PROVIDER_OUTCOMES.has(value) ? value : null;
+}
+// ---------------------------------------------------------------------------
+// Collection
+// ---------------------------------------------------------------------------
+function byCodeUnit(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+/** A directory entry the collector is willing to join onto a path. */
+function isPlainEntry(name) {
+    return name !== "" && name !== "." && name !== ".." && !name.includes("/") && !name.includes("\\") && !name.includes("\0");
+}
+/** Read through the seam, re-applying the size cap so an injected fs cannot exceed it. */
+async function readBounded(fsSeam, relPath) {
+    const text = await fsSeam.readText(relPath);
+    if (text === null || Buffer.byteLength(text, "utf8") > MAX_DISCOVERY_FILE_BYTES)
+        return null;
+    return text;
+}
+/** Lookup names in first-seen order, each with the evidence that produced it. */
+class LookupNames {
+    order = [];
+    evidence = new Map();
+    add(name, e) {
+        const existing = this.evidence.get(name);
+        if (existing) {
+            existing.push(e);
+            return;
+        }
+        this.order.push(name);
+        this.evidence.set(name, [e]);
+    }
+    entries() {
+        return this.order.map((name) => ({ name, evidence: this.evidence.get(name) ?? [] }));
+    }
+}
+function jobDetail(job) {
+    let detail = `job "${job.key}"`;
+    if (job.name !== null && job.name !== job.key)
+        detail += ` named "${job.name}"`;
+    if (job.variance !== null)
+        detail += ` (name may vary: ${VARIANCE_TEXT[job.variance]})`;
+    return detail;
+}
+async function collectWorkflows(fsSeam, evidence, lookups) {
+    const entries = await fsSeam.listDir(WORKFLOWS_DIR);
+    if (entries === null)
+        return;
+    const files = entries
+        .filter((n) => isPlainEntry(n) && /\.ya?ml$/.test(n))
+        .sort(byCodeUnit)
+        .slice(0, MAX_WORKFLOW_FILES);
+    for (const file of files) {
+        const source = `${WORKFLOWS_DIR}/${file}`;
+        const text = await readBounded(fsSeam, source);
+        if (text === null)
+            continue;
+        const scan = scanWorkflowJobs(text);
+        if (scan.jobs.length === 0) {
+            // A workflow file whose jobs could not be read is still evidence of provider CI.
+            evidence.push({
+                kind: "github_workflow_job",
+                source,
+                detail: `jobs could not be read (name may vary: ${VARIANCE_TEXT.unclear})`,
+                nameMayVary: true,
+            });
+            continue;
+        }
+        for (const job of scan.jobs) {
+            const reported = workflowJobReportedName(job);
+            const e = {
+                kind: "github_workflow_job",
+                source,
+                detail: jobDetail(job),
+                nameMayVary: reported === null,
+            };
+            evidence.push(e);
+            if (reported !== null)
+                lookups.add(reported, e);
+        }
+    }
+}
+async function collectCircleCi(fsSeam, evidence, lookups) {
+    const text = await readBounded(fsSeam, CIRCLECI_CONFIG);
+    if (text === null)
+        return;
+    const scan = scanCircleCiJobs(text);
+    if (scan.jobs.length === 0) {
+        evidence.push({
+            kind: "circleci_job",
+            source: CIRCLECI_CONFIG,
+            detail: `jobs could not be read (name may vary: ${VARIANCE_TEXT.unclear})`,
+            nameMayVary: true,
+        });
+        return;
+    }
+    for (const job of scan.jobs) {
+        const exact = job.variance === null && job.key.trim() !== "";
+        const e = {
+            kind: "circleci_job",
+            source: CIRCLECI_CONFIG,
+            detail: exact
+                ? `job "${job.key}" (reports as "${circleCiStatusName(job.key)}")`
+                : `job "${job.key}" (name may vary: ${VARIANCE_TEXT[job.variance ?? "unclear"]})`,
+            nameMayVary: !exact,
+        };
+        evidence.push(e);
+        if (exact)
+            lookups.add(circleCiStatusName(job.key), e);
+    }
+}
+async function collectOtherProviders(fsSeam, evidence, lookups) {
+    if ((await readBounded(fsSeam, "Jenkinsfile")) !== null) {
+        const e = { kind: "jenkinsfile", source: "Jenkinsfile", detail: null, nameMayVary: false };
+        evidence.push(e);
+        for (const name of JENKINS_LOOKUP_NAMES)
+            lookups.add(name, e);
+    }
+    if ((await fsSeam.listDir(".buildkite")) !== null) {
+        // The pipeline slug is not in the repository, so there is no name to look up.
+        evidence.push({ kind: "buildkite", source: ".buildkite", detail: "pipeline slug unknown", nameMayVary: false });
+    }
+}
+/** Hooks are evidence only: their bodies are shell and are never run or parsed. */
+async function collectHooks(fsSeam, evidence) {
+    const husky = await fsSeam.listDir(".husky");
+    if (husky !== null) {
+        const present = new Set(husky);
+        for (const hook of GIT_CLIENT_HOOK_NAMES) {
+            if (!present.has(hook))
+                continue;
+            const source = `.husky/${hook}`;
+            if ((await readBounded(fsSeam, source)) === null)
+                continue;
+            evidence.push({ kind: "husky_hook", source, detail: "hook (evidence only)", nameMayVary: false });
+        }
+    }
+    if ((await readBounded(fsSeam, ".pre-commit-config.yaml")) !== null) {
+        evidence.push({
+            kind: "pre_commit_config",
+            source: ".pre-commit-config.yaml",
+            detail: "hook configuration (evidence only)",
+            nameMayVary: false,
+        });
+    }
+    // In a linked worktree `.git` is a FILE pointing elsewhere; only a real directory is inspected.
+    if ((await fsSeam.listDir(".git")) !== null && (await readBounded(fsSeam, ".git/hooks/pre-push")) !== null) {
+        evidence.push({
+            kind: "git_pre_push_hook",
+            source: ".git/hooks/pre-push",
+            detail: "hook (evidence only)",
+            nameMayVary: false,
+        });
+    }
+}
+function localCandidate(id, name, argv, confidence, evidence) {
+    return { id, name, argv, timeoutSeconds: LOCAL_COMMAND_TIMEOUT_SECONDS, confidence, evidence };
+}
+const PACKAGE_GATE_SCRIPTS = ["test", "lint", "check"];
+/**
+ * Resolve the package manager from lockfiles. More than one manager's lockfile
+ * is ambiguous — running the wrong one could pass a gate the real toolchain
+ * fails — so it resolves to null and the scripts become evidence only.
+ */
+async function detectPackageManager(fsSeam) {
+    const managers = [];
+    if (await fsSeam.exists("pnpm-lock.yaml"))
+        managers.push("pnpm");
+    if (await fsSeam.exists("yarn.lock"))
+        managers.push("yarn");
+    if (await fsSeam.exists("package-lock.json"))
+        managers.push("npm");
+    if (managers.length > 1)
+        return null;
+    return managers[0] ?? "npm";
+}
+async function collectPackageJson(fsSeam, evidence, candidates) {
+    const text = await readBounded(fsSeam, "package.json");
+    if (text === null)
+        return;
+    let scripts;
+    try {
+        const parsed = JSON.parse(text);
+        if (typeof parsed !== "object" || parsed === null)
+            return;
+        const raw = parsed.scripts;
+        if (typeof raw !== "object" || raw === null || Array.isArray(raw))
+            return;
+        scripts = raw;
+    }
+    catch {
+        return; // Unparseable package.json: unsupported, omitted.
+    }
+    const usable = PACKAGE_GATE_SCRIPTS.filter((s) => Object.prototype.hasOwnProperty.call(scripts, s) && isUsablePackageScript(scripts[s]));
+    if (usable.length === 0)
+        return;
+    const pm = await detectPackageManager(fsSeam);
+    for (const script of usable) {
+        if (pm === null) {
+            evidence.push({
+                kind: "package_json_script",
+                source: "package.json",
+                detail: `script "${script}" (omitted: lockfiles name more than one package manager)`,
+                nameMayVary: false,
+            });
+            continue;
+        }
+        const e = { kind: "package_json_script", source: "package.json", detail: `script "${script}"`, nameMayVary: false };
+        evidence.push(e);
+        candidates.push(localCandidate(`${pm}:${script}`, `${pm}-${script}`, packageScriptArgv(pm, script), script === "test" ? "high" : "medium", [e]));
+    }
+}
+async function collectMakefile(fsSeam, evidence, candidates) {
+    const text = await readBounded(fsSeam, "Makefile");
+    if (text === null)
+        return;
+    for (const target of scanMakefileTargets(text)) {
+        const e = { kind: "makefile_target", source: "Makefile", detail: `target "${target}"`, nameMayVary: false };
+        evidence.push(e);
+        candidates.push(localCandidate(`make:${target}`, `make-${target}`, ["make", target], "medium", [e]));
+    }
+}
+async function collectPython(fsSeam, evidence, candidates) {
+    const pytestEvidence = [];
+    const pyEvidence = (source, detail) => ({
+        kind: "python_test_config",
+        source,
+        detail,
+        nameMayVary: false,
+    });
+    const pyproject = await readBounded(fsSeam, "pyproject.toml");
+    if (pyproject !== null && hasIniSection(pyproject, "[tool.pytest.ini_options]")) {
+        pytestEvidence.push(pyEvidence("pyproject.toml", "[tool.pytest.ini_options]"));
+    }
+    if ((await readBounded(fsSeam, "pytest.ini")) !== null) {
+        pytestEvidence.push(pyEvidence("pytest.ini", "pytest configuration"));
+    }
+    const toxIni = await readBounded(fsSeam, "tox.ini");
+    const setupCfg = await readBounded(fsSeam, "setup.cfg");
+    for (const [source, text] of [["tox.ini", toxIni], ["setup.cfg", setupCfg]]) {
+        if (text === null)
+            continue;
+        for (const header of ["[pytest]", "[tool:pytest]"]) {
+            if (hasIniSection(text, header))
+                pytestEvidence.push(pyEvidence(source, header));
+        }
+    }
+    evidence.push(...pytestEvidence);
+    if (pytestEvidence.length > 0) {
+        candidates.push(localCandidate("python:pytest", "pytest", ["python", "-m", "pytest"], "high", pytestEvidence));
+    }
+    if (toxIni !== null && hasIniSection(toxIni, "[tox]")) {
+        const e = pyEvidence("tox.ini", "[tox]");
+        evidence.push(e);
+        candidates.push(localCandidate("tox", "tox", ["tox"], "medium", [e]));
+    }
+    if ((await readBounded(fsSeam, "noxfile.py")) !== null) {
+        const e = pyEvidence("noxfile.py", "nox sessions");
+        evidence.push(e);
+        candidates.push(localCandidate("nox", "nox", ["nox"], "medium", [e]));
+    }
+}
+/** Ask history about `names`; never throws, and never calls the lookup with nothing. */
+async function queryHistory(lookupHistory, names) {
+    if (names.length === 0)
+        return { state: { status: "not_queried" }, outcomes: null };
+    let response;
+    try {
+        response = await lookupHistory([...names]);
+    }
+    catch {
+        return { state: { status: "unavailable" }, outcomes: null };
+    }
+    const state = historyStateFrom(response);
+    const outcomes = state.status === "available" ? response.outcomes : null;
+    return { state, outcomes };
+}
+/**
+ * Collect a gate proposal from the working tree and provider history.
+ *
+ * The default selection is the reported provider checks; when there are none,
+ * the HIGH-confidence local candidates. When there is nothing at all the
+ * proposal says so explicitly (`kind: "none"`, `noCandidates: true`) rather
+ * than presenting an empty provider list as a gate.
+ */
+export async function discoverGate(input) {
+    const { fs: fsSeam, lookupHistory } = input;
+    const evidence = [];
+    const localCandidates = [];
+    const lookups = new LookupNames();
+    await collectWorkflows(fsSeam, evidence, lookups);
+    await collectCircleCi(fsSeam, evidence, lookups);
+    await collectOtherProviders(fsSeam, evidence, lookups);
+    await collectHooks(fsSeam, evidence);
+    await collectPackageJson(fsSeam, evidence, localCandidates);
+    await collectMakefile(fsSeam, evidence, localCandidates);
+    await collectPython(fsSeam, evidence, localCandidates);
+    const all = lookups.entries();
+    const queried = all.slice(0, MAX_LOOKUP_NAMES);
+    const overflow = all.slice(MAX_LOOKUP_NAMES);
+    const { state: history, outcomes } = await queryHistory(lookupHistory, queried.map((e) => e.name));
+    const providerCandidates = [];
+    const unreportedProviderNames = [];
+    for (const entry of queried) {
+        // When history is not `available`, no outcome is trusted, even one the response carried.
+        const outcome = history.status === "available" ? outcomeFor(outcomes, entry.name) : null;
+        if (outcome === "reported") {
+            providerCandidates.push({ name: entry.name, outcome, confidence: "high", evidence: entry.evidence });
+        }
+        else {
+            unreportedProviderNames.push({
+                name: entry.name,
+                outcome,
+                confidence: outcome === "unseen" ? "low" : "medium",
+                evidence: entry.evidence,
+            });
+        }
+    }
+    // Names past the lookup cap were never asked about: unknown, never proposed.
+    for (const entry of overflow) {
+        unreportedProviderNames.push({ name: entry.name, outcome: null, confidence: "medium", evidence: entry.evidence });
+    }
+    const validLocal = localCandidates.filter((c) => isGateCommandName(c.name));
+    const providerChecks = providerCandidates.map((c) => c.name);
+    const localCommandIds = providerChecks.length > 0 ? [] : validLocal.filter((c) => c.confidence === "high").map((c) => c.id);
+    return {
+        providerCandidates,
+        unreportedProviderNames,
+        localCandidates: validLocal,
+        evidence,
+        history,
+        proposed: { kind: deriveProposalKind(providerChecks, localCommandIds), providerChecks, localCommandIds },
+        noCandidates: providerCandidates.length === 0 && validLocal.length === 0,
+    };
+}