@syrkos/filaxis 0.1.0-alpha.10

package/src/terminal/command-executer.ts

@@ -0,0 +1,374 @@
+/**
+ * terminal/command-executer.ts — 持久会话内命令执行（marker 协议 + 三级缓冲 + 双超时）
+ * （净室平移，源锚 8977ff3；剥 SubstrateSecurity——安全策略归消费方；
+ *  interactionManager 两形态嗅探剥——OSS 只认 PromptResponder 注入）
+ *
+ * marker 协议：send-keys 命令 + `echo MARKER$?`，capture-pane 解析 exitCode；
+ * stdout 从 OutputBuffer 增量累积取（不受 capture 窗口截断）。
+ * 双超时：墙钟总限 + 不活动（新输出重置——只杀哑不杀慢）。
+ * 修复点 D：shopt 安全前缀防 PS1 注入。二进制嗅探保 stdout 纯净。
+ */
+import { TmuxInvoker } from "./tmux-invoker.js";
+import { OutputBuffer, type BufferStats } from "./output-buffer.js";
+import { compilePromptPatterns, DEFAULT_TERMINAL_CONFIG, type PromptPayload, type PromptResponder, type TerminalConfig } from "./types.js";
+import { noopLogger, 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 class CommandExecError extends Error {
+    readonly partialOutput: string;
+    /** 超时/中断：远端终态未核实（"unknown"）——上层按未知处理，严禁当已清理 */
+    outcome?: "unknown";
+    constructor(message: string, partialOutput = "", outcome?: "unknown") {
+        super(message);
+        this.name = "CommandExecError";
+        this.partialOutput = partialOutput;
+        this.outcome = outcome;
+    }
+}
+
+const SAFE_PREFIX = "shopt -u promptvars nullglob extglob nocaseglob 2>/dev/null;";
+const BINARY_SNIFF_BYTES = 4096;
+const BINARY_NULL_RATIO = 0.10;
+
+/** 二进制嗅探：前 N 字节 null 占比 >10% 判 binary（PTY 偶发 NUL 容忍） */
+export function isBinaryChunk(text: string): boolean {
+    const sample = text.length > BINARY_SNIFF_BYTES ? text.slice(0, BINARY_SNIFF_BYTES) : text;
+    if (sample.length === 0) return false;
+    let nulls = 0;
+    for (let i = 0; i < sample.length; i++) {
+        if (sample.charCodeAt(i) === 0) nulls++;
+    }
+    return nulls / sample.length > BINARY_NULL_RATIO;
+}
+
+const sleep = (ms: number) => new Promise<void>((r) => setTimeout(r, ms));
+
+export interface CommandExecuterOptions {
+    config?: Partial<TerminalConfig>;
+    logger?: FilaxisLogger;
+}
+
+export class CommandExecuter {
+    private constructor() {}
+
+    private static cfg: TerminalConfig = { ...DEFAULT_TERMINAL_CONFIG };
+    /** 已关回显的会话（每会话一次性 stty -echo——交互 shell 的命令回显不进 stdout） */
+    private static sttyOff = new Set<string>();
+    /** per-session 命令链（审查问题 2：同会话命令必须串行——并发 send-keys 交错） */
+    private static chains = new Map<string, Promise<unknown>>();
+    /** 因终态不可确认被销毁的会话（自愈：重建后 has-session 探活即清除标记） */
+    private static deadSessions = new Set<string>();
+    private static log: FilaxisLogger = noopLogger;
+
+    /** 配置注入（SDK 组装期一次性；测试可覆盖） */
+    static configure(opts: CommandExecuterOptions = {}): void {
+        this.cfg = { ...DEFAULT_TERMINAL_CONFIG, ...opts.config };
+        this.log = opts.logger ?? noopLogger;
+    }
+
+    /**
+     * 在 tmux 会话中执行命令（四阶段 temporal isolation——审查问题 2 修复）：
+     * - **per-session 串行**：同会话命令排队，绝不并发 send-keys；
+     * - 超时（墙钟/不活动）= INTERRUPTING：发 C-c 杀远端前台任务，调用方立即
+     *   收 CommandExecError（挂 outcome:"unknown"）——但**会话锁不释放**；
+     * - DRAINING（仍在链内）：等自己的 marker 可信终态（上限 5s）才把会话交还
+     *   下一条命令；
+     * - 等不到终态 → kill-session 销毁 + 标记 dead（后续调用显式报错指引重建；
+     *   重建后探活自愈）——绝不定时强行复用。
+     */
+    static async execute(id: string, command: string, opts: RunOptions = {}): Promise<TerminalExecResult> {
+        // 自愈探活：dead 标记在但会话已被重建（同 id respawn）→ 清标记放行
+        if (this.deadSessions.has(id)) {
+            try {
+                const r = await TmuxInvoker.tryInvoke(["has-session", "-t", id]);
+                if (r.exitCode === 0) {
+                    this.deadSessions.delete(id);
+                    this.sttyOff.delete(id);
+                } else {
+                    throw new CommandExecError(
+                        `tmux session '${id}' 已因超时终态不可确认被销毁——请重建层（同 id respawn 后自动恢复）再执行`,
+                    );
+                }
+            } catch (e) {
+                if (e instanceof CommandExecError) throw e;
+                throw new CommandExecError(`tmux session '${id}' 已销毁且探活失败——请重建层`);
+            }
+        }
+        const prev = this.chains.get(id) ?? Promise.resolve();
+        const run = prev.catch(() => undefined).then(() => this.executeLocked(id, command, opts));
+        this.chains.set(id, run.catch(() => undefined));
+        return run;
+    }
+
+    private static async executeLocked(id: string, command: string, opts: RunOptions = {}): Promise<TerminalExecResult> {
+        const cfg = this.cfg;
+        const timeoutMs = opts.timeoutMs ?? cfg.command_timeout_ms;
+
+        let alive: boolean;
+        try {
+            const r = await TmuxInvoker.tryInvoke(["has-session", "-t", id]);
+            alive = r.exitCode === 0;
+        } catch {
+            alive = false;
+        }
+        if (!alive) {
+            throw new CommandExecError(`tmux session '${id}' does not exist. Spawn a new session first.`);
+        }
+
+        await TmuxInvoker.invoke(["clear-history", "-t", id]);
+
+        // ── 会话首次执行：关交互回显 + 清提示符（CI 实证：tmux 非登录 shell 的
+        //    PS1 带 hostname 前缀裸奔，命令回显与提示符行全进 capture-pane）。
+        //    stty/PS1 自身的回显经二次 clear 清除 ──
+        if (!this.sttyOff.has(id)) {
+            await this.sendKeys(id, "stty -echo 2>/dev/null; export PS1= PS2=;");
+            await sleep(400);
+            await TmuxInvoker.invoke(["clear-history", "-t", id]);
+            this.sttyOff.add(id);
+        }
+        // 每命令发送前清屏：clear-history 只清滚回区；可见 pane 的残留（CI 六发
+        // 实证 PRE_TASK_OUT 滞留）必须经 shell 命令 `clear`（清终端+光标归位；
+        // C-l 按键在非交互 bash 不被处理，实测无效）——两者一起做
+        try {
+            await TmuxInvoker.invoke(["send-keys", "-t", id, "-l", "clear"]);
+            await TmuxInvoker.invoke(["send-keys", "-t", id, "C-m"]);
+            await sleep(200);
+        } catch { /* best-effort */ }
+        await TmuxInvoker.invoke(["clear-history", "-t", id]).catch(() => undefined);
+
+        const markerToken = Math.random().toString(36).slice(2, 10);
+        const markerPrefix = `---CMD_DONE_${markerToken}_`;
+        const markerEchoNeedle = `echo ${markerPrefix}`;
+        const safeCommand = `${SAFE_PREFIX} ${command}`;
+
+        await this.sendKeys(id, safeCommand);
+        await this.sendKeys(id, `echo ${markerPrefix}$?`);
+
+        const buffer = new OutputBuffer({
+            pendingChars: cfg.buffer_pending_chars,
+            aggregatedChars: cfg.buffer_aggregated_chars,
+            tailChars: cfg.buffer_tail_chars,
+        });
+
+        const wallDeadline = Date.now() + timeoutMs;
+        let lastActivityAt = Date.now();
+        let lastPaneText = "";
+        let binaryDetected = false;
+        let binaryBytes = 0;
+
+        while (true) {
+            if (Date.now() >= wallDeadline || Date.now() - lastActivityAt >= cfg.no_output_timeout_ms) {
+                // ★ INTERRUPTING（审查问题 2：此前裸 throw——前台任务还在跑，下一条
+                //   命令的 send-keys 会打进去。现在：发 C-c → DRAINING 等自己的
+                //   marker 可信终态（仍在链内，串行保证下一条命令等这里完成）→
+                //   等不到则销毁会话标 dead，绝不强行复用）
+                const reason = Date.now() >= wallDeadline
+                    ? `Timeout waiting for command to finish in terminal ${id}`
+                    : `Timeout waiting for command to finish in terminal ${id} (no output for ${cfg.no_output_timeout_ms}ms)`;
+                const partial = this.extractPartialOutput(buffer, markerPrefix, markerEchoNeedle, binaryDetected, binaryBytes);
+                try { await TmuxInvoker.invoke(["send-keys", "-t", id, "C-c"]); } catch { /* 会话可能已死 */ }
+                // ★ 交互 bash 中 ^C 杀整行 job（含本命令尾部的 marker echo）——原命令的
+                //   marker 可能永不出现。DRAINING 改用**独立探测哨兵**：发一条新的
+                //   echo（自身 ^C 幸存——它是 ^C 之后的新行），等它出现在 pane 即
+                //   shell 已回提示符（可信终态：可安全接手）。二者任一先到即算。
+                const drainToken = `__FX_DRAIN_${Math.random().toString(36).slice(2, 8)}`;
+                try {
+                    await TmuxInvoker.invoke(["send-keys", "-t", id, "-l", `echo ${drainToken}`]);
+                    await TmuxInvoker.invoke(["send-keys", "-t", id, "C-m"]);
+                } catch { /* 会话可能已死 */ }
+                const drained = await this.waitForDrain(id, markerPrefix, drainToken, 5_000);
+                if (drained) {
+                    try { await TmuxInvoker.invoke(["clear-history", "-t", id]); } catch { /* best-effort */ }
+                    throw new CommandExecError(
+                        `${reason}（已发 ^C，远端 shell 已确认回提示符——outcome=unknown）`,
+                        partial, "unknown",
+                    );
+                }
+                try { await TmuxInvoker.invoke(["kill-session", "-t", id]); } catch { /* 已死 */ }
+                this.deadSessions.add(id);
+                this.sttyOff.delete(id);
+                throw new CommandExecError(
+                    `${reason}（已发 ^C 但 5s 内未见可信终态——会话已销毁防残影串台；同 id respawn 后自动恢复）`,
+                    partial, "unknown",
+                );
+            }
+
+            const paneText = await this.capturePane(id, cfg.capture_scrollback);
+
+            if (paneText !== lastPaneText) {
+                lastActivityAt = Date.now();
+                if (paneText.length > 0) {
+                    if (!binaryDetected && isBinaryChunk(paneText)) {
+                        binaryDetected = true;
+                        binaryBytes = paneText.length;
+                        this.log.warn(`[${id}] 检测到二进制输出，切换字节计数模式`);
+                    } else if (binaryDetected) {
+                        binaryBytes = paneText.length;
+                    } else {
+                        const delta = this.computeDelta(lastPaneText, paneText);
+                        if (delta.length > 0) buffer.append(delta);
+                        if (opts.onProgress && !paneText.includes(markerPrefix)) {
+                            try {
+                                opts.onProgress({ tail: buffer.readTail(), stats: buffer.stats });
+                            } catch { /* 进度回调失败不阻断 */ }
+                        }
+                    }
+                }
+                lastPaneText = paneText;
+            }
+
+            if (paneText.includes(markerPrefix)) {
+                const exitCode = this.parseExitCode(paneText, markerPrefix);
+                if (exitCode !== null) {
+                    if (binaryDetected) {
+                        return { stdout: `[binary output: ${binaryBytes} bytes omitted]`, exitCode };
+                    }
+                    const stdout = this.stripMarkerNoise(buffer.readLogText(), markerPrefix, markerEchoNeedle);
+                    return { stdout, exitCode };
+                }
+            }
+
+            // 交互 Prompt 检测（无 marker 时；仅文本末尾匹配）
+            if (opts.responder && !paneText.includes(markerPrefix)) {
+                const payload = this.detectPrompt(paneText, id);
+                if (payload) {
+                    this.log.info(`[${id}] 检测到交互 Prompt：${payload.metadata.prompt}`);
+                    const reply = await opts.responder.ask(payload);
+                    if (reply) {
+                        await this.sendKeys(id, reply);
+                        await sleep(800);
+                        lastPaneText = "";
+                        lastActivityAt = Date.now();
+                    }
+                    continue;
+                }
+            }
+
+            // 中途死亡检测（存活=心跳，重置不活动定时器）
+            try {
+                const r = await TmuxInvoker.tryInvoke(["has-session", "-t", id]);
+                alive = r.exitCode === 0;
+            } catch {
+                alive = false;
+            }
+            if (!alive) {
+                throw new CommandExecError(
+                    `tmux session '${id}' died while waiting for command to complete.`,
+                    this.extractPartialOutput(buffer, markerPrefix, markerEchoNeedle, binaryDetected, binaryBytes),
+                );
+            }
+            lastActivityAt = Date.now();
+            await sleep(cfg.poll_interval_ms);
+        }
+    }
+
+    /** 交互 Prompt 检测（末尾锚定，避免输出中段字样误判） */
+    static detectPrompt(paneText: string, terminalId: string): PromptPayload | null {
+        if (!paneText) return null;
+        const re = compilePromptPatterns(this.cfg.prompt_patterns);
+        const m = paneText.match(re);
+        if (!m) return null;
+        const prompt = m[0].trim();
+        return {
+            type: "CONFIRM",
+            title: "Shell Interaction Needed",
+            message: `The command is requesting input: "${prompt}"`,
+            metadata: { terminalId, prompt, platform: "terminal" },
+        };
+    }
+
+    private static parseExitCode(paneText: string, markerPrefix: string): number | null {
+        for (const line of paneText.split("\n")) {
+            if (!line.includes(markerPrefix)) continue;
+            if (line.includes(`echo ${markerPrefix}`)) continue;
+            const match = line.match(new RegExp(`${markerPrefix}(\\d+)`));
+            if (match) return parseInt(match[1] ?? "0", 10);
+        }
+        return null;
+    }
+
+    /** 增量 delta：新快照以上次为前缀 → 尾部；归一 \r 后再试；漂移则整屏（宁重复不丢） */
+    private static computeDelta(prev: string, curr: string): string {
+        if (prev.length === 0) return curr;
+        if (curr.startsWith(prev)) return curr.slice(prev.length);
+        const normPrev = prev.replace(/\r/g, "");
+        const normCurr = curr.replace(/\r/g, "");
+        if (normCurr.startsWith(normPrev)) return curr.slice(prev.length);
+        return curr;
+    }
+
+    /** 剥 marker/echo 噪声得纯净 stdout（marker 行起全停） */
+    private static stripMarkerNoise(log: string, markerPrefix: string, markerEchoNeedle: string): string {
+        const resultLines: string[] = [];
+        for (const line of log.split("\n")) {
+            if (line.includes(markerPrefix)) break;
+            if (line.includes(markerEchoNeedle)) continue;
+            if (/__FX_DRAIN_[0-9a-z]+/.test(line)) continue; // DRAINING 探测哨兵行
+            if (/stty -echo/.test(line)) continue; // 初始化残章
+            if (/\$\s*$/.test(line) && /debian_chroot|@\S+[:~]/.test(line)) continue; // hostname 提示符行（PS1 清理竞态兜底）
+            if (/^\$\s*$/.test(line)) continue; // 清空后的空提示符
+            resultLines.push(line);
+        }
+        while (resultLines.length > 0 && resultLines[resultLines.length - 1]!.trim() === "") {
+            resultLines.pop();
+        }
+        return resultLines.join("\n").trim();
+    }
+
+    private static extractPartialOutput(
+        buffer: OutputBuffer, markerPrefix: string, markerEchoNeedle: string,
+        binaryDetected: boolean, binaryBytes: number,
+    ): string {
+        if (binaryDetected) return `[binary output: ${binaryBytes} bytes omitted]`;
+        return this.stripMarkerNoise(buffer.readLogText(), markerPrefix, markerEchoNeedle);
+    }
+
+    private static async sendKeys(id: string, text: string): Promise<void> {
+        await TmuxInvoker.invoke(["send-keys", "-t", id, "-l", text]);
+        await TmuxInvoker.invoke(["send-keys", "-t", id, "C-m"]);
+    }
+
+    /**
+     * DRAINING（审查问题 2）：超时 ^C 后等可信回提示符证据（有上限）。
+     * 两凭证任一先到：① 原命令 marker（^C 后 trap/echo 幸存时）② 独立探测哨兵
+     * drainToken（^C 之后新发的 echo——^C 杀整行 job 也不影响它）。
+     * 链内调用——串行保证下一条命令在本方法返回/超时后才接手会话。
+     */
+    private static async waitForDrain(id: string, markerPrefix: string, drainToken: string, deadlineMs: number): Promise<boolean> {
+        const deadline = Date.now() + deadlineMs;
+        while (Date.now() < deadline) {
+            const pane = await this.capturePane(id, 80);
+            if (pane.includes(drainToken)) return true;
+            if (pane.includes(markerPrefix) && this.parseExitCode(pane, markerPrefix) !== null) return true;
+            await sleep(120);
+        }
+        return false;
+    }
+
+    private static async capturePane(id: string, scrollback: number): Promise<string> {
+        try {
+            const r = await TmuxInvoker.invoke(["capture-pane", "-t", id, "-p", "-S", `-${scrollback}`]);
+            return r.stdout;
+        } catch {
+            return "";
+        }
+    }
+}

package/src/terminal/output-buffer.ts

@@ -0,0 +1,126 @@
+/**
+ * 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 class OutputBuffer {
+    private pendingStdout: string[] = [];
+    private pendingStderr: string[] = [];
+    private aggregated = "";
+    private tail = "";
+    private totalOutputChars = 0;
+    private truncated = false;
+    private baseOffset = 0;
+
+    private readonly pendingCap: number;
+    private readonly aggregatedCap: number;
+    private readonly tailCap: number;
+
+    constructor(caps: BufferCaps) {
+        this.pendingCap = caps.pendingChars;
+        this.aggregatedCap = caps.aggregatedChars;
+        this.tailCap = caps.tailChars;
+    }
+
+    append(chunk: string, stream: OutputStream = "stdout"): void {
+        if (chunk.length === 0) return;
+        this.totalOutputChars += chunk.length;
+        const buf = stream === "stderr" ? this.pendingStderr : this.pendingStdout;
+        buf.push(chunk);
+        this.trimPending(buf);
+        this.aggregated += chunk;
+        if (this.aggregated.length > this.aggregatedCap) {
+            const dropped = this.aggregated.length - this.aggregatedCap;
+            this.aggregated = this.aggregated.slice(-this.aggregatedCap);
+            this.baseOffset += dropped;
+            this.truncated = true;
+        }
+        this.tail = this.aggregated.slice(-this.tailCap);
+    }
+
+    /** 取走并清空未读增量 */
+    drainPending(): string {
+        const out = this.pendingStdout.join("");
+        const err = this.pendingStderr.join("");
+        this.pendingStdout = [];
+        this.pendingStderr = [];
+        return out + (err ? `\n[stderr]\n${err}` : "");
+    }
+
+    readTail(): string {
+        return this.tail;
+    }
+
+    /** 分页读取（绝对偏移游标；游标过期显式报断档） */
+    readLog(offset = 0, limit?: number): ReadLogResult {
+        if (offset < this.baseOffset) {
+            const lostChars = this.baseOffset - offset;
+            const text = limit === undefined ? this.aggregated : this.aggregated.slice(0, limit);
+            return { ok: false, text, nextOffset: this.baseOffset + text.length, validFrom: this.baseOffset, lostChars };
+        }
+        const start = offset - this.baseOffset;
+        const text = limit === undefined
+            ? this.aggregated.slice(start)
+            : this.aggregated.slice(start, start + limit);
+        return { ok: true, text, nextOffset: offset + text.length };
+    }
+
+    /** 便捷视图：丢失时前置断档提示行 */
+    readLogText(offset = 0, limit?: number): string {
+        const r = this.readLog(offset, limit);
+        if (!r.ok) {
+            return `[游标已过期] 此前约 ${r.lostChars} 字符已被裁掉，以下从绝对偏移 ${r.validFrom} 继续\n` + r.text;
+        }
+        return r.text;
+    }
+
+    get stats(): BufferStats {
+        return { total: this.totalOutputChars, truncated: this.truncated };
+    }
+
+    hasPending(): boolean {
+        return this.pendingStdout.length > 0 || this.pendingStderr.length > 0;
+    }
+
+    reset(): void {
+        this.pendingStdout = [];
+        this.pendingStderr = [];
+        this.aggregated = "";
+        this.tail = "";
+        this.totalOutputChars = 0;
+        this.baseOffset = 0;
+        this.truncated = false;
+    }
+
+    private trimPending(buf: string[]): void {
+        let len = buf.reduce((s, c) => s + c.length, 0);
+        while (len > this.pendingCap && buf.length > 1) {
+            const dropped = buf.shift()!;
+            len -= dropped.length;
+            this.truncated = true;
+        }
+    }
+}

