lark-remote 0.4.5 → 0.5.0

package/dist/router/index.js

@@ -262,7 +262,7 @@ const APPROVAL_ACTION_SPECS = {
     },
 };
 // ===========================================================================
-// W2.1 命令名单单一事实源
+// 命令名单单一事实源
 // 直返语义（cardAction 同步返回 toast 给飞书回调，index.ts 控制层据此不经
 // 队列直接处理）与即时语义（绕串行队列 enqueueImmediate，§9.6）正交，两个
 // 独立清单只共享审批命令名来源（APPROVAL_ACTION_SPECS keys）——历史上同一
@@ -339,7 +339,7 @@ export const SESSION_MUTATING_ACTION_CMDS = new Set([
     'ws.use',
     'config.save',
 ]);
-/** W2.8 单源：payload.offset → 钳位 offset（原先 9 处逐字副本）。 */
+/** 单源：payload.offset → 钳位 offset（原先 9 处逐字副本）。 */
 function payloadOffset(value) {
     return Math.max(0, Math.trunc(Number(value.offset) || 0));
 }
@@ -466,7 +466,7 @@ export 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_…"`）。
      * 因此命令前缀只在「调用方声明纯文本 + 剥离占位符后非空且无占位符 + 首字符是 / 或 !」
@@ -513,7 +513,7 @@ export class CommandRouter {
             await this.bridge.executeBash(cmd, ctx);
             return null;
         }
-        // Forward to Claude (P1-14: pass the enqueue-time cwd through so the
+        // Forward to Claude (pass the enqueue-time cwd through so the
         // run uses the same cwd as the serial queue lane, even if /cd ran while
         // the message was queued)
         // 剥离占位符后再转发：agent 只该看到用户文本（附图已转成 attachments 块，
