istok

Решение проблем

Найдите свой симптом, узнайте причину и исправьте её.

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

Первые проверки

На большинство вопросов отвечают три команды:

istok version          # установлен ли Istok и какая версия
istok project show     # относится ли эта директория к проекту
istok COMMAND --help   # какие флаги принимает ваша версия

Встроенная справка — главный источник истины для установленного бинарника. Если команда ведёт себя не так, как описано здесь, верьте --help и проверьте istok version.

Агент не видит инструменты Istok

Почему: агент не может запустить istok mcp. Чаще всего у редактора или десктопного приложения другой PATH, чем у терминала: в оболочке istok version работает, а у агента — нет.

Что делать:

  1. Проверьте MCP-команду в конфигурации агента: она должна запускать istok mcp.
  2. Убедитесь, что бинарник istok есть в PATH процесса агента, или укажите в конфигурации абсолютный путь.
  3. Перезапустите агента или перезагрузите его конфигурацию после изменения настроек MCP.
  4. Проверьте в статусе MCP у агента, что сервер Istok запустился.

Настройка для каждого агента описана в разделе Быстрый старт.

Агент не пользуется Istok

Почему: MCP лишь делает инструменты доступными. Когда ими пользоваться, агент узнаёт из своих инструкций. Без них он может игнорировать Istok или пользоваться им непоследовательно.

Что делать: добавьте рекомендованные инструкции из быстрого старта и убедитесь, что репозиторий зарегистрирован (см. следующий раздел). Фразы, которые возвращают агента к Istok, собраны в разделе Работа с агентом.

«Not registered» или Istok не находит проект

Почему: директория не входит ни в один зарегистрированный проект — или вы не в том репозитории, в котором себя считаете.

Что делать: проверьте, где вы находитесь и что зарегистрировано:

pwd
istok project list

Если репозитория нет в списке, попросите агента «зарегистрируй этот проект в Istok» или выполните istok init в репозитории. Затем проверьте результат командой istok project show.

Я перенёс или переименовал папку репозитория

Почему: проект привязан к пути. После переноса новый путь не зарегистрирован.

Что делать: привяжите существующий проект к новому пути вместо регистрации нового — так задачи и история останутся на месте:

cd ~/projects/acme-api
istok project rebind acme-api

Агент работает не в том проекте

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

Что делать: запускайте агента из нужной директории и проверьте оттуда istok project show. Не регистрируйте ещё один проект только ради того, чтобы заработала сессия.

CLI, агент и веб-интерфейс показывают разные данные

Почему: они работают с разными базами данных. Каждый процесс читает базу, указанную в --database или ISTOK_DATABASE, а если её нет — базу по умолчанию. Служба веб-интерфейса не видит окружение вашей оболочки.

Что делать: используйте везде одну и ту же базу. Если она у вас нестандартная, передайте её в MCP-команду агента и переустановите службу веб-интерфейса с ней:

istok ui service install --database /path/to/istok.db

Задача зависла в состоянии «в работе»

Почему: скорее всего, её запуск завис. Сессия агента закончилась, а запуск так и не завершился: сигналы активности (heartbeat) прекратились, но аренда ещё не истекла или с тех пор задачу никто не брал.

Что делать: посмотрите фильтр Stale в ленте запусков веб-интерфейса или выведите запуски задачи:

istok run list --task 12

Когда аренда истечёт, следующая попытка взять задачу автоматически закроет зависший запуск как abandoned. Чтобы освободить задачу сразу, прервите запуск в веб-интерфейсе или командой istok run abandon. См. Задачи и запуски.

Задачу не удаётся взять в работу

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

Что делать:

istok task show 12
istok task ready
istok run list --task 12

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

Задачу не взять из-за лимита контекста

Почему: контекст, который обязательно нужно доставить, — записи always и записи, запрошенные по ID, — не помещается в лимит контекста. Istok отказывает во взятии задачи, а не выбрасывает ваши правила молча. В ошибке перечислены нужные записи.

Что делать: найдите причину, исправьте её и проверьте результат перед новой попыткой:

istok context doctor
istok context update RECORD_ID --expected-revision REVISION --delivery ranked
istok context preview 12

Сократите или разделите слишком большие записи либо переведите необязательные записи always в режим ranked.

