@migor/cli 0.9.2 → 0.9.3

package/dist/dev.js

@@ -6,24 +6,42 @@
  * ```
  *   dev.ts（CLI，本文件）                        ← 唯一的进程所有者
  *     ├─ inspector 服务（面板 + POST /run）       ← 面板的读写入口
- *     ├─ fs.watch(src/**) + fs.watch(项目根, 只认 .env)  ← 「代码变了要重启」的**唯一**触发源
+ *     ├─ dev-watch.ts：fs.watch(src/**) + fs.watch(项目根, 只认 .env)  ← 「代码变了要重启」的**唯一**触发源
  *     └─ 子进程：node <tsx> dist/dev-runner.js     ← 常驻；import 用户的 src/app.ts 并驱动它
  *          └─ 用户代码 → trace 经 sink POST /ingest 回面板
  * ```
  *
  * ⚠️ 子进程是 `node <tsx/cli>`，**不是** `npx tsx` —— 后者会吞掉 IPC 通道，理由见
- * `resolveTsxCli()`（那不是一条风格偏好，是一次实测出来的静默故障）。
+ * `dev-child.ts` 的 `resolveTsxCli()`（那不是一条风格偏好，是一次实测出来的静默故障）。
  *
  * 与旧实现的三个区别，都记在 docs/plans/2026-09-22-dev-debug-loop.md：
- * 1. **watch 收编进本文件**。旧实现把「文件变 → 重跑」交给 `tsx watch`，而「面板 → 重启」
+ * 1. **watch 收编进 dev 环**。旧实现把「文件变 → 重跑」交给 `tsx watch`，而「面板 → 重启」
  *    要归 dev.ts ⇒ 两个触发源就有竞态（保存的瞬间恰好点了运行 = 双双 spawn、端口/SSE 串台）。
  *    现在只有一条路径、一个所有者；顺带解掉「`.md` 不在 tsx 的 import 图里所以不被 watch」。
+ *    （C 阶段起 watch 件住在 `dev-watch.ts`，本文件只在启动时接线。）
  * 2. **子进程跑 runner 而不是用户的 main.ts**。四个控件（能力选择 / 多轮 / 工作目录 /
  *    prompt）全是 `createApp` / `app.run` 的选项，而**调用者**能设它们 —— CLI 成了调用者，
  *    于是用户工程里一个 dev 文件都不需要。
  * 3. **trace sink 在 runner 里注册**（不再用 `NODE_OPTIONS=--import` 的 preload）：
  *    CLI 代码本来就在子进程里了，那套注入的存在理由消失了。
  *
+ * ## 本文件只剩「薄接线」（B 阶段，方案 docs/plans/2026-09-23-cli-structure.md §3 B；
+ * ## C 阶段把 watch 件与子进程原语切到 dev-watch.ts / dev-child.ts，见 §3 C）
+ *
+ * 曾经这里有一台隐式状态机（15 个 `let`、40 处写入点、15 个入口；F1/F4/G1/G2 都是它的
+ * 直接后果）。现在**所有「什么情况下该做什么」的判定都在 `dev-machine.ts` 的 `update()`
+ * 里**：每个入口把现实翻译成事件（`DevEventIn`）派发给机器，机器返回新状态与效果清单
+ * （`DevEffect[]`），本文件只负责**执行**效果 —— spawn / kill / IPC / HTTP / fs / 计时器。
+ *
+ * 接线层的纪律：
+ * - **进程身份归属在这里判**（机器看不到句柄）：迟到的消息只可能来自已经不在台上的
+ *   进程，一律不派发给机器；唯一例外是过时进程的 exit 仍要把它**自己那次 spawn 的
+ *   Promise** 收掉（否则启动期被杀的旧进程会把 `await` 它的人永远挂住）。
+ * - `restart` 效果自带「串行链 + 起跑时广播 runner-restart」（旧语义：广播发生在链任务
+ *   真正起跑时，且 closing 后整条链跳过 —— 所以它不是一条 emit 效果）。
+ * - `reject` / `send-ipc` / `arm-abort-timer` / `pick-folder` / `exit-now` 只出现在
+ *   专用流程里，由各 handler 就地解释（要能中断效果序列、把 reject 翻译成 HttpError）。
+ *
  * ## 什么会重启 runner
  *
  * | 变化 | 动作 | 为什么 |
@@ -31,7 +49,7 @@
  * | 能力选择（`toolSources`） | **重启进程** | 它是 `createApp` 的输入；而框架没有 `AgentApp.close()`，进程内反复重建会攒孤儿 MCP 子进程 ⇒ 进程边界是唯一的回收口（D8 第三轮补充） |
  * | 代码 / 文本资产变更 | **重启进程** | Node 的 import 按 URL 缓存，常驻进程收不到源码改动 |
  * | 工作目录 / prompt / 多轮 / 会话 id | **不重启** | 目录是 per-run 输入，runner 内部按目录重建 app（毫秒级）；prompt / 多轮 / 会话 id 本来就是 per-run |
- * | 面板点「中止」 | **先不重启**（优雅 abort） | 框架的 `signal` 是协作式的 ⇒ 中止后 run 以 `stopReason='aborted'` 正常返回、**trace 保得住**；但工具若不读 `signal` 就没人理 ⇒ 5 s 后升级为重启进程兜底（`ABORT_GRACE_MS`），否则 `running` 永远为 true、面板锁死 |
+ * | 面板点「中止」 | **先不重启**（优雅 abort） | 框架的 `signal` 是协作式的 ⇒ 中止后 run 以 `stopReason='aborted'` 正常返回、**trace 保得住**；但工具若不读 `signal` 就没人理 ⇒ 5 s 后升级为重启进程兜底（`ABORT_GRACE_MS`），否则 run 相位永远不落、面板锁死 |
  * | 面板点「清空对话」 | **不重启** | 只是换 sessionId（+ 落盘），下一次 run 换个 id 而已 |
  *
  * 面板是增强项，任何一步失败都只告警、不阻断 dev：inspector 起不来时**降级**成
@@ -41,65 +59,22 @@
  */
 import { spawn } from 'node:child_process';
 import { randomBytes } from 'node:crypto';
-import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, watch, writeFileSync, } from 'node:fs';
-import { createRequire } from 'node:module';
-import { dirname, join, relative, sep } from 'node:path';
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, join, relative } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { KILL_GRACE_MS, killTree, resolveTsxCli } from './dev-child.js';
+import { createInitialState, READY_TIMEOUT_MS, resolveWorkdir, runGateFlags, startupExitMessage, update, } from './dev-machine.js';
+import { APP_ENTRY_REL, DEV_SESSION_ID, SESSION_ID_REL, SESSION_REL, } from './dev-protocol.js';
+import { watchRootEnvFiles, watchTree } from './dev-watch.js';
 import { HttpError, startInspector } from './inspector.js';
-import { multiTurnDefault, normalizeToolSources } from './panel-logic.js';
-import { APP_ENTRY_REL, DEFAULT_BUDGET, DEV_SESSION_ID, SESSION_ID_REL, SESSION_REL, } from './dev-protocol.js';
+import { killActivePickers, pickFolderNative } from './native-pick.js';
+// nextSessionId 已随状态机迁到 dev-machine（纯件）；shouldWatch / watchTree /
+// watchRootEnvFiles 已随 C 阶段迁到 dev-watch —— 本文件继续 re-export 它们的出口：
+// packages/cli/test/panel-logic.test.mjs 从 dist/dev.js 取这些纯件，出口不能断。
+export { nextSessionId } from './dev-machine.js';
+export { shouldWatch, watchRootEnvFiles, watchTree } from './dev-watch.js';
 const HERE = dirname(fileURLToPath(import.meta.url));
 const RUNNER = join(HERE, 'dev-runner.js');
