@bridge_gpt/mcp-server 0.2.69 → 0.2.70

package/build/executor/delivery-outcome.js

@@ -0,0 +1,179 @@
+/**
+ * BAPI-1426 — the server-confirmed ticket delivery outcome an outer worker reads
+ * before it finalizes.
+ *
+ * A managed ticket (one with an active delivery binding on the server) may end
+ * an attempt on purpose without a pull request: its required work is blocked, a
+ * required check failed, or its evidence is missing or stale. The worker then
+ * pushes a checkpoint and stops. Finalization must not report that as an
+ * accidental missing-PR failure, and must never report it as success either.
+ *
+ * Only the SERVER can say a ticket is managed and what its outcome is. This
+ * module makes two bounded, read-only GETs through the executor's own fetch
+ * boundary and the shared repo-scoped credential resolver:
+ *
+ *   1. `GET /ticket-delivery/executions/recover` — is there an active attempt for
+ *      this ticket and branch? A 404 means "not managed" (legacy behavior).
+ *   2. `GET /ticket-delivery/executions/{attempt_id}/readiness?boundary=publish`
+ *      — the server's current decision for that attempt.
+ *
+ * It never throws. Any failure is reported as `unavailable`, which finalization
+ * treats as "no server confirmation" and so falls through to its existing
+ * checks unchanged. An outage is never turned into a failed check. Nothing from
+ * the response is kept beyond closed tokens, a full SHA, an identifier, integer
+ * step ids, and a PR number; free text from evidence never reaches a message.
+ */
+import { buildConductorVcsUrl, resolveConductorBridgeApiAccess, } from "../conductor/bridge-api-client.js";
+/** Server readiness outcomes (mirror of `ticket_delivery_readiness.py`). */
+export const DELIVERY_OUTCOMES = [
+    "blocked",
+    "verification_failed",
+    "evidence_missing_or_stale",
+    "awaiting_post_pr",
+    "complete",
+];
+/** Default bound for each of the two reads. */
+export const DELIVERY_OUTCOME_READ_TIMEOUT_MS = 15_000;
+const FULL_SHA_RE = /^[0-9a-f]{40}$/;
+const ATTEMPT_ID_RE = /^[A-Za-z0-9._:-]{1,128}$/;
+const TOKEN_RE = /^[a-z][a-z0-9_]{0,63}$/;
+const MAX_BLOCKERS = 16;
+const UNAVAILABLE_UNKNOWN = { bound: "unknown", unavailable: true };
+const UNAVAILABLE_BOUND = { bound: true, unavailable: true };
+/** One bounded GET. Never throws; never reads the body of a failed response. */
+async function boundedGet(url, headers, deps) {
+    const timeoutMs = Math.max(1, deps.timeoutMs ?? DELIVERY_OUTCOME_READ_TIMEOUT_MS);
+    const setTimer = deps.setTimer ?? ((cb, ms) => setTimeout(cb, ms));
+    const clearTimer = (deps.clearTimer ?? ((h) => clearTimeout(h)));
+    let handle;
+    const timeout = new Promise((resolve) => {
+        handle = setTimer(() => resolve({ kind: "failed" }), timeoutMs);
+    });
+    const read = (async () => {
+        try {
+            const res = await deps.fetch(url, { method: "GET", headers });
+            if (res.status === 404)
+                return { kind: "not_found" };
+            if (res.status < 200 || res.status >= 300)
+                return { kind: "failed" };
+            const text = await res.text();
+            return { kind: "ok", body: JSON.parse(text) };
+        }
+        catch {
+            return { kind: "failed" };
+        }
+    })();
+    try {
+        return await Promise.race([read, timeout]);
+    }
+    finally {
+        if (handle !== undefined)
+            clearTimer(handle);
+    }
+}
+function asRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : null;
+}
+/** Reduce the server's blocker list to closed kind tokens and integer step ids. */
+export function summarizeDeliveryBlockers(value) {
+    if (!Array.isArray(value))
+        return [];
+    const out = [];
+    for (const entry of value) {
+        if (out.length >= MAX_BLOCKERS)
+            break;
+        const rec = asRecord(entry);
+        if (!rec)
+            continue;
+        const kind = typeof rec.kind === "string" && TOKEN_RE.test(rec.kind) ? rec.kind : "unrecognized";
+        const step = rec.step_id;
+        out.push(typeof step === "number" && Number.isInteger(step) && step >= 0 && step <= 1_000_000
+            ? { kind, step_id: step }
+            : { kind });
+    }
+    return out;
+}
+function isDeliveryOutcomeToken(value) {
+    return typeof value === "string" && DELIVERY_OUTCOMES.includes(value);
+}
+/**
+ * BAPI-1473: does this server decision show a renewed attempt at `headSha` whose
+ * only outstanding work is `remote_ci` deferrals? Requires a bound, available
+ * `awaiting_post_pr` decision, the server's remote-CI-only flag, and an OBSERVED
+ * head equal to `headSha` (never the preserved fallback). Anything else is false.
+ */
+export function deliveryRenewedWithRemoteCiDeferrals(outcome, headSha) {
+    if (!outcome || outcome.bound !== true || outcome.unavailable === true)
+        return false;
+    if (outcome.outcome !== "awaiting_post_pr" || outcome.postPrRemoteCiOnly !== true)
+        return false;
+    const head = headSha.trim().toLowerCase();
+    return FULL_SHA_RE.test(head) && outcome.observedHeadSha === head;
+}
+/**
+ * Read the server-confirmed delivery outcome for `job` on `branch`. Never throws.
+ * Returns `{ bound: false }` when the job has no ticket or branch, or when the
+ * server reports no active attempt (404).
+ */
+export async function fetchServerDeliveryOutcome(job, branch, deps) {
+    try {
+        const ticket = typeof job.ticket_key === "string" ? job.ticket_key.trim() : "";
+        const sourceBranch = typeof branch === "string" ? branch.trim() : "";
+        if (!ticket || !sourceBranch || !job.repo_name)
+            return { bound: false };
+        const resolve = deps.resolveAccess ??
+            ((repoName) => resolveConductorBridgeApiAccess({ ...(deps.accessDeps ?? {}), repoName }));
+        const access = await resolve(job.repo_name);
+        if (!access.ok)
+            return UNAVAILABLE_UNKNOWN;
+        const headers = { "X-API-Key": access.access.apiKey };
+        const recoverUrl = new URL(buildConductorVcsUrl(access.access.baseUrl, "/ticket-delivery/executions/recover"));
+        recoverUrl.searchParams.set("repo_name", job.repo_name);
+        recoverUrl.searchParams.set("ticket_number", ticket);
+        recoverUrl.searchParams.set("source_branch", sourceBranch);
+        const recovered = await boundedGet(recoverUrl.toString(), headers, deps);
+        if (recovered.kind === "not_found")
+            return { bound: false };
+        if (recovered.kind !== "ok")
+            return UNAVAILABLE_UNKNOWN;
+        const binding = asRecord(asRecord(recovered.body)?.binding);
+        const attemptId = binding?.attempt_id;
+        if (typeof attemptId !== "string" || !ATTEMPT_ID_RE.test(attemptId))
+            return UNAVAILABLE_BOUND;
+        const readinessUrl = new URL(buildConductorVcsUrl(access.access.baseUrl, `/ticket-delivery/executions/${encodeURIComponent(attemptId)}/readiness`));
+        readinessUrl.searchParams.set("repo_name", job.repo_name);
+        readinessUrl.searchParams.set("boundary", "publish");
+        const read = await boundedGet(readinessUrl.toString(), headers, deps);
+        if (read.kind !== "ok")
+            return UNAVAILABLE_BOUND;
+        const body = asRecord(read.body);
+        const readiness = asRecord(body?.readiness);
+        if (!readiness || !isDeliveryOutcomeToken(readiness.outcome))
+            return UNAVAILABLE_BOUND;
+        // `preserved_head_sha` is the observed head when the server observed one, but
+        // falls back to the binding's stored head otherwise, so it is NOT proof that
+        // the decision applies to the current head. `observed_head_sha` is.
+        const rawHead = typeof readiness.preserved_head_sha === "string" ? readiness.preserved_head_sha.trim().toLowerCase() : "";
+        const snapshot = asRecord(readiness.snapshot);
+        const rawObserved = typeof snapshot?.observed_head_sha === "string" ? snapshot.observed_head_sha.trim().toLowerCase() : "";
+        const freshBinding = asRecord(body?.binding) ?? binding;
+        const rawPr = freshBinding?.pr_number;
+        return {
+            bound: true,
+            attemptId,
+            outcome: readiness.outcome,
+            preservedHeadSha: FULL_SHA_RE.test(rawHead) ? rawHead : null,
+            blockers: summarizeDeliveryBlockers(readiness.blockers),
+            prNumber: typeof rawPr === "number" && Number.isInteger(rawPr) && rawPr > 0 ? rawPr : null,
+            // Additive (BAPI-1473): present only when the server supplied a usable value,
+            // so a response without them parses exactly as it did before.
+            ...(FULL_SHA_RE.test(rawObserved) ? { observedHeadSha: rawObserved } : {}),
+            ...(readiness.post_pr_remote_ci_only === true ? { postPrRemoteCiOnly: true } : {}),
+        };
+    }
+    catch {
+        return UNAVAILABLE_UNKNOWN;
+    }
+}

