brainclaw 1.7.0 → 1.7.1

package/README.md

@@ -343,11 +343,34 @@ npm run test:coverage      # with coverage report
 
 ## Changelog
 
-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.5.3
-
-- **Cross-project canonical grammar + CLI parity** (pln#359, all phases) — the canonical grammar (`bclaw_find / get / create / update / remove / transition`), `bclaw_context`, and `bclaw_coordinate` now accept an optional `project: <name>` argument that routes the operation to a linked project. Two link kinds are recognised: `cross_project_links` (sibling/peer projects in `config.yaml`, `brainclaw link list`) and workspace store-chain children. Arbitrary directory paths are rejected — adoption requires an explicit link, which gives the user a single point of control over what an agent can reach. Identity is sourced from the caller's home registry; entity writes + audit log entries land in the target. Unknown project names throw `validation_error` with a hint listing the configured links — no silent fallback. Cross-project `bclaw_coordinate` is **inbox-only**: claim/assignment/message all land in the target, the target agent picks the brief up async via its own `bclaw_work`, and auto-spawn from the source process is force-disabled because the spawn cwd / worktree are tied to the target's git repo (a warning surfaces in `FacadeResponse.warnings`). The CLI exposes the same as a global `--project <name>` flag, mutually exclusive with `--cwd`. Refs: helper `resolveProjectCwd` in `src/core/cross-project.ts`, MCP write/read handler dispatch in `src/commands/mcp.ts` and `src/commands/mcp-read-handlers.ts`, `--project` plumbing in `src/cli.ts` preAction, surface advertisement in `src/core/instruction-templates.ts`, plus tests in `tests/unit/cross-project.test.ts` (10 unit cases on the helper), `tests/unit/bclaw-coordinate.test.ts` (4 cross-project routing cases), and `tests/cli-cross-project.test.ts` (5 e2e cases). Closes the `--cwd` workaround pattern that had been the day-to-day shape of multi-project sessions.
+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.7.1
+
+- **MCP project context isolation fix** — `bclaw_switch` now keeps MCP switches
+  session-scoped even when the agent session has to be resolved or created on
+  the fly. Session lookup honors explicit session IDs, avoids adopting another
+  live process's session, detects Codex via native `CODEX_*` runtime variables,
+  and `bclaw_switch(list=true)` reports the session active project with
+  `active_source`.
+
+### v1.7.0
+
+- **Dispatch reliability + scope-aware dirty guard** — evidence-first
+  `agent_run` reconciliation avoids false terminal states, `bclaw_coordinate`
+  accepts pinned refs and a scope-aware `allow_dirty` guard, and the Hermes
+  agent integration joins the supported surfaces.
+
+### v1.6.0
+
+- **Bootstrap loop + cross-project agent workflow** — the bootstrap ideation
+  preset can materialize `PROJECT.md`, `bclaw_init_project` initializes and links
+  arbitrary project paths, and `project=` routing reaches `bclaw_work` /
+  `bclaw_loop` for linked-project operations.
+
+### v1.5.3
+
+- **Cross-project canonical grammar + CLI parity** (pln#359, all phases) — the canonical grammar (`bclaw_find / get / create / update / remove / transition`), `bclaw_context`, and `bclaw_coordinate` now accept an optional `project: <name>` argument that routes the operation to a linked project. Two link kinds are recognised: `cross_project_links` (sibling/peer projects in `config.yaml`, `brainclaw link list`) and workspace store-chain children. Arbitrary directory paths are rejected — adoption requires an explicit link, which gives the user a single point of control over what an agent can reach. Identity is sourced from the caller's home registry; entity writes + audit log entries land in the target. Unknown project names throw `validation_error` with a hint listing the configured links — no silent fallback. Cross-project `bclaw_coordinate` is **inbox-only**: claim/assignment/message all land in the target, the target agent picks the brief up async via its own `bclaw_work`, and auto-spawn from the source process is force-disabled because the spawn cwd / worktree are tied to the target's git repo (a warning surfaces in `FacadeResponse.warnings`). The CLI exposes the same as a global `--project <name>` flag, mutually exclusive with `--cwd`. Refs: helper `resolveProjectCwd` in `src/core/cross-project.ts`, MCP write/read handler dispatch in `src/commands/mcp.ts` and `src/commands/mcp-read-handlers.ts`, `--project` plumbing in `src/cli.ts` preAction, surface advertisement in `src/core/instruction-templates.ts`, plus tests in `tests/unit/cross-project.test.ts` (10 unit cases on the helper), `tests/unit/bclaw-coordinate.test.ts` (4 cross-project routing cases), and `tests/cli-cross-project.test.ts` (5 e2e cases). Closes the `--cwd` workaround pattern that had been the day-to-day shape of multi-project sessions.
 - **Site facts contract** (umbrella `pln_7fdfd70d` sprint 0) — new `scripts/emit-site-facts.mjs` emits `dist/facts.{js,json}` from `MCP_TOOL_NAMES` + `ENTITY_NAMES` so the brainclaw-site (and any consumer) can pull live tool/entity counts at build time without forking the values into a hand-maintained config. The package `files` list ships `dist/facts.json`; build:cli runs the emitter as part of the chain.
 
 ### v1.5.2

package/dist/commands/switch.js

@@ -1,9 +1,9 @@
 import path from 'node:path';
 import { loadActiveProject, saveActiveProject, clearActiveProject } from '../core/active-project.js';
-import { loadCurrentSession, saveCurrentSession } from '../core/identity.js';
+import { buildOperationalIdentity, loadCurrentSession, saveCurrentSession } from '../core/identity.js';
 import { memoryExists } from '../core/io.js';
 import { resolveProjectRef } from '../core/store-resolution.js';
-import { resolveProjectCwd } from '../core/cross-project.js';
+import { resolveCrossProjectLinks, resolveProjectCwd } from '../core/cross-project.js';
 import { scanNestedBrainclawProjects } from '../core/workspace-projects.js';
 import { loadConfig } from '../core/config.js';
 /**
@@ -43,8 +43,12 @@ export function switchProject(projectRef, options = {}) {
     }
     catch { /* name is optional */ }
     const now = new Date().toISOString();
-    const session = loadCurrentSession(cwd);
     const sessionOnly = options.sessionOnly ?? true;
+    let session = loadCurrentSession(cwd);
+    if (!session && sessionOnly) {
+        buildOperationalIdentity(undefined, cwd, { persistImplicitSession: true });
+        session = loadCurrentSession(cwd);
+    }
     if (session && sessionOnly) {
         saveCurrentSession({
             ...session,
@@ -52,6 +56,9 @@ export function switchProject(projectRef, options = {}) {
         }, cwd);
         return { switched: true, path: resolved, name: projectName, scope: 'session', workspace_root: wsRoot };
     }
+    if (sessionOnly) {
+        throw new Error('Cannot switch project without an active agent session. Start with bclaw_work or bclaw_session_start first.');
+    }
     if (session) {
         // Also write to session even when not sessionOnly
         saveCurrentSession({
@@ -75,15 +82,30 @@ export function listAvailableProjects(cwd) {
     if (!wsRoot) {
         throw new Error('No brainclaw workspace found.');
     }
-    const active = loadActiveProject(wsRoot);
+    const sessionActive = loadCurrentSession(cwd)?.active_project;
+    const globalActive = loadActiveProject(wsRoot);
+    const active = sessionActive ?? globalActive;
+    const activeSource = sessionActive ? 'session' : globalActive ? 'global' : 'none';
     const projects = [];
+    const seen = new Set();
+    const addProject = (project) => {
+        const projectPath = path.resolve(project.path);
+        if (seen.has(projectPath))
+            return;
+        seen.add(projectPath);
+        projects.push({
+            ...project,
+            path: projectPath,
+            active: active?.path ? path.resolve(active.path) === projectPath : false,
+        });
+    };
     if (memoryExists(wsRoot)) {
         try {
             const config = loadConfig(wsRoot);
-            projects.push({ name: config.project_name, path: wsRoot, relative_path: '.', active: active?.path === wsRoot });
+            addProject({ name: config.project_name, path: wsRoot, relative_path: '.' });
         }
         catch {
-            projects.push({ path: wsRoot, relative_path: '.', active: active?.path === wsRoot });
+            addProject({ path: wsRoot, relative_path: '.' });
         }
     }
     const children = scanNestedBrainclawProjects(wsRoot, 7);
@@ -92,9 +114,19 @@ export function listAvailableProjects(cwd) {
         if (childPath === wsRoot)
             continue;
         const rel = path.relative(wsRoot, childPath) || '.';
-        projects.push({ name: child.project_name, path: childPath, relative_path: rel, active: active?.path === childPath });
+        addProject({ name: child.project_name, path: childPath, relative_path: rel });
+    }
+    for (const link of resolveCrossProjectLinks(wsRoot)) {
+        if (!link.available)
+            continue;
+        const linkPath = path.resolve(link.absolutePath);
+        addProject({
+            name: link.projectName,
+            path: linkPath,
+            relative_path: path.relative(wsRoot, linkPath) || '.',
+        });
     }
-    return { workspace_root: wsRoot, projects };
+    return { workspace_root: wsRoot, active_source: activeSource, projects };
 }
 export function runSwitch(projectRef, options = {}) {
     // Use real cwd, not effective cwd — switch must see the full workspace

package/dist/core/identity.js

@@ -2,6 +2,7 @@ import crypto from 'node:crypto';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import { detectAiAgent } from './ai-agent-detection.js';
 import { requireRegisteredAgentIdentity } from './agent-registry.js';
 import { loadConfig } from './config.js';
 import { resolveCurrentHostId } from './host.js';
@@ -75,31 +76,42 @@ export function loadCurrentSession(cwd) {
     const dir = sessionsDir(cwd);
     const currentUser = resolveCurrentUser();
     const currentAgent = resolveCurrentAgentName();
-    // 1. Look in sessions/ directory for a matching session
+    const explicitSessionId = resolveExplicitSessionId();
+    const ttlMs = parseDurationToMs(loadConfigSafe(cwd)?.implicit_session_ttl ?? '4h');
+    const now = Date.now();
+    if (explicitSessionId) {
+        const explicit = loadSessionById(explicitSessionId, cwd);
+        return explicit && isSessionAlive(explicit, ttlMs, now) ? explicit : undefined;
+    }
+    // 1. Look in sessions/ directory for the session owned by this process.
+    // Multiple parallel agents can have the same agent name/user in one repo;
+    // a live different PID is a different agent instance, not our session.
     if (fs.existsSync(dir) && currentAgent) {
         const files = fs.readdirSync(dir).filter(f => f.endsWith('.json'));
-        const ttlMs = parseDurationToMs(loadConfigSafe(cwd)?.implicit_session_ttl ?? '4h');
-        const now = Date.now();
+        const legacyPidlessCandidates = [];
         for (const file of files) {
             try {
-                const migration = loadVersionedJsonFile('current_session', path.join(dir, file));
-                const session = {
-                    ...CurrentSessionStateSchema.parse(migration.document),
-                    schema_version: migration.metadata.currentVersion,
-                };
+                const session = loadSessionFile(path.join(dir, file));
                 // Strict match: agent name must match, user must match (when both are known)
                 if (session.agent !== currentAgent)
                     continue;
                 const userMatch = !session.user || !currentUser || session.user === currentUser;
-                const alive = (now - Date.parse(session.last_seen_at)) <= ttlMs;
-                if (userMatch && alive) {
+                if (!userMatch || !isSessionAlive(session, ttlMs, now))
+                    continue;
+                if (session.pid === process.pid) {
                     return session;
                 }
+                if (session.pid === undefined) {
+                    legacyPidlessCandidates.push(session);
+                }
             }
             catch {
                 // skip invalid session files
             }
         }
+        if (legacyPidlessCandidates.length === 1) {
+            return legacyPidlessCandidates[0];
+        }
     }
     // 2. Legacy fallback: .current-session
     const legacyPath = path.join(memoryDir(cwd), LEGACY_SESSION_FILE);
@@ -246,9 +258,24 @@ function resolveCurrentUser() {
 function resolveCurrentAgentName() {
     if (process.env.BRAINCLAW_AGENT_NAME)
         return process.env.BRAINCLAW_AGENT_NAME;
-    if (process.env.CLAUDE_CODE_VERSION)
-        return 'claude-code';
-    return undefined;
+    return detectAiAgent()?.name;
+}
+function resolveExplicitSessionId(env = process.env) {
+    return env.BRAINCLAW_SESSION_ID?.trim()
+        || env.OPENCLAW_SESSION_ID?.trim()
+        || env.CLAUDE_SESSION_ID?.trim()
+        || env.COPILOT_SESSION_ID?.trim()
+        || undefined;
+}
+function loadSessionFile(filepath) {
+    const migration = loadVersionedJsonFile('current_session', filepath);
+    return {
+        ...CurrentSessionStateSchema.parse(migration.document),
+        schema_version: migration.metadata.currentVersion,
+    };
+}
+function isSessionAlive(session, ttlMs, now) {
+    return now - Date.parse(session.last_seen_at) <= ttlMs;
 }
 function loadConfigSafe(cwd) {
     try {

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.7.0 on 2026-05-28T00:12:31.140Z
+// Source: brainclaw v1.7.1 on 2026-06-02T10:24:49.702Z
 export const FACTS = {
-  "version": "1.7.0",
-  "generated_at": "2026-05-28T00:12:31.140Z",
+  "version": "1.7.1",
+  "generated_at": "2026-06-02T10:24:49.702Z",
   "tools": {
     "count": 62,
     "published_count": 61,

package/dist/facts.json

@@ -1,6 +1,6 @@
 {
-  "version": "1.7.0",
-  "generated_at": "2026-05-28T00:12:31.140Z",
+  "version": "1.7.1",
+  "generated_at": "2026-06-02T10:24:49.702Z",
   "tools": {
     "count": 62,
     "published_count": 61,

package/package.json

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