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

47.8 KB
Raw Blame
/**
 * FableLoom scoped QR-hosted sessions with half-duplex protagonist voice (#5383).
 *
 * Implements:
 * 1. Explicit host-session creation with HTTPS & readiness preflight.
 * 2. High-entropy, short-lived join tokens stored strictly hashed (SHA-256).
 * 3. Scoped fragment-based join URL (#session=...&token=...) so credentials
 *    never appear in HTTP request logs or referrers.
 * 4. Machine-local, ephemeral session state and transcript policy.
 * 5. Authoritative server story/session state and computer playback clock.
 * 6. Half-duplex turn contract: LISTENING -> THINKING -> SPEAKING -> LISTENING.
 * 7. Live conversation gate revalidation (helper decision hold, offscreen protagonist, safe audio occupancy).
 * 8. Speech dispatch stays uncommitted until the designated output reports playback (#13112).
 * 9. Reconnect snapshots and session teardown with in-flight abort.
 */

import { createHash, randomBytes, randomUUID, timingSafeEqual } from 'node:crypto';
import { ServerError } from '../../lib/errorHandler.js';
import { getNetworkExposureStatus, isLoopbackHost } from '../../lib/networkExposure.js';
import { PORTS } from '../../lib/ports.js';
import { getVoiceConfig } from '../voice/config.js';
import { resolveCharacterVoice } from '../voice/profiles.js';
import { synthesize } from '../voice/tts.js';
import { transcribe } from '../voice/stt.js';
import { isEchoOfRecentTts, rememberTtsSentence } from '../voice/echo.js';
import { pcmToWavBuffer } from '../../lib/chiptuneRender.js';
import { pcmToFloat } from '../voice/callEndpointing.js';
import {
  FABLELOOM_AUDIO_TARGETS,
  FABLELOOM_RUNTIME_VERSION,
  evaluateFableLoomLiveInput,
  resolvePlaybackPhaseAsset,
} from '../../lib/fableLoomPlayback.js';
import {
  findEpisode,
  getLoom,
} from './records.js';
import {
  publicNode,
  playTurn,
  resolvePlayRoute,
} from './weave.js';
import { getUniverse } from '../universeBuilder.js';
import { parseVoiceId } from '../pipeline/audio.js';

// Explicit casting wins over array order; legacy looms without a selection keep
// their first-character fallback. A deleted selection never becomes another actor.
const protagonistVoiceCharacter = (loom, universe) => loom.protagonistCharacterId
  ? universe?.characters?.find(character => character.id === loom.protagonistCharacterId) || null
  : universe?.characters?.[0] || null;

// Active hosted sessions in memory (ephemeral, machine-local)
const activeSessions = new Map();

// Default session time-to-live: 30 minutes
export const DEFAULT_SESSION_TTL_MINUTES = 30;
export const MAX_SESSION_TTL_MINUTES = 180;

// How often the sweeper walks `activeSessions` looking for expired records.
// TTLs run 1-180 minutes and a machine hosts at most a handful of sessions at
// once, so one unref'd interval is cheaper than arming (and having to cancel)
// a per-session timeout.
export const HOSTED_SESSION_SWEEP_INTERVAL_MS = 60_000;

// How long a dispatched narration may stay in `speaking` waiting for the
// designated output socket. Past this the pending transition is dropped — a
// missing completion is not a successful playback. Long enough for a spoken
// paragraph, short enough that a vanished client cannot hold the scene.
export const HOSTED_SPEECH_ACK_TIMEOUT_MS = 90_000;

/** True once a session record is past its TTL. */
const isExpired = (session) => new Date(session.expiresAt).getTime() <= Date.now();

/** Helper to derive initial playback phase for a node */
export function initialPhaseForNode(node) {
  if (!node) return 'ended';
  if (node.isEnding) return 'ended';
  if (node.playbackAssets?.entryVideoHistoryId) return 'entry';
  if (node.playbackAssets?.holdLoopVideoHistoryIds?.length) return 'hold';
  if (node.videoHistoryId) {
    return node.playbackMode === 'cut' ? 'entry' : 'hold';
  }
  return 'hold';
}

/** Sanitize session record for public/socket consumption (removes hashedToken and private handles) */
export function sanitizeHostedSession(session) {
  if (!session) return null;
  return {
    id: session.id,
    runtimeVersion: FABLELOOM_RUNTIME_VERSION,
    loomId: session.loomId,
    episodeId: session.episodeId,
    universeId: session.universeId || null,
    status: session.status,
    audioTarget: session.audioTarget,
    currentNodeId: session.currentNodeId,
    playbackPhase: session.playbackPhase,
    activeHoldIndex: session.activeHoldIndex,
    turnPhase: session.turnPhase,
    transcript: session.transcript || [],
    hasHostConnected: !!session.hostSocketId,
    hasAudienceConnected: !!session.audienceSocketId,
    createdAt: session.createdAt,
    expiresAt: session.expiresAt,
  };
}

/**
 * Check readiness & HTTPS posture for starting a hosted play session.
 */
