sealkeep 0.9.0 → 0.11.0

package/dist/src/team-realtime.js

@@ -0,0 +1,816 @@
+/**
+ * Push wake-ups for encrypted cross-account presence.
+ *
+ * REST remains the durable append log and cursor catch-up path. The daemon
+ * keeps one Socket.IO connection per machine, multiplexes every locally bound
+ * opaque team-space id over it, and writes received ciphertext rows to a
+ * bounded local inbox. Agent hooks read that inbox at tool boundaries, so a
+ * busy team does not turn "is anyone already touching this?" into continuous
+ * HTTP polling.
+ *
+ * No user setting is involved: the realtime origin/path are derived from the
+ * same hosted API URL the signed-in client already uses, and the bearer stays
+ * in the native keystore/in-memory Socket.IO handshake.
+ */
+import { link, mkdir, open, readFile, readdir, rename, unlink, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { createHash, randomUUID } from "node:crypto";
+import { io } from "socket.io-client";
+import { cloudAuthGeneration, cloudBackoffUntil, cloudToken, cloudUrl, listTeamSpaces, rememberCloudBackoff, } from "./cloud.js";
+import { readConfig, revokeTeamSpaceBindings, updateTeamSpaceBindings } from "./vault.js";
+const SPACE_RE = /^[A-Za-z0-9_-]{43}$/;
+const SENDER_RE = /^[a-f0-9]{8}$/;
+const CHANNEL_PREFIX = "sealkeep:team:";
+const INBOX_LIMIT = 1_000;
+const PUSH_QUEUE_LIMIT = 256;
+const COMPACT_EVERY = 128;
+const DEFAULT_REFRESH_MS = 5_000;
+const TOKEN_RECHECK_MS = 5 * 60_000;
+const STATUS_HEARTBEAT_MS = 30_000;
+const HEALTH_MAX_AGE_MS = 90_000;
+const SUBSCRIBE_TIMEOUT_MS = 10_000;
+const inboxDir = (dataDir, spaceKey) => join(dataDir, "runtime", "team-presence-inbox", createHash("sha256").update(spaceKey).digest("hex"));
+const rowName = (id) => `row-${String(id).padStart(16, "0")}.json`;
+const ROW_FILE_RE = /^row-([0-9]{16})\.json$/;
+const DROPPED_FILE_RE = /^dropped-([0-9]{16})\.marker$/;
+const statusPath = (dataDir) => join(dataDir, "runtime", "team-realtime.json");
+const writeQueues = new Map();
+const compactCounters = new Map();
+function queued(path, work) {
+    const prior = writeQueues.get(path) ?? Promise.resolve();
+    const next = prior.catch(() => undefined).then(work);
+    // The queue tail is bookkeeping, not a second observer of the operation.
+    // Keep it fulfilled even when `next` rejects; the caller owns that rejection.
+    // A rejecting `.finally()` tail caused an unhandled rejection during cleanup.
+    const tracked = next.then(() => undefined, () => undefined).finally(() => {
+        if (writeQueues.get(path) === tracked)
+            writeQueues.delete(path);
+    });
+    writeQueues.set(path, tracked);
+    return next;
+}
+async function atomicJson(path, value) {
+    await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+    const temporary = `${path}.${randomUUID()}.tmp`;
+    await writeFile(temporary, JSON.stringify(value, null, 2) + "\n", { mode: 0o600 });
+    await rename(temporary, path);
+}
+function normalizedRow(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return null;
+    const row = value;
+    const id = Number(row.id);
+    const sequence = Number(row.sequence);
+    const keyVersion = Number(row.key_version);
+    const sender = typeof row.sender === "string" ? row.sender : "";
+    const ciphertext = typeof row.ciphertext === "string" ? row.ciphertext : "";
+    if (!Number.isSafeInteger(id) || id <= 0)
+        return null;
+    if (!Number.isSafeInteger(sequence) || sequence < 0)
+        return null;
+    if (!Number.isSafeInteger(keyVersion) || keyVersion <= 0)
+        return null;
+    if (!SENDER_RE.test(sender) || !ciphertext || ciphertext.length > 4_096)
+        return null;
+    const createdAt = typeof row.created_at === "string" && row.created_at.length <= 80 ? row.created_at : undefined;
+    const spaceId = Number(row.space_id);
+    const accountId = Number(row.account_id);
+    return {
+        id, sender, sequence, key_version: keyVersion, ciphertext,
+        ...(createdAt ? { created_at: createdAt } : {}),
+        ...(Number.isSafeInteger(spaceId) ? { space_id: spaceId } : {}),
+        ...(Number.isSafeInteger(accountId) && accountId > 0 ? { account_id: accountId } : {}),
+    };
+}
+async function markRealtimeGap(dataDir, spaceKey, droppedThrough) {
+    if (!SPACE_RE.test(spaceKey) || !Number.isSafeInteger(droppedThrough) || droppedThrough <= 0)
+        return;
+    const dir = inboxDir(dataDir, spaceKey);
+    await mkdir(dir, { recursive: true, mode: 0o700 });
+    const marker = `dropped-${String(droppedThrough).padStart(16, "0")}.marker`;
+    try {
+        await (await open(join(dir, marker), "wx", 0o600)).close();
+    }
+    catch (error) {
+        if (error.code !== "EEXIST")
+            throw error;
+    }
+    // Immutable, monotonically named markers avoid a cross-process lost-update
+    // race. Once the new high-water marker exists, lower ones are redundant.
+    const entries = await readdir(dir).catch(() => []);
+    await Promise.all(entries.flatMap((name) => {
+        const match = DROPPED_FILE_RE.exec(name);
+        return match && Number(match[1]) < droppedThrough ? [unlink(join(dir, name)).catch(() => undefined)] : [];
+    }));
+}
+async function compactInbox(dataDir, spaceKey) {
+    const dir = inboxDir(dataDir, spaceKey);
+    const entries = await readdir(dir).catch(() => []);
+    const rows = entries.flatMap((name) => {
+        const match = ROW_FILE_RE.exec(name);
+        return match ? [{ id: Number(match[1]), name }] : [];
+    }).filter((item) => Number.isSafeInteger(item.id)).sort((a, b) => a.id - b.id);
+    if (rows.length <= INBOX_LIMIT)
+        return;
+    const removing = rows.slice(0, rows.length - INBOX_LIMIT);
+    await markRealtimeGap(dataDir, spaceKey, removing[removing.length - 1].id);
+    await Promise.all(removing.map((item) => unlink(join(dir, item.name)).catch(() => undefined)));
+}
+/**
+ * Cache one validated wire row in its own immutable file. This is O(event),
+ * not O(all spaces × inbox size), and atomic hard links make overlapping daemon handoffs
+ * converge on the first complete row instead of overwriting one another.
+ */
+export async function cacheRealtimeTeamPresence(dataDir, spaceKey, value) {
+    if (!SPACE_RE.test(spaceKey))
+        return false;
+    const row = normalizedRow(value);
+    if (!row)
+        return false;
+    const dir = inboxDir(dataDir, spaceKey);
+    await mkdir(dir, { recursive: true, mode: 0o700 });
+    const path = join(dir, rowName(row.id));
+    const temporary = join(dir, `.${rowName(row.id)}.${randomUUID()}.tmp`);
+    await writeFile(temporary, JSON.stringify(row) + "\n", { mode: 0o600 });
+    try {
+        await link(temporary, path);
+    }
+    catch (error) {
+        if (error.code === "EEXIST") {
+            await unlink(temporary).catch(() => undefined);
+            return false;
+        }
+        await unlink(temporary).catch(() => undefined);
+        throw error;
+    }
+    await unlink(temporary).catch(() => undefined);
+    const key = `${dataDir}\0${spaceKey}`;
+    const count = compactCounters.get(key);
+    if (count === undefined || count + 1 >= COMPACT_EVERY) {
+        compactCounters.set(key, 0);
+        await compactInbox(dataDir, spaceKey);
+    }
+    else
+        compactCounters.set(key, count + 1);
+    return true;
+}
+/** Read only local ciphertext rows newer than a durable cursor. */
+export async function readRealtimeTeamPresence(dataDir, spaceKey, after) {
+    const cursorBefore = Number.isSafeInteger(after) ? Math.max(0, Math.trunc(after)) : 0;
+    if (!SPACE_RE.test(spaceKey))
+        return { rows: [], cursor: cursorBefore, gap: false };
+    const dir = inboxDir(dataDir, spaceKey);
+    const entries = await readdir(dir).catch(() => []);
+    const allRows = entries.flatMap((name) => {
+        const match = ROW_FILE_RE.exec(name);
+        return match ? [{ id: Number(match[1]), name }] : [];
+    }).filter((item) => Number.isSafeInteger(item.id)).sort((a, b) => a.id - b.id);
+    const markerHighWater = entries.reduce((max, name) => {
+        const match = DROPPED_FILE_RE.exec(name);
+        return match ? Math.max(max, Number(match[1])) : max;
+    }, 0);
+    const overflowHighWater = allRows.length > INBOX_LIMIT ? allRows[allRows.length - INBOX_LIMIT - 1].id : 0;
+    const retained = allRows.slice(-INBOX_LIMIT).filter((item) => item.id > cursorBefore);
+    const rows = (await Promise.all(retained.map(async (item) => {
+        try {
+            const row = normalizedRow(JSON.parse(await readFile(join(dir, item.name), "utf8")));
+            return row?.id === item.id ? row : null;
+        }
+        catch {
+            return null;
+        }
+    }))).filter((row) => row !== null).sort((a, b) => a.id - b.id);
+    return {
+        rows,
+        cursor: rows.reduce((max, row) => Math.max(max, row.id), cursorBefore),
+        gap: cursorBefore < Math.max(markerHighWater, overflowHighWater),
+    };
+}
+export function teamRealtimeChannel(routeKey) {
+    return `${CHANNEL_PREFIX}${routeKey}`;
+}
+export function teamRealtimeEndpoint(env = process.env) {
+    const api = new URL(cloudUrl(env));
+    const pathname = api.pathname.replace(/\/+$/, "");
+    const prefix = pathname.endsWith("/api") ? pathname.slice(0, -4) : "";
+    return { origin: api.origin, path: `${prefix}/realtime` || "/realtime" };
+}
+async function writeStatus(dataDir, status) {
+    await queued(statusPath(dataDir), () => atomicJson(statusPath(dataDir), status));
+}
+export async function readTeamRealtimeStatus(dataDir) {
+    try {
+        const value = JSON.parse(await readFile(statusPath(dataDir), "utf8"));
+        if (value.version !== 1 || typeof value.connected !== "boolean" || typeof value.updatedAt !== "string" || !Array.isArray(value.subscribedSpaces))
+            return null;
+        return {
+            version: 1,
+            connected: value.connected,
+            updatedAt: value.updatedAt,
+            subscribedSpaces: value.subscribedSpaces.filter((item) => typeof item === "string" && SPACE_RE.test(item)),
+            ...(typeof value.connectionId === "string" ? { connectionId: value.connectionId.slice(0, 80) } : {}),
+            ...(typeof value.lastError === "string" ? { lastError: value.lastError.slice(0, 240) } : {}),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+export function teamRealtimeStatusHealthy(status, spaceKey, options = {}) {
+    if (!status?.connected || !status.subscribedSpaces.includes(spaceKey))
+        return false;
+    const age = (options.now ?? Date.now()) - Date.parse(status.updatedAt);
+    return Number.isFinite(age) && age >= 0 && age <= (options.maxAgeMs ?? HEALTH_MAX_AGE_MS);
+}
+export async function teamRealtimeHealthy(dataDir, spaceKey, options = {}) {
+    return teamRealtimeStatusHealthy(await readTeamRealtimeStatus(dataDir), spaceKey, options);
+}
+function errorLine(error) {
+    return (error instanceof Error ? error.message : String(error)).replace(/[\r\n]+/g, " ").slice(0, 240);
+}
+const objectOf = (value) => value && typeof value === "object" && !Array.isArray(value) ? value : null;
+function numberOf(values) {
+    for (const value of values) {
+        const numeric = Number(value);
+        if (Number.isFinite(numeric) && numeric >= 0)
+            return numeric;
+    }
+    return null;
+}
+/** Normalize Socket.IO middleware errors and Engine.IO HTTP 429 responses. */
+function realtimeRateLimit(error) {
+    const root = objectOf(error);
+    const data = objectOf(root?.data);
+    const context = objectOf(root?.context);
+    let body = null;
+    const responseText = typeof context?.responseText === "string" ? context.responseText : "";
+    if (responseText) {
+        try {
+            body = objectOf(JSON.parse(responseText));
+        }
+        catch { /* a proxy may return a plain-text 429 */ }
+    }
+    const bodyError = objectOf(body?.error);
+    const dataError = objectOf(data?.error);
+    const records = [root, data, dataError, context, body, bodyError].filter((item) => item !== null);
+    const status = numberOf(records.flatMap((item) => [item.status, item.statusCode, item.httpStatus]));
+    const words = records.flatMap((item) => [item.code, item.message, item.error])
+        .filter((item) => typeof item === "string").join(" ");
+    if (status !== 429 && !/(?:^|\D)429(?:\D|$)|rate[_ -]?limit|request allowance.*(?:exhausted|reached)|PROJECT_API_REQUEST_LIMIT_EXCEEDED/i.test(words))
+        return null;
+    const milliseconds = numberOf(records.flatMap((item) => [item.retryAfterMs, item.retry_after_ms]));
+    if (milliseconds !== null)
+        return { retryAfterMs: Math.max(1_000, milliseconds) };
+    const seconds = numberOf(records.flatMap((item) => [item.retryAfterSeconds, item.retry_after_seconds, item.retryAfter]));
+    if (seconds !== null)
+        return { retryAfterMs: Math.max(1_000, seconds * 1_000) };
+    const resetAt = records.flatMap((item) => [item.resetAt, item.reset_at]).find((item) => typeof item === "string");
+    if (typeof resetAt === "string" && Number.isFinite(Date.parse(resetAt))) {
+        return { retryAfterMs: Math.max(1_000, Date.parse(resetAt) - Date.now()) };
+    }
+    try {
+        const header = typeof context?.getResponseHeader === "function"
+            ? String(context.getResponseHeader("retry-after") ?? "") : "";
+        const headerSeconds = Number(header);
+        if (Number.isFinite(headerSeconds) && headerSeconds >= 0)
+            return { retryAfterMs: Math.max(1_000, headerSeconds * 1_000) };
+        const headerAt = Date.parse(header);
+        if (Number.isFinite(headerAt))
+            return { retryAfterMs: Math.max(1_000, headerAt - Date.now()) };
+    }
+    catch { /* an Engine.IO context need not expose response headers */ }
+    return { retryAfterMs: 60_000 };
+}
+/**
+ * Start the package-owned machine listener. It is deliberately fail-open:
+ * missing sign-in, no team spaces, network failures, and auth expiry leave the
+ * durable REST path intact and never stop the preservation daemon.
+ */
+export async function startTeamRealtime(dataDir, options = {}) {
+    const endpoint = teamRealtimeEndpoint();
+    // Public status and local inboxes are keyed by the stable logical space id.
+    // The values are rotatable, unguessable Socket.IO room ids.
+    const desired = new Map();
+    const subscribed = new Map();
+    const subscribing = new Map();
+    let socket = null;
+    let socketGeneration = 0;
+    let tokenInUse = null;
+    let lastTokenCheckAt = 0;
+    let nextTokenAttemptAt = 0;
+    let authGeneration = null;
+    let connectionId;
+    let closed = false;
+    let reconnectDelayMs = 500;
+    let reconnectTimer;
+    let refresh;
+    let refreshInFlight;
+    let closeInFlight;
+    let lastError;
+    let readyResolved = false;
+    let readyPersisting = false;
+    let resolveReady;
+    const ready = new Promise((resolve) => { resolveReady = resolve; });
+    const inboxWork = new Map();
+    const activeDrains = new Set();
+    let reconciliation = null;
+    const routeOf = (binding) => binding.realtimeKey && SPACE_RE.test(binding.realtimeKey) ? binding.realtimeKey : binding.spaceKey;
+    const sameRoutes = (left, right) => left.size === right.size && [...left].every(([spaceKey, routeKey]) => right.get(spaceKey) === routeKey);
+    /** Reload local bindings only; this is the cheap five-second discovery path. */
+    const reloadDesired = async () => {
+        const config = await readConfig(dataDir);
+        const next = new Map();
+        for (const binding of Object.values(config.teamSpaces ?? {})) {
+            if (!SPACE_RE.test(binding.spaceKey))
+                continue;
+            next.set(binding.spaceKey, routeOf(binding));
+        }
+        const changed = !sameRoutes(desired, next);
+        desired.clear();
+        for (const [spaceKey, routeKey] of next)
+            desired.set(spaceKey, routeKey);
+        return changed;
+    };
+    /** Best-effort removal of the revoked epoch key from this machine's keystore. */
+    const forgetRevokedFeed = async (spaceKey) => {
+        try {
+            const core = await import("./team-presence.js");
+            const forget = core.forgetTeamSpaceFeed;
+            if (typeof forget === "function") {
+                await forget(dataDir, spaceKey, options.preferred);
+            }
+        }
+        catch (error) {
+            // The binding is already revoked. Keep that security boundary even if a
+            // platform keystore temporarily refuses deletion; surface it for repair.
+            lastError = `team feed revoke: ${errorLine(error)}`;
+        }
+    };
+    /**
+     * One authoritative REST reconciliation per connection generation or
+     * rotation notice. It is deliberately not called by the steady refresh
+     * timer: Socket.IO remains the wake-up path and REST remains bounded.
+     */
+    const reconcileMemberships = () => {
+        if (reconciliation)
+            return reconciliation;
+        const work = (async () => {
+            const before = await readConfig(dataDir);
+            const localBySpace = new Map();
+            for (const binding of Object.values(before.teamSpaces ?? {})) {
+                if (SPACE_RE.test(binding.spaceKey) && !localBySpace.has(binding.spaceKey))
+                    localBySpace.set(binding.spaceKey, binding);
+            }
+            if (!localBySpace.size) {
+                const routingChanged = await reloadDesired();
+                return { bindingChanged: false, routingChanged };
+            }
+            const hosted = await listTeamSpaces(dataDir, options.preferred);
+            const hostedBySpace = new Map(hosted.flatMap((raw) => {
+                const row = raw;
+                return SPACE_RE.test(row.space_key) ? [[row.space_key, row]] : [];
+            }));
+            let bindingChanged = false;
+            for (const [spaceKey, local] of localBySpace) {
+                const remote = hostedBySpace.get(spaceKey);
+                if (!remote) {
+                    await revokeTeamSpaceBindings(dataDir, spaceKey);
+                    await forgetRevokedFeed(spaceKey);
+                    bindingChanged = true;
+                    continue;
+                }
+                const patch = {};
+                const keyVersion = Number(remote.key_version);
+                if (Number.isSafeInteger(keyVersion) && keyVersion > 0)
+                    patch.keyVersion = keyVersion;
+                if (remote.role === "owner" || remote.role === "member")
+                    patch.role = remote.role;
+                if (typeof remote.realtime_key === "string" && SPACE_RE.test(remote.realtime_key))
+                    patch.realtimeKey = remote.realtime_key;
+                if ((patch.keyVersion !== undefined && patch.keyVersion !== local.keyVersion)
+                    || (patch.role !== undefined && patch.role !== local.role)
+                    || (patch.realtimeKey !== undefined && patch.realtimeKey !== local.realtimeKey))
+                    bindingChanged = true;
+                await updateTeamSpaceBindings(dataDir, spaceKey, patch);
+            }
+            const routingChanged = await reloadDesired();
+            return { bindingChanged, routingChanged };
+        })();
+        const tracked = work.finally(() => {
+            if (reconciliation === tracked)
+                reconciliation = null;
+        });
+        reconciliation = tracked;
+        return tracked;
+    };
+    const enqueuePresence = (spaceKey, value) => {
+        const row = normalizedRow(value);
+        if (!row)
+            return;
+        const work = inboxWork.get(spaceKey) ?? { rows: [], droppedThrough: 0, running: false };
+        inboxWork.set(spaceKey, work);
+        if (work.rows.length >= PUSH_QUEUE_LIMIT)
+            work.droppedThrough = Math.max(work.droppedThrough, row.id);
+        else
+            work.rows.push(row);
+        if (work.running)
+            return;
+        work.running = true;
+        const drain = (async () => {
+            for (;;) {
+                const next = work.rows.shift();
+                if (next) {
+                    try {
+                        await cacheRealtimeTeamPresence(dataDir, spaceKey, next);
+                    }
+                    catch (error) {
+                        work.droppedThrough = Math.max(work.droppedThrough, next.id);
+                        lastError = `presence inbox: ${errorLine(error)}`;
+                    }
+                    continue;
+                }
+                if (work.droppedThrough > 0) {
+                    const droppedThrough = work.droppedThrough;
+                    work.droppedThrough = 0;
+                    try {
+                        await markRealtimeGap(dataDir, spaceKey, droppedThrough);
+                    }
+                    catch (error) {
+                        lastError = `presence gap marker: ${errorLine(error)}`;
+                    }
+                    continue;
+                }
+                break;
+            }
+            work.running = false;
+        })();
+        activeDrains.add(drain);
+        void drain.then(() => activeDrains.delete(drain), () => activeDrains.delete(drain));
+    };
+    const snapshot = () => ({
+        version: 1,
+        connected: socket?.connected === true,
+        updatedAt: new Date().toISOString(),
+        subscribedSpaces: [...subscribed.keys()].sort(),
+        ...(connectionId ? { connectionId } : {}),
+        ...(lastError ? { lastError } : {}),
+    });
+    const persistStatus = () => closed ? Promise.resolve() : writeStatus(dataDir, snapshot()).catch(() => undefined);
+    const scheduleReconnect = () => {
+        if (closed || reconnectTimer || Date.now() < nextTokenAttemptAt)
+            return;
+        const delay = reconnectDelayMs;
+        reconnectDelayMs = Math.min(15_000, reconnectDelayMs * 2);
+        nextTokenAttemptAt = Date.now() + delay;
+        reconnectTimer = setTimeout(() => {
+            reconnectTimer = undefined;
+            void refresh();
+        }, delay);
+        reconnectTimer.unref?.();
+    };
+    const settleReady = () => {
+        if (closed || readyResolved || readyPersisting || ![...desired.keys()].every((spaceKey) => subscribed.has(spaceKey)))
+            return;
+        // A separate hook process consumes the durable status file, not this
+        // closure. Do not announce readiness until the acknowledged subscription
+        // generation is visible there, or the very next tool boundary can read the
+        // prior disconnected generation and skip its required reconnect catch-up.
+        const generation = socketGeneration;
+        const expectedConnectionId = connectionId;
+        const expectedSpaces = [...desired.keys()].sort();
+        const expectedStatus = snapshot();
+        readyPersisting = true;
+        void writeStatus(dataDir, expectedStatus).then(() => readTeamRealtimeStatus(dataDir)).then((durable) => {
+            readyPersisting = false;
+            const sameSpaces = durable?.subscribedSpaces.length === expectedSpaces.length
+                && expectedSpaces.every((spaceKey, index) => durable.subscribedSpaces[index] === spaceKey);
+            const socketMatches = expectedStatus.connected ? socket?.connected === true : socket?.connected !== true;
+            if (closed || readyResolved)
+                return;
+            if (generation !== socketGeneration || expectedConnectionId !== connectionId || !socketMatches
+                || ![...desired.keys()].every((spaceKey) => subscribed.has(spaceKey))
+                || durable?.connected !== expectedStatus.connected || durable.connectionId !== expectedConnectionId || !sameSpaces)
+                return;
+            readyResolved = true;
+            resolveReady();
+        }, () => { readyPersisting = false; });
+    };
+    const syncSubscriptions = () => {
+        if (!socket?.connected)
+            return;
+        const generation = socketGeneration;
+        const targetSocket = socket;
+        for (const [spaceKey, routeKey] of [...subscribed]) {
+            if (desired.get(spaceKey) === routeKey)
+                continue;
+            socket.emit("unsubscribe", { channel: teamRealtimeChannel(routeKey) });
+            subscribed.delete(spaceKey);
+            subscribing.delete(spaceKey);
+        }
+        for (const [spaceKey, routeKey] of desired) {
+            if (subscribed.get(spaceKey) === routeKey || subscribing.get(spaceKey) === routeKey)
+                continue;
+            subscribing.set(spaceKey, routeKey);
+            let settled = false;
+            const timeout = setTimeout(() => {
+                if (settled)
+                    return;
+                settled = true;
+                if (generation !== socketGeneration || socket !== targetSocket)
+                    return;
+                if (subscribing.get(spaceKey) === routeKey)
+                    subscribing.delete(spaceKey);
+                lastError = `subscription timed out for ${spaceKey.slice(0, 8)}`;
+                void persistStatus();
+            }, SUBSCRIBE_TIMEOUT_MS);
+            timeout.unref?.();
+            socket.emit("subscribe", { channel: teamRealtimeChannel(routeKey) }, (ack) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timeout);
+                if (generation !== socketGeneration || socket !== targetSocket)
+                    return;
+                if (subscribing.get(spaceKey) !== routeKey || desired.get(spaceKey) !== routeKey)
+                    return;
+                subscribing.delete(spaceKey);
+                if (closed || !ack || typeof ack !== "object" || Array.isArray(ack))
+                    return;
+                const response = ack;
+                if (response.success === true) {
+                    subscribed.set(spaceKey, routeKey);
+                    lastError = undefined;
+                    settleReady();
+                }
+                else if (typeof response.error === "string") {
+                    lastError = response.error.slice(0, 240);
+                }
+                void persistStatus();
+            });
+        }
+        settleReady();
+        void persistStatus();
+    };
+    const stopSocket = () => {
+        if (!socket)
+            return;
+        socketGeneration += 1;
+        socket.removeAllListeners();
+        socket.disconnect();
+        socket = null;
+        tokenInUse = null;
+        subscribed.clear();
+        subscribing.clear();
+    };
+    const reconcileAfterRotation = () => {
+        const generation = socketGeneration;
+        void reconcileMemberships().then(({ bindingChanged, routingChanged }) => {
+            if (closed || generation !== socketGeneration || socket?.connected !== true)
+                return;
+            if (bindingChanged || routingChanged)
+                connectionId = randomUUID();
+            if (!desired.size) {
+                stopSocket();
+                settleReady();
+                void persistStatus();
+                return;
+            }
+            syncSubscriptions();
+        }, (error) => {
+            lastError = `team key rotation: ${errorLine(error)}`;
+            void persistStatus();
+        });
+    };
+    const connect = (token) => {
+        if (socket && tokenInUse === token) {
+            if (!socket.connected && !socket.active)
+                socket.connect();
+            return;
+        }
+        stopSocket();
+        tokenInUse = token;
+        socket = io(endpoint.origin, {
+            path: endpoint.path,
+            auth: { token },
+            // Begin with the broadly proxy-safe Engine.IO polling handshake, then
+            // upgrade when the hosted edge supports WebSocket. Forcing WebSocket as
+            // the initial transport failed behind the real Spala/Cloudflare route
+            // even though its polling handshake and later upgrade are available.
+            transports: ["polling", "websocket"],
+            // Reconnects are owned by refresh(), which checks the shared durable 429
+            // receipt first. Letting Manager reconnect independently would create a
+            // second path capable of bypassing the server's Retry-After instruction.
+            reconnection: false,
+            timeout: 10_000,
+        });
+        socket.on("connect", () => {
+            socketGeneration += 1;
+            const generation = socketGeneration;
+            subscribed.clear();
+            subscribing.clear();
+            connectionId = randomUUID();
+            nextTokenAttemptAt = 0;
+            reconnectDelayMs = 500;
+            if (reconnectTimer)
+                clearTimeout(reconnectTimer);
+            reconnectTimer = undefined;
+            lastError = undefined;
+            // Do not join the route remembered before an offline rotation. First ask
+            // the membership-scoped REST endpoint for this account's current route.
+            void reconcileMemberships().then(() => {
+                if (closed || generation !== socketGeneration || socket?.connected !== true)
+                    return;
+                if (!desired.size) {
+                    stopSocket();
+                    settleReady();
+                    void persistStatus();
+                    return;
+                }
+                syncSubscriptions();
+            }, (error) => {
+                if (closed || generation !== socketGeneration || socket?.connected !== true)
+                    return;
+                // A transient REST failure must not destroy a healthy live lane. Join
+                // the last durable route; a reconnect or key_rotated notice retries.
+                lastError = `team membership reconcile: ${errorLine(error)}`;
+                syncSubscriptions();
+            });
+        });
+        socket.on("disconnect", (reason) => {
+            socketGeneration += 1;
+            subscribed.clear();
+            subscribing.clear();
+            lastError = `disconnected: ${reason}`;
+            scheduleReconnect();
+            void persistStatus();
+        });
+        socket.on("connect_error", (error) => {
+            subscribed.clear();
+            subscribing.clear();
+            lastError = errorLine(error);
+            const limited = realtimeRateLimit(error);
+            if (limited) {
+                const until = Date.now() + limited.retryAfterMs;
+                stopSocket();
+                nextTokenAttemptAt = Math.max(nextTokenAttemptAt, until);
+                lastError = `rate limited until ${new Date(until).toISOString()}`;
+                const backoff = rememberCloudBackoff(dataDir, limited.retryAfterMs).then(() => persistStatus(), () => persistStatus());
+                activeDrains.add(backoff);
+                void backoff.then(() => activeDrains.delete(backoff));
+            }
+            else if (/auth|token|unauthor|forbid|jwt/i.test(lastError)) {
+                stopSocket();
+                nextTokenAttemptAt = Date.now() + TOKEN_RECHECK_MS;
+            }
+            else
+                scheduleReconnect();
+            void persistStatus();
+        });
+        // The native relay may send this server-authored control event directly,
+        // while proxy-compatible deployments wrap it in `broadcast` below. It
+        // carries no new route or key; authorized REST state remains the authority.
+        socket.on("key_rotated", (message) => {
+            const value = objectOf(message);
+            const spaceKey = typeof value?.space_key === "string" ? value.space_key : "";
+            if (!SPACE_RE.test(spaceKey) || !subscribed.has(spaceKey) || desired.get(spaceKey) !== subscribed.get(spaceKey))
+                return;
+            reconcileAfterRotation();
+        });
+        socket.on("broadcast", (message) => {
+            if (!message || typeof message !== "object" || Array.isArray(message))
+                return;
+            const envelope = message;
+            if (typeof envelope.channel !== "string" || !envelope.channel.startsWith(CHANNEL_PREFIX))
+                return;
+            const routeKey = envelope.channel.slice(CHANNEL_PREFIX.length);
+            const logicalSpaces = [...subscribed].flatMap(([spaceKey, subscribedRoute]) => subscribedRoute === routeKey && desired.get(spaceKey) === routeKey ? [spaceKey] : []);
+            if (!logicalSpaces.length)
+                return;
+            if (envelope.event === "presence") {
+                for (const spaceKey of logicalSpaces)
+                    enqueuePresence(spaceKey, envelope.payload);
+                return;
+            }
+            if (envelope.event !== "key_rotated")
+                return;
+            const payload = objectOf(envelope.payload);
+            const spaceKey = typeof payload?.space_key === "string" ? payload.space_key : "";
+            // The old subscribed route and the stable logical id must agree. Ignore
+            // every other payload field: the server-authored membership listing is
+            // the only authority for whether we remain a member and which room wins.
+            if (!SPACE_RE.test(spaceKey) || !logicalSpaces.includes(spaceKey))
+                return;
+            reconcileAfterRotation();
+        });
+    };
+    const refreshOnce = async () => {
+        if (closed)
+            return;
+        try {
+            const routingChanged = await reloadDesired();
+            if (closed)
+                return;
+            if (routingChanged && socket?.connected === true)
+                connectionId = randomUUID();
+            if (!desired.size) {
+                stopSocket();
+                lastError = undefined;
+                settleReady();
+                await persistStatus();
+                return;
+            }
+            // A 429 learned by REST or a prior realtime handshake is a control-plane
+            // instruction, not a hint. Do not let Socket.IO's reconnect manager make
+            // background attempts during that durable cooldown. An already-open push
+            // socket is kept because it consumes no new handshake requests.
+            const backoffUntil = await cloudBackoffUntil(dataDir);
+            if (closed)
+                return;
+            if (socket?.connected !== true && backoffUntil > Date.now()) {
+                stopSocket();
+                nextTokenAttemptAt = Math.max(nextTokenAttemptAt, backoffUntil);
+                lastError = `rate limited until ${new Date(backoffUntil).toISOString()}`;
+                await persistStatus();
+                return;
+            }
+            // Space discovery is cheap JSON and runs every five seconds so enabling
+            // team mode needs no restart. Native token retrieval is deliberately not
+            // on that loop: probing Keychain/Secret Service hundreds of times per
+            // hour would turn an idle daemon into needless process churn.
+            const currentAuthGeneration = await cloudAuthGeneration(dataDir);
+            if (closed)
+                return;
+            if (currentAuthGeneration !== authGeneration)
+                nextTokenAttemptAt = 0;
+            if (socket && currentAuthGeneration === authGeneration && Date.now() - lastTokenCheckAt < TOKEN_RECHECK_MS) {
+                if (!socket.connected && !socket.active && Date.now() >= nextTokenAttemptAt)
+                    socket.connect();
+                syncSubscriptions();
+                return;
+            }
+            if (!socket && Date.now() < nextTokenAttemptAt)
+                return;
+            const token = await cloudToken(dataDir, options.preferred);
+            if (closed)
+                return;
+            lastTokenCheckAt = Date.now();
+            nextTokenAttemptAt = 0;
+            authGeneration = currentAuthGeneration;
+            connect(token);
+            syncSubscriptions();
+        }
+        catch (error) {
+            // A missing/revoked token must not leave an authenticated socket alive.
+            // Transient loss degrades to REST and the next refresh retries cleanly.
+            stopSocket();
+            lastTokenCheckAt = Date.now();
+            nextTokenAttemptAt = Date.now() + TOKEN_RECHECK_MS;
+            authGeneration = await cloudAuthGeneration(dataDir).catch(() => null);
+            lastError = errorLine(error);
+            await persistStatus();
+        }
+    };
+    refresh = () => {
+        if (closed)
+            return Promise.resolve();
+        if (refreshInFlight)
+            return refreshInFlight;
+        const work = refreshOnce();
+        refreshInFlight = work;
+        void work.then(() => { if (refreshInFlight === work)
+            refreshInFlight = undefined; }, () => { if (refreshInFlight === work)
+            refreshInFlight = undefined; });
+        return work;
+    };
+    await refresh();
+    const refreshTimer = setInterval(() => { void refresh(); }, Math.max(250, options.refreshMs ?? DEFAULT_REFRESH_MS));
+    const heartbeatTimer = setInterval(() => { void persistStatus(); }, STATUS_HEARTBEAT_MS);
+    refreshTimer.unref?.();
+    heartbeatTimer.unref?.();
+    return {
+        ready,
+        refresh,
+        close: () => {
+            if (closeInFlight)
+                return closeInFlight;
+            closeInFlight = (async () => {
+                closed = true;
+                clearInterval(refreshTimer);
+                clearInterval(heartbeatTimer);
+                if (reconnectTimer)
+                    clearTimeout(reconnectTimer);
+                reconnectTimer = undefined;
+                stopSocket();
+                await refreshInFlight;
+                await reconciliation?.catch(() => undefined);
+                await Promise.all([...activeDrains]);
+                lastError = undefined;
+                // Queue the final disconnected status after every owned producer has
+                // stopped. No refresh may recreate a socket or write after close.
+                await writeStatus(dataDir, snapshot()).catch(() => undefined);
+            })();
+            return closeInFlight;
+        },
+        status: snapshot,
+    };
+}