@bridge_gpt/mcp-server 0.2.37 → 0.2.39

package/build/executor/service-lifecycle.js

@@ -0,0 +1,269 @@
+/**
+ * Consented executor service lifecycle (BAPI-779, ratified decision R-1).
+ *
+ * WHY THIS MODULE EXISTS SEPARATELY. `service-unit.ts` carries an invariant
+ * titled "Never manages service lifecycle": it renders and writes a unit file
+ * and runs no `launchctl` / `systemctl`. R-1 (2026-08-14) deliberately amends
+ * the *product* rule — `install conductor` may now start the service the
+ * generator just wrote — while keeping the *module* rule intact. So lifecycle
+ * lives here, behind its own entry points, and the generator stays lifecycle
+ * free. A caller that only wants a unit written physically cannot start a
+ * persistent daemon by accident, because it never imports this module.
+ *
+ * Four rules shape everything below.
+ *
+ *  1. **One attempt, never a retry loop.** Each planned command runs at most
+ *     once, and the first failure stops the sequence. A service manager refusing
+ *     to bootstrap a unit is a state to report, not a race to win — retrying
+ *     turns a clear degradation into a hang, and the operator has the exact
+ *     manual command either way.
+ *  2. **Shell-free by construction.** Every command is an
+ *     {@link ExecutorServiceCommand} — an executable plus an argument ARRAY.
+ *     There is no code path that concatenates a command string and hands it to a
+ *     shell, so a unit path or unit name containing shell metacharacters cannot
+ *     become syntax.
+ *  3. **Sanitized results only.** A failure result carries the stage label, the
+ *     exit code, and the manual command. It never carries runner stdout, stderr,
+ *     thrown exception text, or environment values — the command's output is
+ *     untrusted for reporting purposes even though the command itself is ours.
+ *  4. **Local success is NOT readiness.** `startExecutorService` resolving `ok`
+ *     means the service manager accepted the unit on THIS host. It says nothing
+ *     about whether the Bridge server has observed an executor claim, which is
+ *     the only thing that may produce `executor_ready`. The two are reported as
+ *     separate facts everywhere, and nothing in this module may be used to
+ *     derive readiness.
+ *
+ * The command forms follow the conventions the scheduler backends already use
+ * (`scheduler-backends/launchd.ts`, `scheduler-backends/systemd-user.ts`), so
+ * the executor and the scheduler address user-domain services the same way.
+ */
+import { posixShellQuote } from "../scheduler-backends/escaping.js";
+/**
+ * Characters that need no shell quoting. Deliberately conservative — anything
+ * outside this set is quoted rather than reasoned about.
+ */
+const SHELL_SAFE_TOKEN_RE = /^[A-Za-z0-9_./:@%+=-]+$/;
+/**
+ * Quote a token only when it needs it.
+ *
+ * The output is copy-pasted by a human, so `launchctl bootstrap gui/501 /path`
+ * beats `'launchctl' 'bootstrap' 'gui/501' '/path'` for legibility. Safety is
+ * unchanged: anything containing a shell metacharacter — which a unit name or
+ * an executor id legitimately can, since darwin allows those characters in
+ * filenames — falls through to `posixShellQuote`.
+ */
+function shellToken(value) {
+    return SHELL_SAFE_TOKEN_RE.test(value) ? value : posixShellQuote(value);
+}
+/** Render one descriptor as a shell-safe command line. */
+function renderCommand(command) {
+    return [command.executable, ...command.args].map(shellToken).join(" ");
+}
+/**
+ * Build the platform-specific start sequence.
+ *
+ * darwin: `launchctl bootstrap gui/<uid> <plist-path>`
+ * linux:  `systemctl --user daemon-reload`, then
+ *         `systemctl --user enable --now <unit-name>`
+ *
+ * PURE — it consults no runner, no environment, and no filesystem, so an
+ * unsupported or incompletely described target is refused before anything could
+ * be executed.
+ */
+export function buildExecutorServiceStartPlan(target) {
+    if (target.platform !== "darwin" && target.platform !== "linux") {
+        return {
+            ok: false,
+            error: `platform '${String(target.platform)}' has no supported executor service start ` +
+                "sequence (consented start is supported on darwin and linux only).",
+        };
+    }
+    if (typeof target.serviceIdentifier !== "string" || target.serviceIdentifier.length === 0) {
+        return { ok: false, error: "the service identifier is missing, so no unit can be addressed." };
+    }
+    if (target.platform === "darwin") {
+        if (typeof target.unitPath !== "string" || target.unitPath.length === 0) {
+            return { ok: false, error: "the unit path is missing, so launchd has no unit to bootstrap." };
+        }
+        if (typeof target.uid !== "number" || !Number.isInteger(target.uid) || target.uid < 0) {
+            return {
+                ok: false,
+                error: "a numeric uid is required for the launchd domain target `gui/<uid>`; " +
+                    "none was supplied.",
+            };
+        }
+        const commands = [
+            {
+                stage: "launchctl bootstrap",
+                executable: "launchctl",
+                args: ["bootstrap", `gui/${target.uid}`, target.unitPath],
+            },
+        ];
+        return {
+            ok: true,
+            plan: {
+                platform: "darwin",
+                serviceManager: "launchd",
+                commands,
+                manualCommand: commands.map(renderCommand).join(" && "),
+            },
+        };
+    }
+    const commands = [
+        {
+            stage: "systemctl --user daemon-reload",
+            executable: "systemctl",
+            args: ["--user", "daemon-reload"],
+        },
+        {
+            stage: "systemctl --user enable --now",
+            executable: "systemctl",
+            args: ["--user", "enable", "--now", target.serviceIdentifier],
+        },
+    ];
+    return {
+        ok: true,
+        plan: {
+            platform: "linux",
+            serviceManager: "systemd-user",
+            commands,
+            // The two rendered commands joined by ` && ` — the same descriptors the
+            // runner receives, so the printed and the invoked forms cannot diverge.
+            manualCommand: commands.map(renderCommand).join(" && "),
+        },
+    };
+}
+/**
+ * Run the planned start sequence: each command at most once, in order, stopping
+ * at the first non-zero exit or runner refusal.
+ *
+ * A runner that throws is ONE attempted failure, not a signal to retry — a
+ * refusal (`ENOENT` on `systemctl`, a sandbox denial, a spawn error) is a
+ * durable property of the host, so re-running it would only spend time.
+ * `exitCode` is `null` in that case because no exit code exists.
+ */
+export async function startExecutorService(plan, run) {
+    let commandsRun = 0;
+    for (const command of plan.commands) {
+        let exitCode;
+        commandsRun++;
+        try {
+            const result = await run(command.executable, command.args);
+            exitCode = typeof result?.exitCode === "number" ? result.exitCode : 1;
+        }
+        catch {
+            // The thrown value is deliberately discarded: exception text can carry a
+            // path, an environment value, or a spawn detail that has no place in
+            // operator output.
+            return {
+                ok: false,
+                manualCommand: plan.manualCommand,
+                failedStage: command.stage,
+                exitCode: null,
+                reason: "runner-refused",
+                commandsRun,
+            };
+        }
+        if (exitCode !== 0) {
+            return {
+                ok: false,
+                manualCommand: plan.manualCommand,
+                failedStage: command.stage,
+                exitCode,
+                reason: "nonzero-exit",
+                commandsRun,
+            };
+        }
+    }
+    return { ok: true, manualCommand: plan.manualCommand, commandsRun };
+}
+/**
+ * Render a start failure as one secret-free operator line.
+ *
+ * Exported so the installer and any future diagnostic print byte-identical
+ * text; two copies of this sentence would drift.
+ */
+export function formatExecutorServiceStartFailure(result) {
+    const detail = result.reason === "runner-refused"
+        ? "the command could not be run on this host"
+        : `exit code ${result.exitCode}`;
+    return `service start did not complete: '${result.failedStage}' failed (${detail}).`;
+}
+/**
+ * Build the strictly read-only state probe for a target.
+ *
+ * darwin: `launchctl print gui/<uid>/<label>` — the same query
+ * `scheduler-backends/launchd.ts` uses for status.
+ * linux:  `systemctl --user is-active <unit>` — a non-mutating query whose
+ * stdout is a single state token, which is what makes a deterministic mapping
+ * possible (`systemctl --user status` would require parsing a paragraph).
+ */
+export function buildExecutorServiceStateProbe(target) {
+    if (typeof target.serviceIdentifier !== "string" || target.serviceIdentifier.length === 0) {
+        return null;
+    }
+    if (target.platform === "darwin") {
+        if (typeof target.uid !== "number" || !Number.isInteger(target.uid) || target.uid < 0) {
+            return null;
+        }
+        return {
+            stage: "launchctl print",
+            executable: "launchctl",
+            args: ["print", `gui/${target.uid}/${target.serviceIdentifier}`],
+        };
+    }
+    if (target.platform === "linux") {
+        return {
+            stage: "systemctl --user is-active",
+            executable: "systemctl",
+            args: ["--user", "is-active", target.serviceIdentifier],
+        };
+    }
+    return null;
+}
+/** The systemd state tokens this module maps; anything else is `unknown`. */
+const SYSTEMD_INACTIVE_TOKENS = new Set([
+    "inactive",
+    "failed",
+    "activating",
+    "deactivating",
+    "reloading",
+]);
+/**
+ * Inspect local service state. STRICTLY read-only: it issues exactly one probe
+ * and never starts, enables, reloads, bootstraps, or writes anything.
+ *
+ * Returns `unknown` rather than guessing whenever the probe cannot be built,
+ * the runner refuses, or the output is not a token this module recognizes — a
+ * diagnostic that invents a state is worse than one that admits ignorance.
+ */
+export async function inspectExecutorServiceState(target, run) {
+    const probe = buildExecutorServiceStateProbe(target);
+    if (!probe)
+        return { state: "unknown", probe: 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 { state: "unknown", probe };
+    }
+    if (target.platform === "darwin") {
+        // `launchctl print` succeeds only for a job the domain actually holds, so a
+        // zero exit is the loaded/active signal and a non-zero exit is "no such
+        // job". launchd exposes no cheap loaded-but-stopped distinction here, so
+        // this deliberately does not claim `inactive`.
+        return { state: exitCode === 0 ? "active" : "not-found", probe };
+    }
+    const token = stdout.trim().split(/\s+/)[0]?.toLowerCase() ?? "";
+    if (token === "active")
+        return { state: "active", probe };
+    if (token === "unknown")
+        return { state: "not-found", probe };
+    if (SYSTEMD_INACTIVE_TOKENS.has(token))
+        return { state: "inactive", probe };
+    return { state: "unknown", probe };
+}

