lark-remote 0.4.5 → 0.5.0

package/dist/inbound/placeholder.js

@@ -1,7 +1,7 @@
 /**
  * 入站消息结构占位符识别与剥离（纯函数，无 IO，便于表驱动测试）。
  *
- * 背景（P0 事故 2026-09-15）：`@larksuite/channel` 把非文本消息渲染成结构占位符，
+ * 背景（事故 2026-09-15）：`@larksuite/channel` 把非文本消息渲染成结构占位符，
  * 富文本（`post`）里的图片是 `![image](img_v3_…)` —— 首字符恰好是 `!`，于是被
  * `src/router/index.ts` 的裸前缀判定当成 bash 命令执行了整段消息。
  *
@@ -12,7 +12,7 @@
  * 取舍（有意为之）：剥离对所有消息生效，所以用户在**纯文本**消息里手打
  * `![image](…)` / `<file key="…"/>` 这类字面量也会被当成占位符剥掉。代价是极少数
  * 「讨论本工具自身语法」的消息会丢片段；换来的是任何入口都不可能把占位符当命令
- * （P0 事故正是 `![image](img_v3_…)` 的首字符 `!` 命中 bash 判定）。
+ * （事故正是 `![image](img_v3_…)` 的首字符 `!` 命中 bash 判定）。
  */
 /**
  * 可下载资源类占位符：这些占位符对应的资源会由媒体通道下载落盘，

package/dist/index.js

@@ -133,10 +133,10 @@ async 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 语义保持，
+    // 单点化：runner factory 取最新 config 的唯一入口（语义保持，
     // container 未接线时回退启动快照）。
     const latest = () => agentRegistry.getConfigContainer()?.current ?? config;
-    // P1-15: Claude factory reads from configContainer (not closure) so runtime
+    // 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) => {
@@ -256,7 +256,7 @@ function initializeRunner(config, configDir, cliArgs) {
     // Register DshRunner (HTTP-only DSH Web Host agent) and DshSessionReader.
     const dshSessionReader = new DshSessionReader({
         // hostProvider 每次调用读最新 config：/config 修改 host 后 runner 重建为
-        // 新 host，reader（/resume、用量、完成卡）也跟随新 host（CC-02）。
+        // 新 host，reader（/resume、用量、完成卡）也跟随新 host。
         hostProvider: () => getAgentConfig(latest(), 'dsh')?.host,
     });
     agentRegistry.register('dsh', (_ws) => {
@@ -308,7 +308,7 @@ function setupMessageHandlers(connector, router, bridge, sessionStore, workspace
     // 附件路径统一注入 prompt；无文本纯附件只回执（决策 2）。
     const assembler = new InboundTurnAssembler({
         onCommit: (turn, prompt) => {
-            // 入队时刻（T0）快照 cwd + agent/session 绑定，语义与旧路径一致
+            // 入队时刻快照 cwd + agent/session 绑定，语义与旧路径一致
             // （排队期间 /cd、/config 不再导致语义漂移）。
             const messageId = turn.messageIds[turn.messageIds.length - 1] ?? '';
             // turnMessageIds：终态收尾要覆盖本轮每一条消息（逐条挂的 Typing 得逐条撤）
@@ -347,7 +347,7 @@ function setupMessageHandlers(connector, router, bridge, sessionStore, workspace
         },
     });
     router.setInboundFlusher(() => assembler.flushAll('flush'));
-    // 入站媒体（图片/文件/视频/语音/表情）：先认证后下载（P1 review 修复）。
+    // 入站媒体（图片/文件/视频/语音/表情）：先认证后下载（修复）。
     // connector 只上报"媒体到达"，这里先过 owner + enabled 闸门，通过后才
     // 下载——未认证/关闭配置时不会发生任何网络下载或内存/磁盘占用。
     // 下载是异步的：立刻把在途 promise 交给装配器（`kind: 'media'`），
@@ -358,9 +358,9 @@ function setupMessageHandlers(connector, router, bridge, sessionStore, workspace
             return;
         }
         // 读 router.config（活引用）：/config 保存后 setConfigValues 返回新对象，
-        // 启动时捕获的 config 参数会过期（P2 review 修复）。
+        // 启动时捕获的 config 参数会过期（修复）。
         if (!router.config.inboundMedia.enabled) {
-            // 不静默（P3 review）：关闭时给 owner 明确反馈，避免发图后无任何反应。
+            // 不静默：关闭时给 owner 明确反馈，避免发图后无任何反应。
             // 不下载、不落盘，只进 rejected（随 turn 回执一起发出）。
             assembler.ingest({
                 kind: 'rejected',
@@ -585,7 +585,7 @@ function setupMessageHandlers(connector, router, bridge, sessionStore, workspace
         // order.aliasInput / order.aliasRemove / order.textInput 也返回 toast+card，
         // 需直返避免被吞（order.textInput 曾漏在列表外，编辑卡停留在编辑界面）。
         // approval.planFeedback 同 answer 系列：附意见的 toast 需直返 + 不落串行队列。
-        // W2.1：直返名单以 router 的 DIRECT_RETURN_CMDS 为单一来源（历史注释：
+        // 直返名单以 router 的 DIRECT_RETURN_CMDS 为单一来源（历史注释：
         // order.textInput 曾漏在列表外、answer 家族曾漏在直返列表外——两份拷贝漂移）。
         if (DIRECT_RETURN_CMDS.has(actionValue.cmd)) {
             return router.handleCardAction(fullValue, { userId, chatId, messageId });
@@ -605,7 +605,7 @@ function setupMessageHandlers(connector, router, bridge, sessionStore, workspace
             }).catch((err) => logger.error('[control] order.exec dispatch failed:', err));
             return;
         }
-        // B7：非直返命令到这里已经没有回调响应可回（enqueue* 是 fire-and-forget），
+        // 非直返命令到这里已经没有回调响应可回（enqueue* 是 fire-and-forget），
         // handler 返回的 toast 必须显式转成持久文本，否则失败毫无反馈。
         const forwardActionFeedback = (res) => {
             const text = actionFeedbackText(res);

package/dist/instance-lock.js

@@ -18,6 +18,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { bestEffortUnlink } from './common/fs.js';
+import { isWin32 } from './platform/select.js';
 import { binaryName, verifyPidIdentityVerdict } from './platform/identity.js';
 export class InstanceAlreadyRunningError extends Error {
     pid;
@@ -29,7 +30,7 @@ export class InstanceAlreadyRunningError extends Error {
     }
 }
 /**
- * Probe whether a pid is alive. P2-20:
+ * Probe whether a pid is alive.
  *  - process.kill(pid, 0) returning normally → alive.
  *  - ESRCH (no such process) → dead.
  *  - EPERM (operation not permitted) → the process EXISTS but is owned by
@@ -127,14 +128,14 @@ export class InstanceLock {
             this.release();
             process.exit(143);
         });
-        if (process.platform !== 'win32') {
+        if (!isWin32()) {
             process.on('SIGHUP', () => {
                 this.release();
                 process.exit(129);
             });
         }
         else {
-            // win32 无 SIGHUP；CTRL_BREAK 退出前也要释放锁（§3.5，对照 cli.ts 信号转发）
+            // win32 无 SIGHUP；CTRL_BREAK 退出前也要释放锁（对照 cli.ts 信号转发）
             process.on('SIGBREAK', () => {
                 this.release();
                 process.exit(149);

package/dist/logger/index.d.ts

@@ -35,7 +35,7 @@ export declare class Logger {
     getCurrentLogFile(): string;
     private ensureFile;
     /**
-     * P2-19①: remove daily subdirectories older than the retention window.
+     * remove daily subdirectories older than the retention window.
      * Best-effort — any error is swallowed (logging must never throw).
      */
     private pruneOldDirs;

