@bridge_gpt/mcp-server 0.2.62 → 0.2.65

package/build/executor/results.js

@@ -132,3 +132,145 @@ export function commitResidue(telemetry) {
     }
     return out;
 }
+// ---------------------------------------------------------------------------
+// BAPI-1296 — the CI-only fixed-path result reader.
+//
+// A `ci_fix` worker writes `<worktree>/.conductor/result.json` with its per-check
+// mapping (and, optionally, an external-attribution diagnosis). Before this
+// ticket the executor never read that file for `ci_fix`, so the mapping the
+// server's exit contract compares against never arrived and every clean exit
+// looked incomplete. This reader transports it — bounded, allowlisted, and
+// read only after THIS attempt's worker exited (the locked pre-spawn cleanup in
+// `job-runner.ts` removed any earlier attempt's file) — and nothing else.
+//
+// It is TELEMETRY transport, not certification: the executor never decides
+// that coverage is complete because the process exited cleanly, never lets the
+// file supply branch/head/PR identifiers, and never lets it name a transition.
+// The server re-derives completeness from the job row's dispatched set.
+// ---------------------------------------------------------------------------
+/** Largest `ci_fix` result artifact read, in bytes. */
+export const CI_FIX_RESULT_MAX_BYTES = 16_384;
+/** Most entries in `check_fix_claims` (mirrors the dispatch cap). */
+export const CI_FIX_CLAIMS_MAX_ENTRIES = 32;
+/** Longest single claim value, in UTF-8 bytes. */
+export const CI_FIX_CLAIM_MAX_BYTES = 512;
+/** Longest attribution reason, in UTF-8 bytes. */
+export const CI_FIX_ATTRIBUTION_REASON_MAX_BYTES = 300;
+/** The per-check mapping key (Python `CI_FIX_CHECK_CLAIMS_KEY`). */
+export const CI_FIX_CHECK_CLAIMS_KEY = "check_fix_claims";
+/** The attribution keys and sentinel (Python `CI_FIX_ATTRIBUTION_*`). */
+export const CI_FIX_ATTRIBUTION_KEY = "ci_failure_attribution";
+export const CI_FIX_ATTRIBUTION_REASON_KEY = "ci_failure_attribution_reason";
+export const CI_FIX_ATTRIBUTION_EXTERNAL = "external";
+/**
+ * Executor-owned status of the artifact, carried at `result.check_fix_claims_status`
+ * so an operator can tell "the worker wrote nothing" from "the worker wrote
+ * something unusable" from "the worker covered only part of the set". It is the
+ * executor's own observation, never a worker-supplied value.
+ */
+export const CI_FIX_CLAIMS_STATUS_KEY = "check_fix_claims_status";
+const CI_FIX_RESULT_ALLOWED_KEYS = new Set([
+    CI_FIX_CHECK_CLAIMS_KEY,
+    CI_FIX_ATTRIBUTION_KEY,
+    CI_FIX_ATTRIBUTION_REASON_KEY,
+]);
+function isPlainRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+/**
+ * Read and validate `<worktree>/.conductor/result.json` for a `ci_fix` job.
+ *
+ * `requiredChecks` is the executor-validated dispatched union. A claim for any
+ * name outside it, an extra top-level key, an oversized/blank value, an unpaired
+ * attribution, a non-regular file, a file over {@link CI_FIX_RESULT_MAX_BYTES},
+ * or invalid JSON makes the whole artifact `invalid` — nothing from it is
+ * forwarded. A valid artifact that covers only part of the set is `partial` and
+ * IS forwarded, so the server's contract check sees exactly what was claimed.
+ * Never throws; `code` is a fixed, secret-free token.
+ */
+export async function readCiFixResultArtifact(worktreePath, requiredChecks, deps) {
+    const artifactPath = path.join(worktreePath, ".conductor", "result.json");
+    if (deps.lstatPath) {
+        let meta;
+        try {
+            meta = await deps.lstatPath(artifactPath);
+        }
+        catch {
+            return { status: "invalid", code: "artifact_unreadable" };
+        }
+        if (meta === null)
+            return { status: "missing", code: "artifact_absent" };
+        if (meta.isDirectory || meta.isSymbolicLink) {
+            return { status: "invalid", code: "artifact_not_regular_file" };
+        }
+    }
+    let raw;
+    try {
+        raw = await deps.readFile(artifactPath);
+    }
+    catch (err) {
+        const code = err && typeof err === "object" ? err.code : undefined;
+        return code === "ENOENT"
+            ? { status: "missing", code: "artifact_absent" }
+            : { status: "invalid", code: "artifact_unreadable" };
+    }
+    if (typeof raw !== "string")
+        return { status: "invalid", code: "artifact_unreadable" };
+    if (byteLength(raw) > CI_FIX_RESULT_MAX_BYTES) {
+        return { status: "invalid", code: "artifact_oversized" };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return { status: "invalid", code: "artifact_not_json" };
+    }
+    if (!isPlainRecord(parsed))
+        return { status: "invalid", code: "artifact_not_object" };
+    for (const key of Object.keys(parsed)) {
+        if (!CI_FIX_RESULT_ALLOWED_KEYS.has(key)) {
+            return { status: "invalid", code: "artifact_unexpected_key" };
+        }
+    }
+    const claims = parsed[CI_FIX_CHECK_CLAIMS_KEY];
+    if (!isPlainRecord(claims))
+        return { status: "invalid", code: "claims_not_object" };
+    const claimNames = Object.keys(claims);
+    if (claimNames.length > CI_FIX_CLAIMS_MAX_ENTRIES) {
+        return { status: "invalid", code: "claims_too_many" };
+    }
+    const required = new Set(requiredChecks);
+    const validatedClaims = {};
+    for (const name of claimNames) {
+        const value = claims[name];
+        if (!required.has(name))
+            return { status: "invalid", code: "claims_undispatched_check" };
+        if (typeof value !== "string" ||
+            value.trim().length === 0 ||
+            byteLength(value) > CI_FIX_CLAIM_MAX_BYTES) {
+            return { status: "invalid", code: "claims_value_invalid" };
+        }
+        validatedClaims[name] = value;
+    }
+    const fields = { [CI_FIX_CHECK_CLAIMS_KEY]: validatedClaims };
+    const hasAttribution = Object.prototype.hasOwnProperty.call(parsed, CI_FIX_ATTRIBUTION_KEY);
+    const hasReason = Object.prototype.hasOwnProperty.call(parsed, CI_FIX_ATTRIBUTION_REASON_KEY);
+    if (hasAttribution || hasReason) {
+        const attribution = parsed[CI_FIX_ATTRIBUTION_KEY];
+        const reason = parsed[CI_FIX_ATTRIBUTION_REASON_KEY];
+        if (!hasAttribution ||
+            !hasReason ||
+            typeof attribution !== "string" ||
+            attribution.trim().toLowerCase() !== CI_FIX_ATTRIBUTION_EXTERNAL ||
+            typeof reason !== "string" ||
+            reason.trim().length === 0 ||
+            byteLength(reason) > CI_FIX_ATTRIBUTION_REASON_MAX_BYTES) {
+            return { status: "invalid", code: "attribution_invalid" };
+        }
+        fields[CI_FIX_ATTRIBUTION_KEY] = CI_FIX_ATTRIBUTION_EXTERNAL;
+        fields[CI_FIX_ATTRIBUTION_REASON_KEY] = reason;
+    }
+    const covered = requiredChecks.every((name) => Object.prototype.hasOwnProperty.call(validatedClaims, name));
+    return { status: covered ? "complete" : "partial", fields };
+}

