@paperclipai/server 2026.824.0 → 2026.825.0-beta.1

package/dist/services/plugin-worker-manager.js

@@ -21,11 +21,26 @@ import { fork } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import { EventEmitter } from "node:events";
 import { createInterface } from "node:readline";
-import { JSONRPC_VERSION, JSONRPC_ERROR_CODES, PLUGIN_RPC_ERROR_CODES, createRequest, createErrorResponse, parseMessage, serializeMessage, isJsonRpcResponse, isJsonRpcRequest, isJsonRpcNotification, isJsonRpcSuccessResponse, JsonRpcParseError, JsonRpcCallError, SETUP_TOKEN_PTY_OUTPUT_NOTIFICATION, SETUP_TOKEN_PTY_EXIT_NOTIFICATION, } from "@paperclipai/plugin-sdk";
+import { JSONRPC_VERSION, JSONRPC_ERROR_CODES, PLUGIN_RPC_ERROR_CODES, createRequest, createErrorResponse, parseMessage, serializeMessage, isJsonRpcResponse, isJsonRpcRequest, isJsonRpcNotification, isJsonRpcSuccessResponse, JsonRpcParseError, JsonRpcCallError, LOGIN_PTY_OUTPUT_NOTIFICATION, LOGIN_PTY_EXIT_NOTIFICATION, DUPLEX_CHANNEL_DATA_NOTIFICATION, DUPLEX_CHANNEL_EXIT_NOTIFICATION, encodeChannelBytes, decodeChannelBytes, } from "@paperclipai/plugin-sdk";
 import { getActiveStepContext } from "@paperclipai/adapter-utils/acpx-engine/startup-timing";
-import { CLAUDE_SETUP_TOKEN_COMMAND } from "@paperclipai/adapter-claude-local/server";
+import { DUPLEX_CHANNEL_AGGREGATE_BYTES_EXCEEDED, } from "@paperclipai/adapter-utils/duplex-aggregate-byte-ledger";
+import { isLoginCommandKey, validateLoginSessionHome, } from "./login-command.js";
 import { logger } from "../middleware/logger.js";
 import { traceparentFromContextToken } from "../instrumentation.js";
+/**
+ * The host raises this error when the child-stdin transport reservation for a
+ * duplex write fails against the aggregate byte ledger. The host does not write
+ * the frame. The write path throws it, `callInternal` rejects the RPC with it
+ * unwrapped, and the duplex write caller ends the route fail-closed with the
+ * {@link DUPLEX_CHANNEL_AGGREGATE_BYTES_EXCEEDED} marker. Only a duplex write
+ * meters the transport, so this error never reaches a non-duplex control message.
+ */
+class DuplexAggregateBytesExceededError extends Error {
+    constructor() {
+        super(DUPLEX_CHANNEL_AGGREGATE_BYTES_EXCEEDED);
+        this.name = "DuplexAggregateBytesExceededError";
+    }
+}
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
@@ -88,24 +103,119 @@ const MAX_WORKER_MESSAGE_CHARS = 128 * 1024 * 1024;
  */
 const MAX_EXECUTE_LOG_TOTAL_CHARS = 128 * 1024 * 1024;
 /** Maximum characters for one live login pseudo-terminal output notification. */
-const MAX_SETUP_TOKEN_PTY_CHUNK_CHARS = 1_000_000;
+const MAX_LOGIN_PTY_CHUNK_CHARS = 1_000_000;
 /** Maximum cumulative output characters for one login pseudo-terminal route. */
-const MAX_SETUP_TOKEN_PTY_TOTAL_CHARS = 8 * 1024 * 1024;
+const MAX_LOGIN_PTY_TOTAL_CHARS = 8 * 1024 * 1024;
 /** The default open timeout for one login pseudo-terminal route, in milliseconds. */
-const SETUP_TOKEN_PTY_OPEN_TIMEOUT_MS = 30_000;
+const LOGIN_PTY_OPEN_TIMEOUT_MS = 30_000;
 /** The default close timeout for one login pseudo-terminal route, in milliseconds. */
-const SETUP_TOKEN_PTY_CLOSE_TIMEOUT_MS = 10_000;
+const LOGIN_PTY_CLOSE_TIMEOUT_MS = 10_000;
 /**
- * The fixed non-secret error a disallowed login command returns. The manager
- * forwards only the compile-time `CLAUDE_SETUP_TOKEN_COMMAND` to the worker
- * pseudo-terminal. It rejects any other command before the worker call, so a
- * future caller cannot spawn an arbitrary process in the sandbox.
+ * The fixed non-secret error a disallowed login command key returns. The manager
+ * forwards only a closed login command key to the worker pseudo-terminal. It
+ * rejects a key outside the closed set before the worker call, so a caller cannot
+ * select an arbitrary command in the sandbox.
  */
-const SETUP_TOKEN_PTY_COMMAND_NOT_ALLOWED = "SETUP_TOKEN_PTY_COMMAND_NOT_ALLOWED";
+const LOGIN_PTY_COMMAND_NOT_ALLOWED = "LOGIN_PTY_COMMAND_NOT_ALLOWED";
 /** The fixed non-secret error a rejected second credential open returns. */
-const SETUP_TOKEN_PTY_ROUTE_BUSY = "SETUP_TOKEN_PTY_ROUTE_BUSY";
+const LOGIN_PTY_ROUTE_BUSY = "LOGIN_PTY_ROUTE_BUSY";
 /** The fixed non-secret error a failed open returns. */
-const SETUP_TOKEN_PTY_OPEN_FAILED = "SETUP_TOKEN_PTY_OPEN_FAILED";
+const LOGIN_PTY_OPEN_FAILED = "LOGIN_PTY_OPEN_FAILED";
+// Bounds and timeouts for the generic duplex channel route. The route mirrors the
+// login pseudo-terminal route, but it carries no command allowlist and adds seven
+// explicit bounds the pseudo-terminal route lacks. Each bound ends the route when
+// it passes the limit, so a faulty or hostile worker cannot flood the host.
+/** The default maximum characters for one duplex channel data notification. */
+const MAX_DUPLEX_CHANNEL_CHUNK_CHARS = 1_000_000;
+/**
+ * The default maximum cumulative characters the host buffers for one duplex
+ * channel route before a data listener attaches. A worker that streams data
+ * before the consumer binds cannot grow the host buffer without limit.
+ */
+const MAX_DUPLEX_CHANNEL_PRE_BIND_CHARS = 8 * 1024 * 1024;
+/**
+ * The default maximum number of data frames the host buffers for one duplex
+ * channel route before a data listener attaches.
+ */
+const MAX_DUPLEX_CHANNEL_PRE_BIND_FRAMES = 10_000;
+/**
+ * The margin the pre-bind hold ceiling keeps above the pre-bind buffered-frame
+ * bound (`maxDuplexChannelPreBindFrames`). A worker can batch data and exit
+ * frames with the open reply, so the host reads them before the route binds and
+ * before it can apply the per-frame bounds. The host holds these frames and
+ * replays them after the bind. The hold ceiling bounds that hold, so a worker
+ * that floods frames before the open reply cannot make the host hold an
+ * unbounded number of frames.
+ *
+ * The hold ceiling derives from the buffered bound, not a fixed constant. A
+ * fixed ceiling at or below a caller-configured buffered bound would drop the
+ * frame that must instead trip the buffered bound during replay, so the route
+ * would never end. One frame of margin is enough. It lets the frame that
+ * exceeds the buffered bound reach the hold, so the replay's buffered-bound
+ * check, not the hold, ends the route.
+ */
+const DUPLEX_CHANNEL_PRE_BIND_HOLD_MARGIN_FRAMES = 1;
+/**
+ * The default maximum number of in-flight host→worker requests for one duplex
+ * channel route. A worker that never replies cannot make the host hold an
+ * unbounded number of pending requests.
+ */
+const MAX_DUPLEX_CHANNEL_PENDING_REQUESTS = 256;
+/** The default maximum characters for one host→worker duplex channel write. */
+const MAX_DUPLEX_CHANNEL_WRITE_CHARS = 1_000_000;
+/**
+ * The default maximum number of protocol errors for one duplex channel route.
+ * A protocol error is one malformed or mismatched data frame. The route ends
+ * when the count passes this budget, so a flood of bad frames bounds the route.
+ */
+const MAX_DUPLEX_CHANNEL_PROTOCOL_ERRORS = 100;
+/**
+ * The default maximum cumulative bytes the host forwards for one duplex channel
+ * route over its whole life. The host counts the bytes of every inbound chunk,
+ * before and after a data listener attaches. The route ends when the count
+ * passes this cap, so an active route with a bound listener cannot stream an
+ * unbounded number of bytes.
+ */
+const MAX_DUPLEX_CHANNEL_TOTAL_DATA_BYTES = 256 * 1024 * 1024;
+/**
+ * The default maximum lifetime for one duplex channel route, in milliseconds.
+ * The host starts a timer when the route opens and ends the route when the
+ * timer expires, so a route cannot live without limit.
+ */
+const MAX_DUPLEX_CHANNEL_DURATION_MS = 60 * 60 * 1000;
+/** The default open timeout for one duplex channel route, in milliseconds. */
+const DUPLEX_CHANNEL_OPEN_TIMEOUT_MS = 30_000;
+/** The default close timeout for one duplex channel route, in milliseconds. */
+const DUPLEX_CHANNEL_CLOSE_TIMEOUT_MS = 10_000;
+/** The fixed non-secret error a rejected second duplex channel open returns. */
+const DUPLEX_CHANNEL_ROUTE_BUSY = "DUPLEX_CHANNEL_ROUTE_BUSY";
+/** The fixed non-secret error a failed duplex channel open returns. */
+const DUPLEX_CHANNEL_OPEN_FAILED = "DUPLEX_CHANNEL_OPEN_FAILED";
+// The process-scoped monotonic route-generation source. The host mints one
+// strictly increasing, non-reusable `hostRouteId` on each duplex channel open,
+// across every worker in the process. A retired generation never returns, so a
+// late frame for a closed pair never collides with a new open. The host owns the
+// value; no worker field sets it.
+let duplexHostRouteIdSequence = 0;
+/** Mint the next monotonic, non-reusable host route identifier for a duplex channel open. */
+function nextDuplexHostRouteId() {
+    duplexHostRouteIdSequence += 1;
+    return `duplex-route-${duplexHostRouteIdSequence}`;
+}
+// The separator between the two identifiers of a duplex route pair key. It is a
+// null byte, which appears in neither a host route id nor a worker session id, so
+// two distinct pairs never collapse to one key.
+const DUPLEX_PAIR_KEY_SEPARATOR = "\u0000";
+/** Build the exact-pair routing key from the host route id and the worker session id. */
+function duplexPairKey(hostRouteId, workerSessionId) {
+    return `${hostRouteId}${DUPLEX_PAIR_KEY_SEPARATOR}${workerSessionId}`;
+}
+// The maximum number of tombstoned duplex pairs one worker retains. The worker
+// keeps every tombstone until it retires, so a closed pair never returns. Before
+// the set would exceed this bound, the host retires the worker, which drops every
+// route and every tombstone at once. A tombstone overflow fails closed; the host
+// never evicts a tombstone and lets a pair return.
+const MAX_DUPLEX_ROUTE_TOMBSTONES = 4096;
 /** Minimum time between two dropped-`execute.log` debug records. The router
  * rate-limits the record so a flood of dropped chunks writes at most one line
  * per window with a running count. */
