brainclaw 1.23.0 → 1.24.0

package/dist/core/federation-rotation.js

@@ -0,0 +1,124 @@
+/**
+ * Rotation d'epoch — retirer la LECTURE FUTURE à un appareil (pln#658, dec#163).
+ *
+ * ── CE QUE LA ROTATION FAIT, ET CE QU'ELLE NE PEUT PAS FAIRE ──────────────────
+ * Elle crée un epoch N+1 dont le révoqué n'a pas la clé, et fait basculer les écritures
+ * dessus. À partir du cutover, il ne lit plus RIEN de nouveau.
+ *
+ * Elle ne lui retire PAS ce qu'il détient déjà. C'est cryptographiquement impossible : une
+ * clé copiée sur une machine y reste. Le prétendre serait mentir, et dec#163 §3 l'interdit
+ * explicitement. La révocation est FORWARD-ONLY, et c'est dit à l'opérateur en toutes
+ * lettres au moment où il tourne la clé — pas dans une note de bas de page.
+ *
+ * ── LE QUORUM EST APPLIQUÉ ICI, ET SEULEMENT ICI (dec#163 §4) ─────────────────
+ * « Émettre au-delà du premier epoch » = créer un epoch N+1. C'est le moment exact où la
+ * perte d'une machine cesse d'être théorique : après rotation, l'ancien epoch ne sert plus
+ * qu'à relire le passé, et si personne d'autre ne détient le nouveau, une panne de disque
+ * emporte tout le futur. `recoveryReadiness` était RAPPORTÉ et jamais bloquant (mesuré) —
+ * il devient une condition.
+ *
+ * En solo, l'opérateur peut passer outre, mais son consentement est PERSISTÉ : on ne
+ * demande pas deux fois, et surtout on garde la trace qu'il a été demandé.
+ */
+import crypto from 'node:crypto';
+import { loadConnectionState, saveConnectionState, recoveryReadiness, } from './federation-state.js';
+import { storeEpochPrivateKey, epochPublicKey, heldEpochs } from './federation-keyring.js';
+export const FORWARD_ONLY_NOTICE = "La rotation ne retire à personne ce qu'il détient DÉJÀ : un appareil révoqué peut " +
+    "toujours relire ce qui a été scellé avant le cutover. Elle ferme la lecture du FUTUR, " +
+    'pas celle du passé — aucune cryptographie ne peut faire autrement.';
+const SOLO_CONSENT_STATEMENT = "Je comprends que la perte de cette machine signifie la perte définitive de l'historique " +
+    'scellé : aucune restauration côté cloud ne le ramènera.';
+export function soloConsentStatement() {
+    return SOLO_CONSENT_STATEMENT;
+}
+function readConsent(state) {
+    return state.solo_recovery_consent;
+}
+/**
+ * Enregistre le consentement solo. Idempotent : réaccepter ne réécrit pas la date d'origine,
+ * parce que la question « quand cette personne a-t-elle compris le risque ? » a UNE réponse.
+ */
+export function acceptSoloRecoveryRisk(cwd) {
+    const state = loadConnectionState(cwd ?? process.cwd());
+    if (!state)
+        throw new Error('Aucun appairage local : rien à consentir.');
+    const existing = readConsent(state);
+    if (existing)
+        return existing;
+    const consent = {
+        accepted_at: new Date().toISOString(),
+        statement: SOLO_CONSENT_STATEMENT,
+    };
+    saveConnectionState({ ...state, ...{ solo_recovery_consent: consent } }, cwd ?? process.cwd());
+    return consent;
+}
+/**
+ * Fait tourner l'epoch : crée N+1 localement et bascule les écritures dessus.
+ *
+ * NE REMET RIEN AUX AUTRES — c'est délibérément une seconde étape (`cloud grant`). Coupler
+ * les deux ferait qu'un échec de remise laisserait un cutover à moitié fait : les écritures
+ * seraient déjà passées sous N+1 pendant que les lecteurs légitimes n'auraient pas la clé.
+ * Le résultat NOMME donc les destinataires à re-servir.
+ */
+export function rotateEpoch(options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const state = loadConnectionState(cwd);
+    if (!state) {
+        return {
+            ok: false, reason: 'no_pairing',
+            detail: 'Aucun appairage local.',
+            remedy: 'Appairer cet appareil avant toute rotation (`brainclaw cloud connect`).',
+        };
+    }
+    const held = heldEpochs(state.cloud_project_id, options.home);
+    const current = state.keys?.current_epoch ?? 0;
+    if (current <= 0 || !held.includes(current)) {
+        return {
+            ok: false, reason: 'not_holder',
+            detail: `Cet appareil ne détient pas l'epoch courant (${current}) — il ne peut pas en produire le suivant.`,
+            remedy: "Se faire remettre l'epoch courant par un détenteur (`brainclaw cloud grant`) avant de tourner.",
+        };
+    }
+    // ── LE QUORUM, APPLIQUÉ (dec#163 §4) ────────────────────────────────────────
+    const readiness = recoveryReadiness(state);
+    const consent = readConsent(state);
+    if (!readiness.ready && !consent && !options.force) {
+        return {
+            ok: false, reason: 'recovery_quorum',
+            detail: `${readiness.reason ?? 'Quorum de récupération non atteint.'} ` +
+                "Tourner l'epoch maintenant ferait dépendre TOUT le futur du projet de cette seule machine.",
+            remedy: "Appairer un second appareil de récupération, OU accepter explicitement le risque " +
+                '(`brainclaw cloud accept-solo-risk`), ce qui sera consigné avec sa date.',
+        };
+    }
+    const next = current + 1;
+    // Ne jamais écraser : si N+1 existe déjà, c'est qu'une rotation a déjà eu lieu (reprise
+    // après interruption). On la constate au lieu d'en fabriquer une seconde.
+    const already = epochPublicKey(state.cloud_project_id, next, options.home);
+    if (!already) {
+        const generated = crypto.generateKeyPairSync('x25519');
+        storeEpochPrivateKey(state.cloud_project_id, next, generated.privateKey.export({ type: 'pkcs8', format: 'pem' }).toString(), options.home);
+    }
+    const materialized = epochPublicKey(state.cloud_project_id, next, options.home);
+    if (!materialized) {
+        // Vérifier APRÈS écriture : basculer les écritures sur une clé qu'on ne relit pas
+        // produirait des enveloppes que PERSONNE ne peut ouvrir, y compris nous.
+        throw new Error(`Epoch ${next} écrit mais non relisible — le cutover est ANNULÉ pour ne pas sceller ` +
+            'sous une clé fantôme.');
+    }
+    // CUTOVER : les écritures suivantes scellent sous N+1 (emitProjections lit current_epoch).
+    const readable = heldEpochs(state.cloud_project_id, options.home);
+    saveConnectionState({
+        ...state,
+        keys: { ...(state.keys ?? { current_epoch: 0, known_epochs: [] }), current_epoch: next, known_epochs: readable },
+    }, cwd);
+    return {
+        ok: true,
+        previous_epoch: current,
+        new_epoch: next,
+        new_epoch_fingerprint: materialized.fingerprint,
+        readable_epochs: readable,
+        forward_only_notice: FORWARD_ONLY_NOTICE,
+    };
+}
+//# sourceMappingURL=federation-rotation.js.map

