@chances-ai/wire 24.3.0 → 25.0.0

package/dist/serve/acp-session-host.js

@@ -1,251 +1,646 @@
 /**
- * (v20 M3 / docs/6.4a §3; v21 M4 lease / docs/6.5 §5) `AcpSessionHost` — the ACP
- * twin of the bespoke session host. ONE persistent engine session per process,
- * sockets attach/detach over a seq-stamping `ReplayHub` fan-out; the inner engine
- * is the `AcpEngineDriver` (ACP JSON-RPC wire).
+ * (v20 M3 / docs/6.4a §3; v21 M4 lease; **7.5 §14 TRUE-concurrent SessionRouter**)
+ * `AcpSessionHost` — the ACP relay's connection-level host. Originally ONE engine
+ * session per process; as of 7.5 §14 it is a **SessionRouter** that owns N live
+ * `SessionUnit`s (each = its own `ReplayHub` ring + `AcpEngineDriver` turn-runner +
+ * `MessageQueue` + isolated engine), so several sessions run concurrent turns
+ * without cross-talk. The class name is kept (the relay imports it) — it IS the
+ * session host, now multi-session.
  *
- * Two deliberate differences from the M2 design:
- *  1. **State source.** The reconnect snapshot (`busy` / `pendingPermissionIds`)
- *     is read straight off the driver (authoritative). The `ReplayHub` stays a
- *     pure payload-agnostic seq/replay/fan-out layer — it does NOT parse the
- *     outbound bytes for session state (a byte-snoop lived there in the
- *     chances-rpc era; removed with the M3 hard cutover, since ACP frames' first
- *     key is `jsonrpc`/`rseq`, never `type`).
- *  2. **No `ready` re-send.** ACP is client-initiated: a fresh client sends
- *     `initialize`/`session/new` and the driver replies; a cold-reloaded client
- *     re-initializes (client-core, c4).
+ * **Layering (the split that makes concurrency safe):**
+ *  - *Connection-level* (this object): the controller lease, the per-socket socket
+ *    map, the interactive terminals (workspace-level, not chat-session-bound), the
+ *    off-ring read queries / `apply_edit`, `take_control`, and the session
+ *    lifecycle (`session/new` / `session/load` / `list_sessions`). It also tracks
+ *    each client's ACTIVE session (which unit's stream that device sees).
+ *  - *Session-level* (a `SessionUnit`): the turn loop — `session/prompt` →
+ *    `engine.runTurn` → that session's bus → `session/update` → that unit's
+ *    `ReplayHub` → fanned ONLY to sockets whose active session is this unit.
  *
- * **Controller lease (v21 M4 §5).** Disabled by default ⇒ fan-out: any paired
- * device drives, the engine serializes turns via `AGENT_BUSY` (the M2 model).
- * When enabled, this host gates every inbound command by its source clientId —
- * only the lease HOLDER may drive (`session/prompt`/`cancel`), answer a
- * permission, or change the model; everyone else is a read-only VIEWER and gets a
- * typed `not_controller`. `_chances/unstable/take_control` hands control over
- * (any authed client may claim it — single-user multi-device) and bumps
- * `controlEpoch`; the new holder + epoch are broadcast as a
- * `_chances/unstable/control` notification. The gate lives HERE (it needs the
- * socket→clientId map) so the driver stays a protocol-pure turn runner.
+ * **Per-session ring (decision §6.1 / §14, codex R3 Q4).** Each unit has its own
+ * `ReplayHub` (rseq/session): a device attaches to its active session's hub, so it
+ * receives only that session's stream and reconnect-replays only that session's
+ * gap. Connection-level broadcasts (lease state, `workspace_changed`) are written
+ * to EVERY unit's hub ({@link broadcastToAllUnits}) so they reach every socket —
+ * and for the N=1 degenerate (one unit) that is byte-identical to the pre-§14
+ * single-hub behaviour.
  *
- * **Threat model (codex M4-review).** The lease is COORDINATION among one user's
- * equally-authed devices, NOT an authorization boundary. The security boundary is
- * the pairing token (every connection is already token-authed); `clientId` is a
- * self-reported coordination tag, not a trusted identity. A device could spoof
- * another's clientId to "impersonate" the holder — but it gains nothing
- * `take_control` doesn't already grant (any authed client may claim control), so
- * there is no privilege escalation among your own devices. A truly-restricted
- * viewer (read-only access shared with a THIRD party) needs server-issued identity
- * and belongs to the multi-tenant Team era — out of scope here.
+ * **N=1 byte-identical (hard condition, codex R3 Q2).** The eagerly-built DEFAULT
+ * unit + the unchanged `AcpEngineDriver` per-session handlers mean a single-session
+ * connection (one `session/new`, prompts, reconnect) emits exactly the same bytes
+ * as before: initialize / session-new / prompt responses are produced by the SAME
+ * driver code, stamped through the (one) hub; the attach order (relay_welcome →
+ * replayed gap → re-sent open permissions → live socket) is preserved.
  *
- * The seq/replay layer (`ReplayHub`) is reused UNCHANGED — it stamps `rseq` on
- * the serialized ACP JSON-RPC bytes (payload-agnostic, docs/6.2 §3.2).
+ * **Active session is keyed by `clientId` (codex R3 Q3 note).** `clientId` is
+ * minted per `RpcClient` INSTANCE (it doubles as the JSON-RPC id-correlation
+ * prefix, so the wire already requires it unique per client). Two browser tabs are
+ * two `RpcClient`s ⇒ two clientIds; a reconnect reuses its clientId to resume its
+ * lease / terminals / active session — exactly what we want. The "two live sockets
+ * share one clientId" case codex flagged needs a non-conformant client (id
+ * correlation would already break), so per-client active-session is consistent with
+ * the existing trust model and avoids a redundant per-socket token.
+ *
+ * **Controller lease (v21 M4 §5).** Disabled by default ⇒ fan-out (any paired
+ * device drives; the engine serializes turns via `AGENT_BUSY`). When enabled, only
+ * the HOLDER may drive (prompt/cancel/new/load/set_model) or answer a permission;
+ * others are read-only VIEWERs (`not_controller`). The lease is COORDINATION among
+ * one user's equally-authed devices, NOT an authorization boundary (the pairing
+ * token is the security boundary; `clientId` is a self-reported coordination tag).
+ *
+ * The seq/replay layer (`ReplayHub`) is reused UNCHANGED — payload-agnostic rseq
+ * stamping on the serialized ACP JSON-RPC bytes.
  */