package/build/executor/deps.js

@@ -230,5 +230,8 @@ export function createDefaultExecutorDeps() {
             argv1: process.argv[1],
             fileExists: existsSync,
         }),
+        // BAPI-1479: `workerResources` is deliberately NOT built here. Integration
+        // tests spread these real deps, and a real provisioning seam would reach the
+        // host PostgreSQL from them. The executor CLI attaches it (`cli.ts`).
     };
 }

package/build/executor/env.js

@@ -48,6 +48,21 @@
  * value already in the environment WINS over a `.env` entry, which is what makes
  * the sentinel effective even if a file ever survived the strip.
  *
+ * BAPI-1479: "secret-free" means no AMBIENT credential reaches a worker. It does
+ * not mean the worker carries no key whose name looks secret. Two kinds of value
+ * are injected by the executor from its own constants and explicit job state,
+ * after the allowlist has filtered the parent environment:
+ *
+ *  - `CI_WORKER_ENV_CONSTANTS` — CI's throwaway, non-secret test values (the four
+ *    `BGPT_*` keys and `ENVIRONMENT=LOCAL`), so a worker can import `main` the way
+ *    CI does. The allowlist still refuses these names from `parentEnv`.
+ *  - a DISPOSABLE job database (`ExecutorWorkerEnvOptions.workerDatabase`), which
+ *    the job runner provisions per job and drops afterwards. When it is present
+ *    the four sentinel keys name that database instead and the loopback role keys
+ *    (including an empty `POSTGRES_PASSWORD`) are added; when it is absent the
+ *    sentinel stays exactly as BAPI-1019 set it. The worker role is refused on
+ *    `bridgeapi`, so the job database is never the operational one.
+ *
  * The `mcp-invoke` shim (a separate process) resolves `BAPI_API_KEY` itself at
  * call time from the operator's real user-scoped credential store, exactly as it
  * did before BAPI-731, so this worker environment never carries it. The model is
