@bridge_gpt/mcp-server 0.2.59 → 0.2.60

package/build/install-bridge-conductor.js

@@ -54,6 +54,32 @@
  * Neither can produce `complete`: they provision LOCAL capability, and the
  * terminal outcome still turns only on the live server-observed executor claim.
  *
+ * DURABLE-HOST MODE (BAPI-1137). The executor phase below is the supported
+ * bring-up for a *durable host*: an execution home that is not an interactive
+ * shell session, so a sleeping or closed operator laptop no longer stalls a run.
+ * The client command spelling is unchanged — it is still `install conductor` —
+ * and so is every primitive it drives; what this slice does is name the
+ * composition and make its boundaries explicit. Durable-host mode IS that
+ * composition, and nothing more:
+ *
+ *   planning (pure)
+ *     → separately consented unit writing
+ *     → separately consented start
+ *     → read-only local inspection (service state, session/linger durability)
+ *     → bounded server-observed readiness
+ *
+ * `executor install-service` remains the standalone, lifecycle-free generator
+ * for operators who deliberately manage lifecycle themselves.
+ *
+ * HOST OWNERSHIP is an operational selection, not server policy. A durable host
+ * may be operator-operated or Bridge-operated, chosen per repository, and both
+ * choices run IDENTICAL generation and lifecycle logic: `BAPI_BASE_URL` is the
+ * only ownership/location input, while platform paths, unit format, and `PATH`
+ * are machine-specific details rather than ownership signals. Nothing about that
+ * choice reaches `RunPolicy` or any other server policy payload. Bridge-operated
+ * mode is also NON-ALLOCATING: this command can configure a host that has
+ * already been assigned, and it never provisions a fleet or allocates a machine.
+ *
  * The executor phase (BAPI-779) is opt-in via `--executor-id` and runs behind
  * TWO independent consents, per property 3: writing the unit is not consent to
  * start a persistent daemon. Its shape is:
@@ -70,6 +96,13 @@
  * non-fatal: the run prints the exact platform-specific start command and
  * finishes at `complete-with-manual-steps`.
  *
+ * MERGE AUTHORITY IS UNTOUCHED (BAPI-1137). Provisioning a durable host gives
+ * the executor no merge-decision route and no direct GitHub write operation: the
+ * reconciler remains the sole transition authority and the actuator writes only
+ * evidence. Readiness output above must never be worded so as to imply
+ * otherwise — `executor_ready` means an executor is claiming work, not that this
+ * host can merge anything.
+ *
  * The command does NOT persist a repository-level review policy: that is
  * BAPI-694's. The policy selected here is per-run and is reported as such.
  */
@@ -81,6 +114,7 @@ import { MCP_PACKAGE_NAME } from "./mcp-identity.js";
 import { CLAUDE_REVIEW_WORKFLOW_RELPATH, renderClaudeReviewWorkflow, } from "./claude-review-workflow.js";
 import { formatExecutorInstallPreflight, } from "./executor/install-preflight.js";
 import { buildExecutorServiceStartPlan, formatExecutorServiceStartFailure, } from "./executor/service-lifecycle.js";
+import { executorEpicRunIdRefusal, isValidExecutorEpicRunId, } from "./executor/claim-scope.js";
 import { planExecutorServiceInstall, } from "./executor/service-unit.js";
 // ---------------------------------------------------------------------------
 // Options + parsing
