@bridge_gpt/mcp-server 0.2.41 → 0.2.42

package/build/conduct-epic/cli.js

@@ -29,7 +29,6 @@
  * - **Credentials resolve only through `resolveConductorBridgeApiAccess`** and
  *   never enter argv, stdout, stderr, a journal line, or an error string.
  */
-import { execFile } from "node:child_process";
 import { promises as nodeFs } from "node:fs";
 import os from "node:os";
 import path from "node:path";
@@ -40,15 +39,33 @@ import { runGhCommand } from "../conductor/pr-discovery.js";
 import { getDefaultSpawnTerminalTabForPlatform, detectTerminal, createDefaultStartTicketsDeps, } from "../start-tickets.js";
 import { resolveWorktrunkBinary } from "../start-tickets-prereqs.js";
 import { resolveRequiredStartTicketsRepoName } from "../start-tickets-repo.js";
-import { getConfigFieldBaseBranch, getConductorReadiness, getEffectiveSupervisorConfig, getEffectiveSupervisorSetup, getEpicRunState, getIndexBranch, getParseStatus, getPrReviewStatus, pollCiChecks, putSupervisorConfigDefaults, repointIndexBranch, resolveCiChecks, restoreIndexBranch, } from "./bridge-client.js";
+import { bootstrapIndexScope, getConfigFieldBaseBranch, getConductorReadiness, getIndexScopeLifecycle, getIndexScopeStatus, getEffectiveSupervisorConfig, getEffectiveSupervisorSetup, getEpicRunState, getParseStatus, getPrReviewStatus, heartbeatIndexScope, pollCiChecks, putSupervisorConfigDefaults, reclaimIndexScope, recoverIndexScope, resolveCiChecks, retireIndexScope, } from "./bridge-client.js";
 import { appendTicketJournal, createInitialConductEpicCheckpoint, readConductEpicCheckpoint, resolveConductEpicCheckpointPath, resolveConductEpicLockPath, writeConductEpicCheckpointAtomic, CONDUCT_EPIC_TICKET_STATUSES, } from "./checkpoint-store.js";
 import { acquireConductEpicLock, inspectConductEpicLock, isConductEpicLockOwnerAlive, } from "./lock.js";
 import { discoverConductEpicPrState, discoverTicketWorktree, parseGitWorktreePorcelain, } from "./pr-state.js";
 import { spawnConductEpicAgentTab, CONDUCT_EPIC_AGENTS, } from "./spawn.js";