@@ -57,7 +72,9 @@
 import { PR_BASE_BRANCH_ENV_VAR, WORKER_BRANCH_ENV_VAR } from "../pr-base-contract.js";
 import { DECLARED_TOUCHED_FILES_ENV, normalizeDeclaredTouchedFiles, } from "../conductor/file-scope-guard.js";
 import { INDEX_SCOPE_ENV_VAR, validateOptionalIndexScope } from "../index-scope-contract.js";
+import { delimiter as PLATFORM_PATH_DELIMITER } from "node:path";
 import { EPIC_IMPLEMENTER_ENV_PREFIX, EPIC_IMPLEMENTER_NODE_PATH_ENV, LEGACY_EPIC_IMPLEMENTER_ENV_PREFIX, LEGACY_EPIC_IMPLEMENTER_NODE_PATH_ENV, } from "../epic-implementer-env.js";
+import { buildWorkerDatabaseEnv } from "./worker-database-target.js";
 /** Non-secret operational keys forwarded to the worker when present. */
 const ALLOWED_ENV_KEYS = [
     "PATH",
@@ -103,6 +120,29 @@ export const WORKER_SENTINEL_DATABASE_ENV_KEYS = [
     "POSTGRES_DB",
     "PGDATABASE",
 ];
+/**
+ * CI's non-secret test values, injected into EVERY worker environment (BAPI-1479).
+ *
+ * These are the exact literals the Python lane of
+ * `.github/workflows/epic-implementer-ci.yml` sets. They are throwaway CI values,
+ * deliberately NOT secrets, and they encrypt nothing real — `BGPT_ENCRYPTION_KEY`
+ * only has to be a syntactically valid Fernet key so crypto paths import.
+ * Without them a worker cannot run any test that imports `main`
+ * (`KeyError: BGPT_SESSION_SECRET`), so it could not run the checks CI runs.
+ *
+ * Executor-INJECTED, never inherited: the builder assigns them after the
+ * allowlist loop from this map, so an operator's ambient value (possibly a real
+ * secret) can never reach a worker under these names. The allowlist is untouched
+ * — `isExecutorEnvKeyAllowed("BGPT_SESSION_SECRET")` is still `false`, and none
+ * of these keys is in `ALLOWED_ENV_KEYS`.
+ */
+export const CI_WORKER_ENV_CONSTANTS = Object.freeze({
+    BGPT_ENCRYPTION_KEY: "YmFwaTYxMC1jaS10ZXN0LWtleS1ub3QtYS1zZWNyZXQ=",
+    BGPT_DEMO_SECRET: "test-demo-secret",
+    BGPT_SESSION_SECRET: "test-session-secret",
+    BGPT_INVITE_SECRET: "test-invite-secret",
+    ENVIRONMENT: "LOCAL",
+});
 /** Substrings that mark a key as secret-bearing (case-insensitive). */
 const SECRET_NAME_FRAGMENTS = ["TOKEN", "SECRET", "PASSWORD", "API_KEY"];
 /**
@@ -148,6 +188,16 @@ export const EXPLICIT_DENY_KEYS = [
     "OPENAI_API_KEY",
     "GITHUB_TOKEN",
     "GH_TOKEN",
+    // BAPI-1452: the canonical local merge credential. The executor PROCESS keeps
+    // it — the local merge job authenticates with it — so it is deliberately NOT
+    // on `EXECUTOR_PROCESS_GITHUB_CREDENTIAL_DENY_KEYS` below. A worker never
+    // needs it, and denying it here keeps a merge-capable token out of every
+    // agent session even if a future edit widens the allowlist.
+    "GITHUB_MERGE_TOKEN",
+    // BAPI-1461: its deprecated alias and the machine-user key, denied explicitly
+    // for the same reason. The executor process keeps both; a worker never does.
+    "BAPI_LOCAL_MERGE_TOKEN",
+    "BAPI_MACHINE_MERGE_TOKEN",
     "CLAUDE_CONFIG_DIR",
     "XDG_CONFIG_HOME",
     // BAPI-844: the index-scope declaration follows the BAPI_BASE_BRANCH rule —
@@ -288,6 +338,27 @@ export function buildExecutorBaseWorkerEnv(parentEnv, options = {}) {
     env.POSTGRES_DATABASE = WORKER_SENTINEL_DATABASE_NAME;
     env.POSTGRES_DB = WORKER_SENTINEL_DATABASE_NAME;
     env.PGDATABASE = WORKER_SENTINEL_DATABASE_NAME;
+    // BAPI-1479 — a provisioned job database replaces the four sentinel keys
+    // TOGETHER and adds the loopback role keys. Validated before anything is set, so
+    // an invalid name throws rather than leaving a half-pointed environment.
+    if (options.workerDatabase !== undefined) {
+        Object.assign(env, buildWorkerDatabaseEnv(options.workerDatabase));
+    }
+    // BAPI-1479 — CI's throwaway test values, from constants and never from
+    // `parentEnv`, for every job type and every adapter.
+    Object.assign(env, CI_WORKER_ENV_CONSTANTS);
+    // BAPI-1479 — the own-build launcher directory goes FIRST on PATH, from the
+    // explicit option only. The inherited PATH follows it unchanged; an empty or
+    // absent inherited PATH adds no empty component (an empty component means
+    // "the current directory" to a shell, which a worktree must not be).
+    if (typeof options.workerLauncherDirectory === "string" &&
+        options.workerLauncherDirectory.length > 0) {
+        const inherited = env.PATH;
+        env.PATH =
+            typeof inherited === "string" && inherited.length > 0
+                ? `${options.workerLauncherDirectory}${PLATFORM_PATH_DELIMITER}${inherited}`
+                : options.workerLauncherDirectory;
+    }
     if (options.correctionIntentVersion !== undefined) {
         if (options.correctionIntentVersion !== 1)
             throw new Error("unsupported correction intent version");

package/build/executor/failure-reason-codes.js

@@ -0,0 +1,126 @@
+/**
+ * The closed `telemetry.failure_reason_code` vocabulary (BAPI-1453).
+ *
+ * A failed executor job already reports a structured `error_kind`, which is the
+ * ROUTING signal: the server's terminal disposition and the merge re-fire lane
+ * decide on `error_kind` and `classification` alone (R14 rule 3). That kind is
+ * deliberately coarse — `MergeRetryable` covers a dozen distinct reasons — so an
+ * operator reading `explain_run` could not tell a `gh_pr_view_failed` from a
+ * `ci_not_green`. The precise reason existed only in the free-text
+ * `error_message`, which `explain_run` never reads.
+ *
+ * This module names that precise reason as one value from a CLOSED list, so the
+ * server can show it without ever reading free text. Two rules keep it safe:
+ *
+ *  - **Display only.** No disposition, retry, park, or rebase decision may read a
+ *    failure reason code. A row whose code disagrees with its `error_kind` is
+ *    classified by its `error_kind`.
+ *  - **Builders own it.** The failure builders in `merge-job.ts` and
+ *    `job-runner.ts` set it. Observation state never carries it, so a snapshot
+ *    can never overwrite or invent one.
+ *
+ * The list is mirrored in `api/library/epic_implementer/failure_reason_codes.py`.
+ * A parity test fails when the two drift, so add every new value to both.
+ */
+/**
+ * Every reason the local merge executor (`conductor/local-merge.ts`) can return
+ * on the merge-job path, plus the server's migration-graph refusals that reach
+ * the same classifier. The `ci_poll_http_<status>` family is matched by
+ * {@link CI_POLL_HTTP_REASON_PATTERN} rather than listed.
+ */
+const MERGE_REASON_CODES = [
+    "gh_pr_view_timeout",
+    "gh_pr_view_failed",
+    "gh_pr_view_unparseable",
+    "ci_poll_failed",
+    "ci_poll_timeout",
+    "ci_poll_network",
+    "ci_poll_unauthorized",
+    "ci_poll_server",
+    "ci_poll_http",
+    "ci_not_green",
+    "gh_merge_timeout",
+    "gh_merge_failed",
+    "gh_merge_conflict",
+    "merge_aborted",
+    "head_drift",
+    "pr_not_open",
+    "ref_mismatch",
+    "migration_graph_invalid",
+    "migration_graph_unreadable",
+    "local_merge_approval_required",
+    "local_gh_unavailable",
+    "local_merge_credential_missing",
+    "machine_merge_credential_missing",
+    "local_merge_credential_invalid",
+    "machine_merge_credential_invalid",
+    "local_merge_credential_unpermitted",
+    "machine_merge_credential_unpermitted",
+    "local_merge_probe_unavailable",
+    "machine_merge_probe_unavailable",
+];
+/**
+ * Merge-flow outcomes the executor itself produces, outside `local-merge.ts`.
+ * New contract values introduced by BAPI-1453.
+ */
+const EXECUTOR_MERGE_REASON_CODES = [
+    /** The claimed job's merge payload failed validation. */
+    "merge_payload_invalid",
+    /** Bridge API access for the CI re-poll could not be resolved. */
+    "merge_access_unavailable",
+    /** The whole merge flow exceeded its `timeout_seconds`. */
+    "merge_flow_timeout",
+    /** The merge flow threw. */
+    "merge_flow_error",
+    /** The merge flow finished without producing an outcome. */
+    "merge_no_outcome",
+    /** A failed merge response carried no recognized reason. */
+    "merge_failure_unclassified",
+];
+/**
+ * BAPI-1453: the permission probe that runs after a `gh_pr_view_failed` PROVED
+ * the merge credential cannot access the repository.
+ */
+export const GH_REPO_ACCESS_DENIED = "gh_repo_access_denied";
+/** The four pre-spawn verification refusals (`PreSpawnVerificationReason`). */
+const PRE_SPAWN_REASON_CODES = ["dirty", "status-unverifiable", "head-unverifiable", "head-mismatch"];
+/**
+ * BAPI-1530: display-only categories for a pre-worker worktree failure. They
+ * describe a structured outcome and are never read by any disposition decision.
+ */
+const WORKTREE_REASON_CODES = ["worktree_stale_branch", "worktree_lineage_refused", "worktree_fetch_failed"];
+/** Every fixed failure reason code. */
+export const FAILURE_REASON_CODES = [
+    ...MERGE_REASON_CODES,
+    ...EXECUTOR_MERGE_REASON_CODES,
+    GH_REPO_ACCESS_DENIED,
+    ...PRE_SPAWN_REASON_CODES,
+    ...WORKTREE_REASON_CODES,
+];
+/**
+ * The bounded `ci_poll_http_<status>` family. Anchored, exactly three digits,
+ * matched against the WHOLE string: a trailing newline, an extra suffix, a case
+ * change, or any other `ci_poll_*` spelling is rejected. Mirrored byte for byte
+ * in the Python module.
+ */
+export const CI_POLL_HTTP_REASON_PATTERN = /^ci_poll_http_[0-9]{3}$/;
+/** Longest accepted code. Mirrors the Python bound. */
+export const MAX_FAILURE_REASON_CODE_CHARS = 64;
+const FIXED_CODES = new Set(FAILURE_REASON_CODES);
+/** True only for a value in the closed vocabulary. */
+export function isFailureReasonCode(value) {
+    if (typeof value !== "string" || value.length > MAX_FAILURE_REASON_CODE_CHARS)
+        return false;
+    return FIXED_CODES.has(value) || CI_POLL_HTTP_REASON_PATTERN.test(value);
+}
+/**
+ * Narrow a known-good literal to {@link FailureReasonCode}. Throws on a value
+ * outside the vocabulary, so a misspelled builder code fails its first test
+ * rather than reaching the server as a silently dropped `null`.
+ */
+export function failureReasonCode(value) {
+    if (!isFailureReasonCode(value)) {
+        throw new Error(`not a failure reason code: ${value}`);
+    }
+    return value;
+}

package/build/executor/heartbeat.js

@@ -197,3 +197,41 @@ export async function runHeartbeatLoop(params) {
     }
     return ownership.abandoned ? { kind: "abandoned" } : { kind: "done" };
 }
