lark-remote 0.4.4 → 0.5.0

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;
 /**
@@ -86,7 +99,7 @@ export declare abstract class SpawningRunner {
     private stopperRegistration;
     constructor(opts: {
         pidDir?: string;
-        workspace: string;
+        cwd: string;
         stopGraceMs?: number;
         spawnHeartbeatMs?: number;
         /**
@@ -119,15 +132,15 @@ 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
-     * workspace serial queue never settles → permanent deadlock, and /stop
+     * cwd serial queue never settles → permanent deadlock, and /stop
      * can't recover (Terminator.stop returns early when pid === undefined).
      * The timeout keeps the deadlock bounded.
      */
@@ -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

@@ -2,7 +2,7 @@ import { spawnProcess, isWindowsCommandNotFoundLine, useDetachedProcessGroup, }
 import path from 'node:path';
 import os from 'node:os';
 import fs from 'node:fs';
-import { silentlyUnlink } from '../../common/fs.js';
+import { bestEffortUnlink } from '../../common/fs.js';
 import { getLogger } from '../../logger/index.js';
 import { binaryName, verifyPidIdentityVerdictSync } from '../../platform/identity.js';
 import { createTerminator } from '../../platform/terminator.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.workspace.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,10 +181,10 @@ 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
-     * workspace serial queue never settles → permanent deadlock, and /stop
+     * cwd serial queue never settles → permanent deadlock, and /stop
      * can't recover (Terminator.stop returns early when pid === undefined).
      * The timeout keeps the deadlock bounded.
      */
