pi-studio 0.9.52 → 0.9.54

package/index.ts

@@ -23,6 +23,12 @@ import {
 	transformStudioMarkdownOutsideFences,
 } from "./shared/studio-annotation-scanner.js";
 import { stripStudioMarkdownHtmlComments } from "./shared/studio-markdown-html-comments.js";
+import { createStudioFileWatcher } from "./shared/studio-file-watcher.js";
+import {
+	readStudioDiskFileSnapshot,
+	saveStudioDiskFileAs,
+	saveStudioDiskFileIfRevision,
+} from "./shared/studio-disk-revisions.js";
 import { normalizeStudioMarkdownSmartFences } from "./shared/studio-markdown-fences.js";
 import {
 	extractStandaloneLatexDefinitionsFromMarkdown,
@@ -32,6 +38,7 @@ import { escapeStudioPdfLatexTextFragment } from "./shared/studio-pdf-escape.js"
 import { parseStudioLocalPreviewPage, parseStudioPdfLaunchTarget } from "./shared/studio-local-preview-path.js";
 import { resolveStudioPdfResourceFile } from "./shared/studio-pdf-resource.js";
 import { createStudioPandocHtmlResourceFlagResolver } from "./shared/studio-pandoc-resource-flag.js";
+import { createStudioResourceGrantRegistry } from "./shared/studio-resource-grants.js";
 import { prepareStudioLatexForPandoc } from "./shared/studio-latex-pandoc-compat.js";
 import { isStudioCmuxSession, openStudioUrlInBrowser } from "./shared/studio-browser-launcher.js";
 import { buildStudioReplTmuxStartArgs } from "./shared/studio-repl-tmux.js";
@@ -75,6 +82,7 @@ import {
 } from "./shared/studio-side-question.js";
 import {
 	STUDIO_SIDE_CONTEXT_MAX_OUTPUT_CHARS,
+	assertStudioSideQuestionRootStable,
 	formatStudioSideQuestionContextMap,
 	listStudioSideQuestionContext,
 	readStudioSideQuestionContextText,
@@ -312,11 +320,24 @@ interface InitialStudioDocument {
 	path?: string;
 	draftId?: string;
 	resourceDir?: string;
+	diskRevision?: string;
+	watchFile?: boolean;
 }
 
+type StudioDiskWriteResult =
+	| { ok: true; path: string; revision: string; size: number }
+	| {
+		ok: false;
+		conflict?: boolean;
+		reason?: string;
+		path?: string;
+		currentRevision?: string | null;
+		message: string;
+	};
+
 interface StudioLaunchSelection {
 	document: InitialStudioDocument;
-	kind: "document" | "pdf-preview";
+	kind: "document" | "pdf-preview" | "watched-preview";
 	mode?: StudioUiMode;
 	transient?: boolean;
 	skipWorkspaceRestore?: boolean;
@@ -451,6 +472,8 @@ interface StudioSideQuestionToolDescriptor {
 	gateway: boolean;
 }
 
+type StudioSideQuestionContextRootInput = Pick<StudioSideQuestionContextInput, "sourcePath" | "resourceDir" | "gatherScope" | "contextPath">;
+
 interface StudioSideQuestionContextInput {
 	focusKind: StudioSideQuestionFocusKind;
 	focusLabel: string;
@@ -715,12 +738,17 @@ interface SaveAsRequestMessage {
 	requestId: string;
 	path: string;
 	content: string;
+	overwrite?: boolean;
+	expectedRevision?: string;
 }
 
 interface SaveOverRequestMessage {
 	type: "save_over_request";
 	requestId: string;
+	path: string;
 	content: string;
+	expectedRevision?: string;
+	force?: boolean;
 }
 
 interface RefreshFromDiskRequestMessage {
@@ -729,6 +757,12 @@ interface RefreshFromDiskRequestMessage {
 	path?: string;
 }
 
+interface WatchFileSubscribeMessage {
+	type: "watch_file_subscribe";
+	path: string;
+	revision?: string;
+}
+
 interface SendToEditorRequestMessage {
 	type: "send_to_editor_request";
 	requestId: string;
@@ -817,6 +851,7 @@ type IncomingStudioMessage =
 	| SaveAsRequestMessage
 	| SaveOverRequestMessage
 	| RefreshFromDiskRequestMessage
+	| WatchFileSubscribeMessage
 	| SendToEditorRequestMessage
 	| GetFromEditorRequestMessage
 	| QuartoPreviewCheckRequestMessage
@@ -829,6 +864,7 @@ type IncomingStudioMessage =
 
 const REQUEST_TIMEOUT_MS = 5 * 60 * 1000;
 const PREVIEW_RENDER_MAX_CHARS = 400_000;
+const STUDIO_WATCHED_FILE_MAX_CLIENTS = 16;
 const STUDIO_COMPLETION_MAX_TEXT_CHARS = 250_000;
 const STUDIO_COMPLETION_MAX_CONTEXT_CHARS = 12_000;
 const STUDIO_COMPLETION_PREFIX_CHARS = 12_000;
@@ -2459,8 +2495,8 @@ function resolveStudioPath(pathArg: string, cwd: string): { ok: true; resolved:
 	return { ok: true, resolved, label: normalized };
 }
 
-function readStudioFile(pathArg: string, cwd: string):
-	| { ok: true; text: string; label: string; resolvedPath: string }
+function readStudioFile(pathArg: string, cwd: string, options?: { requireCanonicalPath?: boolean }):
+	| { ok: true; text: string; label: string; resolvedPath: string; diskRevision: string }
 	| { ok: false; message: string } {
 	const resolved = resolveStudioPath(pathArg, cwd);
 	if (resolved.ok === false) {
@@ -2468,39 +2504,41 @@ function readStudioFile(pathArg: string, cwd: string):
 	}
 
 	try {
-		const stats = statSync(resolved.resolved);
-		if (!stats.isFile()) {
-			return { ok: false, message: `Path is not a file: ${resolved.label}` };
-		}
-	} catch (error) {
-		return {
-			ok: false,
-			message: `Could not access file: ${resolved.label} (${error instanceof Error ? error.message : String(error)})`,
-		};
-	}
-
-	try {
-		// Read raw bytes first to detect binary content before UTF-8 decode
-		const buf = readFileSync(resolved.resolved);
-		// Heuristic: check the first 8KB for binary indicators
-		const sample = buf.subarray(0, 8192);
+		const snapshot = readStudioDiskFileSnapshot(resolved.resolved);
+		if (options?.requireCanonicalPath) {
+			const requestedPath = resolve(resolved.resolved);
+			const canonicalPath = resolve(snapshot.path);
+			const pathsMatch = process.platform === "win32"
+				? requestedPath.toLowerCase() === canonicalPath.toLowerCase()
+				: requestedPath === canonicalPath;
+			if (!pathsMatch) {
+				return { ok: false, message: `Could not read file: ${resolved.label} (the file location now resolves somewhere else)` };
+			}
+		}
+		// Heuristic: check the first 8KB for binary indicators.
+		const sample = snapshot.buffer.subarray(0, 8192);
 		let nulCount = 0;
 		let controlCount = 0;
 		for (let i = 0; i < sample.length; i++) {
 			const b = sample[i];
 			if (b === 0x00) nulCount++;
-			// Control chars excluding tab (0x09), newline (0x0A), carriage return (0x0D)
+			// Control chars excluding tab (0x09), newline (0x0A), carriage return (0x0D).
 			else if (b < 0x08 || (b > 0x0D && b < 0x20 && b !== 0x1B)) controlCount++;
 		}
 		if (nulCount > 0 || (sample.length > 0 && controlCount / sample.length > 0.1)) {
 			return { ok: false, message: `File appears to be binary: ${resolved.label}` };
 		}
-		const text = buf.toString("utf-8");
-		return { ok: true, text, label: resolved.label, resolvedPath: resolved.resolved };
+		return {
+			ok: true,
+			text: snapshot.buffer.toString("utf-8"),
+			label: resolved.label,
+			resolvedPath: snapshot.path,
+			diskRevision: snapshot.revision,
+		};
 	} catch (error) {
 		return {
 			ok: false,
-			message: `Failed to read file: ${resolved.label} (${error instanceof Error ? error.message : String(error)})`,
+			message: `Could not read file: ${resolved.label} (${error instanceof Error ? error.message : String(error)})`,
 		};
 	}
 }
@@ -2860,23 +2898,18 @@ function writeStudioPreviewExportFile(path: string | null, data: Buffer): { file
 	}
 }
 
-function writeStudioFile(pathArg: string, cwd: string, content: string):
-	| { ok: true; label: string; resolvedPath: string }
-	| { ok: false; message: string } {
-	const resolved = resolveStudioPath(pathArg, cwd);
-	if (resolved.ok === false) {
-		return { ok: false, message: resolved.message };
-	}
-
-	try {
-		writeFileSync(resolved.resolved, content, "utf-8");
-		return { ok: true, label: resolved.label, resolvedPath: resolved.resolved };
-	} catch (error) {
-		return {
-			ok: false,
-			message: `Failed to write file: ${resolved.label} (${error instanceof Error ? error.message : String(error)})`,
-		};
-	}
+function writeStudioFile(pathArg: string, cwd: string, content: string, overwrite = false, expectedRevision?: string):
+	| { ok: true; label: string; resolvedPath: string; diskRevision: string }
+	| { ok: false; conflict?: boolean; reason?: string; path?: string; currentRevision?: string | null; message: string } {
+	const normalizedLabel = normalizePathInput(pathArg);
+	const result = saveStudioDiskFileAs({ path: pathArg, cwd, content, overwrite, expectedRevision }) as StudioDiskWriteResult;
+	if (result.ok === false) return result;
+	return {
+		ok: true,
+		label: normalizedLabel || basename(result.path),
+		resolvedPath: result.path,
+		diskRevision: result.revision,
+	};
 }
 
 function writeStudioSideQuestionMarkdownFile(
@@ -3103,12 +3136,13 @@ function buildStudioCompanionLabel(_label: string | undefined): string {
 }
 
 const STUDIO_HTML_PREVIEW_RESOURCE_MAX_BYTES = 25 * 1024 * 1024;
-const STUDIO_HTML_PREVIEW_IMAGE_MIME_BY_EXT = new Map<string, string>([
+const STUDIO_HTML_PREVIEW_MEDIA_MIME_BY_EXT = new Map<string, string>([
 	[".png", "image/png"],
 	[".jpg", "image/jpeg"],
 	[".jpeg", "image/jpeg"],
 	[".gif", "image/gif"],
 	[".webp", "image/webp"],
+	[".pdf", "application/pdf"],
 ]);
 const STUDIO_LOCAL_LINK_TEXT_EXTENSIONS = new Set([
 	".md", ".markdown", ".mdx", ".qmd", ".txt", ".tex", ".latex", ".rst", ".adoc",
@@ -3133,9 +3167,37 @@ const STUDIO_FILE_BROWSER_IGNORED_DIRS = new Set([
 
 type StudioLocalPreviewResourceKind = "pdf" | "text" | "image" | "office" | "other";
 type StudioFileBrowserSortMode = "name" | "mtime-desc" | "mtime-asc" | "size-desc" | "size-asc";
+type StudioResourceGrantRegistry = ReturnType<typeof createStudioResourceGrantRegistry>;
+
+class StudioResourceGrantRequiredError extends Error {
+	readonly code = "studio-resource-grant-required";
+	readonly filePath: string;
+	readonly directoryPath: string;
+	readonly resourceKind: StudioLocalPreviewResourceKind;
+
+	constructor(filePath: string, resourceKind: StudioLocalPreviewResourceKind) {
+		super("This local resource is outside the locations currently available to Studio.");
+		this.name = "StudioResourceGrantRequiredError";
+		this.filePath = filePath;
+		this.directoryPath = dirname(filePath);
+		this.resourceKind = resourceKind;
+	}
+}
+
+class StudioDirectoryGrantRequiredError extends Error {
+	readonly code = "studio-resource-directory-grant-required";
+	readonly directoryPath: string;
+
+	constructor(directoryPath: string) {
+		super("This folder is not available to the current Studio session.");
+		this.name = "StudioDirectoryGrantRequiredError";
+		this.directoryPath = directoryPath;
+	}
+}
 
 interface StudioLocalPreviewResource {
 	filePath: string;
+	referencePath: string;
 	label: string;
 	extension: string;
 	kind: StudioLocalPreviewResourceKind;
@@ -3154,6 +3216,11 @@ interface StudioFileBrowserEntry {
 	hidden: boolean;
 }
 
+interface StudioFileBrowserLocation {
+	path: string;
+	label: string;
+}
+
 function normalizeStudioFileBrowserSortMode(sort: string | null | undefined): StudioFileBrowserSortMode {
 	const value = typeof sort === "string" ? sort.trim().toLowerCase() : "";
 	if (value === "mtime-desc" || value === "modified-desc" || value === "newest") return "mtime-desc";
@@ -3177,25 +3244,34 @@ function compareStudioFileBrowserEntries(a: StudioFileBrowserEntry, b: StudioFil
 	return compareStudioFileBrowserEntryNames(a, b);
 }
 
-function resolveStudioPdfResourcePath(pdfPath: string | undefined, sourcePath: string | undefined, resourceDir: string | undefined, fallbackCwd: string): string {
+function resolveStudioPdfResourcePath(
+	pdfPath: string | undefined,
+	sourcePath: string | undefined,
+	resourceDir: string | undefined,
+	fallbackCwd: string,
+	resourceGrants?: StudioResourceGrantRegistry,
+): string {
 	const rawPath = typeof pdfPath === "string" ? pdfPath.trim() : "";
 	if (!rawPath) throw new Error("Missing PDF path.");
 	if (/\0/.test(rawPath)) throw new Error("Invalid PDF path.");
-	if (/^[a-z][a-z0-9+.-]*:/i.test(rawPath) && !/^[a-z]:[\\/]/i.test(rawPath)) {
+	if (/^[a-z][a-z0-9+.-]*:/i.test(rawPath) && !/^file:/i.test(rawPath) && !/^[a-z]:[\\/]/i.test(rawPath)) {
 		throw new Error("Only local PDF paths are supported.");
 	}
 
 	const context = resolveStudioPreviewResourceContext(sourcePath, resourceDir, fallbackCwd);
-	const cleanedPath = decodeStudioHtmlPreviewResourcePath(stripStudioHtmlPreviewResourceUrlSuffix(rawPath));
+	const cleanedPath = decodeStudioLocalPreviewResourceReference(rawPath);
 	const expandedPath = recoverLikelyDroppedLeadingSlashPath(expandHome(cleanedPath));
 	const candidate = isAbsolute(expandedPath) ? expandedPath : resolve(context.baseDir, expandedPath);
 	if (extname(candidate).toLowerCase() !== ".pdf") throw new Error("Only .pdf files can be embedded.");
 
-	const boundaryReal = realpathSync(context.boundaryDir);
 	const candidateReal = realpathSync(candidate);
-	const rel = relative(boundaryReal, candidateReal);
-	if (rel.startsWith("..") || isAbsolute(rel)) {
-		throw new Error("PDF path must stay within the current Studio resource directory.");
+	if (resourceGrants) {
+		if (!resourceGrants.allows(candidateReal)) throw new StudioResourceGrantRequiredError(candidateReal, "pdf");
+	} else {
+		const boundaryReal = realpathSync(context.boundaryDir);
+		if (!isPathInsideOrEqualDirectory(candidateReal, boundaryReal)) {
+			throw new Error("PDF path must stay within the current Studio resource directory.");
+		}
 	}
 
 	const stat = statSync(candidateReal);
@@ -3216,6 +3292,22 @@ function decodeStudioHtmlPreviewResourcePath(resourcePath: string): string {
 	}
 }
 
+function decodeStudioLocalPreviewResourceReference(resourcePath: string): string {
+	const raw = String(resourcePath ?? "").trim();
+	if (!/^file:/i.test(raw)) {
+		return decodeStudioHtmlPreviewResourcePath(stripStudioHtmlPreviewResourceUrlSuffix(raw));
+	}
+	try {
+		const url = new URL(raw);
+		if (url.protocol !== "file:") throw new Error("Not a file URL.");
+		url.hash = "";
+		url.search = "";
+		return fileURLToPath(url);
+	} catch {
+		throw new Error("Invalid local file URL.");
+	}
+}
+
 function getStudioLocalPreviewResourceKind(extension: string, filePathOrName?: string): StudioLocalPreviewResourceKind {
 	const ext = extension.toLowerCase();
 	const name = basename(String(filePathOrName || "")).toLowerCase();
@@ -3231,60 +3323,128 @@ function resolveStudioLocalPreviewResourcePath(
 	sourcePath: string | undefined,
 	resourceDir: string | undefined,
 	fallbackCwd: string,
+	resourceGrants?: StudioResourceGrantRegistry,
 ): StudioLocalPreviewResource {
 	const rawPath = typeof resourcePath === "string" ? resourcePath.trim() : "";
 	if (!rawPath) throw new Error("Missing local resource path.");
 	if (/\0/.test(rawPath)) throw new Error("Invalid local resource path.");
 	if (/^\/\//.test(rawPath)) throw new Error("Network resources are not local Studio resources.");
-	if (/^[a-z][a-z0-9+.-]*:/i.test(rawPath) && !/^[a-z]:[\\/]/i.test(rawPath)) {
-		throw new Error("Only local relative resources are supported.");
+	if (/^[a-z][a-z0-9+.-]*:/i.test(rawPath) && !/^file:/i.test(rawPath) && !/^[a-z]:[\\/]/i.test(rawPath)) {
+		throw new Error("Only local file paths and file URLs are supported.");
 	}
 
 	const context = resolveStudioPreviewResourceContext(sourcePath, resourceDir, fallbackCwd);
-	const cleanedPath = decodeStudioHtmlPreviewResourcePath(stripStudioHtmlPreviewResourceUrlSuffix(rawPath));
+	const cleanedPath = decodeStudioLocalPreviewResourceReference(rawPath);
 	if (!cleanedPath || cleanedPath.startsWith("#")) throw new Error("Missing local resource path.");
 	const expandedPath = recoverLikelyDroppedLeadingSlashPath(expandHome(cleanedPath));
 	const candidate = isAbsolute(expandedPath) ? expandedPath : resolve(context.baseDir, expandedPath);
 	const extension = extname(candidate).toLowerCase();
-	const boundaryReal = realpathSync(context.boundaryDir);
 	const candidateReal = realpathSync(candidate);
-	const rel = relative(boundaryReal, candidateReal);
-	if (rel.startsWith("..") || isAbsolute(rel)) {
-		throw new Error("Local resource path must stay within the current Studio resource directory.");
-	}
-
 	const stat = statSync(candidateReal);
 	if (!stat.isFile()) throw new Error("Local resource path does not refer to a file.");
+
+	const kind = getStudioLocalPreviewResourceKind(extension, candidateReal);
+	const matchingGrant = resourceGrants?.findGrant(candidateReal);
+	let effectiveDirectory: string;
+	if (resourceGrants) {
+		if (!matchingGrant) throw new StudioResourceGrantRequiredError(candidateReal, kind);
+		effectiveDirectory = matchingGrant.kind === "directory" ? matchingGrant.path : dirname(candidateReal);
+	} else {
+		const boundaryReal = realpathSync(context.boundaryDir);
+		if (!isPathInsideOrEqualDirectory(candidateReal, boundaryReal)) {
+			throw new Error("Local resource path must stay within the current Studio resource directory.");
+		}
+		effectiveDirectory = boundaryReal;
+	}
+	const relativePath = relative(effectiveDirectory, candidateReal);
+	const useRelativeReference = isPathInsideOrEqualDirectory(candidateReal, effectiveDirectory);
 	return {
 		filePath: candidateReal,
-		label: rel && rel !== "" ? rel : basename(candidateReal),
+		referencePath: useRelativeReference ? (relativePath || basename(candidateReal)) : candidateReal,
+		label: useRelativeReference ? (relativePath || basename(candidateReal)) : basename(candidateReal),
 		extension,
-		kind: getStudioLocalPreviewResourceKind(extension, candidateReal),
+		kind,
 		page: parseStudioLocalPreviewPage(rawPath),
-		resourceDir: boundaryReal,
+		resourceDir: effectiveDirectory,
 	};
 }
 
+function getStudioFileBrowserGrantLocations(resourceGrants: StudioResourceGrantRegistry): {
+	locations: StudioFileBrowserLocation[];
+	exactFiles: StudioFileBrowserEntry[];
+} {
+	const grants = resourceGrants.snapshot();
+	const directoryPaths: string[] = [];
+	for (const grant of grants) {
+		if (grant.kind !== "directory") continue;
+		try {
+			const currentReal = realpathSync(grant.path);
+			if (currentReal === grant.path && statSync(currentReal).isDirectory()) directoryPaths.push(currentReal);
+		} catch {
+			// Missing or replaced directory grants are omitted rather than followed.
+		}
+	}
+	const locations = directoryPaths
+		.map((path) => ({ path, label: basename(path) || path }))
+		.sort((a, b) => a.path.localeCompare(b.path));
+	const exactFiles: StudioFileBrowserEntry[] = [];
+	for (const grant of grants) {
+		if (grant.kind !== "file") continue;
+		if (directoryPaths.some((directoryPath) => isPathInsideOrEqualDirectory(grant.path, directoryPath))) continue;
+		try {
+			const currentReal = realpathSync(grant.path);
+			if (currentReal !== grant.path) continue;
+			const stat = statSync(currentReal);
+			if (!stat.isFile()) continue;
+			const name = basename(currentReal);
+			const extension = extname(currentReal).toLowerCase();
+			exactFiles.push({
+				name,
+				path: currentReal,
+				type: "file",
+				extension,
+				kind: getStudioLocalPreviewResourceKind(extension, currentReal),
+				size: stat.size,
+				mtimeMs: stat.mtimeMs,
+				hidden: name.startsWith("."),
+			});
+		} catch {
+			// Missing exact-file grants remain bounded but are omitted from the Files view.
+		}
+	}
+	exactFiles.sort((a, b) => compareStudioFileBrowserEntries(a, b, "name"));
+	return { locations, exactFiles };
+}
+
 function resolveStudioFileBrowserDirectory(
 	dirPath: string | undefined,
+	rootPath: string | undefined,
 	sourcePath: string | undefined,
 	resourceDir: string | undefined,
 	fallbackCwd: string,
+	resourceGrants: StudioResourceGrantRegistry,
 ): { rootDir: string; currentDir: string; relativeDir: string; parentDir: string | null } {
 	const context = resolveStudioPreviewResourceContext(sourcePath, resourceDir, fallbackCwd);
-	const rootReal = realpathSync(context.boundaryDir);
+	const rawRoot = typeof rootPath === "string" ? rootPath.trim() : "";
+	const expandedRoot = recoverLikelyDroppedLeadingSlashPath(expandHome(rawRoot || context.boundaryDir));
+	const requestedRoot = isAbsolute(expandedRoot) ? expandedRoot : resolve(fallbackCwd, expandedRoot);
+	const requestedRootReal = realpathSync(requestedRoot);
+	if (!statSync(requestedRootReal).isDirectory()) throw new Error("File browser root does not refer to a directory.");
+	const matchingRootGrant = resourceGrants.findGrant(requestedRootReal, { cwd: fallbackCwd });
+	if (!matchingRootGrant || matchingRootGrant.kind !== "directory") {
+		throw new StudioDirectoryGrantRequiredError(requestedRootReal);
+	}
+	const rootReal = matchingRootGrant.path;
 	const rawDir = typeof dirPath === "string" ? dirPath.trim() : "";
-	const baseDir = context.baseDir;
+	const expandedDir = recoverLikelyDroppedLeadingSlashPath(expandHome(rawDir));
 	const requested = rawDir
-		? (isAbsolute(recoverLikelyDroppedLeadingSlashPath(expandHome(rawDir)))
-			? recoverLikelyDroppedLeadingSlashPath(expandHome(rawDir))
-			: resolve(baseDir, recoverLikelyDroppedLeadingSlashPath(expandHome(rawDir))))
-		: baseDir;
+		? (isAbsolute(expandedDir) ? expandedDir : resolve(rootReal, expandedDir))
+		: rootReal;
 	const currentReal = realpathSync(requested);
 	const currentStat = statSync(currentReal);
 	if (!currentStat.isDirectory()) throw new Error("File browser path does not refer to a directory.");
 	if (!isPathInsideOrEqualDirectory(currentReal, rootReal)) {
-		throw new Error("File browser path must stay within the current Studio resource directory.");
+		throw new Error("File browser path must stay within an allowed Studio folder.");
 	}
 	const parent = dirname(currentReal);
 	const parentDir = parent !== currentReal && isPathInsideOrEqualDirectory(parent, rootReal) ? parent : null;
@@ -3294,12 +3454,14 @@ function resolveStudioFileBrowserDirectory(
 
 function listStudioFileBrowserDirectory(
 	dirPath: string | undefined,
+	rootPath: string | undefined,
 	sourcePath: string | undefined,
 	resourceDir: string | undefined,
 	fallbackCwd: string,
+	resourceGrants: StudioResourceGrantRegistry,
 	sortMode?: string | null,
-): { rootDir: string; currentDir: string; relativeDir: string; parentDir: string | null; entries: StudioFileBrowserEntry[]; omitted: number; omittedIgnored: number; sort: StudioFileBrowserSortMode } {
-	const context = resolveStudioFileBrowserDirectory(dirPath, sourcePath, resourceDir, fallbackCwd);
+): { rootDir: string; currentDir: string; relativeDir: string; parentDir: string | null; entries: StudioFileBrowserEntry[]; exactFiles: StudioFileBrowserEntry[]; locations: StudioFileBrowserLocation[]; omitted: number; omittedIgnored: number; sort: StudioFileBrowserSortMode } {
+	const context = resolveStudioFileBrowserDirectory(dirPath, rootPath, sourcePath, resourceDir, fallbackCwd, resourceGrants);
 	const sort = normalizeStudioFileBrowserSortMode(sortMode);
 	const entries: StudioFileBrowserEntry[] = [];
 	let omitted = 0;
@@ -3342,7 +3504,7 @@ function listStudioFileBrowserDirectory(
 	entries.sort((a, b) => compareStudioFileBrowserEntries(a, b, sort));
 	const limitedEntries = entries.slice(0, STUDIO_FILE_BROWSER_MAX_ENTRIES);
 	omitted += Math.max(0, entries.length - limitedEntries.length);
-	return { ...context, entries: limitedEntries, omitted, omittedIgnored, sort };
+	return { ...context, ...getStudioFileBrowserGrantLocations(resourceGrants), entries: limitedEntries, omitted, omittedIgnored, sort };
 }
 
 function resolveStudioHtmlPreviewResourcePath(
@@ -3350,27 +3512,32 @@ function resolveStudioHtmlPreviewResourcePath(
 	sourcePath: string | undefined,
 	resourceDir: string | undefined,
 	fallbackCwd: string,
+	resourceGrants?: StudioResourceGrantRegistry,
 ): { filePath: string; mimeType: string } {
 	const rawPath = typeof resourcePath === "string" ? resourcePath.trim() : "";
 	if (!rawPath) throw new Error("Missing HTML preview resource path.");
 	if (/\0/.test(rawPath)) throw new Error("Invalid HTML preview resource path.");
-	if (/^[a-z][a-z0-9+.-]*:/i.test(rawPath) && !/^[a-z]:[\\/]/i.test(rawPath)) {
+	if (/^[a-z][a-z0-9+.-]*:/i.test(rawPath) && !/^file:/i.test(rawPath) && !/^[a-z]:[\\/]/i.test(rawPath)) {
 		throw new Error("Only local HTML preview resources are supported.");
 	}
 
 	const context = resolveStudioPreviewResourceContext(sourcePath, resourceDir, fallbackCwd);
-	const cleanedPath = decodeStudioHtmlPreviewResourcePath(stripStudioHtmlPreviewResourceUrlSuffix(rawPath));
+	const cleanedPath = decodeStudioLocalPreviewResourceReference(rawPath);
 	const expandedPath = recoverLikelyDroppedLeadingSlashPath(expandHome(cleanedPath));
 	const candidate = isAbsolute(expandedPath) ? expandedPath : resolve(context.baseDir, expandedPath);
 	const ext = extname(candidate).toLowerCase();
-	const mimeType = STUDIO_HTML_PREVIEW_IMAGE_MIME_BY_EXT.get(ext);
-	if (!mimeType) throw new Error("Only local PNG, JPEG, GIF, and WebP images can be embedded in HTML previews.");
+	const mimeType = STUDIO_HTML_PREVIEW_MEDIA_MIME_BY_EXT.get(ext);
+	if (!mimeType) throw new Error("Only local PNG, JPEG, GIF, WebP, and PDF media can be embedded in Studio previews.");
 
-	const boundaryReal = realpathSync(context.boundaryDir);
 	const candidateReal = realpathSync(candidate);
-	const rel = relative(boundaryReal, candidateReal);
-	if (rel.startsWith("..") || isAbsolute(rel)) {
-		throw new Error("HTML preview resource path must stay within the current Studio resource directory.");
+	const kind: StudioLocalPreviewResourceKind = ext === ".pdf" ? "pdf" : "image";
+	if (resourceGrants) {
+		if (!resourceGrants.allows(candidateReal)) throw new StudioResourceGrantRequiredError(candidateReal, kind);
+	} else {
+		const boundaryReal = realpathSync(context.boundaryDir);
+		if (!isPathInsideOrEqualDirectory(candidateReal, boundaryReal)) {
+			throw new Error("HTML preview resource path must stay within the current Studio resource directory.");
+		}
 	}
 
 	const stat = statSync(candidateReal);
@@ -3381,6 +3548,39 @@ function resolveStudioHtmlPreviewResourcePath(
 	return { filePath: candidateReal, mimeType };
 }
 
+function resolveStudioAuthorizedPreviewRenderContext(
+	sourcePath: string | undefined,
+	resourceDir: string | undefined,
+	fallbackCwd: string,
+	resourceGrants: StudioResourceGrantRegistry,
+): { resourcePath?: string; sourcePath?: string } {
+	const context = resolveStudioPreviewResourceContext(sourcePath, resourceDir, fallbackCwd);
+	let resourcePath: string;
+	try {
+		resourcePath = realpathSync(context.baseDir);
+		if (!statSync(resourcePath).isDirectory()) return {};
+	} catch {
+		return {};
+	}
+	const directoryGrant = resourceGrants.findGrant(resourcePath, { cwd: fallbackCwd });
+	if (!directoryGrant || directoryGrant.kind !== "directory") return {};
+
+	const rawSource = typeof sourcePath === "string" ? sourcePath.trim() : "";
+	if (!rawSource) return { resourcePath };
+	try {
+		const expandedSource = recoverLikelyDroppedLeadingSlashPath(expandHome(rawSource));
+		const requestedSource = isAbsolute(expandedSource) ? expandedSource : resolve(fallbackCwd, expandedSource);
+		const canonicalSource = realpathSync(requestedSource);
+		const sourceGrant = resourceGrants.findGrant(dirname(canonicalSource), { cwd: fallbackCwd });
+		if (statSync(canonicalSource).isFile() && sourceGrant?.kind === "directory") {
+			return { resourcePath, sourcePath: canonicalSource };
+		}
+	} catch {
+		// The submitted Markdown can still render without file-adjacent metadata.
+	}
+	return { resourcePath };
+}
+
 function resolveStudioPandocWorkingDir(baseDir: string | undefined): string | undefined {
 	const normalized = typeof baseDir === "string" ? baseDir.trim() : "";
 	if (!normalized) return undefined;
@@ -5191,11 +5391,34 @@ function hasStudioYamlHeaderIncludes(markdown: string): boolean {
 	return /^\s*header-includes\s*:/im.test(split.frontMatter);
 }
 
+function encodeStudioLocalFileUrlForPandoc(resourceUrl: string): string {
+	try {
+		const url = new URL(resourceUrl);
+		if (url.protocol !== "file:" || (url.hostname && url.hostname !== "localhost")) return resourceUrl;
+		const suffix = `${url.search}${url.hash}`;
+		url.search = "";
+		url.hash = "";
+		const localPath = fileURLToPath(url);
+		return encodeURI(localPath).replace(/\?/g, "%3F").replace(/#/g, "%23") + suffix;
+	} catch {
+		return resourceUrl;
+	}
+}
+
+function normalizeStudioMarkdownFileUrlDestinationsForPandoc(markdown: string): string {
+	return transformStudioMarkdownOutsideFences(markdown, (segment: string) => (
+		segment.replace(/(\]\(\s*<?)(file:\/\/(?:localhost)?\/[^<>\s)]+)/gi, (_match, prefix: string, resourceUrl: string) => (
+			`${prefix}${encodeStudioLocalFileUrlForPandoc(resourceUrl)}`
+		))
+	));
+}
+
 function prepareStudioMarkdownForPandoc(markdown: string, options?: { preserveLiteralLatexCommands?: boolean }): string {
 	const shouldPreserveLiteralLatexCommands = options?.preserveLiteralLatexCommands !== false;
 	return mapStudioMarkdownBodyPreservingYamlFrontMatter(markdown, (body) => {
 		const normalizedFences = normalizeStudioMarkdownSmartFences(body);
-		const normalizedMath = normalizeMathDelimiters(normalizedFences);
+		const normalizedFileUrls = normalizeStudioMarkdownFileUrlDestinationsForPandoc(normalizedFences);
+		const normalizedMath = normalizeMathDelimiters(normalizedFileUrls);
 		const latexReady = shouldPreserveLiteralLatexCommands
 			? preserveLiteralLatexCommandsInMarkdown(normalizedMath)
 			: normalizedMath;
@@ -6413,7 +6636,13 @@ function preprocessStudioLatexFootnotemarksForPreview(latex: string): string {
 	});
 }
 
-async function renderStudioMarkdownWithPandoc(markdown: string, isLatex?: boolean, resourcePath?: string, sourcePath?: string): Promise<string> {
+async function renderStudioMarkdownWithPandoc(
+	markdown: string,
+	isLatex?: boolean,
+	resourcePath?: string,
+	sourcePath?: string,
+	options?: { embedResources?: boolean },
+): Promise<string> {
 	const pandocCommand = process.env.PANDOC_PATH?.trim() || "pandoc";
 	const pandocWorkingDir = resolveStudioPandocWorkingDir(resourcePath)
 		?? resolveStudioPandocWorkingDir(sourcePath ? dirname(sourcePath) : undefined);
@@ -6451,7 +6680,9 @@ async function renderStudioMarkdownWithPandoc(markdown: string, isLatex?: boolea
 		await mkdir(htmlTemplateDir, { recursive: true });
 		const htmlTemplatePath = join(htmlTemplateDir, "template.html");
 		await writeFile(htmlTemplatePath, STUDIO_PANDOC_HTML_FRAGMENT_TEMPLATE, "utf-8");
-		if (resourcePath) args.push(await resolveStudioPandocHtmlResourceFlag(pandocCommand));
+		if (resourcePath && options?.embedResources !== false) {
+			args.push(await resolveStudioPandocHtmlResourceFlag(pandocCommand));
+		}
 		args.push("--standalone", `--template=${htmlTemplatePath}`);
 	}
 	const normalizedMarkdown = isLatex
@@ -7599,6 +7830,29 @@ function respondStudioPendingError(res: ServerResponse, status: number, text: st
 	res.end(text);
 }
 
+function respondStudioResourceGrantRequiredJson(res: ServerResponse, error: StudioResourceGrantRequiredError): void {
+	respondJson(res, 403, {
+		ok: false,
+		code: error.code,
+		error: error.message,
+		path: error.filePath,
+		directoryPath: error.directoryPath,
+		label: basename(error.filePath),
+		resourceKind: error.resourceKind,
+	});
+}
+
+function respondStudioDirectoryGrantRequiredJson(res: ServerResponse, error: StudioDirectoryGrantRequiredError): void {
+	respondJson(res, 403, {
+		ok: false,
+		code: error.code,
+		error: error.message,
+		path: error.directoryPath,
+		directoryPath: error.directoryPath,
+		label: basename(error.directoryPath) || error.directoryPath,
+	});
+}
+
 function respondPdfFile(req: IncomingMessage, res: ServerResponse, filePath: string): void {
 	const method = (req.method ?? "GET").toUpperCase();
 	if (method !== "GET" && method !== "HEAD") {
@@ -7661,7 +7915,7 @@ function sanitizeStudioPreviewBlockLine(value: string): string {
 
 function buildStudioLocalResourcePreviewDocument(resource: StudioLocalPreviewResource, options?: { watchPdf?: boolean }): InitialStudioDocument {
 	const label = basename(resource.filePath) || resource.label || "local preview";
-	const resourcePath = resource.label || basename(resource.filePath) || resource.filePath;
+	const resourcePath = resource.referencePath || resource.label || basename(resource.filePath) || resource.filePath;
 	const title = sanitizeStudioPreviewBlockLine(label);
 	let text = "";
 	if (resource.kind === "pdf") {
@@ -7720,7 +7974,14 @@ async function convertStudioOfficeDocumentToMarkdown(resource: StudioLocalPrevie
 	return { text: `${note}\n\n${body}\n`, label };
 }
 
-async function respondLocalPreviewLinkJson(req: IncomingMessage, res: ServerResponse, requestUrl: URL, resource: StudioLocalPreviewResource, serverState: StudioServerState): Promise<void> {
+async function respondLocalPreviewLinkJson(
+	req: IncomingMessage,
+	res: ServerResponse,
+	requestUrl: URL,
+	resource: StudioLocalPreviewResource,
+	serverState: StudioServerState,
+	resourceGrants?: StudioResourceGrantRegistry,
+): Promise<void> {
 	const method = (req.method ?? "GET").toUpperCase();
 	if (method !== "GET" && method !== "HEAD") {
 		res.setHeader("Allow", "GET, HEAD");
@@ -7729,6 +7990,13 @@ async function respondLocalPreviewLinkJson(req: IncomingMessage, res: ServerResp
 	}
 
 	const action = (requestUrl.searchParams.get("action") ?? "resolve").trim().toLowerCase();
+	const originDocId = (requestUrl.searchParams.get("docId") ?? "").trim();
+	const originDocument = originDocId ? readTransientStudioDocument(originDocId) : null;
+	const originatesFromWatchedPreview = requestUrl.searchParams.get("watchedFile") === "1" || originDocument?.watchFile === true;
+	if (action === "document" && originatesFromWatchedPreview) {
+		respondJson(res, 409, { ok: false, error: "Open here is unavailable in a watched preview. Open a separate editable file tab instead." });
+		return;
+	}
 	const basePayload = {
 		ok: true,
 		kind: resource.kind,
@@ -7758,10 +8026,14 @@ async function respondLocalPreviewLinkJson(req: IncomingMessage, res: ServerResp
 		return;
 	}
 
-	if (action !== "document" && action !== "editor-url") {
+	if (action !== "document" && action !== "editor-url" && action !== "watch-url") {
 		respondJson(res, 400, { ok: false, error: "Unsupported local link action." });
 		return;
 	}
+	if (action === "watch-url" && resource.kind !== "text") {
+		respondJson(res, 400, { ok: false, error: "Follow-changes preview is available only for readable text files." });
+		return;
+	}
 	if (resource.kind !== "text" && resource.kind !== "office") {
 		respondJson(res, 400, { ok: false, error: "This local resource is not a document Studio can load into the editor." });
 		return;
@@ -7770,6 +8042,7 @@ async function respondLocalPreviewLinkJson(req: IncomingMessage, res: ServerResp
 	let document: InitialStudioDocument;
 	let responseText = "";
 	let converted = false;
+	let documentResourceDir = resource.resourceDir;
 	if (resource.kind === "office") {
 		let conversion: { text: string; label: string };
 		try {
@@ -7793,12 +8066,19 @@ async function respondLocalPreviewLinkJson(req: IncomingMessage, res: ServerResp
 			return;
 		}
 		responseText = file.text;
+		try {
+			const documentGrant = resourceGrants?.grantDocument(file.resolvedPath, { source: "document" });
+			if (documentGrant?.path) documentResourceDir = documentGrant.path;
+		} catch {
+			// The exact-file grant remains usable if the bounded registry cannot add the document directory.
+		}
 		document = {
 			text: file.text,
 			label: resource.label || file.label,
 			source: "file",
 			path: file.resolvedPath,
-			resourceDir: resource.resourceDir,
+			resourceDir: documentResourceDir,
+			diskRevision: file.diskRevision,
 		};
 	}
 	if (action === "document") {
@@ -7807,15 +8087,24 @@ async function respondLocalPreviewLinkJson(req: IncomingMessage, res: ServerResp
 			text: responseText,
 			label: document.label,
 			converted,
-			resourceDir: resource.resourceDir,
+			resourceDir: documentResourceDir,
+			diskRevision: document.diskRevision || null,
 		});
 		return;
 	}
 
+	if (action === "watch-url") {
+		if (responseText.length > PREVIEW_RENDER_MAX_CHARS) {
+			respondJson(res, 413, { ok: false, error: `Watched preview source exceeds ${PREVIEW_RENDER_MAX_CHARS.toLocaleString()} characters.` });
+			return;
+		}
+		document = { ...document, watchFile: true };
+	}
 	const docId = storeTransientStudioDocument(document);
 	respondJson(res, 200, {
 		...basePayload,
 		converted,
+		resourceDir: documentResourceDir,
 		relativeUrl: buildStudioRelativeUrl(serverState.token, "editor-only", document, docId, { skipWorkspaceRestore: true }),
 	});
 }
@@ -7906,7 +8195,61 @@ async function handleImportStudioFileCopyRequest(req: IncomingMessage, res: Serv
 	});
 }
 
-async function handleRevealLocalPreviewResourceRequest(req: IncomingMessage, res: ServerResponse, studioCwd: string): Promise<void> {
+async function handleStudioResourceGrantRequest(
+	req: IncomingMessage,
+	res: ServerResponse,
+	resourceGrants: StudioResourceGrantRegistry,
+	studioCwd: string,
+): Promise<void> {
+	const method = (req.method ?? "GET").toUpperCase();
+	if (method !== "POST") {
+		res.setHeader("Allow", "POST");
+		respondJson(res, 405, { ok: false, error: "Method not allowed. Use POST." });
+		return;
+	}
+
+	const rawBody = await readRequestBody(req, REQUEST_BODY_MAX_BYTES);
+	let payload: Record<string, unknown> = {};
+	try {
+		payload = rawBody ? JSON.parse(rawBody) : {};
+	} catch {
+		respondJson(res, 400, { ok: false, error: "Invalid JSON body." });
+		return;
+	}
+
+	const grantKind = payload.grantKind === "directory" ? "directory" : payload.grantKind === "file" ? "file" : "";
+	const path = typeof payload.path === "string" ? payload.path.trim() : "";
+	if (!grantKind || !path) {
+		respondJson(res, 400, { ok: false, error: "Choose an exact file or folder to allow." });
+		return;
+	}
+
+	try {
+		const grant = grantKind === "directory"
+			? resourceGrants.grantDirectory(path, { cwd: studioCwd, source: "explicit-directory" })
+			: resourceGrants.grantFile(path, { cwd: studioCwd, source: "explicit-file" });
+		respondJson(res, 200, {
+			ok: true,
+			grant,
+			resourceGrants: resourceGrants.snapshot(),
+			message: grantKind === "directory"
+				? `Allowed this folder for the current Studio session: ${grant.path}`
+				: `Allowed this file for the current Studio session: ${grant.path}`,
+		});
+	} catch (error) {
+		respondJson(res, 400, {
+			ok: false,
+			error: `Could not allow this ${grantKind}: ${error instanceof Error ? error.message : String(error)}`,
+		});
+	}
+}
+
+async function handleRevealLocalPreviewResourceRequest(
+	req: IncomingMessage,
+	res: ServerResponse,
+	studioCwd: string,
+	resourceGrants?: StudioResourceGrantRegistry,
+): Promise<void> {
 	const method = (req.method ?? "GET").toUpperCase();
 	if (method !== "POST") {
 		res.setHeader("Allow", "POST");
@@ -7929,6 +8272,7 @@ async function handleRevealLocalPreviewResourceRequest(req: IncomingMessage, res
 			typeof payload.sourcePath === "string" ? payload.sourcePath : undefined,
 			typeof payload.resourceDir === "string" ? payload.resourceDir : undefined,
 			studioCwd,
+			resourceGrants,
 		);
 		const result = revealStudioLocalFile(resource.filePath);
 		if (!result.ok) {
@@ -7937,11 +8281,20 @@ async function handleRevealLocalPreviewResourceRequest(req: IncomingMessage, res
 		}
 		respondJson(res, 200, { ok: true, message: result.message, path: resource.filePath, label: resource.label });
 	} catch (error) {
+		if (error instanceof StudioResourceGrantRequiredError) {
+			respondStudioResourceGrantRequiredJson(res, error);
+			return;
+		}
 		respondJson(res, 404, { ok: false, error: `Local resource unavailable: ${error instanceof Error ? error.message : String(error)}` });
 	}
 }
 
-async function handleOpenLocalPreviewResourceRequest(req: IncomingMessage, res: ServerResponse, studioCwd: string): Promise<void> {
+async function handleOpenLocalPreviewResourceRequest(
+	req: IncomingMessage,
+	res: ServerResponse,
+	studioCwd: string,
+	resourceGrants?: StudioResourceGrantRegistry,
+): Promise<void> {
 	const method = (req.method ?? "GET").toUpperCase();
 	if (method !== "POST") {
 		res.setHeader("Allow", "POST");
@@ -7968,6 +8321,7 @@ async function handleOpenLocalPreviewResourceRequest(req: IncomingMessage, res:
 			typeof payload.sourcePath === "string" ? payload.sourcePath : undefined,
 			typeof payload.resourceDir === "string" ? payload.resourceDir : undefined,
 			studioCwd,
+			resourceGrants,
 		);
 		if (resource.kind !== "pdf") {
 			respondJson(res, 400, { ok: false, error: "Only local PDF previews can be opened in the system PDF viewer." });
@@ -7981,6 +8335,10 @@ async function handleOpenLocalPreviewResourceRequest(req: IncomingMessage, res:
 			label: resource.label,
 		});
 	} catch (error) {
+		if (error instanceof StudioResourceGrantRequiredError) {
+			respondStudioResourceGrantRequiredJson(res, error);
+			return;
+		}
 		respondJson(res, 404, { ok: false, error: `Local PDF unavailable: ${error instanceof Error ? error.message : String(error)}` });
 	}
 }
@@ -8006,7 +8364,12 @@ function openPathInDefaultViewer(path: string): Promise<void> {
 	});
 }
 
-async function handleOpenStudioFileBrowserDirectoryRequest(req: IncomingMessage, res: ServerResponse, studioCwd: string): Promise<void> {
+async function handleOpenStudioFileBrowserDirectoryRequest(
+	req: IncomingMessage,
+	res: ServerResponse,
+	studioCwd: string,
+	resourceGrants: StudioResourceGrantRegistry,
+): Promise<void> {
 	const method = (req.method ?? "GET").toUpperCase();
 	if (method !== "POST") {
 		res.setHeader("Allow", "POST");
@@ -8030,13 +8393,25 @@ async function handleOpenStudioFileBrowserDirectoryRequest(req: IncomingMessage,
 	try {
 		const directory = resolveStudioFileBrowserDirectory(
 			typeof payload.dir === "string" ? payload.dir : undefined,
+			typeof payload.root === "string" ? payload.root : undefined,
 			typeof payload.sourcePath === "string" ? payload.sourcePath : undefined,
 			typeof payload.resourceDir === "string" ? payload.resourceDir : undefined,
 			studioCwd,
+			resourceGrants,
 		);
 		await openPathInDefaultViewer(directory.currentDir);
 		respondJson(res, 200, { ok: true, message: "Opened folder in file manager.", path: directory.currentDir, rootDir: directory.rootDir });
 	} catch (error) {
+		if (error instanceof StudioDirectoryGrantRequiredError) {
+			respondJson(res, 403, {
+				ok: false,
+				code: error.code,
+				error: error.message,
+				path: error.directoryPath,
+				directoryPath: error.directoryPath,
+			});
+			return;
+		}
 		respondJson(res, 404, { ok: false, error: `Could not open file-browser folder: ${error instanceof Error ? error.message : String(error)}` });
 	}
 }
@@ -8504,10 +8879,11 @@ async function searchStudioSideQuestionLocalContext(
 	const query = String(queryInput || "").trim();
 	if (!query) throw new Error("Local context search query is empty.");
 	if (query.length > 500) throw new Error("Local context search query is too long.");
+	const stableRoot = assertStudioSideQuestionRootStable(contextRoot);
 	const target = options.path
-		? resolveStudioSideQuestionPath(contextRoot, options.path, { directory: true }).path
-		: contextRoot;
-	const targetRelative = relative(contextRoot, target) || ".";
+		? resolveStudioSideQuestionPath(stableRoot, options.path, { directory: true }).path
+		: stableRoot;
+	const targetRelative = relative(stableRoot, target) || ".";
 	const maxResults = Math.max(1, Math.min(200, Math.floor(Number(options.maxResults) || 60)));
 	const args = [
 		"--fixed-strings",
@@ -8527,7 +8903,7 @@ async function searchStudioSideQuestionLocalContext(
 	args.push("--", query, targetRelative);
 	try {
 		const result = await runStudioSubprocess("rg", args, {
-			cwd: contextRoot,
+			cwd: stableRoot,
 			signal: options.signal,
 			timeoutMs: 20_000,
 			stdoutMaxBytes: 250_000,
@@ -8541,11 +8917,11 @@ async function searchStudioSideQuestionLocalContext(
 			if (!match) return [];
 			return [{ path: match[1].split("\\").join("/"), line: Number(match[2]), text: match[3].trim().slice(0, 1_000) }];
 		}).slice(0, maxResults);
-		return { root: contextRoot, query, results: matches, truncated: result.stdoutTruncated || matches.length >= maxResults };
+		return { root: stableRoot, query, results: matches, truncated: result.stdoutTruncated || matches.length >= maxResults };
 	} catch (error) {
 		if (options.signal?.aborted) throw new Error("Local context search was cancelled.");
 		if (!(error instanceof Error) || !error.message.includes("__PI_STUDIO_RG_NOT_FOUND__")) throw error;
-		return searchStudioSideQuestionContext(contextRoot, query, {
+		return searchStudioSideQuestionContext(stableRoot, query, {
 			path: targetRelative,
 			caseSensitive: options.caseSensitive,
 			maxResults,
@@ -8647,7 +9023,12 @@ function formatStudioSideQuestionGitSnapshotResult(
 	};
 }
 
-function createStudioSideQuestionTools(contextRoot: string, webEnabled: boolean, gitSnapshot: StudioSideQuestionGitSnapshot | null = null) {
+function createStudioSideQuestionTools(
+	contextRoot: string,
+	webEnabled: boolean,
+	gitSnapshot: StudioSideQuestionGitSnapshot | null = null,
+	assertContextRoot?: () => string,
+) {
 	const mapTool = defineTool({
 		name: "studio_context_map",
 		label: "Map local context",
@@ -8658,6 +9039,7 @@ function createStudioSideQuestionTools(contextRoot: string, webEnabled: boolean,
 		}),
 		async execute(_toolCallId, params, signal) {
 			if (signal?.aborted) throw new Error("Context map was cancelled.");
+			if (assertContextRoot) assertContextRoot();
 			const target = params.path
 				? resolveStudioSideQuestionPath(contextRoot, params.path, { directory: true }).path
 				: contextRoot;
@@ -8680,6 +9062,7 @@ function createStudioSideQuestionTools(contextRoot: string, webEnabled: boolean,
 		}),
 		async execute(_toolCallId, params, signal) {
 			if (signal?.aborted) throw new Error("Context read was cancelled.");
+			if (assertContextRoot) assertContextRoot();
 			const result = readStudioSideQuestionContextText(contextRoot, params.path, { offset: params.offset, limit: params.limit, maxChars: STUDIO_SIDE_CONTEXT_MAX_OUTPUT_CHARS });
 			const extractableResult = result as { path: string; relativePath: string; extension?: string };
 			const content: { text: string; startLine: number; endLine: number; totalLines: number; truncated: boolean } = result.requiresExtraction
@@ -8703,6 +9086,7 @@ function createStudioSideQuestionTools(contextRoot: string, webEnabled: boolean,
 			maxResults: Type.Optional(Type.Integer({ minimum: 1, maximum: 200 })),
 		}),
 		async execute(_toolCallId, params, signal) {
+			if (assertContextRoot) assertContextRoot();
 			const result = await searchStudioSideQuestionLocalContext(contextRoot, params.query, {
 				path: params.path,
 				caseSensitive: params.caseSensitive,
@@ -9621,21 +10005,35 @@ function parseIncomingMessage(data: RawData): IncomingStudioMessage | null {
 		msg.type === "save_as_request" &&
 		typeof msg.requestId === "string" &&
 		typeof msg.path === "string" &&
-		typeof msg.content === "string"
+		typeof msg.content === "string" &&
+		(msg.overwrite === undefined || typeof msg.overwrite === "boolean") &&
+		(msg.expectedRevision === undefined || typeof msg.expectedRevision === "string")
 	) {
 		return {
 			type: "save_as_request",
 			requestId: msg.requestId,
 			path: msg.path,
 			content: msg.content,
+			overwrite: msg.overwrite === true,
+			expectedRevision: typeof msg.expectedRevision === "string" ? msg.expectedRevision : undefined,
 		};
 	}
 
-	if (msg.type === "save_over_request" && typeof msg.requestId === "string" && typeof msg.content === "string") {
+	if (
+		msg.type === "save_over_request"
+		&& typeof msg.requestId === "string"
+		&& typeof msg.path === "string"
+		&& typeof msg.content === "string"
+		&& (msg.expectedRevision === undefined || typeof msg.expectedRevision === "string")
+		&& (msg.force === undefined || typeof msg.force === "boolean")
+	) {
 		return {
 			type: "save_over_request",
 			requestId: msg.requestId,
+			path: msg.path,
 			content: msg.content,
+			expectedRevision: typeof msg.expectedRevision === "string" ? msg.expectedRevision : undefined,
+			force: msg.force === true,
 		};
 	}
 
@@ -9651,6 +10049,19 @@ function parseIncomingMessage(data: RawData): IncomingStudioMessage | null {
 		};
 	}
 
+	if (
+		msg.type === "watch_file_subscribe"
+		&& typeof msg.path === "string"
+		&& msg.path.length <= 16_384
+		&& (msg.revision === undefined || typeof msg.revision === "string")
+	) {
+		return {
+			type: "watch_file_subscribe",
+			path: msg.path,
+			revision: typeof msg.revision === "string" ? msg.revision : undefined,
+		};
+	}
+
 	if (msg.type === "send_to_editor_request" && typeof msg.requestId === "string" && typeof msg.content === "string") {
 		return {
 			type: "send_to_editor_request",
@@ -10987,6 +11398,7 @@ function buildStudioRelativeUrl(
 	if (doc?.path) params.set("docPath", doc.path);
 	if (doc?.draftId) params.set("draftId", doc.draftId);
 	if (doc?.resourceDir) params.set("resourceDir", doc.resourceDir);
+	if (doc?.watchFile) params.set("watchFile", "1");
 	if (options?.skipWorkspaceRestore) params.set("skipWorkspaceRestore", "1");
 	if (options?.paneFocus) params.set("paneFocus", options.paneFocus);
 	return `/?${params.toString()}`;
@@ -11076,16 +11488,36 @@ function resolveRequestedStudioDocumentFromUrl(
 	const requestedLabel = (requestUrl.searchParams.get("docLabel") ?? "").trim();
 	const requestedDraftId = (requestUrl.searchParams.get("draftId") ?? "").trim();
 	const requestedResourceDir = (requestUrl.searchParams.get("resourceDir") ?? "").trim();
+	const requestedWatchFile = requestUrl.searchParams.get("watchFile") === "1";
 
 	if (requestedPath) {
 		const file = readStudioFile(requestedPath, studioCwd);
-		if (file.ok !== false) {
+		const requestedCanonicalTextPath = resolve(requestedPath);
+		const resolvedFilePath = file.ok !== false ? resolve(file.resolvedPath) : "";
+		const watchedPathStayedCanonical = !requestedWatchFile || (
+			process.platform === "win32"
+				? requestedCanonicalTextPath.toLowerCase() === resolvedFilePath.toLowerCase()
+				: requestedCanonicalTextPath === resolvedFilePath
+		);
+		if (file.ok !== false && watchedPathStayedCanonical) {
 			return {
 				text: file.text,
 				label: requestedLabel || file.label,
 				source: "file",
 				path: file.resolvedPath,
 				resourceDir: requestedResourceDir || fallback?.resourceDir || studioCwd,
+				diskRevision: file.diskRevision,
+				watchFile: requestedWatchFile,
+			};
+		}
+		if (requestedWatchFile && isAbsolute(requestedPath)) {
+			return {
+				text: fallback?.watchFile && fallback.path === requestedPath ? fallback.text : "",
+				label: requestedLabel || basename(requestedPath),
+				source: "file",
+				path: resolve(requestedPath),
+				resourceDir: requestedResourceDir || dirname(resolve(requestedPath)),
+				watchFile: true,
 			};
 		}
 	}
@@ -11370,6 +11802,8 @@ function buildStudioHtml(
 	const initialPath = escapeHtmlForInline(initialDocument?.path ?? "");
 	const initialDraftId = escapeHtmlForInline(initialDocument?.draftId ?? "");
 	const initialResourceDir = escapeHtmlForInline(initialDocument?.resourceDir ?? "");
+	const initialDiskRevision = escapeHtmlForInline(initialDocument?.diskRevision ?? "");
+	const initialWatchFile = initialDocument?.watchFile === true ? "1" : "0";
 	const initialModel = escapeHtmlForInline(initialModelLabel ?? "none");
 	const initialTerminal = escapeHtmlForInline(initialTerminalLabel ?? "unknown");
 	const initialTerminalDetailAttr = escapeHtmlForInline(initialTerminalDetail ?? initialTerminalLabel ?? "unknown");
@@ -11446,12 +11880,12 @@ ${cssVarsBlock}
   </style>
   <link rel="stylesheet" href="${stylesheetHref}" />
 </head>
-<body data-initial-source="${initialSource}" data-initial-label="${initialLabel}" data-initial-path="${initialPath}" data-initial-draft-id="${initialDraftId}" data-initial-resource-dir="${initialResourceDir}" data-model-label="${initialModel}" data-terminal-label="${initialTerminal}" data-terminal-detail="${initialTerminalDetailAttr}" data-theme-name="${initialTheme}" data-context-tokens="${initialContextTokens}" data-context-window="${initialContextWindow}" data-context-percent="${initialContextPercent}" data-studio-mode="${studioMode}" data-ssh-session="${initialSshSession}">
+<body data-initial-source="${initialSource}" data-initial-label="${initialLabel}" data-initial-path="${initialPath}" data-initial-draft-id="${initialDraftId}" data-initial-resource-dir="${initialResourceDir}" data-initial-disk-revision="${initialDiskRevision}" data-watched-file-preview="${initialWatchFile}" data-model-label="${initialModel}" data-terminal-label="${initialTerminal}" data-terminal-detail="${initialTerminalDetailAttr}" data-theme-name="${initialTheme}" data-context-tokens="${initialContextTokens}" data-context-window="${initialContextWindow}" data-context-percent="${initialContextPercent}" data-studio-mode="${studioMode}" data-ssh-session="${initialSshSession}">
   <header id="studioHeader">
     <h1><span class="app-logo" aria-hidden="true">π</span> Studio <span class="app-subtitle">${appSubtitle}</span></h1>
     <div class="controls">
-      <button id="saveAsBtn" type="button" title="Save editor content to a new file path. Cmd/Ctrl+S falls back here when no direct save path is available.">Save editor as…</button>
-      <button id="saveOverBtn" type="button" title="Overwrite current file with editor content. Shortcut: Cmd/Ctrl+S.">Save editor</button>
+      <button id="saveAsBtn" type="button" title="Save editor content to a new file path. Shortcut: Cmd/Ctrl+Shift+S; Cmd/Ctrl+S falls back here for new drafts.">Save editor as…</button>
+      <button id="saveOverBtn" type="button" title="Save only when the current file still matches Studio's disk revision. Shortcut: Cmd/Ctrl+S.">Save editor</button>
       <button id="refreshFromDiskBtn" type="button" title="Reload the current file-backed document from disk.">Refresh from disk</button>
       <button id="clearWorkspaceBtn" type="button" title="Clear editor text and reset this tab to a fresh blank draft. Saved files and responses are not changed.">Reset editor</button>
       <button id="importFileBtn" type="button" title="Import a file as an editable copy.">Import file copy…</button>
@@ -11671,7 +12105,7 @@ ${cssVarsBlock}
     <section id="rightPane">
       <div id="rightSectionHeader" class="section-header">
         <div class="section-header-main">
-          <select id="rightViewSelect" aria-label="Response view mode" title="Right pane view mode. F7 cycles when the right pane is active; Cmd/Ctrl+Alt+1–8 switches directly between all right-pane views. Cmd/Ctrl+Alt+P/E/W/Q keep their mnemonic Preview/Editor Preview/Working/Side questions shortcuts.">
+          <select id="rightViewSelect" aria-label="Response view mode" title="Right pane view mode. F7 cycles when the right pane is active; Cmd/Ctrl+Alt+1–8 switches directly between all right-pane views. Cmd/Ctrl+Alt+P/E/W/F/Q keep mnemonic shortcuts for Preview, Editor Preview, Working, Files, and Side questions.">
             <option value="markdown">Response (Raw)</option>
             <option value="preview" selected>Response (Preview)</option>
             <option value="editor-preview">Editor (Preview)</option>
@@ -11685,6 +12119,7 @@ ${cssVarsBlock}
         </div>
         <div class="section-header-actions">
           <button id="rightFocusBtn" class="pane-focus-btn" type="button" title="Show only the response pane. Shortcut: F10 or Cmd/Ctrl+Esc.">Focus pane</button>
+          <button id="watchedOpenEditableBtn" type="button" hidden title="Open this watched file in a separate editable Studio tab with conflict-safe saving.">Open editable tab</button>
           <span id="exportPreviewControls" class="export-preview-controls">
             <button id="exportPdfBtn" class="export-preview-trigger" type="button" aria-haspopup="menu" aria-expanded="false" title="Choose a format and export the current right-pane preview.">Export right preview</button>
             <div id="exportPreviewMenu" class="export-preview-menu" role="menu" hidden>
@@ -11780,6 +12215,7 @@ ${cssVarsBlock}
             <div><dt>Cmd/Ctrl+Alt+P</dt><dd>Switch the right pane directly to Response Preview; in editor-only views, Editor Preview</dd></div>
             <div><dt>Cmd/Ctrl+Alt+E</dt><dd>Switch the right pane directly to Editor Preview</dd></div>
             <div><dt>Cmd/Ctrl+Alt+W</dt><dd>Switch the right pane directly to Working</dd></div>
+            <div><dt>Cmd/Ctrl+Alt+F</dt><dd>Switch the right pane directly to Files</dd></div>
             <div><dt>Cmd/Ctrl+Alt+Q</dt><dd>Switch the right pane directly to Side questions</dd></div>
             <div><dt>F8</dt><dd>Focus editor text</dd></div>
             <div><dt>Shift+F8</dt><dd>Focus right-pane content</dd></div>
@@ -11801,7 +12237,8 @@ ${cssVarsBlock}
         <section class="shortcuts-group">
           <h3>Editor</h3>
           <dl>
-            <div><dt>Cmd/Ctrl+S</dt><dd>Save editor</dd></div>
+            <div><dt>Cmd/Ctrl+S</dt><dd>Save editor when the disk revision still matches</dd></div>
+            <div><dt>Cmd/Ctrl+Shift+S</dt><dd>Save editor as a new file</dd></div>
             <div class="shortcuts-full-only"><dt>Cmd/Ctrl+Enter</dt><dd>Run editor text, or queue steering during an active run</dd></div>
             <div><dt>Option/Alt+Tab or Cmd/Ctrl+Shift+Space</dt><dd>Suggest a completion at the editor cursor</dd></div>
             <div><dt>Tab</dt><dd>Insert a visible completion suggestion; otherwise indent selected editor text</dd></div>
@@ -11876,6 +12313,10 @@ ${cssVarsBlock}
 export default function (pi: ExtensionAPI) {
 	let serverState: StudioServerState | null = null;
 	const studioWorkspaceStateStore = createStudioWorkspaceStateStore();
+	const studioResourceGrantRegistry = createStudioResourceGrantRegistry();
+	const studioFileWatchers = new Map<WebSocket, ReturnType<typeof createStudioFileWatcher>>();
+	const studioWatchedClientPaths = new Map<WebSocket, string>();
+	const studioFileWatchSubscriptionGenerations = new Map<WebSocket, number>();
 	let activeRequest: ActiveStudioRequest | null = null;
 	let studioDirectRunChain: StudioDirectRunChain | null = null;
 	let queuedStudioDirectRequests: QueuedStudioDirectRequest[] = [];
@@ -11936,6 +12377,38 @@ export default function (pi: ExtensionAPI) {
 		actionRequestId: null,
 	};
 
+	const closeStudioFileWatcher = async (client: WebSocket): Promise<void> => {
+		const watcher = studioFileWatchers.get(client);
+		if (!watcher) return;
+		studioFileWatchers.delete(client);
+		await watcher.close().catch(() => undefined);
+	};
+
+	const closeAllStudioFileWatchers = async (): Promise<void> => {
+		const clients = Array.from(studioFileWatchers.keys());
+		await Promise.all(clients.map((client) => closeStudioFileWatcher(client)));
+		// Keep socket capability metadata until each socket is closed. Clearing it
+		// while an authenticated socket is still open would briefly make a watched
+		// preview look writable to the save handlers.
+	};
+
+	const recordStudioDocumentResourceGrants = (document: InitialStudioDocument, cwd = studioCwd) => {
+		if (document.path) {
+			try {
+				studioResourceGrantRegistry.grantDocument(document.path, { cwd, source: "document" });
+			} catch {
+				// A failed grant must not broaden access or prevent an otherwise valid launch.
+			}
+		}
+		if (document.resourceDir) {
+			try {
+				studioResourceGrantRegistry.grantDirectory(document.resourceDir, { cwd, source: "workspace" });
+			} catch {
+				// A failed workspace grant must not broaden access or prevent an otherwise valid launch.
+			}
+		}
+	};
+
 	const selectStudioReplSessionForTool = (params: { sessionName?: string; target?: string }): { session: StudioReplSessionInfo | null; error?: string; sessions: StudioReplSessionInfo[] } => {
 		const state = listStudioReplSessions();
 		const sessions = state.sessions;
@@ -13604,7 +14077,7 @@ export default function (pi: ExtensionAPI) {
 		await closeStudioSideQuestionRuntime(runtime);
 	};
 
-	const resolveStudioSideQuestionContextRoot = (context: StudioSideQuestionContextInput): string => {
+	const resolveStudioSideQuestionContextRoot = (context: StudioSideQuestionContextRootInput): string => {
 		if (context.gatherScope === "none") return "";
 		const sourcePath = resolveStudioQuizContextPath(context.sourcePath, studioCwd);
 		const resourceDir = resolveStudioQuizContextPath(context.resourceDir, studioCwd);
@@ -13627,6 +14100,51 @@ export default function (pi: ExtensionAPI) {
 		return resolveStudioSideQuestionRoot(root, studioCwd);
 	};
 
+	const assertStudioSideQuestionContextRootAuthorized = (contextRoot: string): string => {
+		if (!contextRoot) return "";
+		const stableRoot = assertStudioSideQuestionRootStable(contextRoot);
+		const grant = studioResourceGrantRegistry.findGrant(stableRoot, { cwd: studioCwd });
+		if (!grant || grant.kind !== "directory") throw new StudioDirectoryGrantRequiredError(stableRoot);
+		return stableRoot;
+	};
+
+	const resolveAuthorizedStudioSideQuestionContextRoot = (context: StudioSideQuestionContextRootInput): string => (
+		assertStudioSideQuestionContextRootAuthorized(resolveStudioSideQuestionContextRoot(context))
+	);
+
+	const handleStudioSideQuestionContextRootRequest = async (req: IncomingMessage, res: ServerResponse): Promise<void> => {
+		const method = (req.method ?? "GET").toUpperCase();
+		if (method !== "POST") {
+			res.setHeader("Allow", "POST");
+			respondJson(res, 405, { ok: false, error: "Method not allowed. Use POST." });
+			return;
+		}
+		const rawBody = await readRequestBody(req, REQUEST_BODY_MAX_BYTES);
+		let payload: Record<string, unknown> = {};
+		try {
+			payload = rawBody ? JSON.parse(rawBody) as Record<string, unknown> : {};
+		} catch {
+			respondJson(res, 400, { ok: false, error: "Invalid JSON body." });
+			return;
+		}
+		const context: StudioSideQuestionContextRootInput = {
+			gatherScope: normalizeStudioSideQuestionGatherScope(payload.gatherScope) as StudioSideQuestionGatherScope,
+			sourcePath: typeof payload.sourcePath === "string" ? payload.sourcePath.slice(0, 16_384) : undefined,
+			resourceDir: typeof payload.resourceDir === "string" ? payload.resourceDir.slice(0, 16_384) : undefined,
+			contextPath: typeof payload.contextPath === "string" ? payload.contextPath.slice(0, 16_384) : undefined,
+		};
+		try {
+			const contextRoot = resolveAuthorizedStudioSideQuestionContextRoot(context);
+			respondJson(res, 200, { ok: true, contextRoot, authorized: Boolean(contextRoot) });
+		} catch (error) {
+			if (error instanceof StudioDirectoryGrantRequiredError) {
+				respondStudioDirectoryGrantRequiredJson(res, error);
+				return;
+			}
+			respondJson(res, 400, { ok: false, error: `Side-question context unavailable: ${error instanceof Error ? error.message : String(error)}` });
+		}
+	};
+
 	const describeStudioSideQuestionActivity = (toolName: string, args: unknown): string => {
 		const value = args && typeof args === "object" ? args as Record<string, unknown> : {};
 		if (toolName === "studio_context_read") return `Reading ${String(value.path || "local context")}`;
@@ -13729,19 +14247,20 @@ export default function (pi: ExtensionAPI) {
 	const createStudioSideQuestionRuntime = async (context: StudioSideQuestionContextInput): Promise<StudioSideQuestionRuntime> => {
 		const ctx = lastCommandCtx;
 		if (!ctx) throw new Error("No active Studio command context is available. Re-open Studio and try again.");
-		const model = latestModelRequestCtx?.model ?? ctx.model;
-		if (!model) throw new Error("No active Pi model is available for side questions.");
-		await resolveStudioModelRequestAuth({ model, modelRegistry: ctx.modelRegistry }, model);
-		const contextRoot = resolveStudioSideQuestionContextRoot(context);
+		const contextRoot = resolveAuthorizedStudioSideQuestionContextRoot(context);
 		if (context.gitContext && context.gatherScope !== "repo") {
 			throw new Error("Git context requires Related files to be set to Repository.");
 		}
+		const model = latestModelRequestCtx?.model ?? ctx.model;
+		if (!model) throw new Error("No active Pi model is available for side questions.");
+		await resolveStudioModelRequestAuth({ model, modelRegistry: ctx.modelRegistry }, model);
 		const gitSnapshot = context.gitContext
 			? await captureStudioSideQuestionGitSnapshot(contextRoot, { runGit: runStudioSideQuestionGitCommand }) as StudioSideQuestionGitSnapshot
 			: null;
 		const webAvailable = Boolean(String(process.env.BRAVE_API_KEY || "").trim());
 		const webEnabled = context.webSearch && webAvailable;
-		const { tools, toolNames } = createStudioSideQuestionTools(contextRoot || studioCwd, webEnabled, gitSnapshot);
+		const assertContextRoot = contextRoot ? () => assertStudioSideQuestionContextRootAuthorized(contextRoot) : undefined;
+		const { tools, toolNames } = createStudioSideQuestionTools(contextRoot || studioCwd, webEnabled, gitSnapshot, assertContextRoot);
 		const localActiveToolNames = context.gatherScope === "none" ? (webEnabled ? ["studio_web_search"] : []) : toolNames;
 		const toolSelection = selectStudioSideQuestionTools(getStudioSideQuestionToolCatalog(), context.toolIds);
 		if (toolSelection.missing.length > 0) {
@@ -13924,6 +14443,7 @@ export default function (pi: ExtensionAPI) {
 		sendStudioSideQuestionState();
 		try {
 			const context = msg.context;
+			if (runtime.contextRoot) assertStudioSideQuestionContextRootAuthorized(runtime.contextRoot);
 			let prompt: string;
 			if (isFollowUp) {
 				prompt = buildStudioSideQuestionFollowUpPrompt(msg.question);
@@ -13992,6 +14512,92 @@ export default function (pi: ExtensionAPI) {
 		}
 	};
 
+	const subscribeStudioWatchedFile = async (client: WebSocket, msg: WatchFileSubscribeMessage): Promise<void> => {
+		const subscriptionGeneration = (studioFileWatchSubscriptionGenerations.get(client) ?? 0) + 1;
+		studioFileWatchSubscriptionGenerations.set(client, subscriptionGeneration);
+		await closeStudioFileWatcher(client);
+		if (studioFileWatchSubscriptionGenerations.get(client) !== subscriptionGeneration || client.readyState !== WebSocket.OPEN) return;
+		if (studioFileWatchers.size >= STUDIO_WATCHED_FILE_MAX_CLIENTS) {
+			sendToClient(client, {
+				type: "watched_file_error",
+				path: msg.path,
+				message: `Studio watched-file client limit reached (${STUDIO_WATCHED_FILE_MAX_CLIENTS}).`,
+			});
+			return;
+		}
+		const canonicalPath = resolve(msg.path);
+		const clientWatchedPath = studioWatchedClientPaths.get(client) ?? "";
+		if (clientWatchedPath !== canonicalPath) {
+			sendToClient(client, {
+				type: "watched_file_error",
+				path: canonicalPath,
+				message: "This socket is not authorized for that server-created watched preview.",
+			});
+			return;
+		}
+
+		const watcher = createStudioFileWatcher({
+			filePath: canonicalPath,
+			initialRevision: msg.revision,
+			readSnapshot: (filePath: string) => {
+				const file = readStudioFile(filePath, dirname(filePath), { requireCanonicalPath: true });
+				if (file.ok === false) throw new Error(file.message);
+				if (file.text.length > PREVIEW_RENDER_MAX_CHARS) {
+					throw new Error(`Watched file exceeds the ${PREVIEW_RENDER_MAX_CHARS.toLocaleString()}-character preview limit.`);
+				}
+				return { path: file.resolvedPath, text: file.text, revision: file.diskRevision };
+			},
+			onUpdate: (snapshot: { path: string; text: string; revision: string }, details: { generation: number; recovered: boolean }) => {
+				if (studioFileWatchers.get(client) !== watcher || client.readyState !== WebSocket.OPEN) return;
+				sendToClient(client, {
+					type: "watched_file_update",
+					path: snapshot.path,
+					text: snapshot.text,
+					diskRevision: snapshot.revision,
+					generation: details.generation,
+					recovered: details.recovered,
+					message: `Updated ${basename(snapshot.path)} from disk.`,
+				});
+			},
+			onError: (error: unknown, details: { generation: number; lastRevision: string | null }) => {
+				if (studioFileWatchers.get(client) !== watcher || client.readyState !== WebSocket.OPEN) return;
+				sendToClient(client, {
+					type: "watched_file_error",
+					path: canonicalPath,
+					diskRevision: details.lastRevision,
+					generation: details.generation,
+					message: `Could not refresh ${basename(canonicalPath)}; keeping the last good preview: ${error instanceof Error ? error.message : String(error)}`,
+				});
+			},
+			onRecovered: (snapshot: { path: string; revision: string }, details: { generation: number; changed: boolean }) => {
+				if (studioFileWatchers.get(client) !== watcher || client.readyState !== WebSocket.OPEN || details.changed) return;
+				sendToClient(client, {
+					type: "watched_file_ready",
+					path: snapshot.path,
+					diskRevision: snapshot.revision,
+					generation: details.generation,
+					recovered: true,
+					message: `Watching ${basename(snapshot.path)} for disk changes.`,
+				});
+			},
+		});
+		studioFileWatchers.set(client, watcher);
+		await watcher.refresh();
+		if (
+			studioFileWatchers.get(client) === watcher
+			&& client.readyState === WebSocket.OPEN
+			&& !watcher.error
+		) {
+			sendToClient(client, {
+				type: "watched_file_ready",
+				path: canonicalPath,
+				diskRevision: watcher.revision,
+				generation: watcher.generation,
+				message: `Watching ${basename(canonicalPath)} for disk changes.`,
+			});
+		}
+	};
+
 	const handleStudioMessage = (client: WebSocket, msg: IncomingStudioMessage) => {
 		if (msg.type === "ping") {
 			sendToClient(client, { type: "pong", timestamp: Date.now() });
@@ -14001,6 +14607,16 @@ export default function (pi: ExtensionAPI) {
 			studioWorkspaceStateStore.set(msg.tabStateId, msg.state);
 			return;
 		}
+		if (msg.type === "watch_file_subscribe") {
+			void subscribeStudioWatchedFile(client, msg).catch((error) => {
+				sendToClient(client, {
+					type: "watched_file_error",
+					path: msg.path,
+					message: `Could not start watched preview: ${error instanceof Error ? error.message : String(error)}`,
+				});
+			});
+			return;
+		}
 
 		emitDebugEvent("studio_message", {
 			type: msg.type,
@@ -14040,6 +14656,7 @@ export default function (pi: ExtensionAPI) {
 				responseHistory: studioResponseHistory,
 				traceState: studioTraceState,
 				initialDocument: initialStudioDocument,
+				resourceGrants: studioResourceGrantRegistry.snapshot(),
 				quartoPreview: getStudioQuartoPreviewSnapshot(),
 				sideQuestion: getStudioSideQuestionPublicState(),
 				webSearchAvailable: Boolean(String(process.env.BRAVE_API_KEY || "").trim()),
@@ -14970,6 +15587,10 @@ export default function (pi: ExtensionAPI) {
 		}
 
 		if (msg.type === "save_as_request") {
+			if (studioWatchedClientPaths.has(client)) {
+				sendToClient(client, { type: "error", requestId: msg.requestId, message: "Watched previews are read-only. Open an editable Studio tab before saving." });
+				return;
+			}
 			if (!isValidRequestId(msg.requestId)) {
 				sendToClient(client, { type: "error", requestId: msg.requestId, message: "Invalid request ID." });
 				return;
@@ -14978,14 +15599,21 @@ export default function (pi: ExtensionAPI) {
 				sendToClient(client, { type: "busy", requestId: msg.requestId, message: "Studio is busy." });
 				return;
 			}
-			if (!msg.content.trim()) {
-				sendToClient(client, { type: "error", requestId: msg.requestId, message: "Nothing to save." });
-				return;
-			}
 
-			const result = writeStudioFile(msg.path, studioCwd, msg.content);
+			const result = writeStudioFile(msg.path, studioCwd, msg.content, msg.overwrite === true, msg.expectedRevision);
 			if (result.ok === false) {
-				sendToClient(client, { type: "error", requestId: msg.requestId, message: result.message });
+				if (result.conflict) {
+					sendToClient(client, {
+						type: "save_as_conflict",
+						requestId: msg.requestId,
+						path: result.path || msg.path,
+						currentRevision: result.currentRevision || null,
+						reason: result.reason || "target-exists",
+						message: result.message,
+					});
+				} else {
+					sendToClient(client, { type: "error", requestId: msg.requestId, message: result.message });
+				}
 				return;
 			}
 
@@ -14995,7 +15623,9 @@ export default function (pi: ExtensionAPI) {
 				source: "file",
 				path: result.resolvedPath,
 				resourceDir: dirname(result.resolvedPath),
+				diskRevision: result.diskRevision,
 			};
+			recordStudioDocumentResourceGrants(initialStudioDocument);
 
 			sendToClient(client, {
 				type: "saved",
@@ -15003,12 +15633,17 @@ export default function (pi: ExtensionAPI) {
 				path: result.resolvedPath,
 				label: result.label,
 				resourceDir: dirname(result.resolvedPath),
+				diskRevision: result.diskRevision,
 				message: `Saved editor text to ${result.label}`,
 			});
 			return;
 		}
 
 		if (msg.type === "save_over_request") {
+			if (studioWatchedClientPaths.has(client)) {
+				sendToClient(client, { type: "error", requestId: msg.requestId, message: "Watched previews are read-only. Open an editable Studio tab before saving." });
+				return;
+			}
 			if (!isValidRequestId(msg.requestId)) {
 				sendToClient(client, { type: "error", requestId: msg.requestId, message: "Invalid request ID." });
 				return;
@@ -15017,35 +15652,52 @@ export default function (pi: ExtensionAPI) {
 				sendToClient(client, { type: "busy", requestId: msg.requestId, message: "Studio is busy." });
 				return;
 			}
-			if (!initialStudioDocument || initialStudioDocument.source !== "file" || !initialStudioDocument.path) {
-				sendToClient(client, {
-					type: "error",
-					requestId: msg.requestId,
-					message: "Save file is only available for file-backed documents.",
-				});
+
+			const result = saveStudioDiskFileIfRevision({
+				path: msg.path,
+				content: msg.content,
+				expectedRevision: msg.expectedRevision,
+				force: msg.force === true,
+			}) as StudioDiskWriteResult;
+			if (result.ok === false) {
+				if (result.conflict) {
+					sendToClient(client, {
+						type: "save_conflict",
+						requestId: msg.requestId,
+						path: result.path || msg.path,
+						currentRevision: result.currentRevision || null,
+						reason: result.reason || "disk-changed",
+						canOverwrite: result.reason !== "location-changed" && result.reason !== "hard-linked-file",
+						message: result.message,
+					});
+				} else {
+					sendToClient(client, { type: "error", requestId: msg.requestId, message: result.message });
+				}
 				return;
 			}
 
-			try {
-				writeFileSync(initialStudioDocument.path, msg.content, "utf-8");
-				initialStudioDocument = {
-					...initialStudioDocument,
-					text: msg.content,
-				};
-				sendToClient(client, {
-					type: "saved",
-					requestId: msg.requestId,
-					path: initialStudioDocument.path,
-					label: initialStudioDocument.label,
-					message: `Saved over ${initialStudioDocument.label}`,
-				});
-			} catch (error) {
-				sendToClient(client, {
-					type: "error",
-					requestId: msg.requestId,
-					message: `Failed to save over file: ${error instanceof Error ? error.message : String(error)}`,
-				});
-			}
+			const previousDocument = initialStudioDocument;
+			const existingLabel = previousDocument?.path === result.path
+				? previousDocument.label
+				: basename(result.path);
+			initialStudioDocument = {
+				text: msg.content,
+				label: existingLabel,
+				source: "file",
+				path: result.path,
+				resourceDir: dirname(result.path),
+				diskRevision: result.revision,
+			};
+			recordStudioDocumentResourceGrants(initialStudioDocument);
+			sendToClient(client, {
+				type: "saved",
+				requestId: msg.requestId,
+				path: result.path,
+				label: existingLabel,
+				resourceDir: dirname(result.path),
+				diskRevision: result.revision,
+				message: `Saved over ${existingLabel}`,
+			});
 			return;
 		}
 
@@ -15069,7 +15721,7 @@ export default function (pi: ExtensionAPI) {
 				return;
 			}
 
-			const refreshed = readStudioFile(refreshPath, studioCwd);
+			const refreshed = readStudioFile(refreshPath, studioCwd, { requireCanonicalPath: true });
 			if (refreshed.ok === false) {
 				sendToClient(client, {
 					type: "error",
@@ -15085,9 +15737,11 @@ export default function (pi: ExtensionAPI) {
 				source: "file",
 				path: refreshed.resolvedPath,
 				resourceDir: dirname(refreshed.resolvedPath),
+				diskRevision: refreshed.diskRevision,
 			};
 			if (!requestedPath || initialStudioDocument?.path === refreshed.resolvedPath) {
 				initialStudioDocument = refreshedDocument;
+				recordStudioDocumentResourceGrants(refreshedDocument);
 			}
 
 			sendToClient(client, {
@@ -15592,14 +16246,25 @@ export default function (pi: ExtensionAPI) {
 				parsedBody && typeof parsedBody === "object" && typeof (parsedBody as { editorLanguage?: unknown }).editorLanguage === "string"
 					? (parsedBody as { editorLanguage: string }).editorLanguage
 					: "";
-			const resourcePath = resolveStudioBaseDir(sourcePath || undefined, userResourceDir || undefined, studioCwd);
+			const authorizedContext = resolveStudioAuthorizedPreviewRenderContext(
+				sourcePath || undefined,
+				userResourceDir || undefined,
+				studioCwd,
+				studioResourceGrantRegistry,
+			);
 			const editorPreviewLanguage = normalizeStudioEditorLanguage(requestedEditorLanguage);
 			const isLatex = editorPreviewLanguage === "latex"
 				|| (
 					(editorPreviewLanguage === undefined || editorPreviewLanguage === "markdown")
 					&& isLikelyStandaloneLatexPreview(markdown)
 				);
-			const html = await renderStudioMarkdownWithPandoc(markdown, isLatex, resourcePath, sourcePath || undefined);
+			const html = await renderStudioMarkdownWithPandoc(
+				markdown,
+				isLatex,
+				authorizedContext.resourcePath,
+				authorizedContext.sourcePath,
+				{ embedResources: false },
+			);
 			respondJson(res, 200, { ok: true, html, renderer: "pandoc" });
 		} catch (error) {
 			const message = error instanceof Error ? error.message : String(error);
@@ -16342,13 +17007,31 @@ export default function (pi: ExtensionAPI) {
 			try {
 				const listing = listStudioFileBrowserDirectory(
 					requestUrl.searchParams.get("dir") ?? undefined,
+					requestUrl.searchParams.get("root") ?? undefined,
 					requestUrl.searchParams.get("sourcePath") ?? undefined,
 					requestUrl.searchParams.get("resourceDir") ?? undefined,
 					studioCwd,
+					studioResourceGrantRegistry,
 					requestUrl.searchParams.get("sort") ?? undefined,
 				);
-				respondJson(res, 200, { ok: true, ...listing, entries: method === "HEAD" ? [] : listing.entries });
+				respondJson(res, 200, {
+					ok: true,
+					...listing,
+					entries: method === "HEAD" ? [] : listing.entries,
+					exactFiles: method === "HEAD" ? [] : listing.exactFiles,
+				});
 			} catch (error) {
+				if (error instanceof StudioDirectoryGrantRequiredError) {
+					respondJson(res, 403, {
+						ok: false,
+						code: error.code,
+						error: error.message,
+						path: error.directoryPath,
+						directoryPath: error.directoryPath,
+						...getStudioFileBrowserGrantLocations(studioResourceGrantRegistry),
+					});
+					return;
+				}
 				respondJson(res, 404, { ok: false, error: `File browser unavailable: ${error instanceof Error ? error.message : String(error)}` });
 			}
 			return;
@@ -16361,7 +17044,7 @@ export default function (pi: ExtensionAPI) {
 				return;
 			}
 
-			void handleOpenStudioFileBrowserDirectoryRequest(req, res, studioCwd).catch((error) => {
+			void handleOpenStudioFileBrowserDirectoryRequest(req, res, studioCwd, studioResourceGrantRegistry).catch((error) => {
 				respondJson(res, 500, { ok: false, error: `Open folder failed: ${error instanceof Error ? error.message : String(error)}` });
 			});
 			return;
@@ -16380,6 +17063,32 @@ export default function (pi: ExtensionAPI) {
 			return;
 		}
 
+		if (requestUrl.pathname === "/resource-grants") {
+			const token = requestUrl.searchParams.get("token") ?? "";
+			if (token !== serverState.token) {
+				respondJson(res, 403, { ok: false, error: "Invalid or expired studio token. Re-run /studio." });
+				return;
+			}
+
+			void handleStudioResourceGrantRequest(req, res, studioResourceGrantRegistry, studioCwd).catch((error) => {
+				respondJson(res, 500, { ok: false, error: `Resource grant failed: ${error instanceof Error ? error.message : String(error)}` });
+			});
+			return;
+		}
+
+		if (requestUrl.pathname === "/side-question-context-root") {
+			const token = requestUrl.searchParams.get("token") ?? "";
+			if (token !== serverState.token) {
+				respondJson(res, 403, { ok: false, error: "Invalid or expired studio token. Re-run /studio." });
+				return;
+			}
+
+			void handleStudioSideQuestionContextRootRequest(req, res).catch((error) => {
+				respondJson(res, 500, { ok: false, error: `Side-question context check failed: ${error instanceof Error ? error.message : String(error)}` });
+			});
+			return;
+		}
+
 		if (requestUrl.pathname === "/local-preview-link") {
 			const token = requestUrl.searchParams.get("token") ?? "";
 			if (token !== serverState.token) {
@@ -16394,9 +17103,21 @@ export default function (pi: ExtensionAPI) {
 						requestUrl.searchParams.get("sourcePath") ?? undefined,
 						requestUrl.searchParams.get("resourceDir") ?? undefined,
 						studioCwd,
+						studioResourceGrantRegistry,
+					);
+					await respondLocalPreviewLinkJson(
+						req,
+						res,
+						requestUrl,
+						resource,
+						serverState,
+						studioResourceGrantRegistry,
 					);
-					await respondLocalPreviewLinkJson(req, res, requestUrl, resource, serverState);
 				} catch (error) {
+					if (error instanceof StudioResourceGrantRequiredError) {
+						respondStudioResourceGrantRequiredJson(res, error);
+						return;
+					}
 					respondJson(res, 404, { ok: false, error: `Local resource unavailable: ${error instanceof Error ? error.message : String(error)}` });
 				}
 			})();
@@ -16410,7 +17131,7 @@ export default function (pi: ExtensionAPI) {
 				return;
 			}
 
-			void handleRevealLocalPreviewResourceRequest(req, res, studioCwd).catch((error) => {
+			void handleRevealLocalPreviewResourceRequest(req, res, studioCwd, studioResourceGrantRegistry).catch((error) => {
 				respondJson(res, 500, { ok: false, error: `Reveal failed: ${error instanceof Error ? error.message : String(error)}` });
 			});
 			return;
@@ -16423,7 +17144,7 @@ export default function (pi: ExtensionAPI) {
 				return;
 			}
 
-			void handleOpenLocalPreviewResourceRequest(req, res, studioCwd).catch((error) => {
+			void handleOpenLocalPreviewResourceRequest(req, res, studioCwd, studioResourceGrantRegistry).catch((error) => {
 				respondJson(res, 500, { ok: false, error: `Open in system viewer failed: ${error instanceof Error ? error.message : String(error)}` });
 			});
 			return;
@@ -16442,9 +17163,14 @@ export default function (pi: ExtensionAPI) {
 					requestUrl.searchParams.get("sourcePath") ?? undefined,
 					requestUrl.searchParams.get("resourceDir") ?? undefined,
 					studioCwd,
+					studioResourceGrantRegistry,
 				);
 				respondPdfFile(req, res, filePath);
 			} catch (error) {
+				if (error instanceof StudioResourceGrantRequiredError) {
+					respondStudioResourceGrantRequiredJson(res, error);
+					return;
+				}
 				respondText(res, 404, `PDF resource unavailable: ${error instanceof Error ? error.message : String(error)}`);
 			}
 			return;
@@ -16463,10 +17189,15 @@ export default function (pi: ExtensionAPI) {
 					requestUrl.searchParams.get("sourcePath") ?? undefined,
 					requestUrl.searchParams.get("resourceDir") ?? undefined,
 					studioCwd,
+					studioResourceGrantRegistry,
 				);
 				respondHtmlPreviewResourceJson(req, res, resource.filePath, resource.mimeType);
 			} catch (error) {
-				respondJson(res, 404, { ok: false, error: `HTML preview resource unavailable: ${error instanceof Error ? error.message : String(error)}` });
+				if (error instanceof StudioResourceGrantRequiredError) {
+					respondStudioResourceGrantRequiredJson(res, error);
+					return;
+				}
+				respondJson(res, 404, { ok: false, error: `Studio preview resource unavailable: ${error instanceof Error ? error.message : String(error)}` });
 			}
 			return;
 		}
@@ -16545,6 +17276,32 @@ export default function (pi: ExtensionAPI) {
 			const host = req.headers.host ?? `127.0.0.1:${state.port}`;
 			const requestUrl = new URL(req.url ?? "/ws", `http://${host}`);
 			const clientMode = normalizeStudioUiMode(requestUrl.searchParams.get("mode"));
+			const requestedWatchedPath = (requestUrl.searchParams.get("watchPath") ?? "").trim();
+			const canonicalWatchedPath = requestedWatchedPath ? resolve(requestedWatchedPath) : "";
+			const requestedDocId = (requestUrl.searchParams.get("docId") ?? "").trim();
+			const capabilityDocument = requestedDocId ? readTransientStudioDocument(requestedDocId) : null;
+			const capabilityWatchedPath = capabilityDocument?.watchFile && capabilityDocument.path
+				? resolve(capabilityDocument.path)
+				: "";
+			const comparableWatchedPath = process.platform === "win32" ? canonicalWatchedPath.toLowerCase() : canonicalWatchedPath;
+			const comparableCapabilityPath = process.platform === "win32" ? capabilityWatchedPath.toLowerCase() : capabilityWatchedPath;
+			const requestsWatchedCapability = Boolean(canonicalWatchedPath || capabilityWatchedPath);
+			if (
+				requestsWatchedCapability
+				&& (
+					clientMode !== "editor-only"
+					|| !canonicalWatchedPath
+					|| !capabilityWatchedPath
+					|| comparableWatchedPath !== comparableCapabilityPath
+				)
+			) {
+				try {
+					ws.close(4003, "Watched preview authorization unavailable");
+				} catch {
+					// Ignore close errors.
+				}
+				return;
+			}
 			if (clientMode === "full") {
 				for (const client of clients) {
 					if (client.readyState !== WebSocket.OPEN) continue;
@@ -16560,6 +17317,7 @@ export default function (pi: ExtensionAPI) {
 			}
 			clients.add(ws);
 			clientModes.set(ws, clientMode);
+			if (canonicalWatchedPath) studioWatchedClientPaths.set(ws, canonicalWatchedPath);
 			emitDebugEvent("studio_ws_connected", { clients: clients.size, mode: clientMode });
 			broadcastState();
 
@@ -16572,15 +17330,33 @@ export default function (pi: ExtensionAPI) {
 				handleStudioMessage(ws, parsed);
 			});
 
-			ws.on("close", () => {
+			const cleanupClient = () => {
 				clients.delete(ws);
 				clientModes.delete(ws);
+				studioWatchedClientPaths.delete(ws);
+				const cleanupGeneration = (studioFileWatchSubscriptionGenerations.get(ws) ?? 0) + 1;
+				studioFileWatchSubscriptionGenerations.set(ws, cleanupGeneration);
+				void closeStudioFileWatcher(ws).finally(() => {
+					if (studioFileWatchSubscriptionGenerations.get(ws) === cleanupGeneration) {
+						studioFileWatchSubscriptionGenerations.delete(ws);
+					}
+				});
+			};
+
+			ws.on("close", () => {
+				cleanupClient();
 				emitDebugEvent("studio_ws_disconnected", { clients: clients.size });
 			});
 
 			ws.on("error", () => {
-				clients.delete(ws);
-				clientModes.delete(ws);
+				// Make the socket unusable before removing its watched-path marker;
+				// otherwise an error event could briefly weaken read-only enforcement.
+				try {
+					ws.terminate();
+				} catch {
+					try { ws.close(); } catch {}
+				}
+				cleanupClient();
 			});
 		});
 
@@ -16648,7 +17424,12 @@ export default function (pi: ExtensionAPI) {
 	const stopServer = async () => {
 		studioSideQuestionStartRequestId = null;
 		await disposeStudioSideQuestionRuntime();
-		if (!serverState) return;
+		await closeAllStudioFileWatchers();
+		if (!serverState) {
+			studioWatchedClientPaths.clear();
+			studioFileWatchSubscriptionGenerations.clear();
+			return;
+		}
 		clearStudioDirectRunState();
 		clearActiveRequest();
 		clearPendingStudioCompletion();
@@ -16674,7 +17455,10 @@ export default function (pi: ExtensionAPI) {
 		await new Promise<void>((resolve) => {
 			state.server.close(() => resolve());
 		});
+		studioWatchedClientPaths.clear();
+		studioFileWatchSubscriptionGenerations.clear();
 		studioWorkspaceStateStore.clear();
+		studioResourceGrantRegistry.clear();
 	};
 
 	const hydrateLatestAssistant = (entries: SessionEntry[]) => {
@@ -16691,6 +17475,13 @@ export default function (pi: ExtensionAPI) {
 			await disposeStudioSideQuestionRuntime();
 			studioTraceHistory.clear();
 			lastCommandCtx = null;
+			for (const client of studioWatchedClientPaths.keys()) {
+				try { client.close(4001, "Watched preview session changed"); } catch {}
+			}
+			await closeAllStudioFileWatchers();
+			transientStudioDocuments.clear();
+			studioResourceGrantRegistry.clear();
+			initialStudioDocument = null;
 		}
 		latestModelRequestCtx = ctx;
 		hydrateLatestAssistant(ctx.sessionManager.getBranch());
@@ -17042,7 +17833,7 @@ export default function (pi: ExtensionAPI) {
 	const resolveStudioLaunchDocument = (
 		trimmed: string,
 		ctx: ExtensionCommandContext,
-		options?: { defaultSource?: "blank" | "last-response"; commandLabel?: string; allowPdfPreview?: boolean; watchPdf?: boolean },
+		options?: { defaultSource?: "blank" | "last-response"; commandLabel?: string; allowPdfPreview?: boolean; watchPdf?: boolean; watchText?: boolean },
 	): StudioLaunchSelection | null => {
 		const defaultSource = options?.defaultSource === "blank" ? "blank" : "last-response";
 		const commandLabel = options?.commandLabel ?? "/studio";
@@ -17149,6 +17940,30 @@ export default function (pi: ExtensionAPI) {
 			return null;
 		}
 
+		if (options?.watchText) {
+			if (file.text.length > PREVIEW_RENDER_MAX_CHARS) {
+				ctx.ui.notify(`Watched preview source exceeds ${PREVIEW_RENDER_MAX_CHARS.toLocaleString()} characters.`, "error");
+				return null;
+			}
+			return {
+				document: {
+					text: file.text,
+					label: file.label,
+					source: "file",
+					path: file.resolvedPath,
+					resourceDir: dirname(file.resolvedPath),
+					diskRevision: file.diskRevision,
+					watchFile: true,
+				},
+				kind: "watched-preview",
+				mode: "editor-only",
+				transient: true,
+				skipWorkspaceRestore: true,
+				paneFocus: "right",
+				resourcePath: file.resolvedPath,
+			};
+		}
+
 		if (file.text.length > 200_000) {
 			ctx.ui.notify(
 				"Loaded a large file. Studio critique requests currently reject documents over 200k characters.",
@@ -17162,6 +17977,7 @@ export default function (pi: ExtensionAPI) {
 			source: "file",
 			path: file.resolvedPath,
 			resourceDir: ctx.cwd,
+			diskRevision: file.diskRevision,
 		});
 	};
 
@@ -17419,7 +18235,7 @@ export default function (pi: ExtensionAPI) {
 		trimmed: string,
 		ctx: ExtensionCommandContext,
 		mode: StudioUiMode,
-		options?: { defaultSource?: "blank" | "last-response"; commandLabel?: string; replaceExistingFull?: boolean; allowPdfPreview?: boolean; watchPdf?: boolean },
+		options?: { defaultSource?: "blank" | "last-response"; commandLabel?: string; replaceExistingFull?: boolean; allowPdfPreview?: boolean; watchPdf?: boolean; watchText?: boolean },
 	) => {
 		const launchOpenFlags = parseStudioLaunchOpenFlags(trimmed);
 		if (launchOpenFlags.error) {
@@ -17435,11 +18251,12 @@ export default function (pi: ExtensionAPI) {
 		const launchesPdfPreview = parsedLaunchPath
 			? Boolean(parseStudioPdfLaunchTarget(normalizePathInput(parsedLaunchPath)))
 			: false;
-		if (launchOpenFlags.watchPdf && !launchesPdfPreview) {
-			ctx.ui.notify("--watch requires a local PDF path, for example: /studio --watch main.pdf", "error");
+		if (launchOpenFlags.watchPdf && !parsedLaunchPath) {
+			ctx.ui.notify("--watch requires a local text or PDF path, for example: /studio --watch notes.md", "error");
 			return;
 		}
-		const requestedLaunchMode: StudioUiMode = launchesPdfPreview ? "editor-only" : mode;
+		const launchesWatchedTextPreview = Boolean(launchOpenFlags.watchPdf && parsedLaunchPath && !launchesPdfPreview);
+		const requestedLaunchMode: StudioUiMode = launchesPdfPreview || launchesWatchedTextPreview ? "editor-only" : mode;
 		if (requestedLaunchMode === "full" && hasConnectedFullStudioView()) {
 			if (options?.replaceExistingFull) {
 				closeStudioClientsByMode("full", 4001, "Full Studio replaced");
@@ -17473,7 +18290,8 @@ export default function (pi: ExtensionAPI) {
 
 		const selection = resolveStudioLaunchDocument(launchArgs, ctx, {
 			...options,
-			watchPdf: launchOpenFlags.watchPdf,
+			watchPdf: launchOpenFlags.watchPdf && launchesPdfPreview,
+			watchText: launchesWatchedTextPreview,
 		});
 		if (!selection) return;
 		const selected = selection.document;
@@ -17489,6 +18307,7 @@ export default function (pi: ExtensionAPI) {
 			ctx.ui.notify(`Failed to start Studio server${portText}: ${message}`, "error");
 			return;
 		}
+		recordStudioDocumentResourceGrants(selected, ctx.cwd);
 		const docId = selection.transient ? storeTransientStudioDocument(selected) : undefined;
 		const url = buildStudioUrl(state.port, state.token, launchMode, selected, docId, {
 			skipWorkspaceRestore: selection.skipWorkspaceRestore,
@@ -17498,7 +18317,9 @@ export default function (pi: ExtensionAPI) {
 			?? (launchOpenFlags.noBrowser ? buildStudioForwardingHint(state.port, url, { prefix: "Browser auto-open was skipped because --no-browser was used." }) : null);
 		const openedLabel = selection.kind === "pdf-preview"
 			? "pi Studio PDF preview"
-			: (launchMode === "editor-only" ? "pi Studio editor-only view" : "pi Studio");
+			: (selection.kind === "watched-preview"
+				? "pi Studio watched file preview"
+				: (launchMode === "editor-only" ? "pi Studio editor-only view" : "pi Studio"));
 
 		const shouldOpenBrowser = shouldAutoOpenStudioBrowser({
 			openRemoteBrowser: launchOpenFlags.openRemoteBrowser,
@@ -17513,6 +18334,8 @@ export default function (pi: ExtensionAPI) {
 				if (selection.kind === "pdf-preview") {
 					const watchLabel = launchOpenFlags.watchPdf ? " (auto-refresh on)" : "";
 					ctx.ui.notify(`Opened ${openedLabel}${watchLabel}: ${selection.resourcePath ?? selected.label}`, "info");
+				} else if (selection.kind === "watched-preview") {
+					ctx.ui.notify(`Opened ${openedLabel}: ${selection.resourcePath ?? selected.label}`, "info");
 				} else if (selected.source === "file") {
 					ctx.ui.notify(`Opened ${openedLabel} with file loaded: ${selected.label}`, "info");
 				} else if (selected.source === "last-response") {
@@ -17535,7 +18358,7 @@ export default function (pi: ExtensionAPI) {
 	};
 
 	pi.registerCommand("studio", {
-		description: "Open pi Studio browser UI or a PDF preview (/studio, /studio <file>, /studio --watch <pdf>, /studio --blank, /studio --last, /studio --no-browser)",
+		description: "Open pi Studio browser UI or a read-only watched preview (/studio, /studio <file>, /studio --watch <file>, /studio --blank, /studio --last, /studio --no-browser)",
 		handler: async (args: string, ctx: ExtensionCommandContext) => {
 			const trimmed = args.trim();
 
@@ -17566,7 +18389,7 @@ export default function (pi: ExtensionAPI) {
 					"Usage: /studio [path|--blank|--last]\n"
 						+ "  /studio           Open studio with last model response (fallback: blank)\n"
 						+ "  /studio <path>    Open a text file in Studio, or a PDF in a read-only companion preview\n"
-						+ "  /studio --watch <pdf>  Open a PDF with auto-refresh enabled\n"
+						+ "  /studio --watch <file>  Open a read-only text preview that follows disk changes, or a PDF with auto-refresh\n"
 						+ "  /studio --blank   Open with blank editor\n"
 						+ "  /studio --last    Open with last model response\n"
 						+ "  /studio --no-browser  Print the Studio URL without opening a browser\n"
@@ -17617,7 +18440,7 @@ export default function (pi: ExtensionAPI) {
 	});
 
 	pi.registerCommand("studio-editor-only", {
-		description: "Open pi Studio in editor-only mode or preview a PDF (/studio-editor-only, /studio-editor-only <file>, /studio-editor-only --watch <pdf>)",
+		description: "Open pi Studio in editor-only mode or a read-only watched preview (/studio-editor-only, /studio-editor-only <file>, /studio-editor-only --watch <file>)",
 		handler: async (args: string, ctx: ExtensionCommandContext) => {
 			const trimmed = args.trim();
 			if (trimmed === "help" || trimmed === "--help" || trimmed === "-h") {
@@ -17625,7 +18448,7 @@ export default function (pi: ExtensionAPI) {
 					"Usage: /studio-editor-only [path|--blank|--last]\n"
 						+ "  /studio-editor-only         Open an editor-only Studio view (default: blank editor)\n"
 						+ "  /studio-editor-only <path>  Open a text file for editing, or a PDF in a read-only preview\n"
-						+ "  /studio-editor-only --watch <pdf>  Open a PDF with auto-refresh enabled\n"
+						+ "  /studio-editor-only --watch <file>  Open a read-only text preview that follows disk changes, or a PDF with auto-refresh\n"
 						+ "  /studio-editor-only --blank Open with blank editor\n"
 						+ "  /studio-editor-only --last  Open with last model response loaded into the editor\n"
 						+ "  /studio-editor-only --no-browser  Print URL without opening a browser\n"
@@ -17981,8 +18804,10 @@ export default function (pi: ExtensionAPI) {
 				label: file.label,
 				source: "file",
 				path: file.resolvedPath,
+				diskRevision: file.diskRevision,
 			};
 			initialStudioDocument = nextDoc;
+			recordStudioDocumentResourceGrants(nextDoc, ctx.cwd);
 
 			broadcastState();
 			broadcastResponseHistory();