package/dist/core/federation-state.js

@@ -34,7 +34,9 @@ import { heldEpochs } from './federation-keyring.js';
 import { counters as outboxCounters } from './federation-outbox-v2.js';
 import { logger } from './logger.js';
 const CONNECTION_FILE = 'connection.json';
-export const FEDERATION_STATE_SCHEMA = 'brainclaw.federation-connection/v2';
+export const FEDERATION_STATE_SCHEMA = 'brainclaw.federation-connection/v3';
+/** Schéma v2 — singleton mono-agent. Lu en tolérance, jamais écrit (trp#1625). */
+const FEDERATION_STATE_SCHEMA_V2 = 'brainclaw.federation-connection/v2';
 /** Nombre d'appareils de récupération exigés avant la première enveloppe (RFC §5.3). */
 export const REQUIRED_RECOVERY_DEVICES = 2;
 // ── Emplacement ───────────────────────────────────────────────────────────────
@@ -63,12 +65,73 @@ export function loadConnectionState(cwd = process.cwd()) {
         return undefined;
     }
     const state = raw;
-    if (state.schema !== FEDERATION_STATE_SCHEMA || !state.cloud_project_id || !state.device?.device_id) {
-        // Un schéma inconnu n'est PAS migré (dec#156) : la v1 est abandonnée, pas dépréciée.
-        logger.warn(`État de connexion fédération ignoré : schéma '${String(state.schema)}' non reconnu (attendu ${FEDERATION_STATE_SCHEMA}).`);
+    const knownSchema = state.schema === FEDERATION_STATE_SCHEMA || state.schema === FEDERATION_STATE_SCHEMA_V2;
+    if (!knownSchema || !state.cloud_project_id || !state.device?.device_id) {
+        // Un schéma inconnu (v1) n'est PAS migré (dec#156) : abandonné, pas déprécié. Mais la
+        // v2 EST lue — c'est le format vivant sur les machines déjà appairées ; le refuser
+        // détruirait leur appairage au premier chargement après mise à jour.
+        logger.warn(`État de connexion fédération ignoré : schéma '${String(state.schema)}' non reconnu.`);
         return undefined;
     }
-    return normalizeState(state, cwd);
+    return normalizeState(projectToV3(state), cwd);
+}
+/**
+ * Projette un état v2 (singleton) vers la forme v3 (liste de pairings) À LA LECTURE.
+ *
+ * Un v2 n'a pas de `pairings` ni de `cloud_url` ni d'agent mémorisé. On dérive un pairing
+ * unique de son `enrollment` — l'agent est marqué inconnu, faute de l'information : le
+ * singleton v2 ne l'a jamais stockée, et l'inventer serait mentir. Un état déjà v3 passe
+ * inchangé. Rien n'est réécrit sur disque ici : la conversion n'a lieu qu'en mémoire, et
+ * la prochaine ÉCRITURE (un appairage, une révocation) persistera la forme v3.
+ */
+function projectToV3(state) {
+    if (Array.isArray(state.pairings)) {
+        return { ...state, schema: FEDERATION_STATE_SCHEMA };
+    }
+    const enrollment = state.enrollment ?? { stage: 'unpaired', updated_at: nowISO() };
+    const derived = {
+        agent_id: '(inconnu — appairé en v2)',
+        stage: enrollment.stage,
+        enrollment_id: enrollment.enrollment_id,
+        role: enrollment.role,
+        updated_at: enrollment.updated_at,
+    };
+    return {
+        ...state,
+        schema: FEDERATION_STATE_SCHEMA,
+        pairings: enrollment.enrollment_id || enrollment.stage !== 'unpaired' ? [derived] : [],
+    };
+}
+// ── Manipulation des pairings (v3) ─────────────────────────────────────────────
+/** Le pairing d'un agent donné, ou `undefined`. */
+export function pairingForAgent(state, agentId) {
+    return state.pairings.find((p) => p.agent_id === agentId);
+}
+/** Y a-t-il au moins un pairing actif ? Décide notamment la genèse d'epoch (premier appareil). */
+export function hasActivePairing(state) {
+    return state.pairings.some((p) => p.stage === 'active');
+}
+/**
+ * Ajoute ou met à jour le pairing d'un agent, SANS toucher aux autres, et maintient le
+ * miroir `enrollment` sur le pairing touché. Retourne un nouvel état (immuable).
+ *
+ * C'est l'unique porte par laquelle un pairing entre ou change : centraliser le maintien
+ * du miroir ici évite qu'un écrivain oublie de le synchroniser et fasse diverger la vue
+ * mono-agent de la source de vérité.
+ */
+export function upsertPairing(state, pairing) {
+    const others = state.pairings.filter((p) => p.agent_id !== pairing.agent_id);
+    return {
+        ...state,
+        pairings: [...others, pairing],
+        enrollment: {
+            stage: pairing.stage,
+            enrollment_id: pairing.enrollment_id,
+            role: pairing.role,
+            updated_at: pairing.updated_at,
+        },
+        updated_at: nowISO(),
+    };
 }
 /**
  * Réconcilie l'état déclaré avec le DISQUE.
@@ -154,11 +217,16 @@ function assertNoSecret(state) {
  */
 export function createConnectionState(params) {
     const now = nowISO();
+    const firstPairing = params.agentId
+        ? { agent_id: params.agentId, stage: 'pending', enrollment_id: params.enrollmentId, updated_at: now }
+        : undefined;
     return {
         schema: FEDERATION_STATE_SCHEMA,
         cloud_project_id: params.cloudProjectId,
+        cloud_url: params.cloudUrl,
         workspace_path: path.resolve(params.workspacePath ?? process.cwd()),
         enrollment: { stage: 'pending', enrollment_id: params.enrollmentId, updated_at: now },
+        pairings: firstPairing ? [firstPairing] : [],
         device: params.device,
         peer_devices: [],
         // 0 = « aucun epoch » et non « premier epoch ». Le premier epoch remis est le 1 ;
@@ -250,18 +318,25 @@ export function summarizeConnection(cwd = process.cwd()) {
             stage: 'unpaired',
             current_epoch: 0,
             readable_epochs: [],
+            pairings: [],
             sync,
             recovery: { ready: false, enrolled: 0, required: REQUIRED_RECOVERY_DEVICES },
         };
     }
     return {
-        connected: state.enrollment.stage === 'active',
+        // Connecté dès qu'AU MOINS UN agent est actif, OU que le miroir l'indique. Le OR est
+        // une ceinture de sécurité pour l'affichage : un état projeté depuis v2, ou construit
+        // à la main, peut porter un miroir actif sans pairing correspondant. Mieux vaut
+        // afficher « connecté » et laisser l'opérateur voir que masquer un appairage réel.
+        connected: hasActivePairing(state) || state.enrollment.stage === 'active',
         cloud_project_id: state.cloud_project_id,
         stage: state.enrollment.stage,
         role: state.enrollment.role,
         current_epoch: state.keys.current_epoch,
         readable_epochs: state.keys.known_epochs,
         device_fingerprint: state.device.x25519_fingerprint,
+        cloud_url: state.cloud_url,
+        pairings: state.pairings.map((p) => ({ agent_id: p.agent_id, stage: p.stage, role: p.role })),
         sync,
         last_pull_at: state.sync.last_pull_at,
         recovery: recoveryReadiness(state),

package/dist/facts.js

@@ -1,8 +1,8 @@
 // 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.24.0 on 2026-08-10T18:03:29.240Z
 export const FACTS = {
-  "version": "1.23.0",
-  "generated_at": "2026-08-09T01:18:58.355Z",
+  "version": "1.24.0",
+  "generated_at": "2026-08-10T18:03:29.240Z",
   "tools": {
     "count": 67,
     "published_count": 65,
@@ -474,7 +474,7 @@ export const FACTS = {
   },
   "bench": {
     "schema": "brainclaw.bench.v1",
-    "generated_at": "2026-08-09T01:18:56.213Z",
+    "generated_at": "2026-08-10T18:03:27.087Z",
     "node_version": "v24.18.0",
     "platform": "linux-x64",
     "repeats": 3,
@@ -483,7 +483,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": 71,
         "payload_chars_median": 1640,
         "payload_tokens_est_median": 410
       },
@@ -491,7 +491,7 @@ 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,
+        "duration_ms_median": 107,
         "payload_chars_median": 2626,
         "payload_tokens_est_median": 657
       },
@@ -499,7 +499,7 @@ export const FACTS = {
         "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,6 +1,6 @@
 {
-  "version": "1.23.0",
-  "generated_at": "2026-08-09T01:18:58.355Z",
+  "version": "1.24.0",
+  "generated_at": "2026-08-10T18:03:29.240Z",
   "tools": {
     "count": 67,
     "published_count": 65,
@@ -472,7 +472,7 @@
   },
   "bench": {
     "schema": "brainclaw.bench.v1",
-    "generated_at": "2026-08-09T01:18:56.213Z",
+    "generated_at": "2026-08-10T18:03:27.087Z",
     "node_version": "v24.18.0",
     "platform": "linux-x64",
     "repeats": 3,
@@ -481,7 +481,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": 71,
         "payload_chars_median": 1640,
         "payload_tokens_est_median": 410
       },
@@ -489,7 +489,7 @@
         "name": "warm_work",
         "volume": "medium",
         "description": "bclaw_work consult over a real-shaped store (~200 plans / 500 handoffs / 450 claims).",
-        "duration_ms_median": 131,
+        "duration_ms_median": 107,
         "payload_chars_median": 2626,
         "payload_tokens_est_median": 657
       },
@@ -497,7 +497,7 @@
         "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/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).*