@zhushanwen/pi-ext-guards 0.2.1 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-ext-guards",
-  "version": "0.2.1",
+  "version": "0.4.0",
   "description": "Shared runtime-environment guards for Pi extensions — oncePerProcess(key, fn) dedupes cross-session side-effect operations against pi factory re-invocation and handler accumulation (shared library, not a Pi extension, zero dependencies).",
   "type": "module",
   "main": "src/index.ts",

package/src/__tests__/guard-stale-ctx.test.ts

@@ -0,0 +1,167 @@
+// src/__tests__/guard-stale-ctx.test.ts
+//
+// guardStaleCtx 单测——验收条款逐条对应（crash-resilience u1-ext-guard）：
+//   a. 前置代际检查：isCtxStale=true → fn 不执行、stale 静默降级（返回 undefined）
+//   b. 非 stale 错误原样上抛（守卫不吞真实 bug，同步 throw 与 async rejection 双面）
+//   c. onStale 回调：前置命中无参调用；文案分诊命中携带错误调用；缺省走 XYZ_AGENT_DEBUG=1 stderr
+//   d. 文案子串匹配：STALE_CTX_MARKER 命中即静默（isCtxStale=false 时文案兜底仍生效）
+//   e. async fn：stale rejection → resolve undefined；非 stale rejection → 原样 reject
+//   f. 正常路径：返回值/resolve 值原样透传（守卫不改变正常路径，A2 负面验证的单测面）
+
+import { describe, expect, it, vi, afterEach } from "vitest";
+
+import { STALE_CTX_MARKER, guardStaleCtx } from "../index.ts";
+
+/** pi 实装 stale 文案的完整形态（E1 崩溃堆栈原文，探针 PS-30 守卫其稳定性）。 */
+const PI_STALE_ERROR = `This extension ctx is stale ${STALE_CTX_MARKER} or reload. Do not use a captured pi or command ctx after ctx.newSession().`;
+
+afterEach(() => {
+	vi.unstubAllEnvs();
+	vi.restoreAllMocks();
+});
+
+describe("guardStaleCtx 前置代际检查（G1 形态）", () => {
+	it("isCtxStale=true：fn 完全不执行，stale 静默降级返回 undefined", () => {
+		const fn = vi.fn(() => "should not run");
+
+		const result = guardStaleCtx(fn, {
+			isCtxStale: () => true,
+			onStale: () => {},
+		});
+
+		expect(fn).not.toHaveBeenCalled();
+		expect(result).toBeUndefined();
+	});
+
+	it("前置命中：onStale 以无参调用（无捕获错误）", () => {
+		const onStale = vi.fn();
+
+		guardStaleCtx(
+			() => {
+				throw new Error("never reached");
+			},
+			{ isCtxStale: () => true, onStale },
+		);
+
+		expect(onStale).toHaveBeenCalledTimes(1);
+		expect(onStale.mock.calls[0]).toHaveLength(0);
+	});
+
+	it("isCtxStale=false（缺省）：fn 正常执行、返回值原样透传（不改变正常路径）", () => {
+		const shared = { ok: true };
+
+		const result = guardStaleCtx(() => shared, { isCtxStale: () => false, onStale: () => {} });
+
+		expect(result).toBe(shared);
+	});
+});
+
+describe("guardStaleCtx 同步抛错分诊（F2 形态同步面）", () => {
+	it("非 stale 错误：原样上抛（同一错误实例，不吞不包装）", () => {
+		const boom = new Error("real bug: schema validation exploded");
+		const onStale = vi.fn();
+
+		expect(() =>
+			guardStaleCtx(() => {
+				throw boom;
+			}, { isCtxStale: () => false, onStale }),
+		).toThrow(boom);
+		expect(onStale).not.toHaveBeenCalled();
+	});
+
+	it("文案子串匹配：isCtxStale=false 但错误文案含 STALE_CTX_MARKER → 静默降级（reload 盲区兜底）", () => {
+		const onStale = vi.fn();
+
+		const result = guardStaleCtx(() => {
+			throw new Error(PI_STALE_ERROR);
+		}, { isCtxStale: () => false, onStale });
+
+		expect(result).toBeUndefined();
+		expect(onStale).toHaveBeenCalledTimes(1);
+		const captured: unknown = onStale.mock.calls[0]?.[0];
+		expect(captured).toBeInstanceOf(Error);
+		expect((captured as Error).message).toContain(STALE_CTX_MARKER);
+	});
+
+	it("非 Error 的 thrown 值含文案子串 → 同样分诊为 stale（String(value) 兜底）", () => {
+		const onStale = vi.fn();
+
+		const result = guardStaleCtx(() => {
+			throw `wrapper: ${STALE_CTX_MARKER} (string throw)`;
+		}, { onStale });
+
+		expect(result).toBeUndefined();
+		expect(onStale).toHaveBeenCalledTimes(1);
+	});
+
+	it("代际翻转兜底：抛错后 isCtxStale() 翻转为 true → 分诊 stale（in-flight 回调场景）", () => {
+		let stale = false;
+		const onStale = vi.fn();
+
+		const result = guardStaleCtx(() => {
+			stale = true; // 模拟同步窗口外的代际翻转（真实场景为 rejection 到达时已翻转）
+			throw new Error("boom");
+		}, { isCtxStale: () => stale, onStale });
+
+		expect(result).toBeUndefined();
+		expect(onStale).toHaveBeenCalledTimes(1);
+	});
+});
+
+describe("guardStaleCtx async fn（F2 形态异步面，scheduler tick 迁移形态）", () => {
+	it("stale rejection：resolve 为 undefined（不 reject，fire-and-forget 安全）", async () => {
+		const onStale = vi.fn();
+
+		const result = guardStaleCtx(async () => {
+			throw new Error(PI_STALE_ERROR);
+		}, { isCtxStale: () => false, onStale });
+
+		await expect(result).resolves.toBeUndefined();
+		expect(onStale).toHaveBeenCalledTimes(1);
+	});
+
+	it("非 stale rejection：原样 reject 给调用方的 .catch（同一错误实例）", async () => {
+		const boom = new Error("async real bug");
+		const onStale = vi.fn();
+
+		const result = guardStaleCtx(async () => {
+			throw boom;
+		}, { isCtxStale: () => false, onStale });
+
+		await expect(result).rejects.toThrow(boom);
+		expect(onStale).not.toHaveBeenCalled();
+	});
+
+	it("async 正常路径：resolve 值原样透传", async () => {
+		const result = guardStaleCtx(async () => "tick done", { onStale: () => {} });
+
+		await expect(result).resolves.toBe("tick done");
+	});
+});
+
+describe("guardStaleCtx onStale 缺省（默认 debug 日志）", () => {
+	it("XYZ_AGENT_DEBUG=1：stderr 写入守卫降级行（含 label 与错误文案）", () => {
+		vi.stubEnv("XYZ_AGENT_DEBUG", "1");
+		const stderr = vi.spyOn(process.stderr, "write").mockReturnValue(true);
+
+		guardStaleCtx(() => {
+			throw new Error(PI_STALE_ERROR);
+		}, { label: "pkg:scene" });
+
+		expect(stderr).toHaveBeenCalledTimes(1);
+		const line = String(stderr.mock.calls[0]?.[0]);
+		expect(line).toContain("[ext-guards] stale ctx degraded (pkg:scene)");
+		expect(line).toContain(STALE_CTX_MARKER);
+	});
+
+	it("XYZ_AGENT_DEBUG 未设：静默（不写 stderr）", () => {
+		vi.stubEnv("XYZ_AGENT_DEBUG", "");
+		const stderr = vi.spyOn(process.stderr, "write").mockReturnValue(true);
+
+		guardStaleCtx(() => {
+			throw new Error(PI_STALE_ERROR);
+		});
+
+		expect(stderr).not.toHaveBeenCalled();
+	});
+});

