forgeplan claim

forgeplan claim резервирует артефакт за конкретным агентом, чтобы другие агенты знали - туда не лезть. Команда пишет небольшой файл .forgeplan/claims/<id>.yaml с идентичностью агента и временем истечения (TTL - time-to-live, после этого клейм считается заброшенным и другой агент может взять артефакт). По умолчанию TTL - 30 минут, максимум - 24 часа.

Это рекомендательный лок, не жёсткий - никакая другая команда Forgeplan не откажет в работе из-за того, что что-то заклеймено. Соглашение такое: агенты сами проверяют forgeplan claims перед началом работы и уважают увиденное. Планировщик (forgeplan dispatch) клеймы учитывает и исключает заклейменные артефакты из своих планов.

Две гарантии безопасности:

• Двойного клейма не будет - если живой клейм уже держит другой агент, вызов завершится понятной ошибкой.
• Продление идемпотентно - тот же агент, повторно вызывающий claim на свой же артефакт, обновит срок истечения, никого не выгнав. Используйте для долгой работы, чтобы клейм не истёк.

Аналог forgeplan_claim на MCP-стороне.

Когда использовать

• Саб-агент получил корзину от forgeplan dispatch - клеймите артефакт перед редактированием файлов.
• Долгая работа (большой рефакторинг, multi-PR фича) - вызывайте claim каждые 20 минут или около того, чтобы продлевать срок до истечения.
• Оркестратор-скрипт хочет заклеймить от имени саб-агента, который не говорит по MCP - передайте --agent worker-1 явно.

Когда НЕ использовать

• Однопоточный workflow - гонки нет, клейм не нужен.
• Ожидаете жёсткий лок, который заблокирует другие команды - клеймы рекомендательные, агенты должны проверять их сами.
• Не подумав о TTL - дефолтные 30 минут защищают от заброшенных клеймов, которые блокируют воркспейс навсегда. Поднимайте TTL только если планируете продлевать до истечения.

Использование

forgeplan claim [OPTIONS] <ID>

Аргументы

  <ID>  Artifact ID to claim (e.g. PRD-057)

Опции

      --agent <AGENT>              Agent identity ("name/version"). Defaults to `cli/<version>`
      --ttl-minutes <TTL_MINUTES>  Time-to-live in minutes (default 30, max 1440 = 24h, min 1) [default: 30]
      --note <NOTE>                Optional free-form note surfaced by `forgeplan claims`
      --json                       Output as JSON for machine consumption
  -h, --help                       Print help
  -V, --version                    Print version

Примеры

Пример 1: Саб-агент клеймит с дефолтным TTL

forgeplan claim PRD-057 --note "implementing FR-003"

Резервирует PRD-057 на 30 минут под дефолтной идентичностью cli/<version>. Заметка появляется в forgeplan claims, чтобы оркестратор видел, чем занят каждый агент.

Пример 2: Оркестратор клеймит от имени агента

forgeplan claim RFC-012 --agent worker-2 --ttl-minutes 60

Полезно, когда оркестратор - это shell-скрипт, гоняющий саб-агентов, не говорящих напрямую по MCP. 60-минутный TTL даёт worker-2 больше времени до необходимости продления.

Пример 3: Продление существующего клейма

forgeplan claim PRD-057 --ttl-minutes 30

Тот же агент, повторно вызывающий claim на свой артефакт, продлевает срок истечения, ничего другого не меняя. Используйте на долгих рефакторингах, прежде чем TTL истечёт.

Место в рабочем процессе

Это шаг 2 multi-agent цикла: dispatch → claim → работа → release. После того как forgeplan dispatch раздал корзины, каждый саб-агент клеймит свой артефакт перед тем, как трогать файлы. Когда работа закончена (или агент упал), слот освобождается через forgeplan release - используйте --force на release, чтобы убрать клейм упавшего агента.

См. также

• forgeplan_claim - MCP-эквивалент
• forgeplan release - снять активный клейм
• forgeplan claims - список активных клеймов
• forgeplan dispatch - продуцирует план работы, который защищают клеймы