@v587d/capital-generation 2.9.2 → 2.10.0

package/CHANGELOG.md

@@ -7,6 +7,49 @@
 - **第三位（patch）**：不破坏既有工具 / 配置 / 会话的新增与修复（如 2.1.1、2.1.2）。
 - **第二位（minor）**：有需要用户知晓的行为变更，且段内附迁移说明（如 2.1.0 的图表呈现通道重做、2.2.0 的数据源与检索来源扩容、2.4.0 的**必须换宿主版本**、2.9.0 的选择器收敛与质检前置——本插件自己的工具与数据契约没变，所以只抬第二位）。
 
+## [2.10.0] - 2026-10-23
+
+自动模式收口为**单轮等待 + 一次交付**：主 Agent 委派后等整棵子树收敛，再把结论和图表一次交到最后
+一轮；同时补上图表交付去重/标题校验、可读文件名，以及数据窗口、成交量单位与财务口径的硬规则。
+本插件自己的工具与数据契约不变，不需要改配置。
+
+### Added
+
+- **自动模式单轮等待**：主 Agent 新增 `wait_for_agents`（仅根会话）。委派或发消息后先等整棵子 Agent
+  树收敛，子角色回传在同一轮内处理，不再每条回执都单独落成一个可见轮次。
+- **四态回执**：`all_settled` / `message` / `user_input` / `timeout`；`timeout` 会列出仍在运行的
+  子 Agent，既不是完成也不是失败。
+- **图表交付质量闸门**：`present_charts` 登记前按 `dataset + kind + 标题` 去重，并校验标题里的
+  6 位股票代码与 dataset 一致；重复图/错标题图进 `failed`，不再进入交付卡片。
+- **可读图表产物与读图指引**：新图文件名带股票代码/ASCII 标题词与图形类型（如
+  `300803-kline-ab12cd34.html`），HTML 顶部补图形类型、来源、时间字段和横轴/纵轴/序列/K 线说明。
+
+### Changed
+
+- **等待不再以可见等待行结束回合**：主 Agent 先调用 `wait_for_agents`；`message` / `user_input`
+  先处理后继续等，`all_settled` 才进入逐行对账，`timeout` 才写等待行。等待期间仍禁止外部检索、
+  反复 `list_agents` 与轮询。
+- **单轮等待只归根会话**：`tools/orchestration` 只挂在根 preset；子 Agent 继续用 `send_message`
+  回传，不能等待兄弟或父 Agent。
+- **派生统计算子收紧**：`N 日` 一律按最近 N 个交易日计算；MA20/10 日高不再用自然日窗口，成交量
+  明确按股展示，量比注明分母是否含当日。
+- **财务与估值口径对齐**：`operating_income` 与媒体“营业总收入”、H1 累计与 Q2 单季、归母与
+  净利润、结构化扣非与媒体扣非分开标注；PE/PB/PS/PCF 并列，倍数分化时写“估值分化”。
+- **Specialist 调度收紧**：单次最多 8 个并发，使用 `Promise.allSettled`，按
+  `dataset_id + chart_source_ref` 记录成功并只重试失败项，禁止重发已成功图表。
+
+### Fixed
+
+- **MA20/10 日高窗口错误**：修复把 12 个交易日当 MA20、8 个交易日当 10 日高的问题；同类问题
+  在 data_junior 的派生统计与主 Agent 的结论复核中都会被协议拦下。
+- **成交量单位误写**：A 股 `history.volume` 原值为股，不再写成“万手”。
+- **H1/单季与扣非混用**：不再把媒体 H1 营业总收入与结构化 Q2 `operating_income` 放在同一增速
+  对比，也不在“扣非缺失”的同时引用媒体扣非。
+- **重复 K 线与错标题图**：`present_charts` 不再接受同 dataset/kind/标题的重复图，也不会把
+  “同花顺 300803”这类标题登记进交付卡片。
+- **Specialist 并发失败吞任务**：`Promise.all` 遇到并发上限错误时不再吞掉整批，失败任务可被
+  单独重试；已成功的 K 线不再被重复创建。
+
 ## [2.9.2] - 2026-10-23
 
 `data_junior` 接入官方 PTC（`run_code`）：内层工具调用压进一段程序，多 Dataset 并发、`too_large`

package/README.md

