dsh-activity-pane 0.7.0 → 0.9.0

package/src/core.mjs

@@ -435,6 +435,23 @@ function chatNodeAt(nodes, key) {
 	}
 }
 
+/** 子代理模型读取的触发信号（R-01-012/AC-17）：快照最新一个助手节点已定案
+ *  （status === "settled"，即其 assistant/message 事件已落宿主日志，尾页读取必命中）
+ *  时为 true。只检查最新一个助手节点——它随流式推送翻转为 settled 的那一刻即产生
+ *  触发，尾扫即停、近 O(1)，完全挂在既有订阅推送上（R-02-004）；工具密集期 4 行折叠窗口
+ *  可能不含助手行，故不看折叠时间线而直接读快照。流式未定案/中断/无快照为 false。 */
+export function chatLatestAssistantSettled(snapshot) {
+	const chat = snapshot?.chat;
+	const order = Array.isArray(chat?.order) ? chat.order : [];
+	const nodes = chat?.nodes;
+	for (let i = order.length - 1; i >= 0; i -= 1) {
+		const node = chatNodeAt(nodes, order[i]);
+		if (!isRecord(node) || node.visibility === "hidden" || node.kind !== "assistant-step") continue;
+		return isRecord(node.data) && node.data.status === "settled";
+	}
+	return false;
+}
+
 /** 尾部反向收集原始工作项（不含 live 合并），取够 want 个可转换项或耗尽 order 即停。
  *  continueToUser：取够后以廉价结构检查（isUserChatNode：非 hidden 的 user/steering 且含非空文本块）继续前走至最近一个未收集的用户节点（含
  *  steering），命中才转换并入队首——供指令锚行派生（R-01-012/AC-12），不为找锚做全序转换。 */
@@ -813,12 +830,54 @@ export function foldedConversationTimeline(snapshot, limit = 4, cwd = "", descen
 	return [];
 }
 