export async function checkHostedSessionReadiness({ loomId, episodeId, loom: customLoom, episode: customEpisode } = {}) {
  const loom = customLoom || (loomId ? await getLoom(loomId) : null);
  if (!loom) {
    throw new ServerError('Loom not found', { status: 404, code: 'NOT_FOUND' });
  }
  const episode = customEpisode || (loom.episodes?.find((e) => e.id === episodeId) || null);
  if (!episode) {
    throw new ServerError('Episode not found', { status: 404, code: 'NOT_FOUND' });
  }

  const warnings = [];
  const errors = [];

  // 1. HTTPS & Network Exposure check
  const netStatus = getNetworkExposureStatus();
  const joinHost = netStatus.cert?.tailscaleHost
    || (netStatus.bind?.host && !isLoopbackHost(netStatus.bind.host) && netStatus.bind.host !== '0.0.0.0' ? netStatus.bind.host : null)
    || 'localhost';
  const joinPort = netStatus.bind?.port || PORTS.API;
  const isHttps = netStatus.scheme === 'https';
  const httpsUrl = isHttps
    ? `https://${joinHost}${joinPort === 443 ? '' : `:${joinPort}`}`
    : `http://${joinHost}${joinPort === 80 ? '' : `:${joinPort}`}`;

  if (!isHttps) {
    errors.push('HTTPS is required for mobile device QR microphone join (run npm run setup:cert to enable TLS).');
  }

  // 2. Host / Story Graph check
  const startNode = episode.nodes?.find((n) => n.id === episode.startNodeId) || null;
  if (!startNode) {
    errors.push('Episode does not have a valid start scene configured.');
  }

  // 3. STT readiness check
  let sttReady = true;
  try {
    const voiceCfg = await getVoiceConfig().catch(() => null);
    if (!voiceCfg) {
      warnings.push('Voice configuration not initialized; using defaults.');
    }
  } catch (err) {
    sttReady = false;
    warnings.push(`STT readiness check warning: ${err?.message || err}`);
  }

  // 4. TTS & Character Voice check
  let ttsReady = true;
  let resolvedVoice = null;
  try {
    let universe = null;
    if (loom.universeId) {
      universe = await getUniverse(loom.universeId).catch(() => null);
    }
    const protagonistChar = protagonistVoiceCharacter(loom, universe);
    if (protagonistChar) {
      resolvedVoice = await resolveCharacterVoice({
        universeId: loom.universeId,
        characterId: protagonistChar.id,
        characterVoiceId: protagonistChar.voiceId,
        route: 'interactive',
      }).catch(() => null);
      if (resolvedVoice?.degraded && resolvedVoice?.warning) {
        warnings.push(resolvedVoice.warning);
      }
    }
  } catch (err) {
    ttsReady = false;
    warnings.push(`Voice resolution warning: ${err?.message || err}`);
  }

  // 5. Playback readiness check
  const playbackReady = true;
  if (startNode) {
    const asset = resolvePlaybackPhaseAsset({
      node: startNode,
      phase: initialPhaseForNode(startNode),
      activeHoldIndex: 0,
    });
    if (startNode.audienceConnection === 'connected' && !asset.safeForLiveVoice) {
      warnings.push('Opening scene hold loop has blocking audio intervals; live voice will be gated.');
    }
  }

  // An audience token authorizes story participation, never a host harness.
  // Keep authored narration available even if the configured narrator is unsafe.
  const llm = await resolvePlayRoute(loom, { callerPolicy: 'direct-api' })
    .then(() => ({ ok: true }))
    .catch(err => ({ ok: false, error: err.message, code: err.code || 'NO_PROVIDER' }));
  if (!llm.ok) warnings.push(`AI narrator unavailable; using authored narration: ${llm.error}`);

  const checks = {
    https: { ok: isHttps, ...(isHttps ? {} : { error: 'HTTPS required' }) },
    host: { ok: !!startNode, ...(startNode ? {} : { error: 'Missing start scene' }) },
    stt: { ok: sttReady },
    llm,
    tts: { ok: ttsReady, voice: resolvedVoice?.voiceId || 'default' },
    playback: { ok: playbackReady },
  };

  const ready = errors.length === 0;

  return {
    ready,
    https: {
      enabled: isHttps,
      host: joinHost,
      port: joinPort,
      url: httpsUrl,
    },
    checks,
    warnings,
    errors,
  };
}

/**
 * Revalidate the live conversation gate at runtime.
 * Live voice interaction is permitted ONLY when:
 * 1. Node has audienceConnection === 'connected'
 * 2. Node playbackMode === 'decision'
 * 3. Playback phase is 'hold' (or active interaction window)
 * 4. Protagonist presence is offscreen (or not explicitly onscreen)
 * 5. Active hold asset is safe for live voice (no character dialogue / blocking SFX)
 */
export function revalidateLiveConversationGate({ session, node, asset }) {
  if (session?.status !== 'active') {
    return { allowed: false, reason: 'SESSION_INACTIVE' };
  }
  return evaluateFableLoomLiveInput({
    node,
    phase: session.playbackPhase,
    asset,
  });
}

/**
 * Create an explicit hosted play session.
 */
export async function createHostedSession(loomId, episodeId, {
  audioTarget = 'host',
  startNodeId,
  ttlMinutes = DEFAULT_SESSION_TTL_MINUTES,
  baseUrl,
} = {}) {
  const loom = await getLoom(loomId);
  if (!loom) {
    throw new ServerError('Loom not found', { status: 404, code: 'NOT_FOUND' });
  }
  const episode = loom.episodes?.find((e) => e.id === episodeId) || null;
  if (!episode) {
    throw new ServerError('Episode not found', { status: 404, code: 'NOT_FOUND' });
  }

  // Run preflight readiness
  const preflight = await checkHostedSessionReadiness({ loomId, episodeId, loom, episode });
  if (!preflight.ready) {
    throw new ServerError(`Hosted session preflight failed: ${preflight.errors.join('; ')}`, {
      status: 412,
      code: 'HOSTED_SESSION_PREFLIGHT_FAILED',
      context: preflight,
    });
  }

  const startNode = episode.nodes?.find((n) => n.id === (startNodeId || episode.startNodeId)) || null;
  if (!startNode) {
    throw new ServerError('Start scene not found', { status: 400, code: 'INVALID_START_NODE' });
  }

  const sessionId = randomUUID();
  // Generate 256-bit cryptographically secure tokens. The audience (QR/join
  // link) token and the host token are DISTINCT secrets — the audience token
  // must never grant `role: 'host'` (#8357), so each is hashed and verified
  // independently.
  const token = randomBytes(32).toString('hex');
  const hashedToken = createHash('sha256').update(token).digest('hex');
  const hostToken = randomBytes(32).toString('hex');
  const hashedHostToken = createHash('sha256').update(hostToken).digest('hex');

  const boundedTtl = Math.max(1, Math.min(MAX_SESSION_TTL_MINUTES, Number.isInteger(ttlMinutes) ? ttlMinutes : DEFAULT_SESSION_TTL_MINUTES));
  const now = new Date();
  const expiresAt = new Date(now.getTime() + boundedTtl * 60 * 1000).toISOString();

  const rootBaseUrl = baseUrl || preflight.https.url;
  // Fragment-based QR URL: #session=...&token=... — carries ONLY the audience
  // token. The host token is returned in the create response and never
  // appears here.
  const joinUrl = `${rootBaseUrl}/fableloom/join#session=${sessionId}&token=${token}`;

  const session = {
    id: sessionId,
    loomId,
    episodeId,
    universeId: loom.universeId || null,
    hashedToken,
    hashedHostToken,
    status: 'active',
    audioTarget: FABLELOOM_AUDIO_TARGETS.includes(audioTarget) ? audioTarget : 'host',
    currentNodeId: startNode.id,
    playbackPhase: initialPhaseForNode(startNode),
    activeHoldIndex: 0,
    turnPhase: 'idle',
    transcript: [{
      id: randomUUID(),
      role: 'narrator',
      text: startNode.prose || startNode.title || '',
      timestamp: now.toISOString(),
    }],
    recentTts: [],
    hostSocketId: null,
    audienceSocketId: null,
    activeTurn: null,
    pendingSpeech: null,
    sceneGeneration: 0,
    switchingEpisode: false,
    episodeSwitchGeneration: 0,
    createdAt: now.toISOString(),
    expiresAt,
  };

  activeSessions.set(sessionId, session);

  return {
    session: sanitizeHostedSession(session),
    token, // audience token — returned ONLY once to session creator; also embedded in joinUrl
    hostToken, // host token — returned ONLY once to session creator; NEVER embedded in joinUrl
    joinUrl,
    preflight,
  };
}

