lark-remote 0.4.5 → 0.5.0

package/dist/runner/common/acp/acp-approval.d.ts

@@ -2,7 +2,7 @@
  * ACP approval/permission mapping and lifecycle shared by the kimi and
  * opencode ACP runners.
  *
- * Extracted from runner.ts and translator.ts to avoid duplication (G5).
+ * Extracted from runner.ts and translator.ts to avoid duplication.
  * Shape source: approval.ts:28-29 — optionId is opaque, echo back as-is.
  */
 import type { ApprovalView } from '../../types.js';
@@ -33,7 +33,7 @@ export declare function buildAcpPermissionOutcome(action: string, options: Permi
 /**
  * 从服务端 options kind 派生审批决定列表：accept/decline/cancel 恒有；
  * 带 always 类 option（kimi approve_always / opencode allow_always）才提供
- * acceptForSession（§P4「本会话总是允许」）。kimi/opencode 两侧共用。
+ * acceptForSession（「本会话总是允许」）。kimi/opencode 两侧共用。
  */
 export declare function deriveAcpAvailableDecisions(options: PermissionOption[]): string[];
 /** 截断长文本并追加省略号（translator 审批 reason 用，原先两份相同拷贝）。 */

package/dist/runner/common/acp/acp-approval.js

@@ -2,7 +2,7 @@
  * ACP approval/permission mapping and lifecycle shared by the kimi and
  * opencode ACP runners.
  *
- * Extracted from runner.ts and translator.ts to avoid duplication (G5).
+ * Extracted from runner.ts and translator.ts to avoid duplication.
  * Shape source: approval.ts:28-29 — optionId is opaque, echo back as-is.
  */
 import { getLogger } from '../../../logger/index.js';
@@ -10,7 +10,7 @@ import { getLogger } from '../../../logger/index.js';
  * Find an option by matching its `kind` against a list of candidate values,
  * and return the `optionId` to echo back in the approval response.
  * ACP option kind values vary between kimi versions; this handles both
- * the documented names and the observed real names (§2.3).
+ * the documented names and the observed real names.
  */
 function findOptionIdByKind(options, candidateKinds) {
     for (const kind of candidateKinds) {
@@ -54,7 +54,7 @@ export function buildAcpPermissionOutcome(action, options, kinds) {
 /**
  * 从服务端 options kind 派生审批决定列表：accept/decline/cancel 恒有；
  * 带 always 类 option（kimi approve_always / opencode allow_always）才提供
- * acceptForSession（§P4「本会话总是允许」）。kimi/opencode 两侧共用。
+ * acceptForSession（「本会话总是允许」）。kimi/opencode 两侧共用。
  */
 export function deriveAcpAvailableDecisions(options) {
     const decisions = ['accept', 'decline', 'cancel'];

package/dist/runner/common/acp/base-acp-runner.js

@@ -15,7 +15,7 @@ export class BaseAcpRunner extends ConnectionBasedRunner {
     constructor(opts, connectionManager) {
         super(opts);
         this.connectionManager = connectionManager;
-        // 协议停止通道（design §3.3）：ACP 的 cancel 就是 `session/cancel`，已由
+        // 协议停止通道：ACP 的 cancel 就是 `session/cancel`，已由
         // cancelCurrentTurn 实现。这里只做登记接线——manager 建在 super() 实参里，
         // 那时 this 不可用，所以只能等 super() 返回后再赋值。
         connectionManager.stopper = ({ client }) => this.buildCooperativeStop(client);

package/dist/runner/common/acp/base-translator.d.ts

@@ -114,7 +114,7 @@ export declare abstract class BaseAcpTranslator {
      */
     setOperationKind(kind: 'turn' | 'compact'): void;
     /**
-     * plan update → PlanEvent（信息保真 C3.2：不再显式丢弃）。
+     * plan update → PlanEvent（信息保真 不再显式丢弃）。
      * ACP PlanEntry: { content, priority, status }（status: pending/in_progress/
      * completed）。基类具体方法：kimi/opencode wire 结构相同，直接复用。
      */
@@ -125,7 +125,7 @@ export declare abstract class BaseAcpTranslator {
      * JSON.parse (older agents send JSON strings) — keeps the card from
      * crashing on undefined input.
      *
-     * 信息保真 C3.1：kind 命中 KIND_TO_TOOL 时用映射名渲染结构化面板；
+     * 信息保真 kind 命中 KIND_TO_TOOL 时用映射名渲染结构化面板；
      * title 与 name 不同时把 title 存到 content block 的 summary 字段
      * （渲染层做面板副标题）。
      */
@@ -144,7 +144,7 @@ export declare abstract class BaseAcpTranslator {
     /** tool_use name recorded at tool_call time (kind mapping wins, else title). */
     protected getToolCallName(toolCallId: string): string | undefined;
     /**
-     * kind → canonical tool name (信息保真 C3.1). Shared by the initial tool_call
+     * kind → canonical tool name (信息保真). Shared by the initial tool_call
      * handler and the tool_call_update patch builder so both agree on the name.
      */
     protected toolNameFromKind(kind: string | undefined): string | undefined;

package/dist/runner/common/acp/base-translator.js

@@ -1,6 +1,6 @@
 import { NotificationMethod, ServerRequestMethod, SessionEventType, } from './protocol-types.js';
 /**
- * ACP tool kind → 常用工具名映射（信息保真 C3.1，数据驱动无 agent 分支）。
+ * ACP tool kind → 常用工具名映射（信息保真，数据驱动无 agent 分支）。
  * kind 命中映射时用映射名渲染结构化面板；否则回落 title（维持现状）。
  */
 const KIND_TO_TOOL = {
@@ -199,7 +199,7 @@ export class BaseAcpTranslator {
     // Shared notification handlers
     // =========================================================================
     /**
-     * plan update → PlanEvent（信息保真 C3.2：不再显式丢弃）。
+     * plan update → PlanEvent（信息保真 不再显式丢弃）。
      * ACP PlanEntry: { content, priority, status }（status: pending/in_progress/
      * completed）。基类具体方法：kimi/opencode wire 结构相同，直接复用。
      */
@@ -224,7 +224,7 @@ export class BaseAcpTranslator {
      * JSON.parse (older agents send JSON strings) — keeps the card from
      * crashing on undefined input.
      *
-     * 信息保真 C3.1：kind 命中 KIND_TO_TOOL 时用映射名渲染结构化面板；
+     * 信息保真 kind 命中 KIND_TO_TOOL 时用映射名渲染结构化面板；
      * title 与 name 不同时把 title 存到 content block 的 summary 字段
      * （渲染层做面板副标题）。
      */
@@ -327,7 +327,7 @@ export class BaseAcpTranslator {
         return this.toolCallNameByCallId.get(toolCallId);
     }
     /**
-     * kind → canonical tool name (信息保真 C3.1). Shared by the initial tool_call
+     * kind → canonical tool name (信息保真). Shared by the initial tool_call
      * handler and the tool_call_update patch builder so both agree on the name.
      */
     toolNameFromKind(kind) {

package/dist/runner/common/acp/protocol-types.js

@@ -45,7 +45,7 @@ export const RpcErrorCode = {
 //
 // REAL envelope: {sessionId, update: {sessionUpdate: '<kind>', ...}}.
 // The discriminator field is `update.sessionUpdate` — there is NO nested
-// `event.type` / `event.delta` (S5/S6 打回根因：旧实现读 params.event，
+// `event.type` / `event.delta` (旧实现读 params.event，
 // 真实通知全部静默丢弃)。
 // =============================================================================
 /** Notification method names for ACP protocol. */

package/dist/runner/common/connection-based-runner.d.ts

@@ -51,7 +51,7 @@ export declare abstract class ConnectionBasedRunner<TClient, TEvent = AgentEvent
     /** Set up the turn: acquire + thread|session new/resume + prompt. */
     protected abstract setupTurn(message: string, opts: SpawnOptions): Promise<void>;
     /**
-     * 本连接的协议停止通道（design §3.3）。
+     * 本连接的协议停止通道。
      *
      * win32 上「优雅停止」没有可拦截的跨进程 SIGTERM，只能经 agent 自有协议通道
      * 请求对方收摊。子类把这个方法的结果交给 ConnectionManager.stopper，由后者按

package/dist/runner/common/connection-based-runner.js

@@ -28,7 +28,7 @@ export class ConnectionBasedRunner {
         this.turnIdleTimeoutMs = opts.turnIdleTimeoutMs ?? defaultTurnIdleTimeoutMs;
     }
     /**
-     * 本连接的协议停止通道（design §3.3）。
+     * 本连接的协议停止通道。
      *
      * win32 上「优雅停止」没有可拦截的跨进程 SIGTERM，只能经 agent 自有协议通道
      * 请求对方收摊。子类把这个方法的结果交给 ConnectionManager.stopper，由后者按
@@ -141,7 +141,7 @@ export class ConnectionBasedRunner {
     async stop(_opts) {
         if (!this._isRunning)
             return;
-        // CC-01: 启动阶段（client/session 未建立）也必须记录停止意图，否则 /stop 被吞、
+        // 启动阶段（client/session 未建立）也必须记录停止意图，否则 /stop 被吞、
         // turn 照常执行。executeTurn 在 setup 完成后检查 stopRequested 补发 cancel。
         this.stopRequested = true;
         this.forceFinish = true;

package/dist/runner/common/jsonl-stream.d.ts

@@ -4,7 +4,7 @@ import type { Readable } from 'node:stream';
 interface JSONLStreamOptions {
     onParseError?: (line: string) => void;
     /**
-     * Pause stdout once `lineQueue` exceeds this depth (P1-4 backpressure).
+     * Pause stdout once `lineQueue` exceeds this depth (backpressure).
      * Default 100 (matches production; tests may pass a smaller value).
      */
     pauseThreshold?: number;
@@ -23,7 +23,7 @@ interface JSONLStreamOptions {
  * - JSON parse errors: when `options.onParseError` is provided, bad lines are
  *   forwarded to the callback; otherwise a warning is logged via getLogger().warn
  *   and the line is skipped.
- * - Optional backpressure (P1-4): when `pauseThreshold` is set, stdout is
+ * - Optional backpressure: when `pauseThreshold` is set, stdout is
  *   paused once the parsed-line queue exceeds the threshold and resumed once
  *   the consumer drains it back below `resumeThreshold`, bounding memory in
  *   long runs where the producer (agent stdout) outpaces the consumer (card

package/dist/runner/common/jsonl-stream.js

@@ -8,7 +8,7 @@ import { getLogger } from '../../logger/index.js';
  * - JSON parse errors: when `options.onParseError` is provided, bad lines are
  *   forwarded to the callback; otherwise a warning is logged via getLogger().warn
  *   and the line is skipped.
- * - Optional backpressure (P1-4): when `pauseThreshold` is set, stdout is
+ * - Optional backpressure: when `pauseThreshold` is set, stdout is
  *   paused once the parsed-line queue exceeds the threshold and resumed once
  *   the consumer drains it back below `resumeThreshold`, bounding memory in
  *   long runs where the producer (agent stdout) outpaces the consumer (card
@@ -22,7 +22,7 @@ import { getLogger } from '../../logger/index.js';
  */
 export function createJSONLStream(stdout, options) {
     const lineQueue = [];
-    // P3-1: accumulate partial-line fragments in an array instead of repeatedly
+    // accumulate partial-line fragments in an array instead of repeatedly
     // string-concatenating a growing `partialLine`. A huge single JSON line
     // (large tool_result / text_end) spanning many chunks caused O(n²) copies:
     // each chunk rebuilt `partialLine + text` over the whole accumulated prefix.
@@ -30,7 +30,7 @@ export function createJSONLStream(stdout, options) {
     // and push complete lines; the residual tail stays as array fragments until
     // the next newline or stream end. Net allocation: O(n) instead of O(n²).
     const partialFragments = [];
-    // P2-14: accumulated byte length of partialFragments. Backpressure (above)
+    // accumulated byte length of partialFragments. Backpressure (above)
     // only counts COMPLETE lines in lineQueue; a never-newline stream (malformed
     // output, binary garbage) accumulates fragments without ever completing a
     // line, so pause never fires and memory grows unbounded. Cap the partial
@@ -41,13 +41,13 @@ export function createJSONLStream(stdout, options) {
     const completeLines = [];
     let done = false;
     let resolveNext = null;
-    // P1-4 backpressure thresholds. Default matches production (100).
+    // backpressure thresholds. Default matches production (100).
     const pauseThreshold = options?.pauseThreshold ?? 100;
     // Default low-water mark is half the high-water mark for meaningful hysteresis
     // (avoids per-line pause/resume thrashing when callers don't set it explicitly).
     let resumeThreshold = options?.resumeThreshold ?? Math.max(0, Math.floor(pauseThreshold / 2));
     // Clamp misconfiguration: resumeThreshold > pauseThreshold would resume at queue
-    // high water then immediately re-pause on the next line → thrash (P1-4 review nit).
+    // high water then immediately re-pause on the next line → thrash (nit).
     if (resumeThreshold > pauseThreshold)
         resumeThreshold = pauseThreshold;
     let paused = false;
@@ -58,7 +58,7 @@ export function createJSONLStream(stdout, options) {
         }
     }
     // Flush any trailing partial line and mark the stream finished. Shared by the
-    // 'end'/'close'/'error' handlers so flush logic lives in one place (P1-4 review nit).
+    // 'end'/'close'/'error' handlers so flush logic lives in one place (nit).
     function flushAndFinish() {
         if (partialFragments.length > 0) {
             const trimmed = partialFragments.join('').trim();
@@ -70,7 +70,7 @@ export function createJSONLStream(stdout, options) {
         done = true;
         notify();
     }
-    // P2-14: flush an oversize partial line as a bad line. When partialFragments
+    // flush an oversize partial line as a bad line. When partialFragments
     // exceeds the byte cap, the partial line is treated as malformed (a single
     // JSON line should never reach 10MB) and reported via onParseError rather
     // than accumulated indefinitely. Resets the buffer so a pathological stream
@@ -93,7 +93,7 @@ export function createJSONLStream(stdout, options) {
     }
     // Apply backpressure after pushing new lines: pause stdout when the queue
     // exceeds the high-water mark so the producer stops feeding until the
-    // consumer drains it. P1-4 bounds memory in long runs.
+    // consumer drains it.bounds memory in long runs.
     function maybePause() {
         if (pauseThreshold > 0 && !paused && lineQueue.length > pauseThreshold) {
             paused = true;
@@ -110,7 +110,7 @@ export function createJSONLStream(stdout, options) {
     }
     stdout.on('data', (chunk) => {
         const text = chunk.toString('utf-8');
-        // P3-1: split on newlines. The first segment continues the pending partial
+        // split on newlines. The first segment continues the pending partial
         // line (joined with accumulated fragments — one join per chunk, not per
         // byte); subsequent segments are complete lines. The last segment is the
         // new partial tail (kept as a single fragment).
@@ -119,7 +119,7 @@ export function createJSONLStream(stdout, options) {
             // No newline in this chunk: the whole chunk is a partial fragment.
             partialFragments.push(segments[0]);
             partialBytes += segments[0].length;
-            // P2-14: cap the partial line. A never-newline stream would otherwise
+            // cap the partial line. A never-newline stream would otherwise
             // accumulate fragments without bound (backpressure only counts complete
             // lines). Flush as a bad line once the byte cap is exceeded.
             if (partialBytes > PARTIAL_BYTE_LIMIT) {
@@ -140,7 +140,7 @@ export function createJSONLStream(stdout, options) {
             // Last segment is the new partial tail.
             partialFragments.push(segments[segments.length - 1]);
             partialBytes = segments[segments.length - 1].length;
-            // P2-14: the trailing partial tail can itself exceed the cap if a single
+            // the trailing partial tail can itself exceed the cap if a single
             // chunk is larger than 10MB with no internal newline.
             if (partialBytes > PARTIAL_BYTE_LIMIT) {
                 flushOversizePartial();
@@ -162,7 +162,7 @@ export function createJSONLStream(stdout, options) {
     stdout.on('close', () => {
         flushAndFinish();
     });
-    // P1-4: handle stdout 'error' so the generator terminates instead of
+    // handle stdout 'error' so the generator terminates instead of
     // hanging forever on the `await new Promise` below. Without this, a stdout
     // error (e.g. broken pipe, runner crash) leaves the consumer awaiting a
     // notify that never comes → bridge serial queue blocks permanently. We do

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

@@ -44,7 +44,7 @@ export declare class JsonRpcClient<InitializeResult = unknown> {
      * 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: ClientHooks): void;

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,