lark-remote 0.1.13 → 0.2.1

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 {};

package/dist/platform/terminator-posix.js

@@ -0,0 +1,103 @@
+import { getLogger } from '../logger/index.js';
+/** 默认日志出口：与迁移前同级别（debug 记信号，info 记 grace 超时）。 */
+function defaultLog(level, message) {
+    const logger = getLogger();
+    if (level === 'debug')
+        logger.debug(message);
+    else
+        logger.info(message);
+}
+/** 退出判定统一口径（CLAUDE.md 红线）：exitCode !== null || signalCode !== null。 */
+function isAlive(proc) {
+    return proc.exitCode === null && proc.signalCode === null;
+}
+async function stopPosix(proc, opts, log) {
+    if (!isAlive(proc)) {
+        return { requested: false, via: 'already-exited' };
+    }
+    const pid = proc.pid;
+    if (pid === undefined) {
+        return { requested: false, via: 'already-exited' };
+    }
+    // 负 PID = 整个进程组：shell 包装层与孙进程一并带走
+    const pgid = -pid;
+    log('debug', `[process-stopper] sending SIGTERM to pgid=${pgid} immediate=${opts.immediate}`);
+    try {
+        process.kill(pgid, 'SIGTERM');
+    }
+    catch {
+        /* process may have exited */
+    }
+    if (opts.immediate) {
+        // 不等待：SIGKILL 紧随其后；进程已死时 kill 抛 ESRCH，忽略即可
+        try {
+            process.kill(pgid, 'SIGKILL');
+        }
+        catch {
+            /* process already gone */
+        }
+        return { requested: true, via: 'taskkill' };
+    }
+    // 与 exit 事件竞速等 grace；用 once 避免重复 stop() 累积监听器（P2-15）
+    let graceTimer;
+    const exited = await Promise.race([
+        new Promise((resolve) => {
+            if (!isAlive(proc))
+                return resolve(true);
+            proc.once('exit', () => resolve(true));
+        }),
+        new Promise((resolve) => {
+            graceTimer = setTimeout(() => resolve(false), opts.graceMs);
+        }),
+    ]);
+    if (graceTimer)
+        clearTimeout(graceTimer);
+    if (!exited) {
+        log('info', `[process-stopper] process group ${pgid} did not exit within grace period, sending SIGKILL`);
+        try {
+            process.kill(pgid, 'SIGKILL');
+        }
+        catch {
+            /* process already gone */
+        }
+        return { requested: true, via: 'taskkill' };
+    }
+    return { requested: true, via: 'cooperative' };
+}
+export function createPosixTerminator(deps) {
+    const log = deps.log ?? defaultLog;
+    return {
+        stop(proc, opts) {
+            return stopPosix(proc, { graceMs: deps.graceMs, immediate: opts.immediate }, log);
+        },
+        cleanupOnExit(proc) {
+            if (!isAlive(proc))
+                return;
+            const pid = proc.pid;
+            if (pid === undefined)
+                return;
+            try {
+                process.kill(-pid, 'SIGKILL');
+            }
+            catch {
+                /* process already gone */
+            }
+        },
+    };
+}
+/**
+ * 迁移前的类名（兼容壳）：返回 void、接受 null proc。
+ * 新代码请用 {@link createPosixTerminator} / `createTerminator`。
+ */
+export class ProcessStopper {
+    graceMs;
+    constructor(opts) {
+        this.graceMs = opts.graceMs;
+    }
+    async stop(proc, opts) {
+        if (!proc)
+            return;
+        await stopPosix(proc, { graceMs: this.graceMs, immediate: opts?.immediate === true }, defaultLog);
+    }
+}
+//# sourceMappingURL=terminator-posix.js.map

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

