@zhushanwen/pi-permission 0.0.1 → 0.1.0

package/README.md

@@ -12,7 +12,7 @@ Pi permission 扩展 — 四档权限模式（yolo / auto / approve / strict）+
 - **AI Classifier**：auto 模式下用 LLM 评估未知命令风险（low/medium/high）
 - **用户审批 UI**：TUI（自定义 Component）/ RPC（select 对话框）/ headless（fail-closed deny）
 - **Reject-with-Reason**：用户拒绝时可输入真实理由（回传 agent 辅助理解）
-- **statusline 集成**：TUI 底部显示当前权限模式标签
+- **statusline 集成**：TUI 底部 footer 显示当前权限模式标签（通过 globalThis Symbol 握手协议向 statusline 注册一行 footer line renderer）
 - **fail-closed**：任何异常路径 → block（绝不静默放行）
 
 ## 安装
@@ -383,17 +383,40 @@ auto 模式下层 3 用 LLM 评估未知命令风险：
 
 ## statusline 集成
 
-session_start 时注册权限 footer，在 TUI 底部显示当前模式标签：
+permission 不再自管 footer，而是通过 **globalThis Symbol 握手协议** 向 `@zhushanwen/pi-statusline` 注册一行 footer line renderer（`session_start` 时调用 `registerPermissionFooterLine`）：
+
+- **statusline 是 footer canonical owner**：唯一创建 footer registry（`getOrCreateFooterRegistry`）。
+- **permission 是 consumer**：永不创建 registry 实例，永不写 `slot.registry` 字段；只通过 `FOOTER_HANDSHAKE_KEY = Symbol.for('@zhushanwen/pi-statusline.footerHandshake')` 读写 slot。
+- **插入位置**：renderer `order=2`，聚合排序后落在 line2（model）和 line3（ctx）之间。
+- **加载顺序无关**：slot 形状 `{version, registry?, pending:[]}`。registry 未就绪时 consumer 只 push pending，等 statusline 后到时 flush（沿用 ask-user 的 pending-flush 修复模式）。
+- **无代码层 import**：permission 仅对 statusline 做运行时 `globalThis` 反射，statusline 是可选 `peerDep`，未安装时静态 import 不会破坏 permission。
+- **重绘触发**：mode/enabled 切换后调用 `requestFooterRender()`（`REQUEST_RENDER_KEY`），statusline 立即重绘 footer。
+
+footer line 内容（精简版，避免 footer 拥挤）：
 
 ```
-[pi-permission] Auto · enabled AST + rules + AI classifier
+[permission] Auto · enabled
+[permission] disabled
 ```
 
 模式标签：YOLO / Auto / Approve / Strict（对应 yolo/auto/approve/strict）。
 
+**未安装 statusline 时 silent 降级**：permission 功能完整，仅 footer 不显示 mode 标签。可用 `/permission status` 查看 mode。
+
+## 升级须知
+
+**v0.0.1 → v0.1.0 breaking change**：本扩展不再自管 footer，权限模式标签现在由 `@zhushanwen/pi-statusline` 聚合提供（通过 globalThis Symbol 握手协议）。此前 footer 由各扩展各自调用 `ctx.ui.setFooter` 单例渲染、互相覆盖。
+
+- **同时安装 statusline 的用户**：无需任何操作。mode 标签自动作为 statusline footer 的一行出现（line2 和 line3 之间）。
+- **未安装 statusline 的用户**：footer 不再显示 mode 标签。两种恢复方式：
+  - 安装 statusline：`pi install npm:@zhushanwen/pi-statusline`，mode 标签回到 footer。
+  - 或随时用 `/permission status` 查看/切换 mode（不依赖 footer）。
+
+详见下方「statusline 集成」章节。
+
 ## 已知限制
 
