@awiki/dsh-plugin 0.3.3 → 0.3.4

package/lib/index.js

@@ -1,18 +1,16 @@
-import { n as downloadedAttachment } from "./sdk-adapter-CDLTgHJA.mjs";
+import { n as downloadedAttachment } from "./sdk-adapter-BeJakxLP.mjs";
 import "@deepseek-ai/cordis";
-import { existsSync } from "node:fs";
+import { createHash, randomUUID, timingSafeEqual } from "node:crypto";
 import { homedir } from "node:os";
-import { basename, dirname, isAbsolute, join, resolve } from "node:path";
+import { isAbsolute, join } from "node:path";
 import z from "@deepseek-ai/schemastery";
 import { Remote, TypertRemoteService } from "@deepseek-ai/dsh-typert-protocol";
 import { SettingsConflictError, settingsNamespace } from "@deepseek-ai/dsh-settings";
 import { defineTool } from "@deepseek-ai/dsh-tools";
 import { chmod, lstat, mkdir, readFile, readdir, rename, rm, unlink, utimes, writeFile } from "node:fs/promises";
-import { createHash, randomUUID } from "node:crypto";
 import { installModelSelection } from "@deepseek-ai/dsh-agent";
 import { createUserMessage } from "@deepseek-ai/dsh-llm";
 import { SessionId } from "@deepseek-ai/dsh-session";
-import { fileURLToPath } from "node:url";
 //#region lib/types/types.js
 /** Client-safe AWiki service and Remote data types. */
 /** Exact browser acknowledgement required before locally signing out. */
@@ -1450,12 +1448,13 @@ var AwikiConversationPreferenceStore = class {
 };
 //#endregion
 //#region lib/types/listener-state.js
-const STATE_VERSION = 1;
+const STATE_VERSION = 2;
 const MAX_STATE_BYTES = 1048576;
 const MAX_CONVERSATIONS = 1e3;
