@bridge_gpt/mcp-server 0.2.66 → 0.2.67

package/build/conductor/bridge-api-client.js

@@ -20,7 +20,7 @@ import { parseContinuationStatusResult, parseContinueParkedChildResult, } from "
 import { resolveDeclaredRunBaseBranch } from "./run-branch.js";
 import { safeEpicLaunchTargetUrl } from "../epic-launch-diagnostic.js";
 import { validateHttpBaseUrl } from "../base-url.js";
-import { isCiResumeRefusalCode } from "./repair-contract.js";
+import { RERUN_CI_CHECK_STATUSES, RERUN_CI_NOT_RUNNABLE_REASONS, RERUN_CI_OUTCOMES, isCiResumeRefusalCode, } from "./repair-contract.js";
 /** Default Bridge API base URL when `BAPI_BASE_URL` is unset. */
 export const CONDUCTOR_DEFAULT_BASE_URL = "https://bridgegpt-api.com";
 /** Default per-request timeout for conductor Bridge API calls. */
@@ -1532,6 +1532,117 @@ export async function dispatchRemediation(access, request, fetchImpl = globalThi
     const parsed = await postRepairRequest(access, `${epicRunApiPath(request.epicRunId)}/tickets/${encodeURIComponent(request.ticketKey)}/dispatch-remediation`, withGuard({ context: request.context }, request.guard), fetchImpl);
     return parseDispatchRemediationResult(parsed);
 }
