@jesonliu/lark-claudecode-bridge 1.3.7 → 1.4.0

package/dist/executor/claude-executor.js

@@ -1,17 +1,26 @@
-// Claude 执行器：封装 Agent SDK 的 query()，把流消息转成进度事件并收集产出
+// Claude 执行器：封装 Agent SDK 的 query()，把流消息转成进度事件并收集产出。
 // 注意：不覆盖/清理任何 ANTHROPIC_* 环境变量，凭证与代理配置透传 process.env
+//
+// 生命周期方案 A2——常驻进程池：
+// - 进程按 affinityKey（appId:chatId:userId）亲和：同通道消息继续写同一 CLI 子进程的
+//   stdin（streaming input 天然多轮），~30s 冷启动税从「每消息一次」摊薄为「每会话一次」；
+// - 复用三前提：进程活着 + 配置指纹一致（人设/模型/plan/env/MCP/插件/档案 settings/cwd，
+//   任一变化即回收重建——保住「每任务现读热生效」卖点）+ 会话指针一致（/new /resume /ws use
+//   换了续接目标，旧进程上下文不再适用）；
+// - 每轮软收尾：现有 finalize（发卡/归档/拉 MCP 状态）在每轮 result 后照常执行，但
+//   不退出消息循环、不杀进程——「收尾」与「退出」分离是本次重构的核心动作；
+// - 崩溃自愈：进程死亡（流结束/抛错）自动出池，下条消息冷启重建 = 退化为旧行为，不会更糟；
+// - 空闲回收：通道空闲超阈值杀进程释放内存（会话无损——指针与 transcript 均落盘，
+//   追问时冷启 + resume 无缝续上）；池上限按 app 统计，LRU 淘汰最久未用的空闲进程。
+// - ephemeral（无 affinityKey 或 resident:false）= spawn 一轮即回收的常驻进程，与旧行为等价。
+import { createHash } from 'node:crypto';
 import { query } from '@anthropic-ai/claude-agent-sdk';
 import { OutputCollector } from './output-collector.js';