@@ -0,0 +1,21 @@
+import type { ChildProcess, SpawnOptions } from 'node:child_process';
+import type { Terminator } from './terminator.js';
+import { AgentStopperRegistry } from './agent-stopper.js';
+export type SpawnLike = (file: string, args: string[], opts?: SpawnOptions) => ChildProcess;
+/** 等待 graceMs 与 exit 事件竞速；返回 true 表示等待结束后进程仍存活。 */
+export type WaitForExit = (proc: ChildProcess, ms: number) => Promise<boolean>;
+export interface Win32TerminatorDeps {
+    /** 协议停止后的优雅等待窗口（毫秒），对应 posix 的 stopGraceMs */
+    graceMs: number;
+    /** 当前 run 所属 agent：用于查协议停止通道；缺省视为无通道 */
+    agent?: string;
+    /** 协议通道注册表注入（测试隔离）；默认进程级单例 */
+    stoppers?: AgentStopperRegistry;
+    /** spawn 注入（测试用）；默认 node:child_process */
+    spawn?: SpawnLike;
+    /** grace 等待器注入（测试用）；默认与 exit 事件竞速 */
+    waitForExit?: WaitForExit;
+    /** 日志注入：本模块处于 seam 底层，不反向依赖 logger 单例 */
+    log?: (message: string) => void;
+}
+export declare function createWin32Terminator(deps: Win32TerminatorDeps): Terminator;

package/dist/platform/terminator-win32.js

@@ -0,0 +1,110 @@
+/**
+ * win32 终止器：协议停止通道 → grace 等待 → taskkill 树杀（design.md §3.2）。
+ *
+ * 状态机：
+ *   1. 进程已退出 → nothing（via='already-exited'）
+ *   2. immediate  → taskkill /PID <pid> /T /F
+ *   3. 优雅       → AgentStopperRegistry 查协议通道
+ *      - 无通道：打日志显式跳过优雅段（不等一个不会来的退出事件）→ 直接树杀
+ *      - 有通道：调用后与 exit 事件竞速等 graceMs，仍存活 → 树杀
+ *
+ * 依赖（spawn / 等待器 / 日志）全部构造注入，win32 语义可在任意宿主上单测。
+ */
+import { spawn as nodeSpawn } from 'node:child_process';
+import { agentStopperRegistry } from './agent-stopper.js';
+/** 退出判定统一口径（CLAUDE.md 红线）：exitCode !== null || signalCode !== null。 */
+function isAlive(proc) {
+    return proc.exitCode === null && proc.signalCode === null;
+}
+/** 默认等待器：exit 事件与定时器竞速，谁先到算谁。 */
+async function defaultWaitForExit(proc, ms) {
+    if (!isAlive(proc))
+        return false;
+    return new Promise((resolve) => {
+        let settled = false;
+        const onExit = () => finish(false);
+        const finish = (alive) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            proc.removeListener('exit', onExit);
+            resolve(alive);
+        };
+        proc.on('exit', onExit);
+        const timer = setTimeout(() => finish(isAlive(proc)), ms);
+    });
+}
+export function createWin32Terminator(deps) {
+    const spawnFn = deps.spawn ?? nodeSpawn;
+    const stoppers = deps.stoppers ?? agentStopperRegistry;
+    const waitForExit = deps.waitForExit ?? defaultWaitForExit;
+    const log = deps.log;
+    /** 树杀：taskkill /PID <pid> /T /F —— posix 负 PID 组杀的等价物。 */
+    function killTree(pid) {
+        if (pid === undefined) {
+            log?.(`win32 树杀跳过：子进程没有 pid（spawn 未成功）`);
+            return;
+        }
+        try {
+            // fire-and-forget：不等 taskkill 自身返回，退出由 proc 的 exit 事件驱动
+            const killer = spawnFn('taskkill', ['/PID', String(pid), '/T', '/F'], {
+                stdio: 'ignore',
+                windowsHide: true,
+            });
+            killer?.on?.('error', () => {
+                // taskkill 拉起失败不致命：调用方仍可走 killOrphan / 陈旧锁自愈
+            });
+        }
+        catch (error) {
+            log?.(`win32 树杀失败：taskkill 拉起异常 ${String(error)}`);
+        }
+    }
+    return {
+        async stop(proc, opts) {
+            if (!isAlive(proc))
+                return { requested: false, via: 'already-exited' };
+            if (proc.pid === undefined) {
+                // 与 posix 同口径：拿不到 pid 就没有可请求的终止目标，不能谎报 requested
+                log?.('win32 停止跳过：子进程没有 pid（spawn 未成功），按已退出处理');
+                return { requested: false, via: 'already-exited' };
+            }
+            if (opts.immediate) {
+                killTree(proc.pid);
+                return { requested: true, via: 'taskkill' };
+            }
+            const agent = deps.agent;
+            const stopper = agent === undefined ? undefined : stoppers.get(agent);
+            if (!stopper) {
+                // 无通道是合法状态：显式记录后走树杀，不做无意义的优雅空转
+                log?.(`win32 优雅停止跳过：agent=${agent ?? '(unknown)'} 无协议停止通道，直接树杀`);
+                killTree(proc.pid);
+                return { requested: true, via: 'skipped-no-channel' };
+            }
+            try {
+                await stopper(proc);
+            }
+            catch (error) {
+                // 通道异常不能吞掉终止流程：记录后继续走树杀兜底
+                log?.(`win32 协议停止通道异常，转入树杀：${String(error)}`);
+            }
+            if (!isAlive(proc))
+                return { requested: true, via: 'cooperative' };
+            const stillAlive = await waitForExit(proc, deps.graceMs);
+            if (!stillAlive)
+                return { requested: true, via: 'cooperative' };
+            killTree(proc.pid);
+            return { requested: true, via: 'taskkill' };
+        },
+        cleanupOnExit(proc) {
+            // M0 真机验证项（§9.2 矩阵）：本方法在 process.on('exit') 里调用，而
+            // killTree 依赖 libuv uv_spawn 在 exit handler 内同步发起 taskkill——
+            // 大概率可用（uv_spawn 本身同步），但与 posix 路径（同步 process.kill）
+            // 可靠性不等价；失败表现为 win32 上 bridge 退出后 agent 变孤儿。
+            if (!isAlive(proc))
+                return;
+            killTree(proc.pid);
+        },
+    };
+}
+//# sourceMappingURL=terminator-win32.js.map

