Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

46.2 KB
Raw Blame
import { catalogIdentityEvents } from './catalogIdentity/events.js';
import { githubNotificationEvents } from './githubNotificationEvents.js';
import { registerModelObservationSocket } from './modelObservation.js';
import { registerBrowserStatusSocket } from './browserStatus.js';
import { registerFleetHostSocket } from './fleetHostNotify.js';
import { spriteEvents } from './sprites/events.js';
import { modelLifecycleEvents } from './modelLifecycleEvents.js';
import { meatspaceEvents } from './meatspaceEvents.js';
import { dashboardEvents } from './dashboardEvents.js';
import { settingsEvents } from './settings.js';
import { recordEvents } from './sharing/recordEvents.js';
import { fableLoomRunEvents } from './fableLoom/runEvents.js';
import { cosEvents } from './cosEvents.js';
import { toAgentListItem } from '../lib/cosAgentListProjection.js';
import { appsEvents } from './apps.js';
import { errorEvents, sanitizeContext } from '../lib/errorHandler.js';
import { handleErrorRecovery } from './autoFixer.js';
import { notificationEvents } from './notifications.js';
import { agentPersonalityEvents } from './agentPersonalities.js';
import { platformAccountEvents } from './platformAccounts.js';
import { updateEvents } from './updateChecker.js';
import { scheduleEvents } from './automationScheduler.js';
import { activityEvents } from './agentActivity.js';
import { digitalTwinEvents } from './digital-twin-meta.js';
import { brainEvents, BRAIN_ENTITY_TYPES } from './brainStorage.js';
import { moltworldWsEvents } from './moltworldWs.js';
import { beeperSocketEvents } from './beeperSocketEvents.js';
import { queueEvents } from './moltworldQueue.js';
import { instanceEvents } from './instanceEvents.js';
import { sanitizePeerForClient } from './instances.js';
import { attachTailcatForwardsToPeers } from './tailcatPeer.js';
import { reviewEvents } from './review.js';
import { loopEvents } from './loops.js';
import { imageGenEvents } from './imageGenEvents.js';
import { trainingEvents } from './loraTraining/events.js';
import { mediaPromptHistoryEvents } from './mediaPromptHistory.js';
import { mediaJobEvents } from './mediaJobQueue/index.js';
import { importerEvents, getImporterProgressFrames } from './importerEvents.js';
import { catalogEvents } from './catalogEvents.js';
import { writersRoomEvents } from './writersRoomEvents.js';
import { musicVideoEvents } from './musicVideo/events.js';
import { fineTuningEvents } from './voice/fineTuningEvents.js';
import { videoGenEvents } from './videoGen/events.js';
import { audioGenEvents } from './audioGen/events.js';
import { aiStatusEvents } from './aiStatusEvents.js';
import { usageBackfillEvents } from './usageBackfillEvents.js';
import { eidoverseWorldEvents } from './eidoverseWorldEvents.js';
import { jevEvents } from './jevEvents.js';
import { layaMlxEvents } from './layaMlxEvents.js';
import { providerQuotaEvents } from './providerQuotaEvents.js';
import { wireProactiveTriggers } from './voice/proactiveTriggers.js';
import { callStateEvents } from './voice/callSession.js';
import {
  validateSocketData,
  errorRecoverSchema
} from '../lib/socketValidation.js';
import { registerEidoverseTravelHandlers } from '../sockets/eidoverseTravel.js';
import { registerVoiceHandlers } from '../sockets/voice.js';
import { registerProcessHandlers } from '../sockets/processes.js';
import { registerAgentProcessHandlers } from '../sockets/agentProcesses.js';
import { registerAppHandlers } from '../sockets/apps.js';
import { registerFableLoomHostedNamespace } from '../sockets/fableLoomHosted.js';
import { cleanupSocketStreams, registerLogHandlers } from '../sockets/logs.js';
import { detachShellSocket, registerShellHandlers } from '../sockets/shell.js';
import { detachItermSocket, registerItermHandlers } from '../sockets/iterm.js';
import { getBuildId } from '../lib/buildId.js';
import { authEvents, isAuthEnabled, verifyRequestSession } from './auth.js';
import { HOST_CONTROL_FORBIDDEN_MESSAGE, socketHasHostControl } from './authGate.js';
import { runEventLogEvents } from './agentRunEventLog.js';
import { bindSystemActivityIo } from './systemActivityNotify.js';
import { armSystemActivityWatchers } from './systemActivityWatchers.js';
import { armReadinessWatchers, registerReadinessSocket } from './readinessNotify.js';
import { registerGeneratedPreviewHandlers } from './generatedPreview/sessions.js';

// Store CoS subscribers
const cosSubscribers = new Set();
// Store error subscribers for auto-fix notifications
const errorSubscribers = new Set();
// Store notification subscribers
const notificationSubscribers = new Set();
// Store agent subscribers
const agentSubscribers = new Set();
// Store instance subscribers
const instanceSubscribers = new Set();
// Store loop subscribers
const loopSubscribers = new Set();
const codeAnimationSubscribers = new Set();
// Store Beeper realtime subscribers (#33). Invalidation frames and transport
// liveness ONLY — see setupBeeperEventForwarding for why this may never be a
// global emit.
const beeperSubscribers = new Set();
const fableLoomSubscribers = new Set();
// Operator command-runner output (#12019). Never a global emit: the stream
// carries host command output, and a peer relay socket (restricted to
// `cos:subscribe`) must not receive it.
const commandSubscribers = new Set();
// Store io instance for broadcasting
let ioInstance = null;

/**
 * Return the module-level Socket.IO instance (null before initSocket runs).
 * Lets services emit to clients from unattended paths (cron handlers) that
 * don't receive an `io` argument.
 */
export function getIo() {
  return ioInstance;
}

const ALL_SUBSCRIBER_SETS = [cosSubscribers, errorSubscribers, notificationSubscribers, agentSubscribers, instanceSubscribers, loopSubscribers, codeAnimationSubscribers, beeperSubscribers, fableLoomSubscribers, commandSubscribers];

