@bridge_gpt/mcp-server 0.2.66 → 0.2.68

package/build/plane/code-snapshot.js

@@ -0,0 +1,468 @@
+/**
+ * Plane-owned detached code snapshots (BAPI-1362).
+ *
+ * ## Why a plane needs its own checkout
+ *
+ * The plane's Python members — the server, the reconciler worker, and the
+ * dead-man observer — import application code from their working directory, and
+ * the working directory used to be the operator's own checkout. That checkout
+ * moves: an operator who fast-forwards `main`, or a `start-tickets` refresh, changes
+ * the files under a live plane. `worker.py` fingerprints its code and exits 75
+ * when it sees the change, so a routine `git pull` brought the plane's
+ * reconciler down in the middle of a bound run.
+ *
+ * A snapshot gives those members a code tree nobody else moves: a Git worktree,
+ * detached at one exact commit, at `.bridge/plane/snapshots/<full-sha>`. It is a
+ * worktree rather than a copy so it costs a checkout rather than a clone, and
+ * Git itself records that it exists.
+ *
+ * ## The safety posture
+ *
+ * This module creates, locks, and removes directories, so every rule below is
+ * about NOT doing so on a guess:
+ *
+ * - **Identity is checked, never assumed.** A snapshot is reused only when Git
+ *   registers it at the expected path, detached, at the expected SHA, AND a read
+ *   of the checkout itself reports that SHA. A directory that merely has the
+ *   right name is not evidence.
+ * - **Nothing is repointed.** A registration at the right path but the wrong
+ *   commit is refused. Resetting or re-checking-out a worktree that a live plane
+ *   may be importing from would change its code in place, which is the exact
+ *   failure this module exists to prevent.
+ * - **Ambiguity refuses.** An existing directory whose ownership cannot be
+ *   established, a symlink, a path that escapes `.bridge/plane/snapshots/`, or a
+ *   registration inspection that failed — all stop with a named reason, and none
+ *   deletes, prunes, or overwrites.
+ * - **Removal needs positive proof.** An obsolete snapshot is removed only when
+ *   it is unlocked AND no live, or inconclusively live, plane references it, and
+ *   only through a non-forced `git worktree remove`, which itself refuses a dirty
+ *   tree.
+ * - **A lock outlives a doubt.** A snapshot is unlocked only after a wind-down
+ *   confirmed every process gone and the manifest cleared. A failed, partial, or
+ *   unclear shutdown leaves it locked — the conservative direction, because a
+ *   leaked lock costs a few megabytes and a wrongly released one lets the
+ *   directory be pruned from under a running plane.
+ *
+ * All I/O arrives through {@link CodeSnapshotDeps}, so the unit tests never run
+ * real Git. Messages are fixed prose plus a path and a SHA, never raw command
+ * output: the exec seam reports an error CODE only, and this module does not
+ * widen that.
+ */
+import path from "path";
+import { getPlanePaths, isFullCommitSha, manifestHasLiveProcess, planeManifestSnapshot, } from "./manifest.js";
+/** Budget for `git worktree add`, which checks out the whole tree. */
+export const SNAPSHOT_CREATE_TIMEOUT_MS = 180_000;
+/** The lock reason prefix. Identifies a lock this module took. */
+export const SNAPSHOT_LOCK_REASON_PREFIX = "bridge-plane";
+/**
+ * Parse `git worktree list --porcelain`.
+ *
+ * Blocks are separated by a blank line; each starts with `worktree <path>`. A
+ * keyword this parser does not know is ignored rather than fatal, so a newer Git
+ * that adds one cannot turn every bring-up into a refusal.
+ */
+export function parseWorktreeList(output) {
+    const registrations = [];
+    let current = null;
+    for (const rawLine of output.split(/\r?\n/)) {
+        if (rawLine.length === 0) {
+            if (current)
+                registrations.push(current);
+            current = null;
+            continue;
+        }
+        if (rawLine.startsWith("worktree ")) {
+            if (current)
+                registrations.push(current);
+            current = {
+                path: rawLine.slice("worktree ".length),
+                head: null,
+                detached: false,
+                locked: false,
+                lockReason: null,
+                prunable: false,
+            };
+            continue;
+        }
+        if (!current)
+            continue;
+        if (rawLine.startsWith("HEAD "))
+            current.head = rawLine.slice("HEAD ".length).trim();
+        else if (rawLine === "detached")
+            current.detached = true;
+        else if (rawLine === "locked" || rawLine.startsWith("locked ")) {
+            current.locked = true;
+            current.lockReason = rawLine.length > "locked".length ? rawLine.slice("locked ".length) : null;
+        }
+        else if (rawLine === "prunable" || rawLine.startsWith("prunable "))
+            current.prunable = true;
+    }
+    if (current)
+        registrations.push(current);
+    return registrations;
+}
+/** Resolve the operator checkout's `HEAD` to a full commit id, or null. */
+async function resolveHeadSha(repoRoot, deps) {
+    const result = await deps.execFile("git", ["rev-parse", "--verify", "HEAD^{commit}"], {
+        cwd: repoRoot,
+    });
+    if (!result.ok)
+        return null;
+    const sha = result.stdout.trim();
+    return isFullCommitSha(sha) ? sha : null;
+}
+/** The commit a snapshot checkout reports as its own `HEAD`, or null. */
+async function readCheckoutSha(snapshotPath, deps) {
+    const result = await deps.execFile("git", ["rev-parse", "--verify", "HEAD^{commit}"], {
+        cwd: snapshotPath,
+    });
+    if (!result.ok)
+        return null;
+    const sha = result.stdout.trim();
+    return isFullCommitSha(sha) ? sha : null;
+}
+async function listRegistrations(repoRoot, deps) {
+    const result = await deps.execFile("git", ["worktree", "list", "--porcelain"], { cwd: repoRoot });
+    if (!result.ok)
+        return null;
+    return parseWorktreeList(result.stdout);
+}
+/** Realpath that resolves to null instead of throwing. */
+async function tryRealpath(filePath, deps) {
+    try {
+        return await deps.fs.realpath(filePath);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The snapshot path as Git REGISTERS it.
+ *
+ * `git worktree list` reports real paths, so a repository reached through a
+ * symlinked prefix (`/tmp` → `/private/tmp` is the everyday case) registers its
+ * snapshots under the resolved prefix. The lexical path in the manifest is the
+ * contract; this is the same location spelled the way Git spells it.
+ */
+async function registeredSnapshotPath(repoRoot, sha, deps) {
+    const realRoot = await tryRealpath(repoRoot, deps);
+    if (realRoot === null)
+        return null;
+    return getPlanePaths(realRoot).snapshotPathFor(sha);
+}
+function fail(reason, message) {
+    return { ok: false, reason, message };
+}
+/**
+ * Does a live, or inconclusively live, plane reference this snapshot directory?
+ *
+ * `in-use` and `unknown` are both "do not touch": the conservative reading of a
+ * probe that could not answer is that something might be using the directory.
+ */
+async function snapshotMayBeInUse(repoRoot, snapshotPath, deps) {
+    const read = await deps.readManifest(repoRoot);
+    if (read.kind === "missing")
+        return "free";
+    if (read.kind !== "valid")
+        return "unknown";
+    const pinned = planeManifestSnapshot(read.manifest);
+    if (pinned.kind !== "pinned" || pinned.snapshot.path !== snapshotPath)
+        return "free";
+    return manifestHasLiveProcess(read.manifest, deps.proc) ? "in-use" : "free";
+}
+/**
+ * Prepare the snapshot for the operator checkout's current commit.
+ *
+ * Resolves `HEAD` once, to a full SHA, and works on the deterministic location
+ * for that SHA. Create-or-reuse, verify, then best-effort prune of obsolete
+ * snapshots. It does NOT lock: locking is a separate step the launcher takes once
+ * the manifest claim has succeeded, so a bring-up that fails a later preflight
+ * check never leaves a lock behind for a plane that did not start.
+ */
+export async function prepareCodeSnapshot(repoRoot, deps) {
+    const sha = await resolveHeadSha(repoRoot, deps);
+    if (sha === null) {
+        return fail("head-unresolved", "the operator checkout's HEAD could not be resolved to a full commit id, so no code snapshot can be pinned");
+    }
+    const planePaths = getPlanePaths(repoRoot);
+    const snapshotPath = planePaths.snapshotPathFor(sha);
+    const snapshot = { path: snapshotPath, sha };
+    try {
+        await deps.fs.mkdir(planePaths.snapshotsDir);
+    }
+    catch {
+        return fail("unsafe-location", "the snapshot directory under .bridge/plane/ could not be created");
+    }
+    // The directory that will hold every snapshot must be what it says it is. A
+    // symlink here would send `git worktree add` — and, later, removal — to
+    // wherever it points.
+    const realSnapshotsDir = await tryRealpath(planePaths.snapshotsDir, deps);
+    const realRoot = await tryRealpath(repoRoot, deps);
+    if (realSnapshotsDir === null ||
+        realRoot === null ||
+        realSnapshotsDir !== getPlanePaths(realRoot).snapshotsDir) {
+        return fail("unsafe-location", "the snapshot directory under .bridge/plane/ resolves outside the repository, so no snapshot was created");
+    }
+    const registrations = await listRegistrations(repoRoot, deps);
+    if (registrations === null) {
+        return fail("registration-unreadable", "Git's worktree registrations could not be read, so snapshot ownership cannot be established");
+    }
+    const registeredPath = await registeredSnapshotPath(repoRoot, sha, deps);
+    if (registeredPath === null) {
+        return fail("unsafe-location", "the repository root could not be resolved");
+    }
+    const registration = registrations.find((entry) => entry.path === registeredPath) ?? null;
+    const stat = await lstatOrNull(snapshotPath, deps);
+    if (stat === "error") {
+        return fail("ownership-ambiguous", "the snapshot path could not be inspected");
+    }
+    let reused = false;
+    if (stat !== null) {
+        // Something is on disk at the snapshot path.
+        if (stat.isSymbolicLink || !stat.isDirectory) {
+            return fail("ownership-ambiguous", `${relativeSnapshotLabel(sha)} exists but is a symlink or not a directory, so it was left alone`);
+        }
+        if (registration === null) {
+            return fail("ownership-ambiguous", `${relativeSnapshotLabel(sha)} exists but Git does not register it as a worktree, so its ownership cannot be established and it was left alone`);
+        }
+        if (!registration.detached || registration.head !== sha) {
+            return fail("identity-mismatch", `${relativeSnapshotLabel(sha)} is registered at a different commit than ${sha.slice(0, 12)}; it was not reset or repointed`);
+        }
+        const real = await tryRealpath(snapshotPath, deps);
+        const checkoutSha = await readCheckoutSha(snapshotPath, deps);
+        if (real !== registeredPath || checkoutSha !== sha) {
+            return fail("identity-mismatch", `${relativeSnapshotLabel(sha)} does not report commit ${sha.slice(0, 12)}; it was not reset or repointed`);
+        }
+        reused = true;
+    }
+    else {
+        if (registration !== null) {
+            // Registered, but the directory is gone: a crash left a stale registration.
+            // Repair it narrowly — and only with proof nothing is using it.
+            const inUse = await snapshotMayBeInUse(repoRoot, snapshotPath, deps);
+            if (inUse !== "free") {
+                return fail("in-use", `${relativeSnapshotLabel(sha)} has a stale Git registration but a plane may still reference it, so it was left alone`);
+            }
+            if (registration.locked) {
+                const unlocked = await deps.execFile("git", ["worktree", "unlock", registeredPath], {
+                    cwd: repoRoot,
+                });
+                if (!unlocked.ok) {
+                    return fail("create-failed", "a stale snapshot lock could not be cleared");
+                }
+            }
+            const pruned = await deps.execFile("git", ["worktree", "prune"], { cwd: repoRoot });
+            if (!pruned.ok) {
+                return fail("create-failed", "the stale snapshot registration could not be pruned");
+            }
+        }
+        const created = await deps.execFile("git", ["worktree", "add", "--detach", snapshotPath, sha], { cwd: repoRoot, timeoutMs: SNAPSHOT_CREATE_TIMEOUT_MS });
+        if (!created.ok) {
+            return fail("create-failed", `the snapshot for commit ${sha.slice(0, 12)} could not be created`);
+        }
+        const verifiedSha = await readCheckoutSha(snapshotPath, deps);
+        const real = await tryRealpath(snapshotPath, deps);
+        if (verifiedSha !== sha || real !== registeredPath) {
+            return fail("verify-failed", `the new snapshot for commit ${sha.slice(0, 12)} did not verify as that commit`);
+        }
+    }
+    const prunedSnapshots = await pruneObsoleteSnapshots(repoRoot, sha, deps);
+    return { ok: true, snapshot, reused, prunedSnapshots };
+}
+function relativeSnapshotLabel(sha) {
+    return `.bridge/plane/snapshots/${sha}`;
+}
+async function lstatOrNull(filePath, deps) {
+    try {
+        return await deps.fs.lstat(filePath);
+    }
+    catch {
+        return "error";
+    }
+}
+/**
+ * Remove snapshots for OTHER commits that are provably unused.
+ *
+ * Best effort and silent on failure: pruning is housekeeping, and a bring-up must
+ * never fail because an old snapshot would not go. Each removal needs all of:
+ * registered by Git under this repository's snapshot directory, not the pinned
+ * SHA, not locked, and not referenced by a plane that is live or whose liveness
+ * could not be determined. `git worktree remove` is run without `--force`, so Git
+ * itself refuses a worktree with local changes.
+ *
+ * If the manifest cannot be read or validated, NOTHING is removed: an unreadable
+ * record might describe a live plane, and "could not tell" is not "unused".
+ */
+export async function pruneObsoleteSnapshots(repoRoot, keepSha, deps) {
+    const removed = [];
+    try {
+        const realRoot = await tryRealpath(repoRoot, deps);
+        if (realRoot === null)
+            return removed;
+        const read = await deps.readManifest(repoRoot);
+        if (read.kind !== "missing" && read.kind !== "valid")
+            return removed;
+        const heldPath = read.kind === "valid" ? planeManifestSnapshot(read.manifest) : { kind: "legacy" };
+        const planeIsLive = read.kind === "valid" && manifestHasLiveProcess(read.manifest, deps.proc);
+        const registrations = await listRegistrations(repoRoot, deps);
+        if (registrations === null)
+            return removed;
+        const snapshotsDir = getPlanePaths(realRoot).snapshotsDir;
+        const keepPath = getPlanePaths(realRoot).snapshotPathFor(keepSha);
+        for (const entry of registrations) {
+            if (path.dirname(entry.path) !== snapshotsDir)
+                continue;
+            const leaf = path.basename(entry.path);
+            if (!isFullCommitSha(leaf) || entry.path === keepPath)
+                continue;
+            if (entry.locked)
+                continue;
+            // A plane that is live or unaccounted for and pinned to this directory
+            // protects it. A plane that holds NO pin (legacy) protects nothing here.
+            if (planeIsLive &&
+                heldPath.kind === "pinned" &&
+                (await tryRealpath(heldPath.snapshot.path, deps)) === entry.path) {
+                continue;
+            }
+            const result = await deps.execFile("git", ["worktree", "remove", entry.path], { cwd: repoRoot });
+            if (result.ok)
+                removed.push(leaf);
+        }
+    }
+    catch {
+        /* housekeeping must never change a bring-up's outcome */
+    }
+    return removed;
+}
+/**
+ * Lock the snapshot for a live plane, so Git will not prune or remove it.
+ *
+ * Idempotent for a lock this module took earlier (a crashed plane leaves one
+ * behind, and its manifest — already proven stale by preflight — is the only
+ * thing that could make the new plane's claim legal). A lock with a reason this
+ * module did not write belongs to someone else and is refused.
+ */
+export async function lockCodeSnapshot(repoRoot, snapshot, planeId, deps) {
+    const registrations = await listRegistrations(repoRoot, deps);
+    const registeredPath = await registeredSnapshotPath(repoRoot, snapshot.sha, deps);
+    const entry = registrations && registeredPath
+        ? (registrations.find((candidate) => candidate.path === registeredPath) ?? null)
+        : null;
+    if (entry === null) {
+        return { ok: false, reason: "lock-failed", message: "the snapshot is not registered with Git, so it cannot be locked" };
+    }
+    if (entry.locked) {
+        if (entry.lockReason !== null && entry.lockReason.startsWith(SNAPSHOT_LOCK_REASON_PREFIX)) {
+            return { ok: true };
+        }
+        return {
+            ok: false,
+            reason: "lock-failed",
+            message: "the snapshot is already locked by something other than a plane",
+        };
+    }
+    const locked = await deps.execFile("git", ["worktree", "lock", "--reason", `${SNAPSHOT_LOCK_REASON_PREFIX} ${planeId}`, registeredPath], { cwd: repoRoot });
+    return locked.ok
+        ? { ok: true }
+        : { ok: false, reason: "lock-failed", message: "the snapshot could not be locked" };
+}
+/**
+ * Unlock a snapshot after its plane is confirmed gone. Never removes it.
+ *
+ * The CALLER decides that "confirmed gone" holds; this only performs the unlock,
+ * and reports whether the snapshot is now unlocked. "Already unlocked" IS the goal
+ * state, so it is success: `git worktree unlock` on an unlocked worktree exits
+ * non-zero and the exec seam cannot tell that apart from a real failure, so the
+ * registration is read first. This matters in practice, because a `plane down`
+ * and the supervisor it signals both wind the same plane down and both release
+ * its snapshot — the loser of that race must not report a failure for a lock that
+ * is, correctly, already gone.
+ */
+export async function unlockCodeSnapshot(repoRoot, snapshot, deps) {
+    const realRoot = await tryRealpath(repoRoot, deps);
+    if (realRoot === null)
+        return { ok: false };
+    const target = getPlanePaths(realRoot).snapshotPathFor(snapshot.sha);
+    const registrations = await listRegistrations(repoRoot, deps);
+    if (registrations !== null) {
+        const entry = registrations.find((candidate) => candidate.path === target);
+        if (entry === undefined || !entry.locked)
+            return { ok: true };
+    }
+    const result = await deps.execFile("git", ["worktree", "unlock", target], { cwd: repoRoot });
+    return { ok: result.ok };
+}
+/**
+ * Release a snapshot for a manifest whose plane has just been confirmed gone.
+ *
+ * The single place the "unlock only after confirmed wind-down" rule is applied to
+ * a manifest: a legacy manifest has nothing to release, and a pinned one is
+ * unlocked and KEPT on disk. Removal is left to a later bring-up's prune, which
+ * has its own proof requirements.
+ */
+export async function releaseCodeSnapshotForManifest(manifest, deps) {
+    const pinned = planeManifestSnapshot(manifest);
+    if (pinned.kind !== "pinned")
+        return { released: false };
+    const result = await unlockCodeSnapshot(manifest.repoRoot, pinned.snapshot, deps);
+    return { released: result.ok };
+}
+/**
+ * Confirm a recorded snapshot is still the commit it was pinned to.
+ *
+ * Used by the detached runtime and by `plane restart`, which act on what the
+ * MANIFEST says and must not consult the moving operator checkout. It asks only
+ * whether the recorded directory still exists, is a real directory (not a
+ * symlink), and still reports the recorded SHA. It never resolves a replacement
+ * SHA and never repairs anything: a moved or missing snapshot is refused, not
+ * upgraded.
+ */
+export async function revalidateCodeSnapshot(repoRoot, snapshot, deps) {
+    if (!isFullCommitSha(snapshot.sha)) {
+        return { ok: false, reason: "identity-mismatch", message: "the recorded snapshot SHA is not a full commit id" };
+    }
+    const expected = getPlanePaths(repoRoot).snapshotPathFor(snapshot.sha);
+    if (snapshot.path !== expected) {
+        return {
+            ok: false,
+            reason: "unsafe-location",
+            message: "the recorded snapshot path is not the canonical location for its commit",
+        };
+    }
+    const stat = await lstatOrNull(snapshot.path, deps);
+    if (stat === "error") {
+        return { ok: false, reason: "missing", message: `${relativeSnapshotLabel(snapshot.sha)} could not be inspected` };
+    }
+    if (stat === null) {
+        return {
+            ok: false,
+            reason: "missing",
+            message: `${relativeSnapshotLabel(snapshot.sha)} no longer exists; the plane's pinned code is gone`,
+        };
+    }
+    if (stat.isSymbolicLink || !stat.isDirectory) {
+        return {
+            ok: false,
+            reason: "unsafe-location",
+            message: `${relativeSnapshotLabel(snapshot.sha)} is now a symlink or not a directory`,
+        };
+    }
+    const realSnapshot = await tryRealpath(snapshot.path, deps);
+    const expectedReal = await registeredSnapshotPath(repoRoot, snapshot.sha, deps);
+    if (realSnapshot === null || expectedReal === null || realSnapshot !== expectedReal) {
+        return {
+            ok: false,
+            reason: "moved",
+            message: `${relativeSnapshotLabel(snapshot.sha)} no longer resolves to its recorded location`,
+        };
+    }
+    const checkoutSha = await readCheckoutSha(snapshot.path, deps);
+    if (checkoutSha !== snapshot.sha) {
+        return {
+            ok: false,
+            reason: "identity-mismatch",
+            message: `${relativeSnapshotLabel(snapshot.sha)} no longer reports commit ${snapshot.sha.slice(0, 12)}`,
+        };
+    }
+    return { ok: true };
+}

package/build/plane/defaults.js

@@ -9,14 +9,14 @@
  * unused factory rather than hiding inside the logic.
  */
 import { createWriteStream, realpathSync, statSync } from "fs";
-import { mkdir, open, readdir, readFile, rename, stat, unlink, writeFile } from "fs/promises";
+import { lstat, mkdir, open, readdir, readFile, realpath, rename, stat, unlink, writeFile, } from "fs/promises";
 import { execFile as execFileCb, spawn as nodeSpawn } from "child_process";
 import net from "net";
 import os from "os";
 import path from "path";
 import { fileURLToPath } from "url";
 import { PLANE_HEARTBEAT_HEALTH_STATES, } from "./types.js";
-import { isProcessAlive } from "./manifest.js";
+import { isProcessAlive, readPlaneManifest } from "./manifest.js";
 /** Filesystem primitives bound to `node:fs/promises`. */
 export function createPlaneFsDeps() {
     return {
@@ -126,7 +126,12 @@ export function probeTcpPort(host, port, timeoutMs) {
 /** `execFile`, argument arrays only. No shell, ever. */
 export function createPlaneExecFile() {
     return (file, args, options) => new Promise((resolve) => {
-        execFileCb(file, args, { cwd: options.cwd, shell: false, windowsHide: true, timeout: 30_000 }, (error, stdout, stderr) => {
+        execFileCb(file, args, {
+            cwd: options.cwd,
+            shell: false,
+            windowsHide: true,
+            timeout: options.timeoutMs ?? 30_000,
+        }, (error, stdout, stderr) => {
             if (error) {
                 const code = error.code;
                 resolve({ ok: false, error: typeof code === "string" ? code : "command failed" });
@@ -136,6 +141,46 @@ export function createPlaneExecFile() {
         });
     });
 }
+/** Synchronous existence probe for a file, used by the roster's virtualenv lookup. */
+export function planeFileExistsSync(filePath) {
+    try {
+        return statSync(filePath).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Real-I/O bindings for the code-snapshot module (BAPI-1362).
+ *
+ * `lstat` (not `stat`) on purpose: the snapshot module must be able to tell a
+ * symlink from a directory, and `stat` follows the link and hides the difference.
+ * A missing path is reported as `null`; any other failure rejects so the caller
+ * treats it as ambiguous rather than absent.
+ */
+export function createCodeSnapshotDeps(proc = createPlaneProcessDeps()) {
+    const fs = createPlaneFsDeps();
+    return {
+        execFile: createPlaneExecFile(),
+        fs: {
+            realpath: (filePath) => realpath(filePath),
+            lstat: async (filePath) => {
+                try {
+                    const result = await lstat(filePath);
+                    return { isSymbolicLink: result.isSymbolicLink(), isDirectory: result.isDirectory() };
+                }
+                catch (err) {
+                    if (err?.code === "ENOENT")
+                        return null;
+                    throw err;
+                }
+            },
+            mkdir: (dirPath) => fs.mkdir(dirPath),
+        },
+        readManifest: (repoRoot) => readPlaneManifest(repoRoot, fs),
+        proc,
+    };
+}
 /** Child spawning. `shell: false` is pinned: argv arrays only, never a string. */
 export function createPlaneSpawn() {
     return (command, args, options) => {

package/build/plane/endpoint.js

@@ -0,0 +1,41 @@
+/** Loopback spellings that name the plane's `127.0.0.1` host. */
+const LOOPBACK_HOSTNAMES = new Set(["127.0.0.1", "localhost", "[::1]", "::1"]);
+/**
+ * Does `baseUrl` name the plane's own loopback endpoint? Pure.
+ *
+ * Cold start and attach are decisions about THE PLANE, so they only make sense
+ * when the Bridge API the command talks to IS the plane's server. The conductor
+ * default base URL is production; a readiness failure against it says nothing
+ * about a local port, and must keep escalating exactly as before. Loopback
+ * spellings are equivalent (`localhost` and `127.0.0.1` reach the same socket);
+ * the port must match exactly.
+ */
+export function baseUrlNamesPlaneEndpoint(baseUrl, endpoint) {
+    let url;
+    try {
+        url = new URL(baseUrl);
+    }
+    catch {
+        return false;
+    }
+    if (url.protocol !== "http:")
+        return false;
+    const port = url.port === "" ? 80 : Number(url.port);
+    return LOOPBACK_HOSTNAMES.has(url.hostname) && port === endpoint.port;
+}
+/**
+ * The plane endpoint, when `baseUrl` names it; otherwise `null`.
+ *
+ * `null` for an unresolvable plane port too: with no endpoint there is no plane
+ * to cold-start, attach to, or probe.
+ */
+export function planeEndpointForTarget(resolution, baseUrl) {
+    if (!resolution.ok)
+        return null;
+    return baseUrlNamesPlaneEndpoint(baseUrl, resolution.endpoint) ? resolution.endpoint : null;
+}
+export function planeNotApplicableForTarget(resolution, baseUrl) {
+    if (typeof baseUrl !== "string" || baseUrl.length === 0 || !resolution.ok)
+        return "unresolvable";
+    return baseUrlNamesPlaneEndpoint(baseUrl, resolution.endpoint) ? null : "remote";
+}