-/**
- * 解析 tsx 的 CLI 入口（绝对路径）。
- *
- * ## 为什么不走 `npx tsx`（实测，不是风格偏好）
- *
- * `npx` 是个**包装器**：它自己再 spawn 一层，而**不把 fd 3 的 IPC 通道转发给孙进程**。
- * 后果不是「启动失败」而是**静默**：runner 里 `process.send` 变成 `undefined`，而
- * `send()` 写的是 `process.send?.()`（可选链）—— 于是所有协议消息被无声丢弃：
- * 面板永远等不到 `ready`，`POST /run` 也永远回不来。更坏的是没有 IPC 通道之后事件循环
- * 无事可做，进程会以 **code=0 干净退出**，看起来像「用户代码自己跑完了」。
- *
- * 同一个 hello 脚本的三方对照：
- *
- * | 启动方式 | `typeof process.send` | IPC |
- * |---|---|---|
- * | `node whoami.mjs` | `function` | ✅ 收到 |
- * | `npx tsx whoami.mjs` | `undefined` | ❌ 无（还多出 npx 的 spinner 噪音） |
- * | `node <tsx>/dist/cli.mjs whoami.mjs` | `function` | ✅ 收到 |
- *
- * ## 为什么不 spawn `node_modules/.bin/tsx`
- *
- * Windows 上它是 `.cmd` shim，会绕回 `npm-bin.ts` 专门要避开的那个 CVE-2024-27980 坑。
- * 直接 `node <tsx/dist/cli.mjs>` 跨平台一致，且是**直接子进程** ⇒ IPC 天然可用。
- *
- * 解析顺序：**用户工程优先**（tsx 是脚手架声明的 devDependency，尊重他们的版本 pin），
- * 再退到 CLI 自己的解析位置（monorepo / 全局安装）。两处都没有 ⇒ `null`，调用方响亮报错。
- */
-export function resolveTsxCli(root, fromCli) {
-    for (const base of [join(root, 'package.json'), fromCli]) {
-        try {
-            return createRequire(base).resolve('tsx/cli');
-        }
-        catch {
-            /* 试下一个解析位置 */
-        }
-    }
-    return null;
-}
-/** 子进程就绪的等待上限：装配正常是毫秒级，MCP 重的工程也要不了这么久 */
-const READY_TIMEOUT_MS = 60_000;
-/** 子进程优雅退出的等待上限，超时补 SIGKILL（kill 必须连整棵树 —— 见 killTree） */
-const KILL_GRACE_MS = 3_000;
-/** 文件事件去抖：编辑器保存常常连发好几个事件（写临时文件 + rename） */
-const WATCH_DEBOUNCE_MS = 150;
-/**
- * 「中止」发出后等它优雅收尾的宽限：超时就重启进程兜底（见 `abortRun`）。
- * 取 5s —— 优雅路径要在**回合边界**才生效（在飞的模型请求先被取消），
- * 给足一个回合；再长就等于按钮按了没反应。
- */
-const ABORT_GRACE_MS = 5_000;
 /**
  * 收尾的**硬上限**：超过它就硬退。
  *
@@ -107,254 +82,6 @@ const ABORT_GRACE_MS = 5_000;
  * 而不是替 SIGKILL 兜底计时器的班（那个兜底只在宽限期到点时才会发出来）。
  */
 const SHUTDOWN_DEADLINE_MS = KILL_GRACE_MS + 2_000;