package/src/__tests__/pi-semantics-stale-ctx-wording.test.ts

@@ -0,0 +1,90 @@
+/**
+ * PS-30 探针：pi ExtensionRunner 的 stale ctx 错误文案契约（crash-resilience D1 守卫
+ * 分诊词锁，docs/pi-semantics.json PS-30）。
+ *
+ * 断言方式（静态直读 dist，同 packages/runtime pi-semantics-prompt-rejection.test.ts 范式）：
+ * - runner.js：`invalidate()` 默认 message 含 "stale after session replacement"
+ *   （staleMessage 的唯一写入点）+ `assertActive()` 的 `throw new Error(this.staleMessage)`
+ *   形态（E1 崩溃堆栈帧 `assertActive → sendUserMessage` 的实装机制）。
+ * - loader.js：pi API（sendMessage / sendUserMessage / appendEntry）的 `assertActive()`
+ *   前置——守卫分诊词覆盖「跨 session 存活回调触碰捕获 pi」的面。
+ * - runner.js：ctx 的 compact / abort / shutdown 受 assertActive 保护——守卫分诊词
+ *   同样覆盖「回调触碰捕获 ctx」的面。
+ *
+ * 该文案是 ext-guards `guardStaleCtx` 的兜底分诊依据（代际检测为主判，本文案为
+ * reload 盲区兜底）。pi 升级红 = 文案/机制漂移：守卫退化为「全部上抛」（回到现状
+ * 崩溃链路，不更危险），同步 ext-guards STALE_CTX_MARKER 与本文档引用后更新 verifiedWith。
+ *
+ * 运行：cd extensions/shared/ext-guards && npx vitest run src/__tests__/pi-semantics-stale-ctx-wording.test.ts
+ */
+import { describe, it, expect } from "vitest";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+/** 定位实装 pi-coding-agent dist（cwd 逐级上溯，同 runtime 探针范式）。 */
+function locatePiCodingAgentDist(): string | null {
+	let dir = process.cwd();
+	for (let i = 0; i < 8; i++) {
+		const candidate = join(dir, "node_modules", "@earendil-works", "pi-coding-agent", "dist");
+		if (existsSync(join(candidate, "core", "extensions", "runner.js"))) return candidate;
+		const parent = join(dir, "..");
+		if (parent === dir) break;
+		dir = parent;
+	}
+	return null;
+}
+
+const PI_DIST = locatePiCodingAgentDist();
+const SKIP_REASON = PI_DIST
+	? ""
+	: "node_modules/@earendil-works/pi-coding-agent/dist 不可达（cwd 上溯未命中，零依赖包无 pi devDep——在仓库根或任意可解析 pi 的目录跑 extensions:test）";
+// skip 提示由 describe.skipIf 的标题携带（下行 SKIP_REASON 已拼入），不经 console
+
+const RUNNER_SRC = PI_DIST ? readFileSync(join(PI_DIST, "core", "extensions", "runner.js"), "utf-8") : "";
+const LOADER_SRC = PI_DIST ? readFileSync(join(PI_DIST, "core", "extensions", "loader.js"), "utf-8") : "";
+
+describe.skipIf(!PI_DIST)(
+	`PS-30 探针：stale ctx 错误文案与 assertActive 机制${SKIP_REASON ? `｜skip：${SKIP_REASON}` : ""}`,
+	() => {
+		it("invalidate() 默认 message 含 stale after session replacement（守卫兜底分诊词的 pi 侧源头）", () => {
+			expect(
+				RUNNER_SRC.includes("stale after session replacement"),
+				"PS-30 漂移：stale 默认文案消失/变更——guardStaleCtx 文案兜底分诊失效退化为全部上抛（回到现状崩溃链路），同步 ext-guards STALE_CTX_MARKER 后更新 verifiedWith",
+			).toBe(true);
+		});
+
+		it("assertActive 以 throw new Error(this.staleMessage) 同步抛错（E1 崩溃机制的实装锚点）", () => {
+			const assertIdx = RUNNER_SRC.indexOf("assertActive() {");
+			expect(assertIdx, "PS-30 漂移：assertActive 方法消失/改名——复核 runner.js 锚点").toBeGreaterThanOrEqual(0);
+			const body = RUNNER_SRC.slice(assertIdx, assertIdx + 300);
+			expect(
+				body.includes("throw new Error(this.staleMessage)"),
+				"PS-30 漂移：assertActive 不再同步 throw staleMessage——E1 型崩溃机制改形，复核 guardStaleCtx 分诊前提",
+			).toBe(true);
+		});
+
+		it("pi API（sendMessage/sendUserMessage/appendEntry）前置 assertActive（守卫覆盖捕获 pi 的触碰面）", () => {
+			for (const method of ["sendMessage(message, options)", "sendUserMessage(content, options)", "appendEntry(customType, data)"]) {
+				const idx = LOADER_SRC.indexOf(method);
+				expect(idx, `PS-30 漂移：loader.js pi API ${method} 消失/改签名——复核锚点`).toBeGreaterThanOrEqual(0);
+				const window = LOADER_SRC.slice(idx, idx + 160);
+				expect(
+					window.includes("assertActive()"),
+					`PS-30 漂移：pi API ${method} 不再前置 assertActive——stale 触碰面改形，复核守卫分诊词的覆盖面`,
+				).toBe(true);
+			}
+		});
+
+		it("ctx 的 compact/abort/shutdown 受 assertActive 保护（守卫覆盖捕获 ctx 的触碰面）", () => {
+			for (const entry of ["compact: (options) => {", "abort: () => {", "shutdown: () => {"]) {
+				const idx = RUNNER_SRC.indexOf(entry);
+				expect(idx, `PS-30 漂移：ctx.${entry.replace(/[: ].*/, "")} 定义消失/改形——复核 createContext 锚点`).toBeGreaterThanOrEqual(0);
+				const window = RUNNER_SRC.slice(idx, idx + 200);
+				expect(
+					window.includes("assertActive()"),
+					`PS-30 漂移：ctx.${entry.replace(/[: ].*/, "")} 不再受 assertActive 保护——stale 触碰面改形，复核守卫分诊词的覆盖面`,
+				).toBe(true);
+			}
+		});
+	},
+);

