lark-remote 0.4.5 → 0.5.1

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

@@ -61,7 +61,7 @@ export class JsonRpcClient {
      * Replace the per-run hooks (used by the runner to bridge
      * notifications/server requests into the active turn's translator).
      * Connection-layer hooks (slot cleanup / onConnectionLost) are preserved:
-     * review P2-1 — an overwrite here previously silenced onClose slot cleanup,
+     * an overwrite here previously silenced onClose slot cleanup,
      * leaving dead slots behind after the server process was killed.
      */
     setHooks(hooks) {

package/dist/runner/common/jsonrpc/connection-manager.d.ts

@@ -94,7 +94,7 @@ export declare class ConnectionManager<TClient extends ConnectionClient = JsonRp
     /** Callback when a connection is lost — cleared from slot map. */
     onConnectionLost?: (cwd: string) => void;
     /**
-     * 协议停止通道工厂（design §3.3）：连接建立后按 pid 登记到 AgentStopperRegistry，
+     * 协议停止通道工厂：连接建立后按 pid 登记到 AgentStopperRegistry，
      * 供 Terminator 在**优雅**停止时回调（win32 上没有可拦截的 SIGTERM，只能靠
      * 协议通道让 agent 自己收摊）。返回 undefined = 该协议无通道。
      *

package/dist/runner/common/jsonrpc/connection-manager.js

@@ -34,7 +34,7 @@ export class ConnectionManager {
     /** Callback when a connection is lost — cleared from slot map. */
     onConnectionLost;
     /**
-     * 协议停止通道工厂（design §3.3）：连接建立后按 pid 登记到 AgentStopperRegistry，
+     * 协议停止通道工厂：连接建立后按 pid 登记到 AgentStopperRegistry，
      * 供 Terminator 在**优雅**停止时回调（win32 上没有可拦截的 SIGTERM，只能靠
      * 协议通道让 agent 自己收摊）。返回 undefined = 该协议无通道。
      *

package/dist/runner/common/jsonrpc/transport.d.ts

@@ -42,7 +42,7 @@ export declare class JsonlRpcTransport {
         /** 终止器注入（测试用）；默认按平台建实现 */
         terminator?: Terminator;
         /**
-         * 协议停止通道工厂（design §3.3）：spawn 成功后按 pid 建通道并登记到
+         * 协议停止通道工厂：spawn 成功后按 pid 建通道并登记到
          * AgentStopperRegistry，进程退出/关闭时注销。返回 undefined = 无通道。
          */
         stopper?: (pid: number) => AgentStopper | undefined;

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

@@ -70,7 +70,7 @@ export class JsonlRpcTransport {
         // agent 是用户自己的可信二进制，provider 认证依赖 API key /
         // 自定义 provider 的 env_key，代理环境依赖 HTTP(S)_PROXY、TMPDIR 等；
         // 任何白名单收窄都会打断认证或网络。调用方 this.env 覆盖 process.env 同名键。
-        // env 覆盖必须大小写不敏感合并（win32 PATH/Path 双键防护，v2 §8.3）
+        // env 覆盖必须大小写不敏感合并（win32 PATH/Path 双键防护）
         const childEnv = mergeProcessEnv(process.env, this.env);
         const proc = spawnProcess(this.binary, this.args, {
             cwd: this.cwd,
@@ -195,7 +195,7 @@ export class JsonlRpcTransport {
         }
         try {
             // 入队后顺序 flush；write() 返回 false（高水位）时暂停直到 drain，
-            // 避免大消息/突发消息在 Node 内部无限缓冲（review P3-8）。
+            // 避免大消息/突发消息在 Node 内部无限缓冲。
             this.writeQueue.push(Buffer.from(JSON.stringify(msg) + '\n', 'utf8'));
             this.flush();
         }

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

@@ -4,7 +4,7 @@ import { type Terminator } from '../../platform/terminator.js';
 import { SpawnHeartbeat } from './spawn-heartbeat.js';
 import type { SpawnOptions } from '../types.js';
 /**
- * 进程级退出监听单例分发（P1-1 修复，2026-08-02）。
+ * 进程级退出监听单例分发（修复，2026-08-02）。
  *
  * 背景：各 agent runner 的 registerExitHandlers 曾是同构复制，每个实例
  * process.on('exit'|'SIGINT'|'SIGTERM') 注册 3 个永不移除的闭包（捕获整个
@@ -20,13 +20,26 @@ import type { SpawnOptions } from '../types.js';
 /**
  * Exit-cleanup contract: anything that spawns a child process group and wants
  * process-level cleanup (agent runners via SpawningRunner, and BashProcessRunner
- * for `!` commands, P1-22) registers with the singleton dispatcher.
+ * for `!` commands) registers with the singleton dispatcher.
  */
 interface ExitCleanupHandler {
     cleanupOnExit(): void;
 }
 /** Register a process-exit cleanup handler (installs listeners at most once). */
 export declare function registerExitCleanup(handler: ExitCleanupHandler): void;
+/**
+ * pid 文件名的 workspace 后缀：`-<消毒 cwd>-<cwd hash>`。
+ *
+ * 消毒段（非字母数字 → `_`）只是可读性；不同 cwd 可能消毒出同一段
+ * （`/w/a+b` 与 `/w/a_b`），而 killOrphan 的身份校验只比对二进制名——
+ * 不掺 hash 时两个 workspace 会共用同一个 pid 文件，启动时的孤儿回收
+ * 可能误杀对方 workspace 存活的同名 agent。hash 段按**原始 cwd** 计算，
+ * 与消毒无关，消除碰撞。消毒段截到 96 字符，深路径下给 MAX_PATH 留余量。
+ *
+ * 导出给测试/anchor 复用：任何「手工构造 runner 会写出的 pid 文件路径」的
+ * 代码都必须走这里，自己拼一份就是自造半迁移。
+ */
+export declare function pidFileSuffix(cwd: string): string;
 /** Remove a handler so it can be GC'd (agent slots / finished bash runs). */
 export declare function unregisterExitCleanup(handler: ExitCleanupHandler): void;
 /**
@@ -119,12 +132,12 @@ export declare abstract class SpawningRunner {
     protected getStdio(): ('ignore' | 'pipe')[];
     /**
      * Create an async iterator over the child's stdout. Default: createJSONLStream
-     * with P1-4 backpressure enabled (pauseThreshold=100).
+     * withbackpressure enabled (pauseThreshold=100).
      */
     protected createStreamReader(stdout: Readable): AsyncGenerator<unknown>;
     /**
      * Await the spawn 'error' event when proc.pid === undefined. Races a
-     * finite timeout (review P2-11) against the 'error' event: Node guarantees
+     * finite timeout against the 'error' event: Node guarantees
      * 'error' for ENOENT/EACCES, but some binaries fail silently without ever
      * emitting it. Without the race, the spawn lead-in hangs forever → the
      * cwd serial queue never settles → permanent deadlock, and /stop
@@ -143,7 +156,7 @@ export declare abstract class SpawningRunner {
      */
     protected spawnChild(opts: SpawnOptions): Promise<ChildProcess>;
     /**
-     * 登记本进程的协议停止通道（design §3.3 表）：win32 上没有可拦截的跨进程
+     * 登记本进程的协议停止通道：win32 上没有可拦截的跨进程
      * SIGTERM，「优雅停止」只能经 agent 自有通道请求对方自行退出。stdio 型 agent
      * CLI 的通道就是关 stdin（cc-connect 已验证 claude：关 stdin → 干净退出并跑
      * Stop hooks）。
@@ -166,12 +179,12 @@ export declare abstract class SpawningRunner {
         immediate?: boolean;
     }): Promise<void>;
     /**
-     * P1-10: 杀掉上一次崩溃留下的孤儿 agent 进程。**身份校验是动手的前置条件**：
+     * 杀掉上一次崩溃留下的孤儿 agent 进程。**身份校验是动手的前置条件**：
      * pid 文件里的 pid 可能已被系统回收给无关进程，`kill(pid, 0)` 存活探测分不出来。
      *
      * 判定单源 = `platform/identity`（posix `ps -o command=` / win32 CIM），三态：
      *   - match    → 杀整个进程组（detached:true 下 agent 是组长，与 Terminator
-     *                posix 路径的 kill(-pid) 同语义，P1-12 子进程不孤儿化）；
+     *                posix 路径的 kill(-pid) 同语义，子进程不孤儿化）；
      *   - mismatch → pid 已被无关进程占用：绝不杀，文件是陈旧垃圾，清除自愈；
      *   - unknown  → 查不到身份（ps 不可用/超时/CIM 被拒）：同样不杀，清文件。
      * 统一原则：只有身份匹配才杀，验证失败一律不杀（fail-closed）。
@@ -198,7 +211,7 @@ export declare abstract class SpawningRunner {
     unregisterExitHandlers(): void;
     /**
      * Current number of runners registered with the process-level exit
-     * dispatcher. Diagnostics / test-support introspection (P1-1 anchor asserts
+     * dispatcher. Diagnostics / test-support introspection (asserts
      * the count returns to baseline after bridge eviction).
      */
     static getRegisteredExitHandlerCount(): number;

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

@@ -11,7 +11,7 @@ import { SpawnHeartbeat } from './spawn-heartbeat.js';
 import { createJSONLStream } from './jsonl-stream.js';
 import { DEFAULT_STOP_GRACE_MS } from '../../config/index.js';
 /**
- * Magic-number constants (Clean Code P3-1, G25 Replace Magic Numbers with
+ * Magic-number constants (Clean Code G25 Replace Magic Numbers with
  * Named Constants). Centralized here so the truncation budgets are visible
  * and adjustable in one place rather than scattered as raw literals.
  */
@@ -22,7 +22,7 @@ class SpawnChildError extends Error {
 }
 /**
  * Timeout (ms) for awaiting the spawn 'error' event when proc.pid === undefined
- * (review P2-11). Node guarantees 'error' for ENOENT/EACCES, but some binaries
+ * Node guarantees 'error' for ENOENT/EACCES, but some binaries
  * fail silently; the race keeps a silent failure from hanging the spawn lead-in
  * forever. Matches the 5s race kimi's override used before it was hoisted to
  * the base.
@@ -54,6 +54,33 @@ export function registerExitCleanup(handler) {
     installExitListenersOnce();
     registeredRunners.add(handler);
 }
+/**
+ * FNV-1a 32 位哈希（hex，平台无关确定性）：pid 文件后缀的消歧段。
+ */
+function fnv1aHex(text) {
+    let hash = 0x811c9dc5;
+    for (let i = 0; i < text.length; i++) {
+        hash ^= text.charCodeAt(i);
+        hash = Math.imul(hash, 0x01000193);
+    }
+    return (hash >>> 0).toString(16).padStart(8, '0');
+}
+/**
+ * pid 文件名的 workspace 后缀：`-<消毒 cwd>-<cwd hash>`。
+ *
+ * 消毒段（非字母数字 → `_`）只是可读性；不同 cwd 可能消毒出同一段
+ * （`/w/a+b` 与 `/w/a_b`），而 killOrphan 的身份校验只比对二进制名——
+ * 不掺 hash 时两个 workspace 会共用同一个 pid 文件，启动时的孤儿回收
+ * 可能误杀对方 workspace 存活的同名 agent。hash 段按**原始 cwd** 计算，
+ * 与消毒无关，消除碰撞。消毒段截到 96 字符，深路径下给 MAX_PATH 留余量。
+ *
+ * 导出给测试/anchor 复用：任何「手工构造 runner 会写出的 pid 文件路径」的
+ * 代码都必须走这里，自己拼一份就是自造半迁移。
+ */
+export function pidFileSuffix(cwd) {
+    const sanitized = cwd.replace(/[^a-zA-Z0-9]/g, '_').slice(0, 96);
+    return `-${sanitized}-${fnv1aHex(cwd)}`;
+}
 /** Remove a handler so it can be GC'd (agent slots / finished bash runs). */
 export function unregisterExitCleanup(handler) {
     registeredRunners.delete(handler);
@@ -120,9 +147,8 @@ export class SpawningRunner {
         this.logTag = opts.logTag ?? 'spawning-runner';
         this.agent = opts.agent;
         const pidDir = opts.pidDir ?? path.join(os.homedir(), '.lark-remote');
-        const workspaceSuffix = `-${opts.cwd.replace(/[^a-zA-Z0-9]/g, '_')}`;
         const pidFilePrefix = opts.pidFilePrefix ?? 'spawning';
-        this.pidFilePath = path.join(pidDir, `${pidFilePrefix}${workspaceSuffix}.pid`);
+        this.pidFilePath = path.join(pidDir, `${pidFilePrefix}${pidFileSuffix(opts.cwd)}.pid`);
         this.terminator =
             opts.terminator ?? createTerminator({ graceMs: this.stopGraceMs, agent: opts.agent });
         this.spawnHeartbeat = new SpawnHeartbeat(opts.spawnHeartbeatMs ?? 30_000, this.logTag);
@@ -142,7 +168,7 @@ export class SpawningRunner {
     }
     /**
      * Create an async iterator over the child's stdout. Default: createJSONLStream
-     * with P1-4 backpressure enabled (pauseThreshold=100).
+     * withbackpressure enabled (pauseThreshold=100).
      */
     createStreamReader(stdout) {
         return createJSONLStream(stdout, {
@@ -155,7 +181,7 @@ export class SpawningRunner {
     }
     /**
      * Await the spawn 'error' event when proc.pid === undefined. Races a
-     * finite timeout (review P2-11) against the 'error' event: Node guarantees
+     * finite timeout against the 'error' event: Node guarantees
      * 'error' for ENOENT/EACCES, but some binaries fail silently without ever
      * emitting it. Without the race, the spawn lead-in hangs forever → the
      * cwd serial queue never settles → permanent deadlock, and /stop
@@ -203,7 +229,7 @@ export class SpawningRunner {
             }
             this.currentProcess = null;
             this.spawnHeartbeat.clear();
-            // P2-13: surface the real spawn error cause instead of a fixed "binary
+            // surface the real spawn error cause instead of a fixed "binary
             // not found" message. ENOENT (binary missing) keeps the friendly hint,
             // but EMFILE/EACCES/ENOMEM/bad-cwd failures must name the actual reason
             // so the user is not misdiagnosed into reinstalling the binary.
@@ -219,7 +245,7 @@ export class SpawningRunner {
         proc.stdout?.once('data', () => {
             this.spawnHeartbeat.notifyStdout();
         });
-        // 协议停止通道登记（design §3.3）：子进程起来后立刻登记，win32 上
+        // 协议停止通道登记：子进程起来后立刻登记，win32 上
         // Terminator 停这个 pid 时才能取到通道；进程退出/被停后注销。
         this.registerStopper(proc);
         this.spawnStderr = '';
@@ -235,7 +261,7 @@ export class SpawningRunner {
                     this.commandNotFoundSeen = true;
                     getLogger().error(`[${this.logTag}] command not found suspected (win32 shim): ${text}`);
                 }
-                // P2-16: most agent CLIs emit progress/warnings/deprecation notices on
+                // most agent CLIs emit progress/warnings/deprecation notices on
                 // stderr, not real errors. Logging each chunk at error level drowns out
                 // genuine errors. Downgrade to warn — the accumulated stderr is already
                 // surfaced at error level in the non-zero-exit result path.
@@ -245,7 +271,7 @@ export class SpawningRunner {
         return proc;
     }
     /**
-     * 登记本进程的协议停止通道（design §3.3 表）：win32 上没有可拦截的跨进程
+     * 登记本进程的协议停止通道：win32 上没有可拦截的跨进程
      * SIGTERM，「优雅停止」只能经 agent 自有通道请求对方自行退出。stdio 型 agent
      * CLI 的通道就是关 stdin（cc-connect 已验证 claude：关 stdin → 干净退出并跑
      * Stop hooks）。
@@ -302,12 +328,12 @@ export class SpawningRunner {
         getLogger().debug(`[${this.logTag}] cleaned pid file ${this.pidFilePath}`);
     }
     /**
-     * P1-10: 杀掉上一次崩溃留下的孤儿 agent 进程。**身份校验是动手的前置条件**：
+     * 杀掉上一次崩溃留下的孤儿 agent 进程。**身份校验是动手的前置条件**：
      * pid 文件里的 pid 可能已被系统回收给无关进程，`kill(pid, 0)` 存活探测分不出来。
      *
      * 判定单源 = `platform/identity`（posix `ps -o command=` / win32 CIM），三态：
      *   - match    → 杀整个进程组（detached:true 下 agent 是组长，与 Terminator
-     *                posix 路径的 kill(-pid) 同语义，P1-12 子进程不孤儿化）；
+     *                posix 路径的 kill(-pid) 同语义，子进程不孤儿化）；
      *   - mismatch → pid 已被无关进程占用：绝不杀，文件是陈旧垃圾，清除自愈；
      *   - unknown  → 查不到身份（ps 不可用/超时/CIM 被拒）：同样不杀，清文件。
      * 统一原则：只有身份匹配才杀，验证失败一律不杀（fail-closed）。
@@ -343,7 +369,7 @@ export class SpawningRunner {
                 return;
             }
             // 身份匹配：杀整个进程组（detached:true 下 agent 是组长），与
-            // Terminator 的 kill(-pid) 语义对齐，子进程不会孤儿化（P1-12）。
+            // Terminator 的 kill(-pid) 语义对齐，子进程不会孤儿化。
             getLogger().info(`[${this.logTag}] killing orphan process group ${-pid}`);
             try {
                 process.kill(-pid, 'SIGTERM');
@@ -377,7 +403,7 @@ export class SpawningRunner {
     }
     /**
      * Current number of runners registered with the process-level exit
-     * dispatcher. Diagnostics / test-support introspection (P1-1 anchor asserts
+     * dispatcher. Diagnostics / test-support introspection (asserts
      * the count returns to baseline after bridge eviction).
      */
     static getRegisteredExitHandlerCount() {
@@ -392,7 +418,7 @@ export class SpawningRunner {
     cleanupOnExit() {
         if (this.currentProcess && this.currentProcess.exitCode === null) {
             try {
-                // P1-12: 只杀组长会让组内子进程（工具调用起的后台进程）reparent 成孤儿。
+                // 只杀组长会让组内子进程（工具调用起的后台进程）reparent 成孤儿。
                 // Terminator.cleanupOnExit 在两种平台上都是「fire-and-forget 强杀整个
                 // 进程组/进程树」（posix kill(-pgid, SIGKILL) / win32 taskkill /T /F），
                 // 退出路径上无法等待，也不需要优雅段。

package/dist/runner/dsh/runner.js

@@ -67,7 +67,7 @@ export class DshRunner {
         let sessionId = opts.sessionId;
         let terminalEmitted = false;
         try {
-            // CC-03: session.create 必须包进同一 try/finally，否则创建失败（服务端不可达/报错）
+            // session.create 必须包进同一 try/finally，否则创建失败（服务端不可达/报错）
             // 会在进入旧 try 之前抛异常，finally 不执行 → running 恒 true、activeAbort 残留。
             if (!sessionId) {
                 const created = await this.client.createSession({
@@ -188,7 +188,7 @@ export class DshRunner {
             }
         }
         catch (err) {
-            // CC-03: createSession 等启动期失败也产出 error result（而非抛异常），
+            // createSession 等启动期失败也产出 error result（而非抛异常），
             // 由本 catch 统一转 error result；state 清理在 finally。
             if (!abort.signal.aborted) {
                 yield {

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

@@ -83,7 +83,7 @@ export declare class KimiAcpRunner extends BaseAcpRunner<KimiAcpTranslator> {
      */
     private readonly terminator;
     /**
-     * shell seam：terminal/create 的可执行解析走这里（design.md §7.2）。kimi 的
+     * shell seam：terminal/create 的可执行解析走这里。kimi 的
      * ACP 服务端固定要 `bash -c`，win32 上没有 Git Bash 时必须在 seam 里变成
      * 明确错误，而不是一个语焉不详的 spawn ENOENT。
      */
@@ -105,7 +105,7 @@ export declare class KimiAcpRunner extends BaseAcpRunner<KimiAcpTranslator> {
      * before producing the result. There is NO total timeout — silence beyond
      * compactIdleTimeoutMs yields 'unknown' (never a fake success). Keeps the
      * connection alive while the background compaction finishes — otherwise
-     * dispose/exit kills it and the record never lands (S5/S6 打回复现 /
+     * dispose/exit kills it and the record never lands (打回复现 /
      * 2026-08-31 事故).
      */
     protected compactBaseline(sessionId: string, opts: SpawnOptions): number;
@@ -113,7 +113,7 @@ export declare class KimiAcpRunner extends BaseAcpRunner<KimiAcpTranslator> {
     protected buildApprovalOutcome(action: string, pending: AcpPendingApproval, response: unknown): unknown;
     getStatusInfo(): AgentStatusInfo;
     /**
-     * Hot-apply a permission-mode change to the live ACP session (§P5).
+     * Hot-apply a permission-mode change to the live ACP session.
      *
      * The local cache is always updated so `getStatusInfo()` (and therefore
      * `/s`) reflects the new mode immediately. When a session is connected,

package/dist/runner/kimi/acp/runner.js

@@ -163,7 +163,7 @@ export class KimiAcpRunner extends BaseAcpRunner {
      */
     terminator = createTerminator({ graceMs: 2_000, agent: 'kimi' });
     /**
-     * shell seam：terminal/create 的可执行解析走这里（design.md §7.2）。kimi 的
+     * shell seam：terminal/create 的可执行解析走这里。kimi 的
      * ACP 服务端固定要 `bash -c`，win32 上没有 Git Bash 时必须在 seam 里变成
      * 明确错误，而不是一个语焉不详的 spawn ENOENT。
      */
@@ -224,7 +224,7 @@ export class KimiAcpRunner extends BaseAcpRunner {
         return new KimiAcpTranslator();
     }
     async applyTurnSettings(client, sessionId) {
-        // CC-07: 下发配置的模型（provider/model）。session/new|resume 只带 cwd/mcpServers，
+        // 下发配置的模型（provider/model）。session/new|resume 只带 cwd/mcpServers，
         // 不带 model；不主动下发则实际跑 kimi 服务端默认模型。
         // 仿 opencode 用 session/set_config_option。失败仅告警不阻断。
         if (this.model) {
@@ -239,7 +239,7 @@ export class KimiAcpRunner extends BaseAcpRunner {
                 getLogger().warn(`[${this.logTag}] set_config_option model failed (non-fatal): ${err.message}`);
             }
         }
-        // A5: 下发配置的思考强度。configId 与取值不是猜的——kimi 真机（0.43.1）
+        // 下发配置的思考强度。configId 与取值不是猜的——kimi 真机（0.43.1）
         // `session/new` 就通告 `{id:'thinking', category:'thought_level',
         // options:[low|high|max]}`，set 成功后响应里 `currentValue` 变成新值；
         // 未知 configId / 非法取值回 -32602（不静默接受），所以失败告警即可判定。
@@ -283,7 +283,7 @@ export class KimiAcpRunner extends BaseAcpRunner {
      * before producing the result. There is NO total timeout — silence beyond
      * compactIdleTimeoutMs yields 'unknown' (never a fake success). Keeps the
      * connection alive while the background compaction finishes — otherwise
-     * dispose/exit kills it and the record never lands (S5/S6 打回复现 /
+     * dispose/exit kills it and the record never lands (打回复现 /
      * 2026-08-31 事故).
      */
     compactBaseline(sessionId, opts) {
@@ -300,7 +300,7 @@ export class KimiAcpRunner extends BaseAcpRunner {
         const baselineTerminalCount = this.compactBaselineRecords.filter(isCompactionTerminalLike).length;
         let promptRejected = false;
         // prompt 结算只供两样东西：成功 result 的翻译素材（stopReason/usage）与 §5.4
-        // 探针。终态判定不再挂在它后面（A7）。
+        // 探针。终态判定不再挂在它后面。
         const promptSettled = promptPromise.then((result) => {
             this.promptSettled = true;
             if (compactionReader) {
@@ -326,7 +326,7 @@ export class KimiAcpRunner extends BaseAcpRunner {
             });
             return;
         }
-        // A7：语义等待在 prompt 触发的那一刻武装。引擎静默超过 compactIdleTimeoutMs
+        // 语义等待在 prompt 触发的那一刻武装。引擎静默超过 compactIdleTimeoutMs
         // 就给出 compact 语义终态，不等 session/prompt 结算——否则挂住的 prompt 会把
         // 用户拖到通用 turnIdleTimeout（默认 30min），拿到的还是一个语义泛化的 turn
         // 超时，而不是「压缩状态未知 / 可重试」。
@@ -372,7 +372,7 @@ export class KimiAcpRunner extends BaseAcpRunner {
         };
     }
     /**
-     * Hot-apply a permission-mode change to the live ACP session (§P5).
+     * Hot-apply a permission-mode change to the live ACP session.
      *
      * The local cache is always updated so `getStatusInfo()` (and therefore
      * `/s`) reflects the new mode immediately. When a session is connected,
@@ -553,14 +553,14 @@ export class KimiAcpRunner extends BaseAcpRunner {
             : undefined;
         const cwd = params.cwd ?? this.activeCwd ?? undefined;
         const outputLimit = params.outputByteLimit ?? TERMINAL_DEFAULT_OUTPUT_LIMIT;
-        // 走 shell seam（design.md §7.2）：argv 逐 token 保留，只把「可执行文件在哪」
+        // 走 shell seam：argv 逐 token 保留，只把「可执行文件在哪」
         // 收口——win32 上 Git Bash 缺失时在这里抛 ShellUnavailableError，由
         // handleTerminalRequest 转成明确的 Terminal request failed 回执，而不是一个
         // 语焉不详的 spawn ENOENT。
         const proc = this.shell.spawnArgv(params.command, params.args ?? [], {
             cwd,
             options: {
-                // env 覆盖大小写不敏感合并（win32 PATH/Path 双键防护，v2 §8.3）
+                // env 覆盖大小写不敏感合并（win32 PATH/Path 双键防护）
                 env: env ? mergeProcessEnv(process.env, env) : undefined,
                 stdio: ['ignore', 'pipe', 'pipe'],
                 // Terminator 用负 PID 杀进程组（kill(-pgid)）；子进程必须是组长

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

@@ -8,12 +8,12 @@
  * accumulates text/thinking deltas and emits turn_diff snapshots (NOT
  * assistant deltas — see handleAgentMessageChunk), plus question elicitation.
  *
- * Wire envelope (R1, source: kimi-code packages/acp-server/src/events-map.ts,
+ * Wire envelope (source: kimi-code packages/acp-server/src/events-map.ts,
  * verified live 2026-08-15/16 against kimi 0.36.0):
  *   session/update params = {sessionId, update: {sessionUpdate: '<kind>', ...}}
  *   — the discriminator is `update.sessionUpdate`, NOT a nested `event.type`.
  *
- * Event mapping (design doc §4.2):
+ * Event mapping:
  *   agent_message_chunk   → turn_diff text snapshot (content.text accumulation)
  *   agent_thought_chunk   → turn_diff reasoning snapshot (content.text accumulation)
  *   tool_call / tool_call_update / usage_update / plan / control-plane noise →

package/dist/runner/kimi/acp/translator.js

@@ -8,12 +8,12 @@
  * accumulates text/thinking deltas and emits turn_diff snapshots (NOT
  * assistant deltas — see handleAgentMessageChunk), plus question elicitation.
  *
- * Wire envelope (R1, source: kimi-code packages/acp-server/src/events-map.ts,
+ * Wire envelope (source: kimi-code packages/acp-server/src/events-map.ts,
  * verified live 2026-08-15/16 against kimi 0.36.0):
  *   session/update params = {sessionId, update: {sessionUpdate: '<kind>', ...}}
  *   — the discriminator is `update.sessionUpdate`, NOT a nested `event.type`.
  *
- * Event mapping (design doc §4.2):
+ * Event mapping:
  *   agent_message_chunk   → turn_diff text snapshot (content.text accumulation)
  *   agent_thought_chunk   → turn_diff reasoning snapshot (content.text accumulation)
  *   tool_call / tool_call_update / usage_update / plan / control-plane noise →
@@ -53,7 +53,7 @@ export class KimiAcpTranslator extends BaseAcpTranslator {
         // Use a stable key for the current text stream. Kimi ACP doesn't
         // provide an itemId in agent_message_chunk; we use 'text' as the
         // single logical text accumulator (one text stream per turn).
-        // R1: wire chunk text lives at content.text and is a DELTA
+        // wire chunk text lives at content.text and is a DELTA
         // (kimi-code events-map.ts assistantDeltaToSessionUpdate:
         // content.text = event.delta), so we accumulate here into a full-text
         // snapshot and emit it as turn_diff. The card reducer's turn_diff path
@@ -145,7 +145,7 @@ export class KimiAcpTranslator extends BaseAcpTranslator {
                     : summary
                         ? truncateWithEllipsis(summary, 200)
                         : undefined,
-            // §P4: 从服务端 options kind 派生——带 approve_always（或 allow_always）
+            // 从服务端 options kind 派生——带 approve_always（或 allow_always）
             // 才提供「本会话总是允许」（acceptForSession）；否则与旧行为一致。
             availableDecisions: deriveAcpAvailableDecisions(params.options ?? []),
         };

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

@@ -51,7 +51,7 @@ export interface OpencodeAcpRunnerOptions {
     errorMonitorPollIntervalMs?: number;
 }
 export declare class OpencodeAcpRunner extends BaseAcpRunner<OpencodeAcpTranslator> {
-    /** Configured session mode applied via session/set_mode (§P5). */
+    /** Configured session mode applied via session/set_mode. */
     private configuredMode;
     /** Current session mode id, parsed from session/new|resume configOptions. */
     private currentModeId?;
@@ -86,7 +86,7 @@ export declare class OpencodeAcpRunner extends BaseAcpRunner<OpencodeAcpTranslat
     protected buildApprovalOutcome(action: string, pending: AcpPendingApproval, _response: unknown): unknown;
     getStatusInfo(): AgentStatusInfo;
     /**
-     * Hot-apply a mode change to the live ACP session (§P5).
+     * Hot-apply a mode change to the live ACP session.
      *
      * opencode's session/set_mode sends no notification — the client refreshes
      * the local mode view itself. The local mode is always updated so

package/dist/runner/opencode/acp/runner.js

@@ -30,7 +30,7 @@ import { OpencodeLogErrorMonitor, resolveOpencodeLogPath } from './error-monitor
 // Runner
 // =============================================================================
 export class OpencodeAcpRunner extends BaseAcpRunner {
-    /** Configured session mode applied via session/set_mode (§P5). */
+    /** Configured session mode applied via session/set_mode. */
     configuredMode;
     /** Current session mode id, parsed from session/new|resume configOptions. */
     currentModeId;
@@ -103,7 +103,7 @@ export class OpencodeAcpRunner extends BaseAcpRunner {
         return new OpencodeAcpTranslator();
     }
     async applyTurnSettings(client, sessionId) {
-        // §P5: apply the configured mode (build/plan). If the session already
+        // apply the configured mode (build/plan). If the session already
         // runs it (from session/new|resume configOptions), skip the wire call;
         // otherwise send session/set_mode and refresh the local view (opencode
         // sends no notification for set_mode).
@@ -160,7 +160,7 @@ export class OpencodeAcpRunner extends BaseAcpRunner {
         };
     }
     /**
-     * Hot-apply a mode change to the live ACP session (§P5).
+     * Hot-apply a mode change to the live ACP session.
      *
      * opencode's session/set_mode sends no notification — the client refreshes
      * the local mode view itself. The local mode is always updated so

package/dist/runner/opencode/acp/translator.js

@@ -176,7 +176,7 @@ export class OpencodeAcpTranslator extends BaseAcpTranslator {
             kind: 'command',
             command: params.toolCall.title ?? undefined,
             reason: rawInput ? truncateWithEllipsis(stringify(rawInput), 200) : undefined,
-            // §P4: 从服务端 options kind 派生——带 allow_always（或 approve_always）
+            // 从服务端 options kind 派生——带 allow_always（或 approve_always）
             // 才提供「本会话总是允许」（acceptForSession）。
             availableDecisions: deriveAcpAvailableDecisions(params.options ?? []),
         };

package/dist/runner/pi/rpc/runner.js

@@ -53,7 +53,7 @@ export class PiRpcRunner extends ConnectionBasedRunner {
             idleTtlMs: opts.idleTtlMs,
             logTag: 'pi-rpc-connection-manager',
         });
-        // 协议停止通道（design §3.3）：pi 的 cancel 是 `{type:'abort'}` 通知，已由
+        // 协议停止通道：pi 的 cancel 是 `{type:'abort'}` 通知，已由
         // cancelCurrentTurn 实现；登记后 win32 优雅停止才有通道可用（否则一路树杀）。
         this.manager.stopper = ({ client }) => this.buildCooperativeStop(client);
     }
@@ -139,7 +139,7 @@ export class PiRpcRunner extends ConnectionBasedRunner {
         this.promptSettled = false;
         const response = await client.request({ type: 'prompt', message });
         if (!response.success) {
-            // CC-08: pi 返回 success:false（无效模型/provider 错误/忙）时立即失败，
+            // pi 返回 success:false（无效模型/provider 错误/忙）时立即失败，
             // 不能当成成功 ACK 继续等 agent_settled（否则最长 turn idle timeout）。
             throw new Error(`pi prompt failed: ${response.error ?? 'unknown error'}`);
         }

package/dist/runner/pi/rpc/translator.d.ts

@@ -32,7 +32,7 @@ export declare class PiRpcTranslator {
     private accReasoning;
     private lastTotalTokens;
     private hasUsage;
-    /** toolcall_start bookkeeping：占位不发事件，end 时补发完整 tool_use（C3.4）。 */
+    /** toolcall_start bookkeeping：占位不发事件，end 时补发完整 tool_use。 */
     private pendingToolCall;
     /** Provider failure (stopReason="error") on the final assistant message. */
     private lastAssistantStopReason;

package/dist/runner/pi/rpc/translator.js

@@ -23,7 +23,7 @@ export class PiRpcTranslator {
     accReasoning = 0;
     lastTotalTokens;
     hasUsage = false;
-    /** toolcall_start bookkeeping：占位不发事件，end 时补发完整 tool_use（C3.4）。 */
+    /** toolcall_start bookkeeping：占位不发事件，end 时补发完整 tool_use。 */
     pendingToolCall = false;
     /** Provider failure (stopReason="error") on the final assistant message. */
     lastAssistantStopReason;
@@ -98,7 +98,7 @@ export class PiRpcTranslator {
                 return [];
             }
             case 'compaction_start': {
-                // 信息保真 C3.4：压缩过程用户可见（info 通知），不再静默。
+                // 信息保真 压缩过程用户可见（info 通知），不再静默。
                 const c = evt;
                 return [
                     {
@@ -125,7 +125,7 @@ export class PiRpcTranslator {
             }
             default:
                 // turn_start/turn_end, agent_start/agent_end, tool_execution_*, and
-                // unknown types are ignored. (compaction_start/end 自 C3.4 起映射为
+                // unknown types are ignored. (compaction_start/end 映射为
                 // notice 事件，不再静默。)
                 return [];
         }
@@ -269,7 +269,7 @@ export class PiRpcTranslator {
                 }
                 break;
             case 'toolcall_start':
-                // 信息保真 C3.4：不再 push 空壳 tool_use（空 id/name 会被渲染成
+                // 信息保真 不再 push 空壳 tool_use（空 id/name 会被渲染成
                 // 无意义工具块）。只保留 bookkeeping，toolcall_end 补发完整事件。
                 this.pendingToolCall = true;
                 break;

package/dist/runner/types.d.ts

@@ -395,14 +395,23 @@ export interface Runner {
     killOrphan(): void;
     registerExitHandlers(): void;
     /**
-     * Remove the runner from the process-level exit dispatcher (P1-1). Called by
+     * Remove the runner from the process-level exit dispatcher. Called by
      * the bridge when the (cwd, kind) cache slot is evicted so the instance is
      * not retained by the singleton dispatcher. Optional so test stubs that only
      * satisfy `registerExitHandlers` remain structurally valid.
      */
     unregisterExitHandlers?(): void;
 }
-export type AgentKind = 'claude' | 'codex' | 'opencode' | 'pi' | 'kimi' | 'dsh';
+/**
+ * Agent 名单单源（运行时数组 + 类型同源，二者不可能漂移）。
+ *
+ * 历史上这份名单被手抄成多份（router 的 VALID_AGENTS、bridge 的 resume.compact
+ * 校验、各 agent 的 config builder…），漂移过：dsh 加入后 bridge 的
+ * resume.compact 仍只有 5 个，带 dsh 的 resume 卡片会静默退回 defaultAgent。
+ * 新增 agent 只改这里。
+ */
+export declare const AGENT_KINDS: readonly ["claude", "codex", "opencode", "pi", "kimi", "dsh"];
+export type AgentKind = (typeof AGENT_KINDS)[number];
 /** Unified session descriptor returned by every AgentSessionReader. */
 export interface AgentSession {
     sessionId: string;