super-dsh 0.3.1 → 0.3.2-d

package/superd-hub/dist/exec-pty-channel.d.ts

@@ -1,58 +0,0 @@
-/** The transport seam the ported PtySession drives (spec §8.2: {write, onData, kill}). */
-export interface PtyChannel {
-    /** Open the transport; resolves when bytes can flow (session readiness itself = the init nonce frame). */
-    open(onData: (chunk: string) => void): Promise<void>;
-    write(s: string): void;
-    /** Polite close (dispose path: 'exit\n' already sent by the session). */
-    close(): void;
-    /** Hard kill: the transport AND any process group behind it (Ruling 8 fallback). */
-    kill(): void;
-    /** Register for unexpected transport death (socket cut / process exit). */
-    onDead(callback: () => void): void;
-    /** Diagnostics tail (transport stderr / socket errors) for init-failure messages. */
-    readonly diag: string;
-}
-/** Local target: `script -qfec bash /dev/null` — host-side PTY, no node-pty (spec §8.2 / D12). */
-export declare class LocalScriptChannel implements PtyChannel {
-    private readonly argv;
-    diag: string;
-    private proc;
-    private deadCb;
-    constructor(argv?: string[]);
-    open(onData: (chunk: string) => void): Promise<void>;
-    write(s: string): void;
-    close(): void;
-    kill(): void;
-    onDead(callback: () => void): void;
-}
-/** Structural view of the `ws` client socket (runtime peer — mesh-gateway precedent). */
-interface WsSocketLike {
-    send(data: unknown): void;
-    terminate(): void;
-    close(): void;
-    on(event: 'open', listener: () => void): unknown;
-    on(event: 'error', listener: (error: unknown) => void): unknown;
-    on(event: 'message', listener: (data: unknown) => void): unknown;
-    on(event: 'close', listener: () => void): unknown;
-}
-type WsConstructorLike = new (url: string, options: {
-    headers: Record<string, string>;
-}) => WsSocketLike;
-/** Remote target: a WebSocket to the peer hub's dumb PTY executor, pairing Cookie riding the upgrade. */
-export declare class WsPtyChannel implements PtyChannel {
-    private readonly url;
-    private readonly headers;
-    private readonly wsCtor;
-    diag: string;
-    private socket;
-    private deadCb;
-    private readonly pending;
-    private opened;
-    constructor(url: string, headers?: Record<string, string>, wsCtor?: WsConstructorLike | undefined);
-    open(onData: (chunk: string) => void): Promise<void>;
-    write(s: string): void;
-    close(): void;
-    kill(): void;
-    onDead(callback: () => void): void;
-}
-export {};

package/superd-hub/dist/exec-pty-channel.js