package/dist/platform/terminator.d.ts

@@ -0,0 +1,44 @@
+/**
+ * 平台终止器 seam 的接口层（design.md §3.2 / §3.3）。
+ *
+ * Windows 没有可拦截的跨进程 SIGTERM、负 PID 无效，因此把「进程组 + 信号」
+ * 换成「协议停止通道 + 进程树杀」。本文件只放接口与平台分发，实现见
+ * terminator-posix.ts / terminator-win32.ts。
+ */
+import type { ChildProcess } from 'node:child_process';
+import type { AgentStopperRegistry } from './agent-stopper.js';
+import type { TerminateResult } from './types.js';
+export { AgentStopperRegistry, agentStopperRegistry } from './agent-stopper.js';
+export type { AgentStopper } from './agent-stopper.js';
+/**
+ * 进程终止器。
+ *
+ * `stop` 的 `immediate` 语义与现状 `process-stopper` 的 `stop({immediate})` 对齐。
+ * 设计文档声明返回 `Promise<void>`，这里收窄为 {@link TerminateResult}：降级
+ * 必须可观测（优雅段被跳过、走了树杀、进程早已退出），否则 win32 上「等一个
+ * 不会来的退出事件」这类退化无法被发现。
+ */
+export interface Terminator {
+    stop(proc: ChildProcess, opts: {
+        immediate: boolean;
+    }): Promise<TerminateResult>;
+    /** 进程级退出清理：fire-and-forget 强杀 */
+    cleanupOnExit(proc: ChildProcess): void;
+}
+export interface TerminatorDeps {
+    /** 优雅等待窗口（毫秒）；win32 为协议停止后的等待，posix 为 SIGTERM→SIGKILL 的 grace */
+    graceMs: number;
+    /** 平台注入（测试用）；默认当前宿主平台 */
+    platform?: NodeJS.Platform;
+    /** 当前 run 所属 agent（win32 查协议通道用；posix 忽略） */
+    agent?: string;
+    /** 协议通道注册表注入（测试隔离）；默认进程级单例 */
+    stoppers?: AgentStopperRegistry;
+    /** 日志注入（测试用）；默认走 logger 单例 */
+    log?: (level: 'debug' | 'info', message: string) => void;
+}
+/**
+ * 唯一的终止器选择入口：posix 走组杀，win32 走「协议通道 + taskkill 树杀」。
+ * 其余模块一律拿这里的 Terminator，禁止散落平台 if（§2.2）。
+ */
+export declare function createTerminator(deps: TerminatorDeps): Terminator;

