@cortexkit/aft-bridge 0.60.0 → 0.62.0

package/dist/subc-transport.js

@@ -17,8 +17,9 @@
  * published plugin dist; it is never a published runtime dependency.
  */
 import { statSync } from "node:fs";
-import { AuthError, connectionFileExists, isConsumerReconnectTransient, routeCloseReason, SocketTimeoutError, StaleRouteHandleError, SubcCallError, SubcClient, SubcError, } from "@cortexkit/subc-client";
+import { AuthError, connectionFileExists, isConsumerReconnectTransient, routeCloseReason, SocketClosedError, SocketTimeoutError, StaleRouteHandleError, SubcCallError, SubcClient, SubcError, } from "@cortexkit/subc-client";
 import { log, warn } from "./active-logger.js";
+import { isTerminalStatus } from "./bash-format.js";
 import { isRouteOpenReloadWindowError, isRouteRequestReloadRefusal } from "./error-contract.js";
 import { asCanonicalRootPath, asRootGeneration, LifecycleRegistry, } from "./lifecycle-registry.js";
 import { canonicalizeProjectRoot } from "./project-identity.js";
@@ -170,6 +171,81 @@ export function isSocketDeathError(error, depth = 0) {
     }
     return isConsumerReconnectTransient(error) || isSubcClientClosedError(error);
 }