/** Shared constant-time comparison against a session's stored token hash. */
function verifyHostedTokenAgainst(sessionId, token, hashField) {
  if (!sessionId || !token || typeof token !== 'string') return false;
  const session = activeSessions.get(sessionId);
  if (session?.status !== 'active') return false;
  if (isExpired(session)) {
    session.status = 'ended';
    return false;
  }
  const storedHash = session[hashField];
  if (!storedHash) return false;
  const candidateHash = createHash('sha256').update(token).digest('hex');
  const storedBuf = Buffer.from(storedHash, 'hex');
  const candidateBuf = Buffer.from(candidateHash, 'hex');
  if (storedBuf.length !== candidateBuf.length) return false;
  return timingSafeEqual(storedBuf, candidateBuf);
}

/**
 * Verify the AUDIENCE join token for a hosted session using constant-time
 * comparison. Does not grant the host role — see `verifyHostedHostToken`.
 */
export function verifyHostedToken(sessionId, token) {
  return verifyHostedTokenAgainst(sessionId, token, 'hashedToken');
}

/**
 * Verify the HOST token for a hosted session using constant-time comparison
 * (#8357). This token is distinct from the audience join token embedded in
 * the QR `joinUrl` — the audience token must never authorize `role: 'host'`.
 */
export function verifyHostedHostToken(sessionId, token) {
  return verifyHostedTokenAgainst(sessionId, token, 'hashedHostToken');
}

/**
 * Retrieve active session by ID.
 */
export function getHostedSession(sessionId) {
  if (!sessionId) return null;
  const session = activeSessions.get(sessionId);
  if (!session) return null;
  if (session.status === 'active' && isExpired(session)) {
    session.status = 'ended';
  }
  return sanitizeHostedSession(session);
}

/**
 * Internal session record retrieval for socket and service operations.
 *
 * Evaluates the TTL, so an expired record reads as absent even when nothing has
 * swept it yet — that is what stops a host reconnecting into the
 * `/fableloom-hosted` namespace minutes after its session should have died.
 */
export function _getInternalSession(sessionId) {
  const session = activeSessions.get(sessionId);
  if (!session) return null;
  if (session.status === 'active' && isExpired(session)) {
    session.status = 'ended';
  }
  if (session.status !== 'active') return null;
  return session;
}

/**
 * Update hosted session state (e.g. audio target, playback phase, current node).
 *
 * `currentNodeId` is validated against the session's CURRENT `episodeId` (only
 * when it actually changes — a phase/hold-index-only update skips the lookup).
 * Without this, a client that drifted from the server's episode (the host
 * advanced an episode without the server learning about it, #8112) would push
 * a node id that belongs to a different episode's graph; the audience's next
 * turn then resolves `findNode` against the WRONG episode, throws "Scene not
 * found", and silently falls back to canned narration with no visible error.
 * Rejecting here fails loudly instead, so a future client bug can't degrade
 * the same way in silence.
 */
export async function updateHostedSession(sessionId, patch = {}, { io } = {}) {
  const session = activeSessions.get(sessionId);
  if (session?.status !== 'active') {
    throw new ServerError('Hosted session not found or ended', { status: 404, code: 'SESSION_NOT_FOUND' });
  }

  // A `switchHostedEpisode` in flight is about to overwrite currentNodeId /
  // playbackPhase / activeHoldIndex with the NEW episode's values anyway. The
  // client's playback-sync effect fires on the very next React commit — well
  // before the switch's async loom-read/preflight work resolves server-side
  // — so a `currentNodeId` racing in during that window legitimately belonged
  // to the OLD episode a moment ago. Treat it as stale and no-op rather than
  // reject it as a `NODE_NOT_IN_EPISODE` bug (#8112).
  if (session.switchingEpisode) {
    return sanitizeHostedSession(session);
  }

  if (patch.audioTarget && FABLELOOM_AUDIO_TARGETS.includes(patch.audioTarget)) {
    session.audioTarget = patch.audioTarget;
  }
  if (patch.currentNodeId && patch.currentNodeId !== session.currentNodeId) {
    const loom = await getLoom(session.loomId);
    const episode = loom?.episodes?.find((e) => e.id === session.episodeId) || null;
    const nodeBelongsToEpisode = !!episode?.nodes?.some((n) => n.id === patch.currentNodeId);
    if (!nodeBelongsToEpisode) {
      throw new ServerError('currentNodeId does not belong to the hosted session\'s current episode', {
        status: 400,
        code: 'NODE_NOT_IN_EPISODE',
      });
    }
    session.currentNodeId = patch.currentNodeId;
    session.sceneGeneration += 1;
    // The host left the scene this narration was spoken against. Dropping the
    // wait here is what stops a late playback ack from committing that move
    // onto the scene the host already left.
    cancelPendingSpeech(session, sessionId, { io, reason: 'node_changed' });
  }
  if (patch.playbackPhase) {
    session.playbackPhase = patch.playbackPhase;
  }
  if (Number.isInteger(patch.activeHoldIndex)) {
    session.activeHoldIndex = patch.activeHoldIndex;
  }

  const sanitized = sanitizeHostedSession(session);
  if (io) {
    io.of('/fableloom-hosted').to(`session:${sessionId}`).emit('hosted:session:sync', sanitized);
  }
  return sanitized;
}

