@bridge_gpt/mcp-server 0.2.53 → 0.2.55

package/build/conductor/readiness-sections.js

@@ -1,11 +1,11 @@
 /**
- * The shared conductor readiness SECTION layer (BAPI-1055).
+ * The shared epic-implementer readiness SECTION layer (BAPI-1055).
  *
  * Extracted verbatim from `conductor/install-doctor.ts`, where these builders
  * had already composed four of the five prerequisite loci. Nothing about a
  * section changed in the move: same ids, same labels, same statuses, same
  * detail text, same installer remediations. What changed is who may consume
- * them — the install-time doctor and the advisory `conductor readiness` gate now
+ * them — the install-time doctor and the advisory `epic-implementer readiness` gate now
  * read ONE adapter set instead of interpreting the same probes twice.
  *
  * ## Why extraction rather than a second aggregator
@@ -37,6 +37,7 @@ import { MANAGED_HOOK_NAMES } from "./git-hooks.js";
 import { MCP_PACKAGE_NAME } from "../mcp-identity.js";
 import { CLAUDE_REVIEW_WORKFLOW_DRIFT_REMEDIATION, summarizeClaudeReviewWorkflowDrift, } from "../claude-review-workflow-drift.js";
 import { describeNativeLedgerAvailability } from "./doctor.js";
+import { classifyDatabaseMigration, classifySingleTransitionAuthority, classifyWorkerPresent, } from "./bring-up-facts.js";
 /** Operator runbook pointer surfaced beside the executor gap. */
 export const CONDUCTOR_OPERATOR_RUNBOOK_POINTER = "docs/claude/epic-conductor-v2-operator-runbook.md";
 /**
@@ -65,7 +66,7 @@ export const CONDUCTOR_PROFILE_TOKEN_REMEDIATION = "re-run `install conductor` a
     "tools become visible after the MCP client is restarted.";
 /** Remediation surfaced whenever the managed conductor hooks are not usable. */
 export const CONDUCTOR_HOOK_TARGET_REMEDIATION = "re-run `install conductor` and accept the local-observability consent, or run " +
-    "`conductor install-git-hooks` directly.";
+    "`epic-implementer install-git-hooks` directly.";
 /** Remediation surfaced when the ledger's native binding does not load. */
 export const CONDUCTOR_LEDGER_LOADABILITY_REMEDIATION = "`better-sqlite3` is an optionalDependency npm silently skips on a build failure — " +
     "reinstall it for this Node runtime to restore local conductor observability.";
@@ -244,9 +245,57 @@ export function reconcilerSection(readiness) {
         detail: r.last_tick_at === null
             ? "no reconciler tick recorded for this repository"
             : `last tick ${r.last_tick_age_seconds}s ago (threshold ${readiness.thresholds.reconciler_stale_after_seconds}s)`,
-        remediation: "start the reconciler (`conductor epic-tick` schedule) for this repository.",
+        remediation: "start the reconciler (`epic-implementer epic-tick` schedule) for this repository.",
     };
 }
