트러블슈팅

증상에서 원인으로 내려갑니다. 막힌 사람은 "헤드리스 토큰이 만료됐다"가 아니라 "아무 일도 안 일어난다"를 들고 오니까요.

어느 증상이든 화면에서 볼 자리가 먼저입니다. 앱이 이미 판정해서 그려 놓은 것을 터미널에서 다시 캐낼 이유가 없습니다. 화면이 답을 주지 못하는 데까지 갔을 때 로그를 엽니다. 로그는 워커와 세션이 자기가 한 일을 시각과 함께 한 줄씩 적어 둔 파일입니다.

아래 회색 칸의 명령은 앱이 대신 하지 않는 확인 작업이라, 터미널에 직접 입력하시면 됩니다. 명령 안의 <루트>는 큐 루트, 그러니까 프로젝트 폴더 안의 .dira입니다.

티켓이 보드에 안 보인다

화면: 보드에서 필터와 검색을 전부 푸시고, 테이블 뷰(?view=table)로도 보세요. 완료 레인은 최근 20건만 그리므로 오래된 완료는 테이블에만 있습니다. 그래도 없으면 알림 종을 여세요. 아무도 집어 가지 않는 할당됨 티켓은 레인이 아니라 거기 뜹니다.

원인: 양쪽 다 없다면 그 파일이 큐 판정을 통과하지 못한 것입니다. 셋 중 하나입니다.

• tickets/ 바로 밑이 아닙니다. 큐는 평면이라 하위 디렉터리를 보지 않습니다. 이 경우 워커가 WARN 구 레이아웃에 티켓 n건이 남아 있다를 남깁니다.
• 파일명이 .md로 안 끝나거나 .으로 시작합니다.
• 이미 .wip·.done 접미사입니다. 그건 열린 티켓이 아닙니다(티켓이 지나는 상태).

ls <루트>/tickets/                          # 평면인지, 이름이 <해시>.md인지
<루트>/workers/w1.sh list                    # 엔진이 실제로 무엇을 열린 티켓으로 보나

list에 없는데 ls에는 있다면 판정에서 빠진 것입니다. WARN 줄은 runner.log에 남습니다 (로그 읽는 법 §runner.log).

대기인데 아무도 안 집는다

화면: 카드에 주황색 deps 태그가 붙었는지 보세요. 붙었다면 선행 티켓이 아직 안 끝난 것이고, 선행이 끝나면 아무도 손대지 않아도 사라집니다. 태그가 없으면 알림 종을 여세요. 답변을 기다리는 티켓과 아무도 집어 가지 않는 티켓이 거기 각각 자기 건수를 말합니다.

원인은 종 항목마다 다릅니다.

• 답변 대기 — 세션이 막혀 ## 질문 n을 붙이고 스스로 잠갔습니다. 존재하지 않는 해시가 deps로 걸려 있어서, 사람이 답을 쓰기 전에는 어떤 워커도 집지 않습니다. 티켓 상세의 진행 기록 맨 끝 입력칸이 그 답을 쓰는 자리입니다. 같은 티켓이 계속 죽어서 여기 온 경우도 있습니다. 자동 회수는 2회까지고 3회째부터 답변 요청으로 넘어갑니다(세션이 ## 블록을 남겼으면 횟수와 무관하게 즉시 넘어갑니다).
• 아무도 집어 가지 않는 티켓(할당됨) — 열린 파일인데 session_id가 채워져 있습니다. 엔진이 만들지 않는 조합이고, 이 상태가 되면 선정에서 영구 제외돼 조용히 죽습니다. 종 안의 그 줄에 붙은 할당 해제 버튼 하나로 풀립니다.

<루트>/workers/w1.sh list                       # deps 대기 / 할당됨이 그대로 찍힌다
tail -20 <루트>/workers/runner.log | grep ASK   # 답변 요청으로 전환된 시점

워커는 도는데 아무것도 안 한다

화면: 헤더 우측의 설정 버튼을 보세요. 인증이 없으면 그 버튼 자체에 인증 필요가 붙습니다. 알림 종 첫 항목도 같은 것을 말합니다. claude 인증이 없어 티켓이 디스패치되지 않습니다. 설정 다이얼로그의 인증 구획에서 그 자리에서 발급하시면 됩니다(인증).

원인: 헤드리스 토큰이 없거나 만료됐습니다. 엔진이 claude이고 비대화형(cron)인데 oauth-token이 없으면 그 후보만 건너뛰고(SKIP), 처음 한 번만 로그에 남깁니다(.authwarn 파일로 중복 로그를 막습니다). claude 아닌 엔진을 쓰는 다른 후보가 있다면 그쪽은 정상 디스패치됩니다 — 굶는 것은 claude 후보뿐입니다. 토큰이 있지만 만료됐다면 디스패치는 일어나되 세션이 인증 오류로 곧바로 끝나 FAIL로 남습니다.

ls -la ~/.config/dira/oauth-token             # 파일이 있는지, 언제 만들었는지
grep 'AUTH 대기' <루트>/workers/runner.log     # SKIP AUTH 대기 ... 최초 1회만 남는 줄

FAIL이 찍혀 있다면 이유는 그 줄의 세션 로그에 있습니다(로그 읽는 법 §logs/).

세션이 뜨자마자 죽는다

