@bridge_gpt/mcp-server 0.2.69 → 0.2.70

package/build/conductor/recovery-cli.js

@@ -1,5 +1,5 @@
 /**
- * `conductor` operator recovery and repair verbs — fourteen CLI-only commands.
+ * `conductor` operator recovery and repair verbs — sixteen 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
@@ -7,10 +7,12 @@
  * `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`. BAPI-1388's guided
- * provider re-run of failed CI workflow runs: `rerun-ci`.
+ * provider re-run of failed CI workflow runs: `rerun-ci`. BAPI-1494's owner
+ * decision on verification hand-offs: `resolve-handoff`. BAPI-1532's answer to a
+ * named plan failure, one forced regeneration on a chosen route: `regenerate-plan`.
  *
  * CLI-only by design — this is an explicit ticket non-goal, not an oversight:
- * none of these fourteen command names is ever registered as an MCP tool, tool
+ * none of these sixteen 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
@@ -26,7 +28,9 @@
  */
 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 { nodeGithubMergeCredentialReadDeps, readLocalGithubRemote } from "./stored-merge-credential.js";
+import { DRIVER_CONTEXT_MAX_BYTES, HANDOFF_RESOLUTION_EVIDENCE_REF_MAX_CHARS, HANDOFF_RESOLUTION_KIND_LABELS, HANDOFF_RESOLUTION_KINDS, HANDOFF_RESOLUTION_MAX_STEPS, HANDOFF_RESOLUTION_REASON_MAX_CHARS, POLICY_PATCH_MAX_BYTES, RESUME_RUN_UNCONFIRMED_MESSAGE, } from "./repair-contract.js";
+import { CONTINUATION_CI_WAITING_REASONS, continuationDispatchedJob, } from "./epic-child-continuation.js";
 import { decodeGuidedBinding, GuidedBindingError, } from "./guided-repair.js";
 // ---------------------------------------------------------------------------
 // Flag parsing
@@ -995,6 +999,196 @@ export async function runRerunCiCommand(argv) {
         return RERUN_CI_EXIT_FAILED;
     }
 }
