pi-studio 0.9.63 → 0.10.1

package/shared/studio-document-hosting.js

@@ -0,0 +1,319 @@
+// Process-scoped document ownership, not durable storage or filesystem authority.
+// The adapter must authenticate workspace IDs and supply a trusted canonical
+// identity resolver. These claims do not authorize filesystem reads or writes.
+// Checkpoint/move commits are synchronous compare-and-swap.
+import { createStudioBuffer, validateStudioBufferWorkspace } from "./studio-buffer-store.js";
+
+const fail = (reason, message, extra = {}) => ({ ok: false, reason, message, ...extra });
+const same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+
+export function studioDocumentMetadataKey(entry, field) {
+	if (entry.metadata[field] !== null) return entry.metadata[field];
+	const source = entry.sourceState;
+	if (source.path) return "file:" + source.path;
+	if (source.draftId) return "draft:" + source.draftId;
+	const kind = source.source || "blank", label = (source.label || "blank").trim().replace(/\s+/g, " ") || kind;
+	return "doc:" + kind + ":" + label;
+}
+export function studioDocumentAuthorityIdentity(entry) {
+	return entry ? [entry.sourceState, entry.resourceDir, studioDocumentMetadataKey(entry, "reviewNotesKey"), studioDocumentMetadataKey(entry, "scratchpadKey")] : null;
+}
+
+export function isStudioPristineBuffer(entry) {
+	return entry.text === "" && entry.baselineText === "" && entry.sourceState.path === null
+		&& entry.sourceState.source === "blank" && ["", "Prompt", "Untitled", "Document"].includes(entry.sourceState.label)
+		&& entry.resourceDir === "" && entry.metadata.reviewNotesKey === null && entry.metadata.scratchpadKey === null;
+}
+export const isStudioPristineWorkspace = state => state.buffers.every(isStudioPristineBuffer);
+
+export function createStudioDocumentCopy(entry, id) {
+	return createStudioBuffer({ ...entry, id, role: "document", revision: 0, baselineText: "", diskRevision: null,
+		sourceState: { source: "blank", label: "Copy of " + (entry.sourceState.label || "document"), path: null, draftId: id,
+			...(entry.sourceState.provenance ? { provenance: entry.sourceState.provenance } : {}) },
+		metadata: { ...entry.metadata, reviewNotesKey: null, scratchpadKey: null } });
+}
+
+export function createStudioDocumentHostingStore(options) {
+	const { makeId, canonicalPath } = options;
+	const now = options.now ?? Date.now;
+	const maxDocuments = options.maxDocuments ?? 256, maxMoves = options.maxMoves ?? 128;
+	const offerLifetimeMs = options.offerLifetimeMs ?? 120_000;
+	const terminalLifetimeMs = options.terminalLifetimeMs ?? 600_000;
+	const workspaces = new Map(), owners = new Map(), paths = new Map(), retired = new Set(), moves = new Map(), pending = new Map();
+	let nextDocumentEpoch = 0;
+	const ownerInfo = owner => owner ? { workspaceId: owner.workspaceId, bufferId: owner.bufferId, mode: owner.mode } : null;
+	function expireOffers() {
+		for (const move of moves.values()) if (move.status === "offered" && now() >= move.expiresAt) cancel(move, "expired");
+		for (const [id, move] of moves) if (move.status !== "offered" && now() - move.terminalAt >= terminalLifetimeMs) moves.delete(id);
+	}
+	function makeMoveRoom() {
+		// Terminal operations advanced the source workspace revision. Forgetting
+		// their explanation cannot make an original delayed Begin current again.
+		for (const [id, move] of moves) {
+			if (moves.size < maxMoves) break;
+			if (move.status !== "offered") moves.delete(id);
+		}
+	}
+	function cancel(move, reason) {
+		if (move.status !== "offered") return outcome(move);
+		const before = workspaces.get(move.sourceWorkspaceId);
+		if (!before) return fail("missing-workspace", "The source workspace is unavailable.");
+		const after = { ...before, revision: before.revision + 1, savedAt: Math.max(now(), before.savedAt + 1) };
+		const planned = plan([after], move.id); if (!planned.ok) return planned;
+		if (options.commitMove) {
+			const stored = options.commitMove({ before: [before], after: planned.states, kind: "cancel", move: outcome(move) });
+			if (!stored?.ok) return stored || fail("unavailable", "Cancellation could not be checkpointed; keep the editor frozen.");
+		}
+		commit(planned); move.status = "cancelled"; move.reason = reason; move.terminalAt = now();
+		if (pending.get(move.sourceWorkspaceId) === move.id) pending.delete(move.sourceWorkspaceId);
+		delete move.source;
+		return outcome(move);
+	}
+	function outcome(move) {
+		return { ok: true, moveId: move.id, status: move.status, bufferId: move.bufferId,
+			sourceWorkspaceId: move.sourceWorkspaceId, targetWorkspaceId: move.targetWorkspaceId ?? null,
+			...(move.reason ? { reason: move.reason } : {}), ...(move.adopted ? { adopted: true } : {}) };
+	}
+	function plan(states, movingId = null) {
+		const checked = [], ids = new Set();
+		for (const value of states) {
+			const result = validateStudioBufferWorkspace(value); if (!result.ok) return result;
+			const state = result.state;
+			if (ids.has(state.workspaceId)) return fail("duplicate-workspace", "One checkpoint per workspace is required.");
+			ids.add(state.workspaceId);
+			const before = workspaces.get(state.workspaceId);
+			if (before && !same(before, state) && (before.mode !== state.mode || state.revision <= before.revision || state.savedAt < before.savedAt)) {
+				return fail("stale-workspace", "The workspace changed. Keep current text and retry explicitly.");
+			}
+			const held = pending.get(state.workspaceId);
+			if (held && held !== movingId) return fail("move-pending", "Finish or cancel the document move before changing this workspace.");
+			checked.push(state);
+		}
+		const nextOwners = new Map(owners), nextPaths = new Map(paths), nextRetired = new Set(retired);
+		const previouslyOwned = new Set();
+		for (const [id, owner] of owners) if (ids.has(owner.workspaceId)) {
+			previouslyOwned.add(id); nextOwners.delete(id); if (owner.path) nextPaths.delete(owner.path);
+		}
+		const added = new Set();
+		for (const state of checked) for (const entry of state.buffers) {
+			if (added.has(entry.id)) return fail("duplicate-document", "A document cannot have two editing locations.");
+			added.add(entry.id);
+			const existing = owners.get(entry.id);
+			if (retired.has(entry.id)) return fail("retired-document", "That document identity was retired. Recover its text as an explicit new copy.");
+			if (existing && existing.workspaceId !== state.workspaceId && (!movingId || moves.get(movingId)?.bufferId !== entry.id)) {
+				return fail("already-open", "This document already has an editing location.", { owner: ownerInfo(existing) });
+			}
+			let path = null;
+			const previous = existing && workspaces.get(existing.workspaceId)?.buffers.find(b => b.id === entry.id);
+			// Capture file identity when backing changes, not on every keystroke or
+			// move. A retargeted/broken symlink must not silently rebind this draft.
+			try { if (entry.sourceState.path) path = previous?.sourceState.path === entry.sourceState.path ? existing.path : canonicalPath(entry.sourceState.path); }
+			catch { return fail("invalid-path", "The document's canonical file identity could not be checked."); }
+			if (path !== null && (typeof path !== "string" || !path || path.includes("\0"))) return fail("invalid-path", "Invalid canonical document path.");
+			let otherId = path && nextPaths.get(path);
+			if (path && !otherId && options.sameFile) {
+				try { otherId = [...nextOwners.values()].find(owner => owner.path && options.sameFile(path, owner.path))?.bufferId; }
+				catch { return fail("invalid-path", "The document's file aliases could not be checked."); }
+			}
+			if (otherId && otherId !== entry.id) return fail("already-open", "This file is already open. Use its existing editor, move it, or make a detached copy.", { owner: ownerInfo(nextOwners.get(otherId)) });
+			const epoch = existing?.workspaceId === state.workspaceId && same(studioDocumentAuthorityIdentity(previous), studioDocumentAuthorityIdentity(entry))
+				? existing.epoch : ++nextDocumentEpoch;
+			const owner = { workspaceId: state.workspaceId, bufferId: entry.id, mode: state.mode, path, epoch };
+			nextOwners.set(entry.id, owner); if (path) nextPaths.set(path, entry.id);
+		}
+		for (const id of previouslyOwned) if (!added.has(id)) {
+			const owner = owners.get(id), entry = workspaces.get(owner.workspaceId).buffers.find(b => b.id === id);
+			if (!isStudioPristineBuffer(entry)) nextRetired.add(id);
+		}
+		if (nextOwners.size + nextRetired.size > maxDocuments) return fail("capacity", "Document ownership capacity reached. No document was evicted.");
+		return { ok: true, states: checked, owners: nextOwners, paths: nextPaths, retired: nextRetired };
+	}
+	function commit(planned) {
+		for (const state of planned.states) workspaces.set(state.workspaceId, state);
+		owners.clear(); for (const [key, value] of planned.owners) owners.set(key, value);
+		paths.clear(); for (const [key, value] of planned.paths) paths.set(key, value);
+		retired.clear(); for (const key of planned.retired) retired.add(key);
+	}
+	const replaceSlot = (state, id, replacement) => ({ ...state, revision: state.revision + 1, savedAt: Math.max(now(), state.savedAt + 1),
+		selectedBufferId: state.selectedBufferId === id ? replacement.id : state.selectedBufferId,
+		order: state.order.map(value => value === id ? replacement.id : value), buffers: state.buffers.map(value => value.id === id ? replacement : value) });
+	const api = {
+		sweep() { expireOffers(); },
+		hasPending: workspaceId => pending.has(workspaceId),
+		pendingId: workspaceId => pending.get(workspaceId) ?? null,
+		pendingMoves: workspaceId => [...moves.values()].filter(m => m.status === "offered" && (m.sourceWorkspaceId === workspaceId || m.targetWorkspaceId === workspaceId)).map(outcome),
+		cancelPending(workspaceId) {
+			const move = moves.get(pending.get(workspaceId));
+			return move ? cancel(move, "connection-closed") : { ok: true };
+		},
+		reclaimPristine(workspaceId) {
+			const state = workspaces.get(workspaceId);
+			if (!state || pending.has(workspaceId) || [...moves.values()].some(m => m.status === "offered" && m.targetWorkspaceId === workspaceId)
+				|| !isStudioPristineWorkspace(state)) return false;
+			for (const entry of state.buffers) owners.delete(entry.id);
+			workspaces.delete(workspaceId);
+			return true;
+		},
+		checkpoint(state) {
+			expireOffers();
+			const before = workspaces.get(state?.workspaceId);
+			if (before && same(before, state)) return { ok: true }; // Exact acknowledgement retry, including while frozen.
+			const planned = plan([state]); if (!planned.ok) return planned;
+			commit(planned); return { ok: true };
+		},
+		workspace: id => workspaces.get(id) ?? null,
+		owner: id => ownerInfo(owners.get(id)),
+		documentAuthorities(workspaceId) {
+			return Object.fromEntries([...owners].filter(([, owner]) => owner.workspaceId === workspaceId).map(([id, owner]) => [id, owner.epoch]));
+		},
+		// Trusted synchronous file-commit hook. Even a same-byte save retires its
+		// original mutation authority, so terminal save receipts can be reclaimed.
+		advanceAuthority(workspaceId, bufferId) {
+			const owner = owners.get(bufferId);
+			if (!owner || owner.workspaceId !== workspaceId) throw new Error("Cannot advance an unowned Document");
+			owner.epoch = ++nextDocumentEpoch;
+			return owner.epoch;
+		},
+		checkAuthority(workspaceId, bufferId, epoch) {
+			const owner = owners.get(bufferId);
+			if (!owner || owner.workspaceId !== workspaceId) return fail("not-owner", "This editing location no longer owns the document.");
+			if (epoch !== owner.epoch) return fail("document-stale", "This request belongs to an earlier document ownership or source generation.");
+			if (moves.get(pending.get(workspaceId))?.bufferId === bufferId) return fail("move-pending", "The moving document is frozen.");
+			return { ok: true };
+		},
+		findFile(path) {
+			try {
+				const canonical = canonicalPath(path);
+				return ownerInfo(owners.get(paths.get(canonical)) || (options.sameFile
+					? [...owners.values()].find(owner => owner.path && options.sameFile(canonical, owner.path)) : null));
+			} catch { return null; }
+		},
+		// Trusted external writers may inspect coordination, not acquire ownership,
+		// file grants or editor authority. Unlike findFile, uncertainty is refusal.
+		checkUnownedFile(path) {
+			try {
+				// The server supplies a normalized absolute target. Keep this shared
+				// identity module browser-loadable (Document clients import it too).
+				const canonical = canonicalPath(path);
+				if (typeof canonical !== "string" || !canonical || canonical.includes("\0")) throw new Error("Invalid canonical identity");
+				if ([...owners.values()].some(owner => owner.path && (owner.path === path || owner.path === canonical
+					|| options.sameFile?.(canonical, owner.path)))) return fail("document-owned", "The HTML export target is owned or claimed by a Document; its file and work were kept.");
+				return { ok: true };
+			} catch { return fail("identity-unknown", "The HTML export target's Document identity could not be verified; nothing was written."); }
+		},
+		checkWrite(workspaceId, bufferId, path) {
+			expireOffers();
+			const owner = owners.get(bufferId), entry = workspaces.get(workspaceId)?.buffers.find(b => b.id === bufferId);
+			if (!owner || owner.workspaceId !== workspaceId || !entry) return fail("not-owner", "This page no longer owns that document.");
+			if (pending.has(workspaceId)) return fail("move-pending", "Resolve the pending move before writing a file.");
+			if (!owner.path || !entry.sourceState.path) return fail("not-file-backed", "Use Save As for a detached document.");
+			try {
+				if (canonicalPath(path) !== owner.path || canonicalPath(entry.sourceState.path) !== owner.path) return fail("source-changed", "The file location changed. Refresh explicitly or use Save As; nothing was written.");
+			} catch { return fail("source-changed", "The file identity could not be checked; nothing was written."); }
+			// Coordination only: the caller must still check disk revision and all
+			// ordinary filesystem authorization immediately before the actual write.
+			return { ok: true };
+		},
+		beginMove({ workspaceId, expectedRevision, bufferId, targetWorkspaceId = null, targetMode = "editor-only", moveId = null, kind = "offer" }) {
+			expireOffers();
+			if (moveId !== null && (typeof moveId !== "string" || !/^[a-f0-9]{48}$/.test(moveId))) return fail("invalid-move", "Invalid move request identity.");
+			const intent = { bufferId, expectedRevision, targetWorkspaceId, targetMode, kind };
+			const retry = moveId && moves.get(moveId);
+			if (retry) {
+				if (retry.sourceWorkspaceId !== workspaceId) return fail("forbidden", "Move identity belongs to another workspace.");
+				if (retry.intent && !same(retry.intent, intent)) return fail("invalid-move", "A move identity cannot be reused for different parameters.");
+				return outcome(retry);
+			}
+			const source = workspaces.get(workspaceId), entry = source?.buffers.find(b => b.id === bufferId);
+			if (!source || source.revision !== expectedRevision || source.selectedBufferId !== bufferId) return fail("stale-workspace", "The originating editor changed. Nothing was moved.");
+			if (entry?.role !== "document") return fail("not-document", "Move Document, not the active Prompt. Make a detached copy of Prompt instead.");
+			if (!["full", "editor-only"].includes(targetMode) || targetWorkspaceId === workspaceId || (targetMode === "full" && !targetWorkspaceId)
+				|| (targetWorkspaceId !== null && (typeof targetWorkspaceId !== "string" || !/^[a-zA-Z0-9_-]{20,128}$/.test(targetWorkspaceId)))) return fail("invalid-target", "Choose a separate document editing location.");
+			if (pending.has(workspaceId)) return fail("move-pending", "This workspace already has a pending move.");
+			makeMoveRoom();
+			if (moves.size >= maxMoves) return fail("capacity", "Too many unresolved moves; current documents were kept.");
+			const id = moveId ?? makeId(); if (moves.has(id)) return fail("duplicate-id", "Move identity could not be allocated.");
+			const move = { id, sourceWorkspaceId: workspaceId, source, bufferId, targetWorkspaceId, targetMode, intent, status: "offered", expiresAt: now() + offerLifetimeMs };
+			moves.set(id, move); pending.set(workspaceId, id);
+			return { ...outcome(move), expiresAt: move.expiresAt };
+		},
+		moveOut({ workspaceId, expectedRevision, bufferId, moveId, destinationId }) {
+			if (workspaces.get(workspaceId)?.mode !== "full") return fail("wrong-mode", "Move out starts from Studio's Document slot.");
+			if (moves.get(moveId)?.status !== "offered" && moves.has(moveId)) return api.beginMove({ workspaceId, expectedRevision, bufferId, moveId, kind: "move-out" });
+			if (typeof destinationId !== "string" || !/^[a-zA-Z0-9_-]{20,128}$/.test(destinationId) || workspaces.has(destinationId)) return fail("invalid-target", "A fresh server-created destination is required.");
+			const started = api.beginMove({ workspaceId, expectedRevision, bufferId, moveId, kind: "move-out" });
+			if (!started.ok || started.status !== "offered") return started;
+			const move = moves.get(moveId), source = workspaces.get(workspaceId), entry = source.buffers.find(b => b.id === bufferId);
+			const nextSource = replaceSlot(source, bufferId, createStudioBuffer({ id: makeId(), role: "document" }));
+			const destination = { version: 2, workspaceId: destinationId, mode: "editor-only", revision: 1, savedAt: now(),
+				activePromptId: null, selectedBufferId: bufferId, order: [bufferId], buffers: [entry] };
+			const planned = plan([nextSource, destination], moveId); if (!planned.ok) return planned;
+			if (options.commitMove) {
+				const stored = options.commitMove({ before: [source, null], after: planned.states, kind: "move-out",
+					move: { ...outcome(move), targetWorkspaceId: destinationId } });
+				if (!stored?.ok) return stored || fail("unavailable", "Move could not be checkpointed; the source was retained.");
+			}
+			commit(planned); move.status = "committed"; move.targetWorkspaceId = destinationId; move.terminalAt = now();
+			pending.delete(workspaceId); delete move.source; return outcome(move);
+		},
+		moveStatus(workspaceId, moveId, incoming = false) {
+			expireOffers(); const move = moves.get(moveId);
+			if (!move || (!incoming && move.sourceWorkspaceId !== workspaceId && move.targetWorkspaceId !== workspaceId)) return fail("forbidden", "Move does not belong to this workspace.");
+			return outcome(move);
+		},
+		declineMove(workspaceId, moveId) {
+			expireOffers(); const move = moves.get(moveId);
+			if (!move || move.targetWorkspaceId !== workspaceId) return fail("forbidden", "Only the bound destination can decline this move.");
+			return cancel(move, "declined");
+		},
+		adoptMove(workspaceId, moveId, bufferId) {
+			const move = moves.get(moveId);
+			if (!move || move.status !== "committed" || move.targetWorkspaceId !== workspaceId || move.bufferId !== bufferId
+				|| owners.get(bufferId)?.workspaceId !== workspaceId) return fail("not-owner", "Only the moved document's current destination can acknowledge adoption.");
+			move.adopted = true; return outcome(move);
+		},
+		cancelMove(workspaceId, moveId) {
+			expireOffers(); let move = moves.get(moveId);
+			if (!move && workspaces.has(workspaceId) && typeof moveId === "string" && /^[a-f0-9]{48}$/.test(moveId)) {
+				// Cancel may overtake an uncertain Begin request. Retain a tombstone so
+				// that late delivery can never re-freeze or move the resumed editor.
+				makeMoveRoom();
+				if (moves.size >= maxMoves) return fail("capacity", "Cancellation could not be recorded. Keep the editor frozen and retry.");
+				move = { id: moveId, sourceWorkspaceId: workspaceId, bufferId: null, status: "offered" };
+				const cancelled = cancel(move, "cancelled"); if (!cancelled.ok) return cancelled;
+				moves.set(moveId, move);
+			}
+			if (!move || move.sourceWorkspaceId !== workspaceId) return fail("forbidden", "Only the originating workspace can cancel this move.");
+			return cancel(move, "cancelled"); // A late Cancel cannot roll back a transfer.
+		},
+		acceptMove({ workspaceId, expectedRevision, targetBufferId, moveId, discardTarget = false }) {
+			expireOffers(); const move = moves.get(moveId);
+			if (!move) return fail("invalid-move", "Move is unavailable; the original editor was kept.");
+			if (move.targetWorkspaceId && move.targetWorkspaceId !== workspaceId) return fail("forbidden", "This move is for another workspace.");
+			if (move.status === "cancelled") return fail("cancelled", "Move was cancelled; the original editor was kept.");
+			if (move.status === "committed") return outcome(move); // Lost acknowledgement: never apply twice.
+			const target = workspaces.get(workspaceId), source = workspaces.get(move.sourceWorkspaceId);
+			if (source !== move.source || target?.revision !== expectedRevision || target?.mode !== move.targetMode || target.workspaceId === source.workspaceId) return fail("stale-workspace", "A participating workspace changed. Nothing was moved.");
+			const placeholder = target.buffers.find(b => b.id === targetBufferId);
+			if (placeholder?.role !== "document") return fail("invalid-target", "Only a Document slot can receive a moved document.");
+			if (discardTarget !== true && (placeholder.sourceState.path || placeholder.text || placeholder.baselineText !== ""
+				|| placeholder.metadata.reviewNotesKey || placeholder.metadata.scratchpadKey)) return fail("target-not-empty", "The destination may contain work. Save/copy it or explicitly confirm replacement before moving here.");
+			if (pending.has(workspaceId)) return fail("move-pending", "The destination is participating in another move.");
+			const entry = source.buffers.find(b => b.id === move.bufferId);
+			const blank = createStudioBuffer({ id: makeId(), role: "document" });
+			const nextSource = replaceSlot(source, entry.id, blank), nextTarget = replaceSlot(target, placeholder.id, entry);
+			const planned = plan([nextSource, nextTarget], move.id); if (!planned.ok) return planned;
+			// The adapter can atomically checkpoint both recovery workspaces here.
+			// No registry ownership is changed if capacity/CAS/storage validation fails.
+			if (options.commitMove) {
+				const stored = options.commitMove({ before: [source, target], after: planned.states, kind: "move", move: { ...outcome(move), targetWorkspaceId: workspaceId } });
+				if (!stored?.ok) return stored || fail("unavailable", "Move could not be checkpointed. Original editors were kept.");
+			}
+			commit(planned); move.status = "committed"; move.targetWorkspaceId = workspaceId; move.terminalAt = now();
+			pending.delete(source.workspaceId); delete move.source;
+			return outcome(move);
+		},
+		clear() { workspaces.clear(); owners.clear(); paths.clear(); retired.clear(); moves.clear(); pending.clear(); },
+	};
+	return Object.freeze(api);
+}

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

