@zhushanwen/pi-smart-context 0.2.0 → 0.3.1

package/README.md

@@ -13,10 +13,20 @@
 - **健壮性**：摘要收缩校验、max-tokens 截断 fail-closed、接管失败 3 次熔断、transcript 回查指针、压缩后最近文件内容重注入（≤5 文件/50K）、多轮压缩降智提示
 - **subagent 进程**自动静默（`PI_SUBAGENT_ROOT_SESSION_ID` 标记）
 
-## 配置
+## 行为门控
 
-`<agentDir>/config/smart-context-ext-config.json`（读时热加载）。schema 与示例见 `skills/smart-context-ext-config/SKILL.md`。xyz-agent 桌面端在设置页（系统 → 智能上下文压缩）可视化配置。
+| 状态 | 工具 execute | 阈值提醒 | 压缩生成接管 |
+|---|---|---|---|
+| enabled，模型未排除 | 放行（低于最低档阈值时拒绝并返回用量建议） | 生效 | 生效（按双模式判定） |
+| enabled，模型命中排除列表 | 拒绝（返回原因） | 跳过 | 跳过（回落 pi 原生生成） |
+| enabled=false | 拒绝（"可在设置页开启"） | 跳过 | 跳过（回落 pi 原生） |
+| compactModel 未配置/无效 | 放行（same-model 不依赖该配置） | 生效 | same-model 生效；cross-model 回退当前模型，压缩不失败 |
+| 模型切换跨界（model_select） | 常驻不变 | 注入一条可用性变化通知（仅跨界时） | 按新模型即时重判 |
+
+行为正确性由 execute / handler 现场校验兜底，每次事件回调重新读配置（热加载，改完下一 turn 生效，无需重启）。
 
-## 设计文档
+> 设计层 why 与业界调研记录见原设计文档（已随 2026-09 docs 清理退役，git 历史可查 `docs/extensions/smart-context/design.md`）。
 
-`docs/extensions/smart-context/design.md`（xyz-agent 仓库）——决策依据、探针记录、验收场景。
+## 配置
+
+`<agentDir>/config/smart-context-ext-config.json`（读时热加载）。schema 与示例见 `skills/smart-context-ext-config/SKILL.md`。xyz-agent 桌面端在设置页（系统 → 智能上下文压缩）可视化配置。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-smart-context",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "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.6.0"
+    "@zhushanwen/pi-ext-guards": "0.4.0",
+    "@zhushanwen/pi-extension-logger": "0.6.0",
+    "@zhushanwen/pi-llm-shared": "0.8.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,30 +18,45 @@ 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,
 	};
 }
 
@@ -148,7 +165,7 @@ describe("session_before_compact 接管 handler", () => {
 	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,13 +5,13 @@ import {
 	buildReinjectSection,
 	checkToolThresholdGuard,
 	computeFileListsLike,
+	estimateShadowedTokens,
 	estimateTextTokens,
 	findCrossedThresholds,
 	formatFileOperationsLike,
 	formatK,
 	getCurrentModelId,
 	isGatingActive,
-	isSubagentProcess,
 	isSummaryInflated,
 	normalizeSmartContextConfig,
 	pickMode,
@@ -136,9 +136,42 @@ describe("摘要后处理纯函数（D11/D13）", () => {
 	});
 });
 
-describe("subagent 识别（R6）", () => {
-	it("PI_SUBAGENT_ROOT_SESSION_ID 存在即 subagent", () => {
-		expect(isSubagentProcess({ PI_SUBAGENT_ROOT_SESSION_ID: "s1" })).toBe(true);
-		expect(isSubagentProcess({})).toBe(false);
+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);
 	});
 });
+
+// [HISTORICAL] subagent 识别（R6）用例已随本地实现删除移除——现行谓词收敛于
+// ext-guards isSubagentProcess（ext-simplify-17 D4），三态与「宁缺勿污」钉值见
+// extensions/shared/ext-guards/src/__tests__/predicates.test.ts。

package/src/compact-handler.ts

@@ -12,8 +12,9 @@
  */
 
 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 { toErrorMessage } from "@zhushanwen/pi-ext-guards";
 import { createLogger } from "@zhushanwen/pi-extension-logger";
 import { resolveModel } from "@zhushanwen/pi-llm-shared";
 import { readFileSync } from "node:fs";
