@bridge_gpt/mcp-server 0.2.53 → 0.2.55

package/build/conductor/epic-implementer-cli.js

@@ -0,0 +1,1298 @@
+/**
+ * Local-only epic-implementer CLI.
+ *
+ * Provides a dependency-light command skeleton for fast git/agent hooks and
+ * operator diagnostics that must NOT depend on the Bridge API backend:
+ *
+ *   epic-implementer emit-event --type <t> --source <s> [...]
+ *   epic-implementer doctor [--json]
+ *   epic-implementer purge  [--json]
+ *
+ * Every command talks only to the local SQLite ledger. Errors are surfaced as
+ * sanitized messages (no stack traces, no secrets, no raw payloads) and
+ * {@link runEpicImplementerCli} returns a process exit code rather than calling
+ * `process.exit` itself (the bin wrapper owns that).
+ *
+ * S4 (BAPI-1080) seam: this file is the renamed public entry point
+ * (`conductor/cli.ts` -> `conductor/epic-implementer-cli.ts`,
+ * `runConductorCli` -> `runEpicImplementerCli`). The enclosing `conductor/`
+ * directory, its ledger schema, event kinds, and MCP profile group remain
+ * unchanged until S5.
+ */
+import { readFileSync, unlinkSync } from "node:fs";
+import { ConductorValidationError, ConductorEpicTickV1FrozenError, toConductorErrorEnvelope, } from "./errors.js";
+import { emitConductorEvent, purgeConductorLedger, sendWorkerMessage, checkWorkerMessages, } from "./store.js";
+import { isDuplicateConstraintError } from "./producer-ledger.js";
+import { SEMANTIC_EVENT_TYPES } from "./taxonomy.js";
+import { DRIVER_CONTEXT_MAX_BYTES } from "./repair-contract.js";
+import { installConductorGitHooks, resolveConductorHookBin } from "./git-hooks.js";
+import { runFileScopeGuardCli } from "./file-scope-guard.js";
+import { runPostCommitHookProducer, runReferenceTransactionHookProducer } from "./git-producer.js";
+import { buildConductorDoctorReport, formatConductorDoctorReport } from "./doctor.js";
+import { resolveSupervisorConfig } from "./supervisor-config.js";
+// `runSupervisor` is imported LAZILY inside runSuperviseCommand: it transitively
+// pulls in the SQLite store, and a static import here would force every
+// epic-implementer CLI invocation (and every test that mocks ./store.js for the
+// other commands) to resolve the full supervisor/store graph eagerly.
+/**
+ * Human-readable error line for a sanitized conductor error envelope. For the
+ * BAPI-526 LEDGER_NATIVE_MODULE_LOAD_FAILED envelope ONLY, append a compact,
+ * allowlisted `details:` suffix (module / node_version / node_modules_abi) so a
+ * CLI operator can see the ABI skew. Never prints arbitrary detail keys, paths,
+ * stacks, argv, or raw caught messages.
+ */
+export function formatConductorErrorLine(envelope) {
+    if (envelope.error === "LEDGER_NATIVE_MODULE_LOAD_FAILED" && envelope.details) {
+        const d = envelope.details;
+        return (`${envelope.message} ` +
+            `details: module=${d.module} node_version=${d.node_version} node_modules_abi=${d.node_modules_abi}`);
+    }
+    return envelope.message;
+}
+/** Human-readable usage text for the epic-implementer CLI. */
+export function getConductorUsage() {
+    return [
+        "Usage: epic-implementer <command> [options]",
+        "",
+        "Local append-only event ledger for multi-agent coordination.",
+        "Talks ONLY to the local SQLite store (~/.config/bridge/events.db); no Bridge API calls.",
+        "",
+        "Commands:",
+        "  emit-event           Append one semantic event to the ledger",
+        "  supervise --run-id <id>  Run the foreground, run-scoped supervisor loop",
+        "  epic-tick            Run one stateless reconciliation pass for an Epic",
+        "  epic-status          Print read-only health summary of an Epic Run",
+        "  send-message         Enqueue ONE typed supervisor->worker relay message (idempotent)",
+        "  check-messages       Read + ACK pending relay messages for a worker (no redelivery)",
+        "  doctor               Read-only health/diagnostics report (ledger + git hooks)",
+        "  readiness            Read-only ADVISORY report of every conductor prerequisite",
+        "                       (install + epic-implementer doctor + plane preflight + server),",
+        "                       each with pass/warn/fail/skip and one named remediation.",
+        "                       Remediations are NOT run automatically; always exits 0.",
+        "  purge                Delete ALL ledger rows (events, messages, supervisor_projection)",
+        "  install-git-hooks    Install local, opportunistic, non-blocking git hooks",
+        "  git-hook post-commit Run the post-commit producer (invoked by the installed hook)",
+        "  git-hook reference-transaction --phase <p> --stdin-file <f>",
+        "                       Run the reference-transaction producer (invoked by the hook)",
+        "  file-scope-guard     Warn-only: compare the branch diff against the declared",
+        "                       touched-file set (always exits 0; never blocks a PR)",
+        "  stop-run             Stop an epic run: block dispatch and cancel queued work",
+        "                       (the run record is preserved). Idempotent.",
+        "  abandon-run          Abandon an epic run — TERMINAL and IRREVERSIBLE.",
+        "                       Idempotent on an already-abandoned run.",
+        "  unpark               Move a parked (needs_human) ticket back into its gate",
+        "                       machine. Retries internally on a concurrent change.",
+        "  adopt-current-head-and-unpark",
+        "                       Recover a ticket parked by a PR-head drift: adopt the",
+        "                       CURRENT PR head and unpark in one step.",
+        "  scope-reparse --epic-run-id <id> --scope-id <scope>",
+        "                       Re-drive the run's OWN index scope through retry-reparse",
+        "                       and schedule its parse. Refused if the scope is not the run's.",
+        "  dispatch-remediation --epic-run-id <id> --ticket-key <key> --context-file <path>",
+        `                       Dispatch a remediation job carrying driver context (UTF-8,`,
+        `                       at most DRIVER_CONTEXT_MAX_BYTES = ${DRIVER_CONTEXT_MAX_BYTES} bytes; never truncated).`,
+        "  merge-child --epic-run-id <id> --pr <number>",
+        "                       Merge the run's PR-bound child through the shared merge",
+        "                       service; the server composes the head and gate identity.",
+        "",
+        "supervise options:",
+        "  --run-id <id>             Run/session identifier to supervise (required)",
+        "  --wake-interval-ms <n>    Deterministic event-poll cadence (clamped 30000..60000)",
+        "  --global-timeout-ms <n>   Total wall-clock ceiling for the run",
+        "  --escalation-cooldown-ms <n>  Min gap between escalations for the same worker+reason",
+        "",
+        "install-git-hooks notes:",
+        "  Hooks are LOCAL, unversioned, opportunistic, and bypassable. Missing hooks are a",
+        "  degraded optional capability and never prevent PR/CI gate evaluation.",
+        "",
+        "emit-event options:",
+        "  --type <t>           Semantic event type (required). One of:",
+        `                       ${SEMANTIC_EVENT_TYPES.join(", ")}`,
+        "  --source <s>         Logical producer (required)",
+        "  --subject <s>        Subject the event is about (e.g. ticket key)",
+        "  --run-id <s>         Run/session identifier",
+        "  --worker-id <s>      Worker/agent identifier",
+        "  --producer <s>       Finer-grained producer identity",
+        "  --schema-version <n> Event schema version (default 1)",
+        "  --time <iso>         ISO-8601 event time (default now)",
+        "  --confidence <0..1>  Confidence score",
+        "  --observed-via <s>   Channel the event was observed through",
+        "  --data-json <json>   Normalized data object (allowlisted top-level keys)",
+        "  --data-json-stdin    Read the complete normalized data object as JSON from stdin",
+        "                       (mutually exclusive with --data-json; keeps raw payloads and",
+        "                       secrets out of the process argument list)",
+        "  --raw-json <json>    Tool-native object; nested under data.raw",
+        "  --payload-ref <ref>  Reference for large external payloads (-> data.payload_ref)",
+        "  --json               Print compact JSON result",
+        "",
+        "send-message options:",
+        "  --run-id <s>             Run/session identifier (required)",
+        "  --worker-id <s>          Target worker identifier (required)",
+        "  --type <s>               Typed message kind, e.g. supervisor.worker_stalled (required)",
+        "  --cause-seq <n>          Idempotency cause sequence, non-negative integer (required)",
+        "  --payload-json <json>    Compact payload object (allowlisted top-level keys)",
+        "  --payload-json-stdin     Read the payload object as JSON from stdin",
+        "                           (mutually exclusive with --payload-json)",
+        "  --available-at <iso>     ISO-8601 time the message becomes available (default now)",
+        "  --cooldown-ms <n>        Per-call cooldown override in ms",
+        "  --json                   Print compact JSON result",
+        "  Note: a duplicate idempotency key or a same-type message inside the cooldown",
+        "  window does NOT enqueue a second message.",
+        "",
+        "check-messages options:",
+        "  --run-id <s>             Run/session identifier (required)",
+        "  --worker-id <s>          Worker identifier (required)",
+        "  --limit <n>              Max messages to deliver/ack (default 10, max 100)",
+        "  --json                   Print compact JSON result",
+        "  Note: returned messages are ACKNOWLEDGED by this call and are not redelivered.",
+        "",
+        "readiness options:",
+        "  --json               Print the versioned structured report as JSON",
+        "  --no-deny-probe      Accepted for parity with `doctor`; inert here — `readiness`",
+        "                       never spawns the deny-enforcement probe, and reports that",
+        "                       check as an explicit skip naming `epic-implementer doctor`",
+        "  --help               Print the readiness usage message",
+        "  Note: advisory only. It blocks nothing and changes no exit code; `drive-epic`",
+        "  remains the sole route-selection gate and server-side admission the sole refusal.",
+        "",
+        "doctor / purge options:",
+        "  --json               Print machine-readable JSON",
+        "  --no-deny-probe      (doctor only) Skip the deny-enforcement preflight — no headless",
+        "                       agent is spawned; the deny_enforcement section reports an",
+        "                       explicit skipped state (enforcement UNVERIFIED, never enforced)",
+        "",
+        "Examples:",
+        "  epic-implementer emit-event --type run.started --source git-hook --run-id BAPI-393 \\",
+        "      --data-json '{\"summary\":\"run started\"}'",
+        "  epic-implementer emit-event --type git.commit_created --source git-hook \\",
+        "      --raw-json '{\"branch\":\"feature/x\",\"sha\":\"abc123\"}'",
+        "  epic-implementer emit-event --type ci.failed --source ci \\",
+        "      --payload-ref 'file:///tmp/ci-log.txt'",
+        "  epic-implementer emit-event --type merge.succeeded --source conductor-merge \\",
+        "      --worker-id w1 --data-json '{\"summary\":\"auto-merged\",\"status\":\"succeeded\"}'",
+        "  epic-implementer doctor --json",
+        "  epic-implementer purge",
+        "",
+        "epic-tick options:",
+        "  --epic-key <KEY>          Epic key to supervise (required, non-empty)",
+        "  --scheduled-at <epoch>    Epoch-seconds timestamp when this tick was scheduled (optional)",
+        "  --lease-ttl-seconds <n>   Lease TTL in seconds (optional, default 120)",
+        "",
+        "approve-plan options:",
+        "  approve-plan <epic_key> --plan-version N [--json]",
+        "  <epic_key>                Epic key (e.g. EPIC-405) (required positional)",
+        "  --plan-version <n>        Strictly positive plan version to approve (required)",
+        "  --json                    Print compact JSON result",
+        "  --help                    Print this usage message",
+        "",
+        "epic-status options:",
+        "  --epic-key <KEY>          Epic key to fetch the snapshot for (required)",
+        "  --json                    Print compact JSON result",
+        "  --help                    Print this usage message",
+        "",
+        "Examples:",
+        "  epic-implementer approve-plan EPIC-405 --plan-version 2",
+        "  epic-implementer approve-plan EPIC-405 --plan-version 2 --json",
+        "  epic-implementer epic-status --epic-key EPIC-405",
+        "  epic-implementer epic-status --epic-key EPIC-405 --json",
+        "",
+        "stop-run / abandon-run options:",
+        "  --epic-run-id <id>        Epic run identifier (required)",
+        "  --json                    Print compact JSON result",
+        "  --help                    Print this usage message",
+        "  stop-run BLOCKS new dispatch and CANCELS queued work; the run record is",
+        "  preserved and the run cannot resume on its own — it is an emergency brake,",
+        "  not a pause. abandon-run is the SAME plus a TERMINAL, IRREVERSIBLE close-out:",
+        "  once abandoned, the run can never resume or be reused. Both are idempotent —",
+        "  repeating either is a safe no-op once the run is already stopped/abandoned.",
+        "",
+        "unpark / adopt-current-head-and-unpark options:",
+        "  --epic-run-id <id>        Epic run identifier (required)",
+        "  --ticket-key <key>        Ticket key (required)",
+        "  --json                    Print compact JSON result",
+        "  --help                    Print this usage message",
+        "  unpark resumes a ticket PARKED with needs_human, once the underlying cause",
+        "  is resolved. adopt-current-head-and-unpark additionally REBINDS the ticket's",
+        "  anchored PR head to whatever the PR's head currently is, for a ticket parked",
+        "  by a human/external push. Both retry internally on a concurrent row change —",
+        "  neither accepts, nor ever asks for, a version counter.",
+        "",
+        "Incident examples:",
+        "  # A run is misbehaving and must stop immediately:",
+        "  epic-implementer stop-run --epic-run-id 3f9c2b7e-...",
+        "  # The run is done for good — close it out:",
+        "  epic-implementer abandon-run --epic-run-id 3f9c2b7e-...",
+        "  # A ticket parked itself (needs_human) and the cause is now fixed:",
+        "  epic-implementer unpark --epic-run-id 3f9c2b7e-... --ticket-key BAPI-852",
+        "  # A human pushed directly to the PR and the ticket parked on head drift:",
+        "  epic-implementer adopt-current-head-and-unpark --epic-run-id 3f9c2b7e-... --ticket-key BAPI-852",
+    ].join("\n");
+}
+/**
+ * Private diagnostic action (BAPI-772): prints the `epic-implementer-bin.js`
+ * path the EXECUTING artifact resolves for hook installation. It exists so a
+ * test can run `node build/epic-implementer-bin.js __hook-bin` against the
+ * real esbuild bundle and assert the printed path exists — a tsc-emit unit
+ * test structurally cannot catch the bundled-layout bug this ticket fixes.
+ * Mirrors `plane __entrypoint`. S4 (BAPI-1080): the retained `conductor-bin.js`
+ * output name is now a fixed migration stub and must never be selected here.
+ */
+export const CONDUCTOR_HOOK_BIN_ACTION = "__hook-bin";
+const VALID_COMMANDS = new Set([
+    "emit-event",
+    "supervise",
+    "epic-tick",
+    "approve-plan",
+    "epic-status",
+    "send-message",
+    "check-messages",
+    "doctor",
+    // BAPI-1055: the consolidated ADVISORY readiness gate. Read-only, always
+    // exits 0, and registers no MCP tool — see `readiness-cli.ts`.
+    "readiness",
+    "purge",
+    "install-git-hooks",
+    "git-hook",
+    "file-scope-guard",
+    // BAPI-872: CLI-only operator recovery verbs — never registered as MCP tools.
+    "stop-run",
+    "abandon-run",
+    "unpark",
+    "adopt-current-head-and-unpark",
+    // BAPI-1154: CLI-only run-addressed repair verbs — never registered as MCP tools.
+    "scope-reparse",
+    "dispatch-remediation",
+    "merge-child",
+    // Private, and deliberately ABSENT from the usage text: `__hook-bin` exists as
+    // the bundled-artifact regression guard for BAPI-772 (mirroring `plane
+    // __entrypoint`), not as a supported operator workflow.
+    CONDUCTOR_HOOK_BIN_ACTION,
+]);
+/**
+ * Parse the top-level conductor argv into a subcommand (without a CLI
+ * framework). `-h`/`--help` and no-args yield help; an unknown first token is a
+ * sanitized error.
+ */
+export function parseConductorArgs(argv) {
+    if (argv.length === 0)
+        return { kind: "help" };
+    const first = argv[0];
+    if (first === "-h" || first === "--help")
+        return { kind: "help" };
+    if (first.startsWith("-")) {
+        return { kind: "error", message: `Unknown option "${first}". Run "epic-implementer --help" for usage.` };
+    }
+    if (!VALID_COMMANDS.has(first)) {
+        return { kind: "error", message: `Unknown command "${first}". Run "epic-implementer --help" for usage.` };
+    }
+    return { kind: "command", command: first, argv: argv.slice(1) };
+}
+/**
+ * Tokenize `--flag value` / `--flag=value` / boolean flags. Unknown flags and
+ * stray positionals raise a {@link ConductorValidationError} with actionable text.
+ */
+function tokenizeFlags(argv, valueFlags, boolFlags) {
+    const values = new Map();
+    const bools = new Set();
+    for (let i = 0; i < argv.length; i += 1) {
+        const token = argv[i];
+        if (token === "-h") {
+            bools.add("--help");
+            continue;
+        }
+        if (!token.startsWith("--")) {
+            throw new ConductorValidationError(`Unexpected argument "${token}".`);
+        }
+        const eq = token.indexOf("=");
+        const name = eq >= 0 ? token.slice(0, eq) : token;
+        if (boolFlags.has(name)) {
+            bools.add(name);
+            continue;
+        }
+        if (!valueFlags.has(name)) {
+            throw new ConductorValidationError(`Unknown flag "${name}".`);
+        }
+        let value;
+        if (eq >= 0) {
+            value = token.slice(eq + 1);
+        }
+        else {
+            const next = argv[i + 1];
+            if (next === undefined) {
+                throw new ConductorValidationError(`Flag "${name}" requires a value.`);
+            }
+            value = next;
+            i += 1;
+        }
+        values.set(name, value);
+    }
+    return { values, bools };
+}
+const EMIT_VALUE_FLAGS = new Set([
+    "--type",
+    "--source",
+    "--id",
+    "--subject",
+    "--run-id",
+    "--worker-id",
+    "--producer",
+    "--schema-version",
+    "--time",
+    "--confidence",
+    "--observed-via",
+    "--data-json",
+    "--raw-json",
+    "--payload-ref",
+]);
+const EMIT_BOOL_FLAGS = new Set(["--json", "--help", "--data-json-stdin"]);
+function defaultReadStdin() {
+    return readFileSync(0, "utf-8");
+}
+function parseJsonFlag(raw, flag) {
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        throw new ConductorValidationError(`Flag "${flag}" must be valid JSON.`);
+    }
+}
+function isPlainObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+/**
+ * Parse `emit-event` flags into a {@link ConductorEventInput}. `--raw-json` is
+ * wrapped under `data.raw` (preserving the normalization boundary for hook
+ * producers) and `--payload-ref` is merged into `data.payload_ref`.
+ *
+ * The normalized `data` object can be supplied either inline via `--data-json`
+ * or, for callers (such as the Claude hook writer) that must keep raw payloads
+ * and secrets out of the process argument list, through stdin via the boolean
+ * `--data-json-stdin` flag. The two are mutually exclusive. `deps.readStdin`
+ * defaults to a blocking read of fd 0 and is only invoked when
+ * `--data-json-stdin` is present, so the synchronous contract is preserved.
+ */
+export function parseEmitEventArgs(argv, deps = {}) {
+    const { values, bools } = tokenizeFlags(argv, EMIT_VALUE_FLAGS, EMIT_BOOL_FLAGS);
+    if (bools.has("--help")) {
+        return { input: { source: "", type: "run.started" }, json: bools.has("--json"), help: true };
+    }
+    const type = values.get("--type");
+    const source = values.get("--source");
+    if (!type)
+        throw new ConductorValidationError('Flag "--type" is required for emit-event.');
+    if (!source)
+        throw new ConductorValidationError('Flag "--source" is required for emit-event.');
+    // Build the data object: start from --data-json OR --data-json-stdin (never
+    // both), then layer raw + payload-ref.
+    let data = {};
+    const dataJsonRaw = values.get("--data-json");
+    const dataJsonStdin = bools.has("--data-json-stdin");
+    // Reject the ambiguous combination BEFORE reading stdin so a misconfigured
+    // caller never blocks on an fd-0 read it did not intend.
+    if (dataJsonRaw !== undefined && dataJsonStdin) {
+        throw new ConductorValidationError('Flags "--data-json" and "--data-json-stdin" are mutually exclusive; pass the normalized data object exactly one way.');
+    }
+    if (dataJsonStdin) {
+        const readStdin = deps.readStdin ?? defaultReadStdin;
+        const stdinRaw = readStdin();
+        // Reuse the same JSON parse + object-validation path as --data-json. The
+        // flag name in any error is the flag itself, never the (possibly secret)
+        // stdin content.
+        const parsed = parseJsonFlag(stdinRaw, "--data-json-stdin");
+        if (!isPlainObject(parsed)) {
+            throw new ConductorValidationError('Flag "--data-json-stdin" must be a JSON object.');
+        }
+        data = { ...parsed };
+    }
+    else if (dataJsonRaw !== undefined) {
+        const parsed = parseJsonFlag(dataJsonRaw, "--data-json");
+        if (!isPlainObject(parsed)) {
+            throw new ConductorValidationError('Flag "--data-json" must be a JSON object.');
+        }
+        data = { ...parsed };
+    }
+    const rawJsonRaw = values.get("--raw-json");
+    if (rawJsonRaw !== undefined) {
+        const parsedRaw = parseJsonFlag(rawJsonRaw, "--raw-json");
+        if (!isPlainObject(parsedRaw)) {
+            throw new ConductorValidationError('Flag "--raw-json" must be a JSON object.');
+        }
+        // Merge with any raw already present in --data-json so neither is dropped.
+        const existingRaw = isPlainObject(data.raw) ? data.raw : {};
+        data.raw = { ...existingRaw, ...parsedRaw };
+    }
+    const payloadRef = values.get("--payload-ref");
+    if (payloadRef !== undefined) {
+        data.payload_ref = payloadRef;
+    }
+    const schemaVersionRaw = values.get("--schema-version");
+    const confidenceRaw = values.get("--confidence");
+    const input = {
+        source,
+        type: type,
+        // Optional caller-supplied deterministic id (BAPI-527): forwarded to the store
+        // so a duplicate collides on the `events.id` UNIQUE constraint, giving the
+        // worker gate path server-side dedup without an in-process ledger poll.
+        id: values.get("--id"),
+        subject: values.get("--subject"),
+        run_id: values.get("--run-id"),
+        worker_id: values.get("--worker-id"),
+        producer: values.get("--producer"),
+        time: values.get("--time"),
+        observed_via: values.get("--observed-via"),
+        data,
+    };
+    if (schemaVersionRaw !== undefined) {
+        const n = Number.parseInt(schemaVersionRaw, 10);
+        if (!Number.isFinite(n))
+            throw new ConductorValidationError('Flag "--schema-version" must be an integer.');
+        input.schema_version = n;
+    }
+    if (confidenceRaw !== undefined) {
+        const n = Number.parseFloat(confidenceRaw);
+        if (!Number.isFinite(n))
+            throw new ConductorValidationError('Flag "--confidence" must be a number.');
+        input.confidence = n;
+    }
+    return { input, json: bools.has("--json"), help: false };
+}
+/** Run the `emit-event` command. Prints the inserted event summary. */
+export async function runEmitEventCommand(argv, deps = {}) {
+    const parsed = parseEmitEventArgs(argv, deps);
+    if (parsed.help) {
+        console.log(getConductorUsage());
+        return 0;
+    }
+    let result;
+    try {
+        result = await emitConductorEvent(parsed.input);
+    }
+    catch (error) {
+        // A forwarded deterministic `--id` (BAPI-527) that collides on the events.id
+        // UNIQUE constraint is a server-side dedup, not a failure: report it as a
+        // structured duplicate so the worker gate path can treat it as a no-op emit
+        // without ever polling the ledger in-process.
+        if (isDuplicateConstraintError(error)) {
+            const dup = { ok: false, reason: "duplicate" };
+            console.log(parsed.json ? JSON.stringify(dup) : JSON.stringify(dup, null, 2));
+            return 0;
+        }
+        throw error;
+    }
+    if (parsed.json) {
+        console.log(JSON.stringify(result));
+    }
+    else {
+        console.log(JSON.stringify(result, null, 2));
+    }
+    return 0;
+}
+// ---------------------------------------------------------------------------
+// send-message / check-messages (BAPI-397 cooperative message relay)
+// ---------------------------------------------------------------------------
+const SEND_MESSAGE_VALUE_FLAGS = new Set([
+    "--run-id",
+    "--worker-id",
+    "--type",
+    "--cause-seq",
+    "--payload-json",
+    "--available-at",
+    "--cooldown-ms",
+]);
+const SEND_MESSAGE_BOOL_FLAGS = new Set(["--payload-json-stdin", "--json", "--help"]);
+/**
+ * Parse `send-message` flags into a {@link SendWorkerMessageInput}. The payload
+ * object can be supplied inline via `--payload-json` OR from stdin via
+ * `--payload-json-stdin` (mutually exclusive, mirroring `emit-event`). The
+ * ambiguous combination is rejected BEFORE any stdin read so a misconfigured
+ * caller never blocks on fd 0. `--cause-seq` and `--cooldown-ms` are validated as
+ * integers; deep identity/type validation is left to the store boundary.
+ */
+export function parseSendMessageArgs(argv, deps = {}) {
+    const { values, bools } = tokenizeFlags(argv, SEND_MESSAGE_VALUE_FLAGS, SEND_MESSAGE_BOOL_FLAGS);
+    if (bools.has("--help")) {
+        return {
+            input: { run_id: "", worker_id: "", type: "", cause_seq: 0 },
+            json: bools.has("--json"),
+            help: true,
+        };
+    }
+    const runId = values.get("--run-id");
+    const workerId = values.get("--worker-id");
+    const type = values.get("--type");
+    const causeSeqRaw = values.get("--cause-seq");
+    if (!runId)
+        throw new ConductorValidationError('Flag "--run-id" is required for send-message.');
+    if (!workerId)
+        throw new ConductorValidationError('Flag "--worker-id" is required for send-message.');
+    if (!type)
+        throw new ConductorValidationError('Flag "--type" is required for send-message.');
+    if (causeSeqRaw === undefined) {
+        throw new ConductorValidationError('Flag "--cause-seq" is required for send-message.');
+    }
+    if (!/^\d+$/.test(causeSeqRaw.trim())) {
+        throw new ConductorValidationError('Flag "--cause-seq" must be a non-negative integer.');
+    }
+    const causeSeq = Number.parseInt(causeSeqRaw.trim(), 10);
+    let payload = {};
+    const payloadInline = values.get("--payload-json");
+    const payloadStdin = bools.has("--payload-json-stdin");
+    if (payloadInline !== undefined && payloadStdin) {
+        throw new ConductorValidationError('Flags "--payload-json" and "--payload-json-stdin" are mutually exclusive; pass the payload object exactly one way.');
+    }
+    if (payloadStdin) {
+        const readStdin = deps.readStdin ?? defaultReadStdin;
+        const parsed = parseJsonFlag(readStdin(), "--payload-json-stdin");
+        if (!isPlainObject(parsed)) {
+            throw new ConductorValidationError('Flag "--payload-json-stdin" must be a JSON object.');
+        }
+        payload = { ...parsed };
+    }
+    else if (payloadInline !== undefined) {
+        const parsed = parseJsonFlag(payloadInline, "--payload-json");
+        if (!isPlainObject(parsed)) {
+            throw new ConductorValidationError('Flag "--payload-json" must be a JSON object.');
+        }
+        payload = { ...parsed };
+    }
+    const input = {
+        run_id: runId,
+        worker_id: workerId,
+        type,
+        cause_seq: causeSeq,
+        payload,
+    };
+    const availableAt = values.get("--available-at");
+    if (availableAt !== undefined)
+        input.available_at = availableAt;
+    const cooldownRaw = values.get("--cooldown-ms");
+    if (cooldownRaw !== undefined) {
+        if (!/^\d+$/.test(cooldownRaw.trim())) {
+            throw new ConductorValidationError('Flag "--cooldown-ms" must be a non-negative integer.');
+        }
+        input.cooldown_ms = Number.parseInt(cooldownRaw.trim(), 10);
+    }
+    return { input, json: bools.has("--json"), help: false };
+}
+/**
+ * Run `send-message`. Prints compact JSON when `--json` is set; otherwise a
+ * sanitized human summary (message id / status / type only — NEVER the payload).
+ */
+export async function runSendMessageCommand(argv, deps = {}) {
+    const parsed = parseSendMessageArgs(argv, deps);
+    if (parsed.help) {
+        console.log(getConductorUsage());
+        return 0;
+    }
+    const result = await sendWorkerMessage(parsed.input);
+    if (parsed.json) {
+        console.log(JSON.stringify(result));
+    }
+    else {
+        console.log([
+            `Message ${result.status}.`,
+            `  id:     ${result.message.id}`,
+            `  type:   ${result.message.type}`,
+            `  state:  ${result.message.state}`,
+        ].join("\n"));
+    }
+    return 0;
+}
+const CHECK_MESSAGES_VALUE_FLAGS = new Set(["--run-id", "--worker-id", "--limit"]);
+const CHECK_MESSAGES_BOOL_FLAGS = new Set(["--json", "--help"]);
+/**
+ * Parse `check-messages` flags into a {@link CheckWorkerMessagesInput}. CLI usage
+ * requires EXPLICIT `--run-id` and `--worker-id` — unlike the MCP tool, it never
+ * silently falls back to conductor environment identity (an operator must say
+ * exactly which worker's queue to drain).
+ */
+export function parseCheckMessagesArgs(argv) {
+    const { values, bools } = tokenizeFlags(argv, CHECK_MESSAGES_VALUE_FLAGS, CHECK_MESSAGES_BOOL_FLAGS);
+    if (bools.has("--help")) {
+        return { input: { run_id: "", worker_id: "" }, json: bools.has("--json"), help: true };
+    }
+    const runId = values.get("--run-id");
+    const workerId = values.get("--worker-id");
+    if (!runId)
+        throw new ConductorValidationError('Flag "--run-id" is required for check-messages.');
+    if (!workerId)
+        throw new ConductorValidationError('Flag "--worker-id" is required for check-messages.');
+    const input = { run_id: runId, worker_id: workerId };
+    const limitRaw = values.get("--limit");
+    if (limitRaw !== undefined) {
+        if (!/^\d+$/.test(limitRaw.trim())) {
+            throw new ConductorValidationError('Flag "--limit" must be a positive integer.');
+        }
+        input.limit = Number.parseInt(limitRaw.trim(), 10);
+    }
+    return { input, json: bools.has("--json"), help: false };
+}
+/**
+ * Run `check-messages`. Prints compact JSON when `--json` is set; otherwise a
+ * sanitized human summary (counts + per-message id/type only — NEVER payloads).
+ */
+export async function runCheckMessagesCommand(argv) {
+    const parsed = parseCheckMessagesArgs(argv);
+    if (parsed.help) {
+        console.log(getConductorUsage());
+        return 0;
+    }
+    const result = await checkWorkerMessages(parsed.input);
+    if (parsed.json) {
+        console.log(JSON.stringify(result));
+        return 0;
+    }
+    const lines = [`Acknowledged ${result.acked_count} of ${result.count} message(s).`];
+    for (const message of result.messages) {
+        lines.push(`  ${message.id}  [${message.type}] -> ${message.state}`);
+    }
+    console.log(lines.join("\n"));
+    return 0;
+}
+const DIAGNOSTIC_BOOL_FLAGS = new Set(["--json", "--help"]);
+const DOCTOR_BOOL_FLAGS = new Set([...DIAGNOSTIC_BOOL_FLAGS, "--no-deny-probe"]);
+/**
+ * Run the strictly read-only `doctor` command. Combines ledger health and git
+ * hook health. `--json` emits the full report with `git_hooks` alongside the
+ * ledger fields at the top level. `--no-deny-probe` skips the deny-enforcement
+ * preflight (no headless agent spawn); the report then carries an explicit
+ * skipped state, never enforced.
+ */
+export async function runDoctorCommand(argv, deps = {}) {
+    const { bools } = tokenizeFlags(argv, new Set(), DOCTOR_BOOL_FLAGS);
+    if (bools.has("--help")) {
+        console.log(getConductorUsage());
+        return 0;
+    }
+    // A caller may inject deps (e.g. a fake deny inspector in tests) to stay hermetic.
+    const report = await buildConductorDoctorReport(bools.has("--no-deny-probe") ? { ...deps, skipDenyProbe: true } : deps);
+    if (bools.has("--json")) {
+        console.log(JSON.stringify({ ...report.ledger, git_hooks: report.git_hooks, mcp_profile: report.mcp_profile, native_ledger: report.native_ledger, deny_enforcement: report.deny_enforcement }));
+        return 0;
+    }
+    console.log(formatConductorDoctorReport(report));
+    return 0;
+}
+/**
+ * Run `install-git-hooks`: install/update the local managed `post-commit` and
+ * `reference-transaction` hooks. Returns 0 even when the directory is not a git
+ * worktree (degraded optional capability) — never a fatal failure.
+ *
+ * BAPI-772: an unresolvable `conductor-bin.js` IS fatal (exit 1). Writing a hook
+ * that points at a nonexistent binary produced a hook that silently did nothing
+ * on every commit, so the installer now refuses and this command reports the
+ * refusal with the resolver's searched-layout remediation.
+ */
+export function runInstallGitHooksCommand(argv) {
+    const { bools } = tokenizeFlags(argv, new Set(), DIAGNOSTIC_BOOL_FLAGS);
+    if (bools.has("--help")) {
+        console.log(getConductorUsage());
+        return 0;
+    }
+    const result = installConductorGitHooks();
+    if (!result.ok) {
+        if (bools.has("--json")) {
+            console.error(JSON.stringify({ error: result.error, reason: result.reason }));
+            return 1;
+        }
+        console.error(`Error: conductor git hooks were NOT installed (${result.error}): ${result.reason}`);
+        return 1;
+    }
+    if (bools.has("--json")) {
+        console.log(JSON.stringify(result));
+        return 0;
+    }
+    const lines = [
+        "Conductor git hooks install",
+        "───────────────────────────",
+        `is git worktree:  ${result.is_worktree}`,
+        `hooks dir:        ${result.hooks_dir ?? "n/a"}`,
+        `conductor bin:    ${result.conductor_bin}`,
+    ];
+    for (const hook of result.installed) {
+        lines.push(`  ${hook.name}: ${hook.action}${hook.warning ? ` (${hook.warning})` : ""}`);
+    }
+    if (result.warnings.length > 0) {
+        lines.push("warnings:");
+        for (const w of result.warnings)
+            lines.push(`  - ${w}`);
+    }
+    console.log(lines.join("\n"));
+    return 0;
+}
+/**
+ * Run the private `__hook-bin` diagnostic: resolve the hook binary from the
+ * executing artifact and print ONLY that canonical path to stdout, so artifact-
+ * level automation can consume it directly. A failed resolution prints the
+ * sanitized resolver reason to stderr and returns 1 — never a stack trace.
+ */
+export function runHookBinDiagnosticCommand() {
+    const resolution = resolveConductorHookBin();
+    if (!resolution.ok) {
+        console.error(`conductor hook bin UNRESOLVED: ${resolution.reason}`);
+        return 1;
+    }
+    console.log(resolution.path);
+    return 0;
+}
+const GIT_HOOK_VALUE_FLAGS = new Set(["--phase", "--stdin-file"]);
+const GIT_HOOK_BOOL_FLAGS = new Set(["--help"]);
+/**
+ * Parse `git-hook <subcommand> [--phase <p>] [--stdin-file <f>]`. Validates the
+ * subcommand and, for `reference-transaction`, surfaces the phase / stdin-file.
+ */
+export function parseGitHookArgs(argv) {
+    const subcommand = argv[0];
+    if (subcommand !== "post-commit" && subcommand !== "reference-transaction") {
+        throw new ConductorValidationError(`Unknown git-hook subcommand "${subcommand ?? ""}". Expected "post-commit" or "reference-transaction".`);
+    }
+    const { values } = tokenizeFlags(argv.slice(1), GIT_HOOK_VALUE_FLAGS, GIT_HOOK_BOOL_FLAGS);
+    return {
+        subcommand,
+        phase: values.get("--phase"),
+        stdinFile: values.get("--stdin-file"),
+    };
+}
+/**
+ * Run a `git-hook` subcommand. ALWAYS returns exit code 0 (after at most a generic
+ * warning) so a conductor producer failure never blocks the git commit/ref update
+ * the hook is attached to.
+ */
+export async function runGitHookCommand(argv) {
+    let parsed;
+    try {
+        parsed = parseGitHookArgs(argv);
+    }
+    catch {
+        // A malformed hook invocation must not block git; warn generically and exit 0.
+        process.stderr.write("Warning: conductor git-hook invocation was invalid.\n");
+        return 0;
+    }
+    try {
+        if (parsed.subcommand === "post-commit") {
+            await runPostCommitHookProducer();
+            return 0;
+        }
+        // reference-transaction: read the captured updates from the stdin file.
+        let stdin = "";
+        if (parsed.stdinFile) {
+            try {
+                stdin = readFileSync(parsed.stdinFile, "utf-8");
+            }
+            catch {
+                stdin = "";
+            }
+            finally {
+                // The hook writes ref updates to a per-transaction mktemp file; remove it
+                // so these never accumulate in /tmp on long-lived checkouts / CI runners.
+                try {
+                    unlinkSync(parsed.stdinFile);
+                }
+                catch {
+                    /* best-effort cleanup */
+                }
+            }
+        }
+        await runReferenceTransactionHookProducer({ phase: parsed.phase ?? "", stdin });
+        return 0;
+    }
+    catch {
+        process.stderr.write("Warning: conductor git-hook producer failed.\n");
+        return 0;
+    }
+}
+// ---------------------------------------------------------------------------
+// epic-tick
+// ---------------------------------------------------------------------------
+const EPIC_TICK_VALUE_FLAGS = new Set([
+    "--epic-key",
+    "--scheduled-at",
+    "--lease-ttl-seconds",
+]);
+const EPIC_TICK_BOOL_FLAGS = new Set(["--help"]);
+/**
+ * Parse `epic-tick` flags. `--epic-key` is required and must be non-empty /
+ * non-whitespace. Numeric overrides (`--scheduled-at`, `--lease-ttl-seconds`)
+ * are validated as non-negative integers using the shared
+ * {@link parsePositiveIntFlag} convention. Malformed input raises a sanitized
+ * {@link ConductorValidationError}.
+ */
+export function parseEpicTickArgs(argv) {
+    const { values, bools } = tokenizeFlags(argv, EPIC_TICK_VALUE_FLAGS, EPIC_TICK_BOOL_FLAGS);
+    if (bools.has("--help")) {
+        return { epicKey: "", help: true };
+    }
+    const epicKeyRaw = values.get("--epic-key");
+    if (epicKeyRaw === undefined || epicKeyRaw.trim().length === 0) {
+        throw new ConductorValidationError('Flag "--epic-key" is required for epic-tick and must be non-empty.');
+    }
+    const scheduledAt = parsePositiveIntFlag(values, "--scheduled-at");
+    const leaseTtlSeconds = parsePositiveIntFlag(values, "--lease-ttl-seconds");
+    return { epicKey: epicKeyRaw.trim(), scheduledAt, leaseTtlSeconds, help: false };
+}
+/**
+ * Default the PreToolUse hook ON for epic-dispatched workers so the supervisor
+ * gets worker-liveness (`tool.intent`) signals without the operator having to
+ * export `BAPI_CONDUCTOR_ENABLE_PRE_TOOL_USE=1` (BAPI-441/A1 finding).
+ *
+ * Both the child-env copy and the hook registration key off this SAME
+ * parent-process env flag, read at dispatch time, so setting it once at the
+ * epic-tick boundary covers the whole tick. Only defaults when the flag is
+ * UNSET — an explicit "0"/"" still disables it, because `isConductorFlagEnabled`
+ * treats those as false. Mutates the supplied env in place (defaults to
+ * `process.env`) and returns it.
+ */
+export function applyEpicTickPreToolUseDefault(env = process.env) {
+    if (env.BAPI_CONDUCTOR_ENABLE_PRE_TOOL_USE === undefined) {
+        env.BAPI_CONDUCTOR_ENABLE_PRE_TOOL_USE = "1";
+    }
+    return env;
+}
+/**
+ * Run the `epic-tick` command. Lazily imports the epic runtime so a plain
+ * `epic-implementer doctor` / `emit-event` invocation never eagerly resolves
+ * the epic/store graph.
+ */
+export async function runEpicTickCommand(_argv) {
+    // BAPI-534 (Epic Conductor v2 slice 0): the v1 epic-tick path is FROZEN. This
+    // fail-loud guard is the FIRST executable statement — before argument parsing,
+    // `applyEpicTickPreToolUseDefault()`, and any lazy `import("./epic-runtime.js")`
+    // — so no v1 tick (or its store/supervisor graph) can ever run. Interactive
+    // `/start-tickets` is unaffected. `runEpicImplementerCli` catches this named
+    // error and formats it consistently (EPIC_TICK_V1_FROZEN → exit 1).
+    throw new ConductorEpicTickV1FrozenError();
+}
+/** @deprecated v1 epic-tick body — retained unreachable behind the freeze guard. */
+export async function runEpicTickCommandLegacy(argv) {
+    const parsed = parseEpicTickArgs(argv);
+    if (parsed.help) {
+        console.log(getConductorUsage());
+        return 0;
+    }
+    // Enable supervisor worker-liveness by default for the whole tick (see the
+    // helper's doc comment); set before runEpicTick dispatches any worker.
+    applyEpicTickPreToolUseDefault();
+    // `runEpicTick` is imported LAZILY so the store/supervisor graph is not
+    // evaluated for other epic-implementer CLI commands that never need it.
+    const { runEpicTick, buildProductionEpicRuntimeDeps } = await import("./epic-runtime.js");
+    const prodDeps = await buildProductionEpicRuntimeDeps(parsed.epicKey);
+    const result = await runEpicTick({
+        epic_key: parsed.epicKey,
+        scheduled_at: parsed.scheduledAt !== undefined ? parsed.scheduledAt * 1000 : undefined,
+        lease_ttl_seconds: parsed.leaseTtlSeconds,
+    }, prodDeps);
+    return result.exit_code;
+}
+// ---------------------------------------------------------------------------
+// approve-plan
+// ---------------------------------------------------------------------------
+const APPROVE_PLAN_VALUE_FLAGS = new Set(["--plan-version"]);
+const APPROVE_PLAN_BOOL_FLAGS = new Set(["--json", "--help"]);
+/**
+ * Parse `approve-plan` argv. `<epic_key>` is the required first positional
+ * argument (a Jira key, e.g. EPIC-405); `--plan-version` is a required
+ * strictly-positive integer flag.
+ * Malformed input raises a sanitized {@link ConductorValidationError}.
+ */
+export function parseApprovePlanArgs(argv) {
+    // Short-circuit for bare --help / -h before positional extraction.
+    if (argv.length === 0 || argv[0] === "--help" || argv[0] === "-h") {
+        return { epicKey: "", planVersion: 0, json: false, help: true };
+    }
+    // Extract the first positional argument (epic_key) before flag tokenization.
+    let epicKey;
+    let restArgv;
+    if (!argv[0].startsWith("-")) {
+        epicKey = argv[0];
+        restArgv = argv.slice(1);
+    }
+    else {
+        restArgv = argv;
+    }
+    const { values, bools } = tokenizeFlags(restArgv, APPROVE_PLAN_VALUE_FLAGS, APPROVE_PLAN_BOOL_FLAGS);
+    if (bools.has("--help")) {
+        return { epicKey: "", planVersion: 0, json: false, help: true };
+    }
+    if (!epicKey || epicKey.trim().length === 0) {
+        throw new ConductorValidationError('Argument "<epic_key>" is required for approve-plan and must be non-empty.');
+    }
+    const planVersion = parsePositiveIntFlag(values, "--plan-version");
+    if (planVersion === undefined) {
+        throw new ConductorValidationError('Flag "--plan-version" is required for approve-plan and must be a strictly positive integer.');
+    }
+    if (planVersion === 0) {
+        throw new ConductorValidationError('Flag "--plan-version" must be a strictly positive integer (≥ 1).');
+    }
+    return { epicKey: epicKey.trim(), planVersion, json: bools.has("--json"), help: false };
+}
+/**
+ * Run the `approve-plan` command. Resolves Bridge API credentials, calls the
+ * atomic approve endpoint, and prints a human-readable or JSON summary.
+ * Returns a process exit code; never calls `process.exit` directly. All
+ * errors are wrapped in sanitized {@link toConductorErrorEnvelope} output —
+ * no stack traces, tokens, or response bodies are printed.
+ */
+export async function runApprovePlanCommand(argv) {
+    let parsed;
+    try {
+        parsed = parseApprovePlanArgs(argv);
+    }
+    catch (error) {
+        const envelope = toConductorErrorEnvelope(error);
+        console.error(`Error: ${formatConductorErrorLine(envelope)}`);
+        return 1;
+    }
+    if (parsed.help) {
+        console.log(getConductorUsage());
+        return 0;
+    }
+    // Lazy import keeps the credential/HTTP graph out of commands that never
+    // need Bridge API access (doctor, emit-event, etc.).
+    const { resolveConductorBridgeApiAccess, approveEpicPlan } = await import("./bridge-api-client.js");
+    const accessResult = await resolveConductorBridgeApiAccess();
+    if (!accessResult.ok) {
+        const envelope = { error: "CREDENTIALS_UNAVAILABLE", status: 401, message: accessResult.error };
+        if (parsed.json) {
+            console.log(JSON.stringify({ ok: false, kind: "unauthorized", error: envelope.message }));
+        }
+        else {
+            console.error(`Error: ${accessResult.error}`);
+        }
+        return 1;
+    }
+    try {
+        const result = await approveEpicPlan(accessResult.access, {
+            epicKey: parsed.epicKey,
+            planVersion: parsed.planVersion,
+        });
+        if (!result.ok) {
+            throw new ConductorValidationError(`approve-plan rejected: version drift or monotonic constraint violation ` +
+                `(kind: ${result.kind}). Ensure --plan-version is strictly greater than ` +
+                `the current approved version and that the blob has been stored first.`);
+        }
+        if (parsed.json) {
+            console.log(JSON.stringify({ ok: true, plan_hash: result.plan_hash }));
+        }
+        else {
+            console.log(`Plan approved atomically. ` +
+                `Epic Key: ${parsed.epicKey}, ` +
+                `Plan Version: ${parsed.planVersion}, ` +
+                `Approved Hash: ${result.plan_hash}`);
+        }
+        return 0;
+    }
+    catch (error) {
+        // S4 (BAPI-1080): standardized to a single sanitized-failure exit code (1)
+        // rather than distinguishing 5xx (2) from other failures.
+        const envelope = toConductorErrorEnvelope(error);
+        if (parsed.json) {
+            console.log(JSON.stringify(envelope));
+        }
+        else {
+            console.error(`Error: ${formatConductorErrorLine(envelope)}`);
+        }
+        return 1;
+    }
+}
+// ---------------------------------------------------------------------------
+// epic-status
+// ---------------------------------------------------------------------------
+const EPIC_STATUS_VALUE_FLAGS = new Set(["--epic-key"]);
+const EPIC_STATUS_BOOL_FLAGS = new Set(["--json", "--help"]);
+/**
+ * Parse `epic-status` flags. `--epic-key` is required and must be non-empty.
+ * Malformed input raises a sanitized {@link ConductorValidationError}.
+ */
+export function parseEpicStatusArgs(argv) {
+    const { values, bools } = tokenizeFlags(argv, EPIC_STATUS_VALUE_FLAGS, EPIC_STATUS_BOOL_FLAGS);
+    if (bools.has("--help")) {
+        return { epicKey: "", json: false, help: true };
+    }
+    const epicKeyRaw = values.get("--epic-key");
+    if (epicKeyRaw === undefined || epicKeyRaw.trim().length === 0) {
+        throw new ConductorValidationError('Flag "--epic-key" is required for epic-status and must be non-empty.');
+    }
+    return { epicKey: epicKeyRaw.trim(), json: bools.has("--json"), help: false };
+}
+/**
+ * Run the `epic-status` command. Resolves Bridge API credentials, calls
+ * `fetchEpicRunState`, and prints either compact JSON or a sanitized
+ * human-readable summary (structured status fields only — never raw payloads).
+ * Returns a process exit code; never calls `process.exit` directly.
+ */
+export async function runEpicStatusCommand(argv) {
+    let parsed;
+    try {
+        parsed = parseEpicStatusArgs(argv);
+    }
+    catch (error) {
+        const envelope = toConductorErrorEnvelope(error);
+        console.error(`Error: ${formatConductorErrorLine(envelope)}`);
+        return 1;
+    }
+    if (parsed.help) {
+        console.log(getConductorUsage());
+        return 0;
+    }
+    // Lazy import keeps the credential/HTTP graph out of commands that never
+    // need Bridge API access (doctor, emit-event, etc.).
+    const { resolveConductorBridgeApiAccess, fetchEpicRunState, ConductorBridgeApiError: BridgeApiError } = await import("./bridge-api-client.js");
+    const accessResult = await resolveConductorBridgeApiAccess();
+    if (!accessResult.ok) {
+        if (parsed.json) {
+            console.log(JSON.stringify({ ok: false, kind: "unauthorized", error: accessResult.error }));
+        }
+        else {
+            console.error(`Error: ${accessResult.error}`);
+        }
+        return 1;
+    }
+    try {
+        const state = await fetchEpicRunState(accessResult.access, parsed.epicKey);
+        if (parsed.json) {
+            console.log(JSON.stringify(state));
+            return 0;
+        }
+        // Human-readable summary: structured status fields only, no raw payloads.
+        const lines = [];
+        const run = state.epic_run;
+        lines.push(`Epic Run: ${run.epic_key}`);
+        lines.push(`  status:          ${run.status}`);
+        lines.push(`  plan_version:    ${run.current_plan_version}`);
+        const leaseState = run.lease_owner
+            ? `${run.lease_owner} (expires ${run.lease_expires_at ?? "unknown"})`
+            : "none";
+        lines.push(`  lease:           ${leaseState}`);
+        lines.push(`  budget:          ${run.budget_wall_clock_seconds ?? "unlimited"}s / ${run.budget_cost_cents ?? "unlimited"} cents`);
+        lines.push(`  consumed:        ${run.consumed_wall_clock_seconds}s / ${run.consumed_cost_cents} cents`);
+        lines.push(`\nTickets (${state.ticket_statuses.length}):`);
+        for (const t of state.ticket_statuses) {
+            const dispatchRef = t.dispatch_run_id ? `dispatch_run_id=${t.dispatch_run_id}` : "-";
+            lines.push(`  ${t.ticket_key}  [${t.status}]  ${dispatchRef}  remediation=${t.remediation_attempts}/${t.remediation_no_progress_attempts}`);
+        }
+        lines.push(`\nDispatches (${state.dispatches.length}):`);
+        for (const d of state.dispatches) {
+            const runRef = d.run_id ? `run_id=${d.run_id}` : "-";
+            lines.push(`  ${d.dispatch_key}  [${d.status}]  ${runRef}`);
+        }
+        console.log(lines.join("\n"));
+        return 0;
+    }
+    catch (error) {
+        if (error instanceof BridgeApiError && error.status === 404) {
+            if (parsed.json) {
+                console.log(JSON.stringify({ epic_key: parsed.epicKey, status: "unknown", state: null }));
+            }
+            else {
+                console.log("No such epic found.");
+            }
+            return 0;
+        }
+        // S4 (BAPI-1080): standardized to a single sanitized-failure exit code (1)
+        // rather than distinguishing 5xx (2) from other failures.
+        const envelope = toConductorErrorEnvelope(error);
+        if (parsed.json) {
+            console.log(JSON.stringify(envelope));
+        }
+        else {
+            console.error(`Error: ${formatConductorErrorLine(envelope)}`);
+        }
+        return 1;
+    }
+}
+// ---------------------------------------------------------------------------
+// supervise
+// ---------------------------------------------------------------------------
+const SUPERVISE_VALUE_FLAGS = new Set([
+    "--run-id",
+    "--wake-interval-ms",
+    "--global-timeout-ms",
+    "--escalation-cooldown-ms",
+]);
+const SUPERVISE_BOOL_FLAGS = new Set(["--help"]);
+/** Parse a required positive-integer flag, raising a sanitized error otherwise. */
+function parsePositiveIntFlag(values, flag) {
+    const raw = values.get(flag);
+    if (raw === undefined)
+        return undefined;
+    if (!/^\d+$/.test(raw.trim())) {
+        throw new ConductorValidationError(`Flag "${flag}" must be a non-negative integer.`);
+    }
+    const n = Number.parseInt(raw.trim(), 10);
+    if (!Number.isFinite(n)) {
+        throw new ConductorValidationError(`Flag "${flag}" must be a non-negative integer.`);
+    }
+    return n;
+}
+/**
+ * Parse `supervise` flags. `--run-id` is required and must be non-empty /
+ * non-whitespace. Numeric overrides are validated as non-negative integers (the
+ * config resolver clamps them to safe bounds). Malformed input raises a
+ * sanitized {@link ConductorValidationError}.
+ */
+export function parseSuperviseArgs(argv) {
+    const { values, bools } = tokenizeFlags(argv, SUPERVISE_VALUE_FLAGS, SUPERVISE_BOOL_FLAGS);
+    if (bools.has("--help")) {
+        return { runId: "", overrides: {}, help: true };
+    }
+    const runIdRaw = values.get("--run-id");
+    if (runIdRaw === undefined || runIdRaw.trim().length === 0) {
+        throw new ConductorValidationError('Flag "--run-id" is required for supervise and must be non-empty.');
+    }
+    const overrides = {};
+    const wake = parsePositiveIntFlag(values, "--wake-interval-ms");
+    if (wake !== undefined)
+        overrides.wake_interval_ms = wake;
+    const globalTimeout = parsePositiveIntFlag(values, "--global-timeout-ms");
+    if (globalTimeout !== undefined)
+        overrides.global_timeout_ms = globalTimeout;
+    const cooldown = parsePositiveIntFlag(values, "--escalation-cooldown-ms");
+    if (cooldown !== undefined)
+        overrides.escalation_cooldown_ms = cooldown;
+    return { runId: runIdRaw.trim(), overrides, help: false };
+}
+/**
+ * Run the foreground `supervise` command. Resolves config (for a startup
+ * banner), runs the supervisor loop, and returns the supervisor's process exit
+ * code. Normal foreground output is written through the runtime's injected log
+ * functions.
+ */
+export async function runSuperviseCommand(argv) {
+    const parsed = parseSuperviseArgs(argv);
+    if (parsed.help) {
+        console.log(getConductorUsage());
+        return 0;
+    }
+    const config = resolveSupervisorConfig(parsed.overrides);
+    console.log(`[supervisor] starting run=${parsed.runId} wake=${config.wake_interval_ms}ms ` +
+        `global_timeout=${config.global_timeout_ms}ms`);
+    const { runSupervisor } = await import("./supervisor-runtime.js");
+    const result = await runSupervisor({ run_id: parsed.runId, config });
+    return result.exit_code;
+}
+/** Run the explicit `purge` command. Prints deleted row counts. */
+export async function runPurgeCommand(argv) {
+    const { bools } = tokenizeFlags(argv, new Set(), DIAGNOSTIC_BOOL_FLAGS);
+    if (bools.has("--help")) {
+        console.log(getConductorUsage());
+        return 0;
+    }
+    const result = await purgeConductorLedger();
+    if (bools.has("--json")) {
+        console.log(JSON.stringify(result));
+        return 0;
+    }
+    console.log([
+        `Conductor ledger purged (existed: ${result.existed}).`,
+        `  events:                ${result.deleted.events}`,
+        `  messages:              ${result.deleted.messages}`,
+        `  supervisor_projection: ${result.deleted.supervisor_projection}`,
+    ].join("\n"));
+    return 0;
+}
+/**
+ * Dispatch the epic-implementer CLI. Returns (asynchronously) a process exit
+ * code (non-zero for parser, validation, and storage failures). The dispatcher
+ * is async so the foreground `supervise` command can be awaited; the
+ * synchronous commands resolve immediately. Only sanitized error messages are
+ * printed; stack traces are never shown.
+ *
+ * S5 seam: the internal `conductor/` ledger schema, event kinds, and MCP
+ * profile group this dispatcher sits alongside remain unrenamed until S5; this
+ * S4 slice renames only the public entry point and CLI-facing text.
+ */
+export async function runEpicImplementerCli(argv) {
+    const parsed = parseConductorArgs(argv);
+    if (parsed.kind === "help") {
+        console.log(getConductorUsage());
+        return 0;
+    }
+    if (parsed.kind === "error") {
+        console.error(`Error: ${parsed.message}`);
+        return 1;
+    }
+    try {
+        switch (parsed.command) {
+            case "emit-event":
+                return await runEmitEventCommand(parsed.argv);
+            case "supervise":
+                return await runSuperviseCommand(parsed.argv);
+            case "epic-tick":
+                return await runEpicTickCommand(parsed.argv);
+            case "approve-plan":
+                return await runApprovePlanCommand(parsed.argv);
+            case "epic-status":
+                return await runEpicStatusCommand(parsed.argv);
+            case "send-message":
+                return await runSendMessageCommand(parsed.argv);
+            case "check-messages":
+                return await runCheckMessagesCommand(parsed.argv);
+            case "doctor":
+                return await runDoctorCommand(parsed.argv);
+            case "readiness": {
+                // Lazily imported, like the recovery verbs: the readiness gate pulls in
+                // the Bridge HTTP client and the plane preflight graph, and a local-only
+                // command (doctor, emit-event) must not pay for that at load time.
+                const { runConductorReadinessCommand } = await import("./readiness-cli.js");
+                return await runConductorReadinessCommand(parsed.argv);
+            }
+            case "purge":
+                return await runPurgeCommand(parsed.argv);
+            case "install-git-hooks":
+                return runInstallGitHooksCommand(parsed.argv);
+            case "git-hook":
+                return await runGitHookCommand(parsed.argv);
+            case CONDUCTOR_HOOK_BIN_ACTION:
+                // Dispatched before any MCP server construction or store access: the
+                // guard must be able to run against a bundle whose ledger is absent.
+                return runHookBinDiagnosticCommand();
+            case "file-scope-guard":
+                // BAPI-507 (N-2): warn-only worker file-scope guard. Always exits 0.
+                return runFileScopeGuardCli();
+            case "stop-run": {
+                // BAPI-872: lazily imported so the Bridge credential/HTTP graph never
+                // loads for a local-only command (doctor, emit-event, etc.).
+                const { runStopRunCommand } = await import("./recovery-cli.js");
+                return await runStopRunCommand(parsed.argv);
+            }
+            case "abandon-run": {
+                const { runAbandonRunCommand } = await import("./recovery-cli.js");
+                return await runAbandonRunCommand(parsed.argv);
+            }
+            case "unpark": {
+                const { runUnparkCommand } = await import("./recovery-cli.js");
+                return await runUnparkCommand(parsed.argv);
+            }
+            case "adopt-current-head-and-unpark": {
+                const { runAdoptCurrentHeadAndUnparkCommand } = await import("./recovery-cli.js");
+                return await runAdoptCurrentHeadAndUnparkCommand(parsed.argv);
+            }
+            // BAPI-1154: the three run-addressed repair verbs — CLI-only, and lazily
+            // imported exactly like the four recovery verbs above.
+            case "scope-reparse": {
+                const { runScopeReparseCommand } = await import("./recovery-cli.js");
+                return await runScopeReparseCommand(parsed.argv);
+            }
+            case "dispatch-remediation": {
+                const { runDispatchRemediationCommand } = await import("./recovery-cli.js");
+                return await runDispatchRemediationCommand(parsed.argv);
+            }
+            case "merge-child": {
+                const { runMergeChildCommand } = await import("./recovery-cli.js");
+                return await runMergeChildCommand(parsed.argv);
+            }
+            default:
+                console.error('Error: Unknown command. Run "epic-implementer --help" for usage.');
+                return 1;
+        }
+    }
+    catch (error) {
+        // S4 (BAPI-1080): standardized to a single sanitized-failure exit code (1)
+        // rather than distinguishing 5xx (2) from other failures. Deliberate
+        // non-catch outcomes of the underlying commands (e.g. a command's own
+        // `return 1`) are untouched by this catch.
+        const envelope = toConductorErrorEnvelope(error);
+        console.error(`Error: ${formatConductorErrorLine(envelope)}`);
+        return 1;
+    }
+}