brainclaw 1.6.0 → 1.7.1

package/README.md

@@ -14,7 +14,7 @@ If you've ever:
 - watched two coworkers (or two agents) **edit the same files** without knowing it,
 - or **gave up running multiple agents in parallel** because keeping them in sync was a pain,
 
-brainclaw gives you durable shared state across sessions, agents, and teammates. Plans, claims, handoffs, decisions, and traps live in `.brainclaw/`, work identically across any compatible agent (Claude Code, Codex, Copilot, Cline, OpenCode, Cursor, Windsurf, Kilocode, Roo Code, Continue, Mistral Vibe, Antigravity/Gemini CLI, …), and stay accessible whether you orchestrate them in parallel or pick them up one after another.
+brainclaw gives you durable shared state across sessions, agents, and teammates. Plans, claims, handoffs, decisions, and traps live in `.brainclaw/`, work identically across any compatible agent (Claude Code, Codex, Copilot, Cline, OpenCode, Cursor, Windsurf, Kilocode, Roo Code, Continue, Mistral Vibe, Hermes, Antigravity/Gemini CLI, …), and stay accessible whether you orchestrate them in parallel or pick them up one after another.
 
 Use it two ways — **together or separately**:
 
@@ -81,7 +81,8 @@ brainclaw is designed to sit alongside the coding agents teams are already using
 
 | Logo | Agent | Tier | What brainclaw configures |
 |---|---|---|---|
