lark-remote 0.1.5 → 0.1.7

package/dist/runner/common/jsonrpc/connection-manager.d.ts

@@ -0,0 +1,125 @@
+/**
+ * ConnectionManager: manages agent-server connections per workspace, shared by
+ * all workspace-lifetime JSON-line runners (codex app-server, kimi acp,
+ * opencode acp, and pi rpc).
+ *
+ * Each workspace gets its own connection (transport + client). Connections are
+ * created on demand via `acquire()`, cached for reuse, and released after an
+ * idle timeout (30 minutes default).
+ *
+ * The manager is protocol-agnostic over the concrete client. The default
+ * `clientFactory` builds a JsonRpcClient with the `initialize` handshake (the
+ * ACP-style reference protocol); protocols that are NOT JSON-RPC (pi's
+ * `--mode rpc`, which has no handshake and binds the session at spawn) inject
+ * their own `clientFactory` + `buildArgs` + `shouldReuse` + `bindSession`.
+ */
+import { JsonlRpcTransport } from './transport.js';
+import { JsonRpcClient } from './client.js';
+/** Minimal client surface the manager needs from any protocol client. */
+export interface ConnectionClient {
+    ready: boolean;
+    healthy: boolean;
+    connect(): Promise<unknown>;
+    dispose(): Promise<void>;
+}
+/** Request context for acquire() — currently only an optional session id. */
+export interface AcquireRequest {
+    sessionId?: string;
+}
+/** Context passed to clientFactory to build + wire a concrete client. */
+export interface ClientFactoryContext {
+    transport: JsonlRpcTransport;
+    requestTimeoutMs: number;
+    /** Wire into the client's close callback so slot cleanup + onConnectionLost fire. */
+    baseOnClose: () => void;
+}
+export interface ConnectionManagerOptions<TClient extends ConnectionClient = JsonRpcClient> {
+    /** Path to the server binary. */
+    binary: string;
+    /**
+     * Args to spawn the server with. Defaults to `[]` — each protocol's runner
+     * injects its own default (e.g. codex `['app-server', '--stdio']`, kimi
+     * `['acp']`).
+     */
+    args?: string[];
+    /**
+     * Optional arg builder over the acquire request — used by protocols that bind
+     * a session at spawn (pi: `--session-id`). Defaults to `() => this.args`.
+     */
+    buildArgs?: (req: AcquireRequest) => string[];
+    /** Environment variables to pass to the binary. */
+    env?: Record<string, string | undefined>;
+    /** Request timeout in milliseconds. */
+    requestTimeoutMs?: number;
+    /** Idle TTL in milliseconds. */
+    idleTtlMs?: number;
+    /**
+     * Initialize handshake params for the default JsonRpcClient path. Ignored
+     * when `clientFactory` is provided.
+     */
+    initializeParams?: object;
+    /**
+     * Build + wire a concrete protocol client. Defaults to a JsonRpcClient with
+     * the initialize handshake. Non-JSON-RPC protocols inject their own client.
+     */
+    clientFactory?: (ctx: ClientFactoryContext) => TClient;
+    /**
+     * Whether an existing (cached) connection can be reused for a request.
+     * Defaults to `client.ready && client.healthy`. Session-bound protocols (pi)
+     * additionally require the requested session id to match the bound one.
+     */
+    shouldReuse?: (ctx: {
+        client: TClient;
+        req: AcquireRequest;
+        boundSessionId: string | undefined;
+    }) => boolean;
+    /** Log tag prefix for operational log lines. */
+    logTag?: string;
+}
+export declare class ConnectionManager<TClient extends ConnectionClient = JsonRpcClient> {
+    private slots;
+    private readonly binary;
+    private readonly buildArgs;
+    private readonly env;
+    private readonly requestTimeoutMs;
+    private readonly idleTtlMs;
+    private readonly initializeParams;
+    private readonly clientFactory;
+    private readonly shouldReuse;
+    private readonly logTag;
+    /** Callback when a connection is lost — cleared from slot map. */
+    onConnectionLost?: (workspace: string) => void;
+    constructor(opts: ConnectionManagerOptions<TClient>);
+    /**
+     * Acquire a connection for the given workspace.
+     * Creates a new connection if one does not exist or the previous one was lost
+     * (or, for session-bound protocols, bound to a different session).
+     * Serializes creation so concurrent calls share the same connection.
+     */
+    acquire(workspace: string, req?: AcquireRequest): Promise<TClient>;
+    /**
+     * Record the session id a fresh connection actually bound to (e.g. discovered
+     * via a protocol `get_state` after a fresh spawn). This lets a subsequent run
+     * resume the SAME session on the live connection instead of respawning it.
+     */
+    bindSession(workspace: string, sessionId: string): void;
+    /**
+     * Release (dispose) a connection for the given workspace.
+     */
+    release(workspace: string): Promise<void>;
+    /**
+     * Dispose all connections.
+     */
+    disposeAll(): Promise<void>;
+    /**
+     * Notify that the workspace is active — disarm the idle timer.
+     */
+    notifyActivity(workspace: string): void;
+    /**
+     * Notify that the workspace is idle — arm the idle timer.
+     */
+    notifyIdle(workspace: string): void;
+    private createClient;
+    private clearIdleTimer;
+    private disposeSlot;
+}

