@tiagojct/subsub 0.11.0 → 0.11.2

package/src/cli.ts

@@ -134,12 +134,38 @@ export function reviewCommand(args: string[], cfg: SubsubConfig, env: NodeJS.Pro
 	};
 }
 
+const HELP = `Sub-Sub: your research assistant, working from your own Zotero library.
+
+Usage:
+  subsub                 Start Sub-Sub in the terminal
+  subsub --librarian     Start in the Librarian, which only manages the library
+  subsub web             Open Sub-Sub in the browser
+  subsub init            Set up or change the settings (folder, tag list, profile, models)
+  subsub doctor          Check the set-up; each line marked FIX says what to do
+  subsub shortcut        Add a Sub-Sub shortcut (--remove takes it away)
+  subsub review preview|apply <note>
+                         Check or apply a tag review note from Inbox/
+  subsub --version       Show the versions
+
+Options:
+  --here                 Work in the current folder, not in the Sub-Sub folder
+
+In Sub-Sub, type /subsub for the state, /researcher or /librarian to switch modes,
+/profile to change the profile, /undo to undo the last change, and / for all commands.
+Sub-Sub runs on pi: pi's options (for example --model, --resume) also work.
+
+Docs: https://subsub.tiagojacinto.eu`;
+
 export async function run(argv: string[] = process.argv.slice(2)): Promise<void> {
 	const env = process.env;
 	const home = homedir();
 	const here = argv.includes("--here");
 	const args = argv.filter((a) => a !== "--here");
 
+	if (args[0] === "--help" || args[0] === "-h" || args[0] === "help") {
+		console.log(HELP);
+		return;
+	}
 	if (args[0] === "--version" || args[0] === "-v") {
 		const piPkg = join(dirname(fileURLToPath(import.meta.resolve("@earendil-works/pi-coding-agent"))), "..");
 		console.log(`subsub ${packageVersion()} (pi ${packageVersion(piPkg)})`);
@@ -173,7 +199,12 @@ export async function run(argv: string[] = process.argv.slice(2)): Promise<void>
 		return;
 	}
 	if (isSelfUpdate(args)) {
-		console.log(`Sub-Sub is not updated with "update". Its code is in ${PACKAGE_DIR}; after new code arrives, run "npm install" there.`);
+		if (PACKAGE_DIR.split(/[\\/]/).includes("node_modules")) {
+			console.log("Sub-Sub is not updated with \"update\". To update it, run the installer again (https://subsub.tiagojacinto.eu/install/);");
+			console.log("if you installed it with npm, type: npm install -g @tiagojct/subsub");
+		} else {
+			console.log(`Sub-Sub is not updated with "update". Its code is in ${PACKAGE_DIR}; after new code arrives, run "npm install" there.`);
+		}
 		console.log('To update packages added to Sub-Sub, use "subsub update --extensions".');
 		process.exitCode = 1;
 		return;
@@ -206,6 +237,8 @@ export async function run(argv: string[] = process.argv.slice(2)): Promise<void>
 	env.SUBSUB_CLI = "1";
 	// pi's update notice would point to the global pi, not to this copy.
 	env.PI_SKIP_VERSION_CHECK ??= "1";
+	// pi reports a first install to pi.dev and names itself to some providers; Sub-Sub sends no usage data.
+	env.PI_TELEMETRY ??= "0";
 
 	process.argv = [process.argv[0], process.argv[1], ...args];
 	const index = fileURLToPath(import.meta.resolve("@earendil-works/pi-coding-agent"));

package/src/config.ts

@@ -39,7 +39,7 @@ export type Profile = "reader" | "scholar" | "author" | "editor";
 export const PROFILES: Profile[] = ["reader", "scholar", "author", "editor"];
 
 /** The Zotero server release that this Sub-Sub version runs when there is no local server folder. */
-export const SERVER_VERSION = "0.5.1";
+export const SERVER_VERSION = "0.5.2";
 
 /** The Starbuck release (PyPI) that this Sub-Sub version runs when there is no local Starbuck folder. */
 export const STARBUCK_VERSION = "0.2.0";
@@ -159,7 +159,9 @@ export function loadConfig(env: NodeJS.ProcessEnv = process.env): SubsubConfig {
 	// "models" per mode; "model" (0.10) for both; {} or "" means: the user chooses in pi (/login, /model).
 	const one = typeof user.model === "string" ? user.model : undefined;
 	const given = user.models && typeof user.models === "object" ? (user.models as Record<string, string>) : undefined;
-	const models: Partial<Record<Mode, string>> = given ?? (one !== undefined ? { librarian: one || undefined, researcher: one || undefined } : { ...DEFAULT_MODELS });
+	// Without a settings file (no subsub init yet), the user chooses in pi: no default that may lack a key.
+	const fallback = existsSync(file) ? { ...DEFAULT_MODELS } : {};
+	const models: Partial<Record<Mode, string>> = given ?? (one !== undefined ? { librarian: one || undefined, researcher: one || undefined } : fallback);
 	for (const k of Object.keys(models) as Mode[]) if (!models[k]) delete models[k];
 	const themes = user.themes === false ? false : typeof user.themes === "string" ? user.themes : user.themes?.researcher;
 	return {
@@ -223,6 +225,19 @@ export function serverCommand(
 	return { command: uv, args: ["tool", "run", "--quiet", "--from", `zotero-local-mcp==${SERVER_VERSION}`, program, ...args] };
 }
 
+/**
+ * uv caches the PyPI index; right after a release it may not know the pinned version yet
+ * ("there is no version of zotero-local-mcp==0.5.2"). Then the same command runs again with
+ * the index for that package refreshed. Returns undefined when a retry would not help.
+ */
+export function refreshedArgs(args: string[], stderr: string): string[] | undefined {
+	if (!/there is no version of|no solution found/i.test(stderr)) return undefined;
+	const i = args.indexOf("--from");
+	if (args[0] !== "tool" || args[1] !== "run" || i < 0 || args.includes("--refresh-package")) return undefined;
+	const pkg = args[i + 1].split(/[=<>!~]/)[0];
+	return [...args.slice(0, 2), "--refresh-package", pkg, ...args.slice(2)];
+}
+
 export function starbuckEnabled(cfg: Pick<SubsubConfig, "addons">): boolean {
 	return (cfg.addons ?? []).includes("starbuck");
 }

package/src/doctor.ts

@@ -20,6 +20,7 @@ import {
 	starbuckCommand,
 	starbuckEnabled,
 	type SubsubConfig,
+	refreshedArgs,
 } from "./config.ts";
 import { isObsidianVault, LEGACY_SETTINGS_DIR, SETTINGS_FILES, settingsFile } from "./layout.ts";
 import { profileSpec } from "./profiles.ts";
@@ -92,7 +93,10 @@ export function runChecks(
 
 	const cmd = serverCommand(cfg, "zotero-local-mcp", ["--check"], env);
 	const local = cmd.args.includes("--directory");
-	const res = run(cmd.command, cmd.args, { ...env, ...(cfg.envFile ? { ZOTERO_MCP_ENV: cfg.envFile } : {}) });
+	const serverEnv = { ...env, ...(cfg.envFile ? { ZOTERO_MCP_ENV: cfg.envFile } : {}) };
+	let res = run(cmd.command, cmd.args, serverEnv);
+	const retry = res.status !== 0 ? refreshedArgs(cmd.args, res.stderr) : undefined;
+	if (retry) res = run(cmd.command, retry, serverEnv);
 	let st: Record<string, any> | undefined;
 	try {
 		st = JSON.parse(res.stdout);
@@ -123,7 +127,8 @@ export function runChecks(
 	);
 	const v = st.vocabulary ?? {};
 	if (v.loaded === false || !v.tags) {
-		out.push({ name: "Tag list", ok: false, detail: v.path ? `cannot read ${v.path}` : "not set", fix: "Type subsub init: it creates a starter tag list." });
+		const path = v.path && v.path !== "None" ? v.path : undefined; // the server writes Python's None when unset
+		out.push({ name: "Tag list", ok: false, detail: path ? `cannot read ${path}` : "not set", fix: "Type subsub init: it creates a starter tag list." });
 	} else {
 		const noTopics = Array.isArray(v.facets) && !v.facets.includes("topic");
 		out.push({
@@ -149,7 +154,7 @@ export function runChecks(
 	out.push(
 		hasLogin(agentDir)
 			? { name: "Model login", ok: true, detail: Object.keys(cfg.models).length ? Object.entries(cfg.models).map(([m, id]) => `${m} ${id}`).join(", ") : "pi's default model" }
-			: { name: "Model login", ok: false, detail: "no model provider yet", fix: "Type subsub, then /login." },
+			: { name: "Model login", ok: false, detail: "no model provider yet", fix: "Open Sub-Sub (subsub web), select the model button and save an API key. In the terminal: type subsub, then /login." },
 	);
 	return out;
 }

package/src/init.ts

@@ -152,9 +152,10 @@ export async function runInit(
 	// Without questions (--yes), an existing folder stays exactly as it is.
 	const keepAsIs = Boolean(flags.yes) && !flags.folder && !flags.notes && oldFolder !== undefined;
 	const folderDefault = flags.folder ?? flags.notes ?? (oldFolder ? (keepAsIs ? oldFolder : subsubFolder(oldFolder)) : join(home, "Documents", FOLDER_NAME));
-	const answer = expand((await io.ask("Sub-Sub folder (or an Obsidian vault)", folderDefault)).trim() || folderDefault, home);
-	const notes = keepAsIs && answer === oldFolder ? answer : subsubFolder(answer);
+	const answer = expand(cleanPath(await io.ask("Sub-Sub folder (or an Obsidian vault)", folderDefault)) || folderDefault, home);
+	let notes = keepAsIs && answer === oldFolder ? answer : subsubFolder(answer);
 	if (notes !== answer) io.say(`That is an Obsidian vault. Sub-Sub will use ${notes}.`);
+	else if (notes !== folderDefault) io.say(`Sub-Sub folder: ${notes}`);
 
 	// ---- files of the old layout
 	const from = oldFolder && existsSync(oldFolder) ? oldFolder : notes;
@@ -171,10 +172,16 @@ export async function runInit(
 			"Move them",
 			[
 				{ value: "yes", label: "Move them (recommended)" },
-				{ value: "no", label: from === notes ? "Leave them; Sub-Sub still reads them from Systems/" : "Leave them where they are" },
+				// In a new folder, files left behind would not be read: then "no" means keeping the old folder.
+				{ value: "no", label: from === notes ? "Leave them; Sub-Sub still reads them from Systems/" : flags.folder || flags.notes ? "Leave them where they are" : `Leave them, and keep using ${from}` },
 			],
 			flags.move ?? (flags.yes ? "no" : "yes"),
 		);
+		// A folder given on the command line (--folder, --notes) is a deliberate choice and stays.
+		if (move === "no" && from !== notes && !flags.folder && !flags.notes) {
+			notes = from;
+			io.say(`Sub-Sub keeps using ${notes}.`);
+		}
 	}
 
 	explain("Profile", "The profile sets how much Sub-Sub writes for you and which tools it offers. Change it at any time with /profile.");
@@ -207,7 +214,7 @@ export async function runInit(
 		);
 	}
 
-	explain("Contact email", "Unpaywall needs an email address to find open-access PDFs. Sub-Sub sends it only to Unpaywall, Crossref, OpenAlex and PubMed, as they ask.");
+	explain("Contact email", "Unpaywall needs an email address to find open-access PDFs. Sub-Sub sends it with its requests to PubMed, Europe PMC, OpenAlex, Crossref and Unpaywall, as they ask, and to nobody else.");
 	const email = (await io.ask("Email (optional)", flags.email ?? envValues.ZOTERO_CONTACT_EMAIL ?? "")).trim();
 
 	explain("Reference checks (Starbuck)", "An optional add-on for manuscripts: it checks that each cited work exists, matches its citation and was not retracted. Sub-Sub then has /verify.");
@@ -295,6 +302,7 @@ export async function runInit(
 	if (starbuck === "on") io.say(starbuckNote || "Reference checks: on. The first start downloads Starbuck.");
 	if (fmup) io.say("FMUP / U.Porto: the FMUP model service will come in a later version. Until then, connect a model provider yourself.");
 	io.say("Next: type subsub web to open Sub-Sub in your browser (or subsub for the terminal). Connect a model provider with the model button (or /login in the terminal). To check the setup, type subsub doctor.");
+	if (tags === "any-field") io.say('The tag list has no topics yet. Before you tag, ask Sub-Sub: "propose topics for my tag list".');
 	return { configFile, envFile, notes, created, moved: move === "yes" ? moves.length : 0, zotero };
 }
 
@@ -348,7 +356,10 @@ function terminalIO(): InitIO & { close(): void } {
 
 export async function initMain(args: string[], env: NodeJS.ProcessEnv = process.env): Promise<number> {
 	const flags = parseFlags(args);
-	if (!process.stdin.isTTY) flags.yes ??= "true";
+	if (!process.stdin.isTTY && flags.yes === undefined) {
+		flags.yes = "true";
+		console.log("Not a terminal: Sub-Sub takes the default answers (as with --yes).");
+	}
 	const io = flags.yes ? defaultsIO((l) => console.log(l)) : terminalIO();
 	try {
 		await runInit(io, flags, env, { prepareStarbuck: (cfg) => {
@@ -364,3 +375,11 @@ export async function initMain(args: string[], env: NodeJS.ProcessEnv = process.
 		(io as { close?: () => void }).close?.();
 	}
 }
+
+/** A path as typed, dragged from Finder (spaces escaped) or copied from Explorer (in quotes). */
+export function cleanPath(raw: string): string {
+	let p = raw.trim();
+	if (p.length > 1 && (p[0] === '"' || p[0] === "'") && p.at(-1) === p[0]) return p.slice(1, -1);
+	if (process.platform !== "win32") p = p.replace(/\\([ '"()&])/g, "$1");
+	return p;
+}

package/src/paths.ts

@@ -45,9 +45,14 @@ export function realish(abs: string): string {
 	return tail.length ? join(real, ...tail) : real;
 }
 
+/** macOS and Windows file systems ignore case: ~/.SSH is ~/.ssh. */
+const FOLD_CASE = process.platform === "darwin" || process.platform === "win32";
+
 export function within(child: string, parent: string | undefined): boolean {
 	if (!parent) return false;
-	const rel = relative(parent, child);
+	// NFC: a name typed with combining accents is the same file as the precomposed one.
+	const [c, p] = [child.normalize("NFC"), parent.normalize("NFC")];
+	const rel = FOLD_CASE ? relative(p.toLowerCase(), c.toLowerCase()) : relative(p, c);
 	return rel === "" || (!rel.startsWith(`..${sep}`) && rel !== ".." && !isAbsolute(rel));
 }
 
@@ -92,6 +97,30 @@ export type PathVerdict = { ok: true } | { ok: false; why: string };
 export function judgePath(target: string, policy: PathPolicy): PathVerdict {
 	const hit = policy.protectedPaths.find((p) => within(target, p));
 	if (hit) return { ok: false, why: `it changes a protected file or folder (${hit})` };
-	if (policy.allowed.some((a) => within(target, a))) return { ok: true };
-	return { ok: false, why: "it is outside the vault and the working folder" };
+	const root = policy.allowed.find((a) => within(target, a));
+	if (!root) return { ok: false, why: "it is outside the vault and the working folder" };
+	// Notes never live in hidden folders; .git/hooks, .obsidian/plugins or .vscode can run code.
+	// Only the part inside the folder counts, so a vault under ~/.something still works.
+	const hidden = relative(root, target).split(/[\\/]/).find((part) => part.startsWith(".") && part !== "." && part !== "..");
+	if (hidden) return { ok: false, why: `it is in a hidden folder or file (${hidden})` };
+	return { ok: true };
+}
+
+/** Files with keys and passwords: the model may not read them, even when you ask. */
+export function secretPaths(): string[] {
+	const home = realish(homedir());
+	return [
+		join(home, ".subsub", "agent", "auth.json"),
+		...[process.env.SUBSUB_AGENT_DIR, process.env.PI_CODING_AGENT_DIR].filter((d): d is string => !!d).map((d) => join(realish(d.replace(/^~(?=$|[\\/])/, home)), "auth.json")),
+		join(home, ".pi", "agent", "auth.json"),
+		join(home, ".config", "zotero-local-mcp", "env"),
+		join(home, ".ssh"),
+		join(home, ".aws"),
+		join(home, ".netrc"),
+	];
+}
+
+/** True if reading `target` would read a secret; for grep, also a folder that holds one. */
+export function isSecret(target: string, recursive = false, envFile?: string): boolean {
+	return [...secretPaths(), ...(envFile ? [realish(envFile)] : [])].some((p) => within(target, p) || (recursive && within(p, target)));
 }

package/src/preview.ts

@@ -12,6 +12,12 @@ function s(v: unknown, n = 90): string {
 	return t.length > n ? `${t.slice(0, n - 3)}...` : t;
 }
 
+/** What will be written: shown whole up to a large limit, and the rest is counted, never silently cut. */
+function whole(v: unknown, n = 3000): string {
+	const t = typeof v === "string" ? v : JSON.stringify(v);
+	return t.length > n ? `${t.slice(0, n)} [${t.length - n} more characters not shown]` : t;
+}
+
 function list(rows: string[], total?: number): string[] {
 	const out = rows.slice(0, MAX_LINES);
 	const rest = (total ?? rows.length) - out.length;
@@ -27,7 +33,7 @@ function describeChange(c: Obj): string {
 		if (["key", "item", "added", "removed", "tags_after"].includes(k)) continue;
 		if (v && typeof v === "object" && "after" in (v as Obj)) {
 			const b = (v as Obj).before;
-			parts.push(`${k}: ${s(b || "(empty)", 40)} -> ${s((v as Obj).after, 60)}`);
+			parts.push(`${k}: ${s(b || "(empty)", 40)} -> ${whole((v as Obj).after)}`);
 		}
 	}
 	return `${s(c.item ?? c.key, 60)}: ${parts.join("; ") || "(change)"}`;
@@ -83,7 +89,7 @@ export function formatPreview(tool: string, preview: unknown): string {
 	}
 	if (tool.endsWith("attach_note") || tool.endsWith("create_note")) {
 		if (p.item || p.parent) lines.push(`Note on: ${s(p.item ?? p.parent, 90)}`);
-		if (p.summary || p.note_preview) lines.push(s(p.summary ?? p.note_preview, 600));
+		if (p.summary || p.note_preview) lines.push(whole(p.summary ?? p.note_preview));
 		if (p.link) lines.push(`Link: ${p.link}`);
 	}
 	const skipped = p.skipped as Obj | undefined;

package/src/prompt.ts

@@ -60,6 +60,12 @@ export function roleText(mode: Mode, cfg?: Pick<SubsubConfig, "userName" | "abou
 export function systemAddition(mode: Mode, cfg: SubsubConfig, cwd: string): string {
 	const user = who(cfg);
 	const parts = [`# Sub-Sub: ${mode === "librarian" ? "Librarian" : "Researcher"} mode`, roleText(mode, cfg)];
+	if (cfg.vault) {
+		parts.push(
+			"# The Sub-Sub folder",
+			`The Sub-Sub folder is ${cfg.vault}. Folder names in these instructions (Inbox/, Literature/, Syntheses/, Research/, Zotero/) are inside it. Write notes there with absolute paths, even when the working folder is somewhere else.`,
+		);
+	}
 	const shared = readIf(cfg.sharedRules);
 	if (shared) {
 		parts.push(

package/src/shortcut.ts

@@ -81,7 +81,7 @@ export function desktopEntry(p: ShortcutPlan): string {
 		"[Desktop Entry]",
 		"Type=Application",
 		"Name=Sub-Sub",
-		"Comment=Zotero librarian and research assistant",
+		"Comment=Research assistant for your Zotero library",
 		`Exec=${desktopQuote(p.node)} ${desktopQuote(p.bin)} web`,
 		`Path=${p.home}`,
 		`Icon=${join(p.packageDir, "assets", "icon.png")}`,
@@ -103,7 +103,7 @@ export function windowsScript(p: ShortcutPlan): string {
 		`  $s.Arguments = ${psQuote(`"${p.bin}" web`)}`,
 		`  $s.WorkingDirectory = ${psQuote(p.home)}`,
 		`  $s.IconLocation = ${psQuote(join(p.packageDir, "assets", "icon.ico"))}`,
-		"  $s.Description = 'Sub-Sub: Zotero librarian and research assistant'",
+		"  $s.Description = 'Sub-Sub: research assistant for your Zotero library'",
 		"  $s.WindowStyle = 7",
 		"  $s.Save()",
 		"  Write-Output (Join-Path $dir 'Sub-Sub.lnk')",

package/src/subsub.ts

@@ -1,5 +1,5 @@
 /**
- * Sub-Sub: a Zotero librarian and research assistant for pi.
+ * Sub-Sub: a research assistant for pi that works from your own Zotero library.
  *
  * - Two modes: the Librarian manages the library (Zotero tools only); the
  *   Researcher does the same and also searches PubMed, Europe PMC and OpenAlex
@@ -39,7 +39,7 @@ import {
 import { profileList, profileSpec, promptBlocked } from "./profiles.ts";
 import { coerceArgs, loosenArrays, resolvePathArgs } from "./args.ts";
 import { applyEdits, checkLiteratureNote } from "./notes.ts";
-import { buildPolicy, judgePath, normalizeToolPath, realish, within } from "./paths.ts";
+import { buildPolicy, isSecret, judgePath, normalizeToolPath, realish, within } from "./paths.ts";
 import { describeArgs, formatPreview } from "./preview.ts";
 import { headerLines, type LibraryState, paintPreview, QUOTES, type Scheme, schemeFromAnsi, themeName } from "./look.ts";
 import { systemAddition } from "./prompt.ts";
@@ -130,6 +130,7 @@ export async function createSubsub(pi: ExtensionAPI, deps: SubsubDeps = {}): Pro
 	if (deps.bridge) registerTools(deps.bridge);
 
 	pi.registerFlag("librarian", { description: "Start Sub-Sub in the Librarian mode", type: "boolean", default: false });
+	pi.registerFlag("researcher", { description: "Start Sub-Sub in the Researcher mode", type: "boolean", default: false });
 
 	let mode: Mode = cfg.defaultMode;
 	const benchRun = Boolean(process.env.SUBSUB_BENCH_OUT);
@@ -252,11 +253,12 @@ export async function createSubsub(pi: ExtensionAPI, deps: SubsubDeps = {}): Pro
 		emitWeb();
 	}
 
-	async function applyMode(ctx: ExtensionContext, next: Mode, remember: boolean): Promise<void> {
+	/** Set the mode's tools and, unless `switchModel` is false, the mode's model. */
+	async function applyMode(ctx: ExtensionContext, next: Mode, remember: boolean, switchModel = true): Promise<void> {
 		mode = next;
 		pi.setActiveTools(toolsFor(mode, registered(), toolOpts()));
 		const spec = cfg.models[mode];
-		if (spec) {
+		if (spec && switchModel) {
 			const i = spec.indexOf("/");
 			const model = i > 0 ? ctx.modelRegistry.find(spec.slice(0, i), spec.slice(i + 1)) : undefined;
 			const ok = model ? await pi.setModel(model) : false;
@@ -274,20 +276,28 @@ export async function createSubsub(pi: ExtensionAPI, deps: SubsubDeps = {}): Pro
 			registerTools(b);
 		}
 		let restored: Mode | undefined;
-		for (const e of ctx.sessionManager.getBranch() as Array<{ customType?: string; data?: { mode?: unknown } }>) {
+		// A resumed conversation keeps its model. pi records a model for every new session too,
+		// so only a session with messages counts (pi's own test for an existing session).
+		let hasModel = false;
+		let hasMessages = false;
+		for (const e of ctx.sessionManager.getBranch() as Array<{ type?: string; customType?: string; data?: { mode?: unknown } }>) {
 			const m = e.customType === MODE_ENTRY ? e.data?.mode : undefined;
 			if (m === "librarian" || m === "researcher") restored = m;
+			if (e.type === "model_change") hasModel = true;
+			if (e.type === "message") hasMessages = true;
 		}
+		const modelChosen = hasModel && hasMessages;
 		// Judge light or dark before Sub-Sub changes the theme.
 		if (lookOn(ctx)) scheme ??= schemeFromAnsi(ctx.ui.theme.getFgAnsi("text"), ctx.ui.theme.name);
 		applyTheme(ctx);
-		await applyMode(ctx, restored ?? (pi.getFlag("librarian") ? "librarian" : cfg.defaultMode), false);
+		await applyMode(ctx, restored ?? (pi.getFlag("librarian") ? "librarian" : pi.getFlag("researcher") ? "researcher" : cfg.defaultMode), false, !modelChosen);
 		if (lookOn(ctx)) {
 			setHeader(ctx);
 			void refreshLibrary();
 		} else if (webView) {
 			void refreshLibrary();
 		}
+		if (!ctx.model && !webView) ctx.ui.notify("Sub-Sub: no model is connected yet. Type /login and select a provider (or use the model button in subsub web).", "warning");
 		for (const [name, err] of Object.entries(bridge.errors)) {
 			ctx.ui.notify(`Sub-Sub: the ${name} server did not start: ${err.split("\n")[0]}`, "error");
 		}
@@ -300,11 +310,29 @@ export async function createSubsub(pi: ExtensionAPI, deps: SubsubDeps = {}): Pro
 		await b?.close();
 	});
 
+	/** Prompt commands for the Researcher; the Librarian has the library ones (tag-batch, clean-tags, import-queue). */
+	const RESEARCH_PROMPTS = ["lit", "compare", "lit-note", "synthesis", "gaps", "manuscript", "verify", "review", "alert", "request-copy", "digest"];
+
+	// /tree moves to another branch: take that branch's mode (pi restores its model itself).
+	pi.on("session_tree", async (_event, ctx) => {
+		let m: Mode | undefined;
+		for (const e of ctx.sessionManager.getBranch() as Array<{ customType?: string; data?: { mode?: unknown } }>) {
+			const x = e.customType === MODE_ENTRY ? e.data?.mode : undefined;
+			if (x === "librarian" || x === "researcher") m = x;
+		}
+		if (m && m !== mode) await applyMode(ctx, m, false, false);
+	});
+
 	pi.on("model_select", async (_event, ctx) => status(ctx));
 
 	// Prompt commands that the profile does not run (/lit for Reader, /review for Reader and Scholar).
 	// The input event comes before pi expands a prompt template.
 	pi.on("input", async (event, ctx) => {
+		const cmd = /^\/([\w-]+)(?:\s|$)/.exec(event.text.trim())?.[1];
+		if (mode === "librarian" && cmd && RESEARCH_PROMPTS.includes(cmd)) {
+			ctx.ui.notify(`Sub-Sub: /${cmd} is part of the Researcher. Switch with /researcher.`, "warning");
+			return { action: "handled" };
+		}
 		const why = promptBlocked(event.text, profile);
 		if (!why) return { action: "continue" };
 		ctx.ui.notify(`Sub-Sub: ${why}`, "warning");
@@ -333,6 +361,10 @@ export async function createSubsub(pi: ExtensionAPI, deps: SubsubDeps = {}): Pro
 				return { block: true, reason: why };
 			}
 		}
+		// grep, find and ls search the working folder when no path is given.
+		if (["read", "grep", "find", "ls"].includes(name) && isSecret(normalizeToolPath(typeof input.path === "string" ? input.path : ".", ctx.cwd), name === "grep", cfg.envFile)) {
+			return { block: true, reason: "That file holds keys or passwords. Sub-Sub does not read it." };
+		}
 		if (name.startsWith("verify_")) return verifyGate(name, input, ctx);
 		const kind = benchOut && name === "scholar_queue_imports" ? "confirm" : gateKind(name, input);
 		if (!kind) return undefined;
@@ -351,6 +383,11 @@ export async function createSubsub(pi: ExtensionAPI, deps: SubsubDeps = {}): Pro
 			return { block: true, reason: `Library changes need ${user}'s approval, which needs an interactive session.` };
 		}
 		if (kind === "confirm") {
+			// A file the tool writes is judged like any file write: protected files stay protected.
+			if (typeof input.output_path === "string") {
+				const verdict = judgePath(normalizeToolPath(input.output_path, ctx.cwd), buildPolicy({ vault: cfg.vault, cwd: ctx.cwd, serverDir: cfg.serverDir, packageDir: PACKAGE_DIR }));
+				if (!verdict.ok && /protected|hidden/.test(verdict.why)) return { block: true, reason: `Sub-Sub does not write there: ${verdict.why}.` };
+			}
 			const ok = await ctx.ui.confirm(`Sub-Sub: run ${name}?`, describeArgs(input));
 			return ok ? undefined : { block: true, reason: `${user} did not approve. Ask what to change.` };
 		}
@@ -364,11 +401,25 @@ export async function createSubsub(pi: ExtensionAPI, deps: SubsubDeps = {}): Pro
 			return { block: true, reason: `Preview failed: ${(err as Error).message}` };
 		}
 		if (preview.isError) return { block: true, reason: preview.text };
-		const ok = await ctx.ui.confirm(
-			`Sub-Sub: apply ${name.replace(/^(zotero|scholar)_/, "")}?`,
-			paintFor(ctx)(formatPreview(name, preview.data ?? preview.text)),
-		);
-		return ok ? undefined : { block: true, reason: `${user} did not approve this change. Ask what to change; do not retry the same call.` };
+		const title = `Sub-Sub: apply ${name.replace(/^(zotero|scholar)_/, "")}?`;
+		let shown = formatPreview(name, preview.data ?? preview.text);
+		// The dialog may stay open for minutes. Before applying, compute the preview again: if the
+		// library changed meanwhile (an edit in Zotero, new items), show the new preview instead.
+		for (let round = 0; round < 3; round++) {
+			const ok = await ctx.ui.confirm(round ? `${title} (the library changed; this is the new preview)` : title, paintFor(ctx)(shown));
+			if (!ok) return { block: true, reason: `${user} did not approve this change. Ask what to change; do not retry the same call.` };
+			let again;
+			try {
+				again = await current().call(name, { ...input, dry_run: true }, ctx.signal);
+			} catch (err) {
+				return { block: true, reason: `Preview failed: ${(err as Error).message}` };
+			}
+			if (again.isError) return { block: true, reason: again.text };
+			const now = formatPreview(name, again.data ?? again.text);
+			if (now === shown) return undefined;
+			shown = now;
+		}
+		return { block: true, reason: "The library kept changing while the preview was open. Nothing was applied; try again." };
 	});
 
 	/** A literature note (front matter with a citekey) must state its evidence; see notes.ts. */
@@ -476,7 +527,7 @@ export async function createSubsub(pi: ExtensionAPI, deps: SubsubDeps = {}): Pro
 			} catch (err) {
 				saved = ` Not saved: ${(err as Error).message}`;
 			}
-			await applyMode(ctx, mode, false);
+			await applyMode(ctx, mode, false, false);
 			ctx.ui.notify(`Sub-Sub: ${profileSpec(profile).label} profile (${profileSpec(profile).summary}).${saved}`, "info");
 		},
 	});