package/dist/platform/terminator.js

@@ -0,0 +1,24 @@
+import { currentPlatform, isWin32 } from './select.js';
+import { createPosixTerminator } from './terminator-posix.js';
+import { createWin32Terminator } from './terminator-win32.js';
+// 注册表实现在 agent-stopper.ts（避免与 terminator-win32.ts 循环依赖），
+// 这里 re-export 以维持调用方的单一入口。
+export { AgentStopperRegistry, agentStopperRegistry } from './agent-stopper.js';
+/**
+ * 唯一的终止器选择入口：posix 走组杀，win32 走「协议通道 + taskkill 树杀」。
+ * 其余模块一律拿这里的 Terminator，禁止散落平台 if（§2.2）。
+ */
+export function createTerminator(deps) {
+    const platform = deps.platform ?? currentPlatform;
+    if (isWin32(platform)) {
+        return createWin32Terminator({
+            graceMs: deps.graceMs,
+            agent: deps.agent,
+            stoppers: deps.stoppers,
+            // win32 侧日志不带级别（无 debug 级输出），统一按 info 透传
+            log: deps.log ? (message) => deps.log?.('info', message) : undefined,
+        });
+    }
+    return createPosixTerminator({ graceMs: deps.graceMs, log: deps.log });
+}
+//# sourceMappingURL=terminator.js.map

package/dist/platform/types.d.ts

@@ -0,0 +1,23 @@
+/**
+ * 平台 seam 纯类型。
+ */
+/**
+ * spawn 发现规格 —— resolveExecutable 的产出（v2 §4.3，仅探测/诊断用）。
+ * v2 收窄：.cmd 垫片命中即报告垫片路径本身，不再解析内容定位入口；
+ * 执行统一走 platform/spawn.ts 的 cross-spawn 包装。
+ */
+export interface LaunchSpec {
+    kind: 'direct';
+    /** 可执行文件路径（posix 绝对路径 / win32 含 .cmd 垫片路径） */
+    file: string;
+}
+/** 终止结果（§3.2 win32 状态机产出；可观测降级用）。 */
+export interface TerminateResult {
+    /** 进程是否已确认被请求终止（不代表已退出，退出由 exit 事件驱动） */
+    requested: boolean;
+    /**
+     * 终止途经：协议停止 / 强制终止 / 进程已退出 / 无通道跳过优雅段。
+     * 强制终止在 posix 下是 SIGKILL 组杀、win32 下是 taskkill 树杀，同枚举值。
+     */
+    via: 'cooperative' | 'taskkill' | 'already-exited' | 'skipped-no-channel';
+}

package/dist/platform/types.js

@@ -0,0 +1,5 @@
+/**
+ * 平台 seam 纯类型。
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/restart.js

@@ -1,4 +1,4 @@
-import { spawn } from 'node:child_process';
+import { spawnProcess } from './platform/spawn.js';
 import fs from 'node:fs';
 import path from 'node:path';
 import { getLogger } from './logger/index.js';
@@ -24,10 +24,12 @@ const POLL_MS = 100;
 export function spawnReplacementBridge(logsDir) {
     fs.mkdirSync(logsDir, { recursive: true });
     const out = fs.openSync(path.join(logsDir, 'restart-child.log'), 'a');
-    const child = spawn(process.execPath, process.argv.slice(1), {
+    const child = spawnProcess(process.execPath, process.argv.slice(1), {
         cwd: process.cwd(),
         env: { ...process.env, [RESTART_WAIT_PID_ENV]: String(process.pid) },
         detached: true,
+        // win32：detached 继任者默认会闪控制台窗口（§3.7）
+        windowsHide: true,
         stdio: ['ignore', out, out],
     });
     // Late spawn errors (e.g. binary removed mid-run) must not crash the