/**
 * Re-bind a hosted session to a different episode of the same loom, so the
 * audience's phone stays connected across an episode transition instead of
 * being silently stranded on the old episode's graph (#8112).
 *
 * Aborts any in-flight turn against the OLD episode first (a turn that
 * resolves mid-switch must not land narration/a transition against the new
 * one), re-runs the same readiness preflight `createHostedSession` requires,
 * and — on failure — ends the session outright via `endHostedSession` rather
 * than leaving it half-bound to an episode that can't play. Resets
 * `currentNodeId` to the new episode's opening node and clears the
 * transcript/turnPhase so the audience view starts clean.
 */
export async function switchHostedEpisode(sessionId, episodeId, { io } = {}) {
  const session = activeSessions.get(sessionId);
  if (session?.status !== 'active') {
    throw new ServerError('Hosted session not found or ended', { status: 404, code: 'SESSION_NOT_FOUND' });
  }

  // Serializes switches — without it, two overlapping calls (a host
  // double-clicking "Next Episode" before the first one's async work
  // resolves) could race and let the EARLIER request commit last, rebinding
  // the session to an episode the UI has already left.
  if (session.switchingEpisode) {
    throw new ServerError('An episode switch is already in progress', { status: 409, code: 'EPISODE_SWITCH_IN_PROGRESS' });
  }

  // Abort BEFORE the first await: a turn already in flight against the OLD
  // episode must not be able to resolve and commit narration/a transition
  // while this function is off awaiting the loom read below. Clear the speech
  // wait in the same turn so its timer cannot emit that transition later.
  cancelPendingSpeech(session, sessionId, { io, reason: 'episode_switch' });
  if (session.activeTurn?.abortController) {
    session.activeTurn.abortController.abort('episode_switch');
    session.activeTurn = null;
  }
  session.sceneGeneration += 1;
  // Blocks `startHostedListening` from starting a NEW turn for the rest of
  // this function — without it, a turn that starts during the awaits below
  // would run against the OLD episode and could commit/emit AFTER this
  // switch's `hosted:session:sync`, mixing old-episode content into the new
  // episode. Always cleared in `finally`, including on every early return.
  session.switchingEpisode = true;
  session.episodeSwitchGeneration += 1;

  // Re-checked after every await below — a host "end", DELETE /sessions/:id,
  // or the TTL sweep can tear this session down while we're off reading the
  // loom or running preflight. Without this a switch that loses that race
  // would resurrect a deleted session's state and emit `hosted:session:sync`
  // AFTER the room already saw the terminal `hosted:session:ended`.
  const isLive = () => activeSessions.get(sessionId) === session && session.status === 'active';

  try {
    const loom = await getLoom(session.loomId);
    if (!isLive()) return { ok: false, ended: true, reason: 'session_ended' };
    if (!loom) {
      throw new ServerError('Loom not found', { status: 404, code: 'NOT_FOUND' });
    }
    const episode = findEpisode(loom, episodeId);

    const preflight = await checkHostedSessionReadiness({ loomId: session.loomId, episodeId, loom, episode });
    if (!isLive()) return { ok: false, ended: true, reason: 'session_ended' };
    const startNode = preflight.ready
      ? episode.nodes?.find((n) => n.id === episode.startNodeId) || null
      : null;
    if (!preflight.ready || !startNode) {
      endHostedSession(sessionId, { reason: 'episode_not_ready', io });
      return { ok: false, ended: true, reason: 'episode_not_ready', preflight };
    }

    return commitHostedEpisodeSwitch(session, sessionId, episodeId, startNode, { io });
  } finally {
    session.switchingEpisode = false;
  }
}

function commitHostedEpisodeSwitch(session, sessionId, episodeId, startNode, { io }) {
  const now = new Date();
  session.episodeId = episodeId;
  session.currentNodeId = startNode.id;
  session.playbackPhase = initialPhaseForNode(startNode);
  session.activeHoldIndex = 0;
  session.turnPhase = 'idle';
  session.transcript = [{
    id: randomUUID(),
    role: 'narrator',
    text: startNode.prose || startNode.title || '',
    timestamp: now.toISOString(),
  }];
  session.recentTts = [];

  const sanitized = sanitizeHostedSession(session);
  if (io) {
    io.of('/fableloom-hosted').to(`session:${sessionId}`).emit('hosted:session:sync', sanitized);
  }
  return { ok: true, session: sanitized };
}

/**
 * End a hosted session and notify connected clients.
 */
export function endHostedSession(sessionId, { reason = 'ended', io } = {}) {
  const session = activeSessions.get(sessionId);
  if (!session) return { ok: true };

  // Take the timer before the session leaves the map. A timeout that fires
  // after `hosted:session:ended` must not emit a transition into a dead room.
  takePendingSpeech(session);
  if (session.activeTurn?.abortController) {
    session.activeTurn.abortController.abort(reason);
    session.activeTurn = null;
  }

  session.status = 'ended';
  session.turnPhase = 'ended';

  if (io) {
    const ns = io.of('/fableloom-hosted');
    ns.to(`session:${sessionId}`).emit('hosted:session:ended', { sessionId, reason });
  }

  activeSessions.delete(sessionId);
  return { ok: true };
}

/**
 * Start audience listening phase on the session.
 */
