@syrkos/filaxis 0.1.0-alpha.10

package/dist/ssh-pty-driver.d.ts

@@ -0,0 +1,74 @@
+import type { RuntimeDriver, FileSystemDriver, ExecOptions, ExecResult, RuntimeDescriptor } from "./driver.js";
+import type { SessionStartOptions, SessionHandleInfo, WatchOptions, ReadLogOptions } from "./session-types.js";
+import { type SshHop } from "./ssh-helpers.js";
+import { RemoteSessionManager } from "./remote-session-manager.js";
+import { type FilaxisLogger } from "./logger.js";
+/** 层状态机（净室平移源语义）：connecting → active → idle → dead / degraded（退化） */
+export type LayerState = "connecting" | "active" | "idle" | "degraded" | "dead";
+export declare const LAYER_IDLE_THRESHOLD_MS = 10000;
+export declare function resolveLayerState(d: {
+    alive: boolean;
+    reconnecting?: boolean;
+    execInFlight?: boolean;
+    lastActivityAt?: number;
+    shellGone?: string;
+}, now?: number): LayerState;
+export interface SshPtyDriverOptions {
+    logger?: FilaxisLogger;
+}
+/** SSH Transport driver：每层一条独立多跳 PTY + 双通道 exec + 远端会话/文件 */
+export declare class SshPtyDriver implements RuntimeDriver {
+    readonly descriptor: RuntimeDescriptor;
+    readonly fs: FileSystemDriver;
+    readonly sessions: RemoteSessionManager;
+    private link;
+    private alive;
+    effectiveUser?: string;
+    layerShellGone?: string;
+    layerState: LayerState;
+    lastActivityAt: number;
+    execInFlight: boolean;
+    reconnecting: boolean;
+    private reconnectAttempts;
+    private readonly log;
+    private static readonly MAX_RECONNECT;
+    private static readonly RECONNECT_DELAYS_MS;
+    constructor(descriptor: RuntimeDescriptor, opts?: SshPtyDriverOptions);
+    currentState(): LayerState;
+    /** 建链：root PTY + 逐跳登录（sshHops）+ enterSteps 有序管线 + cwd 恢复 + 身份探测 */
+    init(): Promise<void>;
+    private assertNotFallenBack;
+    private scheduleReconnect;
+    private bindLink;
+    /** 派生 ssh 子层（独立连接）：本层路径为前缀，enter 管线显式清空 */
+    pushChild(hop: SshHop): Promise<SshPtyDriver>;
+    /** 派生组合层（docker-in-ssh 等）：父层管线全量继承再追加本步 */
+    pushInto(enterCmd: string, enterLabel: string): Promise<SshPtyDriver>;
+    exit(): Promise<void>;
+    destroy(): Promise<void>;
+    getCwd(): Promise<string>;
+    getEnv(key: string): Promise<string | undefined>;
+    /** 双通道 exec 分发（FEAT-03） */
+    exec(command: string, options?: ExecOptions): Promise<ExecResult>;
+    /**
+     * exec 通道（非 PTY，FEAT-03）：独立 ssh 进程（无 -tt），stdout/stderr 物理分离；
+     * enterSteps 以 stdin 管道重放（`… shell -s` 链，零嵌套引用）+ 层 cwd 拼装 +
+     * nonce marker 实测 effectiveUser（子 shell + $? 变量锁）。
+     */
+    private execChannel;
+    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(): {
+        sessionId: string;
+        command: string;
+        running: boolean;
+        startedAt: number;
+    }[];
+}

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

