From 23f9271d041f5b0ced750bd53697e830b25229cf Mon Sep 17 00:00:00 2001 From: Codex Date: Sat, 3 Oct 2026 14:03:16 +0900 Subject: [PATCH] docs: remove resolved router_state incident report Co-Authored-By: Claude Opus 5.5 --- docs/fix-2026-10-03-router-state-startup.md | 264 -------------------- 1 file changed, 264 deletions(-) delete mode 100644 docs/fix-2026-10-03-router-state-startup.md diff --git a/docs/fix-2026-10-03-router-state-startup.md b/docs/fix-2026-10-03-router-state-startup.md deleted file mode 100644 index 606b25c..0000000 --- a/docs/fix-2026-10-03-router-state-startup.md +++ /dev/null @@ -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:` → `` 형태로 저장함. -- 호출 위치: `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 완료).