pi-studio 0.9.53 → 0.9.55

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,
@@ -68,9 +74,11 @@ import {
 import {
 	buildStudioSideQuestionFollowUpPrompt,
 	buildStudioSideQuestionPrompt,
+	getStudioSideQuestionThinkingLevels,
 	normalizeStudioSideQuestionFocusKind,
 	normalizeStudioSideQuestionGatherScope,
 	normalizeStudioSideQuestionThinking,
+	resolveStudioSideQuestionThinking,
 	STUDIO_SIDE_QUESTION_FOCUS_MAX_CHARS,
 	STUDIO_SIDE_QUESTION_QUESTION_MAX_CHARS,
 } from "./shared/studio-side-question.js";
@@ -114,7 +122,7 @@ type StudioQuartoPreviewStatus = "idle" | "starting" | "running" | "stopping" |
 type StudioShowMeSourceKind = "selection" | "response" | "editor" | "context";
 type StudioSideQuestionFocusKind = "selection" | "section" | "editor" | "response" | "none";
 type StudioSideQuestionGatherScope = "none" | "folder" | "repo" | "custom";
-type StudioSideQuestionThinking = "off" | "minimal" | "low" | "medium" | "high";
+type StudioSideQuestionThinking = ModelThinkingLevel;
 type StudioSideQuestionStatus = "idle" | "running" | "error";
 
 interface StudioQuartoPreviewContext {
@@ -314,11 +322,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;
@@ -719,12 +740,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 {
@@ -733,6 +759,12 @@ interface RefreshFromDiskRequestMessage {
 	path?: string;
 }
 
+interface WatchFileSubscribeMessage {
+	type: "watch_file_subscribe";
+	path: string;
+	revision?: string;
+}
+
 interface SendToEditorRequestMessage {
 	type: "send_to_editor_request";
 	requestId: string;
@@ -821,6 +853,7 @@ type IncomingStudioMessage =
 	| SaveAsRequestMessage
 	| SaveOverRequestMessage
 	| RefreshFromDiskRequestMessage
+	| WatchFileSubscribeMessage
 	| SendToEditorRequestMessage
 	| GetFromEditorRequestMessage
 	| QuartoPreviewCheckRequestMessage
@@ -833,6 +866,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;
@@ -2463,8 +2497,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) {
@@ -2472,39 +2506,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)})`,
 		};
 	}
 }
@@ -2864,23 +2900,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(
@@ -7961,6 +7992,13 @@ async function respondLocalPreviewLinkJson(
 	}
 
 	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,
@@ -7990,10 +8028,14 @@ async function respondLocalPreviewLinkJson(
 		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;
@@ -8038,6 +8080,7 @@ async function respondLocalPreviewLinkJson(
 			source: "file",
 			path: file.resolvedPath,
 			resourceDir: documentResourceDir,
+			diskRevision: file.diskRevision,
 		};
 	}
 	if (action === "document") {
@@ -8047,16 +8090,27 @@ async function respondLocalPreviewLinkJson(
 			label: document.label,
 			converted,
 			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 }),
+		relativeUrl: buildStudioRelativeUrl(serverState.token, "editor-only", document, docId, {
+			skipWorkspaceRestore: true,
+			paneFocus: action === "watch-url" ? "right" : undefined,
+		}),
 	});
 }
 
@@ -9956,21 +10010,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,
 		};
 	}
 
@@ -9986,6 +10054,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",
@@ -11322,6 +11403,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()}`;
@@ -11411,16 +11493,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,
 			};
 		}
 	}
@@ -11705,6 +11807,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");
@@ -11781,12 +11885,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>
@@ -11804,10 +11908,12 @@ ${cssVarsBlock}
     <section id="leftPane">
       <div id="leftSectionHeader" class="section-header">
         <div class="section-header-main">
