brainclaw 1.20.4 → 1.22.0

package/dist/core/federation-relay.js

@@ -0,0 +1,223 @@
+/**
+ * Commandes cloud matérialisées localement — le RELAIS (pln#651 étape 7, dec#154).
+ *
+ * ── CE QUI SURVIT INTACT AU CHIFFREMENT ───────────────────────────────────────
+ * À écrire d'emblée, pour qu'on ne « résolve » pas un faux problème : `base_rev` compare
+ * un IDENTIFIANT DE RÉVISION, pas du contenu. L'idempotence, `operation_id`, la
+ * provenance et l'audit ne référencent que des ids et des actions. Rien de tout cela n'a
+ * besoin de lire le clair, et le chiffrement ne gêne donc en rien ce module.
+ *
+ * LE RELAIS N'ÉCRIT JAMAIS DE CONTENU. Le contenu reste en écriture depuis le local
+ * uniquement. Une commande venue du dashboard porte sur des MÉTADONNÉES : priorité,
+ * ordre, rang, statut, métadonnées de roadmap. C'est la conséquence directe de dec#154 —
+ * « le Cloud est une projection et un relais ; le local est la source de vérité ».
+ *
+ * ── LA TROISIÈME CLASSE D'APPELANTS (dec#155) ─────────────────────────────────
+ * Le relais cloud n'a NI session, NI cwd, NI contexte ambiant : seulement un id d'entité
+ * et un `base_rev`. C'est le cas le plus pur du routage autoritatif par l'entité, déjà en
+ * place côté core depuis la 1.21.0.
+ *
+ * NE PAS RÉINVENTER DE RÉSOLUTION AMBIANTE POUR LUI. La tentation est réelle — « si le
+ * projet n'est pas précisé, prendre le projet actif » — et c'est exactement la dérive que
+ * pln#648/649 ont corrigée pour le routage local. Une commande sans cible résoluble est
+ * REFUSÉE, jamais devinée.
+ *
+ * ── LES CONFLITS ──────────────────────────────────────────────────────────────
+ * Présentés avec une proposition de résolution, JAMAIS de last-write-wins silencieux. Et
+ * c'est le contrat de refus de T3 exprimé sur un autre transport : une divergence PROUVÉE
+ * refuse et nomme ; une ABSENCE retombe sur la réponse ambiante. Le même mécanisme, pas
+ * un second.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { z } from 'zod';
+import { memoryDir, writeFileAtomic } from './io.js';
+import { nowISO } from './ids.js';
+import { canonicalJson } from './federation-canonical.js';
+import { logger } from './logger.js';
+const JOURNAL_DIR = ['coordination', 'federation', 'commands'];
+/**
+ * Les seuls champs qu'une commande cloud peut toucher.
+ *
+ * LISTE FERMÉE ET NON EXTENSIBLE PAR CONFIGURATION : c'est la traduction exécutable de
+ * « le relais n'écrit jamais de contenu ». Ajouter `text` ou `description` ici ferait du
+ * Cloud une source d'écriture de contenu et retournerait dec#154.
+ */
+export const RELAYABLE_FIELDS = ['priority', 'rank', 'status'];
+export const CloudCommandSchema = z.object({
+    /** Identité de l'opération, créée par l'émetteur et REJOUÉE à l'identique en cas de retry. */
+    operation_id: z.string().min(1),
+    /** Cible : un id d'entité opaque. Pas de projet, pas de cwd, pas de session (dec#155). */
+    object_id: z.string().min(1),
+    /** Révision sur laquelle l'émetteur s'appuie. Un décalage produit un conflit VISIBLE. */
+    base_rev: z.number().int().nonnegative(),
+    field: z.enum(RELAYABLE_FIELDS),
+    value: z.union([z.string(), z.number()]),
+    /** Identité Ed25519 de l'émetteur — audité, pas cru sur parole. */
+    issued_by: z.string().min(1),
+    issued_at: z.string().min(1),
+}).strict();
+function journalDir(cwd) {
+    return path.join(memoryDir(cwd), ...JOURNAL_DIR);
+}
+/**
+ * Le journal est indexé par `operation_id` — c'est ce qui rend le rejeu inoffensif.
+ *
+ * Un index par (object_id, base_rev) ne suffirait pas : deux commandes distinctes peuvent
+ * légitimement viser la même révision d'un même objet (changer la priorité, puis le rang).
+ */
+function entryPath(cwd, operationId) {
+    // Le nom de fichier est assaini : un operation_id venu du réseau ne doit pas pouvoir
+    // écrire hors du répertoire du journal via '../'.
+    const safe = operationId.replace(/[^A-Za-z0-9_.-]/g, '_');
+    return path.join(journalDir(cwd), `${safe}.json`);
+}
+export function loadJournalEntry(cwd, operationId) {
+    const filepath = entryPath(cwd, operationId);
+    if (!fs.existsSync(filepath))
+        return undefined;
+    try {
+        return JSON.parse(fs.readFileSync(filepath, 'utf-8'));
+    }
+    catch (err) {
+        // Une entrée illisible n'est PAS traitée comme absente : la traiter ainsi ferait
+        // réappliquer une commande déjà appliquée, ce que tout ce module cherche à empêcher.
+        logger.warn(`Entrée de journal illisible (${operationId}) : ${err instanceof Error ? err.message : String(err)}`);
+        // `cause` conservée : sans elle, un opérateur voit « journal corrompu » sans savoir
+        // si c'est un JSON tronqué, un encodage cassé ou un disque plein.
+        throw new Error(`Journal corrompu pour l'opération ${operationId} — refus d'appliquer à l'aveugle.`, { cause: err });
+    }
+}
+function writeEntry(cwd, entry) {
+    const filepath = entryPath(cwd, entry.operation_id);
+    fs.mkdirSync(path.dirname(filepath), { recursive: true });
+    writeFileAtomic(filepath, `${JSON.stringify(entry, null, 2)}\n`);
+}
+/**
+ * Applique une commande cloud au journal local.
+ *
+ * `resolveLocalRev` est INJECTÉ plutôt que lu ici : ce module ne connaît pas le stockage
+ * des entités, et lui donner cette connaissance en ferait un second chemin d'écriture sur
+ * la mémoire — précisément ce que « le relais n'écrit jamais de contenu » interdit. Il
+ * écrit le journal ; c'est l'appelant qui, à partir du journal, applique un changement de
+ * métadonnée par la voie locale normale.
+ *
+ * TROIS ISSUES ET AUCUN ÉCRASEMENT SILENCIEUX :
+ *   applied   — base_rev correspond, l'effet est enregistré ;
+ *   duplicate — operation_id déjà connu, aucun second effet (idempotence) ;
+ *   conflict  — base_rev périmé : l'entrée est écrite en état `conflict` AVEC une
+ *               proposition, et attend une décision humaine.
+ */
+export function applyCloudCommand(params) {
+    const parsed = CloudCommandSchema.safeParse(params.raw);
+    if (!parsed.success) {
+        return { status: 'refused', reason: `commande invalide : ${parsed.error.issues.map((i) => i.path.join('.')).join(', ')}` };
+    }
+    const cmd = parsed.data;
+    // IDEMPOTENCE D'ABORD. Rejouer une commande déjà appliquée doit être un no-op, y compris
+    // si la révision locale a changé entre-temps — sinon un retry réseau produirait un
+    // conflit fantôme sur une opération pourtant déjà réussie.
+    const existing = loadJournalEntry(params.cwd, cmd.operation_id);
+    if (existing) {
+        return { status: 'duplicate', entry: existing };
+    }
+    const localRev = params.resolveLocalRev(cmd.object_id);
+    if (localRev === undefined) {
+        // TROISIÈME CLASSE D'APPELANTS (dec#155) : pas de repli ambiant. Un objet inconnu est
+        // refusé et nommé, jamais rattaché au « projet actif » par défaut.
+        return { status: 'refused', reason: `objet '${cmd.object_id}' inconnu localement — aucune résolution ambiante pour le relais cloud (dec#155).` };
+    }
+    const base = {
+        operation_id: cmd.operation_id,
+        object_id: cmd.object_id,
+        base_rev: cmd.base_rev,
+        field: cmd.field,
+        value: cmd.value,
+        issued_by: cmd.issued_by,
+        issued_at: cmd.issued_at,
+        materialized_at: nowISO(),
+    };
+    if (cmd.base_rev !== localRev) {
+        // CONFLIT VISIBLE, jamais un écrasement. La proposition est formulée ici parce que
+        // c'est ici qu'on connaît les deux révisions ; la rendre plus tard obligerait
+        // l'interface à re-déduire ce que le journal savait déjà.
+        const entry = {
+            ...base,
+            state: 'conflict',
+            conflict: {
+                local_rev: localRev,
+                proposal: localRev > cmd.base_rev
+                    ? `Le local a avancé (rév. ${localRev} > ${cmd.base_rev}). Rejouer la commande sur la révision ${localRev}, ou l'abandonner si le changement local la rend caduque.`
+                    : `La commande s'appuie sur une révision (${cmd.base_rev}) postérieure au local (${localRev}) — le local a probablement été restauré. Vérifier avant d'appliquer.`,
+            },
+        };
+        writeEntry(params.cwd, entry);
+        return { status: 'conflict', entry };
+    }
+    const entry = { ...base, state: 'pending' };
+    writeEntry(params.cwd, entry);
+    return { status: 'applied', entry };
+}
+/** Marque une entrée synchronisée une fois l'effet local réellement appliqué. */
+export function markCommandSynced(cwd, operationId) {
+    const entry = loadJournalEntry(cwd, operationId);
+    if (!entry)
+        return false;
+    writeEntry(cwd, { ...entry, state: 'synced' });
+    return true;
+}
+/**
+ * Résout un conflit par une DÉCISION EXPLICITE.
+ *
+ * Il n'existe volontairement aucune résolution automatique : dec#154 dit « jamais de
+ * last-write-wins silencieux », et un mode « auto » finirait par être le défaut.
+ */
+export function resolveCommandConflict(params) {
+    const entry = loadJournalEntry(params.cwd, params.operationId);
+    if (!entry || entry.state !== 'conflict')
+        return undefined;
+    const resolved = {
+        ...entry,
+        state: params.decision === 'accept' ? 'pending' : 'synced',
+        conflict: undefined,
+    };
+    writeEntry(params.cwd, resolved);
+    return resolved;
+}
+/** Entrées du journal dans un état donné — sert à rendre les conflits visibles. */
+export function listCommands(cwd, state) {
+    const dir = journalDir(cwd);
+    if (!fs.existsSync(dir))
+        return [];
+    const out = [];
+    for (const name of fs.readdirSync(dir)) {
+        if (!name.endsWith('.json'))
+            continue;
+        try {
+            const entry = JSON.parse(fs.readFileSync(path.join(dir, name), 'utf-8'));
+            if (!state || entry.state === state)
+                out.push(entry);
+        }
+        catch {
+            logger.warn(`Entrée de journal ignorée (illisible) : ${name}`);
+        }
+    }
+    return out.sort((a, b) => a.materialized_at.localeCompare(b.materialized_at));
+}
+/**
+ * Empreinte d'audit d'une commande — ce qui a été demandé, par qui, sur quelle révision.
+ *
+ * Calculée sur les octets CANONIQUES pour qu'elle soit reproductible des deux côtés : un
+ * audit qu'on ne peut pas recalculer identiquement ne prouve rien.
+ */
+export function commandAuditDigest(cmd) {
+    return canonicalJson({
+        operation_id: cmd.operation_id,
+        object_id: cmd.object_id,
+        base_rev: cmd.base_rev,
+        field: cmd.field,
+        value: cmd.value,
+        issued_by: cmd.issued_by,
+    });
+}
+//# sourceMappingURL=federation-relay.js.map