export function emitCodeAnimationChanged(id, kind) {
  broadcastToSet(codeAnimationSubscribers, 'code-animation:changed', kind ? { id, kind } : { id });
}

/** Emit a `command:<id>:*` frame to sockets that sent `command:subscribe`. */
export function broadcastToCommandSubscribers(event, data) {
  broadcastToSet(commandSubscribers, event, data);
}

function broadcastToSet(set, event, data) {
  const disconnected = [];
  for (const s of set) {
    if (!s.connected) { disconnected.push(s); continue; }
    s.emit(event, data);
  }
  for (const s of disconnected) set.delete(s);
}

function registerSubscriber(socket, namespace, set) {
  socket.on(`${namespace}:subscribe`, (options) => {
    if (namespace === 'cos' && ['invalidate', 'full'].includes(options?.taskLists)) socket.cosTaskLists = options.taskLists;
    set.add(socket);
    socket.emit(`${namespace}:subscribed`);
  });
  socket.on(`${namespace}:unsubscribe`, () => {
    set.delete(socket);
    socket.emit(`${namespace}:unsubscribed`);
  });
}

// A peer relay (server/services/peerSocketRelay.js) authenticates the socket
// handshake with the paired peer token or the legacy Basic password (#8386) —
// never a session — so it can never satisfy the per-event re-check below on
// its own. This is the ONLY carve-out: a minimal, read-only allowlist of the
// subscribe/unsubscribe events the relay needs to receive `cos:agent:*`
// broadcasts. Every other event, including any `shell:*`/host-control event,
// still requires a real operator session and disconnects a peer-authenticated
// socket exactly as it did before. Keep this list minimal — do not add a
// mutating or host-affecting event here.
const PEER_RELAY_ALLOWED_EVENTS = new Set(['cos:subscribe', 'cos:unsubscribe']);

// Events that execute on the host — an interactive PTY, keystrokes into the
// user's live iTerm2 sessions, or git/npm/PM2/deploy runs in a managed app's
// directory. They need the same operator authority as the HTTP
// requireHostControl routes (#8226): on a password-free install a remote
// LAN/tailnet socket is refused (#8708). Every `shell:*` and `iterm:*` event
// is included by prefix; read-only subscriptions stay open to remote sockets.
// `error:recover` queues a recovery agent that runs shell commands (#8716).
// Detection can bootstrap a PM2 daemon while inspecting an app-specific home.
// The HTTP twin of this set is HOST_CONTROL_ROUTES in lib/hostControlRoutes.js.
const HOST_CONTROL_SOCKET_EVENTS = new Set(['app:update', 'app:standardize', 'app:deploy', 'standardize:start', 'detect:start', 'error:recover']);
const HOST_CONTROL_SOCKET_PREFIXES = ['shell:', 'iterm:'];
const isHostControlSocketEvent = (event) => typeof event === 'string'
  && (HOST_CONTROL_SOCKET_EVENTS.has(event) || HOST_CONTROL_SOCKET_PREFIXES.some((prefix) => event.startsWith(prefix)));

// A refusal goes out on the error event the event's own client already
// listens on, so the waiting UI settles instead of hanging.
const hostControlRefusal = (event, payload) => {
  const refusal = { code: 'HOST_CONTROL_FORBIDDEN', error: HOST_CONTROL_FORBIDDEN_MESSAGE, message: HOST_CONTROL_FORBIDDEN_MESSAGE };
  if (event.startsWith('shell:')) return ['shell:error', { ...refusal, sessionId: payload?.sessionId }];
  if (event.startsWith('iterm:')) return ['iterm:error', { ...refusal, id: payload?.id }];
  if (event === 'standardize:start') return ['standardize:complete', { success: false, ...refusal }];
  if (event === 'detect:start') return ['detect:complete', { success: false, ...refusal }];
  return [`${event}:error`, { ...refusal, appId: payload?.appId }];
};

function registerAuthHandlers(socket, _io) {
  // Per-event auth re-check: the handshake gate only runs once at connection
  // time, so every inbound event re-verifies an enabled session. With auth
  // off, host-control events still need a local connection.
  if (typeof socket.use === 'function') {
    socket.use(async ([event, payload], next) => {
      try {
        if (!(await isAuthEnabled())) {
          if (!isHostControlSocketEvent(event) || socketHasHostControl(socket)) return next();
          console.warn(`⛔ Refused host-control socket event ${event} from a non-local connection`);
          socket.emit(...hostControlRefusal(event, payload));
          return;
        }
        if (await verifyRequestSession({ headers: socket.handshake?.headers || {} })) return next();
        const peerAuthMethod = socket.data?.portosAuthMethod;
        if ((peerAuthMethod === 'peer' || peerAuthMethod === 'basic') && PEER_RELAY_ALLOWED_EVENTS.has(event)) {
          return next();
        }
        socket.disconnect(true);
      } catch (err) {
        console.error(`❌ Socket auth middleware error: ${err?.message ?? err}`);
        socket.disconnect(true);
      }
    });
  }
}

function registerBuildHandlers(socket, _io) {
  // The bundle hash is safe to push across federated socket relays. Git
  // identity remains on the machine-local system-build API (#4694).
  socket.emit('build:id', { buildId: getBuildId() });
}

function registerImporterHandlers(socket, _io) {
  // Replay on demand because the importer UI mounts after the shared socket.
  socket.on('importer:progress:replay', () => {
    for (const frame of getImporterProgressFrames()) {
      socket.emit('importer:progress', frame);
    }
  });
}

function registerSubscriptionHandlers(socket, _io) {
  registerSubscriber(socket, 'cos', cosSubscribers);
  registerSubscriber(socket, 'errors', errorSubscribers);
  registerSubscriber(socket, 'notifications', notificationSubscribers);
  registerSubscriber(socket, 'agents', agentSubscribers);
  registerSubscriber(socket, 'instances', instanceSubscribers);
  registerSubscriber(socket, 'loops', loopSubscribers);
  registerSubscriber(socket, 'code-animation', codeAnimationSubscribers);
  registerSubscriber(socket, 'beeper', beeperSubscribers);
  registerSubscriber(socket, 'fableloom', fableLoomSubscribers);
  registerSubscriber(socket, 'command', commandSubscribers);
}