@@ -1,162 +0,0 @@
-// PTY channels — the ONE seam spec §8.2 carves out of better-dsh's
-// PtySession: the session machinery (nonce injection, framing, two-stage
-// interrupt, idle TTL) is transport-agnostic; only {open, write, kill} differ
-// between "a local `script -qfec` subprocess" (this machine as target) and
-// "a WebSocket to the peer's dumb PTY executor" (a paired machine as target).
-//
-// The WS client follows mesh-gateway's crash-proofing lesson: an 'error'
-// listener is ALWAYS registered (ECONNREFUSED / a rejected 401 upgrade would
-// otherwise be an uncaught exception), and sends before 'open' queue in
-// order while post-close sends are swallowed (the session's death path owns
-// the teardown).
-import { spawn } from 'node:child_process';
-import { createRequire } from 'node:module';
-/** Local target: `script -qfec bash /dev/null` — host-side PTY, no node-pty (spec §8.2 / D12). */
-export class LocalScriptChannel {
-    argv;
-    diag = '';
-    proc = null;
-    deadCb;
-    constructor(argv = ['script', '-qfec', 'bash', '/dev/null']) {
-        this.argv = argv;
-    }
-    async open(onData) {
-        const proc = spawn(this.argv[0], this.argv.slice(1), { stdio: ['pipe', 'pipe', 'pipe'], detached: true });
-        this.proc = proc;
-        proc.stdout.setEncoding('utf8');
-        proc.stdout.on('data', (d) => onData(d));
-        proc.stderr.setEncoding('utf8').on('data', (d) => { this.diag = (this.diag + d).slice(-2_000); });
-        proc.once('close', () => this.deadCb?.());
-        proc.once('error', (err) => { this.diag = (this.diag + `\n[pty: spawn failed: ${err.message}]`).slice(-2_000); this.deadCb?.(); });
-    }
-    write(s) {
-        if (this.proc?.stdin?.writable !== true)
-            return;
-        try {
-            this.proc.stdin.write(s);
-        }
-        catch { /* dead: the death callback settles the session */ }
-    }
-    close() {
-        this.write('exit\n');
-        const pid = this.proc?.pid;
-        this.proc = null;
-        if (pid === undefined)
-            return;
-        setTimeout(() => { try {
-            process.kill(-pid, 'SIGKILL');
-        }
-        catch { /* already gone */ } }, 1_000).unref();
-    }
-    kill() {
-        const pid = this.proc?.pid;
-        this.proc = null;
-        if (pid === undefined)
-            return;
-        try {
-            process.kill(-pid, 'SIGTERM');
-        }
-        catch { /* already gone */ }
-        setTimeout(() => { try {
-            process.kill(-pid, 'SIGKILL');
-        }
-        catch { /* already gone */ } }, 2_000).unref();
-    }
-    onDead(callback) { this.deadCb = callback; }
-}
-const WS_MODULE = 'ws';
-let wsConstructor;
-function loadWs() {
-    if (wsConstructor !== undefined)
-        return wsConstructor;
-    const require = createRequire(import.meta.url);
-    const mod = require(WS_MODULE);
-    const boxed = mod;
-    wsConstructor = (typeof mod === 'function' ? mod : boxed.default);
-    return wsConstructor;
-}
-/** Remote target: a WebSocket to the peer hub's dumb PTY executor, pairing Cookie riding the upgrade. */
-export class WsPtyChannel {
-    url;
-    headers;
-    wsCtor;
-    diag = '';
-    socket = null;
-    deadCb;
-    pending = [];
-    opened = false;
-    constructor(url, headers = {}, wsCtor = undefined) {
-        this.url = url;
-        this.headers = headers;
-        this.wsCtor = wsCtor;
-    }
-    open(onData) {
-        return new Promise((resolve, reject) => {
-            let settled = false;
-            let socket;
-            try {
-                socket = new (this.wsCtor ?? loadWs())(this.url, { headers: this.headers });
-            }
-            catch (err) {
-                reject(err instanceof Error ? err : new Error(String(err)));
-                return;
-            }
-            this.socket = socket;
-            // crash-proof by construction (mesh-gateway fix-round-1 lesson): 'error'
-            // ALWAYS has a listener; 'close' is guaranteed to follow and the dead
-            // path owns the teardown.
-            socket.on('error', (err) => { this.diag = (this.diag + `\n[pty-ws: ${err instanceof Error ? err.message : String(err)}]`).slice(-2_000); });
-            socket.on('open', () => {
-                if (settled)
-                    return;
-                settled = true;
-                this.opened = true;
-                for (const chunk of this.pending.splice(0))
-                    socket.send(chunk);
-                resolve();
-            });
-            socket.on('message', (data) => {
-                const text = typeof data === 'string'
-                    ? data
-                    : Array.isArray(data)
-                        ? Buffer.concat(data).toString('utf8')
-                        : Buffer.from(data).toString('utf8');
-                onData(text);
-            });
-            socket.on('close', () => {
-                if (!settled) {
-                    settled = true;
-                    reject(new Error(`pty-ws: socket closed before opening${this.diag !== '' ? `; ${this.diag}` : ''}`));
-                    return;
-                }
-                this.opened = false;
-                this.deadCb?.();
-            });
-        });
-    }
-    write(s) {
-        if (this.socket === null)
-            return;
-        if (!this.opened) {
-            this.pending.push(s);
-            return;
-        }
-        try {
-            this.socket.send(s);
-        }
-        catch { /* dead: the close path settles the session */ }
-    }
-    close() {
-        try {
-            this.socket?.close();
-        }
-        catch { /* already closing */ }
-    }
-    kill() {
-        try {
-            this.socket?.terminate();
-        }
-        catch { /* already gone */ }
-    }
-    onDead(callback) { this.deadCb = callback; }
-}

package/superd-hub/dist/exec-pty-framing.d.ts

