brainclaw 1.20.0 → 1.20.1

package/dist/commands/export.js

@@ -6,7 +6,7 @@ import { loadConfig, saveConfig } from '../core/config.js';
 import { isAgentIntegrationName, upsertAgentIntegrationDeclaration } from '../core/agent-integrations.js';
 import { resolveInstructions, loadInstructions } from '../core/instructions.js';
 import { detectAiAgent } from '../core/ai-agent-detection.js';
-import { AGENT_EXPORT_REGISTRY, resolveExportTarget, resolveExportTargetByFormat, writeExportFile, writeLiveCompanionFile, buildHygieneSection, describeAutoConfigWrite, writeExportCompanionFiles, collectExportGitignoreEntries, ensureGitignoreEntries, BRAINCLAW_EXCLUSIVE_DIRECTORIES, } from '../core/agent-files.js';
+import { AGENT_EXPORT_REGISTRY, resolveExportTarget, resolveExportTargetByFormat, resolveLiveCompanionPath, writeExportFile, writeLiveCompanionFile, buildHygieneSection, describeAutoConfigWrite, writeExportCompanionFiles, collectExportGitignoreEntries, ensureGitignoreEntries, BRAINCLAW_EXCLUSIVE_DIRECTORIES, } from '../core/agent-files.js';
 import { buildCoordinationSnapshot } from '../core/coordination.js';
 import { listClaims } from '../core/claims.js';
 import { listCandidates } from '../core/candidates.js';
