Target¶

Команды target — ежедневный вид одной пары проект–harness. Они читают. Они никогда не обновляют target, не снимают backup и не восстанавливают его.

Повседневное восстановление последнего рабочего сетапа — intent switch. Не набирайте install plan --action rollback, если вы не восстанавливаете остановившуюся операцию.

ai-stp task start --intent switch --idempotency-key switch-session-01 --json

Expert-чтения target ниже ничего не восстанавливают. target rollback называет предыдущую подтверждённую версию. Восстановление через install plan --action rollback — expert recovery. Повторная установка более ранней версии через action=update — не то же самое, что восстановление из backup.

Таблица команд¶

Команда	Mutability	Confirmation	Когда
`ai-stp target status`	`read`	`none`	ежедневное состояние одного проекта и harness
`ai-stp target diff`	`read`	`none`	что изменила бы установка выбранной версии
`ai-stp target backups`	`read`	`none`	копии provider, из которых эта пара может восстановиться
`ai-stp target rollback`	`read`	`none`	назвать точную предыдущую verified-версию

--json глобальный. Всегда передавайте его. Ни одна из этих команд не берёт --confirm и не берёт digest плана.

Status¶

Expert recovery:

ai-stp target status --project <project_id> --harness codex --json

--project — стабильный id паспорта проекта. --harness обязателен и один из antigravity, claude-code, codex, cursor, grok-build, opencode, pi.

Чтобы прочитать target как он есть сейчас, передайте provider:

ai-stp target status \
  --project <project_id> \
  --harness codex \
  --provider <exe> \
  --provider-manifest <path> \
  --protocol-version 3 \
  --target <dir> \
  --json

--provider-manifest необязателен: релиз, под которым эту пару последний раз проверяли, читается из журнала, когда названный исполняемый файл — его точные байты. Без подписанного релиза чтение спрашивает в v3. --unverified-provider читает через исполняемый файл, который не покрыт подписанным или attested-релизом. Изоляцию это не ослабляет.

--requires-env повторяемый. Каждое значение — дополнительная переменная в верхнем регистре, которая нужна этому target сверх паспорта сетапа. Никогда NAME=value. --catalog-version — новейшая известная версия, чтобы сообщить catalog drift. --target обязателен для протокола v2 и v3.

states — список, потому что пара может одновременно ждать установки и не хватать переменной. Значения: not_selected, pending_install, local_drift, catalog_drift, needs_configuration, installed.

Поля успеха: project_id, harness_id, states, selected_stable_id, selected_version, installed_stable_id, installed_version, observed_target_digest, verified_target_digest, missing_env, pending_authorization, shadowed_by, catalog_version.

Diff¶

Diff отвечает, что изменила бы установка выбранной версии. Ничего не меняет. Опции совпадают со status.

ai-stp target diff \
  --project <project_id> \
  --harness codex \
  --provider <exe> \
  --protocol-version 3 \
  --target <dir> \
  --json

Читайте изменения управляемых путей: modified, added, deleted, с expected_digest и observed_digest. unsafe в observed digest значит, что текущие байты не считаются content address.

Backups¶

ai-stp target backups --project <project_id> --harness codex --json

Без --provider ответ — собственная запись журнала. С --provider те же строки ещё говорят, какие копии всё ещё существуют и удерживаются — единственный способ увидеть копию, которую журнал всё ещё предлагает, а provider уже не имеет.

ai-stp target backups \
  --project <project_id> \
  --harness codex \
  --provider <exe> \
  --provider-manifest <path> \
  --protocol-version 3 \
  --target <dir> \
  --json

У каждой копии есть backup_ref, операция, которая её сняла, и версия сетапа, установленная в тот момент. Эта команда ничего не восстанавливает.

Expert recovery (остановившийся rollback):

ai-stp install plan \
  --action rollback \
  --backup-ref <exact> \
  --provider <exe> \
  --provider-manifest <path> \
  --protocol-version 3 \
  --target <dir> \
  --json
ai-stp install approve --operation <id> --plan-digest sha256:... --json
ai-stp install apply --operation <id> --provider <exe> --json

Rollback (только имя)¶

ai-stp target rollback --project <project_id> --harness codex --json

Только --project и --harness. Ответ называет setup_stable_id, setup_version, operation_id, verified_at, project_id, harness_id. Ничего не откатывает.

Три отличия, которые стоит держать в голове:

target rollback называет предыдущую подтверждённую версию и ничего не восстанавливает. Это ответ на «куда откатываться», а не «откатись».
Повторная установка более ранней версии через install plan --action update — не то же самое, что восстановление: bundle не содержит файлов, которые вы не устанавливали, а копия их сохраняет.
Восстановление возвращает target целиком. Один компонент восстановить нельзя, и такой запрос отклоняется.

Сетап — закреплённый состав, не папка с текущими файлами. Обновить один skill, отключить hook или поменять setting — уже новая версия сетапа.

Happy path¶

Ежедневно:

target status --project <id> --harness <id>
→ target diff --project <id> --harness <id>   # если states включает local_drift
→ task start --intent install --idempotency-key install-session-01 --json

После успешного apply:

target status --project <id> --harness <id>
→ states включает installed

Перед рискованным изменением:

task start --intent switch --idempotency-key switch-session-01 --json
→ target backups --project <id> --harness <id>
→ target rollback --project <id> --harness <id>   # имя, не restore

Именованные поля успеха¶

Команда	Какие поля читать
`status`	`states`, `selected_`, `installed_`, `missing_env`, `shadowed_by`
`diff`	у управляемого пути `code`, `expected_digest`, `observed_digest`
`backups`	`backup_ref`, флаг held, версия сетапа на копии
`rollback`	`setup_stable_id`, `setup_version`, `operation_id`, `verified_at`

Отказы¶

Что видно	Что это значит	Что делать
`AI_STP_VALIDATION_ERROR`	нет `--project` или `--harness`, или нет `--target` для v2/v3	добавить объявленные опции
`AI_STP_NOT_FOUND`	у этой пары ещё нет журнала	сначала select и install; пустой status — типизированная пустота, когда пара есть, а установлено ничего
`AI_STP_UNSUPPORTED_APPLY`	этот harness id не из закрытого набора	использовать поддерживаемый harness
считать `target rollback` восстановлением	он только называет версию	`install plan --action rollback --backup-ref`
просить восстановить один компонент	восстановление — весь target	отказ; соберите новый сетап
`NAME=value` в `--requires-env`	опция берёт только имя	передать имя переменной в верхнем регистре
удалять backup руками	восстановлению они ещё нужны	ждать, пока recover/resume не закончится

Работающий агент не меняет свой активный target на месте. Новый сетап проверяется отдельно; переключение — после этой проверки.

Связанные страницы¶

Флаги берутся из continuation argv¶

ai-stp task intents --json

Не дампьте help --agent как прелюдию. Флаги текущей задачи — в continuation argv.

Эта страница группирует команды target, чтобы человек их нашёл. Если страница и CLI расходятся, следуйте CLI.