package/dist/core/federation-state.js

@@ -0,0 +1,270 @@
+/**
+ * Fédération v2 — état local de connexion (pln#651 étape 3).
+ *
+ * Création propre, AUCUNE migration (dec#156) : ce module ne lit ni `cloud_sync` ni
+ * `BRAINCLAW_CLOUD_*`. Le chemin v1 a été démoli en étape 2, et le défaut vivant qu'il
+ * portait — la SEULE PRÉSENCE d'une variable d'environnement valant consentement au
+ * sync — ne doit pas se reconstituer ici. Le consentement est un fichier écrit par une
+ * cérémonie d'appairage explicite (étape 4), rien d'autre.
+ *
+ * ── OÙ VIT QUOI, ET POURQUOI ──────────────────────────────────────────────────
+ *   `.brainclaw/coordination/federation/connection.json`  (workspace, ce module)
+ *       Le lien workspace ↔ cloud_project_id, l'identité d'appareil PUBLIQUE, les
+ *       epochs connus, la position de sync, les états visibles. AUCUN SECRET.
+ *
+ *   `~/.brainclaw/keys/`                                   (federation-keyring.ts)
+ *       Les clés privées. Hors du store, parce qu'un store de workspace se copie,
+ *       se synchronise et — dans d'autres projets que celui-ci — se committe.
+ *
+ * La frontière est vérifiée par un test, pas seulement par cette phrase : le pack de
+ * l'étape 8 injecte une sentinelle et exige qu'aucun octet de clé privée n'atteigne
+ * `.brainclaw/`.
+ *
+ * ── LES TROIS ÉTATS SONT UNE EXIGENCE, PAS UN CONFORT (dec#154) ───────────────
+ * « Le Cloud est une projection et un relais ; le local est la source de vérité. » Une
+ * opération venue du Cloud se matérialise dans le journal local AVEC UN ÉTAT VISIBLE :
+ * pending / synced / conflict. Un état invisible transformerait le relais en autorité
+ * silencieuse — exactement ce que dec#154 refuse.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { memoryDir, writeFileAtomic } from './io.js';
+import { generateId, nowISO } from './ids.js';
+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';
+/** Nombre d'appareils de récupération exigés avant la première enveloppe (RFC §5.3). */
+export const REQUIRED_RECOVERY_DEVICES = 2;
+// ── Emplacement ───────────────────────────────────────────────────────────────
+export function connectionStatePath(cwd = process.cwd()) {
+    return path.join(memoryDir(cwd), 'coordination', 'federation', CONNECTION_FILE);
+}
+// ── Lecture ───────────────────────────────────────────────────────────────────
+/**
+ * Charge l'état de connexion, ou `undefined` si le workspace n'est pas appairé.
+ *
+ * FAIL-CLOSED SUR ÉTAT ILLISIBLE : un JSON corrompu renvoie `undefined` et journalise,
+ * il ne renvoie PAS un état par défaut. Un défaut fabriqué ferait croire à un appairage
+ * avec un `current_epoch` de 0, et l'appelant tenterait de sceller sous une clé
+ * inexistante. « Pas appairé » est une réponse sûre ; « appairé, epoch 0 » ne l'est pas.
+ */
+export function loadConnectionState(cwd = process.cwd()) {
+    const filepath = connectionStatePath(cwd);
+    if (!fs.existsSync(filepath))
+        return undefined;
+    let raw;
+    try {
+        raw = JSON.parse(fs.readFileSync(filepath, 'utf-8'));
+    }
+    catch (err) {
+        logger.warn(`État de connexion fédération illisible (${filepath}): ${err instanceof Error ? err.message : String(err)}`);
+        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}).`);
+        return undefined;
+    }
+    return normalizeState(state, cwd);
+}
+/**
+ * Réconcilie l'état déclaré avec le DISQUE.
+ *
+ * `known_epochs` dit ce que l'appareil croit détenir ; `heldEpochs()` lit ce qu'il
+ * détient réellement. Le désaccord n'est pas théorique : une restauration partielle de
+ * sauvegarde, ou un `disconnect` interrompu, produit exactement cela. Faire confiance au
+ * JSON conduirait à tenter un déchiffrement sous une clé absente et à rendre l'erreur au
+ * mauvais endroit — loin de la cause.
+ */
+function normalizeState(state, cwd) {
+    const onDisk = heldEpochs(state.cloud_project_id);
+    const declared = state.keys?.known_epochs ?? [];
+    const missing = declared.filter((e) => !onDisk.includes(e));
+    if (missing.length > 0) {
+        logger.warn(`Trousseau incomplet pour ${state.cloud_project_id} : epoch(s) ${missing.join(', ')} déclaré(s) ` +
+            `mais absent(s) de ~/.brainclaw/keys/. Ces révisions ne sont pas déchiffrables sur cet appareil.`);
+    }
+    return {
+        ...state,
+        workspace_path: state.workspace_path ?? path.resolve(cwd),
+        peer_devices: state.peer_devices ?? [],
+        keys: {
+            current_epoch: state.keys?.current_epoch ?? 0,
+            // Le disque fait autorité sur ce qui est LISIBLE.
+            known_epochs: onDisk,
+        },
+        sync: {
+            feed_cursor: state.sync?.feed_cursor,
+            high_water: state.sync?.high_water ?? {},
+            last_pull_at: state.sync?.last_pull_at,
+            last_push_at: state.sync?.last_push_at,
+        },
+        counters: {
+            pending: state.counters?.pending ?? 0,
+            synced: state.counters?.synced ?? 0,
+            conflict: state.counters?.conflict ?? 0,
+        },
+    };
+}
+// ── Écriture ──────────────────────────────────────────────────────────────────
+/**
+ * Persiste l'état de connexion de façon atomique.
+ *
+ * REFUSE D'ÉCRIRE UN SECRET : le contrôle ci-dessous n'est pas de la paranoïa décorative.
+ * `{...state, private_key}` compile, et une clé privée sérialisée dans un fichier du
+ * store serait ensuite copiée par tout ce qui copie un store. C'est le même raisonnement
+ * que les trois filets de l'étape 5 : le typage TypeScript est une BORNE INFÉRIEURE, pas
+ * une garantie d'exécution — chaque clé présente à l'exécution est sérialisée.
+ */
+export function saveConnectionState(state, cwd = process.cwd()) {
+    assertNoSecret(state);
+    const next = { ...state, updated_at: nowISO() };
+    const filepath = connectionStatePath(cwd);
+    fs.mkdirSync(path.dirname(filepath), { recursive: true });
+    writeFileAtomic(filepath, `${JSON.stringify(next, null, 2)}\n`);
+}
+const SECRET_MARKERS = ['PRIVATE KEY', 'BEGIN OPENSSH', 'BEGIN RSA', 'BEGIN EC PARAMETERS'];
+/**
+ * Refuse tout état contenant du matériel de clé privée, quel que soit le NOM du champ.
+ *
+ * Le contrôle porte sur le CONTENU sérialisé et non sur une liste de champs interdits :
+ * une liste de noms ne rattrape pas un champ ajouté demain, alors qu'un PEM privé porte
+ * toujours son en-tête. C'est le même choix que le filet 2 de l'étape 5 — fail-closed sur
+ * ce qui sort, pas allowlist sur ce qu'on a pensé à interdire.
+ */
+function assertNoSecret(state) {
+    const serialized = JSON.stringify(state);
+    for (const marker of SECRET_MARKERS) {
+        if (serialized.includes(marker)) {
+            throw new Error(`Refus d'écrire l'état de connexion : du matériel de clé privée ('${marker}') s'y trouve. ` +
+                `Les secrets vont dans ~/.brainclaw/keys/ via federation-keyring.ts, jamais dans le store de workspace.`);
+        }
+    }
+}
+/**
+ * Crée l'état de connexion initial d'un workspace fraîchement appairé.
+ *
+ * `stage: 'pending'` et non `'active'` : créer l'état ne vaut pas approbation. Le passage
+ * à `active` appartient à la cérémonie de l'étape 4, après preuve de possession ET
+ * approbation humaine. Un état créé optimiste rejouerait le défaut de la v1 — un artefact
+ * local suffisant à déclencher du sync.
+ */
+export function createConnectionState(params) {
+    const now = nowISO();
+    return {
+        schema: FEDERATION_STATE_SCHEMA,
+        cloud_project_id: params.cloudProjectId,
+        workspace_path: path.resolve(params.workspacePath ?? process.cwd()),
+        enrollment: { stage: 'pending', enrollment_id: params.enrollmentId, updated_at: now },
+        device: params.device,
+        peer_devices: [],
+        // 0 = « aucun epoch » et non « premier epoch ». Le premier epoch remis est le 1 ;
+        // sceller sous l'epoch 0 doit être impossible, pas silencieusement plausible.
+        keys: { current_epoch: 0, known_epochs: [] },
+        sync: { high_water: {} },
+        counters: { pending: 0, synced: 0, conflict: 0 },
+        created_at: now,
+        updated_at: now,
+    };
+}
+/**
+ * Identifiant d'appareil, indépendant de l'identité d'agent (RFC §5.1).
+ *
+ * Un agent peut tourner sur plusieurs machines et une machine porter plusieurs agents ;
+ * c'est l'APPAREIL qui détient une clé de déchiffrement et qu'on révoque en cas de perte.
+ * Réutiliser l'agent_id ferait qu'une révocation coupe l'agent partout à la fois.
+ */
+export function newDeviceId() {
+    return generateId('federation_devices');
+}
+// ── Anti-rejeu ────────────────────────────────────────────────────────────────
+/**
+ * Décide si une révision entrante est acceptable pour un objet donné.
+ *
+ * STRICTEMENT SUPÉRIEURE (RFC §6.5) : l'égalité est refusée ici, et le dédoublonnage
+ * d'une enveloppe déjà connue se fait par `idempotency_key` à l'étape 6 — deux
+ * mécanismes distincts pour deux questions distinctes. Confondre les deux ferait
+ * accepter un rejeu de même révision porteur d'un contenu différent.
+ */
+export function acceptsRevision(state, objectId, incomingRev) {
+    const seen = state.sync.high_water[objectId];
+    return seen === undefined || incomingRev > seen;
+}
+/** Avance la barrière anti-rejeu. Ne régresse JAMAIS, même si l'appelant le demande. */
+export function recordRevision(state, objectId, rev) {
+    const seen = state.sync.high_water[objectId];
+    if (seen !== undefined && rev <= seen)
+        return state;
+    return { ...state, sync: { ...state.sync, high_water: { ...state.sync.high_water, [objectId]: rev } } };
+}
+/**
+ * Un projet ne peut émettre sa PREMIÈRE enveloppe v2 qu'après l'enrôlement de deux
+ * appareils de récupération indépendamment attestés (RFC §5.3).
+ *
+ * POURQUOI CETTE PORTE EXISTE ICI, dans l'état et non dans la commande : un enrôlement
+ * par appareil sans scénario de perte produit des workspaces DÉFINITIVEMENT illisibles.
+ * Si tous les porteurs sont perdus, le passé scellé est irrécupérable par construction —
+ * aucun reset côté Cloud ne le restaure. La porte est donc au plus près de la donnée qui
+ * la conditionne, pour qu'un second appelant ne puisse pas l'oublier.
+ *
+ * Les appareils révoqués ne comptent pas : deux porteurs dont un révoqué n'offrent aucun
+ * chemin de remplacement.
+ */
+export function recoveryReadiness(state) {
+    const all = [state.device, ...state.peer_devices];
+    const enrolled = all.filter((d) => d.recovery && !d.revoked_at).length;
+    if (enrolled >= REQUIRED_RECOVERY_DEVICES) {
+        return { ready: true, enrolled, required: REQUIRED_RECOVERY_DEVICES };
+    }
+    return {
+        ready: false,
+        enrolled,
+        required: REQUIRED_RECOVERY_DEVICES,
+        reason: `${enrolled}/${REQUIRED_RECOVERY_DEVICES} appareil(s) de récupération attesté(s). ` +
+            `Sans un second porteur, la perte de cet appareil rendrait le passé scellé irrécupérable — ` +
+            `aucune restauration côté cloud ne le ramènerait.`,
+    };
+}
+/**
+ * Ce que `brainclaw cloud status` rend — le critère de sortie « les trois états de sync
+ * sont observables par une commande ».
+ *
+ * DEUX SOURCES, ET LES DEUX SONT LE DISQUE, PAS LA DÉCLARATION :
+ *   `readable_epochs` vient de `heldEpochs()` via la réconciliation du chargement ;
+ *   `sync` vient du comptage réel de l'outbox, pas des compteurs de `connection.json`.
+ *
+ * Les compteurs persistés restent un cache d'affichage bon marché pour les appelants qui
+ * n'ont pas besoin d'exactitude. Un STATUT, lui, est consulté précisément quand on doute :
+ * s'il relisait un compteur que le code a lui-même incrémenté, il n'observerait rien et
+ * rassurerait à tort au pire moment.
+ */
+export function summarizeConnection(cwd = process.cwd()) {
+    const state = loadConnectionState(cwd);
+    const sync = outboxCounters(cwd);
+    if (!state) {
+        return {
+            connected: false,
+            stage: 'unpaired',
+            current_epoch: 0,
+            readable_epochs: [],
+            sync,
+            recovery: { ready: false, enrolled: 0, required: REQUIRED_RECOVERY_DEVICES },
+        };
+    }
+    return {
+        connected: 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,
+        sync,
+        last_pull_at: state.sync.last_pull_at,
+        recovery: recoveryReadiness(state),
+    };
+}
+//# sourceMappingURL=federation-state.js.map

