@bridge_gpt/mcp-server 0.2.18 → 0.2.20

package/build/executor/job-runner.js

@@ -0,0 +1,822 @@
+/**
+ * Claimed-job execution engine (BAPI-534 core, BAPI-535 job behaviors; TDD §7/§8/§9).
+ *
+ * A single claim-owned path runs the `smoke` no-op acceptance job (the acceptance
+ * spine — no real worker LLM), the deterministic `merge` job (no worktree / no
+ * worker), and real headless spawn jobs (`implement`, `resume`, `spec_review`,
+ * plus the recovery jobs `remediate`/`ci_fix`/`rebase`; see `job-types.ts`).
+ * The claim response's `claim_token` + `repo_name` are used unchanged for every
+ * heartbeat/complete/fail. Once ownership is abandoned (stale-claim or dead-man),
+ * the executor stops touching the worktree and never reports success.
+ *
+ * BAPI-535 additions: `merge` (deterministic local `gh`), `resume` pre-spawn
+ * protocol (preserve-work-by-construction), verdict-artifact reading for
+ * `spec_review`, plus per-job worker-log tee, watch registry, and optional
+ * read-only viewer tabs wired around every spawned worker.
+ */
+import os from "node:os";
+import { buildExecutorWorkerEnv } from "./env.js";
+import { runHeartbeatLoop } from "./heartbeat.js";
+import { isExecutorNamedError, toExecutorFailure, secretFreeErrorMessage, MissingVerdictArtifact, } from "./job-errors.js";
+import { buildConductorMergeAccessForExecutorJob, buildDefaultMergeLocalDeps, runExecutorMergeJob, MERGE_RETRYABLE, MERGE_FAILED, } from "./merge-job.js";
+import { createObservationState } from "./observation.js";
+import { provisionExecutorDenyLayer } from "./permissions.js";
+import { runProcessWithTimeout } from "./process.js";
+import { prepareResumeSpawn } from "./resume-pre-spawn.js";
+import { renderPromptSpecPrompt } from "./prompt-spec.js";
+import { buildGenericSuccessResult, buildSmokeResult, commitResidue, readCompletionArtifacts, resolveJobTimeoutSeconds, } from "./results.js";
+import { sendTerminalMutationWithRetry } from "./terminal-mutation.js";
+import { isVerdictJobType, readVerdictArtifact } from "./verdict-artifact.js";
+import { createWorkerLogTee, closeWorkerLogTee, teeAsyncIterable, } from "./worker-log.js";
+import { registerExecutorJobLog, markExecutorJobLogFinished, } from "./job-log-registry.js";
+import { executorViewerTabsEnabled, openExecutorViewerTab } from "./viewer-tabs.js";
+import { isRecoveryJobType, isSpawnJobType } from "./job-types.js";
+import { validateWorkerFinalization } from "./worker-finalization.js";
+import { ensureExecutorWorktree } from "./worktree.js";
+import { buildClaudeExecutorArgv, CLAUDE_EXECUTABLE, resolveExecutorModelAlias, resolveExecutorPrompt, } from "./worker-command.js";
+import { collectGitTelemetry } from "./observation.js";
+/** Default runtime for the no-op smoke process (ms). */
+const DEFAULT_SMOKE_DURATION_MS = 100;
+/** ProcessClassification maps 1:1 onto the wire ExecutorClassification. */
+function toWireClassification(c) {
+    return c;
+}
+function classificationToErrorKind(c) {
+    switch (c) {
+        case "timeout":
+            return "Timeout";
+        case "killed":
+            return "Killed";
+        default:
+            return "WorkerCrashed";
+    }
+}
+function boundedError(err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return message.slice(0, 200);
+}
+function nowIso(deps) {
+    return new Date(deps.now()).toISOString();
+}
+/** Build the injected resume pre-spawn seams from executor deps/options. */
+function buildResumeSeams(deps, options) {
+    return {
+        runCommand: deps.runCommand,
+        platform: deps.platform,
+        env: deps.env,
+        cwd: deps.cwd,
+        worktrunkBinary: options.worktrunkBinary,
+        baseBranch: options.baseBranch,
+        pathExists: async (p) => {
+            try {
+                await deps.stat(p);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        },
+    };
+}
+/** Build the local job-log registry deps (secret-free) from executor deps. */
+function buildJobLogRegistryDeps(deps) {
+    return {
+        readFile: deps.readFile,
+        writeFile: deps.writeFile,
+        mkdir: deps.mkdir,
+        env: deps.env,
+        tmpdir: () => os.tmpdir(),
+        platform: deps.platform,
+    };
+}
+/**
+ * Default merge dispatch: resolve Bridge API access, then run the deterministic
+ * merge. Exported for unit tests (access-resolution failure → retryable). The
+ * `controls.signal` (overall-timeout abort) is threaded into local merge deps
+ * without changing the local `gh` credential model.
+ */
+export async function defaultRunMergeForClaimed(job, deps, _options, controls) {
+    const accessResult = await buildConductorMergeAccessForExecutorJob({
+        env: deps.env,
+        cwd: deps.cwd,
+        homedir: deps.homedir,
+        platform: deps.platform,
+        readFile: deps.readFile,
+        stat: deps.stat,
+    });
+    if (!accessResult.ok) {
+        // Access resolution feeds only the executor's read-only CI re-poll; a missing
+        // or temporarily-unavailable Bridge API access is transient infrastructure, so
+        // it is RETRYABLE (BAPI-572). The local `gh` credential model is unchanged.
+        return {
+            ok: false,
+            failure: {
+                error_kind: MERGE_RETRYABLE,
+                error_message: accessResult.error,
+                classification: "crashed",
+            },
+        };
+    }
+    return runExecutorMergeJob(job, {
+        access: accessResult.access,
+        // Thread the overall-timeout abort signal into local merge deps WITHOUT
+        // changing the local `gh` credential model (the signal is not a credential).
+        localMergeDeps: buildDefaultMergeLocalDeps(deps, controls?.signal),
+    });
+}
+/** An in-memory owned process for the no-op `smoke` acceptance job. */
+function createNoopProcess(deps, durationMs, message) {
+    let killResolve = null;
+    const killed = new Promise((res) => {
+        killResolve = res;
+    });
+    let done = false;
+    async function* stdout() {
+        if (message)
+            yield message;
+    }
+    return {
+        pid: undefined,
+        stdout: stdout(),
+        stderr: null,
+        async wait() {
+            const natural = deps
+                .sleep(durationMs)
+                .then(() => ({ exitCode: 0, signal: null }));
+            const result = await Promise.race([natural, killed]);
+            done = true;
+            return result;
+        },
+        kill(signal) {
+            if (done)
+                return;
+            killResolve?.({ exitCode: null, signal });
+        },
+    };
+}
+/** Run the process and heartbeat loop concurrently; return the process outcome. */
+async function superviseProcess(params) {
+    const isDoneRef = { value: false };
+    const hb = runHeartbeatLoop({
+        job: params.job,
+        httpClient: params.httpClient,
+        options: params.options,
+        deps: params.deps,
+        ownership: params.ownership,
+        proc: params.proc,
+        observation: params.observation,
+        collectTelemetry: params.collectTelemetry,
+        isDone: () => isDoneRef.value,
+    });
+    const result = await runProcessWithTimeout(params.proc, params.timeoutSeconds, params.deps, {
+        termGraceMs: params.options.termGraceMs,
+        onStdout: (chunk) => params.observation.recordStdout(chunk),
+    });
+    isDoneRef.value = true;
+    await hb;
+    params.observation.setExitCode(result.exitCode);
+    return result;
+}
+function terminalToRunResult(terminal, successStatus) {
+    switch (terminal.outcome) {
+        case "success":
+            return { status: successStatus };
+        case "invalid_job_result":
+            return { status: "failed", reason: "invalid_job_result" };
+        case "stale_claim":
+            return { status: "abandoned", reason: "stale_claim" };
+        case "abandoned":
+            return { status: "abandoned", reason: "deadman" };
+        case "skipped":
+            return { status: "abandoned", reason: "already_abandoned" };
+    }
+}
+/** Dispatch and run a single claimed job. */
+export async function runClaimedJob(job, httpClient, options, deps, _report, seams = {}) {
+    const ownership = {
+        abandoned: false,
+        lastSuccessfulHeartbeatAt: deps.now(),
+    };
+    const observation = createObservationState({ now: deps.now }, { advisoryParserEnabled: options.advisoryParserEnabled });
+    // `merge` is a deterministic executor action: dispatched BEFORE any worktree
+    // ensure/recreate or worker-spawn logic — it ensures no worktree and spawns no
+    // worker (TDD §5/§9).
+    if (job.job_type === "merge") {
+        return runMergeJob(job, httpClient, options, deps, ownership, observation, seams);
+    }
+    if (job.job_type === "smoke") {
+        return runSmokeJob(job, httpClient, options, deps, ownership, observation);
+    }
+    // `implement`/`resume`/`spec_review` and the recovery jobs (`remediate`/
+    // `ci_fix`/`rebase`) all run through the real headless-spawn path — dispatched
+    // via the shared `isSpawnJobType` policy (`job-types.ts`) AFTER the dedicated
+    // `merge` and `smoke` branches so those keep their bespoke handling.
+    if (isSpawnJobType(job.job_type)) {
+        return runSpawnJob(job, httpClient, options, deps, ownership, observation, seams);
+    }
+    // Unsupported job type — fail server-side; never spawn.
+    await httpClient.fail(job, {
+        error_kind: "ContractError.UnsupportedJobType",
+        error_message: `unsupported job_type '${job.job_type}' in executor T3b`,
+        classification: "crashed",
+    });
+    return { status: "failed", reason: "unsupported_job_type" };
+}
+/**
+ * Adapt a `runMerge(...)` promise into an {@link OwnedChildProcess} so the merge
+ * flow is supervised by the SAME heartbeat/deadman/timeout path as spawn/smoke
+ * jobs even though it spawns no worker. `wait()` resolves when the merge outcome
+ * is available (exit_code 0 on `ok`, 1 otherwise); `kill()` aborts the internal
+ * {@link AbortController} (cancelling in-flight local `gh` work) and resolves the
+ * owned process as killed. The stored outcome/error let the runner map the
+ * supervised result to `/complete` or `/fail` afterwards (killed/timeout is read
+ * from the supervised `ProcessRunResult`/`ownership`, not from this adapter).
+ */
+function createMergeFlowProcess(startMerge) {
+    const controller = new AbortController();
+    let outcome;
+    let error;
+    let done = false;
+    let settleWait = () => { };
+    const waitPromise = new Promise((resolve) => {
+        settleWait = resolve;
+    });
+    // Start the merge flow immediately; capture its resolution/rejection.
+    startMerge(controller.signal).then((result) => {
+        outcome = result;
+        if (!done) {
+            done = true;
+            settleWait({ exitCode: result.ok ? 0 : 1, signal: null });
+        }
+    }, (err) => {
+        error = err;
+        if (!done) {
+            done = true;
+            settleWait({ exitCode: 1, signal: null });
+        }
+    });
+    const proc = {
+        pid: undefined,
+        stdout: null,
+        stderr: null,
+        async wait() {
+            return waitPromise;
+        },
+        kill(signal) {
+            if (done)
+                return;
+            controller.abort();
+            done = true;
+            settleWait({ exitCode: null, signal });
+        },
+    };
+    return {
+        proc,
+        getOutcome: () => outcome,
+        getError: () => error,
+    };
+}
+/**
+ * Run a deterministic `merge` job: NO worktree ensured, NO worker spawned. Unlike
+ * the pre-BAPI-572 version, the merge flow now runs under the SHARED heartbeat/
+ * deadman/timeout supervision path (via {@link superviseProcess}) so a live merge
+ * heartbeats (the janitor never re-queues a healthy multi-minute merge) and the
+ * whole flow honors `payload.timeout_seconds`. A timeout is reported as a
+ * RETRYABLE failure and a late merge resolution after timeout/abandonment is
+ * ignored. The local merge executor's outcome otherwise drives `/complete`
+ * (success) or `/fail`; stale/retry/invalid terminal outcomes reuse T3a handling.
+ */
+async function runMergeJob(job, httpClient, options, deps, ownership, observation, seams) {
+    // Resolve + enforce payload.timeout_seconds BEFORE starting any merge work.
+    const timeout = resolveJobTimeoutSeconds(job, options.defaultJobTimeoutSeconds);
+    if (!timeout.ok) {
+        await httpClient.fail(job, {
+            error_kind: "ContractError.Timeout",
+            error_message: timeout.error,
+            classification: "crashed",
+        });
+        return { status: "failed", reason: "timeout_contract" };
+    }
+    const timeoutSeconds = timeout.timeoutSeconds;
+    const runMerge = seams.runMerge ?? defaultRunMergeForClaimed;
+    const flow = createMergeFlowProcess((signal) => runMerge(job, deps, options, { signal }));
+    const procResult = await superviseProcess({
+        job,
+        httpClient,
+        options,
+        deps,
+        ownership,
+        observation,
+        proc: flow.proc,
+        timeoutSeconds,
+        collectTelemetry: async () => ({}),
+    });
+    // Ownership abandonment (stale-claim / dead-man) wins: never send a terminal
+    // mutation for a claim we no longer own, and never process a late outcome.
+    if (ownership.abandoned) {
+        return { status: "abandoned", reason: ownership.abandonReason };
+    }
+    // Overall merge flow timed out: fail the active claim as RETRYABLE and ignore
+    // any later merge promise resolution (the abort has already been signalled).
+    if (procResult.classification === "timeout") {
+        const terminal = await sendTerminalMutationWithRetry({
+            kind: "fail",
+            send: () => httpClient.fail(job, {
+                error_kind: MERGE_RETRYABLE,
+                error_message: `merge flow timed out after ${timeoutSeconds} seconds`,
+                classification: "timeout",
+                telemetry: observation.snapshot(),
+            }),
+            deps,
+            options,
+            ownership,
+            log: deps.log,
+        });
+        return terminalToRunResult(terminal, "failed");
+    }
+    // A thrown error inside the merge flow maps to a bounded MergeFailed.
+    const flowError = flow.getError();
+    if (flowError !== undefined) {
+        const terminal = await sendTerminalMutationWithRetry({
+            kind: "fail",
+            send: () => httpClient.fail(job, {
+                error_kind: MERGE_FAILED,
+                error_message: secretFreeErrorMessage(flowError),
+                classification: "crashed",
+                telemetry: observation.snapshot(),
+            }),
+            deps,
+            options,
+            ownership,
+            log: deps.log,
+        });
+        return terminalToRunResult(terminal, "failed");
+    }
+    const outcome = flow.getOutcome();
+    if (outcome === undefined) {
+        // Clean process result with no stored outcome — an internal invariant break;
+        // fail loud rather than silently reporting success.
+        const terminal = await sendTerminalMutationWithRetry({
+            kind: "fail",
+            send: () => httpClient.fail(job, {
+                error_kind: MERGE_FAILED,
+                error_message: "merge flow completed without an outcome",
+                classification: "crashed",
+                telemetry: observation.snapshot(),
+            }),
+            deps,
+            options,
+            ownership,
+            log: deps.log,
+        });
+        return terminalToRunResult(terminal, "failed");
+    }
+    if (outcome.ok) {
+        const completion = {
+            job_type: "merge",
+            exit_code: 0,
+            classification: "clean_exit",
+            result: outcome.result,
+            telemetry: observation.snapshot(),
+        };
+        const terminal = await sendTerminalMutationWithRetry({
+            kind: "complete",
+            send: () => httpClient.complete(job, completion),
+            deps,
+            options,
+            ownership,
+            log: deps.log,
+        });
+        return terminalToRunResult(terminal, "completed");
+    }
+    const terminal = await sendTerminalMutationWithRetry({
+        kind: "fail",
+        send: () => httpClient.fail(job, { ...outcome.failure, telemetry: observation.snapshot() }),
+        deps,
+        options,
+        ownership,
+        log: deps.log,
+    });
+    return terminalToRunResult(terminal, "failed");
+}
+async function runSmokeJob(job, httpClient, options, deps, ownership, observation) {
+    const timeout = resolveJobTimeoutSeconds(job, options.defaultJobTimeoutSeconds);
+    if (!timeout.ok) {
+        // Consistent with runSpawnJob: a timeout-contract failure fails the job
+        // rather than silently substituting a default.
+        await httpClient.fail(job, {
+            error_kind: "ContractError.Timeout",
+            error_message: timeout.error,
+            classification: "crashed",
+        });
+        return { status: "failed", reason: "timeout_contract" };
+    }
+    const timeoutSeconds = timeout.timeoutSeconds;
+    const payload = job.payload && typeof job.payload === "object" ? job.payload : {};
+    const durationMs = typeof payload.duration_ms === "number" && payload.duration_ms > 0
+        ? payload.duration_ms
+        : DEFAULT_SMOKE_DURATION_MS;
+    const message = typeof payload.message === "string" ? payload.message : "smoke ok";
+    const proc = createNoopProcess(deps, durationMs, message);
+    const procResult = await superviseProcess({
+        job,
+        httpClient,
+        options,
+        deps,
+        ownership,
+        observation,
+        proc,
+        timeoutSeconds,
+        collectTelemetry: async () => ({}),
+    });
+    if (ownership.abandoned) {
+        return { status: "abandoned", reason: ownership.abandonReason };
+    }
+    const evidence = {
+        message,
+        exit_code: procResult.exitCode,
+        classification: procResult.classification,
+    };
+    const result = buildSmokeResult(evidence, procResult.classification === "clean_exit" ? "pass" : "fail");
+    const completion = {
+        job_type: "smoke",
+        exit_code: procResult.exitCode ?? 0,
+        classification: toWireClassification(procResult.classification),
+        result,
+        telemetry: observation.snapshot(),
+    };
+    const terminal = await sendTerminalMutationWithRetry({
+        kind: "complete",
+        send: () => httpClient.complete(job, completion),
+        deps,
+        options,
+        ownership,
+        log: deps.log,
+    });
+    return terminalToRunResult(terminal, "completed");
+}
+async function prepareSpawn(job, httpClient, options, deps, seams) {
+    if (job.job_type === "resume") {
+        const prepareResume = seams.prepareResumeSpawn ?? prepareResumeSpawn;
+        try {
+            const prepared = await prepareResume(job, options, buildResumeSeams(deps, options));
+            return {
+                ok: true,
+                worktreePath: prepared.worktreePath,
+                branch: prepared.branch,
+                prompt: prepared.prompt,
+            };
+        }
+        catch (err) {
+            const failure = isExecutorNamedError(err)
+                ? toExecutorFailure(err)
+                : {
+                    error_kind: "ResumeError",
+                    error_message: secretFreeErrorMessage(err),
+                    classification: "crashed",
+                };
+            await httpClient.fail(job, failure);
+            return {
+                ok: false,
+                result: {
+                    status: "failed",
+                    reason: isExecutorNamedError(err) ? err.errorKind : "resume_prepare_failed",
+                },
+            };
+        }
+    }
+    // Resolve an explicit `payload.prompt` or the `/implement-ticket <KEY> --auto`
+    // synthesis (implement + recovery). `spec_review` matches neither — it is
+    // resolved AFTER worktree preparation from its structured `payload.prompt_spec`
+    // (rendering `{{GIT_LOG}}` needs the prepared worktree), so a non-ok result
+    // here is not yet a failure when a `prompt_spec` is present to render.
+    const explicit = resolveExecutorPrompt(job);
+    const payload = job.payload && typeof job.payload === "object"
+        ? job.payload
+        : {};
+    const hasPromptSpec = payload.prompt_spec !== undefined && payload.prompt_spec !== null;
+    // Fail fast — BEFORE any worktree work — when there is neither a usable
+    // explicit/synthesized prompt nor a structured `prompt_spec` to render, so a
+    // genuinely prompt-less job never creates a worktree it cannot use.
+    if (!explicit.ok && !hasPromptSpec) {
+        await httpClient.fail(job, {
+            error_kind: "ContractError.Prompt",
+            error_message: explicit.error,
+            classification: "crashed",
+        });
+        return { ok: false, result: { status: "failed", reason: "prompt_contract" } };
+    }
+    const ensureWorktree = seams.ensureWorktree ?? ensureExecutorWorktree;
+    // Recovery jobs (`remediate`/`ci_fix`/`rebase`) continue on the ticket's
+    // existing bound branch/PR (it carries the implement commit), so they reuse it
+    // from `origin/<branch>` with the F7 stale-branch guard OFF. `implement` and
+    // `spec_review` stay fresh-off-base with the guard ON. `resume` never reaches
+    // here — it has its own preservation protocol above.
+    const reuseExistingBranch = isRecoveryJobType(job.job_type);
+    const wt = await ensureWorktree(job, options, deps, { reuseExistingBranch });
+    if (!wt.ok) {
+        await httpClient.fail(job, {
+            error_kind: "WorktreeError",
+            error_message: wt.error,
+            classification: "crashed",
+        });
+        return { ok: false, result: { status: "failed", reason: "worktree_create_failed" } };
+    }
+    // Explicit/synthesized prompt wins verbatim, preserving existing behavior.
+    if (explicit.ok) {
+        return { ok: true, worktreePath: wt.worktreePath, branch: wt.branch, prompt: explicit.prompt };
+    }
+    // No explicit/synthesized prompt: render the structured `payload.prompt_spec`
+    // against the prepared worktree (the `spec_review` path). A malformed spec
+    // fails loud with `ContractError.Prompt` so we `/fail` rather than spawn a
+    // worker with an empty prompt. Error messages are secret-free by construction.
+    const renderPrompt = seams.renderPromptSpecPrompt ?? renderPromptSpecPrompt;
+    try {
+        const rendered = await renderPrompt(job, {
+            worktreePath: wt.worktreePath,
+            workBranch: wt.branch,
+            baseBranch: options.baseBranch,
+            runCommand: deps.runCommand,
+        });
+        return { ok: true, worktreePath: wt.worktreePath, branch: wt.branch, prompt: rendered };
+    }
+    catch (err) {
+        const failure = isExecutorNamedError(err)
+            ? toExecutorFailure(err)
+            : {
+                error_kind: "ContractError.Prompt",
+                error_message: secretFreeErrorMessage(err),
+                classification: "crashed",
+            };
+        await httpClient.fail(job, failure);
+        return { ok: false, result: { status: "failed", reason: "prompt_contract" } };
+    }
+}
+async function runSpawnJob(job, httpClient, options, deps, ownership, observation, seams) {
+    // --- Worktree + prompt (resume pre-spawn protocol or standard) -------
+    const prep = await prepareSpawn(job, httpClient, options, deps, seams);
+    if (!prep.ok)
+        return prep.result;
+    const { worktreePath, branch, prompt } = prep;
+    // --- Timeout contract ------------------------------------------------
+    const timeout = resolveJobTimeoutSeconds(job, options.defaultJobTimeoutSeconds);
+    if (!timeout.ok) {
+        await httpClient.fail(job, {
+            error_kind: "ContractError.Timeout",
+            error_message: timeout.error,
+            classification: "crashed",
+        });
+        return { status: "failed", reason: "timeout_contract" };
+    }
+    // --- Deny layer (fail-open) ------------------------------------------
+    const deny = await provisionExecutorDenyLayer(worktreePath, { baseBranch: options.baseBranch }, {
+        readFile: deps.readFile,
+        writeFile: deps.writeFile,
+        mkdir: deps.mkdir,
+        homedir: deps.homedir,
+    });
+    if (!deny.ok)
+        deps.errorLog(deny.warning);
+    // --- Worker log tee + watch registry + viewer tab (BAPI-535 §8) ------
+    const registryDeps = buildJobLogRegistryDeps(deps);
+    const markFinished = seams.markExecutorJobLogFinished ?? markExecutorJobLogFinished;
+    const createTee = seams.createWorkerLogTee ?? createWorkerLogTee;
+    let tee = null;
+    try {
+        tee = await createTee(worktreePath, {
+            mkdir: deps.mkdir,
+            writeFile: deps.writeFile,
+            appendFile: deps.appendFile,
+            platform: deps.platform,
+        });
+    }
+    catch {
+        tee = null;
+    }
+    if (tee) {
+        const registerLog = seams.registerExecutorJobLog ?? registerExecutorJobLog;
+        try {
+            await registerLog({
+                job_id: job.id,
+                repo_name: job.repo_name,
+                job_type: job.job_type,
+                ticket_key: job.ticket_key ?? undefined,
+                worktree_path: worktreePath,
+                log_path: tee.logPath,
+                started_at: nowIso(deps),
+            }, registryDeps);
+        }
+        catch {
+            /* registry is a visibility nicety — never fail the job */
+        }
+        if (executorViewerTabsEnabled(deps.platform, deps.env)) {
+            const openViewer = seams.openExecutorViewerTab ?? openExecutorViewerTab;
+            try {
+                const viewer = await openViewer({
+                    platform: deps.platform,
+                    env: deps.env,
+                    workerLogPath: tee.logPath,
+                    worktreePath,
+                    ticketKey: job.ticket_key ?? undefined,
+                    runCommand: deps.runCommand,
+                    cwd: deps.cwd,
+                });
+                if (viewer.status === "failed") {
+                    deps.errorLog(`executor viewer tab failed (non-fatal): ${viewer.reason}`);
+                }
+            }
+            catch (err) {
+                deps.errorLog(`executor viewer tab error (non-fatal): ${secretFreeErrorMessage(err)}`);
+            }
+        }
+    }
+    const finalizeRegistry = async () => {
+        if (!tee)
+            return;
+        try {
+            await markFinished(job.id, nowIso(deps), registryDeps);
+        }
+        catch {
+            /* non-fatal */
+        }
+    };
+    // --- Spawn -----------------------------------------------------------
+    const alias = resolveExecutorModelAlias(job.payload);
+    const argv = buildClaudeExecutorArgv(prompt, alias);
+    const env = buildExecutorWorkerEnv(deps.env);
+    let proc;
+    try {
+        proc = deps.spawnProcess(CLAUDE_EXECUTABLE, argv, { cwd: worktreePath, env });
+    }
+    catch (err) {
+        await closeWorkerLogTee(tee);
+        await finalizeRegistry();
+        await httpClient.fail(job, {
+            error_kind: "SpawnError",
+            error_message: `failed to spawn worker: ${boundedError(err)}`,
+            classification: "crashed",
+        });
+        return { status: "failed", reason: "spawn_failed" };
+    }
+    // Tee stdout/stderr to the worker log WITHOUT changing what the runner sees.
+    const supervisedProc = tee
+        ? {
+            ...proc,
+            stdout: proc.stdout ? teeAsyncIterable(proc.stdout, tee, "stdout") : null,
+            stderr: proc.stderr ? teeAsyncIterable(proc.stderr, tee, "stderr") : null,
+        }
+        : proc;
+    const collectTelemetry = () => collectGitTelemetry({ runCommand: deps.runCommand, now: deps.now }, worktreePath, options.baseBranch);
+    const procResult = await superviseProcess({
+        job,
+        httpClient,
+        options,
+        deps,
+        ownership,
+        observation,
+        proc: supervisedProc,
+        timeoutSeconds: timeout.timeoutSeconds,
+        collectTelemetry,
+    });
+    // Final telemetry snapshot from the worktree.
+    observation.setGitTelemetry(await collectTelemetry());
+    // Finalize the log tee WITHOUT signaling the worker (it has already exited).
+    await closeWorkerLogTee(tee);
+    if (ownership.abandoned) {
+        await finalizeRegistry();
+        return { status: "abandoned", reason: ownership.abandonReason };
+    }
+    const git = observation.git();
+    if (procResult.classification === "clean_exit") {
+        // Verdict jobs (`spec_review`) forward the fixed-path artifact verbatim; a
+        // missing/invalid artifact is a fail-loud `MissingVerdictArtifact`.
+        if (isVerdictJobType(job.job_type)) {
+            const readArtifact = seams.readVerdictArtifact ?? readVerdictArtifact;
+            let result;
+            try {
+                result = await readArtifact(worktreePath, { readFile: deps.readFile, platform: deps.platform });
+            }
+            catch (err) {
+                const failure = isExecutorNamedError(err)
+                    ? toExecutorFailure(err)
+                    : {
+                        error_kind: MissingVerdictArtifact,
+                        error_message: secretFreeErrorMessage(err),
+                        classification: "crashed",
+                    };
+                await finalizeRegistry();
+                const terminal = await sendTerminalMutationWithRetry({
+                    kind: "fail",
+                    send: () => httpClient.fail(job, { ...failure, ...commitResidue(git), telemetry: observation.snapshot() }),
+                    deps,
+                    options,
+                    ownership,
+                    log: deps.log,
+                });
+                return terminalToRunResult(terminal, "failed");
+            }
+            // BAPI-528 Wave 3 M2: verdict jobs (`spec_review`) also produce a
+            // human-readable critique at `<worktree>/.conductor/critique.md`. Read it
+            // AFTER the mandatory verdict (result.json) so a missing critique never
+            // masks a MissingVerdictArtifact — `readCompletionArtifacts` is fail-open
+            // and returns undefined when there is no critique (e.g. smoke), so
+            // verdict-only jobs still complete. Without this the critique was written
+            // by the worker but never posted, orphaning the W2-6 server-side persist.
+            const artifacts = await readCompletionArtifacts(worktreePath, deps);
+            const completion = {
+                job_type: job.job_type,
+                exit_code: procResult.exitCode ?? 0,
+                classification: "clean_exit",
+                result,
+                artifacts,
+                ...commitResidue(git),
+                telemetry: observation.snapshot(),
+            };
+            const terminal = await sendTerminalMutationWithRetry({
+                kind: "complete",
+                send: () => httpClient.complete(job, completion),
+                deps,
+                options,
+                ownership,
+                log: deps.log,
+            });
+            await finalizeRegistry();
+            return terminalToRunResult(terminal, "completed");
+        }
+        // Non-verdict spawn jobs (`implement`, `resume`, and the recovery jobs
+        // `remediate`/`ci_fix`/`rebase`) use the generic success-result construction;
+        // the verdict-artifact path above stays limited to verdict jobs like
+        // `spec_review`. Recovery jobs complete through this same generic envelope.
+        const artifacts = await readCompletionArtifacts(worktreePath, deps);
+        const result = buildGenericSuccessResult({
+            summary: `${job.job_type} ${job.ticket_key ?? ""} completed`.trim(),
+            branch,
+            headSha: git.last_commit_sha,
+            localCommitCount: git.local_commit_count,
+        });
+        // BAPI-551: a worker can exit `clean_exit` yet strand its implementation if
+        // its push never landed on origin and no PR was opened (e.g. it backgrounded
+        // a slow push and returned early). Convert that into a fail-loud executor
+        // failure rather than silently reporting success.
+        const finalization = await validateWorkerFinalization({
+            job,
+            branch,
+            worktreePath,
+            result,
+            runCommand: deps.runCommand,
+            headSha: git.last_commit_sha,
+        });
+        if (!finalization.ok) {
+            await finalizeRegistry();
+            const terminal = await sendTerminalMutationWithRetry({
+                kind: "fail",
+                send: () => httpClient.fail(job, {
+                    ...finalization.failure,
+                    ...commitResidue(git),
+                    telemetry: observation.snapshot(),
+                }),
+                deps,
+                options,
+                ownership,
+                log: deps.log,
+            });
+            return terminalToRunResult(terminal, "failed");
+        }
+        const completion = {
+            job_type: job.job_type,
+            exit_code: procResult.exitCode ?? 0,
+            classification: "clean_exit",
+            result,
+            artifacts,
+            ...commitResidue(git),
+            telemetry: observation.snapshot(),
+        };
+        const terminal = await sendTerminalMutationWithRetry({
+            kind: "complete",
+            send: () => httpClient.complete(job, completion),
+            deps,
+            options,
+            ownership,
+            log: deps.log,
+        });
+        await finalizeRegistry();
+        return terminalToRunResult(terminal, "completed");
+    }
+    // crashed / timeout / killed → fail
+    await finalizeRegistry();
+    const terminal = await sendTerminalMutationWithRetry({
+        kind: "fail",
+        send: () => httpClient.fail(job, {
+            error_kind: classificationToErrorKind(procResult.classification),
+            error_message: `worker exited (${procResult.classification}, exit_code=${procResult.exitCode})`,
+            classification: toWireClassification(procResult.classification),
+            ...commitResidue(git),
+            telemetry: observation.snapshot(),
+        }),
+        deps,
+        options,
+        ownership,
+        log: deps.log,
+    });
+    return terminalToRunResult(terminal, "failed");
+}