docs: remove resolved router_state incident report

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Codex
2026-10-03 14:03:16 +09:00
parent 20f829a73a
commit 23f9271d04

View File

@@ -1,264 +0,0 @@
# 장애 보고서: EJClaw 전체 봇 오프라인 (2026-10-03)
- 작성: Claude Code (Opus 5.5)
- 작성 시각: 2026-10-03 05:3x KST
- 대상: `ejclaw.service` (`/home/claude/EJClaw`)
- 영향 없음: `kaclaw.service` (계속 정상 동작)
---
## 1. 요약
| 항목 | 내용 |
|---|---|
| 장애 시작 | 2026-10-03 05:11:01 KST |
| 복구 완료 | 2026-10-03 05:22:23 KST (이후 안정) |
| 장애 시간 | 약 11분 |
| 증상 | EJClaw 봇 3개(claude_오너, claude_리뷰어, claude_중재자)가 Discord에서 오프라인 |
| 직접 원인 | 시작할 때 실행되는 DB 검사가 새 기능이 쓴 `router_state` 키를 "지원하지 않는 키"로 판단해 부팅을 거부함 |
| 근본 원인 | 커밋 `c858b6e`에서 새 `router_state` 키(`paired_session_task:*`)를 추가하면서 시작 검사 허용 목록은 수정하지 않음 |
| 조치 | 긴급: `src/db/router-state.ts` 허용 목록에 `paired_session_task:%` 추가 (1줄). 후속: 허용 키 목록 일원화 + 쓰기 시점 차단 (9장) |
| 데이터 변경 | 없음 (DB 수정이나 삭제 없음) |
| 커밋 여부 | 커밋 완료: `11c179c` (긴급 수정 + 재발 방지 + 회귀 테스트 + 이 문서) |
---
## 2. 증상
`systemctl --user status ejclaw.service`의 결과:
```
Active: activating (auto-restart) (Result: exit-code)
Process: ... ExecStart=/home/claude/.bun/bin/bun src/index.ts (code=exited, status=78)
```
- 프로세스가 시작한 지 약 0.5초 만에 exit code 78(`CONFIG`)로 종료됨.
- systemd가 5초 간격으로 다시 시작했지만 매번 똑같이 실패함. 05:11~05:22 사이 실패 로그는 122건, restart counter는 40을 넘음.
- Discord에 로그인하는 단계까지 가지 못해 봇이 모두 오프라인이었음.
반복된 에러 로그:
```
ERROR (claude): Failed to start EJClaw {"exitCode":78}
StartupPreconditionError: Unsupported router_state DB keys remain before startup
(keys=paired_session_task:base_all,paired_session_task:base_all:reviewer,
paired_session_task:music_bot_v2,paired_session_task:music_bot_v2:reviewer)
at assertNoUnsupportedRouterStateDbKeys (src/db/database-lifecycle.ts:87:13)
at openInitializedPersistentDatabase (src/db/database-lifecycle.ts:97:3)
at initDatabase (src/db/runtime-database.ts:12:8)
at main (src/index.ts:251:3)
```
---
## 3. 원인 분석
### 3.1 시작 검사 로직
`src/db/database-lifecycle.ts`의 `openInitializedPersistentDatabase()`는 DB를 연 뒤 다음 순서로 사전 조건을 검사함:
1. `assertNoPendingLegacyRoomMigration`
2. `assertNoUnexpectedDataStateFiles`
3. **`assertNoUnsupportedRouterStateDbKeys`** ← 여기서 실패
3번이 호출하는 `getUnsupportedRouterStateKeysFromDatabase()`(`src/db/router-state.ts`)는
`router_state` 테이블의 모든 키를 다음 기준으로 검사함:
- 키에 `:`가 있으면 **첫 번째 `:` 뒤의 부분**을, 없으면 키 전체를 꺼냄
- 꺼낸 값이 `'last_seq'`, `'last_agent_seq'` 중 하나가 **아니면** "지원하지 않는 키"로 판단
- 지원하지 않는 키가 하나라도 있으면 `StartupPreconditionError`를 던지고 exit 78로 종료
원래 이 검사는 예전 버전에서 남은 레거시 키(`last_timestamp`, `last_agent_timestamp` 등)가 남은 채로
시작하는 일을 막으려고 만든 안전장치임 (`src/db.test.ts:1974` 테스트 참고).
### 3.2 새로 생긴 키
2026-10-01 20:25 커밋 `c858b6e` "feat: scope paired owner/reviewer sessions to one paired task"에서
`src/paired-session-binding.ts`가 추가됨.
- 목적: paired 방에서 owner/reviewer 세션이 몇 주씩 이어지며 관련 없는 대화까지 계속 읽는 문제를 줄이기 위해,
세션을 하나의 paired task 범위로만 resume하도록 함.
- 저장 방식: 세션 폴더와 task를 묶은 정보를 `router_state` 테이블에
`paired_session_task:<sessionFolder>` → `<taskId>` 형태로 저장함.
- 호출 위치: `src/message-agent-executor.ts:346`의 `bindPairedSessionToTask(sessionFolder, sessionTaskId)`.
실제로 생긴 키:
```
paired_session_task:base_all
paired_session_task:base_all:reviewer
paired_session_task:music_bot_v2
paired_session_task:music_bot_v2:reviewer
```
이 키들은 검사 로직에서 각각 `base_all`, `base_all:reviewer`, `music_bot_v2`, `music_bot_v2:reviewer`로 해석되므로
허용 목록(`last_seq`, `last_agent_seq`)에 해당하지 않음. 그래서 **정상 데이터인데도 "지원하지 않는 키"로 판단됨**.
### 3.3 왜 바로 터지지 않고 05:11에 터졌나 (타임라인)
시작 검사는 **프로세스가 시작할 때 한 번만** 실행되므로, 실행 중에 키가 새로 생겨도 그 프로세스는 문제없이 동작함.
문제는 그 키가 생긴 **뒤에 처음 재시작할 때** 나타남.
| 시각 (KST) | 사건 |
|---|---|
| 10-01 20:25 | 커밋 `c858b6e` (새 키를 쓰는 기능 추가) |
| 10-01 20:52 | 커밋 `2e285c5` (현재 HEAD) |
| 10-02 02:08:13 | ejclaw 재시작 → 새 코드로 시작. 이 시점에는 DB에 새 키가 없어서 검사 통과 |
| 10-02 02:08 ~ 10-03 05:11 | 정상 운영. paired 방(base_all, music_bot_v2)에서 작업하면서 `paired_session_task:*` 키 4개가 DB에 저장됨 |
| 10-03 05:11:00 | `ejclaw.service`가 stop됨(SIGTERM). 진행 중이던 그룹 2개의 restart context를 저장함. 누가 재시작했는지는 로그로 확인 안 됨 |
| 10-03 05:11:01 | 재시작했지만 시작 검사에서 실패 → **이때부터 crash loop** |
| 10-03 05:11 ~ 05:22 | 5초 간격으로 계속 재시작했지만 매번 실패 (122건) |
| 10-03 05:2x | 원인 확인, 코드 수정 |
| 10-03 05:22:12 | 수정된 코드로 자동 재시작 성공 |
| 10-03 05:22:23 | 수동 `systemctl --user restart` → PID 3195300으로 안정적으로 동작 시작 |
| 10-03 05:22:24~26 | Discord 봇 3개 연결 확인 |
정리: **기능을 추가하고 처음 재시작하면 반드시 터지는 버그**였음. 기능을 배포한 직후(02:08)에는 아직 키가 없어서 드러나지 않았음.
### 3.4 KAclaw가 영향을 받지 않은 이유
KAclaw는 예전 코드베이스라 paired_session_task 기능이 없음. 이 키를 쓰지 않으므로 해당 없음. 장애 기간 내내 `active (running)`이었음.
---
## 4. 해결 방안 검토
| 방안 | 내용 | 판단 |
|---|---|---|
| A. DB에서 키 삭제 | `router_state`에서 `paired_session_task:*` 행을 지움 | ✗ 임시방편. 다음에 paired 작업을 하면 키가 다시 생기고, 그다음 재시작에서 또 터짐. 세션 스코프 정보도 사라짐 |
| B. 시작 검사 끄기 | `assertNoUnsupportedRouterStateDbKeys` 호출을 제거 | ✗ 레거시 키를 막는 안전장치까지 없어짐 |
| **C. 허용 목록에 새 키 추가** | 검사 쿼리에서 `paired_session_task:` 접두사 키를 제외 | ✓ **채택**. 근본 원인(허용 목록 누락)을 바로 고치고, 기존 안전장치와 데이터는 그대로 둠 |
---
## 5. 실제 조치
### 5.1 코드 수정
파일: `src/db/router-state.ts`, 함수 `getUnsupportedRouterStateKeysFromDatabase`
> 05:22 긴급 조치 당시의 diff임. 최종 코드(`11c179c`)에서는 이 SQL 조건 대신 `isSupportedRouterStateKey()`로 검사함 (9장 참고).
```diff
@@ -49,6 +49,7 @@ export function getUnsupportedRouterStateKeysFromDatabase(
ELSE key
END
) NOT IN ('last_seq', 'last_agent_seq')
+ AND key NOT LIKE 'paired_session_task:%'
ORDER BY key`,
)
.all() as Array<{ key: string }>;
```
- (긴급 조치 기준) 키 전체가 `paired_session_task:`로 시작하면 검사 대상에서 제외함.
- `:`를 기준으로 자르기 **전의 원래 키**로 비교함. 그래서 `paired_session_task:music_bot_v2:reviewer`처럼 `:`가 여러 개인 키도 제외됨.
- 기존 레거시 키(`last_timestamp` 등) 검출은 그대로 동작함.
### 5.2 DB
- 수정하지 않음. 기존 `paired_session_task:*` 키 4개는 그대로 유지되고 기능도 그대로 사용함.
### 5.3 서비스 재시작
```
systemctl --user restart ejclaw.service
```
- 재시작 때 진행 중이던 그룹 2개(music_bot_v2, 기본_codex)는 SIGTERM으로 중단됨. EJClaw의 restart context 및 recovery 모드가 이를 다시 큐에 넣었음
(`Queued interrupted paired turn attempt for restart recovery`). 05:22:23의 `Agent killed by signal` / `Agent exited with error` 로그는
이 재시작 때문에 생긴 정상적인 중단 로그임.
---
## 6. 결과 및 검증
### 6.1 서비스 상태
```
ActiveState=active
MainPID=3195300
NRestarts=0
ActiveEnterTimestamp=Sat 2026-10-03 05:22:23 KST
```
### 6.2 Discord 연결 로그
```
05:22:24 Discord bot connected {"username":"claude_오너#7927"}
05:22:25 Discord bot connected {"username":"claude_리뷰어#6669"}
05:22:26 Discord bot connected {"username":"claude_중재자#7544"}
```
이후 `StartupPreconditionError`가 다시 발생하지 않음.
### 6.3 테스트
`bun test ./src/db.test.ts` 결과:
- 수정 후: **83 pass / 2 fail**
- 수정 전(`git stash` 후 같은 테스트 실행): **83 pass / 2 fail**. 실패한 테스트도 같음
실패한 2개는 이번 수정과 관계없이 원래 실패하던 테스트임:
- `room assignment writes > does not create a legacy room projection table when assigning a canonical room`
- `room assignment writes > keeps canonical room metadata writable after explicit migration drops the legacy table`
주의: 경로 없이 `bun test src/db.test.ts`로 실행하면 `data/workspaces/general/owner/src/db.test.ts`
(에이전트 워크스페이스에 있는 사본)까지 함께 실행되어 결과가 섞임. 반드시 `./src/db.test.ts`처럼 경로를 지정할 것.
---
## 7. 재시작 후 확인 체크리스트
EJClaw를 재시작한 뒤 아래 항목을 차례로 확인할 것.
1. **서비스 상태**
`systemctl --user status ejclaw.service`
→ `active (running)`이어야 함. `activating (auto-restart)`이면 실패한 것.
2. **시작 에러 없음**
`journalctl --user -u ejclaw.service --since "10 min ago" --no-pager | grep StartupPreconditionError`
→ 출력이 없어야 함.
3. **재시작 횟수가 늘지 않음**
`systemctl --user show ejclaw.service -p NRestarts` 를 1분 간격으로 두 번 실행
→ 값이 같아야 함.
4. **수정이 남아 있음**
`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. 후속 권장 사항 (모두 처리함, 결과는 9장)
1. ~~**수정 커밋**~~ → `11c179c`로 처리.
2. ~~**회귀 테스트 추가**~~ → 처리. `src/db.test.ts`에 "`paired_session_task:*` 키가 있어도 시작 검사를 통과한다"는 테스트를 추가할 것.
3. ~~**재발 방지 규칙**~~ → 허용 목록 일원화 + 쓰기 차단으로 처리. 앞으로 `router_state`에 새 키를 쓰는 기능을 추가할 때는 반드시 `getUnsupportedRouterStateKeysFromDatabase` 허용 목록도 같이 수정할 것.
가능하면 허용 접두사를 `paired-session-binding.ts`의 `SESSION_TASK_KEY_PREFIX` 같은 상수와 한 곳에서 관리하도록 리팩터링할 것.
4. ~~**원래 실패하던 테스트 2개**~~ → `bun test` 러너 차이로 확인됨 (vitest에서는 통과).
---
## 9. 후속 조치 (2026-10-03 05:3x, 8장 반영)
- **수정 커밋**: `11c179c`로 이 문서와 함께 커밋함. pull/reset으로 수정이 사라질 위험은 없어짐.
- **재발 방지 (구조)**: `src/db/router-state.ts`에 허용 키 목록을 한 곳으로 모음
(`last_seq`, `last_agent_seq`, 접두사 `paired_session_task:`).
- 시작 검사와 **쓰기 경로**(`setRouterStateInDatabase`)가 같은 목록(`isSupportedRouterStateKey`)을 씀.
- 등록하지 않은 키를 쓰려고 하면 **그 자리에서 에러**가 남. 그래서 새 키를 추가한 기능은 테스트나 첫 쓰기에서 바로 드러나고,
"다음 재시작 때 서비스 전체가 crash loop"로 번지지 않음.
- `paired-session-binding.ts`는 접두사 상수 `PAIRED_SESSION_TASK_KEY_PREFIX`를 이 파일에서 가져다 씀(중복 정의 제거).
- SQL `LIKE 'paired_session_task:%'`는 `_`가 와일드카드라 느슨했는데, `startsWith`로 바꿔 정확히 비교함.
- **회귀 테스트** (`src/db.test.ts`):
- 앱이 실제로 쓰는 키(`last_seq`, `last_agent_seq`, `bindPairedSessionToTask`로 만든 owner/reviewer 키)가 있는 DB로 다시 시작해도 통과.
- 등록하지 않은 키(`some_new_feature:room`, 레거시 `last_timestamp`) 쓰기는 거부.
- 두 테스트 모두 수정 전 코드에서는 실패하는 것을 확인함.
- **검증**: `bun run test`(vitest) 1,710 pass / 0 fail, `tsc --noEmit`, `eslint`, `prettier --check` 통과.
실DB 사본으로 새 시작 경로(`openInitializedDatabaseFromFile`)를 돌려 통과 확인.
- **6.3의 "원래 실패하던 테스트 2개"**: 프로젝트 테스트 러너인 vitest(`bun run test`)에서는 통과함.
`bun test`(bun 내장 러너)에서만 `.get()`이 `undefined` 대신 `null`을 돌려줘서 실패하는 러너 차이이며, 코드 결함이 아님.
앞으로 테스트는 `bun run test` 또는 `bunx vitest run <파일>`로 실행할 것.
- **05:11 재시작을 건 쪽**: `기본_codex`(test_channel) 방의 에이전트가 채널(`joke-app`) 등록 후 `systemctl restart`를 직접 실행함.
등록 스크립트도 같은 시작 검사(`initDatabase`)를 거치므로 그때 이미 막혀 있었고, 에이전트는 DB에 직접 써서 등록을 마쳤음(05:23 완료).