@syrkos/filaxis 0.1.0-alpha.10

package/dist/layer-discovery.d.ts

@@ -0,0 +1,30 @@
+/**
+ * layer-discovery.ts — 异步层环境探测助手（冷启动锦囊之异步侧）
+ *
+ * 探测不阻塞建层：`discoverLayer(driver)` 返回 Promise，消费方（自发现编排/
+ * 观察窗）自行选择 fire-and-forget 或 await——建层与探测解耦。
+ * 两段式（stage1 快 / stage2 慢包导入）+ 蒸馏 + 落盘（stale 防漂移）+ 可选跳过 stage2。
+ */
+import { LayerEnvStore, type LayerEnvEntry, type LayerEnvironmentSpec } from "./layer-env.js";
+import type { RuntimeDriver } from "./driver.js";
+export interface DiscoverLayerOptions {
+    /** 落盘 Store（缺省内存态——探测结果仍返回不落盘） */
+    store?: LayerEnvStore;
+    /** 跳过 stage2（慢包导入——10s+；快路径/离线探测） */
+    skipStage2?: boolean;
+    /** stage2 独立超时（缺省 120s——由调用方驱动 exec 超时） */
+    stage2TimeoutMs?: number;
+    logger?: {
+        warn(msg: string): void;
+    };
+}
+export interface DiscoverLayerResult {
+    key: string;
+    spec: LayerEnvironmentSpec;
+    /** stage2 失败/跳过时如实标注（诚实不假装完整） */
+    probeNote?: string;
+    stale?: boolean;
+    entry?: LayerEnvEntry;
+}
+/** 异步探测一层环境：两段式 → 蒸馏 → （可选）落盘（漂移标 stale 不覆盖） */
+export declare function discoverLayer(driver: RuntimeDriver, opts?: DiscoverLayerOptions): Promise<DiscoverLayerResult>;

package/dist/layer-env.d.ts

@@ -0,0 +1,95 @@
+import type { RuntimeDescriptor } from "./driver.js";
+import { type SshConnParams } from "./ssh-helpers.js";
+/** 层环境规格（蒸馏快照——版本号/有无/型号，非全量 dump） */
+export interface LayerEnvironmentSpec {
+    os?: string;
+    kernel_arch?: string;
+    python?: string;
+    node?: string;
+    bun?: string;
+    java?: string;
+    cuda?: string;
+    gpu?: {
+        model: string;
+        vram_mb?: number;
+    };
+    docker?: boolean;
+    /** 关键包（present-only，"torch@2.4.0" 形态；匹配按 @ 前名） */
+    packages?: string[];
+}
+export interface SshHopLite {
+    host: string;
+    conn?: SshConnParams;
+}
+/** 重进路径投影（agent 据此零试错重进该层；环境身份不含 hops，重进路径含） */
+export interface LayerConnectionInfo {
+    driver: string;
+    target?: string;
+    conn?: SshConnParams;
+    hops?: SshHopLite[];
+    enters?: Array<{
+        cmd: string;
+        label?: string;
+    }>;
+    launch_cmd?: string;
+}
+/** 单层条目 */
+export interface LayerEnvEntry {
+    connection: LayerConnectionInfo;
+    environment: LayerEnvironmentSpec;
+    discovered_at: string;
+    /** 连接拓扑+环境快照 hash（漂移检测锚点：命中不一致 → stale 供重探，不自动覆盖） */
+    fingerprint: string;
+    /** 探测部分失败的说明（诚实标注，不假装完整） */
+    probe_note?: string;
+}
+export interface LayerEnvConfigFile {
+    layers: Record<string, LayerEnvEntry>;
+}
+/**
+ * 环境身份键（两键两职责之一：driverKey 管连接复用，本键管规格归属）：
+ * 落点[+端口]/enter 标签链——hops 不进键（同落点经不同路径=同一环境规格）。
+ */
+export declare function layerEnvKey(desc: RuntimeDescriptor): string;
+/** stage 1（快：亚秒级）——OS/架构/语言运行时/GPU/CUDA/docker；输出行 `fx_key=value` */
+export declare function buildProbeStage1(): string;
+/** stage 2（慢：python 冷导入 10s+）——关键包版本；有 GNU timeout 逐项 15s 兜底 */
+export declare function buildProbeStage2(): string;
+/** 关键包探测清单（扩展在此加行） */
+export declare const PROBE_PACKAGES: Array<{
+    key: string;
+    kind: "python" | "tool";
+    probe: string;
+    matchNames: string[];
+}>;
+/**
+ * 探测输出解析（纯函数）：`fx_key=value` 行 → 蒸馏规格。
+ * PTY 回显防御：回显行是未展开原文（值含 `$(`）——一律丢弃。
+ * 真实性红线：nvidia-smi 失败文案（驱动不通信）不得记为 GPU 型号。
+ */
+export declare function parseProbeOutput(stdout: string): LayerEnvironmentSpec;
+export declare class LayerEnvStore {
+    readonly path: string;
+    private cache;
+    constructor(path: string);
+    load(force?: boolean): Promise<LayerEnvConfigFile>;
+    /** 原子写：tmp + rename */
+    save(cfg: LayerEnvConfigFile): Promise<void>;
+    /** 写入/更新一层规格；漂移检测：指纹不一致标 stale 不自动覆盖（显式 force 才覆写） */
+    upsert(key: string, entry: LayerEnvEntry, force?: boolean): Promise<{
+        stale: boolean;
+    }>;
+}
+/** 连接投影（descriptor → LayerConnectionInfo；重进路径含 hops） */
+export declare function projectConnection(desc: RuntimeDescriptor): LayerConnectionInfo;
+/** 指纹：连接投影 + 环境快照 hash */
+export declare function layerFingerprint(conn: LayerConnectionInfo, spec: LayerEnvironmentSpec): string;
+export interface LayerMatchResult {
+    key: string;
+    entry: LayerEnvEntry;
+}
+/**
+ * 按需求匹配层：needs 形如 "gpu" / "torch"（包名） / "python>=3.12"（版本比较）。
+ * 全部 need 命中才入选；结果不排序（调用方按需排）。
+ */
+export declare function matchLayers(cfg: LayerEnvConfigFile, needs: string[]): LayerMatchResult[];

