@mulmoclaude/mulmoscript-plugin 4.4.0 → 4.5.1

package/dist/server.cjs

@@ -21,8 +21,8 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 	enumerable: true
 }) : target, mod));
 //#endregion
-const require_plugin = require("./plugin-BOq5YkTl.cjs");
-const require_contract = require("./contract-BhN3yKJC.cjs");
+const require_plugin = require("./plugin-C5JC2lNR.cjs");
+const require_contract = require("./contract-BHqxMUWm.cjs");
 let fs = require("fs");
 let path = require("path");
 path = __toESM(path, 1);
@@ -42,6 +42,29 @@ async function fileToDataUri(filePath, mimeType) {
 	return `data:${mimeType};base64,${(await (0, node_fs_promises.readFile)(filePath)).toString("base64")}`;
 }
 //#endregion
+//#region src/server/types.ts
+/**
+* Host capabilities the server ops run against. Only genuinely
+* host-specific transport lives here — the mulmocast orchestration, path
+* containment, and generation-state tracking are all in-package.
+*/
+/**
+* Which named-root capabilities a host has NOT wired.
+*
+* Pure and exported so the rule can be tested without building a server: the
+* condition used to key on the root COUNT alone, so a host that HAD passed
+* `artifactsFor` was told at every boot that its writes land in the default
+* root — the opposite of what the code then did (#3022).
+*
+* Reads and uploads need nothing from the host, so they never appear here.
+*/
+function missingRootCapabilities(backend) {
+	const missing = [];
+	if (backend.rootScopedGenerationState !== true) missing.push("GENERATION is refused until this host declares `rootScopedGenerationState` (its pending-generation state must carry the root, or it must keep none)");
+	if (backend.artifactsFor === void 0) missing.push("save/update land in the DEFAULT root until this host passes `artifactsFor`");
+	return missing;
+}
+//#endregion
 //#region src/server/mulmoErrorCapture.ts
 var capturedErrors = new node_async_hooks.AsyncLocalStorage();
 var loggerInstalled = false;
@@ -190,11 +213,17 @@ async function withBeatProgress(beats, onBeat, body) {
 }
 /** Map identity for the in-flight tracker. JSON array keeps the three
 *  fields unambiguous (a human-visible delimiter could collide). */
