istok run

istok run работает с запусками — отдельными попытками выполнить задачу. Агенты делают всё это через MCP; CLI нужен, чтобы посмотреть состояние, разобраться с проблемой или управлять запуском напрямую. Понятия описаны в разделах Задачи и запуски и Проверки.

Команды

ID запусков — канонические значения UUIDv7.

Список запусков

istok run list
istok run list --task 12
istok run list --status active --limit 20

Возможные статусы: active, succeeded, failed, blocked, cancelled и abandoned; --status можно повторять.

run list показывает только текущий проект. Запуски всех проектов, где идущие и зависшие запуски различаются, смотрите в ленте запусков веб-интерфейса.

Посмотреть запуск

istok run show RUN_ID

Показывает состояние запуска, аренду, ревизию, снимок контекста, выполнения, проверки и артефакты. Здесь удобно взять текущую аренду или ревизию перед следующей операцией. Веб-интерфейс показывает тот же запуск, а снимок контекста — в разделе What the agent saw.

Аренда

Командам, которые выполняют или меняют работу внутри активного запуска, нужна его текущая аренда:

istok run heartbeat RUN_ID --lease LEASE

Аренду выдаёт взятие задачи или восстановление запуска. Если она сменилась, используйте новую.

Сигнал активности

istok run heartbeat RUN_ID --lease LEASE

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

Выполнить команду

istok run exec RUN_ID --lease LEASE -- pnpm lint
istok run exec RUN_ID --lease LEASE -- \
  go test ./internal/orders -run TestGetOrder

Всё после -- — это команда и её аргументы. Команда и её вывод сохраняются вместе с запуском.

Проверить запуск

istok run validate RUN_ID --lease LEASE -- go test ./...
istok run validate RUN_ID --lease LEASE -- pnpm test

Результат становится доказательством проверки, на которое могут ссылаться finish и istok task done. --summary задаёт краткое описание проверки; без него описание строится из результата.

Опции exec и validate

istok run exec RUN_ID \
  --lease LEASE \
  --cwd packages/api \
  -- pnpm test

Управляемые команды получают от родительского процесса не всё окружение, а только переменные из разрешённого списка, плюс ISTOK_RUN_ID, ISTOK_EXECUTION_ID и ISTOK_PROJECT_ROOT. См. Настройка.

Используйте --allow-dangerous, только когда операции это действительно нужно; причина сохраняется:

istok run exec RUN_ID \
  --lease LEASE \
  --allow-dangerous \
  --override-reason "Required for the requested migration" \
  -- COMMAND

Артефакты

istok run artifact list RUN_ID
istok run artifact verify ARTIFACT_ID --run RUN_ID

Артефакты связывают с запуском файлы, которые он создал. Их содержимое лежит в хранилище артефактов Istok, вне базы данных.

Завершить запуск

istok run finish RUN_ID \
  --lease LEASE \
  --expected-revision REVISION \
  --status succeeded \
  --summary "Implemented and validated."

finish требует текущую аренду, ожидаемую ревизию, конечный статус (succeeded, failed, blocked или cancelled) и краткий итог. Чтобы завершить запуск как succeeded, нужна пройденная проверка и ни одного ещё работающего управляемого выполнения.

Если ни одна проверка не применима, завершите запуск без проверки явно:

istok run finish RUN_ID \
  --lease LEASE \
  --expected-revision REVISION \
  --status succeeded \
  --summary "Documentation-only change." \
  --allow-unvalidated \
  --override-reason "No automated checks apply to this change"

Восстановить запуск

istok run recover RUN_ID --reason "Continuing interrupted work"

Восстановление выдаёт тому же запуску новую аренду. Оно работает только для исполнителя, которому принадлежит запуск; дальше используйте возвращённую аренду.

--force заменяет собственную аренду текущего исполнителя ещё до её истечения, например если токен потерян:

istok run recover RUN_ID \
  --force \
  --reason "Replacing stale local session"

Прервать запуск

istok run abandon RUN_ID \
  --expected-revision REVISION \
  --reason "Implementation approach needs to be restarted"

Прерывание завершает попытку, оставляет её в истории со статусом abandoned и оставляет задачу открытой для нового взятия. Аренда не нужна, так что это работает и для запуска, чей агент уже пропал.

Команда CLI работает с любым активным запуском, поэтому сначала проверьте через istok run show, что над ним никто не работает. Веб-интерфейс прерывает только зависшие запуски, а MCP-инструмент run_abandon доступен только в профилях supervisor и admin.

Запись работы, сделанной вне Istok

exec и validate запускают команды сами. Если команда выполнялась в другом месте, запишите её:

istok run execution start RUN_ID --lease LEASE -- COMMAND
istok run execution finish EXECUTION_ID --run RUN_ID --expected-revision REVISION --status succeeded --exit-code 0
istok run validation record EXECUTION_ID --run RUN_ID --source attested --status passed --command "COMMAND" --summary "Checked manually"

Эти команды не запускают процесс. execution finish также принимает --duration-ms, --signal и --timed-out; validation record — --exit-code и --duration-ms. У проверки, записанной так, источник attested: её всегда можно отличить от проверок, которые Istok получил из команды, запущенной им самим.

Ревизии

finish, abandon и execution finish принимают --expected-revision. Если запуск или выполнение изменились с момента чтения, команда завершается ошибкой, а не перезаписывает более новое состояние. Выполните istok run show и повторите с текущей ревизией.

Вывод JSON

JSON-результаты запусков в CLI и MCP используют "schema_version": "2". См. Вывод JSON.

Справка

istok run exec --help
istok run validate --help
istok run finish --help
istok run recover --help
istok run abandon --help