export async function startHostedListening(sessionId, { io } = {}) {
  const session = activeSessions.get(sessionId);
  if (session?.status !== 'active') {
    throw new ServerError('Session is not active', { status: 400, code: 'SESSION_INACTIVE' });
  }

  // `switchHostedEpisode` holds this while it's off awaiting the loom read
  // and readiness preflight. Without this gate a turn could start against the
  // OLD episode mid-switch, then commit and emit AFTER the new episode's
  // `hosted:session:sync` — mixing old-episode content into the new episode.
  if (session.switchingEpisode) {
    throw new ServerError('An episode switch is in progress', { status: 409, code: 'EPISODE_SWITCH_IN_PROGRESS' });
  }

  // Reserve admission before the loom read so simultaneous mic/text starts
  // cannot replace each other's active turn while their gate checks await.
  if (session.startingListening) {
    throw new ServerError('A turn is already starting', { status: 409, code: 'TURN_IN_PROGRESS' });
  }
  session.startingListening = true;
  try {
    const episodeId = session.episodeId;
    const switchGeneration = session.episodeSwitchGeneration;
    const loom = await getLoom(session.loomId);
    if (activeSessions.get(sessionId) !== session || session.status !== 'active') {
      throw new ServerError('Session is not active', { status: 400, code: 'SESSION_INACTIVE' });
    }
    if (session.switchingEpisode || session.episodeSwitchGeneration !== switchGeneration || session.episodeId !== episodeId) {
      throw new ServerError('Session changed while starting the listening turn', { status: 409, code: 'EPISODE_SWITCH_IN_PROGRESS' });
    }

    const episode = loom.episodes?.find((e) => e.id === episodeId) || null;
    const node = episode?.nodes?.find((n) => n.id === session.currentNodeId) || null;
    const asset = resolvePlaybackPhaseAsset({
      node,
      phase: session.playbackPhase,
      activeHoldIndex: session.activeHoldIndex,
    });

    const gate = revalidateLiveConversationGate({ session, node, asset });
    if (!gate.allowed) {
      throw new ServerError(`Live voice conversation is not permitted: ${gate.reason}`, {
        status: 409,
        code: gate.reason,
      });
    }

    if (session.turnPhase === 'speaking' || session.turnPhase === 'thinking') {
      throw new ServerError('A turn is already in progress', { status: 409, code: 'TURN_IN_PROGRESS' });
    }

    const turnId = randomUUID();
    session.turnPhase = 'listening';
    session.activeTurn = {
      id: turnId,
      abortController: new AbortController(),
      startedAt: Date.now(),
    };

    if (io) {
      io.of('/fableloom-hosted').to(`session:${sessionId}`).emit('hosted:turn:phase', {
        phase: 'listening',
        turnId,
      });
    }

    return { ok: true, turnId };
  } finally {
    session.startingListening = false;
  }
}

function emitHosted(io, sessionId, event, payload) {
  if (!io) return;
  io.of('/fableloom-hosted').to(`session:${sessionId}`).emit(event, payload);
}

function designatedOutputSocketId(session) {
  if (!session) return null;
  return session.audioTarget === 'audience' ? session.audienceSocketId : session.hostSocketId;
}

function takePendingSpeech(session) {
  const pending = session?.pendingSpeech;
  if (!pending) return null;
  if (pending.timer) clearTimeout(pending.timer);
  pending.timer = null;
  session.pendingSpeech = null;
  return pending;
}

// Drop a playback wait without committing its transition. `emit` is false when
// the caller is about to publish its own terminal phase (session end).
function cancelPendingSpeech(session, sessionId, { io, reason, emit = true } = {}) {
  const pending = takePendingSpeech(session);
  if (!pending) return false;
  if (session.activeTurn?.id === pending.turnId) {
    session.activeTurn.abortController?.abort(reason);
    session.activeTurn = null;
  }
  if (!emit || session.status !== 'active' || session.turnPhase !== 'speaking') return true;
  session.turnPhase = 'idle';
  emitHosted(io, sessionId, 'hosted:turn:phase', { phase: 'idle', turnId: pending.turnId, reason });
  return true;
}

function expireHostedSpeech(sessionId, turnId, io) {
  const session = activeSessions.get(sessionId);
  if (!session || session.status !== 'active') return;
  const pending = session.pendingSpeech;
  if (!pending || pending.turnId !== turnId) return;
  // A switch or scene change already owns the outcome. Clearing here must not
  // publish a phase (or a transition) for a turn the room has left.
  if (session.switchingEpisode
    || session.episodeSwitchGeneration !== pending.episodeSwitchGeneration
    || session.sceneGeneration !== pending.sceneGeneration
    || session.currentNodeId !== pending.sourceNodeId) {
    takePendingSpeech(session);
    return;
  }
  cancelPendingSpeech(session, sessionId, { io, reason: 'speech_timeout' });
  console.log(`⏭️ Hosted speech ${turnId} timed out before playback completion`);
}

function armPendingSpeech(session, sessionId, { io, turn, playResult, targetNode }) {
  const outputSocketId = designatedOutputSocketId(session);
  if (!outputSocketId) return false;
  const pending = {
    turnId: turn.id,
    target: session.audioTarget === 'audience' ? 'audience' : 'host',
    outputSocketId,
    episodeId: session.episodeId,
    episodeSwitchGeneration: session.episodeSwitchGeneration,
    sceneGeneration: session.sceneGeneration,
    sourceNodeId: session.currentNodeId,
    action: targetNode ? 'move' : 'stay',
    transitionId: targetNode ? playResult.transitionId : null,
    targetNodeId: targetNode?.id || null,
    timer: null,
  };
  pending.timer = setTimeout(() => {
    try {
      expireHostedSpeech(sessionId, pending.turnId, io);
    } catch (err) {
      console.error(`❌ Hosted speech timeout failed: ${err.message}`);
    }
  }, HOSTED_SPEECH_ACK_TIMEOUT_MS);
  pending.timer.unref?.();
  session.pendingSpeech = pending;
  turn.outputSocketId = outputSocketId;
  return true;
}

function commitHostedMove(session, sessionId, { io, loom, targetNode, transitionId }) {
  session.currentNodeId = targetNode.id;
  session.playbackPhase = initialPhaseForNode(targetNode);
  session.activeHoldIndex = 0;
  session.sceneGeneration += 1;
  session.turnPhase = 'idle';
  session.activeTurn = null;
  emitHosted(io, sessionId, 'hosted:story:transition', {
    node: publicNode(targetNode, loom),
    transitionId,
    playbackPhase: session.playbackPhase,
  });
}

function releaseHostedStay(session, sessionId, { io, turnId }) {
  session.turnPhase = 'listening';
  session.activeTurn = null;
  emitHosted(io, sessionId, 'hosted:turn:phase', { phase: 'listening', turnId });
}