package/dist/runner/common/jsonrpc/connection-manager.js

@@ -0,0 +1,205 @@
+/**
+ * ConnectionManager: manages agent-server connections per workspace, shared by
+ * all workspace-lifetime JSON-line runners (codex app-server, kimi acp,
+ * opencode acp, and pi rpc).
+ *
+ * Each workspace gets its own connection (transport + client). Connections are
+ * created on demand via `acquire()`, cached for reuse, and released after an
+ * idle timeout (30 minutes default).
+ *
+ * The manager is protocol-agnostic over the concrete client. The default
+ * `clientFactory` builds a JsonRpcClient with the `initialize` handshake (the
+ * ACP-style reference protocol); protocols that are NOT JSON-RPC (pi's
+ * `--mode rpc`, which has no handshake and binds the session at spawn) inject
+ * their own `clientFactory` + `buildArgs` + `shouldReuse` + `bindSession`.
+ */
+import { JsonlRpcTransport } from './transport.js';
+import { JsonRpcClient } from './client.js';
+import { getLogger } from '../../../logger/index.js';
+const DEFAULT_IDLE_TTL_MS = 30 * 60 * 1000; // 30 minutes
+const DEFAULT_REQUEST_TIMEOUT_MS = 60_000; // 60 seconds
+export class ConnectionManager {
+    slots = new Map();
+    binary;
+    buildArgs;
+    env;
+    requestTimeoutMs;
+    idleTtlMs;
+    initializeParams;
+    clientFactory;
+    shouldReuse;
+    logTag;
+    /** Callback when a connection is lost — cleared from slot map. */
+    onConnectionLost;
+    constructor(opts) {
+        this.binary = opts.binary;
+        this.buildArgs = opts.buildArgs ?? (() => opts.args ?? []);
+        this.env = opts.env ?? {};
+        this.requestTimeoutMs = opts.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+        this.idleTtlMs = opts.idleTtlMs ?? DEFAULT_IDLE_TTL_MS;
+        this.initializeParams = opts.initializeParams ?? {};
+        this.clientFactory =
+            opts.clientFactory ??
+                ((ctx) => new JsonRpcClient(ctx.transport, {
+                    onNotification: () => { },
+                    onServerRequest: () => { },
+                    onClose: ctx.baseOnClose,
+                }, ctx.requestTimeoutMs, this.initializeParams));
+        this.shouldReuse = opts.shouldReuse ?? (({ client }) => client.ready && client.healthy);
+        this.logTag = opts.logTag ?? 'jsonrpc-connection-manager';
+    }
+    /**
+     * Acquire a connection for the given workspace.
+     * Creates a new connection if one does not exist or the previous one was lost
+     * (or, for session-bound protocols, bound to a different session).
+     * Serializes creation so concurrent calls share the same connection.
+     */
+    async acquire(workspace, req = {}) {
+        const existing = this.slots.get(workspace);
+        if (existing) {
+            // If a create is in flight, wait for it
+            if (existing.createPromise) {
+                return existing.createPromise;
+            }
+            // Reuse when the (session-aware) reuse predicate holds — e.g. the client
+            // is ready and its transport is alive (default), or it is bound to the
+            // requested session (pi). Otherwise replace it so the next run respawns
+            // the process.
+            if (this.shouldReuse({
+                client: existing.client,
+                req,
+                boundSessionId: existing.boundSessionId,
+            })) {
+                return existing.client;
+            }
+            this.disposeSlot(workspace);
+        }
+        const createPromise = this.createClient(workspace, req);
+        this.slots.set(workspace, {
+            client: null, // placeholder
+            boundSessionId: req.sessionId,
+            idleTimer: null,
+            createPromise,
+        });
+        try {
+            const client = await createPromise;
+            // 竞态：创建期间 release()/disposeAll() 已把 slot 删掉（并可能已
+            // dispose 连接）。此时不能再把新连接塞回 slot——否则会复活一个无人管理、
+            // 无 idle timer 的连接泄漏。归还给调用者继续使用，但不再缓存。
+            const slotAfterCreate = this.slots.get(workspace);
+            if (!slotAfterCreate || slotAfterCreate.createPromise !== createPromise) {
+                return client;
+            }
+            this.slots.set(workspace, {
+                client,
+                boundSessionId: req.sessionId,
+                idleTimer: null,
+                createPromise: null,
+            });
+            return client;
+        }
+        catch (err) {
+            // 只删除自己的槽位：并发 release + 重新 acquire 后 slot 可能已被新的
+            // createPromise 占据，误删会破坏新连接。
+            const current = this.slots.get(workspace);
+            if (current && current.createPromise === createPromise) {
+                this.slots.delete(workspace);
+            }
+            throw err;
+        }
+    }
+    /**
+     * Record the session id a fresh connection actually bound to (e.g. discovered
+     * via a protocol `get_state` after a fresh spawn). This lets a subsequent run
+     * resume the SAME session on the live connection instead of respawning it.
+     */
+    bindSession(workspace, sessionId) {
+        const slot = this.slots.get(workspace);
+        if (slot)
+            slot.boundSessionId = sessionId;
+    }
+    /**
+     * Release (dispose) a connection for the given workspace.
+     */
+    async release(workspace) {
+        this.disposeSlot(workspace);
+    }
+    /**
+     * Dispose all connections.
+     */
+    async disposeAll() {
+        const workspaces = [...this.slots.keys()];
+        await Promise.all(workspaces.map((w) => this.disposeSlot(w)));
+    }
+    /**
+     * Notify that the workspace is active — disarm the idle timer.
+     */
+    notifyActivity(workspace) {
+        const slot = this.slots.get(workspace);
+        if (slot) {
+            this.clearIdleTimer(slot);
+        }
+    }
+    /**
+     * Notify that the workspace is idle — arm the idle timer.
+     */
+    notifyIdle(workspace) {
+        const slot = this.slots.get(workspace);
+        if (slot) {
+            this.clearIdleTimer(slot);
+            slot.idleTimer = setTimeout(() => {
+                getLogger().info(`[${this.logTag}] idle timeout for workspace=${workspace}, releasing connection`);
+                this.disposeSlot(workspace);
+            }, this.idleTtlMs);
+        }
+    }
+    // =========================================================================
+    // Internal
+    // =========================================================================
+    async createClient(workspace, req) {
+        const transport = new JsonlRpcTransport({
+            binary: this.binary,
+            args: this.buildArgs(req),
+            cwd: workspace,
+            env: this.env,
+        });
+        let client = null;
+        client = this.clientFactory({
+            transport,
+            requestTimeoutMs: this.requestTimeoutMs,
+            baseOnClose: () => {
+                getLogger().info(`[${this.logTag}] connection closed workspace=${workspace}`);
+                // 只清理自己创建的 slot：并发 release + 重新 acquire 后 slot 可能已被
+                // 新连接占据，误删会破坏新连接。
+                if (this.slots.get(workspace)?.client === client) {
+                    this.slots.delete(workspace);
+                    this.onConnectionLost?.(workspace);
+                }
+            },
+        });
+        await client.connect();
+        return client;
+    }
+    clearIdleTimer(slot) {
+        if (slot.idleTimer !== null) {
+            clearTimeout(slot.idleTimer);
+            slot.idleTimer = null;
+        }
+    }
+    async disposeSlot(workspace) {
+        const slot = this.slots.get(workspace);
+        if (!slot)
+            return;
+        this.slots.delete(workspace);
+        this.clearIdleTimer(slot);
+        if (slot.client) {
+            try {
+                await slot.client.dispose();
+            }
+            catch (err) {
+                getLogger().warn(`[${this.logTag}] dispose error workspace=${workspace}: ${err}`);
+            }
+        }
+    }
+}
+//# sourceMappingURL=connection-manager.js.map

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