-- **Footer 单例覆盖**：Pi 只有一个 footer 槽位。本扩展的 footer 会覆盖（或被覆盖）其他扩展的 footer，最典型的冲突是 **`@zhushanwen/pi-statusline`**（两者都注册 footer）。若同时安装，后注册者覆盖前者。要同时显示两者，需自行 fork 合并 footer 渲染逻辑。可用 `grep -r "setFooter" ~/.pi/agent/extensions/` 排查冲突。
+- **Footer 由 statusline 聚合**：本扩展不再自管 footer，mode 标签通过 globalThis Symbol 握手协议向 `@zhushanwen/pi-statusline` 注册（见「statusline 集成」）。未安装 statusline 时 footer 不显示 mode 标签（silent 降级，不影响功能）。
 - **TUI Reject-with-Reason**：当前 RPC 分支已完整接入 `ctx.ui.input` 采集拒绝理由；TUI 分支因 pi-tui Input 组件集成成本较高，暂保留简化 deny（固定文案），后续迭代补齐内联文本输入。
 - **headless 模式**：json/print 模式无交互 UI，所有审批请求 fail-closed deny（不阻塞自动化流程，但 strict/approve 模式下无法放行）。
 - **wasm 加载**：AST 分析依赖 tree-sitter-bash wasm，加载失败时 fail-closed（clean=false, parseError=true）。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-permission",
-  "version": "0.0.1",
+  "version": "0.1.0",
   "description": "Pi permission extension — four permission modes (yolo/auto/approve/strict) with three-layer pipeline (AST + rules + AI classifier).",
   "type": "module",
   "main": "src/index.ts",