+/**
+ * Send ONE awaited heartbeat carrying an ownership context, through the same
+ * transport, response interpretation, and ownership bookkeeping the periodic loop
+ * uses (BAPI-1504). The covered runner calls it BEFORE spawning a worker, with
+ * `worker: null`, so a cleanup-capable row's stored ownership is non-null whenever
+ * a worker may exist. It is only ever called while no periodic loop is running, so
+ * the two can never overlap or arrive out of order.
+ *
+ * `stale_claim` marks the claim abandoned, exactly like the loop. A stop request
+ * and an auth failure are reported to the caller without touching ownership; the
+ * caller owns what happens next. It never signals any process.
+ */
+export async function sendImmediateHeartbeat(params) {
+    const { job, httpClient, deps, ownership, observation } = params;
+    const git = await params.collectTelemetry();
+    observation.setGitTelemetry(git);
+    const result = normalizeHeartbeatResult(await httpClient.heartbeat(job, {
+        local_commit_count: git.local_commit_count,
+        last_commit_sha: git.last_commit_sha,
+        telemetry: observation.snapshot(),
+        ownership_context: params.ownershipContext,
+    }));
+    if (result.stop_requested === true)
+        return { kind: "server_stop" };
+    if (result.outcome === "auth_fatal") {
+        return { kind: "auth_fatal", httpStatus: result.authHttpStatus ?? 401 };
+    }
+    if (result.outcome === "updated") {
+        ownership.lastSuccessfulHeartbeatAt = deps.now();
+        return { kind: "accepted" };
+    }
+    if (result.outcome === "stale_claim") {
+        ownership.abandoned = true;
+        ownership.abandonReason = "stale_claim";
+        return { kind: "stale_claim" };
+    }
+    return { kind: "transient" };
+}