package/dist/local-driver.d.ts

@@ -0,0 +1,47 @@
+import type { RuntimeDriver, FileSystemDriver, ExecOptions, ExecResult, RuntimeDescriptor } from "./driver.js";
+import { LocalSessionManager } from "./local-session-manager.js";
+import type { SessionStartOptions, SessionHandleInfo, WatchOptions, ReadLogOptions } from "./session-types.js";
+import type { FilaxisLogger } from "./logger.js";
+export interface LocalDriverOptions {
+    /** 缺省工作目录 */
+    cwd?: string;
+    /** exec 状态/日志目录（缺省 os.tmpdir()/filaxis-exec） */
+    execDir?: string;
+    /** 执行 shell（缺省 bash） */
+    shell?: string;
+    logger?: FilaxisLogger;
+}
+/** 本地 Transport：进程内执行 + 原生 fs */
+export declare class LocalRuntimeDriver implements RuntimeDriver {
+    descriptor: RuntimeDescriptor;
+    fs: FileSystemDriver;
+    /** 会话式 exec 引擎（长跑 + 双文件落盘 + 热窗口 + watch） */
+    readonly sessions: LocalSessionManager;
+    private readonly defaultCwd?;
+    private readonly execDir;
+    private readonly shell;
+    private readonly log;
+    constructor(opts?: LocalDriverOptions);
+    /** 从 descriptor 构建（descriptor.cwd 初始化缺省工作目录） */
+    static fromDescriptor(descriptor: RuntimeDescriptor, fallbackCwd?: string): LocalRuntimeDriver;
+    init(): Promise<void>;
+    destroy(): Promise<void>;
+    getCwd(): Promise<string>;
+    getEnv(key: string): Promise<string | undefined>;
+    execSession(command: string, opts?: SessionStartOptions): Promise<SessionHandleInfo>;
+    tailSession(sessionId: string, lines?: number): Promise<string[]>;
+    readSessionLog(sessionId: string, opts?: ReadLogOptions): Promise<string>;
+    watchSession(sessionId: string, opts: WatchOptions): {
+        cancel(): void;
+    };
+    stopSession(sessionId: string): Promise<{
+        exitCode?: number | null;
+    }>;
+    listSessions(): Array<{
+        sessionId: string;
+        command: string;
+        running: boolean;
+        startedAt: number;
+    }>;
+    exec(command: string, options?: ExecOptions): Promise<ExecResult>;
+}

