@syrkos/filaxis 0.1.0-alpha.10

package/dist/index.js

@@ -0,0 +1,4200 @@
+var __esm = (fn, res, err) => () => {
+  if (fn)
+    try {
+      res = fn(fn = 0);
+    } catch (e) {
+      err = [e];
+    }
+  if (err)
+    throw err[0];
+  return res;
+};
+
+// src/ssh-helpers.ts
+import { homedir } from "node:os";
+import { join } from "node:path";
+function renderForwardArg(f) {
+  if (f.kind === "D")
+    return String(f.port);
+  return `${f.bind ? `${f.bind}:` : ""}${f.port}:${f.target ?? ""}`;
+}
+function hopHost(hop) {
+  return isHopObj(hop) ? hop.host : hop;
+}
+function hopLabel(hop) {
+  if (!isHopObj(hop) || !hop.conn)
+    return hopHost(hop);
+  const { user, port, jump, forwards } = hop.conn;
+  let s = `${user ? `${user}@` : ""}${hopHost(hop)}${port ? `:${port}` : ""}`;
+  if (jump)
+    s += ` -J ${jump}`;
+  if (forwards?.length) {
+    s += ` ${forwards.map((f) => f.kind === "D" ? `-D${f.port}` : `-${f.kind}${f.port}→${f.target}`).join(" ")}`;
+  }
+  return s;
+}
+function sshArgsFor(hop) {
+  if (!isHopObj(hop) || !hop.conn)
+    return [hopHost(hop)];
+  const { user, port, keyFile, jump, forwards } = hop.conn;
+  const args = [];
+  if (jump)
+    args.push("-J", jump);
+  if (keyFile)
+    args.push("-i", expandHomePath(keyFile));
+  if (port)
+    args.push("-p", String(port));
+  for (const f of forwards ?? []) {
+    args.push(f.kind === "L" ? "-L" : f.kind === "R" ? "-R" : "-D", renderForwardArg(f));
+  }
+  args.push(user ? `${user}@${hopHost(hop)}` : hopHost(hop));
+  return args;
+}
+function sshArgsQuoted(hop) {
+  return sshArgsFor(hop).map((a) => /^[A-Za-z0-9_@:./-]+$/.test(a) ? a : `"${a.replace(/"/g, "\\\"")}"`).join(" ");
+}
+function expandHomePath(p) {
+  if (p === "~")
+    return homedir();
+  if (p.startsWith("~/") || p.startsWith("~\\"))
+    return join(homedir(), p.slice(2));
+  return p;
+}
+function enterStepsOf(config) {
+  if (Array.isArray(config?.enterPipeline)) {
+    return config.enterPipeline.filter((s) => s && typeof s.cmd === "string" && s.cmd).map((s) => ({ cmd: String(s.cmd), label: s.label ? String(s.label) : undefined }));
+  }
+  const legacy = config?.enterCmd ? String(config.enterCmd) : "";
+  return legacy ? [{ cmd: legacy, label: config?.enterLabel ? String(config.enterLabel) : undefined }] : [];
+}
+function autonomousSshOpts(conn) {
+  const opts = ["-o", "ConnectTimeout=10", "-o", "ServerAliveInterval=30", "-o", "ServerAliveCountMax=3"];
+  if (conn?.hostKeyPolicy === "strict") {
+    opts.push("-o", "StrictHostKeyChecking=yes");
+    if (conn.knownHostsFile) {
+      opts.push("-o", `UserKnownHostsFile=${expandHomePath(conn.knownHostsFile)}`);
+    }
+  } else {
+    opts.push("-o", "StrictHostKeyChecking=accept-new");
+  }
+  return opts;
+}
+function rootSshSpawnArgs(destArgs, conn) {
+  return ["-tt", ...autonomousSshOpts(conn), ...destArgs];
+}
+function hopSshCommand(hop) {
+  const conn = typeof hop === "object" ? hop.conn : undefined;
+  return `ssh ${autonomousSshOpts(conn).join(" ")} ${sshArgsQuoted(hop)}`;
+}
+async function resolveSshIdentity(hop) {
+  const cacheKey = typeof hop === "string" ? hop : JSON.stringify(hop);
+  const cached = identityCache.get(cacheKey);
+  if (cached)
+    return cached;
+  try {
+    const { execFile } = await import("node:child_process");
+    const { promisify } = await import("node:util");
+    const X = promisify(execFile);
+    const { stdout } = await X("ssh", ["-G", ...sshArgsFor(hop)], { timeout: 8000 });
+    const h = stdout.match(/^hostname (\S+)$/m)?.[1] ?? hopHost(hop);
+    const p = stdout.match(/^port (\d+)$/m)?.[1] ?? "22";
+    const u = stdout.match(/^user (\S+)$/m)?.[1] ?? "";
+    const id = `${u ? u + "@" : ""}${h}:${p}`;
+    identityCache.set(cacheKey, id);
+    return id;
+  } catch {
+    return `unresolved:${hopHost(hop)}`;
+  }
+}
+function layerPathIdentities(desc) {
+  const hops = Array.isArray(desc.config?.sshHops) ? desc.config.sshHops : [];
+  const connParams = desc.config?.connParams;
+  const root = desc.target ? connParams ? { host: desc.target, conn: connParams } : desc.target : "";
+  return [root, ...hops].filter(Boolean);
+}
+function layerDisplayName(desc) {
+  const hops = (Array.isArray(desc.config?.sshHops) ? desc.config.sshHops : []).map((h) => hopLabel(h));
+  const connParams = desc.config?.connParams;
+  const root = hopLabel(connParams ? { host: desc.target ?? "?", conn: connParams } : desc.target ?? "?");
+  const parts = [root, ...hops];
+  parts.push(...enterStepsOf(desc.config).map((s) => s.label ?? s.cmd.slice(0, 24)));
+  return parts.join(" → ");
+}
+function layerDisplayLabel(d) {
+  const base = layerDisplayName(d.descriptor);
+  return d.containerId ? `${base}(${d.containerId})` : base;
+}
+function renderExecChannel(steps, command, opts) {
+  const remoteArgs = [];
+  for (const s of steps) {
+    const cleaned = s.cmd.replace(/(^|\s)-(it|ti)\b/g, "$1-i").replace(/(^|\s)-t\b/g, "$1-i").trim();
+    const m = SHELL_TAIL_RE.exec(cleaned);
+    if (!m) {
+      return { kind: "unreachable", reason: "进入命令非「… shell」形态（无法非交互重放）", step: s.cmd };
+    }
+    remoteArgs.push(...cleaned.split(/\s+/), "-s");
+  }
+  remoteArgs.push("sh", "-s");
+  const cd = opts.cwd ? `cd ${JSON.stringify(opts.cwd)} 2>/dev/null || true; ` : "";
+  return { kind: "ok", remoteArgs, stdinCmd: `${cd}${opts.nonceWrapped}` };
+}
+var isHopObj = (h) => typeof h === "object", SSH_INPUT_WAIT_RE, identityCache, SHELL_TAIL_RE;
+var init_ssh_helpers = __esm(() => {
+  SSH_INPUT_WAIT_RE = /(?:password|passphrase|verification\s+code|login|密码|口令)[^\n]*[:：]\s*$|yes\s*\/\s*no|are you sure|continue connecting/i;
+  identityCache = new Map;
+  SHELL_TAIL_RE = /(?:^|\s)(bash|sh|zsh|ash|dash)\s*$/;
+});
+// src/session-buffer.ts
+var MAX_PENDING_BYTES = 2 * 1024 * 1024;
+
+class LineAssembler {
+  pending = "";
+  feed(chunk) {
+    this.pending += chunk;
+    const lines = [];
+    let idx;
+    while ((idx = this.pending.indexOf(`
+`)) !== -1) {
+      let line = this.pending.slice(0, idx);
+      if (line.endsWith("\r"))
+        line = line.slice(0, -1);
+      lines.push(line);
+      this.pending = this.pending.slice(idx + 1);
+    }
+    if (this.pending.length > MAX_PENDING_BYTES) {
+      lines.push(this.pending.slice(0, MAX_PENDING_BYTES) + "[TRUNCATED_CHUNK]");
+      this.pending = "";
+    }
+    return lines;
+  }
+  flush() {
+    if (this.pending === "")
+      return [];
+    const rest = this.pending.endsWith("\r") ? this.pending.slice(0, -1) : this.pending;
+    this.pending = "";
+    return rest === "" ? [] : [rest];
+  }
+}
+var TRUNC_SUFFIX = "[…truncated, see session log]";
+
+class OutputRingBuffer {
+  maxLines;
+  maxLineBytes;
+  lines = [];
+  evictedLines = 0;
+  constructor(opts = {}) {
+    this.maxLines = opts.maxLines ?? 50;
+    this.maxLineBytes = opts.maxLineBytes ?? 512;
+  }
+  push(line) {
+    let text = line.text;
+    if (text.length > this.maxLineBytes) {
+      const keep = Math.max(0, this.maxLineBytes - TRUNC_SUFFIX.length);
+      text = text.slice(0, keep) + TRUNC_SUFFIX;
+    }
+    this.lines.push({ stream: line.stream, text });
+    if (this.lines.length > this.maxLines) {
+      const overflow = this.lines.length - this.maxLines;
+      this.lines = this.lines.slice(-this.maxLines);
+      this.evictedLines += overflow;
+    }
+  }
+  tail(n) {
+    return this.lines.slice(-Math.max(0, n)).map((l) => l.text);
+  }
+  tailLines(n) {
+    return this.lines.slice(-Math.max(0, n));
+  }
+  get evictedCount() {
+    return this.evictedLines;
+  }
+  contextAround(index, contextLines) {
+    const from = Math.max(0, index - contextLines);
+    const to = Math.min(this.lines.length, index + contextLines + 1);
+    return this.lines.slice(from, to);
+  }
+  indexOfLine(text) {
+    const i = this.lines.findIndex((l) => l.text === text);
+    return i === -1 ? this.lines.length - 1 : i;
+  }
+  get size() {
+    return this.lines.length;
+  }
+}
+var MAX_WATCHERS_PER_SESSION = 8;
+
+class WatchRegistry {
+  watchers = new Map;
+  add(spec) {
+    if (this.watchers.size >= MAX_WATCHERS_PER_SESSION) {
+      throw new Error(`watcher 数量已达上限（${MAX_WATCHERS_PER_SESSION}/会话），先 cancel 旧的再注册`);
+    }
+    this.watchers.set(spec.id, { ...spec, regex: this.toRegex(spec.pattern) });
+  }
+  match(line) {
+    const hits = [];
+    for (const [id, w] of this.watchers) {
+      if (w.regex.test(line)) {
+        hits.push(id);
+        if (w.once !== false)
+          this.watchers.delete(id);
+      }
+    }
+    return hits;
+  }
+  cancel(id) {
+    return this.watchers.delete(id);
+  }
+  get size() {
+    return this.watchers.size;
+  }
+  toRegex(pattern) {
+    if (pattern instanceof RegExp)
+      return pattern;
+    const escaped = pattern.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    return new RegExp(escaped);
+  }
+}
+// src/logger.ts
+var noopLogger = {
+  debug: () => {
+    return;
+  },
+  info: () => {
+    return;
+  },
+  warn: () => {
+    return;
+  },
+  error: () => {
+    return;
+  }
+};
+// src/local-session-manager.ts
+import { spawn } from "node:child_process";
+import fs from "node:fs/promises";
+import { createWriteStream } from "node:fs";
+import path from "node:path";
+import { tmpdir } from "node:os";
+import * as crypto from "node:crypto";
+
+// src/shell-discovery.ts
+import { existsSync } from "node:fs";
+import { execSync } from "node:child_process";
+var GIT_BASH_CANDIDATES = [
+  "C:\\Program Files\\Git\\bin\\bash.exe",
+  "C:\\Program Files\\Git\\usr\\bin\\bash.exe",
+  "C:\\Program Files (x86)\\Git\\bin\\bash.exe"
+];
+function bashOnPath() {
+  try {
+    return execSync("where bash", { stdio: ["ignore", "pipe", "ignore"] }).toString().split(`
+`).map((l) => l.trim()).filter(Boolean)[0];
+  } catch {
+    return;
+  }
+}
+function resolveLocalShell(preferred, log) {
+  if (preferred)
+    return preferred;
+  if (process.platform !== "win32")
+    return "bash";
+  const fromEnv = process.env.FILAXIS_SHELL;
+  if (fromEnv)
+    return fromEnv;
+  const p = bashOnPath();
+  if (p && !/System32/i.test(p))
+    return "bash";
+  for (const c of GIT_BASH_CANDIDATES) {
+    if (existsSync(c))
+      return c;
+  }
+  log?.warn("[Filaxis] Windows 未找到可用 bash（PATH " + (p ? "上是 WSL 转发入口" : "上无 bash") + "且未嗅探到 Git Bash）——请安装 Git（https://git-scm.com）或设 FILAXIS_SHELL 指向 bash.exe 完整路径");
+  return "bash";
+}
+
+// src/local-session-manager.ts
+function escapeRegExp(p) {
+  return p.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+var MAX_FILE_LINE_BYTES = 1e6;
+var MAX_SESSION_LOG_BYTES = 64 * 1024 * 1024;
+var KILL_GRACE_MS = 1500;
+
+class LocalSessionManager {
+  onEvent = () => {
+    return;
+  };
+  entries = new Map;
+  maxLines;
+  maxLineBytes;
+  ttlMs;
+  logDir;
+  shell;
+  log;
+  spawnImpl;
+  constructor(opts = {}) {
+    this.maxLines = opts.maxLines ?? 50;
+    this.maxLineBytes = opts.maxLineBytes ?? 512;
+    this.ttlMs = opts.ttlMs ?? 10 * 60000;
+    this.logDir = opts.logDir ?? path.join(tmpdir(), "filaxis-sessions");
+    this.log = opts.logger ?? noopLogger;
+    this.shell = resolveLocalShell(opts.shell, this.log);
+    this.spawnImpl = opts.spawnImpl ?? ((cmd, argv, o) => spawn(cmd, argv, o));
+  }
+  async start(command, opts = {}) {
+    const sessionId = `${opts.name ? opts.name.replace(/[^a-zA-Z0-9_-]/g, "-") + "-" : "sess-"}` + crypto.randomBytes(4).toString("hex");
+    await fs.mkdir(this.logDir, { recursive: true });
+    const logBase = path.join(this.logDir, sessionId);
+    const entry = {
+      sessionId,
+      command,
+      startedAt: Date.now(),
+      ownerSessionId: opts.ownerSessionId,
+      ring: new OutputRingBuffer({ maxLines: this.maxLines, maxLineBytes: this.maxLineBytes }),
+      watchers: new WatchRegistry,
+      watcherMeta: new Map,
+      assemblers: { stdout: new LineAssembler, stderr: new LineAssembler },
+      logStreams: {
+        stdout: createWriteStream(`${logBase}.out`),
+        stderr: createWriteStream(`${logBase}.err`)
+      },
+      logBase,
+      logBytes: 0,
+      logCapped: false,
+      running: true
+    };
+    this.entries.set(sessionId, entry);
+    const env = { ...process.env, ...opts.env };
+    const cwd = opts.cwd || process.cwd();
+    const proc = this.spawnImpl(this.shell, ["-c", command], {
+      env,
+      cwd,
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+    entry.proc = proc;
+    proc.stdout?.on("data", (buf) => this.ingestChunk(entry, buf.toString("utf-8"), "stdout"));
+    proc.stderr?.on("data", (buf) => this.ingestChunk(entry, buf.toString("utf-8"), "stderr"));
+    proc.on("close", (code) => this.finalize(entry, code));
+    proc.on("error", (err) => {
+      this.ingestLine(entry, `[session-error] ${err.message}`, "stderr");
+      this.finalize(entry, null);
+    });
+    this.log.info(`[Session ${sessionId}] started: ${command.slice(0, 80)} (pid=${proc.pid})`);
+    return { sessionId, logBase, pid: proc.pid };
+  }
+  tail(sessionId, n = 50) {
+    return this.require(sessionId).ring.tail(n);
+  }
+  tailLines(sessionId, n = 50) {
+    return this.require(sessionId).ring.tailLines(n);
+  }
+  async readLog(sessionId, opts = {}) {
+    const entry = this.require(sessionId);
+    const file = opts.stream === "stderr" ? `${entry.logBase}.err` : `${entry.logBase}.out`;
+    let content;
+    try {
+      content = await fs.readFile(file, "utf-8");
+    } catch {
+      return "";
+    }
+    let lines = content.split(`
+`);
+    if (lines.length > 0 && lines[lines.length - 1] === "")
+      lines.pop();
+    if (opts.offsetLines)
+      lines = lines.slice(opts.offsetLines);
+    if (opts.lines)
+      lines = lines.slice(-opts.lines);
+    return lines.join(`
+`);
+  }
+  watch(sessionId, opts) {
+    const entry = this.require(sessionId);
+    const watcherId = `w-${crypto.randomBytes(3).toString("hex")}`;
+    entry.watchers.add({ id: watcherId, pattern: opts.pattern, once: opts.once });
+    entry.watcherMeta.set(watcherId, opts);
+    const regex = opts.pattern instanceof RegExp ? opts.pattern : new RegExp(escapeRegExp(String(opts.pattern)));
+    for (const l of entry.ring.tailLines(Infinity)) {
+      if (regex.test(l.text)) {
+        if (opts.once !== false) {
+          entry.watchers.cancel(watcherId);
+          entry.watcherMeta.delete(watcherId);
+        }
+        if (opts.thenStop)
+          this.stop(sessionId).catch(() => {
+            return;
+          });
+        this.emit({
+          type: "match",
+          sessionId,
+          ownerSessionId: entry.ownerSessionId,
+          watcherId,
+          pattern: String(opts.pattern),
+          matchedLine: l.text,
+          stream: l.stream,
+          context: entry.ring.contextAround(entry.ring.size - 1, opts.contextLines ?? 5).map((c) => c.text)
+        });
+        break;
+      }
+    }
+    return {
+      cancel: () => {
+        entry.watchers.cancel(watcherId);
+        entry.watcherMeta.delete(watcherId);
+      }
+    };
+  }
+  async ready(sessionId, opts) {
+    const entry = this.require(sessionId);
+    const regex = opts.pattern instanceof RegExp ? opts.pattern : new RegExp(opts.pattern.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"));
+    for (const l of entry.ring.tailLines(Infinity)) {
+      if (regex.test(l.text))
+        return { matchedLine: l.text };
+    }
+    if (entry.ring.evictedCount > 0) {
+      throw new Error(`就绪标记可能已滚出热窗口（evicted=${entry.ring.evictedCount}，历史不完整）——` + `可经 readLog 回查 ${entry.logBase}.out/.err，或加大窗口后重启会话`);
+    }
+    return await new Promise((resolve, reject) => {
+      const w = this.watch(sessionId, { pattern: opts.pattern, once: true });
+      let poll;
+      const timer = setTimeout(() => {
+        if (poll)
+          clearInterval(poll);
+        w.cancel();
+        this.stop(sessionId).catch(() => {
+          return;
+        });
+        reject(new Error(`ready() 超时（${opts.timeoutMs}ms）未见到就绪标记——会话已自动停止`));
+      }, opts.timeoutMs);
+      poll = setInterval(() => {
+        const e = this.entries.get(sessionId);
+        if (!e) {
+          clearTimeout(timer);
+          clearInterval(poll);
+          reject(new Error(`会话 ${sessionId} 已消失（终态回收）`));
+          return;
+        }
+        for (const l of e.ring.tailLines(5)) {
+          if (regex.test(l.text)) {
+            clearTimeout(timer);
+            clearInterval(poll);
+            w.cancel();
+            resolve({ matchedLine: l.text });
+            return;
+          }
+        }
+      }, 30);
+      poll.unref?.();
+      if (!entry.running) {
+        clearTimeout(timer);
+        clearInterval(poll);
+        reject(new Error(`会话 ${sessionId} 已退出（exitCode=${entry.exitCode ?? "?"}），就绪标记未出现`));
+      }
+    });
+  }
+  async stop(sessionId) {
+    const entry = this.require(sessionId);
+    if (!entry.running) {
+      return { status: "exited", exitCode: entry.exitCode };
+    }
+    if (entry.proc?.pid) {
+      try {
+        entry.proc.kill("SIGTERM");
+      } catch {}
+      const pid = entry.proc.pid;
+      setTimeout(() => {
+        try {
+          process.kill(pid, "SIGKILL");
+        } catch {}
+      }, KILL_GRACE_MS).unref();
+    }
+    for (let i = 0;i < 20 && entry.running; i++) {
+      await new Promise((r) => setTimeout(r, 50));
+    }
+    if (!entry.running)
+      return { status: "exited", exitCode: entry.exitCode };
+    return { status: "stopped" };
+  }
+  list() {
+    return Array.from(this.entries.values()).map((e) => ({
+      sessionId: e.sessionId,
+      command: e.command,
+      running: e.running,
+      startedAt: e.startedAt
+    }));
+  }
+  require(sessionId) {
+    const e = this.entries.get(sessionId);
+    if (!e)
+      throw new Error(`session '${sessionId}' 不存在（可能已终态被 TTL 回收）`);
+    return e;
+  }
+  ingestChunk(entry, text, stream) {
+    for (const line of entry.assemblers[stream].feed(text))
+      this.ingestLine(entry, line, stream);
+  }
+  ingestLine(entry, fullLine, stream) {
+    const fileChunk = fullLine.length > MAX_FILE_LINE_BYTES ? fullLine.slice(0, MAX_FILE_LINE_BYTES) + `
+[…file-line-truncated]` : fullLine;
+    if (!entry.logCapped) {
+      entry.logBytes += fileChunk.length + 1;
+      if (entry.logBytes > MAX_SESSION_LOG_BYTES) {
+        entry.logCapped = true;
+        for (const s of ["stdout", "stderr"]) {
+          entry.logStreams[s].end(s === stream ? `[log-capped: session log exceeded ${MAX_SESSION_LOG_BYTES} bytes, file writes suppressed; ring buffer continues]
+` : `[log-capped]
+`);
+        }
+      } else {
+        entry.logStreams[stream].write(fileChunk + `
+`);
+      }
+    }
+    entry.ring.push({ stream, text: fullLine });
+    const anchor = entry.ring.size - 1;
+    for (const watcherId of entry.watchers.match(fullLine)) {
+      const meta = entry.watcherMeta.get(watcherId);
+      entry.watcherMeta.delete(watcherId);
+      if (meta?.thenStop) {
+        this.stop(entry.sessionId).catch(() => {
+          return;
+        });
+      }
+      this.emit({
+        type: "match",
+        sessionId: entry.sessionId,
+        ownerSessionId: entry.ownerSessionId,
+        watcherId,
+        pattern: String(meta?.pattern ?? "?"),
+        matchedLine: entry.ring.tail(1)[0] ?? fullLine,
+        stream,
+        context: entry.ring.contextAround(anchor, meta?.contextLines ?? 5).map((l) => l.text)
+      });
+    }
+  }
+  finalize(entry, exitCode) {
+    if (!entry.running)
+      return;
+    entry.running = false;
+    entry.exitCode = exitCode;
+    for (const s of ["stdout", "stderr"]) {
+      for (const line of entry.assemblers[s].flush())
+        this.ingestLine(entry, line, s);
+      if (!entry.logCapped)
+        entry.logStreams[s].end();
+    }
+    entry.watcherMeta.clear();
+    this.emit({
+      type: "exit",
+      sessionId: entry.sessionId,
+      ownerSessionId: entry.ownerSessionId,
+      exitCode,
+      lastLines: entry.ring.tail(20)
+    });
+    this.log.info(`[Session ${entry.sessionId}] exited code=${exitCode}`);
+    entry.ttlTimer = setTimeout(() => this.entries.delete(entry.sessionId), this.ttlMs).unref();
+  }
+  emit(ev) {
+    try {
+      this.onEvent(ev);
+    } catch (err) {
+      this.log.warn(`session event sink threw: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+}
+// src/local-driver.ts
+import { spawn as spawn2 } from "node:child_process";
+import fs2 from "node:fs/promises";
+import { createWriteStream as createWriteStream2 } from "node:fs";
+import path2 from "node:path";
+import { tmpdir as tmpdir2 } from "node:os";
+import * as crypto2 from "node:crypto";
+class LocalRuntimeDriver {
+  descriptor = { driver: "local", target: "localhost" };
+  fs;
+  sessions;
+  defaultCwd;
+  execDir;
+  shell;
+  log;
+  constructor(opts = {}) {
+    this.defaultCwd = opts.cwd;
+    this.execDir = opts.execDir ?? path2.join(tmpdir2(), "filaxis-exec");
+    this.log = opts.logger ?? noopLogger;
+    this.shell = resolveLocalShell(opts.shell, this.log);
+    this.fs = new LocalFileSystem;
+    this.sessions = new LocalSessionManager({
+      logDir: path2.join(this.execDir, "sessions"),
+      shell: this.shell,
+      logger: this.log
+    });
+  }
+  static fromDescriptor(descriptor, fallbackCwd) {
+    const drv = new LocalRuntimeDriver({ cwd: descriptor.cwd ?? fallbackCwd });
+    drv.descriptor = descriptor;
+    return drv;
+  }
+  async init() {}
+  async destroy() {}
+  async getCwd() {
+    return this.defaultCwd || process.cwd();
+  }
+  async getEnv(key) {
+    return process.env[key];
+  }
+  async execSession(command, opts) {
+    return this.sessions.start(command, opts);
+  }
+  async tailSession(sessionId, lines = 50) {
+    return this.sessions.tail(sessionId, lines);
+  }
+  async readSessionLog(sessionId, opts) {
+    return this.sessions.readLog(sessionId, opts);
+  }
+  watchSession(sessionId, opts) {
+    return this.sessions.watch(sessionId, opts);
+  }
+  async stopSession(sessionId) {
+    return this.sessions.stop(sessionId);
+  }
+  listSessions() {
+    return this.sessions.list();
+  }
+  async exec(command, options) {
+    if (options?.channel === "pty") {
+      throw new Error('local Transport 不支持 channel:"pty"（PTY 交互语义属远端 Transport；本地 exec 通道天然分离且恒可用）');
+    }
+    await fs2.mkdir(this.execDir, { recursive: true });
+    const taskId = crypto2.randomBytes(8).toString("hex");
+    const logPath = path2.join(this.execDir, `${taskId}.log`);
+    const statusPath = path2.join(this.execDir, `${taskId}.status.json`);
+    const nonce = crypto2.randomBytes(6).toString("hex");
+    const marker = `__FILAXIS_META_${nonce}__`;
+    const wrapped = `( ${command} ); __filaxis_ec=$?; ` + `printf '\\n${marker}:%d:%s\\n' "$__filaxis_ec" "$(id -un 2>/dev/null)"; ` + `exit $__filaxis_ec`;
+    return new Promise((resolve, reject) => {
+      let stdout = "";
+      let stderr = "";
+      const env = { ...process.env, ...options?.env };
+      const cwd = options?.cwd || this.defaultCwd || process.cwd();
+      const p = spawn2(this.shell, ["-c", wrapped], {
+        env,
+        cwd,
+        stdio: ["ignore", "pipe", "pipe"]
+      });
+      const startTime = Date.now();
+      const writeStatus = async (status, extra = {}) => {
+        try {
+          await fs2.writeFile(statusPath, JSON.stringify({
+            pid: p.pid,
+            command,
+            status,
+            startTime,
+            endTime: Date.now(),
+            ...extra
+          }, null, 2), "utf-8");
+        } catch {}
+      };
+      writeStatus("running");
+      const logStream = createWriteStream2(logPath);
+      p.stdout.on("data", (d) => {
+        stdout += d;
+        logStream.write(d);
+      });
+      p.stderr.on("data", (d) => {
+        stderr += d;
+        logStream.write(d);
+      });
+      let settled = false;
+      let finished = false;
+      const cleanupProcess = (exitStatus, extra = {}) => {
+        if (finished)
+          return;
+        finished = true;
+        logStream.end();
+        return writeStatus(exitStatus, extra);
+      };
+      const detachLifecycle = () => {
+        if (timeout)
+          clearTimeout(timeout);
+        if (onAbort)
+          signal?.removeEventListener("abort", onAbort);
+      };
+      const timeout = options?.timeoutMs ? setTimeout(() => {
+        if (settled)
+          return;
+        settled = true;
+        finished = true;
+        detachLifecycle();
+        p.unref();
+        logStream.end();
+        writeStatus("timeout", { error: "Command timeout", exitCode: null });
+        const e = new Error(`Command timeout after ${options.timeoutMs}ms (process continues in background, log: ${logPath}, status: ${statusPath})`);
+        e.outcome = "unknown";
+        reject(e);
+      }, options.timeoutMs) : null;
+      const signal = options?.signal;
+      const onAbort = signal ? () => {
+        if (settled)
+          return;
+        settled = true;
+        finished = true;
+        detachLifecycle();
+        try {
+          p.kill("SIGTERM");
+        } catch {}
+        logStream.end();
+        writeStatus("aborted", { error: "Aborted by AbortSignal", exitCode: null });
+        const abortErr = new Error("Command aborted by AbortSignal（本地进程已 SIGTERM，终态未核实——outcome=unknown）");
+        abortErr.name = "AbortError";
+        abortErr.outcome = "unknown";
+        reject(abortErr);
+      } : null;
+      if (signal && onAbort) {
+        if (signal.aborted)
+          onAbort();
+        else
+          signal.addEventListener("abort", onAbort, { once: true });
+      }
+      p.on("close", (code) => {
+        detachLifecycle();
+        if (settled)
+          return;
+        settled = true;
+        const finish = () => {
+          let out = stdout;
+          let effectiveUser;
+          let sentinelCode;
+          const mIdx = out.lastIndexOf(`
+${marker}:`);
+          if (mIdx !== -1) {
+            const metaLine = out.slice(mIdx + 1).split(`
+`, 1)[0] ?? "";
+            const m = metaLine.match(new RegExp(`^${marker}:(-?\\d+):(.*)$`));
+            if (m) {
+              effectiveUser = m[2] === "" ? undefined : m[2];
+              sentinelCode = parseInt(m[1], 10);
+              out = out.slice(0, mIdx);
+            }
+          }
+          logStream.end();
+          if (sentinelCode === undefined) {
+            writeStatus("killed", { exitCode: null, closeCode: code ?? null });
+            const e = new Error(`命令未完成（无完成哨兵——进程被信号终止，close code=${code}）。半截现场 stdout 尾 500:
+${out.slice(-500)}
+stderr 尾 300:
+${stderr.slice(-300)}`);
+            e.outcome = "unknown";
+            reject(e);
+            return;
+          }
+          writeStatus("completed", { exitCode: sentinelCode });
+          resolve({ stdout: out, stderr, exitCode: sentinelCode, effectiveUser });
+        };
+        finish();
+      });
+      p.on("error", (err) => {
+        detachLifecycle();
+        const pWrite = cleanupProcess("failed", { error: err.message, exitCode: -1 });
+        if (settled)
+          return;
+        settled = true;
+        if (pWrite)
+          pWrite.then(() => reject(err), () => reject(err));
+        else
+          reject(err);
+      });
+    });
+  }
+}
+
+class LocalFileSystem {
+  async readFile(filePath) {
+    return await fs2.readFile(filePath, "utf-8");
+  }
+  async readBase64(filePath) {
+    const buf = await fs2.readFile(filePath);
+    return Buffer.from(buf).toString("base64");
+  }
+  async writeFile(filePath, content) {
+    await fs2.writeFile(filePath, content, "utf-8");
+  }
+  async exists(filePath) {
+    try {
+      await fs2.access(filePath);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  async stat(filePath) {
+    try {
+      const st = await fs2.stat(filePath);
+      return { mtimeMs: st.mtimeMs, size: st.size };
+    } catch {
+      return null;
+    }
+  }
+  async readdir(dirPath) {
+    const dirents = await fs2.readdir(dirPath, { withFileTypes: true });
+    return await Promise.all(dirents.map(async (d) => {
+      const stats = await fs2.stat(path2.join(dirPath, d.name)).catch(() => null);
+      return {
+        name: d.name,
+        isDirectory: d.isDirectory(),
+        size: stats?.size,
+        mtime: stats?.mtimeMs
+      };
+    }));
+  }
+  async rm(filePath, options) {
+    await fs2.rm(filePath, options);
+  }
+  async mkdir(dirPath, options) {
+    await fs2.mkdir(dirPath, options);
+  }
+}
+// src/events.ts
+import { EventEmitter } from "node:events";
+var DEFAULT_ITER_QUEUE_MAX = 1024;
+
+class EventBus {
+  emitter = new EventEmitter;
+  queueMax;
+  iterables = new Set;
+  constructor(opts = {}) {
+    this.queueMax = opts.queueMax ?? DEFAULT_ITER_QUEUE_MAX;
+    this.emitter.setMaxListeners(0);
+  }
+  on(type, handler) {
+    const wrapped = (ev) => {
+      try {
+        handler(ev);
+      } catch {}
+    };
+    this.emitter.on(type === "*" ? "__all" : type, wrapped);
+    return () => this.emitter.off(type === "*" ? "__all" : type, wrapped);
+  }
+  once(type, handler) {
+    try {
+      this.emitter.once(type, handler);
+    } catch {}
+  }
+  off(type, handler) {
+    this.emitter.off(type === "*" ? "__all" : type, handler);
+  }
+  emit(ev) {
+    this.emitter.emit(ev.type, ev);
+    this.emitter.emit("__all", ev);
+    for (const it of this.iterables) {
+      if (!it.active)
+        continue;
+      if (it.queue.length >= this.queueMax) {
+        it.queue.shift();
+        it.dropped++;
+      }
+      it.queue.push(ev);
+    }
+  }
+  iterable(type) {
+    const entry = { queue: [], dropped: 0, active: true };
+    this.iterables.add(entry);
+    const handle = {
+      [Symbol.asyncIterator]: async function* () {
+        try {
+          while (entry.active) {
+            if (entry.queue.length === 0) {
+              await new Promise((r) => setTimeout(r, 10));
+              continue;
+            }
+            const ev = entry.queue.shift();
+            if (type && ev.type !== type)
+              continue;
+            yield ev;
+          }
+        } finally {
+          entry.active = false;
+        }
+      },
+      dropped: () => entry.dropped
+    };
+    handle.__entry = entry;
+    return handle;
+  }
+  listenerCount(type) {
+    return this.emitter.listenerCount(type === "*" || !type ? "__all" : type);
+  }
+}
+// src/ssh-pty-driver.ts
+import { spawn as spawn3 } from "node:child_process";
+import * as crypto4 from "node:crypto";
+init_ssh_helpers();
+
+// src/remote-session-manager.ts
+import * as crypto3 from "node:crypto";
+var q = (s) => `'${s.replace(/'/g, "'\\''")}'`;
+
+class RemoteSessionManager {
+  onEvent = () => {
+    return;
+  };
+  entries = new Map;
+  exec;
+  logDir;
+  pollMs;
+  idleReapMs;
+  log;
+  constructor(opts) {
+    this.exec = opts.exec;
+    this.logDir = opts.logDir ?? "/tmp/filaxis-sessions";
+    this.pollMs = opts.pollMs ?? 1500;
+    this.idleReapMs = opts.idleReapMs;
+    this.log = opts.logger ?? noopLogger;
+  }
+  async start(command, opts = {}) {
+    const sessionId = `${opts.name ? opts.name.replace(/[^a-zA-Z0-9_-]/g, "-") + "-" : "rsess-"}` + crypto3.randomBytes(4).toString("hex");
+    const base = `${this.logDir}/${sessionId}`;
+    const wrapped = `{ ${command}; }; echo $? > ${base}.code`;
+    const cd = opts.cwd ? `cd ${q(opts.cwd)} && ` : "";
+    const envPrefix = opts.env ? Object.entries(opts.env).map(([k, v]) => `${k}=${q(v)}`).join(" ") + " " : "";
+    const r = await this.exec(`mkdir -p ${q(this.logDir)}; ${cd}${envPrefix}nohup sh -c ${q(wrapped)} > ${base}.out 2> ${base}.err < /dev/null & echo $!`);
+    const pid = parseInt((r.stdout || "").trim().split(`
+`).pop() ?? "", 10);
+    const entry = {
+      sessionId,
+      command,
+      base,
+      pid: Number.isFinite(pid) ? pid : undefined,
+      startedAt: Date.now(),
+      ownerSessionId: opts.ownerSessionId,
+      running: true,
+      outOffset: 0,
+      assembler: new LineAssembler,
+      watchers: new Map,
+      lastAttentionAt: Date.now()
+    };
+    this.entries.set(sessionId, entry);
+    this.startPolling(entry);
+    this.log.info(`[RemoteSession ${sessionId}] started (pid=${entry.pid}): ${command.slice(0, 60)}`);
+    return { sessionId, logBase: base, pid: entry.pid };
+  }
+  async tail(sessionId, n = 50) {
+    const e = this.require(sessionId);
+    e.lastAttentionAt = Date.now();
+    const r = await this.exec(`tail -n ${n} ${e.base}.out 2>/dev/null || true`);
+    return (r.stdout || "").split(`
+`).filter((l, i, arr) => l !== "" || i < arr.length - 1).filter((l) => l !== "");
+  }
+  async readLog(sessionId, opts = {}) {
+    const e = this.require(sessionId);
+    const file = opts.stream === "stderr" ? `${e.base}.err` : `${e.base}.out`;
+    let cmd = `cat ${file} 2>/dev/null || true`;
+    if (opts.offsetLines)
+      cmd = `tail -n +${opts.offsetLines + 1} ${file} 2>/dev/null || true`;
+    if (opts.lines)
+      cmd += ` | tail -n ${opts.lines}`;
+    const r = await this.exec(cmd);
+    return (r.stdout || "").replace(/\n$/, "");
+  }
+  watch(sessionId, opts) {
+    const e = this.require(sessionId);
+    e.lastAttentionAt = Date.now();
+    const id = `rw-${crypto3.randomBytes(3).toString("hex")}`;
+    const regex = opts.pattern instanceof RegExp ? opts.pattern : new RegExp(opts.pattern.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"));
+    e.watchers.set(id, { ...opts, regex });
+    return {
+      cancel: () => {
+        e.watchers.delete(id);
+      }
+    };
+  }
+  async tailLines(sessionId, n = 50) {
+    const e = this.require(sessionId);
+    e.lastAttentionAt = Date.now();
+    const r = await this.exec(`tail -n ${n} ${e.base}.out 2>/dev/null; echo __FX_TL__; tail -n ${n} ${e.base}.err 2>/dev/null`);
+    const parts = (r.stdout || "").split("__FX_TL__");
+    const out = [];
+    for (const l of (parts[0] ?? "").split(`
+`)) {
+      if (l.trim() !== "")
+        out.push({ stream: "stdout", text: l });
+    }
+    for (const l of (parts[1] ?? "").split(`
+`)) {
+      if (l.trim() !== "")
+        out.push({ stream: "stderr", text: l });
+    }
+    return out;
+  }
+  async stop(sessionId) {
+    const e = this.require(sessionId);
+    if (!e.running)
+      return { status: e.exitCode != null ? "exited" : "stopped", exitCode: e.exitCode };
+    if (e.pid == null)
+      return { status: "unknown" };
+    try {
+      await this.exec(`pkill -TERM -P ${e.pid} 2>/dev/null; kill -TERM ${e.pid} 2>/dev/null; sleep 1; kill -0 ${e.pid} 2>/dev/null && echo ALIVE || echo DEAD`);
+      const probe = await this.exec(`kill -0 ${e.pid} 2>/dev/null && echo ALIVE || echo DEAD`);
+      if (probe.stdout.includes("ALIVE")) {
+        await this.exec(`pkill -KILL -P ${e.pid} 2>/dev/null; kill -KILL ${e.pid} 2>/dev/null; true`);
+      }
+      return { status: "stopped" };
+    } catch {
+      return { status: "unknown" };
+    }
+  }
+  list() {
+    return Array.from(this.entries.values()).map((e) => ({
+      sessionId: e.sessionId,
+      command: e.command,
+      running: e.running,
+      startedAt: e.startedAt
+    }));
+  }
+  reapIdle(now = Date.now(), ttlMs) {
+    const ttl = ttlMs ?? this.idleReapMs ?? 30 * 60 * 1000;
+    for (const e of Array.from(this.entries.values())) {
+      if (!e.running)
+        continue;
+      if (e.watchers.size > 0)
+        continue;
+      if (now - e.lastAttentionAt < ttl)
+        continue;
+      this.emit({
+        type: "exit",
+        sessionId: e.sessionId,
+        ownerSessionId: e.ownerSessionId,
+        exitCode: null,
+        lastLines: []
+      });
+      this.stop(e.sessionId).catch(() => {
+        return;
+      });
+    }
+  }
+  require(sessionId) {
+    const e = this.entries.get(sessionId);
+    if (!e)
+      throw new Error(`remote session '${sessionId}' 不存在`);
+    return e;
+  }
+  startPolling(entry) {
+    entry.pollTimer = setInterval(() => void this.poll(entry).catch(() => {
+      return;
+    }), this.pollMs);
+    entry.pollTimer.unref?.();
+  }
+  async poll(entry) {
+    if (!entry.running)
+      return;
+    try {
+      const r = await this.exec(`tail -n +${entry.outOffset + 1} ${entry.base}.out 2>/dev/null || true`);
+      const text = r.stdout || "";
+      if (text) {
+        entry.outOffset += text.split(`
+`).filter((l, i, a) => i < a.length - 1 || l !== "").length;
+        for (const line of entry.assembler.feed(text))
+          this.onLine(entry, line);
+      }
+      const code = await this.exec(`cat ${entry.base}.code 2>/dev/null || true`);
+      const codeStr = (code.stdout || "").trim();
+      if (codeStr !== "" && /^\d+$/.test(codeStr)) {
+        this.finalize(entry, parseInt(codeStr, 10));
+      } else if (entry.pid != null) {
+        const alive = await this.exec(`kill -0 ${entry.pid} 2>/dev/null && echo Y || echo N`);
+        if (alive.stdout.includes("N"))
+          this.finalize(entry, null);
+      }
+    } catch {}
+  }
+  onLine(entry, line) {
+    for (const [id, w] of entry.watchers) {
+      if (w.regex.test(line)) {
+        if (w.once !== false)
+          entry.watchers.delete(id);
+        if (w.thenStop)
+          this.stop(entry.sessionId).catch(() => {
+            return;
+          });
+        this.emit({
+          type: "match",
+          sessionId: entry.sessionId,
+          ownerSessionId: entry.ownerSessionId,
+          watcherId: id,
+          pattern: String(w.pattern),
+          matchedLine: line,
+          stream: "stdout",
+          context: [line]
+        });
+        entry.lastAttentionAt = Date.now();
+      }
+    }
+  }
+  finalize(entry, exitCode) {
+    if (!entry.running)
+      return;
+    entry.running = false;
+    entry.exitCode = exitCode;
+    if (entry.pollTimer)
+      clearInterval(entry.pollTimer);
+    entry.watchers.clear();
+    this.emit({
+      type: "exit",
+      sessionId: entry.sessionId,
+      ownerSessionId: entry.ownerSessionId,
+      exitCode,
+      lastLines: []
+    });
+    this.log.info(`[RemoteSession ${entry.sessionId}] exited code=${exitCode}`);
+  }
+  emit(ev) {
+    try {
+      this.onEvent(ev);
+    } catch (err) {
+      this.log.warn(`remote session event sink threw: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+}
+
+// src/ssh-pty-driver.ts
+var ANSI_RE = /\x1b\[[0-9;?]*[a-zA-Z]|\x1b\][^\x07]*\x07|\x1b[=>]|\r(?!\n)/g;
+var stripAnsi = (s) => s.replace(ANSI_RE, "");
+
+class PtyLink {
+  proc;
+  fallbackNonce = crypto4.randomBytes(16).toString("hex");
+  fallbackSteps = new Set;
+  assembler = new LineAssembler;
+  lineBuffer = [];
+  ready = false;
+  readyWaiter;
+  readyRejecter;
+  rawArrived = false;
+  firstOutWaiter;
+  chain = Promise.resolve();
+  handshakeTail = [];
+  handshakeUser;
+  handshakeWhat = "";
+  pendingExitFailure;
+  onUnexpectedExit;
+  onLayerFallback;
+  fallbackSeen;
+  registerFallbackStep() {
+    const step = String(this.fallbackSteps.size);
+    this.fallbackSteps.add(step);
+    return `; echo __FILAXIS_FB_${this.fallbackNonce}_${step}_$?_$RANDOM`;
+  }
+  attach(args) {
+    this.fallbackNonce = crypto4.randomBytes(16).toString("hex");
+    this.fallbackSteps.clear();
+    this.fallbackSeen = undefined;
+    this.proc = spawn3("ssh", args, { stdio: ["pipe", "pipe", "pipe"] });
+    this.proc.stdout.on("data", (d) => this.onData(d.toString("utf-8")));
+    this.proc.stderr.on("data", (d) => this.onData(d.toString("utf-8")));
+    this.proc.on("exit", (code) => {
+      if (!this.ready) {
+        const err = new Error(this.egressError(`ssh 进程建链期间退出（code=${code}）: ${this.handshakeWhat}`));
+        if (this.readyRejecter)
+          this.readyRejecter(err);
+        else
+          this.pendingExitFailure = err;
+      }
+      this.onUnexpectedExit?.();
+    });
+  }
+  send(s) {
+    this.proc?.stdin.write(s);
+  }
+  queue(fn) {
+    const run = this.chain.then(fn);
+    this.chain = run.catch(() => {
+      return;
+    });
+    return run;
+  }
+  egressError(reason) {
+    const raw = this.handshakeTail.join(`
+`).trim();
+    return raw ? `${reason}
+[ssh 原始输出·直交]
+${raw.slice(-1500)}` : `${reason}
+[ssh 原始输出·空（对端无任何回显）]`;
+  }
+  handshakeEvidence() {
+    const raw = this.handshakeTail.join(`
+`).trim();
+    return raw ? raw.slice(-1500) : "（无原始输出）";
+  }
+  async handshake(what) {
+    this.ready = false;
+    this.handshakeTail = [];
+    this.handshakeWhat = what;
+    this.fallbackSeen = undefined;
+    if (!this.pendingExitFailure)
+      await this.waitQuiet();
+    this.send(`stty -echo -ixon cols 500 rows 50; export PS1= PS2=; echo PTYRDY_$RANDOM$RANDOM_$(id -un 2>/dev/null)
+`);
+    try {
+      await new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new Error(this.egressError(`PTYRDY 握手超时（20s）: ${what}`))), 20000);
+        this.readyWaiter = () => {
+          clearTimeout(timer);
+          resolve();
+        };
+        this.readyRejecter = (e) => {
+          clearTimeout(timer);
+          reject(e);
+        };
+        if (this.pendingExitFailure) {
+          const e = this.pendingExitFailure;
+          this.pendingExitFailure = undefined;
+          this.readyRejecter(e);
+        }
+      });
+    } finally {
+      this.readyWaiter = undefined;
+      this.readyRejecter = undefined;
+    }
+    this.lineBuffer = [];
+    this.ready = true;
+  }
+  async execMarker(command, timeoutMs, abortSignal) {
+    if (!this.ready)
+      throw new Error("PTY 未就绪（层切换中）");
+    const marker = `__FX_M_${crypto4.randomBytes(4).toString("hex")}`;
+    const hasRedirect = /(\d>|>>|2>&1|>&)/.test(command);
+    const cmdLine = hasRedirect ? command : `{ ${command}; } 2>&1`;
+    const wrapped = `trap 'echo "${marker}_130_$(id -un)"' INT; ${cmdLine}; echo "${marker}_$?_$(id -un)"`;
+    const callerP = new Promise((resolve, reject) => {
+      this.queue(() => this.markerCycle(marker, wrapped, command, timeoutMs, abortSignal, { resolve, reject })).catch(() => {
+        return;
+      });
+    });
+    return callerP;
+  }
+  markerCycle(marker, wrapped, command, timeoutMs, abortSignal, caller) {
+    return new Promise((cycleDone) => {
+      let notified = false;
+      let drained = false;
+      this.lineBuffer = [];
+      const markerRe = new RegExp(`${marker}_(\\d+)(?:_(\\S+))?`);
+      const notify = (fn) => {
+        if (!notified) {
+          notified = true;
+          fn();
+        }
+      };
+      const cleanupAbort = () => abortSignal?.removeEventListener("abort", onAbort);
+      const enterDraining = () => {
+        if (drained)
+          return;
+        drained = true;
+        deadline = setTimeout(() => {
+          clearInterval(poll);
+          cleanupAbort();
+          this.kill();
+          cycleDone();
+        }, 5000);
+      };
+      let deadline = null;
+      const onAbort = () => {
+        if (notified)
+          return;
+        this.send("\x03");
+        notify(() => {
+          const e = new DOMException(`SshPty exec aborted by AbortSignal（已发 ^C，远端终态未核实——outcome=unknown）`, "AbortError");
+          e.outcome = "unknown";
+          caller.reject(e);
+        });
+        enterDraining();
+      };
+      abortSignal?.addEventListener("abort", onAbort, { once: true });
+      const timer = setTimeout(() => {
+        if (notified)
+          return;
+        this.send("\x03");
+        notify(() => {
+          const e = new Error(`SshPty exec 超时（${timeoutMs}ms，已发 ^C，远端终态未核实——outcome=unknown）: ${command.slice(0, 60)}`);
+          e.outcome = "unknown";
+          caller.reject(e);
+        });
+        enterDraining();
+      }, timeoutMs);
+      const poll = setInterval(() => {
+        const buf = this.lineBuffer;
+        for (let i = 0;i < buf.length; i++) {
+          const m = buf[i].match(markerRe);
+          if (m) {
+            const prefix = m.index ? buf[i].slice(0, m.index) : "";
+            this.lineBuffer = buf.slice(i + 1);
+            clearInterval(poll);
+            clearTimeout(timer);
+            if (deadline)
+              clearTimeout(deadline);
+            cleanupAbort();
+            if (!notified) {
+              const out = [...buf.slice(0, i), ...prefix ? [prefix] : []].join(`
+`);
+              notify(() => caller.resolve({
+                stdout: out,
+                stderr: "",
+                exitCode: parseInt(m[1], 10),
+                effectiveUser: m[2]
+              }));
+            }
+            cycleDone();
+            return;
+          }
+        }
+      }, 25);
+      this.send(`${wrapped}
+`);
+    });
+  }
+  kill() {
+    this.proc?.kill();
+    this.proc = undefined;
+    this.ready = false;
+  }
+  async waitQuiet() {
+    const firstOut = new Promise((resolve) => {
+      if (this.rawArrived)
+        resolve();
+      else
+        this.firstOutWaiter = resolve;
+    });
+    await Promise.race([firstOut, new Promise((r) => setTimeout(r, 8000))]);
+    await new Promise((r) => setTimeout(r, 600));
+  }
+  onData(text) {
+    if (this.firstOutWaiter) {
+      this.firstOutWaiter();
+      this.firstOutWaiter = undefined;
+    }
+    this.rawArrived = true;
+    for (const line of this.assembler.feed(stripAnsi(text))) {
+      const fb = [...line.matchAll(/__FILAXIS_FB_([a-f0-9]{32})_(\d+)_(\d+)_(\d+)(?!\w)/g)].find((m) => m[1] === this.fallbackNonce && this.fallbackSteps.has(m[2]));
+      if (fb) {
+        this.fallbackSeen = line.trim().slice(0, 200);
+        if (this.ready)
+          this.onLayerFallback?.(this.fallbackSeen);
+      }
+      if (!this.ready) {
+        const m = line.match(/PTYRDY_(\d+)(?:_([A-Za-z0-9._-]+))?/);
+        if (m) {
+          if (m[2])
+            this.handshakeUser = m[2];
+          this.readyWaiter?.();
+          this.readyWaiter = undefined;
+          continue;
+        }
+        if (line.trim()) {
+          this.handshakeTail.push(line.length > 200 ? line.slice(0, 200) + "…" : line);
+          if (this.handshakeTail.length > 30)
+            this.handshakeTail.shift();
+        }
+        if (SSH_INPUT_WAIT_RE.test(line)) {
+          this.readyRejecter?.(new Error(this.egressError(`建链卡在等待输入（交互提示）: ${this.handshakeWhat}`)));
+        }
+        continue;
+      }
+      this.lineBuffer.push(line);
+    }
+  }
+}
+var LAYER_IDLE_THRESHOLD_MS = 1e4;
+function resolveLayerState(d, now = Date.now()) {
+  if (!d.alive)
+    return "dead";
+  if (d.shellGone)
+    return "degraded";
+  if (d.reconnecting)
+    return "connecting";
+  if (d.execInFlight)
+    return "active";
+  if (d.lastActivityAt && now - d.lastActivityAt >= LAYER_IDLE_THRESHOLD_MS)
+    return "idle";
+  return d.lastActivityAt ? "active" : "connecting";
+}
+
+class SshPtyDriver {
+  descriptor;
+  fs;
+  sessions;
+  link = new PtyLink;
+  alive = true;
+  effectiveUser;
+  layerShellGone;
+  layerState = "connecting";
+  lastActivityAt = 0;
+  execInFlight = false;
+  reconnecting = false;
+  reconnectAttempts = 0;
+  log;
+  static MAX_RECONNECT = 3;
+  static RECONNECT_DELAYS_MS = [2000, 5000, 1e4];
+  constructor(descriptor, opts = {}) {
+    this.descriptor = descriptor;
+    this.log = opts.logger ?? noopLogger;
+    const self = this;
+    const fsExec = async (cmd) => self.execChannel(cmd, undefined);
+    const statOf = async (p) => {
+      const r = await fsExec(`stat -c '%s %Y' ${q2(p)} 2>/dev/null || stat -f '%z %m' ${q2(p)} 2>/dev/null || true`);
+      const m = r.stdout.trim().match(/^(\d+)\s+(\d+)$/);
+      return m ? { size: parseInt(m[1], 10), mtimeMs: parseInt(m[2], 10) * 1000 } : null;
+    };
+    this.fs = {
+      async readFile(p) {
+        return (await fsExec(`base64 ${q2(p)} | base64 -d 2>/dev/null`)).stdout;
+      },
+      async writeFile(p, content) {
+        const b64 = Buffer.from(content, "utf-8").toString("base64");
+        await fsExec(`printf %s ${q2(b64)} | base64 -d > ${q2(p)}`);
+      },
+      async exists(p) {
+        const r = await fsExec(`test -e ${q2(p)} && echo Y || echo N`);
+        return r.stdout.trim() === "Y";
+      },
+      stat: statOf,
+      async readdir(p) {
+        const r = await fsExec(`ls -1A ${q2(p)} 2>/dev/null || true`);
+        const names = r.stdout.split(`
+`).filter(Boolean);
+        return Promise.all(names.map(async (name) => {
+          const full = `${p.replace(/\/$/, "")}/${name}`;
+          const d = await fsExec(`test -d ${q2(full)} && echo Y || echo N`);
+          const st = await statOf(full);
+          return { name, isDirectory: d.stdout.trim() === "Y", size: st?.size, mtime: st?.mtimeMs };
+        }));
+      },
+      async rm(p, options) {
+        await fsExec(`rm ${options?.recursive ? "-r " : ""}${options?.force ? "-f " : ""}${q2(p)}`);
+      },
+      async mkdir(p, options) {
+        await fsExec(`mkdir ${options?.recursive ? "-p " : ""}${q2(p)}`);
+      }
+    };
+    this.sessions = new RemoteSessionManager({ exec: (cmd) => this.exec(cmd), logger: this.log });
+    this.bindLink();
+  }
+  currentState() {
+    return resolveLayerState({
+      alive: this.alive,
+      reconnecting: this.reconnecting,
+      execInFlight: this.execInFlight,
+      lastActivityAt: this.lastActivityAt,
+      shellGone: this.layerShellGone
+    });
+  }
+  async init() {
+    const target = this.descriptor.target ?? "";
+    if (!target)
+      throw new Error("SshPtyDriver 需要 descriptor.target（user@host 或 ssh config 别名）");
+    const hops = Array.isArray(this.descriptor.config?.sshHops) ? this.descriptor.config.sshHops : [];
+    const enterSteps = enterStepsOf(this.descriptor.config);
+    const connParams = this.descriptor.config?.connParams;
+    const rootHop = connParams ? { host: target, conn: connParams } : target;
+    this.layerShellGone = undefined;
+    this.link.onLayerFallback = (evidence) => {
+      this.layerShellGone = evidence;
+      this.layerState = "degraded";
+      this.log.warn(`[SshPty] 内层 shell 已退出，层退化：${evidence}——连接仍在但已非本层环境`);
+    };
+    this.link.attach(rootSshSpawnArgs(sshArgsFor(rootHop), connParams));
+    await this.link.handshake(`ssh ${hopLabel(rootHop)}`);
+    for (const hop of hops) {
+      await Promise.resolve().then(() => init_ssh_helpers());
+      this.link.send(`${hopSshCommand(hop)}${this.link.registerFallbackStep()}
+`);
+      try {
+        await this.link.handshake(`ssh ${hopLabel(hop)}`);
+      } catch (err) {
+        this.link.kill();
+        throw err;
+      }
+      this.assertNotFallenBack(`ssh ${hopLabel(hop)}`);
+    }
+    for (const step of enterSteps) {
+      this.link.send(`${step.cmd}${this.link.registerFallbackStep()}
+`);
+      try {
+        await this.link.handshake(`enter: ${step.cmd.slice(0, 40)}`);
+      } catch (err) {
+        this.link.kill();
+        throw err;
+      }
+      this.assertNotFallenBack(`enter: ${step.cmd.slice(0, 40)}`);
+    }
+    if (this.descriptor.cwd) {
+      await this.execChannel(`cd ${JSON.stringify(this.descriptor.cwd)} 2>/dev/null || true`, undefined);
+    }
+    if (this.link.handshakeUser)
+      this.effectiveUser = this.link.handshakeUser;
+    this.layerState = "active";
+    this.lastActivityAt = Date.now();
+  }
+  assertNotFallenBack(what) {
+    if (this.link.fallbackSeen) {
+      throw new Error(`层进入命令未驻留（${what}）——命令执行后立即退出，目标可能不存在或命令有误
+[哨兵证据] ${this.link.fallbackSeen}
+[原始输出·直交]
+${this.link.handshakeEvidence()}`);
+    }
+  }
+  scheduleReconnect() {
+    if (this.reconnecting || !this.alive)
+      return;
+    this.reconnecting = true;
+    const attempt = () => {
+      if (!this.alive) {
+        this.reconnecting = false;
+        return;
+      }
+      if (this.reconnectAttempts >= SshPtyDriver.MAX_RECONNECT) {
+        this.reconnecting = false;
+        this.layerState = "dead";
+        return;
+      }
+      this.reconnectAttempts++;
+      const delay = SshPtyDriver.RECONNECT_DELAYS_MS[Math.min(this.reconnectAttempts - 1, SshPtyDriver.RECONNECT_DELAYS_MS.length - 1)];
+      const timer = setTimeout(() => {
+        (async () => {
+          try {
+            this.link = new PtyLink;
+            this.bindLink();
+            await this.init();
+            this.reconnecting = false;
+            this.reconnectAttempts = 0;
+            this.lastActivityAt = Date.now();
+            this.layerState = "active";
+          } catch {
+            attempt();
+          }
+        })();
+      }, delay);
+      timer.unref?.();
+    };
+    attempt();
+  }
+  bindLink() {
+    this.link.onUnexpectedExit = () => {
+      if (this.alive && !this.reconnecting) {
+        this.layerState = "connecting";
+        this.scheduleReconnect();
+      }
+    };
+  }
+  async pushChild(hop) {
+    const myHops = Array.isArray(this.descriptor.config?.sshHops) ? this.descriptor.config.sshHops : [];
+    const child = new SshPtyDriver({
+      driver: "ssh",
+      target: this.descriptor.target,
+      config: { ...this.descriptor.config, sshHops: [...myHops, hop], enterPipeline: undefined, enterCmd: undefined, enterLabel: undefined }
+    }, { logger: this.log });
+    await child.init();
+    return child;
+  }
+  async pushInto(enterCmd, enterLabel) {
+    const myHops = Array.isArray(this.descriptor.config?.sshHops) ? this.descriptor.config.sshHops : [];
+    const enterPipeline = [...enterStepsOf(this.descriptor.config), { cmd: enterCmd, label: enterLabel }];
+    const child = new SshPtyDriver({
+      driver: "ssh",
+      target: this.descriptor.target,
+      config: { ...this.descriptor.config, sshHops: myHops, enterPipeline, enterCmd: undefined, enterLabel: undefined }
+    }, { logger: this.log });
+    await child.init();
+    return child;
+  }
+  async exit() {
+    if (!this.alive)
+      return;
+    this.alive = false;
+    this.reconnecting = false;
+    this.layerState = "dead";
+    this.link.kill();
+  }
+  async destroy() {
+    await this.exit();
+  }
+  async getCwd() {
+    return (await this.exec("pwd")).stdout.trim();
+  }
+  async getEnv(key) {
+    return (await this.exec(`printf %s "\\$${key}"`)).stdout;
+  }
+  async exec(command, options) {
+    if (!this.alive)
+      throw new Error("层已退出");
+    if (this.layerShellGone)
+      throw new Error(`层已退化：内层 shell 已退出（${this.layerShellGone.slice(0, 60)}）——连接仍在但已非本层环境`);
+    if (this.reconnecting)
+      throw new Error("连接意外断开，自动重连中——请稍后重试");
+    if (options?.channel === "pty") {
+      this.execInFlight = true;
+      try {
+        const r = await this.link.execMarker(command, options?.timeoutMs ?? 120000, options?.signal);
+        if (r.effectiveUser)
+          this.effectiveUser = r.effectiveUser;
+        return r;
+      } finally {
+        this.execInFlight = false;
+        this.lastActivityAt = Date.now();
+      }
+    }
+    return this.execChannel(command, options);
+  }
+  async execChannel(command, options) {
+    const hops = Array.isArray(this.descriptor.config?.sshHops) ? this.descriptor.config.sshHops : [];
+    const enterSteps = enterStepsOf(this.descriptor.config);
+    const connParams = this.descriptor.config?.connParams;
+    const rootHop = connParams ? { host: this.descriptor.target ?? "", conn: connParams } : this.descriptor.target ?? "";
+    const nonce = crypto4.randomBytes(6).toString("hex");
+    const marker = `__FILAXIS_META_${nonce}`;
+    const wrapped = `( ${command} ); __filaxis_ec=$?; printf '\\n${marker}:%d:%s\\n' "$__filaxis_ec" "$(id -un 2>/dev/null)"; exit $__filaxis_ec`;
+    const render = renderExecChannel(enterSteps, command, {
+      cwd: options?.cwd ?? this.descriptor.cwd,
+      marker,
+      nonceWrapped: wrapped
+    });
+    if (render.kind === "unreachable") {
+      throw new Error(`不可直达层（exec 通道）：${render.reason}［${render.step}］——该层含 PTY 内交互二次跳转，请用 channel:"pty"（stderr 将混流，终端语义）`);
+    }
+    if (hops.length > 0) {
+      throw new Error(`不可直达层（exec 通道）：多跳 PTY 登录链（${hops.map(hopLabel).join(" → ")}）无法以单条非 PTY 进程复现——请用 channel:"pty"，或将途经机收敛为 -J jump（ProxyJump）`);
+    }
+    return new Promise((resolve, reject) => {
+      const argv = [...autonomousSshOpts(connParams), ...sshArgsFor(rootHop), "--", ...render.remoteArgs];
+      const p = spawn3("ssh", argv, {
+        env: { ...process.env, ...options?.env },
+        cwd: options?.cwd,
+        stdio: ["pipe", "pipe", "pipe"]
+      });
+      let stdout = "";
+      let stderr = "";
+      let settled = false;
+      p.stdout.on("data", (d) => {
+        stdout += d;
+      });
+      p.stderr.on("data", (d) => {
+        stderr += d;
+      });
+      p.stdin.write(render.stdinCmd);
+      p.stdin.end();
+      const onAbort = () => {
+        p.kill("SIGTERM");
+        const e = new DOMException("exec aborted by AbortSignal（本地 ssh 已终止，远端进程状态未核实——outcome=unknown）", "AbortError");
+        e.outcome = "unknown";
+        e.reason = "aborted";
+        finish(() => reject(e));
+      };
+      const timer = options?.timeoutMs ? setTimeout(() => {
+        p.kill("SIGTERM");
+        const e = new Error(`exec 通道超时（${options.timeoutMs}ms，远端进程状态未核实）: ${command.slice(0, 60)}`);
+        e.outcome = "unknown";
+        finish(() => reject(e));
+      }, options.timeoutMs) : null;
+      const cleanupAbort = () => options?.signal?.removeEventListener("abort", onAbort);
+      options?.signal?.addEventListener("abort", onAbort, { once: true });
+      const finish = (fn) => {
+        if (!settled) {
+          settled = true;
+          if (timer)
+            clearTimeout(timer);
+          cleanupAbort();
+          fn();
+        }
+      };
+      if (options?.signal?.aborted)
+        onAbort();
+      p.on("close", (code) => {
+        let out = stdout;
+        let effectiveUser;
+        let sentinelCode;
+        const mIdx = out.lastIndexOf(`
+${marker}:`);
+        if (mIdx !== -1) {
+          const metaLine = out.slice(mIdx + 1).split(`
+`, 1)[0] ?? "";
+          const m = metaLine.match(new RegExp(`^${marker}:(-?\\d+):(.*)$`));
+          if (m) {
+            effectiveUser = m[2] === "" ? undefined : m[2];
+            sentinelCode = parseInt(m[1], 10);
+            out = out.slice(0, mIdx);
+          }
+        }
+        if (effectiveUser)
+          this.effectiveUser = effectiveUser;
+        if (sentinelCode === undefined) {
+          finish(() => {
+            const e = new Error(`命令未完成（无完成哨兵——通道中断/进程被信号终止，close code=${code}）。半截现场 stdout 尾 500 字符:
+${out.slice(-500)}
+stderr 尾 300:
+${stderr.slice(-300)}`);
+            e.outcome = "unknown";
+            reject(e);
+          });
+          return;
+        }
+        finish(() => resolve({ stdout: out, stderr, exitCode: sentinelCode, effectiveUser }));
+      });
+      p.on("error", (err) => finish(() => reject(err)));
+    });
+  }
+  async execSession(command, opts) {
+    if (this.layerShellGone)
+      throw new Error("层已退化——后台任务会落在父环境，请重建层后再启动");
+    return this.sessions.start(command, opts);
+  }
+  async tailSession(sessionId, lines) {
+    return this.sessions.tail(sessionId, lines);
+  }
+  async readSessionLog(sessionId, opts) {
+    return this.sessions.readLog(sessionId, opts);
+  }
+  watchSession(sessionId, opts) {
+    return this.sessions.watch(sessionId, opts);
+  }
+  async stopSession(sessionId) {
+    return this.sessions.stop(sessionId);
+  }
+  listSessions() {
+    return this.sessions.list();
+  }
+}
+function q2(s) {
+  return `'${s.replace(/'/g, "'\\''")}'`;
+}
+
+// src/terminal-manager.ts
+import path3 from "node:path";
+import { tmpdir as tmpdir3 } from "node:os";
+
+// src/terminal/session-registry.ts
+import fs3 from "node:fs/promises";
+
+// src/terminal/tmux-invoker.ts
+import { spawn as spawn4 } from "node:child_process";
+
+// src/terminal/types.ts
+class TmuxError extends Error {
+  args;
+  exitCode;
+  stderr;
+  constructor(message, args, exitCode, stderr) {
+    super(message);
+    this.args = args;
+    this.exitCode = exitCode;
+    this.stderr = stderr;
+    this.name = "TmuxError";
+  }
+}
+var DEFAULT_TERMINAL_CONFIG = {
+  env_hardening_prefix: "export GIT_TERMINAL_PROMPT=0 SSH_ASKPASS=/bin/false PAGER=cat",
+  spawn_max_wait_ms_local: 5000,
+  spawn_max_wait_ms_remote: 20000,
+  spawn_poll_ms: 200,
+  command_timeout_ms: 600000,
+  no_output_timeout_ms: 120000,
+  poll_interval_ms: 500,
+  capture_scrollback: 500,
+  buffer_pending_chars: 1e5,
+  buffer_aggregated_chars: 500000,
+  buffer_tail_chars: 4000,
+  prompt_patterns: [
+    "(?:password|passphrase|密码|口令)[^\\n]*[:：]\\s*$",
+    "\\(yes\\/no[^)]*\\)\\s*\\??\\s*$",
+    "press any key to continue[^\\n]*$"
+  ]
+};
+function compilePromptPatterns(patterns) {
+  const joined = patterns.length === 1 ? patterns[0] : `(?:${patterns.join("|")})`;
+  return new RegExp(joined, "mi");
+}
+
+// src/terminal/tmux-invoker.ts
+class TmuxInvoker {
+  static invoke(args) {
+    return new Promise((resolve, reject) => {
+      let stdout = "";
+      let stderr = "";
+      let settled = false;
+      const p = spawn4("tmux", args, { stdio: ["ignore", "pipe", "pipe"] });
+      p.stdout.on("data", (d) => {
+        stdout += d;
+      });
+      p.stderr.on("data", (d) => {
+        stderr += d;
+      });
+      const settle = (exitCode) => {
+        if (settled)
+          return;
+        settled = true;
+        const code = exitCode ?? 0;
+        if (code === 0) {
+          resolve({ stdout, stderr, exitCode: 0 });
+        } else {
+          reject(new TmuxError(`tmux ${args.join(" ")} failed with exit code ${code}` + (stderr ? `: ${stderr.trim()}` : ""), args, code, stderr));
+        }
+      };
+      p.once("exit", (code) => settle(code));
+      p.once("close", (code) => settle(code));
+      p.once("error", (err) => {
+        if (settled)
+          return;
+        settled = true;
+        reject(err);
+      });
+    });
+  }
+  static async tryInvoke(args) {
+    try {
+      return await this.invoke(args);
+    } catch (e) {
+      if (e instanceof TmuxError) {
+        return { stdout: "", stderr: e.stderr, exitCode: e.exitCode };
+      }
+      throw e;
+    }
+  }
+  static async isAvailable() {
+    try {
+      await this.tryInvoke(["list-sessions"]);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}
+
+// src/terminal/session-registry.ts
+class SessionRegistry {
+  dirResolver;
+  log;
+  reconciledDirs = new Set;
+  constructor(dirResolver, log = noopLogger) {
+    this.dirResolver = dirResolver;
+    this.log = log;
+  }
+  async ensureDir() {
+    await fs3.mkdir(this.dirResolver(), { recursive: true });
+  }
+  async init() {
+    await this.ensureDir();
+    const dir = this.dirResolver();
+    if (this.reconciledDirs.has(dir))
+      return;
+    this.reconciledDirs.add(dir);
+    await this.reconcileOnStartup();
+  }
+  async save(profile) {
+    await fs3.writeFile(`${this.dirResolver()}/${profile.id}.json`, JSON.stringify(profile, null, 2));
+  }
+  async load(id) {
+    try {
+      const raw = await fs3.readFile(`${this.dirResolver()}/${id}.json`, "utf-8");
+      return JSON.parse(raw);
+    } catch {
+      return null;
+    }
+  }
+  async remove(id) {
+    try {
+      await fs3.unlink(`${this.dirResolver()}/${id}.json`);
+    } catch {}
+  }
+  async reconcileOnStartup() {
+    const dir = this.dirResolver();
+    let files;
+    try {
+      files = await fs3.readdir(dir);
+    } catch {
+      return { scanned: 0, kept: 0, removed: 0 };
+    }
+    const profiles = files.filter((f) => f.endsWith(".json"));
+    let kept = 0;
+    let removed = 0;
+    await Promise.all(profiles.map(async (file) => {
+      const id = file.slice(0, -5);
+      const profile = await this.load(id);
+      if (!profile || profile.id !== id) {
+        await this.remove(id);
+        removed++;
+        return;
+      }
+      try {
+        const r = await TmuxInvoker.tryInvoke(["has-session", "-t", id]);
+        if (r.exitCode === 0) {
+          kept++;
+          this.log.info(`[reconcile] 会话 [${id}] 仍存活，保留（已重连）`);
+        } else {
+          await this.remove(id);
+          removed++;
+          this.log.warn(`[reconcile] 僵尸会话 [${id}] 已清理`);
+        }
+      } catch {
+        kept++;
+      }
+    }));
+    return { scanned: profiles.length, kept, removed };
+  }
+}
+
+// src/terminal/session-launcher.ts
+var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+class SessionLauncher {
+  registry;
+  cfg;
+  log;
+  constructor(registry, opts = {}) {
+    this.registry = registry;
+    this.cfg = { ...DEFAULT_TERMINAL_CONFIG, ...opts.config };
+    this.log = opts.logger ?? noopLogger;
+  }
+  async launch(driver, target, config, customId) {
+    const id = customId || "term_" + Date.now().toString(36) + "_" + Math.random().toString(36).slice(2, 6);
+    const launchCmd = this.resolveLaunchCmd(driver, target, config);
+    try {
+      const alive = await TmuxInvoker.tryInvoke(["has-session", "-t", id]);
+      if (alive.exitCode === 0) {
+        this.log.info(`会话 [${id}] 已存在于 tmux，复用`);
+        const profile = { id, driver, target: target ?? "", config, createdAt: Date.now() };
+        await this.registry.save(profile);
+        return id;
+      }
+    } catch {}
+    const finalCmd = this.cfg.env_hardening_prefix ? `${this.cfg.env_hardening_prefix}; ${launchCmd}` : launchCmd;
+    this.log.info(`启动持久会话 [${id}] (driver: ${driver})`);
+    await TmuxInvoker.invoke(["new-session", "-d", "-x", "220", "-s", id, finalCmd]);
+    const ok = await this.waitForAlive(id, driver);
+    if (!ok) {
+      await this.registry.remove(id);
+      throw new Error(this.diedHint(id, driver, target));
+    }
+    const profile = { id, driver, target: target ?? "", config, createdAt: Date.now() };
+    await this.registry.save(profile);
+    return id;
+  }
+  resolveLaunchCmd(driver, target, config) {
+    const c = config ?? {};
+    if (typeof c.launchCmd === "string" && c.launchCmd)
+      return c.launchCmd;
+    if (driver === "ssh" && target) {
+      const sshOpts = typeof c.sshOptions === "string" ? c.sshOptions : "";
+      return `ssh ${sshOpts} -t ${target}`;
+    }
+    if (driver === "docker" && target) {
+      const runtime = typeof c.runtime === "string" ? c.runtime : "docker";
+      const shell = typeof c.shell === "string" ? c.shell : "sh";
+      return `${runtime} exec -i ${target} ${shell} -i`;
+    }
+    if (driver === "k8s" && target) {
+      const runtime = typeof c.runtime === "string" ? c.runtime : "kubectl";
+      const ns = typeof c.namespace === "string" ? `-n ${c.namespace}` : "";
+      const shell = typeof c.shell === "string" ? c.shell : "sh";
+      return `${runtime} exec -i ${ns} ${target} -- ${shell} -i`;
+    }
+    if (driver === "teleport" && target) {
+      const cluster = typeof c.cluster === "string" ? `--cluster=${c.cluster} ` : "";
+      const login = typeof c.login === "string" ? `${c.login}@` : "";
+      return `tsh ssh ${cluster}${login}${target}`;
+    }
+    if (driver === "local")
+      return "bash";
+    throw new Error(`Unknown driver '${driver}' and no config.launchCmd provided. ` + `Supply config.launchCmd with the full command to enter the environment ` + `(e.g. "nix develop", "conda run -n myenv bash", "distrobox enter my-box").`);
+  }
+  async waitForAlive(id, driver) {
+    const isLocal = driver === "local";
+    const maxWaitMs = isLocal ? this.cfg.spawn_max_wait_ms_local : this.cfg.spawn_max_wait_ms_remote;
+    const maxDeadStreak = isLocal ? 1 : 3;
+    const deadline = Date.now() + maxWaitMs;
+    let deadStreak = 0;
+    while (Date.now() < deadline) {
+      await sleep(this.cfg.spawn_poll_ms);
+      let alive;
+      try {
+        const r = await TmuxInvoker.tryInvoke(["has-session", "-t", id]);
+        alive = r.exitCode === 0;
+      } catch {
+        return false;
+      }
+      if (!alive) {
+        deadStreak++;
+        if (deadStreak >= maxDeadStreak)
+          return false;
+        continue;
+      }
+      deadStreak = 0;
+      const paneOut = await TmuxInvoker.tryInvoke(["capture-pane", "-t", id, "-p"]);
+      if (paneOut.stdout !== "")
+        return true;
+    }
+    try {
+      const r = await TmuxInvoker.tryInvoke(["has-session", "-t", id]);
+      return r.exitCode === 0;
+    } catch {
+      return false;
+    }
+  }
+  diedHint(id, driver, target) {
+    const hint = driver === "docker" ? `Make sure the container '${target}' is running ('docker ps'). Use the container name/ID, not the image name.` : driver === "ssh" ? `Check that '${target}' is reachable and SSH credentials are valid.` : driver === "teleport" ? `Check 'tsh status' — a valid Teleport login is required.` : "The shell exited immediately after launch.";
+    return `Session '${id}' (driver: ${driver}) died immediately after spawn. ${hint}`;
+  }
+}
+
+// src/terminal/output-buffer.ts
+class OutputBuffer {
+  pendingStdout = [];
+  pendingStderr = [];
+  aggregated = "";
+  tail = "";
+  totalOutputChars = 0;
+  truncated = false;
+  baseOffset = 0;
+  pendingCap;
+  aggregatedCap;
+  tailCap;
+  constructor(caps) {
+    this.pendingCap = caps.pendingChars;
+    this.aggregatedCap = caps.aggregatedChars;
+    this.tailCap = caps.tailChars;
+  }
+  append(chunk, stream = "stdout") {
+    if (chunk.length === 0)
+      return;
+    this.totalOutputChars += chunk.length;
+    const buf = stream === "stderr" ? this.pendingStderr : this.pendingStdout;
+    buf.push(chunk);
+    this.trimPending(buf);
+    this.aggregated += chunk;
+    if (this.aggregated.length > this.aggregatedCap) {
+      const dropped = this.aggregated.length - this.aggregatedCap;
+      this.aggregated = this.aggregated.slice(-this.aggregatedCap);
+      this.baseOffset += dropped;
+      this.truncated = true;
+    }
+    this.tail = this.aggregated.slice(-this.tailCap);
+  }
+  drainPending() {
+    const out = this.pendingStdout.join("");
+    const err = this.pendingStderr.join("");
+    this.pendingStdout = [];
+    this.pendingStderr = [];
+    return out + (err ? `
+[stderr]
+${err}` : "");
+  }
+  readTail() {
+    return this.tail;
+  }
+  readLog(offset = 0, limit) {
+    if (offset < this.baseOffset) {
+      const lostChars = this.baseOffset - offset;
+      const text = limit === undefined ? this.aggregated : this.aggregated.slice(0, limit);
+      return { ok: false, text, nextOffset: this.baseOffset + text.length, validFrom: this.baseOffset, lostChars };
+    }
+    const start = offset - this.baseOffset;
+    const text = limit === undefined ? this.aggregated.slice(start) : this.aggregated.slice(start, start + limit);
+    return { ok: true, text, nextOffset: offset + text.length };
+  }
+  readLogText(offset = 0, limit) {
+    const r = this.readLog(offset, limit);
+    if (!r.ok) {
+      return `[游标已过期] 此前约 ${r.lostChars} 字符已被裁掉，以下从绝对偏移 ${r.validFrom} 继续
+` + r.text;
+    }
+    return r.text;
+  }
+  get stats() {
+    return { total: this.totalOutputChars, truncated: this.truncated };
+  }
+  hasPending() {
+    return this.pendingStdout.length > 0 || this.pendingStderr.length > 0;
+  }
+  reset() {
+    this.pendingStdout = [];
+    this.pendingStderr = [];
+    this.aggregated = "";
+    this.tail = "";
+    this.totalOutputChars = 0;
+    this.baseOffset = 0;
+    this.truncated = false;
+  }
+  trimPending(buf) {
+    let len = buf.reduce((s, c) => s + c.length, 0);
+    while (len > this.pendingCap && buf.length > 1) {
+      const dropped = buf.shift();
+      len -= dropped.length;
+      this.truncated = true;
+    }
+  }
+}
+
+// src/terminal/command-executer.ts
+class CommandExecError extends Error {
+  partialOutput;
+  outcome;
+  constructor(message, partialOutput = "", outcome) {
+    super(message);
+    this.name = "CommandExecError";
+    this.partialOutput = partialOutput;
+    this.outcome = outcome;
+  }
+}
+var SAFE_PREFIX = "shopt -u promptvars nullglob extglob nocaseglob 2>/dev/null;";
+var BINARY_SNIFF_BYTES = 4096;
+var BINARY_NULL_RATIO = 0.1;
+function isBinaryChunk(text) {
+  const sample = text.length > BINARY_SNIFF_BYTES ? text.slice(0, BINARY_SNIFF_BYTES) : text;
+  if (sample.length === 0)
+    return false;
+  let nulls = 0;
+  for (let i = 0;i < sample.length; i++) {
+    if (sample.charCodeAt(i) === 0)
+      nulls++;
+  }
+  return nulls / sample.length > BINARY_NULL_RATIO;
+}
+var sleep2 = (ms) => new Promise((r) => setTimeout(r, ms));
+
+class CommandExecuter {
+  constructor() {}
+  static cfg = { ...DEFAULT_TERMINAL_CONFIG };
+  static sttyOff = new Set;
+  static chains = new Map;
+  static deadSessions = new Set;
+  static log = noopLogger;
+  static configure(opts = {}) {
+    this.cfg = { ...DEFAULT_TERMINAL_CONFIG, ...opts.config };
+    this.log = opts.logger ?? noopLogger;
+  }
+  static async execute(id, command, opts = {}) {
+    if (this.deadSessions.has(id)) {
+      try {
+        const r = await TmuxInvoker.tryInvoke(["has-session", "-t", id]);
+        if (r.exitCode === 0) {
+          this.deadSessions.delete(id);
+          this.sttyOff.delete(id);
+        } else {
+          throw new CommandExecError(`tmux session '${id}' 已因超时终态不可确认被销毁——请重建层（同 id respawn 后自动恢复）再执行`);
+        }
+      } catch (e) {
+        if (e instanceof CommandExecError)
+          throw e;
+        throw new CommandExecError(`tmux session '${id}' 已销毁且探活失败——请重建层`);
+      }
+    }
+    const prev = this.chains.get(id) ?? Promise.resolve();
+    const run = prev.catch(() => {
+      return;
+    }).then(() => this.executeLocked(id, command, opts));
+    this.chains.set(id, run.catch(() => {
+      return;
+    }));
+    return run;
+  }
+  static async executeLocked(id, command, opts = {}) {
+    const cfg = this.cfg;
+    const timeoutMs = opts.timeoutMs ?? cfg.command_timeout_ms;
+    let alive;
+    try {
+      const r = await TmuxInvoker.tryInvoke(["has-session", "-t", id]);
+      alive = r.exitCode === 0;
+    } catch {
+      alive = false;
+    }
+    if (!alive) {
+      throw new CommandExecError(`tmux session '${id}' does not exist. Spawn a new session first.`);
+    }
+    await TmuxInvoker.invoke(["clear-history", "-t", id]);
+    if (!this.sttyOff.has(id)) {
+      await this.sendKeys(id, "stty -echo 2>/dev/null; export PS1= PS2=;");
+      await sleep2(400);
+      await TmuxInvoker.invoke(["clear-history", "-t", id]);
+      this.sttyOff.add(id);
+    }
+    try {
+      await TmuxInvoker.invoke(["send-keys", "-t", id, "-l", "clear"]);
+      await TmuxInvoker.invoke(["send-keys", "-t", id, "C-m"]);
+      await sleep2(200);
+    } catch {}
+    await TmuxInvoker.invoke(["clear-history", "-t", id]).catch(() => {
+      return;
+    });
+    const markerToken = Math.random().toString(36).slice(2, 10);
+    const markerPrefix = `---CMD_DONE_${markerToken}_`;
+    const markerEchoNeedle = `echo ${markerPrefix}`;
+    const safeCommand = `${SAFE_PREFIX} ${command}`;
+    await this.sendKeys(id, safeCommand);
+    await this.sendKeys(id, `echo ${markerPrefix}$?`);
+    const buffer = new OutputBuffer({
+      pendingChars: cfg.buffer_pending_chars,
+      aggregatedChars: cfg.buffer_aggregated_chars,
+      tailChars: cfg.buffer_tail_chars
+    });
+    const wallDeadline = Date.now() + timeoutMs;
+    let lastActivityAt = Date.now();
+    let lastPaneText = "";
+    let binaryDetected = false;
+    let binaryBytes = 0;
+    while (true) {
+      if (Date.now() >= wallDeadline || Date.now() - lastActivityAt >= cfg.no_output_timeout_ms) {
+        const reason = Date.now() >= wallDeadline ? `Timeout waiting for command to finish in terminal ${id}` : `Timeout waiting for command to finish in terminal ${id} (no output for ${cfg.no_output_timeout_ms}ms)`;
+        const partial = this.extractPartialOutput(buffer, markerPrefix, markerEchoNeedle, binaryDetected, binaryBytes);
+        try {
+          await TmuxInvoker.invoke(["send-keys", "-t", id, "C-c"]);
+        } catch {}
+        const drainToken = `__FX_DRAIN_${Math.random().toString(36).slice(2, 8)}`;
+        try {
+          await TmuxInvoker.invoke(["send-keys", "-t", id, "-l", `echo ${drainToken}`]);
+          await TmuxInvoker.invoke(["send-keys", "-t", id, "C-m"]);
+        } catch {}
+        const drained = await this.waitForDrain(id, markerPrefix, drainToken, 5000);
+        if (drained) {
+          try {
+            await TmuxInvoker.invoke(["clear-history", "-t", id]);
+          } catch {}
+          throw new CommandExecError(`${reason}（已发 ^C，远端 shell 已确认回提示符——outcome=unknown）`, partial, "unknown");
+        }
+        try {
+          await TmuxInvoker.invoke(["kill-session", "-t", id]);
+        } catch {}
+        this.deadSessions.add(id);
+        this.sttyOff.delete(id);
+        throw new CommandExecError(`${reason}（已发 ^C 但 5s 内未见可信终态——会话已销毁防残影串台；同 id respawn 后自动恢复）`, partial, "unknown");
+      }
+      const paneText = await this.capturePane(id, cfg.capture_scrollback);
+      if (paneText !== lastPaneText) {
+        lastActivityAt = Date.now();
+        if (paneText.length > 0) {
+          if (!binaryDetected && isBinaryChunk(paneText)) {
+            binaryDetected = true;
+            binaryBytes = paneText.length;
+            this.log.warn(`[${id}] 检测到二进制输出，切换字节计数模式`);
+          } else if (binaryDetected) {
+            binaryBytes = paneText.length;
+          } else {
+            const delta = this.computeDelta(lastPaneText, paneText);
+            if (delta.length > 0)
+              buffer.append(delta);
+            if (opts.onProgress && !paneText.includes(markerPrefix)) {
+              try {
+                opts.onProgress({ tail: buffer.readTail(), stats: buffer.stats });
+              } catch {}
+            }
+          }
+        }
+        lastPaneText = paneText;
+      }
+      if (paneText.includes(markerPrefix)) {
+        const exitCode = this.parseExitCode(paneText, markerPrefix);
+        if (exitCode !== null) {
+          if (binaryDetected) {
+            return { stdout: `[binary output: ${binaryBytes} bytes omitted]`, exitCode };
+          }
+          const stdout = this.stripMarkerNoise(buffer.readLogText(), markerPrefix, markerEchoNeedle);
+          return { stdout, exitCode };
+        }
+      }
+      if (opts.responder && !paneText.includes(markerPrefix)) {
+        const payload = this.detectPrompt(paneText, id);
+        if (payload) {
+          this.log.info(`[${id}] 检测到交互 Prompt：${payload.metadata.prompt}`);
+          const reply = await opts.responder.ask(payload);
+          if (reply) {
+            await this.sendKeys(id, reply);
+            await sleep2(800);
+            lastPaneText = "";
+            lastActivityAt = Date.now();
+          }
+          continue;
+        }
+      }
+      try {
+        const r = await TmuxInvoker.tryInvoke(["has-session", "-t", id]);
+        alive = r.exitCode === 0;
+      } catch {
+        alive = false;
+      }
+      if (!alive) {
+        throw new CommandExecError(`tmux session '${id}' died while waiting for command to complete.`, this.extractPartialOutput(buffer, markerPrefix, markerEchoNeedle, binaryDetected, binaryBytes));
+      }
+      lastActivityAt = Date.now();
+      await sleep2(cfg.poll_interval_ms);
+    }
+  }
+  static detectPrompt(paneText, terminalId) {
+    if (!paneText)
+      return null;
+    const re = compilePromptPatterns(this.cfg.prompt_patterns);
+    const m = paneText.match(re);
+    if (!m)
+      return null;
+    const prompt = m[0].trim();
+    return {
+      type: "CONFIRM",
+      title: "Shell Interaction Needed",
+      message: `The command is requesting input: "${prompt}"`,
+      metadata: { terminalId, prompt, platform: "terminal" }
+    };
+  }
+  static parseExitCode(paneText, markerPrefix) {
+    for (const line of paneText.split(`
+`)) {
+      if (!line.includes(markerPrefix))
+        continue;
+      if (line.includes(`echo ${markerPrefix}`))
+        continue;
+      const match = line.match(new RegExp(`${markerPrefix}(\\d+)`));
+      if (match)
+        return parseInt(match[1] ?? "0", 10);
+    }
+    return null;
+  }
+  static computeDelta(prev, curr) {
+    if (prev.length === 0)
+      return curr;
+    if (curr.startsWith(prev))
+      return curr.slice(prev.length);
+    const normPrev = prev.replace(/\r/g, "");
+    const normCurr = curr.replace(/\r/g, "");
+    if (normCurr.startsWith(normPrev))
+      return curr.slice(prev.length);
+    return curr;
+  }
+  static stripMarkerNoise(log, markerPrefix, markerEchoNeedle) {
+    const resultLines = [];
+    for (const line of log.split(`
+`)) {
+      if (line.includes(markerPrefix))
+        break;
+      if (line.includes(markerEchoNeedle))
+        continue;
+      if (/__FX_DRAIN_[0-9a-z]+/.test(line))
+        continue;
+      if (/stty -echo/.test(line))
+        continue;
+      if (/\$\s*$/.test(line) && /debian_chroot|@\S+[:~]/.test(line))
+        continue;
+      if (/^\$\s*$/.test(line))
+        continue;
+      resultLines.push(line);
+    }
+    while (resultLines.length > 0 && resultLines[resultLines.length - 1].trim() === "") {
+      resultLines.pop();
+    }
+    return resultLines.join(`
+`).trim();
+  }
+  static extractPartialOutput(buffer, markerPrefix, markerEchoNeedle, binaryDetected, binaryBytes) {
+    if (binaryDetected)
+      return `[binary output: ${binaryBytes} bytes omitted]`;
+    return this.stripMarkerNoise(buffer.readLogText(), markerPrefix, markerEchoNeedle);
+  }
+  static async sendKeys(id, text) {
+    await TmuxInvoker.invoke(["send-keys", "-t", id, "-l", text]);
+    await TmuxInvoker.invoke(["send-keys", "-t", id, "C-m"]);
+  }
+  static async waitForDrain(id, markerPrefix, drainToken, deadlineMs) {
+    const deadline = Date.now() + deadlineMs;
+    while (Date.now() < deadline) {
+      const pane = await this.capturePane(id, 80);
+      if (pane.includes(drainToken))
+        return true;
+      if (pane.includes(markerPrefix) && this.parseExitCode(pane, markerPrefix) !== null)
+        return true;
+      await sleep2(120);
+    }
+    return false;
+  }
+  static async capturePane(id, scrollback) {
+    try {
+      const r = await TmuxInvoker.invoke(["capture-pane", "-t", id, "-p", "-S", `-${scrollback}`]);
+      return r.stdout;
+    } catch {
+      return "";
+    }
+  }
+}
+
+// src/terminal-manager.ts
+class TerminalManager {
+  registry;
+  launcher;
+  terminalDir;
+  constructor(opts = {}) {
+    this.terminalDir = opts.terminalDir ?? path3.join(tmpdir3(), "filaxis-terminals");
+    const log = opts.logger ?? noopLogger;
+    this.registry = new SessionRegistry(() => this.terminalDir, log);
+    this.launcher = new SessionLauncher(this.registry, { config: opts.config, logger: log });
+    CommandExecuter.configure({ config: opts.config, logger: log });
+  }
+  async init() {
+    await this.registry.init();
+  }
+  async spawnSession(driver, target, config, customId) {
+    await this.init();
+    return this.launcher.launch(driver, target, config, customId);
+  }
+  async runCommand(id, command, timeoutMsOrOptions = 600000) {
+    const opts = typeof timeoutMsOrOptions === "number" ? { timeoutMs: timeoutMsOrOptions } : timeoutMsOrOptions;
+    return CommandExecuter.execute(id, command, opts);
+  }
+  async destroySession(id) {
+    try {
+      await TmuxInvoker.invoke(["kill-session", "-t", id]);
+    } catch {}
+    await this.registry.remove(id);
+  }
+  async getSession(id) {
+    return this.registry.load(id);
+  }
+}
+
+// src/tmux-driver.ts
+var q3 = (s) => `'${s.replace(/'/g, "'\\''")}'`;
+
+class TmuxSessionDriver {
+  descriptor;
+  fs;
+  terminal;
+  log;
+  constructor(descriptor, opts = {}) {
+    this.descriptor = descriptor;
+    this.terminal = opts.terminalManager ?? new TerminalManager;
+    this.log = opts.logger ?? noopLogger;
+    const self = this;
+    this.fs = {
+      async readFile(p) {
+        return (await self.exec(`base64 ${q3(p)} | base64 -d 2>/dev/null`)).stdout;
+      },
+      async writeFile(p, content) {
+        const b64 = Buffer.from(content, "utf-8").toString("base64");
+        await self.exec(`printf %s ${q3(b64)} | base64 -d > ${q3(p)}`);
+      },
+      async exists(p) {
+        const r = await self.exec(`test -e ${q3(p)} && echo Y || echo N`);
+        return r.stdout.trim() === "Y";
+      },
+      async stat(p) {
+        const r = await self.exec(`stat -c '%s %Y' ${q3(p)} 2>/dev/null || stat -f '%z %m' ${q3(p)} 2>/dev/null || true`);
+        const m = r.stdout.trim().match(/^(\d+)\s+(\d+)$/);
+        return m ? { size: parseInt(m[1], 10), mtimeMs: parseInt(m[2], 10) * 1000 } : null;
+      },
+      async readdir(p) {
+        const r = await self.exec(`ls -1A ${q3(p)} 2>/dev/null || true`);
+        const names = r.stdout.split(`
+`).filter(Boolean);
+        const out = [];
+        for (const name of names) {
+          const full = `${p.replace(/\/$/, "")}/${name}`;
+          const d = await self.exec(`test -d ${q3(full)} && echo Y || echo N`);
+          const st = await this.stat(full);
+          out.push({ name, isDirectory: d.stdout.trim() === "Y", size: st?.size, mtime: st?.mtimeMs });
+        }
+        return out;
+      },
+      async rm(p, options) {
+        await self.exec(`rm ${options?.recursive ? "-r " : ""}${options?.force ? "-f " : ""}${q3(p)}`);
+      },
+      async mkdir(p, options) {
+        await self.exec(`mkdir ${options?.recursive ? "-p " : ""}${q3(p)}`);
+      }
+    };
+  }
+  async init() {
+    if (!this.descriptor.terminalId) {
+      this.descriptor.terminalId = await this.terminal.spawnSession(this.descriptor.driver, this.descriptor.target, this.descriptor.config);
+    }
+    if (this.descriptor.cwd) {
+      try {
+        await this.terminal.runCommand(this.descriptor.terminalId, `cd "${this.descriptor.cwd}" 2>/dev/null || true`, 1e4);
+      } catch {}
+    }
+  }
+  ownedSessions = new Set;
+  async destroy() {
+    if (this.descriptor.terminalId) {
+      for (const sid of this.ownedSessions) {
+        const base = `/tmp/filaxis-sessions/${sid}`;
+        try {
+          await this.terminal.runCommand(this.descriptor.terminalId, `kill $(cat ${q3(base)}.pid 2>/dev/null) 2>/dev/null; rm -f ${q3(base)}.pid; true`, 5000);
+        } catch {}
+      }
+      this.ownedSessions.clear();
+      await this.terminal.destroySession(this.descriptor.terminalId);
+    }
+  }
+  async exec(command, options) {
+    if (options?.channel === "pty") {
+      const r = await this.terminal.runCommand(this.descriptor.terminalId, command, {
+        timeoutMs: options?.timeoutMs ?? 120000
+      });
+      return { stdout: r.stdout, stderr: "", exitCode: r.exitCode };
+    }
+    const r = await this.terminal.runCommand(this.descriptor.terminalId, command, {
+      timeoutMs: options?.timeoutMs ?? 120000
+    });
+    return { stdout: r.stdout, stderr: "", exitCode: r.exitCode };
+  }
+  async getCwd() {
+    const r = await this.exec("pwd");
+    return r.stdout.trim();
+  }
+  async getEnv(key) {
+    return (await this.exec(`printf %s "\\$${key}"`)).stdout;
+  }
+  async execSession(command, opts) {
+    const sessionId = `${opts?.name ?? "tsess"}-${Math.random().toString(16).slice(2, 8)}`;
+    const base = `/tmp/filaxis-sessions/${sessionId}`;
+    const wrapped = `{ ${command}; }; echo $? > ${base}.code`;
+    const cd = opts?.cwd ? `cd ${q3(opts.cwd)} && ` : "";
+    await this.exec(`mkdir -p /tmp/filaxis-sessions; ${cd}nohup bash -c ${q3(wrapped)} > ${base}.out 2> ${base}.err < /dev/null & echo $! > ${base}.pid; echo started`);
+    this.ownedSessions.add(sessionId);
+    return { sessionId, logBase: base };
+  }
+  async tailSession(sessionId, lines = 50) {
+    const r = await this.exec(`tail -n ${lines} /tmp/filaxis-sessions/${sessionId}.out 2>/dev/null || true`);
+    return r.stdout.split(`
+`).filter(Boolean);
+  }
+  async readSessionLog(sessionId, opts) {
+    const suffix = opts?.stream === "stderr" ? ".err" : ".out";
+    let cmd = `cat /tmp/filaxis-sessions/${sessionId}${suffix} 2>/dev/null || true`;
+    if (opts?.lines)
+      cmd += ` | tail -n ${opts.lines}`;
+    return (await this.exec(cmd)).stdout.replace(/\n$/, "");
+  }
+  watchSession(_sessionId, _opts) {
+    throw new Error("tmux 后端会话 watcher 属 M2 观察流批次（stream-session 落位后接入）");
+  }
+  async stopSession(sessionId) {
+    await this.exec(`kill $(cat /tmp/filaxis-sessions/${sessionId}.pid 2>/dev/null) 2>/dev/null; true`);
+    const code = await this.exec(`cat /tmp/filaxis-sessions/${sessionId}.code 2>/dev/null || true`);
+    const c = code.stdout.trim();
+    return { exitCode: /^\d+$/.test(c) ? parseInt(c, 10) : null };
+  }
+  listSessions() {
+    return [];
+  }
+}
+
+// src/factory.ts
+class RuntimeFactory {
+  custom = new Map;
+  registerDriver(type, factory) {
+    if (this.custom.has(type) || ["local", "ssh", "tmux"].includes(type)) {
+      throw new Error(`driver '${type}' 已注册，拒绝覆盖——先 unregister 或换类型名`);
+    }
+    this.custom.set(type, factory);
+  }
+  unregisterDriver(type) {
+    return this.custom.delete(type);
+  }
+  registeredTypes() {
+    return ["local", "ssh", "tmux", ...this.custom.keys()];
+  }
+  create(descriptor, fallbackCwd) {
+    if (descriptor.driver === "local") {
+      return LocalRuntimeDriver.fromDescriptor(descriptor, fallbackCwd);
+    }
+    if (descriptor.driver === "ssh") {
+      return new SshPtyDriver(descriptor);
+    }
+    if (descriptor.driver === "tmux") {
+      return new TmuxSessionDriver(descriptor);
+    }
+    const f = this.custom.get(descriptor.driver);
+    if (f)
+      return f(descriptor);
+    throw new Error(`未知 driver '${descriptor.driver}'——经 registerDriver() 注册，或在 config.launchCmd 提供完整启动命令`);
+  }
+}
+// src/runtime-stack.ts
+import { spawn as spawn5 } from "node:child_process";
+class RuntimeStack {
+  static driverCache = new Map;
+  events = new EventBus;
+  factory;
+  log;
+  featuresCache = null;
+  constructor(opts = {}) {
+    this.factory = opts.factory ?? new RuntimeFactory;
+    this.log = opts.logger ?? noopLogger;
+  }
+  static driverKey(d) {
+    const c = d.config ?? {};
+    return JSON.stringify({
+      driver: d.driver,
+      target: d.target,
+      terminalId: d.terminalId,
+      cwd: d.cwd,
+      capabilities: d.capabilities,
+      cfg: {
+        launchCmd: c.launchCmd,
+        runtime: c.runtime,
+        shell: c.shell,
+        namespace: c.namespace,
+        sshOptions: c.sshOptions,
+        connParams: c.connParams
+      }
+    });
+  }
+  async connect(descriptor, fallbackCwd) {
+    const key = RuntimeStack.driverKey(descriptor);
+    const cached = RuntimeStack.driverCache.get(key);
+    if (cached) {
+      this.log.debug(`[Filaxis] 指纹命中复用连接: ${descriptor.driver}/${descriptor.target ?? "local"}`);
+      return cached;
+    }
+    const drv = this.factory.create(descriptor, fallbackCwd);
+    await drv.init();
+    RuntimeStack.driverCache.set(key, drv);
+    this.log.info(`[Filaxis] 新建连接: ${descriptor.driver}/${descriptor.target ?? "local"}`);
+    return drv;
+  }
+  static evictDriver(d) {
+    const key = RuntimeStack.driverKey(d);
+    const drv = RuntimeStack.driverCache.get(key);
+    RuntimeStack.driverCache.delete(key);
+    return drv;
+  }
+  registerDriver(type, f) {
+    this.factory.registerDriver(type, f);
+    this.featuresCache = null;
+  }
+  async features() {
+    if (this.featuresCache)
+      return this.featuresCache;
+    const has = (bin) => new Promise((resolve) => {
+      const probe = process.platform === "win32" ? spawn5("where", [bin], { stdio: "ignore" }) : spawn5("which", [bin], { stdio: "ignore" });
+      probe.on("close", (code) => resolve(code === 0));
+      probe.on("error", () => resolve(false));
+    });
+    const [sshOk, sftpOk, tmuxOk] = await Promise.all([has("ssh"), has("sftp"), has("tmux")]);
+    this.featuresCache = {
+      mux: process.platform !== "win32" && sshOk,
+      sftp: sftpOk,
+      persistent: tmuxOk,
+      transports: this.factory.registeredTypes(),
+      stderrSeparated: true
+    };
+    return this.featuresCache;
+  }
+}
+// src/dialect.ts
+var NULL_DIALECT = {
+  family: "unknown",
+  base64Encode: [],
+  base64Decode: [],
+  sha256: []
+};
+async function tryCmd(exec, cmd) {
+  try {
+    const r = await exec(cmd);
+    return { ok: r.exitCode === 0, stdout: r.stdout };
+  } catch {
+    return { ok: false, stdout: "" };
+  }
+}
+async function probeDialect(exec) {
+  const gnuEnc = await tryCmd(exec, "printf filaxis | base64 -w 0");
+  if (gnuEnc.ok && gnuEnc.stdout.includes("ZmlsYXhpcw==")) {
+    const gnuDec = await tryCmd(exec, "printf ZmlsYXhpcw== | base64 -d");
+    if (gnuDec.ok && gnuDec.stdout.includes("filaxis")) {
+      const sha = await detectSha256(exec);
+      return { family: sha.family, base64Encode: ["base64", "-w", "0"], base64Decode: ["base64", "-d"], sha256: sha.argv };
+    }
+  }
+  const bsdEnc = await tryCmd(exec, "printf filaxis | base64");
+  if (bsdEnc.ok && bsdEnc.stdout.replace(/\s+/g, "").includes("ZmlsYXhpcw==")) {
+    const decD = await tryCmd(exec, "printf ZmlsYXhpcw== | base64 -d");
+    const decFlag = decD.ok && decD.stdout.includes("filaxis") ? "-d" : "-D";
+    const sha = await detectSha256(exec);
+    return { family: sha.family, base64Encode: ["base64"], base64Decode: ["base64", decFlag], sha256: sha.argv };
+  }
+  return { ...NULL_DIALECT, sha256: (await detectSha256(exec)).argv };
+}
+var HEX64 = /[0-9a-f]{64}/;
+async function detectSha256(exec) {
+  const coreutils = await tryCmd(exec, "printf filaxis | sha256sum");
+  if (coreutils.ok && HEX64.test(coreutils.stdout)) {
+    return { family: "gnu", argv: ["sha256sum"] };
+  }
+  const bsd = await tryCmd(exec, "printf filaxis | sha256 -q");
+  if (bsd.ok && HEX64.test(bsd.stdout.trim())) {
+    return { family: "bsd", argv: ["sha256", "-q"] };
+  }
+  const openssl = await tryCmd(exec, "printf filaxis | openssl dgst -sha256");
+  if (openssl.ok && HEX64.test(openssl.stdout)) {
+    return { family: "openssl-fallback", argv: ["openssl", "dgst", "-sha256"] };
+  }
+  return { family: "unknown", argv: [] };
+}
+
+class DialectCache {
+  cache = new Map;
+  async get(probeKey, exec, force = false) {
+    if (!force && this.cache.has(probeKey))
+      return this.cache.get(probeKey);
+    const d = await probeDialect(exec);
+    this.cache.set(probeKey, d);
+    return d;
+  }
+  invalidate(probeKey) {
+    if (probeKey)
+      this.cache.delete(probeKey);
+    else
+      this.cache.clear();
+  }
+}
+
+// src/index.ts
+init_ssh_helpers();
+
+// src/stream-session-manager.ts
+import * as crypto5 from "node:crypto";
+import { existsSync as existsSync2, mkdirSync, rmSync } from "node:fs";
+import { join as join2 } from "node:path";
+import { tmpdir as tmpdir4 } from "node:os";
+import { spawn as spawn6 } from "node:child_process";
+
+// src/vt100-screen.ts
+var ESC = "\x1B";
+var BEL = "\x07";
+
+class Vt100Screen {
+  rows;
+  curRow = 0;
+  curCol = 0;
+  state = 0;
+  csiBuf = "";
+  oscBuf = "";
+  _frames = 0;
+  constructor(opts = {}) {
+    const rows = opts.rows ?? 24;
+    const cols = opts.cols ?? 220;
+    this.rows = Array.from({ length: rows }, () => Array.from({ length: cols }, () => " "));
+  }
+  feed(chunk) {
+    for (const ch of chunk)
+      this.put(ch);
+    this._frames++;
+  }
+  snapshot() {
+    return this.rows.map((r) => r.join("").replace(/ +$/, "")).join(`
+`);
+  }
+  get cursor() {
+    return { row: this.curRow, col: this.curCol };
+  }
+  get frames() {
+    return this._frames;
+  }
+  put(ch) {
+    switch (this.state) {
+      case 0: {
+        if (ch === ESC) {
+          this.state = 1;
+          return;
+        }
+        this.writeChar(ch);
+        return;
+      }
+      case 1: {
+        if (ch === "[") {
+          this.state = 2;
+          this.csiBuf = "";
+          return;
+        }
+        if (ch === "]") {
+          this.state = 3;
+          this.oscBuf = "";
+          return;
+        }
+        this.state = 0;
+        return;
+      }
+      case 2: {
+        if (ch >= "0" && ch <= "9" || ch === ";" || ch === "?") {
+          this.csiBuf += ch;
+          return;
+        }
+        this.state = 0;
+        this.csiDispatch(ch);
+        return;
+      }
+      default: {
+        if (ch === BEL || ch === ESC) {
+          this.state = 0;
+          return;
+        }
+        if (this.oscBuf.length < 256)
+          this.oscBuf += ch;
+        return;
+      }
+    }
+  }
+  csiDispatch(final) {
+    const parts = this.csiBuf.replace(/\?/g, "").split(";");
+    const n = (i, d) => {
+      const v = parts[i] === undefined || parts[i] === "" ? d : parseInt(parts[i], 10);
+      return Number.isFinite(v) ? v : d;
+    };
+    switch (final) {
+      case "H":
+      case "f":
+        this.moveTo(Math.max(0, n(0, 1) - 1), Math.max(0, n(1, 1) - 1));
+        return;
+      case "A":
+        this.moveTo(this.curRow - Math.max(1, n(0, 1)), this.curCol);
+        return;
+      case "B":
+        this.moveTo(this.curRow + Math.max(1, n(0, 1)), this.curCol);
+        return;
+      case "C":
+        this.moveTo(this.curRow, this.curCol + Math.max(1, n(0, 1)));
+        return;
+      case "D":
+        this.moveTo(this.curRow, this.curCol - Math.max(1, n(0, 1)));
+        return;
+      case "J": {
+        const mode = n(0, 0);
+        if (mode === 2)
+          this.clearAll();
+        else if (mode === 0)
+          this.clearRegion(this.curRow, this.curCol, this.rows.length - 1, -1);
+        else if (mode === 1)
+          this.clearRegion(0, 0, this.curRow, this.curCol);
+        return;
+      }
+      case "K": {
+        const mode = n(0, 0);
+        if (mode === 0)
+          this.clearRegion(this.curRow, this.curCol, this.curRow, -1);
+        else if (mode === 1)
+          this.clearRegion(this.curRow, 0, this.curRow, this.curCol);
+        else
+          this.clearRegion(this.curRow, 0, this.curRow, -1);
+        return;
+      }
+      default:
+        return;
+    }
+  }
+  writeChar(ch) {
+    if (ch === `
+`) {
+      this.lineFeed();
+      return;
+    }
+    if (ch === "\r") {
+      this.curCol = 0;
+      return;
+    }
+    if (ch === "\b") {
+      this.curCol = Math.max(0, this.curCol - 1);
+      return;
+    }
+    if (ch === "\t") {
+      const cols = this.rows[0].length;
+      this.curCol = Math.min(cols - 1, (Math.floor(this.curCol / 8) + 1) * 8);
+      return;
+    }
+    if (ch < " ")
+      return;
+    const cols = this.rows[0].length;
+    if (this.curCol >= cols) {
+      this.curCol = 0;
+      this.lineFeed();
+    }
+    this.rows[this.curRow][this.curCol] = ch;
+    this.curCol++;
+  }
+  lineFeed() {
+    if (this.curRow >= this.rows.length - 1) {
+      this.rows.shift();
+      const cols = this.rows[0].length;
+      this.rows.push(Array.from({ length: cols }, () => " "));
+      this.curRow = this.rows.length - 1;
+    } else {
+      this.curRow++;
+    }
+  }
+  moveTo(row, col) {
+    const cols = this.rows[0].length;
+    this.curRow = Math.max(0, Math.min(this.rows.length - 1, row));
+    this.curCol = Math.max(0, Math.min(cols - 1, col));
+  }
+  clearRegion(row1, col1, row2, col2) {
+    const cols = this.rows[0].length;
+    for (let r = Math.max(0, row1);r <= Math.min(this.rows.length - 1, row2); r++) {
+      const from = r === row1 ? Math.max(0, col1) : 0;
+      const to = col2 === -1 || r < row2 ? cols - 1 : Math.min(cols - 1, col2);
+      for (let c = from;c <= to; c++)
+        this.rows[r][c] = " ";
+    }
+  }
+  clearAll() {
+    const cols = this.rows[0].length;
+    this.rows = Array.from({ length: this.rows.length }, () => Array.from({ length: cols }, () => " "));
+  }
+}
+
+// src/stream-session-manager.ts
+var masters = new Map;
+
+class StreamSessionManager {
+  onEvent = () => {
+    return;
+  };
+  entries = new Map;
+  destKey;
+  destArgs;
+  muxEnabled;
+  idleReapMs;
+  spawnImpl;
+  muxDir;
+  log;
+  static DEFAULT_IDLE_REAP_MS = 30 * 60 * 1000;
+  constructor(destArgs, opts = {}) {
+    this.destArgs = destArgs;
+    this.destKey = crypto5.createHash("sha256").update(destArgs.join("\x00")).digest("hex").slice(0, 16);
+    this.muxEnabled = !opts.disableMux && process.platform !== "win32";
+    this.idleReapMs = opts.idleReapMs;
+    this.spawnImpl = opts.spawnImpl ?? ((cmd, argv, o) => spawn6(cmd, argv, o));
+    this.muxDir = opts.muxDir ?? join2(tmpdir4(), "filaxis-stream-mux");
+    this.log = opts.logger ?? noopLogger;
+  }
+  muxFlags() {
+    if (!this.muxEnabled)
+      return [];
+    let m = masters.get(this.destKey);
+    if (!m) {
+      m = { path: join2(this.ensureMuxDir(), `cm-${this.destKey}`), refCount: 0 };
+      masters.set(this.destKey, m);
+    }
+    return [
+      "-o",
+      `ControlPath=${m.path}`,
+      "-o",
+      "ControlMaster=auto",
+      "-o",
+      "ControlPersist=600"
+    ];
+  }
+  ensureMuxDir() {
+    if (!existsSync2(this.muxDir))
+      mkdirSync(this.muxDir, { recursive: true });
+    return this.muxDir;
+  }
+  async start(command, opts = {}) {
+    const sessionId = `${opts.name ?? "stream"}-${crypto5.randomBytes(3).toString("hex")}`;
+    const argv = [
+      "-o",
+      "StrictHostKeyChecking=accept-new",
+      "-o",
+      "ConnectTimeout=10",
+      ...this.muxFlags(),
+      ...this.destArgs,
+      "--",
+      command
+    ];
+    const child = this.spawnImpl("ssh", argv, { stdio: ["ignore", "pipe", "pipe"] });
+    const entry = {
+      sessionId,
+      name: opts.name,
+      command,
+      destKey: this.destKey,
+      child,
+      ring: new OutputRingBuffer({ maxLines: 50, maxLineBytes: 512 }),
+      watchers: new WatchRegistry,
+      watcherMeta: new Map,
+      startedAt: Date.now(),
+      running: true,
+      lastAttentionAt: Date.now(),
+      ownerSessionId: opts.ownerSessionId,
+      opts
+    };
+    this.entries.set(sessionId, entry);
+    const m = masters.get(this.destKey);
+    if (m)
+      m.refCount++;
+    child.stdout?.on("data", (d) => {
+      const text = d.toString("utf-8");
+      if (entry.opts?.onScreen) {
+        if (!entry.screen)
+          entry.screen = new Vt100Screen;
+        entry.screen.feed(text);
+        try {
+          entry.opts.onScreen(entry.screen.snapshot(), entry.screen.frames);
+        } catch {}
+      }
+      this.onChunk(entry, text, "stdout");
+    });
+    child.stderr?.on("data", (d) => this.onChunk(entry, d.toString("utf-8"), "stderr"));
+    child.on("exit", (code) => {
+      if (!entry.running)
+        return;
+      entry.running = false;
+      entry.exitCode = code;
+      try {
+        opts.onExit?.(code);
+      } catch {}
+      this.emit({
+        type: "exit",
+        sessionId,
+        ownerSessionId: opts.ownerSessionId,
+        exitCode: code,
+        lastLines: entry.ring.tail(10)
+      });
+      this.releaseMaster();
+    });
+    child.on("error", (err) => {
+      entry.running = false;
+      this.emit({
+        type: "exit",
+        sessionId,
+        ownerSessionId: opts.ownerSessionId,
+        exitCode: null,
+        lastLines: [err.message]
+      });
+      this.releaseMaster();
+    });
+    if (opts.watchPattern) {
+      this.watch(sessionId, {
+        pattern: opts.watchPattern,
+        once: opts.watchOnce ?? true,
+        contextLines: opts.contextLines
+      });
+    }
+    this.log.info(`[StreamSession ${sessionId}] 流建立（mux=${this.muxEnabled}）`);
+    return { sessionId, name: opts.name };
+  }
+  watch(sessionId, opts) {
+    const e = this.require(sessionId);
+    e.lastAttentionAt = Date.now();
+    const watcherId = `sw-${crypto5.randomBytes(3).toString("hex")}`;
+    e.watchers.add({ id: watcherId, pattern: opts.pattern, once: opts.once });
+    e.watcherMeta.set(watcherId, { pattern: opts.pattern, contextLines: opts.contextLines, once: opts.once });
+    return {
+      cancel: () => {
+        e.watchers.cancel(watcherId);
+        e.watcherMeta.delete(watcherId);
+      }
+    };
+  }
+  tail(sessionId, n = 50) {
+    const e = this.require(sessionId);
+    e.lastAttentionAt = Date.now();
+    return e.ring.tail(n);
+  }
+  tailLines(sessionId, n = 50) {
+    const e = this.require(sessionId);
+    e.lastAttentionAt = Date.now();
+    return e.ring.tailLines(n);
+  }
+  stop(sessionId) {
+    const e = this.require(sessionId);
+    e.running = false;
+    e.child.kill("SIGTERM");
+    this.entries.delete(sessionId);
+    this.log.info(`[StreamSession ${sessionId}] 已收摊`);
+  }
+  list() {
+    const now = Date.now();
+    return Array.from(this.entries.values()).map((e) => ({
+      sessionId: e.sessionId,
+      name: e.name,
+      command: e.command,
+      running: e.running,
+      idleMs: now - e.lastAttentionAt,
+      armedWatchers: e.watcherMeta.size
+    }));
+  }
+  reapIdle(now = Date.now(), ttlMs) {
+    const ttl = ttlMs ?? this.idleReapMs ?? StreamSessionManager.DEFAULT_IDLE_REAP_MS;
+    for (const e of Array.from(this.entries.values())) {
+      if (!e.running)
+        continue;
+      if (e.watcherMeta.size > 0)
+        continue;
+      if (now - e.lastAttentionAt < ttl)
+        continue;
+      this.log.warn(`[StreamSession ${e.sessionId}] 注意力衰减：自动回收`);
+      this.emit({
+        type: "exit",
+        sessionId: e.sessionId,
+        ownerSessionId: e.ownerSessionId,
+        exitCode: null,
+        lastLines: e.ring.tail(5)
+      });
+      this.stop(e.sessionId);
+    }
+  }
+  onChunk(entry, text, stream) {
+    for (const raw of text.split(`
+`)) {
+      if (raw === "")
+        continue;
+      const clean = raw.replace(/\r$/, "");
+      entry.ring.push({ stream, text: clean });
+      try {
+        entry.opts?.onLine?.({ stream, text: clean });
+      } catch {}
+      const anchor = entry.ring.size - 1;
+      for (const watcherId of entry.watchers.match(clean)) {
+        entry.lastAttentionAt = Date.now();
+        const meta = entry.watcherMeta.get(watcherId);
+        entry.watcherMeta.delete(watcherId);
+        this.emit({
+          type: "match",
+          sessionId: entry.sessionId,
+          ownerSessionId: entry.ownerSessionId,
+          watcherId,
+          pattern: String(meta?.pattern ?? "?"),
+          matchedLine: clean,
+          stream,
+          context: entry.ring.contextAround(anchor, meta?.contextLines ?? 5).map((l) => l.text)
+        });
+      }
+    }
+  }
+  releaseMaster() {
+    const m = masters.get(this.destKey);
+    if (!m)
+      return;
+    m.refCount = Math.max(0, m.refCount - 1);
+    if (m.refCount === 0 && this.entries.size === 0 && existsSync2(m.path)) {
+      try {
+        rmSync(m.path, { force: true });
+      } catch {}
+    }
+  }
+  require(sessionId) {
+    const e = this.entries.get(sessionId);
+    if (!e)
+      throw new Error(`stream 会话 '${sessionId}' 不存在`);
+    return e;
+  }
+  emit(ev) {
+    try {
+      this.onEvent(ev);
+    } catch (err) {
+      this.log.warn(`stream event sink threw: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+}
+// src/file-transfer.ts
+import { createHash as createHash2 } from "node:crypto";
+import fs4 from "node:fs/promises";
+import { spawn as defaultSpawn } from "node:child_process";
+var CHUNK_B64 = 48 * 1024;
+
+class TransferVerificationError extends Error {
+  constructor(op, detail) {
+    super(`文件传输校验失败（${op}）: ${detail}`);
+    this.name = "TransferVerificationError";
+  }
+}
+var q4 = (s) => `'${s.replace(/'/g, "'\\''")}'`;
+async function putFile(exec, dialect, localPath, remotePath) {
+  if (!dialect.base64Decode.length) {
+    throw new Error("远端 base64 原语不可用（方言探测 unknown）——该路径不支持文件传输");
+  }
+  const content = await fs4.readFile(localPath);
+  const b64 = content.toString("base64");
+  const tmp = `${remotePath}.filaxis-tmp`;
+  await exec(`rm -f ${q4(tmp)}`);
+  for (let i = 0;i < b64.length; i += CHUNK_B64) {
+    const chunk = b64.slice(i, i + CHUNK_B64);
+    const r = await exec(`printf %s ${q4(chunk)} >> ${q4(tmp)}`);
+    if (r.exitCode !== 0)
+      throw new Error(`put 分块写入失败（chunk ${i / CHUNK_B64}）: ${r.stdout}`);
+  }
+  const dec = dialect.base64Decode.join(" ");
+  const mv = await exec(`${dec} < ${q4(tmp)} > ${q4(remotePath)} && rm -f ${q4(tmp)}`);
+  if (mv.exitCode !== 0) {
+    await exec(`rm -f ${q4(tmp)}`).catch(() => {
+      return;
+    });
+    throw new Error(`put 落位失败: ${mv.stdout}`);
+  }
+  const localSha = createHash2("sha256").update(content).digest("hex");
+  const v = await verify(exec, dialect, remotePath, content.length, localSha);
+  if (!v.verified)
+    throw new TransferVerificationError("put", v.detail);
+  return { bytes: content.length, sha256: localSha, verified: true };
+}
+async function getFile(exec, dialect, remotePath, localPath) {
+  if (!dialect.base64Encode.length) {
+    throw new Error("远端 base64 原语不可用（方言探测 unknown）——该路径不支持文件传输");
+  }
+  const enc = dialect.base64Encode.join(" ");
+  const r = await exec(`${enc} < ${q4(remotePath)}`);
+  if (r.exitCode !== 0)
+    throw new Error(`get 编码回传失败: ${r.stdout}`);
+  const content = Buffer.from(r.stdout.replace(/\s+/g, ""), "base64");
+  await fs4.writeFile(localPath, content);
+  const localSha = createHash2("sha256").update(content).digest("hex");
+  const v = await verify(exec, dialect, remotePath, content.length, localSha);
+  if (!v.verified)
+    throw new TransferVerificationError("get", v.detail);
+  return { bytes: content.length, sha256: localSha, verified: true };
+}
+async function verify(exec, dialect, remotePath, expectSize, expectSha) {
+  const sz = await exec(`wc -c < ${q4(remotePath)}`);
+  const size = parseInt((sz.stdout || "").trim(), 10);
+  if (size !== expectSize)
+    return { verified: false, detail: `size 不一致（远端 ${size} ≠ 本地 ${expectSize}）` };
+  if (!dialect.sha256.length) {
+    return { verified: true, detail: "size-only（sha256 原语缺席）" };
+  }
+  const sh = await exec(`${dialect.sha256.join(" ")} < ${q4(remotePath)}`);
+  const remoteSha = (sh.stdout || "").replace(/[^0-9a-f]/g, "");
+  if (!remoteSha.includes(expectSha)) {
+    return { verified: false, detail: `sha256 不一致（远端 ${remoteSha.slice(0, 16)}… ≠ 本地 ${expectSha.slice(0, 16)}…）` };
+  }
+  return { verified: true, detail: "size+sha256" };
+}
+async function defaultSftpSpawn(argv, batch) {
+  return new Promise((resolve, reject) => {
+    const p = defaultSpawn("sftp", argv, { stdio: ["pipe", "pipe", "pipe"] });
+    let stderr = "";
+    p.stderr?.on("data", (d) => {
+      stderr += d;
+    });
+    p.stdin?.write(batch);
+    p.stdin?.end();
+    p.on("close", (code) => resolve({ exitCode: code, stderr }));
+    p.on("error", reject);
+  });
+}
+async function sftpPutFile(exec, dialect, localPath, remotePath, opts) {
+  const doSpawn = opts.spawnImpl ?? defaultSftpSpawn;
+  const batch = `put ${q4(localPath)} ${q4(remotePath)}
+`;
+  const r = await doSpawn([...opts.connArgs, "-b", "-"], batch);
+  if (r.exitCode !== 0) {
+    throw new Error(`sftp put 失败（exit=${r.exitCode}）——可降级 base64 管道: ${r.stderr.trim().slice(0, 200)}`);
+  }
+  const content = await fs4.readFile(localPath);
+  const localSha = createHash2("sha256").update(content).digest("hex");
+  const v = await verify(exec, dialect, remotePath, content.length, localSha);
+  if (!v.verified)
+    throw new TransferVerificationError("put", v.detail);
+  return { bytes: content.length, sha256: localSha, verified: true };
+}
+async function sftpGetFile(exec, dialect, remotePath, localPath, opts) {
+  const doSpawn = opts.spawnImpl ?? defaultSftpSpawn;
+  const batch = `get ${q4(remotePath)} ${q4(localPath)}
+`;
+  const r = await doSpawn([...opts.connArgs, "-b", "-"], batch);
+  if (r.exitCode !== 0) {
+    throw new Error(`sftp get 失败（exit=${r.exitCode}）——可降级 base64 管道: ${r.stderr.trim().slice(0, 200)}`);
+  }
+  const content = await fs4.readFile(localPath);
+  const localSha = createHash2("sha256").update(content).digest("hex");
+  const v = await verify(exec, dialect, remotePath, content.length, localSha);
+  if (!v.verified)
+    throw new TransferVerificationError("get", v.detail);
+  return { bytes: content.length, sha256: localSha, verified: true };
+}
+// src/layer-env.ts
+init_ssh_helpers();
+import { createHash as createHash3 } from "node:crypto";
+import { rename, stat, mkdir, writeFile, readFile } from "node:fs/promises";
+import { dirname } from "node:path";
+function layerEnvKey(desc) {
+  if (desc.driver === "local")
+    return "local";
+  const c = desc.config ?? {};
+  if (c.pty === true) {
+    const conn = c.connParams;
+    const hostPart = `${desc.target ?? "?"}${conn?.port ? `:${conn.port}` : ""}`;
+    const enters = enterStepsOf(c).map((s) => s.label ?? slugify(s.cmd));
+    return [hostPart, ...enters].join("/");
+  }
+  return `${desc.driver}:${desc.target ?? "default"}`;
+}
+function slugify(s) {
+  return s.trim().toLowerCase().replace(/\s+/g, "-").slice(0, 40) || "enter";
+}
+function buildProbeStage1() {
+  return [
+    `echo "fx_os=$(grep PRETTY_NAME /etc/os-release 2>/dev/null | head -1 | cut -d'"' -f2)"`,
+    `echo "fx_os_dsm=$(grep -E '^productversion=' /etc.defaults/VERSION 2>/dev/null | sed 's/productversion=/Synology DSM v/;s/"//g')"`,
+    `echo "fx_kernel_arch=$(uname -s -m 2>/dev/null)"`,
+    `echo "fx_python=$(if command -v python3 >/dev/null 2>&1; then python3 --version 2>&1; elif command -v python >/dev/null 2>&1; then python --version 2>&1; fi | head -1)"`,
+    `echo "fx_node=$(node --version 2>&1 | head -1)"`,
+    `echo "fx_bun=$(bun --version 2>&1 | head -1)"`,
+    `echo "fx_java=$(java -version 2>&1 | head -1)"`,
+    `echo "fx_gpu=$(nvidia-smi --query-gpu=name,memory.total --format=csv,noheader 2>/dev/null | head -1)"`,
+    `echo "fx_cuda=$(nvidia-smi 2>/dev/null | grep -o 'CUDA Version: [0-9.][0-9.]*' | head -1 | grep -o '[0-9][0-9.]*')"`,
+    `echo "fx_docker=$(command -v docker >/dev/null 2>&1 && echo yes || echo no)"`
+  ].join("; ");
+}
+function buildProbeStage2() {
+  const py = `command -v python3 >/dev/null 2>&1 && echo python3 || echo python`;
+  const parts = [
+    `__FX_PY=$(${py}); __FX_TO=""; command -v timeout >/dev/null 2>&1 && __FX_TO="timeout 15"`
+  ];
+  for (const pkg of PROBE_PACKAGES) {
+    if (pkg.kind === "python") {
+      parts.push(`echo "fx_pkg_${pkg.key}=$($__FX_TO "$__FX_PY" -c '${pkg.probe}' 2>/dev/null)"`);
+    } else {
+      parts.push(`echo "fx_tool_${pkg.key}=$($__FX_TO ${pkg.probe} 2>/dev/null | head -1)"`);
+    }
+  }
+  return parts.join("; ");
+}
+var PROBE_PACKAGES = [
+  { key: "torch", kind: "python", probe: "import torch;print(torch.__version__)", matchNames: ["torch", "pytorch"] },
+  { key: "transformers", kind: "python", probe: "import transformers;print(transformers.__version__)", matchNames: ["transformers", "huggingface"] },
+  { key: "onnxruntime", kind: "python", probe: "import onnxruntime;print(onnxruntime.__version__)", matchNames: ["onnxruntime", "onnx"] },
+  { key: "numpy", kind: "python", probe: "import numpy;print(numpy.__version__)", matchNames: ["numpy"] },
+  { key: "ffmpeg", kind: "tool", probe: "ffmpeg -version", matchNames: ["ffmpeg"] },
+  { key: "git", kind: "tool", probe: "git --version", matchNames: ["git"] }
+];
+function parseProbeOutput(stdout) {
+  const spec = {};
+  const pkgs = [];
+  for (const rawLine of stdout.split(/\r?\n/)) {
+    const m = rawLine.trim().match(/^fx_([a-z0-9_]+)=(.*)$/);
+    if (!m)
+      continue;
+    const val = m[2].trim();
+    if (!val || val.includes("$(") || val.includes("__FX"))
+      continue;
+    switch (m[1]) {
+      case "os":
+        spec.os = val || undefined;
+        break;
+      case "os_dsm":
+        if (val)
+          spec.os = val;
+        break;
+      case "kernel_arch":
+        spec.kernel_arch = val;
+        break;
+      case "python":
+        if (/Python \d/.test(val))
+          spec.python = val;
+        break;
+      case "node":
+        if (/^v?\d/.test(val))
+          spec.node = val.replace(/^v/, "");
+        break;
+      case "bun":
+        if (/^\d+\./.test(val))
+          spec.bun = val;
+        break;
+      case "java":
+        if (/version/i.test(val))
+          spec.java = val;
+        break;
+      case "gpu": {
+        const gm = val.match(/^(.+?),\s*(\d+)\s*MiB$/);
+        if (gm) {
+          spec.gpu = { model: gm[1].trim(), vram_mb: parseInt(gm[2], 10) };
+        } else if (val && looksLikeGpuModel(val)) {
+          spec.gpu = { model: val };
+        }
+        break;
+      }
+      case "cuda":
+        if (/^\d+(\.\d+)*$/.test(val))
+          spec.cuda = val;
+        break;
+      case "docker":
+        spec.docker = val === "yes";
+        break;
+      default: {
+        const pm = m[1].match(/^(?:pkg|tool)_(.+)$/);
+        if (pm) {
+          const key = pm[1];
+          const def = PROBE_PACKAGES.find((p) => p.key === key);
+          const version = extractVersion(val);
+          const name = def?.key ?? key;
+          pkgs.push(version ? `${name}@${version}` : name);
+        }
+      }
+    }
+  }
+  if (!spec.os && spec.kernel_arch)
+    spec.os = spec.kernel_arch.split(/\s+/)[0];
+  if (pkgs.length > 0)
+    spec.packages = [...new Set(pkgs)];
+  return spec;
+}
+function extractVersion(raw) {
+  if (!raw)
+    return;
+  const m = raw.match(/(\d+(\.\d+)+[a-z0-9._-]*)/i) || raw.match(/version\s+(\S+)/i) || raw.match(/(\d+\.\d+)/);
+  return m?.[1];
+}
+function looksLikeGpuModel(val) {
+  if (val.length > 60)
+    return false;
+  if (/failed|error|couldn|can't|unable|no device|not found|driver/i.test(val))
+    return false;
+  if (/[.!?]$/.test(val))
+    return false;
+  return /^[A-Za-z0-9 ()+.-]+$/.test(val);
+}
+
+class LayerEnvStore {
+  path;
+  cache = null;
+  constructor(path) {
+    this.path = path;
+  }
+  async load(force = false) {
+    let mtimeMs = 0;
+    try {
+      mtimeMs = (await stat(this.path)).mtimeMs;
+    } catch {
+      const cfg = { layers: {} };
+      this.cache = { mtimeMs: 0, cfg };
+      return cfg;
+    }
+    if (!force && this.cache?.mtimeMs === mtimeMs)
+      return this.cache.cfg;
+    try {
+      const parsed = JSON.parse(await readFile(this.path, "utf-8"));
+      const cfg = parsed?.layers && typeof parsed.layers === "object" ? { layers: parsed.layers } : { layers: {} };
+      this.cache = { mtimeMs, cfg };
+      return cfg;
+    } catch {
+      return this.cache?.cfg ?? { layers: {} };
+    }
+  }
+  async save(cfg) {
+    await mkdir(dirname(this.path), { recursive: true });
+    const tmp = `${this.path}.tmp`;
+    await writeFile(tmp, JSON.stringify(cfg, null, 2), "utf-8");
+    await rename(tmp, this.path);
+    this.cache = null;
+  }
+  async upsert(key, entry, force = false) {
+    const cfg = await this.load();
+    const existing = cfg.layers[key];
+    if (existing && !force && existing.fingerprint !== entry.fingerprint) {
+      return { stale: true };
+    }
+    cfg.layers[key] = entry;
+    await this.save(cfg);
+    return { stale: false };
+  }
+}
+function projectConnection(desc) {
+  const c = desc.config ?? {};
+  const hops = Array.isArray(c.sshHops) ? c.sshHops.map((h) => typeof h === "string" ? { host: h } : h) : [];
+  return {
+    driver: desc.driver,
+    target: desc.target,
+    conn: c.connParams,
+    hops: hops.length ? hops : undefined,
+    enters: enterStepsOf(c).map((s) => ({ cmd: s.cmd, label: s.label })),
+    launch_cmd: typeof c.launchCmd === "string" ? c.launchCmd : undefined
+  };
+}
+function layerFingerprint(conn, spec) {
+  return "sha256:" + createHash3("sha256").update(JSON.stringify({ conn: { driver: conn.driver, target: conn.target, enters: conn.enters }, spec })).digest("hex").slice(0, 24);
+}
+function matchLayers(cfg, needs) {
+  const out = [];
+  for (const [key, entry] of Object.entries(cfg.layers)) {
+    const spec = entry.environment;
+    const ok = needs.every((need) => {
+      const vm = need.match(/^([a-zA-Z][a-zA-Z0-9_-]*)(>=|<=|>|<|=)?\s*([\d.]+)?$/);
+      if (!vm)
+        return false;
+      const name = vm[1].toLowerCase();
+      const op = vm[2];
+      const want = vm[3];
+      if (name === "gpu")
+        return spec.gpu != null;
+      if (name === "docker")
+        return spec.docker === true;
+      if (name === "cuda")
+        return spec.cuda != null;
+      if (name === "python" || name === "node" || name === "bun" || name === "java") {
+        const have = spec[name];
+        if (!have)
+          return false;
+        if (!op || !want)
+          return true;
+        return compareVersion(extractVersion(have) ?? "0", want, op);
+      }
+      const pkg = (spec.packages ?? []).find((p) => {
+        const base = p.split("@")[0];
+        const def = PROBE_PACKAGES.find((d) => base === d.key || d.matchNames.includes(base));
+        return base === name || def?.matchNames.includes(name);
+      });
+      if (!pkg)
+        return false;
+      if (!op || !want)
+        return true;
+      return compareVersion(pkg.split("@")[1] ?? "0", want, op);
+    });
+    if (ok)
+      out.push({ key, entry });
+  }
+  return out;
+}
+function compareVersion(a, b, op) {
+  const pa = a.split(".").map((x) => parseInt(x, 10) || 0);
+  const pb = b.split(".").map((x) => parseInt(x, 10) || 0);
+  for (let i = 0;i < Math.max(pa.length, pb.length); i++) {
+    const d = (pa[i] ?? 0) - (pb[i] ?? 0);
+    if (d !== 0) {
+      if (op === ">=")
+        return d > 0;
+      if (op === "<=")
+        return d < 0;
+      if (op === ">")
+        return d > 0;
+      if (op === "<")
+        return d < 0;
+      return false;
+    }
+  }
+  return op === ">=" || op === "<=" || op === "=";
+}
+// src/file-edit.ts
+class EditConflictError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "EditConflictError";
+  }
+}
+var q5 = (s) => `'${s.replace(/'/g, "'\\''")}'`;
+var shellSafe = (s) => !s.includes("'") && !s.includes(`
+`);
+var statCmdOf = (f) => `stat -c '%Y %s' ${f} 2>/dev/null || stat -f '%m %z' ${f} 2>/dev/null`;
+var dialectCache = new Map;
+async function dialectOf(drv) {
+  const key = JSON.stringify(drv.descriptor);
+  const hit = dialectCache.get(key);
+  if (hit)
+    return hit;
+  const probe = await drv.exec("echo FX2=$(printf filaxis | base64 -w 0 2>/dev/null | head -c 8);" + "echo FX3=$(printf ZmlsYXhpcw== | base64 -d 2>/dev/null | head -c 7);" + "echo FX4=$(printf ZmlsYXhpcw== | base64 -D 2>/dev/null | head -c 7)", { timeoutMs: 15000 });
+  const out = probe.stdout || "";
+  const b64Gnu = /FX2=ZmlsYXhp/.test(out);
+  const decD = /FX4=filaxis/.test(out);
+  const d = {
+    statCmd: "",
+    enc: b64Gnu ? "base64 -w 0" : "base64",
+    dec: decD ? "base64 -D" : "base64 -d",
+    shaCmd: `{ sha256sum ${"{f}"} 2>/dev/null || sha256 -q ${"{f}"} 2>/dev/null || openssl dgst -sha256 ${"{f}"} 2>/dev/null | tail -1; } | head -c 12`
+  };
+  dialectCache.set(key, d);
+  return d;
+}
+async function editFile(drv, path, oldStr, newStr, opts = {}) {
+  const dialect = await dialectOf(drv);
+  const qp = q5(path);
+  const readCmd = `${statCmdOf(qp)}; ${dialect.shaCmd.replace(/\{f\}/g, qp)}; echo __FXS__; ${dialect.enc} ${qp} 2>/dev/null`;
+  const r = await drv.exec(readCmd, { timeoutMs: 30000 });
+  const [stampPart, b64Part] = (r.stdout || "").split("__FXS__");
+  const originStampRaw = (stampPart ?? "").trim();
+  const originLines = originStampRaw.split(/\n/);
+  const statStamp = (originLines[0] ?? "").trim();
+  const shaStamp = (originLines[1] ?? "").trim();
+  if (!shellSafe(statStamp) || !shellSafe(shaStamp)) {
+    throw new Error(`远端戳异常（stat/sha256 输出非单行）: ${path}`);
+  }
+  const originParts = statStamp.split(/\s+/);
+  const origin = {
+    mtimeMs: parseInt(originParts[0] ?? "0", 10) * 1000,
+    size: parseInt(originParts[1] ?? "0", 10)
+  };
+  if (!origin.size || !shaStamp)
+    throw new Error(`文件不存在或指纹异常: ${path}（${originStampRaw}）`);
+  const content0 = Buffer.from((b64Part ?? "").replace(/\s+/g, ""), "base64").toString("utf-8");
+  const occurrences = content0.split(oldStr).length - 1;
+  if (occurrences === 0) {
+    throw new Error(`未命中待替换片段（0 处）: ${path}（oldStr 长度 ${oldStr.length}，文件 ${content0.length} 字符）`);
+  }
+  if (occurrences > 1 && !opts.all) {
+    throw new Error(`多处命中（${occurrences} 处）——精确替换语义拒绝；确认全替换请传 { all: true }: ${path}`);
+  }
+  const edited = opts.all ? content0.split(oldStr).join(newStr) : content0.replace(oldStr, newStr);
+  const newB64 = Buffer.from(edited, "utf-8").toString("base64");
+  if (newB64.length > 30000) {
+    return editFileViaFs(drv, path, edited, occurrences);
+  }
+  const cmd = `if [ "$(${statCmdOf(qp)})" = "${statStamp}" ] && ` + `[ "$(${dialect.shaCmd.replace(/\{f\}/g, qp)})" = "${shaStamp}" ]; then ` + `printf %s ${q5(newB64)} | ${dialect.dec} > ${qp}.fx-tmp && mv ${qp}.fx-tmp ${qp} && ` + `echo "FX_OK $(stat -c '%Y %s' ${qp} 2>/dev/null || stat -f '%m %z' ${qp} 2>/dev/null)"; ` + `else echo FX_CAS_FAIL; fi`;
+  const cas = await drv.exec(cmd, { timeoutMs: 30000 });
+  const out = (cas.stdout || "").trim();
+  if (out.startsWith("FX_CAS_FAIL")) {
+    throw new EditConflictError(`TOCTOU 冲突：CAS 戳不符（他人先写）: ${path}（读时 stat ${statStamp} sha ${shaStamp}）`);
+  }
+  if (!out.startsWith("FX_OK")) {
+    throw new Error(`远端 CAS 写回异常: ${path}（输出 ${out.slice(0, 80)}）`);
+  }
+  return {
+    path,
+    occurrences,
+    bytesBefore: origin.size,
+    bytesAfter: edited.length,
+    lockedAtMtimeMs: origin.mtimeMs
+  };
+}
+async function editFileViaFs(drv, path, edited, occurrences) {
+  if (!drv.fs.stat) {
+    throw new Error(`该层不支持受控编辑（fs.stat 缺席——TOCTOU 锁依赖）: ${path}`);
+  }
+  const before = await drv.fs.stat(path);
+  if (!before)
+    throw new Error(`文件不存在: ${path}`);
+  const lockCheck = await drv.fs.stat(path);
+  if (!lockCheck || lockCheck.mtimeMs !== before.mtimeMs || lockCheck.size !== before.size) {
+    throw new EditConflictError(`TOCTOU 冲突：读取后文件已被他人修改（mtime ${before.mtimeMs}→${lockCheck?.mtimeMs}）: ${path}`);
+  }
+  await drv.fs.writeFile(path, edited);
+  const after = await drv.fs.stat(path);
+  if (after && before.mtimeMs === after.mtimeMs && before.size === after.size) {
+    if (edited.length !== after.size) {
+      throw new Error(`写后回读异常（size 未随写入变化）: ${path}`);
+    }
+  }
+  return {
+    path,
+    occurrences,
+    bytesBefore: before.size,
+    bytesAfter: edited.length,
+    lockedAtMtimeMs: before.mtimeMs
+  };
+}
+
+// src/agent-toolkit.ts
+var TOOL_DEFS = [
+  {
+    type: "function",
+    function: {
+      name: "run_command",
+      description: "执行一次性命令。退出码如实返回（非零不是异常——是数据，供条件分支）；" + "只有无法执行（超时/中断/连接死）才报错。stdout 与 stderr 分离返回。",
+      parameters: {
+        type: "object",
+        properties: {
+          command: { type: "string", description: "shell 命令" },
+          timeout_ms: { type: "number", description: "超时毫秒（缺省 120000）" }
+        },
+        required: ["command"]
+      }
+    }
+  },
+  {
+    type: "function",
+    function: {
+      name: "spawn_and_observe",
+      description: "启动长跑任务（立即返回句柄不阻塞）。可选就绪标记（ready_marker——回溯热窗口，" + "快输出进程竞态安全）与错误模式（error_pattern——命中即自动收摊防遗忘泄漏）。" + "后续用 stop_and_verify 停止并核实终态。",
+      parameters: {
+        type: "object",
+        properties: {
+          command: { type: "string", description: "长跑命令" },
+          ready_marker: { type: "string", description: "就绪标记（如 'listening on'）" },
+          error_pattern: { type: "string", description: "错误模式（命中即收摊）" },
+          name: { type: "string", description: "会话名（人读前缀）" }
+        },
+        required: ["command"]
+      }
+    }
+  },
+  {
+    type: "function",
+    function: {
+      name: "stop_and_verify",
+      description: "停止任务并核实终态。status 三态：exited=拿到退出码；stopped=终止已核实；" + "unknown=核实不可达（非成功非失败——重试核实或显式上报，严禁当已清理）。",
+      parameters: {
+        type: "object",
+        properties: {
+          session_id: { type: "string", description: "spawn_and_observe 返回的 session_id" }
+        },
+        required: ["session_id"]
+      }
+    }
+  },
+  {
+    type: "function",
+    function: {
+      name: "read_file",
+      description: "读取远端层文件（UTF-8 文本）。返回内容与 (size, mtime_ms)。",
+      parameters: {
+        type: "object",
+        properties: {
+          path: { type: "string" }
+        },
+        required: ["path"]
+      }
+    }
+  },
+  {
+    type: "function",
+    function: {
+      name: "edit_file",
+      description: "受控编辑远端文件：精确替换（唯一命中校验，all=true 全替换）+ TOCTOU 乐观锁（他人先写则拒绝）" + "+ base64 保真写回（零 Shell 转义——绝不 sed -i）。未命中/多处命中/冲突均报错不盲写。",
+      parameters: {
+        type: "object",
+        properties: {
+          path: { type: "string" },
+          old: { type: "string", description: "待替换片段（含足够上下文唯一）" },
+          new: { type: "string" },
+          all: { type: "boolean", description: "多处命中全替换（缺省报错）" }
+        },
+        required: ["path", "old", "new"]
+      }
+    }
+  },
+  {
+    type: "function",
+    function: {
+      name: "observe_stream",
+      description: "长跑观察（限时快照）：启动长跑会话并观察一段时间（缺省 8s）按流过滤（stderr/stdout/both），" + "返回行对象（带 stream 标记）。跨流序为到达序。",
+      parameters: {
+        type: "object",
+        properties: {
+          command: { type: "string" },
+          duration_ms: { type: "number", description: "观察时长（缺省 8000）" },
+          stream: { type: "string", enum: ["stdout", "stderr", "both"], description: "流过滤（缺省 both）" },
+          name: { type: "string" }
+        },
+        required: ["command"]
+      }
+    }
+  }
+];
+function createAgentToolkit(stack, opts = {}) {
+  const layer = opts.driver ? Promise.resolve(opts.driver) : stack.connect(opts.descriptor ?? { driver: "local" });
+  const readyTimeoutMs = opts.readyTimeoutMs ?? 15000;
+  return {
+    tools: TOOL_DEFS,
+    layer,
+    handlers: {
+      async run_command({ command, timeout_ms }) {
+        const drv = await layer;
+        const r = await drv.exec(command, { timeoutMs: timeout_ms });
+        return {
+          stdout: r.stdout,
+          stderr: r.stderr,
+          exit_code: r.exitCode,
+          effective_user: r.effectiveUser
+        };
+      },
+      async spawn_and_observe({ command, ready_marker, error_pattern, name }) {
+        const drv = await layer;
+        const h = await drv.execSession(command, name ? { name } : undefined);
+        if (error_pattern) {
+          drv.watchSession(h.sessionId, { pattern: error_pattern, once: false, thenStop: true });
+        }
+        let note;
+        if (ready_marker) {
+          const t0 = Date.now();
+          for (;; ) {
+            const lines = await drv.tailSession(h.sessionId, 50);
+            if (lines.some((l) => l.includes(ready_marker))) {
+              note = "ready";
+              break;
+            }
+            if (Date.now() - t0 > readyTimeoutMs) {
+              await drv.stopSession(h.sessionId).catch(() => {
+                return;
+              });
+              throw new Error(`ready 超时（${readyTimeoutMs}ms 未见 '${ready_marker}'——已自动停止）`);
+            }
+            await new Promise((r) => setTimeout(r, 100));
+          }
+        }
+        return { session_id: h.sessionId, log_base: h.logBase, note };
+      },
+      async read_file({ path }) {
+        const drv = await layer;
+        if (!drv.fs.stat)
+          throw new Error("该层不支持 read_file 的元数据（fs.stat 缺席）");
+        const st = await drv.fs.stat(path);
+        if (!st)
+          throw new Error(`文件不存在: ${path}`);
+        const content = await drv.fs.readFile(path);
+        return { path, content, size: st.size, mtime_ms: st.mtimeMs };
+      },
+      async edit_file({ path, old, new: newStr, all }) {
+        const drv = await layer;
+        const r = await editFile(drv, path, old, newStr, { all });
+        return { path: r.path, occurrences: r.occurrences, bytes_before: r.bytesBefore, bytes_after: r.bytesAfter };
+      },
+      async observe_stream({ command, duration_ms, stream, name }) {
+        const drv = await layer;
+        const h = await drv.execSession(command, name ? { name } : undefined);
+        const dur = duration_ms ?? 8000;
+        await new Promise((r) => setTimeout(r, dur));
+        const anyDrv = drv;
+        const lines = anyDrv.sessions?.tailLines ? anyDrv.sessions.tailLines(h.sessionId, 500) : (await drv.tailSession(h.sessionId, 500)).map((t) => ({ stream: "stdout", text: t }));
+        const filtered = stream && stream !== "both" ? lines.filter((l) => l.stream === stream) : lines;
+        await drv.stopSession(h.sessionId).catch(() => {
+          return;
+        });
+        return { session_id: h.sessionId, lines: filtered };
+      },
+      async stop_and_verify({ session_id }) {
+        const drv = await layer;
+        const r = await drv.stopSession(session_id);
+        if (r.status === "exited")
+          return { status: "exited", exit_code: r.exitCode };
+        if (r.status === "stopped")
+          return { status: "stopped", note: "终止已核实（SIGKILL 升级在场）" };
+        if (r.status === "unknown")
+          return { status: "unknown", note: "核实不可达——重连后核实或显式上报" };
+        return r.exitCode != null ? { status: "exited", exit_code: r.exitCode } : { status: "stopped", note: "已发终止（旧形态 driver——建议升级内核取三态）" };
+      }
+    }
+  };
+}
+// src/layer-discovery.ts
+async function discoverLayer(driver, opts = {}) {
+  const key = layerEnvKey(driver.descriptor);
+  const r1 = await driver.exec(buildProbeStage1(), { timeoutMs: 30000 });
+  const spec = parseProbeOutput(r1.stdout);
+  let probeNote;
+  if (!opts.skipStage2) {
+    try {
+      const r2 = await driver.exec(buildProbeStage2(), {
+        timeoutMs: opts.stage2TimeoutMs ?? 120000
+      });
+      const spec2 = parseProbeOutput(r2.stdout);
+      spec.packages = spec2.packages;
+    } catch (err) {
+      probeNote = `stage2 失败（${err instanceof Error ? err.message : String(err)}）——packages 可能缺席`;
+      opts.logger?.warn(`[discoverLayer ${key}] ${probeNote}`);
+    }
+  } else {
+    probeNote = "stage2 skipped";
+  }
+  const entry = {
+    connection: projectConnection(driver.descriptor),
+    environment: spec,
+    discovered_at: new Date().toISOString(),
+    fingerprint: layerFingerprint(projectConnection(driver.descriptor), spec),
+    probe_note: probeNote
+  };
+  let stale;
+  if (opts.store) {
+    const r = await opts.store.upsert(key, entry);
+    stale = r.stale;
+  }
+  return { key, spec, probeNote, stale, entry: opts.store ? undefined : entry };
+}
+// src/stream-window.ts
+import { spawn as spawn7 } from "node:child_process";
+var TRUNC_SUFFIX2 = "…[truncated]";
+
+class StreamWindow {
+  name;
+  layerAlias;
+  source;
+  command;
+  maxFrames;
+  maxLineBytes;
+  frames = [];
+  nextSeq = 1;
+  _stale = false;
+  _closed = false;
+  consumers = new Map;
+  transport = null;
+  lastActivityAt = Date.now();
+  constructor(name, layerAlias, source, command, maxFrames = 200, maxLineBytes = 1024) {
+    this.name = name;
+    this.layerAlias = layerAlias;
+    this.source = source;
+    this.command = command;
+    this.maxFrames = maxFrames;
+    this.maxLineBytes = maxLineBytes;
+  }
+  get stale() {
+    return this._stale;
+  }
+  get closed() {
+    return this._closed;
+  }
+  get frameCount() {
+    return this.frames.length;
+  }
+  get oldestSeq() {
+    return this.frames.length ? this.frames[0].seq : 0;
+  }
+  get newestSeq() {
+    return this.frames.length ? this.frames[this.frames.length - 1].seq : 0;
+  }
+  get lastActiveAt() {
+    return this.lastActivityAt;
+  }
+  push(text) {
+    if (this._closed)
+      return;
+    let line = text;
+    if (line.length > this.maxLineBytes) {
+      line = line.slice(0, this.maxLineBytes - TRUNC_SUFFIX2.length) + TRUNC_SUFFIX2;
+    }
+    this.frames.push({ seq: this.nextSeq++, ts: Date.now(), text: line });
+    if (this.frames.length > this.maxFrames) {
+      this.frames = this.frames.slice(-this.maxFrames);
+    }
+    this._stale = false;
+    this.lastActivityAt = Date.now();
+  }
+  peekLast(n = 20) {
+    return this.snapshot(this.frames.slice(-Math.max(0, n)));
+  }
+  peekWindow(ms) {
+    const cutoff = Date.now() - ms;
+    const frames = this.frames.filter((f) => f.ts >= cutoff);
+    return this.snapshot(frames);
+  }
+  peekSince(sinceSeq, n = 50, consumerId) {
+    const frames = this.frames.filter((f) => f.seq > sinceSeq).slice(0, Math.max(0, n));
+    const result = this.snapshot(frames);
+    if (this.oldestSeq > sinceSeq + 1 && sinceSeq > 0)
+      result.gap = true;
+    if (consumerId) {
+      const lastSeq = frames.length ? frames[frames.length - 1].seq : sinceSeq;
+      this.consumers.set(consumerId, Math.max(lastSeq, sinceSeq));
+      this.lastActivityAt = Date.now();
+    }
+    return result;
+  }
+  consumerSeq(consumerId) {
+    return this.consumers.get(consumerId) ?? 0;
+  }
+  markStale() {
+    if (this._closed)
+      return;
+    this._stale = true;
+  }
+  attachTransport(t) {
+    this.transport = t;
+  }
+  close() {
+    if (this._closed)
+      return;
+    this._closed = true;
+    try {
+      if (this.transport?.kind === "local") {
+        this.transport.child.kill("SIGTERM");
+      } else if (this.transport?.kind === "remote") {
+        Promise.resolve(this.transport.manager.stop(this.transport.sessionId)).catch(() => {});
+      }
+    } catch {}
+    this.frames = [];
+    this.consumers.clear();
+  }
+  snapshot(frames) {
+    this.lastActivityAt = Date.now();
+    return {
+      name: this.name,
+      oldestSeq: this.oldestSeq,
+      newestSeq: this.newestSeq,
+      stale: this._stale,
+      frames
+    };
+  }
+}
+
+class LineSplitter {
+  buf = "";
+  push(chunk, onLine) {
+    this.buf += chunk;
+    const lines = this.buf.split(`
+`);
+    this.buf = lines.pop() ?? "";
+    for (const line of lines) {
+      const clean = line.replace(/\r$/, "");
+      if (clean !== "")
+        onLine(clean);
+    }
+  }
+  flush(onLine) {
+    const rest = this.buf.replace(/\r$/, "");
+    this.buf = "";
+    if (rest !== "")
+      onLine(rest);
+  }
+}
+
+class RemoteBridge {
+  window;
+  manager;
+  constructor(window, manager) {
+    this.window = window;
+    this.manager = manager;
+  }
+  async start(command) {
+    const { sessionId } = await this.manager.start(command, {
+      name: this.window.name.replace(/[^A-Za-z0-9_-]/g, "_"),
+      onLine: (line) => this.window.push(line.text),
+      onExit: () => this.window.markStale()
+    });
+    this.window.attachTransport({ kind: "remote", manager: this.manager, sessionId });
+  }
+}
+
+class StreamWindowRegistry {
+  windows = new Map;
+  sweeper;
+  idleTtlMs;
+  shell;
+  log;
+  constructor(opts = {}) {
+    this.idleTtlMs = opts.idleTtlMs ?? 30 * 60000;
+    this.shell = opts.shell ?? resolveLocalShell(undefined, opts.logger);
+    this.log = opts.logger ?? noopLogger;
+    this.sweeper = setInterval(() => this.sweep(), 60000);
+    this.sweeper.unref();
+  }
+  async open(opts) {
+    const existing = this.windows.get(opts.name);
+    if (existing && !existing.closed) {
+      throw new Error(`观察窗 '${opts.name}' 已存在（stop 后可重建）`);
+    }
+    const layerAlias = opts.layerAlias ?? "local";
+    const source = opts.name.split(":").slice(-1)[0] ?? opts.name;
+    const win = new StreamWindow(opts.name, layerAlias, source, opts.command, opts.maxFrames, opts.maxLineBytes);
+    if (layerAlias === "local") {
+      const child = spawn7(this.shell, ["-c", opts.command], { stdio: ["ignore", "pipe", "pipe"] });
+      const splitter = new LineSplitter;
+      child.stdout?.on("data", (d) => splitter.push(d.toString("utf-8"), (l) => win.push(l)));
+      child.stderr?.on("data", (d) => splitter.push(d.toString("utf-8"), (l) => win.push(l)));
+      child.on("exit", () => {
+        splitter.flush((l) => win.push(l));
+        win.markStale();
+      });
+      win.attachTransport({ kind: "local", child });
+    } else {
+      if (!opts.manager)
+        throw new Error(`remote 窗需要 StreamSessionManager（layer='${layerAlias}'）`);
+      await new RemoteBridge(win, opts.manager).start(opts.command);
+    }
+    this.windows.set(opts.name, win);
+    this.log.info(`[StreamWindow] open '${opts.name}' (layer=${layerAlias})`);
+    return win;
+  }
+  stop(name) {
+    const win = this.require(name);
+    win.close();
+    this.windows.delete(name);
+  }
+  peek(pattern) {
+    return this.matches(pattern);
+  }
+  get(name) {
+    return this.windows.get(name);
+  }
+  list() {
+    return [...this.windows.values()].map((w) => ({
+      name: w.name,
+      layer: w.layerAlias,
+      frames: w.frameCount,
+      stale: w.stale,
+      command: w.command
+    }));
+  }
+  require(name) {
+    const w = this.windows.get(name);
+    if (!w)
+      throw new Error(`观察窗 '${name}' 不存在`);
+    return w;
+  }
+  matches(pattern) {
+    const hasWildcard = pattern.includes("*") || pattern.includes("?");
+    if (!hasWildcard) {
+      const w = this.windows.get(pattern);
+      return w ? [w] : [];
+    }
+    const re = new RegExp("^" + pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*").replace(/\?/g, ".") + "$");
+    return [...this.windows.values()].filter((w) => re.test(w.name));
+  }
+  sweep() {
+    const now = Date.now();
+    for (const [name, w] of this.windows) {
+      if (now - w.lastActiveAt > this.idleTtlMs) {
+        this.log.info(`[StreamWindow] '${name}' 空引用超时 → 销毁`);
+        this.stop(name);
+      }
+    }
+  }
+  dispose() {
+    clearInterval(this.sweeper);
+    for (const name of [...this.windows.keys()])
+      this.stop(name);
+  }
+}
+var _registry = null;
+function getStreamWindowRegistry() {
+  if (!_registry)
+    _registry = new StreamWindowRegistry;
+  return _registry;
+}
+export {
+  DEFAULT_TERMINAL_CONFIG,
+  DialectCache,
+  EditConflictError,
+  EventBus,
+  LAYER_IDLE_THRESHOLD_MS,
+  LayerEnvStore,
+  LineAssembler,
+  LocalRuntimeDriver,
+  LocalSessionManager,
+  NULL_DIALECT,
+  OutputBuffer,
+  OutputRingBuffer,
+  PROBE_PACKAGES,
+  RemoteSessionManager,
+  RuntimeFactory,
+  RuntimeStack,
+  SSH_INPUT_WAIT_RE,
+  SshPtyDriver,
+  StreamSessionManager,
+  StreamWindow,
+  StreamWindowRegistry,
+  TerminalManager,
+  TmuxError,
+  TmuxSessionDriver,
+  TransferVerificationError,
+  Vt100Screen,
+  WatchRegistry,
+  autonomousSshOpts,
+  buildProbeStage1,
+  buildProbeStage2,
+  compilePromptPatterns,
+  createAgentToolkit,
+  discoverLayer,
+  editFile,
+  enterStepsOf,
+  expandHomePath,
+  getFile,
+  getStreamWindowRegistry,
+  hopHost,
+  hopLabel,
+  hopSshCommand,
+  layerDisplayLabel,
+  layerDisplayName,
+  layerEnvKey,
+  layerFingerprint,
+  layerPathIdentities,
+  matchLayers,
+  noopLogger,
+  parseProbeOutput,
+  probeDialect,
+  projectConnection,
+  putFile,
+  renderExecChannel,
+  renderForwardArg,
+  resolveLayerState,
+  resolveLocalShell,
+  resolveSshIdentity,
+  rootSshSpawnArgs,
+  sftpGetFile,
+  sftpPutFile,
+  sshArgsFor,
+  sshArgsQuoted
+};