@bridge_gpt/mcp-server 0.2.66 → 0.2.68

package/build/doctor.js

@@ -1,3 +1,6 @@
+import { formatGitCompatibilityDiagnostic } from "./start-tickets-prereqs.js";
+import { constants as assetFsConstants } from "node:fs";
+import { collectPackagedAssetDoctor } from "./generated-assets-doctor.js";
 /**
  * doctor — a strictly read-only, detect-and-instruct diagnostics subcommand for
  * the packaged `start-tickets` automation (BAPI-305).
@@ -19,7 +22,7 @@
  * reach a mutating lifecycle verb — `enable-linger`, `bootstrap`, `start` and
  * their kin exist in this file only as remediation TEXT the operator runs.
  */
-import { readdir, readFile, stat } from "fs/promises";
+import { readdir, readFile, stat, lstat, access, realpath } from "fs/promises";
 import { spawn } from "child_process";
 import os from "os";
 import path from "path";
@@ -54,6 +57,7 @@ import { validateBranchName } from "./base-ref.js";
 import { readPlaneManifest } from "./plane/manifest.js";
 import { validateTicketKey } from "./ticket-key-utils.js";
 import { resolveBranchForTicket } from "./worktree-core.js";
+import { BRIDGE_PERMISSIONS_MANIFEST_RELPATH, inspectBridgePermissions, } from "./bridge-permissions.js";
 import { diagnoseStaleWorktreeBranches, formatStaleWorktreeDiagnosticReport, } from "./stale-worktree-doctor.js";
 /**
  * The report/usage title (BAPI-669, U9b). `doctor` diagnoses the whole Bridge
@@ -76,6 +80,7 @@ export function getDoctorUsage() {
         `${DOCTOR_REPORT_TITLE}. It only checks your environment and prints manual`,
         "install instructions — it does not install anything, modify your system, or",
         "start the MCP server.",
+        "Git presence remains a prerequisite; Git-version compatibility is advisory-only.",
         "",
         "Flags:",
         "  --agent claude|cursor-agent|codex  Agent to include in the prerequisite check (default: claude)",
@@ -159,6 +164,13 @@ export function getDoctorUsage() {
         "It reads no install-state file, writes nothing, runs no launchctl/systemctl, and",
         "is advisory: missing, malformed, or credential-less units never change the exit code.",
         "",
+        "It also includes an advisory '/drive-epic-run permission rules' section",
+        "(BAPI-1398): whether the project permissions.allow rules and the optional user",
+        "autoMode entries that install writes are PRESENT, MISSING, or DRIFTED (for",
+        "example after the BAPI_MCP_CLI launcher changed). It reads .claude/settings.local.json,",
+        "~/.claude/settings.json, and .bridge/bridge-permissions.json, writes nothing,",
+        "and never changes the exit code.",
+        "",
         "Conductor ledger / native-module diagnostics (the SQLite ledger's native",
         "binding load status and Node-version skew) live under a separate command:",
         "  epic-implementer doctor",
@@ -363,6 +375,7 @@ export async function collectDoctorResults(deps, agentName) {
     const injected = deps;
     const probeDeps = {
         ...deps,
+        commandAssetMetadata: injected.commandAssetMetadata ?? { lstat, access: p => access(p, assetFsConstants.R_OK) },
         readFile: injected.readFile ?? ((p) => readFile(p, "utf-8")),
         stat: injected.stat ?? ((p) => stat(p)),
         homedir: injected.homedir ?? os.homedir,
@@ -412,6 +425,10 @@ export function formatDoctorPrereqSection(platform, collection) {
         return lines.join("\n");
     }
     for (const result of collection.results) {
+        if (result.gitCompatibility) {
+            lines.push(formatGitCompatibilityDiagnostic(result.gitCompatibility));
+            continue;
+        }
         const status = result.found ? "FOUND  " : "MISSING";
         // Missing-detail stays suppressed for every prerequisite EXCEPT one that has
         // been explicitly audited (BAPI-727, `renderDetailWhenMissing`). The general
@@ -1679,6 +1696,55 @@ export function formatOperationalAdvisoryReport(diagnostic) {
     lines.push("           runs NO command probe, repairs no scheduler, and never changes the exit code.");
     return lines.join("\n");
 }
+/** Collect the permission-rules inspection. Reads only; never writes. */
+export async function collectBridgePermissionsDiagnostic(deps) {
+    return inspectBridgePermissions({ cwd: deps.cwd, homeDir: deps.homeDir, env: deps.env }, { readFile: deps.readFile });
+}
+function formatPermissionScope(label, scope, optionalNote) {
+    switch (scope.state) {
+        case "present":
+            return [`PRESENT   ${label} — all ${scope.count} Bridge entries in ${scope.path}`];
+        case "missing":
+            return [
+                `MISSING   ${label} — ${scope.missing.length} Bridge entr${scope.missing.length === 1 ? "y is" : "ies are"} absent from ${scope.path}`,
+                ...(optionalNote ? [`  ${optionalNote}`] : []),
+            ];
+        case "drifted":
+            return [
+                `DRIFTED   ${label} — ${scope.reason} (${scope.path})`,
+                ...(scope.missing.length > 0 ? [`  ${scope.missing.length} current rule(s) missing.`] : []),
+                ...(scope.stale.length > 0 ? [`  ${scope.stale.length} rule(s) Bridge wrote earlier no longer match.`] : []),
+            ];
+        case "malformed":
+            return [`MALFORMED ${label} — ${scope.path} is not valid JSON settings; doctor did not change it.`];
+    }
+}
+/** Render the permission-rules section (pure formatting, secret-free). */
+export function formatBridgePermissionsDiagnosticReport(inspection) {
+    const lines = ["", "/drive-epic-run permission rules (auto mode)", ""];
+    if (inspection.launcher.ok) {
+        lines.push(`Launcher prefix: ${inspection.launcher.prefix}`);
+        if (inspection.recordedLauncher && inspection.recordedLauncher !== inspection.launcher.prefix) {
+            lines.push(`  Rules were written for a different launcher: ${inspection.recordedLauncher}`);
+        }
+    }
+    if (inspection.project.state === "launcher-refused") {
+        lines.push("REFUSED   project permissions.allow — the launcher override cannot be matched by an exact rule.");
+        if (!inspection.launcher.ok)
+            lines.push(`  ${inspection.launcher.reason}.`);
+    }
+    else {
+        lines.push(...formatPermissionScope("project permissions.allow", inspection.project));
+    }
+    lines.push(...formatPermissionScope("user autoMode entries", inspection.user, "Optional: install adds them only after you say yes."));
+    const healthy = inspection.project.state === "present" && inspection.user.state === "present";
+    if (!healthy) {
+        lines.push(`  To repair: re-run \`npx -y ${MCP_PACKAGE_NAME} install\` in a terminal (it lists every rule it writes).`);
+        lines.push(`  To remove Bridge's entries: \`npx -y ${MCP_PACKAGE_NAME} install --remove-bridge-permissions\`.`);
+    }
+    lines.push(`  Bridge's ownership record: ${BRIDGE_PERMISSIONS_MANIFEST_RELPATH}. Advisory only; never changes the exit code.`);
+    return lines.join("\n");
+}
 /**
  * Read-only inventory of this host's epic-launch profiles and whether each
  * one's credential binding matches its target. It reports; it never binds or
@@ -1886,6 +1952,13 @@ export async function runDoctorCli(argv, overrides = {}) {
     const preference = await readModelRoutingPreference(deps.env.BAPI_REPO_NAME ?? "_doctor_unscoped_", "review_ticket", preferencePath);
     log(`Personal model routing preference: ${preference.warning ?? preference.source}.`);
     log(formatDoctorPrereqSection(deps.platform, collection));
+    if (overrides.packagedAssets !== false) {
+        const injected = overrides.packagedAssets ?? {};
+        log(await collectPackagedAssetDoctor({ cwd: injected.cwd ?? deps.cwd,
+            readFile: injected.readFile ?? deps.readFile ?? (p => readFile(p, "utf-8")),
+            lstat: injected.lstat ?? lstat, access: injected.access ?? (p => access(p, assetFsConstants.R_OK)), realpath: injected.realpath ?? realpath,
+            platform: deps.platform }));
+    }
     // Executor-adapter section (BAPI-781). Advisory with respect to the EXIT CODE
     // — an unusable adapter is reported loudly but does not change doctor's
     // pass/fail, which stays driven by the start-tickets prerequisites this
@@ -1972,6 +2045,24 @@ export async function runDoctorCli(argv, overrides = {}) {
             /* local-launcher diagnostics are advisory; never block the doctor report */
         }
     }