-function generationMapKey(kind, filePath, key) {
-	return JSON.stringify([
+function generationMapKey(kind, filePath, key, root) {
+	const normalized = require_contract.normalizeRoot(root);
+	return normalized === "" ? JSON.stringify([
 		kind,
 		filePath,
 		key
+	]) : JSON.stringify([
+		kind,
+		filePath,
+		key,
+		normalized
 	]);
 }
 /**
@@ -205,19 +234,60 @@ function generationMapKey(kind, filePath, key) {
 function createMulmoScriptServerOps(backend) {
 	const log = backend.log ?? NOOP_LOG;
 	setMulmoErrorCaptureLogger(log);
-	const storiesDir = path.default.resolve(backend.storiesDir);
-	function toStoryRef(absolutePath) {
-		const root = ensureStoriesReal() ?? storiesDir;
-		const rel = path.default.relative(root, absolutePath).split(path.default.sep).join("/");
-		return rel ? `stories/${rel}` : "stories";
-	}
-	let storiesRealCache = null;
-	function ensureStoriesReal() {
-		if (storiesRealCache) return storiesRealCache;
+	const rootDirs = /* @__PURE__ */ new Map([["", path.default.resolve(backend.storiesDir)]]);
+	for (const [id, dir] of Object.entries(backend.extraRoots ?? {})) {
+		const trimmed = id.trim();
+		if (trimmed === "") throw new Error("mulmoScript: extraRoots key must not be empty — the empty id is reserved for the default stories root");
+		if (rootDirs.has(trimmed)) throw new Error(`mulmoScript: extraRoots keys must be distinct after trimming — "${trimmed}" is registered twice`);
+		rootDirs.set(trimmed, path.default.resolve(dir));
+	}
+	warnAboutUnwiredRoots();
+	/**
+	* Tell a host which named-root capabilities it has not wired — and nothing
+	* when it has wired them all.
+	*
+	* The condition used to be the root COUNT alone, so a host that had passed
+	* `artifactsFor` was still told, at every boot, that its writes land in the
+	* default root. That is not a stale wording: it is the opposite of what the
+	* code then does, read by the hosts that got the wiring RIGHT (#3022, from
+	* the consuming host).
+	*
+	* Silence when nothing is missing, because a warning that always fires is
+	* one people learn to skip — and then the host that really did forget
+	* `artifactsFor` cannot tell either. Each clause is emitted only when that
+	* capability is actually absent, so the message says what is true for THIS
+	* host rather than what was true when it was written.
+	*/
+	function warnAboutUnwiredRoots() {
+		if (rootDirs.size <= 1) return;
+		const missing = missingRootCapabilities(backend);
+		if (missing.length === 0) return;
+		log.warn(`extra stories roots registered — reads and uploads work, but ${missing.join(", and ")} (#3019)`, { roots: [...rootDirs.keys()].filter((id) => id !== "") });
+	}
+	/** The registered directory for a wire `root`, or null when the host never
+	*  registered it. Null is a REJECTION, not a fallback to the default: an
+	*  unknown root must not quietly read the workspace's file of the same
+	*  name. */
+	function rootDir(root) {
+		return rootDirs.get(require_contract.normalizeRoot(root)) ?? null;
+	}
+	function toStoryRef(absolutePath, root) {
+		const dir = rootDir(root);
+		if (dir === null) return null;
+		const base = ensureStoriesReal(root) ?? dir;
+		return require_plugin.storyRefWithin(base, absolutePath, path.default);
+	}
+	const storiesRealCache = /* @__PURE__ */ new Map();
+	function ensureStoriesReal(root) {
+		const dir = rootDir(root);
+		if (dir === null) return null;
+		const cached = storiesRealCache.get(dir);
+		if (cached) return cached;
 		try {
-			(0, fs.mkdirSync)(storiesDir, { recursive: true });
-			storiesRealCache = (0, fs.realpathSync)(storiesDir);
-			return storiesRealCache;
+			if (require_contract.normalizeRoot(root) === "") (0, fs.mkdirSync)(dir, { recursive: true });
+			const real = (0, fs.realpathSync)(dir);
+			storiesRealCache.set(dir, real);
+			return real;
 		} catch {
 			return null;
 		}
@@ -233,8 +303,9 @@ function createMulmoScriptServerOps(backend) {
 	* stories/ is a regular directory or a legitimate symlink to another
 	* location. ENOENT and traversal are distinguished (404 vs 400).
 	*/
-	function resolveStory(filePath) {
-		const storiesReal = ensureStoriesReal();
+	function resolveStory(filePath, root) {
+		if (rootDir(root) === null) return opBadRequest("Unknown stories root");
+		const storiesReal = ensureStoriesReal(root);
 		if (!storiesReal) return opServerError("stories directory not available");
 		if (path.default.isAbsolute(filePath)) return opBadRequest("Invalid filePath");
 		const ARTIFACTS_STORIES = "artifacts/stories";
@@ -254,6 +325,19 @@ function createMulmoScriptServerOps(backend) {
 		};
 	}
 	/**
+	* Whether this root is one the host registered.
+	*
+	* Every other root-aware op learns this from `resolveStory`, which needs a
+	* file. `pendingGenerations` needs none — it only filters an in-memory map —
+	* so an unregistered root produced `{ ok: true, pending: [] }`, and a host
+	* typo or a stale card read back as "no work is running" (Codex P2 on
+	* #3015). An unknown root is a question this package cannot answer, and the
+	* answer it must not give is a confident empty one.
+	*/
+	function guardStoryRootRegistered(root) {
+		return rootDir(root) === null ? opBadRequest(`unknown stories root "${require_contract.normalizeRoot(root)}"`) : null;
+	}
+	/**
 	* Realpath containment pre-guard for wire paths handed to the phase-1
 	* core's save/reopen/update executes. The core's own path guard is
 	* lexical (it runs against the generic FileOps, whose read/write follows
@@ -265,11 +349,121 @@ function createMulmoScriptServerOps(backend) {
 	* validation (including the script-vs-filePath mode check) belongs to
 	* the core.
 	*/
-	function guardStoryWirePath(filePath) {
+	function guardStoryWirePath(filePath, root) {
 		if (typeof filePath !== "string" || filePath === "") return null;
-		const resolved = resolveStory(filePath);
+		const resolved = resolveStory(filePath, root);
 		return resolved.ok ? null : resolved;
 	}
+	/**
+	* Whether a GENERATION may run in this root.
+	*
+	* The pair identity is complete inside this package but stops at the host
+	* boundary: a host's per-session store keys pending work by
+	* `(kind, filePath, key)` — `generationKey` in `@mulmobridge/protocol`,
+	* which bridges also consume. Two roots running the same generation in one
+	* session would collapse to one entry, and either completion would clear the
+	* other root's indicator (Codex P1 on #3015).
+	*
+	* Whose hazard it is decides who answers: a host declares
+	* `rootScopedGenerationState` when its own pending state carries the root —
+	* or when it keeps none, which is MulmoTerminal's case. It was refused for a
+	* collision it cannot have (#3019).
+	*
+	* Absent still refuses, so a host that has not thought about this keeps the
+	* shipped behaviour rather than being quietly opened up.
+	*/
+	function guardStoryGenerationRoot(root) {
+		if (require_contract.normalizeRoot(root) === "") return null;
+		const registered = guardStoryRootRegistered(root);
+		if (registered) return registered;
+		if (backend.rootScopedGenerationState === true) return null;
+		return opBadRequest("generating in a non-default stories root is not supported yet");
+	}
+	/**
+	* The write half of the same fail-closed rule.
+	*
+	* It lives in the ops that write rather than at their dispatch sites,
+	* because a per-site guard is a list someone has to remember to extend:
+	* `save` / `updateBeat` / `updateScript` were guarded and the two upload
+	* kinds were not, so an image could still land in a named root
+	* (CodeRabbit on #3015). `save` / `update* ` cannot follow suit — they run
+	* through the package executors, not through these ops — so
+	* `test_server_roots.ts` walks the whole ops surface and fails on any op
+	* that is neither in the read-only allowlist nor refusing.
+	*/
+	/**
+	* Whether a WRITE may target this root.
+	*
+	* Reads are root-aware; writes are not. `executeMulmoScriptSave` and the
+	* update executors run against one `FileOps`, bound by the host to the
+	* default root, so a write naming another root would rewrite the DEFAULT
+	* root's identically-named file and then announce the other one as changed
+	* (#3015 review G1). Closing it was fail-closed: "readable but not yet
+	* writable" beats "wrote somewhere else and said so".
+	*
+	* It opens per root, not globally: the host answers `artifactsFor` for the
+	* roots it can serve, and a root it cannot is still refused. A host that
+	* wires nothing keeps the shipped refusal (#3019).
+	*/
+	function guardStoryWriteRoot(root) {
+		if (require_contract.normalizeRoot(root) === "") return null;
+		const registered = guardStoryRootRegistered(root);
+		if (registered) return registered;
+		return artifactsForRoot(root) === null ? opBadRequest("writing to a non-default stories root is not supported yet") : null;
+	}
+	/**
+	* The FileOps a write to this root must go through.
+	*
+	* The default root keeps the single `artifacts` it always had, byte for
+	* byte. A named root is served only when the host both REGISTERED it
+	* (`extraRoots` — the containment boundary, so a host cannot widen the
+	* addressable set through this back door) and can supply a FileOps for it.
+	*/
+	function artifactsForRoot(root) {
+		const normalized = require_contract.normalizeRoot(root);
+		if (normalized === "") return backend.artifacts;
+		if (rootDir(normalized) === null) return null;
+		const hostOps = backend.artifactsFor?.(normalized);
+		return hostOps === void 0 || hostOps === null ? null : storiesScoped(hostOps);
+	}
+	/**
+	* Address a named root's FileOps the way the READ side addresses it.
+	*
+	* The two sides disagreed about one path segment, and the disagreement was
+	* silent. A read strips `stories/` and resolves under the registered
+	* directory (`<root>/<rel>`); a write handed the executors' wire path
+	* straight to the host's FileOps, which is rooted at that same registered
+	* directory, so the bytes landed in `<root>/stories/<rel>`. `save` then
+	* REPORTED SUCCESS and returned a wire path that could not be read back —
+	* a card pointing at nothing (#3020 review H1, from the consuming host).
+	*
+	* Stripping here makes "the directory you registered is the directory your
+	* FileOps is rooted at" true, which is what a host writes without being
+	* told. The default root is untouched: its FileOps is rooted one level up,
+	* at `<workspace>/artifacts`, and is shared with other plugins.
+	*
+	* A path that is not a stories wire path throws rather than passing
+	* through. Everything reaching here has been through `normalizeStoryPath`
+	* or `storyFilePath`, so one that has not is a bug — and letting it through
+	* would write it somewhere nobody can read, which is the failure this whole
+	* wrapper exists to end.
+	*/
+	function storiesScoped(inner) {
+		const within = (wirePath) => {
+			const relative = require_plugin.storiesRelativePath(wirePath);
+			if (relative === null) throw new Error(`mulmoScript: "${wirePath}" is not a stories path — a named root's FileOps takes stories paths only`);
+			return relative;
+		};
+		return {
+			read: async (wirePath) => inner.read(within(wirePath)),
+			readBytes: async (wirePath) => inner.readBytes(within(wirePath)),
+			write: async (wirePath, data) => inner.write(within(wirePath), data),
+			readDir: async (wirePath) => inner.readDir(within(wirePath)),
+			stat: async (wirePath) => inner.stat(within(wirePath)),
+			exists: async (wirePath) => inner.exists(within(wirePath)),
+			unlink: async (wirePath) => inner.unlink(within(wirePath))
+		};
+	}
 	function ffmpegGuard() {
 		if (backend.isFfmpegAvailable?.() === false) return {
 			ok: false,
@@ -279,6 +473,13 @@ function createMulmoScriptServerOps(backend) {
 		return null;
 	}
 	const inFlightGenerations = /* @__PURE__ */ new Map();
+	/** Emit `root` only when it names a non-default one: an event carrying
+	*  `root: ""` and one carrying nothing must stay indistinguishable to every
+	*  pre-#3014 consumer. */
+	function rootField(root) {
+		const normalized = require_contract.normalizeRoot(root);
+		return normalized === "" ? {} : { root: normalized };
+	}
 	/** Tracker state and events key on the canonical `stories/<rel>` wire
 	*  form: subscribers (the View's pubsub filter, `pendingGenerations`
 	*  callers) match by exact string, so the accepted alias spellings
@@ -288,9 +489,23 @@ function createMulmoScriptServerOps(backend) {
 	function canonicalWirePath(filePath) {
 		return require_plugin.normalizeStoryPath(filePath) ?? filePath;
 	}
-	function publishGeneration(chatSessionId, kind, filePath, key, finished, error) {
+	/**
+	* `error` and `root` travel in an options object, NOT as two trailing
+	* optional positionals.
+	*
+	* They were positional once, and appending `root` to the sixteen call sites
+	* put it in `error`'s slot at the nine that pass no error: every start event
+	* carried `error: "<root>"`, the root was dropped from the key, the tracker
+	* entry was filed under the default root — and because the matching finish
+	* DID pass both, its key differed and the entry was never deleted, leaking
+	* one row per generation for the life of the process. Two adjacent optional
+	* strings cannot be told apart by the type checker, so the shape is the only
+	* thing that can prevent it (#3015 review).
+	*/
+	function publishGeneration(chatSessionId, kind, filePath, key, finished, opts = {}) {
+		const { error, root } = opts;
 		const wirePath = canonicalWirePath(filePath);
-		const mapKey = generationMapKey(kind, wirePath, key);
+		const mapKey = generationMapKey(kind, wirePath, key, root);
 		const existing = inFlightGenerations.get(mapKey);
 		if (finished) {
 			if (existing && existing.count > 1) {
@@ -307,6 +522,7 @@ function createMulmoScriptServerOps(backend) {
 				kind,
 				filePath: wirePath,
 				key,
+				root: require_contract.normalizeRoot(root),
 				count: 1
 			});
 		}
@@ -315,7 +531,8 @@ function createMulmoScriptServerOps(backend) {
 			filePath: wirePath,
 			key,
 			done: finished,
-			...error ? { error } : {}
+			...error ? { error } : {},
+			...rootField(root)
 		};
 		backend.onGenerationEvent?.(chatSessionId, event);
 	}
@@ -326,21 +543,31 @@ function createMulmoScriptServerOps(backend) {
 	* save — reloading there would rebuild the element the caret is in, mid-keystroke. A write
 	* from the agent carries no origin, so everyone reloads.
 	*/
-	function publishScriptChanged(filePath, origin) {
+	function publishScriptChanged(filePath, origin, root) {
 		backend.onScriptChanged?.({
 			filePath: canonicalWirePath(filePath),
-			...origin === void 0 ? {} : { origin }
+			...origin === void 0 ? {} : { origin },
+			...rootField(root)
 		});
 	}
-	/** Snapshot of generations currently in flight for one script — the
-	*  View's mount-time catch-up, filtered to its wire `filePath`. */
-	function pendingGenerations(filePath) {
+	/**
+	* Snapshot of generations currently in flight for one script — the View's
+	* mount-time catch-up.
+	*
+	* Filtered on the PAIR. Filtering on `filePath` alone hands a View watching
+	* `repoB/stories/deck.json` the run started for `repoA`'s identically-named
+	* deck, and the caller cannot discard it because the returned event would
+	* carry no root either (Codex P1 / CodeRabbit on #3015).
+	*/
+	function pendingGenerations(filePath, root) {
 		const wirePath = canonicalWirePath(filePath);
-		return [...inFlightGenerations.values()].filter((entry) => entry.filePath === wirePath).map(({ kind, key }) => ({
+		const wanted = require_contract.normalizeRoot(root);
+		return [...inFlightGenerations.values()].filter((entry) => entry.filePath === wirePath && entry.root === wanted).map(({ kind, key }) => ({
 			kind,
 			filePath: wirePath,
 			key,
-			done: false
+			done: false,
+			...rootField(root)
 		}));
 	}
 	/**
@@ -352,7 +579,7 @@ function createMulmoScriptServerOps(backend) {
 	async function runStoryOp(filePath, options, handler, deps = {}) {
 		const resolver = deps.resolveStory ?? resolveStory;
 		const build = deps.buildContext ?? buildContext;
-		const resolved = resolver(filePath);
+		const resolved = resolver(filePath, options.root);
 		if (!resolved.ok) return resolved;
 		try {
 			const context = await build(resolved.absolutePath, options.force ?? false);
@@ -373,8 +600,11 @@ function createMulmoScriptServerOps(backend) {
 			return opServerError(require_plugin.errorMessage(err));
 		}
 	}
-	async function beatImageOp(filePath, beatIndex) {
-		return runStoryOp(filePath, { operation: "beat-image" }, async ({ context }) => {
+	async function beatImageOp(filePath, beatIndex, root) {
+		return runStoryOp(filePath, {
+			operation: "beat-image",
+			root
+		}, async ({ context }) => {
 			const { imagePath } = (0, mulmocast.getBeatPngImagePath)(context, beatIndex);
 			if (!(0, fs.existsSync)(imagePath)) return {
 				ok: true,
@@ -386,9 +616,10 @@ function createMulmoScriptServerOps(backend) {
 			};
 		});
 	}
-	async function beatAudioOp(filePath, beatIndex) {
+	async function beatAudioOp(filePath, beatIndex, root) {
 		return runStoryOp(filePath, {
 			operation: "beat-audio",
+			root,
 			onContextMissing: () => ({
 				ok: true,
 				audio: null
@@ -410,8 +641,11 @@ function createMulmoScriptServerOps(backend) {
 			};
 		});
 	}
-	async function beatMovieOp(filePath, beatIndex) {
-		return runStoryOp(filePath, { operation: "beat-movie" }, async ({ context }) => {
+	async function beatMovieOp(filePath, beatIndex, root) {
+		return runStoryOp(filePath, {
+			operation: "beat-movie",
+			root
+		}, async ({ context }) => {
 			const { movieFile, soundEffectFile, lipSyncFile } = (0, mulmocast.getBeatMoviePaths)(context, beatIndex);
 			const existing = [
 				lipSyncFile,
@@ -421,12 +655,15 @@ function createMulmoScriptServerOps(backend) {
 			].find((candidate) => (0, fs.existsSync)(candidate));
 			return {
 				ok: true,
-				moviePath: existing ? toStoryRef(existing) : null
+				moviePath: existing ? toStoryRef(existing, root) : null
 			};
 		});
 	}
-	async function characterImageOp(filePath, key) {
-		return runStoryOp(filePath, { operation: "character-image" }, async ({ context }) => {
+	async function characterImageOp(filePath, key, root) {
+		return runStoryOp(filePath, {
+			operation: "character-image",
+			root
+		}, async ({ context }) => {
 			const imagePath = (0, mulmocast.getReferenceImagePath)(context, key, "png");
 			if (!(0, fs.existsSync)(imagePath)) return {
 				ok: true,
@@ -441,46 +678,51 @@ function createMulmoScriptServerOps(backend) {
 	/** Shared "output exists and is newer than the source script" gate for
 	*  movie / PDF status. A stale artifact (script edited after it was
 	*  generated) reports null so the UI re-offers the Generate button. */
-	function freshOutputRef(outputPath, absoluteFilePath) {
+	function freshOutputRef(outputPath, absoluteFilePath, root) {
 		if (!(0, fs.existsSync)(outputPath)) return null;
 		if ((0, fs.statSync)(outputPath).mtimeMs < (0, fs.statSync)(absoluteFilePath).mtimeMs) return null;
-		return toStoryRef(outputPath);
+		return toStoryRef(outputPath, root);
 	}
-	async function movieStatusOp(filePath) {
+	async function movieStatusOp(filePath, root) {
 		return runStoryOp(filePath, {
 			operation: "movie-status",
+			root,
 			onContextMissing: () => ({
 				ok: true,
 				moviePath: null
 			})
 		}, async ({ absoluteFilePath, context }) => ({
 			ok: true,
-			moviePath: freshOutputRef((0, mulmocast.movieFilePath)(context), absoluteFilePath)
+			moviePath: freshOutputRef((0, mulmocast.movieFilePath)(context), absoluteFilePath, root)
 		}));
 	}
-	async function pdfStatusOp(filePath) {
+	async function pdfStatusOp(filePath, root) {
 		return runStoryOp(filePath, {
 			operation: "pdf-status",
+			root,
 			onContextMissing: () => ({
 				ok: true,
 				pdfPath: null
 			})
 		}, async ({ absoluteFilePath, context }) => ({
 			ok: true,
-			pdfPath: freshOutputRef((0, mulmocast.pdfFilePath)(context, PDF_MODE), absoluteFilePath)
+			pdfPath: freshOutputRef((0, mulmocast.pdfFilePath)(context, PDF_MODE), absoluteFilePath, root)
 		}));
 	}
 	async function renderBeatOp(args) {
-		const { filePath, beatIndex, force, chatSessionId } = args;
+		const { filePath, beatIndex, force, chatSessionId, root } = args;
+		const rootGuard = guardStoryGenerationRoot(root);
+		if (rootGuard) return rootGuard;
 		const ffmpeg = ffmpegGuard();
 		if (ffmpeg) return ffmpeg;
 		const mapKey = String(beatIndex);
-		publishGeneration(chatSessionId, "beatImage", filePath, mapKey, false);
+		publishGeneration(chatSessionId, "beatImage", filePath, mapKey, false, { root });
 		let genError;
 		try {
 			const result = await runStoryOp(filePath, {
 				force,
-				operation: "render-beat"
+				operation: "render-beat",
+				root
 			}, async ({ context }) => {
 				await (0, mulmocast.generateBeatImage)({
 					index: beatIndex,
@@ -497,18 +739,24 @@ function createMulmoScriptServerOps(backend) {
 			if (!result.ok) genError = result.error;
 			return result;
 		} finally {
-			publishGeneration(chatSessionId, "beatImage", filePath, mapKey, true, genError);
+			publishGeneration(chatSessionId, "beatImage", filePath, mapKey, true, {
+				error: genError,
+				root
+			});
 		}
 	}
 	async function generateBeatAudioOp(args) {
-		const { filePath, beatIndex, force, chatSessionId } = args;
+		const { filePath, beatIndex, force, chatSessionId, root } = args;
+		const rootGuard = guardStoryGenerationRoot(root);
+		if (rootGuard) return rootGuard;
 		const mapKey = String(beatIndex);
-		publishGeneration(chatSessionId, "beatAudio", filePath, mapKey, false);
+		publishGeneration(chatSessionId, "beatAudio", filePath, mapKey, false, { root });
 		let genError;
 		try {
 			const result = await runStoryOp(filePath, {
 				force,
-				operation: "generate-beat-audio"
+				operation: "generate-beat-audio",
+				root
 			}, async ({ context }) => {
 				await (0, mulmocast.generateBeatAudio)(beatIndex, context, { settings: process.env });
 				const beat = context.studio.script.beats[beatIndex];
@@ -531,17 +779,23 @@ function createMulmoScriptServerOps(backend) {
 			if (!result.ok) genError = result.error;
 			return result;
 		} finally {
-			publishGeneration(chatSessionId, "beatAudio", filePath, mapKey, true, genError);
+			publishGeneration(chatSessionId, "beatAudio", filePath, mapKey, true, {
+				error: genError,
+				root
+			});
 		}
 	}
 	async function renderCharacterOp(args) {
-		const { filePath, key, force, chatSessionId } = args;
-		publishGeneration(chatSessionId, "characterImage", filePath, key, false);
+		const { filePath, key, force, chatSessionId, root } = args;
+		const rootGuard = guardStoryGenerationRoot(root);
+		if (rootGuard) return rootGuard;
+		publishGeneration(chatSessionId, "characterImage", filePath, key, false, { root });
 		let genError;
 		try {
 			const result = await runStoryOp(filePath, {
 				force,
-				operation: "render-character"
+				operation: "render-character",
+				root
 			}, async ({ context }) => {
 				const imageEntries = context.studio.script.imageParams?.images ?? {};
 				const imageEntry = imageEntries[key];
@@ -565,11 +819,17 @@ function createMulmoScriptServerOps(backend) {
 			if (!result.ok) genError = result.error;
 			return result;
 		} finally {
-			publishGeneration(chatSessionId, "characterImage", filePath, key, true, genError);
+			publishGeneration(chatSessionId, "characterImage", filePath, key, true, {
+				error: genError,
+				root
+			});
 		}
 	}
-	async function uploadBeatImageOp(filePath, beatIndex, imageData) {
-		return runStoryOp(filePath, { operation: "upload-beat-image" }, async ({ context }) => {
+	async function uploadBeatImageOp(filePath, beatIndex, imageData, root) {
+		return runStoryOp(filePath, {
+			operation: "upload-beat-image",
+			root
+		}, async ({ context }) => {
 			const { imagePath } = (0, mulmocast.getBeatPngImagePath)(context, beatIndex);
 			const base64 = stripDataUri(imageData);
 			await backend.writeFileAtomic(imagePath, Buffer.from(base64, "base64"));
@@ -579,8 +839,11 @@ function createMulmoScriptServerOps(backend) {
 			};
 		});
 	}
-	async function uploadCharacterImageOp(filePath, key, imageData) {
-		return runStoryOp(filePath, { operation: "upload-character-image" }, async ({ context }) => {
+	async function uploadCharacterImageOp(filePath, key, imageData, root) {
+		return runStoryOp(filePath, {
+			operation: "upload-character-image",
+			root
+		}, async ({ context }) => {
 			const imagePath = (0, mulmocast.getReferenceImagePath)(context, key, "png");
 			const base64 = stripDataUri(imageData);
 			await backend.writeFileAtomic(imagePath, Buffer.from(base64, "base64"));
@@ -629,54 +892,68 @@ function createMulmoScriptServerOps(backend) {
 	* initiating View (and any other mounted View) reloads assets off disk
 	* as they land — the successor of the SSE per-beat events.
 	*/
-	async function generateMovieOp(filePath, chatSessionId) {
+	async function generateMovieOp(filePath, chatSessionId, root) {
+		const rootGuard = guardStoryGenerationRoot(root);
+		if (rootGuard) return rootGuard;
 		const ffmpeg = ffmpegGuard();
 		if (ffmpeg) return ffmpeg;
-		const resolved = resolveStory(filePath);
+		const resolved = resolveStory(filePath, root);
 		if (!resolved.ok) return resolved;
 		const absoluteFilePath = resolved.absolutePath;
 		if (inFlightMovies.has(absoluteFilePath)) return opBadRequest("Movie generation is already in progress for this script");
 		inFlightMovies.add(absoluteFilePath);
-		publishGeneration(chatSessionId, "movie", filePath, "", false);
+		publishGeneration(chatSessionId, "movie", filePath, "", false, { root });
 		let genError;
 		try {
 			const result = await runMovieGeneration(absoluteFilePath, (event) => {
-				publishGeneration(chatSessionId, event.kind === "image" ? "beatImage" : "beatAudio", filePath, String(event.beatIndex), true);
+				publishGeneration(chatSessionId, event.kind === "image" ? "beatImage" : "beatAudio", filePath, String(event.beatIndex), true, { root });
 			});
 			if (!result.ok) {
 				genError = result.error;
 				return opServerError(result.error);
 			}
+			const movieRef = toStoryRef(result.outputPath, root);
+			if (movieRef === null) return opServerError("generated movie is outside the registered stories root");
 			return {
 				ok: true,
-				moviePath: toStoryRef(result.outputPath)
+				moviePath: movieRef
 			};
 		} catch (err) {
 			genError = require_plugin.errorMessage(err);
 			return opServerError(genError);
 		} finally {
 			inFlightMovies.delete(absoluteFilePath);
-			publishGeneration(chatSessionId, "movie", filePath, "", true, genError);
+			publishGeneration(chatSessionId, "movie", filePath, "", true, {
+				error: genError,
+				root
+			});
 		}
 	}
-	function triggerAutoBackgroundMovie(absoluteFilePath, wireFilePath, chatSessionId) {
+	function triggerAutoBackgroundMovie(absoluteFilePath, wireFilePath, chatSessionId, root) {
+		if (guardStoryGenerationRoot(root)) {
+			log.warn("refused an auto background movie in a non-default stories root", {
+				filePath: wireFilePath,
+				root
+			});
+			return;
+		}
 		if (inFlightMovies.has(absoluteFilePath)) return;
 		inFlightMovies.add(absoluteFilePath);
-		runBackgroundMovieGeneration(absoluteFilePath, wireFilePath, chatSessionId);
+		runBackgroundMovieGeneration(absoluteFilePath, wireFilePath, chatSessionId, root);
 	}
-	async function runBackgroundMovieGeneration(absoluteFilePath, wireFilePath, chatSessionId) {
+	async function runBackgroundMovieGeneration(absoluteFilePath, wireFilePath, chatSessionId, root) {
 		const errorSidecarPath = `${absoluteFilePath}.error.txt`;
 		try {
 			(0, fs.unlinkSync)(errorSidecarPath);
 		} catch {}
-		publishGeneration(chatSessionId, "movie", wireFilePath, "", false);
+		publishGeneration(chatSessionId, "movie", wireFilePath, "", false, { root });
 		let genError;
 		try {
 			const result = await runMovieGeneration(absoluteFilePath, (event) => {
 				const eventKind = event.kind === "image" ? "beatImage" : "beatAudio";
 				const key = String(event.beatIndex);
-				publishGeneration(chatSessionId, eventKind, wireFilePath, key, false);
-				setImmediate(() => publishGeneration(chatSessionId, eventKind, wireFilePath, key, true));
+				publishGeneration(chatSessionId, eventKind, wireFilePath, key, false, { root });
+				setImmediate(() => publishGeneration(chatSessionId, eventKind, wireFilePath, key, true, { root }));
 			});
 			if (!result.ok) {
 				genError = result.error;
@@ -700,7 +977,10 @@ function createMulmoScriptServerOps(backend) {
 			});
 		} finally {
 			inFlightMovies.delete(absoluteFilePath);
-			publishGeneration(chatSessionId, "movie", wireFilePath, "", true, genError);
+			publishGeneration(chatSessionId, "movie", wireFilePath, "", true, {
+				error: genError,
+				root
+			});
 		}
 	}
 	async function writeErrorSidecar(errorSidecarPath, message) {
@@ -736,15 +1016,17 @@ function createMulmoScriptServerOps(backend) {
 	}
 	/** Long-held foreground PDF generation (the package View's `generatePdf`
 	*  dispatch) — the PDF sibling of `generateMovieOp`. */
-	async function generatePdfOp(filePath, chatSessionId) {
+	async function generatePdfOp(filePath, chatSessionId, root) {
+		const rootGuard = guardStoryGenerationRoot(root);
+		if (rootGuard) return rootGuard;
 		const ffmpeg = ffmpegGuard();
 		if (ffmpeg) return ffmpeg;
-		const resolved = resolveStory(filePath);
+		const resolved = resolveStory(filePath, root);
 		if (!resolved.ok) return resolved;
 		const absoluteFilePath = resolved.absolutePath;
 		if (inFlightPdfs.has(absoluteFilePath)) return opBadRequest("PDF generation is already in progress for this script");
 		inFlightPdfs.add(absoluteFilePath);
-		publishGeneration(chatSessionId, "pdf", filePath, "", false);
+		publishGeneration(chatSessionId, "pdf", filePath, "", false, { root });
 		let genError;
 		try {
 			const context = await buildContext(absoluteFilePath);
@@ -753,22 +1035,27 @@ function createMulmoScriptServerOps(backend) {
 				return opServerError(genError);
 			}
 			const result = await runPdfGeneration(context, (beatIndex) => {
-				publishGeneration(chatSessionId, "beatImage", filePath, String(beatIndex), true);
+				publishGeneration(chatSessionId, "beatImage", filePath, String(beatIndex), true, { root });
 			});
 			if (!result.ok) {
 				genError = result.error;
 				return opServerError(result.error);
 			}
+			const pdfRef = toStoryRef(result.outputPath, root);
+			if (pdfRef === null) return opServerError("generated PDF is outside the registered stories root");
 			return {
 				ok: true,
-				pdfPath: toStoryRef(result.outputPath)
+				pdfPath: pdfRef
 			};
 		} catch (err) {
 			genError = require_plugin.errorMessage(err);
 			return opServerError(genError);
 		} finally {
 			inFlightPdfs.delete(absoluteFilePath);
-			publishGeneration(chatSessionId, "pdf", filePath, "", true, genError);
+			publishGeneration(chatSessionId, "pdf", filePath, "", true, {
+				error: genError,
+				root
+			});
 		}
 	}
 	return {
@@ -776,6 +1063,10 @@ function createMulmoScriptServerOps(backend) {
 		toStoryRef,
 		resolveStory,
 		guardStoryWirePath,
+		guardStoryRootRegistered,
+		guardStoryWriteRoot,
+		artifactsForRoot,
+		guardStoryGenerationRoot,
 		ffmpegGuard,
 		runStoryOp,
 		publishGeneration,
@@ -874,12 +1165,56 @@ var UPLOAD_KINDS = /* @__PURE__ */ new Set(["uploadBeatImage", "uploadCharacterI
 * FileOps, guarded by the instance's realpath containment
 * (`guardStoryWirePath`) — the core's own guard is lexical.
 */
+/**
+* Stamp the root a successful result acted in.
+*
+* Only on success: a failure carries `code` and `error`, and adding a root to
+* it would invite a reader to treat the pair as addressable when the call did
+* not happen. Only when NON-default, so a result for a call that named no root
+* stays byte-identical to what this package returned before roots existed —
+* which is what keeps every existing card working untouched.
+*/
+function withRoot(result, root) {
+	const normalized = require_contract.normalizeRoot(root);
+	if (normalized === "") return result;
+	if (!isRecord(result) || result.ok !== true) return result;
+	return {
+		...result,
+		root: normalized
+	};
+}
+/** `undefined` when `root` is absent or a string; a failure envelope otherwise. */
+function guardSuppliedRoot(root) {
+	if (root === void 0 || typeof root === "string") return void 0;
+	return {
+		ok: false,
+		code: "bad_request",
+		error: `mulmoScript root must be a string, got ${typeof root}`
+	};
+}
 function createMulmoScriptDispatchHandler(ops) {
-	const executeContext = { files: { artifacts: ops.backend.artifacts } };
+	/**
+	* The executor context for a write, bound to the root it names.
+	*
+	* One `FileOps` was held for the whole handler, so the executors — which
+	* take a WIRE path (`stories/…`) and resolve it against whatever FileOps
+	* they are given — wrote a named root's script into the DEFAULT root's
+	* identically-named file. Choosing here keeps `MulmoScriptExecuteContext`
+	* and every executor unchanged: the root never reaches them, only the right
+	* FileOps does (#3019).
+	*/
+	function executeContextFor(root) {
+		const artifacts = ops.artifactsForRoot(root);
+		return artifacts === null ? null : { files: { artifacts } };
+	}
 	async function saveKind(args) {
-		const guard = ops.guardStoryWirePath(args.filePath);
+		const rootGuard = ops.guardStoryWriteRoot(str(args.root));
+		if (rootGuard) return fromOpFailure(rootGuard);
+		const guard = ops.guardStoryWirePath(args.filePath, str(args.root));
 		if (guard) return fromOpFailure(guard);
-		const outcome = await require_plugin.executeMulmoScriptSave(executeContext, {
+		const context = executeContextFor(str(args.root));
+		if (context === null) return invalidArgs("save");
+		const outcome = await require_plugin.executeMulmoScriptSave(context, {
 			script: args.script,
 			filename: str(args.filename),
 			filePath: str(args.filePath)
@@ -893,11 +1228,15 @@ function createMulmoScriptDispatchHandler(ops) {
 		};
 	}
 	async function updateKind(kind, args) {
-		const guard = ops.guardStoryWirePath(args.filePath);
+		const rootGuard = ops.guardStoryWriteRoot(str(args.root));
+		if (rootGuard) return fromOpFailure(rootGuard);
+		const guard = ops.guardStoryWirePath(args.filePath, str(args.root));
 		if (guard) return fromOpFailure(guard);
-		const outcome = kind === "updateBeat" ? await require_plugin.executeUpdateBeat(executeContext, args) : await require_plugin.executeUpdateScript(executeContext, args);
+		const context = executeContextFor(str(args.root));
+		if (context === null) return invalidArgs(kind);
+		const outcome = kind === "updateBeat" ? await require_plugin.executeUpdateBeat(context, args) : await require_plugin.executeUpdateScript(context, args);
 		if (!outcome.ok) return fromPackageFailure(outcome);
-		ops.publishScriptChanged(str(args.filePath) ?? "", str(args.origin));
+		ops.publishScriptChanged(str(args.filePath) ?? "", str(args.origin), str(args.root));
 		return { ok: true };
 	}
 	const STATUS_OPS = {
@@ -913,30 +1252,37 @@ function createMulmoScriptDispatchHandler(ops) {
 		const statusOp = STATUS_OPS[kind];
 		if (statusOp) {
 			const filePath = str(args.filePath);
-			return filePath ? envelope(await statusOp(filePath)) : invalidArgs(kind);
+			return filePath ? envelope(await statusOp(filePath, str(args.root))) : invalidArgs(kind);
 		}
 		if (kind === "characterImage") {
 			const parsed = keyArgs(args);
-			return parsed ? envelope(await ops.characterImageOp(parsed.filePath, parsed.key)) : invalidArgs(kind);
+			return parsed ? envelope(await ops.characterImageOp(parsed.filePath, parsed.key, str(args.root))) : invalidArgs(kind);
 		}
 		const parsed = beatArgs(args);
 		if (!parsed) return invalidArgs(kind);
-		return envelope(await BEAT_PROBE_OPS[kind](parsed.filePath, parsed.beatIndex));
+		return envelope(await BEAT_PROBE_OPS[kind](parsed.filePath, parsed.beatIndex, str(args.root)));
+	}
+	/** Movie and PDF take the whole script; the other generate kinds take a beat
+	*  or a character within it. */
+	async function wholeScriptGenerationKind(kind, args) {
+		const filePath = str(args.filePath);
+		if (!filePath) return invalidArgs(kind);
+		const chatSessionId = str(args.chatSessionId);
+		const root = str(args.root);
+		return envelope(kind === "generateMovie" ? await ops.generateMovieOp(filePath, chatSessionId, root) : await ops.generatePdfOp(filePath, chatSessionId, root));
 	}
 	async function generateKind(kind, args) {
+		if (kind === "generateMovie" || kind === "generatePdf") return wholeScriptGenerationKind(kind, args);
 		const chatSessionId = str(args.chatSessionId);
+		const root = str(args.root);
 		const force = args.force === true;
-		if (kind === "generateMovie" || kind === "generatePdf") {
-			const filePath = str(args.filePath);
-			if (!filePath) return invalidArgs(kind);
-			return envelope(kind === "generateMovie" ? await ops.generateMovieOp(filePath, chatSessionId) : await ops.generatePdfOp(filePath, chatSessionId));
-		}
 		if (kind === "renderCharacter") {
 			const parsed = keyArgs(args);
 			return parsed ? envelope(await ops.renderCharacterOp({
 				...parsed,
 				force,
-				chatSessionId
+				chatSessionId,
+				root
 			})) : invalidArgs(kind);
 		}
 		const parsed = beatArgs(args);
@@ -944,11 +1290,13 @@ function createMulmoScriptDispatchHandler(ops) {
 		return envelope(kind === "renderBeat" ? await ops.renderBeatOp({
 			...parsed,
 			force,
-			chatSessionId
+			chatSessionId,
+			root
 		}) : await ops.generateBeatAudioOp({
 			...parsed,
 			force,
-			chatSessionId
+			chatSessionId,
+			root
 		}));
 	}
 	async function uploadKind(kind, args) {
@@ -956,33 +1304,43 @@ function createMulmoScriptDispatchHandler(ops) {
 		if (!imageData) return invalidArgs(kind);
 		if (kind === "uploadCharacterImage") {
 			const parsed = keyArgs(args);
-			return parsed ? envelope(await ops.uploadCharacterImageOp(parsed.filePath, parsed.key, imageData)) : invalidArgs(kind);
+			return parsed ? envelope(await ops.uploadCharacterImageOp(parsed.filePath, parsed.key, imageData, str(args.root))) : invalidArgs(kind);
 		}
 		const parsed = beatArgs(args);
 		if (!parsed) return invalidArgs(kind);
-		return envelope(await ops.uploadBeatImageOp(parsed.filePath, parsed.beatIndex, imageData));
+		return envelope(await ops.uploadBeatImageOp(parsed.filePath, parsed.beatIndex, imageData, str(args.root)));
 	}
-	return async (args) => {
-		const kind = str(args.kind);
-		if (!kind) return invalidArgs("<missing>");
+	async function pendingKind(kind, args) {
+		const filePath = str(args.filePath);
+		if (!filePath) return invalidArgs(kind);
+		const root = str(args.root);
+		const rootGuard = ops.guardStoryRootRegistered(root);
+		if (rootGuard) return fromOpFailure(rootGuard);
+		return {
+			ok: true,
+			pending: ops.pendingGenerations(filePath, root)
+		};
+	}
+	/** Which handler serves this kind. Routing only — the caller tags the answer. */
+	async function route(kind, args) {
 		if (kind === "save") return saveKind(args);
 		if (kind === "updateBeat" || kind === "updateScript") return updateKind(kind, args);
 		if (PROBE_KINDS.has(kind)) return probeKind(kind, args);
 		if (GENERATE_KINDS.has(kind)) return generateKind(kind, args);
 		if (UPLOAD_KINDS.has(kind)) return uploadKind(kind, args);
-		if (kind === "pendingGenerations") {
-			const filePath = str(args.filePath);
-			if (!filePath) return invalidArgs(kind);
-			return {
-				ok: true,
-				pending: ops.pendingGenerations(filePath)
-			};
-		}
+		if (kind === "pendingGenerations") return pendingKind(kind, args);
 		return {
 			ok: false,
 			code: "bad_request",
 			error: `unknown mulmoScript dispatch kind "${kind}"`
 		};
+	}
+	return async (args) => {
+		const kind = str(args.kind);
+		if (!kind) return invalidArgs("<missing>");
+		const malformedRoot = guardSuppliedRoot(args.root);
+		if (malformedRoot) return malformedRoot;
+		return withRoot(await route(kind, args), str(args.root));
 	};
 }
 //#endregion