텍스팅 수업 진행자 부재 시 AI 듣기 OFF 원인 확정 해결 설계 구현 완료 QA 대기

결론

effectiveListeningEnabled =
  configuredListeningEnabled ||
  (fallbackFeatureEnabled
     && isTextingLesson
     && !manualListeningOff            // 진행자 수동 OFF 가 presence 판정을 이긴다
     && monitorPresence !== "present")

문제 상황

텍스팅 수업에서는 AI의 아동 음성 입력을 막기 위해 기본 듣기 OFF를 사용한다. 진행자는 별도 host relay로 아동 음성을 듣고, 들은 내용을 텍스트 메시지로 AI 세션에 대신 주입한다.

1. 아동이 활동을 시작하며 AI 세션을 생성한다.
2. 텍스팅 수업 기본값에 따라 AI 듣기는 OFF다.
3. 진행자가 해당 room을 모니터링하지 않는다.
4. 아동이 말해도 AI 음성 입력은 차단되고, 진행자 텍스트 입력도 없다.
5. AI가 응답할 사용자 입력을 받지 못한다.

현재 코드에서 확인되는 원인

presence의 정확한 정의

hasActiveMonitor =
     // ① 포커스뷰 — HOST_START_MONITORING claim
     claims.some(c => c.role === "host"
                  && c.peerKind === "monitoring-claim"
                  && c.monitoringRoomId === roomId)
     // ② 통합 모니터링(카드뷰) — HOST_START_GROUP_MONITORING claim
  || claims.some(c => c.role === "host"
                  && c.peerKind === "group-monitoring-claim"
                  && c.monitoringGroupId === routerManager.getGroupId(roomId))

// 진단 전용 — authoritative presence 계산에는 포함하지 않음
hasMonitorSocketMembership =
  socketsInRoom.some(s => roleOf(s) === "host")

monitorPresenceMismatch =
  hasMonitorSocketMembership !== hasActiveMonitor

오판 조건의 실제 범위 — 초안 표현은 과장이었다

"통합 모니터링 수업 전반에서 상시 무력화"라는 초안 문장은 코드 경로를 더 따라가 보면 성립하지 않는다. ②가 실제로 판정을 좌우하는 조건은 하나로 좁혀진다.

구현 함정 — 현재 Redis에는 카드뷰 group claim 인덱싱이 누락돼 있다

• monitor-presence: 진행자가 대시보드에 접속한 상태일 뿐이므로 판정에서 제외한다.
• monitoring-claim / group-monitoring-claim: 특정 room·group을 실제로 점유·모니터링하므로 authoritative 판정에 포함한다.
• room socket monitor 멤버십: claim 생성 전·해제 후의 짧은 전환 구간이나 stale UI에도 남을 수 있으므로 presence OR 조건이 아니라 mismatch 진단에 사용한다.
• existingProducers: producer 존재는 모니터링 claim과 무관하므로 판정에 쓰지 않는다.
• cross-instance 배포에서는 로컬 peers Map만 보지 않고 Redis claim과 생존 확인을 사용한다.
• stale/zombie claim은 presence로 인정하기 전에 기존 cleanup 경로로 제거한다. socket 멤버십은 연결이 끊기면 adapter에서 사라지지만 claim과의 일시적 불일치는 메트릭으로 관측한다.

해결 계약

1. snapshot 조회 — 입장과 소켓 재연결 시에만

presence를 push 이벤트(2번)로 유지하므로 모든 startSession 직전에 동기 조회할 필요가 없다. 조회 시점은 두 곳으로 한정한다.

socket.emit("get-room-monitor-presence", { roomId }, response => {
  // { roomId, hasActiveMonitor, monitorCount, revision }
})

// 호출 지점 (구현)
//   (i)  세션 시작(confirmReady) — 이 시점에 guest peer 가 존재한다
//   (ii) 조회 실패 시 bounded retry
// 재연결 복구는 클라이언트가 조회하지 않는다 → 서버가 JOIN_ROOM(role guest) 시점에
//   해당 소켓으로 snapshot push (아래 authz 항목 참조)
// 그 외 세션 start 는 push 로 유지한 ref 최신값을 읽어
//   startSession({ initialListeningEnabled }) 로 전달

// 권한: 클라이언트가 보낸 roomId 를 신뢰하지 않는다
//   게스트  → 자기 peer 의 roomId 와 일치할 때만
//   진행자  → monitoringRoomId / joinedRoomId 와 일치할 때만
//   그 외   → FORBIDDEN

