@zhushanwen/pi-smart-context 0.4.3 → 0.5.0

package/src/__tests__/notices.test.ts

@@ -0,0 +1,194 @@
+// src/__tests__/notices.test.ts
+//
+// U5/D6 通知文案构建纯函数（buildCompactCompleteNotice / buildCompactFailureNotice）。
+// 投递形态断言（customType/display/{triggerTurn:false, deliverAs:"nextTurn"}）在装配层
+// 覆盖：index-reminder-delivery.test.ts（提醒/模型通知）+ compact-handler.test.ts（压缩
+// 完成/失败通知全接线），本文件只锁文案内容与条件分支。
+//
+// C1 落盘信号（sendCompactionPersistSignal）的形态在本文件直测：它是 runtime 分诊消费的
+// 机器信号（非用户可见通知），字段与投递选项是跨层契约，漂移即分界行链路断。
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { describe, expect, it, vi } from "vitest";
+
+import { COMPACTION_ENTRY_APPENDED_SOURCE, SMART_CONTEXT_NOTICE_CUSTOM_TYPE } from "@zhushanwen/extension-protocol";
+
+import {
+	buildCompactCompleteNotice,
+	buildCompactFailureNotice,
+	sendCompactionPersistSignal,
+	sendSmartContextImmediateNotice,
+	sendSmartContextNotice,
+} from "../notices.js";
+
+describe("buildCompactCompleteNotice（U5/D6 完成通知：压缩前后 token 数与模式）", () => {
+	it("含模式、前后 token（formatK 口径）与下一条消息生效语义", () => {
+		const text = buildCompactCompleteNotice({ mode: "same-model", tokensBefore: 190_000, tokensAfter: 45_000 });
+		expect(text).toContain("[smart-context]");
+		expect(text).toContain("后台压缩完成");
+		expect(text).toContain("same-model");
+		expect(text).toContain("190K");
+		expect(text).toContain("45K");
+		expect(text).toContain("下一条消息");
+	});
+
+	it("cross-model 模式名照原样展示", () => {
+		const text = buildCompactCompleteNotice({ mode: "cross-model", tokensBefore: 1_234_500, tokensAfter: 200_000 });
+		expect(text).toContain("cross-model");
+		expect(text).toContain("1234.5K");
+	});
+});
+
+describe("buildCompactFailureNotice（U5/D6 失败通知：四终局原因行，不静默）", () => {
+	it("inflated（收缩校验放弃）：说明无净收益与未落盘", () => {
+		const text = buildCompactFailureNotice({ outcome: "inflated" });
+		expect(text).toContain("未缩小上下文");
+		expect(text).toContain("未落盘");
+		expect(text).toContain("[smart-context]");
+	});
+
+	it("dropped（被抢先）：说明另一轮压缩已生效，不声称「上下文保持原样」", () => {
+		const text = buildCompactFailureNotice({ outcome: "dropped", droppedReason: "preempted" });
+		expect(text).toContain("另一轮压缩已先行落盘");
+		expect(text).toContain("未再写入");
+		expect(text).not.toContain("上下文保持原样"); // 上下文已被较新压缩结果改变
+	});
+
+	it("dropped（会话已切换）：说明切换事实，不声称「上下文保持原样」", () => {
+		const text = buildCompactFailureNotice({ outcome: "dropped", droppedReason: "session-mismatch" });
+		expect(text).toContain("会话已切换");
+		expect(text).toContain("未落盘");
+		expect(text).toContain("不受本次压缩影响");
+		expect(text).not.toContain("上下文保持原样");
+	});
+
+	it("dropped（写入接口不可用）：上下文确实未被触碰，如实声明保持原样", () => {
+		const text = buildCompactFailureNotice({ outcome: "dropped", droppedReason: "persist-unavailable" });
+		expect(text).toContain("写入接口不可用");
+		expect(text).toContain("上下文保持原样");
+	});
+
+	it("dropped（未细分缺省）：只说会话状态变化与未落盘，不声称保持原样", () => {
+		const text = buildCompactFailureNotice({ outcome: "dropped" });
+		expect(text).toContain("会话状态已变化");
+		expect(text).toContain("未落盘");
+		expect(text).not.toContain("上下文保持原样");
+	});
+
+	it("empty（生成空结果）：带重试指引", () => {
+		const text = buildCompactFailureNotice({ outcome: "empty" });
+		expect(text).toContain("未返回结果");
+		expect(text).toContain("compact_context");
+	});
+
+	it("error（异常）：错误消息嵌入文案", () => {
+		const text = buildCompactFailureNotice({ outcome: "error", error: "connect ECONNREFUSED" });
+		expect(text).toContain("connect ECONNREFUSED");
+		expect(text).toContain("compact_context");
+	});
+
+	it("熔断达到阈值：附加「自动触发已暂停」行（并入本条，不另发通知）", () => {
+		const text = buildCompactFailureNotice({ outcome: "empty", failureStreak: 3, circuitBreakerOpen: true });
+		expect(text).toContain("连续失败 3 次");
+		expect(text).toContain("自动触发压缩已暂停");
+		expect(text).toContain("compact_context 工具仍可手动调用"); // SI5：工具路径不受熔断影响
+	});
+
+	it("未达熔断：empty/error 带重试行；inflated/dropped（含各细分原因）不带（放弃类无需重试指引）", () => {
+		expect(buildCompactFailureNotice({ outcome: "empty", failureStreak: 1 })).toContain("重试");
+		expect(buildCompactFailureNotice({ outcome: "inflated" })).not.toContain("重试");
+		for (const droppedReason of ["preempted", "session-mismatch", "persist-unavailable"] as const) {
+			expect(buildCompactFailureNotice({ outcome: "dropped", droppedReason })).not.toContain("重试");
+		}
+		expect(buildCompactFailureNotice({ outcome: "dropped" })).not.toContain("重试");
+	});
+});
+
+describe("落盘信号词表值锚定（extension-protocol SSOT，contract.notify-custom-types 先例同款）", () => {
+	it("SMART_CONTEXT_NOTICE_CUSTOM_TYPE === 'smart-context'（历史 session JSONL 已有该 customType entry，改值 = 跨侧破坏性变更）", () => {
+		expect(SMART_CONTEXT_NOTICE_CUSTOM_TYPE).toBe("smart-context");
+	});
+
+	it("COMPACTION_ENTRY_APPENDED_SOURCE === 'compaction-entry-appended'（runtime 分诊 details.source 字节契约）", () => {
+		expect(COMPACTION_ENTRY_APPENDED_SOURCE).toBe("compaction-entry-appended");
+	});
+});
+
+describe("sendSmartContextImmediateNotice（C2 手动触发失败回执：即时可见投递）", () => {
+	function makePi(): { pi: ExtensionAPI; sendMessage: ReturnType<typeof vi.fn> } {
+		const sendMessage = vi.fn();
+		return { pi: { sendMessage } as unknown as ExtensionAPI, sendMessage };
+	}
+
+	it("投递选项无 deliverAs（{triggerTurn:false}）——空闲即达，不进 nextTurn pending 队列", () => {
+		const { pi, sendMessage } = makePi();
+		sendSmartContextImmediateNotice(pi, "后台压缩未启动：原因", "compact-start-failed");
+		const [message, options] = sendMessage.mock.calls[0]!;
+		// toEqual 全量锁投递选项：无 deliverAs = pi sendCustomMessage 分支序不走
+		// _pendingNextTurnMessages（nextTurn 通道），空闲分支直接 _appendCustomMessage
+		// （立即 append + emit，用户当下可见——失败回执与触发动作不脱钩）
+		expect(options).toEqual({ triggerTurn: false });
+		// 消息载荷与 nextTurn 形态一致：customType 单源常量 + display:true 可见 + source 定位
+		expect(message).toEqual({
+			customType: SMART_CONTEXT_NOTICE_CUSTOM_TYPE,
+			content: "后台压缩未启动：原因",
+			display: true,
+			details: { source: "compact-start-failed" },
+		});
+	});
+
+	it("busy 回执同一即时形态（source=compact-busy）", () => {
+		const { pi, sendMessage } = makePi();
+		sendSmartContextImmediateNotice(pi, "后台压缩进行中", "compact-busy");
+		const [, options] = sendMessage.mock.calls[0]!;
+		expect(options).toEqual({ triggerTurn: false });
+	});
+
+	it("对照：sendSmartContextNotice（其余通知）保持 nextTurn 不动", () => {
+		const { pi, sendMessage } = makePi();
+		sendSmartContextNotice(pi, "后台压缩完成", "compact-complete");
+		const [, options] = sendMessage.mock.calls[0]!;
+		expect(options).toEqual({ triggerTurn: false, deliverAs: "nextTurn" });
+	});
+});
+
+describe("sendCompactionPersistSignal（C1 落盘信号：runtime 分诊消费的机器信号）", () => {
+	function makePi(impl?: () => void): { pi: ExtensionAPI; sendMessage: ReturnType<typeof vi.fn> } {
+		const sendMessage = vi.fn(impl);
+		return { pi: { sendMessage } as unknown as ExtensionAPI, sendMessage };
+	}
+
+	it("形态契约：customType 单源常量 + display:false + content 空串 + details{source, compactionId} + {triggerTurn:false} 无 deliverAs", () => {
+		const { pi, sendMessage } = makePi();
+		sendCompactionPersistSignal(pi, "entry-1");
+
+		expect(sendMessage).toHaveBeenCalledTimes(1);
+		const [message, options] = sendMessage.mock.calls[0]!;
+		expect(message).toEqual({
+			customType: SMART_CONTEXT_NOTICE_CUSTOM_TYPE,
+			content: "",
+			display: false,
+			details: { source: COMPACTION_ENTRY_APPENDED_SOURCE, compactionId: "entry-1" },
+		});
+		// toEqual 全量锁投递选项：无 deliverAs（空闲时 pi 立即 append 并 emit，秒级直达）
+		expect(options).toEqual({ triggerTurn: false });
+	});
+
+	it("compactionId undefined 透传（形状声明保守允许；runtime 侧降级尾部兜底）", () => {
+		const { pi, sendMessage } = makePi();
+		sendCompactionPersistSignal(pi, undefined);
+
+		expect(sendMessage.mock.calls[0]![0].details).toEqual({
+			source: COMPACTION_ENTRY_APPENDED_SOURCE,
+			compactionId: undefined,
+		});
+	});
+
+	it("sendMessage 同步抛错 → 内吞不上抛（上抛会把已落盘的压缩改记失败，dmg-r1-2 同语义）", () => {
+		const { pi, sendMessage } = makePi(() => {
+			throw new Error("boom");
+		});
+		expect(() => sendCompactionPersistSignal(pi, "entry-1")).not.toThrow();
+		expect(sendMessage).toHaveBeenCalledTimes(1);
+	});
+});

