@dsh-electron/dsh-plugin-multi-root-workspace 0.1.12 → 0.1.14

package/lib/{registry-YTUOjmVu.js → registry-DR_sMuvS.js}

@@ -2,7 +2,7 @@ import { a as runPrimaryOperation, n as freezeOperationScope, o as runRegistryOp
 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-4zdwV7u4.js";
+import { a as snapshotSchema, i as parseArguments, r as AuthorityServer, s as storeIdentity, t as AuthorityClient } from "./protocol-CnR1KTXy.js";
 import { createRequire } from "node:module";
 import { closeSync, fstatSync, mkdirSync, openSync, statSync } from "node:fs";
 import { randomUUID } from "node:crypto";
@@ -94,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.
@@ -164,7 +265,7 @@ var RegistryAuthorityLease = class RegistryAuthorityLease {
 			mode: 448
 		});
 		if (process.platform === "win32") {
-			const { acquireLockHandleWin32 } = await import("./registry-lease-win32-DVTq9d4D.js");
+			const { acquireLockHandleWin32 } = await import("./registry-lease-win32-DDO-c7ig.js");
 			let handle;
 			try {
 				handle = await acquireLockHandleWin32(leasePath);
@@ -216,7 +317,7 @@ var RegistryAuthorityLease = class RegistryAuthorityLease {
 		if (this.released) return;
 		this.released = true;
 		if (this.held.kind === "win32") {
-			const { releaseLockHandleWin32 } = await import("./registry-lease-win32-DVTq9d4D.js");
+			const { releaseLockHandleWin32 } = await import("./registry-lease-win32-DDO-c7ig.js");
 			await releaseLockHandleWin32(this.held.handle);
 			return;
 		}
@@ -291,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:
@@ -343,8 +446,18 @@ var MultiRootRegistry = class extends Service {
 	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" };
@@ -352,6 +465,8 @@ var MultiRootRegistry = class extends Service {
 	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. */
@@ -385,6 +500,19 @@ var MultiRootRegistry = class extends Service {
 		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;
@@ -411,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();
@@ -447,6 +576,52 @@ var MultiRootRegistry = class extends Service {
 	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.
@@ -815,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;
 	}
 	/**
@@ -848,7 +1032,7 @@ var MultiRootRegistry = class extends Service {
 		try {
 			return this.table?.get(key);
 		} catch (error) {
-			if (unknownStorageState(error)) this.enterStorageFailed("registry storage state cannot be confirmed; restart and reconcile");
+			if (unknownStorageState(error)) this.enterStorageFailed("registry storage state cannot be confirmed; restart and reconcile", "quarantine");
 			throw error;
 		}
 	}
@@ -879,7 +1063,7 @@ var MultiRootRegistry = class extends Service {
 			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");
+			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));
@@ -938,18 +1122,17 @@ var MultiRootRegistry = class extends Service {
 		if ((this.published.get(key) ?? "") === signature) {
 			if (previousMetadata !== metadata && (previousMetadata !== void 0 || statuses.length > 0)) {
 				this.operationRevision++;
-				this.notifyShared(key);
-				for (const listener of this.listeners) listener(key);
+				this.deliverNotifications(key);
 			}
 			return;
 		}
-		this.published.set(key, signature);
+		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.notifyShared(key);
-		for (const listener of this.listeners) listener(key);
+		this.deliverNotifications(key);
 	}
 	projectRoots(statuses) {
 		return statuses.flatMap((status) => {
@@ -987,6 +1170,41 @@ var MultiRootRegistry = class extends Service {
 	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;
@@ -996,24 +1214,63 @@ var MultiRootRegistry = class extends Service {
 			...row,
 			id: additionalRootId(row.id)
 		}).filter(([, value]) => value !== void 0)));
-		this.cache.set(snapshot.primary, rows);
-		this.publish(snapshot.primary, rows);
-		this.ctx.multiRootScope.setRegistryAuthority(snapshot.available);
+		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() {
-		this.connectionGeneration++;
-		this.client = void 0;
-		this.remoteRevisions.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.ctx.multiRootScope.setAdditionalRoots(primary, this.projectRoots(rows).map((root) => ({
+		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
-		})));
-		this.published.clear();
+		}));
+		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;
@@ -1101,76 +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" || this.client !== void 0) return;
-			if (this.authorityState.kind === "config-invalid") return;
-			if (this.lease !== void 0) {
-				if (this.domain !== void 0) return;
-				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;
-			}
-			if (this.sharedStorageRoot !== void 0 && this.medium === void 0) try {
-				if (!isAbsolute(this.sharedStorageRoot)) throw new Error("sharedStorageRoot must be absolute");
-				this.medium = storeIdentity(this.sharedStorageRoot);
-				if (storeIdentity(dirname(leasePath)).id !== this.medium.id || basename(leasePath) !== `multi_root_workspace.lock`) throw new Error("shared registry requires its canonical medium lock, without alternate lock names");
-			} catch (error) {
-				this.enterStorageFailed(String(error));
-				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 [
-						0,
-						50,
-						150
-					]) {
-						if (delay) await new Promise((resolve) => setTimeout(resolve, delay));
-						if (this.disposed) return;
-						const generation = ++this.connectionGeneration;
-						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();
-							});
-							if (this.disposed || generation !== this.connectionGeneration) {
-								client.close();
-								return;
+	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;
+				}
+				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;
 							}
-							this.client = client;
-							adopted = true;
-							this.connectionFailure = void 0;
-							this.authorityState = {
-								kind: "follower",
-								epoch: client.epoch
-							};
-							break;
-						} catch (error) {
-							this.connectionFailure = String(error);
 						}
+						return;
 					}
+					this.enterStorageFailed(`${DOMAIN_NAME}: cannot acquire the registry lease: ${error instanceof Error ? error.message : String(error)}`, "retryable");
 					return;
 				}
-				this.enterStorageFailed(`${DOMAIN_NAME}: cannot acquire the registry lease: ${error instanceof Error ? error.message : String(error)}`);
-				return;
-			}
-			await this.openDomain();
-		});
+				await this.openDomain();
+			});
+		} finally {
+			this.recovery.arm();
+			this.noteRecoveryTransition();
+		}
 	}
 	/**
 	* Open the domain under an already-held lease and publish every stored root.
@@ -1183,43 +1457,69 @@ var MultiRootRegistry = class extends Service {
 			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.operationEpoch = randomUUID();
-		this.operationRevision = 0;
-		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) {
-				if (unknownStorageState(error)) {
-					this.enterStorageFailed("Skills migration result is unknown; restart and reconcile");
-					return;
+		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)}`);
 				}
-				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);
-		});
-		if (this.authorityState.kind !== "active") return;
+		} 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 {
-			this.server = await AuthorityServer.listen(this.medium.endpoint, this.medium.id, this.operationEpoch, this.maxRoots, (method, args) => this.dispatchShared(method, args));
+			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.domain = void 0;
-			this.enterStorageFailed(`cannot start shared registry: ${String(error)}`);
+			this.enterStorageFailed(`cannot start shared registry: ${String(error)}`, "retryable");
 			return;
 		}
-		this.ctx.multiRootScope.setRegistryAuthority(true);
+		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;
+		});
 	}
 	/** Fail closed: empty scope, no table, contended state. */
 	enterContended() {
@@ -1235,23 +1535,21 @@ var MultiRootRegistry = class extends Service {
 		}
 	}
 	/** Fail closed: empty scope, no table, storage-failed state. The lease, if held, stays. */
-	enterStorageFailed(reason) {
+	enterStorageFailed(reason, recovery) {
 		this.operationEpoch = void 0;
 		this.ctx.multiRootScope.setRegistryAuthority(false);
 		if (this.shared) {
-			for (const [key, rows] of this.cache) this.ctx.multiRootScope.setAdditionalRoots(key, this.projectRoots(rows).map((root) => ({
-				...root,
-				withheld: true
-			})));
-			this.published.clear();
+			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() {
@@ -1276,6 +1574,8 @@ 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 () => {