@bridge_gpt/mcp-server 0.2.36 → 0.2.38

package/build/plane/shutdown.js

@@ -0,0 +1,195 @@
+/**
+ * Plane wind-down (BAPI-756, AC-6).
+ *
+ * One primitive serves both attended Ctrl-C and a separate `plane down`
+ * invocation, so the two paths cannot drift into different escalation
+ * semantics.
+ *
+ * The honest caveat this compensates for: a SIGKILLed supervisor cannot kill
+ * its own group at that instant. Nothing can fix that in-process — so the
+ * manifest exists, `plane down` reads it from a *different* process, and the
+ * recorded process group is swept from there. That is the designed
+ * compensation, not a fallback.
+ *
+ * Two safety rules govern every branch:
+ * - **Never signal an unvalidated record.** A malformed manifest is reported,
+ *   not acted on. A kill list is the last thing that should be parsed loosely.
+ * - **Never clear on an unconfirmed death.** If a survivor remains, or its
+ *   liveness is unknown, the manifest is retained so a later `plane down` can
+ *   retry. Clearing it would orphan the survivor permanently.
+ */
+import { clearPlaneManifest, probeManifestMembers, readPlaneManifest, } from "./manifest.js";
+/** SIGTERM→SIGKILL grace period. */
+export const PLANE_SHUTDOWN_GRACE_MS = 10_000;
+/** How long stragglers get after SIGKILL before they are declared unknown. */
+export const PLANE_SHUTDOWN_KILL_WAIT_MS = 3_000;
+/** Liveness poll interval during both waits. */
+export const PLANE_SHUTDOWN_POLL_MS = 250;
+/**
+ * Signal the recorded process group, escalate to SIGKILL, and clear the
+ * manifest only once every recorded process is confirmed dead.
+ */
+export async function shutdownPlane(repoRoot, deps) {
+    const graceMs = deps.graceMs ?? PLANE_SHUTDOWN_GRACE_MS;
+    const killWaitMs = deps.killWaitMs ?? PLANE_SHUTDOWN_KILL_WAIT_MS;
+    const pollMs = deps.pollIntervalMs ?? PLANE_SHUTDOWN_POLL_MS;
+    const read = await readPlaneManifest(repoRoot, deps.fs);
+    if (read.kind === "missing") {
+        return {
+            ok: true,
+            outcome: "no-plane",
+            escalated: false,
+            manifestCleared: false,
+            members: [],
+            messages: ["No plane manifest found — nothing to wind down."],
+        };
+    }
+    if (read.kind !== "valid") {
+        // Deliberately before any liveness probe: an unvalidated record must never
+        // become a signal target, not even a signal-zero one.
+        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.",
+            members: [],
+        };
+    }
+    const manifest = read.manifest;
+    const messages = [];
+    if (!isAnythingAlive(manifest, deps.proc, deps.selfPid)) {
+        const cleared = await clearPlaneManifest(repoRoot, manifest.planeId, deps.fs);
+        if (!cleared.ok) {
+            return {
+                ok: false,
+                reason: "clear-failed",
+                message: cleared.message,
+                members: reportMembers(manifest, deps.proc),
+            };
+        }
+        return {
+            ok: true,
+            outcome: "already-dead",
+            escalated: false,
+            manifestCleared: cleared.removed,
+            members: reportMembers(manifest, deps.proc),
+            messages: ["Every recorded plane process was already gone; manifest cleared."],
+        };
+    }
+    messages.push(deps.selfPid === undefined
+        ? `Sending SIGTERM to plane process group ${manifest.supervisorPgid}.`
+        : "Sending SIGTERM to every plane member.");
+    signalPlane(manifest, "SIGTERM", deps.proc, deps.selfPid);
+    await waitForDeath(manifest, deps, graceMs, pollMs);
+    let escalated = false;
+    if (isAnythingAlive(manifest, deps.proc, deps.selfPid)) {
+        escalated = true;
+        messages.push("Grace period elapsed with survivors — escalating to SIGKILL.");
+        signalPlane(manifest, "SIGKILL", deps.proc, deps.selfPid);
+        await waitForDeath(manifest, deps, killWaitMs, pollMs);
+    }
+    const members = reportMembers(manifest, deps.proc);
+    if (isAnythingAlive(manifest, deps.proc, deps.selfPid)) {
+        const survivors = members
+            .filter((m) => m.liveness !== "dead")
+            .map((m) => `${m.name}(pid ${m.pid ?? "?"}, ${m.liveness})`);
+        if (deps.selfPid !== manifest.supervisorPid &&
+            deps.proc.isAlive(manifest.supervisorPid) !== "dead") {
+            survivors.push(`supervisor(pid ${manifest.supervisorPid})`);
+        }
+        return {
+            ok: false,
+            reason: "survivors",
+            message: `wind-down could not confirm every process was terminated: ${survivors.join(", ")}. ` +
+                "The manifest was RETAINED so `plane down` can be retried.",
+            members,
+        };
+    }
+    const cleared = await clearPlaneManifest(repoRoot, manifest.planeId, deps.fs);
+    if (!cleared.ok) {
+        return { ok: false, reason: "clear-failed", message: cleared.message, members };
+    }
+    return {
+        ok: true,
+        outcome: "terminated",
+        escalated,
+        manifestCleared: cleared.removed,
+        members,
+        messages,
+    };
+}
+/**
+ * Deliver a signal to the whole plane.
+ *
+ * The process group is addressed first — that is what reaches members whose own
+ * pid the manifest may not have recorded yet. Individual pids are then signalled
+ * as a backstop for the platform case where group delivery is unavailable; a
+ * signal to an already-dead pid is a no-op, so the belt-and-braces costs nothing.
+ */
+function signalPlane(manifest, signal, proc, selfPid) {
+    // The group signal is what reaches a member whose pid the manifest may not
+    // have recorded yet — but it also reaches the supervisor, so it is skipped
+    // when the supervisor is the one calling. Individual member pids are then the
+    // complete target set, because the runtime records each pid immediately after
+    // the spawn that produced it.
+    if (selfPid === undefined) {
+        proc.signal(-manifest.supervisorPgid, signal);
+        proc.signal(manifest.supervisorPid, signal);
+    }
+    for (const member of manifest.members) {
+        if (member.pid === null || member.pid === selfPid)
+            continue;
+        if (member.state === "exited")
+            continue;
+        proc.signal(member.pid, signal);
+    }
+}
+function isAnythingAlive(manifest, proc, selfPid) {
+    if (manifest.supervisorPid !== selfPid &&
+        proc.isAlive(manifest.supervisorPid) !== "dead") {
+        return true;
+    }
+    return probeManifestMembers(manifest, proc).some((probe) => probe.member.pid !== selfPid && probe.liveness !== "dead");
+}
+function reportMembers(manifest, proc) {
+    return probeManifestMembers(manifest, proc).map((probe) => ({
+        name: probe.member.name,
+        pid: probe.member.pid,
+        liveness: probe.liveness,
+        exitCode: probe.member.exitCode,
+        exitSignal: probe.member.exitSignal,
+    }));
+}
+/** Poll liveness on the injected clock until everything is dead or time runs out. */
+async function waitForDeath(manifest, deps, budgetMs, pollMs) {
+    let waited = 0;
+    while (waited < budgetMs) {
+        if (!isAnythingAlive(manifest, deps.proc, deps.selfPid))
+            return;
+        await deps.clock.sleep(pollMs);
+        waited += pollMs;
+    }
+}
+/** Render a wind-down result for the terminal. */
+export function formatPlaneShutdown(result) {
+    const lines = [];
+    if (!result.ok) {
+        lines.push(`plane down FAILED: ${result.message}`);
+    }
+    else {
+        for (const message of result.messages)
+            lines.push(message);
+    }
+    for (const member of result.members) {
+        const detail = member.exitSignal !== null
+            ? `signal ${member.exitSignal}`
+            : member.exitCode !== null
+                ? `exit ${member.exitCode}`
+                : "no recorded exit status";
+        lines.push(`  ${member.name.padEnd(12)} ${member.liveness.padEnd(7)} (${detail})`);
+    }
+    if (result.ok && result.manifestCleared)
+        lines.push("Manifest cleared.");
+    return lines.join("\n");
+}

