brainclaw 1.25.0 → 1.26.1

package/dist/core/io.js

@@ -1,4 +1,6 @@
+import crypto from 'node:crypto';
 import fs from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 import { withLock, cleanStaleLocks } from './lock.js';
 export { mutate } from './mutation-pipeline.js';
@@ -121,9 +123,199 @@ export function entityRecordDirs(subdir, cwd = process.cwd(), preferredDirName)
 export function entityRecordPaths(subdir, id, cwd, preferredDirName) {
     return entityRecordDirs(subdir, cwd ?? process.cwd(), preferredDirName).map((d) => path.join(d, `${id}.json`));
 }
+/**
+ * The id grammar every session record filename is built from (pln#672).
+ *
+ * A session id arrives from the ENVIRONMENT (BRAINCLAW_SESSION_ID and the
+ * per-agent variants read by resolveExplicitSessionId) and is interpolated
+ * straight into a filename: `<id>.json` / `<id>.snapshot.json`. Unvalidated,
+ * `../../../ESCAPED` walks out of the store — reproduced on disk on
+ * 2026-08-18: saveCurrentSession wrote outside the store root, and the same
+ * path feeds loadSessionById (read) and clearCurrentSession (unlink).
+ *
+ * Allowed: a leading alphanumeric, then alphanumerics, `.`, `_`, `-`, up to
+ * 128 chars — covers brainclaw's own `sess_<hex>` and the UUID-shaped ids
+ * some agents export. Refused by construction: path separators, `..`, drive
+ * letters and absolute paths, empty ids, and any id starting with a dot.
+ * The `.snapshot` suffix stays separately refused for current_session ids
+ * (pln#670) — that is a type-collision rule, not a path-safety one.
+ */
+const SAFE_SESSION_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+/**
+ * Win32 device namespace (pln#672 review P2, reproduced on a Windows host):
+ * `CON`, `NUL`, `COM1`… are not directory entries — `CON.json` opens the
+ * console device, `stat` reports a file, and the sessions directory stays
+ * empty. A record "written" there is silently lost. The reservation applies
+ * to the basename BEFORE the first dot, case-insensitively, so `con.json`
+ * and `Con.anything` are covered too. Refused on every platform: the grammar
+ * is shared, and an id must mean the same thing on all of them.
+ */
+const WIN32_RESERVED_BASENAME_RE = /^(con|prn|aux|nul|com[1-9]|lpt[1-9])$/i;
+export function isSafeSessionId(sessionId) {
+    if (!SAFE_SESSION_ID_RE.test(sessionId))
+        return false;
+    return !WIN32_RESERVED_BASENAME_RE.test(sessionId.split('.')[0]);
+}
+/** Throwing variant for the filename builders — a traversal must be loud, never silent. */
+export function assertSafeSessionId(sessionId) {
+    if (!isSafeSessionId(sessionId)) {
+        throw new Error(`session id '${sessionId}' is not a valid record identifier: only [A-Za-z0-9._-] (starting with an alphanumeric, max 128 chars) may become a session filename`);
+    }
+}
+/**
+ * Normalize an agent name into ONE filesystem path segment (pln#673).
+ *
+ * The agent name arrives from the environment (BRAINCLAW_AGENT_NAME, read by
+ * resolveCurrentAgentName) and became a DIRECTORY name unvalidated: proved on
+ * disk on 2026-08-18 that `'../../../../outside/PWNED'` made saveRuntimeNote
+ * create the directory and write the note ENTIRELY OUTSIDE the store.
+ *
+ * This is deliberately the SAME normalization the inbox has always used
+ * (`agentInboxDir`, messaging.ts) rather than a new convention: lower-case,
+ * then every character outside [a-z0-9_-] becomes `_`. Separators and dots
+ * cannot survive it, so no traversal can. When that replacement (or a length
+ * cap) would collapse distinct raw names, a stable hash suffix keeps their
+ * runtime directories separate. It remains IDENTITY for every normal agent
+ * name brainclaw produces (claude-code, codex, github-copilot, …) — verified
+ * against the real store — so existing normal directories do not move.
+ * Readers still probe a contained raw legacy name as a fallback (see
+ * runtime.ts) so a non-canonical legacy directory never becomes invisible.
+ *
+ * Alias resolution is deliberately NOT applied here: mapping `copilot` to
+ * `github-copilot` would relocate notes, which is a product decision, not a
+ * path-safety one.
+ */
+const AGENT_SEGMENT_UNSAFE_RE = /[^a-z0-9_-]/g;
+const WIN32_RESERVED_BASENAME_FOR_SEGMENT_RE = /^(con|prn|aux|nul|com[1-9]|lpt[1-9])$/i;
+// 128 leaves ample room for the record id and works below the 255-byte
+// component limit even when an agent name contains non-BMP characters (which
+// normalize to ASCII underscores). The hash makes truncation collision-safe.
+const MAX_AGENT_PATH_SEGMENT_LENGTH = 128;
+export function sanitizeAgentPathSegment(agent) {
+    const source = agent.trim().toLowerCase();
+    let normalized = source.replace(AGENT_SEGMENT_UNSAFE_RE, '_');
+    if (normalized.length === 0)
+        return 'unknown-agent';
+    // A Win32 device name is not a usable directory either (mkdir CON fails).
+    if (WIN32_RESERVED_BASENAME_FOR_SEGMENT_RE.test(normalized))
+        normalized = `${normalized}_`;
+    // A replacement would otherwise merge distinct identities (`a.b` and `a_b`)
+    // into one runtime directory. Preserve safe canonical names exactly, but add
+    // a deterministic discriminator to every lossy or length-capped segment.
+    if (source === normalized && normalized.length <= MAX_AGENT_PATH_SEGMENT_LENGTH)
+        return normalized;
+    const suffix = crypto.createHash('sha256').update(source).digest('hex').slice(0, 16);
+    return `${normalized.slice(0, MAX_AGENT_PATH_SEGMENT_LENGTH - suffix.length - 1)}_${suffix}`;
+}
+export const SESSION_SNAPSHOT_FILENAME_SUFFIX = '.snapshot.json';
+/**
+ * Filesystem type discriminator for session snapshots (codex review, pln#670).
+ * Case-fold before the suffix comparison because default Windows filesystems
+ * are case-insensitive: `X.SNAPSHOT.json` IS the path a lower-case probe
+ * resolves, and every suffix decision must agree on its type.
+ */
+export function isSessionSnapshotRecordFilename(filename) {
+    return filename.toLowerCase().endsWith(SESSION_SNAPSHOT_FILENAME_SUFFIX);
+}
+/**
+ * EVERY path a session_snapshot record for `sessionId` can occupy, canonical first.
+ *
+ * session_snapshot and current_session are two different record types that share
+ * the `sessions` directory family AND the same session_id — only the filename keeps
+ * them apart (pln#670). Snapshots are written as `<id>.snapshot.json` so a
+ * current_session `<id>.json` for the same session can never clobber them, whatever
+ * directory each resolver picks. The plain `<id>.json` probes cover records written
+ * before the split; readers must schema-validate every candidate.
+ */
+export function sessionSnapshotRecordPaths(sessionId, cwd, preferredDirName) {
+    // pln#672 — the id becomes a filename here too: refuse a traversal loudly
+    // rather than build a path that escapes the store.
+    assertSafeSessionId(sessionId);
+    const dirs = entityRecordDirs('sessions', cwd ?? process.cwd(), preferredDirName);
+    return [
+        ...dirs.map((d) => path.join(d, `${sessionId}.snapshot.json`)),
+        ...dirs.map((d) => path.join(d, `${sessionId}.json`)),
+    ];
+}
 export function memoryDir(cwd = process.cwd(), preferredDirName) {
     return path.join(cwd, preferredDirName ?? MEMORY_DIR);
 }