@@ -1,34 +0,0 @@
-import type { OutputStats } from '../../remote/plugin.js';
-/** 收帧帧体：退出码 + 只读回传的 cwd（Non-Goal ②：报告不重建）。 */
-export interface PtyFrame {
-    exit: number;
-    cwd: string | null;
-}
-/** 8 字节随机串的 hex 形（spec §五.2：每次下发前生成）。 */
-export declare function genNonce(bytes?: number): string;
-/** 命令整行：花括号复合体 + Nonce 收帧尾（spec §五.2 的 printf 逐字落地 + cwd 第三字段）。 */
-export declare function wrapPtyCommand(cmd: string, nonce: string): string;
-/** init 整行：哑终端（echo/PS1/PS2/TERM）+ 固定 40×120（Non-Goal ③）+ INIT 帧。 */
-export declare function buildInitCommand(nonce: string): string;
-export declare function stripAnsi(s: string): string;
-export declare function normalizePtyText(s: string): string;
-export declare function tailWindow(text: string, cap: number, stats?: OutputStats): {
-    text: string;
-    truncated?: number;
-    stats?: OutputStats;
-};
-export interface FrameParserEvents {
-    /** 输出文本：feed 路径经 normalize（剥 ANSI/规整换行）；flush 路径为**裸放出**（残余字节原样，勿假设已剥洗）。 */
-    onOutput?(text: string): void;
-    onFrame(frame: PtyFrame): void;
-}
-export interface NonceFrameParser {
-    feed(chunk: string): void;
-    flush(): void;
-}
-/**
- * 单 nonce、单帧解析器：一轮 dispatch 一个实例。只认 `\x1b]133;D;<nonce>;`，
- * 错误 nonce 的静态/伪造 marker 永不匹配，按普通输出流过（再经 ANSI 剥洗）。
- * 缓冲尾若可能是 marker 前缀则扣留，flush() 时作为输出放出。
- */
-export declare function createNonceFrameParser(nonce: string, events: FrameParserEvents): NonceFrameParser;

package/superd-hub/dist/exec-pty-framing.js