화면: 알림 종의 세션이 열리자마자 죽는 워커 항목입니다. 한도 소진·API 과부하·연결 끊김처럼 큐도 워커도 멀쩡한데 세션만 죽는 경우고, 사유 문구에 복구 시각이 들어 있으면 그대로 보여 줍니다(session limit · resets 7:40pm 같은 줄).

원인: 앱 밖입니다. 여기서 하실 일은 기다리거나 한도를 올리는 것이지 큐를 고치는 게 아닙니다. 그동안 워커는 idle↔running을 오가고 티켓은 대기에 앉아 있어서 화면의 다른 곳은 전부 정상으로 보입니다. 이 항목이 따로 있는 이유가 그것입니다.

이 알림은 저절로 꺼집니다. 마지막 tick 결과가 10분보다 오래됐거나 다음 tick이 DONE이면 사라집니다.

기다리기 싫으시면 손으로 지우셔도 됩니다. 항목 오른쪽 아래 읽음으로 표시를 누르면 그때 나열돼 있던 실패가 한 번에 덮이고 항목이 통째로 접힙니다. 한도가 풀린 걸 이미 아는데 문구가 아직 남아 있을 때 쓰라고 있는 버튼입니다. 네 알림 중 이렇게 지울 수 있는 것은 이 항목뿐이고, 나머지 셋은 사람이 손을 대야 꺼집니다.

지운다고 다음 사고까지 묻히지는 않습니다. 덮이는 단위가 워커가 아니라 실패 하나이고 그 키가 실패의 로그 파일명이라서, 새 FAIL이 오면 파일명이 달라 항목이 다시 뜹니다.

grep -E 'FAIL|TIMEOUT' <루트>/workers/runner.log | tail -5

FAIL 줄 꼬리의 로그 파일명이 사유의 원본입니다. 마지막 줄 JSON의 result가 그 문구입니다 (로그 읽는 법 §logs/).

워커가 stale이다

화면: 워커 화면의 상태 칸입니다. 행마다 pid가 같이 보입니다.

원인: 이게 항상 오작동은 아닙니다. 회수(reap)는 죽은 세션이 쥐고 있던 티켓을 다시 열린 상태로 돌려놓는 동작인데, 그 판정 기준이 시간이 아니라 프로세스 생존입니다. 오래 걸리는 정상 세션과 매달린 세션은 걸린 시간만으로 구분되지 않으니까요. pid가 살아 있으면 running이라 아무리 오래 걸려도 그대로 두고, 죽었으면 stale이며 다음 tick이 회수합니다(디스패치 직후 3분 유예는 있습니다). stale을 보셨다면 대개 30초 안에 저절로 풀립니다.

<루트>/workers/w1.sh reap                                 # 지금 한 번 강제로 돌려본다
tail -20 <루트>/workers/runner.log | grep -E 'REAP|SKIP'

REAP이 찍히면 회수된 것이고, 아무것도 안 찍히면 세션이 아직 살아 있습니다. 그럴 때는 기다리시면 됩니다(로그 읽는 법 §runner.log).

cron에 등록됐는데 안 깨어난다

화면: 워커 화면의 상태 칸이 stopped면 crontab에 그 워커의 줄이 없다는 뜻입니다(파일만 있습니다). idle이면 등록은 돼 있습니다.

원인: 앱에서 워커를 등록할 때마다 macOS가 앱 관리 권한을 다시 묻습니다. 앱이 crontab에 줄을 쓰는 동작이라 그렇습니다. 전체 디스크 접근 권한과는 별개고, 이 승인은 다음 등록까지 남지 않습니다. 응답하기 전까지 등록 자체가 멈춰 있어서, 창을 놓치면 "만들었는데 안 돈다"로 보입니다(인증 §앱 관리).

crontab -l | grep <워커이름>     # 그 워커의 두 줄이 실제로 등록됐는지

안 보이면 설정 › 개인정보 보호 및 보안 › 앱 관리에서 승인하고 워커를 다시 만드세요. 손으로 거는 절차는 엔진만으로 돌리기 §crontab 두 줄에 있습니다. 등록은 됐는데 로그가 아예 안 자란다면 다음 항입니다(로그 읽는 법 §cron.log).

워커가 아예 안 뜬다

화면: 프로젝트 목록에서 그 프로젝트가 연결 안 됨이거나, 워커 화면에 있어야 할 행이 아예 없습니다. 앱도 그 경로를 못 읽고 있다는 뜻이라, 이건 큐의 문제가 아니라 경로의 문제입니다.

원인: 큐 루트가 클라우드 마운트(구글드라이브 등)인데 마운트가 안 붙어 있습니다. 워커 파일 자체가 그 마운트 안에 있으니, 마운트가 빠지면 cron이 때리는 경로에 실행할 스크립트가 없습니다. 에러 없이 조용히 실패해서 "큐가 비어서 안 도는구나"로 오해하기 쉬운 자리입니다(엔진만으로 돌리기 §큐를 프로젝트 밖에 둘 때).

ls <루트>/workers/     # 워커 파일이 실제로 보이는지부터 확인

안 보이면 마운트 상태를 먼저 보세요. 마운트는 붙어 있고 행도 보이는데 runner.log가 자라지 않는다면 셔뱅이나 실행 권한이 깨진 것이고, 그건 cron.log에만 남습니다(로그 읽는 법 §cron.log).

다음은 로그 읽는 법입니다.