pi-lean-dimension 0.3.3 → 0.4.0

package/README.md

@@ -21,34 +21,27 @@ npx playwright install chromium firefox
 That's it — the tools are registered and start enabled by default. Control
 them with `/web on|off|learn` (`on` = browser tools, `learn` = browser tools
 plus guide-saving via `web-learn`, `off` = everything off). The state persists
-per session. To set a different default for **new** sessions, add this to your
-Pi settings (`~/.pi/agent/settings.json` or `.pi/settings.json`):
+per session. To set a different default for **new** sessions, add a
+`toolsetDefaults` block to your Pi settings (`~/.pi/agent/settings.json` or
+`.pi/settings.json`):
 
 ```json
-{ "browserToggle": { "defaultEnabled": false } }
+{
+  "toolsetDefaults": {
+    "toolset-state:pi-lean-dimension.web": { "enabled": false },
+    "toolset-state:pi-lean-dimension.web-learn": { "enabled": false },
+    "toolset-state:pi-lean-dimension.search": { "enabled": false }
+  }
+}
 ```
 
-> ⚠️ **Deprecated — not yet replaced.** `browserToggle.defaultEnabled` is
-> still read today and works as shown. It is *scheduled* to be replaced by
-> the `pi-tool-masking` library's `toolsetDefaults` block in an upcoming
-> release — **that block is not read yet**, so keep the legacy key until the
-> replacement ships. To be ready, you can add the future block alongside it
-> (it's harmless today; it'll take effect automatically once the offload
-> lands):
->
-> ```json
-> {
->   "browserToggle": { "defaultEnabled": false },
->   "toolsetDefaults": {
->     "toolset-state:pi-lean-dimension.web": { "enabled": false },
->     "toolset-state:pi-lean-dimension.web-learn": { "enabled": false },
->     "toolset-state:pi-lean-dimension.search": { "enabled": false }
->   }
-> }
-> ```
->
-> (omit a `toolsetDefaults` key to use the toolset's packaged default; the
-> `search` key only applies when `pi-lean-search` is installed.)
+`toolsetDefaults` is read by the [`pi-tool-masking`](https://github.com/coreyryanhanson/pi-tool-masking/) library on restore, before
+the toolset's packaged default. Omit a key to use the packaged default; the
+`search` key only applies when `pi-lean-search` is installed.
+
+> The legacy `browserToggle.defaultEnabled` key is **removed in 0.4.0** and
+> no longer read. If you pinned it, move the value into the matching
+> `toolsetDefaults` entry above.
 
 ---
 

package/node_modules/pi-lean-portal/README.md

@@ -115,17 +115,10 @@ toggles guide-saving mode, and manages browser profiles.
 ### Persistence
 
 The toggle state is stored in the conversation's branch history. A fresh
-conversation starts with the default from `settings.json` (`browserToggle.defaultEnabled`,
-which defaults to `true`).
-
-> ⚠️ `browserToggle.defaultEnabled` is still read today but is scheduled to be
-> replaced by the `pi-tool-masking` library's `toolsetDefaults` block in an
-> upcoming release — **that block is not read yet**, so keep the legacy key
-> until the replacement ships. See
-> [Configuration (`settings.json`)](#configuration-settingsjson) for the
-> future shape and how to pre-add it harmlessly. A migration warning fires on
-> session start once the legacy key is present and the web default hasn't yet
-> been mirrored into `toolsetDefaults`.
+conversation starts with the default from `settings.json` — the
+`pi-tool-masking` library's `toolsetDefaults` block (see
+[Configuration (`settings.json`)](#configuration-settingsjson)), falling back
+to the toolset's packaged default (`true` for `web`).
 
 ---
 
@@ -615,48 +608,30 @@ a `profile` parameter:
 }
 ```
 
-### `browserToggle.defaultEnabled` *(deprecated — not yet replaced)*
+### `toolsetDefaults` *(settings-based toolset defaults)*
 
-Whether browser tools are enabled on fresh conversations. **This key is still
-read today and works as shown.** It is *scheduled* to be replaced by the
-`pi-tool-masking` library's `toolsetDefaults` block in an upcoming release —
-**that block is not read yet**, so keep this key until the replacement ships.
+Whether browser tools are enabled on fresh conversations. Read by the
+`pi-tool-masking` library at restore time, between the chat-branch tier and
+the toolset's packaged default:
 
 ```jsonc
 {
-  "browserToggle": {
-    "defaultEnabled": true
+  "toolsetDefaults": {
+    "toolset-state:pi-lean-dimension.web": { "enabled": true },
+    "toolset-state:pi-lean-dimension.web-learn": { "enabled": false },
+    "toolset-state:pi-lean-dimension.search": { "enabled": true }
   }
 }
 ```
 
-> ⚠️ **Preparing for the offload.** Settings-based toolset defaults are being
-> offloaded to the `pi-tool-masking` library, which will read a new
-> `toolsetDefaults` block keyed by persist key. **The new block is not read
-> by the current release** — it's harmless to add now and will take effect
-> automatically once the offload ships, at which point the legacy key stops
-> being read. To pre-stage the migration, set both:
->
-> ```jsonc
-> {
->   "browserToggle": { "defaultEnabled": true },
->   "toolsetDefaults": {
->     "toolset-state:pi-lean-dimension.web": { "enabled": true },
->     "toolset-state:pi-lean-dimension.web-learn": { "enabled": false },
->     "toolset-state:pi-lean-dimension.search": { "enabled": true }
->   }
-> }
-> ```
->
-> - Keys are the toolsets' `persistKey` values (`toolset-state:<id>`).
-> - Omit a `toolsetDefaults` key to use the toolset's packaged default (`web`
->   and `search` default `true`; `web-learn` defaults `false`).
-> - The `search` key only applies when `pi-lean-search` is installed.
->
-> Once the offload ships and the legacy read is removed, delete the
-> `browserToggle` block. Until then, a migration warning fires on session
-> start when the legacy key is present and the web default hasn't yet been
-> mirrored into `toolsetDefaults`; mirroring it suppresses the warning.
+- Keys are the toolsets' `persistKey` values (`toolset-state:<id>`).
+- Omit a `toolsetDefaults` key to use the toolset's packaged default (`web`
+  and `search` default `true`; `web-learn` defaults `false`).
+- The `search` key only applies when `pi-lean-search` is installed.
+
+> The legacy `browserToggle.defaultEnabled` key is **removed in 0.4.0** — it
+> is no longer read. If you pinned it, move the value into the matching
+> `toolsetDefaults` entry above.
 
 ### `browser.maxStorageStateSize`
 

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

@@ -9,24 +9,12 @@ import {
 	getDefaultResolutionMode,
 } from "pi-tool-masking";
 import type { ToolsetSpec } from "pi-tool-masking";
-import { readMergedSettings } from "./core/shared/settings-reader.js";
-
-// Focus-mode guard helper. The library's published `DefaultResolutionMode`
-// type is `"exclusion" | "inclusion"` (the allowlist mode is unpublished /
-// ships in pi-tool-masking 1.2.0), so the string cast is load-bearing: an
-// allowlist-capable consumer sharing the `globalThis` module state writes
-// `"allowlist"` into it, and this consumer reads that value back at runtime
-// even though its own bundled type doesn't name the mode. On published
-// versions no caller ever writes `"allowlist"`, so this is a no-op for
-// ordinary users — it only activates when an allowlist-capable
-// pi-tool-masking consumer is in play.
-//
-// Cleanup at the ^1.2.0 bump: once `DefaultResolutionMode` names
-// `"allowlist"`, drop the `as string` cast here and in pi-lean-search's
-// co-activation mirror — the type system can then check the comparison
-// directly and the cast becomes a suppressor of a check it should perform.
+
+// Focus-mode guard: refuse actuating subcommands while the library holds the
+// line — inclusion mode or allowlist focus (an upstream pi-tool-masking
+// consumer).
 function isFocusHolding(): boolean {
-	const mode = getDefaultResolutionMode() as string;
+	const mode = getDefaultResolutionMode();
 	return mode === "inclusion" || mode === "allowlist";
 }
 
@@ -154,86 +142,13 @@ function renderBrowserGlyph(
 	}
 }
 
-// ---- Legacy settings migration warning ---------------------------
-//
-// The portal currently seeds the web toolset's fresh-session default from
-// `browserToggle.defaultEnabled` in settings.json. An upcoming pi-tool-masking
-// release takes over settings-based toolset defaults and reads a new
-// `toolsetDefaults` block instead. Warn users who pinned the legacy key so
-// they can migrate before the offload lands and the legacy read is removed.
-//
-// ponytail: warn-only — we still honor the legacy key for backward compat
-// until pi-tool-masking owns the settings tier; then delete this helper and
-// the `browserToggle` read below. Ceiling: a silent default shift for users
-// who ignore the warning; upgrade path is the pi-tool-masking bump.
-const TOOLSET_DEFAULTS_MIGRATION_MSG =
-	"⚠️ pi-lean-portal: settings-based toolset defaults are moving to the " +
-	"pi-tool-masking library. The `browserToggle.defaultEnabled` key in your " +
-	"settings.json will stop being read in an upcoming release. It still works " +
-	"today — KEEP it until the replacement ships, and add the new " +
-	"`toolsetDefaults` block alongside it so your config is ready (the new " +
-	"block is not read yet, but is harmless now and will take effect " +
-	"automatically once the offload lands):\n\n" +
-	"{\n" +
-	'  "browserToggle": { "defaultEnabled": true },\n' +
-	'  "toolsetDefaults": {\n' +
-	'    "toolset-state:pi-lean-dimension.web": { "enabled": true },\n' +
-	'    "toolset-state:pi-lean-dimension.web-learn": { "enabled": true },\n' +
-	'    "toolset-state:pi-lean-dimension.search": { "enabled": true }\n' +
-	"  }\n" +
-	"}\n" +
-	"(omit a `toolsetDefaults` key to use the toolset's packaged default; the " +
-	"`search` key only applies when pi-lean-search is installed). Mirror your " +
-	"web default into `toolset-state:pi-lean-dimension.web` to silence this " +
-	"warning.";
-
-function hasLegacyToolsetDefault(merged: Record<string, unknown>): boolean {
-	const seg = merged["browserToggle"];
-	if (!seg || typeof seg !== "object" || Array.isArray(seg)) return false;
-	return (
-		typeof (seg as Record<string, unknown>)["defaultEnabled"] === "boolean"
-	);
-}
-
-// The new `toolsetDefaults` block the pi-tool-masking offload will read.
-// When the user has already migrated the web toolset's default into it,
-// the warning is redundant even if the legacy `browserToggle.defaultEnabled`
-// key is still sitting on disk — suppress so a migrated settings file stays
-// quiet. Only the web persist key gates this: it's the one the legacy key
-// controlled, so its presence means the user acted on the migration.
-const WEB_TOOLSET_PERSIST_KEY = "toolset-state:pi-lean-dimension.web";
-function hasMigratedToolsetDefault(merged: Record<string, unknown>): boolean {
-	const td = merged["toolsetDefaults"];
-	if (!td || typeof td !== "object" || Array.isArray(td)) return false;
-	const entry = (td as Record<string, unknown>)[WEB_TOOLSET_PERSIST_KEY];
-	if (!entry || typeof entry !== "object" || Array.isArray(entry)) return false;
-	return typeof (entry as Record<string, unknown>)["enabled"] === "boolean";
-}
-
 // ---- Toggle initializer ------------------------------------------
 
 export default function initBrowserToggle(pi: ExtensionAPI) {
-	const merged = readMergedSettings();
-	// Warn only when the legacy key is pinned AND the user hasn't already
-	// migrated the web default into `toolsetDefaults`. Once the migrated
-	// entry exists, pi-tool-masking will read it directly and the legacy
-	// key is dead weight — no need to nag.
-	const legacyDefaultPinned =
-		hasLegacyToolsetDefault(merged) && !hasMigratedToolsetDefault(merged);
-	const browserToggleSegment = (merged as Record<string, unknown>)[
-		"browserToggle"
-	] as Record<string, unknown> | undefined;
-	const webDefault =
-		browserToggleSegment &&
-		typeof browserToggleSegment["defaultEnabled"] === "boolean"
-			? (browserToggleSegment["defaultEnabled"] as boolean)
-			: true;
-
-	const webSpec: ToolsetSpec = {
-		...PORTAL_WEB_SPEC,
-		defaultEnabled: webDefault,
-	};
-	const webToolset = defineToolset(pi, webSpec);
+	// Settings-based toolset defaults (`toolsetDefaults` tier) are read by
+	// pi-tool-masking itself inside defineToolset/restore — pass the packaged
+	// spec straight through.
+	const webToolset = defineToolset(pi, PORTAL_WEB_SPEC);
 	const learnToolset = defineToolset(pi, PORTAL_LEARN_SPEC);
 
 	// ── Keep cached state in sync with library events ─────────
@@ -267,8 +182,7 @@ export default function initBrowserToggle(pi: ExtensionAPI) {
 			// unguarded, matching the focus controller's treatment of its own
 			// read-only commands.
 			if (["on", "off", "learn"].includes(cmd) && isFocusHolding()) {
-				const inInclusion =
-					(getDefaultResolutionMode() as string) === "inclusion";
+				const inInclusion = getDefaultResolutionMode() === "inclusion";
 				ctx.ui.notify(
 					inInclusion
 						? "Another plugin has active inclusion mode — this toolset can't be toggled while inclusion is holding the line. Deactivate it there first."
@@ -348,11 +262,6 @@ export default function initBrowserToggle(pi: ExtensionAPI) {
 		restoreProfile(pi, ctx);
 		_lastCtx = ctx;
 		syncCachedState();
-		// One-time-per-session migration warning when the legacy
-		// `browserToggle.defaultEnabled` pin is still on disk.
-		if (legacyDefaultPinned) {
-			ctx.ui.notify(TOOLSET_DEFAULTS_MIGRATION_MSG, "warning");
-		}
 	});
 
 	pi.on("session_tree", async (_event, ctx) => {

package/node_modules/pi-lean-portal/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-lean-portal",
-	"version": "0.3.3",
+	"version": "0.4.0",
 	"description": "Pi extension. Interactive web browsing for Pi — a /web toggle removes the tools from context when switched off, Playwright Chromium/Firefox deliver accessibility-tree snapshots, persistent profiles, cookies, and domain-matched guides; custom/stealth backends (Camoufox) plug in when a site blocks the shipped browsers.",
 	"keywords": [
 		"pi-package",
@@ -56,7 +56,7 @@
 	},
 	"dependencies": {
 		"node-html-parser": "^6.1.0",
-		"pi-tool-masking": "^1.1.0",
+		"pi-tool-masking": "^1.2.0",
 		"playwright": "^1.60.0",
 		"turndown": "^7.2.0"
 	},

package/node_modules/pi-lean-search/__tests__/web-search.test.ts

@@ -80,9 +80,7 @@ describe("readSearxngUrl", () => {
 		vi.mocked(existsSync).mockImplementation(
 			(path) => typeof path === "string" && path.includes(".pi"),
 		);
-		vi.mocked(readFileSync).mockReturnValue(
-			JSON.stringify({ theme: "dark", browserToggle: {} }),
-		);
+		vi.mocked(readFileSync).mockReturnValue(JSON.stringify({ theme: "dark" }));
 		expect(readSearxngUrl()).toBeUndefined();
 	});
 
@@ -482,8 +480,7 @@ describe("pi-lean-dimension.web co-activation mirror", () => {
 	// Allowlist focus (an upstream pi-tool-masking consumer) holds the line —
 	// the mirror must not co-activate, so a stale library `doRestore` emitting
 	// a web `changed` during resume can't disable search or write a {enabled}
-	// entry. Set the shared module state directly (published type doesn't name
-	// "allowlist").
+	// entry. Set the shared module state directly.
 	it("skips co-activation while allowlist focus is active", async () => {
 		const { pi, events } = mockSearchPi(["web-search"]);
 		searchExtension(pi);

package/node_modules/pi-lean-search/index.ts

@@ -208,20 +208,10 @@ export default function (pi: ExtensionAPI) {
 	// co-activation. The focus set is authoritative, so a web `changed` event
 	// — including one a stale library `doRestore` emits during resume — must
 	// not disable search or write a focus-indistinguishable {enabled} entry.
-	// The published `DefaultResolutionMode` type doesn't name `"allowlist"`
-	// (it ships in pi-tool-masking 1.2.0), so the string cast is load-bearing:
-	// an allowlist-capable consumer sharing the `globalThis` module state
-	// writes `"allowlist"` into it and we read it back here. No-op for
-	// ordinary users on published versions, where nothing ever writes
-	// `"allowlist"`.
-	//
-	// Cleanup at the ^1.2.0 bump: drop the `as string` cast once
-	// `DefaultResolutionMode` names `"allowlist"` — same as the matching cast
-	// in pi-lean-portal's browser-toggle focus guard.
 	pi.events.on(TOOLSET_EVENTS.changed, (data: unknown) => {
 		const event = data as ToolsetChangedEvent;
 		if (event.id === "pi-lean-dimension.web") {
-			if ((getDefaultResolutionMode() as string) === "allowlist") return;
+			if (getDefaultResolutionMode() === "allowlist") return;
 			if (event.enabled) {
 				searchToolset.enable(pi);
 			} else {

package/node_modules/pi-lean-search/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-lean-search",
-	"version": "0.3.3",
+	"version": "0.4.0",
 	"description": "Pi extension. SearXNG search tool for Pi — pairs with pi-lean-portal's /web toggle; search-only installs are valid, or add it to a portal install for the full web-tools suite.",
 	"keywords": [
 		"pi-package",
@@ -38,7 +38,7 @@
 		"test": "vitest run"
 	},
 	"dependencies": {
-		"pi-tool-masking": "^1.1.0"
+		"pi-tool-masking": "^1.2.0"
 	},
 	"peerDependencies": {
 		"@earendil-works/pi-ai": "*",

package/node_modules/pi-tool-masking/README.md

@@ -16,7 +16,7 @@ Without `pi-tool-masking`, every pi extension that toggles tools reimplements th
 4. On `session_start` / `session_tree`, walk the branch for persisted entries and re-apply state.
 5. Emit events so side-effect owners (status bars, pickers) can re-render.
 
-`pi-tool-masking` does all of that in one call: `defineToolset(pi, spec)`. It also adds dependency cascading (enabling a toolset auto-enables its dependencies) and reverse cascading (disabling a toolset auto-disables dependents).
+`pi-tool-masking` does all of that in one call: `defineToolset(pi, spec)`. It also adds dependency cascading (enabling a toolset auto-enables its dependencies) and reverse cascading (disabling a toolset auto-disables dependents), plus a settings tier for per-scope defaults and allowlist mode for reliable focus across reloads.
 
 ---
 
@@ -89,19 +89,24 @@ Register a toolset and receive a `Toolset` handle (`enable`, `disable`, `isEnabl
 
 **Idempotent re-registration:** calling `defineToolset` with the same `spec.id` and an unchanged spec returns the existing toolset. This is safe across `/reload`.
 
-### `setDefaultResolutionMode(pi, mode)`
+### `setDefaultResolutionMode(pi, mode, allowlist?)`
 
-Switch how toolsets with no persisted state resolve on restore. Two modes:
+Switch how toolsets with no persisted state resolve on restore. Three modes:
 
 | Mode | Behavior on restore (no persisted entry) |
 |---|---|
 | `"exclusion"` (default) | Toolsets default **on** if `defaultEnabled` is true, **off** otherwise |
-| `"inclusion"` | All unknown toolsets default **off** — useful for focus-mode "only these tools" workflows |
+| `"inclusion"` (@deprecated since 1.2.0) | All unknown toolsets default **off** — a weaker, unbounded floor. Use `"allowlist"` instead for focus-style "only these tools" suppression |
+| `"allowlist"` | Only the listed toolset ids are **on**, everything else **off** — a finite, branch-persisted set whose complement is computed at restore, resilient to toolsets installed later. Pass the array as the third argument: `setDefaultResolutionMode(pi, "allowlist", ["my-plugin.web"])` |
 
 ### `getDefaultResolutionMode()`
 
 Read the current default resolution mode. Returns `"exclusion"` until a session restore loads the persisted mode.
 
+### `getActiveAllowlist()`
+
+Read the live allowlist array from module state. Returns the `string[]` when the active mode is `"allowlist"`, otherwise `undefined`. Parameterless (like `getDefaultResolutionMode`) — the downstream call site receives `ExtensionAPI`, which doesn't expose `sessionManager`, so the branch can't be read there. The branch remains the source of truth; module state is the live mirror, snapped from the last mode branch entry by `doRestore` (and by `setDefaultResolutionMode` when it appends the entry). A consumer consults this to keep toolsets registered *after* focus was entered off.
+
 ### `getRegisteredToolsets()`
 
 Return a read-only snapshot of every registered toolset (`{ spec, toolset }`). No `pi` argument needed — pure registry read.
@@ -121,10 +126,59 @@ Return a read-only snapshot of every registered toolset (`{ spec, toolset }`). N
 | `Toolset` | Handle returned by `defineToolset` |
 | `ToolsetChangedEvent` | Shape of events emitted by `TOOLSET_EVENTS` |
 | `RegistryEntry` | `{ spec: ToolsetSpec; toolset: Toolset }` — a single registered toolset |
-| `DefaultResolutionMode` | `"exclusion" \| "inclusion"` |
+| `DefaultResolutionMode` | `"exclusion" \| "inclusion" \| "allowlist"` |
+| `MalformedSettingsError` | Thrown by `writeToolsetDefaults` / `clearToolsetDefaults` when settings.json is corrupt or non-object (never silently overwritten). Catch with `instanceof`. |
 
 ---
 
+## Toolset defaults (settings tier)
+
+A toolset's fresh-session default is no longer locked to its packaged `spec.defaultEnabled`. Users can pin `{ enabled: boolean }` under a reserved `toolsetDefaults` key in pi-core settings, keyed by the toolset's full `persistKey` — without toggling (which writes a session-scoped chat-branch entry). The library reads both files itself inside `doRestore`, fresh on each `/reload`, so downstream consumers no longer need to reinvent a settings reader to inject values into `spec.defaultEnabled` before `defineToolset`.
+
+Restore resolves each toolset's default in this order (first hit wins):
+
+1. **Chat-branch entry** — the last `appendEntry(persistKey, …)` on this branch. A `null` tombstone (see [`clearToolsetEntry`](#tombstone-helpers)) falls through to tier 2.
+2. **Settings pin** — `toolsetDefaults[persistKey].enabled`, merged global → project (project wins per entry). Mode-agnostic.
+3. **Packaged default** — `spec.defaultEnabled ?? true`, filtered by resolution mode for unpinned toolsets only.
+
+Settings pins are honored in all three modes, mirroring how chat-branch entries are honored — only unpinned toolsets consult mode for the floor.
+
+### `readMergedToolsetDefaults()`
+
+Read and merge `toolsetDefaults` from global (`~/.pi/agent/settings.json`, or `$PI_CODING_AGENT_DIR/settings.json`) and project (`<cwd>/.pi/settings.json`) settings. Project overrides global per entry. Missing/unreadable/malformed files contribute `{}`. Never throws. Returns `Record<persistKey, { enabled: boolean }>`. Read once per loop and pass the snapshot to `getEffectiveDefault` to avoid re-reading disk per toolset.
+
+### `readToolsetDefaults(scope)`
+
+Read one scope's raw `toolsetDefaults` block (no merge). `scope` is `"global"` or `"project"`. Same never-throw policy. Use for `defaults show`-style commands that need per-scope attribution.
+
+### `writeToolsetDefaults(entries, scope)`
+
+Merge a batch of `{ [persistKey]: { enabled } }` entries into one scope's `toolsetDefaults`, preserving every other top-level key and every existing entry not in `entries`. A write where every entry already matches its on-disk value is a no-op (no reformat, no mtime bump). Returns the settings file path. **Throws `MalformedSettingsError`** if the file exists but parses to a non-object or is unparsable — a corrupt file is never silently overwritten.
+
+### `clearToolsetDefaults(scope)`
+
+Remove the `toolsetDefaults` wrapper key entirely from one scope, preserving every other top-level key. Returns the path removed from, or `null` if the key was already absent (or the file missing). No per-entry clear by design — write an `entries` map without the unwanted keys via `writeToolsetDefaults`. Same `MalformedSettingsError` guard.
+
+### `getEffectiveDefault(spec, snapshot?)`
+
+Resolve a toolset's effective fresh-session default: settings tier (2) then packaged `spec.defaultEnabled ?? true` (3). **Ignores resolution mode** — callers needing mode-aware behavior must consult `getDefaultResolutionMode()` themselves. Pass an explicit `snapshot` (from `readMergedToolsetDefaults()`) when looping over multiple toolsets; omit it for a one-off (it performs its own read).
+
+## Tombstone helpers
+
+Within pi-core's append-only `SessionManager`, a toolset's chat-branch entry can't be deleted — but a `null` tombstone appended after the last entry makes `doRestore` fall through to the settings tier so settings re-assert. Tombstones are dedup'd (no-op when the last entry is already cleared) and never written for never-toggled toolsets. A later manual toggle appends after the tombstone and supersedes it.
+
+### `clearToolsetEntry(pi, persistKey, branch)`
+
+Append a `null` tombstone for one toolset's branch entry (dedup'd). `branch` is the caller's `ctx.sessionManager.getBranch()` snapshot — `ExtensionAPI` exposes `appendEntry` but not `sessionManager`, so the dedup read comes from the caller.
+
+### `clearAllToolsetEntries(pi, branch)`
+
+Tombstone every registered toolset's branch entry (dedup'd per toolset). Covers exactly the toolsets in the global registry.
+
+### `applyToolsetEnabled(pi, spec, enabled)`
+
+Apply a toolset's enabled state via `setActiveTools` and emit `TOOLSET_EVENTS.changed` **without** writing a branch entry — the live-apply half of a settings restore (pull a toolset to its settings/packaged default without persisting a chat-branch pin).
+
 ## ToolsetSpec fields
 
 ```ts
@@ -206,15 +260,18 @@ pi.events.on(TOOLSET_EVENTS.restored, (event) => {
 });
 ```
 
-### Focus mode (inclusion resolution)
+### Focus mode (allowlist resolution)
 
 ```ts
 import { setDefaultResolutionMode, getRegisteredToolsets } from "pi-tool-masking";
 
-// Enter focus: set inclusion mode so unknown toolsets stay off
-setDefaultResolutionMode(pi, "inclusion");
+// Enter focus: allowlist mode keeps only the listed toolsets on — restore
+// applies it on the next /reload, and the loop below applies it live.
+// "inclusion" (deprecated) cannot guarantee this: a toolset installed after
+// focus leaks on, because the set of "on" toolsets was never recorded.
+setDefaultResolutionMode(pi, "allowlist", ["my-plugin.web"]);
 
-// Enable only the allowlisted toolsets
+// Apply live: enable only the allowlisted toolsets
 const allowlist = new Set(["my-plugin.web"]);
 for (const entry of getRegisteredToolsets()) {
  if (allowlist.has(entry.spec.id)) {
@@ -282,7 +339,9 @@ ids with a stable namespace (<product-family>.<subset>, e.g. "foo.web").
 
 - **Registration:** `defineToolset` stores the spec and handle in a global registry (shared across module instances, so multiple extensions see the same toolsets).
 - **Persistence:** each toolset writes `{ enabled }` entries under its `persistKey` on the session branch. On `session_start` or `session_tree`, the library re-reads the branch and applies the last persisted state.
-- **Default resolution:** a single `toolset-resolution-mode` entry on the branch controls whether unknown toolsets default on or off. This is set by `setDefaultResolutionMode` and persists across reloads.
+- **Default resolution:** a `toolset-resolution-mode` entry on the branch controls how toolsets with no persisted state resolve on restore — `exclusion` (on/off by `defaultEnabled`), `inclusion` (deprecated unbounded floor), or `allowlist` (a finite branch-persisted array whose complement is computed at restore). Set by `setDefaultResolutionMode`, persists across reloads.
+- **Defaults tiers:** each toolset's restore default resolves chat-branch entry → `toolsetDefaults` settings pin → packaged `spec.defaultEnabled`, filtered by resolution mode for unpinned toolsets only. Settings pins are read fresh from disk on each restore.
+- **Null-tombstone-aware restore:** a `null` last branch entry (written by `clearToolsetEntry`) falls through to the settings tier instead of any stale prior entry; mode resolution is likewise null-tombstone-aware (`branchMode ?? "exclusion"`). Tombstones aren't sticky — a later toggle supersedes them.
 - **Events:** a live toggle emits only when state actually changes (no-op toggles are suppressed); restore always emits, so side-effect owners stay in sync across reloads and tree navigations.
 
 ---