@syrkos/filaxis 0.1.0-alpha.11 → 0.1.0-alpha.13

package/dist/index.js

@@ -1182,7 +1182,7 @@ class PtyLink {
   registerFallbackStep() {
     const step = String(this.fallbackSteps.size);
     this.fallbackSteps.add(step);
-    return `; echo __FILAXIS_FB_${this.fallbackNonce}_${step}_$?_$RANDOM`;
+    return `; echo __FILAXIS_FB_${this.fallbackNonce}_${step}_$?_$$`;
   }
   attach(args) {
     this.fallbackNonce = crypto4.randomBytes(16).toString("hex");
@@ -1232,7 +1232,7 @@ ${raw.slice(-1500)}` : `${reason}
     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)
+    this.send(`stty -echo -ixon cols 500 rows 50; export PS1= PS2=; echo PTYRDY_$$_$(id -un 2>/dev/null)
 `);
     try {
       await new Promise((resolve, reject) => {
@@ -2612,6 +2612,8 @@ class RuntimeFactory {
 }
 // src/runtime-stack.ts
 import { spawn as spawn5 } from "node:child_process";
+import * as os from "node:os";
+init_ssh_helpers();
 class RuntimeStack {
   static driverCache = new Map;
   events = new EventBus;
@@ -2631,12 +2633,15 @@ class RuntimeStack {
       cwd: d.cwd,
       capabilities: d.capabilities,
       cfg: {
+        pty: c.pty,
+        connParams: c.connParams,
+        sshHops: c.sshHops,
+        enters: enterStepsOf(c).map((s) => s.cmd),
         launchCmd: c.launchCmd,
         runtime: c.runtime,
         shell: c.shell,
         namespace: c.namespace,
-        sshOptions: c.sshOptions,
-        connParams: c.connParams
+        sshOptions: c.sshOptions
       }
     });
   }
@@ -2663,6 +2668,185 @@ class RuntimeStack {
     this.factory.registerDriver(type, f);
     this.featuresCache = null;
   }
+  namedLayers = new Map;
+  activeName;
+  get layers() {
+    return this.namedLayers;
+  }
+  get active() {
+    return this.activeName ? this.namedLayers.get(this.activeName)?.driver : undefined;
+  }
+  get activeLayer() {
+    return this.activeName ? this.namedLayers.get(this.activeName) : undefined;
+  }
+  async addLayer(name, descriptorOrDriver) {
+    this.assertNotDupName(name);
+    if (this.isDriver(descriptorOrDriver)) {
+      const driver = descriptorOrDriver;
+      const handle = { name, descriptor: driver.descriptor, driver };
+      this.namedLayers.set(name, handle);
+      this.activeName = name;
+      return { handle, reused: false };
+    }
+    const descriptor = descriptorOrDriver;
+    const hit = await this.findIdentityHit(descriptor);
+    if (hit) {
+      const reused = hit.terminal || await this.verifyLanding(hit.handle, hopHost(layerPathIdentities(descriptor).at(-1) ?? ""));
+      if (reused) {
+        this.log.info(`[Filaxis] 层 '${name}' 落点已由 '${hit.handle.name}' 持有——幂等复用（不重复建连）`);
+        return { handle: hit.handle, reused: true, reusedFrom: hit.handle.name };
+      }
+      throw new Error(`层名 '${name}' 的落点 identity 命中既有层 '${hit.handle.name}' 的途经节点，且落点校验不符` + `（期望 ${hopHost(layerPathIdentities(descriptor).at(-1) ?? "?")}，实测 ${hit.handle.actualHostname ?? "?"}）` + `（宁重连不错主机）：请检查连接参数后重试`);
+    }
+    const driver = await this.connect(descriptor);
+    const handle = { name, descriptor: driver.descriptor, driver };
+    this.namedLayers.set(name, handle);
+    this.activeName = name;
+    return { handle, reused: false };
+  }
+  async layerInto(from, name, enterCmd, opts = {}) {
+    this.assertNotDupName(name);
+    const src = this.requireLayer(from);
+    const pushInto = src.driver.pushInto;
+    if (typeof pushInto !== "function") {
+      throw new Error(`层 '${from}'（${src.descriptor.driver}）不支持派生进入——需 ssh PTY 形态（pushInto 缺席）`);
+    }
+    const driver = await pushInto.call(src.driver, enterCmd, opts.label ?? enterCmd.slice(0, 30));
+    const handle = { name, descriptor: driver.descriptor, driver };
+    this.namedLayers.set(name, handle);
+    this.activeName = name;
+    return handle;
+  }
+  async sshInto(from, name, target, connParams) {
+    this.assertNotDupName(name);
+    const src = this.requireLayer(from);
+    const hop = connParams ? { host: target, conn: connParams } : target;
+    const hit = await this.findIdentityHopHit(hop);
+    if (hit) {
+      const reused = hit.terminal || await this.verifyLanding(hit.handle, hopHost(hop));
+      if (reused) {
+        this.log.info(`[Filaxis] 层 '${name}' 落点已由 '${hit.handle.name}' 持有——幂等复用（不重复建连）`);
+        return { handle: hit.handle, reused: true, reusedFrom: hit.handle.name };
+      }
+      throw new Error(`层名 '${name}' 的落点 identity 命中既有层 '${hit.handle.name}' 的途经节点，且落点校验不符` + `（期望 ${hopHost(hop)}，实测 ${hit.handle.actualHostname ?? "?"}）——宁重连不错主机：请检查连接参数后重试`);
+    }
+    const pushChild = src.driver.pushChild;
+    if (typeof pushChild !== "function") {
+      throw new Error(`层 '${from}'（${src.descriptor.driver}）不支持链式 ssh 派生——需 ssh PTY 形态（pushChild 缺席）`);
+    }
+    const driver = await pushChild.call(src.driver, hop);
+    const handle = { name, descriptor: driver.descriptor, driver };
+    this.namedLayers.set(name, handle);
+    this.activeName = name;
+    return { handle, reused: false };
+  }
+  layer(name) {
+    return this.requireLayer(name);
+  }
+  setActive(name) {
+    const h = this.requireLayer(name);
+    this.activeName = name;
+    return h;
+  }
+  async removeLayer(name, opts = {}) {
+    const h = this.requireLayer(name);
+    this.namedLayers.delete(name);
+    if (opts.destroy) {
+      RuntimeStack.evictDriver(h.descriptor);
+      await h.driver.destroy().catch(() => {
+        return;
+      });
+    }
+    if (this.activeName === name) {
+      this.activeName = [...this.namedLayers.keys()].at(-1);
+    }
+  }
+  layerText() {
+    if (this.namedLayers.size === 0)
+      return "Filaxis 命名层：（空——addLayer/layerInto 注册）";
+    const lines = [];
+    for (const h of this.namedLayers.values()) {
+      const d = h.driver;
+      const base = h.descriptor.driver === "local" ? `${os.hostname()}[local]` : layerDisplayName(h.descriptor);
+      const state = d.reconnecting === true ? " ↻连中" : d.layerShellGone ? " ⚠退化（内层 shell 已退出，勿在此层执行）" : d.alive === false ? " ⚠死（removeLayer 后按原参数重建）" : "";
+      const user = d.effectiveUser ? ` · ${d.effectiveUser}$` : "";
+      const mark = h.name === this.activeName ? " ◀ 默认" : "";
+      lines.push(`  ${h.name}: ${base}${user}${state}${mark}`);
+    }
+    return ["Filaxis 命名层（工具缺省落【默认层】；显式按名寻址任意层）：", ...lines].join(`
+`);
+  }
+  snapshot() {
+    return {
+      layers: [...this.namedLayers.values()].map((h) => ({ name: h.name, descriptor: h.descriptor })),
+      active: this.activeName
+    };
+  }
+  async restore(snap) {
+    for (const { name, descriptor } of snap.layers) {
+      if (this.namedLayers.has(name))
+        continue;
+      const driver = await this.connect(descriptor);
+      this.namedLayers.set(name, { name, descriptor: driver.descriptor, driver });
+    }
+    if (snap.active && this.namedLayers.has(snap.active))
+      this.activeName = snap.active;
+  }
+  assertNotDupName(name) {
+    if (this.namedLayers.has(name)) {
+      throw new Error(`层名 '${name}' 已占用（既有：${[...this.namedLayers.keys()].join(", ")}）——换名或先 removeLayer`);
+    }
+  }
+  requireLayer(name) {
+    const h = this.namedLayers.get(name);
+    if (!h) {
+      throw new Error(`层 '${name}' 不存在（既有：${[...this.namedLayers.keys()].join(", ") || "空"}）`);
+    }
+    return h;
+  }
+  isDriver(x) {
+    return typeof x.exec === "function";
+  }
+  async findIdentityHit(descriptor) {
+    if (enterStepsOf(descriptor.config ?? {}).length > 0)
+      return;
+    const dest = layerPathIdentities(descriptor).at(-1);
+    if (!dest)
+      return;
+    return this.findIdentityHopHit(dest);
+  }
+  async findIdentityHopHit(dest) {
+    const destId = await resolveSshIdentity(dest);
+    if (!destId || destId.startsWith("unresolved:")) {
+      return;
+    }
+    for (const h of this.namedLayers.values()) {
+      if (enterStepsOf(h.descriptor.config ?? {}).length > 0)
+        continue;
+      const path = layerPathIdentities(h.descriptor);
+      for (let i = 0;i < path.length; i++) {
+        if (await resolveSshIdentity(path[i]) === destId) {
+          return { handle: h, terminal: i === path.length - 1 };
+        }
+      }
+    }
+    return;
+  }
+  async verifyLanding(hit, expectedHost) {
+    if (!expectedHost)
+      return true;
+    const d = hit.driver;
+    if (typeof d.exec !== "function")
+      return true;
+    try {
+      hit.actualHostname ??= ((await d.exec("hostname")).stdout || "").trim().split(`
+`).pop() || "";
+    } catch {
+      return false;
+    }
+    const actual = hit.actualHostname;
+    return Boolean(actual) && (actual.includes(expectedHost) || expectedHost.includes(actual));
+  }
   async features() {
     if (this.featuresCache)
       return this.featuresCache;
@@ -3573,31 +3757,12 @@ 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;
-}
+var shaCmdOf = (f) => `{ sha256sum ${f} 2>/dev/null || sha256 -q ${f} 2>/dev/null || openssl dgst -sha256 ${f} 2>/dev/null | tail -1; } | head -c 12`;
 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 readCmd = `${statCmdOf(qp)}; ${shaCmdOf(qp)}; echo __FXS__; ` + `printf ZmlsYXhpcw== | base64 -d 2>/dev/null; echo __FXD__; base64 < ${qp} 2>/dev/null`;
   const r = await drv.exec(readCmd, { timeoutMs: 30000 });
-  const [stampPart, b64Part] = (r.stdout || "").split("__FXS__");
+  const [stampPart, restPart] = (r.stdout || "").split("__FXS__");
   const originStampRaw = (stampPart ?? "").trim();
   const originLines = originStampRaw.split(/\n/);
   const statStamp = (originLines[0] ?? "").trim();
@@ -3612,7 +3777,9 @@ async function editFile(drv, path, oldStr, newStr, opts = {}) {
   };
   if (!origin.size || !shaStamp)
     throw new Error(`文件不存在或指纹异常: ${path}（${originStampRaw}）`);
-  const content0 = Buffer.from((b64Part ?? "").replace(/\s+/g, ""), "base64").toString("utf-8");
+  const [decPart, b64Part = ""] = (restPart ?? "").split("__FXD__");
+  const dec = (decPart ?? "").trim() === "filaxis" ? "base64 -d" : "base64 -D";
+  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} 字符）`);
@@ -3625,7 +3792,7 @@ async function editFile(drv, path, oldStr, newStr, opts = {}) {
   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 cmd = `if [ "$(${statCmdOf(qp)})" = "${statStamp}" ] && ` + `[ "$(${shaCmdOf(qp)})" = "${shaStamp}" ]; then ` + `printf %s ${q5(newB64)} | ${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")) {
@@ -3680,7 +3847,8 @@ var TOOL_DEFS = [
         type: "object",
         properties: {
           command: { type: "string", description: "shell 命令" },
-          timeout_ms: { type: "number", description: "超时毫秒（缺省 120000）" }
+          timeout_ms: { type: "number", description: "超时毫秒（缺省 120000）" },
+          layer: { type: "string", description: "目标层名（缺省=默认层——最近 push_ssh/push_into 的层）" }
         },
         required: ["command"]
       }
@@ -3697,7 +3865,8 @@ var TOOL_DEFS = [
           command: { type: "string", description: "长跑命令" },
           ready_marker: { type: "string", description: "就绪标记（如 'listening on'）" },
           error_pattern: { type: "string", description: "错误模式（命中即收摊）" },
-          name: { type: "string", description: "会话名（人读前缀）" }
+          name: { type: "string", description: "会话名（人读前缀）" },
+          layer: { type: "string", description: "目标层名（缺省=默认层）" }
         },
         required: ["command"]
       }
@@ -3725,7 +3894,8 @@ var TOOL_DEFS = [
       parameters: {
         type: "object",
         properties: {
-          path: { type: "string" }
+          path: { type: "string" },
+          layer: { type: "string", description: "目标层名（缺省=默认层）" }
         },
         required: ["path"]
       }
@@ -3742,7 +3912,8 @@ var TOOL_DEFS = [
           path: { type: "string" },
           old: { type: "string", description: "待替换片段（含足够上下文唯一）" },
           new: { type: "string" },
-          all: { type: "boolean", description: "多处命中全替换（缺省报错）" }
+          all: { type: "boolean", description: "多处命中全替换（缺省报错）" },
+          layer: { type: "string", description: "目标层名（缺省=默认层）" }
         },
         required: ["path", "old", "new"]
       }
@@ -3759,22 +3930,87 @@ var TOOL_DEFS = [
           command: { type: "string" },
           duration_ms: { type: "number", description: "观察时长（缺省 8000）" },
           stream: { type: "string", enum: ["stdout", "stderr", "both"], description: "流过滤（缺省 both）" },
-          name: { type: "string" }
+          name: { type: "string" },
+          layer: { type: "string", description: "目标层名（缺省=默认层）" }
         },
         required: ["command"]
       }
     }
