@bridge_gpt/mcp-server 0.2.18 → 0.2.20

package/build/executor/runner.js

@@ -0,0 +1,98 @@
+/**
+ * Poll/claim executor runner (BAPI-534, TDD §7).
+ *
+ * Repeatedly preflights, claims capacity (only when `free_slots > 0`), and
+ * dispatches jobs without blocking the poll loop. Refuses to claim on any fatal
+ * preflight finding. `once` mode performs one preflight/claim cycle and returns
+ * after all active jobs finish. Depends on NO v1 conductor event/ledger module.
+ */
+import { collectExecutorPreflight, buildClaimManifest } from "./preflight.js";
+import { runClaimedJob } from "./job-runner.js";
+import { sweepExecutorWorktrees } from "./worktree-gc.js";
+/**
+ * Run the executor loop. Returns 0 on the `once` path (a single cycle drained);
+ * in continuous mode it does not return (the process is long-lived).
+ */
+export async function runExecutor(options, deps, httpClient, seams = {}) {
+    const collectPreflight = seams.collectPreflight ?? collectExecutorPreflight;
+    const runJob = seams.runJob ?? runClaimedJob;
+    const sweepWorktrees = seams.sweepWorktrees ??
+        ((baseBranch) => sweepExecutorWorktrees({
+            runCommand: deps.runCommand,
+            cwd: deps.cwd,
+            baseBranch,
+            now: deps.now,
+            // Fall back to a no-activity probe when the deps builder omitted the
+            // optional mtime boundary (keeps GC conservative → retains).
+            statMtimeMs: deps.statMtimeMs ?? (async () => null),
+            platform: deps.platform,
+        }));
+    const active = new Map();
+    /**
+     * Run the conservative worktree GC sweep ONLY while the runner owns no active
+     * job worktree. Failures are logged to stderr and never abort claiming
+     * (BAPI-535, TDD §7 teardown).
+     */
+    async function maybeSweepWorktrees() {
+        if (active.size > 0)
+            return;
+        try {
+            await sweepWorktrees(options.baseBranch);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            deps.errorLog(`executor worktree GC sweep failed (non-fatal): ${message.slice(0, 200)}`);
+        }
+    }
+    function dispatch(job, report) {
+        const promise = (async () => {
+            try {
+                await runJob(job, httpClient, options, deps, report);
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                deps.errorLog(`executor job ${job.id} crashed: ${message.slice(0, 200)}`);
+            }
+            finally {
+                active.delete(job.id);
+            }
+        })();
+        active.set(job.id, promise);
+    }
+    for (;;) {
+        const report = await collectPreflight(options, deps, seams.preflightSeams ?? {});
+        if (!report.ok) {
+            deps.errorLog(`executor preflight refused claiming: ${report.fatalFindings.join("; ")}`);
+        }
+        else {
+            let claiming = true;
+            while (claiming && options.maxConcurrent - active.size > 0) {
+                const freeSlots = options.maxConcurrent - active.size;
+                const manifest = buildClaimManifest(report, options, freeSlots);
+                const result = await httpClient.claim(manifest);
+                if (result.kind === "claimed") {
+                    dispatch(result.job, report);
+                }
+                else if (result.kind === "none") {
+                    claiming = false;
+                }
+                else {
+                    deps.errorLog(`executor claim ${result.kind}: ${result.error}`);
+                    claiming = false;
+                }
+            }
+            // Conservative worktree GC runs once per cycle, AFTER the claim attempt and
+            // only while idle (`active.size === 0` — no owned job worktree). This covers
+            // both the startup cycle and between-poll-cycle cadence without ever
+            // sweeping while a job is running. Kept off the pre-claim path so it never
+            // delays claiming a ready job.
+            await maybeSweepWorktrees();
+        }
+        if (options.once)
+            break;
+        await deps.sleep(options.pollIntervalMs);
+    }
+    // `once`: ensure every dispatched job promise settles before returning.
+    await Promise.all(active.values());
+    return 0;
+}

