dsh-over-ssh 0.2.2 → 0.2.4

package/lib/index.js

@@ -1560,12 +1560,23 @@ function decisionKey(decision) {
   const degradations = decision.degradations.map((item) => item.code).join(",");
   return `${decision.kind}|${decision.reason}|${decision.reusesConnection}|${degradations}`;
 }
+function isWatchSessionKey(sessionKey2) {
+  return sessionKey2 === "watch" || sessionKey2.startsWith("watch:");
+}
+function laneKey(connectionId, options) {
+  const lane = options?.lane ?? "interactive";
+  if (options === void 0 || lane === "interactive" && options.sessionKey === void 0) return connectionId;
+  return `${connectionId}\0${lane}\0${options.sessionKey ?? ""}`;
+}
 var TransportService = class {
   #selector;
   #factories;
   #preflight;
   #entries = /* @__PURE__ */ new Map();
   #pending = /* @__PURE__ */ new Map();
+  #statefulLaneLimit;
+  /** Every cache key currently owned by a profile, so release/dispose can cover all of its lanes. */
+  #slots = /* @__PURE__ */ new Map();
   /**
    * Connections released while a `connect()` was still in flight.
    *
@@ -1580,84 +1591,205 @@ var TransportService = class {
    * it just created, so it needs to know it was released.
    */
   #retired = /* @__PURE__ */ new Set();
+  /**
+   * Bumped by every explicit release. An `acquire()` that had to discard a lost transport checks this
+   * after the async discard: a release that arrived in that window must not be undone by recreating the
+   * lane. A global counter avoids a per-session map that would itself retain deleted session ids.
+   */
+  #releaseGeneration = 0;
   constructor(options) {
     this.#selector = options.selector;
     this.#factories = options.factories;
     this.#preflight = options.preflight;
-  }
-  /**
-   * Get a connected transport for a profile, creating it if needed.
-   *
-   * @param profile - the connection to serve.
-   * @param signal - cancellation for the connect attempt.
-   * @returns the transport and the decision behind it (after any preflight revision).
-   * @throws SshDevError from the selector or from the transport's own connect.
-   */
-  async acquire(profile, signal) {
+    this.#statefulLaneLimit = Math.max(0, Math.floor(options.statefulLaneLimit ?? 8));
+  }
+  async acquire(profile, signalOrOptions, signalArgument) {
+    const legacySignal = typeof signalOrOptions?.addEventListener === "function" ? signalOrOptions : void 0;
+    const options = legacySignal === void 0 ? signalOrOptions : void 0;
+    const signal = legacySignal ?? signalArgument;
+    const key = laneKey(profile.id, options);
+    const lane = options?.lane ?? "interactive";
     const decided = this.#selector.decide(profile);
-    const existing = this.#entries.get(profile.id);
+    const releaseGeneration = this.#releaseGeneration;
+    if (lane === "stateful" && this.#statefulLaneLimit > 0 && !this.#entries.has(key) && !this.#pending.has(key) && this.#statefulLaneCount(profile.id, isWatchSessionKey(options?.sessionKey ?? "")) >= this.#statefulLaneLimit) {
+      throw new SshDevError(
+        "CONNECTION_INVALID",
+        `stateful transport \u6570\u91CF\u5DF2\u8FBE\u4E0A\u9650\uFF08${this.#statefulLaneLimit} \u6761/\u8FDE\u63A5\uFF09`,
+        { connectionId: profile.id, limit: this.#statefulLaneLimit }
+      );
+    }
+    this.#rememberSlot(profile.id, key);
+    const existing = this.#entries.get(key);
     if (existing !== void 0 && existing.transport.state !== "lost") {
       if (decisionKey(existing.decision) === decisionKey(decided)) return existing;
     }
     if (existing !== void 0) {
       await this.#discard(profile.id);
+      if (this.#releaseGeneration !== releaseGeneration) {
+        this.#forgetSlotIfIdle(profile.id, key);
+        throw new SshDevError("CANCELLED", `\u8FDE\u63A5\u5728\u91CD\u5EFA\u8FC7\u7A0B\u4E2D\u5DF2\u88AB\u91CA\u653E\uFF1A${profile.id}`, { connectionId: profile.id });
+      }
+      this.#rememberSlot(profile.id, key);
     }
-    const inflight = this.#pending.get(profile.id);
+    const inflight = this.#pending.get(key);
     if (inflight !== void 0) return inflight;
     const attempt = (async () => {
       const decision = this.#preflight === void 0 ? decided : await this.#preflight(profile, decided, signal);
-      const transport = this.#create(profile, decision);
+      const transport = this.#create(profile, decision, lane, options?.sessionKey);
       try {
         await transport.connect(signal);
       } catch (error) {
         await transport.dispose().catch(() => void 0);
         throw error;
       }
-      if (this.#retired.delete(profile.id)) {
+      if (this.#retired.delete(key)) {
         await transport.dispose().catch(() => void 0);
         throw new SshDevError("CANCELLED", `\u8FDE\u63A5\u5728\u5EFA\u7ACB\u8FC7\u7A0B\u4E2D\u5DF2\u88AB\u91CA\u653E\uFF1A${profile.id}`, { connectionId: profile.id });
       }
-      const acquired = { transport, decision };
-      this.#entries.set(profile.id, acquired);
+      const acquired = { transport, decision, lane, connectionId: profile.id };
+      this.#entries.set(key, acquired);
       return acquired;
     })().finally(() => {
-      this.#pending.delete(profile.id);
-      this.#retired.delete(profile.id);
+      this.#pending.delete(key);
+      this.#retired.delete(key);
+      this.#forgetSlotIfIdle(profile.id, key);
     });
-    this.#pending.set(profile.id, attempt);
+    this.#pending.set(key, attempt);
     return attempt;
   }
-  /** The cached transport for a connection, if any. */
-  current(connectionId) {
-    return this.#entries.get(connectionId);
+  /**
+   * The cached transport for a connection.
+   *
+   * Without options this is the legacy interactive slot, so existing callers keep their old meaning.
+   */
+  current(connectionId, options) {
+    return this.#entries.get(laneKey(connectionId, options));
   }
   /** Decisions currently in force, for the connection status UI. */
   decisions() {
-    return [...this.#entries.values()].map((entry) => entry.decision);
+    const seen = /* @__PURE__ */ new Set();
+    const decisions = [];
+    for (const entry of this.#entries.values()) {
+      const key = entry.connectionId ?? decisionKey(entry.decision);
+      if (seen.has(key)) continue;
+      seen.add(key);
+      decisions.push(entry.decision);
+    }
+    return decisions;
   }
-  /** Dispose and forget one connection. */
+  /** Dispose and forget **every lane** of one connection. */
   async release(connectionId) {
+    this.#releaseGeneration++;
     await this.#discard(connectionId);
   }
-  /** Dispose every connection (plugin unload, connection-service shutdown). */
+  /** Number of cached/pending stateful lanes of one class (watch vs session) on one connection. */
+  #statefulLaneCount(connectionId, watchOnly) {
+    let count = 0;
+    const marker = "\0stateful\0";
+    for (const key of this.#slots.get(connectionId) ?? []) {
+      const index = key.indexOf(marker);
+      if (index < 0) continue;
+      if (isWatchSessionKey(key.slice(index + marker.length)) === watchOnly) count++;
+    }
+    return count;
+  }
+  /** Unique DSH session keys currently owning a stateful lane (used by the idle janitor). */
+  statefulSessions() {
+    const sessions = /* @__PURE__ */ new Set();
+    for (const keys of this.#slots.values()) {
+      for (const key of keys) {
+        const marker = "\0stateful\0";
+        const index = key.indexOf(marker);
+        if (index >= 0) sessions.add(key.slice(index + marker.length));
+      }
+    }
+    return [...sessions];
+  }
+  /** Release stateful lanes whose DSH session is no longer live. */
+  async pruneStatefulSessions(isLive) {
+    for (const sessionKey2 of this.statefulSessions()) {
+      if (!isLive(sessionKey2)) await this.releaseSession(sessionKey2);
+    }
+  }
+  /**
+   * Dispose the `stateful` lane of one DSH session on every connection.
+   *
+   * Stateful lanes are keyed by session, so deleting a DSH session would otherwise leave one agent
+   * transport per connection alive for the life of the host process (and with it the daemon-side jobs/LSP
+   * ownership records that transport created). Other lanes are untouched.
+   *
+   * @param sessionKey - the DSH session id used when the stateful lane was acquired.
+   */
+  async releaseSession(sessionKey2) {
+    this.#releaseGeneration++;
+    const disposals = [];
+    for (const [connectionId, keys] of [...this.#slots]) {
+      for (const key of [...keys]) {
+        if (key !== laneKey(connectionId, { lane: "stateful", sessionKey: sessionKey2 })) continue;
+        if (this.#pending.has(key)) this.#retired.add(key);
+        const entry = this.#entries.get(key);
+        this.#entries.delete(key);
+        keys.delete(key);
+        if (entry !== void 0) {
+          disposals.push((async () => {
+            const sessionAware = entry.transport;
+            if (typeof sessionAware.endSession === "function") {
+              await sessionAware.endSession(sessionKey2).catch(() => void 0);
+            }
+            await entry.transport.dispose().catch(() => void 0);
+          })());
+        }
+      }
+      if (keys.size === 0) this.#slots.delete(connectionId);
+    }
+    await Promise.all(disposals);
+  }
+  /** Dispose every connection and lane (plugin unload, connection-service shutdown). */
   async disposeAll() {
-    for (const id of this.#pending.keys()) this.#retired.add(id);
-    await Promise.all([...this.#entries.keys()].map((id) => this.#discard(id)));
+    this.#releaseGeneration++;
+    for (const key of this.#pending.keys()) this.#retired.add(key);
+    await Promise.all([...this.#slots.keys()].map((id) => this.#discard(id)));
   }
-  #create(profile, decision) {
+  #create(profile, decision, lane, sessionKey2) {
     if (decision.kind === "agent") {
       if (this.#factories.createAgent === void 0) {
         throw new SshDevError("CONNECTION_INVALID", "\u9009\u62E9\u5668\u9009\u4E86 Tier 2 \u4EE3\u7406\uFF0C\u4F46\u6CA1\u6709\u6CE8\u518C\u4EE3\u7406\u5DE5\u5382", { connectionId: profile.id });
       }
-      return this.#factories.createAgent(profile, decision);
+      return this.#factories.createAgent(profile, decision, lane, sessionKey2);
     }
     return decision.kind === "ssh2" ? this.#factories.createSsh2(profile, decision) : this.#factories.createAlias(profile, decision);
   }
+  /** Record that a profile owns a cache key (idempotent). */
+  #rememberSlot(connectionId, key) {
+    const keys = this.#slots.get(connectionId);
+    if (keys === void 0) {
+      this.#slots.set(connectionId, /* @__PURE__ */ new Set([key]));
+      return;
+    }
+    keys.add(key);
+  }
+  /** Drop a slot key once neither a cached entry nor an in-flight attempt uses it. */
+  #forgetSlotIfIdle(connectionId, key) {
+    if (this.#entries.has(key) || this.#pending.has(key)) return;
+    const keys = this.#slots.get(connectionId);
+    if (keys === void 0) return;
+    keys.delete(key);
+    if (keys.size === 0) this.#slots.delete(connectionId);
+  }
   async #discard(connectionId) {
-    if (this.#pending.has(connectionId)) this.#retired.add(connectionId);
-    const entry = this.#entries.get(connectionId);
-    this.#entries.delete(connectionId);
-    if (entry !== void 0) await entry.transport.dispose().catch(() => void 0);
+    const keys = [...this.#slots.get(connectionId) ?? []];
+    for (const key of keys) {
+      if (this.#pending.has(key)) this.#retired.add(key);
+    }
+    const entries = keys.map((key) => {
+      const entry = this.#entries.get(key);
+      this.#entries.delete(key);
+      return entry;
+    });
+    this.#slots.delete(connectionId);
+    await Promise.all(entries.map(async (entry) => {
+      if (entry !== void 0) await entry.transport.dispose().catch(() => void 0);
+    }));
   }
 };
 
@@ -1932,6 +2064,17 @@ var Config = z.object({
     transferChunkBytes: z.natural().default(4 * 1024 * 1024),
     /** Chunks in flight at once during a transfer. 1 restores the sequential behaviour. */
     transferConcurrency: z.natural().default(4),
+    /**
+     * Split one connection into traffic lanes (`interactive` / `bulk` / `compute`).
+     *
+     * On by default: transfers then open their own transport instead of competing with an interactive
+     * `remote_exec` for the connection's in-flight window. A lane that fails to connect falls back to the
+     * interactive transport, and turning this off restores exactly the pre-lane behaviour (one transport
+     * per connection). `stateful` carries long-lived job/LSP/watch state (watch uses a dedicated per-session key when an ambient session id is available).
+     */
+    transportLanes: z.boolean().default(true),
+    /** Upper bound on concurrent stateful lane transports per connection, separately for job/LSP sessions and watch (default 8 each). */
+    statefulLanes: z.natural().default(8),
     /** How many finished transfers the progress table retains (FR-2.6.4). */
     transferHistoryEntries: z.natural().default(50),
     // 根内回收站目录名（`<root>/<binDir>`）。改过名（`.dsh-remote-workspace/trash` → 这里）：旧目录仍被
@@ -2410,9 +2553,14 @@ function parseGrepArgs(args) {
     caseSensitive: record2["caseSensitive"] === true,
     noIgnore: record2["noIgnore"] === true,
     include: include.values.length === 0 ? void 0 : include.values,
-    maxResults: clampInt(record2["maxResults"], MAX_GREP_RESULTS, MAX_GREP_RESULTS)
+    maxResults: clampInt(record2["maxResults"], MAX_GREP_RESULTS, MAX_GREP_RESULTS),
+    offset: clampOffset(record2["offset"])
   };
 }
+function clampOffset(value) {
+  const number = typeof value === "number" && Number.isFinite(value) ? Math.floor(value) : 0;
+  return Math.max(0, number);
+}
 function parseGlobArgs(args) {
   const record2 = args ?? {};
   const raw = record2["pattern"];
@@ -2569,7 +2717,7 @@ function readSearchTruncation(raw) {
 function searchTruncationAdvice(reason) {
   switch (reason) {
     case "maxResults":
-      return "\u547D\u4E2D\u6761\u6570\u5230\u9876\uFF08maxResults\uFF09\uFF1A\u7528\u66F4\u5177\u4F53\u7684 pattern\u3001\u52A0 include \u8FC7\u6EE4\uFF0C\u6216\u7F29\u5C0F path \u540E\u91CD\u8DD1\u3002";
+      return "\u547D\u4E2D\u6761\u6570\u5230\u9876\uFF08maxResults\uFF09\uFF1A\u7528\u8FD4\u56DE\u7684 nextOffset \u4F5C\u4E3A offset \u7EE7\u7EED\u7FFB\u9875\uFF0C\u6216\u6536\u7A84 pattern/include/path\u3002";
     case "bytesScanned":
       return "\u626B\u63CF\u5B57\u8282\u6570\u5230\u9876\uFF08bytesScanned\uFF09\uFF1A\u7F29\u5C0F path \u6216\u52A0 include\uFF0C\u907F\u514D\u6574\u6811\u626B\u63CF\u3002";
     case "maxFileBytes":
@@ -4372,6 +4520,7 @@ function parseSessionTrashIndex(text8) {
       segment: record2["segment"],
       originalSegment: record2["originalSegment"],
       title: typeof record2["title"] === "string" ? record2["title"] : void 0,
+      ...typeof record2["parentSessionId"] === "string" && record2["parentSessionId"] !== "" ? { parentSessionId: record2["parentSessionId"] } : {},
       bytes: typeof record2["bytes"] === "number" && Number.isFinite(record2["bytes"]) ? record2["bytes"] : 0,
       deletedAtMs: record2["deletedAtMs"],
       movedBy: record2["movedBy"] === "copy" ? "copy" : "rename",
@@ -4418,6 +4567,7 @@ function makeSessionTrashEntry(input) {
     segment: input.segment,
     originalSegment: input.originalSegment,
     title: input.title,
+    ...input.parentSessionId === void 0 ? {} : { parentSessionId: input.parentSessionId },
     bytes: input.bytes,
     deletedAtMs: input.deletedAtMs,
     movedBy: input.movedBy,
@@ -4693,6 +4843,7 @@ function createSessionAdminDelete(ctx) {
             segment: entryId,
             originalSegment: record2.segment,
             title: record2.title,
+            parentSessionId: record2.parentSessionId,
             bytes: record2.bytes,
             deletedAtMs,
             movedBy,
@@ -4810,31 +4961,63 @@ function createSessionAdminService(deps) {
     if (entry === void 0) {
       throw new SshDevError("TRASH_NOT_FOUND", `\u56DE\u6536\u7AD9\u6761\u76EE\u4E0D\u5B58\u5728\uFF1A${entryId}`, { entryId });
     }
-    const target = joinPath(sessionsRoot, entry.projectDir, entry.originalSegment);
-    const occupied = await deps.stat(target) !== void 0;
-    const plan = planRestoreSession(entry, { occupied });
-    if (plan.kind === "refuse") {
-      throw new SshDevError("TRANSFER_CONFLICT", `\u539F\u8DEF\u5F84\u5DF2\u88AB\u5360\u7528\uFF0C\u62D2\u7EDD\u9759\u9ED8\u6362\u540D\u8FD8\u539F\uFF1A${target}`, {
-        entryId,
-        suggestedId: plan.suggestedId,
-        target
-      });
-    }
-    const from = entryDir(entry.segment);
-    let movedBy;
-    try {
-      movedBy = await deps.moveDir(from, target);
-    } catch (error) {
-      const landed = await deps.stat(target) !== void 0;
-      if (!landed) {
-        throw new SshDevError("REMOTE_COMMAND_FAILED", `\u8FD8\u539F\u4F1A\u8BDD\u5931\u8D25\uFF1A${entry.sessionId}`, {
-          entryId,
-          cause: error instanceof Error ? error.message : String(error)
+    const restoreOne = async (item) => {
+      const target = joinPath(sessionsRoot, item.projectDir, item.originalSegment);
+      const occupied = await deps.stat(target) !== void 0;
+      const plan = planRestoreSession(item, { occupied });
+      if (plan.kind === "refuse") {
+        throw new SshDevError("TRANSFER_CONFLICT", `\u539F\u8DEF\u5F84\u5DF2\u88AB\u5360\u7528\uFF0C\u62D2\u7EDD\u9759\u9ED8\u6362\u540D\u8FD8\u539F\uFF1A${target}`, {
+          entryId: item.id,
+          suggestedId: plan.suggestedId,
+          target
+        });
+      }
+      const from = entryDir(item.segment);
+      let movedBy;
+      try {
+        movedBy = await deps.moveDir(from, target);
+      } catch (error) {
+        const landed = await deps.stat(target) !== void 0;
+        if (!landed) {
+          throw new SshDevError("REMOTE_COMMAND_FAILED", `\u8FD8\u539F\u4F1A\u8BDD\u5931\u8D25\uFF1A${item.sessionId}`, {
+            entryId: item.id,
+            cause: error instanceof Error ? error.message : String(error)
+          });
+        }
+        movedBy = "copy";
+      }
+      return { entry: item, restoredPath: target, movedBy };
+    };
+    const parentStillBinned = entry.parentSessionId !== void 0 && entries.some((item) => item.sessionId === entry.parentSessionId);
+    const restored = await restoreOne(entry);
+    const childrenOf = /* @__PURE__ */ new Map();
+    for (const item of entries) {
+      if (item.id === entry.id || item.parentSessionId === void 0) continue;
+      const bucket = childrenOf.get(item.parentSessionId);
+      if (bucket === void 0) childrenOf.set(item.parentSessionId, [item]);
+      else bucket.push(item);
+    }
+    const restoredSubsessions = [];
+    const failedSubsessions = [];
+    const removedIds = /* @__PURE__ */ new Set([entry.id]);
+    const queue = [...childrenOf.get(entry.sessionId) ?? []];
+    while (queue.length > 0) {
+      const child = queue.shift();
+      if (child === void 0) break;
+      if (removedIds.has(child.id)) continue;
+      try {
+        const childRestored = await restoreOne(child);
+        restoredSubsessions.push({ sessionId: child.sessionId, restoredPath: childRestored.restoredPath });
+        removedIds.add(child.id);
+        queue.push(...childrenOf.get(child.sessionId) ?? []);
+      } catch (error) {
+        failedSubsessions.push({
+          sessionId: child.sessionId,
+          reason: error instanceof Error ? error.message : String(error)
         });
       }
-      movedBy = "copy";
     }
-    const remaining = entries.filter((item) => item.id !== entryId);
+    const remaining = entries.filter((item) => !removedIds.has(item.id));
     try {
       await writeIndex(remaining);
     } catch (error) {
@@ -4843,7 +5026,7 @@ function createSessionAdminService(deps) {
         cause: error instanceof Error ? error.message : String(error)
       });
     }
-    return { entry, restoredPath: target, movedBy };
+    return { ...restored, restoredSubsessions, failedSubsessions, parentStillBinned };
   });
   const purge = (entryId, options = {}) => {
     void options;
@@ -6447,14 +6630,26 @@ init_errors();
 
 // src/host/infra/transport/agent/agent-protocol-frames.ts
 init_errors();
-var AGENT_PROTOCOL_VERSION = 1;
+import { constants as zlibConstants, zstdCompressSync, zstdDecompressSync } from "node:zlib";
+var AGENT_PROTOCOL_VERSION = 3;
 var AGENT_CLIENT_ID = "dsh-over-ssh/0.1.0";
 var MAX_AGENT_FRAME_BYTES = 16 << 20;
+var AGENT_FRAME_FLAG_ZSTD = 1;
+var AGENT_ZSTD_MIN_BYTES = 512;
+var ZSTD_LEVEL = 1;
+function zstdCompress(payload) {
+  return zstdCompressSync(payload, { params: { [zlibConstants.ZSTD_c_compressionLevel]: ZSTD_LEVEL } });
+}
+function likelyCompressible(payload) {
+  const sample = payload.byteLength > 2048 ? payload.subarray(0, 2048) : payload;
+  const compressed = zstdCompress(sample);
+  return compressed.byteLength < sample.byteLength * 0.9;
+}
 var AGENT_KIND_JSON = 74;
 var AGENT_KIND_BLOB = 66;
 var DEFAULT_AGENT_WATCHER_ID = "default";
 var DEFAULT_AGENT_REQUEST_TIMEOUT_MS = 15e3;
-var DEFAULT_AGENT_MAX_IN_FLIGHT = 8;
+var DEFAULT_AGENT_MAX_IN_FLIGHT = 16;
 var DEFAULT_AGENT_MODE = "--shared";
 var AgentProtocolError = class extends Error {
   code;
@@ -6476,10 +6671,20 @@ function encodeFrame(kind, payload) {
       limit: MAX_AGENT_FRAME_BYTES
     });
   }
-  const header = new Uint8Array(5);
+  let body = payload;
+  let flags = 0;
+  if (payload.byteLength >= AGENT_ZSTD_MIN_BYTES && (payload.byteLength <= 4096 || likelyCompressible(payload))) {
+    const compressed = zstdCompress(payload);
+    if (compressed.byteLength < payload.byteLength) {
+      body = compressed;
+      flags = AGENT_FRAME_FLAG_ZSTD;
+    }
+  }
+  const header = new Uint8Array(6);
   header[0] = kind;
-  new DataView(header.buffer).setUint32(1, payload.byteLength, false);
-  return { header, payload };
+  header[1] = flags;
+  new DataView(header.buffer).setUint32(2, body.byteLength, false);
+  return { header, payload: body };
 }
 function encodeFrameBytes(kind, payload) {
   const { header, payload: body } = encodeFrame(kind, payload);
@@ -6489,24 +6694,44 @@ function encodeFrameBytes(kind, payload) {
   return frame;
 }
 function decodeFrame(bytes) {
-  if (bytes.byteLength < 5) return null;
+  if (bytes.byteLength < 6) return null;
   const kind = bytes[0];
-  const length = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength).getUint32(1, false);
+  const flags = bytes[1];
+  const length = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength).getUint32(2, false);
   if (kind !== AGENT_KIND_JSON && kind !== AGENT_KIND_BLOB) {
     throw new AgentProtocolError("E_PROTOCOL", `\u672A\u77E5\u7684\u5E27\u7C7B\u578B\uFF1A${kind}`, { kind });
   }
+  if ((flags & ~AGENT_FRAME_FLAG_ZSTD) !== 0) {
+    throw new AgentProtocolError("E_PROTOCOL", `\u672A\u77E5\u7684\u5E27\u6807\u5FD7\uFF1A${flags}`, { flags });
+  }
   if (length > MAX_AGENT_FRAME_BYTES) {
     throw new AgentProtocolError("E_TOO_LARGE", `\u58F0\u660E\u957F\u5EA6\u8D85\u8FC7\u4E0A\u9650\uFF08${length} > ${MAX_AGENT_FRAME_BYTES}\uFF09`, {
       declared: length,
       limit: MAX_AGENT_FRAME_BYTES
     });
   }
-  if (bytes.byteLength - 5 < length) return null;
-  return { frame: { kind, payload: bytes.slice(5, 5 + length) }, consumed: 5 + length };
+  if (bytes.byteLength - 6 < length) return null;
+  let payload = bytes.slice(6, 6 + length);
+  if ((flags & AGENT_FRAME_FLAG_ZSTD) !== 0) {
+    try {
+      payload = zstdDecompressSync(payload, { maxOutputLength: MAX_AGENT_FRAME_BYTES + 1 });
+    } catch (error) {
+      if (error instanceof RangeError) {
+        throw new AgentProtocolError("E_TOO_LARGE", "\u89E3\u538B\u540E\u5E27\u8D85\u8FC7\u4E0A\u9650", { limit: MAX_AGENT_FRAME_BYTES });
+      }
+      throw new AgentProtocolError("E_PROTOCOL", "zstd \u5E27\u89E3\u538B\u5931\u8D25", { reason: error instanceof Error ? error.message : String(error) });
+    }
+    if (payload.byteLength > MAX_AGENT_FRAME_BYTES) {
+      throw new AgentProtocolError("E_TOO_LARGE", `\u89E3\u538B\u540E\u5E27\u8D85\u8FC7\u4E0A\u9650\uFF08${payload.byteLength}\uFF09`, { limit: MAX_AGENT_FRAME_BYTES });
+    }
+  }
+  return { frame: { kind, payload }, consumed: 6 + length };
 }
 var COMPACT_MIN_BYTES = 64 * 1024;
+var IDLE_STORE_BYTES = 64 * 1024;
 function growTo(needed) {
-  return Math.min(Math.max(needed * 2, 64 * 1024), MAX_AGENT_FRAME_BYTES + 64 * 1024 + 5);
+  const capped = Math.min(Math.max(needed * 2, 64 * 1024), MAX_AGENT_FRAME_BYTES + 64 * 1024 + 6);
+  return Math.max(capped, needed);
 }
 var AgentFrameParser = class {
   /** Backing store. Its **capacity** may exceed the bytes in use — see {@link growTo}. */
@@ -6533,6 +6758,7 @@ var AgentFrameParser = class {
     if (this.#start === this.#end) {
       this.#start = 0;
       this.#end = 0;
+      if (this.#store.byteLength > IDLE_STORE_BYTES) this.#store = new Uint8Array(IDLE_STORE_BYTES);
     } else if (this.#start >= COMPACT_MIN_BYTES) {
       this.#shift();
     }
@@ -6636,6 +6862,7 @@ function capabilitiesFromAgent(caps, extras = {}) {
     git: source.git === true,
     ripgrep: source.ripgrep === true,
     grep: source.grep === true,
+    ...source.grepPaging === void 0 ? {} : { grepPaging: source.grepPaging === true },
     base64: false,
     findMaxDepth: false,
     sha256: null,
@@ -6671,6 +6898,14 @@ function readAgentCaps(result) {
     ...typeof caps["grep"] === "boolean" ? { grep: caps["grep"] } : {},
     ...typeof caps["exec"] === "boolean" ? { exec: caps["exec"] } : {},
     ...typeof caps["cancel"] === "boolean" ? { cancel: caps["cancel"] } : {},
+    // 增补能力位：新增字段时**必须**在这里放行，否则 hello 发了、宿主也永远看不到（分页门禁就是靠它）。
+    ...typeof caps["batch"] === "boolean" ? { batch: caps["batch"] } : {},
+    ...typeof caps["readGzip"] === "boolean" ? { readGzip: caps["readGzip"] } : {},
+    ...typeof caps["repoSummary"] === "boolean" ? { repoSummary: caps["repoSummary"] } : {},
+    ...typeof caps["patchMany"] === "boolean" ? { patchMany: caps["patchMany"] } : {},
+    ...typeof caps["grepPaging"] === "boolean" ? { grepPaging: caps["grepPaging"] } : {},
+    ...typeof caps["netProbe"] === "boolean" ? { netProbe: caps["netProbe"] } : {},
+    ...typeof caps["resumableUpload"] === "boolean" ? { resumableUpload: caps["resumableUpload"] } : {},
     ...readLspServers(caps["lspServers"])
   };
 }
@@ -6890,7 +7125,9 @@ function readSearchResult(value) {
     truncatedReasons: readStringArray(record2, "truncatedReasons"),
     // `?? undefined` because the helper reports "absent" as `null`, and this field's "absent" must stay
     // distinct from a real `0`.
-    filesFiltered: readOptionalNumber(record2, "filesFiltered") ?? void 0
+    filesFiltered: readOptionalNumber(record2, "filesFiltered") ?? void 0,
+    total: readOptionalNumber(record2, "total"),
+    nextOffset: readOptionalNumber(record2, "nextOffset")
   };
 }
 function readWatchStartResult(value) {
@@ -7388,7 +7625,9 @@ var AgentProtocolClient = class {
     if (session !== void 0 && session !== "") envelope["session"] = session;
     try {
       this.#session.write(encodeFrameBytes(AGENT_KIND_JSON, TEXT_ENCODER.encode(JSON.stringify(envelope))));
-    } catch {
+    } catch (error) {
+      this.#pending.delete(id);
+      this.failConnection(new SshDevError("CONNECTION_LOST", `\u5411\u4EE3\u7406\u5199\u5165 cancel \u5E27\u5931\u8D25\uFF1A${error instanceof Error ? error.message : String(error)}`, { method: "cancel" }));
     }
   }
   #deadlineError(method) {
@@ -7895,6 +8134,7 @@ function createNodeLongSpawner() {
 
 // src/host/infra/transport/agent/agent-transport.ts
 init_transport_base();
+import { gunzipSync } from "node:zlib";
 var DEFAULT_AGENT_PATH = "~/.dsh/over-ssh/dsh-over-ssh-agent";
 var AgentTransport = class extends TransportBase {
   id;
@@ -8116,6 +8356,8 @@ var AgentTransport = class extends TransportBase {
       timedOut: record2["timedOut"] === true,
       stdout,
       stderr,
+      ...nonEmptyString(record2["stdoutBase64"]) === void 0 ? {} : { stdoutBase64: nonEmptyString(record2["stdoutBase64"]) },
+      ...nonEmptyString(record2["stderrBase64"]) === void 0 ? {} : { stderrBase64: nonEmptyString(record2["stderrBase64"]) },
       durationMs: agentDuration ?? Math.max(0, this.#now() - startedAt),
       // The combined alias stays honest about what it covers: either stream was cut.
       truncated: stdoutTruncated || stderrTruncated,
@@ -8161,6 +8403,90 @@ var AgentTransport = class extends TransportBase {
       version: version ?? ""
     };
   }
+  /** Remote TCP reachability preflight (`net.probe`). */
+  async netProbe(host, port, signal) {
+    const result = await this.#rpc("net.probe", { host, port }, signal);
+    const record2 = asRecord(result) ?? {};
+    return {
+      reachable: record2["reachable"] === true,
+      ...typeof record2["error"] === "string" && record2["error"] !== "" ? { error: record2["error"] } : {}
+    };
+  }
+  /** One-round-trip project overview (`repo.summary`). */
+  async repoSummary(root, signal) {
+    await this.connect(signal);
+    const client = this.#requireClient();
+    let result;
+    try {
+      result = await client.request("repo.summary", { root }, this.#requestOptions(void 0, signal));
+    } catch (error) {
+      throw this.#translate(error);
+    }
+    const record2 = asRecord(result);
+    if (record2 === void 0) throw new Error("repo.summary \u8FD4\u56DE\u4E86\u65E0\u6CD5\u89E3\u6790\u7684\u7ED3\u679C");
+    return record2;
+  }
+  /** Multi-file edit in one round trip (`fs.patchMany`). */
+  async patchMany(edits, atomic, signal) {
+    await this.connect(signal);
+    const client = this.#requireClient();
+    let result;
+    try {
+      result = await client.request("fs.patchMany", { edits, atomic }, this.#requestOptions(void 0, signal));
+    } catch (error) {
+      throw this.#translate(error);
+    }
+    const record2 = asRecord(result);
+    if (record2 === void 0) throw new Error("fs.patchMany \u8FD4\u56DE\u4E86\u65E0\u6CD5\u89E3\u6790\u7684\u7ED3\u679C");
+    return record2;
+  }
+  /**
+   * Read several file ranges in one `fs.readMany` round trip.
+   *
+   * Per-item `encoding: "gzip"` payloads are gunzipped here; a single item's failure stays in its item.
+   * Older agents answer `E_METHOD`; `#translate` turns that into `REMOTE_UNSUPPORTED` for the caller's
+   * fallback path.
+   */
+  async batchRead(requests, signal) {
+    await this.connect(signal);
+    const client = this.#requireClient();
+    let result;
+    try {
+      result = await client.request("fs.readMany", {
+        requests: requests.map((request) => ({
+          path: request.path,
+          ...request.offset === void 0 ? {} : { offset: request.offset },
+          ...request.maxBytes === void 0 ? {} : { maxBytes: request.maxBytes }
+        }))
+        // 帧层已对 ≥512 B 的帧做 zstd；这里再要求逐条压缩会让同一段文本被压两遍。
+      }, this.#requestOptions(void 0, signal));
+    } catch (error) {
+      throw this.#translate(error);
+    }
+    const record2 = asRecord(result) ?? {};
+    const items = Array.isArray(record2["items"]) ? record2["items"] : [];
+    const chunks = [];
+    for (const raw of items) {
+      const item = asRecord(raw);
+      if (item === void 0) continue;
+      const path = typeof item["path"] === "string" ? item["path"] : "";
+      const exists = item["exists"] === true;
+      const dataBase64 = typeof item["dataBase64"] === "string" ? item["dataBase64"] : "";
+      let bytes = new Uint8Array(0);
+      if (dataBase64 !== "" && item["encoding"] !== "gzip") bytes = Buffer.from(dataBase64, "base64");
+      else if (dataBase64 !== "") bytes = gunzipSync(Buffer.from(dataBase64, "base64"));
+      chunks.push({
+        path,
+        exists,
+        size: typeof item["size"] === "number" ? item["size"] : bytes.byteLength,
+        version: typeof item["version"] === "string" ? item["version"] : "",
+        truncated: item["truncated"] === true,
+        bytes,
+        ...typeof item["error"] === "string" && item["error"] !== "" ? { error: item["error"] } : {}
+      });
+    }
+    return chunks;
+  }
   /**
    * Read a remote file: `fs.read` (control frame) followed by its blob frame.
    *
@@ -8215,6 +8541,9 @@ var AgentTransport = class extends TransportBase {
    */
   async writeFile(request, signal) {
     await this.connect(signal);
+    if (!(request.bytes instanceof Uint8Array)) {
+      throw new SshDevError("CONNECTION_INVALID", "writeFile \u9700\u8981 Uint8Array \u7C7B\u578B\u7684 bytes", { path: request.path });
+    }
     const client = this.#requireClient();
     const expected = request.expectedVersion ?? request.expectedSha256;
     let expectedVersion;
@@ -8753,9 +9082,16 @@ var AgentTransport = class extends TransportBase {
       state: typeof record2["state"] === "string" ? record2["state"] : "unknown"
     };
   }
-  /** Read a language server's output from `offset`: `lsp.read`. Same offset semantics as {@link procOutput}. */
-  async lspRead(id, offset = 0, signal) {
-    const result = await this.#rpc("lsp.read", { id, offset }, signal);
+  /**
+   * Read a language server's output from `offset`: `lsp.read`. Same offset semantics as {@link procOutput}.
+   *
+   * `maxBytes` bounds one response. The agent defaults it to its 2 MiB chunk; callers that poll (the LSP pump)
+   * pass a smaller cap so a quiet server does not cost 2 MiB of transient host memory per poll. Agents older
+   * than the field ignore it (Go's JSON decoder ignores unknown fields), so it is safe to always send.
+   */
+  async lspRead(id, offset = 0, signal, maxBytes) {
+    const params = maxBytes === void 0 ? { id, offset } : { id, offset, maxBytes: Math.max(1, Math.floor(maxBytes)) };
+    const result = await this.#rpc("lsp.read", params, signal);
     return readLspRead(result);
   }
   /** One language-server session's state: `lsp.status`. */
@@ -8831,7 +9167,9 @@ var AgentTransport = class extends TransportBase {
       ...request.include === void 0 ? {} : { include: [...request.include] },
       // Sent only when the caller asked for it: omitting the key leaves the agent's own default in force, so
       // an older agent that never heard of the field keeps behaving exactly as before.
-      ...request.noIgnore === void 0 ? {} : { noIgnore: request.noIgnore }
+      ...request.noIgnore === void 0 ? {} : { noIgnore: request.noIgnore },
+      ...request.offset === void 0 ? {} : { offset: request.offset },
+      ...request.limit === void 0 ? {} : { limit: request.limit }
     };
     const result = await this.#rpc("search.grep", params, signal);
     return readSearchResult(result);
@@ -9199,6 +9537,8 @@ var defaultLauncher = async (options) => {
 };
 var ChildProcessSession = class {
   #child;
+  /** One shared drain waiter: 16 concurrent requests must not add 16×3 stdin listeners. */
+  #draining;
   constructor(child) {
     this.#child = child;
     this.#child.stdin?.on?.("error", () => void 0);
@@ -9219,12 +9559,14 @@ var ChildProcessSession = class {
    * Resolve once the pipe has drained (or ended).
    *
    * 不等 `'drain'` 会把整个文件堆进 Node 的流缓冲：实测 8 × 15 MiB 打到不读的对端，进程里堆了
-   * 120 MiB——那是在 agent 侧 192 MiB 上限**之外**的另一份。end/error 也要收，否则对端一死就永远等。
+   * 120 MiB——那是在 agent 侧窗口/排队上限**之外**的另一份。end/error 也要收，否则对端一死就永远等。
    */
   drain() {
     const stdin = this.#child.stdin;
     if (stdin === void 0 || stdin === null || stdin.once === void 0) return Promise.resolve();
-    return new Promise((resolve3) => {
+    const existing = this.#draining;
+    if (existing !== void 0) return existing;
+    const pending2 = new Promise((resolve3) => {
       let settled = false;
       const done = () => {
         if (settled) return;
@@ -9232,12 +9574,15 @@ var ChildProcessSession = class {
         stdin.removeListener?.("drain", done);
         stdin.removeListener?.("error", done);
         stdin.removeListener?.("close", done);
+        this.#draining = void 0;
         resolve3();
       };
       stdin.once?.("drain", done);
       stdin.once?.("error", done);
       stdin.once?.("close", done);
     });
+    this.#draining = pending2;
+    return pending2;
   }
   onData(callback) {
     this.#child.stdout?.on("data", callback);
@@ -10321,9 +10666,25 @@ function parentRemotePath(absolute) {
   return remoteDirname(absolute);
 }
 var UTF8 = new TextDecoder("utf-8", { ignoreBOM: true });
+var UTF8_FATAL = new TextDecoder("utf-8", { ignoreBOM: true, fatal: true });
+function toBackendText(bytes, size, truncated, version) {
+  try {
+    return { text: UTF8_FATAL.decode(bytes), size, truncated, version };
+  } catch {
+    return {
+      text: UTF8.decode(bytes),
+      size,
+      truncated,
+      version,
+      binary: true,
+      dataBase64: Buffer.from(bytes).toString("base64")
+    };
+  }
+}
 var POLL_LISTING_SHARE_TTL_MS = 1e3;
 var STAT_CACHE_TTL_MS = 5e3;
 var STAT_CACHE_MAX_ENTRIES = 2048;
+var POLL_LISTING_MAX_ENTRIES = 64;
 var DEFAULT_CACHE = { ttlMs: 5e3, maxEntries: 256, maxBytes: 8 * 1024 * 1024 };
 var STAT_MARKER = "# DSH_STAT";
 var BATCH_MARKER = "#DSH_F ";
@@ -10341,12 +10702,7 @@ function parseBatchRead(stdout, cap) {
       missing.push(path);
     } else {
       const bytes = base64Body === "" ? Buffer.alloc(0) : Buffer.from(base64Body, "base64");
-      chunks.set(path, {
-        text: bytes.toString("utf8"),
-        size,
-        truncated: size > cap,
-        version: `${size}:${Math.floor(mtimeSeconds)}`
-      });
+      chunks.set(path, toBackendText(bytes, size, size > cap, `${size}:${Math.floor(mtimeSeconds)}`));
     }
     path = void 0;
     size = void 0;
@@ -10685,16 +11041,31 @@ var RemoteBackend = class {
     this.#invalidatePath(absolute);
     return { bytes: result.bytes, version: result.version, hunks: result.hunks };
   }
+  async repoSummary(root, signal) {
+    const transport = this.#options.repoSummaryTransport === void 0 ? await this.#transport() : await this.#options.repoSummaryTransport();
+    if (transport.repoSummary === void 0) {
+      throw new SshDevError("REMOTE_UNSUPPORTED", "\u8BE5\u4F20\u8F93\u6CA1\u6709 repo.summary\uFF08\u4EE3\u7406\u592A\u65E7\uFF0C\u91CD\u88C5/\u5347\u7EA7\u4EE3\u7406\uFF09", { root });
+    }
+    return transport.repoSummary(root, signal);
+  }
+  async patchMany(edits, atomic, signal) {
+    const transport = await this.#transport();
+    if (transport.patchMany === void 0) {
+      throw new SshDevError("REMOTE_UNSUPPORTED", "\u8BE5\u4F20\u8F93\u6CA1\u6709 fs.patchMany\uFF08\u4EE3\u7406\u592A\u65E7\uFF0C\u91CD\u88C5/\u5347\u7EA7\u4EE3\u7406\uFF09", { count: edits.length });
+    }
+    const result = await transport.patchMany(edits, atomic, signal);
+    if (result["rolledBack"] !== true) {
+      for (const edit of edits) this.#invalidatePath(edit.path);
+    }
+    return result;
+  }
   async readText(absolute, maxBytes, signal) {
     const chunk = await this.readBytes(absolute, maxBytes, signal);
     return {
       // `TextDecoder` 直接解码字节，`Buffer.from(...).toString()` 要先**整份拷贝**再解码——9 MiB 的文件
       // 就是白白多一次 9 MiB 的 memcpy。`fs-provider` 早就这么做了，这条读路径漏了。
       // `ignoreBOM: true`：默认行为会把 BOM 吃掉，而 `Buffer#toString` 不会，两者必须一致。
-      text: UTF8.decode(chunk.bytes),
-      size: chunk.size,
-      truncated: chunk.truncated,
-      version: chunk.version
+      ...toBackendText(chunk.bytes, chunk.size, chunk.truncated, chunk.version)
     };
   }
   /**
@@ -10743,6 +11114,19 @@ var RemoteBackend = class {
   async #readManyUncached(absolutePaths, options) {
     const transport = await this.#transport();
     const cap = Math.max(0, Math.min(Math.floor(options.maxBytesEach), this.#maxReadBytes));
+    if (transport.batchRead !== void 0) {
+      const chunks2 = await transport.batchRead(
+        absolutePaths.map((path) => ({ path, maxBytes: cap })),
+        options.signal
+      );
+      const texts = absolutePaths.map((path, index) => {
+        const chunk = chunks2[index];
+        if (chunk === void 0 || !chunk.exists || chunk.error !== void 0) return void 0;
+        return toBackendText(chunk.bytes, chunk.size, chunk.truncated, chunk.version);
+      });
+      const missing2 = absolutePaths.filter((path, index) => texts[index] === void 0);
+      return { chunks: texts, missing: [...new Set(missing2)] };
+    }
     const unframeable = absolutePaths.filter((path) => path.includes("\n") || path.includes("\r"));
     const unframeableSet = new Set(unframeable);
     const frameable = absolutePaths.filter((path) => !unframeableSet.has(path));
@@ -10901,7 +11285,7 @@ var RemoteBackend = class {
    *   `CANCELLED` when aborted during setup.
    */
   async watch(absolute, changed, signal) {
-    const transport = await this.#transport();
+    const transport = this.#options.watchTransport === void 0 ? await this.#transport() : await this.#options.watchTransport();
     if (!isWatchCapable(transport)) {
       return this.#watchByPolling(absolute, changed, signal);
     }
@@ -11039,6 +11423,10 @@ var RemoteBackend = class {
     })();
     const entry = { at: now, promise };
     this.#pollListings.set(root, entry);
+    if (this.#pollListings.size > POLL_LISTING_MAX_ENTRIES) {
+      const oldest = this.#pollListings.keys().next();
+      if (!oldest.done) this.#pollListings.delete(oldest.value);
+    }
     promise.catch(() => {
       if (this.#pollListings.get(root) === entry) this.#pollListings.delete(root);
     });
@@ -12613,7 +13001,7 @@ function directoryProbeCommand(root) {
   return `test -d ${shellQuote(root)}`;
 }
 function rankMatches(paths, query, limit) {
-  const needle = query.trim().toLowerCase();
+  const needle = separatorsForMatching(query.trim().toLowerCase());
   if (needle === "") {
     const top = [];
     const better = (left, right) => {
@@ -12638,7 +13026,8 @@ function rankMatches(paths, query, limit) {
   }
   const scored = [];
   for (const path of paths) {
-    const lower = path.toLowerCase();
+    const normalized = separatorsForMatching(path);
+    const lower = normalized.toLowerCase();
     const base = lower.slice(lower.lastIndexOf("/") + 1);
     let score;
     if (base.startsWith(needle)) score = 0;
@@ -12653,11 +13042,15 @@ function rankMatches(paths, query, limit) {
   );
   return scored.slice(0, limit).map((entry) => entry.path);
 }
+function separatorsForMatching(path) {
+  return path.includes("\\") && !path.includes("/") ? path.replaceAll("\\", "/") : path;
+}
 function depth2(path) {
   let segments = 0;
   let inSegment = false;
   for (let index = 0; index < path.length; index += 1) {
-    if (path.charCodeAt(index) === 47) {
+    const code = path.charCodeAt(index);
+    if (code === 47 || code === 92) {
       inSegment = false;
       continue;
     }
@@ -13205,6 +13598,46 @@ function defaultAgentManifestPath(moduleUrl) {
 
 // src/wiring/connections.ts
 var degradedRetryMs = 3e4;
+var LANE_RETRY_AFTER_MS = 15e3;
+function createTransportLaneRouter(options) {
+  const retryAfter = /* @__PURE__ */ new Map();
+  return {
+    enabled: options.enabled,
+    releaseSession: async (sessionKey2) => {
+      if (!options.enabled) return;
+      const suffix = `\0stateful\0${sessionKey2}`;
+      for (const key of retryAfter.keys()) {
+        if (key.endsWith(suffix)) retryAfter.delete(key);
+      }
+      await options.transports.releaseSession(sessionKey2);
+    },
+    statefulSessions: () => options.enabled ? options.transports.statefulSessions() : [],
+    pruneStatefulSessions: async (isLive) => {
+      if (!options.enabled) return;
+      const now = Date.now();
+      for (const [key, until] of retryAfter) {
+        if (until <= now) retryAfter.delete(key);
+      }
+      await options.transports.pruneStatefulSessions(isLive);
+    },
+    async acquire(profile, lane = "interactive", signal, sessionKey2) {
+      if (!options.enabled || lane === "interactive") return options.transports.acquire(profile, signal);
+      const laneOptions = { lane, ...sessionKey2 === void 0 ? {} : { sessionKey: sessionKey2 } };
+      const laneId = `${profile.id}\0${lane}\0${sessionKey2 ?? ""}`;
+      if ((retryAfter.get(laneId) ?? 0) > Date.now()) return options.transports.acquire(profile, signal);
+      try {
+        const acquired = await options.transports.acquire(profile, laneOptions, signal);
+        retryAfter.delete(laneId);
+        return acquired;
+      } catch (error) {
+        if (signal?.aborted === true || isSshDevError(error) && error.code === "CANCELLED") throw error;
+        retryAfter.set(laneId, Date.now() + LANE_RETRY_AFTER_MS);
+        options.onFallback?.({ connectionId: profile.id, lane, error });
+        return options.transports.acquire(profile, signal);
+      }
+    }
+  };
+}
 function pruneBackendConnections(owners, liveRootKeys) {
   for (const backendId of [...owners.keys()]) {
     if (!liveRootKeys.has(backendId)) owners.delete(backendId);
@@ -13316,6 +13749,7 @@ function wireConnections(ctx, config) {
   const transports = new TransportService({
     selector,
     preflight: agentBridge.preflight,
+    statefulLaneLimit: limits.statefulLanes,
     factories: {
       createAlias: aliasFactory,
       createSsh2: (profile) => new Ssh2Transport({
@@ -13337,15 +13771,20 @@ function wireConnections(ctx, config) {
           });
         }
       }),
-      createAgent: (profile) => {
+      createAgent: (profile, _decision, lane, sessionKey2) => {
         const outcome = agentBridge.installationFor(profile.id);
         if (outcome === void 0 || outcome.kind !== "agent") {
           throw new SshDevError("REMOTE_UNSUPPORTED", "Tier 2 \u4EE3\u7406\u5C1A\u672A\u5C31\u7EEA\uFF1A\u5B89\u88C5\u9636\u68AF\u672A\u6210\u529F\uFF0C\u4E0D\u80FD\u521B\u5EFA\u4EE3\u7406\u4F20\u8F93", { connectionId: profile.id });
         }
         const helper = askpass.envFor(profile);
         const passwordOptions = passwordAskpassOptions(profile, helper);
+        const maxInFlight = lane === void 0 || lane === "interactive" ? void 0 : 8;
         return new AgentTransport({
           connectionId: profile.id,
+          ...maxInFlight === void 0 ? {} : { maxInFlight },
+          // Stateful lanes get a stable agent session id: their jobs/LSP/watch ownership must not
+          // collapse into the daemon's default session (or two DSH sessions would share one quota).
+          ...sessionKey2 === void 0 || sessionKey2 === "" ? {} : { sessionId: sessionKey2 },
           agentPath: outcome.remotePath,
           // Same credential source as the Tier 1 transport: an agent session that authenticates differently
           // from the ladder that installed it is exactly the drift the agent-path e2e caught. For a password
@@ -13366,6 +13805,15 @@ function wireConnections(ctx, config) {
       }
     }
   });
+  const transportLanes = createTransportLaneRouter({
+    transports,
+    enabled: limits.transportLanes !== false,
+    onFallback: ({ connectionId, lane, error }) => {
+      ctx.logger?.warn?.(
+        `[dsh-over-ssh] ${connectionId} \u7684 ${lane} lane \u4E0D\u53EF\u7528\uFF0C\u56DE\u9000\u5230 interactive\uFF1A${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+  });
   const remoteHome = createRemoteHomeResolver({
     probe: async (connectionId) => {
       const profile = profiles.get(connectionId);
@@ -13427,6 +13875,26 @@ function wireConnections(ctx, config) {
           }
           return (await transports.acquire(profile)).transport;
         },
+        // `repo.summary` is compute work (it may walk the tree and run git). It runs on the compute lane when
+        // available; reads/writes/listing stay interactive, watch has its own stateful lane below.
+        repoSummaryTransport: async () => {
+          const profile = profiles.get(connectionId);
+          if (profile === void 0) {
+            throw new SshDevError("CONNECTION_NOT_FOUND", `\u8FDC\u7AEF\u6839\u6307\u5411\u672A\u914D\u7F6E\u7684\u8FDE\u63A5\uFF1A${connectionId}`, { root: rootKey(root) });
+          }
+          return (await transportLanes.acquire(profile, "compute")).transport;
+        },
+        // watch.* is long-lived state. Give it a stateful lane per DSH session when the platform's
+        // AsyncLocalStorage carries one; fall back to one shared `watch` lane for agentless callers.
+        watchTransport: async () => {
+          const profile = profiles.get(connectionId);
+          if (profile === void 0) {
+            throw new SshDevError("CONNECTION_NOT_FOUND", `\u8FDC\u7AEF\u6839\u6307\u5411\u672A\u914D\u7F6E\u7684\u8FDE\u63A5\uFF1A${connectionId}`, { root: rootKey(root) });
+          }
+          const sessionId = currentSessionId();
+          const sessionKey2 = sessionId === void 0 || sessionId === "" ? "watch" : `watch:${sessionId}`;
+          return (await transportLanes.acquire(profile, "stateful", void 0, sessionKey2)).transport;
+        },
         // FR-2.7 is a budget, so it has to be reachable from Config: the defaults are the requirement's
         // numbers, and an operator can turn retention off per deployment without a rebuild.
         cache: {
@@ -13530,7 +13998,7 @@ function wireConnections(ctx, config) {
         // Tier 2 when this connection actually runs an agent that reports index support; otherwise this
         // throws and RemoteIndex falls through to the shell path (which is the floor).
         agentScan: async (root, request) => {
-          const { transport } = await transports.acquire(profile);
+          const { transport } = await transportLanes.acquire(profile, "compute");
           if (!(transport instanceof AgentTransport) || transport.agentCapabilities.index !== true) {
             throw new SshDevError("REMOTE_UNSUPPORTED", "\u8BE5\u8FDE\u63A5\u6CA1\u6709\u53EF\u7528\u7684\u4EE3\u7406\u7D22\u5F15", { connectionId });
           }
@@ -13547,7 +14015,7 @@ function wireConnections(ctx, config) {
         // `index.refresh` answers E_METHOD, which becomes REMOTE_UNSUPPORTED and makes RemoteIndex fall back
         // to `agentScan`  -  so wiring this can never regress a working connection into a failing one.
         agentRefresh: async (root, request) => {
-          const { transport } = await transports.acquire(profile);
+          const { transport } = await transportLanes.acquire(profile, "compute");
           if (!(transport instanceof AgentTransport) || transport.agentCapabilities.index !== true) {
             throw new SshDevError("REMOTE_UNSUPPORTED", "\u8BE5\u8FDE\u63A5\u6CA1\u6709\u53EF\u7528\u7684\u4EE3\u7406\u7D22\u5F15", { connectionId });
           }
@@ -13560,14 +14028,14 @@ function wireConnections(ctx, config) {
           return { paths: scan.entries.map((entry) => entry.path), strategy: scan.strategy, truncated: scan.truncated };
         },
         exec: async (command, options) => {
-          const { transport } = await transports.acquire(profile);
+          const { transport } = await transportLanes.acquire(profile, "compute");
           const result = await transport.exec(
             { script: command, maxBytes: options.maxBytes, timeoutMs: options.timeoutMs },
             options.signal
           );
           return { exitCode: result.exitCode, stdout: result.stdout, stderr: result.stderr, truncated: result.truncated };
         },
-        capabilities: async () => (await transports.acquire(profile)).transport.capabilities
+        capabilities: async () => (await transportLanes.acquire(profile, "compute")).transport.capabilities
       }
     });
     indexes.set(connectionId, created);
@@ -13582,7 +14050,7 @@ function wireConnections(ctx, config) {
       }));
     }
   };
-  return { ctx, config, limits, anchorRootDir, profiles, selector, askpass, installations, agentBridge, transports, remoteHome, forgetBackendsOf, browseBackends, readBytesRange, registry, directory, indexes, indexFor, index, cacheBudget };
+  return { ctx, config, limits, anchorRootDir, profiles, selector, askpass, installations, agentBridge, transports, transportLanes, remoteHome, forgetBackendsOf, browseBackends, readBytesRange, registry, directory, indexes, indexFor, index, cacheBudget };
 }
 function readLiveSessions(ctx) {
   let list;
@@ -13763,6 +14231,8 @@ function sessionToolDefinitions(service) {
             sessions: { type: "array", items: { type: "string" }, description: "`list`: one formatted line per session." },
             entries: { type: "array", items: { type: "string" }, description: "`restore` without an id: bin entry ids." },
             restoredPath: { type: "string", description: "`restore` with an id: where the entry went back to." },
+            restoredSubsessions: { type: "integer", description: "`restore`: sub-sessions restored together with the entry." },
+            failedSubsessions: { type: "integer", description: "`restore`: sub-sessions that stayed in the bin (path occupied / move failed)." },
             matched: { type: "integer", description: "`delete_workspace`: how many sessions belonged to the directory." },
             mode: { type: "string", description: "`delete` / `delete_workspace`: the mode that was applied." },
             recoverable: { type: "boolean", description: "`delete`: whether the bin can bring it back." },
@@ -13798,10 +14268,16 @@ function sessionToolDefinitions(service) {
           }
           if (typeof entryId !== "string" || entryId === "") throw new Error("entryId \u5FC5\u987B\u662F\u975E\u7A7A\u5B57\u7B26\u4E32\uFF08\u7701\u7565\u5219\u5217\u51FA\u56DE\u6536\u7AD9\uFF09");
           const result = await service.restore(entryId);
+          const extra = [];
+          if (result.restoredSubsessions.length > 0) extra.push(`\u5E76\u8FD8\u539F\u5B50\u4F1A\u8BDD ${result.restoredSubsessions.length} \u4E2A`);
+          if (result.failedSubsessions.length > 0) extra.push(`${result.failedSubsessions.length} \u4E2A\u5B50\u4F1A\u8BDD\u4ECD\u5728\u56DE\u6536\u7AD9`);
+          if (result.parentStillBinned) extra.push("\u5176\u7236\u4F1A\u8BDD\u4ECD\u5728\u56DE\u6536\u7AD9");
           return {
             action: "restore",
             restoredPath: result.restoredPath,
-            summary: `\u5DF2\u8FD8\u539F\u4F1A\u8BDD ${result.entry.sessionId} -> ${result.restoredPath}`
+            restoredSubsessions: result.restoredSubsessions.length,
+            failedSubsessions: result.failedSubsessions.length,
+            summary: `\u5DF2\u8FD8\u539F\u4F1A\u8BDD ${result.entry.sessionId} -> ${result.restoredPath}${extra.length === 0 ? "" : `\uFF08${extra.join("\uFF0C")}\uFF09`}`
           };
         }
         const mode = record2["mode"] ?? "recycle";
@@ -15968,7 +16444,13 @@ function queryOf(url) {
 }
 function visibleToSession(row, sessionIds, workspace) {
   const sessions = row.sessions ?? [];
-  if (sessions.length > 0) return sessions.some((id) => sessionIds.has(id));
+  if (sessions.length > 0) {
+    if (!sessions.some((id) => sessionIds.has(id))) return false;
+    if (workspace !== "" && row.workspaces !== void 0 && row.workspaces.length > 0) {
+      return row.workspaces.some((candidate) => sameWorkspacePath(candidate, workspace));
+    }
+    return true;
+  }
   if (workspace === "") return false;
   return (row.workspaces ?? []).some((candidate) => sameWorkspacePath(candidate, workspace));
 }
@@ -16027,7 +16509,7 @@ async function serveAction(req, res, deps) {
 
 // src/host/integration/session/session-bin-lock.ts
 init_errors();
-import { mkdir as mkdir5, open as open3, readFile as readFile6, rm as rm3, stat as stat5 } from "node:fs/promises";
+import { mkdir as mkdir5, open as open3, readFile as readFile6, rm as rm3, stat as stat5, utimes } from "node:fs/promises";
 import { dirname as dirname5 } from "node:path";
 var DEFAULT_STALE_LOCK_MS = 6e4;
 var DEFAULT_LOCK_RETRY_MS = 25;
@@ -16036,6 +16518,7 @@ function createSessionBinLock(options) {
   const staleMs = options.staleMs ?? DEFAULT_STALE_LOCK_MS;
   const retryMs = options.retryMs ?? DEFAULT_LOCK_RETRY_MS;
   const timeoutMs = options.timeoutMs ?? DEFAULT_LOCK_TIMEOUT_MS;
+  const heartbeatMs = options.heartbeatMs ?? (staleMs > 0 ? Math.max(1e3, Math.floor(staleMs / 4)) : 0);
   const sleep2 = options.sleep ?? ((ms) => new Promise((resolve3) => setTimeout(resolve3, ms)));
   const now = options.now ?? (() => Date.now());
   const owner = options.owner ?? `${process.pid}@${hostnameOf()}`;
@@ -16116,6 +16599,17 @@ function createSessionBinLock(options) {
     }
     return true;
   };
+  const refreshLock = async (token) => {
+    try {
+      const text8 = await readFile6(options.path, "utf8");
+      const record2 = JSON.parse(text8);
+      if (record2.token !== token) return;
+      const at = new Date(now());
+      await utimes(options.path, at, at);
+    } catch (error) {
+      options.onHeartbeatError?.(error);
+    }
+  };
   const withLock = async (_key, operation) => {
     const deadline = now() + timeoutMs;
     let token;
@@ -16132,9 +16626,17 @@ function createSessionBinLock(options) {
       }
       await sleep2(retryMs);
     }
+    let heartbeat;
+    if (token !== void 0 && heartbeatMs > 0) {
+      heartbeat = setInterval(() => {
+        void refreshLock(token);
+      }, heartbeatMs);
+      heartbeat.unref?.();
+    }
     try {
       return await operation();
     } finally {
+      if (heartbeat !== void 0) clearInterval(heartbeat);
       if (token !== void 0) await releaseIfOwned(token);
     }
   };
@@ -16626,7 +17128,14 @@ async function serveActionWithSignal(action, body, req, res, deps, service, sign
         return;
       }
       const result = await service.restore(entryId, options);
-      send(req, res, 200, { ok: true, restoredPath: result.restoredPath, movedBy: result.movedBy });
+      send(req, res, 200, {
+        ok: true,
+        restoredPath: result.restoredPath,
+        movedBy: result.movedBy,
+        restoredSubsessions: result.restoredSubsessions.length,
+        failedSubsessions: result.failedSubsessions.length,
+        parentStillBinned: result.parentStillBinned
+      });
       return;
     }
     case "purge": {
@@ -16892,7 +17401,7 @@ function retireBrowseBackend(browseBackends, connectionId) {
   const backend = browseBackends.get(connectionId);
   if (backend === void 0) return;
   browseBackends.delete(connectionId);
-  void backend.dispose?.();
+  void Promise.resolve().then(() => backend.dispose?.()).catch(() => void 0);
 }
 function browsingSeams(env) {
   const { profiles, transports, remoteHome, browseBackends } = env;
@@ -17018,7 +17527,7 @@ function registerPanelRoutes(env, hooks) {
 }
 
 // src/wiring/fs.ts
-var LOCAL_WORLD_MISSING_WARNING = 'dsh-over-ssh: \u79C1\u6709\u57DF\u7684 bridge \u672A\u5C31\u4F4D\uFF08ctx.get("localFs") === undefined\uFF09\uFF1A\u672C\u5730\u8DEF\u5F84\u7684\u5199\u5165\u56F4\u680F\u9000\u56DE\u672C\u63D2\u4EF6\u81EA\u5DF1\u7684 LocalBackend\u2014\u2014\u529F\u80FD\u770B\u8D77\u6765\u6B63\u5E38\uFF0C\u4F46\u56F4\u680F\u6362\u4E86\u6267\u884C\u8005\u3002\u8BF7\u68C0\u67E5 cordis.patch.yml \u91CC \u8FDC\u7A0B\u5DE5\u4F5C\u533A-\u79C1\u6709\u57DF \u7EC4\uFF08fs/fileReferences \u7684 isolate \u4E0E\u4E24\u4E2A bridge \u884C\uFF09\u662F\u5426\u88AB\u7981\u7528\u6216\u52A0\u8F7D\u5931\u8D25\u3002';
+var LOCAL_WORLD_MISSING_WARNING = 'dsh-over-ssh: \u79C1\u6709\u57DF\u7684 bridge \u672A\u5C31\u4F4D\uFF08ctx.get("localFs") === undefined\uFF09\uFF1A\u672C\u5730\u8DEF\u5F84\u7684\u5199\u5165\u56F4\u680F\u9000\u56DE\u672C\u63D2\u4EF6\u81EA\u5DF1\u7684 LocalBackend\u2014\u2014\u529F\u80FD\u770B\u8D77\u6765\u6B63\u5E38\uFF0C\u4F46\u56F4\u680F\u6362\u4E86\u6267\u884C\u8005\u3002\u8BF7\u68C0\u67E5 cordis.patch.yml \u91CC \u8FDC\u7A0B\u5DE5\u4F5C\u533A-\u79C1\u6709\u57DF \u7EC4\uFF08fs \u7684 isolate \u4E0E \u8FDC\u7A0B\u5DE5\u4F5C\u533A-\u6865\u63A5fs \u884C\uFF09\u662F\u5426\u88AB\u7981\u7528\u6216\u52A0\u8F7D\u5931\u8D25\u3002';
 function installClientDataChannel(ctx) {
   try {
     installRemoteFace(ctx);
@@ -17027,10 +17536,11 @@ function installClientDataChannel(ctx) {
   }
 }
 function provideHostServices(env) {
-  const { ctx, limits, registry, directory, transports, index, transferService, binService, sessionAdmin, sessionRoots, readBytesRange } = env;
+  const { ctx, limits, registry, directory, transports, transportLanes, index, transferService, binService, sessionAdmin, sessionRoots, readBytesRange } = env;
   const disposeRoots = ctx.provide("sshDevRoots", registry);
   const disposeConnections = ctx.provide("sshDevConnections", directory);
   const disposeTransports = ctx.provide("sshDevTransports", transports);
+  const disposeTransportLanes = ctx.provide("sshDevTransportLanes", transportLanes);
   const disposeIndex = ctx.provide("sshDevIndex", index);
   const disposeTransfer = ctx.provide("sshDevTransfer", transferService);
   const disposeBin = ctx.provide("sshDevRecycleBin", binService);
@@ -17041,7 +17551,7 @@ function provideHostServices(env) {
     ...limits.rangeChunkBytes === void 0 ? {} : { rangeChunkBytes: limits.rangeChunkBytes }
   });
   const disposeSessionRoots = ctx.provide("sshDevSessionRoots", sessionRoots);
-  return { disposeRoots, disposeConnections, disposeTransports, disposeIndex, disposeTransfer, disposeBin, disposeSessionTools, disposeRange, disposeSessionRoots };
+  return { disposeRoots, disposeConnections, disposeTransports, disposeTransportLanes, disposeIndex, disposeTransfer, disposeBin, disposeSessionTools, disposeRange, disposeSessionRoots };
 }
 function provideAgentStatus(env) {
   const { ctx, agentBridge, installations, askpass, remoteHome } = env;
@@ -17116,8 +17626,15 @@ function scheduleActivationDiagnostics(env) {
   return activationTimers;
 }
 function watchSessionRemovals(env) {
-  const { ctx, rootsWiring, onSessionRemoved } = env;
+  const { ctx, rootsWiring, onSessionRemoved, transportLanes } = env;
   onSessionRemoved((sessionId) => {
+    for (const sessionKey2 of [sessionId, `watch:${sessionId}`]) {
+      void transportLanes.releaseSession(sessionKey2).catch((error) => {
+        ctx.logger?.warn?.(
+          `dsh-over-ssh: \u56DE\u6536\u5DF2\u5220\u4F1A\u8BDD ${sessionKey2} \u7684 stateful transport \u5931\u8D25\uFF1A${error instanceof Error ? error.message : String(error)}`
+        );
+      });
+    }
     void rootsWiring.pruneSession(sessionId).catch((error) => {
       ctx.logger?.warn?.(
         `dsh-over-ssh: \u6E05\u7406\u5DF2\u5220\u4F1A\u8BDD ${sessionId} \u7684\u6839\u8BB0\u5F55\u5931\u8D25\uFF1A${error instanceof Error ? error.message : String(error)}`
@@ -17155,6 +17672,7 @@ function createTeardown(env) {
     disposeAgent();
     hostServices.disposeIndex();
     hostServices.disposeTransports();
+    hostServices.disposeTransportLanes();
     hostServices.disposeConnections();
     hostServices.disposeRoots();
     await tools.transports.disposeAll();
@@ -17172,6 +17690,7 @@ function wireFs(env) {
       registry,
       directory: env.directory,
       transports,
+      transportLanes: env.transportLanes,
       index: env.index,
       transferService: env.transferService,
       binService: env.binService,
@@ -17199,7 +17718,24 @@ function wireFs(env) {
       workspacePathOf: (sessionId) => readSessionCwd(ctx, sessionId)
     });
     const activationTimers = scheduleActivationDiagnostics({ ctx, ...routes });
-    watchSessionRemovals({ ctx, rootsWiring: routes.rootsWiring, onSessionRemoved: env.onSessionRemoved });
+    watchSessionRemovals({ ctx, rootsWiring: routes.rootsWiring, onSessionRemoved: env.onSessionRemoved, transportLanes: env.transportLanes });
+    const laneJanitor = setInterval(() => {
+      try {
+        const sessions = ctx.get("sessions");
+        if (sessions?.get === void 0) return;
+        void env.transportLanes.pruneStatefulSessions((sessionKey2) => {
+          if (sessionKey2 === "watch") return true;
+          const target = sessionKey2.startsWith("watch:") ? sessionKey2.slice("watch:".length) : sessionKey2;
+          return sessions.get?.(target) !== void 0;
+        }).catch((error) => {
+          ctx.logger?.warn?.(`over-ssh: \u56DE\u6536\u5931\u8054\u4F1A\u8BDD\u7684 stateful lane \u5931\u8D25\uFF1A${error instanceof Error ? error.message : String(error)}`);
+        });
+      } catch (error) {
+        ctx.logger?.warn?.(`over-ssh: \u8BFB\u53D6\u6D3B\u4F1A\u8BDD\u8868\u5931\u8D25\uFF0C\u8DF3\u8FC7 stateful lane \u6E05\u7406\uFF1A${error instanceof Error ? error.message : String(error)}`);
+      }
+    }, 6e4);
+    laneJanitor.unref?.();
+    activationTimers.push(laneJanitor);
     mergePersistedRoots({ ctx, rootsWiring: routes.rootsWiring });
     return createTeardown({ activationTimers, routes, hostServices, disposeAgent, tools: env, disposeSessionDirectories });
   });
@@ -17304,7 +17840,7 @@ function createTransferDeps(deps) {
      */
     async sha256Remote(absolute, signal) {
       const { connectionId } = requireRemote(deps, absolute);
-      const transport = await deps.transportFor(connectionId);
+      const transport = await deps.transportFor(connectionId, "bulk");
       if (transport.hashFile !== void 0) {
         try {
           const hashed = await transport.hashFile({ path: absolute }, signal);
@@ -17322,7 +17858,7 @@ function createTransferDeps(deps) {
     },
     async readRemote(absolute, options) {
       const { connectionId } = requireRemote(deps, absolute);
-      const transport = await deps.transportFor(connectionId);
+      const transport = await deps.transportFor(connectionId, "bulk");
       const offset = Math.max(0, options.offset ?? 0);
       if (transport.readFileRange !== void 0) {
         const chunk2 = await transport.readFileRange(
@@ -17336,7 +17872,7 @@ function createTransferDeps(deps) {
     },
     async writeRemote(absolute, bytes, options) {
       const { connectionId } = requireRemote(deps, absolute);
-      const transport = await deps.transportFor(connectionId);
+      const transport = await deps.transportFor(connectionId, "interactive");
       if (options.offset === void 0) {
         const outcome2 = await transport.writeFile(
           {
@@ -17359,15 +17895,35 @@ function createTransferDeps(deps) {
       return outcome;
     },
     async statRemote(absolute) {
-      const { target } = requireRemote(deps, absolute);
-      return target.backend.stat(target.absolute ?? absolute);
+      const { target, connectionId } = requireRemote(deps, absolute);
+      const resolved = target.absolute ?? absolute;
+      try {
+        const transport = await deps.transportFor(connectionId, "bulk");
+        if (transport.statPath !== void 0) {
+          const native = await transport.statPath(resolved);
+          if (!(native.exists && native.version === "")) {
+            return {
+              exists: native.exists,
+              isDirectory: native.isDirectory,
+              isFile: native.isFile,
+              isSymlink: false,
+              size: native.size,
+              mtimeMs: native.mtimeMs,
+              version: native.version
+            };
+          }
+        }
+      } catch (error) {
+        if (isSshDevError(error) && error.code === "CANCELLED") throw error;
+      }
+      return target.backend.stat(resolved);
     }
   };
 }
 function createRecycleBinDeps(deps) {
   const remoteMove = async (from, to, signal) => {
     const { connectionId } = requireRemote(deps, from);
-    const transport = await deps.transportFor(connectionId);
+    const transport = await deps.transportFor(connectionId, "interactive");
     if (transport.rename === void 0) {
       throw new SshDevError("REMOTE_UNSUPPORTED", '\u8BE5\u4F20\u8F93\u4E0D\u652F\u6301 rename\uFF0C\u56DE\u6536\u7AD9\u65E0\u6CD5\u4FDD\u8BC1"\u5148\u79FB\u52A8\u540E\u786E\u8BA4"', { from, to });
     }
@@ -17375,7 +17931,7 @@ function createRecycleBinDeps(deps) {
   };
   const remoteRemove = async (path, options) => {
     const { connectionId } = requireRemote(deps, path);
-    const transport = await deps.transportFor(connectionId);
+    const transport = await deps.transportFor(connectionId, "interactive");
     if (transport.remove === void 0) {
       throw new SshDevError("REMOTE_UNSUPPORTED", "\u8BE5\u4F20\u8F93\u4E0D\u652F\u6301 remove\uFF0C\u65E0\u6CD5\u6C38\u4E45\u5220\u9664", { path });
     }
@@ -17745,7 +18301,7 @@ function pruneStaleLocks(locks, liveRootKeys) {
   }
 }
 function wireRoots(env) {
-  const { ctx, limits, profiles, transports, registry } = env;
+  const { ctx, limits, profiles, transports, transportLanes, registry } = env;
   const binRootResolver = createBinRootResolver({
     addHiddenRoot: (root) => registry.addHidden(root),
     removeHiddenRoot: (key) => {
@@ -17801,7 +18357,7 @@ function wireRoots(env) {
   const worldDeps = {
     routed: registry.routed,
     // Local roots resolve through the same router, so a path never reaches the wrong world.
-    transportFor: async (connectionId) => (await transports.acquire(requireProfile(profiles, connectionId))).transport,
+    transportFor: async (connectionId, lane = "interactive") => (await transportLanes.acquire(requireProfile(profiles, connectionId), lane)).transport,
     // ADR-0011: the bin lives **beside** the root (outside the caller's repository) and is registered as a
     // hidden root so the router can reach it. `binRootFor` stays synchronous by answering from a decision made
     // when the root was registered; see `binRootResolver`.
@@ -17849,6 +18405,10 @@ function wireRoots(env) {
         ctx.logger?.warn?.(
           `\u56DE\u6536\u7AD9\u7D22\u5F15\u9501\u5DF2\u8FC7\u671F\u88AB\u56DE\u6536\uFF1A\u6301\u6709\u8005 ${JSON.stringify(event.holder)}\uFF0C\u5DF2\u8FC7\u671F ${Math.round(event.ageMs / 1e3)} \u79D2`
         );
+      },
+      // 心跳失败只警告：锁仍然有效，操作继续；但网络盘 EIO/EPERM 值得在日志里留下痕迹。
+      onHeartbeatError: (error) => {
+        ctx.logger?.warn?.(`\u56DE\u6536\u7AD9\u7D22\u5F15\u9501\u5FC3\u8DF3\u5237\u65B0\u5931\u8D25\uFF08\u9501\u4ECD\u6301\u6709\uFF09\uFF1A${error instanceof Error ? error.message : String(error)}`);
       }
     });
     binLocks.set(key, created);
@@ -17896,6 +18456,8 @@ function toExecOutcome(result) {
     exitCode: result.exitCode,
     stdout: result.stdout,
     stderr: result.stderr,
+    ...result.stdoutBase64 === void 0 ? {} : { stdoutBase64: result.stdoutBase64 },
+    ...result.stderrBase64 === void 0 ? {} : { stderrBase64: result.stderrBase64 },
     durationMs: result.durationMs,
     truncated: result.truncated,
     // 审计 0052 §8: these four used to be dropped right here, so the renderer's per-stream and spill logic
@@ -17923,20 +18485,30 @@ function createRemoteToolBackend(deps) {
     ...resolveForConnection === void 0 ? {} : { resolveForConnection: (connectionId, cwd) => resolveForConnection(connectionId, cwd) },
     ...resolveSessionRoot === void 0 ? {} : { resolveSessionRoot },
     async grep(target, request, signal) {
-      const transport = await deps.acquire(target.connectionId);
+      const transport = await deps.acquire(target.connectionId, "compute");
       const path = joinUnderRoot(target.root, request.path);
+      const offset = request.offset ?? 0;
+      if (offset > 0 && (!isAgentSearchCapable(transport) || transport.agentCapabilities.grepPaging !== true)) {
+        throw new SshDevError("REMOTE_UNSUPPORTED", "\u8BE5\u4F20\u8F93\u6216\u4EE3\u7406\u4E0D\u652F\u6301\u641C\u7D22\u5206\u9875\uFF08offset\uFF09\uFF0C\u8BF7\u51CF\u5C11\u7ED3\u679C\u6216\u6536\u7A84\u67E5\u8BE2", {
+          offset,
+          connectionId: target.connectionId
+        });
+      }
       if (isAgentSearchCapable(transport)) {
         const result2 = await transport.searchGrep(
           {
             paths: [path],
             query: request.pattern,
             literal: !request.regex,
+            ...offset === 0 ? {} : { offset },
+            // 本页条数交给代理切页；扫描上限多要 1 条，才能判断"后面还有没有下一页"。
+            limit: request.maxResults,
+            maxResults: offset + request.maxResults + 1,
             // Case sensitivity and ignore rules are both two-tier contracts: the tier that answers has to
             // receive the same intent the Tier 1 `grepCommand` expresses, or one tool call would mean two
             // things depending on which host has ripgrep (audit 0064 P3).
             ignoreCase: request.caseSensitive !== true,
             ...request.noIgnore === true ? { noIgnore: true } : {},
-            maxResults: request.maxResults,
             // Audit 0052 P10: symmetric with the Tier 1 `grepCommand` `--include=` filters. Without this the
             // **degraded** path had the capability the preferred path lacked.
             ...request.include === void 0 ? {} : { include: [...request.include] }
@@ -17948,7 +18520,9 @@ function createRemoteToolBackend(deps) {
           truncated: result2.truncated,
           strategy: `agent:${result2.strategy}`,
           // Audit 0052 P7: the agent is the only tier that can name the bound that stopped the scan.
-          truncation: readSearchTruncation(result2)
+          truncation: readSearchTruncation(result2),
+          ...result2.total === null ? {} : { total: result2.total },
+          ...result2.nextOffset === null ? { nextOffset: null } : { nextOffset: result2.nextOffset }
         };
       }
       const result = await transport.exec({ script: grepCommand(request, target.root), maxBytes: MAX_OUTPUT_BYTES }, signal);
@@ -17980,7 +18554,7 @@ function createRemoteToolBackend(deps) {
     async glob(target, request, signal) {
       const base = joinUnderRoot(target.root, request.path);
       compileGlob(request.pattern);
-      const transport = await deps.acquire(target.connectionId);
+      const transport = await deps.acquire(target.connectionId, "compute");
       if (transport.globPaths !== void 0) {
         try {
           const native = await transport.globPaths({
@@ -18002,8 +18576,8 @@ function createRemoteToolBackend(deps) {
         strategy: enumerated.source
       };
     },
-    async exec(target, request, signal) {
-      const transport = await deps.acquire(target.connectionId);
+    async exec(target, request, signal, lane = "interactive") {
+      const transport = await deps.acquire(target.connectionId, lane);
       const writeRoots = deps.execWriteRoots?.(target.connectionId, target.root);
       const result = await transport.exec(
         {
@@ -18169,7 +18743,11 @@ function remoteToolDefinitions(backend) {
           items: { type: "string" },
           description: 'Optional filename filters, e.g. `["*.cpp","*.h"]`. Applied to file names, so a whole-tree search for a symbol can be narrowed to one language without hand-picking directories. At most 16 entries.'
         },
-        maxResults: { type: "number", description: "Maximum matches (default 200, hard cap 200). The result reports when the cap was reached." }
+        maxResults: { type: "number", description: "Maximum matches (default 200, hard cap 200). The result reports when the cap was reached." },
+        offset: {
+          type: "number",
+          description: "0-based match index to start from (default 0). Use `nextOffset` from a previous page to continue. Paging needs the agent tier; other tiers refuse instead of silently returning page 0."
+        }
       },
       output: {
         schema: {
@@ -18184,6 +18762,9 @@ function remoteToolDefinitions(backend) {
             include: { type: "array", required: true, items: { type: "string" } },
             truncatedReasons: { type: "array", required: true, items: { type: "string" } },
             filesFiltered: { type: "integer" },
+            total: { type: "integer", description: "Matches found before paging (when the agent reports it)." },
+            nextOffset: { type: "integer", description: "Offset of the next page, or null when there is no next page." },
+            offset: { type: "integer", required: true, description: "The 0-based page offset this result was produced with." },
             matches: {
               type: "array",
               required: true,
@@ -18217,7 +18798,10 @@ function remoteToolDefinitions(backend) {
           include: [...parsed.include ?? []],
           truncatedReasons: [...truncation.reasons],
           ...truncation.filesFiltered === void 0 ? {} : { filesFiltered: truncation.filesFiltered },
-          matches: outcome.matches.map((hit) => ({ path: hit.path, line: hit.line, text: hit.text }))
+          matches: outcome.matches.map((hit) => ({ path: hit.path, line: hit.line, text: hit.text })),
+          offset: parsed.offset ?? 0,
+          ...outcome.total === void 0 ? {} : { total: outcome.total },
+          ...typeof outcome.nextOffset === "number" ? { nextOffset: outcome.nextOffset } : {}
         };
       }
     }),
@@ -18314,6 +18898,8 @@ function remoteToolDefinitions(backend) {
                   timedOut: { type: "boolean" },
                   stdout: { type: "string" },
                   stderr: { type: "string" },
+                  stdoutBase64: { type: "string" },
+                  stderrBase64: { type: "string" },
                   durationMs: { type: "integer" },
                   truncated: { type: "boolean" }
                 }
@@ -18328,8 +18914,10 @@ function remoteToolDefinitions(backend) {
               type: "boolean",
               description: "Whether this plugin stopped waiting because the timeout budget expired. True does not prove the remote process died; false does not rule out a signal (see `signal`)."
             },
-            stdout: { type: "string" },
-            stderr: { type: "string" },
+            stdout: { type: "string", description: "stdout as text; invalid UTF-8 is replaced (see stdoutBase64)." },
+            stderr: { type: "string", description: "stderr as text; invalid UTF-8 is replaced (see stderrBase64)." },
+            stdoutBase64: { type: "string", description: "Exact stdout bytes (base64) when stdout is not valid UTF-8 and was not truncated." },
+            stderrBase64: { type: "string", description: "Exact stderr bytes (base64) when stderr is not valid UTF-8 and was not truncated." },
             durationMs: { type: "integer" },
             truncated: { type: "boolean" },
             stdoutTruncated: { type: "boolean" },
@@ -18374,6 +18962,8 @@ function remoteToolDefinitions(backend) {
                   timedOut: outcome2.timedOut === true,
                   stdout: outcome2.stdout,
                   stderr: outcome2.stderr,
+                  ...outcome2.stdoutBase64 === void 0 ? {} : { stdoutBase64: outcome2.stdoutBase64 },
+                  ...outcome2.stderrBase64 === void 0 ? {} : { stderrBase64: outcome2.stderrBase64 },
                   durationMs: outcome2.durationMs,
                   truncated: flags2.truncated
                 };
@@ -18407,6 +18997,8 @@ function remoteToolDefinitions(backend) {
           timedOut: outcome.timedOut === true,
           stdout: outcome.stdout,
           stderr: outcome.stderr,
+          ...outcome.stdoutBase64 === void 0 ? {} : { stdoutBase64: outcome.stdoutBase64 },
+          ...outcome.stderrBase64 === void 0 ? {} : { stderrBase64: outcome.stderrBase64 },
           durationMs: outcome.durationMs,
           truncated: flags.truncated,
           stdoutTruncated: flags.stdoutTruncated,
@@ -18448,27 +19040,42 @@ function formatGrep(outcome) {
   const truncation = grepTruncation(outcome);
   const lines = [];
   if (outcome.matches.length === 0) {
-    lines.push(`\u5728\u8FDC\u7AEF\u672A\u627E\u5230\u5339\u914D\uFF08\u7B56\u7565\uFF1A${outcome.strategy}\uFF09\u3002`);
+    const offset = outcome.offset ?? 0;
+    if (offset > 0 && typeof outcome.total === "number" && outcome.total > 0) {
+      lines.push(`offset=${offset} \u8D85\u51FA\u5DF2\u626B\u63CF\u5230\u7684\u5339\u914D\u8303\u56F4\uFF08\u672C\u6B21\u5171\u626B\u63CF\u5230 ${outcome.total} \u6761\uFF09\u3002\u8BF7\u7528\u66F4\u5C0F\u7684 offset\uFF0C\u6216\u6536\u7A84\u641C\u7D22\u540E\u91CD\u8DD1\u3002`);
+    } else {
+      lines.push(`\u5728\u8FDC\u7AEF\u672A\u627E\u5230\u5339\u914D\uFF08\u7B56\u7565\uFF1A${outcome.strategy}\uFF09\u3002`);
+    }
     if (include.length > 0 && truncation?.filesFiltered !== void 0 && truncation.filesFiltered > 0) {
       lines.push(`\u6CE8\u610F\uFF1A${truncation.filesFiltered} \u4E2A\u5019\u9009\u6587\u4EF6\u88AB include \u8FC7\u6EE4\u6389\u4E86 \u2014\u2014 \u82E5\u8FD9\u91CC\u672C\u8BE5\u6709\u547D\u4E2D\uFF0C\u5148\u68C0\u67E5 include \u5199\u5BF9\u6CA1\u6709\u3002`);
     }
   } else {
     lines.push(outcome.matches.map((hit) => `${hit.path}:${hit.line}: ${hit.text}`).join("\n"));
   }
+  if (typeof outcome.total === "number") {
+    if (typeof outcome.nextOffset === "number") {
+      lines.push(`\u5DF2\u626B\u63CF\u5230 ${outcome.total} \u6761\uFF0C\u8FD8\u6709\u4E0B\u4E00\u9875\uFF1Aoffset=${outcome.nextOffset}`);
+    } else {
+      lines.push(`\u5339\u914D\u603B\u6570\uFF1A${outcome.total}`);
+    }
+  }
   const notes = [scope, ...modes].filter((part) => part !== "");
   if (notes.length > 0) lines.push(`\uFF08${notes.join("\uFF1B")}\uFF09`);
-  lines.push(...truncationLines(truncation));
+  lines.push(...truncationLines(truncation, { paging: outcome.strategy.startsWith("agent") }));
   return lines.join("\n");
 }
-function truncationLines(truncation) {
+function truncationLines(truncation, options = {}) {
   if (truncation === void 0 || !truncation.truncated) return [];
-  if (truncation.reasons.length === 0) {
-    return ["\uFF08\u7ED3\u679C\u88AB\u622A\u65AD\uFF1A\u8FDC\u7AEF\u672A\u8BF4\u660E\u89E6\u53D1\u4E86\u54EA\u4E2A\u4E0A\u9650\u3002\u7EE7\u7EED\u53D6\u7ED3\u679C\u9700\u6536\u7A84\u8F93\u5165\u2014\u2014\u52A0 include\u3001\u7F29\u5C0F path\uFF0C\u6216\u8C03\u5927 maxResults \u540E\u91CD\u8DD1\uFF1B\u672C\u5DE5\u5177\u4E0D\u652F\u6301\u5206\u9875/offset\u3002\uFF09"];
-  }
+  const paging = options.paging === true;
+  const summary = paging ? "\uFF08\u7ED3\u679C\u88AB\u622A\u65AD\uFF1A\u8FDC\u7AEF\u672A\u8BF4\u660E\u89E6\u53D1\u4E86\u54EA\u4E2A\u4E0A\u9650\u3002\u53EF\u5C1D\u8BD5\u7528 offset \u7FFB\u9875\uFF1B\u6CA1\u6709 nextOffset \u65F6\u6536\u7A84\u8F93\u5165\u2014\u2014\u52A0 include\u3001\u7F29\u5C0F path\uFF0C\u6216\u8C03\u5927 maxResults \u540E\u91CD\u8DD1\u3002\uFF09" : "\uFF08\u7ED3\u679C\u88AB\u622A\u65AD\uFF1A\u8FDC\u7AEF\u672A\u8BF4\u660E\u89E6\u53D1\u4E86\u54EA\u4E2A\u4E0A\u9650\u3002\u7EE7\u7EED\u53D6\u7ED3\u679C\u9700\u6536\u7A84\u8F93\u5165\u2014\u2014\u52A0 include\u3001\u7F29\u5C0F path\uFF0C\u6216\u8C03\u5927 maxResults \u540E\u91CD\u8DD1\uFF1B\u5F53\u524D\u4F20\u8F93\u4E0D\u652F\u6301\u5206\u9875/offset\u3002\uFF09";
+  if (truncation.reasons.length === 0) return [summary];
+  const advice = truncation.reasons.map(
+    (reason) => reason === "maxResults" && !paging ? "\u547D\u4E2D\u6761\u6570\u5230\u9876\uFF08maxResults\uFF09\uFF1A\u7528\u66F4\u5177\u4F53\u7684 pattern\u3001\u52A0 include \u8FC7\u6EE4\uFF0C\u6216\u7F29\u5C0F path \u540E\u91CD\u8DD1\u3002" : searchTruncationAdvice(reason)
+  );
   return [
     `\uFF08\u7ED3\u679C\u88AB\u622A\u65AD\uFF0C\u89E6\u53D1\u4E0A\u9650\uFF1A${truncation.reasons.join(", ")}\uFF09`,
-    ...truncation.reasons.map((reason) => `\xB7 ${searchTruncationAdvice(reason)}`),
-    "\u7EE7\u7EED\u53D6\u7ED3\u679C\u9700\u6536\u7A84\u8F93\u5165\u540E\u91CD\u8DD1\uFF08\u672C\u5DE5\u5177\u4E0D\u652F\u6301\u5206\u9875/offset\uFF1A\u670D\u52A1\u7AEF\u4E0D\u4FDD\u7559\u4E0A\u6B21\u8C03\u7528\u7684\u72B6\u6001\uFF09\u3002"
+    ...advice.map((line) => `\xB7 ${line}`),
+    paging ? "\u7EE7\u7EED\u53D6\u7ED3\u679C\uFF1A\u4F18\u5148\u7528\u8FD4\u56DE\u7684 nextOffset \u4F5C\u4E3A offset \u7FFB\u9875\uFF1B\u6CA1\u6709 nextOffset \u65F6\u6536\u7A84\u8F93\u5165\u540E\u91CD\u8DD1\u3002" : "\u7EE7\u7EED\u53D6\u7ED3\u679C\u9700\u6536\u7A84\u8F93\u5165\u540E\u91CD\u8DD1\uFF08\u5F53\u524D\u4F20\u8F93\u4E0D\u652F\u6301\u5206\u9875/offset\uFF09\u3002"
   ];
 }
 function formatGlob(outcome) {
@@ -18517,6 +19124,12 @@ function formatExec(outcome) {
 ${stdout.text}`);
   if (stderr.text !== "") parts.push(`stderr:
 ${stderr.text}`);
+  if (outcome.stdoutBase64 !== void 0) {
+    parts.push(`\u26A0 stdout \u5305\u542B\u975E UTF-8 \u5B57\u8282\uFF1A\u4E0A\u9762 stdout \u91CC\u7684\u66FF\u6362\u5B57\u7B26\u4E0D\u662F\u539F\u6587\uFF0C\u7CBE\u786E\u5B57\u8282\u5728 stdoutBase64\uFF08${String(Buffer.from(outcome.stdoutBase64, "base64").byteLength)} \u5B57\u8282\uFF09\u3002`);
+  }
+  if (outcome.stderrBase64 !== void 0) {
+    parts.push(`\u26A0 stderr \u5305\u542B\u975E UTF-8 \u5B57\u8282\uFF1A\u4E0A\u9762 stderr \u91CC\u7684\u66FF\u6362\u5B57\u7B26\u4E0D\u662F\u539F\u6587\uFF0C\u7CBE\u786E\u5B57\u8282\u5728 stderrBase64\uFF08${String(Buffer.from(outcome.stderrBase64, "base64").byteLength)} \u5B57\u8282\uFF09\u3002`);
+  }
   const stdoutCut = outcome.stdoutTruncated ?? outcome.truncated;
   const stderrCut = outcome.stderrTruncated ?? outcome.truncated;
   const cut = [
@@ -18636,7 +19249,8 @@ function toOutputView(output) {
     lost: output.lost,
     exitCode: output.exitCode,
     ...output.signal === void 0 ? {} : { signal: output.signal },
-    timedOut: output.timedOut
+    timedOut: output.timedOut,
+    ...output.exactBytes === void 0 ? {} : { binary: true, dataBase64: Buffer.from(output.exactBytes).toString("base64") }
   };
 }
 function defaultSleep2(ms, signal) {
@@ -18661,7 +19275,7 @@ function createRemoteJobBackend(deps) {
   const now = deps.now ?? (() => Date.now());
   const sleep2 = deps.sleep ?? defaultSleep2;
   const require2 = async (target) => {
-    const transport = await deps.acquire(target.connectionId);
+    const transport = await deps.acquire(target.connectionId, target.sessionKey);
     if (!isAgentJobCapable(transport)) throw unsupported(target.connectionId);
     return transport;
   };
@@ -18744,7 +19358,9 @@ function text3(value) {
   return [{ type: "text", text: value }];
 }
 function targetFor2(backend, exec) {
-  return resolveSessionTarget(exec, { resolve: (cwd) => backend.resolve(cwd), resolveSessionRoot: backend.resolveSessionRoot });
+  const target = resolveSessionTarget(exec, { resolve: (cwd) => backend.resolve(cwd), resolveSessionRoot: backend.resolveSessionRoot });
+  const sessionKey2 = exec.agent?.session.header.id;
+  return sessionKey2 === void 0 || sessionKey2 === "" ? target : { ...target, sessionKey: sessionKey2 };
 }
 var PATH_SPELLING2 = "Accepts an absolute remote path inside the workspace root, or a path relative to the root. An absolute path outside the root is refused. `..` folds but never leaves the root.";
 var JOB_LIFETIME_NOTE = " Job lifetime depends on the transport, and the difference matters for long builds. **Tier 2 (the default) runs a resident daemon**: jobs belong to the *session*, not to the ssh channel, so a dropped connection does **not** kill a running job \u2014 reconnect and read it again with the same `jobId` and `offset`. **Tier 1 (pure POSIX) and `--stdio` mode** tie jobs to the connection: closing the channel kills them. A resident daemon is reclaimed only when it goes idle for its timeout or the process stops, and that reclaim kills its jobs \u2014 so do not rely on a job surviving a long idle gap.";
@@ -18801,6 +19417,11 @@ function formatJobOutput(view) {
     );
   }
   parts.push(view.data === "" ? "\uFF08\u672C\u6B21\u6CA1\u6709\u65B0\u7684\u8F93\u51FA\uFF09" : view.data.replace(/\n$/, ""));
+  if (view.binary === true) {
+    parts.push(
+      `\u26A0 \u672C\u6B21\u8F93\u51FA\u5305\u542B\u975E UTF-8 \u5B57\u8282\uFF1A\u4E0A\u9762 data \u91CC\u7684\u66FF\u6362\u5B57\u7B26\u4E0D\u662F\u539F\u6587\uFF0C\u7CBE\u786E\u5B57\u8282\u5728 dataBase64\uFF08${view.dataBase64 === void 0 ? "\u7F3A\u5931" : `${String(Buffer.from(view.dataBase64, "base64").byteLength)} \u5B57\u8282`}\uFF09\u3002`
+    );
+  }
   if (view.lost) {
     parts.push(
       `\u26A0 \u4F60\u8BF7\u6C42\u7684 offset \u8D77\u70B9\u5DF2\u7ECF\u88AB\u4E22\u5F03\uFF1A\u672C\u6BB5\u6570\u636E**\u4E0D\u662F\u8FDE\u7EED\u8F93\u51FA**\uFF08\u4E2D\u95F4\u6709\u6D1E\uFF09\u3002\u8BE5\u4F5C\u4E1A\u7D2F\u8BA1\u4EA7\u51FA ${view.totalBytes} \u5B57\u8282\uFF0C\u5176\u4E2D\u6700\u65E9\u7684 ${view.droppedBytes} \u5B57\u8282\u5DF2\u4E0D\u53EF\u53D6\u56DE\uFF0C\u4F5C\u4E1A\u6CA1\u6709\u843D\u76D8\u526F\u672C\u3002`
@@ -19033,7 +19654,9 @@ function remoteJobToolDefinitions(backend) {
             jobs: { type: "array", items: { type: "string" }, description: "`list`: one formatted line per job; use `status` for structured fields." },
             jobId: { type: "string", description: "`output` / `kill` / `stdin`: the job acted on." },
             killed: { type: "boolean", description: "`kill`: false when the job had already finished." },
-            data: { type: "string", description: "`output`: output from the requested offset; empty when there is nothing new." },
+            data: { type: "string", description: "`output`: output from the requested offset; empty when there is nothing new. Invalid UTF-8 is replaced (see binary/dataBase64)." },
+            binary: { type: "boolean", description: "`output`: true when the chunk contained non-UTF-8 bytes; `data` is then not the exact content." },
+            dataBase64: { type: "string", description: "`output`: exact bytes (base64), present only when binary is true." },
             state: { type: "string", description: "`output`: `running` / `exited` / `killed` / `failed`." },
             droppedBytes: { type: "integer", description: "`output`: bytes dropped from the oldest end of the ring. Bytes, not lines." },
             exitCode: { type: "integer", description: "`output`: exit code; 0 while the job is still running." },
@@ -19137,6 +19760,7 @@ function remoteJobToolDefinitions(backend) {
             lost: view.lost,
             exitCode: view.exitCode,
             ...view.signal === void 0 ? {} : { signal: view.signal },
+            ...view.binary === true ? { binary: true, ...view.dataBase64 === void 0 ? {} : { dataBase64: view.dataBase64 } } : {},
             timedOut: view.timedOut,
             running: view.state === "running",
             waitedMs,
@@ -19168,6 +19792,7 @@ async function followOutput(backend, target, jobId, offset, timeoutMs, signal) {
           lost: view.lost,
           exitCode: view.exitCode,
           ...view.signal === void 0 ? {} : { signal: view.signal },
+          ...view.binary === true ? { binary: true, ...view.dataBase64 === void 0 ? {} : { dataBase64: view.dataBase64 } } : {},
           timedOut: false,
           running,
           waitedMs: Date.now() - started,
@@ -19188,6 +19813,7 @@ async function followOutput(backend, target, jobId, offset, timeoutMs, signal) {
           lost: view.lost,
           exitCode: view.exitCode,
           ...view.signal === void 0 ? {} : { signal: view.signal },
+          ...view.binary === true ? { binary: true, ...view.dataBase64 === void 0 ? {} : { dataBase64: view.dataBase64 } } : {},
           timedOut: true,
           running: true,
           waitedMs: Date.now() - started,
@@ -19249,6 +19875,52 @@ function rememberVersion(target, absolute, version) {
     rememberedVersions.delete(oldest.value);
   }
 }
+function capReadManyItems(items, maxBytesEach, totalBytesCap) {
+  let remaining = totalBytesCap;
+  return items.map((item) => {
+    if (item.text === void 0) return item;
+    if (item.binary === true && item.dataBase64 !== void 0) {
+      let raw = Buffer.from(item.dataBase64, "base64");
+      let truncated2 = item.truncated;
+      if (raw.byteLength > maxBytesEach) {
+        raw = raw.subarray(0, maxBytesEach);
+        truncated2 = true;
+      }
+      if (raw.byteLength > remaining) {
+        raw = raw.subarray(0, Math.max(0, remaining));
+        truncated2 = true;
+        remaining = 0;
+      } else {
+        remaining -= raw.byteLength;
+      }
+      return { ...item, text: raw.toString("utf8"), dataBase64: raw.toString("base64"), truncated: truncated2 };
+    }
+    let text8 = item.text;
+    let truncated = item.truncated;
+    let bytes = Buffer.byteLength(text8, "utf8");
+    if (bytes > maxBytesEach) {
+      text8 = truncateUtf8(text8, maxBytesEach);
+      truncated = true;
+      bytes = Buffer.byteLength(text8, "utf8");
+    }
+    if (bytes > remaining) {
+      text8 = truncateUtf8(text8, Math.max(0, remaining));
+      truncated = true;
+      remaining = 0;
+    } else {
+      remaining -= bytes;
+    }
+    return { ...item, text: text8, truncated };
+  });
+}
+function truncateUtf8(text8, maxBytes) {
+  const buffer = Buffer.from(text8, "utf8");
+  if (buffer.byteLength <= maxBytes) return text8;
+  if (maxBytes <= 0) return "";
+  let end = Math.min(maxBytes, buffer.byteLength);
+  while (end > 0 && end < buffer.byteLength && ((buffer[end] ?? 0) & 192) === 128) end -= 1;
+  return buffer.subarray(0, end).toString("utf8");
+}
 function createRemoteFileBackend(deps) {
   const cap = Math.max(1, Math.floor(deps.maxReadBytes ?? MAX_READ_FILE_BYTES));
   const requireBackend = (target) => {
@@ -19266,7 +19938,14 @@ function createRemoteFileBackend(deps) {
     async read(target, absolute, signal) {
       const chunk = await requireBackend(target).readText(absolute, cap, signal);
       rememberVersion(target, absolute, chunk.version);
-      return { text: chunk.text, size: chunk.size, truncated: chunk.truncated, version: chunk.version };
+      return {
+        text: chunk.text,
+        size: chunk.size,
+        truncated: chunk.truncated,
+        version: chunk.version,
+        ...chunk.binary === true ? { binary: true } : {},
+        ...chunk.dataBase64 === void 0 ? {} : { dataBase64: chunk.dataBase64 }
+      };
     },
     async write(target, absolute, text8, expectedVersion, signal) {
       const outcome = await requireBackend(target).writeText(absolute, text8, expectedVersion, signal);
@@ -19288,6 +19967,69 @@ function createRemoteFileBackend(deps) {
       rememberVersion(target, absolute, outcome.version);
       return { replaced: outcome.replaced, version: outcome.version, bytes: outcome.bytes };
     },
+    async readMany(target, absolutes, maxBytesEach, totalBytesCap, signal) {
+      const backend = requireBackend(target);
+      if (backend.readMany === void 0) {
+        const read = await Promise.all(absolutes.map(async (absolute) => {
+          try {
+            const chunk = await backend.readText(absolute, maxBytesEach, signal);
+            rememberVersion(target, absolute, chunk.version);
+            return {
+              path: absolute,
+              text: chunk.text,
+              size: chunk.size,
+              version: chunk.version,
+              truncated: chunk.truncated,
+              ...chunk.binary === true ? { binary: true } : {},
+              ...chunk.dataBase64 === void 0 ? {} : { dataBase64: chunk.dataBase64 }
+            };
+          } catch (error) {
+            return { path: absolute, size: 0, version: "", truncated: false, error: error instanceof Error ? error.message : String(error) };
+          }
+        }));
+        return { items: capReadManyItems(read, maxBytesEach, totalBytesCap), missing: [] };
+      }
+      const result = await backend.readMany(absolutes, { maxBytesEach, totalBytesCap, signal });
+      const items = absolutes.map((absolute, index) => {
+        const chunk = result.chunks[index];
+        if (chunk === void 0) {
+          return { path: absolute, size: 0, version: "", truncated: false, error: "\u65E0\u6CD5\u8BFB\u53D6\uFF08\u6587\u4EF6\u4E0D\u5B58\u5728\u3001\u8D85\u9650\u6216\u8BFB\u53D6\u5931\u8D25\uFF09" };
+        }
+        rememberVersion(target, absolute, chunk.version);
+        return {
+          path: absolute,
+          text: chunk.text,
+          size: chunk.size,
+          version: chunk.version,
+          truncated: chunk.truncated,
+          ...chunk.binary === true ? { binary: true } : {},
+          ...chunk.dataBase64 === void 0 ? {} : { dataBase64: chunk.dataBase64 }
+        };
+      });
+      return { items: capReadManyItems(items, maxBytesEach, totalBytesCap), missing: result.missing };
+    },
+    async projectSummary(target, signal) {
+      const backend = requireBackend(target);
+      if (backend.repoSummary === void 0) {
+        throw new Error("\u5F53\u524D\u540E\u7AEF\u6CA1\u6709 repo.summary\uFF08\u8FDC\u7AEF\u4EE3\u7406\u592A\u65E7\uFF0C\u8BF7\u91CD\u88C5/\u5347\u7EA7\u4EE3\u7406\uFF09");
+      }
+      return backend.repoSummary(target.root, signal);
+    },
+    async applyPatchMany(target, edits, atomic, signal) {
+      const backend = requireBackend(target);
+      if (backend.patchMany === void 0) {
+        throw new Error("\u5F53\u524D\u540E\u7AEF\u6CA1\u6709 fs.patchMany\uFF08\u8FDC\u7AEF\u4EE3\u7406\u592A\u65E7\uFF0C\u8BF7\u91CD\u88C5/\u5347\u7EA7\u4EE3\u7406\uFF09");
+      }
+      const result = await backend.patchMany(edits, atomic, signal);
+      if (result["rolledBack"] !== true && Array.isArray(result["results"])) {
+        for (const entry of result["results"]) {
+          if (entry.ok === true && typeof entry.path === "string" && typeof entry.version === "string" && entry.version !== "") {
+            rememberVersion(target, entry.path, entry.version);
+          }
+        }
+      }
+      return result;
+    },
     recall(target, absolute) {
       return rememberedVersions.get(versionKey(target, absolute));
     },
@@ -19386,6 +20128,9 @@ function formatRead(view) {
   const truncatedByWindow = view.lines.length >= view.limit && endLine < view.totalLines;
   const body = view.lines.length > 0 ? view.lines.map((line) => `${line.number}: ${line.text}`).join("\n") : "\uFF08\u8BE5\u8303\u56F4\u5185\u6CA1\u6709\u884C\uFF09";
   const parts = [body];
+  if (view.binary === true) {
+    parts.push("\u26A0 \u8BE5\u6587\u4EF6\u4E0D\u662F\u5408\u6CD5 UTF-8\uFF1A\u4E0A\u9762\u7684\u884C\u6587\u672C\u662F\u66FF\u6362\u89C6\u56FE\uFF0C\u4E0D\u80FD\u7528\u4E8E\u7CBE\u786E\u5185\u5BB9\uFF1B\u9700\u8981\u539F\u59CB\u5B57\u8282\u8BF7\u7528 remote_read_many\uFF08binary/dataBase64\uFF09\u3002");
+  }
   if (view.sourceTruncated) {
     parts.push(
       `\uFF08\u672C\u6B21\u8BFB\u53D6\u88AB ${view.maxReadBytes} \u5B57\u8282\u4E0A\u9650\u622A\u65AD\uFF1A\u6587\u4EF6\u5171 ${view.size} \u5B57\u8282\uFF0C\u4E0A\u9762\u53EA\u8986\u76D6\u5230\u7B2C ${view.totalLines} \u884C\uFF0C\u540E\u7EED\u884C\u672A\u8BFB\u5165\u3002\u8BF7\u7528 offset \u4ECE\u540E\u9762\u7EE7\u7EED\u8BFB\uFF0C\u4E0D\u8981\u628A\u5B83\u5F53\u4F5C\u5B8C\u6574\u6587\u4EF6\u3002\uFF09`
@@ -19484,6 +20229,7 @@ function remoteFileToolDefinitions(backend, allowMutation) {
               description: "The whole-file read hit the byte cap, so later lines were not read at all."
             },
             maxReadBytes: { type: "integer", required: true, description: "The byte cap that read was subject to." },
+            binary: { type: "boolean", description: "The file is not valid UTF-8; lines are only a readable replacement view. Use remote_read_many for exact bytes." },
             size: { type: "integer", required: true, description: "Full file size in bytes." },
             version: {
               type: "string",
@@ -19527,6 +20273,7 @@ function remoteFileToolDefinitions(backend, allowMutation) {
           maxReadBytes: backend.maxReadBytes,
           size: file.size,
           version: file.version,
+          ...file.binary === true ? { binary: true } : {},
           lines: window.lines.map((line) => ({ number: line.number, text: line.text }))
         };
       }
@@ -19821,11 +20568,280 @@ function remoteFileToolDefinitions(backend, allowMutation) {
   ];
 }
 function registerRemoteFileTools(ctx, backend, options) {
-  const disposers = remoteFileToolDefinitions(backend, options?.allowMutation).map((definition) => ctx.tools.register(definition));
+  const disposers = [
+    ...remoteFileToolDefinitions(backend, options?.allowMutation),
+    remoteReadManyToolDefinition(backend),
+    remoteProjectSummaryToolDefinition(backend),
+    remoteApplyPatchManyToolDefinition(backend, options?.allowMutation)
+  ].map((definition) => ctx.tools.register(definition));
   return () => {
     for (const dispose of disposers.splice(0)) dispose();
   };
 }
+function remoteReadManyToolDefinition(backend) {
+  return defineTool5({
+    name: "remote_read_many",
+    description: "Read several text files from the remote workspace in **one** round trip. Use it for context gathering when you already know the file list: one call instead of N `remote_read` calls. Returns each file's raw text (no line numbers), size, version token and a per-file error when that file could not be read. Bounded: at most 16 files, `maxBytes` per file (default 256 KiB, hard cap 1 MiB), 2 MiB total. Read-only: calls may overlap with other read-only remote calls.",
+    isConcurrencySafe: () => true,
+    parameters: {
+      paths: {
+        type: "array",
+        items: { type: "string" },
+        required: true,
+        description: `Files to read (1..16). ${PATH_SPELLING3} Relative paths resolve under the target root.`
+      },
+      maxBytes: {
+        type: "number",
+        description: "Per-file byte cap (default 262144, hard cap 1048576). Truncated files say so."
+      }
+    },
+    output: {
+      schema: {
+        type: "object",
+        additionalProperties: false,
+        properties: {
+          strategy: { type: "string", required: true, description: "`batch` (one logical call; the backend may fall back to parallel single reads internally)." },
+          totalBytes: { type: "integer", required: true },
+          items: {
+            type: "array",
+            required: true,
+            items: {
+              type: "object",
+              additionalProperties: false,
+              properties: {
+                path: { type: "string", required: true },
+                text: { type: "string", description: "File text; invalid UTF-8 is replaced (see binary/dataBase64)." },
+                size: { type: "integer", required: true },
+                version: { type: "string", required: true },
+                truncated: { type: "boolean", required: true },
+                error: { type: "string" },
+                binary: { type: "boolean", description: "The file is not valid UTF-8; `text` is only a readable replacement." },
+                dataBase64: { type: "string", description: "Exact bytes (base64), present only when binary is true." }
+              }
+            }
+          },
+          missing: { type: "array", required: true, items: { type: "string" } }
+        }
+      },
+      render: (_args, value) => text4(formatReadMany(value))
+    },
+    async execute(args, exec) {
+      const record2 = args ?? {};
+      const raw = record2["paths"];
+      if (!Array.isArray(raw) || raw.length === 0 || raw.length > 16) {
+        throw new Error("paths \u5FC5\u987B\u662F 1..16 \u4E2A\u6587\u4EF6\u8DEF\u5F84");
+      }
+      const requested = raw.map((item, index) => requiredString3(item, `paths[${index}]`));
+      const maxBytesEach = clampInt3(record2["maxBytes"], 262144, 1, 1048576);
+      const target = targetFor3(backend, exec);
+      const absolutes = requested.map((path) => resolveOrThrow3(target, path));
+      const totalBytesCap = 2 * 1024 * 1024;
+      const batch = backend.readMany;
+      const result = batch === void 0 ? {
+        items: await (async () => {
+          const read = await Promise.all(absolutes.map(async (path) => {
+            try {
+              const chunk = await backend.read(target, path, exec.signal);
+              return { path, text: chunk.text, size: chunk.size, version: chunk.version, truncated: chunk.truncated };
+            } catch (error) {
+              return { path, size: 0, version: "", truncated: false, error: error instanceof Error ? error.message : String(error) };
+            }
+          }));
+          let remaining = totalBytesCap;
+          return read.map((item) => {
+            if (item.text === void 0) return item;
+            let text8 = item.text;
+            let truncated = item.truncated;
+            let bytes = Buffer.byteLength(text8, "utf8");
+            if (bytes > maxBytesEach) {
+              text8 = truncateUtf8(text8, maxBytesEach);
+              truncated = true;
+              bytes = Buffer.byteLength(text8, "utf8");
+            }
+            if (bytes > remaining) {
+              text8 = truncateUtf8(text8, remaining);
+              truncated = true;
+              remaining = 0;
+            } else {
+              remaining -= bytes;
+            }
+            return { ...item, text: text8, truncated };
+          });
+        })(),
+        missing: []
+      } : await batch.call(backend, target, absolutes, maxBytesEach, totalBytesCap, exec.signal);
+      return {
+        strategy: "batch",
+        totalBytes: result.items.reduce((sum, item) => {
+          const binary = item.binary === true;
+          const dataBase64 = item.dataBase64;
+          if (binary && dataBase64 !== void 0) return sum + Buffer.from(dataBase64, "base64").byteLength;
+          return sum + (item.text === void 0 ? 0 : Buffer.byteLength(item.text, "utf8"));
+        }, 0),
+        items: result.items.map((item) => ({ ...item })),
+        missing: [...result.missing]
+      };
+    }
+  });
+}
+function formatReadMany(view) {
+  const head = `\u6279\u91CF\u8BFB\u53D6 ${view.items.length} \u4E2A\u6587\u4EF6\uFF08${view.strategy === "batch" ? "\u4E00\u6B21\u5F80\u8FD4" : "\u5E76\u53D1\u5355\u8BFB"}\uFF0C\u5171 ${view.totalBytes} \u5B57\u8282\uFF09\u3002`;
+  const sections = view.items.map((item) => {
+    if (item.error !== void 0) return `## ${item.path}
+\u8BFB\u53D6\u5931\u8D25\uFF1A${item.error}`;
+    const truncated = item.truncated ? `\uFF08\u5DF2\u622A\u65AD\uFF0C\u5B8C\u6574 ${item.size} \u5B57\u8282\uFF09` : "";
+    const body = item.text ?? "";
+    const binary = item.binary === true ? `
+\u26A0 \u8BE5\u6587\u4EF6\u4E0D\u662F\u5408\u6CD5 UTF-8\uFF1A\u4E0A\u9762\u6B63\u6587\u91CC\u7684\u66FF\u6362\u5B57\u7B26\u4E0D\u662F\u539F\u6587\uFF0C\u7CBE\u786E\u5B57\u8282\u5728 dataBase64\uFF08${item.dataBase64 === void 0 ? "\u7F3A\u5931" : `${String(Buffer.from(item.dataBase64, "base64").byteLength)} \u5B57\u8282`}\uFF09\u3002` : "";
+    return `## ${item.path}\uFF08version=${item.version}${truncated}\uFF09
+${body}${binary}`;
+  });
+  const missing = view.missing.length === 0 ? "" : `
+\u65E0\u6CD5\u8BFB\u53D6\uFF1A${view.missing.join("\u3001")}`;
+  return [head, ...sections].join("\n\n") + missing;
+}
+function remoteProjectSummaryToolDefinition(backend) {
+  return defineTool5({
+    name: "remote_project_summary",
+    description: "Describe the remote project at a path in **one** round trip: git branch/ahead/behind/dirty (when the agent has git), top-level entries, package manifests (package.json / go.mod / Cargo.toml / pyproject.toml / ...), a README head and detected test/build/lint commands. Use it once at the start of work on an unfamiliar remote repo instead of chaining `ls`, `remote_git` and several `remote_read` calls. Read-only: may overlap with other read-only remote calls.",
+    isConcurrencySafe: () => true,
+    parameters: {
+      path: { type: "string", description: `Directory to summarise. ${PATH_SPELLING3} Defaults to the target root.` }
+    },
+    output: {
+      schema: {
+        type: "object",
+        additionalProperties: false,
+        properties: {
+          root: { type: "string", required: true },
+          summary: { type: "object", required: true, additionalProperties: true, description: "The agent repo.summary payload." }
+        }
+      },
+      render: (_args, value) => text4(formatProjectSummary(value))
+    },
+    async execute(args, exec) {
+      const record2 = args ?? {};
+      const target = targetFor3(backend, exec);
+      const root = record2["path"] === void 0 ? target.root : resolveOrThrow3(target, requiredString3(record2["path"], "path"));
+      if (backend.projectSummary === void 0) throw new Error("\u5F53\u524D\u540E\u7AEF\u6CA1\u6709 repo.summary\uFF08\u8FDC\u7AEF\u4EE3\u7406\u592A\u65E7\uFF0C\u8BF7\u91CD\u88C5/\u5347\u7EA7\u4EE3\u7406\uFF09");
+      const summary = await backend.projectSummary({ ...target, root }, exec.signal);
+      return { root, summary };
+    }
+  });
+}
+function formatProjectSummary(value) {
+  const lines = [`\u9879\u76EE\u6982\u89C8 ${value.root}`];
+  const git = value.summary["git"];
+  if (typeof git === "object" && git !== null) {
+    const record2 = git;
+    const remote = typeof record2["remoteUrl"] === "string" ? `\uFF0Cremote=${record2["remoteUrl"]}` : "";
+    const cut = record2["truncated"] === true ? "\uFF08status \u8F93\u51FA\u88AB\u622A\u65AD\uFF0Cdirty \u53EA\u662F\u4E0B\u754C\uFF09" : "";
+    lines.push(`git\uFF1A${String(record2["branch"] ?? "?")}\uFF0Cdirty=${String(record2["dirty"] ?? 0)}\uFF0Cahead=${String(record2["ahead"] ?? 0)}\uFF0Cbehind=${String(record2["behind"] ?? 0)}${remote}${cut}`);
+  } else {
+    lines.push("git\uFF1A\u4E0D\u53EF\u7528\uFF08\u6216\u8BE5\u76EE\u5F55\u4E0D\u662F\u5DE5\u4F5C\u6811\uFF09");
+  }
+  const topLevel = Array.isArray(value.summary["topLevel"]) ? value.summary["topLevel"] : [];
+  if (topLevel.length > 0) {
+    const names = topLevel.map((entry) => {
+      const record2 = entry ?? {};
+      const name2 = typeof record2["name"] === "string" ? record2["name"] : "?";
+      return record2["isDirectory"] === true ? `${name2}/` : name2;
+    });
+    lines.push(`\u9876\u5C42\uFF08${names.length}${value.summary["truncated"] === true ? "\uFF0C\u5DF2\u622A\u65AD" : ""}\uFF09\uFF1A${names.join("\uFF0C")}`);
+  }
+  const manifests = Array.isArray(value.summary["manifests"]) ? value.summary["manifests"] : [];
+  if (manifests.length > 0) {
+    const listed = manifests.map((entry) => {
+      const record2 = entry ?? {};
+      const kind = typeof record2["kind"] === "string" ? record2["kind"] : "?";
+      const path = typeof record2["path"] === "string" ? record2["path"] : "?";
+      return `${kind}\uFF08${path}\uFF09`;
+    });
+    lines.push(`\u6E05\u5355\uFF1A${listed.join("\uFF0C")}`);
+  }
+  const detected = value.summary["detected"];
+  const commands = typeof detected === "object" && detected !== null ? Object.entries(detected).filter(([, command]) => typeof command === "string").map(([name2, command]) => `${name2}=${String(command)}`).join("\uFF0C") : "";
+  if (commands !== "") lines.push(`\u63A8\u65AD\u547D\u4EE4\uFF1A${commands}`);
+  const readme = value.summary["readmeHead"];
+  if (typeof readme === "string" && readme.trim() !== "") {
+    const head = readme.length > 1536 ? `${readme.slice(0, 1536)}
+\u2026\uFF08README \u5DF2\u622A\u65AD\uFF09` : readme;
+    lines.push(`README \u5934\uFF1A
+${head.trimEnd()}`);
+  }
+  return lines.join("\n");
+}
+function remoteApplyPatchManyToolDefinition(backend, allowMutation) {
+  return defineTool5({
+    name: "remote_apply_patch",
+    description: "Apply several file edits in **one** round trip on the remote host. Each edit is either a literal find/replace (`find` + `replace`, `all` to replace every occurrence) or a unified diff (`patch`), with an optional `expectedVersion` guard. Every edit is validated before **any** file is written; with `atomic: true` (default) a late failure rolls applied edits back. Use it for multi-file refactors instead of N `remote_edit` calls; for one file prefer `remote_edit`/`remote_patch`. Max 32 edits, 4 MiB total snapshot.",
+    parameters: {
+      edits: {
+        type: "array",
+        required: true,
+        description: "1..32 edits; each needs `path` plus either `find`+`replace` or `patch`.",
+        items: {
+          type: "object",
+          additionalProperties: false,
+          properties: {
+            path: { type: "string", required: true },
+            expectedVersion: { type: "string" },
+            find: { type: "string" },
+            replace: { type: "string" },
+            all: { type: "boolean" },
+            create: { type: "boolean" },
+            patch: { type: "string" }
+          }
+        }
+      },
+      atomic: { type: "boolean", description: "Roll back on a late failure (default true)." }
+    },
+    output: {
+      schema: {
+        type: "object",
+        additionalProperties: false,
+        properties: {
+          applied: { type: "integer", required: true },
+          rolledBack: { type: "boolean", required: true },
+          results: { type: "array", required: true, items: { type: "object", additionalProperties: true } }
+        }
+      },
+      render: (_args, value) => text4(formatApplyPatchMany(value))
+    },
+    async execute(args, exec) {
+      const record2 = args ?? {};
+      const raw = record2["edits"];
+      if (!Array.isArray(raw) || raw.length === 0 || raw.length > 32) throw new Error("edits \u5FC5\u987B\u662F 1..32 \u6761\u7F16\u8F91");
+      const target = targetFor3(backend, exec);
+      const edits = raw.map((entry, index) => {
+        const item = entry ?? {};
+        const path = resolveOrThrow3(target, requiredString3(item["path"], `edits[${index}].path`));
+        assertWritable(target, path, allowMutation);
+        return {
+          path,
+          ...typeof item["expectedVersion"] === "string" ? { expectedVersion: item["expectedVersion"] } : {},
+          ...typeof item["find"] === "string" ? { find: item["find"] } : {},
+          ...typeof item["replace"] === "string" ? { replace: item["replace"] } : {},
+          ...item["all"] === true ? { all: true } : {},
+          ...item["create"] === true ? { create: true } : {},
+          ...typeof item["patch"] === "string" ? { patch: item["patch"] } : {}
+        };
+      });
+      if (backend.applyPatchMany === void 0) throw new Error("\u5F53\u524D\u540E\u7AEF\u6CA1\u6709 fs.patchMany\uFF08\u8FDC\u7AEF\u4EE3\u7406\u592A\u65E7\uFF0C\u8BF7\u91CD\u88C5/\u5347\u7EA7\u4EE3\u7406\uFF09");
+      const result = await backend.applyPatchMany(target, edits, record2["atomic"] !== false, exec.signal);
+      return {
+        applied: typeof result["applied"] === "number" ? result["applied"] : 0,
+        rolledBack: result["rolledBack"] === true,
+        results: Array.isArray(result["results"]) ? result["results"] : []
+      };
+    }
+  });
+}
+function formatApplyPatchMany(value) {
+  const head = `\u6279\u91CF\u4FEE\u6539\uFF1A\u6210\u529F ${value.applied} \u6761${value.rolledBack ? "\uFF0C\u5931\u8D25\u540E\u5DF2\u56DE\u6EDA" : ""}\u3002`;
+  const lines = value.results.map((item) => `- ${item.path}\uFF1A${item.ok ? "\u6210\u529F" : `\u5931\u8D25\uFF08${item.error ?? "\u672A\u77E5\u539F\u56E0"}\uFF09`}`);
+  return [head, ...lines].join("\n");
+}
 
 // src/host/integration/lsp/lsp-framing.ts
 var HEADER_END = Buffer.from("\r\n\r\n", "latin1");
@@ -19930,6 +20946,7 @@ function parseContentLength(header) {
 }
 
 // src/host/integration/lsp/lsp-session.ts
+var LSP_READ_CHUNK_BYTES = 256 * 1024;
 var IDLE_POLL_MS = 60;
 var BUSY_POLL_MS = 0;
 var DEFAULT_REQUEST_TIMEOUT_MS = 2e4;
@@ -20218,16 +21235,17 @@ var LspSession = class _LspSession {
       if (this.#stopped) return;
       let delay = IDLE_POLL_MS;
       try {
-        const chunk = await this.#transport.lspRead(this.#id, this.#offset, signal);
+        const chunk = await this.#transport.lspRead(this.#id, this.#offset, signal, LSP_READ_CHUNK_BYTES);
         this.#offset = chunk.nextOffset;
         if (chunk.lost) {
           this.#failAll(new LspSessionError("\u8BED\u8A00\u670D\u52A1\u5668\u8F93\u51FA\u5DF2\u88AB\u4E22\u5F03\uFF08\u73AF\u5F62\u7F13\u51B2\u6EA2\u51FA\uFF09\uFF0C\u6D41\u4E0D\u53EF\u6062\u590D"));
           this.#stopped = true;
           return;
         }
-        if (chunk.data !== "") {
+        const bytes = chunk.exactBytes ?? (chunk.data === "" ? void 0 : Buffer.from(chunk.data, "utf8"));
+        if (bytes !== void 0 && bytes.length > 0) {
           delay = BUSY_POLL_MS;
-          for (const message of this.#parser.feed(chunk.data)) this.#dispatch(message);
+          for (const message of this.#parser.feed(bytes)) this.#dispatch(message);
         }
         if (chunk.state === "exited") {
           this.#failAll(new LspSessionError("\u8BED\u8A00\u670D\u52A1\u5668\u5DF2\u9000\u51FA"));
@@ -20479,7 +21497,7 @@ function describeInstalled(available) {
 }
 var MAX_SESSIONS = 8;
 function sessionKeyPrefix(target, language) {
-  return `${target.connectionId}\0${target.root}\0${language}\0`;
+  return `${target.connectionId}\0${target.root}\0${language}\0${target.sessionKey ?? ""}\0`;
 }
 function sessionKey(target, language, override) {
   const server = override === void 0 ? "" : `${override.command}\0${(override.args ?? []).join("\0")}`;
@@ -20518,7 +21536,7 @@ function createLspRegistry(deps) {
             `\u6CA1\u6709 ${language} \u7684\u9ED8\u8BA4\u8BED\u8A00\u670D\u52A1\u5668\u3002\u8BF7\u7528 \`server\` \u6307\u5B9A\u8981\u8FD0\u884C\u7684\u547D\u4EE4\uFF08\u8FDC\u7AEF\u9700\u8981\u6709\u8FD9\u4E2A\u7A0B\u5E8F\uFF09\u3002`
           );
         }
-        const transport = await deps.acquire(target.connectionId);
+        const transport = await deps.acquire(target.connectionId, target.sessionKey);
         const available = transport.capabilities?.lspServers;
         if (available !== void 0 && !command.command.includes("/")) {
           if (!available.some((server) => server.command === command.command)) {
@@ -20625,6 +21643,21 @@ function createForwardToolBackend(acquire) {
           { connectionId }
         );
       }
+      if (transport.netProbe !== void 0) {
+        let probe2;
+        try {
+          probe2 = await transport.netProbe(normalizeProbeHost(request.remoteHost), request.remotePort, signal);
+        } catch (error) {
+          if (!(error instanceof SshDevError) || error.code !== "REMOTE_UNSUPPORTED") throw error;
+        }
+        if (probe2 !== void 0 && !probe2.reachable) {
+          throw new SshDevError(
+            "CONNECTION_UNREACHABLE",
+            `\u8FDC\u7AEF\u7AEF\u53E3\u4E0D\u53EF\u8FBE\uFF1A${request.remoteHost}:${String(request.remotePort)}${probe2.error === void 0 ? "" : `\uFF08${probe2.error}\uFF09`}`,
+            { connectionId, remoteHost: request.remoteHost, remotePort: request.remotePort }
+          );
+        }
+      }
       const handle = await transport.forward(request, signal);
       sequence2 += 1;
       const id = `fwd-${String(sequence2)}`;
@@ -20658,6 +21691,9 @@ function createForwardToolBackend(acquire) {
     }
   };
 }
+function normalizeProbeHost(host) {
+  return host.startsWith("[") && host.endsWith("]") ? host.slice(1, -1) : host;
+}
 function formatResult(value) {
   if (Array.isArray(value["forwards"])) {
     const forwards = value["forwards"];
@@ -21067,12 +22103,13 @@ function remoteGitDefinition(backend) {
         stashAction: readString3(record2["stashAction"]),
         all: record2["all"] === true
       });
+      const lane = READ_ACTIONS.includes(action) ? "compute" : "interactive";
       const outcome = await backend.exec(target, {
         command: quoteAll(argv),
         cwd: resolveCwd(target, readString3(record2["cwd"])),
         env: { ...GIT_ENV },
         timeoutMs: readPositiveInt2(record2["timeoutMs"], DEFAULT_TIMEOUT_MS3)
-      }, exec.signal);
+      }, exec.signal, lane);
       const capped = capLines(outcome.stdout, maxLines);
       const errCapped = capLines(outcome.stderr, maxLines);
       const base = {
@@ -21180,9 +22217,44 @@ function readArgs(args) {
     ...typeof record2["server"] === "string" && record2["server"] !== "" ? { server: record2["server"] } : {}
   };
 }
+function splitCommandLine(value) {
+  const parts = [];
+  let current = "";
+  let started = false;
+  let quote2;
+  for (let index = 0; index < value.length; index += 1) {
+    const char = value[index];
+    if (quote2 !== void 0) {
+      if (char === quote2) quote2 = void 0;
+      else if (char === "\\" && quote2 === '"' && index + 1 < value.length) {
+        current += value[index + 1];
+        index += 1;
+      } else current += char;
+      continue;
+    }
+    if (char === '"' || char === "'") {
+      quote2 = char;
+      started = true;
+      continue;
+    }
+    if (/\s/.test(char)) {
+      if (started) {
+        parts.push(current);
+        current = "";
+        started = false;
+      }
+      continue;
+    }
+    current += char;
+    started = true;
+  }
+  if (quote2 !== void 0) throw new Error('server \u7684\u5F15\u53F7\u6CA1\u6709\u95ED\u5408\uFF1B\u5E26\u7A7A\u683C\u7684\u8DEF\u5F84\u8BF7\u5199\u6210 "/opt/my tools/server" --stdio');
+  if (started) parts.push(current);
+  return parts;
+}
 function parseServer(value) {
   if (value === void 0) return void 0;
-  const parts = value.split(/\s+/).filter((part) => part !== "");
+  const parts = splitCommandLine(value);
   if (parts.length === 0) return void 0;
   return parts.length === 1 ? { command: parts[0] } : { command: parts[0], args: parts.slice(1) };
 }
@@ -21204,7 +22276,7 @@ function remoteLspToolDefinitions(deps) {
         column: { type: "integer", description: "Column for `hover` / `definition`, 1-based. Required for those two actions." },
         server: {
           type: "string",
-          description: "Executable to run, with optional arguments (`gopls`, `rust-analyzer`, `pylsp -v`). Defaults to the table entry for the file language; required when the language has no entry."
+          description: 'Executable to run, with optional arguments (`gopls`, `rust-analyzer`, `pylsp -v`). Defaults to the table entry for the file language; required when the language has no entry. Quote a path that contains spaces: `"/opt/my tools/server" --stdio`.'
         }
       },
       output: {
@@ -21272,19 +22344,16 @@ function remoteLspToolDefinitions(deps) {
         const requested = parsed.path;
         if (requested === void 0) throw new Error(`${parsed.action} \u9700\u8981 path`);
         const target = targetFor3(backend, exec);
+        const sessionKey2 = exec.agent?.session.header.id;
+        const lspTarget = sessionKey2 === void 0 || sessionKey2 === "" ? { connectionId: target.connectionId, root: target.root } : { connectionId: target.connectionId, root: target.root, sessionKey: sessionKey2 };
         const path = resolveOrThrow3(target, requested);
         const language = languageForPath(path);
         const override = parseServer(parsed.server);
         if (parsed.action === "stop") {
-          const stopped = await registry.stop({ connectionId: target.connectionId, root: target.root }, language, exec.signal);
+          const stopped = await registry.stop(lspTarget, language, exec.signal);
           return { action: "stop", path, language, stopped };
         }
-        const session = await registry.session(
-          { connectionId: target.connectionId, root: target.root },
-          language,
-          override,
-          exec.signal
-        );
+        const session = await registry.session(lspTarget, language, override, exec.signal);
         const uri = pathToUri(path);
         if (parsed.action === "diagnostics") {
           const document = await backend.read(target, path, exec.signal);
@@ -21463,6 +22532,10 @@ function wireSessionAdmin(env) {
       ctx.logger?.warn?.(
         `\u4F1A\u8BDD\u56DE\u6536\u7AD9\u7D22\u5F15\u9501\u5DF2\u8FC7\u671F\u88AB\u56DE\u6536\uFF1A\u6301\u6709\u8005 ${JSON.stringify(event.holder)}\uFF0C\u5DF2\u8FC7\u671F ${Math.round(event.ageMs / 1e3)} \u79D2`
       );
+    },
+    // 心跳失败只警告：锁仍有效，操作继续；网络盘 EIO/EPERM 需要留下痕迹。
+    onHeartbeatError: (error) => {
+      ctx.logger?.warn?.(`\u4F1A\u8BDD\u56DE\u6536\u7AD9\u7D22\u5F15\u9501\u5FC3\u8DF3\u5237\u65B0\u5931\u8D25\uFF08\u9501\u4ECD\u6301\u6709\uFF09\uFF1A${error instanceof Error ? error.message : String(error)}`);
     }
   });
   const sessionAdmin = createSessionAdminService({
@@ -22187,7 +23260,7 @@ async function relayCopy(deps, transport, request, source) {
 
 // src/wiring/tools-management.ts
 function wireManagementTools(env) {
-  const { ctx, limits, profiles, transports, registry, binService, toolBackend, sessionRoots, recordFor, transferService, transferTracker } = env;
+  const { ctx, limits, profiles, transportLanes, registry, binService, toolBackend, sessionRoots, recordFor, transferService, transferTracker } = env;
   const rootRefFor = (target) => registry.records.find(
     (record2) => record2.root.location === "remote" && record2.root.connectionId === target.connectionId && record2.root.path === target.root
   )?.root;
@@ -22275,7 +23348,7 @@ function wireManagementTools(env) {
       return { kind: "undone", action: undone.action, id: String(undone.entry.id), message: undone.message };
     },
     copy: async ({ target, from, to, overwrite, recursive, signal }) => {
-      const acquire = async (connectionId) => (await transports.acquire(requireProfile(profiles, connectionId))).transport;
+      const acquire = async (connectionId) => (await transportLanes.acquire(requireProfile(profiles, connectionId), "interactive")).transport;
       return copyRemoteFile(
         {
           transportFor: acquire,
@@ -22304,7 +23377,7 @@ function wireManagementTools(env) {
       );
     },
     probeEnv: async (connectionId, refresh, signal) => {
-      const transport = (await transports.acquire(requireProfile(profiles, connectionId))).transport;
+      const transport = (await transportLanes.acquire(requireProfile(profiles, connectionId), "interactive")).transport;
       if (transport.probeEnv === void 0) return void 0;
       return transport.probeEnv(refresh, signal);
     }
@@ -22348,8 +23421,8 @@ function execWriteRootsSeam(env) {
   };
 }
 function wireTools(env) {
-  const { ctx, limits, profiles, transports, registry, indexFor, transferService, transferTracker, binService, notifySessionRemoved: notifySessionRemoved2 } = env;
-  const { sessionRoots, toolBackend, disposeTools } = wireAgentTools({ ctx, limits, profiles, transports, registry, indexFor });
+  const { ctx, limits, profiles, transports, transportLanes, registry, indexFor, transferService, transferTracker, binService, notifySessionRemoved: notifySessionRemoved2 } = env;
+  const { sessionRoots, toolBackend, disposeTools } = wireAgentTools({ ctx, limits, profiles, transports, transportLanes, registry, indexFor });
   const {
     recordFor,
     disposeJobTools,
@@ -22357,13 +23430,14 @@ function wireTools(env) {
     lspRegistry,
     disposeLspTools,
     assertWritable: assertWritable2
-  } = wireFileAndJobTools({ ctx, limits, profiles, transports, registry, sessionRoots });
+  } = wireFileAndJobTools({ ctx, limits, profiles, transports, transportLanes, registry, sessionRoots });
   const sessionAdmin = wireSessionAdmin({ ctx, limits, notifySessionRemoved: notifySessionRemoved2 });
   const { dispose: disposeManagement } = wireManagementTools({
     ctx,
     limits,
     profiles,
     transports,
+    transportLanes,
     registry,
     binService,
     toolBackend,
@@ -22395,7 +23469,7 @@ function wireTools(env) {
   };
 }
 function wireAgentTools(env) {
-  const { ctx, limits, profiles, transports, registry, indexFor } = env;
+  const { ctx, limits, profiles, transports, transportLanes, registry, indexFor } = env;
   const sessionRoots = createSessionRootIndex({
     filePath: sessionRootsFilePath(),
     readFile: readFile10,
@@ -22420,7 +23494,7 @@ function wireAgentTools(env) {
       const covering = longestContainingRoot(candidates, normalizeRemotePath(cwd));
       return covering === void 0 ? void 0 : { connectionId, root: covering };
     },
-    acquire: async (connectionId) => (await transports.acquire(requireProfile(profiles, connectionId))).transport,
+    acquire: async (connectionId, lane = "interactive") => (await transportLanes.acquire(requireProfile(profiles, connectionId), lane)).transport,
     enumerate: async (connectionId, root, signal) => {
       const result = await indexFor(connectionId).enumerate(root, signal === void 0 ? {} : { signal });
       return { paths: result.paths, truncated: result.truncated, source: result.source };
@@ -22447,7 +23521,7 @@ function wireAgentTools(env) {
   return { sessionRoots, toolBackend, disposeTools };
 }
 function wireFileAndJobTools(env) {
-  const { ctx, limits, profiles, transports, registry, sessionRoots } = env;
+  const { ctx, limits, profiles, transportLanes, registry, sessionRoots } = env;
   const remoteRootFor = (cwd) => {
     const resolved = registry.routed.tryResolve(cwd);
     if (!resolved.ok) return void 0;
@@ -22465,7 +23539,10 @@ function wireFileAndJobTools(env) {
     // ADR-0013: the session id (plus its fork lineage) is the strict scope; `cwd` alone cannot separate
     // two conversations opened on the same directory.
     resolveSessionRoot: (cwd, sessionId) => sessionRoots.outcomeFor(cwd, sessionIdentityOf(ctx, sessionId)),
-    acquire: async (connectionId) => (await transports.acquire(requireProfile(profiles, connectionId))).transport
+    acquire: async (connectionId, sessionKey2) => {
+      const lane = sessionKey2 === void 0 || sessionKey2 === "" ? "interactive" : "stateful";
+      return (await transportLanes.acquire(requireProfile(profiles, connectionId), lane, void 0, sessionKey2)).transport;
+    }
   });
   const disposeJobTools = registerRemoteJobTools(ctx, jobBackend);
   const fileBackend = createRemoteFileBackend({
@@ -22507,7 +23584,10 @@ function wireFileAndJobTools(env) {
     }
   };
   const lspRegistry = createLspRegistry({
-    acquire: async (connectionId) => (await transports.acquire(requireProfile(profiles, connectionId))).transport,
+    acquire: async (connectionId, sessionKey2) => {
+      const lane = sessionKey2 === void 0 || sessionKey2 === "" ? "interactive" : "stateful";
+      return (await transportLanes.acquire(requireProfile(profiles, connectionId), lane, void 0, sessionKey2)).transport;
+    },
     onLog: (connectionId, message) => {
       ctx.logger?.info?.(`over-ssh: [${connectionId}] \u8BED\u8A00\u670D\u52A1\u5668\uFF1A${message}`);
     }