@bridge_gpt/mcp-server 0.2.65 → 0.2.67

package/build/conductor/recovery-cli.js

@@ -1,14 +1,16 @@
 /**
- * `conductor` operator recovery and repair verbs — twelve CLI-only commands.
+ * `conductor` operator recovery and repair verbs — fourteen 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`. BAPI-1388's guided
+ * provider re-run of failed CI workflow runs: `rerun-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 fourteen 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 +27,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 +381,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 +413,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 +473,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 +655,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 +669,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,
@@ -554,15 +710,23 @@ export async function runScopeReparseCommand(argv) {
 const DISPATCH_REMEDIATION_USAGE = [
     "Usage: epic-implementer dispatch-remediation --epic-run-id <id> --ticket-key <key> --context-file <path> [--json]",
     "",
-    "Dispatch a remediation job for a ticket at code_review (or parked there),",
+    "Dispatch a remediation job for a ticket at code_review or ci (or parked there),",
     "carrying your driver context to the worker. The SERVER chooses the job type",
-    "(remediate, or reconcile_overlap for a conflict/overlap ticket) and admits it",
+    "(remediate, or reconcile_overlap for a conflict/overlap ticket; ci_fix for a CI",
+    "failure the server's FRESH CI read routes to investigation) and admits it",
     "through the reconciler's own strict-serial lane, remediation budget, and",
-    "dedup key. A parked ticket is resumed in the same step.",
+    "dedup key. A parked ticket is resumed in the same step (unguided only). An",
+    "infrastructure CI failure is refused by name and points to rerun-ci.",
     "",
     `--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 +745,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: "selected gate",
+            }, parsed.json);
+        }
         const { dispatchRemediationRepair } = await import("./recovery-operations.js");
         const outcome = await dispatchRemediationRepair(access, {
             epicRunId: parsed.epicRunId,
@@ -594,7 +780,7 @@ export async function runDispatchRemediationCommand(argv, deps = {}) {
             verb: "dispatch-remediation",
             epicRunId: parsed.epicRunId,
             targetLabel: `ticket ${parsed.ticketKey}`,
-            stateLabel: "code_review gate",
+            stateLabel: "selected gate",
         }, parsed.json, (result) => [
             `  job:             ${result.job_type || "unknown"}${result.job_id !== null ? ` (job ${result.job_id})` : ""}`,
         ]);
@@ -604,6 +790,195 @@ export async function runDispatchRemediationCommand(argv, deps = {}) {
         return 1;
     }
 }
+// ---------------------------------------------------------------------------
+// BAPI-1388 — rerun-ci
+// ---------------------------------------------------------------------------
+const RERUN_CI_VALUE_FLAGS = new Set(["--epic-run-id", "--ticket-key", "--binding"]);
+/** Exit codes: 0 applied (including an all-not-re-runnable no-op), 2 refused/stale, 3 unconfirmed, 1 other. */
+export const RERUN_CI_EXIT_OK = 0;
+export const RERUN_CI_EXIT_FAILED = 1;
+export const RERUN_CI_EXIT_REFUSED = 2;
+export const RERUN_CI_EXIT_UNCONFIRMED = 3;
+const RERUN_CI_USAGE = [
+    "Usage: epic-implementer rerun-ci --epic-run-id <id> --ticket-key <key> --binding <token> [--json]",
+    "",
+    "Ask the CI provider to re-run a ticket's FAILED required checks at its bound head,",
+    "for a ticket at ci or parked on it. Copy the command exactly as the run",
+    "explanation rendered it: --binding pins the ticket version and head it showed.",
+    "The SERVER re-reads fresh CI evidence, re-runs each GitHub Actions workflow run at",
+    "most once per head, and reports every failed check as enqueued, deduplicated,",
+    "deferred, or not_re_runnable.",
+    "",
+    "rerun-ci NEVER re-runs the claude-review workflow. It charges no allowance and",
+    "changes no park state, and a re-run is not a verdict: when CI is green, use",
+    "`epic-implementer resume-ci` (a parked ticket) or let the reconciler observe it.",
+    "If the failure is a code defect, use `dispatch-remediation --context-file`.",
+    "",
+    "The request 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 codes: 0 applied (including a no-op when nothing could be re-run); 2 refused",
+    "or stale; 3 unconfirmed; 1 other failure (including a server without this verb).",
+].join("\n");
+export function parseRerunCiArgs(argv) {
+    const { values, bools } = tokenizeRecoveryFlags(argv, RERUN_CI_VALUE_FLAGS, RECOVERY_BOOL_FLAGS);
+    if (bools.has("--help")) {
+        return { epicRunId: "", ticketKey: "", binding: "", json: bools.has("--json"), help: true };
+    }
+    return {
+        epicRunId: requireFlag(values, "--epic-run-id"),
+        ticketKey: requireFlag(values, "--ticket-key"),
+        binding: requireFlag(values, "--binding"),
+        json: bools.has("--json"),
+        help: false,
+    };
+}
+const RERUN_CI_STATUS_TEXT = {
+    enqueued: "re-run requested",
+    deduplicated: "already requested",
+    deferred: "deferred (not requested; run the verb again after a fresh explain-run)",
+    not_re_runnable: "not re-runnable",
+};
+const RERUN_CI_REASON_TEXT = {
+    not_github_actions: "not a GitHub Actions check",
+    no_workflow_run_id: "no workflow run id",
+    claude_review_excluded: "claude-review is never re-run",
+};
+const RERUN_CI_OUTCOME_TEXT = {
+    enqueued: "re-runs requested",
+    partial: "partially requested (some runs deferred)",
+    nothing_to_enqueue: "nothing to enqueue (no failed check could be re-run)",
+};
+const RERUN_CI_NEXT_ACTION = {
+    enqueued: "Wait for the re-runs to finish, then read `epic-implementer explain-run`. When CI is " +
+        "green use `epic-implementer resume-ci` (a parked ticket); this verb did not mark CI passed.",
+    partial: "Some runs were not requested. Read `epic-implementer explain-run` and, if still " +
+        "offered, re-run the command it renders with its fresh binding.",
+    nothing_to_enqueue: "No re-run was possible. Read `epic-implementer explain-run`; for a code defect use " +
+        "`dispatch-remediation --context-file`.",
+};
+function rerunCiCheckLine(check) {
+    const identity = [
+        check.name ?? "(unnamed check)",
+        check.workflow_identity ? `workflow ${check.workflow_identity}` : null,
+        check.run_id !== null ? `run ${check.run_id}` : null,
+    ]
+        .filter((part) => part !== null)
+        .join(", ");
+    const reason = check.reason ? ` — ${RERUN_CI_REASON_TEXT[check.reason] ?? check.reason}` : "";
+    const job = check.job_id !== null ? ` (job ${check.job_id})` : "";
+    return `    - ${identity}: ${RERUN_CI_STATUS_TEXT[check.status] ?? check.status}${reason}${job}`;
+}
+/**
+ * Exported for tests: render one `rerun-ci` outcome. Success goes to stdout and
+ * every failure to stderr (`--json` included). An unsupported server is NEVER a
+ * success and says it is "not available on this server".
+ */
+export function renderRerunCiOutcome(outcome, parsed, json) {
+    const label = `ticket ${parsed.ticketKey} (run ${parsed.epicRunId})`;
+    if (outcome.kind === "applied") {
+        const result = outcome.result;
+        if (result.committed && !result.event_recorded) {
+            console.error(`Warning: rerun-ci for ${label} COMMITTED, but its operator_verb_applied audit ` +
+                "event was not recorded. The action stands.");
+        }
+        if (json) {
+            console.log(JSON.stringify({
+                ok: true,
+                outcome: "applied",
+                request_id: outcome.requestId,
+                reference_reused: outcome.referenceReused,
+                result,
+            }));
+            return RERUN_CI_EXIT_OK;
+        }
+        const lines = [
+            `rerun-ci (guided) — ${label}`,
+            `  ticket:          ${result.ticket_key}`,
+            `  head:            ${result.head_sha ? "`" + result.head_sha + "`" : "unknown"}`,
+            `  outcome:         ${RERUN_CI_OUTCOME_TEXT[result.outcome] ?? result.outcome}`,
+            "  failed checks:",
+            ...result.checks.map(rerunCiCheckLine),
+            `  next action:     ${RERUN_CI_NEXT_ACTION[result.outcome] ?? "Read `epic-implementer explain-run`."}`,
+            `  request:         ${outcome.requestId}${outcome.referenceReused ? " (re-sent from the local reference)" : ""}`,
+            `  event recorded:  ${result.event_recorded}`,
+        ];
+        console.log(lines.join("\n"));
+        return RERUN_CI_EXIT_OK;
+    }
+    if (outcome.kind === "refused" || outcome.kind === "stale") {
+        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(`Refused: rerun-ci for ${label} — ${outcome.code}: ${outcome.message}. ` +
+                (outcome.kind === "stale"
+                    ? "Nothing was written. The run changed since this command was rendered; re-read the run explanation."
+                    : "Nothing was written."));
+        }
+        return RERUN_CI_EXIT_REFUSED;
+    }
+    if (outcome.kind === "unconfirmed") {
+        if (json) {
+            console.error(JSON.stringify({
+                ok: false,
+                outcome: "unconfirmed",
+                reason: outcome.reason,
+                message: outcome.message,
+                request_id: outcome.requestId,
+            }));
+        }
+        else {
+            console.error(`Unconfirmed: rerun-ci for ${label} — ${outcome.message}.`);
+        }
+        return RERUN_CI_EXIT_UNCONFIRMED;
+    }
+    if (json) {
+        console.error(JSON.stringify({ ok: false, outcome: outcome.kind, message: outcome.message }));
+    }
+    else {
+        console.error(`Failed: rerun-ci for ${label} — ${outcome.message}.`);
+    }
+    return RERUN_CI_EXIT_FAILED;
+}
+export async function runRerunCiCommand(argv) {
+    try {
+        const parsed = parseRerunCiArgs(argv);
+        if (parsed.help) {
+            console.log(RERUN_CI_USAGE);
+            return 0;
+        }
+        // Prove the token names THIS command, run, and ticket before credentials are
+        // resolved, so a mismatched binding reaches no one.
+        const binding = checkGuidedBinding(parsed.binding, "rerun-ci", {
+            epicRunId: parsed.epicRunId,
+            ticketKey: parsed.ticketKey,
+        });
+        const access = await resolveRecoveryAccess(parsed.json);
+        if (!access)
+            return RERUN_CI_EXIT_FAILED;
+        const { rerunCiRepair } = await import("./recovery-operations.js");
+        const outcome = await rerunCiRepair(access, {
+            epicRunId: parsed.epicRunId,
+            ticketKey: parsed.ticketKey,
+            binding,
+        });
+        return renderRerunCiOutcome(outcome, parsed, parsed.json);
+    }
+    catch (error) {
+        console.error(`Error: ${toConductorErrorEnvelope(error).message}`);
+        return RERUN_CI_EXIT_FAILED;
+    }
+}
 const MERGE_CHILD_USAGE = [
     "Usage: epic-implementer merge-child --epic-run-id <id> --pr <number> [--json]",
     "",
@@ -651,9 +1026,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 +1036,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 +1065,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 +1124,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 +1138,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 +1189,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 +1213,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 +1262,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 +1276,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 +1490,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 +1610,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;
+    }
+}