-          <select id="editorViewSelect" aria-label="Editor view mode" title="Editor view mode. Shortcut: F7 when the editor pane is active; F6 switches panes.">
-            <option value="markdown" selected>Editor (Raw)</option>
-            <option value="preview">Editor (Preview)</option>
-          </select>
+          <span id="editorViewSelectWrap" class="studio-header-select-wrap">
+            <select id="editorViewSelect" aria-label="Editor view mode" title="Editor view mode. Shortcut: F7 when the editor pane is active; F6 switches panes.">
+              <option value="markdown" selected>Editor (Raw)</option>
+              <option value="preview">Editor (Preview)</option>
+            </select>
+          </span>
         </div>
         <div class="section-header-actions">
           <button id="leftFocusBtn" class="pane-focus-btn" type="button" title="Show only the editor pane. Shortcut: F10 or Cmd/Ctrl+Esc.">Focus pane</button>
@@ -11835,7 +11941,7 @@ ${cssVarsBlock}
             </div>
             <div class="source-actions-row repl-action-line" hidden>
               <button id="sendReplBtn" type="button" hidden title="Send the current selection, or the full editor text, to the active REPL session shown in the right pane.">Send to REPL</button>
-              <select id="replSendModeSelect" hidden aria-label="REPL send mode" title="Choose how Send to REPL interprets the editor text.">
+              <select id="replSendModeSelect" class="studio-flat-select" hidden aria-label="REPL send mode" title="Choose how Send to REPL interprets the editor text.">
                 <option value="raw" selected>Send mode: Raw</option>
                 <option value="literate">Send mode: Literate</option>
               </select>
@@ -11844,11 +11950,11 @@ ${cssVarsBlock}
               <button id="copyDraftBtn" type="button" title="Copy the current editor text to the clipboard.">Copy</button>
               <button id="suggestCompletionBtn" type="button" title="Ask the current model for a short completion at the editor cursor. Shortcut: Option/Alt+Tab where available, or Cmd/Ctrl+Shift+Space from the editor.">Suggest</button>
               <button id="suggestCompletionOptionsBtn" type="button" hidden title="Suggestion context options">▾</button>
-              <select id="completionContextSelect" hidden aria-label="Suggestion context mode" title="Choose how much context Suggest includes.">
+              <select id="completionContextSelect" class="studio-flat-select" hidden aria-label="Suggestion context mode" title="Choose how much context Suggest includes.">
                 <option value="cursor" selected>Context: editor only</option>
                 <option value="session">Context: editor + latest response</option>
               </select>
-              <select id="completionModelSelect" hidden aria-label="Suggestion model" title="Choose the model used for Suggest. Suggestions use direct completion with thinking off and do not change the main Pi model.">
+              <select id="completionModelSelect" class="studio-flat-select" hidden aria-label="Suggestion model" title="Choose the model used for Suggest. Suggestions use direct completion with thinking off and do not change the main Pi model.">
                 <option value="current" selected>Suggestion model: current Pi model</option>
               </select>
               <button id="openCompanionBtn" type="button" title="Open a blank editor-only Studio tab.">New editor tab</button>
@@ -11856,7 +11962,7 @@ ${cssVarsBlock}
             </div>
             <div class="source-actions-row">
               <button id="insertHeaderBtn" type="button" title="Insert annotated-reply protocol header (source metadata, [an: ...] syntax hint, precedence note, and end marker).">Annotation header</button>
-              <select id="annotationModeSelect" aria-label="Inline annotation visibility mode" title="On: keep and send [an: ...] markers. Hide: keep markers in the editor, hide them in preview, and strip before Run/Critique.">
+              <select id="annotationModeSelect" class="studio-flat-select" aria-label="Inline annotation visibility mode" title="On: keep and send [an: ...] markers. Hide: keep markers in the editor, hide them in preview, and strip before Run/Critique.">
                 <option value="on" selected>Inline annotations: On</option>
                 <option value="off">Inline annotations: Hide</option>
               </select>
@@ -11864,7 +11970,7 @@ ${cssVarsBlock}
               <button id="saveAnnotatedBtn" type="button" title="Save full editor content (including [an: ...] markers) as a .annotated.md file.">Save .annotated.md</button>
             </div>
             <div class="source-actions-row">
-              <select id="lensSelect" aria-label="Critique focus">
+              <select id="lensSelect" class="studio-flat-select" aria-label="Critique focus">
                 <option value="auto" selected>Critique: Auto</option>
                 <option value="writing">Critique: Writing</option>
                 <option value="code">Critique: Code</option>