package/build/executor/service-unit.js

@@ -10,9 +10,16 @@
  *
  *  1. **Never embeds credentials.** A generated unit carries only the validated
  *     base URL, the generating shell's `PATH`, the repository list, the executor
- *     id, and the packaged invocation. `BAPI_API_KEY` (and every
- *     credential-store value) resolves at *launch* time through the executor's
- *     existing credential seam, so an artifact left on disk is not a secret.
+ *     id, and the packaged invocation. `BAPI_API_KEY` resolves at *launch* time
+ *     through the executor's existing credential-store seam, so an artifact left
+ *     on disk is not a secret. This holds BY CONSTRUCTION rather than by
+ *     scrubbing: {@link ExecutorServiceRenderInput} has no field capable of
+ *     carrying a credential, and no renderer reads ambient environment state.
+ *     `CLAUDE_CODE_OAUTH_TOKEN`, when the operator has exported one into the
+ *     service's own launch-time environment, forwards unchanged into the direct
+ *     `claude` worker environment (BAPI-791) — Bridge never stores, resolves, or
+ *     diagnoses it, and there is no `anthropic:oauth` bundle any more.
+ *     `ANTHROPIC_API_KEY` is never forwarded to a worker under any circumstance.
  *     `PATH` is baked deliberately (the scheduler backends set the precedent —
  *     see `BAKED_ENV_VAR_NAMES` in `../scheduler-backends/escaping.js`,
  *     BAPI-327): under launchd / `systemd --user` the environment PATH is the