package/build/executor/terminal-mutation.js

@@ -0,0 +1,34 @@
+/**
+ * Send a terminal mutation with the fencing-aware retry policy. Skips entirely
+ * when ownership was already abandoned.
+ */
+export async function sendTerminalMutationWithRetry(params) {
+    const { deps, options, ownership } = params;
+    if (ownership.abandoned)
+        return { outcome: "skipped" };
+    while (true) {
+        const outcome = await params.send();
+        if (outcome === "updated")
+            return { outcome: "success" };
+        if (outcome === "stale_claim") {
+            ownership.abandoned = true;
+            ownership.abandonReason = "stale_claim";
+            return { outcome: "stale_claim" };
+        }
+        if (outcome === "invalid_job_result") {
+            // The server already failed the job — reporting `/fail` afterward is wrong.
+            params.log?.(`${params.kind}: server rejected the result envelope (invalid_job_result)`);
+            return { outcome: "invalid_job_result" };
+        }
+        // retry_later / fatal_http_error — retryable within the dead-man window.
+        if (deps.now() - ownership.lastSuccessfulHeartbeatAt >= options.deadmanMs) {
+            ownership.abandoned = true;
+            ownership.abandonReason = "deadman";
+            return { outcome: "abandoned" };
+        }
+        params.log?.(`${params.kind}: transient mutation failure (${outcome}); retrying`);
+        await deps.sleep(options.heartbeatIntervalMs);
+        if (ownership.abandoned)
+            return { outcome: "abandoned" };
+    }
+}

package/build/executor/test-clock.js

@@ -0,0 +1,109 @@
+export class VirtualClock {
+    t = 0;
+    timers = [];
+    id = 0;
+    now = () => this.t;
+    setTimer = (cb, ms) => {
+        const id = ++this.id;
+        this.timers.push({ at: this.t + ms, cb, id });
+        return id;
+    };
+    clearTimer = (h) => {
+        this.timers = this.timers.filter((x) => x.id !== h);
+    };
+    sleep = (ms) => new Promise((res) => {
+        this.setTimer(() => res(), ms);
+    });
+    /** Fire timers in time order until `predicate()` holds or timers run out. */
+    async tickUntil(predicate, maxSteps = 5000) {
+        let steps = 0;
+        await flushMicrotasks();
+        while (!predicate() && this.timers.length > 0 && steps++ < maxSteps) {
+            this.timers.sort((a, b) => a.at - b.at);
+            const next = this.timers.shift();
+            this.t = next.at;
+            next.cb();
+            await flushMicrotasks();
+        }
+    }
+}
+async function flushMicrotasks() {
+    for (let i = 0; i < 12; i++)
+        await Promise.resolve();
+}
+/** A controllable fake owned process for `implement` spawn tests. */
+export function makeControllableProcess(stdout) {
+    let resolveWait;
+    const waitP = new Promise((r) => {
+        resolveWait = r;
+    });
+    const signals = [];
+    let done = false;
+    return {
+        proc: {
+            pid: 4242,
+            stdout: stdout ?? null,
+            stderr: null,
+            wait: () => waitP,
+            kill: (s) => {
+                signals.push(s);
+                if (!done) {
+                    done = true;
+                    resolveWait({ exitCode: null, signal: s });
+                }
+            },
+        },
+        resolve: (v) => {
+            done = true;
+            resolveWait(v);
+        },
+        signals,
+    };
+}
+/** Build a full fake `ExecutorDeps`, driven by a `VirtualClock`. */
+export function makeFakeExecutorDeps(clock, overrides = {}) {
+    const base = {
+        runCommand: async () => ({ stdout: "", stderr: "", exitCode: 0 }),
+        spawnProcess: () => {
+            throw new Error("spawnProcess not configured for this test");
+        },
+        readFile: async () => {
+            throw new Error("ENOENT");
+        },
+        writeFile: async () => { },
+        mkdir: async () => undefined,
+        stat: async () => ({ mode: 0o644 }),
+        statfs: async () => ({ bavail: 1_000_000, bsize: 4096 }),
+        sleep: clock.sleep,
+        now: clock.now,
+        setTimer: clock.setTimer,
+        clearTimer: clock.clearTimer,
+        env: {},
+        cwd: "/repo",
+        platform: "linux",
+        homedir: () => "/home/tester",
+        fetch: async () => ({ status: 204, text: async () => "" }),
+        log: () => { },
+        errorLog: () => { },
+    };
+    return { ...base, ...overrides };
+}
+/** Sensible default executor options for tests. */
+export function makeTestOptions(overrides = {}) {
+    return {
+        executorId: "exec-test",
+        repos: ["repo-a"],
+        repoName: "repo-a",
+        maxConcurrent: 2,
+        pollIntervalMs: 15000,
+        heartbeatIntervalMs: 60000,
+        deadmanMs: 120000,
+        termGraceMs: 10000,
+        once: true,
+        worktrunkBinary: "wt",
+        baseBranch: "main",
+        advisoryParserEnabled: false,
+        defaultJobTimeoutSeconds: 1200,
+        ...overrides,
+    };
+}