@@ -0,0 +1,50 @@
+/**
+ * JSONL-RPC transport shared by JSON-line-RPC agent servers
+ * (codex app-server, kimi acp, and future ACP-style integrations).
+ *
+ * Wraps a child process with JSON-line-based bidirectional communication:
+ * each line on stdout is a JSON message from the server; each `write()`
+ * sends a JSON line to stdin.
+ */
+export interface TransportEvents {
+    onMessage(msg: unknown): void;
+    onClose(reason: string): void;
+}
+export declare class JsonlRpcTransport {
+    private proc;
+    private _closed;
+    private events;
+    private stopper;
+    private readonly binary;
+    private readonly args;
+    private readonly cwd;
+    private readonly env;
+    /** JSON lines buffered while stdin is under backpressure (bounded by callers). */
+    private writeQueue;
+    private flushing;
+    constructor(opts: {
+        binary: string;
+        args: string[];
+        cwd: string;
+        env?: Record<string, string | undefined>;
+    });
+    get closed(): boolean;
+    /**
+     * Spawn the child process and start reading its stdout.
+     * Returns when the process closes (or immediately if spawn fails).
+     */
+    start(events: TransportEvents): Promise<void>;
+    /**
+     * Write a JSON message as a single line to the process's stdin.
+     * On EPIPE, triggers onClose('epipe') without throwing.
+     */
+    write(msg: object): void;
+    /** Send queued lines to stdin, pausing on backpressure until drain. */
+    private flush;
+    /**
+     * Gracefully stop the child process: SIGTERM → grace → SIGKILL.
+     * Idempotent — safe to call multiple times.
+     */
+    close(): Promise<void>;
+    private handleClose;
+}

