@bridge_gpt/mcp-server 0.2.59 → 0.2.62

package/build/executor/service-lifecycle.js

@@ -36,6 +36,24 @@
  * The command forms address user-domain (per-user) services directly:
  * `launchctl` against `gui/<uid>/<label>` on darwin, and `systemctl --user`
  * on linux.
+ *
+ * FOUR INDEPENDENT FACTS (BAPI-1137). A durable host is described by four
+ * separate observations, and no one of them implies another:
+ *
+ *  1. **Unit-content compliance** — what the generated/on-disk unit DECLARES
+ *     (`service-unit.ts`). A perfect unit file can be sitting unloaded.
+ *  2. **Service-manager state** — what the manager is running RIGHT NOW
+ *     ({@link inspectExecutorServiceState}). The manager may still be running a
+ *     previously loaded definition rather than the current bytes on disk.
+ *  3. **Session persistence** — whether the host keeps running it once nobody is
+ *     logged in ({@link inspectExecutorServiceDurability}). An `active` service
+ *     with lingering off is active exactly until the operator logs out.
+ *  4. **Server-observed readiness** — whether BRIDGE has seen an executor claim.
+ *     Only this one can produce `executor_ready`, and rule 4 above is why:
+ *     nothing local, however green, is evidence for it.
+ *
+ * They are reported separately everywhere, and collapsing any pair of them would
+ * reintroduce exactly the dishonest-green this module is built to refuse.
  */
 import { posixShellQuote } from "../platform-escaping.js";
 /**
@@ -62,6 +80,10 @@ function renderCommand(command) {
 /**
  * Build the platform-specific start sequence.
  *
+ * UNCHANGED by BAPI-1137: start remains separately consented, one-shot, and
+ * non-retrying. The durability inspection added lower in this file is read-only
+ * and has no path to this function or to {@link startExecutorService}.
+ *
  * darwin: `launchctl bootstrap gui/<uid> <plist-path>`
  * linux:  `systemctl --user daemon-reload`, then
  *         `systemctl --user enable --now <unit-name>`
@@ -267,3 +289,117 @@ export async function inspectExecutorServiceState(target, run) {
         return { state: "inactive", probe };
     return { state: "unknown", probe };
 }
+/**
+ * The Linux remediation, verbatim and in one place so the lifecycle module, the
+ * installer, and doctor cannot print three subtly different commands.
+ */
+export const EXECUTOR_LINGER_REMEDIATION = "run `loginctl enable-linger $USER` yourself to keep this user's services running " +
+    "without an active login session (Bridge never runs it for you)";
+/**
+ * The macOS prerequisite. A LaunchAgent bootstrapped into `gui/<uid>` lives in a
+ * user-login domain, which `launchctl(1)` documents as created when the user logs
+ * in at the GUI — so it needs that login to exist, and after a reboot it needs
+ * the user to log in again (automatic login, or a human at the keyboard).
+ */
+export const EXECUTOR_MACOS_SESSION_REMEDIATION = "keep this user logged in at the GUI — a launchd LaunchAgent runs in the gui/<uid> " +
+    "login domain, so after a reboot the user must log in again (e.g. enable automatic " +
+    "login) for the executor to come back";
+/**
+ * Build the strictly read-only durability prerequisite probe for a target.
+ *
+ * linux:  `loginctl show-user <uid> --property=Linger` — a QUERY. `show-user`
+ * reads properties; it cannot enable or disable anything, which is what makes it
+ * safe to run unprompted where `enable-linger` would not be.
+ * darwin: `launchctl print gui/<uid>` — the login domain itself, not a service
+ * inside it. A zero exit means the GUI login domain exists for this uid.
+ *
+ * PURE: consults no runner, no environment, and no filesystem, so an
+ * incompletely described target is refused before anything could be executed.
+ */
+export function buildExecutorServiceDurabilityProbe(target) {
+    if (typeof target.uid !== "number" || !Number.isInteger(target.uid) || target.uid < 0) {
+        return null;
+    }
+    if (target.platform === "linux") {
+        return {
+            stage: "loginctl show-user --property=Linger",
+            executable: "loginctl",
+            args: ["show-user", String(target.uid), "--property=Linger"],
+        };
+    }
+    if (target.platform === "darwin") {
+        return {
+            stage: "launchctl print gui",
+            executable: "launchctl",
+            args: ["print", `gui/${target.uid}`],
+        };
+    }
+    return null;
+}
+/**
+ * Inspect the local session/linger durability prerequisite. STRICTLY read-only:
+ * it issues exactly one query and never enables lingering, starts a service,
+ * reloads a manager, or writes anything.
+ *
+ * Everything the runner returns beyond a recognized state token is DISCARDED —
+ * stdout past the token, stderr entirely, and any thrown value — because a
+ * service manager's output can name paths, units, and environment values that
+ * have no place in operator-facing text.
+ */
+export async function inspectExecutorServiceDurability(target, run) {
+    if (target.platform !== "darwin" && target.platform !== "linux") {
+        return { prerequisite: "not-applicable", probe: null, remediation: null };
+    }
+    const probe = buildExecutorServiceDurabilityProbe(target);
+    if (!probe)
+        return { prerequisite: "unverifiable", probe: null, remediation: null };
+    let exitCode;
+    let stdout;
+    try {
+        const result = await run(probe.executable, probe.args);
+        exitCode = typeof result?.exitCode === "number" ? result.exitCode : 1;
+        stdout = typeof result?.stdout === "string" ? result.stdout : "";
+    }
+    catch {
+        return { prerequisite: "unverifiable", probe, remediation: null };
+    }
+    if (target.platform === "darwin") {
+        // The login domain either exists for this uid or it does not; launchctl
+        // exposes no third answer here, and a non-zero exit is reported as an
+        // unavailable session rather than dressed up as a confirmed absence of
+        // durability the probe did not establish.
+        //
+        // A ZERO exit is NOT `configured`. It says the gui/<uid> domain exists at
+        // this instant — which it does whenever an operator runs `install conductor`
+        // or `doctor` from their own logged-in session — and a LaunchAgent in that
+        // domain is tied to the login, not to the machine being powered on. Calling
+        // it `configured` would let a renderer that means "survives logout" assert
+        // the opposite of what launchd guarantees, so darwin gets its own state and
+        // carries the session prerequisite as the thing to keep true.
+        if (exitCode === 0) {
+            return {
+                prerequisite: "session-bound",
+                probe,
+                remediation: EXECUTOR_MACOS_SESSION_REMEDIATION,
+            };
+        }
+        return {
+            prerequisite: "not-configured",
+            probe,
+            remediation: EXECUTOR_MACOS_SESSION_REMEDIATION,
+        };
+    }
+    if (exitCode !== 0)
+        return { prerequisite: "unverifiable", probe, remediation: null };
+    // `loginctl show-user --property=Linger` prints exactly `Linger=yes|no`. Only
+    // those two tokens are mapped; anything else is unverifiable rather than a
+    // guess derived from a format this module does not recognize.
+    const match = stdout.match(/^\s*Linger=(\S+)\s*$/m);
+    const value = match?.[1]?.toLowerCase();
+    if (value === "yes")
+        return { prerequisite: "configured", probe, remediation: null };
+    if (value === "no") {
+        return { prerequisite: "not-configured", probe, remediation: EXECUTOR_LINGER_REMEDIATION };
+    }
+    return { prerequisite: "unverifiable", probe, remediation: null };
+}