@@ -0,0 +1,153 @@
+import { createStudioDocumentCreationIntent } from "./studio-document-escrow.js";
+
+// Identity lookup, not a file read or a new editable owner. Resume is guarded
+// for seen/disconnected tabs; after consent the exact current owner is rechecked.
+export async function openStudioRetainedDocument(options, bufferId, focus = true) {
+ const generation = options.generation();
+ const current = () => generation > 0 && options.generation() === generation && options.current();
+ const query = { operation: "owner", bufferId, focus: false };
+ const validId = value => typeof value === "string" && /^[a-zA-Z0-9_-]{1,128}$/.test(value);
+ try {
+  if (!current()) return false;
+  options.observed?.(bufferId, { live: false });
+  let result = await options.request(query);
+  if (!current()) return false;
+  if (!result.ok || !validId(result.owner?.workspaceId) || result.owner?.bufferId !== bufferId) throw Error(result.message || "That Document is no longer retained. Keep any original tab or recovery copy.");
+  options.observed?.(bufferId, result);
+  if (!focus) return true;
+  const owner = result.owner;
+  const local = owner.workspaceId === options.workspaceId && typeof options.selectOwner === "function";
+  const matches = reply => reply.ok && reply.owner?.workspaceId === owner.workspaceId && reply.owner?.bufferId === owner.bufferId;
+  let resumed = false;
+  if (!local && !result.live && result.seen) {
+   if (!await options.confirm("Reopen the same Document?", "Its tab isn't connected and may have newer edits. Reconnect that tab if you can. Otherwise, reopen the same Document (not a copy)?")) return false;
+   if (!current()) return false;
+   resumed = true;
+  }
+  // Always recheck before opening, including unseen creation URLs and local owners.
+  result = await options.request({ ...query, expectedOwner: owner });
+  if (!current()) return false;
+  if (!matches(result)) throw Error(result.message || "The Document owner changed. Recheck; no new tab was opened.");
+  options.observed?.(bufferId, result);
+  if (!local && !result.live && result.seen && !resumed) throw Error("That editor connected and disconnected while checking. Recheck and choose whether to resume it.");
+  if (local && !result.live) {
+   if (!options.selectOwner(bufferId)) throw Error("The local Document could not be selected. Current work was kept.");
+   options.status("This Document already has an editor here. Its current text was kept; reconnect this window rather than opening another.", "warning");
+  } else if (result.live) {
+   const focused = await options.request({ ...query, focus: true, generation, expectedOwner: owner });
+   if (!current()) return false;
+   if (!matches(focused) || !focused.live) throw Error("The editor changed or disconnected before focus. Keep its original tab and recheck.");
+   options.observed?.(bufferId, focused);
+   if (owner.workspaceId === options.workspaceId && options.selectOwner && !options.selectOwner(bufferId)) throw Error("The local Document could not be selected. Current work was kept.");
+   options.status("Focus requested for the existing Document; switch to it if the browser did not focus it.", "success");
+  } else {
+   if (typeof result.url !== "string" || !result.url) throw Error("The retained editor URL is unavailable. Keep its identity and recheck.");
+   options.open(result.url, resumed);
+   options.status("Requested the same retained Document window. If the browser blocked it, use Show its window; no independent copy was created.", "success");
+  }
+  return true;
+ } catch (e) { if (current()) { options.observed?.(bufferId, { live: false }); options.status(e.message || "The Document owner could not be checked. Keep its identity and recheck.", "warning"); } return false; }
+ finally { if (current()) options.changed(); }
+}
+
+// The retained editor-request tracking. Also read, without writing, before a page may
+// skip the resume question (Sol, candidate67).
+export function createStudioDocumentLaunchIntent(storage, workspaceId) {
+ return createStudioDocumentCreationIntent(storage, "piStudio.bufferWorkspace.v2:" + workspaceId + ":launch", r => {
+  if (!r || Object.keys(r).some(k => !["operationId", "bufferId", "documentEpoch", "expectedRevision", "kind", "path", "sourcePath", "resourceDir", "exportId"].includes(k))
+   || !["blank", "file"].includes(r.kind) || !/^[a-f0-9]{48}$/.test(r.operationId || "") || !/^[a-f0-9]{48}$/.test(r.expectedRevision || "")
+   || !/^[a-zA-Z0-9_-]{1,128}$/.test(r.bufferId || "") || !Number.isSafeInteger(r.documentEpoch) || r.documentEpoch < 1
+   || ["path", "sourcePath", "resourceDir"].some(k => typeof r[k] !== "string" || r[k].length > 16384 || r[k].includes("\0"))
+   || (r.kind === "blank" ? r.path || r.sourcePath || r.resourceDir : !r.path)
+   || (r.exportId !== undefined && (typeof r.exportId !== "string" || !/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/.test(r.exportId)))) throw Error("The retained editor request is invalid. Keep it for inspection; it was not replaced.");
+  return { ...r };
+ }, ["blank", "file"]);
+}
+// A verified creation is independent from opening, seen/live state and focus.
+// Atomic retirement retains token-free destinations; uncertain replies retry v1/v2
+// pending requests unchanged, without borrowing a newer source checkpoint.
+export function createStudioDocumentLaunchController(options) {
+ let flight = null, closed = false, live = false, forgetting = false;
+ const observed = new Map(), ownerFlights = new Map();
+ const nonce = () => Array.from(crypto.getRandomValues(new Uint8Array(24)), b => b.toString(16).padStart(2, "0")).join("");
+ const intents = createStudioDocumentLaunchIntent(options.storage, options.workspaceId);
+ const peek = () => { const saved = intents.peek(); return { ...saved, live: saved.record ? false : live, busy: !!flight || !!ownerFlights.size,
+  destinations: saved.destinations.map(d => ({ ...d, live: observed.get(d.bufferId)?.generation === options.generation() && observed.get(d.bufferId)?.live === true })) }; };
+ const notify = (message, kind = "warning") => { if (!closed) { options.status(message, kind); options.changed(); } };
+ function show(destination, focus = true, presentation = null) {
+  if (closed || (presentation && !presentation.current()) || !destination || !intents.peek().destinations.some(d => d.operationId === destination.operationId && d.bufferId === destination.bufferId)) return Promise.resolve(false);
+  // A source-scoped presenter must not coalesce a fresh explicit Show behind
+  // an older export whose visible origin has since departed.
+  const key = presentation || (destination.bufferId + ":" + focus);
+  if (ownerFlights.has(key)) return ownerFlights.get(key);
+  // Order owner observations across both modes, without dropping or delaying
+  // explicit focus. Later revalidation/focus RPCs supersede older lookup replies.
+  let observation;
+  const beginObservation = () => { observation = { generation: options.generation(), live: false }; observed.set(destination.bufferId, observation); };
+  beginObservation();
+  const work = openStudioRetainedDocument({ ...options, ...(presentation ? { open: presentation.open } : {}),
+   current: () => !closed && (!presentation || presentation.current()),
+   request: body => { beginObservation(); return options.request(body); },
+   observed: (bufferId, result) => { if (observed.get(bufferId) !== observation) return; live = result.live === true; observation.live = live; },
+  }, destination.bufferId, focus).finally(() => { ownerFlights.delete(key); if (!closed) options.changed(); });
+  ownerFlights.set(key, work); return work;
+ }
+ function run(target, open = true, presentation = null) {
+  const current = () => !closed && (!presentation || presentation.current());
+  if (!current() || forgetting) return Promise.resolve(false);
+  if (flight) return flight;
+  flight = (async () => {
+   try {
+    const saved = intents.peek(); if (saved.error) throw Error(saved.error.message);
+    let record = saved.record;
+    if (record && target && ["kind", "path", "sourcePath", "resourceDir", "exportId"].some(k => record.request[k] !== target[k])) throw Error("A different editor request is still tracked. Recheck it or explicitly forget its tracking before opening another Document.");
+    if (!record) {
+     if (!open || !target || options.busy()) return false;
+     // A generated export already checkpointed before rendering. Its presenter
+     // carries that exact authority; a second checkpoint must not silently rebind
+     // older bytes to a newer source. Ordinary New/Open still prepares as before.
+     const retainedProof = target.exportId && presentation?.authority;
+     if (!retainedProof) await options.prepare();
+     if (!current()) return false;
+     const proof = retainedProof || options.authority(); if (!proof?.ok) throw Error(proof?.message || "Checkpoint this editor first.");
+     const stored = intents.capture({ ...target, operationId: nonce(), bufferId: proof.bufferId, documentEpoch: proof.documentEpoch, expectedRevision: proof.expectedRevision });
+     if (!stored.ok) throw Error(stored.message);
+     record = intents.peek().record;
+    } else { const checked = intents.current(); if (!checked.ok) throw Error(checked.message); }
+    if (!current()) return false;
+    const result = await options.request({ ...record.request, operation: "launch", generation: options.generation(), focus: false }, open);
+    if (closed) return false;
+    const completed = intents.complete(result); if (!completed.ok) throw Error(result.message || completed.message);
+    const destination = intents.peek().destinations.find(d => d.operationId === record.request.operationId);
+    presentation?.retained?.(destination ? Object.freeze({ ...destination }) : null);
+    options.changed();
+    // Creation proof/discovery is retained even if its original visible preview
+    // departed while the RPC was in flight. Cancel only automatic presentation.
+    if (!current()) return false;
+    if (open) return show(destination, true, presentation);
+    return show(destination, false);
+   } catch (e) { live = false; if (open) notify(e.message || "Editor outcome unknown. Keep tracking and recheck."); return false; }
+  })().finally(() => { flight = null; if (!closed) options.changed(); });
+  return flight;
+ }
+ const timer = setInterval(() => { if (!closed && !flight && !forgetting && options.generation() && intents.peek().record) void run(null, false); }, 1500);
+ return Object.freeze({
+  start: (target, presentation = null) => run({ kind: target.kind, path: target.path || "", sourcePath: target.sourcePath || "", resourceDir: target.resourceDir || "",
+   ...(target.exportId !== undefined ? { exportId: target.exportId } : {}) }, true, presentation),
+  recheck: () => intents.peek().record ? run(null, true) : show(intents.peek().destinations.at(-1)),
+  ready: async () => { if (intents.peek().record) await run(null, false); else await Promise.all(intents.peek().destinations.map(d => show(d, false))); },
+  openDestination: show, state: peek, busy: () => !!flight || !!ownerFlights.size,
+  needsUnloadConfirmation: () => Boolean(flight || forgetting || ownerFlights.size || peek().error || peek().record || peek().destinations.some(d => !d.live || !options.generation())),
+  async forget() {
+   // Oliver, 13 Oct: a click during an automatic recheck waits for it, then asks.
+   while (flight && !closed) await flight.catch(() => {});
+   if (closed || !intents.peek().record) return false; const before = intents.peek().record;
+   forgetting = true; let agreed;
+   try { agreed = await options.confirm("Forget editor request tracking?", "This does not delete any Document. An uncertain editor may become harder to find. Recheck first. Forget tracking to start another independent request?"); } finally { forgetting = false; }
+   if (!agreed || closed || flight || intents.peek().record !== before) return false;
+   const result = intents.clear(true); if (!result.ok) { notify(result.message); return false; }
+   live = false; notify("Tracking removed. Existing Documents and retained destinations were not deleted.", "success"); return true;
+  },
+  dispose() { closed = true; clearInterval(timer); }
+ });
+}

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