-| [![OpenClaw](https://img.shields.io/badge/OpenClaw-FF6B35?logoColor=white)](https://github.com/openclaw/openclaw) | **[OpenClaw](https://github.com/openclaw/openclaw)** | B | MCP + brainclaw skill (SKILL.md) for structured project memory |
+| [![OpenClaw](https://img.shields.io/badge/OpenClaw-FF6B35?logoColor=white)](https://github.com/openclaw/openclaw) | **[OpenClaw](https://github.com/openclaw/openclaw)** | B | MCP + brainclaw skill (SKILL.md) for structured project memory |
+| [![Hermes](https://img.shields.io/badge/Hermes-111111?logoColor=white)](https://github.com/NousResearch/hermes-agent) | **[Hermes Agent](https://github.com/NousResearch/hermes-agent)** | B | MCP + universal `.agents/skills/brainclaw/SKILL.md` |
 | [![NanoClaw](https://img.shields.io/badge/NanoClaw-4A90D9?logoColor=white)](https://github.com/qwibitai/nanoclaw) | **[NanoClaw](https://github.com/qwibitai/nanoclaw)** | C | brainclaw skill — messaging agent (WhatsApp, Telegram, Slack) |
 | [![NemoClaw](https://img.shields.io/badge/NemoClaw-76B900?logo=nvidia&logoColor=white)](https://github.com/NVIDIA/NemoClaw) | **[NemoClaw](https://github.com/NVIDIA/NemoClaw)** | C | brainclaw skill — NVIDIA enterprise agent stack |
 | [![PicoClaw](https://img.shields.io/badge/PicoClaw-00ADD8?logo=go&logoColor=white)](https://github.com/sipeed/picoclaw) | **[PicoClaw](https://github.com/sipeed/picoclaw)** | C | brainclaw skill — edge/IoT agent (Go, <10MB RAM) |
@@ -132,7 +133,7 @@ npm install -g brainclaw
 brainclaw setup-machine --yes
 ```
 
-This detects the installed agents on the current machine, writes the machine-level MCP and user config Brainclaw manages, and does **not** scan or initialize repositories.
+This detects the installed coding agents on the current machine, writes the machine-level MCP and user config Brainclaw manages for that detected set, and does **not** scan or initialize repositories.
 
 ### 4. Initialize or refresh the current project
 
@@ -231,7 +232,7 @@ Still sharp:
 1. **Same-checkout concurrent edits** — running two agents in the *same* working tree (no per-claim worktree) is still the wrong answer. Use the dispatch path (auto-worktree per claim) instead of raw concurrent CLI sessions.
 2. **Cross-machine sync** — federation across machines is on the roadmap, not in v1.x. Today brainclaw's store is local and one-machine-per-project.
 3. **Spawn-and-forget assumptions** — spawned workers don't always commit their work cleanly. The brief-ack file confirms the spawn started; in the worst case the coordinator harvests open changes.
-4. **Live state for hook-less agents** — Tier B/C agents without lifecycle hooks (Cursor, Cline, Windsurf, Copilot, Continue, Kilocode, Mistral Vibe) get live context via `.live.md` companions regenerated on session-end and handoff, not via real-time push.
+4. **Live state for hook-less agents** — Tier B/C agents without lifecycle hooks (Cursor, Cline, Windsurf, Copilot, Continue, Kilocode, Mistral Vibe, Hermes) get live context via `.live.md` companions regenerated on session-end and handoff, not via real-time push.
 
 Recommended use today:
 
@@ -342,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/mcp-schemas.generated.js

@@ -106,6 +106,25 @@ export const generatedSchemas = {
                                 ],
                                 "additionalProperties": false
                             },
+                            {
+                                "type": "object",
+                                "properties": {
+                                    "kind": {
+                                        "type": "string",
+                                        "const": "min_iterations"
+                                    },
+                                    "n": {
+                                        "type": "integer",
+                                        "exclusiveMinimum": 0,
+                                        "maximum": 9007199254740991
+                                    }
+                                },
+                                "required": [
+                                    "kind",
+                                    "n"
+                                ],
+                                "additionalProperties": false
+                            },
                             {
                                 "type": "object",
                                 "properties": {
@@ -161,6 +180,19 @@ export const generatedSchemas = {
                                 ],
                                 "additionalProperties": false
                             },
+                            {
+                                "type": "object",
+                                "properties": {
+                                    "kind": {
+                                        "type": "string",
+                                        "const": "no_open_questions"
+                                    }
+                                },
+                                "required": [
+                                    "kind"
+                                ],
+                                "additionalProperties": false
+                            },
                             {
                                 "type": "object",
                                 "properties": {
@@ -254,6 +286,7 @@ export const generatedSchemas = {
                     "open",
                     "assigned",
                     "working",
+                    "waiting_input",
                     "done",
                     "failed",
                     "cancelled"

package/dist/commands/mcp.js

@@ -1,5 +1,6 @@
 import crypto from 'node:crypto';
 import fs from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 import { buildClaimEnvPrefix } from '../core/execution-profile.js';
 import { fileURLToPath } from 'node:url';
@@ -35,10 +36,11 @@ import { buildOperationalIdentity, loadAllSessions, loadSessionById } from '../c
 import { validateMcpInput, validateMcpField } from '../core/input-validation.js';
 import { createCapability, createTool as createRegistryTool } from '../core/registries.js';
 import { detectAiAgent } from '../core/ai-agent-detection.js';
-import { checkGitPresence, scanGitRepos, parseRoots, parseRepoSelection, parseAgentSelection, runGlobalInstall, initReposAndConfigureAgents, readSetupState, ALL_KNOWN_AGENTS, } from './setup.js';
+import { checkGitPresence, scanGitRepos, parseRoots, parseRepoSelection, parseAgentSelection, getDetectedSetupAgentNames, getInstalledAgentNames, runGlobalInstall, initReposAndConfigureAgents, readSetupState, ALL_KNOWN_AGENTS, } from './setup.js';
+import { buildAgentInventory } from '../core/agent-inventory.js';
 import { resolveEffectiveCwd, resolveProjectRef, resolveTargetStore } from '../core/store-resolution.js';
 import { probeForQuickSetup, buildQuickSetupProbeResponse, buildOnboardingPreview } from '../core/setup-flow.js';
-import { ensureUserStore } from '../core/setup-state.js';
+import { ensureUserStore, resolveHomeDir } from '../core/setup-state.js';
 import { createPlan, addStep as addStepOp, completeStep as completeStepOp, updateStep as updateStepOp, deleteStep as deleteStepOp, deletePlan as deletePlanOp } from '../core/operations/plan.js';
 import { sendMessage, ackMessage, countActionable, getThread, hasActiveAssignment } from '../core/messaging.js';
 import { dispatch, dispatchReview, generateDispatchBrief } from '../core/dispatcher.js';
@@ -421,7 +423,7 @@ export const MCP_READ_TOOLS = [
 const MCP_WRITE_TOOLS = [
     {
         name: 'bclaw_dispatch',
-        description: 'Unified dispatch entry for sequence-lane parallelization (parallelize plans across lanes). To open a NEW review of a commit/branch, use `bclaw_coordinate(intent="review", open_loop=true, targetAgents=[…])` instead — bclaw_dispatch is for sequence-driven execution, NOT for opening reviews. `intent` discriminator: analysis (sequence lane status, read-only), execute (default — analyze + generate briefs + send to agents), review (routes an EXISTING already-reflected handoff to a reviewer — only for handoffs produced by `session-end --reflect-handoff` or similar). Consolidates the legacy bclaw_dispatch_analysis / bclaw_dispatch / bclaw_dispatch_review. Returns FacadeResponse; for verification semantics see the same response-validation guidance documented on `bclaw_coordinate`.',
+        description: 'Unified dispatch entry for sequence-lane parallelization (parallelize plans across lanes). To open a NEW review of a commit/branch, use `bclaw_coordinate(intent="review", open_loop=true, targetAgents=[…])` instead — bclaw_dispatch is for sequence-driven execution, NOT for opening new reviews. `intent` discriminator: analysis (sequence lane status, read-only), execute (default — analyze + generate briefs + send to agents), review (routes an EXISTING already-reflected handoff to a reviewer — only for handoffs produced by `session-end --reflect-handoff` or similar). Consolidates the legacy bclaw_dispatch_analysis / bclaw_dispatch / bclaw_dispatch_review. Returns FacadeResponse; for verification semantics see the same response-validation guidance documented on `bclaw_coordinate`.',
         annotations: { tier: 'facade', category: 'coordination', headlessApproval: 'prompt' },
         inputSchema: {
             type: 'object',
@@ -947,6 +949,8 @@ const MCP_WRITE_TOOLS = [
                 agent: { type: 'string', description: 'Caller agent name.' },
                 agentId: { type: 'string', description: 'Caller registered agent id.' },
                 project: { type: 'string', description: 'Optional (pln#359 phase 1b): name of a linked project to dispatch into. When set, claim/assignment/message all land in the target project — the target agent picks the brief up async via its own bclaw_work. Auto-spawn is disabled in cross-project mode. Accepts cross_project_links and workspace store-chain children (see `brainclaw link list`).' },
+                allow_dirty: { type: 'boolean', description: 'Override the scope-aware dirty-working-tree guard (trp#371 Tier 2). The guard runs only for worktree-spawning intents (assign/review/reroute) and blocks only when uncommitted files overlap — or cannot be proven disjoint from — the dispatch scope (the worker spawns from HEAD and will not see them). `.brainclaw/` and `.git/` are always excluded. Set true to proceed anyway (the block is downgraded to a warning that lists the overlapping files). Boolean; the string "true"/"false" are also coerced.' },
+                ref: { type: 'string', description: 'Optional git ref (commit/branch/tag) for assign/review/reroute: the dispatched worker builds its worktree from this ref instead of HEAD. When set, uncommitted working-tree changes are intentionally out of scope and the dirty guard allows the dispatch. Ignored by consult/ideate/summarize (no worktree).' },
             },
             required: ['intent', 'task'],
         },
@@ -1260,6 +1264,7 @@ export const FACADE_ORDER = [
     'bclaw_context',
     'bclaw_coordinate',
     'bclaw_dispatch',
+    'bclaw_dispatch_status',
     'bclaw_loop',
     'bclaw_setup',
 ];
@@ -2390,8 +2395,14 @@ async function _executeMcpToolCallInner(payload) {
                 const repos = scanGitRepos(roots);
                 const selectedRepos = parseRepoSelection(choice, repos, cwd);
                 const detected = detectAiAgent(env);
-                const agentList = ALL_KNOWN_AGENTS.map((a, i) => `  ${i + 1}) ${a}${a === detected?.name ? ' ← detected' : ''}`).join('\n');
-                return { response: toolResponse({ content: [{ type: 'text', text: `Selected ${selectedRepos.length} repo(s). Detected AI agent: ${detected?.name ?? 'none'}.\n\nAvailable agents:\n${agentList}\n\nAsk the user which agents to configure.` }], structuredContent: { pending_question: 'agent_selection', roots: rootsArg, repo_selection: choice, selected_repos: selectedRepos.map((r) => ({ path: r.path, name: r.name })), detected_agent: detected?.name ?? null, all_agents: ALL_KNOWN_AGENTS, prompt: 'Please ask the user: "Which agents to configure? Reply: (d)etected, (a)ll, or agent names like claude-code,cursor"' } }) };
+                const installedAgents = getInstalledAgentNames(buildAgentInventory(resolveHomeDir(env) ?? os.homedir(), env));
+                const detectedSetupAgents = getDetectedSetupAgentNames(detected?.name, installedAgents);
+                const agentList = ALL_KNOWN_AGENTS.map((a, i) => {
+                    const tag = a === detected?.name ? ' ← detected' : installedAgents.includes(a) ? ' ← installed' : '';
+                    return `  ${i + 1}) ${a}${tag}`;
+                }).join('\n');
+                const detectedLine = detectedSetupAgents.length > 0 ? `\nDetected install set: ${detectedSetupAgents.join(', ')}\n` : '\n';
+                return { response: toolResponse({ content: [{ type: 'text', text: `Selected ${selectedRepos.length} repo(s). Detected AI agent: ${detected?.name ?? 'none'}.${detectedLine}\nAvailable agents:\n${agentList}\n\nAsk the user which agents to configure.` }], structuredContent: { pending_question: 'agent_selection', roots: rootsArg, repo_selection: choice, selected_repos: selectedRepos.map((r) => ({ path: r.path, name: r.name })), detected_agent: detected?.name ?? null, installed_agents: installedAgents, detected_setup_agents: detectedSetupAgents, all_agents: ALL_KNOWN_AGENTS, prompt: 'Please ask the user: "Which agents to configure? Reply: (d)etected installed, (a)ll, or agent names like claude-code,cursor"' } }) };
             }
             if (step === 'agent_selection') {
                 if (!rootsArg || !repoSelectionArg) {
@@ -2401,7 +2412,8 @@ async function _executeMcpToolCallInner(payload) {
                 const repos = scanGitRepos(roots);
                 const selectedRepos = parseRepoSelection(repoSelectionArg, repos, cwd);
                 const detected = detectAiAgent(env);
-                const selectedAgents = parseAgentSelection(choice, detected?.name);
+                const installedAgents = getInstalledAgentNames(buildAgentInventory(resolveHomeDir(env) ?? os.homedir(), env));
+                const selectedAgents = parseAgentSelection(choice, detected?.name, installedAgents);
                 const summary = [];
                 const written = runGlobalInstall(selectedAgents, env);
                 for (const f of written)
@@ -4426,31 +4438,11 @@ async function _executeMcpToolCallInner(payload) {
                     };
                 }
             }
-            // can_30c295b4 — pre-flight uncommitted-changes check.
-            // Dispatches that spawn a worker (review/assign/consult/ideate) clone
-            // the source repo at HEAD into a worktree. Any uncommitted edits in
-            // the source cwd are invisible to the worker, so the worker reviews
-            // stale code without any error signal. Refuse the dispatch by default
-            // when the source cwd is a git repo with a dirty working tree.
-            // Override via allow_dirty=true when the caller knows the dispatched
-            // work doesn't depend on the modified files (e.g. tests, docs-only
-            // worker tasks). Has no effect when cwd is not a git repo.
-            if (!req.allow_dirty && (req.intent === 'review' || req.intent === 'assign' || req.intent === 'consult' || req.intent === 'ideate')) {
-                try {
-                    const { spawnSync } = await import('node:child_process');
-                    const probe = spawnSync('git', ['-C', cwd, 'status', '--porcelain'], { encoding: 'utf8', timeout: 5000 });
-                    if (probe.status === 0 && typeof probe.stdout === 'string' && probe.stdout.trim().length > 0) {
-                        const fileCount = probe.stdout.trim().split('\n').length;
-                        return {
-                            response: createToolErrorResponse('dirty_working_tree', `Refusing to dispatch: source working tree has ${fileCount} uncommitted file(s). The spawned worker will not see these changes (worktrees branch from HEAD). Commit or stash before dispatching, or pass allow_dirty=true to override. Source cwd: ${cwd}`),
-                        };
-                    }
-                    // probe.status !== 0 → not a git repo (or git unavailable) → skip the check silently
-                }
-                catch {
-                    // best-effort: never block dispatch on a pre-flight check failure unrelated to the actual dirty state
-                }
-            }
+            // can_30c295b4 / trp#371 Tier 2 — the scope-aware dirty-working-tree
+            // guard runs LOWER DOWN, after dispatchCwd / isCrossProject are
+            // resolved (so it probes the dispatch TARGET, not the source, and only
+            // for the intents that actually spawn a worktree worker). See the
+            // assessDirtyDispatchGuard call after the cross-project block.
             const warnings = [];
             const artifacts = [];
             const side_effects = [];
@@ -4504,6 +4496,43 @@ async function _executeMcpToolCallInner(payload) {
                 warnings.push(`cross-project dispatch (project='${req.project}') — auto-spawn disabled; the target agent picks up the brief async via its own bclaw_work.`);
             }
             const effectiveAutoExecute = isCrossProject ? false : req.autoExecute;
+            // can_30c295b4 / trp#371 Tier 2 — scope-aware dirty-working-tree guard.
+            // Only intents that spawn a worktree worker from HEAD can review/edit
+            // stale code, so consult/ideate/summarize are NOT guarded (no worktree
+            // → nothing to protect). Cross-project dispatch is inbox-only (no local
+            // worktree spawned here) so it is skipped too — the target agent builds
+            // its own worktree later via bclaw_work. The guard compares the dirty
+            // files against the dispatch scope and only blocks when overlap can't be
+            // ruled out; allow_dirty=true downgrades a block to a warning, and an
+            // explicit ref makes working-tree dirt intentionally out of scope.
+            const WORKTREE_SPAWNING_INTENTS = new Set(['assign', 'review', 'reroute']);
+            if (!isCrossProject && WORKTREE_SPAWNING_INTENTS.has(req.intent)) {
+                // Probe with the SAME scope the dispatch will actually claim, so the
+                // resolution mirrors reality (codex r1): assign falls back to the task
+                // text (mcp ~assignScope), reroute to the targeted active claim's scope.
+                let guardScope = req.scope;
+                if (req.intent === 'assign') {
+                    guardScope = req.scope ?? req.task;
+                }
+                else if (req.intent === 'reroute' && !req.scope) {
+                    guardScope = listClaims(dispatchCwd).find((c) => c.status === 'active')?.scope;
+                }
+                const { assessDirtyDispatchGuard } = await import('../core/dirty-scope.js');
+                const assessment = assessDirtyDispatchGuard({
+                    cwd: dispatchCwd,
+                    scope: guardScope,
+                    allowDirty: req.allow_dirty,
+                    checkoutRef: req.ref,
+                });
+                if (assessment.decision === 'block') {
+                    return {
+                        response: createToolErrorResponse('dirty_working_tree', `${assessment.reason} (cwd: ${dispatchCwd})`),
+                    };
+                }
+                if (assessment.decision === 'warn') {
+                    warnings.push(`dirty_working_tree: ${assessment.reason}`);
+                }
+            }
             /** Run E2E execution phase on prepared delivery entries. Returns overall execution status. */
             const runCoordinateExecution = async (prepared, opts) => {
                 let overall = 'inbox_only';
@@ -4756,6 +4785,10 @@ async function _executeMcpToolCallInner(payload) {
                         dispatcherAgent: senderAgent,
                         sessionId: connectionSessionId,
                         cwd: dispatchCwd,
+                        // createCoordinatorClaim guarantees the worktree reflects this ref
+                        // (resets a stale branch / re-points a reused worktree) — see the
+                        // worktreeBaseRef invariant there (pln#520 Tier 2).
+                        worktreeBaseRef: req.ref,
                     });
                     const claimId = claimResult.claimId;
                     if (claimResult.worktreeWarning) {
@@ -4996,6 +5029,7 @@ async function _executeMcpToolCallInner(payload) {
                                     dispatcherAgent: senderAgent,
                                     sessionId: connectionSessionId,
                                     cwd: dispatchCwd,
+                                    worktreeBaseRef: req.ref,
                                 });
                                 if (claimResult.worktreeWarning)
                                     out.warnings.push(claimResult.worktreeWarning);
@@ -5184,6 +5218,7 @@ async function _executeMcpToolCallInner(payload) {
                             dispatcherAgent: senderAgent,
                             sessionId: connectionSessionId,
                             cwd: dispatchCwd,
+                            worktreeBaseRef: req.ref,
                         });
                         newClaimId = rerouteClaimResult.claimId;
                         if (rerouteClaimResult.worktreeWarning) {

package/dist/commands/setup.js

@@ -1,4 +1,5 @@
 import fs from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 import readline from 'node:readline/promises';
 import { spawnSync } from 'node:child_process';
@@ -7,7 +8,7 @@ import { detectAiAgent } from '../core/ai-agent-detection.js';
 import { buildAiSurfaceInventory, renderAiSurfaceUsageHints } from '../core/ai-surface-inventory.js';
 import { buildMachineProfile, saveMachineProfile, loadMachineProfile } from '../core/machine-profile.js';
 import { buildAgentInventory, saveAgentInventory, loadAgentInventory } from '../core/agent-inventory.js';
-import { ensureClaudeCodeUserSettings, ensureClaudeCodeUserCommand, ensureCursorMcpConfig, ensureWindsurfMcpConfig, ensureAntigravityMcpConfig, ensureContinueUserMcpConfig, ensureContinueUserPermissions, ensureCodexMcpConfig, writeDetectedAgentAutoConfig, describeAutoConfigWrite, ensureGitignoreEntries, collectWorkspaceGitignoreEntries, BRAINCLAW_EXCLUSIVE_DIRECTORIES, } from '../core/agent-files.js';
+import { ensureClaudeCodeUserSettings, ensureClaudeCodeUserCommand, ensureCursorMcpConfig, ensureWindsurfMcpConfig, ensureAntigravityMcpConfig, ensureContinueUserMcpConfig, ensureContinueUserPermissions, ensureCodexMcpConfig, ensureHermesMcpConfig, writeDetectedAgentAutoConfig, describeAutoConfigWrite, ensureGitignoreEntries, collectWorkspaceGitignoreEntries, BRAINCLAW_EXCLUSIVE_DIRECTORIES, } from '../core/agent-files.js';
 import { MEMORY_DIR, memoryExists, ensureMemoryDir } from '../core/io.js';
 import { saveConfig, defaultConfig } from '../core/config.js';
 import { readSetupState, resolveHomeDir, writeSetupState } from '../core/setup-state.js';
@@ -25,6 +26,9 @@ export const ALL_KNOWN_AGENTS = [
     'antigravity',
     'continue',
     'roo',
+    'kilocode',
+    'mistral-vibe',
+    'hermes',
     'openclaw',
     'nanoclaw',
     'nemoclaw',
@@ -135,13 +139,46 @@ export function parseRepoSelection(choice, repos, cwd = process.cwd()) {
     return indices.map((i) => repos[i]);
 }
 // ─── Step 4: Agent selection ──────────────────────────────────────────────────
-export function parseAgentSelection(choice, detected) {
+function uniqueKnownAgents(names) {
+    const seen = new Set();
+    const result = [];
+    for (const name of names) {
+        if (!name || !ALL_KNOWN_AGENTS.includes(name))
+            continue;
+        if (seen.has(name))
+            continue;
+        seen.add(name);
+        result.push(name);
+    }
+    return result;
+}
+export function getInstalledAgentNames(inventory) {
+    return uniqueKnownAgents(inventory?.agents.filter((agent) => agent.installed).map((agent) => agent.name) ?? []);
+}
+export function getDetectedSetupAgentNames(detected, installedAgents = []) {
+    return uniqueKnownAgents([
+        detected,
+        ...ALL_KNOWN_AGENTS.filter((agent) => installedAgents.includes(agent)),
+    ]);
+}
+export function parseAgentSelection(choice, detected, installedAgents = []) {
     const c = choice.trim().toLowerCase();
     if (c === 'a' || c === 'all')
         return [...ALL_KNOWN_AGENTS];
-    if (c === 'd' || c === 'detected')
-        return detected ? [detected] : [];
-    return c.split(',').map((a) => a.trim()).filter((a) => ALL_KNOWN_AGENTS.includes(a));
+    if (c === 'd' || c === 'detected' || c === 'installed') {
+        return getDetectedSetupAgentNames(detected, installedAgents);
+    }
+    const selected = [];
+    for (const token of c.split(',').map((a) => a.trim()).filter(Boolean)) {
+        const index = Number.parseInt(token, 10);
+        if (/^\d+$/.test(token) && index >= 1 && index <= ALL_KNOWN_AGENTS.length) {
+            selected.push(ALL_KNOWN_AGENTS[index - 1]);
+            continue;
+        }
+        if (ALL_KNOWN_AGENTS.includes(token))
+            selected.push(token);
+    }
+    return uniqueKnownAgents(selected);
 }
 // ─── Step 5: Global install ───────────────────────────────────────────────────
 export function initUserStore(home, env = process.env) {
@@ -237,6 +274,11 @@ export function runGlobalInstall(selectedAgents, env = process.env) {
         if (r && (r.created || r.updated))
             written.push(r.filePath);
     }
+    if (selectedAgents.includes('hermes')) {
+        const r = ensureHermesMcpConfig(home);
+        if (r && (r.created || r.updated))
+            written.push(r.filePath);
+    }
     return written;
 }
 // ─── Step 6: Init repos + configure agents ────────────────────────────────────
@@ -331,30 +373,35 @@ function logDetectedAgentSurfaces(detectedName, detectedSurfaces) {
         console.log('These surfaces are tracked separately from coding agents and will use tailored onboarding flows.');
     }
 }
-async function resolveSelectedAgentsForSetup(options, detectedName) {
+async function resolveSelectedAgentsForSetup(options, detectedName, installedAgents = []) {
+    const detectedSetupAgents = getDetectedSetupAgentNames(detectedName, installedAgents);
     console.log('Supported agents:');
     ALL_KNOWN_AGENTS.forEach((a, i) => {
         const tag = a === detectedName ? ' ← detected' : '';
-        console.log(`  ${i + 1}) ${a}${tag}`);
+        const installedTag = installedAgents.includes(a) ? ' ← installed' : '';
+        console.log(`  ${i + 1}) ${a}${tag}${tag ? '' : installedTag}`);
     });
+    if (detectedSetupAgents.length > 0) {
+        console.log(`Detected install set: ${detectedSetupAgents.join(', ')}`);
+    }
     let agentChoice;
     if (options.agents) {
         agentChoice = options.agents;
     }
     else if (options.yes || !process.stdin.isTTY) {
-        agentChoice = detectedName ? 'detected' : 'all';
+        agentChoice = detectedSetupAgents.length > 0 ? 'detected' : 'all';
     }
     else {
-        const defaultChoice = detectedName ? 'detected' : 'all';
+        const defaultChoice = detectedSetupAgents.length > 0 ? 'detected' : 'all';
         const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
         try {
-            agentChoice = (await rl.question(`Configure agents: (d)etected, (a)ll, or numbers e.g. 1,3 [${defaultChoice}]: `)).trim() || defaultChoice;
+            agentChoice = (await rl.question(`Configure agents: (d)etected installed, (a)ll, names, or numbers e.g. 1,3 [${defaultChoice}]: `)).trim() || defaultChoice;
         }
         finally {
             rl.close();
         }
     }
-    const selectedAgents = parseAgentSelection(agentChoice, detectedName);
+    const selectedAgents = parseAgentSelection(agentChoice, detectedName, installedAgents);
     console.log(`Selected agents: ${selectedAgents.length === 0 ? '(none)' : selectedAgents.join(', ')}`);
     return selectedAgents;
 }
@@ -364,10 +411,12 @@ export async function runSetupMachine(options = {}) {
     const detectedName = detectedAi?.name;
     const testMode = process.env.BRAINCLAW_TEST_MODE === '1';
     const detectedSurfaces = testMode ? [] : buildAiSurfaceInventory();
+    const agentInventory = testMode ? undefined : buildAgentInventory(resolveHomeDir(env) ?? os.homedir(), env);
+    const installedAgents = getInstalledAgentNames(agentInventory);
     console.log(BRAINCLAW_ASCII);
     console.log('Machine bootstrap only — no repositories will be scanned or initialized.');
     logDetectedAgentSurfaces(detectedName, detectedSurfaces);
-    const selectedAgents = await resolveSelectedAgentsForSetup(options, detectedName);
+    const selectedAgents = await resolveSelectedAgentsForSetup(options, detectedName, installedAgents);
     console.log('\n→ Installing machine-level brainclaw prerequisites...');
     const written = runGlobalInstall(selectedAgents, env);
     if (written.length > 0) {
@@ -484,8 +533,10 @@ export async function runSetup(options = {}) {
     const detectedName = detectedAi?.name;
     const testMode = process.env.BRAINCLAW_TEST_MODE === '1';
     const detectedSurfaces = testMode ? [] : buildAiSurfaceInventory();
+    const agentInventory = testMode ? undefined : buildAgentInventory(resolveHomeDir(env) ?? os.homedir(), env);
+    const installedAgents = getInstalledAgentNames(agentInventory);
     logDetectedAgentSurfaces(detectedName, detectedSurfaces);
-    const selectedAgents = await resolveSelectedAgentsForSetup(options, detectedName);
+    const selectedAgents = await resolveSelectedAgentsForSetup(options, detectedName, installedAgents);
     // Step 5: Global install
     console.log('\n→ Installing global brainclaw prerequisites...');
     const written = runGlobalInstall(selectedAgents, env);

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/agent-capability.js

@@ -23,6 +23,7 @@ const AGENT_ALIASES = {
     'gemini': 'antigravity',
     'mistral': 'mistral-vibe',
     'vibe': 'mistral-vibe',
+    'hermes-agent': 'hermes',
 };
 /** Resolve an alias to its canonical agent name, or return the input unchanged. */
 export function resolveAgentAlias(name) {
@@ -227,6 +228,24 @@ const PROFILES = {
         invoke_review_template: 'vibe --prompt "{prompt}" --auto-approve --max-turns 5',
         invoke_consult_template: 'vibe --prompt "{prompt}" --auto-approve --max-turns 3',
     },
+    // Hermes Agent (Nous Research) — autonomous, skills-first agent with native
+    // MCP client support via ~/.hermes/config.yaml. Brainclaw uses Hermes as a
+    // Tier B surface for now: MCP + universal .agents/skills/ skill, no native
+    // Brainclaw hooks until a dedicated Hermes plugin is shipped and validated.
+    hermes: {
+        name: 'hermes', category: 'autonomous-agent', workflowModel: 'task-based',
+        hasMcp: true, hasHooks: false, hasAutoApprove: false, hasSkills: true, hasRules: false,
+        instructionFile: 'AGENTS.md', sharedInstructionFile: true, mcpConfigScope: 'machine', templateTier: 'B',
+        role_capabilities: ['execute', 'review', 'consult'],
+        runtime: { mcp_direct: true, hooks: false, canBeSpawnedCli: true, canSpawnOtherCli: false, inbox: false },
+        max_concurrent_tasks: 1,
+        prompt_delivery: { methods: ['inline_arg', 'temp_file'], preferred: 'inline_arg', max_inline_length: 8000 },
+        execution_env: { surface: 'cli' },
+        invoke_template: 'hermes chat -q "{prompt}"',
+        invoke_binary: 'hermes',
+        invoke_review_template: 'hermes chat -q "{prompt}"',
+        invoke_consult_template: 'hermes chat -q "{prompt}"',
+    },
     // --- Autonomous agents (headless, task-based or scheduled) ---
     openclaw: {
         name: 'openclaw', category: 'autonomous-agent', workflowModel: 'task-based',