@@ -18,7 +18,7 @@
 <p align="center">
   <a href="https://awesome-dsh-plugin.com"><img src="https://awesome-dsh-plugin.com/badge.svg" alt="awesome · DSH plugin"></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-green" alt="License"></a>
-  <a href="https://github.com/v587d/capital-generation/releases"><img src="https://img.shields.io/badge/version-2.9.2-9cf" alt="Version"></a>
+  <a href="https://github.com/v587d/capital-generation/releases"><img src="https://img.shields.io/badge/version-2.10.0-9cf" alt="Version"></a>
   <a href="https://www.npmjs.com/package/@v587d/capital-generation"><img src="https://img.shields.io/npm/v/%40v587d%2Fcapital-generation" alt="npm version"></a>
   <a href="https://github.com/deepseek-ai/deepseek-harness"><img src="https://img.shields.io/badge/powered_by-dsh-4D6BFE?style=flat-square&logo=deepseek&logoColor=white" alt="powered-by-dsh"></a>
 </p>
@@ -115,11 +115,13 @@ https://github.com/v587d/capital-generation
 
 **每份结构化数据都会先做质检。** 无论你有没有提图表，自动模式收到行情或财务数据后都会先交给分析师检查结构、时间轴、缺失与基础统计；要不要图是检查之后的一个判断。明确说“不要图”时，质检照做，只是停在出图之前。
 
+自动模式会把子角色工作期间的中间回执留在同一轮里处理，等材料收齐后再给出完整结论，而不是每条中间进展都单独回一段。
+
 ## 试试这么用
 
 在新的自动模式会话中使用以下指令。将方括号内容换成自己的标的、公告或持仓；证券代码写完整市场后缀，例如 `600519.SH`。每条指令单独发送，便于观察结果。
 
-[样例：假期后研判报告（20261007）](docs/sample/假期后研判报告.md)
+[样例：指南针、同花顺复盘分析报告（20261023）](docs/sample/指南针-同花顺-复盘分析报告.md)
 
 **完整投资研究报告**
 
@@ -191,7 +193,7 @@ https://github.com/v587d/capital-generation
 - **安装后找不到模式？** 确认插件出现在「插件」→ 已安装列表；Web / CLI profile 安装后要重启该 profile，并在新会话选择模式。选择器里应看到自动模式、行情专家、资讯专员；分析师和绘图专员是自动模式的内部角色，不会出现在这里。
 - **配置在哪？** 打开「插件」→ 已安装的 **Capital Generation**，页面顶部就是「数据源 / 精选 Skills / 包含的组件」三格，五把密钥都在第一格；不在 DSH 的普通「设置」页面，也不用点进任何一行组件。保存密钥后新建会话再试。
 - **升级到 2.9.0 后，分析师和绘图专员去哪了？** 这一版把它们收进自动模式内部，不再出现在选择器与预设管理里，避免误开一个没有取数入口的空会话。旧会话仍能按原身份恢复；新任务直接用自动模式提出即可。
-- **桌面端升级后仍是旧版？** 桌面端安装时会固定所解析的版本，不会自动升级。卸载后重新安装，再到插件详情查看版本号；如需指定版本，可在地址末尾加 `#v2.9.2` 或 `@2.9.2`。
+- **桌面端升级后仍是旧版？** 桌面端安装时会固定所解析的版本，不会自动升级。卸载后重新安装，再到插件详情查看版本号；如需指定版本，可在地址末尾加 `#v2.10.0` 或 `@2.10.0`。
 - **刚发布的新版本装不到？** 桌面端取包时会跳过**刚发布不久**的版本（宿主侧包管理器的发布冷却策略，实测会静默装成上一个版本），国内镜像的同步也可能滞后一段时间。急着用最新代码，改用仓库地址安装最直接。
 - **网页抓取失败？** 配置卡片中的「允许启动本地提取网页内容」默认开启：AnySearch 提取失败时可尝试本机直连。关闭后，本机直连的具名来源查询也不可用；请检查该开关和网络连接。
 - **Wind 那部分会消耗积分？** 会。公告与新闻检索、宏观 / 行业 / 汇率指标、按日期区间取的历史 K 线都按次消耗你在 Wind 侧的额度；额度与条款以 Wind 为准，插件不做用量封顶。没配 `WIND_API_KEY` 时这几类不可用，其余功能照常。