function registerErrorHandlers(socket, io) {
  socket.on('error:recover', async (rawData) => {
    try {
      const data = validateSocketData(errorRecoverSchema, rawData, socket, 'error:recover');
      if (!data) return;
      const { code, context } = data;
      console.log(`🔧 Error recovery requested: ${code}`);

      const task = await handleErrorRecovery(code, context);
      io.emit('error:recover:requested', {
        code,
        context,
        taskId: task.id,
        timestamp: Date.now()
      });
    } catch (err) {
      const message = err?.message ?? String(err);
      console.error(`❌ Socket handler error [error:recover]: ${message}`);
      socket.emit('error:recover:error', { message });
    }
  });
}

function registerLifecycleHandlers(socket, _io) {
  socket.on('disconnect', () => {
    console.log(`🔌 Client disconnected: ${socket.id}`);
    cleanupSocketStreams(socket.id);
    for (const set of ALL_SUBSCRIBER_SETS) set.delete(socket);
    const detached = detachShellSocket(socket);
    if (detached > 0) {
      console.log(`🐚 Detached ${detached} shell session(s) (still running)`);
    }
    detachItermSocket(socket);
    socket.removeAllListeners();
  });
}

const SOCKET_HANDLER_REGISTRARS = [
  registerAuthHandlers,
  registerReadinessSocket,
  registerModelObservationSocket,
  registerBrowserStatusSocket,
  registerFleetHostSocket,
  registerVoiceHandlers,
  registerBuildHandlers,
  registerImporterHandlers,
  registerAppHandlers,
  registerProcessHandlers,
  registerAgentProcessHandlers,
  registerLogHandlers,
  registerSubscriptionHandlers,
  registerEidoverseTravelHandlers,
  registerErrorHandlers,
  registerShellHandlers,
  registerItermHandlers,
  registerGeneratedPreviewHandlers,
  registerLifecycleHandlers
];

function registerAuthRevocationHandler(io) {
  // Auth-state changes (first-time enable, rotation, disable) all funnel
  // through revokeAllSessions in services/auth.js. Disconnect every current
  // socket so its next event cannot use a stale handshake-time grant.
  authEvents.on('sessions:revoked-all', () => {
    console.log(`🔐 Auth state changed — disconnecting all sockets`);
    if (typeof io.disconnectSockets === 'function') io.disconnectSockets(true);
  });
}

const noPayload = () => ({});

// 1:1 emitter → Socket.IO bridges. `payload` maps the event args to the frame;
// omitted means forward the first argument unchanged.
const SIMPLE_BRIDGES = [
  { emitter: modelLifecycleEvents, event: 'image-to-3d:changed', channel: 'image-to-3d:changed' },
  { emitter: modelLifecycleEvents, event: 'threejs-model:changed', channel: 'threejs-model:changed' },
  { emitter: meatspaceEvents, event: 'death-clock:changed', channel: 'meatspace:death-clock:changed' },
  { emitter: meatspaceEvents, event: 'changed', channel: 'meatspace:changed' },
  { emitter: usageBackfillEvents, event: 'updated', channel: 'usage-backfill:updated', payload: noPayload },
  { emitter: eidoverseWorldEvents, event: 'updated', channel: 'eidoverse:projection', payload: noPayload },
  { emitter: jevEvents, event: 'status', channel: 'jev:status', payload: noPayload },
  { emitter: jevEvents, event: 'stats', channel: 'jev:stats', payload: noPayload },
  { emitter: jevEvents, event: 'heads', channel: 'jev:heads', payload: noPayload },
  { emitter: layaMlxEvents, event: 'updated', channel: 'laya:status', payload: noPayload },
  { emitter: providerQuotaEvents, event: 'updated', channel: 'provider-quota:updated', payload: noPayload },
  // Importer analyze-phase stage progress; each frame carries a `runId` so the
  // client ignores stragglers from a prior run.
  { emitter: importerEvents, event: 'progress', channel: 'importer:progress' },
  { emitter: catalogEvents, event: 'progress', channel: 'catalog:extract:progress' },
  { emitter: catalogIdentityEvents, event: 'changed', channel: 'catalog:identity-changed' },
  // A GitHub notification inbox sync, triage or action changed stored rows.
  { emitter: githubNotificationEvents, event: 'changed', channel: 'github:notifications:changed' },
  { emitter: aiStatusEvents, event: 'status', channel: 'ai:status' },
  // The call-host tab already gets `voice:call:state` from its own socket
  // handler (server/sockets/voice.js); this fans it out to every OTHER tab.
  { emitter: callStateEvents, event: 'state', channel: 'voice:call:state' },
  // A Voice Lab fine-tuning run changed status, sealed a checkpoint, or
  // advanced (throttled) — the Fine-Tuning tab applies the job frame (#10400).
  { emitter: fineTuningEvents, event: 'updated', channel: 'voice:fine-tune:updated' },
  // A storyboard render filed durably by writersRoomSceneImageHook (#1363).
  { emitter: writersRoomEvents, event: 'scene-image', channel: 'writers-room:scene-image' },
  // Scene reference frame / i2v clip filed durably by the music-video hooks
  // (#1760), an opt-in auto-review run advancing (#8988), and a server-owned
  // production run advancing (#9066) — all without a client refetch.
  { emitter: musicVideoEvents, event: 'scene-image', channel: 'music-video:scene-image' },
  { emitter: musicVideoEvents, event: 'scene-video', channel: 'music-video:scene-video' },
  // A scene render failed (or its recorded failure cleared) — #10154.
  { emitter: musicVideoEvents, event: 'scene-failure', channel: 'music-video:scene-failure' },
  { emitter: musicVideoEvents, event: 'auto-review', channel: 'music-video:auto-review' },
  { emitter: musicVideoEvents, event: 'production', channel: 'music-video:production' },
  // A fully-autonomous run (prompt → lyrics → Suno song → video) advancing.
  { emitter: musicVideoEvents, event: 'autonomous', channel: 'music-video:autonomous' },
  { emitter: musicVideoEvents, event: 'song-revision', channel: 'music-video:song-revision' },
  // The Cast & Sets check-in advancing, and a development artifact changing.
  { emitter: musicVideoEvents, event: 'cast-and-sets', channel: 'music-video:cast-and-sets' },
  { emitter: musicVideoEvents, event: 'dev-artifact', channel: 'music-video:dev-artifact' },
  // A publish draft's tab was filled, closed by hand, or discarded.
  { emitter: musicVideoEvents, event: 'publish-draft', channel: 'music-video:publish-draft' },
  // The release cover art was composed, or its source image was queued or failed.
  { emitter: musicVideoEvents, event: 'cover-art', channel: 'music-video:cover-art' },
  // A shot's cached render segment rendering, rendered, or failed (shotSegments.js).
  { emitter: musicVideoEvents, event: 'render-cleanup', channel: 'music-video:render-cleanup' },
  { emitter: musicVideoEvents, event: 'shot-render', channel: 'music-video:shot-render' },
];

