lark-remote 0.4.1 → 0.4.3

package/dist/instance-lock.js

@@ -1,7 +1,24 @@
+/**
+ * 单实例锁（configDir 粒度）。
+ *
+ * 锁文件固定两行：`pid\n<进程名>`。进程名用于 pid 复用防护——锁定进程崩溃后
+ * pid 可能被系统回收给无关进程，纯 `kill(pid, 0)` 存活探测分不出来。
+ *
+ * 校验单源 = `platform/identity`（与 killOrphan 同一套判定、同一套名字口径）：
+ *   - posix `ps -o command=`（**不用 comm**：bash/垫片包装的进程 comm 只会给
+ *     解释器名，拿它比对会假阴性）；
+ *   - win32 CIM `Get-CimInstance Win32_Process`（Windows 没有 ps）。
+ * 名字两侧都必须过 `binaryName`：记录值与比较口径各写一份就会永远判「名字
+ * 不符 → 陈旧」，等于自造一次半迁移。
+ *
+ * 与 killOrphan 的差异：killOrphan 是 fail-closed（身份不明就不杀进程），
+ * 这里是 fail-open（身份不明就认定锁还活着，绝不 clobber 无法证伪的锁）。
+ * 两者方向相反，因此身份判定取三态而不是布尔。
+ */
 import fs from 'node:fs';
 import path from 'node:path';
-import { execFileSync } from 'node:child_process';
 import { silentlyUnlink } from './common/fs.js';
