lark-remote 0.1.12 → 0.2.0

package/dist/platform/identity.js

@@ -0,0 +1,187 @@
+/**
+ * pid 身份验证（design.md §3.4 / §3.5）。
+ *
+ * POSIX 现状用 `ps -o command=` 读命令行，Windows 没有 ps，等价物是 CIM：
+ * PowerShell `Get-CimInstance Win32_Process` 取 CommandLine，并额外取
+ * CreationDate 做 pid 复用加固（Windows pid 复用快）。
+ *
+ * 纪律：
+ * - 只在查询失败/身份不匹配时返回 null / false，绝不抛给调用方——调用方
+ *   （killOrphan、实例锁陈旧判定）一律「只有身份匹配才动手」；
+ * - win32 每次查询要拉起 PowerShell（冷启动约 1s），批量扫 pid 文件的场景
+ *   （killOrphan）应按需调用，真机矩阵（M0）需实测整体耗时；
+ * - platform 显式注入，win32 语义可在任意宿主上单测。
+ */
+import { spawn } from 'node:child_process';
+import path from 'node:path';
+import { currentPlatform, isWin32 } from './select.js';
+const DEFAULT_TIMEOUT_MS = 3000;
+/** 拉起一次性查询进程并收全 stdout；超时/拉起失败/进程报错一律 null。 */
+function collect(file, args, timeoutMs) {
+    return new Promise((resolve) => {
+        let proc;
+        try {
+            // stderr 用 ignore：查询进程的错误输出我们不需要，pipe 而不消费在极端
+            // 情况下（管道缓冲满）会阻塞子进程，把一次性查询拖成挂起。
+            // windowsHide：避免查询进程在桌面闪控制台窗口
+            proc = spawn(file, args, { stdio: ['ignore', 'pipe', 'ignore'], windowsHide: true });
+        }
+        catch {
+            resolve(null);
+            return;
+        }
+        let stdout = '';
+        let settled = false;
+        const finish = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolve(result);
+        };
+        proc.stdout?.setEncoding('utf8');
+        proc.stdout?.on('data', (chunk) => {
+            stdout += chunk;
+        });
+        proc.on('error', () => finish(null));
+        proc.on('exit', (code) => finish({ code, stdout }));
+        const timer = setTimeout(() => {
+            proc.kill();
+            finish(null);
+        }, timeoutMs);
+    });
+}
+/** 解析 CIM 输出（ConvertTo-Json 形态）：单对象或数组，取首条。 */
+function parseCimIdentity(stdout) {
+    const text = stdout.trim();
+    if (!text)
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+    const first = Array.isArray(parsed) ? parsed[0] : parsed;
+    if (!first || typeof first !== 'object')
+        return null;
+    const record = first;
+    // 权限不足时 CIM 会给出 null 字段：命令行拿不到就没有身份可言
+    const commandLine = typeof record.CommandLine === 'string' ? record.CommandLine.trim() : '';
+    if (!commandLine)
+        return null;
+    const rawDate = typeof record.CreationDate === 'string' ? record.CreationDate.trim() : '';
+    return rawDate ? { commandLine, creationDate: rawDate } : { commandLine };
+}
+/**
+ * 查询进程身份；进程不存在或查询失败返回 null。
+ */
+export async function queryProcessIdentity(pid, opts) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return null;
+    const platform = opts?.platform ?? currentPlatform;
+    const timeoutMs = opts?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    if (isWin32(platform)) {
+        const result = await collect('powershell.exe', [
+            '-NoProfile',
+            '-NonInteractive',
+            '-Command',
+            `Get-CimInstance Win32_Process -Filter "ProcessId = ${pid}" ` +
+                // -Compress：单行输出，避免 PowerShell 按控制台宽度换行给解析添变数
+                '| Select-Object -Property CommandLine,CreationDate | ConvertTo-Json -Compress',
+        ], timeoutMs);
+        return result ? parseCimIdentity(result.stdout) : null;
+    }
+    const result = await collect('ps', ['-o', 'command=', '-p', String(pid)], timeoutMs);
+    if (!result || result.code !== 0)
+        return null;
+    const commandLine = result.stdout.split('\n')[0]?.trim() ?? '';
+    return commandLine ? { commandLine } : null;
+}
+function caseInsensitive(platform) {
+    // 与 PathKit.samePath 同口径：win32/darwin 大小写不敏感，linux 严格
+    return isWin32(platform) || platform === 'darwin';
+}
+/**
+ * 引号感知的命令行 tokenizer：双引号段不按空白拆分。CIM 的 CommandLine 里
+ * "C:\Program Files\nodejs\node.exe" 这类含空格路径必须整段保留，朴素
+ * split(/\s+/) 会切碎 token 导致身份假阴性。
+ */
+export function tokenizeCommandLine(commandLine) {
+    const tokens = [];
+    let current = '';
+    let hasContent = false;
+    let inQuotes = false;
+    for (const ch of commandLine) {
+        if (ch === '"') {
+            inQuotes = !inQuotes;
+            // 空引号段也是 token 内容（"" x 与 x 不同），与 cmd 的近似语义一致
+            hasContent = true;
+        }
+        else if (!inQuotes && /\s/.test(ch)) {
+            if (hasContent)
+                tokens.push(current);
+            current = '';
+            hasContent = false;
+        }
+        else {
+            current += ch;
+            hasContent = true;
+        }
+    }
+    if (hasContent)
+        tokens.push(current);
+    return tokens;
+}
+/** 取命令行 token 的「去掉扩展名的 basename」，用于与期望二进制名比较。 */
+function tokenBinaryName(token, platform) {
+    let text = token.trim();
+    if (text.length >= 2 &&
+        ((text.startsWith('"') && text.endsWith('"')) || (text.startsWith("'") && text.endsWith("'")))) {
+        text = text.slice(1, -1);
+    }
+    // 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;
+    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 场景会误杀无辜进程）。
+ */
+function commandLineMatches(commandLine, want, platform) {
+    const tokens = tokenizeCommandLine(commandLine);
+    const first = tokens[0];
+    if (first !== undefined && tokenBinaryName(first, platform) === want)
+        return true;
+    return tokens
+        .slice(1)
+        .some((token) => /[/\\]/.test(token) && tokenBinaryName(token, platform) === want);
+}
+/**
+ * pid 身份验证：进程存活且命令行确实属于期望二进制（+ CreationDate 一致）才 true。
+ *
+ * 用于 killOrphan 与实例锁陈旧判定——只有这里返回 true 才允许动手。
+ */
+export async function verifyPidIdentity(pid, opts) {
+    const platform = opts.platform ?? currentPlatform;
+    const identity = await queryProcessIdentity(pid, opts);
+    if (!identity)
+        return false;
+    const want = caseInsensitive(platform) ? opts.expectedBinary.toLowerCase() : opts.expectedBinary;
+    if (!commandLineMatches(identity.commandLine, want, platform))
+        return false;
+    // CreationDate 仅在 pid 文件带了第三行时才比对（旧文件缺字段 → 退化为命令行匹配）
+    const expected = opts.expectedCreationDate?.trim();
+    if (expected)
+        return identity.creationDate === expected;
+    return true;
+}
+//# sourceMappingURL=identity.js.map

package/dist/platform/path.d.ts

@@ -0,0 +1,24 @@
+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）。
+ *
+ * 只可用于**定位**目录，绝不可反解回 cwd——cwd 必须从 JSONL 内容读取
+ * （回归 2026-06-21 /resume & /cd 路径错乱）。
+ *
+ * posix：`/` → `-`（`_` 同样归一，与 Claude Code 一致）。
+ * win32：`\` 与 `/` **都是**分隔符、`:` 是非法文件名字符，三者都必须归一，
+ * 否则 `C:\Users\x\proj` 会原样拼进目录名，mkdir/stat 必然失败。
+ * 反过来，posix 上 `:` 是**合法**文件名字符，不能动——否则既有目录定位不到。
+ */
+export declare function encodeProjectDirName(cwd: string, opts?: PathOptions): string;
+export declare function displayName(p: string, opts?: PathOptions): string;

package/dist/platform/path.js

@@ -0,0 +1,110 @@
+/**
+ * PathKit — 跨平台路径语义（design.md §5.1）。
+ *
+ * 所有 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;
+    }
+}
+export function samePath(a, b, opts) {
+    const { platform } = resolveOptions(opts);
+    if (platform === 'linux')
+        return a === b;
+    if (isWin32(platform)) {
+        // win32：\ 与 / 都是分隔符，且路径大小写不敏感
+        const norm = (p) => p.replaceAll('\\', '/').replace(/\/+$/, '');
+        return norm(a).toLowerCase() === norm(b).toLowerCase();
+    }
+    // darwin：默认按大小写不敏感处理（macOS 默认文件系统 APFS 不敏感）；
+    // 反斜杠是合法文件名字符，不动。分隔符只有 /。
+    // 假设标注：大小写敏感 APFS/HFS+ 卷上 /Users/A 与 /Users/a 实为两个目录，
+    // 此处会判等（cwd 守卫假阳性）——影响面小（默认卷不敏感），如需精确需
+    // 逐目录 stat 探测卷大小写属性，暂不做。
+    // 尾部分隔符必须与 win32 同口径忽略，否则 `/cd ~/repo/` 与 `/cd ~/repo`
+    // 会被判成两个目录，M2 迁移后直接表现为会话目录错配。
+    const norm = (p) => p.replace(/\/+$/, '');
+    return norm(a).toLowerCase() === norm(b).toLowerCase();
+}
+/**
+ * cwd → 会话项目目录名（Claude/pi 的 on-disk 编码，lossy N-to-N）。
+ *
+ * 只可用于**定位**目录，绝不可反解回 cwd——cwd 必须从 JSONL 内容读取
+ * （回归 2026-06-21 /resume & /cd 路径错乱）。
+ *
+ * posix：`/` → `-`（`_` 同样归一，与 Claude Code 一致）。
+ * win32：`\` 与 `/` **都是**分隔符、`:` 是非法文件名字符，三者都必须归一，
+ * 否则 `C:\Users\x\proj` 会原样拼进目录名，mkdir/stat 必然失败。
+ * 反过来，posix 上 `:` 是**合法**文件名字符，不能动——否则既有目录定位不到。
+ */
+export function encodeProjectDirName(cwd, opts) {
+    const { platform } = resolveOptions(opts);
+    return isWin32(platform)
+        ? cwd.replace(/[/\\:]/g, '-').replace(/_/g, '-')
+        : cwd.replace(/\//g, '-').replace(/_/g, '-');
+}
+export function displayName(p, opts) {
+    const { platform } = resolveOptions(opts);
+    // 必须用与注入 platform 对应的 path 实现，而非宿主 `path`：宿主为 win32 时
+    // `path.basename` 会把 `\` 当分隔符，posix 语义（反斜杠是合法文件名字符）
+    // 就被宿主机悄悄改写。win32/posix 各用各的实现后，结果与宿主无关。
+    return isWin32(platform) ? path.win32.basename(p) : path.posix.basename(p);
+}
+//# sourceMappingURL=path.js.map

package/dist/platform/select.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 平台选择的唯一入口（design.md §2.2 纪律）。
+ *
+ * `process.platform` 的读取只允许发生在本文件；其余模块一律导入
+ * `currentPlatform` / `isWin32`，或接受显式 platform 参数（便于在任意
+ * 宿主上单测 win32 语义）。
+ */
+export declare const currentPlatform: NodeJS.Platform;
+export declare function isWin32(platform?: NodeJS.Platform): boolean;

package/dist/platform/select.js

@@ -0,0 +1,12 @@
+/**
+ * 平台选择的唯一入口（design.md §2.2 纪律）。
+ *
+ * `process.platform` 的读取只允许发生在本文件；其余模块一律导入
+ * `currentPlatform` / `isWin32`，或接受显式 platform 参数（便于在任意
+ * 宿主上单测 win32 语义）。
+ */
+export const currentPlatform = process.platform;
+export function isWin32(platform = currentPlatform) {
+    return platform === 'win32';
+}
+//# sourceMappingURL=select.js.map

package/dist/platform/shell.d.ts

@@ -0,0 +1,51 @@
+/**
+ * ShellBackend：把 `!` 命令与 kimi ACP terminal 的 shell 依赖收进 seam
+ * （design.md §7.2）。
+ *
+ * - posix：`bash -c <command>`（与现状 BashProcessRunner 同语义）；
+ * - win32：默认 Git Bash（`bash.exe -c <command>`），powershell / cmd 仅作为
+ *   显式用户选择 §7.3；
+ * - 首版不做命令翻译器：Git Bash 缺失时抛 {@link ShellUnavailableError}，
+ *   由调用方转成明确错误卡（提示需要 Git Bash）。
+ *
+ * kimi ACP 的 terminal/create 固定 `bash -c`，因此 Git Bash 不是 `!` 的专属
+ * 需求，而是 kimi agent 在 Windows 上可用的前置条件（§4.4）。
+ */
+import type { ChildProcess, SpawnOptions } from 'node:child_process';
+import { type ResolveOptions, type LaunchSpec } from './command.js';
+export type ShellKind = 'bash' | 'powershell' | 'cmd';
+export interface ShellBackend {
+    readonly kind: ShellKind;
+    /**
+     * 执行 command。`options` 透传给底层 spawn（如 stdio/detached）；
+     * win32 会强制附加 `windowsHide: true`，调用方无法覆盖。
+     */
+    spawn(command: string, opts: {
+        cwd: string;
+        options?: SpawnOptions;
+    }): ChildProcess;
+}
+/** shell 不可用（如 win32 上没装 Git Bash）：调用方应转成明确错误卡。 */
+export declare class ShellUnavailableError extends Error {
+    readonly kind: ShellKind;
+    constructor(kind: ShellKind, message: string);
+}
+export type SpawnLike = (file: string, args: readonly string[], opts?: SpawnOptions) => ChildProcess;
+export interface ShellBackendDeps {
+    /** 平台注入（测试用）；默认当前宿主平台 */
+    platform?: NodeJS.Platform;
+    /** win32 下的后端选择：默认 bash（Git Bash） */
+    kind?: ShellKind;
+    /** spawn 注入（测试用）；默认 platform/spawn 的 cross-spawn 包装 */
+    spawn?: SpawnLike;
+    /** PATH 注入（测试 / 守护 env 用）；win32 解析 bash.exe 时透传 */
+    pathEnv?: string;
+    /** 命令解析注入（测试用）；默认 resolveExecutable */
+    resolve?: (name: string, opts?: ResolveOptions) => LaunchSpec | null;
+}
+/** posix bash 后端：`bash -c <command>`。 */
+export declare function createBashShellBackend(deps?: ShellBackendDeps): ShellBackend;
+/** win32 后端：默认 Git Bash，powershell/cmd 为显式用户选择。 */
+export declare function createWin32ShellBackend(deps?: ShellBackendDeps): ShellBackend;
+/** 平台分发的唯一入口：posix → bash，win32 → 默认 Git Bash。 */
+export declare function createShellBackend(deps?: ShellBackendDeps): ShellBackend;

package/dist/platform/shell.js

@@ -0,0 +1,75 @@
+import { currentPlatform, isWin32 } from './select.js';
+import { resolveExecutable } from './command.js';
+import { spawnProcess } from './spawn.js';
+/** shell 不可用（如 win32 上没装 Git Bash）：调用方应转成明确错误卡。 */
+export class ShellUnavailableError extends Error {
+    kind;
+    constructor(kind, message) {
+        super(message);
+        this.name = 'ShellUnavailableError';
+        this.kind = kind;
+    }
+}
+/** posix bash 后端：`bash -c <command>`。 */
+export function createBashShellBackend(deps = {}) {
+    const spawnFn = deps.spawn ?? spawnProcess;
+    return {
+        kind: 'bash',
+        spawn(command, opts) {
+            return spawnFn('bash', ['-c', command], { cwd: opts.cwd, ...opts.options });
+        },
+    };
+}
+/** win32 后端：默认 Git Bash，powershell/cmd 为显式用户选择。 */
+export function createWin32ShellBackend(deps = {}) {
+    const spawnFn = deps.spawn ?? spawnProcess;
+    const kind = deps.kind ?? 'bash';
+    if (kind === 'powershell') {
+        return {
+            kind,
+            spawn(command, opts) {
+                return spawnFn('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', command], {
+                    cwd: opts.cwd,
+                    ...opts.options,
+                    windowsHide: true,
+                });
+            },
+        };
+    }
+    if (kind === 'cmd') {
+        return {
+            kind,
+            spawn(command, opts) {
+                return spawnFn('cmd.exe', ['/d', '/s', '/c', command], {
+                    cwd: opts.cwd,
+                    ...opts.options,
+                    windowsHide: true,
+                });
+            },
+        };
+    }
+    return {
+        kind: 'bash',
+        spawn(command, opts) {
+            const resolve = deps.resolve ?? resolveExecutable;
+            const spec = resolve('bash', { platform: 'win32', pathEnv: deps.pathEnv });
+            if (!spec) {
+                throw new ShellUnavailableError('bash', 'Windows 上执行 bash 命令需要 Git Bash（未在 PATH 中找到 bash.exe）；' +
+                    '请安装 Git for Windows 后重试');
+            }
+            // 执行语义由 cross-spawn 负责（垫片 cmd.exe 受控执行）；这里只保证
+            // bash 存在性并给出明确的「需要 Git Bash」错误
+            return spawnFn(spec.file, ['-c', command], {
+                cwd: opts.cwd,
+                ...opts.options,
+                windowsHide: true,
+            });
+        },
+    };
+}
+/** 平台分发的唯一入口：posix → bash，win32 → 默认 Git Bash。 */
+export function createShellBackend(deps = {}) {
+    const platform = deps.platform ?? currentPlatform;
+    return isWin32(platform) ? createWin32ShellBackend(deps) : createBashShellBackend(deps);
+}
+//# sourceMappingURL=shell.js.map

package/dist/platform/spawn.d.ts

@@ -0,0 +1,41 @@
+import type { ChildProcess, SpawnOptions, SpawnSyncOptions } from 'node:child_process';
+import type { SpawnSyncReturns } from 'child_process';
+/**
+ * cross-spawn 包装：posix 直通，win32 PATHEXT + 垫片 cmd.exe 受控执行。
+ *
+ * 默认注入 `windowsHide: true`：win32 上 .cmd/.bat 垫片经 cmd.exe 执行时，
+ * 不加该选项会闪控制台窗口（测试批量拉起 mock agent 时尤其明显）。该选项
+ * 在 posix 上被 Node 直接忽略（Windows-only），因此默认值零跨平台影响；
+ * 调用方显式传 `windowsHide: false` 仍可覆盖。
+ */
+export declare function spawnProcess(command: string, args?: readonly string[], options?: SpawnOptions): ChildProcess;
+/** cross-spawn 同步版（一次性命令探测/目录查询用）。默认注入同 {@link spawnProcess}。 */
+export declare function spawnProcessSync(command: string, args?: readonly string[], options?: SpawnSyncOptions): SpawnSyncReturns<string | Buffer>;
+/**
+ * env 覆盖合并：先按不区分大小写删除 base 中的同名旧键，再设新值。
+ * Windows env 键大小写不敏感，`{...process.env, PATH:x}` 会产生 `PATH`/`Path`
+ * 双键（§8.3）。注意 posix 上并非普通 spread：base 中大小写不同名的键（如
+ * `Path`）也会被删除，而非与 `PATH` 并存——可接受（posix 语义键为全大写
+ * `PATH`，大小写变体本身就不是语义键），但语义与 spread 不同，勿混淆。
+ */
+export declare function mergeProcessEnv(base?: NodeJS.ProcessEnv, overrides?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+/**
+ * 是否需要为子进程建独立进程组（`spawn` 的 `detached: true`）。
+ *
+ * posix：ProcessStopper 的组杀用负 PID（`kill(-pgid)`），子进程必须是组长，
+ * 否则 kill 抛 ESRCH 被吞，停止/清理链路全失效。
+ *
+ * win32：组杀已由 terminator 的 `taskkill /PID <pid> /T /F` 树杀替代，不需要
+ * 进程组；而 `detached: true` 会让 **`.cmd` 垫片丢掉父进程的 stdio 管道** ——
+ * Windows 上 `DETACHED_PROCESS` 下 cmd.exe 另建控制台并重绑标准句柄，于是
+ * 子进程（npm 安装的 agent 全是 `.cmd` 垫片）的 stdout/stderr 永不抵达父进程，
+ * 表现为 agent 全程静默、turn 超时。实测 `windowsHide: true` 不能改善，
+ * 因此 v1 §3.3「保留 detached + windowsHide」的假设据此修正为「win32 不
+ * detached」。调用方应同时传 `windowsHide: true`，避免 cmd.exe 闪控制台窗口。
+ */
+export declare function useDetachedProcessGroup(platform?: NodeJS.Platform): boolean;
+/**
+ * win32 command-not-found 行嗅探（§4.4）：命中即视为「命令缺失」失败而非
+ * 普通非零退出。platform 注入使其在任意宿主可测。
+ */
+export declare function isWindowsCommandNotFoundLine(line: string, platform?: NodeJS.Platform): boolean;

package/dist/platform/spawn.js

@@ -0,0 +1,77 @@
+/**
+ * spawn 统一收口。
+ *
+ * 全部子进程拉起必须走本模块，禁止直接 child_process.spawn：
+ * - cross-spawn 在 posix 是 child_process.spawn 直通（零行为差异）；win32 上
+ *   做 PATHEXT 解析，.cmd/.bat 经 cmd.exe 以正确的引号转义执行——取代 v1 的
+ *   手写垫片解析层；
+ * - mergeProcessEnv：Windows env 键大小写不敏感，直接 `{...process.env, PATH:x}`
+ *   在键为 `Path` 的机器上产生双键、子进程行为未定义——任何 env 覆盖注入点
+ *   必须经它合并（先按不区分大小写删旧键再设新值）；
+ * - isWindowsCommandNotFoundLine：win32 经 cmd 垫片启动失败不是 spawn 的
+ *   error 事件 ENOENT，而是子进程往 stderr 打
+ *   "'xxx' is not recognized as an internal or external command"（§4.4）。
+ */
+import crossSpawn from 'cross-spawn';
+import { currentPlatform, isWin32 } from './select.js';
+/**
+ * cross-spawn 包装：posix 直通，win32 PATHEXT + 垫片 cmd.exe 受控执行。
+ *
+ * 默认注入 `windowsHide: true`：win32 上 .cmd/.bat 垫片经 cmd.exe 执行时，
+ * 不加该选项会闪控制台窗口（测试批量拉起 mock agent 时尤其明显）。该选项
+ * 在 posix 上被 Node 直接忽略（Windows-only），因此默认值零跨平台影响；
+ * 调用方显式传 `windowsHide: false` 仍可覆盖。
+ */
+export function spawnProcess(command, args = [], options = {}) {
+    return crossSpawn(command, [...args], { windowsHide: true, ...options });
+}
+/** cross-spawn 同步版（一次性命令探测/目录查询用）。默认注入同 {@link spawnProcess}。 */
+export function spawnProcessSync(command, args = [], options = {}) {
+    return crossSpawn.sync(command, [...args], { windowsHide: true, ...options });
+}
+/**
+ * env 覆盖合并：先按不区分大小写删除 base 中的同名旧键，再设新值。
+ * Windows env 键大小写不敏感，`{...process.env, PATH:x}` 会产生 `PATH`/`Path`
+ * 双键（§8.3）。注意 posix 上并非普通 spread：base 中大小写不同名的键（如
+ * `Path`）也会被删除，而非与 `PATH` 并存——可接受（posix 语义键为全大写
+ * `PATH`，大小写变体本身就不是语义键），但语义与 spread 不同，勿混淆。
+ */
+export function mergeProcessEnv(base = process.env, overrides = {}) {
+    const out = { ...base };
+    for (const [key, value] of Object.entries(overrides)) {
+        for (const existing of Object.keys(out)) {
+            if (existing.toLowerCase() === key.toLowerCase()) {
+                delete out[existing];
+            }
+        }
+        if (value !== undefined)
+            out[key] = value;
+    }
+    return out;
+}
+const COMMAND_NOT_FOUND_PATTERN = /is not recognized as an internal or external command|operable program or batch file/i;
+/**
+ * 是否需要为子进程建独立进程组（`spawn` 的 `detached: true`）。
+ *
+ * posix：ProcessStopper 的组杀用负 PID（`kill(-pgid)`），子进程必须是组长，
+ * 否则 kill 抛 ESRCH 被吞，停止/清理链路全失效。
+ *
+ * win32：组杀已由 terminator 的 `taskkill /PID <pid> /T /F` 树杀替代，不需要
+ * 进程组；而 `detached: true` 会让 **`.cmd` 垫片丢掉父进程的 stdio 管道** ——
+ * Windows 上 `DETACHED_PROCESS` 下 cmd.exe 另建控制台并重绑标准句柄，于是
+ * 子进程（npm 安装的 agent 全是 `.cmd` 垫片）的 stdout/stderr 永不抵达父进程，
+ * 表现为 agent 全程静默、turn 超时。实测 `windowsHide: true` 不能改善，
+ * 因此 v1 §3.3「保留 detached + windowsHide」的假设据此修正为「win32 不
+ * detached」。调用方应同时传 `windowsHide: true`，避免 cmd.exe 闪控制台窗口。
+ */
+export function useDetachedProcessGroup(platform = currentPlatform) {
+    return !isWin32(platform);
+}
+/**
+ * win32 command-not-found 行嗅探（§4.4）：命中即视为「命令缺失」失败而非
+ * 普通非零退出。platform 注入使其在任意宿主可测。
+ */
+export function isWindowsCommandNotFoundLine(line, platform = currentPlatform) {
+    return platform === 'win32' && COMMAND_NOT_FOUND_PATTERN.test(line);
+}
+//# sourceMappingURL=spawn.js.map

package/dist/platform/terminator-posix.d.ts

@@ -0,0 +1,38 @@
+/**
+ * posix 终止器：`src/runner/common/process-stopper.ts` 的原样迁移（design.md §3.2）。
+ *
+ * 语义与迁移前逐条对齐：SIGTERM 打负 PID 进程组 → 等 graceMs → SIGKILL；
+ * immediate 则两个信号连发。本次只新增两样东西：
+ *   - 返回 {@link TerminateResult} 让终止途经可观测（与 win32 同构）；
+ *   - `cleanupOnExit`（Terminator 接口要求的进程级退出清理）。
+ *
+ * `ProcessStopper` 保留为兼容壳：行为（含日志文案）零变化，既有调用方与
+ * 测试无需改动；M2 调用点迁移时逐个换成 Terminator 后即可删除。
+ */
+import type { ChildProcess } from 'node:child_process';
+import type { Terminator } from './terminator.js';
+export type LogLevel = 'debug' | 'info';
+export type TerminatorLogger = (level: LogLevel, message: string) => void;
+export interface PosixTerminatorDeps {
+    /** 优雅等待窗口（毫秒），对应现状 stopGraceMs */
+    graceMs: number;
+    /** 日志注入（测试用）；默认 logger 单例 */
+    log?: TerminatorLogger;
+}
+export declare function createPosixTerminator(deps: PosixTerminatorDeps): Terminator;
+interface ProcessStopperOptions {
+    graceMs: number;
+}
+interface StopOptions {
+    immediate?: boolean;
+}
+/**
+ * 迁移前的类名（兼容壳）：返回 void、接受 null proc。
+ * 新代码请用 {@link createPosixTerminator} / `createTerminator`。
+ */
+export declare class ProcessStopper {
+    private graceMs;
+    constructor(opts: ProcessStopperOptions);
+    stop(proc: ChildProcess | null, opts?: StopOptions): Promise<void>;
+}
+export {};