@wrongstack/acp 0.305.0 → 0.306.0

package/dist/client/terminal-server.d.ts

@@ -18,6 +18,12 @@ export interface TerminalServerOptions {
 }
 export declare class TerminalServer {
     private readonly terminals;
+    /**
+     * Stable per-instance identifier for debug logs. 8 hex chars is enough
+     * to disambiguate concurrent TerminalServers in a trace; not meant to
+     * be cryptographically unique.
+     */
+    private readonly instanceId;
     private readonly projectRoot;
     private readonly commandTimeoutMs;
     private readonly outputByteLimit;
@@ -25,6 +31,7 @@ export declare class TerminalServer {
     private readonly maxTerminals;
     private readonly abortSignal;
     private readonly abortHandler;
+    private disposed;
     private nextId;
     constructor(opts: TerminalServerOptions);
     /** Spawn a new terminal. Returns the agent-facing id. */
@@ -63,7 +70,32 @@ export declare class TerminalServer {
     kill(terminalId: string): void;
     /** Kill the process if alive and remove the record. */
     release(terminalId: string): void;
-    /** Kill all active terminals. Used on session close. */
+    /**
+     * Release all resources held by this server: kill every active terminal
+     * and detach the host `AbortSignal` listener.
+     *
+     * Idempotent — calling it multiple times is safe. Required because the
+     * previously-coded `releaseAll()` was the only path that removed the
+     * abort listener: if the host never called it (unhandled error path,
+     * host crash, GC of the session without explicit close), the listener
+     * pinned `this` (terminals Map, output buffers) for the lifetime of the
+     * signal. With `dispose()` this is no longer leak-prone.
+     *
+     * Also exposed as `[Symbol.dispose]` for `using` blocks in Node ≥ 22.
+     *
+     * RAM-leak audit 2026-08-11, MEDIUM (Finding 2).
+     */
+    dispose(): void;
+    /** Alias for `dispose()` — enables `using new TerminalServer(...)`. */
+    [Symbol.dispose](): void;
+    /**
+     * Kill all active terminals. Used on session close.
+     *
+     * @deprecated Prefer `dispose()` (or `using { … }` via `Symbol.dispose`).
+     * `releaseAll` is retained as a delegated wrapper for callers that still
+     * reference it; new code should call `dispose()` directly so the
+     * host-signal listener is removed unconditionally.
+     */
     releaseAll(): void;
     private resolveCwd;
     private buildEnv;

package/dist/client.js

@@ -515,26 +515,36 @@ function makePermissionPolicy(decide) {
 
 // src/client/terminal-server.ts
 import { spawn } from "node:child_process";
+import { randomBytes as randomBytes2 } from "node:crypto";
 import { realpathSync as realpathSync2 } from "node:fs";
 import * as path2 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 DEBUG_DISPOSE = typeof process !== "undefined" && !!process.env?.WRONGSTACK_DEBUG && process.env.WRONGSTACK_DEBUG !== "0" && process.env.WRONGSTACK_DEBUG !== "false";
 var TerminalServer = class {
   terminals = /* @__PURE__ */ new Map();
+  /**
+   * Stable per-instance identifier for debug logs. 8 hex chars is enough
+   * to disambiguate concurrent TerminalServers in a trace; not meant to
+   * be cryptographically unique.
+   */
+  instanceId;
   projectRoot;
   commandTimeoutMs;
   outputByteLimit;
   maxOutputByteLimit;
   maxTerminals;
   abortSignal;
-  abortHandler = () => this.releaseAll();
+  abortHandler = () => this.dispose();
+  disposed = false;
   nextId = 1;
   constructor(opts) {
     this.projectRoot = path2.resolve(opts.projectRoot);
     this.commandTimeoutMs = opts.commandTimeoutMs ?? 5 * 6e4;
     this.outputByteLimit = opts.outputByteLimit ?? 1024 * 1024;
     this.maxOutputByteLimit = opts.maxOutputByteLimit ?? 16 * 1024 * 1024;
+    this.instanceId = `term_srv_${randomBytes2(4).toString("hex")}`;
     this.maxTerminals = this.clampFiniteInt(opts.maxTerminals, 32);
     this.abortSignal = opts.signal;
     if (opts.signal) {
@@ -543,6 +553,11 @@ var TerminalServer = class {
   }
   /** Spawn a new terminal. Returns the agent-facing id. */
   create(params) {
+    if (this.disposed) {
+      throw new Error(
+        "TerminalServer is disposed \u2014 create a new TerminalServer instead of reusing this one"
+      );
+    }
     if (this.terminals.size >= this.maxTerminals) {
       throw new Error(
         `terminal limit reached (${this.maxTerminals}); release an existing terminal before creating another`
@@ -697,13 +712,56 @@ var TerminalServer = class {
     treeKill2(state.proc, { force: true });
     this.terminals.delete(terminalId);
   }
-  /** Kill all active terminals. Used on session close. */
-  releaseAll() {
+  /**
+   * Release all resources held by this server: kill every active terminal
+   * and detach the host `AbortSignal` listener.
+   *
+   * Idempotent — calling it multiple times is safe. Required because the
+   * previously-coded `releaseAll()` was the only path that removed the
+   * abort listener: if the host never called it (unhandled error path,
+   * host crash, GC of the session without explicit close), the listener
+   * pinned `this` (terminals Map, output buffers) for the lifetime of the
+   * signal. With `dispose()` this is no longer leak-prone.
+   *
+   * Also exposed as `[Symbol.dispose]` for `using` blocks in Node ≥ 22.
+   *
+   * RAM-leak audit 2026-08-11, MEDIUM (Finding 2).
+   */
+  dispose() {
+    if (this.disposed) return;
+    if (DEBUG_DISPOSE) {
+      const activeChildren = this.terminals.size;
+      console.debug(
+        JSON.stringify({
+          event: "terminal_server.disposed",
+          instanceId: this.instanceId,
+          activeChildren,
+          hadSignal: this.abortSignal !== void 0,
+          timestamp: (/* @__PURE__ */ new Date()).toISOString()
+        })
+      );
+    }
+    this.disposed = true;
     this.abortSignal?.removeEventListener("abort", this.abortHandler);
     for (const id of [...this.terminals.keys()]) {
       this.release(id);
     }
   }
+  /** Alias for `dispose()` — enables `using new TerminalServer(...)`. */
+  [Symbol.dispose]() {
+    this.dispose();
+  }
+  /**
+   * Kill all active terminals. Used on session close.
+   *
+   * @deprecated Prefer `dispose()` (or `using { … }` via `Symbol.dispose`).
+   * `releaseAll` is retained as a delegated wrapper for callers that still
+   * reference it; new code should call `dispose()` directly so the
+   * host-signal listener is removed unconditionally.
+   */
+  releaseAll() {
+    this.dispose();
+  }
   resolveCwd(cwd) {
     if (!cwd) return this.projectRoot;
     const resolved = path2.resolve(cwd);
@@ -1966,7 +2024,7 @@ var ACPSession = class _ACPSession {
     this.callbackAbort.abort();
     this.promptCallbackAbort?.abort();
     this.promptCallbackAbort = null;
-    this.terminalServer.releaseAll();
+    this.terminalServer.dispose();
     if (this.sessionId && this.agentCapabilities.sessionCapabilities?.close) {
       try {
         await this.closeSession();

package/dist/index.js

@@ -1870,26 +1870,36 @@ function makePermissionPolicy(decide) {
 
 // src/client/terminal-server.ts
 import { spawn } from "node:child_process";
+import { randomBytes as randomBytes2 } from "node:crypto";
 import { realpathSync as realpathSync2 } from "node:fs";
 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 DEBUG_DISPOSE = typeof process !== "undefined" && !!process.env?.WRONGSTACK_DEBUG && process.env.WRONGSTACK_DEBUG !== "0" && process.env.WRONGSTACK_DEBUG !== "false";
 var TerminalServer = class {
   terminals = /* @__PURE__ */ new Map();
+  /**
+   * Stable per-instance identifier for debug logs. 8 hex chars is enough
+   * to disambiguate concurrent TerminalServers in a trace; not meant to
+   * be cryptographically unique.
+   */
+  instanceId;
   projectRoot;
   commandTimeoutMs;
   outputByteLimit;
   maxOutputByteLimit;
   maxTerminals;
   abortSignal;
-  abortHandler = () => this.releaseAll();
+  abortHandler = () => this.dispose();
+  disposed = false;
   nextId = 1;
   constructor(opts) {
     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;
+    this.instanceId = `term_srv_${randomBytes2(4).toString("hex")}`;
     this.maxTerminals = this.clampFiniteInt(opts.maxTerminals, 32);
     this.abortSignal = opts.signal;
     if (opts.signal) {
@@ -1898,6 +1908,11 @@ var TerminalServer = class {
   }
   /** Spawn a new terminal. Returns the agent-facing id. */
   create(params) {
+    if (this.disposed) {
+      throw new Error(
+        "TerminalServer is disposed \u2014 create a new TerminalServer instead of reusing this one"
+      );
+    }
     if (this.terminals.size >= this.maxTerminals) {
       throw new Error(
         `terminal limit reached (${this.maxTerminals}); release an existing terminal before creating another`
@@ -2052,13 +2067,56 @@ var TerminalServer = class {
     treeKill2(state.proc, { force: true });
     this.terminals.delete(terminalId);
   }
-  /** Kill all active terminals. Used on session close. */
-  releaseAll() {
+  /**
+   * Release all resources held by this server: kill every active terminal
+   * and detach the host `AbortSignal` listener.
+   *
+   * Idempotent — calling it multiple times is safe. Required because the
+   * previously-coded `releaseAll()` was the only path that removed the
+   * abort listener: if the host never called it (unhandled error path,
+   * host crash, GC of the session without explicit close), the listener
+   * pinned `this` (terminals Map, output buffers) for the lifetime of the
+   * signal. With `dispose()` this is no longer leak-prone.
+   *
+   * Also exposed as `[Symbol.dispose]` for `using` blocks in Node ≥ 22.
+   *
+   * RAM-leak audit 2026-08-11, MEDIUM (Finding 2).
+   */
+  dispose() {
+    if (this.disposed) return;
+    if (DEBUG_DISPOSE) {
+      const activeChildren = this.terminals.size;
+      console.debug(
+        JSON.stringify({
+          event: "terminal_server.disposed",
+          instanceId: this.instanceId,
+          activeChildren,
+          hadSignal: this.abortSignal !== void 0,
+          timestamp: (/* @__PURE__ */ new Date()).toISOString()
+        })
+      );
+    }
+    this.disposed = true;
     this.abortSignal?.removeEventListener("abort", this.abortHandler);
     for (const id of [...this.terminals.keys()]) {
       this.release(id);
     }
   }
+  /** Alias for `dispose()` — enables `using new TerminalServer(...)`. */
+  [Symbol.dispose]() {
+    this.dispose();
+  }
+  /**
+   * Kill all active terminals. Used on session close.
+   *
+   * @deprecated Prefer `dispose()` (or `using { … }` via `Symbol.dispose`).
+   * `releaseAll` is retained as a delegated wrapper for callers that still
+   * reference it; new code should call `dispose()` directly so the
+   * host-signal listener is removed unconditionally.
+   */
+  releaseAll() {
+    this.dispose();
+  }
   resolveCwd(cwd) {
     if (!cwd) return this.projectRoot;
     const resolved = path3.resolve(cwd);
@@ -3321,7 +3379,7 @@ var ACPSession = class _ACPSession {
     this.callbackAbort.abort();
     this.promptCallbackAbort?.abort();
     this.promptCallbackAbort = null;
-    this.terminalServer.releaseAll();
+    this.terminalServer.dispose();
     if (this.sessionId && this.agentCapabilities.sessionCapabilities?.close) {
       try {
         await this.closeSession();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wrongstack/acp",
-  "version": "0.305.0",
+  "version": "0.306.0",
   "license": "MIT",
   "description": "ACP (Agent Client Protocol) integration for WrongStack — client + agent support",
   "keywords": [
@@ -52,7 +52,7 @@
   ],
   "dependencies": {
     "@agentclientprotocol/sdk": "^1.3.0",
-    "@wrongstack/core": "0.305.0"
+    "@wrongstack/core": "0.306.0"
   },
   "devDependencies": {
     "@types/node": "^26.1.2",