@zhushanwen/pi-base-tool-enhance 0.6.2 → 0.7.1

package/src/background/notify-reconcile-judgement.ts

@@ -0,0 +1,107 @@
+/**
+ * 补投判据纯函数（bg-task-notify-durability 设计 §5 U1）——送达痕迹提取与补投标记
+ * entry 的读写形态约定。
+ *
+ * 两个纯函数族（无 I/O、无 pi 依赖，形态穷举单测覆盖）：
+ *  ① collectDeliveredTaskIds：从会话 entries 提取「已送达完成通知的 taskId 集合」。
+ *     送达痕迹 = 会话文件里的完成通知消息本身（custom_message，customType =
+ *     background-bash）——正常投递经 pi.sendMessage 落盘的形态；fork 副本随 session
+ *     文件复制同形态带走，天然命中（fork 窄窗口的跨会话重复已由设计决策 5 独立限定）。
+ *     判定通道两条，任一命中即算：details.taskId（结构化字段）/ content 文本含
+ *     bt- 形态 token（缺 details 的旧消息——details 载荷是后加的，历史消息只有 content）。
+ *  ② 补投标记（幂等锚）：customType = background-bash:reconciled 的 plain custom
+ *     entry（pi.appendEntry 同步入账），data = {taskId, reconciledAt}。不进 LLM 上下文
+ *     （与 NotifyLedger 同款通道纪律：账务走 appendEntry，送达消息走 sendMessage）。
+ *
+ * 非目标（设计否决记录防回潮）：纯痕迹反查判重不成立（送达消息落盘异步于投递返回，
+ * 双派发的第二次对账在窗口内查不到痕迹必现双投）——补投标记是唯一能在同激活内收敛的
+ * 锚点，两族函数必须配合使用（见 pending-reconcile.ts 判据三条件）。
+ */
+
+import { BACKGROUND_BASH_CUSTOM_TYPE } from "./notify.ts";
+
+/**
+ * 补投标记 entry 的 customType 落盘字符串（形态约定 SSOT，设计决策 1）。
+ * plain custom entry（appendEntry 通道），与送达消息的 background-bash 通道刻意区分。
+ */
+export const RECONCILED_MARKER_CUSTOM_TYPE = "background-bash:reconciled";
+
+/** 补投标记 entry 的 data 落盘形态（设计决策 1：{taskId, reconciledAt}）。 */
+export interface ReconciledMarkerData { // oe-exempt:20260929:framework:workflow/record 协议契约类型——ports 类型契约先行、单实现常态（dev-0.10.5 已验收代码 merge 带入）
+	taskId: string;
+	/** 补投发起时刻（epoch 毫秒；观测字段，判据不消费）。 */
+	reconciledAt: number;
+}
+
+/** 构造补投标记 data（写侧唯一入口——落盘形态演进只改此处与 collect 读侧）。 */
+export function buildReconciledMarkerData(taskId: string, reconciledAt: number): ReconciledMarkerData {
+	return { taskId, reconciledAt };
+}
+
+/**
+ * content 中 bt- 形态 taskId 的提取模式（spawn-background generateTaskId 生成规则：
+ * bt-<epoch ms>-<base36 固定长随机段>）。按生成形态锚定而非任意 bt- 前缀串，避免把
+ * 普通英文词（如 "btw-"）误判为任务 id。设计原文「content 含 taskId」的宽松语义：
+ * 尾部输出摘要里如出现其他任务 id 也会算送达痕迹——方向保守（漏补投优于重复投）。
+ */
+const CONTENT_TASK_ID_PATTERN = /\bbt-\d+-[0-9a-z]+\b/g;
+
+/**
+ * 从会话 entries 提取已送达完成通知的 taskId 集合（判据通道①：送达痕迹）。
+ *
+ * 五形态语义（设计 §5 U1 形态清单）：正常消息（details + content 双通道命中）、
+ * fork 副本（同形态命中）、缺 details 旧消息（仅 content 命中）、非 bash 通知
+ * （customType 不同，不命中）、killed 无痕迹任务（无消息 entry，天然不在集合）。
+ *
+ * 容错对齐 protocol pending-entries 扫描同款纪律：null/非对象元素跳过；content 兼容
+ * string 与 TextContent[] 两种落盘形态（pi appendCustomMessageEntry 接受两者）。
+ */
+export function collectDeliveredTaskIds(entries: readonly unknown[]): Set<string> {
+	const ids = new Set<string>();
+	for (const raw of entries) {
+		if (!raw || typeof raw !== "object") continue;
+		const entry = raw as Record<string, unknown>;
+		if (entry.customType !== BACKGROUND_BASH_CUSTOM_TYPE) continue;
+		const taskId = stringField(entry.details, "taskId");
+		if (taskId !== undefined) ids.add(taskId);
+		const content = entry.content;
+		if (typeof content === "string") {
+			collectTaskIdsFromText(content, ids);
+		} else if (Array.isArray(content)) {
+			for (const block of content) {
+				const text = stringField(block, "text");
+				if (text !== undefined) collectTaskIdsFromText(text, ids);
+			}
+		}
+	}
+	return ids;
+}
+
+/**
+ * 从会话 entries 提取已补投（标记 entry 在）的 taskId 集合（判据通道②：补投标记）。
+ * data 形态防御：缺 taskId / 非字符串的脏标记 entry 跳过（不因单条脏数据报废判据）。
+ */
+export function collectReconciledTaskIds(entries: readonly unknown[]): Set<string> {
+	const ids = new Set<string>();
+	for (const raw of entries) {
+		if (!raw || typeof raw !== "object") continue;
+		const entry = raw as Record<string, unknown>;
+		if (entry.customType !== RECONCILED_MARKER_CUSTOM_TYPE) continue;
+		const taskId = stringField(entry.data, "taskId");
+		if (taskId !== undefined) ids.add(taskId);
+	}
+	return ids;
+}
+
+/** unknown 值上指定键的 string 字段（非对象/缺键/非字符串一律 undefined）。 */
+function stringField(value: unknown, key: string): string | undefined {
+	if (value === null || typeof value !== "object") return undefined;
+	const field = (value as Record<string, unknown>)[key];
+	return typeof field === "string" ? field : undefined;
+}
+
+function collectTaskIdsFromText(text: string, ids: Set<string>): void {
+	for (const match of text.matchAll(CONTENT_TASK_ID_PATTERN)) {
+		ids.add(match[0]);
+	}
+}