package/dist/logger/index.js

@@ -21,7 +21,7 @@ function todayStr(d) {
     return `${y}-${m}-${day}`;
 }
 function timestampStr(d) {
-    // P2-19②: local ISO 8601 with milliseconds and explicit offset, e.g.
+    // local ISO 8601 with milliseconds and explicit offset, e.g.
     // 2026-08-03T01:30:00.000+08:00. Previously this used toISOString() (UTC)
     // while the daily directory boundary (todayStr) used local time — after
     // local midnight in a +08:00 zone the new day's directory held lines
@@ -83,7 +83,7 @@ export class Logger {
         fs.mkdirSync(dayDir, { recursive: true });
         this.currentFile = path.join(dayDir, `${this.prefix}-${this.pid}.log`);
         this.currentDate = dateStr;
-        // P2-19①: prune daily log directories older than the retention window so
+        // prune daily log directories older than the retention window so
         // the logs directory does not grow without bound (single-day size cap is
         // out of scope; bounded retention by day is the requested guard). Wrapped
         // defensively so cleanup failure never blocks logging.
@@ -91,7 +91,7 @@ export class Logger {
         return this.currentFile;
     }
     /**
-     * P2-19①: remove daily subdirectories older than the retention window.
+     * remove daily subdirectories older than the retention window.
      * Best-effort — any error is swallowed (logging must never throw).
      */
     pruneOldDirs(currentDateStr) {
@@ -125,7 +125,7 @@ export class Logger {
         const message = format(...args);
         const line = `${ts} [${LEVEL_UPPER[level]}] ${message}\n`;
         const file = this.ensureFile(date);
-        // P2-19③: never let a disk error (EACCES / ENOSPC / EROFS) escape write().
+        // never let a disk error (EACCES / ENOSPC / EROFS) escape write().
         // If logging itself throws — especially inside an uncaughtException handler
         // that calls logger.error(...) — a re-throw would abort Node and skip
         // instanceLock.release(), leaking the singleton lock. Logging must never

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

@@ -1,7 +1,7 @@
 /**
  * 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）；重试耗尽后
+ * rename 目标被占用（win32 EPERM/EBUSY）时短暂退避重试；重试耗尽后
  * 保留 tmp 现场并告警，再抛出原错误。
  */
 export declare function atomicWrite(filePath: string, content: string | Buffer, encoding?: BufferEncoding): void;

package/dist/persistence/atomic-write.js

@@ -5,13 +5,17 @@ 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）；重试耗尽后
+ * rename 目标被占用（win32 EPERM/EBUSY）时短暂退避重试；重试耗尽后
  * 保留 tmp 现场并告警，再抛出原错误。
  */
 export function atomicWrite(filePath, content, encoding = 'utf-8') {
     const dir = path.dirname(filePath);
     fs.mkdirSync(dir, { recursive: true });
-    const tmpPath = filePath + '.tmp';
+    // tmp 命名：pid-ts-rand 后缀，避免固定
+    // `.tmp` 名在异常残留后被下一次写入复用/误判；必须与目标同目录（rename 原子性）
+    const tmpPath = path.join(dir, `.${path.basename(filePath)}.tmp-${process.pid}-${Date.now()}-${Math.random()
+        .toString(36)
+        .slice(2, 10)}`);
     // Buffer 内容忽略 encoding（writeFileSync 对 Buffer 自动以二进制写出）。
     fs.writeFileSync(tmpPath, content, encoding);
     // fsync the tmp file before rename so its data is durable on disk;

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

@@ -1,5 +1,5 @@
 /**
- * 每 agent 的协议停止通道注册表（design.md §3.3）。
+ * 每 agent 的协议停止通道注册表。
  *
  * Windows 没有可拦截的跨进程 SIGTERM，优雅停止只能靠协议通道（claude 的 stdin
  * 控制通道、codex 的 turn interrupt、ACP 的 session/cancel…）。「无通道」是

package/dist/platform/identity.d.ts

@@ -12,7 +12,13 @@ export interface QueryIdentityOptions {
 export interface VerifyPidIdentityOptions extends QueryIdentityOptions {
     /** 期望的二进制名（basename，如 'claude'/'node'）；win32/darwin 大小写不敏感 */
     expectedBinary: string;
-    /** pid 文件记录的 CreationDate；旧文件缺省该字段则退化为仅命令行匹配 */
+    /**
+     * pid 文件记录的 CreationDate；缺省则退化为仅命令行匹配。
+     * 现状：**无生产写入方**（pid 文件/锁文件都不记 CreationDate），仅测试
+     * 使用——接线需 win32 写侧在正常启动路径多一次 PowerShell 查询自身
+     * CreationDate，与 instance-lock「CIM 只在锁已存在路径查询」的约束冲突，
+     * 故保留该字段但暂不接线。
+     */
     expectedCreationDate?: string;
     /** 匹配强度；默认 'executable'（见 {@link IdentityMatchMode}） */
     matchMode?: IdentityMatchMode;

package/dist/platform/identity.js

@@ -1,5 +1,5 @@
 /**
- * pid 身份验证（design.md §3.4 / §3.5）。
+ * pid 身份验证。
  *
  * POSIX 现状用 `ps -o command=` 读命令行，Windows 没有 ps，等价物是 CIM：
  * PowerShell `Get-CimInstance Win32_Process` 取 CommandLine，并额外取
@@ -9,7 +9,7 @@
  * - 只在查询失败/身份不匹配时返回 null / false，绝不抛给调用方——调用方
  *   （killOrphan、实例锁陈旧判定）一律「只有身份匹配才动手」；
  * - win32 每次查询要拉起 PowerShell（冷启动约 1s），批量扫 pid 文件的场景
- *   （killOrphan）应按需调用，真机矩阵（M0）需实测整体耗时；
+ *   （killOrphan）应按需调用，真机矩阵需实测整体耗时；
  * - platform 显式注入，win32 语义可在任意宿主上单测。
  */
 import { execFileSync, spawn } from 'node:child_process';

package/dist/platform/path.d.ts

@@ -1,6 +1,12 @@
 export interface PathOptions {
     platform?: NodeJS.Platform;
 }
+/**
+ * 路径的「判等键」形态：把 samePath 的平台归一规则单源化，供 Map/Set 键控
+ * 场景使用（按 cwd 建倒排索引时不能每次查询做 O(n) 两两比较）。不变量：
+ * `samePath(a, b)` 当且仅当 `pathKey(a) === pathKey(b)`。
+ */
+export declare function pathKey(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）。

package/dist/platform/path.js

@@ -1,5 +1,5 @@
 /**
- * PathKit — 跨平台路径语义（design.md §5.1）。
+ * PathKit — 跨平台路径语义。
  *
  * 所有 cwd 相等性判断、会话目录编码、pid 文件名后缀、spawn cwd 前统一走本模块。
  * 语义映射：
@@ -14,14 +14,18 @@ import { currentPlatform, isWin32 } from './select.js';
 function resolveOptions(opts) {
     return { platform: opts?.platform ?? currentPlatform };
 }
-export function samePath(a, b, opts) {
+/**
+ * 路径的「判等键」形态：把 samePath 的平台归一规则单源化，供 Map/Set 键控
+ * 场景使用（按 cwd 建倒排索引时不能每次查询做 O(n) 两两比较）。不变量：
+ * `samePath(a, b)` 当且仅当 `pathKey(a) === pathKey(b)`。
+ */
+export function pathKey(p, opts) {
     const { platform } = resolveOptions(opts);
     if (platform === 'linux')
-        return a === b;
+        return p;
     if (isWin32(platform)) {
         // win32：\ 与 / 都是分隔符，且路径大小写不敏感
-        const norm = (p) => p.replaceAll('\\', '/').replace(/\/+$/, '');
-        return norm(a).toLowerCase() === norm(b).toLowerCase();
+        return p.replaceAll('\\', '/').replace(/\/+$/, '').toLowerCase();
     }
     // darwin：默认按大小写不敏感处理（macOS 默认文件系统 APFS 不敏感）；
     // 反斜杠是合法文件名字符，不动。分隔符只有 /。
@@ -29,9 +33,11 @@ export function samePath(a, b, opts) {
     // 此处会判等（cwd 守卫假阳性）——影响面小（默认卷不敏感），如需精确需
     // 逐目录 stat 探测卷大小写属性，暂不做。
     // 尾部分隔符必须与 win32 同口径忽略，否则 `/cd ~/repo/` 与 `/cd ~/repo`
-    // 会被判成两个目录，M2 迁移后直接表现为会话目录错配。
-    const norm = (p) => p.replace(/\/+$/, '');
-    return norm(a).toLowerCase() === norm(b).toLowerCase();
+    // 会被判成两个目录，迁移后直接表现为会话目录错配。
+    return p.replace(/\/+$/, '').toLowerCase();
+}
+export function samePath(a, b, opts) {
+    return pathKey(a, opts) === pathKey(b, opts);
 }
 /**
  * cwd → 会话项目目录名（Claude/pi 的 on-disk 编码，lossy N-to-N）。

package/dist/platform/select.d.ts

@@ -1,5 +1,5 @@
 /**
- * 平台选择的唯一入口（design.md §2.2 纪律）。
+ * 平台选择的唯一入口。
  *
  * `process.platform` 的读取只允许发生在本文件；其余模块一律导入
  * `currentPlatform` / `isWin32`，或接受显式 platform 参数（便于在任意

package/dist/platform/select.js

@@ -1,5 +1,5 @@
 /**
- * 平台选择的唯一入口（design.md §2.2 纪律）。
+ * 平台选择的唯一入口。
  *
  * `process.platform` 的读取只允许发生在本文件；其余模块一律导入
  * `currentPlatform` / `isWin32`，或接受显式 platform 参数（便于在任意

package/dist/platform/shell.d.ts

@@ -1,10 +1,9 @@
 /**
- * ShellBackend：把 `!` 命令与 kimi ACP terminal 的 shell 依赖收进 seam
- * （design.md §7.2）。
+ * ShellBackend：把 `!` 命令与 kimi ACP terminal 的 shell 依赖收进 seam。
  *
  * - posix：`bash -c <command>`（与现状 BashProcessRunner 同语义）；
  * - win32：默认 Git Bash（`bash.exe -c <command>`），powershell / cmd 仅作为
- *   显式用户选择 §7.3；
+ *   显式用户选择；
  * - 首版不做命令翻译器：Git Bash 缺失时抛 {@link ShellUnavailableError}，
  *   由调用方转成明确错误卡（提示需要 Git Bash）。
  *

package/dist/platform/spawn.d.ts

@@ -14,7 +14,7 @@ export declare function spawnProcessSync(command: string, args?: readonly string
 /**
  * env 覆盖合并：先按不区分大小写删除 base 中的同名旧键，再设新值。
  * Windows env 键大小写不敏感，`{...process.env, PATH:x}` 会产生 `PATH`/`Path`
- * 双键（§8.3）。注意 posix 上并非普通 spread：base 中大小写不同名的键（如
+ * 双键。注意 posix 上并非普通 spread：base 中大小写不同名的键（如
  * `Path`）也会被删除，而非与 `PATH` 并存——可接受（posix 语义键为全大写
  * `PATH`，大小写变体本身就不是语义键），但语义与 spread 不同，勿混淆。
  */
@@ -30,7 +30,7 @@ export declare function mergeProcessEnv(base?: NodeJS.ProcessEnv, overrides?: No
  * Windows 上 `DETACHED_PROCESS` 下 cmd.exe 另建控制台并重绑标准句柄，于是
  * 子进程（npm 安装的 agent 全是 `.cmd` 垫片）的 stdout/stderr 永不抵达父进程，
  * 表现为 agent 全程静默、turn 超时。实测 `windowsHide: true` 不能改善，
- * 因此 v1 §3.3「保留 detached + windowsHide」的假设据此修正为「win32 不
+ * 因此 「保留 detached + windowsHide」的假设据此修正为「win32 不
  * detached」。调用方应同时传 `windowsHide: true`，避免 cmd.exe 闪控制台窗口。
  */
 export declare function useDetachedProcessGroup(platform?: NodeJS.Platform): boolean;

package/dist/platform/spawn.js

@@ -32,7 +32,7 @@ export function spawnProcessSync(command, args = [], options = {}) {
 /**
  * env 覆盖合并：先按不区分大小写删除 base 中的同名旧键，再设新值。
  * Windows env 键大小写不敏感，`{...process.env, PATH:x}` 会产生 `PATH`/`Path`
- * 双键（§8.3）。注意 posix 上并非普通 spread：base 中大小写不同名的键（如
+ * 双键。注意 posix 上并非普通 spread：base 中大小写不同名的键（如
  * `Path`）也会被删除，而非与 `PATH` 并存——可接受（posix 语义键为全大写
  * `PATH`，大小写变体本身就不是语义键），但语义与 spread 不同，勿混淆。
  */
@@ -61,7 +61,7 @@ const COMMAND_NOT_FOUND_PATTERN = /is not recognized as an internal or external
  * Windows 上 `DETACHED_PROCESS` 下 cmd.exe 另建控制台并重绑标准句柄，于是
  * 子进程（npm 安装的 agent 全是 `.cmd` 垫片）的 stdout/stderr 永不抵达父进程，
  * 表现为 agent 全程静默、turn 超时。实测 `windowsHide: true` 不能改善，
- * 因此 v1 §3.3「保留 detached + windowsHide」的假设据此修正为「win32 不
+ * 因此 「保留 detached + windowsHide」的假设据此修正为「win32 不
  * detached」。调用方应同时传 `windowsHide: true`，避免 cmd.exe 闪控制台窗口。
  */
 export function useDetachedProcessGroup(platform = currentPlatform) {

package/dist/platform/terminator-posix.js

@@ -56,7 +56,7 @@ async function stopPosix(proc, opts, log) {
         }
         return { requested: true, via: 'taskkill' };
     }
-    // 与 exit 事件竞速等 grace；用 once 避免重复 stop() 累积监听器（P2-15）
+    // 与 exit 事件竞速等 grace；用 once 避免重复 stop() 累积监听器
     let graceTimer;
     const exited = await Promise.race([
         new Promise((resolve) => {

package/dist/platform/terminator-win32.js

@@ -1,5 +1,5 @@
 /**
- * win32 终止器：协议停止通道 → grace 等待 → taskkill 树杀（design.md §3.2）。
+ * win32 终止器：协议停止通道 → grace 等待 → taskkill 树杀。
  *
  * 状态机：
  *   1. 进程已退出 → nothing（via='already-exited'）
@@ -99,7 +99,7 @@ export function createWin32Terminator(deps) {
             return { requested: true, via: 'taskkill' };
         },
         cleanupOnExit(proc) {
-            // M0 真机验证项（§9.2 矩阵）：本方法在 process.on('exit') 里调用，而
+            // 真机验证项（§9.2 矩阵）：本方法在 process.on('exit') 里调用，而
             // killTree 依赖 libuv uv_spawn 在 exit handler 内同步发起 taskkill——
             // 大概率可用（uv_spawn 本身同步），但与 posix 路径（同步 process.kill）
             // 可靠性不等价；失败表现为 win32 上 lark-remote 退出后 agent 变孤儿。

package/dist/platform/terminator.d.ts

@@ -1,5 +1,5 @@
 /**
- * 平台终止器 seam 的接口层（design.md §3.2 / §3.3）。
+ * 平台终止器 seam 的接口层。
  *
  * Windows 没有可拦截的跨进程 SIGTERM、负 PID 无效，因此把「进程组 + 信号」
  * 换成「协议停止通道 + 进程树杀」。本文件只放接口与平台分发，实现见
@@ -14,7 +14,7 @@ export type { AgentStopper } from './agent-stopper.js';
  * 进程终止器。
  *
  * `stop` 的 `immediate` 语义与原 `process-stopper` 的 `stop({immediate})` 对齐。
- * 设计文档声明返回 `Promise<void>`，这里收窄为 {@link TerminateResult}：降级
+ * 声明返回 `Promise<void>`，这里收窄为 {@link TerminateResult}：降级
  * 必须可观测（优雅段被跳过、走了树杀、进程早已退出），否则 win32 上「等一个
  * 不会来的退出事件」这类退化无法被发现。
  */
@@ -39,6 +39,6 @@ export interface TerminatorDeps {
 }
 /**
  * 唯一的终止器选择入口：posix 走组杀，win32 走「协议通道 + taskkill 树杀」。
- * 其余模块一律拿这里的 Terminator，禁止散落平台 if（§2.2）。
+ * 其余模块一律拿这里的 Terminator，禁止散落平台 if。
  */
 export declare function createTerminator(deps: TerminatorDeps): Terminator;

package/dist/platform/terminator.js

@@ -17,12 +17,12 @@ function defaultTerminatorLog(level, message) {
 }
 /**
  * 唯一的终止器选择入口：posix 走组杀，win32 走「协议通道 + taskkill 树杀」。
- * 其余模块一律拿这里的 Terminator，禁止散落平台 if（§2.2）。
+ * 其余模块一律拿这里的 Terminator，禁止散落平台 if。
  */
 export function createTerminator(deps) {
     const platform = deps.platform ?? currentPlatform;
     // 默认日志出口必须真的接上：win32 的「无协议通道 → 直接树杀」「协议通道抛错
-    // → 转树杀」以及 posix 的 grace 超时都是设计要求的可观测降级信号（§3.2），
+    // → 转树杀」以及 posix 的 grace 超时都是设计要求的可观测降级信号，
     // 缺省 undefined 会让这些信号全部静默消失。
     const log = deps.log ?? defaultTerminatorLog;
     if (isWin32(platform)) {

package/dist/platform/types.d.ts

@@ -11,7 +11,7 @@ export interface LaunchSpec {
     /** 可执行文件路径（posix 绝对路径 / win32 含 .cmd 垫片路径） */
     file: string;
 }
-/** 终止结果（§3.2 win32 状态机产出；可观测降级用）。 */
+/** 终止结果（win32 状态机产出；可观测降级用）。 */
 export interface TerminateResult {
     /** 进程是否已确认被请求终止（不代表已退出，退出由 exit 事件驱动） */
     requested: boolean;

package/dist/restart.d.ts

@@ -16,7 +16,7 @@ export declare const RESTART_WAIT_PID_ENV = "LARK_REMOTE_RESTART_WAIT_PID";
  * dir) propagate. Caller picks throw-vs-degrade semantics.
  *
  * Two disciplines live here so every caller inherits them for free:
- * - windowsHide: win32 detached children would flash a console window (§3.7);
+ * - windowsHide: win32 detached children would flash a console window;
  * - the 'error' handler is attached BEFORE the pid check — a failed spawn
  *   emits 'error' asynchronously (ENOENT/EACCES), and the synchronous pid
  *   check throws/returns first, so attaching after would leave the 'error'

package/dist/restart.js

@@ -1,4 +1,4 @@
-import { spawnProcess } from './platform/spawn.js';
+import { mergeProcessEnv, spawnProcess } from './platform/spawn.js';
 import fs from 'node:fs';
 import path from 'node:path';
 import { getLogger } from './logger/index.js';
@@ -23,7 +23,7 @@ const POLL_MS = 100;
  * dir) propagate. Caller picks throw-vs-degrade semantics.
  *
  * Two disciplines live here so every caller inherits them for free:
- * - windowsHide: win32 detached children would flash a console window (§3.7);
+ * - windowsHide: win32 detached children would flash a console window;
  * - the 'error' handler is attached BEFORE the pid check — a failed spawn
  *   emits 'error' asynchronously (ENOENT/EACCES), and the synchronous pid
  *   check throws/returns first, so attaching after would leave the 'error'
@@ -58,7 +58,9 @@ export function spawnDetachedBridge(args, logFilePath, opts) {
  */
 export function spawnReplacementBridge(logsDir) {
     const pid = spawnDetachedBridge(process.argv.slice(1), path.join(logsDir, 'restart-child.log'), {
-        env: { ...process.env, [RESTART_WAIT_PID_ENV]: String(process.pid) },
+        // env 注入统一走 mergeProcessEnv：Windows env 键大小写不敏感，
+        // 覆盖注入必须先按不区分大小写删旧键，避免双键
+        env: mergeProcessEnv(process.env, { [RESTART_WAIT_PID_ENV]: String(process.pid) }),
     });
     if (pid === null) {
         throw new Error('spawn replacement lark-remote failed: no pid');

package/dist/router/config/codex.d.ts

@@ -16,7 +16,7 @@ export declare class CodexConfigBuilder implements AgentConfigCardBuilder {
      * - 否则优先 supported_reasoning_levels 中位 (len-1)/2；
      * - 列表为空才用声明 default_reasoning_level；
      * - 两者皆无 → value=undefined（清空档位 = 不传 effort；router setNestedValue
-     *   对 undefined 做键删除，P1）。
+     *   对 undefined 做键删除）。
      */
     private effortPatchForModel;
 }

package/dist/router/config/codex.js

@@ -41,7 +41,7 @@ export class CodexConfigBuilder {
             key: 'agents.codex.reasoningEffort',
             label: '推理强度',
             type: 'select',
-            // 档位按目录实际声明透传（P2-5）：codex 支持 none/Custom，不再按标准枚举过滤
+            // 档位按目录实际声明透传：codex 支持 none/Custom，不再按标准枚举过滤
             options: getReasoningEffortOptions(currentCodexModel),
             currentValue: currentReasoningEffort,
         });
@@ -108,7 +108,7 @@ export class CodexConfigBuilder {
      * - 否则优先 supported_reasoning_levels 中位 (len-1)/2；
      * - 列表为空才用声明 default_reasoning_level；
      * - 两者皆无 → value=undefined（清空档位 = 不传 effort；router setNestedValue
-     *   对 undefined 做键删除，P1）。
+     *   对 undefined 做键删除）。
      */
     effortPatchForModel(config, newModel) {
         const currentReasoningEffort = config.agents?.codex?.reasoningEffort;

package/dist/router/config/opencode.js

@@ -29,7 +29,7 @@ export class OpencodeConfigBuilder {
             type: 'select',
             options: modelOptions,
         });
-        // §P5: mode select（build/plan，默认 build）——opencode 无运行期审批档位，
+        // mode select（build/plan，默认 build）——opencode 无运行期审批档位，
         // mode 即审批粒度档位（build 逐项审批 / plan 规划模式）。
         const currentMode = displayConfig.agents?.opencode?.mode ?? 'build';
         fields.push({

package/dist/router/index.d.ts

@@ -222,7 +222,7 @@ export declare class CommandRouter {
     /**
      * Route a message: if it starts with /, handle as command; if it starts with !, execute as bash; otherwise forward to Claude.
      *
-     * 命令识别前置条件（2026-09-15 P0 修复，`inbound-unified-input-design.md` §5.6）：
+     * 命令识别前置条件（2026-09-15修复，`inbound-unified-input-design.md` §5.6）：
      * 裸前缀判定会被结构占位符命中 —— SDK 把富文本里的图片渲染成 `![image](img_v3_…)`，
      * 首字符恰好是 `!`，整段用户消息被当 shell 命令执行（`executeBash "[image](img_v3_…"`）。
      * 因此命令前缀只在「调用方声明纯文本 + 剥离占位符后非空且无占位符 + 首字符是 / 或 !」
@@ -304,7 +304,7 @@ export declare class CommandRouter {
      *
      * offset 恒重置为 0（新筛选从第 1 页开始）。路径校验与 TOCTOU 兜底照
      * handleLsPage——校验失败只回错误 toast，绝不动卡片（否则用户看到一张空卡）。
-     * ls.browse / ls.switch 的 value 里刻意不带 q，换目录即清除筛选（设计文档 §2.3）。
+     * ls.browse / ls.switch 的 value 里刻意不带 q，换目录即清除筛选。
      */
     private handleLsFilter;
     /**
@@ -350,17 +350,17 @@ export declare class CommandRouter {
         internalKey: string;
     } | null;
     /**
-     * W2.8 单源：重建 order/ws 列表卡（不投递，card 进 callback 响应体用）。
+     * 单源：重建 order/ws 列表卡（不投递，card 进 callback 响应体用）。
      * `q` 只服务 ws 卡的关键词筛选；order 卡无此功能，不透传。
      */
     private rebuildListCard;
     /**
-     * W2.8 单源：「重建列表卡 → updateCardInPlace」原地刷新骨架（列表卡删除/
+     * 单源：「重建列表卡 → updateCardInPlace」原地刷新骨架（列表卡删除/
      * 翻页/移除/排序/筛选动作共用）。返回重建后的卡片；无卡时返回 undefined 且跳过更新。
      */
     private refreshListCard;
     /**
-     * W2.8 单源：order 三个 input handler（aliasInput/aliasRemove/textInput）
+     * 单源：order 三个 input handler（aliasInput/aliasRemove/textInput）
      * 的公共骨架——校验 orderId → reload+find → mutate → 成功后 toast + raw 卡。
      * mutate 返回 error 时仅回 error toast，不重渲染。
      * 注意：本 helper 只服务「toast + card 进响应体」语义（飞书需用响应体原地
@@ -472,7 +472,7 @@ export declare class CommandRouter {
     setNestedValue(target: AppConfig, key: string, value: unknown): void;
     diffConfig(original: AppConfig, pending: AppConfig): Record<string, string | undefined>;
     /**
-     * config 写盘后的运行时传播（P1-6：自 config.save 卡片路径抽出，卡片保存与
+     * config 写盘后的运行时传播（自 config.save 卡片路径抽出，卡片保存与
      * `/config <key> <value>` 文本直写两条路径共用）。
      *
      * 1. bridge 运行时值同步：setConfig + idle watchdog timeout；
@@ -480,7 +480,7 @@ export declare class CommandRouter {
      *    配置值，/status 与真实 run 自相矛盾）；
      * 3. defaultAgent 切换 → 旧 agent session 存 previousSessions、新 agent 恢复
      *    或清空（等效 /new）；
-     * 4. 当前 agent 配置变更 → syncAgentChoices 并原子写盘（P1-7：禁裸同步写盘，
+     * 4. 当前 agent 配置变更 → syncAgentChoices 并原子写盘（禁裸同步写盘，
      *    写一半崩溃会截断 config.yaml 导致 bridge 起不来）。
      *
      * @param updates 以 config 路径形式给出的变更 key（卡片路径来自 diffConfig；
@@ -530,7 +530,7 @@ export declare class CommandRouter {
     private buildConfigSwitchCard;
     /**
      * Whether a session of the given agent kind can be compacted from a resume
-     * card. Design doc §6.2-2: duck-typing — check if the runner has `runCompact`
+     * card. duck-typing — check if the runner has `runCompact`
      * (codex app-server, kimi acp), instead of hardcoding agentKind === 'codex'.
      */
     private canCompactSession;
@@ -584,7 +584,7 @@ export declare class CommandRouter {
      */
     cmdWs(args: string[], ctx: CommandContext, offset?: number, q?: string): CommandResult;
     /**
-     * L3: degraded card when a session's export is non-empty but unparseable
+     * degraded card when a session's export is non-empty but unparseable
      * (truncated by opencode's pipe cap on huge sessions, or otherwise corrupt).
      * The session exists, so reuse listSessions metadata (title) instead of the
      * misleading "未找到". Reuses the same card-builder helpers (markdownDiv) as