package/src/__tests__/predicates.test.ts

@@ -0,0 +1,109 @@
+// src/__tests__/predicates.test.ts
+//
+// isRecord / isEnoentError / isSubagentProcess 单测（ext-simplify-17 D3/D2/D4 新导出）：
+//   - isRecord 排数组严版：数组必须 false（钉值，防回退到允数组宽版）
+//   - isEnoentError scheduler 严版：仅 Error 子类 + code === "ENOENT" 才 true，
+//     非 Error 对象带 code 是宽版才接受的形态，严版必须 false
+//   - isSubagentProcess 三态 + env 注入隔离 + 旧键宁缺勿污钉值（D4 重锚定）
+
+import { describe, expect, it } from "vitest";
+
+import { isEnoentError, isRecord, isSubagentProcess } from "../index.ts";
+
+describe("isRecord", () => {
+	it("对象 true", () => {
+		expect(isRecord({})).toBe(true);
+		expect(isRecord({ key: "value" })).toBe(true);
+	});
+
+	it("null false", () => {
+		expect(isRecord(null)).toBe(false);
+	});
+
+	it("undefined false", () => {
+		expect(isRecord(undefined)).toBe(false);
+	});
+
+	it("数组 false（排数组钉值——Record 语义不含数组）", () => {
+		expect(isRecord([])).toBe(false);
+		expect(isRecord([{ a: 1 }])).toBe(false);
+	});
+
+	it("字符串 false", () => {
+		expect(isRecord("text")).toBe(false);
+	});
+});
+
+describe("isEnoentError", () => {
+	it("Error 带 code=ENOENT true（Node fs 错误的构造形态）", () => {
+		expect(isEnoentError(Object.assign(new Error("no such file"), { code: "ENOENT" }))).toBe(
+			true,
+		);
+	});
+
+	it("普通 Error false（无 code 属性）", () => {
+		expect(isEnoentError(new Error("x"))).toBe(false);
+	});
+
+	it("code 为其他值 false", () => {
+		expect(isEnoentError(Object.assign(new Error("denied"), { code: "EACCES" }))).toBe(false);
+	});
+
+	it("非 Error 对象带 code=ENOENT false（严版：宽版才接受的形态）", () => {
+		expect(isEnoentError({ code: "ENOENT" })).toBe(false);
+	});
+
+	it("undefined false", () => {
+		expect(isEnoentError(undefined)).toBe(false);
+	});
+});
+
+describe("isSubagentProcess", () => {
+	it("XYZ_AGENT_SUBAGENT=1 命中（引擎 spawn 链恒注入的现行标记）", () => {
+		expect(isSubagentProcess({ XYZ_AGENT_SUBAGENT: "1" })).toBe(true);
+	});
+
+	it("值非 \"1\" 不命中（标记必须是引擎注入的字面 \"1\"）", () => {
+		expect(isSubagentProcess({ XYZ_AGENT_SUBAGENT: "0" })).toBe(false);
+		expect(isSubagentProcess({ XYZ_AGENT_SUBAGENT: "" })).toBe(false);
+		expect(isSubagentProcess({ XYZ_AGENT_SUBAGENT: "true" })).toBe(false);
+	});
+
+	it("缺失不命中（顶层会话 → 消费方不降级）", () => {
+		expect(isSubagentProcess({})).toBe(false);
+	});
+
+	it("env 参数注入隔离：传入的 env 与宿主 process.env 无关（宿主即使带标记，空 env 也不命中）", () => {
+		const saved = process.env.XYZ_AGENT_SUBAGENT;
+		try {
+			process.env.XYZ_AGENT_SUBAGENT = "1";
+			// 显式传 env：宿主的标记不渗透，判据只看参数
+			expect(isSubagentProcess({})).toBe(false);
+			expect(isSubagentProcess({ XYZ_AGENT_SUBAGENT: "1" })).toBe(true);
+		} finally {
+			if (saved === undefined) delete process.env.XYZ_AGENT_SUBAGENT;
+			else process.env.XYZ_AGENT_SUBAGENT = saved;
+		}
+	});
+
+	it("缺省参数读 process.env（不传 env 时以宿主环境为判据）", () => {
+		const saved = process.env.XYZ_AGENT_SUBAGENT;
+		try {
+			process.env.XYZ_AGENT_SUBAGENT = "1";
+			expect(isSubagentProcess()).toBe(true);
+			delete process.env.XYZ_AGENT_SUBAGENT;
+			expect(isSubagentProcess()).toBe(false);
+		} finally {
+			if (saved === undefined) delete process.env.XYZ_AGENT_SUBAGENT;
+			else process.env.XYZ_AGENT_SUBAGENT = saved;
+		}
+	});
+
+	it("旧 PI_SUBAGENT_* 身份键不再命中（[HISTORICAL] D4 重锚前两键任一存在即命中；引擎协议化后无写入方，宁缺勿污）", () => {
+		expect(isSubagentProcess({ PI_SUBAGENT_ROOT_SESSION_ID: "s1" })).toBe(false);
+		expect(isSubagentProcess({ PI_SUBAGENT_SELF_RECORD_ID: "r1" })).toBe(false);
+		expect(isSubagentProcess({ PI_SUBAGENT_ROOT_SESSION_ID: "s1", PI_SUBAGENT_SELF_RECORD_ID: "r1" })).toBe(
+			false,
+		);
+	});
+});

