@bridge_gpt/mcp-server 0.2.18 → 0.2.19

package/build/doctor.js

@@ -51,6 +51,12 @@ export function getDoctorUsage() {
         "bootstrap-field completeness, and repository-indexing state. It performs",
         "read-only GETs only and never affects the exit code.",
         "",
+        "Conductor ledger / native-module diagnostics (the SQLite ledger's native",
+        "binding load status and Node-version skew) live under a separate command:",
+        "  conductor doctor",
+        "That command is likewise strictly read-only — it does not install, rebuild,",
+        "migrate, or write ledger files.",
+        "",
         "Exit code: 0 when all required prerequisites are present, non-zero otherwise.",
     ].join("\n");
 }
@@ -171,6 +177,8 @@ export function formatDoctorReport(platform, agent, collection) {
     lines.push(anyMissing
         ? "Some prerequisites are missing — install the ones above manually, then re-run doctor."
         : "All required prerequisites are present.");
+    // Advisory pointer only (BAPI-526): informational, independent of exit code.
+    lines.push("For conductor ledger/native-module diagnostics, run: conductor doctor");
     return lines.join("\n");
 }
 // ---------------------------------------------------------------------------

package/build/executor/cli.js

@@ -0,0 +1,229 @@
+/**
+ * Executor CLI subcommand (BAPI-534, TDD §12/§13).
+ *
+ * `mcp-server executor --repo <name> [...]` — parses args, resolves default deps,
+ * credentials, and the HTTP client, then runs the poll/claim loop. Never starts
+ * the MCP server; all user-facing diagnostics go to stderr; secrets are never
+ * printed. Returns numeric exit codes rather than throwing at the top level.
+ */
+import os from "node:os";
+import { VERSION } from "../version.generated.js";
+import { resolveWorktrunkBinary } from "../start-tickets-prereqs.js";
+import { resolveStartTicketsRepoName } from "../start-tickets-repo.js";
+import { createDefaultExecutorDeps } from "./deps.js";
+import { resolveExecutorApiAccess, } from "./credentials.js";
+import { createExecutorHttpClient } from "./http-client.js";
+import { runExecutor } from "./runner.js";
+import { runExecutorWatchCli } from "./watch-cli.js";
+/** Fixed executor timing/behavior defaults. */
+const DEFAULT_POLL_INTERVAL_MS = 15_000;
+const DEFAULT_HEARTBEAT_INTERVAL_MS = 60_000;
+const DEFAULT_DEADMAN_MS = 120_000;
+const DEFAULT_TERM_GRACE_MS = 10_000;
+const DEFAULT_BASE_BRANCH = "main";
+const DEFAULT_JOB_TIMEOUT_SECONDS = 20 * 60;
+const DEFAULT_MAX_CONCURRENT = 1;
+export function getExecutorUsage() {
+    return [
+        "Usage: mcp-server executor --repo <name> [--repo <name> ...] [options]",
+        "",
+        "Runs the Epic Conductor v2 local executor: poll → claim → spawn → heartbeat.",
+        "",
+        "Options:",
+        "  --repo <name>                 Repo to serve (repeatable).",
+        "  --repos=<a,b>                 Comma-separated repos.",
+        "  --executor-id <id>            Stable executor id (default: <hostname>-<pid>).",
+        "  --max-concurrent <n>          Max concurrent jobs (>= 1, default 1).",
+        "  --once                        Run a single preflight/claim cycle and exit.",
+        "  --poll-interval-ms <n>        Poll interval (default 15000).",
+        "  --heartbeat-interval-ms <n>   Heartbeat interval (default 60000).",
+        "  --deadman-ms <n>              Dead-man self-kill window (default 120000).",
+        "  --base-branch <name>          Base branch (default main).",
+        "  --no-advisory-parser          Disable the advisory stream-json parser.",
+        "  -h, --help                    Show this help.",
+    ].join("\n");
+}
+function parseIntArg(value, flag) {
+    if (value === undefined)
+        return { ok: false, message: `${flag} requires a numeric value` };
+    const n = Number(value);
+    if (!Number.isFinite(n) || !Number.isInteger(n)) {
+        return { ok: false, message: `${flag} must be an integer` };
+    }
+    return { ok: true, value: n };
+}
+/** Parse the executor CLI arguments into resolved options (pure, synchronous). */
+export function parseExecutorArgs(argv, context) {
+    const repos = [];
+    let executorId;
+    let maxConcurrent = DEFAULT_MAX_CONCURRENT;
+    let once = false;
+    let pollIntervalMs = DEFAULT_POLL_INTERVAL_MS;
+    let heartbeatIntervalMs = DEFAULT_HEARTBEAT_INTERVAL_MS;
+    let deadmanMs = DEFAULT_DEADMAN_MS;
+    let baseBranch = DEFAULT_BASE_BRANCH;
+    let advisoryParserEnabled = true;
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === "--help" || arg === "-h")
+            return { kind: "help" };
+        else if (arg === "--repo") {
+            const v = argv[++i];
+            if (!v)
+                return { kind: "error", message: "--repo requires a value" };
+            repos.push(v);
+        }
+        else if (arg.startsWith("--repos=")) {
+            repos.push(...arg.slice("--repos=".length).split(",").map((s) => s.trim()).filter(Boolean));
+        }
+        else if (arg === "--repos") {
+            const v = argv[++i];
+            if (!v)
+                return { kind: "error", message: "--repos requires a value" };
+            repos.push(...v.split(",").map((s) => s.trim()).filter(Boolean));
+        }
+        else if (arg === "--executor-id") {
+            executorId = argv[++i];
+            if (!executorId)
+                return { kind: "error", message: "--executor-id requires a value" };
+        }
+        else if (arg === "--max-concurrent") {
+            const r = parseIntArg(argv[++i], "--max-concurrent");
+            if (!r.ok)
+                return { kind: "error", message: r.message };
+            maxConcurrent = r.value;
+        }
+        else if (arg === "--once") {
+            once = true;
+        }
+        else if (arg === "--poll-interval-ms") {
+            const r = parseIntArg(argv[++i], "--poll-interval-ms");
+            if (!r.ok)
+                return { kind: "error", message: r.message };
+            pollIntervalMs = r.value;
+        }
+        else if (arg === "--heartbeat-interval-ms") {
+            const r = parseIntArg(argv[++i], "--heartbeat-interval-ms");
+            if (!r.ok)
+                return { kind: "error", message: r.message };
+            heartbeatIntervalMs = r.value;
+        }
+        else if (arg === "--deadman-ms") {
+            const r = parseIntArg(argv[++i], "--deadman-ms");
+            if (!r.ok)
+                return { kind: "error", message: r.message };
+            deadmanMs = r.value;
+        }
+        else if (arg === "--base-branch") {
+            const v = argv[++i];
+            if (!v)
+                return { kind: "error", message: "--base-branch requires a value" };
+            baseBranch = v;
+        }
+        else if (arg === "--no-advisory-parser") {
+            advisoryParserEnabled = false;
+        }
+        else {
+            return { kind: "error", message: `unknown argument: ${arg}` };
+        }
+    }
+    if (repos.length === 0) {
+        return { kind: "error", message: "at least one --repo (or --repos=a,b) is required" };
+    }
+    if (maxConcurrent < 1) {
+        return { kind: "error", message: "--max-concurrent must be >= 1" };
+    }
+    const executorIdFinal = executorId && executorId.trim().length > 0
+        ? executorId.trim()
+        : `${context.hostname}-${context.pid}`;
+    const options = {
+        executorId: executorIdFinal,
+        repos,
+        repoName: repos[0],
+        maxConcurrent,
+        pollIntervalMs,
+        heartbeatIntervalMs,
+        deadmanMs,
+        termGraceMs: DEFAULT_TERM_GRACE_MS,
+        once,
+        worktrunkBinary: resolveWorktrunkBinary(context.platform, context.env),
+        baseBranch,
+        advisoryParserEnabled,
+        defaultJobTimeoutSeconds: DEFAULT_JOB_TIMEOUT_SECONDS,
+    };
+    return { kind: "ok", options };
+}
+function hasRepoFlag(argv) {
+    return argv.some((a) => a === "--repo" || a === "--repos" || a.startsWith("--repos="));
+}
+/** Wire and run the executor CLI. Returns a numeric exit code (never throws). */
+export async function runExecutorCli(argv, overrides = {}) {
+    const errorLog = overrides.errorLog ?? ((m) => console.error(m));
+    // `executor watch <job>` is a READ-ONLY log-attach subcommand (BAPI-535). It
+    // owns the rest of argv and never runs the poll/claim loop or resolves executor
+    // credentials — it only tails a locally-registered worker log.
+    if (argv[0] === "watch") {
+        return runExecutorWatchCli(argv.slice(1));
+    }
+    const deps = overrides.deps ?? createDefaultExecutorDeps();
+    const context = overrides.context ?? {
+        hostname: os.hostname(),
+        pid: process.pid,
+        platform: process.platform,
+        env: process.env,
+    };
+    // Repo fallback: when no --repo/--repos was passed, resolve via the shared
+    // start-tickets repo resolver (BAPI_REPO_NAME / .bridge/config).
+    let effectiveArgv = argv;
+    if (!hasRepoFlag(argv)) {
+        const fallback = await resolveStartTicketsRepoName({
+            env: deps.env,
+            cwd: deps.cwd,
+            readFile: deps.readFile,
+        });
+        if (fallback)
+            effectiveArgv = ["--repo", fallback, ...argv];
+    }
+    const parsed = parseExecutorArgs(effectiveArgv, context);
+    if (parsed.kind === "help") {
+        errorLog(getExecutorUsage());
+        return 0;
+    }
+    if (parsed.kind === "error") {
+        errorLog(`Error: ${parsed.message}\n\n${getExecutorUsage()}`);
+        return 1;
+    }
+    const options = parsed.options;
+    // Resolve credentials for EVERY configured repo so multi-repo mode sends the
+    // correct repo-bound `X-API-Key` per claim/heartbeat/complete/fail — not just
+    // the first repo's key. Uses the (injectable) single-repo resolver per repo.
+    const resolveApi = overrides.resolveApiAccess ?? resolveExecutorApiAccess;
+    const apiKeyByRepo = {};
+    let baseUrl = "";
+    for (const repo of options.repos) {
+        const access = await resolveApi(repo, deps);
+        if (!access.ok) {
+            errorLog(`Error: ${access.error}`);
+            return 1;
+        }
+        apiKeyByRepo[repo] = access.apiKey;
+        baseUrl = access.baseUrl;
+    }
+    const createHttpClient = overrides.createHttpClient ?? createExecutorHttpClient;
+    const httpClient = createHttpClient({
+        baseUrl,
+        apiKey: apiKeyByRepo[options.repoName],
+        apiKeyByRepo,
+        mcpVersion: VERSION,
+        fetch: deps.fetch,
+    });
+    const run = overrides.runExecutor ?? runExecutor;
+    try {
+        return await run(options, deps, httpClient);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        errorLog(`Error: executor exited unexpectedly: ${message.slice(0, 200)}`);
+        return 1;
+    }
+}

