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

package/src/runtime-stack.ts

@@ -8,9 +8,14 @@
  * - features() 能力探测（AC-02：降级不靠猜——mux/sftp/persistent 按平台与二进制探测）
  */
 import { spawn } from "node:child_process";
+import * as os from "node:os";
 import type { RuntimeDriver, RuntimeDescriptor } from "./driver.js";
 import { RuntimeFactory } from "./factory.js";
 import { EventBus } from "./events.js";
+import {
+    enterStepsOf, layerDisplayName, layerPathIdentities, resolveSshIdentity,
+    hopHost, type SshHop, type SshConnParams,
+} from "./ssh-helpers.js";
 import type { SessionEvent } from "./session-types.js";
 import { noopLogger, type FilaxisLogger } from "./logger.js";
 
@@ -34,6 +39,22 @@ export interface RuntimeStackOptions {
     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 class RuntimeStack {
     /** 进程级驱动缓存：同连接拓扑指纹复用既有连接（杜绝孤儿/重复建连） */
     private static driverCache = new Map<string, RuntimeDriver>();
@@ -51,7 +72,10 @@ export 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 {
         const c = (d.config ?? {}) as Record<string, unknown>;
@@ -62,12 +86,15 @@ export 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,
             },
         });
     }
@@ -101,6 +128,267 @@ export class RuntimeStack {
         this.featuresCache = null;
     }
 
