pi-lean-dimension 0.2.3 → 0.3.0

package/node_modules/pi-lean-portal/__tests__/browser-toggle.test.ts

@@ -1,47 +1,43 @@
 /**
- * Tests for browser-toggle.ts — the companion extension that provides
- * /web on | off | status commands for toggling browser automation tools.
+ * Integration tests for browser-toggle.ts — portal-specific concerns.
  *
- * Tests cover:
- * - Filtering logic (getRegisteredIn)
- * - State queries (isBrowserEnabled)
- * - State mutations (applyBrowserState, persistState)
- * - Branch-aware restoration (restoreFromBranch)
- * - Config-driven default (readBrowserToggleConfig, applyConfigDefault)
- * - Command registration and handler dispatch
+ * Invariant tests (peer composition, persist shape, restore) live in the
+ * pi-tool-masking library. These tests cover portal-specific wiring:
+ *   - /web command dispatch
+ *   - defaultProfile persistence under portal-conversation-state
+ *   - glyph render on session_start
+ *   - cached state (getToggleState / getLearnState) reflects library state
  */
 
 import { describe, it, expect, vi, beforeEach } from "vitest";
-import { existsSync, readFileSync } from "node:fs";
+import { EventEmitter } from "node:events";
 import type {
 	ExtensionAPI,
 	ExtensionContext,
 } from "@earendil-works/pi-coding-agent";
