lark-remote 0.4.4 → 0.5.0

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

@@ -1,17 +1,21 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { silentlyUnlink, withBusyRetry } from '../common/fs.js';
+import { bestEffortUnlink, 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）；重试耗尽后
+ * 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;
@@ -63,7 +67,7 @@ export function atomicWrite(filePath, content, encoding = 'utf-8') {
         // errors we must not leak the tmp file — except when the scene is
         // deliberately preserved after busy-retry exhaustion.
         if (!preserveTmpScene) {
-            silentlyUnlink(tmpPath);
+            bestEffortUnlink(tmpPath);
         }
     }
 }
@@ -86,7 +90,7 @@ export function atomicMoveFile(srcPath, destPath) {
     catch (err) {
         if (err.code === 'EXDEV') {
             fs.copyFileSync(srcPath, destPath);
-            silentlyUnlink(srcPath);
+            bestEffortUnlink(srcPath);
         }
         else {
             throw err;

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…）。「无通道」是
@@ -7,7 +7,7 @@
  * 不会来的退出事件。
  *
  * **键 = agent + pid，不是 agent 单维**。两条理由：
- *   1. 同一 agent 可以同时有多个存活子进程（每个 workspace 一条长驻连接，外加
+ *   1. 同一 agent 可以同时有多个存活子进程（每个 cwd 一条长驻连接，外加
  *      claude 的进程代际更替）。按 agent 单键索引时后注册的连接会**覆盖**前一个
  *      的通道，Terminator 便拿着 A 工作区的通道去停 B 工作区的进程；
  *   2. Terminator 手上只有 `proc`，只有 pid 能把「这条通道」与「正要停的那个

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

@@ -41,22 +41,22 @@ async function stopPosix(proc, opts, log) {
     }
     // 负 PID = 整个进程组：shell 包装层与孙进程一并带走
     const pgid = -pid;
-    log('debug', `[process-stopper] sending SIGTERM to pgid=${pgid} immediate=${opts.immediate}`);
+    log('debug', `[terminator] sending SIGTERM to pgid=${pgid} immediate=${opts.immediate}`);
     const termErr = signalGroup(pgid, 'SIGTERM');
     if (termErr) {
-        log('warn', `[process-stopper] ${termErr}`);
+        log('warn', `[terminator] ${termErr}`);
         return { requested: false, via: 'cooperative', error: termErr };
     }
     if (opts.immediate) {
         // 不等待：SIGKILL 紧随其后；进程已死时 kill 抛 ESRCH，忽略即可
         const killErr = signalGroup(pgid, 'SIGKILL');
         if (killErr) {
-            log('warn', `[process-stopper] ${killErr}`);
+            log('warn', `[terminator] ${killErr}`);
             return { requested: false, via: 'taskkill', error: killErr };
         }
         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) => {
@@ -71,10 +71,10 @@ async function stopPosix(proc, opts, log) {
     if (graceTimer)
         clearTimeout(graceTimer);
     if (!exited) {
-        log('info', `[process-stopper] process group ${pgid} did not exit within grace period, sending SIGKILL`);
+        log('info', `[terminator] process group ${pgid} did not exit within grace period, sending SIGKILL`);
         const killErr = signalGroup(pgid, 'SIGKILL');
         if (killErr) {
-            log('warn', `[process-stopper] ${killErr}`);
+            log('warn', `[terminator] ${killErr}`);
             return { requested: false, via: 'taskkill', error: killErr };
         }
         return { requested: true, via: 'taskkill' };

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'）
@@ -74,7 +74,7 @@ export function createWin32Terminator(deps) {
                 return { requested: true, via: 'taskkill' };
             }
             const agent = deps.agent;
-            // 按 agent + pid 查：同一 agent 可能有多条长驻连接（每 workspace 一条），
+            // 按 agent + pid 查：同一 agent 可能有多条长驻连接（每 cwd 一条），
             // 只有 pid 能把通道归属钉到手上这个 proc 上。
             const stopper = agent === undefined ? undefined : stoppers.get(agent, proc.pid);
             if (!stopper) {
@@ -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/card-helpers.d.ts

@@ -8,7 +8,7 @@
  */
 import { markdownDiv } from '../card/collapsible.js';
 import type { AgentSessionContentEvent } from '../runner/index.js';
-import { formatUsageStats } from './utils.js';
+import { formatUsageStats } from './usage-format.js';
 type SessionUsageLike = Parameters<typeof formatUsageStats>[0];
 /**
  * Build a collapsible panel for a single session content event.
@@ -28,8 +28,6 @@ type SessionUsageLike = Parameters<typeof formatUsageStats>[0];
  */
 export declare function sessionEventPanel(ev: AgentSessionContentEvent, index: number, totalEvents: number, tailExpandedCount?: number, agentKind?: string): object;
 export { markdownDiv };
-/** 分页卡「跳转页码」输入框的组件 name（仅用于结构断言与可读性）。 */
-export declare const PAGE_JUMP_INPUT_NAME = "pageInput";
 /** 页码输入非法时的统一提示文案（/ls /ws /resume /active /order 共用）。 */
 export declare const PAGE_JUMP_INVALID_HINT = "\u8BF7\u8F93\u5165\u6709\u6548\u7684\u9875\u7801\uFF08\u6B63\u6574\u6570\uFF09";
 /**

package/dist/router/card-helpers.js

@@ -9,7 +9,7 @@
 import { agentDisplayName } from '../card/card-shared.js';
 import { collapsibleMarkdownPanel, markdownDiv } from '../card/collapsible.js';
 import { formatTimestamp } from '../card/time.js';
-import { formatUsageStats } from './utils.js';
+import { formatUsageStats } from './usage-format.js';
 /**
  * Build a collapsible panel for a single session content event.
  *
@@ -64,7 +64,7 @@ function eventLabel(ev, agentKind) {
 }
 export { markdownDiv };
 /** 分页卡「跳转页码」输入框的组件 name（仅用于结构断言与可读性）。 */
-export const PAGE_JUMP_INPUT_NAME = 'pageInput';
+const PAGE_JUMP_INPUT_NAME = 'pageInput';
 /** 页码输入非法时的统一提示文案（/ls /ws /resume /active /order 共用）。 */
 export const PAGE_JUMP_INVALID_HINT = '请输入有效的页码（正整数）';
 /**

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,
         });
@@ -81,7 +81,7 @@ export class CodexConfigBuilder {
         if (key === 'agents.codex.modelProvider' && typeof value === 'string') {
             const codexCfg = loadCodexConfig();
             const currentModel = config.agents?.codex?.model;
-            const modelPatch = resetModelPatch(key, 'agents.codex.model', currentModel, codexCfg.modelOptions(value));
+            const modelPatch = resetModelPatch('agents.codex.model', currentModel, codexCfg.modelOptions(value));
             if (modelPatch) {
                 patches.push(modelPatch);
                 const replacedModel = modelPatch.value;
@@ -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/common/model-patch.d.ts

@@ -10,13 +10,12 @@
  * model is not offered by the new provider (and the new provider has models),
  * patch the model to the provider's first option.
  *
- * @param providerKey  The field key that changed, e.g. 'agents.codex.modelProvider'.
  * @param modelKey     The model field to reset, e.g. 'agents.codex.model'.
  * @param currentModel The currently-configured model value (may be undefined).
  * @param newModelOptions Models offered by the newly-selected provider.
  * @returns A `{ key, value }` patch, or null when no reset is needed.
  */
-export declare function resetModelPatch(providerKey: string, modelKey: string, currentModel: string | undefined, newModelOptions: string[]): {
+export declare function resetModelPatch(modelKey: string, currentModel: string | undefined, newModelOptions: string[]): {
     key: string;
     value: unknown;
 } | null;

package/dist/router/config/common/model-patch.js

@@ -10,13 +10,12 @@
  * model is not offered by the new provider (and the new provider has models),
  * patch the model to the provider's first option.
  *
- * @param providerKey  The field key that changed, e.g. 'agents.codex.modelProvider'.
  * @param modelKey     The model field to reset, e.g. 'agents.codex.model'.
  * @param currentModel The currently-configured model value (may be undefined).
  * @param newModelOptions Models offered by the newly-selected provider.
  * @returns A `{ key, value }` patch, or null when no reset is needed.
  */
-export function resetModelPatch(providerKey, modelKey, currentModel, newModelOptions) {
+export function resetModelPatch(modelKey, currentModel, newModelOptions) {
     const currentModelIsValid = newModelOptions.some((m) => m === currentModel);
     if (!currentModelIsValid && newModelOptions.length > 0) {
         return { key: modelKey, value: newModelOptions[0] };

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({
@@ -58,7 +58,7 @@ export class OpencodeConfigBuilder {
         if (key === 'agents.opencode.providerID' && typeof value === 'string') {
             const opencodeCfg = loadOpencodeConfig();
             const currentModel = config.agents?.opencode?.modelID;
-            const modelPatch = resetModelPatch(key, 'agents.opencode.modelID', currentModel, opencodeCfg.modelOptions(value));
+            const modelPatch = resetModelPatch('agents.opencode.modelID', currentModel, opencodeCfg.modelOptions(value));
             if (modelPatch)
                 patches.push(modelPatch);
         }

package/dist/router/config/pi.js

@@ -39,7 +39,7 @@ export class PiConfigBuilder {
         // provider 变更时，重置 model 为新 provider 的首个模型
         if (key === 'agents.pi.provider' && typeof value === 'string') {
             const currentModel = config.agents?.pi?.model;
-            const modelPatch = resetModelPatch(key, 'agents.pi.model', currentModel, getPiModelOptions(value));
+            const modelPatch = resetModelPatch('agents.pi.model', currentModel, getPiModelOptions(value));
             if (modelPatch)
                 patches.push(modelPatch);
         }