@khorsheed/dsh-room 0.2.2 → 0.2.4

package/lib/types/dispatch.js

@@ -8,22 +8,27 @@
  * the exact dispatch history — but speech/dispatch events are UI projection
  * and replay ONLY: no prompt ever consumes the room's running log.
  *
- * The prompt every member receives is uniform (the design note's roster +
- * notifications contract): role instructions (first dispatch, or an edit
- * carried as an update) + the room goal (one line, every dispatch — cheap,
- * and it orients the task) + the roster (who exists, with the notification
- * protocol) ONLY when the member has never seen it or it changed since their
- * last dispatch ({@link rosterStaleSince}) + the member's
- * confirmed-undelivered notifications + this dispatch's text. The member's
- * own CLI session (resume chain) holds its working memory; room never
- * resends what it has seen.
+ * The prompt every member receives is uniform: the member's FIRST dispatch
+ * opens with one room briefing (identity, public role, private instructions,
+ * goal, roster of public roles, the tool-based collaboration contract);
+ * every later dispatch carries only what changed since the member's previous
+ * one — an instructions edit, one-line room changes ({@link roomChangesSince}),
+ * a coordinator handoff — plus the member's confirmed-undelivered
+ * notifications and this dispatch's text. The member's own session (resume
+ * chain) holds its working memory; room never resends what it has seen, and
+ * no member ever receives another member's private instructions.
  * @module @khorsheed/dsh-room/dispatch
  */
 import { replayDeliveries } from './deliveries.js';
 import { randomUUID } from 'node:crypto';
+import { SessionId } from '@deepseek-ai/dsh-session';
 import { createUserMessage } from '@deepseek-ai/dsh-llm';
 import { probeLocalAgent, runOutputText } from './adapter.js';
-import { coordinatorMember, memberId, parseRelayDirective, pendingInstructions, previousCursor, replay, rosterStaleSince } from './journal.js';
+import { composeRoomAgent } from './agent-setup.js';
+import { coordinatorMember, memberId, pendingInstructions, previousCursor, replay, roomChangesSince } from './journal.js';
+import { envelopeLine, messageId, sendOrHold } from './messaging.js';
+import { gateState, judgeReport, outstandingFor } from './report-gate.js';
+import { decisionRecord } from './decisions.js';
 /**
  * The room producer's durable identity in its two historical forms: the
  * released V3 wrapper's `plugin` value (`@khorsheed/dsh-room` — the official
@@ -38,6 +43,38 @@ export const ROOM_KIND = 'room';
 export function roomSource() {
     return Object.freeze({ kind: ROOM_KIND });
 }
+/**
+ * A run-state edge's child-session identity: the main agent runs on the room
+ * itself, external members on their child session. Optional — a fresh CLI
+ * member's early running edge predates the child handle's publication (the
+ * terminal edge and the journal backfill cover it).
+ */
+export function runChildSessionId(roomId, member) {
+    if (member?.kind === 'main-agent')
+        return roomId;
+    return member?.childSessionId;
+}
+/**
+ * The child session round a run reached: the last turn/start the child wrote.
+ * Live sessions only — a reconcile path whose child is not in memory omits it.
+ */
+/**
+ * The id of the last assistant message a session's log holds after `afterSeq`:
+ * the message a member's round closed with, which per-message tools (Context
+ * Lens) address in the member's own session.
+ * @param session - the member's session.
+ * @param afterSeq - only messages after this seq count.
+ * @returns the message id, or undefined when the round produced none.
+ */
+export function lastAssistantMessageId(session, afterSeq = -1) {
+    const event = session?.snapshotEvents().findLast(entry => entry.type === 'assistant/message' && entry.seq > afterSeq);
+    const id = event?.data?.message?.id;
+    return typeof id === 'string' ? id : undefined;
+}
+export function runChildTurn(session) {
+    const last = session?.snapshotEvents().filter(event => event.type === 'turn/start').at(-1);
+    return last?.data?.turn;
+}
 /**
  * Whether a durable source belongs to the room producer, in every form the
  * log can hold: the current producer-owned kind (`room`), the V3→V4 migrated
@@ -59,27 +96,37 @@ function closedGoal(state, goalId) {
         && (state.plan.id !== goalId || ['completed', 'cancelled'].includes(state.plan.status));
 }
 /**
- * The roster section: one line per OTHER member (name, provider, one-line
- * role) plus the notification protocol — the fallback channel's trailing
- * own-line `@name <content>` format lives here so a member can reach others
- * without any bridge tooling. Carried only when the member has never seen
- * the roster or it changed since their last dispatch ({@link rosterStaleSince});
- * the member's own session holds it in between. The room GOAL is NOT part of
- * this section: it rides every dispatch on its own line (cheap, and it
- * orients the task).
+ * The member's first-dispatch briefing: who it is (name + public role), its
+ * private instructions, the goal, everyone else by PUBLIC role only (never
+ * their instructions — those read like orders addressed to the reader), and
+ * the collaboration contract. Members reach each other through tools —
+ * `member_message` on the local-agent bridge for CLI members, `room_message`
+ * for the room's own agent — and read the live roster with `room_read`; a
+ * trailing `@name` line in a reply is plain text and reaches nobody.
  */