+/** Typed system codes for a reset or broken connected socket. */
+const REQUEST_CONNECTION_LOSS_CODES = new Set(["ECONNABORTED", "ECONNRESET", "EPIPE"]);
+function hasRequestConnectionLossCode(error) {
+    if (typeof error !== "object" || error === null || !("code" in error))
+        return false;
+    return typeof error.code === "string" && REQUEST_CONNECTION_LOSS_CODES.has(error.code);
+}
+function hasRequestConnectionLossEvidence(error, depth = 0) {
+    if (error instanceof SocketClosedError)
+        return true;
+    if (error instanceof SubcError && error.closeReason === "connection_lost")
+        return true;
+    if (hasRequestConnectionLossCode(error))
+        return true;
+    if (!(error instanceof SubcCallError) ||
+        error.kind !== "outcome_unknown" ||
+        depth >= 4 ||
+        error.cause === undefined ||
+        error.cause === error) {
+        return false;
+    }
+    return hasRequestConnectionLossEvidence(error.cause, depth + 1);
+}
+/**
+ * A raw request first checks `closedErr`, then records itself pending and starts
+ * `writeBorrowed` in the same synchronous send(). A later read-loop failure goes
+ * through fail(), which rejects route-pending requests as SubcError with
+ * closeReason="connection_lost". That proves the request write was attempted,
+ * but the raw request API does not expose whether the socket queued those bytes;
+ * the outcome must therefore stay unknown, not be retried.
+ *
+ * The timer path is different: it rejects with code="request_deadline" while
+ * leaving the shared socket potentially live. Read/body timeouts reach fail() and
+ * get the connection-lost close reason; a direct SocketTimeoutError from writing
+ * can be before or after queueing. The socket's queued/not-queued write wrappers
+ * are stripped by the raw write helper, so neither a bare timeout nor a bare
+ * SocketClosedError alone identifies the write state. The latter remains
+ * supported for older clients that rejected pending calls with that class.
+ * Explicit kind="not_sent" is authoritative and always wins over these shapes.
+ */
+function connectionClosedAfterDispatch(error) {
+    if (error instanceof SubcCallError && error.kind === "not_sent")
+        return error;
+    if (typeof error === "object" && error !== null && "kind" in error && error.kind === "not_sent") {
+        return error;
+    }
+    if (!hasRequestConnectionLossEvidence(error))
+        return error;
+    if (error instanceof SubcCallError)
+        return error;
+    if (!(error instanceof Error))
+        return error;
+    return Object.assign(error, { kind: "outcome_unknown" });
+}
+/**
+ * Requests that subc-client's own deadline rejected after the request had been
+ * handed to `client.request`. Unlike the same `request_deadline` code on a
+ * route.open (which proves nothing was sent), the request may have reached AFT
+ * and started running, so its outcome is unknown. Kept outside the error
+ * object so the error's class, code, message and retry handling stay as
+ * subc-client made them.
+ */
+const dispatchedRequestDeadlines = new WeakSet();
+function noteDispatchedRequestDeadline(error) {
+    if (error instanceof SubcError && error.code === REQUEST_DEADLINE_CODE) {
+        dispatchedRequestDeadlines.add(error);
+    }
+}
+/**
+ * True for a request that ran out of subc-client's deadline after it was sent,
+ * so AFT may have started it (see `dispatchedRequestDeadlines`).
+ */
+export function isDispatchedRequestDeadlineError(error) {
+    return typeof error === "object" && error !== null && dispatchedRequestDeadlines.has(error);
+}
 /**
  * A call that never got an answer on a socket that may still be alive: the
  * client's own request deadline (raw `request`/`routeOpen` reject with code
@@ -420,8 +496,10 @@ class BgSubscription {
     get attachedRoute() {
         return this.route;
     }
+    cancelBackoff = null;
     async stop() {
         this.stopped = true;
+        this.cancelBackoff?.();
         // Wake a live `await sub.closed`; the loop's `finally` remains the sole
         // owner of closeRouteChannel, avoiding a double close from stop() + run().
         const sub = this.current;
@@ -668,7 +746,39 @@ class BgSubscription {
             giveUp("stopped");
     }
     async backoff(attempt) {
-        await this.sleep(reconnectBackoffMs(attempt));
+        if (this.stopped)
+            return;
+        await new Promise((resolve, reject) => {
+            let timer;
+            let finished = false;
+            const settle = (error) => {
+                if (finished)
+                    return;
+                finished = true;
+                if (timer)
+                    clearTimeout(timer);
+                this.cancelBackoff = null;
+                if (error !== undefined)
+                    reject(error);
+                else
+                    resolve();
+            };
+            this.cancelBackoff = () => settle();
+            const delay = reconnectBackoffMs(attempt);
+            if (this.sleep) {
+                // An injected sleeper may not be cancellable. Observe its eventual
+                // rejection, but let stop release the subscription without awaiting it.
+                try {
+                    void this.sleep(delay).then(() => settle(), settle);
+                }
+                catch (error) {
+                    settle(error);
+                }
+            }
+            else {
+                timer = setTimeout(() => settle(), delay);
+            }
+        });
     }
 }
 function isRecord(value) {
@@ -711,17 +821,25 @@ function callDeadlinePassedError(lastError, callDeadlineMs) {
         return withDeadlineSuffix(lastError, suffix);
     return new SubcError(`route to module '${AFT_MODULE_ID}' was not ready before the call ran out of time.${suffix}`, REQUEST_DEADLINE_CODE);
 }
+export const __withDeadlineSuffixForTests = withDeadlineSuffix;
 function withDeadlineSuffix(error, suffix) {
-    if (error instanceof Error) {
-        try {
-            error.message += suffix;
-            return error;
-        }
-        catch {
-            // A frozen SDK error cannot carry the suffix; retain its message in a wrapper.
-        }
-    }
-    return new Error(`${String(error)}${suffix}`);
+    if (!(error instanceof Error))
+        return new Error(`${String(error)}${suffix}`, { cause: error });
+    const message = `${error.message}${suffix}`;
+    if (error instanceof SubcCallError) {
+        const wrapped = new SubcCallError(error.kind, message, error.code, error);
+        // SubcCallError's detail getter only unwraps a direct SubcError cause.
+        Object.defineProperty(wrapped, "detail", { value: error.detail });
+        return wrapped;
+    }
+    if (error instanceof SubcError) {
+        const wrapped = new SubcError(message, error.code, error.detail, error.closeReason);
+        Object.defineProperty(wrapped, "cause", { value: error });
+        return wrapped;
+    }
+    const wrapped = new Error(message, { cause: error });
+    wrapped.name = error.name;
+    return wrapped;
 }
 /**
  * Fire-and-forget route close that can never throw — neither synchronously (a
@@ -924,7 +1042,29 @@ class SubcTransport {
         // dropping it here would cap long tool executions at the subc client's
         // default unary deadline while the command keeps running module-side.
         const timeoutMs = options.transportTimeoutMs ?? options.timeoutMs;
-        const onProgress = options.onProgress;
+        // subc-client delivers wire bodies; hosts use the same decoded callback
+        // shape as BinaryBridge, regardless of the route carrying the request.
+        const callback = options.onProgress;
+        const onProgress = callback
+            ? (body) => {
+                let frame;
+                try {
+                    frame = JSON.parse(new TextDecoder().decode(body));
+                }
+                catch {
+                    return;
+                }
+                if (typeof frame !== "object" || frame === null)
+                    return;
+                const progress = frame;
+                if (progress.type !== "progress" || typeof progress.chunk !== "string")
+                    return;
+                callback({
+                    kind: progress.kind === "stderr" ? "stderr" : "stdout",
+                    text: progress.chunk,
+                });
+            }
+            : undefined;
         return { preview, timeoutMs, onProgress, abortSignal: options.abortSignal };
     }
 }
@@ -941,7 +1081,7 @@ export class SubcTransportPool {
     hostScopes;
     /** Scope identity is host-session-wide, even when the session uses multiple project roots. */
     hostScopeCache = new Map();
