@bridge_gpt/mcp-server 0.2.37 → 0.2.39

package/build/executor/agent-identity.js

@@ -0,0 +1,32 @@
+/**
+ * The executor's selected agent identity (BAPI-781).
+ *
+ * WHY A MODULE FOR ONE STRING. Before the adapter extraction the literal
+ * `"claude"` appeared throughout the spawn path — in the version probe, the
+ * model lookup, the deny probe, the executable name. Replacing those with a
+ * single shared constant is what lets `ExecutorOptions.agentId` default without
+ * every generic module re-hard-coding the same default, and it gives the
+ * eventual "make this configurable" change exactly one place to touch.
+ *
+ * Claude remains the default because it is the only implemented adapter. That is
+ * a statement about what exists, not a fallback: an agent explicitly selected
+ * but unimplemented resolves to an explicit unsupported result rather than
+ * quietly landing back here (see `executor-adapter-registry.ts`).
+ */
+import { DEFAULT_AGENT_NAME } from "../agent-registry.js";
+/** The agent an executor spawns workers with when none is configured. */
+export const DEFAULT_EXECUTOR_AGENT_ID = DEFAULT_AGENT_NAME;
+/**
+ * Resolve the effective agent id for a set of executor options.
+ *
+ * Normalizes blank/whitespace-only configuration to the default rather than
+ * passing it through: an empty string would resolve to `unknown-agent` and
+ * refuse every claim, which is a confusing way to report "you configured
+ * nothing".
+ */
+export function resolveExecutorAgentId(agentId) {
+    if (typeof agentId !== "string")
+        return DEFAULT_EXECUTOR_AGENT_ID;
+    const trimmed = agentId.trim();
+    return trimmed.length > 0 ? trimmed : DEFAULT_EXECUTOR_AGENT_ID;
+}

package/build/executor/cli.js

@@ -10,13 +10,12 @@ import os from "node:os";
 import { VERSION } from "../version.generated.js";
 import { resolveWorktrunkBinary } from "../start-tickets-prereqs.js";
 import { resolveStartTicketsRepoName } from "../start-tickets-repo.js";
+import { DEFAULT_EXECUTOR_AGENT_ID } from "./agent-identity.js";
 import { createDefaultExecutorDeps } from "./deps.js";
 import { resolveBaseUrl, resolveExecutorApiAccess, EXECUTOR_BASE_URL_REQUIRED_MESSAGE, } from "./credentials.js";
 import { createExecutorHttpClient } from "./http-client.js";
 import { runExecutor } from "./runner.js";
 import { runExecutorWatchCli } from "./watch-cli.js";
-import { sweepOrphanedWorkerConfigDirectories } from "./worker-config-isolation.js";
-import { pathApiForProvisioningPlatform } from "../mcp-provisioning.js";
 /** Fixed executor timing/behavior defaults. */
 const DEFAULT_POLL_INTERVAL_MS = 15_000;
 const DEFAULT_HEARTBEAT_INTERVAL_MS = 60_000;
@@ -39,6 +38,8 @@ export function getExecutorUsage() {
         "Options:",
         "  --repo <name>                 Repo to serve (repeatable).",
         "  --repos=<a,b>                 Comma-separated repos.",
+        "  --epic-run-id <id>            Dedicate this executor to an epic run (repeatable).",
+        "                                Omit for the default repository-wide behavior.",
         "  --base-url <url>              Bridge API endpoint (overrides BAPI_BASE_URL).",
         "  --executor-id <id>            Stable executor id (default: <hostname>-<pid>).",
         "  --max-concurrent <n>          Max concurrent jobs (>= 1, default 1).",
@@ -66,9 +67,21 @@ function parseIntArg(value, flag) {
     }
     return { ok: true, value: n };
 }
