@bridge_gpt/mcp-server 0.2.49 → 0.2.51

package/build/conduct-epic/cli.js

@@ -6,12 +6,17 @@
  * right base, that a checkpoint write is atomic, that two sessions cannot edit
  * one checkpoint, that a `MERGED` PR is visible, that `auto_merge_enabled` is on
  * before the first ticket is dispatched — are exactly the kind that fail
- * silently when they live in an instruction file. So they live here, behind five
+ * 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)
  *
- * Design rules that hold across all five:
+ * `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
@@ -34,12 +39,13 @@ 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, getParseStatus, getPrReviewStatus, heartbeatIndexScope, pollCiChecks, putSupervisorConfigDefaults, reclaimIndexScope, recoverIndexScope, resolveCiChecks, retireIndexScope, } from "./bridge-client.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";
@@ -51,7 +57,7 @@ import { INDEX_SCOPE_CONFIGURATION_ERROR, validateOptionalIndexScope, } from "..
 // 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";
+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. */
@@ -67,6 +73,7 @@ export const CONDUCT_EPIC_VERBS = [
     "retire",
     "reclaim",
     "catch-up",
+    "scopes",
 ];
 /** Per-ticket fields `checkpoint set` may assign. */
 const TICKET_FIELDS = [
@@ -91,9 +98,17 @@ 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: {
@@ -130,6 +145,7 @@ export function createDefaultConductEpicDeps() {
         errorLog: (m) => console.error(m),
         resolveAccess: resolveConductorBridgeApiAccess,
         resolveLatestPublishedVersion: () => fetchLatestVersion({ fetch: globalThis.fetch }),
+        publishedIdentityFixture,
         resolveRepoName: resolveRequiredStartTicketsRepoName,
     };
 }
@@ -158,8 +174,14 @@ 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.",
+        "      status warns about STRANDED scopes only; run `conduct-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>]",
@@ -240,6 +262,10 @@ const VERB_FLAGS = {
     // 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.
@@ -272,7 +298,8 @@ export function parseConductEpicArgs(argv) {
         argv[0] === "recover" ||
         argv[0] === "retire" ||
         argv[0] === "reclaim" ||
-        argv[0] === "catch-up") {
+        argv[0] === "catch-up" ||
+        argv[0] === "scopes") {
         verb = argv[0];
         rest = argv.slice(1);
     }
@@ -340,12 +367,23 @@ export function parseConductEpicArgs(argv) {
             }
         }
     }
-    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.`);
+    // 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 `conduct-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;
     }
-    options.epicKey = epicKey;
     const missing = requiredFlagError(options);
     if (missing !== null)
         return parseError(missing);
@@ -487,6 +525,29 @@ function emitFailure(deps, json, reasons, payload = {}) {
 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)
