docs: update router_state incident report to the committed state

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Codex
2026-10-03 05:31:58 +09:00
parent 11c179c565
commit 20f829a73a

View File

@@ -17,9 +17,9 @@
| 증상 | EJClaw 봇 3개(claude_오너, claude_리뷰어, claude_중재자)가 Discord에서 오프라인 |
| 직접 원인 | 시작할 때 실행되는 DB 검사가 새 기능이 쓴 `router_state` 키를 "지원하지 않는 키"로 판단해 부팅을 거부함 |
| 근본 원인 | 커밋 `c858b6e`에서 새 `router_state` 키(`paired_session_task:*`)를 추가하면서 시작 검사 허용 목록은 수정하지 않음 |
| 조치 | `src/db/router-state.ts` 허용 목록에 `paired_session_task:%` 추가 (1줄) |
| 조치 | 긴급: `src/db/router-state.ts` 허용 목록에 `paired_session_task:%` 추가 (1줄). 후속: 허용 키 목록 일원화 + 쓰기 시점 차단 (9장) |
| 데이터 변경 | 없음 (DB 수정이나 삭제 없음) |
| 커밋 여부 | **아직 커밋하지 않음** (working tree 변경만 있음) |
| 커밋 여부 | 커밋 완료: `11c179c` (긴급 수정 + 재발 방지 + 회귀 테스트 + 이 문서) |
---
@@ -137,6 +137,8 @@ KAclaw는 예전 코드베이스라 paired_session_task 기능이 없음. 이
파일: `src/db/router-state.ts`, 함수 `getUnsupportedRouterStateKeysFromDatabase`
> 05:22 긴급 조치 당시의 diff임. 최종 코드(`11c179c`)에서는 이 SQL 조건 대신 `isSupportedRouterStateKey()`로 검사함 (9장 참고).
```diff
@@ -49,6 +49,7 @@ export function getUnsupportedRouterStateKeysFromDatabase(
ELSE key
@@ -148,7 +150,7 @@ KAclaw는 예전 코드베이스라 paired_session_task 기능이 없음. 이
.all() as Array<{ key: string }>;
```
- 키 전체가 `paired_session_task:`로 시작하면 검사 대상에서 제외함.
- (긴급 조치 기준) 키 전체가 `paired_session_task:`로 시작하면 검사 대상에서 제외함.
- `:`를 기준으로 자르기 **전의 원래 키**로 비교함. 그래서 `paired_session_task:music_bot_v2:reviewer`처럼 `:`가 여러 개인 키도 제외됨.
- 기존 레거시 키(`last_timestamp` 등) 검출은 그대로 동작함.
@@ -219,28 +221,29 @@ EJClaw를 재시작한 뒤 아래 항목을 차례로 확인할 것.
`systemctl --user show ejclaw.service -p NRestarts` 를 1분 간격으로 두 번 실행
→ 값이 같아야 함.
4. **수정이 남아 있음**
`grep -n "paired_session_task" /home/claude/EJClaw/src/db/router-state.ts`
→ `AND key NOT LIKE 'paired_session_task:%'` 줄이 있어야 함.
(아직 커밋하지 않았으므로 `git pull`, `git checkout .`, `git reset --hard`, `git stash`를 하면 사라지고 장애가 다시 생김)
`git -C /home/claude/EJClaw merge-base --is-ancestor 11c179c HEAD && echo ok`
→ `ok`가 나와야 함 (수정 커밋이 현재 HEAD에 포함됨).
`grep -n "PAIRED_SESSION_TASK_KEY_PREFIX\|isSupportedRouterStateKey" /home/claude/EJClaw/src/db/router-state.ts`
→ 두 이름이 모두 보여야 함.
5. **Discord 연결**
`journalctl --user -u ejclaw.service --since "10 min ago" --no-pager | grep "Discord bot connected"`
→ claude_오너, claude_리뷰어, claude_중재자 3개가 모두 보여야 함. Discord에서도 온라인이어야 함.
---
## 8. 후속 권장 사항
## 8. 후속 권장 사항 (모두 처리함, 결과는 9장)
1. **수정 커밋**: 이 변경을 커밋해서 이후 pull/reset으로 사라지지 않게 할 것.
2. **회귀 테스트 추가**: `src/db.test.ts`에 "`paired_session_task:*` 키가 있어도 시작 검사를 통과한다"는 테스트를 추가할 것.
3. **재발 방지 규칙**: 앞으로 `router_state`에 새 키를 쓰는 기능을 추가할 때는 반드시 `getUnsupportedRouterStateKeysFromDatabase` 허용 목록도 같이 수정할 것.
1. ~~**수정 커밋**~~ → `11c179c`로 처리.
2. ~~**회귀 테스트 추가**~~ → 처리. `src/db.test.ts`에 "`paired_session_task:*` 키가 있어도 시작 검사를 통과한다"는 테스트를 추가할 것.
3. ~~**재발 방지 규칙**~~ → 허용 목록 일원화 + 쓰기 차단으로 처리. 앞으로 `router_state`에 새 키를 쓰는 기능을 추가할 때는 반드시 `getUnsupportedRouterStateKeysFromDatabase` 허용 목록도 같이 수정할 것.
가능하면 허용 접두사를 `paired-session-binding.ts`의 `SESSION_TASK_KEY_PREFIX` 같은 상수와 한 곳에서 관리하도록 리팩터링할 것.
4. **원래 실패하던 테스트 2개**(`room assignment writes`)는 별도로 확인이 필요함.
4. ~~**원래 실패하던 테스트 2개**~~ → `bun test` 러너 차이로 확인됨 (vitest에서는 통과).
---
## 9. 후속 조치 (2026-10-03 05:3x, 8장 반영)
- **수정 커밋**: 이 문서와 함께 커밋함. pull/reset으로 수정이 사라질 위험은 없어짐.
- **수정 커밋**: `11c179c`로 이 문서와 함께 커밋함. pull/reset으로 수정이 사라질 위험은 없어짐.
- **재발 방지 (구조)**: `src/db/router-state.ts`에 허용 키 목록을 한 곳으로 모음
(`last_seq`, `last_agent_seq`, 접두사 `paired_session_task:`).
- 시작 검사와 **쓰기 경로**(`setRouterStateInDatabase`)가 같은 목록(`isSupportedRouterStateKey`)을 씀.