+import { MCP_PACKAGE_NAME } from "../mcp-identity.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, firstOutputLine as firstLine, lsRemoteSha, normalizeCommitSha, performExactIndexScopeCut, runGit, SCOPE_BOOTSTRAP_MAX_POLLS, SCOPE_BOOTSTRAP_POLL_INTERVAL_MS, } 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 five verb families. `checkpoint set` is two tokens, one verb. */
-export const CONDUCT_EPIC_VERBS = ["init", "status", "checkpoint set", "finish", "spawn"];
+export const CONDUCT_EPIC_VERBS = [
+    "init",
+    "status",
+    "checkpoint set",
+    "finish",
+    "spawn",
+    "recover",
+    "retire",
+    "reclaim",
+];
 /** Per-ticket fields `checkpoint set` may assign. */
 const TICKET_FIELDS = [
     "status",
@@ -67,24 +84,7 @@ const TICKET_FIELDS = [
 const TOP_LEVEL_FIELDS = ["needs_human", "counters.iterations", "counters.merges"];
 /** Build the production dependency set. */
 export function createDefaultConductEpicDeps() {
-    const runCommand = (file, args, options) => new Promise((resolve) => {
-        execFile(file, args, {
-            cwd: options?.cwd,
-            // Git porcelain output for a many-worktree checkout can be large.
-            maxBuffer: 16 * 1024 * 1024,
-            encoding: "utf-8",
-            timeout: options?.timeoutMs,
-            // Explicit: arguments are a list, never a concatenated shell string.
-            shell: false,
-        }, (error, stdout, stderr) => {
-            const code = error?.code;
-            resolve({
-                stdout: stdout ?? "",
-                stderr: stderr ?? "",
-                exitCode: typeof code === "number" ? code : error ? 1 : 0,
-            });
-        });
-    });
+    const runCommand = createExecFileRunCommand();
     const spawner = getDefaultSpawnTerminalTabForPlatform(process.platform);
     const startTicketsDeps = createDefaultStartTicketsDeps();
     return {
@@ -121,6 +121,7 @@ export function createDefaultConductEpicDeps() {
         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,
@@ -134,12 +135,16 @@ export function createDefaultConductEpicDeps() {
 export function getConductEpicUsage() {
     return [
         "Usage:",
-        "  npx -y @bridge_gpt/mcp-server conduct-epic <verb> [flags]",
+        `  npx -y ${MCP_PACKAGE_NAME} conduct-epic <verb> [flags]`,
         "",
         "Verbs:",
         "  init <EPIC> --tickets K1,K2,... [--base-branch <b>] [--checkpoint-path <p>] [--dry-run] [--json]",
-        "      Run the full preflight, create epic/<EPIC> on origin at the fetched base",
-        "      tip, repoint the indexed branch, write the checkpoint, and take the lock.",
+        "      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.",
         "",
@@ -148,14 +153,17 @@ export function getConductEpicUsage() {
         "      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.",
+        "      `scopes` lists EVERY index scope this repository owns — expired and",
+        "      reclaiming ones included — so a crashed epic is visible without SQL.",
         "",
         "  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",
-        "      and parse_requested_for_sha are recorded together, never in two writes.",
+        "      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",
@@ -167,6 +175,26 @@ export function getConductEpicUsage() {
         "      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.",
+        "",
+        "  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",
         "",
@@ -189,6 +217,9 @@ const VERB_FLAGS = {
     "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"],
 };
 /**
  * Parse and fully validate argv BEFORE any I/O.
@@ -214,7 +245,13 @@ export function parseConductEpicArgs(argv) {
         verb = "checkpoint-set";
         rest = argv.slice(2);
     }
-    else if (argv[0] === "init" || argv[0] === "status" || argv[0] === "finish" || argv[0] === "spawn") {
+    else if (argv[0] === "init" ||
+        argv[0] === "status" ||
+        argv[0] === "finish" ||
+        argv[0] === "spawn" ||
+        argv[0] === "recover" ||
+        argv[0] === "retire" ||
+        argv[0] === "reclaim") {
         verb = argv[0];
         rest = argv.slice(1);
     }
@@ -229,6 +266,7 @@ export function parseConductEpicArgs(argv) {
         fields: [],
         dryRun: false,
         json: false,
+        overrideRetention: false,
     };
     const seen = new Set();
     let epicKey;
@@ -257,6 +295,9 @@ export function parseConductEpicArgs(argv) {
             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];
@@ -346,6 +387,16 @@ function assignFlagValue(options, flag, value) {
         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}'.`;
     }
@@ -490,20 +541,16 @@ async function resolveAccess(deps) {
 }
 /** Run `git` with list args in the repository working directory. */
 function git(deps, args) {
-    return Promise.resolve(deps.runCommand("git", args, { cwd: deps.cwd }));
-}
-/** The single trimmed line a `git rev-parse`-style command produced, or null. */
-function firstLine(result) {
-    const value = result.stdout.split("\n")[0]?.trim() ?? "";
-    return value.length === 0 ? null : value;
+    return runGit(cutProtocolDeps(deps), args);
 }
-/** The SHA from `git ls-remote --heads origin <ref>` output, or null. */
-function lsRemoteSha(result) {
-    const line = firstLine(result);
-    if (line === null)
-        return null;
-    const sha = line.split(/\s+/)[0]?.trim() ?? "";
-    return sha.length === 0 ? null : sha;
+/** 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);
@@ -570,7 +617,8 @@ export async function collectConductEpicInitPreflight(deps, options) {
         failures.push(accessResult.error);
     let baseBranch = options.baseBranch ?? null;
     let baseSha = null;
-    let epicBranchAlreadyAtBase = false;
+    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);
@@ -636,22 +684,34 @@ export async function collectConductEpicInitPreflight(deps, options) {
         else if (runState.status !== 404) {
             failures.push(`The epic-run state for ${options.epicKey} could not be read: ${runState.error}`);
         }
-        // (10) Index-branch override: absent, or this epic's own (a re-init after a
-        // crash). A foreign override is named so the operator knows which epic still
-        // holds the repository's index.
-        const indexBranch = await getIndexBranch(access, deps.fetchImpl);
-        if (!indexBranch.ok) {
-            failures.push(`The indexed-branch state could not be read: ${indexBranch.error}`);
+        // (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 override = indexBranch.value.override;
-            if (override !== null && override.override_branch !== epicBranch) {
-                failures.push(`The repository index is already repointed to '${override.override_branch}' by another epic. ` +
-                    "Run `conduct-epic finish` for that epic first.");
+            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 if (override !== null && baseBranch === null) {
-                // (8) default base: this epic's own override remembers the real original.
-                baseBranch = override.original_base_branch;
+            else {
+                cutCommitSha = indexed;
             }
         }
         // (8) default base, continued: the configured base branch, then `main`.
@@ -669,8 +729,9 @@ export async function collectConductEpicInitPreflight(deps, options) {
         failures.push(`The resolved base branch is unusable: ${branchReason}`);
     }
     else {
-        // (8) The base must exist on origin AFTER a fetch — an epic branch cut from a
-        // stale local ref silently starts the epic behind main.
+        // (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.`);
@@ -680,7 +741,28 @@ export async function collectConductEpicInitPreflight(deps, options) {
         if (baseSha === null) {
             failures.push(`origin/${baseBranch} does not exist after fetching.`);
         }
-        // (9) `epic/<EPIC>` must be absent on origin, or already at the base tip.
+        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;
+                }
+            }
+        }
+        // (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}.`);
@@ -688,11 +770,12 @@ export async function collectConductEpicInitPreflight(deps, options) {
         else {
             const existingSha = lsRemoteSha(existing);
             if (existingSha !== null) {
-                if (baseSha !== null && existingSha === baseSha) {
-                    epicBranchAlreadyAtBase = true;
+                if (cutCommitSha !== null && existingSha === cutCommitSha) {
+                    epicBranchAlreadyAtCut = true;
                 }
                 else {
-                    failures.push(`origin/${epicBranch} already exists at a commit other than the ${baseBranch} tip. ` +
+                    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.");
                 }
             }
@@ -717,7 +800,8 @@ export async function collectConductEpicInitPreflight(deps, options) {
         access,
         baseBranch,
         baseSha,
-        epicBranchAlreadyAtBase,
+        cutCommitSha,
+        epicBranchAlreadyAtCut,
         pendingSupervisorConfig,
     };
 }
@@ -743,6 +827,80 @@ function requiredCheckNamesFromResolve(value) {
     }
     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)));
+    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);
+        if (!status.ok) {
+            // A transient read failure is not a verdict: keep polling and let the
+            // bound below be the thing that gives up.
+            lastState = `unreadable (${status.error})`;
+            continue;
+        }
+        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: [
+            `Index scope ${scopeId} did not become ready within the bootstrap window ` +
+                `(last observed state: ${lastState}). Re-run init to resume verification.`,
+        ],
+    };
+}
 /**
  * `conduct-epic init` — the only verb that provisions.
  *
@@ -776,13 +934,19 @@ export async function runConductEpicInit(deps, options) {
         });
     }
     const access = preflight.access;
-    if (access === null || preflight.baseBranch === null || preflight.baseSha === null) {
+    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.
+        // 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];
@@ -791,8 +955,12 @@ export async function runConductEpicInit(deps, options) {
     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}`,
-        `branch:     ${epicBranch}${preflight.epicBranchAlreadyAtBase ? " (already at the base tip)" : ""}`,
+        `cut:        ${cutCommitSha} (canonical indexed commit)`,
+        `branch:     ${epicBranch}${preflight.epicBranchAlreadyAtCut ? " (already at the cut commit)" : ""}`,
         `tickets:    ${options.tickets.join(", ")}`,
         `checkpoint: ${checkpointPath}`,
         ...announcements,
@@ -805,10 +973,11 @@ export async function runConductEpicInit(deps, options) {
             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, repointed, or written):", ...describePlan()]);
+        }, ["Planned (dry run — nothing was pushed, cut, seeded, repointed, or written):", ...describePlan()]);
     }
     // The FIRST durable mutation of the whole verb, deliberately placed here: every
     // preflight check has passed, and nothing has been pushed, repointed, written,
@@ -824,31 +993,60 @@ export async function runConductEpicInit(deps, options) {
         }
         announcements.push(`announced: auto_merge_enabled was OFF and has been enabled on the ${access.repoName} project defaults.`);
     }
-    // Push the epic branch WITHOUT a local checkout: the remote ref is created
-    // directly from the fetched remote-tracking ref, so no local branch, worktree,
-    // or checked-out state is touched.
-    const pushed = await git(deps, [
-        "push",
-        "origin",
-        `refs/remotes/origin/${preflight.baseBranch}:refs/heads/${epicBranch}`,
-    ]);
-    if (pushed.exitCode !== 0) {
-        return emitFailure(deps, options.json, [`Could not create origin/${epicBranch} from the ${preflight.baseBranch} tip.`], {
-            epic_key: options.epicKey,
-        });
+    // --- 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 });
     }
-    const repointed = await repointIndexBranch(access, { branch: epicBranch }, deps.fetchImpl);
-    if (!repointed.ok) {
-        return emitFailure(deps, options.json, [`The repository index could not be repointed to ${epicBranch}: ${repointed.error}`], {
+    // 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}.`);
+    // 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 },
@@ -874,10 +1072,11 @@ export async function runConductEpicInit(deps, options) {
         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),
-        index_repointed: true,
         announcements,
     }, ["Initialized:", ...describePlan()]);
 }
@@ -1058,6 +1257,102 @@ export async function runConductEpicStatus(deps, options) {
             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-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 = {
@@ -1070,9 +1365,14 @@ export async function runConductEpicStatus(deps, options) {
                 ? false
                 : null,
     };
-    // --- the four permitted writes -------------------------------------------
+    // --- the five permitted writes -------------------------------------------
+    // BAPI-846 added the fifth: the scope's fencing epoch, refreshed from the
+    // server's authoritative answer. It rides in the SAME atomic write as the other
+    // four 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;
+    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);
@@ -1094,6 +1394,10 @@ export async function runConductEpicStatus(deps, options) {
             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, {
@@ -1128,11 +1432,104 @@ export async function runConductEpicStatus(deps, options) {
             hard_seconds: checkpoint.deadlines.hard_seconds,
             elapsed_since_spawn_seconds: elapsedSeconds(ticket?.spawned_at ?? null, now),
         },
+        scope,
+        scope_lease_epoch: nextLeaseEpoch,
+        retention_seconds: retentionSeconds,
+        scopes,
         lock,
         needs_human: checkpoint.needs_human,
         probe_errors: probeErrors,
     };
-    return emitSuccess(deps, options.json, payload);
+    return emitSuccess(deps, options.json, payload, [
+        ...renderScopeFreshnessLines(scope),
+        ...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 — `conduct-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) {
+    if (scope === null)
+        return [];
+    const headline = {
+        fresh: "Index is fresh for this epic.",
+        pending: "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.",
+    };
+    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.",
+        `  lifecycle:      ${scope.lifecycle_state ?? "unknown"}`,
+        `  Required commit: ${scope.required_commit_sha ?? "none"}`,
+        `  Indexed commit:  ${scope.indexed_commit_sha ?? "none"}`,
+    ];
+    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.
@@ -1321,7 +1718,6 @@ export function normalizeParseStatus(value) {
         terminal: status === "succeeded" || status === "failed",
         started_at: optionalText("started_at"),
         finished_at: optionalText("finished_at"),
-        index_branch_override: optionalText("index_branch_override"),
     };
 }
 // ---------------------------------------------------------------------------
@@ -1620,12 +2016,27 @@ export async function runConductEpicSpawn(deps, options) {
         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]);
@@ -1667,14 +2078,14 @@ export async function runConductEpicSpawn(deps, options) {
 // finish
 // ---------------------------------------------------------------------------
 /**
- * `conduct-epic finish` — restore the server's indexed base branch and wind down.
+ * `conduct-epic finish` — retire the epic's index scope and wind down.
  *
- * Restoration uses `restoreIndexBranch(access)` and NOTHING else. The
- * checkpoint's `base_branch_original` is display-only: the server holds the
- * durable override row with the true original, and a local copy that drifted
- * (because the operator changed the repository's base mid-run) would restore the
- * index to the wrong branch. `{ ok: true, changed: false }` is a success — that
- * is what a second `finish` sees.
+ * 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);
@@ -1693,19 +2104,44 @@ export async function runConductEpicFinish(deps, options) {
     if (!lock.acquired) {
         return emitFailure(deps, options.json, [`The epic lock could not be acquired: ${lock.reason}`]);
     }
-    const restored = await restoreIndexBranch(access, deps.fetchImpl);
-    if (!restored.ok) {
-        await releaseAcquired(lock);
-        return emitFailure(deps, options.json, [`The repository index could not be restored: ${restored.error}`]);
+    // 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 `conduct-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 \`conduct-epic retire ${checkpoint.epic_key}\`.`);
+    }
     const summary = {
         ok: true,
         epic_key: checkpoint.epic_key,
         epic_branch: checkpoint.epic_branch,
-        index_restored: true,
-        index_changed: restored.value.changed,
-        current_base_branch: restored.value.current_base_branch,
+        /** `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) => ({
@@ -1717,7 +2153,11 @@ export async function runConductEpicFinish(deps, options) {
     };
     const humanLines = [
         `Finished ${checkpoint.epic_key} (${checkpoint.epic_branch})`,
-        `index restore: ${restored.value.changed ? "restored" : "already restored"}`,
+        `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}  ` +
@@ -1727,6 +2167,213 @@ export async function runConductEpicFinish(deps, options) {
     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 `conduct-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",
+    });
+}
+/** `conduct-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"}`,
+    ]);
+}
+/** `conduct-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;
+}
+/** `conduct-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 `conduct-epic status --json` to see it reach",
+        "  `reclaimed`.",
+    ]);
+}
+// ---------------------------------------------------------------------------
 // Entry point
 // ---------------------------------------------------------------------------
 /**
@@ -1761,5 +2408,11 @@ export async function runConductEpicCli(argv, overrides = {}) {
             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);
     }
 }