package/dist/local-session-manager.d.ts

@@ -0,0 +1,98 @@
+/**
+ * local-session-manager.ts — 本地长跑会话引擎（spawn 即返 + 双文件落盘 + 热窗口 + watcher）
+ *
+ * 净室平移自 Aethelum-Nexus `src/core/tools/runtime/session/local-session-manager.ts`
+ * （源锚点：Aethelum-Nexus dev @ 8977ff3 + fix 203a31c），按 REQ-0001 OSS 化改造：
+ * - 剥 SubstrateSecurity（执行网/沙箱属消费方策略——内核不越权预设安全边界）
+ * - SessionNotifier 队列投递 → 纯 onEvent 回调（内核零队列红线）
+ * - 落盘协议改双文件 `<logBase>.out` / `<logBase>.err`（FEAT-04——源版单文件混写）
+ * - 热窗口行对象带 stream 标记；聚合序为到达序（REQ §3.2 跨流顺序契约）
+ * - logger 可注入（缺省 noop）；日志目录/Shell 可配
+ *
+ * 终端语义：start 立即返回，进程长跑（无自动超时——长跑是特性）。
+ * 三级读取：文件全量（完整行落盘，1MB/行防爆 + 64MiB 总量硬顶）＋ 热窗口 ＋ watcher 推送。
+ * 生命周期：退出后句柄保留 ttlMs（默认 10min）供补读，TTL 后回收（timer unref 不撑进程）。
+ */
+import { type ChildProcess } from "node:child_process";
+import type { SessionStartOptions, SessionHandleInfo, SessionEvent, WatchOptions, ReadLogOptions } from "./session-types.js";
+import { type FilaxisLogger } from "./logger.js";
+export interface LocalSessionManagerOptions {
+    maxLines?: number;
+    maxLineBytes?: number;
+    /** 退出后句柄保留时长，默认 10min */
+    ttlMs?: number;
+    /** 会话日志目录（缺省 os.tmpdir()/filaxis-sessions） */
+    logDir?: string;
+    /** 执行 shell（缺省 "bash"；Windows 需 Git Bash/WSL 提供 bash——平台差异显式声明，不静默切换） */
+    shell?: string;
+    /** spawn 注入（缺省 node:child_process.spawn）——消费方沙箱包装/测试 mock 注入点 */
+    spawnImpl?: (cmd: string, argv: string[], opts: {
+        env: NodeJS.ProcessEnv;
+        cwd?: string;
+        stdio: unknown[];
+    }) => ChildProcess;
+    /** 可注入日志（缺省 noop——SDK 不替调用方往 stdout 喷日志） */
+    logger?: FilaxisLogger;
+}
+export declare class LocalSessionManager {
+    /** 事件回调（FEAT-09：消费方订阅点；缺省 noop）。回调异常被吞并记日志，不杀会话 */
+    onEvent: (ev: SessionEvent) => void;
+    private readonly entries;
+    private readonly maxLines;
+    private readonly maxLineBytes;
+    private readonly ttlMs;
+    private readonly logDir;
+    private readonly shell;
+    private readonly log;
+    private readonly spawnImpl;
+    constructor(opts?: LocalSessionManagerOptions);
+    /** 启动长跑会话：立即返回句柄 */
+    start(command: string, opts?: SessionStartOptions): Promise<SessionHandleInfo>;
+    /** 热窗口快照（最近 n 行 text 投影，默认 50；不碰盘） */
+    tail(sessionId: string, n?: number): string[];
+    /** 热窗口行对象（带 stream 标记——按流过滤消费） */
+    tailLines(sessionId: string, n?: number): import("./session-buffer.js").SessionLine[];
+    /** 文件全量/大范围读取（窗口滚出的内容在这里；双文件按流分读） */
+    readLog(sessionId: string, opts?: ReadLogOptions): Promise<string>;
+    /**
+     * 注册 watcher：**回溯匹配**热窗口已有行（spawn→watch 注册间隙的输出不漏——
+     * 与 ready() 同款语义；真实反馈：bash 冷启热后 GO 常在注册前已进窗口），
+     * 未命中再匹配未来行；命中 → onEvent("match")。
+     */
+    watch(sessionId: string, opts: WatchOptions): {
+        cancel(): void;
+    };
+    /**
+     * 就绪握手（FEAT-11 / AC-13）：先回溯扫描热窗口已有行（覆盖 spawn→ready
+     * 调用间隙已输出的标记——只监听增量则快输出进程必漏），未命中再监听增量行。
+     * 滚出感知有据：evictedCount===0 → 窗口历史完整，标记确定未出现，安心等待；
+     * >0 → 历史可能不完整，报「标记可能已滚出（可回查落盘日志）」而非死等。
+     * 超时 → 自动 stop 清理（不留孤儿进程）。
+     */
+    ready(sessionId: string, opts: {
+        pattern: string | RegExp;
+        timeoutMs: number;
+    }): Promise<{
+        matchedLine: string;
+    }>;
+    /**
+     * 停止会话：SIGTERM → 宽限 → SIGKILL 升级；随后短窗核实终态
+     * （FEAT-04：终止即请求、死亡须核实——close 事件到达=exited 带退出码；
+     *  核实窗内未死=stopped（SIGKILL 升级已安排），返回三态不静默当成功）
+     */
+    stop(sessionId: string): Promise<{
+        status: "exited" | "stopped" | "unknown";
+        exitCode?: number | null;
+    }>;
+    list(): Array<{
+        sessionId: string;
+        command: string;
+        running: boolean;
+        startedAt: number;
+    }>;
+    private require;
+    private ingestChunk;
+    private ingestLine;
+    private finalize;
+    private emit;
+}

