@cortexkit/aft-bridge 0.49.3 → 0.50.0

package/dist/subc-transport.js

@@ -16,7 +16,10 @@
  * 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 { connectionFileExists, isConsumerReconnectTransient, StaleRouteHandleError, SubcCallError, SubcClient, SubcError, } from "@cortexkit/subc-client";
+import { log } from "./active-logger.js";
+import { asCanonicalRootPath, asRootGeneration, LifecycleRegistry, } from "./lifecycle-registry.js";
 import { canonicalizeProjectRoot } from "./project-identity.js";
 import { parseStatusBarCounts } from "./status-bar.js";
 /** The subc module id AFT registers under (matches the daemon manifest). */
@@ -37,6 +40,8 @@ const MAX_CONSECUTIVE_TRANSPORT_FAILURES = 3;
  * (otherwise a permanently-failing route resubscribes in a 100ms hot loop). (B-#2.)
  */
 const BG_STABLE_MS = 5_000;
+const BG_LIFECYCLE_LOG_INTERVAL_MS = 60_000;
+const BG_DISPATCH_PROBE_INTERVAL_MS = 60_000;
 /**
  * Session fallback when a tool runtime carries no session id, mirroring the Rust
  * `DEFAULT_SESSION_ID` (`protocol.rs`). Keeps undo/checkpoint/bash namespacing
@@ -51,23 +56,62 @@ const DEFAULT_SESSION_ID = "__default__";
  * with a synthetic success rather than a route call.
  */
 const LOCALLY_SATISFIED_COMMANDS = new Set(["configure"]);
+/** Stable classification for a request that loses its root to coordinated reap. */
+export class SubcRootReapedError extends Error {
+    code = "root_reaped";
+    name = "SubcRootReapedError";
+    canonicalRoot;
+    expectedGeneration;
+    currentGeneration;
+    concretePoolId;
+    currentConcretePoolId;
+    constructor(fields) {
+        super(`subc root was reaped: ${fields.canonicalRoot}`);
+        this.canonicalRoot = fields.canonicalRoot;
+        this.expectedGeneration = fields.expectedGeneration;
+        this.currentGeneration = fields.currentGeneration;
+        this.concretePoolId = fields.concretePoolId;
+        this.currentConcretePoolId = fields.currentConcretePoolId;
+    }
+}
+/** Stable classification for an operation holding an older root generation. */
+export class SubcRootGenerationExpiredError extends Error {
+    code = "root_generation_expired";
+    name = "SubcRootGenerationExpiredError";
+    canonicalRoot;
+    expectedGeneration;
+    currentGeneration;
+    concretePoolId;
+    currentConcretePoolId;
+    constructor(fields) {
+        super(`subc root generation expired: ${fields.canonicalRoot}`);
+        this.canonicalRoot = fields.canonicalRoot;
+        this.expectedGeneration = fields.expectedGeneration;
+        this.currentGeneration = fields.currentGeneration;
+        this.concretePoolId = fields.concretePoolId;
+        this.currentConcretePoolId = fields.currentConcretePoolId;
+    }
+}
+/** A synchronous lifecycle demand check could not establish that the root exists. */
+export class SubcRootDemandRequiredError extends Error {
+    code = "root_demand_required";
+    canonicalRoot;
+    constructor(root) {
+        super(`positive live demand is required before creating subc root state: ${root}`);
+        this.name = "SubcRootDemandRequiredError";
+        this.canonicalRoot = root;
+    }
+}
 function identityKey(identity) {
     return `${identity.project_root}\u0000${identity.harness}\u0000${identity.session}`;
 }
 /**
- * One session's held-open bg_events subscription with its OWN reconnect driver.
- *
- * The idle-stranding fix (Oracle bg_fc2d4119 #3): the resubscribe loop is
- * INDEPENDENT of tool calls. When the subscription's `closed` promise rejects (a
- * socket drop / route GOODBYE / Error), the loop itself reconnects (via the pool's
- * shared single-flight client) and resubscribes — it never waits for a future tool
- * call. So an idle agent (no tool traffic) whose connection drops is still woken
- * for a completion that landed while disconnected (the durable Rust registry holds
- * it until acked; resubscribe + the immediate forced-drain replay it).
+ * One session's held-open bg_events subscription with its own reconnect driver.
  *
- * The loop is a single sequential async task (only one attempt in flight at a
- * time), so no numeric generation guard is needed — `stopped` plus one-instance-
- * per-identity (the pool's bgSubs map) prevents duplicate or stale subscribes.
+ * The reconnect loop is independent of tool calls, including provider StreamEnd:
+ * the module emits StreamEnd when a route is replaced, so only `stop()` proves
+ * that a clean end was requested by this consumer. Reopening the dedicated route
+ * also forces an outbox drain, recovering completions queued while disconnected.
  */
 class BgSubscription {
     identity;
@@ -76,26 +120,37 @@ class BgSubscription {
     consumerIdentity;
     onNudge;
     sleep;
+    canAttach;
+    onRootAttachFailure;
+    onDormant;
+    dispatchProbeIntervalMs;
+    nudgeRef;
+    isCurrent;
     stopped = false;
     /** The live subscription handle, read by stop() to wake the loop's `await closed`. */
     current = null;
     loop;
-    constructor(identity, acquireClient, dropClient, consumerIdentity, onNudge, sleep) {
+    lifecycleLogState = new Map();
+    nudgeReceiptLogState = null;
+    constructor(identity, acquireClient, dropClient, consumerIdentity, onNudge, sleep, canAttach, onRootAttachFailure, onDormant, dispatchProbeIntervalMs, nudgeRef, isCurrent = () => true) {
         this.identity = identity;
         this.acquireClient = acquireClient;
         this.dropClient = dropClient;
         this.consumerIdentity = consumerIdentity;
         this.onNudge = onNudge;
         this.sleep = sleep;
+        this.canAttach = canAttach;
+        this.onRootAttachFailure = onRootAttachFailure;
+        this.onDormant = onDormant;
+        this.dispatchProbeIntervalMs = dispatchProbeIntervalMs;
+        this.nudgeRef = nudgeRef;
+        this.isCurrent = isCurrent;
         this.loop = this.run();
     }
     async stop() {
         this.stopped = true;
-        // Wake a live `await sub.closed` so the loop unwinds via its StreamEnd path,
-        // where the `finally` is the SOLE owner of closeRouteChannel (so the channel
-        // is closed exactly once, never double-closed by stop() + the loop). If the
-        // loop is between routeOpen and subscribe, its post-subscribe `stopped`
-        // re-check (or the pre-subscribe check) closes/returns instead.
+        // 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;
         if (sub) {
             try {
@@ -107,84 +162,200 @@ class BgSubscription {
         }
         await this.loop.catch(() => undefined);
     }
+    info(kind, message) {
+        const now = Date.now();
+        const state = this.lifecycleLogState.get(kind);
+        if (state && now - state.lastEmittedAt < BG_LIFECYCLE_LOG_INTERVAL_MS) {
+            state.suppressed += 1;
+            return;
+        }
+        const suppressed = state?.suppressed ?? 0;
+        this.lifecycleLogState.set(kind, { lastEmittedAt: now, suppressed: 0 });
+        const suffix = suppressed > 0 ? ` suppressed=${suppressed}` : "";
+        log(`subc bg_events: ${message}${suffix}`, { sessionId: this.identity.session });
+    }
+    routeId(route) {
+        return `${route.channel}@${route.epoch}`;
+    }
+    recordNudgeReceipt(routeId) {
+        const now = Date.now();
+        const state = this.nudgeReceiptLogState;
+        if (state && now - state.lastEmittedAt < BG_LIFECYCLE_LOG_INTERVAL_MS) {
+            state.count += 1;
+            return;
+        }
+        const count = (state?.count ?? 0) + 1;
+        this.nudgeReceiptLogState = { lastEmittedAt: now, count: 0 };
+        log(`subc bg_events: nudge received channel=${routeId} count=${count}`, {
+            sessionId: this.identity.session,
+        });
+    }
+    errorText(error) {
+        return error instanceof Error ? `${error.name}: ${error.message}` : String(error);
+    }
+    startDispatchProbe(client, routeId) {
+        const initial = client.droppedIngressFrames;
+        if (typeof initial !== "number")
+            return () => undefined;
+        let previous = initial;
+        const timer = setInterval(() => {
+            const total = client.droppedIngressFrames;
+            if (typeof total !== "number" || total <= previous)
+                return;
+            const delta = total - previous;
+            previous = total;
+            this.info("dispatch-epoch-drop", `client ingress epoch drops scope=client observed_while_channel=${routeId} delta=${delta} total=${total}`);
+        }, this.dispatchProbeIntervalMs);
+        timer.unref?.();
+        return () => clearInterval(timer);
+    }
     async run() {
-        let attempt = 0;
+        let backoffAttempt = 0;
+        let reconnectAttempt = 0;
+        let reconnecting = false;
+        const beginReconnect = () => {
+            reconnecting = true;
+            reconnectAttempt = reconnectAttempt === 0 ? 1 : reconnectAttempt + 1;
+        };
+        const giveUp = (reason) => {
+            this.info("reconnect-gave-up", `reconnect gave-up attempt=${reconnectAttempt} reason=${reason}`);
+        };
         while (!this.stopped) {
+            if (!this.isCurrent()) {
+                if (reconnecting)
+                    giveUp("stale-session");
+                return;
+            }
+            if (!this.canAttach()) {
+                if (reconnecting)
+                    giveUp("root-dormant");
+                this.onDormant();
+                return;
+            }
+            if (reconnecting) {
+                this.info("reconnect-attempt", `reconnect attempt=${reconnectAttempt}`);
+            }
             let client;
             try {
                 client = await this.acquireClient();
             }
-            catch {
-                await this.backoff(attempt++);
+            catch (err) {
+                if (!reconnecting)
+                    beginReconnect();
+                this.info("reconnect-error", `reconnect error attempt=${reconnectAttempt} error=${this.errorText(err)}`);
+                await this.backoff(backoffAttempt++);
+                if (reconnecting)
+                    reconnectAttempt += 1;
                 continue;
             }
-            if (this.stopped)
+            if (this.stopped) {
+                if (reconnecting)
+                    giveUp("stopped");
+                return;
+            }
+            if (!this.isCurrent()) {
+                if (reconnecting)
+                    giveUp("stale-session");
+                return;
+            }
+            if (!this.canAttach()) {
+                if (reconnecting)
+                    giveUp("root-dormant");
+                this.onDormant();
                 return;
+            }
             let route;
             try {
-                // A second dedicated route isolates bg_events from the tool route's
+                // 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 });
             }
             catch (err) {
-                // routeOpen failed. If it signals a dead CONNECTION, drop the shared
-                // client so the next `acquireClient` reconnects fresh — the idle-stranding
-                // fix (B-#1): `acquireClient` returns the cached client, so without this an
-                // idle bg loop would resubscribe forever onto the same dead socket.
+                if (this.isCurrent() && this.onRootAttachFailure(err)) {
+                    if (reconnecting)
+                        giveUp("root-dormant");
+                    this.onDormant();
+                    return;
+                }
                 if (isConsumerReconnectTransient(err))
                     this.dropClient(client);
-                await this.backoff(attempt++);
+                if (!reconnecting)
+                    beginReconnect();
+                this.info("reconnect-error", `reconnect error attempt=${reconnectAttempt} error=${this.errorText(err)}`);
+                await this.backoff(backoffAttempt++);
+                if (reconnecting)
+                    reconnectAttempt += 1;
                 continue;
             }
-            if (this.stopped) {
+            if (this.stopped || !this.isCurrent()) {
                 safeCloseRoute(client, route);
+                if (reconnecting)
+                    giveUp(this.stopped ? "stopped" : "stale-session");
                 return;
             }
-            // Route lifetime: the `finally` guarantees closeRouteChannel on every exit
-            // path from here (StreamEnd return, drop+resubscribe, stopped) so the
-            // dedicated route never leaks (B-#2).
             const subscribedAt = Date.now();
+            const routeId = this.routeId(route);
+            let stopDispatchProbe = () => undefined;
             try {
                 const sub = client.subscribe(route, { op: "bg_events" }, () => {
-                    if (!this.stopped)
-                        this.onNudge();
+                    if (this.stopped) {
+                        this.info("nudge-drop-stopped", `nudge dropped cause=subscription-stopped channel=${routeId}`);
+                        return;
+                    }
+                    this.recordNudgeReceipt(routeId);
+                    if (!this.isCurrent()) {
+                        this.info("nudge-stale-carrier", `nudge carried by stale subscription; checking current session channel=${routeId}`);
+                    }
+                    this.onNudge();
                 });
                 this.current = sub;
-                // stop() may have fired between the pre-subscribe check and here; self-
-                // unsubscribe so the await below resolves immediately (avoids a stop()
-                // that hangs awaiting a subscription nobody woke).
+                stopDispatchProbe = this.startDispatchProbe(client, routeId);
+                this.info("subscription-open", `subscription open channel=${routeId}`);
+                if (reconnecting) {
+                    this.info("reconnect-success", `reconnect success attempt=${reconnectAttempt} channel=${routeId}`);
+                    reconnecting = false;
+                    reconnectAttempt = 0;
+                }
+                // stop() may have fired between routeOpen and subscribe. Unsubscribe so
+                // the held `closed` promise resolves and the route can unwind.
                 if (this.stopped)
                     sub.unsubscribe();
-                // Immediate forced-drain replay: a completion that landed while we were
-                // disconnected is recovered now (resubscribe == the outbox replay trigger).
-                if (!this.stopped)
+                // 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();
                 await sub.closed;
-                // StreamEnd = an intentional close (our unsubscribe or module teardown).
-                // Do NOT resubscribe.
-                return;
+                this.info("stream-end", `stream ended channel=${routeId}`);
+                if (this.stopped) {
+                    giveUp("stopped");
+                    return;
+                }
+                // Provider StreamEnd is also emitted for route replacement; without an
+                // explicit local stop it must reopen rather than strand an idle session.
+                beginReconnect();
             }
             catch (err) {
-                // Dropped (socket death / route GOODBYE / Error). Resubscribe — this is
-                // the independent reconnect driver that fixes idle-stranding.
-                if (this.stopped)
+                const routeId = this.routeId(route);
+                this.info("stream-error", `stream error channel=${routeId} error=${this.errorText(err)}`);
+                if (this.stopped) {
+                    giveUp("stopped");
                     return;
-                // A dead-connection drop must replace the client (B-#1); a route-only
-                // GOODBYE keeps the client and just re-opens a fresh route.
+                }
                 if (isConsumerReconnectTransient(err))
                     this.dropClient(client);
-                // Reset backoff ONLY if the subscription was stable before dropping;
-                // otherwise a permanently-failing route would resubscribe in a 100ms hot
-                // loop and never reach the cap (B-#2).
                 if (Date.now() - subscribedAt >= BG_STABLE_MS)
-                    attempt = 0;
+                    backoffAttempt = 0;
+                beginReconnect();
             }
             finally {
+                stopDispatchProbe();
                 this.current = null;
                 safeCloseRoute(client, route);
             }
-            await this.backoff(attempt++);
+            await this.backoff(backoffAttempt++);
         }
+        if (reconnecting)
+            giveUp("stopped");
     }
     async backoff(attempt) {
         const ms = Math.min(100 * 2 ** Math.min(attempt, 6), 2000);
@@ -198,6 +369,20 @@ function isRouteProvenAbsentError(err) {
     return ((err instanceof SubcError && err.code === "unknown_channel") ||
         err instanceof StaleRouteHandleError);
 }
+/**
+ * A daemon can reject a route bind after the root has been reclaimed. This
+ * signature is deliberately narrower than config_divergence: other divergence
+ * causes remain transient from the transport's point of view.
+ */
+function isAbsentRootRouteError(err) {
+    return (isRecord(err) &&
+        err.code === "config_divergence" &&
+        typeof err.message === "string" &&
+        err.message.includes("project root does not exist"));
+}
+function absentRootError(root) {
+    return new SubcError(`invalid route project root: project root does not exist: ${root}`, "config_divergence");
+}
 /**
  * Fire-and-forget route close that can never throw — neither synchronously (a
  * client that rejects/throws when closing a route on an already-dead socket) nor
@@ -227,20 +412,33 @@ class RouteTornDownError extends Error {
  * `structuredContent`, so re-lifting it makes everything downstream (status_bar,
  * bg_completions, preview_diff, code, …) byte-identical to NDJSON.
  *
- * Every AFT tool reply over subc carries this envelope with a boolean `success`
- * and string `text`. A reply missing the envelope, or whose lifted shape lacks a
- * boolean `success`, is a PROTOCOL VIOLATION — never a tool result — and is thrown
- * rather than coerced. Coercing it (the old `{success:false,text:""}` /
- * raw-record fallback) could let a malformed reply with `success === undefined`
- * read downstream as a successful tool result (audit B-#7). Surfacing it loudly is
- * the honest contract: a broken wire shape is a failure, not a silent empty pass.
+ * Every AFT tool reply over subc carries this envelope with a boolean `success`.
+ * During the wire transition, `structuredContent.text` may be omitted; the bridge
+ * synthesizes it only from exactly one outer text block, while a present field wins
+ * unchanged. A reply missing the envelope, lacking boolean `success`, or missing
+ * text without an unambiguous outer block is a PROTOCOL VIOLATION — never a tool
+ * result — and is thrown rather than coerced. Coercing it (the old
+ * `{success:false,text:""}` / raw-record fallback) could let a malformed reply with
+ * `success === undefined` read downstream as a successful tool result (audit B-#7).
+ * Surfacing it loudly is the honest contract: a broken wire shape is a failure, not
+ * a silent empty pass.
  */
 function reliftReply(reply) {
     if (!isRecord(reply) || !isRecord(reply.structuredContent)) {
         throw new Error("subc tool reply is missing the structuredContent envelope (protocol violation)");
     }
     const flat = reply.structuredContent;
-    if (typeof flat.success !== "boolean" || typeof flat.text !== "string") {
+    if (typeof flat.success !== "boolean") {
+        throw new Error("subc tool reply structuredContent lacks a boolean `success` / string `text` (protocol violation)");
+    }
+    if (!Object.hasOwn(flat, "text")) {
+        const content = reply.content;
+        const block = Array.isArray(content) && content.length === 1 ? content[0] : undefined;
+        if (isRecord(block) && block.type === "text" && typeof block.text === "string") {
+            return { ...flat, text: block.text };
+        }
+    }
+    if (typeof flat.text !== "string") {
         throw new Error("subc tool reply structuredContent lacks a boolean `success` / string `text` (protocol violation)");
     }
     return flat;
@@ -253,15 +451,24 @@ function reliftReply(reply) {
 class SubcTransport {
     pool;
     projectRoot;
+    generation;
     lastStatusBar;
     cachedStatus = null;
-    constructor(pool, projectRoot) {
+    constructor(pool, projectRoot, generation) {
         this.pool = pool;
         this.projectRoot = projectRoot;
+        this.generation = generation;
     }
     getCwd() {
         return this.projectRoot;
     }
+    /** Generation provenance is intentionally observable for lifecycle tests and nudge wiring. */
+    getGeneration() {
+        return this.generation;
+    }
+    getConcretePoolId() {
+        return this.pool.getConcretePoolId();
+    }
     getStatusBar() {
         return this.lastStatusBar;
     }
@@ -283,12 +490,19 @@ class SubcTransport {
             session: session && session.length > 0 ? session : DEFAULT_SESSION_ID,
         };
     }
+    assertCurrent() {
+        this.pool.assertFacadeCurrent(this.projectRoot, this.generation, "facade_use");
+    }
     async toolCall(sessionId, name, rawArgs = {}, options) {
+        this.assertCurrent();
         const { preview, timeoutMs, onProgress } = this.splitOptions(options);
         const body = { name, arguments: rawArgs };
+        const editSlotSurvives = this.pool.getEditSlotSurvives();
+        if (editSlotSurvives !== undefined)
+            body.edit_slot_survives = editSlotSurvives;
         if (preview === true)
             body.preview = true;
-        const reply = await this.pool.routeRequest(this.identityFor(sessionId), body, timeoutMs, onProgress);
+        const reply = await this.pool.routeRequest(this.identityFor(sessionId), body, timeoutMs, onProgress, this.generation);
         const result = reliftReply(reply);
         this.captureStatusBar(result);
         return result;
@@ -304,12 +518,17 @@ class SubcTransport {
      * what scopes it. `configure` is satisfied locally (binding is the configure).
      */
     async send(command, params = {}, options) {
+        this.assertCurrent();
         if (LOCALLY_SATISFIED_COMMANDS.has(command)) {
             return { success: true, command, subc_local: true };
         }
         const { timeoutMs, onProgress } = this.splitOptions(options);
         const session = typeof params.session_id === "string" ? params.session_id : undefined;
-        const reply = await this.pool.routeRequest(this.identityFor(session), { name: command, arguments: params }, timeoutMs, onProgress);
+        const body = { name: command, arguments: params };
+        const editSlotSurvives = this.pool.getEditSlotSurvives();
+        if (editSlotSurvives !== undefined)
+            body.edit_slot_survives = editSlotSurvives;
+        const reply = await this.pool.routeRequest(this.identityFor(session), body, timeoutMs, onProgress, this.generation);
         const response = reliftReply(reply);
         this.captureStatusBar(response);
         return response;
@@ -328,9 +547,9 @@ class SubcTransport {
     }
 }
 /**
- * Route cache over one authenticated subc client. Implements {@link AftTransportPool}
- * so it drops into the plugin in place of {@link BridgePool} behind the shared
- * interface. One client per process; routes keyed by `(root, harness, session)`.
+ * Route cache over one authenticated subc client. In lifecycle mode this class
+ * also owns the concrete pool's root index; the registry owns timer and root
+ * transition state, while this class owns sessions, routes, and subscriptions.
  */
 export class SubcTransportPool {
     harness;
@@ -339,22 +558,38 @@ export class SubcTransportPool {
     consumerIdentity;
     connectFn;
     onBgEventsNudge;
+    onBgEventsNudgeRef;
     bgBackoffSleep;
+    bgDispatchProbeIntervalMs;
+    lifecycleDemandCheck;
+    onLifecycleEvent;
+    onBgNudgeRejected;
+    lifecycleRegistry;
+    registryUsesPoolEventSink = false;
+    lifecycleRegistration = null;
+    outerFacadeEvictor;
     client = null;
     /** Single-flight guard so concurrent first calls share one connect. */
     connecting = null;
-    /** Per-session lifecycle records keyed by a string built from root, harness, and session. */
+    /** Per-session records keyed by the opaque identity key. */
     sessions = new Map();
     /**
-     * Consecutive NON-transient transport throws on the current client with no
-     * success in between. Resets to 0 on any successful request. Trips a client drop
-     * at {@link MAX_CONSECUTIVE_TRANSPORT_FAILURES} to recover a half-open socket
-     * whose timeouts never classify transient (B-#4).
+     * The sole root-scoped session enumeration authority. Keys are opaque and are
+     * removed by the same detacher that removes the corresponding session record.
      */
+    rootIndex = new Map();
+    /** Roots whose route binds must stay dormant until their directories return. */
+    dormantRoots = new Map();
+    /** Consecutive non-transient failures on the current pool-local client. */
     transportFailures = 0;
-    /** Per-root transport facades returned by getBridge/getActiveBridgeForRoot. */
+    /** Concrete per-root facades, including their captured root generation. */
     transports = new Map();
+    generationRejections = new Set();
+    nudgeDeliveryLogState = new Map();
+    pendingRootCleanups = new Set();
     shuttingDown = false;
+    editSlotSurvives;
+    editSlotSurvivesCaptured = false;
     constructor(options) {
         this.connectionFile = options.connectionFile;
         this.harness = options.harness;
@@ -362,205 +597,603 @@ export class SubcTransportPool {
         this.consumerIdentity = options.consumerIdentity;
         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.bgDispatchProbeIntervalMs =
+            options.bgDispatchProbeIntervalMs ?? BG_DISPATCH_PROBE_INTERVAL_MS;
+        const lifecycle = options.lifecycle;
+        const demandCheck = options.lifecycleDemandCheck ?? options.demandCheck ?? lifecycle?.demandCheck;
+        this.lifecycleDemandCheck = demandCheck;
+        this.onLifecycleEvent = options.onLifecycleEvent ?? lifecycle?.onEvent;
+        this.onBgNudgeRejected = options.onBgNudgeRejected;
+        this.outerFacadeEvictor =
+            options.evictOuterFacade ?? lifecycle?.evictOuterFacade ?? (() => undefined);
+        const lifecycleRegistry = options.lifecycleRegistry ?? lifecycle?.registry;
+        if (lifecycleRegistry || demandCheck || options.lifecycleRegistration) {
+            this.registryUsesPoolEventSink =
+                lifecycleRegistry === undefined && this.onLifecycleEvent !== undefined;
+            this.lifecycleRegistry =
+                lifecycleRegistry ??
+                    new LifecycleRegistry({
+                        demandCheck: demandCheck ? (root, poolId) => demandCheck(root, poolId) : undefined,
+                        onEvent: this.registryUsesPoolEventSink ? this.onLifecycleEvent : undefined,
+                    });
+            if (options.lifecycleRegistration) {
+                this.bindLifecycleRegistration(options.lifecycleRegistration);
+            }
+            else {
+                this.bindLifecycleRegistration(this.lifecycleRegistry.registerLifecyclePool(this, {
+                    reapingEnabled: options.reapingEnabled ?? lifecycle?.reapingEnabled ?? false,
+                    evictOuterFacade: (root, generation) => this.outerFacadeEvictor(root, generation),
+                }));
+            }
+        }
     }
     /**
-     * Fail-loud presence check (memory: present-but-unconnectable must never silently
-     * downgrade to standalone). Returns false only when the file is genuinely absent.
+     * Bind a wrapper-owned registration after its generation-matched eviction
+     * callback has been installed. The handle is the only authority that may
+     * deregister this concrete pool.
      */
+    bindLifecycleRegistration(registration) {
+        if (this.lifecycleRegistration && this.lifecycleRegistration !== registration) {
+            this.lifecycleRegistration.deregister();
+        }
+        this.lifecycleRegistration = registration;
+    }
+    /** Construction helper for wrappers that own the registration sequence. */
+    registerLifecyclePool(registry, options) {
+        this.lifecycleRegistry = registry;
+        this.outerFacadeEvictor = options.evictOuterFacade;
+        const registration = registry.registerLifecyclePool(this, options);
+        this.bindLifecycleRegistration(registration);
+        return registration;
+    }
+    /** Replace only the callback; registration identity and switch stay immutable. */
+    setOuterFacadeEvictor(evictOuterFacade) {
+        this.outerFacadeEvictor = evictOuterFacade;
+    }
+    getConcretePoolId() {
+        return this.lifecycleRegistration?.concretePoolId;
+    }
+    getCurrentRootGeneration(root) {
+        return this.currentGeneration(root);
+    }
+    recordBgNudgeRejection(ref) {
+        const event = {
+            type: "subc_bg_nudge_rejected",
+            canonicalRoot: ref.canonicalRoot,
+            session: ref.session,
+            expectedGeneration: ref.generation,
+            currentGeneration: this.currentGeneration(ref.canonicalRoot),
+            expectedConcretePoolId: ref.concretePoolId,
+            currentConcretePoolId: this.currentPoolId(),
+        };
+        this.onBgNudgeRejected?.(event);
+    }
+    getLifecycleRegistration() {
+        return this.lifecycleRegistration;
+    }
+    getLifecycleRegistry() {
+        return this.lifecycleRegistry;
+    }
     static async connectionAvailable(connectionFile) {
         return connectionFileExists(connectionFile);
     }
-    getBridge(projectRoot) {
-        const key = canonicalizeProjectRoot(projectRoot);
-        let transport = this.transports.get(key);
-        if (!transport) {
-            transport = new SubcTransport(this, key);
-            this.transports.set(key, transport);
+    canonicalRoot(projectRoot) {
+        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.
+     */
+    rootCanAttach(root) {
+        let directoryExists = false;
+        try {
+            directoryExists = statSync(root).isDirectory();
+        }
+        catch {
+            // Missing, inaccessible, or otherwise unusable roots cannot be bound.
+        }
+        if (directoryExists) {
+            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;
+    }
+    markRootDormant(root, rejection) {
+        const existing = this.dormantRoots.get(root);
+        if (existing)
+            return existing;
+        const error = rejection instanceof SubcError ? rejection : absentRootError(root);
+        this.dormantRoots.set(root, error);
+        log(`root ${root} reclaimed/absent; suspending attach until it exists`);
+        return error;
+    }
+    assertRootCanAttach(root) {
+        if (this.rootCanAttach(root))
+            return;
+        throw this.dormantRoots.get(root) ?? absentRootError(root);
+    }
+    lifecycleEnabled() {
+        // A disabled registration deliberately behaves like the pre-reaper pool:
+        // synthetic roots may be used, no demand check is required, and no sweep can
+        // acquire a tombstone for the pool.
+        return Boolean(this.lifecycleRegistry && this.lifecycleRegistration?.reapingEnabled);
+    }
+    currentGeneration(root) {
+        const registration = this.lifecycleRegistration;
+        return registration && this.lifecycleRegistry
+            ? this.lifecycleRegistry.currentGeneration(registration.concretePoolId, root)
+            : undefined;
+    }
+    currentPoolId() {
+        return this.lifecycleRegistration?.concretePoolId;
+    }
+    isCurrentLiveGeneration(root, generation) {
+        if (!this.lifecycleEnabled())
+            return true;
+        const registry = this.lifecycleRegistry;
+        const poolId = this.currentPoolId();
+        return (registry !== undefined &&
+            poolId !== undefined &&
+            generation !== undefined &&
+            registry.isCurrentLiveGeneration(poolId, root, generation));
+    }
+    isRootTombstoned(root, generation) {
+        const registry = this.lifecycleRegistry;
+        const poolId = this.currentPoolId();
+        return (registry !== undefined &&
+            poolId !== undefined &&
+            registry.isTombstoned(poolId, root, generation));
+    }
+    recordGenerationRejection(root, expectedGeneration, boundary) {
+        if (!this.lifecycleEnabled())
+            return;
+        const poolId = this.currentPoolId();
+        const registry = this.lifecycleRegistry;
+        if (!poolId || !registry)
+            return;
+        const key = `${poolId}\u0000${root}\u0000${expectedGeneration}\u0000${boundary}`;
+        if (this.generationRejections.has(key))
+            return;
+        this.generationRejections.add(key);
+        registry.recordGenerationRejection(poolId, root, expectedGeneration, boundary);
+        if (this.registryUsesPoolEventSink)
+            return;
+        this.onLifecycleEvent?.({
+            type: "subc_root_generation_rejected",
+            realm: registry.realm,
+            concretePoolId: poolId,
+            canonicalRoot: root,
+            expectedGeneration,
+            currentGeneration: registry.currentGeneration(poolId, root),
+            boundary,
+        });
+    }
+    generationExpiredError(root, expectedGeneration) {
+        const currentGeneration = this.currentGeneration(root);
+        this.recordGenerationRejection(root, expectedGeneration, "stale_generation");
+        return new SubcRootGenerationExpiredError({
+            canonicalRoot: root,
+            expectedGeneration,
+            currentGeneration,
+            concretePoolId: this.currentPoolId(),
+            currentConcretePoolId: this.currentPoolId(),
+        });
+    }
+    rootReapedError(record) {
+        return new SubcRootReapedError({
+            canonicalRoot: record.canonicalRoot,
+            expectedGeneration: record.generation ?? asRootGeneration(1),
+            currentGeneration: record.generation
+                ? this.currentGeneration(record.canonicalRoot)
+                : undefined,
+            concretePoolId: this.currentPoolId(),
+            currentConcretePoolId: this.currentPoolId(),
+        });
+    }
+    assertFacadeCurrent(root, expectedGeneration, boundary) {
+        this.assertGeneration(root, expectedGeneration, boundary);
+    }
+    assertGeneration(root, expectedGeneration, boundary) {
+        if (!this.lifecycleEnabled() || expectedGeneration === undefined)
+            return;
+        if (this.isCurrentLiveGeneration(root, expectedGeneration))
+            return;
+        if (this.isRootTombstoned(root, expectedGeneration)) {
+            throw new SubcRootReapedError({
+                canonicalRoot: root,
+                expectedGeneration,
+                currentGeneration: this.currentGeneration(root),
+                concretePoolId: this.currentPoolId(),
+                currentConcretePoolId: this.currentPoolId(),
+            });
+        }
+        this.recordGenerationRejection(root, expectedGeneration, boundary);
+        throw this.generationExpiredError(root, expectedGeneration);
+    }
+    assertRecordLive(record) {
+        if (!this.isCurrentSession(record.identityKey, record)) {
+            if (record.teardownReason === "root_reaped")
+                throw this.rootReapedError(record);
+            throw new RouteTornDownError("subc session closed");
+        }
+        this.assertGeneration(record.canonicalRoot, record.generation, "route_request");
+    }
+    synchronousDemand(root) {
+        const poolId = this.currentPoolId();
+        if (!this.lifecycleEnabled() || poolId === undefined)
+            return true;
+        if (!this.lifecycleDemandCheck)
+            throw new SubcRootDemandRequiredError(root);
+        const result = this.lifecycleDemandCheck(root, poolId);
+        if (typeof result === "boolean")
+            return result;
+        return result.exists !== false;
+    }
+    makeFacade(root, generation) {
+        const existing = this.transports.get(root);
+        if (existing && (!this.lifecycleEnabled() || existing.getGeneration() === generation)) {
+            return existing;
         }
+        const transport = new SubcTransport(this, root, generation);
+        this.transports.set(root, transport);
         return transport;
     }
+    /**
+     * Return a live facade. Legacy construction remains synchronous. Lifecycle
+     * construction uses the injected synchronous demand seam so a returned facade
+     * always has a registered root and captured generation.
+     */
+    getBridge(projectRoot) {
+        const root = this.canonicalRoot(projectRoot);
+        if (this.shuttingDown && this.lifecycleEnabled()) {
+            throw new SubcCallError("terminal", "subc transport is shutting down");
+        }
+        if (!this.lifecycleEnabled())
+            return this.makeFacade(root);
+        const current = this.currentGeneration(root);
+        const existing = this.transports.get(root);
+        if (current !== undefined &&
+            this.isCurrentLiveGeneration(root, current) &&
+            existing?.getGeneration() === current) {
+            return existing;
+        }
+        if (!this.synchronousDemand(root))
+            throw new SubcRootDemandRequiredError(root);
+        const registration = this.lifecycleRegistration;
+        const registry = this.lifecycleRegistry;
+        if (!registration || !registry)
+            throw new SubcRootDemandRequiredError(root);
+        const generation = registry.registerRoot(registration.concretePoolId, root);
+        return this.makeFacade(root, generation);
+    }
+    /** Async demand entry point for registries whose existence seam is asynchronous. */
+    async getBridgeForDemand(projectRoot) {
+        const root = this.canonicalRoot(projectRoot);
+        if (this.shuttingDown || !this.lifecycleEnabled())
+            return null;
+        const registration = this.lifecycleRegistration;
+        const registry = this.lifecycleRegistry;
+        if (!registration || !registry)
+            return null;
+        const generation = await registry.ensureRootForDemand(registration.concretePoolId, root);
+        if (generation === undefined ||
+            !registry.isCurrentLiveGeneration(registration.concretePoolId, root, generation)) {
+            return null;
+        }
+        return this.makeFacade(root, generation);
+    }
+    /** Alias used by host construction code that calls the seam a demand operation. */
+    demandBridge(projectRoot) {
+        return this.getBridgeForDemand(projectRoot);
+    }
     getActiveBridgeForRoot(projectRoot) {
-        const key = canonicalizeProjectRoot(projectRoot);
-        if (!this.client)
+        const root = this.canonicalRoot(projectRoot);
+        const transport = this.transports.get(root);
+        if (!transport)
+            return null;
+        if (this.lifecycleEnabled()) {
+            return this.isCurrentLiveGeneration(root, transport.getGeneration()) ? transport : null;
+        }
+        if (!this.client || this.shuttingDown)
+            return null;
+        return transport;
+    }
+    /** Non-creating lookup requiring the complete pool/root/generation provenance. */
+    getActiveBridgeForRootGeneration(ref) {
+        const poolId = this.currentPoolId();
+        if (!this.lifecycleEnabled() || poolId === undefined || ref.concretePoolId !== poolId)
+            return null;
+        if (!this.isCurrentLiveGeneration(ref.canonicalRoot, ref.generation))
             return null;
-        return this.transports.get(key) ?? null;
+        const transport = this.transports.get(ref.canonicalRoot);
+        return transport?.getGeneration() === ref.generation ? transport : null;
     }
-    /** All live per-root facades, for session-scoped signals that must not
-     * depend on exact root-key resolution (the command carries the session ID
-     * and the module scopes by session, so fan-out is safe). */
     activeBridges() {
-        if (!this.client || this.shuttingDown)
+        if (this.shuttingDown)
             return [];
-        return [...this.transports.values()];
+        return [...this.transports.entries()].flatMap(([root, transport]) => !this.lifecycleEnabled() || this.isCurrentLiveGeneration(root, transport.getGeneration())
+            ? [transport]
+            : []);
     }
     async toolCall(projectRoot, runtime, name, rawArgs = {}, options) {
         return this.getBridge(projectRoot).toolCall(runtime.sessionID, name, rawArgs, options);
     }
-    getOrCreateSession(key) {
+    getOrCreateSession(identity, generation) {
+        const key = identityKey(identity);
+        const root = asCanonicalRootPath(identity.project_root);
         let record = this.sessions.get(key);
-        if (!record || record.closed) {
-            record = { routeEntry: null, bgSub: null, closed: false, inflight: 0 };
-            this.sessions.set(key, record);
+        if (record && !record.closed) {
+            if (this.lifecycleEnabled() && record.generation !== generation) {
+                throw this.generationExpiredError(root, generation ?? asRootGeneration(1));
+            }
+            return record;
+        }
+        record = {
+            identity,
+            identityKey: key,
+            canonicalRoot: root,
+            generation,
+            routeEntry: null,
+            bgSub: null,
+            closed: false,
+            teardownReason: null,
+            inflight: 0,
+        };
+        this.sessions.set(key, record);
+        let keys = this.rootIndex.get(root);
+        if (!keys) {
+            keys = new Set();
+            this.rootIndex.set(root, keys);
         }
+        keys.add(key);
         return record;
     }
     isCurrentSession(key, record) {
         return this.sessions.get(key) === record && !record.closed;
     }
-    deleteSessionIfEmpty(key, record) {
-        if (this.sessions.get(key) === record &&
+    currentSessionForNudge(identity) {
+        const current = this.sessions.get(identityKey(identity));
+        return current && !current.closed ? current : null;
+    }
+    nudgeRefFor(record) {
+        const poolId = this.currentPoolId();
+        const generation = record.generation;
+        if (poolId === undefined || generation === undefined)
+            return undefined;
+        return {
+            canonicalRoot: record.canonicalRoot,
+            session: record.identity.session,
+            concretePoolId: poolId,
+            generation,
+        };
+    }
+    logNudgeDelivery(kind, record, message) {
+        const key = `${kind}\u0000${record.identityKey}`;
+        const now = Date.now();
+        const state = this.nudgeDeliveryLogState.get(key);
+        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 });
+        const suffix = suppressed > 0 ? ` suppressed=${suppressed}` : "";
+        log(`subc bg_events: ${message}${suffix}`, { sessionId: record.identity.session });
+    }
+    removeIndexMembership(record) {
+        const keys = this.rootIndex.get(record.canonicalRoot);
+        if (!keys)
+            return;
+        keys.delete(record.identityKey);
+        if (keys.size === 0)
+            this.rootIndex.delete(record.canonicalRoot);
+    }
+    deleteSessionIfEmpty(_key, record) {
+        if (this.sessions.get(record.identityKey) === record &&
             !record.closed &&
             record.inflight === 0 &&
             record.routeEntry === null &&
             record.bgSub === null) {
-            this.sessions.delete(key);
+            this.sessions.delete(record.identityKey);
+            this.removeIndexMembership(record);
         }
     }
     /**
-     * Open-or-reuse a route for `identity` and send `body` as a data-plane Request.
-     * Rd reconnect is mutation-safe by construction: transport failures surface to
-     * the caller after clearing stale route/client state so the NEXT call
-     * re-establishes. The only in-place retries are route-absence proofs: either the
-     * daemon returns `unknown_channel`, or the client rejects a stale handle before
-     * writing. In both cases, the request was not delivered to the module.
-     * Tool-level errors come back as normal replies with `success:false` and are
-     * returned, not thrown.
+     * Atomically detaches one opaque identity. Nothing in this method awaits: it
+     * is the sole owner transfer used by session close, root reap, and shutdown.
      */
-    async routeRequest(identity, body, timeoutMs, onProgress) {
+    detachSession(key, reason) {
+        const record = this.sessions.get(key);
+        if (!record || record.closed)
+            return null;
+        record.closed = true;
+        record.teardownReason = reason;
+        this.sessions.delete(key);
+        this.removeIndexMembership(record);
+        const bgSub = record.bgSub;
+        record.bgSub = null;
+        const routeEntry = record.routeEntry;
+        record.routeEntry = null;
+        if (routeEntry)
+            routeEntry.closed = true;
+        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.
+            }
+        }
+        await Promise.allSettled(cleanup);
+    }
+    isReapInduced(record) {
+        return record.teardownReason === "root_reaped";
+    }
+    annotateReapError(error, record) {
+        if (!this.isReapInduced(record))
+            return error;
+        if (error instanceof SubcRootReapedError)
+            return error;
+        if (error instanceof Error) {
+            try {
+                Object.defineProperty(error, "subcTeardownReason", {
+                    configurable: true,
+                    enumerable: true,
+                    value: "root_reaped",
+                    writable: false,
+                });
+            }
+            catch {
+                // A frozen transport error cannot be annotated; use the stable wrapper.
+                return this.rootReapedError(record);
+            }
+            return error;
+        }
+        return this.rootReapedError(record);
+    }
+    /** Open or reuse a route while guarding every lifecycle boundary. */
+    async routeRequest(identity, body, timeoutMs, onProgress, expectedGeneration) {
+        const root = asCanonicalRootPath(identity.project_root);
+        let generation = expectedGeneration;
+        if (this.lifecycleEnabled()) {
+            generation ??= this.currentGeneration(root);
+            if (generation === undefined)
+                throw new SubcRootDemandRequiredError(root);
+            this.assertGeneration(root, generation, "route_request");
+        }
+        this.assertRootCanAttach(root);
         const key = identityKey(identity);
-        const record = this.getOrCreateSession(key);
+        const record = this.getOrCreateSession(identity, generation);
         record.inflight += 1;
         try {
-            const client = await this.ensureClient();
+            let client;
+            try {
+                client = await this.ensureClient();
+                this.assertRecordLive(record);
+            }
+            catch (error) {
+                throw this.annotateReapError(error, record);
+            }
             const openRoute = async () => {
-                // closeSession/shutdown marks and deletes the record synchronously. A request
-                // that was waiting for connect must not open a route for a session that no
-                // longer exists.
-                if (!this.isCurrentSession(key, record)) {
-                    throw new RouteTornDownError("subc session closed");
-                }
                 try {
+                    this.assertRecordLive(record);
                     const opened = await this.routeHandle(client, identity, record);
-                    // routeOpen may have awaited. Do not send a request after a close, even
-                    // if a stale route entry just resolved.
-                    if (!this.isCurrentSession(key, record)) {
-                        throw new RouteTornDownError("subc session closed");
-                    }
+                    this.assertRecordLive(record);
                     return opened;
                 }
-                catch (err) {
-                    // A teardown that raced the open is not a transport fault — surface it
-                    // without dropping the client or charging the failure budget.
-                    if (err instanceof RouteTornDownError)
-                        throw err;
-                    // routeOpen itself failed. Classify the error like other request failures
-                    // for transient connection death, but only while this request's session
-                    // and client are still current. A close-induced failure must not drop a
-                    // healthy client shared by other sessions.
-                    if (isConsumerReconnectTransient(err) &&
+                catch (error) {
+                    if (this.isReapInduced(record))
+                        throw this.annotateReapError(error, record);
+                    if (error instanceof RouteTornDownError)
+                        throw error;
+                    if (isConsumerReconnectTransient(error) &&
                         this.isCurrentSession(key, record) &&
                         this.client === client) {
                         this.dropClient(client);
                     }
-                    throw err;
+                    throw error;
                 }
             };
             const clearRouteEntry = (entry) => {
-                if (record.routeEntry === entry) {
-                    entry.closed = true;
-                    record.routeEntry = null;
-                    if (entry.handle != null) {
-                        // Forgetting only the local handle leaves the module's route bound
-                        // when a request times out but the shared connection remains alive.
-                        safeCloseRoute(entry.client, entry.handle);
-                    }
-                }
+                if (record.routeEntry !== entry)
+                    return;
+                entry.closed = true;
+                record.routeEntry = null;
+                if (entry.handle != null)
+                    safeCloseRoute(entry.client, entry.handle);
             };
-            const handleRequestFailure = (err, entry) => {
-                // The raw `request()` path does not turn failures into SubcCallError; it
-                // rejects with a base SubcError for route-level failures or a raw socket
-                // error for connection failures. Use `isConsumerReconnectTransient`, not
-                // `instanceof SubcCallError`, to distinguish a dead connection from a dead
-                // route.
-                //
-                // A failed request makes its own route suspect, so drop it and let the next
-                // call re-open. Check only the current entry; a stale failure must not
-                // delete a successor route in the same still-open session.
+            const handleRequestFailure = (error, entry) => {
                 clearRouteEntry(entry);
-                // Only a failure from the current session on the current client can charge
-                // or drop that client. A failure caused by closeSession sees
-                // !isCurrentSession because close marked/deleted the record before awaiting
-                // transport cleanup.
-                if (this.isCurrentSession(key, record) && this.client === client) {
-                    if (isConsumerReconnectTransient(err)) {
-                        this.transportFailures = 0;
-                        this.dropClient(client);
-                    }
-                    else if (!isRouteProvenAbsentError(err) &&
-                        ++this.transportFailures >= MAX_CONSECUTIVE_TRANSPORT_FAILURES) {
-                        // A run of non-transient throws (timeouts / route GOODBYEs) with no
-                        // success between them is a half-open socket: local writes succeed but
-                        // no response ever returns, so isConsumerReconnectTransient never fires
-                        // and the client would otherwise be kept forever. Force reconnect.
-                        this.transportFailures = 0;
-                        this.dropClient(client);
-                    }
+                if (!this.isCurrentSession(key, record) ||
+                    this.client !== client ||
+                    this.isReapInduced(record))
+                    return;
+                if (isConsumerReconnectTransient(error)) {
+                    this.transportFailures = 0;
+                    this.dropClient(client);
+                    return;
+                }
+                if (!isRouteProvenAbsentError(error) &&
+                    ++this.transportFailures >= MAX_CONSECUTIVE_TRANSPORT_FAILURES) {
+                    this.transportFailures = 0;
+                    this.dropClient(client);
                 }
             };
             const requestOnRoute = async (route) => {
-                // Forward the caller's progress callback to the subc client. Current
-                // foreground calls return one final reply, so production does not rely on
-                // live progress events here.
+                this.assertRecordLive(record);
                 const reply = await client.request(route, body, { timeoutMs, onProgress });
-                // The half-open failure budget belongs to the current live session on the
-                // current client. A late success after close or client replacement must
-                // not mutate the current client's counter.
-                if (this.isCurrentSession(key, record) && this.client === client) {
-                    this.transportFailures = 0;
+                // A legacy closeSession may intentionally let an already-delivered reply
+                // settle. It must not mutate shared state or recreate a subscription.
+                if (!this.isCurrentSession(key, record)) {
+                    if (this.isReapInduced(record))
+                        throw this.rootReapedError(record);
+                    return reply;
                 }
-                // bg_events is a session resource, not a route-entry resource. A
-                // successful request on an older route should still ensure the subscription
-                // while the session remains open, and a late success after close must not
-                // resurrect one.
+                this.assertGeneration(record.canonicalRoot, record.generation, "request_completion");
+                if (this.client === client)
+                    this.transportFailures = 0;
                 this.ensureBgSubscription(identity, record);
                 return reply;
             };
-            let { route, entry } = await openRoute();
+            let routeAndEntry = await openRoute();
             try {
-                return await requestOnRoute(route);
+                return await requestOnRoute(routeAndEntry.route);
             }
-            catch (err) {
-                if (isRouteProvenAbsentError(err) &&
+            catch (error) {
+                if (this.isReapInduced(record))
+                    throw this.annotateReapError(error, record);
+                if (isRouteProvenAbsentError(error) &&
                     this.isCurrentSession(key, record) &&
                     this.client === client) {
-                    // Either the daemon says the channel does not exist, or the client
-                    // rejected the stale handle before writing. Reopen and resend once; all
-                    // other failures keep the no-auto-retry mutation-safety rule.
-                    clearRouteEntry(entry);
-                    ({ route, entry } = await openRoute());
+                    clearRouteEntry(routeAndEntry.entry);
+                    routeAndEntry = await openRoute();
                     try {
-                        return await requestOnRoute(route);
+                        return await requestOnRoute(routeAndEntry.route);
                     }
-                    catch (retryErr) {
-                        handleRequestFailure(retryErr, entry);
-                        throw retryErr;
+                    catch (retryError) {
+                        if (this.isReapInduced(record))
+                            throw this.annotateReapError(retryError, record);
+                        handleRequestFailure(retryError, routeAndEntry.entry);
+                        throw retryError;
                     }
                 }
-                handleRequestFailure(err, entry);
-                throw err;
+                handleRequestFailure(error, routeAndEntry.entry);
+                throw error;
             }
         }
+        catch (error) {
+            if (this.isReapInduced(record))
+                throw this.annotateReapError(error, record);
+            throw error;
+        }
         finally {
             record.inflight -= 1;
             this.deleteSessionIfEmpty(key, record);
         }
     }
     async ensureClient() {
-        if (this.shuttingDown) {
+        if (this.shuttingDown)
             throw new SubcCallError("terminal", "subc transport is shutting down");
-        }
         if (this.client)
             return this.client;
         if (this.connecting)
@@ -571,57 +1204,51 @@ export class SubcTransportPool {
         })
             .then((client) => {
             this.connecting = null;
-            // shutdown() may have fired while this connect was in flight. Don't
-            // install a live client after teardown — close it and fail the call
-            // (B-#5: otherwise a socket leaks open past shutdown()).
             if (this.shuttingDown) {
                 try {
                     client.close();
                 }
                 catch {
-                    // best-effort
+                    // A late connection is owned by the failed connect and is closed here.
                 }
                 throw new SubcCallError("terminal", "subc transport is shutting down");
             }
             this.client = client;
-            // Fresh client generation starts with a clean failure budget (R2-T2).
             this.transportFailures = 0;
             return client;
         })
-            .catch((err) => {
+            .catch((error) => {
             this.connecting = null;
-            throw err;
+            throw error;
         });
         return this.connecting;
     }
-    /**
-     * Resolve the route channel for `identity`, returning BOTH the channel and the
-     * `RouteEntry` token that owns it. The route-entry token is the route-cache
-     * ownership guard: stale request failures can clear only the route they used,
-     * never a successor route in the same still-open session.
-     */
     async routeHandle(client, identity, record) {
-        const key = identityKey(identity);
         const existing = record.routeEntry;
-        if (existing?.handle != null)
+        if (existing?.handle != null && existing.client === client)
             return { route: existing.handle, entry: existing };
-        if (existing?.opening)
+        if (existing?.opening && existing.client === client)
             return { route: await existing.opening, entry: existing };
-        // Singleflight: install the entry BEFORE awaiting so a concurrent caller for
-        // the same identity awaits this same open instead of minting a second channel.
-        const entry = { client, opening: null, handle: null, closed: false };
+        const entry = {
+            canonicalRoot: record.canonicalRoot,
+            generation: record.generation,
+            client,
+            opening: null,
+            handle: null,
+            closed: false,
+        };
+        this.assertRootCanAttach(record.canonicalRoot);
         const opening = client
             .routeOpen({ kind: "tool_provider", module_id: AFT_MODULE_ID }, identity, {
             consumerIdentity: this.consumerIdentity,
         })
             .then((route) => {
-            // A close/shutdown may have raced this open, or this entry may have been
-            // replaced by a transient drop/reopen. In both cases, release the freshly
-            // minted channel and clear only this entry if it still owns the cache slot.
-            if (!this.isCurrentSession(key, record) ||
+            if (!this.isCurrentSession(record.identityKey, record) ||
                 record.routeEntry !== entry ||
                 entry.closed ||
-                this.client !== client) {
+                this.client !== client ||
+                (this.lifecycleEnabled() &&
+                    !this.isCurrentLiveGeneration(record.canonicalRoot, record.generation))) {
                 safeCloseRoute(client, route);
                 if (record.routeEntry === entry)
                     record.routeEntry = null;
@@ -631,156 +1258,235 @@ export class SubcTransportPool {
             entry.opening = null;
             return route;
         })
-            .catch((err) => {
-            const current = this.isCurrentSession(key, record);
-            // Failed open: drop this entry so the next call retries cleanly, but never
-            // delete a successor entry that replaced it while this open was in flight.
+            .catch((error) => {
+            const currentEntry = this.isCurrentSession(record.identityKey, record) && record.routeEntry === entry;
             if (record.routeEntry === entry) {
                 entry.closed = true;
                 record.routeEntry = null;
             }
-            if (!current && !(err instanceof RouteTornDownError)) {
+            if (!this.isCurrentSession(record.identityKey, record) &&
+                !(error instanceof RouteTornDownError)) {
                 throw new RouteTornDownError("subc route opened after session closed");
             }
-            throw err;
+            if (currentEntry && isAbsentRootRouteError(error)) {
+                this.markRootDormant(record.canonicalRoot, error);
+            }
+            throw error;
         });
         entry.opening = opening;
         record.routeEntry = entry;
         return { route: await opening, entry };
     }
-    /**
-     * Open the dedicated bg_events subscription for `identity` once. Idempotent —
-     * a second call for the same identity is a no-op (one sub per session, the
-     * duplicate-sub guard from Oracle #2). No-op when no nudge handler is wired,
-     * during shutdown, or after the session has been closed.
-     */
     ensureBgSubscription(identity, record) {
-        if (this.shuttingDown || !this.onBgEventsNudge)
+        if (this.shuttingDown || (!this.onBgEventsNudge && !this.onBgEventsNudgeRef))
             return;
-        const key = identityKey(identity);
-        if (!this.isCurrentSession(key, record))
+        if (!this.isCurrentSession(record.identityKey, record))
+            return;
+        if (!this.rootCanAttach(record.canonicalRoot))
             return;
         if (record.bgSub)
             return;
-        const onNudge = () => this.onBgEventsNudge?.(identity.project_root, identity.session);
-        const sub = new BgSubscription(identity, () => this.ensureClient(), (client) => this.dropClient(client), this.consumerIdentity, onNudge, this.bgBackoffSleep);
+        const nudgeRef = this.nudgeRefFor(record);
+        const onNudge = () => {
+            const currentRecord = this.currentSessionForNudge(identity);
+            if (!currentRecord) {
+                this.logNudgeDelivery("drop-no-current-session", record, `nudge dropped cause=no-current-session root=${record.canonicalRoot}`);
+                return;
+            }
+            if (currentRecord !== record) {
+                this.logNudgeDelivery("forward-superseded-carrier", currentRecord, `nudge forwarding cause=superseded-carrying-record root=${currentRecord.canonicalRoot}`);
+            }
+            const currentRef = this.nudgeRefFor(currentRecord);
+            let delivered = false;
+            if (currentRef && this.onBgEventsNudgeRef) {
+                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);
+                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}`);
+        };
+        let sub = null;
+        const clearDormantSubscription = () => {
+            if (sub && record.bgSub === sub)
+                record.bgSub = null;
+        };
+        sub = new BgSubscription(identity, () => this.ensureClient(), (client) => this.dropClient(client), this.consumerIdentity, 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));
         record.bgSub = sub;
+        if (!this.rootCanAttach(record.canonicalRoot)) {
+            record.bgSub = null;
+            void sub.stop();
+        }
     }
-    /** Drop a dead client so the next call reconnects; preserves session records. */
+    /**
+     * Invalidate only routes owned by a dead client. Sessions remain indexed so a
+     * replacement client can reconnect the same identity and its bg subscription.
+     */
     dropClient(client) {
-        if (this.client === client) {
-            this.client = null;
-            for (const [key, record] of this.sessions) {
-                const entry = record.routeEntry;
-                if (entry?.client === client) {
-                    entry.closed = true;
-                    record.routeEntry = null;
-                    this.deleteSessionIfEmpty(key, record);
-                }
-            }
-            // The half-open failure counter is per-client-generation: a dropped client
-            // resets it so the NEXT client starts fresh (R2-T2). Without this, failures
-            // accrued on a client dropped via another path (e.g. a bg-subscription
-            // transient drop) would carry over and trip the backstop on a healthy new
-            // client after a single failure.
-            this.transportFailures = 0;
-            try {
-                client.close();
-            }
-            catch {
-                // best-effort; the socket is already gone
+        if (this.client !== client)
+            return;
+        this.client = null;
+        for (const record of this.sessions.values()) {
+            const entry = record.routeEntry;
+            if (entry?.client !== client)
+                continue;
+            entry.closed = true;
+            record.routeEntry = null;
+            this.deleteSessionIfEmpty(record.identityKey, record);
+        }
+        this.transportFailures = 0;
+        try {
+            client.close();
+        }
+        catch {
+            // A dead socket is already released by the peer.
+        }
+    }
+    /** Synchronous concrete-facade eviction used by the registry coordinator. */
+    evictConcreteFacade(root, generation) {
+        const facade = this.transports.get(root);
+        if (facade?.getGeneration() === generation)
+            this.transports.delete(root);
+    }
+    /**
+     * Registry-owned coordinated close. All record/index/facade mutations happen
+     * before cleanup promises are created; the registry has already tombstoned the
+     * matching generation and evicted the wrapper facade before this is called.
+     */
+    async closeProjectRoot(root, generation) {
+        if (!this.lifecycleEnabled())
+            return { tornDownSessionCount: 0, tornDownFacadeCount: 0 };
+        if (!this.isRootTombstoned(root, generation))
+            return { tornDownSessionCount: 0, tornDownFacadeCount: 0 };
+        const keys = [...(this.rootIndex.get(root) ?? new Set())];
+        const detached = [];
+        for (const key of keys) {
+            const record = this.sessions.get(key);
+            if (record?.canonicalRoot === root && record.generation === generation) {
+                const owner = this.detachSession(key, "root_reaped");
+                if (owner)
+                    detached.push(owner);
             }
         }
+        this.rootIndex.delete(root);
+        const hadFacade = this.transports.get(root)?.getGeneration() === generation;
+        this.evictConcreteFacade(root, generation);
+        const cleanup = Promise.allSettled(detached.map((owner) => this.cleanupDetached(owner))).then(() => ({
+            tornDownSessionCount: detached.length,
+            tornDownFacadeCount: hadFacade ? 1 : 0,
+        }));
+        this.pendingRootCleanups.add(cleanup);
+        void cleanup.finally(() => this.pendingRootCleanups.delete(cleanup));
+        return cleanup;
+    }
+    /** Forward explicit lifecycle close requests to the registry-owned coordinator. */
+    requestProjectRootClose(root, generation, cause = "explicit") {
+        const registry = this.lifecycleRegistry;
+        const registration = this.lifecycleRegistration;
+        if (!registry || !registration || !registration.reapingEnabled)
+            return Promise.resolve();
+        return registry.requestProjectRootClose(registration.concretePoolId, root, generation, cause);
+    }
+    /**
+     * Subc reads config locally, but plugin registration facts are process state
+     * and must accompany route requests because RouteBind has no such field.
+     */
+    setConfigureOverride(key, value) {
+        if (key !== "edit_slot_survives")
+            return;
+        if (typeof value !== "boolean") {
+            throw new Error("edit_slot_survives must be set once to a boolean");
+        }
+        if (this.editSlotSurvivesCaptured) {
+            throw new Error("edit_slot_survives is write-once and was already captured");
+        }
+        this.editSlotSurvives = value;
+        this.editSlotSurvivesCaptured = true;
+    }
+    getEditSlotSurvives() {
+        return this.editSlotSurvives;
     }
-    /** No-op over subc: config is read locally by AFT (wire tiers are ignored). */
-    setConfigureOverride(_key, _value) { }
     /** No-op over subc: the daemon owns the live module's configure lifecycle. */
     async reconfigure(_projectRoot, _overrides) { }
     /** No-op over subc: the daemon supervises the binary, not the plugin. */
     async replaceBinary(path) {
         return path;
     }
-    /** A subc pool instance is terminal after shutdown; ownership revives it outside this class. */
     isShutdown() {
         return this.shuttingDown;
     }
     async shutdown() {
+        if (this.shuttingDown)
+            return;
         this.shuttingDown = true;
-        const subs = [];
-        const entries = [];
-        for (const record of this.sessions.values()) {
-            record.closed = true;
-            const sub = record.bgSub;
-            record.bgSub = null;
-            if (sub)
-                subs.push(sub);
-            const entry = record.routeEntry;
-            record.routeEntry = null;
-            if (entry) {
-                entry.closed = true;
-                entries.push(entry);
-            }
+        this.dormantRoots.clear();
+        // Deregistration synchronously tombstones all registered roots and invokes
+        // closeProjectRoot before this method reaches its first await.
+        const registration = this.lifecycleRegistration;
+        registration?.deregister();
+        this.lifecycleRegistration = null;
+        const detached = [];
+        for (const key of [...this.sessions.keys()]) {
+            const owner = this.detachSession(key, "shutdown");
+            if (owner)
+                detached.push(owner);
         }
-        this.sessions.clear();
+        this.rootIndex.clear();
+        this.transports.clear();
         const client = this.client;
         this.client = null;
-        this.transports.clear();
-        await Promise.allSettled(subs.map((sub) => sub.stop()));
-        await Promise.allSettled(entries.map(async (entry) => {
-            if (entry.handle == null)
-                return;
-            try {
-                await entry.client.closeRouteChannel(entry.handle);
-            }
-            catch {
-                // best-effort; a dropped connection releases the route on the other side
-            }
-        }));
+        const pending = [...this.pendingRootCleanups];
+        await Promise.allSettled([...detached.map((owner) => this.cleanupDetached(owner)), ...pending]);
         if (client) {
             try {
                 client.close();
             }
             catch {
-                // best-effort
+                // Best effort; route cleanup has already been attempted.
             }
         }
     }
-    /**
-     * Tear down a single session's bg subscription (and tool route) — the
-     * per-session close hook (Oracle #5). Idempotent. Wired to OpenCode session-end
-     * / Pi equivalent in S4; until then, shutdown() covers teardown.
-     */
     async closeSession(projectRoot, session) {
         const identity = {
             project_root: canonicalizeProjectRoot(projectRoot),
             harness: this.harness,
             session: session && session.length > 0 ? session : DEFAULT_SESSION_ID,
         };
-        const key = identityKey(identity);
-        const record = this.sessions.get(key);
-        if (!record)
-            return;
-        // All lifecycle mutation happens before the first await. In-flight requests
-        // resumed after this point observe !isCurrentSession and skip route opens,
-        // bg-sub resurrection, and client failure-budget mutation.
-        record.closed = true;
-        this.sessions.delete(key);
-        const sub = record.bgSub;
-        record.bgSub = null;
-        const entry = record.routeEntry;
-        record.routeEntry = null;
-        if (entry)
-            entry.closed = true;
-        if (sub)
-            await sub.stop();
-        if (entry?.handle != null) {
-            try {
-                await entry.client.closeRouteChannel(entry.handle);
-            }
-            catch {
-                // best-effort; a dropped connection releases the route on the other side
-            }
-        }
+        const owner = this.detachSession(identityKey(identity), "session_closed");
+        if (owner)
+            await this.cleanupDetached(owner);
     }
 }
+/**
+ * Resolve a background nudge exactly once by looking up the existing active
+ * bridge without creating one or reviving a shut-down pool; hosts use this
+ * function to acknowledge nudge handling.
+ */
+export function resolveBridgeForNudge(pool, ref) {
+    const candidate = pool;
+    const bridge = candidate.getActiveBridgeForRootGeneration?.(ref) ?? null;
+    if (bridge)
+        return bridge;
+    candidate.recordBgNudgeRejection?.(ref);
+    throw new SubcRootGenerationExpiredError({
+        canonicalRoot: ref.canonicalRoot,
+        expectedGeneration: ref.generation,
+        currentGeneration: candidate.getCurrentRootGeneration?.(ref.canonicalRoot),
+        concretePoolId: ref.concretePoolId,
+        currentConcretePoolId: candidate.getConcretePoolId?.(),
+    });
+}
 //# sourceMappingURL=subc-transport.js.map