@bridge_gpt/mcp-server 0.2.62 → 0.2.65

package/build/executor-launch.js

@@ -0,0 +1,658 @@
+/**
+ * The run-scoped executor launcher (BAPI-1279).
+ *
+ * `drive-epic` used to start an executor only as a lane of a LOCAL plane. A
+ * launch against production — or a second run in any repository, since plane
+ * lanes serve one run — created a run that nothing would ever claim. This module
+ * gives every such run its own executor, started in the background from the
+ * launching checkout.
+ *
+ * ## Two phases, split around run creation
+ *
+ *   - {@link prepareRunExecutor} runs BEFORE `setup-epic` creates the run. It is
+ *     read-only: it resolves the Git top level and the package entrypoint, and a
+ *     failure here refuses the launch while nothing exists yet.
+ *   - {@link ensureRunExecutor} runs AFTER the run exists. It starts (or reuses)
+ *     exactly one executor scoped to that run and waits for its own heartbeat.
+ *     A failure here leaves the run untouched and server-side; the operator gets
+ *     the log path and the exact command to start it by hand.
+ *
+ * ## Files
+ *
+ * Everything lives under `<git top level>/.bridge/executors/`:
+ *
+ *   - `<runId>.json` — the non-secret record: pid, executor id, run id, base
+ *     URL, start time, and the log path.
+ *   - `<runId>.log` — the executor's stdout and stderr, redacted.
+ *   - `<runId>.lock` — held only while one launch decides whether to start or
+ *     reuse, so two launches for one run cannot both spawn.
+ *
+ * ## Secrets
+ *
+ * The API key travels in the child's ENVIRONMENT only — never argv (readable
+ * through `ps`), never the record, never the log. The executor's output passes
+ * through a small detached relay that redacts known credential values, line by
+ * line so a value split across two pipe chunks is still caught. The relay, not
+ * the launcher, owns the pipes: the launcher exits right after the heartbeat
+ * wait, and a pipe to a dead parent would kill the executor on its next write.
+ *
+ * ## What "reuse" requires
+ *
+ * A live pid is not proof. Pids are recycled, so a record is reused only when
+ * the pid is alive, its command line still names this executor id and run, and
+ * that executor instance's own heartbeat is fresh. Anything short of that and
+ * uncertain is refused rather than signalled or duplicated.
+ */
+import { spawn as nodeSpawn } from "node:child_process";
+import { mkdir, open, readFile, stat, unlink } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { shellQuote } from "./epic-launch-profile.js";
+import { isValidExecutorEpicRunId } from "./executor/claim-scope.js";
+import { ensureGitInfoExcluded } from "./git-ignore-utils.js";
+import { createPlaneExecFile, createPlaneProcessDeps, probeAutomationHealth, resolvePackageEntrypoint, } from "./plane/defaults.js";
+import { buildPlaneRedactor } from "./plane/supervisor.js";
+/** Directory, relative to the Git top level, holding every launcher file. */
+export const RUN_EXECUTOR_DIR = path.join(".bridge", "executors");
+/** The ignore line for {@link RUN_EXECUTOR_DIR}. */
+export const RUN_EXECUTOR_IGNORE_ENTRY = ".bridge/executors/";
+/** Default bound on the heartbeat wait. */
+export const RUN_EXECUTOR_HEARTBEAT_TIMEOUT_MS = 90_000;
+/** Heartbeat poll interval during the wait. */
+export const RUN_EXECUTOR_HEARTBEAT_POLL_MS = 2_000;
+/** A launch lock older than this, with no readable owner, is abandoned. */
+export const RUN_EXECUTOR_LOCK_STALE_MS = 5 * 60_000;
+/** Record schema version. A record with any other version is not trusted. */
+const RUN_EXECUTOR_RECORD_VERSION = 1;
+/**
+ * The relay the executor runs under.
+ *
+ * `node -e` with discrete arguments: `<logPath> <command> <args...>`. It owns
+ * the executor's pipes for the executor's whole life, redacts every credential
+ * value it can see in its OWN environment (which is the executor's), buffers to
+ * a line boundary so a value split across two chunks is still whole when it is
+ * checked, and forwards a stop signal so the executor drains gracefully. It is
+ * CommonJS on purpose: `-e` input is CommonJS regardless of the package type.
+ */
+export const RUN_EXECUTOR_RELAY_SOURCE = [
+    'const { spawn } = require("node:child_process");',
+    'const fs = require("node:fs");',
+    "const [logPath, command, ...args] = process.argv.slice(1);",
+    "const secrets = [process.env.BAPI_API_KEY, process.env.ANTHROPIC_API_KEY, process.env.CLAUDE_CODE_OAUTH_TOKEN]",
+    '  .filter((s) => typeof s === "string" && s.length >= 8).sort((a, b) => b.length - a.length);',
+    "const longest = secrets.length > 0 ? secrets[0].length : 0;",
+    'const redact = (t) => { for (const s of secrets) t = t.split(s).join("[redacted]"); return t; };',
+    'const fd = fs.openSync(logPath, "a", 0o600);',
+    "const write = (t) => { try { fs.writeSync(fd, redact(t)); } catch {} };",
+    'const child = spawn(command, args, { stdio: ["ignore", "pipe", "pipe"], env: process.env });',
+    "const pump = (stream) => {",
+    '  let buf = ""; stream.setEncoding("utf8");',
+    '  stream.on("data", (c) => {',
+    "    buf += c;",
+    '    let cut = buf.lastIndexOf("\\n") + 1;',
+    // An over-long line with no newline is cut early. Redact the whole buffer
+    // FIRST: a key straddling the cut would otherwise be written in two pieces,
+    // neither of which matches. After redaction only an incomplete key prefix
+    // (shorter than `longest`) can remain, and the kept tail is that long.
+    "    if (cut === 0 && buf.length > 65536) { buf = redact(buf); cut = Math.max(0, buf.length - longest); }",
+    "    if (cut > 0) { write(buf.slice(0, cut)); buf = buf.slice(cut); }",
+    "  });",
+    '  stream.on("end", () => { if (buf) write(buf); buf = ""; });',
+    "};",
+    "pump(child.stdout); pump(child.stderr);",
+    'for (const sig of ["SIGTERM", "SIGINT", "SIGHUP"]) {',
+    '  process.on(sig, () => { try { child.kill(sig === "SIGHUP" ? "SIGTERM" : sig); } catch {} });',
+    "}",
+    'child.on("error", () => { write("executor relay: the executor process could not be started\\n"); process.exit(1); });',
+    'child.on("close", (code, signal) => {',
+    '  write("executor relay: executor exited (code=" + code + " signal=" + signal + ")\\n");',
+    "  process.exit(code === null ? 1 : code);",
+    "});",
+].join("\n");
+export function createDefaultRunExecutorLaunchDeps() {
+    const execFile = createPlaneExecFile();
+    const proc = createPlaneProcessDeps();
+    return {
+        execFile,
+        resolveEntrypoint: () => resolvePackageEntrypoint(),
+        mkdir: async (dirPath) => {
+            await mkdir(dirPath, { recursive: true });
+        },
+        readFile: (filePath) => readFile(filePath, "utf-8"),
+        createExclusive: async (filePath, data) => {
+            const handle = await open(filePath, "wx", 0o600);
+            try {
+                await handle.writeFile(data, "utf-8");
+            }
+            finally {
+                await handle.close();
+            }
+        },
+        writeFile: async (filePath, data) => {
+            const handle = await open(filePath, "w", 0o600);
+            try {
+                await handle.writeFile(data, "utf-8");
+            }
+            finally {
+                await handle.close();
+            }
+        },
+        unlink: (filePath) => unlink(filePath),
+        mtimeMs: async (filePath) => {
+            try {
+                return (await stat(filePath)).mtimeMs;
+            }
+            catch {
+                return null;
+            }
+        },
+        ensureIgnored: (repoRoot) => ensureGitInfoExcluded(repoRoot, RUN_EXECUTOR_IGNORE_ENTRY, {
+            readFile: (filePath) => readFile(filePath, "utf-8"),
+            writeFile: async (filePath, data) => {
+                const handle = await open(filePath, "w");
+                try {
+                    await handle.writeFile(data, "utf-8");
+                }
+                finally {
+                    await handle.close();
+                }
+            },
+            mkdir: (dirPath, options) => mkdir(dirPath, options),
+            runCommand: async (file, args, options) => {
+                const result = await execFile(file, args, { cwd: options?.cwd ?? repoRoot });
+                return result.ok
+                    ? { stdout: result.stdout, stderr: result.stderr, exitCode: 0 }
+                    : { stdout: "", stderr: "", exitCode: 1 };
+            },
+            platform: process.platform,
+        }),
+        spawn: (command, args, options) => {
+            const child = nodeSpawn(command, args, {
+                cwd: options.cwd,
+                env: options.env,
+                detached: true,
+                shell: false,
+                windowsHide: true,
+                // The relay owns the executor's pipes; the relay itself writes nothing
+                // anywhere but its log, so nothing ties it to this process.
+                stdio: "ignore",
+            });
+            return child;
+        },
+        isAlive: (pid) => proc.isAlive(pid),
+        readHeartbeat: ({ baseUrl, repoName, apiKey, instanceId }) => probeAutomationHealth({ baseUrl, repoName, apiKey, component: "executor", instanceId }),
+        now: () => Date.now(),
+        sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+        hostname: () => os.hostname(),
+        nodeExecutable: process.execPath,
+        parentEnv: process.env,
+        selfPid: process.pid,
+    };
+}
+/** Paths for one run's launcher files. */
+export function runExecutorPaths(repoRoot, epicRunId) {
+    const dir = path.join(repoRoot, RUN_EXECUTOR_DIR);
+    return {
+        dir,
+        record: path.join(dir, `${epicRunId}.json`),
+        log: path.join(dir, `${epicRunId}.log`),
+        lock: path.join(dir, `${epicRunId}.lock`),
+    };
+}
+/**
+ * A stable, non-secret executor id: `drive-epic-<first 8 of run id>-<host>`.
+ *
+ * Stable so a relaunch for the same run on the same host reports under the same
+ * name. It is not a per-instance identity on its own — the heartbeat wait also
+ * requires a heartbeat NEWER than the spawn, so an earlier instance's last
+ * heartbeat never satisfies it.
+ */
+export function runExecutorIdFor(epicRunId, hostname) {
+    const host = hostname.replace(/[^A-Za-z0-9._-]/g, "-").slice(0, 64) || "host";
+    return `drive-epic-${epicRunId.slice(0, 8)}-${host}`;
+}
+/** The executor argv, after the entrypoint. Discrete arguments; no shell. */
+export function runExecutorArgs(args) {
+    return [
+        "executor",
+        "--repo",
+        args.repoName,
+        "--epic-run-id",
+        args.epicRunId,
+        "--base-url",
+        args.baseUrl,
+        "--executor-id",
+        args.executorId,
+        "--exit-when-run-terminal",
+    ];
+}
+/**
+ * The exact command to start the executor by hand. Shell-quoted, and free of
+ * any credential: the executor reads its key from `BAPI_API_KEY` or the stored
+ * `bapi:<repo>` credential, never from argv.
+ */
+export function renderRunExecutorManualCommand(args) {
+    const argv = [args.nodeExecutable, args.entrypoint, ...runExecutorArgs(args)];
+    return `cd ${shellQuote(args.repoRoot)} && ${argv.map(shellQuote).join(" ")}`;
+}
+/**
+ * Phase one, before the run exists: resolve the checkout and the build.
+ *
+ * Read-only. Uses the plane preflight's `git rev-parse` pattern, so a launch
+ * from outside a Git work tree refuses here and creates nothing.
+ */
+export async function prepareRunExecutor(cwd, deps) {
+    const top = await deps.execFile("git", ["rev-parse", "--show-toplevel"], { cwd });
+    const repoRoot = top.ok ? top.stdout.trim() : "";
+    if (!top.ok || repoRoot.length === 0) {
+        return {
+            ok: false,
+            reason: "not-a-git-work-tree",
+            message: `${cwd} is not inside a Git work tree, so no executor can be started from it. ` +
+                "Run drive-epic from inside the target repository's checkout.",
+        };
+    }
+    const entry = deps.resolveEntrypoint();
+    if (!entry.ok) {
+        return {
+            ok: false,
+            reason: "entrypoint-unresolvable",
+            message: `the Bridge MCP server's own entrypoint could not be located (${entry.candidatesChecked} ` +
+                "candidate(s) checked), so no executor can be started. Reinstall or rebuild the package.",
+        };
+    }
+    return { ok: true, prepared: { repoRoot, entrypoint: entry.entrypoint } };
+}
+/** Parse a record, or `null` when it is not one this build trusts. */
+export function parseRunExecutorRecord(raw) {
+    let value;
+    try {
+        value = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (typeof value !== "object" || value === null)
+        return null;
+    const r = value;
+    if (r.version !== RUN_EXECUTOR_RECORD_VERSION)
+        return null;
+    if (typeof r.pid !== "number" || !Number.isInteger(r.pid) || r.pid <= 0)
+        return null;
+    for (const key of ["executorId", "epicRunId", "baseUrl", "startedAt", "logPath"]) {
+        if (typeof r[key] !== "string" || r[key].length === 0)
+            return null;
+    }
+    if (!isValidExecutorEpicRunId(r.epicRunId))
+        return null;
+    return {
+        version: RUN_EXECUTOR_RECORD_VERSION,
+        pid: r.pid,
+        executorId: r.executorId,
+        epicRunId: r.epicRunId,
+        baseUrl: r.baseUrl,
+        startedAt: r.startedAt,
+        logPath: r.logPath,
+    };
+}
+/**
+ * Is the recorded pid still THIS executor?
+ *
+ * Signal 0 first — a dead pid is settled. A live pid is then checked against the
+ * process table: its command line must still name the recorded executor id and
+ * run. A recycled pid fails that (`mismatch`); a table that cannot be read is
+ * `unknown`, which every caller treats as "do not signal, do not duplicate".
+ */
+export async function verifyRunExecutorProcess(record, deps, cwd) {
+    const liveness = deps.isAlive(record.pid);
+    if (liveness === "dead")
+        return "dead";
+    if (liveness !== "alive")
+        return "unknown";
+    // `-ww`: never truncate. The relay's `-e` source comes before the executor's
+    // flags, so a width-limited listing would hide the very flags checked here.
+    const ps = await deps.execFile("ps", ["-ww", "-o", "command=", "-p", String(record.pid)], {
+        cwd,
+    });
+    if (!ps.ok)
+        return "unknown";
+    const command = ps.stdout.trim();
+    if (command.length === 0)
+        return "dead";
+    const namesExecutor = command.includes(` --executor-id ${record.executorId}`);
+    const namesRun = command.includes(` --epic-run-id ${record.epicRunId}`);
+    return namesExecutor && namesRun ? "verified" : "mismatch";
+}
+/**
+ * Every run-scoped executor record in this checkout.
+ *
+ * `plane down` reads these. Malformed files are listed by name and never
+ * parsed loosely: a kill list is the last thing to guess at.
+ */
+export async function listRunExecutorRecords(repoRoot, deps) {
+    const dir = path.join(repoRoot, RUN_EXECUTOR_DIR);
+    let entries;
+    try {
+        entries = await deps.readdir(dir);
+    }
+    catch {
+        return { records: [], malformed: [] };
+    }
+    const records = [];
+    const malformed = [];
+    for (const entry of entries) {
+        if (!entry.isFile() || !entry.name.endsWith(".json"))
+            continue;
+        let raw;
+        try {
+            raw = await deps.readFile(path.join(dir, entry.name));
+        }
+        catch {
+            malformed.push(entry.name);
+            continue;
+        }
+        const record = parseRunExecutorRecord(raw);
+        if (record === null || `${record.epicRunId}.json` !== entry.name) {
+            malformed.push(entry.name);
+            continue;
+        }
+        records.push(record);
+    }
+    return { records, malformed };
+}
+/**
+ * Delete a run's record on the executor's terminal exit — only when the record
+ * still names THIS executor instance (its id, and its own or its relay's pid).
+ * A record a later launch has since replaced is left alone.
+ */
+export async function removeRunExecutorRecordIfOwned(args, deps) {
+    if (!isValidExecutorEpicRunId(args.epicRunId))
+        return false;
+    const { record: recordPath } = runExecutorPaths(args.repoRoot, args.epicRunId);
+    let record;
+    try {
+        record = parseRunExecutorRecord(await deps.readFile(recordPath));
+    }
+    catch {
+        return false;
+    }
+    if (record === null)
+        return false;
+    if (record.executorId !== args.executorId || !args.pids.includes(record.pid))
+        return false;
+    try {
+        await deps.unlink(recordPath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function errnoCode(err) {
+    return err?.code;
+}
+/**
+ * Take the per-run launch lock. Only one launch decides start-or-reuse for a run
+ * at a time. A lock whose owner is gone — or that is unreadable and old — is
+ * replaced once; a live owner means another launch is deciding right now.
+ */
+async function acquireLaunchLock(lockPath, deps) {
+    const body = JSON.stringify({ pid: deps.selfPid, createdAt: new Date(deps.now()).toISOString() });
+    for (let attempt = 0; attempt < 2; attempt++) {
+        try {
+            await deps.createExclusive(lockPath, body);
+            return true;
+        }
+        catch (err) {
+            if (errnoCode(err) !== "EEXIST")
+                return false;
+        }
+        let ownerPid = null;
+        try {
+            const parsed = JSON.parse(await deps.readFile(lockPath));
+            ownerPid = typeof parsed.pid === "number" && parsed.pid > 0 ? parsed.pid : null;
+        }
+        catch {
+            ownerPid = null;
+        }
+        let abandoned;
+        if (ownerPid !== null) {
+            abandoned = deps.isAlive(ownerPid) === "dead";
+        }
+        else {
+            const mtime = await deps.mtimeMs(lockPath);
+            abandoned = mtime !== null && deps.now() - mtime > RUN_EXECUTOR_LOCK_STALE_MS;
+        }
+        if (!abandoned)
+            return false;
+        try {
+            await deps.unlink(lockPath);
+        }
+        catch {
+            return false;
+        }
+    }
+    return false;
+}
+/**
+ * Wait for the executor instance's OWN heartbeat, newer than `notBeforeMs`.
+ *
+ * The instance-scoped read is the same signal plane lanes are gated on. Another
+ * executor's heartbeat can never satisfy it, and `notBeforeMs` keeps an earlier
+ * instance under the same id from satisfying it either. Returns early, false,
+ * once the process is gone.
+ */
+async function awaitExecutorHeartbeat(args) {
+    const { deps } = args;
+    const timeoutMs = deps.heartbeatTimeoutMs ?? RUN_EXECUTOR_HEARTBEAT_TIMEOUT_MS;
+    const pollMs = deps.heartbeatPollMs ?? RUN_EXECUTOR_HEARTBEAT_POLL_MS;
+    const deadline = deps.now() + timeoutMs;
+    for (;;) {
+        let observation = null;
+        try {
+            observation = await deps.readHeartbeat({
+                baseUrl: args.access.baseUrl,
+                repoName: args.access.repoName,
+                apiKey: args.access.apiKey,
+                instanceId: args.executorId,
+            });
+        }
+        catch {
+            observation = null;
+        }
+        if (observation !== null &&
+            observation.result.kind === "state" &&
+            observation.result.state === "fresh" &&
+            (args.notBeforeMs === null ||
+                (observation.observedAtMs !== null && observation.observedAtMs >= args.notBeforeMs))) {
+            return true;
+        }
+        if (deps.isAlive(args.pid) === "dead")
+            return false;
+        if (deps.now() >= deadline)
+            return false;
+        await deps.sleep(Math.min(pollMs, Math.max(0, deadline - deps.now())));
+    }
+}
+/**
+ * Phase two, after the run exists: start or reuse exactly one executor scoped to
+ * it, and confirm it through its own heartbeat.
+ *
+ * Never stops, rolls back, or retries the run. A failure returns the log path
+ * and the manual command; the run stays server-side and recoverable.
+ */
+export async function ensureRunExecutor(args, deps) {
+    const { prepared, repoName, epicRunId, access } = args;
+    const paths = runExecutorPaths(prepared.repoRoot, epicRunId);
+    const executorId = runExecutorIdFor(epicRunId, deps.hostname());
+    const manualCommand = renderRunExecutorManualCommand({
+        repoRoot: prepared.repoRoot,
+        nodeExecutable: deps.nodeExecutable,
+        entrypoint: prepared.entrypoint,
+        repoName,
+        epicRunId,
+        baseUrl: access.baseUrl,
+        executorId,
+    });
+    const fail = (reason, message, executorMayBeRunning = false) => ({
+        ok: false,
+        reason,
+        message: redactAccess(access, message),
+        logPath: paths.log,
+        manualCommand,
+        executorMayBeRunning,
+    });
+    // The run id becomes a file name; only a server-shaped id may.
+    if (!isValidExecutorEpicRunId(epicRunId)) {
+        return fail("invalid-run-id", `run id '${epicRunId}' is not a valid epic run id`);
+    }
+    try {
+        await deps.mkdir(paths.dir);
+    }
+    catch {
+        return fail("spawn-failed", `could not create ${paths.dir}`);
+    }
+    try {
+        await deps.ensureIgnored(prepared.repoRoot);
+    }
+    catch {
+        // Advisory: an unignored scratch directory is untidy, not unsafe.
+    }
+    if (!(await acquireLaunchLock(paths.lock, deps))) {
+        return fail("launch-in-progress", `another launch is starting the executor for run ${epicRunId} right now (${paths.lock}). ` +
+            "Wait for it to finish, then check the log.", true);
+    }
+    try {
+        // --- Reuse, when a recorded executor is provably this run's and alive ---
+        let existingRaw = null;
+        try {
+            existingRaw = await deps.readFile(paths.record);
+        }
+        catch (err) {
+            if (errnoCode(err) !== "ENOENT") {
+                return fail("record-unreadable", `the executor record ${paths.record} could not be read`);
+            }
+        }
+        if (existingRaw !== null) {
+            const existing = parseRunExecutorRecord(existingRaw);
+            if (existing === null || existing.epicRunId !== epicRunId) {
+                // It may name a live process, so nothing is signalled and nothing is
+                // started beside it. A human reads it once and removes it.
+                return fail("record-unreadable", `the executor record ${paths.record} is not one this build can trust, so it is ` +
+                    "unknown whether an executor is already running for this run. Check the process " +
+                    "it names, remove the file, and start the executor with the command below.", true);
+            }
+            const state = await verifyRunExecutorProcess(existing, deps, prepared.repoRoot);
+            if (state === "verified") {
+                const live = await awaitExecutorHeartbeat({
+                    deps,
+                    access,
+                    executorId: existing.executorId,
+                    pid: existing.pid,
+                    notBeforeMs: null,
+                });
+                if (live) {
+                    return {
+                        ok: true,
+                        outcome: "reused",
+                        executorId: existing.executorId,
+                        pid: existing.pid,
+                        logPath: existing.logPath,
+                        recordPath: paths.record,
+                    };
+                }
+                return fail("existing-executor-unconfirmed", `an executor for run ${epicRunId} is already running (pid ${existing.pid}), but its ` +
+                    "heartbeat could not be confirmed. A second one was NOT started beside it.", true);
+            }
+            if (state === "unknown") {
+                return fail("existing-executor-unconfirmed", `the executor recorded for run ${epicRunId} (pid ${existing.pid}) could not be ` +
+                    "verified, so a second one was NOT started beside it.", true);
+            }
+            // `dead` or `mismatch` (a recycled pid): the record is stale. Replace it.
+            try {
+                await deps.unlink(paths.record);
+            }
+            catch {
+                return fail("record-unreadable", `the stale executor record ${paths.record} could not be removed`);
+            }
+        }
+        // --- Start ---------------------------------------------------------------
+        const childEnv = {};
+        for (const [key, value] of Object.entries(deps.parentEnv)) {
+            if (value !== undefined)
+                childEnv[key] = value;
+        }
+        // Environment only, never argv: this satisfies the executor's ambient-key
+        // rule, exactly as `launchPlaneSupervisor` does for plane members.
+        childEnv.BAPI_API_KEY = access.apiKey;
+        childEnv.BAPI_BASE_URL = access.baseUrl;
+        childEnv.BAPI_REPO_NAME = repoName;
+        const spawnedAtMs = deps.now();
+        let child;
+        try {
+            child = deps.spawn(deps.nodeExecutable, [
+                "-e",
+                RUN_EXECUTOR_RELAY_SOURCE,
+                paths.log,
+                deps.nodeExecutable,
+                prepared.entrypoint,
+                ...runExecutorArgs({ repoName, epicRunId, baseUrl: access.baseUrl, executorId }),
+            ], { cwd: prepared.repoRoot, env: childEnv, detached: true });
+        }
+        catch {
+            // Fixed prose: a thrown spawn error can carry the environment.
+            return fail("spawn-failed", "the executor process could not be started");
+        }
+        child.on("error", () => undefined);
+        const pid = child.pid;
+        if (typeof pid !== "number" || pid <= 0) {
+            return fail("spawn-failed", "the executor process started without a pid");
+        }
+        child.unref();
+        const record = {
+            version: RUN_EXECUTOR_RECORD_VERSION,
+            pid,
+            executorId,
+            epicRunId,
+            baseUrl: access.baseUrl,
+            startedAt: new Date(spawnedAtMs).toISOString(),
+            logPath: paths.log,
+        };
+        try {
+            await deps.writeFile(paths.record, `${JSON.stringify(record, null, 2)}\n`);
+        }
+        catch {
+            // The process is running; without a record `plane down` cannot find it,
+            // but the run is still served. Said, not hidden.
+            return fail("spawn-failed", `the executor started (pid ${pid}) but its record ${paths.record} could not be written; ` +
+                "stop it by pid if you need to", true);
+        }
+        const live = await awaitExecutorHeartbeat({
+            deps,
+            access,
+            executorId,
+            pid,
+            notBeforeMs: spawnedAtMs,
+        });
+        if (!live) {
+            const timeoutSeconds = Math.round((deps.heartbeatTimeoutMs ?? RUN_EXECUTOR_HEARTBEAT_TIMEOUT_MS) / 1000);
+            const exited = deps.isAlive(pid) === "dead";
+            return fail("heartbeat-timeout", exited
+                ? `the executor (pid ${pid}) exited before it sent a heartbeat`
+                : `no heartbeat from the executor (pid ${pid}) arrived within ${timeoutSeconds}s`, !exited);
+        }
+        return { ok: true, outcome: "started", executorId, pid, logPath: paths.log, recordPath: paths.record };
+    }
+    finally {
+        try {
+            await deps.unlink(paths.lock);
+        }
+        catch {
+            /* a leftover lock is replaced once its owner is gone */
+        }
+    }
+}
+/** Redact the one credential this module holds from any text it returns. */
+function redactAccess(access, text) {
+    return buildPlaneRedactor([access.apiKey])(text);
+}