@zhushanwen/pi-smart-context 0.1.4 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-smart-context",
-  "version": "0.1.4",
+  "version": "0.3.0",
   "type": "module",
   "main": "index.ts",
   "xyz-agent": {
@@ -36,8 +36,9 @@
     "pi-package"
   ],
   "dependencies": {
-    "@zhushanwen/pi-extension-logger": "0.4.1",
-    "@zhushanwen/pi-llm-shared": "0.5.1"
+    "@zhushanwen/pi-ext-guards": "0.3.0",
+    "@zhushanwen/pi-extension-logger": "0.6.0",
+    "@zhushanwen/pi-llm-shared": "0.7.0"
   },
   "devDependencies": {
     "@vitest/coverage-v8": "^4.1.9",

package/src/__tests__/compact-handler.test.ts

@@ -1,7 +1,9 @@
 import { beforeEach, describe, expect, it, vi } from "vitest";
 
-// mock pi SDK：接管路径的单测不触网（same-mode 输入链 + cross-mode 原生组装都替换）
-vi.mock("@earendil-works/pi-coding-agent", () => ({
+// mock pi SDK：接管路径的单测不触网（same-mode 输入链 + cross-mode 原生组装都替换）。
+// importOriginal 保留真实模块（含 pure.js 依赖的 estimateTokens），其余覆盖项在后
+vi.mock("@earendil-works/pi-coding-agent", async (importOriginal) => ({
+	...(await importOriginal<typeof import("@earendil-works/pi-coding-agent")>()),
 	buildSessionContext: (entries: unknown[]) => ({ messages: [{ role: "user", content: "history" }] }),
 	convertToLlm: (messages: unknown[]) => messages,
 	compact: vi.fn(),
@@ -16,41 +18,59 @@ import { callSameModelCompaction } from "../llm.js";
 import {
 	createBeforeCompactHandler,
 	createTakeoverState,
-	type BeforeCompactLikeEvent,
 } from "../compact-handler.js";
 import { normalizeSmartContextConfig, type SmartContextConfig } from "../pure.js";
-import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI, ExtensionContext, SessionBeforeCompactEvent } from "@earendil-works/pi-coding-agent";
 
-function makeEvent(overrides?: Partial<BeforeCompactLikeEvent["preparation"]>): BeforeCompactLikeEvent {
+// assistant 消息形态锁定为单 text 块（设计 §8.3）：必填标量字段补齐 + content 不得追加
+// thinking/toolCall 块——追加会抬高 shadowedTokens，使「新旧口径数值等价」声明静默失效
+function makeEvent(overrides?: Partial<SessionBeforeCompactEvent["preparation"]>): SessionBeforeCompactEvent {
 	return {
 		type: "session_before_compact",
 		preparation: {
 			firstKeptEntryId: "kept-1",
 			messagesToSummarize: [
-				{ role: "user", content: "x".repeat(4_000) },
-				{ role: "assistant", content: "y".repeat(4_000) },
+				{ role: "user", content: "x".repeat(4_000), timestamp: 0 },
+				{
+					role: "assistant",
+					content: [{ type: "text", text: "y".repeat(4_000) }],
+					api: "openai-completions",
+					provider: "zai",
+					model: "glm",
+					usage: {
+						input: 1, output: 1, cacheRead: 0, cacheWrite: 0, totalTokens: 2,
+						cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+					},
+					stopReason: "stop",
+					timestamp: 0,
+				},
 			],
 			turnPrefixMessages: [],
 			isSplitTurn: false,
 			tokensBefore: 500_000,
 			fileOps: { read: new Set(["/a.ts"]), written: new Set(), edited: new Set() },
+			settings: { enabled: true, reserveTokens: 16_384, keepRecentTokens: 20_000 },
 			...overrides,
 		},
 		branchEntries: [],
 		customInstructions: undefined,
 		reason: "manual",
 		willRetry: false,
+		signal: new AbortController().signal,
 	};
 }
 
-function makeCtx(): ExtensionContext {
+function makeCtx(crossModel?: { provider: string; id: string } | null): ExtensionContext {
 	return {
 		model: { provider: "zai", id: "glm" },
 		getSystemPrompt: () => "sys",
 		sessionManager: { getSessionId: () => "s1", getSessionFile: () => "/tmp/s1.jsonl" },
 		modelRegistry: {
 			getApiKeyAndHeaders: async () => ({ ok: true, apiKey: "k" }),
-			find: () => null,
+			// resolveRef 精确匹配：仅 (provider,id) 同时命中时返回模型（配合 hasConfiguredAuth 放行）
+			find: (provider: string, id: string) =>
+				crossModel && provider === crossModel.provider && id === crossModel.id ? crossModel : null,
+			hasConfiguredAuth: () => crossModel != null,
 		},
 	} as unknown as ExtensionContext;
 }
@@ -84,11 +104,12 @@ describe("session_before_compact 接管 handler", () => {
 		expect(mockedCall).not.toHaveBeenCalled();
 	});
 
-	it("same-model 成功 → compaction 带 engine/mode 标记 + preamble + fileOps 清单 + transcript 指针", async () => {
+	it("same-model 成功 → compaction 带 engine/mode/model 标记 + preamble + fileOps 清单 + transcript 指针", async () => {
 		mockedCall.mockResolvedValue({ ok: true, text: "summary body", usage: { input: 1, output: 2 } });
 		const { handler } = makeHandler(normalizeSmartContextConfig({ compactModel: { type: "ref", ref: "" } }));
 		const decision = await handler(makeEvent(), makeCtx());
-		expect(decision.compaction?.details).toEqual({ engine: "smart-context", mode: "same-model" });
+		// details.model = `${ctx.model.provider}/${ctx.model.id}`（§3.3 ①，用量归属数据源）
+		expect(decision.compaction?.details).toEqual({ engine: "smart-context", mode: "same-model", model: "zai/glm" });
 		expect(decision.compaction?.summary).toContain("summary body");
 		// D13-9 preamble 在最前；D11-2 fileOps；D13-4 transcript
 		expect(decision.compaction?.summary.startsWith("This is an automatically generated checkpoint")).toBe(true);
@@ -115,10 +136,36 @@ describe("session_before_compact 接管 handler", () => {
 		expect(mockedNative).not.toHaveBeenCalled();
 	});
 
+	it("cross-model 成功 → details.model=compactModel 解析结果，native details 字段保留", async () => {
+		mockedNative.mockResolvedValue({
+			summary: "native checkpoint",
+			firstKeptEntryId: "kept-1",
+			tokensBefore: 500_000,
+			usage: {
+				input: 5, output: 6, cacheRead: 0, cacheWrite: 0, totalTokens: 11,
+				cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+			},
+			details: { nativeMarker: "keep" },
+		});
+		const { handler } = makeHandler(
+			normalizeSmartContextConfig({ compactModel: { type: "ref", ref: "xiaomi/mimo" } }),
+		);
+		const decision = await handler(makeEvent(), makeCtx({ provider: "xiaomi", id: "mimo" }));
+		// details.model = `${resolveModel(...).provider}/${id}`（§3.3 ①）；native details 字段原样保留（spread 增量，不改变其他字段）
+		expect(decision.compaction?.details).toEqual({
+			engine: "smart-context",
+			mode: "cross-model",
+			model: "xiaomi/mimo",
+			nativeMarker: "keep",
+		});
+		// nativeCompact 收到的 model 就是解析结果（details.model 与实际执行模型同源）
+		expect(mockedNative.mock.calls[0][1]).toEqual({ provider: "xiaomi", id: "mimo" });
+	});
+
 	it("收缩校验失败（摘要 ≥ 被压段）→ 拒绝 + 同段记录不重试（D13-1）", async () => {
 		mockedCall.mockResolvedValue({ ok: true, text: "z".repeat(10_000) });
 		const { handler, state } = makeHandler(normalizeSmartContextConfig({}));
-		const event = makeEvent({ messagesToSummarize: [{ role: "user", content: "x".repeat(400) }] });
+		const event = makeEvent({ messagesToSummarize: [{ role: "user", content: "x".repeat(400), timestamp: 0 }] });
 		await expect(handler(event, makeCtx())).resolves.toEqual({});
 		expect(state.inflatedSegments.has("kept-1")).toBe(true);
 		// 同段第二次直接跳过（不再调 LLM）

package/src/__tests__/index-generation.test.ts

@@ -0,0 +1,105 @@
+// src/__tests__/index-generation.test.ts
+//
+// G1 装配级测试（crash-resilience D1，参照 scheduler __tests__/index-generation.test.ts 形态）：
+// index.ts 装配点向 registerCompactContextTool 注入的 deps.isCtxStale 必须是 live 绑定
+// wrapper（() => isCtxStale()）——registerCompactContextTool 在 factory 体同步执行，简写
+// 属性 { isCtxStale } 会把该行时刻的初始 () => false 快照进 deps 对象，session_start
+// handler 内的重新赋值不回写已构造对象 → compact onComplete/onError（E1 实锤崩溃点）
+// 守卫的前置代际检查恒不生效，stale 分诊 100% 退化为 PS-30 文案兜底。
+//
+// 可区分快照 vs live 的唯一拓扑是 factory 重跑（生产主路径：pi 每次 session 替换
+// newSession/fork/switchSession 都重跑 factory 函数体，loader.ts extensionCache 只缓存
+// factory 函数对象）：同闭包内 fire session_start 后本闭包恒是当前代（isCtxStale 读到
+// false，与快照实现值不可区分）；只有第一代 deps 在第二代 session_start 递增模块级
+// sessionGeneration 后必须翻 true——快照实现在此恒 false，正是生产失效路径。
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+// Mock 共享 logger（compact-handler 顶层 createLogger；同 scheduler index-generation 形态）
+const { loggerMock } = vi.hoisted(() => ({
+	loggerMock: { debug: vi.fn(), warn: vi.fn(), error: vi.fn() },
+}));
+vi.mock("@zhushanwen/pi-extension-logger", () => ({
+	getLogger: () => loggerMock,
+	createLogger: () => loggerMock,
+	setPiHandle: vi.fn(),
+}));
+
+// 装配捕获：mock tool.js，逐次登记 index.ts 传入的 deps（同 scheduler 捕获 runtime 构造第三参）
+const { registerCompactContextToolCalls } = vi.hoisted(() => ({
+	registerCompactContextToolCalls: [] as Array<{ deps?: { isCtxStale?: () => boolean } }>,
+}));
+vi.mock("../tool.js", () => ({
+	registerCompactContextTool: (_pi: unknown, deps?: { isCtxStale?: () => boolean }) => {
+		registerCompactContextToolCalls.push({ deps });
+	},
+}));
+
+import smartContextExtension from "../index.js";
+
+/** 最小 fake pi：装配路径只消费 on（事件接线）；registerTool/sendUserMessage 兜底。 */
+function createMockPi(): {
+	pi: ExtensionAPI
+	events: Map<string, (...args: unknown[]) => void>
+} {
+	const events = new Map<string, (...args: unknown[]) => void>();
+	const pi = {
+		registerTool: vi.fn(),
+		on: (event: string, handler: (...args: unknown[]) => void) => events.set(event, handler),
+		sendUserMessage: vi.fn(),
+	} as unknown as ExtensionAPI;
+	return { pi, events };
+}
+
+/** 触发 session_start（handler 只更新模块级代数与闭包状态，ctx 不被读取）。 */
+function fireSessionStart(events: Map<string, (...args: unknown[]) => void>): void {
+	const sessionStart = events.get("session_start");
+	expect(sessionStart).toBeDefined();
+	sessionStart!({ type: "session_start" }, {} as ExtensionContext);
+}
+
+describe("G1: compact 工具 deps.isCtxStale live 绑定（crash-resilience D1 装配回归）", () => {
+	beforeEach(() => {
+		registerCompactContextToolCalls.length = 0;
+	});
+
+	it("factory 同步构造 deps：注入的是函数，首个 session_start 前恒 false（安全默认），fire 后本闭包为当前代", () => {
+		const { pi, events } = createMockPi();
+		smartContextExtension(pi);
+		expect(registerCompactContextToolCalls).toHaveLength(1);
+		const isCtxStale = registerCompactContextToolCalls[0]!.deps?.isCtxStale;
+		expect(isCtxStale).toBeTypeOf("function");
+
+		// 首个 session_start 前：无 session，恒 false（安全默认）
+		expect(isCtxStale!()).toBe(false);
+
+		// fire 后本闭包被装配为当前代 → false；同闭包重复 fire（rpc-mode bindExtensions
+		// 重调）后仍为当前代。注意：单闭包拓扑内 live wrapper 与快照实现的返回值同为
+		// false、不可区分——快照 vs live 的回归断言在下方 factory 重跑用例。
+		fireSessionStart(events);
+		expect(isCtxStale!()).toBe(false);
+		fireSessionStart(events);
+		expect(isCtxStale!()).toBe(false);
+	});
+
+	it("factory 重跑：第二次 factory + session_start 后，第一代 deps.isCtxStale 翻 true、第二代 false", () => {
+		// 第一代：独立 factory 执行 + session_start 装配
+		const first = createMockPi();
+		smartContextExtension(first.pi);
+		fireSessionStart(first.events);
+		const firstIsCtxStale = registerCompactContextToolCalls[0]!.deps!.isCtxStale!;
+		expect(firstIsCtxStale()).toBe(false); // 第一代是当前代
+
+		// 第二代：再次独立执行 factory（模拟 newSession/fork/switchSession 的 factory 重跑，
+		// 新闭包；模块级 sessionGeneration 跨 factory 重跑保留）+ session_start
+		const second = createMockPi();
+		smartContextExtension(second.pi);
+		fireSessionStart(second.events);
+
+		// 核心回归断言：第一代 deps 读到第一代闭包重新赋值后的 isCtxStale，感知换代翻
+		// true（快照实现 = 简写属性 { isCtxStale }，在此恒 false——本用例的回归失败点）
+		expect(firstIsCtxStale()).toBe(true);
+		expect(registerCompactContextToolCalls[1]!.deps!.isCtxStale!()).toBe(false); // 第二代是当前代
+	});
+});

package/src/__tests__/pure.test.ts

@@ -5,6 +5,7 @@ import {
 	buildReinjectSection,
 	checkToolThresholdGuard,
 	computeFileListsLike,
+	estimateShadowedTokens,
 	estimateTextTokens,
 	findCrossedThresholds,
 	formatFileOperationsLike,
@@ -136,6 +137,42 @@ describe("摘要后处理纯函数（D11/D13）", () => {
 	});
 });
 
+describe("estimateShadowedTokens 口径契约（D2：与 pi estimateTokens 同源）", () => {
+	// 合法 AssistantMessage 形状的 fixture（block 数组 content，禁止 as 硬塞 string content——
+	// estimateTokens 对 string content 计 0，口径用例会静默失去判别力；设计 §8.3）。
+	// 不 import 名义类型：const 泛型保留 block 字面量形状，由 estimateShadowedTokens
+	// 参数类型（Parameters<typeof estimateTokens>[0]）在调用点结构校验。
+	function makeAssistantMessage<const C extends readonly unknown[]>(content: C) {
+		return {
+			role: "assistant" as const,
+			content,
+			api: "openai-completions",
+			provider: "zai",
+			model: "glm",
+			usage: {
+				input: 1, output: 1, cacheRead: 0, cacheWrite: 0, totalTokens: 2,
+				cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+			},
+			stopReason: "stop" as const,
+			timestamp: 0,
+		};
+	}
+
+	it("仅含 toolCall 块（arguments 大 JSON）→ > 0（旧 chars/4 口径漏计为 0）", () => {
+		const tokens = estimateShadowedTokens([
+			makeAssistantMessage([{ type: "toolCall", id: "c1", name: "edit", arguments: { content: "x".repeat(2_400) } }]),
+		]);
+		expect(tokens).toBeGreaterThan(0);
+	});
+
+	it("仅含 thinking 块 → > 0（旧 chars/4 口径漏计为 0）", () => {
+		const tokens = estimateShadowedTokens([
+			makeAssistantMessage([{ type: "thinking", thinking: "t".repeat(1_600) }]),
+		]);
+		expect(tokens).toBeGreaterThan(0);
+	});
+});
+
 describe("subagent 识别（R6）", () => {
 	it("PI_SUBAGENT_ROOT_SESSION_ID 存在即 subagent", () => {
 		expect(isSubagentProcess({ PI_SUBAGENT_ROOT_SESSION_ID: "s1" })).toBe(true);

package/src/compact-handler.ts

@@ -6,11 +6,13 @@
  * - same-model 模式：完整上下文 + 会话原 system prompt + tools + 末尾追加压缩指令（kv-cache 前缀命中）
  * - cross-model 模式：直接调用包导出的 compact(preparation, 压缩Model, ...)（原生组装零复刻，R4 结论）
  *
- * 输出 CompactionResult.details 携带 {engine:"smart-context", mode} 标记（D1 entry 标记）。
+ * 输出 CompactionResult.details 携带 {engine:"smart-context", mode, model} 标记（D1 entry 标记）。
+ * model = `${model.provider}/${model.id}`（执行压缩的实际模型）——用量页 compaction 归属数据源
+ * （usage-page-fixes §3.3 ①）；pi appendCompaction 对 details 逐字透传落盘（pi-semantics PS-28）。
  */
 
 import { buildSessionContext, compact as nativeCompact, convertToLlm } from "@earendil-works/pi-coding-agent";
-import type { CompactionResult, SessionEntry } from "@earendil-works/pi-coding-agent";
+import type { CompactionResult, SessionBeforeCompactEvent } from "@earendil-works/pi-coding-agent";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { createLogger } from "@zhushanwen/pi-extension-logger";
 import { resolveModel } from "@zhushanwen/pi-llm-shared";
@@ -30,6 +32,7 @@ import {
 	estimateTextTokens,
 	formatFileOperationsLike,
 	getCurrentModelId,
+	isGatingActive,
 	isSummaryInflated,
 	pickMode,
 	pickReinjectFiles,
@@ -37,31 +40,6 @@ import {
 	type SmartContextConfig,
 } from "./pure.js";
 
-/** session_before_compact 事件的宽松形状（消费字段收窄，不依赖 pi 事件类型导出）。 */
-export interface BeforeCompactLikeEvent {
-	type: "session_before_compact";
-	preparation: {
-		firstKeptEntryId: string;
-		messagesToSummarize: ReadonlyArray<{ role: string; content?: unknown }>;
-		turnPrefixMessages: ReadonlyArray<{ role: string }>;
-		isSplitTurn: boolean;
-		tokensBefore: number;
-		previousSummary?: string;
-		fileOps: FileOpsLike;
-	};
-	branchEntries: ReadonlyArray<unknown>;
-	customInstructions?: string;
-	reason: "manual" | "threshold" | "overflow";
-	willRetry: boolean;
-	signal?: AbortSignal;
-}
-
-/** handler 返回（SessionBeforeCompactResult 子集）。 */
-export interface BeforeCompactDecision {
-	cancel?: boolean;
-	compaction?: CompactionResult;
-}
-
 /** session 级接管状态（session_start 重建闭包，规范 Session 隔离）。 */
 export interface TakeoverState {
 	/** 接管连续失败计数（D13-3 熔断：≥3 停止接管）。 */
@@ -93,6 +71,8 @@ function warnLog(message: string, data?: unknown): void {
 export interface SmartContextDetails {
 	engine: "smart-context";
 	mode: "same-model" | "cross-model";
+	/** 执行压缩的模型 `${provider}/${modelId}`（用量归属数据源，usage-page-fixes §3.3 ①）。 */
+	model: string;
 }
 
 /** sessionManager 上会话文件字段/方法的宽松形状（D13-4，消费侧可选链兜底）。 */
@@ -169,7 +149,7 @@ function assembleSummary(
 async function generateSameMode(
 	pi: ExtensionAPI,
 	ctx: ExtensionContext,
-	event: BeforeCompactLikeEvent,
+	event: SessionBeforeCompactEvent,
 ): Promise<CompactionResult | null> {
 	const model = ctx.model;
 	if (!model) {
@@ -178,7 +158,7 @@ async function generateSameMode(
 	}
 	// AgentMessage[]（含 bash/custom 等扩展消息）→ 标准 Message[]（与主会话请求同源转换，
 	// convertToLlm 是 pi host 默认实现——同样的输入产生同样的输出，前缀缓存对齐的前提）
-	const fullMessages = convertToLlm(buildSessionContext(event.branchEntries as SessionEntry[]).messages);
+	const fullMessages = convertToLlm(buildSessionContext(event.branchEntries).messages);
 	const instructionMessage = {
 		role: "user" as const,
 		content: [{ type: "text" as const, text: buildSameModelInstruction(event.customInstructions) }],
@@ -219,7 +199,11 @@ async function generateSameMode(
 		firstKeptEntryId: event.preparation.firstKeptEntryId,
 		tokensBefore: event.preparation.tokensBefore,
 		usage: result.usage as CompactionResult["usage"],
-		details: { engine: "smart-context", mode: "same-model" } satisfies SmartContextDetails,
+		details: {
+			engine: "smart-context",
+			mode: "same-model",
+			model: `${model.provider}/${model.id}`,
+		} satisfies SmartContextDetails,
 	};
 }
 
@@ -230,7 +214,7 @@ async function generateSameMode(
  */
 async function generateCrossMode(
 	ctx: ExtensionContext,
-	event: BeforeCompactLikeEvent,
+	event: SessionBeforeCompactEvent,
 	config: SmartContextConfig,
 ): Promise<CompactionResult | null> {
 	const model = resolveModel(ctx, config.compactModel);
@@ -250,10 +234,8 @@ async function generateCrossMode(
 			Object.entries(auth.headers).filter((entry): entry is [string, string] => typeof entry[1] === "string"),
 		)
 		: undefined;
-	// preparation：BeforeCompactLikeEvent 的宽松形状是 nativeCompact 入参（CompactionPreparation，
-	// 含 settings 等未消费字段）的结构子集——运行时是 pi 原生事件对象，此处单层收窄断言
 	const result = await nativeCompact(
-		event.preparation as Parameters<typeof nativeCompact>[0],
+		event.preparation,
 		model,
 		auth.apiKey,
 		headers,
@@ -266,7 +248,12 @@ async function generateCrossMode(
 	// D13-2：原生 compact 内部对截断的处理沿用原生语义；此处补 engine 标记
 	return {
 		...result,
-		details: { ...(result.details as object | undefined), engine: "smart-context", mode: "cross-model" } as SmartContextDetails,
+		details: {
+			...(result.details as object | undefined),
+			engine: "smart-context",
+			mode: "cross-model",
+			model: `${model.provider}/${model.id}`,
+		} as SmartContextDetails,
 	};
 }
 
@@ -274,20 +261,21 @@ async function generateCrossMode(
  * session_before_compact handler 工厂。
  *
  * state 为 session 级闭包（由 src/index.ts 在 session_start 重建后传入）。
+ * 返回类型省略标注、由函数体对象字面量推断（{} / {compaction}）——SDK SessionBeforeCompactResult
+ * 不在包根导出（仅深层 dist 路径可见），显式标注该名不可 import；推断形状与 SDK 逐字段同形，
+ * 注册点 pi.on() 的 ExtensionHandler 泛型按结构兼容校验。
  */
 export function createBeforeCompactHandler(
 	pi: ExtensionAPI,
 	getState: () => TakeoverState,
 	loadConfigFn: () => SmartContextConfig,
-): (event: BeforeCompactLikeEvent, ctx: ExtensionContext) => Promise<BeforeCompactDecision> {
-	return async (event, ctx) => {
+) {
+	return async (event: SessionBeforeCompactEvent, ctx: ExtensionContext) => {
 		const config = loadConfigFn();
 		const currentModelId = getCurrentModelId(ctx.model);
 
 		// D5 门控：禁用/排除 → 空返回（pi 原生生成）
-		if (config.enabled !== true || currentModelId === "" || config.excludedModels.includes(currentModelId)) {
-			return {};
-		}
+		if (!isGatingActive(config, currentModelId)) return {};
 		const state = getState();
 
 		// D13-3 熔断：连续失败 ≥3 → 本 session 停止接管
@@ -325,7 +313,9 @@ export function createBeforeCompactHandler(
 			}
 
 			state.failStreak = 0;
-			debugLog(`takeover ok: mode=${mode} reason=${event.reason} summaryTokens=${summaryTokens}`);
+			debugLog(
+				`takeover ok: mode=${mode} reason=${event.reason} summaryTokens=${summaryTokens} shadowedTokens=${shadowedTokens}`,
+			);
 			return { compaction: result };
 		} catch (error) {
 			state.failStreak += 1;

package/src/index.ts

@@ -11,13 +11,13 @@
  */
 
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { guardStaleCtx, toErrorMessage } from "@zhushanwen/pi-ext-guards";
 import { setPiHandle } from "@zhushanwen/pi-extension-logger";
 
 import {
 	createBeforeCompactHandler,
 	createTakeoverState,
 	debugLog,
-	type BeforeCompactLikeEvent,
 	type TakeoverState,
 } from "./compact-handler.js";
 import { buildDownshiftNotice, buildSwitchNotice, buildThresholdReminder } from "./reminder.js";
@@ -32,29 +32,6 @@ import {
 	type EntryLike,
 } from "./pure.js";
 
-/** agent_settled 事件形状（无 payload）。 */
-interface AgentSettledLikeEvent {
-	type: "agent_settled";
-}
-
-/** model_select 事件形状。 */
-interface ModelSelectLikeEvent {
-	type: "model_select";
-	model: { provider?: string; id?: string; contextWindow?: number } | undefined;
-	previousModel: { provider?: string; id?: string; contextWindow?: number } | undefined;
-	source: string;
-}
-
-/** session_compact 事件形状（compactionEntry 只消费 type；interface 无隐式 index signature，
- * 禁用 `& Record<string, unknown>` 交叉目标——会破坏 on() 重载的参数逆变匹配）。 */
-interface SessionCompactLikeEvent {
-	type: "session_compact";
-	compactionEntry: { type: string };
-	fromExtension: boolean;
-	reason: "manual" | "threshold" | "overflow";
-	willRetry: boolean;
-}
-
 /** session 级闭包状态（规范：模块级仅工厂函数，状态在 session_start 重建）。 */
 interface SessionState {
 	takeover: TakeoverState;
@@ -67,6 +44,15 @@ function createSessionState(): SessionState {
 	return { takeover: createTakeoverState(), firedThresholds: new Set() };
 }
 
+// G1 代际检测（crash-resilience D1，同 scheduler/src/index.ts 的模块级代数计数器范式）：
+// 必须声明在模块级而非 factory 体内——pi 每次 session 替换（newSession/fork/switchSession）
+// 都重跑 extension factory 函数体（extensionCache 只缓存 factory 函数对象），闭包级声明
+// 每次重跑即重置，各代的 isCtxStale 恒 false。模块级声明下 extensionCache 命中期间共享
+// 同一模块绑定，计数器跨 factory 重跑保留递增：新代 session_start 递增后，旧代闭包捕获
+// 的代数从此小于模块值 → isCtxStale 生效。残余盲区（显式 reload 触发 jiti 重新 import
+// 产生全新模块环境）由 guardStaleCtx 的 STALE_CTX_MARKER 文案兜底分诊覆盖（PS-30 门禁）。
+let sessionGeneration = 0;
+
 /**
  * pi-smart-context extension 工厂函数。
  *
@@ -86,7 +72,16 @@ export default function smartContextExtension(pi: ExtensionAPI): void {
 	// session 级状态（session_start 重建闭包；模块级引用仅指向当前 session 的容器）
 	let state: SessionState = createSessionState();
 
+	// G1 代际比对闭包（isCtxStale）：session_start 装配本代比对（读实时模块级代数），
+	// 供下方事件回调与 compact 工具回调的 guardStaleCtx 前置检查使用——stale 分诊不依赖
+	// pi 错误文案。首个 session_start 前无 session，恒 false 为安全默认。
+	let isCtxStale: () => boolean = () => false;
+
 	pi.on("session_start", (_event: unknown, _ctx: ExtensionContext) => {
+		// 先递增模块级代数再装配：自此同模块环境内所有前代闭包的 isCtxStale 返回 true
+		sessionGeneration += 1;
+		const myGeneration = sessionGeneration;
+		isCtxStale = () => sessionGeneration !== myGeneration;
 		state = createSessionState();
 	});
 
@@ -96,19 +91,22 @@ export default function smartContextExtension(pi: ExtensionAPI): void {
 		() => state.takeover,
 		loadSmartContextConfig,
 	);
-	pi.on("session_before_compact", (event: BeforeCompactLikeEvent, ctx: ExtensionContext) =>
-		beforeCompact(event, ctx));
+	pi.on("session_before_compact", beforeCompact);
 
 	// ── 压缩完成：重置提醒档位（D3）──
-	pi.on("session_compact", (_event: SessionCompactLikeEvent, _ctx: ExtensionContext) => {
+	pi.on("session_compact", (_event, _ctx) => {
 		state.firedThresholds.clear();
 	});
 
 	// ── 工具注册（常驻，不可用态由 execute 运行时校验拒绝，D5）──
-	registerCompactContextTool(pi);
+	// isCtxStale 必须传 live 绑定 wrapper 而非简写属性：本行在 factory 体同步执行，简写
+	// { isCtxStale } 会把此刻的初始 () => false 快照进 deps 对象，上方 session_start
+	// handler 的重新赋值不回写已构造对象 → compact onComplete/onError（E1 实锤崩溃点）
+	// 守卫的前置代际检查恒不生效。wrapper 每次调用读闭包当前绑定。
+	registerCompactContextTool(pi, { isCtxStale: () => isCtxStale() });
 
 	// ── 阈值提醒（D3/D4）：agent_settled 越档检查 + followUp 一次性投递 ──
-	pi.on("agent_settled", (_event: AgentSettledLikeEvent, ctx: ExtensionContext) => {
+	pi.on("agent_settled", (_event, ctx) => {
 		const config = loadSmartContextConfig();
 		const modelId = getCurrentModelId(ctx.model);
 		if (!isGatingActive(config, modelId)) return;
@@ -123,12 +121,21 @@ export default function smartContextExtension(pi: ExtensionAPI): void {
 		const message = buildThresholdReminder(crossed, usage.tokens ?? 0, usage.contextWindow, compactionCount);
 		debugLog(`reminder fired: tiers=${crossed.join(",")} tokens=${usage.tokens}`);
 		// D4：followUp（agent 空闲后投递并触发一个 turn，可立即决定压缩）；
-		// 防循环：crossed 全部已标记 fired，提醒触发的 settled 不会重复发
-		pi.sendUserMessage(message, { deliverAs: "followUp" });
+		// 防循环：crossed 全部已标记 fired，提醒触发的 settled 不会重复发。
+		// 事件回调内直接调用捕获的 pi——session 替换窗口可能 stale（crash-resilience D1
+		// 普查接入点），守卫 stale 静默降级（不杀 pi 进程），非 stale 错误原样上抛。
+		guardStaleCtx(() => {
+			pi.sendUserMessage(message, { deliverAs: "followUp" });
+		}, {
+			isCtxStale,
+			label: "smart-context:threshold-reminder",
+			onStale: (error) => debugLog(`threshold reminder delivery skipped (stale ctx): ${toErrorMessage(error)}`),
+		});
 	});
 
 	// ── 模型切换：跨界通知 + downshift 提醒（D5，仅跨界时注入一次）──
-	pi.on("model_select", (event: ModelSelectLikeEvent, ctx: ExtensionContext) => {
+	// event 类型由 on() 重载上下文推导为 SDK ModelSelectEvent（不在包根导出，省略标注）
+	pi.on("model_select", (event, ctx) => {
 		const config = loadSmartContextConfig();
 		const modelId = getCurrentModelId(event.model);
 		const previousModelId = getCurrentModelId(event.previousModel);
@@ -141,7 +148,14 @@ export default function smartContextExtension(pi: ExtensionAPI): void {
 		if (config.enabled && nowExcluded !== wasExcluded) {
 			const notice = buildSwitchNotice(nowExcluded ? "unavailable" : "available", modelId);
 			debugLog(`switch notice: ${nowExcluded ? "unavailable" : "available"} (${modelId})`);
-			pi.sendUserMessage(notice, { deliverAs: "steer" });
+			// session 替换窗口可能 stale（D1 普查接入点）——守卫 stale 静默降级
+			guardStaleCtx(() => {
+				pi.sendUserMessage(notice, { deliverAs: "steer" });
+			}, {
+				isCtxStale,
+				label: "smart-context:switch-notice",
+				onStale: (error) => debugLog(`switch notice delivery skipped (stale ctx): ${toErrorMessage(error)}`),
+			});
 			return;
 		}
 
@@ -154,7 +168,14 @@ export default function smartContextExtension(pi: ExtensionAPI): void {
 		);
 		if (downshift && isGatingActive(config, modelId)) {
 			debugLog("downshift notice fired");
-			pi.sendUserMessage(downshift, { deliverAs: "steer" });
+			// session 替换窗口可能 stale（D1 普查接入点）——守卫 stale 静默降级
+			guardStaleCtx(() => {
+				pi.sendUserMessage(downshift, { deliverAs: "steer" });
+			}, {
+				isCtxStale,
+				label: "smart-context:downshift-notice",
+				onStale: (error) => debugLog(`downshift notice delivery skipped (stale ctx): ${toErrorMessage(error)}`),
+			});
 		}
 	});
 }

package/src/llm.ts

@@ -1,7 +1,7 @@
 /**
  * same-model 模式的 LLM 调用（D12 + D13-5 cache-key 一致性）。
  *
- * 不走 llm-shared callLLM：其 tools:[] 硬编码会破坏前缀缓存对齐（call.ts:113）。
+ * 不走 llm-shared callLLM：其 tools:[] 硬编码会破坏前缀缓存对齐（llm-shared call.ts）。
  * 此处直接用 completeSimple + getApiKeyAndHeaders，并把 tools schema 与主会话对齐
  * （deepseek-harness summarizer 同款做法：system + tools + messages 全部复用做缓存对齐）。
  *
@@ -13,24 +13,17 @@
 import { completeSimple } from "@earendil-works/pi-ai/compat";
 import type { Context as LlmContext, SimpleStreamOptions } from "@earendil-works/pi-ai/compat";
 import type { Tool as LlmTool, Message, Model } from "@earendil-works/pi-ai";
-import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
-
-/** ToolInfo 的宽松形状（Pick<ToolDefinition, "name"|"description"|"parameters"> 即可投影为 pi-ai Tool）。 */
-interface ToolInfoLike {
-	name: string;
-	description: string;
-	parameters: unknown;
-}
+import type { ExtensionContext, ToolInfo } from "@earendil-works/pi-coding-agent";
 
 /**
  * ToolInfo → pi-ai Tool 投影：三字段直取。parameters 是 typebox schema（主会话同源对象，
  * 序列化后与主请求一致——缓存对齐的关键是不改造、原样透传）。
  */
-export function projectTools(toolInfos: readonly ToolInfoLike[]): LlmTool[] {
+export function projectTools(toolInfos: readonly ToolInfo[]): LlmTool[] {
 	return toolInfos.map((t) => ({
 		name: t.name,
 		description: t.description,
-		parameters: t.parameters as LlmTool["parameters"],
+		parameters: t.parameters,
 	}));
 }
 

package/src/pure.ts

@@ -5,6 +5,7 @@
  * 设计文档：docs/extensions/smart-context/design.md（D5 门控矩阵 / D6 阈值保护 / D8 配置 schema）。
  */
 
+import { estimateTokens } from "@earendil-works/pi-coding-agent";
 import type { ModelSelector } from "@zhushanwen/pi-llm-shared";
 import { loadConfig } from "@zhushanwen/pi-llm-shared";
 
@@ -304,22 +305,15 @@ export function collectKeptReadFiles(branchEntries: ReadonlyArray<unknown>, firs
 
 /**
  * 被压段 token 估算（收缩校验分母：仅 messagesToSummarize；turnPrefixMessages 是保留段前缀，
- * 不属于被压段，不计入）。pi 的 estimateTokens 按 message 内容估算；此处 chars/4 的保守替代：
- * serialize 后长度 / 4（与 pi 同口径量级，用于"摘要 >= 原文"的粗判已足）。
+ * 不属于被压段，不计入）。与 pi 自身压缩用量核算同源：逐条 estimateTokens 求和
+ * （toolCall arguments 与 thinking 块计入分母），消息类型经其签名反推、随 pi 升级自动跟随。
  */
 export function estimateShadowedTokens(
-	messagesToSummarize: ReadonlyArray<{ role: string; content?: unknown }>,
+	messagesToSummarize: ReadonlyArray<Parameters<typeof estimateTokens>[0]>,
 ): number {
-	let chars = 0;
+	let tokens = 0;
 	for (const m of messagesToSummarize) {
-		const content = m.content;
-		if (typeof content === "string") {
-			chars += content.length;
-		} else if (Array.isArray(content)) {
-			for (const b of content as ReadonlyArray<{ type?: string; text?: string }>) {
-				if (typeof b.text === "string") chars += b.text.length;
-			}
-		}
+		tokens += estimateTokens(m);
 	}
-	return Math.ceil(chars / CHARS_PER_TOKEN_ESTIMATE);
+	return tokens;
 }

package/src/tool.ts

@@ -10,6 +10,7 @@
  */
 
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { guardStaleCtx, toErrorMessage } from "@zhushanwen/pi-ext-guards";
 import { Type } from "typebox";
 
 import { debugLog } from "./compact-handler.js";
@@ -109,6 +110,13 @@ export function registerCompactContextTool(
 		gatingProbe?: (ctx: ExtensionContext) => { active: boolean; modelId: string };
 		usageProbe?: (ctx: ExtensionContext) => { tokens: number | null; contextWindow: number };
 		getEntries?: (ctx: ExtensionContext) => ReadonlyArray<EntryLike>;
+		/**
+		 * G1 代际检测（crash-resilience D1）：compact 是 fire-and-forget——onComplete/onError
+		 * 回调在压缩 LLM 调用期间异步触发，用户此间切换/重载 session 后回调持有的 pi 已
+		 * stale（E1 实锤崩溃点）。index.ts 注入模块级代数比对闭包，前置检查 + 错误分诊
+		 * 双保险；缺省时守卫退化为纯文案兜底分诊（PS-30 门禁守文案）。
+		 */
+		isCtxStale?: () => boolean;
 	},
 ): void {
 	const probeGating =
@@ -165,29 +173,47 @@ export function registerCompactContextTool(
 					typeof params.custom_instructions === "string" && params.custom_instructions.trim() !== ""
 						? params.custom_instructions
 						: undefined,
+				// E1 实锤崩溃点（9/3 pi-crash log）：两个回调由 compact 的内部 Promise 链异步
+				// 调用，不在 pi runner emit() 的 try/catch 内——session 替换窗口（GUI 切
+				// session/新建/重载高频触发）下 pi.sendUserMessage 命中 stale ctx 同步抛错即
+				// 杀死 pi 进程。守卫 stale 静默降级（结果不投递，用户可重试 /compact），非
+				// stale 错误原样上抛（守卫不吞真实 bug）。
 				onComplete: (r: unknown) => {
-					const result = toCompactionResultLike(r);
-					const resultMode = result.details?.mode ?? "native-fallback";
-					const fellBack = resultMode === "native-fallback";
-					if (fellBack) debugLog("compact_context: takeover fell back to native generation");
-					const cacheRead = result.usage?.cacheRead;
-					const cost = result.usage
-						? `${formatK(result.usage.input ?? 0)} input${cacheRead ? `（其中缓存命中 ${formatK(cacheRead)}）` : ""} + ${formatK(result.usage.output ?? 0)} output`
-						: "未知";
-					const showHint = compactionCount + 1 >= DEGRADATION_HINT_MIN_COMPACTIONS;
-					const lines = [
-						`[smart-context] 压缩完成。模式：${resultMode}${fellBack ? "（压缩模型不可用，已回退当前模型——请检查配置：xyz-agent 设置页或 smart-context-ext-config skill）" : ""}。`,
-						`压缩前 ${formatK(result.tokensBefore ?? 0)} tokens → 压缩后约 ${formatK(result.estimatedTokensAfter ?? 0)} tokens；摘要生成成本：${cost}。`,
-						showHint ? buildDegradationHintLine() : "",
-					].filter((l) => l !== "");
-					pi.sendUserMessage(lines.join("\n"), { deliverAs: "steer" });
+					guardStaleCtx(() => {
+						const result = toCompactionResultLike(r);
+						const resultMode = result.details?.mode ?? "native-fallback";
+						const fellBack = resultMode === "native-fallback";
+						if (fellBack) debugLog("compact_context: takeover fell back to native generation");
+						const cacheRead = result.usage?.cacheRead;
+						const cost = result.usage
+							? `${formatK(result.usage.input ?? 0)} input${cacheRead ? `（其中缓存命中 ${formatK(cacheRead)}）` : ""} + ${formatK(result.usage.output ?? 0)} output`
+							: "未知";
+						const showHint = compactionCount + 1 >= DEGRADATION_HINT_MIN_COMPACTIONS;
+						const lines = [
+							`[smart-context] 压缩完成。模式：${resultMode}${fellBack ? "（压缩模型不可用，已回退当前模型——请检查配置：xyz-agent 设置页或 smart-context-ext-config skill）" : ""}。`,
+							`压缩前 ${formatK(result.tokensBefore ?? 0)} tokens → 压缩后约 ${formatK(result.estimatedTokensAfter ?? 0)} tokens；摘要生成成本：${cost}。`,
+							showHint ? buildDegradationHintLine() : "",
+						].filter((l) => l !== "");
+						pi.sendUserMessage(lines.join("\n"), { deliverAs: "steer" });
+					}, {
+						isCtxStale: deps?.isCtxStale,
+						label: "smart-context:compact-onComplete",
+						onStale: (error) => debugLog(`compact result delivery skipped (stale ctx): ${toErrorMessage(error)}`),
+					});
 				},
 				onError: (err: Error) => {
+					// 压缩本身的失败信息先落日志（守卫体外——stale 降级时该观测保留）
 					debugLog(`compact_context error: ${err.message}`);
-					pi.sendUserMessage(
-						`[smart-context] 压缩失败：${err.message}。上下文未变化，可稍后重试（若反复失败，检查 smart-context 配置或使用 /compact）。`,
-						{ deliverAs: "steer" },
-					);
+					guardStaleCtx(() => {
+						pi.sendUserMessage(
+							`[smart-context] 压缩失败：${err.message}。上下文未变化，可稍后重试（若反复失败，检查 smart-context 配置或使用 /compact）。`,
+							{ deliverAs: "steer" },
+						);
+					}, {
+						isCtxStale: deps?.isCtxStale,
+						label: "smart-context:compact-onError",
+						onStale: (error) => debugLog(`compact failure notice delivery skipped (stale ctx): ${toErrorMessage(error)}`),
+					});
 				},
 			});