@syrkos/filaxis 0.1.0-alpha.10

package/src/terminal/session-registry.ts

@@ -0,0 +1,98 @@
+/**
+ * terminal/session-registry.ts — TerminalProfile 持久化与重连扫描
+ * （净室平移，源锚 8977ff3；logger 换注入）
+ */
+import fs from "node:fs/promises";
+import { TmuxInvoker } from "./tmux-invoker.js";
+import { noopLogger, 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 class SessionRegistry {
+    private reconciledDirs = new Set<string>();
+
+    constructor(
+        private readonly dirResolver: DirResolver,
+        private readonly log: FilaxisLogger = noopLogger,
+    ) {}
+
+    async ensureDir(): Promise<void> {
+        await fs.mkdir(this.dirResolver(), { recursive: true });
+    }
+
+    /** 确保目录存在 + 每目录一次重连扫描（幂等；换目录=新一轮启动） */
+    async init(): Promise<void> {
+        await this.ensureDir();
+        const dir = this.dirResolver();
+        if (this.reconciledDirs.has(dir)) return;
+        this.reconciledDirs.add(dir);
+        await this.reconcileOnStartup();
+    }
+
+    async save(profile: TerminalProfile): Promise<void> {
+        await fs.writeFile(`${this.dirResolver()}/${profile.id}.json`, JSON.stringify(profile, null, 2));
+    }
+
+    /** 缺失返回 null（不抛） */
+    async load(id: string): Promise<TerminalProfile | null> {
+        try {
+            const raw = await fs.readFile(`${this.dirResolver()}/${id}.json`, "utf-8");
+            return JSON.parse(raw) as TerminalProfile;
+        } catch {
+            return null;
+        }
+    }
+
+    /** 幂等删除 */
+    async remove(id: string): Promise<void> {
+        try {
+            await fs.unlink(`${this.dirResolver()}/${id}.json`);
+        } catch { /* 幂等 */ }
+    }
+
+    /** 启动重连扫描：存活会话保留（=重连），僵尸 profile 清理 */
+    async reconcileOnStartup(): Promise<{ scanned: number; kept: number; removed: number }> {
+        const dir = this.dirResolver();
+        let files: string[];
+        try {
+            files = await fs.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 {
+                // tmux 未安装：无法核实——保留 profile（保守，不误删）
+                kept++;
+            }
+        }));
+        return { scanned: profiles.length, kept, removed };
+    }
+}

package/src/terminal/tmux-invoker.ts

@@ -0,0 +1,65 @@
+/**
+ * terminal/tmux-invoker.ts — tmux CLI 原子调用层（净室平移，源锚 8977ff3）
+ *
+ * stdout/stderr 严格分离；非零退出码 reject（带 exitCode+stderr）不吞错；
+ * exit 与 close 双监听先到为准（真实环境 exit 及时，mock 只发 close 兼容）。
+ */
+import { spawn } from "node:child_process";
+import type { TmuxResult } from "./types.js";
+import { TmuxError } from "./types.js";
+
+export class TmuxInvoker {
+    static invoke(args: string[]): Promise<TmuxResult> {
+        return new Promise((resolve, reject) => {
+            let stdout = "";
+            let stderr = "";
+            let settled = false;
+            const p = spawn("tmux", args, { stdio: ["ignore", "pipe", "pipe"] });
+            p.stdout.on("data", (d: Buffer) => { stdout += d; });
+            p.stderr.on("data", (d: Buffer) => { stderr += d; });
+            const settle = (exitCode: number | null) => {
+                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);
+            });
+        });
+    }
+
+    /** 软失败变体：非零退出码返回带 exitCode 的结果（has-session 的 1=不存在是合法语义） */
+    static async tryInvoke(args: string[]): Promise<TmuxResult> {
+        try {
+            return await this.invoke(args);
+        } catch (e) {
+            if (e instanceof TmuxError) {
+                return { stdout: "", stderr: e.stderr, exitCode: e.exitCode };
+            }
+            throw e;
+        }
+    }
+
+    /** tmux 是否可用（spawn 失败=未安装） */
+    static async isAvailable(): Promise<boolean> {
+        try {
+            await this.tryInvoke(["list-sessions"]);
+            return true;
+        } catch {
+            return false;
+        }
+    }
+}

package/src/terminal/types.ts

