brainclaw 1.22.0 → 1.24.0

package/dist/core/federation-rotation.js

@@ -0,0 +1,124 @@
+/**
+ * Rotation d'epoch — retirer la LECTURE FUTURE à un appareil (pln#658, dec#163).
+ *
+ * ── CE QUE LA ROTATION FAIT, ET CE QU'ELLE NE PEUT PAS FAIRE ──────────────────
+ * Elle crée un epoch N+1 dont le révoqué n'a pas la clé, et fait basculer les écritures
+ * dessus. À partir du cutover, il ne lit plus RIEN de nouveau.
+ *
+ * Elle ne lui retire PAS ce qu'il détient déjà. C'est cryptographiquement impossible : une
+ * clé copiée sur une machine y reste. Le prétendre serait mentir, et dec#163 §3 l'interdit
+ * explicitement. La révocation est FORWARD-ONLY, et c'est dit à l'opérateur en toutes
+ * lettres au moment où il tourne la clé — pas dans une note de bas de page.
+ *
+ * ── LE QUORUM EST APPLIQUÉ ICI, ET SEULEMENT ICI (dec#163 §4) ─────────────────
+ * « Émettre au-delà du premier epoch » = créer un epoch N+1. C'est le moment exact où la
+ * perte d'une machine cesse d'être théorique : après rotation, l'ancien epoch ne sert plus
+ * qu'à relire le passé, et si personne d'autre ne détient le nouveau, une panne de disque
+ * emporte tout le futur. `recoveryReadiness` était RAPPORTÉ et jamais bloquant (mesuré) —
+ * il devient une condition.
+ *
+ * En solo, l'opérateur peut passer outre, mais son consentement est PERSISTÉ : on ne
+ * demande pas deux fois, et surtout on garde la trace qu'il a été demandé.
+ */
+import crypto from 'node:crypto';
+import { loadConnectionState, saveConnectionState, recoveryReadiness, } from './federation-state.js';
+import { storeEpochPrivateKey, epochPublicKey, heldEpochs } from './federation-keyring.js';
+export const FORWARD_ONLY_NOTICE = "La rotation ne retire à personne ce qu'il détient DÉJÀ : un appareil révoqué peut " +
+    "toujours relire ce qui a été scellé avant le cutover. Elle ferme la lecture du FUTUR, " +
+    'pas celle du passé — aucune cryptographie ne peut faire autrement.';
+const SOLO_CONSENT_STATEMENT = "Je comprends que la perte de cette machine signifie la perte définitive de l'historique " +
+    'scellé : aucune restauration côté cloud ne le ramènera.';
+export function soloConsentStatement() {
+    return SOLO_CONSENT_STATEMENT;
+}
+function readConsent(state) {
+    return state.solo_recovery_consent;
+}
+/**
+ * Enregistre le consentement solo. Idempotent : réaccepter ne réécrit pas la date d'origine,
+ * parce que la question « quand cette personne a-t-elle compris le risque ? » a UNE réponse.
+ */
+export function acceptSoloRecoveryRisk(cwd) {
+    const state = loadConnectionState(cwd ?? process.cwd());
+    if (!state)
+        throw new Error('Aucun appairage local : rien à consentir.');
+    const existing = readConsent(state);
+    if (existing)
+        return existing;
+    const consent = {
+        accepted_at: new Date().toISOString(),
+        statement: SOLO_CONSENT_STATEMENT,
+    };
+    saveConnectionState({ ...state, ...{ solo_recovery_consent: consent } }, cwd ?? process.cwd());
+    return consent;
+}
+/**
+ * Fait tourner l'epoch : crée N+1 localement et bascule les écritures dessus.
+ *
+ * NE REMET RIEN AUX AUTRES — c'est délibérément une seconde étape (`cloud grant`). Coupler
+ * les deux ferait qu'un échec de remise laisserait un cutover à moitié fait : les écritures
+ * seraient déjà passées sous N+1 pendant que les lecteurs légitimes n'auraient pas la clé.
+ * Le résultat NOMME donc les destinataires à re-servir.
+ */
+export function rotateEpoch(options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const state = loadConnectionState(cwd);
+    if (!state) {
+        return {
+            ok: false, reason: 'no_pairing',
+            detail: 'Aucun appairage local.',
+            remedy: 'Appairer cet appareil avant toute rotation (`brainclaw cloud connect`).',
+        };
+    }
+    const held = heldEpochs(state.cloud_project_id, options.home);
+    const current = state.keys?.current_epoch ?? 0;
+    if (current <= 0 || !held.includes(current)) {
+        return {
+            ok: false, reason: 'not_holder',
+            detail: `Cet appareil ne détient pas l'epoch courant (${current}) — il ne peut pas en produire le suivant.`,
+            remedy: "Se faire remettre l'epoch courant par un détenteur (`brainclaw cloud grant`) avant de tourner.",
+        };
+    }
+    // ── LE QUORUM, APPLIQUÉ (dec#163 §4) ────────────────────────────────────────
+    const readiness = recoveryReadiness(state);
+    const consent = readConsent(state);
+    if (!readiness.ready && !consent && !options.force) {
+        return {
+            ok: false, reason: 'recovery_quorum',
+            detail: `${readiness.reason ?? 'Quorum de récupération non atteint.'} ` +
+                "Tourner l'epoch maintenant ferait dépendre TOUT le futur du projet de cette seule machine.",
+            remedy: "Appairer un second appareil de récupération, OU accepter explicitement le risque " +
+                '(`brainclaw cloud accept-solo-risk`), ce qui sera consigné avec sa date.',
+        };
+    }
+    const next = current + 1;
+    // Ne jamais écraser : si N+1 existe déjà, c'est qu'une rotation a déjà eu lieu (reprise
+    // après interruption). On la constate au lieu d'en fabriquer une seconde.
+    const already = epochPublicKey(state.cloud_project_id, next, options.home);
+    if (!already) {
+        const generated = crypto.generateKeyPairSync('x25519');
+        storeEpochPrivateKey(state.cloud_project_id, next, generated.privateKey.export({ type: 'pkcs8', format: 'pem' }).toString(), options.home);
+    }
+    const materialized = epochPublicKey(state.cloud_project_id, next, options.home);
+    if (!materialized) {
+        // Vérifier APRÈS écriture : basculer les écritures sur une clé qu'on ne relit pas
+        // produirait des enveloppes que PERSONNE ne peut ouvrir, y compris nous.
+        throw new Error(`Epoch ${next} écrit mais non relisible — le cutover est ANNULÉ pour ne pas sceller ` +
+            'sous une clé fantôme.');
+    }
+    // CUTOVER : les écritures suivantes scellent sous N+1 (emitProjections lit current_epoch).
+    const readable = heldEpochs(state.cloud_project_id, options.home);
+    saveConnectionState({
+        ...state,
+        keys: { ...(state.keys ?? { current_epoch: 0, known_epochs: [] }), current_epoch: next, known_epochs: readable },
+    }, cwd);
+    return {
+        ok: true,
+        previous_epoch: current,
+        new_epoch: next,
+        new_epoch_fingerprint: materialized.fingerprint,
+        readable_epochs: readable,
+        forward_only_notice: FORWARD_ONLY_NOTICE,
+    };
+}
+//# sourceMappingURL=federation-rotation.js.map