package/build/executor/resume-pre-spawn.js

@@ -14,7 +14,7 @@
  * §16 — the amended proposal explicitly rejected `fetch && reset --hard`).
  */
 import { createWorktreeForTicket } from "../worktree-core.js";
-import { ExecutorNamedError, WorktreeLostBeforePush } from "./job-errors.js";
+import { ContinuationLineageMismatch, ContinuationWorktreeMissing, ExecutorNamedError, WorktreeLostBeforePush, } from "./job-errors.js";
 import { assertWorktreeOnBranch, listGitWorktrees, findWorktreeByBranch, remoteBranchExists as remoteBranchExistsDefault, } from "./worktree-inspection.js";
 /** The canonical WIP checkpoint commit message (executor-run, deterministic). */
 export const RESUME_WIP_COMMIT_MESSAGE = "wip: auto-checkpoint before resume";
@@ -119,13 +119,13 @@ export async function recreateResumeWorktreeFromPushedBranch(job, expectedBranch
  * is always clean and complete. No-op cleanly when the tree is already clean.
  * NEVER discards work.
  */
-export async function autoCheckpointDirtyState(worktreePath, seams) {
+export async function autoCheckpointDirtyState(worktreePath, seams, message = RESUME_WIP_COMMIT_MESSAGE) {
     const status = await seams.runCommand("git", ["status", "--porcelain"], { cwd: worktreePath });
     if (status.stdout.trim().length === 0) {
         return { committed: false };
     }
     await seams.runCommand("git", ["add", "-A"], { cwd: worktreePath });
-    await seams.runCommand("git", ["commit", "-m", RESUME_WIP_COMMIT_MESSAGE], {
+    await seams.runCommand("git", ["commit", "-m", message], {
         cwd: worktreePath,
     });
     return { committed: true };
@@ -144,6 +144,75 @@ export async function readResumeGitDiff(worktreePath, baseBranch, seams) {
 export function fillResumePromptPlaceholders(template, gitLog, gitDiff) {
     return template.split("{{GIT_LOG}}").join(gitLog).split("{{GIT_DIFF}}").join(gitDiff);
 }
+// ---------------------------------------------------------------------------
+// BAPI-1300 — parked-child continuation: retained-work verification
+// ---------------------------------------------------------------------------
+/** The deterministic WIP checkpoint message for a continuation. */
+export const CONTINUATION_WIP_COMMIT_MESSAGE = "wip: auto-checkpoint before continuation";
+const FULL_SHA = /^[0-9a-f]{40}$/;
+/** Read the continuation binding from a claimed job's payload (pure). */
+export function readContinuationBinding(job) {
+    const payload = job.payload && typeof job.payload === "object" ? job.payload : null;
+    const raw = payload?.continuation;
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return null;
+    const block = raw;
+    if (block.retained_worktree !== true)
+        return null;
+    const receiptId = asString(block.receipt_id);
+    if (!receiptId)
+        return null;
+    const head = asString(block.bound_head_sha)?.toLowerCase() ?? null;
+    return {
+        receiptId,
+        branch: asString(block.branch) ?? null,
+        boundHeadSha: head !== null && FULL_SHA.test(head) ? head : null,
+    };
+}
+/**
+ * Prove the retained worktree's HEAD descends from the authorized head.
+ *
+ * Run BEFORE the WIP checkpoint: a checkpoint commits onto whatever HEAD is, so
+ * checking afterwards would already have written onto an unrelated history. A
+ * HEAD that equals the bound head, or has it as an ancestor (the worker's own
+ * later local commits), is accepted; anything else — including a bound head the
+ * worktree does not contain at all — is refused. No bound head (nothing was ever
+ * pushed) leaves only the branch check, which the caller has already made.
+ */
+export async function verifyContinuationHeadLineage(worktreePath, boundHeadSha, seams) {
+    if (boundHeadSha === null)
+        return;
+    const result = await seams.runCommand("git", ["merge-base", "--is-ancestor", boundHeadSha, "HEAD"], { cwd: worktreePath });
+    if (result.exitCode !== 0) {
+        throw new ExecutorNamedError(ContinuationLineageMismatch, `continuation worktree HEAD does not descend from the authorized head ${boundHeadSha.slice(0, 12)}`);
+    }
+}
+/**
+ * Locate and verify a continuation's RETAINED worktree, then checkpoint it.
+ *
+ * Order: resolve the existing worktree (never recreate) -> verify its branch ->
+ * verify its head lineage -> WIP-checkpoint dirty state. A missing worktree is a
+ * refusal ({@link ContinuationWorktreeMissing}), not a recreation from origin:
+ * recreation cannot restore unpushed commits, and continuing without them would
+ * silently discard exactly the work the continuation exists to carry. The
+ * checkpoint is recorded as lineage of the authorized head; it never adopts an
+ * arbitrary head. No destructive Git operation is ever issued.
+ */
+export async function prepareRetainedContinuationWorktree(job, binding, seams) {
+    const fields = readResumePayloadFields(job);
+    const expectedBranch = asString(job.expected_branch) ?? fields.expectedBranch ?? binding.branch ?? undefined;
+    if (!expectedBranch) {
+        throw new ExecutorNamedError("ResumeMissingExpectedBranch", `continuation job ${job.id} has no expected_branch`);
+    }
+    const worktreePath = await resolveExistingResumeWorktreePath(fields, expectedBranch, seams);
+    if (worktreePath === null) {
+        throw new ExecutorNamedError(ContinuationWorktreeMissing, `continuation for '${expectedBranch}' found no retained worktree; it is never recreated from origin because unpushed work cannot be recovered that way`);
+    }
+    await assertWorktreeOnBranch(seams.runCommand, worktreePath, expectedBranch);
+    await verifyContinuationHeadLineage(worktreePath, binding.boundHeadSha, seams);
+    const checkpoint = await autoCheckpointDirtyState(worktreePath, seams, CONTINUATION_WIP_COMMIT_MESSAGE);
+    return { worktreePath, branch: expectedBranch, checkpointed: checkpoint.committed };
+}
 /**
  * Orchestrate the resume pre-spawn protocol in the required order:
  *  1. read payload fields
@@ -165,14 +234,28 @@ export async function prepareResumeSpawn(job, options, seams) {
     // Fail loud on a missing/empty prompt template BEFORE any worktree resolution
     // or WIP-checkpoint commit — never spawn an empty-prompt worker.
     const promptTemplate = resolveResumePromptTemplate(job, fields);
+    // BAPI-1300: a resume dispatched as a parked-child continuation carries a
+    // binding and follows the retained-work protocol — never recreated from origin,
+    // and its head lineage is proven before the checkpoint. Every other resume job
+    // keeps the original protocol below unchanged.
+    const continuation = readContinuationBinding(job);
     let worktreePath = await resolveExistingResumeWorktreePath(fields, expectedBranch, seams);
     if (worktreePath === null) {
+        if (continuation !== null) {
+            throw new ExecutorNamedError(ContinuationWorktreeMissing, `continuation for '${expectedBranch}' found no retained worktree; it is never recreated from origin because unpushed work cannot be recovered that way`);
+        }
         worktreePath = await recreateResumeWorktreeFromPushedBranch(job, expectedBranch, seams);
     }
     // Branch verification BEFORE any local mutation — never checkpoint/commit on
     // the wrong branch.
     await assertWorktreeOnBranch(seams.runCommand, worktreePath, expectedBranch);
-    await autoCheckpointDirtyState(worktreePath, seams);
+    if (continuation !== null) {
+        await verifyContinuationHeadLineage(worktreePath, continuation.boundHeadSha, seams);
+        await autoCheckpointDirtyState(worktreePath, seams, CONTINUATION_WIP_COMMIT_MESSAGE);
+    }
+    else {
+        await autoCheckpointDirtyState(worktreePath, seams);
+    }
     const gitLog = await readResumeGitLog(worktreePath, baseBranch, seams);
     const gitDiff = await readResumeGitDiff(worktreePath, baseBranch, seams);
     const prompt = fillResumePromptPlaceholders(promptTemplate, gitLog, gitDiff);

package/build/executor/runner.js

@@ -10,10 +10,14 @@ import { collectExecutorPreflight, buildClaimManifest, createDenyProbeCache, } f
 import { runClaimedJob, runIntegrationCorrectionSpawn } from "./job-runner.js";
 import { appendToActiveJobLogs } from "./job-log-registry.js";
 import { createLiveWorkerRegistry, } from "./live-worker-registry.js";
+import os from "node:os";
 import { sweepExecutorWorktrees } from "./worktree-gc.js";
+import { createMacProcessInspector, hostIdentityDigest, recoverInterruptedOwnership, } from "./process-containment.js";
+import { resolveExecutorStateDir } from "./job-log-registry.js";
 import { INTEGRATION_ACTION_PROTOCOL_VERSION, } from "./types.js";
 import { buildIntegrationCorrectionJob, createIntegrationCorrectionLeaseAdapter, runIntegrationAction, } from "./integration-job.js";
 import { validateBranchName } from "../base-ref.js";
+import { isTerminalEpicRunStatus } from "../epic-run-status.js";
 import { ensureEpicIntegrationPullRequest, createProductionEpicIntegrationGhRunner, formatEpicIntegrationPullRequestOutcome, EPIC_BRANCH_PREFIX, } from "../epic-integration-pr.js";
 /**
  * Signals that request a graceful executor shutdown (BAPI-828).
@@ -96,6 +100,16 @@ export function formatProcessHeartbeatFailureDiagnostic() {
 export function formatProcessHeartbeatRecoveredDiagnostic() {
     return "executor: process-heartbeat delivery has recovered.";
 }
+/**
+ * BAPI-1279 — the diagnostic for a failed run-state read under
+ * `--exit-when-run-terminal`. Fixed text plus a closed reason token: no body,
+ * no URL, no credential. The executor keeps claiming; a failed read never
+ * causes an exit.
+ */
+export function formatRunTerminalReadFailureDiagnostic(reason) {
+    return (`executor: could not read the scoped run's state (reason=${reason}); ` +
+        "staying up and claiming until it can be read.");
+}
 /** Seconds a correction worker may run: what the action deadline leaves, less a margin. */
 function correctionTimeoutSeconds(deadlineAt, nowMs) {
     const deadline = Date.parse(deadlineAt);
@@ -103,6 +117,23 @@ function correctionTimeoutSeconds(deadlineAt, nowMs) {
         return 60;
     return Math.max(60, Math.floor((deadline - nowMs) / 1000) - 60);
 }
+/**
+ * BAPI-1301: the read/remove-only record filesystem startup recovery uses, built
+ * from the executor's injected deps. Without a `readdir` seam there is nothing
+ * to list, so recovery is a no-op; recovery never writes a record.
+ */
+function recoveryRecordFs(deps) {
+    const refuseWrite = async () => {
+        throw new Error("startup ownership recovery never writes records");
+    };
+    return {
+        mkdir: refuseWrite,
+        writeFile: refuseWrite,
+        readFile: (filePath) => deps.readFile(filePath),
+        readdir: deps.readdir ? (dirPath) => deps.readdir(dirPath) : async () => [],
+        removeFile: deps.removeFile ? (filePath) => deps.removeFile(filePath) : async () => { },
+    };
+}
 /**
  * Run the executor loop. Returns 0 on the `once` path (a single cycle drained);
  * in continuous mode it does not return (the process is long-lived).
@@ -121,6 +152,40 @@ export async function runExecutor(options, deps, httpClient, seams = {}) {
             statMtimeMs: deps.statMtimeMs ?? (async () => null),
             platform: deps.platform,
         }));
+    // BAPI-1301 — before the first claim, inspect ownership records left by a
+    // previous executor process on this host. Each record holds the real per-job
+    // token, so the sweep can only ever reach processes that job tagged. The
+    // SERVER still parks such a job as `cleanup_unconfirmed` (it cannot know this
+    // inspection happened); the verdict here is logged for the operator.
+    const recoverOwnedProcesses = seams.recoverOwnedProcesses ??
+        (async () => {
+            const results = await recoverInterruptedOwnership({
+                stateDir: resolveExecutorStateDir({ env: deps.env, tmpdir: () => os.tmpdir(), platform: deps.platform }),
+                inspector: createMacProcessInspector({
+                    runCommand: deps.runCommand,
+                    selfPid: process.pid,
+                    platform: deps.platform,
+                }),
+                deps: { now: deps.now, sleep: deps.sleep, log: deps.errorLog },
+                // Recovery only lists, reads and removes records, so it goes through the
+                // executor's own filesystem seams: an embedded caller or a test with
+                // in-memory deps never touches the real state directory.
+                fsDeps: recoveryRecordFs(deps),
+                deadlineMs: 30_000,
+                hostDigest: hostIdentityDigest(os.hostname()),
+                selfPid: process.pid,
+            });
+            for (const r of results) {
+                deps.errorLog(`[executor] startup ownership inspection: job ${r.jobId} cleanup ${r.verdict.verdict} ` +
+                    `(survivors=${r.verdict.survivors})`);
+            }
+        });
+    try {
+        await recoverOwnedProcesses();
+    }
+    catch (err) {
+        deps.errorLog(`[executor] startup ownership inspection failed (non-fatal): ${err instanceof Error ? err.message.slice(0, 200) : "unknown error"}`);
+    }
     const active = new Map();
     // BAPI-1259 — integration actions share `active` (and therefore the same
     // capacity budget and shutdown drain) with ordinary jobs, keyed by negative
@@ -293,6 +358,50 @@ export async function runExecutor(options, deps, httpClient, seams = {}) {
             deps.errorLog("executor: epic wind-down observation failed unexpectedly (advisory only).");
         }
     };
+    // BAPI-1279 — `--exit-when-run-terminal`. Only ever true for a process scoped
+    // to exactly one run; the CLI refuses the flag otherwise, and this re-check
+    // keeps an embedded caller from arming it on an ambiguous scope.
+    const exitWhenRunTerminal = options.exitWhenRunTerminal === true && observedEpicRunId !== null;
+    let runTerminal = false;
+    // The last failure reason reported, so a long outage logs once per change
+    // rather than once per poll.
+    let lastRunStateFailure = null;
+    /**
+     * Is the scoped run finished? Called only between claim cycles while this
+     * process holds NO job. The wind-down observer runs FIRST, so a run that just
+     * reached `done` still gets its integration-PR ready request before the
+     * executor retires. Any failed read returns `false`: an executor that cannot
+     * see its run keeps claiming rather than guessing it is done.
+     */
+    const scopedRunIsTerminal = async () => {
+        if (!exitWhenRunTerminal || observedEpicRunId === null)
+            return false;
+        await observeEpicRunCompletion();
+        const readState = httpClient.readEpicRunState;
+        if (typeof readState !== "function")
+            return false;
+        let reason = null;
+        let terminal = false;
+        try {
+            const result = await readState.call(httpClient, observedEpicRunId, options.repoName);
+            if (result.ok)
+                terminal = isTerminalEpicRunStatus(result.state.status);
+            else
+                reason = result.reason;
+        }
+        catch {
+            reason = "unexpected";
+        }
+        if (reason !== null) {
+            if (reason !== lastRunStateFailure) {
+                deps.errorLog(formatRunTerminalReadFailureDiagnostic(reason));
+            }
+            lastRunStateFailure = reason;
+            return false;
+        }
+        lastRunStateFailure = null;
+        return terminal;
+    };
     // BAPI-722: ONE deny-probe cache per `runExecutor` invocation, created OUTSIDE
     // the claim loop below — that scope is the whole feature. A cache created inside
     // the loop would be discarded every cycle and re-probe exactly as before; a
@@ -461,6 +570,24 @@ export async function runExecutor(options, deps, httpClient, seams = {}) {
             component: "executor",
             instance_id: options.executorId,
             repo_names: repoNames,
+            // BAPI-1279 — the claim MODE, so the server can report whether a durable
+            // repo-wide executor covers the repository.
+            //
+            // BAPI-1282 — plus the full run id, but ONLY for an executor scoped to
+            // exactly one run. This deliberately reverses BAPI-1279's "never the run
+            // ids": the server needs the complete id to check, per repository, that
+            // the run this executor served is `done`/`abandoned`, so a cleanly retired
+            // executor's stale row stops reading as a lost executor — even when this
+            // process never reaches the server again. The id is one bounded, non-secret,
+            // server-minted UUID the operator already passed as `--epic-run-id`. The
+            // 8-character prefix inside `drive-epic-<runid8>-<host>` is not a substitute:
+            // it is ambiguous, and absent for a hand-chosen `--executor-id`. A
+            // multi-run or repo-wide executor publishes no binding.
+            metadata: options.epicRunIds === undefined
+                ? { claim_mode: "repo_wide" }
+                : observedEpicRunId !== null
+                    ? { claim_mode: "scoped", epic_run_id: observedEpicRunId }
+                    : { claim_mode: "scoped" },
         };
         // Suppression state: one message per CHANGE of delivery state, so a long
         // outage produces one line rather than one per minute.
@@ -758,6 +885,16 @@ export async function runExecutor(options, deps, httpClient, seams = {}) {
                     await maybeSweepWorktrees();
                 }
             }
+            // BAPI-1279 — retire once the scoped run is finished and nothing is held.
+            // Checked whether or not preflight passed: an executor that preflight
+            // keeps refusing still holds a sleep assertion and a record, and must not
+            // outlive its run. `break` takes the SAME path a `--once` pass does:
+            // drain, stop the heartbeat loop, unsubscribe, exit 0.
+            if (!shutdownRequested && active.size === 0 && (await scopedRunIsTerminal())) {
+                runTerminal = true;
+                deps.errorLog(`executor: run ${observedEpicRunId} is finished and no job is held; exiting.`);
+                break;
+            }
             if (options.once || shutdownRequested)
                 break;
             // Sample the clock immediately around the ACTUAL sleep, so the measured gap
@@ -807,6 +944,14 @@ export async function runExecutor(options, deps, httpClient, seams = {}) {
             }
         }
     }
+    if (runTerminal && observedEpicRunId !== null && seams.onRunTerminal) {
+        try {
+            await seams.onRunTerminal(observedEpicRunId);
+        }
+        catch {
+            /* record cleanup must never change a clean terminal exit */
+        }
+    }
     // A graceful signal shutdown is a NORMAL executor exit, not an error: the run did
     // exactly what it was asked to do. A distinct nonzero code here would make every
     // deliberate operator stop look like a crash to launchd, systemd, and the CLI

package/build/executor/test-declaration.js

@@ -0,0 +1,20 @@
+/**
+ * Test support (BAPI-1302): build a required-verification declaration exactly as
+ * the server's `declaration_from_plan_node` seals it, so executor tests exercise
+ * the real strict reader rather than a hand-written shape.
+ */
+import { computeDeclarationDigest, declaredCommandIdentity } from "./completion-supervision.js";
+export function sealDeclaration(commands, provenance = commands.length > 0 ? "declared" : "absent") {
+    const body = {
+        schema_version: 1,
+        provenance,
+        plan_version: 7,
+        plan_hash: "a".repeat(64),
+        commands: commands.map((c, position) => ({
+            identity: declaredCommandIdentity(position, c),
+            position,
+            ...c,
+        })),
+    };
+    return { ...body, digest: computeDeclarationDigest(body) };
+}

package/build/executor/types.js

@@ -42,6 +42,18 @@ export const EXECUTOR_CLASSIFICATION_VALUES = [
     "no_progress",
     "lease_expired",
 ];
+/**
+ * BAPI-1311 — the capability an executor declares when it can run a FOCUSED
+ * merge-stage `rebase`: validate `payload.focused_rebase` before any worker
+ * effect, use the server-rendered prompt verbatim, and supervise the post-push
+ * mergeability/required-check wait under the job's own claim and deadline.
+ * Mirrors `FOCUSED_REBASE_CAPABILITY` in
+ * `src/python/llms/executor_completion_contract.py`. Independent of completion
+ * evidence: `rebase` is not a covered job type.
+ */
+export const FOCUSED_REBASE_CAPABILITY = "focused_rebase.v1";
+/** The focused context version; the same string as the capability on purpose. */
+export const FOCUSED_REBASE_CONTEXT_VERSION = FOCUSED_REBASE_CAPABILITY;
 /**
  * BAPI-1258 — the terminal provider-capacity protocol contract, mirroring
  * `src/python/llms/executor_capacity_contract.py`. Closed values: an executor

package/build/executor/worker-command.js

@@ -17,13 +17,21 @@
  * distinct from the argv vocabulary is what stops a future flag rename in one
  * agent's CLI from becoming an operator-visible policy break across all of them.
  */
-import { ExecutorNamedError } from "./job-errors.js";
+import { CiFixContext, ExecutorNamedError } from "./job-errors.js";
 import { isRecoveryJobType } from "./job-types.js";
+/**
+ * BAPI-1296: `ci_fix` is the one recovery job with a FOCUSED prompt route. It
+ * renders its server-authored `payload.prompt_spec` (the dispatched failing and
+ * missing checks) in `job-runner.ts`, and is never given the full recipe.
+ */
+export const CI_FIX_JOB_TYPE = "ci_fix";
 /**
  * Resolve the worker prompt for the explicit-prompt and legacy synthesis paths.
  * Uses an explicit non-empty `payload.prompt` verbatim; otherwise, for
- * `implement` and the recovery jobs, builds the conservative
- * `/implement-ticket <ticket_key> --auto` prompt.
+ * `implement` and the `remediate`/`rebase` recovery jobs, builds the
+ * conservative `/implement-ticket <ticket_key> --auto` prompt. `ci_fix` never
+ * resolves here (BAPI-1296): it is refused if it carries an explicit prompt and
+ * otherwise falls through to its focused prompt-spec route.
  *
  * Structured `payload.prompt_spec` rendering is NOT done here: it needs the
  * prepared worktree/git state, so `job-runner.ts` renders it in the prepared-spawn
@@ -40,19 +48,46 @@ import { isRecoveryJobType } from "./job-types.js";
 /**
  * True for the job types that synthesize `/implement-ticket <KEY> --auto` when no
  * explicit `payload.prompt` is present: the first-pass `implement` plus the
- * recovery jobs (`remediate`/`ci_fix`/`rebase`), which re-enter the SAME
- * correction loop on the ticket's existing branch/PR. Recovery classification is
- * shared with dispatch and worktree reuse via `isRecoveryJobType` (`job-types.ts`)
- * so eligibility cannot drift. Verdict jobs (`spec_review`/`smoke`) are NOT here —
+ * `remediate`/`rebase` recovery jobs, which re-enter the SAME correction loop on
+ * the ticket's existing branch/PR. Recovery classification is shared with
+ * dispatch and worktree reuse via `isRecoveryJobType` (`job-types.ts`) so
+ * eligibility cannot drift. Verdict jobs (`spec_review`/`smoke`) are NOT here —
  * they carry an explicit `payload.prompt` and write a fixed-path artifact (T6/T5b).
+ *
+ * BAPI-1296: `ci_fix` is EXCLUDED even though it stays a recovery job (branch
+ * reuse, worktree lock, and finalization policy are unchanged). Re-entering the
+ * whole recipe to repair a dispatched check repeated planning and implementation
+ * the server had already finished; `ci_fix` now renders its focused prompt spec
+ * or is refused by name, and never falls back to this synthesis.
  */
-function synthesizesImplementPrompt(jobType) {
+export function synthesizesImplementPrompt(jobType) {
+    if (jobType === CI_FIX_JOB_TYPE)
+        return false;
     return jobType === "implement" || isRecoveryJobType(jobType);
 }
 export function resolveExecutorPrompt(job) {
     const payload = job.payload && typeof job.payload === "object"
         ? job.payload
         : {};
+    // BAPI-1296: `ci_fix` is decided FIRST, ahead of both explicit-prompt
+    // precedence and synthesis. An explicit prompt on a ci_fix job — including an
+    // in-flight legacy `/implement-ticket <KEY> --auto` — is refused by name rather
+    // than run, so an old full-recipe prompt cannot silently defeat the focused
+    // route. Otherwise the non-ok result tells `prepareSpawn` to take the focused
+    // prompt-spec route. The message never echoes the prompt text.
+    if (job.job_type === CI_FIX_JOB_TYPE) {
+        if (typeof payload.prompt === "string" && payload.prompt.trim().length > 0) {
+            return {
+                ok: false,
+                errorKind: CiFixContext,
+                error: "ci_fix job refused before worker effects (reason=explicit_prompt_unsupported)",
+            };
+        }
+        return {
+            ok: false,
+            error: "ci_fix renders its focused payload.prompt_spec; no prompt is synthesized",
+        };
+    }
     // An explicit prompt wins and is returned VERBATIM (un-trimmed), but a
     // whitespace-only string is not a usable worker instruction — treat it as
     // absent so a recovery/implement job still falls back to the synthesized
@@ -62,11 +97,12 @@ export function resolveExecutorPrompt(job) {
         return { ok: true, prompt: explicit };
     }
     // `/implement-ticket <KEY> --auto` is the full correction engine, not just a
-    // first-pass implementer: its post-PR loop owns CI-failure correction, review-
-    // change addressing, and merge-conflict resolution (see .claude/commands/
-    // implement-ticket.md "Clean session exit"). So the recovery jobs that operate
-    // on the ticket's existing branch/PR — `remediate`/`ci_fix`/`rebase` — resume
-    // by RE-ENTERING THE COMPLETE RECIPE from step 1, not a distinct resume path.
+    // first-pass implementer: its post-PR loop owns review-change addressing and
+    // merge-conflict resolution (see .claude/commands/implement-ticket.md "Clean
+    // session exit"). So the recovery jobs that operate on the ticket's existing
+    // branch/PR — `remediate`/`rebase` — resume by RE-ENTERING THE COMPLETE RECIPE
+    // from step 1, not a distinct resume path. (`ci_fix` left this path in
+    // BAPI-1296 and returned above: CI failures are repaired by a focused worker.)
     // That re-entry is safe (BAPI-746), backed by re-entry handling already
     // present in three of the recipe's own steps, not a new assumption: plan
     // generation is idempotent because the server reuses a fresh existing plan