@wrongstack/acp 0.297.0 → 0.298.0

package/dist/agent.js

@@ -3,6 +3,7 @@ import { expectDefined, writeErr } from "@wrongstack/core/utils";
 import { treeKill } from "@wrongstack/core/utils/tree-kill";
 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;
 }
@@ -12,53 +13,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((resolve) => {
+    return new Promise((resolve2) => {
       const line = JSON.stringify(msg) + "\n";
-      this.stdout.write(line, "utf8", () => resolve());
+      this.stdout.write(line, "utf8", () => resolve2());
     });
   }
   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((resolve) => {
-      this.resolveRead = resolve;
+    return new Promise((resolve2) => {
+      this.resolveRead = resolve2;
     });
   }
   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;
@@ -85,29 +115,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 resolve = this.resolveRead;
+      const resolve2 = this.resolveRead;
       this.resolveRead = null;
-      resolve(msg);
+      resolve2(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 {
@@ -242,6 +284,11 @@ function toolToPriority(tool) {
   return "low";
 }
 
+// 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;
 
@@ -331,12 +378,12 @@ var ACPProtocolHandler = class {
    */
   request(method, params, timeoutMs = 6e4) {
     const id = `srv_${this.nextOutId++}`;
-    return new Promise((resolve, reject) => {
+    return new Promise((resolve2, reject) => {
       const timer = setTimeout(() => {
         this.pendingOut.delete(id);
         reject(new Error(`${method} timed out after ${timeoutMs}ms`));
       }, timeoutMs);
-      this.pendingOut.set(id, { resolve, reject, timer });
+      this.pendingOut.set(id, { resolve: resolve2, reject, timer });
       this.transport.send(toWire({ jsonrpc: "2.0", id, method, params })).catch((e) => {
         clearTimeout(timer);
         this.pendingOut.delete(id);
@@ -453,62 +500,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) {
@@ -517,7 +570,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 = {
@@ -547,15 +608,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) {
@@ -570,9 +633,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(),
@@ -588,13 +657,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;
       }
     }
@@ -620,16 +691,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}`);
@@ -641,16 +714,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}`);
@@ -667,11 +742,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) {
@@ -682,18 +759,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) {
@@ -708,11 +789,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,
@@ -731,38 +821,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) {
@@ -815,7 +915,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 ?? ""),
@@ -845,11 +948,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) {
@@ -890,7 +995,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) {
@@ -903,11 +1010,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;
   }
   // ────────────────────────────────────────────────────────────────────
@@ -953,8 +1062,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 stat2 = await fsp.stat(resolved);
+      return stat2.isDirectory() ? resolved : null;
+    } catch {
+      return null;
+    }
+  }
   allocId() {
-    return this.nextId++;
+    return `${this.nextId++}_${randomUUID().replaceAll("-", "")}`;
   }
 };
 function errorToJsonRpc(err) {
@@ -974,8 +1129,10 @@ function errorToJsonRpc(err) {
 }
 
 // src/agent/session-store.ts
-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";
+import { isSafePathSegment, resolveContainedPath } from "@wrongstack/core/utils";
+var RESERVED_SESSION_IDS = /* @__PURE__ */ new Set(["index"]);
 var ACPSessionStore = class {
   dir;
   /**
@@ -985,13 +1142,53 @@ var ACPSessionStore = class {
    * Cleared automatically if the directory disappears between calls.
    */
   initialized = false;
+  /**
+   * Tail of in-flight sidecar-index mutations. `readIndex`/`writeIndex`/
+   * `updateIndex`/delete's index-touching branch all run through the
+   * `withIndexLock` gate so a concurrent save/delete/save cannot read the
+   * same baseline twice and clobber the other writer's edit (Chimera
+   * HIGH — race that could permanently omit or resurrect sessions in
+   * `list()`). Mirrors the `writeChains` pattern in
+   * `packages/core/src/storage/tool-audit-log.ts`.
+   */
+  indexChain = Promise.resolve();
+  /**
+   * Monotonic per-store counter. Used to make tmp filenames unique so two
+   * concurrent saves started in the same millisecond cannot collide on
+   * `<target>.<pid>.<ts>.tmp` and lose one's tmp mid-write (latent bug
+   * discovered by the concurrent same-id save/delete stress test).
+   */
+  writeSeq = 0;
   constructor(opts = {}) {
-    this.dir = opts.dir ?? path.join(process.cwd(), ".acp-sessions");
+    this.dir = opts.dir ?? path2.join(process.cwd(), ".acp-sessions");
+  }
+  /**
+   * Path of `<sessionId>.json` inside the store, or `null` when `sessionId`
+   * is not usable as a single path segment (WS-015).
+   *
+   * The session id arrives from the ACP client — `session/load`,
+   * `session/close` and `session/delete` all take it verbatim from the wire.
+   * It was joined straight onto the store directory, so `../../..` escaped it,
+   * and the `.json` suffix was the only thing narrowing the blast radius:
+   *
+   *   - `load`   — read any `.json` on the machine, e.g. the provider config
+   *                holding API keys
+   *   - `delete` — unlink any `.json` on the machine
+   *   - `save`   — the worst one: a loaded session keeps the traversing id as
+   *                its `state.id`, so the next persist WRITES to that path
+   *
+   * All three now route through here, so the escape is closed once rather than
+   * three times.
+   */
+  sessionFile(sessionId) {
+    if (!isSafePathSegment(sessionId)) return null;
+    if (RESERVED_SESSION_IDS.has(sessionId)) return null;
+    return resolveContainedPath(this.dir, `${sessionId}.json`);
   }
   /** Ensure the store directory exists. Memoized — only mkdirs once. */
   async init() {
     if (this.initialized) return;
-    await fsp.mkdir(this.dir, { recursive: true });
+    await fsp2.mkdir(this.dir, { recursive: true });
     this.initialized = true;
   }
   /**
@@ -1000,30 +1197,43 @@ var ACPSessionStore = class {
    * `session/load` replay.
    */
   async save(state, history) {
+    const target = this.sessionFile(state.id);
+    if (target === null) {
+      throw new Error(`ACPSessionStore: refusing to persist unsafe session id "${state.id}"`);
+    }
     await this.init();
-    const target = path.join(this.dir, `${state.id}.json`);
-    const tmp = `${target}.${process.pid}.${Date.now()}.tmp`;
-    await fsp.writeFile(
-      tmp,
-      JSON.stringify({
-        id: state.id,
-        cwd: state.cwd,
-        modeId: state.modeId,
-        createdAt: state.createdAt,
-        updatedAt: state.updatedAt,
-        title: state.title,
-        ...history && history.length > 0 ? { history } : {}
-      }),
-      "utf8"
-    );
-    await fsp.rename(tmp, target);
+    const tmp = `${target}.${process.pid}.${Date.now()}.${++this.writeSeq}.tmp`;
+    let renamed = false;
+    try {
+      await fsp2.writeFile(
+        tmp,
+        JSON.stringify({
+          id: state.id,
+          cwd: state.cwd,
+          modeId: state.modeId,
+          createdAt: state.createdAt,
+          updatedAt: state.updatedAt,
+          title: state.title,
+          ...history && history.length > 0 ? { history } : {}
+        }),
+        "utf8"
+      );
+      await fsp2.rename(tmp, target);
+      renamed = true;
+    } finally {
+      if (!renamed) {
+        await fsp2.unlink(tmp).catch(() => void 0);
+      }
+    }
     await this.updateIndex(state.id, state.updatedAt);
     return state.id;
   }
   /** Load a persisted session (metadata + history) from disk, or null. */
   async load(sessionId) {
+    const target = this.sessionFile(sessionId);
+    if (target === null) return null;
     try {
-      const data = await fsp.readFile(path.join(this.dir, `${sessionId}.json`), "utf8");
+      const data = await fsp2.readFile(target, "utf8");
       return JSON.parse(data);
     } catch {
       return null;
@@ -1035,9 +1245,20 @@ var ACPSessionStore = class {
     if (indexEntries !== null) {
       return indexEntries.sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
     }
+    const sessions = await this.scanForSessions();
+    void this.writeIndex(sessions).catch(() => void 0);
+    return sessions;
+  }
+  /**
+   * Walk `<dir>` and parse every session file into `{id, updatedAt}`
+   * metadata. Used as the slow-path fallback by `list()` and by
+   * `updateIndex()` when the sidecar index is missing. Pure read —
+   * does NOT touch `index.json`.
+   */
+  async scanForSessions() {
     const files = [];
     try {
-      const entries = await fsp.readdir(this.dir);
+      const entries = await fsp2.readdir(this.dir);
       for (const entry of entries) {
         if (entry.endsWith(".json") && entry !== "index.json") {
           files.push(entry);
@@ -1049,7 +1270,7 @@ var ACPSessionStore = class {
     const sessions = [];
     for (const file of files) {
       try {
-        const data = await fsp.readFile(path.join(this.dir, file), "utf8");
+        const data = await fsp2.readFile(path2.join(this.dir, file), "utf8");
         const parsed = JSON.parse(data);
         if (parsed.id) {
           sessions.push({ id: parsed.id, updatedAt: parsed.updatedAt ?? "" });
@@ -1058,17 +1279,40 @@ var ACPSessionStore = class {
       }
     }
     sessions.sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
-    void this.writeIndex(sessions).catch(() => void 0);
     return sessions;
   }
   /** Sidecar path that stores `{id, updatedAt}` for every saved session. */
   indexPath() {
-    return path.join(this.dir, "index.json");
+    return path2.join(this.dir, "index.json");
+  }
+  /**
+   * Serialize sidecar-index mutations. Each call appends `fn` to the tail
+   * of `indexChain` so reads and writes see a linearized order — a second
+   * caller cannot start until the first one's index update has finished.
+   *
+   * The chain swallows errors (`prev.then(fn, fn)`) so one failing writer
+   * does not poison every subsequent caller, and the catch keeps an
+   * unhandled rejection from leaking out of the stored tail. The cleanup
+   * removes the tail entry once settled, so a quiet store does not retain
+   * stale promises forever.
+   */
+  withIndexLock(fn) {
+    const prev = this.indexChain;
+    const next = prev.then(fn, fn);
+    const settled = next.then(
+      () => void 0,
+      () => void 0
+    );
+    this.indexChain = settled;
+    void settled.finally(() => {
+      if (this.indexChain === settled) this.indexChain = Promise.resolve();
+    });
+    return next;
   }
   /** Read the sidecar index. Returns `null` when missing or unreadable. */
   async readIndex() {
     try {
-      const data = await fsp.readFile(this.indexPath(), "utf8");
+      const data = await fsp2.readFile(this.indexPath(), "utf8");
       const parsed = JSON.parse(data);
       if (!Array.isArray(parsed)) return null;
       const out = [];
@@ -1088,40 +1332,58 @@ var ACPSessionStore = class {
   /** Atomically replace the sidecar index with the supplied entries. */
   async writeIndex(entries) {
     const target = this.indexPath();
-    const tmp = `${target}.${process.pid}.${Date.now()}.tmp`;
-    await fsp.writeFile(tmp, JSON.stringify(entries), "utf8");
-    await fsp.rename(tmp, target);
+    const tmp = `${target}.${process.pid}.${Date.now()}.${++this.writeSeq}.tmp`;
+    let renamed = false;
+    try {
+      await fsp2.writeFile(tmp, JSON.stringify(entries), "utf8");
+      await fsp2.rename(tmp, target);
+      renamed = true;
+    } finally {
+      if (!renamed) {
+        await fsp2.unlink(tmp).catch(() => void 0);
+      }
+    }
   }
   /** Update one entry in the index, adding it if missing. Best-effort. */
   async updateIndex(id, updatedAt) {
-    const entries = await this.readIndex();
-    if (entries === null) {
-      await this.list();
-      return;
-    }
-    const i = entries.findIndex((e) => e.id === id);
-    if (i >= 0) entries[i] = { id, updatedAt };
-    else entries.push({ id, updatedAt });
-    try {
-      await this.writeIndex(entries);
-    } catch {
-    }
+    await this.withIndexLock(async () => {
+      const entries = await this.readIndex();
+      if (entries === null) {
+        const sessions = await this.scanForSessions();
+        try {
+          await this.writeIndex(sessions);
+        } catch {
+        }
+        return;
+      }
+      const i = entries.findIndex((e) => e.id === id);
+      if (i >= 0) entries[i] = { id, updatedAt };
+      else entries.push({ id, updatedAt });
+      try {
+        await this.writeIndex(entries);
+      } catch {
+      }
+    });
   }
   /** Delete a session file. */
   async delete(sessionId) {
+    const target = this.sessionFile(sessionId);
+    if (target === null) return;
     try {
-      await fsp.unlink(path.join(this.dir, `${sessionId}.json`));
+      await fsp2.unlink(target);
     } catch {
     }
-    const entries = await this.readIndex();
-    if (entries === null) return;
-    const next = entries.filter((e) => e.id !== sessionId);
-    if (next.length !== entries.length) {
-      try {
-        await this.writeIndex(next);
-      } catch {
+    await this.withIndexLock(async () => {
+      const entries = await this.readIndex();
+      if (entries === null) return;
+      const next = entries.filter((e) => e.id !== sessionId);
+      if (next.length !== entries.length) {
+        try {
+          await this.writeIndex(next);
+        } catch {
+        }
       }
-    }
+    });
   }
   /** Get the store directory path. */
   getDirectory() {
@@ -1338,12 +1600,12 @@ var WrongStackACPServer = class {
         res.end(JSON.stringify({ error: { code: -32603, message: "Internal error" } }));
       }
     });
-    return new Promise((resolve) => {
+    return new Promise((resolve2) => {
       this.httpServer.listen(port, host, () => {
         writeErr2(`[wstack-acp] HTTP server listening on http://${host}:${port}
 `);
         this.running = true;
-        resolve();
+        resolve2();
       });
     });
   }
@@ -1591,9 +1853,9 @@ function toolNameToKind(name) {
 }
 function toolTitle(name, input) {
   if (isRecord(input)) {
-    const path2 = input.path ?? input.file ?? input.filePath ?? input.pattern ?? input.command;
-    if (typeof path2 === "string" && path2.length > 0) {
-      return `${name}: ${path2.length > 80 ? `${path2.slice(0, 77)}\u2026` : path2}`;
+    const path3 = input.path ?? input.file ?? input.filePath ?? input.pattern ?? input.command;
+    if (typeof path3 === "string" && path3.length > 0) {
+      return `${name}: ${path3.length > 80 ? `${path3.slice(0, 77)}\u2026` : path3}`;
     }
   }
   return name;