@v587d/capital-generation 2.8.3 → 2.9.1

package/lib/chart/events.d.ts

@@ -1,17 +1,11 @@
 import type { SessionLike } from '../data-collector/store.js';
-/**
- * 登记本轮交付物用的官方事件名。
- *
- * 必须留在 `KNOWN_SESSION_EVENT_TYPES` 内——它是 `dsh-tool-present` 追加的同一类型，
- * 因此在**任何** harness 版本上都能被读回。改这里等于改会话日志契约，
- * `test/chart-turn-events.test.mjs` 有一条断言把它钉在 first-party 词汇表上。
- */
+/** Must stay in `KNOWN_SESSION_EVENT_TYPES`; test/chart-turn-events.test.mjs pins it. */
 export declare const CHART_DELIVERABLE_EVENT = "deliverables/presented";
-/** `callId` 前缀：交付事件里携带的图表句柄（官方契约只要求非空字符串）。 */
+/** `callId` only needs to be a non-empty string; carries the chart handle for log tracing. */
 export declare const CHART_CALL_ID_PREFIX = "capital-chart:";
-/** 同一 (session, turn) 的事件上限：防模型循环，超出只告警。 */
+/** Per (session, turn) cap: stops model loops; overflow warns only. */
 export declare const MAX_CHARTS_PER_TURN = 8;
