@mindexec/cli 0.2.133 → 0.2.135

package/server.js

@@ -41,7 +41,7 @@ const VERBOSE_CODEX_TRACE = /^(1|true|yes|on)$/i.test(String(process.env.BRIDGE_
 const COLOR_LOGS_ENABLED = Boolean(process.stdout.isTTY) && !process.env.NO_COLOR;
 const DEFAULT_WEB_APP_ROOT = path.join(BRIDGE_ROOT, 'wwwroot');
 
-const ANSI = {
+const ANSI = {
     reset: '\x1b[0m',
     bold: '\x1b[1m',
     dim: '\x1b[2m',
@@ -52,8 +52,10 @@ const ANSI = {
     blue: '\x1b[34m',
     magenta: '\x1b[35m',
     cyan: '\x1b[36m',
-    white: '\x1b[37m'
-};
+    white: '\x1b[37m'
+};
+
+let isShuttingDown = false;
 
 function paint(text, ...styles) {
     const value = String(text ?? '');
@@ -2042,6 +2044,7 @@ app.post('/api/auth/session', async (req, res) => {
     try {
         const content = req.body?.content;
         await writeStableAuthSessionPayload(content);
+        await wakeRemoteRegistryFollower('auth-session-saved');
         res.json({
             success: true
         });
@@ -2058,6 +2061,7 @@ app.post('/api/auth/session', async (req, res) => {
 app.delete('/api/auth/session', async (req, res) => {
     try {
         await deleteStableAuthSessionPayload();
+        await wakeRemoteRegistryFollower('auth-session-cleared');
         res.json({
             success: true
         });
@@ -2124,6 +2128,11 @@ const remoteFrameWss = new WebSocketServer({ noServer: true });
 const wsClients = new Set();
 const remoteFrameClients = new Set();
 const shellJobs = new Map();
+const REMOTE_FRAME_WS_AUTO_START_LIMIT = 120;
+const REMOTE_FRAME_WS_DEFAULT_FPS = 12;
+const REMOTE_FRAME_WS_DEFAULT_MAX_WIDTH = 960;
+const REMOTE_FRAME_WS_DEFAULT_MAX_HEIGHT = 540;
+const REMOTE_FRAME_WS_DEFAULT_QUALITY = 60;
 
 httpServer.on('upgrade', (req, socket, head) => {
     try {
@@ -2213,12 +2222,101 @@ function updateRemoteFrameClientSubscription(ws, payload = {}) {
     const deviceIds = normalizeRemoteFrameWsDeviceIds(payload.deviceIds ?? payload.devices ?? payload.deviceId);
     ws.remoteFrameDeviceIds = new Set(deviceIds);
     ws.remoteFrameSubscriptionUpdatedAt = new Date().toISOString();
+    ws.remoteFrameAutoStartLive = /^(1|true|yes|on|live)$/i.test(String(payload.autoStartLive ?? payload.startLive ?? ''));
+    ws.remoteFrameAutoStartOptions = normalizeRemoteFrameWsLiveOptions(payload);
     sendRemoteFrameClientJson(ws, {
         type: 'RemoteFrameSubscription',
         timestamp: ws.remoteFrameSubscriptionUpdatedAt,
         deviceIds,
-        mode: deviceIds.length > 0 ? 'selected-devices' : 'all-devices'
+        mode: deviceIds.length > 0 ? 'selected-devices' : 'all-devices',
+        autoStartLive: ws.remoteFrameAutoStartLive === true
     });
+    maybeAutoStartRemoteFrameLiveStreams(ws, deviceIds);
+}
+
+function clampRemoteFrameWsNumber(value, min, max, fallback) {
+    const number = Number(value);
+    if (!Number.isFinite(number)) {
+        return fallback;
+    }
+
+    return Math.max(min, Math.min(max, Math.round(number)));
+}
+
+function normalizeRemoteFrameWsLiveOptions(payload = {}) {
+    return {
+        fps: clampRemoteFrameWsNumber(payload.fps, 1, 24, REMOTE_FRAME_WS_DEFAULT_FPS),
+        maxWidth: clampRemoteFrameWsNumber(payload.maxWidth, 320, 2560, REMOTE_FRAME_WS_DEFAULT_MAX_WIDTH),
+        maxHeight: clampRemoteFrameWsNumber(payload.maxHeight, 180, 1440, REMOTE_FRAME_WS_DEFAULT_MAX_HEIGHT),
+        quality: clampRemoteFrameWsNumber(payload.quality, 20, 95, REMOTE_FRAME_WS_DEFAULT_QUALITY),
+        mode: String(payload.mode || 'remote-fast').trim() || 'remote-fast'
+    };
+}
+
+function getRemoteFrameWsDeviceLookup() {
+    const devices = remoteHub.listDevices({ includeDataUrl: false });
+    return new Map(devices.map(device => [String(device?.deviceId || '').trim(), device]).filter(([id]) => id));
+}
+
+function maybeAutoStartRemoteFrameLiveStreams(ws, deviceIds = []) {
+    if (!ws || ws.remoteFrameAutoStartLive !== true || !Array.isArray(deviceIds) || deviceIds.length === 0) {
+        return;
+    }
+
+    const options = ws.remoteFrameAutoStartOptions || normalizeRemoteFrameWsLiveOptions();
+    const lookup = getRemoteFrameWsDeviceLookup();
+    const started = [];
+    const skipped = [];
+    for (const deviceId of deviceIds.slice(0, REMOTE_FRAME_WS_AUTO_START_LIMIT)) {
+        const device = lookup.get(String(deviceId || '').trim());
+        if (!device?.connected) {
+            skipped.push({ deviceId, reason: 'not-connected' });
+            continue;
+        }
+
+        if (device.liveStreamActive === true) {
+            skipped.push({ deviceId, reason: 'already-live' });
+            continue;
+        }
+
+        const liveCapable = device.liveStreamEnabled === true
+            || device.liveStreamCapable === true
+            || device.capabilities?.liveStream === true
+            || device.capabilities?.stream === true
+            || device.capabilities?.screenStream === true;
+        if (!liveCapable) {
+            skipped.push({ deviceId, reason: 'live-unavailable' });
+            continue;
+        }
+
+        const result = remoteHub.startLiveStream(deviceId, {
+            ...options,
+            streamId: `mdm-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`
+        });
+        if (result?.ok === true) {
+            started.push({
+                deviceId,
+                streamId: result.streamId || '',
+                fps: result.fps || options.fps
+            });
+        } else {
+            skipped.push({
+                deviceId,
+                reason: result?.error || 'start-failed'
+            });
+        }
+    }
+
+    if (started.length > 0 || skipped.length > 0) {
+        sendRemoteFrameClientJson(ws, {
+            type: 'RemoteFrameLiveAutoStart',
+            timestamp: new Date().toISOString(),
+            requested: Math.min(deviceIds.length, REMOTE_FRAME_WS_AUTO_START_LIMIT),
+            started,
+            skipped: skipped.slice(0, 24),
+            options
+        });
+    }
 }
 
 function buildRemoteFrameBinaryPacket(frameEvent) {
@@ -2912,6 +3010,10 @@ const REMOTE_AGENT_MAX_PARALLEL_CANDIDATES = 6;
 const REMOTE_AGENT_RECENT_MANAGER_CACHE_TTL_MS = 30 * 24 * 60 * 60 * 1000;
 const REMOTE_AGENT_RECENT_MANAGER_CACHE_LIMIT = 64;
 const REMOTE_AGENT_RECENT_MANAGER_DEFAULT_KEY = 'default';
+const REMOTE_REGISTRY_FOLLOWER_ENABLED = !/^(0|false|no|off)$/i.test(String(process.env.MINDEXEC_REMOTE_REGISTRY_FOLLOWER || 'true'));
+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;
 let remoteAgentState = createRemoteAgentIdleState();
 let remoteAgentSyncReportState = null;
 let remoteAgentSyncReportLogKey = '';
@@ -2920,6 +3022,23 @@ let remoteAgentConnectPromise = null;
 const remoteAgentRecentSuccessfulManagers = new Map();
 let remoteAgentRecentSuccessfulManagersLoaded = false;
 let remoteAgentRecentSuccessfulManagersSavePromise = null;
+let remoteRegistryFollowerTimer = null;
+let remoteRegistryFollowerInFlight = false;
+let remoteRegistryFollowerStarted = false;
+let remoteRegistryFollowerConsecutiveMissingSession = 0;
+let remoteRegistryFollowerState = {
+    enabled: REMOTE_REGISTRY_FOLLOWER_ENABLED,
+    status: REMOTE_REGISTRY_FOLLOWER_ENABLED ? 'idle' : 'disabled',
+    reason: '',
+    lastAttemptAt: '',
+    lastSuccessAt: '',
+    lastError: '',
+    targetEndpoint: '',
+    targetEndpointCandidates: [],
+    targetLeaseId: '',
+    targetNodeId: '',
+    authenticated: false
+};
 
 function createRemoteAgentIdleState(overrides = {}) {
     return {
@@ -4154,11 +4273,569 @@ async function startRemoteAgentConnectionAttempt(options = {}) {
     return { ok: true, alreadyRunning: false, agent: serializeRemoteAgentState() };
 }
 
+function serializeRemoteRegistryFollowerState() {
+    return {
+        ...remoteRegistryFollowerState,
+        pollMs: REMOTE_REGISTRY_FOLLOWER_POLL_MS,
+        fastRetryMs: REMOTE_REGISTRY_FOLLOWER_FAST_RETRY_MS
+    };
+}
+
+function updateRemoteRegistryFollowerState(patch = {}) {
+    remoteRegistryFollowerState = {
+        ...remoteRegistryFollowerState,
+        ...patch,
+        enabled: REMOTE_REGISTRY_FOLLOWER_ENABLED
+    };
+    emitBridgeEvent('RemoteRegistryFollowerUpdated', serializeRemoteRegistryFollowerState());
+}
+
+function readSupabaseRuntimeConfig() {
+    const envUrl = String(process.env.SUPABASE_URL || process.env.MINDEXEC_SUPABASE_URL || '').trim();
+    const envKey = String(
+        process.env.SUPABASE_KEY
+        || process.env.SUPABASE_ANON_KEY
+        || process.env.SUPABASE_PUBLISHABLE_KEY
+        || process.env.MINDEXEC_SUPABASE_KEY
+        || '').trim();
+    if (envUrl && envKey) {
+        return { url: envUrl.replace(/\/+$/, ''), key: envKey };
+    }
+
+    const candidates = [
+        path.join(WEB_APP_ROOT || '', 'appsettings.json'),
+        path.join(DEFAULT_WEB_APP_ROOT, 'appsettings.json'),
+        path.resolve(BRIDGE_ROOT, '..', 'MindExecution.Web', 'wwwroot', 'appsettings.json')
+    ].filter(Boolean);
+
+    for (const candidate of Array.from(new Set(candidates.map(item => path.resolve(item))))) {
+        try {
+            const payload = JSON.parse(readFileSync(candidate, 'utf8'));
+            const url = String(payload?.Supabase?.Url || '').trim().replace(/\/+$/, '');
+            const key = String(payload?.Supabase?.Key || payload?.Supabase?.AnonKey || payload?.Supabase?.PublishableKey || '').trim();
+            if (url && key) {
+                return { url, key };
+            }
+        } catch {
+            // Try the next appsettings candidate.
+        }
+    }
+
+    return { url: '', key: '' };
+}
+
+function readSupabaseSessionField(source, ...keys) {
+    for (const key of keys) {
+        const value = source?.[key];
+        if (value !== undefined && value !== null && String(value).trim()) {
+            return value;
+        }
+    }
+    return '';
+}
+
+function parseSupabaseSessionForRegistry(content) {
+    let session = null;
+    try {
+        session = JSON.parse(String(content || ''));
+    } catch {
+        return null;
+    }
+
+    const user = session?.user || session?.User || {};
+    const accessToken = String(readSupabaseSessionField(session, 'access_token', 'accessToken', 'AccessToken')).trim();
+    const userId = String(
+        readSupabaseSessionField(user, 'id', 'Id')
+        || readSupabaseSessionField(session, 'user_id', 'userId', 'UserId')).trim();
+    const expiresAtRaw = Number(readSupabaseSessionField(session, 'expires_at', 'expiresAt', 'ExpiresAt') || 0);
+    const expiresAtMs = Number.isFinite(expiresAtRaw) && expiresAtRaw > 0
+        ? (expiresAtRaw > 9999999999 ? expiresAtRaw : expiresAtRaw * 1000)
+        : 0;
+
+    if (!accessToken || !userId) {
+        return null;
+    }
+
+    return {
+        accessToken,
+        userId,
+        expiresAtMs
+    };
+}
+
+function readRegistryTargetField(target, ...keys) {
+    for (const key of keys) {
+        const value = target?.[key];
+        if (value !== undefined && value !== null) {
+            return value;
+        }
+    }
+    return '';
+}
+
+function parseRegistryEndpointCandidates(value) {
+    if (Array.isArray(value)) {
+        return value.map(item => String(item || '').trim()).filter(Boolean);
+    }
+
+    const text = String(value || '').trim();
+    if (!text) {
+        return [];
+    }
+
+    try {
+        const parsed = JSON.parse(text);
+        if (Array.isArray(parsed)) {
+            return parsed.map(item => String(item || '').trim()).filter(Boolean);
+        }
+    } catch {
+        // Fall through to comma/newline split.
+    }
+
+    return text.split(/[,\n]/g).map(item => item.trim()).filter(Boolean);
+}
+
+function normalizeRemoteRegistryTarget(row) {
+    if (!row || typeof row !== 'object') {
+        return null;
+    }
+
+    const activeRaw = readRegistryTargetField(row, 'active', 'Active');
+    const active = activeRaw === true || /^(1|true|yes|on)$/i.test(String(activeRaw || ''));
+    const endpoint = String(readRegistryTargetField(row, 'endpoint', 'Endpoint') || '').trim();
+    const endpointCandidates = normalizeRemoteManagerEndpointList(
+        parseRegistryEndpointCandidates(readRegistryTargetField(row, 'endpoint_candidates', 'endpointCandidates', 'EndpointCandidates')),
+        endpoint);
+    const pairToken = String(readRegistryTargetField(row, 'pair_token', 'pairToken', 'PairToken') || '').trim();
+    const leaseId = String(readRegistryTargetField(row, 'lease_id', 'leaseId', 'LeaseId') || '').trim();
+    const nodeId = String(readRegistryTargetField(row, 'node_id', 'nodeId', 'NodeId') || '').trim();
+    const hostInstanceId = String(readRegistryTargetField(row, 'host_instance_id', 'hostInstanceId', 'HostInstanceId') || '').trim();
+    const expiresAt = String(readRegistryTargetField(row, 'expires_at', 'expiresAt', 'ExpiresAt') || '').trim();
+    const expiresAtMs = Date.parse(expiresAt);
+
+    return {
+        active,
+        endpoint,
+        endpointCandidates,
+        pairToken,
+        leaseId,
+        nodeId,
+        hostInstanceId,
+        expiresAt,
+        expiresAtMs: Number.isFinite(expiresAtMs) ? expiresAtMs : 0
+    };
+}
+
+function isRemoteRegistryTargetExpired(target) {
+    return !target?.expiresAtMs || target.expiresAtMs <= Date.now();
+}
+
+function isRemoteRegistryTargetSameAsLocalHost(localHub, target) {
+    const localLeaseId = safeRemoteAgentField(localHub?.hostTargetLeaseId, 128);
+    const localHostInstanceId = safeRemoteAgentField(localHub?.hostTargetHostInstanceId || localHub?.hostInstanceId, 128);
+    return !!localLeaseId
+        && !!localHostInstanceId
+        && !!target?.leaseId
+        && !!target?.hostInstanceId
+        && localLeaseId.toLowerCase() === String(target.leaseId).toLowerCase()
+        && localHostInstanceId.toLowerCase() === String(target.hostInstanceId).toLowerCase();
+}
+
+async function fetchRemoteRegistryTarget(config, session) {
+    const url = new URL('/rest/v1/remote_host_targets', config.url);
+    url.searchParams.set('select', '*');
+    url.searchParams.set('user_id', `eq.${session.userId}`);
+    url.searchParams.set('limit', '1');
+
+    const response = await fetch(url.toString(), {
+        method: 'GET',
+        headers: {
+            apikey: config.key,
+            Authorization: `Bearer ${session.accessToken}`,
+            Accept: 'application/json'
+        }
+    });
+
+    if (!response.ok) {
+        const text = await response.text().catch(() => '');
+        const error = new Error(`registry-rest-${response.status}${text ? `:${shortenText(text, 160)}` : ''}`);
+        error.statusCode = response.status;
+        throw error;
+    }
+
+    const payload = await response.json();
+    return normalizeRemoteRegistryTarget(Array.isArray(payload) ? payload[0] : payload);
+}
+
+async function reportRemoteRegistryFollowerSync(payload = {}) {
+    const report = createRemoteAgentSyncReport(payload);
+    rememberRemoteAgentSyncReport(report);
+    return report;
+}
+
+function scheduleRemoteRegistryFollower(delayMs = REMOTE_REGISTRY_FOLLOWER_POLL_MS, reason = 'timer') {
+    if (!REMOTE_REGISTRY_FOLLOWER_ENABLED || isShuttingDown) {
+        return;
+    }
+
+    if (remoteRegistryFollowerTimer) {
+        clearTimeout(remoteRegistryFollowerTimer);
+        remoteRegistryFollowerTimer = null;
+    }
+
+    remoteRegistryFollowerTimer = setTimeout(() => {
+        remoteRegistryFollowerTimer = null;
+        runRemoteRegistryFollowerOnce(reason).catch(error => {
+            logWarn('remote', `registry follower failed: ${error?.message || error}`);
+            updateRemoteRegistryFollowerState({
+                status: 'error',
+                reason: 'follower-error',
+                lastError: error?.message || String(error || ''),
+                lastAttemptAt: new Date().toISOString()
+            });
+            scheduleRemoteRegistryFollower(REMOTE_REGISTRY_FOLLOWER_FAST_RETRY_MS, 'error-retry');
+        });
+    }, Math.max(0, Number(delayMs) || 0));
+    remoteRegistryFollowerTimer?.unref?.();
+}
+
+async function wakeRemoteRegistryFollower(reason = 'wake') {
+    if (!REMOTE_REGISTRY_FOLLOWER_ENABLED) {
+        return;
+    }
+    scheduleRemoteRegistryFollower(0, reason);
+}
+
+async function runRemoteRegistryFollowerOnce(trigger = 'timer') {
+    if (!REMOTE_REGISTRY_FOLLOWER_ENABLED || remoteRegistryFollowerInFlight) {
+        return serializeRemoteRegistryFollowerState();
+    }
+
+    remoteRegistryFollowerInFlight = true;
+    const attemptedAt = new Date().toISOString();
+    try {
+        const config = readSupabaseRuntimeConfig();
+        if (!config.url || !config.key) {
+            updateRemoteRegistryFollowerState({
+                status: 'skipped',
+                reason: 'supabase-config-missing',
+                authenticated: false,
+                lastAttemptAt: attemptedAt,
+                lastError: ''
+            });
+            await reportRemoteRegistryFollowerSync({
+                ok: false,
+                skipped: true,
+                reason: 'supabase-config-missing',
+                trigger,
+                authenticated: false
+            });
+            scheduleRemoteRegistryFollower(REMOTE_REGISTRY_FOLLOWER_POLL_MS, 'config-missing');
+            return serializeRemoteRegistryFollowerState();
+        }
+
+        const sessionPayload = await readStableAuthSessionPayload();
+        const session = sessionPayload.found ? parseSupabaseSessionForRegistry(sessionPayload.content) : null;
+        if (!session) {
+            remoteRegistryFollowerConsecutiveMissingSession += 1;
+            if (remoteRegistryFollowerConsecutiveMissingSession >= REMOTE_REGISTRY_FOLLOWER_MISSING_SESSION_STOP_COUNT
+                && isRemoteAgentProcessRunning()) {
+                await stopRemoteAgentConnection('registry-not-authenticated');
+            }
+
+            updateRemoteRegistryFollowerState({
+                status: 'skipped',
+                reason: 'registry-not-authenticated',
+                authenticated: false,
+                lastAttemptAt: attemptedAt,
+                lastError: '',
+                targetEndpoint: '',
+                targetEndpointCandidates: [],
+                targetLeaseId: '',
+                targetNodeId: ''
+            });
+            await reportRemoteRegistryFollowerSync({
+                ok: true,
+                skipped: true,
+                reason: 'registry-not-authenticated',
+                trigger,
+                authenticated: false
+            });
+            scheduleRemoteRegistryFollower(REMOTE_REGISTRY_FOLLOWER_POLL_MS, 'auth-missing');
+            return serializeRemoteRegistryFollowerState();
+        }
+
+        remoteRegistryFollowerConsecutiveMissingSession = 0;
+        if (session.expiresAtMs && session.expiresAtMs <= Date.now()) {
+            updateRemoteRegistryFollowerState({
+                status: 'skipped',
+                reason: 'session-expired',
+                authenticated: false,
+                lastAttemptAt: attemptedAt,
+                lastError: ''
+            });
+            await reportRemoteRegistryFollowerSync({
+                ok: true,
+                skipped: true,
+                reason: 'session-expired',
+                trigger,
+                authenticated: false
+            });
+            scheduleRemoteRegistryFollower(REMOTE_REGISTRY_FOLLOWER_POLL_MS, 'session-expired');
+            return serializeRemoteRegistryFollowerState();
+        }
+
+        const localHub = remoteHub.getStatus({ includeSecrets: false });
+        const target = await fetchRemoteRegistryTarget(config, session);
+
+        if (localHub?.hostTargetActive === true) {
+            if (target?.active === true
+                && !isRemoteRegistryTargetExpired(target)
+                && !isRemoteRegistryTargetSameAsLocalHost(localHub, target)) {
+                remoteHub.setHostTarget({
+                    enabled: false,
+                    nodeId: localHub.hostTargetNodeId
+                });
+                updateRemoteRegistryFollowerState({
+                    status: 'local-host-superseded',
+                    reason: 'local-host-superseded',
+                    authenticated: true,
+                    lastAttemptAt: attemptedAt,
+                    lastSuccessAt: attemptedAt,
+                    targetEndpoint: target.endpoint,
+                    targetEndpointCandidates: target.endpointCandidates,
+                    targetLeaseId: target.leaseId,
+                    targetNodeId: target.nodeId,
+                    lastError: ''
+                });
+                await reportRemoteRegistryFollowerSync({
+                    ok: true,
+                    attempted: true,
+                    disconnected: true,
+                    reason: 'local-host-superseded',
+                    trigger,
+                    authenticated: true,
+                    targetActive: true,
+                    targetEndpoint: target.endpoint,
+                    targetEndpointCandidates: target.endpointCandidates,
+                    targetLeaseId: target.leaseId,
+                    targetNodeId: target.nodeId,
+                    targetExpiresAt: target.expiresAt
+                });
+                scheduleRemoteRegistryFollower(REMOTE_REGISTRY_FOLLOWER_FAST_RETRY_MS, 'local-host-cleared');
+                return serializeRemoteRegistryFollowerState();
+            }
+
+            if (isRemoteAgentProcessRunning()) {
+                await stopRemoteAgentConnection('local-host-target-active');
+            }
+            updateRemoteRegistryFollowerState({
+                status: 'skipped',
+                reason: 'local-monitor-is-host',
+                authenticated: true,
+                lastAttemptAt: attemptedAt,
+                lastSuccessAt: attemptedAt,
+                lastError: ''
+            });
+            await reportRemoteRegistryFollowerSync({
+                ok: true,
+                skipped: true,
+                reason: 'local-monitor-is-host',
+                trigger,
+                authenticated: true,
+                localHostTargetActive: true,
+                localHostTargetLeaseId: localHub.hostTargetLeaseId,
+                localHostTargetNodeId: localHub.hostTargetNodeId
+            });
+            scheduleRemoteRegistryFollower(REMOTE_REGISTRY_FOLLOWER_POLL_MS, 'local-host');
+            return serializeRemoteRegistryFollowerState();
+        }
+
+        if (!target?.active || isRemoteRegistryTargetExpired(target)) {
+            if (isRemoteAgentProcessRunning()) {
+                await stopRemoteAgentConnection('registry-inactive');
+            }
+            updateRemoteRegistryFollowerState({
+                status: 'idle',
+                reason: 'no-active-target',
+                authenticated: true,
+                lastAttemptAt: attemptedAt,
+                lastSuccessAt: attemptedAt,
+                targetEndpoint: '',
+                targetEndpointCandidates: [],
+                targetLeaseId: '',
+                targetNodeId: '',
+                lastError: ''
+            });
+            await reportRemoteRegistryFollowerSync({
+                ok: true,
+                skipped: true,
+                reason: 'no-active-target',
+                trigger,
+                authenticated: true
+            });
+            scheduleRemoteRegistryFollower(REMOTE_REGISTRY_FOLLOWER_POLL_MS, 'no-target');
+            return serializeRemoteRegistryFollowerState();
+        }
+
+        if (isRemoteRegistryTargetSameAsLocalHost(localHub, target)) {
+            updateRemoteRegistryFollowerState({
+                status: 'skipped',
+                reason: 'same-host-lease',
+                authenticated: true,
+                lastAttemptAt: attemptedAt,
+                lastSuccessAt: attemptedAt,
+                targetEndpoint: target.endpoint,
+                targetEndpointCandidates: target.endpointCandidates,
+                targetLeaseId: target.leaseId,
+                targetNodeId: target.nodeId,
+                lastError: ''
+            });
+            await reportRemoteRegistryFollowerSync({
+                ok: true,
+                skipped: true,
+                reason: 'same-host-lease',
+                trigger,
+                authenticated: true,
+                targetActive: true,
+                targetEndpoint: target.endpoint,
+                targetEndpointCandidates: target.endpointCandidates,
+                targetLeaseId: target.leaseId,
+                targetNodeId: target.nodeId,
+                targetExpiresAt: target.expiresAt
+            });
+            scheduleRemoteRegistryFollower(REMOTE_REGISTRY_FOLLOWER_POLL_MS, 'same-host');
+            return serializeRemoteRegistryFollowerState();
+        }
+
+        if (target.endpointCandidates.length === 0 || !target.pairToken) {
+            updateRemoteRegistryFollowerState({
+                status: 'skipped',
+                reason: 'target-missing-endpoint-or-pair',
+                authenticated: true,
+                lastAttemptAt: attemptedAt,
+                lastSuccessAt: attemptedAt,
+                targetEndpoint: target.endpoint,
+                targetEndpointCandidates: target.endpointCandidates,
+                targetLeaseId: target.leaseId,
+                targetNodeId: target.nodeId,
+                lastError: ''
+            });
+            await reportRemoteRegistryFollowerSync({
+                ok: true,
+                skipped: true,
+                reason: 'target-missing-endpoint-or-pair',
+                trigger,
+                authenticated: true,
+                targetActive: true,
+                targetEndpoint: target.endpoint,
+                targetEndpointCandidates: target.endpointCandidates,
+                targetLeaseId: target.leaseId,
+                targetNodeId: target.nodeId,
+                targetExpiresAt: target.expiresAt
+            });
+            scheduleRemoteRegistryFollower(REMOTE_REGISTRY_FOLLOWER_POLL_MS, 'target-incomplete');
+            return serializeRemoteRegistryFollowerState();
+        }
+
+        const connect = await startRemoteAgentConnection({
+            manager: target.endpointCandidates[0],
+            managerCandidates: target.endpointCandidates,
+            pairToken: target.pairToken,
+            leaseId: target.leaseId,
+            nodeId: target.nodeId,
+            engine: 'auto',
+            source: 'local-bridge-registry'
+        });
+
+        const ok = connect?.ok === true;
+        updateRemoteRegistryFollowerState({
+            status: ok ? 'connected' : 'connect-failed',
+            reason: ok ? (connect.alreadyRunning ? 'already-running' : 'connected') : 'connect-failed',
+            authenticated: true,
+            lastAttemptAt: attemptedAt,
+            lastSuccessAt: ok ? new Date().toISOString() : remoteRegistryFollowerState.lastSuccessAt,
+            targetEndpoint: target.endpointCandidates[0],
+            targetEndpointCandidates: target.endpointCandidates,
+            targetLeaseId: target.leaseId,
+            targetNodeId: target.nodeId,
+            lastError: ok ? '' : (connect?.error || 'remote-agent-connect-failed')
+        });
+        await reportRemoteRegistryFollowerSync({
+            ok,
+            attempted: true,
+            connected: ok,
+            skipped: connect?.alreadyRunning === true,
+            reason: ok ? (connect.alreadyRunning ? 'already-running' : 'connected') : 'connect-failed',
+            error: ok ? '' : connect?.error,
+            trigger,
+            authenticated: true,
+            targetActive: true,
+            targetEndpoint: target.endpointCandidates[0],
+            targetEndpointCandidates: target.endpointCandidates,
+            targetLeaseId: target.leaseId,
+            targetNodeId: target.nodeId,
+            targetExpiresAt: target.expiresAt
+        });
+
+        scheduleRemoteRegistryFollower(ok ? REMOTE_REGISTRY_FOLLOWER_POLL_MS : REMOTE_REGISTRY_FOLLOWER_FAST_RETRY_MS, ok ? 'connected' : 'connect-failed');
+        return serializeRemoteRegistryFollowerState();
+    } catch (error) {
+        const transientAuth = error?.statusCode === 401 || error?.statusCode === 403;
+        updateRemoteRegistryFollowerState({
+            status: transientAuth ? 'auth-pending' : 'error',
+            reason: transientAuth ? 'registry-auth-pending' : 'registry-sync-failed',
+            authenticated: false,
+            lastAttemptAt: attemptedAt,
+            lastError: error?.message || String(error || '')
+        });
+        await reportRemoteRegistryFollowerSync({
+            ok: isRemoteAgentProcessRunning(),
+            skipped: true,
+            reason: transientAuth ? 'registry-auth-pending-agent-kept' : 'registry-sync-failed',
+            error: error?.message || String(error || ''),
+            trigger,
+            authenticated: false
+        });
+        scheduleRemoteRegistryFollower(REMOTE_REGISTRY_FOLLOWER_FAST_RETRY_MS, transientAuth ? 'auth-pending' : 'sync-error');
+        return serializeRemoteRegistryFollowerState();
+    } finally {
+        remoteRegistryFollowerInFlight = false;
+    }
+}
+
+function startRemoteRegistryFollower() {
+    if (!REMOTE_REGISTRY_FOLLOWER_ENABLED || remoteRegistryFollowerStarted) {
+        return;
+    }
+
+    remoteRegistryFollowerStarted = true;
+    updateRemoteRegistryFollowerState({
+        status: 'starting',
+        reason: 'startup',
+        lastAttemptAt: '',
+        lastError: ''
+    });
+    scheduleRemoteRegistryFollower(250, 'startup');
+}
+
+function stopRemoteRegistryFollower() {
+    if (remoteRegistryFollowerTimer) {
+        clearTimeout(remoteRegistryFollowerTimer);
+        remoteRegistryFollowerTimer = null;
+    }
+    remoteRegistryFollowerStarted = false;
+    updateRemoteRegistryFollowerState({
+        status: REMOTE_REGISTRY_FOLLOWER_ENABLED ? 'stopped' : 'disabled',
+        reason: 'bridge-shutdown'
+    });
+}
+
 function trimShellOutput(value, maxLength) {
     const text = String(value || '');
     if (text.length <= maxLength) {
-        return text;
-    }
+        return text;
+    }
 
     return text.slice(text.length - maxLength);
 }
@@ -8610,6 +9287,7 @@ app.get('/api/status', async (req, res) => {
         bridgeAuthRequired,
         remoteHub: remoteHub.getStatus({ includeSecrets: false }),
         remoteAgent: serializeRemoteAgentState(),
+        remoteRegistryFollower: serializeRemoteRegistryFollowerState(),
         shellJobsPath: '/api/shell/jobs',
         companyCore: {
             baseUrl: companyCoreBaseUrl,
@@ -10400,15 +11078,14 @@ async function startBridgeServer() {
             `${tone('listen', 'muted')}   ${tone(`http://127.0.0.1:${PORT}`, 'path')}`,
             `${tone('stop', 'muted')}     Ctrl+C`
         ]);
+        startRemoteRegistryFollower();
     });
 }
 
 await startBridgeServer();
 
-// Graceful shutdown
-let isShuttingDown = false;
-
-async function shutdownBridge(signal) {
+// Graceful shutdown
+async function shutdownBridge(signal) {
     if (isShuttingDown) return;
     isShuttingDown = true;
 
@@ -10435,6 +11112,12 @@ async function shutdownBridge(signal) {
         // Ignore if already closed
     }
 
+    try {
+        stopRemoteRegistryFollower();
+    } catch {
+        // Ignore registry follower shutdown errors
+    }
+
     try {
         await stopRemoteAgentConnection('bridge-shutdown');
     } catch {