@@ -0,0 +1,83 @@
+import { type ChildProcess } from "node:child_process";
+import { type SessionLine } from "./session-buffer.js";
+import type { SessionEvent } from "./session-types.js";
+import { type FilaxisLogger } from "./logger.js";
+export interface StreamStartOptions {
+    name?: string;
+    ownerSessionId?: string;
+    /** 建立即挂 watcher（真流式命中——无需等轮询） */
+    watchPattern?: string;
+    watchOnce?: boolean;
+    contextLines?: number;
+    /** 观察窗流桥：每行对象原样回调（截断/入窗由窗侧自理） */
+    onLine?: (line: SessionLine) => void;
+    /** 流进程退出回调（观察窗 stale 语义） */
+    onExit?: (exitCode: number | null) => void;
+    /**
+     * TUI 屏桥（第五季灵感）：原始 chunk（含 ANSI 转义）喂 Vt100Screen 后回调
+     * snapshot（每 chunk 一帧——ncurses 增量包一包一帧）。观察 watch/htop/nvtop
+     * 这类无换行的全屏重绘流用 onScreen 截屏，行流用 onLine——两桥可并存。
+     */
+    onScreen?: (snap: string, frames: number) => void;
+}
+export type SpawnImpl = (cmd: string, argv: string[], opts: {
+    stdio: unknown[];
+}) => ChildProcess;
+export interface StreamSessionManagerOptions {
+    /** 禁用 ControlMaster（测试/平台受限） */
+    disableMux?: boolean;
+    /** 无人消费且无 armed watcher 的回收 TTL（默认 30min；测试可注入短值） */
+    idleReapMs?: number;
+    /** spawn 注入（缺省 node:child_process.spawn）——mock 全测关键 */
+    spawnImpl?: SpawnImpl;
+    /** mux socket 目录（缺省 os.tmpdir()/filaxis-stream-mux） */
+    muxDir?: string;
+    logger?: FilaxisLogger;
+}
+export declare class StreamSessionManager {
+    onEvent: (ev: SessionEvent) => void;
+    private entries;
+    private readonly destKey;
+    private readonly destArgs;
+    private readonly muxEnabled;
+    private readonly idleReapMs?;
+    private readonly spawnImpl;
+    private readonly muxDir;
+    private readonly log;
+    private static readonly DEFAULT_IDLE_REAP_MS;
+    constructor(destArgs: string[], opts?: StreamSessionManagerOptions);
+    /** ControlMaster flags：auto + Persist（首条流顺带建立主连接，无独立 -MNf 步骤） */
+    private muxFlags;
+    private ensureMuxDir;
+    /** 建立观察流：真流式子进程，stdout/stderr 双流逐行进 ring/watcher */
+    start(command: string, opts?: StreamStartOptions): Promise<{
+        sessionId: string;
+        name?: string;
+    }>;
+    /** 流式 watcher：行到达即匹配（真流，无轮询间隔） */
+    watch(sessionId: string, opts: {
+        pattern: string | RegExp;
+        once?: boolean;
+        contextLines?: number;
+    }): {
+        cancel(): void;
+    };
+    tail(sessionId: string, n?: number): string[];
+    /** 行对象视图（带 stream 标记——FEAT-05 按流过滤） */
+    tailLines(sessionId: string, n?: number): SessionLine[];
+    stop(sessionId: string): void;
+    list(): Array<{
+        sessionId: string;
+        name?: string;
+        command: string;
+        running: boolean;
+        idleMs: number;
+        armedWatchers: number;
+    }>;
+    /** 注意力衰减回收（时钟可注入——测试用）；armed watcher = 常驻注意力不回收 */
+    reapIdle(now?: number, ttlMs?: number): void;
+    private onChunk;
+    private releaseMaster;
+    private require;
+    private emit;
+}

package/dist/stream-window.d.ts

