@bridge_gpt/mcp-server 0.2.69 → 0.2.70

package/build/init.js

@@ -9,12 +9,14 @@
  * import `runInit` back from `index.ts`). This module has no top-level side
  * effects and depends only on leaf modules.
  */
-import { writeFile, mkdir, readFile, stat } from "fs/promises";
+import { writeFile, mkdir, readFile, stat, lstat, access, realpath } from "fs/promises";
 import { execFile } from "child_process";
 import path from "path";
 import os from "os";
 import { buildPackagedAssetCatalog } from "./generated-assets-catalog.js";
 import { recordProvisionedAssets } from "./generated-assets-inventory.js";
+import { inspectAssetPath } from "./generated-assets-paths.js";
+import { LEGACY_DOC_DESTINATIONS } from "./docs.generated.js";
 import { VERSION, LAUNCHER_ARGS } from "./version.generated.js";
 import { BRIDGE_CONFIG_TEAMMATE_NOTICE_LINES, validateBridgeConfigRepoNameRepresentability, validateRepoName, resolveRepoNameForProjectRoot, } from "./bridge-config.js";
 import { ensureGitignored as ensureGitignoredShared } from "./git-ignore-utils.js";
@@ -888,6 +890,40 @@ export async function runInit(cwd, options = {}) {
     }
     if (scaffoldFailed)
         throw new Error("Some packaged workflow assets could not be scaffolded.");
+    // ---- Phase 5b: Advisory probe for old procedure copies (BAPI-1470) ----
+    // The six machine-read procedures moved from docs/install/ to
+    // .bridge/procedures/. Report old copies that are still there. This only
+    // inspects metadata: it never reads, rewrites, or deletes an old file, and no
+    // outcome changes `ok` or the exit behavior.
+    const legacyProcedureCopies = [];
+    const legacyProcedureProbeWarnings = [];
+    const inspectionFs = options.assetInspectionFs ?? { lstat, access };
+    const probeRoot = await realpath(cwd).catch(() => path.resolve(cwd));
+    for (const relPath of Object.values(LEGACY_DOC_DESTINATIONS)) {
+        try {
+            const finding = await inspectAssetPath(probeRoot, relPath, inspectionFs);
+            if (finding.status === "present")
+                legacyProcedureCopies.push(relPath);
+            else if (finding.status !== "missing") {
+                legacyProcedureProbeWarnings.push({ relPath, status: finding.status, reason: finding.reason.slice(0, 64) });
+            }
+        }
+        catch {
+            legacyProcedureProbeWarnings.push({ relPath, status: "indeterminate", reason: "probe-failed" });
+        }
+    }
+    if (legacyProcedureCopies.length > 0) {
+        say([
+            "Old procedure copies found:",
+            ...legacyProcedureCopies.map((p) => `  ${p}`),
+            "These are old fallback copies. Bridge now reads `.bridge/procedures/` first. " +
+                "You can delete the listed copies once the new `.bridge/procedures/` files are committed.",
+        ].join("\n"));
+    }
+    for (const w of legacyProcedureProbeWarnings) {
+        warn(`  Could not confirm whether the old procedure copy ${w.relPath} exists (${w.status}: ${w.reason}). ` +
+            "Check that path by hand.");
+    }
     // ---- Phase 6: Scaffold custom pipeline directories ----
     // BAPI-708: shared with `resolveInitScaffoldAssets`, so a `BAPI_PIPELINES_DIR`
     // override moves the scaffold and the commit-safe manifest in lockstep.
@@ -1086,5 +1122,7 @@ says to serialize structured output.
         targetVersion,
         bridgeConfigCreated,
         ...(bridgeConfigRepoName !== undefined ? { bridgeConfigRepoName } : {}),
+        legacyProcedureCopies,
+        legacyProcedureProbeWarnings,
     };
 }

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

@@ -727,6 +727,9 @@ export async function resolveConductorGate(io, access, flags, gateDeps, options)
             plan: { current, desired, write: confirmRequestFor(desired, current.revision), removals, origin: "flags" },
         };
     }