package/src/background/notify.ts

@@ -179,6 +179,17 @@ function sendTaskFinishedMessage(task: BackgroundTask): void {
 	}
 }
 
+/**
+ * 通知文案函数的参数面：只依赖终态渲染所需字段。收窄为结构子集（而非完整
+ * BackgroundTask）使补投路径可直接传 registry 终态条目（RegistryEntry——无
+ * registryPath 等运行时字段），文案组装逻辑主路径与补投路径共用一份。完整
+ * BackgroundTask 满足该子集，既有调用方不受影响。
+ */
+export type NotificationTaskLike = Pick<
+	BackgroundTask,
+	"taskId" | "command" | "outputFile" | "durationMs" | "exitCode" | "reason" | "tailSummary"
+>;
+
 /**
  * 通知文案（§3.1 终态样例）：
  *
@@ -189,7 +200,7 @@ function sendTaskFinishedMessage(task: BackgroundTask): void {
  * 失败任务 head 行标 failed（exit code 即 error 摘要，尾部输出佐证）；timeout 标
  * timed out；tailSummary 为空（无输出/文件丢失）时省略 Last lines 行。
  */
-export function buildNotificationContent(task: BackgroundTask): string {
+export function buildNotificationContent(task: NotificationTaskLike): string {
 	const duration = formatDurationMs(task.durationMs ?? 0);
 	const command = truncateCommand(task.command);
 	let head: string;
@@ -241,7 +252,7 @@ export interface BackgroundBashDetails {
  * command 取原始终态值不截断：截断（PENDING_NAME_LIMIT）是 content 行宽约束，结构化
  * 消费方的行宽由渲染层自己决定（旧数据无 details 时仍走 content 原文兜底）。
  */
-export function buildNotifyDetails(task: BackgroundTask): BackgroundBashDetails {
+export function buildNotifyDetails(task: NotificationTaskLike): BackgroundBashDetails {
 	return {
 		taskId: task.taskId,
 		command: task.command,
@@ -251,6 +262,21 @@ export function buildNotifyDetails(task: BackgroundTask): BackgroundBashDetails
 	};
 }
 
+/**
+ * 收殓终态（exited process-exit / orphaned）的补投文案行（bg-task-notify-durability
+ * 设计决策 3/4）——主路径不产这类消息（process-exit 收殓不 sendMessage），仅供补投：
+ *
+ *   [background-bash] bt-x was terminated when the session went down (exit code unknown): <command>. Output file: <path>; use bash_output to check the output before rerunning.
+ *
+ * 措辞统一为「结果未知、先查输出再决定是否重跑」：不区分被补杀/自行退出（orphaned
+ * 的成因不在 reason 枚举内，二分须补 registry 字段，与零格式变更矛盾）；省略时长
+ * （orphaned 的 durationMs 含属主死后滞留时长，展示误导）；不谎报完成/失败。
+ */
+export function buildTerminatedNotificationLine(task: Pick<NotificationTaskLike, "taskId" | "command" | "outputFile">): string {
+	const command = truncateCommand(task.command);
+	return `[background-bash] ${task.taskId} was terminated when the session went down (exit code unknown): ${command}. Output file: ${task.outputFile}; use bash_output to check the output before rerunning.`;
+}
+
 /** 耗时换算常量（毫秒/秒/分/时 + 时分两位补零宽度）。 */
 const MS_PER_SECOND = 1000;
 const SECONDS_PER_MINUTE = 60;

package/src/background/pending-reconcile.ts

@@ -1,7 +1,8 @@
 /**
- * session_start pending 对账（M3，§3.5 接入细则第 4 条——pending 收尾的统一兜底）。
+ * session_start pending 对账 + 完成通知补投（M3 §3.5 接入细则第 4 条 +
+ * bg-task-notify-durability 设计 §5 U2/U3）。
  *
- * 职责：对「session entries 差集显示 active、但任务已终态」的 bt- 任务补写
+ * 职责一（既有）：对「session entries 差集显示 active、但任务已终态」的 bt- 任务补写
  * pending:unregister entry。覆盖三类 otherwise 悬空场景（设计原文）：
  *  ① 进程 graceful 退出收殓时 pi API 已不可用，unregister 没写成 entry；
  *  ② 强杀后收殓侧只改 registry（标 orphaned），碰不了 session 文件；
@@ -16,19 +17,42 @@
  * 删除——而对账 appendEntry 同步入账先于 emit 执行，emit 到达时该 id 必已注销
  * = 恒 no-op 死路径。）
  *
+ * 职责二（补投，设计决策 1/2）：对「registry 严格终态（非 killed）∧ 会话 entries
+ * 无送达痕迹 ∧ 无补投标记」的后台任务，合并成一条消息补投完成通知，resolve 后
+ * 同步写补投标记 entry 保幂等。覆盖的失效面 = 主路径单次投递丢失（进程死亡收殓、
+ * 投递 throw、投递被接受但未落盘即崩溃）。**补投是 registry 全集的独立遍历，不挂
+ * pending 差集循环**（决策 2）：差集候选 = pending:register 还挂着的任务，而失效
+ * 形态「poller 边沿 unregister 已写、sendMessage 才 throw」下差集为空，挂靠即永久
+ * 漏补。补投**不代写 pending:unregister**——收尾保持差集循环唯一写点（避免绕过
+ * listener 的 isPendingActive 幂等门落冗余 entry）。
+ *
  * 差集判据单点（ext-simplify-13）：collectActivePendingIds（protocol
  * pending-entries 模块，与 pending-notifications 守卫判据同源）+ bt- 前缀过滤；
  * 本地差集副本已删除。task_id 前缀亦消费 protocol 契约常量
  * BACKGROUND_TASK_ID_PREFIX（§2.3，区别于 subagent-workflow 的 bg-/run-）。
  *
- * 终态判据：registry state ∈ {exited, orphaned}，或（state=running/killing 且
- * kill(pid,0) 判死：收殓/写盘失败遗留的 running 条目按事实终态处理）。
- * 不改 registry——终态写入归收殓侧（runtime reaper）/轮询器（单点归属），对账只清
- * pending 侧。
+ * 补投终态判据（决策 2）：protocol isTerminalState 严格终态（exited/orphaned）——
+ * **显式不用下方 isTerminalByRegistry 宽判据**（宽判据含 running/killing 且 pid 判死，
+ * 会把 killing 遗留——kill 已发令、poller 终态化前进程死亡，实为被杀任务——误判为
+ * 可补投）；且 state=exited 时 reason≠killed（killed 是 reason 枚举值而非独立
+ * state，state 级过滤排不掉，必须 reason 级显式排除——kill 的发起方当次交互已同步
+ * 获知结果，补投是重复刺激）。killing/running+判死遗留不补投（保守正确，退化现状）。
+ *
+ * 补投幂等三配套（决策 1，缺一被双派发反例击穿）：
+ *  ① await sendMessage——见 ReconcilePi.sendMessage 注释的实装适配登记；
+ *  ② 进程内 in-flight 单飞守卫（模块级 Set 按 taskId 键控）：同一次激活是
+ *     startup+resume 双派发，第二路对账落在第一路补投的 await 窗口内，若不挡会
+ *     再调 sendMessage（此刻 agent 循环进行中，消息不落盘）且三判据仍全命中
+ *     （标记未写、痕迹未落盘）——按 taskId 键控天然消解同进程 session 替换时旧
+ *     会话 in-flight 误挡新会话的窗口。跳过粒度仅补投扫描，差集循环照常执行。
+ *     摘除绑定 sendMessage settle（finally），不绑「激活结束」；纯内存跨激活无
+ *     状态，进程死亡自然清零；
+ *  ③ resolve 后同步 appendEntry 补投标记——同步入账使后续任何对账立即收敛。
  *
  * 执行链（index.ts session_start 链内）：收殓下沉 runtime 后（u-bte-remove）本链
- * 仅剩对账——「对账见 running+pid 活则不动作，下一 session_start 兜底」的幂等
- * 语义覆盖孤儿终态由 runtime 异步写入的时序窗口。
+ * 仅剩对账 + 补投——「对账见 running+pid 活则不动作，下一 session_start 兜底」的
+ * 幂等语义覆盖孤儿终态由 runtime 异步写入的时序窗口。补投先于差集收尾（先通知后
+ * 清观察面），差集收尾无条件执行（幂等语义不依赖补投成败，两者无隐藏耦合）。
  */
 
 import {
@@ -40,7 +64,19 @@ import { isPidAlive } from "@zhushanwen/extension-protocol/background-task";
 import { toErrorMessage } from "@zhushanwen/pi-ext-guards";
 import { getLogger } from "@zhushanwen/pi-extension-logger";
 
-import { toPendingReason } from "./notify.ts";
+import {
+	buildReconciledMarkerData,
+	collectDeliveredTaskIds,
+	collectReconciledTaskIds,
+	RECONCILED_MARKER_CUSTOM_TYPE,
+} from "./notify-reconcile-judgement.ts";
+import {
+	BACKGROUND_BASH_CUSTOM_TYPE,
+	buildNotificationContent,
+	buildNotifyDetails,
+	buildTerminatedNotificationLine,
+	toPendingReason,
+} from "./notify.ts";
 import { getRegistryPath, readRegistry } from "./registry.ts";
 import { isActiveState, isTerminalState, type RegistryEntry } from "./types.ts";
 
@@ -48,9 +84,25 @@ const logger = getLogger("base-tool-enhance");
 
 /**
  * 对账依赖的最小 pi 面（结构兼容 ExtensionAPI 的子集；测试注入不造完整 pi）。
+ *
+ * sendMessage 返回类型 `void | Promise<void>` 是 pi 0.84.4 实装的适配登记
+ * （bg-task-notify-durability 实装核实）：ExtensionAPI.sendMessage 的类型声明与
+ * loader.js:296 / agent-session.js:2004 两级桥接均不返回 promise（bindCore 包装层
+ * 以 .catch 吞 rejection 转 runner emitError），真实 pi 注入时恒返回 undefined——
+ * 「await resolve 即已落盘」在实装通道上拿不到。await 两者皆合法：
+ *  - 同步 throw（assertActive 失败 / 旧 bus）在调用点抛出，可捕；
+ *  - Promise rejection（若未来 pi 透传 / 测试 mock）可 await 捕获；
+ *  - 实装下 await undefined 立即通过，标记写入退到「调用返回后」——落盘时序核实
+ *    （message_end 落盘先于 LLM 循环）使残余失败域收窄为 agent 循环 start 阶段
+ *    失败（主形态 = 双派发穿透，由 in-flight 守卫挡在 sendMessage 之前），残余
+ *    由设计决策 6 止损路径包络（下次激活重试语义保持）。
  */
 export interface ReconcilePi {
 	appendEntry(customType: string, data?: unknown): void;
+	sendMessage(
+		message: { customType: string; content: string; display: boolean; details?: unknown },
+		options?: { triggerTurn?: boolean; deliverAs?: "steer" | "followUp" | "nextTurn" },
+	): void | Promise<void>;
 }
 
 /** 对账结果（日志 + 测试断言面）。 */
@@ -59,19 +111,37 @@ export interface ReconcileResult {
 	reconciled: number;
 	/** 差集 active 但判据不满足（活任务 / registry 无条目）而保守跳过的 task_id。 */
 	skipped: string[];
+	/** 补投消息已成功送达（sendMessage settle 通过，同步 throw 与 await reject 均不计入）的 task_id——实装桥接层丢 promise，不等于 pi 侧已落盘，见 ReconcilePi.sendMessage 注释。 */
+	redelivered: string[];
 }
 
 /**
- * 对账主体（同步：readRegistry / kill(pid,0) / appendEntry 均同步，session_start
- * 链内毫秒级完成）。每个僵尸任务 appendEntry 一次（唯一权威写路径）。
+ * 补投 in-flight 单飞守卫（决策 1 配套②）：模块级按 taskId 键控。双派发的两路
+ * handler 共享同一模块实例（factory 二调形态），模块级状态对它们可见。
  */
-export function reconcilePendingEntries(
+const inflightRedeliveries = new Set<string>();
+
+/** 测试专用：清空 in-flight 守卫（跨测试文件残留清理）。 */
+export function resetRedeliveryInFlightForTest(): void {
+	inflightRedeliveries.clear();
+}
+
+/**
+ * 对账主体（session_start 维护链入口）。补投（可能 await sendMessage）先于差集
+ * 收尾；差集收尾无条件执行。每个僵尸任务 appendEntry 一次（唯一权威写路径）。
+ */
+export async function reconcilePendingEntries(
 	pi: ReconcilePi,
 	dataDir: string,
 	sessionId: string,
 	entries: unknown[],
-): ReconcileResult {
-	const result: ReconcileResult = { reconciled: 0, skipped: [] };
+): Promise<ReconcileResult> {
+	const result: ReconcileResult = { reconciled: 0, skipped: [], redelivered: [] };
+
+	// ① 补投扫描（独立遍历 registry 全集，先通知后清观察面）
+	await redeliverMissingNotifications(pi, dataDir, sessionId, entries, result);
+
+	// ② 既有 pending 差集循环（无条件执行；unregister 收尾的唯一写点）
 	const unsettled = collectActivePendingIds(entries, { idPrefix: BACKGROUND_TASK_ID_PREFIX });
 	if (unsettled.size === 0) return result;
 
@@ -81,7 +151,12 @@ export function reconcilePendingEntries(
 		if (entry === undefined) {
 			// registry 无条目：终态无从判定（LRU 淘汰的终态条目其 unregister entry 应已
 			// 落盘，差集里还出现 = spawn 后 registry 写失败等罕见路径）——保守不动作，
-			// pending-notifications 已无任何 TTL 清理，差集残留由 next-session 对账重查收口
+			// pending-notifications 已无任何 TTL 清理，差集残留由 next-session 对账重查收口。
+			// warn 是设计决策 6 的 LRU 淘汰重审触发观测落点（含 taskId；此前该形态零日志）
+			logger.warn(
+				"pending reconcile: registry has no entry for a pending bt- id (LRU-evicted or spawn-write failure); unregister stays pending",
+				{ detail: { taskId: id } },
+			);
 			result.skipped.push(id);
 			continue;
 		}
@@ -135,3 +210,136 @@ function settledPendingReason(entry: RegistryEntry): "completed" | "failed" | "t
 	}
 	return "cancelled";
 }
+
+/**
+ * 补投扫描（决策 2：registry 全集独立遍历）。候选 = 严格终态 ∧ 非 killed ∧ 双锚
+ * （送达痕迹 / 补投标记）皆无 ∧ 不在 in-flight。命中者合并为一条消息投递（对齐
+ * NotifyLedger 同批合并先例，避免 N 个任务驱动 N 个 LLM turn 排队），resolve 后
+ * 逐任务同步写补投标记。任一环节失败（同步 throw / await reject / 标记写失败）：
+ * warn 日志（含 taskId 与失败类别），不写标记，下次 session_start 重试。
+ */
+async function redeliverMissingNotifications(
+	pi: ReconcilePi,
+	dataDir: string,
+	sessionId: string,
+	entries: unknown[],
+	result: ReconcileResult,
+): Promise<void> {
+	const registry = readRegistry(getRegistryPath(dataDir, sessionId));
+	if (registry.size === 0) return;
+
+	const delivered = collectDeliveredTaskIds(entries);
+	const reconciled = collectReconciledTaskIds(entries);
+
+	const candidates: RegistryEntry[] = [];
+	for (const entry of registry.values()) {
+		if (!isRedeliveryCandidate(entry, delivered, reconciled)) continue;
+		if (inflightRedeliveries.has(entry.taskId)) {
+			// 同激活第二路对账（双派发）落在第一路补投的 await 窗口内——跳过该任务的
+			// 补投（差集循环不受影响）。debug 是设计决策 6 in-flight 残留边界的观测落点
+			logger.debug("background task notify redelivery in-flight; skipping duplicate reconcile pass", {
+				detail: { taskId: entry.taskId },
+			});
+			continue;
+		}
+		candidates.push(entry);
+	}
+	if (candidates.length === 0) return;
+
+	const message = buildRedeliveryMessage(candidates);
+	const taskIds = candidates.map((entry) => entry.taskId);
+	for (const id of taskIds) inflightRedeliveries.add(id);
+	try {
+		// 决策 1 配套①：同步 throw 与 await reject 分开捕——失败类别进 warn 日志，
+		// 两类统一不写标记（下次激活重试；判据三条件仍命中才会再投）
+		let sent: void | Promise<void>;
+		try {
+			sent = pi.sendMessage(
+				{ customType: BACKGROUND_BASH_CUSTOM_TYPE, content: message.content, display: true, ...(message.details !== undefined ? { details: message.details } : {}) },
+				{ deliverAs: "steer", triggerTurn: true },
+			);
+		} catch (err) {
+			logger.warn("background task notify redelivery sendMessage threw synchronously; no marker written, retry on next session_start", {
+				detail: { taskIds, err: toErrorMessage(err) },
+			});
+			return;
+		}
+		try {
+			await sent;
+		} catch (err) {
+			logger.warn("background task notify redelivery sendMessage rejected; no marker written, retry on next session_start", {
+				detail: { taskIds, err: toErrorMessage(err) },
+			});
+			return;
+		}
+		// 配套③：resolve 后同步写标记（appendEntry 同步入账）——后续任何对账立即收敛。
+		// 逐任务独立 try/catch：单条标记写失败只跳过该任务的重试收尾（下次激活重投；
+		// 若消息实际已落盘则痕迹命中判重，不会重复——仅「消息真丢了」才重投，语义正确）
+		for (const entry of candidates) {
+			try {
+				pi.appendEntry(RECONCILED_MARKER_CUSTOM_TYPE, buildReconciledMarkerData(entry.taskId, Date.now()));
+			} catch (err) {
+				logger.warn("background task notify reconciled marker appendEntry failed; redelivery may repeat on next session_start", {
+					detail: { taskId: entry.taskId, err: toErrorMessage(err) },
+				});
+			}
+		}
+		result.redelivered.push(...taskIds);
+	} finally {
+		// 摘除绑定 sendMessage settle（resolve/reject/同步 throw 皆经此），非「激活结束」；
+		// 摘除记 debug（决策 6 in-flight 残留边界的配对观测）
+		for (const id of taskIds) {
+			inflightRedeliveries.delete(id);
+			logger.debug("background task notify redelivery settled; in-flight guard released", {
+				detail: { taskId: id },
+			});
+		}
+	}
+}
+
+/**
+ * 补投候选判据（决策 1/2 的三条件 + killed reason 级排除）。判据不查 in-flight
+ * （守卫是执行面关注点，独立于候选语义），调用方负责。
+ */
+function isRedeliveryCandidate(entry: RegistryEntry, delivered: Set<string>, reconciled: Set<string>): boolean {
+	// 严格终态：protocol isTerminalState（exited/orphaned）——不用 isTerminalByRegistry
+	// 宽判据（含 running/killing+pid 判死，killing 遗留实为被杀任务，误判即违背
+	// killed 不补投设计意图）
+	if (!isTerminalState(entry.state)) return false;
+	// killed 是 exited 的 reason 枚举值而非独立 state，state 级过滤排不掉——reason 级
+	// 显式排除（bash_kill 发令方当次交互已同步获知结果，补投是重复刺激）
+	if (entry.state === "exited" && entry.reason === "killed") return false;
+	// 双锚判重：送达痕迹在（正常送达/历史补投的消息在）/ 补投标记在——任一命中不再投
+	if (delivered.has(entry.taskId)) return false;
+	if (reconciled.has(entry.taskId)) return false;
+	return true;
+}
+
+/**
+ * 补投消息组装（设计 §3.1 三分支，决策 4）：
+ *  - 单任务且真实终态（exited natural/timeout）：与正常投递同款结构化消息（同
+ *    details 载荷，renderer SystemNotice 结构化渲染正常工作）；
+ *  - 单任务收殓终态（process-exit/orphaned）或多任务合并：整条无 details（details
+ *    载荷只描述单任务，混合/复数场景携带任一任务的 details 会产生「结构化行只讲
+ *    一个任务、其余沉入降级文本」的错位形态），纯文本行逐任务列终态行——exited
+ *    真终态行复用 buildNotificationContent 的 content 文本（禁止把 exit 0 正常完成
+ *    套 terminated 措辞谎报），收殓终态行用 terminated 措辞。
+ */
+function buildRedeliveryMessage(candidates: RegistryEntry[]): { content: string; details?: unknown } {
+	const single = candidates.length === 1 ? candidates[0] : undefined;
+	if (single !== undefined && isGenuineExit(single)) {
+		return {
+			content: buildNotificationContent(single),
+			details: buildNotifyDetails(single),
+		};
+	}
+	const content = candidates
+		.map((entry) => (isGenuineExit(entry) ? buildNotificationContent(entry) : buildTerminatedNotificationLine(entry)))
+		.join("\n");
+	return { content };
+}
+
+/** 真实终态：exited 且成因是自然退出/超时（process-exit 是收殓终止，不算）。 */
+function isGenuineExit(entry: RegistryEntry): boolean {
+	return entry.state === "exited" && (entry.reason === "natural" || entry.reason === "timeout");
+}

package/src/index.ts

@@ -6,7 +6,10 @@
  * 轮询器单例任务表）、bash_output / bash_kill 工具、进程退出收殓、subagent 降级。
  * M3：pending-notifications 通知接入——load 时刷新轮询器通知通路的 pi 引用（D17
  * session 替换接管）+ 挂 exit 边沿通知回调（unregister emit + sendMessage steer）+
- * session_start 对账（appendEntry 权威路径兜底 pending 收尾）。
+ * session_start 对账（appendEntry 权威路径兜底 pending 收尾）+ 完成通知补投
+ * （bg-task-notify-durability：终态无痕迹无标记的任务下次激活合并补投 + 同步幂等标记）。
+ * 维护链双触发面：session_start 事件 + `__taiji_bg_reconcile__` 内部命令（taiji runtime
+ * 在 getCommands 时按节流补触发，覆盖「切走切回同进程重挂接、session_start 不重发」场景）。
  * 收殓下沉（u-bte-remove）：M5 孤儿收殓已移交 taiji runtime（background-task-
  * reaper 双触发面——session 销毁时 + 启动期兜底扫描，设计 file-lock-unification-
  * and-reaper-sink.md §3.2 D2），extension 不再做全局扫描/全局锁；session_start
@@ -16,6 +19,7 @@
 
 import type {
 	ExtensionAPI,
+	ExtensionCommandContext,
 	ExtensionContext,
 	SessionStartEvent,
 } from "@earendil-works/pi-coding-agent";
@@ -52,23 +56,46 @@ export default function baseToolEnhanceExtension(pi: ExtensionAPI): void {
 	// unified-hooks 退役承接：工具报错审计（D11 落点）
 	setupToolErrorAudit(pi);
 	// pending 对账（M3）：任意 session 启动触发（startup/reload/new/resume/fork 全
-	// reason）。孤儿收殓已下沉 runtime（见文件头），本链无全局扫描
+	// reason）。孤儿收殓已下沉 runtime（见文件头），本链无全局扫描。
+	// handler 返回维护链 promise（补投 await sendMessage 使对账 async 化，
+	// bg-task-notify-durability U3）：pi runner emit await handler（runner.js:632），
+	// promise 由其消费不产生 unhandled rejection；错误在维护链内 async 捕获
 	pi.on("session_start", (event: SessionStartEvent, ctx: ExtensionContext) => {
-		runSessionStartMaintenance(pi, ctx, event.reason);
+		return runSessionStartMaintenance(pi, ctx, event.reason);
+	});
+	// 第二触发面（bg-task-notify-durability 补强）：桌面「切走会话再切回」是同进程重新
+	// 挂接——pi 进程存活、不重发 session_start（真机实证），挂在 session_start 上的
+	// 维护链在「投递失败但进程存活」场景（设计 G2 核心场景）永不触发。taiji runtime 在
+	// getCommands（切回后 renderer 主动拉取命令的必经查询）时经 client.prompt 发起本
+	// 命令（60s per-session 节流、fire-and-forget），handler 调同一维护函数（reason 传
+	// 'resume' 语义）。`/__` 双下划线前缀 = 内部命令（前端 internal-command-filter 过滤
+	// 不显示）；无待补任务时维护链三判据早退，零输出零 turn。
+	pi.registerCommand("__taiji_bg_reconcile__", {
+		description:
+			"Internal: rerun pending background-task reconcile + completion-notify redelivery (triggered by taiji runtime on session resume; session_start does not refire for same-process reattach)",
+		handler: async (_args: string, ctx: ExtensionCommandContext) => {
+			return runSessionStartMaintenance(pi, ctx, "resume");
+		},
 	});
 }
 
 /**
- * session_start 维护链（仅剩 M3 对账——收殓下沉 runtime 后，u-bte-remove）。
+ * session_start 维护链（M3 对账 + 补投——收殓下沉 runtime 后，u-bte-remove）。
+ *
+ * 双入口共用本函数：① session_start 事件（reason 透传）；② `__taiji_bg_reconcile__`
+ * 内部命令（runtime 切回触发，reason 恒 'resume'）。维护逻辑与幂等性对两入口完全一致。
  *
- * 执行形态：同步直跑不 await——对账毫秒级（readRegistry + kill(pid,0) +
- * appendEntry），不构成 session 启动链延迟；错误吞掉记 warn（对账失败无害：僵尸
- * register 停留差集，下一 session_start 幂等重查）。
+ * 执行形态：async（补投 await sendMessage，bg-task-notify-durability 设计决策 1
+ * 规格①；实装下 pi.sendMessage 恒同步返回，见 pending-reconcile.ts ReconcilePi
+ * 注释的适配登记）。错误吞掉记 warn（对账/补投失败无害：僵尸 register 停留差集、
+ * 待补任务三判据仍命中，下一 session_start 幂等重查）——async 捕获防 unhandled
+ * rejection 复刻已否决的 fire-and-forget 失效形态。
  *
  * 频率语义（D3 守卫粒度）：对账是 session 级操作（读当前 session 的 pi entries +
  * 当前 session 的 registry，appendEntry 幂等），属豁免类不挂进程级 once flag，
  * 每 session_start 都执行。桌面端每次激活是 startup+resume 双派发（factory 二调
- * 下 handler 还会累积），对账多次执行幂等无害；反之若挂进程级 flag，startup 消费
+ * 下 handler 还会累积），对账多次执行幂等无害（补投的重复穿透由 pending-reconcile
+ * 的 in-flight 单飞守卫 + 同步补投标记收敛）；反之若挂进程级 flag，startup 消费
  * flag 后目标 session 的对账将永远被跳过（M3 对账在主链路被禁用，此处是唯一执行点）。
  *
  * 入口无条件 debug 日志（S6 观测通道）：每次 handler 派发都打，含 reason——
@@ -77,17 +104,17 @@ export default function baseToolEnhanceExtension(pi: ExtensionAPI): void {
  * 不再含全局扫描/全局锁，原 reapSkipped 字段随 reap 调用一并移除——对应 S6
  * 场景「批 2 后 reap 类操作不再执行」。
  */
-function runSessionStartMaintenance(
+async function runSessionStartMaintenance(
 	pi: ExtensionAPI,
 	ctx: ExtensionContext,
 	reason: SessionStartEvent["reason"],
-): void {
+): Promise<void> {
 	logger.debug("session_start maintenance dispatch", {
 		detail: { reason },
 	});
 	try {
 		const sessionId = ctx.sessionManager.getSessionId();
-		reconcilePendingEntries(pi, getAgentDir(), sessionId, ctx.sessionManager.getEntries());
+		await reconcilePendingEntries(pi, getAgentDir(), sessionId, ctx.sessionManager.getEntries());
 	} catch (err) {
 		// 对账失败无害：僵尸 register 停留差集，下一 session_start 幂等重查
 		logger.warn("session_start pending reconcile failed; zombies retried next session start", {