brainclaw 1.21.0 → 1.23.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/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/schema.js

@@ -1175,22 +1175,6 @@ export const RemoteSyncSchema = z.object({
     ssh_key_path: z.string().optional(),
     sync_strategy: z.enum(['pull-only', 'push-pull', 'pr-based']).default('push-pull'),
 });
-export const CloudSyncConfigSchema = z.object({
-    enabled: z.boolean().default(false),
-    endpoint: z.string().default('https://app.brainclaw.dev'),
-    api_key: z.string().optional(),
-    /** Remote project this bridge federates into (scopes signed runtime writes). */
-    project_id: z.string().optional(),
-    /** Approved remote agent identity used to sign runtime writes (pln#100). */
-    agent_id: z.string().optional(),
-    agent_name: z.string().optional(),
-    /**
-     * Fail-closed toggle: when true, the bridge refuses to push a runtime write
-     * unless it can sign it with an approved agent's Ed25519 key. Absent/false
-     * keeps existing API-key-only setups working (signing is additive).
-     */
-    require_signed: z.boolean().optional(),
-});
 export const SessionSnapshotSchema = z.object({
     schema_version: z.number().int().positive().optional(),
     session_id: z.string(),
@@ -1520,7 +1504,6 @@ export const ConfigSchema = z.object({
     target_audience: z.enum(['human', 'agent']).optional().default('human'),
     openclaw_bridge: z.boolean().optional().default(false),
     remote_sync: RemoteSyncSchema.optional(),
-    cloud_sync: CloudSyncConfigSchema.optional(),
     telemetry: z.literal(false),
     allow_network: z.literal(false),
     redaction: RedactionConfigSchema,

package/dist/core/sequence-request-schema.js

@@ -0,0 +1,93 @@
+/**
+ * Schémas zod des entrées de la famille SÉQUENCE — `bclaw_create_sequence` et
+ * `bclaw_update_sequence` (pln#599 batch 2, première famille composite).
+ *
+ * ── CE QUI CHANGE PAR RAPPORT À LA FAMILLE CAPTURE ────────────────────────────
+ * C'est la première famille COMPOSITE : les deux outils partagent un objet imbriqué,
+ * l'item de séquence, dont le schéma était jusqu'ici une constante JSON manuelle
+ * (`SEQUENCE_ITEM_INPUT_SCHEMA`) réutilisée à deux endroits.
+ *
+ * La duplication d'un sous-schéma est exactement ce qui a produit trp#180 — les tableaux
+ * de `bclaw_loop` sans `items` — parce qu'un des deux exemplaires avait été corrigé et pas
+ * l'autre. Le dériver d'une source zod unique supprime la classe entière.
+ *
+ * ── CONTRAINTE INCHANGÉE : FINGERPRINT IDENTIQUE ──────────────────────────────
+ * Le JSON Schema produit doit être byte-identique à celui écrit à la main. Les
+ * `minLength: 1` et `minimum: 1` du schéma d'item sont donc reproduits tels quels, y
+ * compris là où ils paraissent redondants : ce sont des contraintes qu'un client peut déjà
+ * avoir apprises, et les retirer serait un changement de contrat déguisé en migration.
+ *
+ * `status` reste une chaîne libre et non un enum, pour la même raison. Le resserrer est un
+ * changement de surface qui mérite sa propre décision, pas un effet de bord.
+ */
+import { z } from 'zod';
+/**
+ * Item de lane. Source UNIQUE — les deux outils de la famille la partagent, là où le
+ * schéma manuel existait en un exemplaire réutilisé par référence mais impossible à
+ * valider contre le code qui le consomme.
+ */
+export const SequenceItemInputSchema = z
+    .object({
+    planId: z.string().min(1).describe('Plan item ID referenced by this sequence item.'),
+    stepId: z
+        .string()
+        .min(1)
+        .describe('Optional plan step ID inside planId for step-level dispatch/readiness.')
+        .optional(),
+    // REQUIS, comme dans le schema d'origine. Le rendre optionnel etait un
+    // ASSOUPLISSEMENT du contrat — un appel sans rank aurait ete accepte par le schema
+    // publie puis rejete plus loin. La garde de gouvernance l'a detecte via le
+    // fingerprint.
+    rank: z
+        .number()
+        .min(1)
+        .describe('Positive integer ordering key. Ranks must be unique within a sequence.'),
+    hard_after: z
+        .array(z.string())
+        .describe('Sequence item planId values that must complete before this item becomes ready.')
+        .optional(),
+    soft_after: z
+        .array(z.string())
+        .describe('Advisory predecessor planId values; they inform ordering but do not block readiness.')
+        .optional(),
+    lane: z
+        .string()
+        .describe('Optional lane label used for parallel dispatch grouping and filtering.')
+        .optional(),
+    scope_hint: z
+        .string()
+        .describe('Optional file/path scope hint for claim and brief generation.')
+        .optional(),
+    rationale: z
+        .string()
+        .describe('Optional explanation for this item or dependency placement.')
+        .optional(),
+})
+    .describe('Sequence lane item. planId is required; stepId optionally narrows dispatch/readiness to a specific plan step.');
+/** Identité de l'appelant — commune aux deux outils, comme dans la famille capture. */
+const CallerIdentity = {
+    agent: z.string().describe('Agent name.').optional(),
+    agentId: z.string().describe('Registered agent id.').optional(),
+};
+export const CreateSequenceRequestSchema = z.object({
+    name: z.string().describe('Sequence name.'),
+    description: z.string().describe('Optional sequence description.').optional(),
+    // Chaîne libre, PAS un enum : c'est l'état publié. Le resserrer mérite sa propre
+    // décision, pas un effet de bord de migration.
+    status: z.string().describe('Status: draft, active, archived.').optional(),
+    owner: z.string().describe('Optional sequence owner.').optional(),
+    items: z.array(SequenceItemInputSchema).describe('Sequence items in rank order.').optional(),
+    tags: z.array(z.string()).describe('Optional tags.').optional(),
+    ...CallerIdentity,
+});
+export const UpdateSequenceRequestSchema = z.object({
+    id: z.string().describe('Sequence ID or short label.'),
+    name: z.string().describe('Optional new sequence name.').optional(),
+    description: z.string().describe('Optional new description.').optional(),
+    status: z.string().describe('Status: draft, active, archived.').optional(),
+    owner: z.string().describe('Optional sequence owner.').optional(),
+    items: z.array(SequenceItemInputSchema).describe('Optional replacement items array.').optional(),
+    tags: z.array(z.string()).describe('Optional replacement tags.').optional(),
+    ...CallerIdentity,
+});
+//# sourceMappingURL=sequence-request-schema.js.map