Устранение неполадок

Начните с сохранения свидетельств: текущей идентичности сборки, безопасного текста ошибки, затронутой сессии или рабочего процесса, состояния ёмкости, последних журналов и статуса Git. Не выполняйте очистку, удаление или слепые повторы, пока не выясните, не завершилась ли уже устойчивая операция.

Web UI не запускается

Проверки: запустите сервер на переднем плане, вызовите curl -fsS http://127.0.0.1:9889/health, подтвердите, что порт слушает на loopback, и проверьте Settings → About, если оно доступно.

Решение: исправьте сообщённую ошибку зависимости/конфигурации или конфликт порта. Если health работает, а статические файлы — нет, проверьте кандидат и убедитесь, что Python-код и упакованные Web-ресурсы принадлежат одной сборке.

Браузер на другой машине не может подключиться

Это ожидаемо, когда ThreadCells правильно слушает на loopback. Не меняйте его на публичную привязку. Используйте SSH-туннель или аутентифицированный прокси из Удалённого доступа.

Провайдер показывает, что CLI не установлен

Проверки: сравните Настройки → Провайдеры с формой запуска агента, затем запустите command -v PROVIDER_COMMAND от имени runtime-пользователя ThreadCells.

Решение: установите канонический CLI провайдера для этой учётной записи, исправьте её служебный PATH или выберите другого готового провайдера. Одна лишь регистрация адаптера не означает установку.

Провайдер установлен, но не аутентифицирован

Проверки: запустите поддерживаемую команду статуса аутентификации провайдера от имени runtime-пользователя.

Решение: завершите нативную процедуру входа провайдера. ThreadCells не копирует учётные данные другого пользователя и не выполняет вход во время preflight.

Провайдер сообщает, что готовность не подтверждена

Команда существует, но не может предоставить безопасную неинтерактивную информацию о состоянии аутентификации. Проверьте её версию и выполните небольшую нативную проверку. Запуск может оставаться доступным; проверьте, не появляется ли в полученном терминале запрос входа провайдера.

Агент не запускается

Проверки: готовность провайдера, итоговый preview выбранного профиля, путь/права проекта, ёмкость резидентных процессов, выполнений провайдеров и рабочих контекстов, доступность tmux и вывод запуска терминала.

Решение: исправьте первое неудачное условие допуска или предварительное требование провайдера. Не запускайте повторно дубликаты, пока первая сессия ещё запускается.

Ёмкость исчерпана

Откройте Orchestration Capacity и определите точную заполненную категорию. Безопасно выведите из эксплуатации завершённую работу или дождитесь соответствующей задачи провайдера/тяжёлой задачи. Повышайте только этот лимит, когда у хоста и квоты есть измеренный запас.

Недоступен слот тяжёлого выполнения

Слот тяжёлых операций занят сборкой, browser test, сканированием или задачей восстановления. Дождитесь его или исследуйте устаревшую lease через каноническое состояние. Не запускайте дорогостоящую команду вне допуска только ради обхода очереди.

Рабочий процесс ожидает владельца

Прочитайте причину ворот. Предоставляйте запрошенное решение только если это подлинная граница публикации, доверия, разрушительного действия, стоимости или семантики продукта. Обычный финальный ответ провайдера должен оставлять подходящую автономную работу открытой; сообщите об автоматическом закрытии как о дефекте рабочего процесса.

Результат не включён

Подтвердите, что дочерний агент записал устойчивый результат и он был доставлен нужному родителю. Родитель должен прочитать/использовать неизменяемый результат, а затем подтвердить включение. Воспроизведение после перезапуска может снова доставить неподтверждённый результат; не применяйте его дважды.

Новый ввод владельца остаётся в очереди за закрытым рабочим процессом

Один раз перезапустите поддерживаемый runtime и проверьте точные идентичности рабочего процесса и Inbox. Текущие сборки сверяют ожидающую обычную транспортировку Inbox, чей привязанный рабочий процесс уже не открыт, затем позволяют продолжить более новый открытый ход владельца. Не перепривязывайте и не редактируйте строку Inbox вручную; сохраните базу данных и сообщите о дефекте, если устаревшая транспортировка остаётся ожидающей или какая-либо нагрузка пересекает идентичность рабочего процесса.

Авторизация оператора не настроена