조회 결과는 present | absent로 저장한다. 응답 전·timeout·오류는 unknown이다(3번 참조).

2. 수업 전체의 실시간 변경 알림

socket.on("room-monitor-presence-changed", payload => {
  // HOST_START_MONITORING / HOST_STOP_MONITORING /
  // HOST_START_GROUP_MONITORING / HOST_STOP_GROUP_MONITORING /
  // disconnect / zombie cleanup 뒤 서버가 발행
})

AI 세션이 정지 상태면 presence만 갱신하고, 활성 상태면 effective listening을 즉시 다시 계산한다. 이 채널이 정상 동작하는 것이 1번 축소의 전제이므로, 발행 지점 누락은 곧 stale presence로 이어진다.

type RoomMonitorPresence = {
  roomId: string
  hasActiveMonitor: boolean
  monitorCount: number
  revision: number
}

// push: 단조 비교로 순서 역전·중복 방어
if (payload.revision <= presenceRevisionRef.current) return
presenceRevisionRef.current = payload.revision
applyMonitorPresence(payload)

// snapshot(입장·재연결 응답): 무조건 authoritative — ref 를 덮어쓴다
presenceRevisionRef.current = snapshot.revision
applyMonitorPresence(snapshot)

3. unknown 처리 — 즉시 fail-open 금지

조회 실패를 곧바로 듣기 ON으로 처리하면 오작동이 조용히 누적된다. 진행자가 있는데 켜져도 모니터 UI에는 아무 표시가 없어(설정 오염 금지 원칙 때문) 진행자는 "듣기 OFF인데 AI가 반응한다"만 보고 원인을 추적할 수 없다. 조회 실패율이 높은 환경에서는 상시 ON으로 degrade한다.

4. 초기 입장 응답 명시화

{
  status: "waiting-approval" | "joined-room-standalone",
  hasActiveMonitor: boolean,
  monitorPresenceRevision: number
}

기존 RoomNotFound는 실제로 room이 없는 뜻이 아니라 “활성 모니터 없음”으로 사용되고 있다. 신규 계약은 이를 도메인 상태로 명확하게 분리한다.

게스트 상태와 반복 start/stop

type MonitorPresence = "unknown" | "present" | "absent";

configuredListeningEnabled // 진행자가 정한 원래 값
monitorPresence            // 수업 생명주기 동안 유지
fallbackActive =
  fallbackFeatureEnabled &&
  isTextingLesson &&
  monitorPresence !== "present"
effectiveListeningEnabled =
  configuredListeningEnabled || fallbackActive

부작용 방지 원칙

• 설정값을 덮어쓰지 않는다. 자동 fallback은 routerManager.isMicrophoneEnabled나 진행자 UI의 원래 듣기 값을 변경하지 않는다.
• host-toggle-microphone: true를 재사용하지 않는다. 이 이벤트는 persisted room state와 모니터 UI까지 ON으로 오염시킬 수 있다.
• AI input만 제어한다. host relay mute, raw microphone source, recording producer는 presence fallback의 대상이 아니다.
• 세션 경계보다 바깥에 presence를 둔다. stopSession이 presence를 false/unknown으로 초기화하지 않게 한다.
• stale React closure를 피한다. 반복되는 세션 시작과 Socket 콜백은 최신 값을 읽는 ref를 사용한다.
• 초기 연결부터 적용한다. 가능하면 startSession({ initialListeningEnabled })로 전달하여 세션 생성 뒤 ON하는 짧은 입력 유실 구간을 없앤다.
• 진행자에게 보이는 상태와 실제 입력 상태를 일치시킨다. 구현 변경 초안은 fallbackActive 배지를 별도 표시(3단계)로 요구했으나, 구현에서는 실효 상태만 ON/OFF 2단계로 노출한다. 상세는 아래 진행자 UI 표시 계약 절. 어느 방식이든 목적은 같다 — 늦게 들어온 진행자가 "듣기 OFF인데 AI가 반응"하는 상황을 오해해 임의 조작하고 결국 텍스트 전달도 없는 원래 상태로 되돌아가는 것을 막는 것이다.
• 킬스위치를 둔다. 구현 변경 환경변수 대신 운영 메뉴(main/message) 전역 스위치로 구현했다. 배포 없이 끌 수 있고 진행 중 수업까지 즉시 반영된다. 상세는 아래 전역 스위치 절.

