@bridge_gpt/mcp-server 0.2.67 → 0.2.69

package/build/conductor/readiness.js

@@ -92,17 +92,17 @@
  * unrelated additive change look like a breaking one here, or worse, hide a real
  * one.
  */
-import { PRINTED_CHECK_NAME_INSTRUCTION, PRINTED_CONDUCTOR_EXECUTOR_INSTALL_COMMAND, PRINTED_CONDUCTOR_INSTALL_COMMAND, PRINTED_CONNECT_GITHUB_COMMAND, PRINTED_EXECUTOR_ID_INSTRUCTION, } from "../printed-remedy-commands.js";
+import { PRINTED_CHECK_NAME_INSTRUCTION, PRINTED_CONDUCTOR_EXECUTOR_INSTALL_COMMAND, PRINTED_CONDUCTOR_INSTALL_COMMAND, PRINTED_CONNECT_GITHUB_COMMAND, PRINTED_EXECUTOR_ID_INSTRUCTION, PRINTED_QUALIFY_GATE_COMMAND, } from "../printed-remedy-commands.js";
 import { mapConductorDoctorReportToReadinessChecks, } from "./doctor.js";
 import { mapInstallStatusChecksToReadinessChecks, } from "../install-doctor.js";
 import { mapPlanePreflightToReadinessChecks, } from "../plane/preflight.js";
 import { runConductorInstallDoctor, } from "./install-doctor.js";
-import { BRING_UP_SECTION_LABELS, presentRequiredChecks, } from "./readiness-sections.js";
+import { BRING_UP_SECTION_LABELS, describeGateProfile, describeGateProfileWarning, effectiveReviewModeIsRepositoryPolicy, EPIC_BRANCH_CI_SECTION_IDS, epicBranchCiSections, presentRequiredChecks, quotedSubject, } from "./readiness-sections.js";
 import { classifyBringUpFacts } from "./bring-up-facts.js";
 import { CI_WORKFLOW_PATH, REVIEW_WORKFLOW_PATH, ciWorkflowRemedy, repositoryWorkflowRemedy, } from "./repository-workflow-remedy.js";
 import { classifyMergeExecutionEligibility, MERGE_EXECUTION_INELIGIBLE_REMEDIATION, MERGE_EXECUTION_UNVERIFIABLE_REMEDIATION, } from "./merge-execution-eligibility.js";
 import { createReadinessCheck, createReadinessCheckSafely, summarizeReadinessChecks, validateReadinessChecks, } from "../readiness-check.js";
-import { ADMISSION_EVIDENCE_SCHEMA_VERSION, } from "./bridge-api-client.js";
+import { ADMISSION_EVIDENCE_SCHEMA_VERSION, gateProfileWaivesCiWorkflow, } from "./bridge-api-client.js";
 /** This report's own schema version. See the module docstring. */
 export const CONDUCTOR_READINESS_GATE_SCHEMA_VERSION = 1;
 /** Fixed statement carried in every report, so no consumer can mistake it for a gate. */
@@ -359,7 +359,17 @@ export function mapServerReadinessToChecks(readiness, failure = "unreachable") {
     });
     // BAPI-1260 — appended ONLY when the server reported the block, so every
     // pre-BAPI-1260 report keeps exactly the descriptor set above.