+    if (options.ensureProviderCheck !== undefined) {
+        return ensureProviderCheckPlan(io, access, current, currentDesired, options.ensureProviderCheck, gateDeps, options);
+    }
     if (currentDesired !== null) {
         io.log(current.source === "legacy"
             ? "  Using the confirmed gate from this repository's existing --required-check setup."
@@ -764,6 +767,73 @@ export async function resolveConductorGate(io, access, flags, gateDeps, options)
         plan: { current, desired, write: confirmRequestFor(desired, current.revision), removals: [], origin: "interactive" },
     };
 }
+/** BAPI-1461 — `desired` with `check` added as a provider member (kept when present). */
+function withProviderCheck(desired, check) {
+    if (desired.providerChecks.includes(check))
+        return desired;
+    const providerChecks = [...desired.providerChecks, check];
+    return {
+        ...desired,
+        providerChecks,
+        localCommands: desired.localCommands.map((c) => ({ ...c, argv: [...c.argv] })),
+        kind: kindForMembers(providerChecks, desired.localCommands),
+    };
+}
+/**
+ * BAPI-1461 — the converging setup's gate decision when no gate flag was given.
+ *
+ *  - A confirmed gate that already requires the check: used unchanged, no write.
+ *  - A confirmed provider or mixed gate without it: the check is ADDED (every
+ *    member kept), shown against the stored gate, and stored later under the
+ *    combined gate-and-defaults consent.
+ *  - A confirmed local-only or `none` gate: changing its kind is a policy change,
+ *    so the comparison is shown and the owner is asked here. A decline keeps the
+ *    stored gate and is reported as an outstanding blocking fix.
+ *  - No confirmed gate: the discovery proposal plus the check, shown for the
+ *    combined consent. Nothing is stored here.
+ */
+async function ensureProviderCheckPlan(io, access, current, currentDesired, check, gateDeps, options) {
+    if (currentDesired !== null) {
+        if (currentDesired.providerChecks.includes(check)) {
+            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 desired = withProviderCheck(currentDesired, check);
+        renderGateComparison(io, current, desired, []);
+        if (currentDesired.kind === "local" || currentDesired.kind === "none") {
+            if (options.dryRun) {
+                io.log("  Dry run — a real run asks before adding the CI check to this gate.");
+            }
+            else {
+                const ok = await ask(io, "Add the CI workflow check to this repository gate? [y/N]: ");
+                if (!ok) {
+                    io.log("  Kept the stored gate unchanged; the CI check is listed as a step left.");
+                    return {
+                        kind: "plan",
+                        plan: { current, desired: currentDesired, write: null, removals: [], origin: "stored" },
+                        ensureDeclined: true,
+                    };
+                }
+            }
+        }
+        return {
+            kind: "plan",
+            plan: { current, desired, write: confirmRequestFor(desired, current.revision), removals: [], origin: "stored" },
+        };
+    }
+    const proposal = await runGateDiscovery(io, access, gateDeps);
+    renderGateProposal(io, proposal);
+    const desired = withProviderCheck(desiredFromProposalSelection(proposal, proposal.proposed.providerChecks, proposal.proposed.localCommandIds), check);
+    renderGateComparison(io, current, desired, []);
+    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.",
@@ -783,6 +853,14 @@ const GATE_WRITE_REFUSAL_TEXT = Object.freeze({
 export async function storeConductorGate(io, access, plan) {
     if (plan.write === null)
         return plan.current;
+    // BAPI-1461: a stored gate that already equals the desired one is never
+    // rewritten, whatever the caller planned.
+    if (plan.current.source === "stored" &&
+        plan.current.confirmed &&
+        plan.current.profile !== null &&
+        gateMatchesStored(plan.desired, desiredFromStored(plan.current.profile))) {
+        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]}`);

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

@@ -0,0 +1,413 @@
+/**
+ * The converging setup model for `install conductor` (BAPI-1461).
+ *
+ * Setup is no longer a fixed list of phases. It is:
+ *
+ *   check everything (read-only) → fix only what is missing, in order →
+ *   check again → print one verdict.
+ *
+ * This module holds the parts of that loop that do not touch the terminal: the
+ * readiness items, the projection of evidence onto them, the dependency-aware
+ * fix planner, the managed setup pull request and index reads, and the final
+ * rendering. Every effect is an injected seam; nothing here prompts or writes.
+ *
+ * Items reuse the shared readiness catalog's ids and labels, so each item has
+ * one name everywhere it appears. The server's own readiness prerequisites are
+ * the base list; local evidence (sign-ins, the merge token, the setup pull
+ * request, indexing) refines the item it belongs to instead of adding a second
+ * row for the same fact. An unmet blocking item is counted once.
+ */
+import { READINESS_PREREQUISITE_BY_ID, READINESS_PREREQUISITE_CATALOG, } from "./readiness-prerequisites.generated.js";
+import { READINESS_PREREQUISITE_FIXES } from "./printed-remedy-commands.js";
+import { githubSignInRemedy } from "./github-sign-in.js";
+import { EPIC_CI_WORKFLOW_INSTALL_BRANCH, EPIC_CI_WORKFLOW_UPGRADE_BRANCH, } from "./epic-ci-workflow-install.js";
+import { MCP_PACKAGE_NAME } from "./mcp-identity.js";
+/** The catalog ids setup reports, named once. */
+export const SETUP_ITEM_IDS = Object.freeze({
+    claudeLogin: "conductor.claude-login",
+    githubSignIn: "conductor.gh-cli",
+    mergeCredential: "conductor.merge-credential-capability",
+    testCommand: "server.test-command",
+    workflows: "server.indexed-workflows",
+    escalation: "server.unattended-notify-default",
+    supervisorSetup: "server.supervisor-setup",
+    supervisorConfig: "server.supervisor-config",
+    requiredChecks: "server.supervisor-required-checks",
+    repositoryIdentity: "install.identity",
+    serverConnectivity: "install.connectivity",
+});
+/** The catalog label for an id, falling back to the id itself. */
+export function catalogLabel(id) {
+    return READINESS_PREREQUISITE_BY_ID.get(id)?.label ?? id;
+}
+/** The catalog's position for an id; unknown ids sort last, in arrival order. */
+function catalogIndex(id) {
+    const index = READINESS_PREREQUISITE_CATALOG.findIndex((d) => d.id === id);
+    return index === -1 ? Number.MAX_SAFE_INTEGER : index;
+}
+/** The printed setup command, used in fixes that point back at setup. */
+export const PRINTED_SETUP_COMMAND = `npx -y ${MCP_PACKAGE_NAME} install conductor`;
+/**
+ * The fix for the escalation channel. There is no verification route on the
+ * server, so this is a step the person carries out — setup never asks for or
+ * sends an email address.
+ */
+export const ESCALATION_EMAIL_REMEDY = "verify the escalation email: declare notify.webhook_url in your run policy, or ask your Bridge " +
+    "account administrator to confirm that the account email address receives mail, then re-run setup";
+// ---------------------------------------------------------------------------
+// Projection
+// ---------------------------------------------------------------------------
+function fromServerPrerequisite(p, isProduction) {
+    if (p.check_status === "met" || p.check_status === "not_applicable") {
+        return { id: p.id, label: p.label, state: "met", blocking: p.impact === "blocking", remedy: null };
+    }
+    const blocking = p.impact === "blocking";
+    // On production, a Bridge-hosted (self_host) fact is never the customer's to
+    // fix, so it reads as "could not verify — retry", never as server repair advice.
+    if (p.scope === "self_host" && isProduction) {
+        return {
+            id: p.id,
+            label: p.label,
+            state: "unknown",
+            blocking,
+            remedy: READINESS_PREREQUISITE_FIXES.retry,
+        };
+    }
+    return {
+        id: p.id,
+        label: p.label,
+        state: p.check_status === "unknown" ? "unknown" : "needs_action",
+        blocking,
+        remedy: p.fix.length > 0 ? p.fix : READINESS_PREREQUISITE_FIXES.retry,
+    };
+}
+function upsert(items, item) {
+    const at = items.findIndex((i) => i.id === item.id);
+    if (at === -1)
+        items.push(item);
+    else
+        items[at] = item;
+}
+function local(id, state, blocking, remedy) {
+    return { id, label: catalogLabel(id), state, blocking, remedy: state === "met" ? null : remedy };
+}
+/**
+ * Project one assessment pass onto the readiness items, in catalog order.
+ *
+ * Pure. It never derives readiness from a local write or an exit code: a
+ * stored command is met only when the read-back saw it, a workflow only when
+ * the installer found it identical, and indexing only when the index reached
+ * the merge commit.
+ */
+export function projectSetupItems(evidence) {
+    const items = [];
+    const readiness = evidence.readiness;
+    const isProduction = readiness?.is_production === true;
+    if (readiness === null) {
+        items.push(local(SETUP_ITEM_IDS.serverConnectivity, "unknown", true, "the Bridge API readiness report could not be read; check the URL and your network, then re-run setup"));
+    }
+    else if (readiness.prerequisites !== undefined) {
+        for (const p of readiness.prerequisites) {
+            const item = fromServerPrerequisite(p, isProduction);
+            if (item !== null)
+                items.push(item);
+        }
+    }
+    else {
+        // An older server without the shared prerequisites: the supervisor facts it
+        // has always reported stand in for those rows.
+        items.push(local(SETUP_ITEM_IDS.supervisorSetup, readiness.supervisor.setup_present ? "met" : "needs_action", true, `re-run setup and accept storing the repository gate and the safe defaults`), local(SETUP_ITEM_IDS.supervisorConfig, readiness.supervisor.config_present ? "met" : "needs_action", true, `re-run setup and accept storing the repository gate and the safe defaults`));
+    }
+    // --- Sign-ins (read-only, checked first) --------------------------------
+    if (evidence.claudeLoggedIn !== null) {
+        upsert(items, local(SETUP_ITEM_IDS.claudeLogin, evidence.claudeLoggedIn ? "met" : "needs_action", false, "run `claude login`"));
+    }
+    upsert(items, local(SETUP_ITEM_IDS.githubSignIn, evidence.githubSignIn === "signed_in" ? "met" : evidence.githubSignIn === "unavailable" ? "unknown" : "needs_action", true, githubSignInRemedy(evidence.githubSignIn)));
+    // --- Repository identity ------------------------------------------------
+    if (evidence.repositoryIdentity !== "resolved") {
+        upsert(items, local(SETUP_ITEM_IDS.repositoryIdentity, "needs_action", true, evidence.repositoryIdentity === "conflict"
+            ? "this checkout's github.com remote names a different repository than Bridge does; run setup from the matching checkout"
+            : "run setup from a checkout whose `origin` remote is the github.com repository"));
+    }
+    // --- Test command (the stored value, read back) --------------------------
+    if (evidence.testCommand.state !== "stored") {
+        const existing = items.find((i) => i.id === SETUP_ITEM_IDS.testCommand);
+        upsert(items, local(SETUP_ITEM_IDS.testCommand, evidence.testCommand.state === "missing" ? "needs_action" : "unknown", true, evidence.testCommand.state === "missing"
+            ? "save a test command: re-run setup and give the command that runs your tests"
+            : existing?.remedy ?? READINESS_PREREQUISITE_FIXES.retry));
+    }
+    else {
+        const existing = items.find((i) => i.id === SETUP_ITEM_IDS.testCommand);
+        if (existing === undefined)
+            upsert(items, local(SETUP_ITEM_IDS.testCommand, "met", true, null));
+    }
+    // --- Workflow, setup pull request, and indexing --------------------------
+    const workflowItem = projectWorkflowItem(evidence, items.find((i) => i.id === SETUP_ITEM_IDS.workflows));
+    if (workflowItem !== null)
+        upsert(items, workflowItem);
+    // --- The gate change the owner declined ---------------------------------
+    if (evidence.gateChangeDeclined) {
+        upsert(items, local(SETUP_ITEM_IDS.requiredChecks, "needs_action", true, "add the CI workflow check to the repository gate: re-run setup and accept the gate change"));
+    }
+    // --- Merge credential ----------------------------------------------------
+    const merge = projectMergeCredential(evidence.mergeCredential);
+    if (merge !== null)
+        upsert(items, merge);
+    // --- Escalation channel: a fix the person carries out --------------------
+    const escalation = items.find((i) => i.id === SETUP_ITEM_IDS.escalation);
+    if (escalation !== undefined && escalation.state === "needs_action") {
+        upsert(items, { ...escalation, remedy: ESCALATION_EMAIL_REMEDY });
+    }
+    return items
+        .map((item, arrival) => ({ item, arrival }))
+        .sort((a, b) => catalogIndex(a.item.id) - catalogIndex(b.item.id) || a.arrival - b.arrival)
+        .map(({ item }) => item);
+}
+function projectWorkflowItem(evidence, server) {
+    const id = SETUP_ITEM_IDS.workflows;
+    const pr = evidence.setupPullRequest;
+    switch (evidence.workflow.state) {
+        case "pr_open":
+            return local(id, "pending", true, `merge the setup PR: ${evidence.workflow.url}`);
+        case "needs_pr":
+            return local(id, "needs_action", true, "open the setup PR: re-run setup and accept the setup pull request");
+        case "blocked":
+            return local(id, "needs_action", true, evidence.workflow.remedy);
+        case "needs_command":
+            return local(id, "needs_action", true, "save a test command first; setup builds the CI workflow from it");
+        case "unknown":
+            return server ?? local(id, "unknown", true, "the CI workflow could not be checked; re-run setup");
+        case "precondition":
+            // The local preflight could not run, but a merged setup PR still proves the
+            // workflow reached the default branch; then only indexing remains.
+            if (server?.state === "met")
+                return server;
+            if (pr.state !== "merged")
+                return local(id, "needs_action", true, evidence.workflow.remedy);
+            break;
+        case "installed":
+            break;
+    }
+    // The workflow is on the default branch. What remains is indexing.
+    if (pr.state === "closed_unmerged") {
+        return local(id, "needs_action", true, `the setup PR was closed without merging (${pr.url}); reopen and merge it, or delete the branch ${pr.branch} and re-run setup`);
+    }
+    switch (evidence.index.state) {
+        case "reached":
+            // The server's fact can need more than this workflow (for example the
+            // review workflow a policy requires), so a local "met" never hides it.
+            return server !== undefined && server.state !== "met" ? server : local(id, "met", true, null);
+        case "behind":
+            return local(id, "needs_action", true, "re-index the repository: re-run setup to queue indexing");
+        case "in_progress":
+            return local(id, "pending", true, "indexing is running; re-run setup when it finishes");
+        case "queued_by_setup":
+            return local(id, "pending", true, "indexing was queued; re-run setup when it finishes");
+        case "unknown":
+            return local(id, "pending", true, "could not confirm the index reached the setup PR; re-run setup later");
+        case "not_applicable":
+            return server ?? local(id, "met", true, null);
+    }
+}
+function projectMergeCredential(state) {
+    const id = SETUP_ITEM_IDS.mergeCredential;
+    switch (state.state) {
+        case "not_applicable":
+            return null;
+        case "configured":
+            return local(id, "met", true, null);
+        case "missing":
+            return local(id, "needs_action", true, "store a GitHub merge token: re-run setup and accept storing it, or set GITHUB_MERGE_TOKEN");
+        case "env_invalid":
+            return local(id, "needs_action", true, `${state.sourceKey} is set but is not a usable token; fix it or unset it`);
+        case "stored_rejected":
+            return local(id, "needs_action", true, "the stored merge token was rejected by GitHub; re-run setup to replace it");
+        case "machine_missing":
+            return local(id, "needs_action", true, "set BAPI_MACHINE_MERGE_TOKEN in the environment the executor starts from");
+        case "unknown":
+            return local(id, "unknown", true, "the merge token could not be checked right now; re-run setup later");
+    }
+}
+/**
+ * Pick the permitted fixes for the unmet items, in the order they must run.
+ *
+ * Pure. Dependencies are explicit:
+ *  - a missing stored command blocks the workflow PR (it is built from it);
+ *  - a GitHub sign-in that is not ready blocks GitHub-dependent fixes (the
+ *    setup PR), never the Bridge or local ones;
+ *  - an unresolved repository identity blocks the stored merge token.
+ * A fix that is skipped or declined leaves its item outstanding; it never
+ * undoes an independent fix that already succeeded.
+ */
+export function planSetupFixes(evidence, context) {
+    const fixes = [];
+    const githubReady = evidence.githubSignIn === "signed_in";
+    if (evidence.testCommand.state === "missing")
+        fixes.push("save_test_command");
+    const commandAvailable = evidence.testCommand.state === "stored" || fixes.includes("save_test_command");
+    if (githubReady &&
+        commandAvailable &&
+        (evidence.workflow.state === "needs_pr" || evidence.workflow.state === "needs_command")) {
+        fixes.push("setup_pr");
+    }
+    if (context.gateOrDefaultsNeedWrite)
+        fixes.push("gate_and_defaults");
+    if (evidence.repositoryIdentity === "resolved" &&
+        (evidence.mergeCredential.state === "missing" || evidence.mergeCredential.state === "stored_rejected")) {
+        fixes.push("merge_token");
+    }
+    if (evidence.index.state === "behind")
+        fixes.push("reindex");
+    return fixes;
+}
+const SHA_RE = /^[0-9a-f]{40}$/;
+/**
+ * Read the managed setup pull request's state through `gh`. Read-only; any
+ * unreadable answer is `unknown`, never `none`. An open PR wins; otherwise the
+ * most recently merged one; otherwise a closed, unmerged one.
+ */
+export async function readSetupPullRequest(runGh, repository) {
+    const rows = [];
+    for (const branch of [EPIC_CI_WORKFLOW_INSTALL_BRANCH, EPIC_CI_WORKFLOW_UPGRADE_BRANCH]) {
+        let result;
+        try {
+            result = await runGh([
+                "pr", "list", "--repo", repository, "--state", "all", "--head", branch,
+                "--json", "url,state,mergedAt,mergeCommit,headRefName", "--limit", "10",
+            ]);
+        }
+        catch {
+            return { state: "unknown" };
+        }
+        if (result.status !== 0)
+            return { state: "unknown" };
+        let parsed;
+        try {
+            parsed = JSON.parse(result.stdout);
+        }
+        catch {
+            return { state: "unknown" };
+        }
+        if (!Array.isArray(parsed))
+            return { state: "unknown" };
+        rows.push(...parsed);
+    }
+    const str = (v) => (typeof v === "string" && v.length > 0 ? v : null);
+    const open = rows.find((r) => r.state === "OPEN" && str(r.url) && str(r.headRefName));
+    if (open)
+        return { state: "open", url: str(open.url), branch: str(open.headRefName) };
+    const merged = rows
+        .filter((r) => r.state === "MERGED" && str(r.url) && typeof r.mergeCommit?.oid === "string")
+        .sort((a, b) => String(b.mergedAt ?? "").localeCompare(String(a.mergedAt ?? "")));
+    if (merged.length > 0) {
+        const sha = String(merged[0].mergeCommit.oid).toLowerCase();
+        if (!SHA_RE.test(sha))
+            return { state: "unknown" };
+        return { state: "merged", url: str(merged[0].url), mergeCommitSha: sha };
+    }
+    const closed = rows.find((r) => r.state === "CLOSED" && str(r.url) && str(r.headRefName));
+    if (closed)
+        return { state: "closed_unmerged", url: str(closed.url), branch: str(closed.headRefName) };
+    return { state: "none" };
+}
+/**
+ * Whether `indexed` contains `merge`: equal SHAs, or GitHub's compare reports
+ * the indexed commit `identical` to or `ahead` of the merge commit. Any other
+ * answer, or no answer, is `unknown` (never `behind` by guess) except an
+ * explicit `behind`/`diverged`.
+ */
+export async function compareIndexedToMerge(runGh, repository, mergeSha, indexedSha) {
+    if (mergeSha === indexedSha)
+        return "reached";
+    if (!SHA_RE.test(mergeSha) || !SHA_RE.test(indexedSha))
+        return "unknown";
+    let result;
+    try {
+        result = await runGh(["api", `repos/${repository}/compare/${mergeSha}...${indexedSha}`, "--jq", ".status"]);
+    }
+    catch {
+        return "unknown";
+    }
+    if (result.status !== 0)
+        return "unknown";
+    const status = result.stdout.trim();
+    if (status === "identical" || status === "ahead")
+        return "reached";
+    if (status === "behind" || status === "diverged")
+        return "behind";
+    return "unknown";
+}
+/**
+ * Decide the index state for a merged setup PR from one parse-status read.
+ * Never queues anything.
+ */
+export async function assessSetupIndex(pr, readParseStatus, compare) {
+    if (pr.state !== "merged")
+        return { state: "not_applicable" };
+    let status;
+    try {
+        status = await readParseStatus();
+    }
+    catch {
+        return { state: "unknown" };
+    }
+    if (status.status === "queued" || status.status === "in_progress")
+        return { state: "in_progress" };
+    if (status.status === "idle")
+        return { state: "behind" };
+    const indexed = typeof status.indexed_commit_sha === "string" ? status.indexed_commit_sha.toLowerCase() : null;
+    if (indexed === null) {
+        // A failed run left no indexed commit; a succeeded run with an unknown
+        // commit cannot be compared, so it stays pending rather than re-queued.
+        return status.status === "failed" ? { state: "behind" } : { state: "unknown" };
+    }
+    const verdict = await compare(pr.mergeCommitSha, indexed);
+    return verdict === "reached" ? { state: "reached" } : verdict === "behind" ? { state: "behind" } : { state: "unknown" };
+}
+// ---------------------------------------------------------------------------
+// Rendering
+// ---------------------------------------------------------------------------
+const STATE_WORD = Object.freeze({
+    met: "ready",
+    needs_action: "needs action",
+    pending: "pending",
+    unknown: "could not verify",
+});
+/** Blocking items that are not met, each counted once. */
+export function unmetBlockingItems(items) {
+    const seen = new Set();
+    return items.filter((item) => {
+        if (!item.blocking || item.state === "met" || seen.has(item.id))
+            return false;
+        seen.add(item.id);
+        return true;
+    });
+}
+/** The verdict line. Ready only when every blocking item is positively met. */
+export function setupVerdictLine(items) {
+    const left = unmetBlockingItems(items).length;
+    return left === 0 ? "Ready for your first epic" : `Not ready: ${left} step${left === 1 ? "" : "s"} left`;
+}
+/** Render the assessment: a status list, then one fix per unmet blocking item. */
+export function renderSetupAssessment(items, heading) {
+    const lines = ["", heading];
+    const width = Math.max(...Object.values(STATE_WORD).map((w) => w.length));
+    for (const item of items) {
+        if (!item.blocking && item.state === "met")
+            continue;
+        const word = STATE_WORD[item.state].padEnd(width);
+        lines.push(`  ${word}  ${item.label}${item.blocking ? "" : " (advisory)"}`);
+    }
+    const unmet = unmetBlockingItems(items);
+    if (unmet.length > 0) {
+        lines.push("", "Steps left");
+        unmet.forEach((item, index) => lines.push(`  ${index + 1}. ${item.label}: ${item.remedy ?? READINESS_PREREQUISITE_FIXES.retry}`));
+    }
+    const advisories = items.filter((i) => !i.blocking && i.state !== "met" && i.remedy !== null);
+    if (advisories.length > 0) {
+        lines.push("", "Also worth doing (advisory)");
+        for (const item of advisories)
+            lines.push(`  - ${item.label}: ${item.remedy}`);
+    }
+    return lines;
+}