@bridge_gpt/mcp-server 0.2.65 → 0.2.67

package/build/plane/restart.js

@@ -0,0 +1,542 @@
+/**
+ * `plane restart <member>` — the request/result channel between the CLI and the
+ * detached runtime (BAPI-1362).
+ *
+ * ## Why this is a file and a signal
+ *
+ * The process that owns a plane's members is the DETACHED runtime, and
+ * `plane restart` is a different process started later from a shell. Nothing is
+ * shared between them except the filesystem and signals — which is exactly why
+ * the manifest is already the channel for status and shutdown. A restart follows
+ * the same rule:
+ *
+ *   1. the CLI writes a small request file at a FIXED path under `.bridge/plane/`,
+ *   2. sends the runtime one `SIGUSR2`,
+ *   3. the runtime consumes the request exactly once, replaces the member, and
+ *   4. publishes a result file, which the CLI waits for within a bound.
+ *
+ * The signal carries no data and the file is the message. A second signal for the
+ * same request finds the request already consumed and does nothing, so a
+ * duplicated delivery can never cause a second restart.
+ *
+ * ## What this module will not do
+ *
+ * - **Signal anything it has not validated.** The manifest must parse, the
+ *   supervisor must be conclusively alive, the member must be one this command
+ *   supports and the plane actually lists, and the manifest must be new enough to
+ *   come from a runtime that HANDLES the signal — the default action of `SIGUSR2`
+ *   terminates a process that does not, so signalling an older runtime would kill
+ *   the plane it was meant to repair.
+ * - **Signal a process group.** Only the supervisor's own pid, never `-pgid`,
+ *   which would reach every member.
+ * - **Fall back to a plane-wide action.** A timeout or a failed readiness is
+ *   reported and stops there. It never runs `plane down`, never stops the bound
+ *   run, and never retries.
+ * - **Carry a secret.** The request holds a plane id, a request id, a member name,
+ *   and a timestamp. No environment, no argv, no credential, no path.
+ */
+import { randomUUID } from "crypto";
+import { getPlanePaths, isPlaneMemberName, planeManifestLifecycle, readPlaneManifest, } from "./manifest.js";
+import { PLANE_RESTART_FAILURE_REASONS, PLANE_RESTART_MIN_SCHEMA_VERSION, PLANE_RESTART_SIGNAL, PLANE_RESTARTABLE_MEMBERS, } from "./types.js";
+/** Version of the request and result records. */
+export const PLANE_RESTART_IPC_VERSION = 1;
+/** How often the CLI re-reads the result file while waiting. */
+export const PLANE_RESTART_POLL_MS = 500;
+/**
+ * How long the CLI waits for a matching result, per member.
+ *
+ * Each is the WORST-CASE runtime duration plus slack, because the CLI must not
+ * give up on a restart that is still legitimately in progress:
+ *
+ * - `server` — stop grace (10s) + kill wait (3s) + the TCP readiness budget (60s).
+ * - `worker` — the same stop window, plus the foreign-reconciler guard (up to
+ *   150s while a just-stopped reconciler's heartbeat goes stale), plus the
+ *   reconciler's first-heartbeat budget (120s).
+ * - `observer` — the stop window and a live-process check; it has no gate.
+ */
+export const PLANE_RESTART_WAIT_MS = {
+    server: 100_000,
+    worker: 330_000,
+    observer: 45_000,
+};
+/**
+ * A request file older than this is stale, not in progress.
+ *
+ * The longest legitimate wait is {@link PLANE_RESTART_WAIT_MS}'s `worker` entry,
+ * and a request is consumed within a signal delivery of being written, so an
+ * unconsumed file this old was left by a CLI that died before signalling.
+ */
+export const PLANE_RESTART_REQUEST_STALE_MS = 10 * 60_000;
+/** Every value {@link PlaneRestartRefusalReason} may take, for runtime guards. */
+export const PLANE_RESTART_REFUSAL_REASONS = [
+    "plane-starting",
+    "plane-stopping",
+    "member-not-in-plane",
+    "snapshot-invalid",
+    "legacy-unverifiable",
+    "identity-mismatch",
+];
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const PLANE_ID_PATTERN = /^[0-9a-f-]{8,}$/i;
+/** Is this one of the members `plane restart` may replace? */
+export function isPlaneRestartableMember(value) {
+    return (typeof value === "string" && PLANE_RESTARTABLE_MEMBERS.includes(value));
+}
+function isIsoTimestamp(value) {
+    return typeof value === "string" && value.length > 0 && !Number.isNaN(Date.parse(value));
+}
+/** Strictly validate an untrusted parsed-JSON value into a request. */
+export function parsePlaneRestartRequest(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return { ok: false, error: "restart request is not an object" };
+    }
+    const record = value;
+    const allowed = new Set(["version", "planeId", "requestId", "member", "requestedAt"]);
+    for (const key of Object.keys(record)) {
+        if (!allowed.has(key))
+            return { ok: false, error: `restart request has an unsupported field '${key}'` };
+    }
+    if (record.version !== PLANE_RESTART_IPC_VERSION) {
+        return { ok: false, error: "restart request version is not supported" };
+    }
+    if (typeof record.planeId !== "string" || !PLANE_ID_PATTERN.test(record.planeId)) {
+        return { ok: false, error: "restart request plane identity is malformed" };
+    }
+    if (typeof record.requestId !== "string" || !UUID_PATTERN.test(record.requestId)) {
+        return { ok: false, error: "restart request identity is malformed" };
+    }
+    if (!isPlaneRestartableMember(record.member)) {
+        return { ok: false, error: "restart request names a member that cannot be restarted" };
+    }
+    if (!isIsoTimestamp(record.requestedAt)) {
+        return { ok: false, error: "restart request timestamp is malformed" };
+    }
+    return {
+        ok: true,
+        request: {
+            version: PLANE_RESTART_IPC_VERSION,
+            planeId: record.planeId,
+            requestId: record.requestId,
+            member: record.member,
+            requestedAt: record.requestedAt,
+        },
+    };
+}
+/** Strictly validate an untrusted parsed-JSON value into a result. */
+export function parsePlaneRestartResult(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return { ok: false, error: "restart result is not an object" };
+    }
+    const record = value;
+    const allowed = new Set([
+        "version",
+        "planeId",
+        "requestId",
+        "member",
+        "outcome",
+        "reason",
+        "pid",
+        "completedAt",
+        "message",
+    ]);
+    for (const key of Object.keys(record)) {
+        if (!allowed.has(key))
+            return { ok: false, error: `restart result has an unsupported field '${key}'` };
+    }
+    if (record.version !== PLANE_RESTART_IPC_VERSION) {
+        return { ok: false, error: "restart result version is not supported" };
+    }
+    if (typeof record.planeId !== "string" || !PLANE_ID_PATTERN.test(record.planeId)) {
+        return { ok: false, error: "restart result plane identity is malformed" };
+    }
+    if (typeof record.requestId !== "string" || !UUID_PATTERN.test(record.requestId)) {
+        return { ok: false, error: "restart result identity is malformed" };
+    }
+    if (!isPlaneRestartableMember(record.member)) {
+        return { ok: false, error: "restart result names a member that cannot be restarted" };
+    }
+    if (record.outcome !== "restarted" && record.outcome !== "refused" && record.outcome !== "failed") {
+        return { ok: false, error: "restart result outcome is malformed" };
+    }
+    const reasons = [
+        ...PLANE_RESTART_REFUSAL_REASONS,
+        ...PLANE_RESTART_FAILURE_REASONS,
+    ];
+    if (record.reason !== undefined && (typeof record.reason !== "string" || !reasons.includes(record.reason))) {
+        return { ok: false, error: "restart result reason is malformed" };
+    }
+    if (record.pid !== null && !(typeof record.pid === "number" && Number.isSafeInteger(record.pid) && record.pid > 0)) {
+        return { ok: false, error: "restart result pid is malformed" };
+    }
+    if (!isIsoTimestamp(record.completedAt)) {
+        return { ok: false, error: "restart result timestamp is malformed" };
+    }
+    // The message is RENDERED to an operator's terminal, and this record is a file on
+    // disk the CLI did not write. Printable text only: a control character (an ANSI
+    // escape, a carriage return that overwrites the line above) could make the CLI
+    // print something the runtime never said. The runtime only ever writes fixed
+    // prose, so a legitimate message never trips this.
+    // eslint-disable-next-line no-control-regex
+    if (typeof record.message !== "string" || record.message.length > 1000 || /[\u0000-\u001f\u007f]/.test(record.message)) {
+        return { ok: false, error: "restart result message is malformed" };
+    }
+    return {
+        ok: true,
+        result: {
+            version: PLANE_RESTART_IPC_VERSION,
+            planeId: record.planeId,
+            requestId: record.requestId,
+            member: record.member,
+            outcome: record.outcome,
+            ...(record.reason !== undefined
+                ? { reason: record.reason }
+                : {}),
+            pid: record.pid,
+            completedAt: record.completedAt,
+            message: record.message,
+        },
+    };
+}
+/**
+ * Read the pending request and remove it in the same step, so it can be acted on
+ * exactly once.
+ *
+ * The unlink happens BEFORE the request is returned. If it happens after, a crash
+ * between "act" and "unlink" replays the restart on the next signal; before, the
+ * worst case is a request that was consumed and never acted on, which the CLI
+ * reports as a timeout. A dropped restart is recoverable by running it again; a
+ * repeated one is not distinguishable from a crash loop.
+ */
+export async function consumePlaneRestartRequest(repoRoot, fs) {
+    const { restartRequestPath } = getPlanePaths(repoRoot);
+    let raw;
+    try {
+        raw = await fs.readFile(restartRequestPath);
+    }
+    catch (err) {
+        if (err?.code === "ENOENT")
+            return { kind: "none" };
+        return { kind: "invalid" };
+    }
+    try {
+        await fs.unlink(restartRequestPath);
+    }
+    catch (err) {
+        // Another consumer won the race (or the CLI cleaned up): not ours to act on.
+        if (err?.code === "ENOENT")
+            return { kind: "none" };
+        return { kind: "invalid" };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return { kind: "invalid" };
+    }
+    const result = parsePlaneRestartRequest(parsed);
+    return result.ok ? { kind: "valid", request: result.request } : { kind: "invalid" };
+}
+let resultWriteCounter = 0;
+/**
+ * Publish a result through a same-directory temporary file and an atomic rename,
+ * so the waiting CLI can never read half of one. The result path is fixed; the
+ * temporary name is unique per write and never outlives the rename.
+ */
+export async function writePlaneRestartResult(repoRoot, result, fs) {
+    const { restartResultPath } = getPlanePaths(repoRoot);
+    resultWriteCounter += 1;
+    const tempPath = `${restartResultPath}.${process.pid}.${resultWriteCounter}.tmp`;
+    await fs.writeFile(tempPath, `${JSON.stringify(result, null, 2)}\n`);
+    await fs.rename(tempPath, restartResultPath);
+}
+function isMissing(err) {
+    return err?.code === "ENOENT";
+}
+/**
+ * Ask the detached runtime to replace one member, and wait for the outcome.
+ *
+ * Every refusal below happens BEFORE a request is written or a signal is sent, so
+ * a refused invocation has no side effect on the plane at all.
+ */
+export async function requestPlaneRestart(repoRoot, memberInput, deps) {
+    // Member first: it is pure, so a typo costs nothing — not even a manifest read.
+    if (!isPlaneRestartableMember(memberInput)) {
+        return isPlaneMemberName(memberInput) && memberInput.startsWith("executor-")
+            ? { kind: "executor-lane", member: memberInput }
+            : { kind: "unknown-member", member: memberInput };
+    }
+    const member = memberInput;
+    const read = await readPlaneManifest(repoRoot, deps.fs);
+    if (read.kind === "missing")
+        return { kind: "no-live-plane", detail: "no-manifest" };
+    if (read.kind !== "valid")
+        return { kind: "ownership-inconclusive", detail: "manifest" };
+    const manifest = read.manifest;
+    // BEFORE any liveness probe or signal: an older runtime would be KILLED by the
+    // restart signal, not merely ignore it.
+    if (manifest.schemaVersion < PLANE_RESTART_MIN_SCHEMA_VERSION) {
+        return { kind: "unsupported-runtime", schemaVersion: manifest.schemaVersion };
+    }
+    if (!manifest.members.some((m) => m.name === member)) {
+        return { kind: "member-not-in-plane", member };
+    }
+    const supervisor = deps.proc.isAlive(manifest.supervisorPid);
+    if (supervisor === "dead")
+        return { kind: "no-live-plane", detail: "supervisor-dead" };
+    if (supervisor === "unknown" || manifest.supervisorPid === (deps.selfPid ?? process.pid)) {
+        return { kind: "ownership-inconclusive", detail: "liveness" };
+    }
+    const lifecycle = planeManifestLifecycle(manifest);
+    if (lifecycle !== "ready" && lifecycle !== "lanes-failed") {
+        return { kind: "plane-not-steady", lifecycle };
+    }
+    const paths = getPlanePaths(repoRoot);
+    // A result left by an earlier restart must not be mistaken for this one's. The
+    // request id inside it is the real guard; this only keeps the file tidy.
+    try {
+        await deps.fs.unlink(paths.restartResultPath);
+    }
+    catch {
+        /* absent is the normal case */
+    }
+    const requestId = (deps.newRequestId ?? randomUUID)();
+    const request = {
+        version: PLANE_RESTART_IPC_VERSION,
+        planeId: manifest.planeId,
+        requestId,
+        member,
+        requestedAt: deps.clock.now().toISOString(),
+    };
+    const serialized = `${JSON.stringify(request, null, 2)}\n`;
+    const written = await writeRequestExclusively(paths.restartRequestPath, serialized, deps);
+    if (written === "busy")
+        return { kind: "restart-in-progress" };
+    if (written === "error")
+        return { kind: "request-failed" };
+    // The supervisor's OWN pid, positive. Never `-pgid`: that addresses the whole
+    // plane, which is the opposite of what a member restart is for.
+    const signalled = deps.proc.signal(manifest.supervisorPid, PLANE_RESTART_SIGNAL);
+    if (signalled !== "sent") {
+        await removeRequest(paths.restartRequestPath, deps);
+        return signalled === "no-such-process"
+            ? { kind: "no-live-plane", detail: "supervisor-dead" }
+            : { kind: "request-failed" };
+    }
+    const budget = deps.waitMs?.[member] ?? PLANE_RESTART_WAIT_MS[member];
+    const pollMs = deps.pollIntervalMs ?? PLANE_RESTART_POLL_MS;
+    let waited = 0;
+    while (waited < budget) {
+        const result = await readMatchingResult(paths.restartResultPath, manifest.planeId, requestId, deps);
+        if (result !== null) {
+            await removeResult(paths.restartResultPath, deps);
+            return outcomeFromResult(result);
+        }
+        await deps.clock.sleep(pollMs);
+        waited += pollMs;
+    }
+    // Take back a request the runtime never consumed, so a late signal cannot run a
+    // restart the operator has already been told timed out. If it WAS consumed the
+    // unlink is a no-op and the restart may still be finishing — the message says so.
+    await removeRequest(paths.restartRequestPath, deps);
+    return { kind: "timeout", member };
+}
+async function writeRequestExclusively(requestPath, serialized, deps) {
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+        try {
+            await deps.fs.createExclusive(requestPath, serialized);
+            return "written";
+        }
+        catch (err) {
+            if (err?.code !== "EEXIST")
+                return "error";
+        }
+        // Exists. A request is consumed within one signal delivery, so one that has
+        // been sitting for a long time was left by a CLI that died before signalling.
+        let ageMs;
+        try {
+            ageMs = deps.clock.now().getTime() - (await deps.fs.stat(requestPath)).mtimeMs;
+        }
+        catch {
+            // Gone between our create and our stat: try the create once more.
+            continue;
+        }
+        if (ageMs < PLANE_RESTART_REQUEST_STALE_MS)
+            return "busy";
+        await removeRequest(requestPath, deps);
+    }
+    return "busy";
+}
+async function removeRequest(requestPath, deps) {
+    try {
+        await deps.fs.unlink(requestPath);
+    }
+    catch {
+        /* already consumed or never written */
+    }
+}
+async function removeResult(resultPath, deps) {
+    try {
+        await deps.fs.unlink(resultPath);
+    }
+    catch {
+        /* tidy-up only */
+    }
+}
+/** The result for THIS request, or null when there is none yet (or it is someone else's). */
+async function readMatchingResult(resultPath, planeId, requestId, deps) {
+    let raw;
+    try {
+        raw = await deps.fs.readFile(resultPath);
+    }
+    catch (err) {
+        if (isMissing(err))
+            return null;
+        return null;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    const result = parsePlaneRestartResult(parsed);
+    if (!result.ok)
+        return null;
+    if (result.result.planeId !== planeId || result.result.requestId !== requestId)
+        return null;
+    return result.result;
+}
+function outcomeFromResult(result) {
+    if (result.outcome === "restarted") {
+        return { kind: "restarted", member: result.member, pid: result.pid, message: result.message };
+    }
+    if (result.outcome === "refused") {
+        return {
+            kind: "refused",
+            member: result.member,
+            reason: result.reason ?? "plane-starting",
+            message: result.message,
+        };
+    }
+    return {
+        kind: "failed",
+        member: result.member,
+        reason: result.reason,
+        pid: result.pid,
+        message: result.message,
+    };
+}
+/** Wording every member-scoped outcome repeats, so the safety claim is greppable. */
+export const PLANE_RESTART_RETAINS_LINE = "The plane keeps its pinned code and its bound run; only this member was replaced.";
+/**
+ * Render a CLI outcome for the terminal.
+ *
+ * `ok` is the process exit status. Every message is fixed prose plus a member name
+ * and, where known, a pid — nothing here can carry a credential. No failure line
+ * recommends `plane down`: a failed member restart leaves the plane as it was.
+ */
+export function formatPlaneRestartOutcome(outcome) {
+    switch (outcome.kind) {
+        case "restarted":
+            return {
+                ok: true,
+                lines: [
+                    `Restarted ${outcome.member}${outcome.pid !== null ? ` (new pid ${outcome.pid})` : ""} and it passed its readiness check.`,
+                    PLANE_RESTART_RETAINS_LINE,
+                ],
+            };
+        case "no-live-plane":
+            return {
+                ok: false,
+                lines: [
+                    outcome.detail === "no-manifest"
+                        ? "plane restart: there is no live plane here (no .bridge/plane/plane.json). Nothing was changed."
+                        : "plane restart: the recorded supervisor is not running, so there is no live plane to restart a member of. Nothing was changed. Run `plane status`, then `plane up` if the plane is gone.",
+                ],
+            };
+        case "ownership-inconclusive":
+            return {
+                ok: false,
+                lines: [
+                    outcome.detail === "manifest"
+                        ? "plane restart: the plane manifest could not be validated, so ownership of the plane cannot be established. Nothing was signalled or written."
+                        : "plane restart: the supervisor's liveness could not be established, so ownership of the plane cannot be confirmed. Nothing was signalled or written.",
+                    "Inspect it with `plane status`.",
+                ],
+            };
+        case "unsupported-runtime":
+            return {
+                ok: false,
+                lines: [
+                    `plane restart: this plane was started by an older build (manifest schema ${outcome.schemaVersion}) whose runtime cannot take a restart request; sending one would terminate it. Nothing was signalled.`,
+                    "Between runs, `plane down && plane up` moves the plane to new code. While a run is bound, `plane down` STOPS that run — decide that deliberately.",
+                ],
+            };
+        case "unknown-member":
+            return {
+                ok: false,
+                lines: [
+                    `plane restart: '${outcome.member}' is not a restartable member. Supported members: ${PLANE_RESTARTABLE_MEMBERS.join(", ")}.`,
+                ],
+            };
+        case "executor-lane":
+            return {
+                ok: false,
+                lines: [
+                    `plane restart: per-member restart is unavailable for executor lane '${outcome.member}'. Executor lanes are scoped to a run, so they are recovered at the run level (re-attach with \`drive-epic\`), not with \`plane restart\`.`,
+                ],
+            };
+        case "member-not-in-plane":
+            return {
+                ok: false,
+                lines: [
+                    `plane restart: this plane does not list a '${outcome.member}' member (the observer, for example, is not started on a plane whose executor lanes failed). Nothing was changed.`,
+                ],
+            };
+        case "plane-not-steady":
+            return {
+                ok: false,
+                lines: [
+                    `plane restart: the plane is still starting (${outcome.lifecycle}); restart is only available once it has finished starting. Nothing was changed. Check \`plane status\` and retry.`,
+                ],
+            };
+        case "restart-in-progress":
+            return {
+                ok: false,
+                lines: [
+                    "plane restart: another restart request is already pending. Wait for it to finish (`plane status`), then retry. Nothing was changed.",
+                ],
+            };
+        case "request-failed":
+            return {
+                ok: false,
+                lines: [
+                    "plane restart: the request could not be delivered to the plane's supervisor. Nothing was changed. Check `plane status`.",
+                ],
+            };
+        case "refused":
+            return {
+                ok: false,
+                lines: [`plane restart: the plane declined to restart ${outcome.member}: ${outcome.message}`, "No member was stopped."],
+            };
+        case "failed":
+            return {
+                ok: false,
+                lines: [
+                    `plane restart FAILED for ${outcome.member}: ${outcome.message}${outcome.pid !== null ? ` (replacement pid ${outcome.pid})` : ""}`,
+                    "The rest of the plane and its bound run were not touched, and nothing was retried. Inspect `plane status` and the member's log under .bridge/plane/, then run `plane restart " +
+                        `${outcome.member}\` again once the cause is fixed.`,
+                ],
+            };
+        case "timeout":
+            return {
+                ok: false,
+                lines: [
+                    `plane restart: no result for ${outcome.member} arrived within the wait bound. The restart may still be finishing, or it may not have started. Nothing was stopped as a fallback.`,
+                    "Inspect `plane status` and the member's log under .bridge/plane/ before deciding what to do.",
+                ],
+            };
+    }
+}

package/build/plane/shutdown.js

@@ -124,6 +124,7 @@ export async function shutdownPlane(repoRoot, deps) {
                 runShutdown,
             };
         }