@@ -0,0 +1,85 @@
+/**
+ * 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 class TmuxError extends Error {
+    constructor(
+        message: string,
+        public readonly args: string[],
+        public readonly exitCode: number,
+        public readonly stderr: string,
+    ) {
+        super(message);
+        this.name = "TmuxError";
+    }
+}
+
+/** 交互 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 const DEFAULT_TERMINAL_CONFIG: TerminalConfig = {
+    env_hardening_prefix: "export GIT_TERMINAL_PROMPT=0 SSH_ASKPASS=/bin/false PAGER=cat",
+    spawn_max_wait_ms_local: 5_000,
+    spawn_max_wait_ms_remote: 20_000,
+    spawn_poll_ms: 200,
+    command_timeout_ms: 600_000,
+    no_output_timeout_ms: 120_000,
+    poll_interval_ms: 500,
+    capture_scrollback: 500,
+    buffer_pending_chars: 100_000,
+    buffer_aggregated_chars: 500_000,
+    buffer_tail_chars: 4_000,
+    prompt_patterns: [
+        "(?:password|passphrase|密码|口令)[^\\n]*[:：]\\s*$",
+        "\\(yes\\/no[^)]*\\)\\s*\\??\\s*$",
+        "press any key to continue[^\\n]*$",
+    ],
+};
+
+/** 把 prompt_patterns 源串编译成多行 OR 正则（末尾锚定 $；mi——大小写不敏感+多行） */
+export function compilePromptPatterns(patterns: string[]): RegExp {
+    const joined = patterns.length === 1 ? patterns[0]! : `(?:${patterns.join("|")})`;
+    return new RegExp(joined, "mi");
+}

package/src/terminal-manager.ts