let forwardingRegistered = false;

// Registers every process-wide emitter → Socket.IO bridge exactly once, however
// many times initSocket runs. Forwarders read the module-level `ioInstance` at
// emit time (never capture `io`), so a re-init forwards through the latest io.
// A bridge only goes live by being listed here or in SIMPLE_BRIDGES.
function setupEventForwarding() {
  if (forwardingRegistered) return;
  forwardingRegistered = true;
  for (const { emitter, event, channel, payload } of SIMPLE_BRIDGES) {
    emitter.on(event, (...args) => ioInstance?.emit(channel, payload ? payload(...args) : args[0]));
  }
  runEventLogEvents.on('mind:event', (event) => broadcastToCos('cos:mind:event', event));
  setupCosEventForwarding();
  setupErrorEventForwarding();
  setupAppsEventForwarding();
  setupNotificationEventForwarding();
  setupAgentEventForwarding();
  setupBrainEventForwarding();
  setupDigitalTwinEventForwarding();
  setupMoltworldWsEventForwarding();
  setupMoltworldQueueEventForwarding();
  setupInstanceEventForwarding();
  setupReviewEventForwarding();
  setupPeerAgentEventForwarding();
  setupUpdateEventForwarding();
  setupLoopEventForwarding();
  setupMediaGenEventForwarding();
  setupProactiveSpeechForwarding();
  setupBeeperEventForwarding();
  setupRecordEventForwarding();
  setupFableLoomRunForwarding();
}

// Bounded invalidations only: records remain behind their existing HTTP gates.
function setupRecordEventForwarding() {
  const forward = ({ recordKind, recordId }) => {
    if (recordKind === 'creativeDirectorProject') {
      ioInstance?.emit('creative-director:project:changed', { id: recordId });
    } else if (recordKind === 'creativeCommission') {
      ioInstance?.emit('commission:changed', { id: recordId });
    } else if (recordKind === 'storyboard') {
      ioInstance?.emit('storyboard:changed', { id: recordId });
    }
  };
  recordEvents.on('updated', forward);
  recordEvents.on('deleted', forward);
  recordEvents.on('invalidated', forward);
}

export function initSocket(io) {
  registerAuthRevocationHandler(io);
  registerFableLoomHostedNamespace(io);

  io.on('connection', (socket) => {
    console.log(`🔌 Client connected: ${socket.id}`);
    // Each registrar hangs its own per-socket cleanup on 'disconnect' (13+
    // today), past Node's default cap of 10 — which warned on every connect.
    socket.setMaxListeners(50);
    for (const registerHandlers of SOCKET_HANDLER_REGISTRARS) {
      registerHandlers(socket, io);
    }
  });

  ioInstance = io;
  setupEventForwarding();
  // Invalidation only. Clients coalesce the frame into one bounded activity
  // read; a missed frame is repaired by the reconnect read, not by polling.
  bindSystemActivityIo(io);
  armReadinessWatchers().catch((err) => {
    console.error(`❌ Readiness watchers failed: ${err.message}`);
  });
  armSystemActivityWatchers().catch((err) => {
    console.error(`❌ system activity watchers failed: ${err.message}`);
  });
}

function setupProactiveSpeechForwarding() {
  wireProactiveTriggers({ io: ioInstance });
}

// Broadcast to all connected clients
export function broadcast(io, event, data) {
  io.emit(event, data);
}

// Test-only seam (mirrors the `__testing` convention in authGate.js): lets an
// integration test wire the real per-event auth re-check onto a live
// Socket.IO server without pulling in every other registrar's dependencies.
export const __testing = { registerAuthHandlers, PEER_RELAY_ALLOWED_EVENTS, registerSubscriptionHandlers };

// Broadcast to CoS subscribers only
function broadcastToCos(event, data) {
  if (event !== 'cos:tasks:changed') {
    broadcastToSet(cosSubscribers, event, data);
    return;
  }
  for (const socket of cosSubscribers) {
    if (!socket.connected) { cosSubscribers.delete(socket); continue; }
    const completedChanged = data?.task?.status === 'completed'
      || data?.previousStatus === 'completed' || ['deleted', 'peer-merged'].includes(data?.action);
    socket.emit(event, socket.cosTaskLists === 'invalidate'
      ? { invalidated: true, ...(completedChanged ? { completedChanged: true } : {}) } : data);
  }
}

// Broadcast to error subscribers only
function broadcastToErrors(event, data) { broadcastToSet(errorSubscribers, event, data); }

// Environment changes need no Mind turn. Coalesce bursts into one bounded,
// payload-free invalidation and send it only to existing CoS subscribers.
let mindVisibilityTimer = null;
function invalidateMindVisibility() {
  if (!cosSubscribers.size || mindVisibilityTimer) return;
  mindVisibilityTimer = setTimeout(() => {
    mindVisibilityTimer = null;
    broadcastToCos('cos:mind:visibility', { invalidated: true });
  }, 250);
  mindVisibilityTimer.unref?.();
}

