@bridge_gpt/mcp-server 0.2.52 → 0.2.53

package/build/plane/preflight.js

@@ -12,13 +12,71 @@
  * it — including any manifest belonging to a plane that is already running.
  */
 import path from "path";
-import { PLANE_SERVER_PORT_ENV_VAR, } from "./types.js";
+import { PLANE_SERVER_PORT_ENV_VAR, planeCheckFinding, planeCheckPassed, } from "./types.js";
 import { checkPlaneBuildFreshness, checkPlaneRuntimeEntrypoint } from "./build-freshness.js";
 import { checkAlembicHead } from "./alembic-head.js";
 import { manifestHasLiveProcess, readPlaneManifest } from "./manifest.js";
 import { detectClaudeLogin, formatClaudeLoginAdvisory } from "../claude-login.js";
+import { createReadinessCheck, createReadinessCheckSafely, } from "../readiness-check.js";
 /** Files that must exist for a path to be this repository's root. */
 const REQUIRED_REPO_FILES = ["main.py", "worker.py", "alembic.ini"];
+/** Fixed remediation for a `plane up` run started outside the repository root. */
+export const PLANE_REPOSITORY_ROOT_REMEDIATION = "run `plane up` from the Bridge API repository root (the directory holding main.py, worker.py, and alembic.ini).";
+/** Fixed remediation for an unresolvable Bridge repository identity. */
+export const PLANE_REPO_IDENTITY_REMEDIATION = "set BAPI_REPO_NAME in this shell, or add a valid .bridge/config at the repository root.";
+/** Fixed remediation for an unresolvable Bridge credential. */
+export const PLANE_CREDENTIAL_REMEDIATION = "set BAPI_API_KEY in this shell, or store it with `mcp-server credentials`; a spawned shell never sees .mcp.json env.";
+/** Fixed remediation for the resolver's credential-file permission advisory. */
+export const PLANE_CREDENTIAL_PERMISSIONS_REMEDIATION = "restrict the Bridge credentials file to owner-only permissions (chmod 600), then rerun.";
+/** Fixed remediation for an advisory Claude-login gap. */
+export const PLANE_CLAUDE_LOGIN_REMEDIATION = "run `claude login` on this host so plane members inherit an authenticated session; startup continues either way.";
+/** Fixed remediation for an occupied local server port. */
+export const PLANE_SERVER_PORT_OCCUPIED_REMEDIATION = `stop the server that owns the port (or wind down its plane) and retry, or set ${PLANE_SERVER_PORT_ENV_VAR} to a free port — the port may belong to a SIBLING WORKTREE.`;
+/** Fixed remediation for a port whose availability could not be determined. */
+export const PLANE_SERVER_PORT_UNKNOWN_REMEDIATION = `retry, or set ${PLANE_SERVER_PORT_ENV_VAR} to a port you know is free; startup continues and uvicorn fails loudly if the port is taken.`;
+/** Fixed remediation for a configured port that could not be resolved at all. */
+export const PLANE_SERVER_ENDPOINT_REMEDIATION = `set ${PLANE_SERVER_PORT_ENV_VAR} to a valid port number (1-65535), or unset it to use the default.`;
+/** Fixed remediation for an unreadable or malformed plane manifest. */
+export const PLANE_MANIFEST_UNREADABLE_REMEDIATION = "inspect .bridge/plane/plane.json and remove it by hand once you have confirmed no plane is running; preflight signalled no process and changed no file.";
+/** Fixed remediation for a plane that is still running. */
+export const PLANE_ALREADY_RUNNING_REMEDIATION = "run `plane status` to inspect the running plane, or `plane down` to wind it down first.";
+/** Ids the credential check reports under, kept stable across every branch. */
+const PLANE_CREDENTIAL_OUTCOME_IDS = {
+    identity: "repo-identity",
+    credential: "bridge-credentials",
+    permissions: "credential-permissions",
+};
+/** Fixed detail for a prerequisite skipped because the repository root is invalid. */
+const PLANE_ROOT_DEPENDENT_SKIP_DETAIL = "not run — every remaining check is relative to a valid repository root";
+/**
+ * Every prerequisite `runPlanePreflight` short-circuits past when the
+ * repository root is invalid, with the name it is reported under.
+ *
+ * A table rather than a derived list: these are the checks that must still
+ * APPEAR in the outcome set, and deriving them from the ones that ran is exactly
+ * the "absence means pass" inference this whole change removes.
+ */
+const ROOT_DEPENDENT_CHECKS = [
+    ["worktree-presence", "worktree-presence", "Git work tree"],
+    ["claude-login", "claude-login", "Claude login"],
+    // The credential check reports THREE independently actionable facts under one
+    // check name, so all three ids are listed. Listing only the check name would
+    // leave `repo-identity` and `credential-permissions` absent from the outcome
+    // set, and the adapter would then report them as unknown FAILURES on a run
+    // where they were merely never reached.
+    ["bridge-credentials", PLANE_CREDENTIAL_OUTCOME_IDS.identity, "Bridge repository identity"],
+    ["bridge-credentials", PLANE_CREDENTIAL_OUTCOME_IDS.credential, "Bridge API credential"],
+    [
+        "bridge-credentials",
+        PLANE_CREDENTIAL_OUTCOME_IDS.permissions,
+        "Bridge credential file permissions",
+    ],
+    ["executor-build", "executor-build", "Executor build freshness"],
+    ["runtime-entrypoint", "runtime-entrypoint", "Runtime re-exec entrypoint"],
+    ["server-port", "server-port", "Local server port"],
+    ["alembic-head", "alembic-head", "Database migration head"],
+    ["existing-plane", "existing-plane", "Existing plane"],
+];
 /** Bound on the port probe so a black-holed port cannot stall bring-up. */
 export const PLANE_PORT_PROBE_TIMEOUT_MS = 1_500;
 /**
@@ -31,25 +89,50 @@ export const PLANE_PORT_PROBE_TIMEOUT_MS = 1_500;
  */
 export async function runPlanePreflight(repoRoot, deps) {
     const diagnostics = [];
+    const outcomes = [];
     const add = (diagnostic) => {
         if (diagnostic)
             diagnostics.push(diagnostic);
     };
-    const rootCheck = await checkRepositoryRoot(repoRoot, deps);
-    add(rootCheck);
+    // BAPI-1055: every check's own report, recorded whole. `add` still filters
+    // nulls for the legacy diagnostic list; `record` never infers anything from
+    // that filtering — the outcomes come from the check itself.
+    const record = (report) => {
+        add(report.diagnostic);
+        outcomes.push(...report.outcomes);
+        return report;
+    };
+    const rootCheck = record(await checkRepositoryRoot(repoRoot, deps));
     // Every remaining check is relative to the repository root. Without a valid
     // one there is nothing coherent left to check, so report and stop here rather
     // than emitting a cascade of derived failures the operator cannot act on.
-    if (rootCheck)
-        return { ok: false, diagnostics };
+    if (rootCheck.diagnostic) {
+        // The dependent prerequisites are recorded as explicitly SKIPPED rather
+        // than left absent (BAPI-1055). No probe is issued for any of them — no
+        // filesystem read, no process spawn, no credential resolution, no port
+        // connect — so the read-only, no-side-effect contract is unchanged; only
+        // the reporting is. Without this, a run that checked the least would look
+        // identical to a run in which everything passed.
+        for (const [check, id, label] of ROOT_DEPENDENT_CHECKS) {
+            outcomes.push({
+                check,
+                id,
+                label,
+                status: "skip",
+                detail: PLANE_ROOT_DEPENDENT_SKIP_DETAIL,
+            });
+        }
+        return { ok: false, diagnostics, outcomes };
+    }
     // BAPI-1054: aggregated with every other independent check rather than
     // short-circuiting. `checkRepositoryRoot` above proved the marker files are
     // here; this proves the directory is a real work tree. They are independent
     // facts and both can be true at once, which is exactly what the all-or-nothing
     // contract exists to report together.
-    add(await checkRepositoryWorktree(repoRoot, deps));
-    add(await checkClaudeLogin(deps));
+    record(await checkRepositoryWorktree(repoRoot, deps));
+    record(await checkClaudeLogin(deps));
     const credentials = await checkBridgeCredentials(repoRoot, deps);
+    outcomes.push(...credentials.outcomes);
     // Advisories first, then the failure. An insecure credentials file and an
     // unresolvable credential are independent facts and can both be true, so the
     // advisory is appended unconditionally rather than only on the success path.
@@ -57,26 +140,33 @@ export async function runPlanePreflight(repoRoot, deps) {
         add(advisory);
     if (!credentials.ok)
         add(credentials.diagnostic);
-    add(await checkPlaneBuildFreshness(repoRoot, { fs: deps.fs }));
+    record(await checkPlaneBuildFreshness(repoRoot, { fs: deps.fs }));
     // Read-only, and evaluated alongside the other independent checks so an
     // unresolvable re-exec target aggregates with them instead of short-circuiting.
     const runtimeEntrypoint = deps.resolveRuntimeEntrypoint();
-    add(checkPlaneRuntimeEntrypoint(runtimeEntrypoint));
+    record(checkPlaneRuntimeEntrypoint(runtimeEntrypoint));
     // An unresolvable override is a configuration failure, not a port failure:
     // there is no port to probe, so the probe is skipped entirely rather than
     // falling back to 8000 and reporting on a port the operator did not ask for.
     if (deps.endpoint.ok) {
-        add(await checkServerPort(deps, deps.endpoint.endpoint));
+        record(await checkServerPort(deps, deps.endpoint.endpoint));
     }
     else {
-        add({ check: "server-port", severity: "blocking", message: deps.endpoint.message });
+        // The endpoint resolver owns this diagnostic's prose; the structured fix is
+        // authored here beside it rather than derived downstream by an aggregator.
+        record(planeCheckFinding({
+            check: "server-port",
+            severity: "blocking",
+            message: deps.endpoint.message,
+            remediation: PLANE_SERVER_ENDPOINT_REMEDIATION,
+        }, "Local server port", "the configured local server endpoint could not be resolved"));
     }
-    add(await checkAlembicHead(repoRoot, {
+    record(await checkAlembicHead(repoRoot, {
         execFile: deps.execFile,
         fileExists: (filePath) => fileExists(filePath, deps.fs),
         platform: deps.platform,
     }));
-    add(await checkExistingPlane(repoRoot, deps));
+    record(await checkExistingPlane(repoRoot, deps));
     const blocking = diagnostics.filter((d) => d.severity === "blocking");
     // `!runtimeEntrypoint.ok` is already covered by the blocking count; it is
     // repeated here so the compiler narrows the union rather than requiring a
@@ -85,11 +175,12 @@ export async function runPlanePreflight(repoRoot, deps) {
     // here, like `!runtimeEntrypoint.ok`, so the compiler narrows the union rather
     // than requiring a non-null assertion on the context field below.
     if (blocking.length > 0 || !credentials.ok || !runtimeEntrypoint.ok || !deps.endpoint.ok) {
-        return { ok: false, diagnostics };
+        return { ok: false, diagnostics, outcomes };
     }
     return {
         ok: true,
         diagnostics,
+        outcomes,
         context: {
             repoRoot,
             repoName: credentials.repoName,
@@ -116,12 +207,14 @@ export async function runPlanePreflight(repoRoot, deps) {
  * parent would otherwise spawn `uvicorn main:app` against nothing.
  */
 async function checkRepositoryRoot(repoRoot, deps) {
+    const label = "Repository root";
     if (!path.isAbsolute(repoRoot)) {
-        return {
+        return planeCheckFinding({
             check: "repository-root",
             severity: "blocking",
             message: "the repository root could not be resolved to an absolute path",
-        };
+            remediation: PLANE_REPOSITORY_ROOT_REMEDIATION,
+        }, label, "the repository root could not be resolved to an absolute path");
     }
     const missing = [];
     for (const file of REQUIRED_REPO_FILES) {
@@ -131,14 +224,18 @@ async function checkRepositoryRoot(repoRoot, deps) {
     if (!(await fileExists(path.join(repoRoot, "mcp_server"), deps.fs))) {
         missing.push("mcp_server/");
     }
-    if (missing.length === 0)
-        return null;
-    return {
+    if (missing.length === 0) {
+        return planeCheckPassed("repository-root", label, "all Bridge API root marker files are present");
+    }
+    return planeCheckFinding({
         check: "repository-root",
         severity: "blocking",
         message: `this does not look like the Bridge API repository root — missing ${missing.join(", ")}. ` +
             "Run `plane up` from the repository root.",
-    };
+        remediation: PLANE_REPOSITORY_ROOT_REMEDIATION,
+    }, label, 
+    // Marker file NAMES only — never the resolved root, which is an absolute path.
+    `missing root marker(s): ${missing.join(", ")}`);
 }
 /** Remediation for a directory that is not a Git work tree. Fixed prose. */
 export const PLANE_WORKTREE_REMEDIATION = "cd into the intended worktree (or create it with `git worktree add`) and rerun.";
@@ -160,6 +257,7 @@ export const PLANE_WORKTREE_REMEDIATION = "cd into the intended worktree (or cre
  * operator performs it.
  */
 export async function checkRepositoryWorktree(repoRoot, deps) {
+    const label = "Git work tree";
     const result = await deps.execFile("git", ["rev-parse", "--is-inside-work-tree"], {
         cwd: repoRoot,
     });
@@ -168,14 +266,19 @@ export async function checkRepositoryWorktree(repoRoot, deps) {
     // stderr is deliberately NOT interpolated: it is unbounded text from a
     // subprocess, and the remediation does not depend on which way it failed.
     if (!result.ok || result.stdout.trim() !== "true") {
-        return {
+        return planeCheckFinding({
             check: "worktree-presence",
             severity: "blocking",
             message: `${repoRoot} is not inside a Git work tree (git rev-parse --is-inside-work-tree ` +
                 `did not report 'true'). No worktree was created — ${PLANE_WORKTREE_REMEDIATION}`,
-        };
+            remediation: PLANE_WORKTREE_REMEDIATION,
+        }, label, 
+        // The legacy `message` keeps naming `repoRoot` for the operator reading a
+        // terminal; the consolidated detail excludes it, because that root is an
+        // absolute path and the consolidated report is a wider surface.
+        "this directory is not inside a Git work tree");
     }
-    return null;
+    return planeCheckPassed("worktree-presence", label, "inside a Git work tree");
 }
 /**
  * Advisory-only Claude login marker (BAPI-791).
@@ -191,14 +294,41 @@ export async function checkRepositoryWorktree(repoRoot, deps) {
  * credential check `plane up` performs.
  */
 export async function checkClaudeLogin(deps) {
+    const label = "Claude login";
     const result = await detectClaudeLogin({ homedir: deps.homedir, readFile: deps.fs.readFile });
-    if (result.detected)
-        return null;
-    return {
+    if (result.detected) {
+        return planeCheckPassed("claude-login", label, "a local Claude login marker was detected");
+    }
+    // Still a WARNING, never blocking: the advisory gains a structured fix, it
+    // does not gain the power to refuse a bring-up.
+    return planeCheckFinding({
         check: "claude-login",
         severity: "warning",
         message: formatClaudeLoginAdvisory(result),
-    };
+        remediation: PLANE_CLAUDE_LOGIN_REMEDIATION,
+    }, label, "no local Claude login marker was detected");
+}
+/** Build the credential check's permission-advisory outcome. */
+function credentialPermissionsOutcome(advisories) {
+    // Counted, never quoted: the resolver's advisory text is buffered output this
+    // module does not author, so the consolidated outcome reports only that it
+    // fired. The advisory itself still reaches the operator as a diagnostic.
+    return advisories.length === 0
+        ? {
+            check: "bridge-credentials",
+            id: PLANE_CREDENTIAL_OUTCOME_IDS.permissions,
+            label: "Bridge credential file permissions",
+            status: "pass",
+            detail: "the credential resolver raised no permission advisory",
+        }
+        : {
+            check: "bridge-credentials",
+            id: PLANE_CREDENTIAL_OUTCOME_IDS.permissions,
+            label: "Bridge credential file permissions",
+            status: "warn",
+            detail: `the credential resolver raised ${advisories.length} permission advisory line(s)`,
+            remediation: PLANE_CREDENTIAL_PERMISSIONS_REMEDIATION,
+        };
 }
 /**
  * Resolve the repository identity, then the Bridge credential for it.
@@ -233,7 +363,8 @@ export async function checkBridgeCredentials(repoRoot, deps) {
     });
     if (!repo.ok) {
         // Nothing has called the credential resolver yet, so there is no advisory
-        // source to have captured from.
+        // source to have captured from — and the credential outcome is `skip`
+        // rather than `fail`, because the resolver was never asked.
         return {
             ok: false,
             advisories: [],
@@ -242,7 +373,26 @@ export async function checkBridgeCredentials(repoRoot, deps) {
                 severity: "blocking",
                 message: "the Bridge repository identity could not be resolved — set BAPI_REPO_NAME or add a " +
                     "valid .bridge/config at the repository root.",
+                remediation: PLANE_REPO_IDENTITY_REMEDIATION,
             },
+            outcomes: [
+                {
+                    check: "bridge-credentials",
+                    id: PLANE_CREDENTIAL_OUTCOME_IDS.identity,
+                    label: "Bridge repository identity",
+                    status: "fail",
+                    detail: "the Bridge repository identity could not be resolved",
+                    remediation: PLANE_REPO_IDENTITY_REMEDIATION,
+                },
+                {
+                    check: "bridge-credentials",
+                    id: PLANE_CREDENTIAL_OUTCOME_IDS.credential,
+                    label: "Bridge API credential",
+                    status: "skip",
+                    detail: "not resolved — there is no repository identity to resolve a credential for",
+                },
+                credentialPermissionsOutcome([]),
+            ],
         };
     }
     const warnings = createResolverWarningBuffer();
@@ -267,36 +417,92 @@ export async function checkBridgeCredentials(repoRoot, deps) {
         // Sanitized: a resolver throw becomes a category, never exception text
         // (which could echo file contents). Advisories captured before the throw
         // are still real observations and are kept.
+        const advisories = warnings.drain();
         return {
             ok: false,
-            advisories: warnings.drain(),
+            advisories,
             diagnostic: {
                 check: "bridge-credentials",
                 severity: "blocking",
                 message: `Bridge credentials for target bapi:${repo.repoName} could not be resolved ` +
                     "(resolver unavailable).",
+                remediation: PLANE_CREDENTIAL_REMEDIATION,
             },
+            outcomes: [
+                identityResolvedOutcome(),
+                {
+                    check: "bridge-credentials",
+                    id: PLANE_CREDENTIAL_OUTCOME_IDS.credential,
+                    label: "Bridge API credential",
+                    status: "fail",
+                    // Category, never exception text: a resolver throw can echo file content.
+                    detail: "the credential resolver was unavailable",
+                    remediation: PLANE_CREDENTIAL_REMEDIATION,
+                },
+                credentialPermissionsOutcome(advisories),
+            ],
         };
     }
     if (!result.ok) {
+        const advisories = warnings.drain();
         return {
             ok: false,
-            advisories: warnings.drain(),
+            advisories,
             diagnostic: {
                 check: "bridge-credentials",
                 severity: "blocking",
                 message: `Bridge credentials for target bapi:${repo.repoName} could not be resolved ` +
                     `(${result.kind}). Set BAPI_API_KEY in this shell, or store it with ` +
                     "`mcp-server credentials`. A spawned shell never sees .mcp.json env.",
+                remediation: PLANE_CREDENTIAL_REMEDIATION,
             },
+            outcomes: [
+                identityResolvedOutcome(),
+                {
+                    check: "bridge-credentials",
+                    id: PLANE_CREDENTIAL_OUTCOME_IDS.credential,
+                    label: "Bridge API credential",
+                    status: "fail",
+                    // `result.kind` is the resolver's own closed category vocabulary; the
+                    // repository name is deliberately omitted from the consolidated detail.
+                    detail: `no Bridge API credential resolved (${result.kind})`,
+                    remediation: PLANE_CREDENTIAL_REMEDIATION,
+                },
+                credentialPermissionsOutcome(advisories),
+            ],
         };
     }
+    const advisories = warnings.drain();
     return {
         ok: true,
         repoName: repo.repoName,
         apiKey: result.credentials.apiKey,
         source: result.credentials.source,
-        advisories: warnings.drain(),
+        advisories,
+        outcomes: [
+            identityResolvedOutcome(),
+            {
+                check: "bridge-credentials",
+                id: PLANE_CREDENTIAL_OUTCOME_IDS.credential,
+                label: "Bridge API credential",
+                status: "pass",
+                // The SOURCE, never the value: `source` is `"env"` or `"file"`.
+                detail: `resolved from ${result.credentials.source} (the value is never read into a report)`,
+            },
+            credentialPermissionsOutcome(advisories),
+        ],
+    };
+}
+/** The identity outcome for every branch reached after identity resolved. */
+function identityResolvedOutcome() {
+    return {
+        check: "bridge-credentials",
+        id: PLANE_CREDENTIAL_OUTCOME_IDS.identity,
+        label: "Bridge repository identity",
+        status: "pass",
+        // The resolved repository NAME is omitted deliberately: it is not needed to
+        // act on a passing check, and this outcome flows into a wider report.
+        detail: "the Bridge repository identity resolved",
     };
 }
 /**
@@ -353,26 +559,35 @@ function createResolverWarningBuffer() {
  * refuse a perfectly good bring-up.
  */
 export async function checkServerPort(deps, endpoint) {
+    const label = "Local server port";
     const target = `${endpoint.host}:${endpoint.port}`;
     const result = await deps.probePort(endpoint.host, endpoint.port, PLANE_PORT_PROBE_TIMEOUT_MS);
-    if (result.kind === "refused")
-        return null;
+    if (result.kind === "refused") {
+        return planeCheckPassed("server-port", label, `${target} is free`);
+    }
+    // Severity is unchanged in both branches: `connected` still blocks, an
+    // indeterminate probe still only warns.
     if (result.kind === "connected") {
-        return {
+        return planeCheckFinding({
             check: "server-port",
             severity: "blocking",
             message: `${target} is already accepting connections. ` +
                 "That port may belong to a SIBLING WORKTREE's server — check before you kill it. " +
                 `Stop the existing server (or wind down its plane) and retry, or set ${PLANE_SERVER_PORT_ENV_VAR} ` +
                 "to a free port.",
-        };
+            remediation: PLANE_SERVER_PORT_OCCUPIED_REMEDIATION,
+        }, label, `${target} is already accepting connections`);
     }
-    return {
+    return planeCheckFinding({
         check: "server-port",
         severity: "warning",
         message: `could not determine whether ${target} is free ` +
             `(${result.error}); startup continues and uvicorn will fail loudly if the port is taken.`,
-    };
+        remediation: PLANE_SERVER_PORT_UNKNOWN_REMEDIATION,
+    }, label, 
+    // The probe's own `error` text stays in the legacy message for the operator
+    // at the terminal and is not copied into the consolidated detail.
+    `could not determine whether ${target} is free`);
 }
 /**
  * Refuse to start over a plane that is still alive.
@@ -382,17 +597,23 @@ export async function checkServerPort(deps, endpoint) {
  * where the classification can be re-checked. Preflight never mutates disk.
  */
 export async function checkExistingPlane(repoRoot, deps) {
+    const label = "Existing plane";
     const read = await readPlaneManifest(repoRoot, deps.fs);
-    if (read.kind === "missing")
-        return null;
+    // Three distinct states, three distinct fixes (BAPI-1055): unreadable/malformed,
+    // stale, and live. Manifest validation, the liveness probe, and the
+    // never-touch-disk rule are all unchanged.
+    if (read.kind === "missing") {
+        return planeCheckPassed("existing-plane", label, "no plane manifest is present");
+    }
     if (read.kind !== "valid") {
-        return {
+        return planeCheckFinding({
             check: "existing-plane",
             severity: "blocking",
             message: `an existing .bridge/plane/plane.json could not be validated (${read.error}). ` +
                 "No process was signalled and the file was left untouched — inspect it, then remove " +
                 "it by hand if no plane is running.",
-        };
+            remediation: PLANE_MANIFEST_UNREADABLE_REMEDIATION,
+        }, label, "an existing plane manifest could not be validated");
     }
     // BAPI-882: a manifest carrying THIS process's own plane id is its own claim,
     // not a competitor. Checked after validation and BEFORE the liveness probe,
@@ -411,24 +632,40 @@ export async function checkExistingPlane(repoRoot, deps) {
     // A live manifest with a DIFFERENT plane id still blocks, unchanged — that is
     // a genuine second plane and the whole point of the check.
     if (deps.ownPlaneId !== undefined && read.manifest.planeId === deps.ownPlaneId) {
-        return null;
+        return planeCheckPassed("existing-plane", label, "the existing manifest carries this launch's own plane id");
     }
     if (!manifestHasLiveProcess(read.manifest, deps.proc)) {
         // Stale. Reported as information so the operator understands why an old
         // manifest is about to be replaced; the claim revalidates before it does.
+        // No remediation: the operator has nothing to do — the claim replaces it.
         return {
-            check: "existing-plane",
-            severity: "warning",
-            message: "a previous plane manifest is present but every recorded process is gone; it will be " +
-                "replaced after a final liveness re-check.",
+            diagnostic: {
+                check: "existing-plane",
+                severity: "warning",
+                message: "a previous plane manifest is present but every recorded process is gone; it will be " +
+                    "replaced after a final liveness re-check.",
+            },
+            outcomes: [
+                {
+                    check: "existing-plane",
+                    id: "existing-plane",
+                    label,
+                    status: "warn",
+                    detail: "a stale plane manifest is present and will be replaced after a liveness re-check",
+                },
+            ],
         };
     }
-    return {
+    return planeCheckFinding({
         check: "existing-plane",
         severity: "blocking",
         message: `a plane is already running (supervisor pid ${read.manifest.supervisorPid}). ` +
             "Run `plane status` to inspect it, or `plane down` to wind it down first.",
-    };
+        remediation: PLANE_ALREADY_RUNNING_REMEDIATION,
+    }, label, 
+    // The supervisor pid stays in the legacy message; the consolidated detail
+    // reports the fact, not the process identifier.
+    "a plane is already running for this repository");
 }
 async function fileExists(filePath, fs) {
     try {
@@ -439,3 +676,81 @@ async function fileExists(filePath, fs) {
         return false;
     }
 }
+// ---------------------------------------------------------------------------
+// Canonical readiness projection (BAPI-1055)
+// ---------------------------------------------------------------------------
+/**
+ * The complete plane prerequisite set, keyed by outcome id, in render order.
+ *
+ * Stable like the install- and conductor-side descriptor sets, and for the same
+ * reason: a preflight that returned early, threw, or was never run must still
+ * yield every prerequisite as an explicit unknown.
+ */
+export const PLANE_READINESS_DESCRIPTORS = [
+    { id: "repository-root", label: "Repository root" },
+    { id: "worktree-presence", label: "Git work tree" },
+    { id: "claude-login", label: "Claude login" },
+    { id: "repo-identity", label: "Bridge repository identity" },
+    { id: "bridge-credentials", label: "Bridge API credential" },
+    { id: "credential-permissions", label: "Bridge credential file permissions" },
+    { id: "executor-build", label: "Executor build freshness" },
+    { id: "runtime-entrypoint", label: "Runtime re-exec entrypoint" },
+    { id: "server-port", label: "Local server port" },
+    { id: "alembic-head", label: "Database migration head" },
+    { id: "existing-plane", label: "Existing plane" },
+];
+/** Fixed detail for a plane prerequisite the preflight never reported on. */
+const PLANE_UNREPORTED_DETAIL = "not reported — the plane preflight produced no outcome for this prerequisite";
+/** Fixed remediation for a plane prerequisite the preflight never reported on. */
+const PLANE_UNREPORTED_REMEDIATION = "run `plane up` (or `conductor readiness` again) to re-collect the plane preflight; this " +
+    "prerequisite's state is unknown, not healthy.";
+/**
+ * Project a plane preflight result into canonical readiness checks.
+ *
+ * PURE, and it NEVER runs a preflight of its own: it reads the outcomes an
+ * already-executed `runPlanePreflight` emitted. Two rules matter here and both
+ * exist because of how this could quietly go wrong:
+ *
+ * - A pass is only ever read from an explicit `status: "pass"` outcome. The
+ *   absence of a `PlaneDiagnostic` proves nothing — `add()` keeps only non-null
+ *   diagnostics, and a failed repository-root check returns before most checks
+ *   run — so a report built on silence would look healthiest on the runs where
+ *   the least was actually checked.
+ * - A launch-permitting `warning` maps to `warn`, never `fail` and never `skip`,
+ *   and nothing here feeds back into the preflight's own `ok` calculation.
+ */
+export function mapPlanePreflightToReadinessChecks(result) {
+    const byId = new Map();
+    for (const outcome of result?.outcomes ?? []) {
+        if (!byId.has(outcome.id))
+            byId.set(outcome.id, outcome);
+    }
+    return PLANE_READINESS_DESCRIPTORS.map(({ id, label }) => {
+        const outcome = byId.get(id);
+        if (!outcome) {
+            return createReadinessCheck({
+                id: `plane.${id}`,
+                source: "plane",
+                label,
+                status: "fail",
+                detail: PLANE_UNREPORTED_DETAIL,
+                remediation: PLANE_UNREPORTED_REMEDIATION,
+            });
+        }
+        return createReadinessCheckSafely({
+            id: `plane.${id}`,
+            source: "plane",
+            label: outcome.label || label,
+            status: outcome.status,
+            ...(outcome.detail ? { detail: outcome.detail } : {}),
+            // A failure without a fix would violate the contract and be replaced by a
+            // generic "unreadable" check, losing the real finding; the fallback keeps
+            // the finding and names the recollection step instead.
+            ...(outcome.status === "fail"
+                ? { remediation: outcome.remediation ?? PLANE_UNREPORTED_REMEDIATION }
+                : outcome.status !== "pass" && outcome.remediation
+                    ? { remediation: outcome.remediation }
+                    : {}),
+        });
+    });
+}