@bridge_gpt/mcp-server 0.2.66 → 0.2.68

package/build/plane/status.js

@@ -6,8 +6,8 @@
  * a hole in the roster (a member that crashed and was deliberately not
  * restarted) is precisely what this command exists to *show*.
  */
-import { planeManifestLifecycle, probeManifestMembers, readPlaneManifest, } from "./manifest.js";
-import { PLANE_RUNTIME_DIR, PLANE_RUNTIME_LOG_PATH, } from "./types.js";
+import { planeManifestLifecycle, planeManifestSnapshot, probeManifestMembers, readPlaneManifest, } from "./manifest.js";
+import { PLANE_RESTART_MIN_SCHEMA_VERSION, PLANE_RUNTIME_DIR, PLANE_RUNTIME_LOG_PATH, } from "./types.js";
 import { WORKER_STALE_EXIT_CODE } from "./worker-exit-code.js";
 /** Read the manifest and probe every recorded pid. Strictly read-only. */
 export async function getPlaneStatus(repoRoot, deps) {
@@ -35,6 +35,8 @@ export async function getPlaneStatus(repoRoot, deps) {
         unrecognizedMemberNames: read.unrecognizedMemberNames,
         lifecycle: planeManifestLifecycle(manifest),
         epicRunId: manifest.epicRunId ?? null,
+        snapshot: planeManifestSnapshot(manifest),
+        restartSupported: manifest.schemaVersion >= PLANE_RESTART_MIN_SCHEMA_VERSION,
         createdAt: manifest.createdAt,
         updatedAt: manifest.updatedAt,
         members: probeManifestMembers(manifest, deps.proc).map((probe) => ({
@@ -45,6 +47,10 @@ export async function getPlaneStatus(repoRoot, deps) {
             exitCode: probe.member.exitCode,
             exitSignal: probe.member.exitSignal,
             logPath: probe.member.logPath,
+            ...(probe.member.cwd !== undefined ? { cwd: probe.member.cwd } : {}),
+            ...(probe.member.restartFailure !== undefined
+                ? { restartFailure: probe.member.restartFailure }
+                : {}),
         })),
     };
 }
@@ -78,7 +84,19 @@ function describeLifecycle(phase) {
                 "left running; nothing is claiming jobs. Wind it down with `plane down`.");
     }
 }