+  },
+  {
+    type: "function",
+    function: {
+      name: "push_ssh",
+      description: "建立命名 ssh 层（成为默认层——后续工具缺省落它）。同落点幂等复用（reused=true 返回既有层，" + "不重复建连）+ 落点校验（宁重连不错主机）。跳板传 jump（-J 不占层）。",
+      parameters: {
+        type: "object",
+        properties: {
+          host: { type: "string", description: "目标主机（user@host 或 ssh config 别名）" },
+          port: { type: "number", description: "SSH 端口（非 22 时指定）" },
+          user: { type: "string", description: "登录用户名" },
+          key: { type: "string", description: "私钥文件路径（-i）" },
+          jump: { type: "string", description: "跳板（-J：途径机不占层）" },
+          name: { type: "string", description: "层名（缺省=host；注册表内唯一，显式寻址用）" }
+        },
+        required: ["host"]
+      }
+    }
+  },
+  {
+    type: "function",
+    function: {
+      name: "push_into",
+      description: "从默认层（或 from 指定层）进入内层 shell（docker exec -i <ctr> sh / kubectl exec 等）——" + "enter 管线全量继承追加（父层 docker→再 su 不丢）。新层成为默认层。需 ssh 层为源。",
+      parameters: {
+        type: "object",
+        properties: {
+          enter_cmd: { type: "string", description: '进入命令，如 "docker exec -i web sh"' },
+          label: { type: "string", description: "层显示标签" },
+          from: { type: "string", description: "源层名（缺省=默认层）" },
+          name: { type: "string", description: "层名（缺省=label）" }
+        },
+        required: ["enter_cmd"]
+      }
+    }
+  },
+  {
+    type: "function",
+    function: {
+      name: "list_layers",
+      description: "列出全部命名层（链路/状态/有效用户/默认层标记）。死层/退化层有警示标注（removeLayer 后按原参数重建）。",
+      parameters: { type: "object", properties: {}, required: [] }
+    }
+  },
+  {
+    type: "function",
+    function: {
+      name: "remove_layer",
+      description: "移出命名层（缺省连接保留在指纹缓存——再建同层零成本；destroy=true 才真销毁连接）。",
+      parameters: {
+        type: "object",
+        properties: {
+          name: { type: "string", description: "层名" },
+          destroy: { type: "boolean", description: "真销毁连接（缺省 false=保留可复用）" }
+        },
+        required: ["name"]
+      }
+    }
   }
 ];
 function createAgentToolkit(stack, opts = {}) {
   const layer = opts.driver ? Promise.resolve(opts.driver) : stack.connect(opts.descriptor ?? { driver: "local" });
   const readyTimeoutMs = opts.readyTimeoutMs ?? 15000;
+  const resolveDrv = async (layerName) => {
+    if (layerName)
+      return stack.layer(layerName).driver;
+    return stack.active ?? await layer;
+  };
   return {
     tools: TOOL_DEFS,
     layer,
     handlers: {
-      async run_command({ command, timeout_ms }) {
-        const drv = await layer;
+      async run_command({ command, timeout_ms, layer: layerName }) {
+        const drv = await resolveDrv(layerName);
         const r = await drv.exec(command, { timeoutMs: timeout_ms });
         return {
           stdout: r.stdout,
@@ -3783,8 +4019,8 @@ function createAgentToolkit(stack, opts = {}) {
           effective_user: r.effectiveUser
         };
       },
-      async spawn_and_observe({ command, ready_marker, error_pattern, name }) {
-        const drv = await layer;
+      async spawn_and_observe({ command, ready_marker, error_pattern, name, layer: layerName }) {
+        const drv = await resolveDrv(layerName);
         const h = await drv.execSession(command, name ? { name } : undefined);
         if (error_pattern) {
           drv.watchSession(h.sessionId, { pattern: error_pattern, once: false, thenStop: true });
@@ -3809,8 +4045,8 @@ function createAgentToolkit(stack, opts = {}) {
         }
         return { session_id: h.sessionId, log_base: h.logBase, note };
       },
-      async read_file({ path }) {
-        const drv = await layer;
+      async read_file({ path, layer: layerName }) {
+        const drv = await resolveDrv(layerName);
         if (!drv.fs.stat)
           throw new Error("该层不支持 read_file 的元数据（fs.stat 缺席）");
         const st = await drv.fs.stat(path);
@@ -3819,13 +4055,13 @@ function createAgentToolkit(stack, opts = {}) {
         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;
+      async edit_file({ path, old, new: newStr, all, layer: layerName }) {
+        const drv = await resolveDrv(layerName);
         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;
+      async observe_stream({ command, duration_ms, stream, name, layer: layerName }) {
+        const drv = await resolveDrv(layerName);
         const h = await drv.execSession(command, name ? { name } : undefined);
         const dur = duration_ms ?? 8000;
         await new Promise((r) => setTimeout(r, dur));
@@ -3837,6 +4073,49 @@ function createAgentToolkit(stack, opts = {}) {
         });
         return { session_id: h.sessionId, lines: filtered };
       },
+      async push_ssh({ host, port, user, key, jump, name }) {
+        const connParams = {};
+        if (port != null)
+          connParams.port = Number(port);
+        if (user)
+          connParams.user = String(user);
+        if (key)
+          connParams.keyFile = String(key);
+        if (jump)
+          connParams.jump = String(jump);
+        const r = await stack.addLayer(name ?? String(host), {
+          driver: "ssh",
+          target: String(host),
+          config: Object.keys(connParams).length ? { connParams } : undefined
+        });
+        return {
+          layer: r.handle.name,
+          reused: r.reused,
+          reused_from: r.reusedFrom,
+          note: r.reused ? "落点已由既有层持有——幂等复用（未重复建连）" : "新层已建并成为默认层"
+        };
+      },
+      async push_into({ enter_cmd, label, from, name }) {
+        const srcName = from ?? stack.activeLayer?.name;
+        if (!srcName)
+          throw new Error("无源层——先 push_ssh 建层，或显式传 from");
+        const h = await stack.layerInto(srcName, name ?? label ?? enter_cmd.slice(0, 30), enter_cmd, { label });
+        return { layer: h.name, target: h.descriptor.target };
+      },
+      async list_layers(_args) {
+        return {
+          text: stack.layerText(),
+          layers: [...stack.layers.values()].map((h) => ({
+            name: h.name,
+            driver: h.descriptor.driver,
+            target: h.descriptor.target
+          }))
+        };
+      },
+      async remove_layer({ name, destroy }) {
+        await stack.removeLayer(name, { destroy });
+        return { removed: name };
+      },
       async stop_and_verify({ session_id }) {
         const drv = await layer;
         const r = await drv.stopSession(session_id);

package/dist/runtime-stack.d.ts

@@ -1,6 +1,7 @@
 import type { RuntimeDriver, RuntimeDescriptor } from "./driver.js";
 import { RuntimeFactory } from "./factory.js";
 import { EventBus } from "./events.js";
+import { type SshConnParams } from "./ssh-helpers.js";
 import type { SessionEvent } from "./session-types.js";
 import { type FilaxisLogger } from "./logger.js";
 export type FilaxisEvents = SessionEvent | {
@@ -24,6 +25,23 @@ export interface RuntimeStackOptions {
     logger?: FilaxisLogger;
     factory?: RuntimeFactory;
 }
+/** 命名层句柄（Paramiko 式「连接即句柄」的持有与寻址单元） */
+export interface LayerHandle {
+    /** 层名（注册表内唯一——显式寻址零歧义） */
+    name: string;
+    descriptor: RuntimeDescriptor;
+    driver: RuntimeDriver;
+    /** 落点校验缓存（hostname 实测——宁重连不错主机） */
+    actualHostname?: string;
+}
+/** 层注册表快照（descriptor 即可序列化层身份——可 JSON 落盘跨进程恢复） */
+export interface LayerSnapshot {
+    layers: Array<{
+        name: string;
+        descriptor: RuntimeDescriptor;
+    }>;
+    active?: string;
+}
 export declare class RuntimeStack {
     /** 进程级驱动缓存：同连接拓扑指纹复用既有连接（杜绝孤儿/重复建连） */
     private static driverCache;
@@ -35,7 +53,10 @@ export declare class RuntimeStack {
     /**
      * 连接拓扑指纹（净室移植自源版 driverKey，身份白名单投影）：
      * 显示标签/运行态缓存等非身份字段不进键——不把既有连接挤出缓存、不误建重复连接。
-     * 注：ssh 层的 enterSteps 管线属 ssh Transport 批次，届时并入 cfg 投影。
+     * 环境身份三列（源版同款）：pty 标志 + sshHops 逐跳链 + enters 进入管线（归一化——
+     * legacy enterCmd 与等价 enterPipeline 单步同键）。缺列后果：同 target/connParams
+     * 但进不同容器的两层指纹相同 → connect 复用错连接 → B 容器的命令跑进 A 容器
+     * （「执行环境即 Layer」的身份底线——平移时曾丢列，第十季检查补齐）。
      */
     static driverKey(d: RuntimeDescriptor): string;
     /** 建立层连接：指纹命中即复用（AC-07 连接计数语义） */
@@ -44,6 +65,67 @@ export declare class RuntimeStack {
     static evictDriver(d: RuntimeDescriptor): RuntimeDriver | undefined;
     /** 开放注册（透传 factory；AC-09 第三方 Transport 同权） */
     registerDriver(type: string, f: (descriptor: RuntimeDescriptor) => RuntimeDriver): void;
+    private namedLayers;
+    private activeName?;
+    /** 层注册表只读视图 */
+    get layers(): ReadonlyMap<string, LayerHandle>;
+    /** 默认层 driver（最近注册/setActive 的层；无层时 undefined——消费方自兜底） */
+    get active(): RuntimeDriver | undefined;
+    /** 默认层句柄（含层名；无层时 undefined） */
+    get activeLayer(): LayerHandle | undefined;
+    /**
+     * 注册命名层。descriptor 形态走 connect（指纹复用）+ 回环检测幂等；
+     * driver 形态直接登记现成句柄（pushChild/pushInto 派生产物、消费方自建连接）。
+     * 新层自动成为默认层。
+     */
+    addLayer(name: string, descriptorOrDriver: RuntimeDescriptor | RuntimeDriver): Promise<{
+        handle: LayerHandle;
+        reused: boolean;
+        reusedFrom?: string;
+    }>;
+    /** 从命名层派生进入层（docker exec/kubectl 等——enter 管线全量继承追加） */
+    layerInto(from: string, name: string, enterCmd: string, opts?: {
+        label?: string;
+    }): Promise<LayerHandle>;
+    /** 从命名层链式 ssh 派生子层（本层路径为前缀——途经继承；含回环检测幂等） */
+    sshInto(from: string, name: string, target: string, connParams?: SshConnParams): Promise<{
+        handle: LayerHandle;
+        reused: boolean;
+        reusedFrom?: string;
+    }>;
+    /** 按名取层（不存在时报错并附候选清单） */
+    layer(name: string): LayerHandle;
+    /** 设默认层（显式声明「接下来都在这层干」——无全局焦点指针，最近使用 + 显式声明双轨） */
+    setActive(name: string): LayerHandle;
+    /** 移出注册表（缺省连接保留在指纹缓存可复用；destroy=true 才真销毁） */
+    removeLayer(name: string, opts?: {
+        destroy?: boolean;
+    }): Promise<void>;
+    /** 层清单纯文本（零 ANSI/零表格——npm 零依赖红线；彩色表格留消费方） */
+    layerText(): string;
+    /** 层身份快照（可 JSON 落盘——跨进程恢复的凭证） */
+    snapshot(): LayerSnapshot;
+    /**
+     * 按快照重建（幂等：已在层的名字跳过）：tmux 层 terminalId 命中=零成本 re-attach
+     * （现场全保）；ssh 层=重握手 + enterPipeline 逐条重放（位置确定性恢复）。
+     */
+    restore(snap: LayerSnapshot): Promise<void>;
+    private assertNotDupName;
+    private requireLayer;
+    private isDriver;
+    /**
+     * descriptor 落点 identity（路径末节点）比对既有层全部路径节点。
+     * 判重边界（原版 push_ssh 语义忠实平移）：**只在无 enter 管线的纯 ssh 落点层之间**——
+     * enter 层（容器/内层 shell）的落点是容器而非宿主机，hop identity 管不到（enter 管线
+     * 不进 layerPathIdentities）：同宿主机两个不同容器层会撞 identity + hostname 同为宿主机
+     * → 误幂等返回错容器。enter 层的身份与复用归 driverKey（含 enters 三列）。
+     */
+    private findIdentityHit;
+    /** terminal=true：identity 命中在该层路径**末节点**（同落点构造性成立，免 hostname 探测）；
+     *  false：命中途经节点（identity 撞了中间跳——hostname 落点校验把关） */
+    private findIdentityHopHit;
+    /** 落点校验（宁重连不错主机）：命中层实测 hostname vs 期望 host——不符=identity 撞途经节点 */
+    private verifyLanding;
     /**
      * 能力探测（AC-02：降级不靠猜）。结果缓存至注册表变化。
      * Windows 无 ControlMaster → mux=false（自动退化直连为既定行为）。