Задачу не взять: ошибка при подготовке кода

Почему: при взятии задачи Istok обновляет индекс кода и подбирает код ещё до создания запуска. Если подготовить пригодный индекс не удаётся, взятие задачи завершается ошибкой — запуск не стартует с устаревшим кодом.

Что делать:

istok index status
istok index rebuild
istok task claim 12

Исправляйте поиск по коду, а не обходите его. Флаг --without-retrieval вместе с --override-reason оставлен для исключительных случаев.

Результаты поиска неверные или устаревшие

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

Что делать: проверьте индекс и при необходимости пересоберите его:

istok index status
istok index rebuild

Если пересборка тоже не удалась, начните с вывода istok index status: по нему видно, какие файлы или какое состояние индекса вызывают проблему.

Граф в состоянии «degraded»

Почему: некоторые файлы не дали полной структурной информации. Поиск работает, но граф неполон. Граф строится только для Go, TypeScript и JavaScript.

Что делать: проверьте istok index status. Если граф вам нужен, а проблема не уходит, выполните istok index rebuild и проверьте снова.

Команда запуска отклоняет аренду

Почему: exec, validate, heartbeat и finish требуют текущую аренду запуска. При восстановлении аренда меняется, и старая перестаёт работать.

Что делать: узнайте текущее состояние командой istok run show RUN_ID и используйте текущую аренду. Если аренда потеряна, а вы тот же исполнитель, восстановите запуск и получите новую:

istok run recover RUN_ID --reason "Lost local lease token"

Если старая аренда ещё действует, добавьте --force. Восстановить запуск может только исполнитель, которому он принадлежит.

Операция отклонена из-за устаревшей ревизии

Почему: у задач, запусков, записей контекста и заметок знаний есть ревизии. Если объект изменился после того, как вы его прочитали, операция со старым --expected-revision отклоняется, а не перезаписывает более новое состояние.

Что делать: прочитайте объект заново (istok task show 12, istok run show RUN_ID, istok context show RECORD_ID) и повторите с последней ревизией. Со старой ревизией операция так и будет падать.

Проверка не проходит

Почему: проверка не пройдена. Это записывается, а не теряется.

Что делать: посмотрите вывод через istok run show RUN_ID или в веб-интерфейсе, исправьте проблему и снова запустите проверку в том же запуске. Новая задача не нужна. См. Проверки.

Запуск не удаётся завершить

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

Что делать: проверьте istok run show RUN_ID. Если ни одна проверка ещё не пройдена, запустите её, затем завершите запуск с актуальными значениями. Если автоматической проверки нет, завершите явно с --allow-unvalidated и --override-reason. См. istok run.

Хочу бросить попытку и начать заново

Почему: подход не сработал, но задача по-прежнему актуальна.

Что делать: прервите запуск. Задача останется открытой, а запуск — в её истории:

istok run abandon RUN_ID \
  --expected-revision REVISION \
  --reason "Restarting with a different approach"

Агенты могут это сделать только с MCP-профилем supervisor или admin.

Веб-интерфейс не открывается

Почему: обычно порт уже занят — часто другим istok ui или службой веб-интерфейса, которая уже его обслуживает.

Что делать: откройте http://127.0.0.1:7700 и проверьте, не запущен ли интерфейс. Если нет, запустите его на другом порту:

istok ui --port 7800

Если страница сообщает, что веб-интерфейс не собран, значит, бинарник собран из исходников без фронтенда. Установите официальный релиз или соберите через make install — эта команда сначала собирает фронтенд.

Служба веб-интерфейса останавливается после выхода из системы

Почему: на Linux systemd останавливает пользовательские службы, когда заканчивается ваша последняя сессия.

Что делать: включите lingering для своего пользователя:

loginctl enable-linger

На macOS агент launchd привязан к вашему сеансу: он останавливается при выходе из системы и запускается снова при входе.

Как сообщить о проблеме

Соберите небольшой набор диагностики:

istok version
istok project show
istok index status
istok task show TASK_ID
istok run show RUN_ID

Для проблем с MCP приложите конфигурацию MCP агента и укажите, может ли агент запустить сервер Istok. Прежде чем чем-то делиться публично, уберите секреты и закрытое содержимое проекта.