@@ -538,7 +538,7 @@ export class CommandRouter {
      * Validates payload and dispatches to the corresponding command.
      */
     async handleCardAction(value, ctx) {
-        // W2.1：审批家族以 APPROVAL_ACTION_SPECS keys 为单一来源分发
+        // 审批家族以 APPROVAL_ACTION_SPECS keys 为单一来源分发
         // （原 7 个 case 与 spec keys 是同一份知识的两份拷贝，已两次漂移）。
         if (APPROVAL_ACTION_CMDS.includes(value.cmd)) {
             return this.handleApprovalAction(value, ctx);
@@ -584,7 +584,7 @@ export class CommandRouter {
                     await this.bridge.sendResult({ text: '请先 /cd 设置工作目录' }, ctx);
                     return;
                 }
-                // P1-5：校验前不得写入 sessionId。旧实现先无条件 setSessionId 再调
+                // 校验前不得写入 sessionId。旧实现先无条件 setSessionId 再调
                 // cmdResume 校验，过期卡片（session 不在当前 cwd）校验失败时 store 已被
                 // 污染；value.sessionId 缺失时还会静默清空已有绑定。现在统一走 cmdResume
                 // 的已验证路径（:2352 校验通过才写入），sessionId 缺失直接报错。
@@ -759,7 +759,7 @@ export class CommandRouter {
         if (!targetTask) {
             // The target already began (or was cancelled) before this handler ran. We
             // must NOT claim the queue was cleared — nothing is removed in this branch
-            // and tasks queued behind the target are still waiting (see A13).
+            // and tasks queued behind the target are still waiting.
             await this.bridge.sendResult({
                 text: '该消息已不在队列中（可能已开始执行或被撤销），无法立即执行。其余排队消息保持原状。',
             }, ctx);
@@ -777,7 +777,7 @@ export class CommandRouter {
         // which would put the edited task behind tasks queued after it.
         if (targetTask.editedMessage) {
             const editedContent = targetTask.editedMessage;
-            // D3/Step3: 替换闭包复用原任务的 binding（不重新快照）+ 恢复丢失的
+            ///Step3: 替换闭包复用原任务的 binding（不重新快照）+ 恢复丢失的
             // cwdOverride（lane cwd 同源）。否则编辑后重新执行的 run 会丢 cwd 与绑定。
             this.bridge.setTaskReplacement(cwd, messageId, async () => {
                 await this.handle(editedContent, ctx, {
@@ -834,7 +834,7 @@ export class CommandRouter {
         const latestTask = this.bridge.getQueuedTask(cwd, messageId);
         if (latestTask?.editedMessage) {
             const editedContent = latestTask.editedMessage;
-            // D3/Step3: 复用原任务 binding + 恢复 cwdOverride（同上）。
+            ///Step3: 复用原任务 binding + 恢复 cwdOverride（同上）。
             this.bridge.setTaskReplacement(cwd, messageId, async () => {
                 await this.handle(editedContent, ctx, {
                     cwdOverride: cwd,
@@ -1049,7 +1049,7 @@ export class CommandRouter {
         // setTaskReplacement and the begin-path consumption are synchronous, so
         // there is no interleaving window.
         //
-        // D3/Step3：复用原任务 binding（不重新快照）+ 恢复 cwdOverride。
+        ///Step3：复用原任务 binding（不重新快照）+ 恢复 cwdOverride。
         const inputTask = this.bridge.getQueuedTask(cwd, messageId);
         if (!inputTask) {
             // Task already left the queue (began or was cancelled) before we could
@@ -1155,7 +1155,7 @@ export class CommandRouter {
     async handleLsRefresh(value, ctx) {
         const targetPath = value.path;
         const offset = value.offset ?? 0;
-        // TOCTOU guard (review P2-2): existsSync → statSync can race (target
+        // TOCTOU guard: existsSync → statSync can race (target
         // deleted in between), throwing into enqueueImmediate's catch which only
         // logs — violating the "card button clicks must give visible feedback"
         // red line. Treat a vanished/non-dir path as "use current cwd" instead of
@@ -1185,7 +1185,7 @@ export class CommandRouter {
             return { toast: { type: 'error', content: paging.error } };
         }
         const resolvedTarget = path.resolve(targetPath);
-        // TOCTOU guard (review P2-2): existsSync → statSync can race; without the
+        // TOCTOU guard: existsSync → statSync can race; without the
         // try/catch the throw lands in enqueueImmediate's silent .catch and the
         // paginated card never updates (no visible feedback for the click).
         let isDir;
@@ -1208,7 +1208,7 @@ export class CommandRouter {
      *
      * offset 恒重置为 0（新筛选从第 1 页开始）。路径校验与 TOCTOU 兜底照
      * handleLsPage——校验失败只回错误 toast，绝不动卡片（否则用户看到一张空卡）。
-     * ls.browse / ls.switch 的 value 里刻意不带 q，换目录即清除筛选（设计文档 §2.3）。
+     * ls.browse / ls.switch 的 value 里刻意不带 q，换目录即清除筛选。
      */
     async handleLsFilter(value, ctx) {
         const targetPath = value.path;
@@ -1352,7 +1352,7 @@ export class CommandRouter {
         };
     }
     /**
-     * W2.8 单源：重建 order/ws 列表卡（不投递，card 进 callback 响应体用）。
+     * 单源：重建 order/ws 列表卡（不投递，card 进 callback 响应体用）。
      * `q` 只服务 ws 卡的关键词筛选；order 卡无此功能，不透传。
      */
     rebuildListCard(kind, offset, ctx, q) {
@@ -1361,7 +1361,7 @@ export class CommandRouter {
         return this.cmdWs([], ctx, offset, q).card;
     }
     /**
-     * W2.8 单源：「重建列表卡 → updateCardInPlace」原地刷新骨架（列表卡删除/
+     * 单源：「重建列表卡 → updateCardInPlace」原地刷新骨架（列表卡删除/
      * 翻页/移除/排序/筛选动作共用）。返回重建后的卡片；无卡时返回 undefined 且跳过更新。
      */
     async refreshListCard(kind, value, ctx) {
@@ -1372,7 +1372,7 @@ export class CommandRouter {
         return card;
     }
     /**
-     * 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 进响应体」语义（飞书需用响应体原地
@@ -1863,7 +1863,7 @@ export class CommandRouter {
                 try {
                     const oldDefaultAgent = this.config.defaultAgent;
                     this.config = setConfigValues(this.configPath, this.config, updates);
-                    // P1-6：运行时传播（idleTimeout / clearRunners / syncAgentChoices /
+                    // 运行时传播（idleTimeout / clearRunners / syncAgentChoices /
                     // defaultAgent 切换的 session 处理）抽到共享方法，与文本直写路径共用。
                     const switchResult = this.propagateConfigSave(oldDefaultAgent, updates, ctx);
                     this.pendingConfig = null;
@@ -1909,7 +1909,7 @@ export class CommandRouter {
         return diffConfig(original, pending);
     }
     /**
-     * config 写盘后的运行时传播（P1-6：自 config.save 卡片路径抽出，卡片保存与
+     * config 写盘后的运行时传播（自 config.save 卡片路径抽出，卡片保存与
      * `/config <key> <value>` 文本直写两条路径共用）。
      *
      * 1. bridge 运行时值同步：setConfig + idle watchdog timeout；
@@ -1917,7 +1917,7 @@ export 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；
@@ -1991,7 +1991,7 @@ export class CommandRouter {
                 switchSessionId = '';
             }
         }
-        // DSH preset 变更 = 下次 run 新建 session（§4.3 D1）：
+        // DSH preset 变更 = 下次 run 新建 session（§4.3）：
         // preset 在 session 创建时固定，中途切换会被服务端拒绝（agent-preset-conflict）。
         // 旧 sessionId 存入 previousSessions 停车位（可手动 /resume，但 /resume 会做
         // preset 一致性校验），当前 sessionId 清空——下次 run 走 session.create 新建。
@@ -2009,7 +2009,7 @@ export class CommandRouter {
                 switchNotice = `DSH preset 已变更，下次消息将新建会话`;
             }
         }
-        // DSH host 变更 = 换服务（CC-02）：旧 host 的 sessionId 发往新 host 是错的。
+        // DSH host 变更 = 换服务：旧 host 的 sessionId 发往新 host 是错的。
         // 视为 session 边界，仿 preset 分支停车 + 清空当前 sessionId，下次 run 新建会话。
         const hasDshHostChange = Object.keys(updates).some((k) => k === 'agents.dsh.host');
         if (hasDshHostChange && this.config.defaultAgent === 'dsh' && !switchNotice) {
@@ -2029,11 +2029,11 @@ export class CommandRouter {
         const hasCurrentAgentUpdate = Object.keys(updates).some((k) => k === currentAgentConfigKey || k.startsWith(`${currentAgentConfigKey}.`));
         if (hasCurrentAgentUpdate) {
             this.config = syncAgentChoices(this.config, currentAgent);
-            // P1-7：agentChoices 同步写盘必须走原子写（tmp+rename），禁裸同步写盘
+            // agentChoices 同步写盘必须走原子写（tmp+rename），禁裸同步写盘
             atomicWrite(this.configPath, YAML.stringify(this.config));
             this.bridge.setConfig(this.config);
         }
-        // P1-6 + live approval settings (§P5): active workspace-lifetime runners
+        // live approval settings: active workspace-lifetime runners
         // are not evicted by clearRunners() (would orphan the live subprocess).
         // Push the new approval-mode settings to those runners via the unified
         // duck method `updateApprovalMode` (codex thread/settings/update,
@@ -2446,7 +2446,7 @@ ${sessionCwdLine}${agentLines.map((l) => `- ${l}`).join('\n')}
         // Claude writes into JSONL (e.g. `/tmp` → `/private/tmp` on macOS).
         // Without this, a hand-typed unresolved path never matches any JSONL's
         // cwd field and the user's `/cd /tmp/foo` never finds their sessions.
-        // TOCTOU: the directory may vanish between stat and realpath (review P2-1).
+        // TOCTOU: the directory may vanish between stat and realpath.
         // Reject gracefully instead of letting realpathSync throw into the queue
         // task's .catch (which only logs — the user gets no feedback). Mirrors
         // handleLsSwitch's realpath guard so /cd and ls.switch behave identically.
@@ -2503,7 +2503,7 @@ ${sessionCwdLine}${agentLines.map((l) => `- ${l}`).join('\n')}
      */
     switchCwdAndNotify(userId, canonical, _ctx) {
         this.sessionStore.setCwd(userId, canonical);
-        // Auto-resume newest session if exists (P1-15: 读取失败不阻断切换，给可见提示)
+        // Auto-resume newest session if exists (读取失败不阻断切换，给可见提示)
         let newestSession;
         try {
             newestSession = this.sessionReader.getNewestSession(canonical);
@@ -2634,7 +2634,7 @@ ${sessionCwdLine}${agentLines.map((l) => `- ${l}`).join('\n')}
     }
     /**
      * 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'.
      */
     canCompactSession(agentKind, cwd) {
@@ -3111,7 +3111,7 @@ ${sessionCwdLine}${agentLines.map((l) => `- ${l}`).join('\n')}
                 if (!fs.existsSync(wsPath))
                     return { text: `路径不存在: ${wsPath}` };
                 // Canonicalize via realpath so it matches Claude JSONL cwd (2026-06-21).
-                // TOCTOU guard (review P2-1): mirror cmdCd — if the path vanishes
+                // TOCTOU guard: mirror cmdCd — if the path vanishes
                 // between existsSync and realpath, reply gracefully instead of
                 // throwing into the queue task's silent .catch.
                 let canonical;
@@ -3332,7 +3332,7 @@ ${sessionCwdLine}${agentLines.map((l) => `- ${l}`).join('\n')}
         }
     }
     /**
-     * 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
@@ -3427,7 +3427,7 @@ ${sessionCwdLine}${agentLines.map((l) => `- ${l}`).join('\n')}
                     };
                 }
             }
-            // L3: 校验通过后才写入
+            // 校验通过后才写入
             this.sessionStore.setSessionId(ctx.userId, agentKind, sessionIdArg, cwd);
             const { events: content, usage, isActive, aiTitle, recap, displayTitle, activeRunRunId, } = this.readSessionDisplayState(sessionIdArg, cwd, {
                 agentKind,
@@ -3490,7 +3490,7 @@ ${sessionCwdLine}${agentLines.map((l) => `- ${l}`).join('\n')}
             }
         }
         catch (err) {
-            // P1-15: 读取失败必须给用户可见反馈，而不是误导性的「没有 session 记录」
+            // 读取失败必须给用户可见反馈，而不是误导性的「没有 session 记录」
             const msg = err instanceof Error ? err.message : String(err);
             return { text: `读取 ${agentDisplayName(agentKind)} session 列表失败: ${msg}` };
         }
@@ -3562,7 +3562,7 @@ ${sessionCwdLine}${agentLines.map((l) => `- ${l}`).join('\n')}
             const prefetchedTitle = meta?.displayTitle;
             // aiTitle 不能单独作为"预取标题"键：若 displayTitle 缺失（理论上 opencode
             // info.title 非空但 export 无 user text），标题兜底是 summary，label 必须
-            // 是中性"会话摘要"而不是"最近输入"（Review R3 P2-1 边缘分支）。
+            // 是中性"会话摘要"而不是"最近输入"（Review 边缘分支）。
             const titleText = prefetchedTitle ?? (summaryIsPlaceholder ? '' : s.summary);
             const titleLabel = prefetchedTitle
                 ? meta?.aiTitle
@@ -3727,7 +3727,7 @@ ${sessionCwdLine}${agentLines.map((l) => `- ${l}`).join('\n')}
                 elements.push({ tag: 'hr' });
             }
         }
-        // Pagination bar（W2.9 复用 paginationBar：safeOffset 已对齐页边界，
+        // Pagination bar（复用 paginationBar：safeOffset 已对齐页边界，
         // offset±pageSize 与原先 currentPage±1 的页码换算等价）
         if (totalPages > 1) {
             elements.push(...paginationBar({
@@ -3763,14 +3763,14 @@ ${sessionCwdLine}${agentLines.map((l) => `- ${l}`).join('\n')}
             const value = args.slice(1).join(' ');
             try {
                 const oldDefaultAgent = this.config.defaultAgent;
-                // P2-23：直写前若 pendingConfig 存在未保存差异，提示用户被丢弃的条数，
+                // 直写前若 pendingConfig 存在未保存差异，提示用户被丢弃的条数，
                 // 避免静默清空导致用户在卡片上的修改无反馈丢失。差异必须在 setConfigValue
                 // 之前计算——直写本身也会改变 config，不应计入「被丢弃的未保存修改」。
                 const discarded = this.pendingConfig
                     ? Object.keys(this.diffConfig(this.config, this.pendingConfig)).length
                     : 0;
                 this.config = setConfigValue(this.configPath, this.config, key, value);
-                // P1-6：直写路径与 config.save 卡片路径共用运行时传播（idleTimeout /
+                // 直写路径与 config.save 卡片路径共用运行时传播（idleTimeout /
                 // clearRunners / syncAgentChoices / defaultAgent 切换）。key 经 mapAgentKey
                 // 归一化，pi./codex./opencode./kimi. 命中 agents.* 判定；claude. 与
                 // defaultAgent 不再漏判。

package/dist/router/order-exec-dispatch.js

@@ -23,7 +23,7 @@ export async function dispatchOrderExecForQueue(args) {
         await bridge.sendResult({ text: '指令不存在或已被删除' }, ctx);
         return 'not-found';
     }
-    // Step4/D4: 入队时刻（T0）快照 agent+session，随任务闭包带到 T1 执行时刻，
+    // Step4/入队时刻快照 agent+session，随任务闭包带到执行时刻，
     // 避免排队期间 /new、/config 改写 live 状态导致语义漂移。唯一捕获点
     // Bridge.currentBinding。
     const binding = bridge.currentBinding(ctx.userId);
@@ -38,7 +38,7 @@ export async function dispatchOrderExecForQueue(args) {
             // The internal key is NOT a valid Feishu message id, so the queue
             // status card must reply to the real Feishu card message id instead.
             feishuReplyTo: ctx.messageId,
-            // D3/Step4：binding 随 taskMeta 存进 QueuedTask，供替换闭包
+            ///Step4：binding 随 taskMeta 存进 QueuedTask，供替换闭包
             // （queue.edit/queue.immediate）复用，不重新快照。
             binding,
         },

package/dist/runner/bash/runner.d.ts

@@ -28,7 +28,7 @@ export interface BashRunner {
 export declare class BashProcessRunner implements BashRunner {
     private currentProcess;
     /**
-     * 背压高水位/低水位（P1-4 层④，参照 jsonl-stream.ts 的 pauseThreshold/
+     * 背压高水位/低水位（层④，参照 jsonl-stream.ts 的 pauseThreshold/
      * resumeThreshold）。stdout/stderr 队列超过高水位时 pause 流（内存有界），
      * 消费者 drain 到低水位后 resume。构造可注入以便测试用小水位。
      */
@@ -50,7 +50,7 @@ export declare class BashProcessRunner implements BashRunner {
         cwd: string;
     }): AsyncGenerator<BashOutputEvent>;
     /**
-     * P1-22: called by the process-level exit dispatcher on SIGINT/SIGTERM/exit.
+     * called by the process-level exit dispatcher on SIGINT/SIGTERM/exit.
      * Kills the whole process group (leader + background children) via
      * Terminator, matching agent-runner cleanupOnExit semantics.
      */

package/dist/runner/bash/runner.js

@@ -17,7 +17,7 @@ import { registerExitCleanup, unregisterExitCleanup } from '../common/spawning-r
 export class BashProcessRunner {
     currentProcess = null;
     /**
-     * 背压高水位/低水位（P1-4 层④，参照 jsonl-stream.ts 的 pauseThreshold/
+     * 背压高水位/低水位（层④，参照 jsonl-stream.ts 的 pauseThreshold/
      * resumeThreshold）。stdout/stderr 队列超过高水位时 pause 流（内存有界），
      * 消费者 drain 到低水位后 resume。构造可注入以便测试用小水位。
      */
@@ -32,7 +32,7 @@ export class BashProcessRunner {
         if (this.queueLowWater > this.queueHighWater) {
             this.queueLowWater = this.queueHighWater;
         }
-        // `!` bash 无协议停止通道（§3.3）：posix 走组杀（与原 ProcessStopper 同实现），
+        // `!` bash 无协议停止通道：posix 走组杀（与原 ProcessStopper 同实现），
         // win32 优雅段显式跳过后树杀。
         this.terminator = opts?.terminator ?? createTerminator({ graceMs: stopGraceMs, agent: 'bash' });
         this.shell = opts?.shell ?? createShellBackend();
@@ -61,7 +61,7 @@ export class BashProcessRunner {
             });
         }
         catch (err) {
-            // win32 Git Bash 缺失（§7.2）：同步抛出，转成明确错误输出而非悬死。
+            // win32 Git Bash 缺失：同步抛出，转成明确错误输出而非悬死。
             if (err instanceof ShellUnavailableError) {
                 getLogger().warn(`[bash-runner] shell unavailable: ${err.message}`);
                 yield { type: 'stderr', content: `${err.message}\n` };
@@ -76,7 +76,7 @@ export class BashProcessRunner {
         const stdout = proc.stdout;
         const stderr = proc.stderr;
         getLogger().info(`[bash-runner] spawn pid=${proc.pid} command="${command.slice(0, 50)}..." cwd=${opts.cwd}`);
-        // P1-22: register with the process-level exit dispatcher while the process
+        // register with the process-level exit dispatcher while the process
         // is alive — bridge exit/restart (SIGINT/SIGTERM/exit) then kills the whole
         // group via cleanupOnExit instead of orphaning `!` processes.
         registerExitCleanup(this);
@@ -85,7 +85,7 @@ export class BashProcessRunner {
         // for logging, one for queueing) -- both fired on the same chunk.
         const stdoutQueue = [];
         const stderrQueue = [];
-        // 背压状态（P1-4 层④）：队列超高水位 → pause 对应流；drain 到低水位 → resume。
+        // 背压状态（层④）：队列超高水位 → pause 对应流；drain 到低水位 → resume。
         let stdoutPaused = false;
         let stderrPaused = false;
         const maybePauseStdout = () => {
@@ -209,7 +209,7 @@ export class BashProcessRunner {
         }
     }
     /**
-     * P1-22: called by the process-level exit dispatcher on SIGINT/SIGTERM/exit.
+     * called by the process-level exit dispatcher on SIGINT/SIGTERM/exit.
      * Kills the whole process group (leader + background children) via
      * Terminator, matching agent-runner cleanupOnExit semantics.
      */

package/dist/runner/claude/runner.js

@@ -127,7 +127,7 @@ export class ClaudeRunner {
                 await this.session.respondPermission(requestId, { behavior: 'deny' });
                 return;
             case 'cancel': {
-                // 审批超时/取消：deny 送达后中断 turn（对齐方案验收「审批超时未响应，
+                // 审批超时/取消：deny 送达后中断 turn（对齐「审批超时未响应，
                 // 已自动取消」终态；仅 deny 会让 claude 继续回合导致卡片 done）。
                 await this.session.respondPermission(requestId, {
                     behavior: 'deny',

package/dist/runner/claude/session.d.ts

@@ -53,7 +53,7 @@ export interface PermissionResult {
 }
 /**
  * ClaudeSession extends SpawningRunner 复用其 spawn/pid 文件/killOrphan/
- * Terminator/SpawnHeartbeat/退出分发器机制（P1-1/P1-10/P1-11 契约保持），
+ * Terminator/SpawnHeartbeat/退出分发器机制（契约保持），
  * 但 run() 覆盖为「长驻 + 按 turn 消费」：进程跨 turn 存活，turn 结束以
  * stream-json result 事件（非 compact）为界，而不是进程退出。
  */
@@ -138,7 +138,7 @@ export declare class ClaudeSession extends SpawningRunner {
     private startStreamReader;
     /**
      * 消费事件队列直到本 turn 的 result 事件（非 compact/compaction）。
-     * 消费者提前关闭生成器（bridge 循环体抛错）→ 杀进程防孤儿（P1-11 语义）。
+     * 消费者提前关闭生成器（bridge 循环体抛错）→ 杀进程防孤儿（语义）。
      *
      * result = turn 终态（2026-08-16 真实 claude 实测：长驻模式下 result 之后
      * 不再有 stdout 事件，后台任务完成是静默的；旧 -p 流程「等进程退出再收尾」

package/dist/runner/claude/session.js

@@ -43,7 +43,7 @@ const DEFAULT_IDLE_TTL_MS = 30 * 60 * 1000;
 const COMPACTION_RESULT_SUBTYPES = new Set(['compact', 'compaction']);
 /**
  * ClaudeSession extends SpawningRunner 复用其 spawn/pid 文件/killOrphan/
- * Terminator/SpawnHeartbeat/退出分发器机制（P1-1/P1-10/P1-11 契约保持），
+ * Terminator/SpawnHeartbeat/退出分发器机制（契约保持），
  * 但 run() 覆盖为「长驻 + 按 turn 消费」：进程跨 turn 存活，turn 结束以
  * stream-json result 事件（非 compact）为界，而不是进程退出。
  */
@@ -127,7 +127,7 @@ export class ClaudeSession extends SpawningRunner {
             // 或 --resume 目标会话）。比较进程当前 session（init 报告值）而非 spawn
             // 请求值：bridge 会把 init 的 session_id 写回 SessionStore，第二条消息
             // 带着它来；若拿 spawn 请求值（''）比较，每条消息都会误判切换、杀进程
-            // 重启，长驻设计失效（2026-08-16 review P0）。
+            // 重启，长驻设计失效（2026-08-16）。
             if (this.isRunning && this.sessionId !== (opts.sessionId ?? '')) {
                 getLogger().info(`[${this.logTag}] session mismatch: process=${this.sessionId || '(fresh)'} ` +
                     `requested=${opts.sessionId ?? '(fresh)'}, recycling process`);
@@ -174,7 +174,7 @@ export class ClaudeSession extends SpawningRunner {
             getLogger().warn(`[${this.logTag}] respondPermission skipped: process not running requestId=${requestId}`);
             return;
         }
-        // review P2-2：requestId 不在待审批表（已 control_cancel / 进程回收）时
+        // requestId 不在待审批表（已 control_cancel / 进程回收）时
         // 丢弃响应，不能以空 updatedInput allow（claude 会拿空输入执行工具）。
         if (!this.pendingToolInputs.has(requestId)) {
             getLogger().warn(`[${this.logTag}] respondPermission dropped: unknown requestId=${requestId}`);
@@ -204,7 +204,7 @@ export class ClaudeSession extends SpawningRunner {
     async respondAskUserQuestion(requestId, answers) {
         if (!this.isRunning)
             return;
-        // review P2-2：未知 requestId 时不能回写缺原始 questions 的 answers
+        // 未知 requestId 时不能回写缺原始 questions 的 answers
         // （官方要求 updatedInput 必须包含原始 questions）。
         if (!this.pendingToolInputs.has(requestId)) {
             getLogger().warn(`[${this.logTag}] respondAskUserQuestion dropped: unknown requestId=${requestId}`);
@@ -285,7 +285,7 @@ export class ClaudeSession extends SpawningRunner {
      */
     async startProcess(opts) {
         if (this.isRunning) {
-            // review P3-4：复用进程（跨 turn 长驻）时清掉上一轮的空闲回收 timer——
+            // 复用进程（跨 turn 长驻）时清掉上一轮的空闲回收 timer——
             // 否则长 turn 中它会空转触发一次（回调因 turnActive 空转返回，无害但
             // 多余）；新一轮结束后的 armIdleTimer 会重新武装。
             this.clearIdleTimer();
@@ -381,7 +381,7 @@ export class ClaudeSession extends SpawningRunner {
     // =========================================================================
     /**
      * 消费事件队列直到本 turn 的 result 事件（非 compact/compaction）。
-     * 消费者提前关闭生成器（bridge 循环体抛错）→ 杀进程防孤儿（P1-11 语义）。
+     * 消费者提前关闭生成器（bridge 循环体抛错）→ 杀进程防孤儿（语义）。
      *
      * result = turn 终态（2026-08-16 真实 claude 实测：长驻模式下 result 之后
      * 不再有 stdout 事件，后台任务完成是静默的；旧 -p 流程「等进程退出再收尾」
@@ -554,7 +554,7 @@ export class ClaudeSession extends SpawningRunner {
     async translateEvent(raw) {
         const event = raw;
         const type = event.type;
-        // review P3-3：--resume 会先重放上一轮历史事件（旧 result 之外还可能有
+        // --resume 会先重放上一轮历史事件（旧 result 之外还可能有
         // 旧 assistant/user 内容）。init 之前除 init 本身外一律丢弃，避免历史
         // 内容混进当前卡片（result 分支的 sawInit 守卫升级为全类型守卫）。
         if (type !== 'system' && !this.sawInit)
@@ -678,7 +678,7 @@ export class ClaudeSession extends SpawningRunner {
         const request = (raw.request ?? {});
         const subtype = request.subtype;
         if (subtype !== 'can_use_tool') {
-            // review P3-1：未知 subtype 不能静默丢弃——claude 在等 control_response，
+            // 未知 subtype 不能静默丢弃——claude 在等 control_response，
             // 不回应 turn 会永久挂起（无审批卡、无超时）。deny 兜底让 claude 继续。
             getLogger().warn(`[${this.logTag}] unknown control request subtype=${String(subtype)} requestId=${requestId}`);
             void this.writeControlResponse(requestId, {
@@ -692,7 +692,7 @@ export class ClaudeSession extends SpawningRunner {
         const toolName = String(request.tool_name ?? '');
         const input = (request.input ?? {});
         this.pendingToolInputs.set(requestId, input);
-        // review P1：允许所有只放行工具权限；AskUserQuestion 不能被空 answers
+        // 允许所有只放行工具权限；AskUserQuestion 不能被空 answers
         // 自动放行（claude 会把空答案当作已作答），必须继续上抛卡片让用户回答。
         if (this.autoApprove && toolName !== 'AskUserQuestion') {
             getLogger().info(`[${this.logTag}] auto-approving requestId=${requestId} tool=${toolName}`);
@@ -702,7 +702,7 @@ export class ClaudeSession extends SpawningRunner {
             }).catch((err) => {
                 getLogger().warn(`[${this.logTag}] auto-approve write failed requestId=${requestId}: ${err.message}`);
             });
-            // review P2-1：自动放行不经过协调器/respondPermission，条目不会随
+            // 自动放行不经过协调器/respondPermission，条目不会随
             // 响应被删除——立即释放，否则长会话（允许所有）下 Map 无界增长。
             this.pendingToolInputs.delete(requestId);
             return [];
@@ -717,7 +717,7 @@ export class ClaudeSession extends SpawningRunner {
                     behavior: 'deny',
                     message: '无法解析 AskUserQuestion 选项',
                 }).catch(() => { });
-                // review P2-1：解析失败 deny 后同样释放条目（不经过 respondPermission）。
+                // 解析失败 deny 后同样释放条目（不经过 respondPermission）。
                 this.pendingToolInputs.delete(requestId);
                 return [];
             }
@@ -760,7 +760,7 @@ export class ClaudeSession extends SpawningRunner {
             ];
         }
         // 非命令工具的兜底防御：input 无 command 字段时 JSON 序列化，但空对象
-        // 序列化成 `{}` 对用户无意义——内容为空时回退展示工具名（review P3-5）。
+        // 序列化成 `{}` 对用户无意义——内容为空时回退展示工具名。
         const rawCommand = typeof input.command === 'string' ? input.command : JSON.stringify(input);
         const command = rawCommand && rawCommand !== '{}' && rawCommand !== 'null'
             ? rawCommand
@@ -817,7 +817,7 @@ function parseUserQuestions(input) {
         const question = typeof q.question === 'string' ? q.question : '';
         if (!question)
             continue;
-        // review P3-2：answers 字典以问题文本为 key，重复文本会互相覆盖——
+        // answers 字典以问题文本为 key，重复文本会互相覆盖——
         // 视为解析失败（调用方 deny 兜底），不把坏问题上抛给用户。
         if (seenQuestions.has(question))
             return [];
@@ -839,7 +839,7 @@ function parseUserQuestions(input) {
                 });
             }
         }
-        // review P3-2：零选项问题无法作答（多选连自定义答案都没有），视为
+        // 零选项问题无法作答（多选连自定义答案都没有），视为
         // 解析失败（调用方 deny 兜底），不把坏问题上抛给用户。
         if (options.length === 0)
             return [];

package/dist/runner/codex/app-server/runner.js

@@ -136,7 +136,7 @@ export class CodexAppServerRunner extends ConnectionBasedRunner {
             },
         };
         this.connectionManager = new ConnectionManager(managerOpts);
-        // 协议停止通道（design §3.3）：codex 的 cancel 是 `turn/interrupt` 请求，已由
+        // 协议停止通道：codex 的 cancel 是 `turn/interrupt` 请求，已由
         // cancelCurrentTurn 实现；登记后 win32 优雅停止才有通道可用（否则一路树杀）。
         this.connectionManager.stopper = ({ client }) => this.buildCooperativeStop(client);
     }
@@ -235,7 +235,7 @@ export class CodexAppServerRunner extends ConnectionBasedRunner {
         else if (pending.kind === 'permissions') {
             // 权限审批的响应没有 decision 字段（真实协议只回 granted profile +
             // scope）：decline/cancel 必须返回空授权（拒绝全部），否则会把用户已
-            // 勾选的条目当作授予返回（2026-08-12 review 发现：勾选后点「拒绝」实
+            // 勾选的条目当作授予返回（2026-08-12 ：勾选后点「拒绝」实
             // 际授予了所选权限）。accept/acceptForSession 才带用户勾选的条目。
             const denied = action === 'decline' || action === 'cancel';
             client.respond(requestId, {
@@ -358,7 +358,7 @@ export class CodexAppServerRunner extends ConnectionBasedRunner {
         }
         else {
             const threadResult = await client.request('thread/start', threadParams);
-            // 会话键假设（review P2-4）：主线程 thread.id === session_meta.session_id，
+            // 会话键假设：主线程 thread.id === session_meta.session_id，
             // 故 thread.id 可同时用作协议 threadId 与 store/session reader 的 session
             // 键（bridge 用 turn_started 通知的 threadId 写回，/resume、Compact 按此
             // 键定位 JSONL）。forked/subagent 线程二者会分叉（openai/codex#29327），

package/dist/runner/codex/app-server/translator.d.ts

@@ -26,7 +26,7 @@ export declare class CodexAppServerTranslator {
     /** Full command output per item id (item-scoped snapshot). */
     private toolOutputByItem;
     /**
-     * Tool identity per item id (信息保真 C2): recorded at item/started, spread
+     * Tool identity per item id (信息保真): recorded at item/started, spread
      * into every toolOutput turn_diff, released at item/completed.
      */
     private toolItemMeta;
@@ -85,7 +85,7 @@ export declare class CodexAppServerTranslator {
     private handlePlanUpdated;
     private handleTokenUsageUpdated;
     /**
-     * warning 通知 → notice 事件（信息保真 C2：运行期告警不再静默丢弃）。
+     * warning 通知 → notice 事件（信息保真 运行期告警不再静默丢弃）。
      */
     private handleWarning;
     /**

package/dist/runner/codex/app-server/translator.js

@@ -27,7 +27,7 @@ export class CodexAppServerTranslator {
     /** Full command output per item id (item-scoped snapshot). */
     toolOutputByItem = new Map();
     /**
-     * Tool identity per item id (信息保真 C2): recorded at item/started, spread
+     * Tool identity per item id (信息保真): recorded at item/started, spread
      * into every toolOutput turn_diff, released at item/completed.
      */
     toolItemMeta = new Map();
@@ -326,7 +326,7 @@ export class CodexAppServerTranslator {
                 return [];
             }
             this.toolOutputByItem.set(item.id, authoritative);
-            // 信息保真 C2：完成事件同样携带身份，并在发出后释放 meta。
+            // 信息保真 完成事件同样携带身份，并在发出后释放 meta。
             const meta = this.toolItemMeta.get(item.id);
             this.toolItemMeta.delete(item.id);
             return [
@@ -383,7 +383,7 @@ export class CodexAppServerTranslator {
                 ];
             }
         }
-        // 信息保真 C2：webSearch/mcpToolCall/dynamicToolCall 等无专属 completed 分支的
+        // 信息保真 webSearch/mcpToolCall/dynamicToolCall 等无专属 completed 分支的
         // 工具 item 也必须收尾——否则 run-state 侧工具块永挂 running（无 completedAt/终态），
         // toolItemMeta 泄漏到下个 turn 的 clear() 才被释放。
         if (this.startedToolItems.has(item.id)) {
@@ -466,7 +466,7 @@ export class CodexAppServerTranslator {
         return [];
     }
     /**
-     * warning 通知 → notice 事件（信息保真 C2：运行期告警不再静默丢弃）。
+     * warning 通知 → notice 事件（信息保真 运行期告警不再静默丢弃）。
      */
     handleWarning(params) {
         return [
@@ -653,7 +653,7 @@ export class CodexAppServerTranslator {
             // item/started 锚定工具块位置（真实时序）：命令开始时即创建工具块，
             // 而不是等到首个输出 delta——否则后续 reasoning item 会插到 command 之前。
             this.startedToolItems.add(item.id);
-            // 信息保真 C2：记录工具身份，随 turn_diff 透传（run-state 首见时写入）。
+            // 信息保真 记录工具身份，随 turn_diff 透传（run-state 首见时写入）。
             this.toolItemMeta.set(item.id, {
                 toolName: 'Bash',
                 toolInput: { command: item.command, ...(item.cwd ? { cwd: item.cwd } : {}) },