@@ -0,0 +1,96 @@
+// Same-workspace replacement is not a move or a new-tab launch. The buffer
+// client owns its frozen slot and verified before-state; this controller owns
+// transport flights, cancellation and the synchronous DOM-binding boundary.
+export function createStudioDocumentOpenController(options) {
+	let closed = false, flight = null, flightKey = null, cancelFlight = null;
+	const nonce = options.makeOperationId ?? (() => Array.from(crypto.getRandomValues(new Uint8Array(24)), b => b.toString(16).padStart(2, "0")).join(""));
+	const client = () => options.client();
+	const pending = () => client()?.openBackup();
+	const notify = (message, severity = "warning") => { if (!closed) options.status?.(message, severity); };
+	const changed = () => { if (!closed) options.changed?.(); };
+	const fail = message => ({ ok: false, message });
+	// 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"]);
+	async function deliver(owner, record, operation, settings = {}) {
+		const generation = options.generation();
+		const current = () => !closed && client() === owner && generation > 0 && generation === options.generation() && pending()?.record === record;
+		try {
+			if (!current()) return fail("Reconnect the owning editor before checking this open request.");
+			const result = await options.request({ ...record.request, operation, generation });
+			if (!current()) return fail("The opening editor changed; its backup was kept.");
+			if (!result?.ok && operation === "open" && finalOpenRefusals.has(result?.reason)) {
+				await deliver(owner, record, "open-cancel", { quiet: true });
+				notify(result.message || "That file can't be opened here. Current work was kept.");
+				return fail(result.message || "The file was not opened.");
+			}
+			if (!result?.ok) throw Error(result?.message || "The file-open outcome is unknown. Keep the backup and recheck.");
+			// Capture pre-debounce Prompt typing, or detect late affected DOM changes.
+			options.capture?.();
+			const applied = owner.finishOpen(result, () => current() && options.domCurrent(record));
+			if (!applied.ok) throw Error(applied.message);
+			if (result.status === "committed") options.replace?.(record.request.bufferId);
+			if (applied.selectedChanged) options.bind();
+			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");
+			await owner.settled();
+			// Failure to release a server receipt cannot undo verified local adoption.
+			// Send no acknowledgements from an obsolete connection or disposed page.
+			if (!closed && client() === owner && generation === options.generation()) {
+				const proof = owner.hostingAuthority(record.request.bufferId);
+				if (proof.ok) try {
+					await options.request({ ...record.request, operation: "open-ack", generation,
+						acknowledgedRevision: proof.expectedRevision, acknowledgedEpoch: proof.documentEpoch });
+				} catch { /* The bounded server receipt remains retained. */ }
+				if (!closed && client() === owner && generation === options.generation() && result.status === "reused") await options.reuse(record.request, result.owner);
+			}
+			return { ...applied, bufferId: record.request.bufferId };
+		} catch (error) {
+			if (current()) notify((error?.message || "File opening could not be checked.") + " Keep this tab; use Recheck file opening or Cancel pending opening.");
+			return fail(error?.message || "Unknown file-open outcome.");
+		} finally { changed(); }
+	}
+	function tracked(run, key) {
+		flightKey = key;
+		flight = Promise.resolve().then(run).finally(() => { flight = null; flightKey = null; changed(); });
+		changed(); return flight;
+	}
+	return Object.freeze({
+		open(input, isCurrent = () => true) {
+			if (closed) return Promise.resolve(fail("This editor is closed."));
+			const key = JSON.stringify(input);
+			if (flight) return key === flightKey ? flight : Promise.resolve(fail("Resolve the current opening first."));
+			if (pending()?.record || pending()?.error || options.busy?.()) return Promise.resolve(fail("Resolve the retained Document operation first."));
+			const owner = client(), generation = options.generation();
+			return tracked(async () => {
+				try {
+					await options.prepare(input.bufferId, isCurrent);
+					if (closed || client() !== owner || generation !== options.generation() || !isCurrent()) return fail("The editor changed before opening. Current work was kept.");
+					const proof = owner.hostingAuthority(input.bufferId); if (!proof.ok) throw Error(proof.message);
+					const request = { operationId: nonce(), bufferId: input.bufferId, expectedRevision: proof.expectedRevision, documentEpoch: proof.documentEpoch,
+						path: input.path, sourcePath: input.sourcePath || "", resourceDir: input.resourceDir || "", discardTarget: true };
+					const begun = owner.beginOpen(request); if (!begun.ok) throw Error(begun.message);
+					changed(); return await deliver(owner, pending().record, "open");
+				} catch (error) { notify(error.message); return fail(error.message); }
+			}, key);
+		},
+		recheck() {
+			if (flight) return flight;
+			const owner = client(), record = pending()?.record;
+			if (closed || !record) return Promise.resolve(fail("No retained file opening to check."));
+			return tracked(() => deliver(owner, record, "open"), null);
+		},
+		cancel() {
+			if (cancelFlight) return cancelFlight;
+			const owner = client(), record = pending()?.record;
+			if (closed || !record) return Promise.resolve(fail("No retained file opening to cancel."));
+			cancelFlight = deliver(owner, record, "open-cancel").finally(() => { cancelFlight = null; changed(); });
+			return cancelFlight;
+		},
+		active: () => Boolean(flight || cancelFlight || pending()?.record || pending()?.error),
+		state: () => ({ ...pending(), busy: Boolean(flight), cancelling: Boolean(cancelFlight) }),
+		dispose() { closed = true; },
+	});
+}

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

