lark-remote 0.1.13 → 0.2.0

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

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