package/build/executor/types.js

@@ -0,0 +1,18 @@
+/**
+ * Epic Conductor v2 executor — core type/boundary definitions (BAPI-534, TDD §7).
+ *
+ * ARCHITECTURE BOUNDARY (TDD §12, Req 1): files under `mcp_server/src/executor/`
+ * are a dumb, pull-based local worker. They MUST NOT import from the v1
+ * conductor event/ledger graph — `conductor/store.ts`, `conductor/taxonomy.ts`,
+ * `conductor/event-accessors.ts`, `conductor/epic-runtime.ts`,
+ * `conductor/epic-reconcile.ts`, `conductor/epic-state.ts`, or any conductor
+ * producer / supervisor-runtime module. Allowed conductor reuse is limited to
+ * read-only / deterministic helpers — the deny-enforcement preflight
+ * (`conductor/deny-enforcement-preflight.ts`), and (BAPI-535 T3b) the local merge
+ * executor (`conductor/local-merge.ts`) plus the read-only Bridge API access +
+ * merge request/response types (`conductor/bridge-api-client.ts`) for the
+ * deterministic `merge` job.
+ * All subprocess / HTTP / filesystem / clock access is behind injected deps so
+ * every requirement is unit-testable on Linux CI with no real I/O.
+ */
+export {};

package/build/executor/verdict-artifact.js