@@ -11874,7 +11980,7 @@ ${cssVarsBlock}
               <button id="showMeResponseBtn" type="button" hidden title="Explain the response displayed in the right pane using the smallest useful visual or structural representation.">Explain displayed response</button>
               <button id="askAsideBtn" type="button" title="Open a separate side-question thread without adding it to the main Pi conversation.">Side question</button>
               <button id="quizBtn" type="button" title="Open an active quiz for the current editor selection or document.">Quiz me</button>
-              <select id="highlightSelect" aria-label="Editor syntax highlighting">
+              <select id="highlightSelect" class="studio-flat-select" aria-label="Editor syntax highlighting">
                 <option value="off">Syntax highlight: Off</option>
                 <option value="bash">Syntax highlight: Bash</option>
                 <option value="c">Syntax highlight: C</option>
@@ -11904,11 +12010,11 @@ ${cssVarsBlock}
                 <option value="xml">Syntax highlight: XML</option>
                 <option value="yaml">Syntax highlight: YAML</option>
               </select>
-              <select id="lineNumbersSelect" aria-label="Editor line numbers">
+              <select id="lineNumbersSelect" class="studio-flat-select" aria-label="Editor line numbers">
                 <option value="off">Line numbers: Off</option>
                 <option value="on" selected>Line numbers: On</option>
               </select>
-              <select id="editorFontSizeSelect" aria-label="Editor text size" title="Adjust raw editor text size.">
+              <select id="editorFontSizeSelect" class="studio-flat-select" aria-label="Editor text size" title="Adjust raw editor text size.">
                 <option value="10">Editor text: 10px</option>
                 <option value="11">Editor text: 11px</option>
                 <option value="12" selected>Editor text: 12px</option>