@@ -187,18 +187,23 @@ export function refreshLiveCompanions(cwd) {
         const instructions = getInstructionText({ project: undefined, agent: undefined }, effectiveCwd);
         const activeClaims = listClaims(effectiveCwd).filter((c) => c.status === 'active');
         const pendingCandidates = listCandidates('pending', effectiveCwd);
-        const seen = new Set();
-        const targets = AGENT_EXPORT_REGISTRY.filter((t) => {
-            if (seen.has(t.format))
-                return false;
-            seen.add(t.format);
-            return true;
-        });
         let written = 0;
         const errors = [];
         const liveGitignoreEntries = [];
-        for (const target of targets) {
+        // trp_6a49f976 F1 (codex review): dedupe by RESOLVED LIVE PATH, never by
+        // stable export format. Format-dedup dropped every agents-md agent after
+        // codex — including mistral-vibe, whose REGISTERED live companion
+        // (.vibe/live.md) then never got refreshed, while the stale-surface
+        // advisory told the operator `brainclaw refresh` would fix exactly that
+        // file. A path counts as taken only once something was actually RENDERED
+        // for it, so a tier with no live companion (codex, Tier A) does not shadow
+        // a rendering agent that shares its default path (hermes → AGENTS.live.md).
+        const renderedLivePaths = new Set();
+        for (const target of AGENT_EXPORT_REGISTRY) {
             try {
+                const livePath = resolveLiveCompanionPath(target.agentName, target.relativePath);
+                if (renderedLivePaths.has(livePath))
+                    continue;
                 const profile = getAgentCapabilityProfile(target.agentName);
                 if (!profile)
                     continue;
@@ -214,7 +219,8 @@ export function refreshLiveCompanions(cwd) {
                 };
                 const live = renderLiveSection(input);
                 if (!live)
-                    continue; // Tier A — no live companion needed
+                    continue; // no live companion for this tier
+                renderedLivePaths.add(livePath);
                 const writeResult = writeLiveCompanionFile(live.content, target.agentName, target.relativePath, effectiveCwd);
                 if (writeResult.created || writeResult.updated) {
                     written++;

package/dist/core/instruction-templates.js

@@ -220,15 +220,18 @@ function renderHeader(input) {
 function renderLiveHeader(input) {
     // pln#638 volet 2a — HONESTY FIX. This header used to say "auto-refreshed",
     // but regeneration is EXPLICIT: it happens on session-end, handoff, and
-    // `export --write`. An agent tier that never fires those events (no hooks, no
-    // MCP) read a file claiming to be fresh while being arbitrarily stale. A claim
-    // that is false for half the tiers is worse than no claim, so the header now
+    // `brainclaw refresh`. An agent tier that never fires those events (no hooks,
+    // no MCP) read a file claiming to be fresh while being arbitrarily stale. A
+    // claim that is false for half the tiers is worse than no claim, so the header
     // names the actual triggers and tells the reader how to force a refresh.
+    // trp_6a49f976: the 1.20.0 header cited `brainclaw export --write`, which the
+    // CLI rejects outright AND which never wrote a live companion — the honest
+    // recovery for THIS file is `brainclaw refresh`.
     // Guarded by tests/unit/guidance-engine-consistency.test.ts.
     return [
-        `> Brainclaw live state — do not edit. Regenerated on: session-end, handoff, \`brainclaw export --write\`.`,
+        `> Brainclaw live state — do not edit. Regenerated on: session-end, handoff, \`brainclaw refresh\`.`,
         `> Written by brainclaw v${input.brainclawVersion} at ${new Date().toISOString().slice(0, 19)}`,
-        `> Older than your last session? It is stale — run \`brainclaw export --write\` to refresh.`,
+        `> Older than your last session? It is stale — run \`brainclaw refresh\`.`,
     ].join('\n');
 }
 // Kept deliberately small (pln#542): entry point + grammar + escalation

package/dist/core/surface-freshness.js

@@ -3,7 +3,7 @@
  *
  * WHY THIS EXISTS. 2a made the live header HONEST: it stopped claiming
  * "auto-refreshed" and started naming its real triggers (session-end, handoff,
- * `export --write`) plus the version and timestamp that wrote it. Honesty alone
+ * `brainclaw refresh`) plus the version and timestamp that wrote it. Honesty alone
  * does not help an agent tier that never fires any of those triggers, though — it
  * just tells that tier, truthfully, that the file might be arbitrarily old. 2b
  * closes the loop by USING the stamp: compare it against the running version and
@@ -63,16 +63,23 @@ export function assessSurfaceFreshness(content, currentVersion) {
         return { kind: 'fresh', version };
     return { kind: 'stale', stampedVersion: version, currentVersion };
 }
+/** The command that regenerates every stable surface. `export --write` alone is rejected by the CLI (a mode flag is required — see runExport). */
+export const STABLE_SURFACE_REFRESH_COMMAND = 'brainclaw export --all --write';
+/** The command that regenerates every live companion. */
+export const LIVE_SURFACE_REFRESH_COMMAND = 'brainclaw refresh';
 /**
  * The set of surfaces this project could have on disk, derived from the export
  * registries rather than listed here. Deduplicated because several agents share
- * a target (four of them write AGENTS.md).
+ * a target (four of them write AGENTS.md); a path claimed by both registries
+ * counts as stable, since `export` regenerates it.
  */
-function candidateSurfacePaths() {
-    return [...new Set([
-            ...AGENT_EXPORT_REGISTRY.map((t) => t.relativePath),
-            ...LIVE_COMPANION_EXPORT_REGISTRY.map((t) => t.relativePath),
-        ])];
+function candidateSurfaces() {
+    const stable = new Set(AGENT_EXPORT_REGISTRY.map((t) => t.relativePath));
+    const live = new Set(LIVE_COMPANION_EXPORT_REGISTRY.map((t) => t.relativePath));
+    return [
+        ...[...stable].map((relativePath) => ({ relativePath, kind: 'stable' })),
+        ...[...live].filter((p) => !stable.has(p)).map((relativePath) => ({ relativePath, kind: 'live' })),
+    ];
 }
 /**
  * Scan the project's generated surfaces and report the ones stamped with a
@@ -85,7 +92,7 @@ function candidateSurfacePaths() {
  */
 export function reconcileSurfaceFreshness(cwd, currentVersion) {
     const result = { stale: [], freshCount: 0, unknownCount: 0 };
-    for (const relativePath of candidateSurfacePaths()) {
+    for (const { relativePath, kind } of candidateSurfaces()) {
         const full = path.join(cwd, relativePath);
         let head;
         try {
@@ -107,7 +114,7 @@ export function reconcileSurfaceFreshness(cwd, currentVersion) {
         }
         const verdict = assessSurfaceFreshness(head, currentVersion);
         if (verdict.kind === 'stale')
-            result.stale.push({ relativePath, stampedVersion: verdict.stampedVersion });
+            result.stale.push({ relativePath, stampedVersion: verdict.stampedVersion, kind });
         else if (verdict.kind === 'fresh')
             result.freshCount += 1;
         else
@@ -119,31 +126,48 @@ export function reconcileSurfaceFreshness(cwd, currentVersion) {
  * Build the advisory for a stale-surface scan, or `undefined` when there is
  * nothing to say.
  *
- * NO `next_actions`, deliberately. The recovery is `brainclaw export --write`,
- * and there is no MCP tool that performs it — `bclaw_setup` is the onboarding
- * wizard and takes no write flag. Pointing at it anyway would ship a next_action
- * whose args the engine rejects, which is the precise class of drift this plan
- * exists to eliminate; and per pln#634's own rule, a builder with no genuine
- * follow-up returns nothing rather than inventing one. The command therefore
- * travels in the message, where it is true.
+ * NO `next_actions`, deliberately. The recovery is a CLI command, and there is
+ * no MCP tool that performs it — `bclaw_setup` is the onboarding wizard and
+ * takes no write flag. Pointing at it anyway would ship a next_action whose
+ * args the engine rejects, which is the precise class of drift this plan exists
+ * to eliminate; and per pln#634's own rule, a builder with no genuine follow-up
+ * returns nothing rather than inventing one. The command therefore travels in
+ * the message, where it is true.
+ *
+ * WHICH command depends on what is stale (trp_6a49f976): this advisory shipped
+ * in 1.20.0 recommending `brainclaw export --write`, which the CLI rejects
+ * (a mode flag is required) and which — even corrected to `--all` — never
+ * touches live companions, the very files the first real-world firing listed.
+ * The recovery must be per kind, and only for the kinds actually stale.
  */
 export function staleSurfaceWarning(result, currentVersion) {
     if (result.stale.length === 0)
         return undefined;
     const shown = result.stale.slice(0, 8);
     const overflow = result.stale.length - shown.length;
+    const kinds = new Set(result.stale.map((s) => s.kind));
+    const commands = [
+        ...(kinds.has('stable') ? [STABLE_SURFACE_REFRESH_COMMAND] : []),
+        ...(kinds.has('live') ? [LIVE_SURFACE_REFRESH_COMMAND] : []),
+    ];
+    const recovery = kinds.size === 2
+        ? ` Run \`${STABLE_SURFACE_REFRESH_COMMAND}\` (stable surfaces) and \`${LIVE_SURFACE_REFRESH_COMMAND}\` (live companions) to refresh them.`
+        : ` Run \`${commands[0]}\` to refresh them.`;
     return {
         code: 'generated_surfaces_stale',
         message: `${result.stale.length} generated guidance surface(s) were written by an older brainclaw than v${currentVersion}: `
             + shown.map((s) => `${s.relativePath} (v${s.stampedVersion})`).join(', ')
             + (overflow > 0 ? ` (+${overflow} more)` : '')
             + '. An agent tier that never triggers a regeneration is reading them as-is.'
-            + ' Run `brainclaw export --write` to refresh them.',
+            + recovery,
         data: {
             current_version: currentVersion,
-            stale_surfaces: shown.map((s) => ({ path: s.relativePath, stamped_version: s.stampedVersion })),
+            stale_surfaces: shown.map((s) => ({ path: s.relativePath, stamped_version: s.stampedVersion, kind: s.kind })),
             ...(overflow > 0 ? { stale_surfaces_omitted: overflow } : {}),
-            refresh_command: 'brainclaw export --write',
+            // Kept as a single runnable string for consumers that shipped against
+            // 1.20.0; refresh_commands is the structured form.
+            refresh_command: commands.join(' && '),
+            refresh_commands: commands,
         },
     };
 }

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.20.0 on 2026-08-02T17:17:41.989Z
+// Source: brainclaw v1.20.1 on 2026-08-02T21:44:51.056Z
 export const FACTS = {
-  "version": "1.20.0",
-  "generated_at": "2026-08-02T17:17:41.989Z",
+  "version": "1.20.1",
+  "generated_at": "2026-08-02T21:44:51.056Z",
   "tools": {
     "count": 67,
     "published_count": 65,
@@ -474,7 +474,7 @@ export const FACTS = {
   },
   "bench": {
     "schema": "brainclaw.bench.v1",
-    "generated_at": "2026-08-02T17:17:40.300Z",
+    "generated_at": "2026-08-02T21:44:48.979Z",
     "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": 65,
+        "duration_ms_median": 76,
         "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": 121,
+        "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": 10,
+        "duration_ms_median": 12,
         "payload_chars_median": 499,
         "payload_tokens_est_median": 125
       }

package/dist/facts.json

@@ -1,6 +1,6 @@
 {
-  "version": "1.20.0",
-  "generated_at": "2026-08-02T17:17:41.989Z",
+  "version": "1.20.1",
+  "generated_at": "2026-08-02T21:44:51.056Z",
   "tools": {
     "count": 67,
     "published_count": 65,
@@ -472,7 +472,7 @@
   },
   "bench": {
     "schema": "brainclaw.bench.v1",
-    "generated_at": "2026-08-02T17:17:40.300Z",
+    "generated_at": "2026-08-02T21:44:48.979Z",
     "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": 65,
+        "duration_ms_median": 76,
         "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": 121,
+        "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": 10,
+        "duration_ms_median": 12,
         "payload_chars_median": 499,
         "payload_tokens_est_median": 125
       }

package/docs/mcp-schema-changelog.md

@@ -8,6 +8,21 @@ guarantees this changelog follows.
 
 ---
 
+## [1.20.1] — 2026-08-02
+
+**Changed — `generated_surfaces_stale` recovery data is now true, and structured (#163)**
+- The VALUE of `data.refresh_command` changes: it was `brainclaw export --write`,
+  which the CLI rejects (a mode flag is required), and is now a runnable command
+  derived from what is actually stale — `brainclaw export --all --write` (stable
+  surfaces), `brainclaw refresh` (live companions), or both joined with ` && `
+  when both kinds are stale. The field keeps its type (string); consumers that
+  displayed it verbatim now display something that works.
+- Additive fields on the same warning's `data`: `refresh_commands: string[]`
+  (the structured form of the above) and `kind: "stable" | "live"` on each
+  `stale_surfaces[]` entry.
+- Read contract only: no tool added/removed/renamed, no inputSchema change,
+  no surface-fingerprint movement.
+
 ## [1.20.0] — 2026-08-02
 
 **Fixed — 1.19.0 contract entries now actually emitted (#158)**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brainclaw",
-  "version": "1.20.0",
+  "version": "1.20.1",
   "description": "Shared project memory for humans and coding agents.",
   "type": "module",
   "repository": {