@dsh-electron/dsh-plugin-multi-root-workspace 0.1.11 → 0.1.13

package/lib/{registry-KSsmU393.js → registry-Bv431TfO.js}

@@ -1,13 +1,53 @@
+import { a as runPrimaryOperation, n as freezeOperationScope, o as runRegistryOperation } from "./registry-operation-C2ZV3Jhw.js";
 import { i as isWindowsNetworkOrDevicePath } from "./windows-runner-contract-B5R2K3mM.js";
 import { a as classifyStoredRoots, d as reservedRootBoundary, f as resolveRootIndex, i as canonicalRoot, m as validateRootCandidate, n as additionalRootId, r as availableRoots, s as expandRootInput, t as RootValidationError, u as removeStatusAt } from "./roots-Ca_W1S9n.js";
 import { r as validateAliasId, t as migrateRootSkills } from "./metadata-DgqSdVX_.js";
+import { a as snapshotSchema, i as parseArguments, r as AuthorityServer, s as storeIdentity, t as AuthorityClient } from "./protocol-CJOvAvOS.js";
 import { createRequire } from "node:module";
 import { closeSync, fstatSync, mkdirSync, openSync, statSync } from "node:fs";
 import { randomUUID } from "node:crypto";
-import { dirname, isAbsolute } from "node:path";
+import { basename, dirname, isAbsolute } from "node:path";
 import { Service } from "@deepseek-ai/cordis";
-import { defineDomain, domainTable } from "@deepseek-ai/dsh-storage-domain";
+import { DomainFacility, defineDomain, domainTable } from "@deepseek-ai/dsh-storage-domain";
 import { tryLockExclusive } from "@deepseek-ai/node-addon-system/flock";
+//#region src/compat/authority-storage.ts
+/** Open an explicitly bound medium through public storage APIs only. */
+async function openAuthorityStorage(ctx, root, spec) {
+	const { JsonStorageBackend } = await import("@deepseek-ai/dsh-storage-json");
+	const backend = new JsonStorageBackend(root);
+	const name = `multi-root-${randomUUID()}`;
+	const unmount = ctx.get("storage").backend.register(name, backend);
+	let facility;
+	const fiber = ctx.inject(["storage"], (scope) => {
+		facility = new DomainFacility(scope, {
+			backend: name,
+			routes: {}
+		});
+	});
+	try {
+		await fiber;
+		if (!facility) throw new Error("shared registry requires the storage hub");
+		const domain = await facility.open(spec);
+		return {
+			table: domain.table.bind(domain),
+			async close() {
+				try {
+					await domain.close();
+				} finally {
+					unmount();
+					await backend.close();
+					await fiber.dispose();
+				}
+			}
+		};
+	} catch (error) {
+		unmount();
+		await backend.close();
+		await fiber.dispose();
+		throw error;
+	}
+}
+//#endregion
 //#region src/compat/storage-zod.ts
 /**
 * Build the domain record schemas with the zod module the installed
@@ -54,6 +94,107 @@ function domainZod() {
 	return createRequire(require.resolve("@deepseek-ai/dsh-storage-domain/package.json"))("zod");
 }
 //#endregion
+//#region src/authority/recovery.ts
+var RecoveryScheduler = class {
+	run;
+	eligible;
+	enabled;
+	timers;
+	timer;
+	inFlight = false;
+	disposed = false;
+	attempts = 0;
+	retryAt;
+	constructor(options) {
+		this.run = options.run;
+		this.eligible = options.eligible;
+		this.enabled = options.enabled;
+		this.timers = options.timers ?? {
+			setTimeout,
+			clearTimeout,
+			random: Math.random,
+			now: Date.now
+		};
+	}
+	/**
+	* Ask for a recovery attempt. Called after every `ensureAuthority()` and on
+	* every downgrade event. A healthy state (`!eligible()`) resets the backoff;
+	* a pending timer or in-flight attempt is never duplicated or reset.
+	*/
+	arm() {
+		if (this.disposed || !this.enabled) return;
+		if (!this.eligible()) {
+			this.attempts = 0;
+			this.clearTimer();
+			return;
+		}
+		if (this.timer !== void 0 || this.inFlight) return;
+		const delay = this.delay(this.attempts);
+		this.retryAt = this.timers.now() + delay;
+		this.timer = this.timers.setTimeout(() => {
+			this.tick();
+		}, delay);
+		this.timer.unref();
+	}
+	/**
+	* Progress event (a follower connection was just adopted): the backoff is
+	* earned, so reset it and run the next attempt immediately — still through
+	* the single pending timer.
+	*/
+	kick() {
+		if (this.disposed || !this.enabled) return;
+		this.attempts = 0;
+		if (this.inFlight) return;
+		this.clearTimer();
+		this.retryAt = this.timers.now();
+		this.timer = this.timers.setTimeout(() => {
+			this.tick();
+		}, 0);
+		this.timer.unref();
+	}
+	/** Stop scheduling. An in-flight attempt is left to finish on its own. */
+	dispose() {
+		this.disposed = true;
+		this.clearTimer();
+	}
+	get state() {
+		return {
+			phase: this.disposed || !this.enabled && this.eligible() ? "disabled" : this.inFlight ? "attempting" : this.timer !== void 0 ? "waiting" : "idle",
+			attempts: this.attempts,
+			nextRetryAt: this.timer === void 0 ? void 0 : this.retryAt
+		};
+	}
+	clearTimer() {
+		if (this.timer !== void 0) {
+			this.timers.clearTimeout(this.timer);
+			this.timer = void 0;
+		}
+		this.retryAt = void 0;
+	}
+	delay(n) {
+		return Math.min(1e3 * 2 ** n, 3e4) * (.8 + .4 * this.timers.random());
+	}
+	async tick() {
+		this.timer = void 0;
+		this.retryAt = void 0;
+		if (!this.eligible()) {
+			this.attempts = 0;
+			return;
+		}
+		this.inFlight = true;
+		try {
+			await this.run();
+		} catch {}
+		this.inFlight = false;
+		if (this.disposed || !this.eligible()) {
+			this.attempts = 0;
+			return;
+		}
+		this.attempts++;
+		this.arm();
+	}
+};
+//#endregion
 //#region src/registry-lease.ts
 /**
 * Store-wide kernel lease for the multi-root registry.
@@ -209,8 +350,8 @@ var RegistryAuthorityLease = class RegistryAuthorityLease {
 *   only when the operator removes it (or when the store is repaired). Storage
 *   that cannot be parsed at all is backed up and skipped by the domain layer,
 *   with a warning.
-* - **Mutations are serialized per primary root.** Every mutation runs its
-*   whole read → validate → persist sequence inside one queue per key. The
+* - **Mutations and fs admissions are serialized store-wide.** Every mutation
+*   runs its whole read → validate → persist sequence inside the store queue. The
 *   storage domain serializes individual `put()`/`delete()` calls, which is not
 *   enough: two concurrent `add()` calls would both read the same snapshot and
 *   the later write would drop the earlier one, and a removal racing an add
@@ -251,6 +392,8 @@ const REGISTRY_CONTENDED_MESSAGE = "the root registry is owned by another DSH pr
 const DEFAULT_MAX_ADDITIONAL_ROOTS = 16;
 /** Hard ceiling for `maxAdditionalRoots`: values above it are config-invalid. */
 const MAX_ADDITIONAL_ROOTS_CEILING = 64;