package/dist/runner/common/jsonrpc/transport.js

@@ -0,0 +1,230 @@
+/**
+ * JSONL-RPC transport shared by JSON-line-RPC agent servers
+ * (codex app-server, kimi acp, and future ACP-style integrations).
+ *
+ * Wraps a child process with JSON-line-based bidirectional communication:
+ * each line on stdout is a JSON message from the server; each `write()`
+ * sends a JSON line to stdin.
+ */
+import { spawn } from 'node:child_process';
+import { ProcessStopper } from '../process-stopper.js';
+import { getLogger } from '../../../logger/index.js';
+/** Max bytes for a single line before we disconnect (10MB). */
+const MAX_LINE_BYTES = 10 * 1024 * 1024;
+/** Max bytes retained from stderr for diagnostics (64KB). */
+const MAX_STDERR_BYTES = 64 * 1024;
+export class JsonlRpcTransport {
+    proc = null;
+    _closed = false;
+    events = null;
+    stopper;
+    binary;
+    args;
+    cwd;
+    env;
+    /** JSON lines buffered while stdin is under backpressure (bounded by callers). */
+    writeQueue = [];
+    flushing = false;
+    constructor(opts) {
+        this.binary = opts.binary;
+        this.args = opts.args;
+        this.cwd = opts.cwd;
+        this.env = opts.env ?? {};
+        this.stopper = new ProcessStopper({ graceMs: 5000 });
+    }
+    get closed() {
+        return this._closed;
+    }
+    /**
+     * Spawn the child process and start reading its stdout.
+     * Returns when the process closes (or immediately if spawn fails).
+     */
+    async start(events) {
+        this.events = events;
+        // agent 是用户自己的可信二进制，provider 认证依赖 API key /
+        // 自定义 provider 的 env_key，代理环境依赖 HTTP(S)_PROXY、TMPDIR 等；
+        // 任何白名单收窄都会打断认证或网络。调用方 this.env 覆盖 process.env 同名键。
+        const childEnv = { ...process.env, ...this.env };
+        const proc = spawn(this.binary, this.args, {
+            cwd: this.cwd,
+            stdio: ['pipe', 'pipe', 'pipe'],
+            detached: true,
+            env: childEnv,
+        });
+        this.proc = proc;
+        if (proc.pid === undefined) {
+            // ENOENT early check
+            const err = await new Promise((resolve) => {
+                proc.once('error', (e) => resolve(e));
+                setTimeout(() => resolve(undefined), 5000);
+            });
+            this._closed = true;
+            const reason = err ? `ENOENT: ${this.binary} not found` : `spawn failed: ${this.binary}`;
+            events.onClose(reason);
+            return;
+        }
+        getLogger().info(`[jsonrpc-transport] spawned pid=${proc.pid} binary=${this.binary}`);
+        proc.stdin?.on('error', (err) => {
+            getLogger().warn(`[jsonrpc-transport] stdin error: ${err.message}`);
+            this.handleClose('epipe');
+        });
+        // Stderr: rolling buffer, last 64KB retained, only log
+        let stderrBuf = '';
+        proc.stderr?.on('data', (chunk) => {
+            const text = chunk.toString('utf-8');
+            stderrBuf = (stderrBuf + text).slice(-MAX_STDERR_BYTES);
+            getLogger().debug(`[jsonrpc-transport] stderr: ${text.trimEnd()}`);
+        });
+        // Stdout: line-split with 10MB line limit
+        let remainder = '';
+        proc.stdout?.on('data', (chunk) => {
+            remainder += chunk.toString('utf-8');
+            const lines = remainder.split('\n');
+            // Lines except the last (incomplete) one
+            remainder = lines.pop() ?? '';
+            for (const line of lines) {
+                if (line.length === 0)
+                    continue;
+                if (line.length > MAX_LINE_BYTES) {
+                    getLogger().error(`[jsonrpc-transport] line exceeds ${MAX_LINE_BYTES} bytes, disconnecting`);
+                    this.handleClose('parse_error');
+                    return;
+                }
+                try {
+                    const msg = JSON.parse(line);
+                    events.onMessage(msg);
+                }
+                catch (err) {
+                    getLogger().warn(`[jsonrpc-transport] failed to parse JSON: ${err.message} line=${line.slice(0, 200)}`);
+                }
+            }
+        });
+        // Handle process exit
+        const onExit = (code, signal) => {
+            this._closed = true;
+            this.proc = null;
+            // Flush remaining buffer
+            if (remainder.length > 0) {
+                try {
+                    const msg = JSON.parse(remainder);
+                    events.onMessage(msg);
+                }
+                catch {
+                    // ignore trailing incomplete line
+                }
+            }
+            const reason = signal ? `signal:${signal}` : `exit:${code}`;
+            events.onClose(reason);
+            getLogger().info(`[jsonrpc-transport] process exited pid=${proc.pid} code=${code} signal=${signal}`);
+        };
+        proc.once('exit', onExit);
+        proc.once('error', (err) => {
+            getLogger().error(`[jsonrpc-transport] process error: ${err.message}`);
+            this.handleClose(`error:${err.message}`);
+        });
+    }
+    /**
+     * Write a JSON message as a single line to the process's stdin.
+     * On EPIPE, triggers onClose('epipe') without throwing.
+     */
+    write(msg) {
+        if (this._closed || !this.proc?.stdin) {
+            return;
+        }
+        try {
+            // 入队后顺序 flush；write() 返回 false（高水位）时暂停直到 drain，
+            // 避免大消息/突发消息在 Node 内部无限缓冲（review P3-8）。
+            this.writeQueue.push(Buffer.from(JSON.stringify(msg) + '\n', 'utf8'));
+            this.flush();
+        }
+        catch {
+            this.handleClose('epipe');
+        }
+    }
+    /** Send queued lines to stdin, pausing on backpressure until drain. */
+    flush() {
+        const stdin = this.proc?.stdin;
+        if (this._closed || !stdin || this.flushing)
+            return;
+        this.flushing = true;
+        const next = () => {
+            if (this._closed) {
+                this.writeQueue = [];
+                this.flushing = false;
+                return;
+            }
+            const chunk = this.writeQueue.shift();
+            if (!chunk) {
+                this.flushing = false;
+                return;
+            }
+            try {
+                const ok = stdin.write(chunk, (err) => {
+                    if (err) {
+                        this.handleClose('epipe');
+                    }
+                });
+                if (!ok) {
+                    // 流满：等待 drain 再发下一条，队列有界（调用方同步节奏）。
+                    stdin.once('drain', next);
+                }
+                else {
+                    next();
+                }
+            }
+            catch {
+                this.handleClose('epipe');
+            }
+        };
+        next();
+    }
+    /**
+     * Gracefully stop the child process: SIGTERM → grace → SIGKILL.
+     * Idempotent — safe to call multiple times.
+     */
+    async close() {
+        if (this._closed)
+            return;
+        this._closed = true;
+        const proc = this.proc;
+        if (proc) {
+            try {
+                await this.stopper.stop(proc);
+            }
+            catch {
+                // Ignore stop errors — process may already be dead
+            }
+            if (proc.stdin && !proc.stdin.destroyed) {
+                proc.stdin.end();
+            }
+        }
+    }
+    handleClose(reason) {
+        if (this._closed)
+            return;
+        this._closed = true;
+        this.writeQueue = [];
+        // Remove the exit listener to avoid double-firing
+        if (this.proc) {
+            this.proc.removeAllListeners('exit');
+            this.proc.removeAllListeners('error');
+        }
+        const proc = this.proc;
+        this.proc = null;
+        if (proc) {
+            if (proc.stdin && !proc.stdin.destroyed) {
+                proc.stdin.end();
+            }
+            // 异常路径（EPIPE/超长行/进程 error）也要收掉子进程，避免孤儿进程
+            // 继续运行（如超长行场景子进程还在往 stdout 灌数据）。
+            void this.stopper.stop(proc).catch((err) => {
+                getLogger().warn(`[jsonrpc-transport] failed to stop process during close: ${err instanceof Error ? err.message : String(err)}`);
+            });
+        }
+        // 统一关闭出口：EPIPE/超长行/进程 error 都必须通知上层（connection-manager
+        // 靠 onClose 删除 slot、client 靠它 failPending），否则 slot 悬挂死连接。
+        this.events?.onClose(reason);
+        getLogger().info(`[jsonrpc-transport] closed: ${reason}`);
+    }
+}
+//# sourceMappingURL=transport.js.map

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