@@ -0,0 +1,83 @@
+/**
+ * terminal-manager.ts — 持久终端会话门面（净室平移，源锚 8977ff3）
+ *
+ * OSS 化：源版全 static + getProjectRoot 单例 → 实例类（terminalDir 可配，
+ * 缺省 os.tmpdir()/filaxis-terminals；多实例多目录并存）；logger 注入。
+ *
+ * 公开契约（与源版签名一致）：
+ *   spawnSession(driver,target,config?,customId?) → Promise<string>
+ *   runCommand(id,cmd,timeoutMs|options) → Promise<{stdout,exitCode}>
+ *   getSession(id) / destroySession(id) / init()
+ */
+import path from "node:path";
+import { tmpdir } from "node:os";
+import { SessionRegistry, type TerminalProfile } from "./terminal/session-registry.js";
+import { SessionLauncher } from "./terminal/session-launcher.js";
+import { CommandExecuter, type RunOptions } from "./terminal/command-executer.js";
+import { TmuxInvoker } from "./terminal/tmux-invoker.js";
+import type { TerminalConfig } from "./terminal/types.js";
+import { noopLogger, 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 class TerminalManager {
+    private readonly registry: SessionRegistry;
+    private readonly launcher: SessionLauncher;
+    readonly terminalDir: string;
+
+    constructor(opts: TerminalManagerOptions = {}) {
+        this.terminalDir = opts.terminalDir ?? path.join(tmpdir(), "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(): Promise<void> {
+        await this.registry.init();
+    }
+
+    /** 启动（或复用）持久 tmux 会话 */
+    async spawnSession(
+        driver: string,
+        target: string | undefined,
+        config?: Record<string, unknown>,
+        customId?: string,
+    ): Promise<string> {
+        await this.init();
+        return this.launcher.launch(driver, target, config, customId);
+    }
+
+    /** 会话内执行命令（纯净 stdout + exitCode；第三参 number|RunOptions 多态） */
+    async runCommand(
+        id: string,
+        command: string,
+        timeoutMsOrOptions: number | RunOptions = 600_000,
+    ): Promise<{ stdout: string; exitCode: number }> {
+        const opts: RunOptions = typeof timeoutMsOrOptions === "number"
+            ? { timeoutMs: timeoutMsOrOptions }
+            : timeoutMsOrOptions;
+        return CommandExecuter.execute(id, command, opts);
+    }
+
+    /** 销毁会话 + 删 profile（best-effort：kill-session 失败不阻断） */
+    async destroySession(id: string): Promise<void> {
+        try {
+            await TmuxInvoker.invoke(["kill-session", "-t", id]);
+        } catch { /* best-effort */ }
+        await this.registry.remove(id);
+    }
+
+    /** 读 profile；缺失返回 null */
+    async getSession(id: string): Promise<TerminalProfile | null> {
+        return this.registry.load(id);
+    }
+}

package/src/tmux-driver.ts

@@ -0,0 +1,167 @@
+/**
+ * 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, FileEntry, ExecOptions, ExecResult, RuntimeDescriptor,
+} from "./driver.js";
+import { TerminalManager } from "./terminal-manager.js";
+import type {
+    SessionStartOptions, SessionHandleInfo, WatchOptions, ReadLogOptions,
+} from "./session-types.js";
+import { noopLogger, type FilaxisLogger } from "./logger.js";
+
+const q = (s: string) => `'${s.replace(/'/g, "'\\''")}'`;
+
+export interface TmuxDriverOptions {
+    terminalManager?: TerminalManager;
+    logger?: FilaxisLogger;
+}
+
+export class TmuxSessionDriver implements RuntimeDriver {
+    descriptor: RuntimeDescriptor;
+    fs: FileSystemDriver;
+    readonly terminal: TerminalManager;
+    private readonly log: FilaxisLogger;
+
+    constructor(descriptor: RuntimeDescriptor, opts: TmuxDriverOptions = {}) {
+        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 ${q(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 ${q(b64)} | base64 -d > ${q(p)}`);
+            },
+            async exists(p) {
+                const r = await self.exec(`test -e ${q(p)} && echo Y || echo N`);
+                return r.stdout.trim() === "Y";
+            },
+            async stat(p) {
+                const r = await self.exec(`stat -c '%s %Y' ${q(p)} 2>/dev/null || stat -f '%z %m' ${q(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): Promise<FileEntry[]> {
+                const r = await self.exec(`ls -1A ${q(p)} 2>/dev/null || true`);
+                const names = r.stdout.split("\n").filter(Boolean);
+                const out: FileEntry[] = [];
+                for (const name of names) {
+                    const full = `${p.replace(/\/$/, "")}/${name}`;
+                    const d = await self.exec(`test -d ${q(full)} && echo Y || echo N`);
+                    const st = await (this as FileSystemDriver).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 " : ""}${q(p)}`); },
+            async mkdir(p, options) { await self.exec(`mkdir ${options?.recursive ? "-p " : ""}${q(p)}`); },
+        };
+    }
+
+    /** init：无 terminalId 则 spawn；有则验证存活（跨进程重连语义）；cwd 恢复 */
+    async init(): Promise<void> {
+        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`,
+                    10_000,
+                );
+            } catch { /* cwd 恢复失败不阻断初始化 */ }
+        }
+    }
+
+    /** 本实例启动的后台会话（sessionId 集合——destroy 只清理自己的，绝不扫目录误杀他层） */
+    private ownedSessions = new Set<string>();
+
+    /** destroy：只停**本实例**启动的后台进程（审查问题 1：全目录扫杀会误杀同机其他
+     * Filaxis 实例/其他层的任务——/tmp/filaxis-sessions 是共享目录），再销毁会话 */
+    async destroy(): Promise<void> {
+        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 ${q(base)}.pid 2>/dev/null) 2>/dev/null; rm -f ${q(base)}.pid; true`,
+                        5_000,
+                    );
+                } catch { /* best-effort：单个会话清理失败不阻断其余 */ }
+            }
+            this.ownedSessions.clear();
+            await this.terminal.destroySession(this.descriptor.terminalId);
+        }
+    }
+
+    async exec(command: string, options?: ExecOptions): Promise<ExecResult> {
+        if (options?.channel === "pty") {
+            // tmux 后端本身即 PTY 语义（send-keys/capture-pane）
+            const r = await this.terminal.runCommand(this.descriptor.terminalId!, command, {
+                timeoutMs: options?.timeoutMs ?? 120_000,
+            });
+            return { stdout: r.stdout, stderr: "", exitCode: r.exitCode };
+        }
+        // exec 通道语义：独立 ssh 直达不适用于 tmux 复合层——走 PTY 但显式声明混流
+        const r = await this.terminal.runCommand(this.descriptor.terminalId!, command, {
+            timeoutMs: options?.timeoutMs ?? 120_000,
+        });
+        return { stdout: r.stdout, stderr: "", exitCode: r.exitCode };
+    }
+
+    async getCwd(): Promise<string> {
+        const r = await this.exec("pwd");
+        return r.stdout.trim();
+    }
+
+    async getEnv(key: string): Promise<string | undefined> {
+        return (await this.exec(`printf %s "\\$${key}"`)).stdout;
+    }
+
+    // ── 会话族：nohup 后台进程经会话 shell 启动（.pid 落盘供 destroy 清理）──
+    async execSession(command: string, opts?: SessionStartOptions): Promise<SessionHandleInfo> {
+        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 ${q(opts.cwd)} && ` : "";
+        await this.exec(`mkdir -p /tmp/filaxis-sessions; ${cd}nohup bash -c ${q(wrapped)} > ${base}.out 2> ${base}.err < /dev/null & echo $! > ${base}.pid; echo started`);
+        this.ownedSessions.add(sessionId);
+        return { sessionId, logBase: base };
+    }
+    async tailSession(sessionId: string, lines = 50): Promise<string[]> {
+        const r = await this.exec(`tail -n ${lines} /tmp/filaxis-sessions/${sessionId}.out 2>/dev/null || true`);
+        return r.stdout.split("\n").filter(Boolean);
+    }
+    async readSessionLog(sessionId: string, opts?: ReadLogOptions): Promise<string> {
+        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: string, _opts: WatchOptions): { cancel(): void } {
+        throw new Error("tmux 后端会话 watcher 属 M2 观察流批次（stream-session 落位后接入）");
+    }
+    async stopSession(sessionId: string): Promise<{ exitCode?: number | null }> {
+        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(): Array<{ sessionId: string; command: string; running: boolean; startedAt: number }> {
+        return []; // 无常驻索引（M2 批补 registry 化）
+    }
+}

package/src/vt100-screen.ts

@@ -0,0 +1,166 @@
+/**
+ * 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;
+}
+
+const ESC = "\u001b";
+const BEL = "\u0007";
+
+export class Vt100Screen {
+    private rows: string[][];
+    private curRow = 0;
+    private curCol = 0;
+    /** 解析状态：0=normal 1=esc 2=csi 3=osc */
+    private state = 0;
+    private csiBuf = "";
+    private oscBuf = "";
+    private _frames = 0;
+
+    constructor(opts: Vt100ScreenOptions = {}) {
+        const rows = opts.rows ?? 24;
+        const cols = opts.cols ?? 220;
+        this.rows = Array.from({ length: rows }, () => Array.from({ length: cols }, () => " "));
+    }
+
+    /** 喂原始字节流（含转义序列） */
+    feed(chunk: string): void {
+        for (const ch of chunk) this.put(ch);
+        this._frames++;
+    }
+
+    /** 字符级高清截屏（行尾空白裁剪） */
+    snapshot(): string {
+        return this.rows.map((r) => r.join("").replace(/ +$/, "")).join("\n");
+    }
+
+    get cursor(): { row: number; col: number } {
+        return { row: this.curRow, col: this.curCol };
+    }
+
+    /** 已喂 chunk 数（帧计数——TUI 增量包一包一帧） */
+    get frames(): number {
+        return this._frames;
+    }
+
+    private put(ch: string): void {
+        switch (this.state) {
+            case 0: { // normal
+                if (ch === ESC) { this.state = 1; return; }
+                this.writeChar(ch);
+                return;
+            }
+            case 1: { // esc
+                if (ch === "[") { this.state = 2; this.csiBuf = ""; return; }
+                if (ch === "]") { this.state = 3; this.oscBuf = ""; return; }
+                // 其余两字符序列（(B 等）忽略
+                this.state = 0;
+                return;
+            }
+            case 2: { // csi
+                if (ch >= "0" && ch <= "9" || ch === ";" || ch === "?") { this.csiBuf += ch; return; }
+                this.state = 0;
+                this.csiDispatch(ch);
+                return;
+            }
+            default: { // osc
+                if (ch === BEL || ch === ESC) { this.state = 0; return; }
+                if (this.oscBuf.length < 256) this.oscBuf += ch; // 忽略内容（防长流）
+                return;
+            }
+        }
+    }
+
+    private csiDispatch(final: string): void {
+        const parts = this.csiBuf.replace(/\?/g, "").split(";");
+        const n = (i: number, d: number) => {
+            const v = parts[i] === undefined || parts[i] === "" ? d : parseInt(parts[i]!, 10);
+            return Number.isFinite(v) ? v : d;
+        };
+        switch (final) {
+            case "H": case "f": // CUP/HVP：1-based 定位
+                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; // CUU
+            case "B": this.moveTo(this.curRow + Math.max(1, n(0, 1)), this.curCol); return; // CUD
+            case "C": this.moveTo(this.curRow, this.curCol + Math.max(1, n(0, 1))); return; // CUF
+            case "D": this.moveTo(this.curRow, this.curCol - Math.max(1, n(0, 1))); return; // CUB
+            case "J": { // ED
+                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": { // EL
+                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; // m（SGR）等其余序列忽略
+        }
+    }
+
+    private writeChar(ch: string): void {
+        if (ch === "\n") { 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(); } // autowrap
+        this.rows[this.curRow]![this.curCol] = ch;
+        this.curCol++;
+    }
+
+    private lineFeed(): void {
+        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++;
+        }
+    }
+
+    private moveTo(row: number, col: number): void {
+        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));
+    }
+
+    /** endCol=-1 表示到行尾；endRow 含 */
+    private clearRegion(row1: number, col1: number, row2: number, col2: number): void {
+        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] = " ";
+        }
+    }
+
+    private clearAll(): void {
+        const cols = this.rows[0]!.length;
+        this.rows = Array.from({ length: this.rows.length }, () => Array.from({ length: cols }, () => " "));
+    }
+}