+/** A medium/lock binding error only a changed configuration can repair. */
+var SharedConfigError = class extends Error {};
 /**
 * The durable-boundary validators. The builder is the zod module the
 * INSTALLED storage-domain resolves, not this package's own `zod` copy:
@@ -296,20 +439,46 @@ var MultiRootRegistry = class extends Service {
 	];
 	/** Absolute lock path; absent means the row was composed without `leasePath`. */
 	leasePath;
+	sharedStorageRoot;
+	authorityStorageContext;
+	medium;
+	server;
+	client;
+	connectionFailure;
+	connectionGeneration = 0;
+	/** Local cancel of the in-flight handshake; teardown must not wait out hello. */
+	connectionAbort;
+	remoteProjectionReady = false;
+	remoteRevisions = /* @__PURE__ */ new Map();
+	/**
+	* Primary roots whose projection must still be synced after a follower
+	* reconnect — populated from the tracked cache keys at adoption, removed as
+	* each `applySnapshot` lands. Recovery completes only when it empties.
+	*/
+	pendingSync = /* @__PURE__ */ new Set();
+	/** Bounded background retry for degraded authority states (ADR-0026 R1). */
+	recovery;
+	operationProof = Object.freeze({});
 	/** Whether this process currently owns the store. */
 	authorityState = { kind: "contended" };
 	/** Held kernel lease; present once acquire succeeded, including after a failed open. */
 	lease;
 	/** Open domain handle; present only while {@link authority} is `active`. */
 	domain;
+	/** The last failed `openDomain` reason; a repeat failure is not re-logged. */
+	lastOpenFailure;
 	/** The open table; present once this process is the authority. */
 	table;
 	/** Last classified status list per canonical primary root. */
 	cache = /* @__PURE__ */ new Map();
 	/** Signature of the last published grant per key, so a no-op refresh stays a no-op. */
 	published = /* @__PURE__ */ new Map();
-	/** One promise chain per canonical primary root: mutations never interleave. */
+	/** Pending store-ordered work, grouped by primary for teardown accounting. */
 	chains = /* @__PURE__ */ new Map();
+	/** Admissions and mutations share one order, including across primary roots. */
+	operationChain = Promise.resolve();
+	operationEpoch;
+	operationRevision = 0;
 	/** Store-wide queue for lease acquire / open / release. */
 	authorityChain = Promise.resolve();
 	/** Change listeners, keyed by their own disposer identity. */