-/**
- * 会触发重启的文件类型（**允许清单**，不是排除清单）。
- *
- * 用允许清单而不是「除了 node_modules 都算」：`.DS_Store` / 编辑器 swap / 日志会
- * 让常驻进程反复重启，而那种重启看起来像「agent 自己在抖」。
- * `.md` **必须在**里面 —— 文本资产（`@Prompt` 拉的 `.md`、子 agent 的 `system.md`）
- * 不在 tsx 的 import 图里，旧实现因此对它们**静默无感**（D4 的 G3b）。
- */
-const WATCH_EXT = new Set(['.ts', '.mts', '.cts', '.tsx', '.js', '.mjs', '.cjs', '.json', '.md']);
-/**
- * 按文件名（而非扩展名）命中的环境变量文件。
- *
- * ⚠️ 它们**不在** `watchTree` 的根（`src/`）下 ⇒ 由 `watchRootEnvFiles` 单独盯。
- * 早先只有 `shouldWatch` 认识这两个名字、却没有任何一个 watch 够得着它们，
- * 于是「改 `.env` 会重启」是一句**没人执行**的承诺（真跑抓出来的，见 `watchRootEnvFiles`）。
- */
-const WATCH_NAMES = new Set(['.env', '.env.local']);
-/**
- * 不看的目录：产物、依赖、VCS、dev 自己的状态。
- *
- * ⚠️ 这道闸是**第二层**。第一层是**监视根**：`devServer` 只 `watchTree(<projectRoot>/src)`
- * —— `.agentia/`（会话历史 + 当前会话 id）与 `dist/` 都在项目根，**根本不在范围内**。
- * 两层都要有：只靠根的话，哪天把根改成项目根（一个很自然的想法），`.agentia/session.json`
- * 就会立刻变成「每次多轮 run 重启一次子进程」的自噬循环。
- */
-const WATCH_SKIP = new Set(['node_modules', 'dist', '.git', '.agentia', 'coverage']);
-/**
- * 这个文件该不该触发重启？**导出是为了单测** —— 它是「改 `.md` 会不会重启」这条
- * 承诺的唯一判据，而那条承诺正是旧实现静默失效的地方（G3b）。
- */
-export function shouldWatch(abs) {
-    const base = abs.slice(abs.lastIndexOf(sep) + 1);
-    if (WATCH_NAMES.has(base))
-        return true;
-    const dot = base.lastIndexOf('.');
-    return dot > 0 && WATCH_EXT.has(base.slice(dot));
-}
-/**
- * 杀掉**整棵树**。
- *
- * `npx tsx` 自己还会 spawn 子进程，只 kill 直接子进程会留下孤儿（照搬 v0.7.0
- * 「`close()` 保证子进程已终止」的纪律）。POSIX 下靠 `detached: true` 把子进程
- * 变成进程组组长，再对**负 pid** 发信号；win32 没有进程组，用 `taskkill /T`。
- */
-function killTree(child, signal) {
-    const pid = child.pid;
-    if (pid === undefined)
-        return;
-    if (process.platform === 'win32') {
-        try {
-            spawn('taskkill', ['/pid', String(pid), '/T', '/F'], { stdio: 'ignore' });
-        }
-        catch {
-            /* 已经退出了 */
-        }
-        return;
-    }
-    try {
-        process.kill(-pid, signal); // 负 pid = 整个进程组
-    }
-    catch {
-        try {
-            child.kill(signal);
-        }
-        catch {
-            /* 已经退出了 */
-        }
-    }
-}
-/**
- * 这个**目录**要不要进 watch 范围？
- *
- * ⚠️ 判据必须由 `addDir` 自己执行，不能只留在「初始递归」那一个调用点 ——
- * 动态新增目录（watcher 回调里发现新目录时调 `addDir`）走的是**另一条路**，
- * 只在一处判就等于「启动时就存在的 `dist/` 不看、启动后才出现的 `dist/` 看」。
- *
- * 真实影响面由**监视根**兜着（`devServer` 只看 `<projectRoot>/src`，见 `WATCH_SKIP`），
- * 所以它今天多半打不到 `.agentia` —— 但那是「碰巧打不到」，不是「判据成立」。
- *
- * 判据只看**目录名**（不看路径段）：项目根本身叫 `dist` / `node_modules` 是合法的
- * （见 `shouldWatch` 的同一条教训），所以 root 由调用方显式豁免。
- */
-function shouldDescend(dir) {
-    const name = dir.slice(dir.lastIndexOf(sep) + 1);
-    return !WATCH_SKIP.has(name) && !name.startsWith('.');
-}
-/**
- * 文件事件去抖通知器：同一批事件只回调**第一条**。
- *
- * 为什么抽出来共用：**两个** watch（递归目录树 `watchTree` / 项目根的 env 文件
- * `watchRootEnvFiles`）都要同一套去抖与关闭语义。各写一份就会漂 —— 比如只有一处清理
- * `timer`，关闭后仍会回调一次；而那种漂的后果是「停机时又重启了一次子进程」。
- */
-function makeNotifier(onFile) {
-    let closed = false;
-    let timer = null;
-    const pending = new Set();
-    const flush = () => {
-        timer = null;
-        if (closed || pending.size === 0)
-            return;
-        const first = [...pending][0];
-        pending.clear();
-        onFile(first);
-    };
-    return {
-        note: (abs) => {
-            if (closed)
-                return;
-            pending.add(abs);
-            if (timer === null)
-                timer = setTimeout(flush, WATCH_DEBOUNCE_MS);
-        },
-        dispose: () => {
-            closed = true;
-            if (timer !== null)
-                clearTimeout(timer);
-        },
-    };
-}
-/**
- * 递归 watch 一个目录树（`fs.watch` 的 recursive 在 Linux 上到 Node 20 才稳，
- * 这里自己递归 + 新目录动态加入，跨平台同一条代码路径）。
- *
- * 跳过目录（`WATCH_SKIP` / 点开头）的判据由 `addDir` **内部**执行 —— 初始递归与
- * 动态新增两条路共用它，见 `shouldDescend`。
- *
- * ⚠️ 它只看**一棵**树：`.env` / `.env.local` 在项目根、不在 `src/` 下，所以那两份由
- * `watchRootEnvFiles` 单独盯（见它的说明）。
- *
- * **导出是为了单测**：它是「改文本资产不用重启」那条承诺的落点。
- */
-export function watchTree(root, onFile) {
-    const watchers = new Map();
-    let closed = false;
-    const notifier = makeNotifier(onFile);
-    const note = (abs) => {
-        if (closed || !shouldWatch(abs))
-            return;
-        notifier.note(abs);
-    };
-    /** @param isRoot 项目根自己 —— 它可能就叫 `dist` / `.foo`，但必须看（唯一豁免处） */
-    const addDir = (dir, isRoot = false) => {
-        if (closed || watchers.has(dir))
-            return;
-        // 跳过目录的判据在**这里**（唯一一处），不在调用点 —— 见 shouldDescend 的说明
-        if (!isRoot && !shouldDescend(dir))
-            return;
-        let entries;
-        try {
-            entries = readdirSync(dir, { withFileTypes: true });
-        }
-        catch {
-            return; // 目录刚被删掉
-        }
-        let w;
-        try {
-            w = watch(dir, { persistent: true }, (_event, name) => {
-                if (name === null)
-                    return;
-                const abs = join(dir, String(name));
-                note(abs);
-                // 新目录要加进 watch 范围（否则新加的能力目录永远不触发重启）。
-                // 跳过判据由 addDir 内部执行 ⇒ 这里**不要**再判一次（两处判就会漂）。
-                try {
-                    if (statSync(abs).isDirectory())
-                        addDir(abs);
-                }
-                catch {
-                    /* 被删了 */
-                }
-            });
-        }
-        catch {
-            return; // 权限 / 已被删
-        }
-        w.on('error', () => { });
-        watchers.set(dir, w);
-        for (const e of entries) {
-            if (e.isDirectory())
-                addDir(join(dir, e.name));
-        }
-    };
-    addDir(root, true);
-    return () => {
-        closed = true;
-        notifier.dispose();
-        for (const w of watchers.values())
-            w.close();
-        watchers.clear();
-    };
-}
-/**
- * 只盯**项目根**下按文件名命中的那几份文件（`.env` / `.env.local`）。
- *
- * **为什么单开一个、而不是把 `watchTree` 的根抬到项目根**：`.env` 在项目根，而**其他**
- * 该看的东西都在 `src/` —— 抬根会把 `README.md` / `docs/` / `examples/` 全收进来，
- * 「改代码要重启」就变成「改任何文档也重启」。所以这里刻意**不递归**，且**只认名字**
- * （不认扩展名：项目根的 `package.json` 同样不该由这里管）。
- *
- * ⚠️ 它存在的理由：`WATCH_NAMES` 曾经是一条**够不着**的判据 —— 允许清单里有 `.env`、
- * `usage-guide` 也承诺「看 `.env`」，但 `watchTree` 的根是 `<projectRoot>/src`，
- * 而 `.env` 在项目根 ⇒ 改 `.env` **静默无感**（与 G3b 同类：文档承诺了、代码够不着）。
- * **这条只有真跑能守**：根是**调用点**决定的，`watchTree` 自己无从知道该看哪儿
- * （`scripts/e2e-dev.ts` 第 9-bis 步钉着它）。
- */
-export function watchRootEnvFiles(root, onFile) {
-    const notifier = makeNotifier(onFile);
-    let w;
-    try {
-        w = watch(root, { persistent: true }, (_event, name) => {
-            if (name === null)
-                return;
-            const base = String(name);
-            if (!WATCH_NAMES.has(base))
-                return;
-            notifier.note(join(root, base));
-        });
-    }
-    catch {
-        return () => { }; // 项目根不可 watch（权限）—— 静默降级成「只看 src/」，与旧行为一致
-    }
-    w.on('error', () => { });
-    return () => {
-        w.close();
-        notifier.dispose();
-    };
-}
-/**
- * 「清空对话」换到的下一个 id：`dev` → `dev-2` → `dev-3` …（导出是为了单测，同 `shouldWatch`）。
- *
- * 为什么是**换 id** 而不是删会话文件：`session.json` 是 `SessionStore` 的账，面板对它
- * **只读**（写它会造出「面板显示的对话」与「模型真正看到的对话」不一致，见 `readSession`）。
- * 而「当前用哪个 id」是 dev 环的界面状态 ⇒ 换 id 就够，且**不动别人的账**
- * （旧对话还在盘上，run 列表里那些 run 也都还指得到）。
- *
- * 认不出的形状（用户手工改了 id 文件）⇒ 回到 `-2`，不抛：一个怪 id 不该让面板坏掉。
- */
-export function nextSessionId(current, base = DEV_SESSION_ID) {
-    // base 是**参数**（导出为单测用）⇒ 进正则前先转义。现在只有默认值走得到，
-    // 但「一个参数迟早被传脏值」这类坑不值得留着（`.x` 会变成「任意字符 + x」）
-    const esc = base.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-    const m = new RegExp(`^${esc}(?:-(\\d+))?$`).exec(current);
-    if (m === null)
-        return `${base}-2`;
-    const n = m[1] === undefined ? 1 : Number(m[1]);
-    return `${base}-${n + 1}`;
-}
 /**
  * @param argv 透传给 dev 环的参数：`agentia dev -- "问题"` 时 argv[0] 是**首次 run 的 prompt**。
  *   脚手架把 `npm run dev` 指到本命令，而工程 README 文档化的用法正是
@@ -382,37 +109,22 @@ export function devServer(argv = []) {
         process.exitCode = 1;
         return 1;
     }
-    let child = null;
+    // ---------- 接线层持有的句柄（不进机器状态：不可序列化，机器只管「相位 + 数据」） ----------
     let inspector = null;
     let stopWatch = null;
     /** 项目根那份 `.env` / `.env.local` 的 watch —— 与 `stopWatch` 是**两个**，两者都要收 */
     let stopEnvWatch = null;