+/**
+ * BAPI-794 — `epic_run_id` is always server-minted as `str(uuid.uuid4())`
+ * (`api/library/db/epic_runs.py`), so a standard UUID shape (any version) is a
+ * cheap, safe pre-validation: it rejects an obvious typo before any credential
+ * resolution or executor-loop startup, without over-constraining the CLI to a
+ * version the server does not itself enforce.
+ */
+const EPIC_RUN_ID_PATTERN = /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/;
+function isValidEpicRunId(value) {
+    return EPIC_RUN_ID_PATTERN.test(value);
+}
 /** Parse the executor CLI arguments into resolved options (pure, synchronous). */
 export function parseExecutorArgs(argv, context) {
     const repos = [];
+    const epicRunIds = [];
     let executorId;
     let maxConcurrent = DEFAULT_MAX_CONCURRENT;
     let once = false;
@@ -97,6 +110,17 @@ export function parseExecutorArgs(argv, context) {
                 return { kind: "error", message: "--repos requires a value" };
             repos.push(...v.split(",").map((s) => s.trim()).filter(Boolean));
         }
+        else if (arg === "--epic-run-id") {
+            const v = argv[++i];
+            if (!v || !v.trim())
+                return { kind: "error", message: "--epic-run-id requires a value" };
+            const trimmed = v.trim();
+            if (!isValidEpicRunId(trimmed)) {
+                return { kind: "error", message: `--epic-run-id has an invalid value: ${trimmed}` };
+            }
+            if (!epicRunIds.includes(trimmed))
+                epicRunIds.push(trimmed);
+        }
         else if (arg === "--executor-id") {
             executorId = argv[++i];
             if (!executorId)
@@ -172,28 +196,20 @@ export function parseExecutorArgs(argv, context) {
         advisoryParserEnabled,
         defaultJobTimeoutSeconds: DEFAULT_JOB_TIMEOUT_SECONDS,
         baseUrl,
+        // BAPI-781 — the agent whose executor adapter owns argv, environment, MCP
+        // scoping, auth detection, deny enforcement, and lifecycle. Set explicitly
+        // at the bootstrap boundary so the literal `"claude"` does not reappear
+        // inside generic spawn code. There is no CLI flag for it yet: Claude is the
+        // only implemented adapter, and offering a flag that can only fail closed
+        // would advertise a choice that does not exist.
+        agentId: DEFAULT_EXECUTOR_AGENT_ID,
+        // BAPI-794 — `undefined` (never an empty array) when no --epic-run-id flag
+        // was supplied, so downstream `epicRunIds !== undefined` checks (the claim
+        // manifest builder, startup diagnostics) see an unambiguous "unscoped".
+        ...(epicRunIds.length > 0 ? { epicRunIds } : {}),
     };
     return { kind: "ok", options };
 }
-/**
- * Build the sweep boundary from executor deps, or `null` when this executor was
- * constructed without the filesystem operations the sweep needs. `null` simply
- * skips the sweep — unlike isolation itself, a missing sweep is not a safety
- * problem, only uncollected residue.
- */
-function buildWorkerConfigSweepDeps(deps) {
-    const { tmpdir, readdir, lstatPath, rmRecursive } = deps;
-    if (!tmpdir || !readdir || !lstatPath || !rmRecursive)
-        return null;
-    return {
-        tmpdir,
-        readdir,
-        lstatPath,
-        rmRecursive,
-        join: (...segments) => pathApiForProvisioningPlatform(deps.platform).join(...segments),
-        now: deps.now,
-    };
-}
 function hasRepoFlag(argv) {
     return argv.some((a) => a === "--repo" || a === "--repos" || a.startsWith("--repos="));
 }
@@ -235,6 +251,15 @@ export async function runExecutorCli(argv, overrides = {}) {
         return 1;
     }
     const options = parsed.options;
+    // BAPI-794 — startup diagnostics: only non-secret run identifiers, never
+    // credentials, job payloads, or command arguments beyond the run IDs
+    // themselves (which are not secrets — see EPIC_RUN_ID_PATTERN's docstring).
+    if (options.epicRunIds !== undefined) {
+        errorLog(`executor scoped to epic run(s): ${options.epicRunIds.join(", ")}`);
+    }
+    else {
+        errorLog("executor running repository-wide (no --epic-run-id configured)");
+    }
     // The mutating executor requires an EXPLICIT base URL (BAPI-676): `--base-url`
     // then `BAPI_BASE_URL`, never an implicit production default. Fail here —
     // before any credential resolution, HTTP client, or claim side effect.
@@ -273,24 +298,10 @@ export async function runExecutorCli(argv, overrides = {}) {
         mcpVersion: VERSION,
         fetch: deps.fetch,
     });
