@bridge_gpt/mcp-server 0.2.65 → 0.2.66

package/build/conductor/recovery-cli.js

@@ -1,14 +1,15 @@
 /**
- * `conductor` operator recovery and repair verbs — twelve CLI-only commands.
+ * `conductor` operator recovery and repair verbs — thirteen CLI-only commands.
  *
  * The four BAPI-872 recovery verbs: `stop-run`, `abandon-run`, `unpark`,
  * `adopt-current-head-and-unpark`. The six run-addressed repair verbs: BAPI-1154's
  * `scope-reparse`, `dispatch-remediation`, `merge-child`, and BAPI-1176's
  * `scope-catch-up`, `patch-policy`, `resume-run`. BAPI-1300's parked-child
  * continuation pair: `continue-child` and the read-only `continuation-receipt`.
+ * BAPI-1326's allowance-preserving CI resume: `resume-ci`.
  *
  * CLI-only by design — this is an explicit ticket non-goal, not an oversight:
- * none of these twelve command names is ever registered as an MCP tool, tool
+ * none of these thirteen command names is ever registered as an MCP tool, tool
  * description, or generated tool-schema input (`index-static.test.ts` guards
  * this). They exist so an operator (or `plane down`, via
  * `recovery-operations.ts`) can recover a stuck run or ticket WITHOUT
@@ -25,6 +26,7 @@
 import { readFile } from "node:fs/promises";
 import { ConductorValidationError, toConductorErrorEnvelope } from "./errors.js";
 import { DRIVER_CONTEXT_MAX_BYTES, POLICY_PATCH_MAX_BYTES, RESUME_RUN_UNCONFIRMED_MESSAGE, } from "./repair-contract.js";
+import { decodeGuidedBinding, GuidedBindingError, } from "./guided-repair.js";
 // ---------------------------------------------------------------------------
 // Flag parsing
 // ---------------------------------------------------------------------------
@@ -378,13 +380,26 @@ export async function runAdoptCurrentHeadAndUnparkCommand(argv) {
 // ---------------------------------------------------------------------------
 // BAPI-1154 — repair verbs: scope-reparse, dispatch-remediation, merge-child
 // ---------------------------------------------------------------------------
-const SCOPE_REPARSE_VALUE_FLAGS = new Set(["--epic-run-id", "--scope-id"]);
+// BAPI-1333 — `--binding` is the ONE guided-repair input: the opaque token
+// ExplainRun rendered, carrying the subject the command is pinned to. It is not
+// a version counter the operator composes, so REJECTED_VERSION_FLAGS is unchanged.
+const SCOPE_REPARSE_VALUE_FLAGS = new Set(["--epic-run-id", "--scope-id", "--binding"]);
 const DISPATCH_REMEDIATION_VALUE_FLAGS = new Set([
     "--epic-run-id",
     "--ticket-key",
     "--context-file",
+    "--binding",
 ]);
 const MERGE_CHILD_VALUE_FLAGS = new Set(["--epic-run-id", "--pr"]);
+/**
+ * BAPI-1333 — attach `binding` ONLY when `--binding` was given, so an unguided
+ * parse result is exactly what it was before.
+ */
+function withBinding(parsed, values) {
+    if (!values.has("--binding"))
+        return parsed;
+    return { ...parsed, binding: requireFlag(values, "--binding") };
+}
 function requireFlag(values, flag) {
     const value = values.get(flag);
     if (value === undefined || value.trim().length === 0) {
@@ -397,25 +412,25 @@ export function parseScopeReparseArgs(argv) {
     if (bools.has("--help")) {
         return { epicRunId: "", scopeId: "", json: bools.has("--json"), help: true };
     }
-    return {
+    return withBinding({
         epicRunId: requireFlag(values, "--epic-run-id"),
         scopeId: requireFlag(values, "--scope-id"),
         json: bools.has("--json"),
         help: false,
-    };
+    }, values);
 }
 export function parseDispatchRemediationArgs(argv) {
     const { values, bools } = tokenizeRecoveryFlags(argv, DISPATCH_REMEDIATION_VALUE_FLAGS, RECOVERY_BOOL_FLAGS);
     if (bools.has("--help")) {
         return { epicRunId: "", ticketKey: "", contextFile: "", json: bools.has("--json"), help: true };
     }
-    return {
+    return withBinding({
         epicRunId: requireFlag(values, "--epic-run-id"),
         ticketKey: requireFlag(values, "--ticket-key"),
         contextFile: requireFlag(values, "--context-file"),
         json: bools.has("--json"),
         help: false,
-    };
+    }, values);
 }
 export function parseMergeChildArgs(argv) {
     const { values, bools } = tokenizeRecoveryFlags(argv, MERGE_CHILD_VALUE_FLAGS, RECOVERY_BOOL_FLAGS);
@@ -457,6 +472,124 @@ export function decodeDriverContextFile(bytes) {
     }
     return text;
 }
+/** One repair result, however it ended, as the renderer needs it. */
+// ---------------------------------------------------------------------------
+// BAPI-1333 — guided (binding-pinned) repairs
+// ---------------------------------------------------------------------------
+/** Exit codes shared with `resume-ci`: 0 applied/no-op, 2 refused/stale, 3 unconfirmed. */
+export const GUIDED_REPAIR_EXIT_OK = 0;
+export const GUIDED_REPAIR_EXIT_FAILED = 1;
+export const GUIDED_REPAIR_EXIT_REFUSED = 2;
+export const GUIDED_REPAIR_EXIT_UNCONFIRMED = 3;
+export const GUIDED_REPAIR_UNCONFIRMED_MESSAGE = "the outcome could not be confirmed: the server may or may not have applied this " +
+    "guided repair. Re-run the SAME command to re-send the same pinned request, or " +
+    "inspect the run read-only";
+const GUIDED_STALE_GUIDANCE = "Nothing was written. The run changed since this command was rendered (possibly " +
+    "by this command's own earlier delivery). Re-read the run explanation before " +
+    "choosing another action.";
+/**
+ * Decode `--binding` and prove it names THIS command, run, and target. Runs
+ * before credentials are resolved, so a mismatched token reaches no one.
+ */
+function checkGuidedBinding(token, verb, expected) {
+    let binding;
+    try {
+        binding = decodeGuidedBinding(token);
+    }
+    catch (err) {
+        throw new ConductorValidationError(err instanceof GuidedBindingError ? err.message : "--binding could not be decoded; nothing was sent.");
+    }
+    if (binding.verb !== verb ||
+        binding.epicRunId !== expected.epicRunId ||
+        (expected.scopeId !== undefined && binding.scopeId !== expected.scopeId) ||
+        (expected.ticketKey !== undefined && binding.ticketKey !== expected.ticketKey)) {
+        throw new ConductorValidationError("--binding was rendered for a different command, run, or target; nothing was sent.");
+    }
+    return binding;
+}
+/**
+ * Send one guided repair and render its closed outcome. Success goes to stdout;
+ * every failure goes to stderr (JSON mode included), with the exit codes above.
+ */
+async function runGuidedRepairCommand(input, json) {
+    const { guidedRepairOnce } = await import("./recovery-operations.js");
+    const { guidedPayloadDigest } = await import("./guided-repair.js");
+    const outcome = await guidedRepairOnce({
+        binding: input.binding,
+        payloadDigest: guidedPayloadDigest(input.payload),
+        send: input.send,
+        unconfirmedMessage: GUIDED_REPAIR_UNCONFIRMED_MESSAGE,
+    });
+    const verb = input.binding.verb;
+    const runId = input.binding.epicRunId;
+    if (outcome.kind === "committed" || outcome.kind === "no_op") {
+        const result = outcome.result;
+        if (outcome.kind === "committed" && !result.event_recorded) {
+            console.error(`Warning: ${verb} on run ${runId} (${input.label}) COMMITTED, but its ` +
+                "operator_verb_applied audit event was not recorded. The action stands.");
+        }
+        if (json) {
+            console.log(JSON.stringify({
+                ok: true,
+                outcome: outcome.kind,
+                request_id: outcome.requestId,
+                reference_reused: outcome.referenceReused,
+                result,
+            }));
+            return GUIDED_REPAIR_EXIT_OK;
+        }
+        console.log([
+            `${verb} (guided) — run ${runId}`,
+            `  target:          ${input.label}`,
+            `  ${input.stateLabel}: ${result.before ?? "none"} → ${result.after ?? "none"}`,
+            `  outcome:         ${outcome.kind === "committed" ? "committed" : "no-op (already in effect; nothing written)"}`,
+            `  request:         ${outcome.requestId}${outcome.referenceReused ? " (re-sent from the local reference)" : ""}`,
+            `  event recorded:  ${result.event_recorded}`,
+        ].join("\n"));
+        return GUIDED_REPAIR_EXIT_OK;
+    }
+    if (outcome.kind === "stale" || outcome.kind === "refused") {
+        const payload = {
+            ok: false,
+            outcome: outcome.kind,
+            code: outcome.code,
+            message: outcome.message,
+            request_id: outcome.requestId,
+            nothing_written: true,
+        };
+        if (json) {
+            console.error(JSON.stringify(payload));
+        }
+        else {
+            console.error(`Error: ${verb} ${outcome.kind === "stale" ? "is stale" : "refused"} on run ${runId} ` +
+                `(${input.label}) — ${outcome.code}: ${outcome.message}` +
+                (outcome.kind === "stale" ? ` ${GUIDED_STALE_GUIDANCE}` : ""));
+        }
+        return GUIDED_REPAIR_EXIT_REFUSED;
+    }
+    if (outcome.kind === "unconfirmed") {
+        if (json) {
+            console.error(JSON.stringify({
+                ok: false,
+                outcome: "unconfirmed",
+                message: outcome.message,
+                request_id: outcome.requestId,
+                reference_kept: true,
+            }));
+        }
+        else {
+            console.error(`Error: ${verb} on run ${runId} (${input.label}) — ${outcome.message}.`);
+        }
+        return GUIDED_REPAIR_EXIT_UNCONFIRMED;
+    }
+    if (json) {
+        console.error(JSON.stringify({ ok: false, outcome: "unavailable", message: outcome.message }));
+    }
+    else {
+        console.error(`Error: ${verb} on run ${runId} (${input.label}) — ${outcome.message}.`);
+    }
+    return GUIDED_REPAIR_EXIT_FAILED;
+}
 /**
  * Render a repair outcome. Human mode prints the verb and run first, the target
  * second, ONE labeled `Before → After` pair third, then whether this call
@@ -521,6 +654,12 @@ const SCOPE_REPARSE_USAGE = [
     "schedule its parse. The scope must be the one bound to the named run, or the",
     "server refuses it (TICKET_NOT_IN_RUN) with nothing written. Prints the scope",
     "lifecycle before → after; it does not wait for the parse to finish.",
+    "",
+    "Guided mode (BAPI-1333): add --binding <token> exactly as the run explanation",
+    "rendered it. The request is pinned to the subject that explanation showed and",
+    "is stored locally before it is sent, so re-running the same command after a",
+    "lost response re-sends the SAME request. A subject that has since changed is",
+    "refused as stale with nothing written (exit 2); an unconfirmed outcome exits 3.",
 ].join("\n");
 export async function runScopeReparseCommand(argv) {
     try {
@@ -529,9 +668,25 @@ export async function runScopeReparseCommand(argv) {
             console.log(SCOPE_REPARSE_USAGE);
             return 0;
         }
+        const binding = parsed.binding === undefined
+            ? null
+            : checkGuidedBinding(parsed.binding, "scope-reparse", {
+                epicRunId: parsed.epicRunId,
+                scopeId: parsed.scopeId,
+            });
         const access = await resolveRecoveryAccess(parsed.json);
         if (!access)
             return 1;
+        if (binding !== null) {
+            const { scopeReparse } = await import("./bridge-api-client.js");
+            return await runGuidedRepairCommand({
+                binding,
+                payload: { scope_id: parsed.scopeId },
+                send: (guard) => scopeReparse(access, { epicRunId: parsed.epicRunId, scopeId: parsed.scopeId, guard }),
+                label: `scope ${parsed.scopeId}`,
+                stateLabel: "scope lifecycle",
+            }, parsed.json);
+        }
         const { scopeReparseRepair } = await import("./recovery-operations.js");
         const outcome = await scopeReparseRepair(access, {
             epicRunId: parsed.epicRunId,
@@ -563,6 +718,12 @@ const DISPATCH_REMEDIATION_USAGE = [
     `--context-file must be non-empty UTF-8 text of at most DRIVER_CONTEXT_MAX_BYTES`,
     `(${DRIVER_CONTEXT_MAX_BYTES} bytes). It is rejected, never truncated, and is never`,
     "printed, logged, or echoed — it reaches only the worker's prompt.",
+    "",
+    "Guided mode (BAPI-1333): add --binding <token> exactly as the run explanation",
+    "rendered it. The request is pinned to the subject that explanation showed and",
+    "is stored locally before it is sent, so re-running the same command after a",
+    "lost response re-sends the SAME request. A subject that has since changed is",
+    "refused as stale with nothing written (exit 2); an unconfirmed outcome exits 3.",
 ].join("\n");
 export async function runDispatchRemediationCommand(argv, deps = {}) {
     try {
@@ -581,9 +742,31 @@ export async function runDispatchRemediationCommand(argv, deps = {}) {
             throw new ConductorValidationError("--context-file could not be read; nothing was sent.");
         }
         const context = decodeDriverContextFile(bytes);
+        const binding = parsed.binding === undefined
+            ? null
+            : checkGuidedBinding(parsed.binding, "dispatch-remediation", {
+                epicRunId: parsed.epicRunId,
+                ticketKey: parsed.ticketKey,
+            });
         const access = await resolveRecoveryAccess(parsed.json);
         if (!access)
             return 1;
+        if (binding !== null) {
+            const { dispatchRemediation } = await import("./bridge-api-client.js");
+            return await runGuidedRepairCommand({
+                binding,
+                // Digested, never stored: the context stays out of the reference file.
+                payload: { ticket_key: parsed.ticketKey, context: context },
+                send: (guard) => dispatchRemediation(access, {
+                    epicRunId: parsed.epicRunId,
+                    ticketKey: parsed.ticketKey,
+                    context,
+                    guard,
+                }),
+                label: `ticket ${parsed.ticketKey}`,
+                stateLabel: "code_review gate",
+            }, parsed.json);
+        }
         const { dispatchRemediationRepair } = await import("./recovery-operations.js");
         const outcome = await dispatchRemediationRepair(access, {
             epicRunId: parsed.epicRunId,
@@ -651,9 +834,9 @@ export async function runMergeChildCommand(argv) {
 // ---------------------------------------------------------------------------
 // BAPI-1176 — repair verbs: scope-catch-up, patch-policy, resume-run
 // ---------------------------------------------------------------------------
-const SCOPE_CATCH_UP_VALUE_FLAGS = new Set(["--epic-run-id", "--scope-id"]);
-const PATCH_POLICY_VALUE_FLAGS = new Set(["--epic-run-id", "--patch-file"]);
-const RESUME_RUN_VALUE_FLAGS = new Set(["--epic-run-id"]);
+const SCOPE_CATCH_UP_VALUE_FLAGS = new Set(["--epic-run-id", "--scope-id", "--binding"]);
+const PATCH_POLICY_VALUE_FLAGS = new Set(["--epic-run-id", "--patch-file", "--binding"]);
+const RESUME_RUN_VALUE_FLAGS = new Set(["--epic-run-id", "--binding"]);
 /** `--clear-quarantine` is a `resume-run` switch only; no other verb accepts it. */
 const RESUME_RUN_BOOL_FLAGS = new Set(["--json", "--help", "--clear-quarantine"]);
 export function parseScopeCatchUpArgs(argv) {
@@ -661,24 +844,24 @@ export function parseScopeCatchUpArgs(argv) {
     if (bools.has("--help")) {
         return { epicRunId: "", scopeId: "", json: bools.has("--json"), help: true };
     }
-    return {
+    return withBinding({
         epicRunId: requireFlag(values, "--epic-run-id"),
         scopeId: requireFlag(values, "--scope-id"),
         json: bools.has("--json"),
         help: false,
-    };
+    }, values);
 }
 export function parsePatchPolicyArgs(argv) {
     const { values, bools } = tokenizeRecoveryFlags(argv, PATCH_POLICY_VALUE_FLAGS, RECOVERY_BOOL_FLAGS);
     if (bools.has("--help")) {
         return { epicRunId: "", patchFile: "", json: bools.has("--json"), help: true };
     }
-    return {
+    return withBinding({
         epicRunId: requireFlag(values, "--epic-run-id"),
         patchFile: requireFlag(values, "--patch-file"),
         json: bools.has("--json"),
         help: false,
-    };
+    }, values);
 }
 export function parseResumeRunArgs(argv) {
     const { values, bools } = tokenizeRecoveryFlags(argv, RESUME_RUN_VALUE_FLAGS, RESUME_RUN_BOOL_FLAGS);
@@ -690,12 +873,12 @@ export function parseResumeRunArgs(argv) {
             help: true,
         };
     }
-    return {
+    return withBinding({
         epicRunId: requireFlag(values, "--epic-run-id"),
         clearQuarantine: bools.has("--clear-quarantine"),
         json: bools.has("--json"),
         help: false,
-    };
+    }, values);
 }
 /**
  * Validate and decode a `patch-policy` file's BYTES into a merge-patch object.
@@ -749,6 +932,12 @@ const SCOPE_CATCH_UP_USAGE = [
     "refused (SCOPE_CATCH_UP_REFUSED). The scope must be the one bound to the named",
     "run, or the server refuses it (TICKET_NOT_IN_RUN) with nothing written. Prints",
     "the scope lifecycle before → after; it does not wait for a scheduled parse.",
+    "",
+    "Guided mode (BAPI-1333): add --binding <token> exactly as the run explanation",
+    "rendered it. The request is pinned to the subject that explanation showed and",
+    "is stored locally before it is sent, so re-running the same command after a",
+    "lost response re-sends the SAME request. A subject that has since changed is",
+    "refused as stale with nothing written (exit 2); an unconfirmed outcome exits 3.",
 ].join("\n");
 export async function runScopeCatchUpCommand(argv) {
     try {
@@ -757,9 +946,25 @@ export async function runScopeCatchUpCommand(argv) {
             console.log(SCOPE_CATCH_UP_USAGE);
             return 0;
         }
+        const binding = parsed.binding === undefined
+            ? null
+            : checkGuidedBinding(parsed.binding, "scope-catch-up", {
+                epicRunId: parsed.epicRunId,
+                scopeId: parsed.scopeId,
+            });
         const access = await resolveRecoveryAccess(parsed.json);
         if (!access)
             return 1;
+        if (binding !== null) {
+            const { scopeCatchUp } = await import("./bridge-api-client.js");
+            return await runGuidedRepairCommand({
+                binding,
+                payload: { scope_id: parsed.scopeId },
+                send: (guard) => scopeCatchUp(access, { epicRunId: parsed.epicRunId, scopeId: parsed.scopeId, guard }),
+                label: `scope ${parsed.scopeId}`,
+                stateLabel: "scope lifecycle",
+            }, parsed.json);
+        }
         const { scopeCatchUpRepair } = await import("./recovery-operations.js");
         const outcome = await scopeCatchUpRepair(access, {
             epicRunId: parsed.epicRunId,
@@ -792,6 +997,12 @@ const PATCH_POLICY_USAGE = [
     "--patch-file must hold a non-empty JSON object of at most POLICY_PATCH_MAX_BYTES",
     `(${POLICY_PATCH_MAX_BYTES} bytes). Its contents are never printed; the result names only`,
     "the changed dotted paths and before/after policy digest tokens.",
+    "",
+    "Guided mode (BAPI-1333): add --binding <token> exactly as the run explanation",
+    "rendered it. The request is pinned to the subject that explanation showed and",
+    "is stored locally before it is sent, so re-running the same command after a",
+    "lost response re-sends the SAME request. A subject that has since changed is",
+    "refused as stale with nothing written (exit 2); an unconfirmed outcome exits 3.",
 ].join("\n");
 export async function runPatchPolicyCommand(argv, deps = {}) {
     try {
@@ -810,9 +1021,23 @@ export async function runPatchPolicyCommand(argv, deps = {}) {
             throw new ConductorValidationError("--patch-file could not be read; nothing was sent.");
         }
         const mergePatch = decodePolicyPatchFile(bytes);
+        const binding = parsed.binding === undefined
+            ? null
+            : checkGuidedBinding(parsed.binding, "patch-policy", { epicRunId: parsed.epicRunId });
         const access = await resolveRecoveryAccess(parsed.json);
         if (!access)
             return 1;
+        if (binding !== null) {
+            const { patchPolicy } = await import("./bridge-api-client.js");
+            return await runGuidedRepairCommand({
+                binding,
+                // Digested, never stored: no policy value reaches the reference file.
+                payload: { merge_patch: mergePatch },
+                send: (guard) => patchPolicy(access, { epicRunId: parsed.epicRunId, mergePatch, guard }),
+                label: "run policy",
+                stateLabel: "policy digest",
+            }, parsed.json);
+        }
         const { patchPolicyRepair } = await import("./recovery-operations.js");
         const outcome = await patchPolicyRepair(access, {
             epicRunId: parsed.epicRunId,
@@ -845,6 +1070,12 @@ const RESUME_RUN_USAGE = [
     "",
     "If the response is lost or cannot be read, the resume may or may not have",
     "committed: inspect the run read-only before any separately authorized retry.",
+    "",
+    "Guided mode (BAPI-1333): add --binding <token> exactly as the run explanation",
+    "rendered it. The request is pinned to the subject that explanation showed and",
+    "is stored locally before it is sent, so re-running the same command after a",
+    "lost response re-sends the SAME request. A subject that has since changed is",
+    "refused as stale with nothing written (exit 2); an unconfirmed outcome exits 3.",
 ].join("\n");
 export async function runResumeRunCommand(argv) {
     try {
@@ -853,9 +1084,29 @@ export async function runResumeRunCommand(argv) {
             console.log(RESUME_RUN_USAGE);
             return 0;
         }
+        const binding = parsed.binding === undefined
+            ? null
+            : checkGuidedBinding(parsed.binding, "resume-run", { epicRunId: parsed.epicRunId });
+        if (binding !== null && binding.controlState === "quarantined" && !parsed.clearQuarantine) {
+            throw new ConductorValidationError("This binding names a quarantined run; --clear-quarantine is required. Nothing was sent.");
+        }
         const access = await resolveRecoveryAccess(parsed.json);
         if (!access)
             return 1;
+        if (binding !== null) {
+            const { resumeRun } = await import("./bridge-api-client.js");
+            return await runGuidedRepairCommand({
+                binding,
+                payload: { clear_quarantine: parsed.clearQuarantine },
+                send: (guard) => resumeRun(access, {
+                    epicRunId: parsed.epicRunId,
+                    clearQuarantine: parsed.clearQuarantine,
+                    guard,
+                }),
+                label: parsed.clearQuarantine ? "run (clear quarantine)" : "run",
+                stateLabel: "run state",
+            }, parsed.json);
+        }
         const { resumeRunRepair } = await import("./recovery-operations.js");
         const outcome = await resumeRunRepair(access, {
             epicRunId: parsed.epicRunId,
@@ -1047,6 +1298,11 @@ export function renderContinueChildResult(result, target, json) {
         }
         console.error(`${label}: not continuable right now. Nothing was sent.`);
         console.error(currentLine(result.current));
+        // BAPI-1344: the park's own guidance names the exit that remains (for a
+        // first attempt with no recorded retained head, the run operator).
+        if (result.current.parked && result.current.needs_human_reason) {
+            console.error(`Park: ${result.current.needs_human_reason}`);
+        }
         return 1;
     }
     if (result.kind === "unconfirmed") {
@@ -1162,3 +1418,238 @@ export async function runContinuationReceiptCommand(argv) {
         return 1;
     }
 }
+// ---------------------------------------------------------------------------
+// BAPI-1326 — resume-ci
+// ---------------------------------------------------------------------------
+const RESUME_CI_USAGE = [
+    "Usage: epic-implementer resume-ci --epic-run-id <id> --ticket-key <key> [--json]",
+    "",
+    "Resume a child parked on a qualified CI stop (an expired CI wait, exhausted",
+    "required-check repairs, or an unavailable verdict) once CI has finished green.",
+    "The server re-reads the pull request, the specification, and the required",
+    "checks, then returns CI to evaluation at the same head. It creates no job,",
+    "grants no repair or new wait, keeps the original deadline, and does not mark",
+    "CI passed or authorize review or merge.",
+    "",
+    "The operation is pinned locally before it is sent; re-running after a lost",
+    "response reuses it and reports the original result. Nothing else is tried.",
+    "",
+    "Exit codes: 0 committed or replayed; 2 refused; 3 unconfirmed; 1 other failure.",
+].join("\n");
+/** Distinct exit codes, so automation can tell a refusal from an unknown outcome. */
+export const RESUME_CI_EXIT_OK = 0;
+export const RESUME_CI_EXIT_FAILED = 1;
+export const RESUME_CI_EXIT_REFUSED = 2;
+export const RESUME_CI_EXIT_UNCONFIRMED = 3;
+/**
+ * Fixed operator sentences, chosen by the server's structured code. No server,
+ * provider, or exception text ever reaches the terminal.
+ */
+const RESUME_CI_REFUSAL_SENTENCES = {
+    TICKET_NOT_IN_RUN: "the ticket is not part of this run",
+    CI_STOP_NOT_ELIGIBLE: "this CI park has no complete qualified stop record, so resume-ci does not apply",
+    CI_RESUME_STALE_OPERATION: "the ticket is no longer on the CI stop this operation was made for, and its result is not retained",
+    CI_RESUME_OPERATION_CONFLICT: "this operation already names a different CI recovery",
+    ROW_VERSION_CONFLICT: "the ticket kept changing while the resume was being applied",
+    RUN_NOT_DISPATCHABLE: "the run is paused, stopped, quarantined, or not active",
+    CI_RESUME_BUDGET_EXHAUSTED: "the run's wall-clock or cost budget is spent, or could not be read",
+    CI_RESUME_HELD: "the ticket is held by a completion, permission, declassification, or stale-specification hold",
+    CI_RESUME_LIVE_WORK: "corrective work is, or may be, live for this ticket",
+    CI_RESUME_SPEC_CHANGED: "the ticket's specification changed or could not be verified",
+    CI_RESUME_POLICY_CHANGED: "the run's required-check policy changed, or is unavailable or unconfigured",
+    CI_RESUME_BINDING_CHANGED: "the pull request, its head, or its target branch changed since the stop",
+    CI_RESUME_CHECKS_NOT_GREEN: "the bound head's required checks are not currently green",
+    CI_RESUME_VERDICT_UNAVAILABLE: "the CI provider's verdict could not be read in time",
+    CI_RESUME_BUSY: "the ticket or run stayed busy for the whole bounded wait",
+};
+/** The next step for a refusal, where one is useful. */
+const RESUME_CI_REFUSAL_GUIDANCE = {
+    CI_STOP_NOT_ELIGIBLE: "The existing explicit path is `epic-implementer unpark`, which RESETS the CI gate's " +
+        "clock and repair allowance. If the park's origin is unclear, ask the run operator " +
+        "to assess it first.",
+    CI_RESUME_STALE_OPERATION: "Read `epic-implementer explain-run` for the ticket; start a new resume-ci only if " +
+        "its current stop independently qualifies.",
+    CI_RESUME_CHECKS_NOT_GREEN: "Wait for the required checks to finish green, then retry.",
+    CI_RESUME_VERDICT_UNAVAILABLE: "Retry later. If the provider stays unavailable, escalate to the CI-platform operator.",
+    CI_RESUME_BUSY: "Retry the same command; it reuses the same operation.",
+    ROW_VERSION_CONFLICT: "Retry the same command; it reuses the same operation.",
+    RUN_NOT_DISPATCHABLE: "Resume the run first (`epic-implementer resume-run`), then retry.",
+    CI_RESUME_LIVE_WORK: "Retry when the running work has finished.",
+};
+const RESUME_CI_STOP_REASON_TEXT = {
+    wait_expired: "an expired CI wait",
+    repair_exhausted: "exhausted required-check repairs",
+    verdict_unavailable: "an unavailable CI verdict",
+};
+const RESUME_CI_NOT_ELIGIBLE_TEXT = {
+    ticket_not_found: "the ticket is not part of this run",
+    not_parked: "the ticket is not parked",
+    not_ci_park: "the ticket is not parked at the CI gate",
+    no_typed_stop: "the CI park has no complete qualified stop record (a legacy or incomplete park)",
+    stop_superseded: "the CI stop belongs to an earlier park episode",
+};
+/** The one consequence statement every committed result carries. */
+const RESUME_CI_CONSEQUENCE = "CI is back in evaluation at the same head; its verdict is pending. This action did NOT " +
+    "mark CI passed, authorize review or merge, create a job, extend the deadline, or refund " +
+    "any repair.";
+export function parseResumeCiArgs(argv) {
+    return parseTicketRecoveryArgs(argv);
+}
+function resumeCiOperationSummary(op) {
+    return {
+        resumed_at: op.resumed_at,
+        stop_reason: op.stop_reason,
+        park_generation: op.park_generation,
+        resumed_gate: op.resumed_gate,
+        ci_gate_status: op.ci_gate_status,
+        allowance_effect: op.allowance_effect,
+        preserved_attempts: op.preserved_attempts,
+        preserved_ci_infra_rerun_attempts_used: op.preserved_ci_infra_rerun_attempts_used,
+        preserved_entry_attempts: op.preserved_entry_attempts,
+        deadline_at: op.deadline_at,
+        deadline_source: op.deadline_source,
+        deadline_extended: op.deadline_extended,
+        jobs_created: op.jobs_created,
+        ci_passed_by_action: op.ci_passed_by_action,
+    };
+}
+function allowanceLine(op) {
+    const infra = op.preserved_ci_infra_rerun_attempts_used ?? 0;
+    const entry = op.preserved_entry_attempts ?? 0;
+    return (`Preserved allowances: repair attempts spent ${op.preserved_attempts}, ` +
+        `infrastructure retries used ${infra}, entry attempts ${entry}.`);
+}
+function deadlineLine(op) {
+    if (op.deadline_at === null)
+        return "Deadline unchanged (not recorded).";
+    const source = op.deadline_source === "post_repair" ? "post-repair window" : "original gate window";
+    return `Deadline unchanged: ${op.deadline_at} (${source}).`;
+}
+function currentStateLine(current) {
+    return (`Current state (read now, separate from the history above): ticket ${current.ticket_status ?? "unknown"}, ` +
+        `gate ${current.current_gate ?? "unknown"}, CI gate ${current.ci_gate_status ?? "unknown"}, ` +
+        `held by run control: ${current.held_by_run_control ? "yes" : "no"}.`);
+}
+/**
+ * Exported for tests: render a `resume-ci` result.
+ *
+ * The outcome word leads the first line. Committed and replayed results go to
+ * stdout with exit 0; refused, unconfirmed, and failed outcomes go to stderr with
+ * their own non-zero codes. No operation key, stop binding, row version, SHA,
+ * credential, provider error, or URL is ever printed, in either mode.
+ */
+export function renderResumeCiResult(result, target, json) {
+    const label = `ticket ${target.ticketKey} (run ${target.epicRunId})`;
+    if (result.kind === "committed" || result.kind === "replayed") {
+        const r = result.result;
+        if (json) {
+            console.log(JSON.stringify({
+                ok: true,
+                outcome: result.kind,
+                historical: result.kind === "replayed",
+                epic_run_id: r.epic_run_id,
+                ticket_key: r.ticket_key,
+                operation: resumeCiOperationSummary(r.operation),
+                current: r.current,
+                audit_recorded: r.audit_recorded,
+                audit_warning: r.audit_warning,
+                reference_reused: result.reusedReference,
+            }));
+            return RESUME_CI_EXIT_OK;
+        }
+        const reason = RESUME_CI_STOP_REASON_TEXT[r.operation.stop_reason] ?? "a CI stop";
+        if (result.kind === "committed") {
+            console.log(`Committed: resume-ci for ${label}, which was parked on ${reason}.`);
+            console.log(RESUME_CI_CONSEQUENCE);
+            console.log(allowanceLine(r.operation));
+            console.log(deadlineLine(r.operation));
+            console.log("Next: the reconciler's next identical green poll confirms CI; review and merge checks still apply.");
+        }
+        else {
+            console.log(`Replayed historical result: resume-ci for ${label} committed earlier, at ` +
+                `${r.operation.resumed_at}. Nothing was changed by this call.`);
+            console.log(`History: the ticket was parked on ${reason} and was returned to CI evaluation.`);
+            console.log(allowanceLine(r.operation));
+            console.log(deadlineLine(r.operation));
+            console.log(currentStateLine(r.current));
+            console.log("This history does not show that CI is green now, or that review or merge may proceed.");
+        }
+        if (!r.audit_recorded && r.audit_warning) {
+            console.log(`Warning: ${r.audit_warning}`);
+        }
+        return RESUME_CI_EXIT_OK;
+    }
+    if (result.kind === "refused" || result.kind === "not_eligible" || result.kind === "stale_reference") {
+        const code = result.kind === "refused"
+            ? result.errorCode
+            : result.kind === "stale_reference"
+                ? "CI_RESUME_STALE_OPERATION"
+                : "CI_STOP_NOT_ELIGIBLE";
+        const sentence = result.kind === "not_eligible"
+            ? RESUME_CI_NOT_ELIGIBLE_TEXT[result.reason] ?? "resume-ci does not apply"
+            : RESUME_CI_REFUSAL_SENTENCES[code] ?? "the server refused the request";
+        const guidance = RESUME_CI_REFUSAL_GUIDANCE[code];
+        if (json) {
+            console.error(JSON.stringify({
+                ok: false,
+                outcome: "refused",
+                refusal_code: code,
+                ...(result.kind === "not_eligible" ? { local_reason: result.reason } : {}),
+                message: sentence,
+                ...(guidance ? { guidance } : {}),
+                nothing_written: true,
+            }));
+            return RESUME_CI_EXIT_REFUSED;
+        }
+        console.error(`Refused: resume-ci for ${label} — ${sentence}. Nothing was written.`);
+        if (guidance)
+            console.error(guidance);
+        return RESUME_CI_EXIT_REFUSED;
+    }
+    if (result.kind === "unconfirmed") {
+        if (json) {
+            console.error(JSON.stringify({
+                ok: false,
+                outcome: "unconfirmed",
+                transport: result.transport,
+                attempts: result.attempts,
+            }));
+            return RESUME_CI_EXIT_UNCONFIRMED;
+        }
+        console.error(`Unconfirmed: resume-ci for ${label} — no durable answer arrived after ${result.attempts} ` +
+            `attempts (${result.transport}). The resume may or may not have committed.`);
+        console.error("Re-run the same command later: it reuses this same operation and reports its original " +
+            "result. Do not use unpark or another recovery in the meantime.");
+        return RESUME_CI_EXIT_UNCONFIRMED;
+    }
+    const message = result.kind === "unavailable" ? result.message : "the outcome could not be read";
+    if (json) {
+        console.error(JSON.stringify({ ok: false, outcome: "failed", message }));
+    }
+    else {
+        console.error(`Failed: resume-ci for ${label} — ${message}.`);
+    }
+    return RESUME_CI_EXIT_FAILED;
+}
+export async function runResumeCiCommand(argv) {
+    try {
+        const parsed = parseResumeCiArgs(argv);
+        if (parsed.help) {
+            console.log(RESUME_CI_USAGE);
+            return 0;
+        }
+        const access = await resolveRecoveryAccess(parsed.json);
+        if (!access)
+            return RESUME_CI_EXIT_FAILED;
+        const { resumeCiOnce } = await import("./recovery-operations.js");
+        const result = await resumeCiOnce(access, {
+            epicRunId: parsed.epicRunId,
+            ticketKey: parsed.ticketKey,
+        });
+        return renderResumeCiResult(result, parsed, parsed.json);
+    }
+    catch (error) {
+        console.error(`Error: ${toConductorErrorEnvelope(error).message}`);
+        return RESUME_CI_EXIT_FAILED;
+    }
+}