@bridge_gpt/mcp-server 0.2.62 → 0.2.65

package/build/conductor/recovery-cli.js

@@ -1,13 +1,14 @@
 /**
- * `conductor` operator recovery and repair verbs — ten CLI-only commands.
+ * `conductor` operator recovery and repair verbs — twelve 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`.
+ * `scope-catch-up`, `patch-policy`, `resume-run`. BAPI-1300's parked-child
+ * continuation pair: `continue-child` and the read-only `continuation-receipt`.
  *
  * CLI-only by design — this is an explicit ticket non-goal, not an oversight:
- * none of these ten command names is ever registered as an MCP tool, tool
+ * none of these twelve 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
@@ -23,7 +24,7 @@
  */
 import { readFile } from "node:fs/promises";
 import { ConductorValidationError, toConductorErrorEnvelope } from "./errors.js";
-import { DRIVER_CONTEXT_MAX_BYTES, POLICY_PATCH_MAX_BYTES } from "./repair-contract.js";
+import { DRIVER_CONTEXT_MAX_BYTES, POLICY_PATCH_MAX_BYTES, RESUME_RUN_UNCONFIRMED_MESSAGE, } from "./repair-contract.js";
 // ---------------------------------------------------------------------------
 // Flag parsing
 // ---------------------------------------------------------------------------