@@ -12006,20 +12112,23 @@ ${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/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>
-            <option value="editor-quarto-preview" hidden>Editor (Quarto Preview)</option>
-            <option value="trace">Working</option>
-            <option value="changes">Changes</option>
-            <option value="files">Files</option>
-            <option value="repl">REPL</option>
-            <option value="side-questions">Side questions</option>
-          </select>
+          <span id="rightViewSelectWrap" class="studio-header-select-wrap">
+            <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>
+              <option value="editor-quarto-preview" hidden>Editor (Quarto Preview)</option>
+              <option value="trace">Working</option>
+              <option value="changes">Changes</option>
+              <option value="files">Files</option>
+              <option value="repl">REPL</option>
+              <option value="side-questions">Side questions</option>
+            </select>
+          </span>
         </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>
@@ -12042,28 +12151,34 @@ ${cssVarsBlock}
       <div class="response-wrap">
         <div id="responseActions" class="response-actions">
           <div class="response-actions-row response-options-row">
-            <select id="followSelect" aria-label="Auto-update response">
-              <option value="on" selected>Auto-update response: On</option>
-              <option value="off">Auto-update response: Off</option>
-            </select>
-            <select id="responseHighlightSelect" aria-label="Response markdown highlighting">
-              <option value="off">Syntax highlight: Off</option>
-              <option value="on" selected>Syntax highlight: On</option>
-            </select>
-            <select id="responseFontSizeSelect" aria-label="Response text size" title="Adjust right-pane response, preview, and working text size.">
-              <option value="11">Response text: 11px</option>
-              <option value="12">Response text: 12px</option>
-              <option value="12.5">Response text: 12.5px</option>
-              <option value="13">Response text: 13px</option>
-              <option value="13.5" selected>Response text: 13.5px</option>
-              <option value="14">Response text: 14px</option>
-              <option value="14.5">Response text: 14.5px</option>
-              <option value="15">Response text: 15px</option>
-              <option value="15.5">Response text: 15.5px</option>
-              <option value="16">Response text: 16px</option>
-              <option value="18">Response text: 18px</option>
-              <option value="20">Response text: 20px</option>
-            </select>
+            <span id="followSelectWrap" class="studio-menu-select-wrap response-option-select-wrap">
+              <select id="followSelect" aria-label="Auto-update response">
+                <option value="on" selected>Auto-update response: On</option>
+                <option value="off">Auto-update response: Off</option>
+              </select>
+            </span>
+            <span id="responseHighlightSelectWrap" class="studio-menu-select-wrap response-option-select-wrap">
+              <select id="responseHighlightSelect" aria-label="Response markdown highlighting">
+                <option value="off">Syntax highlight: Off</option>
+                <option value="on" selected>Syntax highlight: On</option>
+              </select>
+            </span>
+            <span id="responseFontSizeSelectWrap" class="studio-menu-select-wrap response-option-select-wrap">
+              <select id="responseFontSizeSelect" aria-label="Response text size" title="Adjust right-pane response, preview, and working text size.">
+                <option value="11">Response text: 11px</option>
+                <option value="12">Response text: 12px</option>
+                <option value="12.5">Response text: 12.5px</option>
+                <option value="13">Response text: 13px</option>
+                <option value="13.5" selected>Response text: 13.5px</option>
+                <option value="14">Response text: 14px</option>
+                <option value="14.5">Response text: 14.5px</option>
+                <option value="15">Response text: 15px</option>
+                <option value="15.5">Response text: 15.5px</option>
+                <option value="16">Response text: 16px</option>
+                <option value="18">Response text: 18px</option>
+                <option value="20">Response text: 20px</option>
+              </select>
+            </span>
           </div>
           <div class="response-actions-row history-row">
             <button id="pullLatestBtn" type="button" title="Fetch the latest assistant response when auto-update is off.">Fetch latest response</button>
@@ -12137,7 +12252,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>
@@ -12213,6 +12329,9 @@ 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[] = [];
@@ -12273,6 +12392,21 @@ 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 {
@@ -13573,6 +13707,9 @@ export default function (pi: ExtensionAPI) {
 		}
 		: null;
 
+	const getCurrentStudioSideQuestionThinkingLevels = (): StudioSideQuestionThinking[] =>
+		getStudioSideQuestionThinkingLevels(latestModelRequestCtx?.model ?? lastCommandCtx?.model) as StudioSideQuestionThinking[];
+
 	const getStudioThemeOptions = () => {
 		try {
 			const themes = lastCommandCtx?.ui?.getAllThemes?.() ?? [];
@@ -13608,6 +13745,7 @@ export default function (pi: ExtensionAPI) {
 			modelLabel: currentModelLabel,
 			currentModel: getCurrentStudioModelDescriptor(),
 			thinkingLevel: getThinkingLevelSafe() ?? "off",
+			sideQuestionThinkingLevels: getCurrentStudioSideQuestionThinkingLevels(),
 			piModels: modelOptions,
 			suggestionModels: modelOptions,
 			currentTheme: getCurrentStudioThemeDescriptor(),
@@ -13914,6 +14052,7 @@ export default function (pi: ExtensionAPI) {
 		const payload: Record<string, unknown> = {
 			type: "side_question_state",
 			state: getStudioSideQuestionPublicState(),
+			sideQuestionThinkingLevels: getCurrentStudioSideQuestionThinkingLevels(),
 			webSearchAvailable: Boolean(String(process.env.BRAVE_API_KEY || "").trim()),
 		};
 		if (client) payload.availablePiTools = getPublicStudioSideQuestionToolCatalog();
@@ -14135,6 +14274,7 @@ export default function (pi: ExtensionAPI) {
 		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 thinking = resolveStudioSideQuestionThinking(model, context.thinking) as StudioSideQuestionThinking;
 		const gitSnapshot = context.gitContext
 			? await captureStudioSideQuestionGitSnapshot(contextRoot, { runGit: runStudioSideQuestionGitCommand }) as StudioSideQuestionGitSnapshot
 			: null;
@@ -14173,7 +14313,7 @@ export default function (pi: ExtensionAPI) {
 				customTools: tools,
 				sessionManager: sideSessionManager,
 				model,
-				thinking: context.thinking,
+				thinking,
 				inheritedPrompt: stripStudioDynamicSystemPromptFooter(ctx.getSystemPrompt()),
 			});
 			session = agentRuntime.session;
@@ -14182,7 +14322,7 @@ export default function (pi: ExtensionAPI) {
 				cwd: workingDirectory,
 				sessionManager: sideSessionManager,
 				model,
-				thinkingLevel: context.thinking,
+				thinkingLevel: thinking,
 				tools: activeToolNames,
 				customTools: tools,
 				resourceLoader: createStudioSideQuestionResourceLoader(ctx),
@@ -14215,7 +14355,7 @@ export default function (pi: ExtensionAPI) {
 				tools: selectedPiTools,
 			},
 			modelLabel: formatStudioModelOptionLabel(model),
-			thinking: context.thinking,
+			thinking,
 			messages: [],
 			activity: [],
 			error: context.webSearch && !webAvailable ? "Web search was requested but BRAVE_API_KEY is not configured; this thread will use local context only." : "",
@@ -14393,6 +14533,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() });
@@ -14402,6 +14628,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,
@@ -14423,6 +14659,7 @@ export default function (pi: ExtensionAPI) {
 				modelLabel: currentModelLabel,
 				currentModel: getCurrentStudioModelDescriptor(),
 				thinkingLevel: getThinkingLevelSafe() ?? "off",
+				sideQuestionThinkingLevels: getCurrentStudioSideQuestionThinkingLevels(),
 				piModels: getStudioModelOptions(),
 				suggestionModels: getStudioModelOptions(),
 				currentTheme: getCurrentStudioThemeDescriptor(),
@@ -15372,6 +15609,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;
@@ -15380,14 +15621,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;
 			}
 
@@ -15397,6 +15645,7 @@ export default function (pi: ExtensionAPI) {
 				source: "file",
 				path: result.resolvedPath,
 				resourceDir: dirname(result.resolvedPath),
+				diskRevision: result.diskRevision,
 			};
 			recordStudioDocumentResourceGrants(initialStudioDocument);
 
@@ -15406,12 +15655,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;
@@ -15420,35 +15674,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;
 		}
 
@@ -15472,7 +15743,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",
@@ -15488,6 +15759,7 @@ 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;
@@ -16855,7 +17127,14 @@ export default function (pi: ExtensionAPI) {
 						studioCwd,
 						studioResourceGrantRegistry,
 					);
-					await respondLocalPreviewLinkJson(req, res, requestUrl, resource, serverState, studioResourceGrantRegistry);
+					await respondLocalPreviewLinkJson(
+						req,
+						res,
+						requestUrl,
+						resource,
+						serverState,
+						studioResourceGrantRegistry,
+					);
 				} catch (error) {
 					if (error instanceof StudioResourceGrantRequiredError) {
 						respondStudioResourceGrantRequiredJson(res, error);
@@ -17019,6 +17298,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;
@@ -17034,6 +17339,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();
 
@@ -17046,15 +17352,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();
 			});
 		});
 
@@ -17122,7 +17446,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();
@@ -17148,6 +17477,8 @@ export default function (pi: ExtensionAPI) {
 		await new Promise<void>((resolve) => {
 			state.server.close(() => resolve());
 		});
+		studioWatchedClientPaths.clear();
+		studioFileWatchSubscriptionGenerations.clear();
 		studioWorkspaceStateStore.clear();
 		studioResourceGrantRegistry.clear();
 	};
@@ -17166,6 +17497,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());
@@ -17517,7 +17855,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";
@@ -17624,6 +17962,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.",
@@ -17637,6 +17999,7 @@ export default function (pi: ExtensionAPI) {
 			source: "file",
 			path: file.resolvedPath,
 			resourceDir: ctx.cwd,
+			diskRevision: file.diskRevision,
 		});
 	};
 
@@ -17894,7 +18257,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) {
@@ -17910,11 +18273,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");
@@ -17948,7 +18312,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;
@@ -17974,7 +18339,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,
@@ -17989,6 +18356,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") {
@@ -18011,7 +18380,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();
 
@@ -18042,7 +18411,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"
@@ -18093,7 +18462,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") {
@@ -18101,7 +18470,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"
@@ -18457,6 +18826,7 @@ export default function (pi: ExtensionAPI) {
 				label: file.label,
 				source: "file",
 				path: file.resolvedPath,
+				diskRevision: file.diskRevision,
 			};
 			initialStudioDocument = nextDoc;
 			recordStudioDocumentResourceGrants(nextDoc, ctx.cwd);