-    let closing = false;
-    let running = false;
-    /**
-     * 「已经受理、但 run 还没发出去」的窄窗口标志（`submitRun` 里换能力选择要 `await restart`）。
-     *
-     * 为什么必须有它：`running` 只能在 run **真的发进通道之后**置位（它是「runner 里有个
-     * run 在飞」的口径，面板据此禁用按钮、`abortRun` 据此判「有没有可中止的东西」）。
-     * 而受理到发出之间有一次 await ⇒ 只看 `running` 的闸在「改了能力选择 ⇒ 双击运行」
-     * 这条路径上会**放两个请求进来**（两个 `runOnce` 并发、`currentAbort` 被覆盖、
-     * `pendingNote` 挂到别人的 traceId 上）。§6 待定 5 承诺的是**默认拒绝**。
-     *
-     * 刻意**不**并进 `running`（那会让面板在还没 run 时就把「中止」按钮点亮，而
-     * `abortRun` 此时只能回 409 —— 一个自相矛盾的面板）。
-     */
-    let launching = false;
-    let lastError = null;
-    /** 在飞 run 期间来的文件变更：等 run 收尾再重启（不在飞的 run 不该被掐掉） */
-    let pendingRestart = null;
-    let pendingNote = null;
+    /** 当代子进程句柄（机器状态的 `child` 相位对应的实物；身份归属判定靠它） */
+    let currentProc = null;
+    /** 中止在飞 run 的兜底计时器（机器侧对应 `run: 'aborting'` 相位 + arm/disarm 效果） */
+    let abortTimer = null;
     /** 重启串行化：两次重启不能交叠（否则会留下没人管的子进程） */
     let chain = Promise.resolve();
     /** dev token（D0）：每个 dev 会话一个，进程退出即失效 */
     const token = randomBytes(16).toString('hex');
     // ---------- 会话 id（面板的「清空对话」） ----------
     /**
-     * 当前会话 id。从 `.agentia/dev-session-id` 读，读不到就用 `DEV_SESSION_ID`。
+     * 当前会话 id 的初值：从 `.agentia/dev-session-id` 读，读不到就用 `DEV_SESSION_ID`。
      *
      * 为什么要落盘：只放内存的话，用户「清空对话」之后重启 `npm run dev`，
      * 刚清掉的那段对话会**自己回来** —— 静默不一致。
@@ -429,7 +141,6 @@ export function devServer(argv = []) {
             return DEV_SESSION_ID;
         }
     };
-    let sessionId = readSessionId();
     const writeSessionId = (id) => {
         try {
             mkdirSync(join(projectRoot, '.agentia'), { recursive: true });
@@ -440,23 +151,104 @@ export function devServer(argv = []) {
             console.warn(`[agentia] 会话 id 落盘失败（${e.message}）：本次「清空对话」在重启 dev 后会失效`);
         }
     };
-    /** 中止在飞 run 的兜底计时器：signal 是**协作式**的，卡死的工具不会理它（见 abortRun） */
-    let abortTimer = null;
+    // ---------- 状态机 ----------
+    // 全部可变状态收敛在这一个对象里（15 个 let → DevMachineState 的显式字段）；
+    // 迁移只经 update()，写入点只有 dispatch 与各 handler 里的 `state = r.state`。
+    let state = createInitialState({ projectRoot, sessionId: readSessionId() });
     const clearAbortTimer = () => {
         if (abortTimer !== null) {
             clearTimeout(abortTimer);
             abortTimer = null;
         }
     };
