zcode-acp-server 0.2.0 → 0.3.1

package/dist/remote/hub-server.js

@@ -0,0 +1,346 @@
+/**
+ * zcode-acp-hub — machine-level singleton for remote access.
+ *
+ * The hub is the ONLY public entry point (the port a tunnel maps). It does
+ * exactly three things (ADR-0002): token auth, instance discovery, and
+ * byte-level WebSocket proxying from a remote client to one bridge's loopback
+ * ACP endpoint. It holds no session state and understands no ACP — a proxied
+ * connection stays bound to one instance for its whole lifetime.
+ *
+ * Bridges register via POST /api/register every 10s (the registration doubles
+ * as the heartbeat; entries older than the heartbeat TTL are pruned). A client
+ * that needs an immediately-honest list (e.g. a phone app's pull-to-refresh)
+ * passes ?probe=1 to /api/instances: the hub TCP-probes each registered
+ * loopback port and prunes unreachable bridges before answering — no periodic
+ * probing, the cost is paid only when someone refreshes. When no instance is
+ * registered and no proxy is active for `idleExitMs`, the hub exits — the
+ * next bridge re-spawns it on demand.
+ */
+import { createHash, timingSafeEqual } from "node:crypto";
+import { createServer } from "node:http";
+import net from "node:net";
+import { WebSocket, WebSocketServer } from "ws";
+import { AGENT_INFO, compareVersions, log, warn } from "../utils.js";
+const HEARTBEAT_TIMEOUT_MS = 30_000;
+const IDLE_EXIT_MS = 10 * 60_000;
+const PING_INTERVAL_MS = 30_000;
+/** Per-instance TCP probe timeout for /api/instances?probe=1. */
+const PROBE_TIMEOUT_MS = 500;
+const MAX_BODY_BYTES = 1024 * 1024;
+/** Constant-time token compare (hash both to equal length first). */
+function tokenEquals(a, b) {
+    const ha = createHash("sha256").update(a).digest();
+    const hb = createHash("sha256").update(b).digest();
+    return timingSafeEqual(ha, hb);
+}
+function authorized(req, url, token) {
+    const header = req.headers.authorization;
+    if (header?.startsWith("Bearer "))
+        return tokenEquals(header.slice(7), token);
+    const query = url.searchParams.get("token");
+    return query !== null && tokenEquals(query, token);
+}
+function setCors(res) {
+    // The web UI is deployed as a separate origin; the token is the boundary.
+    res.setHeader("Access-Control-Allow-Origin", "*");
+    res.setHeader("Access-Control-Allow-Methods", "GET, POST, OPTIONS");
+    res.setHeader("Access-Control-Allow-Headers", "Authorization, Content-Type");
+}
+async function readJson(req) {
+    const chunks = [];
+    let size = 0;
+    try {
+        // The async iterator rejects when the client aborts mid-body — a truncated
+        // POST must degrade to "invalid body", not reject into the event loop.
+        for await (const chunk of req) {
+            size += chunk.length;
+            if (size > MAX_BODY_BYTES)
+                return null;
+            chunks.push(chunk);
+        }
+        const parsed = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+        return typeof parsed === "object" && parsed !== null
+            ? parsed
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+function validSessions(raw) {
+    if (!Array.isArray(raw))
+        return null;
+    const out = [];
+    for (const s of raw) {
+        const rec = s;
+        if (typeof rec?.sessionId !== "string")
+            return null;
+        out.push({
+            sessionId: rec.sessionId,
+            ...(typeof rec.title === "string" ? { title: rec.title } : {}),
+            updatedAt: typeof rec.updatedAt === "number" ? rec.updatedAt : Date.now(),
+        });
+    }
+    return out;
+}
+/**
+ * TCP-probe a bridge's loopback endpoint. Loopback refusals are instant, so
+ * the timeout only guards pathological cases; a bare connect+destroy is
+ * harmless to the bridge's HTTP server.
+ */
+function portOpen(port, timeoutMs) {
+    return new Promise((resolve) => {
+        const socket = new net.Socket();
+        const done = (ok) => {
+            socket.destroy();
+            resolve(ok);
+        };
+        socket.setTimeout(timeoutMs);
+        socket.once("connect", () => done(true));
+        socket.once("timeout", () => done(false));
+        socket.once("error", () => done(false));
+        socket.connect(port, "127.0.0.1");
+    });
+}
+/**
+ * Start the hub. Resolves once listening; rejects on bind failure (including
+ * EADDRINUSE when another hub already owns the port).
+ */
+export function startHub(options) {
+    const { port, host, token, heartbeatTimeoutMs = HEARTBEAT_TIMEOUT_MS, idleExitMs = IDLE_EXIT_MS, pingIntervalMs = PING_INTERVAL_MS, onIdleExit, } = options;
+    const instances = new Map();
+    const proxyPairs = new Set();
+    const timers = [];
+    let idleSince = null;
+    const wss = new WebSocketServer({ noServer: true });
+    const server = createServer((req, res) => {
+        // Async handler failures (malformed URL, aborted body) must never escape
+        // into the event loop — warn and drop the connection.
+        void handleHttp(req, res).catch((e) => {
+            warn(`hub: request failed: ${e instanceof Error ? e.message : String(e)}`);
+            res.destroy();
+        });
+    });
+    server.on("upgrade", (req, socket, head) => {
+        const url = new URL(req.url ?? "/", "http://127.0.0.1");
+        if (url.pathname !== "/acp") {
+            socket.destroy();
+            return;
+        }
+        if (!authorized(req, url, token)) {
+            warn("hub: unauthorized WS upgrade rejected");
+            socket.destroy();
+            return;
+        }
+        const entry = instances.get(url.searchParams.get("instance") ?? "");
+        if (!entry) {
+            warn("hub: WS upgrade for unknown instance rejected");
+            socket.destroy();
+            return;
+        }
+        // Dial the bridge's loopback endpoint before accepting the client side,
+        // so a dead bridge fails the upgrade instead of half-opening a pipe.
+        const bridge = new WebSocket(`ws://127.0.0.1:${entry.port}/acp`);
+        bridge.once("open", () => {
+            wss.handleUpgrade(req, socket, head, (client) => startProxy(client, bridge));
+        });
+        bridge.once("error", (e) => {
+            warn(`hub: dial bridge :${entry.port} failed: ${e.message}`);
+            socket.destroy();
+        });
+    });
+    async function handleHttp(req, res) {
+        const url = new URL(req.url ?? "/", "http://127.0.0.1");
+        setCors(res);
+        if (req.method === "OPTIONS") {
+            res.writeHead(204);
+            res.end();
+            return;
+        }
+        if (url.pathname === "/api/health") {
+            res.writeHead(200, { "Content-Type": "text/plain" });
+            res.end("ok");
+            return;
+        }
+        if (url.pathname === "/api/instances" && req.method === "GET") {
+            if (!authorized(req, url, token)) {
+                res.writeHead(401, { "Content-Type": "text/plain" });
+                res.end("unauthorized");
+                return;
+            }
+            // On-demand liveness probe (?probe=1): verify every registered bridge's
+            // loopback port and prune the unreachable ones before answering, so a
+            // client refresh gets an honest list instead of waiting out the
+            // heartbeat TTL (hard-killed bridges never unregister).
+            if (["1", "true"].includes((url.searchParams.get("probe") ?? "").toLowerCase())) {
+                const probes = await Promise.all(Array.from(instances.entries(), async ([id, entry]) => ({
+                    id,
+                    ok: await portOpen(entry.port, PROBE_TIMEOUT_MS),
+                })));
+                for (const { id, ok } of probes) {
+                    if (!ok) {
+                        instances.delete(id);
+                        idleSince = null; // re-arm the idle clock on membership change
+                        log(`hub: pruned instance ${id} (probe: endpoint unreachable)`);
+                    }
+                }
+            }
+            const list = Array.from(instances.values())
+                .sort((a, b) => a.startedAt - b.startedAt)
+                .map((e) => ({
+                id: e.id,
+                port: e.port,
+                pid: e.pid,
+                startedAt: e.startedAt,
+                workspace: e.workspace,
+                sessions: e.sessions,
+            }));
+            res.writeHead(200, { "Content-Type": "application/json" });
+            res.end(JSON.stringify(list));
+            return;
+        }
+        if ((url.pathname === "/api/register" || url.pathname === "/api/unregister") &&
+            req.method === "POST") {
+            const body = await readJson(req);
+            if (!body || typeof body.token !== "string" || !tokenEquals(body.token, token)) {
+                res.writeHead(401, { "Content-Type": "text/plain" });
+                res.end("unauthorized");
+                return;
+            }
+            const id = typeof body.id === "string" ? body.id : "";
+            if (!id) {
+                res.writeHead(400, { "Content-Type": "text/plain" });
+                res.end("missing id");
+                return;
+            }
+            if (url.pathname === "/api/register") {
+                const bridgePort = typeof body.port === "number" ? body.port : 0;
+                const sessions = validSessions(body.sessions);
+                if (!(bridgePort >= 1 && bridgePort <= 65535) || !sessions) {
+                    res.writeHead(400, { "Content-Type": "text/plain" });
+                    res.end("invalid register payload");
+                    return;
+                }
+                const prev = instances.get(id);
+                instances.set(id, {
+                    id,
+                    port: bridgePort,
+                    pid: typeof body.pid === "number" ? body.pid : 0,
+                    startedAt: prev?.startedAt ?? Date.now(),
+                    workspace: typeof body.workspace === "string" ? body.workspace : "",
+                    sessions,
+                    lastSeen: Date.now(),
+                });
+            }
+            else {
+                instances.delete(id);
+                idleSince = null; // re-arm the idle clock on membership change
+            }
+            // Version self-upgrade: a bridge NEWER than this hub just registered,
+            // so this process is running stale code. Reply first (the bridge
+            // re-spawns the hub from its own, newer dist when it sees `restarting`),
+            // then exit. Equal/older/absent versions never trigger a restart.
+            const stale = url.pathname === "/api/register" &&
+                typeof body.version === "string" &&
+                compareVersions(body.version, AGENT_INFO.version) > 0;
+            res.writeHead(200, { "Content-Type": "application/json" });
+            res.end(JSON.stringify(stale ? { ok: true, restarting: true } : { ok: true }));
+            if (stale) {
+                log(`hub: bridge ${body.version} is newer than hub ${AGENT_INFO.version} — restarting to upgrade`);
+                const restart = setTimeout(() => {
+                    void close().finally(() => onIdleExit?.());
+                }, 500);
+                restart.unref();
+            }
+            return;
+        }
+        res.writeHead(404, { "Content-Type": "text/plain" });
+        res.end("not found");
+    }
+    function startProxy(client, bridge) {
+        const pair = { client, bridge };
+        proxyPairs.add(pair);
+        const teardown = () => {
+            if (!proxyPairs.delete(pair))
+                return;
+            client.close();
+            bridge.close();
+        };
+        // Forward with the frame's binary flag intact: `ws.send(buffer)` defaults
+        // to a BINARY frame, and the SDK's WS server drops non-text frames.
+        const forward = (to) => (data, isBinary) => {
+            if (to.readyState === WebSocket.OPEN)
+                to.send(data, { binary: isBinary });
+        };
+        client.on("message", forward(bridge));
+        bridge.on("message", forward(client));
+        client.on("close", teardown);
+        client.on("error", teardown);
+        bridge.on("close", teardown);
+        bridge.on("error", teardown);
+    }
+    // Prune instances whose bridge stopped heartbeating (crash or Zed exit).
+    const pruner = setInterval(() => {
+        const now = Date.now();
+        for (const [id, entry] of instances) {
+            if (now - entry.lastSeen > heartbeatTimeoutMs) {
+                instances.delete(id);
+                idleSince = null;
+                log(`hub: pruned instance ${id} (heartbeat timeout)`);
+            }
+        }
+    }, Math.min(heartbeatTimeoutMs / 2, 5_000));
+    pruner.unref();
+    timers.push(pruner);
+    // Keepalive pings on both legs — tunnels (notably Cloudflare) drop idle WS.
+    const pinger = setInterval(() => {
+        for (const { client, bridge } of proxyPairs) {
+            if (client.readyState === WebSocket.OPEN)
+                client.ping();
+            if (bridge.readyState === WebSocket.OPEN)
+                bridge.ping();
+        }
+    }, pingIntervalMs);
+    pinger.unref();
+    timers.push(pinger);
+    // Idle exit: with nothing registered and nobody proxied, the hub exits; the
+    // next bridge re-spawns it on demand (see endpoint.ts).
+    const idleCheck = setInterval(() => {
+        if (instances.size > 0 || proxyPairs.size > 0) {
+            idleSince = null;
+            return;
+        }
+        if (idleSince === null)
+            idleSince = Date.now();
+        if (Date.now() - idleSince >= idleExitMs) {
+            log("hub: idle for too long with no instances — exiting");
+            clearInterval(idleCheck);
+            void close().finally(() => onIdleExit?.());
+        }
+    }, Math.min(idleExitMs / 4, 10_000));
+    idleCheck.unref();
+    timers.push(idleCheck);
+    async function close() {
+        for (const t of timers)
+            clearInterval(t);
+        for (const { client, bridge } of proxyPairs) {
+            client.terminate();
+            bridge.terminate();
+        }
+        proxyPairs.clear();
+        wss.close();
+        server.closeAllConnections?.();
+        await new Promise((resolve) => server.close(() => resolve()));
+    }
+    return new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(port, host, () => {
+            // port 0 binds an ephemeral port — report the actual one (used by tests).
+            const addr = server.address();
+            const bound = typeof addr === "object" && addr !== null ? addr.port : port;
+            log(`hub: listening on ${host}:${bound} (instances: 0)`);
+            resolve({ port: bound, close });
+        });
+    });
+}
+//# sourceMappingURL=hub-server.js.map

