@zhushanwen/pi-pending-notifications 0.10.0 → 0.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-pending-notifications",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Cross-extension async operation registration/query mechanism for Pi.",
   "type": "module",
   "main": "src/index.ts",
@@ -34,8 +34,8 @@
     "typebox": "1.3.27"
   },
   "dependencies": {
-    "@zhushanwen/extension-protocol": "0.22.0",
-    "@zhushanwen/pi-delivery-port": "0.2.0",
+    "@zhushanwen/extension-protocol": "0.24.0",
+    "@zhushanwen/pi-delivery-port": "0.3.0",
     "@zhushanwen/pi-extension-logger": "0.6.2"
   },
   "peerDependenciesMeta": {

package/src/__tests__/collect-results.test.ts

@@ -412,6 +412,76 @@ describe("collect_results tool", () => {
 		]);
 	});
 
+	it("[结清五值回填 §3.3.6] 注销 reason 事实经结清解析回填 outcome：completed/failed/cancelled/lost/no_result 分别可达", async () => {
+		// 回填权威 = 结清视图（reason 事实 → resolveSettlementReason），不经
+		// mapReasonToStatus 旧映射——lost/no_result 在旧 status 副档恒落 unknown，
+		// 本用例五值逐一可达即锁定断层修复（真 listener 落盘 → 全链路回填）。
+		const cases: Array<[string, string]> = [
+			["ok-1", "completed"],
+			["ok-2", "failed"],
+			["ok-3", "cancelled"],
+			["ok-4", "lost"],
+			["ok-5", "no_result"],
+		];
+		for (const [id] of cases) setup.entries.push(makeRegisterEntry(id));
+		setup.port.collectArm.mockReturnValue(cases.map(([id]) => ({ id, state: "waiting" })));
+
+		const promise = runCollect(setup, { ids: cases.map(([id]) => id) });
+		const arrivalCb = setup.port.onCollectArrival.mock.calls[0][0] as () => void;
+		// 真实 listener 落盘注销 entry：reason 事实 + mapReasonToStatus 的 status 副档
+		// （lost/no_result 的 status 落 unknown——旧映射通道下 outcome 恒 unknown 的缺陷形态）
+		for (const [id, reason] of cases) setup.handlers.pendingUnregister!({ id, reason });
+		// 端口 consume 真实返回形态（MF-1-6）：只含载荷，type/outcome 归回填
+		setup.port.consume.mockReturnValueOnce(cases.map(([id]) => ({ id, content: `payload-${id}` })));
+
+		arrivalCb();
+		const res = await promise;
+
+		expect(res.details.collected).toEqual(
+			cases.map(([id, outcome]) => ({
+				id,
+				type: "workflow",
+				outcome,
+				content: `payload-${id}`,
+			})),
+		);
+	});
+
+	it("[畸形 data 兜底 §3.3.6] 结清视图缺位（reason 非 string）取 legacy status 副档，与端口快照通道同规则", async () => {
+		// 两通道统一填充规则（结清优先 + legacy status 兜底）：注销 entry 的 reason
+		// 非 string 是畸形 data（结清视图不入，pending-entries.ts absorbUnregisterEntry），
+		// status 合法在册——回填取 status 值，与端口快照通道（collectFieldsFor 同款
+		// `??` 形态）对同一 id 产出一致；reason 合法时结清视图优先（兜底不触发）；
+		// 两视图皆缺位保持 undefined（诚实缺省）。status 值经真 listener 落盘契约同源
+		// （mapReasonToStatus 映射产物），此处直插 entry 镜像落盘形态。
+		setup.entries.push(
+			makeRegisterEntry("ok-1"),
+			makeRegisterEntry("mf-1"),
+			makeRegisterEntry("nil-1"),
+			{ customType: "pending:unregister", data: { id: "ok-1", reason: "completed", status: "completed" } },
+			{ customType: "pending:unregister", data: { id: "mf-1", reason: 42, status: "cancelled" } },
+			{ customType: "pending:unregister", data: { id: "nil-1", reason: 42, status: "not-a-status" } },
+		);
+		setup.port.collectArm.mockReturnValue(
+			["ok-1", "mf-1", "nil-1"].map((id) => ({ id, state: "waiting" })),
+		);
+
+		const promise = runCollect(setup, { ids: ["ok-1", "mf-1", "nil-1"] });
+		const arrivalCb = setup.port.onCollectArrival.mock.calls[0][0] as () => void;
+		setup.port.consume.mockReturnValueOnce(
+			["ok-1", "mf-1", "nil-1"].map((id) => ({ id, content: `payload-${id}` })),
+		);
+
+		arrivalCb();
+		const res = await promise;
+
+		expect(res.details.collected).toEqual([
+			{ id: "ok-1", type: "workflow", outcome: "completed", content: "payload-ok-1" },
+			{ id: "mf-1", type: "workflow", outcome: "cancelled", content: "payload-mf-1" },
+			{ id: "nil-1", type: "workflow", outcome: undefined, content: "payload-nil-1" },
+		]);
+	});
+
 	it("超时路径：已收部分进 collected、未完成进 stillOpen（诚实返回，不抛错）", async () => {
 		setup.entries.push(makeRegisterEntry("fast"), makeRegisterEntry("slow"));
 		setup.port.collectArm.mockReturnValue([

package/src/__tests__/pending-notifications.test.ts

@@ -14,7 +14,7 @@
 
 /* eslint-disable taste/no-unsafe-cast */
 
-import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI, ExtensionContext, Theme } from "@earendil-works/pi-coding-agent";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
 import pendingNotificationsExtension from "../index";
@@ -422,7 +422,7 @@ describe("pendingNotificationsExtension factory", () => {
 			}
 		});
 
-		it("U7c: 未知 reason 落 default 兜底 completed（兜底语义的显式登记——未来若改兜底口径，此用例同步更新）", () => {
+		it("U7c: 未知 reason 落 default 兜底 unknown（fail-visible 缺省——§3.3.11④ fail-open=completed 废除，不产假成功）", () => {
 			fireSessionStart(setup);
 			setup.handlers.pendingRegister!({ id: "w-unknown", type: "workflow", name: "op" });
 			setup.appendEntryMock.mockClear();
@@ -431,7 +431,24 @@ describe("pendingNotificationsExtension factory", () => {
 
 			expect(setup.appendEntryMock).toHaveBeenCalledWith(
 				"pending:unregister",
-				expect.objectContaining({ id: "w-unknown", reason: "some-future-reason", status: "completed" }),
+				expect.objectContaining({ id: "w-unknown", reason: "some-future-reason", status: "unknown" }),
+			);
+		});
+
+		it("[subagent-observability §3.3.11④] reason 缺失（emit 方漏传的畸形 data）→ 结清 reason = no_result，不产 completed 假成功", () => {
+			fireSessionStart(setup);
+			setup.handlers.pendingRegister!({ id: "w-no-reason", type: "workflow", name: "op" });
+			setup.appendEntryMock.mockClear();
+
+			setup.handlers.pendingUnregister!({ id: "w-no-reason" });
+
+			expect(setup.appendEntryMock).toHaveBeenCalledWith(
+				"pending:unregister",
+				expect.objectContaining({ id: "w-no-reason", reason: "no_result", status: "unknown" }),
+			);
+			expect(setup.appendEntryMock).not.toHaveBeenCalledWith(
+				"pending:unregister",
+				expect.objectContaining({ reason: "completed" }),
 			);
 		});
 	});
@@ -454,6 +471,21 @@ describe("pendingNotificationsExtension factory", () => {
 			const ids = (res.details as { items: PendingEntry[] }).items.map((i) => i.id);
 			expect(ids.sort()).toEqual(["s-1", "w-1"]);
 		});
+
+		it("renderResult 接线（C-ext-05）：注册定义携带函数成员 + 折叠态输出 details.summary 一行", async () => {
+			fireSessionStart(setup);
+			setup.handlers.pendingRegister!({ id: "w-1", type: "workflow", name: "a" });
+			const tool = setup.registerToolMock.mock.calls[0][0] as {
+				renderResult: (result: unknown, options: { expanded: boolean }, theme: Theme) => { render: (width: number) => string[] };
+			};
+			expect(typeof tool.renderResult).toBe("function");
+			const res = await runTool(setup, { action: "count" });
+			const renderTheme = { fg: (_token: string, text: string) => text } as unknown as Theme;
+			const lines = tool.renderResult(res, { expanded: false }, renderTheme).render(400);
+			// Text.render 按宽度 pad，trim 后断言（折叠态 = details.summary 一行）
+			expect(lines.length).toBe(1);
+			expect(lines[0].trim()).toBe("1 pending operations");
+		});
 	});
 
 	describe("写侧幂等（P2）", () => {

package/src/index.ts

@@ -259,6 +259,9 @@ export default function pendingNotificationsExtension(pi: ExtensionAPI): void {
 			debugLog("warn", "listener: pending:unregister parse failed", data);
 			return;
 		}
+		if (parsed.reasonMalformed) {
+			debugLog("warn", "listener: pending:unregister reason missing/malformed (emit-side contract breach) → settled no_result", data);
+		}
 
 		debugLog("debug", "listener: pending:unregister parsed", parsed);
 
@@ -424,8 +427,8 @@ export default function pendingNotificationsExtension(pi: ExtensionAPI): void {
 		await awaitCollectArrivals(port, waitingIds, collected, timeoutMs, signal);
 
 		// 终局序列（设计 §3.1③）：consume 取走剩余已到达挂起条目（超时/abort 路径的
-		// 部分收取），collectRelease 解散等待集并把未收挂起条目直通内核 flush（跳过
-		// 合批窗口，恢复 push）。空等待路径不会走到这里（提前返回）。
+		// 部分收取），collectRelease 解散等待集并把未收挂起条目直通内核 flush（边沿
+		// 即投——攒批窗已删 §3.3.7③，恢复 push）。空等待路径不会走到这里（提前返回）。
 		collected.push(...port.consume());
 		port.collectRelease();
 
@@ -464,8 +467,9 @@ export default function pendingNotificationsExtension(pi: ExtensionAPI): void {
 				case "ready":
 				case "unregistered-no-entry":
 					// 快照收取：ready = 日志条目已有终局的读侧快照（不写新终局）；
-					// unregistered-no-entry = 第四态无载荷有限信息形态（outcome 取注销
-					// status、note 说明来源，端口侧组装）。两态的 entry 契约在册。
+					// unregistered-no-entry = 第四态无载荷有限信息形态（outcome 由端口
+					// 按结清视图优先 + legacy status 兜底填充、note 说明来源，端口侧
+					// 组装）。两态的 entry 契约在册。
 					buckets.collected.push({ id: snap.id, ...(snap.entry ?? {}) });
 					break;
 				case "in-push-pipeline":
@@ -526,22 +530,27 @@ export default function pendingNotificationsExtension(pi: ExtensionAPI): void {
 		});
 	}
 
-	/** type/outcome 缺失回填（设计 §3.1③ 字段来源表：type 与 pending:register 的
-	 * type 对齐、outcome 与 pending:unregister 的 status 对齐；MF-1-6：端口 consume
-	 * 只返回 {id, content, details}，终态字段统一由本处单遍扫描回填）：「等待中
-	 * 同步到达」的挂起条目在端口 consume 时点，生产方的注销 entry 尚未落盘
-	 * （managed flushBatch 的 deliver 与 unregisterPending 同步段相邻、deliver 先
-	 * 行；端口 consume 由到达回调在 deliver 栈内同步触发），outcome 恒取空。await
-	 * 恢复后生产方同步栈已完成（注销 entry 已落盘），按本 session entries 现算回填；
-	 * 注销不在册的条目保持 undefined（诚实缺省，不虚构终态）。快照收取条目
-	 * （ready / unregistered-no-entry）的 type/outcome 已由端口 collectArm 填充，
-	 * 回填只补缺不覆盖。 */
+	/** type/outcome 缺失回填（设计 §3.1③ 字段来源表 + §3.3.6 结清权威）：type 与
+	 *  pending:register 的 type 对齐；outcome 与端口快照通道（delivery-port
+	 *  collectFieldsFor / collectArm）统一填充规则——注销结清视图优先（reason 事实
+	 *  经 resolveSettlementReason 结清解析，封闭五值 + 词表外 unknown fail-visible，
+	 *  protocol scanPendingFields 单点投影），legacy status 副档兜底。结清视图承载
+	 *  no_result/lost 等新写入方 reason 的真值（旧 status 副档恒落 unknown），兜底
+	 *  仅服务结清视图缺位的畸形 data（status 合法但 reason 非 string——注销 entry
+	 *  不入结清视图、status 副档在册），此时两通道同取 status 值保持一致；两视图
+	 *  皆缺位保持 undefined（诚实缺省，不虚构终态）。「等待中同步到达」的挂起条目
+	 *  在端口 consume 时点，生产方的注销 entry 尚未落盘（managed flushBatch 的
+	 *  deliver 与 unregisterPending 同步段相邻、deliver 先行；端口 consume 由到达
+	 *  回调在 deliver 栈内同步触发），outcome 恒取空。await 恢复后生产方同步栈已完成
+	 *  （注销 entry 已落盘），按本 session entries 现算回填；注销不在册的条目保持
+	 *  undefined。快照收取条目（ready / unregistered-no-entry）的 type/outcome 已由
+	 *  端口 collectArm 填充，回填只补缺不覆盖。 */
 	function backfillCollectFields(ctx: ExtensionContext, collected: CollectedEntry[]): void {
 		if (!collected.some((c) => c.outcome === undefined || c.type === undefined)) return;
 		const fields = scanPendingFields(ctx.sessionManager.getEntries());
 		for (const c of collected) {
 			if (c.type === undefined) c.type = fields.registerTypes.get(c.id);
-			if (c.outcome === undefined) c.outcome = fields.unregisterStatuses.get(c.id);
+			if (c.outcome === undefined) c.outcome = fields.unregisterSettlements.get(c.id) ?? fields.unregisterStatuses.get(c.id);
 		}
 	}
 }
@@ -574,27 +583,35 @@ function parseRegisterEvent(data: unknown): ParsedRegister | null {
 interface ParsedUnregister {
 	id: string;
 	reason: string;
+	/** reason 缺失/非 string（emit 方违约的畸形 data）——缺省 no_result 结清时置位，
+	 *  调用点 debugLog warn 留痕（[subagent-observability §3.3.11④]）。 */
+	reasonMalformed?: boolean;
 }
 
 /** 解析 pending:unregister 事件 data（容错缺失/类型错误字段）。
- *  T2 通知由 subagent-workflow 自有通道 bg-notify-render 承担，不经本事件。 */
+ *  T2 通知由 subagent-workflow 自有通道 bg-notify-render 承担，不经本事件。
+ *  [subagent-observability §3.3.11④] reason 缺失/非 string（emit 方漏传的违约
+ *  形态）缺省 no_result 不产 completed——无事实可依不产假成功结清，与
+ *  resolveSettlementReason / resolveSettlement 缺省方向一致；畸形经调用点
+ *  warn 留痕。 */
 function parseUnregisterEvent(data: unknown): ParsedUnregister | null {
 	if (typeof data !== "object" || data === null) return null;
 	const d = data as Record<string, unknown>;
 	if (typeof d.id !== "string") return null;
-	return {
-		id: d.id,
-		reason: typeof d.reason === "string" ? d.reason : "completed",
-	};
+	if (typeof d.reason !== "string") {
+		return { id: d.id, reason: "no_result", reasonMalformed: true };
+	}
+	return { id: d.id, reason: d.reason };
 }
 
 /** 将事件 reason 映射为 pending:unregister entry 的 status 字段（落盘契约组成部分）。
  *  权威单点在 protocol pending-entries（ext-simplify-17 D10）——本函数是对 protocol
  *  导出的类型收窄包装（PendingStatus 枚举留在本包，protocol 不引 extension 侧类型），
  *  既有调用点零改动；bte 对账写侧同引 protocol 单点，两侧映射不再可能漂移。
- *  词表演化背景（U5 / §3.2.5 通知词表对齐）见 protocol 实现处 JSDoc。 */
+ *  词表演化背景（U5 / §3.2.5 通知词表对齐）见 protocol 实现处 JSDoc；unknown 缺省
+ *  成员两侧词表同批收录，收窄赋值成立无需断言。 */
 function mapReasonToStatus(reason: string): PendingStatus {
-	return mapReasonToStatusImpl(reason) as PendingStatus;
+	return mapReasonToStatusImpl(reason);
 }
 
 /** 格式化 active 列表为可读文本 */

package/src/render-result.ts

@@ -4,32 +4,7 @@
 
 import type { Theme } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
-import { firstContentText } from "@zhushanwen/extension-protocol";
-
-/** content[0] 的 text 纯文本（content 缺失或非 text 类型时兜底空串）。 */
-function contentText(result: unknown): string {
-	const content = fieldValue(result, "content");
-	if (!Array.isArray(content)) return "";
-	return firstContentText({ content });
-}
-
-/** unknown 值按字段名安全取值（index-signature 收窄，替代全可选结构断言）。 */
-function fieldValue(v: unknown, key: string): unknown {
-	if (typeof v !== "object" || v === null) return undefined;
-	return (v as Record<string, unknown>)[key];
-}
-
-/** 从 details 安全读取 summary（容错非对象形态与旧版本 entry）。 */
-function readDetailsSummary(result: unknown): string | undefined {
-	const summary = fieldValue(fieldValue(result, "details"), "summary");
-	return typeof summary === "string" && summary !== "" ? summary : undefined;
-}
-
-/** 折叠态回退：content 文本首行（保持一行摘要形态）。 */
-function firstLine(text: string): string {
-	const idx = text.indexOf("\n");
-	return idx === -1 ? text : text.slice(0, idx);
-}
+import { firstLine, readDetailsSummary, resultContentText } from "@zhushanwen/extension-protocol";
 
 /** 折叠态（expanded=false）= details.summary 一行（dim）；展开态 = content 纯文本。 */
 export function renderPendingNotificationsResult(
@@ -37,7 +12,7 @@ export function renderPendingNotificationsResult(
 	options: { expanded: boolean },
 	theme: Theme,
 ): Text {
-	if (options.expanded) return new Text(contentText(result), 0, 0);
-	const summary = readDetailsSummary(result) ?? firstLine(contentText(result));
+	if (options.expanded) return new Text(resultContentText(result), 0, 0);
+	const summary = readDetailsSummary(result) ?? firstLine(resultContentText(result));
 	return new Text(theme.fg("dim", summary), 0, 0);
 }

package/src/state.ts

@@ -39,7 +39,9 @@ export type PendingType = "workflow" | "subagent" | "bash" | "session";
 export type PendingKind = "lifetime";
 
 /** 异步操作终态/过渡状态。active = 仍在运行；其他都视为已结束 */
-export type PendingStatus = "active" | "completed" | "failed" | "cancelled" | "expired" | "time_limited" | "aborted";
+/** unknown = 词表外 reason 的解析缺省（fail-visible——§3.3.11④ fail-open=completed 废除，
+ *  不可判读时如实标注不产假成功；仍属「已结束」——非 active）。 */
+export type PendingStatus = "active" | "completed" | "failed" | "cancelled" | "expired" | "time_limited" | "aborted" | "unknown";
 
 /** 一个异步操作的完整描述（= pending:register entry 的 data 字段） */
 export interface PendingEntry {
@@ -125,9 +127,9 @@ export function computeCollectWaitKeys(entries: unknown[], currentSessionId: str
 
 /**
  * collect 终局回填的字段视图单点在 protocol scanPendingFields（register 首见
- * type + 注销 status 的 MAPPED 成员，与 delivery-port 快照基线同一映射规则，
- * MF-2-1；回填时序背景见 index.ts collectResults 回填段）——本文件不持有
- * 字段映射实现。
+ * type + 注销 status 视图 + 注销 reason 事实的结清视图——回填 outcome 读结清视图
+ * （§3.3.6 权威通道），与 delivery-port 快照基线同一扫描规则，MF-2-1；回填时序
+ * 背景见 index.ts collectResults 回填段）——本文件不持有字段映射实现。
  */
 
 /**