package/chart-ui/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@v587d/capital-charts",
-  "version": "2.9.2",
+  "version": "2.10.0",
   "description": "自动模式的图表前端组件（浏览器半边 + 序列旁路路由）：由 @v587d/capital-generation 随包携带并作为 host 平面行挂载。",
   "license": "MIT",
   "type": "module",

package/config/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@v587d/config",
-  "version": "2.9.2",
+  "version": "2.10.0",
   "description": "自动模式的取数凭据与偏好配置行：卡片坐在 @v587d/capital-generation 插件主页的「配置」段，点这一行本身没有表单。",
   "license": "MIT",
   "type": "module",

package/lib/agents/settled-wake.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Removes redundant `subagent-settled` notices at the closing frame; otherwise the host loop opens
+ * another step after a complete answer and folds it. Only children with an admitted relay are
+ * dropped — a silent child may carry its only outcome in the notice.
+ * Rationale: docs/dev/chart-delivery-events.md §6.3.
+ */
+import type { SessionLike } from '../data-collector/store.js';
+export interface WakeMessageLike {
+    readonly id?: string;
+    readonly source?: {
+        readonly kind?: string;
+        readonly senderSessionId?: string;
+    };
+}
+interface InboxLike {
+    readonly nextTurn?: readonly unknown[];
+    readonly nextStep?: readonly unknown[];
+    remove?(messageId: string): boolean;
+}
+export interface WakeAgentLike {
+    readonly session?: SessionLike;
+    readonly inbox?: InboxLike;
+}
+export interface SettledWakeGuard {
+    /** `user/message` events: human resets the exchange, an admitted child relay marks that child. */
+    acceptUserMessage(session: SessionLike, source: {
+        kind?: string;
+        senderSessionId?: string;
+    }): void;
+    /** Terminal assistant-stream frame: the closing answer is being written. */
+    acceptClosing(agent: WakeAgentLike | undefined): void;
+    /** A notice inserted after the closing frame must not wake a new step. */
+    acceptInboxInserted(agent: WakeAgentLike | undefined, message: WakeMessageLike | undefined): void;
+    /** A fresh activation invalidates the previous exchange's relay marker. */
+    acceptSubagentStart(info: {
+        id?: string;
+    }): void;
+    /** Diagnostics/tests. */
+    closing(): boolean;
+    admitted(): readonly string[];
+}
+export declare function createSettledWakeGuard(): SettledWakeGuard;
+export {};

package/lib/agents/settled-wake.js

@@ -0,0 +1,81 @@
+function messageOf(value) {
+    return value !== null && typeof value === 'object' ? value : undefined;
+}
+export function createSettledWakeGuard() {
+    let rootSessionId;
+    let closing = false;
+    const admitted = new Set();
+    const owns = (session) => {
+        if (session?.id === undefined)
+            return false;
+        // A child's own user/message events must not clear the root's state.
+        if (session.header?.origin === 'subagent')
+            return false;
+        rootSessionId ??= session.id;
+        return session.id === rootSessionId;
+    };
+    const dropNotice = (agent, message) => {
+        const childId = message.source?.senderSessionId;
+        if (typeof childId !== 'string' || !admitted.has(childId))
+            return false;
+        if (agent?.inbox?.remove === undefined || typeof message.id !== 'string')
+            return false;
+        let removed = false;
+        try {
+            removed = agent.inbox.remove(message.id);
+        }
+        catch {
+            removed = false;
+        }
+        if (removed)
+            admitted.delete(childId);
+        return removed;
+    };
+    const dropPending = (agent) => {
+        if (agent?.inbox === undefined)
+            return;
+        for (const value of [...(agent.inbox.nextTurn ?? []), ...(agent.inbox.nextStep ?? [])]) {
+            const message = messageOf(value);
+            if (message?.source?.kind !== 'subagent-settled')
+                continue;
+            dropNotice(agent, message);
+        }
+    };
+    return {
+        acceptUserMessage(session, source) {
+            if (!owns(session))
+                return;
+            if (source.kind === 'user') {
+                admitted.clear();
+                closing = false;
+                return;
+            }
+            if (source.kind !== 'agent-message')
+                return;
+            if (typeof source.senderSessionId !== 'string' || source.senderSessionId.length === 0)
+                return;
+            admitted.add(source.senderSessionId);
+            // The answer that follows this relay is not the previous closing answer.
+            closing = false;
+        },
+        acceptClosing(agent) {
+            if (agent?.session !== undefined && !owns(agent.session))
+                return;
+            closing = true;
+            dropPending(agent);
+        },
+        acceptInboxInserted(agent, message) {
+            if (agent?.session !== undefined && !owns(agent.session))
+                return;
+            if (message?.source?.kind !== 'subagent-settled' || !closing)
+                return;
+            dropNotice(agent, message);
+        },
+        acceptSubagentStart(info) {
+            if (typeof info?.id === 'string' && info.id.length > 0)
+                admitted.delete(info.id);
+        },
+        closing: () => closing,
+        admitted: () => [...admitted],
+    };
+}