// Process-wide listeners forward through the current IO and subscriber sets.
function setupCosEventForwarding() {
  // Dashboard invalidations deliberately omit decisions, prompts and settings.
  for (const event of ['goals:changed', 'backup:changed']) {
    dashboardEvents.on(event, () => ioInstance?.emit(event, {}));
  }
  for (const event of ['cos:schedule:changed', 'cos:decisions:changed', 'cos:day:changed']) {
    dashboardEvents.on(event, () => broadcastToCos(event, {}));
  }
  settingsEvents.on('settings:updated', () => {
    ioInstance?.emit('backup:changed', {});
    ioInstance?.emit('jev:policy', {});
  });
  // A failed restore also invalidates policy: clients must show the strict
  // read failure instead of continuing to offer stale safety settings.
  settingsEvents.on('settings:invalidated', () => ioInstance?.emit('jev:policy', {}));
  for (const [source, target] of [
    ['scheduler:scheduled', 'cos:scheduler:changed'],
    ['scheduler:ran', 'cos:scheduler:changed'],
    ['scheduler:cancelled', 'cos:scheduler:changed'],
    ['agents:changed', 'cos:agents:changed'],
    ['storage:changed', 'cos:storage:changed'],
    ['learning:changed', 'cos:learning:changed'],
  ]) {
    cosEvents.on(source, data => {
      broadcastToCos(target, target === 'cos:scheduler:changed' && typeof data?.id === 'string' ? { id: data.id } : {});
      if (target === 'cos:scheduler:changed' && data?.id === 'backup-daily') {
        ioInstance?.emit('backup:changed', {});
      }
    });
  }
  // Status events
  cosEvents.on('goals:changed', data => broadcastToCos('cos:goals:changed', data));
  cosEvents.on('status', (data) => broadcastToCos('cos:status', data));
  for (const event of ['config:changed', 'status:paused', 'status:resumed']) {
    cosEvents.on(event, data => broadcastToCos(`cos:${event}`, data));
  }

  // Log events for real-time UI feedback
  cosEvents.on('log', (data) => broadcastToCos('cos:log', data));

  // Task events
  // `cosTaskStore` emits this immediately for every persisted lifecycle
  // transition. Forward the task itself so focused views can update one row
  // without waiting for the file watcher to rebuild the entire task list.
  cosEvents.on('tasks:changed', (data) => broadcastToCos('cos:tasks:changed', data));

  cosEvents.on('maintenance:updated', (data) => broadcastToCos('cos:maintenance:updated', data));

  // Agent events. These three carry a whole agent RECORD, and every consumer —
  // the CoS agents list, the task-update hook, the peer relay — treats it as a
  // list row. So they leave through the same projection as `GET /api/cos/agents`:
  // no transcript (that is the separate `agent:output` stream) and a bounded task
  // description. Without it the socket refills the very list the listing
  // projection just shrank, and ships a 50 KB pasted prompt to every subscriber —
  // including, through the relay, a peer. Projected HERE rather than at the emit
  // because the server-side `cosEvents` listeners need the whole record.
  cosEvents.on('agent:spawned', (data) => broadcastToCos('cos:agent:spawned', toAgentListItem(data)));
  cosEvents.on('agent:updated', (data) => broadcastToCos('cos:agent:updated', toAgentListItem(data)));
  cosEvents.on('agent:completed', (data) => broadcastToCos('cos:agent:completed', toAgentListItem(data)));
  cosEvents.on('agent:output', (data) => broadcastToCos('cos:agent:output', data));
  cosEvents.on('agent:feedback', (data) => broadcastToCos('cos:agent:feedback', data));
  cosEvents.on('agent:btw', (data) => broadcastToCos('cos:agent:btw', data));
  cosEvents.on('persistent-mind:status', (data) => broadcastToCos('cos:mind:status', data));

  // Memory events
  cosEvents.on('memory:created', (data) => broadcastToCos('cos:memory:created', data));
  cosEvents.on('memory:updated', (data) => broadcastToCos('cos:memory:updated', data));
  cosEvents.on('memory:deleted', (data) => broadcastToCos('cos:memory:deleted', data));
  // Approval/rejection also changes the active collection. Use the existing
  // identity invalidation rather than forwarding the full approved record.
  for (const event of ['memory:approved', 'memory:rejected']) {
    cosEvents.on(event, ({ id }) => broadcastToCos('cos:memory:updated', { id }));
  }
  cosEvents.on('memory:extracted', (data) => broadcastToCos('cos:memory:extracted', data));
  cosEvents.on('memory:approval-needed', (data) => broadcastToCos('cos:memory:approval-needed', data));

  // Health events
  cosEvents.on('health:check', (data) => broadcastToCos('cos:health:check', data));
  cosEvents.on('health:critical', (data) => broadcastToCos('cos:health:critical', data));

  // Evaluation events
  cosEvents.on('evaluation', (data) => broadcastToCos('cos:evaluation', data));
  cosEvents.on('task:ready', (data) => broadcastToCos('cos:task:ready', data));

  // Feature agent events
  cosEvents.on('feature-agent:status', (data) => broadcastToCos('cos:feature-agent:status', data));
  cosEvents.on('feature-agent:output', (data) => broadcastToCos('cos:feature-agent:output', data));
  cosEvents.on('feature-agent:run-complete', (data) => broadcastToCos('cos:feature-agent:run-complete', data));

  // Watcher events
  cosEvents.on('watcher:stopped', (data) => broadcastToCos('cos:watcher:stopped', data));

  // A user-initiated on-demand "Run" that produced no task — the client toasts
  // this so an explicit trigger that finds no actionable work (parked) isn't a
  // silent no-op.
  cosEvents.on('schedule:on-demand-empty', (data) => broadcastToCos('cos:schedule:on-demand-empty', data));
  // Programmatic scheduled handlers report what they actually did — no agent
  // task is created, so there is nothing else for the user to watch.
  cosEvents.on('schedule:on-demand-handled', (data) => broadcastToCos('cos:schedule:on-demand-handled', data));
  for (const event of ['config:changed', 'status', 'status:paused', 'status:resumed',
    'agent:spawned', 'agent:updated', 'agent:completed', 'health:check', 'health:critical']) {
    cosEvents.on(event, invalidateMindVisibility);
  }
}

const isClientRefusal = (error) => error.status >= 400 && error.status < 500 && error.severity !== 'critical';