-    hostScopeRefusals = new Set();
+    hostScopeRefusals = new Map();
     hostScopeOutcomes = new Map();
     connectFn;
     onBgEventsNudge;
@@ -1008,8 +1148,7 @@ export class SubcTransportPool {
         this.connectFn = options.connect ?? ((opts) => SubcClient.connect(opts));
         this.onBgEventsNudge = options.onBgEventsNudge;
         this.onBgEventsNudgeRef = options.onBgEventsNudgeRef;
-        this.bgBackoffSleep =
-            options.bgBackoffSleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+        this.bgBackoffSleep = options.bgBackoffSleep;
         this.routeRetrySleep =
             options.routeRetrySleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
         this.bgDispatchProbeIntervalMs =
@@ -1395,8 +1534,12 @@ export class SubcTransportPool {
      * always nudges a drain, replaying completions queued while no carrier existed.
      */
     async reapIdleSessions(now = Date.now()) {
-        for (const [key, state] of this.nudgeDeliveryLogState) {
-            if (now - state.lastEmittedAt >= 15 * 60_000)
+        for (const [key, bucket] of this.nudgeDeliveryLogState) {
+            for (const [kind, state] of bucket) {
+                if (now - state.lastEmittedAt >= 15 * 60_000)
+                    bucket.delete(kind);
+            }
+            if (bucket.size === 0)
                 this.nudgeDeliveryLogState.delete(key);
         }
         const detached = [];
@@ -1484,7 +1627,7 @@ export class SubcTransportPool {
         }
         if (typeof data.task_id === "string") {
             // Terminal tasks remain pinned until the daemon explicitly ACKs them.
-            const terminal = ["completed", "failed", "killed", "timed_out"].includes(String(data.status));
+            const terminal = isTerminalStatus(data.status);
             const running = ["starting", "running", "killing"].includes(String(data.status));
             record.backgroundTasks.set(data.task_id, terminal ? "terminal" : running ? "running" : "unknown");
             if (name === "bash" || name === "powershell")
@@ -1569,15 +1712,19 @@ export class SubcTransportPool {
         };
     }
     logNudgeDelivery(kind, record, message) {
-        const key = `${kind}\u0000${record.identityKey}`;
+        let bucket = this.nudgeDeliveryLogState.get(record.identityKey);
+        if (!bucket) {
+            bucket = new Map();
+            this.nudgeDeliveryLogState.set(record.identityKey, bucket);
+        }
         const now = Date.now();
-        const state = this.nudgeDeliveryLogState.get(key);
+        const state = bucket.get(kind);
         if (state && now - state.lastEmittedAt < BG_LIFECYCLE_LOG_INTERVAL_MS) {
             state.suppressed += 1;
             return;
         }
         const suppressed = state?.suppressed ?? 0;
-        this.nudgeDeliveryLogState.set(key, { lastEmittedAt: now, suppressed: 0 });
+        bucket.set(kind, { lastEmittedAt: now, suppressed: 0 });
         const suffix = suppressed > 0 ? ` suppressed=${suppressed}` : "";
         log(`subc bg_events: ${message}${suffix}`, { sessionId: record.identity.session });
     }
@@ -1622,10 +1769,7 @@ export class SubcTransportPool {
         record.teardownReason = reason;
         this.sessions.delete(key);
         this.removeIndexMembership(record);
-        for (const logKey of this.nudgeDeliveryLogState.keys()) {
-            if (logKey.endsWith(`\u0000${key}`))
-                this.nudgeDeliveryLogState.delete(logKey);
-        }
+        this.nudgeDeliveryLogState.delete(key);
         const bgSub = record.bgSub;
         record.bgSub = null;
         const routeEntry = record.routeEntry;
@@ -1991,7 +2135,7 @@ export class SubcTransportPool {
                     return reply;
                 }
                 catch (requestError) {
-                    const error = frameReadTimeoutError(routeClosedMidCallError(requestError, routeAndEntry.entry, record));
+                    const error = frameReadTimeoutError(routeClosedMidCallError(connectionClosedAfterDispatch(requestError), routeAndEntry.entry, record));
                     if (this.isReapInduced(record))
                         throw this.annotateReapError(error, record);
                     const ownsRoute = this.isCurrentSession(key, record) && this.client === client;
@@ -2038,6 +2182,7 @@ export class SubcTransportPool {
                         continue;
                     }
                     handleRequestFailure(error, routeAndEntry.entry);
+                    noteDispatchedRequestDeadline(error);
                     throw error;
                 }
             }
@@ -2200,21 +2345,45 @@ export class SubcTransportPool {
         return { route: await opening, entry };
     }
     hostScope(client, identity) {
-        if (this.hostScopeRefusals.has(identity.session))
-            return Promise.resolve(undefined);
+        let lookupReason = "cache_miss";
+        const refused = this.hostScopeRefusals.get(identity.session);
+        if (refused) {
+            // A refusal applies to one route-binding attempt, not to the session's future scope.
+            // Look up the host scope again on the next bind instead of leaving later routes unscoped.
+            const previous = this.hostScopeCache.get(identity.session);
+            if (previous)
+                this.cancelHostScopeRetry(previous);
+            this.hostScopeCache.delete(identity.session);
+            this.hostScopeRefusals.delete(identity.session);
+            lookupReason = `previous_bind_refusal code=${refused}`;
+        }
         let state = this.hostScopeCache.get(identity.session);
         if (!state) {
             state = { retryAt: 0, retryMs: HOST_SCOPE_RETRY_FLOOR_MS };
             this.hostScopeCache.set(identity.session, state);
         }
         if (state.answer) {
-            return Promise.resolve(state.answer.result === "scope" && !state.scopeBindPending ? state.answer.scope : undefined);
+            const reason = state.scopeBindPending
+                ? "scope_sync_pending"
+                : `cached_${state.answer.result}`;
+            log(`subc head scope: session=${identity.session} lookup=skipped reason=${reason}`);
+            return Promise.resolve({
+                scope: state.answer.result === "scope" && !state.scopeBindPending
+                    ? state.answer.scope
+                    : undefined,
+                reason,
+            });
         }
-        if (state.pending)
+        if (state.pending) {
+            log(`subc head scope: session=${identity.session} lookup=skipped reason=inflight_lookup`);
             return state.pending;
+        }
         // Backoff skips the lookup, not the bind, so an unavailable core cannot delay every root.
-        if (Date.now() < state.retryAt)
-            return Promise.resolve(undefined);
+        if (Date.now() < state.retryAt) {
+            log(`subc head scope: session=${identity.session} lookup=skipped reason=backoff retry_in=${state.retryAt - Date.now()}ms`);
+            return Promise.resolve({ reason: state.unscopedReason ?? "lookup_backoff" });
+        }
+        log(`subc head scope: session=${identity.session} lookup=started reason=${lookupReason}`);
         const current = state;
         clearTimeout(current.retryTimer);
         current.retryTimer = undefined;
@@ -2223,25 +2392,36 @@ export class SubcTransportPool {
         const lookup = this.readHostScope(client, identity, abort.signal).then((outcome) => {
             // A scope-close push may invalidate the session while the management request is in flight.
             if (this.hostScopeCache.get(identity.session) !== current)
-                return undefined;
+                return { reason: "lookup_invalidated" };
             current.pending = undefined;
             current.lookupAbort = undefined;
             if (abort.signal.aborted)
-                return undefined;
+                return { reason: "lookup_cancelled" };
             this.logHostScopeOutcome(identity.session, outcome);
+            const reason = outcome.result === "error"
+                ? `lookup_error code=${outcome.code}`
+                : `lookup_${outcome.result}`;
             if (outcome.result === "scope" || outcome.result === "no_scope") {
                 current.answer = outcome;
                 current.retryAt = 0;
                 current.retryMs = HOST_SCOPE_RETRY_FLOOR_MS;
-                if (outcome.result === "scope")
-                    this.promoteHostScope(identity.session);
+                if (outcome.result === "scope") {
+                    // After a refusal, confirm daemon acceptance before replacing working fallback routes.
+                    current.promoteAfterBind = Boolean(refused);
+                    if (!current.promoteAfterBind)
+                        this.promoteHostScope(identity.session);
+                }
             }
             else {
+                current.unscopedReason = reason;
                 current.retryAt = Date.now() + current.retryMs;
                 current.retryMs = Math.min(current.retryMs * 2, HOST_SCOPE_RETRY_CAP_MS);
                 this.scheduleHostScopeRetry(identity.session, current);
             }
-            return outcome.result === "scope" ? outcome.scope : undefined;
+            return {
+                scope: outcome.result === "scope" ? outcome.scope : undefined,
+                reason,
+            };
         });
         current.pending = lookup;
         return lookup;
@@ -2304,7 +2484,7 @@ export class SubcTransportPool {
                 retry = this.hostScope(client, record.identity);
             }
             void retry.catch((error) => {
-                warn(`subc head scope: background retry failed code=${error instanceof Error ? error.name : "Error"}`);
+                warn(`subc head scope: session=${session} background retry failed code=${error instanceof Error ? error.name : "Error"}`);
             });
         }, Math.max(0, state.retryAt - Date.now()));
         state.retryTimer.unref();
@@ -2320,8 +2500,8 @@ export class SubcTransportPool {
     }
     refuseHostScopeBind(session, state, code) {
         if (!this.hostScopeRefusals.has(session)) {
-            this.hostScopeRefusals.add(session);
-            warn(`subc head scope: session=${session} scoped bind refused code=${code}; binding unscoped; retry stopped`);
+            this.hostScopeRefusals.set(session, code);
+            warn(`subc head scope: session=${session} scoped bind refused code=${code}; retry stopped until next bind lookup`);
         }
         if (state) {
             state.scopeBindPending = false;
@@ -2332,7 +2512,7 @@ export class SubcTransportPool {
     async retryHostScopeBind(client, identity, state, scope) {
         try {
             // Validate daemon acceptance before retiring a working fallback route or its held requests.
-            const route = await client.routeOpen({ kind: "tool_provider", module_id: AFT_MODULE_ID }, identity, { consumerIdentity: this.consumerIdentity, scope });
+            const route = await this.bindHostToolRoute(client, identity, "scope_probe", "scope_sync_retry", scope);
             safeCloseRoute(client, route);
             if (this.hostScopeCache.get(identity.session) !== state ||
                 !state.scopeBindPending ||
@@ -2341,6 +2521,7 @@ export class SubcTransportPool {
                 !this.unscopedHostRecord(identity.session))
                 return;
             state.scopeBindPending = false;
+            state.promoteAfterBind = false;
             state.retryAt = 0;
             state.retryMs = HOST_SCOPE_RETRY_FLOOR_MS;
             log(`subc head scope: session=${identity.session} scoped bind recovered ref=${scope.ref.slice(0, 8)} epoch=${scope.scopeEpoch}`);
@@ -2496,27 +2677,49 @@ export class SubcTransportPool {
             signal.removeEventListener("abort", cancel);
         }
     }
-    openHostToolRoute(client, identity, record, entry) {
+    openHostToolRoute(client, identity, record, entry, channel = "tool") {
         if (!this.hostScopes ||
             !["opencode", "pi"].includes(identity.harness) ||
             identity.session === DEFAULT_SESSION_ID) {
-            return client.routeOpen({ kind: "tool_provider", module_id: AFT_MODULE_ID }, identity, {
-                consumerIdentity: this.consumerIdentity,
-            });
-        }
-        return this.openScopedHostToolRoute(client, identity, record, entry);
+            const reason = !this.hostScopes
+                ? "host_scopes_disabled"
+                : identity.session === DEFAULT_SESSION_ID
+                    ? "default_session"
+                    : "unsupported_harness";
+            log(`subc head scope: session=${identity.session} lookup=skipped reason=${reason}`);
+            return this.bindHostToolRoute(client, identity, channel, reason);
+        }
+        return this.openScopedHostToolRoute(client, identity, record, entry, channel);
+    }
+    bindHostToolRoute(client, identity, channel, reason, scope) {
+        log(`subc head scope: session=${identity.session} bind=${scope ? "scoped" : "unscoped"} channel=${channel} root=${identity.project_root} reason=${reason}` +
+            (scope ? ` ref=${scope.ref.slice(0, 8)} epoch=${scope.scopeEpoch}` : ""));
+        return client.routeOpen({ kind: "tool_provider", module_id: AFT_MODULE_ID }, identity, {
+            consumerIdentity: this.consumerIdentity,
+            ...(scope ? { scope } : {}),
+        });
     }
-    async openScopedHostToolRoute(client, identity, record, entry) {
-        const scope = await this.hostScope(client, identity);
+    async openScopedHostToolRoute(client, identity, record, entry, channel = "tool") {
+        const decision = await this.hostScope(client, identity);
+        const scope = decision.scope;
+        let reason = decision.reason;
         this.assertRecordLive(record);
         if (scope) {
             try {
-                const route = await client.routeOpen({ kind: "tool_provider", module_id: AFT_MODULE_ID }, identity, { consumerIdentity: this.consumerIdentity, scope });
+                const route = await this.bindHostToolRoute(client, identity, channel, reason, scope);
                 if (entry)
                     entry.hostScope = scope;
+                const state = this.hostScopeCache.get(identity.session);
+                if (state?.promoteAfterBind &&
+                    state.answer?.result === "scope" &&
+                    state.answer.scope === scope) {
+                    state.promoteAfterBind = false;
+                    this.promoteHostScope(identity.session);
+                }
                 return route;
             }
             catch (error) {
+                log(`subc head scope: session=${identity.session} bind=failed channel=${channel} reason=scoped_open_error code=${error instanceof SubcError ? (error.code ?? error.name) : "Error"}`);
                 if (!(error instanceof SubcError) || !error.code || isSocketDeathError(error))
                     throw error;
                 // A restarting provider has not rejected the scope. Keep it for the normal reopen retry.
@@ -2526,22 +2729,27 @@ export class SubcTransportPool {
                 const state = this.hostScopeCache.get(identity.session);
                 if (state && isHostScopeSyncRefusal(error.code)) {
                     this.deferHostScopeBind(identity.session, state, error.code);
+                    reason = `scope_sync_pending code=${error.code}`;
                 }
                 else {
                     this.refuseHostScopeBind(identity.session, state, error.code);
+                    // Look up the host scope again after a cached scoped route is refused,
+                    // before opening an unscoped route.
+                    if (decision.reason === "cached_scope") {
+                        return this.openScopedHostToolRoute(client, identity, record, entry, channel);
+                    }
+                    reason = `scoped_bind_refused code=${error.code}`;
                 }
             }
         }
         this.assertRecordLive(record);
-        const route = await client.routeOpen({ kind: "tool_provider", module_id: AFT_MODULE_ID }, identity, {
-            consumerIdentity: this.consumerIdentity,
-        });
+        const route = await this.bindHostToolRoute(client, identity, channel, reason);
         // Scope recovery can finish while a fallback bind waits for the provider, including bg_events.
         if (this.hostScopeCache.get(identity.session)?.answer?.result === "scope" &&
             !this.hostScopeCache.get(identity.session)?.scopeBindPending &&
             !this.hostScopeRefusals.has(identity.session)) {
             safeCloseRoute(client, route);
-            return this.openScopedHostToolRoute(client, identity, record, entry);
+            return this.openScopedHostToolRoute(client, identity, record, entry, channel);
         }
         return route;
     }
@@ -2596,6 +2804,15 @@ export class SubcTransportPool {
         if (!this.rootCanAttach(record.canonicalRoot))
             return;
         const nudgeRef = this.nudgeRefFor(record);
+        const dispatch = (callback) => {
+            const failed = (error) => warn(`subc bg nudge delivery failed: ${describeFailure(error)}`);
+            try {
+                void Promise.resolve(callback()).catch(failed);
+            }
+            catch (error) {
+                failed(error);
+            }
+        };
         const onNudge = (observedEvent) => {
             const currentRecord = this.currentSessionForNudge(identity);
             if (!currentRecord) {
@@ -2611,14 +2828,14 @@ export class SubcTransportPool {
             const currentRef = this.nudgeRefFor(currentRecord);
             let delivered = false;
             if (currentRef && this.onBgEventsNudgeRef) {
-                this.onBgEventsNudgeRef(currentRef);
+                dispatch(() => this.onBgEventsNudgeRef?.(currentRef));
                 delivered = true;
             }
             if (this.onBgEventsNudge) {
                 if (!currentRef && this.onBgEventsNudgeRef) {
                     this.logNudgeDelivery("fallback-missing-generation", currentRecord, `nudge dispatch fallback=root-session-handler cause=generation-provenance-unavailable root=${currentRecord.canonicalRoot}`);
                 }
-                this.onBgEventsNudge(currentRecord.identity.project_root, currentRecord.identity.session);
+                dispatch(() => this.onBgEventsNudge?.(currentRecord.identity.project_root, currentRecord.identity.session));
                 delivered = true;
             }
             if (delivered)
@@ -2633,7 +2850,7 @@ export class SubcTransportPool {
         };
         sub = new BgSubscription(identity, () => this.ensureClient(), (client, cause) => this.dropClient(client, cause), (client) => {
             binding.hostScope = undefined;
-            return this.openHostToolRoute(client, identity, record, binding);
+            return this.openHostToolRoute(client, identity, record, binding, "bg_events");
         }, onNudge, this.bgBackoffSleep, () => this.rootCanAttach(record.canonicalRoot), (error) => {
             if (!isAbsentRootRouteError(error))
                 return false;