Dépannage — pièges courants et comment récupérer

Si vous exécutez brainclaw en production, vous rencontrerez éventuellement l’un de ces problèmes. Chacun a un chemin de récupération spécifique — aucun ne nécessite de supprimer .brainclaw/ et de recommencer.

”Un agent a laissé un claim actif et est parti”

Symptôme : bclaw_find entity=claim filter={status: "active"} affiche un claim ouvert depuis des heures ; aucun événement agent_run récent ; le worktree existe toujours.

Récupération :

# Inspecter ce qui se passait
brainclaw doctor --dispatch       # affiche les claims périmés, les agent_runs orphelins

# Libérer le claim (vous devenez l'acteur dans le journal d'audit ;
# en 1.10, l'outrepassement de propriété est automatique pour les appelants trusted+ — aucun flag requis)
brainclaw release-claim <claim_id>
# Optionnel : faire passer le plan lié dans le même appel :
brainclaw release-claim <claim_id> --plan-status done
# ou via MCP :
bclaw_release_claim id=<claim_id>

Le handoff qui aurait dû être rédigé est manquant — capturez ce que vous savez du travail via brainclaw handoff (le CLI) afin que le prochain agent puisse tout de même récupérer le contexte.

”J’ai envoyé un travail et rien ne s’est passé”

Symptôme : bclaw_coordinate intent=assign targetAgents=[...] task="..." a retourné ok, mais l’agent cible n’a jamais récupéré le dossier.

Diagnostiquer dans cet ordre :

1. Le message est-il arrivé ? bclaw_read_inbox depuis l’identité de l’agent cible, ou bclaw_get_thread thread_id=<id> si vous en avez un. Si rien — vérifiez que le nom de l’agent cible correspond à l’identité enregistrée (bclaw_find entity=agent_run pour voir ce que brainclaw pense que sont les agents).
2. Le auto-spawn était-il activé ? Par défaut, il est activé, mais le dispatch inter-projets (avec project=…) le désactive de force. Vérifiez FacadeResponse.warnings pour auto-spawn disabled. Si oui, l’agent cible récupérera le dossier la prochaine fois qu’il exécutera bclaw_work — c’est le modèle de la boîte de réception et c’est intentionnel.
3. Le CLI de l’agent cible est-il dans le PATH ? validateAgentForDispatch rejette avec binary_missing si l’invoke_binary de l’agent (par exemple, codex, claude, cline) n’est pas dans le PATH. Visible dans le tableau des avertissements de dispatch.
4. La session de l’agent cible a-t-elle réellement démarré ? bclaw_find entity=agent_run filter={status: "launching"} — si l’agent_run est bloqué sur launching, le spawn a eu lieu mais l’agent n’a jamais atteint la poignée de main. Vérifiez brainclaw doctor --dispatch pour le résultat du réconciliateur de lancement périmé.

”bclaw_context retourne une mémoire vide / périmée”

Symptôme : une fonctionnalité sur laquelle vous travaillez présente des traps connus, mais bclaw_context kind=memory path="..." ne retourne rien de pertinent.

Causes possibles :

• Filtrage de provenance — par défaut, bclaw_find et le contexte mémoire excluent les enregistrements provenance.kind="legacy" et les enregistrements auto_reflect avec une confiance inférieure à 0,6. Passez filter={includeLegacy: true, minAutoReflectConfidence: 0.3} pour élargir.
• Désaccord de chemin de portée — le classeur mémoire évalue les éléments par chevauchement de chemin. path="src/auth/" correspond aux éléments étiquetés avec auth ou src/auth/..., pas aux éléments étiquetés avec authentication. Essayez bclaw_search query="authentication" pour les trouver par texte intégral.
• Lectures inter-projets — si le piège se trouve dans un projet lié, passez project=<name> pour lire son store. Sans ce paramètre, l’appel ne touche que le projet actuel.

”La fusion a effacé mon node_modules”

Résolu depuis pln#498 dans v1.5.0 — detachWorktreeJunctions s’exécute avant git worktree remove sur Windows, de sorte que le rm récursif de git ne peut pas suivre la jonction node_modules jusqu’au dépôt principal. Si vous voyez cela sur v1.4.x ou antérieur, mettez à niveau.

”trp#36 — Plantage de l’adaptateur Cloudflare après la construction”

Résolu depuis v1.5.3 côté site : scripts/build.mjs reconnaît le plantage connu de l’adaptateur Cloudflare après la construction, accepte la sortie non nulle et émet le sitemap manuellement via scripts/emit-sitemap.mjs. Le HTML est intact ; le bundle worker reste cassé jusqu’à la sortie de la mise à niveau Astro 6 + cloudflare 13 (investigation Linux/macOS en cours). Détails complets : trp#36 dans la mémoire du projet.

”Je ne trouve pas d’agent dans le registre”

Symptôme : bclaw_create entity=plan data={author: "claude-code"} fonctionne, mais bclaw_coordinate intent=assign targetAgents=[claude-code] affiche unknown_profile.

Cause : profil d’agent (descripteur de capacité intégré) ≠ identité d’agent enregistrée (locale au projet). Le validateur de dispatch utilise les profils. Correction :

brainclaw register-agent claude-code --kind agent
brainclaw enable-agent claude-code      # écrit le fichier d'instruction natif de l'agent

Agents blancs pour le dispatch : claude-code, codex, github-copilot. Les autres noms (gemini, antigravity, sonnet, opus) sont interdits selon la politique du projet.

”J’ai perdu la trace de qui travaille sur quoi”

bclaw_context kind=board                 # claims actifs, affectations, plans à travers l'espace de travail
bclaw_context kind=board_summary         # seuls des comptes légers
brainclaw doctor                         # vérification de l'état + candidats de réparation
brainclaw stale list                     # plans/pièges/transferts/candidats qui semblent périmés

bclaw_context kind=delta since=<prior_session_id> est ce qui se rapproche le plus de « ce qui a changé depuis ma dernière vérification ».

En cas de doute — lire le journal d’audit

Toute mutation d’état est écrite dans .brainclaw/audit.log (JSONL). C’est la source de vérité de « ce qui s’est réellement passé, qui l’a fait et quand ». Suivez-le avec tail -f .brainclaw/audit.log pendant que vous reproduisez ; l’entrée juste avant la défaillance est généralement le coupable.