-    // ---------- 子进程 ----------
-    const spawnChild = (toolSources) => {
+    /** 机器效果里只允许专用流程解释的几种（走到通用执行器就是接线错了，响亮失败） */
+    const SPECIAL_ONLY = new Set([
+        'reject',
+        'send-ipc',
+        'arm-abort-timer',
+        'pick-folder',
+        'exit-now',
+    ]);
+    /**
+     * 通用效果执行器：同步效果立即按序执行；异步效果（restart / spawn-child / stop-child /
+     * close-inspector）按序 await，返回的 Promise 由调用方决定等不等。
+     * 异步函数在第一个 await 之前是同步执行的 ⇒ 纯同步效果序列（如 emit）保持同步语义。
+     */
+    const runEffects = async (effects) => {
+        for (const e of effects) {
+            switch (e.kind) {
+                case 'emit':
+                    inspector?.emitDev(e.event);
+                    break;
+                case 'note-run':
+                    inspector?.noteRun(e.traceId, e.note);
+                    break;
+                case 'log':
+                    if (e.level === 'error')
+                        console.error(e.message);
+                    else if (e.level === 'warn')
+                        console.warn(e.message);
+                    else
+                        console.log(e.message);
+                    break;
+                case 'persist-session-id':
+                    writeSessionId(e.id);
+                    break;
+                case 'disarm-abort-timer':
+                    clearAbortTimer();
+                    break;
+                case 'stop-watchers':
+                    stopWatch?.();
+                    stopEnvWatch?.();
+                    break;
+                case 'kill-pickers':
+                    killActivePickers();
+                    break;
+                case 'kill-child':
+                    if (currentProc)
+                        killTree(currentProc, 'SIGKILL');
+                    break;
+                case 'restart':
+                    await restartExec(e.reason, e.toolSources);
+                    break;
+                case 'spawn-child':
+                    // 首次拉起：失败归 boot-failed（机器：lastError + 终端 error + 唯一一帧 runner-error）
+                    await spawnExec(e.toolSources).catch((err) => {
+                        void dispatch({ type: 'boot-failed', message: err.message });
+                    });
+                    break;
+                case 'stop-child':
+                    await stopChildExec();
+                    break;
+                case 'close-inspector':
+                    if (inspector)
+                        await inspector.close();
+                    break;
+                default:
+                    throw new Error(`效果「${String(e.kind)}」不该走通用执行器（SPECIAL_ONLY：${[...SPECIAL_ONLY].join('/')}）`);
+            }
+        }
+    };
+    /** 派发一个事件：状态迁移**同步**生效，效果随后执行（返回效果的 Promise） */
+    const dispatch = (ev) => {
+        const r = update(state, ev);
+        state = r.state;
+        return runEffects(r.effects);
+    };
+    // ---------- 子进程（spawn / stop / restart 三个执行器） ----------
+    /**
+     * 拉起一代 runner 并等到它 ready（或失败）。状态迁移全部由派发事件完成；
+     * 这里只管：spawn、挂监听、归属判定、就绪超时。
+     */
+    const spawnExec = async (toolSources) => {
         // 每次 spawn 都重解析一次：tsx 是启动期才知道存不存在的东西（用户可能刚 `npm i -D tsx`），
         // 缓存住会让「装好了但还报找不到」这种话变成一句谎。
         const tsxCli = resolveTsxCli(projectRoot, import.meta.url);
         if (tsxCli === null) {
-            return Promise.reject(new Error('找不到 tsx —— dev 环要用它跑 TypeScript 源码（runner 会 import 你的 src/app.ts）。\n' +
-                '装一个即可：npm i -D tsx（脚手架生成的工程已经声明了它；手写工程把它加进 devDependencies）'));
+            throw new Error('找不到 tsx —— dev 环要用它跑 TypeScript 源码（runner 会 import 你的 src/app.ts）。\n' +
+                '装一个即可：npm i -D tsx（脚手架生成的工程已经声明了它；手写工程把它加进 devDependencies）');
         }
+        void dispatch({ type: 'child-spawned', toolSources });
         const env = {
             ...process.env,
             // ⚠️ cwd 必须仍是**项目根**：loadEnvFile() 按 cwd 找 .env、discover 的相对路径也按 cwd。
@@ -466,8 +258,9 @@ export function devServer(argv = []) {
             AGENTIA_INSPECT_TOKEN: token,
             ...(toolSources === null ? {} : { AGENTIA_DEV_TOOL_SOURCES: JSON.stringify(toolSources) }),
         };
-        // `process.execPath` + tsx 的 CLI 入口，而不是 `npx tsx`（理由见 resolveTsxCli）：
-        // 直接子进程 ⇒ fd 3 的 IPC 通道可用；也顺带丢掉 npx 那一层启动开销与 spinner 噪音。
+        // `process.execPath` + tsx 的 CLI 入口，而不是 `npx tsx`（理由见 dev-child.ts 的
+        // resolveTsxCli）：直接子进程 ⇒ fd 3 的 IPC 通道可用；也顺带丢掉 npx 那一层启动开销
+        // 与 spinner 噪音。
         const proc = spawn(process.execPath, [tsxCli, RUNNER], {
             cwd: projectRoot,
             stdio: ['inherit', 'inherit', 'inherit', 'ipc'],
@@ -475,141 +268,110 @@ export function devServer(argv = []) {
             detached: process.platform !== 'win32',
             env,
         });
-        const handle = {
-            child: proc,
-            capabilities: [],
-            multiTurn: [],
-            defaultWorkdir: projectRoot,
-            // 就绪前只能给缺省值（真正生效的那份由 `ready` 消息报上来）
-            budget: { ...DEFAULT_BUDGET },
-            warning: null,
-            toolSources,
-        };
-        // 立刻挂上（不是等到 ready）：ready 之前崩掉的进程也得能被 stopChild 收掉，
-        // 否则每失败一次就留一个孤儿 npx/tsx 进程树。
-        child = handle;
-        return new Promise((resolve, reject) => {
+        // 立刻挂上（不是等到 ready）：ready 之前崩掉的进程也得能被 stopChildExec 收掉，
+        // 否则每失败一次就留一个孤儿 tsx 进程树。
+        currentProc = proc;
+        await new Promise((resolve, reject) => {
             let settled = false;
             const timer = setTimeout(() => {
-                killTree(proc, 'SIGKILL');
-                fail(`dev runner 启动超时（${READY_TIMEOUT_MS} ms 内没有就绪信号）`);
+                if (settled)
+                    return;
+                settled = true;
+                if (currentProc === proc) {
+                    // 机器：lastError = 超时文案 + kill-child 效果（就地执行 ⇒ killTree 这个孩子）
+                    void dispatch({ type: 'child-ready-timeout' });
+                    currentProc = null;
+                    reject(new Error(state.lastError));
+                }
+                else {
+                    // 过时进程（已被摘掉）：只收掉自己的 Promise，不碰机器状态
+                    reject(new Error(`dev runner 启动超时（${READY_TIMEOUT_MS} ms 内没有就绪信号）`));
+                }
             }, READY_TIMEOUT_MS);
-            /**
-             * 启动失败 ⇒ **把 child 摘掉**，不能把一个死 handle 留在那儿。
-             *
-             * 为什么这是硬要求：`restart` 的失败路径靠 `if (!child)` 判「起不来」（⇒ 回 500、
-             * `running` 不置位），而 spawn 出来的进程如果只发了 `'error'`（ENOENT / EACCES 那类），
-             * 它**不会**再发 `'exit'`、`exitCode` 恒为 `null` ⇒ 留着的话下一次 `POST /run` 会
-             * 往一条已断的通道 `send()`（抛 `ERR_IPC_CHANNEL_CLOSED`），且 `running` 卡在 `true`
-             * ⇒ 面板之后每次运行都 409。摘掉它，`if (!child)` 就能正确报「runner 起不来」。
-             */
-            const fail = (message) => {
+            proc.on('error', (err) => {
                 if (settled)
                     return;
                 settled = true;
                 clearTimeout(timer);
-                if (child?.child === proc)
-                    child = null;
-                reject(new Error(message));
-            };
-            proc.on('error', (err) => {
-                lastError = `启动 dev runner 失败：${err.message}`;
-                fail(lastError);
+                if (currentProc === proc) {
+                    // spawn 失败（ENOENT/EACCES）：不会再有 exit。摘掉当代（机器的迁移）+ 拒 Promise
+                    void dispatch({ type: 'child-spawn-failed', message: err.message });
+                    currentProc = null;
+                    reject(new Error(state.lastError));
+                }
+                else {
+                    reject(err);
+                }
             });
             proc.on('message', (raw) => {
                 // 归属判定用**进程身份**而不是代号：迟到的消息只可能来自已经不在台上的那个进程
-                if (child?.child !== proc)
+                if (currentProc !== proc)
                     return;
                 const msg = raw;
                 if (msg.type === 'ready') {
-                    handle.capabilities = msg.capabilities;
-                    handle.multiTurn = msg.multiTurn;
-                    handle.defaultWorkdir = msg.defaultWorkdir;
-                    handle.budget = msg.budget;
-                    handle.warning = msg.warning;
-                    if (msg.warning)
-                        console.warn(`[agentia] ${msg.warning}`);
-                    // 广播「就绪」：面板加载时那次 /api/dev 拿到的还是初值（capabilities 为空），
-                    // 没有这一条它就一直空着 —— 详见 dev-protocol 的 DevEvent 注释。
-                    emit({ kind: 'runner-ready' });
+                    void dispatch({
+                        type: 'child-ready',
+                        capabilities: msg.capabilities,
+                        multiTurn: msg.multiTurn,
+                        defaultWorkdir: msg.defaultWorkdir,
+                        budget: msg.budget,
+                        warning: msg.warning,
+                    });
                     if (!settled) {
                         settled = true;
                         clearTimeout(timer);
-                        resolve(handle);
+                        resolve();
                     }
                     return;
                 }
                 if (msg.type === 'run-start') {
-                    running = true;
+                    void dispatch({ type: 'ipc-run-start' });
                     return;
                 }
                 if (msg.type === 'run-done') {
-                    running = false;
-                    clearAbortTimer();
-                    if (msg.traceId !== null && pendingNote !== null) {
-                        inspector?.noteRun(msg.traceId, pendingNote);
-                    }
-                    pendingNote = null;
-                    // 中止的 run 也带 error（`abortedResult()` 刻意如此）⇒ `ok` 是 false。
-                    // 但它**不是**「环坏了」，不该在告警条上留一条永远不消的红字（判别只看 stopReason）。
-                    if (!msg.ok && msg.stopReason !== 'aborted')
-                        lastError = msg.error;
-                    emit({
-                        kind: 'run-done',
+                    void dispatch({
+                        type: 'ipc-run-done',
                         traceId: msg.traceId,
                         ok: msg.ok,
                         stopReason: msg.stopReason,
                         error: msg.error,
                         finalText: msg.finalText,
                     });
-                    void afterRun();
                     return;
                 }
                 if (msg.type === 'run-error') {
-                    running = false;
-                    clearAbortTimer();
-                    pendingNote = null;
-                    lastError = msg.message;
-                    emit({ kind: 'runner-error', message: msg.message });
-                    void afterRun();
+                    void dispatch({ type: 'ipc-run-error', message: msg.message });
                 }
             });
             proc.on('exit', (code, sig) => {
-                const isCurrent = child?.child === proc;
-                if (isCurrent)
-                    child = null;
                 const how = `code=${code ?? 'null'}${sig ? `, signal=${sig}` : ''}`;
+                const isCurrent = currentProc === proc;
+                if (isCurrent) {
+                    currentProc = null;
+                    // 机器按相位分流：starting ⇒ 启动失败归因（**不 emit**，F4：发射权在等 spawn 的
+                    // 那一侧）；ready ⇒ 意外退出 + emit runner-error；closing ⇒ 静默摘除
+                    void dispatch({ type: 'child-exit', how });
+                }
                 if (!settled) {
-                    // 没等到 ready 就退了 ⇒ 这是**启动失败**，不是「跑着跑着意外退出」。
-                    // ⚠️ 必须先把原因写进 lastError 再往下走：下面的 emit 是同步执行的，而
-                    // fail() 的 reject 要等到下一个微任务才被调用方的 catch 接住 —— 先 reject
-                    // 会让面板收到一句更笼统的「意外退出」，把真正的原因挤成只出现在终端里。
-                    lastError = `dev runner 退出（${how}）—— 多半是用户代码 import 期就抛了，看上面的输出`;
-                    fail(lastError);
+                    settled = true;
+                    clearTimeout(timer);
+                    // 当代进程：机器刚把原因写进 lastError（exitReason，G1 判据），Promise 用它拒；
+                    // 过时进程：不碰机器状态（lastError 与新一代共享，写给上一代 = 张冠李戴），
+                    // 但它自己这次 spawn 的 Promise 必须收掉，否则启动期被杀的旧进程会挂住等待方。
+                    reject(new Error(isCurrent ? (state.lastError ?? startupExitMessage(how)) : startupExitMessage(how)));
                 }
-                if (!isCurrent || closing)
-                    return;
-                running = false;
-                clearAbortTimer();
-                lastError = lastError ?? `dev runner 意外退出（${how}）`;
-                emit({ kind: 'runner-error', message: lastError });
             });
         });
     };
-    const stopChild = async () => {
-        const handle = child;
-        child = null;
-        if (!handle)
+    const stopChildExec = async () => {
+        const proc = currentProc;
+        currentProc = null;
+        if (!proc)
             return;
-        // ⚠️ 子进程要没了 ⇒ **不可能再有在飞 run**，必须把 running 落下来。
-        // 为什么这是硬要求：`proc.on('exit')` 的归属判定（`child?.child === proc`）此刻已经
-        // 为假（上一行刚把 child 置 null），所以 exit 处理器会**早退**、不会帮忙清 running。
-        // 少了这一行，「中止超时 ⇒ 重启兜底」之后 running 永远是 true ⇒ 之后每次 POST /run
-        // 都 409 —— 面板**照样锁死**，只是从「卡在 run 上」变成「卡在 running 标志上」。
-        // （唯一会在 run 在飞时杀子进程的路径就是这条兜底：文件变更那条走 pendingRestart 延后。）
-        running = false;
-        clearAbortTimer();
-        const proc = handle.child;
+        // 子进程要没了 ⇒ 不可能再有在飞 run：机器的 child-stopped 迁移把 run 相位落下来
+        // （旧代码这里漏过 running=false，症状是「中止超时 ⇒ 重启兜底」之后面板永久 409）。
+        // 派完之后这个进程的 exit 到来时已不是当代 ⇒ 不会再触发归因（与旧 isCurrent 早退一致）。
+        void dispatch({ type: 'child-stopped' });
         if (proc.exitCode !== null || proc.signalCode !== null)
             return;
         await new Promise((done) => {
@@ -624,180 +386,162 @@ export function devServer(argv = []) {
             killTree(proc, 'SIGTERM');
         });
     };
-    /** 重启 = 停旧的 + 起新的；串行化，且把「重启」这件事广播给面板（不静默） */
-    const restart = (reason, toolSources) => {
+    /** 重启 = 停旧的 + 起新的；串行化，且把「重启」这件事广播给面板（不静默）。
+     *  广播在**链任务真正起跑时**发（与旧 restart 一致）：排在后面的重启不提前广播，
+     *  closing 之后整条链跳过。 */
+    const restartExec = (reason, toolSources) => {
         chain = chain.then(async () => {
-            if (closing)
+            if (state.closing)
                 return;
-            emit({ kind: 'runner-restart', reason });
-            await stopChild();
+            inspector?.emitDev({ kind: 'runner-restart', reason });
+            await stopChildExec();
             try {
-                await spawnChild(toolSources);
+                await spawnExec(toolSources);
             }
             catch (e) {
-                lastError = e.message;
-                emit({ kind: 'runner-error', message: lastError });
+                // 失败归 restart-failed（机器：lastError + 唯一一帧 runner-error）
+                void dispatch({ type: 'restart-failed', message: e.message });
             }
         });
         return chain;
     };
-    /** run 收尾后处理「在飞期间攒下的重启请求」 */
-    const afterRun = () => {
-        if (pendingRestart === null || closing)
-            return Promise.resolve();
-        const reason = pendingRestart;
-        pendingRestart = null;
-        return restart(reason, child?.toolSources ?? null);
-    };
-    // ---------- 面板侧 ----------
-    const emit = (ev) => inspector?.emitDev(ev);
+    // ---------- 面板侧（hooks：把 HTTP 翻译成事件，把效果翻译成响应） ----------
     const devState = () => ({
         available: true,
         projectRoot,
         home: process.env.HOME ?? '',
-        capabilities: child?.capabilities ?? [],
-        multiTurn: child?.multiTurn ?? [],
-        warning: child?.warning ?? null,
-        defaultWorkdir: child?.defaultWorkdir ?? projectRoot,
+        capabilities: state.capabilities,
+        multiTurn: state.multiTurn,
+        warning: state.warning,
+        defaultWorkdir: state.defaultWorkdir,
         // 生效值由 runner 报（就绪前是缺省值）—— 面板显示与实际生效必须是同一份
-        budget: child?.budget ?? { ...DEFAULT_BUDGET },
-        sessionId,
-        running,
-        lastError,
+        budget: state.budget,
+        sessionId: state.sessionId,
+        running: runGateFlags(state).running,
+        lastError: state.lastError,
     });
+    /** 专用流程共用：从效果清单里取出 reject 并抛成 HttpError（机器的「拒绝」出面） */
+    const throwIfRejected = (effects) => {
+        const rej = effects.find((e) => e.kind === 'reject');
+        if (rej && rej.kind === 'reject')
+            throw new HttpError(rej.status, rej.message);
+    };
     const submitRun = async (req) => {
-        // ⚠️ 闸必须**同时**看 `launching`：受理到 run 真正发出去之间有 `await restart(...)`，
-        //    只判 `running` 的话「改了能力选择 ⇒ 双击运行」的两个请求会双双通过 ⇒
-        //    runner 里两个 `runOnce` 并发、`currentAbort` 被覆盖、`pendingNote` 挂错 traceId。
-        //    §6 待定 5 承诺的是**默认拒绝**，而这条正是当初漏掉的路径。
-        if (running || launching) {
-            throw new HttpError(409, '上一次 run 还在跑。等它结束，或先「中止」它再发新的（并发语义见计划 §6 待定 5）');
-        }
-        // 上一轮中止留下的兜底计时器不该跨到这一轮来（否则会掐掉一次正常的 run）
-        clearAbortTimer();
-        const caps = child?.capabilities ?? [];
-        const selected = req.toolSources ?? caps;
-        const toolSources = normalizeToolSources(selected, caps);
-        const workdir = req.workdir && req.workdir.length > 0 ? req.workdir : devState().defaultWorkdir;
-        if (!existsSync(workdir) || !statSync(workdir).isDirectory()) {
-            // 响亮失败：目录写错时**不能**退回项目根 —— 那会让 agent 对着错的目录乱写（D5）
-            throw new HttpError(400, `工作目录不存在或不是文件夹：${workdir}`);
-        }
-        const defaults = multiTurnDefault(toolSources ?? caps, child?.multiTurn ?? []);
-        const multiTurn = req.multiTurn ?? defaults.value;
+        const workdir = resolveWorkdir(req, state.defaultWorkdir);
+        // 查盘是副作用 ⇒ 接线层做，机器只拿事实判 400。响亮失败：目录写错时**不能**退回
+        // 项目根 —— 那会让 agent 对着错的目录乱写（D5）。
+        const workdirExists = existsSync(workdir) && statSync(workdir).isDirectory();
+        const r = update(state, { type: 'ui-run-requested', req, workdir, workdirExists });
+        state = r.state;
+        throwIfRejected(r.effects);
+        /** 发出前任何一步失败：机器复位 + 补延后重启（旧 finally 的职责），再以 500 出面 */
+        const failLaunch = (message) => {
+            const r2 = update(state, { type: 'run-launch-failed', message });
+            state = r2.state;
+            void runEffects(r2.effects.filter((e) => e.kind !== 'reject'));
+            throwIfRejected(r2.effects);
+            throw new Error(message); // 不可达（run-launch-failed 必带 reject），只喂类型
+        };
         let restarted = false;
-        const prev = child?.toolSources ?? null;
-        const same = (prev === null && toolSources === undefined) ||
-            (prev !== null &&
-                toolSources !== undefined &&
-                prev.join('\u0000') === toolSources.join('\u0000'));
-        // 占位：从这里到「run 发出」之间不能让第二个请求通过上面的闸（见 launching 的说明）。
-        // 校验已经做完（工作目录在上一行之前判过）⇒ 占位期间不会有 400 把标志留在 true 上。
-        launching = true;
-        try {
-            if (!child || !same) {
-                // 换能力选择 ⇒ 重启进程（D8：理由是回收口，不是成本）。不重启的话旧 app 的
-                // MCP 子进程没人收编 —— 框架没有 AgentApp.close()。
-                restarted = true;
-                await restart('能力选择变化（toolSources）', toolSources ?? null);
-                if (!child)
-                    throw new HttpError(500, lastError ?? 'runner 起不来');
+        for (const e of r.effects) {
+            if (e.kind === 'disarm-abort-timer') {
+                // 上一轮中止留下的兜底计时器不该跨到这一轮来（否则会掐掉一次正常的 run）
+                clearAbortTimer();
             }
-            pendingNote = {
-                prompt: req.prompt,
-                workdir,
-                toolSources: toolSources ?? null,
-                multiTurn,
-            };
-            running = true; // 乐观置位：连点两次在 runner ack 之前就该被拒
-            // 会话 id 由**父进程**给：它是面板级状态（「清空对话」换的就是它），
-            // 且必须跨 runner 重启稳定 —— 改代码会重启 runner，但不该丢掉会话。
-            // （面板**不能**指定它，见 `RunRequest` 里那条说明。）
-            let sent = false;
-            try {
-                sent = child.child.send({
-                    type: 'run',
-                    request: {
-                        prompt: req.prompt,
-                        workdir,
-                        multiTurn,
-                        sessionId,
-                        toolSources: toolSources ?? null,
-                    },
-                });
+            else if (e.kind === 'restart') {
+                restarted = true;
+                await restartExec(e.reason, e.toolSources);
+                if (state.child !== 'ready')
+                    failLaunch(state.lastError ?? 'runner 起不来');
             }
-            catch (e) {
-                // 通道刚断开时 `send()` **会抛**（`ERR_IPC_CHANNEL_CLOSED`），不只是返回 false。
-                // 抛的那条会跳过下面所有复位 ⇒ `running` 永久留成 true ⇒ 面板之后每次
-                // `POST /run` 都 409（「面板锁死」换了个地方复现）。统一翻译成 500。
-                throw new HttpError(500, `runner 通道已断（${e.message}），稍后再试`);
+            else if (e.kind === 'send-ipc') {
+                const proc = currentProc;
+                if (!proc)
+                    failLaunch(state.lastError ?? 'runner 起不来');
+                let sent = false;
+                try {
+                    sent = proc.send(e.message);
+                }
+                catch (e2) {
+                    // 通道刚断开时 `send()` **会抛**（`ERR_IPC_CHANNEL_CLOSED`），不只是返回 false。
+                    // 不翻译成失败事件的话机器相位会停在 launching ⇒ 面板之后每次 POST /run 都 409。
+                    failLaunch(`runner 通道已断（${e2.message}），稍后再试`);
+                }
+                if (!sent)
+                    failLaunch('runner 通道已断（进程可能刚退出），稍后再试');
             }
-            if (!sent)
-                throw new HttpError(500, 'runner 通道已断（进程可能刚退出），稍后再试');
-            emit({
-                kind: 'run-start',
-                prompt: req.prompt,
-                workdir,
-                toolSources: toolSources ?? null,
-                multiTurn,
-            });
-            return { accepted: true, restarted };
-        }
-        catch (e) {
-            // 任何一步失败都必须把两处状态复位：留下的 `running = true` 会让面板**永久** 409，
-            // 而留下的 `pendingNote` 会挂到下一轮 run 的 traceId 上（张冠李戴）。
-            running = false;
-            pendingNote = null;
-            throw e;
-        }
-        finally {
-            launching = false;
         }
+        void dispatch({ type: 'run-launched' });
+        return { accepted: true, restarted };
     };
     /**
      * 中止在飞 run（§6 待定 5 的「显式 kill 按钮」）。
      *
-     * 两条路，按顺序：
+     * 两条路，按顺序（状态迁移在机器里，这里只管计时器与等待）：
      * 1. **优雅**：给 runner 发 `run-abort`，它 abort 掉 `app.run` 的 `signal` ⇒ 引擎在回合边界
      *    以 `stopReason='aborted'` **正常返回** ⇒ **trace 照常落盘**（框架契约：不抛异常）。
      * 2. **兜底**：`signal` 是**协作式**的 —— 工具若不读 `ToolRunContext.signal`（本仓已知
      *    「MCP 在途中止 ⇒ Promise 永不 settle」那类），abort 就没人理。那就重启进程收编它
-     *    （代价是这次 run 的 trace 丢掉，但**面板不至于永久锁死**：`running` 一直是 true 的话，
-     *    之后每次 `POST /run` 都 409 —— 那才是真正没法用的状态）。
+     *    （代价是这次 run 的 trace 丢掉，但**面板不至于永久锁死**）。
      */
     const abortRun = async () => {
-        if (!running || !child)
-            throw new HttpError(409, '当前没有在飞的 run');
-        // 幂等：中止已发出、升级计时器还挂着时再点一次，**不该再挂一个计时器** ——
-        // 两个计时器到点会触发两次 restart，第二次打在一个刚重启好的 runner 上
-        // （那会把用户刚跑起来的 run 又掐掉一次）。
-        if (abortTimer !== null)
+        const r = update(state, { type: 'ui-abort-requested' });
+        state = r.state;
+        throwIfRejected(r.effects);
+        const arm = r.effects.find((e) => e.kind === 'arm-abort-timer');
+        if (arm?.kind !== 'arm-abort-timer') {
+            // 幂等：中止已发出（机器相位已是 aborting），不挂第二个计时器
             return { accepted: true, escalated: false };
-        const proc = child.child;
-        const sent = proc.send({ type: 'run-abort' });
-        if (!sent)
-            throw new HttpError(500, 'runner 通道已断（进程可能刚退出），稍后再试');
+        }
+        const sendEff = r.effects.find((e) => e.kind === 'send-ipc');
+        const proc = currentProc;
+        let sent = false;
+        try {
+            sent = proc && sendEff && sendEff.kind === 'send-ipc' ? proc.send(sendEff.message) : false;
+        }
+        catch (e) {
+            // 相位退回 running（中止没生效，run 还在飞）；错误原样上抛（HTTP 层映射 500）
+            void dispatch({ type: 'abort-send-failed', message: e.message });
+            throw e;
+        }
+        if (!sent) {
+            const message = 'runner 通道已断（进程可能刚退出），稍后再试';
+            void dispatch({ type: 'abort-send-failed', message });
+            throw new HttpError(500, message);
+        }
         const escalated = await new Promise((resolve) => {
             let tick = null;
-            abortTimer = setTimeout(() => {
-                abortTimer = null;
+            let deadline = null;
+            let done = false;
+            const finish = (value) => {
+                if (done)
+                    return;
+                done = true;
                 if (tick !== null)
                     clearInterval(tick);
-                // 还在跑 ⇒ signal 没人理。这时**必须**升级，否则面板锁死。
-                // 也记进 lastError：被掐掉的 run 是个「发生过的事」，不该只闪一下就没了
-                // （面板的通知会被下一次操作覆盖，刷新页面就再也看不到）。
-                lastError = '中止超时（工具不响应 signal）⇒ 已重启 runner 兜底：这次 run 的 trace 丢了';
-                void restart('中止超时：run 不响应 signal（工具可能不可取消）', child?.toolSources ?? null);
-                resolve(true);
-            }, ABORT_GRACE_MS);
-            // 正常收尾（run-done / run-error）会把计时器清掉并让这里 resolve(false)
+                if (deadline !== null)
+                    clearTimeout(deadline);
+                clearAbortTimer();
+                resolve(value);
+            };
+            abortTimer = setTimeout(() => {
+                abortTimer = null;
+                // 还在跑 ⇒ signal 没人理 ⇒ 必须升级（机器：lastError + restart 效果），否则面板锁死
+                void dispatch({ type: 'abort-grace-expired' });
+                finish(true);
+            }, arm.ms);
+            /**
+             * 轮询的**自己的**上限。没有它就有一种挂死：run 正常收尾时 run-done 会先
+             * disarm（清掉上面的升级计时器）再把相位落到 idle，而轮询是 50 ms 一拍 ——
+             * 若这 50 ms 内又起了一个新 run，轮询永远等不到 idle，而升级计时器已经没了
+             * ⇒ 这个 Promise **无人 resolve**，`POST /run/abort` 挂住不还。
+             * 上限比升级刻度略长：正常升级总是先到。
+             */
+            deadline = setTimeout(() => finish(false), arm.ms + 500);
+            // 正常收尾（run-done / run-error）会把相位落下来，轮询据此 resolve(false)
             tick = setInterval(() => {
-                if (!running) {
-                    if (tick !== null)
-                        clearInterval(tick);
-                    clearAbortTimer();
-                    resolve(false);
-                }
+                if (!runGateFlags(state).running)
+                    finish(false);
             }, 50);
             tick.unref();
         });
@@ -811,12 +555,46 @@ export function devServer(argv = []) {
      * 而新的 run 用新 id ⇒ 模型看到的上下文是空的。
      */
     const clearSession = async () => {
-        if (running) {
-            throw new HttpError(409, '有 run 在飞时不能清空对话（它会写回当前会话）。先中止或等它结束');
+        const r = update(state, { type: 'ui-clear-session' });
+        state = r.state;
+        throwIfRejected(r.effects);
+        for (const e of r.effects) {
+            if (e.kind === 'persist-session-id')
+                writeSessionId(e.id);
+        }
+        return { sessionId: state.sessionId };
+    };
+    /**
+     * 原生文件夹选择框（面板工作目录控件的「用系统选择器…」按钮）。
+     *
+     * **串行化**在机器里（picking 相位）：同时只许一个在飞，第二个请求 409。
+     * 没有面板侧超时（用户可能慢慢选）；进程退出时由 `killActivePickers()` 收编。
+     */
+    const pickFolder = async () => {
+        const r = update(state, { type: 'ui-pick-requested' });
+        state = r.state;
+        throwIfRejected(r.effects);
+        try {
+            const picked = await pickFolderNative();
+            void dispatch({ type: 'ui-pick-resolved' });
+            return picked;
+        }
+        catch (e) {
+            // 平台不支持 / 命令缺失（native-pick 的报错已指向降级路径「浏览…」）⇒ 501
+            const r2 = update(state, { type: 'ui-pick-failed', message: e.message });
+            state = r2.state;
+            throwIfRejected(r2.effects);
+            throw e; // 不可达（ui-pick-failed 必带 reject），只喂类型
         }
-        sessionId = nextSessionId(sessionId);
-        writeSessionId(sessionId);
-        return { sessionId };
+    };
+    /**
+     * 客户端断开（刷新 / 关标签页）时收掉在飞的选择框（G2 的出口）：机器给出
+     * kill-pickers 效果 ⇒ kill 子进程 ⇒ pickFolderNative 那侧走「视同取消」
+     * （resolve null）⇒ ui-pick-resolved 把 picking 落下来。没有这条出口：
+     * 选择框挂在桌面上没人看、picking 永远不落、之后每次点「系统选择…」都 409。
+     */
+    const cancelPick = () => {
+        void dispatch({ type: 'ui-pick-cancelled' });
     };
     const readSession = async () => {
         // 面板**只读**会话文件：它记的是「我发了什么」，而模型看到的是「store 里有什么」，
@@ -833,7 +611,7 @@ export function devServer(argv = []) {
             const { readFile } = await import('node:fs/promises');
             const parsed = JSON.parse(await readFile(file, 'utf8'));
             // 读**当前** id（不是常量）：清空对话之后面板必须立刻显示空，而不是旧对话
-            const messages = parsed.sessions?.[sessionId];
+            const messages = parsed.sessions?.[state.sessionId];
             return { messages: Array.isArray(messages) ? messages : [] };
         }
         catch (e) {
@@ -842,60 +620,41 @@ export function devServer(argv = []) {
     };
     // ---------- 收尾 ----------
     /**
-     * 收尾：停 watch、收**整棵**子进程树、关面板。
-     *
-     * 返回 Promise 而不是 fire-and-forget：信号处理器要等它真的做完才 `exit` —— 理由见
-     * `shutdownAndExit`（这是个实测出来的坑，不是风格）。
-     */
-    const shutdown = async () => {
-        if (closing)
-            return;
-        closing = true;
-        stopWatch?.();
-        stopEnvWatch?.();
-        try {
-            await stopChild();
-        }
-        finally {
-            if (inspector)
-                await inspector.close();
-        }
-    };
-    let shuttingDown = false;
-    /**
-     * 收尾后退出（SIGINT / SIGTERM 共用同一条出口）。
+     * 收尾后退出（SIGINT / SIGTERM 共用同一条出口）。迁移规则在机器里
+     * （第一次 ⇒ closing + 收尾效果序列；第二次 ⇒ exit-now 立即硬退）。
      *
      * ## 为什么不能沿用「固定 50 ms 后 `process.exit(0)`」（实测，不是风格偏好）
      *
-     * `stopChild()` 给子进程的宽限期是 `KILL_GRACE_MS`（3 s）—— 它 SIGTERM 之后等 3 s
+     * `stopChildExec()` 给子进程的宽限期是 `KILL_GRACE_MS`（3 s）—— 它 SIGTERM 之后等 3 s
      * 才补 SIGKILL。而固定 50 ms 就 exit 会让父进程在这 3 s 之前消失：
      * - 那段宽限连同 **SIGKILL 兜底**一起没了（计时器随父进程消失）；
-     * - `process.on('exit')` 那条兜底此刻也是空操作 —— `stopChild` 第一行就把 `child`
-     *   置成了 null，而它的归属判定是 `child?.child === proc`。
+     * - `process.on('exit')` 那条兜底此刻也是空操作 —— 句柄早已被摘掉。
      * ⇒ 一个**不响应 SIGTERM** 的 runner（连同它自己 spawn 的 MCP 子进程）活成孤儿。
-     * SIGTERM 路径没有这个问题（它不主动退出、等事件循环自然空），两条路径口径必须一致。
      *
      * 上限仍然要有：面板若还有挂着的连接，收尾可能卡住 ⇒ `SHUTDOWN_DEADLINE_MS` 到点硬退；
-     * 再按一次 Ctrl+C 立即硬退（不让用户面对一个按不动的 Ctrl+C）。
+     * 再按一次 Ctrl+C 立即硬退（机器的 exit-now）。
      */
     const shutdownAndExit = (code) => {
-        if (shuttingDown) {
+        const r = update(state, { type: 'shutdown' });
+        state = r.state;
+        if (r.effects.some((e) => e.kind === 'exit-now')) {
             process.exit(code);
         }
-        shuttingDown = true;
         const deadline = setTimeout(() => process.exit(code), SHUTDOWN_DEADLINE_MS);
         deadline.unref();
-        void shutdown().finally(() => {
+        void runEffects(r.effects).finally(() => {
             clearTimeout(deadline);
             process.exit(code);
         });
     };
     process.on('SIGINT', () => shutdownAndExit(0));
     process.on('SIGTERM', () => shutdownAndExit(0));
-    // 最后一道兜底：任何路径走到进程退出都不该留下子进程树（含上面那条硬退路径）
+    // 最后一道兜底：任何路径走到进程退出都不该留下子进程树（含上面那条硬退路径）——
+    // 含还挂着的原生文件夹选择框（同步 kill，与 killTree 同一条纪律）
     process.on('exit', () => {
-        if (child)
-            killTree(child.child, 'SIGKILL');
+        killActivePickers();
+        if (currentProc)
+            killTree(currentProc, 'SIGKILL');
     });
     // ---------- 启动 ----------
     /**
@@ -916,14 +675,15 @@ export function devServer(argv = []) {
                     session: readSession,
                     abort: abortRun,
                     clearSession,
+                    pickFolder,
+                    cancelPick,
                     /**
-                     * ① 实时右栏：runner 逐笔 POST 上来的增量记账事件**原样广播**给面板。
-                     *
-                     * 父进程在这一层**不做任何解释**（不折回、不缓存、不裁剪）：折回是面板的活
-                     * （它有 `panel-logic.applyTraceEvent` 与单测），而父进程插一手就多一处会漂的口径。
-                     * 这里只保证「按收到的顺序、同步转发」—— SSE 写入本身是有序的。
+                     * ① 实时右栏：runner 逐笔 POST 上来的增量记账事件**原样广播**给面板
+                     * （机器只有一条 emit 效果，刻意零解释 —— 折回是面板的活）。
                      */
-                    traceEvent: (e) => emit({ kind: 'trace-event', event: e }),
+                    traceEvent: (e) => {
+                        void dispatch({ type: 'trace-event', event: e });
+                    },
                 },
             });
             console.log(`Inspector: http://127.0.0.1:${inspector.port}/?t=${token}\n` +
@@ -938,23 +698,14 @@ export function devServer(argv = []) {
     };
     void (async () => {
         await startPanel();
-        try {
-            await spawnChild(null);
-        }
-        catch (e) {
-            lastError = e.message;
-            console.error(`[agentia] ${lastError}`);
-        }
+        // 拉起第一代 runner（boot ⇒ spawn-child 效果；失败归 boot-failed：终端 error +
+        // 唯一一帧 runner-error —— 见机器里那条迁移的注释）
+        await dispatch({ type: 'boot' });
         // 「文件变了 ⇒ 重启」的**唯一**出口：两处 watch 都走它，理由文案因此只有一种写法。
         const onFileChange = (abs) => {
-            const rel = relative(projectRoot, abs);
-            if (running) {
-                pendingRestart = `文件变更：${rel}`;
-                return;
-            }
-            void restart(`文件变更：${rel}`, child?.toolSources ?? null);
+            void dispatch({ type: 'file-changed', rel: relative(projectRoot, abs) });
         };
-        // 代码与文本资产都在 `src/` 下（`.md` 必须在允许清单里 —— 见 WATCH_EXT）
+        // 代码与文本资产都在 `src/` 下（`.md` 必须在允许清单里 —— 见 dev-watch.ts 的 WATCH_EXT）
         stopWatch = watchTree(join(projectRoot, 'src'), onFileChange);
         // `.env` / `.env.local` 在**项目根**、不在 `src/` 下 ⇒ 单独盯。
         // 少了这一句，「改 .env 会重启」就是一句没人执行的承诺（真跑抓出来的）。