@@ -328,7 +497,23 @@ var MultiRootRegistry = class extends Service {
 	*/
 	constructor(ctx, config = {}) {
 		super(ctx, "multiRootRegistry");
+		this.authorityStorageContext = ctx;
 		this.leasePath = config.leasePath;
+		this.sharedStorageRoot = config.sharedStorageRoot;
+		this.recovery = new RecoveryScheduler({
+			enabled: config.backgroundRecovery !== false,
+			eligible: () => !this.disposed && (this.authorityState.kind === "contended" || this.authorityState.kind === "storage-failed" && this.authorityState.recovery === "retryable" || this.authorityState.kind === "follower" && this.pendingSync.size > 0),
+			run: async () => {
+				if (this.authorityState.kind === "follower" && this.pendingSync.size > 0) {
+					await this.syncProjection();
+					return;
+				}
+				await this.ensureAuthority({ background: true });
+				if (this.client) await this.syncProjection();
+				this.noteRecoveryTransition();
+			}
+		});
+		if (config.sharedStorageRoot !== void 0) this.ctx.multiRootScope.requireAdmission(this.operationProof);
 		this.ctx.multiRootScope.setRegistryAuthority(false);
 		const configured = config.maxAdditionalRoots === void 0 ? 16 : config.maxAdditionalRoots;
 		if (Number.isInteger(configured) && configured >= 1 && configured <= 64) this.maxRoots = configured;
@@ -354,6 +539,7 @@ var MultiRootRegistry = class extends Service {
 		this.ctx.effect(() => () => this.releaseAuthority(), "multi-root-registry: authority release");
 		if (this.authorityState.kind === "config-invalid") {
 			this.ctx.logger.error(`multi-root-workspace: ${this.authorityState.reason}; no additional root is granted`);
+			this.noteRecoveryTransition();
 			return;
 		}
 		await this.ensureAuthority();
@@ -367,8 +553,9 @@ var MultiRootRegistry = class extends Service {
 	*/
 	get unavailable() {
 		switch (this.authorityState.kind) {
-			case "active": return;
-			case "contended": return REGISTRY_CONTENDED_MESSAGE;
+			case "active":
+			case "follower": return;
+			case "contended": return this.shared && this.connectionFailure ? `shared registry is unavailable: ${this.connectionFailure}` : REGISTRY_CONTENDED_MESSAGE;
 			case "storage-failed":
 			case "config-invalid": return this.authorityState.reason;
 		}
@@ -377,9 +564,64 @@ var MultiRootRegistry = class extends Service {
 	* Whether this process is the Registry Authority for the store-wide medium.
 	* Tests and diagnostics read this; surfaces use {@link unavailable}.
 	*/
+	get epoch() {
+		return this.authorityState.kind === "active" ? this.operationEpoch : this.client?.epoch;
+	}
+	get shared() {
+		return this.sharedStorageRoot !== void 0;
+	}
+	get available() {
+		return this.authorityState.kind === "active" || this.authorityState.kind === "follower";
+	}
 	get authority() {
 		return this.authorityState;
 	}
+	/** The class a degraded authority belongs to; `undefined` when healthy. */
+	get recoveryClass() {
+		switch (this.authorityState.kind) {
+			case "contended": return "retryable";
+			case "storage-failed": return this.authorityState.recovery;
+			case "config-invalid": return "config";
+			case "follower": return this.pendingSync.size > 0 ? "retryable" : void 0;
+			default: return;
+		}
+	}
+	/**
+	* Read-only diagnostics for operators: the authority state, the epoch, the
+	* last connection failure, and what the recovery scheduler is doing.
+	* `requires-restart` marks classes no timer will ever fix — a `config`
+	* row or a `quarantine`d store must NOT read as "retrying". Purely a read;
+	* it never arms or runs anything.
+	*/
+	get diagnostics() {
+		const recoveryClass = this.recoveryClass;
+		const scheduled = this.recovery.state;
+		return {
+			authorityState: this.authorityState,
+			epoch: this.epoch,
+			connectionFailure: this.connectionFailure,
+			recoveryClass,
+			recovery: {
+				phase: recoveryClass === "config" || recoveryClass === "quarantine" ? "requires-restart" : scheduled.phase,
+				attempts: scheduled.attempts,
+				nextRetryAt: scheduled.nextRetryAt,
+				pendingSync: this.pendingSync.size
+			}
+		};
+	}
+	/** The last logged `(kind, recoveryClass)` pair; dedupes transition logs. */
+	loggedRecovery;
+	/**
+	* Log one line per authority/recovery-class TRANSITION — never per tick:
+	* waiting↔attempting moves say nothing an operator did not already know.
+	*/
+	noteRecoveryTransition() {
+		const key = `${this.authorityState.kind}:${this.recoveryClass ?? ""}`;
+		if (this.loggedRecovery === key) return;
+		this.loggedRecovery = key;
+		const detail = this.authorityState.kind === "storage-failed" || this.authorityState.kind === "config-invalid" ? this.authorityState.reason : this.connectionFailure ?? "";
+		this.ctx.logger.info(this.recoveryClass === void 0 ? `multi-root-workspace: registry authority recovered (${this.authorityState.kind})` : `multi-root-workspace: registry authority is ${this.authorityState.kind} (${this.recoveryClass})${detail === "" ? "" : `: ${detail.slice(0, 200)}`}`);
+	}
 	/**
 	* The configured cap on stored additional-root records per primary root.
 	* Surfaces show it next to the count so "N of LIMIT" is always explainable.
@@ -430,11 +672,47 @@ var MultiRootRegistry = class extends Service {
 	*/
 	async refresh(primaryRoot) {
 		await this.ensureAuthority();
+		if (this.client) try {
+			return await this.remote("snapshot", [primaryRoot]);
+		} catch (error) {
+			if (this.client) throw error;
+			await this.ensureAuthority();
+			if (this.client) return await this.remote("snapshot", [primaryRoot]);
+		}
 		if (this.authorityState.kind !== "active") return [];
 		const key = canonicalRoot(primaryRoot);
 		return await this.serialize(key, () => this.reclassify(key));
 	}
 	/**
+	* Admit one fs invocation in the same order as mutations, then run its I/O
+	* OUTSIDE the queue. Revocation does not wait for already-admitted work.
+	* Shared followers obtain the same ordered snapshot through attested IPC.
+	*/
+	async withOperation(policy, kind, body) {
+		if (this.disposed) throw new Error("multi-root registry: cannot admit an operation after disposal");
+		const capturedPolicy = structuredClone(policy);
+		await this.ensureAuthority();
+		const key = canonicalRoot(capturedPolicy.workspaceRoot);
+		if (this.shared && this.available) {
+			const snapshot = this.client ? await this.remoteSnapshot("admit", [key]) : await this.captureSnapshot(key);
+			const scope = freezeOperationScope(this.ctx.multiRootScope.resolveSnapshot(capturedPolicy, this.projectRoots(snapshot.roots), snapshot.available));
+			return await runRegistryOperation(scope, kind, snapshot.epoch, snapshot.revision, body, this.operationProof, capturedPolicy.mode);
+		}
+		const admission = await this.serialize(key, () => {
+			if (this.disposed) throw new Error("multi-root registry: cannot admit an operation after disposal");
+			return {
+				scope: freezeOperationScope(this.shared ? this.ctx.multiRootScope.resolveSnapshot(capturedPolicy, this.projectRoots(this.cache.get(key) ?? []), false) : this.ctx.multiRootScope.resolve(capturedPolicy)),
+				epoch: this.operationEpoch,
+				revision: this.operationRevision
+			};
+		});
+		return await runRegistryOperation(admission.scope, kind, admission.epoch, admission.revision, body, this.operationProof, capturedPolicy.mode);
+	}
+	withPrimaryOperation(policy, body) {
+		const scope = this.ctx.multiRootScope.resolveSnapshot(policy, this.projectRoots(this.cache.get(canonicalRoot(policy.workspaceRoot)) ?? []), false);
+		return runPrimaryOperation(freezeOperationScope(scope), policy.mode, this.operationProof, body);
+	}
+	/**
 	* Registers one additional root.
 	* @param primaryRoot - the session workspace root the root belongs to.
 	* @param input - the directory and optional alias.
@@ -443,6 +721,7 @@ var MultiRootRegistry = class extends Service {
 	*/
 	async add(primaryRoot, input) {
 		await this.ensureAuthority();
+		if (this.client) return await this.remote("add", [primaryRoot, input]);
 		this.requireActive();
 		const key = canonicalRoot(primaryRoot);
 		return await this.serialize(key, async () => {
@@ -513,6 +792,11 @@ var MultiRootRegistry = class extends Service {
 	*/
 	async setAccess(primaryRoot, ref, access) {
 		await this.ensureAuthority();
+		if (this.client) return await this.remote("setAccess", [
+			primaryRoot,
+			ref,
+			access
+		]);
 		this.requireActive();
 		const key = canonicalRoot(primaryRoot);
 		return await this.serialize(key, async () => {
@@ -554,6 +838,7 @@ var MultiRootRegistry = class extends Service {
 	*/
 	async removeAt(primaryRoot, ref) {
 		await this.ensureAuthority();
+		if (this.client) return await this.remote("removeAt", [primaryRoot, ref]);
 		this.requireActive();
 		const key = canonicalRoot(primaryRoot);
 		return await this.serialize(key, async () => await this.persist(key, removeStatusAt(this.reclassify(key), ref)));
@@ -568,6 +853,11 @@ var MultiRootRegistry = class extends Service {
 	*/
 	async setAlias(primaryRoot, ref, alias) {
 		await this.ensureAuthority();
+		if (this.client) return await this.remote("setAlias", [
+			primaryRoot,
+			ref,
+			alias ?? null
+		]);
 		this.requireActive();
 		const key = canonicalRoot(primaryRoot);
 		return await this.serialize(key, async () => {
@@ -587,10 +877,22 @@ var MultiRootRegistry = class extends Service {
 	}
 	/** Change a Skill switch without changing any grant field. */
 	async setSkillsEnabled(primaryRoot, ref, skillsEnabled) {
+		await this.ensureAuthority();
+		if (this.client) return await this.remote("setSkillsEnabled", [
+			primaryRoot,
+			ref,
+			skillsEnabled
+		]);
 		if (typeof skillsEnabled !== "boolean") throw new RootValidationError("invalid-ref", "skillsEnabled must be a boolean");
 		return await this.setSkillsMetadata(primaryRoot, ref, { skillsEnabled });
 	}
 	async setAliasId(primaryRoot, ref, aliasId) {
+		await this.ensureAuthority();
+		if (this.client) return await this.remote("setAliasId", [
+			primaryRoot,
+			ref,
+			aliasId
+		]);
 		return await this.setSkillsMetadata(primaryRoot, ref, { aliasId });
 	}
 	async setSkillsMetadata(primaryRoot, ref, patch) {
@@ -617,6 +919,11 @@ var MultiRootRegistry = class extends Service {
 	*/
 	async move(primaryRoot, ref, beforeRef) {
 		await this.ensureAuthority();
+		if (this.client) return await this.remote("move", [
+			primaryRoot,
+			ref,
+			beforeRef ?? null
+		]);
 		this.requireActive();
 		const key = canonicalRoot(primaryRoot);
 		return await this.serialize(key, async () => {
@@ -645,6 +952,7 @@ var MultiRootRegistry = class extends Service {
 	*/
 	async recheck(primaryRoot) {
 		await this.ensureAuthority();
+		if (this.client) return await this.remote("recheck", [primaryRoot]);
 		this.requireActive();
 		const key = canonicalRoot(primaryRoot);
 		return await this.serialize(key, async () => await this.persist(key, this.reclassify(key)));
@@ -666,7 +974,10 @@ var MultiRootRegistry = class extends Service {
 	* @returns the canonical paths of every `available` root.
 	*/
 	granted(primaryRoot) {
-		return availableRoots(this.statusesOf(canonicalRoot(primaryRoot)));
+		return this.shared ? this.ctx.multiRootScope.snapshot({
+			workspaceRoot: primaryRoot,
+			mode: "workspace-write"
+		}).additionalRoots : availableRoots(this.statusesOf(canonicalRoot(primaryRoot)));
 	}
 	/**
 	* The scope the registry publishes: only usable roots, in registry order.
@@ -679,13 +990,22 @@ var MultiRootRegistry = class extends Service {
 	/** Classify one stored record set and cache it. */
 	accept(primaryRoot, record) {
 		const key = canonicalRoot(primaryRoot);
-		const statuses = classifyStoredRoots(key, record.roots.map(toRegisteredRoot));
+		const statuses = this.classify(key, record);
 		this.cache.set(key, statuses);
+		this.publish(key, statuses);
+		return statuses;
+	}
+	/**
+	* The pure half of {@link accept}: classification plus the over-limit
+	* warning, without writing the cache or the scope. {@link openDomain}
+	* staging uses it so a half-opened domain cannot materialize rows.
+	*/
+	classify(key, record) {
+		const statuses = classifyStoredRoots(key, record.roots.map(toRegisteredRoot));
 		if (statuses.length > this.maxRoots && !this.warnedOverLimit.has(key)) {
 			this.warnedOverLimit.add(key);
 			this.ctx.logger.warn(`multi-root-workspace: ${statuses.length} roots are stored for ${key}, above the configured limit of ${this.maxRoots}; all of them stay granted, only new adds are refused`);
 		}
-		this.publish(key, statuses);
 		return statuses;
 	}
 	/**
@@ -709,7 +1029,12 @@ var MultiRootRegistry = class extends Service {
 	*/
 	lookupRecords(key) {
 		if (this.authorityState.kind !== "active") return void 0;
-		return this.table?.get(key);
+		try {
+			return this.table?.get(key);
+		} catch (error) {
+			if (unknownStorageState(error)) this.enterStorageFailed("registry storage state cannot be confirmed; restart and reconcile", "quarantine");
+			throw error;
+		}
 	}
 	/**
 	* Re-classify one key from its stored records: every directory is `stat`ed
@@ -734,22 +1059,28 @@ var MultiRootRegistry = class extends Service {
 	async persist(key, statuses) {
 		const table = this.requireTable();
 		const durable = persistedPrimaryRoot.parse({ roots: migrateRootSkills(statuses.map(toPersistedRoot)) });
-		if (statuses.length === 0) await table.delete(key);
-		else await table.put(key, durable);
+		try {
+			if (statuses.length === 0) await table.delete(key);
+			else await table.put(key, durable);
+		} catch (error) {
+			if (unknownStorageState(error)) this.enterStorageFailed("registry write result is unknown; restart and reconcile durable state", "quarantine");
+			throw error;
+		}
 		const classified = statuses.length === 0 ? [] : classifyStoredRoots(key, durable.roots.map(toRegisteredRoot));
 		this.cache.set(key, classified);
 		this.publish(key, classified);
 		return classified;
 	}
 	/**
-	* Run one job for one primary root after every job already queued for that
-	* root. The whole read → validate → write sequence belongs inside the job:
+	* Run one job after every store job already queued. The whole
+	* read → validate → write sequence belongs inside the job:
 	* the storage domain serializes individual writes, so without this the loser
 	* of a race reads a snapshot that is already stale and writes it back.
 	*/
 	async serialize(key, job) {
-		const run = (this.chains.get(key) ?? Promise.resolve()).then(job);
+		const run = this.operationChain.then(job);
 		const tail = run.then(() => void 0, () => void 0);
+		this.operationChain = tail;
 		this.chains.set(key, tail);
 		try {
 			return await run;
@@ -781,7 +1112,7 @@ var MultiRootRegistry = class extends Service {
 		const withheld = statuses.filter((status) => status.state !== "available");
 		const signature = [...statuses.filter((status) => status.state === "available").map((status) => `available:${status.access}:${recordedGrantOf(status)}`), ...withheld.map((status) => `${status.state}:${status.invalidReason ?? ""}:${status.access}:${status.path}:${recordedGrantOf(status) ?? ""}`)].join("\n");
 		const previousMetadata = this.metadataPublished.get(key);
-		const metadata = JSON.stringify(statuses.map((row) => [
+		const metadata = JSON.stringify(this.shared ? statuses : statuses.map((row) => [
 			row.id,
 			row.aliasId,
 			row.skillsEnabled,
@@ -789,11 +1120,22 @@ var MultiRootRegistry = class extends Service {
 		]));
 		this.metadataPublished.set(key, metadata);
 		if ((this.published.get(key) ?? "") === signature) {
-			if (previousMetadata !== metadata && (previousMetadata !== void 0 || statuses.length > 0)) for (const listener of this.listeners) listener(key);
+			if (previousMetadata !== metadata && (previousMetadata !== void 0 || statuses.length > 0)) {
+				this.operationRevision++;
+				this.deliverNotifications(key);
+			}
 			return;
 		}
-		this.published.set(key, signature);
-		const effective = statuses.flatMap((status) => {
+		if (signature === "") this.published.delete(key);
+		else this.published.set(key, signature);
+		this.operationRevision++;
+		const effective = this.projectRoots(statuses);
+		this.ctx.multiRootScope.setAdditionalRoots(key, effective);
+		if (withheld.length > 0) this.ctx.logger.warn(`multi-root-workspace: ${withheld.length} registered root(s) of ${key} are not writable right now (${withheld.map((status) => `${status.path}: ${status.state}`).join(", ")}); they stay registered and are reported by /workspace-folders`);
+		this.deliverNotifications(key);
+	}
+	projectRoots(statuses) {
+		return statuses.flatMap((status) => {
 			const recorded = recordedGrantOf(status);
 			if (status.state === "invalid" && status.invalidReason !== "membership-conflict" || recorded === void 0) return [];
 			return [{
@@ -805,10 +1147,188 @@ var MultiRootRegistry = class extends Service {
 				...status.alias === void 0 ? {} : { alias: status.alias }
 			}];
 		});
-		this.ctx.multiRootScope.setAdditionalRoots(key, effective);
-		if (withheld.length > 0) this.ctx.logger.warn(`multi-root-workspace: ${withheld.length} registered root(s) of ${key} are not writable right now (${withheld.map((status) => `${status.path}: ${status.state}`).join(", ")}); they stay registered and are reported by /workspace-folders`);
+	}
+	snapshotOf(primary) {
+		return snapshotSchema.parse({
+			protocol: 1,
+			store: this.medium.id,
+			epoch: this.operationEpoch,
+			revision: this.operationRevision,
+			primary,
+			roots: this.cache.get(primary) ?? [],
+			available: this.authorityState.kind === "active"
+		});
+	}
+	async captureSnapshot(primary) {
+		const key = canonicalRoot(primary);
+		return await this.serialize(key, () => {
+			this.requireActive();
+			this.reclassify(key);
+			return this.snapshotOf(key);
+		});
+	}
+	notifyShared(key) {
+		if (this.server && this.authorityState.kind === "active") this.server.changed(this.snapshotOf(key));
+	}
+	/** Depth of {@link commit}; nested calls share the outer round's buffers. */
+	commitDepth = 0;
+	/** Keys whose publish inside a commit produced deferred notifications, first-seen order. */
+	commitNotifications = /* @__PURE__ */ new Set();
+	/**
+	* Run `body` as one Registry commit: scope writes inside it go through
+	* `multiRootScope.batch`, and the `notifyShared` broadcasts plus Registry
+	* listener calls `publish()` produces are collected per key instead of
+	* delivered. When the OUTERMOST commit ends — also when `body` throws — the
+	* scope batch flushes first, then the broadcasts go out in first-seen key
+	* order, then the listeners: no synchronous callback can observe a
+	* half-committed state.
+	*/
+	commit(body) {
+		this.commitDepth++;
+		try {
+			return this.ctx.multiRootScope.batch(body);
+		} finally {
+			if (--this.commitDepth === 0) {
+				const keys = [...this.commitNotifications];
+				this.commitNotifications.clear();
+				for (const key of keys) this.notifyShared(key);
+				for (const key of keys) for (const listener of this.listeners) listener(key);
+			}
+		}
+	}
+	/** Deliver one key's notifications now, or collect them inside a commit. */
+	deliverNotifications(key) {
+		if (this.commitDepth > 0) {
+			this.commitNotifications.add(key);
+			return;
+		}
+		this.notifyShared(key);
 		for (const listener of this.listeners) listener(key);
 	}
+	applySnapshot(snapshot) {
+		if (!this.client || snapshot.store !== this.medium?.id || snapshot.epoch !== this.client.epoch) return;
+		const previous = this.remoteRevisions.get(snapshot.primary) ?? -1;
+		if (snapshot.revision < previous) return;
+		this.remoteRevisions.set(snapshot.primary, snapshot.revision);
+		const rows = snapshot.roots.map((row) => Object.fromEntries(Object.entries({
+			...row,
+			id: additionalRootId(row.id)
+		}).filter(([, value]) => value !== void 0)));
+		this.commit(() => {
+			this.cache.set(snapshot.primary, rows);
+			this.publish(snapshot.primary, rows);
+			this.ctx.multiRootScope.setRegistryAuthority(snapshot.available);
+		});
+		this.remoteProjectionReady = snapshot.available;
+		this.pendingSync.delete(snapshot.primary);
+	}
+	remoteUnavailable() {
+		try {
+			this.connectionGeneration++;
+			this.client = void 0;
+			this.remoteRevisions.clear();
+			this.pendingSync.clear();
+			this.authorityState = { kind: "contended" };
+			this.ctx.multiRootScope.setRegistryAuthority(false);
+			if (!this.remoteProjectionReady) return;
+			this.remoteProjectionReady = false;
+			for (const [primary, rows] of this.cache) this.withholdScope(primary, rows);
+		} finally {
+			this.recovery.arm();
+			this.noteRecoveryTransition();
+		}
+	}
+	/**
+	* Resynchronize each still-pending tracked primary outside the authority
+	* queue: per-key snapshots through the live client. A failed key stays in
+	* `pendingSync` for the next tick; a lost connection abandons the round —
+	* `remoteUnavailable` already emptied the set.
+	*/
+	async syncProjection() {
+		for (const key of [...this.pendingSync]) try {
+			await this.remoteSnapshot("snapshot", [key]);
+		} catch {
+			if (!this.client) break;
+		}
+	}
+	/**
+	* Write one key's withheld-only projection into the scope, keeping
+	* `published` truthful: the signature records what the scope HOLDS, never
+	* what `publish()` last computed — a withheld signature can never equal a
+	* publish signature, so an empty snapshot afterwards really writes the
+	* retraction. A repeated write of the same withheld projection is a no-op
+	* (the same-signature skip is also the republish gate of a repeated
+	* downgrade). `metadataPublished` is untouched: a withheld write announces
+	* nothing to the Registry view.
+	*/
+	withholdScope(key, rows) {
+		const roots = this.projectRoots(rows).map((root) => ({
+			...root,
+			withheld: true
+		}));
+		const signature = roots.length === 0 ? "" : `\u0000withheld\n${JSON.stringify(roots)}`;
+		if ((this.published.get(key) ?? "") === signature) return;
+		if (signature === "") this.published.delete(key);
+		else this.published.set(key, signature);
+		this.ctx.multiRootScope.setAdditionalRoots(key, roots);
+	}
+	async remoteSnapshot(method, args) {
+		const client = this.client, generation = this.connectionGeneration;
+		if (!client) throw new Error("registry authority is unavailable");
+		const value = await client.request(method, args);
+		let snapshot;
+		try {
+			snapshot = snapshotSchema.parse(value);
+		} catch (error) {
+			client.close();
+			throw error;
+		}
+		if (generation !== this.connectionGeneration || client !== this.client || snapshot.store !== this.medium?.id || snapshot.epoch !== client.epoch || snapshot.primary !== canonicalRoot(String(args[0]))) {
+			client.close();
+			throw new Error("stale registry connection or authority epoch");
+		}
+		this.applySnapshot(snapshot);
+		return snapshot;
+	}
+	async remote(method, args) {
+		await this.remoteSnapshot(method, args);
+		return this.list(String(args[0]));
+	}
+	async dispatchShared(method, values) {
+		const args = parseArguments(method, values);
+		const primary = String(args[0]);
+		if (!isAbsolute(primary)) throw new Error("registry primary must be absolute");
+		if (method === "snapshot" || method === "admit") return this.captureSnapshot(primary);
+		const ref = args[1];
+		switch (method) {
+			case "add":
+				await this.add(primary, args[1]);
+				break;
+			case "removeAt":
+				await this.removeAt(primary, ref);
+				break;
+			case "setAccess":
+				await this.setAccess(primary, ref, args[2]);
+				break;
+			case "setAlias":
+				await this.setAlias(primary, ref, args[2] === null ? void 0 : args[2]);
+				break;
+			case "setSkillsEnabled":
+				await this.setSkillsEnabled(primary, ref, args[2]);
+				break;
+			case "setAliasId":
+				await this.setAliasId(primary, ref, args[2]);
+				break;
+			case "move":
+				await this.move(primary, ref, args[2] === null ? void 0 : args[2]);
+				break;
+			case "recheck":
+				await this.recheck(primary);
+				break;
+			default: throw new Error("unsupported registry method");
+		}
+		return this.captureSnapshot(primary);
+	}
 	/**
 	* The open table.
 	* @returns the live table.
@@ -817,6 +1337,7 @@ var MultiRootRegistry = class extends Service {
 	*   or an error when the service has not started.
 	*/
 	requireTable() {
+		if (this.authorityState.kind === "follower") throw new Error("a follower never opens registry storage");
 		if (this.authorityState.kind === "contended") throw new RootValidationError("registry-contended", REGISTRY_CONTENDED_MESSAGE);
 		if (this.authorityState.kind === "config-invalid") throw new RootValidationError("config-invalid", `the root registry configuration is invalid (${this.authorityState.reason}); no additional root is granted`);
 		if (this.authorityState.kind === "storage-failed") throw new RootValidationError("storage-unavailable", `the root registry store is unavailable (${this.authorityState.reason}); remove or repair \$DSH_HOME/storages/multi_root_workspace.json and restart dsh`);
@@ -837,36 +1358,93 @@ var MultiRootRegistry = class extends Service {
 	* retries here (the command `list` and the panel Retry button both call
 	* {@link MultiRootRegistry.refresh}).
 	*/
-	async ensureAuthority() {
-		await this.serializeAuthority(async () => {
-			if (this.disposed) return;
-			if (this.authorityState.kind === "active") return;
-			if (this.authorityState.kind === "config-invalid") return;
-			if (this.lease !== void 0) {
-				await this.openDomain();
-				return;
-			}
-			const leasePath = this.leasePath;
-			if (leasePath === void 0 || leasePath === "") {
-				this.enterStorageFailed(`${DOMAIN_NAME}: leasePath is not configured; set it next to storage-json.root (default $DSH_HOME/storages/${DOMAIN_NAME}.lock)`);
-				return;
-			}
-			if (!isAbsolute(leasePath)) {
-				this.enterStorageFailed(`${DOMAIN_NAME}: leasePath must be an absolute path`);
-				return;
-			}
-			try {
-				this.lease = await RegistryAuthorityLease.acquire(leasePath);
-			} catch (error) {
-				if (error instanceof RegistryLeaseContendedError) {
-					this.enterContended();
+	async ensureAuthority(options = {}) {
+		try {
+			await this.serializeAuthority(async () => {
+				if (this.disposed) return;
+				if (this.authorityState.kind === "active" || this.client !== void 0) return;
+				if (this.authorityState.kind === "config-invalid") return;
+				if (this.authorityState.kind === "storage-failed" && this.authorityState.recovery !== "retryable") return;
+				if (this.lease !== void 0) {
+					if (this.domain !== void 0) return;
+					await this.openDomain();
 					return;
 				}
-				this.enterStorageFailed(`${DOMAIN_NAME}: cannot acquire the registry lease: ${error instanceof Error ? error.message : String(error)}`);
-				return;
-			}
-			await this.openDomain();
-		});
+				const leasePath = this.leasePath;
+				if (leasePath === void 0 || leasePath === "") {
+					this.enterStorageFailed(`${DOMAIN_NAME}: leasePath is not configured; set it next to storage-json.root (default $DSH_HOME/storages/${DOMAIN_NAME}.lock)`, "config");
+					return;
+				}
+				if (!isAbsolute(leasePath)) {
+					this.enterStorageFailed(`${DOMAIN_NAME}: leasePath must be an absolute path`, "config");
+					return;
+				}
+				if (this.sharedStorageRoot !== void 0 && this.medium === void 0) try {
+					if (!isAbsolute(this.sharedStorageRoot)) throw new SharedConfigError("sharedStorageRoot must be absolute");
+					const medium = storeIdentity(this.sharedStorageRoot);
+					if (storeIdentity(dirname(leasePath)).id !== medium.id || basename(leasePath) !== `multi_root_workspace.lock`) throw new SharedConfigError("shared registry requires its canonical medium lock, without alternate lock names");
+					this.medium = medium;
+				} catch (error) {
+					this.enterStorageFailed(String(error), error instanceof SharedConfigError ? "config" : "retryable");
+					return;
+				}
+				try {
+					this.lease = await RegistryAuthorityLease.acquire(leasePath);
+				} catch (error) {
+					if (error instanceof RegistryLeaseContendedError) {
+						this.enterContended();
+						if (this.medium !== void 0) for (const delay of options.background ? [0] : [
+							0,
+							50,
+							150
+						]) {
+							if (delay) await new Promise((resolve) => setTimeout(resolve, delay));
+							if (this.disposed) return;
+							const generation = ++this.connectionGeneration;
+							const controller = new AbortController();
+							this.connectionAbort = controller;
+							let adopted = false;
+							try {
+								const client = await AuthorityClient.connect(this.medium.endpoint, this.medium.id, this.maxRoots, (snapshot) => {
+									if (adopted && generation === this.connectionGeneration) this.applySnapshot(snapshot);
+								}, () => {
+									if (adopted && generation === this.connectionGeneration) this.remoteUnavailable();
+								}, controller.signal);
+								if (this.disposed || generation !== this.connectionGeneration) {
+									client.close();
+									return;
+								}
+								this.client = client;
+								adopted = true;
+								this.connectionFailure = void 0;
+								this.authorityState = {
+									kind: "follower",
+									epoch: client.epoch
+								};
+								this.pendingSync = new Set(this.cache.keys());
+								if (this.pendingSync.size === 0) {
+									this.ctx.multiRootScope.setRegistryAuthority(true);
+									this.remoteProjectionReady = true;
+								}
+								this.recovery.kick();
+								break;
+							} catch (error) {
+								this.connectionFailure = String(error);
+							} finally {
+								if (this.connectionAbort === controller) this.connectionAbort = void 0;
+							}
+						}
+						return;
+					}
+					this.enterStorageFailed(`${DOMAIN_NAME}: cannot acquire the registry lease: ${error instanceof Error ? error.message : String(error)}`, "retryable");
+					return;
+				}
+				await this.openDomain();
+			});
+		} finally {
+			this.recovery.arm();
+			this.noteRecoveryTransition();
+		}
 	}
 	/**
 	* Open the domain under an already-held lease and publish every stored root.
@@ -876,35 +1454,78 @@ var MultiRootRegistry = class extends Service {
 	async openDomain() {
 		let domain;
 		try {
-			domain = await this.ctx.storageDomain.open(multiRootDomainSpec);
+			domain = this.medium === void 0 ? await this.ctx.storageDomain.open(multiRootDomainSpec) : await openAuthorityStorage(this.authorityStorageContext, this.medium.root, multiRootDomainSpec);
 		} catch (error) {
 			const reason = `${DOMAIN_NAME}: ${error instanceof Error ? error.message : String(error)}`;
-			this.ctx.logger.error(`multi-root-workspace: cannot open the root registry store (${DOMAIN_NAME}); no additional root is granted until it is repaired or removed: ${reason}`);
-			this.enterStorageFailed(reason);
+			if (this.lastOpenFailure !== reason) {
+				this.lastOpenFailure = reason;
+				this.ctx.logger.error(`multi-root-workspace: cannot open the root registry store (${DOMAIN_NAME}); no additional root is granted until it is repaired or removed: ${reason}`);
+			}
+			this.enterStorageFailed(reason, "retryable");
 			return;
 		}
-		this.domain = domain;
-		this.table = domain.table(TABLE_NAME);
-		this.authorityState = { kind: "active" };
-		this.loggedContended = false;
-		this.cache.clear();
-		this.published.clear();
-		for (const [primaryRoot, record] of this.table.entries()) await this.serialize(canonicalRoot(primaryRoot), async () => {
-			const migrated = { roots: migrateRootSkills(record.roots) };
-			let accepted = record;
-			if (JSON.stringify(migrated) !== JSON.stringify(record)) try {
-				await this.table.put(primaryRoot, migrated);
-				accepted = migrated;
-			} catch (error) {
-				this.ctx.logger.warn(`multi-root skills: metadata migration failed; Skills remain withheld: ${String(error)}`);
+		const epoch = randomUUID();
+		const staged = /* @__PURE__ */ new Map();
+		let table;
+		try {
+			table = domain.table(TABLE_NAME);
+			for (const [primaryRoot, record] of table.entries()) {
+				const migrated = { roots: migrateRootSkills(record.roots) };
+				let accepted = record;
+				if (JSON.stringify(migrated) !== JSON.stringify(record)) try {
+					await table.put(primaryRoot, migrated);
+					accepted = migrated;
+				} catch (error) {
+					if (unknownStorageState(error)) {
+						this.domain = domain;
+						this.enterStorageFailed("Skills migration result is unknown; restart and reconcile", "quarantine");
+						return;
+					}
+					this.ctx.logger.warn(`multi-root skills: metadata migration failed; Skills remain withheld: ${String(error)}`);
+				}
+				const key = canonicalRoot(primaryRoot);
+				staged.set(key, this.classify(key, accepted));
 			}
-			this.accept(primaryRoot, accepted);
+		} catch (error) {
+			if (unknownStorageState(error)) {
+				this.domain = domain;
+				this.enterStorageFailed("registry storage state cannot be confirmed; restart and reconcile", "quarantine");
+				return;
+			}
+			try {
+				await domain.close();
+			} catch {}
+			throw error;
+		}
+		let server;
+		if (this.medium !== void 0) try {
+			server = await AuthorityServer.listen(this.medium.endpoint, this.medium.id, epoch, this.maxRoots, (method, args) => this.dispatchShared(method, args));
+		} catch (error) {
+			await domain.close();
+			this.enterStorageFailed(`cannot start shared registry: ${String(error)}`, "retryable");
+			return;
+		}
+		this.commit(() => {
+			this.domain = domain;
+			this.table = table;
+			this.operationEpoch = epoch;
+			this.operationRevision = 0;
+			this.authorityState = { kind: "active" };
+			this.loggedContended = false;
+			this.server = server;
+			const earlier = new Set(this.cache.keys());
+			this.cache.clear();
+			for (const [key, statuses] of staged) this.cache.set(key, statuses);
+			for (const key of /* @__PURE__ */ new Set([...earlier, ...staged.keys()])) this.publish(key, staged.get(key) ?? []);
+			this.ctx.multiRootScope.setRegistryAuthority(true);
+			this.lastOpenFailure = void 0;
 		});
-		this.ctx.multiRootScope.setRegistryAuthority(true);
 	}
 	/** Fail closed: empty scope, no table, contended state. */
 	enterContended() {
-		this.withdrawPublished();
+		this.operationEpoch = void 0;
+		if (this.shared) this.remoteUnavailable();
+		else this.withdrawPublished();
 		this.ctx.multiRootScope.setRegistryAuthority(false);
 		this.table = void 0;
 		this.authorityState = { kind: "contended" };
@@ -914,14 +1535,21 @@ var MultiRootRegistry = class extends Service {
 		}
 	}
 	/** Fail closed: empty scope, no table, storage-failed state. The lease, if held, stays. */
-	enterStorageFailed(reason) {
-		this.withdrawPublished();
+	enterStorageFailed(reason, recovery) {
+		this.operationEpoch = void 0;
 		this.ctx.multiRootScope.setRegistryAuthority(false);
+		if (this.shared) {
+			for (const [key, rows] of this.cache) this.withholdScope(key, rows);
+			this.server?.close();
+			this.server = void 0;
+		} else this.withdrawPublished();
 		this.table = void 0;
 		this.authorityState = {
 			kind: "storage-failed",
-			reason
+			reason,
+			recovery
 		};
+		this.noteRecoveryTransition();
 	}
 	/** Drop every grant this process has published. Idempotent. */
 	withdrawPublished() {
@@ -945,8 +1573,16 @@ var MultiRootRegistry = class extends Service {
 	*/
 	async releaseAuthority() {
 		this.disposed = true;
+		this.connectionGeneration++;
+		this.recovery.dispose();
+		this.connectionAbort?.abort();
+		this.client?.close();
+		this.client = void 0;
 		await this.serializeAuthority(async () => {
+			this.server?.close();
+			this.server = void 0;
 			this.table = void 0;
+			this.operationEpoch = void 0;
 			this.authorityState = { kind: "contended" };
 			this.ctx.multiRootScope.setRegistryAuthority(false);
 			await this.drainMutations();
@@ -964,7 +1600,7 @@ var MultiRootRegistry = class extends Service {
 		});
 	}
 	/**
-	* Wait until no per-primary-root mutation is queued or running.
+	* Wait until no store work is queued or running (operation I/O is outside).
 	*
 	* One pass is enough, and only because the authority state has already been
 	* flipped: no further mutation can be admitted (it would fail in
@@ -1063,5 +1699,12 @@ function normalizeAlias(alias) {
 	if (trimmed.length > 120) throw new RootValidationError("invalid-alias", `an alias must be at most 120 characters`);
 	return trimmed;
 }
+/** Structural across storage releases; older versions do not expose this code. */
+function unknownStorageState(error, seen = /* @__PURE__ */ new Set()) {
+	if (error === null || typeof error !== "object" || seen.has(error)) return false;
+	seen.add(error);
+	const value = error;
+	return value.code === "unknown-state" || unknownStorageState(value.cause, seen) || Array.isArray(value.errors) && value.errors.some((item) => unknownStorageState(item, seen));
+}
 //#endregion
 export { MultiRootRegistry as a, multiRootDomainSpec as c, MAX_ALIAS_LENGTH as i, RegistryAuthorityLease as l, DOMAIN_NAME as n, REGISTRY_CONTENDED_MESSAGE as o, MAX_ADDITIONAL_ROOTS_CEILING as r, TABLE_NAME as s, DEFAULT_MAX_ADDITIONAL_ROOTS as t, RegistryLeaseContendedError as u };