@animus-ui/next-plugin 0.1.7 → 0.1.9

package/dist/index.mjs

@@ -1,8 +1,8 @@
-import { t as __require } from "./chunk-y_GBKt04.mjs";
-import { a as getSharedExternalDirs, c as setAnalysisPromise, d as setSharedEngine, f as setSharedExternalDirs, i as getSharedCss, l as setManifestJson, m as setSharedSystemProps, n as getAnalysisPromise, o as getSharedExternalEntries, p as setSharedExternalEntries, s as resetAnalysisPromise, t as engineApi, u as setSharedCss } from "./singleton-BKALu7Mk.mjs";
-import { DEFAULT_EXTENSIONS, assembleStylesheet, assertNoRetiredEngineSelection, buildPathAliasesJson, buildSystemPropsModule, clearEngineCache, collectExternalPackageSources, contentHash, discoverFiles, enforceExternalTokenContracts, extractSystemFilePackages, findAssetSpecifiers, findPackageRoot, formatRustTimingWaterfall, loadSystemConfig, mergeExternalKeyframes, postProcessCss, preprocessMdx, readTsconfigAliasPairs, resolveAssetFile, resolveLightningTargets, runProjectAnalysis, serializeStaticCss, staleDistIncludesMessage, substituteAssetPlaceholders, toWatchKeys, unresolvableIncludesMessage } from "@animus-ui/extract/pipeline";
-import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, statSync, unlinkSync, watch, writeFileSync } from "fs";
-import { basename, dirname, extname, join, relative, resolve, sep } from "path";
+import { S as __require, _ as replacementEpochPath, a as REPLACEMENT_EPOCH_ARTIFACT, b as stylesPath, c as SYSTEM_PROPS_ARTIFACT, f as envelopeCssArtifact, g as readJsonEnvelope, h as readCssEnvelope, i as MANIFEST_ARTIFACT, l as analysisCommitPath, n as ANALYSIS_INPUTS_ARTIFACT, o as SESSION_ASSETS_DIR, p as envelopeJsonArtifact, r as ANALYSIS_STATUS_ARTIFACT, s as STYLES_ARTIFACT, t as ANALYSIS_COMMIT_ARTIFACT, v as sessionArtifactDir, x as systemPropsPath, y as sessionsRootDir } from "./session-paths-DfYIPDcM.mjs";
+import { C as setSharedExternalEntries, S as setSharedExternalDirs, T as setWatchTransaction, _ as setOwningWatchSession, b as setSharedCss, d as getSharedExternalEntries, f as getWatchTransaction, g as setManifestJson, h as setAnalyzedHashes, l as getSharedCss, m as setAnalysisPromise, n as engineApi, o as getOwningWatchSession, p as resetAnalysisPromise, r as getAnalysisPromise, s as getReplacementEpoch, t as claimProcessSessionId, u as getSharedExternalDirs, v as setReplacementEpoch, w as setSharedSystemProps, x as setSharedEngine, y as setSessionArtifactDir } from "./singleton-BjSsGjsg.mjs";
+import { DEFAULT_EXTENSIONS, assembleStylesheet, assertNoErrorDiagnostics, assertNoRetiredEngineSelection, buildPathAliasesJson, buildSystemPropsModule, clearEngineCache, collectExternalPackageSources, contentHash, createSourceIdentity, discoverFiles, enforceExternalTokenContracts, excludeCollectedPackages, extractSystemFilePackages, findAssetSpecifiers, findPackageRoot, firstOwners, formatRustTimingWaterfall, hashReplacementPlans, isExcludedPackageRelativePath, isPathWithinRoot, loadSystemConfig, mergeExternalKeyframes, postProcessCss, preprocessMdx, readTsconfigAliasPairs, resolveAssetFile, resolveLightningTargets, runProjectAnalysis, serializeStaticCss, sharesVolumeRoot, snapshotFilePlans, staleDistIncludesMessage, substituteAssetPlaceholders, toWatchKeys, unresolvableIncludesMessage, walkPackageSources } from "@animus-ui/extract/pipeline";
+import { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, unlinkSync, watch, writeFileSync } from "fs";
+import { basename, dirname, extname, join, relative, resolve } from "path";
 import { fileURLToPath } from "url";
 //#region src/resolve-packages.ts
 /**
@@ -94,6 +94,21 @@ function logBuildTimings(bt, rustTiming, log, verbose) {
 * alias harvesting must skip.
 */
 const ANIMUS_CSS_MODULE_ID = ".animus/styles.css";