@@ -0,0 +1,124 @@
+/**
+ * stream-window.ts — 流式观察窗（远端拉模式流反转为本地推模式滚动窗）
+ *
+ * 净室平移自 Aethelum-Nexus `src/core/stream/stream-window.ts`
+ * （源锚 8977ff3）。OSS 化：logger 注入；引擎接 filaxis StreamSessionManager
+ * （onLine 行对象→text 投影）；local 窗 spawn 弃 shell:true（Windows cmd 会挂
+ * unix 命令）改 shell -c 与 exec 一致。
+ *
+ * 关键语义（源施工图定案，全保）：
+ * - 帧编号 per-window 单调递增，断连续编不归零（断点续读正确性依赖）
+ * - 双限缓冲：帧数环形覆盖（滚动=设计行为）+ 单帧字节截断
+ * - peek 三模式（last / window 时间窗 / since 增量），全部非破坏读
+ * - 多消费者游标：consumer_id → last_seq，互不干扰
+ * - 断流 stale 窗保留全部帧；重连续编；关窗收割流进程
+ * - 窗纯内存缓冲（不走消息路由——消费方自行桥接）
+ */
+import { type ChildProcess } from "node:child_process";
+import { StreamSessionManager } from "./stream-session-manager.js";
+import { type FilaxisLogger } from "./logger.js";
+export interface StreamFrame {
+    seq: number;
+    /** 帧到达本地时刻（时钟域统一本地） */
+    ts: number;
+    text: string;
+}
+export interface PeekResult {
+    name: string;
+    oldestSeq: number;
+    newestSeq: number;
+    stale: boolean;
+    frames: StreamFrame[];
+    /** since 模式且中间发生环形覆盖时置 true（空洞显式可见，不静默） */
+    gap?: boolean;
+}
+type Transport = {
+    kind: "local";
+    child: ChildProcess;
+} | {
+    kind: "remote";
+    manager: StreamSessionManager;
+    sessionId: string;
+};
+export declare class StreamWindow {
+    readonly name: string;
+    readonly layerAlias: string;
+    readonly source: string;
+    readonly command: string;
+    private readonly maxFrames;
+    private readonly maxLineBytes;
+    private frames;
+    private nextSeq;
+    private _stale;
+    private _closed;
+    private readonly consumers;
+    private transport;
+    private lastActivityAt;
+    constructor(name: string, layerAlias: string, source: string, command: string, maxFrames?: number, maxLineBytes?: number);
+    get stale(): boolean;
+    get closed(): boolean;
+    get frameCount(): number;
+    get oldestSeq(): number;
+    get newestSeq(): number;
+    get lastActiveAt(): number;
+    /** 行入窗（截断+环形覆盖；不更新消费者游标——游标只在 peek since 时推进） */
+    push(text: string): void;
+    /** 最近 n 帧 */
+    peekLast(n?: number): PeekResult;
+    /** 最近 ms 毫秒内的帧 */
+    peekWindow(ms: number): PeekResult;
+    /**
+     * 增量断点续读：返回 > sinceSeq 的帧（上限 n 兜底）。
+     * 带 consumerId 时推进该消费者游标；中间覆盖（oldestSeq > sinceSeq+1）置 gap。
+     */
+    peekSince(sinceSeq: number, n?: number, consumerId?: string): PeekResult;
+    /** 无状态读取消费者已知游标（未注册返回 0） */
+    consumerSeq(consumerId: string): number;
+    /** 流进程退出/断连 → stale（保留全部帧，seq 冻结在 nextSeq 上，重连续编） */
+    markStale(): void;
+    attachTransport(t: Transport): void;
+    /** 关窗：收割流进程 + 内容清空（由 Registry 除名） */
+    close(): void;
+    private snapshot;
+}
+export interface StreamWindowRegistryOptions {
+    /** 空引用窗延迟销毁 TTL（对齐 stream 注意力衰减语义） */
+    idleTtlMs?: number;
+    /** local 窗 shell（缺省 resolveLocalShell——与 exec 同源） */
+    shell?: string;
+    logger?: FilaxisLogger;
+}
+export declare class StreamWindowRegistry {
+    private readonly windows;
+    private readonly sweeper;
+    private readonly idleTtlMs;
+    private readonly shell;
+    private readonly log;
+    constructor(opts?: StreamWindowRegistryOptions);
+    /** 开窗（local 经 spawn shell -c；remote 经 StreamSessionManager 行桥） */
+    open(opts: {
+        name: string;
+        layerAlias?: string;
+        command: string;
+        maxFrames?: number;
+        maxLineBytes?: number;
+        manager?: StreamSessionManager;
+    }): Promise<StreamWindow>;
+    stop(name: string): void;
+    /** 通配聚合 peek：glob 如 "vm-ai:*"（* 与 ?；无通配=精确名） */
+    peek(pattern: string): StreamWindow[];
+    get(name: string): StreamWindow | undefined;
+    list(): Array<{
+        name: string;
+        layer: string;
+        frames: number;
+        stale: boolean;
+        command: string;
+    }>;
+    private require;
+    private matches;
+    private sweep;
+    dispose(): void;
+}
+export declare function getStreamWindowRegistry(): StreamWindowRegistry;
+export {};

package/dist/terminal/command-executer.d.ts