@@ -0,0 +1,32 @@
+/**
+ * JSON-RPC 2.0 base types shared by all JSON-line-RPC agent protocols
+ * (codex app-server, kimi acp, and future ACP-style integrations).
+ *
+ * Protocol-specific method/params types live in each protocol's own
+ * protocol-types.ts; only the wire envelope lives here.
+ */
+export interface JsonRpcRequest {
+    jsonrpc: '2.0';
+    id: number | string;
+    method: string;
+    params?: unknown;
+}
+export interface JsonRpcNotification {
+    jsonrpc: '2.0';
+    method: string;
+    params?: unknown;
+}
+export interface JsonRpcSuccessResponse {
+    jsonrpc: '2.0';
+    id: number | string;
+    result: unknown;
+}
+export interface JsonRpcErrorResponse {
+    jsonrpc: '2.0';
+    id: number | string | null;
+    error: {
+        code: number;
+        message: string;
+        data?: unknown;
+    };
+}

package/dist/runner/common/jsonrpc/types.js

@@ -0,0 +1,9 @@
+/**
+ * JSON-RPC 2.0 base types shared by all JSON-line-RPC agent protocols
+ * (codex app-server, kimi acp, and future ACP-style integrations).
+ *
+ * Protocol-specific method/params types live in each protocol's own
+ * protocol-types.ts; only the wire envelope lives here.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/runner/common/process-stopper.d.ts

@@ -23,6 +23,7 @@ export declare class ProcessStopper {
      * Pass `immediate: true` to skip the grace window — SIGTERM and SIGKILL
      * are sent back-to-back. Safe to call on an already-exited process.
      */
-    stop(proc: ChildProcess, opts?: StopOptions): Promise<void>;
+    /** proc 可为 null（调用方已清理 currentProcess）；nullish 直接返回。 */
+    stop(proc: ChildProcess | null, opts?: StopOptions): Promise<void>;
 }
 export {};

package/dist/runner/common/process-stopper.js

@@ -19,6 +19,7 @@ export class ProcessStopper {
      * Pass `immediate: true` to skip the grace window — SIGTERM and SIGKILL
      * are sent back-to-back. Safe to call on an already-exited process.
      */
+    /** proc 可为 null（调用方已清理 currentProcess）；nullish 直接返回。 */
     async stop(proc, opts) {
         if (!proc || proc.exitCode !== null || proc.signalCode !== null) {
             return;