@cortexkit/aft-bridge 0.59.0 → 0.61.0

package/dist/subc-transport.js

@@ -17,12 +17,13 @@
  * published plugin dist; it is never a published runtime dependency.
  */
 import { statSync } from "node:fs";
-import { AuthError, connectionFileExists, isConsumerReconnectTransient, StaleRouteHandleError, SubcCallError, SubcClient, SubcError, } from "@cortexkit/subc-client";
+import { AuthError, connectionFileExists, isConsumerReconnectTransient, routeCloseReason, 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";
-import { callPresetFor, PRESET_FIELD, 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() {
@@ -49,6 +50,61 @@ export class SubcRouteClosedMidCallError extends SubcCallError {
         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
@@ -101,6 +157,8 @@ 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")
@@ -164,6 +222,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
@@ -305,7 +371,7 @@ class BgSubscription {
     identity;
     acquireClient;
     dropClient;
-    consumerIdentity;
+    openRoute;
     onNudge;
     sleep;
     canAttach;
@@ -316,23 +382,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;
@@ -343,14 +411,20 @@ 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;
+    }
+    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;
@@ -477,7 +551,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)) {
@@ -536,6 +610,8 @@ class BgSubscription {
                 });
                 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) {
@@ -586,6 +662,7 @@ class BgSubscription {
                 stopDispatchProbe();
                 this.current = null;
                 this.attached = null;
+                this.route = null;
                 safeCloseRoute(client, route);
             }
             await this.backoff(backoffAttempt++);
@@ -594,14 +671,47 @@ 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) {
     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);
 }
 /**
@@ -636,17 +746,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
@@ -799,6 +917,8 @@ 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);
@@ -823,10 +943,14 @@ 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)
@@ -857,6 +981,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;
@@ -883,6 +1012,8 @@ 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();
@@ -916,11 +1047,11 @@ 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;
-        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 =
@@ -1174,7 +1305,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();
         }
@@ -1279,6 +1412,12 @@ export class SubcTransportPool {
             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();
@@ -1298,8 +1437,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 = [];
@@ -1387,7 +1530,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")
@@ -1472,19 +1615,27 @@ 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 });
     }
     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;
@@ -1507,6 +1658,7 @@ export class SubcTransportPool {
             this.sessions.delete(record.identityKey);
             this.removeIndexMembership(record);
         }
+        this.stopUnusedHostScopeRetry(record.identity.session);
     }
     /**
      * Atomically detaches one opaque identity. Nothing in this method awaits: it
@@ -1520,16 +1672,14 @@ 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;
         record.routeEntry = null;
         if (routeEntry)
             routeEntry.closed = true;
+        this.stopUnusedHostScopeRetry(record.identity.session);
         return { record, bgSub, routeEntry };
     }
     async cleanupDetached(detached) {
@@ -1589,6 +1739,17 @@ export class SubcTransportPool {
         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();
@@ -1760,17 +1921,16 @@ export class SubcTransportPool {
             const clearRouteEntry = (entry) => {
                 if (record.routeEntry !== entry)
                     return;
-                entry.closed = true;
-                entry.closedBy ??= "route replaced";
-                record.routeEntry = null;
-                record.retiredRoutes.add(entry);
-                this.closeRetiredRoute(record, entry);
+                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, {
@@ -1785,7 +1945,8 @@ export class SubcTransportPool {
                 // route remains reusable, and no replacement may cut its other calls.
                 if (aborted ||
                     isRouteProvenAbsentError(error) ||
-                    (error instanceof SubcError && error.closeReason !== undefined)) {
+                    (error instanceof SubcError && error.closeReason !== undefined) ||
+                    isSubcFrameReadTimeoutError(error)) {
                     clearRouteEntry(entry);
                 }
                 if (aborted || !ownsClient || this.client !== client)
@@ -1877,10 +2038,15 @@ export class SubcTransportPool {
                     return reply;
                 }
                 catch (requestError) {
-                    const error = routeClosedMidCallError(requestError, routeAndEntry.entry, record);
+                    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
@@ -1978,9 +2144,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;
@@ -1994,6 +2165,7 @@ export class SubcTransportPool {
                 throw new SubcTransportShuttingDownError();
             }
             this.client = client;
+            owner = client;
             this.hadWorkingClient = true;
             this.transportFailures = 0;
             return client;
@@ -2027,10 +2199,7 @@ export class SubcTransportPool {
             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 ||
@@ -2046,6 +2215,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) => {
@@ -2054,6 +2232,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");
@@ -2067,6 +2246,393 @@ 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;
@@ -2077,6 +2643,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) {
@@ -2092,32 +2667,46 @@ 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)
                 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;
@@ -2166,6 +2755,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();
@@ -2337,6 +2928,13 @@ export class SubcTransportPool {
         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;
@@ -2349,11 +2947,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();
@@ -2370,6 +2973,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);
     }