@@ -0,0 +1,73 @@
+import { type BufferStats } from "./output-buffer.js";
+import { type PromptPayload, type PromptResponder, type TerminalConfig } from "./types.js";
+import { type FilaxisLogger } from "../logger.js";
+export interface ProgressSnapshot {
+    tail: string;
+    stats: BufferStats;
+}
+export interface RunOptions {
+    timeoutMs?: number;
+    /** 交互响应者（密码/确认 Prompt——消费方注入；null=无交互能力） */
+    responder?: PromptResponder | null;
+    /** 流式回调：每次 capture 到新内容触发（原始 tail 快照，未剥 marker 噪声） */
+    onProgress?: (snapshot: ProgressSnapshot) => void;
+}
+export interface TerminalExecResult {
+    stdout: string;
+    exitCode: number;
+}
+/** 命令失败富错误：partialOutput 携带截至失败时刻的累积输出 */
+export declare class CommandExecError extends Error {
+    readonly partialOutput: string;
+    /** 超时/中断：远端终态未核实（"unknown"）——上层按未知处理，严禁当已清理 */
+    outcome?: "unknown";
+    constructor(message: string, partialOutput?: string, outcome?: "unknown");
+}
+/** 二进制嗅探：前 N 字节 null 占比 >10% 判 binary（PTY 偶发 NUL 容忍） */
+export declare function isBinaryChunk(text: string): boolean;
+export interface CommandExecuterOptions {
+    config?: Partial<TerminalConfig>;
+    logger?: FilaxisLogger;
+}
+export declare class CommandExecuter {
+    private constructor();
+    private static cfg;
+    /** 已关回显的会话（每会话一次性 stty -echo——交互 shell 的命令回显不进 stdout） */
+    private static sttyOff;
+    /** per-session 命令链（审查问题 2：同会话命令必须串行——并发 send-keys 交错） */
+    private static chains;
+    /** 因终态不可确认被销毁的会话（自愈：重建后 has-session 探活即清除标记） */
+    private static deadSessions;
+    private static log;
+    /** 配置注入（SDK 组装期一次性；测试可覆盖） */
+    static configure(opts?: CommandExecuterOptions): void;
+    /**
+     * 在 tmux 会话中执行命令（四阶段 temporal isolation——审查问题 2 修复）：
+     * - **per-session 串行**：同会话命令排队，绝不并发 send-keys；
+     * - 超时（墙钟/不活动）= INTERRUPTING：发 C-c 杀远端前台任务，调用方立即
+     *   收 CommandExecError（挂 outcome:"unknown"）——但**会话锁不释放**；
+     * - DRAINING（仍在链内）：等自己的 marker 可信终态（上限 5s）才把会话交还
+     *   下一条命令；
+     * - 等不到终态 → kill-session 销毁 + 标记 dead（后续调用显式报错指引重建；
+     *   重建后探活自愈）——绝不定时强行复用。
+     */
+    static execute(id: string, command: string, opts?: RunOptions): Promise<TerminalExecResult>;
+    private static executeLocked;
+    /** 交互 Prompt 检测（末尾锚定，避免输出中段字样误判） */
+    static detectPrompt(paneText: string, terminalId: string): PromptPayload | null;
+    private static parseExitCode;
+    /** 增量 delta：新快照以上次为前缀 → 尾部；归一 \r 后再试；漂移则整屏（宁重复不丢） */
+    private static computeDelta;
+    /** 剥 marker/echo 噪声得纯净 stdout（marker 行起全停） */
+    private static stripMarkerNoise;
+    private static extractPartialOutput;
+    private static sendKeys;
+    /**
+     * DRAINING（审查问题 2）：超时 ^C 后等可信回提示符证据（有上限）。
+     * 两凭证任一先到：① 原命令 marker（^C 后 trap/echo 幸存时）② 独立探测哨兵
+     * drainToken（^C 之后新发的 echo——^C 杀整行 job 也不影响它）。
+     * 链内调用——串行保证下一条命令在本方法返回/超时后才接手会话。
+     */
+    private static waitForDrain;
+    private static capturePane;
+}

package/dist/terminal/output-buffer.d.ts