+/**
+ * Walk UP from a directory and return the outermost .brainclaw/ root found.
+ * Bypasses resolveEffectiveCwd / active project entirely — the answer depends
+ * only on the filesystem, which is what makes it safe for identity-level state
+ * that must NOT follow the active project (pln#648: a session record anchored
+ * on the effective cwd moved with every switch, out of the resolver's reach).
+ *
+ * Lives HERE, in a leaf module: identity.ts needs it, and store-resolution.ts
+ * imports identity.ts — the import cycle that blocked pln#648's first attempt.
+ * store-resolution re-exports it for its existing callers.
+ *
+ * Stops at the filesystem root, at $HOME (a user-level store is never a
+ * workspace root), and never climbs ABOVE BRAINCLAW_STORE_BOUNDARY when set —
+ * the containment contract tests and agent shells rely on (a leaked parent
+ * store must not widen the walk into the host machine).
+ */
+export function findOutermostBrainclawRoot(startDir) {
+    let dir = path.resolve(startDir);
+    const root = path.parse(dir).root;
+    const home = os.homedir();
+    const boundaryRaw = process.env.BRAINCLAW_STORE_BOUNDARY?.trim();
+    const boundary = boundaryRaw ? path.resolve(boundaryRaw) : undefined;
+    let outermost;
+    while (dir !== root && dir !== home) {
+        if (fs.existsSync(path.join(dir, MEMORY_DIR, 'config.yaml'))) {
+            outermost = dir;
+        }
+        if (boundary && dir === boundary)
+            break;
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return outermost;
+}
+/**
+ * The workspace anchor for identity-level state (pln#648 review P1): walking
+ * UP, the NEAREST store declaring `store_type: workspace` wins; only when no
+ * workspace is declared does the outermost store answer. Without the role
+ * check, two sibling declared workspaces under a common parent store would
+ * anchor to that parent and see each other's sessions — breaking exactly the
+ * isolation `resolveWorkspaceRoot` (chain-based, role-aware) guarantees.
+ * The role is read from the raw YAML — the same convention the store-chain
+ * walk uses (`store_type` is not part of the typed Config surface) — so this
+ * stays a leaf-module fs answer with no config.ts dependency.
+ * Same stops as the outermost walk: filesystem root, $HOME, and never above
+ * BRAINCLAW_STORE_BOUNDARY.
+ */
+export function findSessionAnchorRoot(startDir) {
+    let dir = path.resolve(startDir);
+    const root = path.parse(dir).root;
+    const home = os.homedir();
+    const boundaryRaw = process.env.BRAINCLAW_STORE_BOUNDARY?.trim();
+    const boundary = boundaryRaw ? path.resolve(boundaryRaw) : undefined;
+    let outermost;
+    while (dir !== root && dir !== home) {
+        const configPath = path.join(dir, MEMORY_DIR, 'config.yaml');
+        if (fs.existsSync(configPath)) {
+            outermost = dir;
+            try {
+                if (/^store_type:\s*workspace\b/m.test(fs.readFileSync(configPath, 'utf-8'))) {
+                    return dir;
+                }
+            }
+            catch { /* unreadable config — treat as a plain store */ }
+        }
+        if (boundary && dir === boundary)
+            break;
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return outermost;
+}
 export function memoryPath(filename, cwd, preferredDirName) {
     return path.join(memoryDir(cwd, preferredDirName), filename);
 }

package/dist/core/project-discovery.js

@@ -222,7 +222,13 @@ function discoverFiles(cwd, files, dirs) {
     }
     return results;
 }
-function isManagedByBrainclaw(filePath) {
+/**
+ * True when an instruction file was generated by `brainclaw export` (or carries
+ * a managed section marker). Exported for the bootstrap scan (pln#671): a
+ * managed export derives FROM brainclaw memory, so proposing it as a bootstrap
+ * import would feed brainclaw its own output back as new knowledge.
+ */
+export function isManagedByBrainclaw(filePath) {
     try {
         const content = fs.readFileSync(filePath, 'utf-8').slice(0, 200);
         return content.includes('brainclaw') && (content.includes('Managed by brainclaw') ||

package/dist/core/runtime.js

@@ -2,7 +2,7 @@ import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
 import { resolveCurrentHostId, sanitizeHostId } from './host.js';
-import { resolveEntityDir } from './io.js';
+import { resolveEntityDir, sanitizeAgentPathSegment } from './io.js';
 import { mutate } from './mutation-pipeline.js';
 import { loadVersionedJsonFile, saveVersionedJsonFile } from './migration.js';
 import { RuntimeNoteSchema } from './schema.js';
@@ -19,14 +19,60 @@ function privateRuntimeDir(cwd, mode = 'read') {
     return resolveEntityDir('runtime-private', cwd ?? process.cwd(), mode);
 }
 function sharedAgentDir(agent, cwd, mode = 'read') {
-    return path.join(sharedRuntimeDir(cwd, mode), agent);
+    // pln#673 — the agent name is env-controlled and becomes a path segment:
+    // normalize it so a traversal cannot be expressed at all.
+    return path.join(sharedRuntimeDir(cwd, mode), sanitizeAgentPathSegment(agent));
+}
+/**
+ * Return a pre-normalization directory only when it is provably one direct
+ * child of `baseDir`. Compatibility reads must not reintroduce the traversal
+ * the normalized write path closes: the agent name is still env-controlled.
+ *
+ * Dots inside a segment are retained for existing names such as
+ * `Legacy.Agent`; separators, Win32 aliases (including trailing dots/spaces),
+ * and platform-invalid components are not legacy data we can safely probe.
+ */
+const UNSAFE_LEGACY_AGENT_SEGMENT_RE = /[<>:"/\\|?*\u0000-\u001F]/;
+const WIN32_RESERVED_LEGACY_AGENT_BASENAME_RE = /^(con|prn|aux|nul|com[1-9]|lpt[1-9])$/i;
+function legacyAgentDir(baseDir, agent) {
+    if (agent.length === 0
+        || agent !== agent.trim()
+        || agent.endsWith('.')
+        || UNSAFE_LEGACY_AGENT_SEGMENT_RE.test(agent)
+        || WIN32_RESERVED_LEGACY_AGENT_BASENAME_RE.test(agent.split('.')[0]))
+        return undefined;
+    const base = path.resolve(baseDir);
+    const candidate = path.resolve(path.join(base, agent));
+    return path.dirname(candidate) === base ? candidate : undefined;
+}
+/**
+ * Both directories an agent's notes can occupy, canonical first (pln#673).
+ * Writes always use the normalized segment; reads also probe the RAW name so
+ * notes written before the normalization stay visible — the dual-read pattern
+ * pln#648/pln#670 already use for relocated records. Deduped when the name is
+ * already canonical, which is the case for every agent brainclaw produces.
+ */
+function agentDirCandidates(baseDir, agent) {
+    const canonical = path.join(baseDir, sanitizeAgentPathSegment(agent));
+    const raw = legacyAgentDir(baseDir, agent);
+    return raw && canonical !== raw ? [canonical, raw] : [canonical];
 }
 function hostRootDir(visibility, hostId, cwd, mode = 'read') {
     const baseDir = visibility === 'machine' ? machineRuntimeDir(cwd, mode) : privateRuntimeDir(cwd, mode);
     return path.join(baseDir, sanitizeHostId(hostId));
 }
 function hostAgentDir(visibility, hostId, agent, cwd, mode = 'read') {
-    return path.join(hostRootDir(visibility, hostId, cwd, mode), agent);
+    // pln#673 — same normalization as the shared tree; the host segment was
+    // already sanitized (sanitizeHostId), the agent segment was not.
+    return path.join(hostRootDir(visibility, hostId, cwd, mode), sanitizeAgentPathSegment(agent));
+}
+/** A contained raw path that can be retired after an update reaches its canonical location. */
+function legacyRuntimeNotePath(note, visibility, hostId, cwd) {
+    const base = visibility === 'shared'
+        ? sharedRuntimeDir(cwd, 'write')
+        : hostRootDir(visibility, hostId, cwd, 'write');
+    const legacyDir = legacyAgentDir(base, note.agent);
+    return legacyDir ? path.join(legacyDir, `${note.id}.json`) : undefined;
 }
 export function ensureRuntimeDir(agent, cwd, visibility = 'shared', hostId) {
     const dir = visibility === 'shared'
@@ -57,6 +103,13 @@ export function saveRuntimeNote(note, cwd) {
             registryFaultPoint('after_registry_journal');
         }
         saveVersionedJsonFile('runtime_note', filepath, parsed);
+        // An update to a pre-normalization record must not leave two physical
+        // copies with the same id. Retire only the verified-contained raw path,
+        // and only after the canonical write succeeds.
+        const legacyPath = legacyRuntimeNotePath(note, visibility, hostId, cwd);
+        if (legacyPath && legacyPath !== filepath && fs.existsSync(legacyPath)) {
+            fs.unlinkSync(legacyPath);
+        }
         appendEvent({ action: 'create', item_type: 'runtime_note', item_id: note.id, agent: note.agent, agent_id: note.agent_id }, cwd);
         commitMemoryChange(`runtime note: ${note.note_type ?? 'note'} (${note.agent})`, cwd);
     });
@@ -64,9 +117,39 @@ export function saveRuntimeNote(note, cwd) {
 export function runtimeNotePath(note, cwd) {
     const visibility = note.visibility ?? 'shared';
     const hostId = sanitizeHostId(note.host_id ?? resolveCurrentHostId());
-    return visibility === 'shared'
-        ? path.join(sharedAgentDir(note.agent, cwd), `${note.id}.json`)
-        : path.join(hostAgentDir(visibility, hostId, note.agent, cwd), `${note.id}.json`);
+    // pln#673 — the canonical (normalized) location, plus the RAW-name fallback
+    // for notes written before the normalization: this function answers "where is
+    // THIS note", and a record must not become invisible (nor undeletable)
+    // because its directory predates the fix. Canonical first; the raw candidate
+    // only wins when it actually holds the file.
+    const base = visibility === 'shared'
+        ? sharedRuntimeDir(cwd)
+        : hostRootDir(visibility, hostId, cwd);
+    const candidates = agentDirCandidates(base, note.agent).map((dir) => path.join(dir, `${note.id}.json`));
+    return candidates.find((candidate) => fs.existsSync(candidate)) ?? candidates[0];
+}
+/**
+ * Park one runtime note's raw record under `.brainclaw/gc-backups/` — the same
+ * park-don't-delete net the retention sweeps use (trp_dc9ca61e). Daily-bucketed
+ * JSONL so removals do not explode into one file per note. Returns the backup
+ * path, or undefined when the source record cannot be read.
+ */
+export function parkRuntimeNoteBackup(note, cwd) {
+    try {
+        const sourcePath = runtimeNotePath(note, cwd);
+        const content = fs.readFileSync(sourcePath, 'utf-8');
+        const parsed = JSON.parse(content);
+        parsed._removed_at = new Date().toISOString();
+        parsed._removal_type = 'bclaw_remove';
+        const day = new Date().toISOString().slice(0, 10);
+        const backupPath = path.join(cwd ?? process.cwd(), '.brainclaw', 'gc-backups', `removed-runtime-notes-${day}.jsonl`);
+        fs.mkdirSync(path.dirname(backupPath), { recursive: true });
+        fs.appendFileSync(backupPath, JSON.stringify(parsed) + '\n', 'utf-8');
+        return backupPath;
+    }
+    catch {
+        return undefined;
+    }
 }
 export function deleteRuntimeNote(note, cwd) {
     return mutate({ cwd }, () => {
@@ -118,12 +201,17 @@ export function listSharedJournaledRuntimeNotes(cwd) {
 function readAgentNotes(dir, agent) {
     if (!fs.existsSync(dir))
         return [];
-    const agents = agent
-        ? [agent]
-        : fs.readdirSync(dir).filter((entry) => fs.statSync(path.join(dir, entry)).isDirectory());
+    // pln#673 — a filtered read probes BOTH the normalized directory and the raw
+    // name (a pre-normalization directory must stay readable); an unfiltered read
+    // enumerates whatever is on disk, which covers both by construction. The
+    // candidates are absolute, so the join below must not prepend `dir` again.
+    const agentDirectories = agent
+        ? agentDirCandidates(dir, agent)
+        : fs.readdirSync(dir)
+            .filter((entry) => fs.statSync(path.join(dir, entry)).isDirectory())
+            .map((entry) => path.join(dir, entry));
     const notes = [];
-    for (const a of agents) {
-        const agentDirectory = path.join(dir, a);
+    for (const agentDirectory of agentDirectories) {
         if (!fs.existsSync(agentDirectory))
             continue;
         const files = fs.readdirSync(agentDirectory).filter((file) => file.endsWith('.json'));

package/dist/core/store-resolution.js

@@ -4,7 +4,11 @@ import path from 'node:path';
 import { loadActiveProject } from './active-project.js';
 import { loadConfig } from './config.js';
 import { loadCurrentSession, loadSessionById, resolveExplicitSessionId } from './identity.js';
-import { MEMORY_DIR } from './io.js';
+import { findOutermostBrainclawRoot, MEMORY_DIR } from './io.js';
+// pln#648 — the walk moved to io.ts (leaf) so identity.ts can anchor session
+// records on it without importing this module (which imports identity.ts).
+// Re-exported here to keep the existing API surface.
+export { findOutermostBrainclawRoot } from './io.js';
 import { summarizeWorkspaceProjects } from './workspace-projects.js';
 /**
  * Walk up the filesystem from `cwd`, collecting every `.brainclaw/` directory
@@ -423,26 +427,6 @@ export function resolveProjectRef(ref, cwd = process.cwd(), storeChainOptions) {
     }
     return undefined;
 }
-/**
- * Walk UP from a directory and return the outermost .brainclaw/ root found.
- * This bypasses resolveEffectiveCwd / active project to find the true workspace root.
- */
-export function findOutermostBrainclawRoot(startDir) {
-    let dir = path.resolve(startDir);
-    const root = path.parse(dir).root;
-    const home = os.homedir();
-    let outermost;
-    while (dir !== root && dir !== home) {
-        if (fs.existsSync(path.join(dir, MEMORY_DIR, 'config.yaml'))) {
-            outermost = dir;
-        }
-        const parent = path.dirname(dir);
-        if (parent === dir)
-            break;
-        dir = parent;
-    }
-    return outermost;
-}
 /**
  * Resolve the most specific child store that should answer a context request.
  *

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.25.0 on 2026-08-10T23:31:26.947Z
+// Source: brainclaw v1.26.1 on 2026-08-18T15:32:22.089Z
 export const FACTS = {
-  "version": "1.25.0",
-  "generated_at": "2026-08-10T23:31:26.947Z",
+  "version": "1.26.1",
+  "generated_at": "2026-08-18T15:32:22.089Z",
   "tools": {
     "count": 70,
     "published_count": 68,
@@ -477,8 +477,8 @@ export const FACTS = {
   },
   "bench": {
     "schema": "brainclaw.bench.v1",
-    "generated_at": "2026-08-10T23:31:25.464Z",
-    "node_version": "v24.18.0",
+    "generated_at": "2026-08-18T15:32:19.941Z",
+    "node_version": "v24.19.0",
     "platform": "linux-x64",
     "repeats": 3,
     "scenarios": [
@@ -486,7 +486,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": 59,
+        "duration_ms_median": 86,
         "payload_chars_median": 1640,
         "payload_tokens_est_median": 410
       },
@@ -494,17 +494,17 @@ 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": 88,
-        "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": 10,
-        "payload_chars_median": 499,
-        "payload_tokens_est_median": 125
+        "duration_ms_median": 11,
+        "payload_chars_median": 1305,
+        "payload_tokens_est_median": 326
       }
     ]
   }

package/dist/facts.json

@@ -1,6 +1,6 @@
 {
-  "version": "1.25.0",
-  "generated_at": "2026-08-10T23:31:26.947Z",
+  "version": "1.26.1",
+  "generated_at": "2026-08-18T15:32:22.089Z",
   "tools": {
     "count": 70,
     "published_count": 68,
@@ -475,8 +475,8 @@
   },
   "bench": {
     "schema": "brainclaw.bench.v1",
-    "generated_at": "2026-08-10T23:31:25.464Z",
-    "node_version": "v24.18.0",
+    "generated_at": "2026-08-18T15:32:19.941Z",
+    "node_version": "v24.19.0",
     "platform": "linux-x64",
     "repeats": 3,
     "scenarios": [
@@ -484,7 +484,7 @@
         "name": "cold_onboard",
         "volume": "empty",
         "description": "fresh machine → init → first useful context. Baseline for time-to-first-value.",
-        "duration_ms_median": 59,
+        "duration_ms_median": 86,
         "payload_chars_median": 1640,
         "payload_tokens_est_median": 410
       },
@@ -492,17 +492,17 @@
         "name": "warm_work",
         "volume": "medium",
         "description": "bclaw_work consult over a real-shaped store (~200 plans / 500 handoffs / 450 claims).",
-        "duration_ms_median": 88,
-        "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": 10,
-        "payload_chars_median": 499,
-        "payload_tokens_est_median": 125
+        "duration_ms_median": 11,
+        "payload_chars_median": 1305,
+        "payload_tokens_est_median": 326
       }
     ]
   }

package/docs/code-map.md

@@ -136,35 +136,44 @@ call `bclaw_code_refresh` and retry.
 
 ## Freshness badge model
 
-Every Code Map response carries a freshness badge so a stale index is always
-visible rather than silently misleading. The status is one of:
+Every Code Map response has one top-level `freshness` field:
+`fresh`, `stale`, `partial`, or `missing`. It is the synthetic index signal that
+an agent uses to decide whether to refresh, and it has the same meaning on
+`bclaw_work`, `bclaw_code_status`, `bclaw_code_find`, and `bclaw_code_brief`.
+
+```json
+{
+  "freshness": "fresh",
+  "details": {
+    "index": {
+      "status": "fresh",
+      "stale_file_count": 0,
+      "partial_reason": null,
+      "git_head_changed": null
+    },
+    "spot_check": {
+      "status": "stale",
+      "checked_files": 1,
+      "stale_changed_files": ["src/example.ts"],
+      "deleted_files": [],
+      "unchecked_files": [],
+      "budget_exhausted": false,
+      "partial_reason": null
+    }
+  }
+}
+```
 
-| Status | Meaning | Fix |
-|---|---|---|
-| `fresh` | Index matches the working tree, the extractor config, and the parser binaries. | — |
-| `stale_changed_files` | One or more indexed files have changed on disk since they were parsed. | `refresh --changed` |
-| `stale_extractor` | The extractor configuration (ignore rules, size caps, supported extensions, query budget, or active language set) changed since these shards were produced. | `refresh --changed` (heals on the cheap path) |
-| `stale_grammar` | A Tree-sitter grammar (or the engine glue) binary changed since these shards were produced. | `refresh --changed` (heals on the cheap path) |
-| `partial` | The index could not be fully read/built this pass (e.g. the project lock was held by a live writer). | retry |
-| `missing_index` | No index exists yet for this project. | `refresh --all` |
-
-Staleness reasons are kept separate on purpose: a content change
-(`stale_changed_files`) is independent from a config change (`stale_extractor`)
-which is independent from a parser-binary change (`stale_grammar`). The badge
-surfaces the dominant reason; `--json` output and the manifest carry the per-file
-counts.
-
-**Index freshness vs this call's spot-check.** `bclaw_code_status` reports the
-*index* freshness (the manifest state). `bclaw_code_find` / `bclaw_code_brief`
-additionally run a bounded, per-query *spot-check* of the files they actually
-touch — so a single call can read `stale_changed_files` (a file it looked at
-changed on disk) or `partial` (the spot-check hit its budget) even while the index
-itself is `fresh`. When the call-level status diverges from the index, the badge
-carries an `index_status` detail so the two are not confused, e.g.
-`{ status: "partial", details: { index_status: "fresh", partial_reason:
-"lazy_check_budget_exhausted" } }` reads as *"index fresh, this call's spot-check
-incomplete (budget)"* — not a contradiction with a `fresh` `status()`.
+`details.index` is the index diagnosis: its detailed `status` may be
+`stale_changed_files`, `stale_extractor`, `stale_grammar`, or
+`stale_git_head`. `details.spot_check` is a bounded, read-only observation of
+the candidates touched by `find` or `brief`; it is `not_run` on `status` and on
+a work section with no query. A stale or partial spot-check never silently
+changes the shared top-level signal. It gives the agent precise evidence for an
+explicit `bclaw_code_refresh(scope="changed")`, then a retry.
 
+No read command parses files or refreshes the index. `bclaw_work` can suggest
+that explicit refresh, but never performs it lazily.
 ## Lifecycle — pull-based, no daemon
 
 Code Map never runs in the background and never auto-reindexes. The model is lazy

package/package.json

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