// Set up error event forwarding
function setupErrorEventForwarding() {
  // Forward error events to error subscribers. Use `safeContext` (second arg
  // from emitErrorEvent) — `error.context` may contain sensitive fields like
  // apiKey/token that must not be broadcast to clients. When the caller emits
  // directly (bypassing `emitErrorEvent`), `safeContext` is undefined; in that
  // case sanitize the raw context defensively rather than passing it through.
  errorEvents.on('error', (error, safeContext) => {
    // A 4xx refusal is answered to its own caller: the browser's request()
    // already toasts its failures, and most refusals come from agents and
    // scripts calling the API, which would otherwise red-toast every open tab.
    if (isClientRefusal(error)) return;
    const context = safeContext !== undefined
      ? safeContext
      : sanitizeContext(error.context);
    broadcastToErrors('error:notified', {
      message: error.message,
      code: error.code,
      severity: error.severity,
      timestamp: error.timestamp,
      canAutoFix: error.canAutoFix,
      context
    });
  });
}

// Set up apps event forwarding - broadcasts to ALL clients
function setupAppsEventForwarding() {
  appsEvents.on('changed', (data) => {
    invalidateMindVisibility();
    if (ioInstance) {
      ioInstance.emit('apps:changed', data);
    }
  });
}

// Broadcast to notification subscribers only
function broadcastToNotifications(event, data) { broadcastToSet(notificationSubscribers, event, data); }

// Set up notification event forwarding
function setupNotificationEventForwarding() {
  notificationEvents.on('added', (data) => broadcastToNotifications('notifications:added', data));
  notificationEvents.on('removed', (data) => broadcastToNotifications('notifications:removed', data));
  notificationEvents.on('updated', (data) => broadcastToNotifications('notifications:updated', data));
  notificationEvents.on('count-changed', (count) => broadcastToNotifications('notifications:count', count));
  notificationEvents.on('cleared', () => broadcastToNotifications('notifications:cleared', {}));
}

// Broadcast to agent subscribers only
function broadcastToAgents(event, data) { broadcastToSet(agentSubscribers, event, data); }

// Set up agent event forwarding
function setupAgentEventForwarding() {
  // Personality events
  agentPersonalityEvents.on('changed', (data) => broadcastToAgents('agents:personality:changed', data));

  // Account events
  platformAccountEvents.on('changed', (data) => broadcastToAgents('agents:account:changed', data));

  // Schedule events
  scheduleEvents.on('changed', (data) => broadcastToAgents('agents:schedule:changed', data));
  scheduleEvents.on('execute', (data) => broadcastToAgents('agents:schedule:execute', data));

  // Activity events
  activityEvents.on('activity', (data) => broadcastToAgents('agents:activity', data));
  activityEvents.on('activity:updated', (data) => broadcastToAgents('agents:activity:updated', data));
}

// Forward only invalidations, never private traits, interview text or settings.
// All status/settings writers save meta; sync also signals after document I/O.
function setupDigitalTwinEventForwarding() {
  for (const event of ['meta:changed', 'sync:completed', 'traits:updated', 'taste:profile-updated', 'interview:analyzed']) {
    digitalTwinEvents.on(event, () => ioInstance?.emit('digital-twin:changed', {}));
  }
}

// Set up brain event forwarding - broadcast to all clients
function setupBrainEventForwarding() {
  // Invalidation only: record bodies, local paths and settings stay behind HTTP.
  const changed = (type, id) => {
    ioInstance?.emit('brain:changed', { type, id });
    if (type === 'links') ioInstance?.emit('brain:links:changed', { id });
  };
  for (const type of BRAIN_ENTITY_TYPES) {
    brainEvents.on(`${type}:upserted`, ({ id }) => changed(type, id));
    brainEvents.on(`${type}:deleted`, ({ id }) => changed(type, id));
  }
  brainEvents.on('record:changed', ({ type, id }) => changed(type, id));
  brainEvents.on('meta:changed', () => changed('meta'));

  brainEvents.on('classified', (data) => {
    if (ioInstance) {
      ioInstance.emit('brain:classified', data);
    }
  });
  brainEvents.on('threads:upserted', (data) => {
    if (ioInstance) ioInstance.emit('brain:threads:changed', data);
  });
  brainEvents.on('threads:deleted', (data) => {
    if (ioInstance) ioInstance.emit('brain:threads:changed', data);
  });
}

// Set up Moltworld WebSocket event forwarding to agent subscribers
function setupMoltworldWsEventForwarding() {
  moltworldWsEvents.on('status', (data) => broadcastToAgents('moltworld:status', data));
  moltworldWsEvents.on('event', (data) => broadcastToAgents('moltworld:event', data));
  moltworldWsEvents.on('presence', (data) => broadcastToAgents('moltworld:presence', data));
  moltworldWsEvents.on('thinking', (data) => broadcastToAgents('moltworld:thinking', data));
  moltworldWsEvents.on('action', (data) => broadcastToAgents('moltworld:action', data));
  moltworldWsEvents.on('interaction', (data) => broadcastToAgents('moltworld:interaction', data));
  moltworldWsEvents.on('nearby', (data) => broadcastToAgents('moltworld:nearby', data));
}

// Set up Moltworld queue event forwarding to agent subscribers
function setupMoltworldQueueEventForwarding() {
  queueEvents.on('added', (data) => broadcastToAgents('moltworld:queue:added', data));
  queueEvents.on('updated', (data) => broadcastToAgents('moltworld:queue:updated', data));
  queueEvents.on('removed', (data) => broadcastToAgents('moltworld:queue:removed', data));
}

// Broadcast to instance subscribers only
function broadcastToInstances(event, data) { broadcastToSet(instanceSubscribers, event, data); }