@@ -0,0 +1,53 @@
+/**
+ * Fixed-path verdict-artifact reading (BAPI-535, TDD §9).
+ *
+ * For verdict job types (`spec_review`, `smoke`) the executor reads exactly
+ * `<worktree>/.conductor/result.json` after the worker exits and posts the parsed
+ * object VERBATIM at `/complete`. A missing/unreadable/invalid artifact is a
+ * fail-loud named failure ({@link MissingVerdictArtifact}) — "a verdict can never
+ * be silently absent". The executor performs NO markdown parsing, NO verdict
+ * judgment, and NO schema-specific interpretation; per-`job_type` schema
+ * validation is server-owned at `/complete` (T2/T6).
+ */
+import { MissingVerdictArtifact, ExecutorNamedError } from "./job-errors.js";
+import { pathApiForExecutorPlatform } from "./worktree-inspection.js";
+/** The fixed `.conductor` result directory (relative to the worktree). */
+export const CONDUCTOR_RESULT_DIR = ".conductor";
+/** The fixed verdict artifact filename. */
+export const CONDUCTOR_RESULT_FILE = "result.json";
+/** True only for verdict job types (`spec_review`, `smoke`). */
+export function isVerdictJobType(jobType) {
+    return jobType === "spec_review" || jobType === "smoke";
+}
+/** Join `<worktree>/.conductor/result.json` with platform-correct separators. */
+export function buildVerdictArtifactPath(worktreePath, platform = process.platform) {
+    const pathApi = pathApiForExecutorPlatform(platform);
+    return pathApi.join(worktreePath, CONDUCTOR_RESULT_DIR, CONDUCTOR_RESULT_FILE);
+}
+/**
+ * Read and parse `<worktree>/.conductor/result.json`. Returns the parsed JSON
+ * OBJECT verbatim. Throws {@link ExecutorNamedError} kind
+ * {@link MissingVerdictArtifact} for a missing/unreadable file, invalid JSON, or
+ * a non-object top-level value (array, `null`, string, number, boolean).
+ */
+export async function readVerdictArtifact(worktreePath, deps) {
+    const artifactPath = buildVerdictArtifactPath(worktreePath, deps.platform ?? process.platform);
+    let raw;
+    try {
+        raw = await deps.readFile(artifactPath);
+    }
+    catch {
+        throw new ExecutorNamedError(MissingVerdictArtifact, `verdict artifact missing or unreadable at ${CONDUCTOR_RESULT_DIR}/${CONDUCTOR_RESULT_FILE}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new ExecutorNamedError(MissingVerdictArtifact, `verdict artifact ${CONDUCTOR_RESULT_DIR}/${CONDUCTOR_RESULT_FILE} is not valid JSON`);
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new ExecutorNamedError(MissingVerdictArtifact, `verdict artifact ${CONDUCTOR_RESULT_DIR}/${CONDUCTOR_RESULT_FILE} must be a JSON object`);
+    }
+    return parsed;
+}

package/build/executor/viewer-tabs.js

@@ -0,0 +1,78 @@
+/**
+ * Optional read-only viewer tabs (BAPI-535, TDD §8, G5).
+ *
+ * Opens a NON-OWNING terminal tab that runs `tail -f` against a job's worker log,
+ * visually identical to the v1 per-ticket tabs but strictly read-only: closing
+ * the tab kills nothing, and nothing typed into it affects the job. The tab
+ * command is ALWAYS `tail -f <log>` — never `claude`, Worktrunk, or any
+ * worker-owning process — so the viewing surface is fully decoupled from the
+ * execution surface. Failures are non-fatal: opening a viewer never throws,
+ * never kills the worker, and never changes completion/failure reporting.
+ */
+import { getDefaultSpawnTerminalTabForPlatform, } from "../start-tickets.js";
+/** Env var that force-enables/disables viewer tabs regardless of platform. */
+export const EXECUTOR_VIEWER_TABS_ENV = "BAPI_EXECUTOR_VIEWER_TABS";
+const TRUE_TOKENS = new Set(["1", "true", "on"]);
+const FALSE_TOKENS = new Set(["0", "false", "off"]);
+/**
+ * Whether viewer tabs are enabled: default ON for `darwin`, OFF elsewhere, with
+ * `BAPI_EXECUTOR_VIEWER_TABS=1|true|on` / `0|false|off` overriding either way.
+ */
+export function executorViewerTabsEnabled(platform, env) {
+    const raw = env[EXECUTOR_VIEWER_TABS_ENV];
+    if (typeof raw === "string") {
+        const token = raw.trim().toLowerCase();
+        if (TRUE_TOKENS.has(token))
+            return true;
+        if (FALSE_TOKENS.has(token))
+            return false;
+    }
+    return platform === "darwin";
+}
+/** Single-quote a path for safe embedding in a POSIX shell command. */
+function shellQuote(value) {
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+/**
+ * Build the read-only tail-follow shell command. The executable action is always
+ * exactly `tail -f <worker-log-path>` — it can never own the worker process.
+ */
+export function buildTailFollowCommand(workerLogPath) {
+    return `tail -f ${shellQuote(workerLogPath)}`;
+}
+/**
+ * Open a read-only viewer tab tailing the worker log. Returns a `skipped` result
+ * when viewer tabs are disabled and a `failed` result (never a throw) when the
+ * spawn boundary reports/raises a failure — the worker lifecycle is untouched.
+ */
+export async function openExecutorViewerTab(options) {
+    if (!executorViewerTabsEnabled(options.platform, options.env)) {
+        return { status: "skipped", reason: "viewer tabs disabled for this platform/config" };
+    }
+    const command = buildTailFollowCommand(options.workerLogPath);
+    const spawnTab = options.spawnTab ?? getDefaultSpawnTerminalTabForPlatform(options.platform);
+    const terminal = options.terminal ?? "terminal";
+    // A minimal StartTicketsDeps for the shared spawner; `spawnTerminalTab` is
+    // self-referential (only used by higher-level orchestration, not the leaf
+    // spawner) and never spawns a worker here.
+    const startTicketsDeps = {
+        runCommand: options.runCommand,
+        platform: options.platform,
+        env: options.env,
+        cwd: options.cwd,
+        spawnTerminalTab: spawnTab,
+    };
+    try {
+        const result = await spawnTab(startTicketsDeps, terminal, command, {
+            key: options.ticketKey ?? "",
+            worktreePath: options.worktreePath,
+        });
+        if (result.ok)
+            return { status: "opened" };
+        return { status: "failed", reason: result.error };
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        return { status: "failed", reason: reason.slice(0, 200) };
+    }
+}

package/build/executor/watch-cli.js

@@ -0,0 +1,113 @@
+/**
+ * `executor watch <job>` subcommand (BAPI-535, TDD §8).
+ *
+ * Ad-hoc, READ-ONLY attachment to a running (or recently-run) job's worker log:
+ * it resolves the local job-log registry record, verifies the log file exists,
+ * and `tail -f`s it with inherited stdio. It NEVER sends a signal to the worker
+ * process and never owns the execution lifecycle — closing the watch leaves the
+ * worker untouched. Missing registry records or missing log files fail loud with
+ * actionable stderr text and a non-zero exit code.
+ */
+import { spawn } from "node:child_process";
+import { access } from "node:fs/promises";
+import os from "node:os";
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { readExecutorJobLogRecord, } from "./job-log-registry.js";
+export function getExecutorWatchUsage() {
+    return [
+        "Usage: mcp-server executor watch <job-id>",
+        "",
+        "Attach read-only to a running (or recently-run) executor job's worker log",
+        "via `tail -f`. Closing the watch never affects the worker process.",
+        "",
+        "Arguments:",
+        "  <job-id>        Numeric executor job id to watch.",
+        "",
+        "Options:",
+        "  -h, --help      Show this help.",
+    ].join("\n");
+}
+/** Accept EXACTLY one numeric job id; reject missing/non-numeric/extra args. */
+export function parseExecutorWatchArgs(argv) {
+    const positionals = [];
+    for (const arg of argv) {
+        if (arg === "-h" || arg === "--help")
+            return { kind: "help" };
+        if (arg.startsWith("-"))
+            return { kind: "error", message: `unknown argument: ${arg}` };
+        positionals.push(arg);
+    }
+    if (positionals.length === 0) {
+        return { kind: "error", message: "a numeric <job-id> is required" };
+    }
+    if (positionals.length > 1) {
+        return { kind: "error", message: "exactly one <job-id> is accepted" };
+    }
+    const raw = positionals[0];
+    if (!/^[0-9]+$/.test(raw)) {
+        return { kind: "error", message: `job id must be numeric: '${raw}'` };
+    }
+    return { kind: "ok", jobId: Number(raw) };
+}
+/**
+ * Spawn `tail -f <log_path>` with inherited stdio for interactive CLI attachment.
+ * Resolves with the tail process's numeric exit code. NEVER signals the worker.
+ */
+export function spawnTailFollow(logPath, spawnImpl = spawn) {
+    return new Promise((resolve) => {
+        const child = spawnImpl("tail", ["-f", logPath], { stdio: "inherit" });
+        child.on("close", (code) => resolve(code ?? 0));
+        child.on("error", () => resolve(1));
+    });
+}
+/** Build the default (production) registry deps from real fs/env/os boundaries. */
+export function createDefaultWatchRegistryDeps() {
+    return {
+        readFile: (p) => readFile(p, "utf-8"),
+        writeFile: (p, data) => writeFile(p, data, "utf-8"),
+        mkdir: (p, opts) => mkdir(p, opts),
+        env: process.env,
+        tmpdir: () => os.tmpdir(),
+        platform: process.platform,
+    };
+}
+async function defaultLogExists(logPath) {
+    try {
+        await access(logPath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Resolve the job-log record and attach read-only via `tail -f`. Returns a
+ * numeric exit code: `0` on a clean tail exit, non-zero on a missing registry
+ * record or missing log file (with actionable stderr).
+ */
+export async function runExecutorWatchCli(argv, overrides = {}) {
+    const errorLog = overrides.errorLog ?? ((m) => console.error(m));
+    const parsed = parseExecutorWatchArgs(argv);
+    if (parsed.kind === "help") {
+        errorLog(getExecutorWatchUsage());
+        return 0;
+    }
+    if (parsed.kind === "error") {
+        errorLog(`Error: ${parsed.message}\n\n${getExecutorWatchUsage()}`);
+        return 1;
+    }
+    const registryDeps = overrides.registryDeps ?? createDefaultWatchRegistryDeps();
+    const readRecord = overrides.readRecord ?? readExecutorJobLogRecord;
+    const record = await readRecord(parsed.jobId, registryDeps);
+    if (!record.ok) {
+        errorLog(`Error: no worker log registered for job ${parsed.jobId}: ${record.reason}`);
+        return 1;
+    }
+    const logExists = overrides.logExists ?? defaultLogExists;
+    if (!(await logExists(record.record.log_path))) {
+        errorLog(`Error: worker log for job ${parsed.jobId} is missing at ${record.record.log_path}`);
+        return 1;
+    }
+    const spawnTail = overrides.spawnTail ?? ((logPath) => spawnTailFollow(logPath));
+    return spawnTail(record.record.log_path);
+}

package/build/executor/worker-command.js

@@ -0,0 +1,106 @@
+/**
+ * Headless Claude worker command construction (BAPI-534, TDD §7).
+ *
+ * Resolves the exact argv, model alias, and prompt for a spawned worker. Model
+ * aliases resolve through the agent registry (never a raw untrusted string); no
+ * MCP config is ever added. When no safe alias is available, `--model` is omitted.
+ */
+import { resolveAgentSpec, resolveModelAlias, isModelTier, isValidModelAlias, } from "../agent-registry.js";
+import { isRecoveryJobType } from "./job-types.js";
+/**
+ * Resolve the Claude model alias from a job payload. Accepts a direct
+ * `model_alias` only when it passes registry alias validation AND the static
+ * Claude allowlist; otherwise resolves from a valid `model_tier` through the
+ * registry. Returns `null` when no safe alias is available (so `--model` is
+ * omitted) — an unsafe/invalid string is never returned.
+ */
+export function resolveExecutorModelAlias(payload) {
+    const agent = resolveAgentSpec("claude");
+    if (!agent)
+        return null;
+    const p = payload && typeof payload === "object" ? payload : {};
+    const directRaw = p.model_alias;
+    if (typeof directRaw === "string" && directRaw.trim().length > 0) {
+        const direct = directRaw.trim();
+        const allowed = !agent.staticModelAliasAllowlist || agent.staticModelAliasAllowlist.includes(direct);
+        if (isValidModelAlias(direct) && allowed) {
+            return direct;
+        }
+        // An invalid/disallowed direct alias falls through to the tier path — never
+        // returned as-is.
+    }
+    const tier = isModelTier(p.model_tier) ? p.model_tier : null;
+    return resolveModelAlias(agent, tier, null);
+}
+/**
+ * Resolve the worker prompt for the explicit-prompt and legacy synthesis paths.
+ * Uses an explicit non-empty `payload.prompt` verbatim; otherwise, for
+ * `implement` and the recovery jobs, builds the conservative
+ * `/implement-ticket <ticket_key> --auto` prompt.
+ *
+ * Structured `payload.prompt_spec` rendering (the `spec_review` path) is NOT done
+ * here: it needs the prepared worktree/git state, so `job-runner.ts` renders it
+ * in the prepared-spawn path AFTER worktree preparation. `spec_review` therefore
+ * returns `ok:false` from this function by design — that non-ok result is the
+ * signal for the runner to fall through to prompt-spec rendering, not a terminal
+ * failure. A real spawn job with neither an explicit prompt, a synthesis path,
+ * nor a `prompt_spec` is the genuine contract failure.
+ */
+/**
+ * True for the job types that synthesize `/implement-ticket <KEY> --auto` when no
+ * explicit `payload.prompt` is present: the first-pass `implement` plus the
+ * recovery jobs (`remediate`/`ci_fix`/`rebase`), which re-enter the SAME
+ * correction loop on the ticket's existing branch/PR. Recovery classification is
+ * shared with dispatch and worktree reuse via `isRecoveryJobType` (`job-types.ts`)
+ * so eligibility cannot drift. Verdict jobs (`spec_review`/`smoke`) are NOT here —
+ * they carry an explicit `payload.prompt` and write a fixed-path artifact (T6/T5b).
+ */
+function synthesizesImplementPrompt(jobType) {
+    return jobType === "implement" || isRecoveryJobType(jobType);
+}
+export function resolveExecutorPrompt(job) {
+    const payload = job.payload && typeof job.payload === "object"
+        ? job.payload
+        : {};
+    // An explicit prompt wins and is returned VERBATIM (un-trimmed), but a
+    // whitespace-only string is not a usable worker instruction — treat it as
+    // absent so a recovery/implement job still falls back to the synthesized
+    // `/implement-ticket <KEY> --auto` correction prompt below.
+    const explicit = payload.prompt;
+    if (typeof explicit === "string" && explicit.trim().length > 0) {
+        return { ok: true, prompt: explicit };
+    }
+    // `/implement-ticket <KEY> --auto` is the full correction engine, not just a
+    // first-pass implementer: its post-PR loop owns CI-failure correction, review-
+    // change addressing, and merge-conflict resolution (see .claude/commands/
+    // implement-ticket.md "Clean session exit"). So the recovery jobs that operate
+    // on the ticket's existing branch/PR — `remediate`/`ci_fix`/`rebase` — resume
+    // through the same command, which detects the outstanding CI/review/conflict
+    // state and continues rather than restarting. Without this, a code_review
+    // `changes_requested` (near-certain in real runs) enqueues a `remediate` job
+    // that fails `no usable prompt` and strands the run (BAPI-528 Milestone-A gap #3).
+    const ticketKey = typeof job.ticket_key === "string" && job.ticket_key.trim().length > 0
+        ? job.ticket_key.trim()
+        : null;
+    if (synthesizesImplementPrompt(job.job_type) && ticketKey) {
+        return { ok: true, prompt: `/implement-ticket ${ticketKey} --auto` };
+    }
+    return {
+        ok: false,
+        error: `no usable prompt for job_type '${job.job_type}' (no payload.prompt and no ticket_key)`,
+    };
+}
+/**
+ * Build the exact headless Claude argv. `--model <alias>` is included only when
+ * an alias is provided. No MCP config arguments are ever emitted.
+ */
+export function buildClaudeExecutorArgv(prompt, alias) {
+    const argv = ["-p", prompt, "--output-format", "stream-json", "--verbose"];
+    if (alias) {
+        argv.push("--model", alias);
+    }
+    argv.push("--dangerously-skip-permissions");
+    return argv;
+}
+/** The worker executable is always exactly `claude`. */
+export const CLAUDE_EXECUTABLE = "claude";