package/dist/logger.d.ts

@@ -0,0 +1,12 @@
+/**
+ * logger.ts — 可注入日志接口（REQ-0001 §8.1：内核不绑任何 logger 实现）
+ *
+ * 消费方注入自己的 logger；缺省 noop（静默内核——SDK 不替调用方往 stdout 喷日志）。
+ */
+export interface FilaxisLogger {
+    debug(msg: string, ...args: unknown[]): void;
+    info(msg: string, ...args: unknown[]): void;
+    warn(msg: string, ...args: unknown[]): void;
+    error(msg: string, ...args: unknown[]): void;
+}
+export declare const noopLogger: FilaxisLogger;

package/dist/remote-session-manager.d.ts

@@ -0,0 +1,64 @@
+import type { SessionStartOptions, SessionHandleInfo, SessionEvent, WatchOptions, ReadLogOptions, SessionFinalStatus } from "./session-types.js";
+import type { ExecResult } from "./driver.js";
+import { type FilaxisLogger } from "./logger.js";
+export interface RemoteSessionManagerOptions {
+    /** 执行通道回调（远端命令落点） */
+    exec: (command: string) => Promise<Pick<ExecResult, "stdout" | "exitCode">>;
+    /** 远端会话日志目录（缺省 /tmp/filaxis-sessions） */
+    logDir?: string;
+    /** watcher 轮询间隔（默认 1500ms） */
+    pollMs?: number;
+    /** 无人消费且无 armed watcher 的回收 TTL（缺省 30min；时钟可注入测试） */
+    idleReapMs?: number;
+    logger?: FilaxisLogger;
+}
+export declare class RemoteSessionManager {
+    onEvent: (ev: SessionEvent) => void;
+    private entries;
+    private readonly exec;
+    private readonly logDir;
+    private readonly pollMs;
+    private readonly idleReapMs?;
+    private readonly log;
+    constructor(opts: RemoteSessionManagerOptions);
+    /** 启动远端长跑会话：nohup 双文件落盘 + 退出码文件；立即返回 */
+    start(command: string, opts?: SessionStartOptions): Promise<SessionHandleInfo>;
+    /** 热窗口快照（远端 tail .out） */
+    tail(sessionId: string, n?: number): Promise<string[]>;
+    /** 落盘日志读取（按流分读——FEAT-04 双文件） */
+    readLog(sessionId: string, opts?: ReadLogOptions): Promise<string>;
+    watch(sessionId: string, opts: WatchOptions): {
+        cancel(): void;
+    };
+    /**
+     * 行对象视图（双流：.out + .err 各取最近 n 行，行对象带 stream 标记）——
+     * observe 工具族用（第五季反馈 #2：此前仅 tail() 投影 stdout，stderr 漏读）
+     */
+    tailLines(sessionId: string, n?: number): Promise<Array<{
+        stream: "stdout" | "stderr";
+        text: string;
+    }>>;
+    /**
+     * 停止会话：发 kill -TERM → kill -0 核实。核实不可达（exec 抛错）→ 显式 unknown
+     * （终止即请求、死亡须核实——REQ §3.2 细则 6）。
+     */
+    stop(sessionId: string): Promise<{
+        status: SessionFinalStatus;
+        exitCode?: number | null;
+    }>;
+    list(): Array<{
+        sessionId: string;
+        command: string;
+        running: boolean;
+        startedAt: number;
+    }>;
+    /** 注意力衰减回收：无人消费且无 armed watcher 超 TTL → 自动收摊 + 事件广播（时钟可注入） */
+    reapIdle(now?: number, ttlMs?: number): void;
+    private require;
+    private startPolling;
+    /** 轮询：增量读 .out 喂 watcher；读 .code 判定终态 */
+    private poll;
+    private onLine;
+    private finalize;
+    private emit;
+}

