23/Documentation
문제 해결
실제 검색에 사용할 만한 표현으로 정리한 증상 목록
증상은 아래에 순서대로 나와 있습니다. 페이지에서 해당하는 증상을 검색하십시오. herdr plugin의 Os { NotFound } · update에 "not currently on a branch"가 표시됨 · tailscale serve failed · 응답 없음(서비스가 시작되지 않음) · 전화기에서 URL을 열 수 없음 · 페이지는 로드되지만 빈 상태로 유지됨(빈 페이지, 403) · 비밀번호 프롬프트에 입력이 되지 않음 · 푸시 알림이 오지 않음 · 재부팅 후 사라짐 · 창 너비가 좁게 고정됨 · Collie가 tmux 창 열기를 거부함 · tmux list: output did not parse · herdr plugin list에 이전 버전이 표시됨 · 다시 빌드한 후 UI가 업데이트되지 않음 · Herdr에 머신을 저장했는데 휴대폰에 표시되지 않습니다 · 휴대폰에서 시작한 업데이트가 staging 상태로 유지됩니다 · macOS에서 휴대전화 업데이트 시 Collie가 로드되지 않는 문제 · macOS에서 collie status에 "loaded, not running"이라고 표시됨 · 창에 prompt-cache 칩이 표시되지 않는 문제 · Kiro 창의 기록이 비어 있는 상태로 열림 · 창에 채팅 또는 기록이 없음 · 새 Codex 창에 아직 기록이 없다고 표시됨 · 휴대폰에 에이전트가 표시하지 않는 화면을 Collie가 읽을 수 없다고 표시됨 · 전송이 3회 실패하여 스마트폰에서 신고를 제안합니다 · New 페이지에서 에이전트가 회색으로 비활성화되어 표시되는 경우 · Start 실행 시 폴더가 없다고 표시되거나 확인할 수 없다고 표시되는 경우 · walky talky: 전송이 거부됨, "창 내부에서 실행하십시오" · walky talky: 메시지가 수신함에 남아 있고 입력되지 않음 · walky talky: "이 머신에 로그 기록이 없음" · walky talky: 스킬이 만료됨 · durable agent가 표시되지 않거나 Unreachable로 표시되는 경우.
herdr plugin … 실행 시 Error: Os { code: 2, kind: NotFound, message: "No such file or directory" } 오류와 함께 실패합니다. (플러그인 설치 실패, 액션 호출 실패). 이것은 Collie의 문제가 아닌 아닙니다. Herdr 서버가 실행 중이지 않은 상태이므로 CLI가 제어 소켓(~/.config/herdr/herdr.sock)에 접근할 수 없음을 의미합니다. 단서는 raw Os {…} 오류입니다. 연결 가능한 서버는 경로/매니페스트 문제에 대해 구조화된 JSON(예: plugin_manifest_not_found)으로 응답하므로, 가공되지 않은 Os { NotFound } 오류가 발생하는 것은 Collie나 경로를 검사하기도 전에 소켓 연결에 실패했음을 뜻합니다. 서버와 통신하는 모든 하위 명령인 link, install, action invoke에서 발생하지만, herdr plugin --help는 계속 작동합니다(소켓을 열지 않음). 해결 방법: 먼저 Herdr를 시작하거나(herdr server &, 또는 Herdr TUI를 실행하면 서버가 부팅됨), ls ~/.config/herdr/herdr.sock 파일이 생성되었는지 확인한 후 설치를 다시 시도하십시오. herdr plugin list 명령으로 빠르게 확인할 수 있습니다. 동일한 오류가 발생하면 서버가 다운된 것입니다.
update 실행 시 You are not currently on a branch 오류와 함께 실패합니다. 0.23.1(#63) 이전에 GitHub로 설치한 경우 발생합니다. herdr plugin install는 복제하는 대신 분리(detach)되므로 이전 update에는 git pull할 브랜치가 없었습니다. 수정 사항은 복구 대상인 체크아웃 내부에 포함되어 제공되므로, 이를 적용하려면 한 번 다시 설치해야 합니다. "You are not currently on a branch" 오류가 발생하며 실패하는 경우에 세 가지 명령이 있습니다.
start 실행 시 note: tailscale serve failed 메시지를 출력합니다. Collie 자체는 정상 작동 중입니다(127.0.0.1에서 여전히 실행 중). tailnet ingress만 시작되지 않았으며, 터미널의 안내 문구 위에 tailscale 자체 오류가 표시됩니다. 일반적인 원인으로는 사용자가 Tailscale operator가 아니거나(sudo tailscale set --operator=$USER), 노드에서 로그아웃되었거나(tailscale up), Headscale / .internal tailnet 도메인에서 HTTPS 인증서를 사용할 수 없는 경우가 있습니다. COLLIE_SERVE_MODE=http은(는) 바로 이 용도로 사용됩니다. .env에서 이를 설정한 다음 bin/collie restart 명령을 실행하십시오. tailscale serve status 명령으로 확인하십시오.
serve에서 HTTPS certificates are not enabled on this tailnet을(를) 안내합니다. 게시된 항목이 없으며 대기 중인 항목도 없습니다. 관리 콘솔을(를) 열고 "Enable HTTPS"를 켠 다음 collie serve 명령을 다시 실행하십시오. Headscale / .internal 도메인에는 활성화할 인증서가 없으므로 대신 COLLIE_SERVE_MODE=http을(를) 사용하십시오.
배너에 ⚠ Collie isn't answering on :8787 yet 표시됩니다. (서비스가 시작되지 않음, 연결 거부됨). 서비스는 시작되었지만 HTTP 서버가 프로브에 응답하지 않습니다. 먼저 유닛 상태를 확인하고(systemctl --user status collie), bin/collie logs(또는 실시간 확인을 위해 journalctl --user -u collie -f)에서 원인을 확인하십시오. 대부분 포트가 이미 사용 중이거나(.env에 COLLIE_PORT를 설정한 다음 bin/collie restart를 실행하면 새 포트에 대해 tailscale serve도 다시 실행됨), 첫 번째 빌드가 실패한 경우입니다(로그에 표시됨. 문제를 수정한 후 bin/collie build 실행). 유닛은 5초마다 자동으로 재시작되므로 원인을 해결하면 대개 저절로 복구됩니다.
휴대폰에서 tailnet URL을 열 수 없습니다. 다음 목록을 순서대로 확인하십시오: (1) 휴대폰에서 Tailscale 앱이 실행 중이며 호스트와 동일한 tailnet에 연결되어 있는지 확인합니다. (2) local URL이 아닌 배너의 tailnet URL(bin/collie url)을 열고 있는지 확인합니다. http://127.0.0.1:8787는 호스트 자체에서만 작동합니다. (3) tailnet의 DNS 설정에서 MagicDNS가 활성화되어 있는지 확인합니다(URL은 MagicDNS 이름임). (4) 호스트가 온라인 상태인지 확인합니다. 호스트에서 tailscale status를 확인하거나 휴대폰의 Tailscale 앱에서 호스트로 ping을 보내십시오. (5) tailnet 정책이 실제로 이 노드에 대한 피어 접속을 허용하는 상태인지 확인합니다. 그렇지 않은 경우 배너의 tailnet 줄 아래에 해당 내용이 표시되며, 다른 방법으로는 확인할 수 없습니다. 프론트 도어는 올바르게 게시되었고, 인증서가 유효하며, 루프백은 패킷 필터를 거치지 않으므로 호스트 자체에서 보낸 curl 요청은 200을 반환합니다. 특히 두 가지 요인 때문에 혼란을 줄 수 있습니다. tailscale ping는 성공하지만(disco ping은 ACL을 우회함), 차단된 트래픽은 거부(refused)되지 않고 삭제(dropped)되므로 휴대폰에서는 응답 없이 멈추며 "서버 다운"으로 인식됩니다. ACL 정책(Tailscale의 경우 <https://login.tailscale.com/admin/acls>, Headscale의 경우 정책 파일)에서 이를 수정하십시오. 이 검사는 최선형(best-effort)으로 동작하며 의도적으로 확정하지 않습니다. 이 노드의 필터가 아무것도 허용하지 않을 때만 허용할 때만 알림을 표시하며(이는 다른 장치가 아직 tailnet에 연결되지 않았음을 의미할 수도 있음), 판단할 수 없을 때는 아무 것도 표시하지 않습니다.
페이지가 로드되지만 빈 상태로 유지됩니다. (빈 페이지, 흰색 화면); API 호출이 403 cross-origin rejected 실패합니다. Collie가 예상하지 않은 오리진(커스텀 도메인 또는 Host 헤더를 재작성하는 프록시)을 통해 접근하고 있습니다. COLLIE_ALLOWED_ORIGINS를 사용하여 정확한 공개 오리진을 허용하거나(설정 참조), 프록시가 Host를 변경 없이 전달하도록 설정하십시오(docs/deployment.md의 네 번째 프록시 요구사항).
sudo (또는 SSH 패스프레이즈, 또는 gpg) 프롬프트에 입력이 전달되지 않습니다. Send 대신 키보드 위 작업 행에 있는 Type를 사용하십시오. Send는 Enter 키를 누르기 전에 화면에서 입력 내용을 다시 읽어 확인 항목을 전송하므로(#34), 에코를 비활성화하는 암호 프롬프트에서는 다시 읽을 내용이 없습니다. 반면 Type는 Enter를 포함한 키 입력을 창으로 직접 보냅니다. Type에 입력한 내용은 저장되지 않고 초안으로 복사되거나 나중에 복원되지 않으며, Collie가 암호 프롬프트를 인식하는 즉시 저장된 초안도 삭제합니다(#103).
푸시 알림이 도착하지 않습니다. 수동으로 하나를 발송하십시오: bin/collie push-test. 명령어가 이를 구분하는 순서대로 3가지 원인이 있습니다. 푸시가 비활성화되었다고 표시되는 경우(키가 브리지에 도달하지 못했습니다. push-keys 명령을 실행하고 다시 시작하십시오. Web Push 참조), 구독된 기기가 없다고 표시되는 경우(이 휴대폰의 설정 → 알림에서 이를 활성화한 적이 없습니다), 또는 전송되었다고 보고되지만 아무것도 도착하지 않는 경우(휴대폰이 보안 컨텍스트가 아닌 일반 HTTP 오리진에 있습니다. 설정에 insecure 플래그가 표시됩니다).
재부팅 후 Collie가 사라집니다. Linux에서는 거의 항상 lingering 문제이므로 loginctl enable-linger $USER을(를) 실행하십시오(재부팅 후에도 유지하기). macOS에서는 launchd 에이전트가 login에서 시작되므로 실제로 로그인되어 있는지(로그인 화면에 머물러 있지 않은지), 에이전트가 로드되었는지 확인하십시오: launchctl print gui/$(id -u)/herdr.collie.
창의 터미널이 좁게 고정되어 내부의 전체 화면 앱이 찌그러짐 (Copilot CLI, top, 미러의 나머지 영역이 비어 있는 동안 띠 형태로 렌더링되는 모든 TUI). 해당 창의 터미널이 실제로 그만큼 좁으며, Collie는 이를 그대로 미러링합니다. Herdr 창의 너비는 탭의 분할 그리드 내 직사각형 영역에 따라 결정되므로, 탭을 공유하는 창은 열(column)을 나누어 갖습니다. Herdr는 창 지오메트리를 데스크톱 클라이언트가 연결되어 있을 때만에만 적용합니다 (herdr#1709). 연결된 클라이언트가 없으면 분할 창을 닫아도 남은 창이 이전의 좁은 너비로 고정되며, 소켓을 통한 pane.zoom 및 pane.resize 작업으로도 변경되지 않습니다. Collie 측에서는 이를 해결할 수 없습니다. Collie는 창 지오메트리를 전혀 변경하지 않습니다 (ADR 0031: 휴대전화는 Show in terminal 탭 시에만 오퍼레이터의 터미널 크기를 변경함). 이는 특정 앱에 국한된 문제가 아닙니다. 54열 창에서 실행되는 top 역시 동일하게 보입니다. 실제 너비를 측정하려면 창 내부에서 tput cols을(를) 실행하십시오. 이것이 실제 너비이며, herdr pane layout에서 보고하는 값과 다를 수 있습니다. 해결하려면 Herdr 클라이언트를 연결한 다음 해당 클라이언트에서 창을 확대하거나 크기를 조정하거나(herdr pane zoom <pane-id> --on는 클라이언트가 연결되어 있을 때 터미널 크기를 변경함), 창을 닫고 새 창을 여십시오 (#167).
Collie가 tmux 창 열기를 거부함 (휴대폰의 new tab 요청이 window-size을(를) 지목하며 거부되어 반환됨). 요청 자체의 오류가 아닙니다. 3.7 미만 tmux에서는 서버의 window-size이(가) manual인 상태에서 윈도우를 생성하면 전체 서버가 충돌하며(tmux #4849, 3.7에서 수정됨), 충돌한 서버는 모든 윈도우를 함께 종료시킵니다. Collie는 대신 요청을 거부하고 감지한 tmux를 표시합니다. 해결 방법은 출력되는 한 줄(해당 서버에서의 tmux set -g window-size latest)을 실행하거나 tmux 3.7을 사용하는 것입니다. 다른 부분에는 영향이 없습니다. 해당 창의 다른 모든 작업은 계속 작동합니다(요구 사항에도 동일한 주의 사항이 적용됩니다).
Collie 로그에 tmux list: output did not parse이(가) 기록되고 대시보드가 비어 있는 것으로 표시됩니다. 크래시가 아닙니다. 일부 tmux 버전(3.6b가 아닌 3.4)은 -F 목록 출력 시 이 어댑터가 읽는 구분 기호를 이스케이프합니다. Collie는 이제 두 형식을 모두 읽으므로 0개 행으로 파싱되는 목록은 빈 herd로 저장되는 대신 mux 오류로 보고됩니다. 오류 라인에는 tmux 버전과 감지한 라인 수가 표시됩니다. 두 번째 원인은 로캘이었습니다. UTF-8 로캘 없이 시작된 경우(최소 컨테이너, systemd 유닛), tmux는 해당 구분 기호를 이스케이프하는 대신 _로 대체합니다. Collie는 이제 모든 tmux 명령을 -u 환경에서 실행하므로 목록이 더 이상 LANG나 LC_ALL에 의존하지 않습니다. 여전히 이 문제가 발생하면 tmux -V 버전을 기록하고 이슈를 등록하십시오. 수정 작업은 .env이 아니라 어댑터에 적용되어야 합니다.
update 이후에도 herdr plugin list에 이전 버전이 표시됩니다. 정상적인 동작입니다. Herdr는 설치 또는 링크 시점에 읽은 매니페스트를 캐시합니다. 현재 실행 중인 항목에 대한 신뢰할 수 있는 기준은 바닥글의 build stamp 또는 bin/collie version입니다. 링크된 클론의 경우 update이(가) 다시 링크되어 자체 복구되며(herdr plugin link "$(pwd)"을(를) 사용하여 강제 실행), Herdr ≥0.8.0에서는 매니페스트를 디스크에서 다시 읽습니다.
재빌드 후 휴대폰에 이전 UI가 표시됩니다. PWA의 service-worker 캐시는 오리진별로 관리되므로 두 개의 오리진(사용자 지정 도메인 및 원시 host:8787)에서 Collie에 접근하면 각각 고유한 번들을 캐시하는 두 개의 설치본이 생성됩니다. 바닥글의 build stamp(vX.Y.Z · sha · time)에는 현재 실행 중인 번들이 표시됩니다. Collie는 X-Collie-Build 헤더 및 /api/config을(를) 통해 제공 중인 항목을 보고합니다. 불일치 시 바닥글에 "새 빌드 — 탭하여 업데이트."이(가) 표시됩니다. 그렇지 않은 경우 PWA를 몇 번 다시 열거나(SW가 자동 업데이트됨) 해당 오리진의 사이트 데이터를 삭제하십시오. 권장 사항: 하나의 HTTPS 오리진을 선택하여 계속 사용하십시오. (일반 HTTP에서는 SW를 등록할 수 없으므로 항상 최신 상태이지만 PWA 기능은 사용할 수 없습니다.)
Herdr에 머신을 저장했는데 휴대폰에 표시되지 않습니다. 정상적인 동작입니다. Herdr의 저장된 머신은 자체 클라이언트 목록이며 crew는 Collie 고유의 목록입니다. 두 목록은 서로 연동되지 않습니다. 휴대폰에서 해당 머신에 접근하려면 등록하십시오. lead에서 collie crew add <ssh-host>를 실행한 다음, lead에서 collie restart를 실행하고 collie crew status로 연결을 확인하십시오. Herdr에서 머신을 추가하거나 제거해도 crew에는 아무런 영향이 없습니다(Herdr 머신 및 crew).
창에 prompt-cache 칩이 표시되지 않습니다. 세 가지 원인 중 하나이며 collie doctor을 통해 구분할 수 있습니다. 창의 하네스에 저널 어댑터가 없는 경우이며, 이는 integration-<agent> 및 journal-roots 행에 명시됩니다. 창이 세션을 보고하지 않은 경우이며, 이는 agent-sessions 행에 창 id별로 표시됩니다. 또는 에이전트가 아직 턴을 수행하지 않은 경우로, 이는 오류가 아닙니다. 측정되기 전에는 아무것도 표시되지 않으므로 에이전트의 첫 응답 시 칩이 나타납니다. 벤더가 캐시 유효 기간을 공개하지 않는 하네스 역시 아무것도 표시되지 않으며, cache-claims에 이 빌드에서 제공하는 모든 규칙이 나열되어 있습니다.
Kiro 창의 기록이 비어 있는 상태로 열립니다. 창의 Kiro가 세션 잠금을 보유하고 있는지 확인하십시오.
cat ~/.kiro/sessions/*/*/.lockHerdr는 Kiro 창의 세션 이름을 지정하지 않으므로 Collie는 실행 중인 Kiro가 보유한 잠금을 통해 세션을 찾습니다. 이는 창의 포그라운드 프로세스를 나열하는 유일한 멀티플렉서인 Herdr에서만 작동하며, Kiro 프로세스가 정확히 하나만 실행 중일 때만 작동합니다. 그렇지 않으면 기록에 창에 에이전트 세션이 없다고 표시됩니다.
Collie는 --v3 또는 --agent-engine v3을(를) 사용해 시작되었거나 Kiro 자체 설정에서 V3 엔진으로 구성된 Kiro V3 세션을 읽습니다. 따라서 해당 창에서 Kiro를 해당 방식으로 다시 시작하십시오. Kiro에는 설치할 Herdr 훅이 없습니다. 세션이 다른 위치에 저장되어 있다면 kiro_root을(를) 설정한 다음 collie restart을(를) 실행하십시오.
Chat이 표시되어야 할 창에 터미널이 표시됩니다. 에이전트 창의 기본값은 Chat이므로 다음 두 가지 중 하나에 해당합니다. 이 기기에서 이전에 터미널을 선택한 경우: 창의 ⋮ 메뉴를 열고 채팅 보기를 탭하십시오. 또는 창에 세션이 없거나 읽을 로그가 없는 경우입니다. 새 창은 "Send a message to start"와 함께 Chat을 표시하며, 첫 번째 턴이 읽을 내용 없이 끝나거나 먼저 질문을 할 때 터미널로 대체됩니다. 메뉴 행에 누락된 부분이 표시되며 다음 항목에 단계가 설명되어 있습니다.
창에 Chat이나 History가 없으며, ⋮ 메뉴에 창이 세션을 지정하지 않았다고 표시됩니다. Chat 및 History는 에이전트의 세션 로그를 읽으며, Collie는 에이전트가 멀티플렉서를 통해 세션을 보고할 때만 로그를 찾습니다. Herdr에서는 해당 보고가 에이전트 자체 통합 기능에서 전달되므로, 통합 기능이 누락되었거나 오래된 경우 별다른 증상 없이 두 항목이 모두 숨겨집니다. collie doctor은(는) agent-sessions 아래에 창 이름을, integration-<agent> 아래에 수정 방법을 표시합니다.
herdr integration status을(를) 실행하십시오. 에이전트가not installed또는outdated인 경우herdr integration install <agent>을(를) 실행하십시오. Oh My Pi는omp이고 pi는pi이므로 각각 고유한 설정이 필요합니다.- 해당 창에서 에이전트를 다시 시작하십시오. 에이전트는 시작할 때 훅을 로드하므로, 설치 중에 실행 중이었던 에이전트는 계속해서 아무것도 보고하지 않습니다.
- 훅이 최신 상태이고 다시 시작한 창에서도 여전히 아무것도 보고하지 않는다면, 다른 에이전트가 연 셸에서 해당 에이전트가 시작되었는지 확인하십시오. Oh My Pi의 훅은 상위 에이전트로부터
OMPCODE=1을(를) 상속받으면 침묵을 유지합니다. 새 터미널에서 시작하십시오.
tmux, zellij, tern에서는 Claude Code만 Collie의 beacon 훅을 통해 세션을 보고합니다. collie hooks install claude(Collie는 Claude 자체 설정에 훅을 작성합니다)을 실행하십시오. 다른 agent는 해당 환경에서 Chat이나 History를 지원하지 않습니다.
새 Codex 창에 아직 기록이 없다고 표시됩니다. 첫 번째 턴 전까지는 정상적인 동작입니다. Codex는 시작할 때가 아니라 첫 프롬프트가 전송될 때만 Herdr에 세션을 보고하므로, 그때까지 새 창에는 세션과 History 링크가 없습니다. collie doctor은(는) 이러한 창을 agent-sessions 아래에 아직 보고되지 않은 상태로 표시하며, 이를 오류로 간주하지 않습니다. Codex가 응답한 후에도 해당 문구가 계속 남아 있다면 Codex에서 /hooks을(를) 여십시오. 훅이 변경되면 Codex에서 검토를 요청하며, "Continue without trusting"을 선택하면 herdr integration status에 최신 상태로 표시되더라도 Herdr 훅이 꺼집니다. 해당 화면에서 훅을 신뢰하도록 설정하거나, herdr integration install codex을(를) 실행한 뒤 새 세션을 시작하십시오.
데스크톱의 에이전트에는 일반 프롬프트가 표시되는데, 휴대폰에는 Collie가 대화 상자를 읽을 수 없다고 표시되거나 전송한 내용이 입력 상자에 도달하지 않습니다. 보통 에이전트의 화면 렌더링 방식이 변경되어 Collie가 화면을 잘못 읽었습니다. 스크린샷으로는 확인할 수 없는 정보(Collie가 읽는 색상 및 흐린 텍스트)를 담고 있는 원본 텍스트를 첨부하여 이슈를 등록해 주십시오. herdr pane list을(를) 사용하여 pane id를 확인한 후 다음을 실행하십시오.
herdr pane read <pane-id> --source recent --lines 200 --format ansi > pane.txt휴대폰에 문제가 여전히 표시되는 상태에서 실행하고, 에이전트 버전(claude --version, codex --version 등)과 함께 pane.txt을(를) 첨부하십시오. 이 파일은 터미널 텍스트이므로 먼저 내용을 확인하고 개인정보를 삭제하십시오.
전송이 3회 실패하여 스마트폰에서 신고를 제안합니다. 한 창에서 Collie 문제로 추정되는 원인(입력란을 읽거나 쓸 수 없음, 텍스트가 입력되었으나 Enter가 이어지지 않음, 또는 전송 추적이 끊김)으로 전송이 3회 연속 실패했습니다. 사용자를 보호하기 위한 거부(입력란의 임시 보관 텍스트, 실행 중인 턴, 열려 있는 대화 상자)는 횟수에 포함되지 않습니다. 카드의 신고 버튼을 탭하십시오. 외부로 전송되기 전에 Collie 및 에이전트 버전, 멀티플렉서, 각 실패한 전송의 코드 등 이슈 전체 내용이 시트에 표시됩니다. 직접 입력한 텍스트는 포함되지 않으며, 입력한 내용 포함 또는 화면 포함 옵션을 켜지 않는 한 화면 내용도 포함되지 않습니다. 화면 내용은 알려진 보안 비밀 형태를 마스킹한 해당 창의 마지막 40개 행입니다. 이슈는 공개되므로 직접 내용을 검토하십시오. GitHub에서 열기 버튼은 브라우저에서 본인의 GitHub 계정으로 내용이 입력된 양식을 열며, 보고서 복사 버튼은 동일한 텍스트를 복사합니다. 동일한 시그니처 행을 가진 이슈가 있는지 확인하려면 먼저 이미 보고하셨습니까? 버튼을 탭하십시오. 창 메뉴와 설정 → 시스템 메뉴를 통해서도 언제든지 동일한 시트를 열 수 있습니다. X 버튼을 누르면 전송이 다시 성공할 때까지 해당 창의 카드가 닫힙니다. 크루 멤버의 창에서는 아직 신고 기능이 제공되지 않으므로 위의 단계를 사용하십시오.
휴대폰에서 시작한 업데이트가 staging 상태로 유지됩니다. 1.6.0 이하 버전의 Collie에서는 휴대폰에서 업데이트를 탭했을 때 새 버전을 준비(stage)한 후 멈출 수 있었습니다. 교체를 수행하는 runner가 시작되지 않았고, 서비스는 이전 버전을 계속 제공했으며, 실행 기록은 잠금을 유지한 채 staging 상태로 머물렀습니다. 세 가지 현상이 함께 나타나면 이 문제입니다. collie update --status가 staging(또는 10분이 지난 경우 interrupted — the updater is gone)을 보고하고, 새 릴리스의 버전 디렉터리가 versions/ 아래에 존재하며, ~/.config/collie/collie.log의 runner 로그가 0바이트입니다. 동일한 머신의 셸에서 입력한 collie update는 항상 작동했는데, 이는 같은 결함이 반대편에서 나타난 결과입니다. 이 문제는 다음 릴리스부터 수정되었습니다. 이제 핸드오프 시 사용자 관리자가 runner를 확인할 때까지 대기하며, 거부된 핸드오프는 관리자 자체의 이유와 함께 실패로 보고됩니다.
이미 멈춘 머신을 정리하려면 10분 동안 아무것도 하지 마십시오. 업데이터가 사라진 실행은 마지막 전환 후 10분이 지나면 재시도 차단을 중단하므로 다음 탭이 진행됩니다. 지금 바로 정리하려면 기록, 잠금 및 staging 진행률 파일을 삭제한 다음 --status의 출력을 확인하십시오.
collie update --status # note the pid it names
ps -p <pid> -o command= # empty output: the updater really is gone
rm -f ~/.local/state/collie/update.json ~/.local/state/collie/update.lock
rm -f ~/.local/state/collie/update-staging-*.log
collie update --status # "no update has run on this install yet"오래된 실행을 정리하는 명령은 없으며, 이 세 파일이 중단된 staging이 남긴 상태의 전부입니다. 접미사가 붙은 인스턴스는 이를 ~/.local/state/collie-<name>/에 대신 보관합니다. 업데이트가 실제로 실행 중일 때는 절대 삭제하지 마십시오. 먼저 pid를 확인하십시오. 잠금을 제거한 활성 업데이터는 보호 장치 없이 current를 전환하게 됩니다. versions/는 그대로 두십시오. 절반만 준비된 버전 디렉터리는 무해하며, 재시도 시 다시 빌드되고 보존 정리 작업에서 더 이상 필요하지 않은 항목을 제거합니다.
macOS에서 휴대전화 업데이트 시 Collie가 언로드된 상태로 남습니다. Mac에서 다음을 실행하십시오:
collie restartCollie 1.8.x 이하 버전에서는 휴대폰에서 업데이트를 탭했을 때 launchd agent가 중지된 후 다시 로드되지 않아, 휴대폰에서 서비스 연결이 끊기고 launchctl print gui/$(id -u)/herdr.collie에 아무것도 나타나지 않을 수 있었습니다. 러너가 agent의 프로세스 그룹을 공유했기 때문에 agent를 재시작하는 도중에 러너가 강제 종료되었습니다. collie restart 명령은 agent의 plist를 다시 작성하고 이를 로드합니다. 1.9.0부터는 bridge가 자체 프로세스 세션에서 러너를 시작합니다. 그 이후에도 휴대폰 업데이트로 인해 agent가 언로드된다면 같은 명령을 실행하고 #213에 내용을 남겨 주십시오.
macOS에서 collie start 명령이 완료되었지만 collie status에 "loaded, not running"으로 표시됩니다. launchd 작업이 로드되었으나 실행 중인 프로세스가 없어 로그가 비어 있습니다. 작업을 수동으로 시작하십시오:
launchctl kickstart gui/$(id -u)/herdr.collie
collie status접미사가 붙은 인스턴스는 고유한 레이블(예: herdr.collie-next)을 가집니다. 1.17.0 버전부터는 collie start 및 collie restart 명령이 이 단계를 대신 수행하며, 표시되는 프로세스가 없을 때 이 명령과 함께 경고를 출력합니다. 그 후에도 작업이 "loaded, not running" 상태로 유지된다면 collie logs 명령으로 로그를 확인한 다음 #213에 내용을 남겨 주십시오.
New 페이지에서 에이전트가 회색으로 비활성화되어 표시됩니다. 이름 뒤 대괄호 안에 사유가 표시됩니다. "not installed"는 로그인 셸이 사용하는 PATH에서 머신이 에이전트 명령을 찾지 못했음을 의미합니다. 해당 머신의 로그인 셸에서 bash -lc 'command -v claude'(또는 에이전트 자체 이름)을 실행하십시오. 아무것도 출력되지 않으면 해당 머신에 에이전트를 설치하거나, 셸의 로그인 파일에서 에이전트를 PATH에 추가하는 줄을 수정한 후 페이지를 다시 여십시오. crew에서는 선택한 머신을 확인하십시오. 각 member는 자체 디스크를 조회합니다. "this machine runs an older Collie"는 해당 member를 업데이트해야 함을 의미합니다(시스템에서 작업 시작하기). "needs Herdr" 및 머신 이름이 붙은 "only on"은 에이전트가 아니라 새 worktree 스위치에 해당합니다.
Start 실행 시 "There is no folder … on this machine" 또는 "could not confirm the start" 메시지가 표시됩니다. 첫 번째 오류는 시작을 실행하는 머신에 해당 폴더가 없어 아무것도 시작되지 않았음을 의미합니다. 앞에 /나 ~가 없는 이름은 홈 디렉터리 하위의 폴더이므로 projects은(는) ~/projects을(를) 의미합니다. 폴더를 생성하거나 Recent에서 선택하십시오. 두 번째 오류는 휴대폰이 응답을 수신하지 못했음을 의미합니다. 창이 이미 생성되어 있을 수 있으므로 먼저 대시보드를 확인하십시오. 다시 시도은(는) 동일한 요청을 전송하며 두 번째 창을 중복해서 열지 않습니다(휴대폰에서 에이전트 또는 셸 시작).
Walky talky
walky talky에는 6가지 주요 증상이 있습니다. 각 증상마다 원인을 보여주는 명령이 있습니다(Walky talky).
collie walky send에 "run this inside a pane, or send from the phone"이라고 표시됩니다. 명령이 일반 터미널 등 에이전트 창 외부에서 실행되었습니다. Collie는 창 자체의 환경에서 발신자를 식별합니다. 창이 없는 전송은 거부됩니다. 에이전트 창 내에서 명령을 실행하거나 모바일에서 전송하십시오. 에이전트 창에서는 collie walky who이(가) 창을 (you)(으)로 표시합니다. "no Collie bridge on this machine knows this pane" 오류는 다른 Collie가 해당 창을 소유하고 있음을 의미합니다. "no running Collie bridge answers" 오류는 브리지가 다운되었음을 의미하므로 collie status을(를) 실행하십시오.
메시지에 "held"로 표시되며 아직 입력되지 않았습니다. collie walky status <id> 실행 시 "held: draft present" 또는 "held: turn running"이 출력됩니다. 입력창에 초안이 남아 있거나 에이전트가 작업 중입니다. Collie는 입력창이 비워지거나 턴이 끝날 때까지 최대 60분 동안 메시지 입력을 대기합니다. 메시지를 다시 보내지 마십시오. 지금 입력되도록 하려면 해당 pane의 초안을 전송하거나 지우십시오. 이전 lead 환경에서는 "queued (outcome known on the lead)" 메시지 역시 대기를 의미합니다.
메시지가 inbox에 머물러 있으며 입력되지 않았습니다. collie walky status <id> 실행 시 "waiting in the inbox, not typed" 및 그 이유가 출력됩니다. "held past 60 minutes"는 60분의 보류 시간 내내 초안이 남아 있었거나, pane이 사용 중이었거나, 대화창이 열려 있었음을 의미합니다. Collie는 초안이나 대화창에 메시지를 입력하지 않습니다. "box not free"는 Collie가 빈 입력창을 찾지 못했음을 의미합니다. "pane busy"는 2분이 지난 후에도 이전 메시지가 해당 위치에 계속 입력 중이었음을 의미합니다. "pane replaced"는 메시지가 대기하는 동안 다른 세션이 pane을 차지했음을 의미합니다. 그 외에 "no terminal"과 "bridge restarted"가 있습니다. 해당 pane에서 collie walky inbox 명령을 실행하거나 모바일의 pane 메뉴에서 Messages를 여십시오. Collie는 메시지 입력을 재시도하지 않습니다.
collie walky send에 "not sent: pane replaced"라고 표시됩니다. 주소가 #k3f9과 같은 토큰으로 끝나며 지정된 pane이 닫혔습니다. 현재 다른 pane이 해당 pane id를 사용하고 있으므로 Collie는 메시지를 입력하지 않습니다. collie walky who 명령을 실행하고 새 주소로 전송하십시오. "not sent: sender gone" 응답도 원인이 동일합니다. 메시지를 보낸 pane이 닫혔거나 다른 pane이 해당 id를 차지한 상태입니다.
pane의 헤더에 "no log record on this machine"이 표시됩니다. 모바일이 화면 텍스트에서 walky talky 헤더를 발견했으나, 이 머신의 로그에는 해당 id를 가진 메시지가 없습니다. 누군가 직접 해당 줄을 입력했거나, 7일 또는 2,000줄이 지나 로그에서 삭제되었거나, 다른 Collie 인스턴스에 저장되어 있습니다. collie walky status <id> 명령을 실행하십시오. "no record of <id> on this machine"이 출력되면 이를 확인할 수 있습니다. crew 멤버의 pane인 경우 해당 멤버 머신에서 실행하십시오. 모바일이 읽은 로그는 해당 머신의 로그입니다. 해당 줄을 일반 텍스트로 취급하고, 필요한 경우 발신자에게 문의하십시오.
스킬이 오래되었습니다. collie doctor 실행 시 skill-walky-talky 행에서 경고가 발생하며 에이전트가 이전 가이드를 따릅니다. 인스트럭션 파일의 텍스트가 현재 빌드와 일치하지 않습니다. 어떤 harness가 이전 버전인지 확인하려면 collie skill status 명령을 실행하십시오. 스크립트에서 collie skill status --check 명령을 실행하면 복사본이 오래된 경우 아무것도 출력하지 않고 종료 코드 3을 반환합니다. collie skill install all 명령으로 이를 수정한 후 에이전트를 다시 시작하십시오. refused 표시가 있는 대상은 심볼릭 링크이거나 마커가 손상된 상태이므로 설치 시 절대 변경되지 않습니다.
Durable agent
연결한 durable agent는 자체 검증, 사유 및 케이스를 갖습니다. collie durable list 및 collie doctor부터 시작한 다음 Durable agent 문제 해결 문서를 확인하십시오.