lark-remote 0.1.12 → 0.2.0

package/dist/config/wizard.js

@@ -1,41 +1,83 @@
 import { registerApp } from '@larksuite/channel';
-import qrcode from 'qrcode-terminal';
 import fs from 'node:fs';
 import path from 'node:path';
 import YAML from 'yaml';
 import { AppConfigSchema } from './index.js';
+import { needsQrImage, renderQrImage, renderTerminalQr } from './qr.js';
+import { silentlyUnlink } from '../common/fs.js';
+/** Where the fallback QR image is written (next to the config it will seed). */
+const QR_IMAGE_NAME = 'qr-code.gif';
+/**
+ * Print the scan-to-create QR code.
+ *
+ * The terminal symbol uses full blocks on Windows (half blocks there often
+ * render wrong and cannot be scanned); the image file is offered whenever the
+ * terminal cannot show a trustworthy symbol — Windows, or a window too narrow
+ * for the symbol to fit without wrapping.
+ *
+ * Returns true when the fallback image was written, so the caller only cleans
+ * up a file that actually exists.
+ */
+function printRegistrationQr(info, imagePath) {
+    console.log('请用飞书 App 扫描以下二维码完成应用创建：\n');
+    const qr = renderTerminalQr(info.url, { columns: process.stdout.columns });
+    if (qr)
+        console.log(`${qr.text}\n`);
+    else
+        console.log('（当前终端太窄，二维码显示不下：可拉宽窗口重试，或扫下面的图片）\n');
+    let wroteImage = false;
+    if (needsQrImage(qr)) {
+        try {
+            fs.mkdirSync(path.dirname(imagePath), { recursive: true });
+            fs.writeFileSync(imagePath, renderQrImage(info.url));
+            wroteImage = true;
+            console.log(`二维码图片：${imagePath}（或用图片查看器打开后扫码）`);
+        }
+        catch (err) {
+            console.log(`二维码图片写入失败：${String(err)}`);
+        }
+    }
+    const mins = Math.max(1, Math.round(info.expireIn / 60));
+    console.log(`\n二维码有效期：约 ${mins} 分钟`);
+    console.log(`也可以直接在浏览器打开：${info.url}\n`);
+    return wroteImage;
+}
 /**
  * Run the QR-code registration wizard. The user scans the QR with their
  * Feishu/Lark app to create a new application; the SDK polls until the
  * creation completes and returns the credentials.
  */
