@bridge_gpt/mcp-server 0.2.69 → 0.2.70

package/build/plane/schema-compatibility.js

@@ -0,0 +1,137 @@
+/**
+ * Launch schema compatibility check for `plane up` (BAPI-1455).
+ *
+ * The migration-head check compares only the Alembic stamp. A local database can
+ * be stamped at head while a migration's DDL is missing (a colliding WIP revision
+ * applied, then a later `alembic stamp` skipping the real one); it passes that
+ * check and then fails the first launch read with `UndefinedColumn`.
+ *
+ * This check asks the ONE shared Python evaluation
+ * (`api/library/epic_implementer/schema_compatibility.py`, through
+ * `scripts/check_local_launch_schema.py --json`) whether the launch-critical
+ * objects exist. The object list lives only there. The script runs from the
+ * plane's pinned snapshot with the operator's interpreter, the same way
+ * {@link checkAlembicHead} runs Alembic.
+ *
+ * Like the migration-head check it is asymmetric: it **blocks only on a proven
+ * incompatibility** (the read succeeded and a listed object is missing). Every
+ * other outcome — the check could not reach the database, timed out, the
+ * subprocess failed, or its output was unreadable — is a named warning and
+ * startup continues. The check is read-only; it never migrates or stamps.
+ */
+import { planeCheckFinding, planeCheckPassed } from "./types.js";
+/** The script path, relative to the code root it runs from. Argument arrays only. */
+export const PLANE_SCHEMA_CHECK_SCRIPT = "scripts/check_local_launch_schema.py";
+/** Whole-subprocess bound: interpreter start, imports, connection, and query. */
+export const PLANE_SCHEMA_CHECK_TIMEOUT_MS = 20_000;
+/** Fixed prefix of the fail-open warning, so tests and greps can match it. */
+export const PLANE_SCHEMA_UNVERIFIED_PREFIX = "Schema compatibility could not be verified";
+/** Fixed heading of the blocking refusal. */
+export const PLANE_SCHEMA_REFUSAL_HEADING = "Local schema incompatible";
+/**
+ * The safe repair route. Never `alembic stamp` and never a downgrade: a stamp
+ * records bookkeeping and cannot restore missing DDL.
+ */
+export const PLANE_SCHEMA_REPAIR_ROUTE = "write a reviewed, forward-only Alembic migration that restores the missing objects, " +
+    "or rebuild the local database only with the owner's explicit consent.";
+/** Structured fix for an unverifiable schema. Never blocking. */
+export const PLANE_SCHEMA_UNVERIFIED_REMEDIATION = `run \`python ${PLANE_SCHEMA_CHECK_SCRIPT}\` by hand to see the result; startup continues under existing behavior.`;
+/** The closed reasons the Python check reports for `unknown`. */
+const UNKNOWN_REASONS = new Set(["unreachable", "timeout", "query_error"]);
+/** A missing-object name from the maintained list: identifiers, dots, and the constraint suffix only. */
+const OBJECT_NAME_RE = /^[a-z_][a-z0-9_.]*( \(check constraint on [a-z_][a-z0-9_.]*\))?$/;
+const STAMP_RE = /^[0-9A-Za-z_]{1,32}(,[0-9A-Za-z_]{1,32}){0,7}$/;
+const MAX_MISSING = 64;
+/**
+ * Validate the script's JSON. Only the LAST non-empty stdout line is read, so a
+ * library that prints a banner cannot break the result. Anything outside the
+ * closed shape returns null — never a guessed refusal.
+ */
+export function parseSchemaCheckOutput(stdout) {
+    const lines = stdout.split(/\r?\n/).map((l) => l.trim()).filter((l) => l.length > 0);
+    const last = lines[lines.length - 1];
+    if (!last)
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(last);
+    }
+    catch {
+        return null;
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+        return null;
+    const r = parsed;
+    const status = r["status"];
+    if (status !== "compatible" && status !== "incompatible" && status !== "unknown")
+        return null;
+    const missingRaw = r["missing"];
+    if (!Array.isArray(missingRaw) || missingRaw.length > MAX_MISSING)
+        return null;
+    const missing = [];
+    for (const m of missingRaw) {
+        if (typeof m !== "string" || m.length > 200 || !OBJECT_NAME_RE.test(m))
+            return null;
+        missing.push(m);
+    }
+    const reasonRaw = r["reason"];
+    const reason = typeof reasonRaw === "string" && UNKNOWN_REASONS.has(reasonRaw) ? reasonRaw : null;
+    const stampRaw = r["stamp"];
+    const stamp = typeof stampRaw === "string" && STAMP_RE.test(stampRaw) ? stampRaw : null;
+    if (status === "incompatible" && missing.length === 0)
+        return null;
+    if (status !== "incompatible" && missing.length > 0)
+        return null;
+    return { status, missing, reason, stamp };
+}
+/** The operator-facing refusal text. Names come only from the maintained list. */
+export function formatSchemaRefusal(stamp, missing) {
+    return [
+        `${PLANE_SCHEMA_REFUSAL_HEADING} — plane up did not start; nothing was claimed or spawned.`,
+        `  applied migration stamp: ${stamp ?? "applied stamp unavailable"} (a stamp is not proof that its DDL exists)`,
+        "  missing launch-critical objects:",
+        ...missing.map((m) => `    - ${m}`),
+        `  repair: ${PLANE_SCHEMA_REPAIR_ROUTE}`,
+    ].join("\n");
+}
+/**
+ * Run the shared Python schema check. Blocks only on a proven incompatibility.
+ *
+ * `python` is the operator's interpreter (resolved by the caller exactly as the
+ * Python members are); `codeRoot` is the pinned snapshot the script runs from.
+ */
+export async function checkSchemaCompatibility(python, codeRoot, deps) {
+    const run = await deps.execFile(python, [PLANE_SCHEMA_CHECK_SCRIPT, "--json"], {
+        cwd: codeRoot,
+        timeoutMs: PLANE_SCHEMA_CHECK_TIMEOUT_MS,
+    });
+    // Captured subprocess text is never displayed: only fixed prose and closed
+    // reasons reach a report.
+    if (!run.ok)
+        return unverified("the schema check did not complete");
+    const parsed = parseSchemaCheckOutput(run.stdout);
+    if (parsed === null)
+        return unverified("the schema check output was not readable");
+    if (parsed.status === "unknown")
+        return unverified(`the check could not run (${parsed.reason ?? "query_error"})`);
+    if (parsed.status === "compatible") {
+        return planeCheckPassed("launch-schema", SCHEMA_CHECK_LABEL, "every launch-critical schema object exists");
+    }
+    return planeCheckFinding({
+        check: "launch-schema",
+        severity: "blocking",
+        message: formatSchemaRefusal(parsed.stamp, parsed.missing),
+        remediation: PLANE_SCHEMA_REPAIR_ROUTE,
+    }, SCHEMA_CHECK_LABEL, `missing [${parsed.missing.join(", ")}] at stamp ${parsed.stamp ?? "unavailable"}`);
+}
+/** Human-readable name for the launch schema prerequisite. */
+const SCHEMA_CHECK_LABEL = "Launch-critical schema";
+function unverified(detail) {
+    const diagnostic = {
+        check: "launch-schema",
+        severity: "warning",
+        message: `${PLANE_SCHEMA_UNVERIFIED_PREFIX}: ${detail}. Startup continues under existing behavior.`,
+        remediation: PLANE_SCHEMA_UNVERIFIED_REMEDIATION,
+    };
+    return planeCheckFinding(diagnostic, SCHEMA_CHECK_LABEL, `${PLANE_SCHEMA_UNVERIFIED_PREFIX}: ${detail}`);
+}

