@zhushanwen/pi-goal 0.6.2 → 0.6.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-goal",
-  "version": "0.6.2",
+  "version": "0.6.4",
   "description": "Codex-style /goal command for Pi — persistent goal-driven autonomous loop with evidence-based completion, token/time budgets, blocked detection, and steering templates.",
   "type": "module",
   "main": "src/index.ts",

package/src/__tests__/event-adapter.test.ts

@@ -65,6 +65,7 @@ function makeFakeCtx(overrides?: {
 	aborted?: boolean;
 	hasUI?: boolean;
 	contextUsage?: { tokens?: number; contextWindow?: number };
+	entries?: unknown[];
 }): { ctx: ExtensionContext; calls: RecordedCall[] } {
 	const calls: RecordedCall[] = [];
 	const signal = { aborted: overrides?.aborted ?? false } as AbortSignal;
@@ -87,7 +88,7 @@ function makeFakeCtx(overrides?: {
 				bold: (text: string) => text,
 			},
 		},
-		sessionManager: { getEntries: () => [], getBranch: () => undefined },
+		sessionManager: { getEntries: () => overrides?.entries ?? [], getBranch: () => undefined },
 	} as unknown as ExtensionContext;
 	return { ctx, calls };
 }
@@ -179,6 +180,153 @@ describe("handleAgentEnd — continuation", () => {
 		expect(sendContext).toHaveLength(1);
 		expect(sendContext[0]!.content).toContain("[GOAL]");
 	});