진행자 UI 표시 계약 구현 변경

초안은 configured 값을 그대로 보여주고 fallback 은 "자동" 배지로 덧붙이는 3단계 표시를 요구했다. 구현에서는 모니터 UI 가 실효 상태만 ON/OFF 두 단계로 표시한다.

표시값 = configured || fallbackActive     // "지금 AI 가 듣고 있는가"
토글값 = !표시값                          // ON 으로 보일 때 누르면 실제로 OFF 된다

// 서버 guestState 는 두 값을 분리해 그대로 보존한다
guestState.isMicrophoneEnabled   // 진행자가 정한 configured (fallback 이 덮어쓰지 않음)
guestState.listeningFallbackActive // 실제 입력이 열린 동안만 true

진행자 수동 조작 우선 구현 변경

버튼 조작 자체가 진행자 존재의 가장 강한 신호다. 따라서 수동 OFF 는 presence 판정을 이긴다.

전역 스위치 구현 변경

운영 메뉴 main/message 최하단에 "진행자 부재 시 AI 듣기 자동 ON" 전역 ON/OFF 를 둔다. 기본값 ON 이며 OFF 면 텍스팅 수업은 기존 동작(듣기 OFF 유지 = fail-closed)으로 돌아간다.

브라우저 → PUT /api/settings/listening-fallback        (멤버 세션 인증)
            ↳ withAuthAdminOrDeveloper — admin/developer 외 401/403
         → PUT {socket}/internal/settings/listening-fallback  (X-Internal-Api-Key)
         → Redis 글로벌 키 기록 → sfuNamespace.emit(LISTENING_FALLBACK_SETTING_UPDATED)
         → 게스트가 수신해 fallback 재계산 (진행 중 수업도 즉시 반영)

effective 값을 읽어야 하는 기존 코드 경로 구현 성패

"configured를 덮어쓰지 않는다"는 원칙만 지키면 끝나지 않는다. 현재 코드에는 configured intent를 유일한 소스로 읽어 마이크를 복원하는 경로가 이미 존재하고, 이 경로를 함께 바꾸지 않으면 fallback이 조용히 사라진다.

1. 스텝·활동 전환의 마이크 복원 필수

// use-step-transition.ts — 모두 configured intent(microphoneEnabledRef)만 읽는다
:78  / :102   세션 시작 후   if (microphoneEnabledRef.current) scheduleMicOnAfterFirstResponse()
:116          AI 스텝 복귀   if (microphoneEnabledRef.current) toggleMicrophone(true)
:130-137      비-AI 스텝     toggleMicrophone(false) 후 previousMicState 로 ref 원복

• 위 3개 지점과 scheduleMicOnAfterFirstResponse 게이트를 effectiveListeningEnabled 기준으로 바꾼다.
• 동시에 비-AI 스텝(full:video / full:image)에서는 fallback도 mute를 유지한다. 이 가드를 우회하면 영상·이미지 위로 AI 발화가 흐르는 문제가 재발한다 (use-step-transition.ts:124-128 — PPI-907 revert 사유).
• 비-AI 스텝 진입 시 toggleMicrophone(false)가 ref를 덮어쓰고 원복하는 패턴이 있으므로, fallback을 별도 상태로 두고 계산된 effective를 적용하는 구조여야 한다. ref를 직접 true로 써서 해결하려 하면 configured 오염 금지 원칙과 충돌한다.

2. external STT가 configured를 오염시키는 기존 경로

use-guest-page-session.ts:2566  setAgentListeningEnabled(true, "external-stt-enabled")
room-handlers.ts:534-540        STT ON → mic 강제 ON
                                "Disabling external STT must not force listening mode off"

3. VAD 프로필이 시딩되지 않은 채 AI와 직접 대화하게 된다

서버 발행 지점

구현 단계

검증 시나리오