-import { AcpEngineDriver, dispatchWorkspaceQuery, hostSupportsWorkspaceQueries, isWorkspaceQueryMethod, } from "../rpc/index.js";
+import { AcpEngineDriver, TERMINAL_METHODS, dispatchWorkspaceEdit, dispatchWorkspaceQuery, hostSupportsTerminal, hostSupportsWorkspaceEdits, hostSupportsWorkspaceQueries, isTerminalMethod, isWorkspaceEditMethod, isWorkspaceQueryMethod, } from "../rpc/index.js";
 import { ReplayHub } from "./replay-hub.js";
 import { MessageQueue } from "./ws-transport.js";
 /** Lease wire methods (chances extensions; a plain ACP client never sends them). */
 const METHOD_TAKE_CONTROL = "_chances/unstable/take_control";
 const METHOD_CONTROL_STATE = "_chances/unstable/control";
-/** JSON-RPC error for a viewer's privileged command while a lease is held. */
+/** (7.5 W1) Fanned after a successful `apply_edit` so OTHER devices viewing the
+ *  same file re-query. A connection-level broadcast — NOT an AppEvent. */
+const METHOD_WORKSPACE_CHANGED = "_chances/unstable/workspace_changed";
+/** Session lifecycle (router-owned). */
+const METHOD_NEW_SESSION = "session/new";
+const METHOD_LOAD_SESSION = "session/load";
+const METHOD_LIST_SESSIONS = "_chances/unstable/list_sessions";
+/** JSON-RPC error codes. */
 const NOT_CONTROLLER = -32010;
-/** (v23 M5) Bound a read-only workspace query so a hung git/fs can't park a
- *  fire-and-forget handler forever. */
+const ERR_INVALID_PARAMS = -32602;
+/** (v23 M5) Bound a read-only workspace query so a hung git/fs can't park forever. */
 const QUERY_TIMEOUT_MS = 10_000;