package/build/plane/status.js

@@ -0,0 +1,125 @@
+/**
+ * `plane status` — read-only inspection (BAPI-756).
+ *
+ * Status runs in a different process from the supervisor, so it reads the
+ * manifest and probes pids. It never signals, never writes, and never repairs:
+ * a hole in the roster (a member that crashed and was deliberately not
+ * restarted) is precisely what this command exists to *show*.
+ */
+import { probeManifestMembers, readPlaneManifest, } from "./manifest.js";
+import { PLANE_RUNTIME_DIR, PLANE_RUNTIME_LOG_PATH, } from "./types.js";
+/** Read the manifest and probe every recorded pid. Strictly read-only. */
+export async function getPlaneStatus(repoRoot, deps) {
+    const read = await readPlaneManifest(repoRoot, deps.fs);
+    if (read.kind === "missing")
+        return { ok: true, kind: "no-plane" };
+    if (read.kind !== "valid") {
+        // No liveness probe and no signal: an unvalidated manifest yields no pid a
+        // caller could act on.
+        return {
+            ok: false,
+            error: `.bridge/plane/plane.json could not be validated (${read.error}). No process was ` +
+                "probed. Inspect the file and remove it by hand once you have confirmed no plane " +
+                "is running.",
+        };
+    }
+    const manifest = read.manifest;
+    return {
+        ok: true,
+        kind: "plane",
+        planeId: manifest.planeId,
+        supervisorPid: manifest.supervisorPid,
+        supervisorPgid: manifest.supervisorPgid,
+        supervisorLiveness: deps.proc.isAlive(manifest.supervisorPid),
+        createdAt: manifest.createdAt,
+        updatedAt: manifest.updatedAt,
+        members: probeManifestMembers(manifest, deps.proc).map((probe) => ({
+            name: probe.member.name,
+            pid: probe.member.pid,
+            state: probe.member.state,
+            liveness: probe.liveness,
+            exitCode: probe.member.exitCode,
+            exitSignal: probe.member.exitSignal,
+            logPath: probe.member.logPath,
+        })),
+    };
+}
+/** One line per member: name, state, exit status where known, log path. */
+export function formatPlaneStatus(result) {
+    if (!result.ok)
+        return `plane status FAILED: ${result.error}`;
+    if (result.kind === "no-plane") {
+        return `No plane is running (no ${PLANE_RUNTIME_DIR}/plane.json).`;
+    }
+    const lines = [
+        `Plane ${result.planeId}`,
+        `  supervisor   pid ${result.supervisorPid} (group ${result.supervisorPgid}) — ${result.supervisorLiveness}`,
+        `  started      ${result.createdAt}`,
+        `  updated      ${result.updatedAt}`,
+        "",
+    ];
+    for (const member of result.members) {
+        lines.push(`  ${member.name.padEnd(12)} ${describeMemberState(member, result.supervisorLiveness)}  ` +
+            `${member.logPath}`);
+    }
+    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
+        // is what made BAPI-768 look like "nothing happened" instead of "the runtime
+        // died before it could spawn anything". The runtime trace is the evidence.
+        lines.push("");
+        lines.push(`${neverStarted.length} member(s) were NEVER STARTED: the supervisor died before it ` +
+            "reached them, so their log files above may be empty or missing entirely.");
+        lines.push(`Read the runtime trace instead: ${PLANE_RUNTIME_LOG_PATH}`);
+    }
+    // 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));
+    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.");
+    }
+    return lines.join("\n");
+}
+/**
+ * True for a member the manifest still records as pre-spawn.
+ *
+ * `state: "spawning"` with no pid is written by the runtime up front, for the
+ * whole roster, before it starts anything. So it does not mean "this member
+ * exited without a status" — it means the runtime never got this far.
+ */
+function isPreStart(member) {
+    return member.state === "spawning" && member.pid === null;
+}
+export function describeMemberState(member, supervisorLiveness) {
+    // 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);
+    }
+    if (member.exitSignal !== null) {
+        return `exited   (signal ${member.exitSignal})`.padEnd(34);
+    }
+    if (member.exitCode !== null) {
+        return `exited   (code ${member.exitCode})`.padEnd(34);
+    }
+    if (member.liveness === "unknown") {
+        return `unknown  (pid ${member.pid ?? "?"}, liveness unverifiable)`.padEnd(34);
+    }
+    if (isPreStart(member)) {
+        if (supervisorLiveness === "alive") {
+            return `starting (not yet spawned)`.padEnd(34);
+        }
+        if (supervisorLiveness === "dead") {
+            return `never started`.padEnd(34);
+        }
+        // The supervisor's own liveness is what separates "still coming up" from
+        // "died on the way", so without it neither claim is honest.
+        return `unknown  (supervisor liveness unverifiable)`.padEnd(34);
+    }
+    return `exited   (no recorded exit status)`.padEnd(34);
+}