@@ -1,89 +0,0 @@
-// PTY nonce framing — PORTED VERBATIM from better-dsh src/remote/nonce-framing.ts
-// (spec §8.2 / D12 "原样照抄"; only the import specifiers were adapted to this
-// package's ESM convention). Command wrap = brace compound + OSC-133;D nonce
-// tail carrying exit + cwd; parser holds back possible marker prefixes and
-// flushes leftovers raw.
-import { randomBytes } from 'node:crypto';
-/** 8 字节随机串的 hex 形（spec §五.2：每次下发前生成）。 */
-export function genNonce(bytes = 8) {
-    return randomBytes(bytes).toString('hex');
-}
-/** 命令整行：花括号复合体 + Nonce 收帧尾（spec §五.2 的 printf 逐字落地 + cwd 第三字段）。 */
-export function wrapPtyCommand(cmd, nonce) {
-    return `{\n${cmd}\n} ; printf '\\033]133;D;${nonce};%s;%s\\007' "$?" "$PWD"\n`;
-}
-/** init 整行：哑终端（echo/PS1/PS2/TERM）+ 固定 40×120（Non-Goal ③）+ INIT 帧。 */
-export function buildInitCommand(nonce) {
-    return `stty -echo 2>/dev/null ; stty rows 40 cols 120 2>/dev/null ; PS1='' ; PS2='' ; export TERM=dumb ; printf '\\033]133;D;${nonce};0;%s\\007' "$PWD"\n`;
-}
-const ANSI_RE = /\x1b(?:\][^\x07\x1b]*(?:\x07|\x1b\\)?|\[[0-9;?]*[ -/]*[@-~]|[@-Z\\-_])/g;
-export function stripAnsi(s) {
-    return s.replace(ANSI_RE, '');
-}
-export function normalizePtyText(s) {
-    return stripAnsi(s).replace(/\r\n/g, '\n').replace(/\r/g, '');
-}
-export function tailWindow(text, cap, stats) {
-    let tail = text.slice(-cap);
-    if (tail.charCodeAt(0) >= 0xdc00 && tail.charCodeAt(0) <= 0xdfff)
-        tail = tail.slice(1);
-    const returned = stats?.unit === 'bytes' ? Buffer.byteLength(tail) : tail.length;
-    const total = stats?.total ?? text.length;
-    const updated = stats === undefined ? {} : { stats: { ...stats, returned } };
-    if (total <= returned)
-        return { text: tail, ...updated };
-    const unit = stats?.unit === 'bytes' ? 'bytes' : 'chars';
-    const eviction = stats !== undefined && stats.dropped > 0 ? `; retained ${stats.retained}, dropped head ${stats.dropped}, retention limit ${stats.retentionLimit} ${stats.unit === 'bytes' ? 'bytes' : 'UTF-16 code units'}` : '';
-    return { text: `[truncated: showing last ${returned} of ${total} ${unit}${eviction}]\n${tail}`, truncated: total, ...updated };
-}
-const FRAME_BODY_RE = /^(\d+);([^\x07\x1b]*)(?:\x07|\x1b\\)/; // cwd 是尾字段：合法路径可含 `;`，只有 BEL/ESC 终止它
-/**
- * 单 nonce、单帧解析器：一轮 dispatch 一个实例。只认 `\x1b]133;D;<nonce>;`，
- * 错误 nonce 的静态/伪造 marker 永不匹配，按普通输出流过（再经 ANSI 剥洗）。
- * 缓冲尾若可能是 marker 前缀则扣留，flush() 时作为输出放出。
- */
-export function createNonceFrameParser(nonce, events) {
-    const prefix = `\x1b]133;D;${nonce};`;
-    let buf = '';
-    let done = false;
-    const emit = (raw) => {
-        const text = normalizePtyText(raw);
-        if (text.length > 0)
-            events.onOutput?.(text);
-    };
-    const holdback = () => {
-        const max = Math.min(buf.length, prefix.length - 1);
-        for (let k = max; k > 0; k--)
-            if (buf.endsWith(prefix.slice(0, k)))
-                return k;
-        return 0;
-    };
-    const consume = () => {
-        if (done)
-            return;
-        const i = buf.indexOf(prefix);
-        if (i < 0) {
-            const keep = holdback();
-            emit(buf.slice(0, buf.length - keep));
-            buf = buf.slice(buf.length - keep);
-            return;
-        }
-        emit(buf.slice(0, i));
-        const rest = buf.slice(i + prefix.length);
-        const m = FRAME_BODY_RE.exec(rest);
-        if (m === null) {
-            buf = buf.slice(i);
-            return;
-        } // 帧体未到齐，整段扣留
-        events.onFrame({ exit: Number(m[1]), cwd: m[2].length > 0 ? m[2] : null });
-        done = true; // 帧后字节一律丢弃（下一轮是新解析器）
-        buf = '';
-    };
-    return {
-        feed(chunk) { buf += chunk; consume(); },
-        // 流结束 = 裸放出扣留的残余（含未完成的 marker 前缀）：不经过 ANSI 剥洗——
-        // stripAnsi 会把未闭合 OSC 整段吃掉，扣留字节就此蒸发，违背 flush 语义。
-        flush() { if (buf.length > 0)
-            events.onOutput?.(buf); buf = ''; },
-    };
-}

package/superd-hub/dist/exec-pty-session.d.ts