Подтвердите, что THREADCELLS_OPERATOR_VERIFIER_FILE достигает реального процесса сервера, и перезапустите его. Если конфигурация недопустима, проверьте schema, абсолютный/канонический путь, владельца/режим файла, читаемость и каждый родительский каталог. Учётная запись службы не должна владеть verifier или иметь возможность заменить его.

Правильный секрет оператора не подходит

Подтвердите, что сервер загрузил тот же verifier, который сгенерировал CLI. Минимальная длина — ровно пять символов. Проверьте старый процесс сервера или недавно заменённый verifier; не записывайте введённый секрет в журнал.

Telegram не настроен или тест не проходит

Откройте Settings → Telegram после разблокировки изменений оператора. Not configured требует действительных токена бота и ID чата. Invalid означает, что приватный файл токена не прошёл проверки владельца, обычного файла или режима. Успешная проверка подключения подтверждает учётные данные бота; отправьте явное тестовое уведомление, чтобы проверить чат и необязательный ID темы. Если любое действие не проходит, проверьте исходящие HTTPS/DNS. Безопасные ошибки намеренно не содержат тел Telegram response и токена. См. Уведомления Telegram.

Statistics не содержит текущую сессию

Обновите использование/статус, проверьте, поддерживает ли провайдер телеметрию, и подтвердите, что его устойчивые свидетельства развертывания остаются читаемыми. Для подсчёта сессии не нужно удалять. Отсутствующие поля провайдера должны показывать Not reported, а не ноль.

Итог Statistics кажется продублированным

Сравните глобальные измерения, измерения сессии и терминала и сохраните базу данных. Накопительные снимки провайдера должны обновлять одну стабильную контрольную точку при опросе/перезапуске/воспроизведении. Не удаляйте строки вручную до диагностики.

Не совпадают Docs и идентичность сборки

Settings → About, нижний колонтитул Docs, манифест кандидата и ревизия статических ресурсов должны совпадать. Пересоберите и проверьте один неизменяемый кандидат; не объединяйте Web-вывод одного checkout с Python-кодом другого.

Давление на диск или Обслуживание не может освободить место

Проверьте dry-run план обслуживания. Защищённые, активные, неизвестные элементы, резервные копии, текущие релизы и релизы восстановления намеренно сохраняются. Устраните сообщённую ссылку/владельца или безопасно расширьте диск; никогда не удаляйте рекурсивно корень runtime.

Для максимального доказанно безопасного освобождения места проверьте отдельный preview Full Cleanup. Выполнение остаётся заблокированным, пока не подтверждён простой каждого агента либо активны выполнение провайдера, тяжёлая операция, поставленное в очередь изменение или runtime-операция. Не закрывайте агентов в состоянии «Готов» и не ослабляйте этот gate: их состояние продолжения остаётся защищённым. Full Cleanup удаляет все доказанно неактивные локальные релизы, поэтому подтвердите приемлемость потери локального отката. Защищённые неоднозначные инструменты, резервные копии, полномочия над исходниками, dirty или unpublished worktree и неизвестные пути — ожидаемые записи отчёта, а не основания удалить их вручную.

Full Output сообщает, что вывод очищен

Исторический агент в состоянии «Завершён» может остаться в SQLite после того, как Full Cleanup удалит его старый долговременный журнал. Это корректное состояние с сохранёнными метаданными: Sessions и Agents остаются работоспособными, а Full Output сообщает DURABLE_OUTPUT_UNAVAILABLE. Вывод текущих агентов и агентов в состоянии «Готов» защищён. Если исторический текст необходим, восстановите его из сохранённой резервной копии; не фабрикуйте и не присоединяйте другой журнал.

Терминал браузера не переподключается после перезапуска

Один раз обновите страницу, подтвердите, что сервер и сессия tmux исправны, и проверьте WebSocket-подключение браузера через любой обратный прокси. Убедитесь, что Caddy или другой прокси не удаляет заголовки upgrade. Установленный PWA не кэширует состояние терминала или WebSocket.

Всё ещё не получается

Сохраните минимальные воспроизводимые свидетельства и выполните сфокусированные проверки компонента до широких наборов. В отчёты об issue включайте только безопасные для публикации пути и сообщения. Ожидания к отчёту см. в Contributing.