-    // BAPI-731: sweep isolation directories orphaned by an ungraceful earlier exit
-    // (SIGKILL, OOM, host reboot) where per-job disposal never ran. Deliberately a
-    // ONE-SHOT startup step, separate from per-job disposal: normal cleanup stays
-    // immediate, and this only reclaims residue. Never blocks claiming — a sweep
-    // failure is a bounded diagnostic, because refusing to start over leftover
-    // temp directories would be a worse failure than the leftovers.
-    const sweep = overrides.sweepOrphanedWorkerConfigDirectories ?? sweepOrphanedWorkerConfigDirectories;
-    try {
-        const isolationSweepDeps = buildWorkerConfigSweepDeps(deps);
-        if (isolationSweepDeps) {
-            const swept = await sweep(isolationSweepDeps);
-            for (const diagnostic of swept.diagnostics)
-                errorLog(diagnostic);
-        }
-    }
-    catch {
-        errorLog("worker config isolation sweep did not complete; continuing startup");
-    }
+    // BAPI-790: the startup orphan sweep is gone with the thing it swept. The
+    // executor no longer creates a per-job Claude configuration directory, so an
+    // ungraceful exit (SIGKILL, OOM, host reboot) leaves no residue for a sweep to
+    // reclaim and startup has one less filesystem step to get wrong.
     const run = overrides.runExecutor ?? runExecutor;
     // Hand the loop the VALIDATED runtime configuration: the parsed options plus the
     // normalized base URL resolution actually settled on.

package/build/executor/deps.js

@@ -9,7 +9,7 @@
  */
 import { execFile, spawn } from "node:child_process";
 import { existsSync } from "node:fs";
-import { readFile, writeFile, appendFile, mkdir, mkdtemp, chmod, rm, readdir, lstat, stat, statfs, } from "node:fs/promises";
+import { open, readFile, writeFile, appendFile, mkdir, mkdtemp, chmod, rm, readdir, lstat, stat, statfs, } from "node:fs/promises";
 import os from "node:os";
 import { promisify } from "node:util";
 import { resolveMcpShimInvocationForRuntime } from "../mcp-server-invocation.js";
