@bridge_gpt/mcp-server 0.2.59 → 0.2.62

package/build/doctor.js

@@ -10,9 +10,14 @@
  * found/missing plus the exact per-OS manual install command for each missing one.
  *
  * The audience is security-conscious/corporate, so the doctor is STRICTLY
- * read-only: no `--fix`, no auto-install, no npm `postinstall`, no terminal
- * spawning, no MCP server startup. It only ever runs read-only PATH probes
- * (`which`/`where`, `bash --version`, `git rev-parse`) through the injected deps.
+ * read-only: no `--fix`, no auto-install, no npm `postinstall`, no interactive
+ * terminal spawning, no MCP server startup. Every child process it starts is a
+ * QUERY: read-only PATH probes (`which`/`where`, `bash --version`,
+ * `git rev-parse`) and, on a host that has generated executor service units, the
+ * one read-only session probe that section issues (`loginctl show-user
+ * --property=Linger` / `launchctl print gui/<uid>`, BAPI-1137). Nothing here can
+ * reach a mutating lifecycle verb — `enable-linger`, `bootstrap`, `start` and
+ * their kin exist in this file only as remediation TEXT the operator runs.
  */
 import { readdir, readFile, stat } from "fs/promises";
 import { spawn } from "child_process";
@@ -29,7 +34,8 @@ import { resolveExecutorAgentAdapter } from "./agent-launchers/executor-adapter-
 import { parseDefaultOnEnvFlag } from "./env-flags.js";
 import { createBridgeApiUrls } from "./bridge-api-urls.js";
 import { probeToolSurface } from "./tool-surface-gating.js";
-import { resolveBapiCredentials } from "./credential-store.js";
+import { readStoredBinding, resolveBapiCredentials } from "./credential-store.js";
+import { listEpicLaunchProfiles } from "./epic-launch-profile.js";
 import { resolveConductorBridgeApiAccess } from "./conductor/bridge-api-client.js";
 import { getLiveRepositoryConductors, getParseDispatcherHealth, } from "./epic-shared/bridge-client.js";
 import { resolveRequiredStartTicketsRepoName } from "./start-tickets-repo.js";
@@ -39,7 +45,7 @@ import { MCP_SERVER_NAME, MCP_PACKAGE_NAME, } from "./mcp-identity.js";
 import { DEFAULT_AGENT_NAME, resolveAgentSpec, isAgentName, formatValidAgentNames, } from "./agent-registry.js";
 import { getDoctorPrereqDescriptors, probePrerequisite, } from "./start-tickets-prereqs.js";
 import { resolveProfiles } from "./mcp-profile.js";
-import { executorLaunchdDirForHome, executorSystemdDirForHome, executorIdFromLaunchdFilename, executorIdFromSystemdFilename, inspectExecutorServiceArtifact, EXECUTOR_SERVICE_BASE_URL_ENV, } from "./executor/index.js";
+import { executorLaunchdDirForHome, executorSystemdDirForHome, executorIdFromLaunchdFilename, executorIdFromSystemdFilename, inspectExecutorServiceArtifact, inspectExecutorServiceDurability, EXECUTOR_SERVICE_BASE_URL_ENV, } from "./executor/index.js";
 import { DEFAULT_BAPI_BASE_URL } from "./executor/credentials.js";
 import { detectClaudeLogin, formatClaudeLoginAdvisory } from "./claude-login.js";
 import { validateBranchName } from "./base-ref.js";
@@ -1005,6 +1011,53 @@ export function formatToolSurfaceDiagnosticReport(diag) {
     lines.push("to observe surface changes; no project MCP configuration change is required.");
     return lines.join("\n");
 }
