@v587d/capital-generation 2.9.2 → 2.10.1

package/lib/agents/skill-usage.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Programmatic selected-skill ledger: a load counts only after the host returned the
+ * selected provider's body. The root prompt reads the tree; the report script re-derives
+ * the same facts from durable session logs, so model self-report is never the source.
+ */
+import { type AgentLike } from './root-tool-policy.js';
+export interface SkillUsageRow {
+    readonly sessionId: string;
+    readonly parentSession?: string;
+    readonly role: string;
+    readonly names: readonly string[];
+}
+/** Register a role Agent before it loads anything, so the tree edge survives an empty session. */
+export declare function trackSelectedSkillUsage(agent: AgentLike | undefined, role: string): void;
+export declare function recordSelectedSkillUsage(agent: AgentLike | undefined, role: string, name: string): void;
+/** A new user turn drops the previous turn's names but keeps the tree edges. */
+export declare function resetSelectedSkillUsage(rootSessionId: string): void;
+/** Agent teardown: the whole subtree's records are process-local and must not outlive it. */
+export declare function clearSelectedSkillUsage(rootSessionId: string): void;
+export declare function clearAllSelectedSkillUsage(): void;
+export declare function skillUsageRows(rootSessionId: string): SkillUsageRow[];
+export declare function skillUsageNamesForSession(sessionId: string): string[];

package/lib/agents/skill-usage.js

@@ -0,0 +1,92 @@
+/**
+ * Programmatic selected-skill ledger: a load counts only after the host returned the
+ * selected provider's body. The root prompt reads the tree; the report script re-derives
+ * the same facts from durable session logs, so model self-report is never the source.
+ */
+import { agentSessionId } from './root-tool-policy.js';
+const records = new Map();
+const bareSession = (id) => id.replace(/^session-/, '');
+function recordFor(agent, role) {
+    const id = agentSessionId(agent);
+    if (id === undefined)
+        return undefined;
+    const key = bareSession(id);
+    const parent = agent?.session?.header?.parentSession;
+    const parentId = typeof parent === 'string' && parent.length > 0 ? bareSession(parent) : undefined;
+    const existing = records.get(key);
+    if (existing !== undefined) {
+        existing.role = role;
+        if (parentId !== undefined)
+            existing.parentSession = parentId;
+        return existing;
+    }
+    const created = {
+        sessionId: key,
+        ...(parentId === undefined ? {} : { parentSession: parentId }),
+        role,
+        names: [],
+    };
+    records.set(key, created);
+    return created;
+}
+/** Register a role Agent before it loads anything, so the tree edge survives an empty session. */
+export function trackSelectedSkillUsage(agent, role) {
+    recordFor(agent, role);
+}
+export function recordSelectedSkillUsage(agent, role, name) {
+    if (name.length === 0)
+        return;
+    const record = recordFor(agent, role);
+    if (record === undefined)
+        return;
+    if (!record.names.includes(name))
+        record.names.push(name);
+}
+function rootOf(sessionId) {
+    let cursor = records.get(sessionId);
+    const seen = new Set();
+    while (cursor?.parentSession !== undefined && !seen.has(cursor.sessionId)) {
+        seen.add(cursor.sessionId);
+        const parent = records.get(cursor.parentSession);
+        if (parent === undefined)
+            break;
+        cursor = parent;
+    }
+    return cursor?.sessionId ?? sessionId;
+}
+/** A new user turn drops the previous turn's names but keeps the tree edges. */
+export function resetSelectedSkillUsage(rootSessionId) {
+    const root = bareSession(rootSessionId);
+    for (const record of records.values()) {
+        if (rootOf(record.sessionId) === root)
+            record.names.length = 0;
+    }
+}
+/** Agent teardown: the whole subtree's records are process-local and must not outlive it. */
+export function clearSelectedSkillUsage(rootSessionId) {
+    const root = bareSession(rootSessionId);
+    // Resolve every member BEFORE deleting: removing the root first would orphan its children
+    // and the remaining loop would no longer see them.
+    const doomed = [...records.values()]
+        .filter((record) => rootOf(record.sessionId) === root)
+        .map((record) => record.sessionId);
+    for (const id of doomed)
+        records.delete(id);
+}
+export function clearAllSelectedSkillUsage() {
+    records.clear();
+}
+export function skillUsageRows(rootSessionId) {
+    const root = bareSession(rootSessionId);
+    return [...records.values()]
+        .filter((record) => rootOf(record.sessionId) === root && record.names.length > 0)
+        .map((record) => ({
+        sessionId: record.sessionId,
+        ...(record.parentSession === undefined ? {} : { parentSession: record.parentSession }),
+        role: record.role,
+        names: [...record.names],
+    }));
+}
+export function skillUsageNamesForSession(sessionId) {
+    return [...(records.get(bareSession(sessionId))?.names ?? [])];
+}

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/capital-settings.d.ts

@@ -6,7 +6,7 @@
  */
 import type { Context } from '@deepseek-ai/cordis';
 import type { RetrieverConfig } from './retriever-config.js';