1. 진행자 없이 텍스팅 수업에 입장해 첫 AI 세션이 듣기 ON으로 생성되는지 확인한다.
2. AI 세션을 여러 번 start/stop해도 재조회 없이 ON이 유지되는지 확인한다(push 유지값 사용).
3. 진행자가 포커스뷰에 있는 텍스팅 수업은 기존처럼 듣기 OFF로 생성되는지 확인한다.
4. ★ 활동을 2개 이상 진행해 스텝·활동 전환 후에도 fallback ON이 유지되는지 확인한다. 영상/이미지 스텝을 지나 AI 스텝으로 복귀했을 때 AI가 아동 음성에 계속 반응해야 한다. 가장 실패하기 쉬운 항목 — configured intent만 읽는 복원 경로가 남아 있으면 두 번째 활동부터 무응답이 된다.
5. 비-AI 스텝(full:video / full:image) 재생 중에는 fallback 상태에서도 AI 입력이 mute이고 영상 위로 AI 발화가 흐르지 않는지 확인한다(PPI-907 회귀 방지). 이때 모니터 듣기 표시도 OFF 로 내려간다.
6. ★ 진행자 수동 조작 우선 — fallback 으로 ON 표시된 상태에서 듣기 버튼을 누르면 실제로 OFF 되고 AI 가 아동 음성에 반응하지 않는지 확인한다. 다시 누르면 ON 이 된다.
   초안 계약에서는 이 클릭이 무시됐다 — configured 만 false 가 되고 fallback 이 유지되어 계속 듣는 상태였다.
7. 수동 OFF 후 다음 활동으로 넘어가면 억제가 풀려 presence 기준으로 재판정되는지 확인한다 (진행자가 여전히 있으면 OFF 유지, 이탈했으면 다시 ON).
8. ★ 진행자가 통합 모니터링(카드뷰)만 열어둔 텍스팅 수업도 듣기 OFF로 생성되는지 확인한다.
   재현 전제: 텍스팅 수업은 1:1 진입 시 포커스뷰로 직행하므로, 이 케이스를 만들려면 non-voice 아동을 class_groups에 편성해 카드뷰(그룹 페이지)에 노출시켜야 한다. 편성이 불가능하면 이 시나리오는 해당 없음으로 표기하고, ②는 방어적 코드로 남긴다.
9. 카드뷰 진행자가 대시보드를 닫으면(그룹 claim 삭제) 듣기 ON으로 전환되는지 확인한다.
10. external STT를 켰다 끈 뒤 진행자가 재입장했을 때 복원되는 configured 값이 의도와 일치하는지 확인한다.
11. 활성 AI 세션 중 포커스뷰 진행자가 이탈하면 듣기 ON으로 전환되는지 확인한다.
12. 진행자가 재입장하면 자동 fallback만 해제되고 원래 OFF가 복원되는지 확인한다.
13. AI 세션 정지 중 진행자 상태가 바뀐 뒤 다음 start가 최신값(push로 갱신된 ref)을 쓰는지 확인한다.
14. Socket 재연결(네트워크 순단·새로고침) 후 진행자 상태가 바뀌어 있었다면 서버 join push 로 복구되는지 확인한다. 클라이언트가 별도로 조회하지 않아도 반영돼야 한다.
15. presence 조회 권한 — 다른 수업의 roomId 로 get-room-monitor-presence 를 호출하면 FORBIDDEN 이 반환되는지 확인한다(자기 방·자기가 모니터링하는 방만 허용).
16. presence 조회 timeout(ack 무응답 3초·소켓 미연결 포함) 시 재시도 후 unknown 확정 → ON 되는지, 게스트 콘솔·LogRocket ListeningFallback:Activated 의 presence: "unknown" 으로 그 경로가 구분되는지 확인한다.
17. 음성 수업, host relay, 녹음 producer, 진행자 UI의 configured 듣기 값이 변경되지 않는지 회귀 확인한다.
18. room socket 멤버십만 남고 claim이 없는 전환·cleanup 구간에서 presence는 absent를 유지하고 mismatch 메트릭만 증가하는지 확인한다.
19. 반대 방향 — claim은 있으나 room socket 멤버십이 없는 구간(카드 언마운트 등)도 presence는 present를 유지하고 mismatch만 증가하는지 확인한다.
20. 동일 room의 오래된 revision 이벤트가 늦게 도착해도 게스트가 무시하는지 확인한다.
21. revision counter가 리셋된 상황(Redis 키 삭제 후)에서 재연결 snapshot으로 presence가 복구되는지, 그리고 Redis 미연결 배포에서 revision 비교가 꺼진 채 push가 정상 적용되는지 확인한다.
22. 다중 Socket 인스턴스에서 진행자와 게스트가 다른 인스턴스에 연결되어도 focus/group claim 판정 결과가 같은지 확인한다.
23. 전역 스위치(main/message) OFF 시 진행 중 수업까지 즉시 비활성되고 기존 동작으로 복귀하는지, ON 으로 되돌리면 다시 활성되는지, 기본값이 ON 인지 확인한다.
24. 전역 스위치 권한 — 일반 진행자(manager) 계정에서는 변경이 차단되는지(403) 확인한다. admin/developer 만 변경할 수 있어야 한다.