@@ -1,78 +0,0 @@
-import { type StreamOutputStats } from '../../remote/plugin.js';
-import type { PtyChannel } from './exec-pty-channel.js';
-/** spec §五.2 逐字。 */
-export declare const RECONNECT_NOTICE = "[remote: session reconnected to fresh shell; cwd reset to default]";
-export interface PtySessionOptions {
-    key: string;
-    channel: PtyChannel;
-    idleTtlSec: number;
-    initTimeoutSec?: number;
-    /** 池回调：会话彻底出池（dispose）时触发；进程意外死亡不出池（Ruling 7）。 */
-    onDead?: () => void;
-}
-export interface PtyDispatchOptions {
-    stdin?: string;
-    timeoutSec?: number;
-}
-export interface PtyDispatchResult {
-    output: string;
-    outputStats?: StreamOutputStats;
-    exit: number | null;
-    cwd: string | null;
-    timedOut: boolean;
-    reconnected: boolean;
-    durationMs: number;
-}
-export type PtyState = 'cold' | 'starting' | 'ready' | 'dead' | 'disposed';
-/** 会话运行时快照（status 面消费，Ruling 16 词汇源）。 */
-export interface SessionSnapshot {
-    state: PtyState;
-    busy: boolean;
-    idleMs: number | null;
-}
-export declare class PtySession {
-    private readonly opts;
-    private state;
-    private startPromise;
-    private queue;
-    private idleTimer;
-    private onChunk;
-    private deathWaiters;
-    private inFlight;
-    private lastSettleAt;
-    constructor(opts: PtySessionOptions);
-    get sessionState(): PtyState;
-    /** status 面快照：state + busy（有命令在跑）+ idleMs（上次 settle 至今）。 */
-    get snapshot(): SessionSnapshot;
-    /** 同一会话命令严格串行（FIFO）；死亡/冷态先重启。 */
-    dispatch(cmd: string, dOpts?: PtyDispatchOptions): Promise<PtyDispatchResult>;
-    /** TTL / row teardown：尽力 exit，1s 后杀组，出池。 */
-    dispose(): Promise<void>;
-    private write;
-    private start;
-    private doStart;
-    private diag;
-    private markDead;
-    private resetIdleTimer;
-    private clearIdleTimer;
-}
-export interface PtyPoolDefaults {
-    idleTtlSec: number;
-    initTimeoutSec?: number;
-}
-/** 会话池：键 → 会话。意外死亡的会话留在池内（下次 dispatch 带 reconnect 提示）。 */
-export declare class PtyPool {
-    private readonly defaults;
-    private readonly sessions;
-    constructor(defaults: PtyPoolDefaults);
-    get size(): number;
-    /** status 面：键上的会话快照（无会话 = undefined → "none — dials on first exec"）。 */
-    inspect(key: string): SessionSnapshot | undefined;
-    /** roster 面：池内全部会话。 */
-    list(): Array<{
-        key: string;
-        snapshot: SessionSnapshot;
-    }>;
-    getOrCreate(key: string, channelOf: () => PtyChannel): PtySession;
-    disposeAll(): Promise<void>;
-}

package/superd-hub/dist/exec-pty-session.js