+// ---------------------------------------------------------------------------
+// BAPI-1388 — `rerun-ci`
+// ---------------------------------------------------------------------------
+/** The synthetic code an old server's missing route is reported under. */
+export const RERUN_CI_ROUTE_UNAVAILABLE_CODE = "RERUN_CI_ROUTE_UNAVAILABLE";
+/** The fixed operator text for a server that has no `rerun-ci` route. */
+export const RERUN_CI_ROUTE_UNAVAILABLE_MESSAGE = "rerun-ci is not available on this server; upgrade the Bridge API server before using it";
+const RERUN_CI_HEAD_RE = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/;
+function parseRerunCiCheck(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new ConductorBridgeApiError("server");
+    }
+    const c = value;
+    const status = c["status"];
+    if (typeof status !== "string" ||
+        !RERUN_CI_CHECK_STATUSES.includes(status)) {
+        throw new ConductorBridgeApiError("server");
+    }
+    const reason = c["reason"];
+    if (reason !== undefined &&
+        reason !== null &&
+        (typeof reason !== "string" ||
+            !RERUN_CI_NOT_RUNNABLE_REASONS.includes(reason))) {
+        throw new ConductorBridgeApiError("server");
+    }
+    const optionalPositive = (field) => {
+        const v = c[field];
+        if (v === undefined || v === null)
+            return null;
+        if (typeof v !== "number" || !Number.isSafeInteger(v) || v <= 0) {
+            throw new ConductorBridgeApiError("server");
+        }
+        return v;
+    };
+    const optionalText = (field) => {
+        const v = c[field];
+        if (v === undefined || v === null)
+            return null;
+        if (typeof v !== "string")
+            throw new ConductorBridgeApiError("server");
+        return v;
+    };
+    return {
+        name: optionalText("name"),
+        workflow_identity: optionalText("workflow_identity"),
+        run_id: optionalPositive("run_id"),
+        status: status,
+        reason: (reason ?? null),
+        job_id: optionalPositive("job_id"),
+    };
+}
+/**
+ * Strictly parse a `rerun-ci` success body. Anything short of the contract — an
+ * unknown outcome or per-check status, a malformed head, a non-list `checks` —
+ * throws, so a malformed answer is never read as a success.
+ */
+export function parseRerunCiResult(parsed) {
+    const p = parseRepairBase(parsed);
+    const outcome = p["outcome"];
+    const checks = p["checks"];
+    const head = p["head_sha"];
+    if (typeof p["ticket_key"] !== "string" ||
+        typeof outcome !== "string" ||
+        !RERUN_CI_OUTCOMES.includes(outcome) ||
+        !Array.isArray(checks) ||
+        (head !== undefined && head !== null && (typeof head !== "string" || !RERUN_CI_HEAD_RE.test(head)))) {
+        throw new ConductorBridgeApiError("server");
+    }
+    return {
+        epic_run_id: p["epic_run_id"],
+        ticket_key: p["ticket_key"],
+        before: parseRepairNullableString(p["before"]),
+        after: parseRepairNullableString(p["after"]),
+        committed: p["committed"],
+        event_recorded: p["event_recorded"],
+        outcome: outcome,
+        head_sha: typeof head === "string" ? head : null,
+        checks: checks.map(parseRerunCiCheck),
+    };
+}
+/**
+ * POST `/jira/epic-runs/runs/{epic_run_id}/tickets/{ticket_key}/rerun-ci` — body
+ * `{repo_name, guard}` and nothing else: no context, check list, or run id, because
+ * the SERVER decides what is re-runnable from its own fresh, head-bound CI read.
+ *
+ * A generic `{"detail":"Not Found"}` 404 or a 405 means the server predates the
+ * route; it is reported under {@link RERUN_CI_ROUTE_UNAVAILABLE_CODE} so no caller
+ * can read it as a refusal of THIS ticket or as a success (following
+ * {@link classifySupervisorBootstrapFailure}). A structured 404 — notably
+ * `TICKET_NOT_IN_RUN` — keeps its own code and stays a refusal.
+ */
+export async function rerunCi(access, request, fetchImpl = globalThis.fetch) {
+    requireNonEmptyString(request.epicRunId);
+    requireNonEmptyString(request.ticketKey);
+    let parsed;
+    try {
+        parsed = await postRepairRequest(access, `${epicRunApiPath(request.epicRunId)}/tickets/${encodeURIComponent(request.ticketKey)}/rerun-ci`, { guard: request.guard }, fetchImpl);
+    }
+    catch (err) {
+        if (err instanceof ConductorBridgeApiError &&
+            !err.errorCode &&
+            (err.status === 404 || err.status === 405)) {
+            throw new ConductorBridgeApiError("http", err.status, {
+                errorCode: RERUN_CI_ROUTE_UNAVAILABLE_CODE,
+                bodyPreview: RERUN_CI_ROUTE_UNAVAILABLE_MESSAGE,
+            });
+        }
+        throw err;
+    }
+    return parseRerunCiResult(parsed);
+}
 /**
  * POST `/jira/epic-runs/runs/{epic_run_id}/merge-child` — body EXACTLY
  * `{repo_name, pr_number}`. The server composes the head, gate, and action key.
@@ -2469,6 +2580,20 @@ function requireBool(o, key) {
         throw readinessShapeError();
     return v;
 }
+/**
+ * An optional boolean field as a spreadable fragment: `{}` when the key is absent,
+ * `{ [key]: value }` when it is a boolean, and a shape error for anything else —
+ * including an explicit `null`. Spreading keeps an absent field ABSENT rather than
+ * present-as-`undefined`.
+ */
+function optionalBoolField(o, key) {
+    if (!(key in o) || o[key] === undefined)
+        return {};
+    const v = o[key];
+    if (typeof v !== "boolean")
+        throw readinessShapeError();
+    return { [key]: v };
+}
 function requireInt(o, key) {
     const v = o[key];
     if (typeof v !== "number" || !Number.isInteger(v))
@@ -2617,6 +2742,15 @@ function parseRequiredChecksVerification(sup, requiredChecksCount) {
         required_checks_evidence_fresh: fresh,
     };
 }
