dsh-over-ssh 0.0.0-stage → 0.1.1

package/lib/fs.js

@@ -0,0 +1,1451 @@
+// src/fs.ts
+import "@deepseek-ai/cordis";
+
+// src/host/integration/fs/fs-provider.ts
+import { StringDecoder } from "node:string_decoder";
+import "@deepseek-ai/cordis";
+import { FileSystem, FsTargetKey, FsVersion } from "@deepseek-ai/dsh-fs";
+
+// src/host/integration/fs/platform-errors.ts
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { FsError } from "@deepseek-ai/dsh-fs";
+var hostClass;
+var detection;
+function resolveHostFsPath(entryScript) {
+  if (entryScript === void 0 || entryScript === "") return void 0;
+  try {
+    const resolved = createRequire(entryScript).resolve("@deepseek-ai/dsh-fs");
+    return typeof resolved === "string" && resolved !== "" ? resolved : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function hostFsCandidates(entryScript) {
+  if (entryScript === void 0 || entryScript === "") return [];
+  const base = dirname(entryScript);
+  const relative = join("node_modules", "@deepseek-ai", "dsh-fs", "lib", "index.js");
+  return [join(base, relative), join(base, "..", relative), join(base, "..", "..", relative)].map(
+    (path) => pathToFileURL(path).href
+  );
+}
+function startHostErrorDetection(entryScript = process.argv[1]) {
+  if (detection !== void 0) return;
+  const started = detectHostFsError(entryScript);
+  detection = started;
+  void started.catch(() => void 0);
+}
+async function detectHostFsError(entryScript) {
+  const resolved = resolveHostFsPath(entryScript);
+  const sources = resolved === void 0 ? hostFsCandidates(entryScript) : [pathToFileURL(resolved).href, ...hostFsCandidates(entryScript)];
+  for (const candidate of sources) {
+    try {
+      const module = await import(candidate);
+      const found = module.FsError;
+      if (typeof found === "function" && found !== FsError) {
+        hostClass = found;
+        return hostClass;
+      }
+    } catch {
+    }
+  }
+  return void 0;
+}
+function isFsError(error) {
+  if (error instanceof FsError) return true;
+  return hostClass !== void 0 && error instanceof hostClass;
+}
+function activeFsErrorClass() {
+  return hostClass ?? FsError;
+}
+function platformFsError(message, code, options) {
+  const Constructor = activeFsErrorClass();
+  return new Constructor(message, code, options);
+}
+
+// src/host/infra/cache/lru.ts
+var LruCache = class {
+  #maxEntries;
+  #maxBytes;
+  #sizeOf;
+  #entries = /* @__PURE__ */ new Map();
+  #bytes = 0;
+  #hits = 0;
+  #misses = 0;
+  #evictions = 0;
+  #rejectedOversize = 0;
+  constructor(options, sizeOf) {
+    if (!Number.isInteger(options.maxEntries) || options.maxEntries < 1) throw new Error("LruCache.maxEntries must be a positive integer");
+    if (!Number.isInteger(options.maxBytes) || options.maxBytes < 1) throw new Error("LruCache.maxBytes must be a positive integer");
+    this.#maxEntries = options.maxEntries;
+    this.#maxBytes = options.maxBytes;
+    this.#sizeOf = sizeOf;
+  }
+  /** Look up a value and mark it most-recently used. */
+  get(key) {
+    const entry = this.#entries.get(key);
+    if (entry === void 0) {
+      this.#misses++;
+      return void 0;
+    }
+    this.#entries.delete(key);
+    this.#entries.set(key, entry);
+    this.#hits++;
+    return entry.value;
+  }
+  /** Look up a value without changing recency or counters. */
+  peek(key) {
+    return this.#entries.get(key)?.value;
+  }
+  /** Whether the key is retained. */
+  has(key) {
+    return this.#entries.has(key);
+  }
+  /**
+   * Insert or replace a value.
+   *
+   * @returns `false` when the value alone exceeds `maxBytes` and was therefore not stored.
+   */
+  set(key, value) {
+    const bytes = this.#sizeOf(value);
+    if (bytes > this.#maxBytes) {
+      this.delete(key);
+      this.#rejectedOversize++;
+      return false;
+    }
+    this.delete(key);
+    this.#entries.set(key, { value, bytes });
+    this.#bytes += bytes;
+    this.#evictToBounds();
+    return true;
+  }
+  /** Remove a key, returning whether it was present. */
+  delete(key) {
+    const entry = this.#entries.get(key);
+    if (entry === void 0) return false;
+    this.#entries.delete(key);
+    this.#bytes -= entry.bytes;
+    return true;
+  }
+  /**
+   * Remove every entry whose key starts with `prefix`, in one pass over the internal map.
+   *
+   * 存在的理由：调用方（`VersionedCache.invalidatePrefix`）在**每次写**之后都要按前缀失效，而在此之前
+   * 它只有 `keys()` 可用——`keys()` 会把整张表**物化**成一个数组，随后又用 `delete(key)` 逐个做哈希
+   * 查找。这里直接在 `#entries` 上过一遍：不建中间数组，字节记账就地扣减，边迭代边删除（Map 迭代器
+   * 规范保证删除当前条目后仍会访问后续条目）。
+   *
+   * **为什么是"前缀"而不是更通用的"谓词"**：谓词要为每条 key 付一次 JS 回调，而一次 `keys()` 物化只是
+   * 一次指针批量拷贝。实测（20 000 条 × 2 000 次，只命中 1 条）旧写法 1 289 ms、前缀版 962 ms、
+   * 谓词版 953 ms——两者同量级；但在**生产上限**（读缓存 256 条 / 目录缓存 512 条）下谓词版反而比旧
+   * 写法慢（20 000 次：160 ms vs 148 ms），前缀版打平（147 ms）。也就是说：谓词版只在大表上不亏，
+   * 在小表上亏；前缀版两边都不亏。热路径上的方法按真实规模选形状。
+   *
+   * @param prefix - key prefix.
+   * @returns the number of removed entries.
+   */
+  deleteByPrefix(prefix) {
+    let removed = 0;
+    for (const [key, entry] of this.#entries) {
+      if (!key.startsWith(prefix)) continue;
+      this.#entries.delete(key);
+      this.#bytes -= entry.bytes;
+      removed++;
+    }
+    return removed;
+  }
+  /** Remove everything. */
+  clear() {
+    this.#entries.clear();
+    this.#bytes = 0;
+  }
+  /** Keys from least to most recently used. */
+  keys() {
+    return [...this.#entries.keys()];
+  }
+  /** Current counters. */
+  get stats() {
+    return {
+      entries: this.#entries.size,
+      bytes: this.#bytes,
+      hits: this.#hits,
+      misses: this.#misses,
+      evictions: this.#evictions,
+      rejectedOversize: this.#rejectedOversize
+    };
+  }
+  /**
+   * Drop the least-recently-used entry.
+   *
+   * Exposed so a shared {@link CacheBudget} can make this cache give bytes back; `#evictToBounds` is the
+   * same operation driven by this cache's own limits.
+   *
+   * @returns `false` when the cache is empty (the caller must not retry in a loop).
+   */
+  evictOldest() {
+    const oldest = this.#entries.keys().next();
+    if (oldest.done === true) return false;
+    const entry = this.#entries.get(oldest.value);
+    if (entry === void 0) return false;
+    this.#entries.delete(oldest.value);
+    this.#bytes -= entry.bytes;
+    this.#evictions++;
+    return true;
+  }
+  /**
+   * Come down to `maxBytes` by dropping the oldest entries.
+   *
+   * @param maxBytes - the ceiling to reach.
+   * @returns how many entries were dropped.
+   */
+  trimTo(maxBytes) {
+    let dropped = 0;
+    while (this.#bytes > maxBytes && this.evictOldest()) dropped++;
+    return dropped;
+  }
+  #evictToBounds() {
+    while (this.#entries.size > this.#maxEntries || this.#bytes > this.#maxBytes) {
+      if (!this.evictOldest()) return;
+    }
+  }
+};
+
+// src/host/infra/cache/versioned.ts
+var VersionedCache = class {
+  #ttlMs;
+  #now;
+  #lru;
+  #budget;
+  #hits = 0;
+  #misses = 0;
+  #freshHits = 0;
+  #staleHits = 0;
+  #revalidations = 0;
+  constructor(options, sizeOf) {
+    if (!Number.isInteger(options.ttlMs) || options.ttlMs < 0) throw new Error("VersionedCache.ttlMs must be a non-negative integer");
+    this.#ttlMs = options.ttlMs;
+    this.#now = options.now ?? Date.now;
+    this.#lru = new LruCache({ maxEntries: options.maxEntries, maxBytes: options.maxBytes }, (entry) => sizeOf(entry.value));
+    this.#budget = options.budget;
+    this.#budget?.join(this);
+  }
+  /** Bytes this cache holds (the budget member contract). */
+  get bytes() {
+    return this.#lru.stats.bytes;
+  }
+  /** Drop oldest entries down to `maxBytes` (the budget member contract). */
+  trimTo(maxBytes) {
+    return this.#lru.trimTo(maxBytes);
+  }
+  /** Drop the oldest entry (the budget member contract). */
+  evictOldest() {
+    return this.#lru.evictOldest();
+  }
+  /**
+   * Leave the shared budget, so a retired cache stops counting against the total.
+   *
+   * Called by whoever owns the cache when its root goes away. Without it a removed root's cache stayed in the
+   * accounting forever, which is the leak the budget exists to prevent.
+   */
+  leaveBudget() {
+    this.#budget?.leave(this);
+  }
+  /**
+   * Look up an entry.
+   *
+   * @param key - route key.
+   * @returns the entry with its freshness, or `undefined` when nothing is retained.
+   */
+  get(key) {
+    const stored = this.#lru.get(key);
+    if (stored === void 0) {
+      this.#misses++;
+      return void 0;
+    }
+    const ageMs = Math.max(0, this.#now() - stored.storedAt);
+    const fresh = ageMs <= this.#ttlMs;
+    this.#hits++;
+    if (fresh) this.#freshHits++;
+    else this.#staleHits++;
+    return { value: stored.value, version: stored.version, fresh, ageMs };
+  }
+  /** Insert or replace an entry, stamping it as just-read. */
+  set(key, value, version) {
+    const stored = this.#lru.set(key, { value, version, storedAt: this.#now() });
+    if (stored) this.#budget?.enforce(this);
+    return stored;
+  }
+  /**
+   * Refresh an entry's timestamp after a cheap remote version check matched.
+   *
+   * @param key - route key.
+   * @param version - the version observed by the check; a mismatch refuses the touch.
+   * @returns whether the entry was refreshed.
+   */
+  touch(key, version) {
+    const stored = this.#lru.peek(key);
+    if (stored === void 0 || stored.version !== version) return false;
+    const refreshed = this.#lru.set(key, { value: stored.value, version: stored.version, storedAt: this.#now() });
+    if (refreshed) this.#revalidations++;
+    return refreshed;
+  }
+  /** Drop one entry. */
+  invalidate(key) {
+    return this.#lru.delete(key);
+  }
+  /**
+   * Drop every entry whose key starts with the prefix, used when a directory epoch changes.
+   *
+   * @param prefix - key prefix.
+   * @returns the number of removed entries.
+   */
+  invalidatePrefix(prefix) {
+    return this.#lru.deleteByPrefix(prefix);
+  }
+  /** Remove everything. */
+  clear() {
+    this.#lru.clear();
+  }
+  /** Current counters. */
+  get stats() {
+    const lru = this.#lru.stats;
+    return {
+      entries: lru.entries,
+      bytes: lru.bytes,
+      hits: this.#hits,
+      misses: this.#misses,
+      freshHits: this.#freshHits,
+      staleHits: this.#staleHits,
+      revalidations: this.#revalidations,
+      evictions: lru.evictions
+    };
+  }
+};
+
+// src/host/domain/errors.ts
+var SshDevError = class extends Error {
+  code;
+  details;
+  constructor(code, message, details = {}) {
+    super(message);
+    this.name = "SshDevError";
+    this.code = code;
+    this.details = details;
+  }
+};
+function isSshDevError(value) {
+  return value instanceof SshDevError;
+}
+
+// src/shared/root-keys.ts
+function normalizeLocalPath(path, options = {}) {
+  const caseInsensitive = options.caseInsensitive ?? false;
+  const unified = path.replace(/\\/g, "/");
+  const unc = unified.startsWith("//");
+  const posixAbsolute = unified.startsWith("/");
+  const driveMatch = /^([A-Za-z]):/.exec(unified);
+  const driveLetter = driveMatch?.[1];
+  const drive = driveLetter === void 0 ? "" : `${driveLetter.toUpperCase()}:`;
+  const rest = unc ? unified.slice(2) : drive === "" ? unified : unified.slice(2);
+  const segments = [];
+  for (const segment of rest.split("/")) {
+    if (segment === "" || segment === ".") continue;
+    if (segment === "..") {
+      segments.pop();
+      continue;
+    }
+    segments.push(segment);
+  }
+  const body = segments.join("/");
+  let normalized;
+  if (unc) normalized = `//${body}`;
+  else if (drive !== "") normalized = body === "" ? `${drive}/` : `${drive}/${body}`;
+  else if (posixAbsolute) normalized = body === "" ? "/" : `/${body}`;
+  else normalized = body === "" ? "." : body;
+  return caseInsensitive ? normalized.toLowerCase() : normalized;
+}
+function normalizePosixPath(path) {
+  if (!path.startsWith("/")) return void 0;
+  const segments = [];
+  for (const segment of path.split("/")) {
+    if (segment === "" || segment === ".") continue;
+    if (segment === "..") {
+      segments.pop();
+      continue;
+    }
+    segments.push(segment);
+  }
+  return segments.length === 0 ? "/" : `/${segments.join("/")}`;
+}
+
+// src/host/domain/path-grammar.ts
+function normalizeRemotePath(path) {
+  const normalized = normalizePosixPath(path);
+  if (normalized !== void 0) return normalized;
+  if (path === "") throw new SshDevError("ROOT_INVALID", "\u8FDC\u7A0B\u8DEF\u5F84\u4E0D\u80FD\u4E3A\u7A7A", {});
+  throw new SshDevError("ROOT_INVALID", `\u8FDC\u7A0B\u8DEF\u5F84\u5FC5\u987B\u662F\u7EDD\u5BF9\u8DEF\u5F84\uFF1A${path}`, { path });
+}
+function remotePathContains(root, candidate) {
+  const normalizedRoot = normalizeRemotePath(root);
+  const normalizedCandidate = normalizeRemotePath(candidate);
+  if (normalizedRoot === "/") return true;
+  return normalizedCandidate === normalizedRoot || normalizedCandidate.startsWith(`${normalizedRoot}/`);
+}
+function longestContainingRoot(roots, candidate) {
+  let best;
+  for (const root of roots) {
+    if (!remotePathContains(root, candidate)) continue;
+    if (best === void 0 || normalizeRemotePath(root).length > normalizeRemotePath(best).length) best = root;
+  }
+  return best;
+}
+
+// src/host/infra/transport/git-status.ts
+function isGitStatusTransport(value) {
+  return typeof value === "object" && value !== null && typeof value.gitStatus === "function";
+}
+var DEFAULT_GIT_STATUS_TTL_MS = 5e3;
+var DEFAULT_GIT_STATUS_MAX_ENTRIES = 64;
+var DEFAULT_GIT_STATUS_MAX_BYTES = 4 * 1024 * 1024;
+var DEFAULT_GIT_STATUS_MAX_CHANGES = 2e3;
+var DEFAULT_GIT_STATUS_MAX_PATH_BYTES = 512 * 1024;
+function cacheKey(connectionId, root) {
+  return `${connectionId}\0${root}`;
+}
+function awaitCallerCancellation(shared, signal) {
+  if (signal === void 0) return shared;
+  if (signal.aborted) {
+    return Promise.reject(new SshDevError("CANCELLED", "git \u72B6\u6001\u67E5\u8BE2\u5DF2\u88AB\u8C03\u7528\u65B9\u53D6\u6D88", { reason: "aborted" }));
+  }
+  return new Promise((resolve, reject) => {
+    const onAbort = () => {
+      reject(new SshDevError("CANCELLED", "git \u72B6\u6001\u67E5\u8BE2\u5DF2\u88AB\u8C03\u7528\u65B9\u53D6\u6D88", { reason: "aborted" }));
+    };
+    signal.addEventListener("abort", onAbort, { once: true });
+    shared.then(
+      (value) => {
+        signal.removeEventListener("abort", onAbort);
+        resolve(value);
+      },
+      (error) => {
+        signal.removeEventListener("abort", onAbort);
+        reject(error);
+      }
+    );
+  });
+}
+function createGitStatusService(deps) {
+  const maxChanges = Math.max(1, Math.floor(deps.maxChanges ?? DEFAULT_GIT_STATUS_MAX_CHANGES));
+  const maxPathBytes = Math.max(1, Math.floor(deps.maxPathBytes ?? DEFAULT_GIT_STATUS_MAX_PATH_BYTES));
+  const cache = new VersionedCache(
+    {
+      ttlMs: deps.ttlMs ?? DEFAULT_GIT_STATUS_TTL_MS,
+      maxEntries: deps.maxEntries ?? DEFAULT_GIT_STATUS_MAX_ENTRIES,
+      maxBytes: deps.maxBytes ?? DEFAULT_GIT_STATUS_MAX_BYTES,
+      ...deps.now === void 0 ? {} : { now: deps.now }
+    },
+    (snapshot) => snapshot.changes.reduce((total, change) => total + change.path.length + change.status.length, snapshot.branch?.length ?? 0)
+  );
+  const bounded = (changes, alreadyTruncated) => {
+    const kept = [];
+    let bytes = 0;
+    for (const change of changes) {
+      if (kept.length >= maxChanges || bytes + change.path.length > maxPathBytes) {
+        return { changes: kept, truncated: true };
+      }
+      kept.push(change);
+      bytes += change.path.length;
+    }
+    return { changes: kept, truncated: alreadyTruncated };
+  };
+  const inFlight = /* @__PURE__ */ new Map();
+  return {
+    async status(query, signal) {
+      const root = deps.resolveRoot(query.connectionId, query.path);
+      if (root === void 0) {
+        return { available: false, reason: "no-root", changes: [], truncated: false };
+      }
+      const key = cacheKey(query.connectionId, root);
+      const directory = relativeDirectory(root, query.path);
+      const forCaller = (snapshot) => snapshot.available ? { ...snapshot, directory } : snapshot;
+      const cached = cache.get(key);
+      if (cached !== void 0 && cached.fresh) return forCaller(cached.value);
+      const running = inFlight.get(key);
+      if (running !== void 0) return forCaller(await awaitCallerCancellation(running, signal));
+      const attempt = (async () => {
+        const snapshot = await fetchSnapshot(deps, query, root, directory, void 0, bounded);
+        if (snapshot.available || snapshot.reason === "tier-1" || snapshot.reason === "agent-unsupported") {
+          cache.set(key, snapshot, "");
+        }
+        return snapshot;
+      })();
+      inFlight.set(key, attempt);
+      const settle = () => {
+        if (inFlight.get(key) === attempt) inFlight.delete(key);
+      };
+      attempt.then(settle, settle);
+      return forCaller(await awaitCallerCancellation(attempt, signal));
+    },
+    invalidate(connectionId) {
+      if (connectionId === void 0) return;
+      cache.invalidatePrefix(`${connectionId}\0`);
+    },
+    get cacheStats() {
+      return cache.stats;
+    }
+  };
+}
+async function fetchSnapshot(deps, query, root, directory, signal, bounded) {
+  let transport;
+  try {
+    transport = await deps.transportFor(query.connectionId);
+  } catch (error) {
+    if (signal?.aborted === true || isCancellation(error)) throw error;
+    return { available: false, reason: "transport-unavailable", changes: [], truncated: false };
+  }
+  if (!isGitStatusTransport(transport)) {
+    return { available: false, reason: "tier-1", changes: [], truncated: false };
+  }
+  let answer;
+  try {
+    answer = await transport.gitStatus(root, signal);
+  } catch (error) {
+    if (signal?.aborted === true || isCancellation(error)) throw error;
+    const code = isSshDevError(error) ? error.code : void 0;
+    if (code === "REMOTE_UNSUPPORTED") return { available: false, reason: "agent-unsupported", changes: [], truncated: false };
+    if (isSshDevError(error) && error.details["agentCode"] === "E_PARAMS") return { available: false, reason: "not-a-work-tree", changes: [], truncated: false };
+    return { available: false, reason: "git-status-failed", changes: [], truncated: false };
+  }
+  const capped = bounded(answer.changes, answer.truncated);
+  return {
+    available: true,
+    root,
+    directory,
+    ...answer.branch === void 0 ? {} : { branch: answer.branch },
+    changes: capped.changes,
+    truncated: capped.truncated
+  };
+}
+function isCancellation(error) {
+  return isSshDevError(error) && error.code === "CANCELLED";
+}
+function relativeDirectory(root, path) {
+  const normalizedRoot = normalizeRemotePath(root);
+  const normalizedPath = normalizeRemotePath(path);
+  if (!remotePathContains(normalizedRoot, normalizedPath)) return "";
+  if (normalizedRoot === normalizedPath) return "";
+  return normalizedPath.slice(normalizedRoot === "/" ? 1 : normalizedRoot.length + 1);
+}
+
+// src/host/domain/roots/root.ts
+function normalizeLocalPath2(path, options = {}) {
+  return normalizeLocalPath(path, { caseInsensitive: options.caseInsensitive ?? process.platform === "win32" });
+}
+
+// src/shared/routes.ts
+function asRouteHost(value) {
+  if (typeof value !== "object" || value === null) return void 0;
+  const register = value.register;
+  return typeof register === "function" ? value : void 0;
+}
+
+// src/host/app/roots/roots-api-contract.ts
+var ROOTS_API_MAX_BODY_BYTES = 64 * 1024;
+function trustVerdict(req) {
+  const host = headerOf(req, "host");
+  if (host === void 0) return "no-host";
+  const hostUrl = parseAuthority(host);
+  if (hostUrl === void 0) return "bad-host";
+  if (headerOf(req, "sec-fetch-site") === "cross-site") return "cross-site";
+  const origin = headerOf(req, "origin");
+  if (origin === void 0) return "ok";
+  const trimmed = origin.trim();
+  if (trimmed === "" || trimmed === "null") return "bad-origin";
+  let originUrl;
+  try {
+    originUrl = new URL(trimmed);
+  } catch {
+    return "bad-origin";
+  }
+  if (originUrl.protocol !== "http:" && originUrl.protocol !== "https:") return "bad-origin";
+  if (originUrl.host === hostUrl.host) return "ok";
+  if (originUrl.port === "" && originUrl.hostname === hostUrl.hostname) return "ok";
+  return "bad-origin";
+}
+function trustMessage(verdict) {
+  switch (verdict) {
+    case "no-host":
+      return "\u8BF7\u6C42\u7F3A\u5C11 Host \u5934\uFF0C\u62D2\u7EDD";
+    case "bad-host":
+      return "Host \u5934\u65E0\u6CD5\u89E3\u6790\uFF0C\u62D2\u7EDD";
+    case "cross-site":
+      return "\u8DE8\u7AD9\u8BF7\u6C42\uFF08Sec-Fetch-Site: cross-site\uFF09\u88AB\u62D2\u7EDD";
+    case "bad-origin":
+      return "\u8BF7\u6C42\u7684 Origin \u4E0E Host \u4E0D\u540C\u6E90\uFF0C\u62D2\u7EDD";
+    default:
+      return "ok";
+  }
+}
+function headerOf(req, name) {
+  const value = req.headers[name] ?? req.headers[name.toLowerCase()];
+  if (value === void 0) return void 0;
+  return Array.isArray(value) ? value[0] : value;
+}
+function parseAuthority(authority) {
+  try {
+    return new URL(`http://${authority}`);
+  } catch {
+    return void 0;
+  }
+}
+
+// src/host/app/roots/roots-api-http.ts
+async function readBody(req, maxBytes) {
+  const chunks = [];
+  let total = 0;
+  for await (const chunk of req) {
+    const buffer = toBytes(chunk);
+    total += buffer.length;
+    if (total > maxBytes) {
+      throw new SshDevError("ROOT_INVALID", `\u8BF7\u6C42\u4F53\u8D85\u8FC7\u4E0A\u9650 ${maxBytes} \u5B57\u8282\uFF0C\u62D2\u7EDD`);
+    }
+    chunks.push(buffer);
+  }
+  return Buffer.concat(chunks).toString("utf8");
+}
+function toBytes(chunk) {
+  if (typeof chunk === "string") return Buffer.from(chunk, "utf8");
+  if (chunk instanceof Uint8Array) return chunk;
+  throw new Error("\u8BF7\u6C42\u4F53\u5206\u7247\u4E0D\u662F\u5B57\u7B26\u4E32\u4E5F\u4E0D\u662F\u5B57\u8282\u5E8F\u5217");
+}
+function send(req, res, status, value) {
+  res.statusCode = status;
+  res.setHeader("content-type", "application/json; charset=utf-8");
+  res.setHeader("cache-control", "no-store");
+  const body = `${JSON.stringify(value)}
+`;
+  res.end((req.method ?? "GET").toUpperCase() === "HEAD" ? void 0 : body);
+}
+function asRecord(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return void 0;
+  return value;
+}
+function messageOf(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+
+// src/host/infra/transport/git-status-route.ts
+var GIT_STATUS_API_PATH = "/api/over-ssh/git-status";
+function toPublicAnswer(snapshot) {
+  return {
+    ok: true,
+    available: snapshot.available,
+    ...snapshot.root === void 0 ? {} : { root: snapshot.root },
+    ...snapshot.directory === void 0 ? {} : { directory: snapshot.directory },
+    ...snapshot.branch === void 0 ? {} : { branch: snapshot.branch },
+    changes: snapshot.changes.map((change) => ({ path: change.path, status: change.status })),
+    truncated: snapshot.truncated,
+    ...snapshot.reason === void 0 ? {} : { reason: snapshot.reason }
+  };
+}
+function createGitStatusApi(deps) {
+  const handle = async (req, res) => {
+    const method = (req.method ?? "GET").toUpperCase();
+    if (method !== "POST" && method !== "GET" && method !== "HEAD") {
+      res.setHeader("allow", "GET, HEAD, POST");
+      send(req, res, 405, { ok: false, error: `\u4E0D\u652F\u6301\u7684\u65B9\u6CD5\uFF1A${method}` });
+      return;
+    }
+    const verdict = trustVerdict(req);
+    if (verdict !== "ok") {
+      send(req, res, 403, { ok: false, error: trustMessage(verdict) });
+      return;
+    }
+    if (method !== "POST") {
+      res.setHeader("allow", "POST");
+      send(req, res, 405, { ok: false, error: "git-status \u53EA\u63A5\u53D7 POST" });
+      return;
+    }
+    try {
+      const body = asRecord(JSON.parse(await readBody(req, ROOTS_API_MAX_BODY_BYTES)));
+      const connectionId = body?.["connectionId"];
+      const path = body?.["path"];
+      if (typeof connectionId !== "string" || connectionId === "") {
+        send(req, res, 400, { ok: false, error: "git-status \u9700\u8981 connectionId", reason: "bad-connection" });
+        return;
+      }
+      if (typeof path !== "string" || path === "") {
+        send(req, res, 400, { ok: false, error: "git-status \u9700\u8981 path", reason: "bad-path" });
+        return;
+      }
+      const controller = new AbortController();
+      const onClose = () => {
+        controller.abort();
+      };
+      res.on?.("close", onClose);
+      let snapshot;
+      try {
+        snapshot = await deps.service.status({ connectionId, path }, controller.signal);
+      } finally {
+        res.off?.("close", onClose);
+      }
+      send(req, res, 200, toPublicAnswer(snapshot));
+    } catch (error) {
+      const invalidBody = error instanceof SyntaxError;
+      send(req, res, invalidBody ? 400 : 500, { ok: false, error: messageOf(error) });
+    }
+  };
+  return { handle };
+}
+function registerGitStatusRoute(provider, deps) {
+  const api = createGitStatusApi(deps);
+  try {
+    provider.inject(["webServer"], (scoped) => {
+      const host = asRouteHost(scoped.get("webServer"));
+      if (host === void 0) return void 0;
+      try {
+        const dispose = host.register({ kind: "exact", path: GIT_STATUS_API_PATH, handler: api.handle });
+        return () => dispose();
+      } catch {
+        return void 0;
+      }
+    });
+  } catch {
+  }
+}
+
+// src/host/integration/fs/git-status-wiring.ts
+function wireGitStatus(ctx) {
+  const service = createGitStatusService({
+    transportFor: async (connectionId) => {
+      const connections = ctx.get("sshDevConnections");
+      const transports = ctx.get("sshDevTransports");
+      if (connections === void 0 || transports === void 0) return void 0;
+      const profile = connections.get(connectionId);
+      if (profile === void 0) return void 0;
+      const acquired = await transports.acquire(profile);
+      return acquired.transport;
+    },
+    resolveRoot: (connectionId, path) => {
+      const registry = ctx.get("sshDevRoots");
+      if (registry === void 0) return void 0;
+      const roots = registry.records.map((record) => record.root).filter((root) => root.location === "remote" && root.connectionId === connectionId).map((root) => root.path);
+      return longestContainingRoot(roots, normalizeRemotePath(path));
+    }
+  });
+  registerGitStatusRoute(ctx, { service });
+}
+
+// src/host/domain/literal-text.ts
+function countOccurrences(haystack, needle) {
+  if (needle === "") return 0;
+  let count = 0;
+  let index = haystack.indexOf(needle);
+  while (index !== -1) {
+    count += 1;
+    index = haystack.indexOf(needle, index + needle.length);
+  }
+  return count;
+}
+function replaceLiteral(source, needle, replacement, all) {
+  if (needle === "") return { text: source, replacements: 0 };
+  if (all) {
+    const parts = source.split(needle);
+    return { text: parts.join(replacement), replacements: parts.length - 1 };
+  }
+  const at = source.indexOf(needle);
+  if (at === -1) return { text: source, replacements: 0 };
+  return {
+    text: `${source.slice(0, at)}${replacement}${source.slice(at + needle.length)}`,
+    replacements: 1
+  };
+}
+
+// src/host/integration/session-scope.ts
+import { AsyncLocalStorage } from "node:async_hooks";
+var STORE_KEY = /* @__PURE__ */ Symbol.for("dsh-over-ssh/session-scope");
+function store() {
+  const holder = globalThis;
+  const existing = holder[STORE_KEY];
+  if (existing !== void 0) return existing;
+  const created = new AsyncLocalStorage();
+  holder[STORE_KEY] = created;
+  return created;
+}
+function currentSessionId() {
+  return store().getStore()?.sessionId;
+}
+var MAX_FORK_DEPTH = 32;
+var ancestorCache = /* @__PURE__ */ new Map();
+var ANCESTOR_CACHE_MAX = 256;
+function readSessionAncestors(ctx, sessionId) {
+  const cached = ancestorCache.get(sessionId);
+  if (cached !== void 0) {
+    ancestorCache.delete(sessionId);
+    ancestorCache.set(sessionId, cached);
+    return cached;
+  }
+  const walked = walkAncestors(ctx, sessionId);
+  if (walked.settled) {
+    ancestorCache.set(sessionId, walked.ancestors);
+    while (ancestorCache.size > ANCESTOR_CACHE_MAX) {
+      const oldest = ancestorCache.keys().next();
+      if (oldest.done === true) break;
+      ancestorCache.delete(oldest.value);
+    }
+  }
+  return walked.ancestors;
+}
+function walkAncestors(ctx, sessionId) {
+  let list;
+  try {
+    const sessions = ctx.get("sessions");
+    list = sessions?.list?.();
+  } catch {
+    return { ancestors: [], settled: false };
+  }
+  if (!Array.isArray(list)) return { ancestors: [], settled: false };
+  const parents = /* @__PURE__ */ new Map();
+  let settled = false;
+  for (const session of list) {
+    const id = session?.header?.id;
+    const parent = session?.header?.parentSession;
+    if (typeof id !== "string" || id === "") continue;
+    if (id === sessionId) settled = true;
+    if (typeof parent === "string" && parent !== "") parents.set(id, parent);
+  }
+  const ancestors = [];
+  let current = parents.get(sessionId);
+  while (current !== void 0 && ancestors.length < MAX_FORK_DEPTH && !ancestors.includes(current)) {
+    ancestors.push(current);
+    current = parents.get(current);
+  }
+  return { ancestors, settled };
+}
+
+// src/host/integration/fs/fs-provider.ts
+var MAX_WHOLE_READ_BYTES = 16 * 1024 * 1024;
+var BINARY_SNIFF_BYTES = 8e3;
+var UTF8 = new TextDecoder("utf-8", { ignoreBOM: true });
+var MIN_RANGE_CHUNK_BYTES = 1;
+var MAX_RANGE_WINDOW_BYTES = 8 * 1024 * 1024;
+var MAX_RANGE_CHUNK_BYTES = MAX_RANGE_WINDOW_BYTES;
+var RoutedFsProvider = class extends FileSystem {
+  static inject = ["sshDevRoots"];
+  // `protected`, not `#private`, on purpose: the platform reaches this service through `ctx.fs`, which
+  // Cordis wraps in a Proxy, and a `#private` read through a Proxy throws ("…whose class did not declare
+  // it"). Every method here may run with the Proxy as `this`, so the state it touches cannot be `#private`.
+  rangeReader;
+  rangeChunkBytes;
+  /** Reads the live sessions' working directories; see {@link RoutedFsProviderOptions.sessionWorkspaceCwds}. */
+  sessionWorkspaceCwds;
+  /** Reads one session's fork lineage; see {@link RoutedFsProviderOptions.sessionAncestors}. */
+  sessionAncestors;
+  /**
+   * Change detector for {@link syncSessionRoots}: the state the last sync produced.
+   *
+   * A small mutable holder rather than a `string` field: every method here may run with the Cordis service Proxy
+   * as `this`, and mutating a property through that Proxy is the one thing this class must not rely on — mutating
+   * a property of an object it *read* through the Proxy is fine.
+   */
+  sessionSync;
+  constructor(ctx, options = {}) {
+    super(ctx);
+    this.rangeReader = options.readBytesRange;
+    this.sessionWorkspaceCwds = options.sessionWorkspaceCwds ?? (() => readSessionCwds(ctx));
+    this.sessionAncestors = options.sessionAncestors ?? ((sessionId) => readSessionAncestors(ctx, sessionId));
+    this.sessionSync = { lastSignature: "" };
+    startHostErrorDetection();
+    const requested = Math.floor(options.rangeChunkBytes ?? MAX_RANGE_CHUNK_BYTES);
+    this.rangeChunkBytes = Number.isFinite(requested) && requested > 0 ? Math.min(Math.max(requested, MIN_RANGE_CHUNK_BYTES), MAX_RANGE_CHUNK_BYTES) : MAX_RANGE_CHUNK_BYTES;
+  }
+  /** This provider confines writes to the registered roots. */
+  get sandboxMode() {
+    return "workspace-write";
+  }
+  /** Resolve a model-facing path to the router's target and wrap it for the core. */
+  async resolve(path, opts) {
+    const resolved = this.resolveWithSessionSync(path, opts?.cwd);
+    if (!resolved.ok) throw toFsError(resolved.error);
+    return { targetKey: FsTargetKey(resolved.target.targetKey), displayPath: resolved.target.displayPath };
+  }
+  /** Path a subprocess in the target's world can open (the remote absolute path for remote roots). */
+  processPath(target) {
+    const routed = this.routedTarget(target);
+    return routed.backend.processPath?.(routed.absolute) ?? routed.absolute;
+  }
+  /**
+   * Map a host path into the process world: for a local root the two are the same string.
+   *
+   * **This is a mapping, not an access check.** It used to answer `undefined` for any path outside the
+   * registered local roots, which broke the platform's own machinery: the PTC worker maps its runtime into the
+   * subprocess world through this method, so every `run_code` call died with
+   * `PTC runtime bootstrap is unavailable in the subprocess execution world:
+   * …/@deepseek-ai/dsh-ptc-runtime-node/lib/process.js` — a file that exists and that the harness has every
+   * right to read (2026-10-31, reported by the user as "the session cannot read the workspace").
+   *
+   * The core's own `dsh-fs-local` answers `resolve(hostPath)` unconditionally for exactly this reason: the
+   * question is "what is this host path called in the process world", not "may this caller open it". Access
+   * control lives in {@link resolve}/{@link readFile}/{@link writeText}, where the roots are enforced.
+   */
+  processPathFromHostPath(hostPath) {
+    if (!isAbsoluteHostPath(hostPath)) return void 0;
+    return normalizeLocalPath2(hostPath, { caseInsensitive: false });
+  }
+  /** Canonical `file:` URI in the target's world. */
+  fileUrl(target) {
+    const routed = this.routedTarget(target);
+    if (routed.backend.fileUrl !== void 0) return routed.backend.fileUrl(routed.absolute);
+    return `file://${encodeURI(routed.absolute)}`;
+  }
+  /** Containment; two targets in different worlds never contain one another. */
+  contains(parent, child) {
+    const left = this.routedTarget(parent);
+    const right = this.routedTarget(child);
+    if (left.backendKey !== right.backendKey) return false;
+    return this.router().contains(left, right);
+  }
+  /** Metadata, or `undefined` for an absent target. */
+  async stat(target, signal) {
+    const routed = this.routedTarget(target);
+    const info = await this.call(() => routed.backend.stat(routed.absolute, signal));
+    if (!info.exists) return void 0;
+    return toFsInfo(info);
+  }
+  /** Path metadata without following a final symlink, where the backend can tell. */
+  async lstat(path, opts, signal) {
+    const resolved = this.resolveWithSessionSync(path, opts?.cwd);
+    if (!resolved.ok) throw toFsError(resolved.error);
+    const routed = resolved.target;
+    const info = await this.call(() => this.router().statTarget(routed, { followSymlink: false, ...signal === void 0 ? {} : { signal } }));
+    if (!info.exists) return void 0;
+    const fsInfo = toFsInfo(info);
+    return info.isSymlink ? { version: fsInfo.version, type: "symlink", ...fsInfo.size === void 0 ? {} : { size: fsInfo.size } } : fsInfo;
+  }
+  /**
+   * Whole-file UTF-8 text; binary and oversize files fail with typed codes.
+   *
+   * Reads **bytes** rather than calling `backend.readText`, so the binary sniff happens before decoding: the
+   * previous shape asked the backend for the decoded text and then re-encoded the whole string
+   * (`Buffer.from(text, 'utf8')`) only to look at its first {@link BINARY_SNIFF_BYTES} bytes. Measured on a
+   * 9 MiB file (audit 2026-11-01b follow-up): `open`+`stat`+`read` 2.65 ms, `+` decode 3.95 ms, `+` the
+   * redundant re-encode **5.66 ms** — 1.71 ms, ~75% of the plugin's overhead, spent to encode bytes the caller
+   * had just decoded. `TextDecoder` then decodes straight off the read buffer without the extra copy.
+   */
+  async readText(target, signal) {
+    const routed = this.routedTarget(target);
+    const chunk = await this.call(() => routed.backend.readBytes(routed.absolute, MAX_WHOLE_READ_BYTES, signal));
+    if (chunk.truncated) {
+      throw platformFsError(`cannot read "${routed.displayPath}": file exceeds ${MAX_WHOLE_READ_BYTES} bytes`, "FS_TOO_LARGE");
+    }
+    assertText(routed.displayPath, chunk.bytes);
+    return UTF8.decode(chunk.bytes);
+  }
+  /**
+   * Stream text in chunks, paging through the offset reader when the composition injected one.
+   *
+   * The platform calls this for every file at or above **its own** streaming threshold —
+   * `@deepseek-ai/dsh-tool-fs/lib/index.js:217` (`STREAM_MIN_SIZE = 10 * 1024 * 1024`) feeding `:338` — and
+   * `@deepseek-ai/dsh-fs/lib/types/index.d.ts:164-172` makes the backend own both the chunking and the
+   * cross-chunk UTF-8 decoding. Answering by reading the whole file first, which is what this did, made that
+   * contract a lie twice over: it buffered the entire file *and* it refused anything past the whole-file cap
+   * with `FS_TOO_LARGE`, so the `read` tool could not open a large remote log at all even when the caller had
+   * asked for one window of it.
+   *
+   * Without the offset seam the previous semantics are kept exactly: one bounded whole read, one chunk, and
+   * `FS_TOO_LARGE` past the cap. Nothing pretends to be chunked when it is not.
+   */
+  async streamText(target, signal) {
+    const routed = this.routedTarget(target);
+    const reader = this.rangeReader;
+    const chunkBytes = this.rangeChunkBytes;
+    if (reader !== void 0) {
+      const probe = await this.call(
+        () => reader(routed.backend, { absolute: routed.absolute, offset: 0, length: chunkBytes }, signal)
+      );
+      if (probe !== null) {
+        assertText(routed.displayPath, Buffer.from(probe.bytes.subarray(0, BINARY_SNIFF_BYTES)));
+        return pagedText(reader, chunkBytes, routed, probe, signal);
+      }
+    }
+    const text = await this.readText(target, signal);
+    return (async function* whole() {
+      yield text;
+    })();
+  }
+  /** Whole-file bytes, refusing oversized targets instead of truncating. */
+  async readBytes(target, signal, maxBytes) {
+    const routed = this.routedTarget(target);
+    const chunk = await this.call(() => routed.backend.readBytes(routed.absolute, maxBytes, signal));
+    if (chunk.truncated) {
+      throw platformFsError(`cannot read "${routed.displayPath}": file exceeds ${maxBytes} bytes`, "FS_TOO_LARGE");
+    }
+    return chunk.bytes;
+  }
+  /**
+   * One byte window, bounded by the caller's window rather than the file size.
+   *
+   * Two paths, and they are deliberately distinguishable:
+   *
+   *  - the backend has an offset read (the injected {@link BackendRangeReader} answers with a window):
+   *    the window is fetched as a sequence of requests of at most the configured chunk size, each
+   *    starting at the file offset it needs. Nothing before `offset` is ever transferred or held, so
+   *    the memory bound is the chunk size plus the returned window, not the file size. The window
+   *    itself is capped at {@link MAX_RANGE_WINDOW_BYTES} — it is returned whole, so it is allocated
+   *    whole, and an unbounded `length` would be an unbounded allocation;
+   *  - the backend has none (a local backend, a transport without `readFileRange`, or no injected
+   *    reader at all): the previous semantics are kept exactly — one bounded prefix read `[0, end)`
+   *    capped at 8 MiB, then a slice — and a window past that cap still fails with `FS_TOO_LARGE`
+   *    instead of silently buffering the file.
+   */
+  async readByteRange(target, range, signal) {
+    const routed = this.routedTarget(target);
+    const start = Math.max(0, Math.floor(range.offset));
+    const wanted = Math.max(0, Math.floor(range.length));
+    if (wanted === 0) return new Uint8Array(0);
+    if (wanted > MAX_RANGE_WINDOW_BYTES) {
+      throw platformFsError(
+        `cannot read "${routed.displayPath}": the requested window (${wanted} bytes) exceeds the ${MAX_RANGE_WINDOW_BYTES}-byte limit`,
+        "FS_TOO_LARGE"
+      );
+    }
+    assertNotAborted(signal, `${routed.displayPath} [${start}, ${start + wanted})`);
+    const reader = this.rangeReader;
+    const chunkBytes = this.rangeChunkBytes;
+    const chunked = await this.call(() => readChunkedWindow(reader, chunkBytes, routed, start, wanted, signal));
+    if (chunked !== void 0) return chunked;
+    const end = start + wanted;
+    if (end > MAX_RANGE_WINDOW_BYTES) {
+      throw platformFsError(
+        `cannot read "${routed.displayPath}": this backend cannot read the window [${start}, ${end}) without buffering it (limit ${MAX_RANGE_WINDOW_BYTES} bytes)`,
+        "FS_TOO_LARGE"
+      );
+    }
+    const chunk = await this.call(() => routed.backend.readBytes(routed.absolute, end, signal));
+    return chunk.bytes.subarray(start, Math.min(end, chunk.bytes.byteLength));
+  }
+  /** Direct children, in stable name order, with resolved child targets. */
+  async listDir(target, signal) {
+    const routed = this.routedTarget(target);
+    const entries = await this.call(() => this.router().listTarget(routed, signal));
+    return entries.map((entry) => ({
+      name: entry.name,
+      type: entry.isDirectory ? "directory" : entry.isFile ? "file" : "other",
+      target: { targetKey: FsTargetKey(entry.targetKey), displayPath: entry.displayPath },
+      // 后端给的令牌带 inode，是唯一与 mtime 精度无关的「换过文件」信号；秒级现算会把同一秒内的
+      // 两次写入算成同一个版本（审计 0086）。只有后端没给时才退回现算，且退回时也用毫秒而不是秒。
+      version: FsVersion(entry.version ?? `${entry.size}:${entry.mtimeMs}`),
+      size: entry.size
+    }));
+  }
+  /** Atomic write, honouring the write intent and the plugin's fence. */
+  async writeText(target, content, expected, signal, sandboxPolicy) {
+    const routed = this.routedTarget(target);
+    this.assertWritable(routed, sandboxPolicy);
+    const info = await this.call(() => routed.backend.stat(routed.absolute, signal));
+    const existed = info.exists;
+    const before = existed ? await this.readPriorText(routed, info, signal) : void 0;
+    if (expected?.kind === "createIfAbsent" && existed) {
+      throw platformFsError(`cannot create "${routed.displayPath}": target already exists`, "FS_NOT_OBSERVED");
+    }
+    const guard = expected?.kind === "replaceIfVersion" ? expected.version : void 0;
+    const outcome = await this.call(
+      () => routed.backend.writeText(routed.absolute, content, guard, signal)
+    ).catch((error) => {
+      throw mapWriteError(error, routed.displayPath);
+    });
+    return {
+      operation: existed ? "update" : "create",
+      version: FsVersion(outcome.version),
+      // `before` is the **diff basis**, so it is LF-normalized exactly like `after`
+      // (`@deepseek-ai/dsh-fs/lib/types/index.d.ts:118-134`: "LF-normalized storage text (the diff basis)"),
+      // and the core's own backend does the same (`dsh-fs-local/lib/index.js:872,879`). Reporting the raw text
+      // made every CRLF file render as a whole-file diff: `@deepseek-ai/dsh-tool-fs/lib/index.js:596` diffs
+      // `before` against an LF-normalized `after`, so one changed line looked like every line changed.
+      before: before === void 0 ? null : normalizeLineEndings(before),
+      after: normalizeLineEndings(content)
+    };
+  }
+  /** Literal edit with the core's three-state semantics and an optional version guard. */
+  async editText(target, edit, expected, signal, sandboxPolicy) {
+    const routed = this.routedTarget(target);
+    this.assertWritable(routed, sandboxPolicy);
+    const chunk = await this.call(() => routed.backend.readText(routed.absolute, MAX_WHOLE_READ_BYTES, signal)).catch((error) => {
+      throw mapWriteError(error, routed.displayPath);
+    });
+    if (expected !== void 0 && expected.version !== chunk.version) {
+      throw platformFsError(`cannot edit "${routed.displayPath}": file changed since it was read`, "FS_STALE_VERSION");
+    }
+    const lineEndings = chunk.text.includes("\r\n") ? "\r\n" : "\n";
+    const before = normalizeLineEndings(chunk.text);
+    const occurrences = countOccurrences(before, edit.oldString);
+    if (occurrences === 0) {
+      throw platformFsError(`cannot edit "${routed.displayPath}": the requested text was not found`, "FS_EDIT_NOT_FOUND");
+    }
+    if (occurrences > 1 && !edit.replaceAll) {
+      throw platformFsError(`cannot edit "${routed.displayPath}": the requested text appears ${occurrences} times`, "FS_AMBIGUOUS_EDIT");
+    }
+    const after = replaceLiteral(before, edit.oldString, edit.newString, edit.replaceAll === true).text;
+    if (routed.backend.editText !== void 0 && lineEndings === "\n") {
+      try {
+        const native = await this.call(
+          () => routed.backend.editText(
+            routed.absolute,
+            edit.oldString,
+            edit.newString,
+            edit.replaceAll === true,
+            chunk.version,
+            signal
+          )
+        );
+        return { version: FsVersion(native.version), before, after };
+      } catch (error) {
+        if (!isSshDevError(error) || error.code !== "REMOTE_UNSUPPORTED") {
+          throw mapWriteError(error, routed.displayPath);
+        }
+      }
+    }
+    const outcome = await this.call(
+      () => routed.backend.writeText(routed.absolute, restoreLineEndings(after, lineEndings), chunk.version, signal)
+    ).catch((error) => {
+      throw mapWriteError(error, routed.displayPath);
+    });
+    return { version: FsVersion(outcome.version), before, after };
+  }
+  /**
+   * Watch one target through its backend.
+   *
+   * The route decides the world, then the backend owns the mechanism:
+   *
+   *  - **local roots** delegate to the platform's own `FileSystem.watch` (chokidar) via `PlatformLocalBackend`.
+   *    Before this method was wired, taking over `ctx.fs` made **local** files stop reporting changes: the
+   *    platform's `dsh-api-workspace-files` got `workspace-file/watch-unsupported` for every target, because
+   *    `RoutedFsProvider` replaced the sandboxed provider (a `LocalFileSystem` subclass) and this method only
+   *    ever threw. Delegating restores the pre-takeover behaviour without a second chokidar implementation.
+   *  - **remote roots** with a native agent watcher use `watch.start/poll/stop`; Tier 1 remains unsupported
+   *    and keeps failing honestly (the caller falls back to revalidation on read).
+   *
+   * A backend that has **no** `watch` method keeps the historical `FS_IO_ERROR` refusal — never a silent
+   * no-op, which would leave a consumer believing it is subscribed.
+   *
+   * @param target - the target whose changes were requested.
+   * @param changed - platform callback: re-stat on no argument, subscription-failure on an error.
+   * @param signal - cancels watcher initialization and subscription.
+   * @returns the disposer (`() => Promise<void>`), idempotent.
+   * @throws FsError `FS_IO_ERROR` when the backend cannot watch, plus the mapped backend failures
+   *   (`FS_NOT_FOUND`, `AbortError` for cancellation, …).
+   */
+  async watch(target, changed, signal) {
+    const routed = this.routedTarget(target);
+    const backendWatch = routed.backend.watch;
+    if (backendWatch === void 0) {
+      throw platformFsError(`filesystem watching is not supported for "${routed.displayPath}"`, "FS_IO_ERROR");
+    }
+    return await this.call(() => backendWatch.call(routed.backend, routed.absolute, changed, signal));
+  }
+  rootsService() {
+    const registry = this.ctx.sshDevRoots;
+    if (registry === void 0) {
+      throw platformFsError("the over-ssh root registry is not registered", "FS_IO_ERROR");
+    }
+    return registry;
+  }
+  router() {
+    return this.rootsService().routed;
+  }
+  /**
+   * Resolve a path, syncing the live sessions' working directories once if it fails.
+   *
+   * Why on failure rather than before every call: the sync costs a walk of the live-session list plus a
+   * containment scan over the roots, and the overwhelming majority of resolutions succeed against a registered
+   * root. Why it must exist at all: the platform reads the workspace through `ctx.fs` by **absolute path without
+   * a cwd** while a turn starts, so a session whose own directory no root covers lost the entire turn before the
+   * model was called — there was no cwd to key a fallback on.
+   *
+   * One sync, then one retry: a session that appeared a moment ago is therefore picked up on its **first** read
+   * rather than failing once and working on the next call, and a second failure means the sync genuinely had
+   * nothing to add (the path is outside every root), so the caller gets the original error.
+   *
+   * @param path - model-facing path.
+   * @param cwd - the caller's session cwd, when it has one.
+   * @returns the resolution; when nothing changed the caller keeps the **original** failure.
+   */
+  resolveWithSessionSync(path, cwd) {
+    const options = this.sessionRouteOptions(cwd);
+    const first = this.router().tryResolve(path, options);
+    if (first.ok) return first;
+    this.syncSessionRoots();
+    return this.router().tryResolve(path, options);
+  }
+  /**
+   * The route options for one call: the cwd the platform supplied, plus the session identity this call runs
+   * under when the tool dispatcher carried one down (`integration/session-scope.ts`, ADR-0013).
+   *
+   * Both are kept because they answer different questions. The cwd is what the platform's contract provides
+   * (relative spellings, the workspace-level rule, the anchor rule); the session is the only thing that can
+   * separate two conversations opened on the same directory. A call with neither is an agentless one and keeps
+   * the plugin-wide view, exactly as before.
+   *
+   * @param cwd - the caller's session cwd, when it has one.
+   * @returns the options to hand the route table.
+   */
+  sessionRouteOptions(cwd) {
+    const sessionId = currentSessionId();
+    const identity = sessionId === void 0 || sessionId === "" ? void 0 : { sessionId, ancestors: this.sessionAncestors(sessionId) };
+    const sessionCwd = cwd !== void 0 || sessionId === void 0 || sessionId === "" ? void 0 : this.sessionWorkspaceCwdOf(sessionId);
+    return {
+      ...cwd === void 0 ? {} : { cwd },
+      ...identity === void 0 ? {} : { session: identity },
+      ...sessionCwd === void 0 ? {} : { sessionCwd }
+    };
+  }
+  /**
+   * The working directory of one live session, or `undefined` when it is not listed.
+   *
+   * @param sessionId - the asking session.
+   * @returns its cwd, when the platform reports one.
+   */
+  sessionWorkspaceCwdOf(sessionId) {
+    return readSessionCwd(this.ctx, sessionId);
+  }
+  /**
+   * Re-read the live sessions and register their working directories as session roots.
+   *
+   * Guarded by **change detection**, not by a time window: reading the session list and comparing it with the
+   * state the last sync produced costs microseconds, while a time throttle would have a window in which a session
+   * created a moment ago is not registered yet — and that session's very first read is exactly the one that used
+   * to kill the turn. The signature includes the session roots that currently exist, so a registry reset (which
+   * drops them) is noticed and repaired too.
+   */
+  syncSessionRoots() {
+    try {
+      const cwds = this.sessionWorkspaceCwds();
+      if (cwds.length === 0) return;
+      const registry = this.rootsService();
+      if (sessionSyncSignature(cwds, registry) === this.sessionSync.lastSignature) return;
+      registry.syncSessionWorkspaces(cwds);
+      this.sessionSync.lastSignature = sessionSyncSignature(cwds, registry);
+    } catch {
+    }
+  }
+  routedTarget(target) {
+    try {
+      return this.router().targetFromKey(target.targetKey);
+    } catch (error) {
+      throw isSshDevError(error) ? toFsError(error) : error;
+    }
+  }
+  /** Enforce the per-call policy and the root's own writability. */
+  assertWritable(routed, policy) {
+    const mode = policy?.mode ?? this.sandboxMode;
+    if (mode === "read-only") {
+      throw platformFsError(`sandbox denies writing "${routed.displayPath}" (read-only)`, "FS_SANDBOX_DENIED");
+    }
+    if (routed.root.writable === false) {
+      throw platformFsError(`the root of "${routed.displayPath}" is registered read-only`, "FS_SANDBOX_DENIED");
+    }
+  }
+  /**
+   * Previous text content, when it is readable text inside the cap; `undefined` otherwise.
+   *
+   * `undefined` here means **"no previous text to report"**, never "the target is absent" — the caller
+   * already decided existence from {@link BackendStat.exists}. Keeping those two apart is what stops a
+   * directory / oversized / binary file from slipping past a `createIfAbsent` guard.
+   */
+  async readPriorText(routed, info, signal) {
+    if (info.isDirectory || info.size > MAX_WHOLE_READ_BYTES) return void 0;
+    const chunk = await routed.backend.readText(routed.absolute, MAX_WHOLE_READ_BYTES, signal).catch((error) => {
+      if (signal?.aborted === true) throw error;
+      return void 0;
+    });
+    if (chunk === void 0 || chunk.truncated) return void 0;
+    const bytes = Buffer.from(chunk.text, "utf8");
+    const sniff = bytes.subarray(0, BINARY_SNIFF_BYTES);
+    if (sniff.includes(0)) return void 0;
+    return chunk.text;
+  }
+  /** Run a backend call, translating domain errors into core codes. */
+  async call(operation) {
+    try {
+      return await operation();
+    } catch (error) {
+      if (isFsError(error)) throw error;
+      throw isSshDevError(error) ? toFsError(error) : error;
+    }
+  }
+};
+function createRoutedFsProvider(options) {
+  const plugin = ((ctx) => {
+    new RoutedFsProvider(ctx, options);
+    try {
+      wireGitStatus(ctx);
+    } catch (error) {
+      ctx.logger?.warn?.(`git status route: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  });
+  plugin.inject = RoutedFsProvider.inject;
+  return plugin;
+}
+function assertNotAborted(signal, what) {
+  if (signal?.aborted !== true) return;
+  const error = new Error(`the read of ${what} was cancelled`);
+  error.name = "AbortError";
+  throw error;
+}
+function toFsInfo(info) {
+  return {
+    version: FsVersion(info.version),
+    type: info.isDirectory ? "directory" : info.isFile ? "file" : "other",
+    ...info.isDirectory ? {} : { size: info.size }
+  };
+}
+async function readChunkedWindow(reader, chunkBytes, routed, offset, length, signal) {
+  if (reader === void 0) return void 0;
+  const buffer = Buffer.allocUnsafe(length);
+  let filled = 0;
+  while (filled < length) {
+    signal?.throwIfAborted();
+    const requestLength = Math.min(length - filled, chunkBytes);
+    const window = await reader(
+      routed.backend,
+      { absolute: routed.absolute, offset: offset + filled, length: requestLength },
+      signal
+    );
+    if (window === null) return void 0;
+    assertNotAborted(signal, `${routed.displayPath} [${offset + filled}, ${offset + filled + requestLength})`);
+    const bytes = window.bytes.subarray(0, requestLength);
+    Buffer.from(bytes).copy(buffer, filled);
+    filled += bytes.byteLength;
+    if (window.truncated === false || bytes.byteLength === 0) break;
+  }
+  return new Uint8Array(buffer.buffer, buffer.byteOffset, filled);
+}
+async function* pagedText(reader, chunkBytes, routed, firstWindow, signal) {
+  const decoder = new StringDecoder("utf8");
+  let offset = 0;
+  let window = firstWindow;
+  for (; ; ) {
+    signal?.throwIfAborted();
+    const bytes = Buffer.from(window.bytes.subarray(0, chunkBytes));
+    offset += bytes.byteLength;
+    if (bytes.byteLength > 0) {
+      const text = decoder.write(bytes);
+      if (text.length > 0) yield text;
+    }
+    if (window.truncated === false || bytes.byteLength === 0) break;
+    window = await reader(routed.backend, { absolute: routed.absolute, offset, length: chunkBytes }, signal).catch((error) => {
+      throw isSshDevError(error) ? toFsError(error) : error;
+    });
+    assertNotAborted(signal, `${routed.displayPath} [${offset}, ${offset + chunkBytes})`);
+    if (window === null) {
+      throw platformFsError(
+        `cannot stream "${routed.displayPath}": the backend stopped offering offset reads mid-stream`,
+        "FS_IO_ERROR"
+      );
+    }
+  }
+  const tail = decoder.end();
+  if (tail.length > 0) yield tail;
+}
+function sessionSyncSignature(cwds, registry) {
+  const roots = registry.sessionWorkspaceRecords.map((record) => record.key).join("\0");
+  return `${cwds.join("\0")}
${roots}`;
+}
+function readSessionCwd(ctx, sessionId) {
+  let list;
+  try {
+    const sessions = ctx.get("sessions");
+    list = sessions?.list?.();
+  } catch {
+    return void 0;
+  }
+  if (!Array.isArray(list)) return void 0;
+  for (const session of list) {
+    if (session?.header?.id !== sessionId) continue;
+    const cwd = session.header.cwd;
+    return typeof cwd === "string" && cwd !== "" ? cwd : void 0;
+  }
+  return void 0;
+}
+function readSessionCwds(ctx) {
+  let list;
+  try {
+    const sessions = ctx.get("sessions");
+    list = sessions?.list?.();
+  } catch {
+    return [];
+  }
+  if (!Array.isArray(list)) return [];
+  const cwds = [];
+  for (const session of list) {
+    const cwd = session?.header?.cwd;
+    if (typeof cwd === "string" && cwd !== "") cwds.push(cwd);
+  }
+  return cwds;
+}
+function assertText(displayPath, bytes) {
+  if (bytes.subarray(0, BINARY_SNIFF_BYTES).includes(0)) {
+    throw platformFsError(`cannot read "${displayPath}": not a UTF-8 text file`, "FS_NOT_TEXT");
+  }
+}
+function normalizeLineEndings(text) {
+  return text.replace(/\r\n/g, "\n");
+}
+function restoreLineEndings(text, lineEndings) {
+  return lineEndings === "\n" ? text : text.replace(/\n/g, lineEndings);
+}
+function isAbsoluteHostPath(path) {
+  return /^[A-Za-z]:[\\/]/.test(path) || path.startsWith("/") || path.startsWith("//");
+}
+function toFsError(error) {
+  if (error.code === "CANCELLED") {
+    const cancelled = new Error(`the filesystem operation was cancelled: ${error.message}`);
+    cancelled.name = "AbortError";
+    throw cancelled;
+  }
+  const code = error.code === "REMOTE_NOT_FOUND" || error.code === "ROOT_OUTSIDE" ? "FS_NOT_FOUND" : error.code === "SANDBOX_DENIED" ? "FS_SANDBOX_DENIED" : error.code === "TRANSFER_CONFLICT" ? "FS_STALE_VERSION" : "FS_IO_ERROR";
+  return platformFsError(`${error.code}: ${error.message}`, code, { cause: error });
+}
+function mapWriteError(error, displayPath) {
+  if (isFsError(error)) return error;
+  if (isSshDevError(error)) {
+    if (error.code === "TRANSFER_CONFLICT") {
+      return platformFsError(`cannot write "${displayPath}": file changed since it was read`, "FS_STALE_VERSION", { cause: error });
+    }
+    return toFsError(error);
+  }
+  return error;
+}
+var MAPPED_DOMAIN_CODES = [
+  "REMOTE_NOT_FOUND",
+  "ROOT_OUTSIDE",
+  "SANDBOX_DENIED",
+  "TRANSFER_CONFLICT",
+  "REMOTE_UNSUPPORTED",
+  "ROOT_INVALID",
+  "REMOTE_COMMAND_FAILED",
+  "CANCELLED"
+];
+
+// src/fs.ts
+function apply(ctx) {
+  if (ctx.get("fs") !== void 0) {
+    ctx.logger?.warn?.("fs: ctx.fs \u5DF2\u88AB\u5360\u7528\uFF08\u6838\u5FC3 fs-sandbox \u4ECD\u5728\uFF09\uFF0C\u672C\u6B21\u8DF3\u8FC7\u63A5\u7BA1\uFF1B\u8981\u63A5\u7BA1\u8BF7\u540C\u65F6\u7981\u7528\u6838\u5FC3\u884C");
+    return void 0;
+  }
+  const range = ctx.get("sshDevRangeReader");
+  return ctx.plugin(
+    createRoutedFsProvider({
+      ...range === void 0 ? {} : { readBytesRange: range.readBytesRange },
+      ...range?.rangeChunkBytes === void 0 ? {} : { rangeChunkBytes: range.rangeChunkBytes }
+    })
+  );
+}
+export {
+  MAPPED_DOMAIN_CODES,
+  RoutedFsProvider,
+  createRoutedFsProvider,
+  apply as default,
+  toFsError
+};