@cortexkit/aft-bridge 0.58.2 → 0.60.0

package/dist/subc-transport.js

@@ -16,13 +16,13 @@
  * top of it. subc-client is a build-time path dependency bundled into the
  * published plugin dist; it is never a published runtime dependency.
  */
-import { existsSync, statSync } from "node:fs";
-import { AuthError, connectionFileExists, isConsumerReconnectTransient, StaleRouteHandleError, SubcCallError, SubcClient, SubcError, } from "@cortexkit/subc-client";
+import { statSync } from "node:fs";
+import { AuthError, connectionFileExists, isConsumerReconnectTransient, routeCloseReason, SocketTimeoutError, StaleRouteHandleError, SubcCallError, SubcClient, SubcError, } from "@cortexkit/subc-client";
 import { log, warn } from "./active-logger.js";
 import { isRouteOpenReloadWindowError, isRouteRequestReloadRefusal } from "./error-contract.js";
 import { asCanonicalRootPath, asRootGeneration, LifecycleRegistry, } from "./lifecycle-registry.js";
 import { canonicalizeProjectRoot } from "./project-identity.js";
-import { WORKER_SESSION_FIELD } from "./transport.js";
+import { callPresetFor, HOST_TOOL_NAMES_FIELD, PRESET_FIELD, WORKER_SESSION_FIELD, } from "./transport.js";
 /** The subc pool is closing and cannot carry another request. */
 export class SubcTransportShuttingDownError extends SubcCallError {
     constructor() {
@@ -30,6 +30,106 @@ export class SubcTransportShuttingDownError extends SubcCallError {
         this.name = "SubcTransportShuttingDownError";
     }
 }
+/**
+ * The plugin closed one of its own routes (pool shutdown, session close,
+ * project-root close, or a sibling call on the same session discarding the
+ * shared route) while this call's request was already in flight on it.
+ *
+ * subc-client records a request as pending and starts writing its frame in the
+ * same synchronous step, and its `closeRoute` rejects exactly those pending
+ * requests. So a request rejected that way was written, or queued to be
+ * written, and the daemon may have run it: the outcome is unknown. The call
+ * must not be blind-retried, and bash must not re-run it on the host.
+ */
+export class SubcRouteClosedMidCallError extends SubcCallError {
+    reason;
+    constructor(reason, cause) {
+        super("outcome_unknown", `the command may have run; the route closed mid-call: ${reason}`, "route_closed", cause);
+        this.name = "SubcRouteClosedMidCallError";
+        this.reason = reason;
+    }
+}
+/**
+ * A data-plane request was queued and sent, but reading the daemon's response
+ * frame timed out waiting for body bytes after the header was received.
+ *
+ * subc-client raises SocketTimeoutError from readExact when the body does not
+ * arrive within BODY_READ_TIMEOUT_MS after the header. Because the request was
+ * already sent to the daemon, it may have executed: the outcome is unknown.
+ * The call must not be blind-retried, and bash must not re-run it on the host.
+ */
+export class SubcFrameReadTimeoutError extends SubcCallError {
+    constructor(cause) {
+        super("outcome_unknown", "the command may have run; timed out waiting for frame body bytes from the AFT daemon", "frame_read_timeout", cause);
+        this.name = "SubcFrameReadTimeoutError";
+    }
+}
+/**
+ * Matches the frame-body read timeout raised by subc-client (socket.ts:185/190):
+ * "timed out waiting for <N> bytes".
+ *
+ * Excludes connect timeouts ("timed out connecting to ...") and write timeouts
+ * ("timed out writing to subc"): connect timeouts are provably pre-send, while
+ * write timeouts keep their existing transport classification.
+ */
+function isFrameBodyReadTimeoutMessage(message) {
+    return (typeof message === "string" &&
+        (/timed out waiting for \d+ bytes/i.test(message) ||
+            message.includes("timed out waiting for frame body bytes")));
+}
+export function isSubcFrameReadTimeoutError(error) {
+    if (error instanceof SubcFrameReadTimeoutError)
+        return true;
+    if (error instanceof SocketTimeoutError && isFrameBodyReadTimeoutMessage(error.message)) {
+        return true;
+    }
+    if (error instanceof SubcError && isFrameBodyReadTimeoutMessage(error.message)) {
+        return true;
+    }
+    if (error instanceof SubcCallError) {
+        if (error.code === "frame_read_timeout")
+            return true;
+        if (error.cause !== undefined &&
+            error.cause !== error &&
+            isSubcFrameReadTimeoutError(error.cause)) {
+            return true;
+        }
+        if (isFrameBodyReadTimeoutMessage(error.message))
+            return true;
+    }
+    return false;
+}
+export function frameReadTimeoutError(error) {
+    if (!isSubcFrameReadTimeoutError(error))
+        return error;
+    return error instanceof SubcFrameReadTimeoutError ? error : new SubcFrameReadTimeoutError(error);
+}
+/**
+ * subc-client's rejection of a request that was pending when the client itself
+ * closed the route: `closeRoute` tearing that route down, or the client closing
+ * its connection. The client types both with `closeReason: "closed_by_caller"`;
+ * a daemon GOODBYE carries the daemon's reason and a lost connection carries
+ * `"connection_lost"`. A route closed with no request pending produces no error
+ * at all, and a request started on an already-closed route fails with
+ * `StaleRouteHandleError`. A route closed while still opening is reported as a
+ * not-sent `SubcCallError`, which is not a `SubcError` and so never matches.
+ */
+export function isLocalRouteCloseRejection(error) {
+    return error instanceof SubcError && error.closeReason === "closed_by_caller";
+}
+/** The route-close reason that matches a session's teardown, if it was torn down. */
+function teardownCloseReason(teardown) {
+    switch (teardown) {
+        case "shutdown":
+            return "transport shutting down";
+        case "session_closed":
+            return "session closed";
+        case "root_reaped":
+            return "project root closed";
+        default:
+            return null;
+    }
+}
 class ReconnectKeyChangedError extends Error {
     constructor() {
         super("the subc daemon restarted and its connection key changed; the reconnect did not complete within the deadline, retry");
@@ -56,6 +156,12 @@ export function isSubcClientClosedError(error) {
  * the connection has already been torn down locally.
  */
 export function isSocketDeathError(error, depth = 0) {
+    if (isSubcFrameReadTimeoutError(error))
+        return true;
+    // Raw data-plane requests wrap socket death in a SubcError; its typed
+    // connection-loss reason survives even when the underlying errno does not.
+    if (error instanceof SubcError && error.closeReason === "connection_lost")
+        return true;
     if (error instanceof SubcCallError) {
         const cause = error.cause;
         return depth < 4 && cause !== undefined && cause !== error
@@ -115,6 +221,14 @@ export class SubcLivenessProbeTimeoutError extends Error {
 }
 /** The subc module id AFT registers under (matches the daemon manifest). */
 const AFT_MODULE_ID = "aft";
+const HOST_SCOPE_LOOKUP_TIMEOUT_MS = 2_000;
+const HOST_SCOPE_RETRY_FLOOR_MS = 5_000;
+const HOST_SCOPE_RETRY_CAP_MS = 300_000;
+function isHostScopeSyncRefusal(code) {
+    // crates/aft/src/gh_shim_relay/mod.rs lists scope_not_synced and scope_changed as retryable.
+    // A live scope freshly reported by core can also be scope_not_live until the daemon applies it.
+    return code === "scope_not_live" || code === "scope_not_synced" || code === "scope_changed";
+}
 /**
  * A run of consecutive per-call failures that got no answer (timeout / route
  * GOODBYE / refusal) on the SAME client raises the suspicion of a dead half-open
@@ -256,7 +370,7 @@ class BgSubscription {
     identity;
     acquireClient;
     dropClient;
-    consumerIdentity;
+    openRoute;
     onNudge;
     sleep;
     canAttach;
@@ -267,23 +381,25 @@ class BgSubscription {
     isCurrent;
     noteClientAlive;
     noteUnansweredCall;
+    onRouteAttached;
     stopped = false;
     /** The live subscription handle, read by stop() to wake the loop's `await closed`. */
     current = null;
     /** Client carrying the live subscription route, counted when that client is dropped. */
     attached = null;
+    route = null;
     loop;
     lifecycleLogState = new Map();
     nudgeReceiptLogState = null;
-    constructor(identity, acquireClient, dropClient, consumerIdentity, onNudge, sleep, canAttach, onRootAttachFailure, onDormant, dispatchProbeIntervalMs, nudgeRef, isCurrent = () => true, 
+    constructor(identity, acquireClient, dropClient, openRoute, onNudge, sleep, canAttach, onRootAttachFailure, onDormant, dispatchProbeIntervalMs, nudgeRef, isCurrent = () => true, 
     /** Reports a reply seen on the client, which proves its socket still delivers. */
     noteClientAlive = () => undefined, 
     /** Reports a call on the client that got no answer; enough in a row start a liveness probe. */
-    noteUnansweredCall = () => undefined) {
+    noteUnansweredCall = () => undefined, onRouteAttached = () => undefined) {
         this.identity = identity;
         this.acquireClient = acquireClient;
         this.dropClient = dropClient;
-        this.consumerIdentity = consumerIdentity;
+        this.openRoute = openRoute;
         this.onNudge = onNudge;
         this.sleep = sleep;
         this.canAttach = canAttach;
@@ -294,12 +410,16 @@ class BgSubscription {
         this.isCurrent = isCurrent;
         this.noteClientAlive = noteClientAlive;
         this.noteUnansweredCall = noteUnansweredCall;
+        this.onRouteAttached = onRouteAttached;
         this.loop = this.run();
     }
     /** The client whose route currently carries this subscription, if any. */
     get attachedClient() {
         return this.attached;
     }
+    get attachedRoute() {
+        return this.route;
+    }
     async stop() {
         this.stopped = true;
         // Wake a live `await sub.closed`; the loop's `finally` remains the sole
@@ -350,6 +470,11 @@ class BgSubscription {
         const initial = client.droppedIngressFrames;
         if (typeof initial !== "number")
             return () => undefined;
+        const existing = dispatchProbes.get(client);
+        if (existing) {
+            existing.users += 1;
+            return () => releaseDispatchProbe(client);
+        }
         let previous = initial;
         const timer = setInterval(() => {
             const total = client.droppedIngressFrames;
@@ -359,8 +484,10 @@ class BgSubscription {
             previous = total;
             this.info("dispatch-epoch-drop", `client ingress epoch drops scope=client observed_while_channel=${routeId} delta=${delta} total=${total}`);
         }, this.dispatchProbeIntervalMs);
+        dispatchProbeTimers += 1;
         timer.unref?.();
-        return () => clearInterval(timer);
+        dispatchProbes.set(client, { users: 1, timer });
+        return () => releaseDispatchProbe(client);
     }
     async run() {
         let backoffAttempt = 0;
@@ -421,7 +548,7 @@ class BgSubscription {
             try {
                 // A dedicated route keeps bg_events independent of the tool route's
                 // credit window while preserving the client's connection-bound handle.
-                route = await client.routeOpen({ kind: "tool_provider", module_id: AFT_MODULE_ID }, this.identity, { consumerIdentity: this.consumerIdentity });
+                route = await this.openRoute(client);
             }
             catch (err) {
                 if (this.isCurrent() && this.onRootAttachFailure(err)) {
@@ -476,10 +603,12 @@ class BgSubscription {
                     if (!this.isCurrent()) {
                         this.info("nudge-stale-carrier", `nudge carried by stale subscription; checking current session channel=${routeId}`);
                     }
-                    this.onNudge();
+                    this.onNudge(true);
                 });
                 this.current = sub;
                 this.attached = client;
+                this.route = route;
+                this.onRouteAttached();
                 stopDispatchProbe = this.startDispatchProbe(client, routeId);
                 this.info("subscription-open", `subscription open channel=${routeId}`);
                 if (reconnecting) {
@@ -494,7 +623,7 @@ class BgSubscription {
                 // A reconnect may have missed completions, so force a drain after every
                 // successful subscribe to replay anything queued while the stream was down.
                 if (!this.stopped && this.isCurrent())
-                    this.onNudge();
+                    this.onNudge(false);
                 await sub.closed;
                 this.info("stream-end", `stream ended channel=${routeId}`);
                 if (this.stopped) {
@@ -530,6 +659,7 @@ class BgSubscription {
                 stopDispatchProbe();
                 this.current = null;
                 this.attached = null;
+                this.route = null;
                 safeCloseRoute(client, route);
             }
             await this.backoff(backoffAttempt++);
@@ -545,7 +675,8 @@ function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function isRouteProvenAbsentError(err) {
-    return ((err instanceof SubcError && err.code === "unknown_channel") ||
+    return ((err instanceof SubcError &&
+        (err.code === "unknown_channel" || err.code === "stale_route_epoch")) ||
         err instanceof StaleRouteHandleError);
 }
 /**
@@ -610,6 +741,21 @@ function abortedRequestError() {
     error.name = "AbortError";
     return error;
 }
+// The metric is connection-wide, so observing it needs one timer, not one per
+// session. Last unsubscribe releases the timer, including on a dead socket.
+const dispatchProbes = new Map();
+let dispatchProbeTimers = 0;
+function releaseDispatchProbe(client) {
+    const probe = dispatchProbes.get(client);
+    if (!probe || --probe.users > 0)
+        return;
+    clearInterval(probe.timer);
+    dispatchProbeTimers -= 1;
+    dispatchProbes.delete(client);
+}
+export function __dispatchProbeCountForTests() {
+    return dispatchProbeTimers;
+}
 /**
  * A route open that resolved AFTER its session was torn down (closeSession /
  * shutdown / client swap). The caller's request can't proceed, but this is an
@@ -618,6 +764,25 @@ function abortedRequestError() {
  */
 class RouteTornDownError extends Error {
 }
+/**
+ * True when a call stopped at a teardown before its request was handed to the
+ * client (a closed session, or a route that opened after the teardown), so the
+ * request provably never reached AFT.
+ */
+export function isSubcRouteTornDownError(error) {
+    return error instanceof RouteTornDownError;
+}
+/**
+ * Turn subc-client's bare rejection of a request that was in flight on a route
+ * the plugin closed into an outcome-unknown error that names the close reason.
+ * Any other error passes through unchanged.
+ */
+function routeClosedMidCallError(error, entry, record) {
+    if (!isLocalRouteCloseRejection(error))
+        return error;
+    const reason = teardownCloseReason(record.teardownReason) ?? entry.closedBy ?? "route closed by the plugin";
+    return new SubcRouteClosedMidCallError(reason, error);
+}
 /**
  * Re-lift the route reply into the flat {@link ToolCallResult} shape the standalone
  * `BinaryBridge.toolCall` returns. The Rust module wraps the full flat response
@@ -709,6 +874,9 @@ class SubcTransport {
             body.preview = true;
         if (options?.workerSession === true)
             body[WORKER_SESSION_FIELD] = true;
+        if (options?.hostToolNames)
+            body[HOST_TOOL_NAMES_FIELD] = options.hostToolNames;
+        body[PRESET_FIELD] = callPresetFor(options?.workerSession === true);
         const reply = await this.pool.routeRequest(this.identityFor(sessionId), body, timeoutMs, onProgress, this.generation, abortSignal);
         return reliftReply(reply);
     }
@@ -732,10 +900,15 @@ class SubcTransport {
         // The caller's role travels beside the call, like the session (which the
         // route bind carries), not inside the command's arguments: the module
         // reads it from the call body.
-        const { [WORKER_SESSION_FIELD]: workerSession, ...args } = params;
+        // The caller's tool names travel the same way: RouteBind has no field for
+        // them, and one route's host must not decide another route's wording.
+        const { [WORKER_SESSION_FIELD]: workerSession, [HOST_TOOL_NAMES_FIELD]: hostToolNames, ...args } = params;
         const body = { name: command, arguments: args };
         if (workerSession === true)
             body[WORKER_SESSION_FIELD] = true;
+        if (hostToolNames !== undefined)
+            body[HOST_TOOL_NAMES_FIELD] = hostToolNames;
+        body[PRESET_FIELD] = callPresetFor(workerSession === true);
         const editSlotSurvives = this.pool.getEditSlotSurvives();
         if (editSlotSurvives !== undefined)
             body.edit_slot_survives = editSlotSurvives;
@@ -765,6 +938,11 @@ export class SubcTransportPool {
     connectionFile;
     handshakeTimeoutMs;
     consumerIdentity;
+    hostScopes;
+    /** Scope identity is host-session-wide, even when the session uses multiple project roots. */
+    hostScopeCache = new Map();
+    hostScopeRefusals = new Set();
+    hostScopeOutcomes = new Map();
     connectFn;
     onBgEventsNudge;
     onBgEventsNudgeRef;
@@ -791,6 +969,12 @@ export class SubcTransportPool {
     routeReopenRetryMs = null;
     /** Per-session records keyed by the opaque identity key. */
     sessions = new Map();
+    /** Keep global insertion order so a session using several roots selects the same first live route. */
+    sessionIndex = new Map();
+    // Pending host creation events are bounded. Forgetting one only makes that
+    // session unknown (retained), never falsely eligible for eviction.
+    observedStarts = new Set();
+    sessionSweep = null;
     /**
      * The sole root-scoped session enumeration authority. Keys are opaque and are
      * removed by the same detacher that removes the corresponding session record.
@@ -820,6 +1004,7 @@ export class SubcTransportPool {
         this.harness = options.harness;
         this.handshakeTimeoutMs = options.handshakeTimeoutMs;
         this.consumerIdentity = options.consumerIdentity;
+        this.hostScopes = options.hostScopes ?? false;
         this.connectFn = options.connect ?? ((opts) => SubcClient.connect(opts));
         this.onBgEventsNudge = options.onBgEventsNudge;
         this.onBgEventsNudgeRef = options.onBgEventsNudgeRef;
@@ -912,9 +1097,10 @@ export class SubcTransportPool {
         return asCanonicalRootPath(canonicalizeProjectRoot(projectRoot));
     }
     /**
-     * Check a root immediately before opening a route. The reclaim marker is only
-     * an existence hint; a directory that has already returned wins over a stale
-     * sibling marker, so the marker contents are never parsed.
+     * Check a root immediately before opening a route. Only the directory's
+     * existence decides: a reclaim marker beside it (`<root>.reclaimed`) needs
+     * no check, since an absent directory suspends the bind either way and a
+     * directory that has returned wins over a stale marker.
      */
     rootCanAttach(root) {
         let directoryExists = false;
@@ -928,13 +1114,6 @@ export class SubcTransportPool {
             this.dormantRoots.delete(root);
             return true;
         }
-        // Read the marker only as a latency hint. Directory absence is sufficient
-        // to suspend the bind, and the marker's JSON is intentionally irrelevant.
-        const reclaimedMarkerPresent = existsSync(`${root}.reclaimed`);
-        if (reclaimedMarkerPresent) {
-            this.markRootDormant(root);
-            return false;
-        }
         this.markRootDormant(root);
         return false;
     }
@@ -1084,7 +1263,9 @@ export class SubcTransportPool {
      * always has a registered root and captured generation.
      */
     getBridge(projectRoot) {
-        const root = this.canonicalRoot(projectRoot);
+        return this.getBridgeForCanonicalRoot(this.canonicalRoot(projectRoot));
+    }
+    getBridgeForCanonicalRoot(root) {
         if (this.shuttingDown && this.lifecycleEnabled()) {
             throw new SubcTransportShuttingDownError();
         }
@@ -1166,6 +1347,7 @@ export class SubcTransportPool {
             if (this.lifecycleEnabled() && record.generation !== generation) {
                 throw this.generationExpiredError(root, generation ?? asRootGeneration(1));
             }
+            record.lastUsedAt = Date.now();
             return record;
         }
         record = {
@@ -1174,20 +1356,199 @@ export class SubcTransportPool {
             canonicalRoot: root,
             generation,
             routeEntry: null,
+            retiredRoutes: new Set(),
             bgSub: null,
             closed: false,
             teardownReason: null,
             inflight: 0,
+            lastUsedAt: Date.now(),
+            observedFromStart: this.observedStarts.delete(key),
+            backgroundTasks: new Map(),
+            backgroundWatches: new Map(),
+            unknownBackgroundWork: false,
+            pendingBgNudge: false,
+            pendingDetach: false,
         };
         this.sessions.set(key, record);
+        let records = this.sessionIndex.get(identity.session);
+        if (!records) {
+            records = new Set();
+            this.sessionIndex.set(identity.session, records);
+        }
+        records.add(record);
         let keys = this.rootIndex.get(root);
         if (!keys) {
             keys = new Set();
             this.rootIndex.set(root, keys);
         }
         keys.add(key);
+        if (!this.sessionSweep) {
+            this.sessionSweep = setInterval(() => {
+                void this.reapIdleSessions();
+            }, 60_000);
+            this.sessionSweep.unref?.();
+        }
         return record;
     }
+    /** Release only idle carriers, not the daemon's durable session or completion queue.
+     * The next request opens a new route and subscribes again; subscription startup
+     * 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)
+                this.nudgeDeliveryLogState.delete(key);
+        }
+        const detached = [];
+        for (const [key, record] of this.sessions) {
+            if (
+            // The wire has no session-wide background census. A resumed/rebound
+            // session may have tasks or watches this pool never saw, so only a
+            // host-observed creation can establish a complete lifetime history.
+            !record.observedFromStart ||
+                record.backgroundTasks.size > 0 ||
+                record.backgroundWatches.size > 0 ||
+                record.unknownBackgroundWork ||
+                record.pendingBgNudge ||
+                record.pendingDetach ||
+                record.inflight > 0 ||
+                record.retiredRoutes.size > 0 ||
+                record.routeEntry?.opening ||
+                now - record.lastUsedAt < 15 * 60_000)
+                continue;
+            const owner = this.detachSession(key, "session_closed");
+            if (owner)
+                detached.push(owner);
+        }
+        if (this.sessions.size === 0 && this.sessionSweep) {
+            clearInterval(this.sessionSweep);
+            this.sessionSweep = null;
+        }
+        const cleanup = Promise.allSettled(detached.map((owner) => this.cleanupDetached(owner)));
+        this.pendingRootCleanups.add(cleanup);
+        try {
+            await cleanup;
+        }
+        finally {
+            this.pendingRootCleanups.delete(cleanup);
+        }
+    }
+    observeSessionStart(projectRoot, session) {
+        if (this.shuttingDown || !session)
+            return;
+        const key = identityKey({
+            project_root: canonicalizeProjectRoot(projectRoot),
+            harness: this.harness,
+            session,
+        });
+        const record = this.sessions.get(key);
+        if (record) {
+            record.observedFromStart = true;
+            return;
+        }
+        if (this.observedStarts.size >= 256)
+            this.observedStarts.delete(this.observedStarts.values().next().value);
+        this.observedStarts.add(key);
+    }
+    __pendingSessionStartsForTests() {
+        return this.observedStarts.size;
+    }
+    observeBackgroundReply(record, body, reply) {
+        const name = String(body.name);
+        const args = isRecord(body.arguments) ? body.arguments : {};
+        const data = isRecord(reply) && isRecord(reply.structuredContent) ? reply.structuredContent : null;
+        const affectsBackground = name === "bash" ||
+            name === "powershell" ||
+            [
+                "bash_status",
+                "bash_kill",
+                "bash_write",
+                "bash_promote",
+                "bash_watch",
+                "bash_notify",
+                "bash_unnotify",
+                "bash_wait_detach",
+                "bash_drain_completions",
+                "bash_ack_completions",
+            ].includes(name);
+        if (!data || data.success !== true) {
+            if (affectsBackground) {
+                if (typeof args.task_id === "string") {
+                    if (!record.backgroundTasks.has(args.task_id))
+                        record.backgroundTasks.set(args.task_id, "unknown");
+                }
+                else
+                    record.unknownBackgroundWork = true;
+            }
+            return;
+        }
+        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 running = ["starting", "running", "killing"].includes(String(data.status));
+            record.backgroundTasks.set(data.task_id, terminal ? "terminal" : running ? "running" : "unknown");
+            if (name === "bash" || name === "powershell")
+                record.pendingDetach = false;
+        }
+        if (Array.isArray(data.bg_completions)) {
+            for (const completion of data.bg_completions) {
+                if (isRecord(completion) && typeof completion.task_id === "string")
+                    record.backgroundTasks.set(completion.task_id, "terminal");
+                else
+                    record.unknownBackgroundWork = true;
+            }
+        }
+        if (Array.isArray(data.pending_matches)) {
+            for (const match of data.pending_matches) {
+                if (isRecord(match) &&
+                    typeof match.watch_id === "string" &&
+                    typeof match.task_id === "string")
+                    record.backgroundWatches.set(match.watch_id, match.task_id);
+                else
+                    record.unknownBackgroundWork = true;
+            }
+        }
+        if (name === "bash_drain_completions" &&
+            Array.isArray(data.bg_completions) &&
+            Array.isArray(data.pending_matches))
+            record.pendingBgNudge = false;
+        if (name === "bash_notify") {
+            if (typeof data.watch_id === "string" && typeof args.task_id === "string")
+                record.backgroundWatches.set(data.watch_id, args.task_id);
+            else
+                record.unknownBackgroundWork = true;
+        }
+        if (name === "bash_unnotify" && data.unregistered === true && typeof args.watch_id === "string")
+            record.backgroundWatches.delete(args.watch_id);
+        if (name === "bash_ack_completions" && Array.isArray(data.acked_task_ids)) {
+            // ACK also acknowledges mid-run pattern matches. It does not prove a
+            // running/unknown task is terminal, so those must keep their carrier.
+            for (const task of data.acked_task_ids)
+                if (typeof task === "string" && record.backgroundTasks.get(task) === "terminal") {
+                    record.backgroundTasks.delete(task);
+                    // The daemon's terminal ACK also removes every watch on that task.
+                    for (const [watch, owner] of record.backgroundWatches) {
+                        if (owner === task)
+                            record.backgroundWatches.delete(watch);
+                    }
+                }
+        }
+        if (name === "bash_wait_detach") {
+            if (typeof data.detached === "boolean")
+                record.pendingDetach = data.detached;
+            else
+                record.unknownBackgroundWork = true;
+        }
+    }
+    __retainedSessionCountsForTests() {
+        return {
+            sessions: this.sessions.size,
+            roots: this.rootIndex.size,
+            routes: [...this.sessions.values()].filter((r) => r.routeEntry !== null).length,
+            subscriptions: [...this.sessions.values()].filter((r) => r.bgSub !== null).length,
+            sweepTimers: this.sessionSweep ? 1 : 0,
+        };
+    }
     isCurrentSession(key, record) {
         return this.sessions.get(key) === record && !record.closed;
     }
@@ -1221,6 +1582,10 @@ export class SubcTransportPool {
         log(`subc bg_events: ${message}${suffix}`, { sessionId: record.identity.session });
     }
     removeIndexMembership(record) {
+        const records = this.sessionIndex.get(record.identity.session);
+        records?.delete(record);
+        if (records?.size === 0)
+            this.sessionIndex.delete(record.identity.session);
         const keys = this.rootIndex.get(record.canonicalRoot);
         if (!keys)
             return;
@@ -1232,11 +1597,18 @@ export class SubcTransportPool {
         if (this.sessions.get(record.identityKey) === record &&
             !record.closed &&
             record.inflight === 0 &&
+            record.retiredRoutes.size === 0 &&
+            record.backgroundTasks.size === 0 &&
+            record.backgroundWatches.size === 0 &&
+            !record.unknownBackgroundWork &&
+            !record.pendingBgNudge &&
+            !record.pendingDetach &&
             record.routeEntry === null &&
             record.bgSub === null) {
             this.sessions.delete(record.identityKey);
             this.removeIndexMembership(record);
         }
+        this.stopUnusedHostScopeRetry(record.identity.session);
     }
     /**
      * Atomically detaches one opaque identity. Nothing in this method awaits: it
@@ -1250,26 +1622,36 @@ 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);
+        }
         const bgSub = record.bgSub;
         record.bgSub = null;
         const routeEntry = record.routeEntry;
         record.routeEntry = null;
         if (routeEntry)
             routeEntry.closed = true;
+        this.stopUnusedHostScopeRetry(record.identity.session);
         return { record, bgSub, routeEntry };
     }
     async cleanupDetached(detached) {
         const cleanup = [];
         if (detached.bgSub)
             cleanup.push(detached.bgSub.stop());
-        const routeEntry = detached.routeEntry;
-        const route = routeEntry?.handle;
-        if (routeEntry && route !== null && route !== undefined) {
-            try {
-                cleanup.push(Promise.resolve(routeEntry.client.closeRouteChannel(route)).catch(() => undefined));
-            }
-            catch {
-                // A client may throw synchronously when its socket is already closed.
+        const entries = new Set(detached.record.retiredRoutes);
+        detached.record.retiredRoutes.clear();
+        if (detached.routeEntry)
+            entries.add(detached.routeEntry);
+        for (const entry of entries) {
+            entry.closed = true;
+            if (entry.handle != null) {
+                try {
+                    cleanup.push(Promise.resolve(entry.client.closeRouteChannel(entry.handle)).catch(() => undefined));
+                }
+                catch {
+                    // A client may throw synchronously when its socket is already closed.
+                }
             }
         }
         await Promise.allSettled(cleanup);
@@ -1299,6 +1681,28 @@ export class SubcTransportPool {
         }
         return this.rootReapedError(record);
     }
+    closeRetiredRoute(record, entry) {
+        if (entry.inflight > 0 || !record.retiredRoutes.delete(entry))
+            return;
+        if (entry.handle != null)
+            safeCloseRoute(entry.client, entry.handle);
+        this.deleteSessionIfEmpty(record.identityKey, record);
+    }
+    releaseRouteRequest(record, entry) {
+        entry.inflight -= 1;
+        this.closeRetiredRoute(record, entry);
+    }
+    retireHostToolRoute(record) {
+        const entry = record.routeEntry;
+        if (!entry)
+            return;
+        entry.closed = true;
+        entry.closedBy ??= "route replaced";
+        record.routeEntry = null;
+        record.retiredRoutes.add(entry);
+        this.closeRetiredRoute(record, entry);
+        this.stopUnusedHostScopeRetry(record.identity.session);
+    }
     /** Open or reuse a route while guarding every lifecycle boundary. */
     async routeRequest(identity, body, timeoutMs, onProgress, expectedGeneration, abortSignal) {
         const callStartedAt = performance.now();
@@ -1470,16 +1874,16 @@ export class SubcTransportPool {
             const clearRouteEntry = (entry) => {
                 if (record.routeEntry !== entry)
                     return;
-                entry.closed = true;
-                record.routeEntry = null;
-                if (entry.handle != null)
-                    safeCloseRoute(entry.client, entry.handle);
+                this.retireHostToolRoute(record);
             };
             const handleRequestFailure = (error, entry) => {
                 const aborted = error instanceof Error && error.name === "AbortError";
                 const ownsClient = this.isCurrentSession(key, record) &&
                     this.client === client &&
                     !this.isReapInduced(record);
+                if (ownsClient && error instanceof SubcError && error.closeReason?.startsWith("scope_")) {
+                    this.invalidateHostScope(identity.session);
+                }
                 if (!aborted && ownsClient && isSocketDeathError(error)) {
                     // Dropped before the route is cleared so the drop log counts it.
                     this.dropClient(client, {
@@ -1489,20 +1893,31 @@ export class SubcTransportPool {
                         route: routeLabel(entry.handle),
                     });
                 }
-                clearRouteEntry(entry);
+                // A call's timeout or refusal says nothing about the route's health.
+                // Retire only a cancelled carrier or one known to be gone; a slow live
+                // route remains reusable, and no replacement may cut its other calls.
+                if (aborted ||
+                    isRouteProvenAbsentError(error) ||
+                    (error instanceof SubcError && error.closeReason !== undefined) ||
+                    isSubcFrameReadTimeoutError(error)) {
+                    clearRouteEntry(entry);
+                }
                 if (aborted || !ownsClient || this.client !== client)
                     return;
                 if (isRouteProvenAbsentError(error))
                     return;
-                // Anything else is this call's own outcome: a timeout, a GOODBYE, a
-                // refusal, or a managed not_sent/outcome_unknown verdict. It fails this
-                // call and route only; a run of them just checks the connection.
-                this.noteUnansweredCall(client, {
-                    error,
-                    trigger: "request",
-                    session: identity.session,
-                    route: routeLabel(entry.handle),
-                });
+                if (isDaemonAnswerError(error)) {
+                    this.transportFailures = 0;
+                    this.noteClientAlive(client);
+                }
+                else if (isUnansweredCallError(error)) {
+                    this.noteUnansweredCall(client, {
+                        error,
+                        trigger: "request",
+                        session: identity.session,
+                        route: routeLabel(entry.handle),
+                    });
+                }
             };
             const requestOnRoute = async (route, entry, requestTimeoutMs) => {
                 this.assertRecordLive(record);
@@ -1520,10 +1935,22 @@ export class SubcTransportPool {
                 };
                 abortSignal?.addEventListener("abort", onAbort, { once: true });
                 try {
-                    const request = client.request(route, body, {
-                        timeoutMs: Math.ceil(requestTimeoutMs),
-                        onProgress,
-                    });
+                    // Track the actual client promise, not the abort race. A cancelled
+                    // caller has no terminal from the daemon yet, so closing its carrier
+                    // here would still cut sibling calls and invalidate request credits.
+                    entry.inflight += 1;
+                    let request;
+                    try {
+                        request = client.request(route, body, {
+                            timeoutMs: Math.ceil(requestTimeoutMs),
+                            onProgress,
+                        });
+                    }
+                    catch (error) {
+                        this.releaseRouteRequest(record, entry);
+                        throw error;
+                    }
+                    request = request.finally(() => this.releaseRouteRequest(record, entry));
                     const reply = abortSignal ? await Promise.race([request, aborted]) : await request;
                     // A legacy closeSession may intentionally let an already-delivered reply
                     // settle. It must not mutate shared state or recreate a subscription.
@@ -1536,6 +1963,7 @@ export class SubcTransportPool {
                     if (this.client === client)
                         this.transportFailures = 0;
                     this.noteClientAlive(client);
+                    this.observeBackgroundReply(record, body, reply);
                     this.ensureBgSubscription(identity, record);
                     return reply;
                 }
@@ -1547,6 +1975,10 @@ export class SubcTransportPool {
             let reopened = false;
             let retriedAbsentRoute = false;
             while (true) {
+                // Another call can retire a just-acquired carrier before this caller
+                // dispatches. Only already-pending requests belong on retired routes.
+                if (routeAndEntry.entry.closed)
+                    routeAndEntry = await openRouteAfterReloadWindow();
                 // Checked outside the try below so the retry branches never mistake
                 // this call's own expiry for a daemon refusal worth retrying.
                 const requestTimeoutMs = remainingMs();
@@ -1558,10 +1990,16 @@ export class SubcTransportPool {
                         this.resetRouteReopenBackoff();
                     return reply;
                 }
-                catch (error) {
+                catch (requestError) {
+                    const error = frameReadTimeoutError(routeClosedMidCallError(requestError, routeAndEntry.entry, record));
                     if (this.isReapInduced(record))
                         throw this.annotateReapError(error, record);
                     const ownsRoute = this.isCurrentSession(key, record) && this.client === client;
+                    if (ownsRoute &&
+                        ((error instanceof SubcError && error.code === "stale_route_epoch") ||
+                            error instanceof StaleRouteHandleError)) {
+                        this.invalidateHostScope(identity.session);
+                    }
                     // A route that was bound before a module reload started gets its
                     // requests refused by the daemon for as long as the drain lasts. The
                     // refusal happens before the request is forwarded, so it is handled
@@ -1607,10 +2045,14 @@ export class SubcTransportPool {
         catch (error) {
             if (this.isReapInduced(record))
                 throw this.annotateReapError(error, record);
+            this.observeBackgroundReply(record, body, null);
+            if (record.backgroundTasks.size > 0 || record.unknownBackgroundWork)
+                this.ensureBgSubscription(identity, record);
             throw error;
         }
         finally {
             record.inflight -= 1;
+            record.lastUsedAt = Date.now();
             this.deleteSessionIfEmpty(key, record);
         }
     }
@@ -1655,9 +2097,14 @@ export class SubcTransportPool {
             return this.client;
         if (this.connecting)
             return this.connecting;
+        let owner;
         this.connecting = this.connectFn({
             connectionFile: this.connectionFile,
             handshakeTimeoutMs: this.handshakeTimeoutMs,
+            onControlPush: (push) => {
+                if (owner && this.client === owner)
+                    this.onScopeRouteClose(push);
+            },
         })
             .then((client) => {
             this.connecting = null;
@@ -1671,6 +2118,7 @@ export class SubcTransportPool {
                 throw new SubcTransportShuttingDownError();
             }
             this.client = client;
+            owner = client;
             this.hadWorkingClient = true;
             this.transportFailures = 0;
             return client;
@@ -1700,12 +2148,11 @@ export class SubcTransportPool {
             opening: null,
             handle: null,
             closed: false,
+            inflight: 0,
+            closedBy: null,
         };
         this.assertRootCanAttach(record.canonicalRoot);
-        const opening = client
-            .routeOpen({ kind: "tool_provider", module_id: AFT_MODULE_ID }, identity, {
-            consumerIdentity: this.consumerIdentity,
-        })
+        const opening = this.openHostToolRoute(client, identity, record, entry)
             .then((route) => {
             if (!this.isCurrentSession(record.identityKey, record) ||
                 record.routeEntry !== entry ||
@@ -1721,6 +2168,15 @@ export class SubcTransportPool {
             entry.handle = route;
             entry.opening = null;
             this.noteClientAlive(client);
+            const state = this.hostScopeCache.get(identity.session);
+            if (state)
+                this.scheduleHostScopeRetry(identity.session, state);
+            if (state?.answer?.result === "scope" &&
+                !state.scopeBindPending &&
+                !entry.hostScope &&
+                !this.hostScopeRefusals.has(identity.session)) {
+                this.promoteHostScope(identity.session);
+            }
             return route;
         })
             .catch((error) => {
@@ -1729,6 +2185,7 @@ export class SubcTransportPool {
                 entry.closed = true;
                 record.routeEntry = null;
             }
+            this.stopUnusedHostScopeRetry(identity.session);
             if (!this.isCurrentSession(record.identityKey, record) &&
                 !(error instanceof RouteTornDownError)) {
                 throw new RouteTornDownError("subc route opened after session closed");
@@ -1742,17 +2199,404 @@ export class SubcTransportPool {
         record.routeEntry = entry;
         return { route: await opening, entry };
     }
+    hostScope(client, identity) {
+        if (this.hostScopeRefusals.has(identity.session))
+            return Promise.resolve(undefined);
+        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);
+        }
+        if (state.pending)
+            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);
+        const current = state;
+        clearTimeout(current.retryTimer);
+        current.retryTimer = undefined;
+        const abort = new AbortController();
+        current.lookupAbort = abort;
+        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;
+            current.pending = undefined;
+            current.lookupAbort = undefined;
+            if (abort.signal.aborted)
+                return undefined;
+            this.logHostScopeOutcome(identity.session, outcome);
+            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);
+            }
+            else {
+                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;
+        });
+        current.pending = lookup;
+        return lookup;
+    }
+    unscopedHostRecord(session) {
+        for (const record of this.sessionIndex.get(session) ?? []) {
+            const entry = record.routeEntry;
+            if (record.identity.session === session &&
+                !record.closed &&
+                ((entry &&
+                    !entry.closed &&
+                    !entry.hostScope &&
+                    entry.client === this.client &&
+                    (entry.handle || entry.opening)) ||
+                    (record.bgSub?.attachedClient === this.client && record.bgSub?.attachedRoute)))
+                return record;
+        }
+        return undefined;
+    }
+    cancelHostScopeRetry(state) {
+        clearTimeout(state.retryTimer);
+        state.retryTimer = undefined;
+        state.lookupAbort?.abort();
+    }
+    stopUnusedHostScopeRetry(session) {
+        const state = this.hostScopeCache.get(session);
+        if (state && !this.unscopedHostRecord(session)) {
+            if (state.retryTimer || (state.scopeBindPending && state.bindPending))
+                log(`subc head scope: session=${session} retry stopped reason=route_closed`);
+            this.cancelHostScopeRetry(state);
+            state.scopeBindPending = false;
+        }
+    }
+    scheduleHostScopeRetry(session, state) {
+        if (this.shuttingDown ||
+            this.hostScopeCache.get(session) !== state ||
+            (state.answer && !state.scopeBindPending) ||
+            state.pending ||
+            state.bindPending ||
+            state.retryTimer ||
+            this.hostScopeRefusals.has(session) ||
+            !this.unscopedHostRecord(session))
+            return;
+        // A head can keep its tool route for its whole life, so recovery cannot rely on another bind.
+        state.retryTimer = setTimeout(() => {
+            state.retryTimer = undefined;
+            const record = this.unscopedHostRecord(session);
+            const client = record?.routeEntry?.client ?? record?.bgSub?.attachedClient;
+            if (this.shuttingDown || this.hostScopeCache.get(session) !== state || !record || !client)
+                return;
+            let retry;
+            if (state.scopeBindPending && state.answer?.result === "scope") {
+                state.bindPending = this.retryHostScopeBind(client, record.identity, state, state.answer.scope).finally(() => {
+                    state.bindPending = undefined;
+                    this.scheduleHostScopeRetry(session, state);
+                });
+                retry = state.bindPending;
+            }
+            else {
+                retry = this.hostScope(client, record.identity);
+            }
+            void retry.catch((error) => {
+                warn(`subc head scope: background retry failed code=${error instanceof Error ? error.name : "Error"}`);
+            });
+        }, Math.max(0, state.retryAt - Date.now()));
+        state.retryTimer.unref();
+    }
+    deferHostScopeBind(session, state, code) {
+        state.scopeBindPending = true;
+        if (Date.now() >= state.retryAt) {
+            state.retryAt = Date.now() + state.retryMs;
+            state.retryMs = Math.min(state.retryMs * 2, HOST_SCOPE_RETRY_CAP_MS);
+        }
+        warn(`subc head scope: session=${session} scoped bind refused code=${code}; binding unscoped; retry in=${Math.max(0, state.retryAt - Date.now())}ms`);
+        this.scheduleHostScopeRetry(session, state);
+    }
+    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`);
+        }
+        if (state) {
+            state.scopeBindPending = false;
+            this.cancelHostScopeRetry(state);
+        }
+        // Remember the downgrade without misreporting it as core's no_scope answer.
+    }
+    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 });
+            safeCloseRoute(client, route);
+            if (this.hostScopeCache.get(identity.session) !== state ||
+                !state.scopeBindPending ||
+                this.shuttingDown ||
+                client !== this.client ||
+                !this.unscopedHostRecord(identity.session))
+                return;
+            state.scopeBindPending = 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}`);
+            this.promoteHostScope(identity.session);
+        }
+        catch (error) {
+            if (this.hostScopeCache.get(identity.session) !== state ||
+                !state.scopeBindPending ||
+                this.shuttingDown ||
+                !this.unscopedHostRecord(identity.session))
+                return;
+            if (error instanceof SubcError &&
+                error.code &&
+                !isSocketDeathError(error) &&
+                !isRouteOpenReloadWindowError(error) &&
+                !isHostScopeSyncRefusal(error.code)) {
+                this.refuseHostScopeBind(identity.session, state, error.code);
+            }
+            else {
+                this.deferHostScopeBind(identity.session, state, error instanceof SubcError ? (error.code ?? error.name) : "Error");
+            }
+        }
+    }
+    promoteHostScope(session) {
+        for (const record of this.sessions.values()) {
+            const entry = record.routeEntry;
+            if (record.identity.session !== session)
+                continue;
+            // Retirement stops new dispatches; the existing request counter defers closure of held waits.
+            if (entry?.handle && !entry.hostScope)
+                this.retireHostToolRoute(record);
+            const sub = record.bgSub;
+            if (!sub?.attachedRoute)
+                continue;
+            // The old subscription must finish closing before its normal attach path opens a scoped one.
+            void sub.stop().then(() => {
+                if (record.bgSub !== sub)
+                    return;
+                record.bgSub = null;
+                this.ensureBgSubscription(record.identity, record);
+            });
+        }
+    }
+    logHostScopeOutcome(session, outcome) {
+        let key;
+        let detail;
+        switch (outcome.result) {
+            case "scope":
+                key = JSON.stringify([outcome.result, outcome.scope.ref, outcome.scope.scopeEpoch]);
+                detail = `scope ref=${outcome.scope.ref.slice(0, 8)} epoch=${outcome.scope.scopeEpoch}`;
+                break;
+            case "error":
+                key = JSON.stringify([outcome.result, outcome.code]);
+                detail = `error code=${outcome.code} after=${outcome.afterMs}`;
+                break;
+            case "timeout":
+                key = outcome.result;
+                detail = `timeout after=${outcome.afterMs}`;
+                break;
+            default:
+                key = outcome.result;
+                detail = outcome.result;
+        }
+        // Elapsed time varies on every retry; only a changed answer or error code merits another line.
+        if (this.hostScopeOutcomes.get(session) === key)
+            return;
+        this.hostScopeOutcomes.set(session, key);
+        log(`subc head scope: session=${session} result=${detail}`);
+    }
+    async readHostScope(client, identity, signal) {
+        const startedAt = Date.now();
+        const timeout = () => ({ result: "timeout", afterMs: Date.now() - startedAt });
+        let expired = false;
+        let timer;
+        const abort = new AbortController();
+        let cancel;
+        const cancelled = new Promise((resolve) => {
+            cancel = () => {
+                expired = true;
+                abort.abort();
+                resolve({ result: "error", code: "AbortError", afterMs: Date.now() - startedAt });
+            };
+            signal.addEventListener("abort", cancel, { once: true });
+        });
+        const read = async () => {
+            let route;
+            try {
+                route = await client.routeOpen({ kind: "management_surface", module_id: "prefrontal-core" }, identity, { consumerIdentity: this.consumerIdentity });
+                if (expired)
+                    return timeout();
+                const envelope = await client.request(route, {
+                    // Core decodes every management request as {method, params}.
+                    method: "session.scope_identity",
+                    params: { harness: identity.harness, session: identity.session },
+                }, { timeoutMs: HOST_SCOPE_LOOKUP_TIMEOUT_MS, signal: abort.signal });
+                // Core answers a management request as {result: <answer>}.
+                const reply = isRecord(envelope) ? envelope.result : undefined;
+                if (isRecord(reply) && reply.answer === "no_scope")
+                    return { result: "no_scope" };
+                if (!isRecord(reply) ||
+                    !isRecord(reply.owner) ||
+                    reply.owner.kind !== "reserved" ||
+                    reply.owner.module_id !== "prefrontal-core" ||
+                    typeof reply.ref !== "string" ||
+                    reply.ref.length === 0 ||
+                    !Number.isSafeInteger(reply.scope_epoch) ||
+                    reply.scope_epoch < 0)
+                    return { result: "malformed" };
+                return {
+                    result: "scope",
+                    scope: {
+                        owner: { kind: "reserved", module_id: "prefrontal-core" },
+                        ref: reply.ref,
+                        scopeEpoch: reply.scope_epoch,
+                    },
+                };
+            }
+            catch (error) {
+                // A missing or unavailable scope service must not disable the host's tools.
+                if (expired)
+                    return timeout();
+                return {
+                    result: "error",
+                    code: error instanceof SubcError && error.code
+                        ? error.code
+                        : error instanceof Error
+                            ? error.name
+                            : "Error",
+                    afterMs: Date.now() - startedAt,
+                };
+            }
+            finally {
+                if (route)
+                    safeCloseRoute(client, route);
+            }
+        };
+        try {
+            // Keep the two-second bind budget during core startup; fallback routes retry in the background.
+            return await Promise.race([
+                read(),
+                cancelled,
+                new Promise((resolve) => {
+                    timer = setTimeout(() => {
+                        expired = true;
+                        abort.abort();
+                        resolve(timeout());
+                    }, HOST_SCOPE_LOOKUP_TIMEOUT_MS);
+                }),
+            ]);
+        }
+        finally {
+            clearTimeout(timer);
+            signal.removeEventListener("abort", cancel);
+        }
+    }
+    openHostToolRoute(client, identity, record, entry) {
+        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);
+    }
+    async openScopedHostToolRoute(client, identity, record, entry) {
+        const scope = await this.hostScope(client, identity);
+        this.assertRecordLive(record);
+        if (scope) {
+            try {
+                const route = await client.routeOpen({ kind: "tool_provider", module_id: AFT_MODULE_ID }, identity, { consumerIdentity: this.consumerIdentity, scope });
+                if (entry)
+                    entry.hostScope = scope;
+                return route;
+            }
+            catch (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.
+                if (isRouteOpenReloadWindowError(error))
+                    throw error;
+                this.assertRecordLive(record);
+                const state = this.hostScopeCache.get(identity.session);
+                if (state && isHostScopeSyncRefusal(error.code)) {
+                    this.deferHostScopeBind(identity.session, state, error.code);
+                }
+                else {
+                    this.refuseHostScopeBind(identity.session, state, error.code);
+                }
+            }
+        }
+        this.assertRecordLive(record);
+        const route = await client.routeOpen({ kind: "tool_provider", module_id: AFT_MODULE_ID }, identity, {
+            consumerIdentity: this.consumerIdentity,
+        });
+        // 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 route;
+    }
+    invalidateHostScope(session) {
+        const state = this.hostScopeCache.get(session);
+        if (state) {
+            if (state.scopeBindPending)
+                log(`subc head scope: session=${session} retry stopped reason=scope_route_closed`);
+            this.cancelHostScopeRetry(state);
+        }
+        this.hostScopeCache.delete(session);
+        this.hostScopeRefusals.delete(session);
+        for (const record of this.sessions.values()) {
+            if (record.identity.session !== session || !record.routeEntry)
+                continue;
+            this.retireHostToolRoute(record);
+        }
+    }
+    onScopeRouteClose(push) {
+        if (push.op !== "route.closed")
+            return;
+        const reason = routeCloseReason(push);
+        if (!reason?.startsWith("scope_")) {
+            for (const record of this.sessions.values()) {
+                const route = record.routeEntry?.handle;
+                if (!route)
+                    continue;
+                if ((Array.isArray(push.body.channels) && push.body.channels.includes(route.channel)) ||
+                    (!Array.isArray(push.body.channels) && push.body.module_id === AFT_MODULE_ID))
+                    this.retireHostToolRoute(record);
+            }
+            return;
+        }
+        const sessions = new Set();
+        for (const record of this.sessions.values()) {
+            const routes = [record.routeEntry?.handle, record.bgSub?.attachedRoute].filter((route) => route != null);
+            if ((Array.isArray(push.body.channels) &&
+                routes.some((route) => push.body.channels.includes(route.channel))) ||
+                (!Array.isArray(push.body.channels) && push.body.module_id === AFT_MODULE_ID))
+                sessions.add(record.identity.session);
+        }
+        for (const session of sessions)
+            this.invalidateHostScope(session);
+    }
     ensureBgSubscription(identity, record) {
         if (this.shuttingDown || (!this.onBgEventsNudge && !this.onBgEventsNudgeRef))
             return;
         if (!this.isCurrentSession(record.identityKey, record))
             return;
-        if (!this.rootCanAttach(record.canonicalRoot))
-            return;
         if (record.bgSub)
             return;
+        if (!this.rootCanAttach(record.canonicalRoot))
+            return;
         const nudgeRef = this.nudgeRefFor(record);
-        const onNudge = () => {
+        const onNudge = (observedEvent) => {
             const currentRecord = this.currentSessionForNudge(identity);
             if (!currentRecord) {
                 this.logNudgeDelivery("drop-no-current-session", record, `nudge dropped cause=no-current-session root=${record.canonicalRoot}`);
@@ -1761,6 +2605,9 @@ export class SubcTransportPool {
             if (currentRecord !== record) {
                 this.logNudgeDelivery("forward-superseded-carrier", currentRecord, `nudge forwarding cause=superseded-carrying-record root=${currentRecord.canonicalRoot}`);
             }
+            currentRecord.lastUsedAt = Date.now();
+            if (observedEvent)
+                currentRecord.pendingBgNudge = true;
             const currentRef = this.nudgeRefFor(currentRecord);
             let delivered = false;
             if (currentRef && this.onBgEventsNudgeRef) {
@@ -1778,18 +2625,32 @@ export class SubcTransportPool {
                 return;
             this.logNudgeDelivery("drop-no-compatible-handler", currentRecord, `nudge dropped cause=generation-provenance-unavailable-and-root-session-handler-unwired root=${currentRecord.canonicalRoot}`);
         };
+        const binding = {};
         let sub = null;
         const clearDormantSubscription = () => {
             if (sub && record.bgSub === sub)
                 record.bgSub = null;
         };
-        sub = new BgSubscription(identity, () => this.ensureClient(), (client, cause) => this.dropClient(client, cause), this.consumerIdentity, onNudge, this.bgBackoffSleep, () => this.rootCanAttach(record.canonicalRoot), (error) => {
+        sub = new BgSubscription(identity, () => this.ensureClient(), (client, cause) => this.dropClient(client, cause), (client) => {
+            binding.hostScope = undefined;
+            return this.openHostToolRoute(client, identity, record, binding);
+        }, onNudge, this.bgBackoffSleep, () => this.rootCanAttach(record.canonicalRoot), (error) => {
             if (!isAbsentRootRouteError(error))
                 return false;
             this.markRootDormant(record.canonicalRoot, error);
             return true;
         }, clearDormantSubscription, this.bgDispatchProbeIntervalMs, nudgeRef, () => this.isCurrentSession(record.identityKey, record) &&
-            this.isCurrentLiveGeneration(record.canonicalRoot, record.generation), (client) => this.noteClientAlive(client), (client, cause) => this.noteUnansweredCall(client, cause));
+            this.isCurrentLiveGeneration(record.canonicalRoot, record.generation), (client) => this.noteClientAlive(client), (client, cause) => this.noteUnansweredCall(client, cause), () => {
+            const state = this.hostScopeCache.get(identity.session);
+            if (state)
+                this.scheduleHostScopeRetry(identity.session, state);
+            if (state?.answer?.result === "scope" &&
+                !state.scopeBindPending &&
+                !binding.hostScope &&
+                !this.hostScopeRefusals.has(identity.session)) {
+                this.promoteHostScope(identity.session);
+            }
+        });
         record.bgSub = sub;
         if (!this.rootCanAttach(record.canonicalRoot)) {
             record.bgSub = null;
@@ -1825,6 +2686,12 @@ export class SubcTransportPool {
             ` message=${JSON.stringify(message)}`);
         this.client = null;
         for (const record of this.sessions.values()) {
+            for (const retired of record.retiredRoutes) {
+                if (retired.client !== client)
+                    continue;
+                retired.closed = true;
+                record.retiredRoutes.delete(retired);
+            }
             const entry = record.routeEntry;
             if (entry?.client !== client)
                 continue;
@@ -1832,6 +2699,8 @@ export class SubcTransportPool {
             record.routeEntry = null;
             this.deleteSessionIfEmpty(record.identityKey, record);
         }
+        for (const session of this.hostScopeCache.keys())
+            this.stopUnusedHostScopeRetry(session);
         this.transportFailures = 0;
         try {
             client.close();
@@ -1996,7 +2865,20 @@ export class SubcTransportPool {
         if (this.shuttingDown)
             return;
         this.shuttingDown = true;
+        if (this.sessionSweep)
+            clearInterval(this.sessionSweep);
+        this.sessionSweep = null;
+        this.nudgeDeliveryLogState.clear();
+        this.generationRejections.clear();
+        this.observedStarts.clear();
         this.dormantRoots.clear();
+        const scopeLookups = [...this.hostScopeCache.values()].flatMap((state) => {
+            this.cancelHostScopeRetry(state);
+            return state.pending ? [state.pending] : [];
+        });
+        this.hostScopeCache.clear();
+        this.hostScopeRefusals.clear();
+        this.hostScopeOutcomes.clear();
         // Deregistration synchronously tombstones all registered roots and invokes
         // closeProjectRoot before this method reaches its first await.
         const registration = this.lifecycleRegistration;
@@ -2009,11 +2891,16 @@ export class SubcTransportPool {
                 detached.push(owner);
         }
         this.rootIndex.clear();
+        this.sessionIndex.clear();
         this.transports.clear();
         const client = this.client;
         this.client = null;
         const pending = [...this.pendingRootCleanups];
-        await Promise.allSettled([...detached.map((owner) => this.cleanupDetached(owner)), ...pending]);
+        await Promise.allSettled([
+            ...detached.map((owner) => this.cleanupDetached(owner)),
+            ...pending,
+            ...scopeLookups,
+        ]);
         if (client) {
             try {
                 client.close();
@@ -2030,6 +2917,13 @@ export class SubcTransportPool {
             session: session && session.length > 0 ? session : DEFAULT_SESSION_ID,
         };
         const owner = this.detachSession(identityKey(identity), "session_closed");
+        if (!this.sessionIndex.has(identity.session)) {
+            const state = this.hostScopeCache.get(identity.session);
+            if (state)
+                this.cancelHostScopeRetry(state);
+            this.hostScopeCache.delete(identity.session);
+            this.hostScopeRefusals.delete(identity.session);
+        }
         if (owner)
             await this.cleanupDetached(owner);
     }