pi-studio 0.10.1 → 0.10.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-studio",
-  "version": "0.10.1",
+  "version": "0.10.2",
   "description": "Two-pane browser workspace for pi with prompt/response editing, annotations, critiques, active quiz, prompt/response history, live previews, and tmux-backed REPL/literate REPL workflows",
   "type": "module",
   "license": "MIT",

package/shared/repl-gnuplot-processes.js

@@ -0,0 +1,180 @@
+import { execFile } from "node:child_process";
+import { readFile, lstat, unlink } from "node:fs/promises";
+import { basename } from "node:path";
+import { promisify } from "node:util";
+
+const exec = promisify(execFile);
+export const GNUPLOT_OWNER_ENV = "PI_REPL_GNUPLOT_OWNER";
+export const GNUPLOT_OWNER_OPTION = "@pi_repl_gnuplot_owner";
+export const validGnuplotOwner = (value) => typeof value === "string" && value.length === 32 && /^[a-f0-9]{32}$/.test(value);
+
+// On macOS, ps flattens argv/environment into ambiguous text. Read the native
+// NUL-delimited KERN_PROCARGS2 buffer instead. Only the requested marker leaves
+// this isolated stdlib-only process: never print argv or other environment data.
+const macOwnerScript = String.raw`
+import ctypes, errno, json, struct, sys
+libc = ctypes.CDLL('/usr/lib/libSystem.B.dylib', use_errno=True)
+libc.sysctl.argtypes = [ctypes.POINTER(ctypes.c_int), ctypes.c_uint, ctypes.c_void_p, ctypes.POINTER(ctypes.c_size_t), ctypes.c_void_p, ctypes.c_size_t]
+key = b'PI_REPL_GNUPLOT_OWNER='
+rows = []
+for value in sys.argv[1:]:
+    pid = int(value)
+    try:
+        mib = (ctypes.c_int * 3)(1, 49, pid)
+        size = ctypes.c_size_t()
+        if libc.sysctl(mib, 3, None, ctypes.byref(size), None, 0):
+            raise OSError(ctypes.get_errno(), 'process metadata unavailable')
+        if not 4 <= size.value <= 1048576:
+            raise ValueError('invalid process metadata size')
+        buffer = ctypes.create_string_buffer(size.value)
+        if libc.sysctl(mib, 3, buffer, ctypes.byref(size), None, 0):
+            raise OSError(ctypes.get_errno(), 'process metadata unavailable')
+        data = buffer.raw[:size.value]
+        argc = struct.unpack_from('i', data)[0]
+        if not 1 <= argc <= 16384:
+            raise ValueError('invalid argument count')
+        pos = data.index(b'\0', 4) + 1
+        while pos < len(data) and data[pos] == 0:
+            pos += 1
+        for _ in range(argc):
+            pos = data.index(b'\0', pos) + 1
+        matches = [item[len(key):].decode('ascii') for item in data[pos:].split(b'\0') if item.startswith(key)]
+        if len(matches) > 1:
+            raise ValueError('duplicate ownership marker')
+        marker = matches[0] if matches else None
+        if marker is not None and (len(marker) != 32 or any(c not in '0123456789abcdef' for c in marker)):
+            marker = None
+        rows.append({'pid': pid, 'owner': marker})
+    except OSError as error:
+        rows.append({'pid': pid, 'gone': True} if error.errno == errno.ESRCH else {'pid': pid, 'error': 'process metadata unavailable'})
+    except Exception:
+        rows.append({'pid': pid, 'error': 'invalid process metadata'})
+print(json.dumps(rows))
+`;
+
+export function parseGnuplotCandidates(text, uid) {
+	return text.split("\n").filter((line) => line.trim()).flatMap((line) => {
+		const match = /^\s*(\d+)\s+(\d+)\s+(.+)$/.exec(line);
+		if (!match) throw new Error("Could not parse gnuplot process candidates; refusing unverified cleanup.");
+		const pid = Number(match[1]), ownerUid = Number(match[2]);
+		if (![pid, ownerUid].every(Number.isSafeInteger)) throw new Error("Invalid gnuplot process identity.");
+		// Include the interpreter too: QProcess's short-lived detached launcher
+		// can still have that image before exec'ing gnuplot_qt. Names select
+		// candidates only; they never authorize a signal.
+		return ownerUid === uid && ["gnuplot", "gnuplot_qt"].includes(basename(match[3])) ? [pid] : [];
+	});
+}
+
+export function ownerFromEnvironment(data) {
+	const values = data.toString("utf8").split("\0").filter((value) => value.startsWith(`${GNUPLOT_OWNER_ENV}=`));
+	if (values.length > 1) throw new Error("Duplicate gnuplot ownership marker.");
+	return values.length ? values[0].slice(GNUPLOT_OWNER_ENV.length + 1) : null;
+}
+
+export async function readGnuplotOwners(pids, { platform = process.platform, execute = exec, read = readFile } = {}) {
+	if (!pids.length) return [];
+	if (pids.length > 128 || pids.some((pid) => !Number.isSafeInteger(pid) || pid <= 1)) throw new Error("Invalid or excessive gnuplot process candidates.");
+	if (platform === "darwin") {
+		let result, rows;
+		try {
+			result = await execute("python3", ["-I", "-S", "-c", macOwnerScript, ...pids.map(String)], {
+				timeout: 3000, killSignal: "SIGKILL", maxBuffer: 64 * 1024,
+			});
+		} catch {
+			throw new Error("Could not inspect gnuplot process ownership on macOS; an existing python3 is required. No installation was attempted.");
+		}
+		try { rows = JSON.parse(result.stdout); }
+		catch { throw new Error("Invalid gnuplot ownership inspection result."); }
+		if (!Array.isArray(rows) || rows.length !== pids.length || rows.some((row, i) => row.pid !== pids[i] || (!row.gone && !row.error && row.owner !== null && typeof row.owner !== "string"))) {
+			throw new Error("Invalid gnuplot ownership inspection result.");
+		}
+		return rows;
+	}
+	if (platform === "linux") {
+		return Promise.all(pids.map(async (pid) => {
+			try {
+				const data = await read(`/proc/${pid}/environ`);
+				if (data.length > 1024 * 1024) throw new Error("Excessive process metadata.");
+				const owner = ownerFromEnvironment(data);
+				return { pid, owner: validGnuplotOwner(owner) ? owner : null };
+			} catch (error) {
+				if (error.code === "ENOENT" || error.code === "ESRCH") return { pid, gone: true };
+				throw new Error(`Could not inspect gnuplot ownership for PID ${pid}.`, { cause: error });
+			}
+		}));
+	}
+	throw new Error("Detached gnuplot ownership inspection requires macOS or Linux.");
+}
+
+export async function findOwnedGnuplotProcesses(table, owner, { uid = process.getuid?.(), execute = exec, inspect = readGnuplotOwners } = {}) {
+	if (!validGnuplotOwner(owner)) throw new Error("Invalid gnuplot ownership marker.");
+	const listing = await execute("ps", ["-axo", "pid=,uid=,comm="], { timeout: 3000, maxBuffer: 4 * 1024 * 1024 });
+	// Tty-attached interpreter jobs are already handled by pane ancestry.
+	// Inspect only detached candidates; a text-only session needs no Python
+	// metadata reader when no detached gnuplot processes exist.
+	const candidates = parseGnuplotCandidates(listing.stdout, uid).filter((pid) => table.some((p) => p.pid === pid && p.uid === uid && /^\?+$/.test(p.tty) && !p.state.startsWith("Z")));
+	const rows = await inspect(candidates);
+	const failed = rows.find((row) => row.error);
+	if (failed) throw new Error(`Could not inspect gnuplot ownership for PID ${failed.pid}; refusing unverified cleanup.`);
+	return rows.filter((row) => row.owner === owner && !row.gone).map((row) => table.find((p) => p.pid === row.pid));
+}
+
+// Socket cleanup is separate from process ownership. Remember only paths
+// actually open in a marked process, never a guessed TMPDIR/PID filename.
+export function parseUnixSocketNames(text) {
+	if (text && !text.includes("\0")) throw new Error("Could not parse Unix socket ownership data.");
+	let pid;
+	const entries = [];
+	for (let field of text.split("\0")) {
+		field = field.replace(/^\n+/, "");
+		if (!field || field.startsWith("f")) continue;
+		if (/^p\d+$/.test(field) && Number.isSafeInteger(Number(field.slice(1)))) { pid = Number(field.slice(1)); continue; }
+		if (!pid || !field.startsWith("n")) throw new Error("Invalid Unix socket ownership field.");
+		if (field.startsWith("n/")) {
+			// Linux lsof may append socket type/state even in field output.
+			const name = field.slice(1).replace(/ type=STREAM(?: \([^)]*\))?$/, "");
+			entries.push({ pid, path: name });
+		}
+	}
+	return entries;
+}
+
+async function unixSockets(selection, execute = exec) {
+	try {
+		const result = await execute("lsof", ["-nP", "-a", ...selection, "-U", "-F0pn"], { timeout: 3000, maxBuffer: 4 * 1024 * 1024 });
+		if (result.stderr?.trim()) throw new Error("Unix socket ownership inspection was incomplete.");
+		return parseUnixSocketNames(result.stdout);
+	} catch (error) {
+		if (error.code === 1 && !error.stdout && !error.stderr) return []; // no matching open sockets
+		throw error;
+	}
+}
+
+export async function snapshotGnuplotSockets(p, { execute = exec, stat = lstat } = {}) {
+	const entries = await unixSockets(["-p", String(p.pid)], execute);
+	const sockets = [];
+	for (const entry of entries) {
+		if (entry.pid !== p.pid || basename(entry.path) !== `qtgnuplot${p.pid}`) continue;
+		const info = await stat(entry.path).catch((error) => { if (error.code === "ENOENT") return null; throw error; });
+		if (info?.isSocket() && info.uid === p.uid) sockets.push({ path: entry.path, uid: info.uid, dev: info.dev, ino: info.ino, ctimeMs: info.ctimeMs });
+	}
+	return sockets;
+}
+
+export async function cleanupGnuplotSockets(sockets, { uid = process.getuid?.(), execute = exec, stat = lstat, remove = unlink } = {}) {
+	if (!sockets.length) return [];
+	// Refuse to unlink paths still reported by ANY same-user process, not just
+	// gnuplot. This also catches replacement listeners and shared sockets.
+	const references = await unixSockets(["-u", String(uid)], execute);
+	const warnings = [];
+	for (const socket of sockets) {
+		const current = await stat(socket.path).catch((error) => { if (error.code === "ENOENT") return null; throw error; });
+		if (!current) continue;
+		if (references.some((entry) => entry.path === socket.path) || !current.isSocket() || current.uid !== uid || current.uid !== socket.uid || current.dev !== socket.dev || current.ino !== socket.ino || current.ctimeMs !== socket.ctimeMs) {
+			warnings.push(`Qt socket changed or is still in use; left untouched: ${socket.path}`);
+			continue;
+		}
+		await remove(socket.path).catch((error) => { if (error.code !== "ENOENT") throw error; });
+	}
+	return warnings;
+}