@@ -0,0 +1,21 @@
+import { validateStudioBufferWorkspace } from "./studio-buffer-store.js";
+// One noneditable pre-open workspace backup + immutable intent. No URLs/tokens,
+// no filesystem grant. A timeout never clears it or authorizes a new request.
+export function createStudioDocumentOpenStorage(storage, key, expected) {
+ let loaded=false,raw=null,record=null,error=null;
+ function normalize(value){
+  const r=value?.request,b=validateStudioBufferWorkspace(value?.before,expected);
+  if(value?.version!==1||Object.keys(value).some(k=>!['version','request','before'].includes(k))||!b.ok||!r
+   ||Object.keys(r).some(k=>!['operationId','bufferId','documentEpoch','expectedRevision','path','sourcePath','resourceDir','discardTarget'].includes(k))
+   ||typeof r.operationId!=='string'||!/^[a-f0-9]{48}$/.test(r.operationId)||typeof r.expectedRevision!=='string'||!/^[a-f0-9]{48}$/.test(r.expectedRevision)
+   ||!Number.isSafeInteger(r.documentEpoch)||r.documentEpoch<1||!b.state.buffers.some(n=>n.id===r.bufferId)||r.discardTarget!==true
+   ||['path','sourcePath','resourceDir'].some(k=>typeof r[k]!=='string'||r[k].length>16384||r[k].includes('\0'))||!r.path)throw Error('Invalid retained file-open record. Keep it for inspection.');
+  return Object.freeze({version:1,request:Object.freeze({...r}),before:b.state});
+ }
+ const failure=e=>({ok:false,reason:'open-storage',message:e.message||'File-open backup storage is unavailable.'});
+ function peek(){if(!loaded)try{raw=storage.getItem(key)||null;if(raw?.length>6100000)throw Error('Oversized file-open backup.');record=raw?normalize(JSON.parse(raw)):null;loaded=true;error=null;}catch(e){error=failure(e);}return {record,error};}
+ return Object.freeze({peek,
+  capture(value){try{peek();if(error)return error;if(record)throw Error('Resolve the existing file-open request first.');const next=normalize(value),encoded=JSON.stringify(next);if(encoded.length>6100000)throw Error('File-open backup exceeds its limit. Nothing was opened.');if((storage.getItem(key)||null)!==raw)throw Error('File-open tracking changed independently.');storage.setItem(key,encoded);if(storage.getItem(key)!==encoded)throw Error('File-open backup readback failed.');raw=encoded;record=next;return {ok:true,record};}catch(e){return failure(e);}},
+  clear(operationId){try{peek();if(error)return error;if(!record||record.request.operationId!==operationId)throw Error('The file-open backup changed.');if((storage.getItem(key)||null)!==raw)throw Error('File-open tracking changed independently.');storage.removeItem(key);if(storage.getItem(key))throw Error('File-open backup removal could not be verified.');raw=record=null;return {ok:true};}catch(e){return failure(e);}}
+ });
+}