package/dist/runtime-stack.d.ts

@@ -0,0 +1,52 @@
+import type { RuntimeDriver, RuntimeDescriptor } from "./driver.js";
+import { RuntimeFactory } from "./factory.js";
+import { EventBus } from "./events.js";
+import type { SessionEvent } from "./session-types.js";
+import { type FilaxisLogger } from "./logger.js";
+export type FilaxisEvents = SessionEvent | {
+    type: "layerState";
+    layer: string;
+    state: string;
+};
+export interface StackFeatures {
+    /** ControlMaster 多路复用可用（非 Windows + ssh 二进制存在） */
+    mux: boolean;
+    /** sftp 大文件快路径可用 */
+    sftp: boolean;
+    /** tmux 持久会话后端可用（缺席 → 持久层显式降级非持久） */
+    persistent: boolean;
+    /** 已注册 Transport 类型 */
+    transports: string[];
+    /** exec 通道 stderr 物理分离（平台默认；远端层的逐层标注属 driver 属性） */
+    stderrSeparated: boolean;
+}
+export interface RuntimeStackOptions {
+    logger?: FilaxisLogger;
+    factory?: RuntimeFactory;
+}
+export declare class RuntimeStack {
+    /** 进程级驱动缓存：同连接拓扑指纹复用既有连接（杜绝孤儿/重复建连） */
+    private static driverCache;
+    readonly events: EventBus<FilaxisEvents>;
+    private readonly factory;
+    private readonly log;
+    private featuresCache;
+    constructor(opts?: RuntimeStackOptions);
+    /**
+     * 连接拓扑指纹（净室移植自源版 driverKey，身份白名单投影）：
+     * 显示标签/运行态缓存等非身份字段不进键——不把既有连接挤出缓存、不误建重复连接。
+     * 注：ssh 层的 enterSteps 管线属 ssh Transport 批次，届时并入 cfg 投影。
+     */
+    static driverKey(d: RuntimeDescriptor): string;
+    /** 建立层连接：指纹命中即复用（AC-07 连接计数语义） */
+    connect(descriptor: RuntimeDescriptor, fallbackCwd?: string): Promise<RuntimeDriver>;
+    /** 逐出缓存（销毁归调用方——先 evict 再 destroy，避免销毁竞态复用） */
+    static evictDriver(d: RuntimeDescriptor): RuntimeDriver | undefined;
+    /** 开放注册（透传 factory；AC-09 第三方 Transport 同权） */
+    registerDriver(type: string, f: (descriptor: RuntimeDescriptor) => RuntimeDriver): void;
+    /**
+     * 能力探测（AC-02：降级不靠猜）。结果缓存至注册表变化。
+     * Windows 无 ControlMaster → mux=false（自动退化直连为既定行为）。
+     */
+    features(): Promise<StackFeatures>;
+}

