@bridge_gpt/mcp-server 0.2.62 → 0.2.65

package/build/executor/job-runner.js

@@ -17,7 +17,7 @@
 import { rm, readdir, lstat, unlink } from "node:fs/promises";
 import os from "node:os";
 import { runHeartbeatLoop } from "./heartbeat.js";
-import { isExecutorNamedError, toExecutorFailure, secretFreeErrorMessage, MissingVerdictArtifact, PreSpawnVerification, RequiredMcpRegistration, McpSurfaceMismatch, WorkerStartupFatal, WORKER_STARTUP_FATAL_MESSAGE, formatMcpSurfaceMismatch, ClaudeNotAuthenticated, CLAUDE_NOT_AUTHENTICATED_MESSAGE, ExecutorAdapterUnavailable, ExecutorNamedError, WorktreeBusy, StaleArtifactCleanupFailed, WORKTREE_BUSY_MESSAGE, WorkerEnvFilePresent, WORKER_ENV_FILE_PRESENT_MESSAGE, } from "./job-errors.js";
+import { isExecutorNamedError, toExecutorFailure, RebaseNotVerified, secretFreeErrorMessage, MissingVerdictArtifact, PreSpawnVerification, RequiredMcpRegistration, McpSurfaceMismatch, WorkerStartupFatal, WORKER_STARTUP_FATAL_MESSAGE, formatMcpSurfaceMismatch, ClaudeNotAuthenticated, CLAUDE_NOT_AUTHENTICATED_MESSAGE, ExecutorAdapterUnavailable, ExecutorNamedError, WorktreeBusy, StaleArtifactCleanupFailed, CiFixContext, WORKTREE_BUSY_MESSAGE, WorkerEnvFilePresent, WORKER_ENV_FILE_PRESENT_MESSAGE, } from "./job-errors.js";
 import { buildConductorMergeAccessForExecutorJob, buildDefaultMergeLocalDeps, runExecutorMergeJob, MERGE_RETRYABLE, MERGE_FAILED, } from "./merge-job.js";
 import { createProductionCiRerunDeps, runCiRerunJob, } from "./ci-rerun-job.js";
 import { createObservationState } from "./observation.js";