@@ -117,6 +151,12 @@ export function getInstallBridgeConductorUsage() {
         "  --executor-id <id>         Stable executor id. Supplying it OPTS IN to the",
         "                             consented executor-provisioning phase below; the",
         "                             phase is skipped entirely without it.",
+        "  --epic-run-id <id>         Claim scope for the generated unit (repeatable).",
+        "  --repo-wide                Claim-scope opt-out: claim from every authorized",
+        "                             repo, unscoped by run. EXACTLY ONE of --epic-run-id",
+        "                             or --repo-wide is required with --executor-id — the",
+        "                             executor refuses to start without one, so a unit",
+        "                             generated without it would fail on every boot.",
         "  --allowed-bot <slug>       claude-review workflow: allowed bot login",
         "  --secret-name <NAME>       claude-review workflow: OAuth token secret NAME",
         "  --branches a,b             claude-review workflow: PR branch triggers",
@@ -152,8 +192,17 @@ export function getInstallBridgeConductorUsage() {
         "hook consent; a degraded ledger reports the module, NODE_MODULE_VERSION, and",
         "failure kind, and never triggers an install, rebuild, or migration.",
         "",
-        "Executor provisioning: `executor install-service` still generates a unit and",
-        "nothing else, and remains available for operators who want the file only.",
+        "Durable-host mode: this command is the supported bring-up for a persistent,",
+        "laptop-independent executor. It composes planning, separately consented unit",
+        "writing, separately consented start, read-only local inspection, and bounded",
+        "server-observed readiness. `executor install-service` still generates a unit and",
+        "nothing else, and remains available for operators who manage lifecycle themselves.",
+        "",
+        "Host ownership (operator-operated or Bridge-operated) is an operational selection,",
+        "not server policy: both run identical generation and lifecycle logic, and",
+        "BAPI_BASE_URL is the only ownership/location input. Bridge-operated mode allocates",
+        "no host — it configures one already assigned. A repository with no assigned durable",
+        "host is NOT ready; escalate that to Bridge operations.",
         "",
         "With --executor-id, this command does the whole leg. A preflight checks the platform,",
         "`wt` / `git` / `claude` on PATH, and an explicit base URL, then reports whether",
@@ -200,6 +249,8 @@ export function parseInstallBridgeConductorArgs(argv) {
     let epicKey;
     let planFile;
     let executorId;
+    const epicRunIds = [];
+    let repoWide = false;
     let allowedBot;
     let secretName;
     let branches;
@@ -231,6 +282,11 @@ export function parseInstallBridgeConductorArgs(argv) {
                     return { status: "error", message: "--skip-workflow takes no value" };
                 skipWorkflow = true;
                 break;
+            case "--repo-wide":
+                if (inline !== undefined)
+                    return { status: "error", message: "--repo-wide takes no value" };
+                repoWide = true;
+                break;
             case "--repo":
             case "--required-check":
             case "--required-checks":
@@ -238,6 +294,7 @@ export function parseInstallBridgeConductorArgs(argv) {
             case "--epic-key":
             case "--plan-file":
             case "--executor-id":
+            case "--epic-run-id":
             case "--allowed-bot":
             case "--secret-name":
             case "--branches": {
@@ -259,6 +316,8 @@ export function parseInstallBridgeConductorArgs(argv) {
                     planFile = value;
                 else if (flag === "--executor-id")
                     executorId = value;
+                else if (flag === "--epic-run-id")
+                    epicRunIds.push(value);
                 else if (flag === "--allowed-bot")
                     allowedBot = value;
                 else if (flag === "--secret-name")
@@ -304,6 +363,47 @@ export function parseInstallBridgeConductorArgs(argv) {
                 "so the bootstrap refuses to write one.",
         };
     }
+    // BAPI-1137 — the claim scope is validated HERE, at parse time, for the same
+    // reason the required-check list is: a unit that cannot start is worse than a
+    // refused invocation, and discovering it costs a reboot to notice.
+    if (executorId !== undefined) {
+        if (epicRunIds.length > 0 && repoWide) {
+            return {
+                status: "error",
+                message: "--epic-run-id and --repo-wide are mutually exclusive: a generated unit carries exactly " +
+                    "one claim scope.",
+            };
+        }
+        if (epicRunIds.length === 0 && !repoWide) {
+            return {
+                status: "error",
+                message: "--executor-id requires an explicit claim scope: pass --epic-run-id <id> (repeatable) or " +
+                    "--repo-wide. The executor refuses to start without one, so a unit generated without it " +
+                    "would install cleanly and then fail on every boot.",
+            };
+        }
+        const seenRunIds = new Set();
+        for (const runId of epicRunIds) {
+            // The SAME shape check `executor install-service` applies, reused rather
+            // than restated: a value that reaches the rendered argument vector is
+            // validated at the point of entry, so a malformed id is one refusal here
+            // instead of a unit that installs and then fails on every boot.
+            if (!isValidExecutorEpicRunId(runId)) {
+                return { status: "error", message: executorEpicRunIdRefusal(runId) };
+            }
+            if (seenRunIds.has(runId)) {
+                return { status: "error", message: `Duplicate --epic-run-id: ${runId}` };
+            }
+            seenRunIds.add(runId);
+        }
+    }
+    else if (epicRunIds.length > 0 || repoWide) {
+        return {
+            status: "error",
+            message: "--epic-run-id / --repo-wide configure the generated executor unit, so they require " +
+                "--executor-id.",
+        };
+    }
     return {
         status: "ok",
         options: {
@@ -319,6 +419,8 @@ export function parseInstallBridgeConductorArgs(argv) {
             branches,
             skipWorkflow,
             executorId,
+            ...(epicRunIds.length > 0 ? { epicRunIds } : {}),
+            ...(repoWide ? { repoWide: true } : {}),
         },
     };
 }
@@ -435,7 +537,12 @@ function buildExecutorProvisioningPlans(executor, executorId, baseUrl,
  * access rather than from a flag, so the unit can only ever serve the
  * repository this install actually authenticated for.
  */
-repos) {
+repos, 
+/**
+ * The claim scope the unit starts with (BAPI-1137). Exactly one side is set,
+ * validated at parse time — a unit without a scope fails on every boot.
+ */
+claimScope) {
     if (executor.platform !== "darwin" && executor.platform !== "linux") {
         return {
             ok: false,
@@ -455,6 +562,13 @@ repos) {
             baseUrl,
             homeDir: executor.homeDir,
             envPath: executor.envPath,
+            // Forwarded so the supervised process starts with the scope the
+            // operator chose. Without it the executor refuses to start (R54) and the
+            // service manager restarts it forever.
+            ...(claimScope.epicRunIds !== undefined && claimScope.epicRunIds.length > 0
+                ? { epicRunIds: claimScope.epicRunIds }
+                : {}),
+            ...(claimScope.repoWide === true ? { repoWide: true } : {}),
         }, platform);
     }
     catch (err) {
@@ -523,23 +637,102 @@ async function runExecutorProvisioningPhase(deps, executor, plans, access) {
         return null;
     }
     deps.log("  the service manager accepted the unit.");
+    // ---- Read-only local inspection (BAPI-1137) ---------------------------
+    // Reported as its own fact, deliberately BEFORE and separately from the server
+    // observation below. "The manager accepted the unit" and "the manager is
+    // running it" and "Bridge has seen it claim" are three different statements,
+    // and an operator who reads one as another is exactly how a dead durable host
+    // gets called healthy.
+    let localState = "unknown";
+    if (executor.inspectServiceState) {
+        try {
+            const inspection = await executor.inspectServiceState(plans.install);
+            localState = inspection.state;
+        }
+        catch {
+            // A probe that throws leaves the state unknown. Nothing here is allowed to
+            // upgrade "I could not ask" into a state.
+            localState = "unknown";
+        }
+    }
+    deps.log(`  local service state (read-only): ${localState}`);
+    deps.log("  that is a LOCAL fact only — it says nothing about whether Bridge has observed a claim.");
+    if (executor.inspectDurability) {
+        let durability = null;
+        try {
+            durability = await executor.inspectDurability(plans.install);
+        }
+        catch {
+            durability = null;
+        }
+        if (durability === null || durability.prerequisite === "unverifiable") {
+            deps.log("  durable session: unverifiable — this run could not establish whether the executor " +
+                "survives logout.");
+        }
+        else if (durability.prerequisite === "configured") {
+            deps.log("  durable session: configured — the executor survives logout on this host.");
+        }
+        else if (durability.prerequisite === "session-bound") {
+            // The probe answered, and what it answered is "a login session exists" —
+            // not "this survives logout". Reported as the qualified fact it is, with
+            // the session prerequisite the operator has to keep true.
+            deps.log("  durable session: session-bound — a login session exists, but the executor is NOT " +
+                "logout-durable on this host.");
+            if (durability.remediation) {
+                deps.log(`  manual action: ${durability.remediation}`);
+            }
+        }
+        else if (durability.prerequisite === "not-configured") {
+            // NOT durably configured, said plainly, with the command the OPERATOR runs.
+            // Bridge never runs it: enabling lingering changes how the host behaves
+            // after logout, and that is the operator's decision on their own machine.
+            deps.log("  durable session: NOT durably configured — the executor stops when you log out.");
+            if (durability.remediation) {
+                deps.log(`  manual action: ${durability.remediation}`);
+            }
+        }
+        else {
+            // `not-applicable`. Unreachable in practice — this phase only runs on
+            // darwin and linux, both of which have a prerequisite — but stated rather
+            // than left as silence, because a fact that renders nothing is
+            // indistinguishable from a fact that was never collected.
+            deps.log("  durable session: not applicable on this platform.");
+        }
+    }
     // ---- Bounded observation ----------------------------------------------
     // Only reached after a SUCCESSFUL start: polling for an executor that was
     // never started would burn the whole budget to learn what we already know.
     deps.log(`  watching the server for an executor claim (up to ${Math.round(EXECUTOR_OBSERVATION_BUDGET_MS / 1000)}s)…`);
     const observation = await observeExecutorReadiness(access, deps.fetchJson, executor);
     if (observation.status === "observed") {
-        deps.log("  the server observed this executor.");
+        deps.log(`  the server observed an executor claim for this repository (requested executor id: ${plans.install.executorId}).`);
+        // BAPI-1137, honestly scoped: the readiness contract this client can read is
+        // REPOSITORY-scoped — `GET .../conductor-readiness?repo_name=` returns
+        // `executor.{liveness_readable,last_seen_at,last_seen_age_seconds,ready}`
+        // and carries no executor id, because the server derives liveness from the
+        // repository's `executor_jobs` rows. So this observation proves an executor
+        // is claiming for this repository; it cannot prove it is THIS executor id.
+        // The honest move is to say so rather than to invent a request or response
+        // field the endpoint does not implement — see the durable-host runbook's
+        // prerequisite note for the server-side contract this needs.
+        deps.log("  note: the readiness contract is repository-scoped and carries no executor id, so this");
+        deps.log("  confirms an executor is claiming for this repository — not specifically the one just started.");
+        deps.log("  if another executor already serves this repository, verify the requested id yourself before");
+        deps.log("  treating this host as the one doing the work.");
         return observation.readiness;
     }
     // The honest degradation: name what WAS achieved and what was not, separately.
-    deps.log("  the unit was written and the service manager started it,");
-    deps.log("  but the server did not observe an executor claim within the budget " +
-        `(${observation.attempts} read(s), ${observation.readFailures} unreadable).`);
+    deps.log(`  started locally, not observed (executor id: ${plans.install.executorId}).`);
+    deps.log(`  local service state (read-only): ${localState}`);
+    deps.log("  the unit was written and the service manager started it, but the server did not observe " +
+        `an executor claim within the budget (${observation.attempts} read(s), ` +
+        `${observation.readFailures} unreadable).`);
     deps.log(observation.lastReady === false
         ? "  the server last reported this repository's executor as stale/not ready."
         : "  the server has not yet seen any executor claim for this repository.");
     deps.log("  executor_ready is NOT claimed — only a live server observation can produce it.");
+    deps.log("  escalate to the host's operating party (operator-operated) or to Bridge operations " +
+        "(Bridge-operated) with the repository name and the executor id above.");
     return null;
 }
 // ---------------------------------------------------------------------------
@@ -847,7 +1040,7 @@ export async function runInstallBridgeConductorCli(argv, deps) {
         // could not be resolved the doctor above has already produced a fatal
         // section, so this fallback only matters for the narrow window where a
         // caller injected a non-fatal doctor.
-        const planned = buildExecutorProvisioningPlans(executor, options.executorId, baseUrl, access ? [access.repoName] : []);
+        const planned = buildExecutorProvisioningPlans(executor, options.executorId, baseUrl, access ? [access.repoName] : [], { epicRunIds: options.epicRunIds, repoWide: options.repoWide });
         if (!planned.ok) {
             deps.errorLog("");
             deps.errorLog(`Executor provisioning refused — ${planned.error}`);