+
+	// ── pending 守卫：background subagent/workflow 运行时不死循环 ──
+
+	it("有活跃 pending → 不发 continuation（pending 守卫生效）", async () => {
+		const { pi, calls: piCalls } = makeFakePi();
+		const { ctx, calls: ctxCalls } = makeFakeCtx({
+			entries: [
+				{ type: "custom", customType: "pending:register", data: { id: "bg-1", type: "subagent", name: "worker" } },
+			],
+		});
+		const session = createGoalSession();
+		session.state = makeRunningState({ tokensUsed: 200, lastTurnTokensUsed: 0 });
+
+		await handleAgentEnd(pi, session, ctx);
+		const all = allCalls(piCalls, ctxCalls);
+
+		const followUp = all.filter(
+			(c) => c.kind === "sendContext" && (c.payload as { deliverAs?: string } | undefined)?.deliverAs === "followUp",
+		);
+		expect(followUp).toHaveLength(0); // 有活跃 pending，不发 continuation
+	});
+
+	it("pending register 已 unregister → 差集归零，正常发 continuation", async () => {
+		const { pi, calls: piCalls } = makeFakePi();
+		const { ctx, calls: ctxCalls } = makeFakeCtx({
+			entries: [
+				{ type: "custom", customType: "pending:register", data: { id: "bg-1" } },
+				{ type: "custom", customType: "pending:unregister", data: { id: "bg-1" } },
+			],
+		});
+		const session = createGoalSession();
+		session.state = makeRunningState({ tokensUsed: 200, lastTurnTokensUsed: 0 });
+
+		await handleAgentEnd(pi, session, ctx);
+		const all = allCalls(piCalls, ctxCalls);
+
+		const followUp = all.filter(
+			(c) => c.kind === "sendContext" && (c.payload as { deliverAs?: string } | undefined)?.deliverAs === "followUp",
+		);
+		expect(followUp).toHaveLength(1);
+	});
+
+	it("pending expiresAt 已过期 → 仍判活跃不发 continuation（刻意不校验 TTL）", async () => {
+		const { pi, calls: piCalls } = makeFakePi();
+		const { ctx, calls: ctxCalls } = makeFakeCtx({
+			entries: [
+				{ type: "custom", customType: "pending:register", data: { id: "bg-1", expiresAt: Date.now() - 1000 } },
+			],
+		});
+		const session = createGoalSession();
+		session.state = makeRunningState({ tokensUsed: 200, lastTurnTokensUsed: 0 });
+
+		await handleAgentEnd(pi, session, ctx);
+		const all = allCalls(piCalls, ctxCalls);
+
+		const followUp = all.filter(
+			(c) => c.kind === "sendContext" && (c.payload as { deliverAs?: string } | undefined)?.deliverAs === "followUp",
+		);
+		expect(followUp).toHaveLength(0); // 过期仍判活跃，避免长任务死循环复现
+	});
+
+	it("有活跃 pending → appendEntry goal:log 诊断记录（多元素计数 + ids 透出）", async () => {
+		const { pi, states } = makeFakePi();
+		const { ctx } = makeFakeCtx({
+			entries: [
+				{ type: "custom", customType: "pending:register", data: { id: "bg-1" } },
+				{ type: "custom", customType: "pending:register", data: { id: "bg-2" } },
+			],
+		});
+		const session = createGoalSession();
+		session.state = makeRunningState({ tokensUsed: 200, lastTurnTokensUsed: 0 });
+
+		await handleAgentEnd(pi, session, ctx);
+
+		// goal:log 走 appendEntry（非 goal-history）→ 进 states
+		const deferredLog = states.find(
+			(s) =>
+				(s as { component?: string } | undefined)?.component === "goal:agent-end" &&
+				/continuation deferred/.test(String((s as { message?: string } | undefined)?.message ?? "")),
+		);
+		expect(deferredLog).toBeDefined();
+		const data = (deferredLog as { data?: { activePending?: number; ids?: string[] } } | undefined)?.data;
+		expect(data?.activePending).toBe(2); // 多元素计数（替代原 >=1 弱断言）
+		expect(data?.ids).toEqual(["bg-1", "bg-2"]); // ids 透出
+	});
+
+	it("重复 register 同 id → 去重计为 1（seen.has 守卫）", async () => {
+		const { pi, calls: piCalls, states } = makeFakePi();
+		const { ctx, calls: ctxCalls } = makeFakeCtx({
+			entries: [
+				{ type: "custom", customType: "pending:register", data: { id: "bg-1" } },
+				{ type: "custom", customType: "pending:register", data: { id: "bg-1" } },
+			],
+		});
+		const session = createGoalSession();
+		session.state = makeRunningState({ tokensUsed: 200, lastTurnTokensUsed: 0 });
+
+		await handleAgentEnd(pi, session, ctx);
+		const all = allCalls(piCalls, ctxCalls);
+
+		// 守卫触发：count>0 不发 continuation
+		const followUp = all.filter(
+			(c) => c.kind === "sendContext" && (c.payload as { deliverAs?: string } | undefined)?.deliverAs === "followUp",
+		);
+		expect(followUp).toHaveLength(0);
+		// seen 去重：2 条同 id register 计为 1（非 2）
+		const deferredLog = states.find(
+			(s) => (s as { component?: string } | undefined)?.component === "goal:agent-end",
+		);
+		expect((deferredLog as { data?: { activePending?: number } } | undefined)?.data?.activePending).toBe(1);
+	});
+
+	it("非字符串/缺失 id 的 register → 被忽略，正常发 continuation（typeof id 防御）", async () => {
+		const { pi, calls: piCalls } = makeFakePi();
+		const { ctx, calls: ctxCalls } = makeFakeCtx({
+			entries: [
+				{ type: "custom", customType: "pending:register", data: { id: 123 } }, // 数字 id（非字符串）
+				{ type: "custom", customType: "pending:register", data: {} }, // 无 id
+			],
+		});
+		const session = createGoalSession();
+		session.state = makeRunningState({ tokensUsed: 200, lastTurnTokensUsed: 0 });
+
+		await handleAgentEnd(pi, session, ctx);
+		const all = allCalls(piCalls, ctxCalls);
+
+		// count=0，守卫不触发，走正常 continuation
+		const followUp = all.filter(
+			(c) => c.kind === "sendContext" && (c.payload as { deliverAs?: string } | undefined)?.deliverAs === "followUp",
+		);
+		expect(followUp).toHaveLength(1);
+	});
+
+	it("无 pending entries → 正常发 continuation（回归保护）", async () => {
+		const { pi, calls: piCalls } = makeFakePi();
+		const { ctx, calls: ctxCalls } = makeFakeCtx(); // getEntries 默认空
+		const session = createGoalSession();
+		session.state = makeRunningState({ tokensUsed: 200, lastTurnTokensUsed: 0 });
+
+		await handleAgentEnd(pi, session, ctx);
+		const all = allCalls(piCalls, ctxCalls);
+
+		const followUp = all.filter(
+			(c) => c.kind === "sendContext" && (c.payload as { deliverAs?: string } | undefined)?.deliverAs === "followUp",
+		);
+		expect(followUp).toHaveLength(1);
+	});
 });
 
 // ── handleAgentEnd：并发保护（G-021）+ stale（G-020）───