+// ---------------------------------------------------------------------------
+// BAPI-1494 — resolve-handoff
+// ---------------------------------------------------------------------------
+const RESOLVE_HANDOFF_VALUE_FLAGS = new Set([
+    "--epic-run-id",
+    "--ticket-key",
+    "--steps",
+    "--kind",
+    "--evidence",
+    "--reason",
+]);
+/** Exit codes: 0 recorded (or an identical replay), 1 refused or failed. */
+export const RESOLVE_HANDOFF_EXIT_OK = 0;
+export const RESOLVE_HANDOFF_EXIT_FAILED = 1;
+/** The paired-record instruction every success ends with. */
+export const RESOLVE_HANDOFF_PAIRED_RECORD_INSTRUCTION = "Release from draft also needs the paired .bridge/epic-workarounds/<KEY>.md record " +
+    "removed in a new epic-head commit. The integration PR leaves draft only when both " +
+    "holds are clear: the hand-off ledger hold and the workaround-folder hold.";
+const RESOLVE_HANDOFF_USAGE = [
+    "Usage: epic-implementer resolve-handoff --epic-run-id <id> --ticket-key <key> --steps 27,36",
+    "         --kind verified|risk_accepted --evidence <ref> --reason <text> [--json]",
+    "",
+    "Record the run owner's decision on a ticket's verification hand-offs: steps a worker",
+    "could not verify unattended. An unresolved hand-off holds the integration PR in draft.",
+    "",
+    "  --kind verified       the owner completed the verification of the affected criteria",
+    "  --kind risk_accepted  verification is still incomplete; the owner accepts the risk",
+    "",
+    "This records a HUMAN decision. Run it only with the owner's named steps, kind, evidence",
+    "and reason; it is never an automatic in-run recovery, and workers cannot run it. The",
+    "server records your verified API-key identity as the actor; you cannot supply one.",
+    "--evidence is stored as a reference (at most 500 characters) and is never fetched.",
+    "--reason is at most 2000 characters.",
+    "",
+    RESOLVE_HANDOFF_PAIRED_RECORD_INSTRUCTION,
+    "",
+    "Exit codes: 0 recorded (or the same decision already recorded); 1 refused or failed.",
+].join("\n");
+/** Character count in code points, the way the server's validation counts. */
+function codePointLength(value) {
+    return [...value].length;
+}
+function parseHandoffSteps(raw) {
+    const parts = raw.split(",");
+    const steps = [];
+    for (const part of parts) {
+        const token = part.trim();
+        if (!/^[1-9][0-9]*$/.test(token)) {
+            throw new ConductorValidationError("--steps must be a comma-separated list of positive integers (for example 27,36).");
+        }
+        const step = Number(token);
+        if (!Number.isSafeInteger(step)) {
+            throw new ConductorValidationError("--steps holds a step id that is too large.");
+        }
+        if (steps.includes(step)) {
+            throw new ConductorValidationError(`--steps names step ${step} more than once.`);
+        }
+        steps.push(step);
+    }
+    if (steps.length > HANDOFF_RESOLUTION_MAX_STEPS) {
+        throw new ConductorValidationError(`--steps may name at most ${HANDOFF_RESOLUTION_MAX_STEPS} steps.`);
+    }
+    return steps;
+}
+function boundedText(values, flag, max) {
+    const value = requireFlag(values, flag);
+    if (codePointLength(value) > max) {
+        throw new ConductorValidationError(`Flag "${flag}" must be at most ${max} characters.`);
+    }
+    return value;
+}
+export function parseResolveHandoffArgs(argv) {
+    const { values, bools } = tokenizeRecoveryFlags(argv, RESOLVE_HANDOFF_VALUE_FLAGS, RECOVERY_BOOL_FLAGS);
+    if (bools.has("--help")) {
+        return {
+            epicRunId: "",
+            ticketKey: "",
+            steps: [],
+            kind: "verified",
+            evidenceRef: "",
+            reason: "",
+            json: bools.has("--json"),
+            help: true,
+        };
+    }
+    const kind = requireFlag(values, "--kind");
+    if (!HANDOFF_RESOLUTION_KINDS.includes(kind)) {
+        throw new ConductorValidationError('--kind must be "verified" or "risk_accepted".');
+    }
+    return {
+        epicRunId: requireFlag(values, "--epic-run-id"),
+        ticketKey: requireFlag(values, "--ticket-key"),
+        steps: parseHandoffSteps(requireFlag(values, "--steps")),
+        kind: kind,
+        evidenceRef: boundedText(values, "--evidence", HANDOFF_RESOLUTION_EVIDENCE_REF_MAX_CHARS),
+        reason: boundedText(values, "--reason", HANDOFF_RESOLUTION_REASON_MAX_CHARS),
+        json: bools.has("--json"),
+        help: false,
+    };
+}
+/**
+ * Exported for tests: render one `resolve-handoff` outcome. Success goes to stdout
+ * and every failure to stderr (`--json` included). `risk_accepted` always reads
+ * "risk accepted" — never verified or passed.
+ */
+export function renderResolveHandoffOutcome(outcome, parsed, json) {
+    const label = `ticket ${parsed.ticketKey} (run ${parsed.epicRunId})`;
+    const pairedRecord = RESOLVE_HANDOFF_PAIRED_RECORD_INSTRUCTION.replace("<KEY>", parsed.ticketKey);
+    if (outcome.ok) {
+        const result = outcome.result;
+        const decision = HANDOFF_RESOLUTION_KIND_LABELS[parsed.kind];
+        if (result.committed && !result.event_recorded) {
+            console.error(`Warning: resolve-handoff for ${label} COMMITTED, but its operator_verb_applied ` +
+                "audit event was not recorded. The decision stands.");
+        }
+        if (json) {
+            console.log(JSON.stringify({
+                ok: true,
+                outcome: result.committed ? "committed" : "replayed",
+                decision,
+                result,
+                next_action: pairedRecord,
+            }));
+            return RESOLVE_HANDOFF_EXIT_OK;
+        }
+        const lines = [
+            result.committed
+                ? `resolve-handoff — ${label}: decision recorded (${decision})`
+                : `resolve-handoff — ${label}: this decision was already recorded; nothing was written`,
+            ...result.resolutions.map((res) => `  steps ${res.steps.join(", ")}: ${HANDOFF_RESOLUTION_KIND_LABELS[res.kind]} by ` +
+                `${res.actor} at epic head \`${res.epic_head_sha}\` (binding ${res.binding_attempt_id}, ` +
+                `evidence revision ${res.evidence_revision}); evidence: ${res.evidence_ref}`),
+            `  unresolved hand-offs left on this ticket: ${result.remaining_unresolved}`,
+            `  event recorded:  ${result.committed ? String(result.event_recorded) : "not applicable (replay)"}`,
+            `  next action:     ${pairedRecord}`,
+        ];
+        console.log(lines.join("\n"));
+        return RESOLVE_HANDOFF_EXIT_OK;
+    }
+    if (outcome.kind === "refused") {
+        if (json) {
+            console.error(JSON.stringify({
+                ok: false,
+                outcome: "refused",
+                code: outcome.code,
+                message: outcome.message,
+                nothing_written: true,
+            }));
+        }
+        else {
+            console.error(`Refused: resolve-handoff for ${label} — ${outcome.code}: ${outcome.message} ` +
+                "Nothing was written.");
+        }
+        return RESOLVE_HANDOFF_EXIT_FAILED;
+    }
+    if (json) {
+        console.error(JSON.stringify({ ok: false, outcome: "unavailable", message: outcome.message }));
+    }
+    else {
+        console.error(`Failed: resolve-handoff for ${label} — ${outcome.message}. Whether the decision was ` +
+            "recorded is unconfirmed; read `epic-implementer explain-run` before retrying.");
+    }
+    return RESOLVE_HANDOFF_EXIT_FAILED;
+}
+export async function runResolveHandoffCommand(argv) {
+    try {
+        const parsed = parseResolveHandoffArgs(argv);
+        if (parsed.help) {
+            console.log(RESOLVE_HANDOFF_USAGE);
+            return 0;
+        }
+        const access = await resolveRecoveryAccess(parsed.json);
+        if (!access)
+            return RESOLVE_HANDOFF_EXIT_FAILED;
+        const { resolveHandoffRepair } = await import("./recovery-operations.js");
+        const outcome = await resolveHandoffRepair(access, {
+            epicRunId: parsed.epicRunId,
+            ticketKey: parsed.ticketKey,
+            steps: parsed.steps,
+            kind: parsed.kind,
+            evidenceRef: parsed.evidenceRef,
+            reason: parsed.reason,
+        });
+        return renderResolveHandoffOutcome(outcome, parsed, parsed.json);
+    }
+    catch (error) {
+        console.error(`Error: ${toConductorErrorEnvelope(error).message}`);
+        return RESOLVE_HANDOFF_EXIT_FAILED;
+    }
+}
 const MERGE_CHILD_USAGE = [
     "Usage: epic-implementer merge-child --epic-run-id <id> --pr <number> [--json]",
     "",
@@ -1020,9 +1214,14 @@ export async function runMergeChildCommand(argv) {
         if (!access)
             return 1;
         const { mergeChildRepair } = await import("./recovery-operations.js");
-        const outcome = await mergeChildRepair(access, {
-            epicRunId: parsed.epicRunId,
-            prNumber: parsed.prNumber,
+        // BAPI-1461: this verb runs in the person's own session, so a merge token
+        // stored once for this repository is the last rung after the env keys.
+        const outcome = await mergeChildRepair(access, { epicRunId: parsed.epicRunId, prNumber: parsed.prNumber }, {
+            storedMergeCredential: {
+                allowStoredEntry: true,
+                localRemote: await readLocalGithubRemote(process.cwd()),
+                storeDeps: nodeGithubMergeCredentialReadDeps(process.env),
+            },
         });
         return renderRepairResult(outcome, {
             verb: "merge-child",
@@ -1336,11 +1535,17 @@ export async function runResumeRunCommand(argv) {
 // ---------------------------------------------------------------------------
 // continue-child / continuation-receipt (BAPI-1300)
 // ---------------------------------------------------------------------------
-const CONTINUE_CHILD_VALUE_FLAGS = new Set(["--epic-run-id", "--ticket-key", "--reason", "--worker-exit-proof"]);
+const CONTINUE_CHILD_VALUE_FLAGS = new Set([
+    "--epic-run-id",
+    "--ticket-key",
+    "--reason",
+    "--worker-exit-proof",
+    "--context-file",
+]);
 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> --worker-exit-proof exited|fenced] [--json]",
+    "Usage: epic-implementer continue-child --epic-run-id <id> --ticket-key <key> [--reason <text> --worker-exit-proof exited|fenced] [--context-file <path>] [--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 +1556,18 @@ const CONTINUE_CHILD_USAGE = [
     "committed. Re-running continue-child reuses the SAME request (it never",
     "approves a new head or episode); continuation-receipt looks the receipt up.",
     "Never accepts a version counter or a park generation.",
+    "",
+    "--context-file (CI-repair continuations only): driver context for the repair",
+    "worker, sent beside --reason (never merged into it). It 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. A re-run of",
+    "a pending request must pass the same file. A server that does not support it",
+    "rejects the request (exit 1); it is never retried without the context.",
+    "",
+    "When CI is already green at the bound head, the server resumes the child",
+    "without a repair: no job is dispatched and no allowance is charged (exit 0).",
+    "While CI is still running or unreadable, nothing is written; re-run the same",
+    "command later — it re-sends the SAME request.",
 ].join("\n");
 const CONTINUATION_RECEIPT_USAGE = [
     "Usage: epic-implementer continuation-receipt --epic-run-id <id> --ticket-key <key> [--request-id <id>] [--json]",
@@ -1381,12 +1598,14 @@ function parseContinuationArgs(argv, valueFlags) {
     if (requestId !== undefined && !/^[A-Za-z0-9][A-Za-z0-9._:-]{7,63}$/.test(requestId)) {
         throw new ConductorValidationError('Flag "--request-id" is not a valid request id.');
     }
+    const contextFile = values.has("--context-file") ? requireFlag(values, "--context-file") : undefined;
     return {
         epicRunId,
         ticketKey,
         ...(reason ? { reason } : {}),
         ...(workerExitProof ? { workerExitProof: workerExitProof } : {}),
         ...(requestId ? { requestId } : {}),
+        ...(contextFile !== undefined ? { contextFile } : {}),
         json: bools.has("--json"),
         help: false,
     };
@@ -1441,12 +1660,40 @@ function currentLine(current) {
     return (`Current: parked at gate ${current.parked_gate} (episode ${current.park_generation}${age}); ` +
         `${available}.`);
 }
+// BAPI-1514 — presentation of the CI-aware continuation refusals (closed codes).
+const CI_GREEN_ADOPTED_REASON = "ci_green_adopted";
+const CI_GREEN_ADOPTED_TEXT = "already resolved — resumed without repair; no repair job was dispatched and no " +
+    "continuation allowance was charged";
+const CI_WAITING_TEXT = {
+    ci_pending_at_bound_head: "CI is still running at the bound head.",
+    ci_provider_read_unavailable: "the CI read failed or timed out.",
+    ci_observation_stale: "the pull-request head moved while CI was being read.",
+};
+const CI_WAITING_WHEN = {
+    ci_pending_at_bound_head: " after CI finishes",
+    ci_provider_read_unavailable: " after the CI provider recovers",
+    ci_observation_stale: " now (the server re-reads CI)",
+};
+const CI_ROUTE_GUIDANCE = {
+    ci_route_conflict: "The pull request is conflicting, so a CI repair is the wrong exit. Resolve the conflict " +
+        "instead (rebase / overlap reconciliation via dispatch-remediation). No repair was dispatched.",
+    ci_route_rerun: "This is an infrastructure CI failure; the server's infrastructure re-run path owns it " +
+        "(rerun-ci). No repair was dispatched.",
+    ci_route_hold: "CI routing is holding; no widened repair was dispatched. Re-read the run state " +
+        "(explain-run) before choosing another action.",
+    driver_context_not_supported: "--context-file applies only to a CI-repair (ci_fix) continuation. Drop --context-file " +
+        "and re-run with --reason only. Nothing was written.",
+};
 /** Exported for tests: render a `continue-child` result. Returns the exit code. */
 export function renderContinueChildResult(result, target, json) {
     const label = `Ticket ${target.ticketKey} (run ${target.epicRunId})`;
     if (result.kind === "decided") {
         const r = result.result;
-        const ok = r.outcome === "committed" || r.outcome === "already_continued";
+        const greenAdopted = r.outcome === "refused" && r.reason_code === CI_GREEN_ADOPTED_REASON;
+        const ok = r.outcome === "committed" || r.outcome === "already_continued" || greenAdopted;
+        // BAPI-1514 — only a committed receipt for THIS request is a real dispatch,
+        // and only that may count against an intervention budget or allowance.
+        const dispatched = continuationDispatchedJob(r);
         if (json) {
             console.log(JSON.stringify({
                 ok,
@@ -1457,6 +1704,9 @@ export function renderContinueChildResult(result, target, json) {
                 replayed: r.replayed,
                 retryable: r.retryable,
                 reference_reused: result.reusedReference,
+                dispatched,
+                allowance_charged: dispatched,
+                ...(greenAdopted ? { resolved_without_repair: true } : {}),
                 receipt: r.receipt === null ? null : receiptSummary(r.receipt),
                 current: currentSummary(r.current),
             }));
@@ -1486,7 +1736,27 @@ export function renderContinueChildResult(result, target, json) {
                 console.error(`${label}: continuation UNSUPPORTED (${r.reason_code}) — ${r.explanation}`);
                 return 1;
             default:
+                if (greenAdopted) {
+                    console.log(`${label}: ${CI_GREEN_ADOPTED_TEXT}.`);
+                    if (r.current)
+                        console.log(currentLine(r.current));
+                    return 0;
+                }
+                if (r.reason_code !== null && CONTINUATION_CI_WAITING_REASONS.has(r.reason_code)) {
+                    console.error(`${label}: WAITING (${r.reason_code}) — ${CI_WAITING_TEXT[r.reason_code] ?? r.explanation}`);
+                    console.error(`Nothing was written: no repair job was dispatched and no continuation allowance was charged. ` +
+                        `Re-run the same continue-child command${CI_WAITING_WHEN[r.reason_code] ?? ""}; it re-sends ` +
+                        `the SAME request (${result.requestId}).`);
+                    if (r.current?.expected_head_sha) {
+                        console.error(`Bound head: ${r.current.expected_head_sha}.`);
+                    }
+                    return 1;
+                }
                 console.error(`${label}: continuation REFUSED (${r.reason_code}) — ${r.explanation}`);
+                if (r.reason_code !== null && CI_ROUTE_GUIDANCE[r.reason_code] !== undefined) {
+                    console.error(CI_ROUTE_GUIDANCE[r.reason_code]);
+                    return 1;
+                }
                 if (r.retryable)
                     console.error("This refusal is retryable; nothing was written.");
                 return 1;
@@ -1505,6 +1775,11 @@ export function renderContinueChildResult(result, target, json) {
         }
         console.error(`${label}: request REJECTED before anything was written (status ${result.status}` +
             `${result.errorCode ? `, ${result.errorCode}` : ""}).`);
+        if (result.driverContextSent && result.status === 422) {
+            console.error("The request carried --context-file driver context. This server may not support it yet; " +
+                "the request was NOT retried without it. Upgrade the server, or drop --context-file " +
+                "deliberately and re-run.");
+        }
         return 1;
     }
     if (result.kind === "not_continuable") {
@@ -1588,13 +1863,26 @@ export function renderContinuationReceiptResult(result, target, json) {
     console.log(currentLine(status.current));
     return 0;
 }
-export async function runContinueChildCommand(argv) {
+export async function runContinueChildCommand(argv, deps = {}) {
     try {
         const parsed = parseContinueChildArgs(argv);
         if (parsed.help) {
             console.log(CONTINUE_CHILD_USAGE);
             return 0;
         }
+        // BAPI-1514 — read and validate the context BEFORE credentials are resolved,
+        // exactly as dispatch-remediation does, so an invalid file reaches no one.
+        let driverContext;
+        if (parsed.contextFile !== undefined) {
+            let bytes;
+            try {
+                bytes = await (deps.readFile ?? ((p) => readFile(p)))(parsed.contextFile);
+            }
+            catch {
+                throw new ConductorValidationError("--context-file could not be read; nothing was sent.");
+            }
+            driverContext = decodeDriverContextFile(bytes);
+        }
         const access = await resolveRecoveryAccess(parsed.json);
         if (!access)
             return 1;
@@ -1604,6 +1892,7 @@ export async function runContinueChildCommand(argv) {
             ticketKey: parsed.ticketKey,
             ...(parsed.reason ? { reason: parsed.reason } : {}),
             ...(parsed.workerExitProof ? { workerExitProof: parsed.workerExitProof } : {}),
+            ...(driverContext !== undefined ? { driverContext } : {}),
         });
         return renderContinueChildResult(result, parsed, parsed.json);
     }
@@ -1651,8 +1940,18 @@ export async function runGrantContinuationCommand(argv) {
             return 1;
         }
         const { requestId, outcome: result } = operation;
-        if (json)
-            console.log(JSON.stringify({ ...result, request_id: requestId }));
+        if (json) {
+            console.log(JSON.stringify(result.kind === "result"
+                ? {
+                    kind: result.kind,
+                    committed: result.committed,
+                    replayed: result.replayed,
+                    request_id: requestId,
+                    source_park_generation: result.sourceParkGeneration,
+                    gate: result.gate,
+                }
+                : { ...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")
@@ -1924,8 +2223,280 @@ export async function runResumeCiCommand(argv) {
         return RESUME_CI_EXIT_FAILED;
     }
 }
+// ---------------------------------------------------------------------------
+// BAPI-1532 — regenerate-plan
+// ---------------------------------------------------------------------------
+const REGENERATE_PLAN_USAGE = [
+    "Usage: epic-implementer regenerate-plan --epic-run-id <id> --ticket-key <key>",
+    "                                        --route <test|implementation> --reason <text> [--json]",
+    "",
+    "Answer a child parked on a NAMED plan failure with ONE forced plan regeneration on",
+    "the route you choose. The server checks the failure reason's finite allowance, then",
+    "commits the route override, the gate reset, and its audit event together.",
+    "",
+    "Success means the override and reset COMMITTED. It does not mean a usable plan",
+    "exists: request the plan and poll get_plan until it shows plan_metadata_status: ok.",
+    "",
+    "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 or stale; 3 unconfirmed; 1 other failure.",
+].join("\n");
+export const REGENERATE_PLAN_EXIT_OK = 0;
+export const REGENERATE_PLAN_EXIT_FAILED = 1;
+export const REGENERATE_PLAN_EXIT_REFUSED = 2;
+export const REGENERATE_PLAN_EXIT_UNCONFIRMED = 3;
+/** The fixed text a server that lacks the route is reported under. */
+export const REGENERATE_PLAN_SERVER_TOO_OLD = "server too old";
+export function parseRegeneratePlanArgs(argv) {
+    const { values, bools } = tokenizeRecoveryFlags(argv, new Set([...TICKET_VALUE_FLAGS, "--route", "--reason"]), RECOVERY_BOOL_FLAGS);
+    if (bools.has("--help")) {
+        return { epicRunId: "", ticketKey: "", route: "test", json: bools.has("--json"), help: true };
+    }
+    const epicRunId = values.get("--epic-run-id");
+    if (epicRunId === undefined || epicRunId.trim().length === 0) {
+        throw new ConductorValidationError('Flag "--epic-run-id" is required and must be non-empty.');
+    }
+    const ticketKey = values.get("--ticket-key");
+    if (ticketKey === undefined || ticketKey.trim().length === 0) {
+        throw new ConductorValidationError('Flag "--ticket-key" is required and must be non-empty.');
+    }
+    const route = values.get("--route")?.trim();
+    if (route !== "test" && route !== "implementation") {
+        throw new ConductorValidationError('Flag "--route" is required and must be "test" or "implementation".');
+    }
+    const reason = values.get("--reason")?.trim();
+    if (reason === undefined || reason.length === 0) {
+        throw new ConductorValidationError('Flag "--reason" is required and must be non-empty.');
+    }
+    return {
+        epicRunId: epicRunId.trim(),
+        ticketKey: ticketKey.trim(),
+        route,
+        reason,
+        json: bools.has("--json"),
+        help: false,
+    };
+}
+/** Fixed operator sentences, chosen by the server's structured code. */
+const REGENERATE_PLAN_REFUSAL_SENTENCES = {
+    TICKET_NOT_IN_RUN: "the ticket is not part of this run",
+    NOT_FOUND: "the run or ticket was not found",
+    PLAN_REGEN_NOT_ELIGIBLE: "the ticket is not parked on a named plan failure at the implement gate",
+    PLAN_REGEN_OPERATION_CONFLICT: "this operation already names a different regeneration",
+    PLAN_REGEN_ANSWERED_CONFLICT: "this park was already answered with a different route",
+    PLAN_REGEN_STALE_PARK: "the ticket is on a different park than this request was made for",
+    PLAN_REGEN_ALLOWANCE_SPENT: "every regeneration this failure reason allows has been used",
+    PLAN_REGEN_ROUTE_NOT_ALLOWED: "that route is not the one the next regeneration allows",
+    PLAN_REGEN_RUN_NOT_ACTIVE: "the run is paused, stopped, quarantined, or not active",
+    PLAN_REGEN_BUSY: "the ticket or run stayed busy for the whole bounded wait",
+    PLAN_REGEN_SCHEMA_UNAVAILABLE: "the server database has not been migrated for this action yet",
+    SPEC_SNAPSHOT_UNAVAILABLE: "the ticket's current specification could not be read",
+    CONFLICT: "the ticket kept changing while the request was being applied",
+};
+const REGENERATE_PLAN_GUIDANCE = "Read `epic-implementer explain-run` for the ticket's current park and next action.";
+const REGENERATE_PLAN_NOT_ELIGIBLE_TEXT = {
+    ticket_not_found: "the ticket is not part of this run",
+    not_parked: "the ticket is not parked",
+    not_implement_park: "the ticket is not parked at the implement gate",
+    no_plan_failure: "the park has no named plan failure (a legacy or unrelated park)",
+    park_superseded: "the plan failure was already answered or belongs to an earlier park",
+};
+/**
+ * Exported for tests: render a `regenerate-plan` result.
+ *
+ * Committed and replayed results go to stdout with exit 0 (JSON stdout stays
+ * machine-readable; progress goes to stderr). Refused, stale, unconfirmed, and
+ * failed outcomes go to stderr with their own non-zero codes. No operation key,
+ * row version, credential, server exception, or URL is ever printed.
+ */
+export function renderRegeneratePlanResult(result, target, json) {
+    const label = `ticket ${target.ticketKey} (run ${target.epicRunId})`;
+    if (result.kind === "committed" || result.kind === "replayed" || result.kind === "answered_replay") {
+        const r = result.result;
+        if (json) {
+            console.log(JSON.stringify({
+                ok: true,
+                outcome: result.kind,
+                historical: result.kind !== "committed",
+                epic_run_id: r.epic_run_id,
+                ticket_key: r.ticket_key,
+                accepted_route: r.accepted_route,
+                answered_park_generation: r.answered_park_generation,
+                ticket_status: r.ticket_status,
+                plan_ready: false,
+                reference_reused: result.reusedReference,
+            }));
+            return REGENERATE_PLAN_EXIT_OK;
+        }
+        if (result.kind === "committed") {
+            console.log(`Committed: the ${r.accepted_route} route override and the gate reset for ${label}. ` +
+                "This does NOT mean a usable plan exists.");
+            console.log("Next: request the plan and poll get_plan until it shows plan_metadata_status: ok.");
+        }
+        else {
+            console.log(`Replayed historical result: regenerate-plan for ${label} committed earlier on the ` +
+                `${r.accepted_route} route. Nothing was changed by this call.`);
+            console.log("This does not show that a usable plan exists.");
+        }
+        return REGENERATE_PLAN_EXIT_OK;
+    }
+    if (result.kind === "unsupported_server") {
+        // The server predates the route. Nothing was written and no other mutation
+        // stands in for it.
+        if (json) {
+            console.error(JSON.stringify({
+                ok: false,
+                outcome: "unsupported_server",
+                message: REGENERATE_PLAN_SERVER_TOO_OLD,
+                nothing_written: true,
+            }));
+        }
+        else {
+            console.error(REGENERATE_PLAN_SERVER_TOO_OLD);
+        }
+        return REGENERATE_PLAN_EXIT_FAILED;
+    }
+    if (result.kind === "refused" || result.kind === "not_eligible" ||
+        result.kind === "stale_subject" || result.kind === "pinned_mismatch") {
+        let code;
+        let sentence;
+        if (result.kind === "refused") {
+            code = result.errorCode;
+            sentence = REGENERATE_PLAN_REFUSAL_SENTENCES[code] ?? "the server refused the request";
+        }
+        else if (result.kind === "stale_subject") {
+            code = "REPAIR_SUBJECT_STALE";
+            sentence = "the ticket is no longer on the park this operation was made for";
+        }
+        else if (result.kind === "pinned_mismatch") {
+            code = "PLAN_REGEN_PINNED_ROUTE";
+            sentence =
+                `an earlier unconfirmed regenerate-plan is pinned on the ${result.pinnedRoute} route; ` +
+                    "re-run it with that route";
+        }
+        else {
+            code = "PLAN_REGEN_NOT_ELIGIBLE";
+            sentence = REGENERATE_PLAN_NOT_ELIGIBLE_TEXT[result.reason] ?? "regenerate-plan does not apply";
+        }
+        if (json) {
+            console.error(JSON.stringify({
+                ok: false,
+                outcome: "refused",
+                refusal_code: code,
+                ...(result.kind === "not_eligible" ? { local_reason: result.reason } : {}),
+                message: sentence,
+                guidance: REGENERATE_PLAN_GUIDANCE,
+                nothing_written: true,
+            }));
+            return REGENERATE_PLAN_EXIT_REFUSED;
+        }
+        console.error(`Refused: regenerate-plan for ${label} — ${sentence}. Nothing was written.`);
+        console.error(REGENERATE_PLAN_GUIDANCE);
+        return REGENERATE_PLAN_EXIT_REFUSED;
+    }
+    if (result.kind === "unconfirmed") {
+        if (json) {
+            console.error(JSON.stringify({
+                ok: false,
+                outcome: "unconfirmed",
+                transport: result.transport,
+                attempts: result.attempts,
+            }));
+            return REGENERATE_PLAN_EXIT_UNCONFIRMED;
+        }
+        console.error(`Unconfirmed: regenerate-plan for ${label} — no durable answer arrived after ${result.attempts} ` +
+            `attempts (${result.transport}). The regeneration 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 REGENERATE_PLAN_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: regenerate-plan for ${label} — ${message}.`);
+    }
+    return REGENERATE_PLAN_EXIT_FAILED;
+}
+export async function runRegeneratePlanCommand(argv) {
+    try {
+        const parsed = parseRegeneratePlanArgs(argv);
+        if (parsed.help) {
+            console.log(REGENERATE_PLAN_USAGE);
+            return 0;
+        }
+        const access = await resolveRecoveryAccess(parsed.json);
+        if (!access)
+            return REGENERATE_PLAN_EXIT_FAILED;
+        const { regeneratePlanOnce } = await import("./recovery-operations.js");
+        if (!parsed.json) {
+            // Progress goes to stderr so stdout stays the result alone.
+            console.error(`Requesting plan regeneration for ticket ${parsed.ticketKey} on the ${parsed.route} route...`);
+        }
+        const result = await regeneratePlanOnce(access, {
+            epicRunId: parsed.epicRunId,
+            ticketKey: parsed.ticketKey,
+            route: parsed.route,
+            reason: parsed.reason ?? "",
+        });
+        return renderRegeneratePlanResult(result, parsed, parsed.json);
+    }
+    catch (error) {
+        console.error(`Error: ${toConductorErrorEnvelope(error).message}`);
+        return REGENERATE_PLAN_EXIT_FAILED;
+    }
+}
+const ESCALATE_FALLBACK_MESSAGE = "Escalation request refused or unavailable.";
+/**
+ * Build the safe failure document for `escalate`. Reads ONLY a bridge error's
+ * `errorCode`, `status`, and already-redacted `bodyPreview`; every other failure
+ * gets a stable local code and a fixed message. Arbitrary exception text is never
+ * inspected, and no command-specific redaction is added here.
+ */
+export function formatEscalateError(error) {
+    // Recognized by name rather than `instanceof`: the client module is imported
+    // lazily inside the command, so this formatter does not load it.
+    if (error instanceof Error && error.name === "ConductorBridgeApiError") {
+        const bridge = error;
+        const preview = typeof bridge.bodyPreview === "string" ? bridge.bodyPreview.trim() : "";
+        return {
+            ok: false,
+            error_code: typeof bridge.errorCode === "string" && bridge.errorCode.length > 0
+                ? bridge.errorCode
+                : "ESCALATE_REQUEST_FAILED",
+            status: typeof bridge.status === "number" ? bridge.status : null,
+            message: preview.length > 0 ? preview : ESCALATE_FALLBACK_MESSAGE,
+        };
+    }
+    if (error instanceof ConductorValidationError) {
+        return {
+            ok: false,
+            error_code: "ESCALATE_INVALID_ARGUMENTS",
+            status: null,
+            message: "Invalid escalate arguments; run with --help for usage.",
+        };
+    }
+    return {
+        ok: false,
+        error_code: "ESCALATE_UNEXPECTED_FAILURE",
+        status: null,
+        message: ESCALATE_FALLBACK_MESSAGE,
+    };
+}
 /** No state mutation: callers halt the affected work before asking a question. */
 export async function runEscalateCommand(argv, deps = {}) {
+    // Captured before parsing can throw, so a malformed command line still answers
+    // in the format the caller asked for.
+    const json = argv.includes("--json");
+    const fail = (document) => {
+        if (json)
+            console.log(JSON.stringify(document));
+        else
+            console.error(`Error: ${document.error_code}: ${document.message}`);
+        return 1;
+    };
     try {
         const { values, bools } = tokenizeRecoveryFlags(argv, new Set(["--epic-run-id", "--ticket-key", "--cause", "--action-needed"]), RECOVERY_BOOL_FLAGS);
         if (bools.has("--help")) {
@@ -1936,18 +2507,32 @@ export async function runEscalateCommand(argv, deps = {}) {
             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;
+            return fail({
+                ok: false,
+                error_code: "ESCALATE_INVALID_ARGUMENTS",
+                status: null,
+                message: "action-needed exceeds 300 characters",
+            });
+        }
+        const resolveAccess = deps.resolveAccess ?? (async () => {
+            const { resolveConductorBridgeApiAccess } = await import("./bridge-api-client.js");
+            const resolved = await resolveConductorBridgeApiAccess();
+            return resolved.ok ? resolved.access : null;
+        });
+        const access = await resolveAccess();
+        if (!access) {
+            return fail({
+                ok: false,
+                error_code: "ESCALATE_CREDENTIALS_UNAVAILABLE",
+                status: null,
+                message: "Bridge API credentials could not be resolved.",
+            });
         }
-        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;
+    catch (error) {
+        return fail(formatEscalateError(error));
     }
 }