@cortexkit/aft-bridge 0.42.0 → 0.43.1

package/dist/subc-transport.js

@@ -0,0 +1,725 @@
+/**
+ * Subconscious (subc) transport — the daemon-backed alternative to the standalone
+ * NDJSON {@link BinaryBridge}. Implements the SAME {@link AftProjectTransport} /
+ * {@link AftTransportPool} interfaces the plugins consume, so the entire tool /
+ * hoisting / permission / UI surface stays transport-agnostic: only the ONE
+ * construction site (BridgePool vs SubcTransportPool) differs.
+ *
+ * Standalone model: one `aft` child process per project root, session passed
+ * per call. Subc model: ONE {@link SubcClient} per process (one authenticated
+ * daemon connection), and a route opened+cached per `(project_root, harness,
+ * session)` triple — exactly subc's {@link BindIdentity}. So the "pool" here is a
+ * route cache over a single client, not N child processes.
+ *
+ * This module is S2 of B-FINAL: the tool-call route only. The bg_events idle-wake
+ * subscription (S3) and the config gate that selects this transport (S4) build on
+ * 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 { connectionFileExists, isConsumerReconnectTransient, SubcCallError, SubcClient, } from "@cortexkit/subc-client";
+import { canonicalizeProjectRoot } from "./project-identity.js";
+import { parseStatusBarCounts } from "./status-bar.js";
+/** The subc module id AFT registers under (matches the daemon manifest). */
+const AFT_MODULE_ID = "aft";
+/**
+ * A run of consecutive NON-transient transport throws (timeout / route GOODBYE)
+ * on the SAME client is presumed a dead half-open connection (local writes
+ * succeed, no response ever arrives), so the client is dropped after this many.
+ * A single throw does not drop the client (a slow tool can legitimately time out
+ * once); the counter resets on any successful request. Tool-level errors never
+ * count — they return `success:false`, they do not throw. (Audit B-#4.)
+ */
+const MAX_CONSECUTIVE_TRANSPORT_FAILURES = 3;
+/**
+ * A bg subscription that stayed up at least this long before dropping is treated
+ * as "stable", so its reconnect backoff resets to zero. A subscription that fails
+ * faster than this is escalating-broken and must keep backing off toward the cap
+ * (otherwise a permanently-failing route resubscribes in a 100ms hot loop). (B-#2.)
+ */
+const BG_STABLE_MS = 5_000;
+/**
+ * Session fallback when a tool runtime carries no session id, mirroring the Rust
+ * `DEFAULT_SESSION_ID` (`protocol.rs`). Keeps undo/checkpoint/bash namespacing
+ * identical to the standalone path for session-less calls.
+ */
+const DEFAULT_SESSION_ID = "__default__";
+/**
+ * Commands the plugin issues via `send()` that have NO meaning over subc and must
+ * never hit the wire. `configure` is the prime case: under subc the RouteBind IS
+ * the configure (AFT reads local `.cortexkit` config and ignores wire tiers — see
+ * the unified-config model), so a `send("configure", …)` is satisfied locally
+ * with a synthetic success rather than a route call.
+ */
+const LOCALLY_SATISFIED_COMMANDS = new Set(["configure"]);
+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).
+ *
+ * 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.
+ */
+class BgSubscription {
+    identity;
+    acquireClient;
+    dropClient;
+    onNudge;
+    sleep;
+    stopped = false;
+    /** The live subscription handle, read by stop() to wake the loop's `await closed`. */
+    current = null;
+    loop;
+    constructor(identity, acquireClient, dropClient, onNudge, sleep) {
+        this.identity = identity;
+        this.acquireClient = acquireClient;
+        this.dropClient = dropClient;
+        this.onNudge = onNudge;
+        this.sleep = sleep;
+        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.
+        const sub = this.current;
+        if (sub) {
+            try {
+                sub.unsubscribe();
+            }
+            catch {
+                // best-effort; the socket may already be gone
+            }
+        }
+        await this.loop.catch(() => undefined);
+    }
+    async run() {
+        let attempt = 0;
+        while (!this.stopped) {
+            let client;
+            try {
+                client = await this.acquireClient();
+            }
+            catch {
+                await this.backoff(attempt++);
+                continue;
+            }
+            if (this.stopped)
+                return;
+            let channel;
+            try {
+                // A SECOND, dedicated routeOpen (NOT the tool route cache): the daemon
+                // mints a fresh channel per route.open, so the bg_events subscribe rides
+                // its own channel, isolated from the tool route's credit window.
+                channel = await client.routeOpen({ kind: "tool_provider", module_id: AFT_MODULE_ID }, this.identity);
+            }
+            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 (isConsumerReconnectTransient(err))
+                    this.dropClient(client);
+                await this.backoff(attempt++);
+                continue;
+            }
+            if (this.stopped) {
+                safeCloseRoute(client, channel);
+                return;
+            }
+            // Channel 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();
+            try {
+                const sub = client.subscribe(channel, { op: "bg_events" }, () => {
+                    if (!this.stopped)
+                        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).
+                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)
+                    this.onNudge();
+                await sub.closed;
+                // StreamEnd = an intentional close (our unsubscribe or module teardown).
+                // Do NOT resubscribe.
+                return;
+            }
+            catch (err) {
+                // Dropped (socket death / route GOODBYE / Error). Resubscribe — this is
+                // the independent reconnect driver that fixes idle-stranding.
+                if (this.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;
+            }
+            finally {
+                this.current = null;
+                safeCloseRoute(client, channel);
+            }
+            await this.backoff(attempt++);
+        }
+    }
+    async backoff(attempt) {
+        const ms = Math.min(100 * 2 ** Math.min(attempt, 6), 2000);
+        await this.sleep(ms);
+    }
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * 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
+ * via an unhandled rejection. Used on every best-effort teardown path.
+ */
+function safeCloseRoute(client, channel) {
+    try {
+        void client.closeRouteChannel(channel).catch(() => undefined);
+    }
+    catch {
+        // synchronous throw (e.g. closing a route on an already-closed client) — ignore
+    }
+}
+/**
+ * A route open that resolved AFTER its session was torn down (closeSession /
+ * shutdown / client swap). The caller's request can't proceed, but this is an
+ * intentional teardown — NOT a transport fault — so it must not drop the client
+ * or count toward the half-open-socket failure budget (B-#3/B-#4).
+ */
+class RouteTornDownError extends Error {
+}
+/**
+ * Re-lift the route reply into the flat {@link ToolCallResult} shape the standalone
+ * `BinaryBridge.toolCall` returns. The Rust module wraps the full flat response
+ * (`{id, success, …data, text}`) under `structuredContent` (S1 envelope), alongside
+ * the MCP `{content, isError}` a generic host reads. The first-party plugin reads
+ * `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.
+ */
+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") {
+        throw new Error("subc tool reply structuredContent lacks a boolean `success` / string `text` (protocol violation)");
+    }
+    return flat;
+}
+/**
+ * One project root's view onto the shared subc client. Holds per-root status
+ * caches (mirroring BinaryBridge) and routes every call through the pool's single
+ * client, opening+caching a route per `(root, harness, session)`.
+ */
+class SubcTransport {
+    pool;
+    projectRoot;
+    lastStatusBar;
+    cachedStatus = null;
+    constructor(pool, projectRoot) {
+        this.pool = pool;
+        this.projectRoot = projectRoot;
+    }
+    getCwd() {
+        return this.projectRoot;
+    }
+    getStatusBar() {
+        return this.lastStatusBar;
+    }
+    getCachedStatus() {
+        return this.cachedStatus;
+    }
+    cacheStatusSnapshot(snapshot) {
+        this.cachedStatus = snapshot;
+    }
+    captureStatusBar(response) {
+        const parsed = parseStatusBarCounts(response.status_bar);
+        if (parsed)
+            this.lastStatusBar = parsed;
+    }
+    identityFor(session) {
+        return {
+            project_root: this.projectRoot,
+            harness: this.pool.harness,
+            session: session && session.length > 0 ? session : DEFAULT_SESSION_ID,
+        };
+    }
+    async toolCall(sessionId, name, rawArgs = {}, options) {
+        const { preview, timeoutMs, onProgress } = this.splitOptions(options);
+        const body = { name, arguments: rawArgs };
+        if (preview === true)
+            body.preview = true;
+        const reply = await this.pool.routeRequest(this.identityFor(sessionId), body, timeoutMs, onProgress);
+        const result = reliftReply(reply);
+        this.captureStatusBar(result);
+        return result;
+    }
+    /**
+     * Lifecycle / native-command path. Over subc there is no separate "native
+     * command" channel — every command rides the tool_provider route as a
+     * `{name, arguments}` Request and the module's gate decides validity (the 21
+     * core tools plus the `bash_drain_completions` / `bash_ack_completions` plumbing
+     * allowlist). The bind session is taken from `params.session_id` so a
+     * session-scoped command (drain/ack) reaches the matching route — the module
+     * re-injects the BIND session over any body session, so the route identity is
+     * what scopes it. `configure` is satisfied locally (binding is the configure).
+     */
+    async send(command, params = {}, options) {
+        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 response = reliftReply(reply);
+        this.captureStatusBar(response);
+        return response;
+    }
+    splitOptions(options) {
+        if (!options)
+            return {};
+        const preview = options.preview;
+        const timeoutMs = options.timeoutMs;
+        const onProgress = options.onProgress;
+        return { preview, timeoutMs, onProgress };
+    }
+}
+/**
+ * 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)`.
+ */
+export class SubcTransportPool {
+    harness;
+    connectionFile;
+    handshakeTimeoutMs;
+    connectFn;
+    onBgEventsNudge;
+    bgBackoffSleep;
+    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. */
+    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).
+     */
+    transportFailures = 0;
+    /** Per-root transport facades returned by getBridge/getActiveBridgeForRoot. */
+    transports = new Map();
+    shuttingDown = false;
+    constructor(options) {
+        this.connectionFile = options.connectionFile;
+        this.harness = options.harness;
+        this.handshakeTimeoutMs = options.handshakeTimeoutMs;
+        this.connectFn = options.connect ?? ((opts) => SubcClient.connect(opts));
+        this.onBgEventsNudge = options.onBgEventsNudge;
+        this.bgBackoffSleep =
+            options.bgBackoffSleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    }
+    /**
+     * Fail-loud presence check (memory: present-but-unconnectable must never silently
+     * downgrade to standalone). Returns false only when the file is genuinely absent.
+     */
+    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);
+        }
+        return transport;
+    }
+    getActiveBridgeForRoot(projectRoot) {
+        const key = canonicalizeProjectRoot(projectRoot);
+        if (!this.client)
+            return null;
+        return this.transports.get(key) ?? null;
+    }
+    async toolCall(projectRoot, runtime, name, rawArgs = {}, options) {
+        return this.getBridge(projectRoot).toolCall(runtime.sessionID, name, rawArgs, options);
+    }
+    getOrCreateSession(key) {
+        let record = this.sessions.get(key);
+        if (!record || record.closed) {
+            record = { routeEntry: null, bgSub: null, closed: false, inflight: 0 };
+            this.sessions.set(key, record);
+        }
+        return record;
+    }
+    isCurrentSession(key, record) {
+        return this.sessions.get(key) === record && !record.closed;
+    }
+    deleteSessionIfEmpty(key, record) {
+        if (this.sessions.get(key) === record &&
+            !record.closed &&
+            record.inflight === 0 &&
+            record.routeEntry === null &&
+            record.bgSub === null) {
+            this.sessions.delete(key);
+        }
+    }
+    /**
+     * Open-or-reuse a route for `identity` and send `body` as a data-plane Request.
+     * Rd reconnect (mutation-safe by construction — NEVER auto-retries): on a
+     * transport-level {@link SubcCallError} the cached channel is discarded and the
+     * dead client cleared so the NEXT call re-establishes, but the failed call is
+     * surfaced to the agent unchanged (identical to a standalone bridge death). Only
+     * `SubcClient.request` transport failures throw here; a tool-level error comes
+     * back as a normal reply with `success:false` and is returned, not thrown.
+     */
+    async routeRequest(identity, body, timeoutMs, onProgress) {
+        const key = identityKey(identity);
+        const record = this.getOrCreateSession(key);
+        record.inflight += 1;
+        try {
+            const client = await this.ensureClient();
+            // 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");
+            }
+            let channel;
+            let entry;
+            try {
+                ({ channel, entry } = await this.routeChannel(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");
+                }
+            }
+            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) &&
+                    this.isCurrentSession(key, record) &&
+                    this.client === client) {
+                    this.dropClient(client);
+                }
+                throw err;
+            }
+            try {
+                // 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.
+                const reply = await client.request(channel, 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;
+                }
+                // 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.ensureBgSubscription(identity, record);
+                return reply;
+            }
+            catch (err) {
+                // 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.
+                if (record.routeEntry === entry) {
+                    entry.closed = true;
+                    record.routeEntry = null;
+                }
+                // 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 (++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);
+                    }
+                }
+                throw err;
+            }
+        }
+        finally {
+            record.inflight -= 1;
+            this.deleteSessionIfEmpty(key, record);
+        }
+    }
+    async ensureClient() {
+        if (this.shuttingDown) {
+            throw new SubcCallError("terminal", "subc transport is shutting down");
+        }
+        if (this.client)
+            return this.client;
+        if (this.connecting)
+            return this.connecting;
+        this.connecting = this.connectFn({
+            connectionFile: this.connectionFile,
+            handshakeTimeoutMs: this.handshakeTimeoutMs,
+        })
+            .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
+                }
+                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) => {
+            this.connecting = null;
+            throw err;
+        });
+        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 routeChannel(client, identity, record) {
+        const key = identityKey(identity);
+        const existing = record.routeEntry;
+        if (existing?.channel != null)
+            return { channel: existing.channel, entry: existing };
+        if (existing?.opening)
+            return { channel: 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, channel: null, closed: false };
+        const opening = client
+            .routeOpen({ kind: "tool_provider", module_id: AFT_MODULE_ID }, identity)
+            .then((channel) => {
+            // 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) ||
+                record.routeEntry !== entry ||
+                entry.closed ||
+                this.client !== client) {
+                safeCloseRoute(client, channel);
+                if (record.routeEntry === entry)
+                    record.routeEntry = null;
+                throw new RouteTornDownError("subc route opened after teardown");
+            }
+            entry.channel = channel;
+            entry.opening = null;
+            return channel;
+        })
+            .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.
+            if (record.routeEntry === entry) {
+                entry.closed = true;
+                record.routeEntry = null;
+            }
+            if (!current && !(err instanceof RouteTornDownError)) {
+                throw new RouteTornDownError("subc route opened after session closed");
+            }
+            throw err;
+        });
+        entry.opening = opening;
+        record.routeEntry = entry;
+        return { channel: 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)
+            return;
+        const key = identityKey(identity);
+        if (!this.isCurrentSession(key, record))
+            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), onNudge, this.bgBackoffSleep);
+        record.bgSub = sub;
+    }
+    /** Drop a dead client so the next call reconnects; preserves session records. */
+    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
+            }
+        }
+    }
+    /** No-op over subc: config is read locally by AFT (wire tiers are ignored). */
+    setConfigureOverride(_key, _value) { }
+    /** No-op over subc: the daemon supervises the binary, not the plugin. */
+    async replaceBinary(path) {
+        return path;
+    }
+    async shutdown() {
+        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.sessions.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.channel == null)
+                return;
+            try {
+                await entry.client.closeRouteChannel(entry.channel);
+            }
+            catch {
+                // best-effort; a dropped connection releases the route on the other side
+            }
+        }));
+        if (client) {
+            try {
+                client.close();
+            }
+            catch {
+                // best-effort
+            }
+        }
+    }
+    /**
+     * 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?.channel != null) {
+            try {
+                await entry.client.closeRouteChannel(entry.channel);
+            }
+            catch {
+                // best-effort; a dropped connection releases the route on the other side
+            }
+        }
+    }
+}
+//# sourceMappingURL=subc-transport.js.map