@@ -603,6 +664,36 @@ export const PUBLISHED_IDENTITY_TIMEOUT_MS = 120_000;
 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 `conduct-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) {
@@ -630,6 +721,13 @@ export function describePublishedIdentityReason(reason) {
  * 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 {
@@ -752,7 +850,11 @@ export async function evaluatePublishGate(deps, expectedCommitSha) {
             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.",
+                    "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: [],
         };
@@ -1054,16 +1156,35 @@ async function driveIndexScopeBootstrap(deps, access, scopeId, options) {
         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.
+            // 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 &&
@@ -1105,7 +1226,7 @@ async function driveIndexScopeBootstrap(deps, access, scopeId, options) {
     return {
         ok: false,
         failures: [
-            `Index scope ${scopeId} did not become ready within the bootstrap window ` +
+            `TIMED OUT: index scope ${scopeId} did not become ready within the bootstrap window ` +
                 `(last observed state: ${lastState}). Re-run init to resume verification.`,
         ],
     };
@@ -1191,7 +1312,12 @@ export async function runConductEpicInit(deps, options) {
             tickets: options.tickets,
             checkpoint_path: checkpointPath,
             announcements,
-        }, ["Planned (dry run — nothing was pushed, cut, seeded, repointed, or written):", ...describePlan()]);
+        }, [
+            "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,
@@ -1242,6 +1368,20 @@ export async function runConductEpicInit(deps, options) {
         });
     }
     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: "conduct-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
@@ -1303,12 +1443,19 @@ export async function runConductEpicInit(deps, options) {
  *   unavailable — each leaves its sub-object `null`, adds a `probe_errors` entry,
  *   and the command still exits 0 with a complete object. The loop must be able
  *   to see its own checkpoint during a GitHub outage.
- * - **The write allowlist is exactly four fields** (`ci_last_poll`,
- *   `last_seen_head`, `last_state_change_at`, and a newly discovered
- *   `ticket.branch`) plus the normal `updated_at`. Everything else is
- *   observational. In particular the checkpoint stores no "expected head":
- *   merge identity always comes from a fresh `pr.head_sha`, and a stored
+ * - **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);
@@ -1572,6 +1719,31 @@ export async function runConductEpicStatus(deps, options) {
             };
         }
     }
+    // --- 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:
@@ -1635,13 +1807,17 @@ export async function runConductEpicStatus(deps, options) {
                 ? false
                 : null,
     };
-    // --- 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.
+    // --- 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] };
@@ -1659,6 +1835,15 @@ export async function runConductEpicStatus(deps, options) {
             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;
@@ -1673,8 +1858,15 @@ export async function runConductEpicStatus(deps, options) {
             const written = await writeConductEpicCheckpointAtomic(checkpointPath, next, deps.fs, {
                 skipChmod: deps.platform === "win32",
             });
-            if (!written.ok)
+            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 = {
@@ -1684,7 +1876,9 @@ export async function runConductEpicStatus(deps, options) {
         checkpoint_path: checkpointPath,
         checkpoint_exists: true,
         all_done: allDone,
-        ticket: ticket === null ? null : projectConductEpicTicketFacts(ticket, discoveredBranch),
+        ticket: projectedTicket === null
+            ? null
+            : projectConductEpicTicketFacts(projectedTicket, discoveredBranch),
         worktree_path: worktreePath,
         worktree_exists: worktreeExists,
         branch_head: branchHead,
@@ -1703,6 +1897,9 @@ export async function runConductEpicStatus(deps, options) {
             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,
@@ -1711,7 +1908,7 @@ export async function runConductEpicStatus(deps, options) {
         probe_errors: probeErrors,
     };
     return emitSuccess(deps, options.json, payload, [
-        ...renderScopeFreshnessLines(scope),
+        ...renderScopeFreshnessLines(scope, dispatcher),
         ...renderStrandedScopeLines(scopes, declaredScopeId),
     ]);
 }
@@ -1770,12 +1967,20 @@ function renderStrandedScopeLines(scopes, ownScopeId) {
     }
     return lines;
 }
-function renderScopeFreshnessLines(scope) {
+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: "Waiting for index refresh.",
+        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.",
@@ -1799,6 +2004,9 @@ function renderScopeFreshnessLines(scope) {
     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 `conduct-epic catch-up <EPIC>` to repair it.");
@@ -2427,6 +2635,18 @@ export async function runConductEpicFinish(deps, options) {
         deps.errorLog(`The index scope was not retired: ${scopeRetirementError}. ` +
             `Retry with \`conduct-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: "conduct-epic finish",
+        requestReady: true,
+    });
+    deps.errorLog(`Integration PR: ${JSON.stringify(integrationPrAdvisory)}`);
     const summary = {
         ok: true,
         epic_key: checkpoint.epic_key,
@@ -2593,7 +2813,35 @@ export async function runConductEpicCatchUp(deps, options) {
         required_commit_sha: value.required_commit_sha,
         parse_scheduled: value.parse_scheduled,
     };
-    const lines = renderCatchUpLines(value, target.scopeId);
+    // 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: "conduct-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);
@@ -2607,8 +2855,17 @@ export async function runConductEpicCatchUp(deps, options) {
  * 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) {
+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 [
@@ -2618,6 +2875,7 @@ function renderCatchUpLines(value, scopeId) {
                 value.parse_scheduled
                     ? "  A re-parse is scheduled. Poll `conduct-epic status` until freshness reads `fresh`."
                     : "  No re-parse was scheduled; poll `conduct-epic status` for the scope's own state.",
+                ...waiting,
             ];
         case "already_current":
             return [
@@ -2631,6 +2889,7 @@ function renderCatchUpLines(value, scopeId) {
                     ? "  A re-parse is scheduled. Poll `conduct-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 [
@@ -2780,6 +3039,63 @@ export async function runConductEpicReclaim(deps, options) {
         "  `reclaimed`.",
     ]);
 }
+/**
+ * `conduct-epic scopes` — the repository-wide index-scope inventory (BAPI-963).
+ *
+ * `--help` promised this listing under `status` and no invocation delivered it:
+ * `conduct-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 `conduct-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
 // ---------------------------------------------------------------------------
@@ -2805,6 +3121,8 @@ export async function runConductEpicCli(argv, overrides = {}) {
     }
     const options = parsed.options;
     switch (options.verb) {
+        case "scopes":
+            return runConductEpicScopes(deps, options);
         case "init":
             return runConductEpicInit(deps, options);
         case "status":