+/** Optional boolean: absent/null from an older server, a non-boolean fails closed. */
+function parseOptionalBool(o, key) {
+    const v = o[key];
+    if (v === undefined || v === null)
+        return null;
+    if (typeof v !== "boolean")
+        throw readinessShapeError();
+    return v;
+}
 /** Optional positive-integer threshold: absent/null from an older server. */
 function parseOptionalPositiveInt(o, key) {
     const v = o[key];
@@ -2666,6 +2800,9 @@ export function parseConductorReadinessResponse(body) {
             // Absent on a pre-BAPI-694 server, where no repository default can exist.
             review_policy_present: sup.review_policy_present === true,
             ...parseRequiredChecksVerification(sup, requiredChecksCount),
+            required_checks_retired_gate_configured: parseOptionalBool(sup, "required_checks_retired_gate_configured"),
+            required_checks_ci_workflow_absent: parseOptionalBool(sup, "required_checks_ci_workflow_absent"),
+            required_checks_review_workflow_absent: parseOptionalBool(sup, "required_checks_review_workflow_absent"),
         },
         github: {
             credentials_readable: requireBool(gh, "credentials_readable"),
@@ -2891,6 +3028,11 @@ function parseConductorCiWorkflow(body) {
         probe_succeeded: requireBool(o, "probe_succeeded"),
         workflow_present: requireBool(o, "workflow_present"),
         migration_guard_present: requireBool(o, "migration_guard_present"),
+        // BAPI-1359: OPTIONAL so a newer CLI still reads an older server. An absent
+        // key stays `undefined` — never materialized as a default — and a present key
+        // must be a real boolean (`null`, strings, numbers, and objects all reject).
+        ...optionalBoolField(o, "migration_guard_required"),
+        ...optionalBoolField(o, "migration_chain_probe_succeeded"),
     };
 }
 /**

package/build/conductor/bring-up-facts.js

@@ -1,5 +1,5 @@
 /** The pinned operator runbook every remedy below points into. */
-export const BRING_UP_RUNBOOK = "docs/claude/epic-implementer-v2-operator-runbook.md";
+export const BRING_UP_RUNBOOK = "docs/epic-implementer/operator-runbook.md";
 /**
  * The client-derived refusal vocabulary, IN REFUSAL ORDER.
  *

package/build/conductor/doctor.js

@@ -822,9 +822,9 @@ export function formatConductorDoctorReport(report) {
             lines.push(`  - ${w}`);
     }
     lines.push("");
-    lines.push("Epic Conductor v2 reconciles epics server-side — nothing to schedule");
-    lines.push("locally. To execute claimed jobs on this machine, run:");
-    lines.push(`  npx -y ${MCP_PACKAGE_NAME} executor --repo <name>`);
+    lines.push("The Epic Implementer reconciles epics server-side — nothing to schedule");
+    lines.push("locally. To execute a run's claimed jobs on this machine, run:");
+    lines.push(`  npx -y ${MCP_PACKAGE_NAME} executor --repo <name> --epic-run-id <run-id>`);
     lines.push("");
     lines.push("MCP Profile (optional, local)");
     lines.push("─────────────────────────────");

package/build/conductor/epic-implementer-cli.js

@@ -57,18 +57,21 @@ export function getConductorUsage() {
     return [
         "Usage: epic-implementer <command> [options]",
         "",
-        "Local append-only event ledger for multi-agent coordination.",
-        "Talks ONLY to the local SQLite store (~/.config/bridge/events.db); no Bridge API calls.",
+        "Local append-only event ledger for multi-agent coordination, plus run-control",
+        "commands. The ledger commands talk ONLY to the local SQLite store",
+        "(~/.config/bridge/events.db); the run-control commands (stop-run through",
+        "rerun-ci), epic-status, and readiness call the Bridge API.",
         "",
         "Commands:",
         "  emit-event           Append one semantic event to the ledger",
         "  supervise --run-id <id>  Run the foreground, run-scoped supervisor loop",
-        "  epic-tick            Run one stateless reconciliation pass for an Epic",
+        "  epic-tick            RETIRED (v1): always exits 1 with EPIC_TICK_V1_FROZEN; the",
+        "                       server-side reconciler replaced it",
         "  epic-status          Print read-only health summary of an Epic Run",
         "  send-message         Enqueue ONE typed supervisor->worker relay message (idempotent)",
         "  check-messages       Read + ACK pending relay messages for a worker (no redelivery)",
         "  doctor               Read-only health/diagnostics report (ledger + git hooks)",
-        "  readiness            Read-only ADVISORY report of every conductor prerequisite",
+        "  readiness            Read-only ADVISORY report of every Epic Implementer prerequisite",
         "                       (install + epic-implementer doctor + plane preflight + server),",
         "                       each with pass/warn/fail/skip and one named remediation.",
         "                       Remediations are NOT run automatically; always exits 0.",
@@ -115,6 +118,10 @@ export function getConductorUsage() {
         "  resume-ci --epic-run-id <id> --ticket-key <key> [--json]",
         "                       Resume a child parked on a qualified CI stop once CI is green: CI",
         "                       returns to evaluation with NO new wait, job, or repair allowance.",
+        "  rerun-ci --epic-run-id <id> --ticket-key <key> --binding <token> [--json]",
+        "                       Ask CI to re-run a ticket's FAILED checks at its bound head (guided: copy",
+        "                       the command explain-run rendered). Charges NO allowance and never re-runs",
+        "                       claude-review. A re-run is not a verdict: after CI is green, use resume-ci.",
         "",
         "supervise options:",
         "  --run-id <id>             Run/session identifier to supervise (required)",
@@ -196,11 +203,11 @@ export function getConductorUsage() {
         "  epic-implementer scope-catch-up --epic-run-id <id> --scope-id <scope>",
         "      # a merge landed on epic/<KEY> that the scope never observed (unobserved_advance)",
         "  epic-implementer patch-policy --epic-run-id <id> --patch-file required-checks.json",
-        "      # required_checks_empty_no_mode; the file holds {\"required_checks\":[\"conductor-ci / gate\"]}",
+        "      # required_checks_empty_no_mode; the file holds {\"required_checks\":[\"epic-implementer-ci / gate\"]}",
         "  epic-implementer resume-run --epic-run-id <id>",
         "      # a cap_wall_clock pause whose cause is now cleared",
         "",
-        "epic-tick options:",
+        "epic-tick options (retired; parsed by no live path):",
         "  --epic-key <KEY>          Epic key to supervise (required, non-empty)",
         "  --scheduled-at <epoch>    Epoch-seconds timestamp when this tick was scheduled (optional)",
         "  --lease-ttl-seconds <n>   Lease TTL in seconds (optional, default 120)",
@@ -259,6 +266,8 @@ export function getConductorUsage() {
         "  epic-implementer continuation-receipt --epic-run-id 3f9c2b7e-... --ticket-key BAPI-852",
         "  # CI finished green after the child parked on an expired CI wait:",
         "  epic-implementer resume-ci --epic-run-id 3f9c2b7e-... --ticket-key BAPI-852",
+        "  # CI failed on infrastructure: re-run it (never claude-review); then resume-ci once green:",
+        "  epic-implementer rerun-ci --epic-run-id 3f9c2b7e-... --ticket-key BAPI-852 --binding <token>",
     ].join("\n");
 }
 /**
@@ -312,6 +321,8 @@ const VALID_COMMANDS = new Set([
     "continuation-receipt",
     // BAPI-1326: CLI-only allowance-preserving CI resume — never an MCP tool.
     "resume-ci",
+    // BAPI-1388: CLI-only guided provider re-run of failed CI workflow runs — never an MCP tool.
+    "rerun-ci",
     // Private, and deliberately ABSENT from the usage text: `__hook-bin` exists as
     // the bundled-artifact regression guard for BAPI-772 (mirroring `plane
     // __entrypoint`), not as a supported operator workflow.
@@ -1451,6 +1462,11 @@ export async function runEpicImplementerCli(argv) {
                 const { runResumeCiCommand } = await import("./recovery-cli.js");
                 return await runResumeCiCommand(parsed.argv);
             }
+            case "rerun-ci": {
+                // BAPI-1388: delegates only to the guided, pinned rerun-ci operation.
+                const { runRerunCiCommand } = await import("./recovery-cli.js");
+                return await runRerunCiCommand(parsed.argv);
+            }
             default:
                 console.error('Error: Unknown command. Run "epic-implementer --help" for usage.');
                 return 1;

package/build/conductor/errors.js

@@ -70,9 +70,10 @@ export class ConductorStoreError extends Error {
  */
 export class ConductorEpicTickV1FrozenError extends Error {
     constructor() {
-        super("The v1 `epic-implementer epic-tick` path is frozen (EPIC_TICK_V1_FROZEN). Epic " +
-            "Conductor v2 replaces the local epic tick with a server-side reconciler " +
-            "plus the local executor — run `mcp-server executor` instead.");
+        super("The v1 `epic-implementer epic-tick` path is frozen (EPIC_TICK_V1_FROZEN). The " +
+            "Epic Implementer replaced the local epic tick with a server-side reconciler " +
+            "plus the local executor — run `mcp-server executor --repo <name> " +
+            "--epic-run-id <run-id>` instead.");
         this.name = "ConductorEpicTickV1FrozenError";
     }
 }

package/build/conductor/guided-repair.js

@@ -32,6 +32,9 @@ export const GUIDED_REPAIR_VERBS = [
     "scope-reparse",
     "scope-catch-up",
     "dispatch-remediation",
+    // BAPI-1388 — ticket-addressed, pinned to the same version-and-head subject as
+    // `dispatch-remediation`, and consuming the binding ExplainRun renders.
+    "rerun-ci",
 ];
 /** A malformed or mismatched binding. The message never echoes the token. */
 export class GuidedBindingError extends Error {
@@ -57,6 +60,7 @@ const ALLOWED_KEYS = {
     "scope-reparse": ["scope_id", "lifecycle_state", "required_commit_sha"],
     "scope-catch-up": ["scope_id", "lifecycle_state", "required_commit_sha"],
     "dispatch-remediation": ["ticket_key", "expected_row_version", "expected_head_sha"],
+    "rerun-ci": ["ticket_key", "expected_row_version", "expected_head_sha"],
 };
 function invalid() {
     return new GuidedBindingError("--binding is not a valid guided-repair binding; nothing was sent. Copy the " +
@@ -148,7 +152,7 @@ export function decodeGuidedBinding(token) {
             throw invalid();
         }
     }
-    else if (guidedVerb === "dispatch-remediation") {
+    else if (guidedVerb === "dispatch-remediation" || guidedVerb === "rerun-ci") {
         binding.ticketKey = boundedString(raw.ticket_key, 64);
         binding.expectedRowVersion = nonNegativeInt(raw.expected_row_version);
         binding.expectedHeadSha = optionalSha(raw.expected_head_sha);
@@ -202,7 +206,7 @@ export function guardForBinding(binding, requestId) {
             guard.block_reason = binding.blockReason;
         return guard;
     }
-    if (binding.verb === "dispatch-remediation") {
+    if (binding.verb === "dispatch-remediation" || binding.verb === "rerun-ci") {
         return {
             request_id: requestId,
             epic_run_id: binding.epicRunId,

package/build/conductor/hook-runtime-qualification.js

@@ -89,7 +89,7 @@ export const HOOK_RUNTIME_ACTIONS = {
         "from a persistent install.",
     "unqualified-runtime": "the hook runtime is not a qualified persistent installation (supported: a persistent npm " +
         `install of ${MCP_PACKAGE_NAME} ${HOOK_RUNTIME_COMPATIBLE_RANGE} on macOS or Linux with an even ` +
-        `Node LTS line >= ${HOOK_RUNTIME_MIN_NODE_MAJOR}). See mcp_server/docs/CONDUCTOR.md.`,
+        `Node LTS line >= ${HOOK_RUNTIME_MIN_NODE_MAJOR}). See mcp_server/docs/EPIC-IMPLEMENTER.md.`,
     "node-unavailable": "`node` could not be launched from PATH, so the hook cannot run. Put a qualified Node on PATH " +
         "and re-run `epic-implementer doctor`.",
     "native-unavailable": "better-sqlite3 does not load for the hook's Node, so no event can be recorded. Reinstall the " +

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

@@ -23,14 +23,13 @@
  * inspected a local checkout to decide merge eligibility would be answering a
  * different question from the one the server's before-merge preflight answers.
  *
- * ## Deferred remedy
+ * ## Remedy command
  *
- * {@link MERGE_WORKFLOW_REMEDY_COMMAND} names the generate-and-PR command epic
- * child 4 ships. Until child 4 lands, a refusal may name a command that is not
- * yet an executable entry point on the operator's machine. That residual risk,
- * its three containments, and who owns escalation are recorded once, in the
+ * {@link MERGE_WORKFLOW_REMEDY_COMMAND} is the complete generate-and-PR command that
+ * BAPI-1136 shipped (BAPI-1376 made it a full launcher command). Its history and containments are recorded once, in the
  * Python module's docstring; this mirror does not restate them.
  */
+import { MCP_PACKAGE_NAME } from "../mcp-identity.js";
 /** The one `RunPolicy.merge_execution_mode` value this contract governs. */
 export const MERGE_EXECUTION_MODE_GITHUB_ACTIONS = "github_actions";
 /**
@@ -80,7 +79,27 @@ export function mergeWorkflowVersionSupportsIntegrationActions(version) {
         INTEGRATION_ACTION_WORKFLOW_VERSIONS.includes(version));
 }
 /**
- * The single command that generates the merge workflow and opens its pull
- * request. Every refusal, remediation, and readiness line imports this constant.
+ * The dispatched subcommand that generates the merge workflow and opens its pull
+ * request. This is the part the CLI's own dispatcher (`index.ts`) matches on
+ * (`install`), not the launcher that starts it. The Python mirror derives its
+ * command head from this value.
  */
-export const MERGE_WORKFLOW_REMEDY_COMMAND = "install-bridge conductor --merge-workflow";
+export const MERGE_WORKFLOW_SUBCOMMAND = "install conductor --merge-workflow";
+/**
+ * The complete, copy-ready command that generates the merge workflow and opens
+ * its pull request. Every refusal, remediation, and readiness line imports this
+ * constant.
+ *
+ * The package name comes from `mcp-identity.ts`, the sole source of that
+ * literal (BAPI-806). That module is itself dependency-free, so this import can
+ * never close a cycle. The `<@org/team|@user>` placeholder is deliberately NOT a valid owner — the
+ * installer refuses it — so an operator must replace it before running.
+ */
+export const MERGE_WORKFLOW_REMEDY_COMMAND = `npx -y ${MCP_PACKAGE_NAME} ${MERGE_WORKFLOW_SUBCOMMAND} --codeowner <@org/team|@user>`;
+/**
+ * One reusable instruction to print beside {@link MERGE_WORKFLOW_REMEDY_COMMAND}.
+ * Bridge cannot infer who should review the workflow file, so the placeholder
+ * must be replaced by hand.
+ */
+export const MERGE_WORKFLOW_CODEOWNER_INSTRUCTION = "Bridge cannot infer the code owner. Before running, replace <@org/team|@user> " +
+    "with the one @user or @org/team who should review the workflow file.";

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

@@ -31,7 +31,7 @@
  * not eligible: it is a workflow this build has never been taught to reason
  * about, and "newer is probably fine" is a guess about a merge actuator.
  */
-import { MERGE_WORKFLOW_CHILD_MERGE_COMPATIBLE_VERSIONS, MERGE_WORKFLOW_REMEDY_COMMAND, mergeWorkflowVersionSupportsChildMerge, } from "./merge-execution-contract.js";
+import { MERGE_WORKFLOW_CHILD_MERGE_COMPATIBLE_VERSIONS, MERGE_WORKFLOW_CODEOWNER_INSTRUCTION, MERGE_WORKFLOW_REMEDY_COMMAND, mergeWorkflowVersionSupportsChildMerge, } from "./merge-execution-contract.js";
 /**
  * Remediation for a verdict that could not be established.
  *
@@ -51,7 +51,8 @@ export const MERGE_EXECUTION_UNVERIFIABLE_REMEDIATION = "re-run once the Bridge
  * second way.
  */
 export const MERGE_EXECUTION_INELIGIBLE_REMEDIATION = `run \`${MERGE_WORKFLOW_REMEDY_COMMAND}\` to generate the merge workflow and open its ` +
-    "pull request, then re-run once it is merged to the default branch.";
+    `pull request. ${MERGE_WORKFLOW_CODEOWNER_INSTRUCTION} ` +
+    "Then re-run once it is merged to the default branch.";
 function unverifiable(reason, detail) {
     return {
         status: "could_not_verify",

package/build/conductor/pr-ci-producer.js

@@ -531,7 +531,7 @@ export async function observePrCiFromPollResponse(commitRef, pollResponse, deps
 function extractTicketKeyFromRef(headRef) {
     if (!headRef)
         return null;
-    const match = /([A-Z][A-Z0-9]+-\d+)/i.exec(headRef);
+    const match = /([A-Z][A-Z0-9_]{0,19}-\d+)/i.exec(headRef);
     return match ? match[1].toUpperCase() : null;
 }
 /**

package/build/conductor/readiness-cli.js

@@ -39,6 +39,8 @@ import { readinessEndpointEnvironments, resolveConductorBridgeApiAccess, resolve
 import { validateHttpBaseUrl } from "../base-url.js";
 import { claudeReviewWorkflowPath } from "../claude-review-workflow.js";
 import { runDefaultPlanePreflight } from "../plane/cli.js";
+import { planeNotApplicableForTarget } from "../plane/endpoint.js";
+import { resolvePlaneServerEndpoint } from "../plane/member-roster.js";
 /** Fixed notice emitted to stderr when a source could not be collected. */
 export const READINESS_COLLECTION_NOTICE = "one or more readiness sources could not be collected; the affected prerequisites are reported as failures.";
 /** Usage text for `epic-implementer readiness`. */
@@ -101,10 +103,18 @@ async function collectProductionReport(repoRoot, env, baseUrl) {
     const accessResult = baseUrl === undefined
         ? await resolveConductorBridgeApiAccess({ env: reportEnv, cwd: repoRoot })
         : await resolveEpicLaunchBridgeApiAccess({ baseUrl }, { env: resolverEnv, cwd: repoRoot });
+    // BAPI-1360: the plane checks apply only when the selected access target names
+    // the local plane. Resolved from the SAME env the plane preflight reads, through
+    // the shared leaf predicate `drive-epic` uses, and never guessed: a target that
+    // is remote, or that cannot be resolved at all, is an explicit skip.
+    const planeNotApplicable = planeNotApplicableForTarget(resolvePlaneServerEndpoint(reportEnv), accessResult.ok ? accessResult.access.baseUrl : null);
     if (baseUrl !== undefined && !accessResult.ok) {
         // A refused override is never permission for a downstream doctor collector
         // to resolve credentials afresh from the general CLI environment.
-        return collectConductorReadinessGate({ repoName: null });
+        return collectConductorReadinessGate({
+            repoName: null,
+            ...(planeNotApplicable !== null ? { planeNotApplicable } : {}),
+        });
     }
     const access = accessResult.ok ? accessResult.access : null;
     return collectConductorReadinessGate({
@@ -134,7 +144,13 @@ async function collectProductionReport(repoRoot, env, baseUrl) {
         // The deny-enforcement probe is never spawned from this command; the check
         // is reported as an explicit skip naming `epic-implementer doctor` instead.
         conductorDoctorDeps: { env: reportEnv, skipDenyProbe: true },
-        runPlanePreflight: () => runDefaultPlanePreflight(repoRoot, reportEnv),
+        // Provided ONLY for a target that names the local plane; otherwise the rows
+        // are skipped without any probe.
+        ...(planeNotApplicable === null
+            ? {
+                runPlanePreflight: () => runDefaultPlanePreflight(repoRoot, reportEnv),
+            }
+            : { planeNotApplicable }),
     });
 }
 /**

package/build/conductor/readiness-sections.js

@@ -33,6 +33,7 @@
  * The one exception is {@link inspectWorkflowPresence}, which awaits the
  * READ-ONLY reader seams its caller injects and never opens a path of its own.
  */
+import { PRINTED_CONNECT_GITHUB_COMMAND } from "../printed-remedy-commands.js";
 import { MANAGED_HOOK_NAMES } from "./git-hooks.js";
 import { MCP_PACKAGE_NAME } from "../mcp-identity.js";
 import { CLAUDE_REVIEW_WORKFLOW_DRIFT_REMEDIATION, summarizeClaudeReviewWorkflowDrift, } from "../claude-review-workflow-drift.js";
@@ -41,7 +42,7 @@ import { classifyMergeExecutionEligibility, MERGE_EXECUTION_UNVERIFIABLE_REMEDIA
 import { MERGE_WORKFLOW_CHILD_MERGE_COMPATIBLE_VERSIONS, MERGE_WORKFLOW_PATH, mergeWorkflowVersionSupportsChildMerge, } from "./merge-execution-contract.js";
 import { classifyDatabaseMigration, classifySingleTransitionAuthority, classifyWorkerPresent, } from "./bring-up-facts.js";
 /** Operator runbook pointer surfaced beside the executor gap. */
-export const CONDUCTOR_OPERATOR_RUNBOOK_POINTER = "docs/claude/epic-implementer-v2-operator-runbook.md";
+export const CONDUCTOR_OPERATOR_RUNBOOK_POINTER = "docs/epic-implementer/operator-runbook.md";
 /**
  * Capability-matrix guidance for the executor leg.
  *
@@ -105,6 +106,22 @@ export const REQUIRED_CHECKS_PRESENTATION_COPY = {
         remediation: "restore required-check verification (a readable default branch with static lane " +
             "workflows and a current Bridge API), or correct the required-check configuration.",
     },
+    // BAPI-1360 — file- and check-specific copy for the two proven, repository-admin
+    // causes of `unverifiable`. Fixed strings over the two hard-coded workflow paths
+    // and the two gate names; nothing from the payload is interpolated.
+    retiredGate: {
+        detail: "Could not verify — a configured required check is the retired gate " +
+            `conductor-ci / gate; ${REQUIRED_CHECKS_OPERATOR_HOLD}`,
+        remediation: "a repository administrator replaces conductor-ci / gate with epic-implementer-ci / gate in the " +
+            "plan's required_checks, the supervisor done-gate checks, and branch protection.",
+    },
+    laneAbsent: {
+        detail: "Could not verify — a lane workflow file is missing from the default branch, so a configured " +
+            `required check has no producer; ${REQUIRED_CHECKS_OPERATOR_HOLD}`,
+        remediation: "a repository administrator adds the missing lane workflow file(s) — " +
+            ".github/workflows/epic-implementer-ci.yml and/or .github/workflows/claude-review.yml — " +
+            "to the default branch so the configured required checks (such as epic-implementer-ci / gate) have a producer.",
+    },
     empty: {
         detail: "Could not verify — the required-check list is EMPTY, which is unsafe: the done gate " +
             `would pass unconditionally; ${REQUIRED_CHECKS_OPERATOR_HOLD}`,
@@ -155,6 +172,24 @@ export function presentRequiredChecks(supervisor) {
             ...REQUIRED_CHECKS_PRESENTATION_COPY.unknown_name,
         };
     }
+    // BAPI-1360 — optional bounded facts refine the generic unverifiable copy. An
+    // old server reports neither, and keeps the wording above. Retired gate ranks
+    // first, then a proven-absent lane; anything else stays generic.
+    if (supervisor.required_checks_retired_gate_configured === true) {
+        return {
+            outcome: "unverifiable",
+            satisfied: false,
+            ...REQUIRED_CHECKS_PRESENTATION_COPY.retiredGate,
+        };
+    }
+    if (supervisor.required_checks_ci_workflow_absent === true ||
+        supervisor.required_checks_review_workflow_absent === true) {
+        return {
+            outcome: "unverifiable",
+            satisfied: false,
+            ...REQUIRED_CHECKS_PRESENTATION_COPY.laneAbsent,
+        };
+    }
     return {
         outcome: "unverifiable",
         satisfied: false,
@@ -268,7 +303,7 @@ export function githubCredentialsSection(readiness) {
         detail: g.credentials_readable
             ? `incomplete: ${missing} unresolved`
             : "no GitHub credential row for this repository",
-        remediation: "connect GitHub from the Bridge setup UI (`install-bridge connect-github`).",
+        remediation: `connect GitHub from the Bridge setup UI or run \`${PRINTED_CONNECT_GITHUB_COMMAND}\`.`,
     };
 }
 export function githubActionsSection(readiness) {
@@ -396,7 +431,7 @@ export function reconcilerSection(readiness) {
         // remediation at all — so a report could name a gap with no next step.
         return {
             id: "reconciler-liveness",
-            label: "Reconciler tick liveness",
+            label: "Active-run progress",
             status: "degraded",
             detail: "liveness could not be read",
             remediation: "retry once the Bridge API is reachable; reconciler liveness is unknown here, " +
@@ -406,19 +441,19 @@ export function reconcilerSection(readiness) {
     if (!r.stale) {
         return {
             id: "reconciler-liveness",
-            label: "Reconciler tick liveness",
+            label: "Active-run progress",
             status: "ok",
             detail: `last tick ${r.last_tick_age_seconds}s ago across ${r.active_run_count} active run(s)`,
         };
     }
     return {
         id: "reconciler-liveness",
-        label: "Reconciler tick liveness",
+        label: "Active-run progress",
         status: "degraded",
         detail: r.last_tick_at === null
             ? "no reconciler tick recorded for this repository"
             : `last tick ${r.last_tick_age_seconds}s ago (threshold ${readiness.thresholds.reconciler_stale_after_seconds}s)`,
-        remediation: "start the reconciler (`epic-implementer epic-tick` schedule) for this repository.",
+        remediation: "check the worker first (`server.worker-present`), then inspect the stalled run with `epic-implementer epic-status`.",
     };
 }
 // ---------------------------------------------------------------------------