package/dist/session-buffer.d.ts

@@ -0,0 +1,73 @@
+/**
+ * session-buffer.ts — 会话窗口基础件（纯逻辑，无 I/O）
+ *
+ * 净室平移自 Aethelum-Nexus `src/core/tools/runtime/session/session-buffer.ts`
+ * （源锚点：Aethelum-Nexus dev @ 8977ff3）。
+ *
+ * LineAssembler     字节流按 \n 组行（CRLF 剥 \r；partial 暂存；flush 收尾）
+ * OutputRingBuffer  热窗口：maxLines × maxLineBytes 截断；截断仅发生在窗口副本
+ *                   ——落盘文件侧由调用方写完整行
+ *                   OSS 扩展（REQ-0001 FEAT-11）：evictedCount 逐出计数——
+ *                   ready() 滚出感知「有据」的机制件（>0 = 窗口历史不完整）
+ * WatchRegistry     行级 watcher：string=子串 / RegExp 命中；once 默认；每会话上限
+ */
+export declare class LineAssembler {
+    private pending;
+    /** 喂入一段输出，返回其中已成行的部分（不含尾部的 partial） */
+    feed(chunk: string): string[];
+    /** 进程退出时调用：无换行的残余强制成行 */
+    flush(): string[];
+}
+export interface RingBufferOptions {
+    maxLines?: number;
+    maxLineBytes?: number;
+}
+/** 输出流标记（定义于 session-types，此处 re-export 便利用户） */
+export type { OutputStream } from "./session-types.js";
+import type { OutputStream } from "./session-types.js";
+/** 热窗口行对象：跨流聚合序为到达序（不承诺进程真实写入序——REQ §3.2） */
+export interface SessionLine {
+    stream: OutputStream;
+    text: string;
+}
+export declare class OutputRingBuffer {
+    private readonly maxLines;
+    private readonly maxLineBytes;
+    private lines;
+    private evictedLines;
+    constructor(opts?: RingBufferOptions);
+    /** 完整行入窗（窗口侧按 maxLineBytes 硬截断 text 含标记；文件侧由调用方写原行） */
+    push(line: SessionLine): void;
+    /** 最近 n 行的 text 投影（简洁消费） */
+    tail(n: number): string[];
+    /** 最近 n 行对象（带 stream 标记——FEAT-05 按流过滤迭代用） */
+    tailLines(n: number): SessionLine[];
+    /**
+     * 自创建以来被挤出窗口的行数（FEAT-11 滚出感知有据）：
+     * 0 = 窗口历史完整（标记若出现过必仍在窗内）；>0 = 历史可能不完整。
+     */
+    get evictedCount(): number;
+    /**
+     * 命中行 ± contextLines 的上下文切片（索引相对当前窗口，越界收敛）。
+     * 供 watcher 命中时组装通知上下文。
+     */
+    contextAround(index: number, contextLines: number): SessionLine[];
+    /** 命中行的窗口索引（按 text 查找；找不到回退末行）——watch 上下文组装用 */
+    indexOfLine(text: string): number;
+    get size(): number;
+}
+export interface WatcherSpec {
+    id: string;
+    pattern: string | RegExp;
+    /** 命中一次即摘除（默认 true） */
+    once?: boolean;
+}
+export declare class WatchRegistry {
+    private watchers;
+    add(spec: WatcherSpec): void;
+    /** 匹配一行，返回命中的 watcher id（once 的命中即摘除） */
+    match(line: string): string[];
+    cancel(id: string): boolean;
+    get size(): number;
+    private toRegex;
+}

package/dist/session-types.d.ts