package/shared/repl-session-stop.js

@@ -0,0 +1,285 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { GNUPLOT_OWNER_OPTION, validGnuplotOwner, findOwnedGnuplotProcesses, snapshotGnuplotSockets, cleanupGnuplotSockets } from "./repl-gnuplot-processes.js";
+
+const exec = promisify(execFile);
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+const processKey = (p) => `${p.pid}:${p.uid}:${p.startedAt}`;
+const live = (p) => Boolean(p && !p.state.startsWith("Z"));
+const fingerprintFormat = "#{pid}|#{session_id}|#{session_name}|#{session_created}|#{W:#{window_id}:#{window_linked}:#{P:#{pane_id}:#{pane_pid}:#{pane_dead};};}";
+const paneFormat = "#{pid}\t#{session_id}\t#{session_name}\t#{session_created}\t#{pane_id}\t#{pane_pid}\t#{pane_tty}\t#{pane_dead}\t#{window_id}\t#{window_index}\t#{pane_index}\t#{window_linked}\t#{@pi_repl_gnuplot_owner}\t#{@pi_repl_record_id}";
+
+export function parseStopProcessTable(text) {
+	return text.split("\n").filter((line) => line.trim()).map((line) => {
+		const f = line.trim().split(/\s+/);
+		if (f.length !== 11 || !f.slice(0, 4).every((v) => /^\d+$/.test(v) && Number.isSafeInteger(Number(v)))) throw new Error("Could not parse process ownership data; refusing unsafe shutdown.");
+		return { pid: Number(f[0]), ppid: Number(f[1]), pgid: Number(f[2]), uid: Number(f[3]), tty: f[4], startedAt: f.slice(5, 10).join(" "), state: f[10] };
+	});
+}
+
+export async function readStopProcessTable() {
+	const result = await exec("ps", ["-axo", "pid=,ppid=,pgid=,uid=,tty=,lstart=,stat="], {
+		env: { ...process.env, LC_ALL: "C", TZ: "UTC" }, timeout: 3000, maxBuffer: 4 * 1024 * 1024,
+	});
+	return parseStopProcessTable(result.stdout);
+}
+
+function parsePanes(text) {
+	return text.split("\n").filter((line) => line.trim()).map((line) => {
+		const f = line.split("\t");
+		if (f.length !== 14 || !/^\d+$/.test(f[0]) || !/^\$\d+$/.test(f[1]) || !/^\d+$/.test(f[3]) ||
+			!/^%\d+$/.test(f[4]) || !/^\d+$/.test(f[5]) || !/^\/dev\//.test(f[6]) || !/^[01]$/.test(f[7]) ||
+			!/^@\d+$/.test(f[8]) || !/^\d+$/.test(f[9]) || !/^\d+$/.test(f[10]) || !/^[01]$/.test(f[11])) {
+			throw new Error("Could not identify tmux pane ownership; refusing unsafe shutdown.");
+		}
+		return { serverPid: Number(f[0]), sessionId: f[1], sessionName: f[2], createdAt: f[3], paneId: f[4], pid: Number(f[5]), tty: f[6].slice(5), dead: f[7], windowId: f[8], windowIndex: Number(f[9]), paneIndex: Number(f[10]), linked: f[11], recordId: f[13], gnuplotOwner: f[12] };
+	});
+}
+
+async function readPanes(tmux) {
+	const result = await tmux(["list-panes", "-a", "-F", paneFormat]);
+	if (result.code !== 0) {
+		if (/no server running|(?:error connecting|failed to connect).*?(?:No such file|Connection refused)/i.test(result.stderr)) return [];
+		throw new Error(`Could not inspect tmux while verifying shutdown: ${result.stderr.trim() || `exit ${result.code}`}`);
+	}
+	return parsePanes(result.stdout);
+}
+
+function fingerprint(panes) {
+	const first = panes[0];
+	let windows = "", previousWindow;
+	for (const p of [...panes].sort((a, b) => a.windowIndex - b.windowIndex || a.paneIndex - b.paneIndex)) {
+		if (p.windowId !== previousWindow) {
+			if (previousWindow) windows += ";";
+			windows += `${p.windowId}:${p.linked}:`;
+			previousWindow = p.windowId;
+		}
+		windows += `${p.paneId}:${p.pid}:${p.dead};`;
+	}
+	return `${first.serverPid}|${first.sessionId}|${first.sessionName}|${first.createdAt}|${windows};`;
+}
+
+function closure(table, roots) {
+	const ids = new Set(roots);
+	let changed;
+	do {
+		changed = false;
+		for (const p of table) if (ids.has(p.ppid) && !ids.has(p.pid)) { ids.add(p.pid); changed = true; }
+	} while (changed);
+	return ids;
+}
+
+function protectedProcesses(table, panes, currentPid, serverPid) {
+	// Never include the server as an ownership root: its children include
+	// other REPLs, attached clients and unrelated history loggers.
+	const ids = closure(table, [currentPid, ...panes.filter((p) => p.dead === "0").map((p) => p.pid)]);
+	const byPid = new Map(table.map((p) => [p.pid, p]));
+	let p = byPid.get(currentPid);
+	const visited = new Set();
+	while (p && !visited.has(p.pid)) { visited.add(p.pid); ids.add(p.pid); p = byPid.get(p.ppid); }
+	ids.add(0); ids.add(1); ids.add(serverPid);
+	for (const pane of panes) ids.add(pane.serverPid);
+	return ids;
+}
+
+/** Snapshot-based, session-scoped counterpart to the independent test tracker. */
+export class SessionStopProcesses {
+	constructor({ table, panes, selected, currentPid, uid }) {
+		this.owned = new Map();
+		this.groups = new Map();
+		this.uid = uid;
+		this.currentPid = currentPid;
+		this.serverPid = selected[0].serverPid;
+		this.issues = new Set();
+		const otherPanes = panes.filter((p) => p.sessionId !== selected[0].sessionId);
+		const protectedIds = protectedProcesses(table, otherPanes, currentPid, this.serverPid);
+		const roots = [];
+		for (const pane of selected) {
+			if (pane.linked !== "0" || otherPanes.some((p) => p.paneId === pane.paneId)) throw new Error("A REPL window is linked to another session. Unlink it before stopping; nothing was stopped.");
+			const p = table.find((candidate) => candidate.pid === pane.pid);
+			if (pane.dead !== "0" || !live(p) || p.tty !== pane.tty || p.pgid !== p.pid) {
+				throw new Error(`Cannot verify the runtime owner of pane ${pane.paneId}; nothing was stopped. Inspect dead or detached panes manually.`);
+			}
+			if (protectedIds.has(p.pid) || p.uid !== uid) throw new Error("REPL ownership overlaps Pi, another session or another user; nothing was stopped.");
+			roots.push(p.pid);
+			this.groups.set(p.pgid, p);
+		}
+		const ids = closure(table, roots);
+		for (const p of table) {
+			if (ids.has(p.pid) || (this.groups.has(p.pgid) && p.tty === this.groups.get(p.pgid).tty)) {
+				if (protectedIds.has(p.pid) || p.uid !== uid) throw new Error("Runtime descendants overlap protected processes; nothing was stopped.");
+				this.owned.set(processKey(p), p);
+			}
+		}
+	}
+
+	rememberMarked(processes, table, panes) {
+		const protectedIds = protectedProcesses(table, panes, this.currentPid, this.serverPid);
+		for (const p of processes) {
+			if (!live(p) || p.uid !== this.uid || protectedIds.has(p.pid)) {
+				throw new Error(`Marked gnuplot PID ${p.pid} overlaps a protected process; no signal was sent to it.`);
+			}
+			this.owned.set(processKey(p), p);
+		}
+	}
+
+	refresh(table, panes) {
+		const protectedIds = protectedProcesses(table, panes, this.currentPid, this.serverPid);
+		const byPid = new Map(table.map((p) => [p.pid, p]));
+		const known = table.filter((p) => this.owned.has(processKey(p)));
+		const ids = closure(table, known.filter((p) => !protectedIds.has(p.pid)).map((p) => p.pid));
+		for (const [pgid, leader] of this.groups) {
+			const currentLeader = byPid.get(leader.pid);
+			const members = table.filter((p) => p.pgid === pgid && live(p));
+			if (currentLeader && processKey(currentLeader) !== processKey(leader)) continue; // recycled leader
+			// Do not adopt new processes solely because they share a stale
+			// numeric PGID. Require continuity through a known live member.
+			if (known.some((p) => live(p) && p.pgid === pgid && !protectedIds.has(p.pid))) {
+				for (const p of members) ids.add(p.pid);
+			} else if (members.some((p) => !this.owned.has(processKey(p)))) {
+				this.issues.add(`Unconfirmed survivors in former pane group ${pgid}; manual inspection is required.`);
+			}
+		}
+		for (const p of table) {
+			if (!ids.has(p.pid) && !this.owned.has(processKey(p))) continue;
+			if (protectedIds.has(p.pid) || p.uid !== this.uid) {
+				if (live(p)) this.issues.add(`PID ${p.pid} now overlaps a protected process/session; it was not signalled.`);
+				continue;
+			}
+			this.owned.set(processKey(p), p);
+		}
+		return table.filter((p) => this.owned.has(processKey(p)) && live(p) && !protectedIds.has(p.pid) && p.uid === this.uid);
+	}
+}
+
+export const PI_REPL_STOP_SESSION_NAME = /^pi-repl-(python|julia|r|ghci|clojure|ruby|java|octave|matlab|gnuplot|cpp)$/;
+
+/**
+ * Explicit stop only. Never used by send, startup, reload, or shutdown hooks.
+ * sessionNamePattern names the sessions this host owns; pi-studio passes its own.
+ */
+export async function stopVerifiedReplSession({ tmux, sessionName, sessionNamePattern = PI_REPL_STOP_SESSION_NAME, snapshot = readStopProcessTable, signal = (pid, value) => process.kill(pid, value), currentPid = process.pid, uid = process.getuid?.(), graceMs = 500, termMs = 1000, killMs = 2000, findMarked = findOwnedGnuplotProcesses, snapshotSockets = snapshotGnuplotSockets, cleanupSockets = cleanupGnuplotSockets }) {
+	// A global or sticky pattern keeps state between tests; refuse it rather than misjudge a name.
+	if (!(sessionNamePattern instanceof RegExp) || sessionNamePattern.global || sessionNamePattern.sticky) throw new Error("Verified REPL shutdown needs a plain session-name pattern.");
+	if (typeof uid !== "number" || typeof sessionName !== "string" || !sessionNamePattern.test(sessionName)) throw new Error("Verified REPL shutdown requires a supported local Unix session.");
+	const panes = await readPanes(tmux);
+	const selected = panes.filter((p) => p.sessionName === sessionName);
+	if (!selected.length) throw new Error("The selected session ended or changed before shutdown; no processes were signalled.");
+	const original = selected[0];
+	const gnuplot = sessionName === "pi-repl-gnuplot";
+	const owner = gnuplot && validGnuplotOwner(original.gnuplotOwner) ? original.gnuplotOwner : undefined;
+	const warnings = gnuplot && !owner ? ["Detached gnuplot/Qt helpers cannot be verified: this session has no valid ownership marker. Unattributed detached helpers were left untouched."] : [];
+	function guardOwner(currentPanes) {
+		if (owner && currentPanes.some((p) => (p.serverPid !== original.serverPid || p.sessionId !== original.sessionId || p.createdAt !== original.createdAt) && p.gnuplotOwner === owner)) {
+			throw new Error("Gnuplot ownership marker is shared with another session; refusing ambiguous cleanup.");
+		}
+	}
+	guardOwner(panes);
+	const table = await snapshot();
+	const server = table.find((p) => p.pid === original.serverPid);
+	if (!live(server) || server.uid !== uid) throw new Error("Cannot verify the local tmux server owner; nothing was stopped.");
+	const tracker = new SessionStopProcesses({ table, panes, selected, currentPid, uid });
+	const sockets = new Map(), capturedSockets = new Set();
+	let socketInspectionFailed = false;
+	async function rememberMarked(currentTable, currentPanes) {
+		const marked = await findMarked(currentTable, owner, { uid });
+		tracker.rememberMarked(marked, currentTable, currentPanes);
+		for (const p of marked) {
+			// Native Qt detaches from the tty. Avoid repeatedly inspecting the
+			// interpreter's unrelated open files; this is NOT signal authority.
+			if (!/^\?+$/.test(p.tty) || capturedSockets.has(processKey(p))) continue;
+			try {
+				const paths = await snapshotSockets(p);
+				if (paths.length) {
+					const fresh = (await snapshot()).find((candidate) => candidate.pid === p.pid);
+					if (!live(fresh) || processKey(fresh) !== processKey(p)) { socketInspectionFailed = true; continue; }
+					capturedSockets.add(processKey(p));
+				}
+				for (const entry of paths) sockets.set(entry.path, entry);
+			} catch { socketInspectionFailed = true; }
+		}
+	}
+	if (owner) await rememberMarked(table, panes.filter((p) => p.sessionId !== original.sessionId));
+	const originalFingerprint = fingerprint(selected);
+	const repeatPanes = await readPanes(tmux);
+	const repeatSelected = repeatPanes.filter((p) => p.sessionId === original.sessionId);
+	const repeatTable = await snapshot();
+	guardOwner(repeatPanes);
+	if ((owner && repeatSelected.some((p) => p.gnuplotOwner !== owner)) || !repeatSelected.length || fingerprint(repeatSelected) !== originalFingerprint ||
+		!repeatTable.some((p) => processKey(p) === processKey(server)) ||
+		selected.some((pane) => !repeatTable.some((p) => p.pid === pane.pid && tracker.owned.has(processKey(p))))) {
+		throw new Error("Session ownership changed while preparing shutdown; nothing was stopped.");
+	}
+	if (owner) {
+		await rememberMarked(repeatTable, repeatPanes.filter((p) => p.sessionId !== original.sessionId));
+		// The native metadata/socket readers can take time. Revalidate pane
+		// and server birth identities once more after them, before tmux acts.
+		const fresh = await snapshot();
+		if (!fresh.some((p) => live(p) && processKey(p) === processKey(server)) || selected.some((pane) => !fresh.some((p) => live(p) && p.pid === pane.pid && tracker.owned.has(processKey(p))))) {
+			throw new Error("Session ownership changed during helper inspection; nothing was stopped.");
+		}
+	}
+	// This comparison and kill execute in the same tmux command queue: a
+	// changed/replaced session or newly linked/added pane cannot slip between
+	// the final topology check and kill-session. No runtime input is injected.
+	let condition = `#{==:${fingerprintFormat},${originalFingerprint}}`;
+	if (/^[a-f0-9]{32}$/.test(original.recordId)) condition = `#{&&:${condition},#{==:#{@pi_repl_record_id},${original.recordId}}}`;
+	if (owner) condition = `#{&&:${condition},#{==:#{${GNUPLOT_OWNER_OPTION}},${owner}}}`;
+	const stopped = await tmux(["if-shell", "-F", "-t", original.sessionId, condition, `kill-session -t '${original.sessionId}'`, "display-message -p PI_REPL_STOP_CHANGED"]);
+	if (stopped.code !== 0 || stopped.stdout.includes("PI_REPL_STOP_CHANGED")) throw new Error(`tmux refused or could not complete the stop; no follow-up signals were sent. ${stopped.stderr.trim() || stopped.stdout.trim()}`);
+
+	const signals = [];
+	async function inspect() {
+		const currentPanes = await readPanes(tmux);
+		const currentTable = await snapshot();
+		guardOwner(currentPanes);
+		const sameServer = currentTable.some((p) => processKey(p) === processKey(server));
+		if (sameServer && currentPanes.some((p) => p.serverPid === original.serverPid && p.sessionId === original.sessionId && p.createdAt === original.createdAt)) throw new Error("The original tmux session still exists; no follow-up signals were sent.");
+		if (owner) await rememberMarked(currentTable, currentPanes);
+		return tracker.refresh(currentTable, currentPanes);
+	}
+	async function wait(ms) {
+		const deadline = Date.now() + ms;
+		while (true) {
+			const remaining = await inspect();
+			// Allow a bounded quiet grace for startDetached's launcher to exec;
+			// an empty ancestry snapshot alone does not establish settlement.
+			if ((!remaining.length && !owner) || Date.now() >= deadline) return remaining;
+			await sleep(100);
+		}
+	}
+	async function sendVerified(p, value) {
+		// Fresh pane protection + fresh process birth identity before every
+		// individual signal, including KILL escalation. No pkill/group kills.
+		const remaining = await inspect();
+		if (!remaining.some((candidate) => processKey(candidate) === processKey(p))) return;
+		// Marker inspection can involve a subprocess. Refresh ordinary birth
+		// identities and pane protections again immediately before signalling.
+		const freshPanes = await readPanes(tmux);
+		guardOwner(freshPanes);
+		const fresh = tracker.refresh(await snapshot(), freshPanes);
+		if (!fresh.some((candidate) => processKey(candidate) === processKey(p))) return;
+		try { signal(p.pid, value); signals.push({ pid: p.pid, signal: value }); }
+		catch (error) {
+			if (error.code !== "ESRCH") tracker.issues.add(`Could not send ${value} to verified PID ${p.pid}: ${error.message}`);
+		}
+	}
+	try {
+		let remaining = await wait(graceMs);
+		for (const p of remaining) await sendVerified(p, "SIGTERM");
+		remaining = await wait(termMs);
+		const deadline = Date.now() + killMs;
+		while (remaining.length && Date.now() < deadline) {
+			for (const p of remaining) await sendVerified(p, "SIGKILL");
+			remaining = await wait(100);
+		}
+		if (remaining.length) tracker.issues.add(`Surviving verified PIDs: ${remaining.map((p) => p.pid).join(", ")}.`);
+		if (tracker.issues.size) throw new Error([...tracker.issues].join(" "));
+		if (socketInspectionFailed) warnings.push("Qt processes exited, but their socket files could not be fully inspected; unverified files were left untouched (lsof may be unavailable).");
+		try { warnings.push(...await cleanupSockets([...sockets.values()], { uid })); }
+		catch { warnings.push("Qt processes exited, but socket cleanup could not be fully verified; unverified files were left untouched."); }
+		return { sessionName, processCount: tracker.owned.size, signals, warnings };
+	} catch (error) {
+		throw new Error(`Stop requested for ${sessionName}, but runtime cleanup could not be fully verified: ${error.message} Inspect remaining processes manually; logs and clean records were preserved.`, { cause: error });
+	}
+}