// Set up instance event forwarding
function setupInstanceEventForwarding() {
  // Invalidation only: the copyable serve capability stays behind the status API.
  instanceEvents.on('tailcat:serve:changed', () => ioInstance?.emit('tailcat:serve:changed', {}));
  // Redact each peer's stored proxy password before it reaches the browser
  // (keep username + hasPassword) — same secret-stripping the GET /instances
  // route applies. `data` is the full peers array.
  instanceEvents.on('peers:updated', (data) => {
    const sanitized = Array.isArray(data) ? data.map(sanitizePeerForClient) : data;
    // Best-effort attach; never block the broadcast if forward metadata is busy.
    Promise.resolve(Array.isArray(sanitized) ? attachTailcatForwardsToPeers(sanitized) : sanitized)
      .then((enriched) => broadcastToInstances('instances:peers:updated', enriched))
      .catch(() => broadcastToInstances('instances:peers:updated', sanitized));
  });
  // Realtime sync lifecycle for the Instances cards: { phase, peerId, ... }.
  // No secrets — just a peer instanceId + counts — so forward as-is.
  instanceEvents.on('sync:progress', (data) => {
    broadcastToInstances('sync:progress', data);
  });
}

// Set up peer agent event forwarding (remote agent streaming)
function setupPeerAgentEventForwarding() {
  instanceEvents.on('peer:agents:updated', (data) => broadcastToInstances('instances:peer:agents:updated', data));
  instanceEvents.on('peer:agent:spawned', (data) => broadcastToInstances('instances:peer:agent:spawned', data));
  instanceEvents.on('peer:agent:updated', (data) => broadcastToInstances('instances:peer:agent:updated', data));
  instanceEvents.on('peer:agent:output', (data) => broadcastToInstances('instances:peer:agent:output', data));
  instanceEvents.on('peer:agent:completed', (data) => broadcastToInstances('instances:peer:agent:completed', data));
}

// Set up review event forwarding
function setupReviewEventForwarding() {
  // Global invalidations reach the bell/dashboard even without a CoS room
  // subscription. They carry no record payload and are never peer-forwarded.
  for (const event of ['tasks:changed', 'agent:completed', 'agent:feedback', 'memory:approved', 'memory:rejected']) {
    cosEvents.on(event, () => {
      if (ioInstance) ioInstance.emit('review:queue:changed');
    });
  }
  reviewEvents.on('queue:changed', () => {
    if (ioInstance) ioInstance.emit('review:queue:changed');
  });
  reviewEvents.on('item:created', (data) => {
    if (ioInstance) ioInstance.emit('review:item:created', data?.metadata?.privateSecurity ? { id: data.id, metadata: { privateSecurity: true } } : data);
  });
  reviewEvents.on('item:updated', (data) => {
    if (ioInstance) ioInstance.emit('review:item:updated', data?.metadata?.privateSecurity ? { id: data.id, metadata: { privateSecurity: true } } : data);
  });
  reviewEvents.on('item:deleted', (data) => {
    if (ioInstance) ioInstance.emit('review:item:deleted', data?.metadata?.privateSecurity ? { id: data.id, metadata: { privateSecurity: true } } : data);
  });
  // Bulk status changes ("Mark all read" / "Complete all") carry only ids, a
  // status and a timestamp — nothing to redact.
  reviewEvents.on('items:bulk-updated', (data) => {
    if (ioInstance) ioInstance.emit('review:items:bulk-updated', data);
  });
}

// Set up update event forwarding
function setupUpdateEventForwarding() {
  updateEvents.on('update:available', (data) => {
    if (ioInstance) {
      ioInstance.emit('portos:update:available', data);
    }
  });
  updateEvents.on('update:checked', (data) => {
    if (ioInstance) {
      ioInstance.emit('portos:update:checked', data);
    }
  });
}

// Broadcast to loop subscribers only
function broadcastToLoops(event, data) { broadcastToSet(loopSubscribers, event, data); }

// Broadcast to Beeper subscribers only
function broadcastToBeeper(event, data) { broadcastToSet(beeperSubscribers, event, data); }

// Bridge the server's Beeper WebSocket onto Socket.IO (#33, decided on #12).
//
// THIS MUST NEVER BE `ioInstance.emit`. `peerSocketRelay.js` opens a Socket.IO
// CLIENT to every online peer, so a global emit crosses the wire to other
// installs — the boundary pinned at socket.test.js (#4694). Beeper message
// content is PII and machine-local (#7's ADR), so the frames here carry
// invalidation only: ids, kinds and transport liveness, never bodies, display
// names or handles. The browser refetches from the PortOS mirror.
function setupBeeperEventForwarding() {
  beeperSocketEvents.on('invalidate', (data) => broadcastToBeeper('beeper:invalidate', data));
  beeperSocketEvents.on('state', (data) => broadcastToBeeper('beeper:realtime', data));
}

// Set up loop event forwarding
function setupLoopEventForwarding() {
  loopEvents.on('created', (data) => broadcastToLoops('loop:created', data));
  loopEvents.on('stopped', (data) => broadcastToLoops('loop:stopped', data));
  loopEvents.on('resumed', (data) => broadcastToLoops('loop:resumed', data));
  loopEvents.on('deleted', (data) => broadcastToLoops('loop:deleted', data));
  loopEvents.on('updated', (data) => broadcastToLoops('loop:updated', data));
  loopEvents.on('iteration:start', (data) => broadcastToLoops('loop:iteration:start', data));
  loopEvents.on('iteration:complete', (data) => broadcastToLoops('loop:iteration:complete', data));
  loopEvents.on('iteration:error', (data) => broadcastToLoops('loop:iteration:error', data));
  loopEvents.on('output', (data) => broadcastToLoops('loop:output', data));
}