+/** Retention window for sibling session directories (design D2). */
+const SESSION_DIR_MAX_AGE_MS = 1440 * 60 * 1e3;
+/** Watchdog added to the debounce ceiling for status deadlines (D3). */
+const STATUS_WATCHDOG_MS = 2e3;
+/** Flat legacy `.animus/` artifacts removed at session start — unreachable
+*  by session-scoped loaders and no longer written by anyone. */
+const LEGACY_FLAT_ARTIFACTS = [
+	MANIFEST_ARTIFACT,
+	ANALYSIS_INPUTS_ARTIFACT,
+	STYLES_ARTIFACT,
+	SYSTEM_PROPS_ARTIFACT,
+	REPLACEMENT_EPOCH_ARTIFACT,
+	ANALYSIS_COMMIT_ARTIFACT,
+	ANALYSIS_STATUS_ARTIFACT
+];
 /** Default path fragments excluded from source discovery (full + watch). */
 const DEFAULT_EXCLUDE = [
 	"node_modules",
@@ -128,15 +143,18 @@ var ExtractionSession = class {
 	/** Physical asset files registered with the host watcher. */
 	assetDependencyPaths = /* @__PURE__ */ new Set();
 	assetDependencyKeys = /* @__PURE__ */ new Set();
-	/** When set (Turbopack orchestration), every analysis also persists
-	*  `.animus/analysis-inputs.json` so isolated loader workers can hydrate.
-	*  Webpack mode leaves this off — its loader shares the process. */
-	persistAnalysisInputs = false;
 	/** Emitter identity override for the system-props module id. Webpack mode
 	*  (null) injects the absolute `.animus/system-props.js` path, resolved by
 	*  NormalModuleReplacement; Turbopack rejects absolute-path imports, so
 	*  its driver sets the virtual id that `resolveAlias` maps to disk. */
 	systemPropsModuleId = null;
+	/** Whether the analysis-inputs hydration corpus is serialized + written.
+	*  False (webpack mode): the loader shares the pipeline process and reads
+	*  the manifest from memory — the corpus is never persisted. True is set
+	*  by the Turbopack orchestration driver, whose isolated loader workers
+	*  replay it (spec: next-turbopack-integration, "Manifest disk artifact" /
+	*  "Webpack mode skips the hydration corpus"). */
+	persistAnalysisInputs = false;
 	/** Absolute directory prefixes for external DS packages (loader allowlisting). */
 	externalPackageDirs = [];
 	/** Absolute package dir → owning specifier (cross-source correlation). */
@@ -145,6 +163,45 @@ var ExtractionSession = class {
 	externalFileOwners = {};
 	/** External package specifier → absolute source entry path. */
 	externalSourceEntries = /* @__PURE__ */ new Map();
+	/** SourceId derivation authority for the current generation (openspec:
+	*  external-source-watch-ingestion, design D2) — canonical roots
+	*  realpath'd once per full pipeline; alias→SourceId associations
+	*  recorded while files exist so deletion resolves through the cache. */
+	sourceIdentity = null;
+	/** Canonical admitted external root → declared specifiers (set-valued
+	*  ownership, design D2; duplicate specifiers resolving to one canonical
+	*  root share it). Engine watch wiring and tests read this. */
+	externalRootOwners = /* @__PURE__ */ new Map();
+	/** Canonical external root → the extension set its collection walk used
+	*  (widened for dist-only roots); rewalks and classification share it. */
+	externalRootExtensions = /* @__PURE__ */ new Map();
+	/** Canonical admitted external watch roots — the engine-side watch
+	*  surface (webpack contextDependencies / Turbopack watchers). */
+	externalWatchRoots = [];
+	/** Canonical external root → (raw sourceKey → {raw content hash, recorded
+	*  abs spelling}): the previous-generation inventory a dirty-root rewalk
+	*  diffs against (design D3). Raw hashes — MDX preprocessing never skews
+	*  the diff; the recorded abs path is a registered deletion alias, so a
+	*  reconstructed deletion always resolves through cached identity. */
+	externalInventory = /* @__PURE__ */ new Map();
+	/** Sticky diagnostics (design D5/D7): stable key → message, re-surfaced
+	*  on every full pipeline until the underlying condition clears. */
+	stickyDiagnostics = /* @__PURE__ */ new Map();
+	/** Volume-membership predicate for the cross-volume gate (design D5).
+	*  Injected seam: the shared predicate only discriminates on Windows
+	*  (win32 semantics are unit-tested via path.win32), so runtime tests
+	*  drive the gate through this. */
+	sharesProjectVolume = sharesVolumeRoot;
+	/** Orchestrator seams (openspec: external-source-watch-ingestion, design
+	*  D4). `onExternalRootResolved` fires per volume-admitted external root
+	*  DURING collection — after resolution, BEFORE that root's sources are
+	*  walked — so a watching host can open its handle with no blind gap
+	*  between scan and watch. `onExternalRootsCommitted` fires once after a
+	*  successful full-pipeline publication with the complete admitted
+	*  canonical root set (the host's promote/replay/close-old phase; a
+	*  failed pipeline never fires it, so the host rolls back). */
+	onExternalRootResolved = null;
+	onExternalRootsCommitted = null;
 	options;
 	staticCssJson;
 	system = null;
@@ -158,15 +215,49 @@ var ExtractionSession = class {
 	/** Loader-reported dependency paths for bundler watch registration. */
 	systemDependencyPaths = [];
 	systemDependencyHashes = /* @__PURE__ */ new Map();
-	lastCssHash = null;
 	lastSystemPropsHash = null;
-	lastManifestHash = null;
-	lastAnalysisInputsHash = null;
+	/** Per-payload write guards: payloadHash gates rewrites (byte-identical
+	*  payloads leave disk untouched); diskHash is the hash of the CURRENT
+	*  disk bytes (envelope included) recorded in the analysis-commit. null =
+	*  not yet seeded (first publication reads the artifact's envelope so a
+	*  same-session restart never rewrites byte-identical artifacts). */
+	artifactRecords = {
+		manifest: null,
+		inputs: null,
+		styles: null
+	};
+	/** Last written analysis-commit; null = seeded from disk on first use. */
+	lastCommit = null;
+	/** Session identity — claimed once per PROCESS (one Next invocation),
+	*  adopted by every subsequent session instance so all compilers share
+	*  one artifact tree (design D2: `next dev`/`next build` co-writing are
+	*  separate processes and therefore separate sessions). */
+	sessionId = claimProcessSessionId();
+	/** Epoch value of the last published analysis; null = not yet known
+	*  (seeded from the session dir's artifact on first publication so a
+	*  same-session restart with unchanged plans never rewrites bytes). */
+	lastEpochValue = null;
+	/** Watcher debounce ceiling feeding status deadlines (design D3). */
+	debounceCeilingMs = 75;
+	/** Test seam: observes every session-artifact write (name, content)
+	*  post-rename — write ORDER is part of the transaction contract. */
+	onArtifactWrite = null;
+	/** Status attempt bookkeeping (design D3). */
+	statusAttemptId = 0;
+	statusAttemptOpen = false;
+	/** Debounce-window observations pending analysis (sourceKey → hash). */
+	debouncePending = /* @__PURE__ */ new Map();
+	/** Session-start hygiene (pruning + legacy cleanup) runs once. */
+	sessionStartHygieneDone = false;
 	lcssTargets = null;
 	constructor(options) {
 		this.options = options;
 		this.staticCssJson = serializeStaticCss(options.staticCss);
 	}
+	/** This session's artifact directory. Requires `rootDir` to be set. */
+	get sessionDir() {
+		return sessionArtifactDir(this.rootDir, this.sessionId);
+	}
 	get verbose() {
 		return this.options.verbose === true || process.env.ANIMUS_DEBUG === "1" || process.env.ANIMUS_DEBUG === "true";
 	}
@@ -182,24 +273,87 @@ var ExtractionSession = class {
 	elapsed(t) {
 		return this.verbose ? Math.round(performance.now() - t) : 0;
 	}
+	/** Lazily-computed scan config (options are constructor-fixed, so the
+	*  derivation is stable for the session's lifetime). */
+	scanConfigMemo = null;
 	/** Resolve the scan configuration from options — the single source of the
 	*  exclude/extension policy shared by the full and incremental pipelines. */
 	resolveScanConfig() {
-		const extensionsSet = new Set(this.options.extensions ?? DEFAULT_EXTENSIONS);
-		return {
-			excludePatterns: this.options.exclude ?? DEFAULT_EXCLUDE,
-			extensionsSet,
-			shouldHandleMdx: extensionsSet.has(".mdx")
-		};
+		if (this.scanConfigMemo === null) {
+			const extensionsSet = new Set(this.options.extensions ?? DEFAULT_EXTENSIONS);
+			this.scanConfigMemo = {
+				excludePatterns: this.options.exclude ?? DEFAULT_EXCLUDE,
+				extensionsSet,
+				shouldHandleMdx: extensionsSet.has(".mdx")
+			};
+		}
+		return this.scanConfigMemo;
+	}
+	/**
+	* Watch entry point: one single-flight analysis transaction per event
+	* batch (openspec: next-webpack-served-transform-coherence, design D3).
+	* The first entering session runs the transaction; every concurrent
+	* entry — same session re-entered, or another compiler's session
+	* (client/server/RSC each hold their own instance) — joins the in-flight
+	* promise, so no compiler proceeds against a generation older than the
+	* one the transaction publishes. A rejected transaction rejects every
+	* joiner; the gate always clears.
+	*/
+	async handleWatchUpdate(changes) {
+		const inflight = getWatchTransaction();
+		if (inflight) {
+			await inflight;
+			return;
+		}
+		if (!this.system) {
+			const owner = getOwningWatchSession();
+			const hasBatch = (changes.modifiedFiles?.size ?? 0) > 0 || (changes.removedFiles?.size ?? 0) > 0;
+			if (owner && owner !== this && hasBatch) await owner.ingestForwardedBatch(changes);
+			return;
+		}
+		const transaction = this.processWatchUpdate(changes);
+		setWatchTransaction(transaction);
+		try {
+			await transaction;
+		} finally {
+			setWatchTransaction(null);
+		}
+	}
+	/**
+	* Owner-side entry for a batch observed by a NON-OWNING compiler's
+	* watcher. Serializes behind any in-flight transaction, then runs the
+	* forwarded batch as its own transaction — never drops it (a forwarded
+	* batch has no other delivery; content-hash diffing makes an
+	* already-covered batch a cheap no-op).
+	*/
+	async ingestForwardedBatch(changes) {
+		if (!this.system) return;
+		for (;;) {
+			const inflight = getWatchTransaction();
+			if (!inflight) break;
+			await inflight;
+		}
+		const transaction = this.processWatchUpdate(changes);
+		setWatchTransaction(transaction);
+		try {
+			await transaction;
+		} finally {
+			setWatchTransaction(null);
+		}
 	}
 	/**
 	* Incremental watch pass: geological reset when the system file changed,
 	* otherwise content-hash diffing restricted to the watcher's change sets
 	* (falling back to a full discovery walk when no sets are provided).
 	*/
-	async handleWatchUpdate(changes) {
-		if (!this.system) return;
+	async processWatchUpdate(changes) {
 		const rootDir = this.rootDir;
+		try {
+			changes = this.reconcileExternalRoots(changes);
+		} catch (err) {
+			this.warn(`external root reconciliation failed: ${String(err)}`);
+		}
+		const changed = [...changes.modifiedFiles ?? [], ...changes.removedFiles ?? []];
 		let assetChanged = false;
 		try {
 			let systemHit;
@@ -213,16 +367,16 @@ var ExtractionSession = class {
 					break;
 				}
 			}
-			else systemHit = [...changes.modifiedFiles ?? [], ...changes.removedFiles ?? []].find((path) => toWatchKeys(path).some((key) => this.systemDependencyKeys.has(key)));
+			else systemHit = changed.find((path) => toWatchKeys(path).some((key) => this.systemDependencyKeys.has(key)));
 			if (systemHit) {
 				this.log(`geological reset: system dependency changed (${relative(rootDir, systemHit)})`);
 				this.resetForHmr();
-				const promise = this.runFullPipeline();
+				const promise = this.runFullPipeline(this.pendingFromBatch(changes));
 				setAnalysisPromise(promise);
 				await promise;
 				return;
 			}
-			if ([...changes.modifiedFiles ?? [], ...changes.removedFiles ?? []].some((path) => toWatchKeys(path).some((key) => this.assetDependencyKeys.has(key)))) {
+			if (changed.some((path) => toWatchKeys(path).some((key) => this.assetDependencyKeys.has(key)))) {
 				this.assetCopyCache.clear();
 				assetChanged = true;
 			}
@@ -230,53 +384,122 @@ var ExtractionSession = class {
 			this.warn(`HMR geological-reset check failed: ${String(err)}`);
 		}
 		const { excludePatterns, extensionsSet, shouldHandleMdx } = this.resolveScanConfig();
+		const priorCacheEntries = /* @__PURE__ */ new Map();
+		const recordPrior = (key) => {
+			if (!priorCacheEntries.has(key)) priorCacheEntries.set(key, this.fileCache.get(key) ?? null);
+		};
+		const inventoryUpdates = [];
+		const ownerRemovals = [];
 		let removedAny = false;
 		if (changes.removedFiles) for (const removedPath of changes.removedFiles) {
-			const rel = relative(rootDir, removedPath);
-			if (this.fileCache.delete(rel) || this.fileCache.delete(rel + ".tsx")) removedAny = true;
+			let key;
+			let owningRoot = null;
+			if (isPathWithinRoot(rootDir, removedPath)) key = relative(rootDir, removedPath);
+			else {
+				const resolved = this.sourceIdentity?.resolveDeletedSourceId(removedPath);
+				if (!resolved) continue;
+				key = resolved.sourceKey;
+				owningRoot = resolved.owningRoot;
+			}
+			recordPrior(key);
+			recordPrior(key + ".tsx");
+			if (this.fileCache.delete(key) || this.fileCache.delete(key + ".tsx")) {
+				removedAny = true;
+				if (owningRoot) {
+					inventoryUpdates.push({
+						root: owningRoot,
+						key,
+						hash: null,
+						abs: removedPath
+					});
+					ownerRemovals.push(key, key + ".tsx");
+				}
+			}
 		}
-		let files;
+		let targets;
 		if (changes.modifiedFiles) {
-			files = [];
+			targets = [];
 			for (const modifiedPath of changes.modifiedFiles) {
-				if (!extensionsSet.has(extname(modifiedPath))) continue;
-				const rel = relative(rootDir, modifiedPath);
-				if (rel.startsWith("..")) continue;
-				if (excludePatterns.some((pattern) => modifiedPath.includes(pattern) || rel.includes(pattern))) continue;
-				files.push(modifiedPath);
+				const classified = this.classifyWatchPath(modifiedPath, {
+					excludePatterns,
+					extensionsSet
+				});
+				if (classified) targets.push({
+					abs: modifiedPath,
+					...classified
+				});
 			}
-		} else files = discoverFiles(rootDir, rootDir, excludePatterns, extensionsSet);
+		} else targets = discoverFiles(rootDir, rootDir, excludePatterns, extensionsSet).map((abs) => ({
+			abs,
+			key: relative(rootDir, abs),
+			owningRoot: null
+		}));
 		const changedPaths = [];
-		for (const filePath of files) {
-			let relPath = relative(rootDir, filePath);
+		for (const target of targets) {
+			let relPath = target.key;
 			let source;
 			try {
-				source = readFileSync(filePath, "utf-8");
+				source = readFileSync(target.abs, "utf-8");
 			} catch {
 				continue;
 			}
-			if (shouldHandleMdx && extname(filePath) === ".mdx") {
+			const rawHash = contentHash(source);
+			if (shouldHandleMdx && extname(target.abs) === ".mdx") {
 				const processed = await this.preprocessMdxEntry(source, relPath, { warn: false });
 				if (!processed) continue;
 				source = processed.source;
 				relPath = processed.relPath;
 			}
 			const cached = this.fileCache.get(relPath);
-			const hash = contentHash(source);
+			const hash = relPath === target.key ? rawHash : contentHash(source);
 			if (!cached || cached.hash !== hash) {
 				changedPaths.push(relPath);
+				recordPrior(relPath);
 				this.fileCache.set(relPath, {
 					hash,
 					source
 				});
+				if (target.owningRoot) {
+					const owner = this.externalRootOwners.get(target.owningRoot)?.values().next().value;
+					if (owner !== void 0) this.externalFileOwners[relPath] ??= owner;
+					inventoryUpdates.push({
+						root: target.owningRoot,
+						key: target.key,
+						hash: rawHash,
+						abs: target.abs
+					});
+				}
 			}
 		}
 		if (changedPaths.length > 0 || removedAny || assetChanged) {
 			const fileEntries = this.buildFileEntriesFromCache();
+			const pending = changedPaths.map((rel) => [rel, this.fileCache.get(rel).hash]);
 			resetAnalysisPromise();
-			const promise = this.runIncrementalPipeline(fileEntries);
+			const promise = this.runIncrementalPipeline(fileEntries, pending);
 			setAnalysisPromise(promise);
-			await promise;
+			try {
+				await promise;
+			} catch (err) {
+				for (const [key, prior] of priorCacheEntries) if (prior === null) this.fileCache.delete(key);
+				else this.fileCache.set(key, prior);
+				throw err;
+			}
+			for (const update of inventoryUpdates) {
+				let inventory = this.externalInventory.get(update.root);
+				if (!inventory) {
+					inventory = /* @__PURE__ */ new Map();
+					this.externalInventory.set(update.root, inventory);
+				}
+				if (update.hash === null) inventory.delete(update.key);
+				else inventory.set(update.key, {
+					hash: update.hash,
+					abs: update.abs
+				});
+			}
+			for (const key of ownerRemovals) delete this.externalFileOwners[key];
+		} else if (this.statusAttemptOpen) {
+			this.debouncePending.clear();
+			this.writeAnalysisStatus("idle", []);
 		}
 	}
 	/**
@@ -307,9 +530,11 @@ var ExtractionSession = class {
 			relPath: relPath + ".tsx"
 		};
 	}
-	async runFullPipeline() {
+	async runFullPipeline(pending = []) {
 		const pipelineStart = this.now();
 		const bt = {};
+		this.runSessionStartHygiene();
+		setSessionArtifactDir(this.sessionDir);
 		clearEngineCache(engineApi);
 		const rootDir = this.rootDir;
 		const resolvedSystemPath = resolve(rootDir, this.options.system);
@@ -373,6 +598,7 @@ var ExtractionSession = class {
 		t = this.now();
 		const packageNames = extractSystemFilePackages(resolvedSystemPath);
 		const preResolved = resolvePackagesByName(rootDir, packageNames);
+		const rawExternalFiles = /* @__PURE__ */ new Map();
 		const collected = await collectExternalPackageSources({
 			specifiers: packageNames,
 			resolveSpecifier: (name) => preResolved[name] ? resolve(rootDir, preResolved[name]) : null,
@@ -380,6 +606,7 @@ var ExtractionSession = class {
 			extensionsSet,
 			hasEntry: (relPath) => fileEntries.some((e) => e.path === relPath),
 			preprocessFile: async (source, relPath, absPath) => {
+				rawExternalFiles.set(absPath, contentHash(source));
 				if (shouldHandleMdx && extname(absPath) === ".mdx") return this.preprocessMdxEntry(source, relPath, {
 					warn: true,
 					missingDepFlag
@@ -389,7 +616,16 @@ var ExtractionSession = class {
 					relPath
 				};
 			},
-			onUnreadable: (relPath, err) => this.warn(`skipped unreadable package file ${relPath}: ${String(err)}`)
+			onUnreadable: (relPath, err) => this.warn(`skipped unreadable package file ${relPath}: ${String(err)}`),
+			onPackageResolved: (_specifier, packageDir) => {
+				if (!this.onExternalRootResolved) return;
+				if (!this.sharesProjectVolume(rootDir, packageDir)) return;
+				let canonical = packageDir;
+				try {
+					canonical = realpathSync(packageDir);
+				} catch {}
+				this.onExternalRootResolved(canonical);
+			}
 		});
 		for (const record of collected.outcomes) if (record.outcome === "empty") this.warn(`include '${record.specifier}' resolved but discovered no component sources`);
 		const unresolvableMessage = unresolvableIncludesMessage(collected.outcomes);
@@ -402,12 +638,54 @@ var ExtractionSession = class {
 			if (this.options.strict) throw new Error(staleDistMessage);
 			this.warn(staleDistMessage);
 		}
-		const packageMap = collected.packageMap;
+		const rejectedSpecifiers = /* @__PURE__ */ new Set();
+		const crossVolumeDetails = [];
+		for (const [dir, specifiers] of Object.entries(collected.dirOwnerSets)) {
+			if (this.sharesProjectVolume(rootDir, dir)) continue;
+			for (const specifier of specifiers) rejectedSpecifiers.add(specifier);
+			crossVolumeDetails.push(`${specifiers.join(", ")} → ${dir}`);
+		}
+		this.stickyDiagnostics.delete("cross-volume");
+		if (rejectedSpecifiers.size > 0) {
+			const message = `ANIMUS_EXTERNAL_CROSS_VOLUME_UNSUPPORTED: external package source root(s) on a different volume than the project root (${rootDir}): ${crossVolumeDetails.join("; ")} — cross-volume workspace sources are unsupported; the package(s) are excluded from extraction and watching`;
+			if (this.options.strict) throw new Error(`[animus-next] ${message}`);
+			this.stickyDiagnostics.set("cross-volume", message);
+		}
+		for (const message of this.stickyDiagnostics.values()) this.warn(message);
+		const admitted = excludeCollectedPackages(collected, rejectedSpecifiers, rootDir);
+		const identity = createSourceIdentity(rootDir);
+		this.externalRootOwners = /* @__PURE__ */ new Map();
+		this.externalRootExtensions = /* @__PURE__ */ new Map();
+		for (const [dir, specifiers] of Object.entries(admitted.dirOwnerSets)) {
+			const canonical = identity.registerExternalRoot(dir);
+			const owners = this.externalRootOwners.get(canonical) ?? /* @__PURE__ */ new Set();
+			for (const specifier of specifiers) owners.add(specifier);
+			this.externalRootOwners.set(canonical, owners);
+			const exts = admitted.dirExtensions[dir];
+			if (exts) this.externalRootExtensions.set(canonical, new Set(exts));
+		}
+		this.sourceIdentity = identity;
+		this.externalWatchRoots = identity.externalRoots();
+		this.externalInventory = /* @__PURE__ */ new Map();
+		for (const [absPath, rawHash] of rawExternalFiles) {
+			const resolved = identity.resolveSourceId(absPath);
+			if (!resolved?.owningRoot) continue;
+			let inventory = this.externalInventory.get(resolved.owningRoot);
+			if (!inventory) {
+				inventory = /* @__PURE__ */ new Map();
+				this.externalInventory.set(resolved.owningRoot, inventory);
+			}
+			inventory.set(resolved.sourceKey, {
+				hash: rawHash,
+				abs: absPath
+			});
+		}
+		const packageMap = admitted.packageMap;
 		this.lastPackageMap = packageMap;
-		this.externalDirOwners = collected.dirOwners;
-		this.externalFileOwners = collected.fileOwners;
-		this.externalSourceEntries = collected.sourceEntries;
-		for (const entry of collected.entries) {
+		this.externalDirOwners = firstOwners(admitted.dirOwnerSets);
+		this.externalFileOwners = admitted.fileOwners;
+		this.externalSourceEntries = admitted.sourceEntries;
+		for (const entry of admitted.entries) {
 			const hash = contentHash(entry.source);
 			this.fileCache.set(entry.path, {
 				hash,
@@ -419,30 +697,160 @@ var ExtractionSession = class {
 				hash
 			});
 		}
-		this.externalPackageDirs = collected.packageDirs;
-		setSharedExternalDirs(collected.packageDirs);
-		setSharedExternalEntries(collected.sourceEntries);
-		if (this.system && collected.sourceEntries.size > 0) {
+		this.externalPackageDirs = admitted.packageDirs;
+		setSharedExternalDirs(admitted.packageDirs);
+		setSharedExternalEntries(admitted.sourceEntries);
+		if (this.system && admitted.keyframesScanEntries.size > 0) {
 			const api = engineApi();
-			const merge = mergeExternalKeyframes((entry, root) => api.scanKeyframesExports(entry, root), this.system.keyframesJson, collected.sourceEntries.values(), this.rootDir);
+			const merge = mergeExternalKeyframes((entry, root) => api.scanKeyframesExports(entry, root), this.system.keyframesJson, admitted.keyframesScanEntries.values(), this.rootDir);
 			this.system.keyframesJson = merge.keyframesJson;
 			this.externalKeyframesDiagnostics = merge.diagnostics;
-		}
+		} else this.externalKeyframesDiagnostics = [];
 		bt.packageResolve = this.elapsed(t);
-		await this.analyzeAndEmit(fileEntries, packageMap, false, bt, pipelineStart);
+		const universe = new Set(fileEntries.map((entry) => entry.path));
+		for (const key of [...this.fileCache.keys()]) if (!universe.has(key)) this.fileCache.delete(key);
+		await this.analyzeAndEmit(fileEntries, packageMap, false, bt, pipelineStart, pending);
+		this.onExternalRootsCommitted?.(this.externalWatchRoots);
+		setOwningWatchSession(this);
 	}
 	/**
-	* Reset analysis state for HMR geological reset.
+	* Reset analysis state for HMR geological reset. Payload write guards go
+	* back to null so the next publication reseeds them from the disk
+	* envelopes — a byte-identical post-reset artifact is still not
+	* rewritten.
 	*/
 	resetForHmr() {
 		resetAnalysisPromise();
-		this.lastCssHash = null;
+		this.artifactRecords = {
+			manifest: null,
+			inputs: null,
+			styles: null
+		};
 		this.lastSystemPropsHash = null;
-		this.lastManifestHash = null;
-		this.lastAnalysisInputsHash = null;
 		clearEngineCache(engineApi);
 	}
 	/**
+	* The (sourceKey, observedSourceHash) pairs of a watch batch — cheap
+	* evidence for the status file's pending set on the geological-reset
+	* path, where the batch's component edits ride along with the system
+	* edit (design D3: loaders wait only on observed inputs).
+	*/
+	pendingFromBatch(changes) {
+		const { excludePatterns, extensionsSet } = this.resolveScanConfig();
+		const pending = [];
+		for (const path of changes.modifiedFiles ?? []) {
+			const classified = this.classifyWatchPath(path, {
+				excludePatterns,
+				extensionsSet
+			});
+			if (!classified) continue;
+			try {
+				pending.push([classified.key, contentHash(readFileSync(path, "utf-8"))]);
+			} catch {}
+		}
+		return pending;
+	}
+	/**
+	* Root-dirty inventory reconciliation (design D3): partition the
+	* watcher's change sets into explicit FILE events and external ROOT hits
+	* (a reported path that IS an admitted root, or a directory inside one),
+	* rewalk each dirty root through the shared discovery policy, diff the
+	* SourceId+raw-hash inventory against the previous generation, and merge
+	* the reconstructed created/edited/deleted deltas with the explicit
+	* events (identity-level dedup happens downstream at the cache gate).
+	* Deletion falls out of the inventory diff — webpack may report only the
+	* directory (probe-proven).
+	*/
+	reconcileExternalRoots(changes) {
+		const identity = this.sourceIdentity;
+		if (!identity) return changes;
+		if (!changes.modifiedFiles && !changes.removedFiles) return changes;
+		if (this.externalWatchRoots.length === 0) return changes;
+		const { extensionsSet } = this.resolveScanConfig();
+		const dirtyRoots = /* @__PURE__ */ new Set();
+		const modified = /* @__PURE__ */ new Set();
+		const removed = /* @__PURE__ */ new Set();
+		const rootHitFor = (path) => {
+			const containing = identity.containingExternalRoot(path);
+			if (!containing) return null;
+			try {
+				return statSync(path).isDirectory() ? containing : null;
+			} catch {
+				return identity.resolveDeletedSourceId(path) ? null : containing;
+			}
+		};
+		for (const path of changes.modifiedFiles ?? []) {
+			const root = rootHitFor(path);
+			if (root) dirtyRoots.add(root);
+			else modified.add(path);
+		}
+		for (const path of changes.removedFiles ?? []) {
+			const root = rootHitFor(path);
+			if (root) dirtyRoots.add(root);
+			else removed.add(path);
+		}
+		for (const root of dirtyRoots) {
+			const previous = this.externalInventory.get(root) ?? /* @__PURE__ */ new Map();
+			const seen = /* @__PURE__ */ new Set();
+			const walked = walkPackageSources(root, this.externalRootExtensions.get(root) ?? extensionsSet);
+			if (walked.length === 0 && previous.size > 0) this.warn(`external root rewalk found no files under ${root} while its inventory holds ${previous.size} — reconciling as full deletion`);
+			for (const abs of walked) {
+				const resolved = identity.resolveSourceId(abs);
+				if (!resolved || resolved.owningRoot !== root) continue;
+				seen.add(resolved.sourceKey);
+				let rawHash;
+				try {
+					rawHash = contentHash(readFileSync(abs, "utf-8"));
+				} catch {
+					continue;
+				}
+				if (previous.get(resolved.sourceKey)?.hash !== rawHash) modified.add(abs);
+			}
+			for (const [key, entry] of previous) if (!seen.has(key)) removed.add(entry.abs);
+		}
+		return {
+			modifiedFiles: modified,
+			removedFiles: removed
+		};
+	}
+	/**
+	* Route one watcher-reported path (design D1/D2): a project-root member
+	* (lexical containment — existing local semantics preserved; consumer
+	* exclude patterns apply) or an admitted external member (identity
+	* resolution with symlink-escape rejection; package-relative excludes
+	* mirror the collection walk's filters — guardrail G1, one policy).
+	* Returns null for dropped paths.
+	*/
+	classifyWatchPath(absPath, scan) {
+		const ext = extname(absPath);
+		const rootDir = this.rootDir;
+		if (isPathWithinRoot(rootDir, absPath)) {
+			if (!scan.extensionsSet.has(ext)) return null;
+			const rel = relative(rootDir, absPath);
+			if (scan.excludePatterns.some((pattern) => absPath.includes(pattern) || rel.includes(pattern))) return null;
+			return {
+				key: rel,
+				owningRoot: null
+			};
+		}
+		const resolved = this.sourceIdentity?.resolveSourceId(absPath);
+		if (!resolved) return null;
+		if (resolved.owningRoot === null) {
+			if (!scan.extensionsSet.has(ext)) return null;
+			if (scan.excludePatterns.some((pattern) => resolved.sourceKey.includes(pattern))) return null;
+			return {
+				key: resolved.sourceKey,
+				owningRoot: null
+			};
+		}
+		if (!(this.externalRootExtensions.get(resolved.owningRoot) ?? scan.extensionsSet).has(ext)) return null;
+		if (isExcludedPackageRelativePath(resolved.pathInRoot)) return null;
+		return {
+			key: resolved.sourceKey,
+			owningRoot: resolved.owningRoot
+		};
+	}
+	/**
 	* Build file entries from cache: every cached file rides with full source.
 	* The v2 engine has NO Rust-side cache (arch-extract-v2-spine: uncached
 	* re-analysis beats a cache-hit path), so it must always receive full sources
@@ -461,10 +869,10 @@ var ExtractionSession = class {
 	* Run incremental pipeline with cache-aware file entries.
 	* Reuses system config from the last full pipeline run.
 	*/
-	async runIncrementalPipeline(fileEntries) {
+	async runIncrementalPipeline(fileEntries, pending = []) {
 		const bt = {};
 		const pipelineStart = this.now();
-		await this.analyzeAndEmit(fileEntries, this.lastPackageMap, true, bt, pipelineStart);
+		await this.analyzeAndEmit(fileEntries, this.lastPackageMap, true, bt, pipelineStart, pending);
 	}
 	/**
 	* Shared analysis + emit core for both pipelines — the single call site
@@ -482,27 +890,49 @@ var ExtractionSession = class {
 	* - `true` (HMR): skips the report log, and guards the system-props.js
 	*   write by lastSystemPropsHash.
 	*
-	* The styles.css write guard (lastCssHash) is identical on both paths.
+	* The disk artifacts land under the session directory in transaction
+	* order (design D1): manifest → analysis-inputs (Turbopack orchestration
+	* only) → styles.css → system-props → analysis-commit →
+	* replacements-epoch (last, only when moved). The analysis-status file walks starting → analyzing →
+	* committing → idle around the attempt, landing in `failed` (with the
+	* diagnostic) on any throw (design D3).
 	*/
-	async analyzeAndEmit(fileEntries, packageMap, devMode, bt, pipelineStart) {
+	async analyzeAndEmit(fileEntries, packageMap, devMode, bt, pipelineStart, pending = []) {
+		this.beginStatusAttempt();
+		this.debouncePending.clear();
+		this.writeAnalysisStatus("starting", pending);
+		try {
+			await this.analyzeAndEmitAttempt(fileEntries, packageMap, devMode, bt, pipelineStart, pending);
+			this.writeAnalysisStatus("idle", []);
+		} catch (err) {
+			this.writeAnalysisStatus("failed", pending, String(err));
+			throw err;
+		}
+	}
+	async analyzeAndEmitAttempt(fileEntries, packageMap, devMode, bt, pipelineStart, pending) {
 		const system = this.system;
-		const result = runProjectAnalysis(engineApi, {
+		const analysisOptions = {
 			fileEntries,
 			packageMap,
 			system,
 			emitter: {
 				runtimeImport: "@animus-ui/system/runtime",
 				cssModuleId: ANIMUS_CSS_MODULE_ID,
-				systemPropsModuleId: this.systemPropsModuleId ?? join(this.rootDir, ".animus", "system-props.js")
+				systemPropsModuleId: this.systemPropsModuleId ?? systemPropsPath(this.sessionDir)
 			},
 			pathAliasesJson: this.pathAliasesJson,
 			staticCssJson: this.staticCssJson,
 			externalDirs: this.externalPackageDirs.map((dir) => relative(this.rootDir, dir)),
-			devMode,
+			devMode
+		};
+		this.writeAnalysisStatus("analyzing", pending);
+		const result = runProjectAnalysis(engineApi, {
+			...analysisOptions,
 			warn: (message) => this.warn(message),
 			strict: this.options.strict,
 			extraDiagnostics: this.externalKeyframesDiagnostics
 		});
+		assertNoErrorDiagnostics(result.manifest?.diagnostics);
 		enforceExternalTokenContracts({
 			diagnostics: result.manifest?.diagnostics,
 			fileOwners: this.externalFileOwners,
@@ -539,80 +969,310 @@ var ExtractionSession = class {
 			})
 		].filter(Boolean).join("\n");
 		setSharedCss(fullCss);
-		const cssHash = contentHash(fullCss);
-		if (cssHash !== this.lastCssHash) {
-			this.writeAnimusFile("styles.css", fullCss);
-			this.lastCssHash = cssHash;
-		}
 		const systemPropsContent = buildSystemPropsModule({
 			systemPropMapJson: JSON.stringify(manifest?.system_prop_map ?? {}),
 			groupRegistryJson: system.groupRegistryJson,
 			dynamicProps: manifest?.dynamic_props ?? {}
 		});
 		setSharedSystemProps(systemPropsContent);
+		setManifestJson(result.manifestJson);
+		setAnalyzedHashes(new Map(fileEntries.map((entry) => [entry.path, entry.hash])));
+		this.writeAnalysisStatus("committing", pending);
+		const epoch = hashReplacementPlans(snapshotFilePlans(manifest), systemPropsContent);
+		if (this.lastCommit === null) this.lastCommit = this.seedCommitFromDisk();
+		const generation = (this.lastCommit?.generation ?? 0) + 1;
+		this.publishPayloadArtifact("manifest", MANIFEST_ARTIFACT, result.manifestJson, epoch, generation, envelopeJsonArtifact);
+		if (this.persistAnalysisInputs) this.publishPayloadArtifact("inputs", ANALYSIS_INPUTS_ARTIFACT, JSON.stringify({
+			analyzedHashes: Object.fromEntries(fileEntries.map((entry) => [entry.path, entry.hash])),
+			...result.inputs
+		}), epoch, generation, envelopeJsonArtifact);
+		this.publishPayloadArtifact("styles", STYLES_ARTIFACT, fullCss, epoch, generation, envelopeCssArtifact);
 		if (devMode) {
 			const systemPropsHash = contentHash(systemPropsContent);
 			if (systemPropsHash !== this.lastSystemPropsHash) {
-				this.writeAnimusFile("system-props.js", systemPropsContent);
+				this.writeSessionArtifact(SYSTEM_PROPS_ARTIFACT, systemPropsContent);
 				this.lastSystemPropsHash = systemPropsHash;
 			}
-		} else this.writeAnimusFile("system-props.js", systemPropsContent);
-		setManifestJson(result.manifestJson);
-		const manifestHash = contentHash(result.manifestJson);
-		if (this.lastManifestHash === null) this.lastManifestHash = this.diskArtifactHash("manifest.json");
-		if (manifestHash !== this.lastManifestHash) {
-			this.writeAnimusFile("manifest.json", result.manifestJson);
-			this.lastManifestHash = manifestHash;
+		} else this.writeSessionArtifact(SYSTEM_PROPS_ARTIFACT, systemPropsContent);
+		this.publishAnalysisCommit(epoch, generation);
+		this.publishReplacementEpoch(epoch);
+		bt.total = this.elapsed(pipelineStart);
+		logBuildTimings(bt, manifest?.timing, (msg) => this.log(msg), this.verbose);
+	}
+	/** Open a status attempt (attemptId increments once per burst — a
+	*  debouncing pre-write and the analysis that follows share one id). */
+	beginStatusAttempt() {
+		if (!this.statusAttemptOpen) {
+			this.statusAttemptId += 1;
+			this.statusAttemptOpen = true;
 		}
-		if (this.persistAnalysisInputs) {
-			const inputsJson = JSON.stringify(result.inputs);
-			const inputsHash = contentHash(inputsJson);
-			if (this.lastAnalysisInputsHash === null) this.lastAnalysisInputsHash = this.diskArtifactHash("analysis-inputs.json");
-			if (inputsHash !== this.lastAnalysisInputsHash) {
-				this.writeAnimusFile("analysis-inputs.json", inputsJson);
-				this.lastAnalysisInputsHash = inputsHash;
+	}
+	/** Write the session's analysis-status artifact (design D3). Terminal
+	*  states (idle/failed) close the attempt. */
+	writeAnalysisStatus(state, pending, diagnostic) {
+		const status = {
+			schema: 1,
+			sessionId: this.sessionId,
+			attemptId: this.statusAttemptId,
+			state,
+			pending,
+			deadlineAt: Date.now() + this.debounceCeilingMs + STATUS_WATCHDOG_MS,
+			...diagnostic !== void 0 ? { diagnostic } : {}
+		};
+		this.writeSessionArtifact(ANALYSIS_STATUS_ARTIFACT, JSON.stringify(status));
+		if (state === "idle" || state === "failed") this.statusAttemptOpen = false;
+	}
+	/**
+	* Orchestrator seam (Turbopack watcher): record watch events observed
+	* during the debounce window so a loader running ahead of the analysis
+	* has positive evidence to wait on (design D3 'debouncing'). Paths are
+	* filtered by the scan config and hashed at observation time.
+	*/
+	noteDebouncedWatchEvents(absPaths) {
+		if (!this.rootDir) return;
+		const additions = this.pendingFromBatch({ modifiedFiles: new Set(absPaths) });
+		if (additions.length === 0) return;
+		this.beginStatusAttempt();
+		for (const [key, hash] of additions) this.debouncePending.set(key, hash);
+		if (this.debounceStatusWriteScheduled) return;
+		this.debounceStatusWriteScheduled = true;
+		queueMicrotask(() => {
+			this.debounceStatusWriteScheduled = false;
+			if (this.debouncePending.size === 0) return;
+			try {
+				this.writeAnalysisStatus("debouncing", [...this.debouncePending.entries()]);
+			} catch (err) {
+				this.warn(`debounce status write failed: ${String(err)}`);
 			}
+		});
+	}
+	/** One pending microtask flushes a burst of debounce observations. */
+	debounceStatusWriteScheduled = false;
+	/**
+	* Write one payload artifact into the session directory, enveloped with
+	* `{sessionId, generation, replacementEpoch, payloadHash}` and rewritten
+	* only when the PAYLOAD bytes changed (byte-identical re-analyses leave
+	* disk untouched — spec: "Unchanged manifest is not rewritten"). The
+	* recorded diskHash (hash of the enveloped bytes) feeds the
+	* analysis-commit.
+	*/
+	publishPayloadArtifact(key, name, payload, epoch, generation, wrap) {
+		const payloadHash = contentHash(payload);
+		if (this.artifactRecords[key] === null) this.artifactRecords[key] = this.seedPayloadRecord(key, name);
+		const record = this.artifactRecords[key];
+		if (record !== null && record.payloadHash === payloadHash) return;
+		const envelope = {
+			sessionId: this.sessionId,
+			generation,
+			replacementEpoch: epoch,
+			payloadHash
+		};
+		const bytes = wrap(payload, JSON.stringify(envelope));
+		this.writeSessionArtifact(name, bytes);
+		this.artifactRecords[key] = {
+			payloadHash,
+			diskHash: contentHash(bytes)
+		};
+	}
+	/** Reconstruct a payload write guard from the on-disk artifact's envelope
+	*  (same-session restart: a byte-identical payload must not rewrite). */
+	seedPayloadRecord(key, name) {
+		let bytes;
+		try {
+			bytes = readFileSync(join(this.sessionDir, name), "utf-8");
+		} catch {
+			return null;
 		}
-		bt.total = this.elapsed(pipelineStart);
-		logBuildTimings(bt, manifest?.timing, (msg) => this.log(msg), this.verbose);
+		let envelope;
+		try {
+			envelope = key === "styles" ? readCssEnvelope(bytes) : readJsonEnvelope(bytes);
+		} catch {
+			return null;
+		}
+		if (!envelope || typeof envelope.payloadHash !== "string") return null;
+		return {
+			payloadHash: envelope.payloadHash,
+			diskHash: contentHash(bytes)
+		};
+	}
+	/** Last analysis-commit persisted in this session's directory, or null. */
+	seedCommitFromDisk() {
+		try {
+			const parsed = JSON.parse(readFileSync(analysisCommitPath(this.sessionDir), "utf-8"));
+			return parsed.schema === 1 && parsed.sessionId === this.sessionId && typeof parsed.generation === "number" ? parsed : null;
+		} catch {
+			return null;
+		}
+	}
+	/**
+	* Publish the analysis-commit — the transaction identity (design D1).
+	* Written AFTER every payload and BEFORE the epoch; skipped entirely when
+	* the payload set (disk hashes) and epoch are unchanged, so a no-op
+	* re-analysis neither re-keys loader-worker hydration nor burns a
+	* generation.
+	*/
+	publishAnalysisCommit(epoch, generation) {
+		const manifestHash = this.artifactRecords.manifest?.diskHash ?? "";
+		const inputsHash = this.persistAnalysisInputs ? this.artifactRecords.inputs?.diskHash ?? "" : void 0;
+		const stylesHash = this.artifactRecords.styles?.diskHash ?? "";
+		const prev = this.lastCommit;
+		if (prev !== null && prev.manifestHash === manifestHash && prev.inputsHash === inputsHash && prev.stylesHash === stylesHash && prev.replacementEpoch === epoch) return;
+		const commit = {
+			schema: 1,
+			sessionId: this.sessionId,
+			generation,
+			replacementEpoch: epoch,
+			manifestHash,
+			...inputsHash !== void 0 ? { inputsHash } : {},
+			stylesHash
+		};
+		this.writeSessionArtifact(ANALYSIS_COMMIT_ARTIFACT, JSON.stringify(commit));
+		this.lastCommit = commit;
+	}
+	/**
+	* Publish the canonical replacement epoch: maintain the session-scoped
+	* disk witness `{schema, sessionId, epoch}`, rewritten ONLY when the
+	* epoch VALUE changes so style-only analyses and same-session restarts
+	* leave bytes and mtime untouched, then expose the value through the
+	* singleton for the plugin's needBuild fan-out and the loader's catch-up
+	* re-check. Every VALUE move also reconciles sibling sessions' epoch
+	* artifacts (below) — the webpack cold-cache validity witness.
+	*/
+	publishReplacementEpoch(epoch) {
+		const onDisk = this.diskEpochValue();
+		if (this.lastEpochValue === null) this.lastEpochValue = onDisk;
+		if (epoch !== onDisk) this.writeSessionArtifact(REPLACEMENT_EPOCH_ARTIFACT, JSON.stringify({
+			schema: 1,
+			sessionId: this.sessionId,
+			epoch
+		}));
+		if (epoch !== this.lastEpochValue) {
+			this.lastEpochValue = epoch;
+			this.reconcileSiblingEpochs(epoch);
+		}
+		setReplacementEpoch(epoch);
 	}
-	/** Content hash of an existing `.animus/` artifact, or null when absent or
-	*  unreadable. Seeds a null write guard so a FRESH session never rewrites a
-	*  byte-identical artifact (spec: next-turbopack-integration — a rewrite
-	*  changes mtime/inode and needlessly re-keys Turbopack loader-worker
-	*  hydration). */
-	diskArtifactHash(name) {
+	/**
+	* Sibling epoch reconciliation — the cross-session half of the webpack
+	* persistent-cache witness (spec: dev-served-transform-coherence,
+	* "Offline change invalidates restored modules"). Restored-module
+	* snapshots reference the epoch artifact of the session that BUILT them;
+	* with session-scoped trees that file would otherwise sit untouched
+	* forever, keeping stale snapshots valid. Whenever this session's epoch
+	* value moves, delete every sibling epoch artifact that disagrees (their
+	* snapshots must invalidate — restore-on-demand then rebuilds from the
+	* current generation) and leave agreeing siblings byte-untouched (warm
+	* restores stay valid). Deleting a stale artifact is pruning, not a
+	* foreign-session write; races with concurrent sessions are tolerated
+	* (S14).
+	*/
+	/** Sibling ids already reconciled away (artifact deleted or absent) —
+	*  nothing left to invalidate for them on later moves. */
+	reconciledSiblingIds = /* @__PURE__ */ new Set();
+	/** sessions-root listing memo, keyed by the root dir's mtime — a new or
+	*  pruned sibling DIRECTORY moves it; agreeing siblings stay listed. */
+	siblingListing = null;
+	reconcileSiblingEpochs(epoch) {
+		const rootPath = sessionsRootDir(this.rootDir);
+		let entries;
 		try {
-			return contentHash(readFileSync(join(this.rootDir, ".animus", name), "utf-8"));
+			const mtimeMs = statSync(rootPath).mtimeMs;
+			if (this.siblingListing?.mtimeMs === mtimeMs) entries = this.siblingListing.entries;
+			else {
+				entries = readdirSync(rootPath);
+				this.siblingListing = {
+					mtimeMs,
+					entries
+				};
+			}
+		} catch {
+			return;
+		}
+		for (const entry of entries) {
+			if (entry === this.sessionId) continue;
+			if (this.reconciledSiblingIds.has(entry)) continue;
+			const siblingEpochPath = join(rootPath, entry, REPLACEMENT_EPOCH_ARTIFACT);
+			try {
+				if (JSON.parse(readFileSync(siblingEpochPath, "utf-8")).epoch === epoch) continue;
+			} catch (err) {
+				if (err?.code === "ENOENT") {
+					this.reconciledSiblingIds.add(entry);
+					continue;
+				}
+			}
+			try {
+				unlinkSync(siblingEpochPath);
+			} catch {}
+			this.reconciledSiblingIds.add(entry);
+		}
+	}
+	/** Epoch value held by this session's on-disk artifact, or null when
+	*  absent, unreadable, or not the expected schema. */
+	diskEpochValue() {
+		try {
+			const parsed = JSON.parse(readFileSync(replacementEpochPath(this.sessionDir), "utf-8"));
+			return parsed.schema === 1 && typeof parsed.epoch === "string" ? parsed.epoch : null;
 		} catch {
 			return null;
 		}
 	}
-	/** Ensure `.animus/` exists and write one generated artifact into it.
+	/** Session-start hygiene (design D2): delete legacy flat artifacts
+	*  (unreachable by session-scoped loaders) and prune sibling session
+	*  directories older than the retention window — never the own dir,
+	*  tolerating races with concurrently-pruning sessions (S14). */
+	runSessionStartHygiene() {
+		if (this.sessionStartHygieneDone) return;
+		this.sessionStartHygieneDone = true;
+		const animusDir = join(this.rootDir, ".animus");
+		for (const name of LEGACY_FLAT_ARTIFACTS) try {
+			unlinkSync(join(animusDir, name));
+		} catch {}
+		let entries;
+		try {
+			entries = readdirSync(sessionsRootDir(this.rootDir));
+		} catch {
+			return;
+		}
+		const cutoff = Date.now() - SESSION_DIR_MAX_AGE_MS;
+		for (const entry of entries) {
+			if (entry === this.sessionId) continue;
+			const dir = join(sessionsRootDir(this.rootDir), entry);
+			try {
+				if (statSync(dir).mtimeMs < cutoff) rmSync(dir, {
+					recursive: true,
+					force: true
+				});
+			} catch {}
+		}
+	}
+	/** Ensure the session directory exists and write one artifact into it.
 	*  Write-then-rename so cross-process readers (Turbopack loader workers)
 	*  can never observe a torn half-written file. The tmp name carries the
 	*  pid — Next dev evaluates the config in more than one process, and two
 	*  sessions writing the same artifact must not race on one tmp path. */
-	writeAnimusFile(name, content) {
-		const dir = join(this.rootDir, ".animus");
-		if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+	writeSessionArtifact(name, content) {
+		const dir = this.sessionDir;
+		mkdirSync(dir, { recursive: true });
 		const tmpPath = join(dir, `.${name}.${process.pid}.tmp`);
 		writeFileSync(tmpPath, content);
 		renameSync(tmpPath, join(dir, name));
+		this.onArtifactWrite?.(name, content);
 	}
 	/**
 	* asset() placeholder substitution (global-styles-system): resolve each
-	* referenced specifier through Node resolution, copy the bytes into
-	* `.animus/assets/` under a content-hashed name, and substitute a
-	* RELATIVE url. `.animus/styles.css` is processed by Next's own CSS
-	* pipeline (webpack and Turbopack alike), which applies its native asset
-	* handling — publicPath and output hashing — to relative url()
-	* references. Unsubstitutable specifiers warn and emit literally in
-	* non-strict mode, fail the build under `strict: true`.
+	* referenced specifier through Node resolution, copy the bytes into the
+	* session directory's `assets/` under a content-hashed name, and
+	* substitute a RELATIVE url — relative to the session-scoped styles.css,
+	* which sits beside `assets/`, so the emitted `./assets/<file>` form is
+	* unchanged. The stylesheet is processed by Next's own CSS pipeline
+	* (webpack and Turbopack alike), which applies its native asset handling
+	* — publicPath and output hashing — to relative url() references.
+	* Unsubstitutable specifiers warn and emit literally in non-strict mode,
+	* fail the build under `strict: true`.
 	*/
 	substituteAssetReferences(globalCss, devMode) {
 		const specifiers = findAssetSpecifiers(globalCss);
-		const assetsDir = join(this.rootDir, ".animus", "assets");
+		const assetsDir = join(this.sessionDir, SESSION_ASSETS_DIR);
 		const expected = /* @__PURE__ */ new Set();
 		this.assetDependencyPaths.clear();
 		this.assetDependencyKeys.clear();
@@ -708,7 +1368,37 @@ function pruneStaleAssets(assetsDir, expected) {
 	}
 }
 //#endregion
+//#region src/loader-path.ts
+const __dirname$1 = dirname(fileURLToPath(import.meta.url));
+/**
+* The one loader-path derivation: first existing dist candidate under the
+* plugin dir, else the in-repo source fallback. Both loader resolvers below
+* are thin wrappers, so rule registration and any loader-chain predicate
+* can never drift (openspec: next-webpack-served-transform-coherence,
+* design D1).
+*/
+function resolveLoaderPath(pluginDir, distCandidates, sourceFallback) {
+	for (const candidate of distCandidates) {
+		const distPath = resolve(pluginDir, candidate);
+		if (existsSync(distPath)) return distPath;
+	}
+	return resolve(pluginDir, sourceFallback);
+}
+/**
+* This package's webpack loader path, shared by the rule registration
+* (with-animus) and the needBuild loader-chain predicate (plugin). Compiled
+* dist ships `loader.mjs` next to this module; running from source falls
+* back to the TypeScript loader.
+*/
+function resolveAnimusLoaderPath() {
+	return resolveLoaderPath(__dirname$1, ["loader.mjs"], "loader.ts");
+}
+//#endregion
 //#region src/plugin.ts
+/** Loud unsupported-version failure (design D7): the coherence mechanism
+*  cannot exist without the per-compilation needBuild hook, so a webpack
+*  that lacks it fails immediately instead of serving stale transforms. */
+const UNSUPPORTED_WEBPACK_MESSAGE = "[animus-extract] Unsupported webpack: NormalModule.getCompilationHooks(compilation).needBuild is required for dev transform coherence and this webpack does not expose it. Use a Next.js version covered by the animus webpack gauntlet.";
 const PLUGIN_NAME = "AnimusWebpackPlugin";
 /**
 * Webpack adapter for the extraction pipeline. All pipeline logic lives in
@@ -722,11 +1412,57 @@ var AnimusWebpackPlugin = class {
 	session;
 	initialized = false;
 	aliasesExtracted = false;
+	/** Loader paths counting as "the animus loader" in a module's chain —
+	*  this package's own loader plus an optional harness override. */
+	animusLoaderPaths;
+	/** Epoch THIS compiler last proceeded with (set after every awaited
+	*  watchRun transaction — including joined ones). Null until the
+	*  initialization pipeline publishes. */
+	lastBuiltEpoch = null;
+	/** Armed by watchRun when the transaction moved the epoch; captured and
+	*  disarmed by the next compilation's needBuild wiring (design D1). */
+	epochMovedForNextCompilation = false;
 	constructor(options) {
 		this.options = options;
 		assertNoRetiredEngineSelection(options.engine);
 		setSharedEngine(options.engine ?? "v2");
 		this.session = new ExtractionSession(options);
+		this.animusLoaderPaths = new Set([resolveAnimusLoaderPath()]);
+		if (options.loaderPath) this.animusLoaderPaths.add(options.loaderPath);
+	}
+	/** True when the module's loader chain contains the animus loader — the
+	*  needBuild fan-out predicate (design D1: no historical records; covers
+	*  restored persistent-cache modules and raw passthroughs alike). */
+	moduleUsesAnimusLoader(module) {
+		const loaders = module?.loaders;
+		if (!Array.isArray(loaders)) return false;
+		return loaders.some((entry) => typeof entry?.loader === "string" && this.animusLoaderPaths.has(entry.loader));
+	}
+	/** Append the exact epoch artifact path to `watchOptions.ignored`,
+	*  preserving the user's shape (design D2: the artifact participates in
+	*  module snapshots via addDependency but never triggers live watch
+	*  turns — no echo compilations). Session identity is process-claimed,
+	*  so every compiler's plugin instance derives the SAME session-scoped
+	*  path here regardless of which instance ends up owning the pipeline.
+	*  Derived from the ONE root (session.rootDir, set at config time by
+	*  with-animus); compiler.context is the fallback for bare-apply
+	*  harnesses — identical when compiler.context === cwd. */
+	appendEpochWatchIgnore(compiler) {
+		const options = compiler.options;
+		if (!options) return;
+		const epochPath = replacementEpochPath(sessionArtifactDir(this.session.rootDir ?? compiler.context, this.session.sessionId));
+		options.watchOptions ??= {};
+		const watchOptions = options.watchOptions;
+		const ignored = watchOptions.ignored;
+		if (ignored === void 0 || ignored === null) watchOptions.ignored = [epochPath];
+		else if (Array.isArray(ignored)) {
+			if (!ignored.includes(epochPath)) ignored.push(epochPath);
+		} else if (typeof ignored === "string") watchOptions.ignored = [ignored, epochPath];
+		else if (ignored instanceof RegExp) watchOptions.ignored = (path) => path === epochPath || ignored.test(path);
+		else if (typeof ignored === "function") {
+			const original = ignored;
+			watchOptions.ignored = (path) => path === epochPath || Boolean(original(path));
+		}
 	}
 	/** Extract path aliases from webpack's resolve.alias config. Runs once per
 	*  plugin instance — the resolve config is immutable after apply. */
@@ -751,12 +1487,29 @@ var AnimusWebpackPlugin = class {
 	}
 	apply(compiler) {
 		if (compiler.options?.name === "edge-server") return;
+		const NormalModule = compiler.webpack?.NormalModule;
+		if (typeof NormalModule?.getCompilationHooks !== "function") throw new Error(UNSUPPORTED_WEBPACK_MESSAGE);
+		this.appendEpochWatchIgnore(compiler);
+		compiler.hooks.thisCompilation.tap(PLUGIN_NAME, (compilation) => {
+			const epochMoved = this.epochMovedForNextCompilation;
+			this.epochMovedForNextCompilation = false;
+			const needBuild = NormalModule.getCompilationHooks(compilation).needBuild;
+			if (typeof needBuild?.tapAsync !== "function") throw new Error(UNSUPPORTED_WEBPACK_MESSAGE);
+			needBuild.tapAsync(PLUGIN_NAME, (module, _context, callback) => {
+				if (epochMoved && this.moduleUsesAnimusLoader(module)) {
+					callback(null, true);
+					return;
+				}
+				callback();
+			});
+		});
 		compiler.hooks.compilation.tap(PLUGIN_NAME, (compilation) => {
 			const registerSystemDependencies = () => {
 				for (const dep of this.session.systemDependencyPaths) if (existsSync(dep)) compilation.fileDependencies.add(dep);
 				else compilation.missingDependencies.add(dep);
 				for (const dep of this.session.assetDependencyPaths) if (existsSync(dep)) compilation.fileDependencies.add(dep);
 				else compilation.missingDependencies.add(dep);
+				for (const root of this.session.externalWatchRoots) compilation.contextDependencies.add(root);
 			};
 			registerSystemDependencies();
 			const stage = compiler.webpack?.Compilation.PROCESS_ASSETS_STAGE_ADDITIONAL ?? -2e3;
@@ -768,7 +1521,7 @@ var AnimusWebpackPlugin = class {
 				registerSystemDependencies();
 				const css = getSharedCss();
 				if (!css || !RawSource) return;
-				const cssPath = join(this.session.rootDir || compiler.context, ".animus", "styles.css");
+				const cssPath = stylesPath(sessionArtifactDir(this.session.rootDir || compiler.context, this.session.sessionId));
 				if (compilation.getAsset(cssPath)) {
 					compilation.updateAsset(cssPath, new RawSource(css));
 					return;
@@ -777,7 +1530,7 @@ var AnimusWebpackPlugin = class {
 			});
 		});
 		compiler.hooks.run.tapPromise(PLUGIN_NAME, async (_compiler) => {
-			this.session.rootDir = _compiler.context;
+			this.adoptCompilerContext(_compiler);
 			this.extractAliases(_compiler);
 			const existing = getAnalysisPromise();
 			if (existing) {
@@ -789,25 +1542,27 @@ var AnimusWebpackPlugin = class {
 			await promise;
 		});
 		compiler.hooks.watchRun.tapPromise(PLUGIN_NAME, async (_compiler) => {
-			this.session.rootDir = _compiler.context;
+			this.adoptCompilerContext(_compiler);
 			this.extractAliases(_compiler);
 			if (!this.initialized) {
 				const existing = getAnalysisPromise();
-				if (existing) {
-					await existing;
-					this.initialized = true;
-					return;
+				if (existing) await existing;
+				else {
+					const promise = this.session.runFullPipeline();
+					setAnalysisPromise(promise);
+					await promise;
 				}
-				const promise = this.session.runFullPipeline();
-				setAnalysisPromise(promise);
-				await promise;
 				this.initialized = true;
+				this.lastBuiltEpoch = getReplacementEpoch();
 				return;
 			}
 			await this.session.handleWatchUpdate({
 				modifiedFiles: _compiler.modifiedFiles,
 				removedFiles: _compiler.removedFiles
 			});
+			const epoch = getReplacementEpoch();
+			this.epochMovedForNextCompilation = this.lastBuiltEpoch !== null && epoch !== null && epoch !== this.lastBuiltEpoch;
+			if (epoch !== null) this.lastBuiltEpoch = epoch;
 		});
 	}
 	/**
@@ -816,6 +1571,44 @@ var AnimusWebpackPlugin = class {
 	resetForHmr() {
 		this.session.resetForHmr();
 	}
+	/** Session identity (process-claimed) — with-animus derives the
+	*  session-scoped alias/stub paths from it (design D2). */
+	get sessionId() {
+		return this.session.sessionId;
+	}
+	/** Set the project root at CONFIG time (with-animus) — the ONE root all
+	*  session-path derivations use. The compiler hooks ADOPT
+	*  compiler.context only when no root was published (bare-apply
+	*  harnesses); they never overwrite this. */
+	setRootDir(rootDir) {
+		this.session.rootDir = rootDir;
+	}
+	/** One warning per plugin instance for a context/root mismatch. */
+	warnedRootDivergence = false;
+	/** The run/watchRun taps' root handling: adopt compiler.context when no
+	*  config-time root exists; otherwise KEEP the configured root — every
+	*  frozen config-time derivation (stub path, css alias target,
+	*  virtual:animus/system-props target, watch-ignore) came from it, and a
+	*  silent overwrite re-keys sessionDir so the pipeline publishes
+	*  artifacts where none of those consumers look. A disagreement is
+	*  surfaced loudly instead (with-animus derives the root from Next's own
+	*  `dir`, which equals compiler.context in real Next runs — a mismatch
+	*  means a custom-webpack setup wired the plugin differently). */
+	adoptCompilerContext(compiler) {
+		const context = compiler.context;
+		if (!this.session.rootDir) {
+			this.session.rootDir = context;
+			return;
+		}
+		if (context && this.session.rootDir !== context && !this.warnedRootDivergence) {
+			this.warnedRootDivergence = true;
+			console.warn(`[animus-extract] compiler.context (${context}) differs from the configured project root (${this.session.rootDir}); keeping the configured root — run next against the app directory (or align your custom webpack context) so both agree`);
+		}
+	}
+	/** This session's artifact directory, derived from the one root. */
+	get sessionDir() {
+		return this.session.sessionDir;
+	}
 	/** Expose options for the loader */
 	getOptions() {
 		return this.options;
@@ -854,25 +1647,35 @@ function resolveTurbopackMode(options, env = process.env) {
 	if (mode === "auto") return env.TURBOPACK !== void 0;
 	return false;
 }
+/** rootDir-relative module request for an absolute path — always forward
+*  slashes, even when path.relative produced Windows separators. */
+function rootRelativeRequest(rootDir, absPath) {
+	return `./${relative(rootDir, absPath).replace(/\\/g, "/")}`;
+}
 /**
 * Build the `turbopack` config fragment: one glob-keyed loader rule
 * (file-level allowlisting lives in the loader via manifest lookup — Next 15
 * rules have no condition algebra) plus resolve aliases for the virtual
 * system-props id, the emitter's stylesheet id, and each collected external
-* package specifier redirected to its source entry.
+* package specifier redirected to its source entry. Loader options carry
+* the session identity (design D2: an options-borne, JSON-serializable
+* Turbopack task input — restart-cold by construction), and the artifact
+* aliases point into the session-scoped tree.
 */
 function buildTurbopackConfig(args) {
-	const { rootDir, loaderPath, options, externalSourceEntries } = args;
+	const { rootDir, loaderPath, options, externalSourceEntries, sessionId, sessionDir } = args;
 	const loaderOptions = {
 		rootDir,
+		sessionId,
+		sessionDir,
 		...options.strict !== void 0 ? { strict: options.strict } : {},
 		...options.cssImportTarget !== void 0 ? { cssImportTarget: options.cssImportTarget } : {}
 	};
 	const resolveAlias = {
-		[TURBOPACK_SYSTEM_PROPS_ID]: "./.animus/system-props.js",
-		".animus/styles.css": "./.animus/styles.css"
+		[TURBOPACK_SYSTEM_PROPS_ID]: rootRelativeRequest(rootDir, join(sessionDir, SYSTEM_PROPS_ARTIFACT)),
+		".animus/styles.css": rootRelativeRequest(rootDir, join(sessionDir, STYLES_ARTIFACT))
 	};
-	for (const [specifier, srcEntry] of externalSourceEntries) resolveAlias[specifier] = `./${relative(rootDir, srcEntry).replace(/\\/g, "/")}`;
+	for (const [specifier, srcEntry] of externalSourceEntries) resolveAlias[specifier] = rootRelativeRequest(rootDir, srcEntry);
 	return {
 		rules: { [ANIMUS_TURBOPACK_RULE_GLOB]: { loaders: [{
 			loader: loaderPath,
@@ -889,11 +1692,7 @@ function buildTurbopackConfig(args) {
 * not guaranteed.
 */
 function resolveTurbopackLoaderPath(pluginDir) {
-	for (const candidate of ["turbopack-loader.cjs", "turbopack-loader.mjs"]) {
-		const distPath = resolve(pluginDir, candidate);
-		if (existsSync(distPath)) return distPath;
-	}
-	return resolve(pluginDir, "turbopack-loader.ts");
+	return resolveLoaderPath(pluginDir, ["turbopack-loader.cjs", "turbopack-loader.mjs"], "turbopack-loader.ts");
 }
 //#endregion
 //#region src/turbopack-orchestrator.ts
@@ -904,12 +1703,15 @@ function resolveTurbopackLoaderPath(pluginDir) {
 * filesystem watcher — the bundler only ever sees the `.animus/` disk
 * artifacts.
 */
-/** Run the full pipeline with the Turbopack emitter identity: hydration
-*  artifacts persisted, and the virtual system-props id (Turbopack rejects
-*  the webpack path's absolute-path imports). */
+/** Run the full pipeline with the Turbopack emitter identity: the virtual
+*  system-props id (Turbopack rejects the webpack path's absolute-path
+*  imports). Turbopack orchestration persists the analysis-inputs
+*  hydration corpus — its isolated loader workers replay it (spec:
+*  next-turbopack-integration, "Manifest disk artifact"; webpack mode
+*  skips the corpus). */
 async function runTurbopackPipeline(session) {
-	session.persistAnalysisInputs = true;
 	session.systemPropsModuleId = TURBOPACK_SYSTEM_PROPS_ID;
+	session.persistAnalysisInputs = true;
 	await session.runFullPipeline();
 }
 const activeWatcherRoots = /* @__PURE__ */ new Set();
@@ -935,11 +1737,31 @@ const IGNORED_SEGMENTS = new Set([
 function startTurbopackWatcher(session, rootDir, debounceMs = 75, watchFn = watch) {
 	if (activeWatcherRoots.has(rootDir)) return null;
 	activeWatcherRoots.add(rootDir);
+	if (typeof session.noteDebouncedWatchEvents === "function") session.debounceCeilingMs = debounceMs;
 	const pendingPaths = /* @__PURE__ */ new Set();
 	const watchers = /* @__PURE__ */ new Map();
 	let timer = null;
 	let updateChain = Promise.resolve();
 	let closed = false;
+	const externalWatchers = /* @__PURE__ */ new Map();
+	let pendingOpened = /* @__PURE__ */ new Map();
+	let capturedDuringSnapshot = [];
+	const externalDiagnosticKey = (root) => `external-watch:${root}`;
+	const failureReason = (err) => {
+		const code = err?.code;
+		if (code === "EMFILE" || code === "ENFILE" || code === "ENOSPC" || code === "EPERM") return `capacity(${code})`;
+		if (/inotify|too many/i.test(String(err))) return "capacity";
+		return code ?? "error";
+	};
+	const degradeExternalRoot = (root, err) => {
+		externalWatchers.get(root)?.close();
+		externalWatchers.delete(root);
+		pendingOpened.get(root)?.close();
+		pendingOpened.delete(root);
+		const message = `ANIMUS_EXTERNAL_WATCH_UNAVAILABLE root=${relative(rootDir, root)} reason=${failureReason(err)} effect=changes in this workspace source may require restart`;
+		session.stickyDiagnostics?.set(externalDiagnosticKey(root), message);
+		console.warn(`[animus-extract] ${message}`);
+	};
 	const flush = () => {
 		timer = null;
 		const modifiedFiles = /* @__PURE__ */ new Set();
@@ -951,8 +1773,15 @@ function startTurbopackWatcher(session, rootDir, debounceMs = 75, watchFn = watc
 			removedFiles
 		}).catch((err) => {
 			console.warn(`[animus-extract] Turbopack watch update failed: ${String(err)}`);
+		}).then(() => {
+			if (pendingOpened.size > 0 || capturedDuringSnapshot.length > 0) rollbackPendingExternal();
 		}));
 	};
+	const rollbackPendingExternal = () => {
+		for (const watcher of pendingOpened.values()) watcher.close();
+		pendingOpened = /* @__PURE__ */ new Map();
+		capturedDuringSnapshot = [];
+	};
 	const closeAll = () => {
 		if (closed) return;
 		closed = true;
@@ -960,12 +1789,29 @@ function startTurbopackWatcher(session, rootDir, debounceMs = 75, watchFn = watc
 		timer = null;
 		for (const watcher of watchers.values()) watcher.close();
 		watchers.clear();
+		for (const watcher of externalWatchers.values()) watcher.close();
+		externalWatchers.clear();
+		rollbackPendingExternal();
+		session.onExternalRootResolved = null;
+		session.onExternalRootsCommitted = null;
 		activeWatcherRoots.delete(rootDir);
 	};
 	const onWatcherError = (err) => {
 		closeAll();
 		console.warn(`[animus-extract] Turbopack dev watcher failed (${String(err)}); source edits require a dev-server restart`);
 	};
+	const enqueuePath = (abs) => {
+		pendingPaths.add(abs);
+		try {
+			session.noteDebouncedWatchEvents?.([abs]);
+		} catch (err) {
+			console.warn(`[animus-extract] Turbopack debounce status update failed: ${String(err)}`);
+		}
+		if (!timer) {
+			timer = setTimeout(flush, debounceMs);
+			timer.unref?.();
+		}
+	};
 	const onEvent = (baseDir, filename) => {
 		if (closed || !filename) return;
 		const rel = filename.toString();
@@ -974,10 +1820,47 @@ function startTurbopackWatcher(session, rootDir, debounceMs = 75, watchFn = watc
 		if (baseDir === rootDir && !watchers.has(abs)) try {
 			if (statSync(abs).isDirectory()) addWatcher(abs, true);
 		} catch {}
-		pendingPaths.add(abs);
-		if (!timer) {
-			timer = setTimeout(flush, debounceMs);
-			timer.unref?.();
+		enqueuePath(abs);
+	};
+	/** External-root event path: fenced by watcher identity ({watcherRootId,
+	*  generation} — a handle that is neither current nor pending belongs to
+	*  a retired generation and its events are rejected), `filename == null`
+	*  marks the ROOT dirty for rediscovery, and events observed while the
+	*  root's generation is still snapshotting are buffered for replay. */
+	const onExternalEvent = (root, self, filename) => {
+		if (closed) return;
+		const watcher = self();
+		const active = watcher !== void 0 && externalWatchers.get(root) === watcher;
+		const isPending = watcher !== void 0 && pendingOpened.get(root) === watcher;
+		if (!active && !isPending) return;
+		let abs;
+		if (filename == null) abs = root;
+		else {
+			const rel = filename.toString();
+			if (rel.split(/[\\/]/).some((segment) => IGNORED_SEGMENTS.has(segment))) return;
+			abs = rel === "" ? root : join(root, rel);
+		}
+		if (isPending && !active) {
+			capturedDuringSnapshot.push(abs);
+			return;
+		}
+		enqueuePath(abs);
+	};
+	/** Open one external-root watcher into `into` (the committed set at
+	*  startup, the pending set during reset reconciliation). Failures
+	*  degrade ONLY this root (design D7); node_modules-resident roots are
+	*  documented unwatchable and never registered (guardrail G2). */
+	const openExternalWatcher = (root, into) => {
+		if (root.split(/[\\/]/).includes("node_modules")) return;
+		try {
+			let watcher;
+			watcher = watchFn(root, { recursive: true }, (_event, filename) => onExternalEvent(root, () => watcher, filename));
+			watcher.on("error", (err) => degradeExternalRoot(root, err));
+			watcher.unref?.();
+			into.set(root, watcher);
+			session.stickyDiagnostics?.delete(externalDiagnosticKey(root));
+		} catch (err) {
+			degradeExternalRoot(root, err);
 		}
 	};
 	const addWatcher = (dir, recursive) => {
@@ -997,6 +1880,23 @@ function startTurbopackWatcher(session, rootDir, debounceMs = 75, watchFn = watc
 		console.warn(`[animus-extract] Turbopack dev watcher unavailable (${String(err)}); source edits require a dev-server restart`);
 		return null;
 	}
+	for (const root of session.externalWatchRoots ?? []) openExternalWatcher(root, externalWatchers);
+	session.onExternalRootResolved = (root) => {
+		if (closed) return;
+		if (externalWatchers.has(root) || pendingOpened.has(root)) return;
+		openExternalWatcher(root, pendingOpened);
+	};
+	session.onExternalRootsCommitted = (roots) => {
+		if (closed) return;
+		const admitted = new Set(roots);
+		for (const [root, watcher] of pendingOpened) externalWatchers.set(root, watcher);
+		pendingOpened = /* @__PURE__ */ new Map();
+		for (const [root, watcher] of [...externalWatchers]) if (!admitted.has(root)) {
+			watcher.close();
+			externalWatchers.delete(root);
+		}
+		for (const abs of capturedDuringSnapshot.splice(0)) enqueuePath(abs);
+	};
 	return { close: closeAll };
 }
 //#endregion
@@ -1026,10 +1926,12 @@ function withAnimus(options) {
 			...nextConfig,
 			webpack(config, context) {
 				if (typeof existingWebpack === "function") config = existingWebpack(config, context);
-				const rootDir = process.cwd();
-				const animusDir = join(rootDir, ".animus");
-				if (!existsSync(animusDir)) mkdirSync(animusDir, { recursive: true });
-				const stubCssPath = join(animusDir, "styles.css");
+				const rootDir = typeof context.dir === "string" && context.dir.length > 0 ? context.dir : process.cwd();
+				const plugin = new AnimusWebpackPlugin(options);
+				plugin.setRootDir(rootDir);
+				const sessionDir = plugin.sessionDir;
+				if (!existsSync(sessionDir)) mkdirSync(sessionDir, { recursive: true });
+				const stubCssPath = stylesPath(sessionDir);
 				if (!existsSync(stubCssPath)) {
 					const { declaration } = assembleStylesheet({
 						layers: options.layers,
@@ -1048,28 +1950,26 @@ function withAnimus(options) {
 						}
 					} catch {}
 				}
-				const plugin = new AnimusWebpackPlugin(options);
-				const isExternalPackageFile = (filePath) => plugin.getExternalPackageDirs().some((dir) => filePath.startsWith(dir + sep) || filePath === dir);
+				const isExternalPackageFile = (filePath) => plugin.getExternalPackageDirs().some((dir) => isPathWithinRoot(dir, filePath));
 				config.plugins = config.plugins || [];
 				config.plugins.push(plugin);
 				const { DefinePlugin } = context.webpack ?? {};
 				if (typeof DefinePlugin === "function") config.plugins.push(new DefinePlugin({ __ANIMUS_DEV__: JSON.stringify(context.dev === true) }));
 				config.resolve = config.resolve || {};
 				config.resolve.alias = config.resolve.alias || {};
-				config.resolve.alias[ANIMUS_CSS_MODULE_ID] = join(rootDir, ".animus", "styles.css");
-				const systemPropsPath = join(rootDir, ".animus", "system-props.js");
+				config.resolve.alias[ANIMUS_CSS_MODULE_ID] = stylesPath(sessionDir);
+				const sessionSystemPropsPath = systemPropsPath(sessionDir);
 				config.plugins.push({ apply(compiler) {
 					compiler.hooks.normalModuleFactory.tap("AnimusVirtualResolve", (nmf) => {
 						nmf.hooks.beforeResolve.tap("AnimusVirtualResolve", (resolveData) => {
-							if (resolveData.request === "virtual:animus/system-props") resolveData.request = systemPropsPath;
-							if (resolveData.request === "virtual:animus/styles.css") resolveData.request = join(rootDir, ".animus", "styles.css");
+							if (resolveData.request === "virtual:animus/system-props") resolveData.request = sessionSystemPropsPath;
+							if (resolveData.request === "virtual:animus/styles.css") resolveData.request = stylesPath(sessionDir);
 							const srcEntry = plugin.getExternalSourceEntries().get(resolveData.request);
 							if (srcEntry) resolveData.request = srcEntry;
 						});
 					});
 				} });
-				const loaderPath = resolve(__dirname, "loader.mjs");
-				const actualLoaderPath = existsSync(loaderPath) ? loaderPath : resolve(__dirname, "loader.ts");
+				const actualLoaderPath = resolveAnimusLoaderPath();
 				config.module = config.module || {};
 				config.module.rules = config.module.rules || [];
 				config.module.rules.push({
@@ -1113,7 +2013,9 @@ async function wireTurbopack(nextConfig, options) {
 		rootDir,
 		loaderPath: resolveTurbopackLoaderPath(__dirname),
 		options,
-		externalSourceEntries: session.externalSourceEntries
+		externalSourceEntries: session.externalSourceEntries,
+		sessionId: session.sessionId,
+		sessionDir: session.sessionDir
 	});
 	const existing = nextConfig.turbopack ?? {};
 	if (existing.rules && "*.{ts,tsx,js,jsx,mjs}" in existing.rules) throw new Error(`[animus-extract] turbopack.rules['${ANIMUS_TURBOPACK_RULE_GLOB}'] is already configured — remove the consumer rule or disable unstable_turbopack`);