+    // ══════════ 命名层注册表（第十季 Layer 渗透定案——零破坏纯增量） ══════════
+    // 设计拍板：牵丝出身 Paramiko 式「连接即句柄」——栈/焦点弱化为消费方心智
+    //（Aethelum 垫片自带全局焦点栈），SDK 只补「句柄的持有与寻址」：
+    //   - 命名注册：名字唯一=零歧义（子串匹配/焦点切换留给消费方）
+    //   - 派生：pushChild/pushInto（ssh PTY 原语，派生即 init）——父子关系由
+    //     descriptor 继承天然记录（connParams/sshHops/enterPipeline 全量继承）
+    //   - 回环检测幂等返回：同落点 identity 命中 → 返回既有层 reused:true（原版
+    //     push_ssh 判重语义的 Paramiko 化——报错是栈时代的脾气）+ 落点校验
+    //     （hostname 实测 vs 期望，不符=撞了途经节点 → 拒绝，宁重连不错主机）
+    //   - snapshot/restore：descriptor 即层身份（tmux 层 terminalId 零成本
+    //     re-attach 现场全保；ssh 层重握手 + enterPipeline 逐条重放=位置确定性恢复）
+
+    private namedLayers = new Map<string, LayerHandle>();
+    private activeName?: string;
+
+    /** 层注册表只读视图 */
+    get layers(): ReadonlyMap<string, LayerHandle> { return this.namedLayers; }
+
+    /** 默认层 driver（最近注册/setActive 的层；无层时 undefined——消费方自兜底） */
+    get active(): RuntimeDriver | undefined {
+        return this.activeName ? this.namedLayers.get(this.activeName)?.driver : undefined;
+    }
+
+    /** 默认层句柄（含层名；无层时 undefined） */
+    get activeLayer(): LayerHandle | undefined {
+        return this.activeName ? this.namedLayers.get(this.activeName) : undefined;
+    }
+
+    /**
+     * 注册命名层。descriptor 形态走 connect（指纹复用）+ 回环检测幂等；
+     * driver 形态直接登记现成句柄（pushChild/pushInto 派生产物、消费方自建连接）。
+     * 新层自动成为默认层。
+     */
+    async addLayer(
+        name: string,
+        descriptorOrDriver: RuntimeDescriptor | RuntimeDriver,
+    ): Promise<{ handle: LayerHandle; reused: boolean; reusedFrom?: string }> {
+        this.assertNotDupName(name);
+        if (this.isDriver(descriptorOrDriver)) {
+            const driver = descriptorOrDriver;
+            const handle: LayerHandle = { name, descriptor: driver.descriptor, driver };
+            this.namedLayers.set(name, handle);
+            this.activeName = name;
+            return { handle, reused: false };
+        }
+        const descriptor = descriptorOrDriver;
+        // 回环检测幂等（descriptor 形态）：新落点 identity ∈ 既有层路径 identity 集。
+        // 末节点命中=同落点构造性成立（canonical identity 相同）→ 直接复用；
+        // 途经节点命中（identity 撞了某层的中间跳）→ hostname 落点校验把关（宁重连不错主机）
+        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: LayerHandle = { name, descriptor: driver.descriptor, driver };
+        this.namedLayers.set(name, handle);
+        this.activeName = name;
+        return { handle, reused: false };
+    }
+
+    /** 从命名层派生进入层（docker exec/kubectl 等——enter 管线全量继承追加） */
+    async layerInto(from: string, name: string, enterCmd: string, opts: { label?: string } = {}): Promise<LayerHandle> {
+        this.assertNotDupName(name);
+        const src = this.requireLayer(from);
+        const pushInto = (src.driver as unknown as {
+            pushInto?: (cmd: string, label: string) => Promise<RuntimeDriver>;
+        }).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: LayerHandle = { name, descriptor: driver.descriptor, driver };
+        this.namedLayers.set(name, handle);
+        this.activeName = name;
+        return handle;
+    }
+
+    /** 从命名层链式 ssh 派生子层（本层路径为前缀——途经继承；含回环检测幂等） */
+    async sshInto(
+        from: string,
+        name: string,
+        target: string,
+        connParams?: SshConnParams,
+    ): Promise<{ handle: LayerHandle; reused: boolean; reusedFrom?: string }> {
+        this.assertNotDupName(name);
+        const src = this.requireLayer(from);
+        const hop: SshHop = connParams ? { host: target, conn: connParams } : target;
+        // 回环检测幂等（链式派生落点=新 hop；末节点命中直接复用，途经命中 hostname 把关）
+        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 as unknown as {
+            pushChild?: (hop: SshHop) => Promise<RuntimeDriver>;
+        }).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: LayerHandle = { name, descriptor: driver.descriptor, driver };
+        this.namedLayers.set(name, handle);
+        this.activeName = name;
+        return { handle, reused: false };
+    }
+
+    /** 按名取层（不存在时报错并附候选清单） */
+    layer(name: string): LayerHandle {
+        return this.requireLayer(name);
+    }
+
+    /** 设默认层（显式声明「接下来都在这层干」——无全局焦点指针，最近使用 + 显式声明双轨） */
+    setActive(name: string): LayerHandle {
+        const h = this.requireLayer(name);
+        this.activeName = name;
+        return h;
+    }
+
+    /** 移出注册表（缺省连接保留在指纹缓存可复用；destroy=true 才真销毁） */
+    async removeLayer(name: string, opts: { destroy?: boolean } = {}): Promise<void> {
+        const h = this.requireLayer(name);
+        this.namedLayers.delete(name);
+        if (opts.destroy) {
+            RuntimeStack.evictDriver(h.descriptor);
+            await h.driver.destroy().catch(() => undefined);
+        }
+        if (this.activeName === name) {
+            this.activeName = [...this.namedLayers.keys()].at(-1); // 回落最后注册层
+        }
+    }
+
+    /** 层清单纯文本（零 ANSI/零表格——npm 零依赖红线；彩色表格留消费方） */
+    layerText(): string {
+        if (this.namedLayers.size === 0) return "Filaxis 命名层：（空——addLayer/layerInto 注册）";
+        const lines: string[] = [];
+        for (const h of this.namedLayers.values()) {
+            const d = h.driver as unknown as {
+                alive?: boolean; layerShellGone?: unknown; reconnecting?: boolean; effectiveUser?: string;
+            };
+            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("\n");
+    }
+
+    /** 层身份快照（可 JSON 落盘——跨进程恢复的凭证） */
+    snapshot(): LayerSnapshot {
+        return {
+            layers: [...this.namedLayers.values()].map((h) => ({ name: h.name, descriptor: h.descriptor })),
+            active: this.activeName,
+        };
+    }
+
+    /**
+     * 按快照重建（幂等：已在层的名字跳过）：tmux 层 terminalId 命中=零成本 re-attach
+     * （现场全保）；ssh 层=重握手 + enterPipeline 逐条重放（位置确定性恢复）。
+     */
+    async restore(snap: LayerSnapshot): Promise<void> {
+        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;
+    }
+
+    // ── 注册表内部 ──
+
+    private assertNotDupName(name: string): void {
+        if (this.namedLayers.has(name)) {
+            throw new Error(`层名 '${name}' 已占用（既有：${[...this.namedLayers.keys()].join(", ")}）——换名或先 removeLayer`);
+        }
+    }
+
+    private requireLayer(name: string): LayerHandle {
+        const h = this.namedLayers.get(name);
+        if (!h) {
+            throw new Error(`层 '${name}' 不存在（既有：${[...this.namedLayers.keys()].join(", ") || "空"}）`);
+        }
+        return h;
+    }
+
+    private isDriver(x: RuntimeDescriptor | RuntimeDriver): x is RuntimeDriver {
+        return typeof (x as RuntimeDriver).exec === "function";
+    }
+
+    /**
+     * descriptor 落点 identity（路径末节点）比对既有层全部路径节点。
+     * 判重边界（原版 push_ssh 语义忠实平移）：**只在无 enter 管线的纯 ssh 落点层之间**——
+     * enter 层（容器/内层 shell）的落点是容器而非宿主机，hop identity 管不到（enter 管线
+     * 不进 layerPathIdentities）：同宿主机两个不同容器层会撞 identity + hostname 同为宿主机
+     * → 误幂等返回错容器。enter 层的身份与复用归 driverKey（含 enters 三列）。
+     */
+    private async findIdentityHit(descriptor: RuntimeDescriptor): Promise<{ handle: LayerHandle; terminal: boolean } | undefined> {
+        if (enterStepsOf((descriptor.config ?? {}) as Record<string, unknown>).length > 0) return undefined;
+        const dest = layerPathIdentities(descriptor).at(-1);
+        if (!dest) return undefined;
+        return this.findIdentityHopHit(dest);
+    }
+
+    /** terminal=true：identity 命中在该层路径**末节点**（同落点构造性成立，免 hostname 探测）；
+     *  false：命中途经节点（identity 撞了中间跳——hostname 落点校验把关） */
+    private async findIdentityHopHit(dest: SshHop): Promise<{ handle: LayerHandle; terminal: boolean } | undefined> {
+        const destId = await resolveSshIdentity(dest);
+        if (!destId || destId.startsWith("unresolved:")) {
+            // 解析不可达（DNS/离线）——identity 不可靠，跳过判重（建层失败由 connect 兜底）
+            return undefined;
+        }
+        for (const h of this.namedLayers.values()) {
+            if (enterStepsOf((h.descriptor.config ?? {}) as Record<string, unknown>).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 undefined;
+    }
+
+    /** 落点校验（宁重连不错主机）：命中层实测 hostname vs 期望 host——不符=identity 撞途经节点 */
+    private async verifyLanding(hit: LayerHandle, expectedHost: string): Promise<boolean> {
+        if (!expectedHost) return true;
+        const d = hit.driver as unknown as { exec?: (cmd: string) => Promise<{ stdout: string }> };
+        if (typeof d.exec !== "function") return true;
+        try {
+            hit.actualHostname ??= ((await d.exec("hostname")).stdout || "").trim().split("\n").pop() || "";
+        } catch {
+            return false; // 探测失败=不可核实——拒绝复用
+        }
+        const actual = hit.actualHostname;
+        return Boolean(actual) && (actual!.includes(expectedHost) || expectedHost.includes(actual!));
+    }
+
     /**
      * 能力探测（AC-02：降级不靠猜）。结果缓存至注册表变化。
      * Windows 无 ControlMaster → mux=false（自动退化直连为既定行为）。

package/src/ssh-pty-driver.ts

@@ -54,11 +54,13 @@ class PtyLink {
     onLayerFallback?: (evidence: string) => void;
     fallbackSeen?: string;
 
-    /** 进入步骤退出哨兵（本物理链独有 nonce + 步骤号；$RANDOM 展开值防回显伪造） */
+    /** 进入步骤退出哨兵（本物理链独有 nonce + 步骤号；$$ 展开 PID 防回显伪造——
+     *  POSIX 全 shell 通吃：$RANDOM 是 bash 特性，dash/busybox ash 下展开为空致哨兵
+     *  形态崩坏（CI 实锤：PTY 层 enter sh 握手 20s 超时）） */
     registerFallbackStep(): string {
         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: string[]): void {
@@ -107,7 +109,7 @@ class PtyLink {
         if (!this.pendingExitFailure) await this.waitQuiet();
         // 握手行顺带身份探测（冷启动锦囊：省一次独立 execChannel("id -un")——
         // Windows 下那次 exec 是第二次完整 SSH 握手，建层耗时近半在此）
-        this.send("stty -echo -ixon cols 500 rows 50; export PS1= PS2=; echo PTYRDY_$RANDOM$RANDOM_$(id -un 2>/dev/null)\n");
+        this.send("stty -echo -ixon cols 500 rows 50; export PS1= PS2=; echo PTYRDY_$$_$(id -un 2>/dev/null)\n");
         try {
             await new Promise<void>((resolve, reject) => {
                 const timer = setTimeout(() => reject(new Error(this.egressError(`PTYRDY 握手超时（20s）: ${what}`))), 20_000);
@@ -266,7 +268,8 @@ class PtyLink {
             }
             if (!this.ready) {
                 // 非行首锚定（容忍与提示符粘连）；字面回显的字面串不含数字与真实用户名，安全
-                // PTYRDY_$RANDOM 展开值 + 顺带 id -un（冷启动锦囊：握手即身份，省一整次独立 ssh 握手）
+                // PTYRDY_$$_ 展开值（$$=PID，POSIX 全 shell——$RANDOM 系 bash 特性）+ 顺带
+                // id -un（冷启动锦囊：握手即身份，省一整次独立 ssh 握手）
                 const m = line.match(/PTYRDY_(\d+)(?:_([A-Za-z0-9._-]+))?/);
                 if (m) {
                     if (m[2]) this.handshakeUser = m[2]; // 本握手步（hop/enter/终层）的登录身份