brainclaw 1.23.0 → 1.25.0

package/dist/core/worktree.js

@@ -7,6 +7,7 @@ import yaml from 'yaml';
 import { logger } from './logger.js';
 import { loadConfig } from './config.js';
 import { parsePorcelainZ, isSystemDirtyPath } from './dirty-scope.js';
+import { entityRecordDirs } from './io.js';
 /** Normalizes a path for use in git CLI arguments (forward slashes on Windows). */
 function gitPath(p) {
     return p.replace(/\\/g, '/');
@@ -1548,6 +1549,68 @@ export function probeLocalBranch(mainWorktreePath, branchName) {
 export function isGitRepo(cwd) {
     return runGit(['rev-parse', '--is-inside-work-tree'], cwd).ok;
 }
+/**
+ * Comparison key for worktree paths: PHYSICAL identity when the path exists
+ * (realpath expands Windows 8.3 short names — `RUNNER~1` and `runneradmin`
+ * are the same directory but different strings, and git always reports the
+ * long form while a claim may carry the short one), else plain resolution.
+ * Forward slashes, case-folded on win32.
+ */
+function worktreePathKey(p) {
+    let resolved;
+    try {
+        resolved = fs.realpathSync.native(p);
+    }
+    catch {
+        resolved = path.resolve(p);
+    }
+    resolved = resolved.replace(/\\/g, '/').replace(/\/+$/, '');
+    return process.platform === 'win32' ? resolved.toLowerCase() : resolved;
+}
+/**
+ * Worktree paths referenced by an ACTIVE, non-expired claim — the set the GC
+ * must never touch.
+ *
+ * Read directly from the claims record dirs (both layouts, pln#649) instead of
+ * claims.ts: claims.ts imports worktree.ts, so the dependency can only point
+ * this way. The parse is deliberately lenient — an unreadable claim simply does
+ * not protect anything; it never blocks the GC of OTHER worktrees.
+ *
+ * Scope note: dispatch claims are project-local, so the project store is the
+ * right authority here; workspace-level claims (cross-project) never carry a
+ * lane worktree_path.
+ */
+function activeClaimWorktreePaths(cwd) {
+    const out = new Set();
+    const now = new Date();
+    for (const dir of entityRecordDirs('claims', cwd)) {
+        let files;
+        try {
+            files = fs.readdirSync(dir).filter((f) => f.endsWith('.json'));
+        }
+        catch {
+            continue;
+        }
+        for (const f of files) {
+            try {
+                const claim = JSON.parse(fs.readFileSync(path.join(dir, f), 'utf-8'));
+                if (claim.status !== 'active')
+                    continue;
+                if (typeof claim.worktree_path !== 'string' || !claim.worktree_path)
+                    continue;
+                // Mirror isClaimExpired: a zombie claim past its expiry must not make a
+                // worktree un-GC-able forever.
+                if (claim.expires_at && new Date(claim.expires_at) < now)
+                    continue;
+                out.add(worktreePathKey(claim.worktree_path));
+            }
+            catch {
+                /* lenient by design — see above */
+            }
+        }
+    }
+    return out;
+}
 /**
  * Removes worktrees whose branch has been fully merged into the current branch
  * (typically master/main after a merge). Also removes brainclaw-managed
@@ -1561,6 +1624,16 @@ export function isGitRepo(cwd) {
  *   - content (`git cherry HEAD <branch>`, patch-id): catches squash merges,
  *     which is GitHub's default merge strategy on this repo and previously left
  *     every squashed lane un-GC-able forever.
+ *
+ * ACTIVE-CLAIM GATE (incident 2026-08-10): a freshly-dispatched lane worktree
+ * has no commits of its own — its branch IS an ancestor of HEAD, so both merged
+ * probes say "merged" — and before the agent's first write it has no uncommitted
+ * changes either. Both historical gates therefore pass during a lane's startup
+ * window, and the post-merge hook destroyed a live codex lane 7 minutes after
+ * spawn (worktree emptied under the running agent). The coordination store is
+ * the authority on liveness: a worktree referenced by an active claim is
+ * untouchable — merged or not, clean or not, force or not. The escape hatch is
+ * releasing the claim, never bypassing it.
  */
 export function cleanMergedWorktrees(mainWorktreePath, options = {}) {
     const result = { removed: [], skipped: [], pruned: false };
@@ -1580,9 +1653,16 @@ export function cleanMergedWorktrees(mainWorktreePath, options = {}) {
             .filter(Boolean)
         : []);
     const worktrees = listWorktrees(mainWorktreePath);
+    const protectedPaths = activeClaimWorktreePaths(mainWorktreePath);
     for (const wt of worktrees) {
         if (wt.is_main)
             continue;
+        // Active-claim gate — see the function doc. Checked BEFORE the merged
+        // probes and BEFORE `force`: a live dispatched lane is never GC-able.
+        if (protectedPaths.has(worktreePathKey(wt.path))) {
+            result.skipped.push({ path: wt.path, reason: 'active claim' });
+            continue;
+        }
         // trp#926 — a lane's branch is "merged" if EITHER git says its commits are
         // ancestors of HEAD (fast-forward / merge-commit) OR every commit's patch
         // is already on HEAD (squash-merge, catching GitHub's default strategy).
@@ -1621,7 +1701,7 @@ export function cleanMergedWorktrees(mainWorktreePath, options = {}) {
         }
     }
     // Clean orphan brainclaw worktree directories (no matching git worktree)
-    cleanOrphanWorktreeDirs(mainWorktreePath, worktrees, result, options.dryRun);
+    cleanOrphanWorktreeDirs(mainWorktreePath, worktrees, result, options.dryRun, protectedPaths);
     return result;
 }
 /** A worker whose heartbeat file was touched within this window looks alive. */
@@ -1722,7 +1802,7 @@ export function gcWorktreeIfHarvested(mainWorktreePath, worktreePath, options =
  * Removes brainclaw-managed worktree directories under ~/.brainclaw/worktrees/
  * that no longer have a corresponding git worktree entry.
  */
-function cleanOrphanWorktreeDirs(mainWorktreePath, activeWorktrees, result, dryRun) {
+function cleanOrphanWorktreeDirs(mainWorktreePath, activeWorktrees, result, dryRun, protectedPaths = new Set()) {
     const base = worktreesBaseDir(mainWorktreePath);
     if (!fs.existsSync(base))
         return;
@@ -1740,6 +1820,13 @@ function cleanOrphanWorktreeDirs(mainWorktreePath, activeWorktrees, result, dryR
         const dirPath = path.resolve(path.join(base, entry.name));
         if (activePaths.has(dirPath))
             continue;
+        // Active-claim gate: a dir whose git admin entry vanished can still host a
+        // LIVE agent (the 2026-08-10 incident left exactly this state behind). If a
+        // claim still points here, it is not debris.
+        if (protectedPaths.has(worktreePathKey(dirPath))) {
+            result.skipped.push({ path: dirPath, reason: 'active claim' });
+            continue;
+        }
         // This directory is not referenced by any git worktree — it's orphaned
         if (dryRun) {
             result.removed.push(dirPath);

package/dist/facts.js

@@ -1,11 +1,11 @@
 // Generated by scripts/emit-site-facts.mjs at build time. Do not edit manually.
-// Source: brainclaw v1.23.0 on 2026-08-09T01:18:58.355Z
+// Source: brainclaw v1.25.0 on 2026-08-10T23:31:26.947Z
 export const FACTS = {
-  "version": "1.23.0",
-  "generated_at": "2026-08-09T01:18:58.355Z",
+  "version": "1.25.0",
+  "generated_at": "2026-08-10T23:31:26.947Z",
   "tools": {
-    "count": 67,
-    "published_count": 65,
+    "count": 70,
+    "published_count": 68,
     "names": [
       "bclaw_bootstrap",
       "bclaw_release_notes",
@@ -34,6 +34,9 @@ export const FACTS = {
       "bclaw_code_status",
       "bclaw_code_find",
       "bclaw_code_brief",
+      "bclaw_code_impact",
+      "bclaw_code_export",
+      "bclaw_code_outline",
       "bclaw_code_refresh",
       "bclaw_dispatch",
       "bclaw_send_message",
@@ -474,7 +477,7 @@ export const FACTS = {
   },
   "bench": {
     "schema": "brainclaw.bench.v1",
-    "generated_at": "2026-08-09T01:18:56.213Z",
+    "generated_at": "2026-08-10T23:31:25.464Z",
     "node_version": "v24.18.0",
     "platform": "linux-x64",
     "repeats": 3,
@@ -483,7 +486,7 @@ export const FACTS = {
         "name": "cold_onboard",
         "volume": "empty",
         "description": "fresh machine → init → first useful context. Baseline for time-to-first-value.",
-        "duration_ms_median": 77,
+        "duration_ms_median": 59,
         "payload_chars_median": 1640,
         "payload_tokens_est_median": 410
       },
@@ -491,15 +494,15 @@ export const FACTS = {
         "name": "warm_work",
         "volume": "medium",
         "description": "bclaw_work consult over a real-shaped store (~200 plans / 500 handoffs / 450 claims).",
-        "duration_ms_median": 131,
-        "payload_chars_median": 2626,
-        "payload_tokens_est_median": 657
+        "duration_ms_median": 88,
+        "payload_chars_median": 2625,
+        "payload_tokens_est_median": 656
       },
       {
         "name": "first_edit",
         "volume": "medium",
         "description": "code_find + code_brief on the fresh-agent path (missing index, first touch).",
-        "duration_ms_median": 14,
+        "duration_ms_median": 10,
         "payload_chars_median": 499,
         "payload_tokens_est_median": 125
       }

package/dist/facts.json

@@ -1,9 +1,9 @@
 {
-  "version": "1.23.0",
-  "generated_at": "2026-08-09T01:18:58.355Z",
+  "version": "1.25.0",
+  "generated_at": "2026-08-10T23:31:26.947Z",
   "tools": {
-    "count": 67,
-    "published_count": 65,
+    "count": 70,
+    "published_count": 68,
     "names": [
       "bclaw_bootstrap",
       "bclaw_release_notes",
@@ -32,6 +32,9 @@
       "bclaw_code_status",
       "bclaw_code_find",
       "bclaw_code_brief",
+      "bclaw_code_impact",
+      "bclaw_code_export",
+      "bclaw_code_outline",
       "bclaw_code_refresh",
       "bclaw_dispatch",
       "bclaw_send_message",
@@ -472,7 +475,7 @@
   },
   "bench": {
     "schema": "brainclaw.bench.v1",
-    "generated_at": "2026-08-09T01:18:56.213Z",
+    "generated_at": "2026-08-10T23:31:25.464Z",
     "node_version": "v24.18.0",
     "platform": "linux-x64",
     "repeats": 3,
@@ -481,7 +484,7 @@
         "name": "cold_onboard",
         "volume": "empty",
         "description": "fresh machine → init → first useful context. Baseline for time-to-first-value.",
-        "duration_ms_median": 77,
+        "duration_ms_median": 59,
         "payload_chars_median": 1640,
         "payload_tokens_est_median": 410
       },
@@ -489,15 +492,15 @@
         "name": "warm_work",
         "volume": "medium",
         "description": "bclaw_work consult over a real-shaped store (~200 plans / 500 handoffs / 450 claims).",
-        "duration_ms_median": 131,
-        "payload_chars_median": 2626,
-        "payload_tokens_est_median": 657
+        "duration_ms_median": 88,
+        "payload_chars_median": 2625,
+        "payload_tokens_est_median": 656
       },
       {
         "name": "first_edit",
         "volume": "medium",
         "description": "code_find + code_brief on the fresh-agent path (missing index, first touch).",
-        "duration_ms_median": 14,
+        "duration_ms_median": 10,
         "payload_chars_median": 499,
         "payload_tokens_est_median": 125
       }

package/docs/cli.md

@@ -652,6 +652,14 @@ Search the symbol index by name (function / class / component / hook / type). Re
 ### `brainclaw code-map brief <target> [--limit <n>]`
 
 Given a symbol or path, return a ranked reading list (`suggested_files_to_read`) plus related memory (decisions/traps/constraints) — what to read before editing.
+### `brainclaw code-map export <symbol-or-path> [--direction outgoing|incoming|both]`
+
+Export a compact **local** Code Map subgraph around one symbol or file. The default
+is one hop in both directions; hard caps always apply (depth 4, 100 nodes, 200
+edges), so the command never defaults to a whole-graph export. `--max-nodes`,
+`--max-edges`, and `--depth` only tighten the result; `--min-confidence` has a
+hard floor of 0.5. JSON keeps each edge's `kind`, `source`, and `confidence`.
+Use `--format mermaid` for a diagram projected from that same JSON model.
 
 ```bash
 brainclaw code-map refresh --all

package/docs/code-map.md

@@ -24,6 +24,7 @@ rebuilds it.
   brainclaw memory.
 - **To locate** a function/class/component/hook by name without grepping:
   `code-map find <query>` (or `bclaw_code_find`).
+- **To inspect a bounded local dependency neighborhood**: `code-map export <symbol-or-path>` (or `bclaw_code_export`) returns compact nodes and edges, not a repository graph dump.
 - **To check coverage / staleness**: `code-map status` (or `bclaw_code_status`).
 - **After pulling changes or doing work**: `code-map refresh` to bring the index
   back to `fresh`.
@@ -95,9 +96,30 @@ Read-only. Builds a reading brief for a symbol or file: a ranked
 brainclaw code-map brief App
 ```
 
+### `brainclaw code-map export <symbol-or-path>`
+
+Read-only export of a **local** persisted subgraph around one symbol or file. It
+never refreshes, reparses, calls a service, or silently turns into a whole-project
+graph export. The default is one hop in both directions; limits are always
+reported and hard-capped at depth 4, 100 nodes, and 200 edges.
+
+```bash
+brainclaw code-map export useAuth --direction incoming --depth 2 --json
+brainclaw code-map export src/hooks/useAuth.ts --format mermaid
+```
+
+`--direction` is `outgoing`, `incoming`, or `both` (default). `--max-nodes` and
+`--max-edges` can tighten the response only; `--min-confidence` cannot be set
+below 0.5. JSON is canonical and includes compact `nodes`, `edges`, root IDs,
+limits, truncation flags, and a freshness badge. Every edge retains `kind`,
+`source`, and `confidence`; low-confidence nodes/relations are excluded so an
+extraction heuristic cannot appear indistinguishable from a high-confidence
+relation. `--format mermaid` adds a Mermaid rendering projected from those exact
+JSON nodes and edges—never from a second traversal.
+
 ## MCP tools
 
-Capable agents should prefer the MCP surface. The four tools mirror the CLI and
+Capable agents should prefer the MCP surface. The read tools mirror the CLI and
 all return a `freshness_badge`:
 
 | Tool | Kind | Purpose |
@@ -105,6 +127,7 @@ all return a `freshness_badge`:
 | `bclaw_code_status` | read | Store presence, freshness badge, index stats. Never refreshes. |
 | `bclaw_code_find` | read | Ranked symbol-index search (`query`, optional `limit`). Never refreshes. |
 | `bclaw_code_brief` | read | Reading brief for a symbol/path (`target`, optional `limit`, files capped at 12). Never refreshes. |
+| `bclaw_code_export` | read | Bounded local subgraph around required `target`; direction/depth/node/edge caps, confidence filtering, and optional Mermaid projection. Never refreshes. |
 | `bclaw_code_refresh` | write | Rebuild the index. `scope` = `"changed"` (default) or `"all"`. Fails fast on a live lock. |
 
 The read tools never trigger a parse — if `bclaw_code_status` /

package/docs/design/federation-onboarding-usecases.md

@@ -0,0 +1,254 @@
+# Fédération cloud — cartographie des cas d'usage et des parcours
+
+> Objectif fixé par l'opérateur (2026-08-09) : identifier **tous** les cas pour qu'un ou
+> plusieurs humains, sur un ou plusieurs projets, avec un ou plusieurs agents, utilisent la
+> fédération **simplement**. Point de départ : l'onboarding côté cloud, avec l'idée d'un
+> appairage par agent via une URL d'activation.
+>
+> Chaque affirmation « état actuel » de ce document a été **mesurée sur le code ou en
+> production cette session** — les références (dec#, trp#) pointent la mesure.
+
+---
+
+## 1. Le vocabulaire d'abord — quatre identités, pas deux
+
+Tout le reste du document repose sur cette distinction. La confusion entre ces quatre
+notions est la cause directe des deux pièges déjà rencontrés (trp#1610, trp#1625).
+
+| Identité | Ce qu'elle est | Sa preuve | Où elle vit |
+|---|---|---|---|
+| **Compte humain** | La personne — s'inscrit, approuve, administre | session web (email + mot de passe) | cloud (`users`) |
+| **Appareil** | La machine — détient les clés de **déchiffrement** | clé X25519, empreinte comparée à l'appairage | local (`~/.brainclaw/keys/`) + cloud (`enrollments`) |
+| **Agent** | Le logiciel (claude-code, codex…) — **signe** ce qu'il émet | clé Ed25519, attestée à l'appairage | local (registre d'agents) + cloud (`agents`) |
+| **Projet** | Le magasin `.brainclaw/` et sa projection aveugle | — | local (source de vérité) + cloud (projection, dec#154) |
+
+Relations cibles (dec#158/159) : un humain **possède** des appareils ; un appareil
+**héberge** des agents ; un enrôlement lie *(agent, appareil, humain propriétaire, projet)*.
+
+**Écart mesuré aujourd'hui** : l'enrôlement lie agent + appareil mais **pas l'humain**
+(aucun `owner_user_id`), et l'état local ne connaît qu'**un** appairage par workspace, sans
+mémoriser quel agent (trp#1625).
+
+---
+
+## 2. La matrice des situations
+
+Quatre axes : humains (1/N) × machines (1/N) × agents (1/N) × projets (1/N).
+Les combinaisons se ramènent à six situations réellement distinctes :
+
+| # | Situation | État aujourd'hui | Ce qui bloque |
+|---|---|---|---|
+| S1 | 1 humain, 1 machine, 1 agent, 1 projet | ✅ **fonctionne, vérifié en prod** | — |
+| S2 | + agents supplémentaires sur la même machine | ❌ | `connection.json` singleton : le 2ᵉ `connect` **écrase** le 1ᵉʳ (trp#1625) |
+| S3 | + machines supplémentaires (même humain) | ❌ | pas de **remise de clé d'epoch** : la 2ᵉ machine ne peut ni lire ni sceller (dec#159) |
+| S4 | + humains supplémentaires (équipe) | ❌ | pas d'invitation par email (`404` si compte inexistant, zéro envoi d'email), pas de propriétaire d'appareil |
+| S5 | plusieurs projets | 🟡 | 1 workspace = 1 projet : correct par construction ; clés API scopées par projet (vérifié : `403` croisé) ; mais l'URL du cloud n'est pas persistée, à repasser à chaque commande |
+| S6 | agents sans humain au terminal (CI, headless) | ❌ non conçu | la cérémonie exige un humain qui compare des empreintes — cas à traiter explicitement, pas par contournement |
+
+La règle de conception qui découle de dec#158 : **le solo est le cas dégénéré du modèle
+d'équipe**, jamais une branche parallèle. S1 doit rester exactement « S4 où le même humain
+joue tous les rôles et où les approbations s'effondrent en un geste ».
+
+---
+
+## 3. Les parcours, un par un
+
+Convention : 🖥 = côté cloud (navigateur), ⌨ = côté machine (terminal), 👤 = geste humain
+explicite. ✅/🟡/❌ = état mesuré de chaque étape.
+
+### W1 — Solo : premier appairage (S1) — *fonctionne aujourd'hui*
+
+Le cas « j'utilisais déjà brainclaw en local » : le magasin existe, le cloud est vide.
+
+| # | Étape | Où | État |
+|---|---|---|---|
+| 1 | Créer un compte, créer/choisir le projet cloud | 🖥 | ✅ |
+| 2 | « Connect an agent » → créer une invitation (rôle + libellé) → **code affiché une fois** (TTL 15 min, usage unique, seul le SHA-256 est stocké) | 🖥👤 | ✅ |
+| 3 | `brainclaw cloud connect <code> --url <url> --agent <id>` **depuis le bon workspace** — le workspace appairé est affiché avec les empreintes | ⌨ | ✅ (garde trp#1610 livrée) |
+| 4 | Comparer les **deux empreintes** terminal ↔ écran, approuver | 🖥👤 | ✅ |
+| 5 | `brainclaw cloud await --url <url>` → appairage local actif, **genèse de la clé d'epoch 1** (premier appareil seulement) | ⌨ | ✅ (livré ce jour) |
+| 6 | `brainclaw cloud push --url <url>` → plans + mémoire projet scellés, envoyés, stockés | ⌨ | ✅ (vérifié en prod : enveloppe en base, zéro fuite) |
+
+**Frictions restantes de W1** (aucune bloquante) : l'URL doit être répétée à chaque commande
+(l'état ne la persiste pas — mesuré) ; `connect` puis `await` sont deux commandes là où une
+seule suffirait (`connect` pourrait attendre l'approbation en sondant) ; l'agent doit être
+un identifiant opaque `[a-zA-Z0-9_-]{4,64}` et l'erreur ne le dit qu'après coup.
+
+### W2 — Deuxième agent, même machine (S2) — *à construire*
+
+Cible : les agents d'une même machine **partagent la clé X25519 de l'appareil** et signent
+chacun avec leur Ed25519. C'est cohérent avec l'attestation existante (elle lie déjà un
+Ed25519 à un X25519) : chaque agent atteste **la même** clé d'appareil.
+
+| # | Étape | Où | État |
+|---|---|---|---|
+| 1 | Créer une invitation **par agent** (ou une invitation multi-usages ? → non : usage unique conservé, un code par agent) | 🖥👤 | ✅ (mécanique identique à W1) |
+| 2 | `cloud connect <code> --agent <id2>` → détecte l'appairage existant, **réutilise la clé d'appareil**, ajoute un enrôlement à la liste | ⌨ | ❌ `connection.json` doit devenir une **liste d'appairages** `{agent, enrollment_id, role}` autour d'un `device` unique |
+| 3 | Approbation par empreintes — l'empreinte de chiffrement **répète** celle de l'appareil, l'empreinte d'identité change par agent | 🖥👤 | 🟡 l'écran d'approbation existe ; afficher « appareil déjà connu » serait le bon signal |
+| 4 | Chaque agent pousse sous sa propre signature ; l'origine (`origin_agent_id`) les distingue | ⌨ | ✅ le transport le fait déjà |
+
+**Prérequis structurel** : migration de `connection.json` (forme v2 → v3) avec lecture
+tolérante des deux formats — même discipline que la purge cloud (rien d'irréversible sans
+chemin de retour).
+
+### W3 — Deuxième machine, même humain (S3) — *bloqué sur la remise d'epoch*
+
+| # | Étape | Où | État |
+|---|---|---|---|
+| 1 | Invitation + cérémonie sur la machine B (identique à W1 étapes 2–4) | 🖥⌨👤 | ✅ |
+| 2 | La machine B est `active` **mais ne détient aucune clé d'epoch** : elle ne peut ni lire ni sceller | — | ⚠️ c'est l'état actuel : actif et inopérant, sans message |
+| 3 | Une machine détentrice (A) **remet** les epochs autorisés : paquet HPKE scellé vers la X25519 attestée de B, manifeste signé (`epoch_grant`, dec#159) | ⌨ A | ❌ à construire — **le cœur du chantier** |
+| 4 | B vérifie le manifeste, range les clés (`storeEpochPrivateKey` refuse déjà d'écraser une clé différente), relit le passé autorisé | ⌨ B | 🟡 primitives présentes, protocole absent |
+
+**Point de vigilance déjà mesuré** : le premier appairage marque `recovery: true` et le
+quorum de récupération (2 appareils) est **rapporté mais jamais appliqué** — le solo n'est
+pas bloqué, mais la perte de l'unique machine = perte du passé, et rien ne l'affiche.
+
+### W4 — Embarquer un deuxième développeur (S4) — *le parcours demandé, à construire*
+
+Le principe directeur (convergence des deux critiques de l'idéation) : **deux approbations
+de nature différente**. L'admin admet **l'humain** ; l'humain approuve **ses appareils**.
+Un admin ne peut pas comparer les empreintes du terminal d'un tiers — le faire approuver à
+sa place réduirait la cérémonie à un clic de confiance (dec#8).
+
+| # | Étape | Où | État |
+|---|---|---|---|
+| 1 | Admin : « Inviter un membre » → email + rôle | 🖥👤 | ❌ aujourd'hui `404` si le compte n'existe pas |
+| 2 | Le cloud envoie un email avec lien d'acceptation ; si le compte n'existe pas, le lien passe par l'inscription | 🖥 | ❌ **zéro envoi d'email dans le backend** (une skill `cloudflare-email-service` est disponible pour le construire) |
+| 3 | Le membre accepte → `project_members` actif avec son rôle | 🖥👤 | 🟡 la table et les rôles existent, le flux non |
+| 4 | Le membre crée **ses** invitations d'agent (portée : ses propres appareils) et fait W1/W2 sur ses machines | 🖥⌨👤 | ❌ nécessite `owner_user_id` sur `enrollments` + revendication de propriétaire **dans le payload d'attestation signé** (sinon la liaison humain↔appareil ne vaut que la parole du cloud) |
+| 5 | L'**admin voit** les appareils du membre (métadonnées, pas les clés) ; le **membre** les approuve | 🖥 | ❌ l'écran d'approbation ne filtre pas par propriétaire |
+| 6 | Un custodian remet les epochs selon l'**horizon** choisi (tout / à partir de maintenant / borné) | ⌨ | ❌ même chantier que W3-3 + **arbitrage produit** (voir §7) |
+
+### W5 — Révoquer (agent, appareil, ou humain)
+
+| # | Étape | Où | État |
+|---|---|---|---|
+| 1 | Révoquer l'enrôlement (bouton « Revoke ») | 🖥👤 | ✅ existe |
+| 2 | Supprimer / renommer l'agent dans le registre cloud | 🖥 | ❌ **aucun `DELETE /agents/:id`**, le `PATCH` ne change que le statut — c'est le manque constaté par l'opérateur |
+| 3 | Rotation d'epoch N+1, remise aux lecteurs restants | ⌨ | ❌ dépend de W3-3 |
+| 4 | Affichage honnête : « ne lit plus le **futur** ; conserve ce qu'il avait déjà déchiffré » | 🖥 | ✅ le texte existe sur la page connect |
+
+### W6 — Perte de machine / récupération
+
+RFC §5.3 : un porteur restant approuve la nouvelle clé, enveloppe les epochs historiques
+autorisés, révoque l'ancienne. Même mécanique que W3-3 avec un autorisateur différent —
+**toute solution qui inventerait un second canal de transfert de clés créerait un second
+endroit où une clé peut fuir** (conséquence 3 de dec#158).
+État : ❌ (bloqué sur la remise d'epoch) + ⚠️ quorum non appliqué (mesuré).
+
+### W7 — Quotidien : synchroniser
+
+| # | Étape | État |
+|---|---|---|
+| 1 | `cloud push` — scelle, met en file, envoie ; refus des trois filets listés un par un | ✅ vérifié en prod |
+| 2 | **Pull** — tirer les enveloppes des autres, vérifier (`verifyInbound` : roster, signature, AAD, anti-rejeu), matérialiser localement | ❌ **`verifyInbound` n'a aucun appelant de production** — symétrique exact de l'émission avant ce matin ; le « Materialized N signals » des sessions vient du chemin **v1** |
+| 3 | Relais dashboard : changer statut/priorité depuis le web, appliqué localement (`applyCloudCommand`) | 🟡 primitives présentes des deux côtés, câblage du poll absent |
+| 4 | Automatisation : push en fin de session, pull en début (hooks existants) | ❌ manuel aujourd'hui |
+| 5 | Conflits : `409` → recalage signé une fois, sinon visible en `conflict` | ✅ |
+
+### W8 — Multi-projets (S5)
+
+Fonctionne par construction (1 workspace = 1 projet, table d'ids opaques cloisonnée par
+projet cloud — testé). Reste : persister l'URL du cloud par appairage, et le sélecteur de
+projet web existe déjà.
+
+### W9 — Agent headless / CI (S6) — *à concevoir, pas à contourner*
+
+La cérémonie exige un humain au terminal. Pour un runner CI éphémère, trois options à
+trancher **plus tard** (aucune n'est urgente) : appairage du runner par son propriétaire au
+provisioning ; « appareil de service » à rôle réduit (écriture seule, jamais custodian) ;
+ou exclusion assumée (le CI passe par un membre humain). À documenter comme limite tant que
+non conçu.
+
+---
+
+## 4. L'URL d'activation — ce qu'elle change, ce qu'elle ne doit jamais porter
+
+L'idée de l'opérateur est bonne et **peu coûteuse** : l'URL est un véhicule pour le code
+d'invitation existant, pas un nouveau mécanisme.
+
+```
+https://app.brainclaw.dev/a/<code>          ← partageable à l'humain OU collée à l'agent
+brainclaw cloud connect <url|code> --agent x  ← la CLI accepte les deux formes
+```
+
+Ce que ça améliore : une seule chose à copier (aujourd'hui : code + URL + savoir où les
+mettre) ; un agent à qui on colle l'URL peut en extraire le code ET l'adresse du
+déploiement — ce qui règle au passage la non-persistance de l'URL.
+
+**Les invariants qui rendent l'URL sûre** (tous déjà en place pour le code) :
+usage unique, TTL 15 min, seul le SHA-256 stocké, et surtout — **l'URL ne donne aucun droit
+de lecture**. Elle n'ouvre que le droit de *candidater* ; la sécurité reste dans la
+comparaison d'empreintes à l'approbation, et les clés d'epoch ne voyagent **jamais** dans
+une URL.
+
+**Le piège à refuser explicitement** : mettre dans l'URL de quoi éviter l'approbation
+(« lien magique » qui active). Ce serait le modèle moltbook, voir ci-dessous.
+
+## 5. Pourquoi pas l'auto-enregistrement (le modèle moltbook), et ce qu'on en garde
+
+Le modèle « l'agent s'enregistre tout seul dans l'application » échoue sur trois points,
+tous structurels :
+
+1. **Aucune liaison de propriété** — n'importe quel processus connaissant l'URL devient un
+   agent du projet ; l'identité se squatte.
+2. **Le cloud peut fabriquer des agents** — sans approbation humaine par empreintes, un
+   cloud hostile insère son propre « membre fantôme » dans le projet, et le chiffrement de
+   bout en bout devient décoratif (c'est exactement l'attaque que l'attestation
+   X25519-par-Ed25519 ferme, migrations 0022/0025).
+3. **Rien ne lie l'agent à une clé** — un agent enregistré sans attestation ne peut pas
+   recevoir d'epoch de façon vérifiable.
+
+**Ce qu'on en garde** : la simplicité du geste — *un seul artefact à transmettre*. C'est
+précisément l'URL d'activation (§4) : la simplicité de moltbook, la cérémonie en dessous.
+
+---
+
+## 6. Besoins transverses (indépendants des parcours)
+
+| Besoin | Pourquoi | État |
+|---|---|---|
+| Envoi d'email (invitations, notifications d'approbation) | W4 | ❌ — skill `cloudflare-email-service` disponible |
+| CRUD agents cloud (`DELETE`, renommage, purge des agents v1 périmés) | W5, demande opérateur | ❌ |
+| État local multi-appairage (`connection.json` v3 : un `device`, une liste d'agents) | W2, trp#1625 | ❌ |
+| Persistance de l'URL du cloud dans l'état d'appairage | toutes les commandes | ❌ (mesuré) |
+| `connect` qui enchaîne l'attente d'approbation (supprime `await` du chemin nominal) | W1 friction | ❌ |
+| Pull v2 (`verifyInbound` câblé + matérialisation + curseur de feed) | W7 — sans lui, la fédération est **unidirectionnelle** | ❌ |
+| Application du quorum de récupération (aujourd'hui rapporté, jamais bloquant) | W6 | ❌ |
+| Écran « appareils par humain » (l'admin voit, le propriétaire approuve) | W4 | ❌ |
+
+## 7. Les arbitrages qui vous appartiennent (aucun n'est technique)
+
+Repris de dec#159 — à trancher **avant** W3/W4, parce qu'irréversibles par nature :
+
+1. **Horizon par défaut d'un nouveau membre** : rien / depuis l'adhésion / tout.
+   Recommandation technique : minimal (élargir reste toujours possible, reprendre jamais).
+2. **Qui est custodian** des remises de clés : le premier appareil ? tout membre `admin` ?
+   un quorum ? — et l'exigence d'indépendance des appareils de récupération.
+3. **Disponibilité** : accepter qu'un nouveau membre attende qu'un custodian soit en ligne,
+   ou financer une récupération explicitement détentrice de clés (coffre).
+4. **Équivocation du cloud** : aucun témoin / gossip d'équipe / journal de transparence.
+   Le cloud hostile qui montre des rosters différents à deux humains reste indétectable
+   sans canal hors bande — c'est une limite à afficher, pas à taire.
+
+## 8. Ordre de construction proposé
+
+Chaque tranche est livrable et vérifiable seule ; les deux premières ne demandent aucun
+arbitrage :
+
+1. **Fondations sans arbitrage** — état multi-appairage (W2), URL persistée + URL
+   d'activation (§4), `connect` qui attend, CRUD agents (W5-2). *Débloque S2 et la demande
+   opérateur immédiate.*
+2. **Pull v2** (W7-2) — la fédération devient bidirectionnelle ; sans lui, un deuxième
+   appareil n'aurait de toute façon rien à lire.
+3. **Invitation d'humains** (W4-1..3, email inclus) — après l'arbitrage §7-1 au minimum.
+4. **Remise d'epoch** (W3/W4-6/W6) — le gros œuvre, après les arbitrages §7-1/2/3.
+
+---
+
+*Références : dec#154 (cloud = projection), dec#155 (relais sans contexte), dec#156 (v2
+cassante), dec#158 (appairage deux niveaux), dec#159 (synthèse idéation, epoch grants),
+dec#160 (six divergences de contrat, résolues), trp#1610 (connect appaire le cwd),
+trp#1625 (connection.json singleton), critiques `CRITIQUE-codex.md` /
+`CRITIQUE-claude-code.md` (worktrees de l'idéation du 2026-08-09).*