@@ -0,0 +1,74 @@
+/**
+ * session-types.ts — 会话生命周期公共类型
+ *
+ * 净室平移自 Aethelum-Nexus `src/core/tools/runtime/session/local-session-manager.ts`
+ * 类型段（源锚点：Aethelum-Nexus dev @ 8977ff3），按 REQ-0001 OSS 化裁剪：
+ * - 剔除 notifyQueue（通知路由目标队列——消息队列路由属消费方桥，内核零队列红线）
+ * - ownerSessionId 保留（纯透传的归属上下文 ID，无业务语义负载）
+ * - 新增终态三态 SessionFinalStatus（FEAT-04：终止即请求、死亡须核实）
+ */
+export interface SessionStartOptions {
+    cwd?: string;
+    env?: Record<string, string>;
+    /** 会话名（sessionId 前缀，便于人读） */
+    name?: string;
+    /** 归属上下文 ID（事件通知时原样透传，供调用方关联自己的任务/请求） */
+    ownerSessionId?: string;
+}
+export interface SessionHandleInfo {
+    sessionId: string;
+    /** 落盘日志基名——实际双文件 `<logBase>.out` / `<logBase>.err`（FEAT-04 双文件协议） */
+    logBase: string;
+    pid?: number;
+}
+/**
+ * 会话终态三态（FEAT-04 / REQ §3.2 细则 6）：
+ * - exited   收到进程退出码（自然退出或终止后的确认退出）
+ * - stopped  终止请求已发出且清理核实通过
+ * - unknown  核实不可达（SSH 断线/网络分区/核实超时）——显式暴露，严禁当成功
+ */
+export type SessionFinalStatus = "exited" | "stopped" | "unknown";
+export interface SessionFinalState {
+    status: SessionFinalStatus;
+    exitCode?: number;
+}
+export type SessionEvent = {
+    type: "match";
+    sessionId: string;
+    watcherId: string;
+    pattern: string;
+    matchedLine: string;
+    /** 命中行所属流（FEAT-04/05 双流标记） */
+    stream: "stdout" | "stderr";
+    context: string[];
+    /** 归属上下文（调用方透传） */
+    ownerSessionId?: string;
+} | {
+    type: "exit";
+    sessionId: string;
+    exitCode: number | null;
+    lastLines: string[];
+    ownerSessionId?: string;
+};
+export interface WatchOptions {
+    pattern: string | RegExp;
+    /** 命中携带 命中行 ± N 行，默认 5 */
+    contextLines?: number;
+    /** 命中一次即摘除（默认 true） */
+    once?: boolean;
+    /**
+     * 命中即收摊：watcher 命中后自动 stop 会话——「观察对象结束 → 观察者退场」
+     * 从模型自觉变机制。观察型会话（tail -f 等永不退出的流）尤其需要，防遗忘泄漏。
+     */
+    thenStop?: boolean;
+}
+/** 输出流标记（FEAT-04/05：双流行对象——stdout/stderr 物理分离） */
+export type OutputStream = "stdout" | "stderr";
+export interface ReadLogOptions {
+    /** 取最近 N 行（缺省=全量） */
+    lines?: number;
+    /** 自文件头跳过 N 行 */
+    offsetLines?: number;
+    /** 读哪条流的落盘文件（FEAT-04 双文件协议；缺省 "stdout"） */
+    stream?: OutputStream;
+}

package/dist/shell-discovery.d.ts

@@ -0,0 +1,4 @@
+/** 发现本执行 shell（Linux/macOS 恒 "bash"） */
+export declare function resolveLocalShell(preferred?: string, log?: {
+    warn(msg: string): void;
+}): string;

package/dist/ssh-helpers.d.ts

