@mindexec/cli 0.2.135 → 0.2.137

package/package.json

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

package/scripts/remote-frame-ws-smoke.mjs

@@ -184,6 +184,20 @@ async function main() {
         assert.ok(frame.metadata.frameSeq > 0, 'frameSeq should be positive');
         assert.equal(frame.metadata.mimeType, 'image/png');
         assert.ok(frame.payload.length > 0, 'payload should be non-empty');
+
+        const frameStatus = await fetchJson(`${bridge.baseUrl}/api/status?remoteFrames=ws`);
+        assert.equal(frameStatus.ok, true);
+        assert.ok(frameStatus.payload?.remoteFrameWs?.clientCount >= 1, JSON.stringify(frameStatus.payload?.remoteFrameWs));
+        assert.ok(frameStatus.payload?.remoteFrameWs?.framesSent >= 1, JSON.stringify(frameStatus.payload?.remoteFrameWs));
+        assert.equal(frameStatus.payload?.remoteFrameWs?.lastFrameDeviceId, device.deviceId);
+        assert.equal(frameStatus.payload?.remoteFrameWs?.lastFrameSeq, frame.metadata.frameSeq);
+        assert.ok(
+            frameStatus.payload?.remoteFrameWs?.clients?.some(client =>
+                Array.isArray(client.deviceIds)
+                && client.deviceIds.includes(device.deviceId)
+                && client.autoStartLive === true
+                && client.sent >= 1),
+            JSON.stringify(frameStatus.payload?.remoteFrameWs));
         ws.close();
 
         console.log('Remote frame WebSocket smoke OK');

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';
@@ -2128,6 +2128,35 @@ const remoteFrameWss = new WebSocketServer({ noServer: true });
 const wsClients = new Set();
 const remoteFrameClients = new Set();
 const shellJobs = new Map();
+let remoteFrameClientSeq = 0;
+const remoteFrameWsDiagnostics = {
+    opened: 0,
+    closed: 0,
+    errors: 0,
+    framesReceived: 0,
+    framesSent: 0,
+    framesDropped: 0,
+    framesInvalid: 0,
+    framesNoClients: 0,
+    framesNoSubscribers: 0,
+    autoStartRequested: 0,
+    autoStartStarted: 0,
+    autoStartSkipped: 0,
+    lastOpenAt: '',
+    lastCloseAt: '',
+    lastErrorAt: '',
+    lastFrameAt: '',
+    lastFrameDeviceId: '',
+    lastFrameSeq: 0,
+    lastFrameBytes: 0,
+    lastFrameMatchedClients: 0,
+    lastFrameSentClients: 0,
+    lastFrameDroppedClients: 0,
+    lastAutoStartAt: '',
+    lastAutoStartRequested: 0,
+    lastAutoStartStarted: 0,
+    lastAutoStartSkipped: 0
+};
 const REMOTE_FRAME_WS_AUTO_START_LIMIT = 120;
 const REMOTE_FRAME_WS_DEFAULT_FPS = 12;
 const REMOTE_FRAME_WS_DEFAULT_MAX_WIDTH = 960;
@@ -2308,9 +2337,20 @@ function maybeAutoStartRemoteFrameLiveStreams(ws, deviceIds = []) {
     }
 
     if (started.length > 0 || skipped.length > 0) {
+        const now = new Date().toISOString();
+        ws.remoteFrameLastAutoStartAt = now;
+        ws.remoteFrameLastAutoStartStarted = started.length;
+        ws.remoteFrameLastAutoStartSkipped = skipped.length;
+        remoteFrameWsDiagnostics.autoStartRequested += Math.min(deviceIds.length, REMOTE_FRAME_WS_AUTO_START_LIMIT);
+        remoteFrameWsDiagnostics.autoStartStarted += started.length;
+        remoteFrameWsDiagnostics.autoStartSkipped += skipped.length;
+        remoteFrameWsDiagnostics.lastAutoStartAt = now;
+        remoteFrameWsDiagnostics.lastAutoStartRequested = Math.min(deviceIds.length, REMOTE_FRAME_WS_AUTO_START_LIMIT);
+        remoteFrameWsDiagnostics.lastAutoStartStarted = started.length;
+        remoteFrameWsDiagnostics.lastAutoStartSkipped = skipped.length;
         sendRemoteFrameClientJson(ws, {
             type: 'RemoteFrameLiveAutoStart',
-            timestamp: new Date().toISOString(),
+            timestamp: now,
             requested: Math.min(deviceIds.length, REMOTE_FRAME_WS_AUTO_START_LIMIT),
             started,
             skipped: skipped.slice(0, 24),
@@ -2352,20 +2392,36 @@ function buildRemoteFrameBinaryPacket(frameEvent) {
 }
 
 function broadcastRemoteBinaryFrame(frameEvent) {
+    const frame = frameEvent?.frame || {};
+    remoteFrameWsDiagnostics.framesReceived += 1;
+    remoteFrameWsDiagnostics.lastFrameAt = new Date().toISOString();
+    remoteFrameWsDiagnostics.lastFrameDeviceId = String(frameEvent?.deviceId || frame.deviceId || '').trim();
+    remoteFrameWsDiagnostics.lastFrameSeq = Number(frame.frameSeq || 0) || 0;
+    remoteFrameWsDiagnostics.lastFrameBytes = Number(frameEvent?.byteLength || frameEvent?.payload?.length || 0) || 0;
+    remoteFrameWsDiagnostics.lastFrameMatchedClients = 0;
+    remoteFrameWsDiagnostics.lastFrameSentClients = 0;
+    remoteFrameWsDiagnostics.lastFrameDroppedClients = 0;
+
     if (remoteFrameClients.size === 0) {
+        remoteFrameWsDiagnostics.framesNoClients += 1;
         return;
     }
 
-    const deviceId = String(frameEvent?.deviceId || frameEvent?.frame?.deviceId || '').trim();
+    const deviceId = remoteFrameWsDiagnostics.lastFrameDeviceId;
     if (!deviceId) {
+        remoteFrameWsDiagnostics.framesInvalid += 1;
         return;
     }
 
     const packet = buildRemoteFrameBinaryPacket(frameEvent);
     if (!packet) {
+        remoteFrameWsDiagnostics.framesInvalid += 1;
         return;
     }
 
+    let matched = 0;
+    let sent = 0;
+    let dropped = 0;
     for (const client of remoteFrameClients) {
         if (client.readyState !== 1) {
             continue;
@@ -2376,23 +2432,85 @@ function broadcastRemoteBinaryFrame(frameEvent) {
             continue;
         }
 
+        matched += 1;
         if (client.bufferedAmount > 8 * 1024 * 1024) {
             client.remoteFrameDroppedCount = (client.remoteFrameDroppedCount || 0) + 1;
+            client.remoteFrameLastDropAt = new Date().toISOString();
+            remoteFrameWsDiagnostics.framesDropped += 1;
+            dropped += 1;
             continue;
         }
 
         try {
             client.send(packet, { binary: true });
             client.remoteFrameSentCount = (client.remoteFrameSentCount || 0) + 1;
+            client.remoteFrameLastSentAt = new Date().toISOString();
+            client.remoteFrameLastDeviceId = deviceId;
+            client.remoteFrameLastSeq = remoteFrameWsDiagnostics.lastFrameSeq;
+            remoteFrameWsDiagnostics.framesSent += 1;
+            sent += 1;
         } catch {
             client.remoteFrameDroppedCount = (client.remoteFrameDroppedCount || 0) + 1;
+            client.remoteFrameLastDropAt = new Date().toISOString();
+            remoteFrameWsDiagnostics.framesDropped += 1;
+            dropped += 1;
         }
     }
+
+    remoteFrameWsDiagnostics.lastFrameMatchedClients = matched;
+    remoteFrameWsDiagnostics.lastFrameSentClients = sent;
+    remoteFrameWsDiagnostics.lastFrameDroppedClients = dropped;
+    if (matched === 0) {
+        remoteFrameWsDiagnostics.framesNoSubscribers += 1;
+    }
+}
+
+function serializeRemoteFrameWsDiagnostics() {
+    const clients = [];
+    for (const client of remoteFrameClients) {
+        const deviceIds = client.remoteFrameDeviceIds instanceof Set
+            ? Array.from(client.remoteFrameDeviceIds)
+            : [];
+        clients.push({
+            id: client.remoteFrameClientId || '',
+            readyState: client.readyState,
+            connectedAt: client.remoteFrameConnectedAt || '',
+            subscribedAt: client.remoteFrameSubscriptionUpdatedAt || '',
+            deviceCount: deviceIds.length,
+            deviceIds: deviceIds.slice(0, 24),
+            autoStartLive: client.remoteFrameAutoStartLive === true,
+            autoStartOptions: client.remoteFrameAutoStartOptions || null,
+            sent: Number(client.remoteFrameSentCount || 0),
+            dropped: Number(client.remoteFrameDroppedCount || 0),
+            bufferedAmount: Number(client.bufferedAmount || 0),
+            lastSentAt: client.remoteFrameLastSentAt || '',
+            lastDropAt: client.remoteFrameLastDropAt || '',
+            lastDeviceId: client.remoteFrameLastDeviceId || '',
+            lastFrameSeq: Number(client.remoteFrameLastSeq || 0) || 0,
+            lastAutoStartAt: client.remoteFrameLastAutoStartAt || '',
+            lastAutoStartStarted: Number(client.remoteFrameLastAutoStartStarted || 0),
+            lastAutoStartSkipped: Number(client.remoteFrameLastAutoStartSkipped || 0)
+        });
+    }
+
+    return {
+        protocol: 'mindexec.remote.frames.binary.v1',
+        path: '/api/remote/frames/ws',
+        clientCount: remoteFrameClients.size,
+        ...remoteFrameWsDiagnostics,
+        clients
+    };
 }
 
 remoteFrameWss.on('connection', (ws, req) => {
     remoteFrameClients.add(ws);
     ws.binaryType = 'arraybuffer';
+    ws.remoteFrameClientId = `rfws-${++remoteFrameClientSeq}`;
+    ws.remoteFrameConnectedAt = new Date().toISOString();
+    ws.remoteFrameSentCount = 0;
+    ws.remoteFrameDroppedCount = 0;
+    remoteFrameWsDiagnostics.opened += 1;
+    remoteFrameWsDiagnostics.lastOpenAt = ws.remoteFrameConnectedAt;
     try {
         const parsed = new URL(req.url || '/', `http://${req.headers.host || '127.0.0.1'}`);
         updateRemoteFrameClientSubscription(ws, {
@@ -2416,12 +2534,21 @@ remoteFrameWss.on('connection', (ws, req) => {
             });
         }
     });
-    ws.on('close', () => remoteFrameClients.delete(ws));
-    ws.on('error', () => remoteFrameClients.delete(ws));
+    ws.on('close', () => {
+        remoteFrameClients.delete(ws);
+        remoteFrameWsDiagnostics.closed += 1;
+        remoteFrameWsDiagnostics.lastCloseAt = new Date().toISOString();
+    });
+    ws.on('error', () => {
+        remoteFrameClients.delete(ws);
+        remoteFrameWsDiagnostics.errors += 1;
+        remoteFrameWsDiagnostics.lastErrorAt = new Date().toISOString();
+    });
     sendRemoteFrameClientJson(ws, {
         type: 'RemoteFrameSocketReady',
         timestamp: new Date().toISOString(),
-        protocol: 'mindexec.remote.frames.binary.v1'
+        protocol: 'mindexec.remote.frames.binary.v1',
+        clientId: ws.remoteFrameClientId
     });
 });
 
@@ -3014,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 = '';
@@ -3026,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',
@@ -3039,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 {
@@ -3490,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
@@ -4290,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(
@@ -4516,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',
@@ -4537,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');
             }
 
@@ -4567,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',
@@ -4586,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) {
@@ -4652,7 +5240,7 @@ async function runRemoteRegistryFollowerOnce(trigger = 'timer') {
         }
 
         if (!target?.active || isRemoteRegistryTargetExpired(target)) {
-            if (isRemoteAgentProcessRunning()) {
+            if (isRemoteAgentRegistryOwned()) {
                 await stopRemoteAgentConnection('registry-inactive');
             }
             updateRemoteRegistryFollowerState({
@@ -9286,8 +9874,10 @@ app.get('/api/status', async (req, res) => {
         bridgeTokenHeader,
         bridgeAuthRequired,
         remoteHub: remoteHub.getStatus({ includeSecrets: false }),
+        remoteFrameWs: serializeRemoteFrameWsDiagnostics(),
         remoteAgent: serializeRemoteAgentState(),
         remoteRegistryFollower: serializeRemoteRegistryFollowerState(),
+        remoteRegistryRealtime: serializeRemoteRegistryRealtimeState(),
         shellJobsPath: '/api/shell/jobs',
         companyCore: {
             baseUrl: companyCoreBaseUrl,
@@ -11118,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 {