@bridge_gpt/mcp-server 0.2.62 → 0.2.66

package/build/conductor/recovery-operations.js

@@ -18,9 +18,12 @@
  * callers: `recovery-cli.ts` and `plane/shutdown.ts`.
  */
 import { randomUUID } from "crypto";
-import { adoptCurrentHeadAndUnparkTicket, completeMergeChild, ConductorBridgeApiError, dispatchRemediation, fetchEpicRunState, mergeChild, patchPolicy, resumeRun, safeDiagnosticMessage, scopeCatchUp, scopeReparse, stopEpicRun, unparkEpicTicket, updateEpicRunStatus, } from "./bridge-api-client.js";
+import { adoptCurrentHeadAndUnparkTicket, completeMergeChild, ConductorBridgeApiError, dispatchRemediation, fetchEpicRunState, mergeChild, patchPolicy, resumeRun, safeDiagnosticMessage, scopeCatchUp, scopeReparse, stopEpicRun, unparkEpicTicket, updateEpicRunStatus, fetchChildContinuationStatus, postContinueParkedChild, resumeCiTicket, REVIEW_HEAD_REFUSAL_CODES, } from "./bridge-api-client.js";
+import { clearGuidedReference, guardForBinding, GUIDED_PAYLOAD_CONFLICT_MESSAGE, GUIDED_REFERENCE_STORE_FAILED_MESSAGE, prepareGuidedRequest, } from "./guided-repair.js";
 import { DEFAULT_GATE_NAME } from "./git-ci-types.js";
+import { canonicalSha256, clearContinuationReference, clearRecoveryReferenceFile, computeContinuationFingerprint, readRecoveryReferenceFile, writeRecoveryReferenceFile, isFullSha, newContinuationRequestId, readContinuationReference, writeContinuationReference, } from "./epic-child-continuation.js";
 import { resolveLocalMergeCredential, resolveLocalMergeMethod, runApprovedLocalMerge, } from "./local-merge.js";