package/shared/studio-browser-launcher.js

@@ -1,4 +1,5 @@
 import { spawn } from "node:child_process";
+import { win32 } from "node:path";
 
 export const STUDIO_TERMINAL_BROWSER_OPEN_TIMEOUT_MS = 5_000;
 export const STUDIO_MUXY_CLI_TIMEOUT_SECONDS = 4;
@@ -78,22 +79,48 @@ export function getStudioCmuxBrowserOpenCommand(target, env = process.env) {
  */
 export function getStudioDefaultBrowserOpenCommand(target, platform = process.platform) {
 	if (platform === "darwin") return { command: "open", args: [target] };
-	if (platform === "win32") return { command: "cmd", args: ["/c", "start", "", target] };
+	// Not cmd /c start, which cuts the URL at each & and expands %NAME% (#5).
+	// url.dll's handler takes the URL as one argument, with no shell.
+	if (platform === "win32") return { command: "rundll32.exe", args: ["url.dll,FileProtocolHandler", target] };
 	return { command: "xdg-open", args: [target] };
 }
 
 /**
- * @param {{ command: string, args: string[] }} openCommand
+ * Build the platform-native invocation that opens a local file in its default app,
+ * or a folder in the file manager.
+ *
+ * @param {string} path
+ * @param {NodeJS.Platform} [platform]
+ * @returns {{ command: string, args: string[], verbatim?: boolean }}
+ */
+export function getStudioDefaultViewerOpenCommand(path, platform = process.platform) {
+	if (platform === "darwin") return { command: "open", args: [path] };
+	// Not cmd /c start, which cuts the path at & and expands %NAME%, even inside quotes;
+	// nor url.dll, which loses non-ASCII names. Explorer reads an unquoted comma as a
+	// switch separator and opens Documents for / separators, so the path is resolved and
+	// passed quoted as is. Windows paths can't contain ", and one that does is refused,
+	// so the quotes can't be closed early (Sol).
+	if (platform === "win32") {
+		if (path.includes("\"")) throw new Error("A Windows path can't contain \".");
+		return { command: "explorer.exe", args: [`"${win32.resolve(path)}"`], verbatim: true };
+	}
+	return { command: "xdg-open", args: [path] };
+}
+
+/**
+ * @param {{ command: string, args: string[], verbatim?: boolean }} openCommand
  * @param {typeof spawn} spawnProcess
  * @returns {Promise<void>}
  */
-function spawnDetachedBrowser(openCommand, spawnProcess) {
+function spawnDetached(openCommand, spawnProcess) {
 	return new Promise((resolve, reject) => {
 		let child;
 		try {
 			child = spawnProcess(openCommand.command, openCommand.args, {
 				stdio: "ignore",
 				detached: true,
+				shell: false,
+				...(openCommand.verbatim ? { windowsVerbatimArguments: true } : {}),
 			});
 		} catch (error) {
 			reject(error);
@@ -216,6 +243,18 @@ export async function openStudioUrlInBrowser(target, options = {}) {
 	}
 
 	const openCommand = getStudioDefaultBrowserOpenCommand(target, options.platform ?? process.platform);
-	await spawnDetachedBrowser(openCommand, options.spawnProcess ?? spawn);
+	await spawnDetached(openCommand, options.spawnProcess ?? spawn);
 	return "system";
 }
+
+/**
+ * Open a local file in its default app, or a folder in the file manager.
+ *
+ * @param {string} path
+ * @param {{ platform?: NodeJS.Platform, spawnProcess?: typeof spawn }} [options]
+ * @returns {Promise<void>}
+ */
+export async function openStudioPathInDefaultViewer(path, options = {}) {
+	const openCommand = getStudioDefaultViewerOpenCommand(path, options.platform ?? process.platform);
+	await spawnDetached(openCommand, options.spawnProcess ?? spawn);
+}

package/shared/studio-buffer-client.js

@@ -306,7 +306,9 @@ export function createStudioBufferClient(options) {
 				if (owned && same(owned, store.get(owned.id))) escrow.resolve(backup.moveId);
 			}
 			const selected = store.get(state.selectedBufferId);
-			return { ok: true, restored: !fromInitial, editor: projectStudioBufferEditor(state), baselineText: selected.baselineText };
+			// restored also covers a launch the server registered before this tab opened;
+			// fromBrowser says this tab had its own copy, as after a reload.
+			return { ok: true, restored: !fromInitial, fromBrowser: Boolean(localState), editor: projectStudioBufferEditor(state), baselineText: selected.baselineText };
 		},
 		capture,
 		select(id) {

package/shared/studio-document-open-client.js

@@ -9,6 +9,8 @@ export function createStudioDocumentOpenController(options) {
 	const notify = (message, severity = "warning") => { if (!closed) options.status?.(message, severity); };
 	const changed = () => { if (!closed) options.changed?.(); };
 	const fail = message => ({ ok: false, message });
+	// Optional narration; it never changes a committed open's outcome (Sol).
+	const opened = bufferId => { try { return options.opened?.(bufferId); } catch { return ""; } };
 	// Refusals the server makes before recording anything: the open certainly didn't happen, so it
 	// is closed through the ordinary Cancel route and its reason shown, not kept as unknown (Oliver, 9 Oct).
 	const finalOpenRefusals = new Set(["too-large", "invalid-document"]);
@@ -34,7 +36,7 @@ export function createStudioDocumentOpenController(options) {
 			changed();
 			if (!settings.quiet) notify(result.status === "cancelled" ? "File opening cancelled. Current work was kept."
 				: result.status === "reused" ? "The file already has an editor. Current work was kept."
-				: "Opened the file in its existing buffer. Other work was kept; nothing was sent.", "success");
+				: opened(record.request.bufferId) || "Opened the file.", "success");
 			await owner.settled();
 			// Failure to release a server receipt cannot undo verified local adoption.
 			// Send no acknowledgements from an obsolete connection or disposed page.