@bridge_gpt/mcp-server 0.2.50 → 0.2.52

package/build/plane/manifest.js

@@ -17,7 +17,7 @@
  *    argv, and no credential field, and unknown keys are rejected outright.
  */
 import path from "path";
-import { PLANE_MANIFEST_FILENAME, PLANE_MANIFEST_SCHEMA_VERSION, PLANE_RUNTIME_DIR, } from "./types.js";
+import { PLANE_MANIFEST_FILENAME, PLANE_MANIFEST_SUPPORTED_SCHEMA_VERSIONS, PLANE_RUNTIME_DIR, } from "./types.js";
 /**
  * Derive every runtime path beneath a validated repository root.
  *
@@ -67,11 +67,22 @@ const MEMBER_KEYS = new Set([
     "exitSignal",
     "logPath",
 ]);
-/** `server`, `worker`, or `executor-<positive integer>`. Nothing else. */
+/**
+ * `server`, `worker`, `observer`, or `executor-<positive integer>`. Nothing else.
+ *
+ * `observer` was added in BAPI-1029, which is also why
+ * {@link PLANE_MANIFEST_SCHEMA_VERSION} moved to 2. Widening the member set is
+ * backward-compatible only in the direction nobody is hurt by — a pre-release
+ * manifest simply has no observer entry and still validates here. The reverse
+ * is the one that bites: an OLDER build reading a manifest that names `observer`
+ * does not recognize it, and before the member-scoped skip in
+ * {@link parsePlaneManifest} that aborted the whole parse and orphaned the
+ * entire detached plane.
+ */
 export function isPlaneMemberName(value) {
     if (typeof value !== "string")
         return false;
-    if (value === "server" || value === "worker")
+    if (value === "server" || value === "worker" || value === "observer")
         return true;
     return /^executor-[1-9][0-9]*$/.test(value);
 }
@@ -98,8 +109,14 @@ export function parsePlaneManifest(value) {
             return { ok: false, error: `manifest has an unsupported field '${key}'` };
         }
     }