package/build/executor/http-client.js

@@ -217,6 +217,25 @@ function mapMutationResponse(status, bodyText, allowInvalidResult) {
         return { outcome: "auth_fatal", authHttpStatus: status };
     return { outcome: "fatal_http_error" };
 }
+/**
+ * The closed `error_code` of a cleanup-report 409 refusal, or `null` for anything
+ * else. Reads only the code; the body is never retained (BAPI-1504).
+ */
+function parseCleanupRefusalCode(bodyText) {
+    try {
+        const parsed = JSON.parse(bodyText);
+        if (typeof parsed !== "object" || parsed === null)
+            return null;
+        const detail = parsed.detail;
+        if (typeof detail !== "object" || detail === null)
+            return null;
+        const code = detail.error_code;
+        return code === "CLEANUP_REPORT_NOT_APPLICABLE" || code === "CLEANUP_REPORT_JOB_RUNNING" ? code : null;
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * Adapt the executor's injected `FetchLike` transport to the narrower
  * `ConductorFetch` shape the shared read-only Bridge API GET helper expects
@@ -419,6 +438,59 @@ export function createExecutorHttpClient(config) {
                 return "failed";
             }
         },
+        /**
+         * Deliver one cleanup confirmation (BAPI-1504).
+         *
+         * Only a validated 200 body or an explicit `409 CLEANUP_REPORT_NOT_APPLICABLE`
+         * is terminal. Everything else retains the local ownership record. Nothing
+         * from the response body, the token, or a raw transport error is returned.
+         */
+        async reportCleanup(request) {
+            let status;
+            let text;
+            try {
+                const res = await post(`/${request.jobId}/cleanup-report`, {
+                    repo_name: request.repoName,
+                    ownership_token: request.ownershipToken,
+                    cleanup_verdict: "confirmed",
+                    path: request.path,
+                }, request.repoName);
+                status = res.status;
+                text = res.text;
+            }
+            catch {
+                return { kind: "retained", reason: "network_error", retryable: true };
+            }
+            if (status >= 200 && status < 300) {
+                return isOkBody(text)
+                    ? { kind: "accepted" }
+                    : { kind: "retained", reason: "malformed_response", retryable: false };
+            }
+            if (status === 409) {
+                const code = parseCleanupRefusalCode(text);
+                if (code === "CLEANUP_REPORT_NOT_APPLICABLE")
+                    return { kind: "not_applicable" };
+                if (code === "CLEANUP_REPORT_JOB_RUNNING") {
+                    return { kind: "retained", reason: "job_running", retryable: true };
+                }
+                return { kind: "retained", reason: "malformed_response", retryable: false };
+            }
+            if (status === 401 || status === 403) {
+                return { kind: "retained", reason: "unauthorized", retryable: false };
+            }
+            if (status === 404) {
+                // A server that predates the route: keep the record for a later start.
+                (config.warn ?? ((message) => console.error(message)))(`cleanup_report_unsupported job=${request.jobId}`);
+                return { kind: "retained", reason: "unsupported", retryable: false };
+            }
+            if (status === 429)
+                return { kind: "retained", reason: "rate_limited", retryable: true };
+            if (status === 503)
+                return { kind: "retained", reason: "retry_later", retryable: true };
+            if (status >= 500)
+                return { kind: "retained", reason: "server_error", retryable: true };
+            return { kind: "retained", reason: "malformed_response", retryable: false };
+        },
         complete(job, completion) {
             const body = {
                 repo_name: job.repo_name,