package/dist/remote/hub-server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hub-server.js","sourceRoot":"","sources":["../../src/remote/hub-server.ts"],"names":[],"mappings":"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"}

package/dist/server.d.ts

@@ -9,6 +9,7 @@
 import type * as acp from "@agentclientprotocol/sdk";
 import { ZcodeBackend } from "./backend/index.js";
 import { BackgroundTaskListener } from "./handlers/background-tasks.js";
+import { ClientRegistry } from "./remote/broadcast.js";
 /** Client capabilities advertised in the initialize request. */
 export interface ClientCapabilities {
     fs?: {
@@ -72,6 +73,13 @@ export declare class ZcodeAcpServer {
          * passed through unchanged. */
         mcpServers?: acp.McpServer[];
     }>;
+    /**
+     * Session cwds (acp_sid → cwd), recorded at session/new and lazy-recovery.
+     * Unlike pendingSessions this survives materialization — the hub discovery
+     * payload needs a workspace label for live sessions, whose pending entries
+     * are deleted on first use.
+     */
+    readonly sessionCwds: Map<string, string>;
     /** Currently running turns, keyed by the ACP request id. */
     readonly pendingTurns: Map<number, PendingTurn>;
     /**
@@ -80,18 +88,44 @@ export declare class ZcodeAcpServer {
      * concurrent prompts from both missing each other and registering at once.
      */
     readonly preemptLocks: Map<string, Promise<void>>;
-    /** Capabilities advertised by the connected client (Zed, JetBrains, ...). */
+    /** Capabilities advertised by connected clients (Zed, JetBrains, remote). */
     clientCapabilities: ClientCapabilities;
     /**
-     * Connection-scoped AgentContext, captured at `connect()` time. Held so that
-     * background listeners can push `session/update` notifications OUTSIDE a
-     * request handler (e.g. when a background task completes after `session/
-     * prompt` has already returned). Null before `connect()` runs (only during
-     * the brief startup window — sessions can't be created before connect).
+     * All connected ACP clients (the stdio editor plus any remote WebSocket
+     * clients). Handlers push notifications through `clients.broadcast()` so
+     * every attached client sees the same stream; the registry replaces the old
+     * single `acpClient` reference. Background listeners use it to push
+     * `session/update` notifications outside request handlers.
+     */
+    readonly clients: ClientRegistry;
+    /**
+     * Lightweight session summaries for the remote hub's discovery API
+     * (acp_sid → { title, updatedAt, hasActivity }). In-memory only — the hub
+     * holds no business state and the bridge dies with its editor, so persistence
+     * would buy nothing. Maintained by `touchSessionSummary` at session
+     * registration, title set, and turn completion. `hasActivity` gates the
+     * discovery payload: an editor restart auto-resumes its stored placeholder,
+     * materializing an empty backend session — never-used sessions stay invisible
+     * to remote clients until first real use.
      */
-    acpClient: acp.AgentContext | null;
+    readonly sessionSummaries: Map<string, {
+        title?: string;
+        updatedAt: number;
+        hasActivity?: boolean;
+    }>;
     /** Session titles already set, to enforce set-once (acp_sid → title). */
     readonly sessionTitles: Map<string, string>;
+    /**
+     * Sessions verified as loaded in the CURRENT backend subprocess — populated
+     * only after a successful session/create or session/resume RPC. A bare
+     * `registerSession` mapping does NOT qualify: the backend answers
+     * `session/messages` only for sessions it has loaded, so `session/load`
+     * must not skip the resume RPC for a mapping that was never loaded (e.g.
+     * re-registered from the durable store by an early ensureRealSession
+     * caller, or left behind by a failed resume) — the replay would silently
+     * come back empty.
+     */
+    readonly backendLoadedSessions: Set<string>;
     /**
      * Sessions eligible for auto-title on first end_turn. Only `session/new`
      * populates this — resumed/loaded sessions already carry a title, so their
@@ -143,6 +177,19 @@ export declare class ZcodeAcpServer {
      * background-task listener needs the reverse lookup to address notifications).
      */
     registerSession(acpSid: string, zcodeSid: string): void;
+    /** Update a session's discovery summary (title sticky once set). */
+    touchSessionSummary(acpSid: string, title?: string): void;
+    /**
+     * Mark a session as having real interaction (a prompt turn ran, or history
+     * was replayed on load). Gates the hub discovery payload — never-used
+     * sessions stay invisible to remote clients until first use.
+     */
+    markSessionActive(acpSid: string): void;
+    /**
+     * Best-effort workspace label for the hub discovery payload: first known
+     * session cwd, else the bridge process cwd.
+     */
+    workspaceLabel(): string;
     /**
      * Ensure a background-task listener is registered for the session. Idempotent
      * — returns the existing listener if already registered (covers resume/load
@@ -171,6 +218,14 @@ export declare class ZcodeAcpServer {
      * `session/request_permission`.
      */
     supportsElicitationForm(): boolean;
+    /**
+     * OR-merge capabilities from a newly connected client. Each connection runs
+     * its own `initialize`; boolean capabilities are unioned across clients so a
+     * feature advertised by ANY attached client (Zed or a remote one) enables the
+     * richer interaction path, and `_meta` flags (e.g. terminal_output) merge
+     * shallowly. Idempotent for re-connecting clients with equal capabilities.
+     */
+    mergeClientCapabilities(caps: ClientCapabilities): void;
     /** Handle `initialize`: negotiate version + declare agent capabilities. */
     initialize(params: acp.InitializeRequest): Promise<acp.InitializeResponse>;
 }

package/dist/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"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"}