-    if (record.schemaVersion !== PLANE_MANIFEST_SCHEMA_VERSION) {
-        return { ok: false, error: "manifest schema version is not supported" };
+    if (typeof record.schemaVersion !== "number" ||
+        !PLANE_MANIFEST_SUPPORTED_SCHEMA_VERSIONS.includes(record.schemaVersion)) {
+        return {
+            ok: false,
+            error: `manifest schema version ${JSON.stringify(record.schemaVersion)} is not supported ` +
+                `(this build reads ${PLANE_MANIFEST_SUPPORTED_SCHEMA_VERSIONS.join(", ")}). A manifest ` +
+                "from a NEWER build must be wound down with that build's `plane down`",
+        };
     }
     if (typeof record.planeId !== "string" || !/^[0-9a-f-]{8,}$/i.test(record.planeId)) {
         return { ok: false, error: "manifest plane identity is missing or malformed" };
@@ -128,6 +145,7 @@ export function parsePlaneManifest(value) {
         return { ok: false, error: "manifest epic run id is malformed" };
     }
     const members = [];
+    const unrecognizedMemberNames = [];
     const seen = new Set();
     for (const raw of record.members) {
         if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
@@ -139,8 +157,26 @@ export function parsePlaneManifest(value) {
                 return { ok: false, error: `manifest member has an unsupported field '${key}'` };
             }
         }
+        // MEMBER-SCOPED, not whole-manifest (BAPI-1029). An unrecognized member
+        // name means this build is older than the one that wrote the file, and
+        // aborting the entire parse over it is what orphans a fully detached plane:
+        // `plane down` returns `unvalidated-manifest`, signals nothing, and leaves
+        // the operator deleting the file by hand while every process keeps running.
+        // Skipping the member instead keeps the plane windable through its process
+        // group — which reaches the unnamed member too, because the whole plane
+        // shares one group.
+        //
+        // Every OTHER member check below stays a hard rejection. Those fire on a
+        // member this build DOES understand, where a bad pid, state, or log path is
+        // corruption or tampering rather than a version gap.
+        if (typeof member.name !== "string" || member.name.length === 0) {
+            return { ok: false, error: "manifest member name is missing or not a string" };
+        }
         if (!isPlaneMemberName(member.name)) {
-            return { ok: false, error: "manifest member name is not a recognized plane member" };
+            if (!unrecognizedMemberNames.includes(member.name)) {
+                unrecognizedMemberNames.push(member.name);
+            }
+            continue;
         }
         if (seen.has(member.name)) {
             return { ok: false, error: `manifest lists member '${member.name}' more than once` };
@@ -172,10 +208,25 @@ export function parsePlaneManifest(value) {
             logPath: member.logPath,
         });
     }
+    // Every listed member was unrecognized: there is nothing this build can act
+    // on, and treating that as a valid manifest would report an empty plane over
+    // a running one. The `members.length === 0` check above cannot catch it,
+    // because the raw array was not empty.
+    if (members.length === 0) {
+        return {
+            ok: false,
+            error: "manifest lists no member this build recognizes " +
+                `(unrecognized: ${unrecognizedMemberNames.join(", ")}). It was written by a newer ` +
+                "build; wind the plane down with that build's `plane down`",
+        };
+    }
     return {
         ok: true,
+        unrecognizedMemberNames,
         manifest: {
-            schemaVersion: PLANE_MANIFEST_SCHEMA_VERSION,
+            // The version AS READ, not the version this build writes: a v1 manifest
+            // that came back stamped v2 would misreport which build owns the plane.
+            schemaVersion: record.schemaVersion,
             planeId: record.planeId,
             repoRoot: record.repoRoot,
             supervisorPid: record.supervisorPid,
@@ -215,7 +266,11 @@ export async function readPlaneManifest(repoRoot, fs) {
     const result = parsePlaneManifest(parsed);
     if (!result.ok)
         return { kind: "malformed", error: result.error };
-    return { kind: "valid", manifest: result.manifest };
+    return {
+        kind: "valid",
+        manifest: result.manifest,
+        unrecognizedMemberNames: result.unrecognizedMemberNames,
+    };
 }
 /**
  * Signal-zero liveness.

package/build/plane/member-logs.js

@@ -76,6 +76,12 @@ export const PLANE_MEMBER_STARTUP_FAILURES = {
     spawnThrew: "the process could not be started",
     noPid: "the process started without a pid",
     readinessTimeout: "it did not start listening in time",
+    // Two heartbeat-specific annotations (BAPI-1036). Before them, a member gated
+    // on a durable heartbeat that never arrived was annotated "it did not start
+    // listening in time" — false in a way that sends an operator looking for a
+    // socket that was never part of the contract.
+    heartbeatReadinessTimeout: "it did not publish a durable heartbeat in time",
+    readinessUnestablished: "its readiness baseline could not be established",
 };
 const ALLOWED_STARTUP_FAILURES = new Set(Object.values(PLANE_MEMBER_STARTUP_FAILURES));
 /** Substituted for any reason not in the allow-list. Never echoes the input. */

package/build/plane/member-roster.js

@@ -10,17 +10,60 @@
  *   `npx` and never a published package;
  * - the reconciler worker is the ORDINARY worker, explicitly not the dead-man
  *   observer;
- * - the dead-man observer is absent by construction — there is no observer
- *   member, pid, log path, or manifest record anywhere in this file (R-3).
+ * - the dead-man observer is a SEPARATE member in its own OS process (R-1,
+ *   BAPI-1029): the plane contains exactly one ordinary worker and exactly one
+ *   dead-man-only observer, and only the observer's environment carries
+ *   `CONDUCTOR_DEAD_MAN_ONLY`. The two are built from distinct environment
+ *   objects so the observer flag can never reach the worker by reference —
+ *   a plane whose "worker" is a second observer has nothing reconciling it.
+ *   Independence here is process-level on ONE host; separate-host isolation is
+ *   A2/R36 and this file does not claim it.
  *
  * Credentials travel in the child environment and nowhere else. No argv entry,
  * member name, log path, or formatted description is built from a secret.
  */
 import path from "path";
-import { PLANE_SERVER_HOST, PLANE_SERVER_PORT, PLANE_SERVER_PORT_ENV_VAR, } from "./types.js";
+import { PLANE_OBSERVER_MODE_ENV, PLANE_OBSERVER_MODE_VALUE, PLANE_SERVER_HOST, PLANE_SERVER_PORT, PLANE_SERVER_PORT_ENV_VAR, } from "./types.js";
 import { relativeLogPathFor } from "./manifest.js";
 /** How long a member with a readiness probe gets to start listening. */
 export const PLANE_READINESS_TIMEOUT_MS = 60_000;
+/**
+ * How long the ordinary worker gets to publish its first FRESH durable
+ * `component=reconciler` heartbeat, newer than the pre-start baseline.
+ *
+ * A FIRST-PUBLICATION budget (BAPI-1036), not a staleness window. The two are
+ * different quantities and the earlier rationale conflated them: the staleness
+ * window is how old a heartbeat may be and still count as fresh, whereas this is
+ * how long bring-up waits for one to ARRIVE. Sized from what the reconciler
+ * actually does — `_record_reconciler_heartbeat` runs at the top of `tick()`,
+ * `tick()` is registered on `IntervalTrigger(seconds=30)` in
+ * `api/library/scheduled_jobs.py`, and APScheduler fires an interval job one
+ * full interval AFTER the scheduler starts. So the first heartbeat lands roughly
+ * `worker.py` boot plus 30 seconds, and 120_000 ms leaves room for a slow boot
+ * plus three further tick opportunities before the plane gives up.
+ *
+ * That it coincides with `RECONCILER_STALE_SECONDS` is now arithmetic, not a
+ * derivation: the number is the same, the reason it was chosen is not.
+ */
+export const PLANE_RECONCILER_READINESS_TIMEOUT_MS = 120_000;
+/**
+ * How long ONE executor lane gets to publish its first FRESH durable
+ * `component=executor` heartbeat, newer than the pre-spawn baseline.
+ *
+ * Deliberately NOT `EXECUTOR_STALE_SECONDS` (300s). The executor publishes its
+ * first heartbeat immediately on entering its loop — `runProcessHeartbeatLoop`
+ * in `mcp_server/src/executor/runner.ts` publishes and only then sleeps
+ * `PROCESS_HEARTBEAT_INTERVAL_MS` — so a healthy lane reports within a node boot
+ * and one HTTP round trip. A 300s budget would buy nothing except three extra
+ * minutes before a DEAD lane is reported, which is the opposite of what a launch
+ * gate is for.
+ *
+ * 90_000 ms is boot plus that immediate publication, plus one full 60-second
+ * retry interval in case the very first delivery hits a transient failure — the
+ * loop's own next attempt is a whole interval later, so a budget under 60s would
+ * fail a lane that recovers on its second try.
+ */
+export const PLANE_EXECUTOR_READINESS_TIMEOUT_MS = 90_000;
 /** Executable used for the Python members. Overridable for a non-default venv. */
 export function resolvePythonExecutable(env) {
     const configured = env.BAPI_PLANE_PYTHON;
@@ -106,8 +149,70 @@ export function buildPlaneChildEnv(parentEnv, context) {
     return env;
 }
 /**
- * The complete roster: exactly one server, one ordinary worker, and `executors`
- * executor lanes. Never an observer.
+ * The observer's child environment: the ordinary child environment plus
+ * dead-man-only mode, and nothing else.
+ *
+ * A FRESH OBJECT, never a mutation of the shared one. `buildPlaneChildEnv`'s
+ * result is handed to the server, the worker, and every executor, so setting the
+ * flag on it in place would turn the reconciler worker into a second observer —
+ * the precise failure `buildPlaneChildEnv`'s `delete` exists to prevent, arrived
+ * at from the other direction.
+ *
+ * Any `CONDUCTOR_DEADMAN_CHANNEL_TYPE` / `CONDUCTOR_DEADMAN_DESTINATION_REF` the
+ * operator exported is inherited through the copy and is never read, echoed,
+ * placed in argv, or written to the manifest here: the observer resolves its own
+ * alert channel from its environment, exactly as a hand-started observer does.
+ */
+export function buildPlaneObserverEnv(childEnv) {
+    return { ...childEnv, [PLANE_OBSERVER_MODE_ENV]: PLANE_OBSERVER_MODE_VALUE };
+}
+/**
+ * The complete roster: exactly one server, one dead-man-only observer, one
+ * ordinary worker, and `executors` executor lanes.
+ *
+ * The ORDER is the contract, and it is not alphabetical:
+ *
+ * 1. `server` — everything downstream needs it. Its TCP readiness also has to
+ *    be satisfied before any heartbeat readiness probe has a route to call.
+ * 2. `worker` — the ordinary reconciler. Its readiness is a fresh durable
+ *    heartbeat, so it is the slowest member by an order of magnitude.
+ * 3. executor lanes — each gated on its OWN durable heartbeat since BAPI-1036.
+ * 4. `observer` — started LAST, and deliberately AFTER every gated member's
+ *    readiness has closed. See below.
+ *
+ * ## Why the observer starts after every readiness gate
+ *
+ * `process_heartbeats` rows are durable across runs, and
+ * `dead_man._evaluate_component` opens an outage as soon as the newest row
+ * exceeds its threshold — there is no boot grace period, and the sweep runs
+ * every 60 seconds. So any plane brought up after more than
+ * `RECONCILER_STALE_SECONDS` of idleness starts with an ALREADY-stale reconciler
+ * row, and an observer sweeping before the new reconciler's first heartbeat
+ * lands would page on ordinary bring-up. The heartbeat readiness gate widens
+ * that window rather than narrowing it: the observer would sweep for the entire
+ * time a member is held back waiting to go fresh.
+ *
+ * BAPI-1036 moved the observer past the executor lanes for exactly the same
+ * reason it was already placed past the worker. `_evaluate_component` watches
+ * the executor component on that same graceless 60-second sweep, so once each
+ * lane can consume a real readiness budget, an observer started before them
+ * would sweep for MINUTES while lanes are still starting — or while a doomed
+ * lane is waiting to be rolled back. The earlier order's only defence was that
+ * the executor sweep is deployment-wide and so usually satisfied by some sibling
+ * process, and that defence expires the moment the executor alert is scoped per
+ * repository (BAPI-1035, this ticket's own recommended predecessor).
+ *
+ * Ordering the observer last closes the window without touching `dead_man.py`,
+ * so the additive-only invariant holds; adding a boot grace to the evaluator was
+ * rejected outright because the acceptance criteria forbid changing its
+ * decisions. The gate is what makes this safe rather than merely quieter: if a
+ * gated member never goes fresh, the plane refuses to start at all and rolls
+ * back — before any observer process is started — so there is no unobserved
+ * running plane. If every gate closes, the observer starts against fresh rows
+ * and its first sweep is truthful.
+ *
+ * The alternative — starting it first and accepting boot noise — trains
+ * operators to dismiss the one alert this epic exists to produce.
  */
 export function buildPlaneMemberRoster(params) {
     const { context, executors, parentEnv, nodeExecutable } = params;
@@ -135,25 +240,86 @@ export function buildPlaneMemberRoster(params) {
         env,
         logPath: relativeLogPathFor("server"),
         readiness: {
+            kind: "tcp",
             host: endpoint.host,
             port: endpoint.port,
             timeoutMs: PLANE_READINESS_TIMEOUT_MS,
         },
     };
+    /**
+     * The independent dead-man observer (R-1, BAPI-1029).
+     *
+     * The SAME `worker.py` the ordinary worker runs, in its own OS process, with
+     * `CONDUCTOR_DEAD_MAN_ONLY=true` in its environment and nowhere else. No shell
+     * string: `PLANE_OBSERVER_COMMAND` remains operator-facing prose while the
+     * spawn is an executable plus an argument vector, so the mode flag never
+     * passes through a shell that could log it or reorder it.
+     *
+     * `readiness: null` on purpose, and the ONLY member left without a readiness
+     * contract since BAPI-1036 gated the executor lanes. The observer has no
+     * listening socket and publishes no durable heartbeat of its own, so "spawned
+     * and still alive" is the honest signal — and inventing a second liveness
+     * channel for the thing whose job is being the liveness channel would be
+     * circular. It inherits the R-4 no-respawn lifecycle unchanged.
+     *
+     * The residual that exemption accepts: an observer that crashes on boot leaves
+     * a plane that is announced ready with no dead-man watcher. It is detected by
+     * `plane status`, which reports the member `exited` with its exit code from the
+     * durable manifest, and by `.bridge/plane/observer.log`; it is contained by the
+     * R-4 no-respawn rule, which leaves the crash visible instead of masking it in
+     * a restart loop; and it escalates to the operator, who is the only party that
+     * can act — the plane never claims the observer is watching when the manifest
+     * says it exited.
+     *
+     * Ordered LAST of all members, after every readiness gate has closed — see the
+     * ordering contract on {@link buildPlaneMemberRoster}.
+     */
+    const observer = {
+        name: "observer",
+        command: resolvePythonExecutable(parentEnv),
+        args: ["worker.py"],
+        cwd,
+        env: buildPlaneObserverEnv(env),
+        logPath: relativeLogPathFor("observer"),
+        readiness: null,
+    };
     const worker = {
         name: "worker",
         command: resolvePythonExecutable(parentEnv),
         args: ["worker.py"],
         cwd,
         env,
+        // The reconciler has no listening socket, so it used to be `readiness: null`
+        // — "spawned and still alive", which cannot tell a booting reconciler from
+        // one that crashed on its first tick. It is now gated on a FRESH durable
+        // `component=reconciler` heartbeat read back through the server member's
+        // `GET /automation/health`, reusing the backend's existing verdict
+        // derivation rather than inventing a health endpoint (BAPI-1029, R9).
         logPath: relativeLogPathFor("worker"),
-        // The reconciler has no listening socket, so "spawned and still alive" is
-        // the only readiness signal available without inventing a health endpoint.
-        readiness: null,
+        readiness: {
+            kind: "process-heartbeat",
+            baseUrl: endpoint.baseUrl,
+            repoName: context.repoName,
+            component: "reconciler",
+            // No `instanceId` here, and it is not an omission. The local reconciler
+            // publishes `<hostname>:<pid>`, and the pid does not exist until `spawn`
+            // returns — the supervisor resolves the identity immediately after the
+            // spawn and before the readiness wait begins. A `DYNO` deployment is the
+            // one case that resolves without a pid, and the supervisor handles it
+            // there for the same reason: one resolver, one rule.
+            timeoutMs: PLANE_RECONCILER_READINESS_TIMEOUT_MS,
+        },
     };
     const executorMembers = [];
     for (let lane = 1; lane <= executors; lane += 1) {
         const name = `executor-${lane}`;
+        // Minted ONCE and used twice, deliberately. The value passed as
+        // `--executor-id` is the value the lane publishes as its heartbeat
+        // `instance_id` (`runner.ts`: `instance_id: options.executorId`), so the
+        // readiness gate can only be honest if it asserts the same string. Two calls
+        // to `buildExecutorId` would be equal today and are exactly the shape that
+        // stops being equal after an edit to one of them.
+        const executorId = buildExecutorId(context.repoName, lane);
         executorMembers.push({
             name,
             command: nodeExecutable,
@@ -167,15 +333,33 @@ export function buildPlaneMemberRoster(params) {
                 "--base-url",
                 endpoint.baseUrl,
                 "--executor-id",
-                buildExecutorId(context.repoName, lane),
+                executorId,
             ],
             cwd,
             env,
             logPath: relativeLogPathFor(name),
-            readiness: null,
+            // Gated since BAPI-1036. `readiness: null` here meant every lane was
+            // declared READY the instant it was spawned, so `plane up` printed a green
+            // banner over a lane that had already exited on a bad node path, an
+            // unbuilt bundle, or a rejected credential.
+            //
+            // Scoped to THIS lane's identity, not to the repository: every lane of one
+            // plane serves the same repository, so a repository-scoped verdict is
+            // satisfied by lane 1 for a lane 2 that never started.
+            //
+            // Carries no credential, exactly like the worker's spec: the API key
+            // travels only in `env` and the probe reads it there at call time.
+            readiness: {
+                kind: "process-heartbeat",
+                baseUrl: endpoint.baseUrl,
+                repoName: context.repoName,
+                component: "executor",
+                instanceId: executorId,
+                timeoutMs: PLANE_EXECUTOR_READINESS_TIMEOUT_MS,
+            },
         });
     }
-    return [server, worker, ...executorMembers];
+    return [server, worker, ...executorMembers, observer];
 }
 /**
  * Deterministic, distinct, CLI-safe executor id for one lane.

package/build/plane/preflight.js

@@ -42,6 +42,12 @@ export async function runPlanePreflight(repoRoot, deps) {
     // than emitting a cascade of derived failures the operator cannot act on.
     if (rootCheck)
         return { ok: false, diagnostics };
+    // 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));
     const credentials = await checkBridgeCredentials(repoRoot, deps);
     // Advisories first, then the failure. An insecure credentials file and an
@@ -134,6 +140,43 @@ async function checkRepositoryRoot(repoRoot, deps) {
             "Run `plane up` from the repository root.",
     };
 }
+/** 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.";
+/**
+ * Confirm the repository root is inside a real Git work tree (BAPI-1054).
+ *
+ * `checkRepositoryRoot` cannot answer this. Its four marker paths — `main.py`,
+ * `worker.py`, `alembic.ini`, `mcp_server/` — are present in every LINKED
+ * worktree and in any plain copy of the tree, so it proves the files are here,
+ * never that Git owns them. A plane brought up over an unpacked archive would
+ * pass that check and then fail at the first `git` operation a member performs.
+ *
+ * Linked worktrees are valid and must stay valid: `--is-inside-work-tree` is
+ * true in a linked worktree (where `.git` is a FILE, not a directory), which is
+ * why the predicate is this command and not a `.git` directory probe.
+ *
+ * READ-ONLY, like every other check here: it creates no worktree and repairs
+ * nothing. A directory that is not a work tree is named, with the fix, and the
+ * operator performs it.
+ */
+export async function checkRepositoryWorktree(repoRoot, deps) {
+    const result = await deps.execFile("git", ["rev-parse", "--is-inside-work-tree"], {
+        cwd: repoRoot,
+    });
+    // A failed command and a `false` answer are the same operator-facing fact —
+    // this is not a work tree — and are reported identically. The command's own
+    // 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 {
+            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}`,
+        };
+    }
+    return null;
+}
 /**
  * Advisory-only Claude login marker (BAPI-791).
  *

package/build/plane/shutdown.js

@@ -48,19 +48,41 @@ export async function shutdownPlane(repoRoot, deps) {
     if (read.kind !== "valid") {
         // Deliberately before any liveness probe: an unvalidated record must never
         // become a signal target, not even a signal-zero one — and, as of BAPI-872,
-        // must never authorize a run-stop lookup either.
+        // must never authorize a run-stop lookup either. That property is NOT
+        // relaxed here.
+        //
+        // What BAPI-1029 changed is the advice. "Remove it by hand" was the whole
+        // guidance, and it is the wrong instruction for the most likely cause: a
+        // manifest written by a NEWER build, which this one cannot parse. Deleting
+        // the file there does not stop anything — it destroys the only record of a
+        // plane that is still running, and orphans every member permanently.
         return {
             ok: false,
             reason: "unvalidated-manifest",
             message: `.bridge/plane/plane.json could not be validated (${read.error}). No process was ` +
-                "signalled. Inspect the file and remove it by hand once you have confirmed no plane " +
-                "is running.",
+                "signalled, because an unvalidated record must never become a signal target.\n" +
+                "  If this manifest was written by a NEWER build, wind the plane down with THAT " +
+                "build's `plane down` — do not delete the file, which would orphan every member " +
+                "with no record of what to stop.\n" +
+                "  Otherwise, confirm no plane is running (`ps` for the recorded pids) and only " +
+                "then remove the file by hand.",
             members: [],
             runShutdown: { kind: "unbound" },
         };
     }
     const manifest = read.manifest;
     const messages = [];
+    if (read.unrecognizedMemberNames.length > 0) {
+        // Said out loud, never assumed harmless (BAPI-1029). The wind-down still
+        // reaches these members — the whole plane shares one process group, and the
+        // group is what gets signalled — but the per-member reporting below cannot
+        // name them, and an operator reading a short list would otherwise conclude
+        // the plane was smaller than it was.
+        messages.push(`This manifest lists ${read.unrecognizedMemberNames.length} member(s) this build does ` +
+            `not recognize: ${read.unrecognizedMemberNames.join(", ")}. They are signalled with ` +
+            "the rest of the process group, but are not reported individually below. The manifest " +
+            "was written by a NEWER build.");
+    }
     // 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

package/build/plane/status.js

@@ -31,6 +31,7 @@ export async function getPlaneStatus(repoRoot, deps) {
         supervisorPid: manifest.supervisorPid,
         supervisorPgid: manifest.supervisorPgid,
         supervisorLiveness: deps.proc.isAlive(manifest.supervisorPid),
+        unrecognizedMemberNames: read.unrecognizedMemberNames,
         createdAt: manifest.createdAt,
         updatedAt: manifest.updatedAt,
         members: probeManifestMembers(manifest, deps.proc).map((probe) => ({
@@ -62,6 +63,16 @@ export function formatPlaneStatus(result) {
         lines.push(`  ${member.name.padEnd(12)} ${describeMemberState(member, result.supervisorLiveness)}  ` +
             `${member.logPath}`);
     }
+    if (result.unrecognizedMemberNames.length > 0) {
+        // Never a silent omission. The plane really has more members than the list
+        // above shows, and the operator needs to know the shortfall is a version
+        // gap rather than a crash.
+        lines.push("");
+        lines.push(`${result.unrecognizedMemberNames.length} member(s) are NOT SHOWN above — this build ` +
+            `does not recognize the name(s): ${result.unrecognizedMemberNames.join(", ")}. The ` +
+            "manifest was written by a NEWER build; use that build's `plane status` to see them, " +
+            "and its `plane down` to stop the plane.");
+    }
     const neverStarted = result.members.filter((m) => isPreStart(m) && result.supervisorLiveness === "dead");
     if (neverStarted.length > 0) {
         // These members have no log to read — pointing the operator at an empty file