package/build/plane/shutdown-deps.js

@@ -0,0 +1,38 @@
+import { releaseCodeSnapshotForManifest } from "./code-snapshot.js";
+import { createCodeSnapshotDeps, createPlaneClock, createPlaneExecFile, createPlaneFsDeps, createPlaneProcessDeps, } from "./defaults.js";
+import { resolvePlaneServerEndpoint } from "./member-roster.js";
+import { baseUrlNamesPlaneEndpoint } from "./endpoint.js";
+import { listRunExecutorRecords, verifyRunExecutorProcess } from "../executor-launch.js";
+/**
+ * Build the production `shutdownPlane` dependencies.
+ *
+ * The run-scoped executors are attributed to this plane by the same rule
+ * `plane up` binds by — a recorded base URL naming the plane's loopback port —
+ * and verified through the executor's own process check, so this is the single
+ * definition of "an executor this wind-down may signal".
+ */
+export function buildPlaneTeardownDeps(options) {
+    const { repoRoot } = options;
+    const fs = createPlaneFsDeps();
+    const proc = createPlaneProcessDeps();
+    const execFile = createPlaneExecFile();
+    const endpoint = resolvePlaneServerEndpoint(options.env);
+    const snapshotDeps = createCodeSnapshotDeps(proc);
+    return {
+        fs,
+        proc,
+        clock: createPlaneClock(),
+        // BAPI-1362 — unlock the pinned snapshot, but only once this wind-down has
+        // confirmed every process gone and cleared the manifest. It stays on disk.
+        releaseSnapshot: (manifest) => releaseCodeSnapshotForManifest(manifest, snapshotDeps),
+        stopBoundRun: options.stopBoundRun,
+        // BAPI-1279 — stop the run-scoped executors drive-epic started here that
+        // target THIS plane's endpoint (the same rule `plane up` binds by).
+        runExecutors: {
+            list: () => listRunExecutorRecords(repoRoot, fs),
+            targetsThisPlane: (baseUrl) => endpoint.ok && baseUrlNamesPlaneEndpoint(baseUrl, endpoint.endpoint),
+            verify: (record) => verifyRunExecutorProcess(record, { isAlive: proc.isAlive, execFile }, repoRoot),
+        },
+        ...(options.ownershipGuard !== undefined ? { ownershipGuard: options.ownershipGuard } : {}),
+    };
+}

