lark-remote 0.4.2 → 0.4.4

package/dist/runner/common/jsonrpc/transport.js

@@ -6,8 +6,11 @@
  * each line on stdout is a JSON message from the server; each `write()`
  * sends a JSON line to stdin.
  */
+import { StringDecoder } from 'node:string_decoder';
 import { spawnProcess, mergeProcessEnv, isWindowsCommandNotFoundLine, useDetachedProcessGroup, } from '../../../platform/spawn.js';
-import { ProcessStopper } from '../process-stopper.js';
+import { binaryName } from '../../../platform/identity.js';
+import { createTerminator } from '../../../platform/terminator.js';
+import { agentStopperRegistry, } from '../../../platform/agent-stopper.js';
 import { getLogger } from '../../../logger/index.js';
 /** Max bytes for a single line before we disconnect (10MB). */
 const MAX_LINE_BYTES = 10 * 1024 * 1024;
@@ -17,11 +20,17 @@ export class JsonlRpcTransport {
     proc = null;
     _closed = false;
     events = null;
-    stopper;
+    terminator;
     binary;
     args;
     cwd;
     env;
+    /** 协议停止通道查找键（与 Terminator 用的 agent key 同一来源，见构造函数）。 */
+    agent;
+    stoppers;
+    stopperFactory;
+    /** 已登记的通道（agent+pid 键）；null = 本连接没有可用通道或已注销。 */
+    registration = null;
     /** JSON lines buffered while stdin is under backpressure (bounded by callers). */
     writeQueue = [];
     flushing = false;
@@ -32,7 +41,21 @@ export class JsonlRpcTransport {
         this.args = opts.args;
         this.cwd = opts.cwd;
         this.env = opts.env ?? {};
-        this.stopper = new ProcessStopper({ graceMs: 5000 });
+        // 协议停止通道按 agent key 索引：调用方（connection-manager）只给 binary，
+        // 这里用 binaryName 归一（含 win32 的 `.cmd` 垫片与全路径两种形态），
+        // 免得每个协议 runner 都要重复传一遍 agent 名。
+        this.agent = opts.agent ?? binaryName(opts.binary);
+        this.stoppers = opts.stoppers ?? agentStopperRegistry;
+        this.stopperFactory = opts.stopper;
+        // Terminator 与注册表共用同一个 agent key 和同一张表：两边任一取错来源，
+        // 查表就静默失配（优雅段退化回树杀还不报错），所以都从这里下传。
+        this.terminator =
+            opts.terminator ??
+                createTerminator({ graceMs: 5000, agent: this.agent, stoppers: this.stoppers });
+    }
+    /** 子进程 pid（spawn 前/退出后为 undefined）；供测试与连接层按 pid 定位。 */
+    get pid() {
+        return this.proc?.pid;
     }
     get closed() {
         return this._closed;
@@ -70,6 +93,9 @@ export class JsonlRpcTransport {
             return;
         }
         getLogger().info(`[jsonrpc-transport] spawned pid=${proc.pid} binary=${this.binary}`);
+        // 子进程起来后立刻登记协议停止通道：win32 上 graceful stop 没有信号可拦，
+        // 只有这条通道能让 agent server 自己收摊（关 stdin / 取消在途 turn）。
+        this.registerStopper(proc.pid);
         proc.stdin?.on('error', (err) => {
             getLogger().warn(`[jsonrpc-transport] stdin error: ${err.message}`);
             this.handleClose('epipe');
@@ -90,34 +116,50 @@ export class JsonlRpcTransport {
             }
         });
         // Stdout: line-split with 10MB line limit
+        // decoder 跨 chunk 缓冲半个多字节字符：逐 chunk toString 会把中文/emoji 打成
+        // 不可逆的 U+FFFD，且 remainder 拼接后无法复原
+        const decoder = new StringDecoder('utf8');
         let remainder = '';
         proc.stdout?.on('data', (chunk) => {
-            remainder += chunk.toString('utf-8');
+            remainder += decoder.write(chunk);
             const lines = remainder.split('\n');
             // Lines except the last (incomplete) one
             remainder = lines.pop() ?? '';
             for (const line of lines) {
                 if (line.length === 0)
                     continue;
-                if (line.length > MAX_LINE_BYTES) {
+                // 上限量的是 UTF-8 字节：中文 1 单元 = 3 字节，用 line.length 会低估 2-3×
+                if (Buffer.byteLength(line, 'utf8') > MAX_LINE_BYTES) {
                     getLogger().error(`[jsonrpc-transport] line exceeds ${MAX_LINE_BYTES} bytes, disconnecting`);
                     this.handleClose('parse_error');
                     return;
                 }
+                let msg;
                 try {
-                    const msg = JSON.parse(line);
-                    events.onMessage(msg);
+                    msg = JSON.parse(line);
                 }
                 catch (err) {
                     getLogger().warn(`[jsonrpc-transport] failed to parse JSON: ${err.message} line=${line.slice(0, 200)}`);
+                    continue;
+                }
+                // handler 抛错是消费方故障，与协议解码无关；单独捕获以免掩盖真实故障点，
+                // 且不能打断同一 chunk 里后续的帧
+                try {
+                    events.onMessage(msg);
+                }
+                catch (err) {
+                    getLogger().error(`[jsonrpc-transport] onMessage handler threw: ${err instanceof Error ? err.message : String(err)}`);
                 }
             }
         });
         // Handle process exit
         const onExit = (code, signal) => {
             this._closed = true;
+            // 进程已经没了：留着旧 pid 的通道只会在 pid 复用后指向无关进程。
+            this.unregisterStopper();
             this.proc = null;
-            // Flush remaining buffer
+            // Flush remaining buffer（decoder.end() 吐出最后半个多字节字符）
+            remainder += decoder.end();
             if (remainder.length > 0) {
                 try {
                     const msg = JSON.parse(remainder);
@@ -209,7 +251,7 @@ export class JsonlRpcTransport {
         const proc = this.proc;
         if (proc) {
             try {
-                await this.stopper.stop(proc);
+                await this.terminator.stop(proc, { immediate: false });
             }
             catch {
                 // Ignore stop errors — process may already be dead
@@ -218,6 +260,27 @@ export class JsonlRpcTransport {
                 proc.stdin.end();
             }
         }
+        // 注销必须在 stop() 之后：Terminator 就是在上面那次调用里查表取通道的。
+        this.unregisterStopper();
+    }
+    /**
+     * 按 pid 登记协议停止通道（工厂返回 undefined = 该 agent 无通道）。
+     * pid 是归属键：同一 agent 的多条长驻连接各有自己的通道，不能互相顶替。
+     */
+    registerStopper(pid) {
+        const stopper = this.stopperFactory?.(pid);
+        if (!stopper)
+            return;
+        this.stoppers.register(this.agent, pid, stopper);
+        this.registration = { pid, stopper };
+    }
+    /** 注销自己登记的那条通道（幂等；带身份校验，防误删同 pid 上的新通道）。 */
+    unregisterStopper() {
+        const reg = this.registration;
+        if (!reg)
+            return;
+        this.registration = null;
+        this.stoppers.unregister(this.agent, reg.pid, reg.stopper);
     }
     handleClose(reason) {
         if (this._closed)
@@ -237,8 +300,14 @@ export class JsonlRpcTransport {
             }
             // 异常路径（EPIPE/超长行/进程 error）也要收掉子进程，避免孤儿进程
             // 继续运行（如超长行场景子进程还在往 stdout 灌数据）。
-            void this.stopper.stop(proc).catch((err) => {
+            void this.terminator
+                .stop(proc, { immediate: false })
+                .catch((err) => {
                 getLogger().warn(`[jsonrpc-transport] failed to stop process during close: ${err instanceof Error ? err.message : String(err)}`);
+            })
+                .finally(() => {
+                // 通道查表发生在上面这次 stop() 里，注销必须等它落定。
+                this.unregisterStopper();
             });
         }
         // 统一关闭出口：EPIPE/超长行/进程 error 都必须通知上层（connection-manager

package/dist/runner/common/spawning-runner.d.ts

@@ -1,6 +1,6 @@
-import { type ChildProcess } from 'node:child_process';
+import type { ChildProcess } from 'node:child_process';
 import type { Readable } from 'node:stream';
-import { ProcessStopper } from './process-stopper.js';
+import { type Terminator } from '../../platform/terminator.js';
 import { SpawnHeartbeat } from './spawn-heartbeat.js';
 import type { SpawnOptions } from '../types.js';
 /**
@@ -50,7 +50,7 @@ export declare function unregisterExitCleanup(handler: ExitCleanupHandler): void
 export declare abstract class SpawningRunner {
     protected currentProcess: ChildProcess | null;
     protected readonly pidFilePath: string;
-    protected readonly stopper: ProcessStopper;
+    protected readonly terminator: Terminator;
     protected readonly spawnHeartbeat: SpawnHeartbeat;
     protected binary: string;
     protected stopGraceMs: number;
@@ -77,6 +77,13 @@ export declare abstract class SpawningRunner {
      * 非零退出」才判 command-not-found；真挂起由既有 grace/超时兜底。
      */
     protected commandNotFoundSeen: boolean;
+    /**
+     * 本 runner 的 agent key（'claude'/…）：win32 上既是 Terminator 查协议停止
+     * 通道的键，也是这里登记通道的键。undefined = 无通道（如 `!` bash）。
+     */
+    protected readonly agent?: string;
+    /** 已登记的协议停止通道（agent+pid 键）；null = 未登记。 */
+    private stopperRegistration;
     constructor(opts: {
         pidDir?: string;
         workspace: string;
@@ -96,6 +103,13 @@ export declare abstract class SpawningRunner {
          * spawn-stage-stalled WARN identifies the right agent.
          */
         logTag?: string;
+        /**
+         * 当前 run 所属 agent（'claude'/'kimi'/…）：win32 上按这个 key 查协议停止
+         * 通道。缺省 undefined = 无通道（Terminator 会显式记录后走树杀，不空等）。
+         */
+        agent?: string;
+        /** 终止器注入（测试用）；默认按平台建 POSIX/win32 实现 */
+        terminator?: Terminator;
     });
     get isRunning(): boolean;
     /**
@@ -114,7 +128,7 @@ export declare abstract class SpawningRunner {
      * 'error' for ENOENT/EACCES, but some binaries fail silently without ever
      * emitting it. Without the race, the spawn lead-in hangs forever → the
      * workspace serial queue never settles → permanent deadlock, and /stop
-     * can't recover (ProcessStopper returns early when pid === undefined).
+     * can't recover (Terminator.stop returns early when pid === undefined).
      * The timeout keeps the deadlock bounded.
      */
     protected awaitSpawnError(proc: ChildProcess): Promise<Error | undefined>;
@@ -128,30 +142,46 @@ export declare abstract class SpawningRunner {
      * On success returns the spawned child.
      */
     protected spawnChild(opts: SpawnOptions): Promise<ChildProcess>;
+    /**
+     * 登记本进程的协议停止通道（design §3.3 表）：win32 上没有可拦截的跨进程
+     * SIGTERM，「优雅停止」只能经 agent 自有通道请求对方自行退出。stdio 型 agent
+     * CLI 的通道就是关 stdin（cc-connect 已验证 claude：关 stdin → 干净退出并跑
+     * Stop hooks）。
+     *
+     * 只在子进程真的挂了 stdin 管道时登记：stdin 为 'ignore' 的子类若照登一条空
+     * 通道，优雅段会从「无通道 → 显式跳过 + 直接树杀」退化成「空转满 grace 再
+     * 树杀」——照样能停，但白等一个不会被消费的请求。
+     */
+    protected registerStopper(proc: ChildProcess): void;
+    /** 注销本 runner 登记的通道（幂等；未登记时无操作）。 */
+    protected unregisterStopper(): void;
     /**
      * Stop the current process if one is running. Delegates the actual
-     * SIGTERM → grace → SIGKILL sequence to `this.stopper.stop(proc, opts)`
-     * (see `src/runner/common/process-stopper.ts`), forwarding the `immediate`
-     * flag verbatim so all subclasses inherit identical stop semantics.
+     * posix SIGTERM → grace → SIGKILL / win32 协议通道 → grace → taskkill 序列
+     * 给 `this.terminator.stop(proc, { immediate })`（见
+     * `src/platform/terminator.ts`），`immediate` 在这里收敛成显式 boolean，
+     * 所有子类继承同一套停止语义。
      */
     stop(opts?: {
         immediate?: boolean;
     }): Promise<void>;
-    killOrphan(): void;
     /**
-     * P1-10: verify the process behind a stale pid file is actually ours before
-     * sending any signal. `ps -o command=` (not `comm=`) is used because agent
-     * binaries may be bash-wrapped scripts whose comm is the interpreter name
-     * (`/bin/bash`); the full command line contains the binary path/basename.
+     * P1-10: 杀掉上一次崩溃留下的孤儿 agent 进程。**身份校验是动手的前置条件**：
+     * pid 文件里的 pid 可能已被系统回收给无关进程，`kill(pid, 0)` 存活探测分不出来。
      *
-     * Returns:
-     *   'match'    — ps succeeded and the command line contains this.binary
-     *                (absolute path) or its basename (PATH lookup).
-     *   'mismatch' — ps succeeded but the command line is clearly a different
-     *                process (pid was recycled to an unrelated process).
-     *   'unknown'  — ps failed / process gone / output unreadable: cannot tell.
+     * 判定单源 = `platform/identity`（posix `ps -o command=` / win32 CIM），三态：
+     *   - match    → 杀整个进程组（detached:true 下 agent 是组长，与 Terminator
+     *                posix 路径的 kill(-pid) 同语义，P1-12 子进程不孤儿化）；
+     *   - mismatch → pid 已被无关进程占用：绝不杀，文件是陈旧垃圾，清除自愈；
+     *   - unknown  → 查不到身份（ps 不可用/超时/CIM 被拒）：同样不杀，清文件。
+     * 统一原则：只有身份匹配才杀，验证失败一律不杀（fail-closed）。
+     *
+     * 同步实现是有意为之：调用方（Bridge.getRunner）是同步方法，改成异步会级联
+     * 整个 runner 接口。posix 上的成本与迁移前逐字相同（一次 execFileSync ps）；
+     * **win32 上同步路径恒返回 `unknown`**（CIM 必须经 PowerShell 收 stdout，没有同步
+     * 形态）→ 落到 fail-closed 分支「不杀 + 清文件」，语义正确而不是能力缺失。
      */
-    private matchPidToBinary;
+    killOrphan(): void;
     /**
      * Register this runner with the process-level exit dispatcher (singleton).
      * Process listeners are installed at most once; subsequent calls only add

package/dist/runner/common/spawning-runner.js

@@ -1,11 +1,12 @@
-import { execFileSync } from 'node:child_process';
 import { spawnProcess, isWindowsCommandNotFoundLine, useDetachedProcessGroup, } from '../../platform/spawn.js';
 import path from 'node:path';
 import os from 'node:os';
 import fs from 'node:fs';
 import { silentlyUnlink } from '../../common/fs.js';
 import { getLogger } from '../../logger/index.js';
-import { ProcessStopper } from './process-stopper.js';
+import { binaryName, verifyPidIdentityVerdictSync } from '../../platform/identity.js';
+import { createTerminator } from '../../platform/terminator.js';
+import { agentStopperRegistry } from '../../platform/agent-stopper.js';
 import { SpawnHeartbeat } from './spawn-heartbeat.js';
 import { createJSONLStream } from './jsonl-stream.js';
 import { DEFAULT_STOP_GRACE_MS } from '../../config/index.js';
@@ -78,7 +79,7 @@ export function unregisterExitCleanup(handler) {
 export class SpawningRunner {
     currentProcess = null;
     pidFilePath;
-    stopper;
+    terminator;
     spawnHeartbeat;
     binary;
     stopGraceMs;
@@ -105,16 +106,25 @@ export class SpawningRunner {
      * 非零退出」才判 command-not-found；真挂起由既有 grace/超时兜底。
      */
     commandNotFoundSeen = false;
+    /**
+     * 本 runner 的 agent key（'claude'/…）：win32 上既是 Terminator 查协议停止
+     * 通道的键，也是这里登记通道的键。undefined = 无通道（如 `!` bash）。
+     */
+    agent;
+    /** 已登记的协议停止通道（agent+pid 键）；null = 未登记。 */
+    stopperRegistration = null;
     constructor(opts) {
         // Subclasses set this.binary after super()
         this.binary = '';
         this.stopGraceMs = opts.stopGraceMs ?? DEFAULT_STOP_GRACE_MS;
         this.logTag = opts.logTag ?? 'spawning-runner';
+        this.agent = opts.agent;
         const pidDir = opts.pidDir ?? path.join(os.homedir(), '.lark-remote');
         const workspaceSuffix = `-${opts.workspace.replace(/[^a-zA-Z0-9]/g, '_')}`;
         const pidFilePrefix = opts.pidFilePrefix ?? 'spawning';
         this.pidFilePath = path.join(pidDir, `${pidFilePrefix}${workspaceSuffix}.pid`);
-        this.stopper = new ProcessStopper({ graceMs: this.stopGraceMs });
+        this.terminator =
+            opts.terminator ?? createTerminator({ graceMs: this.stopGraceMs, agent: opts.agent });
         this.spawnHeartbeat = new SpawnHeartbeat(opts.spawnHeartbeatMs ?? 30_000, this.logTag);
     }
     get isRunning() {
@@ -149,7 +159,7 @@ export class SpawningRunner {
      * 'error' for ENOENT/EACCES, but some binaries fail silently without ever
      * emitting it. Without the race, the spawn lead-in hangs forever → the
      * workspace serial queue never settles → permanent deadlock, and /stop
-     * can't recover (ProcessStopper returns early when pid === undefined).
+     * can't recover (Terminator.stop returns early when pid === undefined).
      * The timeout keeps the deadlock bounded.
      */
     awaitSpawnError(proc) {
@@ -209,6 +219,9 @@ export class SpawningRunner {
         proc.stdout?.once('data', () => {
             this.spawnHeartbeat.notifyStdout();
         });
+        // 协议停止通道登记（design §3.3）：子进程起来后立刻登记，win32 上
+        // Terminator 停这个 pid 时才能取到通道；进程退出/被停后注销。
+        this.registerStopper(proc);
         this.spawnStderr = '';
         proc.stderr?.on('data', (chunk) => {
             const text = chunk.toString('utf-8').trim();
@@ -231,25 +244,79 @@ export class SpawningRunner {
         });
         return proc;
     }
+    /**
+     * 登记本进程的协议停止通道（design §3.3 表）：win32 上没有可拦截的跨进程
+     * SIGTERM，「优雅停止」只能经 agent 自有通道请求对方自行退出。stdio 型 agent
+     * CLI 的通道就是关 stdin（cc-connect 已验证 claude：关 stdin → 干净退出并跑
+     * Stop hooks）。
+     *
+     * 只在子进程真的挂了 stdin 管道时登记：stdin 为 'ignore' 的子类若照登一条空
+     * 通道，优雅段会从「无通道 → 显式跳过 + 直接树杀」退化成「空转满 grace 再
+     * 树杀」——照样能停，但白等一个不会被消费的请求。
+     */
+    registerStopper(proc) {
+        const pid = proc.pid;
+        if (this.agent === undefined || pid === undefined || !proc.stdin)
+            return;
+        const stopper = (target) => {
+            target.stdin?.end();
+        };
+        // 上一次 spawn 的登记先撤掉：进程换代后旧 pid 的条目会一直挂在注册表里
+        // （pid 被系统复用时可能指向无关进程）。
+        this.unregisterStopper();
+        agentStopperRegistry.register(this.agent, pid, stopper);
+        this.stopperRegistration = { pid, stopper };
+    }
+    /** 注销本 runner 登记的通道（幂等；未登记时无操作）。 */
+    unregisterStopper() {
+        const reg = this.stopperRegistration;
+        if (!reg || this.agent === undefined)
+            return;
+        this.stopperRegistration = null;
+        agentStopperRegistry.unregister(this.agent, reg.pid, reg.stopper);
+    }
     /**
      * Stop the current process if one is running. Delegates the actual
-     * SIGTERM → grace → SIGKILL sequence to `this.stopper.stop(proc, opts)`
-     * (see `src/runner/common/process-stopper.ts`), forwarding the `immediate`
-     * flag verbatim so all subclasses inherit identical stop semantics.
+     * posix SIGTERM → grace → SIGKILL / win32 协议通道 → grace → taskkill 序列
+     * 给 `this.terminator.stop(proc, { immediate })`（见
+     * `src/platform/terminator.ts`），`immediate` 在这里收敛成显式 boolean，
+     * 所有子类继承同一套停止语义。
      */
     async stop(opts) {
         const proc = this.currentProcess;
         if (!proc || proc.exitCode !== null || proc.signalCode !== null) {
             this.spawnHeartbeat.clear();
             this.currentProcess = null;
+            this.unregisterStopper();
             return;
         }
         this.stoppedByUser = true;
-        await this.stopper.stop(proc, { immediate: opts?.immediate });
+        // `immediate: opts?.immediate === true`：Terminator 契约要求显式 boolean，
+        // 旧 ProcessStopper 的 `immediate?: boolean` 会静默接受 undefined。
+        await this.terminator.stop(proc, { immediate: opts?.immediate === true });
+        // 注销必须在 stop() 之后：Terminator 就是在上面那次调用里查表取通道的
+        // （immediate 路径不查表，但一并注销同样正确——进程已进入终止流程）。
+        this.unregisterStopper();
         this.currentProcess = null;
         silentlyUnlink(this.pidFilePath);
         getLogger().debug(`[${this.logTag}] cleaned pid file ${this.pidFilePath}`);
     }
+    /**
+     * P1-10: 杀掉上一次崩溃留下的孤儿 agent 进程。**身份校验是动手的前置条件**：
+     * pid 文件里的 pid 可能已被系统回收给无关进程，`kill(pid, 0)` 存活探测分不出来。
+     *
+     * 判定单源 = `platform/identity`（posix `ps -o command=` / win32 CIM），三态：
+     *   - match    → 杀整个进程组（detached:true 下 agent 是组长，与 Terminator
+     *                posix 路径的 kill(-pid) 同语义，P1-12 子进程不孤儿化）；
+     *   - mismatch → pid 已被无关进程占用：绝不杀，文件是陈旧垃圾，清除自愈；
+     *   - unknown  → 查不到身份（ps 不可用/超时/CIM 被拒）：同样不杀，清文件。
+     * 统一原则：只有身份匹配才杀，验证失败一律不杀（fail-closed）。
+     *
+     * 同步实现是有意为之：调用方（Bridge.getRunner）是同步方法，改成异步会级联
+     * 整个 runner 接口。posix 上的成本与迁移前逐字相同（一次 execFileSync ps）；
+     * **win32 上同步路径恒返回 `unknown`**（CIM 必须经 PowerShell 收 stdout，没有同步
+     * 形态）→ 落到 fail-closed 分支「不杀 + 清文件」，语义正确而不是能力缺失。
+     */
     killOrphan() {
         if (!fs.existsSync(this.pidFilePath))
             return;
@@ -260,21 +327,23 @@ export class SpawningRunner {
                 silentlyUnlink(this.pidFilePath);
                 return;
             }
-            // P1-10: pid 复用防护。pid 文件里的 pid 可能是 bridge 崩溃后系统回收复用
-            // 给了无关进程——kill(pid, 0) 存活探测无法区分，必须先验证进程身份。
-            const match = this.matchPidToBinary(pid);
-            if (match !== 'match') {
-                // 'gone'：ps 查不到/报错 → 进程已消失，陈旧追踪物自愈清除（不杀）。
-                // 'mismatch'：身份不匹配 → pid 已被无关进程占用，绝不能杀；文件是
-                // 陈旧垃圾，一并清除。
-                // 统一原则：只有身份匹配才杀；验证失败一律不杀。
-                getLogger().warn(`[${this.logTag}] killOrphan: pid ${pid} not confirmed as ${this.binary} ` +
-                    `(${match}), skipping kill`);
+            const expectedBinary = binaryName(this.binary);
+            // matchMode 'agent-invocation'（不是默认的 'executable'）：agent CLI 普遍是
+            // `#!/usr/bin/env node` 脚本，ps 看到的是 `node <安装路径>/…/cli.js`，名字只在
+            // 路径段里（pi → @earendil-works/pi-coding-agent/…）。用默认档会恒判 mismatch
+            // → 这些 agent 的孤儿永远回收不掉（2026-09-20 实测安装形态）。
+            const verdict = verifyPidIdentityVerdictSync(pid, {
+                expectedBinary,
+                matchMode: 'agent-invocation',
+            });
+            if (verdict !== 'match') {
+                getLogger().warn(`[${this.logTag}] killOrphan: pid ${pid} not confirmed as ${expectedBinary} ` +
+                    `(${verdict}), skipping kill`);
                 silentlyUnlink(this.pidFilePath);
                 return;
             }
             // 身份匹配：杀整个进程组（detached:true 下 agent 是组长），与
-            // ProcessStopper 的 kill(-pid) 语义对齐，子进程不会孤儿化（P1-12）。
+            // Terminator 的 kill(-pid) 语义对齐，子进程不会孤儿化（P1-12）。
             getLogger().info(`[${this.logTag}] killing orphan process group ${-pid}`);
             try {
                 process.kill(-pid, 'SIGTERM');
@@ -288,37 +357,6 @@ export class SpawningRunner {
             // ignore
         }
     }
-    /**
-     * P1-10: verify the process behind a stale pid file is actually ours before
-     * sending any signal. `ps -o command=` (not `comm=`) is used because agent
-     * binaries may be bash-wrapped scripts whose comm is the interpreter name
-     * (`/bin/bash`); the full command line contains the binary path/basename.
-     *
-     * Returns:
-     *   'match'    — ps succeeded and the command line contains this.binary
-     *                (absolute path) or its basename (PATH lookup).
-     *   'mismatch' — ps succeeded but the command line is clearly a different
-     *                process (pid was recycled to an unrelated process).
-     *   'unknown'  — ps failed / process gone / output unreadable: cannot tell.
-     */
-    matchPidToBinary(pid) {
-        try {
-            const out = execFileSync('ps', ['-p', String(pid), '-o', 'command='], {
-                encoding: 'utf-8',
-            }).trim();
-            if (!out || out.includes('<defunct>'))
-                return 'gone';
-            const binary = this.binary;
-            if (!binary)
-                return 'gone';
-            const needle = binary.includes('/') ? binary : path.basename(binary);
-            return out.includes(needle) ? 'match' : 'mismatch';
-        }
-        catch {
-            // ps 失败（进程不存在/权限）→ 视作 gone：不杀，让陈旧文件自愈
-            return 'gone';
-        }
-    }
     /**
      * Register this runner with the process-level exit dispatcher (singleton).
      * Process listeners are installed at most once; subsequent calls only add
@@ -355,12 +393,14 @@ export class SpawningRunner {
         if (this.currentProcess && this.currentProcess.exitCode === null) {
             try {
                 // P1-12: 只杀组长会让组内子进程（工具调用起的后台进程）reparent 成孤儿。
-                // 复用 ProcessStopper 的 immediate 组杀（SIGTERM+SIGKILL 同步发出，
-                // 进程退出路径 fire-and-forget 足够；正常进程退出时是 no-op）。
-                void this.stopper.stop(this.currentProcess, { immediate: true });
+                // Terminator.cleanupOnExit 在两种平台上都是「fire-and-forget 强杀整个
+                // 进程组/进程树」（posix kill(-pgid, SIGKILL) / win32 taskkill /T /F），
+                // 退出路径上无法等待，也不需要优雅段。
+                this.terminator.cleanupOnExit(this.currentProcess);
             }
             catch { }
         }
+        this.unregisterStopper();
         silentlyUnlink(this.pidFilePath);
     }
 }

package/dist/runner/dsh/client.d.ts

@@ -12,7 +12,7 @@
  * (DSH v1 has no `since` resume — reconnection = reopen stream + refetch
  * history, dedup by event seq).
  */
-import type { DshModelCatalogValue, DshModelSelection, DshPresetListValue, DshServerRequest, DshSessionModelsValue, DshStreamItem, DshTokenUsage } from './types.js';
+import type { DshModelCatalogValue, DshModelSelection, DshPresetListValue, DshServerRequest, DshStreamItem, DshTokenUsage } from './types.js';
 interface WebSocketMessageEvent {
     data: unknown;
 }
@@ -49,8 +49,6 @@ export declare class DshClient {
     selectModel(payload: DshModelSelection & {
         sessionId: string;
     }): Promise<DshModelSelection>;
-    /** Read the session's current model selection + full model catalog. */
-    sessionModels(sessionId: string): Promise<DshSessionModelsValue>;
     /** Read the model catalog (session-independent, llm.models). */
     listModels(): Promise<DshModelCatalogValue>;
     /** Read the preset catalog (agentPreset.list). */

package/dist/runner/dsh/client.js

@@ -81,10 +81,6 @@ export class DshClient {
         const value = (await this.unary('session.selectModel', payload));
         return value.selected;
     }
-    /** Read the session's current model selection + full model catalog. */
-    async sessionModels(sessionId) {
-        return (await this.unary('session.models', { sessionId }));
-    }
     /** Read the model catalog (session-independent, llm.models). */
     async listModels() {
         return (await this.unary('llm.models', {}));

package/dist/runner/dsh/types.d.ts

@@ -17,12 +17,6 @@ export interface DshSessionEvent {
     time: number;
     data: Record<string, unknown>;
 }
-/** assistant/chunk chunk payload (StreamChunk). */
-export interface DshChunk {
-    type: string;
-    index?: number;
-    text?: string;
-}
 /** TokenUsage from assistant/message.usage (dsh-llm TokenUsage). */
 export interface DshTokenUsage {
     inputTokens: number;
@@ -89,17 +83,6 @@ export interface DshModelSelection {
     model: string;
     reasoningEffort?: string;
 }
-/** session.models → value. */
-export interface DshSessionModelsValue {
-    current: DshModelSelection;
-    routable: boolean;
-    groups: DshModelGroup[];
-    failures?: Array<{
-        id: string;
-        name: string;
-        message: string;
-    }>;
-}
 /** One preset row of agentPreset.list. */
 export interface DshPresetEntry {
     id: string;
@@ -115,25 +98,6 @@ export interface DshPresetListValue {
     authorable: boolean;
     hasDocument: boolean;
 }
-/** Mux frame payloads we care about (subset of MuxFrame). */
-export type DshMuxFrame = {
-    type: 'session/event';
-    sessionId: string;
-    event: DshSessionEvent;
-} | {
-    type: 'approval/requested';
-    sessionId: string;
-    approvalId: string;
-    toolName: string;
-    callId?: string;
-    reason?: string;
-} | {
-    type: 'stream/error';
-    error: {
-        code: string;
-        message: string;
-    };
-};
 /** ServerRequest envelope (frame.method === frame.payload.type). */
 export interface DshServerRequest {
     type: 'server-request';

package/dist/runner/kimi/acp/runner.d.ts

@@ -44,11 +44,18 @@ export interface KimiAcpRunnerOptions {
      *  LLM 请求（引擎带重试），时长无上限，旧的固定 30s 轮询超时已删除。 */
     compactIdleTimeoutMs?: number;
     model?: string;
+    /**
+     * 思考强度（`low`|`high`|`max`，取值由 `KIMI_THINKING_EFFORTS` 校验）。
+     * 经 `session/set_config_option {configId:'thinking'}` 下发；不下发则跑
+     * kimi 服务端默认档（配置卡片存了也不生效）。
+     */
+    thinkingEffort?: string;
     /** Kimi permission mode (user-facing: manual/auto/yolo). */
     permissionMode?: 'manual' | 'auto' | 'yolo';
 }
 export declare class KimiAcpRunner extends BaseAcpRunner<KimiAcpTranslator> {
     private permissionMode;
+    private thinkingEffort?;
     private readonly compactIdleTimeoutMs;
     /**
      * §5.2 compaction baseline: wire.jsonl records sampled by compactBaseline()
@@ -70,7 +77,17 @@ export declare class KimiAcpRunner extends BaseAcpRunner<KimiAcpTranslator> {
     private bashToolCallIds;
     /** 当前 run 的 session cwd（terminal/create 未给 cwd 时回退用）。 */
     private activeCwd;
-    private readonly processStopper;
+    /**
+     * 终端子进程终止器（terminal/kill|release 与 dispose 清理用）。agent 必须是
+     * 'kimi'：win32 上优雅段靠协议停止通道，查错 key 会静默退化成直接树杀。
+     */
+    private readonly terminator;
+    /**
+     * shell seam：terminal/create 的可执行解析走这里（design.md §7.2）。kimi 的
+     * ACP 服务端固定要 `bash -c`，win32 上没有 Git Bash 时必须在 seam 里变成
+     * 明确错误，而不是一个语焉不详的 spawn ENOENT。
+     */
+    private readonly shell;
     constructor(opts: KimiAcpRunnerOptions);
     protected get logTag(): string;
     protected get turnTimeoutErrorMessage(): string;