@bridge_gpt/mcp-server 0.2.68 → 0.2.70

package/build/conductor/recovery-operations.js

@@ -18,11 +18,12 @@
  * callers: `recovery-cli.ts` and `plane/shutdown.ts`.
  */
 import { randomUUID } from "crypto";
-import { adoptCurrentHeadAndUnparkTicket, completeMergeChild, ConductorBridgeApiError, dispatchRemediation, fetchEpicRunState, mergeChild, patchPolicy, RERUN_CI_ROUTE_UNAVAILABLE_CODE, RERUN_CI_ROUTE_UNAVAILABLE_MESSAGE, rerunCi, resumeRun, safeDiagnosticMessage, scopeCatchUp, scopeReparse, stopEpicRun, unparkEpicTicket, updateEpicRunStatus, fetchChildContinuationStatus, postContinueParkedChild, postGrantContinuation, resumeCiTicket, REVIEW_HEAD_REFUSAL_CODES, } from "./bridge-api-client.js";
+import { adoptCurrentHeadAndUnparkTicket, completeMergeChild, ConductorBridgeApiError, dispatchRemediation, fetchEpicRunState, mergeChild, patchPolicy, RERUN_CI_ROUTE_UNAVAILABLE_CODE, RERUN_CI_ROUTE_UNAVAILABLE_MESSAGE, rerunCi, resolveHandoff, resumeRun, safeDiagnosticMessage, scopeCatchUp, scopeReparse, stopEpicRun, unparkEpicTicket, updateEpicRunStatus, fetchChildContinuationStatus, postContinueParkedChild, postGrantContinuation, resumeCiTicket, regeneratePlanTicket, REVIEW_HEAD_REFUSAL_CODES, } from "./bridge-api-client.js";
 import { clearGuidedReference, guardForBinding, GUIDED_PAYLOAD_CONFLICT_MESSAGE, GUIDED_REFERENCE_STORE_FAILED_MESSAGE, guidedPayloadDigest, 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 { bindingsDriverContextSha256, CONTINUATION_CI_WAITING_REASONS, canonicalSha256, clearContinuationReference, clearRecoveryReferenceFile, computeContinuationFingerprint, driverContextSha256, readRecoveryReferenceFile, writeRecoveryReferenceFile, isFullSha, newContinuationRequestId, readContinuationReference, writeContinuationReference, } from "./epic-child-continuation.js";
 import { resolveLocalMergeCredential, resolveLocalMergeMethod, runApprovedLocalMerge, } from "./local-merge.js";
+import { resolveMergeCredentialAtAction, } from "./stored-merge-credential.js";
 import { RERUN_CI_UNCONFIRMED_REASON, RESUME_RUN_UNCONFIRMED_MESSAGE } from "./repair-contract.js";
 /**
  * Bounded total attempts for a ticket-recovery CAS retry loop. Each attempt
@@ -296,6 +297,19 @@ export async function scopeReparseRepair(access, options, deps = {}) {
         return classifyRepairError(err, "scope-reparse request failed");
     }
 }
+/**
+ * BAPI-1494 — record the owner's decision on a ticket's verification hand-offs.
+ * The server records the verified request actor and decides every refusal.
+ */
+export async function resolveHandoffRepair(access, options, deps = {}) {
+    try {
+        const call = deps.resolveHandoff ?? resolveHandoff;
+        return { ok: true, result: await call(access, options) };
+    }
+    catch (err) {
+        return classifyRepairError(err, "resolve-handoff request failed");
+    }
+}
 /**
  * Dispatch a remediation job with driver context. `context` must already be
  * validated against `DRIVER_CONTEXT_MAX_BYTES`; the server selects the job type.
@@ -341,6 +355,17 @@ export async function mergeChildRepair(access, options, deps = {}) {
         return { ok: true, result: serverResult };
     }
     const runLocal = deps.runLocalMerge ?? runApprovedLocalMerge;
+    const env = deps.env ?? process.env;
+    // BAPI-1461: the repository identity is resolved before any store lookup, and
+    // an unresolved or conflicting identity reads nothing.
+    const resolution = deps.storedMergeCredential
+        ? await resolveMergeCredentialAtAction(env, "local", deps.storedMergeCredential)
+        : null;
+    const credential = resolution === null
+        ? resolveLocalMergeCredential(env, "local")
+        : resolution.status === "resolved"
+            ? resolution.credential
+            : null;
     let succeeded = false;
     let alreadyMerged = false;
     let failureReason = "gh_merge_failed";
@@ -357,10 +382,7 @@ export async function mergeChildRepair(access, options, deps = {}) {
         }, { method: resolveLocalMergeMethod(local.merge_method) }, 
         // BAPI-1136: an explicitly configured local credential, never the ambient
         // login. `env` remains the source of the allowlisted operational base only.
-        {
-            env: deps.env ?? process.env,
-            credential: resolveLocalMergeCredential(deps.env ?? process.env, "local"),
-        });
+        { env, credential });
         succeeded = localResult.status === "succeeded";
         alreadyMerged = succeeded && localResult.reason === "already_merged";
         failureReason = boundedLocalMergeReason(localResult.reason);
@@ -632,6 +654,22 @@ export async function continueChildOnce(access, options, deps = {}) {
         reference = null;
     }
     const reusedReference = reference !== null;
+    // BAPI-1514 — a reused request is bound to the context it was first sent with
+    // (by hash). Re-sending it with a different context, or with/without one, would
+    // be a different request under the same id; refuse locally, sending nothing.
+    if (reference !== null) {
+        const storedSha = bindingsDriverContextSha256(reference.bindings);
+        const wantedSha = options.driverContext === undefined ? undefined : driverContextSha256(options.driverContext);
+        if (storedSha !== wantedSha) {
+            return {
+                kind: "unavailable",
+                message: `a pending continuation request (${reference.requestId}) was sent ` +
+                    (storedSha === undefined ? "without --context-file" : "with a different --context-file") +
+                    "; re-run with the same --context-file (or none, as before) to settle that same " +
+                    "request, or look it up with continuation-receipt",
+            };
+        }
+    }
     if (reference === null) {
         let status;
         try {
@@ -662,6 +700,7 @@ export async function continueChildOnce(access, options, deps = {}) {
             expectedRowVersion: current.row_version,
             expectedHeadSha: head,
             sourceParkGeneration: current.park_generation,
+            ...(options.driverContext !== undefined ? { driverContext: options.driverContext } : {}),
         };
         reference = {
             version: 1,
@@ -699,9 +738,15 @@ export async function continueChildOnce(access, options, deps = {}) {
         requestFingerprint: ref.requestFingerprint,
         reason: options.reason,
         workerExitProof: options.workerExitProof,
+        ...(options.driverContext !== undefined ? { driverContext: options.driverContext } : {}),
     });
     if (outcome.kind === "result" && AUTHORITATIVE_OUTCOMES.has(outcome.result.outcome)) {
-        await clear();
+        const keepForRetry = outcome.result.outcome === "refused" &&
+            outcome.result.retryable &&
+            outcome.result.reason_code !== null &&
+            CONTINUATION_CI_WAITING_REASONS.has(outcome.result.reason_code);
+        if (!keepForRetry)
+            await clear();
         return { kind: "decided", requestId: ref.requestId, reusedReference, result: outcome.result };
     }
     if (outcome.kind === "refused_http") {
@@ -711,6 +756,7 @@ export async function continueChildOnce(access, options, deps = {}) {
             requestId: ref.requestId,
             status: outcome.status,
             errorCode: outcome.errorCode,
+            ...(options.driverContext !== undefined ? { driverContextSent: true } : {}),
         };
     }
     // Uncertain (transport, malformed 2xx, 5xx, or the server's own unconfirmed).
@@ -1131,3 +1177,256 @@ export async function resumeCiOnce(access, options, deps = {}) {
         : "indeterminate";
     return { kind: "unconfirmed", transport, reusedReference, attempts: RESUME_CI_POST_LIMIT };
 }
+// ---------------------------------------------------------------------------
+// BAPI-1532 — `regenerate-plan`: a pinned, bounded answer to a named plan failure
+// ---------------------------------------------------------------------------
+/** The recovery-reference namespace of pinned `regenerate-plan` operations. */
+export const REGENERATE_PLAN_REFERENCE_NAMESPACE = "epic-plan-regenerations";
+/**
+ * Bounded POSTs per invocation. Every POST of one invocation carries the SAME
+ * operation key, route, reason, and park generation; only the row version may be
+ * refreshed, and only while the park identity still matches.
+ */
+export const REGENERATE_PLAN_POST_LIMIT = 3;
+const REGENERATE_PLAN_RETRY_DELAY_MS = 250;
+const REGENERATE_PLAN_OPERATION_KEY_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:-]{7,127}$/;
+const FINALIZATION_CAUSE = "worker_finalization_missing_branch_and_pr";
+/** The longest driver reason the request carries; the server bounds it again. */
+export const REGENERATE_PLAN_REASON_MAX_CHARS = 500;
+/**
+ * Capture the park identity a `regenerate-plan` is pinned to, from authenticated
+ * ticket state, mirroring the server's selection: the ticket is `needs_human`,
+ * its single parked gate is `implement`, and either that gate holds a `parked`
+ * `plan_failure` record for its own park generation, or its committed cause is the
+ * BAPI-1487 finalization park (which the server admits through its own predicate
+ * and which names no planner reason). Never derived from the park's reason text.
+ */
+export function captureRegeneratePlanSubject(ticket) {
+    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] !== "implement") {
+        return { ok: false, reason: "not_implement_park" };
+    }
+    const gate = parked[0][1];
+    const generation = isNonNegativeInteger(gate.park_generation) ? gate.park_generation : 0;
+    const record = gate.plan_failure;
+    if (isRecordValue(record)) {
+        if (record.phase !== "parked")
+            return { ok: false, reason: "park_superseded" };
+        if (!isNonNegativeInteger(record.park_generation) || record.park_generation !== generation) {
+            return { ok: false, reason: "park_superseded" };
+        }
+        return { ok: true, parkGeneration: generation };
+    }
+    if (gate.terminal_failure_cause === FINALIZATION_CAUSE) {
+        return { ok: true, parkGeneration: generation };
+    }
+    return { ok: false, reason: "no_plan_failure" };
+}
+/** The fingerprint of a pinned operation's identity (the row version excluded). */
+export function computeRegeneratePlanFingerprint(ref) {
+    return canonicalSha256({
+        v: 1,
+        operation: "regenerate_plan",
+        target: { repo_name: ref.repoName, epic_run_id: ref.epicRunId, ticket_key: ref.ticketKey },
+        route: ref.route,
+        reason: ref.reason,
+        park_generation: ref.parkGeneration,
+        operation_key: ref.operationKey,
+    });
+}
+function parseRegeneratePlanReference(raw) {
+    if (!isRecordValue(raw) || raw.version !== 1 || raw.operation !== "regenerate_plan")
+        return null;
+    if (typeof raw.repoName !== "string" || !raw.repoName ||
+        typeof raw.epicRunId !== "string" || !raw.epicRunId ||
+        typeof raw.ticketKey !== "string" || !raw.ticketKey ||
+        (raw.route !== "test" && raw.route !== "implementation") ||
+        typeof raw.reason !== "string" || !raw.reason ||
+        !isNonNegativeInteger(raw.parkGeneration) ||
+        !isNonNegativeInteger(raw.expectedRowVersion) ||
+        typeof raw.operationKey !== "string" ||
+        !REGENERATE_PLAN_OPERATION_KEY_PATTERN.test(raw.operationKey) ||
+        typeof raw.fingerprint !== "string") {
+        return null;
+    }
+    const ref = {
+        version: 1,
+        operation: "regenerate_plan",
+        repoName: raw.repoName,
+        epicRunId: raw.epicRunId,
+        ticketKey: raw.ticketKey,
+        route: raw.route,
+        reason: raw.reason,
+        parkGeneration: raw.parkGeneration,
+        expectedRowVersion: raw.expectedRowVersion,
+        operationKey: raw.operationKey,
+        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 computeRegeneratePlanFingerprint(ref) === ref.fingerprint ? ref : null;
+}
+/**
+ * Answer a named plan failure with one forced regeneration, its operation pinned.
+ *
+ * A pinned reference for this ticket is REUSED as-is — same operation key, same
+ * route, same park generation — so a lost response or a restarted process is
+ * answered from the server's durable record, and a later park is never silently
+ * targeted. Only when no reference exists is the park identity read (once) from
+ * authenticated ticket state, and the reference is stored BEFORE the first POST.
+ *
+ * At most {@link REGENERATE_PLAN_POST_LIMIT} POSTs, all with the same key, route
+ * and park generation. A row-version conflict refreshes the row version ONLY while
+ * the park identity still matches; otherwise the result is `stale_subject` and
+ * nothing more is sent. There is no fallback to unpark or any other mutation.
+ */
+export async function regeneratePlanOnce(access, options, deps = {}) {
+    const fetchState = deps.fetchState ?? fetchEpicRunState;
+    const post = deps.post ?? regeneratePlanTicket;
+    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 = parseRegeneratePlanReference(await readRecoveryReferenceFile(REGENERATE_PLAN_REFERENCE_NAMESPACE, callerKey, store));
+    if (reference !== null && reference.repoName !== access.repoName)
+        reference = null;
+    const reusedReference = reference !== null;
+    if (reference !== null && reference.route !== options.route) {
+        // An earlier operation is pinned on a different route and may be unconfirmed.
+        // Sending a second route could answer the same park twice, so nothing is sent.
+        return { kind: "pinned_mismatch", pinnedRoute: reference.route };
+    }
+    const persist = async (ref) => {
+        await writeRecoveryReferenceFile(REGENERATE_PLAN_REFERENCE_NAMESPACE, callerKey, ref, store);
+        if (ref.epicRunId !== callerKey.epicRunId || ref.ticketKey !== callerKey.ticketKey) {
+            await writeRecoveryReferenceFile(REGENERATE_PLAN_REFERENCE_NAMESPACE, { epicRunId: ref.epicRunId, ticketKey: ref.ticketKey }, ref, store);
+        }
+    };
+    const clear = async (ref) => {
+        await clearRecoveryReferenceFile(REGENERATE_PLAN_REFERENCE_NAMESPACE, callerKey, store);
+        await clearRecoveryReferenceFile(REGENERATE_PLAN_REFERENCE_NAMESPACE, { epicRunId: ref.epicRunId, ticketKey: ref.ticketKey }, 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 = captureRegeneratePlanSubject(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,
+            route: options.route,
+            reason: options.reason.slice(0, REGENERATE_PLAN_REASON_MAX_CHARS),
+            parkGeneration: captured.parkGeneration,
+            operationKey: (deps.newOperationKey ?? randomUUID)(),
+        };
+        reference = {
+            version: 1,
+            operation: "regenerate_plan",
+            ...identity,
+            expectedRowVersion: ticket.row_version,
+            fingerprint: computeRegeneratePlanFingerprint(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",
+            };
+        }
+    }
+    let ref = reference;
+    let last = null;
+    for (let attempt = 1; attempt <= REGENERATE_PLAN_POST_LIMIT; attempt += 1) {
+        if (attempt > 1)
+            await sleep(REGENERATE_PLAN_RETRY_DELAY_MS * (attempt - 1));
+        const outcome = await post(access, {
+            epicRunId: ref.epicRunId,
+            ticketKey: ref.ticketKey,
+            route: ref.route,
+            reason: ref.reason,
+            expectedRowVersion: ref.expectedRowVersion,
+            parkGeneration: ref.parkGeneration,
+            operationKey: ref.operationKey,
+        });
+        last = outcome;
+        if (outcome.kind === "result") {
+            await clear(ref);
+            return { kind: outcome.result.outcome, result: outcome.result, reusedReference };
+        }
+        if (outcome.kind === "unsupported_server") {
+            // Nothing was written, and no other mutation stands in for this one.
+            await clear(ref);
+            return { kind: "unsupported_server", status: outcome.status };
+        }
+        if (outcome.kind === "uncertain")
+            continue;
+        if (outcome.kind === "refused" && outcome.errorCode === "PLAN_REGEN_BUSY")
+            continue;
+        if (outcome.kind === "refused" && outcome.errorCode === "CONFLICT") {
+            // Refresh the row version ONLY while the park identity is the same one.
+            const ticket = await readTicket();
+            if (ticket === "unavailable" || ticket === null) {
+                return { kind: "refused", errorCode: outcome.errorCode, status: outcome.status, reusedReference };
+            }
+            const current = captureRegeneratePlanSubject(ticket);
+            if (!current.ok || current.parkGeneration !== ref.parkGeneration) {
+                return { kind: "stale_subject", 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;
+        }
+        // A stale park is the subject changing: back to explain_run, nothing written.
+        if (outcome.kind === "refused" && outcome.errorCode === "PLAN_REGEN_STALE_PARK") {
+            await clear(ref);
+            return { kind: "stale_subject", reusedReference };
+        }
+        // Every other refusal or rejection is authoritative: nothing was written,
+        // and this operation is finished.
+        await clear(ref);
+        return {
+            kind: "refused",
+            errorCode: outcome.kind === "refused" ? outcome.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: REGENERATE_PLAN_POST_LIMIT };
+}

package/build/conductor/repair-contract.js

@@ -1,8 +1,9 @@
 /**
- * The shared contract for the eight operator repair verbs: BAPI-1154's
+ * The shared contract for the nine operator repair verbs: BAPI-1154's
  * `scope-reparse`, `dispatch-remediation`, and `merge-child`, BAPI-1176's
  * `scope-catch-up`, `patch-policy`, and `resume-run`, BAPI-1326's
- * ticket-addressed `resume-ci`, and BAPI-1388's ticket-addressed `rerun-ci`.
+ * ticket-addressed `resume-ci`, BAPI-1388's ticket-addressed `rerun-ci`, and
+ * BAPI-1494's ticket-addressed `resolve-handoff`.
  *
  * CLI-only, exactly like the BAPI-872 recovery verbs: none of these names is ever
  * registered as an MCP tool (`index-static.test.ts` pins that). This module is the
@@ -23,6 +24,7 @@ export const VERB_PATCH_POLICY = "patch-policy";
 export const VERB_RESUME_RUN = "resume-run";
 export const VERB_RESUME_CI = "resume-ci";
 export const VERB_RERUN_CI = "rerun-ci";
+export const VERB_RESOLVE_HANDOFF = "resolve-handoff";
 /** Every repair verb, in the order an operator meets them. */
 export const OPERATOR_REPAIR_VERBS = [
     VERB_SCOPE_REPARSE,
@@ -33,6 +35,7 @@ export const OPERATOR_REPAIR_VERBS = [
     VERB_RESUME_RUN,
     VERB_RESUME_CI,
     VERB_RERUN_CI,
+    VERB_RESOLVE_HANDOFF,
 ];
 /**
  * The ONE cap on driver context, in UTF-8 BYTES — the same number the server
@@ -113,6 +116,14 @@ export const OPERATOR_REPAIR_REFUSAL_CODES = [
     // BAPI-1333
     "GUIDED_REPAIR_DISABLED",
     "REPAIR_SUBJECT_STALE",
+    // BAPI-1494
+    "HANDOFF_NOT_PENDING",
+    "HANDOFF_ALREADY_RESOLVED",
+    "RESOLUTION_ACTOR_UNAVAILABLE",
+    "EPIC_HEAD_UNREADABLE",
+    "HANDOFF_LEDGER_UNREADABLE",
+    "HANDOFF_RESOLUTION_CAPACITY",
+    "HANDOFF_SELECTION_CHANGED",
 ];
 /** True when `code` is one of the closed repair refusal codes. */
 export function isOperatorRepairRefusalCode(code) {
@@ -207,3 +218,37 @@ export const RERUN_CI_NOT_RUNNABLE_REASONS = [
 ];
 /** The closed overall outcomes of an applied `rerun-ci`. */
 export const RERUN_CI_OUTCOMES = ["enqueued", "partial", "nothing_to_enqueue"];
+// ---------------------------------------------------------------------------
+// BAPI-1494 — `resolve-handoff`
+// ---------------------------------------------------------------------------
+/**
+ * The closed `resolve-handoff` refusal subset — mirrors
+ * `RESOLVE_HANDOFF_REFUSAL_CODES` in `operator_repair_contract.py`.
+ */
+export const RESOLVE_HANDOFF_REFUSAL_CODES = [
+    "RESOLUTION_ACTOR_UNAVAILABLE",
+    "TICKET_NOT_IN_RUN",
+    "EPIC_HEAD_UNREADABLE",
+    "HANDOFF_LEDGER_UNREADABLE",
+    "HANDOFF_NOT_PENDING",
+    "HANDOFF_ALREADY_RESOLVED",
+    "HANDOFF_RESOLUTION_CAPACITY",
+    "HANDOFF_SELECTION_CHANGED",
+    "ROW_VERSION_CONFLICT",
+];
+/** True when `code` is one of the closed `resolve-handoff` refusal codes. */
+export function isResolveHandoffRefusalCode(code) {
+    return (typeof code === "string" &&
+        RESOLVE_HANDOFF_REFUSAL_CODES.includes(code));
+}
+/** The two decision kinds. `risk_accepted` is never shown as verified or passed. */
+export const HANDOFF_RESOLUTION_KINDS = ["verified", "risk_accepted"];
+/** The display label for each kind — the same labels the server uses. */
+export const HANDOFF_RESOLUTION_KIND_LABELS = {
+    verified: "verified",
+    risk_accepted: "risk accepted",
+};
+/** Bounds shared with the server (`HANDOFF_RESOLUTION_*` in `api/models/epic_run.py`). */
+export const HANDOFF_RESOLUTION_MAX_STEPS = 50;
+export const HANDOFF_RESOLUTION_EVIDENCE_REF_MAX_CHARS = 500;
+export const HANDOFF_RESOLUTION_REASON_MAX_CHARS = 2000;

package/build/conductor/repository-workflow-remedy.js

@@ -1,3 +1,4 @@
+import { CONSUMER_GUIDE_POINTER } from "../printed-remedy-commands.js";
 /** The two fixed workflow files unattended auto-merge reads. Named once here. */
 export const REVIEW_WORKFLOW_PATH = ".github/workflows/claude-review.yml";
 export const CI_WORKFLOW_PATH = ".github/workflows/epic-implementer-ci.yml";
@@ -5,8 +6,9 @@ export const CI_WORKFLOW_PATH = ".github/workflows/epic-implementer-ci.yml";
 export const MIGRATION_GUARD_JOB_ID = "migration-guard";
 export const MIGRATION_GUARD_CHECKER_PATH = "scripts/check_alembic_migration_graph.py";
 export const MIGRATION_GUARD_INVOCATION = `python ${MIGRATION_GUARD_CHECKER_PATH}`;
-const RETRY = "Run the readiness check again, or pass --attended. " +
-    "If it keeps failing, contact Bridge operations.";
+const RETRY = "Retry readiness, or use --attended.";
+/** Every workflow remedy ends with the guide a consumer can actually install. */
+const GUIDE_SENTENCE = `See ${CONSUMER_GUIDE_POINTER}.`;
 const TEMPLATES = {
     review_workflow_file: `${REVIEW_WORKFLOW_PATH} is missing from the default branch. Add it, or pass --attended.`,
     review_run_id_marker: `${REVIEW_WORKFLOW_PATH} does not emit the run-id: marker in its verdict comment. ` +
@@ -29,7 +31,7 @@ const TEMPLATES = {
         "Add that job, or pass --attended.",
 };
 /** Shown when the report is missing, incomplete, or not in a shape we can name. */
-const UNVERIFIABLE_FALLBACK = "Bridge could not verify the review and CI workflows on the default branch. " + RETRY;
+const UNVERIFIABLE_FALLBACK = `Bridge could not verify the review and CI workflows on the default branch. ${RETRY} ${GUIDE_SENTENCE}`;
 function classifyReview(w) {
     if (w === null || w === undefined || typeof w !== "object")
         return "malformed";
@@ -86,7 +88,7 @@ function classifyCi(c) {
  * unreadable, and otherwise the empty result below.
  */
 export function describeRepositoryWorkflowRemedy(readiness) {
-    const review = classifyReview(readiness?.review_workflow);
+    const review = readiness?.epic_branch_ci?.effective_review_mode === "verdict_protocol" ? classifyReview(readiness?.review_workflow) : [];
     if (review === "malformed") {
         return { section: null, missing: [], text: UNVERIFIABLE_FALLBACK };
     }
@@ -101,7 +103,7 @@ export function describeRepositoryWorkflowRemedy(readiness) {
     return { section: null, missing: [], text: "" };
 }
 function build(section, missing) {
-    return { section, missing, text: missing.map((token) => TEMPLATES[token]).join(" ") };
+    return { section, missing, text: `${missing.map((token) => TEMPLATES[token]).join(" ")} ${GUIDE_SENTENCE}` };
 }
 /**
  * The remedy sentence for a repository whose workflows are not confirmed. Never
@@ -121,5 +123,5 @@ export function ciWorkflowRemedy(c) {
     const tokens = classifyCi(c);
     if (tokens === "malformed" || tokens.length === 0)
         return UNVERIFIABLE_FALLBACK;
-    return tokens.map((token) => TEMPLATES[token]).join(" ");
+    return `${tokens.map((token) => TEMPLATES[token]).join(" ")} ${GUIDE_SENTENCE}`;
 }

package/build/conductor/stored-merge-credential.js

@@ -0,0 +1,76 @@
+/**
+ * Store-aware merge-credential resolution at privileged action boundaries
+ * (BAPI-1461).
+ *
+ * `merge-credential.ts` owns the precedence and stays free of filesystem and
+ * process dependencies. This module is the thin layer that binds it to one
+ * repository's stored entry, so every action boundary — a merge job, the
+ * `sync_base` integration action, the merge-child recovery verb, the
+ * `drive-epic` launch probe, and doctor — resolves the token the same way:
+ *
+ *   `GITHUB_MERGE_TOKEN` → `BAPI_LOCAL_MERGE_TOKEN` → the stored
+ *   `github-merge:github.com/<owner>/<repo>` entry.
+ *
+ * The store is read afresh at each call, never cached, so an executor that
+ * started before the token was stored still finds it when a merge runs.
+ *
+ * ELIGIBILITY is always an explicit input. A durable-host service executor
+ * (started with `--scrub-inherited-github-credentials`) passes `false` and so
+ * never reads a stored GitHub credential. Machine-user mode never reads it.
+ */
+import { execFile } from "node:child_process";
+import { readFile } from "node:fs/promises";
+import os from "node:os";
+import { readGithubMergeCredential, resolveGithubMergeRepositoryIdentity, } from "../credential-store.js";
+import { parseGithubRemote } from "../github-remote.js";
+import { resolveLocalMergeCredentialDetailedAsync, } from "./merge-credential.js";
+/** Real host-local read deps for the user-scoped credential store. */
+export function nodeGithubMergeCredentialReadDeps(env) {
+    return { env, homedir: os.homedir, readFile: (p) => readFile(p, "utf-8") };
+}
+/**
+ * Resolve one kind for a privileged action. The repository identity is settled
+ * BEFORE any store lookup: an unresolved or conflicting identity reads nothing,
+ * so a process can never pick up another repository's entry.
+ */
+export async function resolveMergeCredentialAtAction(env, kind, context) {
+    const allowed = kind === "local" &&
+        context.allowStoredEntry === true &&
+        (context.storeDeps !== undefined || context.readStored !== undefined);
+    const identity = allowed
+        ? resolveGithubMergeRepositoryIdentity({
+            providerRepository: context.providerRepository,
+            localRemote: context.localRemote,
+        })
+        : null;
+    const { storeDeps, readStored } = context;
+    const reader = identity === null || !identity.ok
+        ? undefined
+        : readStored !== undefined
+            ? () => readStored(identity.identity)
+            : storeDeps !== undefined
+                ? () => readGithubMergeCredential(identity.identity, storeDeps)
+                : undefined;
+    return resolveLocalMergeCredentialDetailedAsync(env, kind, {
+        allowStoredEntry: allowed && reader !== undefined,
+        ...(reader !== undefined ? { readStoredEntry: reader } : {}),
+    });
+}
+/** Bound on the one `git remote get-url origin` read. */
+const GIT_REMOTE_TIMEOUT_MS = 5_000;
+const defaultGitRemoteReader = (cwd) => new Promise((resolve) => {
+    execFile("git", ["remote", "get-url", "origin"], { cwd, timeout: GIT_REMOTE_TIMEOUT_MS, env: { ...process.env, GIT_TERMINAL_PROMPT: "0" } }, (error, stdout) => resolve(error ? null : String(stdout)));
+});
+/**
+ * The working tree's github.com `origin` as `owner/repo`, or null. Read-only;
+ * any failure (no git, no remote, a non-GitHub host) is null, never an error.
+ */
+export async function readLocalGithubRemote(cwd, readRemote = defaultGitRemoteReader) {
+    try {
+        const url = await readRemote(cwd);
+        return url === null ? null : parseGithubRemote(url);
+    }
+    catch {
+        return null;
+    }
+}

package/build/conductor/stored-merge-token-probe.js

@@ -0,0 +1,28 @@
+/**
+ * The production probe doctor and setup run against a STORED merge token
+ * (BAPI-1461).
+ *
+ * Kept out of `conductor/doctor.ts` so doctor never imports the merge executor:
+ * this module binds the shared, bounded, read-only capability probe
+ * (`probeLocalMergeCapability`: `gh --version`, `gh auth status`, two `gh api`
+ * GETs) and classifies its answer into the closed verdict doctor understands.
+ * The token reaches only the probe's restricted child environment; nothing here
+ * returns, logs, or prints it.
+ */
+import { classifyLocalGhPreflight, probeLocalMergeCapability, } from "./local-merge.js";
+/** Probe one stored token against one `owner/repo`, returning a closed verdict. */
+export async function probeStoredMergeToken(args) {
+    try {
+        const verdict = classifyLocalGhPreflight(await probeLocalMergeCapability({
+            kind: "local",
+            repository: args.repository,
+            resolved: { credential: args.credential, invalid: false },
+        }, { env: args.env ?? process.env }));
+        if (verdict === "passed" || verdict === "credential_invalid" || verdict === "no_access")
+            return verdict;
+        return "unavailable";
+    }
+    catch {
+        return "unavailable";
+    }
+}

package/build/conductor/temporary-plan.js

@@ -0,0 +1,50 @@
+/**
+ * Scoped private temporary plan file for a trimmed epic plan (BAPI-1510).
+ *
+ * `withPlanPath` hands a callback either the operator's original plan path (when
+ * nothing is skipped — no filesystem work happens) or a private path holding the
+ * trimmed JSON. The temporary directory is created only when needed, the file is
+ * created exclusively with mode 0600, and the whole directory is removed in a
+ * `finally` after success and failure alike. A cleanup failure produces one
+ * sanitized warning (no path, no exception text) and never replaces the callback's
+ * result or error.
+ */
+import { mkdtemp, open, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+export function createDefaultTemporaryPlanFs() {
+    return {
+        mkdtemp: (prefix) => mkdtemp(prefix),
+        writeExclusive: async (path, data, mode) => {
+            const handle = await open(path, "wx", mode);
+            try {
+                await handle.writeFile(data, "utf8");
+            }
+            finally {
+                await handle.close();
+            }
+        },
+        rmDir: (path) => rm(path, { recursive: true, force: true }),
+        tmpdir: () => tmpdir(),
+    };
+}
+export const TEMPORARY_PLAN_CLEANUP_WARNING = "Could not remove a temporary plan file; it is private to your user and safe to delete.";
+export async function withPlanPath(options, callback) {
+    if (!options.skipped)
+        return callback(options.originalPath);
+    const fs = options.fs ?? createDefaultTemporaryPlanFs();
+    const dir = await fs.mkdtemp(join(fs.tmpdir(), "bridge-trimmed-plan-"));
+    try {
+        const planPath = join(dir, "epic-plan.dag.json");
+        await fs.writeExclusive(planPath, options.trimmedJson, 0o600);
+        return await callback(planPath);
+    }
+    finally {
+        try {
+            await fs.rmDir(dir);
+        }
+        catch {
+            options.warn(TEMPORARY_PLAN_CLEANUP_WARNING);
+        }
+    }
+}