@@ -339,53 +487,14 @@ describe("handleBeforeAgentStart", () => {
 
 	// ── pending-notifications（W2 跨扩展集成）───────────────────
 
-	it("有活跃 pending operations → 注入提示含 pending 数量", async () => {
-		const { pi } = makeFakePi();
-		// 创建带 pending:register entries 的 ctx
-		const entries = [
-			{ type: "custom", customType: "pending:register", data: { id: "wf-1", type: "workflow", name: "test-wf" } },
-			{ type: "custom", customType: "pending:register", data: { id: "bg-1", type: "subagent", name: "worker" } },
-		];
-		const ctx = {
-			hasUI: true,
-			signal: { aborted: false } as AbortSignal,
-			getContextUsage: () => undefined,
-			ui: {
-				notify: vi.fn(),
-				setStatus: vi.fn(),
-				setWidget: vi.fn(),
-				theme: { fg: (_c: string, t: string) => t, bold: (t: string) => t },
-			},
-			sessionManager: { getEntries: () => entries, getBranch: () => undefined },
-		} as unknown as ExtensionContext;
-		const session = createGoalSession();
-		session.state = makeRunningState();
-
-		const result = await handleBeforeAgentStart(pi, session, ctx);
-
-		expect(result).toBeDefined();
-		expect(result!.message.customType).toBe("goal-context");
-		expect(result!.message.content).toContain("2 pending async operation(s)");
-	});
-
-	it("有 pending register 但已 unregister → 不注入提示", async () => {
+	it("有活跃 pending entries → 注入 content 不含 pending 提示（pendingHint 已移除）", async () => {
 		const { pi } = makeFakePi();
-		const entries = [
-			{ type: "custom", customType: "pending:register", data: { id: "wf-1", type: "workflow", name: "test-wf" } },
-			{ type: "custom", customType: "pending:unregister", data: { id: "wf-1" } },
-		];
-		const ctx = {
-			hasUI: true,
-			signal: { aborted: false } as AbortSignal,
-			getContextUsage: () => undefined,
-			ui: {
-				notify: vi.fn(),
-				setStatus: vi.fn(),
-				setWidget: vi.fn(),
-				theme: { fg: (_c: string, t: string) => t, bold: (t: string) => t },
-			},
-			sessionManager: { getEntries: () => entries, getBranch: () => undefined },
-		} as unknown as ExtensionContext;
+		const { ctx } = makeFakeCtx({
+			entries: [
+				{ type: "custom", customType: "pending:register", data: { id: "wf-1", type: "workflow", name: "test-wf" } },
+				{ type: "custom", customType: "pending:register", data: { id: "bg-1", type: "subagent", name: "worker" } },
+			],
+		});
 		const session = createGoalSession();
 		session.state = makeRunningState();
 
@@ -393,6 +502,7 @@ describe("handleBeforeAgentStart", () => {
 
 		expect(result).toBeDefined();
 		expect(result!.message.customType).toBe("goal-context");
+		// pendingHint 已删除：pending 感知交给 LLM 调 pending_notifications tool（mandatory）
 		expect(result!.message.content).not.toContain("pending async operation");
 	});
 

package/src/__tests__/goal-control-prompt.test.ts

@@ -61,6 +61,22 @@ describe("goal_control description — 含参数结构反例（Don't 段）", ()
 	});
 });
 
+describe("goal_control promptGuidelines — complete/report_blocked 主动触发引导（防不主动收尾）", () => {
+	// promptGuidelines 进 system prompt guidelines 段（强信号），是修复 complete/report_blocked
+	// 「该主动调但不调」的核心载体。用源码断言锁定两条正向触发引导，防止后续重构删掉。
+	it("源码含 promptGuidelines 字段", () => {
+		expect(ADAPTER_SRC).toMatch(/promptGuidelines:\s*\[/);
+	});
+
+	it("promptGuidelines 含 complete 主动触发信号（proactively + objective is actually achieved）", () => {
+		expect(ADAPTER_SRC).toMatch(/complete:.*proactively call.*objective is actually achieved/s);
+	});
+
+	it("promptGuidelines 含 report_blocked 主动触发信号（proactively + ≥3 approaches）", () => {
+		expect(ADAPTER_SRC).toMatch(/report_blocked:.*proactively call.*≥3 distinct alternative approaches/s);
+	});
+});
+
 describe("goal_control runtime 错误文案 — 含 'Correct:' 纠正正例（≥4 处）", () => {
 	it("源码含 ≥4 处 'Correct:' 纠错文案（4 条 required throw 各一带正例）", () => {
 		// objective/slug/evidence/reason 四条必填 throw 各应带完整 JSON 正例，

package/src/adapters/event-handlers/agent-end.ts

@@ -28,6 +28,7 @@ import {
 } from "../../projection/prompts";
 import { persistAndUpdate, tickState } from "../../service";
 import type { GoalSession } from "../../session";
+import type { SessionEntryLike } from "../../ports";
 import { buildPorts } from "../ports";
 import { makeStaleChecker } from "./shared";
 
@@ -169,9 +170,61 @@ async function handleContinuation(
 	// 终态守卫：persistAndUpdate 可能把 goal 转为 budget_limited/time_limited 终态。
 	// 此时不应发 continuation（deliverAs:"followUp" 会触发新 turn，让已耗尽预算的 agent 再跑一轮）。
 	if (isTerminalStatus(state.status)) return;
+	// pending 守卫：有活跃 background subagent/workflow 时不发 continuation。
+	// 靠 subagent/workflow 完成时 sendMessage({triggerTurn:true,deliverAs:"steer"}) 自然唤醒主 agent；
+	// goal 抢先催会与异步任务完成通知叠加，形成“停不下来”的死循环——continuation 排入
+	// _followUpMessages 队列 → _handlePostAgentRun 的 hasQueuedMessages() 返回 true → agent.continue()
+	// 新 turn → 又 agent_end → 又 continuation。
+	// 刻意不校验 expiresAt：长任务 subagent（>1h TTL）完成时仍 triggerTurn 唤醒主 agent，
+	// 按 TTL 判非活跃会让死循环在长任务场景复现。
+	const pendingOps = countActivePendingOps(ctx.sessionManager.getEntries());
+	if (pendingOps.count > 0) {
+		pi.appendEntry("goal:log", {
+			timestamp: Date.now(),
+			level: "debug",
+			component: "goal:agent-end",
+			message: `continuation deferred: ${pendingOps.count} active pending operation(s)`,
+			data: { activePending: pendingOps.count, ids: pendingOps.ids },
+		});
+		// 用户可见反馈：goal 在等待后台任务完成而非卡死（deferred 无反馈时用户只看到
+		// goal active 但无产出，无法区分等待 vs 死循环）。
+		ctx.ui.notify(
+			`Goal waiting for ${pendingOps.count} background task(s) to complete.`,
+			"info",
+		);
+		return;
+	}
 	// 发 continuation（FR-8.7: 去 debounce 后才发）
 	buildPorts(pi, ctx).messaging.sendContextMessage(
 		continuationPrompt(state, state.timeUsedSeconds),
 		"followUp",
 	);
 }
+
+/** 类型守卫：unknown → Record<string, unknown>（替代裸 as 断言访问 entry.data.id）。 */
+const isRecord = (x: unknown): x is Record<string, unknown> =>
+	typeof x === "object" && x !== null;
+
+/** 计算活跃的 pending async operation（background subagent/workflow）数量。
+ *  读 session entries 里 customType="pending:register" 减 "pending:unregister" 的 id 差集。
+ *  刻意不校验 expiresAt（见 handleContinuation 守卫注释）。 */
+function countActivePendingOps(
+	entries: readonly SessionEntryLike[],
+): { count: number; ids: string[] } {
+	const unregistered = new Set<string>();
+	for (const e of entries) {
+		if (e.type !== "custom" || e.customType !== "pending:unregister") continue;
+		const id = isRecord(e.data) ? e.data.id : undefined;
+		if (typeof id === "string") unregistered.add(id);
+	}
+	const activeIds: string[] = [];
+	const seen = new Set<string>();
+	for (const e of entries) {
+		if (e.type !== "custom" || e.customType !== "pending:register") continue;
+		const id = isRecord(e.data) ? e.data.id : undefined;
+		if (typeof id !== "string" || unregistered.has(id) || seen.has(id)) continue;
+		seen.add(id);
+		activeIds.push(id);
+	}
+	return { count: activeIds.length, ids: activeIds };
+}

package/src/adapters/event-handlers/before-agent-start.ts

@@ -15,7 +15,7 @@
  * contextInjectionPrompt 恒定建议 plan mode（AI 自行决定是否用）。
  */
 
-import type { CustomEntry, ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 
 import { AUTO_CLEAR_TURNS, CONTEXT_USAGE_RATIO_LIMIT } from "../../constants";
 import { isActiveStatus, isTerminalStatus } from "../../engine/goal";
@@ -33,14 +33,6 @@ interface BeforeAgentStartResult {
 	};
 }
 
-/** 类型守卫：把 SDK 的 SessionEntry 联合收窄到 CustomEntry。
- *  SessionEntry 现为联合类型（SessionMessageEntry | CompactionEntry | CustomEntry | ...），
- *  只有 CustomEntry 带 customType/data（pending:register/unregister 由 pi.appendEntry 落地，
- *  type 恒为 "custom"）。读取前必须先收窄。 */
-function isCustomEntry(e: { type: string }): e is CustomEntry {
-	return e.type === "custom";
-}
-
 export async function handleBeforeAgentStart(
 	pi: ExtensionAPI,
 	session: GoalSession,
@@ -69,47 +61,12 @@ export async function handleBeforeAgentStart(
 
 	// 正常 context injection。
 	// 全解耦：planAvailable 恒 true（contextInjectionPrompt 恒定建议 plan mode，AI 自行决定）。
-	// pending-notifications：若有活跃的异步操作，注入等待提示。
-	// 读取 pending:register/unregister entry 算差集，并校验 expiresAt（TTL 过期的视为非活跃）。
-	// pending-notifications 的 rebuildFromEntries 在其 session_start 已 flush 跨 session/过期残留，
-	// 但同一 session 内超时未 unregister 的 entry（如崩溃恢复遗漏）需此处完补以防误报 active。
-	const now = Date.now();
-	const entries = ctx.sessionManager.getEntries();
-	// pending:register/unregister 由 pi.appendEntry 落地为 CustomEntry（type:"custom"）。
-	// 先用 isCustomEntry 收窄联合类型，再读 customType/data。
-	const customEntries = entries.filter(isCustomEntry);
-	const pendingUnregisters = new Set(
-		customEntries.filter((e) => e.customType === "pending:unregister").map((e) => (e.data as Record<string, unknown>)?.id),
-	);
-	const activePending = customEntries.filter((e) => {
-		if (e.customType !== "pending:register") return false;
-		const id = (e.data as Record<string, unknown>)?.id;
-		if (pendingUnregisters.has(id)) return false;
-		// TTL 过期视为非活跃（expiresAt 缺失或类型错误时宽容处理为活跃）
-		const expiresAt = (e.data as Record<string, unknown>)?.expiresAt;
-		if (typeof expiresAt === "number" && expiresAt <= now) return false;
-		return true;
-	});
-	const pendingHint = activePending.length > 0
-		? `\nNote: There are ${activePending.length} pending async operation(s) running. Consider waiting for them to complete before starting new work.`
-		: "";
-
-	pi.appendEntry("goal:log", {
-		timestamp: Date.now(),
-		level: "debug",
-		component: "goal:before-agent-start",
-		message: "pending entries computed",
-		data: {
-			activePending: activePending.length,
-			injectHint: activePending.length > 0,
-			pendingIds: activePending.map((e) => (e.data as Record<string, unknown>)?.id),
-		},
-	});
-
+	// pending 感知由 LLM 自行调 pending_notifications tool（mandatory）查询当前活跃异步操作，
+	// goal 不在此注入——避免与 tool 查询结果形成双信息源不一致（tool 是 EventBus+entries 维护的权威源）。
 	return {
 		message: {
 			customType: "goal-context",
-			content: contextInjectionPrompt(session.state, session.state.timeUsedSeconds, true) + pendingHint,
+			content: contextInjectionPrompt(session.state, session.state.timeUsedSeconds, true),
 			display: false,
 		},
 	};

package/src/adapters/goal-control-adapter.ts

@@ -376,6 +376,18 @@ Don't:
 - complete when no goal is active — create or resume one first (fails with 'Goal mode not active').`,
 		promptSnippet:
 			"Use goal_control to manage the thread goal: create (with slug + objective, only when user asks) or complete (with evidence) or report_blocked (with reason, after trying alternatives).",
+		// promptGuidelines：进 system prompt guidelines 段（强信号位）。
+		// 聚焦 complete/report_blocked 的正向触发引导——这两个 action 是「该主动调但实际不调」
+		// 的核心症结（contextInjectionPrompt 规则 3/4 虽引导，但属 goal 活跃时才注入的 steering，
+		// 措辞被动；此处给 system prompt 层的常驻强信号）。
+		// create 不列：其劝退已在 description + promptSnippet 双重覆盖，此处第三重冗余反而稀释
+		// complete/report_blocked 的注意力权重（P14 约束衰减）。
+		promptGuidelines: [
+			// 全解耦下 todo 非硬前置——objective 实际达成才算（与 handleComplete「todo 由 AI 自判」一致）
+			"complete: proactively call when the active goal's objective is actually achieved, not merely in progress. Evidence must be concrete artifacts (files changed, tests green, commands run). Finishing all todos (incl. verification todos) is the usual readiness signal, but the real bar is the objective being met — you decide.",
+			// P3 数字阈值 ≥3，与 params.reason description 的 "at least 3 approaches" 双重冗余
+			"report_blocked: proactively call when genuinely blocked after ≥3 distinct alternative approaches — not for hard/slow work or uncertainty. State the blocker and what you tried. Do NOT silently stop or leave the goal hanging.",
+		],
 		executionMode: "sequential",
 		parameters: GoalControlParams,
 

package/src/projection/__tests__/prompts.test.ts

@@ -212,12 +212,11 @@ describe("contextInjectionPrompt", () => {
 		expect(out).toContain("test objective");
 	});
 
-	it("要求建 todo（含 verification todo，FR-6/#10）", () => {
+	it("要求建 todo（含 verification todo）", () => {
 		const state = makeState();
 		const out = contextInjectionPrompt(state, 0);
 		expect(out).toContain("todo tool");
-		expect(out).toContain("verification todos");
-		expect(out).toContain("isVerification intent");
+		expect(out).toContain("separate todo for verification checks");
 	});
 
 	it("无 goal_manager 引用（#1 清理后）", () => {

package/src/projection/prompts.ts

@@ -239,7 +239,7 @@ export function contextInjectionPrompt(
 		`Track work with todos:\n` +
 		`Before working, create todos for the task breakdown using the todo tool:\n` +
 		`- Each concrete step becomes a todo item\n` +
-		`- Include verification todos (e.g., 'run tests', 'typecheck') with isVerification intent\n` +
+		`- Add a separate todo for verification checks (e.g., 'run tests', 'typecheck')\n` +
 		`- Track progress by updating todo status as you complete items\n` +
 		planSection +
 		`\n` +