@windsland52/maafw-live 0.3.0 → 0.4.0

package/lib/commands/repl.js

@@ -8,20 +8,41 @@
  * 既能交互用，也能被脚本/agent 用管道驱动：printf 'probe\nquit\n' | maafw-live repl
  */
 import readline from 'node:readline';
+import { resolve } from 'node:path';
 import { spawnDaemon } from '../client/daemon.js';
-import { EXIT } from '../protocol.js';
+import { EXIT, fail } from '../protocol.js';
 import * as act from '../runtime/actions.js';
 import { defaultFramesDir, describeRecord, loadManifest, resolveFrame } from '../runtime/keyframes.js';
+import { roiOutOfBounds } from '../runtime/reco-args.js';
+import { readNodeFile, readParamFile } from '../runtime/node-source.js';
+import { describeMisses } from '../runtime/reco-verdict.js';
+import { ocrModelStatus } from '../runtime/ocr-model.js';
+import { ocrModelName, suggestThreshold } from './reco.js';
 import { ensureSession, SessionError } from '../runtime/session.js';
+import { writeRunReceipt } from '../runtime/receipts.js';
+import { ensureSessionDir, pidAlive, readSessionMeta, sendToSession, sendToSessionExec, SessionServer, sessionPipePath, sessionServeLogTail, spawnSessionServer, stopSession, validSessionName, waitPipeReady, } from '../runtime/session-ipc.js';
+/* 不能 import './index.js' 拿 findCommand：commands/index 也 import 本模块（replCommand），
+ * 循环依赖会在"谁先进来"那条路径上炸（Cannot access before initialization）。
+ * 真命令名清单就地维护——新命令加进 commands/index 时在这里补一行。 */
+const EXEC_HEADS = new Set([
+    'annotate', 'calibrate', 'color', 'connect', 'crop', 'device', 'disconnect', 'env',
+    'events', 'frame', 'kf', 'probe', 'reco', 'roi-check', 'roi-compare', 'run', 'screencap',
+    'stop', 'timing', 'version', 'wait',
+    /* 手势命令与 input.ts 同名，直接走 exec */
+    'click', 'swipe', 'key', 'keys', 'press', 'dbclick', 'scroll', 'move', 'text',
+]);
 import { CONNECT_OPTIONS, sessionOptions } from './runtime.js';