+    // BAPI-1398 /drive-epic-run permission-rules section. Strictly read-only (two
+    // settings files and Bridge's manifest; no command, no network), and advisory:
+    // it never changes the exit code.
+    if (overrides.bridgePermissions !== false) {
+        try {
+            const injected = deps;
+            const permissionDeps = {
+                cwd: overrides.bridgePermissions?.cwd ?? deps.cwd,
+                homeDir: overrides.bridgePermissions?.homeDir ?? (injected.homedir ?? os.homedir)(),
+                env: overrides.bridgePermissions?.env ?? deps.env,
+                readFile: overrides.bridgePermissions?.readFile ?? injected.readFile ?? ((p) => readFile(p, "utf-8")),
+            };
+            log(formatBridgePermissionsDiagnosticReport(await collectBridgePermissionsDiagnostic(permissionDeps)));
+        }
+        catch {
+            /* permission-rule diagnostics are advisory; never block the doctor report */
+        }
+    }
     // Worker containment advisory section (BAPI-1019/A.7). Placed beside the other
     // advisory sections and, uniquely, issuing NO probe of any kind — no command,
     // no file read, no network call. That is what keeps doctor's "an unsupported

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

@@ -55,17 +55,20 @@
  */
 import { readdir, readFile } from "node:fs/promises";
 import path, { dirname, join } from "node:path";
