brainclaw 1.23.0 → 1.25.0

package/dist/core/federation-push.js

@@ -0,0 +1,287 @@
+/**
+ * Fédération v2 — TRANSPORT : drainer l'outbox vers le cloud.
+ *
+ * ── POURQUOI CE MODULE EST SÉPARÉ DE L'ÉMISSION ───────────────────────────────
+ * `federation-emit.ts` scelle et met en file ; celui-ci envoie. La séparation n'est pas
+ * cosmétique : une file qui saurait aussi parler au réseau serait un SECOND chemin par
+ * lequel un objet pourrait sortir sans passer par les trois filets du projecteur. Ici, tout
+ * ce qui part a déjà été scellé — ce module ne voit que des `sealed` opaques et ne peut donc
+ * pas divulguer de clair, même par erreur de programmation.
+ *
+ * ── CE QU'IL FAIT DE L'ÉCHEC ──────────────────────────────────────────────────
+ * Une entrée qui échoue RESTE en attente, avec son erreur enregistrée. Elle n'est ni
+ * supprimée ni déplacée en `conflict` : un échec réseau n'est pas un conflit de révision, et
+ * les confondre ferait disparaître de la file une opération jamais émise.
+ *
+ * Seul un 409 fait passer en `conflict` — c'est le cas où le cloud dit « ta base_rev est
+ * périmée », donc un désaccord d'état qu'un renvoi ne résoudra pas.
+ */
+import crypto from 'node:crypto';
+import { list, transition } from './federation-outbox-v2.js';
+import { loadConnectionState } from './federation-state.js';
+import { loadAgentSigningKey } from './agent-registry.js';
+import { logger } from './logger.js';
+/**
+ * Met une entrée d'outbox à la forme que le cloud attend RÉELLEMENT.
+ *
+ * ── POURQUOI CETTE FONCTION EXISTE, ET CE QU'ELLE A COÛTÉ ────────────────────
+ * La première version envoyait `{ envelope, key_epoch, base_rev }` — la forme que je
+ * SUPPOSAIS. Le cloud attend des champs À PLAT : id, entity_kind, entity_id, rev,
+ * sealed_b64, content_hash, meta, et quatre champs d'origine. Mon test de bout en bout
+ * n'a rien vu : il utilisait un `fetch` simulé, donc il validait mon hypothèse de l'API
+ * contre elle-même.
+ *
+ * C'est la même leçon que d'habitude, à un endroit nouveau : un contrat inter-services ne
+ * se vérifie que contre le service, jamais contre l'idée qu'on s'en fait.
+ *
+ * `sealed` est encodé en base64 d'un JSON canonique : le cloud le stocke sans jamais
+ * l'ouvrir — il n'en a pas la clé.
+ */
+/** En-têtes communs : type, idempotence, et porteur si le déploiement l'exige. */
+function authHeaders(idempotencyKey, apiKey) {
+    const headers = {
+        'content-type': 'application/json',
+        // La clé d'idempotence voyage AUSSI en en-tête : le cloud doit pouvoir dédoublonner
+        // sans ouvrir le corps, qu'il ne peut de toute façon pas lire.
+        'idempotency-key': idempotencyKey,
+    };
+    if (apiKey)
+        headers['authorization'] = `Bearer ${apiKey}`;
+    return headers;
+}
+/**
+ * Charge SIGNÉE DU TRANSPORT — reconstruite exactement comme le cloud la reconstruit.
+ *
+ * L'ordre des clés compte : le cloud fait `JSON.stringify` sur cet objet littéral, sans
+ * tri. Une clé déplacée produit une chaîne différente, donc un condensé différent, donc un
+ * refus SIG_PAYLOAD_HASH_MISMATCH que rien dans le message n'expliquerait.
+ */
+function transportPayload(wire, baseRev) {
+    return JSON.stringify({
+        v: 1,
+        kind: 'brainclaw.federation.v2.envelope',
+        envelope_id: wire['id'],
+        project_id: wire['__project_id'],
+        entity_kind: wire['entity_kind'],
+        entity_id: wire['entity_id'],
+        rev: wire['rev'],
+        base_rev: baseRev,
+        content_hash: wire['content_hash'],
+        key_epoch: wire['key_epoch'],
+        is_tombstone: false,
+    });
+}
+/**
+ * Signe la charge de transport et renseigne les trois champs qui en dépendent.
+ *
+ * ── POURQUOI LE TRANSPORT SIGNE, ALORS QUE L'ENVELOPPE EST DÉJÀ SIGNÉE ───────
+ * Ce sont DEUX garanties distinctes. La signature d'enveloppe (RFC) lie meta ‖ sealed ‖
+ * key_epoch : elle dit « ce contenu vient de cet auteur ». La signature de transport lie
+ * envelope_id, rev, base_rev et content_hash : elle dit « cette opération-ci s'applique à
+ * CETTE révision », ce que la première ne peut pas dire — ces champs n'existent pas encore
+ * au moment de sceller.
+ *
+ * ── ET C'EST CE QUI DÉBLOQUE LE RECALAGE SUR 409 ────────────────────────────
+ * J'avais d'abord jugé les deux contrats incompatibles (dec#160 §6), parce que `base_rev`
+ * peut changer au réessai et invaliderait une signature calculée à l'émission. Faire signer
+ * le TRANSPORT lève l'objection : il resigne simplement avec la nouvelle valeur.
+ *
+ * Cette clé Ed25519 SIGNE, elle ne déchiffre rien : la propriété « ce module ne peut pas
+ * divulguer de clair » tient toujours.
+ */
+function signTransport(wire, baseRev, identityPem) {
+    const payload = Buffer.from(transportPayload(wire, baseRev), 'utf-8');
+    const signature = crypto.sign(null, payload, crypto.createPrivateKey(identityPem));
+    const body = { ...wire, base_rev: baseRev };
+    delete body['__project_id'];
+    return {
+        ...body,
+        origin_sig: signature.toString('base64'),
+        origin_sig_payload_hash: crypto.createHash('sha256').update(payload).digest('hex'),
+    };
+}
+function toWireBody(entry) {
+    const env = entry.sealed;
+    const meta = env.meta;
+    const transport = (meta['transport'] ?? {});
+    // ── L'EMPREINTE PORTE SUR CE QUI EST RÉELLEMENT ENVOYÉ ──────────────────────
+    //
+    // Le cloud recalcule SHA-256 sur les octets DÉCODÉS de `sealed_b64`, en hexadécimal, et
+    // refuse tout écart (CONTENT_HASH_MISMATCH). Le `content_hash` du core est calculé
+    // autrement — base64url sur une autre sérialisation — donc le réutiliser tel quel
+    // échouait systématiquement.
+    //
+    // Le calculer ICI, sur les octets exacts qu'on encode, rend l'accord vrai PAR
+    // CONSTRUCTION plutôt que par coïncidence de conventions. Deux sérialisations qui
+    // doivent produire le même condensé sont un pari ; hacher ce qu'on envoie n'en est pas un.
+    const sealedBytes = Buffer.from(JSON.stringify(env.sealed), 'utf-8');
+    const contentHashHex = crypto.createHash('sha256').update(sealedBytes).digest('hex');
+    return {
+        id: String(transport['idempotency_key'] ?? entry.idempotency_key),
+        entity_kind: meta['kind'],
+        entity_id: meta['id_opaque'],
+        rev: String(meta['base_rev'] ?? entry.base_rev ?? 0),
+        // Aucune tête connue au premier envoi : le cloud l'annonce dans son 409 et l'appelant
+        // se recale une fois. Suivre cette tête localement dupliquerait un état dont le cloud
+        // est déjà l'autorité.
+        base_rev: null,
+        sealed_b64: sealedBytes.toString('base64'),
+        key_epoch: env.key_epoch,
+        content_hash: contentHashHex,
+        idempotency_key: String(transport['idempotency_key'] ?? entry.idempotency_key),
+        // `key_id` de l'enveloppe EST l'empreinte du signataire (cf. federation-emit).
+        // L'agent d'origine voyage à part : le cloud vérifie l'un ET l'autre.
+        origin_agent_id: entry.origin_agent_id ?? env.origin_sig.key_id,
+        // Renseignés par `signTransport` : ils dépendent de `base_rev`, connu seulement ici.
+        origin_sig: '',
+        origin_sig_payload_hash: '',
+        origin_signer_fingerprint: env.origin_sig.key_id,
+        meta,
+        // ── L'ENVELOPPE SIGNÉE, VERBATIM (dec#162) ──────────────────────────────────
+        //
+        // La signature de TRANSPORT ci-dessus prouve « cette opération s'applique à cette
+        // révision » ; elle ne prouve RIEN sur l'auteur du contenu. La signature d'AUTEUR
+        // (origin_sig sur meta‖sealed‖key_epoch, cf. buildEnvelope) est la seule qui le fasse —
+        // et `toWireBody` l'écrasait jusqu'ici en réutilisant le champ `origin_sig` pour le
+        // transport. Un lecteur (pull) ne pouvait donc pas vérifier qui a écrit l'enveloppe.
+        //
+        // On transporte l'enveloppe complète SANS LA TOUCHER. Le cloud la stocke telle quelle et
+        // la rend au pull ; le vérificateur y retrouve `origin_sig.value` d'auteur et
+        // recanonicalise meta/sealed lui-même (federation-inbound). Aucune donnée NOUVELLE ne
+        // fuit : `meta` partait déjà en clair au relais (ligne ci-dessus) — on ne fait que
+        // PERSISTER ce qui transitait déjà. Le champ n'entre pas dans la signature de transport :
+        // son intégrité est portée par la signature d'auteur qu'il contient.
+        envelope_json: JSON.stringify(entry.sealed),
+    };
+}
+/**
+ * Envoie les enveloppes en attente.
+ *
+ * REFUSE plutôt que de deviner : sans appairage actif, sans URL, la fonction lève. Pousser
+ * vers une adresse devinée enverrait des enveloppes chiffrées à un tiers — inintelligibles
+ * pour lui, mais c'est une fuite de métadonnées et de trafic, pas un non-événement.
+ */
+export async function pushPending(options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const doFetch = options.fetchImpl ?? fetch;
+    const result = { attempted: 0, sent: 0, conflicts: 0, failed: 0, errors: [] };
+    const state = loadConnectionState(cwd);
+    if (!state || state.enrollment.stage !== 'active') {
+        throw new Error('Aucun appairage actif : rien n\'est envoyé tant que l\'appairage n\'est pas confirmé localement.');
+    }
+    // MANQUE MESURÉ (2026-08-09) : `FederationConnectionState` ne persiste AUCUNE adresse de
+    // cloud — ni à la racine, ni dans `sync`. L'appairage prend `--url` puis l'oublie. Chaque
+    // commande doit donc la repasser. C'est un défaut d'ergonomie à corriger côté appairage,
+    // pas ici : deviner une adresse enverrait le trafic d'un projet à un tiers — illisible
+    // pour lui, mais une fuite de métadonnées et de trafic n'est pas un non-événement.
+    const base = (options.url ?? '').replace(/\/+$/, '');
+    if (!base) {
+        throw new Error('Adresse du cloud inconnue : passez --url. Elle n\'est pas conservée par l\'appairage ' +
+            '(état de connexion sans champ d\'URL), et aucune adresse n\'est devinée.');
+    }
+    const pending = list('pending', cwd);
+    // File vide = rien à signer : sortir AVANT de résoudre l'identité. Le signataire est
+    // déduit de la première entrée pending ; le chercher sur une file vide transformait
+    // « tout est déjà parti » en erreur d'identité — vécu le 2026-08-10, juste après un
+    // envoi complet dont il ne restait que des conflits.
+    if (pending.length === 0)
+        return result;
+    // L'identité SIGNATAIRE du transport : celle de l'agent qui a produit les enveloppes.
+    // Elle est portée par l'entrée d'outbox, donc le transport n'a pas à deviner qui signe.
+    const agentId = options.agentId ?? pending[0]?.origin_agent_id;
+    const identity = agentId ? loadAgentSigningKey(agentId) : undefined;
+    if (!identity) {
+        throw new Error('Identité de signature introuvable : le cloud vérifie une signature de TRANSPORT ' +
+            'liant envelope_id, rev et base_rev. Sans elle, chaque envoi est refusé en 422.');
+    }
+    const identityPem = identity.privateKeyPem;
+    const batch = options.limit ? pending.slice(0, options.limit) : pending;
+    result.attempted = batch.length;
+    if (options.dryRun)
+        return result;
+    const endpoint = `${base}/api/v1/projects/${state.cloud_project_id}/projection/envelopes`;
+    for (const entry of batch) {
+        try {
+            const wire = { ...toWireBody(entry), __project_id: state.cloud_project_id };
+            let signed = signTransport(wire, null, identityPem);
+            let res = await doFetch(endpoint, {
+                method: 'POST',
+                headers: authHeaders(entry.idempotency_key, options.apiKey),
+                body: JSON.stringify(signed),
+            });
+            // ── RECALAGE SUR 409, UNE SEULE FOIS ──────────────────────────────────
+            //
+            // Le cloud applique une concurrence optimiste : `base_rev` doit désigner la tête
+            // courante. Un émetteur qui n'a jamais poussé ne CONNAÎT pas cette tête — et la
+            // suivre localement dupliquerait un état dont le cloud est déjà l'autorité.
+            //
+            // Le refus la contient (`expected_base_rev`) : on renvoie donc une fois avec la
+            // valeur annoncée. UNE SEULE, délibérément : boucler transformerait un désaccord
+            // réel en écrasement silencieux du travail d'un autre appareil.
+            if (res.status === 409) {
+                const detail = (await res.clone().json().catch(() => ({})));
+                // `current_head_rev` est le nom que le serveur DÉPLOYÉ répond (projection.ts,
+                // REV_CONFLICT). Les deux autres sont des noms historiques gardés en repli.
+                // Dérive constatée le 2026-08-10 : le client lisait `expected_base_rev` sur une
+                // réponse qui ne l'a jamais porté — le recalage ne se déclenchait donc JAMAIS et
+                // chaque mise à jour finissait en conflit. Le test unitaire rejoue depuis la
+                // forme de réponse RÉELLE du serveur ; leçon dec#160/162, un contrat inter-
+                // services ne se vérifie que contre le service.
+                const expected = detail['current_head_rev'] ?? detail['expected_base_rev'] ?? detail['expected'];
+                if (typeof expected === 'string' || typeof expected === 'number') {
+                    // On RESIGNE avec la nouvelle base_rev : c'est précisément ce que la signature
+                    // au niveau du transport rend possible, et qu'une signature figée à l'émission
+                    // interdisait.
+                    signed = signTransport(wire, String(expected), identityPem);
+                    res = await doFetch(endpoint, {
+                        method: 'POST',
+                        headers: authHeaders(entry.idempotency_key, options.apiKey),
+                        body: JSON.stringify(signed),
+                    });
+                }
+            }
+            if (res.ok || res.status === 202) {
+                transition(entry.idempotency_key, 'pending', 'synced', cwd);
+                result.sent += 1;
+                continue;
+            }
+            if (res.status === 409) {
+                // Désaccord de révision : un renvoi à l'identique échouera pareil. L'entrée passe
+                // en `conflict` pour être VUE, pas retentée en boucle.
+                transition(entry.idempotency_key, 'pending', 'conflict', cwd, (e) => ({
+                    ...e,
+                    last_error: `409 conflit de révision (base_rev=${entry.base_rev})`,
+                }));
+                result.conflicts += 1;
+                result.errors.push({ idempotency_key: entry.idempotency_key, status: 409, reason: 'conflit de révision' });
+                continue;
+            }
+            const body = await res.text();
+            result.failed += 1;
+            result.errors.push({
+                idempotency_key: entry.idempotency_key,
+                status: res.status,
+                reason: body.slice(0, 200),
+            });
+            // RESTE en attente : un refus temporaire ne doit pas faire disparaître l'opération.
+            transition(entry.idempotency_key, 'pending', 'pending', cwd, (e) => ({
+                ...e,
+                attempts: e.attempts + 1,
+                last_error: `HTTP ${res.status}`,
+            }));
+        }
+        catch (err) {
+            const reason = err instanceof Error ? err.message : String(err);
+            result.failed += 1;
+            result.errors.push({ idempotency_key: entry.idempotency_key, reason });
+            transition(entry.idempotency_key, 'pending', 'pending', cwd, (e) => ({
+                ...e,
+                attempts: e.attempts + 1,
+                last_error: reason,
+            }));
+            logger.warn(`Envoi échoué (${entry.idempotency_key}) : ${reason}`);
+        }
+    }
+    return result;
+}
+//# sourceMappingURL=federation-push.js.map

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/core/protocol-tool-policy.js

@@ -48,6 +48,9 @@ export const MCP_HEADLESS_AUTO_TOOL_NAMES = [
     'bclaw_code_status',
     'bclaw_code_find',
     'bclaw_code_brief',
+    'bclaw_code_impact',
+    'bclaw_code_export',
+    'bclaw_code_outline',
     'bclaw_send_message',
     'bclaw_ack_message',
     'bclaw_write_note',