package/build/executor/credentials.js

@@ -0,0 +1,65 @@
+/**
+ * Executor Bridge API access resolution (BAPI-534, TDD §7).
+ *
+ * Resolves the `BAPI_API_KEY` + base URL for the executor's HTTP calls ONLY
+ * through the shared credential store (`resolveBapiCredentials`) — never by
+ * reading worktree-local MCP config, and never leaking secret values into
+ * diagnostics/results.
+ */
+import { resolveBapiCredentials } from "../credential-store.js";
+/** Default Bridge API base URL when `BAPI_BASE_URL` is unset/blank. */
+export const DEFAULT_BAPI_BASE_URL = "https://bridgegpt-api.com";
+function resolveBaseUrl(env) {
+    const raw = env.BAPI_BASE_URL;
+    if (typeof raw === "string" && raw.trim().length > 0) {
+        return raw.trim().replace(/\/+$/, "");
+    }
+    return DEFAULT_BAPI_BASE_URL;
+}
+/**
+ * Resolve API access for a single repo. Returns a structured, secret-free
+ * failure for credential-not-found, read/parse failure, missing key, or an
+ * invalid repo name — never throwing, never echoing credential-file contents.
+ */
+export async function resolveExecutorApiAccess(repoName, deps) {
+    const trimmed = typeof repoName === "string" ? repoName.trim() : "";
+    if (trimmed.length === 0) {
+        return { ok: false, error: "invalid repo name: repo name is required" };
+    }
+    const storeDeps = {
+        env: deps.env,
+        homedir: deps.homedir,
+        platform: deps.platform,
+        readFile: deps.readFile,
+        stat: deps.stat,
+    };
+    const result = await resolveBapiCredentials(trimmed, storeDeps);
+    if (!result.ok) {
+        return {
+            ok: false,
+            error: `could not resolve Bridge API credentials for repo '${trimmed}' (${result.kind})`,
+        };
+    }
+    return {
+        ok: true,
+        apiKey: result.credentials.apiKey,
+        baseUrl: resolveBaseUrl(deps.env),
+    };
+}
+/**
+ * Resolve credentials for every configured repo before the executor starts
+ * claiming. Each repo resolves independently; failures are reported per-repo.
+ */
+export async function resolveAllExecutorApiAccess(repos, deps) {
+    const out = [];
+    for (const repo of repos) {
+        const access = await resolveExecutorApiAccess(repo, deps);
+        if (access.ok) {
+            out.push({ ok: true, repoName: repo, apiKey: access.apiKey, baseUrl: access.baseUrl });
+        }
+        else {
+            out.push({ ok: false, repoName: repo, error: access.error });
+        }
+    }
+    return out;
+}