// Bridge both image-gen AND video-gen events from their internal EventEmitters
// onto Socket.IO so client UIs can subscribe via `image-gen:*` / `video-gen:*`.
function setupMediaGenEventForwarding() {
  imageGenEvents.on('started', (data) => {
    if (ioInstance) ioInstance.emit('image-gen:started', data);
  });
  imageGenEvents.on('progress', (data) => {
    if (ioInstance) ioInstance.emit('image-gen:progress', data);
  });
  imageGenEvents.on('completed', (data) => {
    if (ioInstance) ioInstance.emit('image-gen:completed', data);
  });
  imageGenEvents.on('failed', (data) => {
    if (ioInstance) ioInstance.emit('image-gen:failed', data);
  });

  videoGenEvents.on('started', (data) => {
    if (ioInstance) ioInstance.emit('video-gen:started', data);
  });
  videoGenEvents.on('progress', (data) => {
    if (ioInstance) ioInstance.emit('video-gen:progress', data);
  });
  videoGenEvents.on('completed', (data) => {
    if (ioInstance) ioInstance.emit('video-gen:completed', data);
  });
  videoGenEvents.on('failed', (data) => {
    if (ioInstance) ioInstance.emit('video-gen:failed', data);
  });

  // Audio (first-pass music-bed, #1928/#1933) rides the same gen-event contract
  // as image/video. Forward it onto `audio-gen:*` so a user-triggered music-bed
  // render surfaces progress/failure like any other media job, rather than only
  // populating `project.musicBed` silently (or silently failing) with the user
  // left to poll the Render Queue to notice a crash/OOM/sidecar error.
  audioGenEvents.on('started', (data) => {
    if (ioInstance) ioInstance.emit('audio-gen:started', data);
  });
  audioGenEvents.on('progress', (data) => {
    if (ioInstance) ioInstance.emit('audio-gen:progress', data);
  });
  audioGenEvents.on('completed', (data) => {
    if (ioInstance) ioInstance.emit('audio-gen:completed', data);
  });
  audioGenEvents.on('failed', (data) => {
    if (ioInstance) ioInstance.emit('audio-gen:failed', data);
  });

  // Map a media-job kind to its gen-event namespace prefix. image/video/audio
  // jobs drive per-job spinners/toasts and have `*-gen:*` consumers; the shared
  // media queue also runs `training` (LoRA) jobs, which have their own UI and NO
  // `*-gen:*` listener — so they must NOT be forwarded onto the image channel
  // (returning null skips them) rather than falling through to `image-gen:*`.
  const genEvtPrefix = (kind) =>
    kind === 'video' ? 'video-gen'
      : kind === 'image' ? 'image-gen'
        : kind === 'audio' ? 'audio-gen'
          : null;

  spriteEvents.on('changed', ({ recordId }) => {
    ioInstance?.emit('sprites:changed', { recordId });
  });
  // Queue lifecycle events carry the persisted job's routing tags. Generation
  // transport events can precede the queue's terminal state, so do not use them.
  for (const event of ['enqueued', 'started', 'completed', 'failed', 'canceled']) {
    mediaJobEvents.on(event, (job) => {
      for (const tagKey of ['spriteRef', 'spriteWalk', 'spriteAnimation']) {
        const recordId = job.params?.[tagKey]?.recordId;
        if (recordId) ioInstance?.emit('sprites:jobs-changed', { recordId, kind: job.kind, tagKey });
      }
    });
  }

  mediaJobEvents.on('reference-sheet:changed', ({ universeId, entryId, jobId, variant, status }) => {
    ioInstance?.emit('reference-sheet:changed', { universeId, entryId, jobId, variant, status });
  });
  mediaJobEvents.on('changed', () => {
    ioInstance?.emit('media-jobs:changed', {});
  });
  trainingEvents.on('dataset:changed', ({ datasetId }) => {
    ioInstance?.emit('training:dataset:changed', { datasetId });
  });
  trainingEvents.on('checkpoints:changed', ({ runId }) => {
    ioInstance?.emit('training:checkpoints:changed', { runId });
  });

  // Bridge media-job cancellation onto a `*-gen:canceled` socket event keyed by
  // `generationId` (#1791). The internal gen modules emit started/progress/
  // completed/failed but have NO 'canceled' — a job canceled *while queued*
  // never starts a gen run, so it produces only `mediaJobEvents 'canceled'` and
  // no socket frame at all, leaving per-scene render spinners stuck until the
  // component remounts. Every client spinner already correlates by media-job id
  // (`data.generationId === jobId`), so a single id-keyed event clears the right
  // spinner across writers-room, music-video, and `useMediaJobProgress`
  // consumers (catalog et al.) uniformly — no per-domain event needed. For a
  // job canceled *while running* this fires alongside the gen module's `failed`;
  // both clear the spinner and the handlers are idempotent.
  mediaPromptHistoryEvents.on('changed', () => { ioInstance?.emit('media-prompt-history:changed', {}); });

  mediaJobEvents.on('canceled', (job) => {
    if (!ioInstance || !job?.id) return;
    const prefix = genEvtPrefix(job.kind);
    if (!prefix) return;
    ioInstance.emit(`${prefix}:canceled`, { generationId: job.id });
  });

  // Bridge media-job FAILURE onto a `*-gen:failed` socket event keyed by
  // `generationId` (#1799) — the failure-side analog of the canceled bridge
  // above. A job that fails *before* the gen run starts (e.g. an unready BYOV
  // runtime throws synchronously in the queue worker, or the watchdog times the
  // job out) emits only `mediaJobEvents 'failed'` and never a `*-gen:failed`
  // frame, so the scene button stays stuck on "Rendering…". Forward it with the
  // same `{ generationId, error }` shape the gen modules use so the client's
  // `onFailed` clears the spinner and can toast the reason. For a job that fails
  // *while running* this fires alongside the gen module's own `failed`; both
  // settle the spinner to 'failed' and the handler is idempotent.
  mediaJobEvents.on('failed', (job) => {
    if (!ioInstance || !job?.id) return;
    const prefix = genEvtPrefix(job.kind);
    if (!prefix) return;
    ioInstance.emit(`${prefix}:failed`, { generationId: job.id, error: job.error });
  });
}

function setupFableLoomRunForwarding() {
  fableLoomRunEvents.on('export', job => {
    broadcastToSet(fableLoomSubscribers, 'fableloom:export:job', job);
  });
  fableLoomRunEvents.on('editorial', run => {
    broadcastToSet(fableLoomSubscribers, 'fableloom:editorial:run', run);
  });
  fableLoomRunEvents.on('shots', run => {
    broadcastToSet(fableLoomSubscribers, 'fableloom:shots:run', run);
  });
  fableLoomRunEvents.on('production', run => {
    broadcastToSet(fableLoomSubscribers, 'fableloom:production:run', run);
  });
}