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

fix([issue-13112]): wait for hosted speech completion before a scene commit (#13446)

[._.]/118875952fc6
diff --git a/client/src/components/fableloom/LoomPlayPanel.jsx b/client/src/components/fableloom/LoomPlayPanel.jsx
index 0de26971c0..786dedf689 100644
--- a/client/src/components/fableloom/LoomPlayPanel.jsx
+++ b/client/src/components/fableloom/LoomPlayPanel.jsx
@@ -22,6 +22,7 @@ import { playLoomTurn } from '../../services/api';
import { sceneProseClass } from './fieldStyles';
import toast from '../ui/Toast';
import LoomHostedSessionModal from './LoomHostedSessionModal';
+import { abortHostedSpeech, playHostedSpeech, releaseDroppedHostedSpeech } from './hostedSpeechPlayback';
import { audienceCanParticipate } from '../../../../server/lib/fableLoomParticipation.js';
import {
resolveFableLoomProtagonistPresence,
@@ -109,6 +110,7 @@ export default function LoomPlayPanel({ loom, episode: initialEpisode, onClose }
const [hostedAudienceConnected, setHostedAudienceConnected] = useState(false);
const [hostedTurnPhase, setHostedTurnPhase] = useState('idle');
const hostAudioPlayerRef = useRef(null);
+ const hostedSpeechRef = useRef(null);
const scrollRef = useRef(null);
const hostedSocketRef = useRef(null);
// The episode id the server-side hosted session is currently bound to —
@@ -140,6 +142,7 @@ export default function LoomPlayPanel({ loom, episode: initialEpisode, onClose }
socket.on('hosted:turn:phase', (data) => {
setHostedTurnPhase(data.phase || 'idle');
+ hostedSpeechRef.current = releaseDroppedHostedSpeech(hostedSpeechRef.current, data);
});
socket.on('hosted:error', (data) => {
@@ -151,14 +154,15 @@ export default function LoomPlayPanel({ loom, episode: initialEpisode, onClose }
});
socket.on('hosted:turn:tts', (data) => {
- if (data.target === 'host' && data.audio && hostAudioPlayerRef.current) {
- try {
- hostAudioPlayerRef.current.src = `data:${data.mimeType || 'audio/wav'};base64,${data.audio}`;
- hostAudioPlayerRef.current.play().catch(() => null);
- } catch (err) {
- console.warn('TTS playback error:', err);
- }
- }
+ hostedSpeechRef.current = playHostedSpeech(hostAudioPlayerRef.current, {
+ socket,
+ previous: hostedSpeechRef.current,
+ turnId: data?.turnId,
+ target: data?.target,
+ expectedTarget: 'host',
+ mimeType: data?.mimeType,
+ audioBase64: data?.audio,
+ });
});
// The server rejects a second `hosted:episode:switch` sent while an
@@ -186,6 +190,8 @@ export default function LoomPlayPanel({ loom, episode: initialEpisode, onClose }
});
socket.on('hosted:session:ended', (data) => {
+ abortHostedSpeech(hostedSpeechRef.current);
+ hostedSpeechRef.current = null;
setHostedSession(null);
setHostedAudienceConnected(false);
setHostedTurnPhase('idle');
@@ -197,6 +203,8 @@ export default function LoomPlayPanel({ loom, episode: initialEpisode, onClose }
});
return () => {
+ abortHostedSpeech(hostedSpeechRef.current);
+ hostedSpeechRef.current = null;
socket.disconnect();
hostedSocketRef.current = null;
};
diff --git a/client/src/components/fableloom/LoomPlayPanel.test.jsx b/client/src/components/fableloom/LoomPlayPanel.test.jsx
index c0f46100d3..72390dd0c3 100644
--- a/client/src/components/fableloom/LoomPlayPanel.test.jsx
+++ b/client/src/components/fableloom/LoomPlayPanel.test.jsx
@@ -684,4 +684,66 @@ describe('LoomPlayPanel', () => {
expect(screen.getByText(/Duck level: -8 dB/)).toBeInTheDocument();
expect(screen.getByText(/Asset: vid-entry-hall/)).toBeInTheDocument();
});
+
+ it('reports host playback completion and failure for the designated output only', async () => {
+ const user = userEvent.setup();
+ const listeners = {};
+ const socket = {
+ on: vi.fn((event, fn) => { listeners[event] = fn; }),
+ emit: vi.fn(),
+ disconnect: vi.fn(),
+ };
+ io.mockImplementation(() => socket);
+ const play = vi.spyOn(HTMLMediaElement.prototype, 'play').mockResolvedValue(undefined);
+ const { unmount } = render(<LoomPlayPanel loom={loom} episode={episode} />);
+
+ await user.click(screen.getByRole('button', { name: 'Host (QR)' }));
+ await user.click(screen.getByRole('button', { name: 'Start hosted session' }));
+ const audio = document.querySelector('audio');
+ const turnId = '22222222-2222-4222-8222-222222222222';
+
+ await act(async () => {
+ listeners['hosted:turn:tts']({
+ target: 'audience', audio: 'QQ==', mimeType: 'audio/wav', turnId: '11111111-1111-4111-8111-111111111111',
+ });
+ });
+ expect(socket.emit).not.toHaveBeenCalledWith('hosted:speech:done', expect.anything());
+
+ await act(async () => {
+ listeners['hosted:turn:tts']({ target: 'host', audio: 'QQ==', mimeType: 'audio/wav', turnId });
+ await Promise.resolve();
+ });
+ expect(play).toHaveBeenCalled();
+ await act(async () => { audio.onended(); });
+ expect(socket.emit).toHaveBeenCalledWith('hosted:speech:done', { turnId, status: 'ended' });
+
+ play.mockRejectedValueOnce(new Error('blocked'));
+ const failedTurn = '33333333-3333-4333-8333-333333333333';
+ await act(async () => {
+ listeners['hosted:turn:tts']({ target: 'host', audio: 'QQ==', mimeType: 'audio/wav', turnId: failedTurn });
+ await Promise.resolve();
+ });
+ expect(socket.emit).toHaveBeenCalledWith('hosted:speech:done', { turnId: failedTurn, status: 'failed' });
+
+ const droppedTurn = '44444444-4444-4444-8444-444444444444';
+ play.mockResolvedValue(undefined);
+ const pause = vi.spyOn(HTMLMediaElement.prototype, 'pause').mockImplementation(() => {});
+ await act(async () => {
+ listeners['hosted:turn:tts']({ target: 'host', audio: 'QQ==', mimeType: 'audio/wav', turnId: droppedTurn });
+ });
+ await act(async () => {
+ listeners['hosted:turn:phase']({ phase: 'idle', turnId, reason: 'episode_switch' });
+ });
+ expect(socket.emit).not.toHaveBeenCalledWith('hosted:speech:done', { turnId: droppedTurn, status: 'aborted' });
+ await act(async () => {
+ listeners['hosted:turn:phase']({ phase: 'idle', turnId: droppedTurn, reason: 'speech_timeout' });
+ });
+ expect(pause).toHaveBeenCalled();
+ expect(socket.emit).toHaveBeenCalledWith('hosted:speech:done', { turnId: droppedTurn, status: 'aborted' });
+
+ pause.mockRestore();
+ play.mockRestore();
+ unmount();
+ io.mockImplementation(() => ({ on: vi.fn(), emit: vi.fn(), disconnect: vi.fn() }));
+ });
});
diff --git a/client/src/components/fableloom/hostedSpeechPlayback.js b/client/src/components/fableloom/hostedSpeechPlayback.js
new file mode 100644
index 0000000000..d6a2598da0
--- /dev/null
+++ b/client/src/components/fableloom/hostedSpeechPlayback.js
@@ -0,0 +1,68 @@
+/**
+ * Play one hosted narration on the designated output and report how it ended.
+ * The server commits a transition only for `ended` from this socket's turn.
+ */
+
+function report(socket, turnId, status) {
+ socket?.emit('hosted:speech:done', { turnId, status });
+}
+
+export function abortHostedSpeech(playback) {
+ if (!playback || playback.settled) return;
+ playback.settled = true;
+ playback.audio.onended = null;
+ playback.audio.onerror = null;
+ // Stop the element. A later `ended` would otherwise sound like a completion
+ // the server has already been told to drop.
+ try { playback.audio.pause(); } catch { /* element already gone */ }
+ report(playback.socket, playback.turnId, 'aborted');
+}
+
+/**
+ * The server dropped this turn (timeout, abort, switch, scene change) and
+ * said so with an idle phase. Stop only that turn — a later narration, or a
+ * stay that went listening, is still the current playback.
+ */
+export function releaseDroppedHostedSpeech(playback, phase) {
+ if (!playback || playback.settled || phase?.phase !== 'idle') return playback || null;
+ if (!phase.turnId || phase.turnId !== playback.turnId) return playback;
+ abortHostedSpeech(playback);
+ return null;
+}
+
+export function playHostedSpeech(audio, {
+ socket,
+ previous,
+ turnId,
+ target,
+ expectedTarget,
+ mimeType,
+ audioBase64,
+} = {}) {
+ if (target !== expectedTarget) return previous || null;
+ abortHostedSpeech(previous);
+ if (!turnId || !socket) return null;
+ if (!audio || !audioBase64) {
+ report(socket, turnId, 'failed');
+ return null;
+ }
+
+ const playback = { socket, audio, turnId, settled: false };
+ const finish = (status) => {
+ if (playback.settled) return;
+ playback.settled = true;
+ audio.onended = null;
+ audio.onerror = null;
+ report(socket, turnId, status);
+ };
+ audio.onended = () => finish('ended');
+ audio.onerror = () => finish('failed');
+ try {
+ audio.src = `data:${mimeType || 'audio/wav'};base64,${audioBase64}`;
+ const played = audio.play();
+ played?.catch?.(() => finish('failed'));
+ } catch {
+ finish('failed');
+ }
+ return playback;
+}
diff --git a/client/src/pages/FableLoomHostedJoin.jsx b/client/src/pages/FableLoomHostedJoin.jsx
index d88e924147..559921dad1 100644
--- a/client/src/pages/FableLoomHostedJoin.jsx
+++ b/client/src/pages/FableLoomHostedJoin.jsx
@@ -19,6 +19,7 @@ import {
Smartphone,
Volume2,
} from 'lucide-react';
+import { abortHostedSpeech, playHostedSpeech, releaseDroppedHostedSpeech } from '../components/fableloom/hostedSpeechPlayback';
// Guest-facing wording for the live-conversation gates; any other code falls
// back to the server's own message.
@@ -51,6 +52,7 @@ export default function FableLoomHostedJoin() {
const mountedRef = useMounted();
const transcriptScrollRef = useRef(null);
const audioPlayerRef = useRef(null);
+ const speechPlaybackRef = useRef(null);
// The socket effect closes over its first render; this ref keeps its
// `hosted:error` handler pointed at the current recorder state.
const discardRecordingRef = useRef(null);
@@ -101,6 +103,7 @@ export default function FableLoomHostedJoin() {
s.on('hosted:turn:phase', (data) => {
setTurnPhase(data.phase || 'idle');
+ speechPlaybackRef.current = releaseDroppedHostedSpeech(speechPlaybackRef.current, data);
if (data.phase === 'thinking') {
setIsRecording(false);
}
@@ -118,21 +121,20 @@ export default function FableLoomHostedJoin() {
});
s.on('hosted:turn:tts', (data) => {
- // If audio target is audience, play the TTS audio locally on the phone
- if (data.target === 'audience' && data.audio) {
- try {
- const audioUrl = `data:${data.mimeType || 'audio/wav'};base64,${data.audio}`;
- if (audioPlayerRef.current) {
- audioPlayerRef.current.src = audioUrl;
- audioPlayerRef.current.play().catch(() => null);
- }
- } catch (err) {
- console.warn('Audio playback error:', err);
- }
- }
+ speechPlaybackRef.current = playHostedSpeech(audioPlayerRef.current, {
+ socket: s,
+ previous: speechPlaybackRef.current,
+ turnId: data?.turnId,
+ target: data?.target,
+ expectedTarget: 'audience',
+ mimeType: data?.mimeType,
+ audioBase64: data?.audio,
+ });
});
s.on('hosted:session:ended', (data) => {
+ abortHostedSpeech(speechPlaybackRef.current);
+ speechPlaybackRef.current = null;
setTurnPhase('ended');
setAuthError(data?.reason === 'host_ended' ? 'The host has ended this play session.' : 'Session ended.');
});
@@ -140,6 +142,8 @@ export default function FableLoomHostedJoin() {
setSocket(s);
return () => {
+ abortHostedSpeech(speechPlaybackRef.current);
+ speechPlaybackRef.current = null;
s.disconnect();
};
}, [sessionId, token]);
diff --git a/client/src/pages/FableLoomHostedJoin.test.jsx b/client/src/pages/FableLoomHostedJoin.test.jsx
index bdf2be1f58..40cb22ff62 100644
--- a/client/src/pages/FableLoomHostedJoin.test.jsx
+++ b/client/src/pages/FableLoomHostedJoin.test.jsx
@@ -355,4 +355,65 @@ describe('FableLoomHostedJoin', () => {
expect(screen.getByRole('button', { name: /hold talk/i })).not.toBeDisabled();
expect(screen.getByPlaceholderText('Or type a message…')).not.toBeDisabled();
});
+
+ it('reports audience playback completion, failure, and cancellation', async () => {
+ window.location.hash = '#session=sess-123&token=tok-abc';
+ const play = vi.spyOn(HTMLMediaElement.prototype, 'play').mockResolvedValue(undefined);
+ render(<FableLoomHostedJoin />);
+ const handler = (event) => mockSocket.on.mock.calls.filter(([name]) => name === event).at(-1)?.[1];
+ const audio = document.querySelector('audio');
+ const audienceTurn = '22222222-2222-4222-8222-222222222222';
+
+ await act(async () => {
+ handler('hosted:turn:tts')({
+ target: 'host', audio: 'QQ==', mimeType: 'audio/wav', turnId: '11111111-1111-4111-8111-111111111111',
+ });
+ });
+ expect(mockSocket.emit).not.toHaveBeenCalledWith('hosted:speech:done', expect.anything());
+
+ await act(async () => {
+ handler('hosted:turn:tts')({ target: 'audience', audio: 'QQ==', mimeType: 'audio/wav', turnId: audienceTurn });
+ await Promise.resolve();
+ });
+ expect(play).toHaveBeenCalled();
+ await act(async () => { audio.onended(); });
+ expect(mockSocket.emit).toHaveBeenCalledWith('hosted:speech:done', { turnId: audienceTurn, status: 'ended' });
+
+ play.mockRejectedValueOnce(new Error('blocked'));
+ const failedTurn = '33333333-3333-4333-8333-333333333333';
+ await act(async () => {
+ handler('hosted:turn:tts')({ target: 'audience', audio: 'QQ==', mimeType: 'audio/wav', turnId: failedTurn });
+ await Promise.resolve();
+ });
+ expect(mockSocket.emit).toHaveBeenCalledWith('hosted:speech:done', { turnId: failedTurn, status: 'failed' });
+
+ const droppedTurn = '55555555-5555-4555-8555-555555555555';
+ play.mockResolvedValue(undefined);
+ const pause = vi.spyOn(HTMLMediaElement.prototype, 'pause').mockImplementation(() => {});
+ await act(async () => {
+ handler('hosted:turn:tts')({ target: 'audience', audio: 'QQ==', mimeType: 'audio/wav', turnId: droppedTurn });
+ });
+ await act(async () => {
+ handler('hosted:turn:phase')({ phase: 'idle', turnId: audienceTurn, reason: 'speech_timeout' });
+ });
+ expect(mockSocket.emit).not.toHaveBeenCalledWith('hosted:speech:done', { turnId: droppedTurn, status: 'aborted' });
+ await act(async () => {
+ handler('hosted:turn:phase')({ phase: 'listening', turnId: droppedTurn });
+ });
+ expect(mockSocket.emit).not.toHaveBeenCalledWith('hosted:speech:done', { turnId: droppedTurn, status: 'aborted' });
+ await act(async () => {
+ handler('hosted:turn:phase')({ phase: 'idle', turnId: droppedTurn, reason: 'speech_timeout' });
+ });
+ expect(pause).toHaveBeenCalled();
+ expect(mockSocket.emit).toHaveBeenCalledWith('hosted:speech:done', { turnId: droppedTurn, status: 'aborted' });
+ pause.mockRestore();
+
+ const cancelledTurn = '44444444-4444-4444-8444-444444444444';
+ await act(async () => {
+ handler('hosted:turn:tts')({ target: 'audience', audio: 'QQ==', mimeType: 'audio/wav', turnId: cancelledTurn });
+ });
+ await act(async () => { handler('hosted:session:ended')({ reason: 'host_ended' }); });
+ expect(mockSocket.emit).toHaveBeenCalledWith('hosted:speech:done', { turnId: cancelledTurn, status: 'aborted' });
+ play.mockRestore();
+ });
});
diff --git a/docs/features/fableloom-runtime-v1.md b/docs/features/fableloom-runtime-v1.md
index ebd5c5b7e5..e6fc19a6f8 100644
--- a/docs/features/fableloom-runtime-v1.md
+++ b/docs/features/fableloom-runtime-v1.md
@@ -119,29 +119,47 @@ Abort, expiration and teardown cancel the active turn. Recheck turn/session
liveness after asynchronous work so stale results cannot change a new episode
or emit after session end.
-### Speech ordering and the current hosted gap
+### Speech completion before commitment
-Portable hosts must finish narration playback before committing the chosen
-transition (and before admitting another turn). Bind a playback completion to
-the current turn, scene revision and designated output device. Treat cancellation,
-playback failure and missing completion as explicit outcomes, never an implicit
-successful acknowledgement.
+Portable hosts finish narration playback before committing a chosen transition
+and before admitting another turn. Hosted v1 binds that wait to the current
+turn and the designated output socket.
The exported reference player waits for a speech outcome bound to the turn,
node, episode and generation before it commits a move. `completed` or an
explicit `empty` may commit. `failed`, `cancelled`, `unavailable` and `missing`
leave the scene in place. A later episode or turn ignores a stale outcome.
-**Hosted v1 currently guarantees synthesis and audio dispatch before commit,
-not completed playback.** `processHostedUtterance` emits `hosted:turn:tts`
-then immediately changes the node and emits `hosted:story:transition`.
-The legacy `hosted:speech:done` handler merely changes speaking to listening;
-it neither binds the acknowledgement to a turn nor delays a transition. The
-clients currently do not emit that acknowledgement. Repair is tracked in
-[#13112](https://github.com/atomantic/PortOS/issues/13112).
-Do not infer audible completion from a TTS frame or from a committed story frame.
-The regression test pins dispatch-before-commit without claiming playback
-completion.
+When synthesis returns audio and the `audioTarget` role (`host` or `audience`)
+has a connected socket, the server emits `hosted:turn:tts` and leaves the turn
+in `speaking`. A move stays on the current node: `hosted:story:transition` is
+not emitted yet, and further live input is refused. The designated socket — the
+connected `host` or `audience` captured at dispatch — is the only one that can
+finish the wait. It sends `hosted:speech:done` with `{turnId, status}`:
+
+- `ended` commits once, after the server rechecks that the session is still
+ active, the episode and episode-switch generation are unchanged, the scene
+ generation and current node are unchanged, and the transition still targets
+ the same node. A stay returns to `listening`. A move emits
+ `hosted:story:transition` and returns to `idle`.
+- `failed` or `aborted` drops the pending transition and returns to `idle`.
+ Neither is a successful playback.
+
+A second `ended`, a different turn id, a different socket, or the other role
+does not commit. Disconnect of the designated socket, `hosted:turn:abort`,
+episode switch, session teardown, a scene change, and the bounded
+acknowledgement timeout (90 seconds) also drop the pending transition and must
+not emit it afterwards. Each of those drops emits `hosted:turn:phase`
+`{phase: "idle", turnId, reason}` when the room is still active. The output
+playing that turn stops the element, so a later `ended` is not reported as
+completion. An idle phase for a different turn leaves the current playback
+alone. A successful stay (`listening`) and a committed move do not cut audio
+with that idle frame.
+
+If synthesis produces no audio, the turn commits on the narration text
+(text-only fallback). If the designated output is not connected, nothing is
+playing, so the turn commits immediately as well. Do not treat a TTS frame or
+a committed story frame as proof that audio was heard.
## Transport-neutral event schema
@@ -158,7 +176,8 @@ join tokens or instance ids.
| `player:phase` | `{nodeId, phase, activeHoldIndex}` | Same update/sync pair for a phase-only change. |
| `turn:phase` | `{phase: "idle" \| "listening" \| "thinking" \| "speaking", turnId?, text?}` | `hosted:turn:phase`. Text is narration, not a new graph. |
| `turn:speech` | `{turnId, audio, mimeType, target: "host" \| "audience"}` | `hosted:turn:tts`; audio is base64 WAV in the private transport. |
-| `story:transition-committed` | `{transitionId, node, playbackPhase}` | `hosted:story:transition`; node is the server-projected target. |
+| `turn:speech-complete` | `{turnId, status: "ended" \| "failed" \| "aborted"}` | Client sends `hosted:speech:done`. Only `ended` from the designated output commits. |
+| `story:transition-committed` | `{transitionId, node, playbackPhase}` | `hosted:story:transition` after playback `ended` when a connected output was playing; otherwise on text-only fallback. Node is the server-projected target. |
| `session:ended` | `{reason}` | `hosted:session:ended` (also carries a private session id). |
| `runtime:error` | `{code, message}` | `hosted:error`. |
@@ -182,7 +201,9 @@ of provider configuration, adapters, LoRAs or machine-local paths.
`server/services/fableLoom/hostedSession.test.js` exercises the shared admission
policy through real turn admission, including a connected cut with a stale hold
phase, occupied audio, explicit window presence and the legacy decision default.
-Its deferred synthesis test checks the current hosted phase/event ordering.
-Existing hosted socket and weave suites cover role-scoped transport, teardown,
-stale turns and provider-free deterministic traversal. Speech playback
-acknowledgement conformance remains the explicit gap in #13112.
+Its deferred synthesis test checks dispatch-before-commit when no output
+socket is connected. Hosted session and socket suites pin the completion
+wait: only the designated output's current-turn `ended` commits, and playback
+failure, abort, disconnect, scene change, switch, teardown, and timeout drop
+the pending transition.
+Existing weave suites cover role-scoped transport and provider-free traversal.
diff --git a/server/lib/fableLoomValidation.js b/server/lib/fableLoomValidation.js
index 44892e4a40..c2ff621383 100644
--- a/server/lib/fableLoomValidation.js
+++ b/server/lib/fableLoomValidation.js
@@ -468,6 +468,11 @@ export const hostedPlaybackUpdateSchema = z.object({
activeHoldIndex: hostedSessionPatchSchema.shape.activeHoldIndex,
});
+export const hostedSpeechDoneSchema = z.object({
+ turnId: z.string().uuid(),
+ status: z.enum(['ended', 'failed', 'aborted']),
+});
+
export const productionPlanSchema = z.object({
mode: z.enum(FABLELOOM_PRODUCTION_MODES).optional(),
imageMode: z.enum(QUEUEABLE_IMAGE_MODES).optional(),
diff --git a/server/services/fableLoom/hostedSession.js b/server/services/fableLoom/hostedSession.js
index 36d18598ef..c57f975341 100644
--- a/server/services/fableLoom/hostedSession.js
+++ b/server/services/fableLoom/hostedSession.js
@@ -10,7 +10,7 @@
* 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 synthesis and dispatch before commitment (playback ACK: #13112).
+ * 8. Speech dispatch stays uncommitted until the designated output reports playback (#13112).
* 9. Reconnect snapshots and session teardown with in-flight abort.
*/
@@ -62,6 +62,12 @@ export const MAX_SESSION_TTL_MINUTES = 180;
// 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();
@@ -315,6 +321,8 @@ export async function createHostedSession(loomId, episodeId, {
hostSocketId: null,
audienceSocketId: null,
activeTurn: null,
+ pendingSpeech: null,
+ sceneGeneration: 0,
switchingEpisode: false,
episodeSwitchGeneration: 0,
createdAt: now.toISOString(),
@@ -441,6 +449,11 @@ export async function updateHostedSession(sessionId, patch = {}, { io } = {}) {
});
}
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;
@@ -485,11 +498,14 @@ export async function switchHostedEpisode(sessionId, episodeId, { io } = {}) {
// 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.
+ // 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
@@ -558,6 +574,9 @@ 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;
@@ -650,6 +669,248 @@ export async function startHostedListening(sessionId, { io } = {}) {
}
}
+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' };
+ }
+
+ const claim = 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 };
+ }
+
+ try {
+ const loom = await getLoom(session.loomId);
+ if (!speechClaimStillCurrent(session, sessionId, claim)) {
+ // The ack already consumed the wait. If the turn is still the speaking
+ // one, a scene change that lost the race with this commit has to unlock
+ // it — otherwise the room stays in `speaking` with nothing left to ack.
+ 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' };
+ }
+}
+
+/**
+ * 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.
*/
@@ -826,7 +1087,13 @@ export async function processHostedUtterance(sessionId, {
}
if (!isLive()) return abandonTurn('speech synthesis');
- // 4. Dispatch Audio to designated Audio Target
+ 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'),
@@ -835,38 +1102,35 @@ export async function processHostedUtterance(sessionId, {
turnId: turn.id,
});
}
+ if (!isLive()) return abandonTurn('speech dispatch');
- // 5. If transition is chosen, commit it AFTER speech is recorded
- if (playResult.action === 'move' && playResult.transitionId && episode) {
- const targetNode = episode.nodes?.find((n) => n.id === playResult.node?.id);
- if (targetNode) {
- session.currentNodeId = targetNode.id;
- session.playbackPhase = initialPhaseForNode(targetNode);
- session.activeHoldIndex = 0;
- session.turnPhase = 'idle';
+ if (ttsAudio && armPendingSpeech(session, sessionId, { io, turn, playResult, targetNode })) {
+ return { ok: true, awaitingSpeech: true, turnId: turn.id, playResult };
+ }
- emitIfLive('hosted:story:transition', {
- node: publicNode(targetNode, loom),
- transitionId: playResult.transitionId,
- playbackPhase: session.playbackPhase,
- });
- }
+ // 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 {
- // Stay on current node
- session.turnPhase = 'listening';
- emitIfLive('hosted:turn:phase', { phase: 'listening', turnId: turn.id });
+ releaseHostedStay(session, sessionId, { io, turnId: turn.id });
}
-
- session.activeTurn = null;
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', {
@@ -891,6 +1155,8 @@ 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;
@@ -901,6 +1167,7 @@ export function abortHostedTurn(sessionId, { reason = 'aborted', io } = {}) {
io.of('/fableloom-hosted').to(`session:${sessionId}`).emit('hosted:turn:phase', {
phase: 'idle',
reason,
+ ...(turnId ? { turnId } : {}),
});
}
return { ok: true };
@@ -966,6 +1233,7 @@ export function sweepExpiredHostedSessions({ io = sweepIo } = {}) {
export function _resetHostedSessions() {
stopHostedSessionSweep();
for (const session of activeSessions.values()) {
+ takePendingSpeech(session);
if (session.activeTurn?.abortController) {
session.activeTurn.abortController.abort('reset');
}
diff --git a/server/services/fableLoom/hostedSession.test.js b/server/services/fableLoom/hostedSession.test.js
index 238b1dee71..13ea6d8019 100644
--- a/server/services/fableLoom/hostedSession.test.js
+++ b/server/services/fableLoom/hostedSession.test.js
@@ -2,13 +2,16 @@ 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,
@@ -449,6 +452,291 @@ describe('fableLoom hostedSession', () => {
});
});
+ 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('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');
diff --git a/server/services/fableLoom/index.js b/server/services/fableLoom/index.js
index dd7b3dc027..cfba3a4bfb 100644
--- a/server/services/fableLoom/index.js
+++ b/server/services/fableLoom/index.js
@@ -93,13 +93,16 @@ export {
MAX_SESSION_TTL_MINUTES,
_getInternalSession,
_resetHostedSessions,
+ HOSTED_SPEECH_ACK_TIMEOUT_MS,
abortHostedTurn,
+ acknowledgeHostedSpeech,
checkHostedSessionReadiness,
createHostedSession,
endHostedSession,
getHostedSession,
initialPhaseForNode,
processHostedUtterance,
+ releaseHostedSpeechOutput,
revalidateLiveConversationGate,
sanitizeHostedSession,
startHostedListening,
diff --git a/server/sockets/fableLoomHosted.js b/server/sockets/fableLoomHosted.js
index 601dbf46fb..c5b5af1539 100644
--- a/server/sockets/fableLoomHosted.js
+++ b/server/sockets/fableLoomHosted.js
@@ -7,13 +7,15 @@
*/
import { SOCKET_MEDIA_MAX_BYTES } from '../lib/socketPayloadLimits.js';
-import { hostedPlaybackUpdateSchema, hostedTextTurnSchema } from '../lib/fableLoomValidation.js';
+import { hostedPlaybackUpdateSchema, hostedSpeechDoneSchema, hostedTextTurnSchema } from '../lib/fableLoomValidation.js';
import {
_getInternalSession,
abortHostedTurn,
+ acknowledgeHostedSpeech,
endHostedSession,
getHostedSession,
processHostedUtterance,
+ releaseHostedSpeechOutput,
sanitizeHostedSession,
startHostedListening,
switchHostedEpisode,
@@ -320,13 +322,20 @@ export function registerFableLoomHostedNamespace(io) {
}
});
- socket.on('hosted:speech:done', (_data) => {
- // Speech finished playback on output target
- const live = liveSession();
- if (live && live.turnPhase === 'speaking') {
- live.turnPhase = 'listening';
- ns.to(room).emit('hosted:turn:phase', { phase: 'listening' });
- }
+ socket.on('hosted:speech:done', (data) => {
+ const parsed = hostedSpeechDoneSchema.safeParse(data);
+ if (!parsed.success) return undefined;
+ // Role and socket id come from the authenticated connection, never from
+ // the payload, so the other device cannot finish this turn's playback.
+ return acknowledgeHostedSpeech(sessionId, {
+ turnId: parsed.data.turnId,
+ status: parsed.data.status,
+ role: socket.hostedRole,
+ socketId: socket.id,
+ io,
+ }).catch((err) => {
+ console.error(`❌ Hosted speech acknowledgement failed: ${err?.message || err}`);
+ });
});
socket.on('hosted:turn:abort', () => {
@@ -335,6 +344,7 @@ export function registerFableLoomHostedNamespace(io) {
// --- Disconnect lifecycle ---
socket.on('disconnect', () => {
+ releaseHostedSpeechOutput(sessionId, socket.id, { io });
if (socket.hostedRole === 'host' && session.hostSocketId === socket.id) {
session.hostSocketId = null;
} else if (socket.hostedRole === 'audience' && session.audienceSocketId === socket.id) {
diff --git a/server/sockets/fableLoomHosted.test.js b/server/sockets/fableLoomHosted.test.js
index e160d8fc2c..a33fd785e2 100644
--- a/server/sockets/fableLoomHosted.test.js
+++ b/server/sockets/fableLoomHosted.test.js
@@ -797,13 +797,98 @@ describe('fableLoomHosted Socket.IO namespace', () => {
expect(getHostedSession(session.id).episodeId).toBe('ep-1');
});
- it('returns the turn to listening on hosted:speech:done', () => {
+ it('ignores a hosted:speech:done that is not bound to the current turn', () => {
_getInternalSession(session.id).turnPhase = 'speaking';
audience.listeners['hosted:speech:done']({});
+ audience.listeners['hosted:speech:done']({
+ turnId: '00000000-0000-4000-8000-000000000000', status: 'ended',
+ });
- expect(getHostedSession(session.id).turnPhase).toBe('listening');
- expect(roomEvent('hosted:turn:phase')?.data).toMatchObject({ phase: 'listening' });
+ expect(getHostedSession(session.id).turnPhase).toBe('speaking');
+ expect(roomEvent('hosted:turn:phase')).toBeUndefined();
+ });
+
+ it('commits a move only from the designated host output for the current turn', async () => {
+ const host = connectHost();
+ weave.playTurn.mockResolvedValue({
+ action: 'move', transitionId: 'tr-1', narration: 'Onward.', node: { id: 'node-2' }, ended: false,
+ });
+
+ await audience.listeners['hosted:turn:text']({ text: 'go next' });
+
+ const turnId = roomEvent('hosted:turn:tts')?.data?.turnId;
+ expect(turnId).toEqual(expect.any(String));
+ expect(getHostedSession(session.id)).toMatchObject({ currentNodeId: 'node-1', turnPhase: 'speaking' });
+ expect(roomEvent('hosted:story:transition')).toBeUndefined();
+
+ await audience.listeners['hosted:turn:text']({ text: 'overlap' });
+ expect(audience.emitted.find((event) => event.event === 'hosted:error')?.data)
+ .toMatchObject({ code: 'TURN_IN_PROGRESS' });
+ expect(getHostedSession(session.id).currentNodeId).toBe('node-1');
+
+ await audience.listeners['hosted:speech:done']({ turnId, status: 'ended' });
+ await host.listeners['hosted:speech:done']({
+ turnId: '00000000-0000-4000-8000-000000000000', status: 'ended',
+ });
+ expect(getHostedSession(session.id)).toMatchObject({ currentNodeId: 'node-1', turnPhase: 'speaking' });
+
+ await host.listeners['hosted:speech:done']({ turnId, status: 'ended' });
+ expect(getHostedSession(session.id)).toMatchObject({ currentNodeId: 'node-2', turnPhase: 'idle' });
+ expect(roomEvents.filter((event) => event.event === 'hosted:story:transition')).toHaveLength(1);
+
+ await host.listeners['hosted:speech:done']({ turnId, status: 'ended' });
+ expect(roomEvents.filter((event) => event.event === 'hosted:story:transition')).toHaveLength(1);
+ });
+
+ it('lets the audience output commit when playback is aimed at the audience', async () => {
+ _getInternalSession(session.id).audioTarget = 'audience';
+ const host = connectHost();
+ weave.playTurn.mockResolvedValue({
+ action: 'move', transitionId: 'tr-1', narration: 'Onward.', node: { id: 'node-2' }, ended: false,
+ });
+ await audience.listeners['hosted:turn:text']({ text: 'go next' });
+ const turnId = roomEvent('hosted:turn:tts')?.data?.turnId;
+
+ await host.listeners['hosted:speech:done']({ turnId, status: 'ended' });
+ expect(getHostedSession(session.id).currentNodeId).toBe('node-1');
+
+ await audience.listeners['hosted:speech:done']({ turnId, status: 'ended' });
+ expect(getHostedSession(session.id).currentNodeId).toBe('node-2');
+ });
+
+ it('drops a pending move when playback fails or the designated host disconnects', async () => {
+ const host = connectHost();
+ weave.playTurn.mockResolvedValue({
+ action: 'move', transitionId: 'tr-1', narration: 'Onward.', node: { id: 'node-2' }, ended: false,
+ });
+ await audience.listeners['hosted:turn:text']({ text: 'go next' });
+ const failedTurn = roomEvent('hosted:turn:tts')?.data?.turnId;
+
+ await host.listeners['hosted:speech:done']({ turnId: failedTurn, status: 'failed' });
+ expect(getHostedSession(session.id)).toMatchObject({ currentNodeId: 'node-1', turnPhase: 'idle' });
+ expect(roomEvent('hosted:story:transition')).toBeUndefined();
+
+ await audience.listeners['hosted:turn:text']({ text: 'go next' });
+ const turnId = roomEvents.filter((event) => event.event === 'hosted:turn:tts').at(-1)?.data?.turnId;
+ host.listeners.disconnect();
+ expect(getHostedSession(session.id)).toMatchObject({ currentNodeId: 'node-1', turnPhase: 'idle' });
+ await host.listeners['hosted:speech:done']({ turnId, status: 'ended' });
+ expect(roomEvent('hosted:story:transition')).toBeUndefined();
+ });
+
+ it('commits a text-only turn immediately when synthesis produces no audio', async () => {
+ connectHost();
+ tts.synthesize.mockResolvedValueOnce(null);
+ weave.playTurn.mockResolvedValue({
+ action: 'move', transitionId: 'tr-1', narration: 'Onward.', node: { id: 'node-2' }, ended: false,
+ });
+
+ await audience.listeners['hosted:turn:text']({ text: 'go next' });
+
+ expect(roomEvent('hosted:turn:tts')).toBeUndefined();
+ expect(getHostedSession(session.id)).toMatchObject({ currentNodeId: 'node-2', turnPhase: 'idle' });
+ expect(roomEvent('hosted:story:transition')?.data).toMatchObject({ transitionId: 'tr-1' });
});
it('drops the in-flight turn on hosted:turn:abort', async () => {
@@ -814,6 +899,7 @@ describe('fableLoomHosted Socket.IO namespace', () => {
expect(getHostedSession(session.id).turnPhase).toBe('idle');
expect(roomEvent('hosted:turn:phase')?.data).toMatchObject({ phase: 'idle', reason: 'client_aborted' });
+ expect(roomEvent('hosted:turn:phase')?.data.turnId).toEqual(expect.any(String));
});
it('releases the audience slot and tears down listeners on disconnect', () => {