@bridge_gpt/mcp-server 0.2.65 → 0.2.66

package/build/drive-epic.js

@@ -56,10 +56,10 @@
 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 { EPIC_LAUNCH_PROFILE_NAME_PATTERN, renderEpicLaunchCommand, shellQuote, } from "./epic-launch-profile.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, readSetupEpicPolicyFile, runSetupEpicWorkflow, } from "./setup-epic.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";
 import { formatPlaneDiagnostic, launchPlaneControlPlane, requestPlaneScopedLanes, runDefaultPlanePreflight, runPlaneCli, } from "./plane/cli.js";
@@ -120,8 +120,9 @@ export const V2_READINESS_REQUIREMENTS = [
         // The repository-scoped `reconciler` section ("is this repository's work
         // moving?", from `epic_runs.last_tick_at`) is only the fallback for a server
         // too old to report `bring_up`.
-        satisfied: (r) => r.bring_up !== null && r.bring_up !== undefined
-            ? r.bring_up.heartbeat_readable && r.bring_up.worker_present
+        satisfied: (r) => r.bring_up
+            ? r.bring_up.heartbeat_readable && r.bring_up.worker_present &&
+                r.bring_up.single_transition_authority
             : r.reconciler.liveness_readable && !r.reconciler.stale,
     },
     {
@@ -238,6 +239,24 @@ export const V2_RUNTIME_READINESS_IDS = ["reconciler_live"];
  * already encodes that (setup, then config, then credentials).
  */
 export function classifyV2Readiness(readiness, options = {}) {
+    for (const diagnostic of readiness.diagnostics ?? []) {
+        if (diagnostic.severity === null || diagnostic.applicability === null) {
+            return {
+                kind: "operator_blocked",
+                id: "diagnostic-metadata-unknown",
+                describe: "declared diagnostic severity and applicability",
+                remedy: "Upgrade or repair the readiness producer, then retry the selected target.",
+            };
+        }
+        if (diagnostic.applicability === "applicable" && diagnostic.severity === "mandatory" && diagnostic.verdict !== "passed") {
+            return {
+                kind: "operator_blocked",
+                id: "mandatory-diagnostic-unverified",
+                describe: `mandatory diagnostic ${diagnostic.id}`,
+                remedy: "Resolve the mandatory diagnostic at the selected Bridge API target and retry.",
+            };
+        }
+    }
     // BAPI-1102 — the explicit `--attended` opt-out makes the unattended-only
     // requirements INAPPLICABLE, not merely tolerated. They authorize unattended
     // operation and automatic merge behavior; an attended run asks for neither, so
@@ -253,7 +272,9 @@ export function classifyV2Readiness(readiness, options = {}) {
     // which reads the policy and refuses if it declares none. Nothing is weakened:
     // `setup-epic` gates before the create, and the server re-checks the predicate
     // at approval and probes the URL there.
-    const deferred = options.hasPolicyFile
+    const deferred = options.approvedStoredPolicy ||
+        options.effectivePolicy?.escalationChannel === "configured webhook" ||
+        (options.effectivePolicy === undefined && options.hasPolicyFile)
         ? V2_READINESS_REQUIREMENTS.filter((req) => req.id !== "unattended_notify_default")
         : V2_READINESS_REQUIREMENTS;
     // `--into-base` is the second opt-out, and it is structural rather than
@@ -270,8 +291,28 @@ export function classifyV2Readiness(readiness, options = {}) {
         ? gating.filter((req) => req.unattendedOnly !== true)
         : gating;
     const unmet = applicable.filter((req) => !req.satisfied(readiness));
-    if (unmet.length === 0)
+    if (unmet.length === 0) {
+        // Older deployments have no bring-up block; their existing reconciler
+        // liveness predicate remains the available evidence. For deployments that
+        // do report process facts, an unreadable owner never becomes a green launch.
+        if (readiness.bring_up && !readiness.bring_up.heartbeat_readable) {
+            return {
+                kind: "operator_blocked",
+                id: "process-owner-unverified",
+                describe: "a readable reconciler process-owner heartbeat",
+                remedy: "Restore the process heartbeat source before launch.",
+            };
+        }
+        if (readiness.bring_up?.worker_present && !readiness.bring_up.single_transition_authority) {
+            return {
+                kind: "operator_blocked",
+                id: "process-owner-conflict",
+                describe: "one verified reconciler process owner",
+                remedy: "Resolve the missing or duplicate reconciler process before launch.",
+            };
+        }
         return { kind: "green" };
+    }
     const blocker = unmet.find((req) => !V2_RUNTIME_READINESS_IDS.includes(req.id));
     if (blocker) {
         return {
@@ -406,6 +447,10 @@ export function getDriveEpicUsage() {
         "                         non-production server and for durable hosts.",
         "  --base-url <url>       Explicit Bridge API target. With a profile it must",
         "                         agree with it — an override never rebinds a profile.",
+        "BAPI_EPIC_LAUNCH_PROFILE selects a host-local launch profile for epic",
+        "launches. --launch-profile takes precedence. For an environment-selected",
+        "profile, BAPI_BASE_URL remains the general CLI endpoint and does not",
+        "conflict with the epic launch target; --base-url still must agree.",
         "Without either, BAPI_BASE_URL is used. With none of the three, drive-epic",
         `targets production (${CONDUCTOR_DEFAULT_BASE_URL}) and uses the`,
         "stored bapi:<repo> key when one is available. A stored key approved for a",
@@ -1077,7 +1122,14 @@ export async function readLiveEpicRunByKey(access, epicKey, fetchImpl = globalTh
             typeof run.status !== "string") {
             return { kind: "unknown", reason: "the run state response was malformed" };
         }
-        return { kind: "live", epicRunId: run.epic_run_id, status: run.status };
+        return {
+            kind: "live",
+            epicRunId: run.epic_run_id,
+            status: run.status,
+            ...(run.policy_json !== undefined
+                ? { effectivePolicy: effectivePolicyFacts(run.policy_json, "stored") }
+                : {}),
+        };
     }
     catch (err) {
         if (err instanceof ConductorBridgeApiError) {
@@ -1104,8 +1156,8 @@ export function createDefaultDriveEpicDeps() {
                 ...(cwd ? { cwd } : {}),
             });
             return result.ok
-                ? { ok: true, access: result.access, profile: result.profile }
-                : { ok: false, error: result.error };
+                ? { ok: true, access: result.access, profile: result.profile, targetSource: result.targetSource }
+                : { ok: false, error: result.error, kind: result.kind, ...(result.baseUrl ? { baseUrl: result.baseUrl } : {}) };
         },
         // Non-secret, and only ever a value the resolver just agreed with the
         // environment on (a conflicting BAPI_BASE_URL was refused above), so the
@@ -1114,7 +1166,7 @@ export function createDefaultDriveEpicDeps() {
             process.env.BAPI_BASE_URL = baseUrl;
         },
         readReadiness: (access) => fetchConductorReadiness(access, globalThis.fetch),
-        runSetupEpic: (argv) => runSetupEpicWorkflow(argv),
+        runSetupEpic: (argv, handoff) => runSetupEpicWorkflow(argv, {}, handoff),
         readEligibilityArtifact: (path) => readFile(path, "utf8"),
         runPlanePreflight: (repoRoot) => runDefaultPlanePreflight(repoRoot),
         runPlane: (argv, overrides) => runPlaneCli(argv, overrides ?? {}),
@@ -1167,7 +1219,7 @@ export function createDefaultDriveEpicDeps() {
         readPlanDag: (filePath) => readFile(filePath, "utf8"),
         readPolicyFile: (filePath) => readFile(filePath, "utf8"),
         readLiveEpicRun: (access, epicKey) => readLiveEpicRunByKey(access, epicKey),
-        previewSetupEpic: async ({ argv, baseUrl }) => {
+        previewSetupEpic: async ({ argv, baseUrl, handoff }) => {
             const stdout = [];
             const stderr = [];
             const result = await runSetupEpicWorkflow(argv, {
@@ -1176,7 +1228,7 @@ export function createDefaultDriveEpicDeps() {
                 env: { ...process.env, BAPI_BASE_URL: baseUrl },
                 log: (message) => stdout.push(message),
                 errorLog: (message) => stderr.push(message),
-            });
+            }, handoff);
             return { exitCode: result.exitCode, stdout, stderr };
         },
         // Read-only by construction: `prepareRunExecutor` runs `git rev-parse` and
@@ -1251,6 +1303,7 @@ export async function runDriveEpicCli(argv, overrides = {}) {
             options: parsed.options,
             access: accessResult.access,
             profile: launchProfile,
+            targetSource: accessResult.targetSource ?? "default",
         };
         // BAPI-1285 — with no `--plan-file`, look for the plan BEFORE readiness. A
         // discovered plan must count as a supplied one for the BAPI-1153 cold-start
@@ -1319,6 +1372,16 @@ export async function runDriveEpicCli(argv, overrides = {}) {
             }
             return escalate(deps, epicKey, `conductor readiness could not be read: ${safeDiagnosticMessage(err, "readiness request failed")}`);
         }
+        if (ctx.options.planFile !== undefined) {
+            const prepared = await prepareSetupSelection(ctx);
+            if (!prepared.ok) {
+                return refuse(deps, [
+                    `${epicKey}: REFUSED (${prepared.reasonId}) — the selected run or policy could not be verified.`,
+                    "Nothing was created or started.",
+                ]);
+            }
+            ctx = { ...ctx, handoff: prepared.handoff };
+        }
         // --- Route. Exactly one path from here on. -------------------------------
         const selection = selectConductor(readiness);
         // BAPI-1022: surface any containment-hazard advisory before dispatch or
@@ -1377,7 +1440,7 @@ export async function runDriveEpicCli(argv, overrides = {}) {
             const classification = classifyV2Readiness(readiness, {
                 attended: parsed.options.attended === true,
                 intoBase: parsed.options.intoBase === true,
-                hasPolicyFile: parsed.options.policyFile !== undefined,
+                effectivePolicy: ctx.handoff?.selection,
             });
             // Green: create the run, then make sure something will claim its jobs
             // (BAPI-1279). Before this, green delegated to setup-epic and nothing
@@ -1594,6 +1657,61 @@ function escalate(deps, epicKey, reason) {
     deps.errorLog(text);
     return 1;
 }
+/** Resolve policy intent once for the setup delegation, after a fresh run read. */
+async function prepareSetupSelection(ctx, coldStart = false) {
+    const live = coldStart ? { kind: "none" } : await ctx.deps.readLiveEpicRun(ctx.access, ctx.epicKey);
+    if (live.kind === "conflict")
+        return { ok: false, reasonId: "live-run-ambiguous" };
+    if (live.kind === "unknown")
+        return { ok: false, reasonId: "live-run-unknown" };
+    const explicit = ctx.options.policyFile;
+    const selectedPath = explicit ?? (live.kind === "none" ? ctx.profile?.policyRef?.path : undefined);
+    let pinnedPolicy;
+    let digest = null;
+    if (selectedPath !== undefined) {
+        let raw = "";
+        const read = await readSetupEpicPolicyFile(selectedPath, async (filePath) => {
+            raw = await ctx.deps.readPolicyFile(filePath);
+            return raw;
+        });
+        if (!read.ok)
+            return { ok: false, reasonId: "policy-file-unreadable" };
+        pinnedPolicy = read.policy;
+        digest = epicLaunchPolicyDigest(raw);
+    }
+    const policy = coldStart
+        ? { kind: "deferred_cold_preview", source: "deferred", digest: null }
+        : live.kind === "live"
+            ? explicit && digest
+                ? { kind: "explicit_replacement_request", source: "explicit", digest }
+                : { kind: "approved_stored", source: "stored", digest: null }
+            : { kind: "new_run", source: explicit ? "explicit" : selectedPath ? "profile" : "default", digest };
+    const selection = resolveEpicLaunchSelection({
+        baseUrl: ctx.access.baseUrl,
+        repoName: ctx.access.repoName,
+        targetSource: ctx.targetSource,
+        profile: ctx.profile,
+        topology: planeEndpointForBaseUrl(ctx.deps, ctx.access.baseUrl) ? "local_plane" : "remote",
+        policy,
+        escalationChannel: pinnedPolicy
+            ? policyDeclaresNotifyWebhook(pinnedPolicy) ? "configured webhook" : "account email"
+            : live.kind === "live" ? "unavailable" : "account email",
+    });
+    if (pinnedPolicy)
+        pinEpicLaunchPolicy(selection, pinnedPolicy);
+    return { ok: true, handoff: { selection, access: ctx.access, profile: ctx.profile } };
+}
+async function runSelectedSetupEpic(ctx) {
+    const prepared = ctx.handoff
+        ? { ok: true, handoff: ctx.handoff }
+        : await prepareSetupSelection(ctx);
+    if (!prepared.ok) {
+        ctx.deps.errorLog(`${ctx.epicKey}: REFUSED (${prepared.reasonId}) — the selected run or policy could not be verified.`);
+        return { exitCode: 1 };
+    }
+    const result = await ctx.deps.runSetupEpic(buildSetupEpicArgv(ctx.options), prepared.handoff);
+    return result;
+}
 /** Emit one refusal, guarded so it can never name a second conductor. */
 function refuse(deps, lines) {
     const text = lines.join("\n");
@@ -1601,6 +1719,11 @@ function refuse(deps, lines) {
     deps.errorLog(text);
     return 1;
 }
+function durableActorAdmissionDenied(readiness) {
+    const evidence = readiness.admission_evidence;
+    return evidence?.schema_version === 1 &&
+        evidence.records.some((record) => record.predicate === "durable_actor" && record.verdict === "denied");
+}
 /**
  * The plane endpoint, when `baseUrl` names it; otherwise `null`.
  *
@@ -1706,10 +1829,18 @@ async function coldStartPlane(ctx) {
             ...LAUNCHED_PLANE_LEFT_RUNNING,
         ]);
     }
+    const prepared = await prepareSetupSelection(ctx);
+    if (!prepared.ok) {
+        return refuse(deps, [
+            `${epicKey}: REFUSED (${prepared.reasonId}) — the selected run or policy could not be verified.`,
+            ...LAUNCHED_PLANE_LEFT_RUNNING,
+        ]);
+    }
+    ctx = { ...ctx, handoff: prepared.handoff };
     const classification = classifyV2Readiness(readiness, {
         attended: ctx.options.attended === true,
         intoBase: ctx.options.intoBase === true,
-        hasPolicyFile: ctx.options.policyFile !== undefined,
+        effectivePolicy: ctx.handoff?.selection,
     });
     if (classification.kind === "operator_blocked") {
         return refuse(deps, [
@@ -1755,6 +1886,12 @@ async function attachToPlane(ctx, manifest, readiness) {
             "Nothing was started. Fix the credential and run drive-epic again.",
         ]);
     }
+    if (rooted.access.repoName !== ctx.access.repoName || rooted.access.baseUrl !== ctx.access.baseUrl) {
+        return refuse(deps, [
+            `${epicKey}: REFUSED (selection-conflict) — manifest-root credentials resolved a different repository or endpoint.`,
+            "Nothing was started or changed.",
+        ]);
+    }
     const attachCtx = { ...ctx, access: rooted.access };
     // R-7, decided BEFORE any create request. It binds the LANES only
     // (BAPI-1279): a plane whose lanes serve another run still has a reconciler
@@ -1816,7 +1953,7 @@ async function createRunAndRequestLanes(ctx, plane) {
     const { deps, epicKey } = ctx;
     const launched = plane.origin === "launched";
     // ---- PHASE TWO, part one: create the run ------------------------------
-    const setup = await deps.runSetupEpic(buildSetupEpicArgv(ctx.options));
+    const setup = await runSelectedSetupEpic(ctx);
     if (setup.exitCode !== 0) {
         // The control plane is deliberately LEFT RUNNING, and NO EXECUTOR LANE
         // was spawned — there is nothing to claim a job that may not exist.
@@ -2107,11 +2244,17 @@ function liveRunUnknownRefusal(epicKey, reason) {
 async function createRunWithRunExecutor(ctx, readiness) {
     const { deps, epicKey, access, profile } = ctx;
     if (profile !== null && profile.executionMode === "durable") {
+        if (durableActorAdmissionDenied(readiness)) {
+            return refuse(deps, [
+                `${epicKey}: REFUSED (actor-admission-denied) — durable actor admission was denied at the selected target.`,
+                "No run was created and no local executor was started.",
+            ]);
+        }
         const coverage = readiness.executor.repo_wide_executor_live;
         if (coverage !== true) {
             return refuse(deps, durableCoverageRefusal(epicKey, access, profile, coverage, "No run was created").lines);
         }
-        const setup = await deps.runSetupEpic(buildSetupEpicArgv(ctx.options));
+        const setup = await runSelectedSetupEpic(ctx);
         if (setup.exitCode === 0) {
             deps.log([
                 "",
@@ -2126,7 +2269,7 @@ async function createRunWithRunExecutor(ctx, readiness) {
     if (!prepared.ok) {
         return refuse(deps, executorPreconditionRefusal(epicKey, prepared.message, "No run was created.").lines);
     }
-    const setup = await deps.runSetupEpic(buildSetupEpicArgv(ctx.options));
+    const setup = await runSelectedSetupEpic(ctx);
     if (setup.exitCode !== 0) {
         // setup-epic already said why. Nothing was started for a run that may not exist.
         deps.errorLog(`\n${epicKey}: no executor was started.`);
@@ -2164,6 +2307,11 @@ async function createRunWithRunExecutor(ctx, readiness) {
 function reportExecutorOutcome(ctx, ensured, epicRunId, framing) {
     const { deps, epicKey, access } = ctx;
     if (!ensured.ok) {
+        deps.log(JSON.stringify({
+            outcome: "run_exists_executor_unavailable",
+            epic_key: epicKey,
+            epic_run_id: epicRunId,
+        }));
         return refuse(deps, [
             "",
             framing === "created"
@@ -2213,6 +2361,9 @@ async function planeServesLiveRun(ctx, live) {
         const manifest = await findAttachablePlane(ctx);
         if (manifest === null || manifest.epicRunId !== live.epicRunId)
             return false;
+        const owner = await ctx.deps.readPlaneReconcilerState({ access: ctx.access, manifest });
+        if (owner !== "fresh")
+            return false;
         const bound = await ctx.deps.readRunState(ctx.access, manifest.epicRunId);
         return bound.epicKey === ctx.epicKey && !isTerminalEpicRunStatus(bound.status);
     }
@@ -2236,7 +2387,7 @@ async function attachToLiveRun(ctx, readiness, live) {
     const classification = classifyV2Readiness(readiness, {
         attended: ctx.options.attended === true,
         intoBase: ctx.options.intoBase === true,
-        hasPolicyFile: ctx.options.policyFile !== undefined,
+        approvedStoredPolicy: true,
     });
     if (classification.kind === "operator_blocked") {
         return refuse(deps, [
@@ -2252,9 +2403,28 @@ async function attachToLiveRun(ctx, readiness, live) {
             return refuseRemoteRuntime(ctx, readiness);
         return refuse(deps, localReconcilerRefusal(epicKey, readiness).lines);
     }
+    if (planeTarget) {
+        const manifest = await findAttachablePlane(ctx).catch(() => null);
+        if (manifest?.epicRunId === live.epicRunId) {
+            const admission = await checkPlaneAdmission(ctx, readiness, manifest);
+            if (admission !== null)
+                return refuse(deps, admission);
+        }
+    }
     deps.log(`${epicKey}: run ${live.epicRunId} is already live (${live.status}) and no plan was supplied or ` +
         "found, so nothing will be created; making sure it has an executor.");
+    if (live.effectivePolicy) {
+        deps.log(`Effective policy: stored; serial execution; caps ${live.effectivePolicy.caps ? JSON.stringify(live.effectivePolicy.caps) : "unavailable"}; ` +
+            `timeouts ${live.effectivePolicy.job_timeouts ? JSON.stringify(live.effectivePolicy.job_timeouts) : "unavailable"}; ` +
+            `channel ${live.effectivePolicy.escalation_channel}.`);
+    }
     if (profile !== null && profile.executionMode === "durable") {
+        if (durableActorAdmissionDenied(readiness)) {
+            return refuse(deps, [
+                `${epicKey}: REFUSED (actor-admission-denied) — durable actor admission was denied at the selected target.`,
+                "No run was changed and no local executor was started.",
+            ]);
+        }
         const coverage = readiness.executor.repo_wide_executor_live;
         if (coverage !== true) {
             return refuse(deps, durableCoverageRefusal(epicKey, access, profile, coverage, "No run was changed").lines);
@@ -2339,6 +2509,16 @@ function reportControlPlaneLaunchFailure(ctx, controlPlane) {
         "No run was created.",
     ]);
 }
+export const DRIVE_EPIC_ACCESS_REFUSAL_REASON_IDS = {
+    "profile-unusable": "access-profile-unusable",
+    "target-missing": "access-target-missing",
+    "target-conflict": "access-target-conflict",
+    "target-invalid": "access-target-invalid",
+    "repository-conflict": "access-repository-conflict",
+    "repo-missing": "access-repo-missing",
+    "credentials-unavailable": "access-credentials-unavailable",
+    "credential-unbound": "access-credential-unbound",
+};
 /** 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.";
@@ -2370,12 +2550,48 @@ function readSetupPreviewPayload(stdout) {
     if (existing !== null && existing !== undefined && typeof existing !== "string")
         return null;
     const branch = doc.feature_branch;
-    if (branch !== undefined && typeof branch !== "string")
+    if (branch !== undefined && branch !== null && typeof branch !== "string")
         return null;
+    const rawFacts = doc.effective_policy;
+    let effectivePolicy = null;
+    if (rawFacts !== undefined && rawFacts !== null) {
+        if (typeof rawFacts !== "object" || Array.isArray(rawFacts))
+            return null;
+        const facts = rawFacts;
+        if (!["explicit", "profile", "default", "stored"].includes(String(facts.source)) ||
+            facts.serial_execution !== "serial" ||
+            !["attended", "unattended"].includes(String(facts.posture)) ||
+            !["configured webhook", "account email", "unavailable"].includes(String(facts.escalation_channel)))
+            return null;
+        const numericMap = (value) => {
+            if (value === null)
+                return null;
+            if (!value || typeof value !== "object" || Array.isArray(value))
+                return undefined;
+            const entries = Object.entries(value);
+            if (entries.some(([key, number]) => !/^[a-z][a-z0-9_]{0,63}$/.test(key) ||
+                typeof number !== "number" || !Number.isFinite(number)))
+                return undefined;
+            return Object.fromEntries(entries);
+        };
+        const caps = numericMap(facts.caps);
+        const jobTimeouts = numericMap(facts.job_timeouts);
+        if (caps === undefined || jobTimeouts === undefined)
+            return null;
+        effectivePolicy = {
+            source: facts.source,
+            serial_execution: "serial",
+            posture: facts.posture,
+            caps,
+            job_timeouts: jobTimeouts,
+            escalation_channel: facts.escalation_channel,
+        };
+    }
     return {
         existingRunId: typeof existing === "string" && existing !== "" ? existing : null,
         featureBranch: typeof branch === "string" && branch !== "" ? branch : null,
         serverValidated: doc.server_validated,
+        effectivePolicy,
     };
 }
 /** The plan DAG's node count, or `null` unless it parses to `{ nodes: [...] }`. */
@@ -2452,62 +2668,135 @@ async function previewDecision(deps, options, preview, refuseWithReadiness, refu
     });
     // --- Target: resolved, never adopted. -------------------------------------
     const accessResult = await deps.resolveAccess(options.repo, undefined, launchSelectionOf(options));
-    if (!accessResult.ok)
-        return unknownReadiness();
+    if (!accessResult.ok) {
+        if (!accessResult.kind ||
+            !Object.prototype.hasOwnProperty.call(DRIVE_EPIC_ACCESS_REFUSAL_REASON_IDS, accessResult.kind))
+            return unknownReadiness();
+        unknownReadiness();
+        if (accessResult.baseUrl) {
+            preview.target = {
+                base_url: accessResult.baseUrl,
+                kind: planeEndpointForBaseUrl(deps, accessResult.baseUrl) !== null ? "local_plane" : "remote",
+            };
+        }
+        refuseTopLevel({
+            reasonId: DRIVE_EPIC_ACCESS_REFUSAL_REASON_IDS[accessResult.kind],
+            remedy: accessResult.error,
+        });
+        return;
+    }
     const access = accessResult.access;
     const profile = accessResult.profile ?? null;
-    const planeTarget = planeEndpointForBaseUrl(deps, access.baseUrl) !== null;
-    preview.target = { base_url: access.baseUrl, kind: planeTarget ? "local_plane" : "remote" };
-    const ctx = { deps, epicKey, options, access, profile };
+    const endpoint = planeEndpointForBaseUrl(deps, access.baseUrl);
+    const planeTarget = endpoint !== null;
+    preview.target = {
+        base_url: access.baseUrl,
+        kind: planeTarget ? "local_plane" : "remote",
+        ...(accessResult.targetSource === "profile" || accessResult.targetSource === "profile-env"
+            ? { source: accessResult.targetSource }
+            : {}),
+    };
+    const ctx = { deps, epicKey, options, access, profile, targetSource: accessResult.targetSource ?? "default" };
+    // Discover before readiness so a selected local plane can preview its guarded
+    // cold start. Keep the candidate out of ordinary failure documents.
+    let planPath = options.planFile;
+    let plan = { status: "not_found" };
+    let docsRootUnresolved = false;
+    if (planPath !== undefined) {
+        plan = { status: "supplied", path: planPath };
+    }
+    else {
+        const docs = await deps.resolveDocsDir();
+        if (!docs.ok) {
+            docsRootUnresolved = true;
+        }
+        else {
+            const discovered = await discoverEpicPlan(epicKey, docs.docsDir, deps.discoveryFs);
+            plan = {
+                status: discovered.status === "found" ? "found" : discovered.status === "plan_ambiguous" ? "ambiguous" : "not_found",
+                ...(discovered.status === "found" ? { path: discovered.path } : {}),
+                ...(discovered.status === "plan_ambiguous" ? { candidates: [...discovered.candidates] } : {}),
+                ...(discovered.skipped.length > 0
+                    ? { skipped: discovered.skipped.map((entry) => ({ path: entry.path, reason: entry.reason })) }
+                    : {}),
+                epic_plans_dir: discovered.epic_plans_dir,
+            };
+            if (discovered.status === "found")
+                planPath = discovered.path;
+        }
+    }
     // --- Readiness. -----------------------------------------------------------
     let readiness;
     try {
         readiness = await deps.readReadiness(access);
     }
-    catch {
+    catch (err) {
+        if (planPath !== undefined && endpoint !== null && profile?.executionMode !== "durable" &&
+            err instanceof ConductorBridgeApiError && err.kind === "network") {
+            const probe = await deps.probePlanePort(endpoint.host, endpoint.port).catch(() => ({ kind: "error" }));
+            if (probe.kind === "refused") {
+                const preflight = await deps.runPlanePreflight(deps.cwd());
+                const blocker = firstPreconditionRefusal(preflight) ??
+                    preflight.diagnostics.find((diagnostic) => diagnostic.severity === "blocking");
+                preview.plan = plan;
+                if (blocker) {
+                    return refuseTopLevel({
+                        reasonId: blocker.check,
+                        remedy: `The local plane preflight refused ${blocker.check}. Fix that condition and preview again.`,
+                    });
+                }
+                if (!preflight.ok) {
+                    return refuseTopLevel({
+                        reasonId: "plane-preflight-failed",
+                        remedy: "The local plane preflight could not admit guarded startup. Fix its reported condition and preview again.",
+                    });
+                }
+                preview.readiness = { kind: "cold_start" };
+                await finalizeCreatePreview(ctx, preview, planPath, true, refuseTopLevel);
+                if (preview.decision === "create") {
+                    preview.cold_start = { plane_endpoint: access.baseUrl, will_start_plane: true, live_run_checked: false };
+                }
+                return;
+            }
+        }
         return unknownReadiness();
     }
+    preview.plan = plan;
+    if (docsRootUnresolved)
+        return refuseTopLevel(docsRootRefusal(epicKey));
+    const live = await deps.readLiveEpicRun(access, epicKey);
+    if (live.kind === "conflict")
+        return refuseTopLevel(liveRunAmbiguousRefusal(epicKey));
+    if (live.kind === "unknown")
+        return refuseTopLevel(liveRunUnknownRefusal(epicKey, live.reason));
+    const previewCtx = { ...ctx, options: { ...options, ...(planPath ? { planFile: planPath } : {}) } };
+    const prepared = planPath ? await prepareSetupSelection(previewCtx) : null;
+    if (prepared !== null && !prepared.ok) {
+        return refuseTopLevel({
+            reasonId: prepared.reasonId,
+            remedy: "The selected run or policy could not be verified. Nothing was created or started.",
+        });
+    }
     const classification = classifyV2Readiness(readiness, {
         attended: options.attended === true,
         intoBase: options.intoBase === true,
-        hasPolicyFile: options.policyFile !== undefined,
+        effectivePolicy: prepared?.ok ? prepared.handoff.selection : undefined,
+        approvedStoredPolicy: live.kind === "live" && !planPath,
     });
     preview.readiness = { kind: classification.kind };
     const selection = selectConductor(readiness);
-    // --- The plan: supplied, or discovered. -----------------------------------
-    let planPath = options.planFile;
-    if (planPath !== undefined) {
-        preview.plan = { status: "supplied", path: planPath };
-    }
-    else {
-        const docs = await deps.resolveDocsDir();
-        if (!docs.ok)
-            return refuseTopLevel(docsRootRefusal(epicKey));
-        const discovered = await discoverEpicPlan(epicKey, docs.docsDir, deps.discoveryFs);
-        preview.plan = {
-            status: discovered.status === "found"
-                ? "found"
-                : discovered.status === "plan_ambiguous"
-                    ? "ambiguous"
-                    : "not_found",
-            ...(discovered.status === "found" ? { path: discovered.path } : {}),
-            ...(discovered.status === "plan_ambiguous" ? { candidates: [...discovered.candidates] } : {}),
-            ...(discovered.skipped.length > 0
-                ? { skipped: discovered.skipped.map((entry) => ({ path: entry.path, reason: entry.reason })) }
-                : {}),
-            epic_plans_dir: discovered.epic_plans_dir,
-        };
-        if (discovered.status === "found")
-            planPath = discovered.path;
-    }
     // --- The live run. Conflict and unknown refuse whatever the plan says. ------
-    const live = await deps.readLiveEpicRun(access, epicKey);
-    if (live.kind === "conflict")
-        return refuseTopLevel(liveRunAmbiguousRefusal(epicKey));
-    if (live.kind === "unknown")
-        return refuseTopLevel(liveRunUnknownRefusal(epicKey, live.reason));
     if (live.kind === "live") {
         preview.live_run = { epic_run_id: live.epicRunId, status: live.status };
+        if (live.effectivePolicy) {
+            preview.summary.policy_source = live.effectivePolicy.source;
+            preview.summary.serial_execution = live.effectivePolicy.serial_execution;
+            preview.summary.caps = live.effectivePolicy.caps;
+            preview.summary.job_timeouts = live.effectivePolicy.job_timeouts;
+            preview.summary.escalation_channel_label = live.effectivePolicy.escalation_channel;
+            preview.summary.posture = live.effectivePolicy.posture;
+            preview.summary.escalation_channel = null;
+        }
     }
     // --- No plan: attach to a live run, or stop. --------------------------------
     if (planPath === undefined) {
@@ -2537,31 +2826,32 @@ async function previewDecision(deps, options, preview, refuseWithReadiness, refu
     const facts = await previewExecutorFacts(ctx, readiness, planeTarget, null, "No run was created");
     if (facts !== null)
         return refuseWithReadiness(classification.kind, facts, true);
+    await finalizeCreatePreview(prepared?.ok ? { ...previewCtx, handoff: prepared.handoff } : previewCtx, preview, planPath, false, refuseTopLevel, live.kind === "live");
+}
+async function finalizeCreatePreview(ctx, preview, planPath, coldStart, refuseTopLevel, liveRunKnown = false) {
+    const { deps, options, access } = ctx;
+    const prepared = ctx.handoff
+        ? { ok: true, handoff: ctx.handoff }
+        : await prepareSetupSelection(ctx, coldStart);
+    if (!prepared.ok) {
+        return refuseTopLevel({
+            reasonId: prepared.reasonId,
+            remedy: "The selected run or policy could not be verified. Fix it and preview again.",
+        });
+    }
     // Escalation channel, decided with setup-epic's own exported policy helpers. A
     // policy that cannot be read is one fixed refusal; its path, contents, and any
     // webhook URL never leave this function.
     if (preview.summary.posture === "unattended") {
-        if (options.policyFile !== undefined) {
-            const policy = await readSetupEpicPolicyFile(options.policyFile, deps.readPolicyFile);
-            if (!policy.ok) {
-                return refuseTopLevel({
-                    reasonId: "policy-file-unreadable",
-                    remedy: "The --policy-file could not be read as a JSON object. Fix it or pass a different " +
-                        "file, then run the preview again.",
-                });
-            }
-            preview.summary.escalation_channel = policyDeclaresNotifyWebhook(policy.policy)
-                ? "webhook"
-                : "email";
-        }
-        else {
-            preview.summary.escalation_channel = "email";
-        }
+        preview.summary.escalation_channel = prepared.handoff.selection.escalationChannel === "configured webhook"
+            ? "webhook"
+            : prepared.handoff.selection.escalationChannel === "account email" ? "email" : null;
     }
     preview.summary.child_count = await readPlanChildCount(deps, planPath);
     const setup = await deps.previewSetupEpic({
-        argv: [...buildSetupEpicArgv({ ...options, planFile: planPath }), "--dry-run", "--json"],
+        argv: [...buildSetupEpicArgv({ ...options, planFile: planPath }), ...(coldStart ? ["--local-only"] : []), "--dry-run", "--json"],
         baseUrl: access.baseUrl,
+        handoff: prepared.handoff,
     });
     if (setup.exitCode !== 0) {
         preview.summary.server_validation = "failed";
@@ -2582,6 +2872,18 @@ async function previewDecision(deps, options, preview, refuseWithReadiness, refu
     }
     preview.summary.server_validation = payload.serverValidated ? "passed" : "partial";
     preview.summary.branch = payload.featureBranch;
+    if (payload.effectivePolicy) {
+        const facts = payload.effectivePolicy;
+        preview.summary.policy_source = facts.source;
+        preview.summary.serial_execution = facts.serial_execution;
+        preview.summary.caps = facts.caps;
+        preview.summary.job_timeouts = facts.job_timeouts;
+        preview.summary.escalation_channel_label = facts.escalation_channel;
+        if (!coldStart)
+            preview.summary.posture = facts.posture;
+        preview.summary.escalation_channel = facts.escalation_channel === "configured webhook"
+            ? "webhook" : facts.escalation_channel === "account email" ? "email" : null;
+    }
     preview.summary.auto_merge_scope =
         preview.summary.posture === "unattended" ? payload.featureBranch : null;
     // The bootstrap reusing a run IS an attach: it reports the run's id.
@@ -2593,7 +2895,7 @@ async function previewDecision(deps, options, preview, refuseWithReadiness, refu
         preview.decision = "attach";
         return;
     }
-    preview.decision = live.kind === "live" ? "attach" : "create";
+    preview.decision = coldStart ? "create" : liveRunKnown ? "attach" : "create";
 }
 /**
  * The readiness refusal a real launch would print, as a reason id and remedy, or
@@ -2623,6 +2925,12 @@ function previewReadinessRefusal(ctx, classification, readiness, planeTarget, pa
 async function previewExecutorFacts(ctx, readiness, planeTarget, live, outcome) {
     const { deps, epicKey, access, profile } = ctx;
     if (profile !== null && profile.executionMode === "durable") {
+        if (durableActorAdmissionDenied(readiness)) {
+            return {
+                reasonId: "actor-admission-denied",
+                remedy: "Durable actor admission was denied at the selected target. No run was created and no local executor was started.",
+            };
+        }
         const coverage = readiness.executor.repo_wide_executor_live;
         return coverage === true
             ? null
@@ -2630,6 +2938,13 @@ async function previewExecutorFacts(ctx, readiness, planeTarget, live, outcome)
     }
     if (planeTarget) {
         if (live !== null) {
+            const manifest = await findAttachablePlane(ctx).catch(() => null);
+            if (manifest?.epicRunId === live.epicRunId) {
+                const admission = await checkPlaneAdmission(ctx, readiness, manifest);
+                if (admission !== null) {
+                    return { reasonId: "plane-reconciler-unconfirmed", remedy: admission.slice(1).join(" ") };
+                }
+            }
             if (await planeServesLiveRun(ctx, live))
                 return null;
         }
@@ -2650,11 +2965,12 @@ function emitPreview(deps, options, preview) {
     }
     const lines = [
         `${preview.epic_key}: launch preview (read-only; nothing was created or started)`,
+        ...(preview.cold_start ? ["  Decision:   conditional create — drive-epic will attempt guarded startup, recheck the live run, and create only if still appropriate."] : []),
         `  Target:     ${preview.target.base_url ?? "unresolved"}${preview.target.kind ? ` (${preview.target.kind})` : ""}`,
         `  Readiness:  ${preview.readiness.kind}${preview.readiness.reason_id ? ` (${preview.readiness.reason_id})` : ""}`,
         `  Live run:   ${preview.live_run
             ? `${preview.live_run.epic_run_id}${preview.live_run.status ? ` (${preview.live_run.status})` : ""}`
-            : "none"}`,
+            : preview.cold_start ? "unchecked (plane not yet running)" : "none"}`,
         `  Plan:       ${preview.plan.status}${preview.plan.path ? ` — ${preview.plan.path}` : ""}`,
     ];
     for (const candidate of preview.plan.candidates ?? [])
@@ -2663,9 +2979,10 @@ function emitPreview(deps, options, preview) {
         lines.push(`              skipped:   ${skipped.path} (${skipped.reason})`);
     }
     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: ${s.server_validation ?? "n/a"}`, `  Decision:   ${preview.decision}`);
-    if (preview.readiness.remedy)
+    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-")) {
         lines.push(`  Remedy:     ${preview.readiness.remedy}`);
+    }
     if (preview.refusal) {
         lines.push(`  Refusal:    ${preview.refusal.reason_id} — ${preview.refusal.remedy}`);
     }