package/build/executor/deps.js

@@ -0,0 +1,117 @@
+/**
+ * Default (production) executor dependencies (BAPI-534, TDD §7).
+ *
+ * Provides real subprocess/HTTP/fs/timer/clock implementations behind the
+ * injected `ExecutorDeps` boundary so all executor logic stays unit-testable.
+ * Diagnostics route through `console.error` (stderr) because the executor is a
+ * CLI subcommand and MUST NOT write to stdout (which would corrupt the MCP
+ * server's JSON-RPC channel in adjacent tooling).
+ */
+import { execFile, spawn } from "node:child_process";
+import { readFile, writeFile, appendFile, mkdir, stat, statfs } from "node:fs/promises";
+import os from "node:os";
+import { promisify } from "node:util";
+const execFileAsync = promisify(execFile);
+/** Bounded subprocess output buffer (bytes). */
+const MAX_COMMAND_BUFFER = 10 * 1024 * 1024;
+/**
+ * Hard wall-clock cap on every executor HTTP request. Without it a hung
+ * heartbeat/complete/fail (network stall, half-open socket) would block
+ * `runHeartbeatLoop`'s await forever, so the dead-man check never runs and the
+ * 2-minute self-kill invariant is defeated. 30s is well under the 60s heartbeat
+ * interval, so a stuck request fails fast and the loop advances to the dead-man
+ * evaluation instead of stalling.
+ */
+const EXECUTOR_HTTP_TIMEOUT_MS = 30_000;
+export function createDefaultExecutorDeps() {
+    return {
+        async runCommand(file, args, options) {
+            try {
+                const { stdout, stderr } = await execFileAsync(file, args, {
+                    cwd: options?.cwd,
+                    timeout: options?.timeoutMs,
+                    maxBuffer: MAX_COMMAND_BUFFER,
+                    encoding: "utf8",
+                    shell: false,
+                });
+                return { stdout: stdout ?? "", stderr: stderr ?? "", exitCode: 0 };
+            }
+            catch (err) {
+                const e = err;
+                const exitCode = typeof e.code === "number" ? e.code : 1;
+                return { stdout: e.stdout ?? "", stderr: e.stderr ?? "", exitCode };
+            }
+        },
+        spawnProcess(file, args, options) {
+            const child = spawn(file, args, {
+                cwd: options.cwd,
+                env: options.env,
+                stdio: ["ignore", "pipe", "pipe"],
+                shell: false,
+            });
+            child.stdout?.setEncoding("utf8");
+            child.stderr?.setEncoding("utf8");
+            return {
+                pid: child.pid,
+                stdout: child.stdout ?? null,
+                stderr: child.stderr ?? null,
+                wait() {
+                    return new Promise((resolve) => {
+                        child.on("close", (code, signal) => resolve({ exitCode: code, signal }));
+                        child.on("error", () => resolve({ exitCode: null, signal: null }));
+                    });
+                },
+                kill(signal) {
+                    try {
+                        child.kill(signal);
+                    }
+                    catch {
+                        /* already exited */
+                    }
+                },
+            };
+        },
+        readFile: (filePath) => readFile(filePath, "utf-8"),
+        writeFile: (filePath, data) => writeFile(filePath, data, "utf-8"),
+        appendFile: (filePath, data) => appendFile(filePath, data, "utf-8"),
+        mkdir: (dirPath, opts) => mkdir(dirPath, opts),
+        stat: (filePath) => stat(filePath).then((s) => ({ mode: s.mode })),
+        statMtimeMs: (filePath) => stat(filePath)
+            .then((s) => s.mtimeMs)
+            .catch(() => null),
+        statfs: async (path) => {
+            const s = await statfs(path);
+            return { bavail: Number(s.bavail), bsize: Number(s.bsize) };
+        },
+        sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+        now: () => Date.now(),
+        setTimer: (cb, ms) => setTimeout(cb, ms),
+        clearTimer: (handle) => clearTimeout(handle),
+        env: process.env,
+        cwd: process.cwd(),
+        platform: process.platform,
+        homedir: os.homedir,
+        async fetch(url, init) {
+            const g = globalThis;
+            const controller = new AbortController();
+            const timer = setTimeout(() => controller.abort(), EXECUTOR_HTTP_TIMEOUT_MS);
+            try {
+                const res = await g.fetch(url, {
+                    method: init.method,
+                    headers: init.headers,
+                    body: init.body,
+                    signal: controller.signal,
+                });
+                // Read the body within the timeout window too, so a stalled body stream
+                // is aborted rather than hanging the caller after headers arrive.
+                const body = await res.text();
+                return { status: res.status, text: async () => body };
+            }
+            finally {
+                clearTimeout(timer);
+            }
+        },
+        log: (message) => console.error(message),
+        errorLog: (message) => console.error(message),
+    };
+}

