@wrongstack/acp 0.296.4 → 0.298.0

package/dist/index.js

@@ -1,3 +1,8 @@
+// src/agent/protocol-handler.ts
+import { randomUUID } from "node:crypto";
+import * as fsp from "node:fs/promises";
+import * as path from "node:path";
+
 // src/types/acp-v1.ts
 var ACP_PROTOCOL_VERSION = 1;
 function assertNeverSessionUpdate(x) {
@@ -92,12 +97,12 @@ var ACPProtocolHandler = class {
    */
   request(method, params, timeoutMs = 6e4) {
     const id = `srv_${this.nextOutId++}`;
-    return new Promise((resolve3, reject) => {
+    return new Promise((resolve4, reject) => {
       const timer = setTimeout(() => {
         this.pendingOut.delete(id);
         reject(new Error(`${method} timed out after ${timeoutMs}ms`));
       }, timeoutMs);
-      this.pendingOut.set(id, { resolve: resolve3, reject, timer });
+      this.pendingOut.set(id, { resolve: resolve4, reject, timer });
       this.transport.send(toWire({ jsonrpc: "2.0", id, method, params })).catch((e) => {
         clearTimeout(timer);
         this.pendingOut.delete(id);
@@ -214,62 +219,68 @@ var ACPProtocolHandler = class {
       this.clientCapabilities = p.clientCapabilities;
     }
     this.initialized = true;
-    await this.transport.send(toWire({
-      jsonrpc: "2.0",
-      id,
-      result: {
-        protocolVersion: ACP_PROTOCOL_VERSION,
-        agentCapabilities: {
-          loadSession: true,
-          promptCapabilities: {
-            // We route ACP image blocks into the core agent's multimodal
-            // input (server-agent-turn.promptToAgentInput); whether the
-            // model can see them is the configured provider's concern.
-            image: true,
-            audio: false,
-            embeddedContext: true
-          },
-          mcpCapabilities: {
-            http: false,
-            sse: false
+    await this.transport.send(
+      toWire({
+        jsonrpc: "2.0",
+        id,
+        result: {
+          protocolVersion: ACP_PROTOCOL_VERSION,
+          agentCapabilities: {
+            loadSession: true,
+            promptCapabilities: {
+              // We route ACP image blocks into the core agent's multimodal
+              // input (server-agent-turn.promptToAgentInput); whether the
+              // model can see them is the configured provider's concern.
+              image: true,
+              audio: false,
+              embeddedContext: true
+            },
+            mcpCapabilities: {
+              http: false,
+              sse: false
+            },
+            sessionCapabilities: {
+              close: {},
+              list: {},
+              delete: {},
+              resume: {},
+              fork: {}
+            },
+            auth: {
+              logout: {}
+            }
           },
-          sessionCapabilities: {
-            close: {},
-            list: {},
-            delete: {},
-            resume: {},
-            fork: {}
+          agentInfo: {
+            name: this.agentName,
+            title: "WrongStack",
+            version: WRONGSTACK_VERSION
           },
-          auth: {
-            logout: {}
-          }
-        },
-        agentInfo: {
-          name: this.agentName,
-          title: "WrongStack",
-          version: WRONGSTACK_VERSION
-        },
-        authMethods: WRONGSTACK_AUTH_METHODS,
-        modes: this.modes,
-        configOptions: this.configOptions
-      }
-    }));
+          authMethods: WRONGSTACK_AUTH_METHODS,
+          modes: this.modes,
+          configOptions: this.configOptions
+        }
+      })
+    );
     return false;
   }
   async handleAuthenticate(id, _params) {
-    await this.transport.send(toWire({
-      jsonrpc: "2.0",
-      id,
-      result: { outcome: "unauthenticated" }
-    }));
+    await this.transport.send(
+      toWire({
+        jsonrpc: "2.0",
+        id,
+        result: { outcome: "unauthenticated" }
+      })
+    );
     return false;
   }
   async handleLogout(id, _params) {
-    await this.transport.send(toWire({
-      jsonrpc: "2.0",
-      id,
-      result: {}
-    }));
+    await this.transport.send(
+      toWire({
+        jsonrpc: "2.0",
+        id,
+        result: {}
+      })
+    );
     return false;
   }
   async handleSessionNew(id, params) {
@@ -278,7 +289,15 @@ var ACPProtocolHandler = class {
       return false;
     }
     const p = params ?? {};
-    const cwd = typeof p.cwd === "string" ? p.cwd : this.defaultCwd;
+    let cwd = this.defaultCwd;
+    if (typeof p.cwd === "string") {
+      const resolved = await this.resolveSessionCwd(p.cwd);
+      if (resolved === null) {
+        await this.sendError(id, -32602, `cwd must be an absolute path to an existing directory`);
+        return false;
+      }
+      cwd = resolved;
+    }
     const sessionId = `sess_${this.allocId()}`;
     const now = (/* @__PURE__ */ new Date()).toISOString();
     const state = {
@@ -308,15 +327,17 @@ var ACPProtocolHandler = class {
         }
       });
     }
-    await this.transport.send(toWire({
-      jsonrpc: "2.0",
-      id,
-      result: {
-        sessionId,
-        modes: this.modes,
-        configOptions: this.configOptions
-      }
-    }));
+    await this.transport.send(
+      toWire({
+        jsonrpc: "2.0",
+        id,
+        result: {
+          sessionId,
+          modes: this.modes,
+          configOptions: this.configOptions
+        }
+      })
+    );
     return false;
   }
   async handleSessionLoad(id, params) {
@@ -331,9 +352,15 @@ var ACPProtocolHandler = class {
           await this.sendError(id, -32e3, `active session limit reached (${this.maxSessions})`);
           return false;
         }
+        if (loadCwd !== void 0 && await this.resolveSessionCwd(loadCwd) === null) {
+          await this.sendError(id, -32602, `cwd must be an absolute path to an existing directory`);
+          return false;
+        }
+        const candidateCwd = persisted.cwd ?? loadCwd ?? this.defaultCwd;
+        const restoredCwd = await this.resolveSessionCwd(candidateCwd) ?? this.defaultCwd;
         const restored = {
           id: sessionId,
-          cwd: persisted.cwd ?? loadCwd ?? this.defaultCwd,
+          cwd: restoredCwd,
           abort: new AbortController(),
           modeId: persisted.modeId ?? DEFAULT_MODE_ID,
           createdAt: persisted.createdAt ?? (/* @__PURE__ */ new Date()).toISOString(),
@@ -349,13 +376,15 @@ var ACPProtocolHandler = class {
           sessionId,
           update: { sessionUpdate: "current_mode_update", modeId: restored.modeId }
         });
-        await this.transport.send(toWire({
-          jsonrpc: "2.0",
-          id,
-          result: {
-            initialMode: { currentModeId: restored.modeId, availableModes: this.modes }
-          }
-        }));
+        await this.transport.send(
+          toWire({
+            jsonrpc: "2.0",
+            id,
+            result: {
+              initialMode: { currentModeId: restored.modeId, availableModes: this.modes }
+            }
+          })
+        );
         return false;
       }
     }
@@ -381,16 +410,18 @@ var ACPProtocolHandler = class {
           modeId: existing.modeId
         }
       });
-      await this.transport.send(toWire({
-        jsonrpc: "2.0",
-        id,
-        result: {
-          initialMode: {
-            currentModeId: existing.modeId,
-            availableModes: this.modes
+      await this.transport.send(
+        toWire({
+          jsonrpc: "2.0",
+          id,
+          result: {
+            initialMode: {
+              currentModeId: existing.modeId,
+              availableModes: this.modes
+            }
           }
-        }
-      }));
+        })
+      );
       return false;
     }
     await this.sendError(id, -32e3, `session not found: ${sessionId}`);
@@ -402,16 +433,18 @@ var ACPProtocolHandler = class {
     const existing = sessionId ? this.sessions.get(sessionId) : void 0;
     if (existing) {
       existing.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
-      await this.transport.send(toWire({
-        jsonrpc: "2.0",
-        id,
-        result: {
-          initialMode: {
-            currentModeId: existing.modeId,
-            availableModes: this.modes
+      await this.transport.send(
+        toWire({
+          jsonrpc: "2.0",
+          id,
+          result: {
+            initialMode: {
+              currentModeId: existing.modeId,
+              availableModes: this.modes
+            }
           }
-        }
-      }));
+        })
+      );
       return false;
     }
     await this.sendError(id, -32e3, `session not found: ${sessionId}`);
@@ -428,11 +461,13 @@ var ACPProtocolHandler = class {
     session.abort.abort();
     this.sessions.delete(sessionId);
     this.disposeSession(sessionId);
-    await this.transport.send(toWire({
-      jsonrpc: "2.0",
-      id,
-      result: {}
-    }));
+    await this.transport.send(
+      toWire({
+        jsonrpc: "2.0",
+        id,
+        result: {}
+      })
+    );
     return false;
   }
   async handleSessionDelete(id, params) {
@@ -443,18 +478,22 @@ var ACPProtocolHandler = class {
       return false;
     }
     if (!this.sessions.has(sessionId)) {
-      await this.transport.send(toWire({ jsonrpc: "2.0", id, result: { configOptions: [...this.configOptions] } }));
+      await this.transport.send(
+        toWire({ jsonrpc: "2.0", id, result: { configOptions: [...this.configOptions] } })
+      );
       return false;
     }
     const session = this.sessions.get(sessionId);
     session.abort.abort();
     this.sessions.delete(sessionId);
     this.disposeSession(sessionId);
-    await this.transport.send(toWire({
-      jsonrpc: "2.0",
-      id,
-      result: {}
-    }));
+    await this.transport.send(
+      toWire({
+        jsonrpc: "2.0",
+        id,
+        result: {}
+      })
+    );
     return false;
   }
   async handleSessionFork(id, params) {
@@ -469,11 +508,20 @@ var ACPProtocolHandler = class {
       await this.sendError(id, -32e3, `active session limit reached (${this.maxSessions})`);
       return false;
     }
+    let forkCwd = source.cwd;
+    if (typeof p.cwd === "string") {
+      const resolved = await this.resolveSessionCwd(p.cwd);
+      if (resolved === null) {
+        await this.sendError(id, -32602, `cwd must be an absolute path to an existing directory`);
+        return false;
+      }
+      forkCwd = resolved;
+    }
     const now = (/* @__PURE__ */ new Date()).toISOString();
     const sessionId = `sess_${this.allocId()}`;
     const forked = {
       id: sessionId,
-      cwd: typeof p.cwd === "string" ? p.cwd : source.cwd,
+      cwd: forkCwd,
       abort: new AbortController(),
       modeId: source.modeId,
       createdAt: now,
@@ -492,38 +540,48 @@ var ACPProtocolHandler = class {
       sessionId,
       update: { sessionUpdate: "current_mode_update", modeId: forked.modeId }
     });
-    await this.transport.send(toWire({
-      jsonrpc: "2.0",
-      id,
-      result: {
-        sessionId,
-        modes: this.modes,
-        configOptions: this.configOptions
-      }
-    }));
+    await this.transport.send(
+      toWire({
+        jsonrpc: "2.0",
+        id,
+        result: {
+          sessionId,
+          modes: this.modes,
+          configOptions: this.configOptions
+        }
+      })
+    );
     return false;
   }
   async handleProvidersList(id, _params) {
-    await this.transport.send(toWire({
-      jsonrpc: "2.0",
-      id,
-      result: {
-        providers: [],
-        currentProviderId: null
-      }
-    }));
+    await this.transport.send(
+      toWire({
+        jsonrpc: "2.0",
+        id,
+        result: {
+          providers: [],
+          currentProviderId: null
+        }
+      })
+    );
     return false;
   }
   async handleProvidersSet(id, _params) {
-    await this.sendError(id, -32e3, "provider configuration not available through ACP; use wstack auth");
+    await this.sendError(
+      id,
+      -32e3,
+      "provider configuration not available through ACP; use wstack auth"
+    );
     return false;
   }
   async handleProvidersDisable(id, _params) {
-    await this.transport.send(toWire({
-      jsonrpc: "2.0",
-      id,
-      result: {}
-    }));
+    await this.transport.send(
+      toWire({
+        jsonrpc: "2.0",
+        id,
+        result: {}
+      })
+    );
     return false;
   }
   async handleMcpMessage(id, _params) {
@@ -576,7 +634,10 @@ var ACPProtocolHandler = class {
         const terminalId = created?.terminalId;
         if (!terminalId) return { output: "", exitCode: null };
         try {
-          const exit = await this.request("terminal/wait_for_exit", { sessionId, terminalId });
+          const exit = await this.request("terminal/wait_for_exit", {
+            sessionId,
+            terminalId
+          });
           const out = await this.request("terminal/output", { sessionId, terminalId });
           return {
             output: String(out?.output ?? ""),
@@ -606,11 +667,13 @@ var ACPProtocolHandler = class {
     session.abort.signal.removeEventListener("abort", onCancel);
     session.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
     await this.persist(session);
-    await this.transport.send(toWire({
-      jsonrpc: "2.0",
-      id,
-      result: { stopReason: result.stopReason }
-    }));
+    await this.transport.send(
+      toWire({
+        jsonrpc: "2.0",
+        id,
+        result: { stopReason: result.stopReason }
+      })
+    );
     return false;
   }
   async handleSetMode(id, params) {
@@ -651,7 +714,9 @@ var ACPProtocolHandler = class {
         configOptions: [...this.configOptions]
       }
     });
-    await this.transport.send(toWire({ jsonrpc: "2.0", id, result: { configOptions: [...this.configOptions] } }));
+    await this.transport.send(
+      toWire({ jsonrpc: "2.0", id, result: { configOptions: [...this.configOptions] } })
+    );
     return false;
   }
   async handleSessionList(id) {
@@ -664,11 +729,13 @@ var ACPProtocolHandler = class {
       if (s.title !== void 0) out.title = s.title;
       return out;
     });
-    await this.transport.send(toWire({
-      jsonrpc: "2.0",
-      id,
-      result: { sessions }
-    }));
+    await this.transport.send(
+      toWire({
+        jsonrpc: "2.0",
+        id,
+        result: { sessions }
+      })
+    );
     return false;
   }
   // ────────────────────────────────────────────────────────────────────
@@ -714,8 +781,54 @@ var ACPProtocolHandler = class {
     if (data !== void 0) error.data = data;
     await this.transport.send(toWire({ jsonrpc: "2.0", id, error }));
   }
+  /**
+   * Allocate a session id (WS-015).
+   *
+   * This was `this.nextId++`, so ids were `sess_1`, `sess_2`, … — and the
+   * handler has no per-connection ownership: any caller that names a session
+   * id can `session/load`, `session/prompt`, `session/cancel` or
+   * `session/delete` it. Over stdio that is academic (one client per process),
+   * but the agent also serves over HTTP, where a guessable id is the whole
+   * authorization story for any local process or page that reaches the port.
+   *
+   * Random ids do not create ownership — they remove the trivial enumeration
+   * that made its absence exploitable. Real per-connection ownership is the
+   * larger fix and is noted in the WS-015 test file.
+   *
+   * The counter is retained: it keeps ids ordered for debugging and guarantees
+   * uniqueness within a process even in the (impossible) event of a UUID
+   * collision. The random half is what makes the id unguessable.
+   */
+  /**
+   * Resolve a client-supplied `cwd` for a session, or `null` when it is not
+   * usable (WS-015).
+   *
+   * `session/new`, `session/load` and `session/fork` all took `params.cwd`
+   * with a single `typeof === 'string'` check and nothing else. That value is
+   * the working directory the agent then reads, writes and executes in.
+   *
+   * SCOPE, deliberately stated: this does NOT confine the session to a root.
+   * In ACP the client IS the editor and legitimately names its own workspace —
+   * Zed and JetBrains pass the project root — so a fixed boundary here would
+   * break the integration this package exists for. What it enforces is that
+   * the directory is absolute and actually exists as a directory: a relative
+   * or missing `cwd` is a bug or an attack under either reading, and silently
+   * running the agent somewhere other than where the client asked is worse
+   * than refusing. Confinement, if wanted, belongs in an operator-set option
+   * on top of this, not in place of it.
+   */
+  async resolveSessionCwd(requested) {
+    if (!path.isAbsolute(requested)) return null;
+    const resolved = path.resolve(requested);
+    try {
+      const stat3 = await fsp.stat(resolved);
+      return stat3.isDirectory() ? resolved : null;
+    } catch {
+      return null;
+    }
+  }
   allocId() {
-    return this.nextId++;
+    return `${this.nextId++}_${randomUUID().replaceAll("-", "")}`;
   }
 };
 function errorToJsonRpc(err) {
@@ -739,32 +852,14 @@ import { expectDefined, writeErr } from "@wrongstack/core/utils";
 import { treeKill } from "@wrongstack/core/utils/tree-kill";
 
 // src/win32-cmd.ts
-var WIN32_CMD_META = /[&|<>"\r\n\0]/;
-function buildWin32CmdShimInvocation(command, args = []) {
-  assertSafeWin32CmdArgs([command, ...args]);
-  const line = ["call", quoteWin32CmdArg(command), ...args.map(quoteWin32CmdArg)].join(" ");
-  return {
-    command: process.env["COMSPEC"] ?? "cmd.exe",
-    args: ["/d", "/c", line],
-    windowsVerbatimArguments: true
-  };
-}
-function assertSafeWin32CmdArgs(args) {
-  for (const arg of args) {
-    if (typeof arg === "string" && WIN32_CMD_META.test(arg)) {
-      throw new Error(
-        'win32 cmd shim spawn: argument contains a shell metacharacter (one of & | < > ", or a newline) that could enable command injection through the .cmd/.bat wrapper - refusing to run. Offending argument: ' + JSON.stringify(arg)
-      );
-    }
-  }
-}
-function quoteWin32CmdArg(arg) {
-  return `"${arg}"`;
-}
+import {
+  buildWin32CmdShimInvocation
+} from "@wrongstack/core/utils";
 
 // src/agent/stdio-transport.ts
 var DEFAULT_MAX_FRAME_CHARS = 20 * 1024 * 1024;
 var DEFAULT_MAX_QUEUED_MESSAGES = 1e3;
+var DEFAULT_MAX_QUEUED_CHARS = 32 * 1024 * 1024;
 function positiveLimit(value, fallback) {
   return value !== void 0 && Number.isFinite(value) && value > 0 ? Math.floor(value) : fallback;
 }
@@ -774,53 +869,82 @@ var StdioTransport = class {
   stderr = process.stderr;
   buffer = "";
   handlers = /* @__PURE__ */ new Set();
+  claimHandlers = /* @__PURE__ */ new Set();
   closed = false;
   resolveRead = null;
   messageQueue = [];
+  queuedChars = 0;
   maxFrameChars;
   maxQueuedMessages;
+  maxQueuedChars;
+  onStdinData = (chunk) => this.onData(chunk);
+  onStdinEnd = () => this.handleClose();
+  onStdinError = (err) => this.failAll(err);
   constructor(opts = {}) {
     this.maxFrameChars = positiveLimit(opts.maxFrameChars, DEFAULT_MAX_FRAME_CHARS);
     this.maxQueuedMessages = positiveLimit(opts.maxQueuedMessages, DEFAULT_MAX_QUEUED_MESSAGES);
+    this.maxQueuedChars = positiveLimit(opts.maxQueuedChars, DEFAULT_MAX_QUEUED_CHARS);
     this.stdin.resume();
     this.stdin.setEncoding("utf8");
-    this.stdin.on("data", (chunk) => this.onData(chunk));
-    this.stdin.on("end", () => this.handleClose());
-    this.stdin.on("error", (err) => this.failAll(err));
+    this.stdin.on("data", this.onStdinData);
+    this.stdin.on("end", this.onStdinEnd);
+    this.stdin.on("error", this.onStdinError);
   }
   sendStartupMarker() {
     this.stdout.write("[wstack-acp]\n", "utf8");
   }
   send(msg) {
     if (this.closed) return Promise.resolve();
-    return new Promise((resolve3) => {
+    return new Promise((resolve4) => {
       const line = JSON.stringify(msg) + "\n";
-      this.stdout.write(line, "utf8", () => resolve3());
+      this.stdout.write(line, "utf8", () => resolve4());
     });
   }
   sendRaw(chunk) {
     this.stdout.write(chunk, "utf8");
   }
   read() {
-    if (this.messageQueue.length > 0)
-      return Promise.resolve(expectDefined(this.messageQueue.shift()));
+    if (this.messageQueue.length > 0) {
+      const queued = expectDefined(this.messageQueue.shift());
+      this.queuedChars = Math.max(0, this.queuedChars - queued.chars);
+      return Promise.resolve(queued.message);
+    }
     if (this.closed) return Promise.resolve(null);
-    return new Promise((resolve3) => {
-      this.resolveRead = resolve3;
+    return new Promise((resolve4) => {
+      this.resolveRead = resolve4;
     });
   }
   onMessage(handler) {
     this.handlers.add(handler);
     return () => this.handlers.delete(handler);
   }
+  /**
+   * Register a handler that MAY claim a message by returning `true`.
+   * Claimed messages are NOT enqueued for the read() loop — they are
+   * considered fully consumed by the handler. This is how the ACP
+   * server transport prevents the correlation handler (which always
+   * fires on every message but only actually correlates responses)
+   * from starving the read() loop of pipelined requests, notifications,
+   * and any message the handler chose to ignore. See dispatch() for
+   * the gating logic.
+   */
+  onMessageClaim(handler) {
+    this.claimHandlers.add(handler);
+    return () => this.claimHandlers.delete(handler);
+  }
   close() {
     this.closed = true;
+    this.stdin.off("data", this.onStdinData);
+    this.stdin.off("end", this.onStdinEnd);
+    this.stdin.off("error", this.onStdinError);
     this.stdin.pause();
     this.resolveRead?.(null);
     this.resolveRead = null;
     this.buffer = "";
     this.messageQueue.length = 0;
+    this.queuedChars = 0;
     this.handlers.clear();
+    this.claimHandlers.clear();
   }
   onData(chunk) {
     this.buffer += chunk;
@@ -847,29 +971,41 @@ var StdioTransport = class {
         return;
       }
       try {
-        this.dispatch(JSON.parse(raw));
+        this.dispatch(JSON.parse(raw), raw.length);
       } catch (err) {
         this.stderr.write(`[wstack-acp parse error] ${err}
 `, "utf8");
       }
     }
   }
-  dispatch(msg) {
+  dispatch(msg, chars = JSON.stringify(msg).length) {
     if (this.resolveRead) {
-      const resolve3 = this.resolveRead;
+      const resolve4 = this.resolveRead;
       this.resolveRead = null;
-      resolve3(msg);
+      resolve4(msg);
     } else {
-      if (this.messageQueue.length >= this.maxQueuedMessages) {
-        this.stderr.write(
-          `[wstack-acp queue error] pending message queue exceeds ${this.maxQueuedMessages} entries
+      let claimed = false;
+      for (const handler of this.claimHandlers) {
+        try {
+          if (handler(msg)) claimed = true;
+        } catch (err) {
+          this.stderr.write(`[wstack-acp handler error] ${err}
+`, "utf8");
+        }
+      }
+      if (!claimed) {
+        if (this.messageQueue.length >= this.maxQueuedMessages || this.queuedChars + chars > this.maxQueuedChars) {
+          this.stderr.write(
+            `[wstack-acp queue error] pending message queue exceeds ${this.maxQueuedMessages} entries or ${this.maxQueuedChars} characters
 `,
-          "utf8"
-        );
-        this.close();
-        return;
+            "utf8"
+          );
+          this.close();
+          return;
+        }
+        this.messageQueue.push({ message: msg, chars });
+        this.queuedChars += chars;
       }
-      this.messageQueue.push(msg);
     }
     for (const handler of this.handlers) {
       try {
@@ -893,12 +1029,15 @@ var ClientTransport = class {
   child = null;
   buffer = "";
   handlers = /* @__PURE__ */ new Set();
+  claimHandlers = /* @__PURE__ */ new Set();
   closed = false;
   resolveRead = null;
   messageQueue = [];
+  queuedChars = 0;
   opts;
   maxFrameChars;
   maxQueuedMessages;
+  maxQueuedChars;
   constructor(options) {
     this.opts = {
       handshakeTimeoutMs: 3e4,
@@ -906,6 +1045,7 @@ var ClientTransport = class {
     };
     this.maxFrameChars = positiveLimit(options.maxFrameChars, DEFAULT_MAX_FRAME_CHARS);
     this.maxQueuedMessages = positiveLimit(options.maxQueuedMessages, DEFAULT_MAX_QUEUED_MESSAGES);
+    this.maxQueuedChars = positiveLimit(options.maxQueuedChars, DEFAULT_MAX_QUEUED_CHARS);
   }
   async start() {
     if (this.child) return;
@@ -914,8 +1054,16 @@ var ClientTransport = class {
       import("@wrongstack/core/utils"),
       import("node:os")
     ]);
-    return new Promise((resolve3, reject) => {
+    return new Promise((resolve4, reject) => {
       const timeout = setTimeout(() => {
+        const child2 = this.child;
+        this.child = null;
+        if (child2) {
+          try {
+            treeKill(child2);
+          } catch {
+          }
+        }
         reject(
           new Error(`ACP child process failed to start within ${this.opts.handshakeTimeoutMs}ms`)
         );
@@ -959,7 +1107,7 @@ var ClientTransport = class {
           if (settled) return;
           settled = true;
           clearTimeout(timeout);
-          resolve3();
+          resolve4();
         });
         return;
       }
@@ -970,7 +1118,7 @@ var ClientTransport = class {
         child.stderr.on("data", (c) => this.onChildError(c));
         child.on("close", (code) => this.onChildClose(code));
         clearTimeout(timeout);
-        resolve3();
+        resolve4();
       };
       const waitForMarker = (chunk) => {
         this.buffer += chunk;
@@ -989,33 +1137,52 @@ var ClientTransport = class {
   }
   send(msg) {
     if (!this.child) return Promise.reject(new Error("ClientTransport not started"));
-    return new Promise((resolve3, reject) => {
+    return new Promise((resolve4, reject) => {
       const line = JSON.stringify(msg) + "\n";
       this.child?.stdin.write(line, "utf8", (err) => {
         if (err) reject(err);
-        else resolve3();
+        else resolve4();
       });
     });
   }
   read() {
-    if (this.messageQueue.length > 0)
-      return Promise.resolve(expectDefined(this.messageQueue.shift()));
+    if (this.messageQueue.length > 0) {
+      const queued = expectDefined(this.messageQueue.shift());
+      this.queuedChars = Math.max(0, this.queuedChars - queued.chars);
+      return Promise.resolve(queued.message);
+    }
     if (this.closed) return Promise.resolve(null);
-    return new Promise((resolve3) => {
-      this.resolveRead = resolve3;
+    return new Promise((resolve4) => {
+      this.resolveRead = resolve4;
     });
   }
   onMessage(handler) {
     this.handlers.add(handler);
     return () => this.handlers.delete(handler);
   }
+  /**
+   * Register a handler that MAY claim a message by returning `true`.
+   * Claimed messages are NOT enqueued for the read() loop — they are
+   * considered fully consumed by the handler. This is how the ACP
+   * server transport prevents the correlation handler (which always
+   * fires on every message but only actually correlates responses)
+   * from starving the read() loop of pipelined requests, notifications,
+   * and any message the handler chose to ignore. See dispatch() for
+   * the gating logic.
+   */
+  onMessageClaim(handler) {
+    this.claimHandlers.add(handler);
+    return () => this.claimHandlers.delete(handler);
+  }
   stop() {
     this.closed = true;
     this.resolveRead?.(null);
     this.resolveRead = null;
     this.buffer = "";
     this.messageQueue.length = 0;
+    this.queuedChars = 0;
     this.handlers.clear();
+    this.claimHandlers.clear();
     const child = this.child;
     if (!child) return;
     treeKill(child);
@@ -1040,7 +1207,7 @@ var ClientTransport = class {
         return;
       }
       try {
-        this.dispatch(JSON.parse(raw));
+        this.dispatch(JSON.parse(raw), raw.length);
       } catch {
       }
     }
@@ -1050,29 +1217,34 @@ var ClientTransport = class {
   }
   onChildClose(code) {
     this.closed = true;
+    this.child = null;
     this.resolveRead?.(null);
     this.resolveRead = null;
     this.buffer = "";
     this.messageQueue.length = 0;
+    this.queuedChars = 0;
     this.handlers.clear();
     if (code !== 0 && code !== null) {
       writeErr(`[acp-child exited with code ${code}]
 `);
     }
   }
-  dispatch(msg) {
+  dispatch(msg, chars = JSON.stringify(msg).length) {
     if (this.resolveRead) {
-      const resolve3 = this.resolveRead;
+      const resolve4 = this.resolveRead;
       this.resolveRead = null;
-      resolve3(msg);
+      resolve4(msg);
     } else if (this.handlers.size === 0) {
-      if (this.messageQueue.length >= this.maxQueuedMessages) {
-        writeErr(`[acp-child message queue exceeds ${this.maxQueuedMessages} entries]
-`);
+      if (this.messageQueue.length >= this.maxQueuedMessages || this.queuedChars + chars > this.maxQueuedChars) {
+        writeErr(
+          `[acp-child message queue exceeds ${this.maxQueuedMessages} entries or ${this.maxQueuedChars} characters]
+`
+        );
         this.stop();
         return;
       }
-      this.messageQueue.push(msg);
+      this.messageQueue.push({ message: msg, chars });
+      this.queuedChars += chars;
     }
     for (const handler of this.handlers) {
       try {
@@ -1366,12 +1538,12 @@ var WrongStackACPServer = class {
         res.end(JSON.stringify({ error: { code: -32603, message: "Internal error" } }));
       }
     });
-    return new Promise((resolve3) => {
+    return new Promise((resolve4) => {
       this.httpServer.listen(port, host, () => {
         writeErr2(`[wstack-acp] HTTP server listening on http://${host}:${port}
 `);
         this.running = true;
-        resolve3();
+        resolve4();
       });
     });
   }
@@ -1454,26 +1626,26 @@ function emptyRunResult(stopReason) {
 // src/client/file-server.ts
 import { randomBytes } from "node:crypto";
 import { realpathSync } from "node:fs";
-import * as fsp from "node:fs/promises";
-import * as path from "node:path";
+import * as fsp2 from "node:fs/promises";
+import * as path2 from "node:path";
 var DEFAULT_FILE_OPERATIONS = {
-  stat: fsp.stat,
-  readFile: fsp.readFile,
-  writeFile: fsp.writeFile,
-  realpath: fsp.realpath,
-  rename: fsp.rename,
-  unlink: fsp.unlink
+  stat: fsp2.stat,
+  readFile: fsp2.readFile,
+  writeFile: fsp2.writeFile,
+  realpath: fsp2.realpath,
+  rename: fsp2.rename,
+  unlink: fsp2.unlink
 };
 var DEFAULT_MAX_READ_BYTES = 5 * 1024 * 1024;
 var DEFAULT_MAX_WRITE_BYTES = 5 * 1024 * 1024;
 var FsError = class extends Error {
   code;
   path;
-  constructor(code, path4, message) {
+  constructor(code, path5, message) {
     super(message);
     this.name = "FsError";
     this.code = code;
-    this.path = path4;
+    this.path = path5;
   }
 };
 var FileServer = class {
@@ -1484,7 +1656,7 @@ var FileServer = class {
   maxWriteBytes;
   operations;
   constructor(opts) {
-    this.root = path.resolve(opts.projectRoot);
+    this.root = path2.resolve(opts.projectRoot);
     this.realRoot = safeRealpathSync(this.root);
     this.timeoutMs = opts.timeoutMs ?? 3e4;
     this.maxReadBytes = opts.maxReadBytes ?? DEFAULT_MAX_READ_BYTES;
@@ -1497,14 +1669,14 @@ var FileServer = class {
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), this.timeoutMs);
     try {
-      const stat2 = await this.operations.stat(safe).catch((err) => {
+      const stat3 = await this.operations.stat(safe).catch((err) => {
         throw mapFsError(err, safe);
       });
-      if (stat2.size > this.maxReadBytes) {
+      if (stat3.size > this.maxReadBytes) {
         throw new FsError(
           "TOO_LARGE",
           safe,
-          `file is ${stat2.size} bytes, max read is ${this.maxReadBytes} bytes`
+          `file is ${stat3.size} bytes, max read is ${this.maxReadBytes} bytes`
         );
       }
       const content = await this.operations.readFile(safe, {
@@ -1542,7 +1714,7 @@ var FileServer = class {
         signal: controller.signal
       });
       await this.assertRealInside(tmp);
-      await this.assertRealInside(path.dirname(safe));
+      await this.assertRealInside(path2.dirname(safe));
       await this.operations.rename(tmp, safe);
     } catch (err) {
       if (err instanceof FsError) {
@@ -1573,11 +1745,11 @@ var FileServer = class {
     if (typeof p !== "string" || p.length === 0) {
       throw new FsError("INVALID_PATH", p, "path is empty or not a string");
     }
-    if (!path.isAbsolute(p)) {
+    if (!path2.isAbsolute(p)) {
       throw new FsError("INVALID_PATH", p, "path must be absolute (ACP requirement)");
     }
-    const resolved = path.resolve(p);
-    const rootWithSep = this.root.endsWith(path.sep) ? this.root : this.root + path.sep;
+    const resolved = path2.resolve(p);
+    const rootWithSep = this.root.endsWith(path2.sep) ? this.root : this.root + path2.sep;
     if (resolved !== this.root && !resolved.startsWith(rootWithSep)) {
       throw new FsError("OUTSIDE_ROOT", resolved, "path is outside the project root");
     }
@@ -1598,7 +1770,7 @@ var FileServer = class {
       } catch (err) {
         const code = err.code;
         if (code === "ENOENT") {
-          const parent = path.dirname(probe);
+          const parent = path2.dirname(probe);
           if (parent === probe) {
             throw new FsError("ENOENT", resolvedPath, `no existing ancestor: ${resolvedPath}`);
           }
@@ -1607,7 +1779,7 @@ var FileServer = class {
         }
         throw mapFsError(err, resolvedPath);
       }
-      if (real === this.realRoot || real.startsWith(this.realRoot + path.sep)) return;
+      if (real === this.realRoot || real.startsWith(this.realRoot + path2.sep)) return;
       throw new FsError(
         "OUTSIDE_ROOT",
         resolvedPath,
@@ -1680,8 +1852,9 @@ function makePermissionPolicy(decide) {
 // src/client/terminal-server.ts
 import { spawn } from "node:child_process";
 import { realpathSync as realpathSync2 } from "node:fs";
-import * as path2 from "node:path";
+import * as path3 from "node:path";
 import { buildChildEnv } from "@wrongstack/core/utils";
+import { treeKill as treeKill2 } from "@wrongstack/core/utils/tree-kill";
 var EMPTY_BUFFER = Buffer.alloc(0);
 var TerminalServer = class {
   terminals = /* @__PURE__ */ new Map();
@@ -1694,7 +1867,7 @@ var TerminalServer = class {
   abortHandler = () => this.releaseAll();
   nextId = 1;
   constructor(opts) {
-    this.projectRoot = path2.resolve(opts.projectRoot);
+    this.projectRoot = path3.resolve(opts.projectRoot);
     this.commandTimeoutMs = opts.commandTimeoutMs ?? 5 * 6e4;
     this.outputByteLimit = opts.outputByteLimit ?? 1024 * 1024;
     this.maxOutputByteLimit = opts.maxOutputByteLimit ?? 16 * 1024 * 1024;
@@ -1741,7 +1914,7 @@ var TerminalServer = class {
       truncated: false,
       exitStatus: void 0,
       timeoutHandle: null,
-      exitPromise: new Promise((resolve3) => {
+      exitPromise: new Promise((resolve4) => {
         proc.on("close", (code, signalName) => {
           if (state.timeoutHandle) {
             clearTimeout(state.timeoutHandle);
@@ -1752,7 +1925,7 @@ var TerminalServer = class {
             signal: typeof signalName === "string" ? signalName : null
           };
           state.exitStatus = exitStatus;
-          resolve3(exitStatus);
+          resolve4(exitStatus);
         });
         proc.on("error", (err) => {
           if (state.timeoutHandle) {
@@ -1771,7 +1944,7 @@ var TerminalServer = class {
           }
           state.outputChunks.push(errorOutput);
           state.retainedBytes = errorOutput.length;
-          resolve3(exitStatus);
+          resolve4(exitStatus);
         });
       })
     };
@@ -1801,13 +1974,11 @@ var TerminalServer = class {
         state.outputHead = 0;
       }
     };
+    state.onData = onData;
     proc.stdout?.on("data", onData);
     proc.stderr?.on("data", onData);
     state.timeoutHandle = setTimeout(() => {
-      try {
-        proc.kill("SIGTERM");
-      } catch {
-      }
+      treeKill2(proc);
     }, this.commandTimeoutMs);
     this.terminals.set(id, state);
     return { terminalId: id };
@@ -1831,14 +2002,15 @@ var TerminalServer = class {
     if (!state) throw new Error(`unknown terminal: ${terminalId}`);
     return state.exitPromise;
   }
-  /** Kill the process but keep the terminal record (agent can still read output). */
+  /**
+   * Kill the process but keep the terminal record (agent can still read output).
+   * On POSIX this signals only the direct child; descendants may survive because
+   * terminal processes are not spawned as process-group leaders.
+   */
   kill(terminalId) {
     const state = this.terminals.get(terminalId);
     if (!state) throw new Error(`unknown terminal: ${terminalId}`);
-    try {
-      state.proc.kill("SIGTERM");
-    } catch {
-    }
+    treeKill2(state.proc);
   }
   /** Kill the process if alive and remove the record. */
   release(terminalId) {
@@ -1848,10 +2020,17 @@ var TerminalServer = class {
       clearTimeout(state.timeoutHandle);
       state.timeoutHandle = null;
     }
-    try {
-      state.proc.kill("SIGKILL");
-    } catch {
-    }
+    if (state.onData) {
+      state.proc.stdout?.off("data", state.onData);
+      state.proc.stderr?.off("data", state.onData);
+      state.onData = void 0;
+    }
+    state.proc.stdout?.destroy?.();
+    state.proc.stderr?.destroy?.();
+    state.outputChunks.length = 0;
+    state.outputHead = 0;
+    state.retainedBytes = 0;
+    treeKill2(state.proc, { force: true });
     this.terminals.delete(terminalId);
   }
   /** Kill all active terminals. Used on session close. */
@@ -1863,15 +2042,15 @@ var TerminalServer = class {
   }
   resolveCwd(cwd) {
     if (!cwd) return this.projectRoot;
-    const resolved = path2.resolve(cwd);
-    const rootWithSep = this.projectRoot.endsWith(path2.sep) ? this.projectRoot : this.projectRoot + path2.sep;
+    const resolved = path3.resolve(cwd);
+    const rootWithSep = this.projectRoot.endsWith(path3.sep) ? this.projectRoot : this.projectRoot + path3.sep;
     if (resolved !== this.projectRoot && !resolved.startsWith(rootWithSep)) {
       return this.projectRoot;
     }
     try {
       const realRoot = realpathSync2(this.projectRoot);
       const realCwd = realpathSync2(resolved);
-      const realRootWithSep = realRoot.endsWith(path2.sep) ? realRoot : realRoot + path2.sep;
+      const realRootWithSep = realRoot.endsWith(path3.sep) ? realRoot : realRoot + path3.sep;
       if (realCwd !== realRoot && !realCwd.startsWith(realRootWithSep)) {
         return realRoot;
       }
@@ -2014,7 +2193,12 @@ var WebSocketClientTransport = class {
     this.maxBufferedBytes = finitePositiveLimit(opts.maxBufferedBytes, 32 * 1024 * 1024);
     this.maxMessageChars = finitePositiveLimit(opts.maxMessageChars, 20 * 1024 * 1024);
   }
+  /** Pending start() promise resolve/reject — settled in stop() to avoid leaking. */
+  pendingStart = null;
   start() {
+    if (this.closed || this.ws !== null || this.pendingStart !== null) {
+      return Promise.reject(new Error("WebSocket transport has already been started or stopped"));
+    }
     const WS = globalThis.WebSocket;
     if (!WS) {
       return Promise.reject(
@@ -2024,36 +2208,54 @@ var WebSocketClientTransport = class {
       );
     }
     const timeoutMs = this.opts.handshakeTimeoutMs ?? 3e4;
-    return new Promise((resolve3, reject) => {
-      let settled = false;
+    return new Promise((resolve4, reject) => {
       const ws = new WS(this.opts.url, this.opts.protocols);
       this.ws = ws;
       const timer = setTimeout(() => {
-        settled = true;
+        const pending = this.pendingStart;
+        if (pending === null) return;
+        this.pendingStart = null;
+        this.closed = true;
+        if (this.ws === ws) this.ws = null;
+        this.handlers.clear();
         try {
           ws.close();
         } catch {
         }
-        reject(new Error(`WebSocket failed to open within ${timeoutMs}ms`));
+        pending.reject(new Error(`WebSocket failed to open within ${timeoutMs}ms`));
       }, timeoutMs);
+      this.pendingStart = { resolve: resolve4, reject, timer };
       ws.addEventListener("open", () => {
-        if (settled) return;
-        settled = true;
-        clearTimeout(timer);
-        resolve3();
+        const pending = this.pendingStart;
+        if (pending === null) return;
+        this.pendingStart = null;
+        clearTimeout(pending.timer);
+        pending.resolve();
       });
       ws.addEventListener("error", (ev) => {
-        if (settled) {
-          this.closed = true;
+        const pending = this.pendingStart;
+        if (pending === null) {
+          this.stop();
           return;
         }
-        settled = true;
-        clearTimeout(timer);
+        this.pendingStart = null;
+        this.closed = true;
+        if (this.ws === ws) this.ws = null;
+        this.handlers.clear();
+        clearTimeout(pending.timer);
         const message = ev && typeof ev === "object" && "message" in ev ? String(ev.message) : "WebSocket error";
-        reject(new Error(message));
+        pending.reject(new Error(message));
       });
       ws.addEventListener("close", () => {
         this.closed = true;
+        if (this.ws === ws) this.ws = null;
+        this.handlers.clear();
+        const pending = this.pendingStart;
+        if (pending !== null) {
+          this.pendingStart = null;
+          clearTimeout(pending.timer);
+          pending.reject(new Error("WebSocket closed before the connection opened"));
+        }
       });
       ws.addEventListener("message", (ev) => {
         this.onData(ev.data);
@@ -2083,6 +2285,16 @@ var WebSocketClientTransport = class {
   }
   stop() {
     this.closed = true;
+    this.handlers.clear();
+    if (this.pendingStart !== null) {
+      const pending = this.pendingStart;
+      this.pendingStart = null;
+      clearTimeout(pending.timer);
+      try {
+        pending.reject(new Error("WebSocket transport stopped while connecting"));
+      } catch {
+      }
+    }
     if (this.ws) {
       try {
         this.ws.close();
@@ -2495,7 +2707,15 @@ var ACPSession = class _ACPSession {
     if (opts.env !== void 0) transportOpts.env = opts.env;
     if (opts.cwd !== void 0) transportOpts.cwd = opts.cwd;
     const transport = new ClientTransport(transportOpts);
-    return _ACPSession.attach(opts, transport, `failed to spawn ${opts.command}`);
+    try {
+      return await _ACPSession.attach(opts, transport, `failed to spawn ${opts.command}`);
+    } catch (err) {
+      try {
+        transport.stop();
+      } catch {
+      }
+      throw err;
+    }
   }
   /**
    * Connect to a REMOTE ACP agent over a WebSocket instead of spawning a
@@ -3046,7 +3266,7 @@ var ACPSession = class _ACPSession {
     return this.nextId++;
   }
   async sendRequest(id, method, params, timeoutMs) {
-    return new Promise((resolve3, reject) => {
+    return new Promise((resolve4, reject) => {
       const effectiveTimeout = timeoutMs ?? this.timeoutMs;
       const handle = setTimeout(() => {
         this.pending.delete(id);
@@ -3056,7 +3276,7 @@ var ACPSession = class _ACPSession {
       }, effectiveTimeout);
       this.pending.set(id, {
         method,
-        resolve: resolve3,
+        resolve: resolve4,
         reject,
         timeoutMs: effectiveTimeout,
         timeoutHandle: handle
@@ -3222,12 +3442,12 @@ var ToolTranslator = class {
       id: callId,
       params: { name, arguments: args }
     });
-    return new Promise((resolve3, reject) => {
+    return new Promise((resolve4, reject) => {
       const timeout = setTimeout(() => {
         this.pending.delete(callId);
         reject(new Error(`Tool call ${name} timed out after ${this.opts.totalTimeoutMs}ms`));
       }, this.opts.totalTimeoutMs);
-      this.pending.set(callId, { resolve: resolve3, reject, timeout });
+      this.pending.set(callId, { resolve: resolve4, reject, timeout });
     });
   }
   cancelAll() {
@@ -3239,8 +3459,8 @@ var ToolTranslator = class {
 };
 
 // src/integration/acp-bench.ts
-import * as fsp2 from "node:fs/promises";
-import * as path3 from "node:path";
+import * as fsp3 from "node:fs/promises";
+import * as path4 from "node:path";
 function firstLine(s) {
   const line = s.split("\n").map((l) => l.trim()).find((l) => l.length > 0) ?? "";
   return line.length > 120 ? `${line.slice(0, 117)}\u2026` : line;
@@ -3307,11 +3527,11 @@ async function benchOne(agentId, cmd, opts) {
     if (opts.checkFs) {
       const fileToken = `FILE_${opts.marker}`;
       const fileName = `acp-bench-${opts.marker}.txt`;
-      const filePath = path3.join(opts.projectRoot, fileName);
+      const filePath = path4.join(opts.projectRoot, fileName);
       let fsOk = false;
       let fsDetail;
       try {
-        await fsp2.writeFile(filePath, fileToken, "utf8");
+        await fsp3.writeFile(filePath, fileToken, "utf8");
         const fsRes = await session.prompt(
           [
             textContent(
@@ -3447,7 +3667,7 @@ function renderAcpBenchText(result) {
   );
   return lines.join("\n");
 }
-async function removeBenchFile(filePath, remove = fsp2.rm) {
+async function removeBenchFile(filePath, remove = fsp3.rm) {
   await remove(filePath, { force: true }).catch(() => void 0);
 }
 
@@ -3987,7 +4207,7 @@ import { SubagentBudget } from "@wrongstack/core/coordination";
 
 // src/registry/ensemble-registry.ts
 import { spawn as spawn2 } from "node:child_process";
-import { treeKill as treeKill2 } from "@wrongstack/core/utils/tree-kill";
+import { treeKill as treeKill3 } from "@wrongstack/core/utils/tree-kill";
 var PROBE_TIMEOUT_MS = 5e3;
 var PROBE_CACHE_MS = 5e3;
 var MAX_PARALLEL_PROBES = 4;
@@ -4013,7 +4233,7 @@ async function probeWithBound(items, worker, limit) {
 }
 async function defaultProbe(desc, timeoutMs, spawnProcess = spawn2, platform = process.platform) {
   const start = Date.now();
-  return new Promise((resolve3) => {
+  return new Promise((resolve4) => {
     let settled = false;
     let stdout = "";
     let stderr = "";
@@ -4022,11 +4242,11 @@ async function defaultProbe(desc, timeoutMs, spawnProcess = spawn2, platform = p
       settled = true;
       try {
         if (child.exitCode === null && child.signalCode === null) {
-          treeKill2(child);
+          treeKill3(child);
         }
       } catch {
       }
-      resolve3(result);
+      resolve4(result);
     };
     let child;
     try {