+/** (7.5 W3) Per-terminal bounded output ring (frames) — cursor-style scrollback. */
+const TERM_RING = 1000;
+/** (codex R2 M3) Cap concurrent terminals per process (orphan-PTY leak guard). */
+const MAX_TERMINALS = 8;
+/** (7.5 §14) Cap concurrent LIVE sessions so `session/new` spam can't grow memory
+ *  unbounded; opening past the cap evicts the OLDEST idle (non-busy) unit. */
+const MAX_LIVE_SESSIONS = 16;
+/** Placeholder handle held while a PTY spawns (codex R2 S4). */
+const NOOP_HANDLE = { write: () => { }, resize: () => { }, close: () => { } };
 export class AcpSessionHost {
-    hub;
-    queue = new MessageQueue();
-    driver;
     host;
-    done;
+    opts;
+    ringOpts;
+    driverCaps;
     epochCounter = 0;
     shuttingDown = false;
+    // -- (§14) the live sessions --
+    units = new Map();
+    defaultSessionId;
+    /** The FIRST `session/new` claims the eagerly-built default unit (N=1 byte
+     *  identical); subsequent `session/new`s mint fresh units. */
+    defaultClaimed = false;
+    sessionSeq = 0;
     // -- controller lease (§5) --
     leaseEnabled;
     holder = null;
     controlEpoch = 0;
-    /** clientId → socket, for TARGETED lease replies (not_controller / ack). */
-    socketsByClient = new Map();
+    /** clientId → its connection (socket + active session). */
+    conns = new Map();
+    // -- (7.5 W3) interactive terminals (connection/workspace-level) --
+    terminalEnabled;
+    terminalSeq = 0;
+    terminals = new Map();
     constructor(opts) {
-        this.hub = new ReplayHub(opts.ring);
         this.host = opts.host;
+        this.opts = opts;
+        this.ringOpts = opts.ring;
         this.leaseEnabled = opts.controllerLease ?? false;
-        this.driver = new AcpEngineDriver({
-            host: opts.host,
-            sink: this.hub,
-            agent: opts.agent,
-            autoApprove: opts.autoApprove ?? false,
-            logSink: opts.logSink,
-            // (v23 M5) Advertise read-only workspace queries when the host supports
-            // them — this host intercepts + answers them off-ring (the driver itself
-            // never handles them), so the capability is honest only under the relay.
+        this.terminalEnabled = (opts.terminalEnabled ?? false) && hostSupportsTerminal(opts.host);
+        this.driverCaps = {
+            // (v23 M5) read-only queries — relay answers off-ring (driver advertises).
             workspaceQueries: hostSupportsWorkspaceQueries(opts.host),
+            // (7.5 W1) client-initiated write — relay answers off-ring AFTER controller check.
+            workspaceEdits: hostSupportsWorkspaceEdits(opts.host),
+            // (7.5 W3) interactive PTY — only when enabled + supported.
+            terminal: this.terminalEnabled,
+        };
+        // Build the eagerly-created DEFAULT unit (N=1 byte-identical with pre-§14).
+        const unit = this.createUnit((resolver) => ({ built: this.host.build(resolver) }));
+        if (!unit)
+            throw new Error("AcpSessionHost: failed to build the default engine session");
+        this.defaultSessionId = unit.sessionId;
+    }
+    /** (§14) Spin up a new live session: its own hub + queue + driver. The driver's
+     *  `run()` builds the engine through `loader` (its own resolver) in its
+     *  synchronous prefix, so `driver.sessionId` is set by the time `run()` returns
+     *  the promise — we can key the unit immediately. */
+    createUnit(loader) {
+        const hub = new ReplayHub(this.ringOpts);
+        const queue = new MessageQueue();
+        let built;
+        const driver = new AcpEngineDriver({
+            host: this.host,
+            sink: hub,
+            agent: this.opts.agent,
+            autoApprove: this.opts.autoApprove ?? false,
+            ...(this.opts.logSink ? { logSink: this.opts.logSink } : {}),
+            workspaceQueries: this.driverCaps.workspaceQueries,
+            workspaceEdits: this.driverCaps.workspaceEdits,
+            terminal: this.driverCaps.terminal,
+            buildFn: (resolver) => {
+                const r = loader(resolver);
+                built = r.built;
+                return r;
+            },
         });
-        // Build + drive the one session immediately; `run` reads the persistent
-        // queue until it ends (process shutdown). Fire-and-forget; run catches.
-        this.done = this.driver.run(this.queue).catch(() => 1);
+        const done = driver.run(queue).catch(() => 1);
+        // (codex R4 M3) `run()`'s synchronous prefix sets `driver.id` — UNLESS the
+        // loader/host.build threw before the first await (run() then returns a rejected
+        // promise + id stays ""). Fail fast: never key a unit on "" / leave it half-live.
+        if (!driver.id) {
+            queue.end();
+            void done;
+            return null;
+        }
+        const unit = {
+            sessionId: driver.id,
+            hub,
+            driver,
+            queue,
+            done,
+            ...(built?.dispose ? { dispose: built.dispose.bind(built) } : {}),
+        };
+        this.units.set(unit.sessionId, unit);
+        this.evictIfOverCap();
+        return unit;
+    }
+    /** Evict the OLDEST idle unit when over the cap — so `session/new` spam can't
+     *  leak. A victim must be non-default, non-busy, AND not currently VIEWED by any
+     *  connection (codex R4 M2 — evicting a viewed session would orphan its conns,
+     *  whose later messages would silently route to the default unit). Logs what was
+     *  dropped (no silent truncation); if every over-cap unit is protected, we keep
+     *  them (better a bounded overshoot than killing a live/viewed session). */
+    evictIfOverCap() {
+        while (this.units.size > MAX_LIVE_SESSIONS) {
+            const viewed = new Set([...this.conns.values()].map((c) => c.activeSessionId));
+            let victim;
+            for (const u of this.units.values()) {
+                if (u.sessionId === this.defaultSessionId || u.driver.busy || viewed.has(u.sessionId))
+                    continue;
+                victim = u;
+                break;
+            }
+            if (!victim)
+                break; // all busy / viewed / only default — don't force-kill one
+            this.opts.logSink?.(`relay: evicting idle session ${victim.sessionId} (over MAX_LIVE_SESSIONS)\n`);
+            this.units.delete(victim.sessionId);
+            victim.queue.end();
+            void victim.dispose?.();
+        }
+    }
+    unitFor(sessionId) {
+        return (sessionId !== undefined && this.units.get(sessionId)) || this.units.get(this.defaultSessionId);
     }
     /**
-     * Attach a socket, synchronously replaying everything since `lastSeq` then
-     * going live (same disjoint-and-ordered guarantee as the M2 host). `clientId`
-     * (from the `?client_id=` connect query) attributes this socket for the lease.
-     * Wire order: `relay_welcome` → replayed gap → re-sent open permissions → [live].
+     * Attach a socket, replaying everything since `lastSeq` from its active session's
+     * ring then going live. `sessionId` (the `?session_id=` connect query) selects
+     * which unit to view (defaults to the client's last active, else the default
+     * unit — N=1 byte-identical). Wire order: `relay_welcome` → replayed gap →
+     * re-sent open permissions → [live].
      */
-    attach(socket, lastSeq, clientId) {
+    attach(socket, lastSeq, clientId, sessionId) {
         const epoch = ++this.epochCounter;
-        const slice = this.hub.replaySince(lastSeq);
+        const prevActive = clientId ? this.conns.get(clientId)?.activeSessionId : undefined;
+        const unit = this.unitFor(sessionId ?? prevActive);
+        const slice = unit.hub.replaySince(lastSeq);
         const welcome = {
             type: "relay_welcome",
             epoch,
-            headSeq: this.hub.headSeq,
+            headSeq: unit.hub.headSeq,
             reset: slice.reset,
-            busy: this.driver.busy,
-            pendingPermissionIds: this.driver.pendingPermissionIds(),
+            busy: unit.driver.busy,
+            pendingPermissionIds: unit.driver.pendingPermissionIds(),
             lease: this.leaseEnabled,
             holder: this.holder,
             controlEpoch: this.controlEpoch,
         };
-        if (!this.hub.sendTo(socket, frameLine(welcome)))
+        if (!unit.hub.sendTo(socket, frameLine(welcome)))
             return deadAttachment(epoch);
         for (const line of slice.frames) {
-            if (!this.hub.sendTo(socket, line))
+            if (!unit.hub.sendTo(socket, line))
                 return deadAttachment(epoch);
         }
-        // Re-send still-open permission asks (the ring may have evicted them); the
-        // client de-dups by permission id, so one also present in the replay is a no-op.
-        for (const open of this.driver.openPermissionFrames()) {
-            if (!this.hub.sendTo(socket, open))
+        for (const open of unit.driver.openPermissionFrames()) {
+            if (!unit.hub.sendTo(socket, open))
                 return deadAttachment(epoch);
         }
-        this.hub.addSocket(socket);
-        if (clientId)
-            this.socketsByClient.set(clientId, socket);
+        unit.hub.addSocket(socket);
+        if (clientId) {
+            this.conns.set(clientId, { socket, activeSessionId: unit.sessionId });
+            if (this.terminalEnabled)
+                this.resubscribeTerminals(clientId, socket);
+        }
         return {
             epoch,
             detach: () => {
-                this.hub.removeSocket(socket);
-                // Only drop the mapping if it still points at THIS socket — a reconnect
-                // with the same clientId installs a new socket we must not evict. The
-                // holder is intentionally retained: the same client reconnecting resumes
-                // control; another device can always `take_control` if it left for good.
-                if (clientId && this.socketsByClient.get(clientId) === socket)
-                    this.socketsByClient.delete(clientId);
+                unit.hub.removeSocket(socket);
+                if (clientId && this.conns.get(clientId)?.socket === socket)
+                    this.conns.delete(clientId);
+                if (clientId)
+                    this.detachTerminals(clientId);
             },
         };
     }
     /**
-     * One inbound text message (ACP JSON-RPC). Split LF-batched lines; each line
-     * passes the lease {@link gate} (a no-op when the lease is disabled) before
-     * reaching the ONE persistent queue. `fromClientId` (the attach's clientId)
-     * attributes the command to a client for the lease.
+     * One inbound text message (ACP JSON-RPC). Connection-level methods (off-ring
+     * queries/edit/terminal, the lease, the session lifecycle) are handled here;
+     * everything else is routed to the client's ACTIVE session unit's queue.
      */
     onMessage(text, fromClientId) {
         for (const part of text.split("\n")) {
             const line = part.trim();
             if (!line)
                 continue;
-            // (v23 M5) Read-only workspace queries (file tree / read / git) are
-            // intercepted BEFORE the lease gate — they are non-privileged, so a viewer
-            // may browse — and answered targeted + off-ring (never enqueued, never
-            // stamped into the replay ring; a big `read_file` must not fan out to every
-            // device or get replayed on reconnect).
             const msg = tryParseMessage(line);
-            if (msg && typeof msg.method === "string" && isWorkspaceQueryMethod(msg.method)) {
+            const method = msg && typeof msg.method === "string" ? msg.method : undefined;
+            // (v23 M5) Read-only workspace queries — non-privileged (viewers browse),
+            // answered targeted + off-ring (never enqueued / never stamped).
+            if (method && isWorkspaceQueryMethod(method)) {
                 void this.handleQuery(msg, fromClientId);
                 continue;
             }
-            if (this.gate(line, fromClientId))
-                this.queue.push(line);
+            // (7.5 W1) apply_edit — PRIVILEGED off-ring write (controller-gated).
+            if (method && isWorkspaceEditMethod(method)) {
+                if (this.requireController(msg, fromClientId))
+                    void this.handleEdit(msg, fromClientId);
+                continue;
+            }
+            // (7.5 W3) interactive terminal — PRIVILEGED off-ring.
+            if (method && this.terminalEnabled && isTerminalMethod(method)) {
+                if (this.requireController(msg, fromClientId))
+                    void this.handleTerminal(msg, fromClientId);
+                continue;
+            }
+            // (§14) Session lifecycle — router-owned (creates/switches units).
+            if (method === METHOD_NEW_SESSION || method === METHOD_LOAD_SESSION || method === METHOD_LIST_SESSIONS) {
+                // new/load are privileged (they switch the active engine); list is read-only.
+                if (method === METHOD_LIST_SESSIONS) {
+                    this.handleListSessions(msg, fromClientId);
+                }
+                else if (this.requireController(msg, fromClientId)) {
+                    if (method === METHOD_NEW_SESSION)
+                        this.handleNewSession(msg, fromClientId);
+                    else
+                        this.handleLoadSession(msg, fromClientId);
+                }
+                continue;
+            }
+            // Everything else: the lease gate, then route to the active session unit.
+            if (this.gate(line, fromClientId)) {
+                this.routeToActive(line, msg, fromClientId);
+            }
+        }
+    }
+    /** Route a session-level line (prompt, cancel, permission answer, set_model,
+     *  set_options, initialize, get_state, get_models, ping) to the client's active
+     *  session unit. A `params.sessionId`, when present, addresses a specific unit
+     *  (prompt/cancel carry it — codex R3 Q3); a JSON-RPC RESPONSE (no method, has id
+     *  — a permission answer) is broadcast to ALL units so the owning driver resolves
+     *  it and the rest ignore the foreign id. */
+    routeToActive(line, msg, fromClientId) {
+        const isResponse = msg !== null && msg.method === undefined && msg.id !== undefined;
+        if (isResponse) {
+            for (const unit of this.units.values())
+                unit.queue.push(line);
+            return;
+        }
+        const sid = typeof msg?.params?.sessionId === "string"
+            ? (msg.params.sessionId)
+            : undefined;
+        const active = fromClientId ? this.conns.get(fromClientId)?.activeSessionId : undefined;
+        this.unitFor(sid ?? active).queue.push(line);
+    }
+    /** (§14) `session/new`: the FIRST claims the default unit (N=1 byte-identical);
+     *  later ones mint a fresh unit. Switch the requesting client's view to it, then
+     *  push the `session/new` line to that unit's driver so IT responds (eager
+     *  sessionId) — reusing the driver's exact response bytes. */
+    handleNewSession(msg, fromClientId) {
+        let unit;
+        if (!this.defaultClaimed) {
+            this.defaultClaimed = true;
+            unit = this.units.get(this.defaultSessionId);
+        }
+        else {
+            const created = this.createUnit((resolver) => ({ built: this.host.build(resolver) }));
+            if (!created) {
+                // (codex R4 M3) build failed → don't switch to an empty session.
+                if (msg.id !== undefined)
+                    this.replyTo(fromClientId, errorFrame(msg.id, -32000, "failed to create session"));
+                return;
+            }
+            unit = created;
+        }
+        this.switchClientTo(fromClientId, unit, /*replay*/ false);
+        unit.queue.push(JSON.stringify(msg));
+    }
+    /** (§14) `session/load`: rejoin a live unit, or resume one from the store into a
+     *  fresh unit, then switch the client's view (replaying that unit's ring) and
+     *  ack. Unknown id → invalidParams. */
+    handleLoadSession(msg, fromClientId) {
+        const id = msg.params?.sessionId;
+        if (typeof id !== "string" || !this.host.loadSession) {
+            if (msg.id !== undefined)
+                this.replyTo(fromClientId, errorFrame(msg.id, ERR_INVALID_PARAMS, "loadSession unsupported or missing sessionId"));
+            return;
+        }
+        const live = this.units.get(id);
+        if (live) {
+            this.switchClientTo(fromClientId, live, /*replay*/ true);
+            if (msg.id !== undefined)
+                live.hub.write(frameLine(resultFrame(msg.id, {})));
+            return;
+        }
+        // Not live → must exist in the store to resume.
+        const known = this.host.listSessions?.().some((s) => s.id === id) ?? false;
+        if (!known) {
+            if (msg.id !== undefined)
+                this.replyTo(fromClientId, errorFrame(msg.id, ERR_INVALID_PARAMS, "unknown session"));
+            return;
+        }
+        const loadFn = this.host.loadSession.bind(this.host);
+        const unit = this.createUnit((resolver) => {
+            const loaded = loadFn(id, resolver);
+            if (!loaded)
+                throw new Error("unknown session");
+            return { built: loaded.engine, history: loaded.history };
+        });
+        if (!unit) {
+            // (codex R4 M3) resume build failed/raced — createUnit already cleaned up.
+            if (msg.id !== undefined)
+                this.replyTo(fromClientId, errorFrame(msg.id, ERR_INVALID_PARAMS, "unknown session"));
+            return;
+        }
+        this.switchClientTo(fromClientId, unit, /*replay*/ true);
+        if (msg.id !== undefined)
+            unit.hub.write(frameLine(resultFrame(msg.id, {})));
+    }
+    /** (§14) `list_sessions`: read-only, merge live + persisted, off-ring reply. */
+    handleListSessions(msg, fromClientId) {
+        if (msg.id === undefined)
+            return;
+        // Mark a session busy when its LIVE unit has a turn in flight, so a sidebar can
+        // flag a working/awaiting-permission background session (codex R3 Q3).
+        const busyOf = (id) => this.units.get(id)?.driver.busy ?? false;
+        const fromStore = this.host.listSessions?.().map((s) => ({ ...s, busy: busyOf(s.id) })) ?? [];
+        const seen = new Set(fromStore.map((s) => s.id));
+        // Surface any live-but-not-yet-persisted unit too (defensive — serve persists
+        // on create, so this is normally a no-op).
+        const live = [...this.units.keys()]
+            .filter((id) => !seen.has(id))
+            .map((id) => ({ id, title: id, updatedAt: "", busy: busyOf(id) }));
+        this.replyTo(fromClientId, resultFrame(msg.id, { sessions: [...fromStore, ...live] }));
+    }
+    /** Move a client's view to `unit`: detach its socket from the old unit's hub,
+     *  attach to the new one (optionally replaying the new unit's ring so a
+     *  session/load device sees the rehydrated transcript), update active session. */
+    switchClientTo(clientId, unit, replay) {
+        if (!clientId)
+            return;
+        const conn = this.conns.get(clientId);
+        if (conn) {
+            if (conn.activeSessionId !== unit.sessionId) {
+                const old = this.units.get(conn.activeSessionId);
+                old?.hub.removeSocket(conn.socket);
+                if (replay) {
+                    for (const line of unit.hub.replaySince(0).frames)
+                        unit.hub.sendTo(conn.socket, line);
+                    // (codex R4 S1) Re-send still-open permission asks so a switched-to busy
+                    // session's parked permission stays answerable even if the ring evicted
+                    // its original request frame (mirrors the attach path).
+                    for (const open of unit.driver.openPermissionFrames())
+                        unit.hub.sendTo(conn.socket, open);
+                }
+                unit.hub.addSocket(conn.socket);
+                conn.activeSessionId = unit.sessionId;
+            }
         }
     }
-    /** Answer one read-only workspace query: dispatch to the host's query
-     *  primitives and `replyTo` the originating socket only (off-ring). Needs an id
-     *  (to respond) and a clientId (to target); a query missing either is dropped
-     *  (a conformant client always sends both). */
+    // -- off-ring handlers (connection-level; reply to the requesting socket) -----
     async handleQuery(msg, fromClientId) {
         if (msg.id === undefined || fromClientId === undefined)
             return;
         const outcome = await dispatchWorkspaceQuery(this.host, msg.method, msg.params, AbortSignal.timeout(QUERY_TIMEOUT_MS));
-        this.replyTo(fromClientId, outcome.error ? { jsonrpc: "2.0", id: msg.id, error: outcome.error } : { jsonrpc: "2.0", id: msg.id, result: outcome.result });
+        this.replyTo(fromClientId, outcome.error ? errorObj(msg.id, outcome.error) : resultFrame(msg.id, outcome.result));
     }
-    /**
-     * Controller-lease gate. Returns true ⇒ the line may proceed to the driver;
-     * false ⇒ the host handled it (a handoff) or rejected it (a viewer's privileged
-     * command — a `not_controller` reply was sent to the source). A no-op (always
-     * true) when the lease is disabled.
-     */
+    async handleEdit(msg, fromClientId) {
+        if (msg.id === undefined || fromClientId === undefined)
+            return;
+        const outcome = await dispatchWorkspaceEdit(this.host, msg.params, AbortSignal.timeout(QUERY_TIMEOUT_MS));
+        this.replyTo(fromClientId, outcome.error ? errorObj(msg.id, outcome.error) : resultFrame(msg.id, outcome.result));
+        if (!outcome.error) {
+            const path = outcome.result?.path;
+            // Connection-level: fan to EVERY unit's hub so all devices re-query.
+            if (path !== undefined) {
+                this.broadcastToAllUnits(JSON.stringify({ jsonrpc: "2.0", method: METHOD_WORKSPACE_CHANGED, params: { path } }) + "\n");
+            }
+        }
+    }
+    async handleTerminal(msg, fromClientId) {
+        if (fromClientId === undefined)
+            return;
+        const p = (msg.params ?? {});
+        const entryOf = () => (typeof p.terminalId === "string" ? this.terminals.get(p.terminalId) : undefined);
+        switch (msg.method) {
+            case TERMINAL_METHODS.open: {
+                if (msg.id === undefined || !this.host.openTerminal)
+                    return;
+                const cols = typeof p.cols === "number" ? p.cols : 80;
+                const rows = typeof p.rows === "number" ? p.rows : 24;
+                while (this.terminals.size >= MAX_TERMINALS) {
+                    const oldest = this.terminals.keys().next().value;
+                    if (oldest === undefined)
+                        break;
+                    this.closeTerminal(oldest);
+                }
+                const id = `term_${++this.terminalSeq}`;
+                const entry = { handle: NOOP_HANDLE, owner: fromClientId, subscribers: new Set([fromClientId]), buf: [], headSeq: 0 };
+                this.terminals.set(id, entry);
+                try {
+                    entry.handle = await this.host.openTerminal({ cols, rows, cwd: typeof p.cwd === "string" ? p.cwd : undefined, command: typeof p.command === "string" ? p.command : undefined }, (data) => this.onTerminalOutput(id, data));
+                    this.replyTo(fromClientId, resultFrame(msg.id, { terminalId: id }));
+                }
+                catch (e) {
+                    this.terminals.delete(id);
+                    this.replyTo(fromClientId, errorFrame(msg.id, -32000, e.message));
+                }
+                return;
+            }
+            case TERMINAL_METHODS.input: {
+                const entry = entryOf();
+                if (entry && typeof p.data === "string")
+                    entry.handle.write(p.data);
+                return;
+            }
+            case TERMINAL_METHODS.resize: {
+                const entry = entryOf();
+                if (entry && typeof p.cols === "number" && typeof p.rows === "number")
+                    entry.handle.resize(p.cols, p.rows);
+                return;
+            }
+            case TERMINAL_METHODS.close: {
+                if (typeof p.terminalId === "string")
+                    this.closeTerminal(p.terminalId);
+                if (msg.id !== undefined)
+                    this.replyTo(fromClientId, resultFrame(msg.id, { ok: true }));
+                return;
+            }
+        }
+    }
+    onTerminalOutput(terminalId, data) {
+        const entry = this.terminals.get(terminalId);
+        if (!entry)
+            return;
+        const seq = ++entry.headSeq;
+        entry.buf.push({ seq, data });
+        if (entry.buf.length > TERM_RING)
+            entry.buf.shift();
+        const frame = { jsonrpc: "2.0", method: TERMINAL_METHODS.output, params: { terminalId, data, seq } };
+        for (const clientId of [...entry.subscribers]) {
+            const socket = this.conns.get(clientId)?.socket;
+            if (!socket || !socket.send(JSON.stringify(frame) + "\n"))
+                entry.subscribers.delete(clientId);
+        }
+    }
+    closeTerminal(terminalId) {
+        const entry = this.terminals.get(terminalId);
+        if (!entry)
+            return;
+        try {
+            entry.handle.close();
+        }
+        catch {
+            /* already exited */
+        }
+        this.terminals.delete(terminalId);
+    }
+    detachTerminals(clientId) {
+        for (const entry of this.terminals.values())
+            entry.subscribers.delete(clientId);
+    }
+    resubscribeTerminals(clientId, socket) {
+        for (const [id, entry] of this.terminals) {
+            if (entry.owner !== clientId)
+                continue;
+            entry.subscribers.add(clientId);
+            for (const f of entry.buf) {
+                socket.send(JSON.stringify({ jsonrpc: "2.0", method: TERMINAL_METHODS.output, params: { terminalId: id, data: f.data, seq: f.seq } }) + "\n");
+            }
+        }
+    }
+    // -- controller lease ---------------------------------------------------------
+    /** Lease gate for QUEUED commands (prompt, cancel, set_model, set_options,
+     *  permission answers). True ⇒ proceed; false ⇒ host-handled (handoff) or
+     *  rejected (`not_controller`). */
     gate(line, fromClientId) {
         if (!this.leaseEnabled)
-            return true; // default: fan-out, anyone drives
+            return true;
         const msg = tryParseMessage(line);
         if (!msg)
-            return true; // unparseable → let the driver reject it
-        // Handoff: any authed client may take control (single-user multi-device).
+            return true;
         if (msg.method === METHOD_TAKE_CONTROL) {
             if (fromClientId) {
                 this.holder = fromClientId;
                 this.controlEpoch++;
                 this.broadcastControlState();
-                if (msg.id !== undefined) {
-                    this.replyTo(fromClientId, { jsonrpc: "2.0", id: msg.id, result: { holder: this.holder, controlEpoch: this.controlEpoch } });
-                }
+                if (msg.id !== undefined)
+                    this.replyTo(fromClientId, resultFrame(msg.id, { holder: this.holder, controlEpoch: this.controlEpoch }));
             }
-            return false; // host-handled; never a driver command
+            return false;
         }
         if (!isPrivileged(msg))
-            return true; // read-only (initialize/get_state/ping) → viewers allowed
-        // Privileged (drive a turn / answer a permission / change model). Auto-claim
-        // an unheld lease for the first driver, then enforce the holder.
+            return true;
+        return this.requireController(msg, fromClientId);
+    }
+    /** Controller check for a PRIVILEGED command. True ⇒ allowed; false ⇒ rejected
+     *  (`not_controller` sent). Shared by {@link gate} AND the privileged off-ring
+     *  intercepts (apply_edit / terminal / session new+load) so none bypass the lease. */
+    requireController(msg, fromClientId) {
+        if (!this.leaseEnabled)
+            return true;
         if (this.holder === null && fromClientId) {
             this.holder = fromClientId;
             this.broadcastControlState();
         }
         if (fromClientId === undefined || fromClientId !== this.holder) {
             if (fromClientId !== undefined && msg.id !== undefined) {
-                this.replyTo(fromClientId, {
-                    jsonrpc: "2.0",
-                    id: msg.id,
-                    error: { code: NOT_CONTROLLER, message: "not the controller — a lease is active; take control first" },
-                });
+                this.replyTo(fromClientId, errorFrame(msg.id, NOT_CONTROLLER, "not the controller — a lease is active; take control first"));
             }
-            return false; // a stale command from a former holder lands here too (id ≠ holder)
+            return false;
         }
         return true;
     }
-    /** Broadcast the current lease state to every socket (stamped + fanned out). */
+    /** Connection-level broadcast: write `frame` to EVERY unit's hub (so it reaches
+     *  every socket regardless of active session). N=1 ⇒ the single hub ⇒ byte
+     *  identical to the pre-§14 single-hub `hub.write`. */
+    broadcastToAllUnits(frame) {
+        for (const unit of this.units.values())
+            unit.hub.write(frame);
+    }
     broadcastControlState() {
-        const frame = JSON.stringify({ jsonrpc: "2.0", method: METHOD_CONTROL_STATE, params: { lease: this.leaseEnabled, holder: this.holder, controlEpoch: this.controlEpoch } }) + "\n";
-        this.hub.write(frame);
+        this.broadcastToAllUnits(JSON.stringify({ jsonrpc: "2.0", method: METHOD_CONTROL_STATE, params: { lease: this.leaseEnabled, holder: this.holder, controlEpoch: this.controlEpoch } }) + "\n");
     }
-    /** Send a single frame to ONE client (targeted; not fanned out, not stamped). */
+    /** Send a single frame to ONE client's socket (targeted; not fanned, not stamped). */
     replyTo(clientId, obj) {
-        const socket = this.socketsByClient.get(clientId);
+        if (clientId === undefined)
+            return;
+        const socket = this.conns.get(clientId)?.socket;
         if (socket)
-            this.hub.sendTo(socket, JSON.stringify(obj) + "\n");
+            socket.send(JSON.stringify(obj) + "\n");
     }
+    // -- diagnostics (default-unit-scoped for N=1 back-compat) --------------------
     get headSeq() {
-        return this.hub.headSeq;
+        return this.units.get(this.defaultSessionId).hub.headSeq;
     }
     get socketCount() {
-        return this.hub.socketCount;
+        let n = 0;
+        for (const u of this.units.values())
+            n += u.hub.socketCount;
+        return n;
     }
     get busy() {
-        return this.driver.busy;
+        for (const u of this.units.values())
+            if (u.driver.busy)
+                return true;
+        return false;
     }
-    /** Current lease holder (clientId) or null. Exposed for tests/diagnostics. */
     get controllerHolder() {
         return this.holder;
     }
-    /** End the persistent queue → `run` returns → graceful driver shutdown. */
+    /** Number of live sessions (diagnostics/tests). */
+    get sessionCount() {
+        return this.units.size;
+    }
     async shutdown() {
         if (!this.shuttingDown) {
             this.shuttingDown = true;
-            this.queue.end();
+            for (const id of [...this.terminals.keys()])
+                this.closeTerminal(id);
+            for (const unit of this.units.values())
+                unit.queue.end();
+        }
+        // Await every unit's graceful driver shutdown, then dispose its services.
+        let code = 0;
+        for (const unit of this.units.values()) {
+            code = (await unit.done) || code;
+            await unit.dispose?.();
         }
-        return this.done;
+        return code;
     }
 }
 function frameLine(frame) {
     return JSON.stringify(frame) + "\n";
 }
+function resultFrame(id, result) {
+    return { jsonrpc: "2.0", id, result };
+}
+function errorObj(id, error) {
+    return { jsonrpc: "2.0", id, error };
+}
+function errorFrame(id, code, message) {
+    return { jsonrpc: "2.0", id, error: { code, message } };
+}
 function deadAttachment(epoch) {
     return { epoch, detach: () => { } };
 }
@@ -258,11 +653,10 @@ function tryParseMessage(line) {
         return null;
     }
 }
-/** A command that DRIVES the session (only the lease holder may send it): drive a
- *  turn, change the model/options, or ANSWER a permission (a JSON-RPC response —
- *  no method, an id, and a result/error). Read-only methods
- *  (initialize/session.new/get_state/get_models/ping) are NOT privileged so a
- *  viewer can still connect + observe. */
+/** A command that DRIVES a session (only the lease holder may send it). Read-only
+ *  methods (initialize/get_state/get_models/ping) are NOT privileged so a viewer
+ *  can connect + observe. session/new/load are handled by the router (which gates
+ *  them directly), so they are not listed here. */
 function isPrivileged(msg) {
     const m = msg.method;
     if (m === "session/prompt" || m === "session/cancel")