@bridge_gpt/mcp-server 0.2.60 → 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

@@ -7,11 +7,17 @@
  * after all active jobs finish. Depends on NO v1 conductor event/ledger module.
  */
 import { collectExecutorPreflight, buildClaimManifest, createDenyProbeCache, } from "./preflight.js";
-import { runClaimedJob } from "./job-runner.js";
+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).
@@ -94,6 +100,40 @@ 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);
+    if (!Number.isFinite(deadline))
+        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).
@@ -112,7 +152,48 @@ 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
+    // numbers so they can never collide with a server job id.
+    let integrationSeq = 0;
+    // Set once when the server says it has no integration-action route (an older
+    // deployment), so the executor stops asking rather than logging every poll.
+    let integrationActionsUnsupported = false;
     // BAPI-794 — process-local cross-run claim observability. Retains only the
     // last successfully claimed job's `epic_run_id` (never job payloads,
     // credentials, or arguments) so an unintended repo-wide move between epic
@@ -277,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
@@ -445,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.
@@ -536,6 +679,85 @@ export async function runExecutor(options, deps, httpClient, seams = {}) {
         })();
         active.set(job.id, promise);
     }
+    const runOneIntegrationAction = seams.runIntegrationAction ??
+        ((action) => runIntegrationAction(action, seams.integrationActions, {
+            env: deps.env,
+            runCommand: deps.runCommand,
+            sleep: deps.sleep,
+            errorLog: deps.errorLog,
+            cwd: deps.cwd,
+        }, {
+            // A correction reuses the executor's ONE locked spawn path: the same
+            // worktree lock, containment, and supervision every worker gets.
+            runCorrection: async (claimed, driver, heartbeat) => {
+                const adapter = createIntegrationCorrectionLeaseAdapter(heartbeat);
+                const job = buildIntegrationCorrectionJob(claimed, correctionTimeoutSeconds(claimed.deadline_at, deps.now()));
+                await runIntegrationCorrectionSpawn(job, adapter.client, options, deps, driver, undefined, control);
+                return adapter.captured();
+            },
+        }));
+    function dispatchIntegrationAction(action) {
+        const key = --integrationSeq;
+        const promise = (async () => {
+            try {
+                await runOneIntegrationAction(action);
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                deps.errorLog(`executor integration action crashed: ${message.slice(0, 200)}`);
+            }
+            finally {
+                active.delete(key);
+            }
+        })();
+        active.set(key, promise);
+    }
+    /**
+     * Claim durable integration actions into whatever capacity is left
+     * (BAPI-1259). The claim scope is the executor's own: `--epic-run-id` runs,
+     * or the whole repository for `--repo-wide`. The action driver chooses no
+     * next ticket and no gate — it performs one action and reports facts.
+     */
+    async function claimIntegrationActions() {
+        const client = seams.integrationActions;
+        if (!client || integrationActionsUnsupported)
+            return;
+        for (const repoName of options.repos) {
+            while (!shutdownRequested && options.maxConcurrent - active.size > 0) {
+                const result = await client.claim({
+                    protocol_version: INTEGRATION_ACTION_PROTOCOL_VERSION,
+                    repo_name: repoName,
+                    executor_id: options.executorId,
+                    ...(options.epicRunIds !== undefined
+                        ? { epic_run_ids: options.epicRunIds }
+                        : { repo_wide: true }),
+                });
+                if (result.kind === "claimed") {
+                    dispatchIntegrationAction(result.action);
+                    continue;
+                }
+                if (result.kind === "fatal") {
+                    if (result.authHttpStatus === 401 || result.authHttpStatus === 403) {
+                        control.reportAuthFatal?.({
+                            repoName,
+                            category: "claim",
+                            httpStatus: result.authHttpStatus,
+                        });
+                    }
+                    else {
+                        integrationActionsUnsupported = true;
+                        deps.errorLog(`executor: integration actions unavailable on this server (${result.error}); ` +
+                            "not claiming them again in this process");
+                    }
+                    return;
+                }
+                if (result.kind === "retryable") {
+                    deps.errorLog(`executor integration action claim retryable: ${result.error}`);
+                }
+                break;
+            }
+        }
+    }
     // Handlers go on BEFORE preflight and before the first claim (BAPI-828).
     // Preflight can take seconds and the first claim can spawn a worker immediately
     // after it, so registering any later would leave a real window in which a
@@ -654,10 +876,25 @@ export async function runExecutor(options, deps, httpClient, seams = {}) {
                 // cycle's claim loop (a claim-time auth-fatal is the case that matters —
                 // it can flip `shutdownRequested` while `active.size` is still 0). No
                 // worktree-mutating sweep may run once the auth-fatal flag is set.
+                // BAPI-1259 — integration actions take whatever capacity ordinary jobs
+                // left this cycle, under the same shutdown gate.
+                if (!shutdownRequested) {
+                    await claimIntegrationActions();
+                }
                 if (!shutdownRequested) {
                     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
@@ -707,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) };
+}