brainclaw 1.28.6 → 1.28.8

package/dist/cli.js

@@ -3,7 +3,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { Command } from 'commander';
 import { getInstalledBrainclawVersion } from './core/brainclaw-version.js';
-import { cleanOrphanFiles, memoryDir } from './core/io.js';
+import { cleanOrphanFiles, isSafeSessionId, memoryDir } from './core/io.js';
 import { initLogLevel, logger } from './core/logger.js';
 import { resolveEffectiveCwd } from './core/store-resolution.js';
 import { resolveProjectCwd } from './core/cross-project.js';
@@ -82,6 +82,38 @@ function trailingGlobalOptionError(argv, actionCommand) {
     }
     return undefined;
 }
+/**
+ * Hook subprocesses do not reliably inherit the MCP process environment. The
+ * agent integrations do, however, provide their session identity in the JSON
+ * event on stdin. Hydrate it before preAction resolves the effective project;
+ * otherwise a session-scoped switch silently falls back to the workspace root.
+ *
+ * This is deliberately best-effort: hooks are advisory, stdin may be empty or
+ * non-JSON, and an explicitly exported session id remains authoritative.
+ */
+function hydrateHookSessionFromStdin(argv) {
+    if (!argv.includes('--hook') || process.stdin.isTTY || process.env.BRAINCLAW_SESSION_ID)
+        return;
+    try {
+        const raw = fs.readFileSync(0, 'utf8').trim();
+        if (!raw)
+            return;
+        const event = JSON.parse(raw);
+        const sessionId = typeof event.session_id === 'string'
+            ? event.session_id.trim()
+            : typeof event.sessionId === 'string'
+                ? event.sessionId.trim()
+                : typeof event.metadata?.session === 'string'
+                    ? event.metadata.session.trim()
+                    : '';
+        if (sessionId && isSafeSessionId(sessionId)) {
+            process.env.BRAINCLAW_SESSION_ID = sessionId;
+        }
+    }
+    catch {
+        // Invalid hook input must never break the agent's prompt loop.
+    }
+}
 /**
  * Resolve the (possibly nested) subcommand named in argv without parsing.
  * Used to run the trailing-global-option guard BEFORE Commander parses:
@@ -122,7 +154,9 @@ program
     .option('--cwd <path>', 'Override working directory for this invocation')
     .option('--project <name>', 'Run the command against a linked project (cross_project_links or workspace store-chain child). Resolves via resolveProjectCwd; mutually exclusive with --cwd.')
     .hook('preAction', (_thisCommand, actionCommand) => {
-    const root = parseLeadingGlobalOptions(process.argv.slice(2));
+    const argv = process.argv.slice(2);
+    hydrateHookSessionFromStdin(argv);
+    const root = parseLeadingGlobalOptions(argv);
     initLogLevel({ verbose: root.verbose, debug: root.debug });
     // Skip effective cwd resolution for commands that create the store
     const cmdName = actionCommand.name();
@@ -146,14 +180,18 @@ program
     }
     if (!skipResolution) {
         // Resolve effective cwd (explicit > BRAINCLAW_PROJECT > active-project > process.cwd)
+        const resolutionStarted = performance.now();
         const effectiveCwd = resolveEffectiveCwd({ explicitCwd });
+        logger.debug(`Startup project resolution: ${(performance.now() - resolutionStarted).toFixed(1)}ms`);
         if (effectiveCwd !== process.cwd()) {
             // Change process.cwd() so all commands resolve the correct store
             // without needing individual --cwd plumbing
             process.chdir(effectiveCwd);
             logger.info(`Resolved effective cwd: ${effectiveCwd}`);
         }
+        const cleanupStarted = performance.now();
         const removed = cleanOrphanFiles(memoryDir());
+        logger.debug(`Startup orphan cleanup: ${(performance.now() - cleanupStarted).toFixed(1)}ms`);
         if (removed > 0) {
             logger.info(`Cleaned ${removed} orphan lock/tmp file(s) in ${memoryDir()}`);
         }

package/dist/core/io.js

@@ -519,30 +519,32 @@ export function writeFileAtomic(filepath, content, options = {}) {
  * Call once at CLI startup. Returns count of removed files.
  */
 export function cleanOrphanFiles(dirPath) {
+    return cleanOrphanDirectory(dirPath, true);
+}
+function cleanOrphanDirectory(dirPath, root) {
     let removed = 0;
-    if (!fs.existsSync(dirPath))
-        return 0;
-    // Clean .tmp files (residual from crashed writeFileAtomic)
+    // Historical/derived trees are not startup-maintenance targets. Their writers
+    // reclaim stale locks when acquiring them; scanning their contents here makes
+    // connection latency proportional to Git history and Code Map size.
+    const excluded = new Set(['.git', 'code', 'archive', 'gc-backups', 'migration-backups', 'recovery-backups']);
     try {
-        for (const entry of fs.readdirSync(dirPath)) {
-            const full = path.join(dirPath, entry);
-            let stat;
-            try {
-                stat = fs.statSync(full);
+        for (const entry of fs.readdirSync(dirPath, { withFileTypes: true })) {
+            const full = path.join(dirPath, entry.name);
+            // Dirents avoid a stat per entity and do not follow symlinks/junctions.
+            if (entry.isDirectory()) {
+                const name = entry.name.toLowerCase();
+                if (name !== '.git' && !(root && excluded.has(name)))
+                    removed += cleanOrphanDirectory(full, false);
             }
-            catch {
-                continue;
-            }
-            if (entry.endsWith('.tmp') && stat.isFile() && shouldRemoveTmp(entry, stat)) {
+            else if (entry.isFile() && tempOwnerPid(entry.name)) {
                 try {
-                    fs.unlinkSync(full);
-                    removed++;
+                    const stat = fs.lstatSync(full);
+                    if (stat.isFile() && shouldRemoveTmp(entry.name, stat)) {
+                        fs.unlinkSync(full);
+                        removed++;
+                    }
                 }
-                catch { /* already gone */ }
-            }
-            // Recurse into subdirectories
-            if (stat.isDirectory()) {
-                removed += cleanOrphanFiles(full);
+                catch { /* disappeared or unreadable — skip */ }
             }
         }
     }

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.28.6 on 2026-08-28T22:03:41.224Z
+// Source: brainclaw v1.28.8 on 2026-09-09T12:16:44.520Z
 export const FACTS = {
-  "version": "1.28.6",
-  "generated_at": "2026-08-28T22:03:41.224Z",
+  "version": "1.28.8",
+  "generated_at": "2026-09-09T12:16:44.520Z",
   "tools": {
     "count": 71,
     "published_count": 69,
@@ -479,8 +479,8 @@ export const FACTS = {
   },
   "bench": {
     "schema": "brainclaw.bench.v1",
-    "generated_at": "2026-08-28T22:03:39.012Z",
-    "node_version": "v24.19.0",
+    "generated_at": "2026-09-09T12:16:42.258Z",
+    "node_version": "v24.20.0",
     "platform": "linux-x64",
     "repeats": 3,
     "scenarios": [
@@ -488,7 +488,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": 77,
+        "duration_ms_median": 88,
         "payload_chars_median": 1640,
         "payload_tokens_est_median": 410
       },
@@ -496,7 +496,7 @@ 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": 129,
+        "duration_ms_median": 136,
         "payload_chars_median": 2626,
         "payload_tokens_est_median": 657
       },

package/dist/facts.json

@@ -1,6 +1,6 @@
 {
-  "version": "1.28.6",
-  "generated_at": "2026-08-28T22:03:41.224Z",
+  "version": "1.28.8",
+  "generated_at": "2026-09-09T12:16:44.520Z",
   "tools": {
     "count": 71,
     "published_count": 69,
@@ -477,8 +477,8 @@
   },
   "bench": {
     "schema": "brainclaw.bench.v1",
-    "generated_at": "2026-08-28T22:03:39.012Z",
-    "node_version": "v24.19.0",
+    "generated_at": "2026-09-09T12:16:42.258Z",
+    "node_version": "v24.20.0",
     "platform": "linux-x64",
     "repeats": 3,
     "scenarios": [
@@ -486,7 +486,7 @@
         "name": "cold_onboard",
         "volume": "empty",
         "description": "fresh machine → init → first useful context. Baseline for time-to-first-value.",
-        "duration_ms_median": 77,
+        "duration_ms_median": 88,
         "payload_chars_median": 1640,
         "payload_tokens_est_median": 410
       },
@@ -494,7 +494,7 @@
         "name": "warm_work",
         "volume": "medium",
         "description": "bclaw_work consult over a real-shaped store (~200 plans / 500 handoffs / 450 claims).",
-        "duration_ms_median": 129,
+        "duration_ms_median": 136,
         "payload_chars_median": 2626,
         "payload_tokens_est_median": 657
       },

package/docs/integrations/mcp.md

@@ -564,4 +564,19 @@ The CLI remains valuable for:
 - release and packaging
 - debugging and fallback access
 
+### Diagnose MCP startup
+
+Measure startup with a fresh subprocess rather than timing a tool call on an
+existing connection:
+
+```bash
+node scripts/bench-mcp-startup.mjs --cwd . --cli dist/cli.js --repeats 3 --budget-ms 20000
+```
+
+The benchmark covers process launch, `initialize`, the initialized
+notification, and `tools/list`. It requires an explicit project directory
+because normal CLI startup maintenance may update that store. Pass `--debug`
+before the `mcp` command to report project-resolution and orphan-cleanup
+durations on stderr without corrupting JSON-RPC stdout.
+
 But for capable agents, MCP is the first-class path for both reads and writes.

package/package.json

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