-function emptyState() {
+function emptyState(identityScopeHash) {
 	return {
 		version: STATE_VERSION,
+		identityScopeHash,
 		conversations: {}
 	};
 }
@@ -1467,8 +1466,10 @@ function boundedString(value, field) {
 	return value;
 }
 /** Validate and detach the complete state file before the listener trusts any route. */
-function parseState(value) {
-	if (!isRecord(value) || value.version !== STATE_VERSION || !isRecord(value.conversations)) throw new TypeError("awiki: listener state is invalid");
+function parseState(value, identityScopeHash) {
+	if (isRecord(value) && value.version === 1) return emptyState(identityScopeHash);
+	if (isRecord(value) && value.version === STATE_VERSION && typeof value.identityScopeHash === "string" && value.identityScopeHash !== identityScopeHash) return emptyState(identityScopeHash);
+	if (!isRecord(value) || value.version !== STATE_VERSION || value.identityScopeHash !== identityScopeHash || !isRecord(value.conversations)) throw new TypeError("awiki: listener state is invalid");
 	const entries = Object.entries(value.conversations);
 	if (entries.length > MAX_CONVERSATIONS) throw new TypeError("awiki: listener state is too large");
 	const conversations = {};
@@ -1491,6 +1492,7 @@ function parseState(value) {
 	}
 	return {
 		version: STATE_VERSION,
+		identityScopeHash,
 		conversations
 	};
 }
@@ -1501,28 +1503,31 @@ function isMissing(error) {
 var AwikiListenerStateStore = class {
 	hostDirectory;
 	statePath;
-	constructor(stateRoot) {
+	identityScopeHash;
+	constructor(stateRoot, identityScope) {
+		if (identityScope.length === 0 || identityScope.length > 2048) throw new TypeError("awiki: listener identity scope is invalid");
+		this.identityScopeHash = createHash("sha256").update(identityScope).digest("hex");
 		this.hostDirectory = join(stateRoot, ".host");
 		this.statePath = join(this.hostDirectory, "listener-state.json");
 	}
-	/** Load the current state or return an empty v1 document on first use. */
+	/** Load the current identity scope or reset unscoped v1 state on first use. */
 	async load() {
-		if (!await this.hasPrivateHostDirectory()) return emptyState();
+		if (!await this.hasPrivateHostDirectory()) return emptyState(this.identityScopeHash);
 		try {
 			const metadata = await lstat(this.statePath);
 			if (!metadata.isFile() || metadata.isSymbolicLink() || metadata.size > MAX_STATE_BYTES) throw new TypeError("awiki: listener state file is invalid");
 			const text = await readFile(this.statePath, "utf8");
 			if (Buffer.byteLength(text, "utf8") > MAX_STATE_BYTES) throw new TypeError("awiki: listener state file is invalid");
-			return parseState(JSON.parse(text));
+			return parseState(JSON.parse(text), this.identityScopeHash);
 		} catch (error) {
-			if (isMissing(error)) return emptyState();
+			if (isMissing(error)) return emptyState(this.identityScopeHash);
 			if (error instanceof SyntaxError) throw new TypeError("awiki: listener state file is invalid");
 			throw error;
 		}
 	}
 	/** Replace the state atomically without ever writing message or Agent text. */
 	async save(state) {
-		const snapshot = parseState(state);
+		const snapshot = parseState(state, this.identityScopeHash);
 		const text = `${JSON.stringify(snapshot)}\n`;
 		if (Buffer.byteLength(text, "utf8") > MAX_STATE_BYTES) throw new TypeError("awiki: listener state file is too large");
 		await mkdir(this.hostDirectory, {
@@ -1744,11 +1749,12 @@ function incomingFromPeer(message, conversation) {
 }
 function copyState(state) {
 	return {
-		version: 1,
+		version: 2,
+		identityScopeHash: state.identityScopeHash,
 		conversations: Object.fromEntries(Object.entries(state.conversations).map(([id, route]) => [id, { ...route }]))
 	};
 }
-/** Reconcile authorized Direct text from Core history whenever realtime schedules synchronization. */
+/** Consume authorized Direct text only after the identity supervisor commits synchronization. */
 var AwikiAgentListener = class {
 	awiki;
 	agents;
@@ -1757,34 +1763,23 @@ var AwikiAgentListener = class {
 	store;
 	logger;
 	stateReady;
-	state = {
-		version: 1,
-		conversations: {}
-	};
+	state;
 	stateMutation = Promise.resolve();
 	syncMutation = Promise.resolve();
 	scheduledMessageIds = /* @__PURE__ */ new Set();
 	conversationQueues = /* @__PURE__ */ new Map();
-	lifecycle;
-	started;
-	resolveStarted;
-	rejectStarted;
-	lifecycleGeneration = 0;
-	streamGeneration = 0;
-	activeRealtime;
 	stopped = false;
-	termination;
-	resolveTermination;
-	terminationSettled = false;
 	constructor(awiki, agents, config, logger, store) {
 		this.awiki = awiki;
 		this.agents = agents;
 		this.config = config;
-		this.termination = new Promise((resolve) => {
-			this.resolveTermination = resolve;
-		});
 		this.allowedPeers = new Set(config.allowedPeers.map((peer) => peer.startsWith("did:") ? peer : peer.toLowerCase()));
-		this.store = store ?? new AwikiListenerStateStore(config.stateRoot);
+		this.store = store ?? new AwikiListenerStateStore(config.stateRoot, config.identityScope);
+		this.state = {
+			version: 2,
+			identityScopeHash: this.store.identityScopeHash,
+			conversations: {}
+		};
 		this.logger = logger ?? {
 			debug() {},
 			info() {},
@@ -1796,38 +1791,11 @@ var AwikiAgentListener = class {
 			this.state = state;
 		});
 	}
-	/** Start canonical startup sync followed by the single Core-owned realtime stream. */
-	start() {
-		if (this.started !== void 0) return this.started;
-		this.started = new Promise((resolve, reject) => {
-			this.resolveStarted = resolve;
-			this.rejectStarted = reject;
-		});
-		const generation = ++this.lifecycleGeneration;
-		this.lifecycle = this.run(generation).then(() => {
-			this.finishTermination({ kind: "stopped" });
-		}, (error) => {
-			this.rejectStarted?.(error);
-			this.rejectStarted = void 0;
-			this.finishTermination({
-				kind: "failed",
-				error
-			});
-			if (!this.stopped) this.logger.warn("AWiki realtime listener stopped: %s", error instanceof Error ? error.message : "unknown failure");
-		});
-		return this.started;
-	}
-	/** Resolve once with either orderly shutdown or the exact terminal lifecycle failure. */
-	whenTerminated() {
-		return this.termination;
-	}
-	/** Deterministic canonical sync plus committed-history reconciliation for tests and recovery. */
-	async synchronizeOnce(reason) {
+	/** Reconcile only committed history; this consumer cannot start WSS or advance sync. */
+	async reconcileOnce() {
 		await this.enqueueSync(async () => {
 			await this.stateReady;
 			if (this.stopped) return;
-			await this.awiki.syncNow(reason);
-			if (this.stopped) return;
 			await this.reconcileCommittedHistory();
 		});
 	}
@@ -1837,84 +1805,12 @@ var AwikiAgentListener = class {
 		while (this.conversationQueues.size > 0) await Promise.allSettled([...this.conversationQueues.values()]);
 		await this.stateMutation;
 	}
-	/** Stop realtime first, fence late events, drain messages, then release listener-owned Agents. */
+	/** Fence late work, drain committed messages, then release listener-owned Agents. */
 	async dispose() {
 		if (this.stopped) return;
 		this.stopped = true;
-		this.lifecycleGeneration += 1;
-		this.streamGeneration += 1;
-		const active = this.activeRealtime;
-		this.activeRealtime = void 0;
-		await active?.session.stop().catch(() => void 0);
-		await this.lifecycle;
-		this.resolveStarted?.();
-		this.resolveStarted = void 0;
-		this.rejectStarted = void 0;
 		await this.whenIdle();
 		await this.agents.dispose();
-		this.finishTermination({ kind: "stopped" });
-	}
-	finishTermination(result) {
-		if (this.terminationSettled) return;
-		this.terminationSettled = true;
-		this.resolveTermination(result);
-	}
-	currentLifecycle(generation) {
-		return !this.stopped && this.lifecycleGeneration === generation;
-	}
-	async run(lifecycleGeneration) {
-		await this.synchronize("session_start", lifecycleGeneration);
-		if (!this.currentLifecycle(lifecycleGeneration)) return;
-		let active = await this.openRealtime(lifecycleGeneration);
-		if (active === void 0) return;
-		this.resolveStarted?.();
-		this.resolveStarted = void 0;
-		this.rejectStarted = void 0;
-		try {
-			while (this.currentLifecycle(lifecycleGeneration)) {
-				const event = await active.session.nextEvent();
-				if (!this.currentLifecycle(lifecycleGeneration) || this.activeRealtime?.generation !== active.generation) return;
-				if (event === null) {
-					this.activeRealtime = void 0;
-					this.streamGeneration += 1;
-					await active.session.stop();
-					if (!this.currentLifecycle(lifecycleGeneration)) return;
-					await this.synchronize("websocket_reconnect", lifecycleGeneration);
-					if (!this.currentLifecycle(lifecycleGeneration)) return;
-					const replacement = await this.openRealtime(lifecycleGeneration);
-					if (replacement === void 0) return;
-					active = replacement;
-					continue;
-				}
-				if (event.kind !== "sync_required") continue;
-				await this.synchronize(event.cause === "reconnected" ? "websocket_reconnect" : "websocket_hint", lifecycleGeneration);
-			}
-		} finally {
-			if (this.activeRealtime?.generation === active.generation) this.activeRealtime = void 0;
-			await active.session.stop().catch(() => void 0);
-		}
-	}
-	async openRealtime(lifecycleGeneration) {
-		const session = await this.awiki.startRealtime();
-		if (!this.currentLifecycle(lifecycleGeneration)) {
-			await session.stop().catch(() => void 0);
-			return;
-		}
-		const active = {
-			generation: ++this.streamGeneration,
-			session
-		};
-		this.activeRealtime = active;
-		return active;
-	}
-	async synchronize(reason, lifecycleGeneration) {
-		await this.enqueueSync(async () => {
-			await this.stateReady;
-			if (!this.currentLifecycle(lifecycleGeneration)) return;
-			await this.awiki.syncNow(reason);
-			if (!this.currentLifecycle(lifecycleGeneration)) return;
-			await this.reconcileCommittedHistory();
-		});
 	}
 	enqueueSync(operation) {
 		const pending = this.syncMutation.then(operation, operation);
@@ -2081,7 +1977,8 @@ var AwikiAgentListener = class {
 				...update.lastProcessedMessageId === void 0 ? current?.lastProcessedMessageId === void 0 ? {} : { lastProcessedMessageId: current.lastProcessedMessageId } : { lastProcessedMessageId: update.lastProcessedMessageId }
 			};
 			this.state = {
-				version: 1,
+				version: 2,
+				identityScopeHash: this.state.identityScopeHash,
 				conversations: {
 					...this.state.conversations,
 					[conversation.id]: route
@@ -2094,39 +1991,153 @@ var AwikiAgentListener = class {
 	}
 };
 //#endregion
-//#region lib/types/profile-state.js
-/** Match the profile-name boundary enforced by the DSH launcher. */
-function assertProfileName(value, source) {
-	if (typeof value !== "string" || value.length === 0 || value.includes("/") || value.includes("\\") || value === "." || value === ".." || value === "node_modules") throw new TypeError(`awiki: ${source} supplied an invalid profile name`);
-	return value;
+//#region lib/types/realtime-supervisor.js
+const RETRY_BASE_DELAY_MS = 1e3;
+const RETRY_MAX_DELAY_MS = 3e4;
+function syncReason(cause) {
+	if (cause === "session_start") return "session_start";
+	return cause === "reconnected" ? "websocket_reconnect" : "websocket_hint";
 }
-/**
-* Resolve the active DSH profile without guessing it from argv or process type.
-* Desktop's generation-scoped service is authoritative. Ordinary DSH has no
-* corresponding service, so its Loader root is accepted only when it is the
-* exact `$DSH_HOME/profiles/<name>` directory.
-*/
-function resolveAwikiProfileName(ctx, dshHome) {
-	const desktopProfiles = ctx.get("desktopProfiles");
-	if (desktopProfiles !== void 0) return assertProfileName(desktopProfiles.current?.name, "desktopProfiles.current");
-	let profileDir;
-	try {
-		if (ctx.baseUrl === void 0) return void 0;
-		const baseUrl = new URL(ctx.baseUrl);
-		if (baseUrl.protocol !== "file:") return void 0;
-		profileDir = resolve(fileURLToPath(baseUrl));
-	} catch {
-		return;
+/** Own the deployment identity's only WSS without knowing Workspace or Agent policy. */
+var IdentityRealtimeSupervisor = class {
+	realtime;
+	config;
+	logger;
+	lifecycle;
+	generation = 0;
+	activeSession;
+	stoppedSessions = /* @__PURE__ */ new WeakSet();
+	stopped = false;
+	connected = false;
+	startCount = 0;
+	stopCount = 0;
+	lastCommittedSyncCause;
+	retryTimer;
+	resolveRetry;
+	constructor(realtime, config = {}, logger = {
+		debug() {},
+		info() {},
+		warn() {},
+		error() {},
+		name: "awiki-realtime"
+	}) {
+		this.realtime = realtime;
+		this.config = config;
+		this.logger = logger;
 	}
-	const profilesDir = resolve(dshHome, "profiles");
-	if (dirname(profileDir) !== profilesDir) return void 0;
-	return assertProfileName(basename(profileDir), "Loader profile directory");
-}
-/** Resolve the profile-local default while preserving the legacy fallback. */
-function resolveAwikiStateRoot(ctx, dshHome) {
-	const profileName = resolveAwikiProfileName(ctx, dshHome);
-	return profileName === void 0 ? join(dshHome, "awiki", "im-core") : join(dshHome, "awiki", profileName, "im-core");
-}
+	/** Start in the background; identity activation must never await connectivity. */
+	start() {
+		if (this.lifecycle !== void 0 || this.stopped) return;
+		const generation = ++this.generation;
+		this.lifecycle = this.run(generation).catch((error) => {
+			if (!this.stopped) this.logger.warn("AWiki realtime supervisor stopped unexpectedly: %s", error instanceof Error ? error.message : "unknown failure");
+		});
+	}
+	diagnostics() {
+		return {
+			connected: this.connected,
+			activeSessionCount: this.activeSession === void 0 ? 0 : 1,
+			startCount: this.startCount,
+			stopCount: this.stopCount,
+			...this.lastCommittedSyncCause === void 0 ? {} : { lastCommittedSyncCause: this.lastCommittedSyncCause }
+		};
+	}
+	/** Fence late events, wake retry sleep, stop the exact session, and join the lifecycle. */
+	async dispose() {
+		if (this.stopped) return;
+		this.stopped = true;
+		this.generation += 1;
+		this.connected = false;
+		this.wakeRetry();
+		const session = this.activeSession;
+		if (session !== void 0) await this.stopSession(session).catch(() => void 0);
+		await this.lifecycle;
+	}
+	current(generation) {
+		return !this.stopped && this.generation === generation;
+	}
+	async run(generation) {
+		let cause = "session_start";
+		let failures = 0;
+		while (this.current(generation)) {
+			let session;
+			try {
+				await this.synchronize(cause, generation);
+				if (!this.current(generation)) return;
+				session = await this.realtime.startRealtime();
+				if (!this.current(generation)) {
+					await this.stopSession(session).catch(() => void 0);
+					return;
+				}
+				this.activeSession = session;
+				this.startCount += 1;
+				this.connected = (await session.getStatus().catch(() => ({ connected: false }))).connected;
+				failures = 0;
+				while (this.current(generation) && this.activeSession === session) {
+					const event = await session.nextEvent();
+					if (!this.current(generation) || this.activeSession !== session) return;
+					if (event === null) {
+						await this.stopSession(session);
+						cause = "reconnected";
+						break;
+					}
+					this.observeConnection(event);
+					if (event.kind !== "sync_required") continue;
+					await this.synchronize(event.cause, generation);
+				}
+			} catch (error) {
+				this.connected = false;
+				if (session !== void 0) await this.stopSession(session).catch(() => void 0);
+				if (!this.current(generation)) return;
+				failures += 1;
+				this.logger.warn("AWiki realtime lifecycle failed; retrying: %s", error instanceof Error ? error.message : "unknown failure");
+				await this.waitForRetry(failures, generation);
+				cause = cause === "session_start" ? "session_start" : "reconnected";
+			}
+		}
+	}
+	async synchronize(cause, generation) {
+		await this.realtime.syncNow(syncReason(cause));
+		if (!this.current(generation)) return;
+		this.lastCommittedSyncCause = cause;
+		try {
+			await this.config.onSynchronized?.(cause);
+		} catch (error) {
+			this.logger.warn("AWiki realtime post-sync consumer failed: %s", error instanceof Error ? error.message : "unknown failure");
+		}
+	}
+	observeConnection(event) {
+		if (event.kind !== "connection_state_changed") return;
+		this.connected = event.state === "connected";
+	}
+	async stopSession(session) {
+		if (this.stoppedSessions.has(session)) return;
+		this.stoppedSessions.add(session);
+		if (this.activeSession === session) this.activeSession = void 0;
+		this.connected = false;
+		this.stopCount += 1;
+		await session.stop();
+	}
+	waitForRetry(failures, generation) {
+		if (!this.current(generation)) return Promise.resolve();
+		const delay = Math.min(RETRY_BASE_DELAY_MS * 2 ** Math.min(failures - 1, 10), RETRY_MAX_DELAY_MS);
+		return new Promise((resolve) => {
+			const finish = () => {
+				if (this.retryTimer === timer) this.retryTimer = void 0;
+				if (this.resolveRetry === finish) this.resolveRetry = void 0;
+				resolve();
+			};
+			const timer = setTimeout(finish, delay);
+			this.retryTimer = timer;
+			this.resolveRetry = finish;
+		});
+	}
+	wakeRetry() {
+		const timer = this.retryTimer;
+		if (timer !== void 0) clearTimeout(timer);
+		this.resolveRetry?.();
+	}
+};
 //#endregion
 //#region lib/types/index.js
 /** Unified AWiki identity, messaging, attachment, Remote, and model-tool service. */
@@ -2198,6 +2209,7 @@ const Config = z.object({
 	attachmentMaxBytes: z.number().default(DEFAULT_ATTACHMENT_MAX_BYTES),
 	imageAttachmentCacheMaxBytes: z.number().default(DEFAULT_IMAGE_ATTACHMENT_CACHE_MAX_BYTES),
 	pollIntervalMs: z.number().default(DEFAULT_POLL_INTERVAL_MS),
+	realtimeEnabled: z.boolean().default(true),
 	listenerEnabled: z.boolean().default(false),
 	listenerAllowedPeers: z.array(z.string()).default([]),
 	listenerWorkspacePath: z.string(),
@@ -2215,7 +2227,6 @@ const FAILURE_CODES = /* @__PURE__ */ new Set([
 	"forbidden",
 	"identity-recovery-required",
 	"conflict",
-	"state-in-use",
 	"rate-limited",
 	"group-membership-required",
 	"group-identity-stale",
@@ -2229,10 +2240,17 @@ const FAILURE_CODES = /* @__PURE__ */ new Set([
 	"network",
 	"remote"
 ]);
-const LISTENER_RESTART_BASE_DELAY_MS = 1e3;
-const LISTENER_RESTART_MAX_DELAY_MS = 3e4;
-const LISTENER_RESTART_MAX_ATTEMPT = 6;
-const LISTENER_STABLE_RESET_MS = 6e4;
+const DEVICE_JOIN_APPROVAL_CONFIRMATION = "APPROVE";
+const DEVICE_REVOKE_CONFIRMATION = "REVOKE";
+const DEVICE_JOIN_CHALLENGE_TTL_SECONDS = 240;
+const RESUMABLE_JOIN_PHASES = /* @__PURE__ */ new Set([
+	"pending",
+	"challenge_prepared",
+	"response_prepared",
+	"response_verified",
+	"approval_prepared",
+	"authorized"
+]);
 const FAILURE_MESSAGES = {
 	"not-registered": "No AWiki identity is registered for this deployment.",
 	"signed-out": "This installation is signed out of AWiki.",
@@ -2245,7 +2263,6 @@ const FAILURE_MESSAGES = {
 	"forbidden": "The AWiki operation is not permitted.",
 	"identity-recovery-required": "The local AWiki identity must be recovered before it can be used again.",
 	"conflict": "The AWiki operation conflicts with current state.",
-	"state-in-use": "AWiki data is already open in another client.",
 	"rate-limited": "The AWiki service rate-limited the request.",
 	"group-membership-required": "The active AWiki identity is not a member of this group.",
 	"group-identity-stale": "The AWiki group identity binding is still recovering.",
@@ -2261,6 +2278,39 @@ const FAILURE_MESSAGES = {
 };
 var ProviderUnavailableError = class extends Error {};
 var SummaryProviderUnavailableError = class extends Error {};
+function candidateJoinPhase(value) {
+	if (value.remoteState === "rejected") return "rejected";
+	if (value.remoteState === "cancelled" || value.localPhase === "cancelled") return "cancelled";
+	if (value.remoteState === "expired" || value.localPhase === "expired") return "expired";
+	if (value.localPhase === "authorized" && value.remoteState === "consumed" && value.completed && value.identity !== void 0) return "authorized";
+	if (value.sas !== void 0) return value.remoteState === "response_verified" && /^\d{6}$/u.test(value.sas) ? "sas-ready" : void 0;
+	if (value.remoteState === "challenge_sent" || value.remoteState === "response_verified" || value.remoteState === "consumed" || value.localPhase !== "pending") return "verifying";
+	return value.remoteState === "pending" ? "pending" : void 0;
+}
+function adminJoinPhase(value) {
+	if (value.remoteState === "rejected") return "rejected";
+	if (value.remoteState === "cancelled" || value.localPhase === "cancelled") return "cancelled";
+	if (value.remoteState === "expired" || value.localPhase === "expired") return "expired";
+	if (value.localPhase === "authorized" && value.remoteState === "consumed") return "authorized";
+	if (value.sas !== void 0) return value.remoteState === "response_verified" && /^\d{6}$/u.test(value.sas) ? "sas-ready" : void 0;
+	if (value.remoteState === "challenge_sent" || value.remoteState === "response_verified" || value.remoteState === "consumed" || value.localPhase !== "pending") return "verifying";
+	return value.remoteState === "pending" ? "pending" : void 0;
+}
+function requestJoinPhase(value) {
+	switch (value.state) {
+		case "pending": return "pending";
+		case "challenge_sent":
+		case "response_verified": return "verifying";
+		case "consumed": return "authorized";
+		case "cancelled": return "cancelled";
+		case "rejected": return "rejected";
+		case "expired": return "expired";
+	}
+}
+function constantTimeSasMatches(expected, actual) {
+	if (!/^\d{6}$/u.test(expected) || !/^\d{6}$/u.test(actual)) return false;
+	return timingSafeEqual(Buffer.from(expected, "ascii"), Buffer.from(actual, "ascii"));
+}
 /** Validate and preserve one SDK service URL without accepting insecure remote HTTP. */
 function serviceUrl(field, raw, allowInsecureLoopbackForTesting) {
 	let url;
@@ -2331,14 +2381,12 @@ function listenerAllowedPeers(raw, enabled) {
 	return peers;
 }
 /** Resolve and validate every deployment choice before publishing the service. */
-function resolveConfig(ctx, config) {
+function resolveConfig(config) {
 	const allowInsecureLoopbackForTesting = config.allowInsecureLoopbackForTesting ?? false;
 	const configuredStateRoot = config.stateRoot?.trim();
 	const configuredDshHome = process.env.DSH_HOME?.trim();
 	const dshHome = configuredDshHome === void 0 || configuredDshHome.length === 0 ? join(homedir(), ".dsh") : configuredDshHome;
-	const profileName = configuredStateRoot === void 0 || configuredStateRoot.length === 0 ? resolveAwikiProfileName(ctx, dshHome) : void 0;
-	const stateRoot = configuredStateRoot === void 0 || configuredStateRoot.length === 0 ? resolveAwikiStateRoot(ctx, dshHome) : configuredStateRoot;
-	const legacySharedStateDetected = profileName !== void 0 && existsSync(join(dshHome, "awiki", "im-core"));
+	const stateRoot = configuredStateRoot === void 0 || configuredStateRoot.length === 0 ? join(dshHome, "awiki", "im-core") : configuredStateRoot;
 	if (!isAbsolute(stateRoot)) throw new TypeError("awiki: stateRoot must be an absolute path");
 	const attachmentMaxBytes = config.attachmentMaxBytes ?? 10485760;
 	if (!Number.isSafeInteger(attachmentMaxBytes) || attachmentMaxBytes < 1) throw new TypeError("awiki: attachmentMaxBytes must be a positive safe integer");
@@ -2347,6 +2395,8 @@ function resolveConfig(ctx, config) {
 	const pollIntervalMs = config.pollIntervalMs ?? 3e3;
 	if (!Number.isSafeInteger(pollIntervalMs) || pollIntervalMs < 1e3 || pollIntervalMs > 6e4) throw new TypeError("awiki: pollIntervalMs must be a safe integer from 1000 through 60000");
 	const listenerEnabled = config.listenerEnabled ?? false;
+	const realtimeEnabled = config.realtimeEnabled ?? true;
+	if (listenerEnabled && !realtimeEnabled) throw new TypeError("awiki: listenerEnabled requires realtimeEnabled");
 	const listenerWorkspacePath = config.listenerWorkspacePath?.trim() || join(dshHome, "workspaces", "awiki");
 	if (!isAbsolute(listenerWorkspacePath)) throw new TypeError("awiki: listenerWorkspacePath must be an absolute path");
 	const allowedPeers = listenerAllowedPeers(config.listenerAllowedPeers, listenerEnabled);
@@ -2369,10 +2419,7 @@ function resolveConfig(ctx, config) {
 		attachmentMaxBytes,
 		imageAttachmentCacheMaxBytes,
 		pollIntervalMs,
-		...profileName === void 0 ? {} : {
-			profileName,
-			legacySharedStateDetected
-		},
+		realtimeEnabled,
 		listenerEnabled,
 		listener: {
 			allowedPeers,
@@ -2523,6 +2570,7 @@ function normalizeRecoveryPrepareRequest(request) {
 	};
 }
 const IDENTITY_ACCESS_RESPONSE_MAX_BYTES = 65536;
+const SERVER_INFO_RESPONSE_MAX_BYTES = 65536;
 const RECOVERY_RECONCILIATION_RESPONSE_MAX_BYTES = 4096;
 /** Read one untrusted discovery response without buffering beyond the fixed Host limit. */
 async function readBoundedResponseText(response, maxBytes) {
@@ -2741,6 +2789,14 @@ let AwikiService = (() => {
 	let _inspectIdentityAccess_decorators;
 	let _sendRegistrationOtp_decorators;
 	let _registerIdentity_decorators;
+	let _beginDeviceJoin_decorators;
+	let _getDeviceJoinStatus_decorators;
+	let _cancelDeviceJoin_decorators;
+	let _refreshDeviceManagement_decorators;
+	let _startDeviceJoinVerification_decorators;
+	let _approveDeviceJoin_decorators;
+	let _rejectDeviceJoin_decorators;
+	let _revokeDevice_decorators;
 	let _updateDisplayName_decorators;
 	let _getProfile_decorators;
 	let _updateProfile_decorators;
@@ -2786,6 +2842,14 @@ let AwikiService = (() => {
 			_inspectIdentityAccess_decorators = [Remote];
 			_sendRegistrationOtp_decorators = [Remote];
 			_registerIdentity_decorators = [Remote];
+			_beginDeviceJoin_decorators = [Remote];
+			_getDeviceJoinStatus_decorators = [Remote];
+			_cancelDeviceJoin_decorators = [Remote];
+			_refreshDeviceManagement_decorators = [Remote];
+			_startDeviceJoinVerification_decorators = [Remote];
+			_approveDeviceJoin_decorators = [Remote];
+			_rejectDeviceJoin_decorators = [Remote];
+			_revokeDevice_decorators = [Remote];
 			_updateDisplayName_decorators = [Remote];
 			_getProfile_decorators = [Remote];
 			_updateProfile_decorators = [Remote];
@@ -2908,6 +2972,94 @@ let AwikiService = (() => {
 				},
 				metadata: _metadata
 			}, null, _instanceExtraInitializers);
+			__esDecorate(this, null, _beginDeviceJoin_decorators, {
+				kind: "method",
+				name: "beginDeviceJoin",
+				static: false,
+				private: false,
+				access: {
+					has: (obj) => "beginDeviceJoin" in obj,
+					get: (obj) => obj.beginDeviceJoin
+				},
+				metadata: _metadata
+			}, null, _instanceExtraInitializers);
+			__esDecorate(this, null, _getDeviceJoinStatus_decorators, {
+				kind: "method",
+				name: "getDeviceJoinStatus",
+				static: false,
+				private: false,
+				access: {
+					has: (obj) => "getDeviceJoinStatus" in obj,
+					get: (obj) => obj.getDeviceJoinStatus
+				},
+				metadata: _metadata
+			}, null, _instanceExtraInitializers);
+			__esDecorate(this, null, _cancelDeviceJoin_decorators, {
+				kind: "method",
+				name: "cancelDeviceJoin",
+				static: false,
+				private: false,
+				access: {
+					has: (obj) => "cancelDeviceJoin" in obj,
+					get: (obj) => obj.cancelDeviceJoin
+				},
+				metadata: _metadata
+			}, null, _instanceExtraInitializers);
+			__esDecorate(this, null, _refreshDeviceManagement_decorators, {
+				kind: "method",
+				name: "refreshDeviceManagement",
+				static: false,
+				private: false,
+				access: {
+					has: (obj) => "refreshDeviceManagement" in obj,
+					get: (obj) => obj.refreshDeviceManagement
+				},
+				metadata: _metadata
+			}, null, _instanceExtraInitializers);
+			__esDecorate(this, null, _startDeviceJoinVerification_decorators, {
+				kind: "method",
+				name: "startDeviceJoinVerification",
+				static: false,
+				private: false,
+				access: {
+					has: (obj) => "startDeviceJoinVerification" in obj,
+					get: (obj) => obj.startDeviceJoinVerification
+				},
+				metadata: _metadata
+			}, null, _instanceExtraInitializers);
+			__esDecorate(this, null, _approveDeviceJoin_decorators, {
+				kind: "method",
+				name: "approveDeviceJoin",
+				static: false,
+				private: false,
+				access: {
+					has: (obj) => "approveDeviceJoin" in obj,
+					get: (obj) => obj.approveDeviceJoin
+				},
+				metadata: _metadata
+			}, null, _instanceExtraInitializers);
+			__esDecorate(this, null, _rejectDeviceJoin_decorators, {
+				kind: "method",
+				name: "rejectDeviceJoin",
+				static: false,
+				private: false,
+				access: {
+					has: (obj) => "rejectDeviceJoin" in obj,
+					get: (obj) => obj.rejectDeviceJoin
+				},
+				metadata: _metadata
+			}, null, _instanceExtraInitializers);
+			__esDecorate(this, null, _revokeDevice_decorators, {
+				kind: "method",
+				name: "revokeDevice",
+				static: false,
+				private: false,
+				access: {
+					has: (obj) => "revokeDevice" in obj,
+					get: (obj) => obj.revokeDevice
+				},
+				metadata: _metadata
+			}, null, _instanceExtraInitializers);
 			__esDecorate(this, null, _updateDisplayName_decorators, {
 				kind: "method",
 				name: "updateDisplayName",
@@ -3303,6 +3455,12 @@ let AwikiService = (() => {
 		sessionMutation = Promise.resolve();
 		sessionRevision = 0;
 		activeIdentityDid;
+		pendingDeviceJoin;
+		activeDeviceJoinSessionId;
+		requestRefs = /* @__PURE__ */ new Map();
+		requestSessions = /* @__PURE__ */ new Map();
+		deviceRefs = /* @__PURE__ */ new Map();
+		deviceIds = /* @__PURE__ */ new Map();
 		activeSummaryRequests = /* @__PURE__ */ new Set();
 		summaryProvider;
 		recoveryReconciliationTarget;
@@ -3317,7 +3475,7 @@ let AwikiService = (() => {
 		constructor(ctx, config) {
 			super(ctx, "awiki");
 			this.hostContext = ctx;
-			this.resolved = resolveConfig(ctx, config);
+			this.resolved = resolveConfig(config);
 			this.externalHttpAuth = createAwikiExternalHttpAuth(() => this.acquireExternalHttpAuthSession());
 			this.sessionStore = new AwikiSessionStore(this.resolved.stateRoot);
 			this.imageAttachmentCache = new AwikiImageAttachmentCache(this.resolved.stateRoot, this.resolved.attachmentMaxBytes, this.resolved.imageAttachmentCacheMaxBytes);
@@ -3346,12 +3504,12 @@ let AwikiService = (() => {
 			ctx.inject(["workspaceRegistry"], (workspaceCtx) => {
 				this.workspaceContext = workspaceCtx;
 				const provider = this.provider;
-				if (provider !== void 0) this.startListener(provider);
+				if (provider !== void 0) this.ensureAgentConsumer(provider);
 				workspaceCtx.effect(() => async () => {
 					if (this.workspaceContext !== workspaceCtx) return;
 					this.workspaceContext = void 0;
 					const current = this.provider;
-					if (current !== void 0) await this.stopListener(current);
+					if (current !== void 0) await this.stopAgentConsumer(current);
 				}, "awiki: release Workspace listener composition");
 			});
 			registerAwikiTools(ctx, this);
@@ -3372,6 +3530,8 @@ let AwikiService = (() => {
 		*/
 		registerClientFactory(factory) {
 			if (this.provider !== void 0) throw new Error("awiki: a client provider is already registered");
+			this.pendingDeviceJoin = void 0;
+			this.activeDeviceJoinSessionId = void 0;
 			const provider = {
 				client: factory({
 					userServiceUrl: this.resolved.userServiceUrl,
@@ -3385,14 +3545,28 @@ let AwikiService = (() => {
 					allowInsecureLoopbackForTesting: this.resolved.allowInsecureLoopbackForTesting,
 					stateRoot: this.resolved.stateRoot
 				}),
-				listenerRestartAttempt: 0,
-				listenerGeneration: 0,
-				listenerRecoveryBlocked: false
+				realtimeGeneration: 0,
+				agentConsumerGeneration: 0,
+				localDeviceJoinRequestCountAfterSync: 0
 			};
 			this.provider = provider;
-			this.startListener(provider);
+			this.ensureRealtimeSupervisor(provider);
+			this.ensureAgentConsumer(provider);
 			return () => this.disposeProvider(provider);
 		}
+		/** Safe same-process diagnostics for focused E2E. Never exposed through Typert Remote. */
+		getRealtimeDiagnostics() {
+			const provider = this.provider;
+			return {
+				...provider?.realtimeSupervisor?.diagnostics() ?? {
+					connected: false,
+					activeSessionCount: 0,
+					startCount: 0,
+					stopCount: 0
+				},
+				localDeviceJoinRequestCountAfterSync: provider?.localDeviceJoinRequestCountAfterSync ?? 0
+			};
+		}
 		/** Register the optional Model Proxy recovery target without exposing an arbitrary callback or token. */
 		registerRecoveryReconciliationTarget(target) {
 			if (this.recoveryReconciliationTarget !== void 0) throw new Error("awiki: a recovery reconciliation target is already registered");
@@ -3420,18 +3594,42 @@ let AwikiService = (() => {
 		* Read settings needed by the browser presentation.
 		* @returns Browser-safe polling configuration without SDK endpoints or state paths.
 		*/
-		getConfig() {
-			return Promise.resolve({
+		async getConfig() {
+			let handleRecoveryPhoneEnabled = false;
+			const abort = new AbortController();
+			const timeout = setTimeout(() => {
+				abort.abort();
+			}, 1e4);
+			try {
+				const response = await fetch(new URL("/user-service/v1/server-info", this.resolved.userServiceUrl), {
+					method: "GET",
+					headers: {
+						accept: "application/json",
+						"cache-control": "no-store"
+					},
+					cache: "no-store",
+					redirect: "error",
+					signal: abort.signal
+				});
+				if (response.ok) {
+					const text = await readBoundedResponseText(response, SERVER_INFO_RESPONSE_MAX_BYTES);
+					const value = text === void 0 ? void 0 : JSON.parse(text);
+					if (typeof value === "object" && value !== null && value.schema_version === 1) {
+						const methods = value.identity?.handle_recovery?.methods;
+						handleRecoveryPhoneEnabled = Array.isArray(methods) && methods.some((method) => typeof method === "object" && method !== null && method.id === "phone" && method.enabled === true && method.verification?.required === true && method.verification?.type === "sms_otp");
+					}
+				}
+			} catch {} finally {
+				clearTimeout(timeout);
+			}
+			return {
 				ok: true,
 				value: {
 					pollIntervalMs: this.resolved.pollIntervalMs,
 					attachmentMaxBytes: this.resolved.attachmentMaxBytes,
-					...this.resolved.profileName === void 0 ? {} : {
-						profileName: this.resolved.profileName,
-						legacySharedStateDetected: this.resolved.legacySharedStateDetected
-					}
+					handleRecoveryPhoneEnabled
 				}
-			});
+			};
 		}
 		/**
 		* Read the deployment's identity status.
@@ -3454,6 +3652,8 @@ let AwikiService = (() => {
 			const identity = await this.run((client) => client.getIdentity(), { allowSignedOut: true });
 			if (!identity.ok) return identity;
 			this.activeIdentityDid = identity.value?.did;
+			const provider = this.provider;
+			if (identity.value !== null && provider !== void 0) this.ensureProviderRuntime(provider);
 			return identity.value === null ? {
 				ok: true,
 				value: { status: "unregistered" }
@@ -3490,7 +3690,7 @@ let AwikiService = (() => {
 					const session = { status: "signed-out" };
 					this.publishSession(session);
 					const provider = this.provider;
-					if (provider !== void 0) await this.stopListener(provider);
+					if (provider !== void 0) await this.stopProviderRuntime(provider);
 					return {
 						ok: true,
 						value: session
@@ -3523,7 +3723,7 @@ let AwikiService = (() => {
 					};
 					this.publishSession(session);
 					const provider = this.provider;
-					if (provider !== void 0) this.startListener(provider);
+					if (provider !== void 0) this.ensureProviderRuntime(provider);
 					return {
 						ok: true,
 						value: session
@@ -3609,8 +3809,15 @@ let AwikiService = (() => {
 				};
 			}
 		}
-		sendRegistrationOtp(request) {
-			return this.run((client) => client.sendRegistrationOtp(request));
+		async sendRegistrationOtp(request) {
+			this.pendingDeviceJoin = void 0;
+			return this.run(async (client) => {
+				if (await this.selectDeviceJoinSession(client) !== null) throw Object.assign(/* @__PURE__ */ new Error("join already exists"), {
+					name: "AwikiSdkError",
+					code: "conflict"
+				});
+				return client.sendRegistrationOtp(request);
+			});
 		}
 		/**
 		* Register and persist the deployment's only AWiki identity.
@@ -3618,9 +3825,190 @@ let AwikiService = (() => {
 		* @returns The new public identity or a closed failure.
 		*/
 		async registerIdentity(request) {
-			const result = await this.run((client) => client.registerIdentity(request));
-			if (result.ok) await this.activateRegisteredIdentity(result.value);
-			return result;
+			this.pendingDeviceJoin = void 0;
+			const result = await this.run(async (client) => {
+				if (await this.selectDeviceJoinSession(client) !== null) throw Object.assign(/* @__PURE__ */ new Error("join already exists"), {
+					name: "AwikiSdkError",
+					code: "conflict"
+				});
+				return client.registerIdentity(request);
+			});
+			if (!result.ok) return result;
+			if (result.value.status === "registered") {
+				await this.activateRegisteredIdentity(result.value.identity);
+				return {
+					ok: true,
+					value: {
+						status: "registered",
+						identity: result.value.identity
+					}
+				};
+			}
+			this.pendingDeviceJoin = {
+				continuationId: result.value.continuationId,
+				fullHandle: result.value.fullHandle,
+				mode: result.value.mode,
+				requiresUserPresence: result.value.requiresUserPresence
+			};
+			return {
+				ok: true,
+				value: {
+					status: "join-required",
+					fullHandle: result.value.fullHandle,
+					mode: result.value.mode,
+					requiresUserPresence: result.value.requiresUserPresence
+				}
+			};
+		}
+		/** Consume the exact in-memory continuation; ordinary Join never claims rebind user presence. */
+		async beginDeviceJoin() {
+			const continuation = this.pendingDeviceJoin;
+			if (continuation === void 0) return {
+				ok: false,
+				error: failure("conflict")
+			};
+			if (continuation.mode !== "ordinary" || continuation.requiresUserPresence) return {
+				ok: false,
+				error: failure("forbidden")
+			};
+			this.pendingDeviceJoin = void 0;
+			const result = await this.run((client) => client.beginDeviceJoin({
+				continuationId: continuation.continuationId,
+				operationId: `dsh-device-join-${randomUUID()}`,
+				userPresenceConfirmed: false
+			}));
+			if (!result.ok) return result;
+			this.activeDeviceJoinSessionId = result.value.joinSessionId;
+			return this.applyCandidateJoinProgress(result.value);
+		}
+		/** Restore from Core local_sessions and advance only the exact resumable Join. */
+		async getDeviceJoinStatus() {
+			const result = await this.run(async (client) => {
+				const joinSessionId = await this.selectDeviceJoinSession(client);
+				return joinSessionId === null ? null : client.getDeviceJoinStatus(joinSessionId);
+			});
+			if (!result.ok) return result;
+			if (result.value === null) return {
+				ok: true,
+				value: null
+			};
+			this.activeDeviceJoinSessionId = result.value.joinSessionId;
+			return this.applyCandidateJoinProgress(result.value);
+		}
+		async cancelDeviceJoin() {
+			const result = await this.run(async (client) => {
+				const joinSessionId = await this.selectDeviceJoinSession(client);
+				if (joinSessionId === null) return null;
+				return client.cancelDeviceJoin(joinSessionId);
+			});
+			if (!result.ok) return result;
+			this.pendingDeviceJoin = void 0;
+			this.activeDeviceJoinSessionId = void 0;
+			return {
+				ok: true,
+				value: { completed: true }
+			};
+		}
+		/** Reliable-sync and project only Host-opaque device/request references. */
+		refreshDeviceManagement() {
+			return this.run((client) => this.deviceManagementSnapshot(client));
+		}
+		async startDeviceJoinVerification(request) {
+			const joinSessionId = this.requestSessions.get(request?.requestRef);
+			if (joinSessionId === void 0) return {
+				ok: false,
+				error: failure("invalid-request")
+			};
+			const result = await this.run(async (client) => {
+				await this.requireDeviceManager(client);
+				await client.syncDeviceManagement();
+				let notice = (await client.listLocalDeviceJoinRequests()).find((value) => value.joinSessionId === joinSessionId);
+				if (notice === void 0) throw Object.assign(/* @__PURE__ */ new Error("request not found"), {
+					name: "AwikiSdkError",
+					code: "not-found"
+				});
+				const localProgress = await this.localAdminJoinProgress(client, notice);
+				if (localProgress !== void 0) return localProgress;
+				if (!notice.canStartVerification) throw Object.assign(/* @__PURE__ */ new Error("request unavailable"), {
+					name: "AwikiSdkError",
+					code: "forbidden"
+				});
+				const operationId = `dsh-device-verify-${createHash("sha256").update(joinSessionId).digest("hex").slice(0, 32)}`;
+				let started;
+				try {
+					started = await client.startDeviceJoinVerification({
+						joinSessionId,
+						operationId,
+						challengeTtlSeconds: DEVICE_JOIN_CHALLENGE_TTL_SECONDS
+					});
+				} catch (error) {
+					await client.syncDeviceManagement();
+					notice = (await client.listLocalDeviceJoinRequests()).find((value) => value.joinSessionId === joinSessionId);
+					const recovered = notice === void 0 ? void 0 : await this.localAdminJoinProgress(client, notice);
+					if (recovered !== void 0) return recovered;
+					throw error;
+				}
+				await client.syncDeviceManagement();
+				notice = (await client.listLocalDeviceJoinRequests()).find((value) => value.joinSessionId === joinSessionId);
+				if (notice === void 0) return started;
+				return await this.localAdminJoinProgress(client, notice) ?? started;
+			});
+			return result.ok ? this.publicAdminJoinProgress(request.requestRef, result.value) : result;
+		}
+		async approveDeviceJoin(request) {
+			if (request?.confirmation !== DEVICE_JOIN_APPROVAL_CONFIRMATION) return {
+				ok: false,
+				error: failure("invalid-request")
+			};
+			const joinSessionId = this.requestSessions.get(request.requestRef);
+			if (joinSessionId === void 0 || !/^\d{6}$/u.test(request.enteredSas)) return {
+				ok: false,
+				error: failure("invalid-request")
+			};
+			const result = await this.run(async (client) => {
+				await this.requireDeviceManager(client);
+				const progress = await client.getLocalDeviceJoinVerificationProgress(joinSessionId);
+				if (progress.sas === void 0 || !constantTimeSasMatches(progress.sas, request.enteredSas)) throw Object.assign(/* @__PURE__ */ new Error("sas mismatch"), {
+					name: "AwikiSdkError",
+					code: "forbidden"
+				});
+				const prompt = await client.prepareDeviceJoinApproval(joinSessionId);
+				return client.confirmDeviceJoinApproval(prompt.approvalHandle);
+			});
+			return result.ok ? this.publicAdminJoinProgress(request.requestRef, result.value) : result;
+		}
+		async rejectDeviceJoin(request) {
+			const joinSessionId = this.requestSessions.get(request?.requestRef);
+			if (joinSessionId === void 0 || request.reason !== "user_rejected" && request.reason !== "sas_mismatch") return {
+				ok: false,
+				error: failure("invalid-request")
+			};
+			const result = await this.run(async (client) => {
+				await this.requireDeviceManager(client);
+				return client.rejectDeviceJoin(joinSessionId, request.reason);
+			});
+			return result.ok ? this.publicAdminJoinProgress(request.requestRef, result.value) : result;
+		}
+		async revokeDevice(request) {
+			if (request?.confirmation !== DEVICE_REVOKE_CONFIRMATION) return {
+				ok: false,
+				error: failure("invalid-request")
+			};
+			const deviceId = this.deviceIds.get(request.deviceRef);
+			if (deviceId === void 0) return {
+				ok: false,
+				error: failure("invalid-request")
+			};
+			return this.run(async (client) => {
+				await this.requireDeviceManager(client);
+				const target = (await client.getDeviceRegistry()).find((device) => device.deviceId === deviceId);
+				if (target === void 0 || target.isCurrent) throw Object.assign(/* @__PURE__ */ new Error("device unavailable"), {
+					name: "AwikiSdkError",
+					code: "forbidden"
+				});
+				await client.revokeDevice(deviceId);
+				return this.deviceManagementSnapshot(client);
+			});
 		}
 		/**
 		* Update the deployment identity's public WNS display name.
@@ -3647,12 +4035,19 @@ let AwikiService = (() => {
 		}
 		/** Start durable phone recovery for one existing full Handle. */
 		sendRecoveryOtp(request) {
+			this.pendingDeviceJoin = void 0;
 			const normalized = normalizeRecoveryOtpRequest(request);
 			if (normalized === void 0) return Promise.resolve({
 				ok: false,
 				error: failure("invalid-request")
 			});
-			return this.run((client) => client.sendRecoveryOtp(normalized), { allowSignedOut: true });
+			return this.run(async (client) => {
+				if (await this.selectDeviceJoinSession(client) !== null) throw Object.assign(/* @__PURE__ */ new Error("join already exists"), {
+					name: "AwikiSdkError",
+					code: "conflict"
+				});
+				return client.sendRecoveryOtp(normalized);
+			}, { allowSignedOut: true });
 		}
 		/** Verify a recovery OTP and freeze its exact intent before the remote commit. */
 		prepareRecovery(request) {
@@ -4164,10 +4559,10 @@ let AwikiService = (() => {
 			});
 			return this.mutateSession(async () => {
 				const provider = this.provider;
-				if (provider !== void 0) await this.stopListener(provider);
+				if (provider !== void 0) await this.stopProviderRuntime(provider);
 				const result = await this.run((client) => client.clearLocalData(), { allowSignedOut: true });
 				if (!result.ok) {
-					if (provider !== void 0 && this.provider === provider) this.startListener(provider);
+					if (provider !== void 0 && this.provider === provider) this.ensureProviderRuntime(provider);
 					return result;
 				}
 				try {
@@ -4177,9 +4572,10 @@ let AwikiService = (() => {
 					await this.sessionStore.signIn();
 					this.signedOut = false;
 					this.activeIdentityDid = void 0;
+					this.pendingDeviceJoin = void 0;
+					this.activeDeviceJoinSessionId = void 0;
 					this.invalidateSummaries();
 					this.publishSession({ status: "unregistered" });
-					if (provider !== void 0 && this.provider === provider) this.startListener(provider);
 					return result;
 				} catch {
 					return {
@@ -4213,8 +4609,7 @@ let AwikiService = (() => {
 							identity
 						};
 						this.publishSession(session);
-						await provider.listenerStartup;
-						await this.startListener(provider);
+						this.ensureProviderRuntime(provider);
 					}
 					return reconciled;
 				} catch {
@@ -4250,22 +4645,159 @@ let AwikiService = (() => {
 				return false;
 			}
 		}
-		/** Publish one newly registered identity and start its listener through the existing session path. */
+		/** Select the only resumable new-device session; Core local_sessions is the sole restart SoT. */
+		async selectDeviceJoinSession(client) {
+			const sessions = await client.listLocalDeviceJoinSessions();
+			if (this.activeDeviceJoinSessionId !== void 0) {
+				const tracked = sessions.find((value) => value.side === "new_device" && value.joinSessionId === this.activeDeviceJoinSessionId);
+				if (tracked !== void 0) return tracked.joinSessionId;
+				this.activeDeviceJoinSessionId = void 0;
+			}
+			const resumable = sessions.filter((value) => value.side === "new_device" && RESUMABLE_JOIN_PHASES.has(value.localPhase));
+			if (resumable.length > 1) throw Object.assign(/* @__PURE__ */ new Error("multiple local joins"), {
+				name: "AwikiSdkError",
+				code: "conflict"
+			});
+			const selected = resumable[0];
+			this.activeDeviceJoinSessionId = selected?.joinSessionId;
+			return selected?.joinSessionId ?? null;
+		}
+		async applyCandidateJoinProgress(value) {
+			const phase = candidateJoinPhase(value);
+			if (phase === void 0) return {
+				ok: false,
+				error: failure("remote")
+			};
+			if (phase === "cancelled" || phase === "rejected" || phase === "expired") this.activeDeviceJoinSessionId = void 0;
+			if (phase === "authorized") {
+				if (value.identity === void 0) return {
+					ok: false,
+					error: failure("remote")
+				};
+				await this.activateRegisteredIdentity(value.identity);
+			}
+			return {
+				ok: true,
+				value: {
+					phase,
+					expiresAt: value.expiresAt,
+					...phase === "sas-ready" && value.sas !== void 0 ? { sas: value.sas } : {},
+					completed: phase === "authorized"
+				}
+			};
+		}
+		publicAdminJoinProgress(requestRef, value) {
+			const phase = adminJoinPhase(value);
+			if (phase === void 0) return {
+				ok: false,
+				error: failure("remote")
+			};
+			return {
+				ok: true,
+				value: {
+					requestRef,
+					phase,
+					expiresAt: value.expiresAt,
+					...phase === "sas-ready" && value.sas !== void 0 ? { sas: value.sas } : {}
+				}
+			};
+		}
+		async localAdminJoinProgress(client, notice) {
+			const local = (await client.listLocalDeviceJoinSessions()).find((session) => session.side === "admin" && session.joinSessionId === notice.joinSessionId);
+			if (local === void 0) return notice.claimedByCurrentDevice ? client.getLocalDeviceJoinVerificationProgress(notice.joinSessionId) : void 0;
+			if (local.localPhase === "challenge_prepared") return {
+				joinSessionId: notice.joinSessionId,
+				localPhase: local.localPhase,
+				remoteState: notice.state,
+				expiresAt: local.expiresAt
+			};
+			return client.getLocalDeviceJoinVerificationProgress(notice.joinSessionId);
+		}
+		async requireDeviceManager(client) {
+			const current = await client.getCurrentDeviceSummary();
+			if (!current.canManage || current.role !== "admin" || current.readiness !== "admin_ready") throw Object.assign(/* @__PURE__ */ new Error("device manager required"), {
+				name: "AwikiSdkError",
+				code: "forbidden"
+			});
+		}
+		requestRef(joinSessionId) {
+			const existing = this.requestRefs.get(joinSessionId);
+			if (existing !== void 0) return existing;
+			const reference = `join-${randomUUID()}`;
+			this.requestRefs.set(joinSessionId, reference);
+			this.requestSessions.set(reference, joinSessionId);
+			return reference;
+		}
+		deviceRef(deviceId) {
+			const existing = this.deviceRefs.get(deviceId);
+			if (existing !== void 0) return existing;
+			const reference = `device-${randomUUID()}`;
+			this.deviceRefs.set(deviceId, reference);
+			this.deviceIds.set(reference, deviceId);
+			return reference;
+		}
+		async deviceManagementSnapshot(client) {
+			await client.syncDeviceManagement();
+			const current = await client.getCurrentDeviceSummary();
+			if (!current.canManage || current.role !== "admin" || current.readiness !== "admin_ready") {
+				this.requestRefs.clear();
+				this.requestSessions.clear();
+				this.deviceRefs.clear();
+				this.deviceIds.clear();
+				return {
+					canManage: false,
+					...current.role === void 0 ? {} : { role: current.role },
+					readiness: current.readiness,
+					devices: [],
+					requests: []
+				};
+			}
+			const requests = await client.listLocalDeviceJoinRequests();
+			await Promise.all(requests.filter((request) => request.claimedByCurrentDevice).map((request) => client.getLocalDeviceJoinVerificationProgress(request.joinSessionId).catch(() => void 0)));
+			return {
+				canManage: true,
+				role: "admin",
+				readiness: "admin_ready",
+				devices: (await client.getDeviceRegistry()).map((device) => this.publicDevice(device)),
+				requests: requests.map((request) => ({
+					requestRef: this.requestRef(request.joinSessionId),
+					candidateKeyFingerprint: request.candidateKeyFingerprint,
+					issuedAt: request.issuedAt,
+					expiresAt: request.expiresAt,
+					state: requestJoinPhase(request),
+					claimedByCurrentDevice: request.claimedByCurrentDevice,
+					canStartVerification: request.canStartVerification
+				}))
+			};
+		}
+		publicDevice(device) {
+			return {
+				deviceRef: this.deviceRef(device.deviceId),
+				status: device.status,
+				role: device.role,
+				managementReady: device.managementReady,
+				isCurrent: device.isCurrent
+			};
+		}
+		/** Publish one newly registered identity, then start realtime only in the background. */
 		async activateRegisteredIdentity(identity) {
+			this.pendingDeviceJoin = void 0;
+			this.activeDeviceJoinSessionId = void 0;
 			this.activeIdentityDid = identity.did;
 			this.publishSession({
 				status: "active",
 				identity
 			});
 			const provider = this.provider;
-			if (provider !== void 0) {
-				await provider.listenerStartup;
-				await this.startListener(provider);
-			}
+			if (provider !== void 0) this.ensureProviderRuntime(provider);
 		}
 		/** Invalidate cached session work and cancel every model request still owned by the old session. */
 		invalidateSummaries() {
 			this.sessionRevision += 1;
+			this.requestRefs.clear();
+			this.requestSessions.clear();
+			this.deviceRefs.clear();
+			this.deviceIds.clear();
 			for (const controller of this.activeSummaryRequests) controller.abort();
 			this.activeSummaryRequests.clear();
 		}
@@ -4365,120 +4897,148 @@ let AwikiService = (() => {
 			this.sessionMutation = pending.then(() => void 0, () => void 0);
 			return pending;
 		}
-		/** Start one exact identity-bound listener, atomically releasing a failed startup. */
-		startListener(provider) {
-			if (!this.resolved.listenerEnabled || provider.listener !== void 0 || provider.listenerRecoveryBlocked || this.provider !== provider) return Promise.resolve();
-			if (provider.listenerStartup !== void 0) return provider.listenerStartup;
-			if (provider.listenerCleanup !== void 0 || provider.listenerRestartTimer !== void 0) return Promise.resolve();
-			const workspaceContext = this.workspaceContext;
-			const source = provider.client.listener;
-			if (workspaceContext === void 0 || source === void 0) return Promise.resolve();
-			const generation = provider.listenerGeneration;
-			const logger = this.ctx.logger("awiki-listener");
+		/** Start identity realtime and the optional Agent consumer without blocking identity success. */
+		ensureProviderRuntime(provider) {
+			const identityDid = this.activeIdentityDid;
+			if (provider.runtimeReplacement !== void 0) return;
+			if (identityDid !== void 0 && provider.realtimeIdentityDid !== void 0 && provider.realtimeIdentityDid !== identityDid) {
+				this.replaceProviderRuntime(provider, identityDid);
+				return;
+			}
+			this.ensureRealtimeSupervisor(provider);
+			this.ensureAgentConsumer(provider);
+		}
+		replaceProviderRuntime(provider, identityDid) {
+			if (provider.runtimeReplacement !== void 0 || this.provider !== provider) return;
+			const observed = (async () => {
+				await this.stopProviderRuntime(provider);
+				if (this.provider !== provider || this.activeIdentityDid !== identityDid) return;
+				this.ensureRealtimeSupervisor(provider);
+				this.ensureAgentConsumer(provider);
+			})().catch((error) => {
+				this.ctx.logger("awiki-realtime").warn("AWiki identity realtime replacement failed: %s", error instanceof Error ? error.message : "unknown failure");
+			}).finally(() => {
+				if (provider.runtimeReplacement === observed) delete provider.runtimeReplacement;
+				if (this.provider === provider) this.ensureProviderRuntime(provider);
+			});
+			provider.runtimeReplacement = observed;
+		}
+		ensureRealtimeSupervisor(provider) {
+			if (!this.resolved.realtimeEnabled || provider.realtimeSupervisor !== void 0 || provider.realtimeStartup !== void 0 || this.provider !== provider || (provider.client.realtime ?? provider.client.listener) === void 0) return;
+			const generation = provider.realtimeGeneration;
+			const source = provider.client.realtime ?? provider.client.listener;
+			if (source === void 0) return;
+			const logger = this.ctx.logger("awiki-realtime");
 			const observed = (async () => {
 				if (await this.isSignedOut()) return;
-				if (await provider.client.getIdentity() === null) return;
-				if (!this.listenerFenceMatches(provider, workspaceContext, generation)) return;
-				const agents = new DshAwikiListenerAgentRuntime(workspaceContext, this.resolved.listener.workspacePath);
-				const listener = new AwikiAgentListener(source, agents, this.resolved.listener, logger);
-				provider.listener = listener;
-				try {
-					await listener.start();
-				} catch (error) {
-					if (provider.listener === listener) delete provider.listener;
-					try {
-						await listener.dispose();
-					} catch {
-						provider.listenerRecoveryBlocked = true;
-					}
-					if (!provider.listenerRecoveryBlocked && provider.listenerRestartAttempt > 0) this.scheduleListenerRestart(provider, workspaceContext, generation);
-					throw error;
-				}
-				if (!this.listenerFenceMatches(provider, workspaceContext, generation)) {
-					if (provider.listener === listener) delete provider.listener;
-					try {
-						await listener.dispose();
-					} catch (error) {
-						provider.listenerRecoveryBlocked = true;
-						throw error;
-					}
-					return;
-				}
-				provider.listenerStartedAt = Date.now();
-				listener.whenTerminated().then((result) => {
-					if (result.kind === "failed") this.releaseFailedListener(provider, listener, workspaceContext, generation, result.error);
-				});
+				const identity = await provider.client.getIdentity();
+				if (identity === null || !this.realtimeFenceMatches(provider, generation)) return;
+				this.activeIdentityDid = identity.did;
+				const supervisor = new IdentityRealtimeSupervisor(source, { onSynchronized: (cause) => this.onRealtimeSynchronized(provider, generation, cause) }, logger);
+				provider.realtimeSupervisor = supervisor;
+				provider.realtimeIdentityDid = identity.did;
+				supervisor.start();
+				this.ensureAgentConsumer(provider);
 			})().catch((error) => {
-				logger.warn("AWiki listener startup failed: %s", error instanceof Error ? error.message : "unknown failure");
+				logger.warn("AWiki realtime startup failed: %s", error instanceof Error ? error.message : "unknown failure");
 			}).finally(() => {
-				if (provider.listenerStartup === observed) delete provider.listenerStartup;
+				if (provider.realtimeStartup === observed) delete provider.realtimeStartup;
 			});
-			provider.listenerStartup = observed;
-			return observed;
-		}
-		async stopListener(provider) {
-			provider.listenerGeneration += 1;
-			provider.listenerRestartAttempt = 0;
-			delete provider.listenerStartedAt;
-			const timer = provider.listenerRestartTimer;
-			if (timer !== void 0) {
-				delete provider.listenerRestartTimer;
-				clearTimeout(timer);
-			}
-			await provider.listenerStartup;
-			await provider.listenerCleanup;
-			const listener = provider.listener;
-			if (listener === void 0) return;
-			delete provider.listener;
-			try {
-				await listener.dispose();
-			} catch (error) {
-				provider.listenerRecoveryBlocked = true;
-				throw error;
-			}
+			provider.realtimeStartup = observed;
 		}
-		listenerFenceMatches(provider, workspaceContext, generation) {
-			return this.provider === provider && this.workspaceContext === workspaceContext && provider.listenerGeneration === generation;
+		realtimeFenceMatches(provider, generation) {
+			return this.provider === provider && provider.realtimeGeneration === generation;
 		}
-		releaseFailedListener(provider, listener, workspaceContext, generation, error) {
-			if (provider.listener !== listener) return;
-			delete provider.listener;
-			const startedAt = provider.listenerStartedAt;
-			delete provider.listenerStartedAt;
-			if (startedAt !== void 0 && Date.now() - startedAt >= LISTENER_STABLE_RESET_MS) provider.listenerRestartAttempt = 0;
+		async onRealtimeSynchronized(provider, generation, cause) {
+			if (!this.realtimeFenceMatches(provider, generation)) return;
+			if (cause === "system_notification" || cause === "stream_recovery") try {
+				provider.localDeviceJoinRequestCountAfterSync = (await provider.client.listLocalDeviceJoinRequests()).length;
+			} catch {
+				this.ctx.logger("awiki-realtime").debug("AWiki realtime could not observe local device Join requests");
+			}
+			if (![
+				"session_start",
+				"connection_ready",
+				"reconnected",
+				"message",
+				"message_update"
+			].includes(cause)) return;
+			this.ensureAgentConsumer(provider);
+			await provider.agentConsumerStartup;
+			if (!this.realtimeFenceMatches(provider, generation)) return;
+			await provider.agentConsumer?.reconcileOnce();
+		}
+		ensureAgentConsumer(provider) {
+			const workspaceContext = this.workspaceContext;
+			const source = provider.client.agentInbox ?? provider.client.listener;
+			const identityDid = this.activeIdentityDid;
+			if (!this.resolved.listenerEnabled || workspaceContext === void 0 || source === void 0 || identityDid === void 0 || this.provider !== provider) return;
+			if (provider.agentConsumer !== void 0 && provider.agentConsumerIdentityDid === identityDid) return;
+			if (provider.agentConsumerStartup !== void 0) return;
+			const generation = ++provider.agentConsumerGeneration;
 			const logger = this.ctx.logger("awiki-listener");
-			logger.warn("AWiki listener lifecycle failed: %s", error instanceof Error ? error.message : "unknown failure");
-			let disposed = false;
-			const observed = listener.dispose().then(() => {
-				disposed = true;
-			}, (cleanupError) => {
-				provider.listenerRecoveryBlocked = true;
-				logger.warn("AWiki listener cleanup failed: %s", cleanupError instanceof Error ? cleanupError.message : "unknown failure");
+			const observed = (async () => {
+				await this.detachAgentConsumer(provider);
+				if (!this.agentConsumerFenceMatches(provider, workspaceContext, identityDid, generation)) return;
+				const agents = new DshAwikiListenerAgentRuntime(workspaceContext, this.resolved.listener.workspacePath);
+				const consumer = new AwikiAgentListener(source, agents, {
+					...this.resolved.listener,
+					identityScope: identityDid
+				}, logger);
+				provider.agentConsumer = consumer;
+				provider.agentConsumerIdentityDid = identityDid;
+				await consumer.reconcileOnce();
+			})().catch((error) => {
+				logger.warn("AWiki Agent consumer startup failed: %s", error instanceof Error ? error.message : "unknown failure");
 			}).finally(() => {
-				if (provider.listenerCleanup === observed) delete provider.listenerCleanup;
-				if (disposed) this.scheduleListenerRestart(provider, workspaceContext, generation);
+				if (provider.agentConsumerStartup === observed) delete provider.agentConsumerStartup;
+			});
+			provider.agentConsumerStartup = observed;
+		}
+		agentConsumerFenceMatches(provider, workspaceContext, identityDid, generation) {
+			return this.provider === provider && this.workspaceContext === workspaceContext && this.activeIdentityDid === identityDid && provider.agentConsumerGeneration === generation;
+		}
+		async detachAgentConsumer(provider) {
+			const consumer = provider.agentConsumer;
+			if (consumer === void 0) return;
+			delete provider.agentConsumer;
+			delete provider.agentConsumerIdentityDid;
+			const observed = consumer.dispose().finally(() => {
+				if (provider.agentConsumerCleanup === observed) delete provider.agentConsumerCleanup;
 			});
-			provider.listenerCleanup = observed;
-		}
-		scheduleListenerRestart(provider, workspaceContext, generation) {
-			if (provider.listenerRestartTimer !== void 0 || !this.listenerFenceMatches(provider, workspaceContext, generation)) return;
-			provider.listenerRestartAttempt = Math.min(provider.listenerRestartAttempt + 1, LISTENER_RESTART_MAX_ATTEMPT);
-			const exponent = provider.listenerRestartAttempt - 1;
-			const delay = Math.min(LISTENER_RESTART_BASE_DELAY_MS * 2 ** exponent, LISTENER_RESTART_MAX_DELAY_MS);
-			const timer = setTimeout(() => {
-				if (provider.listenerRestartTimer !== timer) return;
-				delete provider.listenerRestartTimer;
-				if (!this.listenerFenceMatches(provider, workspaceContext, generation)) return;
-				this.startListener(provider);
-			}, delay);
-			provider.listenerRestartTimer = timer;
+			provider.agentConsumerCleanup = observed;
+			await observed;
+		}
+		async stopAgentConsumer(provider) {
+			provider.agentConsumerGeneration += 1;
+			await provider.agentConsumerStartup;
+			await provider.agentConsumerCleanup;
+			await this.detachAgentConsumer(provider);
+		}
+		async stopRealtimeSupervisor(provider) {
+			provider.realtimeGeneration += 1;
+			await provider.realtimeStartup;
+			const supervisor = provider.realtimeSupervisor;
+			if (supervisor === void 0) return;
+			delete provider.realtimeSupervisor;
+			delete provider.realtimeIdentityDid;
+			await supervisor.dispose();
+		}
+		async stopProviderRuntime(provider) {
+			await Promise.all([this.stopRealtimeSupervisor(provider), this.stopAgentConsumer(provider)]);
 		}
 		/** Clear one exact provider slot before joining its one shared disposal. */
 		disposeProvider(provider) {
-			if (this.provider === provider) this.provider = void 0;
+			if (this.provider === provider) {
+				this.provider = void 0;
+				this.pendingDeviceJoin = void 0;
+				this.activeDeviceJoinSessionId = void 0;
+				this.invalidateSummaries();
+			}
 			provider.disposal ??= (async () => {
 				try {
-					await this.stopListener(provider);
+					await provider.runtimeReplacement;
+					await this.stopProviderRuntime(provider);
 				} finally {
 					await provider.client.dispose();
 				}