+// ---------------------------------------------------------------------------
+// Bring-up safety (BAPI-1153)
+// ---------------------------------------------------------------------------
+// Three deployment-wide facts, rendered as their own group. Each builder is a
+// thin projection of the ONE classification in `bring-up-facts.ts`, which the
+// advisory gate and the `setup-epic` refusal read too — so the doctor cannot
+// call a database current that setup-epic refuses as behind.
+//
+// Never `fatal`: the installer's fatal state refuses to WRITE, and none of these
+// is a reason not to install. They refuse at `setup-epic`, before a run exists.
+/** Section labels, in render order. Ids come from the shared classification. */
+export const BRING_UP_SECTION_LABELS = {
+    "database-migration-current": "Database migration",
+    "worker-present": "Worker present",
+    "single-transition-authority": "Single transition authority",
+};
+function bringUpSection(verdict) {
+    const base = { id: verdict.id, label: BRING_UP_SECTION_LABELS[verdict.id] };
+    if (verdict.state === "ok") {
+        return { ...base, status: "ok", detail: verdict.detail };
+    }
+    return {
+        ...base,
+        status: "degraded",
+        detail: verdict.detail,
+        ...(verdict.remediation ? { remediation: verdict.remediation } : {}),
+    };
+}
+/** Whether the shared database is at (or ahead of) the server's code heads. */
+export function databaseMigrationCurrentSection(readiness) {
+    return bringUpSection(classifyDatabaseMigration(readiness.bring_up ?? null));
+}
+/** Whether any reconciler (worker) heartbeat is fresh across the deployment. */
+export function workerPresentSection(readiness) {
+    return bringUpSection(classifyWorkerPresent(readiness.bring_up ?? null));
+}
+/** Whether exactly one reconciler holds transition authority. */
+export function singleTransitionAuthoritySection(readiness) {
+    return bringUpSection(classifySingleTransitionAuthority(readiness.bring_up ?? null));
+}
+/** The "Bring-up safety" group, in render order. */
+export function bringUpSafetySections(readiness) {
+    return [
+        databaseMigrationCurrentSection(readiness),
+        workerPresentSection(readiness),
+        singleTransitionAuthoritySection(readiness),
+    ];
+}
 export function workflowSection(presence, reviewPolicySource, driftDetail) {
     if (presence === "present") {
         return {
@@ -527,7 +576,7 @@ export function conductorHookTargetsSection(legacyConductor, conductorContext) {
         return {
             ...base,
             status: "degraded",
-            detail: "hook targets could not be derived (the conductor doctor was not collected)",
+            detail: "hook targets could not be derived (the epic-implementer doctor was not collected)",
             remediation: CONDUCTOR_HOOK_TARGET_REMEDIATION,
         };
     }
@@ -538,7 +587,7 @@ export function conductorHookTargetsSection(legacyConductor, conductorContext) {
         return {
             ...base,
             status: "degraded",
-            detail: "hook targets could not be derived (the conductor doctor reported no hook state)",
+            detail: "hook targets could not be derived (the epic-implementer doctor reported no hook state)",
             remediation: CONDUCTOR_HOOK_TARGET_REMEDIATION,
         };
     }
@@ -576,7 +625,7 @@ export function conductorHookTargetsSection(legacyConductor, conductorContext) {
  *
  * No parallel `better-sqlite3` check: the mapping from an inspection to
  * available/degraded lives in one place ({@link describeNativeLedgerAvailability}),
- * so this section and the conductor doctor can never disagree about whether the
+ * so this section and the epic-implementer doctor can never disagree about whether the
  * binding loads. A degraded result carries the module name, the ABI, and the
  * sanitized failure kind, because the common cause is npm silently skipping an
  * optionalDependency build and that is undiagnosable without the ABI.
@@ -590,7 +639,7 @@ export function conductorLedgerLoadabilitySection(legacyConductor) {
         return {
             ...base,
             status: "degraded",
-            detail: "ledger loadability could not be derived (the conductor doctor was not collected)",
+            detail: "ledger loadability could not be derived (the epic-implementer doctor was not collected)",
             remediation: CONDUCTOR_LEDGER_LOADABILITY_REMEDIATION,
         };
     }
@@ -599,7 +648,7 @@ export function conductorLedgerLoadabilitySection(legacyConductor) {
         return {
             ...base,
             status: "degraded",
-            detail: "ledger loadability could not be derived (the conductor doctor reported no native-ledger state)",
+            detail: "ledger loadability could not be derived (the epic-implementer doctor reported no native-ledger state)",
             remediation: CONDUCTOR_LEDGER_LOADABILITY_REMEDIATION,
         };
     }

package/build/conductor/readiness.js

@@ -1,9 +1,9 @@
 /**
- * The consolidated ADVISORY conductor readiness gate (BAPI-1055, AC-6/AC-7).
+ * The consolidated ADVISORY epic-implementer readiness gate (BAPI-1055, AC-6/AC-7).
  *
  * One report that answers "is this host and repository ready to conduct an
  * epic", assembled from the five loci that each answered part of it before:
- * `bridge doctor`'s install checklist, `conductor doctor`'s local inspections,
+ * `bridge doctor`'s install checklist, `epic-implementer doctor`'s local inspections,
  * `plane` preflight, the server `conductor-readiness` collector, and the
  * install-time doctor that already composed four of them. Every prerequisite
  * comes back as a canonical {@link ReadinessCheck}: a stable id, a
@@ -77,7 +77,7 @@
  * ## Schema versioning
  *
  * {@link CONDUCTOR_READINESS_GATE_SCHEMA_VERSION} is INDEPENDENT of the install
- * doctor's section vocabulary, the conductor doctor's report, the plane
+ * doctor's section vocabulary, the epic-implementer doctor's report, the plane
  * diagnostic shape, and the Python wire response. Each of those evolves for its
  * own reasons; binding this report's version to any of them would make an
  * unrelated additive change look like a breaking one here, or worse, hide a real
@@ -87,6 +87,8 @@ import { mapConductorDoctorReportToReadinessChecks, } from "./doctor.js";
 import { mapInstallStatusChecksToReadinessChecks, } from "../install-doctor.js";
 import { mapPlanePreflightToReadinessChecks, } from "../plane/preflight.js";
 import { runConductorInstallDoctor, } from "./install-doctor.js";
+import { BRING_UP_SECTION_LABELS } from "./readiness-sections.js";
+import { classifyBringUpFacts } from "./bring-up-facts.js";
 import { createReadinessCheck, createReadinessCheckSafely, summarizeReadinessChecks, validateReadinessChecks, } from "../readiness-check.js";
 /** This report's own schema version. See the module docstring. */
 export const CONDUCTOR_READINESS_GATE_SCHEMA_VERSION = 1;
@@ -108,10 +110,25 @@ export const SERVER_READINESS_DESCRIPTORS = [
     { id: "review-policy", label: "Review policy" },
     { id: "github-credentials", label: "GitHub App credentials" },
     { id: "github-actions-permission", label: "GitHub App actions permission" },
+    // BAPI-1153 — the "Bring-up safety" group: deployment-wide facts that decide
+    // whether a plane can drive a run at all, ahead of the repository-scoped
+    // reconciler/executor rows. Labels come from the shared section layer.
+    { id: "database-migration-current", label: BRING_UP_SECTION_LABELS["database-migration-current"] },
+    { id: "worker-present", label: BRING_UP_SECTION_LABELS["worker-present"] },
+    {
+        id: "single-transition-authority",
+        label: BRING_UP_SECTION_LABELS["single-transition-authority"],
+    },
     { id: "reconciler-liveness", label: "Reconciler tick liveness" },
     { id: "executor-readiness", label: "Executor server observation" },
     { id: "review-workflow", label: "Review workflow protocol" },
     { id: "conductor-ci-workflow", label: "Conductor CI migration guard" },
+    // BAPI-1102 — the two ONE-TIME unattended prerequisites plus the aggregate the
+    // third unattended refusal reads. Noun phrases, like every row above: these
+    // render as list items under a source heading, not as sentences.
+    { id: "unattended-consent", label: "Repository unattended consent" },
+    { id: "unattended-notify-default", label: "Verified notify webhook default" },
+    { id: "repository-workflow-readiness", label: "Repository workflow readiness" },
 ];
 /** Fixed, secret-free prose per failure kind. Never a status body or header. */
 const SERVER_FAILURE_COPY = {
@@ -144,7 +161,7 @@ const SERVER_REMEDIATIONS = {
     actionsProbeFailed: "re-run once credentials resolve; the permission could not be checked, which is not the same as confirmed-missing.",
     actionsMissing: "grant the GitHub App `actions: write`; without it the conductor's workflow rerun lane fails open on 403.",
     reconcilerUnreadable: "retry once the Bridge API is reachable; reconciler liveness is unknown here, not confirmed stale.",
-    reconcilerStale: "start the reconciler for this repository (the `conductor epic-tick` schedule) so ticks resume.",
+    reconcilerStale: "start the reconciler for this repository (the `epic-implementer epic-tick` schedule) so ticks resume.",
     executorUnreadable: "retry once the Bridge API is reachable; no executor readiness claim is ever made from local state.",
     executorNeverSeen: "provision and start an executor (`install conductor --executor-id <id>` or `executor install-service`); readiness comes only from a live server observation.",
     executorStale: "restart the executor service; it was observed once and has gone quiet past the server's staleness threshold.",
@@ -153,6 +170,11 @@ const SERVER_REMEDIATIONS = {
     ciWorkflowUnknown: "re-run; the default branch's conductor CI workflow could not be evaluated, which is not the same as the guard being absent.",
     ciWorkflowMissingGuard: "add the migration-guard job to the conductor CI workflow on the default branch so migrations are checked before a merge.",
     olderServer: "upgrade the Bridge API deploy so it reports this fact; its state is unknown here, not healthy.",
+    // BAPI-1102. Each names the ONE action that clears it, and none of them
+    // mentions a webhook URL, a destination, or any configuration value.
+    unattendedConsent: "set `unattended_epic_implementer_allowed` for this repository (docs/claude/account-settings-operator-runbook.md), or run setup with --attended.",
+    unattendedNotifyDefault: "supply a --policy-file declaring notify.webhook_url, or run setup with --attended; an unattended run must have a working escalation channel, and notify.local_sink is not one.",
+    repositoryWorkflowReadiness: "run `install-bridge conductor` so the review and conductor-CI workflows are confirmed on the default branch, or run setup with --attended.",
 };
 /**
  * Project the validated server readiness response into `server.*` checks.
@@ -257,10 +279,12 @@ export function mapServerReadinessToChecks(readiness, failure = "unreachable") {
             remediation: SERVER_REMEDIATIONS.githubCredentials,
         });
     outcomes.push(githubActionsOutcome(readiness));
+    outcomes.push(...bringUpOutcomes(readiness));
     outcomes.push(reconcilerOutcome(readiness));
     outcomes.push(executorOutcome(readiness));
     outcomes.push(reviewWorkflowOutcome(readiness));
     outcomes.push(ciWorkflowOutcome(readiness));
+    outcomes.push(...unattendedOutcomes(readiness));
     const byId = new Map(outcomes.map((outcome) => [outcome.id, outcome]));
     return SERVER_READINESS_DESCRIPTORS.map(({ id, label }) => {
         const outcome = byId.get(id);
@@ -286,6 +310,98 @@ export function mapServerReadinessToChecks(readiness, failure = "unreachable") {
         });
     });
 }
+/**
+ * The three BAPI-1153 bring-up safety rows.
+ *
+ * Read from the SAME classification the install doctor's sections and the
+ * `setup-epic` refusal read (`bring-up-facts.ts`), so the advisory gate cannot
+ * call a fact healthy that setup-epic refuses. Every non-`ok` verdict is `fail`:
+ * unreported and unreadable are never healthy, and the remediation already
+ * separates "retry — unknown" from "confirmed bad — do this".
+ */
+function bringUpOutcomes(readiness) {
+    return classifyBringUpFacts(readiness.bring_up ?? null).map((verdict) => verdict.state === "ok"
+        ? { id: verdict.id, status: "pass", detail: verdict.detail }
+        : {
+            id: verdict.id,
+            status: "fail",
+            detail: verdict.detail,
+            remediation: verdict.remediation ?? SERVER_REMEDIATIONS.olderServer,
+        });
+}
+/**
+ * The three BAPI-1102 unattended prerequisite rows.
+ *
+ * Returned as a group because they share one absence rule: a server older than
+ * BAPI-1102 reports no `unattended` block at all, and an unreported fact is a
+ * FAILURE with the older-server remediation — never a pass. "Could not be read"
+ * and "read and healthy" are the two answers this whole module refuses to
+ * conflate, and these are prerequisites for an UNATTENDED merge, which is the
+ * worst place to guess.
+ *
+ * Consent and workflow readiness are `warn`, not `fail`, when confirmed absent:
+ * a repository that never runs an unattended epic needs neither, so reporting
+ * them as failures would mark a perfectly healthy attended install broken. They
+ * become hard refusals only at `setup-epic`, and only for a run whose effective
+ * policy is actually unattended.
+ */
+function unattendedOutcomes(readiness) {
+    const u = readiness.unattended;
+    if (u === null) {
+        return [
+            "unattended-consent",
+            "unattended-notify-default",
+            "repository-workflow-readiness",
+        ].map((id) => ({
+            id,
+            status: "fail",
+            detail: "this server fact was not reported",
+            remediation: SERVER_REMEDIATIONS.olderServer,
+        }));
+    }
+    return [
+        u.conductor_allowed
+            ? {
+                id: "unattended-consent",
+                status: "pass",
+                detail: "this repository has consented to unattended conductor runs",
+            }
+            : {
+                id: "unattended-consent",
+                status: "warn",
+                detail: "unattended_epic_implementer_allowed is NOT set — an unattended run will be refused before it is created",
+                remediation: SERVER_REMEDIATIONS.unattendedConsent,
+            },
+        u.notify_webhook_default_declared
+            ? {
+                id: "unattended-notify-default",
+                status: "pass",
+                // Presence only. The URL is never reported by the server and is never
+                // rendered here.
+                detail: u.notify_webhook_default_verified === true
+                    ? "a notify webhook default is declared and verified"
+                    : "a notify webhook default is declared (verified at approval, not here)",
+            }
+            : {
+                id: "unattended-notify-default",
+                status: "warn",
+                detail: "no repository notify webhook default is declared — an unattended run needs an escalation channel, and no column supplies a repository default today, so the run must declare notify.webhook_url itself",
+                remediation: SERVER_REMEDIATIONS.unattendedNotifyDefault,
+            },
+        u.repository_readiness_confirmed
+            ? {
+                id: "repository-workflow-readiness",
+                status: "pass",
+                detail: "the review and conductor-CI workflows are both confirmed",
+            }
+            : {
+                id: "repository-workflow-readiness",
+                status: "warn",
+                detail: "the review and conductor-CI workflows are not both confirmed — an unattended auto-merging run will be refused",
+                remediation: SERVER_REMEDIATIONS.repositoryWorkflowReadiness,
+            },
+    ];
+}
 /** Review-policy presence and alignment, as one check with one fix each. */
 function reviewPolicyOutcome(readiness) {
     const s = readiness.supervisor;

package/build/conductor/recovery-cli.js

@@ -1,20 +1,27 @@
 /**
- * `conductor` operator recovery verbs (BAPI-872): `stop-run`, `abandon-run`,
- * `unpark`, `adopt-current-head-and-unpark`.
+ * `conductor` operator recovery and repair verbs — seven CLI-only commands.
+ *
+ * The four BAPI-872 recovery verbs: `stop-run`, `abandon-run`, `unpark`,
+ * `adopt-current-head-and-unpark`. The three BAPI-1154 run-addressed repair
+ * verbs: `scope-reparse`, `dispatch-remediation`, `merge-child`.
  *
  * CLI-only by design — this is an explicit ticket non-goal, not an oversight:
- * none of these four command names is ever registered as an MCP tool, tool
+ * none of these seven 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
- * hand-rolling an HTTP request — the exact thing setup-epic's old raw-PATCH
- * guidance used to ask for.
+ * hand-rolling an HTTP request, a DAL call, or a code edit.
  *
  * Every ticket command's `row_version` CAS handling is entirely internal to
  * `recovery-operations.ts`. This surface never accepts, echoes, or asks the
- * operator for a version counter — see {@link REJECTED_VERSION_FLAGS}.
+ * operator for a version counter — see {@link REJECTED_VERSION_FLAGS}. Every
+ * repair verb takes a mandatory `--epic-run-id`; the SERVER decides whether its
+ * target belongs to that run, and a foreign target is refused with nothing
+ * written on either side.
  */
+import { readFile } from "node:fs/promises";
 import { ConductorValidationError, toConductorErrorEnvelope } from "./errors.js";
+import { DRIVER_CONTEXT_MAX_BYTES } from "./repair-contract.js";
 // ---------------------------------------------------------------------------
 // Flag parsing
 // ---------------------------------------------------------------------------
@@ -63,6 +70,11 @@ function tokenizeRecoveryFlags(argv, valueFlags, boolFlags) {
         if (!valueFlags.has(name)) {
             throw new ConductorValidationError(`Unknown flag "${name}".`);
         }
+        if (values.has(name)) {
+            // A repeated flag is ambiguous — which value did the operator mean? Refused
+            // before the second value is read rather than silently keeping the last one.
+            throw new ConductorValidationError(`Flag "${name}" may be given only once.`);
+        }
         let value;
         if (eq >= 0) {
             value = token.slice(eq + 1);
@@ -137,7 +149,7 @@ async function resolveRecoveryAccess(json) {
 // stop-run
 // ---------------------------------------------------------------------------
 const STOP_RUN_USAGE = [
-    "Usage: conductor stop-run --epic-run-id <id> [--json]",
+    "Usage: epic-implementer stop-run --epic-run-id <id> [--json]",
     "",
     "Stop an epic run: block new dispatch and cancel its queued work. The run",
     "record is preserved (never deleted) so its history stays inspectable.",
@@ -187,7 +199,7 @@ export async function runStopRunCommand(argv) {
 // abandon-run
 // ---------------------------------------------------------------------------
 const ABANDON_RUN_USAGE = [
-    "Usage: conductor abandon-run --epic-run-id <id> [--json]",
+    "Usage: epic-implementer abandon-run --epic-run-id <id> [--json]",
     "",
     "Abandon an epic run — a TERMINAL, IRREVERSIBLE transition. An abandoned run",
     "can never resume or be reused; start a new run instead. Idempotent —",
@@ -232,14 +244,14 @@ export async function runAbandonRunCommand(argv) {
 // unpark / adopt-current-head-and-unpark (shared rendering)
 // ---------------------------------------------------------------------------
 const UNPARK_USAGE = [
-    "Usage: conductor unpark --epic-run-id <id> --ticket-key <key> [--json]",
+    "Usage: epic-implementer unpark --epic-run-id <id> --ticket-key <key> [--json]",
     "",
     "Move a parked (needs_human) ticket back into its gate machine, once the",
     "operator has resolved what parked it. Retries a bounded number of times on",
     "its own if the ticket changes concurrently — never accepts a version counter.",
 ].join("\n");
 const ADOPT_CURRENT_HEAD_USAGE = [
-    "Usage: conductor adopt-current-head-and-unpark --epic-run-id <id> --ticket-key <key> [--json]",
+    "Usage: epic-implementer adopt-current-head-and-unpark --epic-run-id <id> --ticket-key <key> [--json]",
     "",
     "Recover a ticket parked because a human/external push drifted the PR head",
     "off its anchored commit: adopt the CURRENT PR head and unpark in one step.",
@@ -311,3 +323,270 @@ export async function runAdoptCurrentHeadAndUnparkCommand(argv) {
         return 1;
     }
 }
+// ---------------------------------------------------------------------------
+// BAPI-1154 — repair verbs: scope-reparse, dispatch-remediation, merge-child
+// ---------------------------------------------------------------------------
+const SCOPE_REPARSE_VALUE_FLAGS = new Set(["--epic-run-id", "--scope-id"]);
+const DISPATCH_REMEDIATION_VALUE_FLAGS = new Set([
+    "--epic-run-id",
+    "--ticket-key",
+    "--context-file",
+]);
+const MERGE_CHILD_VALUE_FLAGS = new Set(["--epic-run-id", "--pr"]);
+function requireFlag(values, flag) {
+    const value = values.get(flag);
+    if (value === undefined || value.trim().length === 0) {
+        throw new ConductorValidationError(`Flag "${flag}" is required and must be non-empty.`);
+    }
+    return value.trim();
+}
+export function parseScopeReparseArgs(argv) {
+    const { values, bools } = tokenizeRecoveryFlags(argv, SCOPE_REPARSE_VALUE_FLAGS, RECOVERY_BOOL_FLAGS);
+    if (bools.has("--help")) {
+        return { epicRunId: "", scopeId: "", json: bools.has("--json"), help: true };
+    }
+    return {
+        epicRunId: requireFlag(values, "--epic-run-id"),
+        scopeId: requireFlag(values, "--scope-id"),
+        json: bools.has("--json"),
+        help: false,
+    };
+}
+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 {
+        epicRunId: requireFlag(values, "--epic-run-id"),
+        ticketKey: requireFlag(values, "--ticket-key"),
+        contextFile: requireFlag(values, "--context-file"),
+        json: bools.has("--json"),
+        help: false,
+    };
+}
+export function parseMergeChildArgs(argv) {
+    const { values, bools } = tokenizeRecoveryFlags(argv, MERGE_CHILD_VALUE_FLAGS, RECOVERY_BOOL_FLAGS);
+    if (bools.has("--help")) {
+        return { epicRunId: "", prNumber: 0, json: bools.has("--json"), help: true };
+    }
+    const epicRunId = requireFlag(values, "--epic-run-id");
+    const rawPr = requireFlag(values, "--pr");
+    const prNumber = /^[1-9][0-9]*$/.test(rawPr) ? Number(rawPr) : NaN;
+    if (!Number.isSafeInteger(prNumber)) {
+        throw new ConductorValidationError('Flag "--pr" must be a positive integer pull-request number.');
+    }
+    return { epicRunId, prNumber, json: bools.has("--json"), help: false };
+}
+/**
+ * Validate and decode a driver-context file's BYTES.
+ *
+ * Checked in the order that keeps a rejected file from being decoded, resolved
+ * against credentials, or transmitted: the byte length first (against the SAME
+ * `DRIVER_CONTEXT_MAX_BYTES` the server enforces), then a FATAL UTF-8 decode, then
+ * non-whitespace content. Every error names the constraint and never echoes the
+ * file's content. Over-cap context is rejected, never truncated.
+ */
+export function decodeDriverContextFile(bytes) {
+    if (bytes.byteLength > DRIVER_CONTEXT_MAX_BYTES) {
+        throw new ConductorValidationError(`--context-file is ${bytes.byteLength} bytes, over DRIVER_CONTEXT_MAX_BYTES ` +
+            `(${DRIVER_CONTEXT_MAX_BYTES} UTF-8 bytes). Shorten it and retry; nothing was sent.`);
+    }
+    let text;
+    try {
+        text = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+    }
+    catch {
+        throw new ConductorValidationError("--context-file must be valid UTF-8 text; nothing was sent.");
+    }
+    if (text.trim().length === 0) {
+        throw new ConductorValidationError("--context-file is empty or whitespace-only; driver context must say something. " +
+            "Nothing was sent.");
+    }
+    return text;
+}
+/**
+ * Render a repair outcome. Human mode prints the verb and run first, the target
+ * second, ONE labeled `Before → After` pair third, then `committed` and `event
+ * recorded` — a replay is a successful no-op (`committed: false`), never a
+ * refusal. `--json` prints the server's bounded result object exactly, or a
+ * bounded `{ok:false, kind, code, message}` failure. Nothing here can print a
+ * prompt, driver context, row version, action key, head SHA, or credential: the
+ * results carry none of them.
+ */
+function renderRepairResult(outcome, input, json, extraLines = () => []) {
+    if (outcome.ok && outcome.result.committed && !outcome.result.event_recorded) {
+        // The ONE warning, and only for a committed action. A replay records nothing
+        // by design, so it never warns.
+        console.error(`Warning: ${input.verb} on run ${input.epicRunId} (${input.targetLabel}) COMMITTED, ` +
+            "but its operator_verb_applied audit event was not recorded. The action stands " +
+            "and is not rolled back. You ran it, so you own reconciling the missing audit " +
+            "record (the server also reported it to Sentry).");
+    }
+    if (json) {
+        if (outcome.ok) {
+            console.log(JSON.stringify(outcome.result));
+            return 0;
+        }
+        console.log(JSON.stringify(outcome.kind === "refused"
+            ? { ok: false, kind: "refused", code: outcome.code, message: outcome.message }
+            : { ok: false, kind: "unavailable", message: outcome.message }));
+        return 1;
+    }
+    if (!outcome.ok) {
+        if (outcome.kind === "refused") {
+            console.error(`Error: ${input.verb} refused on run ${input.epicRunId} (${input.targetLabel}) — ` +
+                `${outcome.code}: ${outcome.message}`);
+        }
+        else {
+            console.error(`Error: ${input.verb} could not complete on run ${input.epicRunId} ` +
+                `(${input.targetLabel}) — ${outcome.message}.`);
+        }
+        return 1;
+    }
+    const result = outcome.result;
+    const lines = [
+        `${input.verb} — run ${input.epicRunId}`,
+        `  target:          ${input.targetLabel}`,
+        `  ${input.stateLabel}: ${result.before ?? "none"} → ${result.after ?? "none"}`,
+        ...extraLines(result),
+        `  committed:       ${result.committed}${result.committed ? "" : " (already in this state; no change made)"}`,
+        `  event recorded:  ${result.event_recorded}`,
+    ];
+    console.log(lines.join("\n"));
+    return 0;
+}
+const SCOPE_REPARSE_USAGE = [
+    "Usage: epic-implementer scope-reparse --epic-run-id <id> --scope-id <scope> [--json]",
+    "",
+    "Re-drive the run's OWN index scope through the retry-reparse lifecycle and",
+    "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.",
+].join("\n");
+export async function runScopeReparseCommand(argv) {
+    try {
+        const parsed = parseScopeReparseArgs(argv);
+        if (parsed.help) {
+            console.log(SCOPE_REPARSE_USAGE);
+            return 0;
+        }
+        const access = await resolveRecoveryAccess(parsed.json);
+        if (!access)
+            return 1;
+        const { scopeReparseRepair } = await import("./recovery-operations.js");
+        const outcome = await scopeReparseRepair(access, {
+            epicRunId: parsed.epicRunId,
+            scopeId: parsed.scopeId,
+        });
+        return renderRepairResult(outcome, {
+            verb: "scope-reparse",
+            epicRunId: parsed.epicRunId,
+            targetLabel: `scope ${parsed.scopeId}`,
+            stateLabel: "scope lifecycle",
+        }, parsed.json, (result) => [
+            `  outcome:         ${result.outcome}${result.parse_scheduled ? " (parse scheduled)" : ""}`,
+        ]);
+    }
+    catch (error) {
+        console.error(`Error: ${toConductorErrorEnvelope(error).message}`);
+        return 1;
+    }
+}
+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),",
+    "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",
+    "through the reconciler's own strict-serial lane, remediation budget, and",
+    "dedup key. A parked ticket is resumed in the same step.",
+    "",
+    `--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.",
+].join("\n");
+export async function runDispatchRemediationCommand(argv, deps = {}) {
+    try {
+        const parsed = parseDispatchRemediationArgs(argv);
+        if (parsed.help) {
+            console.log(DISPATCH_REMEDIATION_USAGE);
+            return 0;
+        }
+        // Read and validate the context BEFORE credentials are resolved or the HTTP
+        // graph is loaded, so an invalid file costs nothing and reaches no one.
+        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.");
+        }
+        const context = decodeDriverContextFile(bytes);
+        const access = await resolveRecoveryAccess(parsed.json);
+        if (!access)
+            return 1;
+        const { dispatchRemediationRepair } = await import("./recovery-operations.js");
+        const outcome = await dispatchRemediationRepair(access, {
+            epicRunId: parsed.epicRunId,
+            ticketKey: parsed.ticketKey,
+            context,
+        });
+        return renderRepairResult(outcome, {
+            verb: "dispatch-remediation",
+            epicRunId: parsed.epicRunId,
+            targetLabel: `ticket ${parsed.ticketKey}`,
+            stateLabel: "code_review gate",
+        }, parsed.json, (result) => [
+            `  job:             ${result.job_type || "unknown"}${result.job_id !== null ? ` (job ${result.job_id})` : ""}`,
+        ]);
+    }
+    catch (error) {
+        console.error(`Error: ${toConductorErrorEnvelope(error).message}`);
+        return 1;
+    }
+}
+const MERGE_CHILD_USAGE = [
+    "Usage: epic-implementer merge-child --epic-run-id <id> --pr <number> [--json]",
+    "",
+    "Merge the run's child pull request through the shared merge service. You give",
+    "ONLY the PR number: the server finds the one ticket in the run bound to it",
+    "(or refuses, TICKET_NOT_IN_RUN, with nothing written) and composes the head",
+    "commit and gate identity itself. Every merge guard applies, and a merge",
+    "advances the run's scope on the same path as the MCP merge tool. A PR that is",
+    "already merged is a successful no-op.",
+    "",
+    "When the repository merges locally (the default), your own `gh` performs the",
+    "merge — run this from inside the repository's checkout, with `gh auth status`",
+    "passing.",
+].join("\n");
+export async function runMergeChildCommand(argv) {
+    try {
+        const parsed = parseMergeChildArgs(argv);
+        if (parsed.help) {
+            console.log(MERGE_CHILD_USAGE);
+            return 0;
+        }
+        const access = await resolveRecoveryAccess(parsed.json);
+        if (!access)
+            return 1;
+        const { mergeChildRepair } = await import("./recovery-operations.js");
+        const outcome = await mergeChildRepair(access, {
+            epicRunId: parsed.epicRunId,
+            prNumber: parsed.prNumber,
+        });
+        return renderRepairResult(outcome, {
+            verb: "merge-child",
+            epicRunId: parsed.epicRunId,
+            targetLabel: `PR #${parsed.prNumber}`,
+            stateLabel: "merge",
+        }, parsed.json, (result) => [
+            ...(result.ticket_key ? [`  ticket:          ${result.ticket_key}`] : []),
+            ...(result.reason ? [`  reason:          ${result.reason}`] : []),
+        ]);
+    }
+    catch (error) {
+        console.error(`Error: ${toConductorErrorEnvelope(error).message}`);
+        return 1;
+    }
+}