-import type { SelectedSkillSelection } from './agents/selected-skills-provider.js';
+import type { SelectedSkillSelection, SelectedSkillsMode } from './agents/selected-skills-provider.js';
 export declare const CAPITAL_CONFIG_ENTRY_ID = "capital-config";
 /** Fields this repo consumes (the host half owns the rest). */
 export interface CapitalConfigSlice {
@@ -15,7 +15,18 @@ export interface CapitalConfigSlice {
     customPersona?: string;
     retriever?: RetrieverConfig;
     selectedSkills?: SelectedSkillSelection;
+    selectedSkillsMode?: SelectedSkillsMode;
 }
+export type CapitalEntrySource = 'settings-describe' | 'config-editor';
+/**
+ * Settings first, then the config-editor save layer. The selected-skill provider and the
+ * persona section live in a separate preset row; reading only `settings.describe()` there
+ * made a saved toggle look all-off whenever the settings projection was not ready.
+ */
+export declare function readCapitalEntry(ctx: Context): {
+    value?: Record<string, unknown>;
+    source?: CapitalEntrySource;
+};
 export declare function readCapitalConfig(ctx: Context): CapitalConfigSlice;
 /** Flat credential refs needed by the collector domain (same shape as `CollectorConfig`). */
 export declare function readCollectorConfig(ctx: Context): {

package/lib/capital-settings.js

@@ -1,12 +1,32 @@
 export const CAPITAL_CONFIG_ENTRY_ID = 'capital-config';
-export function readCapitalConfig(ctx) {
+/**
+ * Settings first, then the config-editor save layer. The selected-skill provider and the
+ * persona section live in a separate preset row; reading only `settings.describe()` there
+ * made a saved toggle look all-off whenever the settings projection was not ready.
+ */
+export function readCapitalEntry(ctx) {
     try {
         const settings = ctx.get('settings');
-        return settings?.describe?.().find((entry) => entry?.ns === CAPITAL_CONFIG_ENTRY_ID)?.value ?? {};
+        const value = settings?.describe?.().find((entry) => entry?.ns === CAPITAL_CONFIG_ENTRY_ID)?.value;
+        if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
+            return { value: value, source: 'settings-describe' };
+        }
     }
     catch {
-        return {};
     }
+    try {
+        const editor = ctx.get('configEditor');
+        const value = editor?.entries?.().find((row) => row?.options?.id === CAPITAL_CONFIG_ENTRY_ID)?.options?.config;
+        if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
+            return { value: value, source: 'config-editor' };
+        }
+    }
+    catch {
+    }
+    return {};
+}
+export function readCapitalConfig(ctx) {
+    return (readCapitalEntry(ctx).value ?? {});
 }
 /** Flat credential refs needed by the collector domain (same shape as `CollectorConfig`). */
 export function readCollectorConfig(ctx) {

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: {

package/lib/chart/delivery.js

@@ -14,7 +14,8 @@ export function createChartDelivery(options) {
     let explicit = [];
     const exchangeStarts = new Map();
     const fallbackStart = Date.now();
-    let lastFlushedTurn;
+    /** One card per exchange. `turn` is unreliable: a later finish in the same turn may omit it. */
+    let flushed = false;
     let sawFrame = false;
     const attempts = new Map();
     const running = new Map();
@@ -54,14 +55,22 @@ export function createChartDelivery(options) {
             return true;
         return inboxMessages(inbox).every(isSettledNotice);
     };
-    const flush = (session, turn) => {
+    const flush = (session, turn, agent) => {
         // A later step in the same exchange may omit `turn`; it still must not write a second card.
-        if (lastFlushedTurn !== undefined && (turn === undefined || lastFlushedTurn === turn))
+        if (flushed)
             return;
         const inbox = options.inboxOf?.(session);
         reconcileSettled(inbox);
         if (!idle(inbox))
             return;
+        // The wake guard drops notices that would otherwise make the loop open another step after
+        // this answer. Run it even when no chart is selected, and never let it block delivery.
+        try {
+            options.onClosing?.(session, agent, turn);
+        }
+        catch {
+            // A guard failure must not strand an already-selected card.
+        }
         const inputs = (explicit.length > 0 ? explicit : autoInputs(session)).slice(0, maxCharts);
         if (inputs.length === 0)
             return;
@@ -72,9 +81,9 @@ export function createChartDelivery(options) {
         catch {
             written = false;
         }
-        // Sentinel keeps a second turn-less finish in the same exchange from duplicating the card.
+        // A failed write keeps the exchange open so a later closing finish can retry.
         if (written)
-            lastFlushedTurn = turn ?? -1;
+            flushed = true;
     };
     return {
         request(session, inputs) {
@@ -90,7 +99,7 @@ export function createChartDelivery(options) {
             if (explicit.length > maxCharts)
                 explicit = explicit.slice(0, maxCharts);
         },
-        acceptStream(session, frame) {
+        acceptStream(session, frame, agent) {
             if (!owns(session) || frame === undefined)
                 return;
             sawFrame = true;
@@ -116,14 +125,14 @@ export function createChartDelivery(options) {
             }
             if (chunk.type !== 'finish' || chunk.reason?.kind !== 'stop' || attempt.toolCall)
                 return;
-            flush(session, frame.turn);
+            flush(session, frame.turn, agent);
         },
         acceptUserMessage(id, time) {
             exchangeStarts.set(id, time);
             if (id !== sessionId)
                 return;
             explicit = [];
-            lastFlushedTurn = undefined;
+            flushed = false;
         },
         acceptSubagentStart(info) {
             if (typeof info?.id !== 'string' || info.id.length === 0)

package/lib/chart/events.d.ts

@@ -33,7 +33,7 @@ export interface ChartTurnEventInput {
     ownerSessionId: string;
     chart_id: string;
     title: string;
-    /** Workspace-relative chart.html path; the official preview resolves it against session.cwd. */
+    /** Workspace-relative self-contained HTML path; the official preview resolves it against session.cwd. */
     html_path: string;
 }
 export interface ChartEventPublisher {