+import { RESUME_RUN_UNCONFIRMED_MESSAGE } from "./repair-contract.js";
 /**
  * Bounded total attempts for a ticket-recovery CAS retry loop. Each attempt
  * begins with a fresh, authoritative state read — so this bounds full
@@ -179,6 +182,17 @@ async function ticketRecoveryWithRetry(access, options, mutate) {
             });
         }
         catch (err) {
+            const refusal = reviewHeadRefusal(err);
+            if (refusal !== null) {
+                return {
+                    ok: false,
+                    kind: "refused",
+                    epicRunId: options.epicRunId,
+                    ticketKey: options.ticketKey,
+                    errorCode: refusal.errorCode,
+                    message: refusal.message,
+                };
+            }
             return {
                 ok: false,
                 kind: "unavailable",
@@ -188,12 +202,14 @@ async function ticketRecoveryWithRetry(access, options, mutate) {
             };
         }
         if (result.ok) {
+            const recovery = result.ticket_status.review_head_recovery;
             return {
                 ok: true,
                 kind: "unparked",
                 epicRunId: options.epicRunId,
                 ticketKey: options.ticketKey,
                 status: result.ticket_status.status,
+                ...(recovery ? { reviewHeadRecovery: recovery } : {}),
             };
         }
         // `result.kind === "cas-conflict"`: a concurrent write moved the ticket's
@@ -207,6 +223,31 @@ async function ticketRecoveryWithRetry(access, options, mutate) {
         ticketKey: options.ticketKey,
     };
 }
+/**
+ * BAPI-1310 (E1): fixed operator sentences for the review-head refusal codes.
+ * Chosen by code so no server or provider text reaches the terminal.
+ */
+const REVIEW_HEAD_REFUSAL_MESSAGES = {
+    REVIEW_HEAD_ADOPTION_REQUIRED: "the ticket is parked on an unexplained review-head change; accept the current " +
+        "head with `epic-implementer adopt-current-head-and-unpark` (keeps spent repair " +
+        "allowances, resumes at CI). A generic unpark or remediation is refused",
+    REVIEW_HEAD_EPISODE_CONFLICT: "the ticket is no longer on the stop this request was made for; re-check its " +
+        "status (explain-run) before trying again",
+    REVIEW_HEAD_STATE_INVALID: "the ticket's stored recovery state cannot support an allowance-preserving " +
+        "adoption",
+    REVIEW_HEAD_BINDING_CHANGED: "the ticket's pull request could not be confirmed open with an unchanged identity",
+    REVIEW_HEAD_LIVE_WORK: "an executor job is, or may be, active for this ticket; retry when it has finished",
+    REVIEW_HEAD_UNAVAILABLE: "the current head or the ticket specification could not be read; retry shortly",
+};
+/** Map a thrown client error to an E1 refusal, or `null` for anything else. */
+function reviewHeadRefusal(err) {
+    if (!(err instanceof ConductorBridgeApiError) || err.status !== 409)
+        return null;
+    const code = err.errorCode;
+    if (typeof code !== "string" || !REVIEW_HEAD_REFUSAL_CODES.includes(code))
+        return null;
+    return { errorCode: code, message: REVIEW_HEAD_REFUSAL_MESSAGES[code] ?? "refused" };
+}
 /**
  * Unpark a parked `needs_human` ticket, with a bounded authoritative-reread
  * retry on a concurrent `row_version` bump.
@@ -385,9 +426,17 @@ export async function patchPolicyRepair(access, options, deps = {}) {
     }
 }
 /**
- * Resume a paused run, or a quarantined one with `clearQuarantine`. The server
- * re-evaluates activation and owns the control-generation CAS retry; nothing here
- * reads or sends a generation.
+ * Resume a paused run, a quarantined one with `clearQuarantine`, or a run held by
+ * an eligible integration block. The server re-evaluates activation and owns the
+ * control-generation CAS retry; nothing here reads or sends a generation. It makes
+ * exactly ONE mutation call and returns a parsed success verbatim — no read, no
+ * retry, no poll, and no legacy `/resume` fallback.
+ *
+ * Only a structured 4xx is an authoritative refusal (the server decided and wrote
+ * nothing). A 5xx — even one carrying an `error_code` — a timeout, a dropped
+ * connection, or an unparseable/unexpected 2xx cannot prove whether the resume
+ * committed, so each is `unavailable` with {@link RESUME_RUN_UNCONFIRMED_MESSAGE}.
+ * Other repair verbs keep {@link classifyRepairError} unchanged.
  */
 export async function resumeRunRepair(access, options, deps = {}) {
     try {
@@ -395,6 +444,526 @@ export async function resumeRunRepair(access, options, deps = {}) {
         return { ok: true, result: await call(access, options) };
     }
     catch (err) {
-        return classifyRepairError(err, "resume-run request failed");
+        if (err instanceof ConductorBridgeApiError &&
+            typeof err.status === "number" &&
+            err.status >= 400 &&
+            err.status < 500 &&
+            err.errorCode) {
+            return classifyRepairError(err, "resume-run request failed");
+        }
+        return { ok: false, kind: "unavailable", message: RESUME_RUN_UNCONFIRMED_MESSAGE };
+    }
+}
+// ---------------------------------------------------------------------------
+// BAPI-1333 — guided (binding-pinned) repairs
+// ---------------------------------------------------------------------------
+/** The server's refusal code for a guided repair whose pinned subject moved. */
+export const REPAIR_SUBJECT_STALE_CODE = "REPAIR_SUBJECT_STALE";
+/**
+ * Send ONE guided repair request, pinned to its displayed binding.
+ *
+ * The reference (request id, binding digest, payload digest) is durably stored
+ * BEFORE the first POST; a store failure sends nothing and never falls back to
+ * an unguarded or resetting verb. Only a structured 4xx is a definitive answer;
+ * a 5xx, timeout, dropped connection, or unparseable 2xx is `unconfirmed`, and
+ * the reference survives it so a new CLI process re-sends the same request.
+ */
+export async function guidedRepairOnce(options, deps = {}) {
+    const prepared = await prepareGuidedRequest(options.binding, options.payloadDigest, deps);
+    if (prepared.kind === "store_failed") {
+        return { kind: "unavailable", message: GUIDED_REFERENCE_STORE_FAILED_MESSAGE };
+    }
+    if (prepared.kind === "payload_conflict") {
+        return { kind: "unavailable", message: GUIDED_PAYLOAD_CONFLICT_MESSAGE };
+    }
+    const { requestId, referenceReused } = prepared;
+    let result;
+    try {
+        result = await options.send(guardForBinding(options.binding, requestId));
+    }
+    catch (err) {
+        if (err instanceof ConductorBridgeApiError &&
+            typeof err.status === "number" &&
+            err.status >= 400 &&
+            err.status < 500 &&
+            err.errorCode) {
+            await clearGuidedReference(options.binding, deps);
+            const message = err.bodyPreview ?? err.errorCode;
+            if (err.errorCode === REPAIR_SUBJECT_STALE_CODE) {
+                return { kind: "stale", code: err.errorCode, message, requestId, referenceReused };
+            }
+            return { kind: "refused", code: err.errorCode, status: err.status, message, requestId };
+        }
+        return { kind: "unconfirmed", message: options.unconfirmedMessage, requestId, referenceReused };
+    }
+    await clearGuidedReference(options.binding, deps);
+    return result.committed
+        ? { kind: "committed", result, requestId, referenceReused }
+        : { kind: "no_op", result, requestId, referenceReused };
+}
+const AUTHORITATIVE_OUTCOMES = new Set([
+    "committed",
+    "already_continued",
+    "stale_historical_episode",
+    "refused",
+    "unsupported",
+]);
+/**
+ * Look the request's receipt up exactly once. Returns a decided result only when
+ * a durable receipt for THIS request id proves the commit; anything else is
+ * `null` (still unconfirmed). Never re-reads CAS tokens and never mutates.
+ */
+async function lookupOwnReceipt(access, reference, fetchStatus) {
+    let status;
+    try {
+        status = await fetchStatus(access, {
+            epicRunId: reference.bindings.epicRunId,
+            ticketKey: reference.bindings.ticketKey,
+            requestId: reference.requestId,
+        });
+    }
+    catch {
+        return null;
+    }
+    if (!status.found || status.receipt === null)
+        return null;
+    if (status.receipt.request_id !== reference.requestId)
+        return null;
+    const outcome = status.outcome === "stale_historical_episode" ? "stale_historical_episode" : "committed";
+    return {
+        outcome,
+        reason_code: outcome === "committed" ? null : "stale_episode",
+        explanation: outcome === "committed"
+            ? "The receipt proves this request's continuation committed."
+            : "The receipt proves this request's continuation committed; the child has since parked again.",
+        replayed: true,
+        retryable: false,
+        receipt: status.receipt,
+        current: status.current,
+    };
+}
+/**
+ * Continue a parked child through the server's atomic continuation, at most one
+ * POST per invocation.
+ *
+ * A pending recovery reference for this child is REUSED as-is — same request id,
+ * same bindings — so a lost response is resolved by a replay the server answers
+ * from its receipt, and a restarted process can never approve a new head or
+ * episode by re-reading the child. Only when no reference exists are the
+ * bindings read (once), fingerprinted, and stored BEFORE the POST is sent.
+ *
+ * After a transport failure, a malformed success body, or a 5xx, exactly one
+ * receipt lookup follows. No second POST, no new request id, no polling for
+ * completion, and never a fallback to unpark.
+ */
+export async function continueChildOnce(access, options, deps = {}) {
+    const fetchStatus = deps.fetchStatus ?? fetchChildContinuationStatus;
+    const post = deps.post ?? postContinueParkedChild;
+    const store = deps.store ?? {};
+    let reference = await readContinuationReference(options.epicRunId, options.ticketKey, store);
+    if (reference !== null && reference.bindings.repoName !== access.repoName) {
+        reference = null;
+    }
+    const reusedReference = reference !== null;
+    if (reference === null) {
+        let status;
+        try {
+            status = await fetchStatus(access, {
+                epicRunId: options.epicRunId,
+                ticketKey: options.ticketKey,
+            });
+        }
+        catch (err) {
+            return { kind: "unavailable", message: safeDiagnosticMessage(err, "could not read the child") };
+        }
+        const current = status.current;
+        if (!current.parked ||
+            !current.continuation_available ||
+            current.parked_gate === null ||
+            current.park_generation === null) {
+            return { kind: "not_continuable", current };
+        }
+        const head = current.expected_head_sha === null ? null : current.expected_head_sha.toLowerCase();
+        if (head !== null && !isFullSha(head)) {
+            return { kind: "unavailable", message: "the child's bound head is not a full SHA" };
+        }
+        const bindings = {
+            repoName: access.repoName,
+            epicRunId: status.epic_run_id,
+            ticketKey: status.ticket_key,
+            parkedGate: current.parked_gate,
+            expectedRowVersion: current.row_version,
+            expectedHeadSha: head,
+            sourceParkGeneration: current.park_generation,
+        };
+        reference = {
+            version: 1,
+            bindings,
+            requestId: (deps.newRequestId ?? newContinuationRequestId)(),
+            requestFingerprint: computeContinuationFingerprint(bindings),
+            createdAt: new Date().toISOString(),
+        };
+        try {
+            // Also keyed by the caller's own addressing so the next invocation (which
+            // may use the epic key rather than the resolved id) finds it.
+            await writeContinuationReference(reference, store);
+            if (options.epicRunId !== bindings.epicRunId || options.ticketKey !== bindings.ticketKey) {
+                await writeContinuationReference(reference, store, {
+                    epicRunId: options.epicRunId,
+                    ticketKey: options.ticketKey,
+                });
+            }
+        }
+        catch {
+            return {
+                kind: "unavailable",
+                message: "could not store the local recovery reference, so the request was not sent",
+            };
+        }
+    }
+    const ref = reference;
+    const clear = async () => {
+        await clearContinuationReference(options.epicRunId, options.ticketKey, store);
+        await clearContinuationReference(ref.bindings.epicRunId, ref.bindings.ticketKey, store);
+    };
+    const outcome = await post(access, {
+        bindings: ref.bindings,
+        requestId: ref.requestId,
+        requestFingerprint: ref.requestFingerprint,
+        reason: options.reason,
+    });
+    if (outcome.kind === "result" && AUTHORITATIVE_OUTCOMES.has(outcome.result.outcome)) {
+        await clear();
+        return { kind: "decided", requestId: ref.requestId, reusedReference, result: outcome.result };
+    }
+    if (outcome.kind === "refused_http") {
+        await clear();
+        return {
+            kind: "refused_http",
+            requestId: ref.requestId,
+            status: outcome.status,
+            errorCode: outcome.errorCode,
+        };
+    }
+    // Uncertain (transport, malformed 2xx, 5xx, or the server's own unconfirmed).
+    const transport = outcome.kind === "uncertain"
+        ? outcome.status !== undefined
+            ? `${outcome.reason} (status ${outcome.status})`
+            : outcome.reason
+        : "indeterminate commit";
+    const proven = await lookupOwnReceipt(access, ref, fetchStatus);
+    if (proven !== null) {
+        await clear();
+        return { kind: "decided", requestId: ref.requestId, reusedReference, result: proven };
+    }
+    return { kind: "unconfirmed", requestId: ref.requestId, reusedReference, transport };
+}
+/**
+ * Read a child's current episode and, when a local recovery reference exists (or
+ * `requestId` is given), that request's receipt. One bounded GET; read-only. A
+ * reference is cleared only when the lookup PROVES its commit; `not_found` keeps
+ * it, because the absence of a receipt right now does not prove the request will
+ * never have committed if it is still in flight.
+ */
+export async function lookupContinuationReceipt(access, options, deps = {}) {
+    const fetchStatus = deps.fetchStatus ?? fetchChildContinuationStatus;
+    const store = deps.store ?? {};
+    const reference = options.requestId
+        ? null
+        : await readContinuationReference(options.epicRunId, options.ticketKey, store);
+    const requestId = options.requestId ?? reference?.requestId ?? null;
+    let status;
+    try {
+        status = await fetchStatus(access, {
+            epicRunId: reference?.bindings.epicRunId ?? options.epicRunId,
+            ticketKey: reference?.bindings.ticketKey ?? options.ticketKey,
+            ...(requestId ? { requestId } : {}),
+        });
+    }
+    catch (err) {
+        return { kind: "unavailable", message: safeDiagnosticMessage(err, "could not read the child") };
+    }
+    if (status.found && status.receipt !== null) {
+        if (reference !== null && status.receipt.request_id === reference.requestId) {
+            await clearContinuationReference(options.epicRunId, options.ticketKey, store);
+            await clearContinuationReference(reference.bindings.epicRunId, reference.bindings.ticketKey, store);
+        }
+        return { kind: "found", requestId, status };
+    }
+    return { kind: "not_found", requestId, status };
+}
+// ---------------------------------------------------------------------------
+// BAPI-1326 — `resume-ci`: a pinned, bounded, allowance-preserving CI resume
+// ---------------------------------------------------------------------------
+/** The recovery-reference namespace of pinned `resume-ci` operations. */
+export const RESUME_CI_REFERENCE_NAMESPACE = "epic-ci-resumes";
+/**
+ * Bounded POSTs per invocation. Every POST of one invocation carries the SAME
+ * operation key and stop binding; only the row version may be refreshed, and
+ * only while every original binding still matches.
+ */
+export const RESUME_CI_POST_LIMIT = 3;
+/** The pause before a retry. Injectable so tests never sleep. */
+const RESUME_CI_RETRY_DELAY_MS = 250;
+const FULL_SHA_PATTERN = /^[0-9a-f]{40}$/;
+const FINGERPRINT_PATTERN = /^[0-9a-f]{64}$/;
+const CI_STOP_REASON_VALUES = new Set(["wait_expired", "verdict_unavailable", "repair_exhausted"]);
+function isRecordValue(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function isNonNegativeInteger(value) {
+    return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+/** Strictly validate a stop binding; `null` for anything short of the contract. */
+export function parseCiStopBinding(value) {
+    if (!isRecordValue(value))
+        return null;
+    const checks = value.required_checks;
+    if (!isNonNegativeInteger(value.park_generation) ||
+        !CI_STOP_REASON_VALUES.has(value.reason) ||
+        typeof value.accepted_head_sha !== "string" || !FULL_SHA_PATTERN.test(value.accepted_head_sha) ||
+        !isNonNegativeInteger(value.pr_number) || value.pr_number < 1 ||
+        typeof value.base_ref !== "string" || !value.base_ref || value.base_ref.length > 200 ||
+        !Array.isArray(checks) || checks.length > 64 ||
+        !checks.every((c) => typeof c === "string" && c.length > 0 && c.length <= 200) ||
+        (value.required_checks_source !== "run" && value.required_checks_source !== "plan") ||
+        typeof value.required_checks_fingerprint !== "string" ||
+        !FINGERPRINT_PATTERN.test(value.required_checks_fingerprint) ||
+        !(value.spec_hash === null || value.spec_hash === undefined ||
+            (typeof value.spec_hash === "string" && value.spec_hash.length > 0 && value.spec_hash.length <= 128))) {
+        return null;
+    }
+    return {
+        park_generation: value.park_generation,
+        reason: value.reason,
+        accepted_head_sha: value.accepted_head_sha,
+        pr_number: value.pr_number,
+        base_ref: value.base_ref,
+        required_checks: [...checks],
+        required_checks_source: value.required_checks_source,
+        required_checks_fingerprint: value.required_checks_fingerprint,
+        spec_hash: (value.spec_hash ?? null),
+    };
+}
+/**
+ * Capture the ACTIVE typed CI stop's binding from authenticated ticket state,
+ * mirroring the server's selection: the ticket is `needs_human`, its single
+ * parked gate is `ci`, and `gates.ci.ci_stop` is a complete typed record for the
+ * gate's current park generation. Never derived from the park's reason text.
+ */
+export function captureCiStopBinding(ticket) {
+    // The client union predates the v2 gate statuses; the server sends them anyway.
+    if (ticket.status !== "needs_human")
+        return { ok: false, reason: "not_parked" };
+    const gates = isRecordValue(ticket.gates) ? ticket.gates : {};
+    const parked = Object.entries(gates).filter(([, state]) => isRecordValue(state) && state.status === "needs_human");
+    if (parked.length !== 1 || parked[0][0] !== "ci")
+        return { ok: false, reason: "not_ci_park" };
+    const ci = parked[0][1];
+    const stop = ci.ci_stop;
+    if (!isRecordValue(stop) || !isRecordValue(stop.evidence))
+        return { ok: false, reason: "no_typed_stop" };
+    const generation = isNonNegativeInteger(ci.park_generation) ? ci.park_generation : 0;
+    if (stop.park_generation !== generation)
+        return { ok: false, reason: "stop_superseded" };
+    const evidence = stop.evidence;
+    const binding = parseCiStopBinding({
+        park_generation: stop.park_generation,
+        reason: stop.reason,
+        accepted_head_sha: stop.accepted_head_sha,
+        pr_number: evidence.pr_number,
+        base_ref: evidence.base_ref,
+        required_checks: evidence.required_checks,
+        required_checks_source: evidence.required_checks_source,
+        required_checks_fingerprint: evidence.required_checks_fingerprint,
+        spec_hash: evidence.spec_hash ?? null,
+    });
+    return binding === null ? { ok: false, reason: "no_typed_stop" } : { ok: true, binding };
+}
+/** The fingerprint of a pinned operation's identity (the row version excluded). */
+export function computeCiResumeFingerprint(ref) {
+    return canonicalSha256({
+        v: 1,
+        operation: "resume_ci",
+        target: { repo_name: ref.repoName, epic_run_id: ref.epicRunId, ticket_key: ref.ticketKey },
+        operation_key: ref.operationKey,
+        stop_binding: ref.stopBinding,
+    });
+}
+function parseCiResumeReference(raw) {
+    if (!isRecordValue(raw) || raw.version !== 1 || raw.operation !== "resume_ci")
+        return null;
+    const binding = parseCiStopBinding(raw.stopBinding);
+    if (binding === null ||
+        typeof raw.repoName !== "string" || !raw.repoName ||
+        typeof raw.epicRunId !== "string" || !raw.epicRunId ||
+        typeof raw.ticketKey !== "string" || !raw.ticketKey ||
+        !isNonNegativeInteger(raw.expectedRowVersion) ||
+        typeof raw.operationKey !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._:-]{7,127}$/.test(raw.operationKey) ||
+        typeof raw.fingerprint !== "string") {
+        return null;
+    }
+    const ref = {
+        version: 1,
+        operation: "resume_ci",
+        repoName: raw.repoName,
+        epicRunId: raw.epicRunId,
+        ticketKey: raw.ticketKey,
+        expectedRowVersion: raw.expectedRowVersion,
+        operationKey: raw.operationKey,
+        stopBinding: binding,
+        fingerprint: raw.fingerprint,
+        createdAt: typeof raw.createdAt === "string" ? raw.createdAt : "",
+    };
+    // A reference whose fingerprint no longer matches its own identity was
+    // tampered with or truncated; it never authorizes a replay.
+    return computeCiResumeFingerprint(ref) === ref.fingerprint ? ref : null;
+}
+function sameBinding(a, b) {
+    return canonicalSha256(a) === canonicalSha256(b);
+}
+async function readCiResumeReference(key, store) {
+    return parseCiResumeReference(await readRecoveryReferenceFile(RESUME_CI_REFERENCE_NAMESPACE, key, store));
+}
+/**
+ * Resume a ticket parked on a qualified CI stop, with its operation pinned.
+ *
+ * A pinned reference for this ticket is REUSED as-is — same operation key, same
+ * stop binding — so a lost response or a restarted process is answered from the
+ * server's durable receipt, and a later park is never silently targeted. Only
+ * when no reference exists is the binding read (once) from authenticated ticket
+ * state, and the reference is stored BEFORE the first POST.
+ *
+ * At most {@link RESUME_CI_POST_LIMIT} POSTs, all with the same key and binding.
+ * A row-version conflict refreshes the row version only while every original
+ * binding still matches; otherwise the result is `stale_reference` and nothing
+ * more is sent. There is no fallback to unpark, continue-child, or any other
+ * mutation.
+ */
+export async function resumeCiOnce(access, options, deps = {}) {
+    const fetchState = deps.fetchState ?? fetchEpicRunState;
+    const post = deps.post ?? resumeCiTicket;
+    const store = deps.store ?? {};
+    const sleep = deps.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const callerKey = { epicRunId: options.epicRunId, ticketKey: options.ticketKey };
+    let reference = await readCiResumeReference(callerKey, store);
+    if (reference !== null && reference.repoName !== access.repoName)
+        reference = null;
+    const reusedReference = reference !== null;
+    const persist = async (ref) => {
+        await writeRecoveryReferenceFile(RESUME_CI_REFERENCE_NAMESPACE, callerKey, ref, store);
+        if (ref.epicRunId !== callerKey.epicRunId || ref.ticketKey !== callerKey.ticketKey) {
+            await writeRecoveryReferenceFile(RESUME_CI_REFERENCE_NAMESPACE, { epicRunId: ref.epicRunId, ticketKey: ref.ticketKey }, ref, store);
+        }
+    };
+    const readTicket = async () => {
+        try {
+            const state = await fetchState(access, options.epicRunId);
+            return state.ticket_statuses.find((t) => t.ticket_key === options.ticketKey) ?? null;
+        }
+        catch {
+            return "unavailable";
+        }
+    };
+    if (reference === null) {
+        const ticket = await readTicket();
+        if (ticket === "unavailable") {
+            return { kind: "unavailable", message: "could not read the ticket's state, so nothing was sent" };
+        }
+        if (ticket === null)
+            return { kind: "not_eligible", reason: "ticket_not_found" };
+        const captured = captureCiStopBinding(ticket);
+        if (!captured.ok)
+            return { kind: "not_eligible", reason: captured.reason };
+        const identity = {
+            repoName: access.repoName,
+            epicRunId: ticket.epic_run_id,
+            ticketKey: ticket.ticket_key,
+            operationKey: (deps.newOperationKey ?? randomUUID)(),
+            stopBinding: captured.binding,
+        };
+        reference = {
+            version: 1,
+            operation: "resume_ci",
+            ...identity,
+            expectedRowVersion: ticket.row_version,
+            fingerprint: computeCiResumeFingerprint(identity),
+            createdAt: (deps.now ?? (() => new Date()))().toISOString(),
+        };
+        try {
+            await persist(reference);
+        }
+        catch {
+            return {
+                kind: "unavailable",
+                message: "could not store the local recovery reference, so the request was not sent",
+            };
+        }
+    }
+    const clear = async (ref) => {
+        await clearRecoveryReferenceFile(RESUME_CI_REFERENCE_NAMESPACE, callerKey, store);
+        await clearRecoveryReferenceFile(RESUME_CI_REFERENCE_NAMESPACE, { epicRunId: ref.epicRunId, ticketKey: ref.ticketKey }, store);
+    };
+    let ref = reference;
+    let last = null;
+    for (let attempt = 1; attempt <= RESUME_CI_POST_LIMIT; attempt += 1) {
+        if (attempt > 1)
+            await sleep(RESUME_CI_RETRY_DELAY_MS * (attempt - 1));
+        const outcome = await post(access, {
+            epicRunId: ref.epicRunId,
+            ticketKey: ref.ticketKey,
+            expectedRowVersion: ref.expectedRowVersion,
+            operationKey: ref.operationKey,
+            stopBinding: ref.stopBinding,
+        });
+        last = outcome;
+        if (outcome.kind === "result") {
+            await clear(ref);
+            return { kind: outcome.result.outcome, result: outcome.result, reusedReference };
+        }
+        if (outcome.kind === "uncertain")
+            continue;
+        if (outcome.kind === "refused" && outcome.errorCode === "CI_RESUME_BUSY")
+            continue;
+        if (outcome.kind === "refused" && outcome.errorCode === "ROW_VERSION_CONFLICT") {
+            // Refresh the row version ONLY while the stop is still the same one.
+            const ticket = await readTicket();
+            if (ticket === "unavailable" || ticket === null) {
+                return { kind: "refused", errorCode: outcome.errorCode, status: outcome.status, reusedReference };
+            }
+            const current = captureCiStopBinding(ticket);
+            if (!current.ok || !sameBinding(current.binding, ref.stopBinding)) {
+                return { kind: "stale_reference", reusedReference };
+            }
+            ref = { ...ref, expectedRowVersion: ticket.row_version };
+            try {
+                await persist(ref);
+            }
+            catch {
+                return {
+                    kind: "unavailable",
+                    message: "could not update the local recovery reference, so the retry was not sent",
+                };
+            }
+            continue;
+        }
+        // Every other refusal or rejection is authoritative: nothing was written,
+        // and this operation is finished.
+        await clear(ref);
+        return {
+            kind: "refused",
+            errorCode: outcome.errorCode ?? "REQUEST_REJECTED",
+            status: outcome.status,
+            reusedReference,
+        };
+    }
+    if (last !== null && last.kind === "refused") {
+        // Busy or row-version churn for the whole budget: nothing was written, and
+        // the pinned reference is kept for the next invocation.
+        return { kind: "refused", errorCode: last.errorCode, status: last.status, reusedReference };
     }
+    const transport = last !== null && last.kind === "uncertain"
+        ? last.status !== undefined ? `${last.reason} (status ${last.status})` : last.reason
+        : "indeterminate";
+    return { kind: "unconfirmed", transport, reusedReference, attempts: RESUME_CI_POST_LIMIT };
 }