package/lib/agents/wait-for-agents.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Root-only `wait_for_agents`: hold one turn across child relays; returns on the first relay, on
+ * the tree settling, or after 30s. `waitForChildren` has no abort parameter; the slice races it.
+ * Host contract: docs/reference/dsh-surface-ledger.md L36.
+ */
+import type { Context } from '@deepseek-ai/cordis';
+export interface WaitInboxLike {
+    readonly nextTurn?: readonly unknown[];
+    readonly nextStep?: readonly unknown[];
+}
+export interface WaitAgentLike {
+    readonly session?: {
+        readonly id?: string;
+        readonly header?: {
+            readonly parentSession?: string;
+            readonly origin?: 'subagent';
+        };
+    };
+    readonly inbox?: WaitInboxLike;
+    readonly status?: 'idle' | 'running';
+}
+export interface WaitDescendantLike {
+    readonly kind?: string;
+    readonly id?: string;
+    readonly label?: string;
+    readonly activity?: string;
+}
+export interface WaitSubagentsLike {
+    waitForChildren(parent: WaitAgentLike): Promise<boolean>;
+    listDescendants?(rootSessionId: string, signal?: AbortSignal): Promise<readonly WaitDescendantLike[]>;
+}
+interface AgentsLike {
+    get?(id: string): {
+        readonly status?: 'idle' | 'running';
+    } | undefined;
+}
+interface EventContextLike {
+    on?(event: string, listener: (...args: unknown[]) => void): unknown;
+}
+export interface WaitForAgentsOptions {
+    /** Bounded slice; the model cannot extend it. */
+    readonly waitSliceMs?: number;
+    readonly now?: () => number;
+}
+export interface WaitForAgentsDeps extends WaitForAgentsOptions {
+    subagents: () => WaitSubagentsLike | undefined;
+    events?: EventContextLike;
+    agents?: () => AgentsLike | undefined;
+}
+export type WaitForAgentsStatus = 'all_settled' | 'message' | 'user_input' | 'timeout';
+export interface WaitForAgentsReceipt {
+    readonly status: WaitForAgentsStatus;
+    readonly waited_ms: number;
+    readonly pending_messages: number;
+    readonly running: Array<{
+        readonly id: string;
+        readonly label?: string;
+    }>;
+    readonly hint: string;
+}
+declare function render(_args: unknown, value: unknown): Array<{
+    type: 'text';
+    text: string;
+}>;
+export declare function waitForAgentsToolDefinition(deps: WaitForAgentsDeps): {
+    name: string;
+    description: string;
+    parameters: object;
+    output: {
+        schema: object;
+        render: typeof render;
+    };
+    execute(_args: Record<string, unknown>, exec: {
+        signal: AbortSignal;
+        agent?: WaitAgentLike;
+    }): Promise<WaitForAgentsReceipt>;
+};
+export declare function registerWaitForAgentsTool(ctx: Context, options?: WaitForAgentsOptions): void;
+export {};

package/lib/agents/wait-for-agents.js

