brainclaw 1.10.0 → 1.10.1

package/README.md

@@ -369,34 +369,34 @@ The same surface is available through the canonical grammar for agents: `bclaw_c
 
 ## Documentation
 
-The npm package includes the Markdown docs below under `docs/`. Public web docs on `brainclaw.dev` are still being rolled out, so the npm README does not depend on private GitHub links.
+The Markdown docs below ship in the npm package under `docs/` and are versioned in the repo. The links resolve on GitHub and are rewritten to the package repo on the npm page.
 
 If you are integrating Brainclaw into an agent workflow, start with the agent-facing docs first:
 
-|                                            |                                                                                               |
-| ------------------------------------------ | --------------------------------------------------------------------------------------------- |
-| `docs/index.md`                          | Documentation index grouped by getting started, guides, reference, and design                 |
-| `docs/integrations/overview.md`          | Start here for agent integrations                                                             |
-| `docs/integrations/mcp.md`               | MCP runtime path for capable agents                                                           |
-| `docs/quickstart.md`                     | First-time setup on a new project (greenfield)                                                |
-| `docs/quickstart-existing-project.md`    | Joining a project that already has `.brainclaw/`                                            |
-| `docs/server-operations.md`              | Operator and remote-server workflow guide                                                     |
-| `docs/cli.md`                            | CLI reference for operators, scripts, and fallback use                                        |
-| `docs/code-map.md`                       | Code Map — symbol/import index, freshness model, monorepo behavior                            |
-| `docs/concepts/memory.md`                | What "memory" means in brainclaw                                                              |
-| `docs/concepts/plans-and-claims.md`      | Coordination layer                                                                            |
-| `docs/concepts/runtime-notes.md`         | Ephemeral observations                                                                        |
-| `docs/concepts/multi-agent-workflows.md` | The four common scenarios — orchestration, agent switching, project recovery, team async     |
-| `docs/concepts/troubleshooting.md`       | Runbook for degraded coordination state — stale claims, missing dist, octopus failures, etc. |
-| `docs/integrations/cursor.md`            | Cursor                                                                                        |
-| `docs/integrations/claude-code.md`       | Claude Code                                                                                   |
-| `docs/integrations/copilot.md`           | GitHub Copilot                                                                                |
-| `docs/integrations/codex.md`             | Codex                                                                                         |
-| `docs/storage.md`                        | Storage model                                                                                 |
-| `docs/security.md`                       | Security model                                                                                |
-| `docs/review.md`                         | Reflective review                                                                             |
-| `docs/reputation.md`                     | Reputation signals                                                                            |
-| `docs/playbooks/`                        | Audience design constraints for brainclaw development                                         |
+| Doc | What it covers |
+| --- | --- |
+| [docs/index.md](docs/index.md) | Documentation index grouped by getting started, guides, reference, and design |
+| [docs/integrations/overview.md](docs/integrations/overview.md) | Start here for agent integrations |
+| [docs/integrations/mcp.md](docs/integrations/mcp.md) | MCP runtime path for capable agents |
+| [docs/quickstart.md](docs/quickstart.md) | First-time setup on a new project (greenfield) |
+| [docs/quickstart-existing-project.md](docs/quickstart-existing-project.md) | Joining a project that already has `.brainclaw/` |
+| [docs/server-operations.md](docs/server-operations.md) | Operator and remote-server workflow guide |
+| [docs/cli.md](docs/cli.md) | CLI reference for operators, scripts, and fallback use |
+| [docs/code-map.md](docs/code-map.md) | Code Map — symbol/import index, freshness model, monorepo behavior |
+| [docs/concepts/memory.md](docs/concepts/memory.md) | What "memory" means in brainclaw |
+| [docs/concepts/plans-and-claims.md](docs/concepts/plans-and-claims.md) | Coordination layer |
+| [docs/concepts/runtime-notes.md](docs/concepts/runtime-notes.md) | Ephemeral observations |
+| [docs/concepts/multi-agent-workflows.md](docs/concepts/multi-agent-workflows.md) | The four common scenarios — orchestration, agent switching, project recovery, team async |
+| [docs/concepts/troubleshooting.md](docs/concepts/troubleshooting.md) | Runbook for degraded coordination state — stale claims, missing dist, octopus failures, etc. |
+| [docs/integrations/cursor.md](docs/integrations/cursor.md) | Cursor |
+| [docs/integrations/claude-code.md](docs/integrations/claude-code.md) | Claude Code |
+| [docs/integrations/copilot.md](docs/integrations/copilot.md) | GitHub Copilot |
+| [docs/integrations/codex.md](docs/integrations/codex.md) | Codex |
+| [docs/storage.md](docs/storage.md) | Storage model |
+| [docs/security.md](docs/security.md) | Security model |
+| [docs/review.md](docs/review.md) | Reflective review |
+| [docs/reputation.md](docs/reputation.md) | Reputation signals |
+| [docs/playbooks/](docs/playbooks/) | Audience design constraints for brainclaw development |
 
 ---
 
@@ -417,6 +417,13 @@ npm run test:coverage      # with coverage report
 
 For older releases (v0.x and the early v1.0 launch series), `git log` on `master` is the source of truth — every release commit follows the `chore(release): bump version to <semver>` convention, and the matching feature/fix commits reference their plan id (e.g. `feat(mcp): self-heal ... (pln#478)`).
 
+### v1.10.1
+
+Code Map fast-follows from the 1.10.0 dogfood, plus a lint cleanup:
+
+- A git branch switch now flags the index stale (new `stale_git_head` freshness reason); `refresh` honors `.gitignore` (gitignored output dirs no longer indexed); `brief("<path>")` resolves the exact file instead of token-flooding; and the freshness badge distinguishes index freshness from a call's spot-check (`index_status`).
+- The `brainclaw-session` skill + agent instruction surface now point agents at `bclaw_code_find` / `bclaw_code_brief` before grep. Lint baseline cleared to zero (stylistic rules ratcheted to `error`); README doc links clickable; `docs/code-map.md` lists JS / TS / JSX / TSX · Python · PHP · Java.
+
 ### v1.10.0
 
 - **Code Map** — a new per-project [Tree-sitter](docs/code-map.md) symbol + import

package/dist/commands/dispatch-watch.js

@@ -94,7 +94,7 @@ export async function runDispatchWatch(targetId, options = {}) {
     const baseRef = options.base ?? 'master';
     const startedAt = Date.now();
     let poll = 0;
-    let lastState = 'running';
+    let lastState;
     let lastStatus;
     for (;;) {
         poll += 1;

package/dist/commands/doctor.js

@@ -747,7 +747,6 @@ export function runDoctor(options = {}) {
         const msg = e instanceof Error ? e.message : String(e);
         checks.push({ name: 'config', status: 'error', message: `config.yaml is invalid: ${msg}` });
         console.error(`✗ config.yaml is invalid: ${msg}`);
-        hasIssues = true;
         if (options.json) {
             console.log(JSON.stringify({ ok: false, checks, metrics: {} }, null, 2));
         }
@@ -807,7 +806,6 @@ export function runDoctor(options = {}) {
         const msg = e instanceof Error ? e.message : String(e);
         checks.push({ name: 'state', status: 'error', message: `state is invalid: ${msg}` });
         console.error(`✗ state is invalid: ${msg}`);
-        hasIssues = true;
         if (options.json) {
             console.log(JSON.stringify({ ok: false, checks, metrics: {} }, null, 2));
         }
@@ -2202,7 +2200,7 @@ export function runDoctor(options = {}) {
             }
             // Find duplicates (same text at different levels)
             const duplicates = [];
-            allConstraints.forEach((items, key) => {
+            allConstraints.forEach((items, _key) => {
                 if (items.length > 1 && new Set(items.map((i) => i.store)).size > 1) {
                     duplicates.push({
                         type: 'constraint',
@@ -2211,7 +2209,7 @@ export function runDoctor(options = {}) {
                     });
                 }
             });
-            allDecisions.forEach((items, key) => {
+            allDecisions.forEach((items, _key) => {
                 if (items.length > 1 && new Set(items.map((i) => i.store)).size > 1) {
                     duplicates.push({
                         type: 'decision',
@@ -2220,7 +2218,7 @@ export function runDoctor(options = {}) {
                     });
                 }
             });
-            allTraps.forEach((items, key) => {
+            allTraps.forEach((items, _key) => {
                 if (items.length > 1 && new Set(items.map((i) => i.store)).size > 1) {
                     duplicates.push({
                         type: 'trap',

package/dist/commands/loops-handlers.js

@@ -84,7 +84,10 @@ function validateSemanticRequest(req) {
     return null;
 }
 function requestPayload(req) {
-    const { agent, agentId, client_request_id, ...rest } = req;
+    const rest = { ...req };
+    delete rest.agent;
+    delete rest.agentId;
+    delete rest.client_request_id;
     return rest;
 }
 function currentLoopVersion(loopId, cwd) {

package/dist/commands/mcp-read-handlers.js

@@ -1,3 +1,11 @@
+/**
+ * MCP read-only tool handlers.
+ *
+ * Extracted from mcp.ts to reduce file size. These handlers do not mutate
+ * state — they build context, list items, search, and inspect.
+ *
+ * @module
+ */
 import { applyBootstrapImport, renderBootstrapInterview, renderBootstrapSummary, runBootstrapProfile, uninstallBootstrapImport } from '../core/bootstrap.js';
 import { buildAgentToolingContext, renderAgentToolingSummary } from '../core/agent-context.js';
 import { buildCoordinationSnapshot, buildCrossProjectSnapshot } from '../core/coordination.js';

package/dist/commands/mcp.js

@@ -452,7 +452,7 @@ export const MCP_READ_TOOLS = [
     },
     {
         name: 'bclaw_code_status',
-        description: 'Code Map status for this project: store presence, freshness badge (fresh / stale_changed_files / stale_extractor / stale_grammar / partial / missing_index), and index stats (files, nodes, edges). Read-only; never refreshes. Pair with bclaw_code_refresh when freshness is missing_index or stale.',
+        description: 'Code Map status for this project: store presence, freshness badge (fresh / stale_changed_files / stale_extractor / stale_grammar / stale_git_head / partial / missing_index), and index stats (files, nodes, edges). Read-only; never refreshes. Pair with bclaw_code_refresh when freshness is missing_index or stale.',
         annotations: { tier: 'standard', category: 'discovery', headlessApproval: 'auto' },
         inputSchema: {
             type: 'object',
@@ -5360,7 +5360,6 @@ async function _executeMcpToolCallInner(payload) {
                         }));
                         continue;
                     }
-                    const profile = check.profile;
                     // Ensure target agent is registered before creating claims/messages
                     ensureAgentRegisteredForDispatch(agentName, dispatchCwd);
                     const assignScope = req.scope ?? req.task;

package/dist/commands/metrics.js

@@ -12,7 +12,6 @@ export function runMetrics(options = {}) {
     }
     const config = loadConfig();
     const slaHours = config.governance?.review_sla_hours ?? 24;
-    const now = new Date();
     const report = buildMetricsReport(slaHours, options.since);
     if (options.json) {
         console.log(JSON.stringify(report, null, 2));

package/dist/commands/release-claims.js

@@ -39,7 +39,7 @@ export function runReleaseClaims(options = {}) {
         process.exit(0);
     let released = 0;
     mutate({ cwd: options.cwd }, () => {
-        let state = loadState(options.cwd);
+        let state;
         for (const claim of toRelease) {
             try {
                 releaseClaim(claim.id, options.cwd);

package/dist/commands/sequence.js

@@ -11,7 +11,7 @@ function parseItems(raw) {
         parsed = JSON.parse(raw);
     }
     catch (error) {
-        throw new Error(`Invalid --items JSON: ${error instanceof Error ? error.message : String(error)}`);
+        throw new Error(`Invalid --items JSON: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
     }
     if (!Array.isArray(parsed)) {
         throw new Error('Invalid --items JSON: expected an array');

package/dist/commands/sync.js

@@ -61,7 +61,7 @@ export function runSync(options = {}) {
         return;
     }
     // Check git status of .brainclaw/
-    let gitStatus = '';
+    let gitStatus;
     try {
         // Security: execFileSync (no shell) + scopePaths spread as separate args so
         // path specs cannot inject (Socket 2026-06-08 class).

package/dist/commands/upgrade.js

@@ -463,13 +463,6 @@ function upsertSection(existingContent, section) {
     const trimmed = existingContent.trimEnd();
     return trimmed.length > 0 ? `${trimmed}\n\n${section}\n` : `${section}\n`;
 }
-function listJsonFiles(dir) {
-    if (!fs.existsSync(dir))
-        return [];
-    return fs.readdirSync(dir)
-        .filter(f => f.endsWith('.json'))
-        .map(f => path.join(dir, f));
-}
 function listJsonFilesRecursive(dir) {
     if (!fs.existsSync(dir))
         return [];

package/dist/core/agent-context.js

@@ -63,7 +63,7 @@ function readAgentsMarkdown(cwd) {
     // Only extract rules from actionable sections, not from descriptive sections
     // like "why this matters" which contain explanatory bullets, not instructions.
     const SKIP_SECTIONS = /why this matters|what it provides|what brainclaw/i;
-    let currentSection = '';
+    let currentSection;
     let skipSection = false;
     const rules = [];
     for (const line of lines) {

package/dist/core/agent-files.js

@@ -1158,7 +1158,7 @@ export function ensureClaudeCodeCommand(cwd) {
         relativePath: CLAUDE_CODE_COMMAND_RELATIVE_PATH,
     };
 }
-export function ensureClaudeCodeUserSettings(homeDir, env = process.env) {
+export function ensureClaudeCodeUserSettings(homeDir, _env = process.env) {
     if (!homeDir)
         return undefined;
     const filePath = path.join(homeDir, '.claude', 'settings.json');
@@ -1630,7 +1630,6 @@ export function ensureCodexMcpConfig(homeDir, env = process.env) {
         const autoApprovedSet = new Set(getHeadlessAutoApprovedToolNames());
         const toolSectionRe = /^\[mcp_servers\.brainclaw\.tools\.([^\]]+)\]/gm;
         const approvalModeRe = /^\s*approval_mode\s*=\s*"([^"]+)"/m;
-        let m;
         const warnings = [];
         // Split into sections to check each tool block
         const lines = existing.split('\n');

package/dist/core/agent-integrations.js

@@ -160,8 +160,8 @@ export function extractMcpCommandVal(agentName, expectedPath) {
         return { is_valid: false };
     }
     if (expectedPath.endsWith('.toml')) {
-        const cmdMatch = content.match(/\[mcp_servers\.brainclaw\](?:[^\[]*)command\s*=\s*(["'])(.+?)\1/is);
-        const argsMatch = content.match(/\[mcp_servers\.brainclaw\](?:[^\[]*)args\s*=\s*\[(.+?)\]/is);
+        const cmdMatch = content.match(/\[mcp_servers\.brainclaw\](?:[^[]*)command\s*=\s*(["'])(.+?)\1/is);
+        const argsMatch = content.match(/\[mcp_servers\.brainclaw\](?:[^[]*)args\s*=\s*\[(.+?)\]/is);
         let args;
         if (argsMatch) {
             args = argsMatch[1]
@@ -274,7 +274,7 @@ export function assessAgentIntegrationReadiness(config, cwd, env = process.env)
         const surfaces = declaration.surfaces.map((surface) => surfaceExists(surface, cwd, env, declaration.agent_name));
         const missingSurfaces = surfaces.filter((surface) => !surface.exists);
         const driftingSurfaces = surfaces.filter((surface) => surface.drift_message != null);
-        let effectiveTier = 'tier-b';
+        let effectiveTier;
         const selfHealingGuidance = [];
         const hasMissingMcpOrHook = missingSurfaces.some((s) => s.kind === 'mcp' || s.kind === 'hook');
         const hasDriftingMcp = driftingSurfaces.some((s) => s.kind === 'mcp');

package/dist/core/agent-registry.js

@@ -275,7 +275,7 @@ export function registerAgentIdentity(input) {
     saveAgentIdentity(created, input.cwd, input.preferredDirName);
     return created;
 }
-export function resolveCurrentAgentIdentity(cwd, preferredDirName, homeDir) {
+export function resolveCurrentAgentIdentity(cwd, preferredDirName, _homeDir) {
     // env var takes priority over config — allows AI agent to self-identify
     const envAgentId = (process.env.BRAINCLAW_AGENT_ID ?? '').trim();
     const envAgentName = (process.env.BRAINCLAW_AGENT_NAME ?? process.env.BRAINCLAW_AGENT ?? '').trim();
@@ -537,7 +537,7 @@ export function resolveCurrentModel(cwd) {
  * Note: config.current_agent is intentionally NOT used here — it's a singleton
  * global that causes cross-agent confusion in multi-agent setups.
  */
-export function resolveCurrentAgentName(cwd, _homeDir) {
+export function resolveCurrentAgentName(_cwd, _homeDir) {
     const fromEnv = (process.env.BRAINCLAW_AGENT_NAME ?? process.env.BRAINCLAW_AGENT)?.trim();
     if (fromEnv)
         return fromEnv;

package/dist/core/assignments.js

@@ -1,3 +1,15 @@
+/**
+ * Assignment lifecycle — Agent SDK runtime protocol.
+ *
+ * An Assignment is the canonical coordination entity that tracks the full
+ * lifecycle of dispatched work: from creation through offer, acceptance,
+ * execution, and completion (or failure/timeout/reroute).
+ *
+ * Assignments reference Claims (scope lock) and InboxMessages (brief delivery)
+ * but don't replace them. They own the status FSM and heartbeat tracking.
+ *
+ * @module
+ */
 import fs from 'node:fs';
 import { AssignmentSchema } from './schema.js';
 import { resolveEntityDir } from './io.js';

package/dist/core/brainclaw-version.js

@@ -555,7 +555,7 @@ function readWorkspaceBrainclawPackage(cwd) {
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
-        throw new Error(`Failed to read package.json: ${message}`);
+        throw new Error(`Failed to read package.json: ${message}`, { cause: error });
     }
     const name = typeof parsed.name === 'string' ? parsed.name.trim() : '';
     const version = typeof parsed.version === 'string' ? parsed.version.trim() : '';
@@ -617,7 +617,7 @@ function parseNpmDistTags(stdout) {
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
-        throw new Error(`npm view returned invalid JSON: ${message}`);
+        throw new Error(`npm view returned invalid JSON: ${message}`, { cause: error });
     }
     if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
         throw new Error('npm view did not return a dist-tag object.');

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

@@ -8,9 +8,11 @@
  * return not-yet-implemented placeholders that still carry a real
  * `freshness_badge`, locking the response shape for later sprints.
  */
+import { execFileSync } from 'node:child_process';
 import path from 'node:path';
 import { readManifest, storeExists } from './store.js';
 import { refresh as runRefresh } from './refresh.js';
+import { applyGitHeadDrift } from './freshness.js';
 import { brief as runBrief, find as runFind } from './query.js';
 import { defaultMemoryReader } from './memory-reader.js';
 /** spec §9 caps the brief reading list at 12 files. */
@@ -18,6 +20,31 @@ export const BRIEF_FILE_CAP = 12;
 function badge(status, details = {}) {
     return { status, details };
 }
+/**
+ * Read the working tree's current commit at `root` (read-path git-HEAD drift,
+ * trp_42688015). Returns null on any failure or a non-git project (also detached
+ * HEAD resolves to the commit sha, which is the correct comparison key) — a null
+ * makes the comparison a no-op, preserving existing behaviour.
+ *
+ * COST (review finding, LOW): one synchronous `git rev-parse HEAD` per status/
+ * find/brief call. These are interactive, human-/agent-paced reads (not a tight
+ * loop), so a single ~5–15ms spawn is acceptable and keeps branch-switch detection
+ * immediate. If this ever shows up on a profile, memoize per `root` behind a short
+ * TTL (a few seconds) — short enough that a checkout is still caught promptly.
+ */
+function readCurrentGitHead(root) {
+    try {
+        const out = execFileSync('git', ['rev-parse', 'HEAD'], {
+            cwd: root,
+            encoding: 'utf-8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        }).trim();
+        return out || null;
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * P0 JSONL-backed query backend. Reads the durable file store (manifest +
  * shards + indexes); no graph DB. find()/brief() are stubbed for Sprint 1.
@@ -28,8 +55,11 @@ export class JsonlBackend {
      * path; tests inject an in-memory reader to assert attachment without a store.
      */
     memoryReader;
+    /** Read-path git-HEAD reader (injectable for tests). trp_42688015. */
+    gitHeadReader;
     constructor(opts = {}) {
         this.memoryReader = opts.memoryReader ?? defaultMemoryReader;
+        this.gitHeadReader = opts.gitHeadReader ?? readCurrentGitHead;
     }
     async status(input) {
         const manifest = readManifest(input.cwd, input.preferredDirName);
@@ -40,12 +70,13 @@ export class JsonlBackend {
                 stats: null,
             };
         }
+        const base = badge(manifest.freshness.status, {
+            stale_file_count: manifest.freshness.stale_file_count,
+            partial_reason: manifest.freshness.partial_reason,
+        });
         return {
             store_exists: true,
-            freshness_badge: badge(manifest.freshness.status, {
-                stale_file_count: manifest.freshness.stale_file_count,
-                partial_reason: manifest.freshness.partial_reason,
-            }),
+            freshness_badge: this.withHeadDrift(base, manifest, input.cwd),
             stats: {
                 files_indexed: manifest.stats.files_indexed,
                 nodes: manifest.stats.nodes,
@@ -95,10 +126,15 @@ export class JsonlBackend {
     async find(input) {
         const ctx = this.queryContext(input);
         const out = runFind(input.query, input.limit, ctx);
+        const manifest = readManifest(input.cwd, input.preferredDirName);
+        const base = {
+            status: out.freshness_badge.status,
+            details: out.freshness_badge.details,
+        };
         return {
             query: out.query,
             matches: out.matches,
-            freshness_badge: { status: out.freshness_badge.status, details: out.freshness_badge.details },
+            freshness_badge: this.withHeadDrift(base, manifest, input.cwd),
         };
     }
     /**
@@ -109,13 +145,30 @@ export class JsonlBackend {
     async brief(input) {
         const ctx = this.queryContext(input);
         const out = runBrief(input.target, input.limit, ctx, this.memoryReader);
+        const manifest = readManifest(input.cwd, input.preferredDirName);
+        const base = {
+            status: out.freshness_badge.status,
+            details: out.freshness_badge.details,
+        };
         return {
             target: out.target,
             suggested_files_to_read: out.suggested_files_to_read,
             related_memory: out.related_memory,
-            freshness_badge: { status: out.freshness_badge.status, details: out.freshness_badge.details },
+            freshness_badge: this.withHeadDrift(base, manifest, input.cwd),
         };
     }
+    /**
+     * Annotate a read badge with git-HEAD drift vs the commit the index was built
+     * against (`manifest.git.head`). trp_42688015 — a branch switch (whole-tree move)
+     * is otherwise unflagged because `status` reads only write-side freshness and the
+     * per-file lazy check is query-scoped + budgeted. No-op for non-git projects.
+     */
+    withHeadDrift(base, manifest, cwd) {
+        if (!manifest)
+            return base;
+        const root = manifest.project_root || cwd || process.cwd();
+        return applyGitHeadDrift(base, manifest.git.head, this.gitHeadReader(root));
+    }
     queryContext(input) {
         return { cwd: input.cwd, preferredDirName: input.preferredDirName };
     }

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

@@ -105,4 +105,40 @@ export function summarizeFreshness(shards) {
         status = 'stale_grammar';
     return { status, stale_file_count: staleTotal, partial_reason: null };
 }
+/**
+ * Read-path git-HEAD drift (trp_42688015).
+ *
+ * The index records the commit it was built against (`manifest.git.head`). The
+ * per-file lazy read check (query.ts §6.1) only samples a query's candidate files
+ * within a bounded budget, and `status` reports ONLY the write-side manifest
+ * freshness (extractor/grammar hashes) — neither keys on git HEAD. So a whole-tree
+ * move such as `git checkout <other-branch>` left the index reported `fresh`, and
+ * find/brief could serve OLD-branch paths/symbols. This compares the index head to
+ * the working tree's current head and, when they differ, sets a clean `fresh` badge
+ * to the dedicated `stale_git_head` reason, recording the precise cause in
+ * `details.git_head_changed`.
+ *
+ * `stale_git_head` is kept DISTINCT from `stale_changed_files` (review finding):
+ * the latter means CONFIRMED per-file content/path drift (and carries a real
+ * `stale_file_count`); a HEAD move is a weaker signal — "the index was built at
+ * another commit, refresh recommended" — and must not masquerade as confirmed file
+ * changes with a contradictory `stale_file_count: 0`.
+ *
+ * No-op when either head is unknown (non-git project, older manifest) or the heads
+ * match — so existing fresh/non-git behaviour is unchanged. A badge that is already
+ * non-`fresh` (stale_*, partial, missing_index) keeps its more-specific/equally-
+ * actionable status; only the cause detail is added.
+ */
+export function applyGitHeadDrift(badge, indexHead, currentHead) {
+    if (!indexHead || !currentHead || indexHead === currentHead)
+        return badge;
+    const status = badge.status === 'fresh' ? 'stale_git_head' : badge.status;
+    return {
+        status,
+        details: {
+            ...badge.details,
+            git_head_changed: { index_head: indexHead, current_head: currentHead },
+        },
+    };
+}
 //# sourceMappingURL=freshness.js.map

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

@@ -66,7 +66,7 @@ function validateEntry(entry, checker, acc, projectRoot, maxParseFileBytes, cwd,
     if (cached !== undefined)
         return cached;
     const abs = path.join(projectRoot, entry.path);
-    let stat = null;
+    let stat;
     try {
         stat = fs.statSync(abs);
     }
@@ -158,6 +158,14 @@ function deriveBadge(base, acc, budgetExhausted, hadConfidentMatch, emptyIndex)
         details.partial_reason = 'lazy_check_budget_exhausted';
         details.budget = { ...LAZY_BUDGET };
     }
+    // pln#593 #2 — distinguish INDEX freshness (manifest state) from THIS call's
+    // read-path spot-check. When the call-level status diverges from the index
+    // status (a budget-limited `partial`, or a per-file `stale_changed_files` over a
+    // `fresh` index), surface the index status so an agent does not read
+    // status()=fresh vs find()/brief()=partial as a contradiction: it's "index
+    // <index_status>, this call's spot-check <status>".
+    if (status !== base)
+        details.index_status = base;
     void hadConfidentMatch;
     return { status, details };
 }
@@ -460,6 +468,17 @@ function reverseDeps(resolutionIndex, definingPaths, definingByNodeId) {
     }
     return [...byPath.values()];
 }
+/**
+ * Heuristic: does the brief target denote a file PATH rather than a bare symbol
+ * name? A path separator or a supported source extension marks a path target —
+ * for which we resolve the exact file directly instead of fuzzy-tokenizing the
+ * name. Fuzzy-tokenizing a path floods the brief with unrelated same-token symbols
+ * (e.g. brief('src/commands/switch.ts') pulling in every `switch`-named symbol and
+ * code-map test). pln#593 1b.
+ */
+function looksLikePathTarget(target) {
+    return /[\\/]/.test(target) || /\.(?:ts|tsx|js|jsx|mjs|cjs|py|php|java)$/i.test(target);
+}
 /** Find files whose path matches the target directly (path-target briefs). */
 function filesMatchingPath(symbolsIndex, target) {
     const norm = target.replace(/\\/g, '/');
@@ -494,12 +513,24 @@ export function brief(target, limit, ctx, memoryReader) {
     // result with unrelated same-token symbols (e.g. `resolveProjectImports` would pull
     // in every `resolve*`), burying the real defining file + its graph signals. Fall
     // back to the fuzzy token set, then to a path match. (find() stays fuzzy by design.)
-    let defining = gatherSymbolEntries(symbolsIndex, target);
-    const exact = defining.filter((e) => e.name.toLowerCase() === target.toLowerCase());
-    if (exact.length > 0)
-        defining = exact;
-    else if (defining.length === 0)
+    let defining;
+    if (looksLikePathTarget(target)) {
+        // PATH target (pln#593 1b): resolve the exact file; the graph signals (its
+        // imports / dependents / direct tests) then rank below it via rankFiles. Skip
+        // the fuzzy token gather entirely — it floods a path brief with same-token
+        // noise. Degrade to the fuzzy set only if the path resolves to nothing indexed.
         defining = filesMatchingPath(symbolsIndex, target);
+        if (defining.length === 0)
+            defining = gatherSymbolEntries(symbolsIndex, target);
+    }
+    else {
+        defining = gatherSymbolEntries(symbolsIndex, target);
+        const exact = defining.filter((e) => e.name.toLowerCase() === target.toLowerCase());
+        if (exact.length > 0)
+            defining = exact;
+        else if (defining.length === 0)
+            defining = filesMatchingPath(symbolsIndex, target);
+    }
     const root = resolveRoot(ctx);
     const maxBytes = maxParseBytes(ctx);
     const checker = makeLazyChecker();

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

@@ -44,6 +44,11 @@ export const FreshnessStatusSchema = z.enum([
     'stale_changed_files',
     'stale_extractor',
     'stale_grammar',
+    // Read-path only (trp_42688015): the index was built against a different git
+    // commit than the working tree's current HEAD (e.g. after `git checkout`). Kept
+    // DISTINCT from `stale_changed_files` (confirmed per-file content drift) so a
+    // HEAD move is not misreported as confirmed changes — see applyGitHeadDrift.
+    'stale_git_head',
     'partial',
     'missing_index',
 ]);

package/dist/core/code-map/wasm-loader.js

@@ -158,7 +158,7 @@ async function loadEngineGlue() {
         // '../../vendor/...' === dist/vendor/...
         let mod;
         const vendored = new URL('../../vendor/web-tree-sitter/tree-sitter.js', import.meta.url);
-        let vendoredExists = false;
+        let vendoredExists;
         try {
             vendoredExists = fs.existsSync(fileURLToPath(vendored));
         }

package/dist/core/context.js

@@ -1574,7 +1574,7 @@ function isExecutionSensitiveTarget(target) {
 function tokenise(input) {
     return input
         .toLowerCase()
-        .split(/[^a-z0-9_\/-]+/)
+        .split(/[^a-z0-9_/-]+/)
         .map((x) => x.trim())
         .filter(Boolean);
 }

package/dist/core/cross-project.js

@@ -65,7 +65,7 @@ export function detectCrossProjectCycles(cwd) {
     const baseCwd = path.resolve(cwd ?? process.cwd());
     const cycles = [];
     function walk(currentCwd, visited) {
-        let links = [];
+        let links;
         try {
             links = resolveCrossProjectLinks(currentCwd);
         }

package/dist/core/dispatcher.js

@@ -53,7 +53,6 @@ import { sweepAssignments } from './assignment-sweeper.js';
 import { InboxMessageSchema } from './schema.js';
 import { generateId, nowISO } from './ids.js';
 import { applyHandoffUpdates } from '../commands/update-handoff.js';
-const MAX_INLINE_BRIEF_LENGTH = 4000;
 /**
  * Build a cross-platform env prefix for BRAINCLAW_CLAIM_ID. Delegates to
  * the centralised buildClaimEnvPrefix in src/core/execution-profile.ts
@@ -555,7 +554,6 @@ export function scoreAgents(agentPool, plan, activeClaims, cycleAssignments) {
     for (const claim of activeClaims) {
         claimCounts.set(claim.agent, (claimCounts.get(claim.agent) ?? 0) + 1);
     }
-    const maxClaims = Math.max(1, ...claimCounts.values());
     return agentPool.map(agent => {
         // Factor 1: Preference — is this the plan's assignee?
         const preference = (plan.assignee === agent) ? 1.0 : 0.0;

package/dist/core/entity-operations.js

@@ -212,9 +212,6 @@ function loadAll(name, cwd) {
             throw new EntityOperationUnsupportedError(name, 'find');
     }
 }
-function applyFilter(items, filter) {
-    return applyFieldFilter(items, filter).filter((item) => passesProvenanceFilter(item, filter));
-}
 function applyFieldFilter(items, filter) {
     let result = items;
     if (filter.status) {

package/dist/core/ids.js

@@ -48,7 +48,7 @@ export function getNextShortLabel(prefix, cwd, preferredDirName) {
         }
         catch (error) {
             if (!(error instanceof Error) || !('code' in error) || error.code !== 'ENOENT') {
-                throw new Error(`Could not read short-label counter ${fp}: ${error instanceof Error ? error.message : String(error)}`);
+                throw new Error(`Could not read short-label counter ${fp}: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
             }
         }
         const next = (counter[prefix] ?? 0) + 1;

package/dist/core/instruction-templates.js

@@ -323,7 +323,7 @@ function renderAvailableTools() {
         '**Session/claims:** `bclaw_session_start`, `bclaw_session_end`, `bclaw_claim`, `bclaw_release_claim` · **steps:** `bclaw_add_step`, `bclaw_complete_step`, `bclaw_update_step`, `bclaw_delete_step` · **sequences:** `bclaw_list_sequences`, `bclaw_create_sequence`, `bclaw_update_sequence`, `bclaw_delete_sequence`',
         '**Inbox:** `bclaw_read_inbox`, `bclaw_ack_message`, `bclaw_send_message`, `bclaw_correct_handoff` · **capture:** `bclaw_write_note`, `bclaw_quick_capture(text, type?)` · **search:** `bclaw_search` · **setup:** `bclaw_setup`, `bclaw_bootstrap`, `bclaw_switch`, `bclaw_release_notes`',
         '**Escalation (orchestrators):** `bclaw_coordinate(intent=review|consult|assign|ideate)` · `bclaw_dispatch(intent=execute)` on an active sequence · `bclaw_loop(intent=turn|complete_turn|advance|close)` to drive turns · `bclaw_dispatch_status(target_id)` to verify',
-        '**Code discovery (Code Map):** `bclaw_code_find(query)` locate a symbol/class/component · `bclaw_code_brief(target)` ranked reading list + related memory before editing · `bclaw_code_status` / `bclaw_code_refresh` check freshness / rebuild the symbol+import index. Use it before grepping unfamiliar code — see `docs/code-map.md`.',
+        '**Code discovery (Code Map):** `bclaw_code_find(query)` locate a symbol/class/component · `bclaw_code_brief(target)` ranked reading list + related memory before editing · `bclaw_code_status` / `bclaw_code_refresh` check freshness / rebuild the symbol+import index. **Reach for these before `rg`/grep on unfamiliar code** — and if your harness defers MCP tools, `tool_search` for `bclaw_code_*` first rather than falling back to a blind grep. See `docs/code-map.md`.',
         '',
         'Responses are self-teaching — follow their `next_actions`. Full catalog + stability contract: `docs/integrations/mcp.md`, `docs/concepts/mcp-governance.md`.',
     ].join('\n');

package/dist/core/instructions.js

@@ -25,7 +25,6 @@ export function saveInstruction(entry, cwd) {
     });
 }
 export function createInstruction(text, options, cwd) {
-    const entries = loadInstructions(cwd);
     const timestamp = new Date().toISOString();
     const entry = {
         schema_version: 2,

package/dist/core/loops/lock.js

@@ -167,9 +167,6 @@ function loadIdempotencyRecord(kind, key, cwd) {
 function readLockBlob(lockPath) {
     return readJsonIfExists(lockPath) ?? null;
 }
-function writeLockAtomic(lockPath, blob) {
-    writeJsonAtomic(lockPath, blob);
-}
 function processIsAlive(pid) {
     try {
         // Signal 0 just checks for the process's existence without actually sending a signal.

package/dist/core/protocol-skills.js

@@ -34,16 +34,18 @@ reachable (cold start, or a worktree without \`.brainclaw/\`).
 
 1. \`bclaw_work(intent='consult')\` — loads project memory and reports active claims. Read \`bootstrap_recommended\`: if true the project has no usable PROJECT.md (see \`brainclaw-multi-agent\` → bootstrap loop).
 2. If you will edit a scope, claim it: \`bclaw_work(intent='execute', scope='<path-or-feature>')\`. The response's \`claim_id\` is yours; \`claim_status='created'\` = new, \`'existing'\` = resumed.
-3. Do the work. Honor the \`warnings\` array (claim conflicts, sensitive paths, high-severity traps on your scope).
-4. When done (committed, tested), \`bclaw_session_end(autoRelease: true)\` — closes the session record and releases your remaining claims. \`autoRelease\` defaults to false; pass it explicitly or claims survive the session.
+3. Before editing unfamiliar code, orient with the **Code Map** instead of grepping blind: \`bclaw_code_brief(target='<symbol|path>')\` for a ranked reading list — the defining file, its importers, and related decisions/traps — or \`bclaw_code_find(query='<name>')\` to locate a symbol/class/component. A \`missing_index\`/stale badge means run \`bclaw_code_refresh\` first.
+4. Do the work. Honor the \`warnings\` array (claim conflicts, sensitive paths, high-severity traps on your scope).
+5. When done (committed, tested), \`bclaw_session_end(autoRelease: true)\` — closes the session record and releases your remaining claims. \`autoRelease\` defaults to false; pass it explicitly or claims survive the session.
 
-CLI fallback: \`brainclaw context --json\` · \`brainclaw claim create "<desc>" --scope <path>\` · \`brainclaw session-end --auto-release\`.
+CLI fallback: \`brainclaw context --json\` · \`brainclaw code-map brief <symbol>\` / \`brainclaw code-map find <name>\` · \`brainclaw claim create "<desc>" --scope <path>\` · \`brainclaw session-end --auto-release\`.
 
 ## Anti-rationalizations
 
 - **"I'm just exploring, I'll skip session-end."** → A live claim outlives a crash. The next agent sees your stale claim and is blocked. Calling \`bclaw_session_end(autoRelease: true)\` is the zero-cost guarantee — without the flag the claim survives.
 - **"I know the project, I don't need to consult."** → State changes between sessions (commits, new traps, new constraints). Consult is cheap and surfaces what you'd miss.
 - **"I'll claim later once I know the exact scope."** → Claim-before-edit IS the contract; it is exactly what prevents races with parallel agents.
+- **"I'll just grep for it."** → On an unfamiliar or large repo, grep floods you with noise and misses the blast radius. \`bclaw_code_brief\` returns the defining file + its importers + related memory in one ranked call; fall back to grep only when the Code Map index is missing.
 
 ## Red flags
 

package/dist/core/security-detectors.js

@@ -26,7 +26,7 @@ export const BUILTIN_DETECTORS = [
     { id: 'aws_access_key', label: 'AWS access key ID', pattern: /\bAKIA[0-9A-Z]{16}\b/ },
     { id: 'aws_temp_access_key', label: 'AWS temporary access key ID', pattern: /\bASIA[0-9A-Z]{16}\b/ },
     // Google
-    { id: 'google_api_key', label: 'Google API key', pattern: /\bAIza[0-9A-Za-z_\-]{35}\b/ },
+    { id: 'google_api_key', label: 'Google API key', pattern: /\bAIza[0-9A-Za-z_-]{35}\b/ },
     // Slack
     { id: 'slack_token', label: 'Slack token', pattern: /\bxox[abprs]-[0-9A-Za-z-]{10,}\b/ },
     { id: 'slack_webhook', label: 'Slack webhook', pattern: /https:\/\/hooks\.slack\.com\/services\/T[A-Z0-9]{8,}\/B[A-Z0-9]{8,}\/[A-Za-z0-9]{24,}/ },
@@ -80,7 +80,7 @@ export function shannonEntropy(s) {
     return h;
 }
 const SECRET_KEYWORD_CONTEXT = /(?:api[_-]?key|secret|token|password|passwd|auth|bearer|access[_-]?key|private[_-]?key)/i;
-const HIGH_ENTROPY_CANDIDATE = /[A-Za-z0-9_+/=\-]{16,}/g;
+const HIGH_ENTROPY_CANDIDATE = /[A-Za-z0-9_+/=-]{16,}/g;
 /**
  * Entropy-based detection. Scans `text` for token-shaped substrings near
  * a sensitive keyword. Two-stage gating keeps false positives low:

package/dist/core/security-extract.js

@@ -126,7 +126,7 @@ export function parseLockfile(filePath) {
         parsed = JSON.parse(raw);
     }
     catch (err) {
-        throw new Error(`Failed to parse lockfile ${filePath}: ${err.message}`);
+        throw new Error(`Failed to parse lockfile ${filePath}: ${err.message}`, { cause: err });
     }
     if (!parsed || typeof parsed !== 'object')
         return [];
@@ -175,7 +175,7 @@ function readFileOrThrow(p, label) {
         return fs.readFileSync(p, 'utf-8');
     }
     catch (err) {
-        throw new Error(`Could not read ${label} at ${p}: ${err.message}`);
+        throw new Error(`Could not read ${label} at ${p}: ${err.message}`, { cause: err });
     }
 }
 function resolveSibling(parent, nested) {

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.10.0 on 2026-06-20T21:43:38.629Z
+// Source: brainclaw v1.10.1 on 2026-06-21T19:26:16.599Z
 export const FACTS = {
-  "version": "1.10.0",
-  "generated_at": "2026-06-20T21:43:38.629Z",
+  "version": "1.10.1",
+  "generated_at": "2026-06-21T19:26:16.599Z",
   "tools": {
     "count": 66,
     "published_count": 65,

package/dist/facts.json

@@ -1,6 +1,6 @@
 {
-  "version": "1.10.0",
-  "generated_at": "2026-06-20T21:43:38.629Z",
+  "version": "1.10.1",
+  "generated_at": "2026-06-21T19:26:16.599Z",
   "tools": {
     "count": 66,
     "published_count": 65,

package/docs/code-map.md

@@ -1,7 +1,7 @@
 # Code Map
 
-Code Map is a per-project structural index of your JavaScript / TypeScript /
-TSX codebase. It parses each supported file with Tree-sitter and records the
+Code Map is a per-project structural index of your JavaScript / TypeScript / JSX /
+TSX, Python, PHP, and Java codebase. It parses each supported file with Tree-sitter and records the
 symbols it defines (functions, classes, types, interfaces, React components and
 hooks), what it imports and exports, and how files relate — then answers fast
 "what should I read before I edit this?" questions for both human operators and
@@ -130,6 +130,17 @@ 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()`.
+
 ## Lifecycle — pull-based, no daemon
 
 Code Map never runs in the background and never auto-reindexes. The model is lazy
@@ -180,7 +191,7 @@ like any other directory.
 
 The parser is [Tree-sitter](https://tree-sitter.github.io/) compiled to
 WebAssembly. The engine glue (`web-tree-sitter`) and the prebuilt grammar `.wasm`
-files (TypeScript / TSX / JavaScript) are **bundled into the package** during the
+files (JavaScript / TypeScript / JSX / TSX, Python, PHP, Java) are **bundled into the package** during the
 build (`scripts/copy-code-map-wasm.mjs` copies them into `dist/wasm/` and vendors
 the engine glue into `dist/vendor/web-tree-sitter/`).
 

package/package.json

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