@bridge_gpt/mcp-server 0.2.38 → 0.2.39

package/build/conduct-epic/cli.js

@@ -0,0 +1,1732 @@
+/**
+ * The packaged `conduct-epic` CLI (BAPI-803).
+ *
+ * `/conduct-epic` (BAPI-804) is prose. Prose cannot be unit-tested, and the
+ * guarantees the loop depends on — that the epic branch was created from the
+ * right base, that a checkpoint write is atomic, that two sessions cannot edit
+ * one checkpoint, that a `MERGED` PR is visible, that `auto_merge_enabled` is on
+ * before the first ticket is dispatched — are exactly the kind that fail
+ * silently when they live in an instruction file. So they live here, behind five
+ * verbs the loop calls and this file's tests pin:
+ *
+ *   init | status | checkpoint set | finish | spawn
+ *
+ * Design rules that hold across all five:
+ *
+ * - **Nothing creates or mutates an `epic_run`.** This CLI drives a LOCAL loop.
+ *   The one epic-run call it makes (`getEpicRunState`) is a read whose only
+ *   purpose is to REFUSE when the server-side v2 reconciler is already
+ *   conducting the same epic — two conductors on one epic is the failure mode.
+ * - **Every process/network/filesystem boundary is injected** through
+ *   {@link ConductEpicDeps}, so the whole surface is testable without a real
+ *   `gh`, terminal, home directory, or Bridge server.
+ * - **`init` accumulates.** Its preflight runs every independent check and
+ *   prints every failure in one pass. Failing on the first one makes an operator
+ *   discover a five-problem environment five invocations at a time.
+ * - **`status` fails open per probe, `status` never takes the lock.** A `gh`
+ *   outage must not stop the loop from seeing its checkpoint; a read-only
+ *   surface that took a lock would deadlock against the verb that needs it.
+ * - **Credentials resolve only through `resolveConductorBridgeApiAccess`** and
+ *   never enter argv, stdout, stderr, a journal line, or an error string.
+ */
+import { execFile } from "node:child_process";
+import { promises as nodeFs } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { validateBranchName } from "../base-ref.js";
+import { parseDoneGateConfig } from "../conductor/done-gate.js";
+import { resolveConductorBridgeApiAccess, } from "../conductor/bridge-api-client.js";
+import { runGhCommand } from "../conductor/pr-discovery.js";
+import { getDefaultSpawnTerminalTabForPlatform, detectTerminal, createDefaultStartTicketsDeps, } from "../start-tickets.js";
+import { resolveWorktrunkBinary } from "../start-tickets-prereqs.js";
+import { resolveRequiredStartTicketsRepoName } from "../start-tickets-repo.js";
+import { getConfigFieldBaseBranch, getConductorReadiness, getEffectiveSupervisorConfig, getEffectiveSupervisorSetup, getEpicRunState, getIndexBranch, getParseStatus, getPrReviewStatus, pollCiChecks, putSupervisorConfigDefaults, repointIndexBranch, resolveCiChecks, restoreIndexBranch, } from "./bridge-client.js";
+import { appendTicketJournal, createInitialConductEpicCheckpoint, readConductEpicCheckpoint, resolveConductEpicCheckpointPath, resolveConductEpicLockPath, writeConductEpicCheckpointAtomic, CONDUCT_EPIC_TICKET_STATUSES, } from "./checkpoint-store.js";
+import { acquireConductEpicLock, inspectConductEpicLock, isConductEpicLockOwnerAlive, } from "./lock.js";
+import { discoverConductEpicPrState, discoverTicketWorktree, parseGitWorktreePorcelain, } from "./pr-state.js";
+import { spawnConductEpicAgentTab, CONDUCT_EPIC_AGENTS, } from "./spawn.js";
+/** Epic and ticket keys accepted by every verb. */
+export const CONDUCT_EPIC_KEY_PATTERN = /^[A-Z]+-[0-9]+$/;
+/** The five verb families. `checkpoint set` is two tokens, one verb. */
+export const CONDUCT_EPIC_VERBS = ["init", "status", "checkpoint set", "finish", "spawn"];
+/** Per-ticket fields `checkpoint set` may assign. */
+const TICKET_FIELDS = [
+    "status",
+    "branch",
+    "pr_number",
+    "spawned_at",
+    "respawns",
+    "conflict_attempts",
+    "counters.sessions_spawned",
+    "counters.plan_generations_observed",
+    "counters.merge_attempts",
+];
+/** Top-level fields `checkpoint set` may assign. */
+const TOP_LEVEL_FIELDS = ["needs_human", "counters.iterations", "counters.merges"];
+/** Build the production dependency set. */
+export function createDefaultConductEpicDeps() {
+    const runCommand = (file, args, options) => new Promise((resolve) => {
+        execFile(file, args, {
+            cwd: options?.cwd,
+            // Git porcelain output for a many-worktree checkout can be large.
+            maxBuffer: 16 * 1024 * 1024,
+            encoding: "utf-8",
+            timeout: options?.timeoutMs,
+            // Explicit: arguments are a list, never a concatenated shell string.
+            shell: false,
+        }, (error, stdout, stderr) => {
+            const code = error?.code;
+            resolve({
+                stdout: stdout ?? "",
+                stderr: stderr ?? "",
+                exitCode: typeof code === "number" ? code : error ? 1 : 0,
+            });
+        });
+    });
+    const spawner = getDefaultSpawnTerminalTabForPlatform(process.platform);
+    const startTicketsDeps = createDefaultStartTicketsDeps();
+    return {
+        runCommand,
+        runGh: (args, options) => runGhCommand(args, options ?? {}),
+        spawnTab: (shellCommand, context) => spawner(startTicketsDeps, detectTerminal(undefined, process.env), shellCommand, context),
+        fetchImpl: globalThis.fetch,
+        fs: {
+            mkdir: (dirPath, options) => nodeFs.mkdir(dirPath, options),
+            readFile: (filePath) => nodeFs.readFile(filePath, "utf-8"),
+            writeFile: (filePath, data, options) => nodeFs.writeFile(filePath, data, { encoding: "utf-8", mode: options?.mode }),
+            // Real exclusive create: `wx` fails EEXIST in the kernel, so two racing
+            // callers cannot both believe they created the file. Never reconstruct
+            // this from `stat` + `writeFile`.
+            writeFileExclusive: async (filePath, data, options) => {
+                const handle = await nodeFs.open(filePath, "wx", options?.mode);
+                try {
+                    await handle.writeFile(data, "utf-8");
+                }
+                finally {
+                    await handle.close();
+                }
+            },
+            rename: (fromPath, toPath) => nodeFs.rename(fromPath, toPath),
+            chmod: (filePath, mode) => nodeFs.chmod(filePath, mode),
+            unlink: (filePath) => nodeFs.unlink(filePath),
+            stat: (filePath) => nodeFs.stat(filePath),
+        },
+        now: () => new Date(),
+        env: process.env,
+        homedir: os.homedir,
+        hostname: os.hostname,
+        platform: process.platform,
+        cwd: process.cwd(),
+        pid: process.pid,
+        isProcessAlive: isConductEpicLockOwnerAlive,
+        log: (m) => console.log(m),
+        errorLog: (m) => console.error(m),
+        resolveAccess: resolveConductorBridgeApiAccess,
+        resolveRepoName: resolveRequiredStartTicketsRepoName,
+    };
+}
+// ---------------------------------------------------------------------------
+// Usage + argument parsing
+// ---------------------------------------------------------------------------
+/** User-facing usage text for the packaged `conduct-epic` subcommand. */
+export function getConductEpicUsage() {
+    return [
+        "Usage:",
+        "  npx -y @bridge_gpt/mcp-server conduct-epic <verb> [flags]",
+        "",
+        "Verbs:",
+        "  init <EPIC> --tickets K1,K2,... [--base-branch <b>] [--checkpoint-path <p>] [--dry-run] [--json]",
+        "      Run the full preflight, create epic/<EPIC> on origin at the fetched base",
+        "      tip, repoint the indexed branch, write the checkpoint, and take the lock.",
+        "      Every preflight failure is printed in one pass; nothing is written unless",
+        "      all of them pass. --dry-run prints the validated plan and writes nothing.",
+        "",
+        "  status <EPIC> [--checkpoint-path <p>] --json",
+        "      Print one JSON object describing the in-flight ticket, its worktree, PR,",
+        "      CI, review, parse, deadline, and lock state. --json is required. A missing",
+        "      checkpoint exits 0 with checkpoint_exists:false. A failed probe leaves its",
+        "      sub-object null and is listed in probe_errors; it never fails the command.",
+        "",
+        "  checkpoint set <EPIC> --ticket <KEY> [--field <name> <value>]... [--journal <line>]",
+        "                        [--checkpoint-path <p>]",
+        "      Apply ABSOLUTE field values (the caller computes n+1 from status).",
+        `      Ticket fields: ${TICKET_FIELDS.join(", ")}.`,
+        `      Top-level fields: ${TOP_LEVEL_FIELDS.join(", ")}.`,
+        "",
+        "  finish <EPIC> [--checkpoint-path <p>] [--json]",
+        "      Restore the server's indexed base branch (idempotent), release the owned",
+        "      lock, and print the final summary. A second finish succeeds.",
+        "",
+        `  spawn <EPIC> --ticket <KEY> --prompt-file <path> [--agent ${CONDUCT_EPIC_AGENTS.join("|")}]`,
+        "                [--checkpoint-path <p>] [--json]",
+        "      Open exactly ONE agent tab in the ticket's worktree running the prompt",
+        "      file's contents, then increment counters.sessions_spawned and append a",
+        "      journal line. Respawn and conflict budgets are the CALLER's job.",
+        "",
+        "Common:",
+        "  -h, --help                 Show this help",
+        "",
+        "State lives outside the repository, at ~/.config/bridge/conduct/<repo>/ ",
+        "(honoring XDG_CONFIG_HOME): <EPIC>.json, <EPIC>.json.prev, <EPIC>.lock, and",
+        "<EPIC>/prompts/. The directory is 0700 and files are 0600.",
+        "",
+        "Exit codes: 0 on success (including checkpoint_exists:false and an idempotent",
+        "finish); non-zero on any failure, with a one-line reason on stderr. With --json,",
+        "stdout is exactly one JSON object carrying ok.",
+    ].join("\n");
+}
+function parseError(message) {
+    return { status: "error", message };
+}
+/** Which flags each verb accepts. An unknown flag for the verb is rejected. */
+const VERB_FLAGS = {
+    init: ["--tickets", "--base-branch", "--checkpoint-path", "--dry-run", "--json"],
+    status: ["--checkpoint-path", "--json"],
+    "checkpoint-set": ["--ticket", "--field", "--journal", "--checkpoint-path"],
+    finish: ["--checkpoint-path", "--json"],
+    spawn: ["--ticket", "--prompt-file", "--agent", "--checkpoint-path", "--json"],
+};
+/**
+ * Parse and fully validate argv BEFORE any I/O.
+ *
+ * Rejects unknown verbs, unknown flags, duplicate singleton options, missing
+ * values, malformed keys, invalid branch names, and stray positionals. Every one
+ * of those is a mistake a caller can make in a generated shell command, and
+ * catching them here means a bad invocation never spawns a process, resolves a
+ * credential, or touches the checkpoint.
+ */
+export function parseConductEpicArgs(argv) {
+    if (argv.includes("-h") || argv.includes("--help")) {
+        return { status: "help", usage: getConductEpicUsage() };
+    }
+    if (argv.length === 0)
+        return parseError("A verb is required.");
+    let verb;
+    let rest;
+    if (argv[0] === "checkpoint") {
+        if (argv[1] !== "set") {
+            return parseError("Unknown verb 'checkpoint " + (argv[1] ?? "") + "'. Expected 'checkpoint set'.");
+        }
+        verb = "checkpoint-set";
+        rest = argv.slice(2);
+    }
+    else if (argv[0] === "init" || argv[0] === "status" || argv[0] === "finish" || argv[0] === "spawn") {
+        verb = argv[0];
+        rest = argv.slice(1);
+    }
+    else {
+        return parseError(`Unknown verb '${argv[0]}'. Expected one of: ${CONDUCT_EPIC_VERBS.join(", ")}.`);
+    }
+    const allowed = VERB_FLAGS[verb];
+    const options = {
+        verb,
+        epicKey: "",
+        tickets: [],
+        fields: [],
+        dryRun: false,
+        json: false,
+    };
+    const seen = new Set();
+    let epicKey;
+    for (let i = 0; i < rest.length; i += 1) {
+        const arg = rest[i];
+        if (!arg.startsWith("-")) {
+            if (epicKey !== undefined) {
+                return parseError(`Unexpected argument '${arg}'.`);
+            }
+            epicKey = arg;
+            continue;
+        }
+        if (!allowed.includes(arg)) {
+            return parseError(`Unknown flag '${arg}' for '${verbLabel(verb)}'.`);
+        }
+        // `--field` is the one repeatable flag; everything else is a singleton.
+        if (arg !== "--field") {
+            if (seen.has(arg))
+                return parseError(`Duplicate flag '${arg}'.`);
+            seen.add(arg);
+        }
+        switch (arg) {
+            case "--dry-run":
+                options.dryRun = true;
+                break;
+            case "--json":
+                options.json = true;
+                break;
+            case "--field": {
+                const name = rest[i + 1];
+                const value = rest[i + 2];
+                if (name === undefined || value === undefined) {
+                    return parseError("--field requires a name and a value.");
+                }
+                options.fields.push({ name, value });
+                i += 2;
+                break;
+            }
+            default: {
+                const value = rest[i + 1];
+                if (value === undefined)
+                    return parseError(`${arg} requires a value.`);
+                i += 1;
+                const assigned = assignFlagValue(options, arg, value);
+                if (assigned !== null)
+                    return parseError(assigned);
+            }
+        }
+    }
+    if (epicKey === undefined)
+        return parseError(`'${verbLabel(verb)}' requires an <EPIC> key.`);
+    if (!CONDUCT_EPIC_KEY_PATTERN.test(epicKey)) {
+        return parseError(`Invalid epic key '${epicKey}'. Expected the form PROJ-123.`);
+    }
+    options.epicKey = epicKey;
+    const missing = requiredFlagError(options);
+    if (missing !== null)
+        return parseError(missing);
+    return { status: "ok", options };
+}
+/** Human label for a verb in an error message. */
+function verbLabel(verb) {
+    return verb === "checkpoint-set" ? "checkpoint set" : verb;
+}
+/** Apply one value-taking flag, returning an error message or `null`. */
+function assignFlagValue(options, flag, value) {
+    switch (flag) {
+        case "--tickets": {
+            const keys = value
+                .split(",")
+                .map((k) => k.trim())
+                .filter((k) => k.length > 0);
+            if (keys.length === 0)
+                return "--tickets requires at least one ticket key.";
+            for (const key of keys) {
+                if (!CONDUCT_EPIC_KEY_PATTERN.test(key)) {
+                    return `Invalid ticket key '${key}' in --tickets. Expected the form PROJ-123.`;
+                }
+            }
+            if (new Set(keys).size !== keys.length)
+                return "--tickets must not repeat a ticket key.";
+            options.tickets = keys;
+            return null;
+        }
+        case "--ticket": {
+            if (!CONDUCT_EPIC_KEY_PATTERN.test(value)) {
+                return `Invalid ticket key '${value}'. Expected the form PROJ-123.`;
+            }
+            options.ticket = value;
+            return null;
+        }
+        case "--base-branch": {
+            const reason = validateBranchName(value);
+            if (reason)
+                return `Invalid --base-branch value: ${reason}`;
+            options.baseBranch = value;
+            return null;
+        }
+        case "--checkpoint-path":
+            if (value.trim().length === 0)
+                return "--checkpoint-path requires a path.";
+            options.checkpointPath = value;
+            return null;
+        case "--prompt-file":
+            if (value.trim().length === 0)
+                return "--prompt-file requires a path.";
+            options.promptFile = value;
+            return null;
+        case "--agent":
+            if (!CONDUCT_EPIC_AGENTS.includes(value)) {
+                return `Unsupported agent '${value}'. Expected one of: ${CONDUCT_EPIC_AGENTS.join(", ")}`;
+            }
+            options.agent = value;
+            return null;
+        case "--journal":
+            options.journal = value;
+            return null;
+        default:
+            return `Unknown flag '${flag}'.`;
+    }
+}
+/** Verb-specific required-flag checks. */
+function requiredFlagError(options) {
+    if (options.verb === "init" && options.tickets.length === 0) {
+        return "init requires --tickets K1,K2,...";
+    }
+    if (options.verb === "status" && !options.json) {
+        return "status requires --json.";
+    }
+    if (options.verb === "checkpoint-set") {
+        if (options.ticket === undefined)
+            return "checkpoint set requires --ticket <KEY>.";
+        if (options.fields.length === 0 && options.journal === undefined) {
+            return "checkpoint set requires at least one --field or --journal.";
+        }
+    }
+    if (options.verb === "spawn") {
+        if (options.ticket === undefined)
+            return "spawn requires --ticket <KEY>.";
+        if (options.promptFile === undefined)
+            return "spawn requires --prompt-file <path>.";
+    }
+    return null;
+}
+// ---------------------------------------------------------------------------
+// Output discipline
+// ---------------------------------------------------------------------------
+/**
+ * Emit one success result.
+ *
+ * With `--json`, stdout carries EXACTLY one JSON object and every human line is
+ * diverted to stderr — including the `announced:` line, so a caller parsing
+ * stdout never has to strip narration.
+ */
+function emitSuccess(deps, json, payload, humanLines = []) {
+    if (json) {
+        for (const line of humanLines)
+            deps.errorLog(line);
+        deps.log(JSON.stringify(payload, null, 2));
+    }
+    else {
+        for (const line of humanLines)
+            deps.log(line);
+    }
+    return 0;
+}
+/**
+ * Emit one failure. Reasons go to stderr as concise lines; with `--json`, stdout
+ * still carries exactly one object, so a caller can parse a failure the same way
+ * it parses a success.
+ */
+function emitFailure(deps, json, reasons, payload = {}) {
+    for (const reason of reasons)
+        deps.errorLog(reason);
+    if (json) {
+        deps.log(JSON.stringify({ ok: false, ...payload, failures: reasons }, null, 2));
+    }
+    return 1;
+}
+// ---------------------------------------------------------------------------
+// Shared helpers
+// ---------------------------------------------------------------------------
+/** The epic's own branch name. Fixed by contract; never operator-supplied. */
+function epicBranchFor(epicKey) {
+    return `epic/${epicKey}`;
+}
+/** Resolve the checkpoint path from `--checkpoint-path` or the default. */
+function resolveCheckpointPath(deps, repoName, epicKey, override) {
+    if (override !== undefined)
+        return path.resolve(override);
+    return resolveConductEpicCheckpointPath(repoName, epicKey, {
+        env: deps.env,
+        homedir: deps.homedir,
+    });
+}
+/**
+ * The lock seams built from the injected deps.
+ *
+ * Exported so a test can drive concurrent acquisitions through the exact bridge
+ * every mutating verb uses — the production default in `lock.ts` is never
+ * reached from here, so this bridge is what the mutual-exclusion guarantee
+ * actually rests on.
+ */
+export function buildConductEpicLockSeams(deps) {
+    return {
+        readFile: (filePath) => deps.fs.readFile(filePath),
+        removeFile: (filePath) => deps.fs.unlink(filePath),
+        mkdir: (dirPath, options) => deps.fs.mkdir(dirPath, options),
+        isProcessAlive: deps.isProcessAlive,
+        // The atomic exclusive-create primitive itself, not an exists-then-write
+        // pair: contention must surface as an EEXIST rejection from a single
+        // syscall, which is the whole mutual-exclusion signal.
+        writeFileExclusive: (filePath, data) => deps.fs.writeFileExclusive(filePath, data, { mode: 0o600 }),
+    };
+}
+/** This invocation's lock identity. */
+function lockRequest(deps) {
+    return {
+        ownerPid: deps.pid,
+        host: deps.hostname(),
+        acquiredAt: deps.now().toISOString(),
+    };
+}
+/**
+ * Resolve the repository name for PATH derivation, independent of credentials.
+ *
+ * Falls back to `"unknown"` only when the identity genuinely cannot be resolved
+ * from `BAPI_REPO_NAME` or `.bridge/config` — at which point no checkpoint could
+ * have been written under a real name either, so the two agree.
+ */
+async function resolveRepoNameForPath(deps) {
+    try {
+        const result = await deps.resolveRepoName({
+            env: deps.env,
+            cwd: deps.cwd,
+            readFile: (filePath) => deps.fs.readFile(filePath),
+        });
+        if (result.ok)
+            return result.repoName;
+    }
+    catch {
+        /* sanitized: an identity failure degrades to the placeholder below */
+    }
+    return "unknown";
+}
+/** Resolve Bridge access, or a sanitized reason. Never returns the key. */
+async function resolveAccess(deps) {
+    const result = await deps.resolveAccess({
+        env: deps.env,
+        cwd: deps.cwd,
+        homedir: deps.homedir,
+        platform: deps.platform,
+        readFile: (filePath) => deps.fs.readFile(filePath),
+        stat: (filePath) => deps.fs.stat(filePath),
+    });
+    if (result.ok)
+        return { ok: true, access: result.access };
+    return { ok: false, error: `Bridge credentials could not be resolved: ${result.error}` };
+}
+/** Run `git` with list args in the repository working directory. */
+function git(deps, args) {
+    return Promise.resolve(deps.runCommand("git", args, { cwd: deps.cwd }));
+}
+/** The single trimmed line a `git rev-parse`-style command produced, or null. */
+function firstLine(result) {
+    const value = result.stdout.split("\n")[0]?.trim() ?? "";
+    return value.length === 0 ? null : value;
+}
+/** The SHA from `git ls-remote --heads origin <ref>` output, or null. */
+function lsRemoteSha(result) {
+    const line = firstLine(result);
+    if (line === null)
+        return null;
+    const sha = line.split(/\s+/)[0]?.trim() ?? "";
+    return sha.length === 0 ? null : sha;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** Seconds between two ISO timestamps and `now`, clamped at zero. */
+function elapsedSeconds(from, now) {
+    if (from === null)
+        return null;
+    const start = Date.parse(from);
+    if (Number.isNaN(start))
+        return null;
+    return Math.max(0, Math.floor((now.getTime() - start) / 1000));
+}
+/** The in-flight ticket: the FIRST entry that is not `done`. */
+function inFlightTicket(checkpoint) {
+    return checkpoint.tickets.find((ticket) => ticket.status !== "done") ?? null;
+}
+/**
+ * Run every independent `init` check and ACCUMULATE the failures.
+ *
+ * The accumulation is the feature. A first-failure-wins preflight turns a
+ * five-problem environment into five invocations, each revealing one problem,
+ * and the operator fixes them in the order the code happens to check rather than
+ * the order that matters. Checks that genuinely depend on an earlier result
+ * (everything needing credentials, everything needing a base branch) are skipped
+ * with their own recorded failure rather than crashing.
+ *
+ * NOTHING here mutates: no push, no repoint, no checkpoint write, no lock, and
+ * no supervisor-config PUT. The one write this function used to perform — turning
+ * `auto_merge_enabled` on — is returned as {@link ConductEpicInitPreflight.pendingSupervisorConfig}
+ * for the caller to execute on the success path, because a preflight that
+ * accumulates failures must not have already changed a project-wide default by
+ * the time it refuses.
+ */
+export async function collectConductEpicInitPreflight(deps, options) {
+    const failures = [];
+    const announcements = [];
+    const epicBranch = epicBranchFor(options.epicKey);
+    let pendingSupervisorConfig = null;
+    // (1) gh authentication.
+    try {
+        const gh = await deps.runGh(["auth", "status"], { cwd: deps.cwd });
+        if (!gh.ok)
+            failures.push("gh is not authenticated. Run `gh auth login`.");
+    }
+    catch {
+        failures.push("gh could not be run. Install the GitHub CLI and run `gh auth login`.");
+    }
+    // (2) Worktrunk, honoring BAPI_WORKTRUNK_BIN.
+    const worktrunk = resolveWorktrunkBinary(deps.platform, deps.env);
+    try {
+        const probe = await deps.runCommand(worktrunk, ["--version"], { cwd: deps.cwd });
+        if (probe.exitCode !== 0) {
+            failures.push(`Worktrunk ('${worktrunk}') is not available on PATH.`);
+        }
+    }
+    catch {
+        failures.push(`Worktrunk ('${worktrunk}') is not available on PATH.`);
+    }
+    // (3) Bridge credentials.
+    const accessResult = await resolveAccess(deps);
+    const access = accessResult.ok ? accessResult.access : null;
+    if (!accessResult.ok)
+        failures.push(accessResult.error);
+    let baseBranch = options.baseBranch ?? null;
+    let baseSha = null;
+    let epicBranchAlreadyAtBase = false;
+    if (access !== null) {
+        // (4) auto_merge_enabled, and (5) a non-vacuous required-check set.
+        const readiness = await getConductorReadiness(access, deps.fetchImpl);
+        if (!readiness.ok) {
+            failures.push(`Conductor readiness could not be read: ${readiness.error}`);
+        }
+        else if (!readiness.value.supervisor.auto_merge_enabled) {
+            const current = await getEffectiveSupervisorConfig(access, deps.fetchImpl);
+            if (!current.ok) {
+                failures.push(`auto_merge_enabled is not set and the effective supervisor config could not be read: ${current.error}`);
+            }
+            else {
+                // Wholesale upsert: copy every field, flip exactly one. Omitting a field
+                // would reset it to the request model's default.
+                const body = {
+                    teardown_enabled: current.value.teardown_enabled,
+                    auto_rereview_enabled: current.value.auto_rereview_enabled,
+                    max_remediation_attempts: current.value.max_remediation_attempts,
+                    max_remediation_no_progress_attempts: current.value.max_remediation_no_progress_attempts,
+                    worker_liveness_window_seconds: current.value.worker_liveness_window_seconds,
+                    auto_merge_enabled: true,
+                    merge_approval_required: current.value.merge_approval_required,
+                };
+                if (options.dryRun) {
+                    announcements.push(`announced: would enable auto_merge_enabled on the ${access.repoName} project defaults (--dry-run: not sent).`);
+                }
+                else {
+                    // Deferred, not sent. The success announcement is added by
+                    // `runConductEpicInit` only after the PUT actually succeeds, so the
+                    // `announced:` line never claims a settings change that did not happen.
+                    pendingSupervisorConfig = body;
+                }
+            }
+        }
+        // (5) Required checks. `resolveCiChecks` is called EXACTLY ONCE regardless of
+        // the readiness shortcut, because its side effect — warming the
+        // `poll-ci-checks` cache — is what makes the first `status` poll answer at
+        // all. Skipping it when readiness already looks healthy is the bug that
+        // makes tick 1 report `available:false` for no reason.
+        const resolved = await resolveCiChecks(access, undefined, deps.fetchImpl);
+        const resolvedRequired = requiredCheckNamesFromResolve(resolved.ok ? resolved.value : null);
+        if (!readiness.ok) {
+            // Already recorded above; nothing further can be concluded.
+        }
+        else if (readiness.value.supervisor.required_checks_empty) {
+            if (!resolved.ok) {
+                failures.push(`No required CI checks are configured and resolve-ci-checks failed: ${resolved.error}`);
+            }
+            else if (resolvedRequired.length === 0) {
+                failures.push("No required CI checks are configured and resolve-ci-checks returned none. " +
+                    "A done gate with an empty required set passes vacuously.");
+            }
+        }
+        // (6) No active server-side epic run for this key.
+        const runState = await getEpicRunState(access, options.epicKey, deps.fetchImpl);
+        if (runState.ok) {
+            const status = runState.value.epic_run?.status;
+            if (status !== "done" && status !== "abandoned") {
+                failures.push(`A server-side epic run for ${options.epicKey} is ${String(status)}. ` +
+                    "conduct-epic will not drive an epic the v2 reconciler is already conducting.");
+            }
+        }
+        else if (runState.status !== 404) {
+            failures.push(`The epic-run state for ${options.epicKey} could not be read: ${runState.error}`);
+        }
+        // (10) Index-branch override: absent, or this epic's own (a re-init after a
+        // crash). A foreign override is named so the operator knows which epic still
+        // holds the repository's index.
+        const indexBranch = await getIndexBranch(access, deps.fetchImpl);
+        if (!indexBranch.ok) {
+            failures.push(`The indexed-branch state could not be read: ${indexBranch.error}`);
+        }
+        else {
+            const override = indexBranch.value.override;
+            if (override !== null && override.override_branch !== epicBranch) {
+                failures.push(`The repository index is already repointed to '${override.override_branch}' by another epic. ` +
+                    "Run `conduct-epic finish` for that epic first.");
+            }
+            else if (override !== null && baseBranch === null) {
+                // (8) default base: this epic's own override remembers the real original.
+                baseBranch = override.original_base_branch;
+            }
+        }
+        // (8) default base, continued: the configured base branch, then `main`.
+        if (baseBranch === null) {
+            const configured = await getConfigFieldBaseBranch(access, deps.fetchImpl);
+            if (configured.ok && configured.value.base_branch !== null) {
+                baseBranch = configured.value.base_branch;
+            }
+        }
+    }
+    if (baseBranch === null)
+        baseBranch = "main";
+    const branchReason = validateBranchName(baseBranch);
+    if (branchReason) {
+        failures.push(`The resolved base branch is unusable: ${branchReason}`);
+    }
+    else {
+        // (8) The base must exist on origin AFTER a fetch — an epic branch cut from a
+        // stale local ref silently starts the epic behind main.
+        const fetched = await git(deps, ["fetch", "origin", baseBranch]);
+        if (fetched.exitCode !== 0) {
+            failures.push(`git fetch origin ${baseBranch} failed.`);
+        }
+        const tip = await git(deps, ["rev-parse", `refs/remotes/origin/${baseBranch}`]);
+        baseSha = tip.exitCode === 0 ? firstLine(tip) : null;
+        if (baseSha === null) {
+            failures.push(`origin/${baseBranch} does not exist after fetching.`);
+        }
+        // (9) `epic/<EPIC>` must be absent on origin, or already at the base tip.
+        const existing = await git(deps, ["ls-remote", "--heads", "origin", `refs/heads/${epicBranch}`]);
+        if (existing.exitCode !== 0) {
+            failures.push(`git ls-remote could not read origin/${epicBranch}.`);
+        }
+        else {
+            const existingSha = lsRemoteSha(existing);
+            if (existingSha !== null) {
+                if (baseSha !== null && existingSha === baseSha) {
+                    epicBranchAlreadyAtBase = true;
+                }
+                else {
+                    failures.push(`origin/${epicBranch} already exists at a commit other than the ${baseBranch} tip. ` +
+                        "Delete it or finish the previous run before re-initializing.");
+                }
+            }
+        }
+    }
+    // (7) The lock must be free or recoverably dead. Inspected READ-ONLY here;
+    // acquisition happens only after every check passes.
+    const checkpointPath = resolveCheckpointPath(deps, await resolveRepoNameForPath(deps), options.epicKey, options.checkpointPath);
+    const lockState = await inspectConductEpicLock(resolveConductEpicLockPath(checkpointPath), lockRequest(deps), buildConductEpicLockSeams(deps));
+    if (lockState.kind === "live-foreign") {
+        failures.push(`The epic lock is held by live process ${lockState.owner.owner_pid} on ${lockState.owner.host}.`);
+    }
+    else if (lockState.kind === "remote-host") {
+        failures.push(`The epic lock was taken on host ${lockState.owner.host} and cannot be recovered here.`);
+    }
+    else if (lockState.kind === "unknown") {
+        failures.push(`The epic lock is unusable: ${lockState.reason}`);
+    }
+    return {
+        failures,
+        announcements,
+        access,
+        baseBranch,
+        baseSha,
+        epicBranchAlreadyAtBase,
+        pendingSupervisorConfig,
+    };
+}
+/** Extract required check NAMES from a `resolve-ci-checks` soft envelope. */
+function requiredCheckNamesFromResolve(value) {
+    if (!isRecord(value))
+        return [];
+    const detail = value["detail"];
+    if (!isRecord(detail))
+        return [];
+    const checks = detail["checks"];
+    if (!Array.isArray(checks))
+        return [];
+    const names = [];
+    for (const check of checks) {
+        if (!isRecord(check))
+            continue;
+        if (check["required"] !== true)
+            continue;
+        const name = check["name"];
+        if (typeof name === "string" && name.trim().length > 0)
+            names.push(name.trim());
+    }
+    return names;
+}
+/**
+ * `conduct-epic init` — the only verb that provisions.
+ *
+ * Refuses a second run outright: an existing checkpoint means an epic is already
+ * under way, and re-initializing would discard its ticket statuses and counters.
+ * That refusal deliberately applies to a CORRUPT existing checkpoint too — the
+ * bytes may be all that is left of a half-finished run, and overwriting them as
+ * "repair" is worse than making a human look.
+ */
+export async function runConductEpicInit(deps, options) {
+    // Credential resolution is the PREFLIGHT's job (check 3). Probing here as well
+    // would resolve the credential twice and report a failure the preflight is
+    // about to report properly, so `init` reads the access it established instead.
+    const repoName = await resolveRepoNameForPath(deps);
+    const checkpointPath = resolveCheckpointPath(deps, repoName, options.epicKey, options.checkpointPath);
+    const epicBranch = epicBranchFor(options.epicKey);
+    const existing = await readConductEpicCheckpoint(checkpointPath, deps.fs);
+    if (existing.kind !== "missing") {
+        return emitFailure(deps, options.json, [
+            `${options.epicKey} is already initialized: a checkpoint exists at ${checkpointPath}. ` +
+                "Nothing was changed.",
+        ], { epic_key: options.epicKey, checkpoint_path: checkpointPath });
+    }
+    const preflight = await collectConductEpicInitPreflight(deps, options);
+    if (preflight.failures.length > 0) {
+        for (const line of preflight.announcements)
+            deps.errorLog(line);
+        return emitFailure(deps, options.json, preflight.failures, {
+            epic_key: options.epicKey,
+            checkpoint_path: checkpointPath,
+        });
+    }
+    const access = preflight.access;
+    if (access === null || preflight.baseBranch === null || preflight.baseSha === null) {
+        // Unreachable: any of these being absent records a failure above. Guarded so
+        // a future edit cannot turn a missing precondition into a push.
+        return emitFailure(deps, options.json, ["init preflight completed without a usable plan."], {
+            epic_key: options.epicKey,
+        });
+    }
+    // Starts as the preflight's own lines (which in `--dry-run` already include the
+    // would-enable notice) and grows by at most the one success line below.
+    const announcements = [...preflight.announcements];
+    // A function, not a value: the deterministic plan-line ordering is fixed, but
+    // the trailing announcements are only final once the deferred PUT has settled.
+    const describePlan = () => [
+        `epic:       ${options.epicKey}`,
+        `repo:       ${access.repoName}`,
+        `base:       ${preflight.baseBranch} @ ${preflight.baseSha}`,
+        `branch:     ${epicBranch}${preflight.epicBranchAlreadyAtBase ? " (already at the base tip)" : ""}`,
+        `tickets:    ${options.tickets.join(", ")}`,
+        `checkpoint: ${checkpointPath}`,
+        ...announcements,
+    ];
+    if (options.dryRun) {
+        return emitSuccess(deps, options.json, {
+            ok: true,
+            dry_run: true,
+            epic_key: options.epicKey,
+            epic_branch: epicBranch,
+            base_branch: preflight.baseBranch,
+            base_sha: preflight.baseSha,
+            tickets: options.tickets,
+            checkpoint_path: checkpointPath,
+            announcements,
+        }, ["Planned (dry run — nothing was pushed, repointed, or written):", ...describePlan()]);
+    }
+    // The FIRST durable mutation of the whole verb, deliberately placed here: every
+    // preflight check has passed, and nothing has been pushed, repointed, written,
+    // or locked yet. A failed PUT therefore leaves the environment exactly as `init`
+    // found it.
+    if (preflight.pendingSupervisorConfig !== null) {
+        const put = await putSupervisorConfigDefaults(access, preflight.pendingSupervisorConfig, deps.fetchImpl);
+        if (!put.ok) {
+            return emitFailure(deps, options.json, [`auto_merge_enabled could not be enabled: ${put.error}`], {
+                epic_key: options.epicKey,
+                checkpoint_path: checkpointPath,
+            });
+        }
+        announcements.push(`announced: auto_merge_enabled was OFF and has been enabled on the ${access.repoName} project defaults.`);
+    }
+    // Push the epic branch WITHOUT a local checkout: the remote ref is created
+    // directly from the fetched remote-tracking ref, so no local branch, worktree,
+    // or checked-out state is touched.
+    const pushed = await git(deps, [
+        "push",
+        "origin",
+        `refs/remotes/origin/${preflight.baseBranch}:refs/heads/${epicBranch}`,
+    ]);
+    if (pushed.exitCode !== 0) {
+        return emitFailure(deps, options.json, [`Could not create origin/${epicBranch} from the ${preflight.baseBranch} tip.`], {
+            epic_key: options.epicKey,
+        });
+    }
+    const repointed = await repointIndexBranch(access, { branch: epicBranch }, deps.fetchImpl);
+    if (!repointed.ok) {
+        return emitFailure(deps, options.json, [`The repository index could not be repointed to ${epicBranch}: ${repointed.error}`], {
+            epic_key: options.epicKey,
+        });
+    }
+    const request = lockRequest(deps);
+    const checkpoint = createInitialConductEpicCheckpoint({
+        epicKey: options.epicKey,
+        repoName: access.repoName,
+        epicBranch,
+        baseBranchOriginal: preflight.baseBranch,
+        ticketKeys: options.tickets,
+        now: deps.now().toISOString(),
+        lock: { owner_pid: request.ownerPid, host: request.host, acquired_at: request.acquiredAt },
+    });
+    const written = await writeConductEpicCheckpointAtomic(checkpointPath, checkpoint, deps.fs, {
+        skipChmod: deps.platform === "win32",
+    });
+    if (!written.ok) {
+        return emitFailure(deps, options.json, [written.error], { epic_key: options.epicKey });
+    }
+    // The lock is taken LAST: a lock without a checkpoint is a state no verb can
+    // interpret, whereas a checkpoint without a lock is simply an unlocked epic.
+    const lock = await acquireConductEpicLock(resolveConductEpicLockPath(checkpointPath), request, buildConductEpicLockSeams(deps));
+    if (!lock.acquired) {
+        return emitFailure(deps, options.json, [`The epic lock could not be acquired: ${lock.reason}`], {
+            epic_key: options.epicKey,
+            checkpoint_path: checkpointPath,
+        });
+    }
+    return emitSuccess(deps, options.json, {
+        ok: true,
+        epic_key: options.epicKey,
+        epic_branch: epicBranch,
+        base_branch: preflight.baseBranch,
+        base_sha: preflight.baseSha,
+        tickets: options.tickets,
+        checkpoint_path: checkpointPath,
+        lock_path: resolveConductEpicLockPath(checkpointPath),
+        index_repointed: true,
+        announcements,
+    }, ["Initialized:", ...describePlan()]);
+}
+/**
+ * `conduct-epic status <EPIC> --json` — the ONLY evidence a tick acts on.
+ *
+ * Two rules shape everything below:
+ *
+ * - **Every probe fails open.** `gh` down, CI unreachable, the review endpoint
+ *   unavailable — each leaves its sub-object `null`, adds a `probe_errors` entry,
+ *   and the command still exits 0 with a complete object. The loop must be able
+ *   to see its own checkpoint during a GitHub outage.
+ * - **The write allowlist is exactly four fields** (`ci_last_poll`,
+ *   `last_seen_head`, `last_state_change_at`, and a newly discovered
+ *   `ticket.branch`) plus the normal `updated_at`. Everything else is
+ *   observational. In particular the checkpoint stores no "expected head":
+ *   merge identity always comes from a fresh `pr.head_sha`, and a stored
+ *   expectation would be a second source of truth that goes stale.
+ */
+export async function runConductEpicStatus(deps, options) {
+    const accessProbe = await resolveAccess(deps);
+    const repoName = await resolveRepoNameForPath(deps);
+    const checkpointPath = resolveCheckpointPath(deps, repoName, options.epicKey, options.checkpointPath);
+    const read = await readConductEpicCheckpoint(checkpointPath, deps.fs);
+    if (read.kind === "missing") {
+        // Exactly four keys. BAPI-804 asserts this shape to decide whether to run
+        // `init`, so extra narration here would be a contract break.
+        return emitSuccess(deps, options.json, {
+            ok: true,
+            epic_key: options.epicKey,
+            checkpoint_path: checkpointPath,
+            checkpoint_exists: false,
+        });
+    }
+    if (read.kind !== "ok") {
+        return emitFailure(deps, options.json, [read.error], {
+            epic_key: options.epicKey,
+            checkpoint_path: checkpointPath,
+        });
+    }
+    const checkpoint = read.checkpoint;
+    const now = deps.now();
+    const probeErrors = [];
+    const ticket = inFlightTicket(checkpoint);
+    const allDone = ticket === null;
+    // --- worktree + branch discovery -----------------------------------------
+    let discoveredBranch = ticket?.branch ?? null;
+    let worktreePath = null;
+    let worktreeExists = false;
+    if (ticket !== null) {
+        try {
+            const listed = await git(deps, ["worktree", "list", "--porcelain"]);
+            if (listed.exitCode !== 0) {
+                probeErrors.push({ probe: "worktree", reason: "git worktree list failed" });
+            }
+            else {
+                const found = discoverTicketWorktree(parseGitWorktreePorcelain(listed.stdout), ticket.key, ticket.branch);
+                if (found !== null) {
+                    discoveredBranch = found.branch;
+                    worktreePath = found.path;
+                    try {
+                        await deps.fs.stat(found.path);
+                        worktreeExists = true;
+                    }
+                    catch {
+                        worktreeExists = false;
+                    }
+                }
+            }
+        }
+        catch {
+            probeErrors.push({ probe: "worktree", reason: "git worktree list could not be run" });
+        }
+    }
+    // --- git facts ------------------------------------------------------------
+    let branchHead = null;
+    let workerCommits = 0;
+    if (discoveredBranch !== null) {
+        try {
+            const remote = await git(deps, ["ls-remote", "--heads", "origin", discoveredBranch]);
+            if (remote.exitCode !== 0) {
+                probeErrors.push({ probe: "branch_head", reason: "git ls-remote failed" });
+            }
+            else {
+                branchHead = lsRemoteSha(remote);
+            }
+        }
+        catch {
+            probeErrors.push({ probe: "branch_head", reason: "git ls-remote could not be run" });
+        }
+        if (branchHead !== null) {
+            try {
+                await git(deps, ["fetch", "origin"]);
+                const counted = await git(deps, [
+                    "rev-list",
+                    "--count",
+                    `origin/${checkpoint.epic_branch}..origin/${discoveredBranch}`,
+                ]);
+                if (counted.exitCode === 0) {
+                    const parsedCount = Number.parseInt(firstLine(counted) ?? "", 10);
+                    workerCommits = Number.isSafeInteger(parsedCount) && parsedCount >= 0 ? parsedCount : 0;
+                }
+                else {
+                    probeErrors.push({ probe: "worker_commits", reason: "git rev-list failed" });
+                }
+            }
+            catch {
+                probeErrors.push({ probe: "worker_commits", reason: "git rev-list could not be run" });
+            }
+        }
+    }
+    // --- PR state -------------------------------------------------------------
+    let pr = null;
+    if (discoveredBranch !== null) {
+        const probe = await discoverConductEpicPrState(discoveredBranch, {
+            runGh: deps.runGh,
+            cwd: deps.cwd,
+        });
+        if (probe.kind === "ok")
+            pr = probe.pr;
+        else if (probe.kind === "error")
+            probeErrors.push({ probe: "pr", reason: probe.reason });
+    }
+    const mergedExternally = pr?.state === "MERGED" && ticket !== null && ticket.status !== "merged" && ticket.status !== "done";
+    // --- Bridge-backed facts --------------------------------------------------
+    const access = accessProbe.ok ? accessProbe.access : null;
+    if (!accessProbe.ok) {
+        probeErrors.push({ probe: "credentials", reason: accessProbe.error });
+    }
+    let doneGateRequired = null;
+    let reviewOptedIn = false;
+    let reviewSource = null;
+    if (access !== null) {
+        const setup = await getEffectiveSupervisorSetup(access, deps.fetchImpl);
+        if (!setup.ok) {
+            probeErrors.push({ probe: "supervisor_setup", reason: setup.error });
+        }
+        else {
+            const gate = parseDoneGateConfig(setup.value.done_gate_config);
+            for (const condition of gate.conditions) {
+                if (condition.type === "required_ci_checks_green") {
+                    doneGateRequired = [...condition.required_checks];
+                }
+                else if (condition.type === "review_state") {
+                    reviewOptedIn = true;
+                    reviewSource = condition.source;
+                }
+            }
+        }
+    }
+    const ci = access === null || pr?.head_sha == null
+        ? null
+        : await collectCiFacts(deps, access, pr.head_sha, doneGateRequired, checkpoint.ci_last_poll, probeErrors);
+    let review = {
+        opted_in: reviewOptedIn,
+        source: reviewSource,
+        available: null,
+        verdict: null,
+        head_sha: null,
+    };
+    if (access !== null && reviewOptedIn && pr?.number != null) {
+        const status = await getPrReviewStatus(access, pr.number, deps.fetchImpl);
+        if (!status.ok) {
+            probeErrors.push({ probe: "review", reason: status.error });
+            review = { opted_in: true, source: reviewSource, available: null, verdict: null, head_sha: null };
+        }
+        else {
+            review = normalizeReviewStatus(status.value, reviewOptedIn, reviewSource);
+        }
+    }
+    let parse = null;
+    if (access !== null) {
+        const parseStatus = await getParseStatus(access, deps.fetchImpl);
+        if (!parseStatus.ok) {
+            probeErrors.push({ probe: "parse", reason: parseStatus.error });
+        }
+        else {
+            parse = normalizeParseStatus(parseStatus.value);
+        }
+    }
+    // --- lock (inspected, NEVER acquired) ------------------------------------
+    const lockState = await inspectConductEpicLock(resolveConductEpicLockPath(checkpointPath), lockRequest(deps), buildConductEpicLockSeams(deps));
+    const lock = {
+        held_by_me: lockState.kind === "owned",
+        owner_pid: "owner" in lockState ? lockState.owner.owner_pid : null,
+        host: "owner" in lockState ? lockState.owner.host : null,
+        alive: lockState.kind === "owned" || lockState.kind === "live-foreign"
+            ? true
+            : lockState.kind === "dead-local"
+                ? false
+                : null,
+    };
+    // --- the four permitted writes -------------------------------------------
+    let lastSeenHead = ticket?.last_seen_head ?? null;
+    let lastStateChangeAt = ticket?.last_state_change_at ?? null;
+    if (ticket !== null) {
+        const next = { ...checkpoint, tickets: [...checkpoint.tickets] };
+        const index = next.tickets.findIndex((entry) => entry.key === ticket.key);
+        let dirty = false;
+        const updatedTicket = { ...next.tickets[index] };
+        if (updatedTicket.branch === null && discoveredBranch !== null) {
+            updatedTicket.branch = discoveredBranch;
+            dirty = true;
+        }
+        if (branchHead !== null && branchHead !== updatedTicket.last_seen_head) {
+            updatedTicket.last_state_change_at = now.toISOString();
+            updatedTicket.last_seen_head = branchHead;
+            lastSeenHead = branchHead;
+            lastStateChangeAt = updatedTicket.last_state_change_at;
+            dirty = true;
+        }
+        next.tickets[index] = updatedTicket;
+        if (ci?.ci_last_poll) {
+            next.ci_last_poll = ci.ci_last_poll;
+            dirty = true;
+        }
+        if (dirty) {
+            next.updated_at = now.toISOString();
+            const written = await writeConductEpicCheckpointAtomic(checkpointPath, next, deps.fs, {
+                skipChmod: deps.platform === "win32",
+            });
+            if (!written.ok)
+                probeErrors.push({ probe: "checkpoint_write", reason: written.error });
+        }
+    }
+    const payload = {
+        ok: true,
+        epic_key: checkpoint.epic_key,
+        epic_branch: checkpoint.epic_branch,
+        checkpoint_path: checkpointPath,
+        checkpoint_exists: true,
+        all_done: allDone,
+        ticket: ticket === null
+            ? null
+            : {
+                key: ticket.key,
+                status: ticket.status,
+                branch: discoveredBranch,
+                pr_number: ticket.pr_number,
+                spawned_at: ticket.spawned_at,
+                respawns: ticket.respawns,
+                conflict_attempts: ticket.conflict_attempts,
+                counters: { ...ticket.counters },
+            },
+        worktree_path: worktreePath,
+        worktree_exists: worktreeExists,
+        branch_head: branchHead,
+        worker_commits_since_spawn: workerCommits,
+        last_seen_head: lastSeenHead,
+        last_state_change_at: lastStateChangeAt,
+        stale_for_seconds: elapsedSeconds(lastStateChangeAt, now),
+        pr,
+        merged_externally: Boolean(mergedExternally),
+        ci: ci?.ci ?? null,
+        review,
+        parse,
+        deadlines: {
+            soft_seconds: checkpoint.deadlines.soft_seconds,
+            hard_seconds: checkpoint.deadlines.hard_seconds,
+            elapsed_since_spawn_seconds: elapsedSeconds(ticket?.spawned_at ?? null, now),
+        },
+        lock,
+        needs_human: checkpoint.needs_human,
+        probe_errors: probeErrors,
+    };
+    return emitSuccess(deps, options.json, payload);
+}
+/**
+ * Poll CI for `headSha`, warming the resolve cache at most once.
+ *
+ * `poll-ci-checks` answers `available: false` with a "call resolve-ci-checks
+ * first" action until the repository's check config has been cached. That is an
+ * INSTRUCTION, not an error: resolve once, poll once more, and proceed. Resolve
+ * is also what supplies the required names when the done gate does not.
+ */
+async function collectCiFacts(deps, access, headSha, doneGateRequired, previous, probeErrors) {
+    let resolvedValue = null;
+    let resolveCalled = false;
+    const ensureResolved = async () => {
+        if (resolveCalled)
+            return;
+        resolveCalled = true;
+        const resolved = await resolveCiChecks(access, headSha, deps.fetchImpl);
+        if (resolved.ok)
+            resolvedValue = resolved.value;
+        else
+            probeErrors.push({ probe: "ci_resolve", reason: resolved.error });
+    };
+    let polled = await pollCiChecks(access, headSha, deps.fetchImpl);
+    if (!polled.ok) {
+        probeErrors.push({ probe: "ci", reason: polled.error });
+        return null;
+    }
+    if (isRecord(polled.value) && polled.value["available"] === false) {
+        await ensureResolved();
+        polled = await pollCiChecks(access, headSha, deps.fetchImpl);
+        if (!polled.ok) {
+            probeErrors.push({ probe: "ci", reason: polled.error });
+            return null;
+        }
+        // Still unavailable after the one resolve-and-re-poll: CI state is UNKNOWN
+        // (BAPI-814/B3). Falling through would build `{complete: false, checks: []}`,
+        // which is indistinguishable from "polled fine, nothing is green yet" — and
+        // would persist a fingerprint derived from an answer that carried no checks,
+        // so the NEXT poll would compare against it and could report
+        // `stable_across_two_polls`. Return before either happens.
+        if (isRecord(polled.value) && polled.value["available"] === false) {
+            probeErrors.push({
+                probe: "ci",
+                reason: "CI checks are unavailable after resolve-ci-checks and a second poll",
+            });
+            return null;
+        }
+    }
+    const detail = isRecord(polled.value) ? polled.value["detail"] : null;
+    const rawChecks = isRecord(detail) && Array.isArray(detail["checks"]) ? detail["checks"] : [];
+    const checks = rawChecks.filter(isRecord).map((check) => ({
+        name: typeof check["name"] === "string" ? check["name"] : "",
+        status: check["status"] ?? null,
+        conclusion: check["conclusion"] ?? null,
+        required: check["required"] !== false,
+    }));
+    let required = doneGateRequired;
+    if (required === null) {
+        await ensureResolved();
+        required = requiredCheckNamesFromResolve(resolvedValue);
+    }
+    // Sorted so the fingerprint is order-independent: GitHub returns checks in an
+    // arbitrary order, and an order flip must not read as an unstable poll.
+    const requiredSorted = [...new Set(required)].sort();
+    const complete = requiredSorted.length > 0 &&
+        requiredSorted.every((name) => {
+            const raw = rawChecks.filter(isRecord).find((check) => check["name"] === name);
+            return raw !== undefined && raw["complete"] === true && raw["passed"] === true;
+        });
+    const fingerprint = JSON.stringify(checks
+        .filter((check) => requiredSorted.includes(check.name))
+        .map((check) => [check.name, check.status ?? null, check.conclusion ?? null])
+        .sort((a, b) => String(a[0]).localeCompare(String(b[0]))));
+    // Stability is a THREE-part identity: same head, same required set, same
+    // per-check conclusions. A head change resets it, which is the point — a green
+    // result observed twice for an old SHA says nothing about the current one.
+    const stable = previous !== null &&
+        previous.head_sha === headSha &&
+        previous.results_fingerprint === fingerprint &&
+        previous.required.length === requiredSorted.length &&
+        previous.required.every((name, i) => name === requiredSorted[i]);
+    return {
+        ci: {
+            required: requiredSorted,
+            complete,
+            stable_across_two_polls: stable,
+            head_sha: headSha,
+            checks,
+        },
+        ci_last_poll: {
+            head_sha: headSha,
+            required: requiredSorted,
+            results_fingerprint: fingerprint,
+            at: deps.now().toISOString(),
+        },
+    };
+}
+/** Normalize the review-status envelope into the contract's five fields. */
+function normalizeReviewStatus(value, optedIn, source) {
+    const available = isRecord(value) && value["available"] === true;
+    const detail = isRecord(value) && isRecord(value["detail"]) ? value["detail"] : null;
+    let verdict = null;
+    if (detail !== null) {
+        const sticky = detail["sticky_verdict"];
+        const native = detail["review_decision"];
+        if (typeof sticky === "string" && sticky.trim().length > 0) {
+            verdict = normalizeVerdict(sticky);
+        }
+        else if (typeof native === "string" && native.trim().length > 0) {
+            verdict = normalizeVerdict(native);
+        }
+        else {
+            verdict = "unknown";
+        }
+    }
+    return {
+        opted_in: optedIn,
+        source,
+        available: isRecord(value) ? Boolean(value["available"]) : null,
+        // An `available: false` envelope still carries whatever verdict the server
+        // could derive; it is passed through rather than nulled, because the caller
+        // reads `available` to decide how much to trust it.
+        verdict: available || verdict !== null ? verdict : null,
+        head_sha: detail !== null && typeof detail["head_sha"] === "string" ? detail["head_sha"] : null,
+    };
+}
+/** Map every known verdict spelling onto the contract's three values. */
+function normalizeVerdict(raw) {
+    const value = raw.trim().toLowerCase();
+    if (value === "approved")
+        return "approved";
+    if (value === "changes_requested")
+        return "changes_requested";
+    return "unknown";
+}
+/**
+ * Normalize `/jira/parse-status` into the `parse` sub-object.
+ *
+ * The two timestamps are what make the post-merge barrier CAUSAL rather than
+ * coincidental (BAPI-814/A2). `parse.status` is repository-level and stays
+ * `succeeded` from any earlier parse, so "succeeded" alone cannot tell the loop
+ * whether THIS ticket's merge has been indexed; a start or finish strictly later
+ * than the journaled request time can.
+ *
+ * Malformed primitives become `null` rather than being coerced. A blank string
+ * or a number where a timestamp belongs is unavailable evidence, and coercing it
+ * to something truthy would let the barrier pass on a value that means nothing.
+ */
+export function normalizeParseStatus(value) {
+    const known = ["idle", "queued", "in_progress", "succeeded", "failed"];
+    const raw = isRecord(value) ? value["status"] : null;
+    const status = typeof raw === "string" && known.includes(raw) ? raw : null;
+    const optionalText = (key) => {
+        const field = isRecord(value) ? value[key] : null;
+        if (typeof field !== "string")
+            return null;
+        const trimmed = field.trim();
+        return trimmed.length === 0 ? null : trimmed;
+    };
+    return {
+        status,
+        terminal: status === "succeeded" || status === "failed",
+        started_at: optionalText("started_at"),
+        finished_at: optionalText("finished_at"),
+        index_branch_override: optionalText("index_branch_override"),
+    };
+}
+// ---------------------------------------------------------------------------
+// checkpoint set
+// ---------------------------------------------------------------------------
+/**
+ * `conduct-epic checkpoint set` — schema-validated ABSOLUTE edits under the lock.
+ *
+ * Absolute, not relative: the caller reads `status`, computes `n + 1`, and writes
+ * the result. A `--increment` flag would need the CLI to re-read between the
+ * caller's read and its write, which is exactly the lost-update race the lock
+ * exists to prevent.
+ */
+export async function runConductEpicCheckpointSet(deps, options) {
+    // No credential probe here: `checkpoint set` is entirely local — a file read,
+    // a schema-validated edit, and an atomic write. Resolving Bridge access would
+    // make a purely local operation fail-prone during a credential outage.
+    const repoName = await resolveRepoNameForPath(deps);
+    const checkpointPath = resolveCheckpointPath(deps, repoName, options.epicKey, options.checkpointPath);
+    // LOCK FIRST, then read (BAPI-814/B5). Reading before acquiring is a
+    // read-before-lock race: the bytes this call validates and rewrites could be
+    // replaced by another process between the read and the acquisition, and the
+    // write would then silently discard that process's update. Everything that
+    // observes or mutates checkpoint state now happens inside one lock lifetime.
+    const lock = await acquireConductEpicLock(resolveConductEpicLockPath(checkpointPath), lockRequest(deps), buildConductEpicLockSeams(deps));
+    if (!lock.acquired) {
+        return emitFailure(deps, options.json, [`The epic lock could not be acquired: ${lock.reason}`]);
+    }
+    try {
+        const read = await readConductEpicCheckpoint(checkpointPath, deps.fs);
+        if (read.kind === "missing") {
+            return emitFailure(deps, options.json, [
+                `No checkpoint exists at ${checkpointPath}. Run \`conduct-epic init\` first.`,
+            ]);
+        }
+        if (read.kind !== "ok")
+            return emitFailure(deps, options.json, [read.error]);
+        const checkpoint = read.checkpoint;
+        const ticketKey = options.ticket;
+        const index = checkpoint.tickets.findIndex((entry) => entry.key === ticketKey);
+        if (index === -1) {
+            return emitFailure(deps, options.json, [
+                `${ticketKey} is not one of this epic's tickets (${checkpoint.tickets.map((t) => t.key).join(", ")}).`,
+            ]);
+        }
+        const next = {
+            ...checkpoint,
+            counters: { ...checkpoint.counters },
+            tickets: checkpoint.tickets.map((entry) => ({
+                ...entry,
+                counters: { ...entry.counters },
+                journal: [...entry.journal],
+            })),
+        };
+        const now = deps.now().toISOString();
+        const statusBefore = next.tickets[index].status;
+        // Applied in argv order, so a repeated field's LAST assignment wins — the
+        // same rule a shell applies to repeated options.
+        for (const assignment of options.fields) {
+            const applied = applyFieldAssignment(next, index, assignment);
+            if (applied !== null) {
+                return emitFailure(deps, options.json, [applied]);
+            }
+        }
+        if (next.tickets[index].status !== statusBefore) {
+            next.tickets[index].last_state_change_at = now;
+        }
+        if (options.journal !== undefined) {
+            next.tickets[index] = appendTicketJournal(next.tickets[index], options.journal);
+        }
+        next.updated_at = now;
+        const written = await writeConductEpicCheckpointAtomic(checkpointPath, next, deps.fs, {
+            skipChmod: deps.platform === "win32",
+        });
+        if (!written.ok)
+            return emitFailure(deps, options.json, [written.error]);
+        // A concise mutation summary: the FIELD NAMES that changed, never the
+        // checkpoint body, which can carry operator-authored `needs_human` evidence.
+        const changed = options.fields.map((f) => f.name);
+        if (options.journal !== undefined)
+            changed.push("journal");
+        return emitSuccess(deps, options.json, {
+            ok: true,
+            epic_key: checkpoint.epic_key,
+            ticket: ticketKey,
+            updated_fields: changed,
+            checkpoint_path: checkpointPath,
+        }, [`Updated ${ticketKey}: ${changed.join(", ")}`]);
+    }
+    finally {
+        await releaseAcquired(lock);
+    }
+}
+/** Release a lock we acquired, never one a successor replaced it with. */
+async function releaseAcquired(lock) {
+    await lock.release();
+}
+/**
+ * Apply one `--field name value` assignment in place, returning an error message
+ * or `null`.
+ *
+ * Every value is parsed by TYPE, not coerced: `"null"` is only null where null is
+ * a legal value, a counter must be a non-negative integer, a branch must survive
+ * `validateBranchName`, and a status must be in the closed vocabulary. A
+ * permissive parser here would let a typo silently write a nonsense state that
+ * the loop then acts on.
+ */
+function applyFieldAssignment(checkpoint, ticketIndex, assignment) {
+    const { name, value } = assignment;
+    const ticket = checkpoint.tickets[ticketIndex];
+    switch (name) {
+        case "status": {
+            if (!CONDUCT_EPIC_TICKET_STATUSES.includes(value)) {
+                return `Invalid status '${value}'. Expected one of: ${CONDUCT_EPIC_TICKET_STATUSES.join(", ")}`;
+            }
+            ticket.status = value;
+            return null;
+        }
+        case "branch": {
+            if (value === "null") {
+                ticket.branch = null;
+                return null;
+            }
+            const reason = validateBranchName(value);
+            if (reason)
+                return `Invalid branch: ${reason}`;
+            ticket.branch = value;
+            return null;
+        }
+        case "pr_number": {
+            if (value === "null") {
+                ticket.pr_number = null;
+                return null;
+            }
+            const parsed = parseIntegerField(value);
+            if (parsed === null || parsed <= 0)
+                return "pr_number must be a positive integer or null.";
+            ticket.pr_number = parsed;
+            return null;
+        }
+        case "spawned_at": {
+            if (value === "null") {
+                ticket.spawned_at = null;
+                return null;
+            }
+            if (value.trim().length === 0)
+                return "spawned_at must be a non-empty timestamp or null.";
+            ticket.spawned_at = value;
+            return null;
+        }
+        case "respawns":
+        case "conflict_attempts": {
+            const parsed = parseIntegerField(value);
+            if (parsed === null)
+                return `${name} must be a non-negative integer.`;
+            ticket[name] = parsed;
+            return null;
+        }
+        case "counters.sessions_spawned":
+        case "counters.plan_generations_observed":
+        case "counters.merge_attempts": {
+            const parsed = parseIntegerField(value);
+            if (parsed === null)
+                return `${name} must be a non-negative integer.`;
+            const key = name.slice("counters.".length);
+            ticket.counters[key] = parsed;
+            return null;
+        }
+        case "counters.iterations":
+        case "counters.merges": {
+            const parsed = parseIntegerField(value);
+            if (parsed === null)
+                return `${name} must be a non-negative integer.`;
+            checkpoint.counters[name.slice("counters.".length)] = parsed;
+            return null;
+        }
+        case "needs_human": {
+            if (value === "null") {
+                checkpoint.needs_human = null;
+                return null;
+            }
+            let parsed;
+            try {
+                parsed = JSON.parse(value);
+            }
+            catch {
+                return "needs_human must be JSON null or an object with reason, evidence, and at.";
+            }
+            if (parsed === null) {
+                checkpoint.needs_human = null;
+                return null;
+            }
+            if (!isRecord(parsed) ||
+                typeof parsed["reason"] !== "string" ||
+                typeof parsed["evidence"] !== "string" ||
+                typeof parsed["at"] !== "string") {
+                return "needs_human must be JSON null or an object with string reason, evidence, and at.";
+            }
+            checkpoint.needs_human = {
+                reason: parsed["reason"],
+                evidence: parsed["evidence"],
+                at: parsed["at"],
+            };
+            return null;
+        }
+        default:
+            return (`Unknown field '${name}'. Ticket fields: ${TICKET_FIELDS.join(", ")}. ` +
+                `Top-level fields: ${TOP_LEVEL_FIELDS.join(", ")}.`);
+    }
+}
+/** Parse a non-negative integer, rejecting `"1.5"`, `"1e3"`, `"0x1"`, and `""`. */
+function parseIntegerField(value) {
+    if (!/^\d+$/.test(value.trim()))
+        return null;
+    const parsed = Number.parseInt(value.trim(), 10);
+    return Number.isSafeInteger(parsed) && parsed >= 0 ? parsed : null;
+}
+// ---------------------------------------------------------------------------
+// spawn
+// ---------------------------------------------------------------------------
+/**
+ * `conduct-epic spawn` — open exactly ONE agent tab for a ticket.
+ *
+ * Respawn and conflict budgets are deliberately NOT enforced here. The caller
+ * owns them: it reads `status`, decides whether another attempt is warranted,
+ * and only then calls `spawn`. Enforcing a budget in both places means two
+ * thresholds that drift, and the one in prose wins by accident.
+ */
+export async function runConductEpicSpawn(deps, options) {
+    // Local-only, like `checkpoint set`: no credential probe. The spawned agent
+    // resolves its own credentials.
+    const repoName = await resolveRepoNameForPath(deps);
+    const checkpointPath = resolveCheckpointPath(deps, repoName, options.epicKey, options.checkpointPath);
+    // LOCK FIRST (BAPI-814/B5). Checkpoint read, ticket validation, worktree
+    // resolution, prompt read, the spawn itself, and the counter write all live
+    // inside one lock lifetime — so no other process can advance the counters
+    // between the read this call validates and the write it performs.
+    const lock = await acquireConductEpicLock(resolveConductEpicLockPath(checkpointPath), lockRequest(deps), buildConductEpicLockSeams(deps));
+    if (!lock.acquired) {
+        return emitFailure(deps, options.json, [`The epic lock could not be acquired: ${lock.reason}`]);
+    }
+    try {
+        const read = await readConductEpicCheckpoint(checkpointPath, deps.fs);
+        if (read.kind === "missing") {
+            return emitFailure(deps, options.json, [
+                `No checkpoint exists at ${checkpointPath}. Run \`conduct-epic init\` first.`,
+            ]);
+        }
+        if (read.kind !== "ok")
+            return emitFailure(deps, options.json, [read.error]);
+        const checkpoint = read.checkpoint;
+        const ticketKey = options.ticket;
+        const index = checkpoint.tickets.findIndex((entry) => entry.key === ticketKey);
+        if (index === -1) {
+            return emitFailure(deps, options.json, [`${ticketKey} is not one of this epic's tickets.`]);
+        }
+        // Resolve the worktree BEFORE reading the prompt and spawning: a tab opened
+        // in the wrong directory does real work in the wrong place.
+        const listed = await git(deps, ["worktree", "list", "--porcelain"]);
+        if (listed.exitCode !== 0) {
+            return emitFailure(deps, options.json, ["git worktree list failed; the ticket worktree could not be resolved."]);
+        }
+        const found = discoverTicketWorktree(parseGitWorktreePorcelain(listed.stdout), ticketKey, checkpoint.tickets[index].branch);
+        if (found === null) {
+            return emitFailure(deps, options.json, [
+                `No worktree was found for ${ticketKey}. Expected a worktree on the ticket's branch, ` +
+                    `feature/${ticketKey}, or feature/${ticketKey}-<slug>.`,
+            ]);
+        }
+        try {
+            await deps.fs.stat(found.path);
+        }
+        catch {
+            return emitFailure(deps, options.json, [`The worktree path for ${ticketKey} is not accessible.`]);
+        }
+        let prompt;
+        try {
+            prompt = await deps.fs.readFile(options.promptFile);
+        }
+        catch {
+            return emitFailure(deps, options.json, [`The prompt file '${options.promptFile}' could not be read.`]);
+        }
+        const spawned = await spawnConductEpicAgentTab({
+            ticketKey,
+            worktreePath: found.path,
+            prompt,
+            agent: options.agent,
+            platform: deps.platform,
+        }, deps.spawnTab);
+        if (!spawned.ok)
+            return emitFailure(deps, options.json, [spawned.error]);
+        // Counters advance only AFTER the tab actually opened. Incrementing first
+        // would let a failed spawn consume the caller's respawn budget.
+        const now = deps.now().toISOString();
+        const next = {
+            ...checkpoint,
+            counters: { ...checkpoint.counters },
+            tickets: checkpoint.tickets.map((entry) => ({
+                ...entry,
+                counters: { ...entry.counters },
+                journal: [...entry.journal],
+            })),
+        };
+        next.tickets[index].branch = found.branch;
+        next.tickets[index].counters.sessions_spawned += 1;
+        next.tickets[index] = appendTicketJournal(next.tickets[index], `${now} spawned ${options.agent ?? "claude"} in ${found.branch}`);
+        next.updated_at = now;
+        const written = await writeConductEpicCheckpointAtomic(checkpointPath, next, deps.fs, {
+            skipChmod: deps.platform === "win32",
+        });
+        if (!written.ok)
+            return emitFailure(deps, options.json, [written.error]);
+        return emitSuccess(deps, options.json, {
+            ok: true,
+            epic_key: checkpoint.epic_key,
+            ticket: ticketKey,
+            branch: found.branch,
+            worktree_path: found.path,
+            sessions_spawned: next.tickets[index].counters.sessions_spawned,
+        }, [`Spawned one agent tab for ${ticketKey} in ${found.path}`]);
+    }
+    finally {
+        await releaseAcquired(lock);
+    }
+}
+// ---------------------------------------------------------------------------
+// finish
+// ---------------------------------------------------------------------------
+/**
+ * `conduct-epic finish` — restore the server's indexed base branch and wind down.
+ *
+ * Restoration uses `restoreIndexBranch(access)` and NOTHING else. The
+ * checkpoint's `base_branch_original` is display-only: the server holds the
+ * durable override row with the true original, and a local copy that drifted
+ * (because the operator changed the repository's base mid-run) would restore the
+ * index to the wrong branch. `{ ok: true, changed: false }` is a success — that
+ * is what a second `finish` sees.
+ */
+export async function runConductEpicFinish(deps, options) {
+    const accessProbe = await resolveAccess(deps);
+    if (!accessProbe.ok)
+        return emitFailure(deps, options.json, [accessProbe.error]);
+    const access = accessProbe.access;
+    const checkpointPath = resolveCheckpointPath(deps, await resolveRepoNameForPath(deps), options.epicKey, options.checkpointPath);
+    const read = await readConductEpicCheckpoint(checkpointPath, deps.fs);
+    if (read.kind === "missing") {
+        return emitFailure(deps, options.json, [`No checkpoint exists at ${checkpointPath}.`]);
+    }
+    if (read.kind !== "ok")
+        return emitFailure(deps, options.json, [read.error]);
+    const checkpoint = read.checkpoint;
+    const lock = await acquireConductEpicLock(resolveConductEpicLockPath(checkpointPath), lockRequest(deps), buildConductEpicLockSeams(deps));
+    if (!lock.acquired) {
+        return emitFailure(deps, options.json, [`The epic lock could not be acquired: ${lock.reason}`]);
+    }
+    const restored = await restoreIndexBranch(access, deps.fetchImpl);
+    if (!restored.ok) {
+        await releaseAcquired(lock);
+        return emitFailure(deps, options.json, [`The repository index could not be restored: ${restored.error}`]);
+    }
+    await releaseAcquired(lock);
+    const summary = {
+        ok: true,
+        epic_key: checkpoint.epic_key,
+        epic_branch: checkpoint.epic_branch,
+        index_restored: true,
+        index_changed: restored.value.changed,
+        current_base_branch: restored.value.current_base_branch,
+        counters: { ...checkpoint.counters },
+        needs_human: checkpoint.needs_human,
+        tickets: checkpoint.tickets.map((ticket) => ({
+            key: ticket.key,
+            status: ticket.status,
+            pr_number: ticket.pr_number,
+            counters: { ...ticket.counters },
+        })),
+    };
+    const humanLines = [
+        `Finished ${checkpoint.epic_key} (${checkpoint.epic_branch})`,
+        `index restore: ${restored.value.changed ? "restored" : "already restored"}`,
+        `iterations: ${checkpoint.counters.iterations}  merges: ${checkpoint.counters.merges}`,
+        ...checkpoint.tickets.map((ticket) => `  ${ticket.key}  ${ticket.status}  PR ${ticket.pr_number ?? "-"}  ` +
+            `spawned ${ticket.counters.sessions_spawned}  plans ${ticket.counters.plan_generations_observed}  ` +
+            `merges ${ticket.counters.merge_attempts}`),
+        `needs_human: ${checkpoint.needs_human === null ? "none" : checkpoint.needs_human.reason}`,
+    ];
+    return emitSuccess(deps, options.json, summary, humanLines);
+}
+// ---------------------------------------------------------------------------
+// Entry point
+// ---------------------------------------------------------------------------
+/**
+ * Entry point for the packaged `conduct-epic` subcommand.
+ *
+ * Returns a numeric exit code and never throws for user-facing failure: `0` for
+ * help and success, `1` for everything else with a concise stderr reason.
+ */
+export async function runConductEpicCli(argv, overrides = {}) {
+    const deps = { ...createDefaultConductEpicDeps(), ...overrides };
+    const parsed = parseConductEpicArgs(argv);
+    if (parsed.status === "help") {
+        deps.log(parsed.usage);
+        return 0;
+    }
+    if (parsed.status === "error") {
+        deps.errorLog(parsed.message);
+        // `--json` is parsed alongside the failing token, so a malformed invocation
+        // cannot be trusted to have set it. Failures from the parser are therefore
+        // reported on stderr only, and the exit code carries the outcome.
+        return 1;
+    }
+    const options = parsed.options;
+    switch (options.verb) {
+        case "init":
+            return runConductEpicInit(deps, options);
+        case "status":
+            return runConductEpicStatus(deps, options);
+        case "checkpoint-set":
+            return runConductEpicCheckpointSet(deps, options);
+        case "spawn":
+            return runConductEpicSpawn(deps, options);
+        case "finish":
+            return runConductEpicFinish(deps, options);
+    }
+}