@@ -43,6 +44,12 @@ const REJECTED_VERSION_FLAGS = new Set([
     "--expected_row_version",
     "--expected-generation",
     "--expected_generation",
+    // BAPI-1300: the continuation's park-episode binding is read once and stored
+    // by the client itself; an operator never supplies it.
+    "--park-generation",
+    "--park_generation",
+    "--source-park-generation",
+    "--source_park_generation",
 ]);
 /**
  * Tokenize `--flag value` / `--flag=value` / boolean flags for the recovery
@@ -266,16 +273,52 @@ const ADOPT_CURRENT_HEAD_USAGE = [
     "off its anchored commit: adopt the CURRENT PR head and unpark in one step.",
     "Retries a bounded number of times on its own if the ticket changes",
     "concurrently — never accepts a version counter.",
+    "",
+    "For a ticket parked as unexplained_review_head_drift this is \"Adopt current",
+    "head and resume CI\": the server reads the provider's current head, accepts it,",
+    "keeps every repair allowance already spent (no repair attempt is granted), and",
+    "resumes the ticket at CI. No worker is started and nothing is marked passed —",
+    "CI and review must pass again on the accepted head. A repeat of the same",
+    "request reports the recorded result instead of adopting twice.",
 ].join("\n");
-function renderTicketRecoveryResult(result, json) {
+/** BAPI-1310 (E1): the fixed allowance sentence the adoption result carries. */
+const REVIEW_HEAD_ALLOWANCE_LINE = "Allowance effect: repair allowances preserved; acceptance does not grant another repair.";
+/** BAPI-1310 (E1): the warning shown when run control still holds the run. */
+export const REVIEW_HEAD_HELD_WARNING = "Head accepted; run remains held by run control";
+/** Render the E1 adoption result (committed or replayed) to stdout. */
+function renderReviewHeadRecovery(ticketKey, epicRunId, recovery) {
+    const outcome = recovery.result === "replayed"
+        ? "replayed — this operation already committed; nothing changed now"
+        : "committed";
+    console.log(`Ticket ${ticketKey} (run ${epicRunId}): Adopt current head and resume CI — ${outcome}.`);
+    console.log(`  Previous expected head: ${recovery.previous_expected_head_sha}`);
+    console.log(`  Committed accepted head: ${recovery.accepted_head_sha}`);
+    console.log(`  ${REVIEW_HEAD_ALLOWANCE_LINE}`);
+    console.log(`  Resumed at: ${recovery.resumed_gate}`);
+    console.log(`  Current gate: ${recovery.current_gate ?? "unavailable"}`);
+    console.log("  CI and review must pass again on the accepted head; no worker was started and nothing was marked passed.");
+    if (recovery.held_by_run_control) {
+        console.log(`  WARNING: ${REVIEW_HEAD_HELD_WARNING}.`);
+    }
+}
+export function renderTicketRecoveryResult(result, json) {
     if (json) {
         console.log(JSON.stringify(result));
         return result.ok ? 0 : 1;
     }
     if (result.ok) {
+        if (result.reviewHeadRecovery) {
+            renderReviewHeadRecovery(result.ticketKey, result.epicRunId, result.reviewHeadRecovery);
+            return 0;
+        }
         console.log(`Ticket ${result.ticketKey} (run ${result.epicRunId}): unparked — status: ${result.status}.`);
         return 0;
     }
+    if (result.kind === "refused") {
+        console.error(`Ticket ${result.ticketKey} (run ${result.epicRunId}): refused (${result.errorCode}) — ` +
+            `${result.message}. The ticket remains parked; nothing was changed.`);
+        return 1;
+    }
     if (result.kind === "ticket-not-found") {
         console.error(`Ticket ${result.ticketKey}: not found in run ${result.epicRunId}.`);
         return 1;
@@ -440,7 +483,7 @@ function renderRepairResult(outcome, input, json, extraLines = () => []) {
         }
         console.log(JSON.stringify(outcome.kind === "refused"
             ? { ok: false, kind: "refused", code: outcome.code, message: outcome.message }
-            : { ok: false, kind: "unavailable", message: outcome.message }));
+            : { ok: false, kind: "unavailable", message: input.unavailableMessage ?? outcome.message }));
         return 1;
     }
     if (!outcome.ok) {
@@ -448,6 +491,10 @@ function renderRepairResult(outcome, input, json, extraLines = () => []) {
             console.error(`Error: ${input.verb} refused on run ${input.epicRunId} (${input.targetLabel}) — ` +
                 `${outcome.code}: ${outcome.message}`);
         }
+        else if (input.unavailableMessage) {
+            console.error(`Error: ${input.verb} on run ${input.epicRunId} (${input.targetLabel}) — ` +
+                `${input.unavailableMessage}.`);
+        }
         else {
             console.error(`Error: ${input.verb} could not complete on run ${input.epicRunId} ` +
                 `(${input.targetLabel}) — ${outcome.message}.`);
@@ -788,11 +835,16 @@ export async function runPatchPolicyCommand(argv, deps = {}) {
 const RESUME_RUN_USAGE = [
     "Usage: epic-implementer resume-run --epic-run-id <id> [--clear-quarantine] [--json]",
     "",
-    "Clear a paused run's control record and return it to active, after the server",
-    "re-checks the run's activation requirements. A quarantined run resumes only with",
-    "--clear-quarantine; a stopped run never resumes (start a new run). A run that is",
-    "already active with no control record is a successful no-op. The server retries",
-    "a concurrent control change itself — never supply a generation.",
+    "Return a held run to active, after the server re-checks the run's activation",
+    "requirements. A paused run's control record is cleared. A run blocked by an",
+    "eligible integration block has that block lifted (there is no control record",
+    "to clear); the server decides eligibility. A quarantined run resumes only with",
+    "--clear-quarantine; a stopped run never resumes (start a new run). A run that",
+    "is already active and unheld is a successful no-op (already current). The",
+    "server retries a concurrent control change itself — never supply a generation.",
+    "",
+    "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.",
 ].join("\n");
 export async function runResumeRunCommand(argv) {
     try {
@@ -812,8 +864,9 @@ export async function runResumeRunCommand(argv) {
         return renderRepairResult(outcome, {
             verb: "resume-run",
             epicRunId: parsed.epicRunId,
-            targetLabel: parsed.clearQuarantine ? "run control (clear quarantine)" : "run control",
-            stateLabel: "run control",
+            targetLabel: parsed.clearQuarantine ? "run (clear quarantine)" : "run",
+            stateLabel: "run state",
+            unavailableMessage: RESUME_RUN_UNCONFIRMED_MESSAGE,
         }, parsed.json);
     }
     catch (error) {
@@ -821,3 +874,291 @@ export async function runResumeRunCommand(argv) {
         return 1;
     }
 }
+// ---------------------------------------------------------------------------
+// continue-child / continuation-receipt (BAPI-1300)
+// ---------------------------------------------------------------------------
+const CONTINUE_CHILD_VALUE_FLAGS = new Set(["--epic-run-id", "--ticket-key", "--reason"]);
+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]",
+    "",
+    "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",
+    "fresh budget, no counter or clock reset — use unpark for that). The server",
+    "commits one job and one durable receipt together, at most once per episode.",
+    "",
+    "If the response is lost, the outcome is reported UNCONFIRMED, never refused or",
+    "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.",
+].join("\n");
+const CONTINUATION_RECEIPT_USAGE = [
+    "Usage: epic-implementer continuation-receipt --epic-run-id <id> --ticket-key <key> [--request-id <id>] [--json]",
+    "",
+    "Read-only. Show the child's current park episode and, for the pending local",
+    "continuation request (or --request-id), whether its receipt proves a commit.",
+    "A missing receipt is not a refusal. Looking history up authorizes nothing.",
+].join("\n");
+function parseContinuationArgs(argv, valueFlags) {
+    const { values, bools } = tokenizeRecoveryFlags(argv, valueFlags, RECOVERY_BOOL_FLAGS);
+    if (bools.has("--help")) {
+        return { epicRunId: "", ticketKey: "", json: bools.has("--json"), help: true };
+    }
+    const epicRunId = requireFlag(values, "--epic-run-id");
+    const ticketKey = requireFlag(values, "--ticket-key");
+    const reason = values.get("--reason")?.trim();
+    if (reason !== undefined && reason.length > MAX_REASON_CHARS) {
+        throw new ConductorValidationError(`Flag "--reason" must be at most ${MAX_REASON_CHARS} characters.`);
+    }
+    const requestId = values.get("--request-id")?.trim();
+    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.');
+    }
+    return {
+        epicRunId,
+        ticketKey,
+        ...(reason ? { reason } : {}),
+        ...(requestId ? { requestId } : {}),
+        json: bools.has("--json"),
+        help: false,
+    };
+}
+/** Exported for tests: parse `continue-child` arguments. */
+export function parseContinueChildArgs(argv) {
+    return parseContinuationArgs(argv, CONTINUE_CHILD_VALUE_FLAGS);
+}
+/** Exported for tests: parse `continuation-receipt` arguments. */
+export function parseContinuationReceiptArgs(argv) {
+    return parseContinuationArgs(argv, CONTINUATION_RECEIPT_VALUE_FLAGS);
+}
+function receiptSummary(receipt) {
+    return {
+        receipt_id: receipt.receipt_id,
+        request_id: receipt.request_id,
+        gate: receipt.gate,
+        job_type: receipt.job_type,
+        continuation_job_id: receipt.continuation_job_id,
+        original_job_id: receipt.original_job_id,
+        source_park_generation: receipt.source_park_generation,
+        resulting_park_generation: receipt.resulting_park_generation,
+        committed_at: receipt.committed_at,
+        runtime_outcome: receipt.runtime_outcome,
+    };
+}
+function currentSummary(current) {
+    if (current === null)
+        return null;
+    return {
+        status: current.status,
+        parked: current.parked,
+        parked_gate: current.parked_gate,
+        park_generation: current.park_generation,
+        parked_age_seconds: current.parked_age_seconds,
+        needs_human_reason: current.needs_human_reason,
+        unresolved_obligations: current.unresolved_obligations,
+        continuations_used: current.continuations_used,
+        continuation_limit: current.continuation_limit,
+        continuation_available: current.continuation_available,
+        continuation_unavailable_reason: current.continuation_unavailable_reason,
+    };
+}
+function currentLine(current) {
+    if (!current.parked) {
+        return `Current: status ${current.status} (not parked).`;
+    }
+    const age = current.parked_age_seconds === null ? "" : `, parked ${current.parked_age_seconds}s`;
+    const available = current.continuation_available
+        ? "continuation available"
+        : `continuation unavailable (${current.continuation_unavailable_reason ?? "unknown"})`;
+    return (`Current: parked at gate ${current.parked_gate} (episode ${current.park_generation}${age}); ` +
+        `${available}.`);
+}
+/** 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";
+        if (json) {
+            console.log(JSON.stringify({
+                ok,
+                kind: r.outcome,
+                reason_code: r.reason_code,
+                explanation: r.explanation,
+                request_id: result.requestId,
+                replayed: r.replayed,
+                retryable: r.retryable,
+                reference_reused: result.reusedReference,
+                receipt: r.receipt === null ? null : receiptSummary(r.receipt),
+                current: currentSummary(r.current),
+            }));
+            return ok ? 0 : 1;
+        }
+        const receipt = r.receipt;
+        switch (r.outcome) {
+            case "committed":
+                console.log(`${label}: continuation COMMITTED${r.replayed ? " (replayed — already committed earlier)" : ""} — ` +
+                    `job #${receipt?.continuation_job_id} (${receipt?.job_type}) dispatched for park episode ` +
+                    `${receipt?.source_park_generation}; receipt ${receipt?.receipt_id}. This proves the dispatch, ` +
+                    "not that the work has finished.");
+                return 0;
+            case "already_continued":
+                console.log(`${label}: this park episode was ALREADY CONTINUED by another request — job ` +
+                    `#${receipt?.continuation_job_id}, receipt ${receipt?.receipt_id}. Nothing was dispatched ` +
+                    "for this request.");
+                return 0;
+            case "stale_historical_episode":
+                console.error(`${label}: STALE HISTORICAL EPISODE — receipt ${receipt?.receipt_id} (job ` +
+                    `#${receipt?.continuation_job_id}) belongs to park episode ${receipt?.source_park_generation}, ` +
+                    "which is history. The child has parked again and was NOT resumed by it.");
+                if (r.current)
+                    console.error(currentLine(r.current));
+                return 1;
+            case "unsupported":
+                console.error(`${label}: continuation UNSUPPORTED (${r.reason_code}) — ${r.explanation}`);
+                return 1;
+            default:
+                console.error(`${label}: continuation REFUSED (${r.reason_code}) — ${r.explanation}`);
+                if (r.retryable)
+                    console.error("This refusal is retryable; nothing was written.");
+                return 1;
+        }
+    }
+    if (result.kind === "refused_http") {
+        if (json) {
+            console.log(JSON.stringify({
+                ok: false,
+                kind: "refused",
+                status: result.status,
+                code: result.errorCode,
+                request_id: result.requestId,
+            }));
+            return 1;
+        }
+        console.error(`${label}: request REJECTED before anything was written (status ${result.status}` +
+            `${result.errorCode ? `, ${result.errorCode}` : ""}).`);
+        return 1;
+    }
+    if (result.kind === "not_continuable") {
+        if (json) {
+            console.log(JSON.stringify({ ok: false, kind: "not_continuable", current: currentSummary(result.current) }));
+            return 1;
+        }
+        console.error(`${label}: not continuable right now. Nothing was sent.`);
+        console.error(currentLine(result.current));
+        return 1;
+    }
+    if (result.kind === "unconfirmed") {
+        if (json) {
+            console.log(JSON.stringify({
+                ok: false,
+                kind: "unconfirmed",
+                transport: result.transport,
+                request_id: result.requestId,
+                reference_reused: result.reusedReference,
+            }));
+            return 1;
+        }
+        console.error(`${label}: continuation UNCONFIRMED after ${result.transport} — the request may or may not have ` +
+            `committed, and no receipt proves it yet (request ${result.requestId}).`);
+        console.error(`Look it up: epic-implementer continuation-receipt --epic-run-id ${target.epicRunId} ` +
+            `--ticket-key ${target.ticketKey}. Re-running continue-child reuses this same request; it ` +
+            "never starts a new one.");
+        return 1;
+    }
+    if (json) {
+        console.log(JSON.stringify({ ok: false, kind: "unavailable", message: result.message }));
+        return 1;
+    }
+    console.error(`${label}: could not continue — ${result.message}. Nothing was sent.`);
+    return 1;
+}
+/** Exported for tests: render a `continuation-receipt` lookup. */
+export function renderContinuationReceiptResult(result, target, json) {
+    const label = `Ticket ${target.ticketKey} (run ${target.epicRunId})`;
+    if (result.kind === "unavailable") {
+        if (json) {
+            console.log(JSON.stringify({ ok: false, kind: "unavailable", message: result.message }));
+        }
+        else {
+            console.error(`${label}: could not read — ${result.message}.`);
+        }
+        return 1;
+    }
+    const status = result.status;
+    if (json) {
+        console.log(JSON.stringify({
+            ok: true,
+            kind: result.kind,
+            request_id: result.requestId,
+            outcome: status.outcome,
+            receipt: status.receipt === null ? null : receiptSummary(status.receipt),
+            current: currentSummary(status.current),
+        }));
+        return 0;
+    }
+    if (result.kind === "found" && status.receipt !== null) {
+        const r = status.receipt;
+        console.log(`${label}: receipt ${r.receipt_id} — continuation COMMITTED at ${r.committed_at}: job ` +
+            `#${r.continuation_job_id} (${r.job_type}, runtime ${r.runtime_outcome ?? "unknown"}) for park ` +
+            `episode ${r.source_park_generation}.`);
+        if (status.outcome === "stale_historical_episode") {
+            console.log("That episode is history: the child has parked again since.");
+        }
+    }
+    else if (result.requestId !== null) {
+        console.log(`${label}: no receipt for request ${result.requestId} — its commit is NOT proven (this is not a refusal).`);
+    }
+    else {
+        console.log(`${label}: no pending local continuation request.`);
+    }
+    console.log(currentLine(status.current));
+    return 0;
+}
+export async function runContinueChildCommand(argv) {
+    try {
+        const parsed = parseContinueChildArgs(argv);
+        if (parsed.help) {
+            console.log(CONTINUE_CHILD_USAGE);
+            return 0;
+        }
+        const access = await resolveRecoveryAccess(parsed.json);
+        if (!access)
+            return 1;
+        const { continueChildOnce } = await import("./recovery-operations.js");
+        const result = await continueChildOnce(access, {
+            epicRunId: parsed.epicRunId,
+            ticketKey: parsed.ticketKey,
+            ...(parsed.reason ? { reason: parsed.reason } : {}),
+        });
+        return renderContinueChildResult(result, parsed, parsed.json);
+    }
+    catch (error) {
+        console.error(`Error: ${toConductorErrorEnvelope(error).message}`);
+        return 1;
+    }
+}
+export async function runContinuationReceiptCommand(argv) {
+    try {
+        const parsed = parseContinuationReceiptArgs(argv);
+        if (parsed.help) {
+            console.log(CONTINUATION_RECEIPT_USAGE);
+            return 0;
+        }
+        const access = await resolveRecoveryAccess(parsed.json);
+        if (!access)
+            return 1;
+        const { lookupContinuationReceipt } = await import("./recovery-operations.js");
+        const result = await lookupContinuationReceipt(access, {
+            epicRunId: parsed.epicRunId,
+            ticketKey: parsed.ticketKey,
+            ...(parsed.requestId ? { requestId: parsed.requestId } : {}),
+        });
+        return renderContinuationReceiptResult(result, parsed, parsed.json);
+    }
+    catch (error) {
+        console.error(`Error: ${toConductorErrorEnvelope(error).message}`);
+        return 1;
+    }
+}