package/build/plane/shutdown.js

@@ -96,6 +96,12 @@ export async function shutdownPlane(repoRoot, deps) {
             "the rest of the process group, but are not reported individually below. The manifest " +
             "was written by a NEWER build.");
     }
+    // BAPI-1496 — the first ownership checkpoint, before the bound-run stop and
+    // the run-scoped executors: an abort here has stopped and signalled nothing.
+    const firstGuard = await consultOwnershipGuard(deps, manifest, "before-run-stop");
+    if (firstGuard !== null) {
+        return ownershipAborted(firstGuard, "before-run-stop", { kind: "unbound" });
+    }
     // BAPI-872: the server-side run stop, computed ONCE right after the manifest
     // has passed every validation and identity check above — strictly before the
     // first process-group signal in every branch that sends one (the sole branch
@@ -113,6 +119,12 @@ export async function shutdownPlane(repoRoot, deps) {
     // BAPI-1279 — the run-scoped executors that target this plane go first, while
     // its server can still take their final job reports.
     messages.push(...(await stopRunScopedExecutors(deps)));
+    // BAPI-1496 — the second checkpoint, after the awaited work above and
+    // immediately before the members are signalled or the manifest is cleared.
+    const secondGuard = await consultOwnershipGuard(deps, manifest, "before-members");
+    if (secondGuard !== null) {
+        return ownershipAborted(secondGuard, "before-members", runShutdown);
+    }
     if (!isAnythingAlive(manifest, deps.proc, deps.selfPid)) {
         const cleared = await clearPlaneManifest(repoRoot, manifest.planeId, deps.fs);
         if (!cleared.ok) {
@@ -180,6 +192,71 @@ export async function shutdownPlane(repoRoot, deps) {
         runShutdown,
     };
 }
+/**
+ * Ask the ownership guard, if any. Returns the abort message, or `null` to
+ * proceed. A throwing guard is an abort with fixed wording.
+ */
+async function consultOwnershipGuard(deps, manifest, phase) {
+    if (deps.ownershipGuard === undefined)
+        return null;
+    try {
+        const verdict = await deps.ownershipGuard(manifest, phase);
+        return verdict.kind === "proceed" ? null : verdict.message;
+    }
+    catch {
+        return "the plane's ownership could not be confirmed";
+    }
+}
+function ownershipAborted(message, phase, runShutdown) {
+    return {
+        ok: false,
+        reason: "ownership-aborted",
+        message: `${message}. ` +
+            (phase === "before-run-stop"
+                ? "No run was stopped and no process was signalled."
+                : "No plane member was signalled.") +
+            " The manifest was RETAINED.",
+        members: [],
+        runShutdown,
+        ownershipPhase: phase,
+    };
+}
+/**
+ * The run-scoped executors that target this plane, each with its verified
+ * process state (BAPI-1496).
+ *
+ * The SAME attribution (`targetsThisPlane`) and liveness (`verify`) rules
+ * {@link stopRunScopedExecutors} signals by, exported as a read-only leaf so a
+ * caller deciding whether a plane is safe to wind down asks exactly the question
+ * the wind-down will act on. Never signals. `ok: false` when the registry could
+ * not be read; malformed records are returned by name, since they cannot be
+ * attributed to a plane at all.
+ */
+export async function inspectPlaneRunExecutors(runExecutors) {
+    let listed;
+    try {
+        listed = await runExecutors.list();
+    }
+    catch {
+        return { ok: false };
+    }
+    const targeting = [];
+    for (const record of listed.records) {
+        if (!runExecutors.targetsThisPlane(record.baseUrl))
+            continue;
+        targeting.push({ record, state: await verifyRunExecutorSafely(runExecutors, record) });
+    }
+    return { ok: true, targeting, malformed: listed.malformed };
+}
+/** `verify`, with a throw settled as `unknown` — never a signal target. */
+async function verifyRunExecutorSafely(runExecutors, record) {
+    try {
+        return await runExecutors.verify(record);
+    }
+    catch {
+        return "unknown";
+    }
+}
 /**
  * Run the snapshot release for a manifest whose plane is confirmed gone, and say
  * what happened (BAPI-1362). Returns message lines; never throws.
@@ -235,13 +312,7 @@ async function stopRunScopedExecutors(deps) {
             skipped.push(`run ${record.epicRunId} (targets ${record.baseUrl}, not this plane)`);
             continue;
         }
-        let state;
-        try {
-            state = await runExecutors.verify(record);
-        }
-        catch {
-            state = "unknown";
-        }
+        const state = await verifyRunExecutorSafely(runExecutors, record);
         if (state === "dead")
             continue;
         if (state !== "verified") {
@@ -360,7 +431,11 @@ function formatRunShutdown(outcome) {
  */
 export function formatPlaneShutdown(result) {
     const lines = [];
-    const skipRunSection = !result.ok && result.reason === "unvalidated-manifest";
+    // An ownership abort before the run stop attempted no stop, so nothing is
+    // claimed about the run either (BAPI-1496).
+    const skipRunSection = !result.ok &&
+        (result.reason === "unvalidated-manifest" ||
+            (result.reason === "ownership-aborted" && result.ownershipPhase === "before-run-stop"));
     if (!skipRunSection) {
         lines.push(...formatRunShutdown(result.runShutdown));
         lines.push("");

package/build/plane/terminal-run-cleanup.js

@@ -0,0 +1,303 @@
+/**
+ * Terminal-run plane cleanup (BAPI-1496).
+ *
+ * A plane bound to an epic run outlives the run: when the run reaches `done` or
+ * `abandoned`, nothing winds the plane down, and the next local launch then
+ * finds a live plane in its way (`existing-plane`) or attaches to a plane still
+ * running the finished run's pinned code. This module lets a local launch tear
+ * such a plane down first — but ONLY a plane positively attributed to a finished
+ * run, which no other live run depends on.
+ *
+ * Every eligibility fact must be POSITIVELY confirmed. Anything that cannot be
+ * read, does not parse, or disagrees makes the plane `ineligible`, and an
+ * ineligible plane is left exactly as it was, silently: the launch's ordinary
+ * preflight and attach behavior then apply unchanged, with their own wording.
+ *
+ * The teardown itself is the ordinary `shutdownPlane`, built through the shared
+ * dependency builder, with two differences:
+ *   - the bound-run stop returns the already-confirmed terminal outcome. It never
+ *     calls the run-stop endpoint: a finished run has nothing to stop.
+ *   - an ownership guard re-reads the manifest and re-checks the executor
+ *     registry before anything is signalled, so a plane that changed hands (or
+ *     gained a dependent run) after eligibility was decided is never touched.
+ *
+ * There is no retry loop. A failure is reported once, as one secret-free line
+ * naming the next safe action, and the manifest is kept for it.
+ */
+import path from "path";
+import { inspectPlaneRunExecutors, shutdownPlane, } from "./shutdown.js";
+import { buildPlaneTeardownDeps } from "./shutdown-deps.js";
+import { baseUrlNamesPlaneEndpoint } from "./endpoint.js";
+/** A run id is rendered only when it has a plain, bounded identifier shape. */
+const RENDERABLE_RUN_ID = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
+/** The production dependencies. Credential and network modules load lazily. */
+export function createTerminalRunCleanupDeps(env = process.env) {
+    return {
+        readPlaneManifest: async (repoRoot) => {
+            const { readPlaneManifest } = await import("./manifest.js");
+            const { createPlaneFsDeps } = await import("./defaults.js");
+            return readPlaneManifest(repoRoot, createPlaneFsDeps());
+        },
+        canonicalPath: async (filePath) => {
+            try {
+                const { realpath } = await import("fs/promises");
+                return await realpath(filePath);
+            }
+            catch {
+                return null;
+            }
+        },
+        resolveAccess: async (repoRoot) => {
+            try {
+                const { resolveConductorBridgeApiAccess } = await import("../conductor/bridge-api-client.js");
+                return await resolveConductorBridgeApiAccess({ env, cwd: repoRoot });
+            }
+            catch {
+                return { ok: false, kind: "credentials-unavailable", error: "access could not be resolved" };
+            }
+        },
+        resolveRepoName: async (repoRoot) => {
+            try {
+                const { resolveStartTicketsRepoName } = await import("../start-tickets-repo.js");
+                const { readFile } = await import("fs/promises");
+                return await resolveStartTicketsRepoName({
+                    env,
+                    cwd: repoRoot,
+                    readFile: (filePath) => readFile(filePath, "utf-8"),
+                });
+            }
+            catch {
+                return null;
+            }
+        },
+        readRunState: async (access, epicRunId) => {
+            try {
+                const { readEpicRunCompletionState } = await import("../conductor/bridge-api-client.js");
+                return await readEpicRunCompletionState(access, epicRunId);
+            }
+            catch {
+                return { ok: false, reason: "network" };
+            }
+        },
+        listLiveRunIds: async (access) => {
+            try {
+                const { listNonTerminalEpicRunIds } = await import("../conductor/bridge-api-client.js");
+                return await listNonTerminalEpicRunIds(access);
+            }
+            catch {
+                return null;
+            }
+        },
+        buildTeardownDeps: ({ repoRoot, stopBoundRun, ownershipGuard }) => buildPlaneTeardownDeps({ repoRoot, env, stopBoundRun, ownershipGuard }),
+        shutdownPlane,
+    };
+}
+/**
+ * Tear down this checkout's plane when, and only when, it is bound to a run
+ * the server positively reports as `done` or `abandoned`, the server holds no
+ * other non-terminal run, and no other run has a live executor on it.
+ *
+ * Never throws. Idempotent: once a cleanup has completed, the manifest is gone
+ * and a second call is a `no_op`.
+ */
+export async function cleanupTerminalRunPlane(input, overrides = {}) {
+    const deps = { ...createTerminalRunCleanupDeps(), ...overrides };
+    let read;
+    try {
+        read = await deps.readPlaneManifest(input.repoRoot);
+    }
+    catch {
+        return { kind: "ineligible", reason: "manifest-unvalidated" };
+    }
+    if (read.kind === "missing")
+        return { kind: "no_op" };
+    if (read.kind !== "valid")
+        return { kind: "ineligible", reason: "manifest-unvalidated" };
+    const manifest = read.manifest;
+    const epicRunId = manifest.epicRunId;
+    if (epicRunId === undefined || epicRunId.length === 0) {
+        return { kind: "ineligible", reason: "unbound" };
+    }
+    const ownership = await confirmOwnership(manifest, input, deps);
+    if (!ownership.ok)
+        return { kind: "ineligible", reason: ownership.reason };
+    let runState;
+    try {
+        runState = await deps.readRunState(ownership.access, epicRunId);
+    }
+    catch {
+        return { kind: "ineligible", reason: "status-unavailable" };
+    }
+    if (!runState.ok)
+        return { kind: "ineligible", reason: "status-unavailable" };
+    // Only the statuses after which nothing more will happen (the set `wait-run`
+    // uses). Every other status, known or not, leaves the plane alone.
+    const status = runState.state.status;
+    if (status !== "done" && status !== "abandoned") {
+        return { kind: "ineligible", reason: "not-terminal" };
+    }
+    // The executor registry below is this checkout's only. A run launched from a
+    // sibling worktree can ride on this plane with its executor recorded in THAT
+    // worktree, so the plane's own server is asked as well.
+    const served = await otherServedRun(deps, ownership.access, epicRunId);
+    if (served !== null)
+        return { kind: "ineligible", reason: served };
+    // The status was confirmed above; the wind-down reports it rather than asking
+    // the server to stop a run that has already finished.
+    const confirmedTerminal = { kind: "terminal", epicRunId, status };
+    const stopBoundRun = async () => confirmedTerminal;
+    // Assigned below, before `shutdownPlane` can consult the guard.
+    let teardownDeps = null;
+    const ownershipGuard = async () => {
+        const reread = await deps.readPlaneManifest(input.repoRoot);
+        if (reread.kind !== "valid" ||
+            reread.manifest.planeId !== manifest.planeId ||
+            reread.manifest.epicRunId !== epicRunId) {
+            return { kind: "abort", message: "the plane manifest changed after cleanup was decided" };
+        }
+        const again = await confirmOwnership(reread.manifest, input, deps);
+        if (!again.ok || again.access.repoName !== ownership.access.repoName) {
+            return { kind: "abort", message: "the plane's repository or endpoint could not be re-confirmed" };
+        }
+        if (teardownDeps === null ||
+            (await otherServedRun(deps, again.access, epicRunId)) !== null ||
+            (await otherRunDependency(teardownDeps, epicRunId)) !== null) {
+            return { kind: "abort", message: "another run may now depend on this plane" };
+        }
+        return { kind: "proceed" };
+    };
+    try {
+        teardownDeps = deps.buildTeardownDeps({ repoRoot: input.repoRoot, stopBoundRun, ownershipGuard });
+    }
+    catch {
+        return { kind: "ineligible", reason: "executor-registry-unreadable" };
+    }
+    const dependency = await otherRunDependency(teardownDeps, epicRunId);
+    if (dependency !== null)
+        return { kind: "ineligible", reason: dependency };
+    let result;
+    try {
+        result = await deps.shutdownPlane(input.repoRoot, teardownDeps);
+    }
+    catch {
+        return incomplete(epicRunId, manifest.planeId, "the wind-down failed unexpectedly");
+    }
+    if (result.ok) {
+        return { kind: "completed", epicRunId, planeId: manifest.planeId, status };
+    }
+    if (result.reason === "ownership-aborted") {
+        return {
+            kind: "ownership_aborted",
+            epicRunId,
+            planeId: manifest.planeId,
+            message: `plane cleanup for finished ${runLabel(epicRunId)} stopped before signalling the plane: ` +
+                "its ownership changed or could not be confirmed. The manifest was kept; inspect it " +
+                "with `plane status` before winding it down.",
+        };
+    }
+    return incomplete(epicRunId, manifest.planeId, result.reason === "survivors"
+        ? "some plane processes could not be confirmed stopped"
+        : result.reason === "clear-failed"
+            ? "the plane manifest could not be cleared"
+            : "the plane manifest could not be validated");
+}
+/**
+ * Is this manifest this checkout's plane, served on the selected endpoint, for
+ * the same repository Bridge access resolves to? Read-only.
+ */
+async function confirmOwnership(manifest, input, deps) {
+    if (!(await samePath(manifest.repoRoot, input.repoRoot, deps))) {
+        return { ok: false, reason: "repo-mismatch" };
+    }
+    let accessResult;
+    try {
+        accessResult = await deps.resolveAccess(manifest.repoRoot);
+    }
+    catch {
+        return { ok: false, reason: "access-unavailable" };
+    }
+    if (!accessResult.ok)
+        return { ok: false, reason: "access-unavailable" };
+    const access = accessResult.access;
+    // The manifest records no endpoint of its own: the plane in this checkout is
+    // the one serving the endpoint this launch resolved. So the run can only be
+    // read from THIS plane when the manifest-root access names that endpoint.
+    if (!baseUrlNamesPlaneEndpoint(access.baseUrl, input.endpoint)) {
+        return { ok: false, reason: "access-endpoint-mismatch" };
+    }
+    let repoName;
+    try {
+        repoName = await deps.resolveRepoName(input.repoRoot);
+    }
+    catch {
+        repoName = null;
+    }
+    if (repoName === null || repoName !== access.repoName) {
+        return { ok: false, reason: "access-repo-mismatch" };
+    }
+    return { ok: true, access };
+}
+/** Do two paths name the same directory? Unresolvable paths never match. */
+async function samePath(a, b, deps) {
+    let ca;
+    let cb;
+    try {
+        [ca, cb] = await Promise.all([deps.canonicalPath(a), deps.canonicalPath(b)]);
+    }
+    catch {
+        return false;
+    }
+    if (ca === null || cb === null)
+        return false;
+    return path.resolve(ca) === path.resolve(cb);
+}
+/**
+ * Why another run may depend on this plane, or `null` when none can: no OTHER
+ * run has an executor on this plane that may be alive, and the registry was read
+ * cleanly. Uses the wind-down's own attribution and verification, so the
+ * question asked here is the one the wind-down will act on.
+ *
+ * Conservative on purpose: an executor whose process cannot be verified either
+ * way, or a record that cannot be attributed at all, counts as a dependent.
+ */
+async function otherRunDependency(teardownDeps, epicRunId) {
+    if (teardownDeps.runExecutors === undefined)
+        return "executor-registry-unreadable";
+    const inspected = await inspectPlaneRunExecutors(teardownDeps.runExecutors);
+    if (!inspected.ok || inspected.malformed.length > 0)
+        return "executor-registry-unreadable";
+    const shared = inspected.targeting.some(({ record, state }) => record.epicRunId !== epicRunId && (state === "verified" || state === "unknown"));
+    return shared ? "shared-with-live-run" : null;
+}
+/**
+ * Why the plane's server may still serve another run, or `null` when it
+ * positively holds no non-terminal run but the bound one.
+ */
+async function otherServedRun(deps, access, epicRunId) {
+    let ids;
+    try {
+        ids = await deps.listLiveRunIds(access);
+    }
+    catch {
+        ids = null;
+    }
+    if (ids === null)
+        return "live-runs-unconfirmed";
+    return ids.some((id) => id !== epicRunId) ? "shared-with-live-run" : null;
+}
+function incomplete(epicRunId, planeId, cause) {
+    return {
+        kind: "incomplete",
+        epicRunId,
+        planeId,
+        message: `plane cleanup for finished ${runLabel(epicRunId)} was incomplete: ${cause}. The manifest ` +
+            "was kept; inspect the plane with `plane status` before winding it down by hand.",
+    };
+}
+function runLabel(epicRunId) {
+    return RENDERABLE_RUN_ID.test(epicRunId) ? `run ${epicRunId}` : "run";
+}
+/** Exported for callers that render a cleanup outcome: the stderr line, or `null` when silent. */
+export function terminalRunCleanupStderrLine(result) {
+    return result.kind === "incomplete" || result.kind === "ownership_aborted" ? result.message : null;
+}

package/build/printed-remedy-commands.js

@@ -11,6 +11,7 @@
  * mirrored contract (`conductor/merge-execution-contract.ts`).
  */
 import { MCP_PACKAGE_NAME } from "./mcp-identity.js";
+import { EPIC_IMPLEMENTER_CI_CHECK_NAME } from "./epic-ci-workflow.js";
 /** The non-interactive launcher every printed command starts with. */
 const LAUNCHER = `npx -y ${MCP_PACKAGE_NAME}`;
 /** The top-level subcommand tokens `index.ts` dispatches that remedies name. */
@@ -23,21 +24,28 @@ export const PRINTED_REMEDY_DISPATCHED_SUBCOMMANDS = [
 ];
 /** The guided installer (interactive project setup). */
 export const PRINTED_INSTALL_COMMAND = `${LAUNCHER} install`;
+/** Where the installer copies the customer getting-started guide in a consumer project. */
+export const CONSUMER_GUIDE_PATH = "docs/install/epic-implementer-install.md";
+/**
+ * The one documentation pointer customer-facing remedies use: the guide's
+ * consumer path plus the command that writes or refreshes it. A path alone is
+ * not enough, because an older install may not have the file yet.
+ */
+export const CONSUMER_GUIDE_POINTER = `${CONSUMER_GUIDE_PATH} (write or refresh it with ${PRINTED_INSTALL_COMMAND})`;
 /**
  * Conductor bootstrap with an explicit provider check. Since BAPI-1391 a
  * confirmed gate (provider, local, mixed, or none) replaces the old "at least
  * one --required-check" rule; a provider check is still the common scripted form.
  */
-export const PRINTED_CONDUCTOR_INSTALL_COMMAND = `${LAUNCHER} install conductor --required-check <check-name>`;
+export const PRINTED_CONDUCTOR_INSTALL_COMMAND = `${LAUNCHER} install conductor --required-check "${EPIC_IMPLEMENTER_CI_CHECK_NAME}"`;
 /** Conductor bootstrap that also provisions a repository-wide executor service. */
-export const PRINTED_CONDUCTOR_EXECUTOR_INSTALL_COMMAND = `${LAUNCHER} install conductor --required-check <check-name> --executor-id <id> --repo-wide`;
+export const PRINTED_CONDUCTOR_EXECUTOR_INSTALL_COMMAND = `${PRINTED_CONDUCTOR_INSTALL_COMMAND} --executor-id <id> --repo-wide`;
 /** Read-only readiness diagnostics. */
 export const PRINTED_DOCTOR_COMMAND = `${LAUNCHER} doctor`;
 /** Sessionless GitHub App connection. `--repo` is optional for this command. */
 export const PRINTED_CONNECT_GITHUB_COMMAND = `${LAUNCHER} connect-github`;
 /** Explains the `<check-name>` placeholder; print it beside a conductor command. */
-export const PRINTED_CHECK_NAME_INSTRUCTION = "Replace <check-name> with the exact name of a CI check this repository requires; " +
-    "repeat --required-check for each additional check.";
+export const PRINTED_CHECK_NAME_INSTRUCTION = "Run setup to create the workflow and store the required check.";
 /** Explains the `<id>` placeholder of the executor command. */
 export const PRINTED_EXECUTOR_ID_INSTRUCTION = "Replace <id> with a name for the executor service.";
 /**
@@ -50,3 +58,17 @@ export const PRINTED_QUALIFY_GATE_COMMAND = `${LAUNCHER} install-bridge conducto
 export const PRINTED_REPO_WIDE_EXECUTOR_COMMAND = `${LAUNCHER} install conductor --executor-id <id> --repo-wide`;
 /** The lifecycle-free executor service-unit generator. */
 export const PRINTED_EXECUTOR_INSTALL_SERVICE_COMMAND = `${LAUNCHER} executor install-service`;
+/** Fixed public actions; generated into Python from this source at build time. */
+export const READINESS_PREREQUISITE_FIXES = {
+    retry: "Retry the readiness check.",
+    setup: `Run ${PRINTED_CONDUCTOR_INSTALL_COMMAND}, then retry readiness.`,
+    no_index: "Re-index the repository, then retry readiness.",
+    pending_index: "Wait for indexing to finish, then retry readiness.",
+    missing_workflow: `Run ${PRINTED_CONDUCTOR_INSTALL_COMMAND}, merge the workflow changes, then re-index the repository.`,
+    explicit_command: "Run the learn step, or give an explicit test command.",
+    escalation: "Declare a notify webhook, or verify the account email with live email delivery.",
+    self_host: "Check the self-host installation guide, then retry readiness.",
+    consent: "Turn on Allow unattended Epic Implementer runs on the repository Setup page, or use --attended.",
+    github: `Run ${PRINTED_CONNECT_GITHUB_COMMAND}, then retry readiness.`,
+    none: "",
+};