function speechClaimStillCurrent(session, sessionId, claim) {
  return activeSessions.get(sessionId) === session
    && session.status === 'active'
    && !session.switchingEpisode
    && session.turnPhase === 'speaking'
    && session.activeTurn?.id === claim.turnId
    && !session.activeTurn.abortController.signal.aborted
    && session.episodeId === claim.episodeId
    && session.episodeSwitchGeneration === claim.episodeSwitchGeneration
    && session.sceneGeneration === claim.sceneGeneration
    && session.currentNodeId === claim.sourceNodeId;
}

/**
 * Finish or drop the narration that `processHostedUtterance` left in `speaking`.
 *
 * Only the designated output socket's current-turn `ended` commits, and only
 * after the session, episode, and scene generations still match the dispatch.
 * Anything else leaves the node where it was.
 */
export async function acknowledgeHostedSpeech(sessionId, {
  turnId,
  role,
  socketId,
  status,
  io,
} = {}) {
  const session = _getInternalSession(sessionId);
  const pending = session?.pendingSpeech;
  if (!session || !pending) return { accepted: false, reason: 'NO_PENDING_SPEECH' };
  if (pending.turnId !== turnId) return { accepted: false, reason: 'STALE_TURN' };
  if (role !== pending.target) return { accepted: false, reason: 'WRONG_ROLE' };
  if (!socketId || socketId !== pending.outputSocketId) return { accepted: false, reason: 'WRONG_SOCKET' };
  if (!speechClaimStillCurrent(session, sessionId, pending)) return { accepted: false, reason: 'STALE_TURN' };
  if (status !== 'ended' && status !== 'failed' && status !== 'aborted') {
    return { accepted: false, reason: 'INVALID_STATUS' };
  }

  if (status === 'ended' && pending.acknowledging) return { accepted: false, reason: 'ACKNOWLEDGEMENT_IN_PROGRESS' };
  // Keep the original deadline while the authoritative scene read is pending.
  // Its timeout invalidates this turn, so a delayed read cannot commit later.
  const claim = status === 'ended' ? pending : takePendingSpeech(session);
  if (status !== 'ended') {
    if (session.activeTurn?.id === claim.turnId) {
      session.activeTurn.abortController?.abort(status === 'failed' ? 'playback_failed' : 'playback_aborted');
      session.activeTurn = null;
    }
    if (session.turnPhase === 'speaking') {
      session.turnPhase = 'idle';
      emitHosted(io, sessionId, 'hosted:turn:phase', {
        phase: 'idle',
        turnId: claim.turnId,
        reason: status === 'failed' ? 'playback_failed' : 'playback_aborted',
      });
    }
    return { accepted: true, committed: false };
  }

  claim.acknowledging = true;
  try {
    const loom = await getLoom(session.loomId);
    if (!speechClaimStillCurrent(session, sessionId, claim)) {
      // The scene changed while this acknowledgement was being checked.
      // Release this speaking turn without changing a successor's state.
      if (activeSessions.get(sessionId) === session
        && session.status === 'active'
        && session.turnPhase === 'speaking'
        && session.activeTurn?.id === claim.turnId) {
        session.activeTurn.abortController?.abort('speech_superseded');
        session.activeTurn = null;
        session.turnPhase = 'idle';
        emitHosted(io, sessionId, 'hosted:turn:phase', {
          phase: 'idle',
          turnId: claim.turnId,
          reason: 'speech_superseded',
        });
      }
      return { accepted: false, committed: false, reason: 'STALE_TURN' };
    }
    if (claim.action !== 'move') {
      releaseHostedStay(session, sessionId, { io, turnId: claim.turnId });
      return { accepted: true, committed: true };
    }
    const episode = loom?.episodes?.find((item) => item.id === claim.episodeId) || null;
    const source = episode?.nodes?.find((node) => node.id === claim.sourceNodeId) || null;
    const transition = source?.transitions?.find((item) => item.id === claim.transitionId) || null;
    const targetNode = episode?.nodes?.find((node) => node.id === claim.targetNodeId) || null;
    if (!transition || transition.targetNodeId !== claim.targetNodeId || !targetNode) {
      session.activeTurn = null;
      session.turnPhase = 'idle';
      emitHosted(io, sessionId, 'hosted:turn:phase', {
        phase: 'idle',
        turnId: claim.turnId,
        reason: 'transition_unavailable',
      });
      return { accepted: true, committed: false, reason: 'TRANSITION_UNAVAILABLE' };
    }
    commitHostedMove(session, sessionId, {
      io,
      loom,
      targetNode,
      transitionId: claim.transitionId,
    });
    return { accepted: true, committed: true };
  } catch (err) {
    if (speechClaimStillCurrent(session, sessionId, claim)) {
      session.activeTurn = null;
      session.turnPhase = 'idle';
      emitHosted(io, sessionId, 'hosted:turn:phase', {
        phase: 'idle',
        turnId: claim.turnId,
        reason: 'speech_commit_failed',
      });
    }
    console.error(`❌ Hosted speech commit failed: ${err?.message || err}`);
    return { accepted: false, committed: false, reason: 'COMMIT_FAILED' };
  } finally {
    if (session.pendingSpeech === claim) takePendingSpeech(session);
  }
}

/**
 * The designated output disconnected while its narration was still in flight.
 * A replacement socket must not inherit the wait: it never played this audio.
 */
export function releaseHostedSpeechOutput(sessionId, socketId, { io } = {}) {
  const session = activeSessions.get(sessionId);
  if (!session || session.status !== 'active' || !socketId) return { released: false };
  const pendingMatches = session.pendingSpeech?.outputSocketId === socketId;
  const claimedMatches = session.turnPhase === 'speaking' && session.activeTurn?.outputSocketId === socketId;
  if (!pendingMatches && !claimedMatches) return { released: false };
  if (pendingMatches) cancelPendingSpeech(session, sessionId, { io, reason: 'output_disconnected' });
  else if (session.activeTurn?.outputSocketId === socketId) {
    const turnId = session.activeTurn.id;
    session.activeTurn.abortController?.abort('output_disconnected');
    session.activeTurn = null;
    session.turnPhase = 'idle';
    emitHosted(io, sessionId, 'hosted:turn:phase', {
      phase: 'idle',
      turnId,
      reason: 'output_disconnected',
    });
  }
  return { released: true };
}