@@ -1,228 +0,0 @@
-import { Utf16TailRing } from '../../remote/plugin.js';
-// PTY session machinery — PORTED from better-dsh src/remote/pty-session.ts
-// (spec §8.2 / D12 "原样照抄"), with the ONE sanctioned adaptation: the
-// subprocess spawn is replaced by the PtyChannel seam (exec-pty-channel.ts) —
-// every state transition (init nonce handshake, FIFO dispatch, P8 two-stage
-// interrupt \x03 + injected 130-marker, 3s grace, group-kill fallback, idle
-// TTL, OUTPUT_HARD_CAP with surrogate-pair-safe slicing, I1 waiter hygiene)
-// is the ported logic, unchanged.
-import { buildInitCommand, createNonceFrameParser, genNonce, wrapPtyCommand } from './exec-pty-framing.js';
-/** spec §五.2 逐字。 */
-export const RECONNECT_NOTICE = '[remote: session reconnected to fresh shell; cwd reset to default]';
-const DEFAULT_INIT_TIMEOUT_SEC = 30;
-const INTERRUPT_GRACE_MS = 3_000;
-/** pty 收集内存安全帽（Ruling P15，与 oneshot HARD_CAP 对齐）：模型面只见尾窗，保留尾部。 */
-const OUTPUT_HARD_CAP = 4_000_000;
-export class PtySession {
-    opts;
-    state = 'cold';
-    startPromise = null;
-    queue = Promise.resolve();
-    idleTimer = null;
-    onChunk = null;
-    deathWaiters = [];
-    inFlight = 0;
-    lastSettleAt = 0;
-    constructor(opts) {
-        this.opts = opts;
-        this.opts.channel.onDead(() => this.markDead());
-    }
-    get sessionState() { return this.state; }
-    /** status 面快照：state + busy（有命令在跑）+ idleMs（上次 settle 至今）。 */
-    get snapshot() {
-        return { state: this.state, busy: this.inFlight > 0, idleMs: this.lastSettleAt > 0 ? Date.now() - this.lastSettleAt : null };
-    }
-    /** 同一会话命令严格串行（FIFO）；死亡/冷态先重启。 */
-    dispatch(cmd, dOpts = {}) {
-        const attempt = async () => {
-            const started = Date.now();
-            const reconnected = this.state === 'dead';
-            if (this.state !== 'ready')
-                await this.start();
-            this.inFlight++;
-            return await new Promise((resolve) => {
-                const nonce = genNonce();
-                const ring = new Utf16TailRing(OUTPUT_HARD_CAP);
-                let interrupted = false;
-                let settled = false;
-                let interruptTimer;
-                let killTimer;
-                const deathWaiter = () => finish({ output: ring.text, exit: null, cwd: null, timedOut: interrupted });
-                const cleanup = () => {
-                    this.onChunk = null;
-                    // I1（终审）：已结算 dispatch 的死亡等待必须摘除——否则闭包钉住整段 output，
-                    // 长命会话每调用累积一个 waiter（init 路径的 filter 同款形态）
-                    this.deathWaiters = this.deathWaiters.filter((w) => w !== deathWaiter);
-                    if (interruptTimer !== undefined)
-                        clearTimeout(interruptTimer);
-                    if (killTimer !== undefined)
-                        clearTimeout(killTimer);
-                };
-                const finish = (r) => {
-                    if (settled)
-                        return;
-                    settled = true;
-                    cleanup();
-                    this.inFlight--;
-                    this.lastSettleAt = Date.now();
-                    this.resetIdleTimer();
-                    resolve({ ...r, outputStats: { stdout: ring.stats() }, reconnected, durationMs: Date.now() - started });
-                };
-                const parser = createNonceFrameParser(nonce, {
-                    onOutput: (t) => {
-                        ring.push(t);
-                    },
-                    onFrame: ({ exit, cwd }) => finish({ output: ring.text, exit, cwd, timedOut: interrupted }),
-                });
-                this.onChunk = (c) => parser.feed(c);
-                this.write(wrapPtyCommand(cmd, nonce));
-                if (dOpts.stdin !== undefined)
-                    this.write(dOpts.stdin); // Ruling 11: REPL 式紧随
-                interruptTimer = setTimeout(() => {
-                    interrupted = true;
-                    // P8 两段打断：\x03 中断前台作业后，交互 bash 会放弃当前命令行的剩余部分
-                    // （尾部 marker 不再执行）；紧随注入的同 nonce 130-marker 行在 bash 回到
-                    // 读取态后被执行。无论 bash 弃行还是续行，帧都在宽限内到达且 exit=130，
-                    // 会话存活；若命令 trap 掉 SIGINT，原 marker 先帧、注入行帧后字节被丢弃。
-                    this.write('\x03');
-                    this.write(`printf '\\033]133;D;${nonce};130;%s\\007' "$PWD"\n`);
-                    killTimer = setTimeout(() => {
-                        // Ruling 8 的 kill 兜底：宽限无帧 = 会话不可恢复，杀整组后收尸
-                        // （否则 trap-INT 的卡死进程永生，重连后旧组再不可达）
-                        this.opts.channel.kill();
-                        this.markDead();
-                        finish({ output: ring.text, exit: null, cwd: null, timedOut: true });
-                    }, INTERRUPT_GRACE_MS);
-                }, dOpts.timeoutSec === undefined ? 120_000 : dOpts.timeoutSec * 1_000);
-                this.deathWaiters.push(deathWaiter);
-            });
-        };
-        const run = this.queue.then(attempt, attempt);
-        this.queue = run.then(() => undefined, () => undefined);
-        return run;
-    }
-    /** TTL / row teardown：尽力 exit，1s 后杀组，出池。 */
-    async dispose() {
-        if (this.state === 'disposed')
-            return;
-        this.clearIdleTimer();
-        this.state = 'disposed';
-        this.startPromise = null;
-        this.opts.channel.close();
-        this.opts.onDead?.();
-    }
-    write(s) {
-        this.opts.channel.write(s);
-    }
-    async start() {
-        if (this.state === 'disposed')
-            throw new Error(`[E_SESSION_DISPOSED] remote pty session '${this.opts.key}' was disposed — the pool replaces disposed sessions; this reference is stale`);
-        if (this.startPromise === null) {
-            this.state = 'starting';
-            this.startPromise = this.doStart().catch((err) => {
-                this.startPromise = null;
-                this.markDead();
-                throw err;
-            });
-        }
-        return this.startPromise;
-    }
-    async doStart() {
-        const initTimeoutSec = this.opts.initTimeoutSec ?? DEFAULT_INIT_TIMEOUT_SEC;
-        const initNonce = genNonce();
-        await new Promise((resolve, reject) => {
-            const timer = setTimeout(() => {
-                this.opts.channel.kill();
-                reject(new Error(`[E_SESSION_START] remote pty session '${this.opts.key}' did not initialize in ${initTimeoutSec}s` +
-                    (this.diag().length > 0 ? `; transport stderr tail: ${this.diag()}` : '')));
-            }, initTimeoutSec * 1_000);
-            const waiter = () => {
-                clearTimeout(timer);
-                reject(new Error(`[E_SESSION_DIED] remote pty session '${this.opts.key}' died before initializing` +
-                    (this.diag().length > 0 ? `; transport stderr tail: ${this.diag()}` : '')));
-            };
-            this.deathWaiters.push(waiter);
-            const parser = createNonceFrameParser(initNonce, {
-                onFrame: () => {
-                    clearTimeout(timer);
-                    this.deathWaiters = this.deathWaiters.filter((w) => w !== waiter);
-                    if (this.state === 'disposed') {
-                        // dispose 竞态 init：不得复活已终态会话（否则重挂 idle timer + 幽灵 ready）
-                        reject(new Error(`[E_SESSION_DISPOSED] remote pty session '${this.opts.key}' disposed during init`));
-                        return;
-                    }
-                    this.state = 'ready';
-                    this.resetIdleTimer();
-                    resolve();
-                },
-            });
-            this.onChunk = (c) => parser.feed(c);
-            this.opts.channel.open((chunk) => this.onChunk?.(chunk))
-                .catch((err) => {
-                clearTimeout(timer);
-                this.deathWaiters = this.deathWaiters.filter((w) => w !== waiter);
-                reject(err instanceof Error ? err : new Error(String(err)));
-            });
-            this.write(buildInitCommand(initNonce));
-        });
-    }
-    diag() { return this.opts.channel.diag; }
-    markDead() {
-        if (this.state === 'disposed') {
-            // dispose 是终态：不再翻转 state，但在飞 dispatch 的死亡等待仍需立即结算
-            // （row teardown 不是超时——不得等 123s 看门狗，也不得错标 timedOut）
-            const waiters = this.deathWaiters;
-            this.deathWaiters = [];
-            for (const w of waiters)
-                w();
-            return;
-        }
-        this.state = 'dead';
-        this.startPromise = null;
-        this.clearIdleTimer();
-        const waiters = this.deathWaiters;
-        this.deathWaiters = [];
-        for (const w of waiters)
-            w();
-    }
-    resetIdleTimer() {
-        this.clearIdleTimer();
-        this.idleTimer = setTimeout(() => void this.dispose(), this.opts.idleTtlSec * 1_000);
-        this.idleTimer.unref();
-    }
-    clearIdleTimer() {
-        if (this.idleTimer !== null) {
-            clearTimeout(this.idleTimer);
-            this.idleTimer = null;
-        }
-    }
-}
-/** 会话池：键 → 会话。意外死亡的会话留在池内（下次 dispatch 带 reconnect 提示）。 */
-export class PtyPool {
-    defaults;
-    sessions = new Map();
-    constructor(defaults) {
-        this.defaults = defaults;
-    }
-    get size() { return this.sessions.size; }
-    /** status 面：键上的会话快照（无会话 = undefined → "none — dials on first exec"）。 */
-    inspect(key) {
-        return this.sessions.get(key)?.snapshot;
-    }
-    /** roster 面：池内全部会话。 */
-    list() {
-        return [...this.sessions.entries()].map(([key, s]) => ({ key, snapshot: s.snapshot }));
-    }
-    getOrCreate(key, channelOf) {
-        let s = this.sessions.get(key);
-        if (s === undefined || s.sessionState === 'disposed') {
-            s = new PtySession({ key, channel: channelOf(), ...this.defaults, onDead: () => this.sessions.delete(key) });
-            this.sessions.set(key, s);
-        }
-        return s;
-    }
-    async disposeAll() {
-        await Promise.all([...this.sessions.values()].map((s) => s.dispose()));
-        this.sessions.clear();
-    }
-}