@@ -0,0 +1,256 @@
+const DEFAULT_WAIT_SLICE_MS = 30_000;
+const MAX_WAIT_SLICE_MS = 60_000;
+const jsonObject = (properties = {}, required = []) => ({ type: 'object', properties, required, additionalProperties: false });
+function render(_args, value) {
+    return [{ type: 'text', text: JSON.stringify(value) }];
+}
+function sourceKindOf(message) {
+    if (message === null || typeof message !== 'object')
+        return undefined;
+    const source = message.source;
+    if (source === null || typeof source !== 'object')
+        return undefined;
+    const kind = source.kind;
+    return typeof kind === 'string' ? kind : undefined;
+}
+/** Settlement notices are lifecycle noise here; only a human or a relayed result is actionable. */
+function pendingCounts(agent) {
+    const messages = [...(agent.inbox?.nextTurn ?? []), ...(agent.inbox?.nextStep ?? [])];
+    let users = 0;
+    let children = 0;
+    for (const message of messages) {
+        const kind = sourceKindOf(message);
+        if (kind === 'user')
+            users += 1;
+        else if (kind === 'agent-message')
+            children += 1;
+    }
+    return { total: users + children, users, children };
+}
+function resolveSlice(value) {
+    const numeric = typeof value === 'number' && Number.isFinite(value) ? Math.floor(value) : DEFAULT_WAIT_SLICE_MS;
+    return Math.max(1, Math.min(MAX_WAIT_SLICE_MS, numeric));
+}
+function abortReason(signal) {
+    return signal.reason instanceof Error ? signal.reason : new Error('wait_for_agents aborted');
+}
+function waitTimer(ms, signal) {
+    let handle;
+    let onAbort;
+    const promise = new Promise((resolve, reject) => {
+        if (signal.aborted) {
+            reject(abortReason(signal));
+            return;
+        }
+        handle = setTimeout(() => resolve('timeout'), ms);
+        onAbort = () => {
+            if (handle !== undefined)
+                clearTimeout(handle);
+            reject(abortReason(signal));
+        };
+        signal.addEventListener('abort', onAbort, { once: true });
+    });
+    return {
+        promise,
+        dispose: () => {
+            if (handle !== undefined)
+                clearTimeout(handle);
+            if (onAbort !== undefined)
+                signal.removeEventListener('abort', onAbort);
+        },
+    };
+}
+async function runningRows(service, agentsOf, sessionId, signal) {
+    if (typeof service.listDescendants !== 'function')
+        return [];
+    let rows;
+    try {
+        rows = await service.listDescendants(sessionId, signal);
+    }
+    catch {
+        return [];
+    }
+    let agents;
+    try {
+        agents = agentsOf?.();
+    }
+    catch {
+        agents = undefined;
+    }
+    const seen = new Set();
+    const running = [];
+    for (const row of rows ?? []) {
+        if (row?.kind !== 'child' || typeof row.id !== 'string' || seen.has(row.id))
+            continue;
+        let live;
+        try {
+            live = agents?.get?.(row.id);
+        }
+        catch {
+            live = undefined;
+        }
+        // A live idle child is not progressing; a catalog row alone is only a historical child.
+        if (live?.status === 'idle')
+            continue;
+        if (row.activity !== 'running' && live?.status !== 'running')
+            continue;
+        seen.add(row.id);
+        const label = typeof row.label === 'string' && row.label.length > 0 ? row.label : undefined;
+        running.push({ id: row.id, ...(label === undefined ? {} : { label }) });
+    }
+    return running;
+}
+function hintFor(status, pending, running) {
+    switch (status) {
+        case 'all_settled':
+            return '所有子 Agent 已结束。现在按对账表逐行核对；收齐后先 present_charts（有图）再写完整最终答复。';
+        case 'message':
+            return `有 ${pending} 条子 Agent 消息待处理，下一步会带上它们；处理完仍有未结算角色就再调用 wait_for_agents。`;
+        case 'user_input':
+            return `用户在等待期间发来消息；当前有 ${pending} 条可执行消息待处理，先处理用户输入，再决定是否继续等待。`;
+        case 'timeout':
+            return running > 0
+                ? `本次等待窗口内未收敛，仍有 ${running} 个子 Agent 在运行；继续调用 wait_for_agents。running 已列出存活子树，不要再调用 list_agents，也不要 send_message 催运行中的子 Agent；只有用户要求进度或无法继续时才说明。`
+                : '本次等待窗口内未收敛，也没有可报告的运行中子 Agent；再调用一次确认，不要调用 list_agents，不要当作完成。';
+    }
+}
+export function waitForAgentsToolDefinition(deps) {
+    const waitSliceMs = resolveSlice(deps.waitSliceMs);
+    const now = deps.now ?? Date.now;
+    const parameters = jsonObject({});
+    const outputSchema = jsonObject({
+        status: { type: 'string', enum: ['all_settled', 'message', 'user_input', 'timeout'] },
+        waited_ms: { type: 'integer' },
+        pending_messages: { type: 'integer' },
+        running: {
+            type: 'array',
+            items: jsonObject({
+                id: { type: 'string' },
+                label: { type: 'string' },
+            }, ['id']),
+        },
+        hint: { type: 'string' },
+    }, ['status', 'waited_ms', 'pending_messages', 'running', 'hint']);
+    return {
+        name: 'wait_for_agents',
+        description: '等待你的子 Agent 树完成当前工作，单次最多 30 秒；把“每个子 Agent 回传/结算各开一轮”收敛成同一轮。'
+            + '创建、复用或 send_message 之后调用它，等待期间不写可见正文，也不要用“请稍候”式正文结束回合。'
+            + '返回 message 或 user_input 时，下一步会带上这些消息；处理完继续调用。'
+            + '返回 all_settled 才进入对账与最终答复；timeout 表示仍未收敛，仍有 running 时继续调用，不要仅因一次超时写等待行。'
+            + '等待期间不要用 list_agents 轮询。只对主 Agent 开放；没有子 Agent 时会立即返回 all_settled。',
+        parameters,
+        output: { schema: outputSchema, render },
+        // Deliberately no isConcurrencySafe: waiting is the ordering barrier between dispatch and synthesis.
+        async execute(_args, exec) {
+            const agent = exec.agent;
+            const sessionId = agent?.session?.id;
+            if (agent === undefined || sessionId === undefined) {
+                throw new Error('wait_for_agents requires a calling agent (exec.agent was undefined)');
+            }
+            // `parentSession` alone is a user fork; only the subagent origin marks a delegated child.
+            if (agent.session?.header?.origin === 'subagent') {
+                throw new Error('wait_for_agents 只对主 Agent 开放：子 Agent 用 send_message 回传结果，不要等待其他 Agent。');
+            }
+            if (exec.signal.aborted)
+                throw abortReason(exec.signal);
+            const service = deps.subagents();
+            if (service?.waitForChildren === undefined) {
+                throw new Error('wait_for_agents 不可用：宿主 subagents 服务未挂载；不要用 list_agents 轮询代替。');
+            }
+            const started = now();
+            const initial = pendingCounts(agent);
+            if (initial.users > 0 || initial.children > 0) {
+                const status = initial.users > 0 ? 'user_input' : 'message';
+                const running = await runningRows(service, deps.agents, sessionId, exec.signal);
+                return {
+                    status,
+                    waited_ms: Math.max(0, Math.round(now() - started)),
+                    pending_messages: initial.total,
+                    running,
+                    hint: hintFor(status, initial.total, running.length),
+                };
+            }
+            let resolveInbox;
+            const inboxEvent = new Promise((resolve) => { resolveInbox = resolve; });
+            const onInserted = (...args) => {
+                const payload = args[0];
+                if (payload?.agent?.session?.id !== sessionId)
+                    return;
+                const kind = sourceKindOf(payload.message);
+                if (kind === 'agent-message')
+                    resolveInbox('message');
+                else if (kind === 'user')
+                    resolveInbox('user_input');
+            };
+            let dispose;
+            if (typeof deps.events?.on === 'function') {
+                try {
+                    dispose = deps.events.on('agent/inbox/inserted', onInserted);
+                }
+                catch {
+                    dispose = undefined;
+                }
+            }
+            let outcome;
+            const slice = waitTimer(waitSliceMs, exec.signal);
+            try {
+                const wait = Promise.resolve(service.waitForChildren(agent));
+                // The loser of the race must not become an unhandled rejection when the slice or a relay wins.
+                wait.catch(() => undefined);
+                outcome = await Promise.race([
+                    wait.then(() => 'settled'),
+                    inboxEvent,
+                    slice.promise,
+                ]);
+            }
+            finally {
+                slice.dispose();
+                if (typeof dispose === 'function')
+                    dispose();
+            }
+            const pending = pendingCounts(agent);
+            const status = pending.users > 0
+                ? 'user_input'
+                : pending.children > 0
+                    ? 'message'
+                    : outcome === 'timeout' ? 'timeout' : 'all_settled';
+            const running = status === 'all_settled'
+                ? []
+                : await runningRows(service, deps.agents, sessionId, exec.signal);
+            return {
+                status,
+                waited_ms: Math.max(0, Math.round(now() - started)),
+                pending_messages: pending.total,
+                running,
+                hint: hintFor(status, pending.total, running.length),
+            };
+        },
+    };
+}
+export function registerWaitForAgentsTool(ctx, options = {}) {
+    const tools = ctx.get('tools');
+    if (tools === undefined)
+        return;
+    const events = ctx;
+    const definition = waitForAgentsToolDefinition({
+        ...options,
+        subagents: () => {
+            try {
+                return ctx.get('subagents');
+            }
+            catch {
+                return undefined;
+            }
+        },
+        events,
+        agents: () => {
+            try {
+                return ctx.get('agents');
+            }
+            catch {
+                return undefined;
+            }
+        },
+    });
+    ctx.effect(() => tools.register(definition), 'capital-generation.tool(wait_for_agents)');
+}