@@ -0,0 +1,49 @@
+/**
+ * terminal/output-buffer.ts — 三级输出缓冲（净室平移，源锚 8977ff3，纯逻辑零 I/O）
+ *
+ * pending（增量数组）/ aggregated（留尾串）/ tail（快照）三级；游标读取以
+ * UTF-16 码元绝对偏移计，封顶裁头显式报断档（validFrom/lostChars）——
+ * 拒绝静默返回不连续内容。
+ */
+import type { OutputStream } from "./types.js";
+export interface BufferStats {
+    total: number;
+    truncated: boolean;
+}
+export type ReadLogResult = {
+    ok: boolean;
+    text: string;
+    nextOffset: number;
+    validFrom?: number;
+    lostChars?: number;
+};
+export interface BufferCaps {
+    pendingChars: number;
+    aggregatedChars: number;
+    tailChars: number;
+}
+export declare class OutputBuffer {
+    private pendingStdout;
+    private pendingStderr;
+    private aggregated;
+    private tail;
+    private totalOutputChars;
+    private truncated;
+    private baseOffset;
+    private readonly pendingCap;
+    private readonly aggregatedCap;
+    private readonly tailCap;
+    constructor(caps: BufferCaps);
+    append(chunk: string, stream?: OutputStream): void;
+    /** 取走并清空未读增量 */
+    drainPending(): string;
+    readTail(): string;
+    /** 分页读取（绝对偏移游标；游标过期显式报断档） */
+    readLog(offset?: number, limit?: number): ReadLogResult;
+    /** 便捷视图：丢失时前置断档提示行 */
+    readLogText(offset?: number, limit?: number): string;
+    get stats(): BufferStats;
+    hasPending(): boolean;
+    reset(): void;
+    private trimPending;
+}

package/dist/terminal/session-launcher.d.ts

@@ -0,0 +1,28 @@
+/**
+ * terminal/session-launcher.ts — 持久 tmux 会话启动器
+ * （净室平移，源锚 8977ff3；TerminalConfig 注入化）
+ *
+ * FR-1：customId 命中存活会话 → 复用返回同 id（跨进程重启恢复连接的语义）；
+ * 未知 driver 且无 launchCmd → 抛 /Unknown driver/；会话立即死亡 → 清 profile 抛带 hint 错。
+ * FR-9 第一道防线：launchCmd 前置 env_hardening_prefix 关交互 Prompt。
+ */
+import { SessionRegistry } from "./session-registry.js";
+import { type TerminalConfig } from "./types.js";
+import { type FilaxisLogger } from "../logger.js";
+export interface SessionLauncherOptions {
+    config?: Partial<TerminalConfig>;
+    logger?: FilaxisLogger;
+}
+export declare class SessionLauncher {
+    private readonly registry;
+    private readonly cfg;
+    private readonly log;
+    constructor(registry: SessionRegistry, opts?: SessionLauncherOptions);
+    /** 启动（或复用）一个持久 tmux 会话；返回存活会话 id */
+    launch(driver: string, target: string | undefined, config?: Record<string, unknown>, customId?: string): Promise<string>;
+    /** 已知 driver 快捷方式渲染（与 RuntimeDescriptor 注释一致） */
+    resolveLaunchCmd(driver: string, target: string | undefined, config?: Record<string, unknown>): string;
+    /** 存活轮询（远端 driver 更长 deadline + dead-streak 容忍瞬时抖动） */
+    private waitForAlive;
+    private diedHint;
+}

package/dist/terminal/session-registry.d.ts

@@ -0,0 +1,29 @@
+import { type FilaxisLogger } from "../logger.js";
+export interface TerminalProfile {
+    id: string;
+    driver: string;
+    target: string;
+    config?: Record<string, unknown>;
+    createdAt: number;
+}
+export type DirResolver = () => string;
+export declare class SessionRegistry {
+    private readonly dirResolver;
+    private readonly log;
+    private reconciledDirs;
+    constructor(dirResolver: DirResolver, log?: FilaxisLogger);
+    ensureDir(): Promise<void>;
+    /** 确保目录存在 + 每目录一次重连扫描（幂等；换目录=新一轮启动） */
+    init(): Promise<void>;
+    save(profile: TerminalProfile): Promise<void>;
+    /** 缺失返回 null（不抛） */
+    load(id: string): Promise<TerminalProfile | null>;
+    /** 幂等删除 */
+    remove(id: string): Promise<void>;
+    /** 启动重连扫描：存活会话保留（=重连），僵尸 profile 清理 */
+    reconcileOnStartup(): Promise<{
+        scanned: number;
+        kept: number;
+        removed: number;
+    }>;
+}

package/dist/terminal/tmux-invoker.d.ts

@@ -0,0 +1,8 @@
+import type { TmuxResult } from "./types.js";
+export declare class TmuxInvoker {
+    static invoke(args: string[]): Promise<TmuxResult>;
+    /** 软失败变体：非零退出码返回带 exitCode 的结果（has-session 的 1=不存在是合法语义） */
+    static tryInvoke(args: string[]): Promise<TmuxResult>;
+    /** tmux 是否可用（spawn 失败=未安装） */
+    static isAvailable(): Promise<boolean>;
+}