@@ -29,7 +29,8 @@
   "peerDependencies": {
     "@earendil-works/pi-ai": "*",
     "@earendil-works/pi-coding-agent": "*",
-    "@earendil-works/pi-tui": "*"
+    "@earendil-works/pi-tui": "*",
+    "@zhushanwen/pi-statusline": "*"
   },
   "peerDependenciesMeta": {
     "@earendil-works/pi-ai": {
@@ -37,6 +38,9 @@
     },
     "@earendil-works/pi-tui": {
       "optional": true
+    },
+    "@zhushanwen/pi-statusline": {
+      "optional": true
     }
   },
   "devDependencies": {

package/src/__tests__/footer-provider.test.ts

@@ -0,0 +1,342 @@
+/**
+ * footer-provider.test.ts — consumer 端握手协议 + footer 渲染测试。
+ *
+ * 覆盖：
+ *  - TC1：slot 不存在 → consumer 建新 slot（仅 pending，registry 空）
+ *  - TC2：slot 存在 + registry 就绪 → 直接 register（不走 pending）
+ *  - TC3：slot 存在 + registry 未就绪 → push pending
+ *  - TC4：dispose（registry 就绪路径）→ unregister + requestFooterRender
+ *  - TC5：dispose（pending 路径）→ 从 pending 移除 + requestFooterRender
+ *  - TC6：requestFooterRender（statusline 未安装）→ noop（不抛）
+ *  - TC7：requestFooterRender（已注册 fn）→ 调用 fn
+ *  - TC8：version mismatch → readSlot 返回 undefined + warn + ensureSlot 重建
+ *  - TC13：dispose 幂等（重复调用安全）
+ *  - 渲染：renderPermissionFooterLine 四档模式 + enabled/disabled
+ *  - 字面量跨端一致：FOOTER_HANDSHAKE_KEY / REQUEST_RENDER_KEY 与 statusline owner 端 ===
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import {
+	FOOTER_HANDSHAKE_KEY,
+	type FooterLineRenderer,
+	registerPermissionFooterLine,
+	renderPermissionFooterLine,
+	REQUEST_RENDER_KEY,
+	requestFooterRender,
+} from "../footer-provider.js";
+import type { PermissionPalette } from "../statusline-palette.js";
+import type { PermissionMode } from "../types.js";
+import { MODE_LABELS } from "../types.js";
+
+// ──────────────────────── mock helpers ────────────────────────
+
+/** 透传 palette（不加 ANSI，便于断言原始字符串）。 */
+function passthroughPalette(): PermissionPalette {
+	return {
+		dim: (s) => s,
+		text: (s) => s,
+		accent: (s) => s,
+		success: (s) => s,
+		warning: (s) => s,
+	};
+}
+
+/** 构造最小 renderer（render 返回固定行）。 */
+function makeRenderer(order = 2, line = "permission-line"): FooterLineRenderer {
+	return {
+		order,
+		render: () => line,
+	};
+}
+
+/**
+ * mock registry 的显式返回类型。
+ *
+ * 结构上兼容 footer-provider.ts 的 FooterLineRegistry 接口（register/unregister），
+ * 额外暴露 has/calls 供断言。footer-provider.ts 的 FooterLineRegistry 未导出，
+ * 这里用结构等价契约绑定：若 footer-provider.ts 的 registry 接口签名漂移（如
+ * register 增加 id 规范化、unregister 改名），mock 会在传入 slot.registry 时
+ * 编译期暴露（slot 字面量的 registry 字段需满足该结构）。
+ *
+ * register 的 renderer 参数用导出的 FooterLineRenderer 替代原先的 unknown，
+ * 让 mock 与 consumer 端 renderer 契约漂移时编译期即可发现。
+ */
+interface MockFooterRegistry {
+	register(id: string, renderer: FooterLineRenderer): void;
+	unregister(id: string): void;
+	has(id: string): boolean;
+	calls: { op: "register" | "unregister"; id: string }[];
+}
+
+/** mock registry：记录 register/unregister 调用，内部 Map 存储。 */
+function makeRegistry(): MockFooterRegistry {
+	const map = new Map<string, FooterLineRenderer>();
+	const calls: { op: "register" | "unregister"; id: string }[] = [];
+	return {
+		register(id: string, renderer: FooterLineRenderer): void {
+			calls.push({ op: "register", id });
+			map.set(id, renderer);
+		},
+		unregister(id: string): void {
+			calls.push({ op: "unregister", id });
+			map.delete(id);
+		},
+		has: (id: string): boolean => map.has(id),
+		calls,
+	};
+}
+
+/** 读当前 slot（version 守卫后）。 */
+function getRawSlot(): unknown {
+	return Reflect.get(globalThis, FOOTER_HANDSHAKE_KEY);
+}
+
+/** 清理 globalThis 上的握手 slot + requestRender fn（每个测试隔离）。 */
+function cleanGlobalThis(): void {
+	Reflect.deleteProperty(globalThis, FOOTER_HANDSHAKE_KEY);
+	Reflect.deleteProperty(globalThis, REQUEST_RENDER_KEY);
+}
+
+beforeEach(() => {
+	cleanGlobalThis();
+});
+
+afterEach(() => {
+	cleanGlobalThis();
+});
+
+// ──────────────────────── TC1：slot 不存在 → consumer 建新 slot（pending） ────────────────────────
+
+describe("TC1：slot 不存在 → consumer 建新 slot（仅 pending，registry 空）", () => {
+	it("无 slot 时注册 → 新 slot 含 pending 一项，registry 未定义", () => {
+		expect(getRawSlot()).toBeUndefined();
+		registerPermissionFooterLine(makeRenderer());
+		const slot = getRawSlot() as { version: number; registry?: unknown; pending: unknown[] };
+		expect(slot).toBeDefined();
+		expect(slot.version).toBe(1);
+		expect(slot.registry).toBeUndefined(); // consumer 永不创建 registry
+		expect(slot.pending).toHaveLength(1);
+		expect((slot.pending[0] as { id: string }).id).toBe("pi-permission");
+	});
+});
+
+// ──────────────────────── TC2：slot 存在 + registry 就绪 → 直接 register ────────────────────────
+
+describe("TC2：slot 存在 + registry 就绪 → 直接 register（不走 pending）", () => {
+	it("registry 已就绪 → 调 registry.register，pending 不变", () => {
+		const registry = makeRegistry();
+		// 预置 owner 端就绪的 slot（registry 已填）
+		Reflect.set(globalThis, FOOTER_HANDSHAKE_KEY, {
+			version: 1,
+			registry,
+			pending: [],
+		});
+		registerPermissionFooterLine(makeRenderer());
+		expect(registry.has("pi-permission")).toBe(true);
+		expect(registry.calls.filter((c) => c.op === "register")).toHaveLength(1);
+	});
+});
+
+// ──────────────────────── TC3：slot 存在 + registry 未就绪 → push pending ────────────────────────
+
+describe("TC3：slot 存在 + registry 未就绪 → push pending", () => {
+	it("slot 存在但 registry 空 → 新 entry 进 pending（不调 register）", () => {
+		// 预置一个 consumer 先建的空 slot（pending 已有别的 entry）
+		Reflect.set(globalThis, FOOTER_HANDSHAKE_KEY, {
+			version: 1,
+			pending: [{ id: "other", renderer: makeRenderer(0) }],
+		});
+		registerPermissionFooterLine(makeRenderer());
+		const slot = getRawSlot() as { pending: { id: string }[] };
+		expect(slot.pending).toHaveLength(2);
+		expect(slot.pending.some((p) => p.id === "pi-permission")).toBe(true);
+	});
+});
+
+// ──────────────────────── TC4：dispose（registry 就绪）→ unregister ────────────────────────
+
+describe("TC4：dispose（registry 就绪路径）→ unregister + requestFooterRender", () => {
+	it("registry 就绪时 dispose → registry.unregister + 调 requestRender fn", () => {
+		const registry = makeRegistry();
+		Reflect.set(globalThis, FOOTER_HANDSHAKE_KEY, {
+			version: 1,
+			registry,
+			pending: [],
+		});
+		const renderFn = vi.fn();
+		Reflect.set(globalThis, REQUEST_RENDER_KEY, renderFn);
+
+		const dispose = registerPermissionFooterLine(makeRenderer());
+		expect(registry.has("pi-permission")).toBe(true);
+		dispose();
+		expect(registry.has("pi-permission")).toBe(false);
+		expect(renderFn).toHaveBeenCalledOnce();
+	});
+});
+
+// ──────────────────────── TC5：dispose（pending 路径）→ 从 pending 移除 ────────────────────────
+
+describe("TC5：dispose（pending 路径）→ 从 pending 移除 + requestFooterRender", () => {
+	it("registry 未就绪时 dispose → pending 过滤掉 pi-permission + 调 requestRender fn", () => {
+		// 空 slot（pending 路径）
+		const renderFn = vi.fn();
+		Reflect.set(globalThis, REQUEST_RENDER_KEY, renderFn);
+
+		const dispose = registerPermissionFooterLine(makeRenderer());
+		const slotBefore = getRawSlot() as { pending: { id: string }[] };
+		expect(slotBefore.pending).toHaveLength(1);
+
+		dispose();
+		const slotAfter = getRawSlot() as { pending: { id: string }[] };
+		expect(slotAfter.pending.some((p) => p.id === "pi-permission")).toBe(false);
+		expect(renderFn).toHaveBeenCalledOnce();
+	});
+});
+
+// ──────────────────────── TC6/TC7：requestFooterRender ────────────────────────
+
+describe("TC6/TC7：requestFooterRender", () => {
+	it("TC6：statusline 未安装（无 REQUEST_RENDER_KEY）→ noop，不抛异常", () => {
+		expect(() => requestFooterRender()).not.toThrow();
+	});
+
+	it("TC7：已注册 fn → 调用 fn", () => {
+		const fn = vi.fn();
+		Reflect.set(globalThis, REQUEST_RENDER_KEY, fn);
+		requestFooterRender();
+		expect(fn).toHaveBeenCalledOnce();
+	});
+});
+
+// ──────────────────────── TC8：version mismatch → 重建 slot ────────────────────────
+
+describe("TC8：version mismatch → readSlot 丢弃 + ensureSlot 重建", () => {
+	it("slot.version !== 1 → 注册时建新 slot（丢弃旧的），并 console.warn", () => {
+		const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+		// 污染槽位：version=99
+		Reflect.set(globalThis, FOOTER_HANDSHAKE_KEY, {
+			version: 99,
+			pending: [],
+		});
+		registerPermissionFooterLine(makeRenderer());
+		const slot = getRawSlot() as { version: number; pending: unknown[] };
+		expect(slot.version).toBe(1); // 重建为 version=1
+		expect(slot.pending).toHaveLength(1);
+		expect(warnSpy).toHaveBeenCalledWith(
+			expect.stringContaining("version mismatch"),
+		);
+		warnSpy.mockRestore();
+	});
+
+	it("pending 非 Array → 视为无 slot，重建", () => {
+		Reflect.set(globalThis, FOOTER_HANDSHAKE_KEY, {
+			version: 1,
+			pending: "not-an-array",
+		});
+		registerPermissionFooterLine(makeRenderer());
+		const slot = getRawSlot() as { pending: unknown[] };
+		expect(Array.isArray(slot.pending)).toBe(true);
+		expect(slot.pending).toHaveLength(1);
+	});
+});
+
+// ──────────────────────── TC13：dispose 幂等 ────────────────────────
+
+describe("TC13：dispose 幂等（重复调用安全）", () => {
+	it("dispose 两次 → 第二次 noop（once-guard：不重复 unregister / requestRender）", () => {
+		const registry = makeRegistry();
+		Reflect.set(globalThis, FOOTER_HANDSHAKE_KEY, {
+			version: 1,
+			registry,
+			pending: [],
+		});
+		const renderFn = vi.fn();
+		Reflect.set(globalThis, REQUEST_RENDER_KEY, renderFn);
+
+		const dispose = registerPermissionFooterLine(makeRenderer());
+		dispose();
+		// 第二次：once-guard 生效，不应再触发副作用
+		expect(() => dispose()).not.toThrow();
+		expect(registry.calls.filter((c) => c.op === "unregister")).toHaveLength(1);
+		expect(renderFn).toHaveBeenCalledOnce();
+	});
+
+	it("dispose 后 slot 整个被删 → 再次 dispose 不抛（once-guard）", () => {
+		const dispose = registerPermissionFooterLine(makeRenderer());
+		Reflect.deleteProperty(globalThis, FOOTER_HANDSHAKE_KEY);
+		expect(() => dispose()).not.toThrow();
+	});
+});
+
+// ──────────────────────── renderPermissionFooterLine 渲染 ────────────────────────
+
+describe("renderPermissionFooterLine（mode + enabled + rule count + classifier）", () => {
+	const ALL_MODES: PermissionMode[] = ["yolo", "auto", "approve", "strict"];
+
+	it("enabled=true 非 auto → '[permission] <LABEL> · enabled · N user rules'", () => {
+		const palette = passthroughPalette();
+		for (const mode of ALL_MODES.filter((m) => m !== "auto")) {
+			const line = renderPermissionFooterLine(mode, true, 3, "gpt-4", palette);
+			expect(line).toContain("[permission]");
+			expect(line).toContain(MODE_LABELS[mode]);
+			expect(line).toContain("enabled");
+			expect(line).toContain("3 user rules");
+			// 非 auto 模式不显示 classifier
+			expect(line).not.toContain("classifier");
+		}
+	});
+
+	it("enabled=true + auto 模式 + 有 model → 含 classifier model", () => {
+		const palette = passthroughPalette();
+		const line = renderPermissionFooterLine("auto", true, 2, "zhipu/glm-4-flash", palette);
+		expect(line).toContain("[permission]");
+		expect(line).toContain(MODE_LABELS["auto"]);
+		expect(line).toContain("enabled");
+		expect(line).toContain("2 user rules");
+		expect(line).toContain("classifier: zhipu/glm-4-flash");
+	});
+
+	it("enabled=true + auto 模式 + model 为空 → 不显示 classifier 段", () => {
+		const palette = passthroughPalette();
+		const line = renderPermissionFooterLine("auto", true, 0, "", palette);
+		expect(line).toContain("0 user rules");
+		expect(line).not.toContain("classifier");
+	});
+
+	it("enabled=true + ruleCount=1 → 'rule'（单数）", () => {
+		const palette = passthroughPalette();
+		const line = renderPermissionFooterLine("strict", true, 1, "", palette);
+		expect(line).toContain("1 user rule");
+		expect(line).not.toContain("1 user rules");
+	});
+
+	it("enabled=false → '[permission] disabled'（不含 LABEL/rule/classifier）", () => {
+		const palette = passthroughPalette();
+		for (const mode of ALL_MODES) {
+			const line = renderPermissionFooterLine(mode, false, 3, "gpt-4", palette);
+			expect(line).toContain("[permission]");
+			expect(line).toContain("disabled");
+			// disabled 时精简：不显示 mode label / rule count / classifier
+			expect(line).not.toContain(MODE_LABELS[mode]);
+			expect(line).not.toContain("rule");
+			expect(line).not.toContain("classifier");
+		}
+	});
+
+	it("返回单行字符串（非数组）", () => {
+		const line = renderPermissionFooterLine("auto", true, 1, "gpt-4", passthroughPalette());
+		expect(typeof line).toBe("string");
+	});
+});
+
+// ──────────────────────── 字面量跨端一致（与 statusline owner 端 === ） ────────────────────────
+
+describe("协议字面量跨端一致（permission consumer === statusline owner）", () => {
+	it("FOOTER_HANDSHAKE_KEY 是 Symbol.for 同一字符串（Symbol.for 跨 realm 同引用）", () => {
+		expect(FOOTER_HANDSHAKE_KEY).toBe(Symbol.for("@zhushanwen/pi-statusline.footerHandshake"));
+	});
+
+	it("REQUEST_RENDER_KEY 是 Symbol.for 同一字符串", () => {
+		expect(REQUEST_RENDER_KEY).toBe(Symbol.for("@zhushanwen/pi-statusline.requestRender"));
+	});
+});

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

@@ -19,6 +19,7 @@ import { join } from "node:path";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { afterEach, beforeEach, describe, expect, it } from "vitest";
 
+import { FOOTER_HANDSHAKE_KEY, REQUEST_RENDER_KEY } from "../footer-provider.js";
 import permissionExtension from "../index.js";
 
 // ──────────────────────── mock pi ────────────────────────
@@ -73,6 +74,15 @@ function getSessionStartHandler(calls: MockPiCalls): (event: unknown, ctx: unkno
 	return handlers[0];
 }
 
+/** 提取 session_tree handler。 */
+function getSessionTreeHandler(calls: MockPiCalls): (event: unknown, ctx: unknown) => unknown {
+	const handlers = calls.eventHandlers.get("session_tree");
+	if (!handlers || handlers.length === 0) {
+		throw new Error("session_tree handler not registered");
+	}
+	return handlers[0];
+}
+
 /** 构造 mock ctx（含 mode/ui/signal）。 */
 function makeCtx(mode: "tui" | "rpc" | "json" | "print" = "json"): unknown {
 	return {
@@ -125,6 +135,9 @@ beforeEach(() => {
 afterEach(() => {
 	delete process.env.PI_CODING_AGENT_DIR;
 	if (existsSync(TMP_ROOT)) rmSync(TMP_ROOT, { recursive: true, force: true });
+	// 清理 footer 握手 slot（session_start/session_tree handler 会写 globalThis）
+	Reflect.deleteProperty(globalThis, FOOTER_HANDSHAKE_KEY);
+	Reflect.deleteProperty(globalThis, REQUEST_RENDER_KEY);
 });
 
 // ──────────────────────── 测试 ────────────────────────
@@ -280,3 +293,92 @@ describe("W8 /permission rule 命令集成", () => {
 		await expect(handler("rule", ctx)).resolves.not.toThrow();
 	});
 });
+
+// ──────────────────────── footer line 注册（duck typing + session_tree）────────────────────────
+
+describe("footer line 注册", () => {
+	it("session_start：ctx.ui 无 theme → registerFooterLineFor 返回 noop dispose，不抛异常", () => {
+		writeConfig("yolo");
+		const { pi, calls } = createMockPi();
+		permissionExtension(pi);
+		const sessionHandler = getSessionStartHandler(calls);
+
+		// ctx.ui 完全无 theme 字段（headless/mock 形状）。
+		// registerFooterLineFor 的 duck typing 守卫应命中，返回 () => {} 而不调
+		// registerPermissionFooterLine（故 globalThis 不应出现握手 slot）。
+		const ctxNoTheme = { mode: "json", cwd: "/tmp", ui: {}, signal: undefined };
+		expect(() => sessionHandler({}, ctxNoTheme)).not.toThrow();
+		expect(Reflect.get(globalThis, FOOTER_HANDSHAKE_KEY)).toBeUndefined();
+	});
+
+	it("session_start：ctx.ui.theme 存在但 fg 非函数 → noop dispose，不抛异常", () => {
+		writeConfig("yolo");
+		const { pi, calls } = createMockPi();
+		permissionExtension(pi);
+		const sessionHandler = getSessionStartHandler(calls);
+
+		// theme 存在但 fg 缺失/非函数 → duck typing 失败 → noop dispose。
+		const ctxBadFg = {
+			mode: "json",
+			cwd: "/tmp",
+			ui: { theme: { fg: "not-a-function" } },
+			signal: undefined,
+		};
+		expect(() => sessionHandler({}, ctxBadFg)).not.toThrow();
+		// 未注册 renderer → 不应触碰 globalThis 握手 slot
+		expect(Reflect.get(globalThis, FOOTER_HANDSHAKE_KEY)).toBeUndefined();
+	});
+
+	it("session_tree：触发两次 handler 不抛异常（dispose 旧 renderer → refreshConfig → 重注册）", () => {
+		writeConfig("yolo");
+		const { pi, calls } = createMockPi();
+		permissionExtension(pi);
+		const sessionTreeHandler = getSessionTreeHandler(calls);
+
+		// ctx.ui.theme 为合法 fg 函数 → 真实注册 renderer（写 globalThis slot）。
+		const ctxWithTheme = {
+			mode: "json",
+			cwd: "/tmp",
+			ui: {
+				theme: {
+					fg: (_token: string, text: string): string => text,
+				},
+			},
+			signal: undefined,
+		};
+
+		// 第一次：注册 renderer（无旧 renderer，dispose 是 noop）。
+		expect(() => sessionTreeHandler({}, ctxWithTheme)).not.toThrow();
+		expect(Reflect.get(globalThis, FOOTER_HANDSHAKE_KEY)).toBeDefined();
+
+		// 切换 config（模拟分支切换后 permission-config.json 变化）。
+		writeConfig("strict");
+
+		// 第二次：dispose 上次的 renderer → refreshConfig 读到 strict → 重新注册。
+		// disposeFooterLine 是闭包私有变量，这里间接验证：多次触发不抛、不破坏 slot 结构。
+		expect(() => sessionTreeHandler({}, ctxWithTheme)).not.toThrow();
+		// slot 仍存在且结构合规（version=1，pending 是数组）
+		const slot = Reflect.get(globalThis, FOOTER_HANDSHAKE_KEY) as {
+			version: number;
+			pending: unknown[];
+		};
+		expect(slot).toBeDefined();
+		expect(slot.version).toBe(1);
+		expect(Array.isArray(slot.pending)).toBe(true);
+		// 两次注册 + 一次 dispose（第二次触发前）→ pending 应至多 1 项（旧 renderer 已 dispose 移除）
+		expect(slot.pending.length).toBeLessThanOrEqual(1);
+	});
+
+	it("session_tree：ctx.ui 无 theme 时多次触发仍安全（noop dispose 重复调用）", () => {
+		writeConfig("yolo");
+		const { pi, calls } = createMockPi();
+		permissionExtension(pi);
+		const sessionTreeHandler = getSessionTreeHandler(calls);
+
+		// 无 theme → 两次都是 noop dispose，不应抛、不应写 globalThis。
+		const ctxNoTheme = { mode: "json", cwd: "/tmp", ui: {}, signal: undefined };
+		expect(() => sessionTreeHandler({}, ctxNoTheme)).not.toThrow();
+		expect(() => sessionTreeHandler({}, ctxNoTheme)).not.toThrow();
+		expect(Reflect.get(globalThis, FOOTER_HANDSHAKE_KEY)).toBeUndefined();
+	});
+});

package/src/__tests__/statusline-palette.test.ts

@@ -0,0 +1,88 @@
+/**
+ * statusline-palette.test.ts — paletteFromTheme 适配函数单测。
+ *
+ * paletteFromTheme 是纯适配函数：把 Pi Theme 的 theme.fg(token, text) 语义着色 API
+ * 包装为 PermissionPalette 的 5 个字符串着色器（dim/text/accent/success/warning）。
+ * 本测试记录 fg 调用参数，断言每个着色器转发正确的 token + 原始字符串，
+ * 避免后续重构拼错 token（如 "succes"）时静默丢失色彩。
+ */
+import { describe, expect, it, vi } from "vitest";
+
+import { paletteFromTheme } from "../statusline-palette.js";
+
+/** 构造 mock theme：fg 是 spy，记录 (token, text) 调用并原样返回 text。 */
+function makeMockTheme(): {
+	theme: { fg: (token: string, text: string) => string };
+	fg: ReturnType<typeof vi.fn>;
+} {
+	const fg = vi.fn((_token: string, text: string): string => text);
+	return { theme: { fg }, fg };
+}
+
+describe("paletteFromTheme", () => {
+	it("dim → theme.fg('dim', s)", () => {
+		const { theme, fg } = makeMockTheme();
+		const palette = paletteFromTheme(theme);
+		const result = palette.dim("muted text");
+		expect(result).toBe("muted text");
+		expect(fg).toHaveBeenCalledWith("dim", "muted text");
+	});
+
+	it("text → theme.fg('text', s)", () => {
+		const { theme, fg } = makeMockTheme();
+		const palette = paletteFromTheme(theme);
+		const result = palette.text("main body");
+		expect(result).toBe("main body");
+		expect(fg).toHaveBeenCalledWith("text", "main body");
+	});
+
+	it("accent → theme.fg('accent', s)", () => {
+		const { theme, fg } = makeMockTheme();
+		const palette = paletteFromTheme(theme);
+		const result = palette.accent("Auto");
+		expect(result).toBe("Auto");
+		expect(fg).toHaveBeenCalledWith("accent", "Auto");
+	});
+
+	it("success → theme.fg('success', s)", () => {
+		const { theme, fg } = makeMockTheme();
+		const palette = paletteFromTheme(theme);
+		const result = palette.success("enabled");
+		expect(result).toBe("enabled");
+		// 关键断言：token 必须是完整的 "success"（防止拼错成 "succes"）
+		expect(fg).toHaveBeenCalledWith("success", "enabled");
+	});
+
+	it("warning → theme.fg('warning', s)", () => {
+		const { theme, fg } = makeMockTheme();
+		const palette = paletteFromTheme(theme);
+		const result = palette.warning("disabled");
+		expect(result).toBe("disabled");
+		expect(fg).toHaveBeenCalledWith("warning", "disabled");
+	});
+
+	it("五个着色器各自转发正确的 token（全量校验，防 token 漂移）", () => {
+		const { theme, fg } = makeMockTheme();
+		const palette = paletteFromTheme(theme);
+		palette.dim("a");
+		palette.text("b");
+		palette.accent("c");
+		palette.success("d");
+		palette.warning("e");
+		expect(fg).toHaveBeenNthCalledWith(1, "dim", "a");
+		expect(fg).toHaveBeenNthCalledWith(2, "text", "b");
+		expect(fg).toHaveBeenNthCalledWith(3, "accent", "c");
+		expect(fg).toHaveBeenNthCalledWith(4, "success", "d");
+		expect(fg).toHaveBeenNthCalledWith(5, "warning", "e");
+		expect(fg).toHaveBeenCalledTimes(5);
+	});
+
+	it("返回值是 theme.fg 的返回值（透传，不做额外加工）", () => {
+		const theme = {
+			fg: (token: string, text: string): string => `<${token}>${text}</${token}>`,
+		};
+		const palette = paletteFromTheme(theme);
+		expect(palette.dim("x")).toBe("<dim>x</dim>");
+		expect(palette.success("y")).toBe("<success>y</success>");
+	});
+});