brainclaw 1.24.0 → 1.26.0

package/dist/core/code-map/types.js

@@ -110,6 +110,30 @@ export const EdgeSchema = z.object({
     })
         .nullable()
         .optional(),
+    /**
+     * Optional provenance for P4 usage edges. It lets the project resolver replace
+     * only import-derived usages on a later refresh without deleting lexical calls
+     * already proven inside the source file.
+     */
+    origin: z.enum(['usage_local', 'usage_import', 'usage_textual']).optional(),
+});
+/** P4's three deliberately non-interchangeable usage classifications. */
+export const UsageKindSchema = z.enum(['calls', 'references', 'possible_textual_match']);
+/**
+ * An import-binding usage that is lexical in one file but needs the project-wide
+ * import pass before its target symbol is known. This is persisted on the shard,
+ * never surfaced as a `calls`/`references` edge until that target is unique.
+ */
+export const ReferenceCandidateSchema = z.object({
+    from: z.string(),
+    kind: z.enum(['calls', 'references']),
+    module: z.string(),
+    imported_name: z.string(),
+    confidence: z.number().default(1.0),
+    source: z.object({
+        path: z.string(),
+        line: z.number().int().nullable().optional(),
+    }),
 });
 // --- Per-file shard (spec §5.3) ---
 export const ShardFreshnessSchema = z.object({
@@ -136,6 +160,8 @@ export const FileShardSchema = z.object({
     freshness: ShardFreshnessSchema,
     nodes: z.array(NodeSchema).default([]),
     edges: z.array(EdgeSchema).default([]),
+    /** Deferred P4 imported-binding usages; resolved by the whole-project pass. */
+    reference_candidates: z.array(ReferenceCandidateSchema).optional(),
     diagnostics: z.array(z.unknown()).default([]),
 });
 // --- manifest.json (spec §5.1) ---
@@ -243,6 +269,19 @@ export const ImportsIndexSchema = z.object({
     entries: z.record(z.string(), z.array(ImportIndexEntrySchema)).default({}),
 });
 // --- resolution index (P1d) — reverse dependency maps over the P1c graph ---
+/**
+ * One concrete resolved edge which made an importer depend on a target. Kept
+ * alongside the compact aggregate fields on {@link DependencyIndexEntrySchema}
+ * so impact analysis can explain every relation without re-reading all shards.
+ */
+export const DependencyReasonSchema = z.object({
+    kind: z.enum(['resolves_to', 'imports_symbol']),
+    module: z.string().optional(),
+    imported: z.array(z.string()).default([]),
+    confidence: z.number().optional(),
+    /** Source line of the import edge when the extractor supplied one. */
+    source_line: z.number().int().nullable().optional(),
+});
 /**
  * One DEPENDENT of a target (file or symbol): the importing file + enough metadata
  * to lazy-validate it (file_id) and explain WHY it appears (module specifier the
@@ -259,6 +298,8 @@ export const DependencyIndexEntrySchema = z.object({
     imported: z.array(z.string()).default([]),
     /** Resolution edge confidence (inherited from the A file resolution). */
     confidence: z.number().optional(),
+    /** Every resolved edge merged into this importer/target row, source ordered. */
+    reasons: z.array(DependencyReasonSchema).default([]),
 });
 /**
  * Reverse dependency index (P1d): "who imports this target". Built at refresh from
@@ -267,6 +308,19 @@ export const DependencyIndexEntrySchema = z.object({
  * read-path scan of every shard. Forward deps are read straight from a target's own
  * shard, so they need no index.
  */