package/dist/core/federation-state.js

@@ -34,7 +34,9 @@ import { heldEpochs } from './federation-keyring.js';
 import { counters as outboxCounters } from './federation-outbox-v2.js';
 import { logger } from './logger.js';
 const CONNECTION_FILE = 'connection.json';
-export const FEDERATION_STATE_SCHEMA = 'brainclaw.federation-connection/v2';
+export const FEDERATION_STATE_SCHEMA = 'brainclaw.federation-connection/v3';
+/** Schéma v2 — singleton mono-agent. Lu en tolérance, jamais écrit (trp#1625). */
+const FEDERATION_STATE_SCHEMA_V2 = 'brainclaw.federation-connection/v2';
 /** Nombre d'appareils de récupération exigés avant la première enveloppe (RFC §5.3). */
 export const REQUIRED_RECOVERY_DEVICES = 2;
 // ── Emplacement ───────────────────────────────────────────────────────────────
@@ -63,12 +65,73 @@ export function loadConnectionState(cwd = process.cwd()) {
         return undefined;
     }
     const state = raw;
-    if (state.schema !== FEDERATION_STATE_SCHEMA || !state.cloud_project_id || !state.device?.device_id) {
-        // Un schéma inconnu n'est PAS migré (dec#156) : la v1 est abandonnée, pas dépréciée.
-        logger.warn(`État de connexion fédération ignoré : schéma '${String(state.schema)}' non reconnu (attendu ${FEDERATION_STATE_SCHEMA}).`);
+    const knownSchema = state.schema === FEDERATION_STATE_SCHEMA || state.schema === FEDERATION_STATE_SCHEMA_V2;
+    if (!knownSchema || !state.cloud_project_id || !state.device?.device_id) {
+        // Un schéma inconnu (v1) n'est PAS migré (dec#156) : abandonné, pas déprécié. Mais la
+        // v2 EST lue — c'est le format vivant sur les machines déjà appairées ; le refuser
+        // détruirait leur appairage au premier chargement après mise à jour.
+        logger.warn(`État de connexion fédération ignoré : schéma '${String(state.schema)}' non reconnu.`);
         return undefined;
     }
-    return normalizeState(state, cwd);
+    return normalizeState(projectToV3(state), cwd);
+}
+/**
+ * Projette un état v2 (singleton) vers la forme v3 (liste de pairings) À LA LECTURE.
+ *
+ * Un v2 n'a pas de `pairings` ni de `cloud_url` ni d'agent mémorisé. On dérive un pairing
+ * unique de son `enrollment` — l'agent est marqué inconnu, faute de l'information : le
+ * singleton v2 ne l'a jamais stockée, et l'inventer serait mentir. Un état déjà v3 passe
+ * inchangé. Rien n'est réécrit sur disque ici : la conversion n'a lieu qu'en mémoire, et
+ * la prochaine ÉCRITURE (un appairage, une révocation) persistera la forme v3.
+ */
+function projectToV3(state) {
+    if (Array.isArray(state.pairings)) {
+        return { ...state, schema: FEDERATION_STATE_SCHEMA };
+    }
+    const enrollment = state.enrollment ?? { stage: 'unpaired', updated_at: nowISO() };
+    const derived = {
+        agent_id: '(inconnu — appairé en v2)',
+        stage: enrollment.stage,
+        enrollment_id: enrollment.enrollment_id,
+        role: enrollment.role,
+        updated_at: enrollment.updated_at,
+    };
+    return {
+        ...state,
+        schema: FEDERATION_STATE_SCHEMA,
+        pairings: enrollment.enrollment_id || enrollment.stage !== 'unpaired' ? [derived] : [],
+    };
+}
+// ── Manipulation des pairings (v3) ─────────────────────────────────────────────
+/** Le pairing d'un agent donné, ou `undefined`. */
+export function pairingForAgent(state, agentId) {
+    return state.pairings.find((p) => p.agent_id === agentId);
+}
+/** Y a-t-il au moins un pairing actif ? Décide notamment la genèse d'epoch (premier appareil). */
+export function hasActivePairing(state) {
+    return state.pairings.some((p) => p.stage === 'active');
+}
+/**
+ * Ajoute ou met à jour le pairing d'un agent, SANS toucher aux autres, et maintient le
+ * miroir `enrollment` sur le pairing touché. Retourne un nouvel état (immuable).
+ *
+ * C'est l'unique porte par laquelle un pairing entre ou change : centraliser le maintien
+ * du miroir ici évite qu'un écrivain oublie de le synchroniser et fasse diverger la vue
+ * mono-agent de la source de vérité.
+ */
+export function upsertPairing(state, pairing) {
+    const others = state.pairings.filter((p) => p.agent_id !== pairing.agent_id);
+    return {
+        ...state,
+        pairings: [...others, pairing],
+        enrollment: {
+            stage: pairing.stage,
+            enrollment_id: pairing.enrollment_id,
+            role: pairing.role,
+            updated_at: pairing.updated_at,
+        },
+        updated_at: nowISO(),
+    };
 }
 /**
  * Réconcilie l'état déclaré avec le DISQUE.
@@ -154,11 +217,16 @@ function assertNoSecret(state) {
  */
 export function createConnectionState(params) {
     const now = nowISO();
+    const firstPairing = params.agentId
+        ? { agent_id: params.agentId, stage: 'pending', enrollment_id: params.enrollmentId, updated_at: now }
+        : undefined;
     return {
         schema: FEDERATION_STATE_SCHEMA,
         cloud_project_id: params.cloudProjectId,
+        cloud_url: params.cloudUrl,
         workspace_path: path.resolve(params.workspacePath ?? process.cwd()),
         enrollment: { stage: 'pending', enrollment_id: params.enrollmentId, updated_at: now },
+        pairings: firstPairing ? [firstPairing] : [],
         device: params.device,
         peer_devices: [],
         // 0 = « aucun epoch » et non « premier epoch ». Le premier epoch remis est le 1 ;
@@ -250,18 +318,25 @@ export function summarizeConnection(cwd = process.cwd()) {
             stage: 'unpaired',
             current_epoch: 0,
             readable_epochs: [],
+            pairings: [],
             sync,
             recovery: { ready: false, enrolled: 0, required: REQUIRED_RECOVERY_DEVICES },
         };
     }
     return {
-        connected: state.enrollment.stage === 'active',
+        // Connecté dès qu'AU MOINS UN agent est actif, OU que le miroir l'indique. Le OR est
+        // une ceinture de sécurité pour l'affichage : un état projeté depuis v2, ou construit
+        // à la main, peut porter un miroir actif sans pairing correspondant. Mieux vaut
+        // afficher « connecté » et laisser l'opérateur voir que masquer un appairage réel.
+        connected: hasActivePairing(state) || state.enrollment.stage === 'active',
         cloud_project_id: state.cloud_project_id,
         stage: state.enrollment.stage,
         role: state.enrollment.role,
         current_epoch: state.keys.current_epoch,
         readable_epochs: state.keys.known_epochs,
         device_fingerprint: state.device.x25519_fingerprint,
+        cloud_url: state.cloud_url,
+        pairings: state.pairings.map((p) => ({ agent_id: p.agent_id, stage: p.stage, role: p.role })),
         sync,
         last_pull_at: state.sync.last_pull_at,
         recovery: recoveryReadiness(state),

package/dist/core/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

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

@@ -0,0 +1,90 @@
+/**
+ * Schémas zod des entrées de la famille SESSION — `bclaw_session_start` et
+ * `bclaw_session_end` (pln#599 batch 2, troisième famille composite).
+ *
+ * ── LA PARTICULARITÉ DE CETTE FAMILLE : AUCUN CHAMP REQUIS ────────────────────
+ * Les deux outils ont un `properties` fourni mais PAS de clé `required`. C'est délibéré et
+ * doit être préservé au bit près : `bclaw_session_start` sans argument est l'appel normal,
+ * et l'identité comme le contexte se résolvent depuis l'ambiance.
+ *
+ * zod n'émet `required` que s'il existe au moins un champ non-optionnel — donc marquer
+ * TOUS les champs `.optional()` reproduit exactement l'absence de la clé. C'est le
+ * pendant du piège inverse rencontré sur la famille séquence : là-bas un requis était
+ * devenu optionnel (assouplissement) ; ici, oublier un `.optional()` créerait un requis
+ * là où il n'y en avait aucun — un DURCISSEMENT qui casserait l'appel sans argument.
+ *
+ * ── CE QUI N'EST PAS RESSERRÉ, DÉLIBÉRÉMENT ───────────────────────────────────
+ * `contextProfile` et `contextFormat` énumèrent leurs valeurs dans leur description mais
+ * restent des chaînes libres : les profils sont extensibles côté produit, et un enum
+ * publié figerait cette extensibilité. `maintenanceMode` garde en revanche son enum,
+ * parce qu'il en avait déjà un.
+ *
+ * ── GARDE-FOU DE GÉNÉRATION ───────────────────────────────────────────────────
+ * zod émet `additionalProperties: false` d'office ; le générateur le retire À LA RACINE
+ * uniquement (cf. OPEN_SCHEMAS dans scripts/build-mcp-schemas.mjs). Le laisser durcirait
+ * la surface ; le retirer plus profond l'assouplirait.
+ */
+import { z } from 'zod';
+/** Identité de l'appelant — commune à toutes les familles migrées. */
+const CallerIdentity = {
+    agent: z.string().describe('Agent name.').optional(),
+    agentId: z.string().describe('Registered agent id.').optional(),
+};
+export const SessionStartRequestSchema = z.object({
+    ...CallerIdentity,
+    context: z.string().describe('Context target path.').optional(),
+    // Enum CONSERVÉ : il existait déjà dans le schéma manuel.
+    maintenanceMode: z
+        .enum(['fast', 'full'])
+        .describe('Maintenance mode. Default is full for explicit session-start calls; use fast to skip non-critical maintenance work.')
+        .optional(),
+    includeContext: z
+        .boolean()
+        .describe('Include project memory context in the response (equivalent to bclaw_get_context).')
+        .optional(),
+    includeBoard: z
+        .boolean()
+        .describe('Include agent board (plans, claims, handoffs) in the response (equivalent to bclaw_get_agent_board).')
+        .optional(),
+    // Chaîne libre : les profils sont extensibles, un enum publié figerait cette
+    // extensibilité et rejetterait un profil ajouté côté produit.
+    contextProfile: z
+        .string()
+        .describe('Context profile when includeContext is true: dev (default), dense, compact, copilot, quick, briefing, openclaw, ops, research. If unset, uses the agent default profile.')
+        .optional(),
+    contextFormat: z
+        .string()
+        .describe('Context format when includeContext is true: markdown, json, or template.')
+        .optional(),
+});
+export const SessionEndRequestSchema = z.object({
+    session: z.string().describe('Session ID.').optional(),
+    ...CallerIdentity,
+    summary: z.string().describe('Session summary text.').optional(),
+    narrative: z
+        .string()
+        .describe('Free-text narrative of what happened in the session and why. Goes beyond the auto-generated commit list: "Tried X, failed because Y, pivoted to Z. Watch out for A."')
+        .optional(),
+    autoReflect: z.boolean().describe('Auto-reflect session notes as candidates.').optional(),
+    autoRelease: z
+        .boolean()
+        .describe('Auto-release any active claims at session end.')
+        .optional(),
+    reflectHandoff: z
+        .boolean()
+        .describe('Materialize an open handoff from git commits since session start.')
+        .optional(),
+    dispatchReview: z
+        .boolean()
+        .describe('When used with reflectHandoff, auto-dispatch a code review if the reflected handoff is reviewable.')
+        .optional(),
+    reviewer: z
+        .string()
+        .describe('Explicit reviewer for the reflected handoff review dispatch.')
+        .optional(),
+    reflect: z
+        .boolean()
+        .describe('Emit the dogfooding reflection prompt (project + your surfaces/skills/tools). Default true — pass false to suppress on a trivial session. Capture actionable findings via bclaw_quick_capture.')
+        .optional(),
+});
+//# sourceMappingURL=session-request-schema.js.map

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

@@ -0,0 +1,112 @@
+/**
+ * Schémas zod des entrées de la famille STEP — `bclaw_add_step`, `bclaw_update_step`,
+ * `bclaw_complete_step`, `bclaw_delete_step` (pln#599 batch 2, quatrième famille).
+ *
+ * ── CE QUE CETTE FAMILLE APPREND, ET QUI CORRIGE UNE RÈGLE TROP VITE GÉNÉRALISÉE ─
+ * Sur la famille séquence j'avais formulé la consigne « retirer `additionalProperties`
+ * À LA RACINE UNIQUEMENT », au motif que le sous-schéma d'item de lane le portait déjà
+ * dans sa version manuelle. C'était vrai LÀ, et faux comme règle générale.
+ *
+ * Ici, le sous-objet `data` de `bclaw_add_step` n'a PAS d'`additionalProperties` dans la
+ * version écrite à la main. Appliquer « racine uniquement » y laisserait donc le
+ * `additionalProperties: false` émis par zod — exactement le DURCISSEMENT que la règle
+ * était censée empêcher, réintroduit par la règle elle-même.
+ *
+ * La consigne réelle n'a jamais été « racine » : c'est « reproduire le schéma manuel au
+ * bit près ». Le générateur porte désormais une profondeur de retrait PAR SCHÉMA
+ * (cf. OPEN_SCHEMAS dans scripts/build-mcp-schemas.mjs) au lieu d'une règle globale.
+ *
+ * ── DEUX FORMES D'APPEL COEXISTENT, DÉLIBÉRÉMENT ──────────────────────────────
+ * `bclaw_add_step` accepte la forme canonique `{ planId, data: {...} }` ET la forme
+ * historique `{ planId, text, assignee }`. Les deux sont publiées ; supprimer la seconde
+ * du schéma casserait les appelants existants. `title` reste un alias de `text`.
+ *
+ * ── CE QUI N'EST PAS RESSERRÉ ─────────────────────────────────────────────────
+ * `status` reste une chaîne libre bien que ses cinq valeurs soient énumérées dans sa
+ * description : en faire un enum serait un rejet nouveau sur des appels aujourd'hui
+ * acceptés, donc une décision à part entière.
+ */
+import { z } from 'zod';
+/** Identité de l'appelant — commune à toutes les familles migrées. */
+const CallerIdentity = {
+    agent: z.string().describe('Agent name.').optional(),
+    agentId: z.string().describe('Registered agent id.').optional(),
+};
+/**
+ * Charge utile canonique d'un step. Ses champs sont TOUS optionnels et l'objet ne porte
+ * PAS d'`additionalProperties` — voir l'en-tête : c'est ce sous-objet qui a révélé que la
+ * profondeur de retrait devait être décidée par schéma.
+ */
+const AddStepDataSchema = z
+    .object({
+    text: z.string().describe('Step description.').optional(),
+    title: z.string().describe('Alias for text.').optional(),
+    assignee: z.string().describe('Optional assignee.').optional(),
+    estimated_effort: z
+        .number()
+        .describe('Step-level estimate in minutes (pln#495). A duration string like "2h"/"30m" is also accepted and coerced.')
+        .optional(),
+    actual_effort: z
+        .string()
+        .describe('Step-level actual effort, free-form ("45m", "2h"), parsed when the estimation report runs.')
+        .optional(),
+})
+    .describe('Canonical step payload: { text, title?, assignee? }. title is accepted as an alias for text.');
+export const AddStepRequestSchema = z.object({
+    planId: z.string().describe('Plan item ID.'),
+    data: AddStepDataSchema.optional(),
+    // Forme HISTORIQUE, conservée : elle est publiée et des appelants s'en servent.
+    text: z.string().describe('Legacy top-level step description; prefer data.text.').optional(),
+    ...CallerIdentity,
+    assignee: z
+        .string()
+        .describe('Legacy top-level optional assignee; prefer data.assignee.')
+        .optional(),
+    project: z
+        .string()
+        .describe('Optional: name (or path/basename) of a linked project to add the step in. Defaults to the current project. Same resolution as canonical-grammar tools — accepts cross_project_links and workspace store-chain children.')
+        .optional(),
+});
+export const UpdateStepRequestSchema = z.object({
+    planId: z.string().describe('Plan item ID.'),
+    stepId: z.string().describe('Step ID to update.'),
+    // Chaîne libre, PAS un enum : les cinq valeurs sont documentées, pas imposées.
+    status: z
+        .string()
+        .describe('New status: todo, in_progress, testing, done, blocked.')
+        .optional(),
+    text: z.string().describe('New step text.').optional(),
+    assignee: z.string().describe('New assignee (empty string to unassign).').optional(),
+    estimated_effort: z
+        .number()
+        .describe('Step-level estimate in minutes (pln#495); a duration string is also coerced.')
+        .optional(),
+    actual_effort: z
+        .string()
+        .describe('Step-level actual effort, free-form ("45m", "2h").')
+        .optional(),
+    ...CallerIdentity,
+    project: z
+        .string()
+        .describe('Optional: name of a linked project to update the step in. Defaults to the current project.')
+        .optional(),
+});
+export const CompleteStepRequestSchema = z.object({
+    planId: z.string().describe('Plan item ID.'),
+    stepId: z.string().describe('Step ID to complete.'),
+    ...CallerIdentity,
+    project: z
+        .string()
+        .describe('Optional: name of a linked project to complete the step in. Defaults to the current project.')
+        .optional(),
+});
+export const DeleteStepRequestSchema = z.object({
+    planId: z.string().describe('Plan item ID.'),
+    stepId: z.string().describe('Step ID to delete.'),
+    ...CallerIdentity,
+    project: z
+        .string()
+        .describe('Optional: name of a linked project to delete the step from. Defaults to the current project.')
+        .optional(),
+});
+//# sourceMappingURL=step-request-schema.js.map

package/dist/core/store-resolution.js

@@ -102,11 +102,7 @@ export function resolveTargetStore(cwd = process.cwd(), target = 'local', option
 export function resolveEffectiveCwd(options = {}) {
     return resolveEffectiveCwdInfo(options).cwd;
 }
-/**
- * Resolve the effective cwd and explain which selector won. Use this for MCP
- * facades that must echo their project scope to avoid silent cross-project reads.
- */
-export function resolveEffectiveCwdInfo(options = {}) {
+function resolveEffectiveCwdInner(options, observed) {
     const baseCwd = path.resolve(options.baseCwd ?? process.cwd());
     // 1. Explicit --cwd flag
     if (options.explicitCwd) {
@@ -192,9 +188,18 @@ export function resolveEffectiveCwdInfo(options = {}) {
         // A named id is an exact-file lookup, so the record IS the one asked for; the
         // pid check covers the unnamed case. Anything else is a weak adoption.
         if (opts?.requireStrongIdentity && !explicitSessionId && session.pid !== process.pid) {
+            // Observe avant de rejeter : une session d'un AUTRE processus qui designe un autre
+            // projet est exactement le cas ou une ecriture peut partir ailleurs en silence.
+            const weak = session.active_project;
+            if (weak && !observed.sessionProject)
+                observed.sessionProject = { path: weak.path, name: weak.name };
             return undefined;
         }
         const sp = session.active_project;
+        // Retenu AVANT le controle d'adoption : un record trouvable qui designe un projet
+        // compte comme observation meme quand il n'est pas retenu.
+        if (sp && !observed.sessionProject)
+            observed.sessionProject = { path: sp.path, name: sp.name };
         if (sp && fs.existsSync(path.join(sp.path, MEMORY_DIR, 'config.yaml'))) {
             return { cwd: sp.path, active_source: 'session', resolved_project: { path: sp.path, name: sp.name } };
         }
@@ -287,6 +292,30 @@ export function resolveEffectiveCwdInfo(options = {}) {
     // 7. Default
     return { cwd: anchorCwd, active_source: 'cwd', resolved_project: projectInfo(anchorCwd) };
 }
+/**
+ * Point d'entree unique de la resolution (pln#648 SUITE d).
+ *
+ * Enrichit le verdict d'un signal de divergence quand un record de session trouvable
+ * designait un AUTRE projet que celui retenu. Le calcul est purement local : la sonde a
+ * deja lu le record, aucune lecture disque n'est ajoutee.
+ */
+export function resolveEffectiveCwdInfo(options = {}) {
+    const observed = {};
+    const result = resolveEffectiveCwdInner(options, observed);
+    const seen = observed.sessionProject;
+    if (!seen || result.active_source === 'session')
+        return result;
+    if (path.resolve(seen.path) === path.resolve(result.cwd))
+        return result;
+    return {
+        ...result,
+        session_divergence: {
+            session_project_path: seen.path,
+            session_project_name: seen.name,
+            resolved_via: result.active_source,
+        },
+    };
+}
 function projectInfo(cwd) {
     try {
         const config = loadConfig(cwd);

package/dist/core/warnings.js

@@ -48,6 +48,43 @@ export function pushStructuredWarning(warnings, details, input) {
 // Each owns its recovery path, which is the entire point of the structured
 // channel: `scope_already_claimed` used to be a dead-end string; now it names
 // the two calls that resolve it.
+/**
+ * `autoExecute: true` sur `intent='consult'` — un no-op, dit sur le canal STRUCTURE
+ * (pln#626 phase 3).
+ *
+ * POURQUOI PAS UNE ERREUR DURE. Le plan laissait le choix entre refuser et implementer un
+ * vrai « consult run ». Refuser casserait des appelants existants pour un drapeau qui n'a
+ * jamais rien fait, et l'implementer est une decision produit — le plan lui-meme penche
+ * pour le spawn sur les cibles spawn-only, ce qui depasse une correction de surface.
+ *
+ * POURQUOI PAS SEULEMENT UN TEXTE. Phase 1 avait deja pousse un avertissement en texte
+ * libre, ce qui vaut mieux que le silence mais reste illisible pour une machine : un agent
+ * ne peut pas brancher dessus. Le code structure rend le refus DETECTABLE, et la
+ * next_action nomme les deux chemins qui spawnent reellement.
+ *
+ * C'est la moitie de la phase 3 qui ne demande aucun arbitrage : rendre le no-op
+ * observable. L'autre moitie — refuser ou spawner — reste au produit.
+ */
+export function consultAutoExecuteNoOpWarning() {
+    return {
+        code: 'auto_execute_ignored_on_consult',
+        message: "autoExecute has no effect on intent='consult': consult delivers the RFC to the target "
+            + 'inbox(es) only and never spawns an agent — targets pick it up via their own bclaw_work.',
+        data: { intent: 'consult', auto_execute_honored: false },
+        next_actions: [
+            {
+                tool: 'bclaw_dispatch',
+                args: { intent: 'execute' },
+                when: 'to actually spawn workers on a sequence lane',
+            },
+            {
+                tool: 'bclaw_coordinate',
+                args: { intent: 'assign' },
+                when: 'to hand one scope to one agent and have it started',
+            },
+        ],
+    };
+}
 export function agentValidationFailedWarning(input) {
     return {
         code: 'agent_validation_failed',