@@ -0,0 +1,88 @@
+import type { RuntimeDescriptor } from "./driver.js";
+/** 端口透传（随层连接生命周期——层在隧道在，层断即撤） */
+export interface SshPortForward {
+    kind: "L" | "R" | "D";
+    port: number;
+    target?: string;
+    bind?: string;
+}
+export declare function renderForwardArg(f: SshPortForward): string;
+/** SSH 连接参数（结构化——渲染进 ssh 命令行与身份解析） */
+export interface SshConnParams {
+    user?: string;
+    port?: number;
+    keyFile?: string;
+    /** 跳板（-J；途径机不占栈层，由 ssh 自身代理） */
+    jump?: string;
+    forwards?: SshPortForward[];
+    /**
+     * 主机密钥策略（FEAT-12 / AC-12）：
+     * - "tofu"（缺省）——accept-new：首连自动收主机键，已知主机不匹配则拒绝
+     * - "strict"——StrictHostKeyChecking=yes：仅已知主机可连（配合 knownHostsFile 自定义信任锚）
+     */
+    hostKeyPolicy?: "tofu" | "strict";
+    /** 自定义 known_hosts 路径（UserKnownHostsFile；strict 模式的信任锚，缺省用户默认） */
+    knownHostsFile?: string;
+}
+export type SshHop = string | {
+    host: string;
+    conn?: SshConnParams;
+};
+export declare function hopHost(hop: SshHop): string;
+/** 人读形式：root@10.0.20.1:2222 -J jump -L8080→localhost:80 */
+export declare function hopLabel(hop: SshHop): string;
+/** ssh 命令行参数（spawn 数组与 ssh -G 解析共用） */
+export declare function sshArgsFor(hop: SshHop): string[];
+/** PTY 内单行发送所需的引用形式（私钥路径含空格等场景） */
+export declare function sshArgsQuoted(hop: SshHop): string;
+/** `~` 展开——spawn 参数数组不经过 shell，tilde 不会被展开（生产实证：公钥认证被拒 exit 255） */
+export declare function expandHomePath(p: string): string;
+/** 进入管线一步：建层时在链路末端落进内层 shell 的一条命令（docker exec / kubectl exec / su 等） */
+export interface EnterStep {
+    /** 进入命令原文（重放用） */
+    cmd: string;
+    /** 显示/层选择标签（缺省截取 cmd） */
+    label?: string;
+}
+/** 层的完整进入管线（归一化读取）：config.enterPipeline 为准；legacy enterCmd/enterLabel 就地归一 */
+export declare function enterStepsOf(config: Record<string, unknown> | undefined): EnterStep[];
+/**
+ * 自治建链选项（AC-12：host key 策略显式可配）：
+ * - ConnectTimeout=10（先于握手超时暴露真相）；ServerAlive 30×3（静默死亡 ~90s 内暴露）
+ * - hostKeyPolicy：tofu（缺省，accept-new）/ strict（yes + 可选 UserKnownHostsFile）
+ * 不加 BatchMode：禁交互提示会抹掉「等待输入」这个可感知状态——感知到 prompt 后
+ * 把原文直交调用方，而不是假装它不存在。
+ * 渲染只含密钥/known_hosts **路径**，永不包含其内容（AC-12 无泄漏红线）。
+ */
+export declare function autonomousSshOpts(conn?: SshConnParams): string[];
+/** root 层 spawn 全参数（含 -tt 强制 PTY） */
+export declare function rootSshSpawnArgs(destArgs: string[], conn?: SshConnParams): string[];
+/** PTY 内 hop 登录命令（选项语义与 root 对齐） */
+export declare function hopSshCommand(hop: SshHop): string;
+/** 「等待输入」感知特征：ssh 停在交互提示（密码/口令/yes-no）——检测到即失败交还原文 */
+export declare const SSH_INPUT_WAIT_RE: RegExp;
+/** 连接身份解析（ssh -G 本地解析不连网）；失败回退 unresolved: 前缀（视为不相同，不误拦） */
+export declare function resolveSshIdentity(hop: SshHop): Promise<string>;
+/** 层的完整途经身份链（target + hops），供回环检测 */
+export declare function layerPathIdentities(desc: RuntimeDescriptor): SshHop[];
+/** 层显示名（root 含端口/用户 + 途经链 + 进入标签） */
+export declare function layerDisplayName(desc: RuntimeDescriptor): string;
+/** 层显示标签（descriptor 链 + 容器短 ID 后缀） */
+export declare function layerDisplayLabel(d: {
+    descriptor: RuntimeDescriptor;
+    containerId?: string;
+}): string;
+export type ExecChannelRender = {
+    kind: "ok";
+    remoteArgs: string[];
+    stdinCmd: string;
+} | {
+    kind: "unreachable";
+    reason: string;
+    step: string;
+};
+export declare function renderExecChannel(steps: EnterStep[], command: string, opts: {
+    cwd?: string;
+    marker: string;
+    nonceWrapped: string;
+}): ExecChannelRender;