-function rosterSection(state, self) {
-    const lines = state.members
-        .filter(member => member.name !== self)
-        .map((member) => {
-        const provider = member.kind === 'main-agent' ? '原生 DSH' : member.provider ?? '';
-        const role = member.instructions?.split('\n', 1)[0]?.trim();
-        return `- ${member.name}（${provider}）${role === undefined || role === '' ? '' : `：${role}`}`;
+function briefingSection(state, member, instructions, coordinator) {
+    const others = state.members
+        .filter(entry => entry.name !== member.name)
+        .map((entry) => {
+        const facts = [
+            ...coordinator?.name === entry.name ? ['协调者'] : [],
+            ...entry.role === undefined ? [] : [entry.role],
+            entry.kind === 'main-agent' ? '原生 DSH' : entry.kind === 'native' ? `原生 DSH${entry.preset === undefined ? '' : ` · ${entry.preset}`}` : entry.provider ?? '',
+        ].filter(Boolean);
+        return `- ${entry.name}（${facts.join(' · ')}）`;
     });
     return [
-        '【成员名册】',
-        ...lines,
-        '通知协议：要通知某个成员，在回复末尾独占一行写 `@名字 <内容>`；该行会被转交给对方（一阶段需房间主人确认）。',
+        '【房间简报】',
+        `你是协作间成员「${member.name}」${member.role === undefined ? '' : `，职责：${member.role}`}${coordinator?.name === member.name ? '，也是本房间的协调者' : ''}。`,
+        ...instructions === undefined ? [] : [`你的指令：${instructions}`],
+        ...state.goal === undefined ? [] : [`房间目标：${state.goal}`],
+        ...others.length === 0 ? [] : ['其他成员：', ...others],
+        `联系成员、派活用 ${member.kind === 'cli' ? 'member_message' : 'room_message'}，看房间现状和任务编号用 room_read，用法见工具说明。成员发来的消息开头标着来自谁和消息编号（#m12），没有标注的是人发的；派给你的活，你这一轮的最终回复会自动回报给派活人，不用另外回复。`,
+        '要找房间外的会话帮忙（人在消息里 @ 的会话 `@[…](dsh-session:…)`，包括另一个协作间或它的成员），直接用 room_help，不要转给别的成员代问。',
+        // A CLI reaches the room's tools (and its mode's) through an MCP server,
+        // which some CLIs keep behind tool discovery rather than in the visible list.
+        ...member.kind === 'cli' ? [`这些房间工具由名为 dsh-member 的 MCP 服务提供${member.preset === undefined ? '' : `，你挂的「${member.preset}」模式的插件工具也在这个服务里`}；没在工具列表里直接看到时，用工具发现查找 dsh-member 的工具。`, '需要人拍板或补充信息时，用 dsh-member 的 ask_user_question 把问题和选项发给人点选，不要把一串问题写在回复里；它会等人回答后把答案返回给你。'] : [],
+        ...coordinator?.name === member.name ? ['作为协调者：普通对话直接回答，小任务派给成员，只在确有需要时建立正式目标。派完活就结束这一轮，回报会自己送到——不要 sleep 等待，也不要用 room_read 查结果。收到回报时用户已经看过成员的原话：需要推进就推进，否则一两句话即可，不要复述或做汇总表。'] : [],
     ].join('\n');
 }
 /** The notifications section: confirmed-undelivered relays addressed to the member. */
@@ -87,33 +134,90 @@ function notificationsSection(relays) {
     return ['【通知】', ...relays.map(relay => `- ${relay.from} 给你的通知: ${relay.content}`)].join('\n');
 }
 /**
- * Assemble the uniform member prompt: role-instructions carry, then the room
- * goal (every dispatch), then the roster (only when stale for this member),
- * then the member's confirmed-undelivered notifications (except the ones
- * this dispatch's own text already delivers), then this dispatch's text.
+ * Assemble the uniform member prompt: the briefing on the member's first
+ * dispatch, otherwise only what changed since its previous one (handoff,
+ * instructions edit, room changes); then the member's confirmed-undelivered
+ * notifications (except the ones this dispatch's own text already delivers),
+ * then this dispatch's text.
  */
-function assemblePrompt(room, member, cursor, text, relayIds) {
+function assemblePrompt(room, member, cursor, text, relayIds, dispatchSeq) {
     const state = replay(room.snapshotEvents());
     const carried = state.relays.filter(relay => relay.state === 'confirmed' && relay.to === member.name && !relayIds.includes(relay.id));
     const sections = [];
-    const handoff = room.snapshotEvents().filter(event => event.type === 'room/coordinator' && event.data.memberId === memberId(room.snapshotEvents(), member)).at(-1);
-    if (handoff?.type === 'room/coordinator' && (cursor === undefined || handoff.seq > cursor))
-        sections.push(handoff.data.handoff);
-    if (coordinatorMember(state, room.snapshotEvents())?.name === member.name)
-        sections.push('You are the room coordinator. Handle ordinary chat directly; delegate small work in the background using room tools. Establish a goal plan only when useful for the requested execution. Delegate results arrive as correlated reports; do not poll while waiting.');
-    const pending = pendingInstructions(room.snapshotEvents(), member.name, cursor);
-    if (pending?.kind === 'initial')
-        sections.push(`你的角色指令：${pending.instructions}`);
-    if (pending?.kind === 'update')
-        sections.push(`你的角色指令更新为：${pending.instructions}`);
-    if (state.goal !== undefined)
-        sections.push(`本房间的目标：${state.goal}`);
-    if (rosterStaleSince(room.snapshotEvents(), cursor))
-        sections.push(rosterSection(state, member.name));
+    const events = room.snapshotEvents();
+    const coordinator = coordinatorMember(state, events);
+    const handoff = events.filter(event => event.type === 'room/coordinator' && event.data.memberId === memberId(events, member)).at(-1);
+    const pending = pendingInstructions(events, member.name, cursor);
+    if (cursor === undefined) {
+        sections.push(briefingSection(state, member, pending?.instructions, coordinator));
+        if (handoff?.type === 'room/coordinator')
+            sections.push(handoff.data.handoff);
+    }
+    else {
+        if (handoff?.type === 'room/coordinator' && handoff.seq > cursor)
+            sections.push(`你现在是本房间的协调者。\n${handoff.data.handoff}`);
+        if (pending?.kind === 'update')
+            sections.push(`你的指令更新为：${pending.instructions}`);
+        const changes = roomChangesSince(events, cursor, member.name);
+        if (changes.length > 0)
+            sections.push(['【房间变动】', ...changes.map(change => `- ${change}`)].join('\n'));
+    }
     if (carried.length > 0)
         sections.push(notificationsSection(carried));
-    sections.push(text);
-    return { prompt: sections.join('\n\n'), carried };
+    // Reports the gate held for this member and no inbox took: they ride this round.
+    const held = (state.deliveries ?? []).filter(row => row.memberId === memberId(events, member) && row.status === 'held' && row.dispatchSeq !== dispatchSeq);
+    for (const row of held)
+        sections.push(`${envelopeLine(events, row.dispatchSeq) ?? ''}\n${row.text}`.trim());
+    const envelope = dispatchSeq === undefined ? undefined : envelopeLine(events, dispatchSeq);
+    sections.push(envelope === undefined ? text : `${envelope}\n${text}`);
+    return { prompt: sections.join('\n\n'), carried, heldCarried: held.map(row => row.dispatchSeq) };
+}
+/**
+ * Reports held for a member that it has not yet seen in a round: hold
+ * verdicts without a later release.
+ */
+export function pendingHolds(events, recipientId) {
+    const open = new Map();
+    for (const event of events) {
+        if (event.type !== 'room/report-gate' || event.data.memberId !== recipientId)
+            continue;
+        if (event.data.verdict === 'hold')
+            open.set(event.data.dispatchSeq, event.seq);
+        else if (event.data.verdict === 'release')
+            open.delete(event.data.dispatchSeq);
+    }
+    return [...open.keys()];
+}
+/**
+ * The held reports of a member as one prompt section (their envelopes and
+ * texts), or undefined when nothing is held — what a turn the room did not
+ * start (a human waking the agent directly) must still carry.
+ */
+export function heldReportsText(events, recipientId) {
+    const held = (replay(events).deliveries ?? []).filter(row => row.memberId === recipientId && row.status === 'held');
+    if (held.length === 0)
+        return undefined;
+    return {
+        text: held.map(row => `${envelopeLine(events, row.dispatchSeq) ?? ''}\n${row.text}`.trim()).join('\n\n'),
+        seqs: held.map(row => row.dispatchSeq),
+    };
+}
+/** The text of the last assistant message after `afterSeq` ('' when none). */
+function lastAssistantText(events, afterSeq) {
+    const reply = events.filter(event => event.seq > afterSeq && event.type === 'assistant/message').at(-1);
+    return reply?.type === 'assistant/message'
+        ? reply.data.message.content.flatMap(block => block.type === 'text' ? [block.text] : []).join('\n')
+        : '';
+}
+/** Who a delivery of this dispatch reports to (the coordinator for plan work), if anyone. */
+function reportRecipient(events, dispatchSeq) {
+    const source = events.find(event => event.seq === dispatchSeq);
+    if (source?.type !== 'room/dispatch' || source.data.replyTo === undefined)
+        return undefined;
+    const state = replay(events);
+    return source.data.plan === undefined
+        ? state.members.find(member => memberId(events, member) === source.data.replyTo)
+        : coordinatorMember(state, events);
 }
 /** The human-readable reason a run failed (Error message, else String()). */
 function faultMessage(error) {
@@ -131,6 +235,18 @@ export class DispatchEngine {
     queues = new Map();
     scheduled = new Set();
     inFlight = new Map();
+    /** room + recipient → the wake-anyway timer for its held reports. */
+    holdTimers = new Map();
+    /**
+     * room id → member ids whose FIRST start is in flight: the member has no
+     * child session id in the journal yet, but its process may already be
+     * asking the host for its mode tools (claude lists MCP tools at spawn).
+     */
+    freshStarts = new Map();
+    /** Members of this room whose first start is in flight (see {@link freshStarts}). */
+    startingMembers(roomId) {
+        return [...this.freshStarts.get(roomId) ?? []];
+    }
     /**
      * @param ctx - host context carrying the session store and agents registry.
      */
@@ -165,7 +281,12 @@ export class DispatchEngine {
                 return;
             this.scheduled.add(scopedId);
         }
-        const tail = this.queues.get(key) ?? Promise.resolve();
+        // A report to the room's own agent never waits behind that agent's
+        // running round: it joins the round (runMainAgent steers it in) — queued,
+        // it would wake a second turn once the first had already answered.
+        const source = options.dispatchSeq === undefined ? undefined : events.find(event => event.seq === options.dispatchSeq);
+        const joins = member.kind === 'main-agent' && source?.type === 'room/dispatch' && source.data.origin === 'report';
+        const tail = joins ? Promise.resolve() : this.queues.get(key) ?? Promise.resolve();
         let submitted;
         const submission = new Promise(resolve => { submitted = resolve; });
         const next = tail.then(() => this.run(room, memberName, text, { ...options, targetId }, submitted))
@@ -177,6 +298,8 @@ export class DispatchEngine {
                 this.scheduled.delete(`${room.id}:${deliveryId}`);
         });
         this.inFlight.set(next, key);
+        if (joins)
+            return;
         this.queues.set(key, submission);
         void submission.then(() => { if (this.queues.get(key) === submission)
             this.queues.delete(key); });
@@ -214,7 +337,7 @@ export class DispatchEngine {
         const events = room.snapshotEvents();
         const state = replay(events);
         for (const dispatch of events) {
-            if (dispatch.type !== 'room/dispatch' || dispatch.data.targetIds === undefined)
+            if (dispatch.type !== 'room/dispatch' || dispatch.data.targetIds === undefined || dispatch.data.held === true)
                 continue;
             for (const targetId of dispatch.data.targetIds) {
                 const id = `${dispatch.seq}:${targetId}`;
@@ -233,14 +356,19 @@ export class DispatchEngine {
                         const target = state.members.find(member => memberId(events, member) === targetId);
                         if (target !== undefined) {
                             const run = state.runs.find(run => run.member === target.name);
-                            if (run?.state === 'running' && (run.runId === undefined || run.runId === id))
-                                room.append('room/run-state', { member: target.name, state: 'failed', startedAt: run.startedAt, ...run.runId === undefined ? {} : { runId: run.runId }, error: 'Execution outcome is unknown after restart; reconcile before retrying' });
+                            if (run?.state === 'running' && (run.runId === undefined || run.runId === id)) {
+                                const childSessionId = runChildSessionId(room.id, target);
+                                room.append('room/run-state', { member: target.name, state: 'failed', startedAt: run.startedAt,
+                                    ...run.runId === undefined ? {} : { runId: run.runId },
+                                    ...childSessionId === undefined ? {} : { childSessionId },
+                                    error: 'Execution outcome is unknown after restart; reconcile before retrying' });
+                            }
                         }
                         await this.ctx.sessions.flush(room);
-                        await this.report(room, dispatch.seq, id, targetId, 'uncertain', 'Execution outcome is unknown after restart; reconcile before retrying');
+                        await this.reportOutcome(room, dispatch.seq, id, targetId, 'uncertain', 'Execution outcome is unknown after restart; reconcile before retrying');
                     }
                     else {
-                        await this.report(room, dispatch.seq, id, targetId, last.data.state, last.data.text ?? last.data.error ?? '');
+                        await this.reportOutcome(room, dispatch.seq, id, targetId, last.data.state, last.data.text ?? last.data.error ?? '');
                     }
                     continue;
                 }
@@ -249,6 +377,13 @@ export class DispatchEngine {
                     this.dispatch(room, target.name, dispatch.data.text, { dispatchSeq: dispatch.seq, targetId });
             }
         }
+        // recover() runs on every live access; only holds whose wake timer this
+        // process does not own (a restart lost it) are handed over now.
+        for (const member of state.members) {
+            const id = memberId(events, member);
+            if (!this.holdTimers.has(this.holdKey(room.id, id)) && pendingHolds(events, id).length > 0)
+                await this.releaseHeld(room, id, 'restart');
+        }
     }
     /** Execute one dispatch: run-state running → member turn → settle edges. */
     async run(room, memberName, text, options, submitted) {
@@ -265,6 +400,10 @@ export class DispatchEngine {
         memberName = member.name;
         const identity = memberId(room.snapshotEvents(), member);
         const deliveryId = options.dispatchSeq === undefined ? undefined : `${options.dispatchSeq}:${identity}`;
+        // Settled while it waited in the queue (a removal cancels queued work;
+        // an undo must not resurrect it).
+        if (deliveryId !== undefined && state.deliveries?.some(delivery => delivery.id === deliveryId && delivery.status !== 'queued'))
+            return;
         const runId = deliveryId ?? randomUUID();
         const cursor = previousCursor(room.snapshotEvents(), memberName, options.dispatchSeq ?? Number.MAX_SAFE_INTEGER);
         let startedAt;
@@ -274,9 +413,13 @@ export class DispatchEngine {
             startedAt = Date.now();
             if (deliveryId !== undefined)
                 room.append('room/delivery-state', { id: deliveryId, dispatchSeq: options.dispatchSeq, memberId: identity, state: 'running' });
-            memberName = replay(room.snapshotEvents()).members.find(entry => memberId(room.snapshotEvents(), entry) === identity)?.name ?? memberName;
+            // Re-read the roster: the captured member snapshot predates the child
+            // handle's publication (member-updated lands between admission and settle).
+            const current = replay(room.snapshotEvents()).members.find(entry => memberId(room.snapshotEvents(), entry) === identity);
+            memberName = current?.name ?? memberName;
+            const childSessionId = runChildSessionId(room.id, current ?? member);
             room.append('room/run-state', { member: memberName, state: 'running', startedAt, runId,
-                ...member.kind === 'main-agent' ? { childSessionId: room.id } : member.childSessionId === undefined ? {} : { childSessionId: member.childSessionId },
+                ...childSessionId === undefined ? {} : { childSessionId },
             });
             await this.hooks.admitted?.(room, options.dispatchSeq);
             await this.ctx.sessions.flush(room);
@@ -285,8 +428,10 @@ export class DispatchEngine {
         let outcome;
         try {
             outcome = member.kind === 'main-agent'
-                ? await this.runMainAgent(room, member, cursor, text, await admitted(), options.relayIds ?? [])
-                : await this.runCliMember(room, member, cursor, text, admitted, options.relayIds ?? [], submitted, runId);
+                ? await this.runMainAgent(room, member, cursor, text, await admitted(), options.relayIds ?? [], options.dispatchSeq)
+                : member.kind === 'native'
+                    ? await this.runNativeMember(room, member, cursor, text, admitted, options.relayIds ?? [], options.dispatchSeq, runId)
+                    : await this.runCliMember(room, member, cursor, text, admitted, options.relayIds ?? [], submitted, runId, options.dispatchSeq);
         }
         catch (error) {
             this.ctx.logger.warn(`room: dispatch to "${memberName}" failed: ${String(error)}`);
@@ -298,30 +443,102 @@ export class DispatchEngine {
             room.append('room/delivery-state', { id: deliveryId, dispatchSeq: options.dispatchSeq, memberId: identity, state: outcome.state,
                 ...outcome.text === undefined ? {} : { text: outcome.text }, ...outcome.error === undefined ? {} : { error: outcome.error } });
             await this.ctx.sessions.flush(room);
-            await this.report(room, options.dispatchSeq, deliveryId, identity, outcome.state, outcome.text ?? outcome.error ?? '');
+            await this.reportOutcome(room, options.dispatchSeq, deliveryId, identity, outcome.state, outcome.text ?? outcome.error ?? '');
         }
     }
-    async report(room, dispatchSeq, deliveryId, fromId, outcome, text) {
+    /**
+     * Report one delivery's outcome to whoever is waiting on it (the
+     * coordinator for plan work, else the dispatch's `replyTo`), at most once
+     * per delivery. Public so a removal can settle the waits it breaks.
+     */
+    /** Report-gate decisions per recipient, one at a time (see reportOutcome). */
+    gateQueues = new Map();
+    /**
+     * Gate one arrived report for the member waiting on it. Decisions for the
+     * same recipient run one at a time: a decision-model judgement takes a
+     * second or two, and a later report deciding meanwhile (the 「最后一个结果」
+     * rule) would hand over its batch without the one still being judged —
+     * which then got held behind a round that had already answered.
+     */
+    async reportOutcome(room, dispatchSeq, deliveryId, fromId, outcome, text) {
+        const source = room.snapshotEvents().find(event => event.seq === dispatchSeq);
+        const key = `${room.id} ${source?.type === 'room/dispatch' ? source.data.replyTo ?? '' : ''}`;
+        const next = (this.gateQueues.get(key) ?? Promise.resolve())
+            .catch(() => { })
+            .then(() => this.gateReport(room, dispatchSeq, deliveryId, fromId, outcome, text));
+        this.gateQueues.set(key, next);
+        void next.then(() => { if (this.gateQueues.get(key) === next)
+            this.gateQueues.delete(key); }, () => { if (this.gateQueues.get(key) === next)
+            this.gateQueues.delete(key); });
+        return next;
+    }
+    async gateReport(room, dispatchSeq, deliveryId, fromId, outcome, text) {
         const events = room.snapshotEvents();
         const source = events.find(event => event.seq === dispatchSeq);
-        if (source?.type !== 'room/dispatch' || source.data.origin !== 'coordinator' || source.data.replyTo === undefined)
+        if (source?.type !== 'room/dispatch' || (source.data.origin !== 'coordinator' && source.data.origin !== 'member') || source.data.replyTo === undefined)
             return;
         if (events.some(event => event.type === 'room/dispatch' && event.data.reportFor === deliveryId))
             return;
+        if (events.some(event => event.type === 'room/relay' && event.data.intent?.reportFor === deliveryId))
+            return;
         const state = replay(events);
         if (closedGoal(state, source.data.plan?.goalId))
             return;
         const recipient = source.data.plan === undefined ? state.members.find(member => memberId(events, member) === source.data.replyTo) : coordinatorMember(state, events);
-        const sender = state.members.find(member => memberId(events, member) === fromId);
         if (recipient === undefined)
             return;
-        const reportText = `Delegation ${deliveryId} (${sender?.name ?? fromId}) ${outcome}.\n${text.slice(0, 32000)}`;
-        const report = room.append('room/dispatch', { id: randomUUID(), origin: 'report', reportFor: deliveryId,
-            targets: [recipient.name], targetIds: [memberId(events, recipient)], text: reportText,
-            ...source.data.plan === undefined ? {} : { plan: { goalId: source.data.plan.goalId } } });
+        // A removed sender is no longer on the roster: read its last known name.
+        const senderName = state.members.find(member => memberId(events, member) === fromId)?.name
+            ?? events.reduce((name, event) => event.type === 'room/member-added' && event.data.id === fromId ? event.data.name : name, undefined);
+        // The envelope (`【#m12 的回报 · 来自 ada · 完成】`) carries who and how;
+        // the text is the member's own conclusion.
+        const reportText = text.trim() === '' ? `（${outcome === 'done' ? '没有文字输出' : outcome}）` : text.slice(0, 32000);
+        const sourceTask = (state.deliveries ?? []).find(row => row.id === deliveryId)?.task;
+        const intent = { origin: 'report', hop: (source.data.hop ?? 1) + 1, reportFor: deliveryId,
+            ...sourceTask === undefined ? {} : { task: sourceTask },
+            ...source.data.plan === undefined ? {} : { plan: { goalId: source.data.plan.goalId } } };
+        // The gate decides WHEN the recipient gets it; plan work keeps its own cadence.
+        const recipientId = memberId(events, recipient);
+        const deliveries = state.deliveries ?? [];
+        const verdict = source.data.plan !== undefined
+            ? { hold: false, reason: 'plan' }
+            : await judgeReport(this.ctx, {
+                timing: state.settings?.reportTiming ?? 'judge',
+                threshold: state.settings?.reportThreshold ?? 0.5,
+                outcome,
+                outstanding: outstandingFor(deliveries, recipientId, deliveryId).length,
+                state: () => gateState(room.snapshotEvents(), recipient, [
+                    ...deliveries.filter(row => row.memberId === recipientId && row.origin === 'report' && pendingHolds(events, recipientId).includes(row.dispatchSeq))
+                        .map(row => ({ from: '', outcome: '', text: row.text })),
+                    { from: senderName ?? fromId, outcome, text: reportText },
+                ], Date.now()),
+            });
+        // The judgement awaited: a concurrent path may have reported meanwhile.
+        if (room.snapshotEvents().some(event => event.type === 'room/dispatch' && event.data.reportFor === deliveryId))
+            return;
+        // Every timing decision the room weighed is recorded (the timeline row,
+        // Context Lens); the each-setting and plan cadence decide nothing.
+        if (verdict.reason !== 'setting' && verdict.reason !== 'plan') {
+            room.append('room/decision', decisionRecord('report-timing', {
+                outcome: verdict.hold ? 'later' : 'now',
+                ...verdict.reason === 'model' ? {} : { rule: verdict.reason },
+                ...verdict.probability === undefined ? {} : { probability: verdict.probability },
+                ...verdict.call === undefined ? {} : { call: verdict.call },
+                about: { from: senderName ?? fromId, to: recipient.name },
+            }));
+        }
+        if (verdict.hold) {
+            await this.holdReport(room, recipient, reportText, intent, verdict);
+            return;
+        }
+        const sent = sendOrHold(room, { to: recipient, text: reportText, fromName: senderName ?? fromId, intent });
+        if (sent.delivered) {
+            room.append('room/report-gate', { dispatchSeq: sent.seq, memberId: recipientId, member: recipient.name, verdict: 'deliver', reason: verdict.reason,
+                ...verdict.probability === undefined ? {} : { probability: verdict.probability } });
+        }
         await this.ctx.sessions.flush(room);
-        if (this.hooks.allows?.(room, report.seq) !== false)
-            this.dispatch(room, recipient.name, reportText, { dispatchSeq: report.seq, targetId: memberId(events, recipient) });
+        if (sent.delivered && this.hooks.allows?.(room, sent.seq) !== false)
+            this.dispatch(room, recipient.name, reportText, { dispatchSeq: sent.seq, targetId: memberId(events, recipient) });
     }
     /**
      * Mark the relays this run delivered as sent. Delivery = the member's own
@@ -329,6 +546,85 @@ export class DispatchEngine {
      * started): the text lives in the member's private context from then on,
      * so a later run failure cannot un-deliver it.
      */
+    /**
+     * A round of this member started: every report held for it is now in its
+     * context — carried by this prompt (`seqs`) or already in its inbox — so
+     * close those holds and drop the member's wake timer.
+     */
+    async markHeldReleased(room, member, seqs) {
+        const events = room.snapshotEvents();
+        const id = memberId(events, member);
+        for (const seq of seqs)
+            room.append('room/delivery-state', { id: `${seq}:${id}`, dispatchSeq: seq, memberId: id, state: 'done', text: 'carried' });
+        const open = pendingHolds(events, id);
+        for (const seq of new Set([...seqs, ...open]))
+            room.append('room/report-gate', { dispatchSeq: seq, memberId: id, member: member.name, verdict: 'release', reason: 'carried' });
+        this.clearHoldTimer(room.id, id);
+        if (seqs.length > 0 || open.length > 0)
+            await this.ctx.sessions.flush(room);
+    }
+    holdKey(roomId, recipientId) { return `${roomId} ${recipientId}`; }
+    clearHoldTimer(roomId, recipientId) {
+        const key = this.holdKey(roomId, recipientId);
+        const timer = this.holdTimers.get(key);
+        if (timer !== undefined)
+            clearTimeout(timer);
+        this.holdTimers.delete(key);
+    }
+    /**
+     * Keep a report for later: journal it as a held dispatch and arm the
+     * wake-anyway timer. It is NOT pushed into an agent inbox: the host runs
+     * one turn per queued inbox message, so held reports would each wake their
+     * own turn. They ride the recipient's next round instead — the room's own
+     * prompt, or (a human waking a native agent directly) the turn's first step
+     * through {@link heldReportsMessage}.
+     */
+    async holdReport(room, recipient, text, intent, verdict) {
+        const events = room.snapshotEvents();
+        const recipientId = memberId(events, recipient);
+        const dispatch = room.append('room/dispatch', {
+            id: randomUUID(), origin: 'report', targets: [recipient.name], targetIds: [recipientId], text, held: true,
+            hop: intent.hop, ...intent.task === undefined ? {} : { task: intent.task }, ...intent.reportFor === undefined ? {} : { reportFor: intent.reportFor },
+            ...intent.plan === undefined ? {} : { plan: intent.plan },
+        });
+        room.append('room/report-gate', { dispatchSeq: dispatch.seq, memberId: recipientId, member: recipient.name, verdict: 'hold', reason: verdict.reason,
+            ...verdict.probability === undefined ? {} : { probability: verdict.probability } });
+        // Armed before the flush yields: a concurrent recover() must see this
+        // process owns the hold.
+        const key = this.holdKey(room.id, recipientId);
+        if (!this.holdTimers.has(key)) {
+            const timer = setTimeout(() => {
+                this.holdTimers.delete(key);
+                void this.releaseHeld(room, recipientId, 'timeout').catch(error => this.ctx.logger.warn(`room: held report release failed: ${String(error)}`));
+            }, (replay(events).settings?.reportWaitMinutes ?? 3) * 60_000);
+            timer.unref?.();
+            this.holdTimers.set(key, timer);
+        }
+        await this.ctx.sessions.flush(room);
+    }
+    /**
+     * Wake a member for the reports held for it (the hold timeout, a human's
+     * 「现在交给」, or a restart). One short release round: an inbox already
+     * holds the reports; a CLI member gets them carried by the round's prompt.
+     * A no-op when nothing is held any more.
+     * @returns whether a release round was dispatched.
+     */
+    async releaseHeld(room, recipientId, reason) {
+        this.clearHoldTimer(room.id, recipientId);
+        const events = room.snapshotEvents();
+        const open = pendingHolds(events, recipientId);
+        const recipient = replay(events).members.find(member => memberId(events, member) === recipientId);
+        if (open.length === 0 || recipient === undefined)
+            return false;
+        const ids = open.map(seq => `#${messageId(seq)}`).join('、');
+        const text = `（以上 ${open.length} 条回报一直等着交给你：${ids}${reason === 'timeout' ? '，已经等了一段时间' : ''}。用户也已在房间里看到，不要复述。）`;
+        const releaseTask = replay(events).deliveries?.find(row => row.dispatchSeq === open[0] && row.memberId === recipientId)?.task;
+        const release = room.append('room/dispatch', { id: randomUUID(), origin: 'report', targets: [recipient.name], targetIds: [recipientId], text, releases: open, hop: 1,
+            ...releaseTask === undefined ? {} : { task: releaseTask } });
+        await this.ctx.sessions.flush(room);
+        this.dispatch(room, recipient.name, text, { dispatchSeq: release.seq, targetId: recipientId });
+        return true;
+    }
     async markSent(room, relays) {
         if (relays.length === 0)
             return;
@@ -337,29 +633,104 @@ export class DispatchEngine {
         await this.ctx.sessions.flush(room);
     }
     /** Main-agent member turn: a producer-sourced followup on the room's own agent. */
-    async runMainAgent(room, member, cursor, text, _startedAt, relayIds) {
+    async runMainAgent(room, member, cursor, text, _startedAt, relayIds, dispatchSeq) {
         const agent = this.ctx.agents.get(room.id);
         if (agent === undefined) {
             // Fail loud: the room's own agent is not live, the message goes nowhere.
             return { state: 'failed', error: 'the room session has no live agent' };
         }
-        const { prompt, carried } = assemblePrompt(room, member, cursor, text, relayIds);
-        agent.followup(createUserMessage({
-            content: [{ type: 'text', text: prompt }],
-            source: roomSource(),
-        }));
+        const { prompt, carried, heldCarried } = assemblePrompt(room, member, cursor, text, relayIds, dispatchSeq);
+        const before = room.snapshotEvents().at(-1)?.seq ?? -1;
+        const message = createUserMessage({ content: [{ type: 'text', text: prompt }], source: roomSource() });
+        // A report reaching an agent mid-turn joins that turn at its next step:
+        // as its own turn it would make the agent answer a second time, after
+        // the turn that was already waiting for it.
+        const source = dispatchSeq === undefined ? undefined : room.snapshotEvents().find(event => event.seq === dispatchSeq);
+        const report = source?.type === 'room/dispatch' && source.data.origin === 'report';
+        const steerable = agent;
+        if (report && steerable.status === 'running' && typeof steerable.steer === 'function')
+            steerable.steer(message);
+        else
+            agent.followup(message);
+        await this.markHeldReleased(room, member, heldCarried);
         await this.markSent(room, [
             ...carried,
             ...replay(room.snapshotEvents()).relays.filter(relay => relayIds.includes(relay.id)),
         ]);
-        // Phase-1 simplicity: the followup's own turn converging to idle IS the
-        // run; the main agent's reply is its ordinary assistant speech (no
-        // room/speech projection — speech mirrors CLI members only).
+        // The followup's own turn converging to idle IS the run; the main agent's
+        // reply is its ordinary assistant speech (no room/speech projection —
+        // speech mirrors CLI members only). Its last assistant text is the
+        // outcome a waiting sender's report quotes.
         await agent.whenIdle();
-        return { state: 'done' };
+        const output = lastAssistantText(room.snapshotEvents(), before);
+        return { state: 'done', ...output === '' ? {} : { text: output } };
+    }
+    /**
+     * The native member's agent: live, resumed from its session after a
+     * restart, or created on its first round — a child session + agent in this
+     * host process (owned by the room's agent when live), composing the
+     * member's preset at creation. The handle is journaled before any prompt.
+     */
+    async nativeAgent(room, member) {
+        if (member.childSessionId !== undefined) {
+            const live = this.ctx.agents.get(member.childSessionId);
+            if (live !== undefined)
+                return live;
+            const composition = await composeRoomAgent(this.ctx, member.preset);
+            const handle = await this.ctx.agents.resume({
+                resumeSessionId: member.childSessionId,
+                ...composition.setup === undefined ? {} : { setup: composition.setup },
+            });
+            return handle.agent;
+        }
+        const composition = await composeRoomAgent(this.ctx, member.preset);
+        const parent = this.ctx.agents.get(room.id);
+        const sessionId = SessionId(randomUUID());
+        const cwd = member.cwd ?? room.header.cwd;
+        const handle = await this.ctx.agents.create({
+            sessionId,
+            ...parent === undefined ? {} : { parentAgent: parent },
+            meta: {
+                parentSession: room.id, origin: 'subagent', delegationDepth: (room.header.delegationDepth ?? 0) + 1,
+                ...cwd === undefined ? {} : { cwd },
+                ...composition.agentPreset === undefined ? {} : { agentPreset: composition.agentPreset },
+            },
+            ...composition.setup === undefined ? {} : { setup: composition.setup },
+        });
+        room.append('room/member-updated', { name: replay(room.snapshotEvents()).members.find(entry => entry.id === member.id)?.name ?? member.name, childSessionId: sessionId });
+        await this.ctx.sessions.flush(room);
+        return handle.agent;
+    }
+    /**
+     * Native member turn: a room-sourced followup on the member's own agent,
+     * mirrored into the room as speech like a CLI member's reply.
+     */
+    async runNativeMember(room, member, cursor, text, admitted, relayIds, dispatchSeq, runId) {
+        const agent = await this.nativeAgent(room, member);
+        const startedAt = await admitted();
+        const { prompt, carried, heldCarried } = assemblePrompt(room, member, cursor, text, relayIds, dispatchSeq);
+        const before = agent.session.snapshotEvents().at(-1)?.seq ?? -1;
+        agent.followup(createUserMessage({ content: [{ type: 'text', text: prompt }], source: roomSource() }));
+        await this.markHeldReleased(room, member, heldCarried);
+        await this.markSent(room, [
+            ...carried,
+            ...replay(room.snapshotEvents()).relays.filter(relay => relayIds.includes(relay.id)),
+        ]);
+        await agent.whenIdle();
+        const output = lastAssistantText(agent.session.snapshotEvents(), before);
+        const reportedTo = dispatchSeq === undefined ? undefined : reportRecipient(room.snapshotEvents(), dispatchSeq)?.name;
+        room.append('room/speech', {
+            member: replay(room.snapshotEvents()).members.find(entry => entry.id === member.id)?.name ?? member.name,
+            text: output, childSessionId: agent.session.id, durationMs: Date.now() - startedAt,
+            ...runId === undefined ? {} : { runId },
+            ...lastAssistantMessageId(agent.session, before) === undefined ? {} : { messageId: lastAssistantMessageId(agent.session, before) },
+            ...reportedTo === undefined ? {} : { reportedTo },
+        });
+        await this.ctx.sessions.flush(room);
+        return { state: 'done', ...output === '' ? {} : { text: output } };
     }
     /** CLI member turn: facade start (first round) or resume, then the speech mirror. */
-    async runCliMember(room, member, cursor, text, admitted, relayIds, submitted, runId) {
+    async runCliMember(room, member, cursor, text, admitted, relayIds, submitted, runId, dispatchSeq) {
         const facade = probeLocalAgent(this.ctx);
         if (facade === undefined) {
             this.ctx.logger.warn(`room: cannot dispatch to "${member.name}": local-agent facade unavailable`);
@@ -379,32 +750,59 @@ export class DispatchEngine {
                 const previous = room.snapshotEvents().filter(row => row.type === 'room/run-state' && row.data.runId === runId).at(-1);
                 if (previous?.type !== 'room/run-state')
                     return;
-                const total = event.usage?.totalTokens ?? (event.usage === undefined ? undefined : event.usage.inputTokens + event.usage.outputTokens);
+                // TokenUsage counts are disjoint: the billed total is the sum of the
+                // buckets, cache reads and writes included. A provider's own
+                // totalTokens may leave the cache out (claude reports input+output),
+                // so the buckets win whenever they are there.
+                const total = event.usage === undefined ? undefined
+                    : event.usage.inputTokens + (event.usage.cacheReadTokens ?? 0) + (event.usage.cacheWriteTokens ?? 0) + event.usage.outputTokens;
                 room.append('room/execution-metadata', { runId,
                     ...event.observedModel === undefined ? {} : { model: event.observedModel },
                     ...event.observedEffort === undefined ? {} : { effort: event.observedEffort },
                     ...total === undefined || !Number.isFinite(total) || total < 0 ? {} : { tokens: total },
+                    ...event.usage === undefined ? {} : { usage: {
+                            inputTokens: event.usage.inputTokens, outputTokens: event.usage.outputTokens,
+                            ...event.usage.cacheReadTokens === undefined ? {} : { cacheReadTokens: event.usage.cacheReadTokens },
+                            ...event.usage.cacheWriteTokens === undefined ? {} : { cacheWriteTokens: event.usage.cacheWriteTokens },
+                            ...event.usage.reasoningTokens === undefined ? {} : { reasoningTokens: event.usage.reasoningTokens },
+                        } },
                 });
                 void this.ctx.sessions.flush(room).catch(error => this.ctx.logger.warn(`room: execution metadata flush failed: ${String(error)}`));
             },
         };
         if (!controlled)
             startedAt = await admitted();
-        const { prompt, carried } = assemblePrompt(room, member, cursor, text, relayIds);
+        const { prompt, carried, heldCarried } = assemblePrompt(room, member, cursor, text, relayIds, dispatchSeq);
         const prepared = member.childSessionId !== undefined && facade.isPreparedMember?.(member.childSessionId) === true;
         const pendingRun = prepared
-            ? facade.start(room.id, provider, [{ type: 'text', text: prompt }], { preparedMemberId: member.childSessionId, ...admission })
+            ? facade.start(room.id, provider, [{ type: 'text', text: prompt }], { preparedMemberId: member.childSessionId, label: member.name, ...admission })
             : member.childSessionId === undefined
                 // The invite-time model lands as the delegation's own model: the facade
                 // records it with the first start and every later resume re-requests it
-                // (providers bind it at spawn for exec and live alike).
-                ? facade.start(room.id, provider, [{ type: 'text', text: prompt }], { ...admission, ...member.model === undefined ? {} : { model: member.model }, ...member.cwd === undefined ? {} : { cwd: member.cwd } })
+                // (providers bind it at spawn for exec and live alike). The invite-time
+                // effort rides the same channel.
+                ? facade.start(room.id, provider, [{ type: 'text', text: prompt }], 
+                // The member's name labels its child session in the host's subagent list.
+                { ...admission, label: member.name, ...member.model === undefined ? {} : { model: member.model }, ...member.effort === undefined ? {} : { effort: member.effort }, ...member.cwd === undefined ? {} : { cwd: member.cwd } })
                 : facade.resume(room.id, provider, member.childSessionId, [{ type: 'text', text: prompt }], { ...admission, ...member.cwd === undefined ? {} : { cwd: member.cwd } });
         // Existing members can enter core's queue immediately. A fresh/prepared
         // identity must publish its first handle before the next submission resumes it.
         if (controlled && member.childSessionId !== undefined && !prepared)
             submitted();
-        const run = await pendingRun;
+        const fresh = !prepared && member.childSessionId === undefined;
+        const freshId = memberId(room.snapshotEvents(), member);
+        if (fresh) {
+            const starting = this.freshStarts.get(room.id) ?? new Set();
+            this.freshStarts.set(room.id, starting.add(freshId));
+        }
+        const run = await pendingRun.finally(() => {
+            if (!fresh)
+                return;
+            const starting = this.freshStarts.get(room.id);
+            starting?.delete(freshId);
+            if (starting?.size === 0)
+                this.freshStarts.delete(room.id);
+        });
         if (startedAt === undefined) {
             await run.dispose();
             throw new Error('Provider published a room run without admission');
@@ -418,6 +816,7 @@ export class DispatchEngine {
                 ...carried,
                 ...replay(room.snapshotEvents()).relays.filter(relay => relayIds.includes(relay.id)),
             ]);
+            await this.markHeldReleased(room, member, heldCarried);
             await this.ctx.sessions.flush(room);
         }
         catch (error) {
@@ -432,32 +831,22 @@ export class DispatchEngine {
         const output = runOutputText(result.output);
         const interrupted = result.stopReason === 'completed' ? undefined
             : result.stopReason === 'aborted' ? 'cancelled' : 'failed';
+        const reportedTo = dispatchSeq === undefined ? undefined : reportRecipient(room.snapshotEvents(), dispatchSeq)?.name;
+        // The member's own closing message: per-message tools address it in its session.
+        const closingMessageId = lastAssistantMessageId(this.ctx.sessions.get(run.id));
         const speech = output !== '' || interrupted === undefined ? room.append('room/speech', {
             member: replay(room.snapshotEvents()).members.find(entry => entry.id === member.id)?.name ?? member.name,
             text: output,
             childSessionId: run.id,
+            runId,
+            ...closingMessageId === undefined ? {} : { messageId: closingMessageId },
             durationMs: Date.now() - startedAt,
             ...interrupted === undefined ? {} : { interrupted },
+            ...reportedTo === undefined ? {} : { reportedTo },
         }) : undefined;
         if (speech !== undefined)
             await this.ctx.sessions.flush(room);
         if (result.stopReason === 'completed') {
-            // The fallback notification channel: a reply whose trailing own line is
-            // `@name <content>` (the roster-taught format) becomes a pending relay
-            // at the gate — the same shape the family bridge's member_message
-            // produces, so downstream handling is identical.
-            const directive = parseRelayDirective(runOutputText(result.output));
-            const roster = replay(room.snapshotEvents()).members;
-            if (directive !== undefined && directive.to !== member.name
-                && roster.some(entry => entry.name === directive.to)) {
-                room.append('room/relay', {
-                    id: randomUUID(),
-                    from: member.name,
-                    to: directive.to,
-                    content: directive.content,
-                    provenance: { kind: 'speech-fallback', speechSeq: speech.seq },
-                });
-            }
             await this.ctx.sessions.flush(room);
             return { state: 'done', text: runOutputText(result.output) };
         }
@@ -468,23 +857,23 @@ export class DispatchEngine {
             return { state: 'failed', text: output, error: `the member run ended with stopReason "${result.stopReason}"` };
         }
     }
-    /** Settle only this execution and its own task rows, preserving newer runs. */
+    /** Settle only this execution, preserving newer runs. */
     async settle(room, member, runId, startedAt, outcome) {
         const events = room.snapshotEvents();
-        const memberName = replay(events).members.find(entry => memberId(events, entry) === memberId(events, member))?.name ?? member.name;
+        const currentMember = replay(events).members.find(entry => memberId(events, entry) === memberId(events, member));
+        const memberName = currentMember?.name ?? member.name;
         const terminal = events.find(event => event.type === 'room/run-state' && event.data.runId === runId && event.data.state !== 'running');
         if (terminal?.type === 'room/run-state' && terminal.data.state !== 'running') {
             return { ...outcome, state: terminal.data.state, ...terminal.data.error === undefined ? {} : { error: terminal.data.error } };
         }
+        const childSessionId = runChildSessionId(room.id, currentMember ?? member);
+        const childTurn = runChildTurn(childSessionId === undefined ? undefined : this.ctx.sessions.get(childSessionId));
         room.append('room/run-state', {
             member: memberName, runId, state: outcome.state, startedAt, elapsedMs: Date.now() - startedAt,
+            ...childSessionId === undefined ? {} : { childSessionId },
+            ...childTurn === undefined ? {} : { childTurn },
             ...outcome.error === undefined ? {} : { error: outcome.error },
         });
-        for (const task of replay(room.snapshotEvents()).tasks) {
-            if (task.member === memberName && task.status === 'in_progress' && task.deliveryId === runId) {
-                room.append('room/task-updated', { id: task.id, status: outcome.state });
-            }
-        }
         await this.ctx.sessions.flush(room);
         return outcome;
     }