@bridge_gpt/mcp-server 0.2.58 → 0.2.60

package/build/executor/service-unit.js

@@ -26,6 +26,18 @@
  *     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.
+ *
+ *     BAPI-1137 makes this a CHECKED property as well as a constructed one: every
+ *     generation path runs the rendered bytes through
+ *     {@link assertExecutorServiceCredentialPostcondition}, and doctor classifies
+ *     an on-disk unit through the same helper. Be precise about what that claim
+ *     covers. It is a statement about the UNIT'S OWN DECLARATIONS — the
+ *     environment keys it declares and the arguments it passes — and nothing
+ *     more. Host-wide SSH keys and agents, login keychains, `gh` authentication
+ *     state, git credential helpers, and the operator's independently managed
+ *     Claude worker authentication are all outside a unit file, are never
+ *     inspected here, and are NOT asserted absent by any classification this
+ *     module produces.
  *  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.
@@ -56,7 +68,7 @@
  * *discriminating* literal ({@link ExecutorServiceArtifactKind}) rather than a
  * loose `string`, so a plist can never be handed to the systemd inspector.
  */
-import { mkdir as fsMkdir, stat as fsStat, writeFile as fsWriteFile } from "node:fs/promises";
+import { chmod as fsChmod, 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";
@@ -76,6 +88,23 @@ export const EXECUTOR_LAUNCHD_FILENAME_SUFFIX = ".plist";
 export const EXECUTOR_SYSTEMD_UNIT_PREFIX = "bridge-gpt-executor-";
 /** systemd user-unit filename suffix. */
 export const EXECUTOR_SYSTEMD_UNIT_SUFFIX = ".service";
+/**
+ * The permission bits every generated unit is written with: owner read/write
+ * only. Applied EXPLICITLY at write time and re-applied to an existing unit,
+ * rather than inherited from the process umask (BAPI-1137).
+ */
+export const EXECUTOR_SERVICE_UNIT_FILE_MODE = 0o600;
+/**
+ * The durable-host mode flag every generated unit carries (BAPI-1137).
+ *
+ * A DECLARATION OF MODE, not a credential: it asks the executor process to
+ * delete any GitHub write variable it inherited, which is safe on a durable
+ * host because that host holds no standing GitHub write credential and its
+ * merges leave the host entirely. It is opt-in precisely because an ordinary
+ * executor's `merge` job legitimately authenticates `gh` from the environment,
+ * and scrubbing there would break a supported configuration.
+ */
+export const EXECUTOR_SERVICE_SCRUB_GITHUB_CREDENTIALS_FLAG = "--scrub-inherited-github-credentials";
 /** The ONLY Bridge environment value baked into a generated unit. */
 export const EXECUTOR_SERVICE_BASE_URL_ENV = "BAPI_BASE_URL";
 /**
@@ -86,6 +115,18 @@ export const EXECUTOR_SERVICE_BASE_URL_ENV = "BAPI_BASE_URL";
  * empty PATH would be strictly worse than the service manager's default.
  */
 export const EXECUTOR_SERVICE_PATH_ENV = "PATH";
+/**
+ * Home-relative directory segments holding the operator's standard macOS log
+ * area. `~/Library/Logs` exists on every macOS user account, which is why the
+ * two launchd log files live DIRECTLY in it under an executor-qualified name
+ * rather than in a Bridge subdirectory: launchd creates the log file but not a
+ * missing parent directory, and the generator's write contract is ONE file (the
+ * unit), so it has no licence to create a log directory either. A subdirectory
+ * would therefore produce a unit whose logging silently never worked.
+ */
+const LAUNCHD_LOG_DIR_SEGMENTS = ["Library", "Logs"];
+/** Filename prefix for the generated launchd stdout/stderr log files. */
+export const EXECUTOR_LAUNCHD_LOG_FILENAME_PREFIX = "com.bridge-gpt.executor.";
 /** Home-relative directory segments holding Darwin LaunchAgents. */
 const LAUNCHD_DIR_SEGMENTS = ["Library", "LaunchAgents"];
 /** Home-relative directory segments holding Linux systemd user units. */
@@ -118,6 +159,24 @@ export function executorSystemdDirForHome(homeDir) {
 export function executorSystemdUnitPathForId(executorId, homeDir) {
     return pathApiForPlatform("linux").join(executorSystemdDirForHome(homeDir), executorSystemdUnitNameForId(executorId));
 }
+/**
+ * The deterministic launchd stdout/stderr log paths for one executor id:
+ * `~/Library/Logs/com.bridge-gpt.executor.<id>.{out,err}.log`.
+ *
+ * Deterministic and per-executor on purpose. A durable host's whole value is
+ * that nobody is watching its terminal, so "where are this service's logs?" must
+ * have an answer an operator can derive from the executor id alone — and two
+ * executors on one host must never interleave into one file.
+ */
+export function executorLaunchdLogPathsForId(executorId, homeDir) {
+    const pathApi = pathApiForPlatform("darwin");
+    const dir = pathApi.join(homeDir, ...LAUNCHD_LOG_DIR_SEGMENTS);
+    const base = `${EXECUTOR_LAUNCHD_LOG_FILENAME_PREFIX}${executorId}`;
+    return {
+        stdout: pathApi.join(dir, `${base}.out.log`),
+        stderr: pathApi.join(dir, `${base}.err.log`),
+    };
+}
 /**
  * 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
@@ -220,6 +279,22 @@ export function validateExecutorServiceRenderInput(input, platform) {
             throw new ExecutorServiceValidationError("base URL must not contain whitespace");
         }
         assertRenderableValue(input.invocation.executable, "service executable");
+        // BAPI-1137: the packaged invocation is held to the EXISTING executor
+        // launcher contract — an absolute node executable plus the absolute packaged
+        // entry point and the `executor` subcommand, exactly as
+        // `resolvePackagedExecutorInvocation` produces. Validating the shape here
+        // rather than accepting an arbitrary prefix is what stops a caller from
+        // smuggling a credential-bearing option into the unit's argument vector
+        // before the rendered-artifact postcondition ever sees it.
+        if (!input.invocation.executable.startsWith("/")) {
+            throw new ExecutorServiceValidationError("service executable must be an absolute path (a persistent unit cannot rely on PATH)");
+        }
+        if (input.invocation.prefixArgs.length !== 2 ||
+            !input.invocation.prefixArgs[0].startsWith("/") ||
+            input.invocation.prefixArgs[1] !== "executor") {
+            throw new ExecutorServiceValidationError("service invocation must be the packaged launcher contract: an absolute entry point " +
+                "followed by the 'executor' subcommand");
+        }
         // 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.
@@ -233,6 +308,13 @@ export function validateExecutorServiceRenderInput(input, platform) {
             assertRenderableValue(repo, "repository name");
         for (const arg of input.invocation.prefixArgs)
             assertRenderableValue(arg, "service argument");
+        // The claim scope is rendered into the argument vector like every other
+        // value, so it is held to the same barrier. A CR/LF here would open an extra
+        // systemd directive, and `parseSystemdStructure` reads only `Environment=`
+        // and the FIRST `ExecStart=` — so an injected directive would sit in the
+        // written unit without the credential postcondition ever inspecting it.
+        for (const runId of input.epicRunIds ?? [])
+            assertRenderableValue(runId, "epic run id");
         return { ok: true };
     }
     catch (error) {
@@ -266,6 +348,10 @@ export function buildExecutorServiceArguments(input) {
     else if (input.repoWide === true) {
         args.push("--repo-wide");
     }
+    // BAPI-1137: durable-host mode, declared in the unit rather than inferred.
+    // Appended LAST so every pre-existing positional assertion over the prefix,
+    // repository, executor-id, and claim-scope ordering is unchanged.
+    args.push(EXECUTOR_SERVICE_SCRUB_GITHUB_CREDENTIALS_FLAG);
     return args;
 }
 // ---------------------------------------------------------------------------
@@ -278,6 +364,18 @@ export function buildExecutorServiceArguments(input) {
  * 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.
+ *
+ * BAPI-1137 adds `StandardOutPath` / `StandardErrorPath`, each XML escaped like
+ * every other interpolated value, so a durable host's output lands somewhere an
+ * operator can read after the fact instead of in launchd's void. systemd needs
+ * no counterpart: a `--user` unit's stdout/stderr already go to journald.
+ *
+ * Two things are deliberately NOT added. The invocation stays a direct
+ * executable with no shell wrapper, so the process receives SIGTERM/SIGINT
+ * itself rather than a shell swallowing it; and no stop-timeout directive is
+ * rendered, because `launchd.plist(5)` documents `ExitTimeOut`'s default only as
+ * "system-defined" and overriding an unknown default with a guess would be a
+ * change of behavior dressed as a clarification.
  */
 export function renderExecutorLaunchdPlist(input) {
     assertValidRenderInput(input, "darwin");
@@ -292,7 +390,11 @@ export function renderExecutorLaunchdPlist(input) {
     if (input.envPath !== undefined && input.envPath.length > 0) {
         envEntries.push(`    <key>${EXECUTOR_SERVICE_PATH_ENV}</key>`, `    <string>${xmlEscape(input.envPath)}</string>`);
     }
-    return [
+    // Durable logging (BAPI-1137). Derived from the executor id and the home
+    // directory already validated above, so the paths are deterministic and carry
+    // no ambient state.
+    const logPaths = executorLaunchdLogPathsForId(input.executorId, input.homeDir);
+    const content = [
         '<?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">',
@@ -307,6 +409,10 @@ export function renderExecutorLaunchdPlist(input) {
         "  <array>",
         programArgs,
         "  </array>",
+        "  <key>StandardOutPath</key>",
+        `  <string>${xmlEscape(logPaths.stdout)}</string>`,
+        "  <key>StandardErrorPath</key>",
+        `  <string>${xmlEscape(logPaths.stderr)}</string>`,
         "  <key>RunAtLoad</key>",
         "  <true/>",
         "  <key>KeepAlive</key>",
@@ -315,6 +421,12 @@ export function renderExecutorLaunchdPlist(input) {
         "</plist>",
         "",
     ].join("\n");
+    // BAPI-1137: the generator refuses to hand back a unit it could not itself
+    // classify `confirmed-absent`. Checking the RENDERED BYTES rather than the
+    // input is deliberate — it is the artifact, not the intent, that ends up on
+    // disk and that doctor later reads back.
+    assertExecutorServiceCredentialPostcondition("launchd-plist", content);
+    return content;
 }
 /**
  * Escape a value for a systemd directive. {@link systemdQuote} handles
@@ -346,7 +458,7 @@ export function renderExecutorSystemdService(input) {
     if (input.envPath !== undefined && input.envPath.length > 0) {
         environmentLines.push(`Environment=${EXECUTOR_SERVICE_PATH_ENV}=${systemdDirectiveValue(input.envPath)}`);
     }
-    return [
+    const content = [
         "[Unit]",
         `Description=${systemdDirectiveValue(`Bridge GPT epic-conductor executor (${input.executorId})`)}`,
         "After=network-online.target",
@@ -362,11 +474,19 @@ export function renderExecutorSystemdService(input) {
         "WantedBy=default.target",
         "",
     ].join("\n");
+    // Same postcondition as the launchd renderer, over the rendered bytes.
+    assertExecutorServiceCredentialPostcondition("systemd-service", content);
+    return content;
 }
 /**
  * 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.
+ *
+ * The BAPI-1137 credential postcondition is inherited rather than repeated: both
+ * renderers assert it over their own rendered bytes before returning, so this
+ * builder — and {@link planExecutorServiceInstall} above it — cannot produce
+ * an artifact that failed the check.
  */
 export function buildExecutorServiceArtifact(input, platform) {
     if (platform === "darwin") {
@@ -501,11 +621,13 @@ function inspectSystemdService(content) {
  * never invents values.
  */
 export function inspectExecutorServiceArtifact(kind, content) {
+    let recovered;
     try {
-        return kind === "launchd-plist" ? inspectLaunchdPlist(content) : inspectSystemdService(content);
+        recovered =
+            kind === "launchd-plist" ? inspectLaunchdPlist(content) : inspectSystemdService(content);
     }
     catch {
-        return {
+        recovered = {
             ok: false,
             baseUrl: null,
             repos: [],
@@ -513,6 +635,251 @@ export function inspectExecutorServiceArtifact(kind, content) {
             problems: ["unit content could not be parsed"],
         };
     }
+    // BAPI-1137: the credential classification is computed by the SAME helper the
+    // renderers use as their write postcondition, so a unit doctor calls compliant
+    // is exactly a unit this module would agree to generate.
+    const declaration = inspectExecutorServiceCredentialDeclaration(kind, content);
+    return {
+        ...recovered,
+        noStandingGithubWriteCredential: declaration.classification,
+        credentialDeclarationProblems: declaration.problems,
+    };
+}
+/**
+ * The COMPLETE set of environment keys a generated unit may declare, compared
+ * case-insensitively (launchd plist keys and systemd `Environment=` names are
+ * both case-sensitive to the service manager, but an operator edit that changed
+ * only case must not slip past this allowlist).
+ *
+ * `BAPI_BASE_URL` is required; `PATH` is optional (BAPI-327). There is no third
+ * entry, and adding one is a deliberate widening of the asserted claim.
+ */
+export const EXECUTOR_SERVICE_UNIT_ENV_ALLOWLIST = [
+    EXECUTOR_SERVICE_BASE_URL_ENV,
+    EXECUTOR_SERVICE_PATH_ENV,
+];
+/** True when `key` is one of the two allowlisted unit environment keys. */
+export function isAllowedExecutorServiceUnitEnvKey(key) {
+    const upper = key.toUpperCase();
+    return EXECUTOR_SERVICE_UNIT_ENV_ALLOWLIST.some((allowed) => allowed.toUpperCase() === upper);
+}
+/** A token that reads as an option: a leading `-` with something after it. */
+function looksLikeOption(token) {
+    return token.startsWith("-") && token.length > 1;
+}
+/**
+ * Check a recovered argument vector against the CLOSED executor contract:
+ *
+ *   <absolute executable> <absolute packaged entry> executor
+ *   (--repo <name>)+  --executor-id <id>
+ *   [ (--epic-run-id <id>)+ | --repo-wide ]
+ *
+ * Values are consumed POSITIONALLY — the token after `--repo` is that
+ * repository's name whatever it looks like — because repository names and paths
+ * are data, not option spellings, and treating a leading `-` in a value as an
+ * unknown option would misclassify a legal unit as credential-bearing.
+ *
+ * Anything else is a violation: an unrecognized option cannot be shown to be
+ * credential-free, and the contract is the whole basis of the claim.
+ */
+export function checkExecutorServiceArgumentContract(argv) {
+    if (argv.length < 3) {
+        return {
+            ok: false,
+            kind: "ambiguous",
+            problem: "the recovered invocation is too short to match the executor launcher contract",
+        };
+    }
+    const [executable, entryPath, subcommand] = argv;
+    if (!executable.startsWith("/") || looksLikeOption(executable)) {
+        return {
+            ok: false,
+            kind: "ambiguous",
+            problem: "the unit's executable is not an absolute path",
+        };
+    }
+    if (!entryPath.startsWith("/") || looksLikeOption(entryPath)) {
+        return {
+            ok: false,
+            kind: "ambiguous",
+            problem: "the unit's packaged entry point is not an absolute path",
+        };
+    }
+    if (subcommand !== "executor") {
+        return {
+            ok: false,
+            kind: "violation",
+            problem: "the unit does not invoke the packaged 'executor' subcommand",
+        };
+    }
+    let repoCount = 0;
+    let executorIdCount = 0;
+    let epicRunIdCount = 0;
+    let repoWide = false;
+    for (let i = 3; i < argv.length; i++) {
+        const token = argv[i];
+        if (token === "--repo" || token === "--executor-id" || token === "--epic-run-id") {
+            if (i + 1 >= argv.length) {
+                return {
+                    ok: false,
+                    kind: "ambiguous",
+                    problem: `'${token}' has no value in the recovered invocation`,
+                };
+            }
+            i++; // positional value — never re-examined as an option
+            if (token === "--repo")
+                repoCount++;
+            else if (token === "--executor-id")
+                executorIdCount++;
+            else
+                epicRunIdCount++;
+            continue;
+        }
+        if (token === "--repo-wide") {
+            repoWide = true;
+            continue;
+        }
+        if (token === EXECUTOR_SERVICE_SCRUB_GITHUB_CREDENTIALS_FLAG) {
+            // Part of the closed contract: a boolean mode declaration that carries no
+            // value and therefore cannot carry a secret.
+            continue;
+        }
+        return {
+            ok: false,
+            kind: "violation",
+            problem: `'${token}' is not part of the closed executor service argument contract`,
+        };
+    }
+    if (repoCount === 0) {
+        return {
+            ok: false,
+            kind: "ambiguous",
+            problem: "the recovered invocation names no repository",
+        };
+    }
+    if (executorIdCount !== 1) {
+        return {
+            ok: false,
+            kind: "ambiguous",
+            problem: "the recovered invocation does not carry exactly one --executor-id",
+        };
+    }
+    if (repoWide && epicRunIdCount > 0) {
+        return {
+            ok: false,
+            kind: "violation",
+            problem: "the recovered invocation carries both --repo-wide and --epic-run-id",
+        };
+    }
+    return { ok: true };
+}
+/** Recover the launchd structures: `EnvironmentVariables` keys + `ProgramArguments`. */
+function parseLaunchdStructure(content) {
+    let envKeys = null;
+    const envBlock = content.match(/<key>EnvironmentVariables<\/key>\s*<dict>([\s\S]*?)<\/dict>/);
+    if (envBlock) {
+        envKeys = Array.from(envBlock[1].matchAll(/<key>([^<]*)<\/key>/g)).map((m) => xmlUnescape(m[1]));
+    }
+    let argv = null;
+    const argsBlock = content.match(/<key>ProgramArguments<\/key>\s*<array>([\s\S]*?)<\/array>/);
+    if (argsBlock) {
+        argv = Array.from(argsBlock[1].matchAll(/<string>([^<]*)<\/string>/g)).map((m) => xmlUnescape(m[1]));
+    }
+    return { envKeys, argv };
+}
+/** Recover the systemd structures: `Environment=` key names + `ExecStart=` tokens. */
+function parseSystemdStructure(content) {
+    const lines = content.split(/\r?\n/);
+    const envKeys = [];
+    let sawEnvironment = false;
+    for (const line of lines) {
+        if (!line.startsWith("Environment="))
+            continue;
+        sawEnvironment = true;
+        // Only the KEY is read. The value after the first `=` is never inspected.
+        const assignment = line.slice("Environment=".length);
+        const separator = assignment.indexOf("=");
+        if (separator <= 0) {
+            // A directive with no `KEY=` shape leaves the block ambiguous rather than
+            // silently contributing nothing.
+            return { envKeys: null, argv: parseSystemdExecStart(lines) };
+        }
+        envKeys.push(assignment.slice(0, separator));
+    }
+    return { envKeys: sawEnvironment ? envKeys : null, argv: parseSystemdExecStart(lines) };
+}
+/** The `ExecStart=` argument vector, or null when the directive is absent. */
+function parseSystemdExecStart(lines) {
+    const execLine = lines.find((l) => l.startsWith("ExecStart="));
+    if (!execLine)
+        return null;
+    return splitSystemdTokens(execLine.slice("ExecStart=".length));
+}
+/**
+ * Classify one unit's credential declaration from its parsed structures.
+ *
+ * SHARED by the renderers (which inspect their own freshly rendered output as a
+ * write postcondition) and by the exported inspector doctor calls over on-disk
+ * bytes. One implementation is the point: a generator and a diagnostic that
+ * each carried their own notion of "clean" would drift, and the drift would
+ * surface as a unit doctor calls compliant that the generator would refuse.
+ */
+export function inspectExecutorServiceCredentialDeclaration(kind, content) {
+    let structure;
+    try {
+        structure =
+            kind === "launchd-plist" ? parseLaunchdStructure(content) : parseSystemdStructure(content);
+    }
+    catch {
+        return {
+            classification: "unverifiable",
+            problems: ["the unit's structure could not be parsed"],
+        };
+    }
+    const problems = [];
+    if (structure.envKeys === null) {
+        problems.push("the unit declares no parsable environment block");
+    }
+    if (structure.argv === null) {
+        problems.push("the unit declares no parsable invocation");
+    }
+    if (structure.envKeys === null || structure.argv === null) {
+        return { classification: "unverifiable", problems };
+    }
+    const disallowedKeys = structure.envKeys.filter((key) => !isAllowedExecutorServiceUnitEnvKey(key));
+    for (const key of disallowedKeys) {
+        // The KEY NAME only. An environment value is never read, echoed, or
+        // examined for token-like content.
+        problems.push(`the unit declares the non-allowlisted environment key '${key}'`);
+    }
+    const argumentContract = checkExecutorServiceArgumentContract(structure.argv);
+    if (!argumentContract.ok)
+        problems.push(argumentContract.problem);
+    if (disallowedKeys.length > 0)
+        return { classification: "present", problems };
+    if (!argumentContract.ok) {
+        return {
+            classification: argumentContract.kind === "violation" ? "present" : "unverifiable",
+            problems,
+        };
+    }
+    return { classification: "confirmed-absent", problems };
+}
+/**
+ * The write postcondition every generation path shares.
+ *
+ * Throws unless the rendered artifact classifies `confirmed-absent`, so a unit
+ * whose declarations cannot be shown credential-free is never written to disk in
+ * the first place. Called by the renderers themselves rather than by their
+ * callers: a postcondition a caller has to remember is one a new caller forgets.
+ */
+export function assertExecutorServiceCredentialPostcondition(kind, content) {
+    const inspection = inspectExecutorServiceCredentialDeclaration(kind, content);
+    if (inspection.classification === "confirmed-absent")
+        return;
+    const detail = inspection.problems[0] ?? "the unit's declarations could not be verified";
+    throw new ExecutorServiceValidationError("the generated unit does not satisfy the no-standing-GitHub-write-credential postcondition " +
+        `(${inspection.classification}): ${detail}`);
 }
 /**
  * Resolve the packaged launcher a persistent unit should bake in: this process's
@@ -564,6 +931,12 @@ export function getExecutorInstallServiceUsage() {
     return [
         "Usage: mcp-server executor install-service --executor-id <id> --repo <name> [--repo <name> ...] [options]",
         "",
+        "The FILE-GENERATION LEG of durable-host mode. It writes one unit and stops there.",
+        "For the supported composed bring-up — planning, consented write, consented start,",
+        "read-only local inspection, and bounded server-observed readiness — run",
+        "`install conductor` instead. Use this command when you deliberately manage the",
+        "service lifecycle yourself.",
+        "",
         "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",
@@ -594,9 +967,15 @@ export function getExecutorInstallServiceUsage() {
         "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.",
         "",
+        "The unit is written with permissions 0600 (owner read/write only), and on macOS it",
+        "declares deterministic stdout/stderr log paths under ~/Library/Logs so a durable",
+        "host's output is readable after the fact; a systemd --user unit logs to journald.",
+        "",
         "This command writes a file and nothing else. Starting, stopping, enabling, and",
         "removing the service stay operator-managed via launchctl / systemctl --user /",
-        "Task Scheduler.",
+        "Task Scheduler. A written unit is NOT readiness, and neither is a started one:",
+        "only a server-observed executor claim, after a start you perform separately, makes",
+        "this host ready to do work.",
     ].join("\n");
 }
 /** Default, production dependency set for the install-service CLI. */
@@ -615,7 +994,10 @@ export function createDefaultExecutorServiceInstallDeps() {
         resolveInvocation: () => resolvePackagedExecutorInvocation(),
         stat: (filePath) => fsStat(filePath),
         mkdir: (dirPath, options) => fsMkdir(dirPath, options),
-        writeFile: (filePath, content) => fsWriteFile(filePath, content, "utf-8"),
+        // Encoding AND mode passed explicitly (BAPI-1137) — never left to the
+        // process umask.
+        writeFile: (filePath, content, options) => fsWriteFile(filePath, content, options ?? { encoding: "utf-8", mode: EXECUTOR_SERVICE_UNIT_FILE_MODE }),
+        chmod: (filePath, mode) => fsChmod(filePath, mode),
         prompt: defaultConsentPrompt,
         log: (message) => console.log(message),
         errorLog: (message) => console.error(message),
@@ -668,7 +1050,11 @@ 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);
+    await deps.writeFile(artifact.path, artifact.content, {
+        encoding: "utf-8",
+        mode: EXECUTOR_SERVICE_UNIT_FILE_MODE,
+    });
+    await secureUnitMode(artifact.path, deps.chmod);
     return { replaced };
 }
 /** Reject anything that is not an absolute http(s) URL. Never echoes the value. */
@@ -736,14 +1122,40 @@ export async function writeExecutorServicePlan(plan, deps, knownExists) {
             current = null;
         }
         if (current === plan.artifact.content) {
+            // An `unchanged` CONTENT outcome still secures the file's mode: a unit
+            // written by an older CLI (or by a run under a looser umask) is
+            // byte-identical and yet group/world readable, and leaving it that way
+            // because "nothing changed" would make the permission guarantee depend on
+            // when the operator first installed.
+            await secureUnitMode(plan.unitPath, deps.chmod);
             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);
+    await deps.writeFile(plan.unitPath, plan.artifact.content, {
+        encoding: "utf-8",
+        mode: EXECUTOR_SERVICE_UNIT_FILE_MODE,
+    });
+    // Belt and braces for the REPLACE path: `mode` is honoured at creation only,
+    // so an existing unit keeps its old bits unless they are set explicitly.
+    await secureUnitMode(plan.unitPath, deps.chmod);
     return { outcome: exists ? "replaced" : "written", unitPath: plan.unitPath, plan };
 }
+/**
+ * Apply {@link EXECUTOR_SERVICE_UNIT_FILE_MODE} through an optional seam.
+ *
+ * A caller without a `chmod` seam is not an error — the freshly created file
+ * already carries the mode from the write — so a missing seam is a no-op rather
+ * than a failure. A chmod that REJECTS does propagate: the caller asked for a
+ * restricted unit, and silently leaving a readable one behind while reporting
+ * success is the failure mode this whole path exists to prevent.
+ */
+async function secureUnitMode(unitPath, chmod) {
+    if (!chmod)
+        return;
+    await chmod(unitPath, EXECUTOR_SERVICE_UNIT_FILE_MODE);
+}
 /** ENOENT means absent; any other rejection is a real failure and propagates. */
 async function targetExists(stat, filePath) {
     try {
@@ -982,6 +1394,9 @@ function formatPostWriteGuidance(artifact, executorId) {
             `  launchctl bootstrap gui/$(id -u) ${posixShellQuote(artifact.path)}`,
             `  launchctl print gui/$(id -u)/${label}    # status`,
             `  launchctl bootout gui/$(id -u)/${label}  # stop + unload`,
+            "",
+            "Starting it is still not readiness: this host is ready only once the Bridge",
+            "server observes an executor claim from it.",
         ].join("\n");
     }
     const unit = posixShellQuote(executorSystemdUnitNameForId(executorId));
@@ -993,5 +1408,8 @@ function formatPostWriteGuidance(artifact, executorId) {
         "",
         "On a headless host, also run `loginctl enable-linger $USER` so the user service",
         "keeps running without an active login session.",
+        "",
+        "Starting it is still not readiness: this host is ready only once the Bridge",
+        "server observes an executor claim from it.",
     ].join("\n");
 }

package/build/executor/types.js

@@ -19,6 +19,11 @@ export const EXECUTOR_JOB_TYPE_VALUES = [
     "smoke",
     // BAPI-1151 registered it server-side; BAPI-1152 lands the executor body.
     "reconcile_overlap",
+    // BAPI-1160 — the deterministic infrastructure re-run. Registered here AND
+    // implemented in `ci-rerun-job.ts`: a job type the server can dispatch but
+    // this union does not carry fails as `ContractError.UnsupportedJobType`,
+    // which is the single most likely way this ticket could ship half-landed.
+    "ci_rerun",
 ];
 /**
  * Server-authoritative completion classification (T2 `ExecutorClassification`,