@bridge_gpt/mcp-server 0.2.41 → 0.2.43

package/build/conductor/cli.js

@@ -18,7 +18,7 @@ import { ConductorValidationError, ConductorEpicTickV1FrozenError, toConductorEr
 import { emitConductorEvent, purgeConductorLedger, sendWorkerMessage, checkWorkerMessages, } from "./store.js";
 import { isDuplicateConstraintError } from "./producer-ledger.js";
 import { SEMANTIC_EVENT_TYPES } from "./taxonomy.js";
-import { installConductorGitHooks } from "./git-hooks.js";
+import { installConductorGitHooks, resolveConductorHookBin } from "./git-hooks.js";
 import { runFileScopeGuardCli } from "./file-scope-guard.js";
 import { runPostCommitHookProducer, runReferenceTransactionHookProducer } from "./git-producer.js";
 import { buildConductorDoctorReport, formatConductorDoctorReport } from "./doctor.js";
@@ -65,6 +65,15 @@ export function getConductorUsage() {
         "                       Run the reference-transaction producer (invoked by the hook)",
         "  file-scope-guard     Warn-only: compare the branch diff against the declared",
         "                       touched-file set (always exits 0; never blocks a PR)",
+        "  stop-run             Stop an epic run: block dispatch and cancel queued work",
+        "                       (the run record is preserved). Idempotent.",
+        "  abandon-run          Abandon an epic run — TERMINAL and IRREVERSIBLE.",
+        "                       Idempotent on an already-abandoned run.",
+        "  unpark               Move a parked (needs_human) ticket back into its gate",
+        "                       machine. Retries internally on a concurrent change.",
+        "  adopt-current-head-and-unpark",
+        "                       Recover a ticket parked by a PR-head drift: adopt the",
+        "                       CURRENT PR head and unpark in one step.",
         "",
         "supervise options:",
         "  --run-id <id>             Run/session identifier to supervise (required)",
@@ -157,8 +166,47 @@ export function getConductorUsage() {
         "  conductor approve-plan EPIC-405 --plan-version 2 --json",
         "  conductor epic-status --epic-key EPIC-405",
         "  conductor epic-status --epic-key EPIC-405 --json",
+        "",
+        "stop-run / abandon-run options:",
+        "  --epic-run-id <id>        Epic run identifier (required)",
+        "  --json                    Print compact JSON result",
+        "  --help                    Print this usage message",
+        "  stop-run BLOCKS new dispatch and CANCELS queued work; the run record is",
+        "  preserved and the run cannot resume on its own — it is an emergency brake,",
+        "  not a pause. abandon-run is the SAME plus a TERMINAL, IRREVERSIBLE close-out:",
+        "  once abandoned, the run can never resume or be reused. Both are idempotent —",
+        "  repeating either is a safe no-op once the run is already stopped/abandoned.",
+        "",
+        "unpark / adopt-current-head-and-unpark options:",
+        "  --epic-run-id <id>        Epic run identifier (required)",
+        "  --ticket-key <key>        Ticket key (required)",
+        "  --json                    Print compact JSON result",
+        "  --help                    Print this usage message",
+        "  unpark resumes a ticket PARKED with needs_human, once the underlying cause",
+        "  is resolved. adopt-current-head-and-unpark additionally REBINDS the ticket's",
+        "  anchored PR head to whatever the PR's head currently is, for a ticket parked",
+        "  by a human/external push. Both retry internally on a concurrent row change —",
+        "  neither accepts, nor ever asks for, a version counter.",
+        "",
+        "Incident examples:",
+        "  # A run is misbehaving and must stop immediately:",
+        "  conductor stop-run --epic-run-id 3f9c2b7e-...",
+        "  # The run is done for good — close it out:",
+        "  conductor abandon-run --epic-run-id 3f9c2b7e-...",
+        "  # A ticket parked itself (needs_human) and the cause is now fixed:",
+        "  conductor unpark --epic-run-id 3f9c2b7e-... --ticket-key BAPI-852",
+        "  # A human pushed directly to the PR and the ticket parked on head drift:",
+        "  conductor adopt-current-head-and-unpark --epic-run-id 3f9c2b7e-... --ticket-key BAPI-852",
     ].join("\n");
 }
+/**
+ * Private diagnostic action (BAPI-772): prints the `conductor-bin.js` path the
+ * EXECUTING artifact resolves for hook installation. It exists so a test can run
+ * `node build/conductor-bin.js __hook-bin` against the real esbuild bundle and
+ * assert the printed path exists — a tsc-emit unit test structurally cannot catch
+ * the bundled-layout bug this ticket fixes. Mirrors `plane __entrypoint`.
+ */
+export const CONDUCTOR_HOOK_BIN_ACTION = "__hook-bin";
 const VALID_COMMANDS = new Set([
     "emit-event",
     "supervise",
@@ -172,6 +220,15 @@ const VALID_COMMANDS = new Set([
     "install-git-hooks",
     "git-hook",
     "file-scope-guard",
+    // BAPI-872: CLI-only operator recovery verbs — never registered as MCP tools.
+    "stop-run",
+    "abandon-run",
+    "unpark",
+    "adopt-current-head-and-unpark",
+    // Private, and deliberately ABSENT from the usage text: `__hook-bin` exists as
+    // the bundled-artifact regression guard for BAPI-772 (mirroring `plane
+    // __entrypoint`), not as a supported operator workflow.
+    CONDUCTOR_HOOK_BIN_ACTION,
 ]);
 /**
  * Parse the top-level conductor argv into a subcommand (without a CLI
@@ -583,6 +640,11 @@ export async function runDoctorCommand(argv, deps = {}) {
  * Run `install-git-hooks`: install/update the local managed `post-commit` and
  * `reference-transaction` hooks. Returns 0 even when the directory is not a git
  * worktree (degraded optional capability) — never a fatal failure.
+ *
+ * BAPI-772: an unresolvable `conductor-bin.js` IS fatal (exit 1). Writing a hook
+ * that points at a nonexistent binary produced a hook that silently did nothing
+ * on every commit, so the installer now refuses and this command reports the
+ * refusal with the resolver's searched-layout remediation.
  */
 export function runInstallGitHooksCommand(argv) {
     const { bools } = tokenizeFlags(argv, new Set(), DIAGNOSTIC_BOOL_FLAGS);
@@ -591,6 +653,14 @@ export function runInstallGitHooksCommand(argv) {
         return 0;
     }
     const result = installConductorGitHooks();
+    if (!result.ok) {
+        if (bools.has("--json")) {
+            console.error(JSON.stringify({ error: result.error, reason: result.reason }));
+            return 1;
+        }
+        console.error(`Error: conductor git hooks were NOT installed (${result.error}): ${result.reason}`);
+        return 1;
+    }
     if (bools.has("--json")) {
         console.log(JSON.stringify(result));
         return 0;
@@ -600,6 +670,7 @@ export function runInstallGitHooksCommand(argv) {
         "───────────────────────────",
         `is git worktree:  ${result.is_worktree}`,
         `hooks dir:        ${result.hooks_dir ?? "n/a"}`,
+        `conductor bin:    ${result.conductor_bin}`,
     ];
     for (const hook of result.installed) {
         lines.push(`  ${hook.name}: ${hook.action}${hook.warning ? ` (${hook.warning})` : ""}`);
@@ -612,6 +683,21 @@ export function runInstallGitHooksCommand(argv) {
     console.log(lines.join("\n"));
     return 0;
 }
+/**
+ * Run the private `__hook-bin` diagnostic: resolve the hook binary from the
+ * executing artifact and print ONLY that canonical path to stdout, so artifact-
+ * level automation can consume it directly. A failed resolution prints the
+ * sanitized resolver reason to stderr and returns 1 — never a stack trace.
+ */
+export function runHookBinDiagnosticCommand() {
+    const resolution = resolveConductorHookBin();
+    if (!resolution.ok) {
+        console.error(`conductor hook bin UNRESOLVED: ${resolution.reason}`);
+        return 1;
+    }
+    console.log(resolution.path);
+    return 0;
+}
 const GIT_HOOK_VALUE_FLAGS = new Set(["--phase", "--stdin-file"]);
 const GIT_HOOK_BOOL_FLAGS = new Set(["--help"]);
 /**
@@ -1104,9 +1190,31 @@ export async function runConductorCli(argv) {
                 return runInstallGitHooksCommand(parsed.argv);
             case "git-hook":
                 return await runGitHookCommand(parsed.argv);
+            case CONDUCTOR_HOOK_BIN_ACTION:
+                // Dispatched before any MCP server construction or store access: the
+                // guard must be able to run against a bundle whose ledger is absent.
+                return runHookBinDiagnosticCommand();
             case "file-scope-guard":
                 // BAPI-507 (N-2): warn-only worker file-scope guard. Always exits 0.
                 return runFileScopeGuardCli();
+            case "stop-run": {
+                // BAPI-872: lazily imported so the Bridge credential/HTTP graph never
+                // loads for a local-only command (doctor, emit-event, etc.).
+                const { runStopRunCommand } = await import("./recovery-cli.js");
+                return await runStopRunCommand(parsed.argv);
+            }
+            case "abandon-run": {
+                const { runAbandonRunCommand } = await import("./recovery-cli.js");
+                return await runAbandonRunCommand(parsed.argv);
+            }
+            case "unpark": {
+                const { runUnparkCommand } = await import("./recovery-cli.js");
+                return await runUnparkCommand(parsed.argv);
+            }
+            case "adopt-current-head-and-unpark": {
+                const { runAdoptCurrentHeadAndUnparkCommand } = await import("./recovery-cli.js");
+                return await runAdoptCurrentHeadAndUnparkCommand(parsed.argv);
+            }
             default:
                 console.error('Error: Unknown command. Run "conductor --help" for usage.');
                 return 1;

package/build/conductor/doctor.js

@@ -15,6 +15,10 @@ import { doctorConductorLedger } from "./store.js";
 import { detectClaudeLogin, formatClaudeLoginAdvisory } from "../claude-login.js";
 import { inspectConductorGitHooks } from "./git-hooks.js";
 import { resolveMcpShimInvocationForRuntime, resolvePackageRootFromModuleUrl, } from "../mcp-server-invocation.js";
+import { MCP_PACKAGE_NAME } from "../mcp-identity.js";
+import { resolveProfiles } from "../mcp-profile.js";
+/** Explicit display value for an unset `BRIDGE_MCP_PROFILE`. */
+export const MCP_PROFILE_UNSET = "(unset)";
 /**
  * Explicit not-run state for the `deny_enforcement` section when the probe is
  * skipped via `--no-deny-probe`. Enforcement is UNVERIFIED, so the state is
@@ -115,6 +119,66 @@ export async function inspectNativeLedger(nativeLoad, deps = {}) {
         warnings,
     };
 }
+/**
+ * Collect the ledger doctor result and its native-ledger inspection together.
+ *
+ * READ-ONLY and diagnostic only: it never installs or rebuilds
+ * `better-sqlite3`, opens a write transaction, creates or migrates the ledger,
+ * or alters package state. It may THROW when an injected `doctorLedger` seam
+ * throws — {@link collectConductorNativeLedgerSafe} is the containment wrapper
+ * for callers that must not see an exception.
+ */
+export async function collectConductorNativeLedger(deps = {}) {
+    const doctorLedger = deps.doctorLedger ?? doctorConductorLedger;
+    const ledger = await doctorLedger();
+    const native_ledger = await inspectNativeLedger(ledger.native_load, deps);
+    return { ledger, native_ledger };
+}
+/** Map a native-ledger inspection onto the reportable availability shape. */
+export function describeNativeLedgerAvailability(inspection) {
+    if (inspection.binding_loads)
+        return { status: "available" };
+    return {
+        status: "degraded",
+        module: inspection.module,
+        nodeModulesAbi: inspection.node_modules_abi,
+        failureKind: inspection.failure_kind,
+    };
+}
+/**
+ * Sanitized failure-kind token used when the collection itself could not run.
+ *
+ * A collection failure and a load failure are different facts, so this is its
+ * own token rather than a reused one.
+ */
+export const NATIVE_LEDGER_UNCOLLECTED_FAILURE_KIND = "inspection_unavailable";
+/**
+ * Collect the native-ledger inspection, containing every failure.
+ *
+ * A thrown collection error yields a GENERIC degraded inspection — no exception
+ * message, no absolute package path, no stack trace. An operator learns that the
+ * probe could not answer, which is the actionable fact; the raw error is
+ * discarded because it can carry a filesystem path.
+ */
+export async function collectConductorNativeLedgerSafe(deps = {}) {
+    try {
+        return (await collectConductorNativeLedger(deps)).native_ledger;
+    }
+    catch {
+        return {
+            cli_node_version: process.version,
+            engines_node: null,
+            mcp_shim_node: null,
+            mcp_registration_form: "unknown",
+            module: "better-sqlite3",
+            node_modules_abi: process.versions.modules,
+            binding_loads: false,
+            failure_kind: NATIVE_LEDGER_UNCOLLECTED_FAILURE_KIND,
+            degraded: true,
+            warnings: ["the native ledger inspection could not be collected on this host"],
+        };
+    }
+}
 /**
  * Inspect the local schedule metadata store for a registered epic-tick schedule.
  * Strictly read-only: composes orchestrateScheduleList (read-only list path) and
@@ -174,10 +238,10 @@ export async function inspectEpicTickSchedule(deps, orchestrateListOverride) {
             warnings: [
                 "An epic-tick schedule is registered, but the v1 `conductor epic-tick` " +
                     "path is frozen (EPIC_TICK_V1_FROZEN) — it advances nothing. Cancel it: " +
-                    "`npx -y @bridge_gpt/mcp-server schedule-run cancel --id " +
+                    `\`npx -y ${MCP_PACKAGE_NAME} schedule-run cancel --id ` +
                     `${entry.metadata.id ?? "<id>"}\`. ` +
                     "Epic Conductor v2 reconciles server-side; run jobs locally with " +
-                    "`npx -y @bridge_gpt/mcp-server executor --repo <name>`.",
+                    `\`npx -y ${MCP_PACKAGE_NAME} executor --repo <name>\`.`,
             ],
         };
     }
@@ -195,22 +259,35 @@ export async function inspectEpicTickSchedule(deps, orchestrateListOverride) {
 }
 /**
  * Inspect the BRIDGE_MCP_PROFILE environment variable and warn when a
- * conductor/epic context is detected but the profile is not "conductor".
+ * conductor/epic context is detected but the resolved groups omit `conductor`.
  * Strictly read-only, never throws.
+ *
+ * BAPI-772: health is judged from {@link resolveProfiles} — the SAME resolver the
+ * MCP server registers tools with — instead of comparing the raw string to
+ * `"conductor"`. The old equality check called a worker running
+ * `BRIDGE_MCP_PROFILE=conductor,sfcc` (exactly what `buildConductorWorkerEnv`
+ * produces on SFCC projects) or `full` degraded, and its remediation told the
+ * operator to REPLACE the variable — which would have destroyed the worker's
+ * other groups. The remediation now says ADD.
  */
 export function inspectMcpProfile(env, epicTick) {
-    const resolved_profile = env.BRIDGE_MCP_PROFILE || "core";
+    const raw = env.BRIDGE_MCP_PROFILE;
+    const raw_profile = raw === undefined ? MCP_PROFILE_UNSET : raw;
+    const groups = resolveProfiles(raw);
+    const active_groups = Array.from(groups);
     const conductor_context_detected = env.BAPI_CONDUCTOR_ENABLED === "1" ||
         env.BAPI_CONDUCTOR_ENABLED === "true" ||
         epicTick.registered;
-    const degraded = conductor_context_detected && resolved_profile !== "conductor";
+    const degraded = conductor_context_detected && !groups.has("conductor");
     const warnings = [];
     if (degraded) {
-        warnings.push(`BRIDGE_MCP_PROFILE is "${resolved_profile}" but a conductor context is active. ` +
-            `Expected "conductor" — conductor/event/supervisor tools may be missing. ` +
-            `Ensure the spawner injects BRIDGE_MCP_PROFILE=conductor into the worker shell environment.`);
+        warnings.push(`BRIDGE_MCP_PROFILE is ${raw_profile} (active groups: ${active_groups.join(", ")}) ` +
+            `but a conductor context is active. ADD \`conductor\` to BRIDGE_MCP_PROFILE ` +
+            `(e.g. \`${raw_profile === MCP_PROFILE_UNSET ? "conductor" : `${raw_profile},conductor`}\`) — ` +
+            `do NOT replace the value, which would drop the worker's other groups. ` +
+            `Without it the conductor/event/supervisor tools are not registered.`);
     }
-    return { resolved_profile, conductor_context_detected, degraded, warnings };
+    return { raw_profile, active_groups, conductor_context_detected, degraded, warnings };
 }
 /**
  * Read-only probe of the local-merge (F4) capability. Runs `gh --version` and
@@ -277,13 +354,13 @@ export function inspectLocalMerge(runCommand) {
  * Never mutates the ledger, the hooks, the schema, or the OS scheduler.
  */
 export async function buildConductorDoctorReport(deps = {}) {
-    const doctorLedger = deps.doctorLedger ?? doctorConductorLedger;
     const inspectHooks = deps.inspectHooks ?? inspectConductorGitHooks;
     const epicTick = await inspectEpicTickSchedule(deps.scheduleDeps, deps.orchestrateList);
     const mcp_profile = inspectMcpProfile(deps.env ?? process.env, epicTick);
-    // Resolve the ledger once so the native-load probe reflects the same report.
-    const ledger = await doctorLedger();
-    const native_ledger = await inspectNativeLedger(ledger.native_load, deps);
+    // Resolve the ledger once so the native-load probe reflects the same report —
+    // through the SHARED collector (BAPI-775), so the installer's read-only probe
+    // and this report cannot diverge in their interpretation of the binding.
+    const { ledger, native_ledger } = await collectConductorNativeLedger(deps);
     const deny_enforcement = deps.skipDenyProbe
         ? skippedDenyEnforcementResult()
         : await inspectDenyEnforcementSafe(deps.inspectDenyEnforcement);
@@ -369,7 +446,11 @@ export function formatConductorDoctorReport(report) {
     lines.push(`hooks dir:             ${git_hooks.hooks_dir ?? "n/a"}`);
     lines.push(`degraded:              ${git_hooks.degraded}`);
     for (const hook of git_hooks.hooks) {
-        lines.push(`  ${hook.name}: exists=${hook.exists} executable=${hook.executable} managed=${hook.managed_block_present}`);
+        // BAPI-772: the embedded target is shown alongside the structural fields —
+        // a managed block whose binary no longer exists is a DEAD hook, and this line
+        // is where that becomes visible. Advisory only: never changes the exit code.
+        lines.push(`  ${hook.name}: exists=${hook.exists} executable=${hook.executable} managed=${hook.managed_block_present} ` +
+            `bin=${hook.embedded_bin_path ?? "n/a"} bin_is_file=${hook.embedded_bin_is_file}`);
     }
     if (git_hooks.warnings.length > 0) {
         lines.push("git hook warnings:");
@@ -399,12 +480,16 @@ export function formatConductorDoctorReport(report) {
     lines.push("");
     lines.push("Epic Conductor v2 reconciles epics server-side — nothing to schedule");
     lines.push("locally. To execute claimed jobs on this machine, run:");
-    lines.push("  npx -y @bridge_gpt/mcp-server executor --repo <name>");
+    lines.push(`  npx -y ${MCP_PACKAGE_NAME} executor --repo <name>`);
     lines.push("");
     lines.push("MCP Profile (optional, local)");
     lines.push("─────────────────────────────");
+    // The tag belongs to the RESOLVED interpretation, not the raw string: a raw
+    // value of `full` is healthy precisely because it resolves to a set containing
+    // `conductor`.
     const profileTag = mcp_profile.degraded ? "[WARNING] degraded" : "[OK]";
-    lines.push(`resolved profile:      ${mcp_profile.resolved_profile} ${profileTag}`);
+    lines.push(`raw profile:           ${mcp_profile.raw_profile}`);
+    lines.push(`active groups:         ${mcp_profile.active_groups.join(", ")} ${profileTag}`);
     lines.push(`conductor context:     ${mcp_profile.conductor_context_detected}`);
     lines.push(`degraded:              ${mcp_profile.degraded}`);
     if (mcp_profile.warnings.length > 0) {

package/build/conductor/epic-reconcile.js

@@ -19,6 +19,19 @@
  */
 import { computeReadySet, decideRemediation, DEFAULT_MAX_SPEC_REVIEW_ATTEMPTS } from "./epic-state.js";
 import { extractMergeActionIdentityFromGateEvent } from "./merge-ledger.js";
+/**
+ * The canonical park reason for a stale hold that ran out its deadline.
+ *
+ * Byte-identical to the Python reconciler's `SHADOW_STALE_DEADLINE_REASON`, and
+ * that is the point: both conductors park for the same cause, so an operator
+ * greps one string. This introduces no `epic_ticket_status` value — the ticket
+ * moves to the EXISTING `needs_human`, whose vocabulary is closed (R14).
+ */
+export const SHADOW_STALE_DEADLINE_REASON = "shadow_stale_deadline";
+/** Normalize either accepted seam shape into the richer one. */
+function normalizeShadowDecision(raw) {
+    return typeof raw === "string" ? { verdict: raw } : raw;
+}
 /**
  * Sanitize a thrown value into a single-line, bounded diagnostic string for a
  * tick warning (BAPI-487 Requirement 2). Surfaces the real `err.message` (the
@@ -37,6 +50,31 @@ export function safeDiagnosticMessage(err, fallback) {
 // ---------------------------------------------------------------------------
 // reconcileEpic
 // ---------------------------------------------------------------------------
+/**
+ * Surface an elapsed scope-freshness deadline without transitioning the ticket.
+ *
+ * Deliberately diagnostic. The `epic_ticket_status` vocabulary — `parsing`,
+ * `needs_human` and the rest — is owned by the SERVER-side reconciler
+ * (`api/library/epic_conductor/reconciler.py`), which is the single transition
+ * authority for it and already parks this exact condition through its ordinary
+ * `_park_needs_human` commit point under the same `shadow_stale_deadline` reason.
+ * This pass runs the legacy supervisor's own, narrower status vocabulary, and
+ * minting a park from here would give one ticket two transition authorities —
+ * the failure mode R14 exists to prevent.
+ *
+ * So what this does is the honest half: it stops the dispatch (the caller
+ * `continue`s), and it makes the expiry and its cause visible in the tick's
+ * warnings so an operator watching this side is not left wondering why a ticket
+ * sat still. The durable park is observed, not raced for.
+ */
+function reportShadowDeadlineExpired(deps, result, ticketKey, verdict, blockedAdvanceReason) {
+    const reason = blockedAdvanceReason
+        ? `${SHADOW_STALE_DEADLINE_REASON}:${blockedAdvanceReason}`
+        : SHADOW_STALE_DEADLINE_REASON;
+    result.warnings.push(`shadow-freshness deadline elapsed for ${ticketKey}: ${reason}`);
+    deps.log(`[epic-reconcile] ${ticketKey} shadow watermark ${verdict} past deadline (${reason}); ` +
+        `holding dispatch — the server reconciler owns the needs_human park`);
+}
 /**
  * Execute the deterministic observed→desired reconciliation pass. All I/O is
  * behind injected seams; the ready-set is computed by pure code (no LLM).
@@ -158,32 +196,47 @@ export async function reconcileEpic(access, observed, plan, deps, supervisorConf
         // not claim a dispatch key until the backend proves the run's shadow index
         // covers every declared predecessor's merge watermark. Dependency-free nodes
         // bypass the gate entirely so independent tickets keep their parallel behavior.
+        // BAPI-845: the EXPLICIT non-epic bypass. A ticket that declares no
+        // predecessors is not a member of an active epic/scope workflow, so it is
+        // exempted here — before any scope-status lookup and before any ticket-status
+        // mutation. Stating it rather than letting it fall out of a compound
+        // condition is what makes "a scope problem never blocks a non-epic ticket" a
+        // property this file asserts instead of one it happens to have: a stale,
+        // blocked, or failed scope cannot reach an independent ticket's dispatch at
+        // all, because the scope is never consulted for one.
         const declaredDeps = plan.tickets.find((t) => t.ticket_key === ticketKey)?.depends_on ?? [];
-        if (declaredDeps.length > 0 && deps.checkShadowFreshness) {
-            let verdict;
+        const participatesInScopeWorkflow = declaredDeps.length > 0;
+        if (participatesInScopeWorkflow && deps.checkShadowFreshness) {
+            let decision;
             try {
-                verdict = await deps.checkShadowFreshness(ticketKey);
+                decision = normalizeShadowDecision(await deps.checkShadowFreshness(ticketKey));
             }
             catch (err) {
                 // Fail closed: a freshness API error / malformed response never opens the
-                // gate. Hold this tick without claiming a key or consuming any counter.
-                verdict = "stale";
+                // gate, and never parks either — an unread deadline is not an elapsed one.
+                // Hold this tick without claiming a key or consuming any counter.
+                decision = { verdict: "stale" };
                 deps.log(`[epic-reconcile] shadow-freshness error for ${ticketKey}: ${safeDiagnosticMessage(err, "freshness error")}; holding`);
             }
-            if (verdict === "stale") {
-                // BAPI-678: this covers ordinary unproven freshness AND the backend's
-                // warn-only downgrade of a `failed` shadow lifecycle. Identical handling
-                // is intentional — either way the watermark is unproven, so hold before
-                // claiming a dispatch key. The backend clocks the hold and parks the
-                // ticket if its own stale deadline expires, so "hold" is bounded there
-                // rather than repeating forever here.
-                deps.log(`[epic-reconcile] holding ${ticketKey}: shadow watermark stale`);
-                continue;
-            }
-            if (verdict === "failed") {
-                // Terminal shadow failure — the backend has already persisted the run's
-                // blocked state; emit a diagnostic and skip dispatch (no key claimed).
-                deps.log(`[epic-reconcile] shadow index failed for ${ticketKey}; run blocked, skipping dispatch`);
+            const { verdict } = decision;
+            if (verdict === "stale" || verdict === "failed") {
+                // BAPI-678: `stale` covers ordinary unproven freshness AND the backend's
+                // warn-only downgrade of a `failed` shadow lifecycle; `failed` is the
+                // terminal one the backend has already blocked the run for. Both hold.
+                //
+                // BAPI-845 bounds that hold. While the backend reports the typed
+                // `shadow.stale_deadline_seconds` as unexpired the ticket simply waits —
+                // it is never dispatched and never routed to the canonical index, so a
+                // held ticket cannot quietly research against an index that does not
+                // contain its predecessors' merges. A ticket already in `parsing` is left
+                // exactly where it is; nothing on this path advances it.
+                const blocked = decision.blockedAdvanceReason ?? null;
+                const because = blocked ? ` (${blocked})` : "";
+                if (decision.deadlineExpired !== true) {
+                    deps.log(`[epic-reconcile] holding ${ticketKey}: shadow watermark ${verdict}${because}`);
+                    continue;
+                }
+                reportShadowDeadlineExpired(deps, result, ticketKey, verdict, blocked);
                 continue;
             }
             // "covered" | "not_applicable" fall through to the normal claim/dispatch.

package/build/conductor/epic-runtime.js

@@ -27,7 +27,7 @@ import { makeLocalMergeExecutor, resolveLocalMergeMethod } from "./local-merge.j
 import { getHeadSha, getPrNumber } from "./event-accessors.js";
 import { emitConductorEventIfNew } from "./producer-ledger.js";
 import { rebuildObservedState, extractWorkerLiveness, } from "./epic-state.js";
-import { reconcileEpic } from "./epic-reconcile.js";
+import { reconcileEpic, } from "./epic-reconcile.js";
 import { normalizeDeclaredTouchedFiles } from "./file-scope-guard.js";
 import { buildSupervisorRemediationWorkerMessage } from "./supervisor-message-relay.js";
 import { sendWorkerMessage } from "./store.js";
@@ -1953,8 +1953,20 @@ export async function buildProductionEpicRuntimeDeps(epicKey) {
         // BAPI-654 (T2): backend-authoritative shadow ops. Like fetchPlan, they
         // receive `access` as a parameter, so they close over no credentials.
         reconcileShadowMerge: (acc, ek, mergedTicketKey) => reconcileShadowMerge(acc, { epicKey: ek, mergedTicketKey }),
-        checkShadowFreshness: async (acc, ek, tk) => (await fetchShadowDispatchFreshness(acc, { epicKey: ek, ticketKey: tk }))
-            .verdict,
+        // BAPI-845: forward the WHOLE decision, not just the verdict. Dropping the
+        // deadline state here is what left the reconcile pass able only to hold
+        // forever; the reason token is what lets it say why.
+        checkShadowFreshness: async (acc, ek, tk) => {
+            const freshness = await fetchShadowDispatchFreshness(acc, {
+                epicKey: ek,
+                ticketKey: tk,
+            });
+            return {
+                verdict: freshness.verdict,
+                deadlineExpired: freshness.deadlineExpired,
+                blockedAdvanceReason: freshness.blockedAdvanceReason,
+            };
+        },
         // BAPI-442 seams are wired at the reconcileDeps level inside runEpicTick
         // (they need the per-tick `access` and `prBindings` closure). The factory
         // returns the dispatchSeam with isReReview support; the other two seams are

package/build/conductor/errors.js

@@ -100,6 +100,37 @@ export class ConductorLedgerSubprocessRuntimeError extends Error {
         this.envVar = envVar;
     }
 }
+/** Plain-session tools that answer the same questions without worker context. */
+const WORKER_CONTEXT_ALTERNATIVES = "get_epic_snapshot, poll_events";
+/**
+ * Raised (BAPI-772) when a worker-SCOPED operation is called from a plain MCP
+ * session — one that was never spawned by the conductor, so the worker
+ * environment is ABSENT rather than broken.
+ *
+ * This is a guidance envelope, not a fault: `check_messages` and the
+ * `wait_for_done_gate` emit leg used to surface an opaque validation error or a
+ * 503 in an ordinary session, leaving the caller to guess that the tool is
+ * worker-scoped at all. The message states where the context comes from and what
+ * to call instead, and is explicit that NO functional fallback was performed.
+ *
+ * Absence only. Worker env that is present but empty, relative, inaccessible, or
+ * otherwise invalid keeps the fail-loud
+ * {@link ConductorLedgerSubprocessRuntimeError} path — a corrupted runtime must
+ * never be relabeled as "you are just in a normal session".
+ */
+export class ConductorWorkerContextRequiredError extends Error {
+    missingEnvVars;
+    constructor(missingEnvVars) {
+        // Single-line, path-free, secret-free (the committed CLI-stderr invariant in
+        // security-regressions.test.ts requires it). Names only fixed env-var tokens.
+        super("This operation is available only inside a conductor-spawned worker session " +
+            "(created by `start-tickets --conductor` or an executor job). Missing worker " +
+            `context: ${missingEnvVars.join(", ")}. No fallback was performed. In a plain ` +
+            `session use ${WORKER_CONTEXT_ALTERNATIVES} instead.`);
+        this.name = "ConductorWorkerContextRequiredError";
+        this.missingEnvVars = missingEnvVars;
+    }
+}
 /**
  * Structural guard for a native-module-load failure raised by the conductor
  * store (BAPI-526). Detected structurally (by `name` + a valid `details` object)
@@ -225,6 +256,22 @@ export function toConductorErrorEnvelope(error) {
             details: { env_var: error.envVar, reason: error.reason },
         };
     }
+    // Worker-context guidance (BAPI-772): the caller is in a plain MCP session and
+    // the worker environment is ABSENT. A 400 (the module's context-required
+    // convention, shared with EPIC_TICK_V1_FROZEN) rather than a 503: nothing is
+    // broken and nothing becomes available by retrying. `details` carries only the
+    // fixed env-var NAMES — never their values, a path, argv, stderr, or a stack.
+    if (error instanceof ConductorWorkerContextRequiredError) {
+        return {
+            error: "WORKER_CONTEXT_REQUIRED",
+            status: 400,
+            message: error.message,
+            details: {
+                missing_env_vars: error.missingEnvVars.join(","),
+                alternatives: WORKER_CONTEXT_ALTERNATIVES,
+            },
+        };
+    }
     if (error instanceof ConductorValidationError) {
         // Validation messages are conductor-authored and name the offending field,
         // never its value — but redact defensively so an adversarial/secret-bearing