@@ -27,6 +34,24 @@
  *     not run `launchctl`, `systemctl`, `loginctl`, or `schtasks` — starting,
  *     stopping, and enabling the unit stay operator-owned.
  *
+ *     R-1 AMENDMENT (BAPI-779, ratified 2026-08-14). This invariant continues to
+ *     hold for *this module* — the generator and its write primitives still run
+ *     no lifecycle command, and `runExecutorInstallServiceCli` still only writes
+ *     a file. What the amendment changes is that lifecycle management is no
+ *     longer forbidden to Bridge outright: consented, one-shot start and
+ *     read-only state inspection now live in a SEPARATE module,
+ *     {@link ../executor/service-lifecycle.js `executor/service-lifecycle.ts`},
+ *     which `install conductor` drives behind its own independent consent. The
+ *     split is the point — a caller that wants a unit written cannot
+ *     accidentally start a persistent daemon, because the two capabilities are
+ *     in different modules with different entry points.
+ *
+ *     The programmatic seam that split makes possible is
+ *     {@link planExecutorServiceInstall} + {@link writeExecutorServicePlan}:
+ *     pure plan construction separated from the filesystem write, with consent
+ *     left entirely to the caller so the standalone CLI and the conductor can
+ *     apply their own independent consent policies over the same primitives.
+ *
  * The artifact type is deliberately executor-local rather than the scheduler's
  * {@link ../scheduler-backends/types.js#GeneratedArtifact}: that shape carries a
  * loose `kind: string`, whereas the executor wants a *discriminating* literal
@@ -555,9 +580,11 @@ export function getExecutorInstallServiceUsage() {
         "The generated unit contains only the base URL, the generating shell's PATH, the",
         "repositories, the executor id, and the packaged invocation. PATH is baked because",
         "the service manager's minimal default cannot resolve the `claude` worker command.",
-        "BAPI_API_KEY and every credential-store value are deliberately omitted —",
-        "credentials resolve at launch time from the environment or the user-scoped",
-        "bapi:<repo> credential store.",
+        "BAPI_API_KEY is deliberately omitted — it resolves at launch time from the",
+        "environment or the user-scoped bapi:<repo> credential store. A worker",
+        "authenticates through this host's own interactive `claude login`, or, headlessly,",
+        "through a CLAUDE_CODE_OAUTH_TOKEN you export into the service's own environment",
+        "yourself; Bridge only forwards that value unchanged and never stores it.",
         "",
         "This command writes a file and nothing else. Starting, stopping, enabling, and",
         "removing the service stay operator-managed via launchctl / systemctl --user /",
@@ -636,6 +663,79 @@ export async function writeExecutorServiceArtifact(artifact, deps, knownExists)
     await deps.writeFile(artifact.path, artifact.content);
     return { replaced };
 }
+/** Reject anything that is not an absolute http(s) URL. Never echoes the value. */
+function assertAbsoluteHttpBaseUrl(baseUrl) {
+    let parsed;
+    try {
+        parsed = new URL(baseUrl);
+    }
+    catch {
+        throw new ExecutorServiceValidationError(`${EXECUTOR_SERVICE_BASE_URL_ENV} must be an absolute http(s) URL; ` +
+            "the supplied value is not a valid URL");
+    }
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+        throw new ExecutorServiceValidationError(`${EXECUTOR_SERVICE_BASE_URL_ENV} must use http: or https: (got '${parsed.protocol}')`);
+    }
+}
+/**
+ * Build the install plan for one executor id. PURE: validates the render input
+ * for the target platform and renders the artifact, touching no filesystem, no
+ * environment, and no service manager.
+ *
+ * Throws {@link ExecutorServiceValidationError} for an unsafe executor id, an
+ * invalid base URL, an empty repository list, or an unsupported platform —
+ * before any caller could reach a write.
+ */
+export function planExecutorServiceInstall(input, platform) {
+    // The full URL grammar check lives HERE rather than in
+    // `validateExecutorServiceRenderInput`, which deliberately only bars
+    // whitespace and control characters. `runExecutorInstallServiceCli` already
+    // performs this exact check before it reaches a plan, so its behavior is
+    // unchanged; a programmatic caller gets the same guarantee without having to
+    // remember to re-implement it, and a malformed endpoint can never be baked
+    // into a durable unit.
+    assertAbsoluteHttpBaseUrl(input.baseUrl);
+    const artifact = buildExecutorServiceArtifact(input, platform);
+    return {
+        platform,
+        executorId: input.executorId,
+        unitPath: artifact.path,
+        serviceManager: platform === "darwin" ? "launchd" : "systemd-user",
+        serviceIdentifier: platform === "darwin"
+            ? executorLaunchdLabelForId(input.executorId)
+            : executorSystemdUnitNameForId(input.executorId),
+        artifact,
+    };
+}
+/**
+ * Write one planned unit. Creates ONLY the unit's parent directory and ONLY the
+ * unit file — no lifecycle command, no process spawn, no install-state write.
+ *
+ * `knownExists` lets a caller that already probed the target (the standalone
+ * CLI, which stats it to word its consent prompt) avoid a second `stat`.
+ */
+export async function writeExecutorServicePlan(plan, deps, knownExists) {
+    const exists = knownExists ?? (await targetExists(deps.stat, plan.unitPath));
+    if (exists && deps.readFile) {
+        let current = null;
+        try {
+            current = await deps.readFile(plan.unitPath);
+        }
+        catch {
+            // An unreadable existing file is not an error here — it simply means the
+            // content comparison is unavailable, so the write proceeds and reports
+            // `replaced` rather than fabricating `unchanged`.
+            current = null;
+        }
+        if (current === plan.artifact.content) {
+            return { outcome: "unchanged", unitPath: plan.unitPath, plan };
+        }
+    }
+    const pathApi = pathApiForPlatform(plan.platform);
+    await deps.mkdir(pathApi.dirname(plan.unitPath), { recursive: true });
+    await deps.writeFile(plan.unitPath, plan.artifact.content);
+    return { outcome: exists ? "replaced" : "written", unitPath: plan.unitPath, plan };
+}
 /** ENOENT means absent; any other rejection is a real failure and propagates. */
 async function targetExists(stat, filePath) {
     try {
@@ -757,14 +857,18 @@ export async function runExecutorInstallServiceCli(argv, overrides) {
         deps.log(formatWindowsGuidance(renderInput, args));
         return 0;
     }
-    let artifact;
+    // Delegates to the shared programmatic API (BAPI-779) so the CLI and the
+    // conductor render through ONE code path. Consent stays here, in the CLI,
+    // exactly as before — the plan/write primitives ask for none.
+    let plan;
     try {
-        artifact = buildExecutorServiceArtifact(renderInput, deps.platform);
+        plan = planExecutorServiceInstall(renderInput, deps.platform);
     }
     catch (error) {
         deps.errorLog(`Error: ${sanitizeError(error)}`);
         return 1;
     }
+    const artifact = plan.artifact;
     // --- Dry run: a complete preview, before consent and before any fs call. ---
     if (flags.dryRun) {
         deps.log(`Target: ${artifact.path}`);
@@ -803,15 +907,18 @@ export async function runExecutorInstallServiceCli(argv, overrides) {
         }
     }
     // --- Write phase: parent directory + the single unit, nothing else. ---
-    let replaced = false;
+    // The CLI deps carry no `readFile` seam, so the write can only report
+    // `written` or `replaced` here — the existing Created/Replaced output
+    // contract is preserved exactly.
+    let outcome;
     try {
-        ({ replaced } = await writeExecutorServiceArtifact(artifact, deps, exists));
+        ({ outcome } = await writeExecutorServicePlan(plan, deps, exists));
     }
     catch (error) {
         deps.errorLog(`Error: could not write ${artifact.path}: ${sanitizeError(error)}`);
         return 1;
     }
-    deps.log(`${replaced ? "Replaced" : "Created"} ${artifact.path}`);
+    deps.log(`${outcome === "replaced" ? "Replaced" : "Created"} ${artifact.path}`);
     deps.log("");
     deps.log(formatPostWriteGuidance(artifact, options.executorId));
     return 0;
@@ -849,7 +956,9 @@ function formatWindowsGuidance(input, args) {
         "and configure the task to run at logon and restart on failure.",
         "",
         "The command line above carries no credential. Provide the Bridge API key at run time via",
-        "the BAPI_API_KEY environment variable or the user-scoped bapi:<repo> credential store.",
+        "the BAPI_API_KEY environment variable or the user-scoped bapi:<repo> credential store. The",
+        "worker authenticates via this host's interactive `claude login`, or, headlessly, via a",
+        "CLAUDE_CODE_OAUTH_TOKEN you export into the task's own environment yourself.",
     ].join("\n");
 }
 /** Post-write operator guidance — naming the manual lifecycle step, not running it. */

package/build/executor/stale-artifacts.js

@@ -0,0 +1,70 @@
+/**
+ * Pre-spawn removal of a previous attempt's conductor artifacts (BAPI-814/D1).
+ *
+ * `.conductor/` is an IGNORED path in this repository, and worktree preparation's
+ * `git clean -fd` deliberately omits `-x`, so ignored paths survive it. That
+ * turned a stale `result.json` from a housekeeping nuisance into a safety
+ * problem: a `spec_review` retry whose worker exits `0` without writing a
+ * verdict would have the PREVIOUS attempt's verdict read back and posted
+ * verbatim as this attempt's answer. Explicit removal by the attempt owner,
+ * holding the worktree lock, is what makes "no verdict written" observable as
+ * absence instead.
+ *
+ * WHY THIS IS ITS OWN MODULE: `verdict-artifact.ts` is pinned by
+ * `tests/pytest/mcp/test_executor_job_behaviors_static.py` to contain no `.md`
+ * or `markdown` token in its executable code — the "the executor performs NO
+ * markdown parsing, NO verdict judgment" invariant. Naming `critique.md` as a
+ * deletion target there would trip that guard. Deleting an artifact and
+ * interpreting one are genuinely different concerns, so the deletion half lives
+ * here and the guard on the reading half stays exactly as strict as it was.
+ */
+import { CONDUCTOR_RESULT_DIR, CONDUCTOR_RESULT_FILE } from "./verdict-artifact.js";
+import { pathApiForExecutorPlatform } from "./worktree-inspection.js";
+/** The critique artifact a reviewer worker writes alongside its verdict. */
+export const CONDUCTOR_CRITIQUE_FILE = "critique.md";
+/**
+ * The files a prior attempt may leave behind, and the ONLY ones removed here.
+ *
+ * `worker.lock` and `worker.log` are deliberately absent: the lock is live
+ * coordination state, and the log is forensic evidence truncated by its own
+ * owner (`worker-log.ts`). The `.conductor/` directory itself and any unrelated
+ * file inside it are left untouched.
+ */
+export const STALE_ATTEMPT_ARTIFACT_FILES = [
+    CONDUCTOR_RESULT_FILE,
+    CONDUCTOR_CRITIQUE_FILE,
+];
+/**
+ * Delete a previous attempt's verdict and critique artifacts.
+ *
+ * A missing file is a successful no-op — that is the normal first-attempt case.
+ * Any other filesystem failure (a permission problem, an unexpected errno) is
+ * returned as a bounded failure so the caller can stop the attempt *before*
+ * spawning: proceeding past a cleanup that did not happen is exactly the state
+ * this function exists to prevent. The returned reason names the file and the
+ * error code only — never the exception text, the absolute path, or file
+ * contents.
+ */
+export async function removeStaleVerdictArtifacts(worktreePath, deps) {
+    const pathApi = pathApiForExecutorPlatform(deps.platform ?? process.platform);
+    for (const file of STALE_ATTEMPT_ARTIFACT_FILES) {
+        const target = pathApi.join(worktreePath, CONDUCTOR_RESULT_DIR, file);
+        try {
+            await deps.removeFile(target);
+        }
+        catch (err) {
+            const raw = err && typeof err === "object" ? err.code : undefined;
+            // Absence is the expected first-attempt state, not a failure.
+            if (raw === "ENOENT")
+                continue;
+            // A blank code is as uninformative as a missing one; both must render the
+            // same words rather than an empty pair of parentheses.
+            const code = typeof raw === "string" && raw.trim().length > 0 ? raw : "unknown error";
+            return {
+                ok: false,
+                reason: `stale ${CONDUCTOR_RESULT_DIR}/${file} could not be removed (${code})`,
+            };
+        }
+    }
+    return { ok: true };
+}