/**
 * Process a completed audience utterance (audio or text) through STT -> LLM -> TTS -> State Transition.
 */
export async function processHostedUtterance(sessionId, {
  audioBuffer = null,
  textMessage = null,
  io,
} = {}) {
  const session = activeSessions.get(sessionId);
  if (session?.status !== 'active') {
    throw new ServerError('Session is not active', { status: 400, code: 'SESSION_INACTIVE' });
  }

  if (session.turnPhase !== 'listening') {
    // Drop frames/utterances received outside LISTENING phase
    return { dropped: true, reason: 'NOT_IN_LISTENING_PHASE' };
  }

  const turn = session.activeTurn || { id: randomUUID(), abortController: new AbortController(), startedAt: Date.now() };
  session.activeTurn = turn;
  session.turnPhase = 'thinking';

  // This function holds `session` and `turn` across every provider await, but a
  // teardown landing mid-turn (host "end", DELETE /sessions/:id, or the TTL
  // sweep) aborts the controller, clears `activeTurn` and drops the map entry.
  // Re-derive liveness at each boundary so no provider work starts — and no
  // frame is emitted — after the terminal `hosted:session:ended` (#5786).
  const isLive = () => !turn.abortController.signal.aborted
    && activeSessions.get(sessionId) === session
    && session.status === 'active'
    && session.activeTurn === turn;

  const emitIfLive = (event, payload) => {
    if (io && isLive()) io.of('/fableloom-hosted').to(`session:${sessionId}`).emit(event, payload);
  };

  const abandonedResult = { ok: true, aborted: true, turnId: turn.id };
  const abandonTurn = (stage) => {
    console.log(`🛑 Hosted turn ${turn.id} abandoned during ${stage} — session no longer live`);
    return abandonedResult;
  };

  emitIfLive('hosted:turn:phase', { phase: 'thinking', turnId: turn.id });

  try {
    let message = textMessage || '';

    // 1. Transcribe audio if supplied
    if (audioBuffer && !message.trim()) {
      let wavPayload = audioBuffer;
      if (audioBuffer instanceof Int16Array || (ArrayBuffer.isView(audioBuffer) && !(audioBuffer instanceof Buffer))) {
        const floatPcm = pcmToFloat(audioBuffer);
        wavPayload = pcmToWavBuffer(floatPcm, { sampleRate: 16000 });
      }
      const sttResult = await transcribe(wavPayload, { signal: turn.abortController.signal }).catch((err) => {
        // A torn-down turn aborts this signal. That is a cancellation, not a
        // successful empty transcription, and must not fall through as one.
        if (turn.abortController.signal.aborted) return null;
        console.warn(`⚠️ [HostedPlay] STT transcription failed: ${err.message}`);
        return { text: '' };
      });
      if (!sttResult || !isLive()) return abandonTurn('transcription');
      message = (sttResult.text || '').trim();
    }

    // Check for echo / empty message
    if (!message.trim() || isEchoOfRecentTts(message, session.recentTts)) {
      session.turnPhase = 'listening';
      emitIfLive('hosted:turn:phase', {
        phase: 'listening',
        turnId: turn.id,
        note: 'ignored-echo-or-empty',
      });
      return { ok: true, ignored: true };
    }

    // Append audience transcript item
    const audienceItem = {
      id: randomUUID(),
      role: 'audience',
      text: message,
      timestamp: new Date().toISOString(),
    };
    session.transcript.push(audienceItem);
    if (session.transcript.length > 50) session.transcript.shift();

    emitIfLive('hosted:turn:transcript', audienceItem);

    // 2. Run LLM Play Turn
    const loom = await getLoom(session.loomId);
    if (!isLive()) return abandonTurn('loom load');
    const episode = loom.episodes?.find((e) => e.id === session.episodeId) || null;
    const node = episode?.nodes?.find((n) => n.id === session.currentNodeId) || null;

    let playResult;
    try {
      playResult = await playTurn(session.loomId, session.episodeId, {
        nodeId: session.currentNodeId,
        message,
        signal: turn.abortController.signal,
        callerPolicy: 'direct-api',
        transcript: session.transcript.map((t) => ({
          role: t.role === 'audience' ? 'reader' : 'narrator',
          text: t.text,
        })),
      });
    } catch (err) {
      // A cancelled turn has no one left to narrate to — the authored fallback
      // would only produce a reply for a room that already saw `ended`.
      if (!isLive()) return abandonTurn('story turn');
      console.warn(`⚠️ [HostedPlay] LLM turn error, using authored fallback: ${err?.message}`);
      playResult = {
        action: 'stay',
        narration: node?.prose?.slice(0, 200) || "I hear you. Let's see what happens next.",
        node: node ? publicNode(node, loom) : null,
        ended: false,
      };
    }
    if (!isLive()) return abandonTurn('story turn');

    const narration = (playResult?.narration || '').trim() || "Let's continue.";

    // Append protagonist transcript item
    const protagonistItem = {
      id: randomUUID(),
      role: 'protagonist',
      text: narration,
      timestamp: new Date().toISOString(),
      audioTarget: session.audioTarget,
    };
    session.transcript.push(protagonistItem);
    if (session.transcript.length > 50) session.transcript.shift();

    // 3. Synthesize Protagonist Voice
    session.turnPhase = 'speaking';
    rememberTtsSentence(session.recentTts, narration);

    emitIfLive('hosted:turn:phase', { phase: 'speaking', turnId: turn.id, text: narration });
    emitIfLive('hosted:turn:transcript', protagonistItem);

    // Resolve character voice
    let ttsAudio = null;
    try {
      let universe = null;
      if (loom.universeId) {
        universe = await getUniverse(loom.universeId).catch(() => null);
      }
      const char = protagonistVoiceCharacter(loom, universe);
      const resolved = await resolveCharacterVoice({
        universeId: loom.universeId,
        characterId: char?.id,
        characterVoiceId: char?.voiceId,
        route: 'interactive',
      }).catch(() => null);
      if (!isLive()) return abandonTurn('voice resolution');
      const { engine, voice } = parseVoiceId(resolved?.voiceId);

      const synth = await synthesize(narration, {
        engine: engine || undefined,
        profileId: resolved?.profileId || undefined,
        route: 'interactive',
        signal: turn.abortController.signal,
        voice: voice || undefined,
      }).catch((err) => {
        if (turn.abortController.signal.aborted) return null;
        console.warn(`⚠️ [HostedPlay] Protagonist TTS synthesis failed: ${err.message}`);
        return null;
      });
      if (synth?.wav) {
        ttsAudio = synth.wav;
      }
    } catch (err) {
      console.warn(`⚠️ [HostedPlay] Protagonist TTS synthesis failed: ${err.message}`);
    }
    if (!isLive()) return abandonTurn('speech synthesis');

    const targetNode = playResult.action === 'move' && playResult.transitionId && episode
      ? episode.nodes?.find((node) => node.id === playResult.node?.id) || null
      : null;

    // 4. Dispatch audio to the designated output. While that socket is
    // connected, the move stays pending: committing here is what let the
    // scene change under audio that was still playing.
    if (ttsAudio) {
      emitIfLive('hosted:turn:tts', {
        audio: Buffer.isBuffer(ttsAudio) ? ttsAudio.toString('base64') : Buffer.from(ttsAudio).toString('base64'),
        mimeType: 'audio/wav',
        target: session.audioTarget,
        turnId: turn.id,
      });
    }
    if (!isLive()) return abandonTurn('speech dispatch');

    if (ttsAudio && armPendingSpeech(session, sessionId, { io, turn, playResult, targetNode })) {
      return { ok: true, awaitingSpeech: true, turnId: turn.id, playResult };
    }

    // No audio (synthesis failed) or no connected output: nothing is playing,
    // so the narration text is the whole delivery and the turn commits now.
    if (targetNode) {
      commitHostedMove(session, sessionId, {
        io,
        loom,
        targetNode,
        transitionId: playResult.transitionId,
      });
    } else {
      releaseHostedStay(session, sessionId, { io, turnId: turn.id });
    }
    return { ok: true, playResult };
  } catch (err) {
    // A failure that lands after teardown has no room left to tell: the session
    // already emitted its terminal frame, so log and swallow rather than
    // emitting `hosted:error` behind it.
    if (!isLive()) {
      takePendingSpeech(session);
      console.warn(`⚠️ [HostedPlay] Hosted turn ${turn.id} failed after teardown: ${err?.message || err}`);
      return abandonedResult;
    }
    takePendingSpeech(session);
    // Emit BEFORE clearing `activeTurn` — clearing it first makes the turn
    // non-live and would suppress the very error frame the client needs.
    emitIfLive('hosted:error', {
      code: err?.code || 'TURN_FAILED',
      message: err?.message || String(err),
    });
    // Without a phase frame every client stays in `thinking` (mic and text
    // input disabled) until a reload resyncs.
    session.turnPhase = 'idle';
    emitIfLive('hosted:turn:phase', { phase: 'idle', turnId: turn.id });
    session.activeTurn = null;
    // Tells the socket handlers this failure already reached the room.
    if (err && typeof err === 'object') err.hostedReported = true;
    throw err;
  }
}

