@mulmoclaude/core 3.0.1 → 3.1.0

package/dist/collection-watchers/index.cjs

@@ -1,9 +1,10 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_root = require("../root-rPH6FGDT.cjs");
 const require_calendarGrid = require("../calendarGrid-p8K-7cuB.cjs");
 const require_promptSafety = require("../promptSafety-CNEW3_qS.cjs");
 require("../collection/index.cjs");
-const require_discovery = require("../discovery-CtiZMlsX.cjs");
-const require_server = require("../server-DOZFzx5l.cjs");
+const require_discovery = require("../discovery-CDOjfctD.cjs");
+const require_server = require("../server-WU35UYlF.cjs");
 const require_notifier = require("../notifier-DZJj0sOh.cjs");
 let node_fs_promises = require("node:fs/promises");
 //#region src/collection-watchers/config.ts
@@ -48,24 +49,60 @@ function evalNow() {
 *  Used both to build new keys and to filter sweep candidates from the
 *  active bell. */
 var LEGACY_ID_PREFIX = "collection-completion:";
-/** Stable key encoding slug + item, round-tripped through the entry's
+/** Marks a key that carries a root. Placed FIRST so a rooted key can never be
+*  mistaken for a slug — `<prefix>@<root>\0<slug>:<itemId>` vs the original
+*  `<prefix><slug>:<itemId>`. NUL cannot occur in a path, a slug or an itemId,
+*  so the split is unambiguous. */
+var ROOT_MARK = "@";
+var ROOT_SEP = "\0";
+/** Stable key encoding (root, slug, item), round-tripped through the entry's
 *  `pluginData` so we can find it later without a side state file. Slug +
 *  itemId are upstream-validated via `safeSlugName`, which forbids the
-*  colon separator, so the two-segment parse below is unambiguous. */
-function completionLegacyId(slug, itemId) {
-	return `${LEGACY_ID_PREFIX}${slug}:${itemId}`;
-}
-/** Decode a key back into its (slug, itemId) pair, or null if the string
-*  didn't originate from this module. Used by the sweep step. */
+*  colon separator, so the two-segment parse below is unambiguous.
+*
+*  COMPATIBILITY RULE — read this before changing the format. Both apps
+*  (MulmoClaude and MulmoTerminal) read ONE notifier file,
+*  `<ws>/data/notifier/active.json`; they never run simultaneously, but an id
+*  written by one must not produce a duplicate bell for the other. So:
+*
+*  - with NO root, the id is byte-identical to the pre-multi-root format, and a
+*    single-workspace host's existing `active.json` entries keep matching;
+*  - a root is included ONLY when one was supplied, which is what lets two
+*    roots owning the same slug hold two distinct bells instead of deduping
+*    into each other;
+*  - `parseCompletionLegacyId` accepts BOTH forms, forever.
+*
+*  The root is canonicalised here as well as at the watcher's claim, because
+*  this id is written to disk: a caller reaching `reconcileItem` directly with
+*  `/proj/` where the watcher used `/proj` would otherwise publish a SECOND
+*  bell for the same record, and neither pass would ever clear the other's. */
+function completionLegacyId(slug, itemId, root) {
+	return `${LEGACY_ID_PREFIX}${root === void 0 ? "" : `${ROOT_MARK}${require_root.canonicalRoot(root)}${ROOT_SEP}`}${slug}:${itemId}`;
+}
+/** Decode a key back into its (root, slug, itemId), or null if the string
+*  didn't originate from this module. Accepts both the rooted and the
+*  original root-less form — see the compatibility rule above. Used by the
+*  sweep step. */
 function parseCompletionLegacyId(legacyId) {
 	if (!legacyId.startsWith(LEGACY_ID_PREFIX)) return null;
-	const body = legacyId.slice(22);
+	let body = legacyId.slice(22);
+	let root;
+	if (body.startsWith(ROOT_MARK)) {
+		const sep = body.indexOf(ROOT_SEP);
+		if (sep < 0) return null;
+		root = body.slice(1, sep);
+		body = body.slice(sep + 1);
+	}
 	const colon = body.indexOf(":");
 	if (colon < 0) return null;
-	return {
+	const parsed = {
 		slug: body.slice(0, colon),
 		itemId: body.slice(colon + 1)
 	};
+	return root === void 0 ? parsed : {
+		root,
+		...parsed
+	};
 }
 /** The human-readable label shown in a completion notification's title.
 *  Uses the schema's `displayField` value when declared and non-empty;
@@ -79,13 +116,13 @@ function resolveDisplayLabel(schema, item, itemId) {
 /** Every active bell entry whose key matches this (slug, itemId).
 *  Returns multiple when defensive cleanup is needed. Scans `listAll()`
 *  — cheap because the active set is bounded. */
-async function findActiveEntries(slug, itemId) {
+async function findActiveEntries(slug, itemId, root) {
 	const adapter = requireAdapter();
-	const legacyId = completionLegacyId(slug, itemId);
+	const legacyId = completionLegacyId(slug, itemId, root);
 	return (await require_notifier.listAll()).filter((entry) => adapter.readEntry(entry.pluginData)?.legacyId === legacyId);
 }
-async function findActiveEntryIds(slug, itemId) {
-	return (await findActiveEntries(slug, itemId)).map((entry) => entry.id);
+async function findActiveEntryIds(slug, itemId, root) {
+	return (await findActiveEntries(slug, itemId, root)).map((entry) => entry.id);
 }
 var ensureLocks = /* @__PURE__ */ new Map();
 /** Bell priority for a record: the FIRST flagged value in `notifyWhen.in`
@@ -98,14 +135,22 @@ function notifyPriorityForItem(schema, item) {
 	const value = item[spec.field] === void 0 || item[spec.field] === null ? "" : String(item[spec.field]);
 	return spec.in.indexOf(value) === 0 ? "high" : "normal";
 }
-async function ensureItemNotification(slug, schema, itemId, displayLabel, priority) {
-	const legacyId = completionLegacyId(slug, itemId);
+async function ensureItemNotification(slug, schema, itemId, displayLabel, priority, root) {
+	const legacyId = completionLegacyId(slug, itemId, root);
 	while (true) {
 		const inflight = ensureLocks.get(legacyId);
 		if (!inflight) break;
 		await inflight.promise;
 	}
-	const lock = { promise: doEnsureItemNotification(slug, schema, itemId, legacyId, displayLabel, priority) };
+	const lock = { promise: doEnsureItemNotification({
+		slug,
+		schema,
+		itemId,
+		legacyId,
+		displayLabel,
+		priority,
+		root
+	}) };
 	ensureLocks.set(legacyId, lock);
 	try {
 		await lock.promise;
@@ -117,7 +162,7 @@ async function ensureItemNotification(slug, schema, itemId, displayLabel, priori
 *  place (preserving id / position / createdAt) so a record whose flagged
 *  value changed while it stayed pending re-colours the bell without a
 *  clear+republish flicker. No-op when the stored priority already matches. */
-async function reconcileEntrySeverity(slug, itemId, entries, priority) {
+async function reconcileEntrySeverity(slug, itemId, entries, priority, root) {
 	const adapter = requireAdapter();
 	for (const entry of entries) {
 		const parsed = adapter.readEntry(entry.pluginData);
@@ -129,20 +174,21 @@ async function reconcileEntrySeverity(slug, itemId, entries, priority) {
 				slug,
 				itemId,
 				priority,
-				navigateTarget: adapter.buildNavigateTarget(slug, itemId)
+				navigateTarget: adapter.buildNavigateTarget(slug, itemId, root),
+				root
 			})
 		});
 	}
 }
-async function doEnsureItemNotification(slug, schema, itemId, legacyId, displayLabel, priority) {
+async function doEnsureItemNotification({ slug, schema, itemId, legacyId, displayLabel, priority, root }) {
 	const adapter = requireAdapter();
 	try {
-		const existing = await findActiveEntries(slug, itemId);
+		const existing = await findActiveEntries(slug, itemId, root);
 		if (existing.length > 0) {
-			await reconcileEntrySeverity(slug, itemId, existing, priority);
+			await reconcileEntrySeverity(slug, itemId, existing, priority, root);
 			return;
 		}
-		const navigateTarget = adapter.buildNavigateTarget(slug, itemId);
+		const navigateTarget = adapter.buildNavigateTarget(slug, itemId, root);
 		await require_notifier.publish({
 			pluginPkg: adapter.pluginPkg,
 			severity: adapter.priorityToSeverity(priority),
@@ -154,7 +200,8 @@ async function doEnsureItemNotification(slug, schema, itemId, legacyId, displayL
 				slug,
 				itemId,
 				priority,
-				navigateTarget
+				navigateTarget,
+				root
 			})
 		});
 	} catch (err) {
@@ -168,9 +215,9 @@ async function doEnsureItemNotification(slug, schema, itemId, legacyId, displayL
 /** Idempotently clear EVERY bell entry that matches this (slug, itemId).
 *  Silent no-op when nothing matches. The "every" is defensive: if a
 *  duplicate ever slips through, this drains the lot. */
-async function clearItemNotification(slug, itemId) {
+async function clearItemNotification(slug, itemId, root) {
 	try {
-		const ids = await findActiveEntryIds(slug, itemId);
+		const ids = await findActiveEntryIds(slug, itemId, root);
 		for (const entryId of ids) await require_notifier.clear(entryId);
 	} catch (err) {
 		log().warn("notify clear failed", {
@@ -190,18 +237,19 @@ async function clearItemNotification(slug, itemId) {
 *  `{ workspaceRoot: <tmpdir> }` so the check accepts a fixture dataDir. */
 async function reconcileItem(collection, itemId, ioOpts = {}, now = evalNow()) {
 	const { slug, schema } = collection;
+	const root = ioOpts.workspaceRoot;
 	if (!schema.completionField) {
-		await clearItemNotification(slug, itemId);
+		await clearItemNotification(slug, itemId, root);
 		return;
 	}
 	const item = await require_discovery.storeFor(collection, ioOpts).read(itemId);
 	if (item === null) {
-		await clearItemNotification(slug, itemId);
+		await clearItemNotification(slug, itemId, root);
 		return;
 	}
 	await require_server.maybeSpawnSuccessor(collection, item, itemId, ioOpts);
 	if (require_promptSafety.itemIsDone(schema, item)) {
-		await clearItemNotification(slug, itemId);
+		await clearItemNotification(slug, itemId, root);
 		return;
 	}
 	if (schema.triggerField) {
@@ -213,15 +261,15 @@ async function reconcileItem(collection, itemId, ioOpts = {}, now = evalNow()) {
 			triggerField: schema.triggerField
 		});
 		if (due !== true) {
-			await clearItemNotification(slug, itemId);
+			await clearItemNotification(slug, itemId, root);
 			return;
 		}
 	}
 	if (!require_promptSafety.whenMatches(schema.notifyWhen, item)) {
-		await clearItemNotification(slug, itemId);
+		await clearItemNotification(slug, itemId, root);
 		return;
 	}
-	await ensureItemNotification(slug, schema, itemId, resolveDisplayLabel(schema, item, itemId), notifyPriorityForItem(schema, item));
+	await ensureItemNotification(slug, schema, itemId, resolveDisplayLabel(schema, item, itemId), notifyPriorityForItem(schema, item), root);
 }
 /** Boot-time reconcile: walk every record of the collection once (through
 *  its store) and reconcile it. Catches up changes that happened while the
@@ -252,6 +300,36 @@ async function reconcileAllItems(collection, ioOpts = {}, now = evalNow()) {
 *  file is gone, whose collection was deleted, whose schema no longer
 *  tracks completion, or whose item is now done. Reverse-covers the cases
 *  `reconcileAllItems` misses (it only walks files that exist). */
+/** What this sweep should do with an entry, given the root it belongs to and
+*  the root the sweep is running for.
+*
+*  - `mine` — same root (or both root-less: the single-workspace case, which
+*    behaves exactly as it always did). Judge it against the records on disk.
+*  - `skip` — ANOTHER root's entry. Its collection and records live in a tree
+*    this sweep cannot see, so every check would read "gone" and clear a
+*    perfectly live bell. Two roots share one notifier file; this is the
+*    boundary between them.
+*  - `drop-legacy` — a root-less entry seen by a sweep that HAS a root: a
+*    leftover from before bell ids carried one. Nothing this host does from now
+*    on produces a root-less id, so skipping it would strand a bell no pass can
+*    ever clear, while the reconcile publishes a second rooted one beside it.
+*    Clearing converges — the record republishes rooted if still pending. */
+function sweepVerdict(entryRoot, ownRoot) {
+	if (entryRoot === ownRoot) return "mine";
+	if (entryRoot === void 0) return "drop-legacy";
+	return "skip";
+}
+/** Should this entry's bell be dropped? True when the collection is gone, no
+*  longer tracks completion, or the record is missing / done / outside
+*  `notifyWhen`. The reverse of the reconcile invariant, applied to an entry
+*  whose record the forward pass can never walk to (a delete leaves a bell that
+*  a walk over the SURVIVING records cannot clear). */
+async function isStaleEntry(slug, itemId, opts) {
+	const collection = await require_discovery.loadCollection(slug, opts);
+	if (!collection || !collection.schema.completionField) return true;
+	const item = await require_discovery.storeFor(collection, opts).read(itemId);
+	return item === null || require_promptSafety.itemIsDone(collection.schema, item) || !require_promptSafety.whenMatches(collection.schema.notifyWhen, item);
+}
 async function sweepStaleActiveEntries(opts = {}) {
 	const adapter = requireAdapter();
 	let entries;
@@ -261,20 +339,21 @@ async function sweepStaleActiveEntries(opts = {}) {
 		log().warn("sweep list failed", { error: errMsg(err) });
 		return;
 	}
+	const ownRoot = opts.workspaceRoot === void 0 ? void 0 : require_root.canonicalRoot(opts.workspaceRoot);
 	for (const entry of entries) {
 		const own = adapter.readEntry(entry.pluginData);
 		if (!own) continue;
 		const parsed = parseCompletionLegacyId(own.legacyId);
 		if (!parsed) continue;
+		const verdict = sweepVerdict(parsed.root, ownRoot);
+		if (verdict === "skip") continue;
+		if (verdict === "drop-legacy") {
+			await require_notifier.clear(entry.id);
+			continue;
+		}
 		const { slug, itemId } = parsed;
 		try {
-			const collection = await require_discovery.loadCollection(slug, opts);
-			if (!collection || !collection.schema.completionField) {
-				await require_notifier.clear(entry.id);
-				continue;
-			}
-			const item = await require_discovery.storeFor(collection, opts).read(itemId);
-			if (item === null || require_promptSafety.itemIsDone(collection.schema, item) || !require_promptSafety.whenMatches(collection.schema.notifyWhen, item)) await require_notifier.clear(entry.id);
+			if (await isStaleEntry(slug, itemId, opts)) await require_notifier.clear(entry.id);
 		} catch (err) {
 			log().warn("sweep entry failed", {
 				slug,
@@ -294,173 +373,205 @@ var ONE_SECOND_MS = 1e3;
 var ONE_MINUTE_MS = 60 * ONE_SECOND_MS;
 var REDISCOVERY_INTERVAL_MS = 30 * ONE_SECOND_MS;
 var TRIGGER_TICK_INTERVAL_MS = ONE_MINUTE_MS;
-var watchers = /* @__PURE__ */ new Map();
-var rediscoveryTimer = null;
-var triggerTimer = null;
-var started = false;
-/** Guards the clock tick against overlapping itself. Paired with
-*  `watcherEpoch`: a teardown while a pass is in flight bumps the epoch, so
-*  that pass's `finally` knows it belongs to a dead generation and must not
-*  clear a guard the restarted watcher set now owns. `triggerTickInFlight`
-*  is what teardown AWAITS — clearing the flag alone would let a restart run
-*  a second pass alongside the first. */
-var triggerTickRunning = false;
-var watcherEpoch = 0;
-var triggerTickInFlight = null;
-/** The boot pass, from before its first await until it settles. This is the
-*  generation CLAIM: `started` flips only at the end of boot, so it cannot by
-*  itself stop two concurrent starts from racing each other's state. Teardown
-*  awaits this too, so a boot in flight can't arm its intervals after the stop
-*  that was meant to disarm them. */
-var bootInFlight = null;
-/** The root the running (or booting) generation belongs to, NORMALIZED: an
-*  omitted `workspaceRoot` resolves to the host's configured default, so
-*  `start()` and `start({ workspaceRoot: <that same default> })` are the same
-*  generation rather than a spurious conflict. Distinct from
-*  `discoveryOpts.workspaceRoot`, which stays un-normalized because the change
-*  payload's `root` means "an explicit root was passed", not "this root". */
-var activeRoot;
-/** `err.code` on the conflict throw below: another ROOT's watcher generation is
-*  already up. Distinct from `COLLECTION_ROOT_REQUIRED` (this call forgot its
-*  `workspaceRoot`) because the fixes differ — stop the running generation
-*  versus pass the option — and a host that catches watcher startup in one
-*  fire-and-forget `.catch` should not have to match on message text. */
+/** Live generations, keyed by NORMALIZED root: an omitted `workspaceRoot`
+*  resolves to the host's configured default, so `start()` and
+*  `start({ workspaceRoot: <that same default> })` join one generation rather
+*  than mounting two watchers over the same tree. */
+var generations = /* @__PURE__ */ new Map();
+/** Map key for a normalized root. `""` stands for "the host has no configured
+*  default and this call named no root" — a state in which discovery itself
+*  would throw, so at most one such generation can meaningfully exist. */
+var generationKey = (root) => root ?? "";
+/** Retained for hosts that catch it. NO LONGER THROWN: starting a second root
+*  now mounts a second generation instead of refusing. It stays exported
+*  because the refusal was a documented, catchable failure and a host's
+*  `.catch` branch for it must keep compiling — and because a future host-side
+*  constraint that reintroduces a conflict should reuse this code rather than
+*  invent a second one. */
 var WATCHER_ROOT_CONFLICT = "WATCHER_ROOT_CONFLICT";
 /** The root a start request resolves to: its explicit override, else the host's
 *  configured default. `peekWorkspaceRoot` rather than `getWorkspaceRoot` — this
 *  is a comparison, and under an explicit-root binding there is no default to
 *  read, which is not an error here. */
 function effectiveRoot(opts) {
-	return opts?.workspaceRoot ?? require_discovery.peekWorkspaceRoot() ?? void 0;
-}
-/** Discovery options threaded into every `discoverCollections` /
-*  `loadCollection` / `sweepStaleActiveEntries` call. Production: empty
-*  (live workspace). Tests: `{ workspaceRoot, userSkillsDir }` pointing
-*  at a fixture tree. Module-level so per-event handlers can read it
-*  without threading through every signature. */
-var discoveryOpts = {};
-var itemSlots = /* @__PURE__ */ new Map();
-/** Per-slug single-flight for a COLLECTION-granularity reconcile — a burst
-*  of changes the store couldn't attribute to a record collapses into one
-*  pass plus one trailing re-run, mirroring the per-item slots. */
-var collectionSlots = /* @__PURE__ */ new Map();
+	const root = opts?.workspaceRoot ?? require_discovery.peekWorkspaceRoot() ?? void 0;
+	return root === void 0 ? void 0 : require_root.canonicalRoot(root);
+}
+/** The discovery options a generation runs under, with an explicit root put in
+*  canonical form. Everything downstream — the change payload's `root`, the
+*  bell id the reconciler derives — reads it from here, so canonicalising once
+*  at the claim is what keeps those three consistent. An omitted root stays
+*  omitted: "no explicit root" is a distinct state, not a root to normalise. */
+function canonicalDiscoveryOpts(opts) {
+	const base = opts ?? {};
+	return base.workspaceRoot === void 0 ? base : {
+		...base,
+		workspaceRoot: require_root.canonicalRoot(base.workspaceRoot)
+	};
+}
+function newGeneration(discoveryOpts) {
+	return {
+		discoveryOpts,
+		watchers: /* @__PURE__ */ new Map(),
+		itemSlots: /* @__PURE__ */ new Map(),
+		collectionSlots: /* @__PURE__ */ new Map(),
+		rediscoveryTimer: null,
+		triggerTimer: null,
+		started: false,
+		triggerTickRunning: false,
+		triggerTickInFlight: null,
+		alive: true,
+		bootInFlight: null
+	};
+}
+/** The generation used when NO watcher is running at all. Several tests (and a
+*  host that drives a reconcile directly) call the reconcile helpers without a
+*  boot; they still need ONE stable set of single-flight slots, or a burst of
+*  calls that should coalesce into a single publish would each get their own
+*  slot. Created lazily and dropped by a full `stopCollectionWatchers()`. */
+var detachedGeneration = null;
+function fallbackGeneration() {
+	detachedGeneration ??= newGeneration({});
+	return detachedGeneration;
+}
+/** The generation a test helper or a root-less call should act on: the one
+*  named by `workspaceRoot`, else the only one running, else the default
+*  root's. "The only one running" is what keeps the single-root test helpers
+*  (which name no root) working against a generation booted for a tmpdir. */
+function resolveGeneration(workspaceRoot) {
+	if (workspaceRoot !== void 0) return generations.get(generationKey(workspaceRoot));
+	if (generations.size === 1) return [...generations.values()][0];
+	return generations.get(generationKey(effectiveRoot(void 0)));
+}
 /** Boot entry point: sweep stale active entries, then mount watchers for
 *  every discovered collection and arm the periodic re-discovery poll.
-*  Idempotent for the SAME root — a second call is a no-op.
+*  Idempotent for the SAME root — a second call joins the first.
 *
-*  A second call for a DIFFERENT root throws. This module holds exactly one
-*  watcher generation per process (see the "single generation" note in the file
-*  header), so silently returning would leave the second root unwatched: direct
-*  file writes there — the canonical agent path — would emit neither
-*  live-refresh events nor completion bells, with nothing anywhere saying so.
-*  That is the same class of silent-wrong-root failure the explicit-root host
-*  binding exists to make loud, so it is loud here too. */
+*  A call for a DIFFERENT root mounts a SECOND generation beside the first, so
+*  a multi-root host can watch several projects at once. Each generation keeps
+*  its own watcher set, timers and single-flight slots, stamps its own root on
+*  its change payloads, and drives bells whose ids carry that root — which is
+*  what stops two projects' `tasks` collections from deduping into one bell. */
 async function startCollectionWatchers(opts = {}) {
-	const requested = effectiveRoot(opts.discoveryOpts);
-	if (started || bootInFlight !== null) {
-		if (requested !== activeRoot) throw Object.assign(/* @__PURE__ */ new Error(`@mulmoclaude/core/collection-watchers: watchers are already ${started ? "running" : "starting"} for root ${String(activeRoot)}; this process holds one watcher generation, so starting another for ${String(requested)} would leave it unwatched. Call stopCollectionWatchers() first, or run one process per root.`), { code: WATCHER_ROOT_CONFLICT });
-		await bootInFlight;
+	const key = generationKey(effectiveRoot(opts.discoveryOpts));
+	const existing = generations.get(key);
+	if (existing) {
+		await existing.bootInFlight;
 		return;
 	}
-	discoveryOpts = opts.discoveryOpts ?? {};
-	activeRoot = requested;
-	bootInFlight = bootWatchers(opts);
+	const gen = newGeneration(canonicalDiscoveryOpts(opts.discoveryOpts));
+	generations.set(key, gen);
+	gen.bootInFlight = bootWatchers(key, gen, opts);
 	try {
-		await bootInFlight;
+		await gen.bootInFlight;
 	} finally {
-		bootInFlight = null;
+		gen.bootInFlight = null;
 	}
 }
 /** The boot pass itself, owned by exactly one caller — `startCollectionWatchers`
 *  serialises entry into it. On failure it resets `discoveryOpts` so a
 *  supervisor / test harness can retry instead of being permanently latched. */
-async function bootWatchers(opts) {
+async function bootWatchers(key, gen, opts) {
 	try {
-		await sweepStaleActiveEntries(discoveryOpts);
-		await syncWatchers();
+		await sweepStaleActiveEntries(gen.discoveryOpts);
+		await syncWatchers(gen);
 		const intervalMs = opts.rediscoveryIntervalMs === void 0 ? REDISCOVERY_INTERVAL_MS : opts.rediscoveryIntervalMs;
 		if (intervalMs !== null) {
-			rediscoveryTimer = setInterval(() => {
-				syncWatchers().catch((err) => {
+			gen.rediscoveryTimer = setInterval(() => {
+				syncWatchers(gen).catch((err) => {
 					log().warn("watcher rediscovery failed", { error: errMsg(err) });
 				});
 			}, intervalMs);
-			rediscoveryTimer.unref();
+			gen.rediscoveryTimer.unref();
 		}
 		const triggerMs = opts.triggerTickIntervalMs === void 0 ? TRIGGER_TICK_INTERVAL_MS : opts.triggerTickIntervalMs;
 		if (triggerMs !== null) {
-			triggerTimer = setInterval(() => {
-				if (triggerTickRunning) return;
-				triggerTickRunning = true;
-				const epoch = watcherEpoch;
-				triggerTickInFlight = tickTimeTriggers().catch((err) => {
+			gen.triggerTimer = setInterval(() => {
+				if (gen.triggerTickRunning) return;
+				gen.triggerTickRunning = true;
+				gen.triggerTickInFlight = tickTimeTriggers(gen).catch((err) => {
 					log().warn("watcher trigger tick failed", { error: errMsg(err) });
 				}).finally(() => {
-					if (epoch !== watcherEpoch) return;
-					triggerTickRunning = false;
-					triggerTickInFlight = null;
+					if (!gen.alive) return;
+					gen.triggerTickRunning = false;
+					gen.triggerTickInFlight = null;
 				});
 			}, triggerMs);
-			triggerTimer.unref();
+			gen.triggerTimer.unref();
 		}
-		started = true;
+		gen.started = true;
 	} catch (err) {
-		discoveryOpts = {};
-		activeRoot = void 0;
+		gen.alive = false;
+		generations.delete(key);
 		throw err;
 	}
 }
-/** Tear down every watcher and stop the intervals, and release the root claim
-*  so a subsequent `startCollectionWatchers` may re-mount — for ANY root.
+/** Tear down watchers and stop their intervals, releasing the root claim so a
+*  subsequent `startCollectionWatchers` may re-mount.
+*
+*  SCOPE: `{ workspaceRoot }` stops exactly that root's generation and leaves
+*  every other project running — what a multi-root host wants when it closes
+*  one project. Called with NO options it stops ALL generations, which is what
+*  it has always meant for a single-workspace host (and for a test teardown
+*  that must not leak a timer into the next file).
 *
-*  This is a production API, not a test-only one. A single-workspace host never
-*  calls it (process exit reclaims the fds), but since starting a second root
-*  now throws, `stop()` → `start(otherRoot)` is the ONLY way a multi-root host
-*  switches projects. Await it: it waits out a boot still in flight and a clock
-*  pass still running, so the next start does not race the one it replaced. */
-async function stopCollectionWatchers() {
-	await bootInFlight?.catch(() => {});
-	if (rediscoveryTimer) {
-		clearInterval(rediscoveryTimer);
-		rediscoveryTimer = null;
+*  This is a production API, not a test-only one. Await it: it waits out a boot
+*  still in flight and a clock pass still running, so the next start does not
+*  race the one it replaced. */
+async function stopCollectionWatchers(opts) {
+	if (opts?.workspaceRoot !== void 0) {
+		const key = generationKey(effectiveRoot(opts));
+		const gen = generations.get(key);
+		if (gen) await stopGeneration(key, gen);
+		return;
+	}
+	for (const [key, gen] of [...generations.entries()]) await stopGeneration(key, gen);
+	if (opts?.workspaceRoot === void 0) detachedGeneration = null;
+}
+async function stopGeneration(key, gen) {
+	await gen.bootInFlight?.catch(() => {});
+	if (gen.rediscoveryTimer) {
+		clearInterval(gen.rediscoveryTimer);
+		gen.rediscoveryTimer = null;
 	}
-	if (triggerTimer) {
-		clearInterval(triggerTimer);
-		triggerTimer = null;
+	if (gen.triggerTimer) {
+		clearInterval(gen.triggerTimer);
+		gen.triggerTimer = null;
 	}
-	await triggerTickInFlight;
-	triggerTickInFlight = null;
-	watcherEpoch += 1;
-	triggerTickRunning = false;
-	for (const watcher of watchers.values()) try {
+	await gen.triggerTickInFlight;
+	gen.triggerTickInFlight = null;
+	gen.alive = false;
+	gen.triggerTickRunning = false;
+	for (const watcher of gen.watchers.values()) try {
 		watcher.unsubscribe();
 	} catch {}
-	watchers.clear();
-	itemSlots.clear();
-	collectionSlots.clear();
-	discoveryOpts = {};
-	activeRoot = void 0;
-	started = false;
+	gen.watchers.clear();
+	gen.itemSlots.clear();
+	gen.collectionSlots.clear();
+	gen.started = false;
+	generations.delete(key);
 }
 /** Test-only: manually trigger one rediscovery + reconcile pass. */
-async function _syncWatchersForTesting() {
-	return syncWatchers();
+async function _syncWatchersForTesting(workspaceRoot) {
+	const gen = resolveGeneration(workspaceRoot);
+	return gen ? syncWatchers(gen) : false;
 }
 /** Test-only: drive one wall-clock tick synchronously, with an optional
 *  injected clock. */
-async function _tickTimeTriggersForTesting(now) {
-	await tickTimeTriggers(now);
+async function _tickTimeTriggersForTesting(now, workspaceRoot) {
+	const gen = resolveGeneration(workspaceRoot);
+	if (gen) await tickTimeTriggers(gen, now);
 }
 /** Re-reconcile every watched collection that depends on the clock — i.e.
 *  declares `triggerField` (a bell that fires at a date) and/or `spawn`
 *  (recurrence whose successors come due over time). Collections with
 *  neither are skipped. Idempotent. Reads the watcher's cached
 *  `collection.schema` to avoid a per-tick disk read. */
-async function tickTimeTriggers(now = evalNow()) {
-	for (const entry of watchers.values()) {
+async function tickTimeTriggers(gen, now = evalNow()) {
+	for (const entry of gen.watchers.values()) {
 		const { schema } = entry.collection;
 		if (!schema.triggerField && !schema.spawn) continue;
-		await reconcileAllItems(entry.collection, discoveryOpts, now);
+		await reconcileAllItems(entry.collection, gen.discoveryOpts, now);
 	}
 }
 /** Reconcile the watcher set against the currently-discovered
@@ -468,30 +579,30 @@ async function tickTimeTriggers(now = evalNow()) {
 *  their items), drops watchers for vanished slugs, and re-reconciles
 *  items for collections whose schema changed. Runs a final sweep when
 *  this tick changed the watcher set or any schema. */
-async function syncWatchers() {
+async function syncWatchers(gen) {
 	let collections;
 	try {
-		collections = await require_discovery.discoverCollections(discoveryOpts);
+		collections = await require_discovery.discoverCollections(gen.discoveryOpts);
 	} catch (err) {
 		log().warn("watcher discover failed", { error: errMsg(err) });
 		return false;
 	}
-	const vanishedMutated = stopVanishedWatchers(new Set(collections.map((collection) => collection.slug)));
-	const schemaMutated = await reconcileChangedSchemas(collections);
-	const addedMutated = await startNewWatchers(collections);
+	const vanishedMutated = stopVanishedWatchers(gen, new Set(collections.map((collection) => collection.slug)));
+	const schemaMutated = await reconcileChangedSchemas(gen, collections);
+	const addedMutated = await startNewWatchers(gen, collections);
 	if (!vanishedMutated && !schemaMutated && !addedMutated) return false;
-	await sweepStaleActiveEntries(discoveryOpts);
+	await sweepStaleActiveEntries(gen.discoveryOpts);
 	return true;
 }
-function stopVanishedWatchers(liveSlugs) {
+function stopVanishedWatchers(gen, liveSlugs) {
 	let mutated = false;
-	for (const slug of [...watchers.keys()]) {
+	for (const slug of [...gen.watchers.keys()]) {
 		if (liveSlugs.has(slug)) continue;
-		const watcher = watchers.get(slug);
+		const watcher = gen.watchers.get(slug);
 		if (watcher) try {
 			watcher.unsubscribe();
 		} catch {}
-		watchers.delete(slug);
+		gen.watchers.delete(slug);
 		mutated = true;
 		log().info("watcher stopped", { slug });
 	}
@@ -506,10 +617,10 @@ function storagePathChanged(previous, next) {
 }
 /** Re-reconcile already-watched collections whose schema changed since
 *  the last tick. New collections fall through to `startNewWatchers`. */
-async function reconcileChangedSchemas(collections) {
+async function reconcileChangedSchemas(gen, collections) {
 	let mutated = false;
 	for (const collection of collections) {
-		const existing = watchers.get(collection.slug);
+		const existing = gen.watchers.get(collection.slug);
 		if (!existing) continue;
 		const nextJson = JSON.stringify(collection.schema);
 		if (existing.schemaJson === nextJson) continue;
@@ -518,8 +629,8 @@ async function reconcileChangedSchemas(collections) {
 			try {
 				existing.unsubscribe();
 			} catch {}
-			watchers.delete(collection.slug);
-			if (collection.schema.dataSource !== void 0) safePublish({
+			gen.watchers.delete(collection.slug);
+			if (collection.schema.dataSource !== void 0) safePublish(gen, {
 				slug: collection.slug,
 				op: "upsert"
 			});
@@ -529,8 +640,8 @@ async function reconcileChangedSchemas(collections) {
 		existing.schemaJson = nextJson;
 		existing.collection = collection;
 		log().info("watcher schema changed, re-reconciling", { slug: collection.slug });
-		await reconcileAllItems(collection, discoveryOpts);
-		if (collection.schema.dataSource !== void 0) safePublish({
+		await reconcileAllItems(collection, gen.discoveryOpts);
+		if (collection.schema.dataSource !== void 0) safePublish(gen, {
 			slug: collection.slug,
 			op: "upsert"
 		});
@@ -544,11 +655,11 @@ async function reconcileChangedSchemas(collections) {
 *  (logged and swallowed inside the starter) leaves `watchers` untouched, so
 *  the collection is retried next tick; counting that as a mutation made
 *  `syncWatchers` sweep on every tick for as long as the failure persisted. */
-async function startNewWatchers(collections) {
+async function startNewWatchers(gen, collections) {
 	let mutated = false;
 	for (const collection of collections) {
-		if (watchers.has(collection.slug)) continue;
-		if (await startWatcherFor(collection)) mutated = true;
+		if (gen.watchers.has(collection.slug)) continue;
+		if (await startWatcherFor(gen, collection)) mutated = true;
 	}
 	return mutated;
 }
@@ -561,13 +672,13 @@ async function startNewWatchers(collections) {
 *  A store without `watch` cannot report external changes at all — it is
 *  still registered (so bells reconcile at boot and on the clock tick), just
 *  without live updates. */
-async function startWatcherFor(collection) {
+async function startWatcherFor(gen, collection) {
 	const { slug } = collection;
 	try {
-		await reconcileAllItems(collection, discoveryOpts);
-		const store = require_discovery.storeFor(collection, discoveryOpts);
+		await reconcileAllItems(collection, gen.discoveryOpts);
+		const store = require_discovery.storeFor(collection, gen.discoveryOpts);
 		const unsubscribe = store.watch ? await store.watch((change) => {
-			handleStoreChange(slug, change).catch((err) => {
+			handleStoreChange(gen, slug, change).catch((err) => {
 				log().warn("store change handling failed", {
 					slug,
 					error: errMsg(err)
@@ -578,7 +689,7 @@ async function startWatcherFor(collection) {
 			log().warn("collection watcher could not arm, retrying next sync", { slug });
 			return false;
 		}
-		watchers.set(slug, {
+		gen.watchers.set(slug, {
 			slug,
 			dataDir: collection.dataDir,
 			unsubscribe,
@@ -605,26 +716,26 @@ async function startWatcherFor(collection) {
 *  store couldn't say which record, so re-derive everything and pair it with
 *  a sweep — a record deleted remotely leaves a bell that a walk over the
 *  SURVIVING records can never clear. */
-async function handleStoreChange(slug, change) {
+async function handleStoreChange(gen, slug, change) {
 	if (change.kind === "collection") {
-		await scheduleCollectionReconcile(slug);
+		await scheduleCollectionReconcile(gen, slug);
 		return;
 	}
-	const current = watchers.get(slug)?.collection;
+	const current = gen.watchers.get(slug)?.collection;
 	if (!current) return;
-	await scheduleItemReconcile(current, change.itemId);
+	await scheduleItemReconcile(gen, current, change.itemId);
 }
 /** Full re-derivation for a collection-granularity change, single-flighted
 *  per slug so a burst of writes collapses into one pass plus one trailing
 *  re-run. */
-function scheduleCollectionReconcile(slug) {
-	return runSingleFlight(collectionSlots, slug, async () => {
-		const collection = await require_discovery.loadCollection(slug, discoveryOpts);
+function scheduleCollectionReconcile(gen, slug) {
+	return runSingleFlight(gen.collectionSlots, slug, async () => {
+		const collection = await require_discovery.loadCollection(slug, gen.discoveryOpts);
 		if (!collection) return;
-		await reconcileAllItems(collection, discoveryOpts);
-		await sweepStaleActiveEntries(discoveryOpts);
+		await reconcileAllItems(collection, gen.discoveryOpts);
+		await sweepStaleActiveEntries(gen.discoveryOpts);
 	}, () => {
-		safePublish({
+		safePublish(gen, {
 			slug,
 			op: "upsert"
 		});
@@ -634,18 +745,19 @@ function scheduleCollectionReconcile(slug) {
 /** Test-only: feed one store-reported change through the same path a live
 *  subscription uses, so a test can pin how a change is reacted to without
 *  depending on fs.watch timing. */
-function _handleStoreChangeForTesting(slug, change) {
-	return handleStoreChange(slug, change);
+function _handleStoreChangeForTesting(slug, change, workspaceRoot) {
+	const gen = resolveGeneration(workspaceRoot);
+	return gen ? handleStoreChange(gen, slug, change) : Promise.resolve();
 }
 /** Test-only: drive one collection-granularity reconcile directly. */
-function _scheduleCollectionReconcileForTesting(slug) {
-	return scheduleCollectionReconcile(slug);
+function _scheduleCollectionReconcileForTesting(slug, workspaceRoot) {
+	return scheduleCollectionReconcile(resolveGeneration(workspaceRoot) ?? fallbackGeneration(), slug);
 }
-function _scheduleItemReconcileForTesting(collection, itemId) {
-	return scheduleItemReconcile(collection, itemId);
+function _scheduleItemReconcileForTesting(collection, itemId, workspaceRoot) {
+	return scheduleItemReconcile(resolveGeneration(workspaceRoot) ?? fallbackGeneration(), collection, itemId);
 }
-function scheduleItemReconcile(collection, itemId) {
-	return runSingleFlight(itemSlots, `${collection.slug}\x00${itemId}`, () => reconcileItem(collection, itemId, discoveryOpts), () => publishItemChange(collection, itemId));
+function scheduleItemReconcile(gen, collection, itemId) {
+	return runSingleFlight(gen.itemSlots, `${collection.slug}\x00${itemId}`, () => reconcileItem(collection, itemId, gen.discoveryOpts), () => publishItemChange(gen, collection, itemId));
 }
 /** The shared single-flight loop behind both schedulers. Re-runs `pass`
 *  while events keep arriving — the trailing re-run captures any state
@@ -686,9 +798,9 @@ function runSingleFlight(slots, key, pass, onSettled) {
 *  of change nor, reliably, which of `rename`/`change` means what. Only
 *  file-backed collections reach here; a `storage` (db) collection has no
 *  per-record file and publishes wholesale in `scheduleStorageReconcile`. */
-async function publishItemChange(collection, itemId) {
+async function publishItemChange(gen, collection, itemId) {
 	const changeOp = await itemFileExists(collection.dataDir, itemId) ? "upsert" : "delete";
-	safePublish({
+	safePublish(gen, {
 		slug: collection.slug,
 		ids: [itemId],
 		op: changeOp
@@ -710,8 +822,8 @@ async function itemFileExists(dataDir, itemId) {
 *  carries only absolute paths, and a root reconstructed by string surgery
 *  would be a guess. Undefined in a single-workspace host, which is exactly
 *  what the payload contract means by "the host's configured root". */
-function safePublish(payload) {
-	const enriched = require_discovery.collectionChangePayload(payload, discoveryOpts.workspaceRoot);
+function safePublish(gen, payload) {
+	const enriched = require_discovery.collectionChangePayload(payload, gen.discoveryOpts.workspaceRoot);
 	try {
 		require_discovery.publishCollectionChange(enriched);
 	} catch (err) {