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

48.7 KB
Raw Blame
import { describe, it, expect, afterEach, beforeEach, vi } from 'vitest';
import {
  _getInternalSession,
  _resetHostedSessions,
  HOSTED_SPEECH_ACK_TIMEOUT_MS,
  abortHostedTurn,
  acknowledgeHostedSpeech,
  checkHostedSessionReadiness,
  createHostedSession,
  endHostedSession,
  getHostedSession,
  initialPhaseForNode,
  processHostedUtterance,
  releaseHostedSpeechOutput,
  revalidateLiveConversationGate,
  startHostedListening,
  startHostedSessionSweep,
  stopHostedSessionSweep,
  switchHostedEpisode,
  updateHostedSession,
  verifyHostedHostToken,
  verifyHostedToken,
} from './hostedSession.js';
import { FABLELOOM_RUNTIME_VERSION } from '../../lib/fableLoomPlayback.js';
import * as records from './records.js';
import * as weave from './weave.js';
import * as networkExposure from '../../lib/networkExposure.js';
import * as tts from '../voice/tts.js';
import * as stt from '../voice/stt.js';
import * as voiceProfiles from '../voice/profiles.js';
import * as universeBuilder from '../universeBuilder.js';

describe('fableLoom hostedSession', () => {
  const mockLoom = {
    id: 'loom-1',
    name: 'Dragon Quest',
    format: 'prose',
    participationMode: 'helper',
    universeId: 'universe-1',
    episodes: [{
      id: 'ep-1',
      title: 'Episode 1',
      startNodeId: 'node-start',
      nodes: [
        {
          id: 'node-start',
          title: 'Forest Entrance',
          prose: 'You stand at the edge of the dark forest.',
          playbackMode: 'decision',
          audienceConnection: 'connected',
          protagonistPresence: 'offscreen',
          isEnding: false,
          playbackAssets: {
            holdLoopVideoHistoryIds: ['vid-hold-1'],
            audioOccupancy: {
              'vid-hold-1': { durationMs: 5000, characterDialogue: [], music: [], effects: [], safeForLiveVoice: true },
            },
          },
          transitions: [{ id: 'tr-1', targetNodeId: 'node-2', intent: 'enter forest', triggers: ['go into forest'] }],
        },
        {
          id: 'node-2',
          title: 'Deep Woods',
          prose: 'The trees tower above you.',
          playbackMode: 'decision',
          audienceConnection: 'connected',
          protagonistPresence: 'offscreen',
          isEnding: false,
          transitions: [],
        },
      ],
    }, {
      id: 'ep-2',
      title: 'Episode 2',
      startNodeId: 'node-ep2-start',
      nodes: [
        {
          id: 'node-ep2-start',
          title: 'Mountain Pass',
          prose: 'Snow crunches underfoot as you climb.',
          playbackMode: 'decision',
          audienceConnection: 'connected',
          protagonistPresence: 'offscreen',
          isEnding: false,
          transitions: [{ id: 'tr-ep2-1', targetNodeId: 'node-ep2-start', intent: 'keep climbing', triggers: ['climb'] }],
        },
      ],
    }, {
      id: 'ep-3-not-ready',
      title: 'Episode 3',
      startNodeId: 'missing-start-node',
      nodes: [],
    }],
  };

  // Hosted-session preflight gates on the live network posture. Every test
  // that isn't specifically exercising the HTTPS gate runs against this
  // TLS-provisioned snapshot so the rest of the readiness checks are what
  // the assertion is about.
  const httpsExposure = () => ({
    scheme: 'https',
    httpsEnabled: true,
    bind: { host: '0.0.0.0', port: 5555, audience: 'all-interfaces' },
    cert: { mode: 'tailscale', tailscaleHost: 'host-example.example-tailnet.ts.net' },
  });

  const httpExposure = () => ({
    ...httpsExposure(),
    scheme: 'http',
    httpsEnabled: false,
  });

  // A stub Socket.IO surface that records every namespace emit.
  const makeIo = () => {
    const emits = [];
    return {
      emits,
      of: () => ({
        to: (room) => ({
          emit: (event, payload) => emits.push({ room, event, payload }),
        }),
      }),
    };
  };

  // A promise the test resolves by hand, so one provider stage can be held
  // pending across a teardown without any real timing.
  const deferred = () => {
    let settle;
    const promise = new Promise((resolve, reject) => { settle = { resolve, reject }; });
    return { promise, ...settle };
  };

  beforeEach(() => {
    _resetHostedSessions();
    vi.restoreAllMocks();
    vi.spyOn(networkExposure, 'getNetworkExposureStatus').mockImplementation(httpsExposure);
    vi.spyOn(records, 'getLoom').mockResolvedValue(mockLoom);
    vi.spyOn(tts, 'synthesize').mockResolvedValue({
      wav: Buffer.from('RIFFmockwavdata'),
      latencyMs: 50,
      engine: 'kokoro',
    });
    vi.spyOn(stt, 'transcribe').mockResolvedValue({
      text: 'I want to enter the forest',
      latencyMs: 100,
    });
  });

  describe('initialPhaseForNode', () => {
    it('returns ended for ending nodes', () => {
      expect(initialPhaseForNode({ isEnding: true })).toBe('ended');
    });

    it('returns entry when entry clip is present', () => {
      expect(initialPhaseForNode({ playbackAssets: { entryVideoHistoryId: 'vid-entry-1' } })).toBe('entry');
    });

    it('returns hold when hold loops exist', () => {
      expect(initialPhaseForNode({ playbackAssets: { holdLoopVideoHistoryIds: ['vid-hold-1'] } })).toBe('hold');
    });
  });

  describe('checkHostedSessionReadiness', () => {
    it('passes readiness when loom, episode, and start scene are configured over HTTPS', async () => {
      const result = await checkHostedSessionReadiness({ loomId: 'loom-1', episodeId: 'ep-1' });
      expect(result.ready).toBe(true);
      expect(result.https.enabled).toBe(true);
      expect(result.https.url).toMatch(/^https:\/\//);
      expect(result.checks.https.ok).toBe(true);
      expect(result.checks.host.ok).toBe(true);
    });

    it('flags error when the install is serving plain HTTP', async () => {
      vi.spyOn(networkExposure, 'getNetworkExposureStatus').mockImplementation(httpExposure);
      const result = await checkHostedSessionReadiness({ loomId: 'loom-1', episodeId: 'ep-1' });
      expect(result.ready).toBe(false);
      expect(result.https.enabled).toBe(false);
      expect(result.checks.https.ok).toBe(false);
      expect(result.https.url).toMatch(/^http:\/\//);
      expect(result.errors).toContain(
        'HTTPS is required for mobile device QR microphone join (run npm run setup:cert to enable TLS).',
      );
    });

    it('flags error if start scene is missing', async () => {
      const badLoom = {
        ...mockLoom,
        episodes: [{ id: 'ep-1', startNodeId: 'missing-node', nodes: [] }],
      };
      vi.spyOn(records, 'getLoom').mockResolvedValue(badLoom);
      const result = await checkHostedSessionReadiness({ loomId: 'loom-1', episodeId: 'ep-1' });
      expect(result.ready).toBe(false);
      expect(result.errors).toContain('Episode does not have a valid start scene configured.');
    });
  });

  describe('createHostedSession & verifyHostedToken', () => {
    it('creates an active hosted session with hashed token and fragment join URL', async () => {
      const result = await createHostedSession('loom-1', 'ep-1', { audioTarget: 'host' });
      expect(result.session).toBeDefined();
      expect(result.session.id).toBeDefined();
      expect(result.session.status).toBe('active');
      expect(result.session.runtimeVersion).toBe(FABLELOOM_RUNTIME_VERSION);
      expect(result.session.audioTarget).toBe('host');
      expect(result.session.currentNodeId).toBe('node-start');
      expect(result.token).toBeDefined();
      expect(result.token.length).toBe(64); // 256 bits hex
      expect(result.joinUrl).toContain(`#session=${result.session.id}&token=${result.token}`);

      // Internal storage verifies hashed token
      const internal = _getInternalSession(result.session.id);
      expect(internal.hashedToken).toBeDefined();
      expect(internal.hashedToken).not.toBe(result.token); // Hashed, not plaintext

      // Sanitized session omits hashedToken
      const sanitized = getHostedSession(result.session.id);
      expect(sanitized.hashedToken).toBeUndefined();

      // Verify token
      expect(verifyHostedToken(result.session.id, result.token)).toBe(true);
      expect(verifyHostedToken(result.session.id, 'wrong-token')).toBe(false);
      expect(verifyHostedToken('missing-session', result.token)).toBe(false);
    });

    it('mints a separate host token that never appears in the join URL (#8357)', async () => {
      const result = await createHostedSession('loom-1', 'ep-1', { audioTarget: 'host' });
      expect(result.hostToken).toBeDefined();
      expect(result.hostToken.length).toBe(64); // 256 bits hex
      expect(result.hostToken).not.toBe(result.token);
      expect(result.joinUrl).not.toContain(result.hostToken);

      // Internal storage verifies hashed host token, distinct from the audience hash
      const internal = _getInternalSession(result.session.id);
      expect(internal.hashedHostToken).toBeDefined();
      expect(internal.hashedHostToken).not.toBe(internal.hashedToken);
      expect(internal.hashedHostToken).not.toBe(result.hostToken); // Hashed, not plaintext

      // Sanitized session omits hashedHostToken
      const sanitized = getHostedSession(result.session.id);
      expect(sanitized.hashedHostToken).toBeUndefined();

      // The audience token must NOT verify as a host token, and vice versa
      expect(verifyHostedHostToken(result.session.id, result.hostToken)).toBe(true);
      expect(verifyHostedHostToken(result.session.id, result.token)).toBe(false);
      expect(verifyHostedToken(result.session.id, result.hostToken)).toBe(false);
    });

    it('refuses to start a session on an HTTP-only install with a 412 preflight failure', async () => {
      vi.spyOn(networkExposure, 'getNetworkExposureStatus').mockImplementation(httpExposure);
      await expect(createHostedSession('loom-1', 'ep-1', { audioTarget: 'host' })).rejects.toMatchObject({
        status: 412,
        code: 'HOSTED_SESSION_PREFLIGHT_FAILED',
      });
    });
  });

  describe('revalidateLiveConversationGate', () => {
    it('allows live conversation for connected helper decision hold scene with offscreen protagonist', () => {
      const session = { status: 'active', playbackPhase: 'hold' };
      const node = {
        audienceConnection: 'connected',
        playbackMode: 'decision',
        protagonistPresence: 'offscreen',
        isEnding: false,
      };
      const asset = { manifest: { safeForLiveVoice: true } };

      const gate = revalidateLiveConversationGate({ session, node, asset });
      expect(gate.allowed).toBe(true);
    });

    it('rejects if scene audience is disconnected', () => {
      const session = { status: 'active', playbackPhase: 'hold' };
      const node = { audienceConnection: 'disconnected', playbackMode: 'decision', protagonistPresence: 'offscreen' };
      expect(revalidateLiveConversationGate({ session, node }).allowed).toBe(false);
    });

    it('rejects if protagonist is onscreen', () => {
      const session = { status: 'active', playbackPhase: 'hold' };
      const node = { audienceConnection: 'connected', playbackMode: 'decision', protagonistPresence: 'onscreen' };
      expect(revalidateLiveConversationGate({ session, node }).allowed).toBe(false);
    });

    it('rejects if hold asset has blocking character dialogue', () => {
      const session = { status: 'active', playbackPhase: 'hold' };
      const node = { audienceConnection: 'connected', playbackMode: 'decision', protagonistPresence: 'offscreen' };
      const asset = { manifest: { safeForLiveVoice: false } };
      expect(revalidateLiveConversationGate({ session, node, asset }).allowed).toBe(false);
    });
  });

  describe('runtime v1 listening admission', () => {
    // These regressions are checked at turn admission: a stale host phase,
    // explicit window presence or unsafe occupancy must never start providers.
    it.each([
      ['cut node with stale hold phase', { playbackMode: 'cut' }, 'hold', 'PLAYBACK_NOT_DECISION'],
      ['decision entry clip', {}, 'entry', 'PLAYBACK_NOT_IN_HOLD_PHASE'],
      ['decision exit clip', {}, 'exit', 'PLAYBACK_NOT_IN_HOLD_PHASE'],
      ['disconnected decision', { audienceConnection: 'disconnected' }, 'hold', 'AUDIENCE_DISCONNECTED'],
      ['onscreen live window', { interactionWindow: { enabled: true, protagonistPresence: 'onscreen' } }, 'hold', 'PROTAGONIST_ONSCREEN'],
      ['occupied hold', {
        playbackAssets: {
          holdLoopVideoHistoryIds: ['vid-dialogue'],
          audioOccupancy: { 'vid-dialogue': { characterDialogue: [{ startMs: 0, endMs: 1000 }], safeForLiveVoice: true } },
        },
      }, 'hold', 'HOLD_ASSET_OCCUPIED_BY_DIALOGUE'],
    ])('refuses %s before starting a turn', async (_label, patch, phase, code) => {
      const { session } = await createHostedSession('loom-1', 'ep-1');
      const changedLoom = structuredClone(mockLoom);
      Object.assign(changedLoom.episodes[0].nodes[0], patch);
      vi.mocked(records.getLoom).mockResolvedValue(changedLoom);
      _getInternalSession(session.id).playbackPhase = phase;
      vi.spyOn(weave, 'playTurn');
      const io = makeIo();

      await expect(startHostedListening(session.id, { io })).rejects.toMatchObject({ status: 409, code });

      expect(weave.playTurn).not.toHaveBeenCalled();
      expect(stt.transcribe).not.toHaveBeenCalled();
      expect(tts.synthesize).not.toHaveBeenCalled();
      expect(getHostedSession(session.id).turnPhase).toBe('idle');
      expect(io.emits).toEqual([]);
    });

    it('retains the legacy decision default for a connected offscreen hold', async () => {
      const { session } = await createHostedSession('loom-1', 'ep-1');
      const legacyLoom = structuredClone(mockLoom);
      delete legacyLoom.episodes[0].nodes[0].playbackMode;
      vi.mocked(records.getLoom).mockResolvedValue(legacyLoom);

      await expect(startHostedListening(session.id)).resolves.toMatchObject({ ok: true });
      expect(getHostedSession(session.id).turnPhase).toBe('listening');
    });
  });

  describe('half-duplex turn execution', () => {
    it('dispatches synthesized speech before committing the story transition', async () => {
      const { session } = await createHostedSession('loom-1', 'ep-1');
      const io = makeIo();
      const speech = deferred();
      vi.mocked(tts.synthesize).mockReturnValue(speech.promise);
      await startHostedListening(session.id, { io });
      vi.spyOn(weave, 'playTurn').mockResolvedValue({
        action: 'move', transitionId: 'tr-1',
        narration: 'We shall enter the dark woods together.',
        node: { id: 'node-2', title: 'Deep Woods' },
      });

      const pending = processHostedUtterance(session.id, {
        audioBuffer: Buffer.from('fake-audio-bytes'), io,
      });
      await vi.waitFor(() => expect(tts.synthesize).toHaveBeenCalled());
      expect(getHostedSession(session.id)).toMatchObject({
        currentNodeId: 'node-start', turnPhase: 'speaking',
      });
      expect(io.emits.some(({ event }) => event === 'hosted:story:transition')).toBe(false);

      speech.resolve({ wav: Buffer.from('RIFFmockwavdata') });
      await expect(pending).resolves.toMatchObject({ ok: true });

      expect(io.emits.filter(({ event }) => [
        'hosted:turn:phase', 'hosted:turn:tts', 'hosted:story:transition',
      ].includes(event)).map(({ event, payload }) => payload.phase || event)).toEqual([
        'listening', 'thinking', 'speaking', 'hosted:turn:tts', 'hosted:story:transition',
      ]);
      expect(getHostedSession(session.id).currentNodeId).toBe('node-2');
    });

    it('synthesizes the selected protagonist with its approved AuK profile regardless of character order', async () => {
      vi.spyOn(records, 'getLoom').mockResolvedValue({ ...mockLoom, protagonistCharacterId: 'character-1' });
      vi.spyOn(universeBuilder, 'getUniverse').mockResolvedValue({
        characters: [{ id: 'another-character' }, { id: 'character-1', voiceId: 'piper:example' }],
      });
      vi.spyOn(voiceProfiles, 'resolveCharacterVoice').mockResolvedValue({
        source: 'profile',
        profileId: 'voice-profile-1',
        profileRevision: 3,
        voiceId: 'auk:character-1',
        degraded: false,
        warning: null,
      });
      const { session } = await createHostedSession('loom-1', 'ep-1');
      expect(voiceProfiles.resolveCharacterVoice).toHaveBeenLastCalledWith(expect.objectContaining({ characterId: 'character-1', route: 'interactive' }));
      await startHostedListening(session.id);
      vi.spyOn(weave, 'playTurn').mockResolvedValue({
        action: 'stay',
        narration: 'The signal is clear.',
        node: { id: 'node-start' },
      });

      await processHostedUtterance(session.id, { textMessage: 'Can you hear me?' });

      expect(voiceProfiles.resolveCharacterVoice).toHaveBeenLastCalledWith(expect.objectContaining({ characterId: 'character-1', route: 'interactive' }));
      expect(tts.synthesize).toHaveBeenCalledWith('The signal is clear.', {
        engine: 'auk',
        profileId: 'voice-profile-1',
        route: 'interactive',
        signal: expect.any(AbortSignal),
        voice: 'character-1',
      });
    });

    it('splits a namespaced character preset before live synthesis', async () => {
      const { session } = await createHostedSession('loom-1', 'ep-1');
      await startHostedListening(session.id);
      vi.spyOn(universeBuilder, 'getUniverse').mockResolvedValue({
        characters: [{ id: 'character-1', voiceId: 'kokoro:af_heart' }],
      });
      vi.spyOn(voiceProfiles, 'resolveCharacterVoice').mockResolvedValue({
        source: 'character-preset',
        profileId: null,
        profileRevision: null,
        voiceId: 'kokoro:af_heart',
        degraded: false,
        warning: null,
      });
      vi.spyOn(weave, 'playTurn').mockResolvedValue({
        action: 'stay',
        narration: 'Stay on the line.',
        node: { id: 'node-start' },
      });

      await processHostedUtterance(session.id, { textMessage: 'Hello?' });

      expect(tts.synthesize).toHaveBeenCalledWith('Stay on the line.', {
        engine: 'kokoro',
        profileId: undefined,
        route: 'interactive',
        signal: expect.any(AbortSignal),
        voice: 'af_heart',
      });
    });

    it('drops audio frames sent outside listening phase', async () => {
      const { session } = await createHostedSession('loom-1', 'ep-1');
      // session is currently idle
      const res = await processHostedUtterance(session.id, {
        audioBuffer: Buffer.from('dropped'),
      });
      expect(res.dropped).toBe(true);
      expect(res.reason).toBe('NOT_IN_LISTENING_PHASE');
    });

    it('aborts active turn on request', async () => {
      const { session } = await createHostedSession('loom-1', 'ep-1');
      await startHostedListening(session.id);
      expect(getHostedSession(session.id).turnPhase).toBe('listening');

      abortHostedTurn(session.id);
      expect(getHostedSession(session.id).turnPhase).toBe('idle');
    });
  });

  describe('speech completion before commitment', () => {
    const move = {
      action: 'move',
      transitionId: 'tr-1',
      narration: 'We shall enter the dark woods together.',
      node: { id: 'node-2', title: 'Deep Woods' },
    };

    const connectOutput = (session, role = 'host') => {
      const internal = _getInternalSession(session.id);
      const socketId = `${role}-sock`;
      if (role === 'audience') {
        internal.audioTarget = 'audience';
        internal.audienceSocketId = socketId;
      } else {
        internal.hostSocketId = socketId;
      }
      return socketId;
    };

    const speakMove = async (session, io) => {
      await startHostedListening(session.id, { io });
      vi.spyOn(weave, 'playTurn').mockResolvedValue(move);
      return processHostedUtterance(session.id, { textMessage: 'enter the forest', io });
    };

    const transitions = (io) => io.emits.filter((event) => event.event === 'hosted:story:transition');

    it('keeps the old node and refuses overlapping input until the designated output ends playback', async () => {
      const { session } = await createHostedSession('loom-1', 'ep-1');
      const io = makeIo();
      const socketId = connectOutput(session, 'host');
      const result = await speakMove(session, io);

      expect(result).toMatchObject({ ok: true, awaitingSpeech: true });
      expect(getHostedSession(session.id)).toMatchObject({ currentNodeId: 'node-start', turnPhase: 'speaking' });
      expect(transitions(io)).toHaveLength(0);
      expect(io.emits.some((event) => event.event === 'hosted:turn:tts')).toBe(true);

      await expect(processHostedUtterance(session.id, { textMessage: 'again', io }))
        .resolves.toMatchObject({ dropped: true, reason: 'NOT_IN_LISTENING_PHASE' });
      await expect(startHostedListening(session.id, { io })).rejects.toMatchObject({ code: 'TURN_IN_PROGRESS' });
      expect(getHostedSession(session.id).currentNodeId).toBe('node-start');

      await expect(acknowledgeHostedSpeech(session.id, {
        turnId: result.turnId, role: 'audience', socketId: 'audience-sock', status: 'ended', io,
      })).resolves.toMatchObject({ accepted: false });
      await expect(acknowledgeHostedSpeech(session.id, {
        turnId: result.turnId, role: 'host', socketId: 'someone-else', status: 'ended', io,
      })).resolves.toMatchObject({ accepted: false, reason: 'WRONG_SOCKET' });
      await expect(acknowledgeHostedSpeech(session.id, {
        turnId: '00000000-0000-4000-8000-000000000000', role: 'host', socketId, status: 'ended', io,
      })).resolves.toMatchObject({ accepted: false, reason: 'STALE_TURN' });
      expect(getHostedSession(session.id)).toMatchObject({ currentNodeId: 'node-start', turnPhase: 'speaking' });

      await expect(acknowledgeHostedSpeech(session.id, {
        turnId: result.turnId, role: 'host', socketId, status: 'ended', io,
      })).resolves.toMatchObject({ accepted: true, committed: true });
      expect(getHostedSession(session.id)).toMatchObject({ currentNodeId: 'node-2', turnPhase: 'idle' });
      expect(transitions(io)).toHaveLength(1);

      await expect(acknowledgeHostedSpeech(session.id, {
        turnId: result.turnId, role: 'host', socketId, status: 'ended', io,
      })).resolves.toMatchObject({ accepted: false, reason: 'NO_PENDING_SPEECH' });
      expect(transitions(io)).toHaveLength(1);
    });

    it('lets only the audience output commit when audio is aimed at the audience', async () => {
      const { session } = await createHostedSession('loom-1', 'ep-1', { audioTarget: 'audience' });
      const io = makeIo();
      const socketId = connectOutput(session, 'audience');
      _getInternalSession(session.id).hostSocketId = 'host-sock';
      const result = await speakMove(session, io);

      await acknowledgeHostedSpeech(session.id, {
        turnId: result.turnId, role: 'host', socketId: 'host-sock', status: 'ended', io,
      });
      expect(getHostedSession(session.id)).toMatchObject({ currentNodeId: 'node-start', turnPhase: 'speaking' });

      await acknowledgeHostedSpeech(session.id, {
        turnId: result.turnId, role: 'audience', socketId, status: 'ended', io,
      });
      expect(getHostedSession(session.id).currentNodeId).toBe('node-2');
      expect(transitions(io)).toHaveLength(1);
    });

    it('commits immediately on the narration text when synthesis fails', async () => {
      vi.mocked(tts.synthesize).mockResolvedValueOnce(null);
      const { session } = await createHostedSession('loom-1', 'ep-1');
      const io = makeIo();
      connectOutput(session, 'host');

      const result = await speakMove(session, io);

      expect(result.awaitingSpeech).toBeUndefined();
      expect(io.emits.some((event) => event.event === 'hosted:turn:tts')).toBe(false);
      expect(getHostedSession(session.id)).toMatchObject({ currentNodeId: 'node-2', turnPhase: 'idle' });
      expect(transitions(io)).toHaveLength(1);
    });

    it('drops the pending move on playback failure without a transition', async () => {
      const { session } = await createHostedSession('loom-1', 'ep-1');
      const io = makeIo();
      const socketId = connectOutput(session, 'host');
      const result = await speakMove(session, io);

      await expect(acknowledgeHostedSpeech(session.id, {
        turnId: result.turnId, role: 'host', socketId, status: 'failed', io,
      })).resolves.toMatchObject({ accepted: true, committed: false });
      expect(getHostedSession(session.id)).toMatchObject({ currentNodeId: 'node-start', turnPhase: 'idle' });
      expect(transitions(io)).toHaveLength(0);

      await startHostedListening(session.id, { io });
      const next = await processHostedUtterance(session.id, { textMessage: 'enter the forest', io });
      await acknowledgeHostedSpeech(session.id, {
        turnId: result.turnId, role: 'host', socketId, status: 'ended', io,
      });
      expect(getHostedSession(session.id)).toMatchObject({ currentNodeId: 'node-start', turnPhase: 'speaking' });
      await acknowledgeHostedSpeech(session.id, {
        turnId: next.turnId, role: 'host', socketId, status: 'ended', io,
      });
      expect(getHostedSession(session.id).currentNodeId).toBe('node-2');
      expect(transitions(io)).toHaveLength(1);
    });

    it('drops the pending move when acknowledgement times out, and a late ack cannot commit it', async () => {
      vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout'] });
      try {
        const { session } = await createHostedSession('loom-1', 'ep-1');
        const io = makeIo();
        const socketId = connectOutput(session, 'host');
        const result = await speakMove(session, io);
        expect(result.awaitingSpeech).toBe(true);

        await vi.advanceTimersByTimeAsync(HOSTED_SPEECH_ACK_TIMEOUT_MS - 1);
        expect(getHostedSession(session.id)).toMatchObject({ currentNodeId: 'node-start', turnPhase: 'speaking' });
        await vi.advanceTimersByTimeAsync(1);

        expect(getHostedSession(session.id)).toMatchObject({ currentNodeId: 'node-start', turnPhase: 'idle' });
        expect(transitions(io)).toHaveLength(0);
        await acknowledgeHostedSpeech(session.id, {
          turnId: result.turnId, role: 'host', socketId, status: 'ended', io,
        });
        expect(getHostedSession(session.id).currentNodeId).toBe('node-start');
        expect(transitions(io)).toHaveLength(0);
      } finally {
        vi.useRealTimers();
      }
    });

    it('bounds acknowledgement processing when its loom read stalls and rejects the late read', async () => {
      vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout'] });
      try {
        const { session } = await createHostedSession('loom-1', 'ep-1');
        const io = makeIo();
        const socketId = connectOutput(session, 'host');
        const result = await speakMove(session, io);
        const gate = deferred();
        records.getLoom.mockImplementationOnce(() => gate.promise);
        const acknowledgement = acknowledgeHostedSpeech(session.id, {
          turnId: result.turnId, role: 'host', socketId, status: 'ended', io,
        });
        await vi.advanceTimersByTimeAsync(HOSTED_SPEECH_ACK_TIMEOUT_MS);
        expect(getHostedSession(session.id)).toMatchObject({ currentNodeId: 'node-start', turnPhase: 'idle' });
        expect(transitions(io)).toHaveLength(0);
        const next = await startHostedListening(session.id, { io });
        gate.resolve(mockLoom);
        await expect(acknowledgement).resolves.toMatchObject({ accepted: false, committed: false });
        expect(getHostedSession(session.id)).toMatchObject({ currentNodeId: 'node-start', turnPhase: 'listening' });
        expect(_getInternalSession(session.id).activeTurn.id).toBe(next.turnId);
        expect(transitions(io)).toHaveLength(0);
      } finally {
        vi.useRealTimers();
      }
    });

    it('does not emit a transition when playback is aborted, the output disconnects, or the session ends', async () => {
      const io = makeIo();
      const { session } = await createHostedSession('loom-1', 'ep-1');
      const socketId = connectOutput(session, 'host');
      const aborted = await speakMove(session, io);
      abortHostedTurn(session.id, { reason: 'client_aborted', io });
      expect(io.emits.filter((event) => event.event === 'hosted:turn:phase').at(-1)?.payload).toMatchObject({
        phase: 'idle',
        turnId: aborted.turnId,
        reason: 'client_aborted',
      });
      await acknowledgeHostedSpeech(session.id, {
        turnId: aborted.turnId, role: 'host', socketId, status: 'ended', io,
      });
      expect(getHostedSession(session.id)).toMatchObject({ currentNodeId: 'node-start', turnPhase: 'idle' });

      const disconnected = await speakMove(session, io);
      releaseHostedSpeechOutput(session.id, socketId, { io });
      await acknowledgeHostedSpeech(session.id, {
        turnId: disconnected.turnId, role: 'host', socketId, status: 'ended', io,
      });
      expect(transitions(io)).toHaveLength(0);

      const ending = await speakMove(session, io);
      endHostedSession(session.id, { reason: 'host_ended', io });
      expect(io.emits.at(-1).event).toBe('hosted:session:ended');
      expect(transitions(io)).toHaveLength(0);
      expect(ending.awaitingSpeech).toBe(true);
    });

    it('drops a pending move when the host switches episodes', async () => {
      const io = makeIo();
      const { session } = await createHostedSession('loom-1', 'ep-1');
      const socketId = connectOutput(session, 'host');
      const pending = await speakMove(session, io);

      await switchHostedEpisode(session.id, 'ep-2', { io });
      await acknowledgeHostedSpeech(session.id, {
        turnId: pending.turnId, role: 'host', socketId, status: 'ended', io,
      });
      expect(getHostedSession(session.id)).toMatchObject({
        episodeId: 'ep-2', currentNodeId: 'node-ep2-start', turnPhase: 'idle',
      });
      expect(transitions(io)).toHaveLength(0);
    });

    it('refuses to commit after the scene generation changes during acknowledgement', async () => {
      const io = makeIo();
      const { session } = await createHostedSession('loom-1', 'ep-1');
      const socketId = connectOutput(session, 'host');
      const result = await speakMove(session, io);
      const gate = deferred();
      records.getLoom.mockImplementationOnce(() => gate.promise);

      const ack = acknowledgeHostedSpeech(session.id, {
        turnId: result.turnId, role: 'host', socketId, status: 'ended', io,
      });
      _getInternalSession(session.id).sceneGeneration += 1;
      gate.resolve(mockLoom);

      await expect(ack).resolves.toMatchObject({ accepted: false, committed: false });
      expect(getHostedSession(session.id)).toMatchObject({ currentNodeId: 'node-start', turnPhase: 'idle' });
      expect(transitions(io)).toHaveLength(0);
    });

    it('returns to listening without a transition when a stay finishes playback', async () => {
      const { session } = await createHostedSession('loom-1', 'ep-1');
      const io = makeIo();
      const socketId = connectOutput(session, 'host');
      await startHostedListening(session.id, { io });
      vi.spyOn(weave, 'playTurn').mockResolvedValue({
        action: 'stay',
        narration: 'We hold the path.',
        node: { id: 'node-start' },
      });

      const result = await processHostedUtterance(session.id, { textMessage: 'wait', io });

      expect(result.awaitingSpeech).toBe(true);
      expect(getHostedSession(session.id)).toMatchObject({ currentNodeId: 'node-start', turnPhase: 'speaking' });
      await acknowledgeHostedSpeech(session.id, {
        turnId: result.turnId, role: 'host', socketId, status: 'ended', io,
      });
      expect(getHostedSession(session.id)).toMatchObject({ currentNodeId: 'node-start', turnPhase: 'listening' });
      expect(transitions(io)).toHaveLength(0);
    });

    it('drops the pending move when the output reports playback aborted', async () => {
      const { session } = await createHostedSession('loom-1', 'ep-1');
      const io = makeIo();
      const socketId = connectOutput(session, 'host');
      const result = await speakMove(session, io);

      await expect(acknowledgeHostedSpeech(session.id, {
        turnId: result.turnId, role: 'host', socketId, status: 'aborted', io,
      })).resolves.toMatchObject({ accepted: true, committed: false });
      expect(getHostedSession(session.id)).toMatchObject({ currentNodeId: 'node-start', turnPhase: 'idle' });
      expect(io.emits.some((event) => event.payload?.reason === 'playback_aborted')).toBe(true);
      expect(transitions(io)).toHaveLength(0);
    });

    it('drops a pending move when the host leaves the scene before playback ends', async () => {
      const { session } = await createHostedSession('loom-1', 'ep-1');
      const io = makeIo();
      const socketId = connectOutput(session, 'host');
      const result = await speakMove(session, io);

      await updateHostedSession(session.id, { currentNodeId: 'node-2' }, { io });

      expect(getHostedSession(session.id)).toMatchObject({ currentNodeId: 'node-2', turnPhase: 'idle' });
      expect(transitions(io)).toHaveLength(0);
      await acknowledgeHostedSpeech(session.id, {
        turnId: result.turnId, role: 'host', socketId, status: 'ended', io,
      });
      expect(getHostedSession(session.id).currentNodeId).toBe('node-2');
      expect(transitions(io)).toHaveLength(0);
    });

    it('does not commit a move whose transition disappeared before playback ended', async () => {
      const io = makeIo();
      const { session } = await createHostedSession('loom-1', 'ep-1');
      const socketId = connectOutput(session, 'host');
      const result = await speakMove(session, io);
      const changed = structuredClone(mockLoom);
      changed.episodes[0].nodes[0].transitions = [];
      records.getLoom.mockResolvedValue(changed);

      await expect(acknowledgeHostedSpeech(session.id, {
        turnId: result.turnId, role: 'host', socketId, status: 'ended', io,
      })).resolves.toMatchObject({ committed: false, reason: 'TRANSITION_UNAVAILABLE' });
      expect(getHostedSession(session.id)).toMatchObject({ currentNodeId: 'node-start', turnPhase: 'idle' });
      expect(transitions(io)).toHaveLength(0);
    });
  });

  describe('session teardown', () => {
    it('ends hosted session cleanly', async () => {
      const { session } = await createHostedSession('loom-1', 'ep-1');
      expect(getHostedSession(session.id)).not.toBeNull();

      endHostedSession(session.id, { reason: 'user_ended' });
      expect(getHostedSession(session.id)).toBeNull();
    });

    // #5786: the turn holds `session`/`turn` across every provider await, so a
    // teardown landing mid-flight used to let the LLM and TTS run to completion
    // and emit turn frames AFTER the room's terminal `hosted:session:ended`.
    it('abandons a turn whose session is torn down mid story turn, emitting nothing after ended', async () => {
      const io = makeIo();
      const { session } = await createHostedSession('loom-1', 'ep-1');
      await startHostedListening(session.id, { io });

      const storyTurn = deferred();
      vi.spyOn(weave, 'playTurn').mockImplementation(() => storyTurn.promise);

      const pending = processHostedUtterance(session.id, {
        textMessage: 'What is behind the trees?',
        io,
      });
      await vi.waitFor(() => expect(weave.playTurn).toHaveBeenCalled());

      endHostedSession(session.id, { reason: 'user_ended', io });
      storyTurn.resolve({
        action: 'move',
        transitionId: 'tr-1',
        narration: 'We shall enter the dark woods together.',
        node: { id: 'node-2', title: 'Deep Woods' },
      });

      await expect(pending).resolves.toMatchObject({ aborted: true });
      // The provider work downstream of the abandoned stage never ran…
      expect(tts.synthesize).not.toHaveBeenCalled();
      // …and `hosted:session:ended` is the last thing the room ever saw.
      expect(io.emits.at(-1).event).toBe('hosted:session:ended');
    });

    it('treats an aborted transcription as a cancellation, not an empty utterance', async () => {
      const io = makeIo();
      const { session } = await createHostedSession('loom-1', 'ep-1');
      await startHostedListening(session.id, { io });

      const transcription = deferred();
      stt.transcribe.mockImplementation((_audio, opts) => {
        opts.signal.addEventListener('abort', () => transcription.reject(new Error('transcribe aborted')));
        return transcription.promise;
      });
      vi.spyOn(weave, 'playTurn').mockResolvedValue({
        action: 'stay',
        narration: 'Still here.',
        node: { id: 'node-start' },
      });

      const pending = processHostedUtterance(session.id, {
        audioBuffer: Buffer.from('fake-audio-bytes'),
        io,
      });
      await vi.waitFor(() => expect(stt.transcribe).toHaveBeenCalled());

      endHostedSession(session.id, { reason: 'expired', io });

      await expect(pending).resolves.toMatchObject({ aborted: true });
      // An abort used to fall through the STT catch as `{ text: '' }`, which
      // reads as a successfully-empty utterance rather than a cancellation.
      expect(weave.playTurn).not.toHaveBeenCalled();
      expect(io.emits.at(-1).event).toBe('hosted:session:ended');
    });
  });

  // #8112: the host can advance episodes without the server ever learning
  // about it, so a hosted session used to keep resolving audience turns
  // against the OLD episode's graph — findNode throws "Scene not found" and
  // every turn silently falls back to canned narration.
  describe('updateHostedSession — currentNodeId episode validation', () => {
    it('accepts a currentNodeId that belongs to the session episode', async () => {
      const { session } = await createHostedSession('loom-1', 'ep-1');
      const updated = await updateHostedSession(session.id, { currentNodeId: 'node-2' });
      expect(updated.currentNodeId).toBe('node-2');
    });

    it('rejects a currentNodeId from another episode and leaves the session unchanged', async () => {
      const { session } = await createHostedSession('loom-1', 'ep-1');
      await expect(updateHostedSession(session.id, { currentNodeId: 'node-ep2-start' }))
        .rejects.toMatchObject({ status: 400, code: 'NODE_NOT_IN_EPISODE' });
      expect(getHostedSession(session.id).currentNodeId).toBe('node-start');
    });

    it('skips the episode lookup when currentNodeId is unchanged', async () => {
      const { session } = await createHostedSession('loom-1', 'ep-1');
      records.getLoom.mockClear();
      const updated = await updateHostedSession(session.id, { currentNodeId: 'node-start', playbackPhase: 'hold' });
      expect(updated.playbackPhase).toBe('hold');
      expect(records.getLoom).not.toHaveBeenCalled();
    });
  });

  describe('switchHostedEpisode', () => {
    it('re-binds the session to the new episode, resets to its opening node, and clears the transcript', async () => {
      const io = makeIo();
      const { session } = await createHostedSession('loom-1', 'ep-1');

      const result = await switchHostedEpisode(session.id, 'ep-2', { io });
      expect(result.ok).toBe(true);
      expect(result.session.currentNodeId).toBe('node-ep2-start');

      const updated = getHostedSession(session.id);
      expect(updated.currentNodeId).toBe('node-ep2-start');
      expect(updated.playbackPhase).toBe('hold');
      expect(updated.turnPhase).toBe('idle');
      expect(updated.transcript).toHaveLength(1);
      expect(updated.transcript[0].role).toBe('narrator');

      // A subsequent audience turn resolves against episode 2's graph rather
      // than throwing "Scene not found" against the old episode.
      vi.spyOn(weave, 'playTurn').mockResolvedValue({
        action: 'stay',
        narration: 'The pass stretches on.',
        node: { id: 'node-ep2-start' },
      });
      await startHostedListening(session.id, { io });
      const turnResult = await processHostedUtterance(session.id, { textMessage: 'keep climbing', io });
      expect(turnResult.playResult.narration).toBe('The pass stretches on.');
      expect(weave.playTurn).toHaveBeenCalledWith('loom-1', 'ep-2', expect.objectContaining({ nodeId: 'node-ep2-start' }));

      expect(io.emits.some((e) => e.event === 'hosted:session:sync')).toBe(true);
    });

    it('aborts an in-flight turn against the old episode before switching', async () => {
      const io = makeIo();
      const { session } = await createHostedSession('loom-1', 'ep-1');
      await startHostedListening(session.id, { io });

      const storyTurn = deferred();
      vi.spyOn(weave, 'playTurn').mockImplementation(() => storyTurn.promise);
      const pending = processHostedUtterance(session.id, { textMessage: 'enter the forest', io });
      await vi.waitFor(() => expect(weave.playTurn).toHaveBeenCalled());

      await switchHostedEpisode(session.id, 'ep-2', { io });
      storyTurn.resolve({ action: 'stay', narration: 'too late', node: { id: 'node-start' } });

      await expect(pending).resolves.toMatchObject({ aborted: true });
      expect(getHostedSession(session.id).currentNodeId).toBe('node-ep2-start');
    });

    it('ends the session with reason episode_not_ready when the target episode fails preflight', async () => {
      const io = makeIo();
      const { session } = await createHostedSession('loom-1', 'ep-1');

      const result = await switchHostedEpisode(session.id, 'ep-3-not-ready', { io });
      expect(result.ok).toBe(false);
      expect(result.reason).toBe('episode_not_ready');
      expect(getHostedSession(session.id)).toBeNull();
      expect(io.emits.at(-1)).toMatchObject({ event: 'hosted:session:ended', payload: { reason: 'episode_not_ready' } });
    });

    it('throws when the target episode does not belong to the session loom', async () => {
      const { session } = await createHostedSession('loom-1', 'ep-1');
      await expect(switchHostedEpisode(session.id, 'not-an-episode')).rejects.toMatchObject({ status: 404 });
    });

    // A host "end", DELETE /sessions/:id, or the TTL sweep can land while
    // switchHostedEpisode is off awaiting the loom read or preflight. Losing
    // that race must not resurrect the deleted session's state or emit
    // hosted:session:sync AFTER the room already saw hosted:session:ended.
    it('does not resurrect a session torn down while awaiting the loom read', async () => {
      const io = makeIo();
      const { session } = await createHostedSession('loom-1', 'ep-1');

      const loomRead = deferred();
      records.getLoom.mockImplementationOnce(() => loomRead.promise);

      const pending = switchHostedEpisode(session.id, 'ep-2', { io });
      endHostedSession(session.id, { reason: 'host_ended', io });
      loomRead.resolve(mockLoom);

      await expect(pending).resolves.toMatchObject({ ok: false, reason: 'session_ended' });
      expect(getHostedSession(session.id)).toBeNull();
      expect(io.emits.at(-1).event).toBe('hosted:session:ended');
    });

    // Without this gate a turn that starts while the switch is off awaiting
    // the loom read/preflight would run against the OLD episode and could
    // commit and emit AFTER the new episode's hosted:session:sync, mixing
    // old-episode content into the new episode.
    it('refuses to start a new turn while a switch is in flight, and allows one once it settles', async () => {
      const { session } = await createHostedSession('loom-1', 'ep-1');

      const loomRead = deferred();
      records.getLoom.mockImplementationOnce(() => loomRead.promise);

      const pending = switchHostedEpisode(session.id, 'ep-2');
      await expect(startHostedListening(session.id)).rejects.toMatchObject({
        status: 409,
        code: 'EPISODE_SWITCH_IN_PROGRESS',
      });

      loomRead.resolve(mockLoom);
      await pending;

      const listenRes = await startHostedListening(session.id);
      expect(listenRes.ok).toBe(true);
    });

    it('rejects a listen request whose loom read resumes after an episode switch', async () => {
      const io = makeIo();
      const { session } = await createHostedSession('loom-1', 'ep-1');
      const pendingRead = deferred();
      records.getLoom
        .mockImplementationOnce(() => pendingRead.promise)
        .mockResolvedValueOnce(mockLoom);

      const pendingListen = startHostedListening(session.id, { io });
      await switchHostedEpisode(session.id, 'ep-2', { io });
      const syncIndex = io.emits.findLastIndex((event) => event.event === 'hosted:session:sync');

      pendingRead.resolve(mockLoom);
      await expect(pendingListen).rejects.toMatchObject({
        status: 409,
        code: 'EPISODE_SWITCH_IN_PROGRESS',
      });

      expect(getHostedSession(session.id)).toMatchObject({ episodeId: 'ep-2', turnPhase: 'idle' });
      expect(io.emits.slice(syncIndex + 1).some((event) => event.event === 'hosted:turn:phase')).toBe(false);
    });

    // Without this, a host double-clicking "Next Episode" before the first
    // switch's async loom-read/preflight resolves fires two overlapping
    // calls that race — the earlier request could commit last and rebind the
    // session to an episode the UI already left.
    it('rejects a second switch while one is already in flight', async () => {
      const { session } = await createHostedSession('loom-1', 'ep-1');

      const loomRead = deferred();
      records.getLoom.mockImplementationOnce(() => loomRead.promise);

      const pending = switchHostedEpisode(session.id, 'ep-2');
      await expect(switchHostedEpisode(session.id, 'ep-3-not-ready')).rejects.toMatchObject({
        status: 409,
        code: 'EPISODE_SWITCH_IN_PROGRESS',
      });

      loomRead.resolve(mockLoom);
      await expect(pending).resolves.toMatchObject({ ok: true });
      expect(getHostedSession(session.id).episodeId).toBe('ep-2');
    });

    // The client's playback-sync effect fires on the very next React commit
    // after "Next Episode" — well before switchHostedEpisode's async work
    // resolves server-side — so a `hosted:playback:update` racing in during
    // that window carries a currentNodeId that legitimately belonged to the
    // OLD episode a moment ago. It must no-op, not reject as drift (#8112).
    it('treats a currentNodeId update that races with an in-flight switch as a stale no-op', async () => {
      const { session } = await createHostedSession('loom-1', 'ep-1');

      const loomRead = deferred();
      records.getLoom.mockImplementationOnce(() => loomRead.promise);

      const pending = switchHostedEpisode(session.id, 'ep-2');
      const updated = await updateHostedSession(session.id, { currentNodeId: 'node-2' });
      expect(updated.currentNodeId).toBe('node-start');

      loomRead.resolve(mockLoom);
      await pending;
      expect(getHostedSession(session.id).currentNodeId).toBe('node-ep2-start');
    });
  });

  describe('expired-session sweep', () => {
    // Age a session past its TTL without waiting out 30 real minutes.
    const expire = (sessionId) => {
      const internal = _getInternalSession(sessionId);
      internal.expiresAt = new Date(Date.now() - 1000).toISOString();
      return internal;
    };

    afterEach(() => {
      stopHostedSessionSweep();
      vi.useRealTimers();
    });

    it('deletes an expired session on the next sweep tick, aborting its turn and notifying the room', async () => {
      const io = makeIo();
      const { session } = await createHostedSession('loom-1', 'ep-1');
      await startHostedListening(session.id);
      const internal = expire(session.id);
      const { signal } = internal.activeTurn.abortController;
      expect(signal.aborted).toBe(false);

      vi.useFakeTimers();
      startHostedSessionSweep({ intervalMs: 60_000, io });
      // Arming alone tears nothing down; the first tick does.
      expect(io.emits).toHaveLength(0);
      vi.advanceTimersByTime(60_000);

      expect(signal.aborted).toBe(true);
      expect(getHostedSession(session.id)).toBeNull();
      expect(io.emits).toContainEqual({
        room: `session:${session.id}`,
        event: 'hosted:session:ended',
        payload: { sessionId: session.id, reason: 'expired' },
      });
    });

    it('leaves an unexpired session untouched', async () => {
      const io = makeIo();
      const { session } = await createHostedSession('loom-1', 'ep-1');

      vi.useFakeTimers();
      startHostedSessionSweep({ intervalMs: 60_000, io });
      vi.advanceTimersByTime(180_000);

      expect(getHostedSession(session.id)?.status).toBe('active');
      expect(io.emits).toHaveLength(0);
    });

    it('rejects a late reconnect: _getInternalSession returns null once the TTL has passed', async () => {
      const { session, token } = await createHostedSession('loom-1', 'ep-1');
      expect(_getInternalSession(session.id)).not.toBeNull();

      expire(session.id);

      // What the /fableloom-hosted handshake gates on, for host and audience alike.
      expect(_getInternalSession(session.id)).toBeNull();
      expect(verifyHostedToken(session.id, token)).toBe(false);
    });

    it('arms an unref\'d timer once and clears it on stop', () => {
      vi.useFakeTimers();
      const first = startHostedSessionSweep({ intervalMs: 60_000 });
      expect(first.unref).toBeTypeOf('function');
      // Re-arming is a no-op rather than a second leaked interval.
      expect(startHostedSessionSweep({ intervalMs: 60_000 })).toBe(first);
      expect(vi.getTimerCount()).toBe(1);

      stopHostedSessionSweep();
      expect(vi.getTimerCount()).toBe(0);
    });
  });
});