package/dist/terminal/types.d.ts

@@ -0,0 +1,56 @@
+/**
+ * terminal/types.ts — 持久会话子系统共享类型与默认配置
+ *
+ * 净室平移自 Aethelum-Nexus `src/core/tools/terminal/{types,config}.ts`
+ * （源锚 8977ff3）。OSS 化：ConfigLoader/Zod schema 依赖剥——TerminalConfig
+ * 变为注入式选项 + 本文件默认值（内核不绑任何配置装载器）。
+ */
+/** tmux CLI 单次调用结果（stdout/stderr 严格分离；非零退出码 reject 不吞错） */
+export interface TmuxResult {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+}
+export declare class TmuxError extends Error {
+    readonly args: string[];
+    readonly exitCode: number;
+    readonly stderr: string;
+    constructor(message: string, args: string[], exitCode: number, stderr: string);
+}
+/** 交互 Prompt 载荷（持久会话内检测到 Password/Confirm 等等待输入时） */
+export interface PromptPayload {
+    type: "CONFIRM";
+    title: string;
+    message: string;
+    metadata: {
+        terminalId: string;
+        prompt: string;
+        platform: "terminal";
+    };
+}
+/** 交互响应者：返回用户回复字符串，null 表示未作答（消费方自行适配 UI/IM） */
+export interface PromptResponder {
+    ask(payload: PromptPayload): Promise<string | null>;
+}
+export type OutputStream = "stdout" | "stderr";
+/** 持久会话子系统配置（注入式；默认值覆盖源 ConfigLoader schema 语义） */
+export interface TerminalConfig {
+    /** 前置环境加固前缀（关交互入口——GIT_TERMINAL_PROMPT/SSH_ASKPASS/PAGER） */
+    env_hardening_prefix: string;
+    spawn_max_wait_ms_local: number;
+    spawn_max_wait_ms_remote: number;
+    spawn_poll_ms: number;
+    command_timeout_ms: number;
+    /** 不活动超时（只杀哑不杀慢——有新输出即重置） */
+    no_output_timeout_ms: number;
+    poll_interval_ms: number;
+    capture_scrollback: number;
+    buffer_pending_chars: number;
+    buffer_aggregated_chars: number;
+    buffer_tail_chars: number;
+    /** 交互 Prompt 检测模式（多行正则，末尾锚定由 compile 保证） */
+    prompt_patterns: string[];
+}
+export declare const DEFAULT_TERMINAL_CONFIG: TerminalConfig;
+/** 把 prompt_patterns 源串编译成多行 OR 正则（末尾锚定 $；mi——大小写不敏感+多行） */
+export declare function compilePromptPatterns(patterns: string[]): RegExp;

package/dist/terminal-manager.d.ts

@@ -0,0 +1,30 @@
+import { type TerminalProfile } from "./terminal/session-registry.js";
+import { type RunOptions } from "./terminal/command-executer.js";
+import type { TerminalConfig } from "./terminal/types.js";
+import { type FilaxisLogger } from "./logger.js";
+export type { TerminalProfile } from "./terminal/session-registry.js";
+export interface TerminalManagerOptions {
+    /** profile 持久化目录（缺省 os.tmpdir()/filaxis-terminals） */
+    terminalDir?: string;
+    config?: Partial<TerminalConfig>;
+    logger?: FilaxisLogger;
+}
+export declare class TerminalManager {
+    private readonly registry;
+    private readonly launcher;
+    readonly terminalDir: string;
+    constructor(opts?: TerminalManagerOptions);
+    /** 确保目录存在 + 一次重连扫描（幂等） */
+    init(): Promise<void>;
+    /** 启动（或复用）持久 tmux 会话 */
+    spawnSession(driver: string, target: string | undefined, config?: Record<string, unknown>, customId?: string): Promise<string>;
+    /** 会话内执行命令（纯净 stdout + exitCode；第三参 number|RunOptions 多态） */
+    runCommand(id: string, command: string, timeoutMsOrOptions?: number | RunOptions): Promise<{
+        stdout: string;
+        exitCode: number;
+    }>;
+    /** 销毁会话 + 删 profile（best-effort：kill-session 失败不阻断） */
+    destroySession(id: string): Promise<void>;
+    /** 读 profile；缺失返回 null */
+    getSession(id: string): Promise<TerminalProfile | null>;
+}