package/build/executor/env.js

@@ -0,0 +1,79 @@
+/**
+ * Secret-free executor worker environment (BAPI-534, TDD §7).
+ *
+ * v2 executor workers get NO Bridge MCP and NO conductor identity: unlike the
+ * conductor worker env builder, this one omits `BRIDGE_MCP_PROFILE`, every
+ * `BAPI_CONDUCTOR_*` key, `CONDUCTOR_NODE_PATH`, and all secret-bearing keys.
+ * It constructs a FRESH object from a strict allowlist of non-secret operational
+ * keys — it never copies arbitrary `process.env`, so credentials/tokens/headers
+ * cannot leak into the spawned `claude` process.
+ */
+/** Non-secret operational keys forwarded to the worker when present. */
+const ALLOWED_ENV_KEYS = [
+    "PATH",
+    "HOME",
+    "USER",
+    "LOGNAME",
+    "SHELL",
+    "TMPDIR",
+    "TMP",
+    "TEMP",
+    "LANG",
+    "LC_ALL",
+    "TERM",
+    "XDG_CONFIG_HOME",
+    "NO_COLOR",
+];
+/** Substrings that mark a key as secret-bearing (case-insensitive). */
+const SECRET_NAME_FRAGMENTS = ["TOKEN", "SECRET", "PASSWORD", "API_KEY"];
+/** Explicit deny-list of known secret / MCP / conductor keys. */
+const EXPLICIT_DENY_KEYS = [
+    "BRIDGE_MCP_PROFILE",
+    "CONDUCTOR_NODE_PATH",
+    "BAPI_API_KEY",
+    "ANTHROPIC_API_KEY",
+    "OPENAI_API_KEY",
+    "GITHUB_TOKEN",
+    "GH_TOKEN",
+];
+/**
+ * True only when `key` is a safe, allowlisted operational key. Exported so the
+ * allowlist is locally auditable/testable. A key is allowed iff it is in the
+ * allowlist AND is not explicitly denied, does not begin with `BAPI_CONDUCTOR_`,
+ * and does not contain a secret-name fragment.
+ */
+export function isExecutorEnvKeyAllowed(key) {
+    if (!ALLOWED_ENV_KEYS.includes(key))
+        return false;
+    if (EXPLICIT_DENY_KEYS.includes(key))
+        return false;
+    if (key.startsWith("BAPI_CONDUCTOR_"))
+        return false;
+    const upper = key.toUpperCase();
+    if (SECRET_NAME_FRAGMENTS.some((fragment) => upper.includes(fragment)))
+        return false;
+    return true;
+}
+/**
+ * Build the secret-free worker environment: a fresh object containing only the
+ * allowlisted keys that are present (and non-undefined) in `parentEnv`, plus the
+ * literal `BRIDGE_SKIP_PREPUSH=\"1\"` (BAPI-551). This is a constant, never read
+ * from `parentEnv` — the worker's advisory local pre-push suite (~70s) is
+ * redundant for a conductor worker, since its PR is CI-gated by the merge gate
+ * anyway, and the delay was observed causing a worker to background the push and
+ * exit before it landed. `BAPI_CONDUCTOR_*` identity keys remain intentionally
+ * absent from the worker env (TDD §7) — this literal does not change that.
+ */
+export function buildExecutorWorkerEnv(parentEnv) {
+    const env = {};
+    for (const key of ALLOWED_ENV_KEYS) {
+        if (!isExecutorEnvKeyAllowed(key))
+            continue;
+        const value = parentEnv[key];
+        if (typeof value === "string") {
+            env[key] = value;
+        }
+    }
+    env.BRIDGE_SKIP_PREPUSH = "1";
+    return env;
+}