+import { dispatchArgv } from './dispatch.js';
+import { parseOptionArgs } from '../option-args.js';
+import { cliPackage } from '../pkg.js';
 const HELP = [
     '命令：',
     '  probe                          自检运行时',
     '  device [all|adb|win32]         列设备',
     '  connect <win32|adb|gamepad> [target]   手动连接',
     '  connect project <dir> [hwnd|address]   按 interface.json 规划连接（推荐）',
-    '  disconnect                     断开并销毁 Tasker/Controller',
-    '  screencap [out.png]            截一帧落盘（同时进 L0，可升格）',
+    '  disconnect                     断开并销毁 Tasker/Resource/Controller',
+    '  screencap [out.png] | screencap --out out.png    截一帧落盘（同时进 L0，可升格）',
     '  stream start [--fps n] [--scale n] [--l0-roll n] [--l0-anchor n] [--max-frames n] [--block-thresh n] [--change-global n] [--l0-bytes n]',
     '  stream stop | stream status',
     '  frame [seq] [--roi x,y,w,h] [--src auto|full|ring] [--out f.png]   取帧（--src full = 控制器分辨率原图）',
@@ -32,36 +53,89 @@ const HELP = [
     '  annotate [--out f.png] [--som-limit n] [--som-max-area-ratio r] [--from-kf kf:...]   SoM 候选与编号回画（回画优先全分辨率；库帧路径离线、diff 不可用）',
     '  events [n]                     最近 n 条帧流事件（默认 10）',
     '  logs [n]                       daemon 原生 stderr 尾部（默认 20）',
-    '  run <entry> [--timeout ms|0] [--override json] [--resource-dir d]   （异步执行，不阻塞提示符）',
+    '  run <entry> [--timeout ms|0] [--preset name] [--override json] [--resource-dir d] [--watch]   （异步执行，不阻塞提示符；--watch 持续打节点转移；项目模式叠四级 override）',
     '  stop                           停止运行中的任务',
     '  click <x> <y> | swipe <x1> <y1> <x2> <y2> [--duration ms] [--via "x,y;x,y"] | key <code> | text <string>',
     '       swipe --via 走 touch_down→逐点 touch_move→touch_up：**一条笔画画折线**（中途不抬手）',
     '  press <x> <y> [--duration ms] | dbclick <x> <y> | keys <c[,c+..]> | scroll <dx> <dy> | move <dx> <dy>',
     '  touchdown <x> <y> | touchmove <x> <y> | touchup       裸触点原语（跨命令维持同一次按压）',
-    '  reco <type> [k=v ...] [--sweep json]   识别单测（用缓冲最新帧）',
+    '  reco <type> [k=v ...] [--param-file p.json] [--image f.png|kf:…] [--seq n] [--from-kf kf:…] [--resource-dir d] [--sweep json]',
+    '       reco [--node-file node.json | --node-name <节点名>]   （资源取整条链；节点来源与参数来源互斥）',
+    '       识别单测。缺省用会话缓冲最新帧（L1 小图，roi 要按该图尺寸给）；--image 走文件',
+    '       （控制器空间，roi 用 ctrl 坐标）；--from-kf 走库内留存帧、离线。roi 必须给数组：',
+    '       `roi=1,2,3,4`（逗号写法即可，不必写方括号）。',
     '  kf status | kf promote [seq|latest] [--note s] | kf list | kf resolve <kf:...>',
     '  help | quit',
 ];
-/** 极简分词：空格分隔，支持 --flag value 与 key=value；text 用整行剩余内容。
+/** 分词：空格分隔，支持 --flag value 与 key=value；text 用整行剩余内容。
  *
- * **成对引号要剥掉**：脚本与 agent 习惯把带逗号的参数写进引号（`--roi "470,10,180,110"`），
+ * **引号要剥掉**：脚本与 agent 习惯把带逗号的参数写进引号（`--roi "470,10,180,110"`），
  * 不剥就整串当参数：`Number('"470')` = NaN → 走 JSON 变 null → daemon `Number(null)` = 0，
  * 于是退化成一个**合法但错误**的框（实测 `--roi "400,20,200,60"` 变成 `w=200,h=0`）且不报错。
- * 剥引号让"带引号"与"不带引号"等价——这是调用方最自然的写法。 */
+ * 剥引号让"带引号"与"不带引号"等价——这是调用方最自然的写法。
+ *
+ * **引号内的空格不是分隔符**：只按 `/\s+/` 切再逐 token 剥首尾引号，会把带空格的引号参数切碎，
+ * 且残片各自都不成对、于是**原样留着引号**：`--note "活动大厅 主界面"` 变成
+ * `--note '"活动大厅'`（`readFlag` 只取下一个 token）——数据侧被污染成"截断 + 残留引号"，
+ * 而 `kf promote` 照收不误，`kf list` 里看起来像是显示层截断。同一个坑对
+ * `--expected "选择 领队"`、`--override '{...带空格...}'` 一样成立。
+ *
+ * 所以这里按字符扫描：引号内的空白并入当前 token，引号本身不产出。
+ * `\` 只转义引号与 `\` 自身（Windows 路径里的反斜杠必须原样保留）。
+ * 未闭合的引号按"到行尾"收，并把内容原样给出——参数校验层会拿它报错，不在这里静默吞掉。 */
 function tokenize(line) {
-    return line.trim().split(/\s+/).filter((t) => t !== '').map((t) => {
-        if (t.length >= 2) {
-            const a = t[0], z = t[t.length - 1];
-            if ((a === '"' && z === '"') || (a === "'" && z === "'"))
-                return t.slice(1, -1);
+    const tokens = [];
+    let cur = '';
+    let quote = null;
+    let has = false;
+    for (let i = 0; i < line.length; i++) {
+        const ch = line[i];
+        if (quote) {
+            if (ch === '\\' && (line[i + 1] === quote || line[i + 1] === '\\')) {
+                cur += line[++i];
+                continue;
+            }
+            if (ch === quote) {
+                quote = null;
+                continue;
+            }
+            cur += ch;
+            continue;
         }
-        return t;
-    });
+        if (ch === '"' || ch === "'") {
+            quote = ch;
+            has = true;
+            continue;
+        }
+        if (/\s/.test(ch)) {
+            if (has) {
+                tokens.push(cur);
+                cur = '';
+                has = false;
+            }
+            continue;
+        }
+        cur += ch;
+        has = true;
+    }
+    if (has)
+        tokens.push(cur);
+    return tokens;
 }
 function readFlag(tokens, name) {
     const i = tokens.indexOf(name);
     return i >= 0 ? tokens[i + 1] : undefined;
 }
+/** `--option` 这类**可多次出现**的旗标：readFlag 只返回第一次出现的值（后面几次静默丢）。
+ * REPL 里 run --option a=b --option c=d 丢一半配置是最坏的假信号，必须收全。 */
+function readFlagAll(tokens, name) {
+    const out = [];
+    for (let i = 0; i < tokens.length; i++) {
+        if (tokens[i] === name && tokens[i + 1] !== undefined)
+            out.push(tokens[i + 1]);
+    }
+    return out;
+}
 /**
  * 取 count 个数字参数；任何一个不是有限数就返回 null。
  *
@@ -87,6 +161,77 @@ function numFlag(tokens, name, def) {
     const n = Number(raw);
     return Number.isFinite(n) ? n : null;
 }
+/** reco 的 k=v 里**期望数组**的参数：单值写法（`roi=558,68,140,43`）必须落成数组。
+ *
+ * 为什么不能靠"看起来像数字"自动判断：`Number("558,68,140,43")` = NaN，于是旧代码把整串
+ * 当字符串发出去，而 MaaFW 只认 `is_array()` —— 字符串被当**节点名**解析，回执 `ok:false`
+ * 且无置信度，看起来像"模板没读到"。本文件里另外 8 处（frame/crop/color/wait/annotate/swipe）
+ * 早就按逗号拆了，`reco` 是唯一遗漏。
+ *
+ * 为什么只列 `roi`：它是 MaaFW 里唯一"不给数组就必然用错空间"的参数（`roi` 也覆盖了
+ * `roi_offset` 这类同族标量写法，那些在 pipeline 里可以是单值，不擅自升级）。`expected`
+ * 不动——OCR 的 expected 字符串与数组**都命中**（实测），按逗号拆文本是凭空造规则。 */
+const RECO_ARRAY_PARAMS = ['roi'];
+/** `[...]` / `a,b,c` 两种数组写法都收；有一个不是有限数就退回原字符串（不猜、不静默改成 NaN）。 */
+function coerceRecoList(v) {
+    const body = v.startsWith('[') && v.endsWith(']') ? v.slice(1, -1) : v;
+    const parts = body.split(',').map((x) => x.trim());
+    if (parts.some((x) => x === ''))
+        return null;
+    const nums = parts.map((x) => Number(x));
+    return nums.every((n) => Number.isFinite(n)) ? nums : null;
+}
+/** repl `reco <type> k=v …` 的参数解析：沿用既有惯例（数字转 number），列表参数转数组。 */
+export function recoParam(tokens) {
+    const param = {};
+    for (const t of tokens.slice(2)) {
+        const eq = t.indexOf('=');
+        if (eq <= 0)
+            continue;
+        const k = t.slice(0, eq);
+        const v = t.slice(eq + 1);
+        if (RECO_ARRAY_PARAMS.includes(k) && (v.includes(',') || (v.startsWith('[') && v.endsWith(']')))) {
+            param[k] = coerceRecoList(v) ?? v;
+            continue;
+        }
+        param[k] = Number.isFinite(Number(v)) && v !== '' ? Number(v) : v;
+    }
+    return param;
+}
+/** 库帧来源解析（`--from-kf kf:…` 与 `--image kf:…` 共用）：与一次性 CLI 同一份离线读侧。 */
+function kfSourceFrom(id, tokens) {
+    const dir = readFlag(tokens, '--frames-dir') ?? defaultFramesDir();
+    const rr = resolveFrame(dir, id);
+    if (rr.status !== 'available' || !rr.path || !rr.record) {
+        return { error: '库帧不可用（' + rr.status + '）：' + String(rr.reason ?? '') + '（库 ' + dir + '）' };
+    }
+    return {
+        source: {
+            id: rr.record.id, path: rr.path, sha256: rr.record.sha256,
+            ctrlW: rr.record.ctrlW, ctrlH: rr.record.ctrlH,
+            captureSeq: rr.record.captureSeq, capturedAt: rr.record.capturedAt,
+        },
+    };
+}
+/** `screencap` 的参数面：**只认 `--out`**。
+ *
+ * 为什么在这里单独做白名单、而不是全局"位置参数不许以 -- 开头"：本文件的 `text` 吃整行剩余，
+ * `frame`/`crop`/`wait`/`swipe --via` 各有自己的旗标表，全局规则会误伤。而 screencap 的坏参数
+ * 特别贵：旧写法把 `--out` 当**位置参数**，于是真写出一个名为 `--out` 的文件（`ok:true` 掩盖），
+ * 而 CLI 的 `screencap --out x.png` 是对的——同一条链路上两套规则，谁都记不住哪边对。 */
+function screencapArgs(tokens) {
+    const out = readFlag(tokens, '--out');
+    const positionals = tokens.slice(1).filter((t) => !t.startsWith('--') && t !== out);
+    const unknown = tokens.slice(1).filter((t) => t.startsWith('--') && t !== '--out');
+    if (unknown.length) {
+        return { error: 'screencap 只认 --out <png>（收到未知选项 ' + unknown.join(' ') + '）；位置参数写法同样可用' };
+    }
+    if (positionals.length > 1) {
+        return { error: 'screencap 只写一个文件（收到 ' + positionals.length + ' 个位置参数：' + positionals.join(' ') + '）' };
+    }
+    const path = out ?? positionals[0];
+    return path === undefined ? {} : { out: path };
+}
 function short(v, max = 400) {
     const s = typeof v === 'string' ? v : JSON.stringify(v);
     return s.length > max ? s.slice(0, max) + ' …' : s;
@@ -131,9 +276,42 @@ function suggestHead(name, maxDistance = 3) {
 export const replCommand = {
     name: 'repl',
     summary: '交互/管道会话：连接一次，后续命令复用同一个 daemon 与设备会话',
-    usage: 'maafw-live repl [--project <dir>|--kind win32|adb|gamepad [--target ...]]',
-    options: { ...CONNECT_OPTIONS },
+    usage: 'maafw-live repl [--project <dir>|--kind win32|adb|gamepad [--target ...]]\n' +
+        '       maafw-live repl --session <name> [--cmd <命令>]…   命名常驻会话：首次起、之后复用（不必自建驱动）\n' +
+        '        不带 --cmd：进入该会话的交互式提示符（等价于 repl，但连接状态跨调用保持）\n' +
+        '        带 --cmd：把命令送进常驻会话并打印回执；可给多个 --cmd，逐条串行执行\n' +
+        '          maafw-live repl --session cc --cmd "screencap a.png"\n' +
+        '          maafw-live repl --session cc --cmd "run CritterCrashEntry --timeout 0" --cmd "events 20"\n' +
+        '        **必须用 --cmd 传带选项的命令**：不加 --cmd 时参数会先被 repl 自己的选项表解析，\n' +
+        '        `repl --session cc run X --timeout 0` 里的 `--timeout` 会被当成 repl 的选项而报错\n' +
+        '       maafw-live repl --session <name> --session-status   看会话状态\n' +
+        '       maafw-live repl --session <name> --session-stop     收掉会话\n' +
+        '       --session-serve <name>  内部用：常驻侧（从命名管道读命令，不要手敲）',
+    options: {
+        ...CONNECT_OPTIONS,
+        session: { type: 'string' },
+        cmd: { type: 'string', multiple: true },
+        'session-status': { type: 'boolean' },
+        'session-stop': { type: 'boolean' },
+        'session-serve': { type: 'string' },
+    },
     async run(ctx) {
+        /* ── 常驻侧：`--session-serve` 从命名管道收命令，把 repl 的输出按条回给调用方 ──
+         * 这条分支不读 stdin（PowerShell 递不了管道给子进程），而是自己 listen。 */
+        const serveName = typeof ctx.values['session-serve'] === 'string' ? ctx.values['session-serve'] : undefined;
+        if (serveName !== undefined) {
+            if (!validSessionName(serveName)) {
+                return fail('BAD_ARGUMENTS', '会话名只允许字母数字与 - _（1..48 字符）', undefined, EXIT.USAGE);
+            }
+            return await runSessionServer(serveName, ctx);
+        }
+        const name = typeof ctx.values.session === 'string' ? ctx.values.session : undefined;
+        if (name !== undefined) {
+            if (!validSessionName(name)) {
+                return fail('BAD_ARGUMENTS', '会话名只允许字母数字与 - _（1..48 字符）：' + JSON.stringify(name), undefined, EXIT.USAGE);
+            }
+            return await runNamedSession(name, ctx);
+        }
         const client = spawnDaemon();
         const out = (line) => { process.stdout.write(line + '\n'); };
         const state = { session: '(未连接)', plan: null };
@@ -141,8 +319,12 @@ export const replCommand = {
             state.session = String(s.session?.target ?? '(已连接)');
             state.plan = s.plan ?? null;
         };
-        const o = sessionOptions(ctx.values);
+        const o = sessionOptions(ctx);
         if (o.project || o.kind) {
+            /* 起连 = 启动工作：pretask 要跑（--no-pretask 关）。项目 pretask 先于设备扫描，
+             * "启动模拟器"类脚本冷启动也到得了（P0-2）。 */
+            if (o.pretask === undefined)
+                o.pretask = true;
             try {
                 const s = await ensureSession(client, o);
                 remember(s);
@@ -189,510 +371,1131 @@ export const replCommand = {
         };
         try {
             for (;;) {
+                /* 提示符带连接状态：启动连接失败 / 主动 disconnect / daemon 层重连失败后
+                 * 显示「未连接」，别让一个裸 maa> 看起来像会话可用。 */
                 if (process.stdin.isTTY)
-                    process.stdout.write('maa> ');
+                    process.stdout.write(state.session === '(未连接)' ? 'maa(未连接)> ' : 'maa> ');
                 const line = await ask();
                 if (line === null)
                     break;
-                const tokens = tokenize(line);
-                if (!tokens.length)
-                    continue;
-                const head = tokens[0];
-                if (head === 'quit' || head === 'exit')
+                const step = await runReplLine(line, { client, out, state, remember });
+                if (step === 'quit')
                     break;
-                if (head === 'help') {
-                    for (const h of HELP)
-                        out(h);
-                    continue;
-                }
+            }
+        }
+        finally {
+            rl.close();
+            client.close();
+        }
+        return { exitCode: EXIT.OK, human: ['会话结束。'] };
+    },
+};
+async function runReplLine(line, rt) {
+    const { client, out, state, remember } = rt;
+    const tokens = tokenize(line);
+    if (!tokens.length)
+        return 'continue';
+    const head = tokens[0];
+    if (head === 'quit' || head === 'exit')
+        return 'quit';
+    if (head === 'help') {
+        for (const h of HELP)
+            out(h);
+        return 'continue';
+    }
+    try {
+        switch (head) {
+            case 'probe':
+                out(short(await act.probe(client)));
+                break;
+            case 'device':
+                out(short(await act.deviceList(client, tokens[1] ?? 'all')));
+                break;
+            case 'connect': {
+                let s;
                 try {
-                    switch (head) {
-                        case 'probe':
-                            out(short(await act.probe(client)));
-                            break;
-                        case 'device':
-                            out(short(await act.deviceList(client, tokens[1] ?? 'all')));
-                            break;
-                        case 'connect': {
-                            let s;
-                            if (tokens[1] === 'project') {
-                                s = await ensureSession(client, { project: tokens[2], hwnd: tokens[3], address: tokens[3] });
-                            }
-                            else {
-                                s = await ensureSession(client, { kind: tokens[1], target: tokens[2] });
-                            }
-                            remember(s);
-                            out('已连接：' + state.session);
-                            break;
-                        }
-                        case 'disconnect':
-                            out(short(await act.disconnect(client)));
-                            state.session = '(未连接)';
-                            break;
-                        case 'screencap':
-                            out(short(await act.screencap(client, tokens[1])));
-                            break;
-                        case 'stream': {
-                            const sub = tokens[1] ?? 'status';
-                            if (sub === 'start') {
-                                const fps = readFlag(tokens, '--fps');
-                                const scale = readFlag(tokens, '--scale');
-                                const blockThresh = readFlag(tokens, '--block-thresh');
-                                const changeGlobal = readFlag(tokens, '--change-global');
-                                const l0Bytes = readFlag(tokens, '--l0-bytes');
-                                /* 观测策略参数：l0-roll 决定"我有多久回看窗口"（默认 16 帧 ≈ 1.6s @10fps），
-                                 * max-frames 决定环形缓冲长度。协议本就支持，命令面必须可达——
-                                 * 不可达的参数会被调用方当成"没有"。 */
-                                const maxFrames = readFlag(tokens, '--max-frames');
-                                const l0Roll = readFlag(tokens, '--l0-roll');
-                                const l0Anchor = readFlag(tokens, '--l0-anchor');
-                                out(short(await act.streamStart(client, {
-                                    ...(fps ? { fps: Number(fps) } : {}),
-                                    ...(scale ? { scale: Number(scale) } : {}),
-                                    ...(blockThresh ? { blockThresh: Number(blockThresh) } : {}),
-                                    ...(changeGlobal ? { changeGlobal: Number(changeGlobal) } : {}),
-                                    ...(l0Bytes ? { l0Bytes: Number(l0Bytes) } : {}),
-                                    ...(maxFrames ? { maxFrames: Number(maxFrames) } : {}),
-                                    ...(l0Roll ? { l0Roll: Number(l0Roll) } : {}),
-                                    ...(l0Anchor ? { l0Anchor: Number(l0Anchor) } : {}),
-                                })));
-                            }
-                            else if (sub === 'stop')
-                                out(short(await act.streamStop(client)));
-                            else
-                                out(short(await act.streamStatus(client)));
-                            break;
-                        }
-                        case 'wait': {
-                            /* 状态谓词：等到条件成立再往下读，取代硬睡时钟。超时不算错误（satisfied=false）。 */
-                            const modeRaw = tokens[1];
-                            if (modeRaw !== 'stable' && modeRaw !== 'change') {
-                                out('用法：wait stable|change [--timeout ms] [--quiet ms] [--roi x,y,w,h] [--threshold n]'
-                                    + '（模式只认 stable / change'
-                                    + (modeRaw ? '；收到 ' + JSON.stringify(modeRaw)
-                                        + (suggestHead(modeRaw) ? '，是想输入 ' + String(suggestHead(modeRaw)) + ' 吗' : '') : '')
-                                    + '）');
-                                break;
-                            }
-                            /* 数值 flag 必须校验：`--timeout abc` 会变成 NaN 一路传下去，
-                             * 客户端超时算成 NaN → 调用秒超时，看起来像"工具坏了"。 */
-                            const numOr = (name) => {
-                                const raw = readFlag(tokens, name);
-                                if (raw === undefined)
-                                    return undefined;
-                                const n = Number(raw);
-                                return Number.isFinite(n) ? n : null;
-                            };
-                            const tmo = numOr('--timeout');
-                            const qt = numOr('--quiet');
-                            const thr = numOr('--threshold');
-                            if (tmo === null || qt === null || thr === null) {
-                                out('--timeout / --quiet / --threshold 必须是数字'
-                                    + (tmo === null ? '（--timeout 收到 ' + JSON.stringify(readFlag(tokens, '--timeout')) + '）' : ''));
-                                break;
-                            }
-                            const roiRaw = readFlag(tokens, '--roi');
-                            const r = await act.waitState(client, {
-                                mode: modeRaw,
-                                ...(tmo !== undefined ? { timeout: tmo } : {}),
-                                ...(qt !== undefined ? { quiet: qt } : {}),
-                                ...(thr !== undefined ? { threshold: thr } : {}),
-                                ...(roiRaw ? { roi: roiRaw.split(',').map((x) => Number(x)) } : {}),
-                            });
-                            out(short(r, 500));
-                            break;
-                        }
-                        case 'frame': {
-                            const roiRaw = readFlag(tokens, '--roi');
-                            const srcRaw = readFlag(tokens, '--src');
-                            const seq = tokens[1] && !tokens[1].startsWith('--') ? Number(tokens[1]) : undefined;
-                            if (tokens[1] === 'diff') {
-                                /* 两帧在若干 ROI 上的差分：离散网格要的是"哪几格变了"，不是整帧 bbox。 */
-                                const a = readFlag(tokens, '--a');
-                                const b = readFlag(tokens, '--b');
-                                const roisRaw = readFlag(tokens, '--rois');
-                                if (a === undefined || b === undefined || !roisRaw) {
-                                    out('用法：frame diff --a <seq> --b <seq> --rois "x,y,w,h;x,y,w,h"');
-                                    break;
-                                }
-                                const rois = roisRaw.split(';').map((s) => s.split(',').map((x) => Number(x)));
-                                if (rois.some((r) => r.length !== 4 || r.some((n) => !Number.isFinite(n)))) {
-                                    out('--rois 每段要 4 个数字，段间用 ; 分隔');
-                                    break;
-                                }
-                                const d = await act.frameDiff(client, { a: Number(a), b: Number(b), rois });
-                                out(short(d, 900));
-                                break;
-                            }
-                            out(short(await act.frameGet(client, {
-                                ...(seq !== undefined ? { seq } : {}),
-                                ...(roiRaw ? { roi: roiRaw.split(',').map((x) => Number(x)) } : {}),
-                                ...(readFlag(tokens, '--out') ? { out: readFlag(tokens, '--out') } : {}),
-                                ...(srcRaw ? { src: srcRaw } : {}),
-                            })));
-                            break;
-                        }
-                        case 'color': {
-                            const roiRaw = readFlag(tokens, '--roi');
-                            out(short(await act.colorProbe(client, {
-                                ...(roiRaw ? { roi: roiRaw.split(',').map((x) => Number(x)) } : {}),
-                            }), 400));
-                            break;
-                        }
-                        case 'crop': {
-                            const roiRaw = readFlag(tokens, '--roi');
-                            const pointRaw = readFlag(tokens, '--point');
-                            const padRaw = readFlag(tokens, '--pad');
-                            /* --from-kf：源换成库内留存帧（跨会话可用）。解析走与一次性 CLI 同一份离线读侧。 */
-                            const kfId = readFlag(tokens, '--from-kf');
-                            let kfSource;
-                            if (kfId) {
-                                const dir = readFlag(tokens, '--frames-dir') ?? defaultFramesDir();
-                                const rr = resolveFrame(dir, kfId);
-                                if (rr.status !== 'available' || !rr.path || !rr.record) {
-                                    out('库帧不可用（' + rr.status + '）：' + String(rr.reason ?? '') + '（库 ' + dir + '）');
-                                    break;
-                                }
-                                kfSource = {
-                                    id: rr.record.id, path: rr.path, sha256: rr.record.sha256,
-                                    ctrlW: rr.record.ctrlW, ctrlH: rr.record.ctrlH,
-                                    captureSeq: rr.record.captureSeq, capturedAt: rr.record.capturedAt,
-                                };
-                            }
-                            const ck = await act.tplCrop(client, {
-                                ...(roiRaw ? { roi: roiRaw.split(',').map((x) => Number(x)) } : {}),
-                                ...(pointRaw ? { point: pointRaw.split(',').map((x) => Number(x)) } : {}),
-                                ...(padRaw ? { pad: Number(padRaw) } : {}),
-                                ...(readFlag(tokens, '--out') ? { out: readFlag(tokens, '--out') } : {}),
-                                ...(kfSource ? { kfSource, cross: false } : {}),
-                                ...(readFlag(tokens, '--resource-dir')
-                                    ? { resourceDir: readFlag(tokens, '--resource-dir') }
-                                    : (state.plan?.resource?.paths.length ? { resourceDir: state.plan.resource.paths[0] } : {})),
-                            });
-                            out(short(ck, 600));
-                            if (ck.ok !== false && ck.provPath)
-                                out('L2 出处：' + String(ck.provPath));
-                            break;
-                        }
-                        case 'annotate': {
-                            /* --from-kf：源换成库内留存帧（离线；diff 源不可用，工具会如实报） */
-                            const kfSom = readFlag(tokens, '--from-kf');
-                            let somKf;
-                            if (kfSom) {
-                                const dir = readFlag(tokens, '--frames-dir') ?? defaultFramesDir();
-                                const rr = resolveFrame(dir, kfSom);
-                                if (rr.status !== 'available' || !rr.path || !rr.record) {
-                                    out('库帧不可用（' + rr.status + '）：' + String(rr.reason ?? '') + '（库 ' + dir + '）');
-                                    break;
-                                }
-                                somKf = {
-                                    id: rr.record.id, path: rr.path, sha256: rr.record.sha256,
-                                    ctrlW: rr.record.ctrlW, ctrlH: rr.record.ctrlH,
-                                    captureSeq: rr.record.captureSeq, capturedAt: rr.record.capturedAt,
-                                };
-                            }
-                            const somLimitRaw = readFlag(tokens, '--som-limit');
-                            const somLimit = somLimitRaw === undefined ? undefined : Number(somLimitRaw);
-                            if (somLimitRaw !== undefined && (!Number.isFinite(somLimit) || somLimit <= 0)) {
-                                out('--som-limit 必须是正整数（收到 ' + JSON.stringify(somLimitRaw) + '）；0 不等于"不限量"');
-                                break;
-                            }
-                            const somRatioRaw = readFlag(tokens, '--som-max-area-ratio');
-                            const somRatio = somRatioRaw === undefined ? undefined : Number(somRatioRaw);
-                            if (somRatioRaw !== undefined && (!Number.isFinite(somRatio) || somRatio <= 0 || somRatio >= 1)) {
-                                out('--som-max-area-ratio 要在 (0,1) 之间（收到 ' + JSON.stringify(somRatioRaw) + '）；0 不等于"关闭剔除"');
-                                break;
-                            }
-                            const r = await act.annotate(client, {
-                                ...(readFlag(tokens, '--out') ? { out: readFlag(tokens, '--out') } : {}),
-                                ...(somKf ? { kfSource: somKf } : {}),
-                                ...(somLimit !== undefined ? { somLimit } : {}),
-                                ...(somRatio !== undefined ? { somMaxAreaRatio: somRatio } : {}),
-                                ...(readFlag(tokens, '--roi') ? { roi: String(readFlag(tokens, '--roi')).split(',').map((x) => Number(x)) } : {}),
-                                ...(readFlag(tokens, '--resource-dir')
-                                    ? { resourceDir: readFlag(tokens, '--resource-dir') }
-                                    : (state.plan?.resource?.paths.length ? { resourceDir: state.plan.resource.paths[0] } : {})),
-                            });
-                            if (r.ok === false) {
-                                out('annotate 失败：' + String(r.error));
-                                break;
-                            }
-                            out('SoM ' + String(r.count) + ' 候选 → ' + String(r.out) + (somKf ? '（源：留存帧）' : ''));
-                            /* 可用性三列：不读它就会把"30 条"当成"画面就这些可点区域"。 */
-                            const av = r.availability;
-                            if (av) {
-                                out('  可用性：合并池 ' + String(av.mergedTotal ?? '?') + ' → 进表 ' + String(r.count)
-                                    + '（上限 ' + String(av.limit ?? '?') + '，截断 ' + String(av.truncated ?? 0) + '）'
-                                    + '；剔除 巨框 ' + String(av.dropped?.tooBig ?? 0) + ' / 重复 ' + String(av.dropped?.duplicated ?? 0));
-                                if (av.byBand)
-                                    out('  分带（上/中/下）进表/池：' + av.byBand.map((b) => String(b.inTable) + '/' + String(b.inPool)).join('  '));
-                                if (av.outResolution)
-                                    out('  回画分辨率：' + String(av.outResolution.w) + 'x' + String(av.outResolution.h) + '（' + String(av.outResolution.source) + '）');
-                            }
-                            for (const c of r.candidates ?? []) {
-                                out('  #' + c.id + ' [' + c.source + '] ctrl=' + c.ctrl.join(',')
-                                    + (typeof c.areaRatio === 'number' ? ' 面积比=' + c.areaRatio : '')
-                                    + (typeof c.score === 'number' ? ' score=' + c.score : '')
-                                    + (c.text ? '  "' + c.text + '"' : ''));
-                            }
-                            break;
-                        }
-                        case 'events': {
-                            const n = Number(tokens[1] ?? 10);
-                            const evs = client.events.events.slice(-n);
-                            out('事件 ' + evs.length + ' 条（共 ' + client.events.events.length + '）');
-                            for (const e of evs)
-                                out('  ' + short(e, 200));
-                            break;
-                        }
-                        case 'logs': {
-                            const n = Number(tokens[1] ?? 20);
-                            for (const l of client.logTail(n))
-                                out('  ' + l);
-                            break;
-                        }
-                        case 'run': {
-                            const entry = tokens[1];
-                            if (!entry) {
-                                out('用法：run <entry> [--timeout ms|0] [--override json] [--resource-dir d]');
-                                break;
-                            }
-                            /* 任务名 → pipeline 入口解析（与一次性 CLI 同规则）：interface 的 task 名（如中文
-                             * "启动游戏"）不是 pipeline 节点名，不解析会 task not exist 秒败 */
-                            const task = state.plan?.loaded.tasks.find((t) => t.name === entry || t.entry === entry);
-                            const resolvedEntry = task?.entry ?? entry;
-                            const timeout = Number(readFlag(tokens, '--timeout') ?? 30000);
-                            const overrideRaw = readFlag(tokens, '--override');
-                            let override = {};
-                            if (overrideRaw) {
-                                try {
-                                    override = JSON.parse(overrideRaw);
-                                }
-                                catch {
-                                    out('--override 不是合法 JSON');
-                                    break;
-                                }
-                            }
-                            /* 资源目录：--resource-dir 优先，其次当前项目规划（connect project 的 interface.json） */
-                            const resDirs = state.plan?.resource?.paths ?? [];
-                            const explicitDir = readFlag(tokens, '--resource-dir');
-                            if (!explicitDir && !resDirs.length) {
-                                out('缺资源：给 --resource-dir <dir>，或先 connect project <dir>');
-                                break;
-                            }
-                            /* 异步执行不阻塞提示符：--timeout 0 的长任务靠 stop 中断（同一条客户端连接） */
-                            out('已提交 ' + resolvedEntry + (task && task.name !== resolvedEntry ? '（任务 ' + task.name + '）' : '') + '（timeout=' + timeout + '，结果异步打印；stop 可中断）');
-                            const plan = state.plan;
-                            act.run(client, explicitDir
-                                ? { resourceDir: explicitDir, entry: resolvedEntry, override, timeoutMs: timeout }
-                                : {
-                                    resourceDirs: resDirs, entry: resolvedEntry, override, timeoutMs: timeout,
-                                    ...(plan?.loaded.agents.length
-                                        ? { agents: plan.loaded.agents.map((a) => ({ exec: a.exec, args: a.args })), agentCwd: plan.loaded.dir ?? undefined }
-                                        : {}),
-                                }, timeout)
-                                .then((r) => {
-                                const rec = r.record;
-                                out('run 完成：任务级 ' + (rec ? (rec.ok ? 'ok' : 'FAIL') : '未知') +
-                                    (rec?.agent ? '，agent ' + (rec.agent.ok ? '已连接' : '失败') : '') + '  ' + short(r, 700));
-                            })
-                                .catch((e) => out('run 失败：' + (e instanceof Error ? e.message : String(e))));
-                            break;
-                        }
-                        case 'stop':
-                            out(short(await act.runStop(client)));
-                            break;
-                        case 'click': {
-                            const a = nums(tokens, 1, 2);
-                            if (!a) {
-                                out('用法：click <x> <y>');
-                                break;
-                            }
-                            out(short(await act.input(client, { kind: 'click', x: a[0], y: a[1] })));
-                            break;
-                        }
-                        case 'swipe': {
-                            const a = nums(tokens, 1, 4);
-                            const duration = numFlag(tokens, '--duration', 300);
-                            if (!a || duration === null) {
-                                out('用法：swipe <x1> <y1> <x2> <y2> [--duration ms] [--via "x,y;x,y"]');
-                                break;
-                            }
-                            /* --via：中途路径点。走的是 touch_down→逐点 touch_move→touch_up —— **一条笔画画折线**，
-                             * 中途不抬手。连线/谱曲/拖拽排序这类玩法要的正是这个；只有两端点时走原生 post_swipe。 */
-                            const viaRaw = readFlag(tokens, '--via');
-                            let via;
-                            if (viaRaw) {
-                                via = viaRaw.split(';').map((s) => s.split(',').map((x) => Number(x)));
-                                if (via.some((p) => p.length !== 2 || p.some((n) => !Number.isFinite(n)))) {
-                                    out('--via 每段要 2 个数字（x,y），段间用 ; 分隔');
-                                    break;
-                                }
-                            }
-                            out(short(await act.input(client, {
-                                kind: 'swipe', x1: a[0], y1: a[1], x2: a[2], y2: a[3], duration,
-                                ...(via ? { via } : {}),
-                            })));
-                            break;
-                        }
-                        case 'touchdown': {
-                            const a = nums(tokens, 1, 2);
-                            if (!a) {
-                                out('用法：touchdown <x> <y>');
-                                break;
-                            }
-                            out(short(await act.input(client, { kind: 'touch_down', x: a[0], y: a[1] })));
-                            break;
-                        }
-                        case 'touchmove': {
-                            const a = nums(tokens, 1, 2);
-                            if (!a) {
-                                out('用法：touchmove <x> <y>');
-                                break;
-                            }
-                            out(short(await act.input(client, { kind: 'touch_move', x: a[0], y: a[1] })));
-                            break;
-                        }
-                        case 'touchup':
-                            out(short(await act.input(client, { kind: 'touch_up' })));
-                            break;
-                        case 'key': {
-                            const a = nums(tokens, 1, 1);
-                            if (!a) {
-                                out('用法：key <code>（Android KeyEvent 码：3=Home、4=返回）');
-                                break;
-                            }
-                            out(short(await act.input(client, { kind: 'key', code: a[0] })));
-                            break;
-                        }
-                        case 'keys': {
-                            /* 键码只保留正整数：与 CLI/daemon 同一条口径，空集合直接报用法 */
-                            const codes = String(tokens[1] ?? '').split(/[+,]/)
-                                .map((s) => Number(s.trim())).filter((n) => Number.isFinite(n) && n > 0);
-                            if (!codes.length) {
-                                out('用法：keys <code[,code+...]>（至少一个正整数键码，如 17,67）');
-                                break;
-                            }
-                            out(short(await act.input(client, { kind: 'keys', codes })));
-                            break;
-                        }
-                        case 'press': {
-                            const a = nums(tokens, 1, 2);
-                            const duration = numFlag(tokens, '--duration', 800);
-                            if (!a || duration === null) {
-                                out('用法：press <x> <y> [--duration ms]');
-                                break;
-                            }
-                            out(short(await act.input(client, { kind: 'press', x: a[0], y: a[1], duration })));
-                            break;
-                        }
-                        case 'dbclick': {
-                            const a = nums(tokens, 1, 2);
-                            if (!a) {
-                                out('用法：dbclick <x> <y>');
-                                break;
-                            }
-                            out(short(await act.input(client, { kind: 'dbclick', x: a[0], y: a[1] })));
-                            break;
-                        }
-                        case 'scroll': {
-                            const a = nums(tokens, 1, 2);
-                            if (!a) {
-                                out('用法：scroll <dx> <dy>（建议 120 的倍数）');
-                                break;
+                    if (tokens[1] === 'project') {
+                        /* 会话内手动重连也是一次"启动"：pretask 照跑（非零中止、超时 120s）。
+                         * --controller/--resource 补的是"连接 project 但挑哪套 controller/resource"——
+                         * 此前会话里选不了（P0-3 漂移点），一次性 CLI 早就有。 */
+                        s = await ensureSession(client, {
+                            project: tokens[2],
+                            ...(readFlag(tokens, '--controller') ? { controller: readFlag(tokens, '--controller') } : {}),
+                            ...(readFlag(tokens, '--resource') ? { resource: readFlag(tokens, '--resource') } : {}),
+                            hwnd: readFlag(tokens, '--hwnd') ?? tokens[3],
+                            address: readFlag(tokens, '--address') ?? tokens[3],
+                            pretask: !tokens.includes('--no-pretask'),
+                        });
+                    }
+                    else {
+                        s = await ensureSession(client, {
+                            kind: tokens[1],
+                            target: tokens[2],
+                            ...(readFlag(tokens, '--short-side') ? { shortSide: Number(readFlag(tokens, '--short-side')) } : {}),
+                            ...(readFlag(tokens, '--long-side') ? { longSide: Number(readFlag(tokens, '--long-side')) } : {}),
+                            ...(tokens.includes('--raw') ? { rawSize: true } : {}),
+                        });
+                    }
+                }
+                catch (e) {
+                    /* daemon 层连接失败时旧控制器已被销毁：摘要退回未连接（提示符会显示），
+                     * 但保留 state.plan——它只是项目规划，离线 reco/crop 仍可用。规划阶段的失败
+                     * 发生在 connect 之前，旧会话/控制器还在，摘要保持原样。 */
+                    if (e instanceof SessionError && e.code === 'CONNECT_FAILED')
+                        state.session = '(未连接)';
+                    throw e;
+                }
+                remember(s);
+                out('已连接：' + state.session);
+                break;
+            }
+            case 'disconnect':
+                out(short(await act.disconnect(client)));
+                state.session = '(未连接)';
+                break;
+            case 'screencap': {
+                /* --out 与位置参数都收（与 CLI 一致）；未知选项按上面白名单报错，不再写脏文件。 */
+                const a = screencapArgs(tokens);
+                if (a.error) {
+                    out(a.error);
+                    break;
+                }
+                const r = await act.screencap(client, a.out);
+                out(short(r));
+                /* 回执路径与请求路径不一致要说：调用方拿到的"写到哪了"必须可信 */
+                if (a.out && r.path && resolve(String(r.path)) !== resolve(a.out)) {
+                    out('警告：实际写入 ' + String(r.path) + '，与请求的 ' + a.out + ' 不一致');
+                }
+                break;
+            }
+            case 'stream': {
+                const sub = tokens[1] ?? 'status';
+                if (sub === 'start') {
+                    const fps = readFlag(tokens, '--fps');
+                    const scale = readFlag(tokens, '--scale');
+                    const blockThresh = readFlag(tokens, '--block-thresh');
+                    const changeGlobal = readFlag(tokens, '--change-global');
+                    const l0Bytes = readFlag(tokens, '--l0-bytes');
+                    /* 观测策略参数：l0-roll 决定"我有多久回看窗口"（默认 16 帧 ≈ 1.6s @10fps），
+                     * max-frames 决定环形缓冲长度。协议本就支持，命令面必须可达——
+                     * 不可达的参数会被调用方当成"没有"。 */
+                    const maxFrames = readFlag(tokens, '--max-frames');
+                    const l0Roll = readFlag(tokens, '--l0-roll');
+                    const l0Anchor = readFlag(tokens, '--l0-anchor');
+                    out(short(await act.streamStart(client, {
+                        ...(fps ? { fps: Number(fps) } : {}),
+                        ...(scale ? { scale: Number(scale) } : {}),
+                        ...(blockThresh ? { blockThresh: Number(blockThresh) } : {}),
+                        ...(changeGlobal ? { changeGlobal: Number(changeGlobal) } : {}),
+                        ...(l0Bytes ? { l0Bytes: Number(l0Bytes) } : {}),
+                        ...(maxFrames ? { maxFrames: Number(maxFrames) } : {}),
+                        ...(l0Roll ? { l0Roll: Number(l0Roll) } : {}),
+                        ...(l0Anchor ? { l0Anchor: Number(l0Anchor) } : {}),
+                    })));
+                }
+                else if (sub === 'stop')
+                    out(short(await act.streamStop(client)));
+                else
+                    out(short(await act.streamStatus(client)));
+                break;
+            }
+            case 'wait': {
+                /* 状态谓词：等到条件成立再往下读，取代硬睡时钟。超时不算错误（satisfied=false）。 */
+                const modeRaw = tokens[1];
+                if (modeRaw !== 'stable' && modeRaw !== 'change') {
+                    out('用法：wait stable|change [--timeout ms] [--quiet ms] [--roi x,y,w,h] [--threshold n]'
+                        + '（模式只认 stable / change'
+                        + (modeRaw ? '；收到 ' + JSON.stringify(modeRaw)
+                            + (suggestHead(modeRaw) ? '，是想输入 ' + String(suggestHead(modeRaw)) + ' 吗' : '') : '')
+                        + '）');
+                    break;
+                }
+                /* 数值 flag 必须校验：`--timeout abc` 会变成 NaN 一路传下去，
+                 * 客户端超时算成 NaN → 调用秒超时，看起来像"工具坏了"。 */
+                const numOr = (name) => {
+                    const raw = readFlag(tokens, name);
+                    if (raw === undefined)
+                        return undefined;
+                    const n = Number(raw);
+                    return Number.isFinite(n) ? n : null;
+                };
+                const tmo = numOr('--timeout');
+                const qt = numOr('--quiet');
+                const thr = numOr('--threshold');
+                if (tmo === null || qt === null || thr === null) {
+                    out('--timeout / --quiet / --threshold 必须是数字'
+                        + (tmo === null ? '（--timeout 收到 ' + JSON.stringify(readFlag(tokens, '--timeout')) + '）' : ''));
+                    break;
+                }
+                const roiRaw = readFlag(tokens, '--roi');
+                const r = await act.waitState(client, {
+                    mode: modeRaw,
+                    ...(tmo !== undefined ? { timeout: tmo } : {}),
+                    ...(qt !== undefined ? { quiet: qt } : {}),
+                    ...(thr !== undefined ? { threshold: thr } : {}),
+                    ...(roiRaw ? { roi: roiRaw.split(',').map((x) => Number(x)) } : {}),
+                });
+                out(short(r, 500));
+                break;
+            }
+            case 'frame': {
+                const roiRaw = readFlag(tokens, '--roi');
+                const srcRaw = readFlag(tokens, '--src');
+                const seq = tokens[1] && !tokens[1].startsWith('--') ? Number(tokens[1]) : undefined;
+                if (tokens[1] === 'diff') {
+                    /* 两帧在若干 ROI 上的差分：离散网格要的是"哪几格变了"，不是整帧 bbox。 */
+                    const a = readFlag(tokens, '--a');
+                    const b = readFlag(tokens, '--b');
+                    const roisRaw = readFlag(tokens, '--rois');
+                    if (a === undefined || b === undefined || !roisRaw) {
+                        out('用法：frame diff --a <seq> --b <seq> --rois "x,y,w,h;x,y,w,h"');
+                        break;
+                    }
+                    const rois = roisRaw.split(';').map((s) => s.split(',').map((x) => Number(x)));
+                    if (rois.some((r) => r.length !== 4 || r.some((n) => !Number.isFinite(n)))) {
+                        out('--rois 每段要 4 个数字，段间用 ; 分隔');
+                        break;
+                    }
+                    const d = await act.frameDiff(client, { a: Number(a), b: Number(b), rois });
+                    out(short(d, 900));
+                    break;
+                }
+                out(short(await act.frameGet(client, {
+                    ...(seq !== undefined ? { seq } : {}),
+                    ...(roiRaw ? { roi: roiRaw.split(',').map((x) => Number(x)) } : {}),
+                    ...(readFlag(tokens, '--out') ? { out: readFlag(tokens, '--out') } : {}),
+                    ...(srcRaw ? { src: srcRaw } : {}),
+                })));
+                break;
+            }
+            case 'color': {
+                const roiRaw = readFlag(tokens, '--roi');
+                out(short(await act.colorProbe(client, {
+                    ...(roiRaw ? { roi: roiRaw.split(',').map((x) => Number(x)) } : {}),
+                }), 400));
+                break;
+            }
+            case 'crop': {
+                const roiRaw = readFlag(tokens, '--roi');
+                const pointRaw = readFlag(tokens, '--point');
+                const padRaw = readFlag(tokens, '--pad');
+                /* --from-kf：源换成库内留存帧（跨会话可用）。解析走与一次性 CLI 同一份离线读侧。 */
+                const kfId = readFlag(tokens, '--from-kf');
+                let kfSource;
+                if (kfId) {
+                    const k = kfSourceFrom(kfId, tokens);
+                    if (k.error) {
+                        out(k.error);
+                        break;
+                    }
+                    kfSource = k.source;
+                }
+                const ck = await act.tplCrop(client, {
+                    ...(roiRaw ? { roi: roiRaw.split(',').map((x) => Number(x)) } : {}),
+                    ...(pointRaw ? { point: pointRaw.split(',').map((x) => Number(x)) } : {}),
+                    ...(padRaw ? { pad: Number(padRaw) } : {}),
+                    ...(readFlag(tokens, '--out') ? { out: readFlag(tokens, '--out') } : {}),
+                    ...(kfSource ? { kfSource, cross: false } : {}),
+                    ...(readFlag(tokens, '--resource-dir')
+                        ? { resourceDir: readFlag(tokens, '--resource-dir') }
+                        : (state.plan?.resource?.paths.length ? { resourceDir: state.plan.resource.paths[0] } : {})),
+                });
+                out(short(ck, 600));
+                if (ck.ok !== false && ck.provPath)
+                    out('L2 出处：' + String(ck.provPath));
+                break;
+            }
+            case 'annotate': {
+                /* --from-kf：源换成库内留存帧（离线；diff 源不可用，工具会如实报） */
+                const kfSom = readFlag(tokens, '--from-kf');
+                let somKf;
+                if (kfSom) {
+                    const k = kfSourceFrom(kfSom, tokens);
+                    if (k.error) {
+                        out(k.error);
+                        break;
+                    }
+                    somKf = k.source;
+                }
+                const somLimitRaw = readFlag(tokens, '--som-limit');
+                const somLimit = somLimitRaw === undefined ? undefined : Number(somLimitRaw);
+                if (somLimitRaw !== undefined && (!Number.isFinite(somLimit) || somLimit <= 0)) {
+                    out('--som-limit 必须是正整数（收到 ' + JSON.stringify(somLimitRaw) + '）；0 不等于"不限量"');
+                    break;
+                }
+                const somRatioRaw = readFlag(tokens, '--som-max-area-ratio');
+                const somRatio = somRatioRaw === undefined ? undefined : Number(somRatioRaw);
+                if (somRatioRaw !== undefined && (!Number.isFinite(somRatio) || somRatio <= 0 || somRatio >= 1)) {
+                    out('--som-max-area-ratio 要在 (0,1) 之间（收到 ' + JSON.stringify(somRatioRaw) + '）；0 不等于"关闭剔除"');
+                    break;
+                }
+                const r = await act.annotate(client, {
+                    ...(readFlag(tokens, '--out') ? { out: readFlag(tokens, '--out') } : {}),
+                    ...(somKf ? { kfSource: somKf } : {}),
+                    ...(somLimit !== undefined ? { somLimit } : {}),
+                    ...(somRatio !== undefined ? { somMaxAreaRatio: somRatio } : {}),
+                    ...(readFlag(tokens, '--roi') ? { roi: String(readFlag(tokens, '--roi')).split(',').map((x) => Number(x)) } : {}),
+                    ...(readFlag(tokens, '--resource-dir')
+                        ? { resourceDir: readFlag(tokens, '--resource-dir') }
+                        : (state.plan?.resource?.paths.length ? { resourceDir: state.plan.resource.paths[0] } : {})),
+                });
+                if (r.ok === false) {
+                    out('annotate 失败：' + String(r.error));
+                    break;
+                }
+                out('SoM ' + String(r.count) + ' 候选 → ' + String(r.out) + (somKf ? '（源：留存帧）' : ''));
+                /* 可用性三列：不读它就会把"30 条"当成"画面就这些可点区域"。 */
+                const av = r.availability;
+                if (av) {
+                    out('  可用性：合并池 ' + String(av.mergedTotal ?? '?') + ' → 进表 ' + String(r.count)
+                        + '（上限 ' + String(av.limit ?? '?') + '，截断 ' + String(av.truncated ?? 0) + '）'
+                        + '；剔除 巨框 ' + String(av.dropped?.tooBig ?? 0) + ' / 重复 ' + String(av.dropped?.duplicated ?? 0));
+                    if (av.byBand)
+                        out('  分带（上/中/下）进表/池：' + av.byBand.map((b) => String(b.inTable) + '/' + String(b.inPool)).join('  '));
+                    if (av.outResolution)
+                        out('  回画分辨率：' + String(av.outResolution.w) + 'x' + String(av.outResolution.h) + '（' + String(av.outResolution.source) + '）');
+                }
+                for (const c of r.candidates ?? []) {
+                    out('  #' + c.id + ' [' + c.source + '] ctrl=' + c.ctrl.join(',')
+                        + (typeof c.areaRatio === 'number' ? ' 面积比=' + c.areaRatio : '')
+                        + (typeof c.score === 'number' ? ' score=' + c.score : '')
+                        + (c.text ? '  "' + c.text + '"' : ''));
+                }
+                break;
+            }
+            case 'events': {
+                const n = Number(tokens[1] ?? 10);
+                const evs = client.events.events.slice(-n);
+                out('事件 ' + evs.length + ' 条（共 ' + client.events.events.length + '）');
+                /* 每条事件显式带出画面锚点：seq 单独给没有用（L0 是滚动淘汰的，得知道还能不能取到）。
+                 * 保留 `short(e, 200)` 的其余字段，但锚点不能被截断掉——它是这条事件唯一可行动的部分。 */
+                for (const e of evs) {
+                    const ev = e;
+                    const f = ev.frame;
+                    const anchor = !f
+                        ? '  frame=?（旧 daemon 回执，无锚点）'
+                        : f.retained === 'l0'
+                            ? '  frame=l0:' + String(f.seq) + (f.source ? '（' + f.source + '）' : '') + ' → frame get ' + String(f.seq)
+                            : '  frame=gone（seq ' + String(f.seq) + ' 已滚出 L0，取不到了）';
+                    out('  ' + short(e, 200) + anchor);
+                }
+                break;
+            }
+            case 'logs': {
+                const n = Number(tokens[1] ?? 20);
+                for (const l of client.logTail(n))
+                    out('  ' + l);
+                break;
+            }
+            case 'run': {
+                const entry = tokens[1];
+                if (!entry) {
+                    out('用法：run <entry> [--timeout ms|0] [--preset name] [--override json] [--resource-dir d] [--option k=v 可多次] [--watch]');
+                    break;
+                }
+                const wantWatch = tokens.includes('--watch');
+                const rawTimeout = readFlag(tokens, '--timeout');
+                const timeout = rawTimeout === undefined ? 30000 : Number(rawTimeout);
+                if (!Number.isFinite(timeout)) {
+                    out('--timeout 必须是毫秒数（收到 ' + JSON.stringify(rawTimeout) + '）');
+                    break;
+                }
+                const overrideRaw = readFlag(tokens, '--override');
+                let override = {};
+                if (overrideRaw) {
+                    try {
+                        override = JSON.parse(overrideRaw);
+                    }
+                    catch {
+                        out('--override 不是合法 JSON');
+                        break;
+                    }
+                }
+                /* --option 按次取值（可多次）：<键>=<case>、<键>.<字段>=<值>。
+                 * 与一次性 CLI 同一解析器（parseOptionArgs），判错口径一致。 */
+                const optList = readFlagAll(tokens, '--option');
+                let optCases;
+                let optFields;
+                if (optList.length) {
+                    const parsed = parseOptionArgs(optList);
+                    if (parsed.error) {
+                        out(parsed.error);
+                        break;
+                    }
+                    optCases = parsed.cases;
+                    optFields = parsed.fields;
+                }
+                /* 资源与 override：--resource-dir 显式单包（bundle 模式）；否则走 connect project
+                 * 的项目规划，与一次性 CLI 共用 prepareProjectRun（入口解析 / task 适用性 /
+                 * 四级 pipeline_override / agent 桥接都在那一个函数里）。 */
+                const explicitDir = readFlag(tokens, '--resource-dir');
+                const presetRaw = readFlag(tokens, '--preset');
+                const plan = state.plan;
+                /* --resource-dir 只换资源来源，**不换入口解析**：connect project 之后即使覆盖了
+                 * 资源目录，interface 的中文任务名仍要解析成 task.entry（旧行为，别在短路分支里丢）。 */
+                const task = plan?.loaded.tasks.find((t) => t.name === entry || t.entry === entry);
+                let args;
+                let resolvedEntry = task?.entry ?? entry;
+                let taskName = task?.name ?? null;
+                if (explicitDir) {
+                    /* bundle 模式不叠 interface 四级链：--preset 没有地方生效，必须说出来，
+                     * 否则调用方会以为 P1 已经选中（静默丢参数比报错更难查）。 */
+                    if (presetRaw !== undefined) {
+                        out('警告：--resource-dir 是 bundle 模式，不叠 interface 四级 override——--preset ' + presetRaw + ' 不生效');
+                    }
+                    args = { resourceDir: explicitDir, entry: resolvedEntry, override, timeoutMs: timeout };
+                }
+                else if (plan) {
+                    const prep = act.prepareProjectRun({
+                        project: plan,
+                        entry,
+                        presetName: presetRaw ?? null,
+                        override,
+                        ...(optCases ? { optionCases: optCases } : {}),
+                        ...(optFields ? { optionFields: optFields } : {}),
+                    });
+                    if (!prep.ok) {
+                        out('run 拒绝：' + prep.error + (prep.hint ? '\n  hint: ' + prep.hint : ''));
+                        for (const w of prep.warns)
+                            out('  警告：' + w);
+                        break;
+                    }
+                    args = prep.args;
+                    resolvedEntry = prep.entry;
+                    taskName = prep.taskName;
+                    /* 生效记录与警示：与一次性 CLI 同一份。REPL 过去只有裸 --override，
+                     * 项目里的 GUI 选项在会话里静默不生效——调用方看不到任何差异。 */
+                    for (const l of prep.applied)
+                        out('  override: ' + l);
+                    for (const w of prep.warns)
+                        out('  警告：' + w);
+                }
+                else {
+                    out('缺资源：给 --resource-dir <dir>，或先 connect project <dir>');
+                    break;
+                }
+                /* 异步执行不阻塞提示符：--timeout 0 的长任务靠 stop 中断（同一条客户端连接） */
+                out('已提交 ' + resolvedEntry + (taskName && taskName !== resolvedEntry ? '（任务 ' + taskName + '）' : '') + '（timeout=' + timeout + '，结果异步打印；stop 可中断）');
+                /* --watch：把这次 run 的节点转移事件持续打出来（一次性 CLI 的 --watch 在
+                 * REPL 里的等价物——没有它就只能手写轮询 events N，8 分钟轮询真机撞出来的账）。
+                 * 事件源是 daemon 推进来的 client.events.events 数组，只能轮询尾巴；
+                 * 数组有 2000 上限会从头滚，发现指针越过当前长度就重置。run 结束即停。 */
+                let watchTimer = null;
+                if (wantWatch) {
+                    let cursor = client.events.events.length;
+                    watchTimer = setInterval(() => {
+                        const evs = client.events.events;
+                        if (cursor > evs.length)
+                            cursor = 0; /* 滚出上限重置 */
+                        for (; cursor < evs.length; cursor++) {
+                            const e = evs[cursor];
+                            if (e && e.msg) {
+                                out('  [watch] ' + String(e.node ?? '-') + '  ' + String(e.msg) +
+                                    (e.id != null ? '  #' + String(e.id) : '') + '  seq=' + String(e.seq ?? '?'));
                             }
-                            out(short(await act.input(client, { kind: 'scroll', dx: a[0], dy: a[1] })));
-                            break;
                         }
-                        case 'move': {
-                            const a = nums(tokens, 1, 2);
-                            if (!a) {
-                                out('用法：move <dx> <dy>');
-                                break;
-                            }
-                            out(short(await act.input(client, { kind: 'move', dx: a[0], dy: a[1] })));
+                    }, 500);
+                    watchTimer.unref();
+                }
+                act.run(client, args, timeout)
+                    .then((r) => {
+                    if (watchTimer) {
+                        clearInterval(watchTimer);
+                        watchTimer = null;
+                    }
+                    /* 回执不再 short() 截断（0.3.x 实测：截断让 record.nodes[] 在会话里永远不可见，
+                     * "跑失败"变成"看不懂为什么失败"）。三件套替代：结论行（保住「run 完成：任务级 X」
+                     * 首词口径）→ 非 ok 节点点名 → 全量回执落盘给路径。落盘失败不吞结论，退化为完整 JSON。 */
+                    const rec = r.record;
+                    /* 与一次性 CLI 同一份三态判据：`status:0 + stopped:true` 不是"完成"。
+                     * 判据用 record 自带的 timeoutMs，不靠调用方回忆刚才给了什么。 */
+                    const budget = rec && typeof rec.timeoutMs === 'number' ? rec.timeoutMs : null;
+                    const ranFull = rec?.stopped === true && budget !== null && budget > 0
+                        && typeof rec.durationMs === 'number' && rec.durationMs >= budget;
+                    const verdict = !rec ? '未知'
+                        : rec.ok ? 'ok'
+                            : ranFull ? '超时截断（非成功，也非失败）'
+                                : rec.stopped === true ? '被停止（未成功）'
+                                    : 'FAIL';
+                    const nodes = rec?.nodes ?? [];
+                    const okCount = nodes.filter((n) => n.status === 'ok').length;
+                    const notOk = nodes.filter((n) => n.status !== 'ok');
+                    out('run 完成：任务级 ' + verdict +
+                        (rec?.agent ? '，agent ' + (rec.agent.ok ? '已连接' : '失败') : '') +
+                        '  节点 ' + nodes.length + ' 例（ok ' + okCount +
+                        (notOk.length ? ' / 其他 ' + notOk.length : '') + '）');
+                    for (const n of notOk) {
+                        out('  [' + String(n.status) + '] ' + String(n.name) + '  ' + String(n.ms) + 'ms  #' + String(n.seq ?? '?'));
+                    }
+                    /* 落盘走共享助手（目录可用 MAAFW_LIVE_RUNS_DIR 覆盖，单测不写真实 home）；
+                     * 失败不吞结论，退化为完整 JSON。 */
+                    const receipt = writeRunReceipt(r, resolvedEntry);
+                    out(receipt.path !== undefined
+                        ? '完整回执（含全部节点与 msgs）：' + receipt.path
+                        : '回执落盘失败，完整内容：' + JSON.stringify(r));
+                })
+                    .catch((e) => { if (watchTimer) {
+                    clearInterval(watchTimer);
+                    watchTimer = null;
+                } out('run 失败：' + (e instanceof Error ? e.message : String(e))); });
+                break;
+            }
+            case 'stop':
+                out(short(await act.runStop(client)));
+                break;
+            case 'click': {
+                const a = nums(tokens, 1, 2);
+                if (!a) {
+                    out('用法：click <x> <y>');
+                    break;
+                }
+                out(short(await act.input(client, { kind: 'click', x: a[0], y: a[1] })));
+                break;
+            }
+            case 'swipe': {
+                const a = nums(tokens, 1, 4);
+                const duration = numFlag(tokens, '--duration', 300);
+                if (!a || duration === null) {
+                    out('用法：swipe <x1> <y1> <x2> <y2> [--duration ms] [--via "x,y;x,y"]');
+                    break;
+                }
+                /* --via：中途路径点。走的是 touch_down→逐点 touch_move→touch_up —— **一条笔画画折线**，
+                 * 中途不抬手。连线/谱曲/拖拽排序这类玩法要的正是这个；只有两端点时走原生 post_swipe。 */
+                const viaRaw = readFlag(tokens, '--via');
+                let via;
+                if (viaRaw) {
+                    via = viaRaw.split(';').map((s) => s.split(',').map((x) => Number(x)));
+                    if (via.some((p) => p.length !== 2 || p.some((n) => !Number.isFinite(n)))) {
+                        out('--via 每段要 2 个数字（x,y），段间用 ; 分隔');
+                        break;
+                    }
+                }
+                out(short(await act.input(client, {
+                    kind: 'swipe', x1: a[0], y1: a[1], x2: a[2], y2: a[3], duration,
+                    ...(via ? { via } : {}),
+                })));
+                break;
+            }
+            case 'touchdown': {
+                const a = nums(tokens, 1, 2);
+                if (!a) {
+                    out('用法：touchdown <x> <y>');
+                    break;
+                }
+                out(short(await act.input(client, { kind: 'touch_down', x: a[0], y: a[1] })));
+                break;
+            }
+            case 'touchmove': {
+                const a = nums(tokens, 1, 2);
+                if (!a) {
+                    out('用法：touchmove <x> <y>');
+                    break;
+                }
+                out(short(await act.input(client, { kind: 'touch_move', x: a[0], y: a[1] })));
+                break;
+            }
+            case 'touchup':
+                out(short(await act.input(client, { kind: 'touch_up' })));
+                break;
+            case 'key': {
+                const a = nums(tokens, 1, 1);
+                if (!a) {
+                    out('用法：key <code>（Android KeyEvent 码：3=Home、4=返回）');
+                    break;
+                }
+                out(short(await act.input(client, { kind: 'key', code: a[0] })));
+                break;
+            }
+            case 'keys': {
+                /* 键码只保留正整数：与 CLI/daemon 同一条口径，空集合直接报用法 */
+                const codes = String(tokens[1] ?? '').split(/[+,]/)
+                    .map((s) => Number(s.trim())).filter((n) => Number.isFinite(n) && n > 0);
+                if (!codes.length) {
+                    out('用法：keys <code[,code+...]>（至少一个正整数键码，如 17,67）');
+                    break;
+                }
+                out(short(await act.input(client, { kind: 'keys', codes })));
+                break;
+            }
+            case 'press': {
+                const a = nums(tokens, 1, 2);
+                const duration = numFlag(tokens, '--duration', 800);
+                if (!a || duration === null) {
+                    out('用法：press <x> <y> [--duration ms]');
+                    break;
+                }
+                out(short(await act.input(client, { kind: 'press', x: a[0], y: a[1], duration })));
+                break;
+            }
+            case 'dbclick': {
+                const a = nums(tokens, 1, 2);
+                if (!a) {
+                    out('用法：dbclick <x> <y>');
+                    break;
+                }
+                out(short(await act.input(client, { kind: 'dbclick', x: a[0], y: a[1] })));
+                break;
+            }
+            case 'scroll': {
+                const a = nums(tokens, 1, 2);
+                if (!a) {
+                    out('用法：scroll <dx> <dy>（建议 120 的倍数）');
+                    break;
+                }
+                out(short(await act.input(client, { kind: 'scroll', dx: a[0], dy: a[1] })));
+                break;
+            }
+            case 'move': {
+                const a = nums(tokens, 1, 2);
+                if (!a) {
+                    out('用法：move <dx> <dy>');
+                    break;
+                }
+                out(short(await act.input(client, { kind: 'move', dx: a[0], dy: a[1] })));
+                break;
+            }
+            case 'text':
+                out(short(await act.input(client, { kind: 'text', text: line.trim().slice(5) })));
+                break;
+            case 'reco': {
+                /* 类型是位置参数：下一个 token 以 `--` 开头的是选项、含 `=` 的是 k=v 参数，都不是类型。
+                 * 不做这一步，`reco --param-file p.json` 会把 type 设成字符串 "--param-file"（frame 早就
+                 * 按同一惯例跳过 `--` 开头）。 */
+                const first = tokens[1];
+                const type = first !== undefined && !first.startsWith('--') && !first.includes('=')
+                    ? first
+                    : 'TemplateMatch';
+                const param = recoParam(tokens);
+                const sweepRaw = readFlag(tokens, '--sweep');
+                /* 节点/参数来源：与一次性 CLI 同一组互斥、同一份 JSONC 读取（判据只有一份）。
+                 * REPL 的 stdin 是**命令流**，所以 `-`（stdin）在这里没有意义：直接拒绝，不去读会话输入。 */
+                const nodeFileSpec = readFlag(tokens, '--node-file');
+                const nodeName = readFlag(tokens, '--node-name');
+                const paramFileSpec = readFlag(tokens, '--param-file');
+                if (nodeFileSpec === '-' || paramFileSpec === '-') {
+                    out('REPL 里 --node-file / --param-file 不接受 -：- 的意思是 stdin，而 REPL 的 stdin 是命令流。'
+                        + '给文件路径，或改用一次性命令由 shell 管 stdin');
+                    break;
+                }
+                if (nodeFileSpec !== undefined && nodeName !== undefined) {
+                    out('--node-file 与 --node-name 互斥：一个测文件里的节点，一个按资源原名跑');
+                    break;
+                }
+                let node;
+                if (nodeFileSpec !== undefined) {
+                    const f = readNodeFile(nodeFileSpec);
+                    if (f.error) {
+                        out(f.error + (f.hint ? '\n  hint: ' + f.hint : ''));
+                        break;
+                    }
+                    node = f.node;
+                }
+                let paramFromFile;
+                if (paramFileSpec !== undefined) {
+                    if (Object.keys(param).length > 0) {
+                        out('k=v 参数与 --param-file 互斥：一个给字面值，一个给文件');
+                        break;
+                    }
+                    const f = readParamFile(paramFileSpec);
+                    if (f.error) {
+                        out(f.error);
+                        break;
+                    }
+                    paramFromFile = f.param;
+                }
+                const effectiveParam = paramFromFile ?? param;
+                if ((node || nodeName !== undefined) && (Object.keys(effectiveParam).length > 0 || sweepRaw !== undefined)) {
+                    out('k=v 参数 / --param-file / --sweep 只作用于 <type> 路径：与 --node-file / --node-name 同给时不会生效');
+                    break;
+                }
+                /* 资源链：--resource-dir 是显式单包；否则取 connect project 规划出的**整条链**
+                 * （resource.path[] + 控制器 attach 段——只取 [0] 会让 overlay/attach 里的节点改写、
+                 * 只存在于 overlay 的模板、被 And/Or 按名引用的子节点全部消失）。缺了资源 daemon 只会
+                 * 给出零例数（模板/OCR 模型都读不到）——这是 G16 证据里 `[]` 与 `ok:false` 两种签名
+                 * 并存的第三个混淆变量，所以**前置拦下并说清**，不再让它静默。 */
+                const explicitDir = readFlag(tokens, '--resource-dir');
+                const chain = explicitDir !== undefined ? [explicitDir] : (state.plan?.resource?.paths ?? []);
+                if (chain.length === 0) {
+                    out('缺资源目录：reco 的模板/OCR 模型要靠它加载，不给只会得到零例数（看不出病因）。'
+                        + '先给 --resource-dir <dir>，或 connect project <dir>');
+                    break;
+                }
+                const resources = chain.length > 1 ? { resourceDirs: chain } : { resourceDir: chain[0] };
+                /* --image / --seq / --from-kf：图像来源三条与一次性 CLI 一致，由 daemon 按
+                 * 「kfSource → image → 缓冲帧」的次序取（`--image` 优先于 `--seq`，不另行报错——
+                 * 那会再造一套 repl/CLI 规则差）。 */
+                const imageRaw = readFlag(tokens, '--image');
+                const seqRaw = readFlag(tokens, '--seq');
+                const kfId = readFlag(tokens, '--from-kf') ?? (imageRaw?.startsWith('kf:') ? imageRaw : undefined);
+                let kfSource;
+                if (kfId) {
+                    const k = kfSourceFrom(kfId, tokens);
+                    if (k.error) {
+                        out(k.error);
+                        break;
+                    }
+                    kfSource = k.source;
+                }
+                const seqNum = seqRaw === undefined ? undefined : Number(seqRaw);
+                if (seqRaw !== undefined && !Number.isFinite(seqNum)) {
+                    out('--seq 必须是数字（收到 ' + JSON.stringify(seqRaw) + '）');
+                    break;
+                }
+                const nodeSource = node !== undefined || nodeName !== undefined;
+                const r = await act.recoTest(client, {
+                    ...resources, type,
+                    ...(node ? { node } : {}),
+                    ...(nodeName !== undefined ? { nodeName } : {}),
+                    ...(imageRaw && !kfId ? { image: imageRaw } : {}),
+                    ...(seqNum !== undefined ? { seq: seqNum } : {}),
+                    ...(kfSource ? { kfSource } : {}),
+                    ...(nodeSource ? {} : { param: effectiveParam }),
+                    ...(nodeSource ? {} : (sweepRaw ? { sweep: JSON.parse(sweepRaw) } : {})),
+                });
+                /* 能力边界与"查无此节点"是明确结论，不该落进"看起来像 miss" */
+                if (r.ok === false && (r.code === 'CUSTOM_NODE' || r.code === 'NODE_MISSING')) {
+                    const cands = Array.isArray(r.candidates) ? r.candidates.map(String) : [];
+                    out(String(r.error) + (r.code === 'CUSTOM_NODE'
+                        ? '\n  hint: custom/agent 识别要桥接 agent 子进程，用 run --project 验；reco 只测资源合并后的普通节点'
+                        : (cands.length
+                            ? '\n  hint: 资源里最接近的节点名：' + cands.join(' / ')
+                            : '\n  hint: 确认资源名与链（connect project 的 --resource）是否正确；手写节点用 --node-file')));
+                    break;
+                }
+                /* roi 越界：repl 没有单命令退出码（末行统一 EXIT.OK），照本文件既有惯例
+                 * 「打印显式错误 + break」；一次性 CLI 侧同一判据走 EXIT.FINDINGS。 */
+                const meta = r.meta;
+                const oob = roiOutOfBounds(nodeSource ? undefined : (typeof effectiveParam.roi === 'object' ? effectiveParam.roi : undefined), meta?.w, meta?.h);
+                if (oob) {
+                    out(oob);
+                    break;
+                }
+                /* 离线评估（静态图/库帧）标记：防"拿旧截图出分冒充实测"（G21 同族事故）。
+                 * 分数可用于调参/回归，不构成真机验收证据。 */
+                if ((imageRaw && !kfId) || kfSource) {
+                    out('⚠ 离线评估（' + (kfSource ? '库帧 --from-kf' : '静态图 --image') +
+                        '）：分数可用于调参/回归，不构成真机验收证据——验收只认真机 run 的 record.ok');
+                }
+                if (nodeName !== undefined) {
+                    out('layer=resource：只到资源合并结果（run --project 还会再叠 interface 的四级 pipeline_override）');
+                }
+                /* miss 原因与计数：与一次性 CLI 同一份判据（runtime/reco-verdict）。daemon 只回原始
+                 * detail，`missReason` 是本地派生的——不派生就等于没有任何输出，只能回去翻 all/filtered。 */
+                const results = r.results ?? [];
+                const th = suggestThreshold(results);
+                const shownType = String(r.type ?? type);
+                /* OCR 空结果先查模型在不在链上：模型没加载时框架只回空结果，与"roi 里没有字"同形 */
+                const ocrModel = shownType === 'OCR'
+                    ? ocrModelStatus(chain, ocrModelName(node, effectiveParam, r.nodeDump))
+                    : undefined;
+                const verdict = describeMisses(results, shownType, th ? { bestScore: th.bestScore, lowMatch: th.lowMatch } : null, ocrModel ? { ocrModel } : {});
+                /* 调用报错与未命中分开读：前者是"没跑成"，别混进"未命中原因"那一行；
+                 * 两者可以同时出现（扫描里一例报错、另一例真未命中），不能因为报了错就吞掉后者。 */
+                const failed = verdict.perResult.filter((d) => d.failed);
+                if (failed.length > 0) {
+                    const msgs = [...new Set(failed.map((d) => String(d.missReason ?? '')))];
+                    out('识别调用报错 ' + failed.length + ' 例（[报错]，不是未命中）：' +
+                        msgs.slice(0, 2).join(' / ') + (msgs.length > 2 ? ' …' : ''));
+                }
+                const missReasons = [...new Set(verdict.perResult
+                        .filter((d) => !d.failed && d.missReason)
+                        .map((d) => String(d.missReason)))];
+                if (missReasons.length > 0)
+                    out('未命中原因：' + missReasons.join(' / '));
+                if (verdict.rawCount !== null) {
+                    out('  候选 all=' + verdict.rawCount +
+                        (verdict.filteredCount !== null ? ' filtered=' + verdict.filteredCount : ''));
+                }
+                out(short(r, 800));
+                break;
+            }
+            case 'kf': {
+                const sub = tokens[1] ?? 'status';
+                if (sub === 'status') {
+                    out(short(await act.l0Status(client), 600));
+                }
+                else if (sub === 'promote') {
+                    const note = readFlag(tokens, '--note');
+                    /* 批量：kf promote 1 2 3 | kf promote 10..15 | kf promote 1,2,3。逐个升格，
+                     * 淘汰的 seq 附 frame_get 降级命令（daemon 已把 hint 编进 error 文案）。 */
+                    const seqToks = tokens.slice(2).filter((t) => t !== '--note' && t !== String(note)).flatMap((t) => t.split(',')).filter((t) => t !== '');
+                    const range = seqToks.length === 1 && /^(\d+)\.\.(\d+)$/.exec(seqToks[0]);
+                    let pArgs;
+                    if (range) {
+                        const a = Number(range[1]), b = Number(range[2]);
+                        if (a > b || b - a > 200) {
+                            out('范围非法（a..b 且跨度 ≤200）');
                             break;
                         }
-                        case 'text':
-                            out(short(await act.input(client, { kind: 'text', text: line.trim().slice(5) })));
-                            break;
-                        case 'reco': {
-                            const type = tokens[1] ?? 'TemplateMatch';
-                            const param = {};
-                            for (const t of tokens.slice(2)) {
-                                const eq = t.indexOf('=');
-                                if (eq > 0) {
-                                    const k = t.slice(0, eq);
-                                    const v = t.slice(eq + 1);
-                                    param[k] = Number.isFinite(Number(v)) && v !== '' ? Number(v) : v;
-                                }
-                            }
-                            const sweepRaw = readFlag(tokens, '--sweep');
-                            const resourceDir = readFlag(tokens, '--resource-dir') ?? '';
-                            out(short(await act.recoTest(client, {
-                                resourceDir, type, param,
-                                ...(sweepRaw ? { sweep: JSON.parse(sweepRaw) } : {}),
-                            }), 800));
+                        pArgs = { seqs: Array.from({ length: b - a + 1 }, (_, i) => a + i), ...(note ? { note } : {}) };
+                    }
+                    else if (seqToks.length > 1) {
+                        const nums = seqToks.map((t) => Number(t));
+                        if (nums.some((n) => !Number.isInteger(n) || n <= 0)) {
+                            out('seq 必须是正整数');
                             break;
                         }
-                        case 'kf': {
-                            const sub = tokens[1] ?? 'status';
-                            if (sub === 'status') {
-                                out(short(await act.l0Status(client), 600));
-                            }
-                            else if (sub === 'promote') {
-                                const what = tokens[2];
-                                const note = readFlag(tokens, '--note');
-                                const r = await act.kfPromote(client, /^\d+$/.test(String(what))
-                                    ? { seq: Number(what), ...(note ? { note } : {}) }
-                                    : { latest: true, ...(note ? { note } : {}) });
-                                if (r.ok === false)
-                                    out('升格失败：' + String(r.error));
-                                else
-                                    out('已升格 ' + String(r.id) + ' → ' + String(r.path) + (r.idempotent ? '（幂等重试）' : ''));
-                            }
-                            else if (sub === 'list') {
-                                const { manifest, error } = loadManifest(defaultFramesDir());
-                                if (error) {
-                                    out('库不可读：' + error);
-                                    break;
-                                }
-                                if (!manifest) {
-                                    out('关键帧库尚无留存');
-                                    break;
-                                }
-                                out('关键帧库 ' + manifest.frames.length + ' 条（libraryId ' + manifest.libraryId + '）');
-                                for (const f of manifest.frames)
-                                    out('  ' + describeRecord(f));
-                            }
-                            else if (sub === 'resolve') {
-                                const r = resolveFrame(defaultFramesDir(), String(tokens[2] ?? ''));
-                                out(r.status + (r.reason ? '（' + r.reason + '）' : '') + (r.path ? '  ' + r.path : ''));
-                            }
-                            else {
-                                out('用法：kf status | kf promote [seq|latest] [--note s] | kf list | kf resolve <kf:...>');
-                            }
-                            break;
+                        pArgs = { seqs: nums, ...(note ? { note } : {}) };
+                    }
+                    else if (seqToks.length === 1 && /^\d+$/.test(seqToks[0])) {
+                        pArgs = { seq: Number(seqToks[0]), ...(note ? { note } : {}) };
+                    }
+                    else {
+                        pArgs = { latest: true, ...(note ? { note } : {}) };
+                    }
+                    const r = await act.kfPromote(client, pArgs);
+                    if (Array.isArray(r.results)) {
+                        for (const it of r.results) {
+                            if (it.ok)
+                                out('  seq=' + it.seq + ' → ' + it.id);
+                            else
+                                out('  seq=' + it.seq + ' ✗ ' + it.error);
                         }
-                        default:
-                            out('未知命令：' + head
-                                + (suggestHead(head) ? '（是想输入 ' + String(suggestHead(head)) + ' 吗？）' : '')
-                                + '（输入 help 看命令表）');
+                        out('批量：' + String(r.promoted) + ' 成功 / ' + String(r.failed) + ' 失败');
                     }
-                }
-                catch (e) {
-                    if (e instanceof SessionError)
-                        out('会话错误 [' + e.code + ']：' + e.message);
+                    else if (r.ok === false)
+                        out('升格失败：' + String(r.error));
                     else
-                        out('错误：' + (e instanceof Error ? e.message : String(e)));
+                        out('已升格 ' + String(r.id) + ' → ' + String(r.path) + (r.idempotent ? '（幂等重试）' : ''));
+                }
+                else if (sub === 'list') {
+                    const { manifest, error } = loadManifest(defaultFramesDir());
+                    if (error) {
+                        out('库不可读：' + error);
+                        break;
+                    }
+                    if (!manifest) {
+                        out('关键帧库尚无留存');
+                        break;
+                    }
+                    out('关键帧库 ' + manifest.frames.length + ' 条（libraryId ' + manifest.libraryId + '）');
+                    for (const f of manifest.frames)
+                        out('  ' + describeRecord(f));
+                }
+                else if (sub === 'resolve') {
+                    const r = resolveFrame(defaultFramesDir(), String(tokens[2] ?? ''));
+                    out(r.status + (r.reason ? '（' + r.reason + '）' : '') + (r.path ? '  ' + r.path : ''));
+                }
+                else {
+                    out('用法：kf status | kf promote [seq|latest] [--note s] | kf list | kf resolve <kf:...>');
                 }
+                break;
+            }
+            default:
+                out('未知命令：' + head
+                    + (suggestHead(head) ? '（是想输入 ' + String(suggestHead(head)) + ' 吗？）' : '')
+                    + '（输入 help 看命令表）');
+        }
+    }
+    catch (e) {
+        if (e instanceof SessionError)
+            out('会话错误 [' + e.code + ']：' + e.message);
+        else
+            out('错误：' + (e instanceof Error ? e.message : String(e)));
+    }
+    return 'continue';
+}
+/* ─────────────────── 命名常驻会话（`--session <name>`）─────────────────── */
+/** 调用侧：复用已存在的会话，或首次起一个再送命令。 */
+async function runNamedSession(name, ctx) {
+    const wantStatus = ctx.values['session-status'] === true;
+    const wantStop = ctx.values['session-stop'] === true;
+    /* 命令收集：**只认 `--cmd`**。
+     *
+     * 为什么不用裸位置参数：位置参数会先被 repl 自己的选项表解析，于是
+     *   `repl --session cc run X --timeout 0`
+     * 里的 `--timeout` 被当成 repl 的选项直接 BAD_ARGUMENTS 拒掉。而绕开的写法
+     * （整条命令加引号）是个"必须记住"的坑，且退化形态更危险——实测
+     *   `repl --session cc screencap out.png`
+     * 里的位置参数被当成**两条命令**：`screencap`（用默认路径真截了一张、丢掉结果）
+     * + `out.png`（报未知命令），也就是**静默执行了错误的动作**。
+     * 所以这里只收 `--cmd`（可重复），并把裸位置参数当成明确的用法错误报出来，
+     * 不给"看起来成功了"的歧义空间。 */
+    const rawCmds = ctx.values.cmd;
+    const cmds = Array.isArray(rawCmds)
+        ? rawCmds.filter((c) => typeof c === 'string')
+        : typeof rawCmds === 'string' ? [rawCmds] : [];
+    if (ctx.positionals.length) {
+        return fail('BAD_ARGUMENTS', '命名会话的命令要用 --cmd 传（收到位置参数 ' + JSON.stringify(ctx.positionals) + '）', '例：maafw-live repl --session ' + name + ' --cmd "run X --timeout 0"\n' +
+            '       位置参数不加 --cmd 时会被当成多条独立命令（`screencap out.png` 会被拆成两条），\n' +
+            '       所以这里直接拒掉，不猜你的意图', EXIT.USAGE);
+    }
+    if (wantStop) {
+        const meta = readSessionMeta(name);
+        if (!meta)
+            return { exitCode: EXIT.OK, human: ['会话 ' + name + ' 不存在（无需收）'], data: { name, existed: false } };
+        stopSession(name);
+        return { exitCode: EXIT.OK, human: ['已收掉会话 ' + name + '（pid ' + meta.pid + '）'], data: { name, pid: meta.pid } };
+    }
+    const existing = readSessionMeta(name);
+    if (wantStatus) {
+        if (!existing)
+            return { exitCode: EXIT.OK, human: ['会话 ' + name + '：不存在'], data: { name, exists: false } };
+        const alive = pidAlive(existing.pid);
+        return {
+            exitCode: EXIT.OK,
+            human: [
+                '会话 ' + name + '：' + (alive ? '在跑' : '**已死**（meta 还在，但进程没了——用 --session-stop 清掉重起）'),
+                '  pid ' + existing.pid + '，起于 ' + existing.startedAt,
+                '  管道 ' + existing.pipe,
+                '  连接参数 ' + JSON.stringify(existing.connectArgs),
+                '  CLI 版本 ' + (existing.cliVersion ?? '(旧 meta，未记)') +
+                    (existing.cliVersion && existing.cliVersion !== cliPackage().version
+                        ? ' —— 当前 ' + cliPackage().version + '，混版'
+                        : ''),
+            ],
+            data: { ...existing, alive },
+        };
+    }
+    /* 起会话：把本次的连接参数原样交给常驻进程（同一套 CLI 旗标，不另造参数面） */
+    let meta = existing;
+    if (!meta || !pidAlive(meta.pid)) {
+        if (meta)
+            stopSession(name);
+        /* 连接参数透传 = CONNECT_OPTIONS 全集：之前只传 7 个字符串项，--no-pretask /
+         * --short-side / --long-side / --raw 在 --session 下被静默丢掉（P0-2）。
+         * 布尔值以裸旗标形态进 argv（connectArgsToArgv 对 true 只发 --k）。 */
+        const connectArgs = {};
+        for (const k of ['project', 'controller', 'resource', 'hwnd', 'address', 'kind', 'target', 'short-side', 'long-side']) {
+            const v = ctx.values[k];
+            if (typeof v === 'string')
+                connectArgs[k] = v;
+        }
+        for (const k of ['raw', 'no-pretask']) {
+            if (ctx.values[k] === true)
+                connectArgs[k] = true;
+        }
+        meta = spawnSessionServer(name, process.argv[1] ?? '', connectArgs);
+        const ready = await waitPipeReady(meta.pipe, 20000);
+        if (!ready) {
+            /* 真因几乎都在常驻进程自己的日志里（最常见的两种：POSIX 残留 socket 的 EADDRINUSE、
+             * 连接参数不合法）。不读回来就只剩"20s 不可连"这种没法行动的说法。 */
+            const tail = sessionServeLogTail(name);
+            stopSession(name);
+            return fail('SESSION_NOT_READY', '会话 ' + name + ' 起了但管道 ' + meta.pipe + ' 20s 内不可连（常驻进程启动即失败）', (tail.length ? '常驻进程日志尾部：\n    ' + tail.join('\n    ') + '\n' : '') +
+                '    常见原因：POSIX 上残留 socket 未被清（删掉 ' + meta.pipe + ' 重试）；连接参数不合法（多设备未给 --address）', EXIT.FINDINGS);
+        }
+    }
+    /* 不带 --cmd = 交互式：把本进程的 stdin 逐行送进常驻会话，输出照原样打印。
+     * 这样 `repl --session x` 的手感与普通 repl 一致，但连接状态跨调用保持。 */
+    if (!cmds.length) {
+        const rl = readline.createInterface({ input: process.stdin, terminal: process.stdin.isTTY === true });
+        const lines = [];
+        let wake = null;
+        let ended = false;
+        rl.on('line', (l) => { lines.push(l); if (wake) {
+            const w = wake;
+            wake = null;
+            w();
+        } });
+        rl.on('close', () => { ended = true; if (wake) {
+            const w = wake;
+            wake = null;
+            w();
+        } });
+        const ask = async () => {
+            for (;;) {
+                if (lines.length)
+                    return lines.shift() ?? null;
+                if (ended)
+                    return null;
+                await new Promise((r) => { wake = r; });
+            }
+        };
+        try {
+            for (;;) {
+                if (process.stdin.isTTY)
+                    process.stdout.write('maa[' + name + ']> ');
+                const l = await ask();
+                if (l === null)
+                    break;
+                if (!l.trim())
+                    continue;
+                const rep = await sendToSession(meta, l, 600000);
+                for (const o of rep.lines)
+                    process.stdout.write(o + '\n');
+                if (rep.error)
+                    process.stdout.write('错误：' + rep.error + '\n');
+                if (rep.closing || /^(quit|exit)\s*$/i.test(l.trim()))
+                    break;
             }
         }
         finally {
             rl.close();
+        }
+        return { exitCode: EXIT.OK, human: ['会话 ' + name + ' 保持运行（用 --session-stop ' + name + ' 收掉）'], data: { name, pid: meta.pid } };
+    }
+    /* 带 --cmd：逐条串行送进会话。能翻成 argv 的走 exec（结构化 result 随回执回来——
+     * --json 下信封才有命令数据，不再只剩 {name,pid}）；REPL 方言（quit/stream/logs/
+     * wait stable 这类）仍走 line 路径由常驻侧 switch 解释。 */
+    const human = [];
+    const results = [];
+    let exitCode = EXIT.OK;
+    for (const line of cmds) {
+        const argv = replToArgv(line);
+        if (argv) {
+            const rep = await sendToSessionExec(meta, argv, 600000);
+            /* rep.lines = 待认领输出（连接横幅、上一条异步收尾）+ 本命令 human——并入
+             * result.human，否则 --json 下横幅与异步尾巴整条丢（forwardToSession 同款逻辑） */
+            if (rep.result && rep.lines.length)
+                rep.result.human = rep.lines;
+            human.push(...rep.lines);
+            if (rep.error)
+                human.push('错误：' + rep.error);
+            results.push(rep.result ?? null);
+            if (exitCode === EXIT.OK && rep.result && rep.result.exitCode !== EXIT.OK) {
+                exitCode = rep.result.exitCode;
+            }
+            if (exitCode === EXIT.OK && !rep.result && rep.error)
+                exitCode = EXIT.FAIL;
+            continue;
+        }
+        const rep = await sendToSession(meta, line, 600000);
+        human.push(...rep.lines);
+        results.push(null);
+        if (rep.error) {
+            human.push('错误：' + rep.error);
+            if (exitCode === EXIT.OK)
+                exitCode = EXIT.FAIL;
+        }
+        if (rep.closing || /^(quit|exit)\s*$/i.test(line.trim())) {
+            stopSession(name);
+            break;
+        }
+    }
+    return {
+        exitCode,
+        human,
+        /* results 与 cmds 对齐；REPL 方言条目为 null（line 路径没有结构化结果） */
+        data: { name, pid: meta.pid, results },
+    };
+}
+/**
+ * REPL 行 → argv 的方言翻译表。翻不了（REPL 私有命令）返回 null，调用方走 line 路径。
+ * 这是会话"两个实现漂移"的止血带：翻译完进的是 dispatchArgv，与一次性 CLI 同一份
+ * 实现——`run T --option` 在 --cmd 里从此生效（P0-3）。
+ */
+export function replToArgv(line) {
+    const t = tokenize(line);
+    const head = t[0] ?? '';
+    switch (head) {
+        case 'connect': {
+            if (t[1] === 'project')
+                return ['connect', '--project', ...(t.slice(2).length ? t.slice(2) : [])];
+            if (t[1] === 'win32') {
+                if (!t[2])
+                    return null;
+                return ['connect', '--kind', 'win32', '--target', t[2], ...t.slice(3)];
+            }
+            if (t[1] === 'adb') {
+                if (!t[2])
+                    return null;
+                return ['connect', '--kind', 'adb', '--address', t[2], ...t.slice(3)];
+            }
+            /* `connect --project d` 这类直接就是 argv 形态 */
+            if (t[1]?.startsWith('--'))
+                return t;
+            return null;
+        }
+        case 'wait':
+            if (t[1] === 'stable' || t[1] === 'change')
+                return ['wait', '--mode', t[1], ...t.slice(2)];
+            return null;
+        case 'help':
+        case 'quit':
+        case 'exit':
+        case 'stream':
+        case 'logs':
+        case 'repl':
+            return null;
+        default:
+            /* 真命令名直接放行（EXEC_HEADS 与 commands/index 同步维护）；
+             * REPL 私有的 touchdown/touchmove/touchup 手势等留 line 路径。 */
+            return EXEC_HEADS.has(head) ? t : null;
+    }
+}
+/** 常驻侧：从命名管道收命令，交给与交互式 repl 同一份 `runReplLine` 执行。 */
+async function runSessionServer(name, ctx) {
+    const client = spawnDaemon();
+    const state = { session: '(未连接)', plan: null };
+    const remember = (s) => {
+        state.session = String(s.session?.target ?? '(已连接)');
+        state.plan = s.plan ?? null;
+    };
+    const server = new SessionServer((line, reply) => {
+        void runReplLine(line, { client, out: (l) => server.pushOutput(l), state, remember })
+            .then((step) => {
+            reply({ ok: true, lines: [], ...(step === 'quit' ? { closing: true } : {}) });
+            if (step === 'quit') {
+                /* 收尾延后一拍：先把回执写出去，调用方才能读到"会话已结束"而不是连接被掐 */
+                setTimeout(() => {
+                    server.close();
+                    try {
+                        client.close();
+                    }
+                    catch { /* ignore */ }
+                    process.exit(0);
+                }, 150);
+            }
+        })
+            .catch((e) => reply({ ok: false, lines: [], error: e instanceof Error ? e.message : String(e) }));
+    }, 
+    /* exec 路径：argv → dispatchArgv（与一次性 CLI 同一份实现），result 结构化回给调用方。
+     * human 行同时推进回执缓冲——非 --json 的调用方要的文本、会话日志都靠它。 */
+    (argv, reply) => {
+        void dispatchArgv(argv, { client, cwd: process.cwd() })
+            .then(({ result }) => {
+            for (const l of result.human ?? [])
+                server.pushOutput(l);
+            reply({
+                ok: result.exitCode === EXIT.OK || result.exitCode === EXIT.FINDINGS,
+                result,
+                ...(result.error ? { error: result.error.message } : {}),
+            });
+        })
+            .catch((e) => reply({ ok: false, error: e instanceof Error ? e.message : String(e) }));
+    });
+    /* 先建连接、再 listen：反过来的话命令可能在 `ensureSession` 完成**之前**到达，
+     * 那条命令会跑在一个还没连接的会话上（表现为"第一条命令报未连接，第二条才好"）。
+     * 而调用侧有 `waitPipeReady` 轮询，所以推迟 listen 不会让它空等——
+     * 它只是在管道就绪前一直重试，拿到的一定是连接完成的会话。 */
+    const o = sessionOptions(ctx);
+    const startup = [];
+    if (o.project || o.kind) {
+        /* 命名会话的起连同样算"启动"（--no-pretask 已可经 connectArgs 透传进来） */
+        if (o.pretask === undefined)
+            o.pretask = true;
+        try {
+            const s = await ensureSession(client, o);
+            remember(s);
+            startup.push('已连接：' + state.session);
+        }
+        catch (e) {
+            startup.push('连接失败：' + (e instanceof Error ? e.message : String(e)));
+        }
+    }
+    else {
+        startup.push('未连接设备。先 connect project <dir> 或 connect win32 <target>。');
+    }
+    const pipe = sessionPipePath(name);
+    try {
+        /* POSIX 下管道是文件系统里的 socket 文件，父目录必须在 listen 之前就存在，
+         * 否则 listen 直接 ENOENT（Windows 命名管道不走文件系统，这里是空操作）。 */
+        ensureSessionDir(name);
+        await server.listen(pipe);
+    }
+    catch (e) {
+        try {
             client.close();
         }
-        return { exitCode: EXIT.OK, human: ['会话结束。'] };
-    },
-};
+        catch { /* ignore */ }
+        return fail('SESSION_PIPE_FAILED', '命名管道 ' + pipe + ' 监听失败：' + (e instanceof Error ? e.message : String(e)), '同名会话可能已在跑；用 --session-status ' + name + ' 查，或 --session-stop ' + name + ' 收掉', EXIT.FINDINGS);
+    }
+    /* 横幅在 listen 之后入待认领队列：它在第一条命令的回执里出现，与交互式 repl 的"先报连接"一致 */
+    for (const l of startup)
+        server.pushStartup(l);
+    /* 常驻：等管道上的命令，直到收到 quit/exit 或父侧 stopSession 把进程杀掉 */
+    await new Promise(() => { });
+    return { exitCode: EXIT.OK, human: [] };
+}
 //# sourceMappingURL=repl.js.map