package/src/__tests__/pure.test.ts

@@ -46,6 +46,23 @@ describe("normalizeSmartContextConfig", () => {
 		const c = normalizeSmartContextConfig({ compactModel: { type: "regex", pattern: "x" } });
 		expect(c.compactModel).toEqual({ type: "ref", ref: "" });
 	});
+
+	it("autoCompactThresholdRatio 缺省/非法类型回默认 0.9（D4 用户裁决）", () => {
+		expect(DEFAULT_SMART_CONTEXT_CONFIG.autoCompactThresholdRatio).toBe(0.9);
+		expect(normalizeSmartContextConfig({}).autoCompactThresholdRatio).toBe(0.9);
+		expect(normalizeSmartContextConfig({ autoCompactThresholdRatio: "0.8" }).autoCompactThresholdRatio).toBe(0.9);
+		expect(normalizeSmartContextConfig({ autoCompactThresholdRatio: null }).autoCompactThresholdRatio).toBe(0.9);
+		expect(normalizeSmartContextConfig({ autoCompactThresholdRatio: Number.NaN }).autoCompactThresholdRatio).toBe(0.9);
+		expect(normalizeSmartContextConfig({ autoCompactThresholdRatio: Number.POSITIVE_INFINITY }).autoCompactThresholdRatio).toBe(0.9);
+	});
+
+	it("autoCompactThresholdRatio 有限数越界钳制到 [0,1]，区间内直通", () => {
+		expect(normalizeSmartContextConfig({ autoCompactThresholdRatio: 1.5 }).autoCompactThresholdRatio).toBe(1);
+		expect(normalizeSmartContextConfig({ autoCompactThresholdRatio: -0.2 }).autoCompactThresholdRatio).toBe(0);
+		expect(normalizeSmartContextConfig({ autoCompactThresholdRatio: 0.95 }).autoCompactThresholdRatio).toBe(0.95);
+		expect(normalizeSmartContextConfig({ autoCompactThresholdRatio: 0 }).autoCompactThresholdRatio).toBe(0);
+		expect(normalizeSmartContextConfig({ autoCompactThresholdRatio: 1 }).autoCompactThresholdRatio).toBe(1);
+	});
 });
 
 describe("门控与模式判定（D5/D12）", () => {
@@ -78,7 +95,7 @@ describe("门控与模式判定（D5/D12）", () => {
 });
 
 describe("阈值检查（D3/D6）", () => {
-	it("findCrossedThresholds：null tokens 容错为空（R7）；已 fired 排除", () => {
+	it("findCrossedThresholds：null tokens 容错为空（R7 旧编号，见 compact-handler.ts 头注消歧）；已 fired 排除", () => {
 		const tiers = [5_000, 10_000, 15_000];
 		expect(findCrossedThresholds(tiers, null, new Set())).toEqual([]);
 		expect(findCrossedThresholds(tiers, 11_000, new Set([5_000]))).toEqual([10_000]);
@@ -185,7 +202,8 @@ describe("deriveFiredThresholds（D15：session entries → 已提醒档位）",
 
 describe("estimateShadowedTokens 口径契约（D2：与 pi estimateTokens 同源）", () => {
 	// 合法 AssistantMessage 形状的 fixture（block 数组 content，禁止 as 硬塞 string content——
-	// estimateTokens 对 string content 计 0，口径用例会静默失去判别力；设计 §8.3）。
+	// estimateTokens 对 string content 计 0，口径用例会静默失去判别力；上一代接管设计 §8.3，
+	// 旧编号，文档已不在可达域，见 compact-handler.ts 头注消歧）。
 	// 不 import 名义类型：const 泛型保留 block 字面量形状，由 estimateShadowedTokens
 	// 参数类型（Parameters<typeof estimateTokens>[0]）在调用点结构校验。
 	function makeAssistantMessage<const C extends readonly unknown[]>(content: C) {

package/src/__tests__/summary.test.ts

@@ -14,7 +14,7 @@ vi.mock("../pure.js", async (importOriginal) => {
 });
 
 import { DEFAULT_SMART_CONTEXT_CONFIG, loadSmartContextConfig } from "../pure.js";
-import { buildCompactContextSummary, registerCompactContextTool } from "../tool.js";
+import { buildCompactContextSummary, registerCompactContextTool, type BackgroundCompactionControls } from "../tool.js";
 import { renderCompactContextResult } from "../render-result.js";
 
 const mockedLoad = vi.mocked(loadSmartContextConfig);
@@ -23,6 +23,11 @@ beforeEach(() => {
 	mockedLoad.mockReturnValue({ ...DEFAULT_SMART_CONTEXT_CONFIG });
 });
 
+/** 后台任务依赖注入桩（BackgroundCompactionControls 契约的测试替身，形态对齐 tool.test.ts）。 */
+function makeBackground(): BackgroundCompactionControls {
+	return { isActive: () => false, start: () => true };
+}
+
 interface RegisteredTool { // oe-exempt:20261017:test:测试 harness 契约——断言面引用其字段类型，非抽象接口
 	name: string;
 	execute: (
@@ -57,8 +62,8 @@ function makeCtx(): ExtensionContext {
 // ── buildCompactContextSummary ───────────────────────
 
 describe("buildCompactContextSummary", () => {
-	it("恒为 Context compacted（R2 降级态：返回时压缩未完成，无比例数据）", () => {
-		expect(buildCompactContextSummary()).toBe("Context compacted");
+	it("恒为「后台压缩已启动」（后台执行：返回时任务刚启动，完成语义由完成通知承载）", () => {
+		expect(buildCompactContextSummary()).toBe("后台压缩已启动");
 	});
 });
 
@@ -67,13 +72,11 @@ describe("buildCompactContextSummary", () => {
 describe("compact_context execute details.summary", () => {
 	it("details 带现有字段 + summary", async () => {
 		const { pi, tools } = makePi();
-		registerCompactContextTool(pi);
+		registerCompactContextTool(pi, { background: makeBackground() });
 		const res = await tools[0]!.execute("t1", {}, undefined, undefined, makeCtx());
 		expect(res.details).toMatchObject({
 			mode: "same-model",
-			launched: true,
-			fellBack: false,
-			summary: "Context compacted",
+			summary: "后台压缩已启动",
 		});
 	});
 });
@@ -105,7 +108,7 @@ function renderedText(result: unknown, expanded: boolean): string {
 describe("renderCompactContextResult", () => {
 	const result = {
 		content: [{ type: "text", text: "压缩已启动（same-model 模式）..." }],
-		details: { mode: "same-model", launched: true, summary: "Context compacted" },
+		details: { mode: "same-model", summary: "Context compacted" },
 	};
 
 	it("折叠态 → details.summary 一行", () => {

package/src/__tests__/tool.test.ts

@@ -10,7 +10,7 @@ vi.mock("../pure.js", async (importOriginal) => {
 });
 
 import { DEFAULT_SMART_CONTEXT_CONFIG, loadSmartContextConfig } from "../pure.js";
-import { registerCompactContextTool } from "../tool.js";
+import { registerCompactContextTool, type BackgroundCompactionControls } from "../tool.js";
 import { countCompactions } from "../pure.js";
 import type { ExtensionAPI, ExtensionContext, Theme } from "@earendil-works/pi-coding-agent";
 
@@ -23,38 +23,38 @@ interface RegisteredTool {
 	execute: (id: string, params: Record<string, unknown>, signal: undefined, onUpdate: undefined, ctx: ExtensionContext) => Promise<{ content: Array<{ type: string; text: string }>; details: Record<string, unknown> }>;
 }
 
-type CompactOpts = {
-	customInstructions?: string;
-	onComplete: (r: unknown) => void;
-	onError: (e: Error) => void;
-};
-
-function makePi(): { pi: ExtensionAPI & { sendMessage: ReturnType<typeof vi.fn>; sendUserMessage: ReturnType<typeof vi.fn> }; tools: RegisteredTool[] } {
+function makePi(): { pi: ExtensionAPI; tools: RegisteredTool[] } {
 	const tools: RegisteredTool[] = [];
 	const pi = {
 		registerTool: (t: RegisteredTool) => tools.push(t),
-		sendMessage: vi.fn(),
-		sendUserMessage: vi.fn(),
-	} as unknown as ExtensionAPI & { sendMessage: ReturnType<typeof vi.fn>; sendUserMessage: ReturnType<typeof vi.fn> };
+	} as unknown as ExtensionAPI;
 	return { pi, tools };
 }
 
-function makeCtx(compactImpl?: (options: CompactOpts) => void): ExtensionContext {
+/** ctx.compact 恒为 spy：RL5 交互断言——execute 不再触碰压缩执行路径，被调用即红。 */
+function makeCtx(): ExtensionContext {
 	return {
 		model: { provider: "zai", id: "glm" },
 		getContextUsage: () => ({ tokens: 450_000, contextWindow: 1_000_000 }),
 		sessionManager: { getEntries: () => [] },
-		compact: compactImpl ?? ((options: CompactOpts) => {
-			options.onComplete({
-				tokensBefore: 500_000,
-				estimatedTokensAfter: 24_000,
-				usage: { input: 432_000, output: 1_800, cacheRead: 0 },
-				details: { engine: "smart-context", mode: "same-model" },
-			});
-		}),
+		compact: vi.fn(),
 	} as unknown as ExtensionContext;
 }
 
+interface BackgroundSpies {
+	isActive: ReturnType<typeof vi.fn<() => boolean>>;
+	start: ReturnType<typeof vi.fn<(ctx: ExtensionContext, customInstructions?: string) => boolean>>;
+}
+
+/** 后台任务依赖注入桩（BackgroundCompactionControls 契约的测试替身）。 */
+function makeBackground(
+	{ active = false, startResult = true }: { active?: boolean; startResult?: boolean } = {},
+): { controls: BackgroundCompactionControls; spies: BackgroundSpies } {
+	const isActive = vi.fn((): boolean => active);
+	const start = vi.fn((_ctx: ExtensionContext, _customInstructions?: string): boolean => startResult);
+	return { controls: { isActive, start }, spies: { isActive, start } };
+}
+
 const mockedLoad = vi.mocked(loadSmartContextConfig);
 
 beforeEach(() => {
@@ -62,7 +62,7 @@ beforeEach(() => {
 	mockedLoad.mockReturnValue(DEFAULT_SMART_CONTEXT_CONFIG);
 });
 
-describe("compact_context 工具（R2 降级态：fire-and-forget + 结果注入）", () => {
+describe("compact_context 工具（U4 纯触发化：后台任务触发 + 立即回执）", () => {
 	it("parameters 顶层为 Type.Object（OpenAI 兼容红线）", () => {
 		const { pi, tools } = makePi();
 		registerCompactContextTool(pi);
@@ -81,13 +81,25 @@ describe("compact_context 工具（R2 降级态：fire-and-forget + 结果注入
 		expect(tools[0]!.exposure).toBeUndefined();
 	});
 
-	it("门控拒绝（排除命中）→ throw 带原因与恢复指引（D5）", async () => {
+	// V7 工具路径回归：门控拒绝回现状文案，且不触达后台任务（无后台任务启动）
+	it("门控拒绝（排除命中）→ throw 带原因与恢复指引（D5），不触达后台任务（V7）", async () => {
 		mockedLoad.mockReturnValue({ ...DEFAULT_SMART_CONTEXT_CONFIG, excludedModels: ["zai/glm"] });
 		const { pi, tools } = makePi();
-		registerCompactContextTool(pi, { gatingProbe: () => ({ active: false, modelId: "zai/glm" }) });
+		const { controls, spies } = makeBackground();
+		registerCompactContextTool(pi, { gatingProbe: () => ({ active: false, modelId: "zai/glm" }), background: controls });
 		await expect(tools[0].execute("t1", {}, undefined, undefined, makeCtx())).rejects.toThrow(/已配置为排除/);
+		expect(spies.isActive).not.toHaveBeenCalled();
+		expect(spies.start).not.toHaveBeenCalled();
 	});
 
+	it("门控拒绝（禁用）→ throw 带恢复指引（D5）", async () => {
+		mockedLoad.mockReturnValue({ ...DEFAULT_SMART_CONTEXT_CONFIG, enabled: false });
+		const { pi, tools } = makePi();
+		registerCompactContextTool(pi, { gatingProbe: () => ({ active: false, modelId: "zai/glm" }) });
+		await expect(tools[0].execute("t1", {}, undefined, undefined, makeCtx())).rejects.toThrow(/已禁用/);
+	});
+
+	// A9 成本护栏（UC-12）：checkToolThresholdGuard 保留的既有用例
 	it("阈值保护：低于最低档 throw 带用量数据（D6）", async () => {
 		const { pi, tools } = makePi();
 		registerCompactContextTool(pi, { usageProbe: () => ({ tokens: 38_000, contextWindow: 1_000_000 }) });
@@ -100,79 +112,76 @@ describe("compact_context 工具（R2 降级态：fire-and-forget + 结果注入
 		await expect(tools[0].execute("t1", {}, undefined, undefined, makeCtx())).rejects.toThrow(/用量未知/);
 	});
 
-	it("execute 立即返回「已启动」（不 await 压缩完成，R2 契约）+ details 结构化", async () => {
+	// RL5 单测半边：工具触发路径不再掐断进行中回合——mock 层断言不再调用压缩执行
+	// 路径（ctx.compact 的 abort 副作用随之消失）+ 启动后台任务后立即回执（GL1）
+	it("RL5：execute 不触碰 ctx.compact 压缩执行路径（交互断言）+ 启动后台任务立即回执", async () => {
 		const { pi, tools } = makePi();
-		registerCompactContextTool(pi, { getEntries: () => [{ type: "message" }] });
-		const result = await tools[0].execute("t1", {}, undefined, undefined, makeCtx());
+		const { controls, spies } = makeBackground();
+		const ctx = makeCtx();
+		registerCompactContextTool(pi, { getEntries: () => [{ type: "message" }], background: controls });
+		const result = await tools[0].execute("t1", {}, undefined, undefined, ctx);
+		expect(ctx.compact).not.toHaveBeenCalled();
+		expect(spies.start).toHaveBeenCalledTimes(1);
+		expect(spies.start.mock.calls[0]?.[0]).toBe(ctx);
 		expect(result.content[0].text).toContain("压缩已启动");
-		expect(result.content[0].text).toContain("same-model");
-		expect(result.details).toMatchObject({ mode: "same-model", launched: true, fellBack: false, compactionCount: 1 });
+		expect(result.content[0].text).toContain("后台进行");
+		expect(result.content[0].text).toContain("可以继续任何工作");
+		// 等待指引退役：不再要求「引用早期上下文的操作等结果消息到达」
+		expect(result.content[0].text).not.toContain("等结果消息");
+		expect(result.details).toMatchObject({ mode: "same-model", compactionCount: 1 });
 	});
 
-	it("renderResult 接线（C-ext-05）：注册定义携带函数成员 + 折叠态输出 details.summary 一行", async () => {
+	it("custom_instructions 透传给后台启动；空白串归一为 undefined", async () => {
 		const { pi, tools } = makePi();
-		registerCompactContextTool(pi, { getEntries: () => [{ type: "message" }] });
-		const tool = tools[0];
-		expect(typeof tool.renderResult).toBe("function");
-		const result = await tool.execute("t1", {}, undefined, undefined, makeCtx());
-		const renderTheme = { fg: (_token: string, text: string) => text } as unknown as Theme;
-		const lines = tool.renderResult!(result, { expanded: false }, renderTheme).render(400);
-		// Text.render 按宽度 pad，trim 后断言（折叠态 = details.summary 一行）
-		expect(lines.length).toBe(1);
-		expect(lines[0].trim()).toBe("Context compacted");
+		const { controls, spies } = makeBackground();
+		registerCompactContextTool(pi, { background: controls });
+		await tools[0].execute("t1", { custom_instructions: "保留验证结果" }, undefined, undefined, makeCtx());
+		expect(spies.start.mock.calls[0]?.[1]).toBe("保留验证结果");
+		await tools[0].execute("t1", { custom_instructions: "   " }, undefined, undefined, makeCtx());
+		expect(spies.start.mock.calls[1]?.[1]).toBeUndefined();
 	});
 
-	it("onComplete 兑现后 nextTurn 注入结果（含模式/前后 tokens/成本；降智提示按次数）", async () => {
+	// RL1 互斥幂等：已有后台任务进行中 → 幂等成功回执（不是错误），不再启动
+	it("互斥幂等：后台任务进行中 →「后台压缩进行中」成功回执，不再启动新任务", async () => {
 		const { pi, tools } = makePi();
-		registerCompactContextTool(pi, { getEntries: () => [{ type: "compaction" }, { type: "compaction" }] });
-		await tools[0].execute("t1", {}, undefined, undefined, makeCtx());
-		expect(pi.sendMessage).toHaveBeenCalledTimes(1);
-		const [message, options] = pi.sendMessage.mock.calls[0];
-		// D4①：nextTurn 化——custom role 消息 + 不自起 run 的投递路径
-		expect(message.customType).toBe("smart-context");
-		expect(message.details).toEqual({ source: "compact-complete" });
-		expect(options).toEqual({ triggerTurn: false, deliverAs: "nextTurn" });
-		const text = message.content as string;
-		expect(text).toContain("压缩完成");
-		expect(text).toContain("same-model");
-		expect(text).toContain("500K");
-		expect(text).toContain("24K");
-		expect(text).toContain("compacted multiple times");
-		// 旧投递路径（自起 run 的 user 消息）已退役：不再调用 sendUserMessage（mock 挂 spy，被调用即断言红）
-		expect(pi.sendUserMessage).not.toHaveBeenCalled();
+		const { controls, spies } = makeBackground({ active: true });
+		registerCompactContextTool(pi, { background: controls });
+		const result = await tools[0].execute("t1", {}, undefined, undefined, makeCtx());
+		expect(result.content[0].text).toContain("后台压缩进行中");
+		expect(result.content[0].text).toContain("可以继续任何工作");
+		expect(spies.start).not.toHaveBeenCalled();
+		// 无新任务启动，压缩序号不变
+		expect(result.details).toMatchObject({ compactionCount: 0 });
 	});
 
-	it("onComplete 无 engine 标记 → 注入消息含回退说明与修复指引（D7）", async () => {
+	it("竞态兜底：isActive 空闲但 start 返回 false（互斥撞上）→ 同幂等回执", async () => {
 		const { pi, tools } = makePi();
-		registerCompactContextTool(pi);
-		const ctx = makeCtx((options) => options.onComplete({ tokensBefore: 1, estimatedTokensAfter: 1 }));
-		await tools[0].execute("t1", {}, undefined, undefined, ctx);
-		expect(pi.sendMessage).toHaveBeenCalledTimes(1);
-		expect(pi.sendMessage.mock.calls[0][0].content).toContain("回退");
+		const { controls } = makeBackground({ startResult: false });
+		registerCompactContextTool(pi, { background: controls });
+		const result = await tools[0].execute("t1", {}, undefined, undefined, makeCtx());
+		expect(result.content[0].text).toContain("后台压缩进行中");
 	});
 
-	it("onError → 注入失败消息带重试指引（display:true 失败必须用户可见 + nextTurn 投递路径不自起 run）", async () => {
+	// 接线缺失 fail-fast：不撒谎回执、不静默降级（BackgroundCompactionControls 契约）
+	it("background 未注入（生产接线缺失）→ 门控与阈值检查后抛「后台压缩未接线」", async () => {
 		const { pi, tools } = makePi();
-		registerCompactContextTool(pi);
-		const ctx = makeCtx((options) => options.onError(new Error("Nothing to compact")));
-		await tools[0].execute("t1", {}, undefined, undefined, ctx);
-		const [message, options] = pi.sendMessage.mock.calls[0];
-		expect(message.content).toContain("压缩失败");
-		expect(message.content).toContain("Nothing to compact");
-		expect(message.details).toEqual({ source: "compact-failed" });
-		expect(options).toEqual({ triggerTurn: false, deliverAs: "nextTurn" });
+		registerCompactContextTool(pi, { getEntries: () => [{ type: "message" }] });
+		await expect(tools[0].execute("t1", {}, undefined, undefined, makeCtx())).rejects.toThrow(/后台压缩未接线/);
 	});
 
-	it("custom_instructions 透传给 ctx.compact", async () => {
-		let received: string | undefined;
+	it("renderResult 接线（C-ext-05）：注册定义携带函数成员 + 折叠态输出 details.summary 一行", async () => {
 		const { pi, tools } = makePi();
-		registerCompactContextTool(pi);
-		const ctx = makeCtx((options) => {
-			received = options.customInstructions;
-			options.onComplete({ details: { engine: "smart-context", mode: "cross-model" } });
-		});
-		await tools[0].execute("t1", { custom_instructions: "保留验证结果" }, undefined, undefined, ctx);
-		expect(received).toBe("保留验证结果");
+		const { controls } = makeBackground();
+		registerCompactContextTool(pi, { background: controls });
+		const tool = tools[0];
+		expect(typeof tool.renderResult).toBe("function");
+		const result = await tool.execute("t1", {}, undefined, undefined, makeCtx());
+		const renderTheme = { fg: (_token: string, text: string) => text } as unknown as Theme;
+		const lines = tool.renderResult!(result, { expanded: false }, renderTheme).render(400);
+		// Text.render 按宽度 pad，trim 后断言（折叠态 = details.summary 一行；U5 文案：
+		// 工具返回时任务刚启动，「已完成」语义由完成通知承载）
+		expect(lines.length).toBe(1);
+		expect(lines[0].trim()).toBe("后台压缩已启动");
 	});
 
 	it("countCompactions 只数 compaction entries", () => {