@windsland52/maafw-live 0.3.0 → 0.4.0

package/lib/commands/runtime.js

@@ -5,13 +5,17 @@
  * （控制器规划、资源解析、时间线）都不许写在这里——REPL 与其它壳（编辑器插件、面板）调的是同一批动作函数。
  */
 import { mkdirSync } from 'node:fs';
-import { dirname, join } from 'node:path';
+import { watchLogs } from '../runtime/log-watch.js';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
 import { defaultRunDir } from '../client/daemon.js';
-import { computePipelineOverride, mergeOverride } from '../interface/index.js';
 import { EXIT, fail } from '../protocol.js';
+import { parseOptionArgs } from '../option-args.js';
 import * as act from '../runtime/actions.js';
 import { withDaemon } from '../runtime/actions.js';
 import { describeSession, ensureSession, SessionError } from '../runtime/session.js';
+import { writeRunReceipt } from '../runtime/receipts.js';
+import { pruneDir } from '../runtime/prune.js';
+import { installRunSignalGuard } from '../runtime/signal-guard.js';
 /** 连接类选项：凡是要设备的命令都接受同一组，保证"怎么连"只有一套说法。 */
 export const CONNECT_OPTIONS = {
     project: { type: 'string' },
@@ -24,15 +28,30 @@ export const CONNECT_OPTIONS = {
     'short-side': { type: 'string' },
     'long-side': { type: 'string' },
     raw: { type: 'boolean' },
+    /* 跳过 interface.json 的 pretask（它会连 Controller 之前跑一次，非零即中止连接） */
+    'no-pretask': { type: 'boolean' },
 };
-export function sessionOptions(values) {
+/**
+ * 路径参数的解析基准：调用方给的目录就是 `ctx.cwd`（CLI 的 --cwd），不是 process.cwd()。
+ * 只处理**纯路径参数**（--project / --resource-dir / --out / --image / --frames-dir 等）——
+ * `--resource` 同时是"资源名"，能不能按路径解析要留给 resolveResourcePaths（名字优先），
+ * 所以它在 SessionOptions.cwd 里透传，不在这里 resolve。
+ */
+export function argPath(ctx, v) {
+    if (v === undefined)
+        return undefined;
+    return isAbsolute(v) ? v : resolve(ctx.cwd, v);
+}
+export function sessionOptions(ctx) {
+    const values = ctx.values;
     const num = (k) => {
         const v = values[k];
         return typeof v === 'string' && v !== '' ? Number(v) : undefined;
     };
     const str = (k) => (typeof values[k] === 'string' ? values[k] : undefined);
     return {
-        project: str('project'),
+        project: argPath(ctx, str('project')),
+        cwd: ctx.cwd,
         controller: str('controller'),
         resource: str('resource'),
         hwnd: str('hwnd'),
@@ -42,22 +61,32 @@ export function sessionOptions(values) {
         shortSide: num('short-side'),
         longSide: num('long-side'),
         rawSize: values.raw === true,
+        ...(values['no-pretask'] === true ? { pretask: false } : {}),
     };
 }
-/** daemon 抛出的错误一律翻译成结构化失败，不让堆栈进模型上下文。 */
+/** daemon 抛出的错误翻译成结构化失败。退出码按错误的**性质**分：
+ * 前置缺失（脚本找不到 / 会话规划失败）退 4；运行时故障（调用超时、进程退出、发送失败）退 1——
+ * 同一个 code 在所有路径退同一个码，agent 才不会按"缺环境"去查"daemon 卡住"。 */
 export function daemonFail(e, hint) {
     if (e instanceof SessionError)
         return fail(e.code, e.message, hint, EXIT.ENV);
     const msg = e instanceof Error ? e.message : String(e);
-    return fail('DAEMON_ERROR', msg, hint ?? '用 maafw-live probe 检查运行时；连接类错误先 maafw-live device 看有没有设备', EXIT.ENV);
+    /* 超时与进程退出是运行时故障，不是前置缺失：退 1，让"重试 / 换参数"排在"装环境"之前 */
+    if (/^daemon 调用超时|^daemon 已退出|^daemon 请求发送失败/.test(msg)) {
+        return fail('DAEMON_ERROR', msg, hint ?? '重试或看 maafw-live probe；连续出现先 kill 会话重连', EXIT.FAIL);
+    }
+    if (/^找不到 daemon 脚本/.test(msg)) {
+        return fail('DAEMON_ERROR', msg, hint ?? 'daemon 脚本缺失：检查 npm 安装是否完整', EXIT.ENV);
+    }
+    return fail('DAEMON_ERROR', msg, hint ?? '用 maafw-live probe 检查运行时；连接类错误先 maafw-live device 看有没有设备', EXIT.FAIL);
 }
 export const probeCommand = {
     name: 'probe',
     summary: '自检 maa-node 运行时：绑定版本、adb/win32 设备发现数',
     usage: 'maafw-live probe',
-    async run() {
+    async run(ctx) {
         try {
-            return await withDaemon(async (client) => {
+            return await withDaemon(ctx, async (client) => {
                 const info = await act.probe(client);
                 const devices = await act.deviceList(client, 'all').catch(() => []);
                 const human = [
@@ -87,7 +116,7 @@ export const deviceCommand = {
             return fail('BAD_ARGUMENTS', 'kind 只能是 all / adb / win32', undefined, EXIT.USAGE);
         }
         try {
-            return await withDaemon(async (client) => {
+            return await withDaemon(ctx, async (client) => {
                 const list = await act.deviceList(client, kind);
                 const human = list.length
                     ? list.map((d) => {
@@ -115,14 +144,14 @@ export const connectCommand = {
     usage: 'maafw-live connect --project <dir> | --kind win32|adb|gamepad [--target ...]',
     options: { ...CONNECT_OPTIONS },
     async run(ctx) {
-        const o = sessionOptions(ctx.values);
+        const o = sessionOptions(ctx);
         if (!o.project && !o.kind) {
             return fail('BAD_ARGUMENTS', '要么给 --project <dir>（按 interface.json 规划），要么给 --kind', '推荐 --project：控制器类型/窗口正则/输入方法/识别缩放全跟项目走', EXIT.USAGE);
         }
         try {
-            return await withDaemon(async (client) => {
+            return await withDaemon(ctx, async (client) => {
                 const s = await ensureSession(client, o);
-                const lines = describeSession(s);
+                const lines = describeSession(s, ctx.flags.verbose);
                 if (s.streamStopped) {
                     /* 重建控制器会让旧流失效：如实说，别让调用方以为是设备卡了（曾经是"流静默死掉"） */
                     lines.push('', '帧流：已停止（本次连接重建了控制器）；要看帧就 stream start 重开。');
@@ -146,16 +175,18 @@ export const connectCommand = {
 };
 export const disconnectCommand = {
     name: 'disconnect',
-    summary: '断开设备并销毁 Tasker/Controller（一次性命令，等价于结束 REPL 会话）',
-    usage: 'maafw-live disconnect --project <dir> | --kind ...',
+    summary: '断开设备并销毁 Tasker/Controller（会话内命令，等价于结束 REPL 会话）',
+    usage: 'maafw-live disconnect --session <name>（一次性形态：为断开先新连一次，没意义）',
     options: { ...CONNECT_OPTIONS },
+    /* 为断开先新连一次是自相矛盾的操作——断开会话态才需要"断开"（P0-3 L4） */
+    requiresSession: true,
     async run(ctx) {
-        const o = sessionOptions(ctx.values);
+        const o = sessionOptions(ctx);
         if (!o.project && !o.kind) {
             return fail('BAD_ARGUMENTS', '需要 --project 或 --kind 才能建立会话再断开', undefined, EXIT.USAGE);
         }
         try {
-            return await withDaemon(async (client) => {
+            return await withDaemon(ctx, async (client) => {
                 await ensureSession(client, o);
                 const r = await act.disconnect(client);
                 return { exitCode: EXIT.OK, human: ['已断开：' + JSON.stringify(r)], data: r };
@@ -166,27 +197,32 @@ export const disconnectCommand = {
         }
     },
 };
+/** 缺省落点 png/ 的保留上限（与 runs/ 同量级的"不留着看"产物） */
+const PNG_KEEP = 30;
 export const screencapCommand = {
     name: 'screencap',
     summary: '截一帧图并落盘（需要连接：给 --project 或 --kind）',
     usage: 'maafw-live screencap [--project <dir>|--kind ...] [--out <png>]',
     options: { ...CONNECT_OPTIONS, out: { type: 'string' } },
     async run(ctx) {
-        const o = sessionOptions(ctx.values);
-        const out = typeof ctx.values.out === 'string'
-            ? ctx.values.out
-            : join(defaultRunDir(), 'png', 'shot_' + Date.now() + '.png');
+        const o = sessionOptions(ctx);
+        const out = argPath(ctx, typeof ctx.values.out === 'string' ? ctx.values.out : undefined)
+            ?? join(defaultRunDir(), 'png', 'shot_' + Date.now() + '.png');
         try {
             mkdirSync(dirname(out), { recursive: true });
         }
         catch { /* 落盘失败交给 daemon 报错 */ }
+        /* 只修剪缺省落点 png/——显式 --out 是用户指定的位置，不动它 */
+        if (dirname(out) === join(defaultRunDir(), 'png')) {
+            pruneDir(dirname(out), { keep: PNG_KEEP, suffix: '.png' });
+        }
         try {
-            return await withDaemon(async (client) => {
+            return await withDaemon(ctx, async (client) => {
                 const s = await ensureSession(client, o);
                 const r = await act.screencap(client, out);
                 return {
                     exitCode: r.ok === false ? EXIT.FAIL : EXIT.OK,
-                    human: [...describeSession(s), '截图：' + String(r.path ?? out) + (r.bytes ? ' (' + r.bytes + ' bytes)' : '')],
+                    human: [...describeSession(s, ctx.flags.verbose), '截图：' + String(r.path ?? out) + (r.bytes ? ' (' + r.bytes + ' bytes)' : '')],
                     data: r,
                     written: r.path ? [String(r.path)] : [out],
                 };
@@ -197,21 +233,97 @@ export const screencapCommand = {
         }
     },
 };
+export const eventsCommand = {
+    name: 'events',
+    summary: '查帧流事件（stable/change/run），每条自带画面锚点；--watch 可自起帧流现场采集',
+    usage: 'maafw-live events [--limit <n>] [--since <seq>] [--watch <ms>] [--fps <n>]\n' +
+        '       --watch <ms>：本次调用内先起帧流、等 ms 毫秒、再查（**推荐**：daemon 随命令退出而销毁，\n' +
+        '                     事件环不跨进程存活，所以"查上一次留下的记录"是拿不到的）\n' +
+        '       不带 --watch：只查当前 daemon 会话里已有的事件——一次性 CLI 里这通常为空，\n' +
+        '                     该用法主要用于 REPL 之外的脚本在同进程内先跑 run 再查\n' +
+        '       每条事件 frame.retained=l0 表示画面还能取（frame get <seq> / kf promote），gone 表示已滚出',
+    options: { ...CONNECT_OPTIONS, limit: { type: 'string' }, since: { type: 'string' }, watch: { type: 'string' }, fps: { type: 'string' } },
+    async run(ctx) {
+        const o = sessionOptions(ctx);
+        const rawLimit = ctx.values.limit;
+        const limit = typeof rawLimit === 'string' ? Number(rawLimit) : 20;
+        if (!Number.isFinite(limit) || limit <= 0) {
+            return fail('BAD_ARGUMENTS', '--limit 必须是正整数', undefined, EXIT.USAGE);
+        }
+        const rawSince = ctx.values.since;
+        const since = typeof rawSince === 'string' ? Number(rawSince) : undefined;
+        if (rawSince !== undefined && !Number.isFinite(since)) {
+            return fail('BAD_ARGUMENTS', '--since 必须是数字（seq）', undefined, EXIT.USAGE);
+        }
+        const rawWatch = ctx.values.watch;
+        const watch = typeof rawWatch === 'string' ? Number(rawWatch) : undefined;
+        if (rawWatch !== undefined && (!Number.isFinite(watch) || watch <= 0)) {
+            return fail('BAD_ARGUMENTS', '--watch 必须是正毫秒数', undefined, EXIT.USAGE);
+        }
+        const rawFps = ctx.values.fps;
+        const fps = typeof rawFps === 'string' ? Number(rawFps) : undefined;
+        if (rawFps !== undefined && (!Number.isFinite(fps) || fps <= 0)) {
+            return fail('BAD_ARGUMENTS', '--fps 必须是正数', undefined, EXIT.USAGE);
+        }
+        try {
+            return await withDaemon(ctx, async (client) => {
+                const s = await ensureSession(client, o);
+                /* --watch：daemon 随命令退出而销毁，事件环不跨进程存活——所以"自己起流、现场采集"
+                 * 是一次性 CLI 拿到事件的唯一可靠方式。用 `wait` 的 change/stable 语义不合适
+                 * （它等到第一个满足就返回，而我们要的是"跑满这段窗口"），直接起流后按毫秒等。 */
+                let watched = null;
+                if (watch !== undefined) {
+                    await act.streamStart(client, fps !== undefined ? { fps } : {});
+                    await new Promise((r) => setTimeout(r, watch));
+                    watched = { ...(fps !== undefined ? { fps } : {}), ms: watch };
+                }
+                const r = await act.eventsList(client, { limit, ...(since !== undefined ? { since } : {}) });
+                const evs = r.events ?? [];
+                const human = [...describeSession(s, ctx.flags.verbose), '事件 ' + evs.length + ' 条' +
+                        (r.matched !== r.total ? '（匹配 ' + r.matched + ' / 环内共 ' + r.total + '）' : '') +
+                        (r.truncated ? '，已按 --limit 截取' : '') +
+                        (watched ? '（本次起流 ' + watched.ms + 'ms' + (watched.fps ? ' @' + watched.fps + 'fps' : '') + ' 现场采集）' : '')];
+                if (!evs.length) {
+                    human.push(watched
+                        ? '  （这 ' + watched.ms + 'ms 内画面没有变化：事件只在"动了"或"静下来"时产生，' +
+                            '静止画面不产生事件。要抓变化就加长 --watch 或在等待期间对设备做操作）'
+                        : '  （环内没有事件：daemon 随命令退出而销毁，事件环不跨进程存活——' +
+                            '加 --watch <ms> 让它本次调用内起流采集，或改用 REPL 会话）');
+                }
+                for (const e of evs) {
+                    const f = e.frame;
+                    const anchor = !f
+                        ? '  frame=?（无锚点）'
+                        : f.retained === 'l0'
+                            ? '  frame=l0:' + String(f.seq) + (f.source ? '（' + f.source + '）' : '') + ' → frame get ' + String(f.seq)
+                            : '  frame=gone（seq ' + String(f.seq) + ' 已滚出 L0，取不到了）';
+                    human.push('  ' + JSON.stringify(e) + anchor);
+                }
+                return { exitCode: EXIT.OK, human, data: r };
+            });
+        }
+        catch (e) {
+            return daemonFail(e, '事件环只在 daemon 存活期间保留；一次性 CLI 请用 --watch <ms> 现场采集');
+        }
+    },
+};
 export const frameCommand = {
     name: 'frame',
+    /* frame get 的环恒空（NO_FRAME）；frame status 读的是流状态，空环也算有内容的回答 */
+    requiresSession: (ctx) => ctx.positionals[0] === 'get',
     summary: '帧流状态与历史帧取用（环形缓冲只在 REPL 会话里才有内容）',
     usage: 'maafw-live frame status | maafw-live frame get [seq] [--roi x,y,w,h] [--out <png>] [--src auto|full|ring]\n' +
         '        --src full 强制要控制器分辨率原图（L0 已淘汰则报错，绝不给缩小图冒充）',
     options: { ...CONNECT_OPTIONS, roi: { type: 'string' }, out: { type: 'string' }, src: { type: 'string' } },
     async run(ctx) {
         const sub = ctx.positionals[0] ?? 'status';
-        const o = sessionOptions(ctx.values);
+        const o = sessionOptions(ctx);
         if (sub === 'status') {
             try {
-                return await withDaemon(async (client) => {
+                return await withDaemon(ctx, async (client) => {
                     const s = await ensureSession(client, o);
                     const st = await act.streamStatus(client);
-                    return { exitCode: EXIT.OK, human: [...describeSession(s), '帧流：' + JSON.stringify(st)], data: st };
+                    return { exitCode: EXIT.OK, human: [...describeSession(s, ctx.flags.verbose), '帧流：' + JSON.stringify(st)], data: st };
                 });
             }
             catch (e) {
@@ -232,14 +344,14 @@ export const frameCommand = {
         if (roi && (roi.length !== 4 || roi.some((n) => !Number.isFinite(n)))) {
             return fail('BAD_ARGUMENTS', '--roi 需要 4 个数字：x,y,w,h（控制器分辨率坐标，与 pipeline 的 roi 同空间）', undefined, EXIT.USAGE);
         }
-        const out = typeof ctx.values.out === 'string' ? ctx.values.out : undefined;
+        const out = argPath(ctx, typeof ctx.values.out === 'string' ? ctx.values.out : undefined);
         const srcRaw = typeof ctx.values.src === 'string' ? ctx.values.src.toLowerCase() : 'auto';
         if (!['auto', 'full', 'ring'].includes(srcRaw)) {
             return fail('BAD_ARGUMENTS', '--src 只支持 auto | full | ring', undefined, EXIT.USAGE);
         }
         const src = srcRaw;
         try {
-            return await withDaemon(async (client) => {
+            return await withDaemon(ctx, async (client) => {
                 await ensureSession(client, o);
                 const r = await act.frameGet(client, { seq, roi, out, src });
                 if (r.ok === false) {
@@ -269,6 +381,9 @@ export const frameCommand = {
 };
 export const waitCommand = {
     name: 'wait',
+    /* 预热截图不进环 → 恒 NO_FRAME 退 3；就算有帧也没流，stable 秒成立/change 必超时——
+     * 两种结果都是假信号（P0-3 L4） */
+    requiresSession: true,
     summary: '等状态谓词成立：stable=画面静下来 / change=画面动了（取代硬睡时钟）',
     usage: 'maafw-live wait stable|change [--timeout ms] [--quiet ms] [--roi x,y,w,h] [--threshold n]\n' +
         '        超时不算命令失败（ok=true, satisfied=false, 退出码 3）——"没等到"是观测结果',
@@ -283,7 +398,7 @@ export const waitCommand = {
             return fail('BAD_ARGUMENTS', 'wait 只认 stable | change' + (modeRaw ? '（收到 ' + JSON.stringify(modeRaw) + '）' : ''), '用法：maafw-live wait stable|change [--timeout ms] [--quiet ms] [--roi x,y,w,h] [--threshold n]', EXIT.USAGE);
         }
         const mode = modeRaw;
-        const o = sessionOptions(ctx.values);
+        const o = sessionOptions(ctx);
         const timeout = ctx.values.timeout !== undefined ? Number(ctx.values.timeout) : undefined;
         if (timeout !== undefined && !Number.isFinite(timeout)) {
             return fail('BAD_ARGUMENTS', '--timeout 必须是毫秒数', undefined, EXIT.USAGE);
@@ -303,7 +418,7 @@ export const waitCommand = {
             return fail('BAD_ARGUMENTS', '--roi 需要 4 个数字：x,y,w,h', undefined, EXIT.USAGE);
         }
         try {
-            return await withDaemon(async (client) => {
+            return await withDaemon(ctx, async (client) => {
                 await ensureSession(client, o);
                 const r = await act.waitState(client, {
                     mode,
@@ -335,9 +450,15 @@ export const waitCommand = {
 export const runCommand = {
     name: 'run',
     summary: '运行 pipeline：项目模式（推荐）或 resource 目录模式；节点事件按帧序对齐。退出码按任务级 record.ok',
-    usage: 'maafw-live run --entry <task> --project <dir> | --resource-dir <dir> [--timeout <ms|0>] [--override <json>] [--preset <name>] [--resource <名|路径>]\n' +
+    usage: 'maafw-live run --entry <task> --project <dir> | --resource-dir <dir> [--timeout <ms|0>] [--override <json>] [--preset <name>] [--resource <名|路径>] [--option <键>=<值>|<键>.<字段>=<值>]…\n' +
+        '       --option 按次给选项取值（可多次）：<键>=<case 名>（select/switch；checkbox 用逗号分隔）、\n' +
+        '                <键>.<字段>=<值>（input 的输入字段）。优先级 CLI > preset > default_case；\n' +
+        '                input/hotkey 的 pipeline_override 模板靠它替换 {字段名}（hotkey 按控制器 type 映射成键码）\n' +
+        '       项目模式的 pretask 在连 Controller **之前**执行（非零退出即中止，--no-pretask 跳过）\n' +
         '       --timeout 0 = 不自动停止（停止权交调用方：事件流判断 + maafw-live stop / 客户端 run_stop）；>0 时超时自动 post_stop\n' +
-        '       项目模式自动合成 pipeline_override（global→resource→controller→task，preset/default 取值），--override 最后覆盖',
+        '       项目模式自动合成 pipeline_override（global→resource→controller→task，preset/default 取值），--override 最后覆盖\n' +
+        '       --watch <日志条目> = 跑的同时实时 tail（可多次给）：文件 / glob（"logs/*.txt"）/ 目录（取每 tick 最新一个文件，日更轮转不丢）\n' +
+        '       --watch-include/--watch-exclude <regex> 筛选推送行；--watch-interval <ms> 推送间隔（默认 2000）',
     options: {
         ...CONNECT_OPTIONS,
         entry: { type: 'string' },
@@ -345,17 +466,27 @@ export const runCommand = {
         timeout: { type: 'string' },
         override: { type: 'string' },
         preset: { type: 'string' },
+        /* 按次取值（可多次给）：<键>=<case 名>（select/switch/checkbox）、<键>.<字段>=<值>（input） */
+        option: { type: 'string', multiple: true },
+        /* 运行期日志跟随：跑的时候把项目 agent 写的日志实时打出来（可多次给）。
+         * 条目语义见 watchLogs.entries：文件 / glob / 目录（每 tick 取最新 mtime）。 */
+        watch: { type: 'string', multiple: true },
+        'watch-interval': { type: 'string' },
+        'watch-include': { type: 'string', multiple: true },
+        'watch-exclude': { type: 'string', multiple: true },
     },
     async run(ctx) {
-        const o = sessionOptions(ctx.values);
+        const o = sessionOptions(ctx);
         const entry = (typeof ctx.values.entry === 'string' ? ctx.values.entry : ctx.positionals[0]) ?? undefined;
-        const resourceDir = typeof ctx.values['resource-dir'] === 'string' ? ctx.values['resource-dir'] : undefined;
+        const resourceDir = argPath(ctx, typeof ctx.values['resource-dir'] === 'string' ? ctx.values['resource-dir'] : undefined);
         if (!entry) {
             return fail('BAD_ARGUMENTS', '缺少入口任务名：--entry <task>', '项目模式=interface.json 的 task 名；bundle 模式=pipeline 首节点名', EXIT.USAGE);
         }
         if (!o.project && !resourceDir) {
             return fail('BAD_ARGUMENTS', '要么给 --project <dir>，要么给 --resource-dir <dir>', undefined, EXIT.USAGE);
         }
+        /* --override 收对象（=一层）或数组（=逐层）：框架按数组逐层继承，对象会被摊成
+         * [obj] 等价一层。字段缺失继承前值——与 GUI 客户端同一语义（@8061d5b 已核）。 */
         let override = {};
         if (typeof ctx.values.override === 'string') {
             try {
@@ -369,73 +500,105 @@ export const runCommand = {
         if (!Number.isFinite(timeoutMs)) {
             return fail('BAD_ARGUMENTS', '--timeout 必须是毫秒数', undefined, EXIT.USAGE);
         }
+        const presetName = typeof ctx.values.preset === 'string' ? ctx.values.preset : null;
+        const parsedOptions = parseOptionArgs(ctx.values.option);
+        if (parsedOptions.error) {
+            return fail('BAD_ARGUMENTS', parsedOptions.error, '例：--option taskOpt=b  --option 章节数.章节号=4', EXIT.USAGE);
+        }
+        const { cases: optionCases, fields: optionFields } = parsedOptions;
+        /* run 是"启动工作"类命令：pretask 要跑（P0-2——观测/输入类命令不跑，run 保留）。
+         * --no-pretask 显式关。 */
+        if (o.pretask === undefined)
+            o.pretask = true;
+        /* pretask 在连接之前就跑，所以按次取值必须在 ensureSession 之前挂进 SessionOptions——
+         * 否则同一次 run 里 pretask 的末位 JSON 与 pipeline_override 用的不是同一份取值。 */
+        if (Object.keys(optionCases).length)
+            o.optionCases = optionCases;
+        if (Object.keys(optionFields).length)
+            o.optionFields = optionFields;
         try {
-            return await withDaemon(async (client) => {
+            return await withDaemon(ctx, async (client) => {
                 const s = await ensureSession(client, o);
                 let args;
                 let resolvedEntry = entry;
-                let chain = null;
                 let extraWarns = [];
                 let appliedLines = [];
                 if (o.project) {
-                    const paths = s.plan?.resource?.paths ?? [];
-                    if (!paths.length) {
-                        return fail('RESOURCE_NOT_FOUND', '项目里没有解析出资源路径：检查 interface.json 的 resource[] 声明', undefined, EXIT.FINDINGS);
-                    }
-                    const task = s.plan?.loaded.tasks.find((t) => t.name === entry || t.entry === entry);
-                    resolvedEntry = task?.entry ?? entry;
-                    /* task 适用性（task.controller / task.resource 声明） */
-                    const ctrlName = s.plan?.controllerName ?? null;
-                    const resName = s.plan?.resource?.selected ?? null;
-                    if (task?.controller?.length && ctrlName && !task.controller.includes(ctrlName)) {
-                        return fail('TASK_NOT_APPLICABLE', '任务 ' + task.name + ' 不支持当前控制器 ' + ctrlName + '（声明：' + task.controller.join(' / ') + '）', '换 --controller ' + task.controller[0] + '，或选别的任务', EXIT.FINDINGS);
-                    }
-                    if (task?.resource?.length && resName && !task.resource.includes(resName)) {
-                        extraWarns.push('任务 ' + task.name + ' 声明资源 ' + task.resource.join(' / ') + '，当前选中的是 ' + resName);
-                    }
-                    /* pipeline_override 四级合并链（preset > default_case 取值） + 用户 --override 最后覆盖 */
-                    chain = computePipelineOverride({
-                        loaded: s.plan.loaded,
-                        controllerName: ctrlName,
-                        resourceName: resName,
-                        taskName: task?.name ?? null,
-                        presetName: typeof ctx.values.preset === 'string' ? ctx.values.preset : null,
+                    /* 入口解析 / task 适用性 / 四级 override / agent 桥接只有一份实现：
+                     * REPL `run` 调的是同一个 prepareProjectRun，不再各长一套规则。 */
+                    const prep = act.prepareProjectRun({
+                        project: s.plan,
+                        entry,
+                        presetName,
+                        override,
+                        ...(Object.keys(optionCases).length ? { optionCases } : {}),
+                        ...(Object.keys(optionFields).length ? { optionFields } : {}),
                     });
-                    extraWarns = [...extraWarns, ...chain.warns];
-                    appliedLines = chain.applied;
-                    const pt = s.plan.loaded.pretask;
-                    if (pt.length) {
-                        extraWarns.push('项目声明了 ' + pt.length + ' 条 pretask（' + pt.map((p) => p.exec ?? p.name ?? '?').join(' , ') + '），本 CLI 不执行——需自行保证前置条件');
-                    }
-                    const agents = s.plan.loaded.agents;
-                    if (agents.length) {
-                        extraWarns.push('项目声明了 ' + agents.length + ' 个 agent 子进程（' +
-                            agents.map((a) => [a.exec, ...a.args].join(' ')).join(' ; ') +
-                            '），run 时自动 spawn 并桥接——注意 maa-node 与 agent 侧 maa 库须同版本（协议握手要求）');
-                    }
-                    args = {
-                        resourceDirs: paths,
-                        entry: resolvedEntry,
-                        override: { ...chain.override },
-                        timeoutMs,
-                        /* agent 桥接：daemon spawn 子进程（identifier 追加为末参）并 bind/connect 到本次 Resource */
-                        agents: s.plan.loaded.agents.map((a) => ({ exec: a.exec, args: a.args })),
-                        agentCwd: s.plan.loaded.dir ?? undefined,
-                    };
+                    if (!prep.ok)
+                        return fail(prep.code, prep.error, prep.hint, EXIT.FINDINGS);
+                    args = prep.args;
+                    resolvedEntry = prep.entry;
+                    extraWarns = prep.warns;
+                    appliedLines = prep.applied;
                 }
                 else {
                     args = { resourceDir, entry, override, timeoutMs };
+                    /* bundle 模式不载入 interface，preset 没有可应用的四级链——静默丢参数会让调用方
+                     * 以为 P1 已生效；与 REPL 同一句警告。 */
+                    if (presetName)
+                        extraWarns.push('--resource-dir 是 bundle 模式：--preset ' + presetName + ' 不生效（不叠 interface 四级 override）');
+                    if (Object.keys(optionCases).length || Object.keys(optionFields).length) {
+                        extraWarns.push('--resource-dir 是 bundle 模式：--option 不生效（取值只作用于 interface 的 option 链与模板替换）');
+                    }
                 }
-                if (o.project && chain) {
-                    /* 用户 --override 最后覆盖合成结果；与四级链共用同一份合并实现（非对象值原样替换） */
-                    mergeOverride(args.override, override);
+                /* 运行期日志跟随：run 会阻塞到任务结束，期间帧流/事件都不可用（框架占住控制器），
+                 * 唯一还在更新的只有项目 agent 自己写的日志。给了 --watch 就在这里边跑边推。 */
+                const watchRaw = ctx.values.watch;
+                const watchEntries = (Array.isArray(watchRaw) ? watchRaw : watchRaw === undefined ? [] : [watchRaw])
+                    .filter((x) => typeof x === 'string' && x.length > 0)
+                    .map((x) => (isAbsolute(x) ? x : resolve(ctx.cwd, x)));
+                const watchInterval = Number(ctx.values['watch-interval'] ?? 2000);
+                /* include/exclude 正则：编译失败直接报 BAD_ARGUMENTS，不静默当无过滤跑 */
+                const watchInclude = (Array.isArray(ctx.values['watch-include']) ? ctx.values['watch-include'] : ctx.values['watch-include'] === undefined ? [] : [ctx.values['watch-include']])
+                    .filter((x) => typeof x === 'string');
+                const watchExclude = (Array.isArray(ctx.values['watch-exclude']) ? ctx.values['watch-exclude'] : ctx.values['watch-exclude'] === undefined ? [] : [ctx.values['watch-exclude']])
+                    .filter((x) => typeof x === 'string');
+                let includeRes;
+                let excludeRes;
+                try {
+                    includeRes = watchInclude.length ? watchInclude.map((r) => new RegExp(r)) : undefined;
+                    excludeRes = watchExclude.length ? watchExclude.map((r) => new RegExp(r)) : undefined;
                 }
-                const r = await act.run(client, args, timeoutMs);
+                catch (e) {
+                    return fail('BAD_ARGUMENTS', '--watch-include/--watch-exclude 不是合法正则：' + String(e.message), undefined, EXIT.USAGE);
+                }
+                const watcher = watchEntries.length
+                    ? watchLogs({ entries: watchEntries, intervalMs: Number.isFinite(watchInterval) ? watchInterval : 2000, include: includeRes, exclude: excludeRes }, (lines) => {
+                        /* 直写 stdout：--json 模式下也会混进人类可读行，所以下面的信封里另给 watch 统计，
+                         * 并在 --json 时把人类行改走 stderr（stdout 只留信封）。 */
+                        const sink = ctx.flags.json ? process.stderr : process.stdout;
+                        for (const l of lines)
+                            sink.write('[watch] ' + l + '\n');
+                    })
+                    : null;
+                /* 信号处理（审计 #6）：Ctrl-C / kill 时不许让 daemon 里的任务裸跑——向 daemon 发
+                 * run_stop（post_stop），run 回执照常落盘，退出码区分「我停的」与「它坏的」：
+                 * SIGINT=130 / SIGTERM=143（128+signo），任务自身失败仍是 1。
+                 * 第二次按信号直接 bail——第一次没杀掉说明 daemon 已不应答，再等没有现场可留。 */
+                /* 信号处理（审计 #6）：Ctrl-C / kill 时不许让 daemon 里的任务裸跑——向 daemon 发
+                 * run_stop，run 回执照常落盘，退出码区分「我停的」与「它坏的」（128+signo）。 */
+                /* 信号处理（审计 #6）：Ctrl-C / kill 时不许让 daemon 里的任务裸跑——向 daemon 发
+                 * run_stop，run 回执照常落盘，退出码区分「我停的」与「它坏的」（128+signo）。 */
+                const sigGuard = installRunSignalGuard(() => act.runStop(client).then(() => undefined));
+                /* finally 摘钩：act.run 抛错（daemon 死了）也不留监听残留 */
+                const r = await act.run(client, args, timeoutMs).finally(() => sigGuard.restore());
+                const interrupted = sigGuard.code;
+                const watchStats = watcher ? watcher.stop() : null;
                 if (r.ok === false || !r.record) {
                     /* 调用级失败：任务根本没跑起来（未连接 / 资源缺失 / 已有任务在跑）→ FINDINGS */
                     return {
                         exitCode: EXIT.FINDINGS,
-                        human: [...describeSession(s), '调用失败：' + String(r.error ?? 'run 未返回记录')],
+                        human: [...describeSession(s, ctx.flags.verbose), '调用失败：' + String(r.error ?? 'run 未返回记录')],
                         data: r,
                         warnings: [...extraWarns, ...(r.warns ?? [])],
                     };
@@ -445,7 +608,30 @@ export const runCommand = {
                 const rec = r.record;
                 const taskOk = rec.ok === true;
                 const nodes = rec.nodes ?? [];
+                /* 三态结论词：`status:0 + stopped:true` 单看 status 会被读成"成功完成"（本仓 G21 实测误读）。
+                 * 判据用 record 自带的 timeoutMs，不靠调用方回忆当初给了什么：
+                 *   跑满窗口被截断 → 非成功非失败（是"没跑完"，不是"跑完了没成功"）；
+                 *   stopped 但没跑满 → 是任务自己结束、只是没成功。
+                 * 退出码仍按任务级 record.ok，不给截断开绿灯。 */
+                const budget = 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 = interrupted
+                    ? (interrupted === EXIT.SIGINT ? '被 Ctrl-C 中断（SIGINT）' : '被终止信号中断（SIGTERM）')
+                    : taskOk
+                        ? '完成'
+                        : ranFull
+                            ? '超时截断（非成功，也非失败：任务没跑完就被 post_stop 了）'
+                            : rec.stopped === true
+                                ? '被停止（run_stop / 任务自身请求 post_stop，未成功）'
+                                : '失败';
                 const agentLines = [];
+                if (rec.hashCheck?.expected !== undefined) {
+                    agentLines.push(rec.hashCheck.match === true
+                        ? '  资源完整性：' + String(rec.hashCheck.resourceName) + ' hash 校验通过'
+                        : '  资源完整性：' + String(rec.hashCheck.resourceName) + ' hash 不匹配（期望 ' +
+                            String(rec.hashCheck.expected) + ' / 实际 ' + String(rec.hashCheck.actual || '?') + '），按 v2.6 语义不阻断');
+                }
                 if (rec.agent) {
                     agentLines.push(rec.agent.ok
                         ? '  agent 已连接' + (rec.agent.reused ? '（复用）' : '') + '：custom action ' +
@@ -453,9 +639,10 @@ export const runCommand = {
                         : '  agent 连接失败：' + String(rec.agent.error ?? '?'));
                 }
                 const human = [
-                    ...describeSession(s),
-                    '任务 ' + resolvedEntry + '：' + (taskOk ? '完成' : (rec.stopped ? '超时被停止（视为失败）' : '失败')) +
-                        '（status=' + String(rec.status) + '，' + String(rec.durationMs) + 'ms，帧序 ' +
+                    ...describeSession(s, ctx.flags.verbose),
+                    '任务 ' + resolvedEntry + '：' + verdict +
+                        '（status=' + String(rec.status) + '，' + String(rec.durationMs) + 'ms' +
+                        (budget !== null ? ' / timeout=' + String(budget) + 'ms' : '') + '，帧序 ' +
                         String(rec.startSeq) + '..' + String(rec.endSeq) + '）',
                     ...agentLines,
                     ...appliedLines.map((l) => '  override: ' + l),
@@ -478,10 +665,25 @@ export const runCommand = {
                 if (rec.agent && rec.agent.ok === false) {
                     extraWarns.push('agent 连接失败：' + String(rec.agent.error ?? '?'));
                 }
+                if (watchStats && watchStats.files.length === 0) {
+                    extraWarns.push('--watch 没有命中任何文件（' + watchEntries.join(' , ') + '）：检查路径是否存在、日志是否在跑起来之后才创建');
+                }
+                if (watchStats) {
+                    human.push('  运行期日志跟随：' + String(watchStats.pushed) + ' 行（来自 ' +
+                        String(watchStats.files.length) + ' 个文件）');
+                }
+                /* 回执全量落盘（与 repl 同一助手、同一目录约定）：W1 runs 存储的种子。
+                 * 失败只降级为不打路径行，不影响任务结论与退出码。 */
+                const receipt = writeRunReceipt(r, resolvedEntry);
+                if (receipt.path !== undefined) {
+                    human.push('  完整回执（含全部节点与 msgs）：' + receipt.path);
+                }
                 return {
-                    exitCode: taskOk ? EXIT.OK : EXIT.FAIL,
+                    /* 中断优先于任务结论：退出码讲"我怎么走的"，不讲"任务结果如何"（回执里有）。
+                     * 130=SIGINT / 143=SIGTERM，都是 128+signo 惯例。 */
+                    exitCode: interrupted || (taskOk ? EXIT.OK : EXIT.FAIL),
                     human,
-                    data: r,
+                    data: watchStats ? { ...r, watch: watchStats } : r,
                     warnings: [...extraWarns, ...(r.warns ?? [])],
                 };
             });
@@ -495,9 +697,11 @@ export const stopCommand = {
     name: 'stop',
     summary: '停止运行中的任务（post_stop）',
     usage: 'maafw-live stop',
-    async run() {
+    /* 一次性形态没意义：停的是自己刚起的空 daemon，回 ok 误导（设计审查 P0-3 L4） */
+    requiresSession: true,
+    async run(ctx) {
         try {
-            return await withDaemon(async (client) => {
+            return await withDaemon(ctx, async (client) => {
                 const r = await act.runStop(client);
                 return { exitCode: EXIT.OK, human: ['已请求停止：' + JSON.stringify(r)], data: r };
             });
@@ -509,6 +713,6 @@ export const stopCommand = {
 };
 export const RUNTIME_COMMANDS = [
     probeCommand, deviceCommand, connectCommand, disconnectCommand,
-    screencapCommand, frameCommand, waitCommand, runCommand, stopCommand,
+    screencapCommand, frameCommand, eventsCommand, waitCommand, runCommand, stopCommand,
 ];
 //# sourceMappingURL=runtime.js.map