@bridge_gpt/mcp-server 0.2.54 → 0.2.55

package/build/implement-epic/cli.js

@@ -0,0 +1,3158 @@
+/**
+ * The packaged `implement-epic` CLI (BAPI-803).
+ *
+ * `/conduct-epic` (BAPI-804) is prose. (S6 seam: this slash-command mirror is
+ * renamed separately from the packaged `implement-epic` CLI below — S4/BAPI-1080
+ * renames only the packaged positional command.) 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 the
+ * verbs the loop calls and this file's tests pin:
+ *
+ *   init | status | checkpoint set | finish | spawn
+ *   recover | retire | reclaim | catch-up        (index-scope lifecycle)
+ *   scopes                                        (repository-scoped inventory)
+ *
+ * `scopes` (BAPI-963) is the one verb that takes no `<EPIC>` key: it answers
+ * "what does this repository own?", which is not a question about any one epic.
+ *
+ * Design rules that hold across all of them:
+ *
+ * - **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 { 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 { createProductionEpicIntegrationGhRunner, ensureEpicIntegrationPullRequest, formatEpicIntegrationPullRequestOutcome, } from "../epic-integration-pr.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 { bootstrapIndexScope, getConfigFieldBaseBranch, getConductorReadiness, getIndexScopeLifecycle, catchUpIndexScope, getIndexScopeStatus, getEffectiveSupervisorConfig, getEffectiveSupervisorSetup, getEpicRunState, getParseDispatcherHealth, getParseStatus, getPrReviewStatus, heartbeatIndexScope, pollCiChecks, putSupervisorConfigDefaults, reclaimIndexScope, recoverIndexScope, resolveCiChecks, retireIndexScope, } from "./bridge-client.js";
+import { appendTicketJournal, createInitialConductEpicCheckpoint, readConductEpicCheckpoint, resolveConductEpicCheckpointPath, resolveConductEpicLockPath, writeConductEpicCheckpointAtomic, CONDUCT_EPIC_REVIEW_VERDICTLESS_CEILING, 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";
+import { MCP_PACKAGE_NAME } from "../mcp-identity.js";
+import { fetchLatestVersion } from "../cli-release.js";
+import { INDEX_SCOPE_CONFIGURATION_ERROR, validateOptionalIndexScope, } from "../index-scope-contract.js";
+// BAPI-850: the exact-cut protocol, the scope-readiness poll bounds, and the
+// local-git helpers live in ONE shared module that `setup-epic` drives too. This
+// file remains the pilot's owner of the preflight and of how a cut outcome is
+// reported; the cut itself is performed by the shared module.
+import { createExecFileRunCommand, describeScopeBootstrapWindow, firstOutputLine as firstLine, formatScopeBootstrapHeartbeat, lsRemoteSha, normalizeCommitSha, performExactIndexScopeCut, runGit, SCOPE_BOOTSTRAP_MAX_POLLS, SCOPE_BOOTSTRAP_POLL_INTERVAL_MS, SCOPE_BOOTSTRAP_UNREADABLE_STATE, } from "./cut-protocol.js";
+// Re-exported so existing importers of the pilot's normalizer keep compiling.
+export { normalizeCommitSha };
+/** Epic and ticket keys accepted by every verb. */
+export const CONDUCT_EPIC_KEY_PATTERN = /^[A-Z]+-[0-9]+$/;
+/** The verb families. `checkpoint set` is two tokens, one verb. */
+export const CONDUCT_EPIC_VERBS = [
+    "init",
+    "status",
+    "checkpoint set",
+    "finish",
+    "spawn",
+    "recover",
+    "retire",
+    "reclaim",
+    "catch-up",
+    "scopes",
+];
+/** Per-ticket fields `checkpoint set` may assign. */
+const TICKET_FIELDS = [
+    "status",
+    "branch",
+    "pr_number",
+    "spawned_at",
+    "parse_requested_at",
+    "parse_requested_for_sha",
+    "review_verdictless_observations",
+    "review_verdictless_for_sha",
+    "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 = createExecFileRunCommand();
+    const spawner = getDefaultSpawnTerminalTabForPlatform(process.platform);
+    const startTicketsDeps = createDefaultStartTicketsDeps();
+    // Strict enabled-value check (matches `MCP_INTEGRATION === "1"` in
+    // `integration/harness.ts`): only the exact value "1" activates the
+    // fixture, so no broadly truthy ambient environment value can enable it
+    // by accident.
+    const publishedIdentityFixture = process.env[CONDUCT_EPIC_PUBLISHED_IDENTITY_FIXTURE_ENV] === "1"
+        ? CONDUCT_EPIC_PUBLISHED_IDENTITY_FIXTURE
+        : undefined;
+    return {
+        runCommand,
+        runGh: (args, options) => runGhCommand(args, options ?? {}),
+        epicIntegrationGh: createProductionEpicIntegrationGhRunner(),
+        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,
+        sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+        log: (m) => console.log(m),
+        errorLog: (m) => console.error(m),
+        resolveAccess: resolveConductorBridgeApiAccess,
+        resolveLatestPublishedVersion: () => fetchLatestVersion({ fetch: globalThis.fetch }),
+        publishedIdentityFixture,
+        resolveRepoName: resolveRequiredStartTicketsRepoName,
+    };
+}
+// ---------------------------------------------------------------------------
+// Usage + argument parsing
+// ---------------------------------------------------------------------------
+/** User-facing usage text for the packaged `implement-epic` subcommand. */
+export function getConductEpicUsage() {
+    return [
+        "Usage:",
+        `  npx -y ${MCP_PACKAGE_NAME} implement-epic <verb> [flags]`,
+        "",
+        "implement-epic drives EPIC-LEVEL orchestration (a local, index-scope-lifecycle",
+        "loop over an epic's tickets). It is a DIFFERENT flow from the ticket-level",
+        "`implement-ticket` command, which implements one ticket; implement-epic never",
+        "replaces it.",
+        "",
+        "Verbs:",
+        "  init <EPIC> --tickets K1,K2,... [--base-branch <b>] [--checkpoint-path <p>] [--dry-run] [--json]",
+        "      Run the full preflight, then create epic/<EPIC> on origin at the commit the",
+        "      CANONICAL INDEX covers — not the base tip — seed and verify the epic's index",
+        "      scope at that commit, repoint the indexed branch, write the checkpoint, and",
+        "      take the lock. --base-branch selects the base whose history is fetched and",
+        "      recorded; the cut commit is the canonical indexed SHA and is reported",
+        "      separately. init fails closed when the repository has no successful parse.",
+        "      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.",
+        "      status warns about STRANDED scopes only; run `implement-epic scopes` below",
+        "      for the full repository-wide inventory.",
+        "",
+        "  scopes [--json]",
+        "      Repository-scoped, and the ONE verb that takes no <EPIC> key. Lists EVERY",
+        "      index scope this repository owns — live, expired, reclaiming, and",
+        "      reclaimed alike — so a crashed epic is visible without SQL. Read-only:",
+        "      it writes nothing and takes no lease.",
+        "",
+        "  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(", ")}.`,
+        "      Repeat --field to write several in ONE atomic mutation.",
+        "      parse_requested_at / parse_requested_for_sha are ACCEPTED for older",
+        "      checkpoints but no longer written: freshness is read from the scope.",
+        "",
+        "  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.",
+        "",
+        "  recover <EPIC> [--scope <id>] [--checkpoint-path <p>] [--json]",
+        "      Take a NEW ownership generation for a crashed epic's index scope and",
+        "      record the returned fencing epoch locally. Use this instead of SQL when",
+        "      `status` shows a scope whose lease expired. Defaults to the epic's own",
+        "      scope; --scope targets another one (e.g. when the checkpoint is gone).",
+        "",
+        "  retire <EPIC> [--scope <id>] [--checkpoint-path <p>] [--json]",
+        "      Start the scope's retention clock. Deletes NOTHING — the scope stays",
+        "      readable for post-mortem for the whole retention window. Idempotent.",
+        "      `finish` does this for you; this verb is for retiring without finishing.",
+        "",
+        "  catch-up <EPIC> [--scope <id>] [--checkpoint-path <p>] [--json]",
+        "      GUARDED CATCH-UP: replay merges the server never observed, so a scope",
+        "      stranded behind its epic branch can be repaired without waiting for the",
+        "      next ticket to merge. Every replayed commit goes through the SAME AC-10",
+        "      gate a merge webhook would have used — this replays verified merge",
+        "      evidence, it does NOT force the branch into the index, and there is no",
+        "      --force, --override, or skip-guard flag on purpose. A refusal leaves both",
+        "      commit watermarks untouched and schedules no parse. Running it twice",
+        "      leaves the same state as running it once.",
+        "",
+        "  reclaim <EPIC> [--scope <id>] [--override-retention] [--checkpoint-path <p>] [--json]",
+        "      Ask the server to schedule the scope's teardown: three Pinecone",
+        "      namespaces, six parse-table slices, three config rows, and a retained",
+        "      tombstone. Returns as soon as it is SCHEDULED; watch `status` for the",
+        "      result. --override-retention waives only the still-valid-lease and",
+        "      unelapsed-retention waits — an active parse, a held parse lock, a live",
+        "      automation run, or a live epic run still refuse. There is no raw",
+        "      deletion mode.",
+        "",
+        "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"],
+    recover: ["--scope", "--checkpoint-path", "--json"],
+    retire: ["--scope", "--checkpoint-path", "--json"],
+    reclaim: ["--scope", "--override-retention", "--checkpoint-path", "--json"],
+    // BAPI-932. NOTE the flags that are deliberately absent: there is no --force,
+    // no --override, and no --skip-guards, and adding one would defeat the point of
+    // the verb. Catch-up replays commits the SERVER reads through the unchanged
+    // AC-10 gate; it cannot make that gate say yes.
+    "catch-up": ["--scope", "--checkpoint-path", "--json"],
+    // BAPI-963. `--json` ONLY: this verb reads a repository-wide listing, so there
+    // is no checkpoint to point at and no scope to single out. The absence of
+    // --force/--override/--skip-guard here is the same deliberate absence as above.
+    scopes: ["--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" ||
+        argv[0] === "recover" ||
+        argv[0] === "retire" ||
+        argv[0] === "reclaim" ||
+        argv[0] === "catch-up" ||
+        argv[0] === "scopes") {
+        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,
+        overrideRetention: 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 "--override-retention":
+                options.overrideRetention = 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);
+            }
+        }
+    }
+    // BAPI-963: `scopes` is repository-scoped and takes NO positional. Rejecting a
+    // supplied key rather than ignoring it keeps the promise `--help` makes exact —
+    // an operator who types `implement-epic scopes BAPI-1` learns the verb's shape
+    // instead of silently getting a listing that ignored their argument.
+    if (verb === "scopes") {
+        if (epicKey !== undefined) {
+            return parseError(`'scopes' takes no <EPIC> key; it lists every scope this repository owns.`);
+        }
+    }
+    else {
+        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;
+        case "--scope": {
+            // Shape-validated here, before any I/O: a server-minted scope id is a uuid4
+            // hex. Refusing a malformed value at the boundary means a typo never becomes
+            // an authenticated request naming something arbitrary.
+            if (!/^[0-9a-f]{32}$/.test(value)) {
+                return `Invalid --scope value '${value}'. Expected a 32-character index-scope id.`;
+            }
+            options.scope = 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}`;
+}
+/**
+ * Ensure the draft epic-integration PR (BAPI-951), non-fatally. Never throws;
+ * returns the formatted, sanctioned-fields-only outcome for the caller's own
+ * advisory/announcement line.
+ */
+async function ensureEpicIntegrationPrAdvisory(deps, input) {
+    const gh = deps.epicIntegrationGh ?? createProductionEpicIntegrationGhRunner();
+    try {
+        const outcome = await ensureEpicIntegrationPullRequest({
+            epicKey: input.epicKey,
+            epicBranch: input.epicBranch,
+            baseBranch: input.baseBranch,
+            command: input.command,
+            gh,
+            cwd: deps.cwd,
+            requestReady: input.requestReady,
+        });
+        return formatEpicIntegrationPullRequestOutcome(outcome);
+    }
+    catch {
+        return formatEpicIntegrationPullRequestOutcome({ kind: "unavailable", reason: "probe_inconclusive" });
+    }
+}
+/** 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 runGit(cutProtocolDeps(deps), args);
+}
+/** The strict subset of the pilot's deps the shared cut protocol consumes. */
+function cutProtocolDeps(deps) {
+    return {
+        runCommand: deps.runCommand,
+        cwd: deps.cwd,
+        fetchImpl: deps.fetchImpl,
+        errorLog: deps.errorLog,
+    };
+}
+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;
+}
+// ---------------------------------------------------------------------------
+// The published-build identity (BAPI-873)
+// ---------------------------------------------------------------------------
+/**
+ * Hard bound on launching the published package to read its identity. `npx` may
+ * have to download a tarball on a cold cache, so this is generous relative to
+ * the registry lookup — but it is a bound, because a wedged launch must never
+ * stall `init` indefinitely.
+ */
+export const PUBLISHED_IDENTITY_TIMEOUT_MS = 120_000;
+/** The identity shape `--version` emits: 12 lowercase hex, optionally `-dirty`. */
+const PUBLISHED_IDENTITY_PATTERN = /^commit: ([0-9a-f]{12})(-dirty)?$/;
+/** The sentinel a build with no git metadata reports. */
+const PUBLISHED_IDENTITY_UNKNOWN = "unknown";
+/**
+ * Opt-out for the published-identity read, for spawned integration children
+ * ONLY (BAPI-944).
+ *
+ * The required `mcp-integration` CI lane spawns real `implement-epic init`
+ * children, and `readPublishedBuildIdentity` otherwise resolves the npm
+ * `latest` dist-tag and launches it through `npx` — a live registry
+ * dependency inside a lane that is supposed to be hermetic. Naming follows
+ * `INSTALL_REEXEC_SENTINEL` (`install-reexec.ts`); the strict-enabled-value
+ * convention follows `MCP_INTEGRATION` (`integration/harness.ts`). Kept
+ * distinct from `MCP_INTEGRATION` deliberately: that flag gates which test
+ * files run at all, this one gates a single dependency inside them, and
+ * conflating the two would make it impossible to run the integration suite
+ * against a real registry when that is exactly what is under test.
+ */
+export const CONDUCT_EPIC_PUBLISHED_IDENTITY_FIXTURE_ENV = "BAPI_CONDUCTOR_PUBLISHED_IDENTITY_FIXTURE";
+/**
+ * The static clean identity returned when the fixture seam is enabled.
+ *
+ * Non-secret and independent of the current checkout by construction — its
+ * commit is not expected to be present in any local history, so it exercises
+ * the SAME "commit unavailable locally" advisory path a real cold checkout
+ * would hit, rather than a synthesized pass.
+ */
+const CONDUCT_EPIC_PUBLISHED_IDENTITY_FIXTURE = {
+    kind: "known",
+    version: "0.0.0-fixture",
+    commit: "deadbeefcafe",
+    dirty: false,
+};
+/** Human wording for each unavailable category, for the fail-open advisory. */
+export function describePublishedIdentityReason(reason) {
+    switch (reason) {
+        case "registry_unreadable":
+            return "the npm registry could not be read";
+        case "launch_failed":
+            return "the published package could not be launched";
+        case "unreadable_output":
+            return "the published package reported no readable build identity";
+        case "identity_unknown":
+            return "the published build reports an unknown build commit";
+    }
+}
+/**
+ * Read the commit identity embedded in the LATEST PUBLISHED package.
+ *
+ * Two bounded steps: resolve the exact latest version through the shared
+ * registry lookup, then run THAT EXACT VERSION with `--version`. The exactness
+ * matters — invoking a moving `@latest` would read whatever the registry served
+ * at that instant, so the version reported and the version inspected could
+ * differ, and the gate would be comparing an identity to the wrong build.
+ *
+ * Every failure is `unavailable`, never a mismatch: not knowing what was
+ * published is a different fact from knowing it is wrong, and only the second
+ * may block a run.
+ */
+export async function readPublishedBuildIdentity(deps) {
+    // BAPI-944: the fixture short-circuits BOTH the registry resolver and the
+    // `npx` probe below — checked before either is touched, so a spawned
+    // integration child with the sentinel set never reaches the network or the
+    // package manager.
+    if (deps.publishedIdentityFixture !== undefined) {
+        return deps.publishedIdentityFixture;
+    }
+    const resolveVersion = deps.resolveLatestPublishedVersion ?? (() => fetchLatestVersion({ fetch: deps.fetchImpl }));
+    let version;
+    try {
+        version = await resolveVersion();
+    }
+    catch {
+        return { kind: "unavailable", reason: "registry_unreadable" };
+    }
+    if (typeof version !== "string" || version.trim().length === 0) {
+        return { kind: "unavailable", reason: "registry_unreadable" };
+    }
+    const resolvedVersion = version.trim();
+    let probe;
+    try {
+        probe = await deps.runCommand("npx", ["-y", `${MCP_PACKAGE_NAME}@${resolvedVersion}`, "--version"], { cwd: deps.cwd, timeoutMs: PUBLISHED_IDENTITY_TIMEOUT_MS });
+    }
+    catch {
+        return { kind: "unavailable", reason: "launch_failed" };
+    }
+    if (!probe || probe.exitCode !== 0) {
+        return { kind: "unavailable", reason: "launch_failed" };
+    }
+    const lines = String(probe.stdout ?? "")
+        .split("\n")
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0);
+    // The first line is the semver contract `--version` has always emitted. It
+    // must be the version we asked for, or the output does not describe the build
+    // this reader resolved.
+    if (lines[0] !== resolvedVersion) {
+        return { kind: "unavailable", reason: "unreadable_output" };
+    }
+    const commitLine = lines.slice(1).find((line) => line.startsWith("commit:"));
+    if (commitLine === undefined) {
+        return { kind: "unavailable", reason: "unreadable_output" };
+    }
+    if (commitLine === `commit: ${PUBLISHED_IDENTITY_UNKNOWN}`) {
+        return { kind: "unavailable", reason: "identity_unknown" };
+    }
+    const match = PUBLISHED_IDENTITY_PATTERN.exec(commitLine);
+    if (match === null) {
+        return { kind: "unavailable", reason: "unreadable_output" };
+    }
+    return { kind: "known", version: resolvedVersion, commit: match[1], dirty: match[2] !== undefined };
+}
+/**
+ * Decide whether the PUBLISHED build carries the code this epic will be cut at.
+ *
+ * The gate is expressed as CONTAINMENT, not as a version floor and not as an
+ * exact-commit match. "The published build is at least as new as the commit we
+ * are conducting" is the property that actually matters, and it is the property
+ * a version number could never express: the same semver spanned three different
+ * contents, which is why the old floor was unverifiable.
+ *
+ * Blocking and fail-open are separated deliberately. Knowing the published build
+ * is wrong blocks. NOT knowing what was published — a registry outage, a cold
+ * npx launch that failed, a build with no git metadata — is an advisory, because
+ * a network problem must never stop a run.
+ */
+export async function evaluatePublishGate(deps, expectedCommitSha) {
+    if (expectedCommitSha === null) {
+        // The canonical-index check already recorded its own failure; adding a
+        // second one for the same root cause only pads the report.
+        return {
+            failures: [],
+            advisories: [
+                "advisory: the publish gate was not evaluated because no canonical indexed commit is available to check against.",
+            ],
+        };
+    }
+    const expected = normalizeCommitSha(expectedCommitSha);
+    if (expected === null) {
+        return {
+            failures: [
+                "The publish gate cannot be evaluated: the expected commit is not a full 40-character SHA. " +
+                    "Refusing rather than comparing an arbitrary prefix.",
+            ],
+            advisories: [],
+        };
+    }
+    const identity = await readPublishedBuildIdentity(deps);
+    if (identity.kind === "unavailable") {
+        return {
+            failures: [],
+            advisories: [
+                `advisory: the publish gate could not be verified — ${describePublishedIdentityReason(identity.reason)}. ` +
+                    `Initialization is continuing; the published ${MCP_PACKAGE_NAME} build was NOT confirmed to contain ${expected}.`,
+            ],
+        };
+    }
+    if (identity.dirty) {
+        return {
+            failures: [
+                `The published ${MCP_PACKAGE_NAME}@${identity.version} reports build commit ${identity.commit}-dirty. ` +
+                    "A dirty build carries content that no commit represents, so it cannot be verified to contain " +
+                    `${expected}. Publish a build from a clean checkout.`,
+            ],
+            advisories: [],
+        };
+    }
+    // The published SHA must be an object THIS checkout knows about before any
+    // ancestry claim is possible. It is a short SHA, so it cannot be fetched by
+    // name — an unresolvable one is "cannot verify", never "wrong".
+    const present = await git(deps, ["rev-parse", "--verify", "--quiet", `${identity.commit}^{commit}`]);
+    if (present.exitCode !== 0) {
+        return {
+            failures: [],
+            advisories: [
+                `advisory: the published ${MCP_PACKAGE_NAME}@${identity.version} build commit ${identity.commit} ` +
+                    "is not present in this checkout, so the publish gate could not be verified. " +
+                    `Initialization is continuing; fetch origin and confirm that build contains ${expected}.`,
+            ],
+        };
+    }
+    const contains = await git(deps, ["merge-base", "--is-ancestor", expected, identity.commit]);
+    if (contains.exitCode === 0)
+        return { failures: [], advisories: [] };
+    if (contains.exitCode === 1) {
+        return {
+            failures: [
+                `The published ${MCP_PACKAGE_NAME}@${identity.version} was built from ${identity.commit}, ` +
+                    `which does not contain ${expected} — the canonical indexed commit this epic is cut at. ` +
+                    "Publish a build containing that commit before initializing. Since BAPI-945 the " +
+                    "publisher is CI, not a laptop: from a clean, current `main` checkout run " +
+                    "`cd mcp_server && npm version patch`, then `git push origin main` and " +
+                    '`git push origin "mcp-server/v<version>"` — that tag push triggers the ' +
+                    "clean-room release workflow. There is deliberately no --force or --override here.",
+            ],
+            advisories: [],
+        };
+    }
+    return {
+        failures: [],
+        advisories: [
+            `advisory: the publish gate could not be verified — the ancestry of published build commit ` +
+                `${identity.commit} could not be determined locally. Initialization is continuing.`,
+        ],
+    };
+}
+/**
+ * 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 advisories = [];
+    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 cutCommitSha = null;
+    let epicBranchAlreadyAtCut = 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)}. ` +
+                    "implement-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) BAPI-847: there is no repository-wide index-branch override to check
+        // any more. An epic no longer takes the repository's index away from anyone —
+        // it gets its OWN index scope — so two epics running at once is an ordinary
+        // state rather than a conflict a preflight has to detect. The default-base
+        // resolution below therefore never reads a stored "original" branch: nothing
+        // was ever repointed, so the repository's configured base IS the original.
+        // (11) The canonical index must have a usable commit (BAPI-843). This is the
+        // check that inverts the cut order: without a `succeeded` canonical parse
+        // publishing a commit, there is no commit to cut at, and cutting at the base
+        // tip instead is exactly the behavior this replaces. The failure text names
+        // the fix an operator can actually perform.
+        const parseStatus = await getParseStatus(access, deps.fetchImpl);
+        if (!parseStatus.ok) {
+            failures.push(`The canonical parse status could not be read: ${parseStatus.error}`);
+        }
+        else if (parseStatus.value.status !== "succeeded") {
+            failures.push(`The canonical index for ${access.repoName} has no successful parse ` +
+                `(status: ${String(parseStatus.value.status)}). Parse the repository first.`);
+        }
+        else {
+            const indexed = normalizeCommitSha(parseStatus.value.indexed_commit_sha);
+            if (indexed === null) {
+                failures.push(`The canonical index for ${access.repoName} published no commit for its ` +
+                    "last successful parse, so there is no commit to cut at. " +
+                    "Parse the repository first.");
+            }
+            else {
+                cutCommitSha = indexed;
+            }
+        }
+        // (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 is still fetched — local git needs its object history, and the
+        // cut commit is almost always reachable from it — but the base tip is NO
+        // LONGER the branch source (BAPI-843). It is reported for context only.
+        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.`);
+        }
+        if (cutCommitSha !== null) {
+            // (12) The EXACT cut object must be resolvable locally, because `init`
+            // pushes it by SHA. The base fetch usually brings it along; when it did
+            // not — the index covers a commit that is no longer an ancestor of the
+            // base tip — one targeted, NON-MUTATING fetch of that SHA is attempted (it
+            // updates no ref, creates no branch, and checks nothing out). Failing here
+            // is deliberate: it happens before the cut protocol, so nothing has been
+            // held, pushed, or recorded.
+            const present = await git(deps, ["rev-parse", "--verify", "--quiet", `${cutCommitSha}^{commit}`]);
+            if (present.exitCode !== 0) {
+                await git(deps, ["fetch", "origin", cutCommitSha]);
+                const retry = await git(deps, ["rev-parse", "--verify", "--quiet", `${cutCommitSha}^{commit}`]);
+                if (retry.exitCode !== 0) {
+                    failures.push(`The canonical indexed commit ${cutCommitSha} could not be resolved locally ` +
+                        `even after fetching it from origin. Fetch it manually, or re-parse ${access?.repoName ?? "the repository"}.`);
+                    cutCommitSha = null;
+                }
+            }
+        }
+        // (13) BAPI-873: the publish gate. Evaluated HERE — after the cut commit is
+        // known and proven present locally, and still before anything mutates —
+        // because the gate's question is whether the PUBLISHED package (the one
+        // `start-tickets` spawns for every worker) already carries the code this
+        // epic is cut at. A readable mismatch joins `failures` so it is reported
+        // alongside every other readiness problem; an unreadable published identity
+        // becomes an advisory and the run continues.
+        const publishGate = await evaluatePublishGate(deps, cutCommitSha);
+        failures.push(...publishGate.failures);
+        advisories.push(...publishGate.advisories);
+        // (9) `epic/<EPIC>` must be absent on origin, or already at exactly the
+        // canonical indexed commit. An epic branch sitting at ANY other commit still
+        // fails closed — including the base tip, which is no longer special.
+        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 (cutCommitSha !== null && existingSha === cutCommitSha) {
+                    epicBranchAlreadyAtCut = true;
+                }
+                else {
+                    failures.push(`origin/${epicBranch} already exists at ${existingSha}, which is not the ` +
+                        `canonical indexed commit${cutCommitSha ? ` ${cutCommitSha}` : ""}. ` +
+                        "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,
+        advisories,
+        access,
+        baseBranch,
+        baseSha,
+        cutCommitSha,
+        epicBranchAlreadyAtCut,
+        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;
+}
+/**
+ * Drive the scope from a recorded cut to `ready`, or report why it did not.
+ *
+ * Schedules the bootstrap (seed + verifying parse) and then POLLS the control
+ * plane, because readiness is a server-side fact this CLI observes rather than
+ * one it can conclude from its own request succeeding.
+ *
+ * Each terminal state maps to its own operator instruction, and the distinction
+ * matters: `canonical_index_advanced` means re-run `init` (the cut protocol
+ * re-drives at the newer commit), while a verification failure means the seed
+ * itself is wrong and re-cutting would just reproduce it.
+ */
+async function driveIndexScopeBootstrap(deps, access, scopeId, options) {
+    const scheduled = await bootstrapIndexScope(access, { scopeId }, deps.fetchImpl);
+    if (!scheduled.ok) {
+        return { ok: false, failures: [`The index scope could not be seeded: ${scheduled.error}`] };
+    }
+    const sleep = deps.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    // BAPI-963. The seed printed NOTHING for ~30 minutes during the BAPI-943 pilot:
+    // no output, no checkpoint, and a frozen `epic_shadow_index.updated_at`, so a
+    // healthy seed and a wedge looked identical from outside. Because the seed
+    // copies the canonical index wholesale rather than re-parsing, no
+    // `repository_parse_runs` row appears either, removing the last progress
+    // signal. The notice and the per-poll heartbeat below are the fix.
+    //
+    // The MECHANISM (elapsed computation, the line shape, the window description)
+    // lives at the shared `cut-protocol.ts` seam that `setup-epic` also drives, so
+    // v2 can adopt the same progress observation; the RENDERING stays here, on the
+    // pilot's own stderr advisory channel, which is what keeps stdout exactly one
+    // JSON object under `--json`.
+    const startedAtMs = deps.now().getTime();
+    deps.errorLog(describeScopeBootstrapWindow(SCOPE_BOOTSTRAP_POLL_INTERVAL_MS, SCOPE_BOOTSTRAP_MAX_POLLS));
+    let lastState = "unknown";
+    for (let poll = 0; poll < SCOPE_BOOTSTRAP_MAX_POLLS; poll += 1) {
+        await sleep(SCOPE_BOOTSTRAP_POLL_INTERVAL_MS);
+        const status = await getIndexScopeStatus(access, scopeId, deps.fetchImpl);
+        const elapsedMs = deps.now().getTime() - startedAtMs;
+        if (!status.ok) {
+            // A transient read failure is not a verdict: keep polling and let the
+            // bound below be the thing that gives up. The heartbeat reports the fixed
+            // `unreadable` label rather than the raw error, which stays out of a line
+            // that repeats every interval.
+            deps.errorLog(formatScopeBootstrapHeartbeat(elapsedMs, SCOPE_BOOTSTRAP_UNREADABLE_STATE));
+            lastState = `unreadable (${status.error})`;
+            continue;
+        }
+        deps.errorLog(formatScopeBootstrapHeartbeat(elapsedMs, status.value.lifecycle_state));
+        lastState = status.value.lifecycle_state;
+        if (status.value.lifecycle_state === "ready") {
+            if (status.value.indexed_commit_sha !== null &&
+                status.value.indexed_commit_sha === status.value.cut_commit_sha) {
+                return { ok: true, failures: [] };
+            }
+            // `ready` is the server's verdict, and the server only promotes a scope
+            // whose watermark matches. Disagreeing here would mean the control plane
+            // contradicted itself, which is worth refusing rather than proceeding.
+            return {
+                ok: false,
+                failures: [
+                    `Index scope ${scopeId} reports ready but its indexed commit ` +
+                        `(${status.value.indexed_commit_sha ?? "none"}) is not the cut commit ` +
+                        `(${status.value.cut_commit_sha ?? "none"}).`,
+                ],
+            };
+        }
+        if (status.value.lifecycle_state === "failed") {
+            const reason = status.value.last_error ?? "unknown";
+            if (reason === "canonical_index_advanced") {
+                return {
+                    ok: false,
+                    failures: [
+                        `The canonical index advanced before the seed could run, so the scope was not seeded. ` +
+                            `Delete origin/${epicBranchFor(options.epicKey)} and re-run init to cut at the newer commit.`,
+                    ],
+                };
+            }
+            return {
+                ok: false,
+                failures: [
+                    `Index scope ${scopeId} failed verification (${reason}). ` +
+                        "The epic branch and its recorded cut are intact; re-run init to re-drive verification.",
+                ],
+            };
+        }
+    }
+    return {
+        ok: false,
+        failures: [
+            `TIMED OUT: index scope ${scopeId} did not become ready within the bootstrap window ` +
+                `(last observed state: ${lastState}). Re-run init to resume verification.`,
+        ],
+    };
+}
+/**
+ * `implement-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);
+    // BAPI-873: fail-open advisories are reported before the outcome is decided,
+    // on stderr, on both paths — an advisory that only printed on failure would
+    // let a run proceed silently past an unverified publish gate.
+    for (const line of preflight.advisories)
+        deps.errorLog(line);
+    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 ||
+        preflight.cutCommitSha === null) {
+        // Unreachable: any of these being absent records a failure above. Guarded so
+        // a future edit cannot turn a missing precondition into a push — in
+        // particular a missing `cutCommitSha`, which would otherwise be a push at
+        // `undefined`.
+        return emitFailure(deps, options.json, ["init preflight completed without a usable plan."], {
+            epic_key: options.epicKey,
+        });
+    }
+    const cutCommitSha = preflight.cutCommitSha;
+    // 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}`,
+        // The base branch and the cut commit are reported SEPARATELY and never
+        // conflated: the base is context (and the object history git needs), the cut
+        // is the commit the epic actually starts from.
+        `base:       ${preflight.baseBranch} @ ${preflight.baseSha}`,
+        `cut:        ${cutCommitSha} (canonical indexed commit)`,
+        `branch:     ${epicBranch}${preflight.epicBranchAlreadyAtCut ? " (already at the cut commit)" : ""}`,
+        `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,
+            cut_commit_sha: cutCommitSha,
+            tickets: options.tickets,
+            checkpoint_path: checkpointPath,
+            announcements,
+        }, [
+            "Planned (dry run — nothing was pushed, cut, seeded, repointed, or written):",
+            ...describePlan(),
+            `would open a draft pull request ${epicBranch} → ${preflight.baseBranch} for ` +
+                "conductor-ci / gate (BAPI-951; nothing opened in dry-run)",
+        ]);
+    }
+    // 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.`);
+    }
+    // --- The cut protocol (BAPI-843) ----------------------------------------
+    //
+    // Driven by the SHARED exact-cut module (BAPI-850): `cut/begin`, the re-check
+    // of `origin/epic/<EPIC>` under the hold, the exact-SHA push with the
+    // operator's own git, the read-back, `cut/commit`, and the release on every
+    // outcome all happen in `performExactIndexScopeCut`, while the SERVER holds
+    // the canonical repository's parse lock so the commit the index covers cannot
+    // move underneath the ref being created. The pilot creates no `epic_run`, so
+    // it passes no run association.
+    const cutOutcome = await performExactIndexScopeCut(cutProtocolDeps(deps), access, {
+        featureBranch: epicBranch,
+        baseBranch: preflight.baseBranch,
+        candidateCommitSha: cutCommitSha,
+    });
+    if (!cutOutcome.ok) {
+        // `begin` refusals carry the checkpoint path (nothing was leased); every
+        // later refusal names only the epic, exactly as before the extraction.
+        return emitFailure(deps, options.json, cutOutcome.failures, cutOutcome.kind === "begin_refused"
+            ? { epic_key: options.epicKey, checkpoint_path: checkpointPath }
+            : { epic_key: options.epicKey });
+    }
+    // A successful outcome IS the recorded cut: the shared module returns `ok`
+    // only after `cut/commit` accepted the ref, so there is no unrecorded-cut
+    // state to guard against here.
+    const cut = cutOutcome.lease;
+    // --- Seed + verify, only after the hold is released ----------------------
+    const scopeReady = await driveIndexScopeBootstrap(deps, access, cut.scope_id, options);
+    if (!scopeReady.ok) {
+        return emitFailure(deps, options.json, scopeReady.failures, {
+            epic_key: options.epicKey,
+            scope_id: cut.scope_id,
+            checkpoint_path: checkpointPath,
+        });
+    }
+    announcements.push(`announced: index scope ${cut.scope_id} is ready at ${cut.cut_commit_sha}.`);
+    // --- Draft epic-integration PR (BAPI-951) --------------------------------
+    // Only when THIS invocation actually created the branch (`cutOutcome.branchCreated`)
+    // — never on a reused/already-recorded cut, which `init` refuses to reach at all
+    // (an existing checkpoint returns early above). Placed AFTER scope readiness and
+    // BEFORE the checkpoint write, which stays the final mutation.
+    if (cutOutcome.branchCreated) {
+        const formatted = await ensureEpicIntegrationPrAdvisory(deps, {
+            epicKey: options.epicKey,
+            epicBranch,
+            baseBranch: preflight.baseBranch,
+            command: "implement-epic init",
+        });
+        announcements.push(`integration pr: ${JSON.stringify(formatted)}`);
+    }
+    // BAPI-847: `init` used to repoint the REPOSITORY's `base_branch` at the epic
+    // branch here, which is the defect this epic exists to remove — a
+    // repository-wide mutation that every unrelated run then resolved through. The
+    // scope provisioned above already carries the epic branch on its own shadow
+    // config row, so the canonical repository's configuration is never touched and
+    // nothing has to be restored later.
+    //
+    // The checkpoint is still written LAST: it is only correct once the scope has
+    // proven its own coverage.
+    const request = lockRequest(deps);
+    const checkpoint = createInitialConductEpicCheckpoint({
+        epicKey: options.epicKey,
+        repoName: access.repoName,
+        epicBranch,
+        baseBranchOriginal: preflight.baseBranch,
+        // BAPI-844: the server-minted scope from THIS init's cut, recorded so every
+        // later `spawn` declares the scope the epic was actually cut against. It is
+        // stored exactly as returned; nothing local mints, edits, or defaults it.
+        indexScopeId: cut.scope_id,
+        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,
+        cut_commit_sha: cutCommitSha,
+        scope_id: cut.scope_id,
+        tickets: options.tickets,
+        checkpoint_path: checkpointPath,
+        lock_path: resolveConductEpicLockPath(checkpointPath),
+        announcements,
+    }, ["Initialized:", ...describePlan()]);
+}
+/**
+ * `implement-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 five fields** (`ci_last_poll`,
+ *   `last_seen_head`, `last_state_change_at`, a newly discovered
+ *   `ticket.branch`, and — since BAPI-963 — an observed `ticket.pr_number`)
+ *   plus the normal `updated_at`, alongside the scope's fencing epoch. 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.
+ *
+ *   `ticket.pr_number` is a SELF-HEAL, not a new source of truth. `status` already
+ *   derives the PR from GitHub independently, so the checkpoint field was pure
+ *   caller obligation — and when the pilot watcher died during BAPI-943, BAPI-946's
+ *   checkpoint still read `pr_number: null` long after PR #1144 had merged, exactly
+ *   when the driver had lost track and most needed the durable record.
+ */
+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;
+    let reviewDisposition = null;
+    // BAPI-915. An UNREADABLE review policy is not an absent one.
+    //
+    // Before this, an unparseable `done_gate_config` yielded `conditions: []`,
+    // which set `reviewOptedIn = false` — so the pilot read a malformed review
+    // policy as "no review opt-in" and merged on CI alone. That is precisely the
+    // accidental fail-open the Python `INVALID` sentinel exists to prevent, and it
+    // cannot coexist with this ticket's invariant that no malformed input can
+    // select `fail_open`.
+    //
+    // The parser's own `reason` draws the line: `unset` and `disabled` are a
+    // genuine operator opt-out and stay opted out; `malformed` and every
+    // `invalid: …` reason are a policy we could not read, and surface as
+    // opted-in / unavailable / config-invalid so the command's Row 10 handles them
+    // and — having no readable condition — parks under the default disposition.
+    let reviewConfigInvalid = false;
+    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);
+            if (gate.reason === "malformed" || gate.reason.startsWith("invalid:")) {
+                reviewConfigInvalid = true;
+                reviewOptedIn = true;
+                // No readable condition exists, so no disposition may be read from one.
+                // `null` leaves the command's effective default at `park`.
+                reviewSource = null;
+                reviewDisposition = null;
+            }
+            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;
+                    reviewDisposition = condition.verdictless_disposition ?? null;
+                }
+            }
+        }
+    }
+    const ci = access === null || pr?.head_sha == null
+        ? null
+        : await collectCiFacts(deps, access, pr.head_sha, doneGateRequired, checkpoint.ci_last_poll, probeErrors);
+    // BAPI-915: the three additional fields are appended to every shape this
+    // sub-object takes, so a consumer never has to branch on whether they exist.
+    const reviewPolicyFacts = {
+        verdictless_disposition: reviewDisposition,
+        verdictless_ceiling: CONDUCT_EPIC_REVIEW_VERDICTLESS_CEILING,
+        config_invalid: reviewConfigInvalid,
+    };
+    let review = {
+        opted_in: reviewOptedIn,
+        source: reviewSource,
+        available: null,
+        verdict: null,
+        head_sha: null,
+        ...reviewPolicyFacts,
+    };
+    // A config we could not read is reported as opted-in and UNAVAILABLE without
+    // any read being attempted: there is no condition to evaluate a review
+    // against, so `available: false` is the honest answer rather than `null`.
+    if (reviewConfigInvalid) {
+        review = {
+            opted_in: true,
+            source: null,
+            available: false,
+            verdict: null,
+            head_sha: null,
+            ...reviewPolicyFacts,
+        };
+    }
+    else 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,
+                ...reviewPolicyFacts,
+            };
+        }
+        else {
+            review = {
+                ...normalizeReviewStatus(status.value, reviewOptedIn, reviewSource),
+                ...reviewPolicyFacts,
+            };
+        }
+    }
+    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);
+        }
+    }
+    // --- scope (BAPI-845) ----------------------------------------------------
+    // The pilot's freshness evidence, asked DIRECTLY. `parse` above is
+    // repository-level and says nothing about whether *this* merge was indexed,
+    // which is why Row 5 used to reconstruct causality from a request timestamp and
+    // a head SHA. This probe replaces that inference with the scope's own answer:
+    // its lifecycle, both watermarks, and a bounded freshness verdict.
+    //
+    // Absent only when the epic declares no scope — a pilot epic cut before
+    // BAPI-843, or a non-scope run. That is a calm `null` with no probe error,
+    // because there is nothing to report rather than something we failed to read.
+    let scope = null;
+    const declaredScopeId = typeof checkpoint.index_scope_id === "string" && checkpoint.index_scope_id.length > 0
+        ? checkpoint.index_scope_id
+        : null;
+    if (access !== null && declaredScopeId !== null) {
+        const scopeStatus = await getIndexScopeStatus(access, declaredScopeId, deps.fetchImpl);
+        if (!scopeStatus.ok) {
+            probeErrors.push({ probe: "scope", reason: scopeStatus.error });
+            // An unread scope is reported as explicitly `unavailable` rather than left
+            // null: a null could be read as "no scope declared", and that reading would
+            // let the loop proceed past a freshness question it never got an answer to.
+            scope = {
+                scope_id: declaredScopeId,
+                lifecycle_state: null,
+                freshness_status: "unavailable",
+                blocked_reason: null,
+                required_commit_sha: null,
+                indexed_commit_sha: null,
+                last_error: null,
+            };
+        }
+        else {
+            scope = {
+                scope_id: scopeStatus.value.scope_id,
+                lifecycle_state: scopeStatus.value.lifecycle_state,
+                // Fail closed: the client already narrowed an unrecognized value to null,
+                // and null here means "not fresh", never "fine".
+                freshness_status: scopeStatus.value.freshness_status ?? "unavailable",
+                blocked_reason: scopeStatus.value.blocked_reason,
+                required_commit_sha: scopeStatus.value.required_commit_sha,
+                indexed_commit_sha: scopeStatus.value.indexed_commit_sha,
+                last_error: scopeStatus.value.last_error,
+            };
+        }
+    }
+    // --- BAPI-963: what a `pending` scope is actually waiting on ----------------
+    //
+    // Read ONLY when the scope is `pending`, because that is the single state where
+    // "who is going to move this?" is the operator's question. A fresh, blocked, or
+    // failed scope is not waiting on a dispatcher, and issuing the request anyway
+    // would add a round trip to every ordinary tick.
+    //
+    // Fail-open like every other status probe: a failed read records a bounded
+    // probe error and reports `unavailable`, which renders the pre-existing
+    // headline unchanged. Absence is claimed only on positive evidence.
+    let dispatcher = null;
+    if (access !== null && scope !== null && scope.freshness_status === "pending") {
+        const health = await getParseDispatcherHealth(access, deps.fetchImpl);
+        if (health.ok) {
+            dispatcher = health.value;
+        }
+        else {
+            probeErrors.push({ probe: "parse_dispatcher", reason: health.error });
+            dispatcher = {
+                observation: "unavailable",
+                heartbeatState: null,
+                respondingSchedulerRunning: false,
+            };
+        }
+    }
+    // --- BAPI-846: the repository's index scopes, and this epic's heartbeat ---
+    //
+    // TWO distinct jobs, both belonging here rather than in a daemon:
+    //
+    // 1. The LISTING makes a crashed epic's scope discoverable. `scope` above
+    //    answers "is MY index fresh?"; this answers "what index scopes exist, and
+    //    which of them is stranded?" — including expired, reclaiming, and reclaimed
+    //    ones, which is what makes a stale scope actionable without SQL.
+    // 2. The HEARTBEAT renews this epic's lease. The pilot has no long-lived local
+    //    process — `/loop 5m /conduct-epic` re-invokes this command on a timer, so
+    //    the tick loop IS the heartbeat owner, and its cadence matches the default
+    //    heartbeat interval. Beating from here means ownership is renewed exactly
+    //    while a conductor is actively driving the epic, and stops the moment it
+    //    stops ticking, with no untracked daemon and no shutdown contract to get
+    //    wrong.
+    //
+    // Both are probes: a failure lands in `probe_errors` and never fails `status`.
+    let scopes = [];
+    let retentionSeconds = null;
+    let nextLeaseEpoch = checkpoint.index_scope_lease_epoch;
+    if (access !== null) {
+        const listing = await getIndexScopeLifecycle(access, deps.fetchImpl);
+        if (!listing.ok) {
+            probeErrors.push({ probe: "scopes", reason: listing.error });
+        }
+        else {
+            scopes = listing.value.scopes;
+            retentionSeconds = listing.value.retention_seconds;
+        }
+        if (declaredScopeId !== null) {
+            // The epoch comes from the SERVER's listing when it is readable, and from
+            // the checkpoint only as a fallback. Preferring the server is what lets a
+            // conductor keep beating after an operator `recover` superseded its
+            // generation — the alternative is a healthy conductor permanently fenced by
+            // a stale local number.
+            const entry = scopes.find((scope) => scope.scope_id === declaredScopeId);
+            const epoch = entry?.lease_epoch ?? checkpoint.index_scope_lease_epoch;
+            if (epoch !== null && entry?.recoverable !== false) {
+                const beat = await heartbeatIndexScope(access, { scopeId: declaredScopeId, leaseEpoch: epoch }, deps.fetchImpl);
+                if (beat.ok) {
+                    nextLeaseEpoch = beat.value.lease_epoch;
+                }
+                else {
+                    // A rejected beat means fenced or retired. Recorded as a probe error so
+                    // the loop SEES it, not swallowed — but never fatal, because `status`
+                    // is also how an operator finds out they were fenced.
+                    probeErrors.push({ probe: "scope_heartbeat", reason: beat.error });
+                }
+            }
+        }
+    }
+    // --- 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 permitted writes ------------------------------------------------
+    // BAPI-846 added the scope's fencing epoch, refreshed from the server's
+    // authoritative answer; BAPI-963 added the observed `ticket.pr_number`. Every
+    // one of them rides in the SAME atomic write rather than in a second one, so a
+    // tick either records everything it observed or nothing.
+    let lastSeenHead = ticket?.last_seen_head ?? null;
+    let lastStateChangeAt = ticket?.last_state_change_at ?? null;
+    // BAPI-963: what the response PROJECTS for the in-flight ticket. It advances to
+    // the mutated clone only after the atomic write proves durable, so the payload
+    // cannot report a self-healed `pr_number` that never reached disk.
+    let projectedTicket = ticket;
+    const leaseEpochChanged = nextLeaseEpoch !== checkpoint.index_scope_lease_epoch;
+    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;
+        }
+        // BAPI-963: self-heal the PR number from the PR this tick already observed.
+        // `pr.number` is the validated positive-integer-or-null the PR-state parser
+        // produced, so nothing unvalidated reaches the checkpoint. No PR observed
+        // means no write at all — a null observation must never erase a number a
+        // previous tick durably recorded.
+        if (pr !== null && pr.number !== null && pr.number !== updatedTicket.pr_number) {
+            updatedTicket.pr_number = pr.number;
+            dirty = true;
+        }
+        next.tickets[index] = updatedTicket;
+        if (ci?.ci_last_poll) {
+            next.ci_last_poll = ci.ci_last_poll;
+            dirty = true;
+        }
+        if (leaseEpochChanged) {
+            next.index_scope_lease_epoch = nextLeaseEpoch;
+            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 });
+            }
+            else {
+                // Project what was actually PERSISTED. A failed write leaves the response
+                // reporting the original stored value, so the payload never claims a
+                // durable record that is not on disk.
+                projectedTicket = updatedTicket;
+            }
+        }
+    }
+    const payload = {
+        ok: true,
+        epic_key: checkpoint.epic_key,
+        epic_branch: checkpoint.epic_branch,
+        checkpoint_path: checkpointPath,
+        checkpoint_exists: true,
+        all_done: allDone,
+        ticket: projectedTicket === null
+            ? null
+            : projectConductEpicTicketFacts(projectedTicket, discoveredBranch),
+        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),
+        },
+        scope,
+        // BAPI-963: `observed` | `absent` | `unavailable`, or null when the question
+        // did not arise (no scope, no access, or a scope that is not `pending`).
+        parse_dispatcher: dispatcher === null ? null : dispatcher.observation,
+        scope_lease_epoch: nextLeaseEpoch,
+        retention_seconds: retentionSeconds,
+        scopes,
+        lock,
+        needs_human: checkpoint.needs_human,
+        probe_errors: probeErrors,
+    };
+    return emitSuccess(deps, options.json, payload, [
+        ...renderScopeFreshnessLines(scope, dispatcher),
+        ...renderStrandedScopeLines(scopes, declaredScopeId),
+    ]);
+}
+/**
+ * Render the compact freshness unit for the human-readable `status` output.
+ *
+ * There is no dashboard for an index scope and this deliberately does not invent
+ * one — the unit lives on the status surface that already exists. Its shape is
+ * fixed by what an operator needs to decide, in that order:
+ *
+ * 1. **What is happening to the ticket**, first and in plain language. "Waiting
+ *    for index refresh" is the answer to the question actually being asked; a
+ *    lifecycle name is not.
+ * 2. **The lifecycle**, then the two commits on SEPARATE, SEPARATELY LABELLED
+ *    lines. Printing them together, or printing only one, is what let "the commit
+ *    we must index" read as "the commit we indexed".
+ * 3. **The refusal, spelled out**, when there is one. A controlled token is
+ *    precise but not self-explaining, so each is given a sentence — and each
+ *    sentence distinguishes it from a plain parse failure.
+ *
+ * Returns an empty array when the epic declares no scope, so an epic without one
+ * prints exactly what it printed before.
+ */
+/**
+ * Render the STRANDED-SCOPE warning unit for `status` (BAPI-846).
+ *
+ * Deliberately narrow: it names only scopes that are not this epic's and are not
+ * live — the crashed-epic case an operator can act on — and it says nothing at
+ * all when there are none. A full inventory belongs in the JSON payload; the
+ * human output exists to make one specific problem impossible to miss, and a
+ * block that prints on every healthy tick is a block operators stop reading.
+ *
+ * `reclaimed` scopes are omitted: a tombstone is a completed outcome, not
+ * something to act on.
+ */
+function renderStrandedScopeLines(scopes, ownScopeId) {
+    const stranded = scopes.filter((scope) => scope.scope_id !== ownScopeId &&
+        scope.lifecycle_state !== "reclaimed" &&
+        !scope.lease_valid);
+    if (stranded.length === 0)
+        return [];
+    const lines = [
+        `${stranded.length} index scope(s) in this repository have no live lease:`,
+    ];
+    for (const scope of stranded) {
+        const action = scope.recoverable
+            ? "recoverable — `implement-epic recover <EPIC> --scope " + scope.scope_id + "`"
+            : scope.retention_elapsed
+                ? "past retention — the sweep will reclaim it"
+                : `retained until ${scope.retention_deadline ?? "an unknown deadline"}`;
+        lines.push(`  ${scope.scope_id}  ${scope.lifecycle_state ?? "unknown"}  ` +
+            `branch=${scope.feature_branch ?? "unknown"}  ${action}`);
+        if (scope.blockers.length > 0) {
+            lines.push(`    blocked by: ${scope.blockers.join(", ")}`);
+        }
+    }
+    return lines;
+}
+function renderScopeFreshnessLines(scope, dispatcher = null) {
+    if (scope === null)
+        return [];
+    // BAPI-963: `pending` gets a sharper headline when nothing is observed sweeping
+    // the parse queue — "Waiting for index refresh" implies autonomous progress
+    // that, with no dispatcher, is never going to happen. Only a POSITIVE `absent`
+    // observation changes the wording; `observed` and `unavailable` both keep the
+    // original line, because an unavailable read is not evidence of absence.
+    const dispatcherAbsent = dispatcher !== null && dispatcher.observation === "absent";
+    const headline = {
+        fresh: "Index is fresh for this epic.",
+        pending: dispatcherAbsent
+            ? "Waiting for live parse dispatcher."
+            : "Waiting for index refresh.",
+        blocked: "Index refresh is BLOCKED — this advance will not be indexed.",
+        failed: "Index generation FAILED for this scope.",
+        unavailable: "Index freshness is unavailable — treat as not fresh.",
+        unobserved_advance: "The epic branch has advanced BEYOND what this index scope observed.",
+    };
+    // The action line sits immediately under the headline so the output reads
+    // status -> action -> evidence. `unobserved_advance` is the one state that is
+    // actionable rather than merely informative: it is repairable in place.
+    const action = {
+        unobserved_advance: "  Attempting guarded catch-up — replaying the missed merges through the same gate.",
+    };
+    const refusal = {
+        advance_blocked_base_merge: "the base branch was merged forward into the epic branch, which would move the branch's pinned cut point",
+        advance_blocked_unexpected_parent: "the merge commit does not descend directly from the head this scope pinned, so it is not a worker merge",
+        advance_blocked_history_changed: "the pinned head is gone from the branch's history — a force-push or rewrite",
+        advance_blocked_unverifiable: "the advance could not be verified at all, and doubt blocks rather than indexes",
+    };
+    const lines = [
+        headline[scope.freshness_status] ?? "Index freshness is unknown — treat as not fresh.",
+    ];
+    const actionLine = action[scope.freshness_status];
+    if (actionLine !== undefined)
+        lines.push(actionLine);
+    if (scope.freshness_status === "pending" && dispatcherAbsent) {
+        lines.push("  No parse dispatcher was observed. The scheduled refresh cannot begin until", "  the `worker:` dyno is sweeping the parse queue.");
+    }
+    lines.push(`  lifecycle:      ${scope.lifecycle_state ?? "unknown"}`, `  Required commit: ${scope.required_commit_sha ?? "none"}`, `  Indexed commit:  ${scope.indexed_commit_sha ?? "none"}`);
+    if (scope.freshness_status === "unobserved_advance") {
+        lines.push("  Both watermarks agree — at a commit the branch has left behind, which is", "  why this is not `fresh`. Run `implement-epic catch-up <EPIC>` to repair it.");
+    }
+    if (scope.blocked_reason !== null) {
+        lines.push(`  Reason:          ${scope.blocked_reason} — ${refusal[scope.blocked_reason] ?? "the server refused this branch advance"}`);
+        lines.push("  A human must resolve the branch before the epic can continue.");
+    }
+    else if (scope.freshness_status === "failed" && scope.last_error !== null) {
+        lines.push(`  Failure category: ${scope.last_error}`);
+    }
+    return lines;
+}
+/**
+ * Project one checkpoint ticket into the published `ticket` facts.
+ *
+ * `branch` comes from the caller's freshly discovered value rather than the
+ * stored one, matching the rest of the status contract. `journal` is copied so
+ * a consumer of the payload can never reach back into checkpoint state — the
+ * status verb's write allowlist is deliberately narrow, and handing out a live
+ * array reference would be a fifth, undeclared write path.
+ */
+export function projectConductEpicTicketFacts(ticket, discoveredBranch) {
+    return {
+        key: ticket.key,
+        status: ticket.status,
+        branch: discoveredBranch,
+        pr_number: ticket.pr_number,
+        spawned_at: ticket.spawned_at,
+        parse_requested_at: ticket.parse_requested_at,
+        parse_requested_for_sha: ticket.parse_requested_for_sha,
+        review_verdictless_observations: ticket.review_verdictless_observations,
+        review_verdictless_for_sha: ticket.review_verdictless_for_sha,
+        respawns: ticket.respawns,
+        conflict_attempts: ticket.conflict_attempts,
+        counters: { ...ticket.counters },
+        journal: [...ticket.journal],
+    };
+}
+/**
+ * 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"),
+    };
+}
+// ---------------------------------------------------------------------------
+// checkpoint set
+// ---------------------------------------------------------------------------
+/**
+ * `implement-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 \`implement-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 "parse_requested_at":
+        case "parse_requested_for_sha":
+        // BAPI-915: the head the verdictless counter is bound to. Reuses this
+        // nullable-string branch so a tick can clear the binding as deliberately as
+        // it sets it — the counter resets by writing `null` here, not by hand-editing.
+        case "review_verdictless_for_sha": {
+            // The durable half of the post-merge causal barrier (BAPI-825/A2). Both
+            // follow the module's nullable-string convention so a tick can clear them
+            // as deliberately as it sets them — an operator re-running a parse writes
+            // `null` here rather than hand-editing the checkpoint.
+            if (value === "null") {
+                ticket[name] = null;
+                return null;
+            }
+            if (value.trim().length === 0) {
+                return `${name} must be a non-empty string or null.`;
+            }
+            ticket[name] = value;
+            return null;
+        }
+        case "respawns":
+        case "conflict_attempts":
+        // BAPI-915: the head-bound verdictless observation count. Reuses this
+        // non-negative-integer branch, so a negative or non-integer value is
+        // refused by the same parser that guards every other per-ticket counter.
+        case "review_verdictless_observations": {
+            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
+// ---------------------------------------------------------------------------
+/**
+ * `implement-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 \`implement-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.`]);
+        }
+        // BAPI-844: the scope this epic was cut against, read ONLY from the durable
+        // server-returned value on the checkpoint. `process.env.BAPI_INDEX_SCOPE` is
+        // deliberately not consulted — an operator's shell is not the epic's routing
+        // decision, and a pilot ticket has no server-side membership to fall back on,
+        // so an ambient value would silently route this worker's research somewhere
+        // nobody chose. A malformed recorded value stops the spawn with the fixed
+        // configuration error rather than launching an unscoped (canonical) worker.
+        let indexScope;
+        try {
+            indexScope = validateOptionalIndexScope(checkpoint.index_scope_id);
+        }
+        catch {
+            return emitFailure(deps, options.json, [INDEX_SCOPE_CONFIGURATION_ERROR]);
+        }
+        const spawned = await spawnConductEpicAgentTab({
+            ticketKey,
+            worktreePath: found.path,
+            prompt,
+            agent: options.agent,
+            platform: deps.platform,
+            ...(indexScope === undefined ? {} : { indexScope }),
+        }, 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
+// ---------------------------------------------------------------------------
+/**
+ * `implement-epic finish` — retire the epic's index scope and wind down.
+ *
+ * BAPI-847: there is nothing to RESTORE. `init` no longer repoints the
+ * repository's `base_branch`, so `finish` has no repository-wide configuration
+ * to put back — it retires the scope the epic was cut against and reports that
+ * scope's lifecycle outcome and nothing else. The checkpoint's
+ * `base_branch_original` remains display-only: it records which base the epic was
+ * cut from, never a value this verb writes anywhere.
+ */
+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}`]);
+    }
+    // BAPI-846: `finish` RETIRES the epic's index scope; it never deletes it. The
+    // scope keeps every Postgres row and every Pinecone namespace and stays
+    // readable for post-mortem for the whole retention window — deletion is always
+    // the scheduled sweep's or an explicit `reclaim`'s.
+    //
+    // Retirement runs INSIDE the lock, before it is released, so a concurrent
+    // `finish` cannot interleave with it. It calls the retire API and never a
+    // namespace or database deletion, and enough local state is retained (the
+    // checkpoint keeps `index_scope_id` and the epoch) that a failed retirement can
+    // simply be retried with `implement-epic retire`.
+    let scopeRetired = null;
+    let scopeRetirementError = null;
+    if (typeof checkpoint.index_scope_id === "string" && checkpoint.index_scope_id.length > 0) {
+        const retirement = await retireScopeWithEpoch(deps, options, access, {
+            scopeId: checkpoint.index_scope_id,
+            checkpoint,
+            leaseEpoch: checkpoint.index_scope_lease_epoch,
+        });
+        scopeRetired = retirement.ok;
+        if (!retirement.ok)
+            scopeRetirementError = retirement.reason;
+    }
+    await releaseAcquired(lock);
+    // A failed retirement does NOT fail `finish`: the lock is already released and
+    // every other wind-down step has happened, so reporting failure would invite a
+    // re-run that redoes work already done. It is surfaced instead, with the one
+    // command that fixes it — and the scope enters retention on lease expiry
+    // regardless.
+    if (scopeRetirementError !== null) {
+        deps.errorLog(`The index scope was not retired: ${scopeRetirementError}. ` +
+            `Retry with \`implement-epic retire ${checkpoint.epic_key}\`.`);
+    }
+    // --- Draft epic-integration PR (BAPI-951) --------------------------------
+    // Wind-down: ensure the PR exists AND request it be marked ready for human
+    // review. Fail-open, alongside scope retirement — a failure here never rolls
+    // back retirement or fails `finish`, which has already released the lock.
+    const integrationPrAdvisory = await ensureEpicIntegrationPrAdvisory(deps, {
+        epicKey: checkpoint.epic_key,
+        epicBranch: checkpoint.epic_branch,
+        baseBranch: checkpoint.base_branch_original,
+        command: "implement-epic finish",
+        requestReady: true,
+    });
+    deps.errorLog(`Integration PR: ${JSON.stringify(integrationPrAdvisory)}`);
+    const summary = {
+        ok: true,
+        epic_key: checkpoint.epic_key,
+        epic_branch: checkpoint.epic_branch,
+        /** `null` when the epic declares no scope; `false` when retirement failed. */
+        scope_retired: scopeRetired,
+        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 scope:   ${scopeRetired === null
+            ? "none declared"
+            : scopeRetired
+                ? "retired (retention clock started; nothing deleted)"
+                : "NOT retired — see the error above"}`,
+        `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);
+}
+// ---------------------------------------------------------------------------
+// Index-scope lifecycle verbs (BAPI-846)
+// ---------------------------------------------------------------------------
+//
+// `recover`, `retire`, and `reclaim` all reach the authenticated Bridge API and
+// nothing else. There is deliberately no local Pinecone client, no SQL, and no
+// deletion path in this process: the server owns every destructive decision, and
+// a CLI that could delete directly would be a second authority with none of the
+// server's fencing, locking, or blocker checks.
+//
+// Each one persists the server's returned fencing epoch into the protected
+// checkpoint — never into argv or stdout — so a later heartbeat or retirement
+// uses the generation the server actually minted.
+/**
+ * Resolve which scope a lifecycle verb targets.
+ *
+ * `--scope` wins when supplied; otherwise the epic's own scope is read from the
+ * checkpoint. The explicit flag exists for the case the discovery surface is FOR:
+ * a crashed epic whose local checkpoint is gone or was never written, whose scope
+ * an operator found on `status`.
+ */
+async function resolveLifecycleScope(deps, options, checkpointPath) {
+    if (options.scope !== undefined) {
+        // An explicitly named scope carries no local lease state, so any epoch must
+        // come from the server. Reading one from an unrelated checkpoint would send a
+        // generation that belongs to a different scope.
+        return { ok: true, scopeId: options.scope, checkpoint: null, leaseEpoch: null };
+    }
+    const read = await readConductEpicCheckpoint(checkpointPath, deps.fs);
+    if (read.kind === "missing") {
+        return {
+            ok: false,
+            reason: `No checkpoint exists at ${checkpointPath}. ` +
+                "Pass --scope <id> to target a scope directly (see `implement-epic status`).",
+        };
+    }
+    if (read.kind !== "ok")
+        return { ok: false, reason: read.error };
+    const scopeId = read.checkpoint.index_scope_id;
+    if (typeof scopeId !== "string" || scopeId.length === 0) {
+        return { ok: false, reason: `${options.epicKey} declares no index scope.` };
+    }
+    return {
+        ok: true,
+        scopeId,
+        checkpoint: read.checkpoint,
+        leaseEpoch: read.checkpoint.index_scope_lease_epoch,
+    };
+}
+/**
+ * Persist the server's authoritative fencing epoch into the checkpoint.
+ *
+ * Best-effort by design: the lifecycle call already succeeded on the server, and
+ * failing the command because a local cache write failed would report a
+ * successful recovery as a failure. The next `status` re-reads the epoch anyway.
+ */
+async function persistScopeLeaseEpoch(deps, checkpointPath, checkpoint, leaseEpoch) {
+    if (checkpoint === null || leaseEpoch === null)
+        return;
+    if (checkpoint.index_scope_lease_epoch === leaseEpoch)
+        return;
+    const next = {
+        ...checkpoint,
+        index_scope_lease_epoch: leaseEpoch,
+        updated_at: deps.now().toISOString(),
+    };
+    await writeConductEpicCheckpointAtomic(checkpointPath, next, deps.fs, {
+        skipChmod: deps.platform === "win32",
+    });
+}
+/** `implement-epic recover` — take a new ownership generation for a scope. */
+export async function runConductEpicRecover(deps, options) {
+    const accessProbe = await resolveAccess(deps);
+    if (!accessProbe.ok)
+        return emitFailure(deps, options.json, [accessProbe.error]);
+    const checkpointPath = resolveCheckpointPath(deps, await resolveRepoNameForPath(deps), options.epicKey, options.checkpointPath);
+    const target = await resolveLifecycleScope(deps, options, checkpointPath);
+    if (!target.ok)
+        return emitFailure(deps, options.json, [target.reason]);
+    const recovered = await recoverIndexScope(accessProbe.access, { scopeId: target.scopeId }, deps.fetchImpl);
+    if (!recovered.ok) {
+        return emitFailure(deps, options.json, [
+            `The index scope could not be recovered: ${recovered.error}`,
+        ]);
+    }
+    await persistScopeLeaseEpoch(deps, checkpointPath, target.checkpoint, recovered.value.lease_epoch);
+    return emitSuccess(deps, options.json, {
+        ok: true,
+        epic_key: options.epicKey,
+        scope_id: recovered.value.scope_id,
+        lifecycle_state: recovered.value.lifecycle_state,
+        lease_epoch: recovered.value.lease_epoch,
+        lease_expires_at: recovered.value.lease_expires_at,
+    }, [
+        `Recovered index scope ${recovered.value.scope_id}.`,
+        `  lifecycle:    ${recovered.value.lifecycle_state ?? "unknown"}`,
+        `  lease epoch:  ${recovered.value.lease_epoch ?? "unknown"} (previous owners are now fenced)`,
+        `  lease expires: ${recovered.value.lease_expires_at ?? "unknown"}`,
+    ]);
+}
+/**
+ * `implement-epic catch-up` — replay a scope's MISSED merge observations.
+ *
+ * The verb that rescues an ALREADY-stranded epic. Row 5 of `implement-epic` calls
+ * the same endpoint automatically when `status` reports `unobserved_advance`, so
+ * the common case self-heals on a tick; this verb exists for the epic that is
+ * stranded right now and should not have to wait for one.
+ *
+ * It is a guarded catch-up, and the wording here is deliberate everywhere it
+ * appears: it replays verified merge evidence through the server's own AC-10
+ * gate. It cannot force anything, and no flag will ever let it.
+ */
+export async function runConductEpicCatchUp(deps, options) {
+    const accessProbe = await resolveAccess(deps);
+    if (!accessProbe.ok)
+        return emitFailure(deps, options.json, [accessProbe.error]);
+    const checkpointPath = resolveCheckpointPath(deps, await resolveRepoNameForPath(deps), options.epicKey, options.checkpointPath);
+    const target = await resolveLifecycleScope(deps, options, checkpointPath);
+    if (!target.ok)
+        return emitFailure(deps, options.json, [target.reason]);
+    const result = await catchUpIndexScope(accessProbe.access, { scopeId: target.scopeId }, deps.fetchImpl);
+    if (!result.ok) {
+        return emitFailure(deps, options.json, [
+            `The guarded catch-up could not run: ${result.error}`,
+        ]);
+    }
+    const value = result.value;
+    const payload = {
+        ok: value.ok,
+        epic_key: options.epicKey,
+        scope_id: target.scopeId,
+        outcome: value.outcome,
+        reason: value.reason,
+        required_commit_sha: value.required_commit_sha,
+        parse_scheduled: value.parse_scheduled,
+    };
+    // BAPI-963. Catch-up says "a re-parse is scheduled", but NOTHING in the pilot
+    // dispatches it: the queue is swept by the APScheduler job in `worker.py`'s job
+    // set, and the web dyno runs with `DISABLE_SCHEDULER=true`. During the BAPI-943
+    // pilot the first catch-up worked only because an unrelated v2 run's server
+    // happened to be sweeping; had that process stayed dead, the scope would have
+    // sat at `pending` forever with no diagnostic. Read the dispatcher only when a
+    // parse was actually scheduled, so an ordinary catch-up adds no request.
+    let dispatcher = null;
+    if (value.ok && value.parse_scheduled) {
+        const health = await getParseDispatcherHealth(accessProbe.access, deps.fetchImpl);
+        // Advisory: a failed read leaves the successful catch-up successful and simply
+        // says nothing, rather than claiming a dispatcher is missing.
+        if (health.ok)
+            dispatcher = health.value;
+    }
+    const lines = renderCatchUpLines(value, target.scopeId, dispatcher);
+    // --- Draft epic-integration PR (BAPI-951) --------------------------------
+    // Retry point for deferred provisioning: only after a SUCCESSFUL reconciliation
+    // (`value.ok`), and only when the checkpoint carries the epic/base branches this
+    // needs (absent for an explicit `--scope` target with no local checkpoint).
+    if (value.ok && target.checkpoint !== null) {
+        const formatted = await ensureEpicIntegrationPrAdvisory(deps, {
+            epicKey: options.epicKey,
+            epicBranch: target.checkpoint.epic_branch,
+            baseBranch: target.checkpoint.base_branch_original,
+            command: "implement-epic catch-up",
+        });
+        lines.push(`integration pr: ${JSON.stringify(formatted)}`);
+    }
+    return value.ok
+        ? emitSuccess(deps, options.json, payload, lines)
+        : emitFailure(deps, options.json, lines, payload);
+}
+/**
+ * Render one guarded catch-up outcome as distinct, bounded operator lines.
+ *
+ * Every outcome gets its own sentence rather than collapsing into "it did not
+ * work": the three successes call for different next steps (nothing, poll, poll),
+ * and the refusals call for genuinely different human action — a controlled AC-10
+ * block needs the BRANCH fixed, a history-limit refusal needs a fresh scope, and
+ * an `unavailable` needs the provider to come back.
+ */
+function renderCatchUpLines(value, scopeId, dispatcher = null) {
+    const pin = `  Required commit: ${value.required_commit_sha ?? "unknown"}`;
+    // BAPI-963: appended only on POSITIVE evidence that nothing is sweeping. An
+    // `unavailable` observation says nothing, because an advisory that cries wolf
+    // on a network blip is one an operator learns to skip.
+    const waiting = dispatcher !== null && dispatcher.observation === "absent"
+        ? [
+            "  WAITING ON: a live parse dispatcher. No dispatcher was observed, so the",
+            "  scheduled re-parse cannot begin until the `worker:` dyno is sweeping the parse queue.",
+        ]
+        : [];
+    switch (value.outcome) {
+        case "repaired":
+            return [
+                `Guarded catch-up repaired index scope ${scopeId}.`,
+                "  Every replayed merge passed the AC-10 gate.",
+                pin,
+                value.parse_scheduled
+                    ? "  A re-parse is scheduled. Poll `implement-epic status` until freshness reads `fresh`."
+                    : "  No re-parse was scheduled; poll `implement-epic status` for the scope's own state.",
+                ...waiting,
+            ];
+        case "already_current":
+            return [
+                `Index scope ${scopeId} is already current. Nothing was written.`,
+                pin,
+            ];
+        case "parse_scheduled":
+            return [
+                `Index scope ${scopeId} was already pinned at its branch head; no advance was needed.`,
+                value.parse_scheduled
+                    ? "  A re-parse is scheduled. Poll `implement-epic status` until freshness reads `fresh`."
+                    : `  No re-parse was scheduled (${value.reason ?? "the scope is not schedulable right now"}).`,
+                pin,
+                ...waiting,
+            ];
+        case "race_lost":
+            return [
+                `Another observation already owns this scope's target; the catch-up did nothing.`,
+                "  This is the safe outcome of a race, not a failure. Poll `implement-epic status`.",
+                pin,
+            ];
+        case "blocked":
+            return [
+                `Guarded catch-up REFUSED to advance index scope ${scopeId}.`,
+                `  Reason: ${value.reason ?? "the server refused this branch advance"}`,
+                "  Both commit watermarks are unchanged and no parse was scheduled.",
+                "  A human must resolve the branch itself; there is no override.",
+                pin,
+            ];
+        case "history_limit_exceeded":
+            return [
+                `Index scope ${scopeId} is too far behind its epic branch to replay.`,
+                "  Refusing rather than replaying unbounded history. Cut a fresh scope.",
+                pin,
+            ];
+        case "refused_lifecycle":
+            return [
+                `Index scope ${scopeId} cannot take a catch-up in its current state.`,
+                `  Reason: ${value.reason ?? "unknown"}`,
+                pin,
+            ];
+        case "unavailable":
+            return [
+                `The guarded catch-up could not read the epic branch for scope ${scopeId}.`,
+                `  Reason: ${value.reason ?? "unknown"}`,
+                "  An unread branch is never a current one. Retry once the provider recovers.",
+                pin,
+            ];
+        default:
+            return [
+                `The guarded catch-up did not repair index scope ${scopeId}.`,
+                `  Outcome: ${value.outcome ?? "unknown"}  Reason: ${value.reason ?? "unknown"}`,
+                pin,
+            ];
+    }
+}
+/** `implement-epic retire` — start the retention clock; delete nothing. */
+export async function runConductEpicRetire(deps, options) {
+    const accessProbe = await resolveAccess(deps);
+    if (!accessProbe.ok)
+        return emitFailure(deps, options.json, [accessProbe.error]);
+    const checkpointPath = resolveCheckpointPath(deps, await resolveRepoNameForPath(deps), options.epicKey, options.checkpointPath);
+    const target = await resolveLifecycleScope(deps, options, checkpointPath);
+    if (!target.ok)
+        return emitFailure(deps, options.json, [target.reason]);
+    const outcome = await retireScopeWithEpoch(deps, options, accessProbe.access, target);
+    if (!outcome.ok)
+        return emitFailure(deps, options.json, [outcome.reason]);
+    return emitSuccess(deps, options.json, {
+        ok: true,
+        epic_key: options.epicKey,
+        scope_id: outcome.state.scope_id,
+        lifecycle_state: outcome.state.lifecycle_state,
+        lease_epoch: outcome.state.lease_epoch,
+        already_retired: outcome.state.already_retired,
+    }, [
+        outcome.state.already_retired
+            ? `Index scope ${outcome.state.scope_id} was already retired; retention clock unchanged.`
+            : `Retired index scope ${outcome.state.scope_id}. Nothing was deleted.`,
+        "  The scope stays readable for post-mortem for the whole retention window.",
+    ]);
+}
+/**
+ * Retire a scope, resolving the fencing epoch the server currently holds.
+ *
+ * The epoch is the one thing retirement needs and the one thing a local
+ * checkpoint can be wrong about — an operator `recover` (or another conductor)
+ * may have superseded it. So a locally-cached epoch is used only as a first
+ * attempt; on a fencing refusal the CURRENT epoch is read from the server's
+ * listing and the retirement is retried ONCE. That is not a retry loop papering
+ * over a race: retirement is idempotent and the second attempt uses an epoch the
+ * server itself just reported.
+ */
+async function retireScopeWithEpoch(deps, options, access, target) {
+    let epoch = target.leaseEpoch;
+    if (epoch === null) {
+        const current = await lookupScopeEpoch(deps, access, target.scopeId);
+        if (current === null) {
+            return {
+                ok: false,
+                reason: `The current fencing epoch for scope ${target.scopeId} could not be read.`,
+            };
+        }
+        epoch = current;
+    }
+    let retired = await retireIndexScope(access, { scopeId: target.scopeId, leaseEpoch: epoch }, deps.fetchImpl);
+    if (!retired.ok) {
+        const current = await lookupScopeEpoch(deps, access, target.scopeId);
+        if (current !== null && current !== epoch) {
+            epoch = current;
+            retired = await retireIndexScope(access, { scopeId: target.scopeId, leaseEpoch: epoch }, deps.fetchImpl);
+        }
+    }
+    if (!retired.ok) {
+        return { ok: false, reason: `The index scope could not be retired: ${retired.error}` };
+    }
+    const checkpointPath = resolveCheckpointPath(deps, await resolveRepoNameForPath(deps), options.epicKey, options.checkpointPath);
+    await persistScopeLeaseEpoch(deps, checkpointPath, target.checkpoint, retired.value.lease_epoch);
+    return { ok: true, state: retired.value };
+}
+/** Read one scope's CURRENT fencing epoch from the authoritative listing. */
+async function lookupScopeEpoch(deps, access, scopeId) {
+    const listing = await getIndexScopeLifecycle(access, deps.fetchImpl);
+    if (!listing.ok)
+        return null;
+    const entry = listing.value.scopes.find((scope) => scope.scope_id === scopeId);
+    return entry?.lease_epoch ?? null;
+}
+/** `implement-epic reclaim` — ask the server to schedule the scope's teardown. */
+export async function runConductEpicReclaim(deps, options) {
+    const accessProbe = await resolveAccess(deps);
+    if (!accessProbe.ok)
+        return emitFailure(deps, options.json, [accessProbe.error]);
+    const checkpointPath = resolveCheckpointPath(deps, await resolveRepoNameForPath(deps), options.epicKey, options.checkpointPath);
+    const target = await resolveLifecycleScope(deps, options, checkpointPath);
+    if (!target.ok)
+        return emitFailure(deps, options.json, [target.reason]);
+    const scheduled = await reclaimIndexScope(accessProbe.access, { scopeId: target.scopeId, overrideRetention: options.overrideRetention }, deps.fetchImpl);
+    if (!scheduled.ok) {
+        // A refusal names the BLOCKERS the server evaluated, so an operator learns
+        // that a parse is running rather than that "reclaim failed".
+        const blockers = scheduled.blockers ?? [];
+        const reasons = [`The index scope could not be reclaimed: ${scheduled.error}`];
+        if (blockers.length > 0)
+            reasons.push(`  blocked by: ${blockers.join(", ")}`);
+        return emitFailure(deps, options.json, reasons, {
+            epic_key: options.epicKey,
+            scope_id: target.scopeId,
+            blockers,
+        });
+    }
+    return emitSuccess(deps, options.json, {
+        ok: true,
+        epic_key: options.epicKey,
+        scope_id: scheduled.value.scope_id ?? target.scopeId,
+        scheduled: scheduled.value.scheduled,
+    }, [
+        `Scheduled reclamation of index scope ${scheduled.value.scope_id ?? target.scopeId}.`,
+        "  This is SCHEDULED, not done — the teardown waits out Pinecone's",
+        "  consistency window. Run `implement-epic status --json` to see it reach",
+        "  `reclaimed`.",
+    ]);
+}
+/**
+ * `implement-epic scopes` — the repository-wide index-scope inventory (BAPI-963).
+ *
+ * `--help` promised this listing under `status` and no invocation delivered it:
+ * `implement-epic scopes` answered `Unknown verb` and `status <EPIC> --scopes`
+ * answered `Unknown flag`, so an operator asking exactly the question the help
+ * advertised was sent to SQL. The capability already existed — `status` pushes a
+ * stranded-scope warning to stderr — only its documented entry point did not.
+ *
+ * Repository-scoped by construction: it resolves access, reads the lifecycle
+ * listing ONCE, and takes no epic key, no checkpoint, and no lease.
+ */
+export async function runConductEpicScopes(deps, options) {
+    const accessProbe = await resolveAccess(deps);
+    if (!accessProbe.ok)
+        return emitFailure(deps, options.json, [accessProbe.error]);
+    const listing = await getIndexScopeLifecycle(accessProbe.access, deps.fetchImpl);
+    if (!listing.ok) {
+        return emitFailure(deps, options.json, [
+            `The index-scope inventory could not be read: ${listing.error}`,
+        ]);
+    }
+    return emitSuccess(deps, options.json, {
+        ok: true,
+        repo_name: accessProbe.access.repoName,
+        retention_seconds: listing.value.retention_seconds,
+        // The COMPLETE listing, unfiltered. `status` narrows deliberately; this verb
+        // exists because that narrowing is the wrong answer to "what exists?".
+        scopes: listing.value.scopes,
+    }, renderIndexScopeInventoryLines(listing.value.scopes, accessProbe.access.repoName));
+}
+/**
+ * Render the FULL scope inventory for `implement-epic scopes` (BAPI-963).
+ *
+ * Deliberately unlike {@link renderStrandedScopeLines}, which stays narrow: that
+ * one prints only actionable wreckage on a status tick an operator reads every
+ * few minutes, and widening it would turn a warning into wallpaper. This one
+ * answers a question the operator asked on purpose, so it hides nothing —
+ * reclaimed tombstones included, since "it is already gone" is an answer.
+ */
+function renderIndexScopeInventoryLines(scopes, repoName) {
+    if (scopes.length === 0) {
+        return [`${repoName} owns no index scopes.`];
+    }
+    const lines = [`${repoName} owns ${scopes.length} index scope(s):`];
+    for (const scope of scopes) {
+        lines.push(`  ${scope.scope_id}  ${scope.lifecycle_state ?? "unknown"}  ` +
+            `branch=${scope.feature_branch ?? "unknown"}  ` +
+            `lease=${scope.lease_valid ? "live" : "expired"}  ` +
+            `retention=${scope.retention_elapsed ? "elapsed" : (scope.retention_deadline ?? "none")}  ` +
+            `recoverable=${scope.recoverable ? "yes" : "no"}`);
+        if (scope.blockers.length > 0) {
+            lines.push(`    blocked by: ${scope.blockers.join(", ")}`);
+        }
+    }
+    return lines;
+}
+// ---------------------------------------------------------------------------
+// Entry point
+// ---------------------------------------------------------------------------
+/**
+ * Entry point for the packaged `implement-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.
+ *
+ * S4 (BAPI-1080): renamed from `runConductEpicCli` (the packaged positional
+ * command moved from `conduct-epic` to `implement-epic`). Internal
+ * `ConductEpic*` type names, the checkpoint schema, `CONDUCT_EPIC_*`
+ * constants/env vars, and `~/.config/bridge/conduct/` storage paths are
+ * unchanged — they are owned by later slices.
+ */
+export async function runImplementEpicCli(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 "scopes":
+            return runConductEpicScopes(deps, options);
+        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);
+        case "recover":
+            return runConductEpicRecover(deps, options);
+        case "retire":
+            return runConductEpicRetire(deps, options);
+        case "reclaim":
+            return runConductEpicReclaim(deps, options);
+        case "catch-up":
+            return runConductEpicCatchUp(deps, options);
+    }
+}