@@ -25,30 +25,37 @@ import { getWorktreeMcpRegistrationTargets, normalizeWorktreePathForRegistration
 import { resolveExecutorAgentAdapter } from "../agent-launchers/executor-adapter-registry.js";
 import { redactAdapterDiagnostic } from "../agent-launchers/executor-adapter.js";
 import { resolveExecutorAgentId } from "./agent-identity.js";
-import { createProcessTerminationController, runProcessWithTimeout } from "./process.js";
-import { prepareResumeSpawn } from "./resume-pre-spawn.js";
-import { renderPromptSpecPrompt } from "./prompt-spec.js";
+import { closeStdinBounded, createProcessTerminationController, runProcessWithTimeout, writeStdinBounded, } from "./process.js";
+import { buildNotLaunchedEnvelope, claimRequiresCompletionEvidence, SUPPORTED_COMPLETION_RUNTIME, COMPLETION_CONTRACT_MARKER_VALUES, isCoveredJobType, MAX_EVENT_BYTES, runtimeMatchesSupported, successRefusalReason, verificationVerdictFromFacts, } from "./completion-contract.js";
+import { COMPLETION_CAUSE_ERROR_KINDS, EOF_DRAIN_BOUND_MS, finalizationFacts, finalizationObligations, planCompletionAllowance, readCompletionBinding, readDeclaredChecks, readOptionalWatchers, readRequiredVerification, } from "./completion-supervision.js";
+import { compareFinalArtifact, createRequiredVerificationRunner, createSupervisedCommandLauncher, observeFinalArtifact, OWNERSHIP_POLL_MS, preCheckArtifactState, toCompletionCheckFact, } from "./required-verification.js";
+import { createClosureSupervisor, createRequiredWorkLedger } from "./required-work-ledger.js";
+import { buildCleanupVerdict, CLEANUP_RESIDUALS_NOT_COVERED, createDefaultOwnershipRecordFs, createDescendantTracker, createMacProcessInspector, createOwnershipToken, hostIdentityDigest, ownershipTokenDigest, removeOwnershipRecord, runOwnedProcessSweep, withOwnershipTag, writeOwnershipRecord, } from "./process-containment.js";
+import { resolveCompletionEvidenceCapability } from "../agent-launchers/executor-adapter.js";
+import { prepareResumeSpawn, prepareRetainedContinuationWorktree, readContinuationBinding, } from "./resume-pre-spawn.js";
+import { ciFixContextError, readCiFixDispatchContext, renderPromptSpecPrompt, } from "./prompt-spec.js";
 import { defaultResolveBinPath } from "../start-tickets-conductor.js";
 /** The packaged bin basename of the deterministic worker guard (BAPI-1020). */
 const WORKER_GUARD_BIN_FILENAME = "worker-guard-hook-bin.js";
-import { buildGenericSuccessResult, buildSmokeResult, commitResidue, readCompletionArtifacts, resolveJobTimeoutSeconds, } from "./results.js";
+import { buildGenericSuccessResult, CI_FIX_CLAIMS_STATUS_KEY, readCiFixResultArtifact, buildSmokeResult, commitResidue, readCompletionArtifacts, resolveJobTimeoutSeconds, } from "./results.js";
 import { sendTerminalMutationWithRetry } from "./terminal-mutation.js";
 import { removeStaleVerdictArtifacts } from "./stale-artifacts.js";
 import { stripWorkerEnvFiles } from "./env-file-guard.js";
 import { isVerdictJobType, readVerdictArtifact } from "./verdict-artifact.js";
 import { createWorkerLogTee, closeWorkerLogTee, distinctWorkerLogSessionIds, formatWorkerLogSessionInvariantWarning, teeAsyncIterable, } from "./worker-log.js";
 import { acquireExecutorWorktreeLock, } from "./worktree-lock.js";
-import { activateJobLog, deactivateJobLog, registerExecutorJobLog, markExecutorJobLogFinished, } from "./job-log-registry.js";
+import { resolveExecutorStateDir, activateJobLog, deactivateJobLog, registerExecutorJobLog, markExecutorJobLogFinished, } from "./job-log-registry.js";
 import { executorViewerTabsEnabled, openExecutorViewerTab } from "./viewer-tabs.js";
 import { isImplementationStyleJobType, isRecoveryJobType, isSpawnJobType } from "./job-types.js";
 import { cleanupInterruptedWorktree } from "./interrupted-worktree.js";
 import { lazyProviderCheckPoller, runReconcileOverlapJob, } from "./reconcile-overlap-job.js";
 import { resolveExecutorJobBaseBranch } from "./base-branch.js";
 import { resolveExecutorJobIndexScope } from "./index-scope.js";
-import { validateWorkerFinalization } from "./worker-finalization.js";
-import { ensureExecutorWorktree } from "./worktree.js";
+import { readFocusedPullRequest, validateWorkerFinalization } from "./worker-finalization.js";
+import { FOCUSED_REBASE_JOB_TYPE, focusedRebaseContextError, hasFocusedRebaseContext, validateFocusedRebaseContext, waitForFocusedRebase, } from "./rebase-finalization.js";
+import { ensureExecutorWorktree, finalizeRetainedExecutorWorktree, } from "./worktree.js";
 import { buildPrBaseContractLaunchInstruction } from "../pr-base-contract.js";
-import { resolveExecutorPrompt, resolveWorkerPermissionPosture, } from "./worker-command.js";
+import { CI_FIX_JOB_TYPE, resolveExecutorPrompt, resolveWorkerPermissionPosture, } from "./worker-command.js";
 import { collectGitTelemetry, collectRemoteTrackingSha, createMcpSurfaceObserver, evaluatePreSpawnGitVerification, formatWorkerRateLimitAdvisory, normalizeMcpServerNames, } from "./observation.js";
 import { TERMINAL_CAPACITY_PROTOCOL_VERSIONS, TERMINAL_CAPACITY_RUNTIME_CONTRACTS, TERMINAL_CAPACITY_RUNTIMES, } from "./types.js";
 import { isRecognizedServerName, MCP_SERVER_NAME } from "../mcp-identity.js";
@@ -679,6 +686,17 @@ export async function runClaimedJob(job, httpClient, options, deps, _report, sea
  */
 control) {
     const { ownership, observation } = createJobRunState(options, deps);
+    // BAPI-1301: a covered claim must carry an envelope on EVERY terminal report,
+    // including the many refusals that happen before a worker exists (worktree
+    // preparation, pre-spawn verification, MCP registration, …). Without one the
+    // server refuses the report, the row dead-letters and the child parks as
+    // "cleanup unconfirmed" — a transient pre-spawn problem would need a human.
+    // Wrapping the client ONCE makes that structural rather than a per-site duty:
+    // any /fail that has no envelope gets the truthful "not launched" envelope and
+    // keeps its own error kind; reports that already carry one are untouched.
+    if (claimIsCovered(job)) {
+        httpClient = withNotLaunchedEnvelopeFallback(httpClient, job);
+    }
     // `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).
@@ -1266,6 +1284,44 @@ function resolveStaleBranchClassification(payload) {
         return "unknown";
     return raw.trim() === PR_NOT_ATTACHED_REASON_CODE ? "succeeded_pr_not_attached" : "unknown";
 }
+/** The `/fail` payload for a failed worktree preparation. */
+function jobWorktreeFailure(wt) {
+    return (wt.failure ?? {
+        error_kind: "WorktreeError",
+        error_message: wt.error,
+        classification: "crashed",
+    });
+}
+/**
+ * Prepare a job's worktree. A job the server dispatched as a parked-child
+ * CONTINUATION (BAPI-1300; `payload.continuation.retained_worktree === true`)
+ * follows the retained-work protocol: it reuses the existing local worktree,
+ * proves its branch and head lineage, and WIP-checkpoints it — it is never
+ * freshened onto origin (which hard-resets and would drop unpushed work) and
+ * never recreated. Every other job keeps the ordinary path unchanged.
+ */
+async function ensureJobWorktree(job, options, deps, seams, policy) {
+    const continuation = readContinuationBinding(job);
+    if (continuation === null) {
+        const ensureWorktree = seams.ensureWorktree ?? ensureExecutorWorktree;
+        return ensureWorktree(job, options, deps, policy);
+    }
+    const prepareRetained = seams.prepareRetainedContinuationWorktree ?? prepareRetainedContinuationWorktree;
+    try {
+        const retained = await prepareRetained(job, continuation, buildResumeSeams(deps, options));
+        return await finalizeRetainedExecutorWorktree(retained.worktreePath, retained.branch, deps);
+    }
+    catch (err) {
+        const failure = isExecutorNamedError(err)
+            ? toExecutorFailure(err)
+            : {
+                error_kind: "WorktreeError",
+                error_message: secretFreeErrorMessage(err),
+                classification: "crashed",
+            };
+        return { ok: false, error: failure.error_message, failure };
+    }
+}
 async function prepareSpawn(job, httpClient, options, deps, seams) {
     if (job.job_type === "resume") {
         const prepareResume = seams.prepareResumeSpawn ?? prepareResumeSpawn;
@@ -1296,8 +1352,75 @@ async function prepareSpawn(job, httpClient, options, deps, seams) {
             };
         }
     }
+    // BAPI-1296 — the FOCUSED ci_fix route, decided before any worktree effect.
+    // The payload's focused contract (no explicit prompt, a valid ci_fix prompt
+    // spec, a ticket spec, and a head-bound dispatched check set) is validated
+    // here; a failure is a named `ContractError.CiFixContext` refusal and the job
+    // never reaches `ensureWorktree`, let alone the full `/implement-ticket`
+    // recipe it used to re-enter. The recovery classification is unchanged, so the
+    // job still reuses the ticket's bound branch under the same lock and
+    // finalization checks.
+    if (job.job_type === CI_FIX_JOB_TYPE) {
+        const readCiFix = seams.readCiFixDispatchContext ?? readCiFixDispatchContext;
+        let ciFix;
+        try {
+            ciFix = readCiFix(job);
+        }
+        catch (err) {
+            const failure = isExecutorNamedError(err)
+                ? toExecutorFailure(err)
+                : {
+                    error_kind: CiFixContext,
+                    error_message: secretFreeErrorMessage(err),
+                    classification: "crashed",
+                };
+            deps.errorLog(`[executor] job ${job.id}: ${failure.error_message}`);
+            await httpClient.fail(job, failure);
+            return { ok: false, result: { status: "failed", reason: "ci_fix_context" } };
+        }
+        const wt = await ensureJobWorktree(job, options, deps, seams, {
+            reuseExistingBranch: isRecoveryJobType(job.job_type),
+            staleBranchClassification: resolveStaleBranchClassification(job.payload),
+        });
+        if (!wt.ok) {
+            await httpClient.fail(job, jobWorktreeFailure(wt));
+            return { ok: false, result: { status: "failed", reason: "worktree_create_failed" } };
+        }
+        return {
+            ok: true,
+            worktreePath: wt.worktreePath,
+            branch: wt.branch,
+            prompt: "",
+            expectedHeadSha: wt.expectedHeadSha,
+            ciFix,
+        };
+    }
+    // BAPI-1311 — the FOCUSED merge-stage rebase, decided before any worktree
+    // effect. A `rebase` job that carries `payload.focused_rebase` must validate
+    // against its own claim; a failure is a named `ContractError.FocusedRebaseContext`
+    // refusal and the job never reaches `ensureWorktree`, never spawns, and is never
+    // reinterpreted as a legacy rebase. A `rebase` WITHOUT the context is an older
+    // queued job: it keeps its original prompt, deadline, finalization, and server
+    // completion contract, and says so once on stderr.
+    let focusedRebase;
+    if (job.job_type === FOCUSED_REBASE_JOB_TYPE) {
+        if (hasFocusedRebaseContext(job)) {
+            const validation = validateFocusedRebaseContext(job);
+            if (!validation.ok) {
+                const failure = toExecutorFailure(focusedRebaseContextError(job, validation.reason));
+                deps.errorLog(`[executor] job ${job.id}: ${failure.error_message}`);
+                await httpClient.fail(job, failure);
+                return { ok: false, result: { status: "failed", reason: "focused_rebase_context" } };
+            }
+            focusedRebase = validation.context;
+        }
+        else {
+            deps.errorLog(`[executor] job ${job.id}: Legacy rebase handling — no focused_rebase context; running its ` +
+                "original prompt under the existing completion contract (no executor-supervised wait)");
+        }
+    }
     // Resolve an explicit `payload.prompt` or the `/implement-ticket <KEY> --auto`
-    // synthesis (implement + recovery).
+    // synthesis (implement + the remediate/rebase recovery jobs).
     //
     // BAPI-725: `spec_review` now takes the explicit-prompt path like any other job
     // — the reconciler builds its prompt server-side and ships it in
@@ -1325,14 +1448,13 @@ async function prepareSpawn(job, httpClient, options, deps, seams) {
         });
         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
+    // Recovery jobs (`remediate`/`rebase`; `ci_fix` above) 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, {
+    const wt = await ensureJobWorktree(job, options, deps, seams, {
         reuseExistingBranch,
         // BAPI-862: hand the guard the reconciler's own reading of why this branch
         // may already carry commits. Read from the SERVER-minted payload field and
@@ -1341,14 +1463,12 @@ async function prepareSpawn(job, httpClient, options, deps, seams) {
         staleBranchClassification: resolveStaleBranchClassification(job.payload),
     });
     if (!wt.ok) {
-        await httpClient.fail(job, {
-            error_kind: "WorktreeError",
-            error_message: wt.error,
-            classification: "crashed",
-        });
+        await httpClient.fail(job, jobWorktreeFailure(wt));
         return { ok: false, result: { status: "failed", reason: "worktree_create_failed" } };
     }
     // Explicit/synthesized prompt wins verbatim, preserving existing behavior.
+    // BAPI-1311: for a focused rebase that explicit prompt IS the validated
+    // server-rendered prompt (`validateFocusedRebaseContext` required it).
     if (explicit.ok) {
         return {
             ok: true,
@@ -1356,6 +1476,7 @@ async function prepareSpawn(job, httpClient, options, deps, seams) {
             branch: wt.branch,
             prompt: explicit.prompt,
             expectedHeadSha: wt.expectedHeadSha,
+            ...(focusedRebase ? { focusedRebase } : {}),
         };
     }
     // No explicit/synthesized prompt: render the structured `payload.prompt_spec`
@@ -1391,6 +1512,201 @@ async function prepareSpawn(job, httpClient, options, deps, seams) {
         return { ok: false, result: { status: "failed", reason: "prompt_contract" } };
     }
 }
+/**
+ * BAPI-1296 — verify a prepared `ci_fix` checkout against its dispatched CI
+ * context and render the focused prompt, UNDER THE WORKTREE LOCK.
+ *
+ * The dispatched checks describe ONE observed head of ONE branch. Rendering them
+ * into a worker prompt for any other checkout would send the worker to fix
+ * failures that may not exist there, so the comparison runs after the lock is
+ * held (no contender can move the worktree underneath it) and before artifact
+ * cleanup, provisioning, and the spawn. The HEAD is read fresh from the
+ * worktree; nothing is inferred from a remote URL or from worker output. Any
+ * mismatch is a named `ContractError.CiFixContext` refusal with a fixed reason.
+ *
+ * Rendering happens only after the checks pass, through the single-pass
+ * `renderPromptSpecPrompt`, so untrusted check or ticket text is never
+ * re-expanded and never reaches a worker for an unverified checkout.
+ */
+async function renderVerifiedCiFixPrompt(params) {
+    const { job, ciFix, worktreePath, branch, baseBranch, deps, seams } = params;
+    if (branch.trim() !== ciFix.expectedBranch) {
+        return { ok: false, error: ciFixContextError(job, "branch_mismatch") };
+    }
+    let head;
+    try {
+        const revParse = await deps.runCommand("git", ["-C", worktreePath, "rev-parse", "HEAD"]);
+        head = revParse.exitCode === 0 ? revParse.stdout.trim().toLowerCase() : "";
+    }
+    catch {
+        head = "";
+    }
+    if (!head) {
+        return { ok: false, error: ciFixContextError(job, "head_unreadable") };
+    }
+    if (head !== ciFix.headSha) {
+        return { ok: false, error: ciFixContextError(job, "stale_head") };
+    }
+    const renderPrompt = seams.renderPromptSpecPrompt ?? renderPromptSpecPrompt;
+    try {
+        const prompt = await renderPrompt(job, {
+            worktreePath,
+            workBranch: branch,
+            baseBranch,
+            runCommand: deps.runCommand,
+        });
+        return { ok: true, prompt };
+    }
+    catch (err) {
+        return {
+            ok: false,
+            error: isExecutorNamedError(err) ? err : ciFixContextError(job, "prompt_spec_invalid"),
+        };
+    }
+}
+/** BAPI-1311: cap on any one focused finalization read, before the deadline clamp. */
+const FOCUSED_FINALIZATION_READ_MAX_MS = 120_000;
+/**
+ * BAPI-1311 — run the focused rebase's post-push wait and, unless it is `ready`,
+ * report the job's ONE terminal outcome.
+ *
+ * Returns `null` when the wait is `ready`: the caller then submits the ordinary
+ * `/complete` exactly once, and the server's completion verifier re-reads the
+ * provider as the final authority. Every other ending is reported here, once:
+ *
+ * - a PROVEN failure (red required check, closed or conflicting pull request, a
+ *   moved number/head/head branch/base) → `ContractError.RebaseNotVerified`, the
+ *   kind the server records when its own verifier refuses a rebase;
+ * - an UNVERIFIED stop (evidence still unavailable or pending at the deadline, or
+ *   checks unobservable from this executor) → the ordinary `Timeout`
+ *   classification, whose message says the repair is unverified — never that CI
+ *   failed;
+ * - a lost claim returns `abandoned` with NO terminal mutation; a server stop and
+ *   a supervised timeout or crash use the existing driver-phase vocabulary.
+ *
+ * The pushed commit is never reset or discarded on any path: it is on origin, and
+ * this function issues no git write at all.
+ */
+async function superviseFocusedRebaseWait(params) {
+    const { job, httpClient, options, deps, ownership, observation, seams, control } = params;
+    const label = job.ticket_key ? `${job.ticket_key} (job ${job.id})` : `job ${job.id}`;
+    const fail = async (failure) => {
+        await params.finalizeRegistry();
+        const terminal = await sendTerminalMutationWithAuthReport({
+            kind: "fail",
+            send: () => httpClient.fail(job, { ...failure, ...params.commitResidue, telemetry: observation.snapshot() }),
+            deps,
+            options,
+            ownership,
+            log: deps.log,
+        }, job, control);
+        return terminalToRunResult(terminal, "failed");
+    };
+    const pushed = params.pushedHeadSha;
+    if (!pushed) {
+        deps.errorLog(`[executor] Stopped: evidence unavailable — ${label} has no verified pushed head to wait on; ` +
+            "pushed work (if any) preserved");
+        return await fail({
+            error_kind: "Timeout",
+            error_message: `${label}: focused rebase evidence unavailable (reason=pushed_head_unverified); the repair is unverified, not failed CI`,
+            classification: "timeout",
+        });
+    }
+    const wait = seams.waitForFocusedRebase ?? waitForFocusedRebase;
+    const pollChecks = seams.pollProviderChecks ??
+        lazyProviderCheckPoller({
+            env: deps.env,
+            cwd: deps.cwd,
+            homedir: deps.homedir,
+            platform: deps.platform,
+            readFile: deps.readFile,
+            stat: deps.stat,
+        });
+    const phase = await superviseDriverPhase({
+        job,
+        httpClient,
+        options: params.jobOptions,
+        deps,
+        ownership,
+        observation,
+        control,
+        timeoutSeconds: Math.max(1, Math.ceil(params.remainingMs() / 1000)),
+        collectTelemetry: params.collectTelemetry,
+        run: (signal) => wait({
+            jobId: job.id,
+            context: params.context,
+            pushedHeadSha: pushed,
+            expectedBaseBranch: params.expectedBaseBranch,
+            readPullRequest: (timeoutMs) => readFocusedPullRequest(deps.runCommand, params.worktreePath, params.context.prNumber, { timeoutMs }),
+            pollChecks,
+            now: deps.now,
+            sleep: deps.sleep,
+            signal,
+            deadlineMs: params.jobDeadlineMs,
+            errorLog: deps.errorLog,
+        }),
+    });
+    if (phase.kind === "abandoned") {
+        // The claim is gone: another owner may already hold this job, so no terminal
+        // mutation is sent. The pushed commit stays on origin.
+        await params.finalizeRegistry();
+        return { status: "abandoned", reason: ownership.abandonReason };
+    }
+    if (phase.kind === "server_stop") {
+        await params.finalizeRegistry();
+        await httpClient.fail(job, {
+            error_kind: "ServerStopRequested",
+            error_message: "the server requested this run stop; the focused rebase wait was stopped",
+            classification: "killed",
+            telemetry: observation.snapshot(),
+        });
+        ownership.abandoned = true;
+        ownership.abandonReason = "server_stop";
+        return { status: "abandoned", reason: "server_stop" };
+    }
+    if (phase.kind === "timeout") {
+        return await fail({
+            error_kind: "Timeout",
+            error_message: `${label}: focused rebase wait exceeded the job deadline; pushed work preserved; the repair is unverified`,
+            classification: "timeout",
+        });
+    }
+    if (phase.kind === "error") {
+        const message = secretFreeErrorMessage(phase.error);
+        deps.errorLog(`[executor] Stopped: wait_error — ${label}: focused rebase wait failed unexpectedly; pushed work preserved`);
+        return await fail({
+            error_kind: "WorkerCrashed",
+            error_message: `${label}: focused rebase wait failed: ${message}`,
+            classification: "crashed",
+        });
+    }
+    const outcome = phase.value;
+    if (outcome.kind === "ready")
+        return null;
+    if (outcome.kind === "cancelled") {
+        // Cancellation reaches here only when the abort fired without the supervisor
+        // classifying it (a race at the very end of the wait). Nothing was proven.
+        return await fail({
+            error_kind: "Timeout",
+            error_message: `${label}: focused rebase wait was cancelled before evidence was current; pushed work preserved; the repair is unverified`,
+            classification: "timeout",
+        });
+    }
+    if (outcome.proven) {
+        return await fail({
+            error_kind: RebaseNotVerified,
+            error_message: `${label}: focused rebase pushed its repair but cannot succeed (reason=${outcome.reason}); ` +
+                "pushed work preserved on origin; no further repair was launched by this job",
+            classification: "crashed",
+        });
+    }
+    return await fail({
+        error_kind: "Timeout",
+        error_message: `${label}: focused rebase evidence was not current by the job deadline (reason=${outcome.reason}); ` +
+            "pushed work preserved; the repair is unverified, not failed CI",
+        classification: "timeout",
+    });
+}
 /**
  * Final pre-spawn preparation order (BAPI-724, BAPI-727): worktree + prompt
  * preparation (which itself performs reset-based untracked cleanup and command
@@ -1548,6 +1864,29 @@ driver) {
     // which is exactly the path that has no return value to inspect.
     const spawnLifecycle = {};
     try {
+        // --- Focused ci_fix checkout verification (BAPI-1296) ---------------
+        // Inside the lock, ahead of artifact cleanup and every worker-owned write:
+        // a refused ci_fix leaves the worktree exactly as preparation left it. The
+        // verified, rendered prompt replaces preparation's empty placeholder.
+        let readyPrep = prep;
+        if (prep.ciFix) {
+            const rendered = await renderVerifiedCiFixPrompt({
+                job,
+                ciFix: prep.ciFix,
+                worktreePath,
+                branch,
+                baseBranch: effectiveBaseBranch,
+                deps,
+                seams,
+            });
+            if (!rendered.ok) {
+                const failure = toExecutorFailure(rendered.error);
+                deps.errorLog(`[executor] job ${job.id}: ${failure.error_message}`);
+                await httpClient.fail(job, failure);
+                return { status: "failed", reason: "ci_fix_context" };
+            }
+            readyPrep = { ...prep, prompt: rendered.prompt };
+        }
         // --- Stale verdict artifacts (BAPI-814/D1) --------------------------
         // Inside the lock and BEFORE the worker spawns, on the SHARED attempt path,
         // so every job type routed through `runSpawnJob` is covered — `implement`,
@@ -1591,7 +1930,7 @@ driver) {
             seams,
             worktreePath,
             branch,
-            prep,
+            prep: readyPrep,
             effectiveBaseBranch,
             indexScope,
             permissionPosture,
@@ -1638,7 +1977,16 @@ async function runPreparedSpawn(params) {
     // are told to open the PR against the injected run base. Verdict-only
     // `spec_review` produces no PR, so it is excluded from the instruction while
     // still using the pinned base for its fresh worktree.
-    let prompt = isImplementationStyleJobType(job.job_type)
+    //
+    // BAPI-1296: a focused `ci_fix` prompt is used VERBATIM. It repairs a branch
+    // whose PR already exists and must not be told how to open one; the prompt
+    // itself pins it to the existing work branch.
+    //
+    // BAPI-1311: a focused rebase prompt is also used VERBATIM, for the same reason:
+    // it repairs an existing branch whose pull request already exists, and the PR
+    // base contract's "when you open the pull request" instruction would re-add the
+    // new-PR step the focused prompt deliberately excludes.
+    let prompt = isImplementationStyleJobType(job.job_type) && !prep.ciFix && !prep.focusedRebase
         ? `${prep.prompt} ${buildPrBaseContractLaunchInstruction()}`
         : prep.prompt;
     // --- Timeout contract ------------------------------------------------
@@ -1651,6 +1999,22 @@ async function runPreparedSpawn(params) {
         });
         return { status: "failed", reason: "timeout_contract" };
     }
+    // --- Covered completion contract (BAPI-1301) --------------------------
+    // Decided from the CLAIM (the server stamped the requirement), never from the
+    // payload or the worker. A requirement this runner cannot honor — a job type
+    // outside the covered set, or a driver-owned job — is refused explicitly with
+    // an envelope, rather than run under the legacy contract that the server
+    // would then refuse to accept.
+    const covered = claimIsCovered(job);
+    if (covered && (!isCoveredJobType(job.job_type) || driver)) {
+        return await refuseCoveredClaimBeforeLaunch({
+            job, httpClient, options, deps, ownership, observation, control,
+            runtime: unrecognizedRuntime(adapter),
+            dispatchHeadSha: prep.expectedHeadSha ?? null,
+            reason: "uncoverable_job",
+            message: "this executor cannot run this job type under the completion-evidence contract",
+        });
+    }
     // --- Spawn-job driver: the pre-worker phase (BAPI-1152) --------------
     // Runs INSIDE the lock and before every worker-owned side effect. A driver may
     // finish the whole job here (a clean, green reconciliation pushes with no
@@ -1957,6 +2321,9 @@ async function runPreparedSpawn(params) {
         const alias = invocation.value.resolveModelAlias(job.payload);
         spawnShape = invocation.value.buildSpawnShape({
             prompt,
+            // BAPI-1301: a covered attempt sends the prompt on a held stdin instead
+            // of argv; every other job keeps the byte-identical legacy argv.
+            ...(covered ? { promptTransport: "stdin-stream-json" } : {}),
             modelAlias: alias,
             posture: permissionPosture,
             mcpConfigPath: mcpContract.configPath,
@@ -2023,7 +2390,10 @@ async function runPreparedSpawn(params) {
     // `.env` and truncated it — so "could not confirm the worktree is clean" must
     // refuse, never proceed and hope.
     const stripEnvFiles = seams.stripWorkerEnvFiles ?? stripWorkerEnvFiles;
-    const stripped = await stripEnvFiles(worktreePath, {
+    // BAPI-1302: a named function so the covered lane can re-run the SAME guard
+    // before its independent checks — a check must never load an environment file
+    // the worker left behind any more than the worker could load the operator's.
+    const stripWorktreeEnvFiles = () => stripEnvFiles(worktreePath, {
         readdir: (dirPath) => readdir(dirPath),
         // `lstat`/`unlink` only — the guard must never resolve a symlink, because an
         // entry pointing at the main checkout would resolve to the operator's real
@@ -2076,6 +2446,7 @@ async function runPreparedSpawn(params) {
         },
         platform: deps.platform,
     });
+    const stripped = await stripWorktreeEnvFiles();
     if (!stripped.ok) {
         await closeWorkerLog();
         await finalizeRegistry();
@@ -2090,12 +2461,84 @@ async function runPreparedSpawn(params) {
         });
         return { status: "failed", reason: "worker_env_file_present" };
     }
+    // --- Covered attempt: runtime recheck, reservation, phase host (BAPI-1301)
+    // Immediately before spawn, re-probe the EXACT runtime this claim requires.
+    // The claim was admitted on the preflight's qualification, but the installed
+    // CLI can change between the two; a mismatch refuses here, before any worker
+    // exists. Then reserve cleanup/verification/finalization/report time out of
+    // the REMAINING allowance, refusing an impossible reservation instead of
+    // skipping a phase or extending the budget.
+    // The ONE worker spawn boundary (BAPI-790/828). Both the legacy spawn below and
+    // the covered attempt launch through it, so there is still exactly one place a
+    // worker can be started, always from the verified spawn shape. Only a covered
+    // attempt asks for a held stdin; the legacy options stay byte-identical.
+    const spawnWorker = (spawnOptions) => deps.spawnProcess(spawnShape.executable, spawnShape.argv, {
+        cwd: worktreePath,
+        env: spawnOptions.env,
+        ...(spawnOptions.stdin ? { stdin: spawnOptions.stdin } : {}),
+    });
+    if (covered) {
+        const capability = resolveCompletionEvidenceCapability(adapter);
+        const dispatchHeadSha = verification.observedSha ?? prep.expectedHeadSha ?? null;
+        const probed = capability.supported === true
+            ? await capability.value.probeRuntime({
+                runCommand: deps.runCommand,
+                platform: deps.platform,
+                ...(deps.arch !== undefined ? { arch: deps.arch } : {}),
+            })
+            : null;
+        const runtime = probed ?? unrecognizedRuntime(adapter);
+        const refuse = async (reason, message) => {
+            await closeWorkerLog();
+            await finalizeRegistry();
+            return await refuseCoveredClaimBeforeLaunch({
+                job, httpClient, options, deps, ownership, observation, control,
+                runtime, dispatchHeadSha, reason, message,
+            });
+        };
+        if (capability.supported !== true || !runtimeMatchesSupported(runtime)) {
+            return await refuse("unsupported_runtime", "the installed agent runtime is not the qualified completion-evidence runtime; refusing to launch");
+        }
+        if (!spawnShape.stdinMessages?.initial) {
+            return await refuse("unsupported_runtime", "the executor adapter produced no held-stdin prompt message for a covered job");
+        }
+        // BAPI-1302 (D4c) — the server-stamped declaration is validated WHOLE,
+        // before any allowance is reserved or a worker exists. A truncated,
+        // malformed, unsupported or server-refused declaration never launches work
+        // against a partial set of checks.
+        const verificationRead = readRequiredVerification(job.payload);
+        if (verificationRead.kind === "refused") {
+            deps.errorLog(`[executor] job ${job.id}: required-verification declaration refused (${verificationRead.reason})`);
+            return await refuse("declaration_refused", "the job's required-verification declaration is unusable; refusing to launch");
+        }
+        const { spentAllowanceMs } = readCompletionBinding(job, dispatchHeadSha);
+        const plan = planCompletionAllowance({
+            nowMs: deps.now(),
+            remainingMs: remainingMs(),
+            spentAllowanceMs,
+            declaredCheckTimeoutsMs: readDeclaredChecks(job.payload).map((c) => c.timeoutSeconds * 1000),
+        });
+        if (!plan.ok) {
+            return await refuse("allowance_exhausted", "the remaining attempt allowance cannot reserve cleanup, verification and finalization; refusing to launch");
+        }
+        return await runCoveredAttempt({
+            prepared: params,
+            spawnShape,
+            spawnWorker,
+            mcpSurface,
+            tee,
+            closeWorkerLog,
+            finalizeRegistry,
+            plan,
+            runtime,
+            nudge: (ids) => capability.value.buildWatcherNudge(ids),
+            dispatchHeadSha,
+            stripEnvFiles: stripWorktreeEnvFiles,
+        });
+    }
     let proc;
     try {
-        proc = deps.spawnProcess(spawnShape.executable, spawnShape.argv, {
-            cwd: worktreePath,
-            env: spawnShape.env,
-        });
+        proc = spawnWorker({ env: spawnShape.env });
     }
     catch (err) {
         await closeWorkerLog();
@@ -2397,12 +2840,40 @@ async function runPreparedSpawn(params) {
         // 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 genericResult = buildGenericSuccessResult({
+        const executorResult = buildGenericSuccessResult({
             summary: `${job.job_type} ${job.ticket_key ?? ""} completed`.trim(),
             branch,
             headSha: git.last_commit_sha,
             localCommitCount: git.local_commit_count,
         });
+        // BAPI-1296: a focused ci_fix carries its per-check mapping back to the
+        // server at `result.check_fix_claims`, where the exact-job evidence reader
+        // compares it with the dispatched set. Only the allowlisted, validated fields
+        // are merged, and they are spread FIRST so every executor-observed field
+        // (branch, head, commit count, and the verified PR below) wins over anything
+        // the worker file could have said. A missing or invalid file forwards no
+        // claims at all — the server then records an incomplete attempt — and its
+        // status is the executor's own observation, never inferred from exit code.
+        let genericResult = executorResult;
+        if (prep.ciFix) {
+            const readCiResult = seams.readCiFixResultArtifact ?? readCiFixResultArtifact;
+            const ciResult = await readCiResult(worktreePath, prep.ciFix.requiredClaimChecks, {
+                readFile: deps.readFile,
+                lstatPath: deps.lstatPath,
+            });
+            if ("fields" in ciResult) {
+                genericResult = {
+                    ...ciResult.fields,
+                    ...executorResult,
+                    [CI_FIX_CLAIMS_STATUS_KEY]: ciResult.status,
+                };
+            }
+            else {
+                deps.errorLog(`[executor] job ${job.id}: ci_fix result artifact ${ciResult.status} (${ciResult.code}); ` +
+                    "no check_fix_claims forwarded");
+                genericResult = { ...executorResult, [CI_FIX_CLAIMS_STATUS_KEY]: ciResult.status };
+            }
+        }
         // 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
@@ -2415,6 +2886,15 @@ async function runPreparedSpawn(params) {
             runCommand: deps.runCommand,
             headSha: git.last_commit_sha,
             expectedBaseBranch: effectiveBaseBranch,
+            // BAPI-1311: a focused rebase's finalization reads are bounded by the
+            // claim's remaining absolute deadline; every other job keeps the legacy,
+            // unbounded-options invocation exactly.
+            ...(prep.focusedRebase
+                ? {
+                    callTimeoutMs: () => Math.min(FOCUSED_FINALIZATION_READ_MAX_MS, remainingMs()),
+                    exposePushedHead: true,
+                }
+                : {}),
         });
         if (!finalization.ok) {
             await finalizeRegistry();
@@ -2432,6 +2912,30 @@ async function runPreparedSpawn(params) {
             }, job, control);
             return terminalToRunResult(terminal, "failed");
         }
+        // BAPI-1311 — the FOCUSED rebase's supervised post-push wait. The worker has
+        // exited cleanly and finalization PROVED its push is the origin tip, so what
+        // remains is evidence the server's completion verifier will read: the bound
+        // pull request at that head, mergeable, with its effective required checks
+        // green. The wait runs under the SAME claim, heartbeat, dead-man, and timeout
+        // supervision a worker gets, bounded by the job's ORIGINAL absolute deadline.
+        // It launches no worker, enqueues nothing, and resets nothing: a pending check
+        // is waited on, never repaired again. Only `ready` reaches `/complete`, once.
+        if (prep.focusedRebase) {
+            const focusedTerminal = await superviseFocusedRebaseWait({
+                job, httpClient, options, jobOptions, deps, ownership, observation, seams, control,
+                context: prep.focusedRebase,
+                pushedHeadSha: finalization.pushedHeadSha ?? null,
+                expectedBaseBranch: effectiveBaseBranch,
+                worktreePath,
+                jobDeadlineMs,
+                remainingMs,
+                collectTelemetry: driverTelemetry,
+                commitResidue: commitResidue(git),
+                finalizeRegistry,
+            });
+            if (focusedTerminal !== null)
+                return focusedTerminal;
+        }
         // BAPI-862: attach the pull request the EXECUTOR verified. `pr_url` was never
         // populated on this path before — `buildGenericSuccessResult` has no PR field
         // at all — which is why job 1397's stored `result.pr_url` was null even though
@@ -2523,3 +3027,767 @@ async function runPreparedSpawn(params) {
     }, job, control);
     return terminalToRunResult(terminal, "failed");
 }
+// =========================================================================
+// BAPI-1301 (D4a) — the covered-attempt phase host
+// =========================================================================
+/** How often the worker's descendant tree is sampled for containment. */
+const DESCENDANT_SAMPLE_INTERVAL_MS = 2_000;
+/** Bound on delivering the initial prompt message on the held stdin. */
+const INITIAL_PROMPT_WRITE_BOUND_MS = 30_000;
+/** Bound on closing the held stdin once the closure rule fires. */
+const STDIN_CLOSE_BOUND_MS = 5_000;
+const SUPPORTED_COMPLETION_MARKER = COMPLETION_CONTRACT_MARKER_VALUES[0];
+/**
+ * Whether this claim runs under the covered completion contract.
+ *
+ * Only the SERVER can put a job under it (by stamping the capability
+ * requirement), and only for a covered job type. A job carrying the
+ * requirement that this runner cannot honor is refused explicitly — see
+ * {@link refuseCoveredClaimBeforeLaunch} — never silently run the legacy way.
+ */
+function claimIsCovered(job) {
+    return claimRequiresCompletionEvidence(job.required_capabilities);
+}
+/**
+ * Wrap the client so a covered claim's /fail without an envelope carries the
+ * "not launched" envelope (BAPI-1301). Every other call passes straight through.
+ */
+function withNotLaunchedEnvelopeFallback(httpClient, job) {
+    const wrapped = Object.create(httpClient);
+    wrapped.fail = (claimed, failure) => {
+        if (failure.completion_evidence !== undefined)
+            return httpClient.fail(claimed, failure);
+        const { binding } = readCompletionBinding(job, typeof job.expected_head_sha === "string" ? job.expected_head_sha : null);
+        const unlaunched = unlaunchedVerification(readRequiredVerification(job.payload));
+        const envelope = buildNotLaunchedEnvelope({
+            binding,
+            runtime: { ...SUPPORTED_COMPLETION_RUNTIME },
+            verification: unlaunched.verification,
+            residuals: CLEANUP_RESIDUALS_NOT_COVERED,
+            ...(unlaunched.facts ? { verificationFacts: unlaunched.facts } : {}),
+        });
+        return httpClient.fail(claimed, {
+            ...failure,
+            completion_contract: SUPPORTED_COMPLETION_MARKER,
+            completion_evidence: envelope,
+        });
+    };
+    return wrapped;
+}
+/**
+ * The verification a covered report carries when no declared check ran
+ * (BAPI-1302): before launch, after a worker failure, or on a stop.
+ *
+ * A job with no declaration keeps BAPI-1301's version-1 `not_declared`. A job
+ * with one reports version-2 facts naming the stamped declaration with no
+ * command run, which reduces to `not_declared` for an absent or explicitly
+ * empty declaration and `incomplete` otherwise — never `passed`.
+ */
+export function unlaunchedVerification(read) {
+    if (read.kind === "none")
+        return { verification: "not_declared" };
+    const digest = read.kind === "ok" ? read.declaration.digest : read.digest;
+    if (digest === null) {
+        // A declaration whose digest is not even well-formed cannot be named in a
+        // version-2 envelope; version 1 with an incomplete verdict is the truthful
+        // report, and the server refuses to bind it to the stamped row.
+        return { verification: "incomplete" };
+    }
+    const provenance = read.kind === "ok" ? read.declaration.provenance : (read.provenance ?? "refused");
+    const facts = {
+        provenance,
+        declaration_digest: digest,
+        tested_head_sha: null,
+        artifact: "not_observed",
+        commands: [],
+    };
+    return { verification: verificationVerdictFromFacts(facts), facts };
+}
+/**
+ * The runner's facts restricted to the declaration: in declared order, one per
+ * declared command, stopping at the first command the runner reported nothing
+ * for. A missing fact is never invented — the verdict reads it as not run.
+ */
+function declaredOrderFacts(checks, runFacts) {
+    const out = [];
+    for (let i = 0; i < checks.length; i++) {
+        const fact = runFacts[i];
+        if (!fact || fact.identity !== checks[i].identity)
+            break;
+        out.push(fact);
+    }
+    return out;
+}
+/** An identity that cannot match the supported runtime, for truthful refusal envelopes. */
+function unrecognizedRuntime(adapter) {
+    return {
+        adapter: adapter.identity.agentId,
+        cli_version: "unrecognized",
+        platform: "unrecognized",
+        event_schema: "unrecognized",
+    };
+}
+/**
+ * Refuse a covered claim before any worker is launched (BAPI-1301).
+ *
+ * The server requires an envelope on every terminal report for a covered job,
+ * including a refusal. Nothing was spawned, so cleanup is confirmed with zero
+ * survivors; the ledger saw no lifecycle at all, so evidence is insufficient
+ * and the server parks the child with the cause the envelope supports
+ * (`unsupported_completion_evidence` for a runtime refusal,
+ * `required_work_incomplete` for an allowance that cannot fit).
+ */
+async function refuseCoveredClaimBeforeLaunch(input) {
+    const { job, deps } = input;
+    const { binding } = readCompletionBinding(job, input.dispatchHeadSha);
+    const ledger = createRequiredWorkLedger({ binding, lifecycleSupported: input.reason !== "uncoverable_job" });
+    if (input.reason === "allowance_exhausted")
+        ledger.recordAllowanceExhausted();
+    if (input.reason === "declaration_refused")
+        ledger.recordDeclarationRefused();
+    const unlaunched = unlaunchedVerification(readRequiredVerification(job.payload));
+    const envelope = ledger.buildEnvelope({
+        runtime: input.runtime,
+        finalHeadSha: input.dispatchHeadSha,
+        finalization: "unknown",
+        verification: unlaunched.verification,
+        cleanup: buildCleanupVerdict("confirmed", 0, []),
+        missingCapabilities: [],
+        ...(unlaunched.facts ? { verificationFacts: unlaunched.facts } : {}),
+    });
+    const cause = envelope.cause ?? "required_work_incomplete";
+    deps.errorLog(`[executor] job ${job.id}: covered attempt refused before launch (${input.reason})`);
+    const terminal = await sendTerminalMutationWithAuthReport({
+        kind: "fail",
+        send: () => input.httpClient.fail(job, {
+            error_kind: COMPLETION_CAUSE_ERROR_KINDS[cause],
+            error_message: input.message,
+            classification: "crashed",
+            telemetry: input.observation.snapshot(),
+            completion_contract: SUPPORTED_COMPLETION_MARKER,
+            completion_evidence: envelope,
+        }),
+        deps,
+        options: input.options,
+        ownership: input.ownership,
+        log: deps.log,
+    }, job, input.control);
+    return terminalToRunResult(terminal, "failed");
+}
+/**
+ * Run ONE covered attempt from spawn to terminal acknowledgement (BAPI-1301).
+ *
+ * The phases, all under one absolute deadline and one continuous heartbeat:
+ *
+ *   1. worker, prompt on held stdin, stdout read by the authoritative ledger;
+ *      stdin closed only by the closure rule or the hold deadline, then EOF
+ *      drained (bounded);
+ *   2. owned-process cleanup sweep (tag + tracked descendants);
+ *   3. D4c declared checks, when a runner is installed, plus their cleanup;
+ *   4. finalization (`validateWorkerFinalization`, unchanged);
+ *   5. terminal report carrying the versioned envelope, sent only while this
+ *      executor still owns the claim.
+ *
+ * The heartbeat is started HERE, not by `superviseProcess`, precisely so it
+ * does not stop when the worker exits: cleanup, finalization and the report
+ * all still run under a live claim, and a stop/stale/dead-man outcome during
+ * any of them is honored. After the worker exits, no heartbeat outcome ever
+ * signals its (possibly recycled) pid.
+ */
+async function runCoveredAttempt(params) {
+    const { job, httpClient, options, jobOptions, deps, ownership, observation, seams, worktreePath, branch, prep, effectiveBaseBranch, adapter, control, lifecycle, } = params.prepared;
+    const { spawnShape, mcpSurface, plan, closeWorkerLog, finalizeRegistry } = params;
+    // --- Ownership identity -------------------------------------------------
+    // Unpredictable, executor-generated, and injected AFTER the adapter built its
+    // environment, so neither ambient input nor the job payload can choose it.
+    const token = createOwnershipToken();
+    const tokenDigest = ownershipTokenDigest(token);
+    const hostDigest = hostIdentityDigest(os.hostname());
+    const workerEnv = withOwnershipTag(spawnShape.env, token);
+    const stateDir = resolveExecutorStateDir(buildJobLogRegistryDeps(deps));
+    const recordFs = seams.ownershipRecordFs ?? createDefaultOwnershipRecordFs();
+    try {
+        // Written BEFORE the spawn: if this executor is SIGKILLed mid-attempt, a
+        // restarted executor finds the record and sweeps with the real token.
+        await writeOwnershipRecord(stateDir, {
+            jobId: job.id,
+            repoName: job.repo_name,
+            token,
+            hostDigest,
+            createdAt: nowIso(deps),
+            // Lets another executor starting on this host tell a live job from an
+            // interrupted one, so it never sweeps this executor's running worker.
+            executorPid: process.pid,
+        }, recordFs);
+    }
+    catch (err) {
+        deps.errorLog(`[executor] job ${job.id}: ownership record not written (non-fatal): ${boundedError(err)}`);
+    }
+    const inspector = seams.processInspector ??
+        createMacProcessInspector({ runCommand: deps.runCommand, selfPid: process.pid, platform: deps.platform });
+    // --- The ledger and its bindings ------------------------------------------
+    const { binding } = readCompletionBinding(job, params.dispatchHeadSha);
+    const obligationTargets = finalizationObligations(branch, effectiveBaseBranch);
+    const obligations = [
+        { operation: "push", target: obligationTargets.push },
+        { operation: "pr_create", target: obligationTargets.prCreate },
+    ];
+    const ledger = createRequiredWorkLedger({
+        binding,
+        lifecycleSupported: true,
+        optionalWatchers: readOptionalWatchers(job.payload),
+        obligations,
+    });
+    // --- Spawn (held stdin) ---------------------------------------------------
+    let proc;
+    try {
+        proc = params.spawnWorker({ env: workerEnv, stdin: "pipe" });
+    }
+    catch (err) {
+        await closeWorkerLog();
+        await finalizeRegistry();
+        await removeOwnershipRecord(stateDir, job.id, recordFs).catch(() => undefined);
+        const raw = `failed to spawn worker: ${boundedError(err)}`;
+        const redactionCapability = adapter.redaction;
+        ledger.recordTransportFailure(true);
+        const unlaunched = unlaunchedVerification(readRequiredVerification(job.payload));
+        const envelope = ledger.buildEnvelope({
+            runtime: params.runtime,
+            finalHeadSha: params.dispatchHeadSha,
+            finalization: "unknown",
+            verification: unlaunched.verification,
+            cleanup: buildCleanupVerdict("confirmed", 0, []),
+            missingCapabilities: [],
+            ...(unlaunched.facts ? { verificationFacts: unlaunched.facts } : {}),
+        });
+        await httpClient.fail(job, {
+            error_kind: "SpawnError",
+            error_message: redactionCapability?.supported === true
+                ? redactAdapterDiagnostic(raw, deps.env, redactionCapability.value)
+                : raw,
+            classification: "crashed",
+            completion_contract: SUPPORTED_COMPLETION_MARKER,
+            completion_evidence: envelope,
+        });
+        return { status: "failed", reason: "spawn_failed" };
+    }
+    const terminationController = createProcessTerminationController(proc, deps, jobOptions.termGraceMs);
+    lifecycle.deregisterLiveWorker = control?.liveWorkers.register(terminationController);
+    const supervisedProc = params.tee
+        ? {
+            ...proc,
+            stdout: proc.stdout ? teeAsyncIterable(proc.stdout, params.tee, "stdout") : null,
+            stderr: proc.stderr ? teeAsyncIterable(proc.stderr, params.tee, "stderr") : null,
+        }
+        : proc;
+    // --- Ownership lifetime: one heartbeat for the whole attempt ---------------
+    let childLive = true;
+    let workerStartedAt = null;
+    const tracker = proc.pid !== undefined ? createDescendantTracker({ inspector, rootPid: proc.pid }) : null;
+    if (proc.pid !== undefined) {
+        void inspector
+            .identity(proc.pid)
+            .then((identity) => {
+            if (identity)
+                workerStartedAt = identity.startedAt.slice(0, 64);
+        })
+            .catch(() => undefined);
+    }
+    const ownershipContext = () => ({
+        version: 1,
+        token_digest: tokenDigest,
+        host_digest: hostDigest,
+        worker: childLive && proc.pid !== undefined && workerStartedAt !== null
+            ? { pid: proc.pid, started_at: workerStartedAt }
+            : null,
+    });
+    const collectTelemetry = () => collectGitTelemetry({ runCommand: deps.runCommand, now: deps.now }, worktreePath, effectiveBaseBranch);
+    const collectRemoteMarker = () => collectRemoteTrackingSha({ runCommand: deps.runCommand }, worktreePath, branch);
+    const attemptDone = { value: false };
+    let heartbeatOutcome = null;
+    const heartbeat = runHeartbeatLoop({
+        job,
+        httpClient,
+        options: jobOptions,
+        deps,
+        ownership,
+        proc: supervisedProc,
+        observation,
+        collectTelemetry,
+        collectRemoteMarker,
+        isDone: () => attemptDone.value,
+        currentChild: () => (childLive ? proc : null),
+        ownershipContext,
+    }).then((outcome) => {
+        heartbeatOutcome = outcome;
+        return outcome;
+    });
+    const endHeartbeat = async () => {
+        attemptDone.value = true;
+        const outcome = await heartbeat;
+        if (outcome.kind === "auth_fatal") {
+            control?.reportAuthFatal?.({
+                jobId: job.id,
+                repoName: job.repo_name,
+                category: "heartbeat",
+                httpStatus: outcome.httpStatus,
+            });
+        }
+    };
+    // --- Descendant sampling (containment input) -------------------------------
+    let sampleTimer;
+    const scheduleSample = () => {
+        if (!tracker || !childLive)
+            return;
+        sampleTimer = deps.setTimer(() => {
+            sampleTimer = undefined;
+            void tracker.sample().finally(scheduleSample);
+        }, DESCENDANT_SAMPLE_INTERVAL_MS);
+    };
+    if (tracker)
+        void tracker.sample().finally(scheduleSample);
+    // --- Held-stdin closure supervision -----------------------------------------
+    const stdinDeps = { now: deps.now, setTimer: deps.setTimer, clearTimer: deps.clearTimer };
+    const supervisor = createClosureSupervisor({
+        ledger,
+        deps: stdinDeps,
+        writeMessage: (line) => writeStdinBounded(proc, line, { deadlineAtMs: plan.holdDeadlineAtMs, deps: stdinDeps }),
+        closeStdin: async () => {
+            await closeStdinBounded(proc, {
+                deadlineAtMs: Math.min(plan.workerDeadlineAtMs, deps.now() + STDIN_CLOSE_BOUND_MS),
+                deps: stdinDeps,
+            });
+        },
+        buildNudge: params.nudge,
+        deadlineAtMs: plan.holdDeadlineAtMs,
+    });
+    // The authoritative consumer: whole lines into the ledger, bounded. A line
+    // that outgrows the event bound is handed over once (the ledger marks it
+    // `stream_oversize`) and the rest of it is discarded up to its newline.
+    let lineBuffer = "";
+    let discardingOversize = false;
+    const authoritativeStdout = (chunk) => {
+        lineBuffer += chunk;
+        let newline;
+        while ((newline = lineBuffer.indexOf("\n")) >= 0) {
+            const line = lineBuffer.slice(0, newline);
+            lineBuffer = lineBuffer.slice(newline + 1);
+            if (discardingOversize) {
+                discardingOversize = false;
+                continue;
+            }
+            ledger.ingestLine(line);
+            supervisor.onActivity();
+        }
+        if (!discardingOversize && lineBuffer.length > MAX_EVENT_BYTES) {
+            ledger.ingestLine(lineBuffer);
+            lineBuffer = "";
+            discardingOversize = true;
+        }
+        else if (discardingOversize) {
+            lineBuffer = "";
+        }
+    };
+    const runPromise = runProcessWithTimeout(supervisedProc, Math.max(1, Math.ceil(plan.workerWindowMs / 1000)), deps, {
+        termGraceMs: jobOptions.termGraceMs,
+        terminationController,
+        onStdout: (chunk) => observation.recordStdout(chunk),
+        authoritativeStdout,
+        drainDeadlineMs: EOF_DRAIN_BOUND_MS,
+        onStdoutTerminationCheck: (chunk) => {
+            mcpSurface.observeStdout(chunk);
+            return mcpSurface.shouldTerminate();
+        },
+    });
+    // The prompt goes in AFTER supervision started reading stdout, so a child
+    // that writes before it reads can never deadlock against this write.
+    const initialMessage = spawnShape.stdinMessages?.initial;
+    const initialWrite = initialMessage
+        ? await writeStdinBounded(proc, initialMessage, {
+            deadlineAtMs: Math.min(plan.holdDeadlineAtMs, deps.now() + INITIAL_PROMPT_WRITE_BOUND_MS),
+            deps: stdinDeps,
+        })
+        : { ok: false, reason: "no_stdin" };
+    if (!initialWrite.ok) {
+        // Transport failed before any work: nothing the worker did can be
+        // evidence. Stop it through the one termination path.
+        ledger.recordTransportFailure(true);
+        terminationController.requestTermination();
+    }
+    const procResult = await runPromise;
+    childLive = false;
+    if (sampleTimer !== undefined)
+        deps.clearTimer(sampleTimer);
+    supervisor.dispose();
+    if (!discardingOversize && lineBuffer.length > 0)
+        ledger.ingestLine(lineBuffer);
+    ledger.recordStreamEnd(procResult.authoritativeStreamError || procResult.exitUnconfirmed
+        ? "stream_error"
+        : (procResult.stdoutEnd ?? "eof"));
+    ledger.recordProcessExit({ code: procResult.exitCode, signal: procResult.signal });
+    observation.setExitCode(procResult.exitCode);
+    // --- Phase 2: owned-process cleanup (success-blocking) ----------------------
+    let cleanup;
+    if (tracker) {
+        tracker.markRootExited();
+        await tracker.sample();
+    }
+    cleanup = await runOwnedProcessSweep({
+        token,
+        inspector,
+        deps: { now: deps.now, sleep: deps.sleep },
+        deadlineAtMs: deps.now() + plan.reservations.cleanupMs,
+        trackedDescendants: tracker?.owned() ?? [],
+        trackerOverflowed: tracker?.overflowed() ?? false,
+    });
+    // Adapter configuration hygiene stays separate and best-effort; it can never
+    // stand in for the process-cleanup verdict above.
+    const lifecycleCapability = adapter.lifecycle;
+    if (lifecycleCapability?.supported === true && lifecycleCapability.value.declaration.kind === "managed") {
+        try {
+            await lifecycleCapability.value.declaration.cleanupAfterJob({ worktreePath });
+        }
+        catch (err) {
+            deps.errorLog(`adapter lifecycle cleanup failed (non-fatal): ${boundedError(err)}`);
+        }
+    }
+    const finalTelemetry = await collectTelemetry();
+    observation.setGitTelemetry(finalTelemetry);
+    if (typeof finalTelemetry.last_commit_sha === "string") {
+        observation.setAttemptEndSha(finalTelemetry.last_commit_sha);
+    }
+    const finalHeadSha = typeof finalTelemetry.last_commit_sha === "string" ? finalTelemetry.last_commit_sha : null;
+    await closeWorkerLog();
+    await reportWorkerLogSessionInvariant(params.tee, deps);
+    // BAPI-1302: the declaration was validated whole at admission; a refused one
+    // never reaches this point.
+    const verificationRead = readRequiredVerification(job.payload);
+    const declaration = verificationRead.kind === "ok" ? verificationRead.declaration : null;
+    const checks = declaration?.checks ?? [];
+    const envelopeWith = (facts) => ledger.buildEnvelope({
+        runtime: params.runtime,
+        finalHeadSha,
+        finalization: facts.finalization,
+        verification: facts.verification,
+        cleanup,
+        missingCapabilities: facts.missing,
+        satisfiedObligations: [
+            ...(facts.pushSatisfied ? [obligations[0]] : []),
+            ...(facts.prSatisfied ? [obligations[1]] : []),
+        ],
+        ...(facts.verificationFacts ? { verificationFacts: facts.verificationFacts } : {}),
+    });
+    const unverifiedEnvelope = () => {
+        const unlaunched = unlaunchedVerification(verificationRead);
+        return envelopeWith({
+            finalization: "unknown",
+            verification: unlaunched.verification,
+            missing: [],
+            ...(unlaunched.facts ? { verificationFacts: unlaunched.facts } : {}),
+        });
+    };
+    // The terminal report's retry window (BAPI-1301). The shared terminal sender
+    // retries a retryable response until the dead-man window since the last
+    // successful heartbeat passes. Here the heartbeat keeps succeeding through the
+    // report, so that window alone would never close: the report would retry
+    // forever. This view keeps the claim fence and abandonment shared with the
+    // heartbeat, and additionally closes the window at the attempt's absolute
+    // deadline (the end of the report reservation) — never later.
+    const reportOwnership = {
+        get abandoned() {
+            return ownership.abandoned;
+        },
+        set abandoned(value) {
+            ownership.abandoned = value;
+        },
+        get abandonReason() {
+            return ownership.abandonReason;
+        },
+        set abandonReason(value) {
+            ownership.abandonReason = value;
+        },
+        get lastSuccessfulHeartbeatAt() {
+            return Math.min(ownership.lastSuccessfulHeartbeatAt, plan.deadlineAtMs - options.deadmanMs);
+        },
+        set lastSuccessfulHeartbeatAt(value) {
+            ownership.lastSuccessfulHeartbeatAt = value;
+        },
+    };
+    const git = observation.git();
+    const failWith = async (failure, envelope, extra = {}) => {
+        await finalizeRegistry();
+        const terminal = await sendTerminalMutationWithAuthReport({
+            kind: "fail",
+            send: () => httpClient.fail(job, {
+                ...failure,
+                ...commitResidue(git),
+                telemetry: observation.snapshot(),
+                completion_contract: SUPPORTED_COMPLETION_MARKER,
+                completion_evidence: envelope,
+                ...extra,
+            }),
+            deps,
+            options,
+            ownership: reportOwnership,
+            log: deps.log,
+        }, job, control);
+        return terminalToRunResult(terminal, "failed");
+    };
+    const finish = async (result) => {
+        // The terminal report is acknowledged (or ownership is gone): only now does
+        // the job-level heartbeat end, and only now is the restart record retired.
+        await endHeartbeat();
+        await removeOwnershipRecord(stateDir, job.id, recordFs).catch(() => undefined);
+        return result;
+    };
+    // --- Stronger outcomes keep their precedence ---------------------------------
+    // Checked here AND again right before the terminal report: the heartbeat now
+    // outlives the worker, so a lost claim or a server stop can arrive during
+    // cleanup, verification or finalization, and must still win over a report
+    // built from those phases.
+    const strongerOutcome = async () => {
+        if (ownership.abandoned) {
+            await finalizeRegistry();
+            return finish({ status: "abandoned", reason: ownership.abandonReason });
+        }
+        const hbNow = heartbeatOutcome;
+        if (hbNow?.kind === "server_stop") {
+            const result = await failWith({
+                error_kind: "ServerStopRequested",
+                error_message: "the server requested this run stop; the owned worker was terminated",
+                classification: "killed",
+            }, unverifiedEnvelope());
+            ownership.abandoned = true;
+            ownership.abandonReason = "server_stop";
+            return finish(result.status === "failed" ? { status: "abandoned", reason: "server_stop" } : result);
+        }
+        return null;
+    };
+    const earlyStronger = await strongerOutcome();
+    if (earlyStronger)
+        return earlyStronger;
+    const surfaceVerdict = mcpSurface.verdict();
+    if (surfaceVerdict.kind === "mismatch") {
+        return finish(await failWith({
+            error_kind: McpSurfaceMismatch,
+            error_message: formatMcpSurfaceMismatch(surfaceVerdict.expected, surfaceVerdict.observed),
+            classification: "crashed",
+        }, unverifiedEnvelope()));
+    }
+    if (surfaceVerdict.kind === "absent" &&
+        procResult.classification === "crashed" &&
+        procResult.stdoutExcerpt.trim().length === 0) {
+        return finish(await failWith({ error_kind: WorkerStartupFatal, error_message: WORKER_STARTUP_FATAL_MESSAGE, classification: "crashed" }, unverifiedEnvelope()));
+    }
+    if (procResult.classification !== "clean_exit") {
+        if (procResult.classification === "timeout" || procResult.classification === "killed") {
+            await cleanupInterruptedWorktree(worktreePath, {
+                runCommand: deps.runCommand,
+                removeFile: deps.removeFile ?? ((filePath) => rm(filePath)),
+                errorLog: deps.errorLog,
+            });
+        }
+        const authDetection = adapter.authFailureDetection;
+        const authFailure = authDetection?.supported === true && authDetection.value.classify(procResult.stdoutExcerpt).notAuthenticated;
+        const capacityEvidence = authFailure
+            ? undefined
+            : buildTerminalCapacityEvidence(job, observation, adapter.identity.agentId);
+        const envelope = unverifiedEnvelope();
+        const cause = envelope.cause;
+        return finish(await failWith({
+            error_kind: authFailure
+                ? ClaudeNotAuthenticated
+                : cause
+                    ? COMPLETION_CAUSE_ERROR_KINDS[cause]
+                    : classificationToErrorKind(procResult.classification),
+            error_message: authFailure
+                ? CLAUDE_NOT_AUTHENTICATED_MESSAGE
+                : `worker exited (${procResult.classification}, exit_code=${procResult.exitCode})`,
+            classification: toWireClassification(procResult.classification),
+        }, envelope, capacityEvidence !== undefined ? { capacity_evidence: capacityEvidence } : {}));
+    }
+    // --- Phase 3: independent declared checks (BAPI-1302, D4c) ---------------------
+    // Every declared command runs HERE, by the executor, after the worker exited
+    // and its processes were swept — including commands the worker never started
+    // or claims already passed. Worker text is never read. The checks are bound
+    // to the final local artifact: full HEAD plus the tracked tree/index is read
+    // before them and again after them AND their cleanup; any movement makes the
+    // evidence stale. Nothing is committed, reset or repaired.
+    let verification = "not_declared";
+    let verificationFacts;
+    if (declaration !== null && declaration.provenance !== "declared") {
+        // `absent` or `declared_empty`: no declared local verification. Reported
+        // as such — never as a pass.
+        verificationFacts = {
+            provenance: declaration.provenance,
+            declaration_digest: declaration.digest,
+            tested_head_sha: null,
+            artifact: "not_observed",
+            commands: [],
+        };
+        verification = verificationVerdictFromFacts(verificationFacts);
+    }
+    else if (declaration !== null) {
+        const runner = seams.declaredCheckRunner ??
+            createRequiredVerificationRunner({
+                launch: createSupervisedCommandLauncher({
+                    deps,
+                    registerLive: (controller) => control?.liveWorkers.register(controller),
+                }),
+                now: deps.now,
+                log: deps.log,
+            });
+        const ownershipHeld = () => !ownership.abandoned && heartbeatOutcome?.kind !== "server_stop";
+        const envGuard = params.stripEnvFiles ? await params.stripEnvFiles() : { ok: true };
+        const before = envGuard.ok
+            ? await observeFinalArtifact(deps.runCommand, worktreePath)
+            : { head: null, trackedStatus: null };
+        const preState = envGuard.ok ? preCheckArtifactState(before, finalHeadSha) : "not_observed";
+        let runFacts = [];
+        let artifact;
+        if (preState === null) {
+            const checkAbort = new AbortController();
+            // Ownership is re-checked WHILE a command runs, not only between commands:
+            // a lost claim or a server stop terminates the running check.
+            let watchTimer;
+            const watchOwnership = () => {
+                watchTimer = deps.setTimer(() => {
+                    watchTimer = undefined;
+                    if (!ownershipHeld())
+                        checkAbort.abort();
+                    else
+                        watchOwnership();
+                }, OWNERSHIP_POLL_MS);
+            };
+            watchOwnership();
+            try {
+                const outcome = await runner.run({
+                    checks,
+                    worktreePath,
+                    finalHeadSha,
+                    env: workerEnv,
+                    deadlineAtMs: deps.now() + plan.reservations.verificationMs,
+                    signal: checkAbort.signal,
+                    ownershipHeld,
+                });
+                runFacts = outcome.facts ?? [];
+            }
+            catch {
+                // A runner that throws proved nothing ran to completion.
+                runFacts = [];
+            }
+            finally {
+                if (watchTimer !== undefined)
+                    deps.clearTimer(watchTimer);
+            }
+            // Check cleanup BEFORE the final observation: the checks ran with the same
+            // ownership tag, so the same sweep proves they left nothing behind, and a
+            // survivor could still be writing to the worktree. The worse verdict wins.
+            const checkCleanup = await runOwnedProcessSweep({
+                token,
+                inspector,
+                deps: { now: deps.now, sleep: deps.sleep },
+                deadlineAtMs: deps.now() + plan.reservations.checkCleanupMs,
+            });
+            if (checkCleanup.verdict !== "confirmed") {
+                cleanup = buildCleanupVerdict(cleanup.verdict === "failed" || checkCleanup.verdict === "failed" ? "failed" : "unconfirmed", cleanup.survivors + checkCleanup.survivors, [...cleanup.reasons, ...checkCleanup.reasons]);
+            }
+            artifact = compareFinalArtifact(before, await observeFinalArtifact(deps.runCommand, worktreePath));
+        }
+        else {
+            artifact = preState;
+        }
+        verificationFacts = {
+            provenance: "declared",
+            declaration_digest: declaration.digest,
+            tested_head_sha: before.head,
+            artifact,
+            commands: declaredOrderFacts(checks, runFacts).map(toCompletionCheckFact),
+        };
+        verification = verificationVerdictFromFacts(verificationFacts, checks.length);
+    }
+    // --- Phase 4: finalization (unchanged executor facts) ----------------------------
+    const artifacts = await readCompletionArtifacts(worktreePath, deps);
+    const executorResult = buildGenericSuccessResult({
+        summary: `${job.job_type} ${job.ticket_key ?? ""} completed`.trim(),
+        branch,
+        headSha: git.last_commit_sha,
+        localCommitCount: git.local_commit_count,
+    });
+    let genericResult = executorResult;
+    if (prep.ciFix) {
+        const readCiResult = seams.readCiFixResultArtifact ?? readCiFixResultArtifact;
+        const ciResult = await readCiResult(worktreePath, prep.ciFix.requiredClaimChecks, {
+            readFile: deps.readFile,
+            lstatPath: deps.lstatPath,
+        });
+        genericResult =
+            "fields" in ciResult
+                ? { ...ciResult.fields, ...executorResult, [CI_FIX_CLAIMS_STATUS_KEY]: ciResult.status }
+                : { ...executorResult, [CI_FIX_CLAIMS_STATUS_KEY]: ciResult.status };
+    }
+    const finalization = await validateWorkerFinalization({
+        job,
+        branch,
+        worktreePath,
+        result: genericResult,
+        runCommand: deps.runCommand,
+        headSha: git.last_commit_sha,
+        expectedBaseBranch: effectiveBaseBranch,
+    });
+    const facts = finalizationFacts(finalization.ok ? { ok: true } : { ok: false, errorKind: finalization.failure.error_kind });
+    const envelope = envelopeWith({
+        finalization: facts.verdict,
+        verification,
+        missing: [],
+        pushSatisfied: facts.pushSatisfied,
+        prSatisfied: facts.prSatisfied,
+        ...(verificationFacts ? { verificationFacts } : {}),
+    });
+    // --- Phase 5: terminal report -----------------------------------------------------
+    const lateStronger = await strongerOutcome();
+    if (lateStronger)
+        return lateStronger;
+    if (finalization.ok && successRefusalReason(envelope) === null) {
+        const result = typeof finalization.prUrl === "string" ? { ...genericResult, pr_url: finalization.prUrl } : genericResult;
+        const completion = {
+            job_type: job.job_type,
+            exit_code: procResult.exitCode ?? 0,
+            classification: "clean_exit",
+            result,
+            artifacts,
+            ...commitResidue(git),
+            telemetry: observation.snapshot(),
+            completion_contract: SUPPORTED_COMPLETION_MARKER,
+            completion_evidence: envelope,
+        };
+        const terminal = await sendTerminalMutationWithAuthReport({
+            kind: "complete",
+            send: () => httpClient.complete(job, completion),
+            deps,
+            options,
+            ownership: reportOwnership,
+            log: deps.log,
+        }, job, control);
+        await finalizeRegistry();
+        return finish(terminalToRunResult(terminal, "completed"));
+    }
+    // Not a success. A completion cause (required work, cleanup, verification,
+    // permission) outranks the finalization kind; with none, finalization keeps
+    // its existing error kind and recovery lane.
+    const cause = envelope.cause;
+    if (cause) {
+        return finish(await failWith({
+            error_kind: COMPLETION_CAUSE_ERROR_KINDS[cause],
+            error_message: `covered attempt did not prove completion (${successRefusalReason(envelope) ?? cause})`,
+            classification: "crashed",
+        }, envelope));
+    }
+    if (!finalization.ok)
+        return finish(await failWith(finalization.failure, envelope));
+    return finish(await failWith({
+        error_kind: COMPLETION_CAUSE_ERROR_KINDS.required_work_incomplete,
+        error_message: `covered attempt did not prove completion (${successRefusalReason(envelope) ?? "unknown"})`,
+        classification: "crashed",
+    }, envelope));
+}