-    return [...described, ...admissionEvidenceChecks(readiness), ...genericDiagnosticChecks(readiness)];
+    return [
+        ...described,
+        ...admissionEvidenceChecks(readiness),
+        // BAPI-1390 — appended ONLY when the server reported a gate profile.
+        ...gateProfileChecks(readiness),
+        // BAPI-1405 — always three warn-only epic-branch CI rows. An older server
+        // that omits the block renders them as "Unreported — upgrade the server",
+        // never as "no warning".
+        ...epicBranchCiChecks(readiness),
+        ...genericDiagnosticChecks(readiness),
+    ];
 }
 function genericDiagnosticChecks(readiness) {
     return (readiness.diagnostics ?? []).map((diagnostic, index) => {
@@ -432,10 +442,156 @@ function admissionReasonRemedy(record, readiness) {
             return (`a repository administrator replaces ${RETIRED_GATE_NAME} with ${CURRENT_GATE_NAME} in the plan's ` +
                 "required_checks, in the supervisor done-gate checks, and in branch protection." +
                 (ciAbsent ? ` Also add ${CI_WORKFLOW_PATH} to the default branch so ${CURRENT_GATE_NAME} has a producer.` : ""));
+        default:
+            return gateProfileReasonRemedy(record.reason, record.verdict, record.subject ?? null);
+    }
+}
+/** The provider-evidence window the server searches, spelled once for the remedies. */
+const PROVIDER_EVIDENCE_WINDOW = "the last 12 default-branch commits or 8 merged pull-request heads from the last 90 days";
+/**
+ * BAPI-1390 — fixed remedies for the four gate-profile reasons. Everything is a
+ * literal except the validated `subject`. `null` for any other reason, so an
+ * unknown reason falls back to the owner's generic remedy.
+ */
+function gateProfileReasonRemedy(reason, verdict, subject) {
+    switch (reason) {
+        case "provider_check_unseen":
+            return (`a repository administrator confirms that the check ${quotedSubject(subject, "named in the gate profile")} ` +
+                `reports on the default branch — it was not seen on ${PROVIDER_EVIDENCE_WINDOW} — or edits the gate ` +
+                "profile; setup never grants it.");
+        case "provider_evidence_unavailable":
+            return (`Bridge could not read the provider's check history for ${quotedSubject(subject, "a gate-profile check")} ` +
+                `(${PROVIDER_EVIDENCE_WINDOW}), so it is unknown, not absent. Re-run readiness; if it persists, ` +
+                "escalate to Bridge operations.");
+        case "local_command_unqualified":
+            return verdict === "unable_to_verify"
+                ? `the qualification of the local gate command ${quotedSubject(subject, "in the gate profile")} could not ` +
+                    "be read, so it is unknown, not qualified. Re-run readiness; if it persists, escalate to Bridge operations."
+                : `the local gate command ${quotedSubject(subject, "in the gate profile")} is not qualified for the current ` +
+                    "gate-profile revision (unqualified or stale). Qualify it with " +
+                    `\`${PRINTED_QUALIFY_GATE_COMMAND}\`, or have a repository administrator ` +
+                    "edit the gate profile.";
+        case "migration_guard_unset":
+            return verdict === "unable_to_verify"
+                ? "Bridge could not confirm whether this repository has alembic.ini on its default branch, so it could " +
+                    "not decide whether the gate profile needs a migration guard. Re-run readiness, or have a repository " +
+                    "administrator set a migration guard in the gate profile."
+                : "this repository has alembic.ini on its default branch, so its gate profile must name a migration " +
+                    "guard (a provider check or a local command). A repository administrator sets it in the gate " +
+                    "profile; setup never grants it.";
         default:
             return null;
     }
 }
+const GATE_PROFILE_WARNING_REMEDIATION = "no action is needed to launch; confirm the check reports once an epic branch runs CI.";
+/**
+ * BAPI-1390 — the gate-profile row plus one warn row per warning. Appended
+ * ONLY when the server reported the block, so an older server's report is
+ * unchanged. The row is descriptive: the server's admission evidence is the
+ * authority, and the warning rows never hold a launch.
+ */
+export function gateProfileChecks(readiness) {
+    const profile = readiness.gate_profile;
+    if (profile === undefined)
+        return [];
+    if (profile === null) {
+        return [
+            createReadinessCheckSafely({
+                id: "server.gate-profile",
+                source: "server",
+                label: "Gate profile",
+                status: "fail",
+                detail: "the server reported no gate profile, so the CI gate is unverified",
+                remediation: SERVER_REMEDIATIONS.olderServer,
+            }),
+        ];
+    }
+    const detail = describeGateProfile(profile);
+    let row;
+    if (profile.read_failed || profile.stored_malformed) {
+        row = createReadinessCheckSafely({
+            id: "server.gate-profile",
+            source: "server",
+            label: "Gate profile",
+            status: "fail",
+            detail: `${profile.read_failed ? "the stored gate profile could not be read" : "the stored gate profile is malformed"} — ${detail}`,
+            remediation: profile.read_failed
+                ? "re-run readiness; if it persists, escalate to Bridge operations."
+                : "a repository administrator re-saves the gate profile; setup never grants it.",
+        });
+    }
+    else if (profile.verdict === "denied" || profile.verdict === "unable_to_verify") {
+        row = createReadinessCheckSafely({
+            id: "server.gate-profile",
+            source: "server",
+            label: "Gate profile",
+            status: "fail",
+            detail: `${profile.verdict === "denied" ? "DENIED" : "could not be verified"}${profile.reason ? ` (${profile.reason})` : ""} — ${detail}`,
+            remediation: gateProfileReasonRemedy(profile.reason, profile.verdict, profile.subject) ??
+                (profile.verdict === "denied"
+                    ? ADMISSION_OWNER_REMEDIATION.repository_admin
+                    : ADMISSION_OWNER_REMEDIATION.bridge_operations),
+        });
+    }
+    else if (profile.verdict === "confirmed" && profile.kind !== "none") {
+        row = createReadinessCheckSafely({
+            id: "server.gate-profile",
+            source: "server",
+            label: "Gate profile",
+            status: "pass",
+            detail,
+        });
+    }
+    else {
+        row = createReadinessCheckSafely({
+            id: "server.gate-profile",
+            source: "server",
+            label: "Gate profile",
+            status: "warn",
+            detail,
+            remediation: profile.kind === "none"
+                ? "no action is needed to launch; to let child merges proceed without approval, a repository administrator adds checks to the gate profile."
+                : "a repository administrator confirms the gate profile; the server's launch evidence decides whether a run is held.",
+        });
+    }
+    const warnings = profile.warnings.map((warning, index) => createReadinessCheckSafely({
+        id: `server.gate-profile-warning-${index + 1}`,
+        source: "server",
+        label: "Gate profile warning",
+        status: "warn",
+        detail: describeGateProfileWarning(warning.code, warning.name),
+        remediation: GATE_PROFILE_WARNING_REMEDIATION,
+    }));
+    return [row, ...warnings];
+}
+/**
+ * BAPI-1405 — the three warn-only epic-branch CI rows as `server.*` checks:
+ * `server.effective-review-mode`, `server.epic-branch-ci-decision`, and
+ * `server.epic-branch-ci-coverage-warning`.
+ *
+ * Built from the SAME shared sections the install doctor renders, so the two
+ * surfaces cannot word one fact apart. Status is only ever `pass` or `warn`:
+ * these rows never fail, never hold a launch, and feed no verdict.
+ *
+ * Unlike `gateProfileChecks`, an absent or `null` block (older server) still
+ * yields the three rows, each `warn` with "Unreported — upgrade the server" and
+ * the upgrade remediation. Emitting nothing would read as "no warning", which
+ * is the wrong answer: the server simply did not say. Omitted and `null` render
+ * identically. The install doctor's own copies of these sections are filtered
+ * by `INSTALL_SECTION_IDS_OWNED_ELSEWHERE`, so each row still appears once.
+ */
+export function epicBranchCiChecks(readiness) {
+    return epicBranchCiSections(readiness.epic_branch_ci).map((section) => createReadinessCheckSafely({
+        id: `server.${section.id}`,
+        source: "server",
+        label: section.label,
+        status: section.status === "ok" ? "pass" : "warn",
+        detail: section.detail,
+        ...(section.status === "ok" || section.remediation === undefined
+            ? {}
+            : { remediation: section.remediation }),
+    }));
+}
 /**
  * Project the server's typed launch evidence (BAPI-1260) into `server.*`
  * checks, read-only.
@@ -626,11 +782,12 @@ function unattendedOutcomes(readiness) {
                 detail: readiness.review_workflow?.probe_succeeded === true &&
                     readiness.review_workflow?.workflow_present === false
                     ? `${REVIEW_WORKFLOW_PATH} is missing from the default branch — an unattended auto-merging run will be refused`
-                    : readiness.conductor_ci_workflow?.probe_succeeded === true &&
+                    : !gateProfileWaivesCiWorkflow(readiness) &&
+                        readiness.conductor_ci_workflow?.probe_succeeded === true &&
                         readiness.conductor_ci_workflow?.workflow_present === false
                         ? `${CI_WORKFLOW_PATH} is missing from the default branch — an unattended auto-merging run will be refused`
                         : "the review and epic-implementer-ci workflows are not both confirmed — an unattended auto-merging run will be refused",
-                remediation: repositoryWorkflowRemedy(readiness),
+                remediation: gateProfileAwareRepositoryWorkflowRemedy(readiness),
             },
     ];
 }
@@ -639,6 +796,15 @@ function reviewPolicyOutcome(readiness) {
     const s = readiness.supervisor;
     const alignment = s.review_policy_alignment;
     if (alignment !== null) {
+        // BAPI-1405 — `repository_policy` requires no review verdict, so a divergent
+        // done-gate review signal is not a nag. `invalid` still warns.
+        if (alignment.status === "divergent" && effectiveReviewModeIsRepositoryPolicy(readiness)) {
+            return {
+                id: "review-policy",
+                status: "pass",
+                detail: "alignment not applicable: the effective review mode is 'repository_policy', which requires no review verdict",
+            };
+        }
         if (alignment.status === "divergent" || alignment.status === "invalid") {
             return {
                 id: "review-policy",
@@ -839,7 +1005,23 @@ function executorOutcome(readiness) {
         remediation: SERVER_REMEDIATIONS.executorNeverSeen,
     };
 }
-/** Review-workflow protocol facts. `null` means an older server, not health. */
+/**
+ * BAPI-1390 — the repository-workflow remedy under the server's gate-profile
+ * rule: with a STORED gate profile the CI lane file is not required, so the
+ * remedy never names it. Without one, this is exactly
+ * {@link repositoryWorkflowRemedy}.
+ */
+export function gateProfileAwareRepositoryWorkflowRemedy(readiness) {
+    return repositoryWorkflowRemedy(gateProfileWaivesCiWorkflow(readiness) ? { ...readiness, conductor_ci_workflow: null } : readiness);
+}
+/**
+ * Review-workflow protocol facts. `null` means an older server, not health.
+ *
+ * BAPI-1390: the server now requires the review file only for a run whose review
+ * policy source is `verdict_protocol`. This repository-scoped report carries no
+ * run policy, so the row keeps its existing behavior; the per-run decision is the
+ * server's (`unattended.repository_readiness_confirmed` and admission evidence).
+ */
 function reviewWorkflowOutcome(readiness) {
     const w = readiness.review_workflow;
     if (w === null) {
@@ -892,6 +1074,16 @@ function reviewWorkflowOutcome(readiness) {
 /** Conductor-CI migration-guard facts. `null` means an older server. */
 function ciWorkflowOutcome(readiness) {
     const c = readiness.conductor_ci_workflow;
+    // BAPI-1390 — a STORED gate profile names its own checks and migration guard,
+    // so the lane file is not required. A healthy file still reports a pass; any
+    // other state is reported as not applicable rather than as a gap.
+    if (gateProfileWaivesCiWorkflow(readiness) && !(c?.probe_succeeded === true && c.migration_guard_present === true)) {
+        return {
+            id: "conductor-ci-workflow",
+            status: "skip",
+            detail: `${CI_WORKFLOW_PATH} is not required: this repository has a stored gate profile that names its own checks`,
+        };
+    }
     if (c === null) {
         return {
             id: "conductor-ci-workflow",
@@ -974,6 +1166,15 @@ const INSTALL_SECTION_IDS_OWNED_ELSEWHERE = new Set([
     "supervisor-configuration",
     "supervisor-required-checks",
     "supervisor-review-alignment",
+    // BAPI-1390 — owned by `gateProfileChecks`.
+    "supervisor-gate-profile",
+    "supervisor-gate-profile-epic-branch-unseen",
+    "supervisor-gate-profile-epic-branch-search",
+    "supervisor-gate-profile-warning",
+    // BAPI-1405 — owned by `epicBranchCiChecks`.
+    EPIC_BRANCH_CI_SECTION_IDS.reviewMode,
+    EPIC_BRANCH_CI_SECTION_IDS.decision,
+    EPIC_BRANCH_CI_SECTION_IDS.coverage,
     "github-credentials",
     "github-actions-permission",
     "reconciler-liveness",
@@ -1059,7 +1260,9 @@ export async function collectConductorReadinessGate(deps) {
         ...mapInstallStatusChecksToReadinessChecks((installReport?.legacyInstallChecks ?? null), installReport === null),
         ...mapConductorDoctorReportToReadinessChecks(installReport?.legacyConductor ?? null),
         ...mapInstallSectionsToReadinessChecks(installReport?.sections ?? null),
-        ...mapPlanePreflightToReadinessChecks(planeResult, deps.planeNotApplicable),
+        ...mapPlanePreflightToReadinessChecks(planeResult, deps.planeNotApplicable, {
+            ...(deps.epicRunId !== undefined ? { epicRunId: deps.epicRunId } : {}),
+        }),
         ...mapServerReadinessToChecks(installReport?.readiness ?? null, classifyServerFailure(installReport)),
     ];
     // Validate the ASSEMBLED report, not just the pieces: an injected collector or

package/build/conductor/recovery-cli.js

@@ -122,7 +122,7 @@ function parseRunRecoveryArgs(argv) {
     return { epicRunId: epicRunId.trim(), json: bools.has("--json"), help: false };
 }
 function parseTicketRecoveryArgs(argv) {
-    const { values, bools } = tokenizeRecoveryFlags(argv, TICKET_VALUE_FLAGS, RECOVERY_BOOL_FLAGS);
+    const { values, bools } = tokenizeRecoveryFlags(argv, new Set([...TICKET_VALUE_FLAGS, "--reason", "--cleanup-resolution"]), RECOVERY_BOOL_FLAGS);
     if (bools.has("--help")) {
         return { epicRunId: "", ticketKey: "", json: bools.has("--json"), help: true };
     }
@@ -137,6 +137,10 @@ function parseTicketRecoveryArgs(argv) {
     return {
         epicRunId: epicRunId.trim(),
         ticketKey: ticketKey.trim(),
+        ...(values.get("--reason") ? { reason: values.get("--reason").trim() } : {}),
+        ...(values.get("--cleanup-resolution") ? {
+            cleanupResolution: values.get("--cleanup-resolution"),
+        } : {}),
         json: bools.has("--json"),
         help: false,
     };
@@ -263,7 +267,7 @@ export async function runAbandonRunCommand(argv) {
 // unpark / adopt-current-head-and-unpark (shared rendering)
 // ---------------------------------------------------------------------------
 const UNPARK_USAGE = [
-    "Usage: epic-implementer unpark --epic-run-id <id> --ticket-key <key> [--json]",
+    "Usage: epic-implementer unpark --epic-run-id <id> --ticket-key <key> [--cleanup-resolution confirmed|risk_accepted --reason <text>] [--json]",
     "",
     "Move a parked (needs_human) ticket back into its gate machine, once the",
     "operator has resolved what parked it. Retries a bounded number of times on",
@@ -337,6 +341,13 @@ export function renderTicketRecoveryResult(result, json) {
 export async function runUnparkCommand(argv) {
     try {
         const parsed = parseTicketRecoveryArgs(argv);
+        if (parsed.cleanupResolution !== undefined &&
+            !["confirmed", "risk_accepted"].includes(parsed.cleanupResolution)) {
+            throw new ConductorValidationError("--cleanup-resolution must be confirmed or risk_accepted.");
+        }
+        if (parsed.cleanupResolution !== undefined && !parsed.reason) {
+            throw new ConductorValidationError("--cleanup-resolution requires --reason.");
+        }
         if (parsed.help) {
             console.log(UNPARK_USAGE);
             return 0;
@@ -348,6 +359,8 @@ export async function runUnparkCommand(argv) {
         const result = await unparkEpicTicketWithRetry(access, {
             epicRunId: parsed.epicRunId,
             ticketKey: parsed.ticketKey,
+            reason: parsed.reason,
+            cleanupResolution: parsed.cleanupResolution,
         });
         return renderTicketRecoveryResult(result, parsed.json);
     }
@@ -359,6 +372,9 @@ export async function runUnparkCommand(argv) {
 export async function runAdoptCurrentHeadAndUnparkCommand(argv) {
     try {
         const parsed = parseTicketRecoveryArgs(argv);
+        if (parsed.cleanupResolution !== undefined || parsed.reason !== undefined) {
+            throw new ConductorValidationError("Cleanup resolution applies only to unpark.");
+        }
         if (parsed.help) {
             console.log(ADOPT_CURRENT_HEAD_USAGE);
             return 0;
@@ -1320,11 +1336,11 @@ export async function runResumeRunCommand(argv) {
 // ---------------------------------------------------------------------------
 // continue-child / continuation-receipt (BAPI-1300)
 // ---------------------------------------------------------------------------
-const CONTINUE_CHILD_VALUE_FLAGS = new Set(["--epic-run-id", "--ticket-key", "--reason"]);
+const CONTINUE_CHILD_VALUE_FLAGS = new Set(["--epic-run-id", "--ticket-key", "--reason", "--worker-exit-proof"]);
 const CONTINUATION_RECEIPT_VALUE_FLAGS = new Set(["--epic-run-id", "--ticket-key", "--request-id"]);
 const MAX_REASON_CHARS = 500;
 const CONTINUE_CHILD_USAGE = [
-    "Usage: epic-implementer continue-child --epic-run-id <id> --ticket-key <key> [--reason <text>] [--json]",
+    "Usage: epic-implementer continue-child --epic-run-id <id> --ticket-key <key> [--reason <text> --worker-exit-proof exited|fenced] [--json]",
     "",
     "Continue a parked child's CURRENT park episode without resetting it: the same",
     "attempt resumes on its retained work with only the allowance it has left (no",
@@ -1351,6 +1367,13 @@ function parseContinuationArgs(argv, valueFlags) {
     const epicRunId = requireFlag(values, "--epic-run-id");
     const ticketKey = requireFlag(values, "--ticket-key");
     const reason = values.get("--reason")?.trim();
+    const workerExitProof = values.get("--worker-exit-proof")?.trim();
+    if (workerExitProof !== undefined && workerExitProof !== "exited" && workerExitProof !== "fenced") {
+        throw new ConductorValidationError('Flag "--worker-exit-proof" must be exited or fenced.');
+    }
+    if (workerExitProof !== undefined && !reason) {
+        throw new ConductorValidationError('Flag "--worker-exit-proof" requires --reason.');
+    }
     if (reason !== undefined && reason.length > MAX_REASON_CHARS) {
         throw new ConductorValidationError(`Flag "--reason" must be at most ${MAX_REASON_CHARS} characters.`);
     }
@@ -1362,6 +1385,7 @@ function parseContinuationArgs(argv, valueFlags) {
         epicRunId,
         ticketKey,
         ...(reason ? { reason } : {}),
+        ...(workerExitProof ? { workerExitProof: workerExitProof } : {}),
         ...(requestId ? { requestId } : {}),
         json: bools.has("--json"),
         help: false,
@@ -1579,6 +1603,7 @@ export async function runContinueChildCommand(argv) {
             epicRunId: parsed.epicRunId,
             ticketKey: parsed.ticketKey,
             ...(parsed.reason ? { reason: parsed.reason } : {}),
+            ...(parsed.workerExitProof ? { workerExitProof: parsed.workerExitProof } : {}),
         });
         return renderContinueChildResult(result, parsed, parsed.json);
     }
@@ -1587,6 +1612,60 @@ export async function runContinueChildCommand(argv) {
         return 1;
     }
 }
+/** Explicit, bounded grant for the current parked attempt. */
+export async function runGrantContinuationCommand(argv) {
+    try {
+        const { values, bools } = tokenizeRecoveryFlags(argv, new Set(["--epic-run-id", "--ticket-key", "--extra-continuations", "--extra-seconds", "--reason", "--request-id"]), RECOVERY_BOOL_FLAGS);
+        if (bools.has("--help")) {
+            console.log("Usage: epic-implementer grant-continuation --epic-run-id <id> --ticket-key <key> --reason <text> [--extra-continuations 1] [--extra-seconds <1..3600>] [--request-id <id>] [--json]");
+            return 0;
+        }
+        const epicRunId = requireFlag(values, "--epic-run-id");
+        const ticketKey = requireFlag(values, "--ticket-key");
+        const reason = requireFlag(values, "--reason");
+        const extraContinuations = Number(values.get("--extra-continuations") ?? "0");
+        const extraSeconds = Number(values.get("--extra-seconds") ?? "0");
+        if (!Number.isInteger(extraContinuations) || extraContinuations < 0 || extraContinuations > 1 ||
+            !Number.isInteger(extraSeconds) || extraSeconds < 0 || extraSeconds > 3600 ||
+            (extraContinuations === 0 && extraSeconds === 0) || reason.length > MAX_REASON_CHARS) {
+            throw new ConductorValidationError("Grant amounts or reason are outside the allowed bounds.");
+        }
+        const explicitRequestId = values.get("--request-id");
+        if (explicitRequestId !== undefined && !/^[A-Za-z0-9][A-Za-z0-9._:-]{7,63}$/.test(explicitRequestId)) {
+            throw new ConductorValidationError("--request-id is malformed.");
+        }
+        const json = bools.has("--json");
+        const access = await resolveRecoveryAccess(json);
+        if (!access)
+            return 1;
+        const { grantContinuationOnce } = await import("./recovery-operations.js");
+        const operation = await grantContinuationOnce(access, {
+            epicRunId, ticketKey, extraContinuations, extraSeconds, reason,
+            ...(explicitRequestId !== undefined ? { requestId: explicitRequestId } : {}),
+        });
+        if (operation.kind === "not_parked") {
+            throw new ConductorValidationError("The child is not parked at a continuable gate.");
+        }
+        if (operation.kind === "unavailable") {
+            console.error(`Error: ${operation.message}`);
+            return 1;
+        }
+        const { requestId, outcome: result } = operation;
+        if (json)
+            console.log(JSON.stringify({ ...result, request_id: requestId }));
+        else if (result.kind === "result")
+            console.log(`Grant ${result.replayed ? "replayed" : "committed"}: ${requestId}. The child remains parked.`);
+        else if (result.kind === "unconfirmed")
+            console.error(`Grant outcome unconfirmed. Rerun the same command; it reuses request ${requestId}.`);
+        else
+            console.error(`Grant refused (${result.status}${result.errorCode ? `, ${result.errorCode}` : ""}).`);
+        return result.kind === "result" ? 0 : 1;
+    }
+    catch (error) {
+        console.error(`Error: ${toConductorErrorEnvelope(error).message}`);
+        return 1;
+    }
+}
 export async function runContinuationReceiptCommand(argv) {
     try {
         const parsed = parseContinuationReceiptArgs(argv);
@@ -1845,3 +1924,30 @@ export async function runResumeCiCommand(argv) {
         return RESUME_CI_EXIT_FAILED;
     }
 }
+/** No state mutation: callers halt the affected work before asking a question. */
+export async function runEscalateCommand(argv, deps = {}) {
+    try {
+        const { values, bools } = tokenizeRecoveryFlags(argv, new Set(["--epic-run-id", "--ticket-key", "--cause", "--action-needed"]), RECOVERY_BOOL_FLAGS);
+        if (bools.has("--help")) {
+            console.log("Usage: epic-implementer escalate --epic-run-id <id> --ticket-key <key> --cause <cause> --action-needed <text> [--json]");
+            return 0;
+        }
+        const request = { epicRunId: requireFlag(values, "--epic-run-id"),
+            ticketKey: requireFlag(values, "--ticket-key"), cause: requireFlag(values, "--cause"),
+            actionNeeded: requireFlag(values, "--action-needed") };
+        if (request.actionNeeded.length > 300) {
+            console.error("Error: action-needed exceeds 300 characters");
+            return 1;
+        }
+        const access = await (deps.resolveAccess ?? (() => resolveRecoveryAccess(false)))();
+        if (!access)
+            return 1;
+        const escalate = deps.escalate ?? (await import("./bridge-api-client.js")).escalateTicket;
+        console.log(JSON.stringify(await escalate(access, request)));
+        return 0;
+    }
+    catch {
+        console.error("Error: escalation request refused or unavailable");
+        return 1;
+    }
+}

package/build/conductor/recovery-operations.js

@@ -18,7 +18,7 @@
  * 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, 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, resumeRun, safeDiagnosticMessage, scopeCatchUp, scopeReparse, stopEpicRun, unparkEpicTicket, updateEpicRunStatus, fetchChildContinuationStatus, postContinueParkedChild, postGrantContinuation, resumeCiTicket, 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";
@@ -179,6 +179,7 @@ async function ticketRecoveryWithRetry(access, options, mutate) {
                 expectedRowVersion: ticket.row_version,
                 idempotencyKey,
                 reason: options.reason,
+                cleanupResolution: options.cleanupResolution,
             });
         }
         catch (err) {
@@ -697,6 +698,7 @@ export async function continueChildOnce(access, options, deps = {}) {
         requestId: ref.requestId,
         requestFingerprint: ref.requestFingerprint,
         reason: options.reason,
+        workerExitProof: options.workerExitProof,
     });
     if (outcome.kind === "result" && AUTHORITATIVE_OUTCOMES.has(outcome.result.outcome)) {
         await clear();
@@ -724,6 +726,102 @@ export async function continueChildOnce(access, options, deps = {}) {
     }
     return { kind: "unconfirmed", requestId: ref.requestId, reusedReference, transport };
 }
+/** The namespace of pending `grant-continuation` requests (BAPI-1409). */
+export const CONTINUATION_GRANT_REFERENCE_NAMESPACE = "epic-continuation-grants";
+const GRANT_REQUEST_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._:-]{7,63}$/;
+function pendingGrantMatches(raw, wanted) {
+    if (raw === null || typeof raw !== "object")
+        return null;
+    const ref = raw;
+    if (ref.version !== 1 ||
+        ref.repoName !== wanted.repoName ||
+        ref.parkedGate !== wanted.parkedGate ||
+        ref.sourceParkGeneration !== wanted.sourceParkGeneration ||
+        ref.extraContinuations !== wanted.extraContinuations ||
+        ref.extraSeconds !== wanted.extraSeconds ||
+        ref.reason !== wanted.reason ||
+        typeof ref.requestId !== "string" ||
+        !GRANT_REQUEST_ID_RE.test(ref.requestId)) {
+        return null;
+    }
+    return ref.requestId;
+}
+/**
+ * Grant bounded continuation capacity, at most one POST per invocation.
+ *
+ * The request id is pinned locally BEFORE the POST, keyed by run and ticket, and
+ * reused while the park episode, gate, amounts, and reason are unchanged. A rerun
+ * after a lost response therefore replays the same grant (the server answers it
+ * from the stored grant) instead of spending a second one. The reference is
+ * cleared once the outcome is authoritative and kept when it is unconfirmed.
+ */
+export async function grantContinuationOnce(access, options, deps = {}) {
+    const fetchStatus = deps.fetchStatus ?? fetchChildContinuationStatus;
+    const post = deps.post ?? postGrantContinuation;
+    const store = deps.store ?? {};
+    const key = { epicRunId: options.epicRunId, ticketKey: options.ticketKey };
+    let status;
+    try {
+        status = await fetchStatus(access, key);
+    }
+    catch (err) {
+        return { kind: "unavailable", message: safeDiagnosticMessage(err, "could not read the child") };
+    }
+    const current = status.current;
+    if (!current.parked || current.parked_gate === null || current.park_generation === null) {
+        return { kind: "not_parked" };
+    }
+    const wanted = {
+        version: 1,
+        repoName: access.repoName,
+        parkedGate: current.parked_gate,
+        sourceParkGeneration: current.park_generation,
+        extraContinuations: options.extraContinuations,
+        extraSeconds: options.extraSeconds,
+        reason: options.reason,
+    };
+    let requestId = options.requestId ?? null;
+    let reusedReference = false;
+    const pinned = requestId === null;
+    if (pinned) {
+        const stored = pendingGrantMatches(await readRecoveryReferenceFile(CONTINUATION_GRANT_REFERENCE_NAMESPACE, key, store), wanted);
+        if (stored !== null) {
+            requestId = stored;
+            reusedReference = true;
+        }
+        else {
+            requestId = `grant_${(deps.newRequestId ?? randomUUID)()}`;
+            const reference = {
+                ...wanted, requestId, createdAt: new Date().toISOString(),
+            };
+            try {
+                await writeRecoveryReferenceFile(CONTINUATION_GRANT_REFERENCE_NAMESPACE, key, reference, store);
+            }
+            catch {
+                return {
+                    kind: "unavailable",
+                    message: "could not store the local grant reference, so the request was not sent",
+                };
+            }
+        }
+    }
+    const id = requestId;
+    const outcome = await post(access, {
+        epicRunId: options.epicRunId,
+        ticketKey: options.ticketKey,
+        requestId: id,
+        parkedGate: current.parked_gate,
+        expectedRowVersion: current.row_version,
+        sourceParkGeneration: current.park_generation,
+        extraContinuations: options.extraContinuations,
+        extraSeconds: options.extraSeconds,
+        reason: options.reason,
+    });
+    if (pinned && outcome.kind !== "unconfirmed") {
+        await clearRecoveryReferenceFile(CONTINUATION_GRANT_REFERENCE_NAMESPACE, key, store);
+    }
+    return { kind: "posted", requestId: id, reusedReference, outcome };
+}
 /**
  * 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