-import { CONDUCTOR_DEFAULT_BASE_URL, ConductorBridgeApiError, resolveEpicLaunchBridgeApiAccess, fetchConductorReadiness, fetchEpicRunState, safeDiagnosticMessage, } from "./conductor/bridge-api-client.js";
+import { CONDUCTOR_DEFAULT_BASE_URL, ConductorBridgeApiError, resolveEpicLaunchBridgeApiAccess, fetchConductorReadiness, fetchEpicRunState, gateProfileWaivesCiWorkflow, safeDiagnosticMessage, } from "./conductor/bridge-api-client.js";
 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 { policyDeclaresNotifyWebhook, effectivePolicyFacts, readSetupEpicPolicyFile, runSetupEpicWorkflow, } from "./setup-epic.js";
+import { repositoryWorkflowRemedy } from "./conductor/repository-workflow-remedy.js";
+import { policyDeclaresNotifyWebhook, policyNotifyDestinationsConflict, notifyDestinationsConflictMessage, effectivePolicyFacts, readSetupEpicPolicyFile, runSetupEpicWorkflow, } from "./setup-epic.js";
 import { EPIC_KEY_PATTERN } from "./drive-epic-key.js";
+import { flushProcessStdout, writeJsonDocument } from "./conductor/json-output.js";
 import { discoverEpicPlan, } from "./plan-discovery.js";
 import { formatPlaneDiagnostic, launchPlaneControlPlane, requestPlaneScopedLanes, runDefaultPlanePreflight, runPlaneCli, } from "./plane/cli.js";
 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 +78,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 +151,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 +165,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 +177,21 @@ 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.
+        //
+        // BAPI-1390: the server decides which files are required (the review file
+        // only for a `verdict_protocol` run; the CI lane file only for a repository
+        // with no STORED gate profile and no `no_ci_gate`), and `satisfied` reads that
+        // decision as given. The remedy waives the CI file the same way, so a stored
+        // profile is never told to add a file it does not need. Gate-profile WARNINGS
+        // (epic-branch rows) are not requirements and are never read here.
+        remedyFor: (r) => repositoryWorkflowRemedy(gateProfileWaivesCiWorkflow(r) ? { ...r, conductor_ci_workflow: null } : r),
         satisfied: (r) => r.unattended?.repository_readiness_confirmed === true,
     },
     // BAPI-1135 — merge-execution eligibility is deliberately NOT a requirement here.
@@ -348,10 +360,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 +872,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 +937,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 +1032,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 +1050,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.
  *