+import { binaryName, verifyPidIdentityVerdict } from './platform/identity.js';
 export class InstanceAlreadyRunningError extends Error {
     pid;
     lockPath;
@@ -39,22 +56,22 @@ function isPidAlive(pid) {
 }
 export class InstanceLock {
     lockPath;
-    /**
-     * P2-20: injectable process-running probe for testing, and a process-name
-     * verifier to defend against PID reuse (a stale pid recycled by an unrelated
-     * process would otherwise be misjudged as "our instance still running").
-     * Default implementation checks the process name via `ps` when available.
-     */
-    isProcessRunning;
+    verifyIdentity;
     constructor(lockPath, opts) {
         this.lockPath = lockPath;
-        this.isProcessRunning =
-            opts?.isProcessRunning ?? ((pid, expectedComm) => defaultIsProcessRunning(pid, expectedComm));
+        this.verifyIdentity =
+            opts?.verifyIdentity ??
+                ((pid, expectedBinary) => verifyPidIdentityVerdict(pid, { expectedBinary }));
     }
-    acquire() {
+    /**
+     * 取锁。**异步**是接口的一部分：身份校验走 platform/identity（win32 侧是
+     * 异步 CIM 查询），调用方必须 await——漏 await 会在校验完成前就放行第二条
+     * 实例（这正是锁要防的事）。
+     */
+    async acquire() {
         fs.mkdirSync(path.dirname(this.lockPath), { recursive: true });
         // Atomic create-with-exclusive: 'wx' fails if file already exists.
-        // This eliminates the TOCTOU race between readPid+isProcessRunning
+        // This eliminates the TOCTOU race between readPid+verification
         // and writeFileSync in the previous implementation.
         try {
             const fd = fs.openSync(this.lockPath, 'wx');
@@ -64,8 +81,8 @@ export class InstanceLock {
         catch (err) {
             if (err.code === 'EEXIST') {
                 // Lock file exists — check if the owner is still alive
-                const { pid, comm } = this.readPidAndComm();
-                if (pid && this.isProcessRunning(pid, comm)) {
+                const { pid, name } = this.readPidAndName();
+                if (pid && (await this.isHeldByLiveInstance(pid, name))) {
                     throw new InstanceAlreadyRunningError(pid, this.lockPath);
                 }
                 // Stale lock: remove and retry once
@@ -79,8 +96,8 @@ export class InstanceLock {
                     if (retryErr.code === 'EEXIST') {
                         // Another process created the lock between unlink and retry.
                         // Bounded retry (max 1): give up rather than recurse.
-                        const { pid, comm } = this.readPidAndComm();
-                        if (pid && this.isProcessRunning(pid, comm)) {
+                        const { pid, name } = this.readPidAndName();
+                        if (pid && (await this.isHeldByLiveInstance(pid, name))) {
                             throw new InstanceAlreadyRunningError(pid, this.lockPath);
                         }
                         // New lock is also stale — give up rather than recurse.
@@ -95,7 +112,7 @@ export class InstanceLock {
         }
     }
     release() {
-        const { pid } = this.readPidAndComm();
+        const { pid } = this.readPidAndName();
         if (pid === process.pid) {
             silentlyUnlink(this.lockPath);
         }
@@ -125,59 +142,44 @@ export class InstanceLock {
         }
     }
     /**
-     * Lock file stores `pid\ncomm` where comm is the owning process's command
-     * name (captured at acquire time). On stale-lock checks we verify the
-     * recorded pid is still alive AND still running a process whose comm
-     * matches — defending against PID reuse where an unrelated process recycled
-     * the stale pid.
+     * Lock file stores `pid\nbinaryName`, the owning process's executable name
+     * captured at acquire time. `binaryName(process.execPath)` 是唯一在
+     * posix/win32 都稳定可比的口径：win32 没有 ps，而 execPath（`C:\...\node.exe`）
+     * 与 CIM CommandLine 首 token 归一后必然一致（bun/node 垫片场景亦然）。
      */
     lockContents(pid) {
-        return `${pid}\n${currentComm()}`;
+        return `${pid}\n${binaryName(process.execPath)}`;
     }
-    readPidAndComm() {
+    readPidAndName() {
         if (!fs.existsSync(this.lockPath))
-            return { pid: undefined, comm: undefined };
+            return { pid: undefined, name: undefined };
         const raw = fs.readFileSync(this.lockPath, 'utf-8').trim();
-        const [pidStr, ...commParts] = raw.split('\n');
+        const [pidStr, ...nameParts] = raw.split('\n');
         const pid = Number(pidStr);
-        const comm = commParts.join('\n') || undefined;
-        if (Number.isInteger(pid) && pid > 0 && comm)
-            return { pid, comm };
-        // Malformed or missing comm — treat as corrupt, unlink and return undefined
+        const name = nameParts.join('\n') || undefined;
+        if (Number.isInteger(pid) && pid > 0 && name)
+            return { pid, name };
+        // Malformed or missing name — treat as corrupt, unlink and return undefined
         silentlyUnlink(this.lockPath);
-        return { pid: undefined, comm: undefined };
+        return { pid: undefined, name: undefined };
     }
-}
-/**
- * Default probe: alive by ESRCH/EPERM semantics, plus a weak comm-name match
- * to reject PID reuse. If `ps` is unavailable we fall back to the pid-alive
- * check alone (no false negatives, only weaker reuse protection).
- */
-function defaultIsProcessRunning(pid, expectedComm) {
-    if (!isPidAlive(pid))
-        return false;
-    if (!expectedComm)
-        return false;
-    const actualComm = readComm(pid);
-    if (actualComm === null)
-        return true; // ps unavailable → trust pid-alive
-    // Match on the basename so `/usr/local/bin/node` vs `node` still align.
-    const base = (s) => s.split('/').pop() ?? s;
-    return base(actualComm) === base(expectedComm) || actualComm.includes(expectedComm);
-}
-function currentComm() {
-    return readComm(process.pid) ?? 'lark-remote';
-}
-function readComm(pid) {
-    try {
-        const out = execFileSync('ps', ['-p', String(pid), '-o', 'comm='], {
-            encoding: 'utf-8',
-            stdio: ['ignore', 'pipe', 'ignore'],
-        }).trim();
-        return out || null;
-    }
-    catch {
-        return null;
+    /**
+     * 锁是否仍由「我们的」实例持有（fail-open 三态）：
+     *   - 进程不存在             → false（陈旧）
+     *   - 无记录名（老/损坏文件）→ false（无法验证，与迁移前同口径按陈旧处理）
+     *   - 身份 match             → true（锁定实例还在跑，拒绝取锁）
+     *   - 身份 mismatch          → false（pid 已复用给无关进程，陈旧可接管）
+     *   - 身份 unknown           → true（查不到身份，宁可拒绝也不 clobber）
+     */
+    async isHeldByLiveInstance(pid, name) {
+        if (!isPidAlive(pid))
+            return false;
+        if (!name)
+            return false;
+        // 记录名过 binaryName 归一：老锁文件里存的是 ps comm 的全路径形态，
+        // 不归一的话升级后第一次启动会把它误判成「名字不符 → 陈旧」。
+        const verdict = await this.verifyIdentity(pid, binaryName(name));
+        return verdict !== 'mismatch';
     }
 }
 //# sourceMappingURL=instance-lock.js.map

package/dist/platform/agent-stopper.d.ts

@@ -2,21 +2,43 @@
  * 每 agent 的协议停止通道注册表（design.md §3.3）。
  *
  * Windows 没有可拦截的跨进程 SIGTERM，优雅停止只能靠协议通道（claude 的 stdin
- * 控制通道、codex 的 turn interrupt、ACP 的 abort…）。「无通道」是**合法状态**：
- * 由 Terminator 显式跳过优雅段并打日志，绝不允许悄悄等一个永远不会来的退出事件。
+ * 控制通道、codex 的 turn interrupt、ACP 的 session/cancel…）。「无通道」是
+ * **合法状态**：由 Terminator 显式跳过优雅段并打日志，绝不允许悄悄等一个永远
+ * 不会来的退出事件。
+ *
+ * **键 = agent + pid，不是 agent 单维**。两条理由：
+ *   1. 同一 agent 可以同时有多个存活子进程（每个 workspace 一条长驻连接，外加
+ *      claude 的进程代际更替）。按 agent 单键索引时后注册的连接会**覆盖**前一个
+ *      的通道，Terminator 便拿着 A 工作区的通道去停 B 工作区的进程；
+ *   2. Terminator 手上只有 `proc`，只有 pid 能把「这条通道」与「正要停的那个
+ *      进程」对上——agent 键圈族，pid 键定归属。
+ * 反例（pid 键必要性的现成证据）：kimi 的 `terminal/kill` 复用同一个 agent 键
+ * （'kimi'）去停 bash 终端子进程，pid 不同 → 查表落空 → 走树杀，语义正确，
+ * 而不是误用 agent 的 turn-cancel 通道。
  *
  * 独立成文件是为了避免 `terminator.ts`（接口 + 分发）与 `terminator-win32.ts`
  * 互相 import 形成循环依赖。
  */
 import type { ChildProcess } from 'node:child_process';
 export type AgentStopper = (proc: ChildProcess) => void | Promise<void>;
-/** agent key → 协议停止通道。测试请自建实例以隔离。 */
+/** agent key → pid → 协议停止通道。测试请自建实例以隔离。 */
 export declare class AgentStopperRegistry {
     private readonly stoppers;
-    register(agent: string, stopper: AgentStopper): void;
-    get(agent: string): AgentStopper | undefined;
-    has(agent: string): boolean;
+    register(agent: string, pid: number, stopper: AgentStopper): void;
+    get(agent: string, pid: number): AgentStopper | undefined;
+    has(agent: string, pid: number): boolean;
+    /**
+     * 注销通道。
+     *
+     * 传 `stopper` 时只在该 pid 上仍是**同一条**通道时才删：重连/进程换代可能让
+     * 同一 pid 上已经换了新通道，无脑删等于让新连接裸奔（win32 上退化成直接树杀）。
+     *
+     * @returns 是否真的删掉了
+     */
+    unregister(agent: string, pid: number, stopper?: AgentStopper): boolean;
     clear(): void;
+    /** 当前登记的通道条数（诊断 / 测试断言不泄漏用）。 */
+    get size(): number;
 }
-/** 接线用的进程级单例；runner 在 run 启动时注册自己的停止通道。 */
+/** 接线用的进程级单例；runner 在子进程起来时注册自己的停止通道。 */
 export declare const agentStopperRegistry: AgentStopperRegistry;

package/dist/platform/agent-stopper.js

@@ -1,19 +1,51 @@
-/** agent key → 协议停止通道。测试请自建实例以隔离。 */
+/** agent key → pid → 协议停止通道。测试请自建实例以隔离。 */
 export class AgentStopperRegistry {
     stoppers = new Map();
-    register(agent, stopper) {
-        this.stoppers.set(agent, stopper);
+    register(agent, pid, stopper) {
+        let byPid = this.stoppers.get(agent);
+        if (!byPid) {
+            byPid = new Map();
+            this.stoppers.set(agent, byPid);
+        }
+        byPid.set(pid, stopper);
     }
-    get(agent) {
-        return this.stoppers.get(agent);
+    get(agent, pid) {
+        return this.stoppers.get(agent)?.get(pid);
     }
-    has(agent) {
-        return this.stoppers.has(agent);
+    has(agent, pid) {
+        return this.stoppers.get(agent)?.has(pid) === true;
+    }
+    /**
+     * 注销通道。
+     *
+     * 传 `stopper` 时只在该 pid 上仍是**同一条**通道时才删：重连/进程换代可能让
+     * 同一 pid 上已经换了新通道，无脑删等于让新连接裸奔（win32 上退化成直接树杀）。
+     *
+     * @returns 是否真的删掉了
+     */
+    unregister(agent, pid, stopper) {
+        const byPid = this.stoppers.get(agent);
+        const current = byPid?.get(pid);
+        if (!byPid || current === undefined)
+            return false;
+        if (stopper !== undefined && current !== stopper)
+            return false;
+        byPid.delete(pid);
+        if (byPid.size === 0)
+            this.stoppers.delete(agent);
+        return true;
     }
     clear() {
         this.stoppers.clear();
     }
+    /** 当前登记的通道条数（诊断 / 测试断言不泄漏用）。 */
+    get size() {
+        let total = 0;
+        for (const byPid of this.stoppers.values())
+            total += byPid.size;
+        return total;
+    }
 }
-/** 接线用的进程级单例；runner 在 run 启动时注册自己的停止通道。 */
+/** 接线用的进程级单例；runner 在子进程起来时注册自己的停止通道。 */
 export const agentStopperRegistry = new AgentStopperRegistry();
 //# sourceMappingURL=agent-stopper.js.map

package/dist/platform/identity.d.ts

@@ -14,7 +14,36 @@ export interface VerifyPidIdentityOptions extends QueryIdentityOptions {
     expectedBinary: string;
     /** pid 文件记录的 CreationDate；旧文件缺省该字段则退化为仅命令行匹配 */
     expectedCreationDate?: string;
+    /** 匹配强度；默认 'executable'（见 {@link IdentityMatchMode}） */
+    matchMode?: IdentityMatchMode;
 }
+/**
+ * 匹配强度。两个调用方观测到的进程形态**不同**，因此不能共用一档强度：
+ *
+ * - `'executable'`（默认）：命令行的可执行位就是该名字——首 token 的 basename，
+ *   或带路径分隔符的 token 的 basename 去扩展名后相等。用于「记录值本身就是
+ *   可执行名」的调用方（`InstanceLock` 记 `binaryName(process.execPath)`）。
+ *   这里**不能放松**：把它放松成路径段匹配，一个 `node-18` 形态的无关进程就会被
+ *   判成「锁还在」，新实例再也起不来。
+ *
+ * - `'agent-invocation'`：agent CLI 普遍以 **解释器调用脚本** 的形态存在
+ *   （npm/pnpm/bun 全局装的 `bin` 是 `#!/usr/bin/env node` 脚本），ps 看到的是
+ *   `node <安装路径>/.../cli.js`，agent 名只出现在**路径段**里：
+ *     - `pi`   → `node ~/.nvm/…/lib/node_modules/@earendil-works/pi-coding-agent/dist/bundle/cli.js`
+ *     - `dsh`  → `node ~/.nvm/…/lib/node_modules/@deepseek-ai/dsh/lib/bin.js`
+ *     - `codex`→ `node ~/.nvm/…/lib/node_modules/@openai/codex/bin/codex.js`（basename 恰好命中）
+ *   在 `'executable'` 之上，再接受「带路径分隔符的 token 的某个路径段等于
+ *   expectedBinary，或以 expectedBinary + 非字母数字字符开头」。用于 killOrphan
+ *   （记录的是二进制名，观测到的是解释器调用）。
+ *
+ *   两条纪律仍保留：裸参数不参与匹配（`bash claude`、`grep claude foo.log` 仍然
+ *   不匹配），非首 token 必须含路径分隔符。代价是「段前缀」比精确相等松一点
+ *   （`node /x/pi-data/y.js` 会被判成 pi）——比旧的 `out.includes(needle)` 子串匹配
+ *   严格，且换取的是 pi/dsh 这类 agent 的孤儿真的能被回收。
+ *
+ * 未被使用的一档强度等于死代码：加档必须同时有生产调用方与用例。
+ */
+export type IdentityMatchMode = 'executable' | 'agent-invocation';
 /**
  * 查询进程身份；进程不存在或查询失败返回 null。
  */
@@ -26,8 +55,35 @@ export declare function queryProcessIdentity(pid: number, opts?: QueryIdentityOp
  */
 export declare function tokenizeCommandLine(commandLine: string): string[];
 /**
- * pid 身份验证：进程存活且命令行确实属于期望二进制（+ CreationDate 一致）才 true。
+ * 取命令行 token 的「去掉扩展名的 basename」，用于与期望二进制名比较。
+ *
+ * 导出是给「自己记录进程名」的调用方（InstanceLock 写锁文件）复用同一口径：
+ * 记录值与比较口径若各写一份，锁会永远判「名字不符 → 陈旧」，自造一次新的
+ * half-migration。win32 上 `.cmd` 垫片（`node_modules/.bin/claude.cmd`）也靠
+ * 这里的去扩展名把 `claude.cmd` 归一成 `claude`。
+ */
+export declare function binaryName(token: string, platform?: NodeJS.Platform): string;
+/**
+ * 身份判定三态。`unknown`（查询失败/进程已消失）与 `mismatch`（身份不符）必须
+ * 分开：两个调用方对它们的处置**方向相反**——
+ *   - killOrphan：两者都不杀（fail-closed，宁可留孤儿也不误杀无辜进程）；
+ *   - InstanceLock：`unknown` 退回纯存活探测（不 clobber 无法证伪的锁），
+ *     只有 `mismatch` 才判陈旧并接管。
+ * 布尔接口无法同时表达这两种语义，因此这里（async + sync 两个 verdict 入口）是
+ * 唯一判定源。
+ */
+export type IdentityVerdict = 'match' | 'mismatch' | 'unknown';
+export declare function verifyPidIdentityVerdict(pid: number, opts: VerifyPidIdentityOptions): Promise<IdentityVerdict>;
+/**
+ * 同步版判定，给无法 await 的调用方（`SpawningRunner.killOrphan`——Bridge.getRunner
+ * 是同步方法，异步化会级联整个 runner 接口）。
+ *
+ * posix 用 `execFileSync('ps', ...)`，与 `queryProcessIdentity` 的 posix 分支是
+ * 同一条命令、同一个超时；win32 **恒返回 `unknown`**——CIM 必须经 PowerShell
+ * 收 stdout，没有同步形态。`unknown` 在 killOrphan 的 fail-closed 语义下就是
+ * 「不杀 + 清陈旧 pid 文件」，与异步路径一致，因此不是能力缺失而是正确的降级。
  *
- * 用于 killOrphan 与实例锁陈旧判定——只有这里返回 true 才允许动手。
+ * 严禁在这里退回「跳过身份校验直接 kill(pid, 0)」的旧行为：那正是本次迁移
+ * 要堵的洞（pid 被系统回收给无关进程时会误杀）。
  */
-export declare function verifyPidIdentity(pid: number, opts: VerifyPidIdentityOptions): Promise<boolean>;
+export declare function verifyPidIdentityVerdictSync(pid: number, opts: VerifyPidIdentityOptions): IdentityVerdict;

package/dist/platform/identity.js

@@ -12,7 +12,7 @@
  *   （killOrphan）应按需调用，真机矩阵（M0）需实测整体耗时；
  * - platform 显式注入，win32 语义可在任意宿主上单测。
  */
-import { spawn } from 'node:child_process';
+import { execFileSync, spawn } from 'node:child_process';
 import path from 'node:path';
 import { currentPlatform, isWin32 } from './select.js';
 const DEFAULT_TIMEOUT_MS = 3000;
@@ -134,8 +134,15 @@ export function tokenizeCommandLine(commandLine) {
         tokens.push(current);
     return tokens;
 }
-/** 取命令行 token 的「去掉扩展名的 basename」，用于与期望二进制名比较。 */
-function tokenBinaryName(token, platform) {
+/**
+ * 取命令行 token 的「去掉扩展名的 basename」，用于与期望二进制名比较。
+ *
+ * 导出是给「自己记录进程名」的调用方（InstanceLock 写锁文件）复用同一口径：
+ * 记录值与比较口径若各写一份，锁会永远判「名字不符 → 陈旧」，自造一次新的
+ * half-migration。win32 上 `.cmd` 垫片（`node_modules/.bin/claude.cmd`）也靠
+ * 这里的去扩展名把 `claude.cmd` 归一成 `claude`。
+ */
+export function binaryName(token, platform = currentPlatform) {
     let text = token.trim();
     if (text.length >= 2 &&
         ((text.startsWith('"') && text.endsWith('"')) || (text.startsWith("'") && text.endsWith("'")))) {
@@ -143,45 +150,113 @@ function tokenBinaryName(token, platform) {
     }
     // CIM 的 CommandLine 用 Windows 分隔符；posix 用 unix 分隔符
     const p = isWin32(platform) ? path.win32 : path.posix;
-    const base = p.basename(text);
-    const ext = p.extname(base);
-    const name = ext ? base.slice(0, -ext.length) : base;
+    const name = stripExtension(p.basename(text));
     return caseInsensitive(platform) ? name.toLowerCase() : name;
 }
 /**
- * 命令行与期望二进制是否属于同一程序。收紧规则（review 2026-09-05）：
- * 1. 首 token（可执行位）匹配——`/usr/local/bin/claude --verbose` 匹配 claude；
- * 2. 或后续 token 是**带路径分隔符的脚本路径**且 basename 匹配——
- *    `node /home/user/.local/bin/claude` 匹配 claude。
- * 任意位置裸参数不再参与匹配：`bash claude`（脚本恰好叫 claude）、
- * `grep claude foo.log` 这类不再假阳性（killOrphan 场景会误杀无辜进程）。
+ * 命令行与期望二进制是否属于同一程序（review 2026-09-05 收紧 + 2026-09-20 分档）。
+ *
+ * 1. 可执行位匹配：首 token 的 basename 相等——`/usr/local/bin/claude --verbose`
+ *    匹配 claude；native 单文件 CLI（claude 的 `bin/claude.exe`）也走这条；
+ * 2. 或后续 token 是**带路径分隔符的脚本路径**且 basename（去扩展名）相等——
+ *    `node /home/user/.local/bin/claude`、`…/@openai/codex/bin/codex.js` 匹配；
+ * 3. 仅 `'agent-invocation'` 档再放开到**路径段**：某个路径段等于 expectedBinary，
+ *    或以 expectedBinary + 非字母数字字符开头。这是为了 `node …/pi-coding-agent/…/cli.js`
+ *    这类「名字只在目录里」的安装形态（见 IdentityMatchMode）。
+ *
+ * 任意位置裸参数不参与匹配：`bash claude`（脚本恰好叫 claude）、`grep claude foo.log`
+ * 这类不再假阳性（killOrphan 场景会误杀无辜进程）。
  */
-function commandLineMatches(commandLine, want, platform) {
+function commandLineMatches(commandLine, want, platform, mode) {
     const tokens = tokenizeCommandLine(commandLine);
     const first = tokens[0];
-    if (first !== undefined && tokenBinaryName(first, platform) === want)
+    if (first !== undefined && binaryName(first, platform) === want)
         return true;
-    return tokens
-        .slice(1)
-        .some((token) => /[/\\]/.test(token) && tokenBinaryName(token, platform) === want);
+    return tokens.slice(1).some((token) => {
+        // 非首 token 必须像「路径」才参与：把裸参数（`bash claude`）排除在外
+        if (!/[/\\]/.test(token))
+            return false;
+        if (binaryName(token, platform) === want)
+            return true;
+        if (mode !== 'agent-invocation')
+            return false;
+        return token.split(/[/\\]/).some((segment, index, all) => {
+            // 末段是文件名：与 binaryName 同口径去扩展名；中间段是目录名，保留原样
+            const name = index === all.length - 1 ? stripExtension(segment) : segment;
+            const normalized = caseInsensitive(platform) ? name.toLowerCase() : name;
+            if (normalized === want)
+                return true;
+            if (!normalized.startsWith(want))
+                return false;
+            // `pi-coding-agent` / `claude.mock.js` 命中；`claudette` / `claudeAgent` 不命中。
+            // 判定分隔符必须同时覆盖大小写字母（linux 档不归一大小写，`claudeX` 的 X
+            // 是字母而不是分隔符）。
+            const next = normalized[want.length];
+            return next !== undefined && !/[a-zA-Z0-9]/.test(next);
+        });
+    });
+}
+/** 去掉最后一个扩展名（`claude.mock.js` → `claude.mock`）。与 binaryName 的口径一致。 */
+function stripExtension(base) {
+    const dot = base.lastIndexOf('.');
+    return dot > 0 ? base.slice(0, dot) : base;
 }
 /**
- * pid 身份验证：进程存活且命令行确实属于期望二进制（+ CreationDate 一致）才 true。
- *
- * 用于 killOrphan 与实例锁陈旧判定——只有这里返回 true 才允许动手。
+ * 身份快照 → 判定。async/sync 两条取快照的路径共用这一处比较逻辑：口径若各写
+ * 一份，迟早会因为「只在一个路径上收紧规则」而分裂成两种身份语义。
  */
-export async function verifyPidIdentity(pid, opts) {
-    const platform = opts.platform ?? currentPlatform;
-    const identity = await queryProcessIdentity(pid, opts);
-    if (!identity)
-        return false;
+function decideIdentity(identity, opts, platform) {
     const want = caseInsensitive(platform) ? opts.expectedBinary.toLowerCase() : opts.expectedBinary;
-    if (!commandLineMatches(identity.commandLine, want, platform))
-        return false;
+    const mode = opts.matchMode ?? 'executable';
+    if (!commandLineMatches(identity.commandLine, want, platform, mode))
+        return 'mismatch';
     // CreationDate 仅在 pid 文件带了第三行时才比对（旧文件缺字段 → 退化为命令行匹配）
     const expected = opts.expectedCreationDate?.trim();
-    if (expected)
-        return identity.creationDate === expected;
-    return true;
+    if (expected && identity.creationDate !== expected)
+        return 'mismatch';
+    return 'match';
+}
+export async function verifyPidIdentityVerdict(pid, opts) {
+    const platform = opts.platform ?? currentPlatform;
+    const identity = await queryProcessIdentity(pid, opts);
+    if (!identity)
+        return 'unknown';
+    return decideIdentity(identity, opts, platform);
+}
+/**
+ * 同步版判定，给无法 await 的调用方（`SpawningRunner.killOrphan`——Bridge.getRunner
+ * 是同步方法，异步化会级联整个 runner 接口）。
+ *
+ * posix 用 `execFileSync('ps', ...)`，与 `queryProcessIdentity` 的 posix 分支是
+ * 同一条命令、同一个超时；win32 **恒返回 `unknown`**——CIM 必须经 PowerShell
+ * 收 stdout，没有同步形态。`unknown` 在 killOrphan 的 fail-closed 语义下就是
+ * 「不杀 + 清陈旧 pid 文件」，与异步路径一致，因此不是能力缺失而是正确的降级。
+ *
+ * 严禁在这里退回「跳过身份校验直接 kill(pid, 0)」的旧行为：那正是本次迁移
+ * 要堵的洞（pid 被系统回收给无关进程时会误杀）。
+ */
+export function verifyPidIdentityVerdictSync(pid, opts) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return 'unknown';
+    const platform = opts.platform ?? currentPlatform;
+    if (isWin32(platform))
+        return 'unknown';
+    let stdout;
+    try {
+        stdout = execFileSync('ps', ['-o', 'command=', '-p', String(pid)], {
+            encoding: 'utf-8',
+            timeout: opts.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+            stdio: ['ignore', 'pipe', 'ignore'],
+            windowsHide: true,
+        });
+    }
+    catch {
+        // 进程不存在 / ps 不可用 / 超时：查不到身份 → unknown（不杀）
+        return 'unknown';
+    }
+    const commandLine = stdout.split('\n')[0]?.trim() ?? '';
+    if (!commandLine)
+        return 'unknown';
+    return decideIdentity({ commandLine }, opts, platform);
 }
 //# sourceMappingURL=identity.js.map

package/dist/platform/path.d.ts

@@ -1,13 +1,6 @@
 export interface PathOptions {
     platform?: NodeJS.Platform;
-    /** 环境变量注入（测试用）；默认 process.env */
-    env?: Record<string, string | undefined>;
-    /** 家目录注入（测试用）；默认 os.homedir() */
-    home?: string;
-    /** 是否执行 realpath（默认 true）；不存在的路径自动跳过 */
-    realpath?: boolean;
 }
-export declare function canonicalPath(p: string, opts?: PathOptions): string;
 export declare function samePath(a: string, b: string, opts?: PathOptions): boolean;
 /**
  * cwd → 会话项目目录名（Claude/pi 的 on-disk 编码，lossy N-to-N）。

package/dist/platform/path.js

@@ -3,66 +3,16 @@
  *
  * 所有 cwd 相等性判断、会话目录编码、pid 文件名后缀、spawn cwd 前统一走本模块。
  * 语义映射：
- *   canonicalPath(p): realpath(expandEnv(expandTilde(normalizeSeparators(p))))
  *   samePath(a, b):   win32/darwin 默认大小写不敏感 + 分隔符不敏感；linux 严格相等
  *   displayName(p):   path.basename（win32 原生认识 \ 与 /）
  *
  * 全部函数接受显式 `platform` 参数（默认 currentPlatform），使 win32 语义
  * 可在任意宿主的单元测试中验证。
  */
-import fs from 'node:fs';
-import os from 'node:os';
 import path from 'node:path';
 import { currentPlatform, isWin32 } from './select.js';
-/** 展开开头的 ~ 或 ~/（win32 含 ~\）为家目录；其余原样返回。 */
-function expandTilde(p, home, platform) {
-    if (p === '~')
-        return home;
-    if (p.startsWith('~/') || (isWin32(platform) && p.startsWith('~\\'))) {
-        return path.join(home, p.slice(2));
-    }
-    return p;
-}
-/** 展开 %VAR%（win32）或 $VAR / ${VAR}（posix）；未定义的变量保留字面量。 */
-function expandEnv(p, env, platform) {
-    if (isWin32(platform)) {
-        return p.replace(/%([A-Za-z0-9_]+)%/g, (match, name) => env[name] ?? match);
-    }
-    return p.replace(/\$(?:\{([A-Za-z_][A-Za-z0-9_]*)\}|([A-Za-z_][A-Za-z0-9_]*))/g, (match, braced, plain) => {
-        const name = braced ?? plain;
-        if (name === undefined)
-            return match;
-        const value = env[name];
-        return value === undefined ? match : value;
-    });
-}
-/** win32 把反斜杠归一为正斜杠（Node win32 API 两者皆收）；posix 反斜杠是合法文件名字符，不动。 */
-function normalizeSeparators(p, platform) {
-    return isWin32(platform) ? p.replaceAll('\\', '/') : p;
-}
 function resolveOptions(opts) {
-    const platform = opts?.platform ?? currentPlatform;
-    return {
-        platform,
-        env: opts?.env ?? process.env,
-        home: opts?.home ?? os.homedir(),
-        realpath: opts?.realpath ?? true,
-    };
-}
-export function canonicalPath(p, opts) {
-    const { platform, env, home, realpath } = resolveOptions(opts);
-    let out = expandTilde(p, home, platform);
-    out = expandEnv(out, env, platform);
-    out = normalizeSeparators(out, platform);
-    if (!realpath)
-        return out;
-    try {
-        return fs.realpathSync(out);
-    }
-    catch {
-        // 路径尚不存在（如待创建的目录）：返回展开+归一化形态，不抛
-        return out;
-    }
+    return { platform: opts?.platform ?? currentPlatform };
 }
 export function samePath(a, b, opts) {
     const { platform } = resolveOptions(opts);

package/dist/platform/shell.d.ts

@@ -24,6 +24,20 @@ export interface ShellBackend {
         cwd: string;
         options?: SpawnOptions;
     }): ChildProcess;
+    /**
+     * 执行一段 **argv**（不是 shell 字符串）。ACP 的 terminal/create 这类协议
+     * 直接给 command + args，逐 token 语义必须保留（拼成字符串会改写引号/转义），
+     * 所以这里**只把「可执行文件在哪」收进 seam**，不改写参数也不加 `-c`：
+     *
+     * - posix：原样透传（与迁移前 `spawnProcess(command, args, ...)` 逐字一致）；
+     * - win32：首 token 是 shell（bash/sh/zsh/dash）时按 Git Bash 解析，缺失则抛
+     *   {@link ShellUnavailableError}——kimi agent 在 Windows 上可用的前置条件
+     *   （§4.4）。其余命令交给 cross-spawn 做 PATH/PATHEXT 解析，不做命令翻译。
+     */
+    spawnArgv(file: string, args: readonly string[], opts?: {
+        cwd?: string;
+        options?: SpawnOptions;
+    }): ChildProcess;
 }
 /** shell 不可用（如 win32 上没装 Git Bash）：调用方应转成明确错误卡。 */
 export declare class ShellUnavailableError extends Error {