package/src/terminal/session-launcher.ts

@@ -0,0 +1,146 @@
+/**
+ * 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, type TerminalProfile } from "./session-registry.js";
+import { TmuxInvoker } from "./tmux-invoker.js";
+import { DEFAULT_TERMINAL_CONFIG, type TerminalConfig } from "./types.js";
+import { noopLogger, type FilaxisLogger } from "../logger.js";
+
+export interface SessionLauncherOptions {
+    config?: Partial<TerminalConfig>;
+    logger?: FilaxisLogger;
+}
+
+const sleep = (ms: number) => new Promise<void>((r) => setTimeout(r, ms));
+
+export class SessionLauncher {
+    private readonly cfg: TerminalConfig;
+    private readonly log: FilaxisLogger;
+
+    constructor(
+        private readonly registry: SessionRegistry,
+        opts: SessionLauncherOptions = {},
+    ) {
+        this.cfg = { ...DEFAULT_TERMINAL_CONFIG, ...opts.config };
+        this.log = opts.logger ?? noopLogger;
+    }
+
+    /** 启动（或复用）一个持久 tmux 会话；返回存活会话 id */
+    async launch(
+        driver: string,
+        target: string | undefined,
+        config?: Record<string, unknown>,
+        customId?: string,
+    ): Promise<string> {
+        const id = customId || ("term_" + Date.now().toString(36) + "_" + Math.random().toString(36).slice(2, 6));
+        const launchCmd = this.resolveLaunchCmd(driver, target, config);
+
+        // customId 复用：会话仍存活直接返回（profile 按当前入参刷新）
+        try {
+            const alive = await TmuxInvoker.tryInvoke(["has-session", "-t", id]);
+            if (alive.exitCode === 0) {
+                this.log.info(`会话 [${id}] 已存在于 tmux，复用`);
+                const profile: TerminalProfile = { id, driver, target: target ?? "", config, createdAt: Date.now() };
+                await this.registry.save(profile);
+                return id;
+            }
+        } catch { /* tmux 不可用——继续走 new-session 由其报错 */ }
+
+        const finalCmd = this.cfg.env_hardening_prefix
+            ? `${this.cfg.env_hardening_prefix}; ${launchCmd}`
+            : launchCmd;
+        this.log.info(`启动持久会话 [${id}] (driver: ${driver})`);
+        // -x 220：pane 宽列——输出长行不被 80 列折断（marker 解析/stout 纯净度契约依赖整行）
+        await TmuxInvoker.invoke(["new-session", "-d", "-x", "220", "-s", id, finalCmd]);
+
+        const ok = await this.waitForAlive(id, driver);
+        if (!ok) {
+            await this.registry.remove(id);
+            throw new Error(this.diedHint(id, driver, target));
+        }
+        const profile: TerminalProfile = { id, driver, target: target ?? "", config, createdAt: Date.now() };
+        await this.registry.save(profile);
+        return id;
+    }
+
+    /** 已知 driver 快捷方式渲染（与 RuntimeDescriptor 注释一致） */
+    resolveLaunchCmd(driver: string, target: string | undefined, config?: Record<string, unknown>): string {
+        const c = config ?? {};
+        if (typeof c.launchCmd === "string" && c.launchCmd) return c.launchCmd;
+        if (driver === "ssh" && target) {
+            const sshOpts = typeof c.sshOptions === "string" ? c.sshOptions : "";
+            return `ssh ${sshOpts} -t ${target}`;
+        }
+        if (driver === "docker" && target) {
+            const runtime = typeof c.runtime === "string" ? c.runtime : "docker";
+            const shell = typeof c.shell === "string" ? c.shell : "sh";
+            return `${runtime} exec -i ${target} ${shell} -i`;
+        }
+        if (driver === "k8s" && target) {
+            const runtime = typeof c.runtime === "string" ? c.runtime : "kubectl";
+            const ns = typeof c.namespace === "string" ? `-n ${c.namespace}` : "";
+            const shell = typeof c.shell === "string" ? c.shell : "sh";
+            return `${runtime} exec -i ${ns} ${target} -- ${shell} -i`;
+        }
+        if (driver === "teleport" && target) {
+            const cluster = typeof c.cluster === "string" ? `--cluster=${c.cluster} ` : "";
+            const login = typeof c.login === "string" ? `${c.login}@` : "";
+            return `tsh ssh ${cluster}${login}${target}`;
+        }
+        if (driver === "local") return "bash";
+        throw new Error(
+            `Unknown driver '${driver}' and no config.launchCmd provided. ` +
+            `Supply config.launchCmd with the full command to enter the environment ` +
+            `(e.g. "nix develop", "conda run -n myenv bash", "distrobox enter my-box").`,
+        );
+    }
+
+    /** 存活轮询（远端 driver 更长 deadline + dead-streak 容忍瞬时抖动） */
+    private async waitForAlive(id: string, driver: string): Promise<boolean> {
+        const isLocal = driver === "local";
+        const maxWaitMs = isLocal ? this.cfg.spawn_max_wait_ms_local : this.cfg.spawn_max_wait_ms_remote;
+        const maxDeadStreak = isLocal ? 1 : 3;
+        const deadline = Date.now() + maxWaitMs;
+        let deadStreak = 0;
+        while (Date.now() < deadline) {
+            await sleep(this.cfg.spawn_poll_ms);
+            let alive: boolean;
+            try {
+                const r = await TmuxInvoker.tryInvoke(["has-session", "-t", id]);
+                alive = r.exitCode === 0;
+            } catch {
+                return false;
+            }
+            if (!alive) {
+                deadStreak++;
+                if (deadStreak >= maxDeadStreak) return false;
+                continue;
+            }
+            deadStreak = 0;
+            const paneOut = await TmuxInvoker.tryInvoke(["capture-pane", "-t", id, "-p"]);
+            if (paneOut.stdout !== "") return true;
+        }
+        try {
+            const r = await TmuxInvoker.tryInvoke(["has-session", "-t", id]);
+            return r.exitCode === 0;
+        } catch {
+            return false;
+        }
+    }
+
+    private diedHint(id: string, driver: string, target: string | undefined): string {
+        const hint = driver === "docker"
+            ? `Make sure the container '${target}' is running ('docker ps'). Use the container name/ID, not the image name.`
+            : driver === "ssh"
+                ? `Check that '${target}' is reachable and SSH credentials are valid.`
+                : driver === "teleport"
+                    ? `Check 'tsh status' — a valid Teleport login is required.`
+                    : "The shell exited immediately after launch.";
+        return `Session '${id}' (driver: ${driver}) died immediately after spawn. ${hint}`;
+    }
+}