@mindexec/cli 0.2.136 → 0.2.137

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mindexec/cli",
-  "version": "0.2.136",
+  "version": "0.2.137",
   "description": "MindExec local runtime and bridge CLI",
   "main": "server.js",
   "type": "module",

package/scripts/remote-registry-follower-smoke.mjs

@@ -8,6 +8,7 @@ import net from 'node:net';
 import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { WebSocketServer } from 'ws';
 
 const BRIDGE_TOKEN = 'remote-registry-follower-smoke-token';
 const PAIR_TOKEN = 'remote-registry-follower-pair-token';
@@ -84,6 +85,7 @@ function createRegistryTarget({ endpoint, endpointCandidates, leaseId, active =
 
 function startFakeSupabase(getTarget) {
     const requests = [];
+    const realtimeClients = new Set();
     const server = createServer((req, res) => {
         const parsed = new URL(req.url || '/', 'http://127.0.0.1');
         requests.push({
@@ -108,6 +110,77 @@ function startFakeSupabase(getTarget) {
         res.writeHead(404, { 'Content-Type': 'application/json' });
         res.end(JSON.stringify({ error: 'not-found' }));
     });
+    const realtime = new WebSocketServer({ noServer: true });
+
+    realtime.on('connection', (ws, req) => {
+        realtimeClients.add(ws);
+        ws.on('message', data => {
+            const text = data.toString();
+            let message = null;
+            try {
+                message = JSON.parse(text);
+            } catch {
+                return;
+            }
+
+            if (message.event === 'phx_join') {
+                assert.equal(String(req.headers.apikey || ''), SUPABASE_KEY);
+                assert.equal(String(req.headers.authorization || ''), `Bearer ${ACCESS_TOKEN}`);
+                assert.equal(message.payload?.access_token, ACCESS_TOKEN);
+                assert.deepEqual(
+                    message.payload?.config?.postgres_changes?.[0],
+                    {
+                        event: '*',
+                        schema: 'public',
+                        table: 'remote_host_targets',
+                        filter: `user_id=eq.${USER_ID}`
+                    });
+                ws.remoteRegistryTopic = message.topic;
+                ws.send(JSON.stringify({
+                    topic: message.topic,
+                    event: 'phx_reply',
+                    payload: {
+                        status: 'ok',
+                        response: {
+                            postgres_changes: [
+                                {
+                                    id: 1,
+                                    event: '*',
+                                    schema: 'public',
+                                    table: 'remote_host_targets'
+                                }
+                            ]
+                        }
+                    },
+                    ref: message.ref,
+                    join_ref: message.join_ref
+                }));
+                return;
+            }
+
+            if (message.event === 'heartbeat') {
+                ws.send(JSON.stringify({
+                    topic: message.topic,
+                    event: 'phx_reply',
+                    payload: { status: 'ok', response: {} },
+                    ref: message.ref
+                }));
+            }
+        });
+        ws.on('close', () => realtimeClients.delete(ws));
+    });
+
+    server.on('upgrade', (req, socket, head) => {
+        const parsed = new URL(req.url || '/', 'http://127.0.0.1');
+        if (parsed.pathname !== '/realtime/v1/websocket') {
+            socket.destroy();
+            return;
+        }
+
+        realtime.handleUpgrade(req, socket, head, ws => {
+            realtime.emit('connection', ws, req);
+        });
+    });
 
     return new Promise((resolve, reject) => {
         server.once('error', reject);
@@ -117,7 +190,41 @@ function startFakeSupabase(getTarget) {
             resolve({
                 url: `http://127.0.0.1:${port}`,
                 requests,
-                stop: () => new Promise(done => server.close(done))
+                realtimeClients,
+                broadcastChange: (type = 'UPDATE') => {
+                    for (const client of realtimeClients) {
+                        if (client.readyState !== 1 || !client.remoteRegistryTopic) {
+                            continue;
+                        }
+
+                        client.send(JSON.stringify({
+                            topic: client.remoteRegistryTopic,
+                            event: 'postgres_changes',
+                            payload: {
+                                ids: [1],
+                                data: {
+                                    schema: 'public',
+                                    table: 'remote_host_targets',
+                                    commit_timestamp: new Date().toISOString(),
+                                    type,
+                                    record: getTarget(),
+                                    old_record: null
+                                }
+                            },
+                            ref: null
+                        }));
+                    }
+                },
+                stop: () => new Promise(done => {
+                    for (const client of realtimeClients) {
+                        try {
+                            client.close();
+                        } catch {
+                            // best effort only
+                        }
+                    }
+                    realtime.close(() => server.close(done));
+                })
             });
         });
     });
@@ -140,8 +247,10 @@ function spawnBridge({ bridgePort, remoteHubPort, workspacePath, authRoot, label
             WORKSPACE_PATH: workspacePath,
             MINDEXEC_AUTH_DATA_ROOT: authRoot,
             MINDEXEC_REMOTE_REGISTRY_FOLLOWER: follower ? '1' : '0',
-            MINDEXEC_REMOTE_REGISTRY_POLL_MS: '500',
+            MINDEXEC_REMOTE_REGISTRY_POLL_MS: '10000',
             MINDEXEC_REMOTE_REGISTRY_FAST_RETRY_MS: '250',
+            MINDEXEC_REMOTE_REGISTRY_REALTIME_RECONNECT_MS: '250',
+            MINDEXEC_REMOTE_REGISTRY_REALTIME_DEBOUNCE_MS: '100',
             SUPABASE_URL: supabaseUrl,
             SUPABASE_KEY,
             NO_COLOR: '1'
@@ -196,7 +305,7 @@ async function writeSession(authRoot) {
     }), 'utf8');
 }
 
-async function waitForManagedAgent(bridge, managerEndpoint, label) {
+async function waitForManagedAgent(bridge, managerEndpoint, label, timeoutMs = 20000) {
     return await waitFor(async () => {
         const result = await fetchJson(`${bridge.baseUrl}/api/remote/agent/status`);
         const agent = result.payload;
@@ -205,7 +314,7 @@ async function waitForManagedAgent(bridge, managerEndpoint, label) {
             && String(agent.manager || '') === managerEndpoint
             ? agent
             : null;
-    }, 20000, `${label} managed agent\n${bridge.details()}`);
+    }, timeoutMs, `${label} managed agent\n${bridge.details()}`);
 }
 
 async function waitForConnectedDevice(bridge, label) {
@@ -280,14 +389,18 @@ async function main() {
         assert.equal(firstAgent.manager, hostAEndpoint);
         assert.equal(firstAgent.managerCandidates?.[0], staleEndpoint, JSON.stringify(firstAgent.managerCandidates));
         await waitForConnectedDevice(hostA, 'host-a');
+        const firstStatus = await fetchJson(`${client.baseUrl}/api/status`);
+        assert.equal(firstStatus.payload?.remoteRegistryRealtime?.subscribed, true, JSON.stringify(firstStatus.payload?.remoteRegistryRealtime));
+        assert.ok(fakeSupabase.realtimeClients.size >= 1, 'expected LocalBridge realtime watcher to connect');
 
         currentTarget = createRegistryTarget({
             endpoint: hostBEndpoint,
             endpointCandidates: [hostBEndpoint],
             leaseId: 'lease-b'
         });
+        fakeSupabase.broadcastChange('UPDATE');
 
-        const secondAgent = await waitForManagedAgent(client, hostBEndpoint, 'host-b');
+        const secondAgent = await waitForManagedAgent(client, hostBEndpoint, 'host-b', 9000);
         assert.equal(secondAgent.usingNpx, false, JSON.stringify(secondAgent));
         assert.match(String(secondAgent.launcher || ''), /mindexec-remote-fast/i);
         assert.equal(secondAgent.manager, hostBEndpoint);
@@ -299,6 +412,7 @@ async function main() {
             active: false,
             expires_at: new Date(Date.now() - 1000).toISOString()
         };
+        fakeSupabase.broadcastChange('UPDATE');
 
         await waitFor(async () => {
             const result = await fetchJson(`${client.baseUrl}/api/remote/agent/status`);
@@ -306,7 +420,10 @@ async function main() {
                 && String(result.payload?.lastError || '') === 'registry-inactive'
                 ? result.payload
                 : null;
-        }, 15000, `registry inactive stop\n${client.details()}`);
+        }, 9000, `registry inactive stop\n${client.details()}`);
+        const finalStatus = await fetchJson(`${client.baseUrl}/api/status`);
+        assert.ok(finalStatus.payload?.remoteRegistryRealtime?.changes >= 2, JSON.stringify(finalStatus.payload?.remoteRegistryRealtime));
+        assert.ok(finalStatus.payload?.remoteRegistryRealtime?.wakeups >= 2, JSON.stringify(finalStatus.payload?.remoteRegistryRealtime));
 
         assert.ok(fakeSupabase.requests.length >= 2, JSON.stringify(fakeSupabase.requests));
         console.log('Remote registry follower smoke OK');

package/server.js

@@ -17,7 +17,7 @@ import multer from 'multer';
 import crypto from 'crypto';
 import sharp from 'sharp';
 import { createServer } from 'http';
-import { WebSocketServer } from 'ws';
+import { WebSocket, WebSocketServer } from 'ws';
 import chokidar from 'chokidar';
 import Parser from 'web-tree-sitter';
 import { fileURLToPath } from 'url';
@@ -3141,6 +3141,11 @@ const REMOTE_REGISTRY_FOLLOWER_ENABLED = !/^(0|false|no|off)$/i.test(String(proc
 const REMOTE_REGISTRY_FOLLOWER_POLL_MS = Math.max(1500, Number(process.env.MINDEXEC_REMOTE_REGISTRY_POLL_MS || 5000) || 5000);
 const REMOTE_REGISTRY_FOLLOWER_FAST_RETRY_MS = Math.max(500, Number(process.env.MINDEXEC_REMOTE_REGISTRY_FAST_RETRY_MS || 1200) || 1200);
 const REMOTE_REGISTRY_FOLLOWER_MISSING_SESSION_STOP_COUNT = 3;
+const REMOTE_REGISTRY_REALTIME_ENABLED = REMOTE_REGISTRY_FOLLOWER_ENABLED
+    && !/^(0|false|no|off)$/i.test(String(process.env.MINDEXEC_REMOTE_REGISTRY_REALTIME || 'true'));
+const REMOTE_REGISTRY_REALTIME_HEARTBEAT_MS = Math.max(10000, Number(process.env.MINDEXEC_REMOTE_REGISTRY_REALTIME_HEARTBEAT_MS || 25000) || 25000);
+const REMOTE_REGISTRY_REALTIME_RECONNECT_MS = Math.max(1000, Number(process.env.MINDEXEC_REMOTE_REGISTRY_REALTIME_RECONNECT_MS || 2500) || 2500);
+const REMOTE_REGISTRY_REALTIME_DEBOUNCE_MS = Math.max(100, Number(process.env.MINDEXEC_REMOTE_REGISTRY_REALTIME_DEBOUNCE_MS || 250) || 250);
 let remoteAgentState = createRemoteAgentIdleState();
 let remoteAgentSyncReportState = null;
 let remoteAgentSyncReportLogKey = '';
@@ -3153,6 +3158,15 @@ let remoteRegistryFollowerTimer = null;
 let remoteRegistryFollowerInFlight = false;
 let remoteRegistryFollowerStarted = false;
 let remoteRegistryFollowerConsecutiveMissingSession = 0;
+let remoteRegistryRealtimeSocket = null;
+let remoteRegistryRealtimeSessionKey = '';
+let remoteRegistryRealtimeTopic = '';
+let remoteRegistryRealtimeJoinRef = '';
+let remoteRegistryRealtimeRef = 0;
+let remoteRegistryRealtimeHeartbeatTimer = null;
+let remoteRegistryRealtimeReconnectTimer = null;
+let remoteRegistryRealtimeReconnectContext = null;
+let remoteRegistryRealtimeLastWakeAt = 0;
 let remoteRegistryFollowerState = {
     enabled: REMOTE_REGISTRY_FOLLOWER_ENABLED,
     status: REMOTE_REGISTRY_FOLLOWER_ENABLED ? 'idle' : 'disabled',
@@ -3166,6 +3180,26 @@ let remoteRegistryFollowerState = {
     targetNodeId: '',
     authenticated: false
 };
+let remoteRegistryRealtimeState = {
+    enabled: REMOTE_REGISTRY_REALTIME_ENABLED,
+    status: REMOTE_REGISTRY_REALTIME_ENABLED ? 'idle' : 'disabled',
+    reason: '',
+    connected: false,
+    subscribed: false,
+    userId: '',
+    topic: '',
+    lastOpenAt: '',
+    lastJoinAt: '',
+    lastMessageAt: '',
+    lastChangeAt: '',
+    lastCloseAt: '',
+    lastErrorAt: '',
+    lastError: '',
+    reconnects: 0,
+    messages: 0,
+    changes: 0,
+    wakeups: 0
+};
 
 function createRemoteAgentIdleState(overrides = {}) {
     return {
@@ -3617,6 +3651,11 @@ function isRemoteAgentProcessRunning() {
         && !proc.killed;
 }
 
+function isRemoteAgentRegistryOwned() {
+    return isRemoteAgentProcessRunning()
+        && /registry/i.test(String(remoteAgentState.source || ''));
+}
+
 function isLocalRemoteHostTargetActive() {
     const status = remoteHub.getStatus({ includeSecrets: false });
     return status?.hostTargetActive === true
@@ -4417,6 +4456,424 @@ function updateRemoteRegistryFollowerState(patch = {}) {
     emitBridgeEvent('RemoteRegistryFollowerUpdated', serializeRemoteRegistryFollowerState());
 }
 
+function serializeRemoteRegistryRealtimeState() {
+    return {
+        ...remoteRegistryRealtimeState,
+        heartbeatMs: REMOTE_REGISTRY_REALTIME_HEARTBEAT_MS,
+        reconnectMs: REMOTE_REGISTRY_REALTIME_RECONNECT_MS,
+        debounceMs: REMOTE_REGISTRY_REALTIME_DEBOUNCE_MS
+    };
+}
+
+function updateRemoteRegistryRealtimeState(patch = {}) {
+    remoteRegistryRealtimeState = {
+        ...remoteRegistryRealtimeState,
+        ...patch,
+        enabled: REMOTE_REGISTRY_REALTIME_ENABLED
+    };
+    emitBridgeEvent('RemoteRegistryRealtimeUpdated', serializeRemoteRegistryRealtimeState());
+}
+
+function clearRemoteRegistryRealtimeTimers() {
+    if (remoteRegistryRealtimeHeartbeatTimer) {
+        clearInterval(remoteRegistryRealtimeHeartbeatTimer);
+        remoteRegistryRealtimeHeartbeatTimer = null;
+    }
+    if (remoteRegistryRealtimeReconnectTimer) {
+        clearTimeout(remoteRegistryRealtimeReconnectTimer);
+        remoteRegistryRealtimeReconnectTimer = null;
+    }
+}
+
+function closeRemoteRegistryRealtime(reason = 'stopped') {
+    clearRemoteRegistryRealtimeTimers();
+    remoteRegistryRealtimeReconnectContext = null;
+    const socket = remoteRegistryRealtimeSocket;
+    remoteRegistryRealtimeSocket = null;
+    remoteRegistryRealtimeSessionKey = '';
+    remoteRegistryRealtimeTopic = '';
+    remoteRegistryRealtimeJoinRef = '';
+
+    if (socket && socket.readyState !== WebSocket.CLOSED && socket.readyState !== WebSocket.CLOSING) {
+        try {
+            socket.close(1000, String(reason || 'stopped').slice(0, 120));
+        } catch {
+            // Best-effort close only.
+        }
+    }
+
+    updateRemoteRegistryRealtimeState({
+        status: REMOTE_REGISTRY_REALTIME_ENABLED ? 'stopped' : 'disabled',
+        reason,
+        connected: false,
+        subscribed: false,
+        userId: '',
+        topic: ''
+    });
+}
+
+function buildRemoteRegistryRealtimeUrl(config) {
+    try {
+        const url = new URL('/realtime/v1/websocket', config.url);
+        url.protocol = url.protocol === 'https:' ? 'wss:' : 'ws:';
+        url.searchParams.set('apikey', config.key);
+        url.searchParams.set('vsn', '1.0.0');
+        return url.toString();
+    } catch {
+        return '';
+    }
+}
+
+function getRemoteRegistryRealtimeSessionKey(config, session) {
+    const tokenHash = crypto
+        .createHash('sha256')
+        .update(String(session?.accessToken || ''))
+        .digest('hex')
+        .slice(0, 16);
+    return [
+        String(config?.url || '').replace(/\/+$/, ''),
+        String(session?.userId || ''),
+        tokenHash
+    ].join('|');
+}
+
+function sendRemoteRegistryRealtimeMessage(socket, topic, event, payload = {}, options = {}) {
+    if (!socket || socket.readyState !== WebSocket.OPEN) {
+        return '';
+    }
+
+    const ref = String(++remoteRegistryRealtimeRef);
+    const message = {
+        topic,
+        event,
+        payload,
+        ref
+    };
+    if (options.joinRef) {
+        message.join_ref = options.joinRef;
+    }
+    socket.send(JSON.stringify(message));
+    return ref;
+}
+
+function sendRemoteRegistryRealtimeHeartbeat(socket) {
+    sendRemoteRegistryRealtimeMessage(socket, 'phoenix', 'heartbeat', {});
+}
+
+function parseRemoteRegistryRealtimeMessage(data) {
+    let raw = data;
+    if (Buffer.isBuffer(raw)) {
+        raw = raw.toString('utf8');
+    }
+    if (ArrayBuffer.isView(raw)) {
+        raw = Buffer.from(raw.buffer, raw.byteOffset, raw.byteLength).toString('utf8');
+    }
+
+    const parsed = JSON.parse(String(raw || '{}'));
+    if (Array.isArray(parsed)) {
+        return {
+            joinRef: parsed[0] ?? '',
+            ref: parsed[1] ?? '',
+            topic: parsed[2] ?? '',
+            event: parsed[3] ?? '',
+            payload: parsed[4] ?? {}
+        };
+    }
+
+    return {
+        joinRef: parsed.join_ref ?? parsed.joinRef ?? '',
+        ref: parsed.ref ?? '',
+        topic: parsed.topic ?? '',
+        event: parsed.event ?? '',
+        payload: parsed.payload ?? {}
+    };
+}
+
+function isRemoteRegistryRealtimeChange(message) {
+    if (!message || message.event !== 'postgres_changes') {
+        return false;
+    }
+
+    const data = message.payload?.data || message.payload;
+    const table = String(data?.table || data?.record?.table || '').trim();
+    const schema = String(data?.schema || data?.record?.schema || 'public').trim();
+    return table === 'remote_host_targets' && (!schema || schema === 'public');
+}
+
+function wakeRemoteRegistryFollowerFromRealtime(reason = 'realtime-change') {
+    const now = Date.now();
+    if (now - remoteRegistryRealtimeLastWakeAt < REMOTE_REGISTRY_REALTIME_DEBOUNCE_MS) {
+        return;
+    }
+
+    remoteRegistryRealtimeLastWakeAt = now;
+    updateRemoteRegistryRealtimeState({
+        wakeups: remoteRegistryRealtimeState.wakeups + 1,
+        lastChangeAt: new Date().toISOString(),
+        reason
+    });
+    wakeRemoteRegistryFollower(reason).catch(error => {
+        updateRemoteRegistryRealtimeState({
+            status: 'error',
+            reason: 'wake-failed',
+            lastError: error?.message || String(error || ''),
+            lastErrorAt: new Date().toISOString()
+        });
+    });
+}
+
+function scheduleRemoteRegistryRealtimeReconnect(reason = 'reconnect') {
+    if (!REMOTE_REGISTRY_REALTIME_ENABLED || isShuttingDown || !remoteRegistryRealtimeReconnectContext) {
+        return;
+    }
+
+    if (remoteRegistryRealtimeReconnectTimer) {
+        return;
+    }
+
+    updateRemoteRegistryRealtimeState({
+        status: 'reconnecting',
+        reason,
+        connected: false,
+        subscribed: false,
+        reconnects: remoteRegistryRealtimeState.reconnects + 1
+    });
+    remoteRegistryRealtimeReconnectTimer = setTimeout(() => {
+        remoteRegistryRealtimeReconnectTimer = null;
+        const context = remoteRegistryRealtimeReconnectContext;
+        if (!context || isShuttingDown) {
+            return;
+        }
+        ensureRemoteRegistryRealtimeSubscription(context.config, context.session, 'realtime-reconnect')
+            .catch(error => {
+                updateRemoteRegistryRealtimeState({
+                    status: 'error',
+                    reason: 'reconnect-failed',
+                    lastError: error?.message || String(error || ''),
+                    lastErrorAt: new Date().toISOString()
+                });
+                scheduleRemoteRegistryRealtimeReconnect('reconnect-failed');
+            });
+    }, REMOTE_REGISTRY_REALTIME_RECONNECT_MS);
+    remoteRegistryRealtimeReconnectTimer?.unref?.();
+}
+
+async function ensureRemoteRegistryRealtimeSubscription(config, session, trigger = 'sync') {
+    if (!REMOTE_REGISTRY_REALTIME_ENABLED) {
+        closeRemoteRegistryRealtime('disabled');
+        return serializeRemoteRegistryRealtimeState();
+    }
+
+    if (!config?.url || !config?.key || !session?.accessToken || !session?.userId) {
+        closeRemoteRegistryRealtime('not-authenticated');
+        return serializeRemoteRegistryRealtimeState();
+    }
+
+    const sessionKey = getRemoteRegistryRealtimeSessionKey(config, session);
+    if (remoteRegistryRealtimeSocket
+        && remoteRegistryRealtimeSessionKey === sessionKey
+        && (remoteRegistryRealtimeSocket.readyState === WebSocket.OPEN
+            || remoteRegistryRealtimeSocket.readyState === WebSocket.CONNECTING)) {
+        return serializeRemoteRegistryRealtimeState();
+    }
+
+    closeRemoteRegistryRealtime('replaced');
+    const wsUrl = buildRemoteRegistryRealtimeUrl(config);
+    if (!wsUrl) {
+        updateRemoteRegistryRealtimeState({
+            status: 'error',
+            reason: 'invalid-realtime-url',
+            lastError: 'invalid-realtime-url',
+            lastErrorAt: new Date().toISOString()
+        });
+        return serializeRemoteRegistryRealtimeState();
+    }
+
+    const topic = `realtime:remote-host-targets-${String(session.userId).replace(/[^a-zA-Z0-9]/g, '') || 'user'}`;
+    const socket = new WebSocket(wsUrl, {
+        headers: {
+            apikey: config.key,
+            Authorization: `Bearer ${session.accessToken}`
+        }
+    });
+
+    remoteRegistryRealtimeSocket = socket;
+    remoteRegistryRealtimeSessionKey = sessionKey;
+    remoteRegistryRealtimeTopic = topic;
+    remoteRegistryRealtimeReconnectContext = {
+        config: { url: config.url, key: config.key },
+        session: {
+            accessToken: session.accessToken,
+            userId: session.userId,
+            expiresAtMs: session.expiresAtMs
+        }
+    };
+
+    updateRemoteRegistryRealtimeState({
+        status: 'connecting',
+        reason: trigger,
+        connected: false,
+        subscribed: false,
+        userId: session.userId,
+        topic,
+        lastError: ''
+    });
+
+    socket.on('open', () => {
+        if (remoteRegistryRealtimeSocket !== socket) {
+            return;
+        }
+
+        const now = new Date().toISOString();
+        remoteRegistryRealtimeJoinRef = String(++remoteRegistryRealtimeRef);
+        updateRemoteRegistryRealtimeState({
+            status: 'joining',
+            reason: 'socket-open',
+            connected: true,
+            subscribed: false,
+            lastOpenAt: now,
+            lastJoinAt: now
+        });
+        socket.send(JSON.stringify({
+            topic,
+            event: 'phx_join',
+            payload: {
+                config: {
+                    broadcast: { ack: false, self: false },
+                    presence: { enabled: false },
+                    postgres_changes: [
+                        {
+                            event: '*',
+                            schema: 'public',
+                            table: 'remote_host_targets',
+                            filter: `user_id=eq.${session.userId}`
+                        }
+                    ],
+                    private: false
+                },
+                access_token: session.accessToken
+            },
+            ref: remoteRegistryRealtimeJoinRef,
+            join_ref: remoteRegistryRealtimeJoinRef
+        }));
+
+        if (remoteRegistryRealtimeHeartbeatTimer) {
+            clearInterval(remoteRegistryRealtimeHeartbeatTimer);
+        }
+        remoteRegistryRealtimeHeartbeatTimer = setInterval(
+            () => sendRemoteRegistryRealtimeHeartbeat(socket),
+            REMOTE_REGISTRY_REALTIME_HEARTBEAT_MS);
+        remoteRegistryRealtimeHeartbeatTimer?.unref?.();
+    });
+
+    socket.on('message', data => {
+        if (remoteRegistryRealtimeSocket !== socket) {
+            return;
+        }
+
+        let message = null;
+        try {
+            message = parseRemoteRegistryRealtimeMessage(data);
+        } catch (error) {
+            updateRemoteRegistryRealtimeState({
+                status: 'error',
+                reason: 'message-parse-failed',
+                lastError: error?.message || String(error || ''),
+                lastErrorAt: new Date().toISOString()
+            });
+            return;
+        }
+
+        updateRemoteRegistryRealtimeState({
+            messages: remoteRegistryRealtimeState.messages + 1,
+            lastMessageAt: new Date().toISOString()
+        });
+
+        if (message.event === 'phx_reply' && message.ref === remoteRegistryRealtimeJoinRef) {
+            const ok = String(message.payload?.status || '').toLowerCase() === 'ok';
+            updateRemoteRegistryRealtimeState({
+                status: ok ? 'subscribed' : 'error',
+                reason: ok ? 'joined' : 'join-failed',
+                subscribed: ok,
+                lastError: ok ? '' : JSON.stringify(message.payload || {}).slice(0, 240),
+                lastErrorAt: ok ? remoteRegistryRealtimeState.lastErrorAt : new Date().toISOString()
+            });
+            return;
+        }
+
+        if (message.event === 'system') {
+            const status = String(message.payload?.status || '').toLowerCase();
+            if (status === 'ok') {
+                updateRemoteRegistryRealtimeState({
+                    status: 'subscribed',
+                    reason: 'system-ok',
+                    subscribed: true
+                });
+            } else if (status === 'error' || status === 'timeout') {
+                updateRemoteRegistryRealtimeState({
+                    status: 'error',
+                    reason: 'system-error',
+                    subscribed: false,
+                    lastError: String(message.payload?.message || status).slice(0, 240),
+                    lastErrorAt: new Date().toISOString()
+                });
+            }
+            return;
+        }
+
+        if (message.event === 'phx_error' || message.event === 'phx_close') {
+            updateRemoteRegistryRealtimeState({
+                status: 'error',
+                reason: message.event,
+                subscribed: false,
+                lastError: message.event,
+                lastErrorAt: new Date().toISOString()
+            });
+            scheduleRemoteRegistryRealtimeReconnect(message.event);
+            return;
+        }
+
+        if (isRemoteRegistryRealtimeChange(message)) {
+            updateRemoteRegistryRealtimeState({
+                changes: remoteRegistryRealtimeState.changes + 1
+            });
+            wakeRemoteRegistryFollowerFromRealtime('realtime-change');
+        }
+    });
+
+    socket.on('close', (code, reasonBuffer) => {
+        if (remoteRegistryRealtimeSocket !== socket) {
+            return;
+        }
+
+        clearRemoteRegistryRealtimeTimers();
+        remoteRegistryRealtimeSocket = null;
+        updateRemoteRegistryRealtimeState({
+            status: 'closed',
+            reason: reasonBuffer?.toString?.() || `close:${code}`,
+            connected: false,
+            subscribed: false,
+            lastCloseAt: new Date().toISOString()
+        });
+        scheduleRemoteRegistryRealtimeReconnect(`close:${code}`);
+    });
+
+    socket.on('error', error => {
+        if (remoteRegistryRealtimeSocket !== socket) {
+            return;
+        }
+
+        updateRemoteRegistryRealtimeState({
+            status: 'error',
+            reason: 'socket-error',
+            lastError: error?.message || String(error || ''),
+            lastErrorAt: new Date().toISOString()
+        });
+    });
+
+    return serializeRemoteRegistryRealtimeState();
+}
+
 function readSupabaseRuntimeConfig() {
     const envUrl = String(process.env.SUPABASE_URL || process.env.MINDEXEC_SUPABASE_URL || '').trim();
     const envKey = String(
@@ -4643,6 +5100,7 @@ async function runRemoteRegistryFollowerOnce(trigger = 'timer') {
     try {
         const config = readSupabaseRuntimeConfig();
         if (!config.url || !config.key) {
+            closeRemoteRegistryRealtime('supabase-config-missing');
             updateRemoteRegistryFollowerState({
                 status: 'skipped',
                 reason: 'supabase-config-missing',
@@ -4664,9 +5122,10 @@ async function runRemoteRegistryFollowerOnce(trigger = 'timer') {
         const sessionPayload = await readStableAuthSessionPayload();
         const session = sessionPayload.found ? parseSupabaseSessionForRegistry(sessionPayload.content) : null;
         if (!session) {
+            closeRemoteRegistryRealtime('registry-not-authenticated');
             remoteRegistryFollowerConsecutiveMissingSession += 1;
             if (remoteRegistryFollowerConsecutiveMissingSession >= REMOTE_REGISTRY_FOLLOWER_MISSING_SESSION_STOP_COUNT
-                && isRemoteAgentProcessRunning()) {
+                && isRemoteAgentRegistryOwned()) {
                 await stopRemoteAgentConnection('registry-not-authenticated');
             }
 
@@ -4694,6 +5153,7 @@ async function runRemoteRegistryFollowerOnce(trigger = 'timer') {
 
         remoteRegistryFollowerConsecutiveMissingSession = 0;
         if (session.expiresAtMs && session.expiresAtMs <= Date.now()) {
+            closeRemoteRegistryRealtime('session-expired');
             updateRemoteRegistryFollowerState({
                 status: 'skipped',
                 reason: 'session-expired',
@@ -4713,6 +5173,7 @@ async function runRemoteRegistryFollowerOnce(trigger = 'timer') {
         }
 
         const localHub = remoteHub.getStatus({ includeSecrets: false });
+        await ensureRemoteRegistryRealtimeSubscription(config, session, trigger);
         const target = await fetchRemoteRegistryTarget(config, session);
 
         if (localHub?.hostTargetActive === true) {
@@ -4779,7 +5240,7 @@ async function runRemoteRegistryFollowerOnce(trigger = 'timer') {
         }
 
         if (!target?.active || isRemoteRegistryTargetExpired(target)) {
-            if (isRemoteAgentProcessRunning()) {
+            if (isRemoteAgentRegistryOwned()) {
                 await stopRemoteAgentConnection('registry-inactive');
             }
             updateRemoteRegistryFollowerState({
@@ -9416,6 +9877,7 @@ app.get('/api/status', async (req, res) => {
         remoteFrameWs: serializeRemoteFrameWsDiagnostics(),
         remoteAgent: serializeRemoteAgentState(),
         remoteRegistryFollower: serializeRemoteRegistryFollowerState(),
+        remoteRegistryRealtime: serializeRemoteRegistryRealtimeState(),
         shellJobsPath: '/api/shell/jobs',
         companyCore: {
             baseUrl: companyCoreBaseUrl,
@@ -11246,6 +11708,12 @@ async function shutdownBridge(signal) {
         // Ignore registry follower shutdown errors
     }
 
+    try {
+        closeRemoteRegistryRealtime('bridge-shutdown');
+    } catch {
+        // Ignore registry realtime shutdown errors
+    }
+
     try {
         await stopRemoteAgentConnection('bridge-shutdown');
     } catch {