@@ -190,10 +300,34 @@ export function createPluginWorkerHandle(pluginId, options) {
     const maxExecuteLogTotalChars = options.executeLogLimits?.maxTotalCharsPerExecute ?? MAX_EXECUTE_LOG_TOTAL_CHARS;
     // Bounds and timeouts for the login pseudo-terminal route. A caller
     // (a test) can lower them to exercise the terminalize paths.
-    const maxSetupTokenPtyChunkChars = options.setupTokenPtyLimits?.maxChunkChars ?? MAX_SETUP_TOKEN_PTY_CHUNK_CHARS;
-    const maxSetupTokenPtyTotalChars = options.setupTokenPtyLimits?.maxTotalChars ?? MAX_SETUP_TOKEN_PTY_TOTAL_CHARS;
-    const setupTokenPtyOpenTimeoutMs = options.setupTokenPtyLimits?.openTimeoutMs ?? SETUP_TOKEN_PTY_OPEN_TIMEOUT_MS;
-    const setupTokenPtyCloseTimeoutMs = options.setupTokenPtyLimits?.closeTimeoutMs ?? SETUP_TOKEN_PTY_CLOSE_TIMEOUT_MS;
+    const maxLoginPtyChunkChars = options.loginPtyLimits?.maxChunkChars ?? MAX_LOGIN_PTY_CHUNK_CHARS;
+    const maxLoginPtyTotalChars = options.loginPtyLimits?.maxTotalChars ?? MAX_LOGIN_PTY_TOTAL_CHARS;
+    const loginPtyOpenTimeoutMs = options.loginPtyLimits?.openTimeoutMs ?? LOGIN_PTY_OPEN_TIMEOUT_MS;
+    const loginPtyCloseTimeoutMs = options.loginPtyLimits?.closeTimeoutMs ?? LOGIN_PTY_CLOSE_TIMEOUT_MS;
+    // Bounds and timeouts for the generic duplex channel route. A caller (a test)
+    // can lower them to exercise each bound and the terminalize paths. Each
+    // "Chars" name is a historical holdover: the channel now carries `Uint8Array`
+    // chunks, so every one of these bounds counts raw bytes (`.length` on a
+    // `Uint8Array` is its byte count), not UTF-16 code units.
+    const maxDuplexChannelChunkChars = options.duplexChannelLimits?.maxChunkChars ?? MAX_DUPLEX_CHANNEL_CHUNK_CHARS;
+    const maxDuplexChannelPreBindChars = options.duplexChannelLimits?.maxPreBindBufferedChars ??
+        MAX_DUPLEX_CHANNEL_PRE_BIND_CHARS;
+    const maxDuplexChannelPreBindFrames = options.duplexChannelLimits?.maxPreBindBufferedFrames ??
+        MAX_DUPLEX_CHANNEL_PRE_BIND_FRAMES;
+    // The pre-bind hold ceiling stays one frame above the buffered bound, so the
+    // replay, not the hold, ends the route on the buffered bound. See
+    // DUPLEX_CHANNEL_PRE_BIND_HOLD_MARGIN_FRAMES for why the margin must hold.
+    const maxDuplexChannelPreBindHoldFrames = maxDuplexChannelPreBindFrames + DUPLEX_CHANNEL_PRE_BIND_HOLD_MARGIN_FRAMES;
+    const maxDuplexChannelPendingRequests = options.duplexChannelLimits?.maxPendingRequests ??
+        MAX_DUPLEX_CHANNEL_PENDING_REQUESTS;
+    const maxDuplexChannelWriteChars = options.duplexChannelLimits?.maxWriteChars ?? MAX_DUPLEX_CHANNEL_WRITE_CHARS;
+    const maxDuplexChannelProtocolErrors = options.duplexChannelLimits?.maxProtocolErrors ??
+        MAX_DUPLEX_CHANNEL_PROTOCOL_ERRORS;
+    const maxDuplexChannelTotalDataBytes = options.duplexChannelLimits?.maxTotalDataBytes ??
+        MAX_DUPLEX_CHANNEL_TOTAL_DATA_BYTES;
+    const maxDuplexChannelDurationMs = options.duplexChannelLimits?.maxDurationMs ?? MAX_DUPLEX_CHANNEL_DURATION_MS;
+    const duplexChannelOpenTimeoutMs = options.duplexChannelLimits?.openTimeoutMs ?? DUPLEX_CHANNEL_OPEN_TIMEOUT_MS;
+    const duplexChannelCloseTimeoutMs = options.duplexChannelLimits?.closeTimeoutMs ?? DUPLEX_CHANNEL_CLOSE_TIMEOUT_MS;
     // ------------------------------------------------------------------
     // Proactive company scopes (LOOA-629)
     // ------------------------------------------------------------------
@@ -250,11 +384,42 @@ export function createPluginWorkerHandle(pluginId, options) {
     // -----------------------------------------------------------------------
     // JSON-RPC message sending
     // -----------------------------------------------------------------------
-    function sendMessage(message) {
+    function sendMessage(message, meterDuplexWrite = false) {
         if (!childProcess?.stdin?.writable) {
             throw new Error(`Worker process for plugin "${pluginId}" is not writable`);
         }
         const serialized = serializeMessage(message);
+        const ledger = duplexAggregateByteLedger;
+        if (meterDuplexWrite && ledger) {
+            // Charge the child-stdin transport buffer for a duplex write. The host writes
+            // the serialized frame to the child stdin without backpressure. When the child
+            // stops reading its stdin, the frame stays in the host stdin write buffer.
+            // Reserve the exact serialized-frame byte count. That count includes the JSON
+            // escaping and the newline framing, so the ledger covers the retained transport
+            // bytes, not only the raw payload. The RPC separately holds the raw payload
+            // under a `pending_write` token, so the two tokens cover the peak of both
+            // retentions at the same time.
+            const bytes = Buffer.byteLength(serialized);
+            const token = ledger.reserve("stdin_write", bytes);
+            if (!token) {
+                // The reservation would pass the aggregate ceiling. Fail closed before the
+                // enqueue: do not write the frame. The duplex write caller ends the route.
+                throw new DuplexAggregateBytesExceededError();
+            }
+            // Hold the token until the stream flushes the chunk. The write callback fires
+            // when the stream hands the chunk to the operating system, so the bytes then
+            // leave the host stream buffer. The RPC settle and the RPC timeout never
+            // release this token. Only the flush, the stream error, the stream close, or
+            // the worker exit releases it. Release through the outstanding-token set, so a
+            // later stream-error or worker-exit sweep never double-releases the same token.
+            pendingStdinWriteTokens.add(token);
+            childProcess.stdin.write(serialized, () => {
+                if (pendingStdinWriteTokens.delete(token)) {
+                    ledger.release(token);
+                }
+            });
+            return;
+        }
         childProcess.stdin.write(serialized);
     }
     function errorCodeForWorkerHostError(err) {
@@ -509,22 +674,37 @@ export function createPluginWorkerHandle(pluginId, options) {
             log.error({ err: err instanceof Error ? err.message : String(err) }, "execute.log delivery threw");
         }
     }
-    // At most one active credential pseudo-terminal per worker. A non-null route
-    // blocks a second open until the manager confirms the first route's close.
-    let setupTokenPtyRoute = null;
-    function settleSetupTokenPtyWait(route, value) {
+    // Shared route-binding helpers. The login pseudo-terminal route and the duplex
+    // channel route both use them, so the two routes bind and settle one way.
+    // Settle the route wait exactly once. Replace the settler with a no-op, so a
+    // later exit or terminalize never settles the wait a second time.
+    function settleRouteWait(route, value) {
         const settle = route.settleWait;
         route.settleWait = () => { };
         settle(value);
     }
+    // Read the worker session identifier from an open reply, but only when the
+    // route can still bind. Return null for a malformed reply, or for a route that
+    // already left `opening` or terminalized. A late or a duplicate reply never
+    // binds, revives, or reopens a route.
+    function readBindableWorkerSessionId(route, openResult) {
+        const workerSessionId = readNonEmptyString(isRecord(openResult) ? openResult.workerSessionId : null);
+        if (!workerSessionId || route.state !== "opening" || route.terminalized) {
+            return null;
+        }
+        return workerSessionId;
+    }
+    // At most one active credential pseudo-terminal per worker. A non-null route
+    // blocks a second open until the manager confirms the first route's close.
+    let loginPtyRoute = null;
     // Close the worker terminal by the host route identifier and verify the bound
     // acknowledgement. Return true only when the worker returns an acknowledgement
     // that carries the exact host route identifier. An absent, malformed,
     // mismatched, or timed-out acknowledgement returns false, so the caller fails
     // closed.
-    async function closeSetupTokenPtyTerminal(hostRouteId) {
+    async function closeLoginPtyTerminal(hostRouteId) {
         try {
-            const ack = await callInternal("setupTokenPtyClose", { hostRouteId }, setupTokenPtyCloseTimeoutMs);
+            const ack = await callInternal("loginPtyClose", { hostRouteId }, loginPtyCloseTimeoutMs);
             return isRecord(ack) && readNonEmptyString(ack.hostRouteId) === hostRouteId;
         }
         catch {
@@ -534,7 +714,7 @@ export function createPluginWorkerHandle(pluginId, options) {
     // Terminalize the route exactly once. Resolve the login wait, close the worker
     // terminal by the host route identifier, and free the per-worker slot only
     // after the close resolves. Retire the worker when the close is unconfirmed.
-    async function terminalizeSetupTokenPtyRoute(route) {
+    async function terminalizeLoginPtyRoute(route) {
         if (route.terminalized)
             return;
         route.terminalized = true;
@@ -543,14 +723,14 @@ export function createPluginWorkerHandle(pluginId, options) {
         route.buffered = [];
         // A terminalized route reports a null exit code, which the runner treats as a
         // failure.
-        settleSetupTokenPtyWait(route, { exitCode: null });
-        const confirmed = await closeSetupTokenPtyTerminal(route.hostRouteId);
-        if (setupTokenPtyRoute === route)
-            setupTokenPtyRoute = null;
+        settleRouteWait(route, { exitCode: null });
+        const confirmed = await closeLoginPtyTerminal(route.hostRouteId);
+        if (loginPtyRoute === route)
+            loginPtyRoute = null;
         if (!confirmed) {
             // The worker did not acknowledge the close, so the host cannot prove the
             // terminal is gone. Fail closed: retire the worker before any reuse.
-            log.error({ pluginId }, "setup-token login pseudo-terminal close not acknowledged; retiring worker");
+            log.error({ pluginId }, "login pseudo-terminal close not acknowledged; retiring worker");
             void killProcess();
         }
     }
@@ -558,8 +738,8 @@ export function createPluginWorkerHandle(pluginId, options) {
     // listener. Deliver only while the route is `open` and the notification carries
     // the exact bound worker session identifier and valid bounded bytes. Drop an
     // unknown, late, malformed, or mismatched notification. Never log the raw bytes.
-    function routeSetupTokenPtyOutput(notification) {
-        const route = setupTokenPtyRoute;
+    function routeLoginPtyOutput(notification) {
+        const route = loginPtyRoute;
         if (!route || route.state !== "open")
             return;
         const params = isRecord(notification.params) ? notification.params : {};
@@ -569,12 +749,12 @@ export function createPluginWorkerHandle(pluginId, options) {
         const chunk = params.chunk;
         if (typeof chunk !== "string" ||
             chunk.length === 0 ||
-            chunk.length > maxSetupTokenPtyChunkChars) {
+            chunk.length > maxLoginPtyChunkChars) {
             return;
         }
-        if (route.deliveredChars + chunk.length > maxSetupTokenPtyTotalChars) {
+        if (route.deliveredChars + chunk.length > maxLoginPtyTotalChars) {
             // The cumulative output passed the per-route bound. Terminalize the route.
-            void terminalizeSetupTokenPtyRoute(route);
+            void terminalizeLoginPtyRoute(route);
             return;
         }
         route.deliveredChars += chunk.length;
@@ -586,8 +766,8 @@ export function createPluginWorkerHandle(pluginId, options) {
     // Route one login pseudo-terminal exit notification to the login wait. Resolve
     // only while the route is `open` and the notification carries the exact bound
     // worker session identifier.
-    function routeSetupTokenPtyExit(notification) {
-        const route = setupTokenPtyRoute;
+    function routeLoginPtyExit(notification) {
+        const route = loginPtyRoute;
         if (!route || route.state !== "open")
             return;
         const params = isRecord(notification.params) ? notification.params : {};
@@ -595,38 +775,42 @@ export function createPluginWorkerHandle(pluginId, options) {
         if (!workerSessionId || workerSessionId !== route.workerSessionId)
             return;
         const exitCode = typeof params.exitCode === "number" ? params.exitCode : null;
-        settleSetupTokenPtyWait(route, { exitCode });
+        settleRouteWait(route, { exitCode });
     }
     // Close the one route on a worker exit. The worker is gone, so the manager
     // resolves the login wait with the fixed non-secret exit and clears the route
     // one time. The pending pseudo-terminal calls reject through `rejectAllPending`.
-    function closeSetupTokenPtyRouteOnWorkerExit() {
-        const route = setupTokenPtyRoute;
+    function closeLoginPtyRouteOnWorkerExit() {
+        const route = loginPtyRoute;
         if (!route)
             return;
-        setupTokenPtyRoute = null;
+        loginPtyRoute = null;
         route.terminalized = true;
         route.state = "closed";
         route.listener = null;
         route.buffered = [];
-        settleSetupTokenPtyWait(route, { exitCode: null });
+        settleRouteWait(route, { exitCode: null });
     }
     // Open one live login pseudo-terminal route. Reserve the route
     // before the open call, bind the worker session identifier one time on the
     // first successful open reply, and return a session the login transport drives.
     // Terminalize the route on every open failure path.
-    async function openSetupTokenPtySession(input) {
-        if (input.command !== CLAUDE_SETUP_TOKEN_COMMAND) {
-            // Allowlist the login command. Only the fixed `CLAUDE_SETUP_TOKEN_COMMAND`
-            // may run in the sandbox pseudo-terminal. Reject any other command with one
-            // fixed non-secret error before the worker call, so a caller cannot spawn
-            // an arbitrary process in the sandbox pseudo-terminal.
-            throw new Error(SETUP_TOKEN_PTY_COMMAND_NOT_ALLOWED);
-        }
-        if (setupTokenPtyRoute) {
+    async function openLoginPtySession(input) {
+        if (!isLoginCommandKey(input.loginCommandKey)) {
+            // Allowlist the login command key. Only a key in the closed set may open a
+            // sandbox pseudo-terminal. Reject a key outside the set with one fixed
+            // non-secret error before the worker call, so a caller cannot select an
+            // arbitrary command in the sandbox pseudo-terminal.
+            throw new Error(LOGIN_PTY_COMMAND_NOT_ALLOWED);
+        }
+        // Revalidate the server-controlled session home shape before the worker RPC.
+        // The binding validated it at the service boundary; this is the last host gate
+        // before the worker call, so a malformed home fails closed here too.
+        validateLoginSessionHome(input.sessionHome);
+        if (loginPtyRoute) {
             // A route for this worker is not yet closed and confirmed. Reject the
             // second open with one fixed non-secret error before it reaches the worker.
-            throw new Error(SETUP_TOKEN_PTY_ROUTE_BUSY);
+            throw new Error(LOGIN_PTY_ROUTE_BUSY);
         }
         const hostRouteId = randomUUID();
         let settleWait = () => { };
@@ -643,31 +827,32 @@ export function createPluginWorkerHandle(pluginId, options) {
             terminalized: false,
             settleWait,
         };
-        setupTokenPtyRoute = route;
+        loginPtyRoute = route;
         route.state = "opening";
         let openResult;
         try {
-            openResult = await callInternal("setupTokenPtyOpen", {
+            openResult = await callInternal("loginPtyOpen", {
                 hostRouteId,
                 driverKey: input.driverKey,
                 companyId: input.companyId,
                 environmentId: input.environmentId,
                 providerLeaseId: input.providerLeaseId,
-                command: input.command,
-            }, setupTokenPtyOpenTimeoutMs);
+                loginCommandKey: input.loginCommandKey,
+                sessionHome: input.sessionHome,
+            }, loginPtyOpenTimeoutMs);
         }
         catch (err) {
             // A send failure, an RPC rejection, or an open timeout. Terminalize the
             // route exactly once and fail closed.
-            await terminalizeSetupTokenPtyRoute(route);
-            throw err instanceof Error ? err : new Error(SETUP_TOKEN_PTY_OPEN_FAILED);
+            await terminalizeLoginPtyRoute(route);
+            throw err instanceof Error ? err : new Error(LOGIN_PTY_OPEN_FAILED);
         }
-        const workerSessionId = readNonEmptyString(isRecord(openResult) ? openResult.workerSessionId : null);
-        if (!workerSessionId || route.state !== "opening" || route.terminalized) {
+        const workerSessionId = readBindableWorkerSessionId(route, openResult);
+        if (!workerSessionId) {
             // A malformed reply, or a route that already left `opening`. A late or a
             // duplicate reply never binds, revives, or reopens a route.
-            await terminalizeSetupTokenPtyRoute(route);
-            throw new Error(SETUP_TOKEN_PTY_OPEN_FAILED);
+            await terminalizeLoginPtyRoute(route);
+            throw new Error(LOGIN_PTY_OPEN_FAILED);
         }
         // Bind the worker session identifier one time and move the route to `open`.
         route.workerSessionId = workerSessionId;
@@ -686,7 +871,7 @@ export function createPluginWorkerHandle(pluginId, options) {
                 const sid = route.workerSessionId;
                 if (route.state !== "open" || !sid)
                     return;
-                void callInternal("setupTokenPtyInput", { workerSessionId: sid, data }, setupTokenPtyOpenTimeoutMs).catch(() => { });
+                void callInternal("loginPtyInput", { workerSessionId: sid, data }, loginPtyOpenTimeoutMs).catch(() => { });
             },
             wait() {
                 return waitPromise;
@@ -695,10 +880,796 @@ export function createPluginWorkerHandle(pluginId, options) {
                 const sid = route.workerSessionId;
                 if (!sid)
                     return;
-                void callInternal("setupTokenPtyStop", { workerSessionId: sid }, setupTokenPtyOpenTimeoutMs).catch(() => { });
+                void callInternal("loginPtyStop", { workerSessionId: sid }, loginPtyOpenTimeoutMs).catch(() => { });
             },
             async close() {
-                await terminalizeSetupTokenPtyRoute(route);
+                await terminalizeLoginPtyRoute(route);
+            },
+        };
+    }
+    // The live duplex routes on this worker, keyed by the exact
+    // `{ hostRouteId, workerSessionId }` pair. The host binds one pair once, at
+    // open, and routes each data, exit, and close frame only to the route that owns
+    // its exact pair. The host never routes by the worker session id alone.
+    const liveDuplexRoutes = new Map();
+    // The reserved-or-opening routes, keyed by the host route id. A route lives here
+    // from the open call until the worker session id binds. The host then moves it
+    // to `liveDuplexRoutes` under the exact pair key.
+    const openingDuplexRoutes = new Map();
+    // The tombstoned pairs on this worker, keyed by the exact pair key. The host
+    // installs a tombstone atomically when it removes a live binding, and retains it
+    // until the worker retires. A late frame for a tombstoned pair reaches no
+    // listener. A closed pair never returns.
+    const duplexPairTombstones = new Set();
+    // The process-scoped aggregate route-slot controller. The manager injects it, so
+    // the ceiling counts every duplex route across every worker in the process, not
+    // one agent's setting. When it is absent, the worker admits every open, so the
+    // handle runs unbounded in isolation (a unit test constructs it this way).
+    const duplexRouteSlots = options.duplexRouteSlots ?? null;
+    // The routes that currently hold one aggregate slot. The host releases a slot one
+    // time per route, so a double terminalize never releases two slots.
+    const duplexRouteSlotHolders = new Set();
+    // The process-owned aggregate byte ledger. The manager injects it, so one gauge
+    // bounds the aggregate retained bytes across every route in the process. When it
+    // is absent, the worker retains duplex bytes unbounded (a unit test constructs it
+    // this way).
+    const duplexAggregateByteLedger = options.duplexAggregateByteLedger ?? null;
+    // The outstanding child-stdin transport tokens for duplex writes. Each token
+    // covers one serialized frame the host stdin write buffer still retains. The
+    // write callback releases a token on the flush; a stream error, a stream close,
+    // or a worker exit releases every remaining token, because each of those
+    // discards the stdin write buffer. The set is the release guard, so a token
+    // releases one time across the two paths.
+    const pendingStdinWriteTokens = new Set();
+    // Release every outstanding child-stdin transport token. A stream error, a
+    // stream close, or a worker exit calls this, because each discards the stdin
+    // write buffer. The `delete` guard drops each token one time, so a later flush
+    // callback or a second sweep releases nothing again.
+    function releaseAllPendingStdinWriteTokens() {
+        if (!duplexAggregateByteLedger)
+            return;
+        for (const token of pendingStdinWriteTokens) {
+            duplexAggregateByteLedger.release(token);
+        }
+        pendingStdinWriteTokens.clear();
+    }
+    // The terminalized routes that still hold buffered bytes for a late listener
+    // drain. A terminalized route leaves the opening and live maps, so this registry
+    // keeps the worker-exit sweep able to release its still-charged buffered tokens.
+    const terminalDuplexRoutes = new Set();
+    // Reserve `bytes` for one route retention against the aggregate ledger. Return
+    // the held token, or `null` when the reservation would pass the ceiling. When no
+    // ledger is present, return `"no-ledger"`, so the caller admits the retention
+    // with no token. The helper adds a real token to `route.retainedTokens`.
+    function reserveRouteBytes(route, owner, bytes) {
+        if (!duplexAggregateByteLedger)
+            return "no-ledger";
+        const token = duplexAggregateByteLedger.reserve(owner, bytes);
+        if (!token)
+            return null;
+        route.retainedTokens.add(token);
+        return token;
+    }
+    // Transfer a held route token to a new owner label. The token identity and the
+    // reserved bytes stay the same, so no admission gap opens between two
+    // representations of the same retained bytes.
+    function transferRouteToken(token, owner) {
+        if (!token)
+            return;
+        duplexAggregateByteLedger?.transfer(token, owner);
+    }
+    // Release one held route token and drop it from the route registry, in one
+    // synchronous step. A `null` token (no ledger) releases nothing.
+    function releaseRouteToken(route, token) {
+        if (!token)
+            return;
+        route.retainedTokens.delete(token);
+        duplexAggregateByteLedger?.release(token);
+    }
+    // Release every token a route still holds and clear its retained representations,
+    // exactly once. A later call finds an empty registry and releases nothing, so the
+    // helper is idempotent. Every terminal-discard, open-failure, bind-replay
+    // failure, close-acknowledgement failure, worker-exit, and shutdown path calls
+    // it. Terminal map deletion is never treated as proof that retained bytes are
+    // gone; this registry is authoritative for byte cleanup.
+    function discardRouteRetained(route) {
+        if (duplexAggregateByteLedger) {
+            for (const token of route.retainedTokens) {
+                duplexAggregateByteLedger.release(token);
+            }
+        }
+        route.retainedTokens.clear();
+        route.preBind = [];
+        route.preBindExit = null;
+        route.buffered = [];
+        route.bufferedChars = 0;
+        terminalDuplexRoutes.delete(route);
+    }
+    // Try to reserve one aggregate route slot for a route. Return true when the
+    // route holds a slot after the call. When no controller is present, the route
+    // always holds a slot.
+    function acquireDuplexRouteSlot(route) {
+        if (!duplexRouteSlots)
+            return true;
+        if (!duplexRouteSlots.tryAcquire())
+            return false;
+        duplexRouteSlotHolders.add(route);
+        return true;
+    }
+    // Release the aggregate route slot a route holds, one time. A route that never
+    // held a slot releases nothing.
+    function releaseDuplexRouteSlot(route) {
+        if (!duplexRouteSlotHolders.delete(route))
+            return;
+        duplexRouteSlots?.release();
+    }
+    // Retire the worker at once. The host kills the process, so every live route,
+    // every reserved route, and every tombstone drops together. The host uses this
+    // as the fail-closed response to an ownership violation and to a tombstone-set
+    // overflow. The host never logs the raw frame content on a violation.
+    function retireDuplexWorkerOnViolation(reason) {
+        log.error({ pluginId }, `duplex channel ownership violation (${reason}); retiring worker`);
+        void killProcess();
+    }
+    // Install a tombstone for a bound pair atomically with the removal of its live
+    // binding. This runs in one synchronous step, before any slot release or reuse,
+    // so a late frame for the pair reaches no listener. Before the set would exceed
+    // its hard bound, retire the worker, which drops every route and every tombstone
+    // at once. A tombstone overflow fails closed; the host never evicts a tombstone
+    // and lets a pair return.
+    function tombstoneBoundDuplexPair(route) {
+        if (route.workerSessionId === null)
+            return;
+        const pairKey = duplexPairKey(route.hostRouteId, route.workerSessionId);
+        liveDuplexRoutes.delete(pairKey);
+        if (!duplexPairTombstones.has(pairKey)) {
+            if (duplexPairTombstones.size >= MAX_DUPLEX_ROUTE_TOMBSTONES) {
+                // The set is full. Do not evict a tombstone. Retire the worker, which
+                // drops every route and every tombstone together, so no closed pair ever
+                // returns.
+                retireDuplexWorkerOnViolation("tombstone set overflow");
+                return;
+            }
+            duplexPairTombstones.add(pairKey);
+        }
+    }
+    // Close the worker channel by the host route identifier and verify the bound
+    // acknowledgement. Return true only when the worker returns an acknowledgement
+    // for the exact pair. Before a session binds, the acknowledgement carries the
+    // host route identifier only, so a lost open reply still permits a route-only
+    // close. After a session binds, the acknowledgement must echo both the host
+    // route identifier and the bound worker session identifier. An absent,
+    // malformed, mismatched, or timed-out acknowledgement returns false, so the
+    // caller fails closed.
+    async function closeDuplexChannelTerminal(hostRouteId, boundWorkerSessionId) {
+        try {
+            const ack = await callInternal("duplexChannelClose", { hostRouteId }, duplexChannelCloseTimeoutMs);
+            if (!isRecord(ack) || readNonEmptyString(ack.hostRouteId) !== hostRouteId) {
+                return false;
+            }
+            if (boundWorkerSessionId !== null) {
+                // A bound close: the acknowledgement must echo the exact worker session
+                // identifier. A missing or a mismatched identifier is invalid.
+                return readNonEmptyString(ack.workerSessionId) === boundWorkerSessionId;
+            }
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    // Terminalize the route exactly once. Resolve the wait, close the worker
+    // channel by the host route identifier, and free the per-worker slot only
+    // after the close resolves. Retire the worker when the close is unconfirmed.
+    // Clear the route lifetime timer one time. Every terminal path and the
+    // worker-exit path calls this, so a timer never fires after the route ends.
+    function clearDuplexChannelLifetimeTimer(route) {
+        if (route.lifetimeTimer) {
+            clearTimeout(route.lifetimeTimer);
+            route.lifetimeTimer = null;
+        }
+    }
+    async function terminalizeDuplexChannelRoute(route) {
+        if (route.terminalized)
+            return;
+        route.terminalized = true;
+        route.state = "closed";
+        route.listener = null;
+        // Stop admission first. Then move the byte cleanup. Keep the buffered chunks the
+        // host accepted before the route ended, so a listener that attaches after the
+        // end still drains them. A frame can end the route during the pre-bind replay,
+        // before a listener attaches, and the chunks the host accepted before that frame
+        // are valid data the listener must still receive. The buffered bytes stay
+        // bounded by the pre-bind buffered bound, and `onData` clears and releases them
+        // once it drains them.
+        //
+        // The buffered records keep their tokens; move each token to the terminal owner
+        // label and register the route in the terminal registry, so the worker-exit
+        // sweep can release the still-charged bytes later. Do not release a buffered
+        // token at map deletion; terminal map deletion is never proof the bytes are
+        // gone. Release every other token the route still holds (the pre-bind events,
+        // the held exit, and any stranded token), because they never reach a listener.
+        const bufferedTokens = new Set();
+        for (const record of route.buffered) {
+            if (record.token) {
+                bufferedTokens.add(record.token);
+                transferRouteToken(record.token, "terminal_buffered");
+            }
+        }
+        for (const token of [...route.retainedTokens]) {
+            if (!bufferedTokens.has(token)) {
+                route.retainedTokens.delete(token);
+                duplexAggregateByteLedger?.release(token);
+            }
+        }
+        route.preBind = [];
+        route.preBindExit = null;
+        if (route.buffered.length > 0) {
+            terminalDuplexRoutes.add(route);
+        }
+        clearDuplexChannelLifetimeTimer(route);
+        // Remove the live binding and install the tombstone in one synchronous step,
+        // before the worker close and before any reuse. A reserved route that never
+        // bound leaves the opening map only; it has no pair to tombstone, and the
+        // monotonic host route id never returns.
+        openingDuplexRoutes.delete(route.hostRouteId);
+        tombstoneBoundDuplexPair(route);
+        releaseDuplexRouteSlot(route);
+        // A terminalized route reports a null exit code, which the caller treats as a
+        // failure.
+        settleRouteWait(route, { exitCode: null });
+        const confirmed = await closeDuplexChannelTerminal(route.hostRouteId, route.workerSessionId);
+        if (!confirmed) {
+            // The worker did not acknowledge the close, so the host cannot prove the
+            // channel is gone. Fail closed: retire the worker before any reuse.
+            log.error({ pluginId }, "duplex channel close not acknowledged; retiring worker");
+            void killProcess();
+        }
+    }
+    // Count one protocol error for the route. End the route when the count passes
+    // the per-route budget, so a flood of malformed or mismatched frames bounds the
+    // route.
+    function recordDuplexChannelProtocolError(route) {
+        route.protocolErrors += 1;
+        if (route.protocolErrors > maxDuplexChannelProtocolErrors) {
+            void terminalizeDuplexChannelRoute(route);
+        }
+    }
+    // Deliver one duplex channel chunk to the bound listener in isolation. A
+    // listener that throws must not escape the worker stdout notification handler
+    // or the buffered replay, so a throw here breaks neither the notification
+    // dispatch loop nor the pre-bind drain. The manager catches the error and logs
+    // it without the raw bytes. This mirrors the `execute.log` delivery isolation.
+    function deliverDuplexChannelChunk(listener, chunk) {
+        try {
+            listener(chunk);
+        }
+        catch (err) {
+            log.error({ err: err instanceof Error ? err.message : String(err) }, "duplex channel data delivery threw");
+        }
+    }
+    // Route one duplex channel data notification to the per-session listener.
+    // Deliver only while the route is `open` and the notification carries the exact
+    // bound worker session identifier and a valid chunk. Count a mismatched or
+    // malformed frame as a protocol error. End the route at once when one chunk is
+    // larger than the per-chunk limit or when the cumulative bytes pass the total
+    // cap. Buffer a valid frame under the pre-bind bounds when no listener has
+    // attached yet. Never log the raw bytes.
+    // Resolve one inbound duplex frame to its owning route by the exact pair. Return
+    // the live route on an exact live-pair match. Return `"tombstoned"` for a late
+    // frame whose exact pair the host already closed; that frame reaches no listener
+    // and changes no state. Return `"violation"` for any unknown, foreign,
+    // duplicate, ambiguous, or malformed pair; the caller fails closed and retires
+    // the worker. The lookup never routes by the worker session id alone.
+    function resolveDuplexRouteByPair(hostRouteId, workerSessionId) {
+        if (!hostRouteId || !workerSessionId)
+            return "violation";
+        const pairKey = duplexPairKey(hostRouteId, workerSessionId);
+        const live = liveDuplexRoutes.get(pairKey);
+        if (live && live.state === "open")
+            return live;
+        if (duplexPairTombstones.has(pairKey))
+            return "tombstoned";
+        // A frame whose host route id names a route that is still opening arrived
+        // before the bind. It is the host's own reserved route, not a foreign frame.
+        // The caller defers it, so the bind replays it through the exact-pair routing.
+        if (openingDuplexRoutes.has(hostRouteId))
+            return "opening";
+        return "violation";
+    }
+    // Route one duplex channel data frame. On a live route with a listener, deliver
+    // the chunk transiently. On a live route with no listener, buffer the chunk and
+    // charge its raw bytes against the aggregate ledger. The `carried` argument marks
+    // a bind-replay frame: it carries the pre-bind token the buffered record must
+    // reuse, so the replay transfers the token to the buffered representation with no
+    // decrement and no re-reserve. A live frame passes no `carried`, so it reserves a
+    // fresh buffered token. A `carried.token` of `null` means no ledger is present.
+    function routeDuplexChannelData(notification, carried) {
+        const params = isRecord(notification.params) ? notification.params : {};
+        const hostRouteId = readNonEmptyString(params.hostRouteId);
+        const workerSessionId = readNonEmptyString(params.workerSessionId);
+        const resolved = resolveDuplexRouteByPair(hostRouteId, workerSessionId);
+        if (resolved === "tombstoned") {
+            // A late frame for a closed pair. It reaches no listener and changes no
+            // state. A bind replay never lands here, because the replayed route is live;
+            // a carried token stays on its route and the terminal cleanup releases it.
+            // Never log the raw frame content.
+            return;
+        }
+        if (resolved === "violation") {
+            // An unknown, foreign, duplicate, ambiguous, or malformed pair. Fail closed:
+            // retire the worker. Never log the raw frame content.
+            retireDuplexWorkerOnViolation("data frame pair");
+            return;
+        }
+        if (resolved === "opening") {
+            // The frame arrived before the bind. A replay never lands here, because the
+            // route is live during replay. Hold the live frame; the bind replays it.
+            bufferPreBindDuplexFrame(hostRouteId, notification);
+            return;
+        }
+        const route = resolved;
+        // The wire carries the chunk as a base64 string (JSON has no binary type; see
+        // `ChannelBytesWireValue` in protocol.ts). Decode it back to raw bytes before
+        // any bound check, so every bound below counts real bytes, not base64 text.
+        // A bind replay (`replayPreBindDuplexFrames`) reuses this function with a
+        // held event whose chunk the host already decoded once; it carries the
+        // already-decoded `Uint8Array` straight through with no second decode.
+        const rawChunk = params.chunk;
+        const chunk = rawChunk instanceof Uint8Array ? rawChunk : decodeChannelBytes(rawChunk);
+        if (chunk === null || chunk.byteLength === 0) {
+            // The exact pair matches, but the chunk is malformed or empty. Count one
+            // per-route protocol error. Release a carried replay token first.
+            releaseRouteToken(route, carried?.token ?? null);
+            recordDuplexChannelProtocolError(route);
+            return;
+        }
+        if (chunk.byteLength > maxDuplexChannelChunkChars) {
+            // One inbound chunk is larger than the per-chunk limit. End the route at
+            // once. Do not count the chunk as a protocol error.
+            releaseRouteToken(route, carried?.token ?? null);
+            void terminalizeDuplexChannelRoute(route);
+            return;
+        }
+        // Enforce the cumulative total-byte cap before and after a listener attaches.
+        // End the route when the cap is exceeded, so a bound listener cannot receive
+        // data past the cap.
+        const chunkBytes = chunk.byteLength;
+        if (route.totalDataBytes + chunkBytes > maxDuplexChannelTotalDataBytes) {
+            releaseRouteToken(route, carried?.token ?? null);
+            void terminalizeDuplexChannelRoute(route);
+            return;
+        }
+        route.totalDataBytes += chunkBytes;
+        if (route.listener) {
+            // A listener is attached. Deliver the chunk transiently and release a carried
+            // replay token after the synchronous delivery boundary.
+            deliverDuplexChannelChunk(route.listener, chunk);
+            releaseRouteToken(route, carried?.token ?? null);
+            return;
+        }
+        // No listener attached yet. Buffer the frame under the pre-bind bounds. End
+        // the route when the cumulative bytes or the frame count passes the bound.
+        if (route.buffered.length + 1 > maxDuplexChannelPreBindFrames ||
+            route.bufferedChars + chunk.length > maxDuplexChannelPreBindChars) {
+            releaseRouteToken(route, carried?.token ?? null);
+            void terminalizeDuplexChannelRoute(route);
+            return;
+        }
+        let token;
+        if (carried) {
+            // The bind replay transfers the pre-bind token to the buffered
+            // representation. No decrement and no re-reserve, so no admission gap opens.
+            token = carried.token;
+            transferRouteToken(token, "buffered_chunk");
+        }
+        else {
+            // A live frame reserves a fresh buffered token for its exact raw bytes.
+            const reserved = reserveRouteBytes(route, "buffered_chunk", chunkBytes);
+            if (reserved === null) {
+                // The aggregate ceiling rejected the reservation. Retain nothing and fail
+                // closed with the fixed marker.
+                void terminalizeDuplexChannelRoute(route);
+                return;
+            }
+            token = reserved === "no-ledger" ? null : reserved;
+        }
+        route.buffered.push({ chunk, token });
+        route.bufferedChars += chunk.length;
+    }
+    // Route one duplex channel exit notification to the wait. Resolve only while
+    // the route is `open` and the notification carries the exact bound worker
+    // session identifier.
+    function routeDuplexChannelExit(notification) {
+        const params = isRecord(notification.params) ? notification.params : {};
+        const hostRouteId = readNonEmptyString(params.hostRouteId);
+        const workerSessionId = readNonEmptyString(params.workerSessionId);
+        const resolved = resolveDuplexRouteByPair(hostRouteId, workerSessionId);
+        if (resolved === "tombstoned") {
+            // A late exit for a closed pair. It reaches no wait and changes no state.
+            return;
+        }
+        if (resolved === "violation") {
+            // An unknown, foreign, duplicate, ambiguous, or malformed pair. Fail closed:
+            // retire the worker.
+            retireDuplexWorkerOnViolation("exit frame pair");
+            return;
+        }
+        if (resolved === "opening") {
+            // The exit arrived before the bind. Hold it; the bind replays it through the
+            // exact-pair routing.
+            bufferPreBindDuplexFrame(hostRouteId, notification);
+            return;
+        }
+        const exitCode = typeof params.exitCode === "number" ? params.exitCode : null;
+        // A reason-less transport close carries `transportClosed`; a real process exit
+        // does not. Carry the discriminator to the wait only when it is a transport
+        // close, so a real exit keeps the plain `{ exitCode }` result and the broker
+        // still keeps the two apart in the loss taxonomy.
+        if (params.transportClosed === true) {
+            settleRouteWait(resolved, { exitCode, transportClosed: true });
+            return;
+        }
+        settleRouteWait(resolved, { exitCode });
+    }
+    // Hold one frame that arrived before its route bound, in order. The bind replays
+    // the held frames through the exact-pair routing. An exit frame never consumes a
+    // data hold slot; the host holds it in the single `preBindExit` slot instead, so
+    // a worker that batches an exit among enough data frames to fill the hold cannot
+    // crowd out a data frame. The data hold ceiling stays one frame above the
+    // buffered bound, so the replay's buffered-bound check, not the hold, ends the
+    // route. The host counts one protocol error for each data frame past the ceiling,
+    // so an early flood bounds the hold instead of growing without limit.
+    function bufferPreBindDuplexFrame(hostRouteId, notification) {
+        if (!hostRouteId)
+            return;
+        const route = openingDuplexRoutes.get(hostRouteId);
+        if (!route)
+            return;
+        const params = isRecord(notification.params) ? notification.params : {};
+        const workerSessionId = readNonEmptyString(params.workerSessionId);
+        if (!workerSessionId) {
+            // A malformed pair. Count one per-route protocol error and hold nothing.
+            recordDuplexChannelProtocolError(route);
+            return;
+        }
+        if (notification.method === DUPLEX_CHANNEL_EXIT_NOTIFICATION) {
+            // Normalize the exit to the narrow duplex-event schema. An exit retains only
+            // a bounded scalar, so reserve a zero-byte token that carries the record
+            // through the one cleanup path. Release any earlier held exit token first, so
+            // a replaced exit never leaks its reservation.
+            const exitCode = typeof params.exitCode === "number" ? params.exitCode : null;
+            if (route.preBindExit)
+                releaseRouteToken(route, route.preBindExit.token);
+            const reserved = reserveRouteBytes(route, "pre_bind_event", 0);
+            if (reserved === null) {
+                // The aggregate ceiling rejected the reservation. Fail closed.
+                void terminalizeDuplexChannelRoute(route);
+                return;
+            }
+            route.preBindExit = {
+                workerSessionId,
+                exitCode,
+                token: reserved === "no-ledger" ? null : reserved,
+            };
+            return;
+        }
+        // A data event. Validate and normalize it to the narrow duplex-event schema
+        // before any retention. The wire carries the chunk as base64; decode it back
+        // to raw bytes before any bound check or retention.
+        const chunk = decodeChannelBytes(params.chunk);
+        if (chunk === null || chunk.byteLength === 0) {
+            recordDuplexChannelProtocolError(route);
+            return;
+        }
+        if (route.preBind.length >= maxDuplexChannelPreBindHoldFrames) {
+            recordDuplexChannelProtocolError(route);
+            return;
+        }
+        // Reserve the exact retained raw byte count before the host holds the event.
+        const reserved = reserveRouteBytes(route, "pre_bind_event", chunk.byteLength);
+        if (reserved === null) {
+            // The aggregate ceiling rejected the reservation. The caller retains nothing
+            // and the route fails closed with the fixed marker.
+            log.warn({ pluginId, reason: DUPLEX_CHANNEL_AGGREGATE_BYTES_EXCEEDED }, "duplex pre-bind hold rejected");
+            void terminalizeDuplexChannelRoute(route);
+            return;
+        }
+        route.preBind.push({
+            workerSessionId,
+            chunk,
+            token: reserved === "no-ledger" ? null : reserved,
+        });
+    }
+    // Replay the frames a route held before it bound. The route is live now, so the
+    // exact-pair routing delivers each held frame or fails closed on a mismatch.
+    // Replay the held data frames first, in order, then the held exit last, so the
+    // data delivers before the exit resolves the wait, which matches a real worker's
+    // order. A frame that ends the route terminalizes it, and every later frame in
+    // the replay is a no-op, because the routing functions drop a frame for a route
+    // that is not `open`.
+    function replayPreBindDuplexFrames(route) {
+        const held = route.preBind;
+        route.preBind = [];
+        for (const event of held) {
+            if (route.terminalized) {
+                // The route ended mid-replay. Release the remaining held tokens, so the
+                // unreplayed events retain nothing.
+                releaseRouteToken(route, event.token);
+                continue;
+            }
+            // Reconstruct a transient data notification for the exact-pair routing. The
+            // host holds only the bounded event, so it builds this notification for the
+            // routing step and discards it at once. The carried token moves to the
+            // buffered representation without a decrement or a re-reserve.
+            routeDuplexChannelData({
+                jsonrpc: "2.0",
+                method: DUPLEX_CHANNEL_DATA_NOTIFICATION,
+                params: {
+                    hostRouteId: route.hostRouteId,
+                    workerSessionId: event.workerSessionId,
+                    chunk: event.chunk,
+                },
+            }, { token: event.token });
+        }
+        const heldExit = route.preBindExit;
+        route.preBindExit = null;
+        if (heldExit) {
+            // The exit retains only a bounded scalar. Release its placeholder token, then
+            // resolve the wait through the exact-pair routing when the route still lives.
+            releaseRouteToken(route, heldExit.token);
+            if (!route.terminalized) {
+                routeDuplexChannelExit({
+                    jsonrpc: "2.0",
+                    method: DUPLEX_CHANNEL_EXIT_NOTIFICATION,
+                    params: {
+                        hostRouteId: route.hostRouteId,
+                        workerSessionId: heldExit.workerSessionId,
+                        exitCode: heldExit.exitCode,
+                    },
+                });
+            }
+        }
+    }
+    // Close every route on a worker exit. The worker is gone, so the manager
+    // resolves each wait with the fixed non-secret exit, releases each aggregate
+    // slot, and clears the live, opening, and tombstone state. A worker exit is a
+    // worker retirement, so the host drops every tombstone; the monotonic host route
+    // id never returns, so no closed pair can revive on a restart. The pending
+    // channel calls reject through `rejectAllPending`.
+    function closeDuplexChannelRouteOnWorkerExit() {
+        // Enumerate the opening index, the live index, and the terminal registry. A
+        // terminalized route left the opening and live maps but may still hold buffered
+        // bytes for a late listener; the worker is gone, so the host releases them now.
+        const routes = [
+            ...openingDuplexRoutes.values(),
+            ...liveDuplexRoutes.values(),
+            ...terminalDuplexRoutes,
+        ];
+        openingDuplexRoutes.clear();
+        liveDuplexRoutes.clear();
+        duplexPairTombstones.clear();
+        for (const route of routes) {
+            if (!route.terminalized) {
+                route.terminalized = true;
+                route.state = "closed";
+                route.listener = null;
+                route.bufferedChars = 0;
+                clearDuplexChannelLifetimeTimer(route);
+                releaseDuplexRouteSlot(route);
+                settleRouteWait(route, { exitCode: null });
+            }
+            // Release every token the route still holds and clear its retained
+            // representations, exactly once. A route already drained by a late listener
+            // holds no token, so this is harmless and leaves the ledger at zero.
+            discardRouteRetained(route);
+        }
+        // Clear the terminal registry. Every route in it was just discarded above.
+        terminalDuplexRoutes.clear();
+    }
+    // Open one live generic duplex channel route. Reserve the route before the open
+    // call, bind the worker session identifier one time on the first successful
+    // open reply, and return a session a caller drives. Terminalize the route on
+    // every open failure path.
+    async function openDuplexChannel(input) {
+        const hostRouteId = nextDuplexHostRouteId();
+        let settleWait = () => { };
+        const waitPromise = new Promise((resolve) => {
+            settleWait = resolve;
+        });
+        const route = {
+            hostRouteId,
+            state: "reserved",
+            workerSessionId: null,
+            listener: null,
+            buffered: [],
+            bufferedChars: 0,
+            pendingRequests: 0,
+            protocolErrors: 0,
+            totalDataBytes: 0,
+            lifetimeTimer: null,
+            terminalized: false,
+            settleWait,
+            preBind: [],
+            preBindExit: null,
+            retainedTokens: new Set(),
+        };
+        // Reserve one aggregate route slot before any work. When the process-scoped
+        // ceiling is full, reject with the fixed route-busy error and open nothing, so
+        // an active channel never downgrades and the ceiling never overcommits.
+        if (!acquireDuplexRouteSlot(route)) {
+            throw new Error(DUPLEX_CHANNEL_ROUTE_BUSY);
+        }
+        openingDuplexRoutes.set(hostRouteId, route);
+        route.state = "opening";
+        let openResult;
+        try {
+            openResult = await callInternal("duplexChannelOpen", {
+                hostRouteId,
+                driverKey: input.driverKey,
+                companyId: input.companyId,
+                environmentId: input.environmentId,
+                providerLeaseId: input.providerLeaseId,
+                command: input.command,
+            }, duplexChannelOpenTimeoutMs);
+        }
+        catch (err) {
+            // A send failure, an RPC rejection, or an open timeout. Terminalize the
+            // route exactly once and fail closed.
+            await terminalizeDuplexChannelRoute(route);
+            throw err instanceof Error ? err : new Error(DUPLEX_CHANNEL_OPEN_FAILED);
+        }
+        const workerSessionId = readBindableWorkerSessionId(route, openResult);
+        // Verify the worker echoed the exact host route id the open request carried.
+        // A reply with a missing or a mismatched host route id never binds, so the
+        // host binds only a reply that proves the worker holds the exact pair.
+        const echoedHostRouteId = isRecord(openResult)
+            ? readNonEmptyString(openResult.hostRouteId)
+            : null;
+        if (!workerSessionId || echoedHostRouteId !== hostRouteId) {
+            // A malformed reply, a mismatched host route id, or a route that already
+            // left `opening`. A late or a duplicate reply never binds, revives, or
+            // reopens a route.
+            await terminalizeDuplexChannelRoute(route);
+            throw new Error(DUPLEX_CHANNEL_OPEN_FAILED);
+        }
+        const pairKey = duplexPairKey(hostRouteId, workerSessionId);
+        if (liveDuplexRoutes.has(pairKey) || duplexPairTombstones.has(pairKey)) {
+            // The worker returned a pair that is already live or already tombstoned. Fail
+            // closed: terminalize this route and retire the worker before any reuse.
+            await terminalizeDuplexChannelRoute(route);
+            retireDuplexWorkerOnViolation("duplicate bound pair");
+            throw new Error(DUPLEX_CHANNEL_OPEN_FAILED);
+        }
+        // Bind the worker session identifier one time and move the route from the
+        // opening map to the live map under the exact pair key.
+        route.workerSessionId = workerSessionId;
+        route.state = "open";
+        openingDuplexRoutes.delete(hostRouteId);
+        liveDuplexRoutes.set(pairKey, route);
+        // Start the route lifetime timer now the route is open. The route ends when
+        // the timer expires. Every terminal path and the worker-exit path clears the
+        // timer. Unreference the timer so it never blocks the host process shutdown.
+        route.lifetimeTimer = setTimeout(() => {
+            void terminalizeDuplexChannelRoute(route);
+        }, maxDuplexChannelDurationMs);
+        route.lifetimeTimer.unref?.();
+        // Replay any frame that arrived before the bind. The route is live now, so the
+        // exact-pair routing delivers each held frame or fails closed on a mismatch.
+        replayPreBindDuplexFrames(route);
+        // Send one host→worker request under the pending-request bound. End the route
+        // when too many requests are in-flight, so a worker that never replies cannot
+        // make the host hold an unbounded number of pending requests.
+        const sendBoundedRequest = (method, params, 
+        // The exact raw byte count of a `duplexChannelWrite` payload, before base64
+        // encoding. The caller supplies it: `params.data` on the wire is the base64
+        // form (`ChannelBytesWireValue`), so its string length no longer equals the
+        // real payload bytes. A stop request carries no payload and omits this.
+        writeByteCount) => {
+            if (route.state !== "open")
+                return;
+            if (route.pendingRequests >= maxDuplexChannelPendingRequests) {
+                void terminalizeDuplexChannelRoute(route);
+                return;
+            }
+            // Reserve the exact raw byte count of a host→worker write against the
+            // aggregate ledger before `callInternal` retains the payload. A pending write
+            // RPC holds `params.data` until it settles, so this reservation bounds the
+            // aggregate host→worker pending-write bytes across every route. A stop
+            // request carries no payload, so it reserves nothing. When no ledger is
+            // present, admit the write with no token (a unit test constructs the handle
+            // this way).
+            let pendingWriteToken = null;
+            if (method === "duplexChannelWrite" && duplexAggregateByteLedger) {
+                pendingWriteToken = duplexAggregateByteLedger.reserve("pending_write", writeByteCount ?? 0);
+                if (!pendingWriteToken) {
+                    // The reservation would pass the aggregate ceiling. Retain nothing, do
+                    // not enqueue the RPC, and end the route fail-closed with the aggregate
+                    // marker, not the route-busy marker.
+                    log.warn({ pluginId, reason: DUPLEX_CHANNEL_AGGREGATE_BYTES_EXCEEDED }, "duplex pending write reservation rejected");
+                    void terminalizeDuplexChannelRoute(route);
+                    return;
+                }
+            }
+            route.pendingRequests += 1;
+            // Meter the child-stdin transport buffer only for a duplex write. A stop
+            // request carries a tiny fixed frame that the host never lets grow, so it
+            // does not meter or reject. The write path reserves the serialized frame in
+            // `sendMessage` right before the stdin write.
+            const meterDuplexWrite = method === "duplexChannelWrite";
+            void callInternal(method, params, duplexChannelOpenTimeoutMs, undefined, meterDuplexWrite)
+                .catch((err) => {
+                if (err instanceof DuplexAggregateBytesExceededError) {
+                    // The transport reservation failed. The host did not write the frame.
+                    // End the route fail-closed with the aggregate marker, not the
+                    // route-busy marker.
+                    log.warn({ pluginId, reason: DUPLEX_CHANNEL_AGGREGATE_BYTES_EXCEEDED }, "duplex stdin write reservation rejected");
+                    void terminalizeDuplexChannelRoute(route);
+                }
+            })
+                .finally(() => {
+                route.pendingRequests -= 1;
+                // Release the pending-write token one time, after the RPC settles on any
+                // path: success, error, timeout, worker exit, or shutdown. The token is
+                // not in `route.retainedTokens`, so route terminalization never releases
+                // it; only this settlement releases it. The separate `stdin_write` token
+                // covers the serialized frame and releases on the stream flush, the
+                // stream error, the stream close, or the worker exit, never here.
+                if (pendingWriteToken) {
+                    duplexAggregateByteLedger?.release(pendingWriteToken);
+                }
+            });
+        };
+        return {
+            onData(listener) {
+                route.listener = listener;
+                if (route.buffered.length > 0) {
+                    const pending = route.buffered;
+                    route.buffered = [];
+                    route.bufferedChars = 0;
+                    for (const record of pending) {
+                        // Deliver each buffered record, drop its retained buffer, and release
+                        // its exact token before the drain proceeds to the next record. A
+                        // terminal route drains through this same code.
+                        deliverDuplexChannelChunk(listener, record.chunk);
+                        releaseRouteToken(route, record.token);
+                    }
+                    // The buffered records are gone, so the route no longer holds terminal
+                    // bytes for a late listener.
+                    terminalDuplexRoutes.delete(route);
+                }
+            },
+            write(data) {
+                const sid = route.workerSessionId;
+                if (route.state !== "open" || !sid)
+                    return;
+                if (data.byteLength > maxDuplexChannelWriteChars) {
+                    // The write is larger than the size bound. End the route before the
+                    // write reaches the worker.
+                    void terminalizeDuplexChannelRoute(route);
+                    return;
+                }
+                // Encode the raw bytes to the wire-safe base64 form (JSON carries no
+                // binary type) and pass the exact raw byte count separately, so the
+                // pending-write ledger reservation charges the real payload bytes, not
+                // the inflated base64 string length.
+                sendBoundedRequest("duplexChannelWrite", {
+                    hostRouteId: route.hostRouteId,
+                    workerSessionId: sid,
+                    data: encodeChannelBytes(data),
+                }, data.byteLength);
+            },
+            wait() {
+                return waitPromise;
+            },
+            kill() {
+                const sid = route.workerSessionId;
+                if (!sid)
+                    return;
+                sendBoundedRequest("duplexChannelStop", { hostRouteId: route.hostRouteId, workerSessionId: sid });
+            },
+            async close() {
+                await terminalizeDuplexChannelRoute(route);
             },
         };
     }
@@ -840,15 +1811,26 @@ export function createPluginWorkerHandle(pluginId, options) {
             routeExecuteLogNotification(notification);
             return;
         }
-        // Setup-token login pseudo-terminal notifications: deliver output
+        // Login pseudo-terminal notifications: deliver output
         // and the exit to the one host-owned login route, bound by the worker session
         // identifier while the route is open.
-        if (notification.method === SETUP_TOKEN_PTY_OUTPUT_NOTIFICATION) {
-            routeSetupTokenPtyOutput(notification);
+        if (notification.method === LOGIN_PTY_OUTPUT_NOTIFICATION) {
+            routeLoginPtyOutput(notification);
             return;
         }
-        if (notification.method === SETUP_TOKEN_PTY_EXIT_NOTIFICATION) {
-            routeSetupTokenPtyExit(notification);
+        if (notification.method === LOGIN_PTY_EXIT_NOTIFICATION) {
+            routeLoginPtyExit(notification);
+            return;
+        }
+        // Duplex channel notifications: deliver data and the exit to the one
+        // host-owned duplex route, bound by the worker session identifier while the
+        // route is open.
+        if (notification.method === DUPLEX_CHANNEL_DATA_NOTIFICATION) {
+            routeDuplexChannelData(notification);
+            return;
+        }
+        if (notification.method === DUPLEX_CHANNEL_EXIT_NOTIFICATION) {
+            routeDuplexChannelExit(notification);
             return;
         }
         // Stream notifications: forward to the stream bus via callback
@@ -921,6 +1903,17 @@ export function createPluginWorkerHandle(pluginId, options) {
             readline = createInterface({ input: child.stdout });
             readline.on("line", handleLine);
         }
+        // Release the outstanding child-stdin transport tokens when the stdin stream
+        // errors or closes, because each discards the stdin write buffer. The `error`
+        // listener also stops an unhandled EPIPE from a child that closed its stdin.
+        if (child.stdin) {
+            child.stdin.on("error", () => {
+                releaseAllPendingStdinWriteTokens();
+            });
+            child.stdin.on("close", () => {
+                releaseAllPendingStdinWriteTokens();
+            });
+        }
         // Capture stderr for logging
         if (child.stderr) {
             stderrReadline = createInterface({ input: child.stderr });
@@ -958,12 +1951,20 @@ export function createPluginWorkerHandle(pluginId, options) {
         }
         childProcess = null;
         startedAt = null;
+        // The worker exit discards the child-stdin write buffer, so release every
+        // outstanding transport token. The RPC rejections below never release these
+        // tokens; only this sweep, a stream flush, a stream error, or a stream close
+        // releases them.
+        releaseAllPendingStdinWriteTokens();
         // Reject all pending requests
         rejectAllPending(new Error(formatWorkerFailureMessage(`Worker process exited (code=${code}, signal=${signal})`, stderrExcerpt)));
         // Close the one login pseudo-terminal route with a fixed non-secret exit and
         // clear the route one time. The pending pseudo-terminal calls
         // already rejected through `rejectAllPending`.
-        closeSetupTokenPtyRouteOnWorkerExit();
+        closeLoginPtyRouteOnWorkerExit();
+        // Close the one duplex channel route the same way. The pending channel calls
+        // already rejected through `rejectAllPending`.
+        closeDuplexChannelRouteOnWorkerExit();
         // Emit synthetic close for any orphaned stream channels so SSE clients
         // are notified instead of hanging indefinitely.
         if (openStreamChannels.size > 0 && options.onStreamNotification) {
@@ -1216,7 +2217,7 @@ export function createPluginWorkerHandle(pluginId, options) {
     // -----------------------------------------------------------------------
     // RPC call implementation
     // -----------------------------------------------------------------------
-    function callInternal(method, params, timeoutMs, executeLogSink) {
+    function callInternal(method, params, timeoutMs, executeLogSink, meterDuplexWrite = false) {
         const rpcPromise = new Promise((resolve, reject) => {
             if (!childProcess?.stdin?.writable) {
                 reject(new Error(`Cannot call "${method}" — worker for "${pluginId}" is not running`));
@@ -1278,14 +2279,22 @@ export function createPluginWorkerHandle(pluginId, options) {
                     ...createRequest(method, params, id),
                     ...(invocation ? { paperclipInvocation: invocation } : {}),
                 };
-                sendMessage(request);
+                sendMessage(request, meterDuplexWrite);
             }
             catch (err) {
                 clearTimeout(timer);
                 pendingRequests.delete(id);
                 clearInvocation(invocation);
                 clearExecuteRoute(invocation?.id);
-                reject(new Error(`Failed to send "${method}" to worker: ${err instanceof Error ? err.message : String(err)}`));
+                if (err instanceof DuplexAggregateBytesExceededError) {
+                    // The transport reservation failed before the write. Reject with the
+                    // typed error unwrapped, so the duplex write caller ends the route
+                    // fail-closed with the aggregate marker.
+                    reject(err);
+                }
+                else {
+                    reject(new Error(`Failed to send "${method}" to worker: ${err instanceof Error ? err.message : String(err)}`));
+                }
             }
         });
         // Some call sites hand these promises across async boundaries before
@@ -1324,11 +2333,17 @@ export function createPluginWorkerHandle(pluginId, options) {
             }
             return callInternal(method, params, timeoutMs, executeLogSink);
         },
-        openSetupTokenPtySession(input) {
+        openLoginPtySession(input) {
             if (status !== "running" && status !== "starting") {
                 return Promise.reject(new Error(`Cannot open a login pseudo-terminal — worker for "${pluginId}" is ${status}`));
             }
-            return openSetupTokenPtySession(input);
+            return openLoginPtySession(input);
+        },
+        openDuplexChannel(input) {
+            if (status !== "running" && status !== "starting") {
+                return Promise.reject(new Error(`Cannot open a duplex channel — worker for "${pluginId}" is ${status}`));
+            }
+            return openDuplexChannel(input);
         },
         notify(method, params) {
             if (status !== "running")
@@ -1383,6 +2398,35 @@ export function createPluginWorkerHandle(pluginId, options) {
     };
     return handle;
 }
+/**
+ * The default process-scoped aggregate ceiling for concurrent duplex channel
+ * routes. It caps the manager-wide resource, not one agent's run budget. The host
+ * reports an explicit route-busy outcome when the ceiling is full.
+ */
+export const DEFAULT_MAX_CONCURRENT_DUPLEX_ROUTES = 128;
+/**
+ * Build one process-scoped aggregate route-slot controller. The controller holds a
+ * strictly positive integer ceiling and a live count. `tryAcquire` reserves one
+ * slot only when a slot is free, so the count never passes the ceiling.
+ */
+export function createDuplexRouteSlotController(maxRoutes) {
+    const ceiling = typeof maxRoutes === "number" && Number.isInteger(maxRoutes) && maxRoutes > 0
+        ? maxRoutes
+        : DEFAULT_MAX_CONCURRENT_DUPLEX_ROUTES;
+    let active = 0;
+    return {
+        tryAcquire() {
+            if (active >= ceiling)
+                return false;
+            active += 1;
+            return true;
+        },
+        release() {
+            if (active > 0)
+                active -= 1;
+        },
+    };
+}
 /**
  * Create a new PluginWorkerManager.
  *
@@ -1414,6 +2458,15 @@ export function createPluginWorkerManager(managerOptions) {
     const workers = new Map();
     /** Per-plugin startup locks to prevent concurrent spawn races. */
     const startupLocks = new Map();
+    // The one shared, process-scoped aggregate route-slot controller. The manager
+    // injects it into every worker handle, so the duplex route ceiling counts every
+    // concurrent route across the process, not one agent's setting.
+    const duplexRouteSlots = createDuplexRouteSlotController(managerOptions?.maxConcurrentDuplexRoutes);
+    // The one shared, process-owned aggregate byte ledger. The manager injects the
+    // same object into every worker handle, so one gauge bounds the aggregate
+    // retained bytes across every route in the process. It is `null` when the
+    // process root injected no ledger.
+    const duplexAggregateByteLedger = managerOptions?.duplexAggregateByteLedger ?? null;
     return {
         async startWorker(pluginId, options) {
             // Mutex: if a start is already in-flight for this plugin, wait for it
@@ -1426,7 +2479,14 @@ export function createPluginWorkerManager(managerOptions) {
             if (existing && existing.status !== "stopped") {
                 throw new Error(`Worker already registered for plugin "${pluginId}" (status: ${existing.status})`);
             }
-            const handle = createPluginWorkerHandle(pluginId, options);
+            const handle = createPluginWorkerHandle(pluginId, {
+                // Inject the shared process-scoped route-slot controller and the shared
+                // process-owned aggregate byte ledger, unless the caller already supplied
+                // its own (a test may inject its own).
+                duplexRouteSlots,
+                duplexAggregateByteLedger,
+                ...options,
+            });
             workers.set(pluginId, handle);
             // Subscribe to crash/ready events for live event forwarding
             if (managerOptions?.onWorkerEvent) {
@@ -1505,12 +2565,12 @@ export function createPluginWorkerManager(managerOptions) {
             }
             return handle.call(method, params, timeoutMs, executeLogSink);
         },
-        openSetupTokenPtySession(pluginId, input) {
+        openLoginPtySession(pluginId, input) {
             const handle = workers.get(pluginId);
             if (!handle) {
                 return Promise.reject(new Error(`No worker registered for plugin "${pluginId}"`));
             }
-            return handle.openSetupTokenPtySession(input);
+            return handle.openLoginPtySession(input);
         },
     };
 }