package/shared/studio-document-paths.js

@@ -0,0 +1,29 @@
+import { realpathSync, statSync } from "node:fs";
+import { resolve, dirname, basename, join } from "node:path";
+
+// Identity only, NOT file access or write authorization. Recovery text remains
+// recoverable when its original file or ancestor directories no longer exist.
+export function canonicalStudioDocumentPath(input, cwd = process.cwd()) {
+	if (typeof input !== "string" || !input.trim() || input.includes("\0")) throw new Error("Invalid Document path");
+	let candidate = resolve(cwd, input.trim());
+	const missing = [];
+	for (;;) {
+		try { return join(realpathSync(candidate), ...missing.reverse()); }
+		catch (error) {
+			if (!["ENOENT", "ENOTDIR"].includes(error.code)) throw error;
+			const parent = dirname(candidate); if (parent === candidate) throw error;
+			missing.push(basename(candidate)); candidate = parent;
+		}
+	}
+}
+
+// Detect existing hard-link aliases without keying ownership by inode: atomic
+// saves replace inodes but keep the same logical filename. Never follow a
+// retargeted captured canonical path to infer a new identity for an old draft.
+export function studioDocumentPathsReferToSameFile(a, b) {
+	try {
+		if (canonicalStudioDocumentPath(a) !== a || canonicalStudioDocumentPath(b) !== b) return false;
+		const left = statSync(a), right = statSync(b);
+		return left.isFile() && right.isFile() && left.dev === right.dev && left.ino === right.ino;
+	} catch { return false; }
+}