+/** A persisted, high-confidence P4 usage cause targeting one symbol. */
+export const UsageReasonSchema = z.object({
+    kind: z.enum(['calls', 'references']),
+    caller_node_id: z.string(),
+    confidence: z.number(),
+    source_line: z.number().int().nullable().optional(),
+});
+/** One importing file's lexical uses of a target symbol. */
+export const UsageIndexEntrySchema = z.object({
+    path: z.string(),
+    file_id: Sha256Hash,
+    reasons: z.array(UsageReasonSchema).default([]),
+});
 export const ResolutionIndexSchema = z.object({
     schema_version: z.number().int().default(CODE_MAP_SCHEMA_VERSION),
     project_id: z.string(),
@@ -275,6 +329,8 @@ export const ResolutionIndexSchema = z.object({
     dependents_by_file: z.record(z.string(), z.array(DependencyIndexEntrySchema)).default({}),
     /** Keys are TARGET symbol node ids (reverse `imports_symbol`). */
     dependents_by_symbol: z.record(z.string(), z.array(DependencyIndexEntrySchema)).default({}),
+    /** Keys are TARGET symbol ids; only proven P4 call/reference usages are indexed. */
+    usages_by_symbol: z.record(z.string(), z.array(UsageIndexEntrySchema)).default({}),
 });
 // --- .lock (spec §5.8) ---
 export const CodeLockSchema = z.object({
@@ -292,20 +348,25 @@ export const CodeLockSchema = z.object({
     stale_after_ms: z.number().int(),
 });
 /**
- * spec §9 (pln#601) — the COARSE, surface-uniform rollup of the detailed 7-value
- * {@link FreshnessStatus}. find/brief/status/work each expose their own precise
- * status, but an agent wants one consistent top-line signal to decide "trust this
- * or refresh first" without memorizing which `stale_*` variant applies. `coarse`
- * collapses the detail: every `stale_*` → `stale`, `missing_index` → `missing`,
- * `partial`/`fresh` unchanged. Derived (never independently authored) via
- * `coarseFreshness()` so it can never contradict `status`.
+ * The one agent-facing freshness signal. Detailed index causes and per-call
+ * spot-check observations intentionally live under `FreshnessBadge.details`.
  */
 export const CoarseFreshnessSchema = z.enum(['fresh', 'stale', 'partial', 'missing']);
 /** Freshness badge attached to every agent-facing read response (spec §9). */
 export const FreshnessBadgeSchema = z.object({
+    /**
+     * Stable top-line signal shared by work/status/find/brief. It MUST NOT be
+     * changed by a query's bounded spot-check: that observation belongs in
+     * `details.spot_check`, so an agent never sees incompatible badges for the
+     * same index state.
+     */
+    freshness: CoarseFreshnessSchema,
+    /**
+     * Detailed index classification retained for API compatibility. It describes
+     * the index only (never a query spot-check); new consumers branch on
+     * `freshness` and inspect `details` for the reason.
+     */
     status: FreshnessStatusSchema,
-    /** pln#601 — coarse rollup of `status`, uniform across all read surfaces. */
-    coarse: CoarseFreshnessSchema.optional(),
     details: z.record(z.string(), z.unknown()).default({}),
 });
 //# sourceMappingURL=types.js.map

package/dist/core/code-map/vocabulary.js

@@ -47,6 +47,12 @@ export const UniversalEdgeKinds = [
     'resolves_to',
     'imports_symbol',
     'tests_for',
+    // P4 usages: a direct lexical invocation, a non-call lexical binding use, or
+    // an explicitly low-confidence text/property hint. Only `calls` is a proven
+    // invocation; consumers must never promote `possible_textual_match`.
+    'calls',
+    'references',
+    'possible_textual_match',
     'extends',
     'implements',
     'annotates',

package/dist/core/code-map/work-section.js

@@ -18,7 +18,7 @@
  *                      bclaw_work beyond that bounded wait (rule §6 rule 8).
  */
 import { readManifest } from './store.js';
-import { withCoarse } from './freshness.js';
+import { withFreshness } from './freshness.js';
 import { readCodeLock, isLockAbandoned } from './lock.js';
 import { codeMapDir, lockPath } from './paths.js';
 import { JsonlBackend } from './backend.js';
@@ -108,9 +108,9 @@ export async function codeMapWorkSection(cwd, opts = {}) {
                     return {
                         enabled: true,
                         matches: out.matches,
-                        freshness_badge: withCoarse({
+                        freshness_badge: withFreshness({
                             status: 'partial',
-                            details: { partial_reason: 'code_map_lock_active', lock_wait_ms: lockWaitMs },
+                            details: { spot_check: { status: 'partial', partial_reason: 'code_map_lock_active' }, lock_wait_ms: lockWaitMs },
                         }),
                         lock_wait_ms: lockWaitMs,
                     };
@@ -122,9 +122,9 @@ export async function codeMapWorkSection(cwd, opts = {}) {
             return {
                 enabled: true,
                 matches: [],
-                freshness_badge: withCoarse({
+                freshness_badge: withFreshness({
                     status: 'partial',
-                    details: { partial_reason: 'code_map_lock_active', lock_wait_ms: lockWaitMs },
+                    details: { spot_check: { status: 'partial', partial_reason: 'code_map_lock_active' }, lock_wait_ms: lockWaitMs },
                 }),
                 lock_wait_ms: lockWaitMs,
             };
@@ -136,7 +136,7 @@ export async function codeMapWorkSection(cwd, opts = {}) {
             enabled: true,
             missing_index: 'Code Map index is empty for this project. Run `brainclaw code-map refresh --all` (or bclaw_code_refresh) before relying on find/brief.',
             matches: [],
-            freshness_badge: withCoarse({ status: 'missing_index', details: {} }),
+            freshness_badge: withFreshness({ status: 'missing_index', details: {} }),
             ...(lockWaitMs !== undefined ? { lock_wait_ms: lockWaitMs } : {}),
         };
     }
@@ -144,16 +144,14 @@ export async function codeMapWorkSection(cwd, opts = {}) {
     // lazy read-path check (§6.1) returns the true freshness badge, so stale
     // results are surfaced WITH the stale badge rather than hidden.
     if (!query) {
+        // Use the same read-only index observation as bclaw_code_status. This keeps
+        // bclaw_work aligned with status/find/brief for git-HEAD drift too, while
+        // still avoiding any lazy refresh or source parsing.
+        const status = await backend.status({ cwd: ctx.cwd, preferredDirName: ctx.preferredDirName });
         return {
             enabled: true,
             matches: [],
-            freshness_badge: withCoarse({
-                status: manifest.freshness.status,
-                details: {
-                    stale_file_count: manifest.freshness.stale_file_count,
-                    partial_reason: manifest.freshness.partial_reason,
-                },
-            }),
+            freshness_badge: status.freshness_badge,
             ...(lockWaitMs !== undefined ? { lock_wait_ms: lockWaitMs } : {}),
         };
     }
@@ -193,7 +191,7 @@ export function codeMapRefreshNextActions(section) {
             },
         ];
     }
-    if (section.freshness_badge?.status?.startsWith('stale_')) {
+    if (section.freshness_badge?.freshness === 'stale') {
         return [
             {
                 tool: 'bclaw_code_refresh',

package/dist/core/context-diff.js

@@ -1,7 +1,7 @@
 import fs from 'node:fs';
 import { readAuditLog } from './audit.js';
 import { listCandidates } from './candidates.js';
-import { entityRecordPaths } from './io.js';
+import { sessionSnapshotRecordPaths } from './io.js';
 import { loadVersionedJsonFile } from './migration.js';
 import { buildNotificationSummary, hasEventCursor, readUnseenEvents, seedCursorToEnd } from './event-log.js';
 import { SessionSnapshotSchema } from './schema.js';
@@ -44,11 +44,25 @@ export function resolveContextDiffSince(options) {
  * Uses the shared primitive rather than a fourth hand-rolled pair of paths (io.ts).
  */
 function loadSessionSnapshot(sessionId, cwd) {
-    for (const snapshotPath of entityRecordPaths('sessions', sessionId, cwd ?? process.cwd())) {
+    // pln#670 — snapshots carry a type-suffixed name (`<id>.snapshot.json`);
+    // the helper also probes the pre-split `<id>.json` layouts.
+    for (const snapshotPath of sessionSnapshotRecordPaths(sessionId, cwd ?? process.cwd())) {
         if (!fs.existsSync(snapshotPath))
             continue;
         try {
-            return SessionSnapshotSchema.parse(loadVersionedJsonFile('session_snapshot', snapshotPath).document);
+            // Deliberately NOT type-strict (pln#649 + pln#670): this reader answers
+            // "when did session X start" to anchor the diff window, and a
+            // current_session record for the same id is an equally authoritative
+            // source of `started_at`. The suffixed probes come first, so a real
+            // snapshot (richer: context_target, git_sha) still wins when both exist.
+            // Contrast with session-start's loadSessionSnapshot, which must stay
+            // strict — its consumers treat the record as a genuine snapshot.
+            const snapshot = SessionSnapshotSchema.parse(loadVersionedJsonFile('session_snapshot', snapshotPath).document);
+            // A suffix-bearing lookup can construct another snapshot's path (codex
+            // review). Its started_at is useful only when the stored identity matches.
+            if (snapshot.session_id !== sessionId)
+                continue;
+            return snapshot;
         }
         catch {
             // An unparseable record in one layout must not mask a good one in the other.

package/dist/core/entity-operations.js

@@ -28,7 +28,7 @@ import { deleteAssignment, listAssignments, loadAssignment, saveAssignment, tran
 import { listAgentRuns } from './agentruns.js';
 import { reconcileAgentRun, reconcileDeadPidRunningAgentRunAtRead, reconcileStrandedFailureClaimAtRead, TERMINAL_STATUSES } from './agentrun-reconciler.js';
 import { isObserverMode } from './observer-mode.js';
-import { deleteRuntimeNote, listRuntimeNotes, saveRuntimeNote, } from './runtime.js';
+import { deleteRuntimeNote, listRuntimeNotes, parkRuntimeNoteBackup, saveRuntimeNote, } from './runtime.js';
 import { createSequence, deleteSequence, listSequences, updateSequence, } from './sequence.js';
 import { createConstraint, createDecision, createTrap, } from './operations/memory-write.js';
 import { deleteMemoryItem, findMemoryItemInChain, updateMemoryItem, } from './operations/memory-mutation.js';
@@ -853,10 +853,22 @@ export function removeEntity(name, id, cwd, purge = false) {
             const note = notes.find((n) => n.id === id);
             if (!note)
                 throw new EntityNotFoundError(name, id);
+            // trp_dc9ca61e — the tool contract says "archives by default", but this
+            // path hard-deleted regardless of `purge` (runtime_note has no lifecycle,
+            // so there was no soft state to land in). Default remove now parks the
+            // raw record under gc-backups — the same net the retention sweeps use —
+            // and fails CLOSED when the park is impossible: silently downgrading an
+            // archive into a hard-delete is the defect being fixed.
+            if (!purge) {
+                const backupPath = parkRuntimeNoteBackup(note, cwd);
+                if (!backupPath) {
+                    throw new Error(`runtime_note '${id}' could not be archived to gc-backups; pass purge:true to hard-delete`);
+                }
+            }
             const ok = deleteRuntimeNote(note, cwd);
             if (!ok)
                 throw new EntityNotFoundError(name, id);
-            return { entity: name, id, archived: false, purged: true };
+            return { entity: name, id, archived: !purge, purged: purge };
         }
         case 'candidate': {
             // Remove = archive to rejected. `purge` would delete the file; not exposed yet.

package/dist/core/federation-pull.js

@@ -10,8 +10,14 @@ import { verifyInboundBatch } from './federation-inbound.js';
 import { loadEpochPrivateKey } from './federation-keyring.js';
 import { localIdForOpaque, rememberOpaqueId } from './federation-opaque-ids.js';
 import { addStep, createPlan, updatePlan, updateStep } from './operations/plan.js';
+import { createConstraint, createDecision, createTrap } from './operations/memory-write.js';
+import { updateMemoryItem } from './operations/memory-mutation.js';
+import { createSequence, updateSequence } from './sequence.js';
+import { generateRuntimeNoteId, listRuntimeNotes, saveRuntimeNote } from './runtime.js';
+import { HandoffSchema } from './schema.js';
+import { generateIdWithLabel, nowISO } from './ids.js';
+import { mutateState } from './state.js';
 import { memoryDir, writeFileAtomic } from './io.js';
-import { nowISO } from './ids.js';
 import { loadConnectionState, recordRevision, saveConnectionState } from './federation-state.js';
 const INBOUND_SCHEMA = 'brainclaw.federation-inbound-pull/v1';
 const INBOUND_FILE = 'inbound-pull.json';
@@ -164,6 +170,55 @@ function tagsOf(content) {
 function priorityOf(value) {
     return value === 'low' || value === 'medium' || value === 'high' || value === 'critical' ? value : undefined;
 }
+function statusOf(value, accepted) {
+    return typeof value === 'string' && accepted.includes(value) ? value : undefined;
+}
+function authorOf(accepted) {
+    // L'identité de signature a été vérifiée par verifyInboundBatch contre le roster :
+    // elle est sûre à conserver comme provenance locale, sans prétendre connaître un nom.
+    return `federation:${accepted.envelope.origin_sig.key_id}`;
+}
+function textAndTagsPatch(text, tags) {
+    return { text, ...(tags ? { tags } : {}) };
+}
+/**
+ * Handoff has no standalone create operation yet. This goes through mutateState, the same
+ * canonical mutation pipeline used by its lifecycle operations: it never writes an entity
+ * JSON file directly. The remote projection does not carry `from`/`to`, so their local
+ * receiver values deliberately describe the federation hop rather than invent source data.
+ */
+function saveFederatedHandoff(input, cwd) {
+    if (input.id) {
+        mutateState((state) => {
+            const current = state.open_handoffs.find((handoff) => handoff.id === input.id);
+            if (!current)
+                throw new Error(`handoff with id '${input.id}' not found locally despite its opaque mapping`);
+            const next = HandoffSchema.parse({
+                ...current,
+                text: input.text,
+                tags: input.tags ?? current.tags,
+                status: input.status ?? current.status,
+            });
+            Object.assign(current, next);
+        }, cwd);
+        return input.id;
+    }
+    const { id, short_label } = generateIdWithLabel('open_handoffs', cwd);
+    mutateState((state) => {
+        state.open_handoffs.push(HandoffSchema.parse({
+            id,
+            short_label,
+            from: input.author,
+            to: 'local',
+            text: input.text,
+            created_at: nowISO(),
+            author: input.author,
+            status: input.status ?? 'open',
+            tags: input.tags ?? [],
+        }));
+    }, cwd);
+    return id;
+}
 class DeferredMaterialization extends Error {
 }
 /**
@@ -213,8 +268,101 @@ function materialize(accepted, state, cwd) {
         rememberOpaqueId(state.cloud_project_id, created.stepId, opaque, cwd);
         return;
     }
-    // Les familles sans mutation canonique correspondante sont différées. Les accepter dans
-    // high_water les ferait disparaître du feed sans jamais atteindre le magasin local.
+    const author = authorOf(accepted);
+    const text = content['text'];
+    if (accepted.kind === 'decision') {
+        if (existing) {
+            updateMemoryItem({ id: existing, type: 'decision', patch: textAndTagsPatch(text, tags) }, cwd);
+            return;
+        }
+        const created = createDecision({ text, author, tags }, cwd);
+        rememberOpaqueId(state.cloud_project_id, created.id, opaque, cwd);
+        return;
+    }
+    if (accepted.kind === 'constraint') {
+        const status = statusOf(accepted.envelope.meta.status.object, ['active', 'resolved', 'expired']);
+        if (existing) {
+            updateMemoryItem({
+                id: existing,
+                type: 'constraint',
+                patch: { ...textAndTagsPatch(text, tags), ...(status ? { status } : {}) },
+            }, cwd);
+            return;
+        }
+        const created = createConstraint({ text, author, tags }, cwd);
+        // createConstraint correctly owns ID/provenance creation; its lifecycle starts at active,
+        // so apply a projected terminal state through the same mutation path afterwards.
+        if (status && status !== 'active') {
+            updateMemoryItem({ id: created.id, type: 'constraint', patch: { status } }, cwd);
+        }
+        rememberOpaqueId(state.cloud_project_id, created.id, opaque, cwd);
+        return;
+    }
+    if (accepted.kind === 'trap') {
+        const status = statusOf(accepted.envelope.meta.status.object, ['active', 'resolved', 'expired']);
+        const severity = accepted.envelope.meta.priority === 'low' || accepted.envelope.meta.priority === 'medium'
+            ? accepted.envelope.meta.priority
+            : accepted.envelope.meta.priority === 'high' || accepted.envelope.meta.priority === 'critical'
+                ? 'high'
+                : undefined;
+        if (existing) {
+            updateMemoryItem({
+                id: existing,
+                type: 'trap',
+                patch: {
+                    ...textAndTagsPatch(text, tags),
+                    ...(status ? { status } : {}),
+                    ...(severity ? { severity } : {}),
+                },
+            }, cwd);
+            return;
+        }
+        const created = createTrap({ text, author, tags, status, severity }, cwd);
+        rememberOpaqueId(state.cloud_project_id, created.id, opaque, cwd);
+        return;
+    }
+    if (accepted.kind === 'handoff') {
+        const status = statusOf(accepted.envelope.meta.status.object, ['open', 'accepted', 'closed']);
+        const id = saveFederatedHandoff({ id: existing, text, tags, status, author }, cwd);
+        if (!existing)
+            rememberOpaqueId(state.cloud_project_id, id, opaque, cwd);
+        return;
+    }
+    if (accepted.kind === 'sequence') {
+        const status = statusOf(accepted.envelope.meta.status.object, ['draft', 'active', 'archived']);
+        if (existing) {
+            updateSequence({ id: existing, name: text, tags, status }, cwd);
+            return;
+        }
+        const created = createSequence({ name: text, author, tags, status }, cwd);
+        rememberOpaqueId(state.cloud_project_id, created.id, opaque, cwd);
+        return;
+    }
+    if (accepted.kind === 'runtime_note') {
+        if (existing) {
+            const current = listRuntimeNotes({ visibility: 'all', includeAllHosts: true }, cwd)
+                .find((note) => note.id === existing);
+            if (!current)
+                throw new Error(`runtime_note with id '${existing}' not found locally despite its opaque mapping`);
+            saveRuntimeNote({ ...current, text, tags: tags ?? current.tags }, cwd);
+            return;
+        }
+        const id = generateRuntimeNoteId();
+        saveRuntimeNote({
+            id,
+            agent: 'federation',
+            agent_id: accepted.envelope.origin_sig.key_id,
+            text,
+            created_at: nowISO(),
+            tags: tags ?? [],
+            visibility: 'shared',
+            note_type: 'observation',
+        }, cwd);
+        rememberOpaqueId(state.cloud_project_id, id, opaque, cwd);
+        return;
+    }
+    // Les familles hors projection restent dans le journal : les accepter dans high_water
+    // les ferait disparaître du feed sans jamais atteindre le magasin local.
     throw new DeferredMaterialization(`kind '${accepted.kind}' sans mutation canonique de réception.`);
 }
 /**

package/dist/core/federation-push.js

@@ -179,16 +179,22 @@ export async function pushPending(options = {}) {
         throw new Error('Adresse du cloud inconnue : passez --url. Elle n\'est pas conservée par l\'appairage ' +
             '(état de connexion sans champ d\'URL), et aucune adresse n\'est devinée.');
     }
+    const pending = list('pending', cwd);
+    // File vide = rien à signer : sortir AVANT de résoudre l'identité. Le signataire est
+    // déduit de la première entrée pending ; le chercher sur une file vide transformait
+    // « tout est déjà parti » en erreur d'identité — vécu le 2026-08-10, juste après un
+    // envoi complet dont il ne restait que des conflits.
+    if (pending.length === 0)
+        return result;
     // L'identité SIGNATAIRE du transport : celle de l'agent qui a produit les enveloppes.
     // Elle est portée par l'entrée d'outbox, donc le transport n'a pas à deviner qui signe.
-    const agentId = options.agentId ?? list('pending', cwd)[0]?.origin_agent_id;
+    const agentId = options.agentId ?? pending[0]?.origin_agent_id;
     const identity = agentId ? loadAgentSigningKey(agentId) : undefined;
     if (!identity) {
         throw new Error('Identité de signature introuvable : le cloud vérifie une signature de TRANSPORT ' +
             'liant envelope_id, rev et base_rev. Sans elle, chaque envoi est refusé en 422.');
     }
     const identityPem = identity.privateKeyPem;
-    const pending = list('pending', cwd);
     const batch = options.limit ? pending.slice(0, options.limit) : pending;
     result.attempted = batch.length;
     if (options.dryRun)
@@ -214,7 +220,14 @@ export async function pushPending(options = {}) {
             // réel en écrasement silencieux du travail d'un autre appareil.
             if (res.status === 409) {
                 const detail = (await res.clone().json().catch(() => ({})));
-                const expected = detail['expected_base_rev'] ?? detail['expected'];
+                // `current_head_rev` est le nom que le serveur DÉPLOYÉ répond (projection.ts,
+                // REV_CONFLICT). Les deux autres sont des noms historiques gardés en repli.
+                // Dérive constatée le 2026-08-10 : le client lisait `expected_base_rev` sur une
+                // réponse qui ne l'a jamais porté — le recalage ne se déclenchait donc JAMAIS et
+                // chaque mise à jour finissait en conflit. Le test unitaire rejoue depuis la
+                // forme de réponse RÉELLE du serveur ; leçon dec#160/162, un contrat inter-
+                // services ne se vérifie que contre le service.
+                const expected = detail['current_head_rev'] ?? detail['expected_base_rev'] ?? detail['expected'];
                 if (typeof expected === 'string' || typeof expected === 'number') {
                     // On RESIGNE avec la nouvelle base_rev : c'est précisément ce que la signature
                     // au niveau du transport rend possible, et qu'une signature figée à l'émission

package/dist/core/hint-aging.js

@@ -123,7 +123,10 @@ export function ageStaleWarnings(warnings, cwd, options = {}) {
             const overflow = ids.length - shown.length;
             return `${ids.length} ${entity}${ids.length === 1 ? '' : 's'}: ${shown.join(', ')}${overflow > 0 ? ` +${overflow} more` : ''}`;
         });
-        aggregate = `${folded.length} stale item${folded.length === 1 ? '' : 's'} you've already been offered (${parts.join('; ')}) — bclaw_get each id to review, or bclaw_transition to retire.`;
+        // trp_dc9ca61e — do not recommend bclaw_transition for runtime_notes: they
+        // have no lifecycle and the call errors. bclaw_remove (archive by default)
+        // is their retirement path.
+        aggregate = `${folded.length} stale item${folded.length === 1 ? '' : 's'} you've already been offered (${parts.join('; ')}) — bclaw_get each id to review; retire with bclaw_transition, or bclaw_remove for runtime_notes (no lifecycle).`;
     }
     return { warnings: detail, aggregate, served_ids, folded_ids };
 }