brainclaw 1.21.0 → 1.22.0

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/facts.js

@@ -1,8 +1,8 @@
 // Generated by scripts/emit-site-facts.mjs at build time. Do not edit manually.
-// Source: brainclaw v1.21.0 on 2026-08-07T12:11:23.699Z
+// Source: brainclaw v1.22.0 on 2026-08-08T16:03:19.158Z
 export const FACTS = {
-  "version": "1.21.0",
-  "generated_at": "2026-08-07T12:11:23.699Z",
+  "version": "1.22.0",
+  "generated_at": "2026-08-08T16:03:19.158Z",
   "tools": {
     "count": 67,
     "published_count": 65,
@@ -474,7 +474,7 @@ export const FACTS = {
   },
   "bench": {
     "schema": "brainclaw.bench.v1",
-    "generated_at": "2026-08-07T12:11:22.030Z",
+    "generated_at": "2026-08-08T16:03:17.056Z",
     "node_version": "v24.18.0",
     "platform": "linux-x64",
     "repeats": 3,
@@ -483,7 +483,7 @@ export const FACTS = {
         "name": "cold_onboard",
         "volume": "empty",
         "description": "fresh machine → init → first useful context. Baseline for time-to-first-value.",
-        "duration_ms_median": 71,
+        "duration_ms_median": 73,
         "payload_chars_median": 1640,
         "payload_tokens_est_median": 410
       },
@@ -491,15 +491,15 @@ export const FACTS = {
         "name": "warm_work",
         "volume": "medium",
         "description": "bclaw_work consult over a real-shaped store (~200 plans / 500 handoffs / 450 claims).",
-        "duration_ms_median": 101,
-        "payload_chars_median": 2625,
-        "payload_tokens_est_median": 656
+        "duration_ms_median": 128,
+        "payload_chars_median": 2626,
+        "payload_tokens_est_median": 657
       },
       {
         "name": "first_edit",
         "volume": "medium",
         "description": "code_find + code_brief on the fresh-agent path (missing index, first touch).",
-        "duration_ms_median": 11,
+        "duration_ms_median": 14,
         "payload_chars_median": 499,
         "payload_tokens_est_median": 125
       }

package/dist/facts.json

@@ -1,6 +1,6 @@
 {
-  "version": "1.21.0",
-  "generated_at": "2026-08-07T12:11:23.699Z",
+  "version": "1.22.0",
+  "generated_at": "2026-08-08T16:03:19.158Z",
   "tools": {
     "count": 67,
     "published_count": 65,
@@ -472,7 +472,7 @@
   },
   "bench": {
     "schema": "brainclaw.bench.v1",
-    "generated_at": "2026-08-07T12:11:22.030Z",
+    "generated_at": "2026-08-08T16:03:17.056Z",
     "node_version": "v24.18.0",
     "platform": "linux-x64",
     "repeats": 3,
@@ -481,7 +481,7 @@
         "name": "cold_onboard",
         "volume": "empty",
         "description": "fresh machine → init → first useful context. Baseline for time-to-first-value.",
-        "duration_ms_median": 71,
+        "duration_ms_median": 73,
         "payload_chars_median": 1640,
         "payload_tokens_est_median": 410
       },
@@ -489,15 +489,15 @@
         "name": "warm_work",
         "volume": "medium",
         "description": "bclaw_work consult over a real-shaped store (~200 plans / 500 handoffs / 450 claims).",
-        "duration_ms_median": 101,
-        "payload_chars_median": 2625,
-        "payload_tokens_est_median": 656
+        "duration_ms_median": 128,
+        "payload_chars_median": 2626,
+        "payload_tokens_est_median": 657
       },
       {
         "name": "first_edit",
         "volume": "medium",
         "description": "code_find + code_brief on the fresh-agent path (missing index, first touch).",
-        "duration_ms_median": 11,
+        "duration_ms_median": 14,
         "payload_chars_median": 499,
         "payload_tokens_est_median": 125
       }

package/docs/cli.md

@@ -1749,46 +1749,9 @@ brainclaw push --remote origin --message "chore: push memory state" --json
 
 ## Federation
 
-The `federation` command group manages cloud signal exchange with `app.brainclaw.dev`. Federation requires `BRAINCLAW_CLOUD_API_KEY` to be set. It is a planned premium tier for cross-machine and cross-organization coordination.
+The v1 `brainclaw federation` command group and the whole cloud egress path (`app.brainclaw.dev` push/pull, `cloud_sync` config, `BRAINCLAW_CLOUD_*` env vars) were removed in wave 1 of dec#156 / pln#651. There is no migration: the v1 format is abandoned, not deprecated. The v2 federation surface will be introduced by pln#651 wave 3 alongside the pairing CLI (`brainclaw cloud connect`).
 
-### `brainclaw federation push <message>`
-
-Push a test signal to the cloud. The signal is sent from the current project and agent to a target project or broadcast address.
-
-| Option | Description |
-|---|---|
-| `--type <type>` | Signal type (default: `runtime_note`). Accepted values: `signal`, `handoff`, `candidate`, `runtime_note`, `board_snapshot` |
-| `--to-project <project>` | Target project name (default: `broadcast`) |
-| `--to-agent <agent>` | Target agent name |
-
-```bash
-brainclaw federation push "Auth rollout complete" --to-project lodestar
-brainclaw federation push "Blocked on payments" --type runtime_note --to-agent copilot
-```
-
-### `brainclaw federation pull`
-
-Pull signals from the cloud inbox for the current agent.
-
-| Option | Description |
-|---|---|
-| `--agent <name>` | Agent name to pull for (default: auto-detected) |
-| `--since <date>` | Only pull signals after this ISO date |
-| `--limit <n>` | Maximum number of signals to pull (default: 20) |
-
-```bash
-brainclaw federation pull
-brainclaw federation pull --since 2026-04-01
-brainclaw federation pull --agent copilot --limit 50
-```
-
-### `brainclaw federation status`
-
-Check cloud federation configuration: shows the configured cloud URL, whether the API key is set, and pings the cloud health endpoint if configured.
-
-```bash
-brainclaw federation status
-```
+Local cross-project federation (see below) is unaffected.
 
 ---
 
@@ -2244,4 +2207,72 @@ Show brainclaw context volume stats — tokens injected per agent and per MCP to
 |---|---|
 | `--json` | Output as JSON |
 
+### `brainclaw cloud status`
+
+Show the federation v2 connection state for this workspace: linked cloud project, role,
+current key epoch, the epochs actually readable on this device, and the three sync states.
+
+| Option | Description |
+|---|---|
+| `--json` | Output as JSON |
+
+Sync state is **visible by design** (dec#154): a cloud-originated operation materializes in
+the local journal as `pending`, `synced` or `conflict`, and a conflict is presented for
+resolution rather than resolved by a silent last-write-wins. The counts are read from the
+outbox on disk, not from a cached counter — a status that echoed a number the code had
+itself incremented would reassure precisely when you are checking because you doubt.
+
+`readable_epochs` likewise comes from the keyring on disk. It can be shorter than the
+epochs the state declares: a partial backup restore leaves that exact disagreement, and
+the honest answer is what can actually be decrypted here.
+
+### `brainclaw cloud connect <invite-code> --url <url> --agent <id>`
+
+Join a cloud project. This is a **key ceremony**, not a config write: it claims the invite,
+proves possession of this agent's Ed25519 identity, and attests the device's X25519
+encryption key with that same identity.
+
+| Option | Description |
+|---|---|
+| `--url <url>` | Cloud deployment address (required) |
+| `--agent <id>` | Opaque agent identifier to enroll, 4–64 chars (required) |
+| `--json` | Output as JSON |
+
+The human copies **only the invite code**, then compares **two fingerprints** with what the
+approver sees on their screen. No API key, no PEM, no agent_id, no environment variable
+(dec#8). Both fingerprints are printed in full, never truncated — a 16-character comparison
+collides far more easily than it looks.
+
+The attestation is what stops a **phantom member**. Without it, the Cloud — which
+orchestrates the pairing — could insert its own key into the envelope list: end-to-end
+encryption whose key exchange is arbitrated by the very party it claims to neutralize.
+
+A refused pairing writes **nothing** locally, so re-running is safe and leaves no orphan.
+
+### `brainclaw cloud await --url <url>`
+
+Observe the human approval and activate the local pairing.
+
+Deliberately a **separate command**: approval depends on a person, whose delay is not
+bounded. A command that blocked indefinitely on a third party would be a poor citizen in a
+script, and an interrupted pairing must stay resumable. Polling does **not** mutate local
+state — reading a status must never change the workspace.
+
+### `brainclaw cloud disconnect --url <url>`
+
+Remove the local authorization and request remote revocation.
+
+| Option | Description |
+|---|---|
+| `--url <url>` | Cloud deployment address (required) |
+| `--forget-keys` | Also erase this project's epoch keys — its sealed past becomes unreadable here |
+
+Local state flips to revoked **even if the cloud is unreachable**: otherwise a lost device
+would stay authorized for want of a network, the opposite of what revocation must
+guarantee.
+
+What disconnect does **not** do, stated rather than left implied: it does not erase data
+already pulled and decrypted locally, nor what other devices already hold. It withdraws an
+authorization; it does not rewrite the past (RFC §5.2).
+
 This keeps end-user installs aware of published npm releases without requiring a local tarball channel. To keep beta testers on a different channel, set `brainclaw_update_source` to `type: npm` with a different `dist_tag`, such as `prelaunch`.