@@ -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）。
@@ -298,16 +324,16 @@ export class SpawningRunner {
         // （immediate 路径不查表，但一并注销同样正确——进程已进入终止流程）。
         this.unregisterStopper();
         this.currentProcess = null;
-        silentlyUnlink(this.pidFilePath);
+        bestEffortUnlink(this.pidFilePath);
         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）。
@@ -324,7 +350,7 @@ export class SpawningRunner {
             const pidStr = fs.readFileSync(this.pidFilePath, 'utf-8').trim();
             const pid = Number(pidStr);
             if (isNaN(pid) || pid <= 0) {
-                silentlyUnlink(this.pidFilePath);
+                bestEffortUnlink(this.pidFilePath);
                 return;
             }
             const expectedBinary = binaryName(this.binary);
@@ -339,11 +365,11 @@ export class SpawningRunner {
             if (verdict !== 'match') {
                 getLogger().warn(`[${this.logTag}] killOrphan: pid ${pid} not confirmed as ${expectedBinary} ` +
                     `(${verdict}), skipping kill`);
-                silentlyUnlink(this.pidFilePath);
+                bestEffortUnlink(this.pidFilePath);
                 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');
@@ -351,7 +377,7 @@ export class SpawningRunner {
             catch {
                 // process may have exited
             }
-            silentlyUnlink(this.pidFilePath);
+            bestEffortUnlink(this.pidFilePath);
         }
         catch {
             // ignore
@@ -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），
                 // 退出路径上无法等待，也不需要优雅段。
@@ -401,7 +427,7 @@ export class SpawningRunner {
             catch { }
         }
         this.unregisterStopper();
-        silentlyUnlink(this.pidFilePath);
+        bestEffortUnlink(this.pidFilePath);
     }
 }
 //# sourceMappingURL=spawning-runner.js.map

package/dist/runner/common/{runner-utils.d.ts → synthetic-events.d.ts}

@@ -12,10 +12,10 @@ import type { AgentEvent } from '../types.js';
  */
 export declare function syntheticInitEvent(sessionId?: string): AgentEvent;
 /**
- * Build a standardized auth/error result event for yield.
+ * Build a standardized setup-failure result event for yield.
  *
- * Used when initialization or request sending fails (e.g. not logged in,
- * session creation failed). Produces a
+ * Used when setup fails before a turn can run — process spawn errors
+ * (e.g. ENOENT), not-logged-in, or session creation failure. Produces a
  * `result`/`error` event so the bridge can render a card instead of crashing.
  */
-export declare function authErrorEvent(errorMessage: string, sessionId?: string): AgentEvent;
+export declare function setupErrorEvent(errorMessage: string, sessionId?: string): AgentEvent;

package/dist/runner/common/{runner-utils.js → synthetic-events.js}

@@ -20,13 +20,13 @@ export function syntheticInitEvent(sessionId = '') {
     };
 }
 /**
- * Build a standardized auth/error result event for yield.
+ * Build a standardized setup-failure result event for yield.
  *
- * Used when initialization or request sending fails (e.g. not logged in,
- * session creation failed). Produces a
+ * Used when setup fails before a turn can run — process spawn errors
+ * (e.g. ENOENT), not-logged-in, or session creation failure. Produces a
  * `result`/`error` event so the bridge can render a card instead of crashing.
  */
-export function authErrorEvent(errorMessage, sessionId = '') {
+export function setupErrorEvent(errorMessage, sessionId = '') {
     return {
         type: 'result',
         subtype: 'error',
@@ -35,4 +35,4 @@ export function authErrorEvent(errorMessage, sessionId = '') {
         timestamp: new Date().toISOString(),
     };
 }
-//# sourceMappingURL=runner-utils.js.map
+//# sourceMappingURL=synthetic-events.js.map

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

@@ -86,7 +86,7 @@ export declare class DshClient {
      * `session.history` to fill the gap (dedup by seq). Terminates on turn/end
      * or `signal` abort.
      */
-    sessionEvents(sessionId: string, cwd: string, signal: AbortSignal, initialSeq?: number): AsyncGenerator<DshStreamItem>;
+    sessionEvents(sessionId: string, signal: AbortSignal, initialSeq?: number): AsyncGenerator<DshStreamItem>;
     /** Extract TokenUsage from an assistant/message data payload (absent → undefined). */
     static usageOf(data: Record<string, unknown>): DshTokenUsage | undefined;
 }

package/dist/runner/dsh/client.js

@@ -320,7 +320,7 @@ export class DshClient {
      * `session.history` to fill the gap (dedup by seq). Terminates on turn/end
      * or `signal` abort.
      */
-    async *sessionEvents(sessionId, cwd, signal, initialSeq = -1) {
+    async *sessionEvents(sessionId, signal, initialSeq = -1) {
         const state = { lastSeq: initialSeq };
         // Initial baseline: before opening the first live mux subscription, replay
         // history once so events produced between prompt-accept and the mux opening

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({
@@ -135,7 +135,7 @@ export class DshRunner {
                 });
                 const translator = new DshTranslator();
                 try {
-                    for await (const item of this.client.sessionEvents(sessionId, opts.cwd, abort.signal, prePromptSeq)) {
+                    for await (const item of this.client.sessionEvents(sessionId, abort.signal, prePromptSeq)) {
                         if (abort.signal.aborted)
                             break;
                         if (item.kind === 'approval') {
@@ -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

@@ -21,7 +21,7 @@ import type { AgentKind, AgentSessionReader, AgentStatusInfo, SpawnOptions } fro
 import { JsonRpcClient } from '../../common/jsonrpc/client.js';
 import { KimiAcpTranslator } from './translator.js';
 import { type SessionPromptResult } from '../../common/acp/protocol-types.js';
-import { type AcpPendingApproval } from '../../common/acp/protocol-helpers.js';
+import { type AcpPendingApproval } from '../../common/acp/acp-approval.js';
 import { BaseAcpRunner } from '../../common/acp/base-acp-runner.js';
 export interface KimiAcpRunnerOptions {
     kind: AgentKind;
@@ -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

@@ -23,7 +23,7 @@ import { StringDecoder } from 'node:string_decoder';
 import { ConnectionManager, } from '../../common/jsonrpc/connection-manager.js';
 import { KimiAcpTranslator } from './translator.js';
 import { NotificationMethod, RpcErrorCode, ServerRequestMethod, } from '../../common/acp/protocol-types.js';
-import { KIMI_APPROVAL_KINDS, buildAcpPermissionOutcome, } from '../../common/acp/protocol-helpers.js';
+import { KIMI_APPROVAL_KINDS, buildAcpPermissionOutcome, } from '../../common/acp/acp-approval.js';
 import { mapAnswersByIndex } from '../../question-common.js';
 import { getLogger } from '../../../logger/index.js';
 import { BaseAcpRunner } from '../../common/acp/base-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 →
@@ -27,7 +27,7 @@
  */
 import { makeQuestionApprovalEvent } from '../../question-common.js';
 import { ServerRequestMethod, } from '../../common/acp/protocol-types.js';
-import { deriveAcpAvailableDecisions, truncateWithEllipsis, } from '../../common/acp/protocol-helpers.js';
+import { deriveAcpAvailableDecisions, truncateWithEllipsis, } from '../../common/acp/acp-approval.js';
 import { getLogger } from '../../../logger/index.js';
 import { BaseAcpTranslator } from '../../common/acp/base-translator.js';
 /**
@@ -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

@@ -23,7 +23,7 @@ import type { AgentKind, AgentSessionReader, AgentStatusInfo } from '../../types
 import { JsonRpcClient } from '../../common/jsonrpc/client.js';
 import { OpencodeAcpTranslator } from './translator.js';
 import { type SessionNewResult, type SessionResumeResult, type SessionPromptResult } from '../../common/acp/protocol-types.js';
-import { type AcpPendingApproval } from '../../common/acp/protocol-helpers.js';
+import { type AcpPendingApproval } from '../../common/acp/acp-approval.js';
 import { BaseAcpRunner } from '../../common/acp/base-acp-runner.js';
 export interface OpencodeAcpRunnerOptions {
     kind: AgentKind;
@@ -34,7 +34,7 @@ export interface OpencodeAcpRunnerOptions {
     env?: Record<string, string | undefined>;
     /** Args to spawn the ACP server with. Defaults to `['acp']`. Note: no
      *  explicit `--cwd` — opencode acp defaults --cwd to the process cwd, which
-     *  the transport already sets to the workspace (cli/cmd/acp.ts:13-17). */
+     *  the transport already sets to the cwd (cli/cmd/acp.ts:13-17). */
     acpArgs?: string[];
     /** Request timeout in milliseconds. */
     requestTimeoutMs?: number;
@@ -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