-// SDK 选项只收 abortController（无 signal 项），把外部 signal 的中止转发给它
-function bridgeSignal(signal) {
-    const controller = new AbortController();
-    if (signal.aborted) {
-        controller.abort();
-        return controller;
-    }
-    signal.addEventListener('abort', () => controller.abort(), { once: true });
-    return controller;
-}
+/** 常驻进程默认空闲回收阈值：1 小时（方案 §3.2 建议 1h 起步做成配置） */
+const DEFAULT_RESIDENT_IDLE_MS = 60 * 60 * 1000;
+/** 等待后台任务期间的静默超时：超时仍无任何事件（CLI 异常/卡死）按已有信息收尾，防任务永久挂起。
+ *  正常路径无须走到——后台任务完成会唤醒主循环产生新事件，最终由 result/idle 信号收尾 */
+const BG_WAIT_SILENCE_TIMEOUT_MS = 15 * 60 * 1000;
 function summarizeToolInput(input) {
     if (typeof input.command === 'string')
         return input.command;
@@ -34,315 +43,731 @@ function firstErrorLine(content) {
     const line = text.split('\n').map((l) => l.trim()).find((l) => l.length > 0);
     return line ? line.slice(0, 80) : undefined;
 }
-/** 等待后台任务期间的静默超时：超时仍无任何事件（CLI 异常/卡死）按已有信息收尾，防任务永久挂起。
- *  正常路径无须走到——后台任务完成会唤醒主循环产生新事件，最终由 result/idle 信号收尾 */
-const BG_WAIT_SILENCE_TIMEOUT_MS = 15 * 60 * 1000;
-export async function runTask(prompt, opts, cb) {
-    // collector 按 cwd 过滤：只收集工作区内文件（plan mode 的计划文件写在 ~/.claude/plans/
-    // 等工作区外路径，不属于「本次修改/新增的文件」，不应进入收尾清单与文件追踪）
-    const collector = new OutputCollector(opts.cwd);
-    // Streaming Input（官方推荐姿势）：prompt 经 AsyncGenerator 送入，yield 一条用户消息后挂起不结束——
-    // stdin 在整个会话期间保持打开。字符串 prompt 的单轮模式在收到第一条 result 后即关 stdin
-    //（SDK isSingleUserTurn 行为，agent-sdk#384），plan mode 下 ExitPlanMode/AskUserQuestion 这类
-    // 轮次边界的权限请求落在 result 之后，CLI 侧 inputClosed 后全部报 "Stream closed" 中断审批流
-    async function* inputStream() {
-        yield { type: 'user', message: { role: 'user', content: prompt }, parent_tool_use_id: null };
-        await new Promise(() => { }); // 永不自然结束：由消费端收到最终 result 后 break 收尾
+/** MCP server 配置的可序列化投影（指纹用）：只取影响子进程行为的配置字段。
+ *  sdk 实例型 server（进程内 lcb-notify）不可序列化，按名字记 marker——wiring 侧
+ *  每任务新建实例但 delegate 同槽（见 notify-server.ts createNotifySenderSlot），
+ *  名字稳定即语义稳定。env/headers 只参与哈希不落日志，无泄漏面 */
+function serializeMcpServers(servers) {
+    if (!servers)
+        return null;
+    const out = {};
+    for (const [name, raw] of Object.entries(servers)) {
+        const c = raw;
+        out[name] = c.type === 'sdk'
+            ? { type: 'sdk', name: typeof c.name === 'string' ? c.name : name }
+            : {
+                type: c.type,
+                command: c.command,
+                args: c.args,
+                url: c.url,
+                env: c.env,
+                headers: c.headers ? Object.keys(c.headers) : undefined,
+            };
     }
-    let resultErrorText = '';
-    // 启动耗时分解（先诊断承诺）：spawn→init≈CLI 冷启动（配置/插件/MCP 拉起 + resume 回放），
-    // init→首输出≈模型首响。t0 取 query 创建时刻（子进程 spawn 随之发生）
-    const t0 = Date.now();
-    const q = query({
-        prompt: inputStream(),
-        options: {
-            cwd: opts.cwd,
-            settingSources: ['user', 'project'],
-            permissionMode: opts.permissionMode ?? 'default',
-            // 流式增量事件（stream_event）：仅消费首个 text delta 提前点亮「正在执行」（首个完整块
-            // 生成前 otherwise 状态行停留在启动阶段，视觉上拉长「启动中」）；不渲染不落盘，
-            // 完整块仍走 assistant 分支（渲染/落盘口径不变）
-            includePartialMessages: true,
-            // 转发子代理 text 块（默认只转发 tool_use/tool_result 心跳）——配合 parent_tool_use_id
-            // 区分主/子代理输出，飞书进度卡能看到子代理在做什么
-            forwardSubagentText: true,
-            // 分身技能白名单（RunTaskOptions.allowedSkills → Options.skills）：未列出技能对模型
-            // 不可见且被 Skill 工具拒绝；缺省不传 = CLI 默认全量（主机器人行为不变）
-            ...(opts.allowedSkills?.length ? { skills: opts.allowedSkills } : {}),
-            ...(opts.resumeSessionId ? { resume: opts.resumeSessionId } : {}),
-            ...(opts.canUseTool
-                ? {
-                    canUseTool: async (toolName, input, ctx) => {
-                        const decision = await opts.canUseTool(toolName, input, { suggestions: ctx?.suggestions });
-                        // 计划批准即授权写操作：对齐 Claude Code CLI「plan 批准 → accept edits on」语义，
-                        // 后续 Write/Edit 不再逐次弹确认卡（SDK Query.setPermissionMode，官方 permissions 文档姿势）。
-                        // 分身（planApproveEscalates=false）不升级：acceptEdits 会绕过 canUseTool，
-                        // 宿主安全闸（R1 红区/R2 写边界）随之失效——安全优先于确认摩擦
-                        if (decision.behavior === 'allow' && toolName === 'ExitPlanMode'
-                            && opts.planApproveEscalates !== false) {
-                            await q.setPermissionMode('acceptEdits').catch((e) => {
-                                console.warn('[executor] setPermissionMode(acceptEdits) 失败（继续按批准前模式执行）:', e instanceof Error ? e.message : e);
-                            });
-                        }
-                        return decision;
-                    },
-                }
-                : {}),
-            ...(opts.signal ? { abortController: bridgeSignal(opts.signal) } : {}),
-            ...(opts.env ? { env: opts.env } : {}),
-            ...(opts.model ? { model: opts.model } : {}),
-            ...(opts.mcpServers ? { mcpServers: opts.mcpServers } : {}),
-            ...(opts.plugins ? { plugins: opts.plugins.map((p) => ({ type: 'local', path: p.path })) } : {}),
-            // extraArgs 合并口：调用方传入（--settings 档案认证）+ 人格补充（--append-system-prompt，
-            // CLI 2.1.x 只认命令行参数，SDK 同名 option 被静默丢弃——见 RunTaskOptions.appendSystemPrompt 注释）
-            ...((opts.extraArgs && Object.keys(opts.extraArgs).length) || opts.appendSystemPrompt
-                ? {
-                    extraArgs: {
-                        ...(opts.extraArgs ?? {}),
-                        ...(opts.appendSystemPrompt ? { 'append-system-prompt': opts.appendSystemPrompt } : {}),
-                    },
-                }
-                : {}),
-        },
-    });
-    let finalText = '';
-    let sessionId = opts.resumeSessionId ?? '';
-    let turns = 0;
-    // 最后一次 result 的主循环用量：input+cache 三项之和 ≈ 当前上下文规模（超长提醒判定口径）。
-    // streaming 模式下每个 result 携带最近 turn 的用量，取最新值即可（不累加）
-    let usage;
-    // 后台任务在途集合（background_tasks_changed 为 level 信号，整组替换；ambient 杂务任务不计）。
-    // 主 turn result 到达时集合非空 → 不收尾挂起等待：进程一退后台子代理就被连带杀掉，
-    // 永远等不到完成通知——后台任务完成会唤醒 CLI 主循环自动续跑，新事件继续流出直到真正收尾
-    const bgTasks = new Map();
-    // 主 turn 终态已到但仍在等后台任务（true 期间静默超时看门狗生效）
-    let waitingBg = false;
-    let lastEventAt = Date.now();
-    // 启动耗时锚点（见 t0 注释）：initAt=system/init 到达；firstOutAt=首个输出信号
-    // （首个流式 text delta 或首个完整 assistant 块，先到先记）
-    let initAt = 0;
-    let firstOutAt = 0;
-    let sawFirstDelta = false;
-    // init 消息提取的会话清单（每 query 一次）；数组字段全部 ?? [] 兜底——SDK 升级字段改名时清单为空但不崩
-    let inventory;
-    const toolNames = new Map(); // tool_use_id → 工具名（tool_result 块本身不带 name）
-    opts.onQuery?.(q);
-    // 等待后台任务期间的静默看门狗：pending 期间长时间无任何事件则按已有信息收尾。
-    // 经 q.return() 结束 for await（与收到 result 主动 return 走同一条清理路径）
-    const silenceWatch = setInterval(() => {
-        if (waitingBg && Date.now() - lastEventAt > BG_WAIT_SILENCE_TIMEOUT_MS) {
-            console.warn(`[executor] 等待后台任务静默超 ${Math.round(BG_WAIT_SILENCE_TIMEOUT_MS / 60000)} 分钟无事件，按已有结果收尾（后台任务: ${[...bgTasks.values()].map((t) => t.description).join(' / ')}）`);
-            void q.return(undefined).catch(() => { });
+    return out;
+}
+/** 配置指纹（方案 §3.4）：全部 spawn 时输入的稳定哈希。这些输入在 executeTask 里逐项
+ *  现读（人设/模型/plan/env/配置页 MCP/插件/档案 settings/cwd），常驻进程记录
+ *  spawn 时指纹，下条消息指纹不符 → 回收重建——与「每任务现读热生效」语义完全一致，
+ *  代价只是一次冷启动（退化一次现状体验）。
+ *  不入指纹的两类：resumeSessionId——续接目标由复用条件的「指针一致性」单独校验
+ *  （进程首轮 spawn 必然无 resume、次轮指针即自身会话 id，若入指纹则永远无法复用）；
+ *  canUseTool——gate 为通道级对象，decide 时经 getter 现读配置（热），闭包捕获的
+ *  wsName 与 cwd 同源（已入指纹） */
+/** 稳定序列化：对象键深度排序（undefined 值剔除）——同内容不同插入序的对象
+ *  （buildTaskEnv 展开整个 process.env、热重载重建的 env 对象等）不再产生指纹漂移。
+ *  漂移 = 无谓的冷启动重建（用户体感「第二条消息还是慢」），实测踩过：仅键序不同
+ *  的 env 曾触发一次性「配置指纹变化」重建 */
+function stableStringify(v) {
+    if (Array.isArray(v))
+        return v.map(stableStringify);
+    if (v && typeof v === 'object') {
+        const o = {};
+        for (const k of Object.keys(v).sort()) {
+            const val = v[k];
+            if (val !== undefined)
+                o[k] = stableStringify(val);
         }
-    }, 30_000);
-    silenceWatch.unref?.();
-    // 收尾（含 MCP 真实连接状态拉取）：result 即收尾与 idle 权威收尾两条路径共用
-    const finalizeWithMcpPoll = async () => {
-        // 收尾前拉一次 MCP 真实连接状态（init 快照必为 pending，这是空闲期 /mcp 的数据源）；
-        // try/catch 同时兜住同步异常（旧 mock/异常环境下方法缺失）与异步拒绝，绝不阻断收尾
-        try {
-            const statuses = await q.mcpServerStatus();
-            cb.onMcpStatus?.(statuses);
+        return o;
+    }
+    return v;
+}
+/** 指纹分量（名称 → 序列化输入）：整体哈希用于复用判定；分量哈希存 spawn 快照，
+ *  漂移时逐项比对定位「是哪个输入变了」（env 只报键名不报值——env 常含凭证） */
+function fingerprintParts(opts) {
+    return [
+        ['cwd', opts.cwd],
+        ['env', opts.env ?? null],
+        ['appendSystemPrompt', opts.appendSystemPrompt ?? null],
+        ['model', opts.model ?? null],
+        ['permissionMode', opts.permissionMode ?? null],
+        ['extraArgs', opts.extraArgs ?? null],
+        ['allowedSkills', opts.allowedSkills ?? null],
+        ['planApproveEscalates', opts.planApproveEscalates ?? null],
+        ['plugins', opts.plugins?.map((p) => p.path) ?? null],
+        ['mcpServers', serializeMcpServers(opts.mcpServers)],
+    ];
+}
+function hashPart(v) {
+    return createHash('sha256').update(JSON.stringify(stableStringify(v))).digest('hex');
+}
+function fingerprintOf(opts) {
+    return hashPart(fingerprintParts(opts).map(([, v]) => v));
+}
+/** 分量级漂移归因：返回人类可读的变化清单（env 按键名差集，其余按分量名）。
+ *  只在已判定指纹不符后调用（诊断输出，不参与判定路径） */
+function describePartDrift(spawn, now) {
+    const out = [];
+    const nowMap = new Map(now);
+    for (const [name, spawnV] of spawn) {
+        const nowV = nowMap.get(name);
+        if (JSON.stringify(stableStringify(spawnV)) === JSON.stringify(stableStringify(nowV)))
+            continue;
+        if (name === 'env' && spawnV && nowV && typeof spawnV === 'object' && typeof nowV === 'object') {
+            const s = spawnV;
+            const n = nowV;
+            const added = Object.keys(n).filter((k) => !(k in s));
+            const removed = Object.keys(s).filter((k) => !(k in n));
+            const changed = Object.keys(s).filter((k) => k in n && stableStringify(s[k]) !== stableStringify(n[k]));
+            const bits = [
+                added.length ? `新增键 ${added.join(',')}` : '',
+                removed.length ? `消失键 ${removed.join(',')}` : '',
+                changed.length ? `值变化 ${changed.join(',')}` : '',
+            ].filter(Boolean);
+            out.push(`env（${bits.join('；') || '结构变化'}）`);
         }
-        catch { /* 拉取失败：保留 init 快照 */ }
-        return finalize();
-    };
-    try {
-        for await (const message of q) {
-            lastEventAt = Date.now();
-            switch (message.type) {
-                case 'system': {
-                    if (message.subtype === 'init') {
-                        initAt = Date.now();
-                        // init 即携带 session_id：全新会话在首轮 turn 结束前被 /stop 中止时不会有 result 消息，
-                        // 不在此捕获则 sessionId 恒为空串 → catch 挂不上 err.sessionId → 归档 no-op，
-                        // 会话指针停留 null，用户随后「继续」会开全新会话丢失上下文（resume 场景两值等价）
-                        if (typeof message.session_id === 'string' && message.session_id)
-                            sessionId = message.session_id;
-                        inventory = {
-                            model: message.model,
-                            claudeCodeVersion: message.claude_code_version,
-                            // 顶层已注册工具清单（dynamic tool loading 下核心工具在顶层、其余经 ToolSearch 按需加载，
-                            // ToolSearch 索引不到顶层工具）：/status 展示与「工具不存在」误判诊断的数据源
-                            tools: message.tools ?? [],
-                            skills: message.skills ?? [],
-                            slashCommands: message.slash_commands ?? [],
-                            plugins: (message.plugins ?? []).map((p) => ({ name: p.name, path: p.path, version: p.version })),
-                            mcpServers: message.mcp_servers ?? [],
-                            agents: message.agents ?? [],
-                        };
-                        cb.onInit?.(inventory);
+        else {
+            out.push(name);
+        }
+    }
+    return out;
+}
+/** 推送式异步队列：多轮 prompt 的 streaming input 背板。
+ *  SDK 按需拉取（generator 挂起等待 push），push 侧无须关心 CLI 是否就绪 */
+class AsyncQueue {
+    items = [];
+    waiters = [];
+    push(v) {
+        const w = this.waiters.shift();
+        if (w)
+            w(v);
+        else
+            this.items.push(v);
+    }
+    async *stream() {
+        while (true) {
+            if (this.items.length > 0)
+                yield this.items.shift();
+            else
+                yield await new Promise((r) => this.waiters.push(r));
+        }
+    }
+}
+/**
+ * 会话进程：一个 CLI 子进程（query）+ 常驻消息循环。
+ * 生命周期：spawn → N 轮 sendTurn → kill/die。ephemeral 用法 = spawn 后跑一轮即 kill，
+ * 与旧版「每消息一个进程」等价（统一一条循环逻辑，不分叉）。
+ */
+class SessionProcess {
+    q;
+    key;
+    scope;
+    resident;
+    input = new AsyncQueue();
+    abortController = new AbortController();
+    spawnT0 = Date.now();
+    /** spawn 时的全部输入指纹（复用校验用） */
+    fingerprint;
+    /** spawn 时的指纹分量快照（漂移归因日志用；env 值不出现在任何日志） */
+    spawnParts;
+    /** 进程的会话 id（init/result 刷新）：复用校验的「指针一致性」基准 */
+    sessionId = '';
+    /** spawn 时 init 提取的清单（复用轮回放给 onInit；指纹保证清单未变） */
+    inventory;
+    /** 进程当前权限模式：spawn 初值 + ExitPlanMode 批准升级跟踪；复用轮开始前复位到本轮期望
+     *  （否则上一轮 plan 批准后进程停留 acceptEdits，本轮 /plan 语义被吃掉） */
+    currentMode;
+    procInitAt = 0;
+    initDone = false;
+    currentTurn;
+    busy = false;
+    dead = false;
+    /** 空闲回收判定的活跃基准（每轮收尾刷新） */
+    lastUsedAt = Date.now();
+    idleMs = DEFAULT_RESIDENT_IDLE_MS;
+    turnSignalCleanup;
+    /** kill 已执行标记（与 dead 分离：ephemeral 轮内收尾先置 dead，kill 仍须真正 q.return()
+     *  结束流迭代——否则真实 SDK 的子进程在无后续消息时永远挂着等 stdin） */
+    killed = false;
+    constructor(key, opts, resident) {
+        this.key = key;
+        this.scope = opts.residentScope;
+        this.resident = resident;
+        this.fingerprint = fingerprintOf(opts);
+        this.spawnParts = fingerprintParts(opts);
+        this.currentMode = opts.permissionMode ?? 'default';
+        const proc = this;
+        this.q = query({
+            // Streaming Input（官方推荐姿势）：prompt 经 AsyncGenerator 送入，push 一条用户消息后
+            // 挂起不结束——stdin 在整个进程存活期间保持打开（多轮 = 继续push）。
+            // 字符串 prompt 的单轮模式在收到第一条 result 后即关 stdin（SDK isSingleUserTurn
+            // 行为，agent-sdk#384），plan mode 下 ExitPlanMode/AskUserQuestion 这类轮次边界的
+            // 权限请求落在 result 之后，CLI 侧 inputClosed 后全部报 "Stream closed" 中断审批流
+            prompt: this.input.stream(),
+            options: {
+                cwd: opts.cwd,
+                settingSources: ['user', 'project'],
+                permissionMode: opts.permissionMode ?? 'default',
+                // 流式增量事件（stream_event）：仅消费首个 text delta 提前点亮「正在执行」（首个完整块
+                // 生成前 otherwise 状态行停留在启动阶段，视觉上拉长「启动中」）；不渲染不落盘，
+                // 完整块仍走 assistant 分支（渲染/落盘口径不变）
+                includePartialMessages: true,
+                // 转发子代理 text 块（默认只转发 tool_use/tool_result 心跳）——配合 parent_tool_use_id
+                // 区分主/子代理输出，飞书进度卡能看到子代理在做什么
+                forwardSubagentText: true,
+                // 分身技能白名单（RunTaskOptions.allowedSkills → Options.skills）：未列出技能对模型
+                // 不可见且被 Skill 工具拒绝；缺省不传 = CLI 默认全量（主机器人行为不变）
+                ...(opts.allowedSkills?.length ? { skills: opts.allowedSkills } : {}),
+                ...(opts.resumeSessionId ? { resume: opts.resumeSessionId } : {}),
+                ...(opts.canUseTool
+                    ? {
+                        canUseTool: async (toolName, input, ctx) => {
+                            const decision = await opts.canUseTool(toolName, input, { suggestions: ctx?.suggestions });
+                            // 计划批准即授权写操作：对齐 Claude Code CLI「plan 批准 → accept edits on」语义，
+                            // 后续 Write/Edit 不再逐次弹确认卡（SDK Query.setPermissionMode，官方 permissions 文档姿势）。
+                            // 分身（planApproveEscalates=false）不升级：acceptEdits 会绕过 canUseTool，
+                            // 宿主安全闸（R1 红区/R2 写边界）随之失效——安全优先于确认摩擦。
+                            // 模式跟踪：常驻进程跨轮存续，复用轮开始前据此复位（sendTurn）
+                            if (decision.behavior === 'allow' && toolName === 'ExitPlanMode'
+                                && opts.planApproveEscalates !== false) {
+                                await proc.q.setPermissionMode('acceptEdits').then(() => { proc.currentMode = 'acceptEdits'; }).catch((e) => {
+                                    console.warn('[executor] setPermissionMode(acceptEdits) 失败（继续按批准前模式执行）:', e instanceof Error ? e.message : e);
+                                });
+                            }
+                            return decision;
+                        },
                     }
-                    else if (message.subtype === 'status') {
-                        // CLI 状态心跳（requesting=等模型响应 / compacting=上下文压缩 / null=空闲）：刷新进度卡
-                        // 状态行——includePartialMessages=false 下长 API 轮次没有任何其他事件，避免「只有计时在走」的黑盒感
-                        await cb.onProgress({
-                            kind: 'status',
-                            content: message.status === 'requesting' ? '🌐 等待模型响应…'
-                                : message.status === 'compacting' ? '🗜️ 上下文压缩中…'
-                                    : '🔄 运行中',
-                        });
+                    : {}),
+                abortController: this.abortController,
+                ...(opts.env ? { env: opts.env } : {}),
+                ...(opts.model ? { model: opts.model } : {}),
+                ...(opts.mcpServers ? { mcpServers: opts.mcpServers } : {}),
+                ...(opts.plugins ? { plugins: opts.plugins.map((p) => ({ type: 'local', path: p.path })) } : {}),
+                // extraArgs 合并口：调用方传入（--settings 档案认证）+ 人格补充（--append-system-prompt，
+                // CLI 2.1.x 只认命令行参数，SDK 同名 option 被静默丢弃——见 RunTaskOptions.appendSystemPrompt 注释）
+                ...((opts.extraArgs && Object.keys(opts.extraArgs).length) || opts.appendSystemPrompt
+                    ? {
+                        extraArgs: {
+                            ...(opts.extraArgs ?? {}),
+                            ...(opts.appendSystemPrompt ? { 'append-system-prompt': opts.appendSystemPrompt } : {}),
+                        },
                     }
-                    else if (message.subtype === 'background_tasks_changed') {
-                        // 后台任务在途清单（level 信号）：整组替换语义。ambient=true 的杂务任务
-                        // （live-update watcher 等）不算用户可见工作，不计数避免状态行虚高
-                        bgTasks.clear();
-                        for (const t of message.tasks) {
-                            if (!t.ambient)
-                                bgTasks.set(t.task_id, { taskType: t.task_type, description: t.description });
+                    : {}),
+            },
+        });
+    }
+    static spawn(key, opts, resident) {
+        const proc = new SessionProcess(key, opts, resident);
+        void proc.runLoop();
+        return proc;
+    }
+    get isBusy() { return this.busy; }
+    /** 常驻消息循环：进程存活期间常驻，事件按 currentTurn 分发；轮结束只 settle 轮次，
+     *  不退出循环（ephemeral 进程在首轮收尾后 break，对齐旧版「result 即结束」） */
+    async runLoop() {
+        try {
+            for await (const message of this.q) {
+                if (this.dead)
+                    break; // kill 已发起：不再消费
+                const turn = this.currentTurn;
+                if (!turn)
+                    continue; // 轮外杂事件（上轮尾巴的 idle 心跳等）：静默丢弃
+                turn.lastEventAt = Date.now();
+                switch (message.type) {
+                    case 'system': {
+                        if (message.subtype === 'init') {
+                            this.procInitAt = Date.now();
+                            this.initDone = true;
+                            turn.initAt = Date.now();
+                            // init 即携带 session_id：全新会话在首轮 turn 结束前被 /stop 中止时不会有 result 消息，
+                            // 不在此捕获则 sessionId 恒为空串 → catch 挂不上 err.sessionId → 归档 no-op，
+                            // 会话指针停留 null，用户随后「继续」会开全新会话丢失上下文（resume 场景两值等价）
+                            if (typeof message.session_id === 'string' && message.session_id) {
+                                this.sessionId = message.session_id;
+                                turn.sessionId = message.session_id;
+                            }
+                            this.inventory = {
+                                model: message.model,
+                                claudeCodeVersion: message.claude_code_version,
+                                // 顶层已注册工具清单（dynamic tool loading 下核心工具在顶层、其余经 ToolSearch 按需加载，
+                                // ToolSearch 索引不到顶层工具）：/status 展示与「工具不存在」误判诊断的数据源
+                                tools: message.tools ?? [],
+                                skills: message.skills ?? [],
+                                slashCommands: message.slash_commands ?? [],
+                                plugins: (message.plugins ?? []).map((p) => ({ name: p.name, path: p.path, version: p.version })),
+                                mcpServers: message.mcp_servers ?? [],
+                                agents: message.agents ?? [],
+                            };
+                            turn.cb.onInit?.(this.inventory);
                         }
-                        if (waitingBg && bgTasks.size > 0) {
-                            await cb.onProgress({ kind: 'status', content: `⏳ 等待 ${bgTasks.size} 个后台任务完成…` });
+                        else if (message.subtype === 'status') {
+                            // CLI 状态心跳（requesting=等模型响应 / compacting=上下文压缩 / null=空闲）：刷新进度卡
+                            // 状态行——includePartialMessages=false 下长 API 轮次没有任何其他事件，避免「只有计时在走」的黑盒感
+                            await turn.cb.onProgress({
+                                kind: 'status',
+                                content: message.status === 'requesting' ? '🌐 等待模型响应…'
+                                    : message.status === 'compacting' ? '🗜️ 上下文压缩中…'
+                                        : '🔄 运行中',
+                            });
                         }
-                    }
-                    else if (message.subtype === 'session_state_changed' && message.state === 'idle') {
-                        // 权威 turn-over 信号：idle 在 heldBackResult flush 且后台任务续跑循环退出后触发。
-                        // 主 turn result 已到 + 后台任务全部结束 → 真正收尾（后台任务若再唤醒主循环，
-                        // 会先收到新的 assistant/result 事件并覆盖 finalText，idle 仍在最后）
-                        if (waitingBg && bgTasks.size === 0) {
-                            return await finalizeWithMcpPoll();
+                        else if (message.subtype === 'background_tasks_changed') {
+                            // 后台任务在途清单（level 信号）：整组替换语义。ambient=true 的杂务任务
+                            //（live-update watcher 等）不算用户可见工作，不计数避免状态行虚高
+                            turn.bgTasks.clear();
+                            for (const t of message.tasks) {
+                                if (!t.ambient)
+                                    turn.bgTasks.set(t.task_id, { taskType: t.task_type, description: t.description });
+                            }
+                            if (turn.waitingBg && turn.bgTasks.size > 0) {
+                                await turn.cb.onProgress({ kind: 'status', content: `⏳ 等待 ${turn.bgTasks.size} 个后台任务完成…` });
+                            }
                         }
-                    }
-                    else if (message.subtype === 'task_started') {
-                        const tag = message.subagent_type ? ` [${message.subagent_type}]` : '';
-                        await cb.onProgress({
-                            kind: 'status',
-                            content: `${message.is_backgrounded ? '🤖 后台子代理启动' : '🤖 子代理启动'}${tag}: ${message.description}`,
-                        });
-                        // 子代理清单：进度卡独立区块展示每个子代理的运行状态（对齐 CLI 的 agent 进度显示）
-                        await cb.onProgress({
-                            kind: 'agent-start',
-                            agent: { id: message.task_id, description: message.description, type: message.subagent_type ?? 'task' },
-                        });
-                    }
-                    else if (message.subtype === 'task_notification') {
-                        // 后台任务落定（completed/failed/stopped）：summary 为任务自述结论。
-                        // status 会原文渲染进进度卡正文并随每次卡片更新发送——子代理完整报告可达
-                        // 上万字符，截断保留结论摘要（全文另有 agent 清单与 transcript 承载）
-                        const label = message.status === 'completed' ? '✅ 后台任务完成' : message.status === 'failed' ? '❌ 后台任务失败' : '🛑 后台任务已停止';
-                        await cb.onProgress({ kind: 'status', content: `${label}: ${(message.summary ?? '').slice(0, 300)}` });
-                        await cb.onProgress({
-                            kind: 'agent-settle',
-                            id: message.task_id,
-                            status: message.status === 'completed' ? 'done' : message.status === 'failed' ? 'failed' : 'stopped',
-                            ...(message.summary ? { summary: message.summary } : {}),
-                        });
-                    }
-                    break;
-                }
-                case 'stream_event': {
-                    // 流式增量（includePartialMessages）：仅用首个 text delta 提前点亮「正在执行」——
-                    // 完整块生成前状态行 otherwise 停留在启动阶段。按 Anthropic Messages stream 事件
-                    // 结构窄化访问，字段缺失/其他事件类型静默忽略
-                    const ev = message.event;
-                    if (!sawFirstDelta && ev?.type === 'content_block_delta' && ev.delta?.type === 'text_delta') {
-                        sawFirstDelta = true;
-                        if (!firstOutAt)
-                            firstOutAt = Date.now();
-                        await cb.onProgress({ kind: 'first-delta' });
-                    }
-                    break;
-                }
-                case 'assistant': {
-                    if (!firstOutAt)
-                        firstOutAt = Date.now();
-                    // turns 只计主循环轮次：子代理消息（parent_tool_use_id 非空）混入会把单任务轮数
-                    // 放大数倍（旧超长提醒误报的帮凶），兜底口径应以主循环为准
-                    if (!message.parent_tool_use_id)
-                        turns++;
-                    for (const block of message.message.content) {
-                        if (block.type === 'text') {
-                            // 子代理文本加标识前缀（forwardSubagentText 转发），与主 Agent 输出在进度卡上区分
-                            const prefix = message.parent_tool_use_id ? '🤖 ' : '';
-                            await cb.onProgress({ kind: 'text', content: `${prefix}${block.text}` });
+                        else if (message.subtype === 'session_state_changed' && message.state === 'idle') {
+                            // 权威 turn-over 信号：idle 在 heldBackResult flush 且后台任务续跑循环退出后触发。
+                            // 主 turn result 已到 + 后台任务全部结束 → 真正收尾（后台任务若再唤醒主循环，
+                            // 会先收到新的 assistant/result 事件并覆盖 finalText，idle 仍在最后）
+                            if (turn.waitingBg && turn.bgTasks.size === 0) {
+                                await this.finalizeTurn(turn);
+                            }
                         }
-                        else if (block.type === 'tool_use') {
-                            const input = (block.input ?? {});
-                            toolNames.set(block.id, block.name);
-                            collector.track(block.name, input);
-                            await cb.onProgress({ kind: 'tool-start', content: `${block.name}: ${summarizeToolInput(input)}` });
+                        else if (message.subtype === 'task_started') {
+                            const tag = message.subagent_type ? ` [${message.subagent_type}]` : '';
+                            await turn.cb.onProgress({
+                                kind: 'status',
+                                content: `${message.is_backgrounded ? '🤖 后台子代理启动' : '🤖 子代理启动'}${tag}: ${message.description}`,
+                            });
+                            // 子代理清单：进度卡独立区块展示每个子代理的运行状态（对齐 CLI 的 agent 进度显示）
+                            await turn.cb.onProgress({
+                                kind: 'agent-start',
+                                agent: { id: message.task_id, description: message.description, type: message.subagent_type ?? 'task' },
+                            });
+                        }
+                        else if (message.subtype === 'task_notification') {
+                            // 后台任务落定（completed/failed/stopped）：summary 为任务自述结论。
+                            // status 会原文渲染进进度卡正文并随每次卡片更新发送——子代理完整报告可达
+                            // 上万字符，截断保留结论摘要（全文另有 agent 清单与 transcript 承载）
+                            const label = message.status === 'completed' ? '✅ 后台任务完成' : message.status === 'failed' ? '❌ 后台任务失败' : '🛑 后台任务已停止';
+                            await turn.cb.onProgress({ kind: 'status', content: `${label}: ${(message.summary ?? '').slice(0, 300)}` });
+                            await turn.cb.onProgress({
+                                kind: 'agent-settle',
+                                id: message.task_id,
+                                status: message.status === 'completed' ? 'done' : message.status === 'failed' ? 'failed' : 'stopped',
+                                ...(message.summary ? { summary: message.summary } : {}),
+                            });
                         }
-                    }
-                    break;
-                }
-                case 'user': {
-                    const content = message.message.content;
-                    if (!Array.isArray(content))
                         break;
-                    for (const block of content) {
-                        if (block.type === 'tool_result') {
-                            const name = toolNames.get(block.tool_use_id) ?? '';
-                            const note = block.is_error ? firstErrorLine(block.content) : undefined;
-                            await cb.onProgress({ kind: 'tool-result', content: name, ok: !block.is_error, ...(note ? { note } : {}) });
+                    }
+                    case 'stream_event': {
+                        // 流式增量（includePartialMessages）：仅用首个 text delta 提前点亮「正在执行」——
+                        // 完整块生成前状态行 otherwise 停留在启动阶段。按 Anthropic Messages stream 事件
+                        // 结构窄化访问，字段缺失/其他事件类型静默忽略
+                        const ev = message.event;
+                        if (!turn.sawFirstDelta && ev?.type === 'content_block_delta' && ev.delta?.type === 'text_delta') {
+                            turn.sawFirstDelta = true;
+                            if (turn.initAt && !turn.firstOutAt)
+                                turn.firstOutAt = Date.now();
+                            await turn.cb.onProgress({ kind: 'first-delta' });
                         }
+                        break;
                     }
-                    break;
-                }
-                case 'result': {
-                    if (message.subtype === 'success')
-                        finalText = message.result;
-                    // 非成功终态（error_during_execution / error_max_turns 等，错误文本在 errors 数组）：
-                    // 带出循环后统一抛出，消息格式与单轮模式 SDK throw 保持一致（index.ts catch 的 hint 依赖该格式）
-                    else if (message.subtype.startsWith('error'))
-                        resultErrorText = message.errors?.join('\n') || message.subtype;
-                    // usage 提取（error result 可能缺字段，全部兜 0 不抛）
-                    const u = message.usage;
-                    if (u) {
-                        usage = {
-                            inputTokens: u.input_tokens ?? 0,
-                            outputTokens: u.output_tokens ?? 0,
-                            cacheCreationInputTokens: u.cache_creation_input_tokens ?? 0,
-                            cacheReadInputTokens: u.cache_read_input_tokens ?? 0,
-                        };
+                    case 'assistant': {
+                        // P2 修正：输出信号只认 init 之后的（resume 回放的 assistant 块/时钟漂移不再产生
+                        // 负数 init→首输出——统计被离群污染的根因）。渲染/轮次计数不受影响
+                        if (turn.initAt && !turn.firstOutAt)
+                            turn.firstOutAt = Date.now();
+                        // turns 只计主循环轮次：子代理消息（parent_tool_use_id 非空）混入会把单任务轮数
+                        // 放大数倍（旧超长提醒误报的帮凶），兜底口径应以主循环为准
+                        if (!message.parent_tool_use_id)
+                            turn.turns++;
+                        for (const block of message.message.content) {
+                            if (block.type === 'text') {
+                                // 子代理文本加标识前缀（forwardSubagentText 转发），与主 Agent 输出在进度卡上区分
+                                const prefix = message.parent_tool_use_id ? '🤖 ' : '';
+                                await turn.cb.onProgress({ kind: 'text', content: `${prefix}${block.text}` });
+                            }
+                            else if (block.type === 'tool_use') {
+                                const input = (block.input ?? {});
+                                turn.toolNames.set(block.id, block.name);
+                                turn.collector.track(block.name, input);
+                                await turn.cb.onProgress({ kind: 'tool-start', content: `${block.name}: ${summarizeToolInput(input)}` });
+                            }
+                        }
+                        break;
                     }
-                    if ('session_id' in message && typeof message.session_id === 'string')
-                        sessionId = message.session_id;
-                    // 主 turn 终态。后台任务仍在跑时不收尾：return 会触发 q.return() → SDK 清理子进程，
-                    // 后台子代理被连带杀掉、完成通知永远收不到（旧版「主代理结束、子代理无声消失」根因）。
-                    // 挂起继续 for await：后台任务完成会唤醒 CLI 主循环自动续跑（新的 assistant/result
-                    // 事件照常流出，飞书端继续收到推送），直到 session_state_changed(idle) 或续跑 turn 的
-                    // result 在 bgTasks 清空后到达才真正收尾。bgTasks 为空 = 无在途任务，维持旧行为立即收尾
-                    //（CLI 不发 background_tasks_changed 事件时自然退化，不会比旧版更差）
-                    if (message.subtype === 'success' || message.subtype.startsWith('error')) {
-                        if (bgTasks.size > 0) {
-                            waitingBg = true;
-                            await cb.onProgress({ kind: 'status', content: `⏳ 主线回复完成，等待 ${bgTasks.size} 个后台任务…` });
+                    case 'user': {
+                        const content = message.message.content;
+                        if (!Array.isArray(content))
                             break;
+                        for (const block of content) {
+                            if (block.type === 'tool_result') {
+                                const name = turn.toolNames.get(block.tool_use_id) ?? '';
+                                const note = block.is_error ? firstErrorLine(block.content) : undefined;
+                                await turn.cb.onProgress({ kind: 'tool-result', content: name, ok: !block.is_error, ...(note ? { note } : {}) });
+                            }
                         }
-                        return await finalizeWithMcpPoll();
+                        break;
+                    }
+                    case 'result': {
+                        if (message.subtype === 'success')
+                            turn.finalText = message.result;
+                        // 非成功终态（error_during_execution / error_max_turns 等，错误文本在 errors 数组）：
+                        // 带出循环后统一抛出，消息格式与单轮模式 SDK throw 保持一致（index.ts catch 的 hint 依赖该格式）
+                        else if (message.subtype.startsWith('error'))
+                            turn.resultErrorText = message.errors?.join('\n') || message.subtype;
+                        // usage 提取（error result 可能缺字段，全部兜 0 不抛）
+                        const u = message.usage;
+                        if (u) {
+                            turn.usage = {
+                                inputTokens: u.input_tokens ?? 0,
+                                outputTokens: u.output_tokens ?? 0,
+                                cacheCreationInputTokens: u.cache_creation_input_tokens ?? 0,
+                                cacheReadInputTokens: u.cache_read_input_tokens ?? 0,
+                            };
+                        }
+                        if ('session_id' in message && typeof message.session_id === 'string') {
+                            this.sessionId = message.session_id;
+                            turn.sessionId = message.session_id;
+                        }
+                        // 主 turn 终态。后台任务仍在跑时不收尾：return 会触发 q.return() → SDK 清理子进程，
+                        // 后台子代理被连带杀掉、完成通知永远收不到（旧版「主代理结束、子代理无声消失」根因）。
+                        // 挂起继续 for await：后台任务完成会唤醒 CLI 主循环自动续跑（新的 assistant/result
+                        // 事件照常流出，飞书端继续收到推送），直到 session_state_changed(idle) 或续跑 turn 的
+                        // result 在 bgTasks 清空后到达才真正收尾。bgTasks 为空 = 无在途任务，维持旧行为立即收尾
+                        //（CLI 不发 background_tasks_changed 事件时自然退化，不会比旧版更差）
+                        if (message.subtype === 'success' || message.subtype.startsWith('error')) {
+                            if (turn.bgTasks.size > 0) {
+                                turn.waitingBg = true;
+                                await turn.cb.onProgress({ kind: 'status', content: `⏳ 主线回复完成，等待 ${turn.bgTasks.size} 个后台任务…` });
+                                break;
+                            }
+                            await this.finalizeTurn(turn);
+                        }
+                        break;
                     }
-                    break;
                 }
             }
+            // 流自然结束（CLI 进程退出/被 kill）：轮内未收尾的按进程退出错误结算。
+            // kill 路径（/stop、回收）按中止语义（wiring 的 abort 分支命中）；非 kill 的自然
+            // EOF 在 result 之前到达属进程崩溃——明确报因，不再像旧版那样静默返回空成功
+            if (this.currentTurn && !this.currentTurn.settled) {
+                const err = new Error(this.killed ? 'Operation aborted' : 'Claude Code 进程在回复完成前退出（可重发任务；历史上下文经 /resume 可找回）');
+                this.settleTurnError(this.currentTurn, err);
+            }
+            this.die();
         }
-    }
-    catch (e) {
-        // 流错误（/stop 的 AbortError、Stream closed 等）：把已知的 sessionId 挂到错误对象再抛——
-        // wiring 侧据此把中止/出错任务的会话也归档进 /resume 历史（AbortError 自身不携带
-        // sessionId；不改动原 message，index.ts catch 的 hint 匹配不受影响）
-        const err = e instanceof Error ? e : new Error(String(e));
-        if (sessionId && !err.sessionId) {
-            err.sessionId = sessionId;
+        catch (e) {
+            // 流错误（/stop 的 AbortError、Stream closed、进程崩溃等）：把已知的 sessionId 挂到
+            // 错误对象再抛——wiring 侧据此把中止/出错任务的会话也归档进 /resume 历史
+            //（AbortError 自身不携带 sessionId；不改动原 message，index.ts catch 的 hint 匹配不受影响）
+            const err = e instanceof Error ? e : new Error(String(e));
+            if (this.currentTurn && !this.currentTurn.settled)
+                this.settleTurnError(this.currentTurn, err);
+            this.die();
         }
-        throw err;
     }
-    finally {
-        clearInterval(silenceWatch);
+    /** 收尾前拉一次 MCP 真实连接状态（init 快照必为 pending，这是空闲期 /mcp 的数据源）；
+     *  try/catch 同时兜住同步异常（旧 mock/异常环境下方法缺失）与异步拒绝，绝不阻断收尾 */
+    async finalizeTurn(turn) {
+        try {
+            const statuses = await this.q.mcpServerStatus();
+            turn.cb.onMcpStatus?.(statuses);
+        }
+        catch { /* 拉取失败：保留 init 快照 */ }
+        if (turn.resultErrorText) {
+            // 携带 sessionId 抛出：wiring 侧据此把出错任务的会话也归档进 /resume 历史
+            //（错误任务的会话上下文同样有价值；早期不归档导致历史列表难积累）
+            const err = new Error(`Claude Code returned an error result: ${turn.resultErrorText}`);
+            err.sessionId = turn.sessionId || undefined;
+            this.settleTurn(turn, err);
+            return;
+        }
+        this.settleTurn(turn, {
+            sessionId: turn.sessionId,
+            finalText: turn.finalText,
+            producedFiles: turn.collector.files(),
+            turns: turn.turns,
+            ...(turn.usage ? { usage: turn.usage } : {}),
+            ...(this.inventory ? { inventory: this.inventory } : {}),
+        });
     }
-    return finalize();
-    function finalize() {
+    /** 轮次落定（成功/出错共用）：清看门狗与信号监听、复位 busy、（ephemeral）停止循环 */
+    settleTurn(turn, result) {
+        if (turn.settled)
+            return;
+        turn.settled = true;
+        clearInterval(turn.silenceWatch);
+        this.turnSignalCleanup?.();
+        this.turnSignalCleanup = undefined;
+        if (this.currentTurn === turn)
+            this.currentTurn = undefined;
+        this.busy = false;
+        this.lastUsedAt = Date.now();
         // 启动耗时分解（先诊断承诺）：spawn→init 是 CLI 冷启动（配置/插件/MCP server 拉起 +
-        // resume 回放，越用越慢的主要嫌疑），init→首输出是模型首响——数据在手再决定下一步优化
+        // resume 回放）；复用轮为 0s（进程早已就绪）。init→首输出是模型首响（P2 修正后仅计
+        // init 之后的信号，不再被 resume 回放块污染成负数）。总耗时按本轮 push 时刻起算
         const sec = (ms) => `${(ms / 1000).toFixed(1)}s`;
-        console.log(`[executor] 启动耗时：spawn→init ${initAt ? sec(initAt - t0) : '?'}，init→首输出 ${initAt && firstOutAt ? sec(firstOutAt - initAt) : '?'}，总 ${sec(Date.now() - t0)}${opts.resumeSessionId ? '（resume 续接）' : '（新会话）'}`);
-        if (resultErrorText) {
-            // 携带 sessionId 抛出：wiring 侧据此把出错任务的会话也归档进 /resume 历史
-            //（错误任务的会话上下文同样有价值；早期不归档导致历史列表难积累）
-            const err = new Error(`Claude Code returned an error result: ${resultErrorText}`);
-            err.sessionId = sessionId || undefined;
+        const initLag = turn.reused ? '0s（常驻复用）'
+            : this.procInitAt ? sec(this.procInitAt - this.spawnT0) : '?';
+        const firstOut = turn.initAt && turn.firstOutAt && turn.firstOutAt >= turn.initAt ? sec(turn.firstOutAt - turn.initAt) : '?';
+        console.log(`[executor] 启动耗时：spawn→init ${initLag}，init→首输出 ${firstOut}，总 ${sec(Date.now() - turn.t0)}${turn.reused ? '（常驻复用）' : this.resident ? '（新进程）' : '（每消息进程）'}`);
+        if (result instanceof Error)
+            turn.reject(result);
+        else
+            turn.resolve(result);
+        // ephemeral：首轮收尾即停（对齐旧版「result 即 return 结束循环」）
+        if (!this.resident)
+            this.dead = true;
+    }
+    /** settleTurn 的错误入口：附 sessionId 后 reject（复用 catch 路径的挂载语义） */
+    settleTurnError(turn, err) {
+        if (turn.sessionId && !err.sessionId) {
+            err.sessionId = turn.sessionId;
+        }
+        this.settleTurn(turn, err);
+    }
+    /**
+     * 送入一轮任务（prompt 经 stdin 流写入同一进程），返回本轮结果。
+     * 复用轮开始前做三件事：回放 init 清单（无新 init 消息）、重曝光 query 句柄、
+     * 复位权限模式（上一轮 plan 批准可能已把进程切到 acceptEdits）。
+     */
+    async sendTurn(prompt, opts, cb) {
+        if (this.dead) {
+            const err = new Error('Operation aborted');
+            if (this.sessionId)
+                err.sessionId = this.sessionId;
             throw err;
         }
-        return { sessionId, finalText, producedFiles: collector.files(), turns, ...(usage ? { usage } : {}), ...(inventory ? { inventory } : {}) };
+        this.busy = true;
+        this.lastUsedAt = Date.now();
+        this.idleMs = opts.residentIdleMs ?? DEFAULT_RESIDENT_IDLE_MS;
+        const reused = this.initDone;
+        // 本轮 abort 信号接线：外部 signal（/stop、4h 硬超时）中止 = 杀整个进程
+        //（与旧行为等价：abortController.abort 终止整个 query），下条消息冷启重建。
+        // 直接桥接（signal → abortController）与旧 bridgeSignal 一致、不随轮清理——
+        // 「任务结束后 signal 仍传导到进程控制器」是既有可观测行为（wiring 侧不会再触发）
+        if (opts.signal) {
+            if (opts.signal.aborted) {
+                const err = new Error('Operation aborted');
+                if (this.sessionId)
+                    err.sessionId = this.sessionId;
+                this.busy = false;
+                void this.kill();
+                throw err;
+            }
+            const signal = opts.signal;
+            signal.addEventListener('abort', () => this.abortController.abort(new Error('task-aborted')), { once: true });
+            const onAbort = () => { void this.kill(); };
+            signal.addEventListener('abort', onAbort, { once: true });
+            this.turnSignalCleanup = () => signal.removeEventListener('abort', onAbort);
+        }
+        const proc = this;
+        const turn = {
+            prompt,
+            cb,
+            collector: new OutputCollector(opts.cwd),
+            resolve: () => { },
+            reject: () => { },
+            settled: false,
+            t0: Date.now(),
+            initAt: 0,
+            firstOutAt: 0,
+            sawFirstDelta: false,
+            finalText: '',
+            resultErrorText: '',
+            usage: undefined,
+            turns: 0,
+            sessionId: opts.resumeSessionId ?? '',
+            reused,
+            bgTasks: new Map(),
+            waitingBg: false,
+            lastEventAt: Date.now(),
+            toolNames: new Map(),
+            // 等待后台任务期间的静默看门狗：pending 期间长时间无任何事件则按已有信息收尾
+            //（并把进程一并回收——15 分钟静默属异常态，进程可信度存疑，冷启重建更稳）
+            silenceWatch: setInterval(() => {
+                const t = proc.currentTurn;
+                if (t === turn && t.waitingBg && Date.now() - t.lastEventAt > BG_WAIT_SILENCE_TIMEOUT_MS) {
+                    console.warn(`[executor] 等待后台任务静默超 ${Math.round(BG_WAIT_SILENCE_TIMEOUT_MS / 60000)} 分钟无事件，按已有结果收尾（后台任务: ${[...t.bgTasks.values()].map((x) => x.description).join(' / ')}）`);
+                    proc.settleTurn(t, {
+                        sessionId: t.sessionId,
+                        finalText: t.finalText,
+                        producedFiles: t.collector.files(),
+                        turns: t.turns,
+                        ...(t.usage ? { usage: t.usage } : {}),
+                        ...(proc.inventory ? { inventory: proc.inventory } : {}),
+                    });
+                    void proc.kill();
+                }
+            }, 30_000),
+        };
+        turn.silenceWatch.unref?.();
+        if (reused) {
+            // 复用轮：进程早已 init —— 本轮「启动」为 0s；init 清单回放（指纹保证未变）+
+            // 句柄重曝光 + 权限模式复位到本轮期望
+            turn.initAt = Date.now();
+            if (this.inventory)
+                cb.onInit?.(this.inventory);
+            opts.onQuery?.(this.q);
+            const want = opts.permissionMode ?? 'default';
+            if (want !== this.currentMode) {
+                await this.q.setPermissionMode(want).then(() => { this.currentMode = want; }).catch((e) => {
+                    console.warn('[executor] 复用轮 setPermissionMode 复位失败（继续按进程当前模式执行）:', e instanceof Error ? e.message : e);
+                });
+            }
+        }
+        else {
+            opts.onQuery?.(this.q);
+        }
+        const promise = new Promise((resolve, reject) => {
+            turn.resolve = resolve;
+            turn.reject = reject;
+        });
+        this.currentTurn = turn;
+        this.input.push({ type: 'user', message: { role: 'user', content: prompt }, parent_tool_use_id: null });
+        return promise;
+    }
+    /** 主动回收：结束流迭代 + 中止在途控制请求，进程出池。
+     *  忙碌进程不应被回收（会杀掉运行中任务）——调用方自查 isBusy */
+    async kill() {
+        if (this.killed)
+            return;
+        this.killed = true;
+        this.dead = true;
+        if (pool.get(this.key) === this)
+            pool.delete(this.key);
+        // 本轮仍在途时同步 abort（唤醒在途等待；外部 signal 路径的直达桥接已先行触发）；
+        // 空闲回收不 abort——结束迭代本身即触发 SDK 子进程清理，且保持「任务完成后
+        // 控制器不被污染」的既有可观测语义
+        if (this.currentTurn)
+            this.abortController.abort(new Error('process-recycled'));
+        try {
+            await this.q.return(undefined);
+        }
+        catch { /* 进程已退等场景：忽略 */ }
+    }
+    /** 非主动的死亡（流结束/崩溃）：出池即可，迭代已自然结束 */
+    die() {
+        if (this.dead)
+            return;
+        this.dead = true;
+        if (pool.get(this.key) === this)
+            pool.delete(this.key);
+    }
+}
+// ---- 常驻进程池（模块级，跨 app 共享；key 带 appId 前缀防撞） ----
+const pool = new Map();
+let sweeper = null;
+/** 空闲回收巡检：每分钟扫一遍池，空闲超阈值的空闲进程回收。
+ *  复用路径还有内联检查（消息到达时判定），巡检负责「之后再无消息」的内存释放 */
+function ensureSweeper() {
+    if (sweeper)
+        return;
+    sweeper = setInterval(() => {
+        const now = Date.now();
+        for (const proc of [...pool.values()]) {
+            if (!proc.isBusy && proc.idleMs > 0 && now - proc.lastUsedAt > proc.idleMs) {
+                console.log(`[executor] 常驻进程空闲回收：${proc.key}（空闲 ${Math.round((now - proc.lastUsedAt) / 60000)} 分钟）`);
+                void proc.kill();
+            }
+        }
+        if (pool.size === 0 && sweeper) {
+            clearInterval(sweeper);
+            sweeper = null;
+        }
+    }, 60_000);
+    sweeper.unref?.();
+}
+/** 进程注册入池 + 上限约束（按 scope 统计，LRU 淘汰最久未用的空闲进程；忙进程不动） */
+function register(proc, max) {
+    pool.set(proc.key, proc);
+    if (max && max > 0) {
+        const others = [...pool.values()].filter((p) => p !== proc && p.scope === proc.scope);
+        let over = others.length + 1 - max;
+        if (over > 0) {
+            const idleOldestFirst = others.filter((p) => !p.isBusy).sort((a, b) => a.lastUsedAt - b.lastUsedAt);
+            for (const victim of idleOldestFirst) {
+                if (over-- <= 0)
+                    break;
+                console.log(`[executor] 常驻进程池达上限（${max}），LRU 回收：${victim.key}`);
+                void victim.kill();
+            }
+        }
+    }
+    ensureSweeper();
+}
+/** 指针切换时作废该通道的常驻进程（/new、/resume <n>、/ws use）：旧进程的会话上下文
+ *  不再适用。忙进程不动——运行中任务的中止由 /new 的 abort 负责（abort 会连带杀进程） */
+export function killResidentSession(affinityKey) {
+    const proc = pool.get(affinityKey);
+    if (proc && !proc.isBusy)
+        void proc.kill();
+}
+/** 桥接器关闭时回收全部常驻进程（优雅退出，不赖 stdio 断连兜底） */
+export function killAllResidentSessions() {
+    for (const proc of [...pool.values()])
+        void proc.kill();
+}
+/** 测试隔离：清空进程池（生产代码不得调用） */
+export function __resetResidentPoolForTests() {
+    for (const proc of [...pool.values()])
+        void proc.kill();
+    pool.clear();
+}
+export async function runTask(prompt, opts, cb) {
+    const key = opts.affinityKey;
+    if (!key || opts.resident === false) {
+        // ephemeral：每消息一个进程（旧行为）——spawn 一轮即回收的常驻进程，循环逻辑与常驻同一条
+        const proc = SessionProcess.spawn(key ?? `ephemeral:${Math.random().toString(36).slice(2)}`, opts, false);
+        try {
+            return await proc.sendTurn(prompt, opts, cb);
+        }
+        finally {
+            await proc.kill();
+        }
+    }
+    // 常驻路径：复用三校验（活着 / 指纹一致 / 指针一致），任一不符回收重建。
+    // 内联空闲检查与 sweeper 双保险：消息到达时先行判定，不等巡检周期
+    const fp = fingerprintOf(opts);
+    const wantSession = opts.resumeSessionId ?? '';
+    let proc = pool.get(key);
+    if (proc && (!proc.dead) && !proc.isBusy && proc.fingerprint === fp && proc.sessionId === wantSession
+        && !(proc.idleMs > 0 && Date.now() - proc.lastUsedAt > proc.idleMs)) {
+        console.log(`[executor] 常驻进程复用：${key}（会话 ${proc.sessionId || '待 init'}）`);
+        return await proc.sendTurn(prompt, opts, cb);
+    }
+    if (proc) {
+        // 归因日志：指纹漂移（配置热改）/ 指针漂移（/new /resume /ws use / 群聊滚动）/ 空闲超阈值 / 忙碌兜底
+        if (proc.isBusy) {
+            console.warn(`[executor] 通道 ${key} 的常驻进程仍在忙碌（异常：FIFO 串行下不应发生），本轮独立冷启`);
+            const standalone = SessionProcess.spawn(`${key}:overlapping-${Date.now()}`, { ...opts, affinityKey: undefined, resident: false }, false);
+            try {
+                return await standalone.sendTurn(prompt, opts, cb);
+            }
+            finally {
+                await standalone.kill();
+            }
+        }
+        const reason = proc.fingerprint !== fp
+            ? `配置指纹变化：${describePartDrift(proc.spawnParts, fingerprintParts(opts)).join('、')}`
+            : proc.sessionId !== wantSession ? '会话指针变化'
+                : proc.idleMs > 0 && Date.now() - proc.lastUsedAt > proc.idleMs ? '空闲超阈值'
+                    : '进程已退出';
+        console.log(`[executor] 常驻进程回收重建（${reason}）：${key}`);
+        await proc.kill();
+        proc = undefined;
     }
+    const created = SessionProcess.spawn(key, opts, true);
+    register(created, opts.residentMax);
+    return await created.sendTurn(prompt, opts, cb);
 }
 //# sourceMappingURL=claude-executor.js.map