Claims et worktrees — agents parallèles sans roulette de fusion

Un claim est un verrou consultatif sur un scope (glob de chemin, répertoire, id de plan) qui indique aux autres agents : « Je travaille ici, restez éloignés ». Lorsque le claim est créé, brainclaw crée automatiquement un worktree Git isolé sous ~/.brainclaw/worktrees/<project-hash>/<branch>/ afin que les modifications de l’agent n’entrent jamais en conflit avec le worktree d’un autre agent.

Le flux

# Agent A claim le scope auth
bclaw_work intent=execute scope="src/auth/"
# → claim clm_a créé, worktree à ~/.brainclaw/worktrees/<hash>/feat_src-auth/

# Agent B essaie de claim un scope chevauchant
bclaw_work intent=execute scope="src/auth/middleware.ts"
# → conflit : l'agent B voit le claim de l'agent A avant toute modification

Lorsque le travail est terminé :

# Agent A relâche avec la mise à jour du statut du plan
bclaw_release_claim id=clm_a planStatus=done
# → handoff écrit, worktree nettoyé, plan transitionné

Pourquoi des worktrees, pas des branches

Une branche permet à deux agents de modifier le même worktree séquentiellement. Un worktree donne à chaque agent son propre worktree — ils peuvent travailler en parallèle, même sur des branches qui se chevauchent, sans empiéter sur l’npm install ou les node_modules de l’autre.

brainclaw worktree clean élague les branches fusionnées. brainclaw worktree merge <branch> gère la fusion avec la restauration automatique de l’état du worktree principal.

Conflits de claims — quoi faire

Lorsque deux agents posent un claim sur un scope qui se chevauche, le deuxième appel renvoie un avertissement scope_already_claimed avec l’id et l’agent du claim existant. Vous avez trois options, par ordre de préférence :

# 1. Rerouter — relâcher le claim existant et réassigner au nouvel agent.
#    Utilisez ceci lorsque l'agent original est bloqué ou que vous souhaitez une nouvelle tentative.
bclaw_coordinate intent=reroute scope="src/auth/" targetAgents=[codex] task="..."

# 2. Attendre — l'agent original est en cours. Lisez son handoff ou son statut d'assignation :
bclaw_find entity=assignment filter={agent: "claude-code", status: "offered"}
bclaw_find entity=agent_run filter={status: "running"}
# Reprenez le travail après que `bclaw_release_claim` ait été exécuté.

# 3. Force-release — l'agent a abandonné sans relâcher. Dernier recours, auditez l'action.
brainclaw release-claim <claim_id> --force --reason "abandoned session"

bclaw_coordinate intent=reroute est le chemin le plus propre car il fait passer le cycle de vie de l’assignation correctement. Le force-release laisse une lacune dans la chaîne d’audit — ne l’utiliser que lorsque l’agent d’origine a réellement disparu.

« Mon worktree a été effacé après une fusion »

Résolu depuis la v1.5.0 (pln#498) — detachWorktreeJunctions s’exécute avant git worktree remove sous Windows afin que le rm récursif de git ne puisse pas suivre la jonction node_modules jusqu’au dépôt principal. Si vous voyez cela sur la v1.4.x ou une version antérieure, mettez à jour.

Ce qui ne va pas sans claims

Sans claims, deux agents prennent la même tâche en parallèle, modifient tous les deux les mêmes fichiers, exécutent tous les deux leurs tests dans le même node_modules, et le deuxième à commiter découvre le conflit au moment de la fusion. Un côté est écarté — gaspillage de calcul et de tokens.

Consultez parallel feature work pour le pattern complet en contexte, ou le guide de dépannage pour la récupération après des claims périmés.