@@ -32,6 +33,7 @@ import {
 	estimateTextTokens,
 	formatFileOperationsLike,
 	getCurrentModelId,
+	isGatingActive,
 	isSummaryInflated,
 	pickMode,
 	pickReinjectFiles,
@@ -39,31 +41,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 停止接管）。 */
@@ -173,7 +150,7 @@ function assembleSummary(
 async function generateSameMode(
 	pi: ExtensionAPI,
 	ctx: ExtensionContext,
-	event: BeforeCompactLikeEvent,
+	event: SessionBeforeCompactEvent,
 ): Promise<CompactionResult | null> {
 	const model = ctx.model;
 	if (!model) {
@@ -182,7 +159,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) }],
@@ -238,7 +215,7 @@ async function generateSameMode(
  */
 async function generateCrossMode(
 	ctx: ExtensionContext,
-	event: BeforeCompactLikeEvent,
+	event: SessionBeforeCompactEvent,
 	config: SmartContextConfig,
 ): Promise<CompactionResult | null> {
 	const model = resolveModel(ctx, config.compactModel);
@@ -258,10 +235,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,
@@ -287,20 +262,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 停止接管
@@ -338,11 +314,13 @@ 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;
-			warnLog("takeover error, falling back to native", { error: error instanceof Error ? error.message : String(error) });
+			warnLog("takeover error, falling back to native", { error: toErrorMessage(error) });
 			return {}; // D7 回退
 		}
 	};

package/src/index.ts

@@ -11,13 +11,13 @@
  */
 
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { guardStaleCtx, isSubagentProcess, 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";
@@ -27,34 +27,10 @@ import {
 	findCrossedThresholds,
 	getCurrentModelId,
 	isGatingActive,
-	isSubagentProcess,
 	loadSmartContextConfig,
 	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 +43,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 工厂函数。
  *
@@ -77,7 +62,8 @@ export default function smartContextExtension(pi: ExtensionAPI): void {
 	// 日志通道注入（extension-logger 两阶段初始化：工厂拿 pi → setPiHandle）
 	setPiHandle(pi);
 
-	// R6：subagent 子进程不注册工具、不提醒（PI_SUBAGENT_ROOT_SESSION_ID 标记）
+	// R6：subagent 子进程不注册工具、不提醒（宁缺勿污；XYZ_AGENT_SUBAGENT 标记——
+	// ext-guards isSubagentProcess，ext-simplify-17 D4 重锚）
 	if (isSubagentProcess()) {
 		debugLog("subagent process detected, staying inert");
 		return;
@@ -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,18 @@
 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";
+import { toErrorMessage } from "@zhushanwen/pi-ext-guards";
 
 /**
  * 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,
 	}));
 }
 
@@ -134,6 +128,6 @@ export async function callSameModelCompaction(
 		const text = resp.content.map(blockText).join("\n").trim();
 		return { ok: true, text, usage: resp.usage, stopReason: resp.stopReason };
 	} catch (error) {
-		return { ok: false, error: error instanceof Error ? error.message : String(error) };
+		return { ok: false, error: toErrorMessage(error) };
 	}
 }

package/src/pure.ts

@@ -5,8 +5,10 @@
  * 设计文档：docs/extensions/smart-context/design.md（D5 门控矩阵 / D6 阈值保护 / D8 配置 schema）。
  */
 
+import { estimateTokens } from "@earendil-works/pi-coding-agent";
+import { isRecord } from "@zhushanwen/pi-ext-guards";
 import type { ModelSelector } from "@zhushanwen/pi-llm-shared";
-import { loadConfig } from "@zhushanwen/pi-llm-shared";
+import { loadConfig, normalizeModelSelector } from "@zhushanwen/pi-llm-shared";
 
 // ──────────────────────── 配置 schema（D8） ────────────────────────
 
@@ -58,13 +60,8 @@ export function normalizeSmartContextConfig(raw: unknown): SmartContextConfig {
 
 	const enabled = typeof r.enabled === "boolean" ? r.enabled : base.enabled;
 
-	const rawModel = typeof r.compactModel === "object" && r.compactModel !== null
-		? (r.compactModel as Record<string, unknown>)
-		: null;
 	const compactModel: ModelSelector =
-		rawModel?.type === "ref" && typeof rawModel.ref === "string"
-			? { type: "ref", ref: rawModel.ref }
-			: { type: "ref", ref: "" };
+		normalizeModelSelector(r.compactModel) ?? { type: "ref", ref: "" };
 
 	const rawThresholds = Array.isArray(r.reminderThresholds)
 		? r.reminderThresholds
@@ -248,16 +245,6 @@ export function buildReinjectSection(contents: ReadonlyArray<{ path: string; con
 	return `\n\n<recently-read-files>\n${parts.join("\n\n")}\n</recently-read-files>`;
 }
 
-// ──────────────────────── subagent 识别（R6） ────────────────────────
-
-/**
- * subagent 子进程检测（D9/R6）：subagent-core session-runner 无条件注入 PI_SUBAGENT_ROOT_SESSION_ID。
- * 命中 → 本进程不注册工具、不提醒（宁缺勿污）。
- */
-export function isSubagentProcess(env: NodeJS.ProcessEnv = process.env): boolean {
-	return env.PI_SUBAGENT_ROOT_SESSION_ID !== undefined;
-}
-
 // ──────────────────────── session entries 统计（D13 纯函数） ────────────────────────
 
 /** sessionManager entries 的宽松形状（降智计数）。 */
@@ -270,11 +257,6 @@ export function countCompactions(entries: ReadonlyArray<EntryLike>): number {
 	return entries.filter((e) => e.type === "compaction").length;
 }
 
-/** unknown 的对象收窄（Record 视图；字段消费再经 typeof / Array.isArray 收窄）。 */
-function isRecord(value: unknown): value is Record<string, unknown> {
-	return typeof value === "object" && value !== null;
-}
-
 /**
  * 保留段已 Read 的文件集合（D13-11 去重：重注入跳过保留段已有的 Read 结果）。
  * 保留段 = branchEntries 中 firstKeptEntryId 之后的 message entries；从其 toolCall 参数提取 path。
@@ -304,22 +286,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, isRecord, toErrorMessage } from "@zhushanwen/pi-ext-guards";
 import { Type } from "typebox";
 
 import { debugLog } from "./compact-handler.js";
@@ -65,11 +66,6 @@ const TOOL_DESCRIPTION =
 	"2) 后续工作不再依赖将被压缩的早期细节；3) 上下文已超过提醒阈值（你会收到 [smart-context 提示]）。" +
 	"若任一条件不满足，不要调用。";
 
-/** unknown 的对象收窄（Record 视图；字段消费再经 typeof 收窄）。 */
-function isRecord(value: unknown): value is Record<string, unknown> {
-	return typeof value === "object" && value !== null;
-}
-
 /** CompactionResult → 宽松形状的 guard 转换（onComplete 回调参数消费，避免 cast）。 */
 function toCompactionResultLike(result: unknown): CompactionResultLike {
 	const r: Record<string, unknown> = isRecord(result) ? result : {};
@@ -109,6 +105,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 +168,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)}`),
+					});
 				},
 			});