@bridge_gpt/mcp-server 0.2.66 → 0.2.67

package/build/drive-epic-key.js

@@ -4,9 +4,10 @@
  * It lives in its own module so `plan-discovery.ts` can import it without
  * importing `drive-epic.ts`, which imports discovery — a cycle.
  *
- * This is deliberately the narrower CLI grammar. Bundle finalization accepts some
- * underscore or digit project prefixes, but `drive-epic` already rejects them, so
- * metadata naming such a key can never be discovered through this CLI.
+ * BAPI-1348: this is the canonical ticket-key grammar from `ticket-key-utils.ts`,
+ * so a local-mode epic whose prefix carries digits or underscores (for example
+ * `STOREFRONT2-1` or `STOREFRONT_CLIENTA-1`) is accepted.
  */
-/** Jira epic key shape. Matches the epic-key positional rule exactly. */
-export const EPIC_KEY_PATTERN = /^[A-Z]+-[0-9]+$/;
+import { TICKET_KEY_PATTERN } from "./ticket-key-utils.js";
+/** Epic key shape. The canonical ticket-key pattern, shared with every other reader. */
+export const EPIC_KEY_PATTERN = TICKET_KEY_PATTERN;

package/build/drive-epic.js

@@ -59,6 +59,7 @@ import { CONDUCTOR_DEFAULT_BASE_URL, ConductorBridgeApiError, resolveEpicLaunchB
 import { EPIC_LAUNCH_PROFILE_NAME_PATTERN, epicLaunchPolicyDigest, pinEpicLaunchPolicy, renderEpicLaunchCommand, resolveEpicLaunchSelection, shellQuote, } from "./epic-launch-profile.js";
 import { validateHttpBaseUrl, describeBaseUrlRejection } from "./base-url.js";
 import { BRING_UP_REFUSAL_MESSAGES, BRING_UP_RUNBOOK, firstBringUpRefusal, } from "./conductor/bring-up-facts.js";
+import { repositoryWorkflowRemedy } from "./conductor/repository-workflow-remedy.js";
 import { policyDeclaresNotifyWebhook, effectivePolicyFacts, readSetupEpicPolicyFile, runSetupEpicWorkflow, } from "./setup-epic.js";
 import { EPIC_KEY_PATTERN } from "./drive-epic-key.js";
 import { discoverEpicPlan, } from "./plan-discovery.js";
@@ -66,6 +67,7 @@ import { formatPlaneDiagnostic, launchPlaneControlPlane, requestPlaneScopedLanes
 import { PLANE_PORT_PROBE_TIMEOUT_MS, describePlanePortOccupant, } from "./plane/preflight.js";
 import { createPlaneFsDeps, probeAutomationHealth, probeTcpPort, resolveHostname, } from "./plane/defaults.js";
 import { readPlaneManifest } from "./plane/manifest.js";
+import { baseUrlNamesPlaneEndpoint, planeEndpointForTarget } from "./plane/endpoint.js";
 import { resolvePlaneServerEndpoint, } from "./plane/member-roster.js";
 import { resolveMemberInstanceId } from "./plane/supervisor.js";
 import { PLANE_SERVER_PORT_ENV_VAR, } from "./plane/types.js";
@@ -75,6 +77,7 @@ import { isTerminalEpicRunStatus } from "./epic-run-status.js";
 // BAPI-806: mcp-identity.ts is the SOLE source of the package-name literal, so
 // the printed invocation interpolates it rather than repeating it.
 import { MCP_PACKAGE_NAME } from "./mcp-identity.js";
+import { PRINTED_CHECK_NAME_INSTRUCTION, PRINTED_CONDUCTOR_INSTALL_COMMAND, PRINTED_DOCTOR_COMMAND, } from "./printed-remedy-commands.js";
 /** The conductor paths. Derived types below come from this constant. */
 export const DRIVE_EPIC_CONDUCTORS = ["v2"];
 /**
@@ -147,7 +150,7 @@ export const V2_READINESS_REQUIREMENTS = [
     // set — the server simply never said (BAPI-1102 review).
     {
         id: "unattended_consent",
-        describe: "repository consent to unattended conductor runs",
+        describe: "repository consent to unattended Epic Implementer runs",
         unattendedOnly: true,
         // No fixed `remedy`: this requirement's action always depends on WHY.
         remedyFor: (r) => r.unattended === null || r.unattended === undefined
@@ -161,7 +164,7 @@ export const V2_READINESS_REQUIREMENTS = [
     },
     {
         id: "unattended_notify_default",
-        describe: "a verified notify webhook default for escalation",
+        describe: "an escalation channel (a verified notify webhook or the account email)",
         unattendedOnly: true,
         remedy: "Supply a --policy-file declaring notify.webhook_url, or add an email address " +
             "to the account so escalation alerts can be emailed, or pass --attended. " +
@@ -173,13 +176,14 @@ export const V2_READINESS_REQUIREMENTS = [
     },
     {
         id: "repository_readiness",
-        describe: "confirmed review and conductor-CI workflows on the default branch",
+        describe: "confirmed review and epic-implementer-ci workflows on the default branch",
         unattendedOnly: true,
-        // S5 seam: `install-bridge conductor` is the NESTED install-time surface
-        // (BAPI-679), a different command from the top-level `conductor` ->
-        // `epic-implementer` rename in S4/BAPI-1080. It is intentionally outside
-        // S4 and every remedy string below that names it is left unchanged.
-        remedy: "Run `install-bridge conductor` to install them, or pass --attended.",
+        // BAPI-1359 (Miss 38): the remedy names the SPECIFIC missing item, from the
+        // same shared formatter the readiness row and the setup-epic refusal use. The
+        // fixed install-command sentence that stood here could never clear a missing
+        // migration-guard job — no install step creates one — so it is gone from this
+        // refusal.
+        remedyFor: (r) => repositoryWorkflowRemedy(r),
         satisfied: (r) => r.unattended?.repository_readiness_confirmed === true,
     },
     // BAPI-1135 — merge-execution eligibility is deliberately NOT a requirement here.
@@ -348,10 +352,11 @@ export function getDriveEpicUsage() {
         "UNATTENDED by default — it authorizes automatic merge into the epic branch, and",
         "the server stamps its CI gate at first approval. The INTEGRATION PR into the",
         "repository base branch stays human-gated. Pass --attended to opt out. An",
-        "unattended run has two repository prerequisites (consent, which is ON by",
-        "default and switched on the Bridge admin panel's Setup page, and a verified",
-        "notify webhook default) that readiness lists with their state and that are",
-        "refused BY NAME before any run is created.",
+        "unattended run has three repository prerequisites (consent, which is ON by",
+        "default and switched on the Bridge admin panel's Setup page; an escalation",
+        "channel, either a verified notify webhook or the account's email address; and",
+        "confirmed review and CI workflows on the default branch) that readiness lists",
+        "with their state and that are refused BY NAME before any run is created.",
         "",
         "Every run gets an executor (BAPI-1279): with --plan-file, once the run is",
         "created drive-epic starts a RUN-SCOPED EXECUTOR for it in the background, from",
@@ -859,7 +864,7 @@ export function assertSingleConductorInvocation(text) {
     // commands (say, one per profile or target) would hand the reader a choice of
     // authority just as surely as naming two conductors. The same command
     // repeated is still one invocation.
-    const runnable = new Set((text.match(/\bdrive-epic\s+[A-Z][A-Z0-9]*-[0-9]+[^\n]*/g) ?? []).map((line) => line.trim()));
+    const runnable = new Set((text.match(/\bdrive-epic\s+[A-Z][A-Z0-9_]{0,19}-[0-9]+[^\n]*/g) ?? []).map((line) => line.trim()));
     if (runnable.size > 1) {
         throw new Error(`drive-epic emitted ${runnable.size} different runnable launch commands. ` +
             "Exactly one path may ever be presented.");
@@ -924,19 +929,32 @@ export function parseContainmentEligibilityArtifact(raw) {
         return null;
     return { containmentChildren: containmentChildren, flagged };
 }
+/** Sidecar name `assess-epic-implementer-eligibility` writes. */
+export const ELIGIBILITY_ARTIFACT_NAME = "epic-implementer-eligibility.json";
+/** Pre-rename sidecar name, read only when the current name is absent. */
+export const LEGACY_ELIGIBILITY_ARTIFACT_NAME = "conductor-eligibility.json";
 /**
  * Locate and read the containment-eligibility sidecar for a supplied plan
- * file, then parse it. `conductor-eligibility.json` is always a sibling of
- * the plan file — `dirname(planFile)/conductor-eligibility.json` — the same
- * directory `assess-conductor-eligibility` writes it to. Fails open on every
+ * file, then parse it. The sidecar is always a sibling of the plan file —
+ * `dirname(planFile)/epic-implementer-eligibility.json` — the same directory
+ * `assess-epic-implementer-eligibility` writes it to. When that read fails,
+ * the legacy `conductor-eligibility.json` name is tried, so plans written
+ * before the rename still surface their advisory. Fails open on every
  * boundary: a resolution failure, a rejected read (missing file, permission
  * error), invalid JSON, or a malformed/inconsistent artifact all resolve to
  * `null`, never a thrown error.
  */
 export async function readContainmentEligibilityAdvisory(planFile, readEligibilityArtifact) {
     try {
-        const artifactPath = join(dirname(planFile), "conductor-eligibility.json");
-        const raw = await readEligibilityArtifact(artifactPath);
+        const planDir = dirname(planFile);
+        let raw;
+        try {
+            raw = await readEligibilityArtifact(join(planDir, ELIGIBILITY_ARTIFACT_NAME));
+        }
+        catch {
+            // Plans written before the rename carry only the legacy sidecar name.
+            raw = await readEligibilityArtifact(join(planDir, LEGACY_ELIGIBILITY_ARTIFACT_NAME));
+        }
         const parsed = JSON.parse(raw);
         return parseContainmentEligibilityArtifact(parsed);
     }
@@ -1006,6 +1024,10 @@ export function firstPreconditionRefusal(preflight, options = {}) {
 // ---------------------------------------------------------------------------
 // BAPI-1153 — cold start, attach, or one named refusal
 // ---------------------------------------------------------------------------
+// BAPI-1360: the predicate moved to the `plane/endpoint.ts` leaf so the readiness
+// command can share it; it is re-exported here so every existing import and launch
+// decision is unchanged.
+export { baseUrlNamesPlaneEndpoint };
 /**
  * The refusals drive-epic itself names on the cold-start and attach paths.
  *
@@ -1020,31 +1042,6 @@ export const DRIVE_EPIC_PLANE_REFUSALS = [
     /** The plane's own reconciler is not confirmed as the fresh one. */
     "plane-reconciler-unconfirmed",
 ];
-/** Loopback spellings that name the plane's `127.0.0.1` host. */
-const LOOPBACK_HOSTNAMES = new Set(["127.0.0.1", "localhost", "[::1]", "::1"]);
-/**
- * Does `baseUrl` name the plane's own loopback endpoint? Pure.
- *
- * Cold start and attach are decisions about THE PLANE, so they only make sense
- * when the Bridge API the command talks to IS the plane's server. The conductor
- * default base URL is production; a readiness failure against it says nothing
- * about a local port, and must keep escalating exactly as before. Loopback
- * spellings are equivalent (`localhost` and `127.0.0.1` reach the same socket);
- * the port must match exactly.
- */
-export function baseUrlNamesPlaneEndpoint(baseUrl, endpoint) {
-    let url;
-    try {
-        url = new URL(baseUrl);
-    }
-    catch {
-        return false;
-    }
-    if (url.protocol !== "http:")
-        return false;
-    const port = url.port === "" ? 80 : Number(url.port);
-    return LOOPBACK_HOSTNAMES.has(url.hostname) && port === endpoint.port;
-}
 /**
  * Rebuild the identity the plane's reconciler publishes its heartbeat under. Pure.
  *
@@ -1637,7 +1634,7 @@ const READINESS_UNKNOWN_REASON_ID = "readiness-unknown";
  */
 function operatorBlockedRemedy(classification) {
     return (classification.remedy ??
-        "Resolve it with `install-bridge conductor`, then run drive-epic again.");
+        `Resolve it with \`${PRINTED_CONDUCTOR_INSTALL_COMMAND}\` (${PRINTED_CHECK_NAME_INSTRUCTION}), then run drive-epic again.`);
 }
 /**
  * The escalation branch. Prints NO conductor invocation at all — naming a
@@ -1732,10 +1729,7 @@ function durableActorAdmissionDenied(readiness) {
  * applies.
  */
 function planeEndpointForBaseUrl(deps, baseUrl) {
-    const resolution = deps.resolvePlaneEndpoint();
-    if (!resolution.ok)
-        return null;
-    return baseUrlNamesPlaneEndpoint(baseUrl, resolution.endpoint) ? resolution.endpoint : null;
+    return planeEndpointForTarget(deps.resolvePlaneEndpoint(), baseUrl);
 }
 /** What to tell the operator about a plane THIS invocation started and left up. */
 const LAUNCHED_PLANE_LEFT_RUNNING = [
@@ -2521,7 +2515,7 @@ export const DRIVE_EPIC_ACCESS_REFUSAL_REASON_IDS = {
 };
 /** The readiness reason a preview reports for a generic not-ready engine. */
 const ENGINE_NOT_READY_REASON_ID = "engine-not-ready";
-const ENGINE_NOT_READY_REMEDY = "Resolve conductor readiness (`install-bridge conductor`, then `doctor`) and run drive-epic again.";
+const ENGINE_NOT_READY_REMEDY = `Resolve conductor readiness (\`${PRINTED_CONDUCTOR_INSTALL_COMMAND}\`, then \`${PRINTED_DOCTOR_COMMAND}\`) and run drive-epic again. ${PRINTED_CHECK_NAME_INSTRUCTION}`;
 /**
  * Read exactly one well-shaped setup-epic dry-run JSON document out of captured
  * `log` output. Anything else — none, several, or one with the wrong shape — is
@@ -2632,11 +2626,16 @@ async function runDriveEpicPreview(deps, options) {
         decision: "refuse",
         refusal: null,
     };
-    /** A refusal carried by the readiness block (and mirrored where the ticket needs it). */
-    const refuseWithReadiness = (kind, named, alsoTopLevel = false) => {
+    /**
+     * A refusal carried by the readiness block AND mirrored into the top-level
+     * `refusal` (BAPI-1360): every readiness refusal now has one primary explanation
+     * a consumer reads from a single place. The nested readiness pair is unchanged.
+     * `_alsoTopLevel` is retained so existing call sites keep their signature; it no
+     * longer selects anything.
+     */
+    const refuseWithReadiness = (kind, named, _alsoTopLevel = false) => {
         preview.readiness = { kind, reason_id: named.reasonId, remedy: named.remedy };
-        if (alsoTopLevel)
-            preview.refusal = { reason_id: named.reasonId, remedy: named.remedy };
+        preview.refusal = { reason_id: named.reasonId, remedy: named.remedy };
         preview.decision = "refuse";
     };
     /** A refusal that is not about readiness: only the top-level block carries it. */
@@ -2656,9 +2655,39 @@ async function runDriveEpicPreview(deps, options) {
             remedy: "The preview could not complete. Run it again; nothing was created or started.",
         });
     }
+    ensureRefusalExplained(preview);
     emitPreview(deps, options, preview);
     return preview.decision === "create" || preview.decision === "attach" ? 0 : 1;
 }