package/dist/core/identity.js

@@ -260,7 +260,15 @@ function resolveCurrentAgentName() {
         return process.env.BRAINCLAW_AGENT_NAME;
     return detectAiAgent()?.name;
 }
-function resolveExplicitSessionId(env = process.env) {
+/**
+ * The session id the CALLER named, via argument or env. Exported (pln#648 review
+ * P1) because store-resolution must tell a STRONGLY identified session (exact id,
+ * or a record whose pid is this process) from a WEAKLY adopted one (the pidless
+ * candidate at line ~145, or the legacy `.current-session` fallback, which is
+ * returned with no agent/user/pid/TTL check at all). Only the former may steer
+ * resolution from a store the agent never named.
+ */
+export function resolveExplicitSessionId(env = process.env) {
     return env.BRAINCLAW_SESSION_ID?.trim()
         || env.OPENCLAW_SESSION_ID?.trim()
         || env.CLAUDE_SESSION_ID?.trim()

package/dist/core/ids.js

@@ -24,6 +24,11 @@ const PREFIXES = {
     // prefix-based routing (dispatch_status). Canonical prefix is 'rtn'.
     runtime_note: 'rtn',
     runtime_notes: 'rtn',
+    // pln#651 étape 3 — identité d'APPAREIL de la fédération v2, distincte de l'identité
+    // d'agent. Entrée EXPLICITE et non laissée au fallback slice(0,3) : c'est ce fallback
+    // qui a produit la collision de can_b8d53d18 ('runtime_note' → 'run', déjà pris par
+    // agent_run). Il rend 'dev' ici par hasard, pas par contrat.
+    federation_devices: 'dev',
 };
 const ID_COUNTER_FILE = '.id-counter.json';
 function counterPath(cwd, preferredDirName = '.brainclaw') {

package/dist/core/io.js

@@ -13,7 +13,15 @@ const TMP_ORPHAN_MIN_AGE_MS = 60_000;
  * Maps legacy flat directory names to their entity-partitioned paths.
  * Used by resolveEntityDir() for backward-compatible reads and forward writes.
  */
-const ENTITY_DIR_MAP = {
+/**
+ * Exported (pln#649 step 2, review P1-1) so a caller that needs the CANONICAL
+ * relative path for a kind can build a file path directly. `resolveEntityDir`
+ * answers "where do records of this kind generally live" by picking whichever
+ * directory has content — which is the wrong primitive when the question is
+ * "where is THIS record", because a mid-migration store makes the other layout
+ * invisible. Read-only by contract: never mutate this map.
+ */
+export const ENTITY_DIR_MAP = {
     // memory/ — Project entity: durable knowledge
     'constraints': 'memory/constraints',
     'decisions': 'memory/decisions',
@@ -83,6 +91,36 @@ export function resolveEntityDir(subdir, cwd = process.cwd(), mode = 'read', pre
     // Neither exists — return entity path (caller will handle missing dir)
     return entityPath;
 }
+/**
+ * EVERY directory a record of `subdir` can occupy in ONE store, canonical first.
+ *
+ * THE PRIMITIVE THAT WAS MISSING (pln#649, after three reviews found the same defect
+ * at three different call sites). `resolveEntityDir(mode='read')` answers a
+ * DIRECTORY question — "where do records of this kind generally live" — using a
+ * `hasContent` heuristic. Every by-id loader used it for a FILE question — "where is
+ * THIS record" — and the two are not the same: in a store mid-migration, one file in
+ * the canonical directory makes every legacy record invisible. That produced a
+ * reproduced defect in the entity locator, then again in `loadAssignment`, and it is
+ * still latent wherever a loader resolves a directory before looking for an id.
+ *
+ * Callers that need a specific record MUST iterate these, not pick one. Writes keep
+ * using `resolveEntityDir(..., 'write')`, which is always canonical, so nothing new
+ * is ever created in the legacy layout — this is a read-compatibility primitive, not
+ * a migration.
+ */
+export function entityRecordDirs(subdir, cwd = process.cwd(), preferredDirName) {
+    const base = memoryDir(cwd, preferredDirName);
+    const mapped = ENTITY_DIR_MAP[subdir];
+    const legacy = path.join(base, subdir);
+    if (!mapped)
+        return [legacy];
+    const canonical = path.join(base, mapped);
+    return canonical === legacy ? [canonical] : [canonical, legacy];
+}
+/** The same, as record file paths for one id. */
+export function entityRecordPaths(subdir, id, cwd, preferredDirName) {
+    return entityRecordDirs(subdir, cwd ?? process.cwd(), preferredDirName).map((d) => path.join(d, `${id}.json`));
+}
 export function memoryDir(cwd = process.cwd(), preferredDirName) {
     return path.join(cwd, preferredDirName ?? MEMORY_DIR);
 }

package/dist/core/operations/relocate.js

@@ -16,7 +16,7 @@
  */
 import fs from 'node:fs';
 import path from 'node:path';
-import { resolveEntityDir, writeFileAtomic } from '../io.js';
+import { entityRecordPaths, resolveEntityDir, writeFileAtomic } from '../io.js';
 import { getEntitySpec } from '../entity-registry.js';
 import { appendAuditEntry } from '../audit.js';
 import { resolveProjectCwd } from '../cross-project.js';
@@ -62,16 +62,25 @@ export function relocateEntity(input) {
     if (fromCwd === toCwd) {
         throw new Error(`Source and target are the same project (${toCwd}). Nothing to move.`);
     }
-    // Locate the source file across the entity's candidate subdirs.
+    // Locate the source file across the entity's candidate subdirs AND both layouts.
+    //
+    // `resolveEntityDir(sd, cwd, 'read')` picks the canonical directory as soon as it
+    // holds ANY file, so a record still in the pre-migration flat layout was reported
+    // "not found in source project" while sitting right there (pln#649 — same
+    // directory-vs-file confusion fixed in the locator and the by-id loaders; found
+    // here by a Fable audit).
     let srcFile;
     let foundSubdir;
     for (const sd of subdirs) {
-        const candidate = path.join(resolveEntityDir(sd, fromCwd, 'read'), `${input.id}.json`);
-        if (fs.existsSync(candidate)) {
-            srcFile = candidate;
-            foundSubdir = sd;
-            break;
+        for (const candidate of entityRecordPaths(sd, input.id, fromCwd)) {
+            if (fs.existsSync(candidate)) {
+                srcFile = candidate;
+                foundSubdir = sd;
+                break;
+            }
         }
+        if (srcFile)
+            break;
     }
     if (!srcFile || !foundSubdir) {
         throw new Error(`${input.entity} '${input.id}' not found in source project (${fromCwd}).`);
@@ -85,11 +94,32 @@ export function relocateEntity(input) {
         throw new Error(`${input.entity} '${input.id}' is unreadable JSON: ${err.message}`, { cause: err });
     }
     getEntitySpec(input.entity).schema.parse(raw);
-    // Collision guard — never overwrite an item already in the target.
+    // Collision guard — never overwrite an item already in the target, and never
+    // CREATE a second copy of the same id inside it.
+    //
+    // Checking only the canonical directory (`'write'`) was worse than a missed
+    // overwrite: if the target held the same id in the LEGACY layout, the guard passed
+    // and the move wrote a canonical copy beside it — manufacturing an intra-store
+    // duplicate id. Found by a Fable audit.
+    //
+    // THE MECHANISM RECORDED HERE BEFORE WAS WRONG, and is corrected rather than deleted
+    // because a wrong mechanism in a comment misleads the next reader more efficiently than
+    // no comment at all. It claimed the duplicate is "precisely the state the entity locator
+    // refuses as `ambiguous`, so a successful move could leave an entity permanently
+    // unroutable". It is not: `recordExists` is a per-STORE boolean and matches are collected
+    // per store, so a record duplicated across two LAYOUTS INSIDE ONE STORE collapses to a
+    // single `found`. Ambiguity needs two distinct STORES.
+    //
+    // The real harm is quieter and still worth the guard: the two copies drift, the loader
+    // reads whichever layout wins, and a delete that touches only the canonical one promotes
+    // the stale copy back to being the record (the zombie now fixed in assignments.ts).
     const dstDir = resolveEntityDir(foundSubdir, toCwd, 'write');
     const dstFile = path.join(dstDir, `${input.id}.json`);
-    if (fs.existsSync(dstFile)) {
-        throw new Error(`${input.entity} '${input.id}' already exists in the target project — refusing to overwrite.`);
+    for (const existing of entityRecordPaths(foundSubdir, input.id, toCwd)) {
+        if (fs.existsSync(existing)) {
+            throw new Error(`${input.entity} '${input.id}' already exists in the target project (${existing}) — refusing to overwrite `
+                + 'or to create a second copy of the same id.');
+        }
     }
     // Reference guards (plans): refuse to move work under a live claim; warn on
     // sequences that still point at it (v1 does not rewrite refs).