/**
 * Abort current in-flight turn.
 */
export function abortHostedTurn(sessionId, { reason = 'aborted', io } = {}) {
  const session = activeSessions.get(sessionId);
  if (!session) return { ok: true };

  const turnId = session.pendingSpeech?.turnId || session.activeTurn?.id || null;
  takePendingSpeech(session);
  if (session.activeTurn?.abortController) {
    session.activeTurn.abortController.abort(reason);
    session.activeTurn = null;
  }
  session.turnPhase = 'idle';

  if (io) {
    io.of('/fableloom-hosted').to(`session:${sessionId}`).emit('hosted:turn:phase', {
      phase: 'idle',
      reason,
      ...(turnId ? { turnId } : {}),
    });
  }
  return { ok: true };
}

let sweepTimer = null;
let sweepIo = null;

/**
 * Arm the expired-session sweeper.
 *
 * Expiry used to be evaluated only when something happened to look a session up,
 * and even then it just flipped `status` — so the normal end of a QR play
 * session (guest closes the tab, host navigates away) left the record, its node
 * history and its live `AbortController` resident for the process lifetime, and
 * the room never saw `hosted:session:ended`. The sweep reuses `endHostedSession`
 * so teardown stays in one place.
 */
export function startHostedSessionSweep({ intervalMs = HOSTED_SESSION_SWEEP_INTERVAL_MS, io = null } = {}) {
  sweepIo = io || sweepIo;
  if (sweepTimer) return sweepTimer;
  sweepTimer = setInterval(() => {
    // Timer callback — outside the request lifecycle, so an uncaught throw here
    // would take the process down instead of reaching error middleware.
    try {
      sweepExpiredHostedSessions();
    } catch (err) {
      console.error(`❌ FableLoom hosted-session sweep failed: ${err.message}`);
    }
  }, intervalMs);
  sweepTimer.unref?.();
  return sweepTimer;
}

/** Disarm the sweeper (graceful shutdown, tests). */
export function stopHostedSessionSweep() {
  if (sweepTimer) clearInterval(sweepTimer);
  sweepTimer = null;
  sweepIo = null;
}

/**
 * Tear down every expired or already-ended session. Exported so a test (and a
 * future manual "clean up" action) can run one tick without waiting on wall time.
 */
export function sweepExpiredHostedSessions({ io = sweepIo } = {}) {
  const doomed = [];
  for (const [id, session] of activeSessions) {
    if (session.status !== 'active' || isExpired(session)) doomed.push(id);
  }
  for (const id of doomed) {
    endHostedSession(id, { reason: 'expired', io });
  }
  if (doomed.length) {
    console.log(`🧹 Swept ${doomed.length} expired FableLoom hosted session(s)`);
  }
  return doomed.length;
}

/**
 * Test helper to reset in-memory sessions between test runs.
 */
export function _resetHostedSessions() {
  stopHostedSessionSweep();
  for (const session of activeSessions.values()) {
    takePendingSpeech(session);
    if (session.activeTurn?.abortController) {
      session.activeTurn.abortController.abort('reset');
    }
  }
  activeSessions.clear();
}