-/** 向上找根会话的最大跳数（main → data_junior → specialist 只有一跳，留余量）。 */
+/** Root lookup cap (main → data_junior → specialist is one hop, plus headroom). */
 export declare const MAX_OWNER_HOPS = 4;
 interface AppendableSession extends SessionLike {
     append(type: string, data: unknown): unknown;
@@ -19,102 +13,51 @@ interface AppendableSession extends SessionLike {
 interface SessionsService {
     get(id: string): unknown;
 }
-/** 宿主 ctx 里本模块用到的部分；focused 结构类型便于单测注入假实现。 */
+/** Subset of host ctx used here; structural so tests can inject fakes. */
 export interface ChartEventContext {
     get(name: string): unknown;
-    /** 监听会话事件（`turn/start`，仅作**兜底**冲刷）。必须注册在未打 scope 标签的 root context 上。 */
+    /** Fallback flush listener; must be registered on the unscoped root context. */
     on?(event: string, listener: (...args: unknown[]) => void): unknown;
-    /**
-     * 监听 `agent/turn-stopping`：**首选的冲刷时机**。
-     *
-     * 为什么必须是它而不是 `turn/start`：一轮是否"最终"在事件发生的那一刻不可知——子 Agent 的
-     * 结算随时会再触发新一轮。实测（2026-09-20 真机 session `38bad3f9`）：图表在 turn 4 与 5 之间
-     * 寄存，旧规则在下一次 `turn/start` 立刻冲刷，于是交付行落进了**空的过程轮** turn 5，而主 Agent
-     * 写下总结答复的是 turn 6——卡片出现在中间步骤。`agent/turn-stopping` 是官方"该轮即将关闭"的
-     * 钩子（`@mode serial`，轮仍打开、可安全 append），在它上面冲刷，交付行就落进**消费这份图的那一轮**。
-     *
-     * 必须注册在未打 scope 标签的 root context 上：`dsh-scope` 的准入规则会让 standing-scope 的
-     * 监听器收不到子 Agent 的事件，而我们要的正是 owner 自己那轮关闭的事实。
-     */
+    /** Preferred flush hook: open-but-closing turn, on the unscoped root ctx (scoped listeners miss
+     * child events). A missing disposer must keep the turn/start fallback active. */
     onTurnStopping?(listener: (...args: unknown[]) => void): unknown;
     effect?(callback: () => unknown, label?: string): unknown;
-    /** Root context（未打标签）；拿不到时退回自身（宿主平面行即未打标签）。 */
+    /** Unscoped root context; falls back to self when absent. */
     readonly root?: ChartEventContext;
     logger?: {
         warn(message: string): void;
     };
 }
 export interface ChartTurnEventInput {
-    /** 出图时 chart_ref 的 owner scope（与 ChartArtifactRegistry 同一套语义）。 */
+    /** chart_ref owner scope (same semantics as ChartArtifactRegistry). */
     ownerSessionId: string;
     chart_id: string;
     title: string;
-    /** 工作区相对的 chart.html 路径（官方 preview 按 session.cwd 解析它）。 */
+    /** Workspace-relative chart.html path; the official preview resolves it against session.cwd. */
     html_path: string;
 }
 export interface ChartEventPublisher {
-    /**
-     * 记录一张图。
-     * @returns 是否已受理：立即写入、或已寄存等下一个回合都算受理。
-     */
     publish(input: ChartTurnEventInput): boolean;
-    /** 诊断：还没拿到回合、寄存中的图表数。 */
+    /** Diagnostics: queued charts not yet written. */
     pendingCount?(ownerSessionId?: string): number;
-    /**
-     * 诊断：最近一次 publish 的逐步结论（给回执/落盘用）。
-     *
-     * 为什么需要它：交付行"静默不出现"是本项目最难查的故障，而宿主终端并不总能拿到
-     * （cordis logger 只进内存；stderr 也可能落在用户看不到的地方）。把结论带回
-     * `render_chart` 的回执 / 落盘产物，就能**从磁盘**定位，不必依赖终端。
-     */
+    /** Diagnostics: last publish trace, surfaced in receipts / disk so failures are visible without a terminal. */
     lastTrace?(): string;
 }
-/** 只读：最近一次 publish 轨迹。 */
 export declare function chartEventPublishTrace(): string;
-/**
- * 交付通道的**诊断开关**：`CAPITAL_CHART_TRACE=1` 时才输出进度日志与落盘 trace。
- *
- * 默认关闭——对外发布不该往用户终端刷进度、也不该往 workspace 写调试文件。
- * 排查"图表/交付行不出现"时打开它（见 `deliverable-trace.txt` 与 docs/dev/chart-delivery-events.md §6.3 的说明）。
- */
+/** Diagnostic switch; off by default to keep terminals and workspaces clean. */
 export declare function chartTraceEnabled(): boolean;
-/**
- * 从 owner scope 出发向上走到根会话：用户看的是根会话的对话流，卡片必须挂在它上面。
- * 找不到（会话已回收）时返回 undefined，调用方静默跳过。
- */
+/** Walk up to the root session — the user watches the root conversation. Missing session → undefined. */
 export declare function resolveOwnerSession(sessions: SessionsService, ownerSessionId: string, maxHops?: number): AppendableSession | undefined;
-/**
- * 官方 `deliverables/presented` 载荷。
- *
- * 形状与 `dsh-tool-present` 逐字段对齐（那边是 `{ turn, callId, files }`，
- * 客户端 `isPresentedData()` 要求 `turn` 是 >=1 的安全整数、`callId` 非空字符串、
- * `files` 是数组）。`files[].path` 必须是**工作区相对**路径：官方打开动作会拿它去
- * `workspaceFiles.stat({ sessionId, workspaceRoot: session.cwd })` 解析，绝对路径过不了
- * 「Presented file has no verified Host path」这一关。
- *
- * `callId` 只是官方契约里的一个非空字符串句柄，没有配对约束（`present` 那边用来关联
- * tool/result），这里借它携带 `chart_id`，便于在日志里把一条交付回溯到具体图表。
- */
+/** Matches `dsh-tool-present` ({ turn, callId, files }); files[].path must be workspace-relative
+ * because the official open action resolves it against session.cwd. */
 export declare function buildChartEventPayload(input: ChartTurnEventInput, turn: number): Record<string, unknown>;
-/**
- * 进程内待登记条目的总量上限（安全阀）。
- *
- * 正常流程下条目会在 owner 那一轮关闭时被冲刷清空；但如果冲刷时机始终没接上
- * （上游事件名消失、监听注册失败且 turn/start 也没来），模块级 Map 会一直攒着。
- * 这是纯内存元数据（只有 chart_id / 标题 / 相对路径），上限只为防无界增长，
- * 与 `MAX_CHARTS_PER_TURN` 的"防模型循环"是两件事。
- */
+/** Safety valve if flushing never fires; metadata only, bounded against unbounded growth. */
 export declare const MAX_PENDING_CHARTS = 64;
-/**
- * 只给测试用：清空待登记队列。
- *
- * `pending` 是模块级的（必须跨发布器实例存活，见下方说明），因此进程内所有测试
- * 共享它。测试之间要隔离，就在用例开始时调用一次。
- */
+/** Test-only: clear the shared queue between cases. */
 export declare function resetChartEventPending(): void;
 export declare function createChartEventPublisher(ctx: ChartEventContext): ChartEventPublisher | undefined;
-/** 只给测试用：丢弃单例缓存（配合 resetChartEventPending 做用例隔离）。 */
+/** Test-only: drop the singleton cache. */
 export declare function resetChartEventPublisher(): void;
-/** 出图时的 owner scope：与 chart_ref 同源（specialist 出图时正好是主会话）。 */
+/** Owner scope at render time; same source as chart_ref (specialist renders land on the main session). */
 export declare function chartEventOwnerSessionId(session: SessionLike, sourceSession?: SessionLike): string;
 export {};

package/lib/chart/events.js

@@ -1,77 +1,23 @@
 /**
- * 图表 → 对话流的宿主侧事件通道（**first-party 口径**）。
- *
- * 问题：图表由 `visualization_specialist`（主 Agent 的**孙** Agent）生成，它的 tool call
- * 落在自己的会话里；用户在客户端看的是主会话，子会话的事件不会流过来。
- *
- * 做法：`render_chart` 成功后，宿主往**用户正在看的那条会话**追加官方
- * `deliverables/presented` 事件（`present` 工具用的同一条通道），把
- * `capital-analysis/charts/<chart_id>/chart.html` 登记为本轮交付物。用户在收尾的
- * 「本轮文件改动 / 交付」行点开该文件，右侧即用官方 document preview 的
- * script-enabled iframe 渲染自包含图表。
- *
- * ⚠️ 为什么**绝不能**再发明自己的事件类型（2026-09-18 事故，实测根因）：
- * 会话日志的事件词汇表是**闭集**——`@deepseek-ai/dsh-session` 的
- * `KNOWN_SESSION_EVENT_TYPES` 由 harness 仓库自己的 `SessionEventMap` 生成，
- * 注释明写 "downstream (out-of-repo) plugin events are outside this list by
- * construction"。读取侧 `validateStoredEvents()` 是 fail-closed 的：
- *
- *   `KNOWN_SESSION_EVENT_TYPES.has(event.type) || event.ignorable === true`
- *
- * 否则抛 `SessionFormatUnsupportedError` 并拒绝解释**整份日志**。而 `Session.append`
- * 的 options 只转发 `sourceEventSeqs` / `surfaceOp`——**调用方无法设置 `ignorable`**
- * （实测 0.1.5-rc.2 与 0.1.6-alpha.2 都没有该选项）。于是自定义事件是"写时静默通过、
- * 冷加载时整份会话打不开"：本仓曾发 `capital/chart-rendered`，导致 6 份会话在重启后
- * 全部 `failed to observe session`。只有 first-party 事件能持久化。
- *
- * ⚠️ 回合归属（实测教训 2026-09-17）：交付行是**按回合**渲染的，只会出现在它所属回合的
- * 收尾位置。而主 Agent 在等子 Agent 时会**先结束自己的回合**，于是出图往往发生在两个回合
- * 之间——此时 `turnBoundary.lastTurn` 指向那个**已经结束**的回合，照抄它会把交付登记到
- * 上一轮。因此：
- *  - 有回合打开（`openTurnStartSeq` 是数字）→ 立即写入该回合；
- *  - 没有回合打开 → 先寄存，等 owner 的**下一个 `turn/start`** 再写入（那正是会消费这份
- *    子 Agent 结果、写下最终答复的回合）。
- * 寄存的冲刷必须延到微任务：`session/event` 观察者在 `Session.append` 的 appending 窗口内同步执行，
- * 在那里再次 append 会被 "session append cannot reenter" 拒绝。
- *
- * 为什么这不"污染 transcripts"：
- *  - `deliverables/presented` 不在 surface 事件表里，`deriveEventMessage()` 返回 null，
- *    因此它**永不进入** `deriveMessages()`（模型看到的消息历史）；
- *  - payload 只有 `turn` / `callId`（`capital-chart:<chart_id>` 句柄）/ `files[]`
- *    （工作区相对 `html_path` + 标题），没有 rows、series、HTML、绝对路径。
- *
- * 容错：`sessions` / `sessionProjections` 任一不可用、或 append 抛错，都只告警并跳过——
- * 出图本身绝不因此失败（文件已落盘、回执照样给 html_path）。
+ * Chart → conversation deliverable channel (first-party events only).
+ * Event types are a closed set: anything outside KNOWN_SESSION_EVENT_TYPES without `ignorable`
+ * makes the whole log unreadable on cold load, and append() cannot set it.
+ * Only `deliverables/presented` is safe; attribution and the owner-keyed queue are the invariants.
  */
 import { chartSessionScopeId } from './artifact-ref.js';
-/**
- * 登记本轮交付物用的官方事件名。
- *
- * 必须留在 `KNOWN_SESSION_EVENT_TYPES` 内——它是 `dsh-tool-present` 追加的同一类型，
- * 因此在**任何** harness 版本上都能被读回。改这里等于改会话日志契约，
- * `test/chart-turn-events.test.mjs` 有一条断言把它钉在 first-party 词汇表上。
- */
+/** Must stay in `KNOWN_SESSION_EVENT_TYPES`; test/chart-turn-events.test.mjs pins it. */
 export const CHART_DELIVERABLE_EVENT = 'deliverables/presented';
-/** `callId` 前缀：交付事件里携带的图表句柄（官方契约只要求非空字符串）。 */
+/** `callId` only needs to be a non-empty string; carries the chart handle for log tracing. */
 export const CHART_CALL_ID_PREFIX = 'capital-chart:';
-/** 同一 (session, turn) 的事件上限：防模型循环，超出只告警。 */
+/** Per (session, turn) cap: stops model loops; overflow warns only. */
 export const MAX_CHARTS_PER_TURN = 8;
-/** 向上找根会话的最大跳数（main → data_junior → specialist 只有一跳，留余量）。 */
+/** Root lookup cap (main → data_junior → specialist is one hop, plus headroom). */
 export const MAX_OWNER_HOPS = 4;
-/**
- * 最近一次 publish 的逐步轨迹（模块级：发布器每次出图都新建，轨迹要跨实例可读）。
- */
 let lastPublishTrace = '';
-/** 只读：最近一次 publish 轨迹。 */
 export function chartEventPublishTrace() {
     return lastPublishTrace;
 }
-/**
- * 交付通道的**诊断开关**：`CAPITAL_CHART_TRACE=1` 时才输出进度日志与落盘 trace。
- *
- * 默认关闭——对外发布不该往用户终端刷进度、也不该往 workspace 写调试文件。
- * 排查"图表/交付行不出现"时打开它（见 `deliverable-trace.txt` 与 docs/dev/chart-delivery-events.md §6.3 的说明）。
- */
+/** Diagnostic switch; off by default to keep terminals and workspaces clean. */
 export function chartTraceEnabled() {
     try {
         const env = globalThis.process?.env;
@@ -87,14 +33,14 @@ function isAppendableSession(value) {
         && typeof value.append === 'function'
         && typeof value.id === 'string';
 }
+/** `parentSession` alone is seed lineage (a user fork); only `origin: 'subagent'` is delegation. */
 function parentSessionOf(session) {
+    if (session.header?.origin !== 'subagent')
+        return undefined;
     const parent = session.header?.parentSession;
     return typeof parent === 'string' && parent.length > 0 ? parent : undefined;
 }
-/**
- * 从 owner scope 出发向上走到根会话：用户看的是根会话的对话流，卡片必须挂在它上面。
- * 找不到（会话已回收）时返回 undefined，调用方静默跳过。
- */
+/** Walk up to the root session — the user watches the root conversation. Missing session → undefined. */
 export function resolveOwnerSession(sessions, ownerSessionId, maxHops = MAX_OWNER_HOPS) {
     let current;
     try {
@@ -123,18 +69,8 @@ export function resolveOwnerSession(sessions, ownerSessionId, maxHops = MAX_OWNE
     }
     return current;
 }
-/**
- * 官方 `deliverables/presented` 载荷。
- *
- * 形状与 `dsh-tool-present` 逐字段对齐（那边是 `{ turn, callId, files }`，
- * 客户端 `isPresentedData()` 要求 `turn` 是 >=1 的安全整数、`callId` 非空字符串、
- * `files` 是数组）。`files[].path` 必须是**工作区相对**路径：官方打开动作会拿它去
- * `workspaceFiles.stat({ sessionId, workspaceRoot: session.cwd })` 解析，绝对路径过不了
- * 「Presented file has no verified Host path」这一关。
- *
- * `callId` 只是官方契约里的一个非空字符串句柄，没有配对约束（`present` 那边用来关联
- * tool/result），这里借它携带 `chart_id`，便于在日志里把一条交付回溯到具体图表。
- */
+/** Matches `dsh-tool-present` ({ turn, callId, files }); files[].path must be workspace-relative
+ * because the official open action resolves it against session.cwd. */
 export function buildChartEventPayload(input, turn) {
     return {
         turn,
@@ -147,58 +83,17 @@ export function buildChartEventPayload(input, turn) {
         ],
     };
 }
-/**
- * 待登记队列（**进程级**，不能放进发布器实例）。
- *
- * ⚠️ 2026-09-20 真机事故的根因：`createChartEventPublisher()` 是在**每次 `render_chart`
- * 时**惰性调用的（见 `src/index.ts` 的 `chartEvents: () => createChartEventPublisher(...)`），
- * 所以每个实例都拿到一份**自己的** `pending`。于是：
- *   1. 出图时回合是关的 → 图被寄存进**实例 A** 的 pending；
- *   2. 稍后 owner 那一轮关闭 → 冲刷回调跑在**实例 B**（甚至没有实例）上；
- *   3. B 的 pending 是空的 → 什么都没写 → 图**永久丢失**，且静默无报错。
- * 旧代码之所以看不出这个问题，是因为"回合打开时立即 append"这条路径占多数，
- * 只有"回合之间出图"（本项目的主 Agent 等子 Agent 时必然发生）才走寄存。
- *
- * 因此 pending 必须与进程内的服务实例同生命周期：模块级，并在注册冲刷监听时才清理。
- */
+/** Process-level, not per publisher (which is rebuilt per render): keyed by owner (root) session
+ * id — the id flush events carry — and cleared only by flushing or an explicit reset. */
 const pending = new Map();
-/**
- * 进程内待登记条目的总量上限（安全阀）。
- *
- * 正常流程下条目会在 owner 那一轮关闭时被冲刷清空；但如果冲刷时机始终没接上
- * （上游事件名消失、监听注册失败且 turn/start 也没来），模块级 Map 会一直攒着。
- * 这是纯内存元数据（只有 chart_id / 标题 / 相对路径），上限只为防无界增长，
- * 与 `MAX_CHARTS_PER_TURN` 的"防模型循环"是两件事。
- */
+/** Safety valve if flushing never fires; metadata only, bounded against unbounded growth. */
 export const MAX_PENDING_CHARTS = 64;
-/**
- * 只给测试用：清空待登记队列。
- *
- * `pending` 是模块级的（必须跨发布器实例存活，见下方说明），因此进程内所有测试
- * 共享它。测试之间要隔离，就在用例开始时调用一次。
- */
+/** Test-only: clear the shared queue between cases. */
 export function resetChartEventPending() {
     pending.clear();
 }
-/**
- * 惰性构造发布器：`sessions` / `sessionProjections` 缺一不可（都是宿主平面服务，
- * 在 preset scope 里正常可解析；缺失表示宿主组合不完整，此时静默降级）。
- */
-/**
- * 进程级单例发布器。
- *
- * ⚠️ 2026-09-20 真机事故的**真根因**：`src/index.ts` 的 `chartEvents: () => createChartEventPublisher(...)`
- * 是**每次 `render_chart` 都调用一次**的。若每次都新建发布器：
- *   1. 实例 A 出图时把图寄存进自己的队列，并注册了**绑定在 A 上**的冲刷监听；
- *   2. 下一次出图再建实例 B（又注册一套监听）；
- *   3. 冲刷回调里 `flush` 闭包引用的是某个实例的队列，而实例不断增多，
- *      寄存与冲刷落在不同实例上 —— 于是"专家确实出图，但主会话一条交付事件都没有"。
- *
- * 所以发布器必须**进程内唯一**：队列、监听、perTurn 计数都只有一份。
- * 缓存键用 `ctx.root ?? ctx`（cordis 的 root context 是稳定对象；`index.ts` 传进来的
- * 是个每次新建的 spread 字面量，不能用它做身份判断）。构造失败不缓存——宿主服务
- * 可能稍后才就绪，下次出图要能重新解析（保留原有的惰性语义）。
- */
+/** Process-wide singleton (queue, listeners, per-turn counts) keyed by `ctx.root ?? ctx`;
+ * never cache a failed build so later-mounting host services can be picked up. */
 let cachedPublisher;
 export function createChartEventPublisher(ctx) {
     const ref = ctx.root ?? ctx;
@@ -209,7 +104,7 @@ export function createChartEventPublisher(ctx) {
         cachedPublisher = { ref, publisher };
     return publisher;
 }
-/** 只给测试用：丢弃单例缓存（配合 resetChartEventPending 做用例隔离）。 */
+/** Test-only: drop the singleton cache. */
 export function resetChartEventPublisher() {
     cachedPublisher = undefined;
 }
@@ -222,23 +117,15 @@ function buildChartEventPublisher(ctx) {
         return undefined;
     const perTurn = new Map();
     let warned = false;
-    /**
-     * 输出一条诊断。
-     *
-     * ⚠️ 实测（2026-09-20）：cordis 的 `ctx.logger` **只挂了一个内存 exporter**
-     * （`cordis/lib/index.js` 的 `LoggerService` 构造器），全仓没有任何地方注册 console
-     * exporter —— 也就是说 `ctx.logger.warn` 只进内存缓冲，**不会出现在 dsh 终端里**。
-     * 这正是"卡片不出现却零报错"、两轮排查都只能靠猜的原因。
-     * 因此这里**同时**写 `process.stderr`（宿主 stderr 一定能在终端看到）；
-     * logger 照发，保留结构化疗日志，将来有人接 exporter 就能收到。
-     */
+    /** `ctx.logger` only buffers in memory (no console exporter), so also write stderr; otherwise
+     * delivery failures are invisible. */
     const emit = (message) => {
         const line = `capital-generation: ${message}`;
         try {
             ctx.logger?.warn(line);
         }
         catch {
-            // logger 不可用不影响诊断输出。
+            // Logger unavailable; diagnostics still go to stderr below.
         }
         try {
             const stderr = globalThis.process?.stderr;
@@ -246,7 +133,7 @@ function buildChartEventPublisher(ctx) {
                 stderr.write(`${line}\n`);
         }
         catch {
-            // 没有 process（非 Node 载体）时静默跳过。
+            // No process (non-Node host).
         }
     };
     const warn = (message) => {
@@ -255,16 +142,7 @@ function buildChartEventPublisher(ctx) {
         warned = true;
         emit(message);
     };
-    /**
-     * 进度日志：**只在 `CAPITAL_CHART_TRACE=1` 时输出**。
-     *
-     * 寄存/登记这两处状态迁移是排查"交付行不出现"的关键线索，但对**普通用户是噪音**
-     * （每张图两条）。所以默认静默、按需打开：
-     *
-     *   CAPITAL_CHART_TRACE=1 dsh web
-     *
-     * 失败用的 `warn` 不受此开关影响——真出问题必须让人看见。
-     */
+    /** Progress log only under CAPITAL_CHART_TRACE=1; warnings bypass the switch. */
     const note = (message) => {
         if (!chartTraceEnabled())
             return;
@@ -278,7 +156,6 @@ function buildChartEventPublisher(ctx) {
             return undefined;
         }
     };
-    /** 真正写一条事件；返回是否写入。 */
     const append = (owner, turn, input) => {
         const key = `${owner.id}:${turn}`;
         const used = perTurn.get(key) ?? 0;
@@ -294,16 +171,10 @@ function buildChartEventPublisher(ctx) {
             return false;
         }
         perTurn.set(key, used + 1);
-        // 与"已寄存"成对的成功日志：排查交付行不出现时，一眼能看出是没写还是没渲染。
         note(`图表已登记为本轮交付（owner=${owner.id}，turn=${turn}，${input.chart_id}）`);
         return true;
     };
-    /**
-     * 把寄存的图表写进某一轮。
-     *
-     * 冲刷时机决定交付行的落点：首选 `agent/turn-stopping`（该轮即将关闭），
-     * 只有在拿不到这个钩子时才退回 `turn/start`。
-     */
+    /** Flush queued charts into a turn; the preferred hook is turn-stopping. */
     const flush = (ownerSessionId, turn) => {
         const queued = pending.get(ownerSessionId);
         if (queued === undefined || queued.length === 0)
@@ -317,14 +188,9 @@ function buildChartEventPublisher(ctx) {
         for (const item of queued)
             append(owner, turn, item);
     };
-    /**
-     * 首选时机是否可用。
-     *
-     * 关键：`turn-stopping` 缺席时**必须**退回 `turn/start`，否则寄存的图会永远不写（静默丢失）。
-     * 安装成功才置 true；effect 卸载时复位，避免失效后仍以为首选可用。
-     */
+    /** Only a real registration may flip this; otherwise turn/start fallback stays live. */
     let turnStoppingActive = false;
-    /** 不能在任何 appending 窗口内重入 append，统一延到微任务。 */
+    /** Never append inside the appending window; defer to a microtask. */
     const flushSoon = (ownerSessionId, turn) => {
         queueMicrotask(() => {
             try {
@@ -343,8 +209,7 @@ function buildChartEventPublisher(ctx) {
                 const event = args[1];
                 if (event?.type !== 'turn/start')
                     return;
-                // 首选钩子在场时，`turn/start` 不得抢跑：那一轮往往还是过程轮（2026-09-20 真机教训），
-                // 交付行会被落到空轮里。只有拿不到 `agent/turn-stopping` 时才用它兜底。
+                // turn/start must not race ahead while turn-stopping is active; it is only the fallback.
                 if (turnStoppingActive)
                     return;
                 const sessionId = typeof session?.id === 'string' ? session.id : undefined;
@@ -356,7 +221,7 @@ function buildChartEventPublisher(ctx) {
                 flushSoon(sessionId, turn);
             }
             catch {
-                // 事件观察者永不抛出。
+                // Observers never throw.
             }
         });
         if (typeof ctx.effect === 'function') {
@@ -379,21 +244,18 @@ function buildChartEventPublisher(ctx) {
                 flushSoon(sessionId, turn);
             }
             catch {
-                // 事件观察者永不抛出。
+                // Observers must not throw.
             }
         });
-        // ⚠️ 只有**真的拿到 disposer** 才算首选可用（2026-09-20 真机事故）：
-        // 早先这里无条件置 true，于是 `ctx.on('agent/turn-stopping')` 注册失败
-        // （适配器 catch 后返回 undefined）时，闸门仍被打开、`turn/start` 兜底被永久关掉，
-        // 图就**永远滞留 pending**——表现是交付卡片从头到尾不出现，且零报错。
-        // 注册失败必须让 `turnStoppingActive` 保持 false，由 `turn/start` 接上。
+        // Only a real disposer means the preferred hook is active; failed registration must leave
+        // the turn/start fallback on, or queued charts stay pending forever.
         if (typeof disposeTurnStopping === 'function')
             turnStoppingActive = true;
         else
             warn('交付行的首选冲刷时机不可用（agent/turn-stopping 注册失败），已退回 turn/start 兜底；落点可能偏早一轮');
         if (typeof ctx.effect === 'function') {
             ctx.effect(() => () => {
-                // 卸载即视为"首选不可用"，让 `turn/start` 兜底重新接上，避免图静默丢失。
+                // Teardown re-enables the fallback so queued charts are not lost.
                 turnStoppingActive = false;
                 if (typeof disposeTurnStopping === 'function')
                     disposeTurnStopping();
@@ -414,20 +276,15 @@ function buildChartEventPublisher(ctx) {
             const openSeq = boundary?.openTurnStartSeq;
             const lastTurn = boundary?.lastTurn;
             if (typeof openSeq !== 'number') {
-                // 回合之间出图（主 Agent 等子 Agent 时会先关轮）：寄存，等 owner 那一轮
-                // **即将关闭**（`agent/turn-stopping`）时再写——那才是消费这份图、写下答复的回合。
-                //
-                // ⚠️ 寄存队列必须按 **owner**（根会话）的 id 归档，不能按 `input.ownerSessionId`：
-                // 后者是发起出图的 scope（visualization_specialist，孙会话），而冲刷时机
-                // （`turn/start` / `agent/turn-stopping`）拿到的都是 owner 的 id。
-                // 两边键不一致时 `flush()` 永远查不到，图会**永久滞留在 pending**、静默不登记
-                // （2026-09-20 实测：3 个 specialist 会话 render_chart=2 而 deliverables=0）。
+                // Between turns (main agent closes its turn while waiting on children): queue until
+                // the owner's turn closes. Key by owner.id — flush events carry that id; a caller-scope
+                // key would never match and strands charts forever.
                 const queued = pending.get(owner.id) ?? [];
                 if (queued.length >= MAX_CHARTS_PER_TURN) {
                     warn(`图表对话流事件跳过：${owner.id} 已寄存 ${MAX_CHARTS_PER_TURN} 张，等不到新回合`);
                     return false;
                 }
-                // 安全阀：正常不该触发（冲刷会清空）；触发说明冲刷链路坏了，宁可丢图也要有界。
+                // Unreachable in normal flow; bound memory if flushing is broken.
                 let total = 0;
                 for (const list of pending.values())
                     total += list.length;
@@ -437,14 +294,11 @@ function buildChartEventPublisher(ctx) {
                 }
                 queued.push(input);
                 pending.set(owner.id, queued);
-                // 出图时回合是关的 ⇒ 走寄存。这条日志是**必要的可观测性**：它之后若没有对应的
-                // "已登记" 日志，就说明冲刷时机没接上（2026-09-20 的静默丢失正是死在这里，
-                // 两轮排查都因为没有日志而只能猜）。只在进程内报一次，不刷屏。
                 note(`图表已寄存，待 owner 回合关闭时登记（owner=${owner.id}，lastTurn=${String(lastTurn)}，寄存 ${queued.length} 张）`);
                 lastPublishTrace = `${trace.join(' ')} 回合未打开(openTurnStartSeq=${String(openSeq)} lastTurn=${String(lastTurn)}) → 已寄存 ${queued.length} 张，等 turn-stopping/turn-start 冲刷`;
                 return true;
             }
-            // turn 0 / 非法值表示该会话还没真正开过回合。
+            // turn 0 / invalid means the session never really opened a turn.
             if (typeof lastTurn !== 'number' || !Number.isSafeInteger(lastTurn) || lastTurn < 1) {
                 lastPublishTrace = `${trace.join(' ')} 回合号非法(lastTurn=${String(lastTurn)}) → 未写入`;
                 warn('图表对话流事件跳过：owner 会话没有打开中的 turn');
@@ -454,7 +308,7 @@ function buildChartEventPublisher(ctx) {
             lastPublishTrace = `${trace.join(' ')} 回合打开(turn=${lastTurn}) → ${written ? '已直接登记' : '写入失败'}`;
             return written;
         },
-        /** 诊断/测试用：当前寄存未冲刷的图表数。 */
+        /** Diagnostics/tests: queued charts not yet flushed. */
         pendingCount(ownerSessionId) {
             if (ownerSessionId !== undefined)
                 return pending.get(ownerSessionId)?.length ?? 0;
@@ -465,7 +319,7 @@ function buildChartEventPublisher(ctx) {
         },
     };
 }
-/** 出图时的 owner scope：与 chart_ref 同源（specialist 出图时正好是主会话）。 */
+/** Owner scope at render time; same source as chart_ref (specialist renders land on the main session). */
 export function chartEventOwnerSessionId(session, sourceSession) {
     return chartSessionScopeId(sourceSession ?? session);
 }

package/lib/chart/html.d.ts

@@ -5,16 +5,13 @@ export interface VendoredChartLibrary {
     license: string;
 }
 /**
- * 读取随包发布的 lightweight-charts standalone 构建。
- *
- * 路径相对 `import.meta.url`：编译后是 `lib/chart/vendor/...`（由 scripts/copy-assets.mjs
- * 从 `vendor/` 复制过去）。缺失时给出可操作错误，而不是让 HTML 里静默少一段脚本。
+ * Path is relative to import.meta.url (assets copied into lib by scripts/copy-assets.mjs);
+ * a missing library is a hard, actionable error rather than silently missing script bytes.
  */
 export declare function loadVendoredChartLibrary(): VendoredChartLibrary;
 export interface BuildStandaloneHtmlInput {
     payload: ChartPayload;
     library: VendoredChartLibrary;
-    /** 生成时刻（epoch ms），仅用于页脚署名，不参与渲染。 */
     generatedAt: number;
 }
 export declare function buildStandaloneHtml(input: BuildStandaloneHtmlInput): string;

package/lib/chart/html.js

@@ -1,12 +1,7 @@
 /**
- * 自包含 HTML 图表的生成器。
- *
- * 这是整个方案的**降级底线**（内部设计文档 docs/design/chart-visualization.md §5.4 的 L2）：
- * 它只依赖"用户有一个浏览器"，不依赖 DSH 的客户端插件系统、不依赖网络、
- * 不依赖任何上游扩展点。即使 Slot / bundle / 路由全部被上游改动打坏，
- * 用户依然能拿到一张可交互的图。
- *
- * 因此它必须：内联 vendored 库 + 内联数据 + 内联运行时，**零外部请求**。
+ * Standalone HTML: the L2 fallback that needs only a browser. Vendored library, data and
+ * runtime are inlined (zero external requests) so a broken client plugin, route or network
+ * cannot take charts down.
  */
 import { ChartError } from './errors.js';
 import { CHART_RUNTIME_SOURCE } from './runtime.js';
@@ -20,10 +15,8 @@ function nodeFs() {
 }
 let cachedLibrary;
 /**
- * 读取随包发布的 lightweight-charts standalone 构建。
- *
- * 路径相对 `import.meta.url`：编译后是 `lib/chart/vendor/...`（由 scripts/copy-assets.mjs
- * 从 `vendor/` 复制过去）。缺失时给出可操作错误，而不是让 HTML 里静默少一段脚本。
+ * Path is relative to import.meta.url (assets copied into lib by scripts/copy-assets.mjs);
+ * a missing library is a hard, actionable error rather than silently missing script bytes.
  */
 export function loadVendoredChartLibrary() {
     if (cachedLibrary)
@@ -41,15 +34,15 @@ export function loadVendoredChartLibrary() {
         throw new ChartError('chart_runtime_unavailable', `vendored lightweight-charts is missing (${error instanceof Error ? error.message : String(error)}); run npm run vendor:charts && npm run build`);
     }
 }
-/** 内联脚本的安全转义：`</script` 会提前结束 script 元素。 */
+/** `</script` would close the inline script element early. */
 function escapeScript(source) {
     return source.replace(/<\/script/gi, '<\\/script');
 }
-/** 内联 JSON 的安全转义：`<` 一律写成 `\u003c`（JSON 里合法，且彻底杜绝标签闭合）。 */
+/** `<` becomes `\u003c` (valid JSON) so data can never close a tag. */
 function escapeJson(value) {
     return JSON.stringify(value).replace(/</g, '\\u003c');
 }
-/** 数据截至时间：按本仓数据口径用 Asia/Shanghai 显示，同时保留 UTC。 */
+/** Data timestamps display in Asia/Shanghai per data convention; UTC is the fallback. */
 function formatCapturedAt(epochMs) {
     try {
         const parts = new Intl.DateTimeFormat('en-CA', {

package/lib/chart/present-tool.d.ts

@@ -0,0 +1,28 @@
+/**
+ * present_charts: the root Agent's final-turn delivery step.
+ *
+ * render_chart only mints a chart_ref (the specialist row no longer auto-delivers). DSH's
+ * deliverable card replays only declarations recorded before the closing assistant message, so
+ * the card has to be written by the turn that carries the final answer: the root Agent presents
+ * its collected refs/deliverables here immediately before writing that answer. Never a custom
+ * event type — the session-event vocabulary is closed (see events.ts).
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { ChartArtifactRegistry } from './artifact-ref.js';
+import { type ChartEventPublisher } from './events.js';
+export interface PresentChartsInput {
+    artifacts: ChartArtifactRegistry;
+    /** Lazy: the host projection may mount after this row; an absent publisher fails the call loudly. */
+    chartEvents: () => ChartEventPublisher | undefined;
+}
+export interface PresentChartsReceipt {
+    presented: Array<{
+        chart_ref: string;
+        title: string;
+    }>;
+    failed: Array<{
+        chart_ref: string;
+        reason: string;
+    }>;
+}
+export declare function registerPresentChartsTool(ctx: Context, input: PresentChartsInput): void;