-import browserToggle, { getToggleState } from "../browser-toggle.js";
-import {
-	getRegisteredIn,
-	isBrowserEnabled,
-	applyBrowserState,
-	persistState,
-	restoreFromBranch,
+import { TOOLSET_EVENTS, setDefaultResolutionMode } from "pi-tool-masking";
+import browserToggle, {
+	getToggleState,
+	getLearnState,
+	getConversationDefaultProfile,
 	_resetToggleStateForTest,
-	readBrowserToggleConfig,
-	applyConfigDefault,
-	isLearnEnabled,
-	applyLearnState,
-	type BrowserToggleState,
 } from "../browser-toggle.js";
 
-// Mock node:fs so readBrowserToggleConfig and applyConfigDefault can be
-// tested without touching the real filesystem.
-vi.mock("node:fs", () => ({
-	existsSync: vi.fn(),
-	readFileSync: vi.fn(),
-}));
+// Clean globalThis registry between test files
+const REGISTRY_KEY = "__piToolMaskingRegistry";
+const RESTORE_EVENT_KEY = "__piToolMaskingLastRestoreEvent";
+const MODULE_STATE_KEY = "__piToolMaskingModuleState";
+
+beforeEach(() => {
+	_resetToggleStateForTest();
+	delete (globalThis as any)[REGISTRY_KEY];
+	delete (globalThis as any)[RESTORE_EVENT_KEY];
+	delete (globalThis as any)[MODULE_STATE_KEY];
+});
 
 // ─── Fixtures ────────────────────────────────────────────────────
 
-const ALL_BROWSER_TOOLS = [
+const ALL_TOOLS = [
 	{ name: "web-fetch", description: "fetch" },
 	{ name: "browser-navigate", description: "navigate" },
 	{ name: "browser-snapshot", description: "snapshot" },
@@ -53,1195 +49,360 @@ const ALL_BROWSER_TOOLS = [
 	{ name: "browser-console", description: "console" },
 	{ name: "browser-inspect", description: "inspect" },
 	{ name: "web-guide", description: "guide" },
-];
-
-const SOME_BROWSER_TOOLS = [
-	{ name: "web-fetch", description: "fetch" },
-	{ name: "browser-navigate", description: "navigate" },
-	{ name: "browser-console", description: "console" },
-];
-
-const NON_BROWSER_TOOLS = [
+	{ name: "web-learn", description: "learn" },
 	{ name: "read", description: "read files" },
 	{ name: "bash", description: "shell" },
 	{ name: "edit", description: "edit files" },
 	{ name: "write", description: "write files" },
-	{ name: "grep", description: "search" },
-	{ name: "find", description: "find files" },
-	{ name: "ls", description: "list files" },
 ];
 
-// ─── Mock builders ───────────────────────────────────────────────
-
-interface MockPiOptions {
-	tools?: Array<{ name: string; description?: string }>;
-	activeTools?: string[];
+const BROWSER_TOOL_NAMES = new Set(
+	ALL_TOOLS.filter(
+		(t) =>
+			t.name !== "web-learn" &&
+			t.name !== "read" &&
+			t.name !== "bash" &&
+			t.name !== "edit" &&
+			t.name !== "write",
+	).map((t) => t.name),
+);
+
+// ─── Mock builder ────────────────────────────────────────────────
+
+interface MockPi {
+	pi: ExtensionAPI;
+	events: EventEmitter;
+	handlers: Map<string, Array<(...args: any[]) => void>>;
+	entryCalls: Array<{ customType: string; data: unknown }>;
 }
 
-/**
- * Build a minimal ExtensionAPI mock for testing the helper functions.
- * Only implements the methods that the helpers actually call.
- */
-function mockPi(opts: MockPiOptions = {}): ExtensionAPI {
-	const allTools = opts.tools ?? [];
-	let active = opts.activeTools ?? allTools.map((t) => t.name);
+function mockPi(initialTools?: string[]): MockPi {
+	let active = initialTools ?? ALL_TOOLS.map((t) => t.name);
+	const eventEmitter = new EventEmitter();
+	const handlers = new Map<string, Array<(...args: any[]) => void>>();
+	const entryCalls: Array<{ customType: string; data: unknown }> = [];
 
-	return {
-		getAllTools: vi.fn(() => allTools as any),
-		getActiveTools: vi.fn(() => active),
+	const pi = {
+		getAllTools: vi.fn(() => ALL_TOOLS as any),
+		getActiveTools: vi.fn(() => [...active]),
 		setActiveTools: vi.fn((names: string[]) => {
-			active = names;
+			active = [...names];
+		}),
+		appendEntry: vi.fn((customType: string, data?: unknown) => {
+			entryCalls.push({ customType, data });
 		}),
-		appendEntry: vi.fn(),
 		registerCommand: vi.fn(),
-		on: vi.fn(),
+		registerTool: vi.fn(),
+		on: vi.fn(<T>(event: string, handler: (event: T, ctx: any) => void) => {
+			if (!handlers.has(event)) handlers.set(event, []);
+			handlers.get(event)!.push(handler as any);
+		}),
+		get events() {
+			return {
+				emit: (channel: string, data: unknown) =>
+					eventEmitter.emit(channel, data),
+				on: (channel: string, handler: (data: unknown) => void) => {
+					eventEmitter.on(channel, handler);
+					return () => eventEmitter.off(channel, handler);
+				},
+			};
+		},
 	} as unknown as ExtensionAPI;
+
+	return { pi, events: eventEmitter, handlers, entryCalls };
 }
 
-/**
- * Build a minimal ExtensionContext mock for restoreFromBranch tests.
- */
-function mockContext(
-	branchEntries: Array<{
-		type: string;
-		customType?: string;
-		data?: unknown;
-	}>,
-): ExtensionContext {
+function mockCtx(overrides: Partial<ExtensionContext> = {}): any {
 	return {
-		sessionManager: {
-			getBranch: vi.fn(() => branchEntries as any),
+		sessionManager: { getBranch: () => [] },
+		ui: {
+			setStatus: vi.fn(),
+			theme: { fg: (_c: string, t: string) => t },
+			notify: vi.fn(),
 		},
-		ui: { notify: vi.fn() },
-	} as unknown as ExtensionContext;
+		mode: "tui",
+		cwd: "/mock",
+		hasUI: true,
+		isIdle: () => true,
+		modelRegistry: {} as any,
+		...overrides,
+	};
 }
 
-// ==================================================================
-//  getRegisteredIn
-// ==================================================================
-describe("getRegisteredIn", () => {
-	const BROWSER_NAMES = new Set([
-		"web-fetch",
-		"browser-navigate",
-		"browser-snapshot",
-		"browser-click",
-		"browser-type",
-		"browser-scroll",
-		"browser-back",
-		"browser-press",
-		"browser-console",
-		"browser-inspect",
-		"web-guide",
-	]);
-
-	it("returns empty array when no tools are registered", () => {
-		const pi = mockPi({ tools: [] });
-		expect(getRegisteredIn(pi, BROWSER_NAMES)).toEqual([]);
-	});
-
-	it("returns empty array when only non-matching tools are registered", () => {
-		const pi = mockPi({ tools: NON_BROWSER_TOOLS });
-		expect(getRegisteredIn(pi, BROWSER_NAMES)).toEqual([]);
-	});
-
-	it("returns only matching tools when mixed with non-matching tools", () => {
-		const pi = mockPi({
-			tools: [...ALL_BROWSER_TOOLS, ...NON_BROWSER_TOOLS],
-		});
-		expect(getRegisteredIn(pi, BROWSER_NAMES)).toEqual(
-			ALL_BROWSER_TOOLS.map((t) => t.name),
-		);
-	});
-
-	it("returns all matching tools when all are present", () => {
-		const pi = mockPi({ tools: ALL_BROWSER_TOOLS });
-		expect(getRegisteredIn(pi, BROWSER_NAMES)).toEqual(
-			ALL_BROWSER_TOOLS.map((t) => t.name),
-		);
-	});
-
-	it("returns a subset when only some matching tools are registered", () => {
-		const pi = mockPi({ tools: SOME_BROWSER_TOOLS });
-		expect(getRegisteredIn(pi, BROWSER_NAMES)).toEqual(
-			SOME_BROWSER_TOOLS.map((t) => t.name),
-		);
-	});
-
-	it("is case-sensitive (tool names are always lowercase)", () => {
-		const pi = mockPi({
-			tools: [
-				{ name: "Web-Fetch" },
-				{ name: "BROWSER-NAVIGATE" },
-				{ name: "web-fetch" },
-			],
-		});
-		// Only the exact-lowercase match should be returned
-		expect(getRegisteredIn(pi, BROWSER_NAMES)).toEqual(["web-fetch"]);
-	});
-
-	it("ignores tool metadata beyond the name field", () => {
-		const tools = [
-			{ name: "web-fetch", description: "a", extra: 1 },
-			{ name: "browser-scroll", description: "b", promptGuidelines: [] },
-		];
-		const pi = mockPi({ tools: tools as any });
-		expect(getRegisteredIn(pi, BROWSER_NAMES)).toEqual([
-			"web-fetch",
-			"browser-scroll",
-		]);
-	});
-});
+/** Capture the /web command handler from registerCommand. */
+function captureWebHandler(
+	pi: ExtensionAPI,
+): (args: string, ctx: any) => Promise<void> {
+	return (pi.registerCommand as any).mock.calls[0][1].handler;
+}
 
 // ==================================================================
-//  isBrowserEnabled
+//  Default export
 // ==================================================================
-describe("isBrowserEnabled", () => {
-	it("returns true when all browser tools are active", () => {
-		const pi = mockPi({
-			tools: ALL_BROWSER_TOOLS,
-			activeTools: ALL_BROWSER_TOOLS.map((t) => t.name),
-		});
-		expect(isBrowserEnabled(pi)).toBe(true);
-	});
-
-	it("returns false when no browser tools are active", () => {
-		const pi = mockPi({
-			tools: ALL_BROWSER_TOOLS,
-			activeTools: NON_BROWSER_TOOLS.map((t) => t.name),
-		});
-		expect(isBrowserEnabled(pi)).toBe(false);
-	});
-
-	it("returns true when at least one browser tool is active (partial)", () => {
-		const pi = mockPi({
-			tools: ALL_BROWSER_TOOLS,
-			activeTools: ["read", "bash", "web-fetch", "browser-navigate"],
-		});
-		expect(isBrowserEnabled(pi)).toBe(true);
-	});
-
-	it("returns false when no browser tools exist", () => {
-		const pi = mockPi({
-			tools: NON_BROWSER_TOOLS,
-			activeTools: NON_BROWSER_TOOLS.map((t) => t.name),
-		});
-		expect(isBrowserEnabled(pi)).toBe(false);
+describe("initBrowserToggle", () => {
+	it("registers the /web command", () => {
+		const { pi } = mockPi();
+		browserToggle(pi);
+		expect(pi.registerCommand).toHaveBeenCalledWith(
+			"web",
+			expect.objectContaining({
+				description: expect.stringContaining("browser"),
+			}),
+		);
 	});
 
-	it("returns false when active set is empty and browser tools exist", () => {
-		const pi = mockPi({
-			tools: ALL_BROWSER_TOOLS,
-			activeTools: [],
-		});
-		expect(isBrowserEnabled(pi)).toBe(false);
+	it("registers session_start and session_tree handlers", () => {
+		const { pi, handlers } = mockPi();
+		browserToggle(pi);
+		expect(handlers.has("session_start")).toBe(true);
+		expect(handlers.has("session_tree")).toBe(true);
 	});
 });
 
 // ==================================================================
-//  applyBrowserState
+//  /web command dispatch
 // ==================================================================
-describe("applyBrowserState(true) — enable", () => {
-	it("adds browser tools to the active set", () => {
-		const pi = mockPi({
-			tools: [...ALL_BROWSER_TOOLS, ...NON_BROWSER_TOOLS],
-			activeTools: NON_BROWSER_TOOLS.map((t) => t.name),
-		});
-		applyBrowserState(pi, true);
-		const setActive = pi.setActiveTools as ReturnType<typeof vi.fn>;
-		const calledWith: string[] = setActive.mock.calls[0]![0] as string[];
-		expect(calledWith).toEqual(
-			expect.arrayContaining(ALL_BROWSER_TOOLS.map((t) => t.name)),
-		);
-	});
+describe("/web command dispatch", () => {
+	it("on — enables web tools, disables learn tools", async () => {
+		const { pi } = mockPi([]);
+		browserToggle(pi);
 
-	it("preserves non-browser tools when enabling", () => {
-		const pi = mockPi({
-			tools: [...ALL_BROWSER_TOOLS, ...NON_BROWSER_TOOLS],
-			activeTools: NON_BROWSER_TOOLS.map((t) => t.name),
-		});
-		applyBrowserState(pi, true);
-		const setActive = pi.setActiveTools as ReturnType<typeof vi.fn>;
-		const calledWith: string[] = setActive.mock.calls[0]![0] as string[];
-		for (const tool of NON_BROWSER_TOOLS.map((t) => t.name)) {
-			expect(calledWith).toContain(tool);
-		}
-	});
+		await captureWebHandler(pi)("on", mockCtx());
 
-	it("does not duplicate already-active browser tools", () => {
-		const pi = mockPi({
-			tools: [...ALL_BROWSER_TOOLS, ...NON_BROWSER_TOOLS],
-			activeTools: [
-				...NON_BROWSER_TOOLS.map((t) => t.name),
-				"web-fetch",
-				"browser-navigate",
-			],
-		});
-		applyBrowserState(pi, true);
-		const setActive = pi.setActiveTools as ReturnType<typeof vi.fn>;
-		const calledWith: string[] = setActive.mock.calls[0]![0] as string[];
-		// Each browser tool appears exactly once
-		for (const tool of ALL_BROWSER_TOOLS.map((t) => t.name)) {
-			expect(calledWith.filter((n) => n === tool)).toHaveLength(1);
+		const finalActive = pi.getActiveTools();
+		for (const name of BROWSER_TOOL_NAMES) {
+			expect(finalActive).toContain(name);
 		}
+		expect(finalActive).not.toContain("web-learn");
 	});
 
-	it("reports the union of current and browser tools (no duplicates)", () => {
-		const pi = mockPi({
-			tools: [...ALL_BROWSER_TOOLS, ...NON_BROWSER_TOOLS],
-			activeTools: NON_BROWSER_TOOLS.map((t) => t.name),
-		});
-		applyBrowserState(pi, true);
-		const setActive = pi.setActiveTools as ReturnType<typeof vi.fn>;
-		const calledWith: string[] = setActive.mock.calls[0]![0] as string[];
-		const expected = [
-			...NON_BROWSER_TOOLS.map((t) => t.name),
-			...ALL_BROWSER_TOOLS.map((t) => t.name),
-		];
-		expect(new Set(calledWith)).toEqual(new Set(expected));
-	});
+	it("off — disables web tools (learn cascades off via requires)", async () => {
+		const { pi } = mockPi();
+		browserToggle(pi);
 
-	it("is a no-op when no browser tools are registered", () => {
-		const pi = mockPi({
-			tools: NON_BROWSER_TOOLS,
-			activeTools: NON_BROWSER_TOOLS.map((t) => t.name),
-		});
-		applyBrowserState(pi, true);
-		expect(pi.setActiveTools).not.toHaveBeenCalled();
-	});
-});
+		await captureWebHandler(pi)("off", mockCtx());
 
-describe("applyBrowserState(false) — disable", () => {
-	it("removes browser tools from the active set", () => {
-		const pi = mockPi({
-			tools: [...ALL_BROWSER_TOOLS, ...NON_BROWSER_TOOLS],
-			activeTools: [
-				...NON_BROWSER_TOOLS.map((t) => t.name),
-				...ALL_BROWSER_TOOLS.map((t) => t.name),
-			],
-		});
-		applyBrowserState(pi, false);
-		const setActive = pi.setActiveTools as ReturnType<typeof vi.fn>;
-		const calledWith: string[] = setActive.mock.calls[0]![0] as string[];
-		for (const tool of ALL_BROWSER_TOOLS.map((t) => t.name)) {
-			expect(calledWith).not.toContain(tool);
+		const finalActive = pi.getActiveTools();
+		for (const name of BROWSER_TOOL_NAMES) {
+			expect(finalActive).not.toContain(name);
 		}
+		expect(finalActive).not.toContain("web-learn");
 	});
 
-	it("preserves non-browser tools when disabling", () => {
-		const pi = mockPi({
-			tools: [...ALL_BROWSER_TOOLS, ...NON_BROWSER_TOOLS],
-			activeTools: [
-				...NON_BROWSER_TOOLS.map((t) => t.name),
-				...ALL_BROWSER_TOOLS.map((t) => t.name),
-			],
-		});
-		applyBrowserState(pi, false);
-		const setActive = pi.setActiveTools as ReturnType<typeof vi.fn>;
-		const calledWith: string[] = setActive.mock.calls[0]![0] as string[];
-		for (const tool of NON_BROWSER_TOOLS.map((t) => t.name)) {
-			expect(calledWith).toContain(tool);
-		}
-	});
-
-	it("is a no-op when no browser tools are registered", () => {
-		const pi = mockPi({
-			tools: NON_BROWSER_TOOLS,
-			activeTools: NON_BROWSER_TOOLS.map((t) => t.name),
-		});
-		applyBrowserState(pi, false);
-		expect(pi.setActiveTools).not.toHaveBeenCalled();
-	});
+	it("learn — enables both web and learn tools", async () => {
+		const { pi } = mockPi([]);
+		browserToggle(pi);
 
-	it("is a no-op when no browser tools are active (removes nothing)", () => {
-		const pi = mockPi({
-			tools: [...ALL_BROWSER_TOOLS, ...NON_BROWSER_TOOLS],
-			activeTools: NON_BROWSER_TOOLS.map((t) => t.name),
-		});
-		applyBrowserState(pi, false);
-		const setActive = pi.setActiveTools as ReturnType<typeof vi.fn>;
-		const calledWith: string[] = setActive.mock.calls[0]![0] as string[];
-		expect(calledWith).toEqual(NON_BROWSER_TOOLS.map((t) => t.name));
-	});
+		await captureWebHandler(pi)("learn", mockCtx());
 
-	it("can be applied repeatedly without error", () => {
-		const pi = mockPi({
-			tools: [...ALL_BROWSER_TOOLS, ...NON_BROWSER_TOOLS],
-			activeTools: [
-				...NON_BROWSER_TOOLS.map((t) => t.name),
-				...ALL_BROWSER_TOOLS.map((t) => t.name),
-			],
-		});
-		applyBrowserState(pi, false);
-		applyBrowserState(pi, false);
-		expect(pi.setActiveTools).toHaveBeenCalledTimes(2);
-		// Second call should also produce a clean set (no browser tools)
-		const calledWith: string[] = (pi.setActiveTools as ReturnType<typeof vi.fn>)
-			.mock.calls[1]![0] as string[];
-		for (const tool of ALL_BROWSER_TOOLS.map((t) => t.name)) {
-			expect(calledWith).not.toContain(tool);
+		const finalActive = pi.getActiveTools();
+		for (const name of BROWSER_TOOL_NAMES) {
+			expect(finalActive).toContain(name);
 		}
-	});
-});
-
-// ==================================================================
-//  persistState
-// ==================================================================
-describe("persistState", () => {
-	it("calls appendEntry with customType 'web-toggle-state'", () => {
-		const pi = mockPi();
-		persistState(pi, {
-			browserToolsEnabled: true,
-			learnToolsEnabled: false,
-			defaultProfile: "none",
-		});
-		expect(pi.appendEntry).toHaveBeenCalledWith(
-			"web-toggle-state",
-			expect.any(Object),
-		);
+		expect(finalActive).toContain("web-learn");
 	});
 
-	it("stores browserToolsEnabled: true and learnToolsEnabled: false on /web on", () => {
-		const pi = mockPi();
-		persistState(pi, {
-			browserToolsEnabled: true,
-			learnToolsEnabled: false,
-			defaultProfile: "none",
-		});
-		expect(pi.appendEntry).toHaveBeenCalledWith("web-toggle-state", {
-			browserToolsEnabled: true,
-			learnToolsEnabled: false,
-			defaultProfile: "none",
-		});
-	});
-
-	it("stores browserToolsEnabled: false and learnToolsEnabled: false on /web off", () => {
-		const pi = mockPi();
-		persistState(pi, {
-			browserToolsEnabled: false,
-			learnToolsEnabled: false,
-			defaultProfile: "none",
-		});
-		expect(pi.appendEntry).toHaveBeenCalledWith("web-toggle-state", {
-			browserToolsEnabled: false,
-			learnToolsEnabled: false,
-			defaultProfile: "none",
-		});
-	});
-
-	it("stores browserToolsEnabled: true and learnToolsEnabled: true on /web learn", () => {
-		const pi = mockPi();
-		persistState(pi, {
-			browserToolsEnabled: true,
-			learnToolsEnabled: true,
-			defaultProfile: "none",
-		});
-		expect(pi.appendEntry).toHaveBeenCalledWith("web-toggle-state", {
-			browserToolsEnabled: true,
-			learnToolsEnabled: true,
-			defaultProfile: "none",
-		});
-	});
-});
-
-// ==================================================================
-//  getToggleState
-// ==================================================================
-describe("getToggleState", () => {
-	beforeEach(() => {
-		_resetToggleStateForTest();
-	});
-
-	it("returns true by default (browser tools start enabled)", () => {
-		expect(getToggleState()).toBe(true);
-	});
-
-	it("returns false after disabling via applyBrowserState", () => {
-		const pi = mockPi({
-			tools: ALL_BROWSER_TOOLS,
-			activeTools: ALL_BROWSER_TOOLS.map((t) => t.name),
-		});
-		applyBrowserState(pi, false);
-		expect(getToggleState()).toBe(false);
-	});
-
-	it("returns true after re-enabling via applyBrowserState", () => {
-		const pi = mockPi({
-			tools: ALL_BROWSER_TOOLS,
-			activeTools: NON_BROWSER_TOOLS.map((t) => t.name),
-		});
-		applyBrowserState(pi, true);
-		expect(getToggleState()).toBe(true);
-	});
-
-	it("is not affected by persistState", () => {
-		persistState(mockPi(), {
-			browserToolsEnabled: true,
-			learnToolsEnabled: false,
-			defaultProfile: "none",
-		});
-		// persistState doesn't call applyBrowserState, so state is unchanged
-		expect(getToggleState()).toBe(true);
-	});
-
-	it("returns true when browserToolsEnabled is true (regardless of learn state)", () => {
-		const pi = mockPi({
-			tools: ALL_BROWSER_TOOLS,
-			activeTools: ALL_BROWSER_TOOLS.map((t) => t.name),
-		});
-		// getToggleState returns browserToolsEnabled only (status bar compat)
-		applyBrowserState(pi, true);
-		applyLearnState(pi, true);
-		expect(getToggleState()).toBe(true);
-	});
+	it("handles unknown arg — shows status, no state change", async () => {
+		const { pi } = mockPi([]);
+		browserToggle(pi);
 
-	it("reflects the most recent call to applyBrowserState", () => {
-		const pi = mockPi({
-			tools: ALL_BROWSER_TOOLS,
-			activeTools: ALL_BROWSER_TOOLS.map((t) => t.name),
-		});
-		applyBrowserState(pi, false);
-		expect(getToggleState()).toBe(false);
-		applyBrowserState(pi, true);
-		expect(getToggleState()).toBe(true);
-		applyBrowserState(pi, false);
-		expect(getToggleState()).toBe(false);
-	});
-});
+		(pi.setActiveTools as any).mockClear();
+		await captureWebHandler(pi)("xyz", mockCtx());
 
-// ==================================================================
-//  restoreFromBranch
-// ==================================================================
-describe("restoreFromBranch", () => {
-	it("does nothing when the branch has no saved state", () => {
-		const pi = mockPi({
-			tools: ALL_BROWSER_TOOLS,
-			activeTools: ALL_BROWSER_TOOLS.map((t) => t.name),
-		});
-		const ctx = mockContext([
-			{ type: "message", data: { role: "user" } },
-			{ type: "message", data: { role: "assistant" } },
-		]);
-		vi.spyOn(pi, "setActiveTools");
-		restoreFromBranch(pi, ctx);
 		expect(pi.setActiveTools).not.toHaveBeenCalled();
 	});
 
-	it("applies saved browserToolsEnabled=true learnToolsEnabled=false state ", () => {
-		const allNames = ALL_BROWSER_TOOLS.map((t) => t.name);
-		const pi = mockPi({
-			tools: [...ALL_BROWSER_TOOLS, ...NON_BROWSER_TOOLS],
-			activeTools: NON_BROWSER_TOOLS.map((t) => t.name), // browsers off
-		});
-		const ctx = mockContext([
-			{
-				type: "custom",
-				customType: "web-toggle-state",
-				data: {
-					browserToolsEnabled: true,
-					learnToolsEnabled: false,
-					defaultProfile: "none",
-				} satisfies BrowserToggleState,
-			},
-		]);
-		restoreFromBranch(pi, ctx);
-		const setActive = pi.setActiveTools as ReturnType<typeof vi.fn>;
-		expect(setActive).toHaveBeenCalledWith(expect.arrayContaining(allNames));
-	});
-
-	it("applies saved browserToolsEnabled=false learnToolsEnabled=false state", () => {
-		const pi = mockPi({
-			tools: [...ALL_BROWSER_TOOLS, ...NON_BROWSER_TOOLS],
-			activeTools: [
-				...NON_BROWSER_TOOLS.map((t) => t.name),
-				...ALL_BROWSER_TOOLS.map((t) => t.name),
-			],
-		});
-		const ctx = mockContext([
-			{
-				type: "custom",
-				customType: "web-toggle-state",
-				data: {
-					browserToolsEnabled: false,
-					learnToolsEnabled: false,
-					defaultProfile: "none",
-				} satisfies BrowserToggleState,
-			},
-		]);
-		restoreFromBranch(pi, ctx);
-		const setActive = pi.setActiveTools as ReturnType<typeof vi.fn>;
-		const calledWith: string[] = setActive.mock.calls[0]![0] as string[];
-		for (const tool of ALL_BROWSER_TOOLS.map((t) => t.name)) {
-			expect(calledWith).not.toContain(tool);
-		}
-	});
+	it("handles empty args — shows status, no state change", async () => {
+		const { pi } = mockPi([]);
+		browserToggle(pi);
 
-	it("picks the last saved state when multiple toggles exist in branch", () => {
-		const allNames = ALL_BROWSER_TOOLS.map((t) => t.name);
-		const pi = mockPi({
-			tools: [...ALL_BROWSER_TOOLS, ...NON_BROWSER_TOOLS],
-			activeTools: NON_BROWSER_TOOLS.map((t) => t.name),
-		});
-		const ctx = mockContext([
-			{
-				type: "custom",
-				customType: "web-toggle-state",
-				data: { browserToolsEnabled: true, learnToolsEnabled: false },
-			},
-			{
-				type: "custom",
-				customType: "web-toggle-state",
-				data: { browserToolsEnabled: false, learnToolsEnabled: false },
-			},
-			{
-				type: "custom",
-				customType: "web-toggle-state",
-				data: { browserToolsEnabled: true, learnToolsEnabled: true },
-			},
-		]);
-		restoreFromBranch(pi, ctx);
-		const setActive = pi.setActiveTools as ReturnType<typeof vi.fn>;
-		expect(setActive).toHaveBeenCalledWith(expect.arrayContaining(allNames));
-	});
+		(pi.setActiveTools as any).mockClear();
+		await captureWebHandler(pi)("", mockCtx());
 
-	it("does nothing when no browser tools are registered", () => {
-		const pi = mockPi({ tools: NON_BROWSER_TOOLS });
-		const ctx = mockContext([
-			{
-				type: "custom",
-				customType: "web-toggle-state",
-				data: { enabled: false },
-			},
-		]);
-		vi.spyOn(pi, "setActiveTools");
-		restoreFromBranch(pi, ctx);
-		expect(pi.setActiveTools).not.toHaveBeenCalled();
-	});
-
-	it("gracefully handles stale state (tool no longer registered)", () => {
-		const pi = mockPi({
-			tools: NON_BROWSER_TOOLS, // only web-fetch removed from all tools
-			activeTools: [...NON_BROWSER_TOOLS.map((t) => t.name), "web-fetch"],
-		});
-		const ctx = mockContext([
-			{
-				type: "custom",
-				customType: "web-toggle-state",
-				data: {
-					browserToolsEnabled: false,
-					learnToolsEnabled: false,
-					defaultProfile: "none",
-				} satisfies BrowserToggleState,
-			},
-		]);
-		// Should not throw — with no browser tools currently registered,
-		// restoreFromBranch returns early (no-op).
-		expect(() => restoreFromBranch(pi, ctx)).not.toThrow();
 		expect(pi.setActiveTools).not.toHaveBeenCalled();
 	});
 });
 
 // ==================================================================
-//  Default export — factory & command handler
+//  getToggleState / getLearnState
 // ==================================================================
-describe("default export (extension factory)", () => {
-	it("registers the '/web' command", () => {
-		const pi = mockPi({
-			tools: [...ALL_BROWSER_TOOLS, ...NON_BROWSER_TOOLS],
-			activeTools: ALL_BROWSER_TOOLS.map((t) => t.name),
-		});
-		browserToggle(pi);
-		expect(pi.registerCommand).toHaveBeenCalledWith(
-			"web",
-			expect.objectContaining({
-				description: expect.stringContaining("browser"),
-			}),
-		);
-	});
-
-	it("registers session_start handler", () => {
-		const pi = mockPi();
-		browserToggle(pi);
-		expect(pi.on).toHaveBeenCalledWith("session_start", expect.any(Function));
-	});
-
-	it("registers session_tree handler", () => {
-		const pi = mockPi();
-		browserToggle(pi);
-		expect(pi.on).toHaveBeenCalledWith("session_tree", expect.any(Function));
-	});
-});
-
-describe("command handler dispatch (via factory closure)", () => {
-	it("handles 'on' when browsers are off — updates state", () => {
-		const pi = mockPi({
-			tools: [...ALL_BROWSER_TOOLS, ...NON_BROWSER_TOOLS],
-			activeTools: NON_BROWSER_TOOLS.map((t) => t.name), // browsers off
-		});
-		pi.registerCommand = vi.fn((_name, opts) => {
-			opts.handler("on", {
-				ui: {
-					notify: vi.fn(),
-					setStatus: vi.fn(),
-					theme: { fg: vi.fn((_c: string, t: string) => t) },
-				},
-			} as any);
-		}) as any;
-		pi.setActiveTools = vi.fn();
-
-		browserToggle(pi);
-		expect(pi.setActiveTools).toHaveBeenCalled();
-	});
-
-	it("handles 'on' — does not short-circuit (no early return)", () => {
-		// In the new three-state version, 'on' always calls applyBrowserState/applyLearnState
-		const pi = mockPi({
-			tools: [...ALL_BROWSER_TOOLS, ...NON_BROWSER_TOOLS],
-			activeTools: [
-				...NON_BROWSER_TOOLS.map((t) => t.name),
-				...ALL_BROWSER_TOOLS.map((t) => t.name),
-			],
-		});
-		pi.setActiveTools = vi.fn();
-		pi.registerCommand = vi.fn((_name, opts) => {
-			opts.handler("on", {
-				ui: {
-					notify: vi.fn(),
-					setStatus: vi.fn(),
-					theme: { fg: vi.fn((_c: string, t: string) => t) },
-				},
-			} as any);
-		}) as any;
-
-		browserToggle(pi);
-		// In the new three-state version, /web on always applies (no short-circuit)
-		expect(pi.setActiveTools).toHaveBeenCalled();
-	});
-
-	it("handles 'off' when browsers are on — updates state", () => {
-		const nonBrowserNames = NON_BROWSER_TOOLS.map((t) => t.name);
-		const allNames = ALL_BROWSER_TOOLS.map((t) => t.name);
-		const pi = mockPi({
-			tools: [...ALL_BROWSER_TOOLS, ...NON_BROWSER_TOOLS],
-			activeTools: [...nonBrowserNames, ...allNames],
-		});
-		pi.setActiveTools = vi.fn();
-		pi.registerCommand = vi.fn((_name, opts) => {
-			opts.handler("off", {
-				ui: {
-					notify: vi.fn(),
-					setStatus: vi.fn(),
-					theme: { fg: vi.fn((_c: string, t: string) => t) },
-				},
-			} as any);
-		}) as any;
-
-		browserToggle(pi);
-		expect(pi.setActiveTools).toHaveBeenCalled();
+describe("getToggleState / getLearnState", () => {
+	it("start true/false by default", () => {
+		expect(getToggleState()).toBe(true);
+		expect(getLearnState()).toBe(false);
 	});
 
-	it("handles 'off' when already disabled — still updates state", () => {
-		// In the new three-state version, 'off' always applies (no early return)
-		const pi = mockPi({
-			tools: [...ALL_BROWSER_TOOLS, ...NON_BROWSER_TOOLS],
-			activeTools: NON_BROWSER_TOOLS.map((t) => t.name),
-		});
-		pi.setActiveTools = vi.fn();
-		pi.registerCommand = vi.fn((_name, opts) => {
-			opts.handler("off", {
-				ui: {
-					notify: vi.fn(),
-					setStatus: vi.fn(),
-					theme: { fg: vi.fn((_c: string, t: string) => t) },
-				},
-			} as any);
-		}) as any;
-
+	it("update after /web on and /web off", async () => {
+		const { pi } = mockPi();
 		browserToggle(pi);
-		expect(pi.setActiveTools).toHaveBeenCalled();
-	});
 
-	it("handles 'learn' — enables both browser and learn tools", () => {
-		const pi = mockPi({
-			tools: [...ALL_BROWSER_TOOLS, ...NON_BROWSER_TOOLS],
-			activeTools: NON_BROWSER_TOOLS.map((t) => t.name),
-		});
-		pi.setActiveTools = vi.fn();
-		pi.registerCommand = vi.fn((_name, opts) => {
-			opts.handler("learn", {
-				ui: {
-					notify: vi.fn(),
-					setStatus: vi.fn(),
-					theme: { fg: vi.fn((_c: string, t: string) => t) },
-				},
-			} as any);
-		}) as any;
+		const handler = captureWebHandler(pi);
+		await handler("off", mockCtx());
+		expect(getToggleState()).toBe(false);
 
-		browserToggle(pi);
-		expect(pi.setActiveTools).toHaveBeenCalled();
+		await handler("on", mockCtx());
+		expect(getToggleState()).toBe(true);
 	});
 
-	it("handles unknown arg (e.g. 'xyz') — shows status, no state change", () => {
-		const pi = mockPi({
-			tools: [...ALL_BROWSER_TOOLS, ...NON_BROWSER_TOOLS],
-			activeTools: NON_BROWSER_TOOLS.map((t) => t.name),
-		});
-		pi.setActiveTools = vi.fn();
-		pi.registerCommand = vi.fn((_name, opts) => {
-			opts.handler("xyz", {
-				ui: {
-					notify: vi.fn(),
-					setStatus: vi.fn(),
-					theme: { fg: vi.fn((_c: string, t: string) => t) },
-				},
-			} as any);
-		}) as any;
-
+	it("getLearnState true after /web learn", async () => {
+		const { pi } = mockPi([]);
 		browserToggle(pi);
-		expect(pi.setActiveTools).not.toHaveBeenCalled();
-	});
-
-	it("handles missing pi-lean-portal — does not throw", () => {
-		const pi = mockPi({ tools: NON_BROWSER_TOOLS });
-		pi.registerCommand = vi.fn((_name, opts) => {
-			opts.handler("on", {
-				ui: {
-					notify: vi.fn(),
-					setStatus: vi.fn(),
-					theme: { fg: vi.fn((_c: string, t: string) => t) },
-				},
-			} as any);
-		}) as any;
-		// Should not throw even though no browser tools exist
-		expect(() => browserToggle(pi)).not.toThrow();
-	});
 
-	it("handles empty args string — shows status, no state change", () => {
-		const pi = mockPi({
-			tools: [...ALL_BROWSER_TOOLS, ...NON_BROWSER_TOOLS],
-			activeTools: NON_BROWSER_TOOLS.map((t) => t.name),
-		});
-		pi.setActiveTools = vi.fn();
-		pi.registerCommand = vi.fn((_name, opts) => {
-			opts.handler("", {
-				ui: {
-					notify: vi.fn(),
-					setStatus: vi.fn(),
-					theme: { fg: vi.fn((_c: string, t: string) => t) },
-				},
-			} as any);
-		}) as any;
+		await captureWebHandler(pi)("learn", mockCtx());
 
-		browserToggle(pi);
-		expect(pi.setActiveTools).not.toHaveBeenCalled();
+		expect(getToggleState()).toBe(true);
+		expect(getLearnState()).toBe(true);
 	});
 });
 
 // ==================================================================
-//  getRegisteredIn (learn) / isLearnEnabled / applyLearnState
+//  appendEntry persist keys
 // ==================================================================
-describe("getRegisteredIn with learn tool names", () => {
-	const LEARN_NAMES = new Set(["web-learn"]);
-
-	it("returns empty array when no learn tools registered", () => {
-		const pi = mockPi({ tools: ALL_BROWSER_TOOLS });
-		expect(getRegisteredIn(pi, LEARN_NAMES)).toEqual([]);
-	});
-
-	it("returns web-learn when it's in the tool list", () => {
-		const tools = [
-			...ALL_BROWSER_TOOLS,
-			{ name: "web-learn", description: "learn" },
-		];
-		const pi = mockPi({ tools });
-		expect(getRegisteredIn(pi, LEARN_NAMES)).toEqual(["web-learn"]);
-	});
-
-	it("is case-sensitive (tool names are always lowercase)", () => {
-		const tools = [
-			...ALL_BROWSER_TOOLS,
-			{ name: "Web-Learn" },
-			{ name: "web-learn" },
-		];
-		const pi = mockPi({ tools });
-		expect(getRegisteredIn(pi, LEARN_NAMES)).toEqual(["web-learn"]);
-	});
-});
+describe("persistence key split", () => {
+	it("appends toolset-state:portal.web on enable", async () => {
+		const { pi } = mockPi([]);
+		browserToggle(pi);
 
-describe("isLearnEnabled", () => {
-	it("returns true when web-learn is active", () => {
-		const tools = [
-			...ALL_BROWSER_TOOLS,
-			{ name: "web-learn", description: "learn" },
-		];
-		const pi = mockPi({
-			tools,
-			activeTools: [...ALL_BROWSER_TOOLS.map((t) => t.name), "web-learn"],
-		});
-		expect(isLearnEnabled(pi)).toBe(true);
-	});
+		await captureWebHandler(pi)("on", mockCtx());
 
-	it("returns false when web-learn is not active", () => {
-		const tools = [
-			...ALL_BROWSER_TOOLS,
-			{ name: "web-learn", description: "learn" },
-		];
-		const pi = mockPi({
-			tools,
-			activeTools: ALL_BROWSER_TOOLS.map((t) => t.name),
-		});
-		expect(isLearnEnabled(pi)).toBe(false);
+		const webCalls = (pi.appendEntry as any).mock.calls.filter(
+			(c: any) => c[0] === "toolset-state:portal.web",
+		);
+		expect(webCalls.length).toBeGreaterThanOrEqual(1);
 	});
 
-	it("returns false when no learn tools exist", () => {
-		const pi = mockPi({ tools: ALL_BROWSER_TOOLS });
-		expect(isLearnEnabled(pi)).toBe(false);
-	});
-});
+	it("appends toolset-state:portal.learn on learn", async () => {
+		const { pi } = mockPi([]);
+		browserToggle(pi);
 
-describe("applyLearnState", () => {
-	it("enable adds web-learn to active set", () => {
-		const tools = [
-			...ALL_BROWSER_TOOLS,
-			{ name: "web-learn", description: "learn" },
-		];
-		const pi = mockPi({
-			tools,
-			activeTools: ALL_BROWSER_TOOLS.map((t) => t.name),
-		});
-		applyLearnState(pi, true);
-		const setActive = pi.setActiveTools as ReturnType<typeof vi.fn>;
-		const calledWith: string[] = setActive.mock.calls[0]![0] as string[];
-		expect(calledWith).toContain("web-learn");
-	});
+		await captureWebHandler(pi)("learn", mockCtx());
 
-	it("disable removes web-learn from active set", () => {
-		const tools = [
-			...ALL_BROWSER_TOOLS,
-			{ name: "web-learn", description: "learn" },
-		];
-		const allNames = [...ALL_BROWSER_TOOLS.map((t) => t.name), "web-learn"];
-		const pi = mockPi({
-			tools,
-			activeTools: allNames,
-		});
-		applyLearnState(pi, false);
-		const setActive = pi.setActiveTools as ReturnType<typeof vi.fn>;
-		const calledWith: string[] = setActive.mock.calls[0]![0] as string[];
-		expect(calledWith).not.toContain("web-learn");
-	});
-
-	it("is a no-op when no learn tools are registered", () => {
-		const pi = mockPi({ tools: ALL_BROWSER_TOOLS });
-		applyLearnState(pi, true);
-		expect(pi.setActiveTools).not.toHaveBeenCalled();
+		const learnCalls = (pi.appendEntry as any).mock.calls.filter(
+			(c: any) => c[0] === "toolset-state:portal.learn",
+		);
+		expect(learnCalls.length).toBeGreaterThanOrEqual(1);
 	});
 });
 
 // ==================================================================
-//  getRegisteredIn (sibling)
+//  session_start — renders glyph
 // ==================================================================
-describe("getRegisteredIn with sibling tool names", () => {
-	const SIBLING_NAMES = new Set(["web-search"]);
+describe("session_start integration", () => {
+	it("renders browser glyph on session_start", async () => {
+		const { pi, handlers } = mockPi();
+		browserToggle(pi);
 
-	it("returns web-search when it's in the tool list", () => {
-		const tools = [
-			...ALL_BROWSER_TOOLS,
-			{ name: "web-search", description: "SearXNG search" },
-		];
-		const pi = mockPi({ tools });
-		expect(getRegisteredIn(pi, SIBLING_NAMES)).toEqual(["web-search"]);
-	});
+		const startHandlers = handlers.get("session_start")!;
+		const eventObj = {};
+		const ctx = mockCtx();
 
-	it("uses exact-name Set.has() membership — no regex false positives", () => {
-		const tools = [
-			...ALL_BROWSER_TOOLS,
-			{ name: "web-search-news", description: "news" },
-			{ name: "web-search-images", description: "images" },
-		];
-		const pi = mockPi({ tools });
-		expect(getRegisteredIn(pi, SIBLING_NAMES)).toEqual([]);
-	});
+		for (const h of startHandlers) {
+			await h(eventObj, ctx);
+		}
 
-	it("is case-sensitive — only exact lower-case matches", () => {
-		const tools = [
-			...ALL_BROWSER_TOOLS,
-			{ name: "Web-Search" },
-			{ name: "web-search" },
-		];
-		const pi = mockPi({ tools });
-		expect(getRegisteredIn(pi, SIBLING_NAMES)).toEqual(["web-search"]);
+		expect(ctx.ui.setStatus).toHaveBeenCalledWith(
+			"browser",
+			expect.any(String),
+		);
 	});
 });
 
 // ==================================================================
-//  applyConfigDefault — learn state
+//  conversation-default-profile
 // ==================================================================
-describe("applyConfigDefault (learn state)", () => {
-	beforeEach(() => {
-		vi.clearAllMocks();
-	});
-
-	it("learn state starts disabled", () => {
-		// applyConfigDefault should set learnToolsEnabled to false
-		const tools = [
-			...ALL_BROWSER_TOOLS,
-			{ name: "web-learn", description: "learn" },
-		];
-		const pi = mockPi({
-			tools,
-			activeTools: [...ALL_BROWSER_TOOLS.map((t) => t.name), "web-learn"],
-		});
-		vi.mocked(existsSync).mockReturnValue(true);
-		vi.mocked(readFileSync).mockReturnValue(
-			JSON.stringify({ browserToggle: { defaultEnabled: true } }),
-		);
-		applyConfigDefault(pi);
-
-		// applyConfigDefault calls setActiveTools twice:
-		// 1. applyBrowserState(true) — adds browser tools
-		// 2. applyLearnState(false) — removes web-learn
-		// Check the *last* call's result (not the first)
-		const setActive = pi.setActiveTools as ReturnType<typeof vi.fn>;
-		const lastCall = setActive.mock.calls[setActive.mock.calls.length - 1]!;
-		const calledWith: string[] = lastCall[0] as string[];
-		expect(calledWith).not.toContain("web-learn");
-	});
-
-	it("persists learnToolsEnabled: false", () => {
-		const pi = mockPi({ tools: ALL_BROWSER_TOOLS });
-		vi.mocked(existsSync).mockReturnValue(true);
-		vi.mocked(readFileSync).mockReturnValue(
-			JSON.stringify({ browserToggle: { defaultEnabled: true } }),
-		);
-		applyConfigDefault(pi);
-
-		expect(pi.appendEntry).toHaveBeenCalledWith(
-			"web-toggle-state",
-			expect.objectContaining({ learnToolsEnabled: false }),
-		);
+describe("getConversationDefaultProfile", () => {
+	it("returns undefined initially", () => {
+		expect(getConversationDefaultProfile()).toBeUndefined();
 	});
 });
 
 // ==================================================================
-//  readBrowserToggleConfig
+//  Focus-mode guard (Fix 3) — /web on/off/learn refuse during inclusion
 // ==================================================================
-describe("readBrowserToggleConfig", () => {
-	beforeEach(() => {
-		vi.clearAllMocks();
-	});
-
-	it("returns true when neither settings file exists (default)", () => {
-		vi.mocked(existsSync).mockReturnValue(false);
-		expect(readBrowserToggleConfig()).toBe(true);
-	});
-
-	it("returns true when settings files exist but have no browserToggle key", () => {
-		vi.mocked(existsSync).mockReturnValue(true);
-		vi.mocked(readFileSync).mockReturnValue(JSON.stringify({ theme: "dark" }));
-		expect(readBrowserToggleConfig()).toBe(true);
+describe("/web focus-mode guard", () => {
+	it("refuses /web on/off/learn while inclusion focus is active", async () => {
+		const { pi } = mockPi([]);
+		browserToggle(pi);
+		setDefaultResolutionMode(pi, "inclusion");
+
+		for (const sub of ["on", "off", "learn"]) {
+			(pi.setActiveTools as any).mockClear();
+			const ctx = mockCtx();
+			await captureWebHandler(pi)(sub, ctx);
+
+			expect(ctx.ui.notify).toHaveBeenCalledWith(
+				expect.stringContaining("Another plugin has active inclusion mode"),
+				"warning",
+			);
+			expect(pi.setActiveTools).not.toHaveBeenCalled();
+		}
 	});
 
-	it("returns false when browserToggle.defaultEnabled is false (global)", () => {
-		vi.mocked(existsSync).mockImplementation(
-			(path) => typeof path === "string" && path.includes("settings.json"),
-		);
-		vi.mocked(readFileSync).mockImplementation((path: unknown) =>
-			typeof path === "string" && path.includes(".pi/agent/settings")
-				? JSON.stringify({ browserToggle: { defaultEnabled: false } })
-				: JSON.stringify({ theme: "light" }),
-		);
-		expect(readBrowserToggleConfig()).toBe(false);
-	});
+	it("read-only subcommands unaffected by inclusion focus", async () => {
+		const { pi } = mockPi([]);
+		browserToggle(pi);
+		setDefaultResolutionMode(pi, "inclusion");
 
-	it("returns true when browserToggle.defaultEnabled is true (global)", () => {
-		vi.mocked(existsSync).mockReturnValue(true);
-		vi.mocked(readFileSync).mockImplementation((path: unknown) =>
-			typeof path === "string" && path.includes(".pi/agent/settings")
-				? JSON.stringify({ browserToggle: { defaultEnabled: true } })
-				: JSON.stringify({}),
-		);
-		expect(readBrowserToggleConfig()).toBe(true);
-	});
+		for (const sub of ["status", "profile", "cookies", ""]) {
+			const ctx = mockCtx();
+			await captureWebHandler(pi)(sub, ctx);
 
-	it("project settings override global settings", () => {
-		vi.mocked(existsSync).mockReturnValue(true);
-		vi.mocked(readFileSync).mockImplementation((path: unknown) =>
-			typeof path === "string" && path.includes(".pi/agent/settings")
-				? JSON.stringify({ browserToggle: { defaultEnabled: true } })
-				: JSON.stringify({ browserToggle: { defaultEnabled: false } }),
-		);
-		expect(readBrowserToggleConfig()).toBe(false);
+			expect(ctx.ui.notify).not.toHaveBeenCalledWith(
+				expect.stringContaining("Another plugin has active inclusion mode"),
+				"warning",
+			);
+		}
 	});
 
-	it("returns true on malformed JSON", () => {
-		vi.mocked(existsSync).mockReturnValue(true);
-		vi.mocked(readFileSync).mockReturnValue("not valid json");
-		expect(readBrowserToggleConfig()).toBe(true);
-	});
+	it("actuating subcommands work when focus is off (exclusion)", async () => {
+		const { pi } = mockPi([]);
+		browserToggle(pi);
+		// default mode is exclusion after beforeEach reset
 
-	it("returns true when browserToggle.defaultEnabled is not a boolean", () => {
-		vi.mocked(existsSync).mockReturnValue(true);
-		vi.mocked(readFileSync).mockImplementation((path: unknown) =>
-			typeof path === "string" && path.includes(".pi/agent/settings")
-				? JSON.stringify({ browserToggle: { defaultEnabled: "yes" } })
-				: JSON.stringify({}),
-		);
-		expect(readBrowserToggleConfig()).toBe(true);
-	});
+		const ctx = mockCtx();
+		await captureWebHandler(pi)("on", ctx);
 
-	it("returns true when browserToggle is not an object", () => {
-		vi.mocked(existsSync).mockReturnValue(true);
-		vi.mocked(readFileSync).mockImplementation((path: unknown) =>
-			typeof path === "string" && path.includes(".pi/agent/settings")
-				? JSON.stringify({ browserToggle: "on" })
-				: JSON.stringify({}),
+		expect(ctx.ui.notify).not.toHaveBeenCalledWith(
+			expect.stringContaining("Another plugin has active inclusion mode"),
+			"warning",
 		);
-		expect(readBrowserToggleConfig()).toBe(true);
-	});
-
-	it("returns true when settings file content is not an object", () => {
-		vi.mocked(existsSync).mockReturnValue(true);
-		vi.mocked(readFileSync).mockReturnValue("[]");
-		expect(readBrowserToggleConfig()).toBe(true);
+		const finalActive = pi.getActiveTools();
+		for (const name of BROWSER_TOOL_NAMES) {
+			expect(finalActive).toContain(name);
+		}
 	});
 });
 
 // ==================================================================
-//  applyConfigDefault
+//  Glyph sync on external-plugin changed events
 // ==================================================================
-describe("applyConfigDefault", () => {
-	beforeEach(() => {
-		vi.clearAllMocks();
-	});
-
-	it("calls applyBrowserState with the config value (true)", () => {
-		// Config says enabled
-		vi.mocked(existsSync).mockImplementation(
-			(path) => typeof path === "string" && path.includes("settings.json"),
-		);
-		vi.mocked(readFileSync).mockImplementation((path: unknown) =>
-			typeof path === "string" && path.includes(".pi/agent/settings")
-				? JSON.stringify({ browserToggle: { defaultEnabled: true } })
-				: JSON.stringify({}),
-		);
-
-		const pi = mockPi({
-			tools: [...ALL_BROWSER_TOOLS, ...NON_BROWSER_TOOLS],
-			activeTools: NON_BROWSER_TOOLS.map((t) => t.name), // browsers off
-		});
-		vi.spyOn(pi, "setActiveTools");
-
-		applyConfigDefault(pi);
-
-		expect(pi.setActiveTools).toHaveBeenCalledWith(
-			expect.arrayContaining(ALL_BROWSER_TOOLS.map((t) => t.name)),
-		);
-	});
-
-	it("calls applyBrowserState with the config value (false)", () => {
-		vi.mocked(existsSync).mockReturnValue(true);
-		vi.mocked(readFileSync).mockImplementation((path: unknown) =>
-			typeof path === "string" && path.includes(".pi/agent/settings")
-				? JSON.stringify({ browserToggle: { defaultEnabled: false } })
-				: JSON.stringify({}),
-		);
-
-		const pi = mockPi({
-			tools: [...ALL_BROWSER_TOOLS, ...NON_BROWSER_TOOLS],
-			activeTools: [
-				...NON_BROWSER_TOOLS.map((t) => t.name),
-				...ALL_BROWSER_TOOLS.map((t) => t.name),
-			],
-		});
-		vi.spyOn(pi, "setActiveTools");
-
-		applyConfigDefault(pi);
-
-		const calledWith = (pi.setActiveTools as ReturnType<typeof vi.fn>).mock
-			.calls[0]![0] as string[];
-		expect(calledWith).not.toContain("web-fetch");
-		expect(calledWith).not.toContain("browser-navigate");
-	});
-
-	it("persists the applied state", () => {
-		vi.mocked(existsSync).mockReturnValue(true);
-		vi.mocked(readFileSync).mockReturnValue(
-			JSON.stringify({ browserToggle: { defaultEnabled: true } }),
-		);
+describe("external-plugin glyph sync", () => {
+	it("re-renders browser glyph off when external plugin fires portal.web disabled", async () => {
+		const { pi, handlers, events } = mockPi();
+		browserToggle(pi);
 
-		const pi = mockPi({
-			tools: ALL_BROWSER_TOOLS,
-			activeTools: ALL_BROWSER_TOOLS.map((t) => t.name),
-		});
+		// Fire session_start once to establish _lastCtx.
+		// After this, the glyph is rendered correctly for default state.
+		const startCtx = mockCtx();
+		for (const h of handlers.get("session_start") ?? []) {
+			await h({}, startCtx);
+		}
 
-		applyConfigDefault(pi);
+		// Clear the initial render call so we only see the external-plugin re-render.
+		vi.clearAllMocks();
 
-		expect(pi.appendEntry).toHaveBeenCalledWith(
-			"web-toggle-state",
-			expect.objectContaining({
-				browserToolsEnabled: true,
-				learnToolsEnabled: false,
-			}),
+		// Simulate an external plugin disabling portal.web — it has
+		// already removed browser tools from the active set.
+		const nonBrowser = ALL_TOOLS.map((t) => t.name).filter(
+			(n) => !BROWSER_TOOL_NAMES.has(n),
 		);
-	});
+		(pi.getActiveTools as any).mockReturnValue(nonBrowser);
 
-	it("is a no-op when no browser tools are registered", () => {
-		const pi = mockPi({
-			tools: NON_BROWSER_TOOLS,
-			activeTools: NON_BROWSER_TOOLS.map((t) => t.name),
+		events.emit(TOOLSET_EVENTS.changed, {
+			id: "portal.web",
+			enabled: false,
 		});
-		vi.spyOn(pi, "setActiveTools");
-
-		applyConfigDefault(pi);
-
-		expect(pi.setActiveTools).not.toHaveBeenCalled();
-	});
-});
-
-// ==================================================================
-//  restoreFromBranch — updated return value
-// ==================================================================
-describe("restoreFromBranch (return value)", () => {
-	it("returns true when saved state was found and applied", () => {
-		const pi = mockPi({
-			tools: ALL_BROWSER_TOOLS,
-			activeTools: NON_BROWSER_TOOLS.map((t) => t.name),
-		});
-		const ctx = mockContext([
-			{
-				type: "custom",
-				customType: "web-toggle-state",
-				data: {
-					browserToolsEnabled: true,
-					learnToolsEnabled: false,
-					defaultProfile: "none",
-				} satisfies BrowserToggleState,
-			},
-		]);
-		expect(restoreFromBranch(pi, ctx)).toBe(true);
-	});
-
-	it("returns false when no saved state in branch", () => {
-		const pi = mockPi({
-			tools: ALL_BROWSER_TOOLS,
-			activeTools: ALL_BROWSER_TOOLS.map((t) => t.name),
-		});
-		const ctx = mockContext([
-			{ type: "message", data: { role: "user" } },
-			{ type: "message", data: { role: "assistant" } },
-		]);
-		expect(restoreFromBranch(pi, ctx)).toBe(false);
-	});
 
-	it("returns false when no browser tools are registered", () => {
-		const pi = mockPi({ tools: NON_BROWSER_TOOLS });
-		const ctx = mockContext([
-			{
-				type: "custom",
-				customType: "web-toggle-state",
-				data: { browserToolsEnabled: false, learnToolsEnabled: false },
-			},
-		]);
-		expect(restoreFromBranch(pi, ctx)).toBe(false);
+		expect(startCtx.ui.setStatus).toHaveBeenCalledWith("browser", "○ web off");
 	});
 });