@@ -77,6 +77,20 @@ export function createDefaultExecutorDeps() {
         writeFile: (filePath, data) => writeFile(filePath, data, "utf-8"),
         appendFile: (filePath, data) => appendFile(filePath, data, "utf-8"),
         mkdir: (dirPath, opts) => mkdir(dirPath, opts),
+        // BAPI-793 worktree lock. `open(..., "wx")` is atomic at the OS level: it
+        // either creates the file or rejects with EEXIST, with no window between the
+        // two. `0o600` keeps the fencing claim token in the payload readable only by
+        // the operator who owns the executor.
+        writeFileExclusive: async (filePath, data) => {
+            const handle = await open(filePath, "wx", 0o600);
+            try {
+                await handle.writeFile(data, "utf-8");
+            }
+            finally {
+                await handle.close();
+            }
+        },
+        removeFile: (filePath) => rm(filePath, { force: true }),
         stat: (filePath) => stat(filePath).then((s) => ({ mode: s.mode })),
         statMtimeMs: (filePath) => stat(filePath)
             .then((s) => s.mtimeMs)

package/build/executor/env.js

@@ -1,5 +1,6 @@
 /**
- * Secret-free executor worker environment (BAPI-534, TDD §7).
+ * Secret-free GENERIC executor worker environment (BAPI-534, TDD §7; BAPI-790,
+ * BAPI-791; generalized in BAPI-781).
  *
  * v2 executor workers get Bridge MCP access by default (BAPI-724), but NOT
  * through this environment. Access is provisioned into the worktree's
@@ -12,11 +13,31 @@
  * provisioning time instead), and all secret-bearing keys. It constructs a
  * FRESH object from a strict allowlist of non-secret operational keys — it
  * never copies arbitrary `process.env`, so credentials/tokens/headers cannot
- * leak into the spawned `claude` process. The `mcp-invoke` shim (a separate
- * process) resolves `BAPI_API_KEY` itself at call time from the credential
- * store under the worker's redirected `XDG_CONFIG_HOME` — the executor seeds a
- * repo-scoped store into the per-job isolation directory (see
- * `worker-config-isolation.ts`) — so this worker environment never carries it.
+ * leak into a spawned worker process.
+ *
+ * THIS BUILDER IS NOW AGENT-NEUTRAL AND CARRIES NO SECRET AT ALL (BAPI-781).
+ * The single `CLAUDE_CODE_OAUTH_TOKEN` passthrough that used to live here moved
+ * into the Claude adapter (`agent-launchers/claude-executor-adapter.ts`), which
+ * layers it on top of this base. That relocation is the point of the extraction:
+ * forwarding an operator's Claude credential is an AGENT-SPECIFIC decision, and
+ * a generic builder that knew about it would keep every future adapter
+ * Claude-shaped. A different adapter forwards a different name — or none — and
+ * must opt in explicitly rather than inherit Claude's exception.
+ *
+ * `ANTHROPIC_API_KEY` remains absolutely denied here, forwarded or not, and no
+ * adapter can re-admit it through this function — see `EXPLICIT_DENY_KEYS`.
+ *
+ * `CLAUDE_CONFIG_DIR` and `XDG_CONFIG_HOME` REMAIN on the deny list even though
+ * the executor no longer sets them. The deny list defends against the operator's
+ * own ambient values: a redirect exported in the shell that launched the
+ * executor must not reach a worker and silently change which configuration —
+ * and which MCP registrations — the CLI resolves.
+ *
+ * The `mcp-invoke` shim (a separate process) resolves `BAPI_API_KEY` itself at
+ * call time from the operator's real user-scoped credential store, exactly as it
+ * did before BAPI-731, so this worker environment never carries it. The model is
+ * still denied direct reads of that store by the deny layer
+ * (`Read(~/.config/bridge/**)` in `permissions.ts`).
  */
 import { PR_BASE_BRANCH_ENV_VAR } from "../pr-base-contract.js";
 /** Non-secret operational keys forwarded to the worker when present. */
@@ -39,17 +60,33 @@ const SECRET_NAME_FRAGMENTS = ["TOKEN", "SECRET", "PASSWORD", "API_KEY"];
 /**
  * Explicit deny-list of known secret / MCP / conductor keys.
  *
- * BAPI-731 adds the two Claude configuration paths. They are denied on the
- * INHERITED-COPY path and then set explicitly from executor-computed values
- * below, following the `BAPI_BASE_BRANCH` precedent — an operator's
- * `CLAUDE_CONFIG_DIR` or `XDG_CONFIG_HOME` must never be able to redirect a
- * worker back at the operator's own configuration and undo isolation.
+ * The two Claude configuration paths were added by BAPI-731, when the executor
+ * denied the inherited values and then set its own. BAPI-790 removed the setting
+ * half and KEPT the denying half: a worker must inherit the operator's real
+ * configuration (that is how it authenticates now), but it must inherit the
+ * DEFAULT one. An operator who exports `CLAUDE_CONFIG_DIR` or `XDG_CONFIG_HOME`
+ * in the shell that launches the executor would otherwise silently redirect every
+ * worker at a different configuration — and a different MCP registration set —
+ * without anything in the executor choosing that.
  */
-const EXPLICIT_DENY_KEYS = [
+export const EXPLICIT_DENY_KEYS = [
     "BRIDGE_MCP_PROFILE",
     "CONDUCTOR_NODE_PATH",
     "BAPI_API_KEY",
+    // ANTHROPIC_API_KEY has NO passthrough exception (BAPI-791): it stays denied
+    // absolutely, unlike CLAUDE_CODE_OAUTH_TOKEN below, which is denied here too
+    // but is deliberately let back in through the single explicit branch in
+    // the Claude adapter's own env builder, after this allowlisted-copy loop runs.
     "ANTHROPIC_API_KEY",
+    // CLAUDE_CODE_OAUTH_TOKEN is now denied here EXPLICITLY (BAPI-781). Under
+    // BAPI-791 it had to stay off this list, because the generic builder itself
+    // re-admitted it through a single unchanged-copy branch and an explicit deny
+    // would have cancelled that branch. The branch has moved into the Claude
+    // adapter, which layers the key on top of the object this function returns —
+    // so denying it here no longer breaks the passthrough, and it makes the
+    // generic base environment unambiguously credential-free rather than
+    // credential-free-by-omission.
+    "CLAUDE_CODE_OAUTH_TOKEN",
     "OPENAI_API_KEY",
     "GITHUB_TOKEN",
     "GH_TOKEN",
@@ -82,7 +119,7 @@ export function isExecutorEnvKeyAllowed(key) {
         return false;
     return true;
 }
-export function buildExecutorWorkerEnv(parentEnv, options = {}) {
+export function buildExecutorBaseWorkerEnv(parentEnv, options = {}) {
     const env = {};
     for (const key of ALLOWED_ENV_KEYS) {
         if (!isExecutorEnvKeyAllowed(key))
@@ -97,37 +134,11 @@ export function buildExecutorWorkerEnv(parentEnv, options = {}) {
         options.effectiveBaseBranch.length > 0) {
         env[PR_BASE_BRANCH_ENV_VAR] = options.effectiveBaseBranch;
     }
-    // --- Worker config isolation (BAPI-731) --------------------------------
-    // Both paths are assigned from EXPLICIT executor-computed values and are on
-    // `EXPLICIT_DENY_KEYS`, so the inherited-copy loop above can never supply them.
-    // That ordering is the isolation guarantee: an operator `CLAUDE_CONFIG_DIR` or
-    // `XDG_CONFIG_HOME` cannot redirect the worker back at the operator's own
-    // configuration (and its `projects[...].mcpServers` map).
-    if (typeof options.claudeConfigDir === "string" && options.claudeConfigDir.length > 0) {
-        env.CLAUDE_CONFIG_DIR = options.claudeConfigDir;
-    }
-    if (typeof options.xdgConfigHome === "string" && options.xdgConfigHome.length > 0) {
-        env.XDG_CONFIG_HOME = options.xdgConfigHome;
-    }
-    // The ONE deliberately-injected credential, and a genuine exception to this
-    // module's otherwise absolute secret-free rule. It is injected because
-    // isolation REMOVES the worker's previous authentication path: a worker used to
-    // authenticate as a side effect of inheriting the operator's `HOME` and
-    // `~/.claude.json`, and that inheritance is exactly the defect being closed.
-    // Per the measured inventory (`docs/claude/claude-cli-config-isolation-inventory.md`,
-    // finding 4) an operator OAuth/subscription login does NOT follow an isolated
-    // `CLAUDE_CONFIG_DIR`, while `ANTHROPIC_API_KEY` does — so this is the only
-    // supported way an isolated worker can authenticate at all.
-    //
-    // It is passed from an EXPLICIT executor-resolved value rather than copied
-    // (`ANTHROPIC_API_KEY` remains on `EXPLICIT_DENY_KEYS` and still matches the
-    // `API_KEY` secret fragment), so it travels only when the isolation strategy
-    // deliberately supplies it, never as ambient leakage. Nothing writes it to
-    // disk: the only file seeded into the isolated directory is the repo-scoped
-    // Bridge credential store (see `worker-config-isolation.ts`), which never
-    // carries the Anthropic key.
-    if (typeof options.anthropicApiKey === "string" && options.anthropicApiKey.length > 0) {
-        env.ANTHROPIC_API_KEY = options.anthropicApiKey;
-    }
+    // Nothing agent-specific is added here, and deliberately nothing secret. An
+    // adapter that needs to forward an operator-owned credential declares it as a
+    // passthrough and copies it onto the object this function returns; see
+    // `buildClaudeWorkerEnv`. Keeping the base free of every credential is what
+    // makes "which secrets can reach a worker?" answerable per adapter instead of
+    // per call site.
     return env;
 }

package/build/executor/index.js

@@ -10,5 +10,13 @@ export { runExecutor } from "./runner.js";
 // Persistent-service packaging (BAPI-688). The CLI entry plus the PURE helpers
 // doctor needs to enumerate and inspect generated units — doctor must share this
 // module's naming/format contract instead of maintaining a second parser.
-export { runExecutorInstallServiceCli, getExecutorInstallServiceUsage, buildExecutorServiceArtifact, writeExecutorServiceArtifact, inspectExecutorServiceArtifact, executorLaunchdDirForHome, executorSystemdDirForHome, executorIdFromLaunchdFilename, executorIdFromSystemdFilename, EXECUTOR_SERVICE_BASE_URL_ENV, EXECUTOR_SERVICE_PATH_ENV, } from "./service-unit.js";
+export { runExecutorInstallServiceCli, getExecutorInstallServiceUsage, buildExecutorServiceArtifact, writeExecutorServiceArtifact, inspectExecutorServiceArtifact, executorLaunchdDirForHome, executorSystemdDirForHome, executorIdFromLaunchdFilename, executorIdFromSystemdFilename, 
+// Programmatic, lifecycle-free plan/write seam (BAPI-779) — how
+// `install conductor` reaches the generator without shelling out to the CLI.
+planExecutorServiceInstall, writeExecutorServicePlan, resolvePackagedExecutorInvocation, EXECUTOR_SERVICE_BASE_URL_ENV, EXECUTOR_SERVICE_PATH_ENV, } from "./service-unit.js";
+// Consented lifecycle (BAPI-779, R-1). Deliberately a SEPARATE module from the
+// generator above: importing the writer never grants the ability to start a
+// persistent daemon.
+export { buildExecutorServiceStartPlan, buildExecutorServiceStateProbe, formatExecutorServiceStartFailure, inspectExecutorServiceState, startExecutorService, } from "./service-lifecycle.js";
+export { collectExecutorInstallPreflight, formatExecutorInstallPreflight, EXECUTOR_INSTALL_REQUIRED_TOOLS, EXECUTOR_INSTALL_CLAUDE_LOGIN_REMEDIATION, } from "./install-preflight.js";
 export { runExecutorWatchCli, getExecutorWatchUsage, parseExecutorWatchArgs, } from "./watch-cli.js";

package/build/executor/install-preflight.js

@@ -0,0 +1,138 @@
+/**
+ * Executor installation preflight for `install conductor` (BAPI-779).
+ *
+ * This is the gate that runs BEFORE the installer writes a service unit or
+ * starts anything: it answers "can this host actually run a conductor executor?"
+ * loudly, so an unsupported platform or a missing tool fails at the top of the
+ * phase instead of halfway through a persistent-daemon install.
+ *
+ * WHAT IS FATAL, AND WHAT IS NOT. Platform support, an explicit base URL, and
+ * the presence of `wt`, `git`, and `claude` are fatal — none of them can be
+ * worked around later, and provisioning a service that cannot run is worse than
+ * refusing. The Claude login marker is ADVISORY only, and that distinction is
+ * load-bearing: BAPI-790/791 retired every Bridge-managed Anthropic credential,
+ * so the definitive authentication check now happens at the first worker spawn,
+ * not here. Turning the advisory back into a gate would reintroduce exactly the
+ * onboarding barrier that epic removed.
+ *
+ * CREDENTIAL BOUNDARY. The only credential-adjacent read this module performs is
+ * the shared `detectClaudeLogin` marker probe of `<home>/.claude.json`, which
+ * reduces to a single boolean before returning. There is deliberately NO code
+ * path here that reads the OS keychain, a Claude credential file, `.mcp.json`,
+ * `CLAUDE_CODE_OAUTH_TOKEN`, `ANTHROPIC_API_KEY`, a setup token, or the Bridge
+ * credential store — the report type has no field capable of carrying one, and
+ * {@link ExecutorInstallPreflightDeps} exposes no seam that could reach one.
+ */
+import { detectClaudeLogin, formatClaudeLoginAdvisory } from "../claude-login.js";
+import { evaluateExecutorPlatform, formatUnsupportedExecutorPlatform } from "./platform.js";
+/** The executables a conductor executor cannot run without. */
+export const EXECUTOR_INSTALL_REQUIRED_TOOLS = ["wt", "git", "claude"];
+/** The exact remediation for a missing login marker — never a credential gate. */
+export const EXECUTOR_INSTALL_CLAUDE_LOGIN_REMEDIATION = "claude login";
+/** An absolute http(s) URL is the only shape a generated unit may bake. */
+function isExplicitBaseUrl(value) {
+    if (typeof value !== "string" || value.trim().length === 0)
+        return false;
+    let parsed;
+    try {
+        parsed = new URL(value.trim());
+    }
+    catch {
+        return false;
+    }
+    return parsed.protocol === "http:" || parsed.protocol === "https:";
+}
+/**
+ * Collect the preflight report. Never throws: a failing probe becomes a
+ * finding, because a preflight that crashes tells the operator nothing.
+ */
+export async function collectExecutorInstallPreflight(input, deps) {
+    const fatalFindings = [];
+    const warnings = [];
+    const remediations = [];
+    // --- Platform (fatal) ---------------------------------------------------
+    // Reuses the single platform policy (`executor/platform.ts`) rather than
+    // re-listing darwin/linux, so the installer and the runner can never disagree
+    // about which hosts are supported.
+    const platformSupport = evaluateExecutorPlatform(input.platform);
+    if (!platformSupport.supported) {
+        fatalFindings.push(formatUnsupportedExecutorPlatform(String(input.platform)));
+        remediations.push("run the executor on a darwin or linux host; this phase writes and starts a " +
+            "user-domain service unit, which has no supported form here.");
+    }
+    // --- Explicit base URL (fatal) -----------------------------------------
+    const baseUrlExplicit = isExplicitBaseUrl(input.baseUrl);
+    if (!baseUrlExplicit) {
+        fatalFindings.push("no explicit Bridge API base URL was resolved for the service unit " +
+            "(an absolute http(s) URL is required).");
+        remediations.push("set BAPI_BASE_URL to an absolute http(s) endpoint and re-run.");
+    }
+    // --- Required tooling (fatal, one finding per tool) ---------------------
+    const tools = [];
+    for (const name of EXECUTOR_INSTALL_REQUIRED_TOOLS) {
+        let resolved = false;
+        try {
+            resolved = (await deps.lookupExecutable(name)) === true;
+        }
+        catch {
+            // A probe that throws is reported as "not resolved" rather than crashing
+            // the phase; the thrown value is discarded because it can echo a path.
+            resolved = false;
+        }
+        tools.push({ name, resolved });
+        if (!resolved) {
+            fatalFindings.push(`required executable '${name}' did not resolve on PATH.`);
+            remediations.push(`install '${name}' and make sure it resolves on this host's PATH.`);
+        }
+    }
+    // --- Claude login (ADVISORY ONLY) --------------------------------------
+    // Reduced to a boolean by `detectClaudeLogin` itself, which never returns the
+    // parsed object. A missing marker is a warning, never a refusal: BAPI-791
+    // moved the definitive check to the first worker spawn.
+    const login = await detectClaudeLogin({
+        homedir: deps.homedir,
+        readFile: deps.readFile,
+    });
+    if (!login.detected) {
+        warnings.push(formatClaudeLoginAdvisory(login));
+        remediations.push(EXECUTOR_INSTALL_CLAUDE_LOGIN_REMEDIATION);
+    }
+    return {
+        ok: fatalFindings.length === 0,
+        platform: String(input.platform),
+        platformSupported: platformSupport.supported,
+        baseUrlExplicit,
+        tools,
+        claudeLoginDetected: login.detected,
+        fatalFindings,
+        warnings,
+        remediations,
+    };
+}
+/**
+ * Render the report for an operator.
+ *
+ * Prints platform support, base-URL status, per-tool presence, and the boolean
+ * login advisory — and nothing else. There is no wording here about API keys,
+ * setup tokens, or credential capability, because this phase checks for none of
+ * those (see the module docstring's credential boundary).
+ */
+export function formatExecutorInstallPreflight(report) {
+    const lines = [
+        "Executor provisioning preflight",
+        "───────────────────────────────",
+        `  platform:        ${report.platform} (${report.platformSupported ? "supported" : "UNSUPPORTED"})`,
+        `  base URL:        ${report.baseUrlExplicit ? "explicit" : "MISSING"}`,
+    ];
+    for (const tool of report.tools) {
+        lines.push(`  ${tool.name.padEnd(15)}${tool.resolved ? "found on PATH" : "NOT FOUND on PATH"}`);
+    }
+    lines.push(`  claude login:    ${report.claudeLoginDetected ? "marker present (advisory)" : "no marker (advisory)"}`);
+    for (const finding of report.fatalFindings)
+        lines.push(`  refused: ${finding}`);
+    for (const warning of report.warnings)
+        lines.push(`  warn:    ${warning}`);
+    for (const remediation of report.remediations)
+        lines.push(`  → ${remediation}`);
+    return lines.join("\n");
+}