+// ---------------------------------------------------------------------------
+// Executor provisioning diagnostics (BAPI-688) — STRICTLY read-only.
+//
+// Enumerates the deterministic, convention-named executor service units this
+// package generates (`executor install-service`) and reports their non-secret
+// configuration plus credential readiness. It never writes, never runs a
+// MUTATING `launchctl`/`systemctl`/`loginctl` verb, and — like every advisory
+// section — never influences the doctor exit code.
+//
+// It does spawn ONE child process, and only on a host that already has such a
+// unit: the read-only session-durability query added by BAPI-1137, through
+// `defaultReadOnlyLifecycleRunner` below. That is a real change to this
+// section's behavior and is stated here rather than left to be discovered —
+// with no injected runner it issues none, and the fact degrades to
+// `unverifiable` rather than being guessed.
+//
+// Discovery is derived SOLELY from the fixed OS directory + filename prefix, not
+// from `.bridge/install-state.json`: install state is conductor install history,
+// not an artifact registry, so a unit written by hand or by another machine's
+// operator is still found, and a stale state entry never invents one.
+// ---------------------------------------------------------------------------
+/**
+ * Shell-free runner for the ONE read-only durability query this section issues
+ * (BAPI-1137).
+ *
+ * `shell: false` plus an argument ARRAY, matching every other service-manager
+ * invocation in this package: a uid or identifier is data here, never syntax.
+ * The probes it runs — `loginctl show-user --property=Linger`,
+ * `launchctl print gui/<uid>` — are queries; nothing in this file can reach a
+ * mutating lifecycle command. Output is captured only so the lifecycle module
+ * can map a recognized state token, and is never surfaced.
+ */
+function defaultReadOnlyLifecycleRunner(executable, args) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(executable, args, { shell: false, stdio: ["ignore", "pipe", "pipe"] });
+        let stdout = "";
+        let stderr = "";
+        child.stdout?.on("data", (chunk) => {
+            stdout += chunk.toString("utf-8");
+        });
+        child.stderr?.on("data", (chunk) => {
+            stderr += chunk.toString("utf-8");
+        });
+        child.on("error", reject);
+        child.on("close", (code) => resolve({ exitCode: code ?? 1, stdout, stderr }));
+    });
+}
 /** Where generated units live, and how their filenames encode the executor id. */
 function resolveExecutorServiceConvention(platform, homeDir) {
     if (platform === "darwin") {
@@ -1097,6 +1150,36 @@ export async function collectExecutorServiceDiagnostics(deps) {
     const pathApi = path.posix;
     const units = [];
     const warnings = [];
+    // BAPI-1137 — the host-level durability prerequisite, probed ONCE per run
+    // rather than once per unit: lingering and the GUI login domain are properties
+    // of the host and the user, not of any particular unit. Without an injected
+    // read-only runner no command is issued at all and the fact stays
+    // `unverifiable`, so a caller that supplies no runner keeps a zero-probe run.
+    let durability = {
+        prerequisite: "unverifiable",
+        remediation: null,
+    };
+    if (deps.runLifecycleCommand) {
+        try {
+            const inspection = await inspectExecutorServiceDurability({
+                platform: deps.platform === "darwin" ? "darwin" : "linux",
+                // The durability probe addresses the USER's session/linger state, not
+                // a unit, so it needs neither a unit path nor a service identifier.
+                unitPath: "",
+                serviceIdentifier: "durability-probe",
+                uid: deps.uid ?? null,
+            }, deps.runLifecycleCommand);
+            durability = {
+                prerequisite: inspection.prerequisite,
+                remediation: inspection.remediation,
+            };
+        }
+        catch {
+            // Sanitized: a probe that throws leaves the fact unverifiable rather than
+            // surfacing exception text or inventing a state.
+            durability = { prerequisite: "unverifiable", remediation: null };
+        }
+    }
     for (const name of matching) {
         const unitPath = pathApi.join(convention.dir, name);
         const executorId = convention.idFromFilename(name) ?? name;
@@ -1120,12 +1203,33 @@ export async function collectExecutorServiceDiagnostics(deps) {
                 baseUrlClass: "missing",
                 repos: [],
                 credentials: [],
-                warnings: ["unit could not be read; its configuration cannot be verified."],
+                // A unit whose bytes could not be read establishes NOTHING about what it
+                // declares. `unverifiable`, never `confirmed-absent`.
+                noStandingGithubWriteCredential: "unverifiable",
+                warnings: [
+                    "unit could not be read; its configuration cannot be verified.",
+                    "regenerate it through durable-host mode (`install conductor`) if this persists.",
+                ],
             });
             continue;
         }
         const inspection = inspectExecutorServiceArtifact(convention.kind, content);
         const unitWarnings = [...inspection.problems];
+        // BAPI-1137 — the classification comes from the GENERATOR's shared helper,
+        // applied to the unit read off disk. doctor maintains no second notion of
+        // what "declares no GitHub write credential" means, so a unit this section
+        // calls compliant is exactly a unit the generator would agree to write.
+        const credentialDeclaration = inspection.noStandingGithubWriteCredential;
+        unitWarnings.push(...inspection.credentialDeclarationProblems);
+        if (credentialDeclaration === "present") {
+            unitWarnings.push("this unit declares something outside the closed durable-host contract — regenerate it " +
+                "through durable-host mode (`install conductor`) and remove the hand edit.");
+        }
+        else if (credentialDeclaration === "unverifiable") {
+            unitWarnings.push("this unit could only be parsed partially, so the no-standing-GitHub-write-credential " +
+                "property could not be established — regenerate it through durable-host mode " +
+                "(`install conductor`).");
+        }
         let baseUrlClass;
         if (!inspection.baseUrl) {
             baseUrlClass = "missing";
@@ -1153,10 +1257,24 @@ export async function collectExecutorServiceDiagnostics(deps) {
             baseUrlClass,
             repos: inspection.repos,
             credentials,
+            noStandingGithubWriteCredential: credentialDeclaration,
             warnings: unitWarnings,
         });
     }
-    return { status: "collected", units, warnings };
+    return { status: "collected", units, warnings, durability };
+}
+/**
+ * The rendered name of the BAPI-1137 credential diagnostic.
+ *
+ * Named for the NARROW claim it actually makes — the unit's own declarations —
+ * rather than something broader like "host holds no GitHub credential", which
+ * the check cannot support and an operator would reasonably read as covering
+ * their SSH keys, keychain, and `gh` login.
+ */
+export const EXECUTOR_UNIT_CREDENTIAL_DIAGNOSTIC_NAME = "unit-declares-no-github-write-credential";
+/** How each classification renders, once, so the three spellings cannot drift. */
+function formatCredentialDeclarationLine(classification) {
+    return `      ${EXECUTOR_UNIT_CREDENTIAL_DIAGNOSTIC_NAME}: ${classification}`;
 }
 /**
  * Render the advisory "Executor provisioning" section (pure formatting — no I/O).
@@ -1179,6 +1297,7 @@ export function formatExecutorServiceDiagnosticsReport(diagnostics) {
         lines.push(`      executor id: ${unit.executorId}`);
         lines.push(`      ${EXECUTOR_SERVICE_BASE_URL_ENV}: ${unit.baseUrl ?? "(absent)"} [${unit.baseUrlClass}]`);
         lines.push(`      repos: ${unit.repos.length > 0 ? unit.repos.join(", ") : "(none parsed)"}`);
+        lines.push(formatCredentialDeclarationLine(unit.noStandingGithubWriteCredential));
         for (const cred of unit.credentials) {
             lines.push(cred.resolved
                 ? `      credential ${cred.target}: resolved (source: ${cred.source})`
@@ -1188,11 +1307,52 @@ export function formatExecutorServiceDiagnosticsReport(diagnostics) {
             lines.push(`WARN  ${unit.path}: ${warning}`);
         }
     }
+    // The host-level durability prerequisite, rendered SEPARATELY from every unit
+    // above: it is a property of this host and user, and attaching it to a unit
+    // would imply the two were one fact.
+    lines.push("");
+    if (diagnostics.durability.prerequisite === "configured") {
+        lines.push("found durable session: configured — services keep running without an active login.");
+    }
+    else if (diagnostics.durability.prerequisite === "session-bound") {
+        // Deliberately NOT a "found" line. The prerequisite this platform can check
+        // is satisfied, but what it establishes is a login session, not logout
+        // durability, and saying otherwise would contradict launchd.
+        lines.push("WARN  durable session: session-bound — a login session exists, but it is NOT logout-durable.");
+        if (diagnostics.durability.remediation) {
+            lines.push(`      operator action: ${diagnostics.durability.remediation}`);
+        }
+        lines.push("      A LaunchAgent stops with the login it runs under; closing the lid or logging out", "      stops the executor. doctor performed a READ-ONLY query and changed nothing.");
+    }
+    else if (diagnostics.durability.prerequisite === "not-configured") {
+        lines.push("WARN  durable session: NOT durably configured for this host.");
+        if (diagnostics.durability.remediation) {
+            lines.push(`      remediation (operator-run): ${diagnostics.durability.remediation}`);
+        }
+        lines.push("      doctor performed a READ-ONLY query only: it did not run `loginctl enable-linger`,", "      change any session setting, or alter the exit code.");
+    }
+    else if (diagnostics.durability.prerequisite === "not-applicable") {
+        lines.push("SKIP  durable session: this platform has no session/linger prerequisite.");
+    }
+    else {
+        lines.push("SKIP  durable session: unverifiable — the read-only probe produced no recognized answer.", "      That is not evidence that this host is, or is not, durably configured.");
+    }
+    lines.push("");
+    lines.push("Unit-content compliance and service-manager state are INDEPENDENT facts: the manager may");
+    lines.push("still be running a previously loaded definition rather than the bytes currently on disk, so a");
+    lines.push("compliant unit file is not evidence about the running process, and neither is evidence that");
+    lines.push("Bridge has observed an executor claim.");
+    lines.push("");
+    lines.push(`The ${EXECUTOR_UNIT_CREDENTIAL_DIAGNOSTIC_NAME} fact covers the unit's OWN declarations —`);
+    lines.push("its environment keys and its arguments. Host-wide SSH keys and agents, login keychains, `gh`");
+    lines.push("login state, git credential helpers, and independently managed Claude worker authentication");
+    lines.push("are outside it and are never inspected or asserted here.");
     lines.push("");
     lines.push("Generated units carry only the base URL, the generating shell's PATH, repositories, and", "executor id — credentials resolve at");
     lines.push("launch time from BAPI_API_KEY or the user-scoped bapi:<repo> store, so no key value is stored on");
     lines.push("disk or printed here. Starting, stopping, and enabling a unit stay operator-managed. This section");
-    lines.push("is advisory and never changes the doctor exit code.");
+    lines.push("is advisory — including the credential-declaration and durable-session facts, which are excluded");
+    lines.push("from required-prerequisite computation — and never changes the doctor exit code.");
     return lines.join("\n");
 }
 export async function collectPlaneCredentialDiagnostic(deps) {
@@ -1370,6 +1530,12 @@ export async function collectOperationalAdvisories(deps) {
         }
     }
     // BAPI-1102 — a pure path-presence check, using the SAME injected `stat` and
+    // (BAPI-1137) still ONLY a path-presence check: the helpers' CONTENTS are
+    // never read, they are never executed, and neither file is ever deleted. The
+    // guidance below names durable-host mode as their replacement; removing them
+    // stays an operator step, because they live outside this repository and
+    // product code that deleted files in `~/.local/bin` would be a far larger
+    // authority than a read-only diagnostic should hold.
     // `homedir` seams every other advisory here uses, so it stays deterministic
     // under test and reaches no real filesystem in one. A `stat` that throws is
     // "absent"; it is never retried, and a permission error is not reported as a
@@ -1437,8 +1603,10 @@ export function formatOperationalAdvisoryReport(diagnostic) {
         for (const helper of diagnostic.legacyDriveHelpers) {
             lines.push(`           ${helper}`);
         }
-        lines.push("           These predate the scoped two-phase bring-up and are retired. Confirm\n" +
-            "           `drive-epic <EPIC> --plan-file <dag>` works for you, then remove them.\n" +
+        lines.push("           These predate the scoped two-phase bring-up and are retired. The supported\n" +
+            "           replacement is DURABLE-HOST MODE: run `install conductor` to plan, write, and\n" +
+            "           start the executor as a persistent service, then confirm\n" +
+            "           `drive-epic <EPIC> --plan-file <dag>` works for you, and remove them.\n" +
             "           doctor performed a PATH-PRESENCE check only: it did not run, read, or\n" +
             "           modify either file, and it cannot delete them for you.");
     }
@@ -1447,12 +1615,78 @@ export function formatOperationalAdvisoryReport(diagnostic) {
     return lines.join("\n");
 }
 /**
- * CLI entry for the read-only `doctor` subcommand. Returns a process exit code.
- * Help returns 0; parser errors return 1; otherwise it prints the report and
- * returns 0 when every required prerequisite is present, non-zero when any is
- * missing or the platform is unsupported. Never installs, mutates, spawns tabs,
- * or starts the MCP server.
+ * Read-only inventory of this host's epic-launch profiles and whether each
+ * one's credential binding matches its target. It reports; it never binds or
+ * migrates anything.
  */
