@windsland52/maafw-live 0.0.0-stage → 0.4.0

package/lib/runtime/session-ipc.js

@@ -0,0 +1,471 @@
+/**
+ * 命名会话（`repl --session <name>`）的 IPC 面。
+ *
+ * 为什么需要它（本仓 G12）：daemon 连接是**进程态**——帧流、L0 热缓存、事件环都活在
+ * repl 会话里，而一次性命令退出即销毁。此前想跨命令复用，只能自建常驻驱动
+ * （`repl-driver.mjs` 那种：spawn 一个 repl、持续喂 stdin、把 stdout 落盘、再读文件）。
+ * 每个使用者都重写一遍同一套东西，且各有各的坑（stdin 不是管道、shim 引号、EOF 即退出）。
+ *
+ * 这里把那条驱动收进工具本体：`--session <name>` 首次调用时**脱离父进程**起一个常驻
+ * repl（daemon 随之长活），后续同 name 的调用把命令行经命名管道送进去、把回执读回来。
+ *
+ * 三个设计约束（都是踩过的坑，不是偏好）：
+ *
+ * ① **不能用 stdin 喂**：PowerShell 没法把命名管道当 stdin 递给子进程（本仓
+ *    `.live/repl-driver.mjs` 头注释记的就是这条）。所以常驻进程走 `--session-serve`
+ *    从**命名管道**读命令，而不是从 stdin。
+ *
+ * ② **必须脱离父进程**：常驻进程若挂在调用方的作业对象下，父命令一退就被一起收走，
+ *    第二次调用就找不到会话了。Windows 上用 detached + unref。
+ *
+ * ③ **回执要有边界**：管道是字节流，多行回执之间必须能切分。用「一行一条 JSON 信封」，
+ *    每条命令带 id，调用方读到自己的 id 为止——不靠 sleep 猜，也不靠读空判断。
+ *
+ * 命名空间按 **用户 + 会话名** 隔离，会话名做白名单清洗（它要进文件路径与管道名，
+ * 不能让 `..` 或路径分隔符穿过去）。
+ */
+import { createServer, connect } from 'node:net';
+import { spawn, spawnSync } from 'node:child_process';
+import { closeSync, existsSync, lstatSync, mkdirSync, openSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { cliPackage } from '../pkg.js';
+/** 会话名白名单：字母数字与 `-` `_`，1..48 字符。要进管道名与文件路径，必须收紧。 */
+export function validSessionName(name) {
+    return /^[A-Za-z0-9_-]{1,48}$/.test(name);
+}
+/** 会话目录：`~/.maafw-live/sessions/<name>/`（与 frames 同级，都是本工具的本地状态）。 */
+export function sessionDir(name) {
+    return join(homedir(), '.maafw-live', 'sessions', name);
+}
+/** Windows 命名管道名；其它平台用 Unix domain socket 文件（同一份代码，两个平台都能跑）。
+ *
+ * ⚠️ 返回 Unix socket **路径**时会落在 `sessionDir(name)/sock` 下，所以调用方必须先确保
+ * 该目录存在（`ensureSessionDir`）——`listen()` 对不存在的父目录直接 ENOENT。
+ * Windows 命名管道在 `\\.\pipe\` 命名空间里，与文件系统无关，不需要建目录。 */
+export function sessionPipePath(name) {
+    if (process.platform === 'win32')
+        return `\\\\.\\pipe\\maafw-live-${name}`;
+    return join(sessionDir(name), 'sock');
+}
+/** 平台无关的"管道父目录就绪"：Windows 上是空操作（命名管道不走文件系统）。 */
+export function ensureSessionDir(name) {
+    if (process.platform === 'win32')
+        return;
+    mkdirSync(sessionDir(name), { recursive: true });
+}
+export function sessionMetaPath(name) {
+    return join(sessionDir(name), 'meta.json');
+}
+export function readSessionMeta(name) {
+    const p = sessionMetaPath(name);
+    if (!existsSync(p))
+        return null;
+    try {
+        return JSON.parse(readFileSync(p, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+/** 进程还活着吗（`process.kill(pid, 0)` 不真发信号，只做存在性检查）。 */
+export function pidAlive(pid) {
+    if (!Number.isFinite(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (e) {
+        /* EPERM = 进程存在但没权限发信号，仍算活着；ESRCH 才是没了 */
+        return e.code === 'EPERM';
+    }
+}
+/** 常驻侧：把 repl 的输出按"命令"切段回给调用方。 */
+export class SessionServer {
+    onLine;
+    onExec;
+    server = null;
+    sockets = new Set();
+    /** 串行队列：会话共用一条设备连接，命令必须一条条跑完再下一条 */
+    pending = [];
+    buffer = [];
+    current = null;
+    /**
+     * @param onLine  REPL 行解释器（旧 kind=line 路径）
+     * @param onExec  argv 分发器（kind=exec）：注入常驻 client 后走 dispatchArgv，
+     *                回执里带结构化 CommandResult——`--session` 下的 --json 信封靠它才存在。
+     *                不给时 exec 请求回 UNSUPPORTED（防"静默按 line 跑了别的命令"）。
+     */
+    constructor(onLine, onExec) {
+        this.onLine = onLine;
+        this.onExec = onExec;
+    }
+    /** 供 repl 循环调用：把一行输出归到当前命令的回执里。
+     *
+     * **没有当前命令时不是丢弃，而是挂到"待认领"队列**：`run` 这类命令是异步收尾的
+     * （提交后立刻返回，`run 完成…` 稍后才打），而回执在那之前就发出去了——丢掉的话
+     * 调用方永远看不到任务结果。挂起来随下一条命令的回执一起给，轮询式用法正好能拿到。
+     * 队列有上限：没人认领时不能无限涨（常驻会话可能几天没人问）。 */
+    pushOutput(line) {
+        if (!this.current) {
+            this.unclaimed.push(line);
+            if (this.unclaimed.length > 200)
+                this.unclaimed.splice(0, this.unclaimed.length - 200);
+            return;
+        }
+        this.buffer.push(line);
+    }
+    /** 连接横幅等：等价于"还没有命令时打的输出"，与异步收尾共用同一条待认领队列。 */
+    pushStartup(line) {
+        this.pushOutput(line);
+    }
+    unclaimed = [];
+    reply(r) {
+        const cur = this.current;
+        if (!cur)
+            return;
+        this.current = null;
+        /* 一律以服务端缓冲为准：调用方给的 lines 只是形状占位，不能覆盖实际输出 */
+        const payload = {
+            id: cur.id, ok: r.ok,
+            ...(r.error ? { error: r.error } : {}),
+            ...(r.closing ? { closing: true } : {}),
+            ...(r.result ? { result: r.result } : {}),
+            lines: this.buffer,
+        };
+        this.buffer = [];
+        try {
+            cur.socket.write(JSON.stringify(payload) + '\n');
+        }
+        catch {
+            /* 调用方可能已断开（超时先走），不影响会话继续 */
+        }
+    }
+    listen(pipe) {
+        return new Promise((resolve, reject) => {
+            /* POSIX 下 socket 是**文件**：进程被强杀时文件会留下，再 listen 就是 EADDRINUSE
+             * （Windows 命名管道随进程消失，没有这个问题）。所以先清掉残留的 socket 文件——
+             * 但只清"确实是 socket"的，不误删普通文件。 */
+            if (process.platform !== 'win32') {
+                try {
+                    if (lstatSync(pipe).isSocket())
+                        rmSync(pipe, { force: true });
+                }
+                catch {
+                    /* 不存在或不是 socket：都不用管 */
+                }
+            }
+            const server = createServer((socket) => {
+                this.sockets.add(socket);
+                socket.setEncoding('utf8');
+                let buf = '';
+                socket.on('data', (chunk) => {
+                    buf += chunk;
+                    let i;
+                    while ((i = buf.indexOf('\n')) >= 0) {
+                        const raw = buf.slice(0, i);
+                        buf = buf.slice(i + 1);
+                        if (!raw.trim())
+                            continue;
+                        let req;
+                        try {
+                            req = JSON.parse(raw);
+                        }
+                        catch {
+                            socket.write(JSON.stringify({ id: -1, ok: false, lines: [], error: '请求不是合法 JSON' }) + '\n');
+                            continue;
+                        }
+                        /* 同一时刻只允许一条在跑：会话是**串行**的（共用一条设备连接，
+                         * 并发会让两条命令交错读同一份状态）。后到的排队等前一条回执。 */
+                        const run = () => {
+                            this.current = { id: req.id, socket };
+                            /* 待认领的输出（连接横幅、上一条异步命令的收尾）先给，再按本命令的
+                             * 实测输出追加——顺序即时间序，调用方读起来才与交互式 repl 一致。 */
+                            this.buffer = this.unclaimed.splice(0, this.unclaimed.length);
+                            const finish = (r) => {
+                                this.reply(r);
+                                const next = this.pending.shift();
+                                if (next)
+                                    next();
+                            };
+                            try {
+                                if (req.kind === 'exec' && this.onExec) {
+                                    this.onExec(req.argv ?? [], finish);
+                                }
+                                else if (req.kind === 'exec') {
+                                    finish({ ok: false, error: '这个常驻进程不支持 exec 请求（请重启会话）' });
+                                }
+                                else {
+                                    this.onLine(String(req.line ?? ''), finish);
+                                }
+                            }
+                            catch (e) {
+                                finish({ ok: false, error: e instanceof Error ? e.message : String(e) });
+                            }
+                        };
+                        if (this.current)
+                            this.pending.push(run);
+                        else
+                            run();
+                    }
+                });
+                socket.on('error', () => this.sockets.delete(socket));
+                socket.on('close', () => this.sockets.delete(socket));
+            });
+            server.on('error', reject);
+            server.listen(pipe, () => {
+                this.server = server;
+                resolve();
+            });
+        });
+    }
+    close() {
+        for (const s of this.sockets) {
+            try {
+                s.destroy();
+            }
+            catch {
+                /* ignore */
+            }
+        }
+        this.sockets.clear();
+        try {
+            this.server?.close();
+        }
+        catch {
+            /* ignore */
+        }
+    }
+}
+/** 调用侧：把一条命令送到已存在的会话，等它那条回执。 */
+export async function sendToSession(meta, line, timeoutMs) {
+    return await new Promise((resolve, reject) => {
+        const sock = connect(meta.pipe);
+        const id = Date.now() % 1_000_000_000;
+        let buf = '';
+        const done = (fn) => {
+            clearTimeout(timer);
+            try {
+                sock.destroy();
+            }
+            catch {
+                /* ignore */
+            }
+            fn();
+        };
+        const timer = setTimeout(() => {
+            done(() => reject(new Error(`会话 '${meta.name}' 在 ${timeoutMs}ms 内没有回执（会话可能卡在一条长命令上；先 quit 再重试）`)));
+        }, timeoutMs);
+        sock.setEncoding('utf8');
+        sock.on('connect', () => sock.write(JSON.stringify({ id, line }) + '\n'));
+        sock.on('data', (chunk) => {
+            buf += chunk;
+            let i;
+            while ((i = buf.indexOf('\n')) >= 0) {
+                const raw = buf.slice(0, i);
+                buf = buf.slice(i + 1);
+                if (!raw.trim())
+                    continue;
+                let rep;
+                try {
+                    rep = JSON.parse(raw);
+                }
+                catch {
+                    continue;
+                }
+                if (rep.id !== id)
+                    continue;
+                done(() => resolve(rep));
+                return;
+            }
+        });
+        sock.on('error', (e) => done(() => reject(e)));
+    });
+}
+/** 调用侧（v2）：把一条 argv 送到会话，等它那条带结构化 result 的回执。
+ * 与 sendToSession 共用同一条管道/协议，只是 kind/载荷不同。 */
+export async function sendToSessionExec(meta, argv, timeoutMs) {
+    return await new Promise((resolve, reject) => {
+        const sock = connect(meta.pipe);
+        const id = Date.now() % 1_000_000_000;
+        let buf = '';
+        const done = (fn) => {
+            clearTimeout(timer);
+            try {
+                sock.destroy();
+            }
+            catch {
+                /* ignore */
+            }
+            fn();
+        };
+        const timer = setTimeout(() => {
+            done(() => reject(new Error(`会话 '${meta.name}' 在 ${timeoutMs}ms 内没有回执（会话可能卡在一条长命令上；先 quit 再重试）`)));
+        }, timeoutMs);
+        sock.setEncoding('utf8');
+        sock.on('connect', () => sock.write(JSON.stringify({ id, kind: 'exec', argv }) + '\n'));
+        sock.on('data', (chunk) => {
+            buf += chunk;
+            let i;
+            while ((i = buf.indexOf('\n')) >= 0) {
+                const raw = buf.slice(0, i);
+                buf = buf.slice(i + 1);
+                if (!raw.trim())
+                    continue;
+                let rep;
+                try {
+                    rep = JSON.parse(raw);
+                }
+                catch {
+                    continue;
+                }
+                if (rep.id !== id)
+                    continue;
+                done(() => resolve(rep));
+                return;
+            }
+        });
+        sock.on('error', (e) => done(() => reject(e)));
+    });
+}
+/** 起一个脱离父进程的常驻会话（`--session-serve` 模式）。
+ *
+ * `stdio` 不能是 `'ignore'`：常驻进程起不来时（最典型的是 POSIX 上残留 socket 导致
+ * listen 失败），调用方只会看到"管道 20s 内不可连"，真因被吞掉——而 `listen` 的 EADDRINUSE
+ * 与"连接参数错"是完全不同的两件事。所以把它自己的 stdout/stderr 落到会话目录的
+ * `serve.log`，失败时读回来当诊断依据。 */
+export function spawnSessionServer(name, cliEntry, connectArgs) {
+    const dir = sessionDir(name);
+    mkdirSync(dir, { recursive: true });
+    const pipe = sessionPipePath(name);
+    const logPath = join(dir, 'serve.log');
+    let out = 'ignore';
+    try {
+        out = openSync(logPath, 'a');
+    }
+    catch {
+        out = 'ignore';
+    }
+    const args = [cliEntry, 'repl', '--session-serve', name, ...connectArgsToArgv(connectArgs)];
+    const child = spawn(process.execPath, args, {
+        detached: true,
+        stdio: ['ignore', out, out],
+        windowsHide: true,
+    });
+    child.unref();
+    if (typeof out === 'number') {
+        try {
+            closeSync(out);
+        }
+        catch {
+            /* ignore */
+        }
+    }
+    const meta = {
+        name,
+        pid: child.pid ?? 0,
+        pipe,
+        startedAt: new Date().toISOString(),
+        connectArgs,
+        cliVersion: cliPackage().version,
+    };
+    writeFileSync(sessionMetaPath(name), JSON.stringify(meta, null, 2));
+    return meta;
+}
+/** 读常驻进程自己的日志尾部（诊断"为什么起不来"）。 */
+export function sessionServeLogTail(name, lines = 12) {
+    const p = join(sessionDir(name), 'serve.log');
+    if (!existsSync(p))
+        return [];
+    try {
+        const all = readFileSync(p, 'utf8').split(/\r?\n/).filter((l) => l.trim() !== '');
+        return all.slice(-lines);
+    }
+    catch {
+        return [];
+    }
+}
+/** 连接参数 → argv（会话常驻进程用同一套 CLI 旗标启动，不另造一套参数面）。
+ *  布尔值只发裸旗标：`--raw true` 里的 `true` 会被 parseArgs 当成位置参数（用法错误），
+ *  而且"false"是字符串真值，传成参数就把语义反了。 */
+export function connectArgsToArgv(a) {
+    const out = [];
+    for (const [k, v] of Object.entries(a)) {
+        if (v === undefined || v === null || v === false)
+            continue;
+        if (v === true) {
+            out.push('--' + k);
+            continue;
+        }
+        out.push('--' + k, String(v));
+    }
+    return out;
+}
+/** 等管道可连（常驻进程起来要时间；轮询到超时为止，不靠固定 sleep）。 */
+export async function waitPipeReady(pipe, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+        const ok = await new Promise((resolve) => {
+            const sock = connect(pipe);
+            sock.on('connect', () => {
+                sock.destroy();
+                resolve(true);
+            });
+            sock.on('error', () => {
+                sock.destroy();
+                resolve(false);
+            });
+        });
+        if (ok)
+            return true;
+        if (Date.now() > deadline)
+            return false;
+        await new Promise((r) => setTimeout(r, 100));
+    }
+}
+/** 收掉一条会话（清 meta 与目录，管道随进程退出消失）。
+ * 进程树：server → daemon → agent（uv → venv-python → uv-python）。process.kill 只打
+ * 第一层——daemon 来不及收摊就死，agent 树整体孤儿化（实测两层 python 残留）。
+ * taskkill /T 按父链整棵收；uv 重 exec 出的中层会脱离父链漏掉，再补一刀：命令行带
+ * agent/main.py 且父进程已死的全是孤儿（活会话的 agent 父链必健在，不会误伤）。 */
+export function stopSession(name) {
+    const meta = readSessionMeta(name);
+    if (meta && pidAlive(meta.pid)) {
+        if (process.platform === 'win32') {
+            try {
+                spawnSync('taskkill', ['/pid', String(meta.pid), '/T', '/F'], { timeout: 10000 });
+            }
+            catch {
+                try {
+                    process.kill(meta.pid);
+                }
+                catch { /* ignore */ }
+            }
+            try {
+                const ps = 'Get-CimInstance Win32_Process|Where-Object{$_.CommandLine -match \'agent/main\\.py\'}|' +
+                    'Where-Object{-not (Get-Process -Id $_.ParentProcessId -ErrorAction SilentlyContinue)}|' +
+                    'ForEach-Object{try{Stop-Process -Id $_.ProcessId -Force -ErrorAction SilentlyContinue}catch{}}';
+                spawnSync('powershell', ['-NoProfile', '-NonInteractive', '-Command', ps], { timeout: 15000 });
+            }
+            catch {
+                /* ignore */
+            }
+        }
+        else {
+            try {
+                process.kill(meta.pid);
+            }
+            catch {
+                /* ignore */
+            }
+        }
+    }
+    try {
+        rmSync(sessionDir(name), { recursive: true, force: true });
+    }
+    catch {
+        /* ignore */
+    }
+}
+//# sourceMappingURL=session-ipc.js.map

package/lib/runtime/session.js

@@ -0,0 +1,135 @@
+import { loadInterface, resolveResourcePaths } from '../interface/index.js';
+import { planProject, connect } from './actions.js';
+import { runPretasks } from './pretask.js';
+export class SessionError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+        this.name = 'SessionError';
+    }
+}
+/** 需要设备时连一次；项目模式下先规划控制器再连（拒绝猜设备）。 */
+export async function ensureSession(client, o) {
+    if (!o.project && !o.kind)
+        return { connected: false };
+    if (o.project) {
+        /* pretask 要先于 planProject 的设备扫描：'启动模拟器'类 pretask 跑完设备才出现，
+         * 排在扫描之后冷启动永远跑不到（P0-2）。过滤所需的 controller / resource 名都能离线推出来
+         * （controller 覆盖或第一个声明；resource 覆盖或第一个），不需要先扫设备。 */
+        const preNotes = [];
+        if (o.pretask === true) {
+            const loaded = loadInterface(o.project);
+            if (!loaded.file)
+                throw new SessionError(loaded.problems[0]?.message ?? '未找到 interface.json', 'PLAN_FAILED');
+            const pre = await runPretasks({
+                loaded,
+                controllerName: o.controller ?? loaded.controllers[0]?.name ?? null,
+                resourceName: o.resource ?? loaded.resources[0]?.name ?? null,
+                ...(o.optionCases ? { optionCases: o.optionCases } : {}),
+                ...(o.optionFields ? { optionFields: o.optionFields } : {}),
+            });
+            preNotes.push(...pre.notes, ...pre.warns.map((w) => 'pretask 警告：' + w));
+            if (!pre.ok && pre.error)
+                throw new SessionError(pre.error.message, pre.error.code);
+        }
+        const planned = await planProject(client, o.project, {
+            controller: o.controller,
+            hwnd: o.hwnd,
+            address: o.address,
+            resource: o.resource,
+            manualTarget: o.target ?? undefined,
+            ...(o.cwd ? { cwd: o.cwd } : {}),
+        });
+        if (!planned.plan)
+            throw new SessionError(planned.error ?? '控制器规划失败', 'PLAN_FAILED');
+        if (!planned.plan.ok) {
+            const cands = (planned.plan.candidates ?? []).map((d) => d.name || d.id).slice(0, 10);
+            throw new SessionError(planned.plan.error + (cands.length ? '（候选：' + cands.join(' / ') + '）' : ''), planned.plan.code || 'PLAN_FAILED');
+        }
+        /* interface.json 的加载告警：加载成功不代表没问题（缺字段、被跳过的 task/option 都在
+         * problems[]）。此前整个文件加载失败才读第一条，加载成功的告警在 human 与 --json 都看不到。 */
+        const loadWarns = planned.loaded.problems.map((p) => 'interface 告警：' + p.message);
+        if (planned.resource?.error) {
+            throw new SessionError(planned.resource.error, 'RESOURCE_NOT_FOUND');
+        }
+        /* pretask 的位置是契约的一部分：PI 要求它在**连接 Controller 之前**跑完，非零退出即中止启动。
+         * 放到 connect 之后就不再是同一件事（控制器已经建出来了）。 */
+        const conn = await connect(client, { ...planned.plan.connect });
+        if (conn && conn.ok === false)
+            throw new SessionError(conn.error ?? '连接失败', 'CONNECT_FAILED');
+        return {
+            connected: true, plan: planned, session: conn.session ?? null,
+            /* 资源侧提示（多个条目适用、已替用户选了哪一个）与控制器提示同一条 human 通道 */
+            notes: [...(planned.plan.notes ?? []), ...(planned.resource?.notes ?? []), ...loadWarns, ...preNotes],
+            ...(conn.streamStopped === true ? { streamStopped: true } : {}),
+        };
+    }
+    const conn = await connect(client, {
+        kind: o.kind,
+        ...(o.target ? { target: o.target } : {}),
+        ...(o.shortSide ? { shortSide: o.shortSide } : {}),
+        ...(o.longSide ? { longSide: o.longSide } : {}),
+        ...(o.rawSize ? { rawSize: true } : {}),
+    });
+    if (conn && conn.ok === false)
+        throw new SessionError(conn.error ?? '连接失败', 'CONNECT_FAILED');
+    return {
+        connected: true, session: conn.session ?? null,
+        ...(conn.streamStopped === true ? { streamStopped: true } : {}),
+    };
+}
+/**
+ * 离线资源解析：只读 interface.json 拿资源目录，不扫设备、不连接。
+ *
+ * 为什么需要它：从关键帧库留存帧裁模板这条动线**不需要设备**（这正是"不可复现状态"的意义——
+ * 设备早已不在那个画面上）。但自匹配要加载资源，而资源声明在项目里。项目此刻只是资源的
+ * 来源，不是连接的对象，所以走 interface 的规划函数而不走 planProject（后者要扫设备）。
+ *
+ * 返回的是**整条链**（`resource.path[]` 按序叠加，末尾追加当前控制器的 `attach_resource_path`），
+ * 与在线规划同一份 `resolveResourcePaths`：只写 `resource.path` 会让 attach 进来的一段凭空消失。
+ */
+export function offlineResource(project, controller, resource, 
+/** `--resource` 相对路径的解析基准（CLI 的 --cwd） */
+cwd) {
+    const loaded = loadInterface(project);
+    if (!loaded.file) {
+        return {
+            paths: [], names: [], selected: null, controllerName: null,
+            error: loaded.problems[0]?.message ?? '未找到 interface.json',
+        };
+    }
+    const controllerName = controller ?? loaded.controllers[0]?.name ?? null;
+    const plan = resolveResourcePaths(loaded, controllerName ?? undefined, resource, cwd);
+    /* --resource 名字没匹配上且不是目录：离线路径同样拒绝（自匹配拿错资源集，
+     * 裁出来的模板整个不对）。 */
+    if (plan.error)
+        return { paths: [], names: [], selected: null, controllerName, error: plan.error };
+    return { paths: plan.paths, names: plan.names, selected: plan.selected, controllerName };
+}
+/**
+ * 连接结果的行渲染（human 输出与 --json 共用一份事实）。
+ * `verbose=false` 时压制 `note:` 行（多资源选择、连接来源等建议性说明）——
+ * 一次性命令每条都打同一串 note 是噪音；事实行（已连接/分辨率/资源路径）不受门控。
+ */
+export function describeSession(s, verbose = false) {
+    const lines = [];
+    if (!s.connected)
+        return lines;
+    const sess = s.session ?? {};
+    lines.push('已连接：' + String(sess.kind ?? '?') + ' ' + String(sess.target ?? '') +
+        (sess.name ? ' (' + String(sess.name) + ')' : ''));
+    const res = sess.resolution;
+    if (res && res.w)
+        lines.push('  分辨率：' + res.w + 'x' + res.h);
+    if (s.plan) {
+        lines.push('  控制器：' + s.plan.controllerName + '（来自 interface.json）');
+        if (s.plan.resource?.paths.length)
+            lines.push('  资源：' + s.plan.resource.paths.join(' , '));
+    }
+    if (verbose)
+        for (const n of s.notes ?? [])
+            lines.push('  note: ' + n);
+    return lines;
+}
+//# sourceMappingURL=session.js.map

package/lib/runtime/signal-guard.js

@@ -0,0 +1,35 @@
+/**
+ * run 阻塞期信号处理（审计 #6/#9）：Ctrl-C / SIGTERM 时不许让 daemon 里的任务裸跑。
+ *
+ * 第一下：向 daemon 发 run_stop（post_stop），run 回执照常落盘，退出码走 128+signo
+ * （SIGINT=130 / SIGTERM=143）。第二下：直接退出——第一次没杀掉说明 daemon 已不应答，
+ * 再等没有现场可留（daemon 侧另有 onHostGone 兜底清 agent 树）。
+ *
+ * 为什么抽出来：Windows 没法跨进程投递 Ctrl-C，内联在命令里就没法测；
+ * process.emit('SIGINT') 会同步触发监听，单测只验"旗标立了、run_stop 发了"。
+ */
+import { EXIT } from '../protocol.js';
+/** 挂载信号守卫；`runStop` 是"给 daemon 发停止"的那个异步调用。 */
+export function installRunSignalGuard(runStop) {
+    let code = 0;
+    const on = (c) => () => {
+        if (code) {
+            process.exit(c);
+        } // 第二下：daemon 不应答，不再等
+        code = c;
+        void runStop().catch(() => { });
+    };
+    const sigint = on(EXIT.SIGINT);
+    const sigterm = on(EXIT.SIGTERM);
+    process.on('SIGINT', sigint);
+    process.on('SIGTERM', sigterm);
+    return {
+        get code() { return code; },
+        restore() {
+            process.off('SIGINT', sigint);
+            process.off('SIGTERM', sigterm);
+            return code;
+        },
+    };
+}
+//# sourceMappingURL=signal-guard.js.map