-/** One line per member: name, state, exit status where known, log path. */
+/**
+ * Render a status result.
+ *
+ * The ORDER is the design (BAPI-1362): lifecycle and the bound run first, because
+ * they say whether touching the plane is safe at all; then the `Code snapshot`
+ * section, because what code the members run decides which recovery is safe; then
+ * the members, each with a text state and ONE next action. Nothing is carried by
+ * colour or by column alignment alone — every row starts with its member name and
+ * states its condition in words — so the output survives `TERM=dumb`, a pipe, a
+ * narrow terminal, and a screen reader. Long paths and commands are emitted whole
+ * on a line of their own rather than truncated, so the terminal wraps them and
+ * nothing the operator needs to copy is cut.
+ */
 export function formatPlaneStatus(result) {
     if (!result.ok)
         return `plane status FAILED: ${result.error}`;
@@ -93,10 +111,22 @@ export function formatPlaneStatus(result) {
         `  started      ${result.createdAt}`,
         `  updated      ${result.updatedAt}`,
         "",
+        "Code snapshot",
+        ...describeSnapshot(result.snapshot, result.restartSupported),
+        "",
+        "Members",
     ];
+    const context = {
+        supervisorLiveness: result.supervisorLiveness,
+        restartSupported: result.restartSupported,
+        ...(result.snapshot.kind === "pinned" ? { pinnedSha: result.snapshot.snapshot.sha } : {}),
+    };
     for (const member of result.members) {
         lines.push(`  ${member.name.padEnd(12)} ${describeMemberState(member, result.supervisorLiveness)}  ` +
             `${member.logPath}`);
+        const next = describeMemberNextAction(member, context);
+        if (next !== null)
+            lines.push(`               next: ${next}`);
     }
     if (result.unrecognizedMemberNames.length > 0) {
         // Never a silent omission. The plane really has more members than the list
@@ -121,14 +151,53 @@ export function formatPlaneStatus(result) {
     // Members that genuinely ran and exited keep the original no-restart warning;
     // one that never started was not restarted for an entirely different reason,
     // and telling the operator to "read the log above" would be a dead end.
-    const holes = result.members.filter((m) => m.liveness !== "alive" && !neverStarted.includes(m));
+    const holes = result.members.filter((m) => m.liveness !== "alive" && !neverStarted.includes(m) && m.state !== "restarting");
     if (holes.length > 0) {
         lines.push("");
         lines.push(`${holes.length} member(s) are not running. They are NOT restarted automatically — ` +
-            "read the log(s) above, then `plane down` and `plane up` when you have a fix.");
+            "read the log(s) above, then use the `next:` action under each member.");
+        // A full wind-down is the remedy only when there is no live supervisor left to
+        // take a restart request. With one, every restartable member has a scoped fix
+        // and recommending `plane down` here would stop a bound run to repair one
+        // process.
+        if (result.supervisorLiveness !== "alive") {
+            lines.push("The supervisor is not running, so nothing can restart a member: wind the plane down " +
+                "with `plane down` (it stops the bound run first), then `plane up`.");
+        }
     }
     return lines.join("\n");
 }
+/**
+ * The `Code snapshot` section's body lines (BAPI-1362).
+ *
+ * A pinned plane prints the FULL commit id and the complete path — never a
+ * shortened id, because this is the value an operator compares against `git
+ * rev-parse`. A legacy plane says so in exactly one recognizable phrase and
+ * invents nothing.
+ */
+function describeSnapshot(snapshot, restartSupported) {
+    if (snapshot.kind === "pinned") {
+        return [
+            `  status       Pinned`,
+            `  commit       ${snapshot.snapshot.sha}`,
+            `  path         ${snapshot.snapshot.path}`,
+            "  note         The server, worker, and observer run from this commit, so moving your",
+            "               checkout does not change them. `plane restart <member>` reuses it.",
+            "               `plane down && plane up` moves the plane to NEW code: use it between",
+            "               runs, because it stops a bound run.",
+        ];
+    }
+    return [
+        "  status       Unpinned (legacy)",
+        "  note         This plane does not record a code snapshot, so its Python members were",
+        "               launched from your checkout and follow it when it moves. No pinned",
+        "               commit or path is reported because none exists.",
+        restartSupported
+            ? "               `plane restart <member>` still works; it reuses each member's original launch."
+            : "               It was started by an older build, so `plane restart` is unavailable for it.",
+        "               To move it to new code, use `plane down && plane up` between runs (it stops a bound run).",
+    ];
+}
 /**
  * True for a member the manifest still records as pre-spawn.
  *
@@ -140,19 +209,33 @@ function isPreStart(member) {
     return member.state === "spawning" && member.pid === null;
 }
 export function describeMemberState(member, supervisorLiveness) {
+    // A restart in progress or a failed restart is the operator's own action, not a
+    // crash, and is worded as such (BAPI-1362). Both are read BEFORE the exit
+    // branches below, because a failed restart may record an exit status too.
+    if (member.state === "restarting") {
+        return `restarting (replacing pid ${member.pid ?? "?"}; status may change shortly)`.padEnd(34);
+    }
+    if (member.restartFailure !== undefined) {
+        const process = member.liveness === "alive" ? `replacement pid ${member.pid ?? "?"} still running` : "no process running";
+        return `restart FAILED (${member.restartFailure}; ${process})`.padEnd(34);
+    }
     // Precedence below is unchanged and load-bearing: a live pid, then a recorded
     // signal, then a recorded code, then unverifiable liveness. The pre-start
     // cases are appended after all four, so they can only ever claim a member
     // about which nothing else is known.
     if (member.liveness === "alive") {
-        return `running  (pid ${member.pid ?? "?"})`.padEnd(34);
+        // `ready` is the manifest's record that the member passed its readiness gate;
+        // `running` alone means it was spawned and the gate was not (yet) confirmed.
+        const readiness = member.state === "ready" ? "ready" : "readiness not confirmed";
+        return `running  (pid ${member.pid ?? "?"}, ${readiness})`.padEnd(34);
     }
     if (member.exitSignal !== null) {
         return `exited   (signal ${member.exitSignal})`.padEnd(34);
     }
     if (member.exitCode !== null) {
-        if ((member.name === "worker" || member.name === "observer") && member.exitCode === WORKER_STALE_EXIT_CODE) {
-            return `exited   (code 75: code changed; cycle the plane)`.padEnd(34);
+        if ((member.name === "worker" || member.name === "observer") &&
+            member.exitCode === WORKER_STALE_EXIT_CODE) {
+            return `exited   (code 75: code on disk changed)`.padEnd(34);
         }
         return `exited   (code ${member.exitCode})`.padEnd(34);
     }
@@ -172,3 +255,55 @@ export function describeMemberState(member, supervisorLiveness) {
     }
     return `exited   (no recorded exit status)`.padEnd(34);
 }
+/**
+ * The single safest next action for one member, or null when none is needed
+ * (BAPI-1362).
+ *
+ * Scoped by design. A restartable member that is down gets `plane restart
+ * <member>` — which replaces only that member and leaves the pinned commit and
+ * the bound run alone. An executor lane gets run-level recovery, because
+ * per-member restart is unavailable for it and `plane restart executor-N` would
+ * be refused. `plane down && plane up` is named only where it is genuinely the
+ * remedy: no live supervisor to take a request, or a pinned snapshot that is gone.
+ *
+ * Pure, and built from fixed prose plus the member name, which `isPlaneMemberName`
+ * has already bounded — nothing here can carry a path or a credential.
+ */
+export function describeMemberNextAction(member, context) {
+    const isExecutor = member.name.startsWith("executor-");
+    const down = member.liveness !== "alive" && member.state !== "restarting" && !isPreStart(member);
+    const keeps = context.pinnedSha !== undefined
+        ? `it keeps the pinned commit ${context.pinnedSha.slice(0, 12)} and the bound run`
+        : "it leaves the rest of the plane and the bound run running";
+    if (member.state === "restarting") {
+        return "a restart is in progress — run `plane status` again shortly; do not start another.";
+    }
+    if (isExecutor) {
+        return down
+            ? "per-member restart is unavailable for an executor lane — recover at the run level (re-attach with `drive-epic`)."
+            : null;
+    }
+    if (!down && member.restartFailure === undefined)
+        return null;
+    if (context.supervisorLiveness !== "alive") {
+        return "the supervisor is not running, so this member cannot be restarted — `plane down`, then `plane up`.";
+    }
+    if (!context.restartSupported) {
+        return ("this plane was started by an older build, so `plane restart` is unavailable — " +
+            "between runs, `plane down && plane up` moves it to new code (it stops a bound run).");
+    }
+    switch (member.restartFailure) {
+        case "stop-incomplete":
+            return `the old process would not exit — inspect ${member.logPath}, then \`plane restart ${member.name}\` again.`;
+        case "readiness":
+            return (`the replacement did not become ready — inspect ${member.logPath}, then ` +
+                `\`plane restart ${member.name}\` again (${keeps}).`);
+        case "snapshot":
+            return ("the pinned code could not be revalidated — restore it, or between runs " +
+                "`plane down && plane up` moves the plane to new code (it stops a bound run).");
+        case "spawn":
+            return `the replacement could not be started — inspect ${member.logPath}, then \`plane restart ${member.name}\` again.`;
+        default:
+            return `\`plane restart ${member.name}\` — ${keeps}.`;
+    }
+}