+export async function collectEpicLaunchProfileDiagnostic(deps) {
+    const listing = await listEpicLaunchProfiles(deps);
+    if (!listing.ok)
+        return { store: "unreadable", message: listing.message };
+    if (!listing.present)
+        return { store: "absent" };
+    const host = deps.hostname();
+    const profiles = [];
+    for (const entry of listing.entries) {
+        if (!entry.validation.ok) {
+            profiles.push({ name: entry.name, usable: false, problem: entry.validation.kind });
+            continue;
+        }
+        const p = entry.validation.profile;
+        const bound = await readStoredBinding(p.credentialRef.target, {
+            env: deps.env,
+            homedir: deps.homedir,
+            platform: process.platform,
+            readFile: deps.readFile,
+            // Presence probe via read: the binding reader treats any failure as unbound.
+            stat: async (filePath) => {
+                await deps.readFile(filePath);
+                return { mode: 0o600 };
+            },
+        });
+        const hostMatches = p.host === host;
+        const credentialBinding = bound === null ? "unbound" : bound === p.baseUrl ? "matches" : "different";
+        profiles.push({
+            name: p.name,
+            usable: hostMatches && credentialBinding === "matches",
+            target: p.baseUrl,
+            repo: p.repoName,
+            mode: p.executionMode,
+            hostMatches,
+            credentialBinding,
+        });
+    }
+    return { store: "present", profiles };
+}
+/** Render the section, or `null` when this host has no profile store. */
+export function formatEpicLaunchProfileDiagnosticReport(diagnostic) {
+    if (diagnostic.store === "absent")
+        return null;
+    const lines = ["", "Epic launch profiles (read-only)", ""];
+    if (diagnostic.store === "unreadable") {
+        lines.push(`  [warn] ${diagnostic.message}`);
+        return lines.join("\n");
+    }
+    if (diagnostic.profiles.length === 0)
+        lines.push("  (none)");
+    for (const p of diagnostic.profiles) {
+        if (p.problem !== undefined) {
+            lines.push(`  [fail] ${p.name}: ${p.problem} — re-run \`install conductor --launch-profile ${p.name}\`.`);
+            continue;
+        }
+        const tag = p.usable ? "[ok]  " : "[fail]";
+        lines.push(`  ${tag} ${p.name}: ${p.target} repo=${p.repo} mode=${p.mode}`);
+        if (p.hostMatches === false)
+            lines.push("         approved on a different host — profiles are host-local.");
+        if (p.credentialBinding === "unbound") {
+            lines.push("         stored credential not yet approved for this target — re-run guided setup to bind it.");
+        }
+        else if (p.credentialBinding === "different") {
+            lines.push("         stored credential is approved for a DIFFERENT target — a launch will refuse to send it.");
+        }
+    }
+    return lines.join("\n");
+}
 export async function runDoctorCli(argv, overrides = {}) {
     const log = overrides.log ?? ((m) => console.log(m));
     const errorLog = overrides.errorLog ?? ((m) => console.error(m));
@@ -1688,6 +1922,13 @@ export async function runDoctorCli(argv, overrides = {}) {
                     ((p) => readFile(p, "utf-8")),
                 stat: overrides.executorService?.stat ?? injectedFs.stat ?? ((p) => stat(p)),
                 resolveCredentials: overrides.executorService?.resolveCredentials,
+                // BAPI-1137 — the durability prerequisite needs a uid and a read-only
+                // runner. `process.getuid` is absent on win32, where a null uid simply
+                // leaves the fact unverifiable rather than interpolating `undefined`
+                // into a domain target.
+                uid: overrides.executorService?.uid ??
+                    (typeof process.getuid === "function" ? process.getuid() : null),
+                runLifecycleCommand: overrides.executorService?.runLifecycleCommand ?? defaultReadOnlyLifecycleRunner,
             };
             const executorDiagnostics = await collectExecutorServiceDiagnostics(executorDeps);
             log(formatExecutorServiceDiagnosticsReport(executorDiagnostics));
@@ -1745,6 +1986,27 @@ export async function runDoctorCli(argv, overrides = {}) {
             }));
         }
     }
+    // Advisory epic-launch profile section (BAPI-1260). Read-only: it never binds,
+    // migrates, or rewrites a profile or a credential — setup does that, with
+    // consent. Never affects the exit code.
+    if (overrides.launchProfiles !== false) {
+        try {
+            const injectedFs = deps;
+            const report = formatEpicLaunchProfileDiagnosticReport(await collectEpicLaunchProfileDiagnostic({
+                env: overrides.launchProfiles?.env ?? deps.env,
+                homedir: overrides.launchProfiles?.homedir ?? injectedFs.homedir ?? os.homedir,
+                readFile: overrides.launchProfiles?.readFile ??
+                    injectedFs.readFile ??
+                    ((p) => readFile(p, "utf-8")),
+                hostname: overrides.launchProfiles?.hostname ?? os.hostname,
+            }));
+            if (report !== null)
+                log(report);
+        }
+        catch {
+            /* advisory only: an unexpected failure drops the section, never the doctor */
+        }
+    }
     // Advisory operational-advisories section (BAPI-963). Read by the operator
     // asking "what is already running?" right after the readiness sections above.
     //