package/src/index.ts

@@ -3,7 +3,7 @@
 // @zhushanwen/pi-ext-guards —— pi 运行环境守卫共享库（不是 Pi extension，零依赖纯函数，
 // 无 pi SDK peerDep——供任意 @zhushanwen/pi-* 包与子代理核心消费）。
 //
-// 背景与设计依据：docs/design/file-lock-unification-and-reaper-sink.md §2.2 P3 / §3.2 D3。
+// 背景与设计依据：docs/architecture/file-lock-unification-and-reaper-sink.md §2.2 P3 / §3.2 D3。
 // pi 的 extension 缓存按 cwd 失效：switch_session 时 cwd 不变则 factory 被二次调用且
 // handler 累积注册——session_start handler 的真实派发语义是「每 session × factory
 // 调用次数」，不是「每 session 一次」。handler 体内的跨 session 副作用操作（写非本
@@ -82,3 +82,215 @@ export function oncePerProcess<T>(key: string, fn: () => T): T {
 export function toErrorMessage(e: unknown): string {
 	return e instanceof Error ? e.message : String(e);
 }
+
+/**
+ * 判断 value 是否为非 null、非数组的 object（`Record` 语义本义：可按字符串键安全取值）。
+ *
+ * canonical 来自 ext-simplify-17 D3（排数组严版，设计文档
+ * docs/architecture/ext-simplify-17-shared-extraction.md §3.1）。
+ */
+export function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * 判断 err 是否为 Node fs 的 ENOENT 错误（`Error` 实例且 `code === "ENOENT"`）。
+ *
+ * canonical 来自 ext-simplify-17 D2（scheduler 严版，`"code" in err` 收窄避免
+ * `as Record` 强转——taste/no-unsafe-cast）。
+ */
+export function isEnoentError(err: unknown): boolean {
+	return err instanceof Error && "code" in err && err.code === "ENOENT";
+}
+
+// ── subagent 进程判据（isSubagentProcess，ext-simplify-17 D4）────────────
+//
+// 背景：extension 需要知道「当前 pi 进程是否引擎链上的 subagent 子进程」来决定降级
+// （base-tool-enhance background 降级——bte background 生命周期设计的 D14 项，
+// commit 8599abd0c，该设计未在现行 docs 留档 / smart-context R6 不注册工具，
+// 规则定义见 smart-context src/index.ts R 规则族注释）。判据锚
+// XYZ_AGENT_SUBAGENT=1——subagent-engine-sdk env.ts 的 buildEngineChildEnv 对每个引擎
+// 子进程恒注入（L0 层最后写入），再经引擎内二次 spawn（buildOutboundChildEnv 全量
+// 继承）传到 subagent 内的 bash。旧判据（PI_SUBAGENT_ROOT_SESSION_ID /
+// PI_SUBAGENT_SELF_RECORD_ID 两键）在引擎协议化后已无写入方（20260914 探针证实，
+// 报告 .tmp/dev-flow/ext-simplify-17-d4-probe.md），判据失效态由 D4 重锚收敛于此。
+
+/** subagent 进程标记 env 键（引擎 spawn 链恒注入 "1"，subagent-engine-sdk env.ts L0）。 */
+export const SUBAGENT_MARKER_ENV = "XYZ_AGENT_SUBAGENT";
+
+/**
+ * 判断当前进程是否引擎链上的 subagent 子进程。
+ *
+ * 判据 = `env[SUBAGENT_MARKER_ENV] === "1"`（canonical 来自 ext-simplify-17 D4，
+ * 设计文档 docs/architecture/ext-simplify-17-shared-extraction.md §3.1）。口径
+ * 「宁缺勿污」：只有引擎 spawn 链上的真 subagent 才命中——人工 export 旧
+ * PI_SUBAGENT_ROOT_SESSION_ID / PI_SUBAGENT_SELF_RECORD_ID 身份键不再算（两键现
+ * 无写入方，见分节注释）。
+ *
+ * @param env env 快照；缺省读 process.env，显式传入即与宿主进程环境完全隔离（测试注入用）
+ */
+export function isSubagentProcess(
+	env: Record<string, string | undefined> = process.env,
+): boolean {
+	return env[SUBAGENT_MARKER_ENV] === "1";
+}
+
+// ── stale ctx 守卫（guardStaleCtx，崩溃韧性 D1）────────────────────────
+//
+// 背景（docs/design/crash-resilience.md §3.3 D1 / §2.2 事件 E1）：pi 的 extension API
+// 对象（pi / ctx）在 session 替换（newSession/fork/switchSession/reload）后被 runner
+// 标记 stale，再调用其方法会**同步抛错**（loader.js/runner.js 的 assertActive，错误文案
+// 含 STALE_CTX_MARKER）。跨 session 生命周期存活的异步回调（compact 的 onComplete/onError、
+// timer tick、延迟回调）在该窗口触碰 pi/ctx = pi 进程被无人接的同步 throw 炸死（9/3 E1
+// 实锤：smart-context compact onError → sendUserMessage → assertActive → exit 1）。
+// GUI 的每次切 session/新建/重载都在制造失效窗口——这是「pi 单独用不崩、套 GUI 就崩」
+// 的核心机制差异。本守卫把 scheduler 已验证的防御范式（G1 代际前置检查 + F2 catch 文案
+// 分诊）泛化成共享原语，接入方不再各自内联。
+
+/**
+ * pi ExtensionRunner 在 session 替换后标记 stale ctx 的错误文案片段。
+ *
+ * pi 语义断言（0.84.4 实装：runner.js `invalidate()` 默认 message + `assertActive()`
+ * `throw new Error(this.staleMessage)`），登记于 docs/pi-semantics.json PS-30
+ * （探针：extensions/shared/ext-guards/src/__tests__/pi-semantics-stale-ctx-wording.test.ts），
+ * 随 C-proc-08 pi 版本门禁自动重验。文案变更时守卫退化为「全部上抛」（回到现状崩溃链路，
+ * 有 pi-crash log 取证，不更危险），门禁报红提示更新分诊词。
+ */
+export const STALE_CTX_MARKER = "stale after session replacement";
+
+/** guardStaleCtx 的可选项。全部可选——最简接入 = 只传 fn（纯文案兜底分诊）。 */
+export interface GuardStaleCtxOptions {
+	/** 观测标签（默认降级日志的前缀，建议 "包名:场景" 形态）。 */
+	label?: string;
+	/**
+	 * 前置代际检查（G1 形态，主判）：返回 true 表示本回调所属的 session 已被替换，
+	 * 守卫完全不执行 fn、直接走 stale 降级。调用方注入，同 scheduler 的模块级代数
+	 * 计数器模式（session_start 递增模块级代数，旧代闭包捕获值 < 模块值即 stale）。
+	 * 缺省（不注入）恒视为非 stale——前置检查关闭，完全依赖错误文案兜底分诊
+	 * （D1 降级语义声明：无代际计数器的接入方合法形态，文案由 PS-30 门禁守卫）。
+	 */
+	isCtxStale?: () => boolean;
+	/**
+	 * stale 降级通知（静默降级的观测点）：前置检查命中时无参调用；fn 抛错被分诊为
+	 * stale 时以捕获的错误为参调用。缺省 = 仅 XYZ_AGENT_DEBUG=1 时写一行 stderr
+	 * debug（本包零依赖、无 pi handle，不能走 extension-logger；需要落盘日志的
+	 * 接入方传入自己的 debugLog/logger.warn）。
+	 */
+	onStale?: (error?: unknown) => void;
+}
+
+/** PromiseLike 判定（in 收窄，无 cast）：守卫据此为 async fn 的 rejection 挂同一分诊。 */
+function isPromiseLike(value: unknown): value is PromiseLike<unknown> {
+	return (
+		typeof value === "object" &&
+		value !== null &&
+		"then" in value &&
+		typeof value.then === "function"
+	);
+}
+
+/** 缺省降级通知：XYZ_AGENT_DEBUG=1 时 stderr 一行（对齐 extensions 包 XYZ_AGENT_DEBUG 惯例）。 */
+function defaultOnStale(label: string, error?: unknown): void {
+	if (process.env.XYZ_AGENT_DEBUG !== "1") return;
+	const detail =
+		error === undefined
+			? "generation check (isCtxStale)"
+			: error instanceof Error
+				? error.message
+				: String(error);
+	const prefix = label === "" ? "" : ` (${label})`;
+	process.stderr.write(`[ext-guards] stale ctx degraded${prefix}: ${detail}\n`);
+}
+
+/**
+ * 包裹「跨 session 生命周期存活的异步回调」：stale ctx 错误静默降级，非 stale 错误
+ * 原样上抛（守卫不吞真实 bug）。消灭 E1 型崩溃源（crash-resilience D1）。
+ *
+ * 语义三段（与 scheduler 范式逐条对应，scheduler/runtime.ts startScheduler 是迁移先例）：
+ *
+ * 1. **前置代际检查（G1 形态，主判）**：`opts.isCtxStale?.()` 为 true → 不执行 fn
+ *    （完全不触碰捕获的 stale pi/ctx）、调 `opts.onStale?.()`（无参）、返回 undefined。
+ * 2. **fn 同步执行 + 同步抛错分诊（F2 形态的同步面）**：错误文案含
+ *    `STALE_CTX_MARKER`（或抛错后 isCtxStale 翻转）→ 调 `opts.onStale?.(error)`、
+ *    返回 undefined；**非 stale 类错误原样上抛**——守卫不吞真实 bug（上抛的崩溃链路
+ *    与 E1 相同，有 pi-crash log 取证 + 错误规格表走 T4 恢复链路）。
+ * 3. **Promise 透传分诊（F2 形态的异步面）**：fn 返回 Promise 时守卫对 rejection
+ *    挂同一分诊——stale → resolve 为 undefined，非 stale → 原样 reject 给调用方的
+ *    `.catch`。返回的是新 Promise 实例（原实例的 rejection 已被守卫接管，调用方不得
+ *    再对原实例挂 then/catch，否则非 stale 错误会走原实例 rejection）。
+ *
+ * 分诊谓词 = `isCtxStale?.() || message.includes(STALE_CTX_MARKER)`，与 scheduler
+ * 迁移前字面一致：代际为主判（不依赖 pi 文案），文案为兜底（覆盖 reload 产生全新
+ * 模块环境后旧闭包代数冻结、isCtxStale 恒 false 的盲区）。
+ *
+ * @param fn 无参回调（闭包捕获业务所需的 pi/ctx——被捕获的是注册时的引用，这正是
+ *   stale 风险的来源，也是守卫存在的理由）
+ * @returns fn 的返回值；stale 降级路径返回 undefined（前置检查命中时 fn 未执行、无
+ *   Promise 可言，故 async 重载的返回类型是 `Promise<R | undefined> | undefined`——
+ *   前置命中即 undefined）。fire-and-forget 调用方直接 `void`；需要接非 stale 错误的
+ *   调用方（scheduler tick 形态）用 `?.catch`——前置命中返回 undefined 时无 rejection
+ *   可接（retireStaleTimer 已由 onStale 执行），非 stale rejection 才会流到 `.catch`。
+ *
+ * @example fire-and-forget 回调（smart-context compact onError）
+ * ```ts
+ * onError: (err) => guardStaleCtx(() => pi.sendUserMessage(...), { label: "smart-context:compact" })
+ * ```
+ * @example timer tick（scheduler 迁移形态：非 stale 错误外层 warn 不终止调度）
+ * ```ts
+ * void guardStaleCtx(() => this.tickScheduler(), { isCtxStale, onStale: () => this.retireStaleTimer() })
+ *   ?.catch((err) => logger.warn("tick error", { error: toErrorMessage(err) }));
+ * ```
+ */
+export function guardStaleCtx<R>(
+	fn: () => Promise<R>,
+	opts?: GuardStaleCtxOptions,
+): Promise<R | undefined> | undefined;
+export function guardStaleCtx<R>(fn: () => R, opts?: GuardStaleCtxOptions): R | undefined;
+export function guardStaleCtx(fn: () => unknown, opts?: GuardStaleCtxOptions): unknown {
+	const label = opts?.label ?? "";
+	const isCtxStale = opts?.isCtxStale;
+	const onStale = opts?.onStale;
+	const isStale = (): boolean => isCtxStale?.() ?? false;
+	// 与 scheduler 迁移前字面一致的分诊谓词：代际主判 || 文案兜底
+	const triage = (error: unknown): boolean =>
+		isStale() || toErrorMessage(error).includes(STALE_CTX_MARKER);
+	const reportStale = (error?: unknown): void => {
+		if (onStale !== undefined) {
+			// 前置命中（无捕获错误）无参调用；文案分诊命中携带错误——保持 JSDoc 契约
+			if (error === undefined) onStale();
+			else onStale(error);
+		} else {
+			defaultOnStale(label, error);
+		}
+	};
+
+	// 1. 前置代际检查：stale 则完全不触碰捕获的 pi/ctx（P-guard-holds 的守卫第一道）
+	if (isStale()) {
+		reportStale();
+		return undefined;
+	}
+
+	// 2. fn 同步执行 + 同步抛错分诊
+	let result: unknown;
+	try {
+		result = fn();
+	} catch (error) {
+		if (triage(error)) {
+			reportStale(error);
+			return undefined;
+		}
+		throw error;
+	}
+
+	// 3. async fn：rejection 走同一分诊（stale → resolve undefined；非 stale → 原样 reject）
+	if (isPromiseLike(result)) {
+		return result.then(undefined, (error: unknown) => {
+			if (triage(error)) {
+				reportStale(error);
+				return undefined;
+			}
+			throw error;
+		});
+	}
+	return result;
+}