+/** user/message 非用户 source 的 provenance 投影（对齐宿主 dsh-client-ui-chat
+ *  contextProvenance）：recall = 跨会话召回，其余为注入；label 取各 source 形态的
+ *  稳定标识，未知 kind 直接以 kind 呈现。 */
+function contextProvenanceOf(source) {
+	if (!isRecord(source)) return { role: "inject", label: null };
+	const kind = typeof source.kind === "string" ? source.kind : null;
+	if (kind === null) return { role: "inject", label: null };
+	if (kind === "session-reference") return { role: "recall", label: joinedSourceLabels(source.references, "label") ?? kind };
+	if (kind === "agent-instructions") return { role: "inject", label: joinedSourceLabels(source.changes, "path") ?? kind };
+	if (kind === "plugin") return { role: "inject", label: typeof source.plugin === "string" ? source.plugin : kind };
+	if (kind === "skill-invocation") return { role: "inject", label: typeof source.name === "string" ? source.name : kind };
+	return { role: "inject", label: kind };
+}
+
+/** source 数组成员的字段去重收集（首见顺序），逗号拼接为单行标签。 */
+function joinedSourceLabels(list, field) {
+	if (!Array.isArray(list)) return null;
+	const seen = [];
+	for (const entry of list) {
+		const value = isRecord(entry) && typeof entry[field] === "string" ? entry[field] : null;
+		if (value !== null && !seen.includes(value)) seen.push(value);
+	}
+	return seen.length > 0 ? seen.join(", ") : null;
+}
+
 function timelineItemFromEvent(entry, cwd = "") {
 	const event = isRecord(entry?.event) ? entry.event : entry;
 	const data = isRecord(event?.data) ? event.data : {};
 	if (!event || typeof event.type !== "string") return null;
-	if (event.type === "user/message" && data.source?.kind === "user") {
-		return { id: `user:${event.seq}`, kind: "user", icon: "user", label: "用户", text: contentText(data.content), detail: null, status: "done" };
+	if (event.type === "user/message") {
+		if (data.source?.kind === "user") {
+			return { id: `user:${event.seq}`, kind: "user", icon: "user", label: "用户", text: contentText(data.content), detail: null, status: "done" };
+		}
+		// V3 log 路径的注入上下文行：非用户 source 的 user/message 即宿主 ContextMessageNode
+		// （0.1.5 无独立 context 事件），镜像原生 ContextInjectionRow 的角色文案。
+		const text = contentText(data.content);
+		if (text === "") return null;
+		const provenance = contextProvenanceOf(data.source);
+		return {
+			id: `context:${event.seq}`,
+			kind: "context",
+			icon: "context",
+			label: provenance.role === "recall" ? "跨会话召回" : "上下文注入",
+			text,
+			summary: provenance.label ?? "",
+			detail: null,
+			status: "done",
+		};
 	}
 	if (event.type === "assistant/message") {
 		const text = contentText(data.message?.content);
@@ -860,20 +919,15 @@ function historyToolResultRoot(data, resultView, callInfo = null) {
 	};
 }
 
-/** 判断 session window 是否尚未 hydrate，需用 native history 补齐。 */
-export function needsHistorySnapshot(snapshot) {
-	return !snapshot || !Array.isArray(snapshot.chat?.order) || snapshot.chat.order.length === 0;
-}
-
 /** 冷会话 history 回溯深翻：自尾页起按 beforeSeq 向前翻页，直至命中最近一条用户消息
- *  （messagePreviews 的 userPreview 非空，R-01-013/AC-03）、或翻尽
- *  （hasMore=false/无更多事件/业务错误 null）；requireOpenTurnStart 为 true 时
- *  （运行会话开放回合起点兜底，R-01-009/AC-06）命中用户消息后开放回合起点未命中
- *  仍继续深翻直至起点命中或翻尽。maxPages 仅作显式护栏（默认 Infinity 即不设页数
- *  上限——用户消息必然存在于会话最早段，翻尽必终止，无需预置页数界）。fetchPage
- *  (beforeSeq) 注入实际读取（返回 `{events, hasMore}` 或 null），便于纯函数单测；
- *  中途异常保留已得事件并以 error 返回。返回 `{ events, error }`（events 按时间
- *  正序，新页在后）。 */
+ * （messagePreviews 的 userPreview 非空，R-01-013/AC-03）、或翻尽
+ * （hasMore=false/无更多事件/业务错误 null）；requireOpenTurnStart 为 true 时
+ * （运行会话开放回合起点兜底，R-01-009/AC-06）命中用户消息后开放回合起点未命中
+ * 仍继续深翻直至起点命中或翻尽。maxPages 仅作显式护栏（默认 Infinity 即不设页数
+ * 上限——用户消息必然存在于会话最早段，翻尽必终止，无需预置页数界）。fetchPage
+ * (beforeSeq) 注入实际读取（返回 `{events, hasMore}` 或 null），便于纯函数单测；
+ * 中途异常保留已得事件并以 error 返回。返回 `{ events, error }`（events 按时间
+ * 正序，新页在后）。 */
 export async function pagedHistoryEvents({ fetchPage, maxPages = Infinity, requireOpenTurnStart = false }) {
 	const allEvents = [];
 	let beforeSeq;
@@ -902,17 +956,45 @@ export async function pagedHistoryEvents({ fetchPage, maxPages = Infinity, requi
 	return { events: allEvents, error };
 }
 
-/** 冷会话 history 的扁平工作项映射：供没有 ChatSnapshot 的活动/历史会话折叠分组使用。
- *  native `sessions.history` 响应只含 `{events, hasMore, projections?}`（in-flight
- *  partial 以 chunk 事件携带，不做逐 chunk 折叠），故只从事件流取尾部工作项。
+/** V3 log 窗口的扁平工作项映射：供没有 ChatSnapshot 的活动/历史会话折叠分组使用。
+ *  eventSource 快照含 type === "transient" 的 `assistant/live-chunk` 条目（agent-stream
+ *  增量帧，seq 为插值小数，仅存在于流式期间）：按 attemptId 原位累积为单个 running
+ *  assistant 行（对齐快照路径 mergeLiveItems 的 partial 行语义）；回合落定后 transient
+ *  条目随 attempt 出窗，durable assistant/message 自然接管。tool-call-delta 不折叠——
+ *  tool/call 以 durable 事件落定后经既有 call/result 配对路径呈现。
  *  tool/result 落定同 callId 的 call 项（原位替换，name/arguments/callView 由 call 事件补齐）：
  *  history 是冻结过去，call 事件单独留存会成为永久 running 幽灵行（R-01-016/AC-01）。 */
 export function conversationTimelineFromHistory(history, limit = 4, cwd = "") {
 	const items = [];
 	const inflightCalls = new Map(); // callId → { index, data, callView }：等待结果落定的 tool/call 事件
+	const liveAttempts = new Map(); // attemptId → { index, text, reasoning }：流式期间累积的 live 行
 	for (const entry of Array.isArray(history) ? history : []) {
 		const event = eventOf(entry);
 		const data = isRecord(event?.data) ? event.data : {};
+		if (event?.type === "assistant/live-chunk") {
+			const attemptId = typeof data.attemptId === "string" ? data.attemptId : "";
+			const text = typeof data.chunk?.text === "string" ? data.chunk.text : "";
+			if (attemptId === "" || text === "" || !isRecord(data.chunk)) continue;
+			const attempt = liveAttempts.get(attemptId) ?? (() => {
+				const created = { index: items.length, text: "", reasoning: "" };
+				liveAttempts.set(attemptId, created);
+				items.push({ id: `live:${attemptId}`, kind: "assistant", icon: "assistant", text: "", detail: null, status: "running", live: true });
+				return created;
+			})();
+			if (data.chunk.type === "reasoning-delta") attempt.reasoning += text;
+			else if (data.chunk.type === "text-delta") attempt.text += text;
+			else continue;
+			items[attempt.index] = {
+				...items[attempt.index],
+				text: attempt.text,
+				detail: attempt.reasoning || null,
+				// 镜像原生 ReasoningRow：流式思考显示尾部最新行，避免与已定案首行摘要漂移。
+				summary: attempt.reasoning ? latestLineOf(attempt.reasoning) : attempt.text,
+				status: "running",
+				live: true,
+			};
+			continue;
+		}
 		if (event?.type === "tool/result") {
 			const callId = toolResultCallId(data);
 			const pending = callId !== undefined ? inflightCalls.get(callId) : undefined;
@@ -942,12 +1024,15 @@ export function conversationTimelineFromHistory(history, limit = 4, cwd = "") {
 
 /** 冷 history 折叠分组时间线（R-01-017、R-01-012/AC-12～AC-15）：页内全部事件映射折叠后
  *  套用与快照路径同一窗口/锚行选择（selectTimelineRows），最近用户消息滚动触顶后停留为
- *  首行锚行。 */
-export function foldedHistoryTimeline(history, limit = 4, cwd = "") {
+ *  首行锚行。settleIdle：阻塞等待呈现（pendingText 存在）下折叠前把残留 running 行落定，
+ *  组标题/状态由已定案成员派生（「运行了命令」而非「正在运行」蓝闪），与快照路径的
+ *  settleWhenIdle 前置语义一致。 */
+export function foldedHistoryTimeline(history, limit = 4, cwd = "", settleIdle = false) {
 	const max = Math.max(0, limit);
 	if (max === 0) return [];
 	const items = conversationTimelineFromHistory(history, Number.MAX_SAFE_INTEGER, cwd);
-	return selectTimelineRows(foldWorkGroups(items, Number.MAX_SAFE_INTEGER), max);
+	const settled = settleIdle ? settleWhenIdle(items, true) : items;
+	return selectTimelineRows(foldWorkGroups(settled, Number.MAX_SAFE_INTEGER), max);
 }
 
 /** history 指令锚行提取（R-01-012/AC-12 快照窗口外兜底）：尾部反向取最近一条非空文本的
@@ -965,14 +1050,6 @@ export function historyInstructionAnchor(history) {
 }
 
 
-/** 开放回合起点缺口判定（R-01-009/AC-06 冷窗口兜底触发口径）：快照就绪、宿主判定运行中、
- *  轮内订阅已建立，但快照 turnTimings 无开放回合起点（liveStartTime 为 null）——超长回合
- *  的 turn/start 在尾页窗口之外。等待/空闲会话（非运行或无 liveness 记录）不算缺口，
- *  不触发 history 补读。 */
-export function openTurnStartMissing({ snapshotReady = false, running = false, hasLiveness = false, liveStartTime = null } = {}) {
-	return snapshotReady === true && running === true && hasLiveness === true && liveStartTime == null;
-}
-
 /** 开放回合起点兜底提取（R-01-009/AC-06）：history 事件尾部反向扫描，最近一条边界事件
  *  为 turn/start 即存在开放回合、返回其时刻；为 turn/end 则无开放回合返回 null。
  *  minTurn：快照已知的最晚回合号——history 开放回合落后于此（拉取后已切换新回合）时
@@ -1045,6 +1122,64 @@ export function modelMetadata(models) {
 	};
 }
 
+/** 子代理模型溯源（R-01-012/AC-17）：从 history 事件流尾扫最近一条携带模型溯源的
+ *  `assistant/message` 事件，取 `message.source.model`。返回值 reasoning 恒为空串，
+ *  effort 由调用方以 `reasoningEffortFromHistoryEvents` 同页折叠；无命中（空事件、
+ *  无助手消息或溯源缺失）返回 null，调用方保持模型区空白、不以 preset 或母会话
+ *  模型冒充（R-01-012/AC-18）。 */
+export function modelFromHistoryEvents(history) {
+	const entries = Array.isArray(history) ? history : [];
+	for (let i = entries.length - 1; i >= 0; i -= 1) {
+		const event = eventOf(entries[i]);
+		if (event?.type !== "assistant/message") continue;
+		const source = isRecord(event.data?.message?.source) ? event.data.message.source : null;
+		if (source !== null && typeof source.model === "string" && source.model !== "") {
+			return { model: source.model, reasoning: "" };
+		}
+	}
+	return null;
+}
+
+/** 子代理 reasoning effort（R-01-012/AC-17）：history 尾扫最新一条 `request/header`
+ *  事件，取 `config.reasoningEffort`——宿主的会话选择即从该折叠读取。命中最新请求头
+ *  即停：更早请求头属已废弃纪元，即使声明过 effort 也不再回扫。最新请求头未声明
+ *  effort 或页内无请求头（超长子会话的 header 在日志开头、可能落在尾页窗口之外）
+ *  返回 null，调用方回落目录条目 `reasoning` 后保持空值（R-01-012/AC-18）。 */
+export function reasoningEffortFromHistoryEvents(history) {
+	const entries = Array.isArray(history) ? history : [];
+	for (let i = entries.length - 1; i >= 0; i -= 1) {
+		const event = eventOf(entries[i]);
+		if (event?.type !== "request/header") continue;
+		const config = isRecord(event.data?.header?.config) ? event.data.header.config : null;
+		if (config !== null && typeof config.reasoningEffort === "string" && config.reasoningEffort !== "") {
+			return config.reasoningEffort;
+		}
+		return null;
+	}
+	return null;
+}
+
+/** 模型目录分组的 modelId → {name, reasoning} 索引（R-01-012/AC-17）：溯源
+ *  `source.model` 是 provider 侧 id，显示名需经目录分组解析；同一部署的目录分组在
+ *  主/子会话间共享，条目 `reasoning` 是请求头 effort 不可得时的回退来源。畸形条目
+ *  跳过；目录缺失返回空索引，调用方回退显示原始溯源 id（R-01-012/AC-18）。 */
+export function catalogModelEntries(groups) {
+	const entries = {};
+	for (const group of Array.isArray(groups) ? groups : []) {
+		if (!isRecord(group)) continue;
+		for (const model of Array.isArray(group.models) ? group.models : []) {
+			if (!isRecord(model)) continue;
+			if (typeof model.id === "string" && model.id !== "" && typeof model.name === "string" && model.name !== "") {
+				entries[model.id] = {
+					name: model.name,
+					reasoning: typeof model.reasoning === "string" && model.reasoning !== "" ? model.reasoning : "",
+				};
+			}
+		}
+	}
+	return entries;
+}
+
 /** 只提供卡片底部所需的原始统计字段，不拼接当前动作文案。 */
 export function runtimeStats({ elapsedMs = null, outputTokens = null, rateTokS = null } = {}) {
 	return {
@@ -1187,36 +1322,6 @@ export function escapeCssString(value) {
 		.replace(/\0/g, "�");
 }
 
-/** 冷会话补充数据读取决策（单次渲染内是否发起 models/history 读取）。
- *  失败路径会写入空 model/history 使决策转为「不读」（可见期内不热重试）；
- *  详情与记账随可见性清理（pruneInvisibleEntries）一起移除后，决策自然恢复为「读取」。
- *  windowComplete（R-01-009/AC-06、R-01-012/AC-12 冷窗口兜底）：快照已就绪但窗口缺
- *  锚点数据（开放回合起点或可锚用户行在窗口外）时为 false——此时仍发起一次 history
- *  补读，供进度锚点与指令锚行兜底。previewFallbackNeeded 表示最近卡的快照预览
- *  不完整，同样补读一次 history（R-01-013/AC-03、AC-04）；durationFallbackNeeded 表示等待卡或最近卡
- *  需要在已加载的旧 history 之后再取一次最新回合边界（R-01-009/AC-12、R-01-013/AC-12）。 */
-export function detailLoadPlan({
-	detail = {},
-	isSubagent = false,
-	snapshotReady = false,
-	historyNeeded = false,
-	previewFallbackNeeded = false,
-	durationFallbackNeeded = false,
-	windowComplete = true,
-	modelInflight = false,
-	historyInflight = false,
-} = {}) {
-	return {
-		subagent: isSubagent === true,
-		model: !isSubagent && !detail.model && !modelInflight,
-		history:
-			!historyInflight &&
-			((durationFallbackNeeded && detail.durationFallbackLoaded !== true) ||
-				(previewFallbackNeeded && detail.previewFallbackLoaded !== true) ||
-				(!detail.history && ((!snapshotReady && historyNeeded) || (snapshotReady === true && windowComplete === false)))),
-	};
-}
-
 /** 打开重试链是否应取消：目标已成为当前会话（已到达），或用户已激活其它卡片（被新意图取代）。 */
 export function shouldCancelOpenRetry({ targetId, currentId = null, activatedId = null } = {}) {
 	if (targetId === undefined || targetId === null) return true;
@@ -1687,6 +1792,8 @@ export function cardSignature(entries) {
 			entry.loadingTimeline ?? null,
 			entry.loadingPreviews ?? null,
 			entry.tokenStats ?? [entry.outputTokens ?? null, entry.inputTokens ?? null, entry.cacheHitPct ?? null, entry.rateTokS ?? null, entry.elapsedMs ?? null],
+			// 累计运行时长参与签名（R-01-020）：回填/SSE 推送与逐秒推进都要驱动重绘。
+			entry.totalBusyMs ?? null,
 		]),
 	);
 }
@@ -1872,58 +1979,256 @@ function durationTime(value) {
 	return Number.isFinite(time) ? time : null;
 }
 
-/** 从 history 提取最近完整回合的结束时刻与固定耗时；两者始终来自同一回合。 */
-function lastTurnDurationCandidateFromEvents(events) {
-	const starts = new Map();
+/**
+ * 从 history 重放回合/等待边界事件，提取最近一个已结束回合的运行过程耗时（busy 口径：
+ * 起止差值扣除回合内阻塞等待，与 R-01-020 累计口径一致，恒不大于该回合墙钟时长）。
+ * 回合起止不完整、时间逆序或回合运行段不为正时忽略该回合；无可得回合返回 null。
+ */
+export function lastTurnBusyFromEvents(events) {
+	let state = emptyTurnStats();
 	let latest = null;
 	for (const entry of Array.isArray(events) ? events : []) {
-		const event = eventOf(entry);
-		const turn = Number(event?.data?.turn);
-		const time = durationTime(event?.time);
-		if (!Number.isFinite(turn) || time === null) continue;
-		if (event.type === "turn/start") {
-			starts.set(turn, time);
-			continue;
-		}
-		if (event.type !== "turn/end") continue;
-		const start = starts.get(turn);
-		if (start === undefined || time < start) continue;
-		if (latest === null || time > latest.end) latest = { end: time, duration: time - start };
+		const time = durationTime(eventOf(entry)?.time);
+		const prev = state;
+		state = applyTurnEventToStats(state, entry);
+		if (prev.openTurnStart === null || state.openTurnStart !== null) continue;
+		// 能走到回合闭合的必为时刻有效的 turn/end（applyTurnEventToStats 对无效时刻无效果）。
+		const activeMs = (state.busyMs ?? 0) - (prev.busyMs ?? 0);
+		if (activeMs <= 0) continue;
+		latest = { end: time, duration: activeMs };
 	}
-	return latest;
+	return latest?.duration ?? null;
 }
 
-/** 从 turnTimings 提取最近完整回合的结束时刻与固定耗时；两者始终来自同一回合。 */
-function lastTurnDurationCandidateFromTimings(turnTimings) {
-	if (!(turnTimings instanceof Map)) return null;
-	let latest = null;
-	for (const timing of turnTimings.values()) {
-		const start = durationTime(timing?.startTime);
-		const end = durationTime(timing?.endTime);
-		if (start === null || end === null || end < start) continue;
-		if (latest === null || end > latest.end) latest = { end, duration: end - start };
+/** 最近完整回合的固定耗时（busy 口径）：从 history 事件重放派生。 */
+export function lastTurnDuration({ history = [] } = {}) {
+	return lastTurnBusyFromEvents(history);
+}
+
+/** ask_user_question 工具名：提问/计划审查等待的开启边界（tool/call）与配对结算（tool/result）。 */
+const QUESTION_TOOL_NAME = "ask_user_question";
+
+/** 回合/等待边界事件类型全集：busy 记账只消费这些事件，其余事件对记账无效果。 */
+const BOUNDARY_EVENT_TYPES = new Set(["turn/start", "turn/end", "approval/asked", "approval/decided", "tool/call", "tool/result"]);
+
+/** 边界事件判定（宿主实时登记入口与记账转移共用，新增边界只改 BOUNDARY_EVENT_TYPES 一处）。 */
+export function isBusyBoundaryEvent(type) {
+	return BOUNDARY_EVENT_TYPES.has(type);
+}
+
+/** 空记账状态（无任何有效计时）。 */
+export function emptyTurnStats() {
+	return { busyMs: null, openTurnStart: null, openWaitStart: null, openWaitKind: null, openWaitId: null, waitedMs: null, watermarkTime: null };
+}
+
+/** 从任意来源拷贝记账状态：缺失字段归一为 null（旧记录/部分记录兼容）。 */
+export function turnStatsFrom(state) {
+	return {
+		busyMs: state?.busyMs ?? null,
+		openTurnStart: state?.openTurnStart ?? null,
+		openWaitStart: state?.openWaitStart ?? null,
+		openWaitKind: state?.openWaitKind ?? null,
+		openWaitId: state?.openWaitId ?? null,
+		waitedMs: state?.waitedMs ?? null,
+		watermarkTime: state?.watermarkTime ?? null,
+	};
+}
+
+/**
+ * 记账状态逐字段相等（不含 watermarkSeq——它不是状态字段，由宿主侧随写入一并落盘；
+ * watermarkTime 为水位处已覆盖事件的时刻，参与相等判定以让补写该字段的收敛写入生效）。
+ */
+export function turnStatsEqual(a, b) {
+	return (
+		a === b ||
+		((a?.busyMs ?? null) === (b?.busyMs ?? null) &&
+			(a?.openTurnStart ?? null) === (b?.openTurnStart ?? null) &&
+			(a?.openWaitStart ?? null) === (b?.openWaitStart ?? null) &&
+			(a?.openWaitKind ?? null) === (b?.openWaitKind ?? null) &&
+			(a?.openWaitId ?? null) === (b?.openWaitId ?? null) &&
+			(a?.waitedMs ?? null) === (b?.waitedMs ?? null) &&
+			(a?.watermarkTime ?? null) === (b?.watermarkTime ?? null))
+	);
+}
+
+/** 结算当前未配对等待区间：时刻有效则累加 waitedMs，随后清空等待态。 */
+function settleOpenWait(next, time) {
+	if (next.openWaitStart !== null && time >= next.openWaitStart) {
+		next.waitedMs = (next.waitedMs ?? 0) + (time - next.openWaitStart);
+	}
+	next.openWaitStart = null;
+	next.openWaitKind = null;
+	next.openWaitId = null;
+}
+
+/** 强制关闭开放回合（turn/end 与启动扫描共用）：先按时刻结算未配对等待（等待尾部不
+ *  计入运行时长），再把 `time − openTurnStart − waitedMs` 的运行部分累加进 busyMs，
+ *  最后清空回合态；时间逆序时跳过累加、仅清空。 */
+function settleTurnClose(next, time) {
+	if (next.openWaitStart !== null) settleOpenWait(next, time);
+	if (next.openTurnStart !== null && time >= next.openTurnStart) {
+		const activeMs = time - next.openTurnStart - (next.waitedMs ?? 0);
+		if (activeMs > 0) next.busyMs = (next.busyMs ?? 0) + activeMs;
 	}
-	return latest;
+	next.openTurnStart = null;
+	next.waitedMs = null;
 }
 
-/** 从 history 提取最近完整回合的固定耗时；回合起止不完整或逆序时忽略该回合。 */
-export function lastTurnDurationFromEvents(events) {
-	return lastTurnDurationCandidateFromEvents(events)?.duration ?? null;
+/**
+ * 会话回合统计记账的单步转移（R-01-020）：对单个回合/等待边界事件应用后返回新状态。
+ * 状态 `{ busyMs, openTurnStart, openWaitStart, openWaitKind, openWaitId, waitedMs }`——
+ * busyMs 为运行过程时长的累计（null 表示尚无任何有效回合计时），openTurnStart 为当前
+ * 开放回合起点，openWaitStart/openWaitKind/openWaitId 为当前未配对等待区间（回合内
+ * 阻塞等待：'approval' 审批 / 'question' 提问，id 为审批 id 或提问 callId），waitedMs
+ * 为本回合内已配对等待时长的累计；completed/blocked/max-tokens/aborted/error 全部结束
+ * 原因均计入，回合间空闲与回合内等待不计入。等待边界：`approval/asked` 与
+ * `ask_user_question` 的 `tool/call` 开启（记录 id/callId），`approval/decided` 与同
+ * id/callId 的 `tool/result` 结算（id 不匹配的结算事件忽略）；等待串行不嵌套（已有
+ * 未配对等待时新边界忽略），`turn/end` 先按事件时刻强制结算未配对等待再以
+ * `time − openTurnStart − waitedMs` 结算回合。start 覆盖式登记（串行回合下最后一个
+ * start 为当前回合），end 配对最近 start；起点缺失或时间逆序的回合跳过累加、仅清空
+ * 状态。event 兼容 history 条目包装与裸事件（eventOf 解包），宿主实时登记与回填共用
+ * 同一转移，保证口径一致（R-01-020/AC-02）。
+ */
+export function applyTurnEventToStats(state, entry) {
+	const event = eventOf(entry);
+	const time = durationTime(event?.time);
+	const type = event?.type;
+	if (time === null || !isBusyBoundaryEvent(type)) return state;
+	const next = turnStatsFrom(state);
+	if (type === "turn/start") {
+		next.openTurnStart = time;
+		next.openWaitStart = null;
+		next.openWaitKind = null;
+		next.openWaitId = null;
+		next.waitedMs = null;
+		return next;
+	}
+	if (type === "turn/end") {
+		settleTurnClose(next, time);
+		return next;
+	}
+	if (type === "approval/asked") {
+		if (next.openTurnStart === null || next.openWaitStart !== null) return state;
+		next.openWaitStart = time;
+		next.openWaitKind = "approval";
+		next.openWaitId = typeof event?.data?.id === "string" ? event.data.id : null;
+		return next;
+	}
+	if (type === "approval/decided") {
+		if (next.openWaitStart === null || next.openWaitKind !== "approval") return state;
+		if (next.openWaitId !== null && event?.data?.id !== next.openWaitId) return state;
+		settleOpenWait(next, time);
+		return next;
+	}
+	if (type === "tool/call") {
+		if (event?.data?.name !== QUESTION_TOOL_NAME) return state;
+		if (next.openTurnStart === null || next.openWaitStart !== null) return state;
+		next.openWaitStart = time;
+		next.openWaitKind = "question";
+		next.openWaitId = typeof event?.data?.callId === "string" ? event.data.callId : null;
+		return next;
+	}
+	// tool/result：仅结算开启中的提问等待，且 callId 与开启边界一致——其余 result 对
+	// 记账无效果（等待串行，同 callId 的下一个 result 即配对边界）。
+	if (next.openWaitStart === null || next.openWaitKind !== "question") return state;
+	const resultCallId = event?.data?.message?.source?.callId;
+	if (next.openWaitId !== null && resultCallId !== next.openWaitId) return state;
+	settleOpenWait(next, time);
+	return next;
 }
 
-/** 从 turnTimings 提取最近完整回合的固定耗时；全部回合未结束或无效时返回 null。 */
-export function lastTurnDurationFromTimings(turnTimings) {
-	return lastTurnDurationCandidateFromTimings(turnTimings)?.duration ?? null;
+/**
+ * busy 记账字段归一：null/undefined 直通为 null（「无数据」语义），仅真实有限数字
+ * 保留。必须先判空再走 Number()——Number(null) === 0 会把「无开放回合」误归一为
+ * epoch 0，令合成值膨胀为 now−0（R-01-020/AC-06 回归）。
+ */
+export function normalizeBusyMs(value) {
+	if (value === null || value === undefined) return null;
+	const n = Number(value);
+	return Number.isFinite(n) ? n : null;
 }
 
-/** 在快照与 history 中按最近结束时刻选择同一最新完整回合的固定耗时。 */
-export function lastTurnDuration({ turnTimings = null, history = [] } = {}) {
-	const candidates = [lastTurnDurationCandidateFromTimings(turnTimings), lastTurnDurationCandidateFromEvents(history)].filter(Boolean);
-	let latest = null;
-	for (const candidate of candidates) {
-		if (latest === null || candidate.end > latest.end) latest = candidate;
+/**
+ * 标题行累计运行时长的显示合成（R-01-020/AC-01、AC-03、AC-06、AC-07）：已完成回合
+ * 累计加开放回合的实时已耗时（扣除回合内已配对等待与进行中的未配对等待）；两者皆
+ * 不可得时返回 null（调用方不显示，不以 0 冒充）。now 缺失或无效时不推进实时增量，
+ * 只返回已完成累计。等待期间 `(now − openTurnStart)` 与 `(now − openWaitStart)` 两项
+ * 随 now 同步增长相互抵消，显示值自冻结；等待结算时 waitedMs 接管同一增量，恢复
+ * 运行后从冻结值继续，回合结算处连续无跳变。
+ */
+export function totalBusyDisplayMs({ busyMs = null, openTurnStart = null, waitedMs = null, openWaitStart = null, now = null } = {}) {
+	let total = typeof busyMs === "number" && Number.isFinite(busyMs) && busyMs >= 0 ? busyMs : null;
+	if (openTurnStart !== null && Number.isFinite(openTurnStart) && Number.isFinite(now) && now > openTurnStart) {
+		const waited = typeof waitedMs === "number" && Number.isFinite(waitedMs) && waitedMs >= 0 ? waitedMs : 0;
+		const waitingNow = openWaitStart !== null && Number.isFinite(openWaitStart) && now > openWaitStart ? now - openWaitStart : 0;
+		total = (total ?? 0) + Math.max(0, now - openTurnStart - waited - waitingNow);
 	}
-	return latest?.duration ?? null;
+	return total;
+}
+
+/**
+ * 回合统计记账的统一收敛（R-01-020/AC-04、AC-05）：对全会话事件列表重放出下一份
+ * 记账，宿主侧懒回填与启动扫描共用。路径选择——无记录、强制重放、持久化水位非法、
+ * 或水位超前于日志最大 seq（事件 seq 空间被重编，如 dsh 0.1.5 V3 迁移）时从空状态
+ * 全量重放（超前水位会把后续全部实时事件封死在守卫之外，openTurnStart 永不清空、
+ * 总耗时无限增长）；否则从持久化记账出发仅增量应用 `seq > watermarkSeq` 的事件。
+ * 水位推进处同步记录 `watermarkTime`（水位处已覆盖事件的时刻，与实时登记按效果事件
+ * 写入的口径互为保守——检测只要求该值不超过真实边界事件时刻）——宿主实时登记据此
+ * 识别 seq 空间重编（低 seq 事件携带比水位更新的时刻，增量口径已失效）。
+ * `closeOpenTurn`（宿主启动扫描）：重放后仍存在的开放回合按日志最后事件时刻强制
+ * 结算关闭——宿主重启后不存在仍在运行的回合，残留起点只会令总耗时无限增长；尾部
+ * 未配对等待一并按同刻结算（不落到运行时长里）。
+ */
+export function reconcileTurnStats(current, records, { closeOpenTurn = false, forceFresh = false } = {}) {
+	const list = Array.isArray(records) ? records : [];
+	let maxSeq = null;
+	let lastTime = null;
+	for (const record of list) {
+		const seq = Number(record?.seq);
+		if (Number.isFinite(seq) && (maxSeq === null || seq > maxSeq)) maxSeq = seq;
+		const time = durationTime(eventOf(record)?.time);
+		if (time !== null && (lastTime === null || time > lastTime)) lastTime = time;
+	}
+	const fresh = forceFresh || !isRecord(current) || !Number.isFinite(current.watermarkSeq) || (maxSeq !== null && Number(current.watermarkSeq) > maxSeq);
+	let state = emptyTurnStats();
+	let watermarkSeq = null;
+	let watermarkTime = null;
+	// 水位推进：seq 更大即前推水位；事件时刻有效才更新 watermarkTime（无效不前推）。
+	const advance = (record) => {
+		const seq = Number(record?.seq);
+		if (!Number.isFinite(seq) || (watermarkSeq !== null && seq <= watermarkSeq)) return;
+		watermarkSeq = seq;
+		const time = durationTime(eventOf(record)?.time);
+		if (time !== null) watermarkTime = time;
+	};
+	if (fresh) {
+		for (const record of list) {
+			state = applyTurnEventToStats(state, record);
+			advance(record);
+		}
+	} else {
+		state = turnStatsFrom(current);
+		watermarkTime = state.watermarkTime;
+		watermarkSeq = Number(current.watermarkSeq);
+		for (const record of list) {
+			const seq = Number(record?.seq);
+			if (!Number.isFinite(seq) || seq <= watermarkSeq) continue;
+			state = applyTurnEventToStats(state, record);
+			advance(record);
+		}
+	}
+	if (closeOpenTurn && state.openTurnStart !== null) {
+		// 启动扫描：宿主重启后不存在仍在运行的回合——按日志最后事件时刻强制结算关闭；
+		// 日志不可得（空/缺失）时仅清除回合态，不制造虚假运行时长。
+		if (lastTime !== null) settleTurnClose(state, lastTime);
+		state.openTurnStart = null;
+		state.openWaitStart = null;
+		state.openWaitKind = null;
+		state.openWaitId = null;
+		state.waitedMs = null;
+	}
+	return { ...state, watermarkSeq, watermarkTime };
 }
 
 /**