@bridge_gpt/mcp-server 0.2.34 → 0.2.37

package/build/executor/service-unit.js

@@ -0,0 +1,876 @@
+/**
+ * Executor persistent-service packaging (BAPI-688).
+ *
+ * Renders long-running *user-domain* executor services — a macOS launchd
+ * LaunchAgent plist or a Linux systemd `--user` unit — for ONE stable executor
+ * id, and hosts the `executor install-service` CLI that previews or writes
+ * exactly one of them.
+ *
+ * Three invariants shape this module:
+ *
+ *  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.
+ *     `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
+ *     minimal system default, and the executor spawns its worker as the bare
+ *     command `claude`, which on a typical workstation lives in `~/.local/bin`,
+ *     `~/.claude/local`, or `/opt/homebrew/bin` — without the generating
+ *     shell's PATH a service-launched executor crash-loops at worker preflight.
+ *  2. **Filesystem effects only through injected dependencies.** Every `stat` /
+ *     `mkdir` / `writeFile` / prompt goes through {@link ExecutorServiceInstallDeps},
+ *     so the whole CLI is unit-testable without touching a real home directory.
+ *  3. **Never manages service lifecycle.** The installer writes a file. It does
+ *     not run `launchctl`, `systemctl`, `loginctl`, or `schtasks` — starting,
+ *     stopping, and enabling the unit stay operator-owned.
+ *
+ * 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
+ * kind so a plist can never be handed to the systemd inspector. The two remain
+ * structurally compatible (`path` / `content` / `kind`).
+ */
+import { mkdir as fsMkdir, stat as fsStat, writeFile as fsWriteFile } from "node:fs/promises";
+import os from "node:os";
+import { existsSync } from "node:fs";
+import readline from "node:readline";
+import { xmlEscape, systemdQuote, posixShellQuote, windowsCmdQuote, } from "../scheduler-backends/escaping.js";
+import { pathApiForPlatform } from "../scheduler-backends/types.js";
+import { resolveMcpShimInvocationForRuntime, MCP_SERVER_PACKAGE_NAME, } from "../mcp-server-invocation.js";
+import { isTransientNpxEntryPath } from "../schedule-run.js";
+import { parseExecutorArgs } from "./cli.js";
+import { resolveBaseUrl, EXECUTOR_BASE_URL_REQUIRED_MESSAGE } from "./credentials.js";
+// ---------------------------------------------------------------------------
+// Fixed naming conventions (one service unit == one executor id)
+// ---------------------------------------------------------------------------
+/** launchd label prefix. The full label is `<prefix><executor-id>`. */
+export const EXECUTOR_LAUNCHD_LABEL_PREFIX = "com.bridge-gpt.executor.";
+/** launchd plist filename suffix. */
+export const EXECUTOR_LAUNCHD_FILENAME_SUFFIX = ".plist";
+/** systemd user-unit filename prefix. */
+export const EXECUTOR_SYSTEMD_UNIT_PREFIX = "bridge-gpt-executor-";
+/** systemd user-unit filename suffix. */
+export const EXECUTOR_SYSTEMD_UNIT_SUFFIX = ".service";
+/** The ONLY Bridge environment value baked into a generated unit. */
+export const EXECUTOR_SERVICE_BASE_URL_ENV = "BAPI_BASE_URL";
+/**
+ * The one NON-Bridge environment value baked into a generated unit: the
+ * generating shell's `PATH`, captured at render time so a service-launched
+ * executor can resolve the bare `claude` worker command (module docstring,
+ * invariant 1). Baked only when the captured value is non-empty — baking an
+ * empty PATH would be strictly worse than the service manager's default.
+ */
+export const EXECUTOR_SERVICE_PATH_ENV = "PATH";
+/** Home-relative directory segments holding Darwin LaunchAgents. */
+const LAUNCHD_DIR_SEGMENTS = ["Library", "LaunchAgents"];
+/** Home-relative directory segments holding Linux systemd user units. */
+const SYSTEMD_DIR_SEGMENTS = [".config", "systemd", "user"];
+// ---------------------------------------------------------------------------
+// Path + label helpers (pure)
+// ---------------------------------------------------------------------------
+/** The launchd label for an executor id: `com.bridge-gpt.executor.<id>`. */
+export function executorLaunchdLabelForId(executorId) {
+    return `${EXECUTOR_LAUNCHD_LABEL_PREFIX}${executorId}`;
+}
+/** Absolute LaunchAgents directory for a home dir (Darwin path semantics). */
+export function executorLaunchdDirForHome(homeDir) {
+    return pathApiForPlatform("darwin").join(homeDir, ...LAUNCHD_DIR_SEGMENTS);
+}
+/** `~/Library/LaunchAgents/com.bridge-gpt.executor.<id>.plist`. */
+export function executorLaunchdPlistPathForId(executorId, homeDir) {
+    const filename = `${executorLaunchdLabelForId(executorId)}${EXECUTOR_LAUNCHD_FILENAME_SUFFIX}`;
+    return pathApiForPlatform("darwin").join(executorLaunchdDirForHome(homeDir), filename);
+}
+/** The systemd unit name: `bridge-gpt-executor-<id>.service`. */
+export function executorSystemdUnitNameForId(executorId) {
+    return `${EXECUTOR_SYSTEMD_UNIT_PREFIX}${executorId}${EXECUTOR_SYSTEMD_UNIT_SUFFIX}`;
+}
+/** Absolute systemd user-unit directory for a home dir (POSIX semantics). */
+export function executorSystemdDirForHome(homeDir) {
+    return pathApiForPlatform("linux").join(homeDir, ...SYSTEMD_DIR_SEGMENTS);
+}
+/** `~/.config/systemd/user/bridge-gpt-executor-<id>.service`. */
+export function executorSystemdUnitPathForId(executorId, homeDir) {
+    return pathApiForPlatform("linux").join(executorSystemdDirForHome(homeDir), executorSystemdUnitNameForId(executorId));
+}
+/**
+ * Recover the executor id from a LaunchAgents filename, or `null` when the name
+ * does not follow the fixed convention. Doctor uses this so enumeration and
+ * generation share one naming contract.
+ */
+export function executorIdFromLaunchdFilename(filename) {
+    if (!filename.startsWith(EXECUTOR_LAUNCHD_LABEL_PREFIX) ||
+        !filename.endsWith(EXECUTOR_LAUNCHD_FILENAME_SUFFIX)) {
+        return null;
+    }
+    const id = filename.slice(EXECUTOR_LAUNCHD_LABEL_PREFIX.length, filename.length - EXECUTOR_LAUNCHD_FILENAME_SUFFIX.length);
+    return id.length > 0 ? id : null;
+}
+/** Recover the executor id from a systemd unit filename, or `null`. */
+export function executorIdFromSystemdFilename(filename) {
+    if (!filename.startsWith(EXECUTOR_SYSTEMD_UNIT_PREFIX) ||
+        !filename.endsWith(EXECUTOR_SYSTEMD_UNIT_SUFFIX)) {
+        return null;
+    }
+    const id = filename.slice(EXECUTOR_SYSTEMD_UNIT_PREFIX.length, filename.length - EXECUTOR_SYSTEMD_UNIT_SUFFIX.length);
+    return id.length > 0 ? id : null;
+}
+// ---------------------------------------------------------------------------
+// Validation (pure) — everything that becomes a filename or a unit directive
+// ---------------------------------------------------------------------------
+/** Thrown by the pure renderers/builder when an input cannot be safely rendered. */
+export class ExecutorServiceValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ExecutorServiceValidationError";
+    }
+}
+/** Control characters (including NUL/CR/LF) are never legal in a rendered value. */
+// eslint-disable-next-line no-control-regex
+const CONTROL_CHAR_RE = /[\u0000-\u001f\u007f]/;
+/**
+ * systemd unit-name boundary. systemd accepts `[A-Za-z0-9:_.-]` (plus escape
+ * sequences) in a unit name; we additionally require an alphanumeric first
+ * character so a unit can never be mistaken for a flag or a dotfile. Invalid
+ * ids are REJECTED, never silently rewritten — rewriting would break the fixed
+ * one-unit-per-executor-id naming contract the operator and doctor both rely on.
+ */
+const SYSTEMD_UNIT_ID_RE = /^[A-Za-z0-9][A-Za-z0-9:_.-]*$/;
+/**
+ * Reject a value that cannot be interpolated into a unit directive at all.
+ *
+ * Every failure surfaces as an {@link ExecutorServiceValidationError} so the CLI
+ * has one error type to catch and sanitize. `CONTROL_CHAR_RE` covers NUL (which
+ * can truncate a written unit mid-file) alongside CR/LF (which could open a new
+ * directive) and the rest of the C0 range. The escaping helpers below re-check
+ * NUL independently, so this is the first of two barriers, not the only one.
+ */
+function assertRenderableValue(value, label) {
+    if (typeof value !== "string" || value.length === 0) {
+        throw new ExecutorServiceValidationError(`${label} is required`);
+    }
+    if (CONTROL_CHAR_RE.test(value)) {
+        throw new ExecutorServiceValidationError(`${label} contains a control character (NUL, CR, LF, or similar), which could truncate the ` +
+            "unit or inject a directive");
+    }
+}
+/**
+ * Validate an executor id for the target platform. Darwin keeps XML
+ * metacharacters (`& < > " '` are legal filename characters there and are XML
+ * escaped at render time); Linux is held to the literal systemd unit-name
+ * boundary. Both reject path separators, control characters, and relative-path
+ * names so the id can never redirect the write.
+ */
+export function validateExecutorId(executorId, platform) {
+    assertRenderableValue(executorId, "executor id");
+    if (executorId !== executorId.trim()) {
+        throw new ExecutorServiceValidationError("executor id must not have leading or trailing whitespace");
+    }
+    if (executorId.includes("/") || executorId.includes("\\")) {
+        throw new ExecutorServiceValidationError("executor id must not contain a path separator ('/' or '\\')");
+    }
+    if (executorId === "." || executorId === "..") {
+        throw new ExecutorServiceValidationError("executor id must not be a relative path segment");
+    }
+    if (executorId.length > 128) {
+        throw new ExecutorServiceValidationError("executor id must be 128 characters or fewer");
+    }
+    if (platform === "linux" && !SYSTEMD_UNIT_ID_RE.test(executorId)) {
+        throw new ExecutorServiceValidationError(`executor id '${executorId}' is not a valid systemd unit-name fragment: ` +
+            "use only letters, digits, ':', '_', '.', or '-', starting with a letter or digit " +
+            "(the id is never rewritten, because one executor id maps to exactly one unit name)");
+    }
+}
+/** Validate the full render input without producing an artifact. */
+export function validateExecutorServiceRenderInput(input, platform) {
+    try {
+        validateExecutorId(input.executorId, platform);
+        assertRenderableValue(input.homeDir, "home directory");
+        assertRenderableValue(input.baseUrl, "base URL");
+        // Whitespace is never legitimate inside a URL, and a base URL is the one
+        // rendered value that has a strict grammar. Rejecting it here means callers
+        // other than the CLI (which additionally does a full `new URL(...)` check)
+        // still cannot bake a malformed endpoint into a durable unit.
+        if (/\s/.test(input.baseUrl)) {
+            throw new ExecutorServiceValidationError("base URL must not contain whitespace");
+        }
+        assertRenderableValue(input.invocation.executable, "service executable");
+        // PATH is optional (empty means "omit the directive"), but a present value
+        // is held to the same control-character barrier as every rendered value: a
+        // CR/LF or NUL in PATH could open a new directive or truncate the unit.
+        if (input.envPath !== undefined && input.envPath.length > 0) {
+            assertRenderableValue(input.envPath, "PATH value");
+        }
+        if (input.repos.length === 0) {
+            throw new ExecutorServiceValidationError("at least one repository is required");
+        }
+        for (const repo of input.repos)
+            assertRenderableValue(repo, "repository name");
+        for (const arg of input.invocation.prefixArgs)
+            assertRenderableValue(arg, "service argument");
+        return { ok: true };
+    }
+    catch (error) {
+        return { ok: false, error: error instanceof Error ? error.message : String(error) };
+    }
+}
+function assertValidRenderInput(input, platform) {
+    const result = validateExecutorServiceRenderInput(input, platform);
+    if (!result.ok)
+        throw new ExecutorServiceValidationError(result.error);
+}
+/**
+ * Build the executor daemon argument vector: the packaged prefix, then one
+ * `--repo <name>` pair per repository, then `--executor-id <id>`. An argument
+ * ARRAY, never a concatenated shell command — and repository *names*, never
+ * repository paths, because the executor's identity is the id, not a checkout.
+ */
+export function buildExecutorServiceArguments(input) {
+    const args = [...input.invocation.prefixArgs];
+    for (const repo of input.repos)
+        args.push("--repo", repo);
+    args.push("--executor-id", input.executorId);
+    return args;
+}
+// ---------------------------------------------------------------------------
+// Renderers (pure)
+// ---------------------------------------------------------------------------
+/**
+ * Render the launchd LaunchAgent plist for one executor id. `RunAtLoad` and
+ * `KeepAlive` make it a long-running daemon that comes back after a crash or a
+ * login. Every interpolated value is XML escaped. When the render input carries
+ * a non-empty `envPath`, the generating shell's `PATH` is baked alongside the
+ * base URL (module docstring, invariant 1) so the executor's worker spawn can
+ * resolve `claude` under launchd's minimal default environment.
+ */
+export function renderExecutorLaunchdPlist(input) {
+    assertValidRenderInput(input, "darwin");
+    const label = executorLaunchdLabelForId(input.executorId);
+    const programArgs = [input.invocation.executable, ...buildExecutorServiceArguments(input)]
+        .map((arg) => `    <string>${xmlEscape(arg)}</string>`)
+        .join("\n");
+    const envEntries = [
+        `    <key>${EXECUTOR_SERVICE_BASE_URL_ENV}</key>`,
+        `    <string>${xmlEscape(input.baseUrl)}</string>`,
+    ];
+    if (input.envPath !== undefined && input.envPath.length > 0) {
+        envEntries.push(`    <key>${EXECUTOR_SERVICE_PATH_ENV}</key>`, `    <string>${xmlEscape(input.envPath)}</string>`);
+    }
+    return [
+        '<?xml version="1.0" encoding="UTF-8"?>',
+        '<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">',
+        '<plist version="1.0">',
+        "<dict>",
+        "  <key>Label</key>",
+        `  <string>${xmlEscape(label)}</string>`,
+        "  <key>EnvironmentVariables</key>",
+        "  <dict>",
+        ...envEntries,
+        "  </dict>",
+        "  <key>ProgramArguments</key>",
+        "  <array>",
+        programArgs,
+        "  </array>",
+        "  <key>RunAtLoad</key>",
+        "  <true/>",
+        "  <key>KeepAlive</key>",
+        "  <true/>",
+        "</dict>",
+        "</plist>",
+        "",
+    ].join("\n");
+}
+/**
+ * Escape a value for a systemd directive. {@link systemdQuote} handles
+ * backslashes and double quotes; `%` is additionally doubled because systemd
+ * expands `%`-specifiers (`%h`, `%i`, …) inside `ExecStart` and `Environment`.
+ */
+export function systemdDirectiveValue(value) {
+    return systemdQuote(value.replace(/%/g, "%%"));
+}
+/**
+ * Render the systemd `--user` unit for one executor id. `Type=simple` +
+ * `Restart=always` make it a supervised long-running service; `[Install]` /
+ * `WantedBy=default.target` lets the operator `systemctl --user enable` it — the
+ * installer never runs that command itself. When the render input carries a
+ * non-empty `envPath`, the generating shell's `PATH` is baked alongside the base
+ * URL (module docstring, invariant 1) so the executor's worker spawn can resolve
+ * `claude` under the `--user` manager's minimal default environment. Like every
+ * directive value it goes through {@link systemdDirectiveValue}, so `%` is
+ * doubled against specifier expansion.
+ */
+export function renderExecutorSystemdService(input) {
+    assertValidRenderInput(input, "linux");
+    const execStart = [input.invocation.executable, ...buildExecutorServiceArguments(input)]
+        .map(systemdDirectiveValue)
+        .join(" ");
+    const environmentLines = [
+        `Environment=${EXECUTOR_SERVICE_BASE_URL_ENV}=${systemdDirectiveValue(input.baseUrl)}`,
+    ];
+    if (input.envPath !== undefined && input.envPath.length > 0) {
+        environmentLines.push(`Environment=${EXECUTOR_SERVICE_PATH_ENV}=${systemdDirectiveValue(input.envPath)}`);
+    }
+    return [
+        "[Unit]",
+        `Description=${systemdDirectiveValue(`Bridge GPT epic-conductor executor (${input.executorId})`)}`,
+        "After=network-online.target",
+        "",
+        "[Service]",
+        "Type=simple",
+        ...environmentLines,
+        `ExecStart=${execStart}`,
+        "Restart=always",
+        "RestartSec=10",
+        "",
+        "[Install]",
+        "WantedBy=default.target",
+        "",
+    ].join("\n");
+}
+/**
+ * Build the single artifact for a supported persistent-service platform. Pure:
+ * it derives the deterministic path and renders the content, and rejects any
+ * platform that has no generated-unit format rather than guessing one.
+ */
+export function buildExecutorServiceArtifact(input, platform) {
+    if (platform === "darwin") {
+        return {
+            path: executorLaunchdPlistPathForId(input.executorId, input.homeDir),
+            content: renderExecutorLaunchdPlist(input),
+            kind: "launchd-plist",
+        };
+    }
+    if (platform === "linux") {
+        return {
+            path: executorSystemdUnitPathForId(input.executorId, input.homeDir),
+            content: renderExecutorSystemdService(input),
+            kind: "systemd-service",
+        };
+    }
+    throw new ExecutorServiceValidationError(`platform '${platform}' has no generated executor service format ` +
+        "(persistent units are generated for darwin and linux only)");
+}
+/** Reverse {@link xmlEscape} for the five entities it emits. */
+function xmlUnescape(value) {
+    return value
+        .replace(/&lt;/g, "<")
+        .replace(/&gt;/g, ">")
+        .replace(/&quot;/g, '"')
+        .replace(/&apos;/g, "'")
+        .replace(/&amp;/g, "&");
+}
+/** Pull `--repo`/`--executor-id` values out of a recovered argument vector. */
+function readArgumentContract(args) {
+    const repos = [];
+    let executorId = null;
+    for (let i = 0; i < args.length; i++) {
+        if (args[i] === "--repo" && typeof args[i + 1] === "string") {
+            repos.push(args[++i]);
+        }
+        else if (args[i] === "--executor-id" && typeof args[i + 1] === "string") {
+            executorId = args[++i];
+        }
+    }
+    return { repos, executorId };
+}
+/** Inspect a plist produced by {@link renderExecutorLaunchdPlist}. */
+function inspectLaunchdPlist(content) {
+    const problems = [];
+    const envMatch = content.match(new RegExp(`<key>${EXECUTOR_SERVICE_BASE_URL_ENV}</key>\\s*<string>([^<]*)</string>`));
+    const baseUrl = envMatch ? xmlUnescape(envMatch[1]) : null;
+    if (baseUrl === null) {
+        problems.push(`no ${EXECUTOR_SERVICE_BASE_URL_ENV} entry found in the plist`);
+    }
+    const arrayMatch = content.match(/<key>ProgramArguments<\/key>\s*<array>([\s\S]*?)<\/array>/);
+    let args = [];
+    if (arrayMatch) {
+        args = Array.from(arrayMatch[1].matchAll(/<string>([^<]*)<\/string>/g)).map((m) => xmlUnescape(m[1]));
+    }
+    else {
+        problems.push("no ProgramArguments array found in the plist");
+    }
+    const { repos, executorId } = readArgumentContract(args);
+    return { ok: problems.length === 0, baseUrl, repos, executorId, problems };
+}
+/**
+ * Split a systemd directive value into tokens, honouring the double-quoted form
+ * {@link systemdDirectiveValue} emits (backslash escapes inside quotes, `%%`
+ * collapsing to a literal `%`).
+ */
+function splitSystemdTokens(value) {
+    const tokens = [];
+    let current = "";
+    let inQuotes = false;
+    let started = false;
+    for (let i = 0; i < value.length; i++) {
+        const ch = value[i];
+        if (ch === "\\" && i + 1 < value.length) {
+            current += value[++i];
+            started = true;
+        }
+        else if (ch === "%" && value[i + 1] === "%") {
+            current += "%";
+            i++;
+            started = true;
+        }
+        else if (ch === '"') {
+            inQuotes = !inQuotes;
+            started = true;
+        }
+        else if (!inQuotes && /\s/.test(ch)) {
+            if (started)
+                tokens.push(current);
+            current = "";
+            started = false;
+        }
+        else {
+            current += ch;
+            started = true;
+        }
+    }
+    if (started)
+        tokens.push(current);
+    return tokens;
+}
+/** Inspect a unit produced by {@link renderExecutorSystemdService}. */
+function inspectSystemdService(content) {
+    const problems = [];
+    const lines = content.split(/\r?\n/);
+    const envLine = lines.find((l) => l.startsWith(`Environment=${EXECUTOR_SERVICE_BASE_URL_ENV}=`));
+    let baseUrl = null;
+    if (envLine) {
+        const raw = envLine.slice(`Environment=${EXECUTOR_SERVICE_BASE_URL_ENV}=`.length);
+        baseUrl = splitSystemdTokens(raw)[0] ?? null;
+    }
+    if (baseUrl === null || baseUrl.length === 0) {
+        baseUrl = null;
+        problems.push(`no ${EXECUTOR_SERVICE_BASE_URL_ENV} directive found in the unit`);
+    }
+    const execLine = lines.find((l) => l.startsWith("ExecStart="));
+    let args = [];
+    if (execLine) {
+        args = splitSystemdTokens(execLine.slice("ExecStart=".length));
+    }
+    else {
+        problems.push("no ExecStart directive found in the unit");
+    }
+    const { repos, executorId } = readArgumentContract(args);
+    return { ok: problems.length === 0, baseUrl, repos, executorId, problems };
+}
+/**
+ * Recover the persisted contract (base URL, repositories, executor id) from an
+ * artifact this module generated. Doctor calls this instead of maintaining a
+ * second parser, so a renderer change can never silently desync the diagnostic.
+ * Malformed content yields a sanitized `problems` list — it never throws and
+ * never invents values.
+ */
+export function inspectExecutorServiceArtifact(kind, content) {
+    try {
+        return kind === "launchd-plist" ? inspectLaunchdPlist(content) : inspectSystemdService(content);
+    }
+    catch {
+        return {
+            ok: false,
+            baseUrl: null,
+            repos: [],
+            executorId: null,
+            problems: ["unit content could not be parsed"],
+        };
+    }
+}
+/**
+ * Resolve the packaged launcher a persistent unit should bake in: this process's
+ * own absolute Node executable plus the absolute compiled `index.js`, followed by
+ * the `executor` subcommand token.
+ *
+ * A persistent unit must survive a reboot with no login shell, so the two unsafe
+ * forms are refused rather than written: the npm-channel (`npx`) fallback, which
+ * is a PATH-relative command that also re-resolves the package on every launch,
+ * and an entry path inside a prunable `_npx` cache directory.
+ */
+export function resolvePackagedExecutorInvocation(deps) {
+    const resolved = resolveMcpShimInvocationForRuntime({
+        moduleUrl: deps?.moduleUrl ?? import.meta.url,
+        nodeExecutable: deps?.execPath ?? process.execPath,
+        argv1: deps?.argv1 ?? process.argv[1],
+        fileExists: deps?.fileExists ?? ((p) => existsSync(p)),
+    });
+    if (resolved.form !== "absolute-build-path") {
+        return {
+            ok: false,
+            error: "could not resolve an absolute packaged CLI path for a persistent service. " +
+                `A service unit must not launch through 'npx ${MCP_SERVER_PACKAGE_NAME}', which depends on ` +
+                "PATH and a prunable cache. Install the CLI persistently " +
+                `(e.g. 'npm i -g ${MCP_SERVER_PACKAGE_NAME}') and re-run install-service from that binary.`,
+        };
+    }
+    if (isTransientNpxEntryPath(resolved.serverEntryPath)) {
+        return {
+            ok: false,
+            error: `the running CLI lives in an npx cache directory ('${resolved.serverEntryPath}'), which can be ` +
+                "pruned at any time — a service unit baked with that path would fail with ENOENT after a reboot. " +
+                `Install the CLI persistently (e.g. 'npm i -g ${MCP_SERVER_PACKAGE_NAME}') and re-run install-service.`,
+        };
+    }
+    return {
+        ok: true,
+        invocation: {
+            executable: resolved.nodeExecutable,
+            prefixArgs: [resolved.serverEntryPath, "executor"],
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// `executor install-service` CLI
+// ---------------------------------------------------------------------------
+/** User-facing usage for `executor install-service`. */
+export function getExecutorInstallServiceUsage() {
+    return [
+        "Usage: mcp-server executor install-service --executor-id <id> --repo <name> [--repo <name> ...] [options]",
+        "",
+        "Generates ONE long-running user-domain service unit for ONE stable executor id:",
+        "  macOS   ~/Library/LaunchAgents/com.bridge-gpt.executor.<id>.plist",
+        "  Linux   ~/.config/systemd/user/bridge-gpt-executor-<id>.service",
+        "  Windows manual Task Scheduler guidance is printed; nothing is written.",
+        "",
+        "Required:",
+        "  --executor-id <id>            Stable, explicit executor id. A persistent unit",
+        "                                needs a durable identity, so the foreground",
+        "                                <hostname>-<pid> default is never used here.",
+        "  --repo <name>                 Repo to serve (repeatable; --repos=a,b also works).",
+        "  --base-url <url>              Bridge API endpoint, or set BAPI_BASE_URL.",
+        "                                There is NO production default.",
+        "",
+        "Options:",
+        "  --dry-run                     Print the target path and the complete unit body.",
+        "                                Performs no consent prompt and no filesystem write.",
+        "  --yes                         Explicit consent to create the unit's parent",
+        "                                directory and write the unit. Required when stdin",
+        "                                is not a TTY.",
+        "  -h, --help                    Show this help.",
+        "",
+        "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.",
+        "",
+        "This command writes a file and nothing else. Starting, stopping, enabling, and",
+        "removing the service stay operator-managed via launchctl / systemctl --user /",
+        "Task Scheduler.",
+    ].join("\n");
+}
+/** Default, production dependency set for the install-service CLI. */
+export function createDefaultExecutorServiceInstallDeps() {
+    return {
+        platform: process.platform,
+        env: process.env,
+        homeDir: os.homedir(),
+        parseContext: {
+            hostname: os.hostname(),
+            pid: process.pid,
+            platform: process.platform,
+            env: process.env,
+        },
+        isTTY: Boolean(process.stdin.isTTY),
+        resolveInvocation: () => resolvePackagedExecutorInvocation(),
+        stat: (filePath) => fsStat(filePath),
+        mkdir: (dirPath, options) => fsMkdir(dirPath, options),
+        writeFile: (filePath, content) => fsWriteFile(filePath, content, "utf-8"),
+        prompt: defaultConsentPrompt,
+        log: (message) => console.log(message),
+        errorLog: (message) => console.error(message),
+    };
+}
+/** Default-No stdin consent prompt (only reached on a TTY). */
+async function defaultConsentPrompt(question) {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
+    try {
+        const answer = await new Promise((resolve) => rl.question(`${question} [y/N] `, resolve));
+        return /^y(es)?$/i.test(answer.trim());
+    }
+    finally {
+        rl.close();
+    }
+}
+/**
+ * Recognize only `--yes`, `--dry-run`, and help; forward everything else.
+ *
+ * Stripping is what makes `--base-url --yes` fail instead of persisting the
+ * literal string `--yes` as a URL: with `--yes` removed, `--base-url` has no
+ * value left and the executor parser rejects it.
+ */
+export function preprocessInstallServiceFlags(argv) {
+    let yes = false;
+    let dryRun = false;
+    let help = false;
+    const forwardArgs = [];
+    for (const arg of argv) {
+        if (arg === "--yes")
+            yes = true;
+        else if (arg === "--dry-run")
+            dryRun = true;
+        else if (arg === "--help" || arg === "-h")
+            help = true;
+        else
+            forwardArgs.push(arg);
+    }
+    return { yes, dryRun, help, forwardArgs };
+}
+/** Runtime modes that are incoherent for a supervised long-running service. */
+const SERVICE_INCOMPATIBLE_FLAGS = ["--once"];
+/**
+ * Write exactly one rendered artifact: stat the target for create-vs-replace
+ * messaging, create ONLY the unit's parent directory, and write ONLY the unit.
+ * Runs no `launchctl` / `systemctl` / `loginctl` / `schtasks` — lifecycle
+ * management is deliberately not this command's job.
+ */
+export async function writeExecutorServiceArtifact(artifact, deps, knownExists) {
+    const replaced = knownExists ?? (await targetExists(deps.stat, artifact.path));
+    const pathApi = pathApiForPlatform(deps.platform);
+    await deps.mkdir(pathApi.dirname(artifact.path), { recursive: true });
+    await deps.writeFile(artifact.path, artifact.content);
+    return { replaced };
+}
+/** ENOENT means absent; any other rejection is a real failure and propagates. */
+async function targetExists(stat, filePath) {
+    try {
+        await stat(filePath);
+        return true;
+    }
+    catch (error) {
+        const code = error?.code;
+        if (code === "ENOENT" || code === "ENOTDIR")
+            return false;
+        throw error;
+    }
+}
+/** Sanitize a thrown value into a short, secret-free CLI message. */
+function sanitizeError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return message.slice(0, 300);
+}
+/**
+ * CLI entry for `executor install-service`. Returns a numeric exit code and
+ * contains every top-level failure rather than throwing through the process
+ * boundary. Ordering matters: EVERY user-supplied value is validated before the
+ * first `stat` / `mkdir` / `writeFile`, and `--dry-run` returns before both
+ * consent and filesystem access.
+ */
+export async function runExecutorInstallServiceCli(argv, overrides) {
+    const deps = {
+        ...createDefaultExecutorServiceInstallDeps(),
+        ...overrides,
+    };
+    const flags = preprocessInstallServiceFlags(argv);
+    if (flags.help) {
+        deps.log(getExecutorInstallServiceUsage());
+        return 0;
+    }
+    // --- Validation phase: nothing below touches the filesystem. ---
+    if (!flags.forwardArgs.includes("--executor-id")) {
+        deps.errorLog("Error: --executor-id is required by install-service. A persistent unit needs a stable, " +
+            "explicit executor id (one unit maps to exactly one id); the foreground executor's " +
+            "<hostname>-<pid> default is never baked into durable state.");
+        deps.errorLog("");
+        deps.errorLog(getExecutorInstallServiceUsage());
+        return 1;
+    }
+    for (const flag of SERVICE_INCOMPATIBLE_FLAGS) {
+        if (flags.forwardArgs.includes(flag)) {
+            deps.errorLog(`Error: ${flag} is incompatible with install-service — a supervised service runs ` +
+                "continuously, so a single-cycle mode would be silently dropped from the generated unit.");
+            return 1;
+        }
+    }
+    const parsed = parseExecutorArgs(flags.forwardArgs, deps.parseContext);
+    if (parsed.kind === "help") {
+        deps.log(getExecutorInstallServiceUsage());
+        return 0;
+    }
+    if (parsed.kind === "error") {
+        deps.errorLog(`Error: ${parsed.message}`);
+        deps.errorLog("");
+        deps.errorLog(getExecutorInstallServiceUsage());
+        return 1;
+    }
+    const options = parsed.options;
+    const baseUrlResult = resolveBaseUrl(deps.env, options.baseUrl);
+    if (!baseUrlResult.ok) {
+        deps.errorLog(`Error: ${EXECUTOR_BASE_URL_REQUIRED_MESSAGE}`);
+        return 1;
+    }
+    const baseUrl = baseUrlResult.baseUrl;
+    let parsedUrl;
+    try {
+        parsedUrl = new URL(baseUrl);
+    }
+    catch {
+        deps.errorLog(`Error: --base-url / ${EXECUTOR_SERVICE_BASE_URL_ENV} must be an absolute http(s) URL; ` +
+            "the supplied value is not a valid URL.");
+        return 1;
+    }
+    if (parsedUrl.protocol !== "http:" && parsedUrl.protocol !== "https:") {
+        deps.errorLog(`Error: --base-url / ${EXECUTOR_SERVICE_BASE_URL_ENV} must use http: or https: ` +
+            `(got '${parsedUrl.protocol}').`);
+        return 1;
+    }
+    if (deps.platform !== "darwin" && deps.platform !== "linux" && deps.platform !== "win32") {
+        deps.errorLog(`Error: install-service supports darwin, linux, and win32 (manual guidance); ` +
+            `'${deps.platform}' has no supported persistent-service format.`);
+        return 1;
+    }
+    try {
+        validateExecutorId(options.executorId, deps.platform);
+    }
+    catch (error) {
+        deps.errorLog(`Error: ${sanitizeError(error)}`);
+        return 1;
+    }
+    const invocationResult = deps.resolveInvocation();
+    if (!invocationResult.ok) {
+        deps.errorLog(`Error: ${invocationResult.error}`);
+        return 1;
+    }
+    // Capture the generating shell's PATH once, at render time (the
+    // scheduler-backends precedent, BAPI-327): the service manager's default PATH
+    // cannot resolve the bare `claude` worker command. `Path` is the Windows
+    // spelling; a missing/empty value simply omits the directive.
+    const envPath = deps.env.PATH ?? deps.env.Path ?? "";
+    const renderInput = {
+        invocation: invocationResult.invocation,
+        executorId: options.executorId,
+        repos: options.repos,
+        baseUrl,
+        homeDir: deps.homeDir,
+        envPath,
+    };
+    // Windows has no generated user-service format here: print the fully resolved,
+    // secret-free command line plus manual Task Scheduler guidance and stop. No
+    // consent is requested because nothing is written.
+    if (deps.platform === "win32") {
+        const args = buildExecutorServiceArguments(renderInput);
+        deps.log(formatWindowsGuidance(renderInput, args));
+        return 0;
+    }
+    let artifact;
+    try {
+        artifact = buildExecutorServiceArtifact(renderInput, deps.platform);
+    }
+    catch (error) {
+        deps.errorLog(`Error: ${sanitizeError(error)}`);
+        return 1;
+    }
+    // --- Dry run: a complete preview, before consent and before any fs call. ---
+    if (flags.dryRun) {
+        deps.log(`Target: ${artifact.path}`);
+        deps.log("");
+        deps.log(artifact.content);
+        deps.log("(dry run — nothing was written)");
+        return 0;
+    }
+    // --- Consent phase. ---
+    if (!flags.yes && !deps.isTTY) {
+        deps.errorLog(`Error: writing ${artifact.path} needs explicit consent, but stdin is not a TTY. ` +
+            "Re-run with --yes to authorize the write, or with --dry-run to preview the unit.");
+        return 1;
+    }
+    let exists;
+    try {
+        exists = await targetExists(deps.stat, artifact.path);
+    }
+    catch (error) {
+        deps.errorLog(`Error: could not inspect ${artifact.path}: ${sanitizeError(error)}`);
+        return 1;
+    }
+    if (!flags.yes) {
+        const action = exists ? "Replace" : "Create";
+        let approved = false;
+        try {
+            approved = await deps.prompt(`${action} executor service unit ${artifact.path}?`);
+        }
+        catch (error) {
+            deps.errorLog(`Error: could not read consent: ${sanitizeError(error)}`);
+            return 1;
+        }
+        if (!approved) {
+            deps.errorLog("Service installation was not confirmed; nothing was written.");
+            return 1;
+        }
+    }
+    // --- Write phase: parent directory + the single unit, nothing else. ---
+    let replaced = false;
+    try {
+        ({ replaced } = await writeExecutorServiceArtifact(artifact, 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("");
+    deps.log(formatPostWriteGuidance(artifact, options.executorId));
+    return 0;
+}
+// ---------------------------------------------------------------------------
+// Operator guidance formatters.
+//
+// These print command lines a human copy-pastes into a real shell, so they are
+// the ONE surface in this module where a value becomes shell syntax rather than
+// an argument-array element or an escaped unit directive. Executor ids stay
+// deliberately permissive on Darwin (XML metacharacters are valid filename
+// characters there — see `validateExecutorId`), and repository names are only
+// checked for control characters, so every externally-supplied value MUST be
+// shell-quoted here rather than assumed safe.
+//
+// Quoting reuses the escaping helpers the scheduler backends already ship:
+// `posixShellQuote` (single-quote form, `'\''` for embedded quotes) and
+// `windowsCmdQuote` (double-quote form, `""` for embedded quotes). The literal
+// `$(id -u)` in the launchctl templates is intentionally left UNQUOTED — it is
+// command substitution the operator wants evaluated, not interpolated data.
+// ---------------------------------------------------------------------------
+/** Manual Task Scheduler guidance plus the resolved, secret-free command line. */
+function formatWindowsGuidance(input, args) {
+    // Quote EVERY token, not just the ones containing whitespace: the previous
+    // whitespace-only rule left embedded double quotes unescaped, so a value could
+    // close its own quoted token and append a command when pasted.
+    const commandLine = [input.invocation.executable, ...args].map(windowsCmdQuote).join(" ");
+    return [
+        "Windows: install-service does not create a service unit automatically.",
+        "Register the executor as a Task Scheduler task manually, using this resolved command line:",
+        "",
+        `  ${commandLine}`,
+        "",
+        `Set the task's environment variable ${EXECUTOR_SERVICE_BASE_URL_ENV}=${windowsCmdQuote(input.baseUrl)}`,
+        "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.",
+    ].join("\n");
+}
+/** Post-write operator guidance — naming the manual lifecycle step, not running it. */
+function formatPostWriteGuidance(artifact, executorId) {
+    if (artifact.kind === "launchd-plist") {
+        const label = posixShellQuote(executorLaunchdLabelForId(executorId));
+        return [
+            "Next step (manual — install-service never manages lifecycle):",
+            `  launchctl bootstrap gui/$(id -u) ${posixShellQuote(artifact.path)}`,
+            `  launchctl print gui/$(id -u)/${label}    # status`,
+            `  launchctl bootout gui/$(id -u)/${label}  # stop + unload`,
+        ].join("\n");
+    }
+    const unit = posixShellQuote(executorSystemdUnitNameForId(executorId));
+    return [
+        "Next step (manual — install-service never manages lifecycle):",
+        "  systemctl --user daemon-reload",
+        `  systemctl --user enable --now ${unit}`,
+        `  systemctl --user status ${unit}`,
+        "",
+        "On a headless host, also run `loginctl enable-linger $USER` so the user service",
+        "keeps running without an active login session.",
+    ].join("\n");
+}