+/** The fixed explanation used when a refusal reached the end with none of its own. */
+export const PREVIEW_REFUSAL_FALLBACK_REASON_ID = "preview-refused";
+const PREVIEW_REFUSAL_FALLBACK_REMEDY = "The preview refused this launch without naming a specific cause. Resolve conductor readiness and preview again; nothing was created or started.";
+function isNamedRefusal(value) {
+    if (value === null || typeof value !== "object")
+        return false;
+    const { reason_id: reasonId, remedy } = value;
+    return typeof reasonId === "string" && reasonId.trim() !== "" && typeof remedy === "string" && remedy.trim() !== "";
+}
+/**
+ * Every `refuse` decision carries a primary explanation (BAPI-1360).
+ *
+ * Runs after `previewDecision`, whatever path it took. A still-absent or malformed
+ * top-level `refusal` on a refusing preview is filled from the readiness pair when
+ * that pair is valid, and otherwise from a fixed generic reason and remedy — never
+ * from anything thrown or received. An already-valid refusal is left untouched.
+ * The exit code does not depend on this: a refusing decision exits non-zero either
+ * way, so a malformed field can never turn a refusal into a success.
+ */
+export function ensureRefusalExplained(preview) {
+    if (preview.decision !== "refuse")
+        return;
+    if (isNamedRefusal(preview.refusal))
+        return;
+    const { reason_id: reasonId, remedy } = preview.readiness;
+    preview.refusal = isNamedRefusal({ reason_id: reasonId, remedy })
+        ? { reason_id: reasonId, remedy: remedy }
+        : { reason_id: PREVIEW_REFUSAL_FALLBACK_REASON_ID, remedy: PREVIEW_REFUSAL_FALLBACK_REMEDY };
+}
 /** Fill in `preview` by walking the same decisions a real launch makes, read-only. */
 async function previewDecision(deps, options, preview, refuseWithReadiness, refuseTopLevel) {
     const { epicKey } = options;
@@ -2980,7 +3009,9 @@ function emitPreview(deps, options, preview) {
     }
     const s = preview.summary;
     lines.push(`  Posture:    ${s.posture ?? "n/a"}`, `  Children:   ${s.child_count ?? "n/a"}`, `  Branch:     ${s.branch ?? "n/a"}`, `  Auto-merge: ${s.auto_merge_scope ?? "n/a"}`, `  Escalation: ${s.escalation_channel ?? "n/a"}`, `  Validation: ${preview.cold_start ? "Partial — plane is not yet running" : s.server_validation ?? "n/a"}`, `  Decision:   ${preview.decision}`);
-    if (preview.readiness.remedy && !preview.refusal?.reason_id.startsWith("access-")) {
+    if (preview.readiness.remedy &&
+        preview.readiness.remedy !== preview.refusal?.remedy &&
+        !preview.refusal?.reason_id.startsWith("access-")) {
         lines.push(`  Remedy:     ${preview.readiness.remedy}`);
     }
     if (preview.refusal) {

package/build/epic-coherence-input.js

@@ -19,6 +19,7 @@
  */
 import { createHash } from "node:crypto";
 import path from "node:path";
+import { TICKET_KEY_PATTERN } from "./ticket-key-utils.js";
 import { writeJsonAtomically, } from "./conductor-bundle-artifacts.js";
 // ===========================================================================
 // Constants
@@ -41,7 +42,7 @@ export const HIGH_RISK_PATH_PREFIXES = [
     "tests/integration/conductor_harness/",
     "api/library/db/",
 ];
-const EPIC_KEY_PATTERN = /^[A-Z][A-Z0-9]+-\d+$/;
+const EPIC_KEY_PATTERN = TICKET_KEY_PATTERN;
 const EPIC_SLUG_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
 const AC_ID_PATTERN = /^AC-\d+$/;
 const EPIC_AC_BULLET = /^[-*]\s+(?:\*\*)?(AC-\d+):(?:\*\*)?(?:\s+(.*))?$/;