+        messages.push(...(await releaseSnapshotAfterClear(manifest, deps)));
         return {
             ok: true,
             outcome: "already-dead",
@@ -168,6 +169,7 @@ export async function shutdownPlane(repoRoot, deps) {
     if (!cleared.ok) {
         return { ok: false, reason: "clear-failed", message: cleared.message, members, runShutdown };
     }
+    messages.push(...(await releaseSnapshotAfterClear(manifest, deps)));
     return {
         ok: true,
         outcome: "terminated",
@@ -178,6 +180,35 @@ export async function shutdownPlane(repoRoot, deps) {
         runShutdown,
     };
 }
+/**
+ * Run the snapshot release for a manifest whose plane is confirmed gone, and say
+ * what happened (BAPI-1362). Returns message lines; never throws.
+ *
+ * A manifest with no pinned snapshot (a legacy plane) and a caller that supplied
+ * no release capability both produce no output at all, so every pre-snapshot
+ * wind-down reads exactly as it always has.
+ */
+async function releaseSnapshotAfterClear(manifest, deps) {
+    if (deps.releaseSnapshot === undefined || manifest.snapshotSha === undefined)
+        return [];
+    try {
+        const { released } = await deps.releaseSnapshot(manifest);
+        return released
+            ? [
+                `Pinned code snapshot ${manifest.snapshotSha.slice(0, 12)} unlocked and kept on disk ` +
+                    "(.bridge/plane/snapshots/).",
+            ]
+            : [
+                `Pinned code snapshot ${manifest.snapshotSha.slice(0, 12)} was left in place; its lock ` +
+                    "release was not confirmed here (it may already have been released by the supervisor).",
+            ];
+    }
+    catch {
+        return [
+            `Pinned code snapshot ${manifest.snapshotSha.slice(0, 12)} was left locked: releasing it failed.`,
+        ];
+    }
+}
 /**
  * Signal every verified run-scoped executor that targets this plane (BAPI-1279).
  *