package/dist/tmux-driver.d.ts

@@ -0,0 +1,49 @@
+/**
+ * tmux-driver.ts — 持久会话 Transport 适配层
+ * （净室平移自 Aethelum-Nexus tmux-driver.ts，源锚 8977ff3）
+ *
+ * OSS 化：剥 RuntimeProcessManager/RemoteSessionManager/TmuxFileSystem——
+ * fs 经 runCommand base64（方言适配接线 M2 批）；远端会话族沿用本文件
+ * nohup 会话语义（经 TerminalManager 会话 shell 执行）。
+ * terminalId 绑定 + cwd 恢复 + destroy 时 nohup 后台进程显式清理。
+ */
+import type { RuntimeDriver, FileSystemDriver, ExecOptions, ExecResult, RuntimeDescriptor } from "./driver.js";
+import { TerminalManager } from "./terminal-manager.js";
+import type { SessionStartOptions, SessionHandleInfo, WatchOptions, ReadLogOptions } from "./session-types.js";
+import { type FilaxisLogger } from "./logger.js";
+export interface TmuxDriverOptions {
+    terminalManager?: TerminalManager;
+    logger?: FilaxisLogger;
+}
+export declare class TmuxSessionDriver implements RuntimeDriver {
+    descriptor: RuntimeDescriptor;
+    fs: FileSystemDriver;
+    readonly terminal: TerminalManager;
+    private readonly log;
+    constructor(descriptor: RuntimeDescriptor, opts?: TmuxDriverOptions);
+    /** init：无 terminalId 则 spawn；有则验证存活（跨进程重连语义）；cwd 恢复 */
+    init(): Promise<void>;
+    /** 本实例启动的后台会话（sessionId 集合——destroy 只清理自己的，绝不扫目录误杀他层） */
+    private ownedSessions;
+    /** destroy：只停**本实例**启动的后台进程（审查问题 1：全目录扫杀会误杀同机其他
+     * Filaxis 实例/其他层的任务——/tmp/filaxis-sessions 是共享目录），再销毁会话 */
+    destroy(): Promise<void>;
+    exec(command: string, options?: ExecOptions): Promise<ExecResult>;
+    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;
+    }>;
+}

package/dist/vt100-screen.d.ts

@@ -0,0 +1,46 @@
+/**
+ * vt100-screen.ts — 轻量 VT100 虚拟屏幕（TUI 全屏程序字符级截屏）
+ *
+ * 第五季观察窗专项实测灵感：`watch/htop/nvtop` 等 ncurses 程序按
+ * `\x1b[row;colH` 光标定位增量重绘、**不输出换行**——行模式对它退化（数据在但
+ * 不可读）。本件是可选的终端仿真：feed 原始字节流 → snapshot 字符级高清截屏。
+ *
+ * 纯逻辑零 I/O 零依赖；手写状态机零正则。转义序列子集（观察够用）：
+ * CUP/HVP（光标定位）、ED/EL（清屏/清行）、CUU/CUD/CUF/CUB（光标移动）、
+ * LF（换行+滚屏）/CR/BS/TAB、SGR 忽略、OSC 忽略；其余序列保守忽略。
+ * Autowrap：超行宽折到下一行（VT100 语义——ncurses 假设终端宽=实际宽，
+ * 建议 cols 给足）。
+ */
+export interface Vt100ScreenOptions {
+    rows?: number;
+    cols?: number;
+}
+export declare class Vt100Screen {
+    private rows;
+    private curRow;
+    private curCol;
+    /** 解析状态：0=normal 1=esc 2=csi 3=osc */
+    private state;
+    private csiBuf;
+    private oscBuf;
+    private _frames;
+    constructor(opts?: Vt100ScreenOptions);
+    /** 喂原始字节流（含转义序列） */
+    feed(chunk: string): void;
+    /** 字符级高清截屏（行尾空白裁剪） */
+    snapshot(): string;
+    get cursor(): {
+        row: number;
+        col: number;
+    };
+    /** 已喂 chunk 数（帧计数——TUI 增量包一包一帧） */
+    get frames(): number;
+    private put;
+    private csiDispatch;
+    private writeChar;
+    private lineFeed;
+    private moveTo;
+    /** endCol=-1 表示到行尾；endRow 含 */
+    private clearRegion;
+    private clearAll;
+}