package/dist/server.js

@@ -8,6 +8,8 @@
  */
 import { loadZcodeCredentials, mergeEnvWithCreds, resolveZcodeCommand, ZcodeBackend, } from "./backend/index.js";
 import { BackgroundTaskListener } from "./handlers/background-tasks.js";
+import { enqueueSessionSend } from "./handlers/io.js";
+import { ClientRegistry } from "./remote/broadcast.js";
 import { AGENT_INFO, PROTOCOL_VERSION, log } from "./utils.js";
 export class ZcodeAcpServer {
     /** The ZCode subprocess client (lazy — spawned on first use). */
@@ -35,6 +37,13 @@ export class ZcodeAcpServer {
      * share one `session/create` instead of creating two backend sessions.
      */
     pendingSessions = new Map();
+    /**
+     * Session cwds (acp_sid → cwd), recorded at session/new and lazy-recovery.
+     * Unlike pendingSessions this survives materialization — the hub discovery
+     * payload needs a workspace label for live sessions, whose pending entries
+     * are deleted on first use.
+     */
+    sessionCwds = new Map();
     /** Currently running turns, keyed by the ACP request id. */
     pendingTurns = new Map();
     /**
@@ -43,18 +52,40 @@ export class ZcodeAcpServer {
      * concurrent prompts from both missing each other and registering at once.
      */
     preemptLocks = new Map();
-    /** Capabilities advertised by the connected client (Zed, JetBrains, ...). */
+    /** Capabilities advertised by connected clients (Zed, JetBrains, remote). */
     clientCapabilities = {};
     /**
-     * Connection-scoped AgentContext, captured at `connect()` time. Held so that
-     * background listeners can push `session/update` notifications OUTSIDE a
-     * request handler (e.g. when a background task completes after `session/
-     * prompt` has already returned). Null before `connect()` runs (only during
-     * the brief startup window — sessions can't be created before connect).
+     * All connected ACP clients (the stdio editor plus any remote WebSocket
+     * clients). Handlers push notifications through `clients.broadcast()` so
+     * every attached client sees the same stream; the registry replaces the old
+     * single `acpClient` reference. Background listeners use it to push
+     * `session/update` notifications outside request handlers.
      */
-    acpClient = null;
+    clients = new ClientRegistry();
+    /**
+     * Lightweight session summaries for the remote hub's discovery API
+     * (acp_sid → { title, updatedAt, hasActivity }). In-memory only — the hub
+     * holds no business state and the bridge dies with its editor, so persistence
+     * would buy nothing. Maintained by `touchSessionSummary` at session
+     * registration, title set, and turn completion. `hasActivity` gates the
+     * discovery payload: an editor restart auto-resumes its stored placeholder,
+     * materializing an empty backend session — never-used sessions stay invisible
+     * to remote clients until first real use.
+     */
+    sessionSummaries = new Map();
     /** Session titles already set, to enforce set-once (acp_sid → title). */
     sessionTitles = new Map();
+    /**
+     * Sessions verified as loaded in the CURRENT backend subprocess — populated
+     * only after a successful session/create or session/resume RPC. A bare
+     * `registerSession` mapping does NOT qualify: the backend answers
+     * `session/messages` only for sessions it has loaded, so `session/load`
+     * must not skip the resume RPC for a mapping that was never loaded (e.g.
+     * re-registered from the durable store by an early ensureRealSession
+     * caller, or left behind by a failed resume) — the replay would silently
+     * come back empty.
+     */
+    backendLoadedSessions = new Set();
     /**
      * Sessions eligible for auto-title on first end_turn. Only `session/new`
      * populates this — resumed/loaded sessions already carry a title, so their
@@ -119,6 +150,38 @@ export class ZcodeAcpServer {
     registerSession(acpSid, zcodeSid) {
         this.sessionMap.set(acpSid, zcodeSid);
         this.acpSidByZcodeSid.set(zcodeSid, acpSid);
+        this.touchSessionSummary(acpSid);
+    }
+    /** Update a session's discovery summary (title sticky once set). */
+    touchSessionSummary(acpSid, title) {
+        const existing = this.sessionSummaries.get(acpSid);
+        this.sessionSummaries.set(acpSid, {
+            title: title ?? existing?.title,
+            updatedAt: Date.now(),
+            // A title only exists once the session produced content (auto-title on
+            // first end_turn, or a stored title adopted on resume/load).
+            hasActivity: existing?.hasActivity || title !== undefined,
+        });
+    }
+    /**
+     * Mark a session as having real interaction (a prompt turn ran, or history
+     * was replayed on load). Gates the hub discovery payload — never-used
+     * sessions stay invisible to remote clients until first use.
+     */
+    markSessionActive(acpSid) {
+        const existing = this.sessionSummaries.get(acpSid);
+        this.sessionSummaries.set(acpSid, {
+            title: existing?.title,
+            updatedAt: Date.now(),
+            hasActivity: true,
+        });
+    }
+    /**
+     * Best-effort workspace label for the hub discovery payload: first known
+     * session cwd, else the bridge process cwd.
+     */
+    workspaceLabel() {
+        return this.sessionCwds.values().next().value ?? process.cwd();
     }
     /**
      * Ensure a background-task listener is registered for the session. Idempotent
@@ -151,14 +214,16 @@ export class ZcodeAcpServer {
      * the bridge on a notification failure.
      */
     async notifyByZcodeSid(zcodeSid, update) {
-        const cx = this.acpClient;
-        if (!cx)
+        if (this.clients.size === 0)
             return false;
         const acpSid = this.resolveAcpSid(zcodeSid);
         if (!acpSid)
             return false;
         try {
-            await cx.notify("session/update", { sessionId: acpSid, update });
+            // Broadcast notify swallows per-client failures internally (warn only).
+            // Serialized through the replay guard so a background emission queues
+            // behind an in-flight replay batch for the same session.
+            await enqueueSessionSend(acpSid, () => this.clients.broadcast().notify("session/update", { sessionId: acpSid, update }));
             return true;
         }
         catch (e) {
@@ -180,10 +245,33 @@ export class ZcodeAcpServer {
     supportsElicitationForm() {
         return this.clientCapabilities.elicitation?.form != null;
     }
+    /**
+     * OR-merge capabilities from a newly connected client. Each connection runs
+     * its own `initialize`; boolean capabilities are unioned across clients so a
+     * feature advertised by ANY attached client (Zed or a remote one) enables the
+     * richer interaction path, and `_meta` flags (e.g. terminal_output) merge
+     * shallowly. Idempotent for re-connecting clients with equal capabilities.
+     */
+    mergeClientCapabilities(caps) {
+        const cur = this.clientCapabilities;
+        const next = { ...cur, ...caps };
+        next.fs = {
+            readTextFile: cur.fs?.readTextFile || caps.fs?.readTextFile,
+            writeTextFile: cur.fs?.writeTextFile || caps.fs?.writeTextFile,
+        };
+        next.terminal = cur.terminal || caps.terminal;
+        next.elicitation = {
+            form: cur.elicitation?.form || caps.elicitation?.form,
+            url: cur.elicitation?.url || caps.elicitation?.url,
+        };
+        if (cur._meta || caps._meta)
+            next._meta = { ...cur._meta, ...caps._meta };
+        this.clientCapabilities = next;
+    }
     /** Handle `initialize`: negotiate version + declare agent capabilities. */
     async initialize(params) {
         const clientInfo = params.clientInfo ?? null;
-        this.clientCapabilities = params.clientCapabilities ?? {};
+        this.mergeClientCapabilities(params.clientCapabilities ?? {});
         log(`initialize: client protocolVersion=${params.protocolVersion}` +
             `, client=${clientInfo?.name ?? "unknown"}` +
             `, version=${clientInfo?.version ?? "unknown"}` +