@@ -1245,6 +1250,7 @@ export function createDefaultDriveEpicDeps() {
         // construction, so nothing has claimed stdout for the protocol transport.
         log: (message) => console.log(message),
         errorLog: (message) => console.error(message),
+        flushStdout: flushProcessStdout,
     };
 }
 /**
@@ -1637,7 +1643,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 +1738,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 = [
@@ -1793,6 +1796,21 @@ async function checkPlaneAdmission(ctx, readiness, manifest) {
  */
 async function coldStartPlane(ctx) {
     const { deps, epicKey } = ctx;
+    // BAPI-1397 (F1): a policy the server would reject for its notify destinations
+    // is refused BEFORE the plane preflight and `plane up`, naming its file. The
+    // same predicate setup-epic applies; a cold start has no live run, so the
+    // selected file is the explicit one or the profile's, as in
+    // `prepareSetupSelection`. An unreadable file is left to that function.
+    const coldPolicyPath = ctx.options.policyFile ?? ctx.profile?.policyRef?.path;
+    if (coldPolicyPath !== undefined) {
+        const read = await readSetupEpicPolicyFile(coldPolicyPath, (filePath) => deps.readPolicyFile(filePath));
+        if (read.ok && policyNotifyDestinationsConflict(read.policy)) {
+            return refuse(deps, [
+                `${epicKey}: REFUSED (policy-notify-conflict) — ` +
+                    notifyDestinationsConflictMessage(coldPolicyPath, ctx.options.policyFile !== undefined ? "explicit" : "profile"),
+            ]);
+        }
+    }
     // The cold start leaves the readiness `catch` before the ordinary advisory
     // read is reached, so it surfaces the BAPI-1022 containment advisory itself —
     // before anything is started, exactly as every other plan-file route does.
@@ -2521,7 +2539,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 +2650,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 +2679,43 @@ async function runDriveEpicPreview(deps, options) {
             remedy: "The preview could not complete. Run it again; nothing was created or started.",
         });
     }
-    emitPreview(deps, options, preview);
+    ensureRefusalExplained(preview);
+    const emitted = await emitPreview(deps, options, preview);
+    // BAPI-1397 (F3): a `--json` document that could not reach stdout whole is a
+    // failed preview, never a silently truncated one.
+    if (!emitted)
+        return 1;
     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;
@@ -2957,11 +3014,19 @@ async function previewExecutorFacts(ctx, readiness, planeTarget, live, outcome)
         ? null
         : executorPreconditionRefusal(epicKey, inspected.message, outcome === "No run was created" ? "No run was created." : "No run was changed.");
 }
-/** Print the preview: one JSON line with `--json`, short readable lines otherwise. */
-function emitPreview(deps, options, preview) {
+/**
+ * Print the preview: one JSON line with `--json`, short readable lines otherwise.
+ *
+ * BAPI-1397 (F3): the `--json` document goes through the shared CLI writer, which
+ * waits for a piped stdout to drain before the exit code is returned. Resolves
+ * `false` only when that document could not be written whole.
+ */
+async function emitPreview(deps, options, preview) {
     if (options.json === true) {
-        deps.log(JSON.stringify(preview));
-        return;
+        return writeJsonDocument(JSON.stringify(preview), {
+            log: deps.log,
+            flush: deps.flushStdout ?? (async () => true),
+        });
     }
     const lines = [
         `${preview.epic_key}: launch preview (read-only; nothing was created or started)`,
@@ -2980,11 +3045,14 @@ 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) {
         lines.push(`  Refusal:    ${preview.refusal.reason_id} — ${preview.refusal.remedy}`);
     }
     deps.log(lines.join("\n"));
+    return true;
 }

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+(.*))?$/;

package/build/epic-coherence-input.test-fixtures.js

@@ -14,7 +14,7 @@ export function memoryRepo(files, options = {}) {
     const contents = new Map();
     for (const [rel, body] of Object.entries(files))
         contents.set(path.join(ROOT, rel), body);
-    const dirs = new Set([path.sep, ROOT]);
+    const dirs = new Set([path.parse(ROOT).root, ROOT]);
     const addDirs = (abs) => {
         let dir = path.dirname(abs);
         while (!dirs.has(dir)) {
@@ -33,8 +33,9 @@ export function memoryRepo(files, options = {}) {
     const repo = { fs: undefined, files: contents, writes: [], reads: [], realpaths: [] };
     const missing = (p) => Object.assign(new Error(`ENOENT: ${p}`), { code: "ENOENT" });
     const resolveLinks = (p) => {
-        const parts = p.split(path.sep).filter(Boolean);
-        let current = path.sep;
+        const root = path.parse(p).root;
+        const parts = p.slice(root.length).split(path.sep).filter(Boolean);
+        let current = root;
         for (const part of parts) {
             current = path.join(current, part);
             const target = symlinks.get(current);