package/build/executor/heartbeat.js

@@ -0,0 +1,59 @@
+/**
+ * Heartbeat loop + dead-man's switch (BAPI-534, TDD §7, §10, R15).
+ *
+ * Every `heartbeatIntervalMs` (default 60s) POST `/heartbeat` keyed on the
+ * fencing `claim_token`, carrying telemetry residue. Timing chain (TDD §10):
+ * 60s heartbeat, 3-min lease, 2-min executor self-kill, 4-min server re-queue.
+ *
+ *  - `updated`     → advance the dead-man horizon.
+ *  - `stale_claim` → definitive loss of ownership: SIGKILL + abandon the worktree.
+ *  - anything else → transient: keep the worker alive UNTIL 2 minutes without a
+ *                    successful heartbeat, then SIGKILL + abandon (dead-man).
+ *
+ * After abandonment the loop stops all further heartbeat / telemetry / mutation
+ * work so `runClaimedJob` never reports success after losing ownership.
+ */
+import { killOwnedProcess } from "./process.js";
+/**
+ * Run the heartbeat loop until the worker is done or ownership is abandoned. The
+ * FIRST heartbeat fires promptly (no initial interval wait).
+ */
+export async function runHeartbeatLoop(params) {
+    const { job, httpClient, options, deps, ownership, proc, observation } = params;
+    let first = true;
+    while (!ownership.abandoned && !params.isDone()) {
+        if (!first) {
+            await deps.sleep(options.heartbeatIntervalMs);
+            if (ownership.abandoned || params.isDone())
+                break;
+        }
+        first = false;
+        const git = await params.collectTelemetry();
+        observation.setGitTelemetry(git);
+        const residue = observation.snapshot();
+        const outcome = await httpClient.heartbeat(job, {
+            local_commit_count: git.local_commit_count,
+            last_commit_sha: git.last_commit_sha,
+            telemetry: residue,
+        });
+        if (outcome === "updated") {
+            ownership.lastSuccessfulHeartbeatAt = deps.now();
+            continue;
+        }
+        if (outcome === "stale_claim") {
+            // Definitive dead claim: kill the worker and stop touching the worktree.
+            killOwnedProcess(proc, "stale_claim");
+            ownership.abandoned = true;
+            ownership.abandonReason = "stale_claim";
+            break;
+        }
+        // retry_later / fatal_http_error: keep the worker alive within the dead-man
+        // window; SIGKILL + abandon once 2 minutes pass without a successful beat.
+        if (deps.now() - ownership.lastSuccessfulHeartbeatAt >= options.deadmanMs) {
+            killOwnedProcess(proc, "deadman");
+            ownership.abandoned = true;
+            ownership.abandonReason = "deadman";
+            break;
+        }
+    }
+}