-async function runRegistrationWizard() {
+async function runRegistrationWizard(configPath) {
     console.log('\n[lark-remote] 未检测到飞书应用配置，进入扫码创建向导。\n');
-    const result = await registerApp({
-        source: 'lark-remote',
-        onQRCodeReady: (info) => {
-            console.log('请用飞书 App 扫描以下二维码完成应用创建：\n');
-            qrcode.generate(info.url, { small: true });
-            const mins = Math.max(1, Math.round(info.expireIn / 60));
-            console.log(`\n二维码有效期：约 ${mins} 分钟`);
-            console.log(`也可以直接在浏览器打开：${info.url}\n`);
-        },
-        onStatusChange: (info) => {
-            if (info.status === 'domain_switched') {
-                console.log('识别到国际版租户，已切换到 larksuite.com 域名。');
-            }
-            else if (info.status === 'slow_down') {
-                console.log('轮询速度过快，已自动降速。');
-            }
-        },
-    });
-    console.log('\n✓ 应用创建成功');
-    console.log(`  App ID:  ${result.client_id}`);
-    if (result.user_info?.tenant_brand) {
-        console.log(`  Tenant:  ${result.user_info.tenant_brand}`);
+    const imagePath = path.join(path.dirname(configPath), QR_IMAGE_NAME);
+    let wroteImage = false;
+    try {
+        const result = await registerApp({
+            source: 'lark-remote',
+            onQRCodeReady: (info) => {
+                wroteImage = printRegistrationQr(info, imagePath);
+            },
+            onStatusChange: (info) => {
+                if (info.status === 'domain_switched') {
+                    console.log('识别到国际版租户，已切换到 larksuite.com 域名。');
+                }
+                else if (info.status === 'slow_down') {
+                    console.log('轮询速度过快，已自动降速。');
+                }
+            },
+        });
+        console.log('\n✓ 应用创建成功');
+        console.log(`  App ID:  ${result.client_id}`);
+        if (result.user_info?.tenant_brand) {
+            console.log(`  Tenant:  ${result.user_info.tenant_brand}`);
+        }
+        console.log('');
+        return { appId: result.client_id, appSecret: result.client_secret };
+    }
+    finally {
+        if (wroteImage)
+            silentlyUnlink(imagePath);
     }
-    console.log('');
-    return { appId: result.client_id, appSecret: result.client_secret };
 }
 function isInteractiveTerminal() {
     return Boolean(process.stdin.isTTY && process.stdout.isTTY);
@@ -77,7 +119,7 @@ export async function ensureConfig(configPath) {
         return;
     if (!isInteractiveTerminal())
         return;
-    const { appId, appSecret } = await runRegistrationWizard();
+    const { appId, appSecret } = await runRegistrationWizard(configPath);
     writeConfigWithCredentials(configPath, appId, appSecret);
     console.log(`[lark-remote] 凭证已写入 ${configPath}，继续启动...\n`);
 }

package/dist/connector/index.d.ts

@@ -6,9 +6,10 @@ import type { AppConfig } from '../config/index.js';
  * 必须远小于用户连击间隔，否则同一按钮的连续点击会被当成"重复事件"丢弃：
  * - SDK 的 cardAction dedup eventId = `card:{messageId}:{operator.openId}:{actionId}`
  * - actionId = `tag|name|option|JSON.stringify(value)`，不含时间戳/事件序号
- * - config 卡片原地更新（updateCardInPlace），用户在同一张卡上连点 toggle：
+ * - config 卡片原地更新（updateCardInPlace），用户在同一张卡上重复触发
+ *   固定 value 的按钮（如 config.toggle）：
  *   messageId / operator / value 三段都相同 → eventId 完全相同 → 第二次点击被
- *   seenCache drop，toggle 不可逆（"显示工具结果"等开关第二次点击静默失效）。
+ *   seenCache drop，toggle 不可逆（第二次点击静默失效）。
  *
  * SDK 默认 12h 太长；60s 仍会误伤连击。300ms 挡飞书瞬时重投递（<100ms 级），
  * 放过用户连击（慢点两次通常 >500ms）。代价：削弱 message 秒级重投递防护——

package/dist/connector/index.js

@@ -6,6 +6,7 @@ import { sleep } from '../common/sleep.js';
 import axios from 'axios';
 import fs from 'node:fs';
 import { silentlyUnlink } from '../common/fs.js';
+import { displayName } from '../platform/path.js';
 import https from 'node:https';
 import os from 'node:os';
 import path from 'node:path';
@@ -29,9 +30,10 @@ const noKeepAliveAgent = new https.Agent({ keepAlive: false });
  * 必须远小于用户连击间隔，否则同一按钮的连续点击会被当成"重复事件"丢弃：
  * - SDK 的 cardAction dedup eventId = `card:{messageId}:{operator.openId}:{actionId}`
  * - actionId = `tag|name|option|JSON.stringify(value)`，不含时间戳/事件序号
- * - config 卡片原地更新（updateCardInPlace），用户在同一张卡上连点 toggle：
+ * - config 卡片原地更新（updateCardInPlace），用户在同一张卡上重复触发
+ *   固定 value 的按钮（如 config.toggle）：
  *   messageId / operator / value 三段都相同 → eventId 完全相同 → 第二次点击被
- *   seenCache drop，toggle 不可逆（"显示工具结果"等开关第二次点击静默失效）。
+ *   seenCache drop，toggle 不可逆（第二次点击静默失效）。
  *
  * SDK 默认 12h 太长；60s 仍会误伤连击。300ms 挡飞书瞬时重投递（<100ms 级），
  * 放过用户连击（慢点两次通常 >500ms）。代价：削弱 message 秒级重投递防护——
@@ -403,7 +405,7 @@ export class FeishuConnector {
         if (stat.size > MAX_FILE_UPLOAD_SIZE) {
             throw new Error(`File too large (${(stat.size / 1_000_000).toFixed(1)}MB), exceeds ${MAX_FILE_UPLOAD_SIZE / (1024 * 1024)}MB limit`);
         }
-        const fileName = filePath.split('/').pop() ?? 'file';
+        const fileName = displayName(filePath);
         // P2-18: capture the read stream so it can be destroyed on any failure
         // path. Without this, a token/upload/send failure leaks the fd (axios
         // only closes the stream when it fully consumes it on success).

package/dist/index.js

@@ -9,7 +9,7 @@ import { probeAllAgents } from './runner/probe.js';
 import { warmCodexCatalogCache } from './config/codex-config.js';
 import { SessionReaderRegistry, SessionStore } from './session/index.js';
 import { ClaudeSessionReader, CodexSessionReader, OpencodeSessionReader, PiSessionReader, KimiSessionReader, DshSessionReader, } from './session/index.js';
-import { CommandRouter, isImmediateAction } from './router/index.js';
+import { CommandRouter, isImmediateAction, DIRECT_RETURN_CMDS, } from './router/index.js';
 import { dispatchOrderExecForQueue } from './router/order-exec-dispatch.js';
 import { buildCardActionFullValue } from './router/card-action-payload.js';
 import { Bridge } from './bridge/index.js';
@@ -117,13 +117,14 @@ function setupInstanceLockAndHandlers(instanceLock, logger, configDir) {
 /** Initialize per-workspace runner factory + agent registry. */
 function initializeRunner(config, configDir, cliArgs) {
     const agentRegistry = new AgentRegistry();
+    // W2.10 单点化：runner factory 取最新 config 的唯一入口（P1-15 语义保持，
+    // container 未接线时回退启动快照）。
+    const latest = () => agentRegistry.getConfigContainer()?.current ?? config;
     // P1-15: Claude factory reads from configContainer (not closure) so runtime
     // config changes (model, effort, stopGraceMs) take effect after
     // bridge.setConfig() + clearRunners(). Same pattern as codex/pi/kimi.
     agentRegistry.register('claude', (ws) => {
-        const container = agentRegistry.getConfigContainer();
-        const latestConfig = container?.current ?? config;
-        const claudeConfig = latestConfig.claude;
+        const claudeConfig = latest().claude;
         return new ClaudeRunner({
             model: claudeConfig.model,
             effort: claudeConfig.effort,
@@ -141,9 +142,7 @@ function initializeRunner(config, configDir, cliArgs) {
     // + clearRunners().
     const codexSessionReader = new CodexSessionReader({ codexHome: process.env.CODEX_HOME });
     agentRegistry.register('codex', (_ws) => {
-        const container = agentRegistry.getConfigContainer();
-        const latestConfig = container?.current ?? config;
-        const codexConfig = getAgentConfig(latestConfig, 'codex');
+        const codexConfig = getAgentConfig(latest(), 'codex');
         return new CodexAppServerRunner({
             kind: 'codex',
             model: codexConfig?.model,
@@ -169,10 +168,7 @@ function initializeRunner(config, configDir, cliArgs) {
     // Using `opencode session list` and `opencode export` instead of HTTP API
     const opencodeSessionReader = new OpencodeSessionReader();
     agentRegistry.register('opencode', (_ws) => {
-        // Get latest config from container (set below for pi)
-        const container = agentRegistry.getConfigContainer();
-        const latestConfig = container?.current ?? config;
-        const ocConfig = getAgentConfig(latestConfig, 'opencode');
+        const ocConfig = getAgentConfig(latest(), 'opencode');
         // Build model string with validation: provider/model format
         let model;
         if (ocConfig?.modelID) {
@@ -201,10 +197,7 @@ function initializeRunner(config, configDir, cliArgs) {
     agentRegistry.setConfigContainer(configContainer);
     const piSessionReader = new PiSessionReader();
     agentRegistry.register('pi', (ws) => {
-        // 每次 factory 调用时从 registry 获取最新 config
-        const container = agentRegistry.getConfigContainer();
-        const latestConfig = container?.current ?? config;
-        const piConf = getAgentConfig(latestConfig, 'pi');
+        const piConf = getAgentConfig(latest(), 'pi');
         return new PiRpcRunner({
             provider: piConf?.provider ?? 'Volcano',
             model: piConf?.model ?? 'glm-5.2',
@@ -221,10 +214,7 @@ function initializeRunner(config, configDir, cliArgs) {
     // Register KimiAcpRunner (pure ACP mode) and KimiSessionReader
     const kimiSessionReader = new KimiSessionReader();
     agentRegistry.register('kimi', (_ws) => {
-        // 每次 factory 调用时从 registry 获取最新 config
-        const container = agentRegistry.getConfigContainer();
-        const latestConfig = container?.current ?? config;
-        const kimiConf = getAgentConfig(latestConfig, 'kimi');
+        const kimiConf = getAgentConfig(latest(), 'kimi');
         const acpConf = kimiConf?.acp;
         return new KimiAcpRunner({
             kind: 'kimi',
@@ -244,18 +234,10 @@ function initializeRunner(config, configDir, cliArgs) {
     const dshSessionReader = new DshSessionReader({
         // hostProvider 每次调用读最新 config：/config 修改 host 后 runner 重建为
         // 新 host，reader（/resume、用量、完成卡）也跟随新 host（CC-02）。
-        hostProvider: () => {
-            const container = agentRegistry.getConfigContainer();
-            const latestConfig = container?.current ?? config;
-            return getAgentConfig(latestConfig, 'dsh')?.host;
-        },
+        hostProvider: () => getAgentConfig(latest(), 'dsh')?.host,
     });
     agentRegistry.register('dsh', (_ws) => {
-        // Read latest config from container so /config host changes take effect
-        // after bridge.setConfig() + clearRunners().
-        const container = agentRegistry.getConfigContainer();
-        const latestConfig = container?.current ?? config;
-        const dshConf = getAgentConfig(latestConfig, 'dsh');
+        const dshConf = getAgentConfig(latest(), 'dsh');
         return new DshRunner({
             kind: 'dsh',
             sessionReader: dshSessionReader,
@@ -541,18 +523,9 @@ function setupMessageHandlers(connector, router, bridge, sessionStore, workspace
         // order.aliasInput / order.aliasRemove / order.textInput 也返回 toast+card，
         // 需直返避免被吞（order.textInput 曾漏在列表外，编辑卡停留在编辑界面）。
         // approval.planFeedback 同 answer 系列：附意见的 toast 需直返 + 不落串行队列。
-        if (actionValue.cmd === 'queue.input' ||
-            actionValue.cmd === 'order.aliasInput' ||
-            actionValue.cmd === 'order.aliasRemove' ||
-            actionValue.cmd === 'order.textInput' ||
-            actionValue.cmd === 'config.save' ||
-            actionValue.cmd === 'approval.respond' ||
-            actionValue.cmd === 'approval.toggle' ||
-            actionValue.cmd === 'approval.answer' ||
-            actionValue.cmd === 'approval.answerSubmit' ||
-            actionValue.cmd === 'approval.answerCustom' ||
-            actionValue.cmd === 'approval.answerNote' ||
-            actionValue.cmd === 'approval.planFeedback') {
+        // W2.1：直返名单以 router 的 DIRECT_RETURN_CMDS 为单一来源（历史注释：
+        // order.textInput 曾漏在列表外、answer 家族曾漏在直返列表外——两份拷贝漂移）。
+        if (DIRECT_RETURN_CMDS.has(actionValue.cmd)) {
             return router.handleCardAction(fullValue, { userId, chatId, messageId });
         }
         // order.exec → equivalent queued message (Plan A): resolve the order text

package/dist/instance-lock.js

@@ -116,6 +116,13 @@ export class InstanceLock {
                 process.exit(129);
             });
         }
+        else {
+            // win32 无 SIGHUP；CTRL_BREAK 退出前也要释放锁（§3.5，对照 cli.ts 信号转发）
+            process.on('SIGBREAK', () => {
+                this.release();
+                process.exit(149);
+            });
+        }
     }
     /**
      * Lock file stores `pid\ncomm` where comm is the owning process's command

package/dist/persistence/atomic-write.d.ts

@@ -1,6 +1,8 @@
 /**
  * Atomically write content (string or binary Buffer) to a file via tmp + rename.
  * Falls back to copy+unlink when rename fails with EXDEV (cross-device).
+ * rename 目标被占用（win32 EPERM/EBUSY）时短暂退避重试（§6）；重试耗尽后
+ * 保留 tmp 现场并告警，再抛出原错误。
  */
 export declare function atomicWrite(filePath: string, content: string | Buffer, encoding?: BufferEncoding): void;
 /**

package/dist/persistence/atomic-write.js

@@ -1,9 +1,12 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { silentlyUnlink } from '../common/fs.js';
+import { silentlyUnlink, withBusyRetry } from '../common/fs.js';
+import { getLogger } from '../logger/index.js';
 /**
  * Atomically write content (string or binary Buffer) to a file via tmp + rename.
  * Falls back to copy+unlink when rename fails with EXDEV (cross-device).
+ * rename 目标被占用（win32 EPERM/EBUSY）时短暂退避重试（§6）；重试耗尽后
+ * 保留 tmp 现场并告警，再抛出原错误。
  */
 export function atomicWrite(filePath, content, encoding = 'utf-8') {
     const dir = path.dirname(filePath);
@@ -33,8 +36,17 @@ export function atomicWrite(filePath, content, encoding = 'utf-8') {
             }
         }
     }
+    let preserveTmpScene = false;
     try {
-        fs.renameSync(tmpPath, filePath);
+        withBusyRetry(() => fs.renameSync(tmpPath, filePath), {
+            onGiveUp: (err) => {
+                // 保留现场：tmp 里是已写好的完整内容，重试耗尽（win32）或 posix 首次
+                // 占用即失败都说明目标不可达；留着 tmp 供人工恢复，只告警不静默
+                preserveTmpScene = true;
+                getLogger().warn(`[atomic-write] rename to ${filePath} still busy after retries; ` +
+                    `tmp preserved at ${tmpPath}: ${String(err)}`);
+            },
+        });
     }
     catch (err) {
         if (err.code === 'EXDEV') {
@@ -48,8 +60,11 @@ export function atomicWrite(filePath, content, encoding = 'utf-8') {
     finally {
         // Best-effort cleanup: on success the tmp was renamed away (ENOENT here,
         // silently ignored); on EXDEV it was copied and now needs removal; on other
-        // errors we must not leak the tmp file.
-        silentlyUnlink(tmpPath);
+        // errors we must not leak the tmp file — except when the scene is
+        // deliberately preserved after busy-retry exhaustion.
+        if (!preserveTmpScene) {
+            silentlyUnlink(tmpPath);
+        }
     }
 }
 /**
@@ -66,7 +81,7 @@ export function atomicWriteJson(filePath, data) {
  */
 export function atomicMoveFile(srcPath, destPath) {
     try {
-        fs.renameSync(srcPath, destPath);
+        withBusyRetry(() => fs.renameSync(srcPath, destPath));
     }
     catch (err) {
         if (err.code === 'EXDEV') {

package/dist/persistence/load-json-file.d.ts

@@ -4,6 +4,5 @@
  *
  * @param filePath - Path to the JSON file
  * @param fallback - Value to return if file doesn't exist or is corrupted
- * @param parseFn - Optional custom parser (defaults to JSON.parse)
  */
-export declare function loadJsonFile<T>(filePath: string, fallback: T, parseFn?: (raw: string) => T): T;
+export declare function loadJsonFile<T>(filePath: string, fallback: T): T;

package/dist/persistence/load-json-file.js

@@ -6,14 +6,13 @@ import { getLogger } from '../logger/index.js';
  *
  * @param filePath - Path to the JSON file
  * @param fallback - Value to return if file doesn't exist or is corrupted
- * @param parseFn - Optional custom parser (defaults to JSON.parse)
  */
-export function loadJsonFile(filePath, fallback, parseFn = JSON.parse) {
+export function loadJsonFile(filePath, fallback) {
     try {
         if (!fs.existsSync(filePath))
             return fallback;
         const raw = fs.readFileSync(filePath, 'utf-8');
-        return parseFn(raw);
+        return JSON.parse(raw);
     }
     catch (err) {
         getLogger().warn(`[persistence] failed to load ${filePath}, using fallback:`, err);

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

@@ -0,0 +1,22 @@
+/**
+ * 每 agent 的协议停止通道注册表（design.md §3.3）。
+ *
+ * Windows 没有可拦截的跨进程 SIGTERM，优雅停止只能靠协议通道（claude 的 stdin
+ * 控制通道、codex 的 turn interrupt、ACP 的 abort…）。「无通道」是**合法状态**：
+ * 由 Terminator 显式跳过优雅段并打日志，绝不允许悄悄等一个永远不会来的退出事件。
+ *
+ * 独立成文件是为了避免 `terminator.ts`（接口 + 分发）与 `terminator-win32.ts`
+ * 互相 import 形成循环依赖。
+ */
+import type { ChildProcess } from 'node:child_process';
+export type AgentStopper = (proc: ChildProcess) => void | Promise<void>;
+/** agent key → 协议停止通道。测试请自建实例以隔离。 */
+export declare class AgentStopperRegistry {
+    private readonly stoppers;
+    register(agent: string, stopper: AgentStopper): void;
+    get(agent: string): AgentStopper | undefined;
+    has(agent: string): boolean;
+    clear(): void;
+}
+/** 接线用的进程级单例；runner 在 run 启动时注册自己的停止通道。 */
+export declare const agentStopperRegistry: AgentStopperRegistry;

package/dist/platform/agent-stopper.js

@@ -0,0 +1,19 @@
+/** agent key → 协议停止通道。测试请自建实例以隔离。 */
+export class AgentStopperRegistry {
+    stoppers = new Map();
+    register(agent, stopper) {
+        this.stoppers.set(agent, stopper);
+    }
+    get(agent) {
+        return this.stoppers.get(agent);
+    }
+    has(agent) {
+        return this.stoppers.has(agent);
+    }
+    clear() {
+        this.stoppers.clear();
+    }
+}
+/** 接线用的进程级单例；runner 在 run 启动时注册自己的停止通道。 */
+export const agentStopperRegistry = new AgentStopperRegistry();
+//# sourceMappingURL=agent-stopper.js.map

package/dist/platform/command.d.ts

@@ -0,0 +1,11 @@
+import type { LaunchSpec } from './types.js';
+export type { LaunchSpec } from './types.js';
+export interface ResolveOptions {
+    platform?: NodeJS.Platform;
+    /** PATH 环境变量注入（测试用）；默认 process.env.PATH */
+    pathEnv?: string;
+    /** PATHEXT 注入（测试用）；win32 默认 .exe/.bat/.cmd（Windows 默认相对顺序） */
+    pathExt?: readonly string[];
+}
+export declare function clearResolveCache(): void;
+export declare function resolveExecutable(name: string, opts?: ResolveOptions): LaunchSpec | null;

package/dist/platform/command.js

@@ -0,0 +1,107 @@
+/**
+ * resolveExecutable —— 可执行文件发现。
+ *
+ * 职责收窄为「探测/诊断」：报告 agent 装在哪、装没装（可用性探测 probe.ts、
+ * 自更新安装源检测 update/install.ts）。**执行**统一走 platform/spawn.ts 的
+ * cross-spawn 包装（PATHEXT 解析 + .cmd 经 cmd.exe 受控执行），本模块不再
+ * 解析 .cmd/.bat 垫片内容——垫片格式是 npm/pnpm 的上游实现细节（历史变过、
+ * pnpm 生成形态不同），手写解析器等于耦合该细节（v2 §4.2）。
+ *
+ * posix：PATH 目录顺序 + X_OK（现状语义迁移）。
+ * win32：PATH 目录顺序 × PATHEXT(.exe/.cmd/.bat) 解析，.cmd 命中即报告垫片
+ * 路径本身（执行时由 cross-spawn 处理），结果按 (platform, pathEnv, name) 缓存。
+ *
+ * 分隔符/join 全部跟随注入 platform（win32 为 `;` + path.win32.join），
+ * 不读宿主 path——posix 宿主模拟 win32 的测试才保真。
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { currentPlatform, isWin32 } from './select.js';
+const DEFAULT_PATHEXT = ['.exe', '.bat', '.cmd'];
+/**
+ * 缓存 TTL：probe 层（runner/probe.ts）5 分钟，本层更短——bridge 运行期间
+ * 用户新装/卸载 agent（典型场景：按 /config 不可用提示去安装）后，最迟
+ * TTL 过期即可被重新探测到，不必重启。null（未找到）结果同样过期重查。
+ */
+const RESOLVE_CACHE_TTL_MS = 60_000;
+const resolveCache = new Map();
+export function clearResolveCache() {
+    resolveCache.clear();
+}
+/** 过期条目惰性清除；命中返回 spec，未命中/过期返回 undefined。 */
+function cacheGet(key) {
+    const entry = resolveCache.get(key);
+    if (!entry)
+        return undefined;
+    if (Date.now() - entry.ts >= RESOLVE_CACHE_TTL_MS) {
+        resolveCache.delete(key);
+        return undefined;
+    }
+    return entry.spec;
+}
+function listPathDirs(pathEnv, platform) {
+    const delimiter = isWin32(platform) ? ';' : ':';
+    return pathEnv.split(delimiter).filter((dir) => dir.length > 0);
+}
+/**
+ * win32 join：真实 win32 宿主产出原生反斜杠路径；posix 宿主模拟 win32 的
+ * 测试里 dir 是 posix 风格路径，win32 join 会把分隔符归一成 `\` 而宿主 fs
+ * 读不到——回退正斜杠形态再探测一次（Windows fs 本身两种分隔符都认）。
+ */
+function existsWin32(file) {
+    if (fs.existsSync(file))
+        return file;
+    const posixForm = file.replaceAll('\\', '/');
+    if (posixForm !== file && fs.existsSync(posixForm))
+        return posixForm;
+    return null;
+}
+function resolveWin32(name, pathEnv, pathExt) {
+    const hasExtension = /\.[A-Za-z0-9]+$/.test(name);
+    for (const dir of listPathDirs(pathEnv, 'win32')) {
+        const candidates = hasExtension ? [name] : pathExt.map((ext) => name + ext);
+        for (const candidate of candidates) {
+            const found = existsWin32(path.win32.join(dir, candidate));
+            // .cmd/.bat 垫片命中即报告垫片路径本身；执行语义由 cross-spawn 负责
+            if (found)
+                return { kind: 'direct', file: found };
+        }
+    }
+    return null;
+}
+function resolvePosix(name, pathEnv) {
+    for (const dir of listPathDirs(pathEnv, 'linux')) {
+        // 与 win32 分支对称：join 必须跟随注入 platform，而非宿主 path。
+        // 宿主是 win32 时用 path.join 会把 `/tmp/a` + `agent` 拼成 `\tmp\a\agent`，
+        // posix 语义测试在 Windows 宿主上必然落空。
+        const file = path.posix.join(dir, name);
+        try {
+            fs.accessSync(file, fs.constants.X_OK);
+            return { kind: 'direct', file };
+        }
+        catch {
+            // 不是可执行文件（或不存在）→ 尝试下一个 PATH 目录
+        }
+    }
+    return null;
+}
+export function resolveExecutable(name, opts) {
+    // 空名守卫：posix 的 path.join(dir, '') = 目录本身，而目录有 X_OK——
+    // 不挡住会把第一个 PATH 目录误报为「可执行」（dsh 空 binary 之类的假阳性）
+    const trimmed = name.trim();
+    if (!trimmed)
+        return null;
+    const platform = opts?.platform ?? currentPlatform;
+    const pathEnv = opts?.pathEnv ?? process.env.PATH ?? '';
+    const pathExt = opts?.pathExt ?? DEFAULT_PATHEXT;
+    const key = JSON.stringify([platform, pathEnv, [...pathExt].join(';'), trimmed]);
+    const cached = cacheGet(key);
+    if (cached !== undefined)
+        return cached;
+    const spec = isWin32(platform)
+        ? resolveWin32(trimmed, pathEnv, pathExt)
+        : resolvePosix(trimmed, pathEnv);
+    resolveCache.set(key, { spec, ts: Date.now() });
+    return spec;
+}
+//# sourceMappingURL=command.js.map

package/dist/platform/identity.d.ts

@@ -0,0 +1,33 @@
+/** 进程身份快照。creationDate 仅 win32（CIM CreationDate，DMTF 时间串）。 */
+export interface ProcessIdentity {
+    commandLine: string;
+    creationDate?: string;
+}
+export interface QueryIdentityOptions {
+    /** 平台注入（测试用）；默认当前宿主平台 */
+    platform?: NodeJS.Platform;
+    /** 查询超时（毫秒），超时杀掉查询进程并返回 null */
+    timeoutMs?: number;
+}
+export interface VerifyPidIdentityOptions extends QueryIdentityOptions {
+    /** 期望的二进制名（basename，如 'claude'/'node'）；win32/darwin 大小写不敏感 */
+    expectedBinary: string;
+    /** pid 文件记录的 CreationDate；旧文件缺省该字段则退化为仅命令行匹配 */
+    expectedCreationDate?: string;
+}
+/**
+ * 查询进程身份；进程不存在或查询失败返回 null。
+ */
+export declare function queryProcessIdentity(pid: number, opts?: QueryIdentityOptions): Promise<ProcessIdentity | null>;
+/**
+ * 引号感知的命令行 tokenizer：双引号段不按空白拆分。CIM 的 CommandLine 里
+ * "C:\Program Files\nodejs\node.exe" 这类含空格路径必须整段保留，朴素
+ * split(/\s+/) 会切碎 token 导致身份假阴性。
+ */
+export declare function tokenizeCommandLine(commandLine: string): string[];
+/**
+ * pid 身份验证：进程存活且命令行确实属于期望二进制（+ CreationDate 一致）才 true。
+ *
+ * 用于 killOrphan 与实例锁陈旧判定——只有这里返回 true 才允许动手。
+ */
+export declare function verifyPidIdentity(pid: number, opts: VerifyPidIdentityOptions): Promise<boolean>;