LLM용 구현 요약

Socket/SFU 서버에 room monitor presence 조회·변경 이벤트를 추가한다. presence는 두 authoritative claim source의 OR로 정의한다 — ① monitoring-claim(monitoringRoomId === roomId, 포커스뷰), ② group-monitoring-claim(monitoringGroupId === room.groupId, 카드뷰). room socket 멤버십의 host role은 claim과의 mismatch 진단에만 사용한다. ①만 쓰면 카드뷰로만 진입한 진행자를 absent로 오판하므로 ②를 둔다. 다만 그룹 모니터링 아동은 음성 필수이고 1:1 세션은 포커스뷰로 직행하므로, ②가 판정을 좌우하는 경우는 non-voice 아동이 class_groups에 편성된 수업뿐이다 (해당 편성의 실존은 운영 데이터로 확인해야 하며, 없으면 ②는 방어적 코드다). 현재 peer-store.ts는 group claim을 groupMonitorKey에 등록·삭제하지 않으므로 이 인덱스를 먼저 보완한다. 단 그룹 인덱스에는 포커스뷰 claim이 이미 섞여 들어가므로 peerKind 필터 정책을 함께 정한다. 모든 claim mutation과 cleanup은 중앙 presence 발행 helper를 호출하고, Redis INCR 기반 room revision을 snapshot/push에 포함한다. push는 revision 단조 비교로 걸러내되 snapshot revision은 무조건 채택해 counter 리셋에서 복구하고, Redis 미연결 배포에서는 revision 비교를 끈다. 그룹 발행과 mismatch 진단은 room 단위로 coalesce한다. 게스트는 presence를 AI 세션 바깥에서 수업 전체에 걸쳐 유지한다. configured intent만 읽는 기존 마이크 복원 경로(use-step-transition.ts:78/102/116/130-137)를 effective 기준으로 함께 바꿔야 한다 — 바꾸지 않으면 활동 전환 한 번에 fallback이 소실된다. 비-AI 스텝에서는 fallback 상태에서도 mute를 유지한다(PPI-907). external STT의 기존 강제 ON 경로가 configured를 오염시키므로 복원 대상 정의를 명시한다. VAD 프로필 시딩은 Phase 1 범위에서 제외한다. snapshot 조회는 세션 시작 시에만 하고(클라이언트 roomId 를 신뢰하지 않고 self peer 기준으로 권한 검증), 재연결 하이드레이션은 서버가 JOIN_ROOM 시점에 push 한다. 그 외 세션 start는 push로 갱신된 ref 값을 읽어 startSession({ initialListeningEnabled })로 전달한다. 텍스팅 수업에서 presence가 absent면 설정값을 바꾸지 않은 채 agent input만 ON한다. unknown은 bounded retry(ack 오류·무응답·소켓 미연결 포함) 후 확정해 fail-open으로 처리한다. 모니터 UI 는 configured || fallbackActive 실효 상태만 ON/OFF 2단계로 표시하고 토글도 그 값을 기준으로 계산한다. 진행자가 수동으로 듣기를 OFF 하면 fallback 을 억제하며(presence 보다 우선), 억제는 다음 활동에서 해제한다. 전역 스위치는 소켓 이벤트가 아니라 멤버(admin/developer) 인증이 걸린 /api/settings/listening-fallback → 소켓 내부 REST 경로로만 변경한다(소켓 핸드셰이크 무인증). 활성 세션 중 presence 변경도 같은 계산식으로 반영하고, 진행자가 돌아오면 fallback만 해제해 configured listening을 복원한다. 발행 지점에 그룹 모니터링 start/stop과 모든 claim cleanup 경로를 반드시 포함한다.

관련 코드 · 문서

• 호스트 모니터링 claim / 그룹 모니터링 — 코드레벨 동작 흐름
• SFU 서버 Socket.IO / Mediasoup — 코드레벨 동작 흐름
• LiveKit 음성 에이전트와 두 SFU 구조