@bridge_gpt/mcp-server 0.2.12 → 0.2.13

package/README.md

@@ -218,6 +218,8 @@ The MCP server also checks for updates automatically on startup. If a newer vers
 
 This is the Bridge API tooling worth knowing about as a software engineer — the things you'd ask an agent to do — grouped by how often you would use them. Each entry covers **what it does**, **when it's useful** and **how to use it**. The behind-the-scenes plumbing is summarized at the end under [Extra Capabilities](#extra-capabilities), and a full enumeration lives in [Reference](#reference).
 
+Working in a Salesforce B2C Commerce codebase? Bridge also ships read-only SFCC platform-introspection tools — see [Salesforce B2C Commerce (SFCC) Tools](#salesforce-b2c-commerce-sfcc-tools).
+
 For invocation, prefer the slash command — it's deterministic. A free-text example is shown only where natural-language phrasing reliably maps to the right automation; high-consequence or easily-misread automations show only the slash command on purpose.
 
 ### Tier 1 — Regularly useful
@@ -401,6 +403,66 @@ Behind-the-scenes capabilities an agent gains from the MCP tools — mostly invo
 - **Retrieve any generated artifact** (`get_*` for plans, critiques, questions, brainstorms, research, architecture) without regenerating it.
 - **Tiered-section execution telemetry** recording (internal measurement).
 
+## Salesforce B2C Commerce (SFCC) Tools
+
+Salesforce's official MCP server, `@salesforce/b2c-dx-mcp`, covers developer-experience tasks — cartridge deploy, step debugging, docs search, logs/MRT, and SCAPI Custom API scaffolding. As of its current toolset it has no way to *read* the platform's object model, custom objects, or site configuration — exactly the context an AI coding agent needs to write correct Commerce code and to inspect a sandbox before touching it. Bridge's SFCC tools install side-by-side with `b2c-dx-mcp` (they don't duplicate its surface) and close that gap with **read-only OCAPI Data API introspection** of system objects, custom object definitions, and site preferences.
+
+**v1 is read-only and developer-sandbox-only** — no writes, and non-sandbox instances are rejected. Credentials stay local (in `dw.json` or `SFCC_*` env vars) and are never sent to Bridge.
+
+<details>
+<summary><strong>Setup</strong></summary>
+
+The two diagnostic tools (`sfcc_setup_status`, `check_permissions`) are always available. The seven read tools must be enabled with a profile (step 3).
+
+**Prerequisites:** a running SFCC **sandbox** and its hostname, plus an Account Manager API client (`client-id` + `client-secret`).
+
+**1. Set the repo `version` config field** to your SFCC project type — one of `sfra | pwakit | sitegenesis | storefrontnext | hybrid`. The call-time gate reads this; a non-SFCC value blocks every SFCC tool except `sfcc_setup_status`. Set it via your normal config path, the `config_field` MCP tool (operation `update`, field `version`), or the `/teach-bridge` skill.
+
+**2. Provide SFCC credentials.** Create a `dw.json` in your project root:
+
+```json
+{
+  "hostname": "zzzz-001.sandbox.us01.dx.commercecloud.salesforce.com",
+  "client-id": "<account-manager-client-id>",
+  "client-secret": "<account-manager-client-secret>"
+}
+```
+
+Accepted key spellings: `hostname`/`host`, `client-id`/`clientId`/`client_id`, `client-secret`/`clientSecret`/`client_secret`. Prefer a single config — a multi-entry `configs[]` array forces you to pass an explicit `instance` on every call. `dw.json` is auto-added to git exclude and must never be committed. Alternatively, export `SFCC_HOSTNAME` / `SFCC_CLIENT_ID` / `SFCC_CLIENT_SECRET` in the MCP server environment.
+
+**3. Enable the read tools.** Add `sfcc` to `BRIDGE_MCP_PROFILE` in the MCP server `env` block (it is comma-separated; `full` also works), then **restart the MCP client**:
+
+```json
+"env": { "BRIDGE_MCP_PROFILE": "sfcc" }
+```
+
+Without this, only the diagnostic tools are registered.
+
+**4. Verify and grant OCAPI access.** Ask your agent to run `sfcc_setup_status` (expect all checks ✓), then `check_permissions`. If it reports HTTP 401/403, it prints the exact OCAPI Settings JSON to paste in Business Manager (**Administration → Site Development → Open Commerce API Settings → Data API** tab); save it there and re-run. Restart the MCP client after any credential or env change — a running session does not pick them up.
+
+</details>
+
+### Tools
+
+All SFCC tools are read-only and target a developer sandbox. Oversized responses are automatically saved to `BAPI_DOCS_DIR/sfcc/` and previewed inline.
+
+**Diagnostics** (always available, no profile needed)
+- `sfcc_setup_status` — report on every prerequisite: Bridge API key, repo name, `version` config, `dw.json` presence/uniqueness, and AM token acquisition.
+- `check_permissions` — probe OCAPI access via `GET /system_object_definitions`; on 401/403, print the exact OCAPI Settings JSON to paste in Business Manager (split read-only vs. write/import grants).
+
+**System object model** (needs the `sfcc` profile)
+- `system_object_list` — list system object types (Product, Order, Customer, …).
+- `system_object_get` — fetch one type's definition, optionally with its full attribute definitions (`expand_attribute_definitions`).
+- `system_object_attribute_search` — search a type's attribute definitions; prefer this over a full dump when hunting a specific `c_` custom attribute.
+
+**Custom object definitions** (needs the `sfcc` profile)
+- `custom_object_definition_list` — list custom object type definitions.
+- `custom_object_definition_get` — fetch an existing custom type with its key definition and attribute definitions/groups. Read-only — creating a custom object *type* isn't possible via OCAPI; that's a future v2 metadata-import capability.
+
+**Site preferences** (needs the `sfcc` profile; sandbox only)
+- `site_preference_get` — read a preference group's effective preferences.
+- `site_preference_search` — search/filter preferences within a group.
+
 ## CLI Subcommands
 
 Beyond `--init` / `--upgrade`, the package ships operational subcommands of the **single `bridge-api-mcp-server` bin** (not separate binaries) — so they travel with the package to every consumer. See [Usage Documentation → Start Tickets](#tier-1--regularly-useful) for *when* to use `start-tickets`; this section is the full CLI reference.
@@ -591,7 +653,7 @@ Reports are written to `<BAPI_DOCS_DIR>/smoke-test/REPORT-<host>-<timestamp>.md`
 | `BAPI_WORKTRUNK_BIN` | No | `wt` (`git-wt` on Windows) | Override the Worktrunk executable name/path used by `start-tickets` for nonstandard installs |
 | `BAPI_TMUX_SESSION` | No | `bridge-start-tickets` | Override the tmux session-name prefix used by `start-tickets` on Linux |
 | `BAPI_MCP_UPGRADE_ADVICE_ENABLED` | No | _(enabled)_ | MCP-local opt-out for proactively surfacing upgrade advice in pipeline recipe preambles. Set to `false`/`0`/`no`/`off`/`disabled` to suppress. Disabling it does **not** change the `/jira/ping` response or server-side upgrade computation — it only gates the recipe-preamble convention |
-| `BRIDGE_MCP_PROFILE` | No | `core` | Startup-time tool registration profile. Controls which tool groups are registered when the server starts. Valid values: `core` (default — normal coding tools only), `conductor` (core + 8 conductor/event/supervisor tools), `pipeline-authoring` (core + 5 pipeline run/admin tools — `get_pipeline_recipe` is NOT gated; it stays in `core` because the recipe-driven slash commands depend on it), `full` (all tools, equivalent to the legacy unconditional registration). Unknown, blank, or malformed values fail safe to `core`. Dynamic mid-session switching via `tools/list_changed` is unsupported — the profile is resolved once at process startup. **Phase 2b note:** epic/conductor sessions launched via `start-tickets` will automatically inject `BRIDGE_MCP_PROFILE=conductor`; that injection is handled at the spawn boundary and is out of scope for this phase. |
+| `BRIDGE_MCP_PROFILE` | No | `core` | Startup-time tool registration profile — a **comma-separated** list of groups controlling which tool groups are registered when the server starts. `core` is always implicitly included. Valid groups: `core` (default — normal coding tools only), `conductor` (+ 8 conductor/event/supervisor tools), `pipeline-authoring` (+ 5 pipeline run/admin tools — `get_pipeline_recipe` is NOT gated; it stays in `core` because the recipe-driven slash commands depend on it), `sfcc` (+ the 7 heavy SFCC read tools — see [Salesforce B2C Commerce (SFCC) Tools](#salesforce-b2c-commerce-sfcc-tools); the `sfcc_setup_status`/`check_permissions` diagnostics are always registered regardless), and `full` (shortcut that expands to every group). Example: `sfcc,conductor`. Unknown, blank, or malformed tokens are dropped (falling back to `core`). Dynamic mid-session switching via `tools/list_changed` is unsupported — groups are resolved once at process startup. Conductor/epic sessions launched via `start-tickets --conductor` automatically inject `BRIDGE_MCP_PROFILE=conductor` at the spawn boundary; a normal `start-tickets` run stays on `core`. |
 
 ## Worktree credentials and the `mcp-invoke` shim
 

package/build/conductor/doctor.js

@@ -7,6 +7,7 @@
  * failure. This module performs NO writes: no hook installation, no schema
  * migration, no event emission, and no scheduler unit creation.
  */
+import { spawnSync } from "node:child_process";
 import { doctorConductorLedger } from "./store.js";
 import { inspectConductorGitHooks } from "./git-hooks.js";
 /**
@@ -105,6 +106,65 @@ export function inspectMcpProfile(env, epicTick) {
     }
     return { resolved_profile, conductor_context_detected, degraded, warnings };
 }
+/**
+ * Read-only probe of the local-merge (F4) capability. Runs `gh --version` and
+ * `gh auth status` (no writes, no merge) and reports whether the host could merge
+ * a PR locally if `policy_json.local_merge.enabled` were set. Never throws.
+ */
+export function inspectLocalMerge(runCommand) {
+    const run = runCommand ??
+        ((cmd, args) => {
+            try {
+                // Static ESM import (this package is "type": "module"): a lazy
+                // require("child_process") throws ReferenceError under ESM, which the
+                // catch swallowed — making `gh` always look unavailable (false negative).
+                //
+                // `gh auth status` hits api.github.com; with no timeout a network stall
+                // (expired token, DNS hiccup, partition) blocks the doctor process until
+                // the OS TCP timeout fires (30s–2min). Bound it to 10s — a hung health
+                // check then simply reports `gh` unavailable. GH_PROMPT_DISABLED keeps an
+                // interactive prompt from holding the process past the timeout.
+                const r = spawnSync(cmd, args, {
+                    encoding: "utf8",
+                    timeout: 10_000,
+                    env: { ...process.env, GH_PROMPT_DISABLED: "1" },
+                });
+                return { status: r.status };
+            }
+            catch {
+                return { status: null };
+            }
+        });
+    let gh_available = false;
+    let gh_authed = false;
+    try {
+        gh_available = run("gh", ["--version"]).status === 0;
+    }
+    catch {
+        gh_available = false;
+    }
+    if (gh_available) {
+        try {
+            gh_authed = run("gh", ["auth", "status"]).status === 0;
+        }
+        catch {
+            gh_authed = false;
+        }
+    }
+    const warnings = [];
+    if (!gh_available) {
+        warnings.push("`gh` is not installed or not on PATH. Local merge (policy_json.local_merge.enabled) " +
+            "cannot run; install the GitHub CLI to enable conductor-driven merges.");
+    }
+    else if (!gh_authed) {
+        warnings.push("`gh` is installed but not authenticated (`gh auth status` failed). Run `gh auth login` " +
+            "to grant the conductor merge permission; otherwise local merge will emit merge.failed/skip.");
+    }
+    // Capability gap only — local merge is opt-in, so an unauthed host is not a hard
+    // failure unless the operator enabled it. Reported as degraded for visibility.
+    const degraded = !gh_available || !gh_authed;
+    return { gh_available, gh_authed, degraded, warnings };
+}
 /**
  * Build the combined read-only doctor report. Composes the existing ledger
  * doctor, git hook inspection, and the epic-tick schedule enablement check.
@@ -120,6 +180,7 @@ export async function buildConductorDoctorReport(deps = {}) {
         git_hooks: inspectHooks(deps.hooksDeps),
         epic_tick: epicTick,
         mcp_profile,
+        local_merge: inspectLocalMerge(deps.runCommand),
     };
 }
 /**
@@ -128,7 +189,7 @@ export async function buildConductorDoctorReport(deps = {}) {
  * status tags consistent with the git hooks section's visual hierarchy.
  */
 export function formatConductorDoctorReport(report) {
-    const { ledger, git_hooks, epic_tick, mcp_profile } = report;
+    const { ledger, git_hooks, epic_tick, mcp_profile, local_merge } = report;
     const lines = [
         "Conductor ledger doctor",
         "───────────────────────",
@@ -193,5 +254,21 @@ export function formatConductorDoctorReport(report) {
         for (const w of mcp_profile.warnings)
             lines.push(`  - ${w}`);
     }
+    lines.push("");
+    lines.push("Local merge capability (optional, opt-in)");
+    lines.push("─────────────────────────────────────────");
+    const ghTag = local_merge.gh_available
+        ? local_merge.gh_authed
+            ? "[OK]"
+            : "[WARNING] not authenticated"
+        : "[WARNING] not installed";
+    lines.push(`gh available:          ${local_merge.gh_available} ${ghTag}`);
+    lines.push(`gh authenticated:      ${local_merge.gh_authed}`);
+    lines.push(`degraded:              ${local_merge.degraded}`);
+    if (local_merge.warnings.length > 0) {
+        lines.push("local merge warnings:");
+        for (const w of local_merge.warnings)
+            lines.push(`  - ${w}`);
+    }
     return lines.join("\n");
 }

package/build/conductor/epic-runtime.js

@@ -20,6 +20,8 @@
 import { spawnSync } from "child_process";
 import { resolveConductorBridgeApiAccess, claimEpicSupervisionLease, fetchEpicRunState, advanceEpicTicketStatus, createEpicTicketStatus, recordEpicDispatch, transitionEpicDispatch, fetchParseStatus, triggerRepositoryParse, getEpicPlan, buildEpicDispatchKey, fetchEffectiveSupervisorConfig, fetchEffectiveSupervisorSetup, fetchPrReviewStatus, remediateEpicTicket, deletePullRequestBranch, transitionJiraStatus, } from "./bridge-api-client.js";
 import { processGateMetMerge } from "./supervisor-merge.js";
+import { makeLocalMergeExecutor, resolveLocalMergeMethod } from "./local-merge.js";
+import { emitConductorEventIfNew } from "./producer-ledger.js";
 import { rebuildObservedState, extractWorkerLiveness, } from "./epic-state.js";
 import { reconcileEpic } from "./epic-reconcile.js";
 import { buildSupervisorRemediationWorkerMessage } from "./supervisor-message-relay.js";
@@ -38,12 +40,15 @@ const DEFAULT_LEASE_TTL_SECONDS = 120;
 const DEFAULT_MAX_DRIFT_MS = 30_000;
 const DEFAULT_DISPATCH_KEY_TTL_SECONDS = 300; // independent of supervision lease TTL
 const ACTIVE_WORKER_STATUSES = new Set(["dispatched", "running"]);
+// ---------------------------------------------------------------------------
+// Module-private helpers
+// ---------------------------------------------------------------------------
 /**
- * Module-level transient map keyed by `"${epicKey}:${ticketKey}"`. Cleared on
- * parse completion or budget exhaustion. Process-restart safe: re-derived from
- * the parse lock status on the next tick.
+ * Source + producer tags for the durable `parse.triggered` marker that the
+ * parse-after-merge wait emits from the epic-tick process.
  */
-const parseWaitStateMap = new Map();
+const PARSE_WAIT_EVENT_SOURCE = "conductor-supervisor";
+const PARSE_WAIT_EVENT_PRODUCER = "epic-parse-wait";
 function defaultLeaseOwner() {
     return `epic-tick-${process.pid}`;
 }
@@ -220,17 +225,22 @@ export async function runEpicTick(options, deps = {}) {
             const settleMs = 5000;
             const fetchParseStatusFn = deps.fetchParseStatus ?? fetchParseStatus;
             const triggerParseFn = deps.triggerParse ?? triggerRepositoryParse;
+            const emitConductorEventFn = deps.emitConductorEvent ?? emitConductorEventIfNew;
             for (let i = 0; i < observed.unfolded_terminal_signals.length; i++) {
                 const signal = observed.unfolded_terminal_signals[i];
                 if (signal.signal_type !== "merge.succeeded")
                     continue;
                 const ticketKey = signal.ticket_key;
-                const stateKey = `${epic_key}:${ticketKey}`;
-                let pState = parseWaitStateMap.get(stateKey);
-                if (!pState) {
-                    pState = {};
-                    parseWaitStateMap.set(stateKey, pState);
-                }
+                const mergeEvent = signal.event;
+                const mergeTimeMs = new Date(mergeEvent.time).getTime();
+                // rebuildObservedState only surfaces a merge.succeeded whose run_id maps to
+                // a tracked dispatch, so mergeRunId is non-null and in the run-scoped
+                // localEvents read — binding the parse.triggered marker to it guarantees a
+                // later tick re-reads it. The merged PR head SHA (pre-merge) lives under
+                // the merge.* event's data.details; used only as an extra dedupe dimension.
+                const mergeRunId = mergeEvent.run_id ?? null;
+                const mergeDetails = mergeEvent.data?.details;
+                const mergeHeadSha = typeof mergeDetails?.head_sha === "string" ? mergeDetails.head_sha : undefined;
                 const revertSignal = () => {
                     const origStatus = epicRunState.ticket_statuses.find((ts) => ts.ticket_key === ticketKey)?.status ??
                         "running";
@@ -238,27 +248,72 @@ export async function runEpicTick(options, deps = {}) {
                     observed.unfolded_terminal_signals.splice(i, 1);
                     i -= 1;
                 };
-                const elapsedMs = nowFn() - new Date(signal.event.time).getTime();
-                // Budget exhaustion: escalate once, then permanently block
+                const currentPgStatus = epicRunState.ticket_statuses.find((ts) => ts.ticket_key === ticketKey)?.status ?? null;
+                // DURABLE wait state (replaces the former in-memory parseWaitStateMap, which
+                // was lost between stateless epic-tick processes → re-triggered the parse on
+                // every idle tick and never folded to `done`). The marker is a
+                // `parse.triggered` ledger event correlated to this ticket's dispatch run_id
+                // and emitted strictly after the merge — so its presence is the skew-free
+                // signal that the post-merge parse was already kicked off.
+                const parseTriggeredEvent = localEvents.find((e) => e.type === "parse.triggered" &&
+                    e.subject === ticketKey &&
+                    e.run_id === mergeRunId &&
+                    new Date(e.time).getTime() >= mergeTimeMs);
+                const elapsedMs = nowFn() - mergeTimeMs;
+                // Budget exhaustion (measured from the durable merge.succeeded time):
+                // escalate once (gated on the durable Postgres status, not an in-memory
+                // flag) then block. A subsequent tick finds it already blocked and drops
+                // the signal without re-escalating or re-CASing.
                 if (elapsedMs > maxWaitMs) {
-                    if (!pState.escalated) {
-                        await escalateOnce(epic_key, `parse-after-merge budget exhausted for ${ticketKey}`);
-                        pState.escalated = true;
-                        signal.next_status = "blocked";
+                    if (currentPgStatus === "blocked") {
                         observed.ticket_statuses.set(ticketKey, "blocked");
-                        // Let the signal remain so the reconcile pass CASes once to blocked
-                        continue;
-                    }
-                    else {
-                        // Already escalated: map to blocked and skip redundant CAS
-                        observed.ticket_statuses.set(ticketKey, "blocked");
-                        parseWaitStateMap.delete(stateKey);
                         observed.unfolded_terminal_signals.splice(i, 1);
                         i -= 1;
                         continue;
                     }
+                    await escalateOnce(epic_key, `parse-after-merge budget exhausted for ${ticketKey}`);
+                    signal.next_status = "blocked";
+                    observed.ticket_statuses.set(ticketKey, "blocked");
+                    // Let the signal remain so the reconcile pass CASes once to blocked.
+                    continue;
+                }
+                if (!parseTriggeredEvent) {
+                    // No durable trigger for this merge yet — fire the parse and record the
+                    // marker, then hold at ready_for_review for a later tick to fold.
+                    try {
+                        await triggerParseFn(access);
+                        emitConductorEventFn({
+                            source: PARSE_WAIT_EVENT_SOURCE,
+                            type: "parse.triggered",
+                            subject: ticketKey,
+                            run_id: mergeRunId,
+                            worker_id: mergeEvent.worker_id ?? null,
+                            producer: PARSE_WAIT_EVENT_PRODUCER,
+                            observed_via: "supervisor",
+                            time: new Date(nowFn()).toISOString(),
+                            data: {
+                                summary: `parse-after-merge triggered for ${ticketKey}`,
+                                details: {
+                                    epic_key,
+                                    ticket_key: ticketKey,
+                                    ...(mergeHeadSha ? { head_sha: mergeHeadSha } : {}),
+                                },
+                            },
+                        }, {
+                            event_type: "parse.triggered",
+                            run_id: mergeRunId ?? undefined,
+                            commit_sha: mergeHeadSha,
+                        });
+                        log(`[epic-tick] triggered parse-after-merge for ${ticketKey} in epic=${epic_key}`);
+                    }
+                    catch (err) {
+                        const safeMsg = err instanceof Error ? err.constructor.name : "trigger error";
+                        errorLog(`[epic-tick] parse trigger failed (${safeMsg}) for ${ticketKey}; will retry next tick`);
+                    }
+                    revertSignal();
+                    continue;
                 }
-                // Poll the parse lock
+                // A durable parse.triggered exists for this merge — poll the live lock.
                 let parseStatusResult;
                 try {
                     parseStatusResult = await fetchParseStatusFn(access);
@@ -270,38 +325,26 @@ export async function runEpicTick(options, deps = {}) {
                     continue;
                 }
                 if (parseStatusResult.status === "in_progress") {
-                    pState.seenInProgress = true;
+                    // Parse still running — hold.
                     revertSignal();
                     continue;
                 }
-                // status === "idle" — evaluate race guard and completion
-                if (pState.seenInProgress) {
-                    // Previously observed in_progress: the parse finished normally
-                    parseWaitStateMap.delete(stateKey);
-                    continue; // let the signal proceed to CAS → done
-                }
-                if (pState.triggeredAt !== undefined) {
-                    const msSinceTrigger = nowFn() - pState.triggeredAt;
-                    if (msSinceTrigger < settleMs) {
-                        // Idle observed before the async job acquired its lock (race window)
-                        revertSignal();
-                        continue;
-                    }
-                    // Settle window elapsed without in_progress: treat as instantaneous completion
-                    parseWaitStateMap.delete(stateKey);
-                    continue; // let the signal proceed to CAS → done
-                }
-                // No trigger yet — fire it now
-                try {
-                    await triggerParseFn(access);
-                    pState.triggeredAt = nowFn();
-                    log(`[epic-tick] triggered parse-after-merge for ${ticketKey} in epic=${epic_key}`);
-                }
-                catch (err) {
-                    const safeMsg = err instanceof Error ? err.constructor.name : "trigger error";
-                    errorLog(`[epic-tick] parse trigger failed (${safeMsg}) for ${ticketKey}; will retry next tick`);
+                // status === "idle". If the marker is younger than the settle window, the
+                // async parse may not have acquired its lock yet (idle is a false negative)
+                // — hold one more tick. Past the settle window, idle means the post-merge
+                // parse has completed (or finished instantly), so let the merge.succeeded
+                // signal proceed to CAS → done.
+                //
+                // KNOWN LIMITATION: /jira/parse-status only reports {in_progress, idle} —
+                // it cannot distinguish a FAILED parse from a completed one, so an instant
+                // parse failure folds to `done` here. Pre-existing; tracked as P2 (surface
+                // a parse failure/last_error from parse-status).
+                const msSinceTrigger = nowFn() - new Date(parseTriggeredEvent.time).getTime();
+                if (msSinceTrigger < settleMs) {
+                    revertSignal();
+                    continue;
                 }
-                revertSignal();
+                // Completed: do not revert — the signal proceeds to CAS → done.
             }
         }
         // Step 4: Fetch + assert plan integrity (only if fetchPlan injected)
@@ -486,7 +529,27 @@ export async function runEpicTick(options, deps = {}) {
                     });
                 },
                 dispatchSeam: async (ek, tk, attempt = 0) => dispatchSeam(ek, tk, attempt),
-                processMerge: async (acc, event) => processMergeFn(acc, event),
+                processMerge: async (acc, event) => {
+                    // F4: when policy_json.local_merge.enabled is set (opt-in, default OFF)
+                    // and the caller did not inject a processMerge stub, run the real merge
+                    // pipeline with a LOCAL executor swapped in for the backend route — the
+                    // merge happens here using the agent's own `gh` credentials, so the
+                    // hosted backend never needs global GitHub write scope. Otherwise the
+                    // default backend-route path is unchanged for all existing users.
+                    if (deps.processMerge === undefined) {
+                        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                        const localCfg = epicRunState.epic_run.policy_json?.local_merge;
+                        if (localCfg?.enabled === true) {
+                            return processGateMetMerge(acc, event, {
+                                merge: makeLocalMergeExecutor({
+                                    method: resolveLocalMergeMethod(localCfg.method),
+                                    approvalRequired: localCfg.approval_required === true,
+                                }, { env: process.env }),
+                            });
+                        }
+                    }
+                    return processMergeFn(acc, event);
+                },
                 postActionWaitSeam: async (ek, tk) => postActionWaitSeam(ek, tk),
                 escalateOnce: async (ek, reason) => escalateOnce(ek, reason),
                 log,
@@ -812,12 +875,21 @@ export async function buildProductionEpicRuntimeDeps(epicKey) {
                 dryRun: dispatchDryRun,
                 autoApprove: true,
                 maxParallel: 1,
-                refreshMain: false,
+                // F-base: a merge-gated dependent MUST cut from the predecessor's merged
+                // code. With refreshMain:false the worktree was cut from a STALE local
+                // `main` (never fetched/ff'd after the predecessor merged on origin), so
+                // dependents built without the predecessor's code — defeating the whole
+                // merge-gated handoff. Refresh (fetch origin + ff local base) before cut.
+                refreshMain: true,
                 branchOverrides: {},
                 baseBranch: "main",
                 conductorEnabled: true,
                 // BAPI-441: re-dispatch reuses the existing branch/worktree.
                 resumeMode: isResume,
+                // F7: on a FRESH dispatch, refuse a stale leftover `feature/<KEY>` branch
+                // (e.g. a prior run's worktree) rather than silently building on it. No
+                // effect on resume (which reuses a located worktree via a different path).
+                guardStaleWorktree: !isResume,
             }, {
                 createConductorContext: createStartTicketsConductorContext,
                 provisionConductorHooksForRows,

package/build/conductor/epic-state.js

@@ -193,6 +193,14 @@ export function rebuildObservedState(postgresState, events, _now) {
     const pendingMergeEvents = [];
     // Track which tickets already have a folded signal (one override per ticket)
     const foldedTicketKeys = new Set();
+    // Track which tickets already have a gate.met queued for merge this tick, so a
+    // second gate.met for the same ticket never double-enqueues. Distinct from
+    // foldedTicketKeys: a prior run.stopped fold (→ ready_for_review) must NOT
+    // suppress a later gate.met's merge enqueue (both map to ready_for_review;
+    // only gate.met enqueues a merge, and the worker frequently emits run.stopped
+    // BEFORE a post-hoc gate.met). Only a fold to a non-mergeable status (blocked)
+    // suppresses the merge — handled via the effective-status check below.
+    const mergeQueuedTicketKeys = new Set();
     // BAPI-441: per-ticket latest blocking reason (ci.failed / review.changes_requested),
     // tracked across the full ledger so an already-blocked ticket still carries a
     // reason for the remediation pass to frame the nudge.
@@ -233,12 +241,19 @@ export function rebuildObservedState(postgresState, events, _now) {
         const postgresStatus = ticketStatusMap.get(ticketKey) ?? "planned";
         if (!isNonTerminal(postgresStatus))
             continue;
-        // Only queue for merge actioning if this ticket hasn't already been folded
-        // this tick. Without this guard, two gate.met events for the same ticket
-        // would both enqueue, and a ci.failed → gate.met sequence would enqueue a
-        // merge action for a ticket whose effective status is "blocked".
-        if (event.type === "gate.met" && !foldedTicketKeys.has(ticketKey)) {
+        // Queue gate.met for merge actioning unless (a) this ticket's effective
+        // status this tick is non-mergeable ("blocked" — e.g. a ci.failed that
+        // folded earlier in the same batch, or a Postgres-blocked ticket whose
+        // ci.failed re-folds every tick), or (b) a gate.met for it is already
+        // queued. `postgresStatus` already reflects same-tick folds (the loop
+        // mutates `ticketStatusMap`), so a prior run.stopped fold leaves it
+        // "ready_for_review" and the merge proceeds — fixing the deadlock where a
+        // worker's run.stopped (lower seq) suppressed a later operator/CI gate.met.
+        if (event.type === "gate.met" &&
+            postgresStatus !== "blocked" &&
+            !mergeQueuedTicketKeys.has(ticketKey)) {
             pendingMergeEvents.push(event);
+            mergeQueuedTicketKeys.add(ticketKey);
         }
         const signalType = event.type;
         const nextStatus = signalToNextStatus(signalType, isReview);