@bridge_gpt/mcp-server 0.2.1 → 0.2.3

package/build/conductor/cli.js

@@ -0,0 +1,1048 @@
+/**
+ * Local-only conductor CLI.
+ *
+ * Provides a dependency-light command skeleton for fast git/agent hooks and
+ * operator diagnostics that must NOT depend on the Bridge API backend:
+ *
+ *   conductor emit-event --type <t> --source <s> [...]
+ *   conductor doctor [--json]
+ *   conductor 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 runConductorCli} returns a process exit code rather than calling
+ * `process.exit` itself (the bin wrapper owns that).
+ */
+import { readFileSync, unlinkSync } from "node:fs";
+import { ConductorValidationError, toConductorErrorEnvelope } from "./errors.js";
+import { emitConductorEvent, purgeConductorLedger, sendWorkerMessage, checkWorkerMessages, } from "./store.js";
+import { SEMANTIC_EVENT_TYPES } from "./taxonomy.js";
+import { installConductorGitHooks } from "./git-hooks.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 conductor
+// CLI invocation (and every test that mocks ./store.js for the other commands) to
+// resolve the full supervisor/store graph eagerly.
+/** Human-readable usage text for the conductor CLI. */
+export function getConductorUsage() {
+    return [
+        "Usage: conductor <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)",
+        "  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)",
+        "",
+        "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",
+        "  --llm-budget-calls <n>    Max LLM judgment calls per run before degraded-only mode",
+        "  --escalation-cooldown-ms <n>  Min gap between escalations for the same worker+reason",
+        "  --no-llm                  Deterministic-only mode (never call the LLM judgment boundary)",
+        "",
+        "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.",
+        "",
+        "doctor / purge options:",
+        "  --json               Print machine-readable JSON",
+        "",
+        "Examples:",
+        "  conductor emit-event --type run.started --source git-hook --run-id BAPI-393 \\",
+        "      --data-json '{\"summary\":\"run started\"}'",
+        "  conductor emit-event --type git.commit_created --source git-hook \\",
+        "      --raw-json '{\"branch\":\"feature/x\",\"sha\":\"abc123\"}'",
+        "  conductor emit-event --type ci.failed --source ci \\",
+        "      --payload-ref 'file:///tmp/ci-log.txt'",
+        "  conductor emit-event --type merge.succeeded --source conductor-merge \\",
+        "      --worker-id w1 --data-json '{\"summary\":\"auto-merged\",\"status\":\"succeeded\"}'",
+        "  conductor doctor --json",
+        "  conductor 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:",
+        "  conductor approve-plan EPIC-405 --plan-version 2",
+        "  conductor approve-plan EPIC-405 --plan-version 2 --json",
+        "  conductor epic-status --epic-key EPIC-405",
+        "  conductor epic-status --epic-key EPIC-405 --json",
+    ].join("\n");
+}
+const VALID_COMMANDS = new Set([
+    "emit-event",
+    "supervise",
+    "epic-tick",
+    "approve-plan",
+    "epic-status",
+    "send-message",
+    "check-messages",
+    "doctor",
+    "purge",
+    "install-git-hooks",
+    "git-hook",
+]);
+/**
+ * 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 "conductor --help" for usage.` };
+    }
+    if (!VALID_COMMANDS.has(first)) {
+        return { kind: "error", message: `Unknown command "${first}". Run "conductor --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",
+    "--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,
+        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 function runEmitEventCommand(argv, deps = {}) {
+    const parsed = parseEmitEventArgs(argv, deps);
+    if (parsed.help) {
+        console.log(getConductorUsage());
+        return 0;
+    }
+    const result = emitConductorEvent(parsed.input);
+    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 function runSendMessageCommand(argv, deps = {}) {
+    const parsed = parseSendMessageArgs(argv, deps);
+    if (parsed.help) {
+        console.log(getConductorUsage());
+        return 0;
+    }
+    const result = 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 function runCheckMessagesCommand(argv) {
+    const parsed = parseCheckMessagesArgs(argv);
+    if (parsed.help) {
+        console.log(getConductorUsage());
+        return 0;
+    }
+    const result = 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"]);
+/**
+ * Run the strictly read-only `doctor` command. Combines ledger health, git hook
+ * health, and epic-tick schedule enablement status. `--json` emits the full
+ * report with `epic_tick` alongside `git_hooks` at the top level.
+ */
+export async function runDoctorCommand(argv) {
+    const { bools } = tokenizeFlags(argv, new Set(), DIAGNOSTIC_BOOL_FLAGS);
+    if (bools.has("--help")) {
+        console.log(getConductorUsage());
+        return 0;
+    }
+    // scheduleDeps omitted: buildConductorDoctorReport lazily loads schedule-run.
+    const report = await buildConductorDoctorReport({});
+    if (bools.has("--json")) {
+        console.log(JSON.stringify({ ...report.ledger, git_hooks: report.git_hooks, epic_tick: report.epic_tick }));
+        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.
+ */
+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 (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"}`,
+    ];
+    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;
+}
+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 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") {
+            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 */
+                }
+            }
+        }
+        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 };
+}
+/**
+ * Run the `epic-tick` command. Lazily imports the epic runtime so a plain
+ * `conductor doctor` / `emit-event` invocation never eagerly resolves the
+ * epic/store graph.
+ */
+export async function runEpicTickCommand(argv) {
+    const parsed = parseEpicTickArgs(argv);
+    if (parsed.help) {
+        console.log(getConductorUsage());
+        return 0;
+    }
+    // `runEpicTick` is imported LAZILY so the store/supervisor graph is not
+    // evaluated for other conductor 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: ${envelope.message}`);
+        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) {
+        const envelope = toConductorErrorEnvelope(error);
+        if (parsed.json) {
+            console.log(JSON.stringify(envelope));
+        }
+        else {
+            console.error(`Error: ${envelope.message}`);
+        }
+        return envelope.status >= 500 ? 2 : 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: ${envelope.message}`);
+        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;
+        }
+        const envelope = toConductorErrorEnvelope(error);
+        if (parsed.json) {
+            console.log(JSON.stringify(envelope));
+        }
+        else {
+            console.error(`Error: ${envelope.message}`);
+        }
+        return envelope.status >= 500 ? 2 : 1;
+    }
+}
+// ---------------------------------------------------------------------------
+// supervise
+// ---------------------------------------------------------------------------
+const SUPERVISE_VALUE_FLAGS = new Set([
+    "--run-id",
+    "--wake-interval-ms",
+    "--global-timeout-ms",
+    "--llm-budget-calls",
+    "--escalation-cooldown-ms",
+]);
+const SUPERVISE_BOOL_FLAGS = new Set(["--no-llm", "--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); `--no-llm` selects
+ * deterministic-only mode. 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 llmCalls = parsePositiveIntFlag(values, "--llm-budget-calls");
+    if (llmCalls !== undefined)
+        overrides.llm_max_calls = llmCalls;
+    const cooldown = parsePositiveIntFlag(values, "--escalation-cooldown-ms");
+    if (cooldown !== undefined)
+        overrides.escalation_cooldown_ms = cooldown;
+    if (bools.has("--no-llm"))
+        overrides.llm_enabled = false;
+    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 llm=${config.llm_enabled ? `on(${config.llm_max_calls})` : "off"}`);
+    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 function runPurgeCommand(argv) {
+    const { bools } = tokenizeFlags(argv, new Set(), DIAGNOSTIC_BOOL_FLAGS);
+    if (bools.has("--help")) {
+        console.log(getConductorUsage());
+        return 0;
+    }
+    const result = 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 conductor 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.
+ */
+export async function runConductorCli(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 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 runSendMessageCommand(parsed.argv);
+            case "check-messages":
+                return runCheckMessagesCommand(parsed.argv);
+            case "doctor":
+                return await runDoctorCommand(parsed.argv);
+            case "purge":
+                return runPurgeCommand(parsed.argv);
+            case "install-git-hooks":
+                return runInstallGitHooksCommand(parsed.argv);
+            case "git-hook":
+                return runGitHookCommand(parsed.argv);
+            default:
+                console.error('Error: Unknown command. Run "conductor --help" for usage.');
+                return 1;
+        }
+    }
+    catch (error) {
+        const envelope = toConductorErrorEnvelope(error);
+        console.error(`Error: ${envelope.message}`);
+        return envelope.status >= 500 ? 2 : 1;
+    }
+}