brainclaw 1.23.0 → 1.24.0

package/dist/core/federation-grant.js

@@ -0,0 +1,223 @@
+/**
+ * Remise attestée d'une clé privée d'epoch. Le Cloud relaie ce manifeste et
+ * son ciphertext sans pouvoir ouvrir l'un ou l'autre.
+ */
+import crypto from 'node:crypto';
+import { z } from 'zod';
+import { canonicalJson } from './federation-canonical.js';
+import { HPKE_SUITE, open as hpkeOpen, seal } from './federation-hpke.js';
+import { epochPublicKey, fingerprintKeyPem, loadDevicePrivateKey, loadEpochPrivateKey, storeEpochPrivateKey } from './federation-keyring.js';
+export const EPOCH_GRANT_SCHEMA = 'brainclaw.federation-epoch-grant/v1';
+export const EPOCH_GRANT_KIND = 'epoch_grant';
+export const EPOCH_GRANT_AAD_PROTOCOL = 'brainclaw/federation-epoch-grant/aad/v1';
+const Aad = z.object({
+    protocol: z.literal(EPOCH_GRANT_AAD_PROTOCOL),
+    cloud_project_id: z.string().min(1),
+    epoch: z.number().int().positive(),
+    target_device_id: z.string().min(1),
+    target_x25519_fingerprint: z.string().regex(/^[a-f0-9]{64}$/),
+    policy_revision: z.number().int().nonnegative(),
+    grant_id: z.string().min(1),
+}).strict();
+const Sealed = z.object({
+    alg: z.literal(HPKE_SUITE),
+    enc: z.string().min(1),
+    nonce: z.string().min(1),
+    ciphertext: z.string().min(1),
+}).strict();
+export const EpochGrantManifestSchema = z.object({
+    schema: z.literal(EPOCH_GRANT_SCHEMA),
+    kind: z.literal(EPOCH_GRANT_KIND),
+    grant_id: z.string().min(1),
+    cloud_project_id: z.string().min(1),
+    epoch: z.number().int().positive(),
+    policy_revision: z.number().int().nonnegative(),
+    target: z.object({
+        device_id: z.string().min(1),
+        x25519_fingerprint: z.string().regex(/^[a-f0-9]{64}$/),
+    }).strict(),
+    /** Le lecteur recompose cet AAD et le compare avant de déchiffrer. */
+    aad: Aad,
+    epoch_public_key_pem: z.string().min(1),
+    epoch_public_key_fingerprint: z.string().regex(/^[a-f0-9]{64}$/),
+    sealed: Sealed,
+    custodian_sig: z.object({
+        alg: z.literal('Ed25519'),
+        key_id: z.string().min(1),
+        value: z.string().min(1),
+    }).strict(),
+}).strict();
+export function epochGrantAad(params) {
+    return {
+        protocol: EPOCH_GRANT_AAD_PROTOCOL,
+        cloud_project_id: params.cloudProjectId,
+        epoch: params.epoch,
+        target_device_id: params.targetDeviceId,
+        target_x25519_fingerprint: params.targetX25519Fingerprint,
+        policy_revision: params.policyRevision,
+        grant_id: params.grantId,
+    };
+}
+export function epochGrantSigningInput(manifest) {
+    return Buffer.concat([
+        Buffer.from('brainclaw/federation-epoch-grant/v1\0', 'utf8'),
+        Buffer.from(canonicalJson(manifest), 'utf8'),
+    ]);
+}
+function unsigned(manifest) {
+    const { custodian_sig: _signature, ...value } = manifest;
+    return value;
+}
+function publicX25519(pem) {
+    let key;
+    try {
+        key = crypto.createPublicKey(pem);
+    }
+    catch {
+        throw new Error('Clé X25519 cible illisible.');
+    }
+    if (key.asymmetricKeyType !== 'x25519')
+        throw new Error('La cible doit fournir une clé X25519.');
+}
+function privateEd25519(pem) {
+    let key;
+    try {
+        key = crypto.createPrivateKey(pem);
+    }
+    catch {
+        throw new Error('Clé Ed25519 custodian illisible.');
+    }
+    if (key.asymmetricKeyType !== 'ed25519')
+        throw new Error('Le custodian doit signer en Ed25519.');
+    return key;
+}
+function normalizedPem(pem) { return pem.replace(/\r/g, '').trim(); }
+export function buildEpochGrant(params) {
+    if (!params.custodian.active)
+        throw new Error('Custodian inactif.');
+    if (!params.target.active || !params.target.attested || !params.target.canRead)
+        throw new Error('Cible non autorisée.');
+    if (!params.target.authorizedEpochs.includes(params.epoch))
+        throw new Error('Epoch hors horizon autorisé.');
+    if (!Number.isInteger(params.epoch) || params.epoch <= 0 || !Number.isInteger(params.policyRevision) || params.policyRevision < 0) {
+        throw new Error('Epoch ou révision de politique invalide.');
+    }
+    if (!params.cloudProjectId || !params.grantId || !params.target.deviceId)
+        throw new Error('Projet, grant_id ou cible absent.');
+    publicX25519(params.target.x25519PublicKeyPem);
+    const targetFingerprint = fingerprintKeyPem(params.target.x25519PublicKeyPem);
+    if (targetFingerprint !== params.target.x25519Fingerprint)
+        throw new Error('Empreinte cible différente de la clé attestée.');
+    const epochPrivate = loadEpochPrivateKey(params.cloudProjectId, params.epoch, params.home);
+    const announced = epochPublicKey(params.cloudProjectId, params.epoch, params.home);
+    if (!epochPrivate || !announced)
+        throw new Error('Custodian non détenteur de cet epoch.');
+    const aad = epochGrantAad({
+        cloudProjectId: params.cloudProjectId,
+        epoch: params.epoch,
+        grantId: params.grantId,
+        policyRevision: params.policyRevision,
+        targetDeviceId: params.target.deviceId,
+        targetX25519Fingerprint: targetFingerprint,
+    });
+    const sealed = seal({
+        recipientPublicKeyPem: params.target.x25519PublicKeyPem,
+        plaintext: new TextEncoder().encode(epochPrivate.export({ type: 'pkcs8', format: 'pem' }).toString()),
+        aadCanonicalBytes: new TextEncoder().encode(canonicalJson(aad)),
+    });
+    const value = {
+        schema: EPOCH_GRANT_SCHEMA,
+        kind: EPOCH_GRANT_KIND,
+        grant_id: params.grantId,
+        cloud_project_id: params.cloudProjectId,
+        epoch: params.epoch,
+        policy_revision: params.policyRevision,
+        target: { device_id: params.target.deviceId, x25519_fingerprint: targetFingerprint },
+        aad,
+        epoch_public_key_pem: announced.public_key_pem,
+        epoch_public_key_fingerprint: announced.fingerprint,
+        sealed,
+    };
+    const signature = crypto.sign(null, epochGrantSigningInput(value), privateEd25519(params.custodian.privateKeyPem)).toString('base64url');
+    return EpochGrantManifestSchema.parse({
+        ...value,
+        custodian_sig: { alg: 'Ed25519', key_id: params.custodian.keyId, value: signature },
+    });
+}
+function reject(reason, detail) {
+    return { ok: false, reason, detail };
+}
+function signatureValid(manifest, signer) {
+    try {
+        const key = crypto.createPublicKey(signer);
+        return key.asymmetricKeyType === 'ed25519'
+            && crypto.verify(null, epochGrantSigningInput(unsigned(manifest)), key, Buffer.from(manifest.custodian_sig.value, 'base64url'));
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * La clé n'est écrite qu'après roster custodian, signature, AAD, cible, HPKE et
+ * comparaison de la clé publique redérivée avec l'annonce signée.
+ */
+export function verifyAndStoreEpochGrant(params) {
+    const parsed = EpochGrantManifestSchema.safeParse(params.raw);
+    if (!parsed.success)
+        return reject('schema_invalid', parsed.error.issues.map((issue) => issue.message).join('; '));
+    const manifest = parsed.data;
+    const signer = params.activeCustodians.get(manifest.custodian_sig.key_id);
+    if (!signer)
+        return reject('non_custodian', 'Signataire absent des custodians actifs.');
+    if (!signatureValid(manifest, signer))
+        return reject('bad_signature', 'Signature Ed25519 invalide.');
+    const aad = epochGrantAad({
+        cloudProjectId: manifest.cloud_project_id,
+        epoch: manifest.epoch,
+        grantId: manifest.grant_id,
+        policyRevision: manifest.policy_revision,
+        targetDeviceId: manifest.target.device_id,
+        targetX25519Fingerprint: manifest.target.x25519_fingerprint,
+    });
+    if (canonicalJson(manifest.aad) !== canonicalJson(aad))
+        return reject('aad_mismatch', 'AAD différent des liaisons annoncées.');
+    if (manifest.target.device_id !== params.recipientDeviceId)
+        return reject('target_mismatch', 'Remise destinée à un autre appareil.');
+    const recipient = params.recipientPrivateKey ?? loadDevicePrivateKey(params.recipientDeviceId, params.home);
+    if (!recipient || recipient.asymmetricKeyType !== 'x25519')
+        return reject('recipient_key_unavailable', 'Clé X25519 destinataire absente.');
+    const recipientPublic = crypto.createPublicKey(recipient).export({ type: 'spki', format: 'pem' }).toString();
+    if (fingerprintKeyPem(recipientPublic) !== manifest.target.x25519_fingerprint)
+        return reject('target_mismatch', 'Clé locale différente de la cible attestée.');
+    const clear = hpkeOpen({
+        recipientPrivateKey: recipient,
+        sealed: manifest.sealed,
+        aadCanonicalBytes: new TextEncoder().encode(canonicalJson(aad)),
+    });
+    if (!clear)
+        return reject('undecryptable', 'HPKE a refusé la remise.');
+    let privatePem;
+    let derivedPublic;
+    try {
+        privatePem = new TextDecoder().decode(clear);
+        const epochPrivate = crypto.createPrivateKey(privatePem);
+        if (epochPrivate.asymmetricKeyType !== 'x25519')
+            throw new Error('non-X25519');
+        derivedPublic = crypto.createPublicKey(epochPrivate).export({ type: 'spki', format: 'pem' }).toString();
+    }
+    catch {
+        return reject('epoch_key_mismatch', 'Clair d’epoch invalide.');
+    }
+    if (normalizedPem(derivedPublic) !== normalizedPem(manifest.epoch_public_key_pem)
+        || fingerprintKeyPem(derivedPublic) !== manifest.epoch_public_key_fingerprint
+        || fingerprintKeyPem(manifest.epoch_public_key_pem) !== manifest.epoch_public_key_fingerprint)
+        return reject('epoch_key_mismatch', 'Clé publique redérivée différente de l’annonce.');
+    try {
+        storeEpochPrivateKey(manifest.cloud_project_id, manifest.epoch, privatePem, params.home);
+    }
+    catch (error) {
+        return reject('storage_refused', error instanceof Error ? error.message : String(error));
+    }
+    return { ok: true, manifest };
+}
+//# sourceMappingURL=federation-grant.js.map

package/dist/core/federation-keyring.js

@@ -238,4 +238,43 @@ export function epochPublicKey(cloudProjectId, epoch, home = os.homedir()) {
         .toString();
     return { public_key_pem: pem, fingerprint: fingerprintKeyPem(pem) };
 }
+/**
+ * Fait naître la PREMIÈRE clé d'epoch d'un projet, si et seulement si personne n'en détient.
+ *
+ * ── POURQUOI CETTE FONCTION MANQUAIT, ET CE QUE SON ABSENCE PRODUISAIT ────────
+ * Mesuré le 2026-08-09 : `storeEpochPrivateKey` n'avait AUCUN appelant de production — seuls
+ * les tests en fabriquaient. Un projet fraîchement appairé restait donc à `current_epoch: 0`
+ * avec `known_epochs: []`, et toute tentative de sceller échouait sur « clé d'epoch
+ * introuvable ». La fédération ne pouvait rien émettre, non par refus mais par absence de
+ * clé — un état qu'aucun message n'expliquait.
+ *
+ * ── QUI A LE DROIT DE CRÉER, ET POURQUOI C'EST ÉTROIT ─────────────────────────
+ * Le PREMIER appareil d'un projet, et lui seul. Un appareil qui rejoint un projet existant
+ * ne doit RIEN créer : il doit RECEVOIR la clé par une remise attestée (dec#159). En
+ * fabriquer une localement produirait un second epoch portant le même numéro et une clé
+ * différente — donc des enveloppes que personne d'autre ne peut lire, sans qu'aucune erreur
+ * ne se déclenche à l'émission.
+ *
+ * C'est le cas dégénéré du modèle d'équipe, pas une branche parallèle : en solo, le premier
+ * appareil est aussi le seul custodian.
+ *
+ * NE RÉÉCRIT JAMAIS : si une clé existe déjà pour cet epoch, elle est renvoyée telle quelle.
+ * `storeEpochPrivateKey` refuse de son côté d'écraser une clé DIFFÉRENTE.
+ */
+export function ensureFirstEpochKey(cloudProjectId, epoch, home = os.homedir()) {
+    const existing = epochPublicKey(cloudProjectId, epoch, home);
+    if (existing)
+        return { created: false, ...existing };
+    const { privateKey } = crypto.generateKeyPairSync('x25519');
+    const pem = privateKey.export({ type: 'pkcs8', format: 'pem' }).toString();
+    storeEpochPrivateKey(cloudProjectId, epoch, pem, home);
+    const materialized = epochPublicKey(cloudProjectId, epoch, home);
+    if (!materialized) {
+        // Vérifier APRÈS écriture plutôt que supposer : une clé qu'on croit détenir mais qui
+        // n'est pas relisible produirait des enveloppes illisibles, découvertes bien plus tard.
+        throw new Error(`Clé d'epoch ${epoch} écrite mais non relisible pour ${cloudProjectId} — ` +
+            'ne pas émettre tant que la cause n\'est pas comprise.');
+    }
+    return { created: true, ...materialized };
+}
 //# sourceMappingURL=federation-keyring.js.map

package/dist/core/federation-opaque-ids.js

@@ -0,0 +1,111 @@
+/**
+ * Correspondance id LOCAL ↔ id OPAQUE — et elle ne quitte jamais la machine (RFC §7).
+ *
+ * ── POURQUOI UNE TABLE PLUTÔT QU'UN HACHAGE ──────────────────────────────────
+ * Un id opaque doit être STABLE : sans stabilité, chaque émission créerait un nouvel objet
+ * côté cloud et le board afficherait un doublon par mise à jour. La tentation est donc de
+ * dériver l'opaque du local par un hachage — c'est reproductible et sans état.
+ *
+ * Mais un hachage NON CLEFÉ est réversible par devinette : le cloud connaît la forme des
+ * ids locaux (`pln_`, `dec_`, `trp_` + hexadécimal court), il lui suffit d'énumérer pour
+ * confirmer qu'un opaque correspond à `pln_5047fdb1`. Il apprendrait alors le compteur
+ * local, l'ordre de création, et le lien entre deux projets partageant un objet.
+ *
+ * Une table locale n'a pas ce défaut : l'opaque est un UUID v4 sans relation calculable
+ * avec le local. Le prix est un état à conserver — assumé, parce que le RFC pose déjà que
+ * la correspondance reste locale, et parce que la PERDRE n'est pas une catastrophe : on
+ * réémet sous de nouveaux opaques, ce qui duplique l'affichage sans rien divulguer.
+ *
+ * ── CE FICHIER NE SORT JAMAIS ────────────────────────────────────────────────
+ * Il contient exactement ce que la projection existe pour cacher : la liaison entre un
+ * objet du cloud et son identité locale. Il vit sous `.brainclaw/coordination/federation/`
+ * et n'est référencé par aucune enveloppe.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { memoryDir, writeFileAtomic } from './io.js';
+import { logger } from './logger.js';
+const MAP_FILE = 'opaque-ids.json';
+export const OPAQUE_MAP_SCHEMA = 'brainclaw.federation-opaque-map/v1';
+function mapPath(cwd) {
+    return path.join(memoryDir(cwd), 'coordination', 'federation', MAP_FILE);
+}
+function loadMap(cwd) {
+    const file = mapPath(cwd);
+    if (!fs.existsSync(file))
+        return { schema: OPAQUE_MAP_SCHEMA, entries: {} };
+    try {
+        const parsed = JSON.parse(fs.readFileSync(file, 'utf-8'));
+        if (parsed.schema !== OPAQUE_MAP_SCHEMA || typeof parsed.entries !== 'object' || !parsed.entries) {
+            // FAIL-CLOSED sur un fichier d'une autre forme : repartir d'une table vide
+            // RÉÉMETTRA sous de nouveaux opaques (doublons visibles), ce qui est bruyant mais
+            // sûr. Réutiliser une table mal comprise pourrait au contraire rattacher un objet à
+            // l'identité d'un autre.
+            logger.warn(`Table d'ids opaques d'une forme inconnue — ignorée : ${file}`);
+            return { schema: OPAQUE_MAP_SCHEMA, entries: {} };
+        }
+        return { schema: OPAQUE_MAP_SCHEMA, entries: parsed.entries };
+    }
+    catch (err) {
+        logger.warn(`Table d'ids opaques illisible (${err instanceof Error ? err.message : String(err)}) — ignorée.`);
+        return { schema: OPAQUE_MAP_SCHEMA, entries: {} };
+    }
+}
+/**
+ * Renvoie l'id opaque STABLE d'un objet local, en le créant à la première demande.
+ *
+ * La clé inclut le projet cloud : le même objet local projeté vers deux projets cloud
+ * distincts reçoit deux opaques différents. Sans cela, deux clouds pourraient recouper
+ * leurs tables et découvrir qu'ils regardent le même objet.
+ */
+export function opaqueIdFor(cloudProjectId, localId, cwd = process.cwd()) {
+    const map = loadMap(cwd);
+    const key = `${cloudProjectId}/${localId}`;
+    const existing = map.entries[key];
+    if (existing)
+        return existing;
+    const fresh = crypto.randomUUID();
+    map.entries[key] = fresh;
+    const file = mapPath(cwd);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    writeFileAtomic(file, `${JSON.stringify(map, null, 2)}\n`);
+    return fresh;
+}
+/** Résout l'identifiant local correspondant à un opaque reçu du cloud. */
+export function localIdForOpaque(cloudProjectId, opaqueId, cwd = process.cwd()) {
+    const prefix = `${cloudProjectId}/`;
+    for (const [key, value] of Object.entries(loadMap(cwd).entries)) {
+        if (key.startsWith(prefix) && value === opaqueId)
+            return key.slice(prefix.length);
+    }
+    return undefined;
+}
+/**
+ * Enregistre le sens inverse du mapping après la création canonique de l'objet local.
+ * Refuse une incohérence au lieu de rattacher un opaque au mauvais objet.
+ */
+export function rememberOpaqueId(cloudProjectId, localId, opaqueId, cwd = process.cwd()) {
+    const map = loadMap(cwd);
+    const key = `${cloudProjectId}/${localId}`;
+    const current = map.entries[key];
+    if (current && current !== opaqueId) {
+        throw new Error(`Correspondance opaque incohérente pour ${localId}.`);
+    }
+    const prefix = `${cloudProjectId}/`;
+    const inverse = Object.entries(map.entries).find(([entryKey, value]) => entryKey.startsWith(prefix) && value === opaqueId && entryKey !== key);
+    if (inverse)
+        throw new Error(`Opaque ${opaqueId} déjà rattaché à ${inverse[0].slice(prefix.length)}.`);
+    if (current === opaqueId)
+        return;
+    map.entries[key] = opaqueId;
+    const file = mapPath(cwd);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    writeFileAtomic(file, `${JSON.stringify(map, null, 2)}\n`);
+}
+/** Nombre de correspondances connues — utile au diagnostic, jamais projeté. */
+export function opaqueMapSize(cloudProjectId, cwd = process.cwd()) {
+    const prefix = `${cloudProjectId}/`;
+    return Object.keys(loadMap(cwd).entries).filter((k) => k.startsWith(prefix)).length;
+}
+//# sourceMappingURL=federation-opaque-ids.js.map

package/dist/core/federation-outbox-v2.js

@@ -76,7 +76,17 @@ export function transition(idempotencyKey, from, to, cwd = process.cwd(), mutate
             const entry = JSON.parse(fs.readFileSync(src, 'utf-8'));
             const next = mutate({ ...entry, updated_at: nowISO() });
             writeFileAtomic(dest, `${JSON.stringify(next, null, 2)}\n`);
-            fs.rmSync(src, { force: true });
+            // MISE À JOUR SUR PLACE — `from === to` est un cas LÉGITIME et non un no-op : c'est
+            // ainsi qu'un échec d'envoi incrémente `attempts` et enregistre `last_error` sans
+            // quitter la file d'attente.
+            //
+            // Sans cette garde, `src` et `dest` sont le MÊME chemin : on écrit le fichier puis on
+            // le SUPPRIME aussitôt. L'entrée disparaît exactement au moment où l'on voulait
+            // seulement noter que son envoi a échoué — donc l'opération jamais émise perd sa
+            // seule trace, et précisément lors de l'incident où elle compte.
+            // Trouvé par le test « un 500 laisse aussi en attente » (2026-08-09).
+            if (path.resolve(src) !== path.resolve(dest))
+                fs.rmSync(src, { force: true });
             return true;
         }
         catch (err) {
@@ -93,11 +103,31 @@ export function list(state, cwd = process.cwd()) {
     if (!fs.existsSync(dir))
         return [];
     const entries = [];
+    let legacy = 0;
     for (const name of fs.readdirSync(dir)) {
         if (!name.endsWith('.json'))
             continue;
         try {
-            entries.push(JSON.parse(fs.readFileSync(path.join(dir, name), 'utf-8')));
+            const parsed = JSON.parse(fs.readFileSync(path.join(dir, name), 'utf-8'));
+            // ── DÉBRIS v1 DANS LE MÊME RÉPERTOIRE ────────────────────────────────────
+            //
+            // dec#156 a abandonné le format v1 SANS migration — mais la v2 réutilise le même
+            // chemin sur disque, et les entrées v1 y sont restées. Elles n'ont ni `schema` ni
+            // `created_at` (leurs champs sont op/entity_type/enqueued_at/last_status).
+            //
+            // Sans ce filtre, le tri par `created_at` lève « Cannot read properties of
+            // undefined (reading 'localeCompare') » et `brainclaw cloud status` PLANTE —
+            // c'est-à-dire la toute première commande qu'on lance après un appairage réussi.
+            // Constaté sur un magasin réel portant 129 entrées v1 (2026-08-09).
+            //
+            // Elles sont IGNORÉES, pas supprimées : ce sont des opérations peut-être jamais
+            // émises, et les effacer ici retirerait leur seule trace. Le compte est journalisé
+            // pour que leur présence reste visible plutôt que devinée.
+            if (parsed.schema !== OUTBOX_ENTRY_SCHEMA || typeof parsed.created_at !== 'string') {
+                legacy += 1;
+                continue;
+            }
+            entries.push(parsed);
         }
         catch {
             // Une entrée corrompue est ignorée à la lecture mais reste sur disque : la
@@ -105,6 +135,10 @@ export function list(state, cwd = process.cwd()) {
             logger.warn(`Entrée d'outbox ignorée (illisible) : ${name}`);
         }
     }
+    if (legacy > 0) {
+        logger.warn(`${legacy} entrée(s) d'outbox au format v1 ignorée(s) dans « ${STATE_DIRS[state]} » — ` +
+            `abandonnées par dec#156, conservées sur disque, sans effet sur la fédération v2.`);
+    }
     return entries.sort((a, b) => a.created_at.localeCompare(b.created_at));
 }
 /**

package/dist/core/federation-pairing.js

@@ -25,8 +25,9 @@ import crypto from 'node:crypto';
 import { nowISO } from './ids.js';
 import { loadAgentSigningKey, ensureAgentSigningKey } from './agent-registry.js';
 import { buildKeyAttestation, fingerprintPem } from './federation-attestation.js';
-import { ensureDeviceKey, } from './federation-keyring.js';
-import { createConnectionState, loadConnectionState, saveConnectionState, newDeviceId, } from './federation-state.js';
+import { ensureDeviceKey, ensureFirstEpochKey, } from './federation-keyring.js';
+import { logger } from './logger.js';
+import { createConnectionState, loadConnectionState, saveConnectionState, upsertPairing, hasActivePairing, newDeviceId, } from './federation-state.js';
 export class PairingError extends Error {
     stage;
     status;
@@ -84,7 +85,25 @@ export async function beginPairing(params) {
     }
     // (3) LA CLÉ DE CHIFFREMENT DE L'APPAREIL. Distincte de l'identité, jamais dérivée
     // d'elle (RFC §5.1) — c'est ce qui rend « écrire sans lire » possible.
-    const deviceId = params.deviceId ?? newDeviceId();
+    //
+    // MULTI-AGENTS : si un appairage existe déjà pour CE projet cloud, on RÉUTILISE son
+    // appareil (dec#161) — les agents d'une même machine partagent une clé de chiffrement.
+    // Générer un nouveau device par agent multiplierait les clés de déchiffrement sans
+    // raison, et exigerait une remise d'epoch par device au lieu de par machine.
+    const existing = loadConnectionState(cwd);
+    const sameProject = existing && existing.cloud_project_id === cloudProjectId;
+    if (existing && !sameProject) {
+        throw new PairingError(`Ce workspace est déjà appairé au projet ${existing.cloud_project_id} ; un workspace ne ` +
+            'peut pas être lié à deux projets cloud. Utilisez un autre répertoire.', 'claim');
+    }
+    // Ne refuser QUE si l'agent est déjà ACTIF — là il n'y a rien à faire. Un pairing
+    // `pending`/`attested` est une cérémonie interrompue : la relancer est une REPRISE
+    // légitime (nouvelle invitation, nouveau enrollment_id), et upsertPairing remplace
+    // proprement l'ancien enregistrement de cet agent.
+    if (sameProject && existing.pairings.some((p) => p.agent_id === params.agentId && p.stage === 'active')) {
+        throw new PairingError(`L'agent '${params.agentId}' est déjà appairé et actif sur ce workspace. Rien à faire.`, 'claim');
+    }
+    const deviceId = params.deviceId ?? (sameProject ? existing.device.device_id : newDeviceId());
     const device = ensureDeviceKey(deviceId);
     // (4) PREUVE DE POSSESSION + ATTESTATION, EN UN SEUL ACTE. Les deux signatures sont
     // produites par la MÊME clé d'identité : c'est ce lien qui interdit à quiconque
@@ -126,12 +145,18 @@ export async function beginPairing(params) {
         // porteur reste exigé — `recoveryReadiness` continue de refuser tant qu'il manque.
         recovery: true,
     };
-    const state = createConnectionState({
-        cloudProjectId,
-        device: deviceRecord,
-        workspacePath: cwd,
-        enrollmentId,
-    });
+    // AJOUT, pas écrasement (trp#1625). Sur un projet déjà appairé, on greffe le pairing du
+    // nouvel agent sur l'état existant — device et epochs conservés. Sinon, création.
+    const pairing = {
+        agent_id: params.agentId,
+        stage: 'pending',
+        enrollment_id: enrollmentId,
+        updated_at: nowISO(),
+    };
+    const base = sameProject
+        ? existing
+        : createConnectionState({ cloudProjectId, device: deviceRecord, workspacePath: cwd, enrollmentId, agentId: params.agentId });
+    const state = sameProject ? upsertPairing(existing, pairing) : base;
     saveConnectionState(state, cwd);
     return {
         enrollment_id: enrollmentId,
@@ -148,7 +173,12 @@ export async function beginPairing(params) {
  * (RFC §5.2 phase 4) ; cette fonction ne fait que lire un état de cérémonie.
  */
 export async function checkPairingApproval(params) {
-    const res = await params.transport.get(`/api/v1/enrollments/${params.enrollmentId}`);
+    // `/status` et non la route complète : l'agent en cours d'appairage n'a NI JWT NI clé
+    // d'API — il n'en obtient une qu'une fois approuvé. Interroger `GET /enrollments/:id`
+    // (withUserAuth) échouait donc sur « Missing API key » juste après une preuve de
+    // possession réussie, laissant la cérémonie à un pas de la fin (constaté en production
+    // le 2026-08-10). `/status` est public et ne rend que l'état du cycle de vie.
+    const res = await params.transport.get(`/api/v1/enrollments/${params.enrollmentId}/status`);
     if (res.status !== 200) {
         throw new PairingError(describeError(res.body, "l'état de l'enrôlement n'a pas pu être lu"), 'poll', res.status);
     }
@@ -169,9 +199,54 @@ export function completePairing(params) {
     if (!state) {
         throw new PairingError("Aucun état d'appairage local — relancer `brainclaw cloud connect`.", 'complete');
     }
+    // Le pairing à activer : celui de l'enrôlement nommé, sinon le miroir courant (solo).
+    const targetEnrollmentId = params.enrollmentId ?? state.enrollment.enrollment_id;
+    const target = state.pairings.find((p) => p.enrollment_id === targetEnrollmentId);
+    if (!target) {
+        throw new PairingError(`Aucun pairing en attente pour l'enrôlement ${String(targetEnrollmentId)} — relancer \`cloud connect\`.`, 'complete');
+    }
+    // La genèse d'epoch ne joue que si AUCUN pairing n'était encore actif : c'est le PREMIER
+    // agent du premier appareil. Un second agent sur le même appareil hérite de l'epoch déjà
+    // détenu — regénérer produirait un epoch concurrent (dec#161). `ensureFirstEpochKey`
+    // reste idempotent en dernier recours, mais la condition dit l'intention.
+    const firstEverActivation = !hasActivePairing(state);
+    // ── GENÈSE DE LA PREMIÈRE CLÉ D'EPOCH ───────────────────────────────────────
+    //
+    // Sans elle, l'appairage s'achevait sur `current_epoch: 0` et `known_epochs: []` : le
+    // projet était « actif » et incapable de sceller quoi que ce soit, échouant sur « clé
+    // d'epoch introuvable » sans qu'aucun message n'explique pourquoi. Mesuré le 2026-08-09 —
+    // `storeEpochPrivateKey` n'avait aucun appelant de production.
+    //
+    // SEUL LE PREMIER APPAREIL crée. Un appareil qui rejoint un projet existant doit RECEVOIR
+    // la clé par une remise attestée (dec#159) : en fabriquer une localement produirait un
+    // second epoch au même numéro avec une clé différente, donc des enveloppes que personne
+    // d'autre ne peut lire — et aucune erreur ne se déclencherait à l'émission.
+    //
+    // `peer_devices` vide est le signal disponible ici. Il est FAIBLE : un cloud hostile peut
+    // prétendre qu'un projet peuplé est vide pour pousser ce client à forger un epoch
+    // concurrent. Le roster signé de dec#159 est ce qui fermera ce trou ; en attendant, la
+    // limite est nommée plutôt que tue.
+    const isFirstDevice = (state.peer_devices?.length ?? 0) === 0;
+    const doGenesis = firstEverActivation && isFirstDevice;
+    const epoch = state.keys.current_epoch > 0 ? state.keys.current_epoch : 1;
+    let knownEpochs = state.keys.known_epochs;
+    if (doGenesis) {
+        const key = ensureFirstEpochKey(state.cloud_project_id, epoch);
+        if (key.created) {
+            logger.info(`Epoch ${epoch} créé pour ce projet — empreinte ${key.fingerprint}`);
+        }
+        knownEpochs = knownEpochs.includes(epoch) ? knownEpochs : [...knownEpochs, epoch];
+    }
+    // Active le pairing ciblé via upsertPairing (qui maintient le miroir `enrollment`).
+    const activated = upsertPairing(state, {
+        ...target,
+        stage: 'active',
+        role: params.role ?? target.role,
+        updated_at: nowISO(),
+    });
     const next = {
-        ...state,
-        enrollment: { ...state.enrollment, stage: 'active', role: params.role ?? state.enrollment.role, updated_at: nowISO() },
+        ...activated,
+        keys: { current_epoch: doGenesis ? epoch : state.keys.current_epoch, known_epochs: knownEpochs },
     };
     saveConnectionState(next, cwd);
     return next;