package/lib/chart/artifact-ref.d.ts

@@ -11,6 +11,8 @@ export interface ChartArtifactRef {
     dataset_id: string | null;
     source_label: string | null;
     captured_at: number | null;
+    /** Six-digit security/index code parsed from the Dataset envelope or rows, when present. */
+    subject_code: string | null;
     kind: string;
     axis: 'time' | 'index';
     title: string;
@@ -28,7 +30,7 @@ export interface ChartArtifactRegistryOptions {
 }
 /**
  * In-process chart_ref capabilities: session/task/workspace binding and the deliverable owner
- * scope. Process restart invalidates them; chart.html remains the offline fallback.
+ * scope. Process restart invalidates them; the title-named self-contained HTML remains the offline fallback.
  */
 export declare class ChartArtifactRegistry {
     private readonly records;
@@ -44,6 +46,7 @@ export declare class ChartArtifactRegistry {
         dataset_id?: string | null;
         source_label?: string | null;
         captured_at?: number | null;
+        subject_code?: string | null;
         kind: string;
         axis: 'time' | 'index';
         title: string;

package/lib/chart/artifact-ref.js

@@ -18,7 +18,7 @@ export function chartSessionScopeId(session) {
 }
 /**
  * In-process chart_ref capabilities: session/task/workspace binding and the deliverable owner
- * scope. Process restart invalidates them; chart.html remains the offline fallback.
+ * scope. Process restart invalidates them; the title-named self-contained HTML remains the offline fallback.
  */
 export class ChartArtifactRegistry {
     records = new Map();
@@ -57,6 +57,7 @@ export class ChartArtifactRegistry {
             dataset_id: input.dataset_id ?? null,
             source_label: input.source_label ?? null,
             captured_at: input.captured_at ?? null,
+            subject_code: input.subject_code ?? null,
             kind: input.kind,
             axis: input.axis,
             title: input.title,

package/lib/chart/delivery.d.ts

@@ -31,6 +31,15 @@ export interface AssistantStreamFrameLike {
         };
     };
 }
+/** Live root Agent passed to the closing hook so it can cancel inbox notices before the loop claims them. */
+export interface DeliveryAgentLike {
+    readonly session?: SessionLike;
+    readonly inbox?: {
+        readonly nextTurn?: readonly unknown[];
+        readonly nextStep?: readonly unknown[];
+        remove?(messageId: string): boolean;
+    };
+}
 interface InboxStateLike {
     'next-turn'?: readonly unknown[];
     'next-step'?: readonly unknown[];
@@ -41,13 +50,18 @@ export interface ChartDeliveryOptions {
     publish: (sessionId: string, inputs: ChartTurnEventInput[]) => boolean;
     /** Durable pending input; synchronous projection read. Absent means "cannot tell" → proceed. */
     inboxOf?: (session: SessionLike) => InboxStateLike | undefined;
+    /**
+     * Runs on every closing finish, including exchanges with no chart. The wake guard removes
+     * redundant settlement notices here; it must never be allowed to block delivery.
+     */
+    onClosing?: (session: SessionLike, agent: DeliveryAgentLike | undefined, turn: number | undefined) => void;
     /** Bounded batch; the card collapses past four files and expands on demand. */
     maxCharts?: number;
 }
 export interface ChartDelivery {
     /** `present_charts` selection; merged across calls because models often retry in batches. */
     request(session: SessionLike, inputs: ChartTurnEventInput[]): void;
-    acceptStream(session: SessionLike | undefined, frame: AssistantStreamFrameLike): void;
+    acceptStream(session: SessionLike | undefined, frame: AssistantStreamFrameLike, agent?: DeliveryAgentLike): void;
     /** A new human message starts a new exchange: old charts must not ride into it. */
     acceptUserMessage(sessionId: string, time: number): void;
     acceptSubagentStart(info: {