brainclaw 1.5.5 → 1.7.0

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';
@@ -11,7 +12,7 @@ import { buildContext, renderContextMarkdown, renderContextPromptTemplate, rende
 import { buildCoordinationSnapshot } from '../core/coordination.js';
 import { checkBrainclawInstallableUpdate, getInstalledBrainclawVersion, readDiskBrainclawVersion, renderBrainclawInstallableUpdateNotice } from '../core/brainclaw-version.js';
 import { loadConfig } from '../core/config.js';
-import { loadState, persistState, saveState } from '../core/state.js';
+import { collectLoadValidationWarnings, findLoadValidationWarning, loadState, persistState, saveState } from '../core/state.js';
 import { generateIdWithLabel } from '../core/ids.js';
 import { memoryExists } from '../core/io.js';
 import { generateCandidateIdWithLabel, loadCandidate, saveCandidate } from '../core/candidates.js';
@@ -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';
@@ -48,6 +50,7 @@ import { WorkRequestSchema, CoordinateRequestSchema } from '../core/facade-schem
 import { getSpawnableAgents, getCapabilityProfile, buildInvokeCommand, validateAgentForDispatch } from '../core/agent-capability.js';
 import { attemptExecution } from '../core/execution.js';
 import { createAgentRun, transitionAgentRun } from '../core/agentruns.js';
+import { sweepDeadPidRunningAgentRunsAtRead } from '../core/agentrun-reconciler.js';
 import { createAssignment, generateAssignmentId, patchAssignmentMessageId, transitionAssignment, bumpActiveAssignmentHeartbeat, } from '../core/assignments.js';
 import { harvestCandidates } from './harvest.js';
 export const SCHEMA_VERSION = '1.0.0';
@@ -402,11 +405,25 @@ export const MCP_READ_TOOLS = [
             required: ['thread_id'],
         },
     },
+    {
+        name: 'bclaw_dispatch_status',
+        description: 'Consolidated dispatch status — given a `target_id` (asgn_/clm_/lop_/run_), resolves all linked entities (assignment, claim, loop, agent_run), reads the on-disk artefacts (brief-ack sentinel + per-assignment stdout/stderr log tails), checks OS pid liveness, and returns a single health verdict + a recommended next action. Replaces the five separate `bclaw_find` / `bclaw_get` calls a caller would otherwise make to verify a dispatch is actually doing useful work. Particularly useful right after `bclaw_coordinate` returns `execution_status="delivered_and_started"` — that response\'s `verify_with` hint points at this tool by name. See docs/concepts/dispatch-lifecycle.md for the full entity model and FSM details.',
+        annotations: { tier: 'facade', category: 'coordination', headlessApproval: 'auto' },
+        inputSchema: {
+            type: 'object',
+            properties: {
+                target_id: { type: 'string', description: 'Any one of: an assignment id (`asgn_…`), a claim id (`clm_…`), a loop id (`lop_…`), or an agent_run id (`run_…`). The tool resolves to the assignment scope internally and fetches the rest.' },
+                tail_log_lines: { type: 'number', description: 'How many trailing lines of each captured log file (stdout / stderr) to include in the response. Default 20. Pass 0 to omit tails and only return size_bytes.' },
+                stall_threshold_ms: { type: 'number', description: 'Age in ms past which a `running` agent_run with a live pid but no recent activity is considered `stalled`. Default 300000 (5 min).' },
+            },
+            required: ['target_id'],
+        },
+    },
 ];
 const MCP_WRITE_TOOLS = [
     {
         name: 'bclaw_dispatch',
-        description: 'Unified dispatch entry for sequence-lane parallelization. `intent` discriminator: analysis (sequence lane status, read-only), execute (default — analyze + generate briefs + send), review (routes an EXISTING reviewable handoff to a reviewer — NOT for opening new reviews; use bclaw_coordinate(intent=review, open_loop=true) for that). Consolidates bclaw_dispatch_analysis / bclaw_dispatch / bclaw_dispatch_review.',
+        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',
@@ -482,6 +499,21 @@ const MCP_WRITE_TOOLS = [
             },
         },
     },
+    {
+        name: 'bclaw_init_project',
+        description: "Initialize brainclaw at an arbitrary path AND register it as a cross_project_link in the caller's store. Lets an agent operating in workspace A bootstrap a brainclaw project in folder B in one MCP call.",
+        annotations: { tier: 'standard', category: 'session', headlessApproval: 'prompt' },
+        inputSchema: {
+            type: 'object',
+            properties: {
+                path: { type: 'string', description: 'Absolute or relative path of the target folder. Resolved via path.resolve(callerCwd, path).' },
+                force: { type: 'boolean', description: 'Pass --force to init (rebuild managed config). Default false.' },
+                project_mode: { type: 'string', description: 'Optional project mode (single-project, multi-project, auto).' },
+                link_as: { type: 'string', description: 'Optional name to register the cross_project_link under. Defaults to path basename.' },
+            },
+            required: ['path'],
+        },
+    },
     {
         name: 'bclaw_write_note',
         description: 'Add a runtime note. Requires contributor trust level or above. Use crossProject to push a runtime-note signal to a linked project (requires role: publisher in cross_project_links config).',
@@ -630,23 +662,33 @@ const MCP_WRITE_TOOLS = [
     },
     {
         name: 'bclaw_add_step',
-        description: 'Add a sub-step to a plan item. Requires contributor trust level or above.',
+        description: 'Add a sub-step to a plan item. Canonical shape is `{ planId, data: { text, title?, assignee? } }`; legacy top-level `{ text, assignee }` still works for backward compatibility. If both are present, data.* wins and a warning is emitted. Requires contributor trust level or above. Pass `project` to target a step in a plan that lives in a linked project (same pattern as the canonical-grammar tools).',
         annotations: { tier: 'standard', category: 'coordination', headlessApproval: 'auto' },
         inputSchema: {
             type: 'object',
             properties: {
                 planId: { type: 'string', description: 'Plan item ID.' },
-                text: { type: 'string', description: 'Step description.' },
+                data: {
+                    type: 'object',
+                    description: 'Canonical step payload: { text, title?, assignee? }. title is accepted as an alias for text.',
+                    properties: {
+                        text: { type: 'string', description: 'Step description.' },
+                        title: { type: 'string', description: 'Alias for text.' },
+                        assignee: { type: 'string', description: 'Optional assignee.' },
+                    },
+                },
+                text: { type: 'string', description: 'Legacy top-level step description; prefer data.text.' },
                 agent: { type: 'string', description: 'Agent name.' },
                 agentId: { type: 'string', description: 'Registered agent id.' },
-                assignee: { type: 'string', description: 'Optional assignee.' },
+                assignee: { type: 'string', description: 'Legacy top-level optional assignee; prefer data.assignee.' },
+                project: { type: 'string', description: 'Optional: name (or path/basename) of a linked project to add the step in. Defaults to the current project. Same resolution as canonical-grammar tools — accepts cross_project_links and workspace store-chain children.' },
             },
-            required: ['planId', 'text'],
+            required: ['planId'],
         },
     },
     {
         name: 'bclaw_complete_step',
-        description: 'Mark a plan sub-step as done. Requires contributor trust level or above.',
+        description: 'Mark a plan sub-step as done. Requires contributor trust level or above. Pass `project` to operate on a plan in a linked project.',
         annotations: { tier: 'standard', category: 'coordination', headlessApproval: 'auto' },
         inputSchema: {
             type: 'object',
@@ -655,13 +697,14 @@ const MCP_WRITE_TOOLS = [
                 stepId: { type: 'string', description: 'Step ID to complete.' },
                 agent: { type: 'string', description: 'Agent name.' },
                 agentId: { type: 'string', description: 'Registered agent id.' },
+                project: { type: 'string', description: 'Optional: name of a linked project to complete the step in. Defaults to the current project.' },
             },
             required: ['planId', 'stepId'],
         },
     },
     {
         name: 'bclaw_update_step',
-        description: 'Update a plan sub-step (status, text, assignee). Supports all step statuses: todo, in_progress, testing, done, blocked. Requires contributor trust level or above.',
+        description: 'Update a plan sub-step (status, text, assignee). Supports all step statuses: todo, in_progress, testing, done, blocked. Requires contributor trust level or above. Pass `project` to operate on a plan in a linked project.',
         annotations: { tier: 'standard', category: 'coordination', headlessApproval: 'auto' },
         inputSchema: {
             type: 'object',
@@ -673,13 +716,14 @@ const MCP_WRITE_TOOLS = [
                 assignee: { type: 'string', description: 'New assignee (empty string to unassign).' },
                 agent: { type: 'string', description: 'Agent name.' },
                 agentId: { type: 'string', description: 'Registered agent id.' },
+                project: { type: 'string', description: 'Optional: name of a linked project to update the step in. Defaults to the current project.' },
             },
             required: ['planId', 'stepId'],
         },
     },
     {
         name: 'bclaw_delete_step',
-        description: 'Remove a sub-step from a plan. Requires contributor trust level or above.',
+        description: 'Remove a sub-step from a plan. Requires contributor trust level or above. Pass `project` to operate on a plan in a linked project.',
         annotations: { tier: 'standard', category: 'coordination', headlessApproval: 'prompt' },
         inputSchema: {
             type: 'object',
@@ -688,6 +732,7 @@ const MCP_WRITE_TOOLS = [
                 stepId: { type: 'string', description: 'Step ID to delete.' },
                 agent: { type: 'string', description: 'Agent name.' },
                 agentId: { type: 'string', description: 'Registered agent id.' },
+                project: { type: 'string', description: 'Optional: name of a linked project to delete the step from. Defaults to the current project.' },
             },
             required: ['planId', 'stepId'],
         },
@@ -877,6 +922,7 @@ const MCP_WRITE_TOOLS = [
                 task: { type: 'string', description: 'Optional task description (used as claim description when creating a claim).' },
                 messageId: { type: 'string', description: 'Optional message/thread ID for traceability.' },
                 contextTarget: { type: 'string', description: 'Optional path passed to bclaw_get_context to filter memory.' },
+                project: { type: 'string', description: 'Optional linked project name/path. Routes session, context, claims, audit, and bootstrap probe to that project. Defaults to the current cwd.' },
                 agent: { type: 'string', description: 'Agent name.' },
                 agentId: { type: 'string', description: 'Registered agent id.' },
                 compact: { type: 'boolean', description: 'Return a compact payload (default true). Set to false to include the full context result. Compact mode avoids exceeding MCP token limits on projects with large memory.', default: true },
@@ -886,13 +932,13 @@ const MCP_WRITE_TOOLS = [
     },
     {
         name: 'bclaw_coordinate',
-        description: 'Multi-agent coordination facade: assign tasks to agents (with claims), consult agents (no claim), create a review candidate, open an ideation loop, reroute an active claim to another agent, or summarize a thread. Returns a FacadeResponse with selected_targets, delivery_plan, artifacts, and side_effects.',
+        description: 'Multi-agent coordination facade: assign tasks to agents (with claims), consult agents (no claim), create a review candidate, open an ideation loop, reroute an active claim to another agent, or summarize a thread. Returns a FacadeResponse with selected_targets, delivery_plan, artifacts, side_effects, and execution_status. IMPORTANT — execution_status semantics: `delivered_and_started` means the spawn wrapper touched the brief-ack sentinel (`.brainclaw/coordination/runtime/ack/<assignment_id>.ack`) — NOT that the worker is doing useful work. Spawned workers may still die silently before consuming the brief (cf. trap trp_38f63ea4). To verify a dispatch is actually alive, query `bclaw_find(entity="agent_run", filter={assignment_id})` then check `status==="running"` AND OS-level pid liveness (Windows: `Get-Process -Id <pid>` ; POSIX: `kill -0 <pid>`) AND `last_event_at` within the last few minutes. See docs/concepts/troubleshooting.md §"Inbox messages stuck / brief-ack never arrived" for the diagnostic playbook, and docs/integrations/<agent>.md for per-agent spawn semantics (notably codex.md re sandbox MCP availability).',
         annotations: { tier: 'facade', category: 'coordination', headlessApproval: 'auto' },
         inputSchema: {
             type: 'object',
             properties: {
                 intent: { type: 'string', enum: ['assign', 'consult', 'review', 'reroute', 'summarize', 'ideate'], description: 'Coordination intent. "assign" creates a claim per target agent and dispatches the brief. "consult" dispatches without creating claims. "review" creates a review candidate. "ideate" opens an ideation loop with the task as the proposal seed (driver wire-up: pln#492 phase 2.d). "reroute" releases the current claim and reassigns. "summarize" reads a thread and returns a summary.' },
-                task: { type: 'string', description: 'Brief or task description delivered to target agents.' },
+                task: { type: 'string', description: 'Brief or task description delivered to target agents. WARNING: the brief is delivered to a worker that may be sandboxed and not have brainclaw MCP wired in its session — notably codex spawned with `--sandbox workspace-write`. Briefs that instruct MCP-call protocols (e.g. require the worker to call `bclaw_send_message`, `bclaw_assignment_update`, `bclaw_complete_step`) will hang the worker silently. Prefer file-based protocols (write findings/reply to a markdown file in the worktree + commit fixes directly on the branch) for these agents. The coordinator then harvests the file and lifecycle-closes the assignment itself. See docs/integrations/<agent>.md for per-agent capability matrix.' },
                 scope: { type: 'string', description: 'File or feature scope. Used as claim scope for assign/reroute; as thread id for summarize if threadId is absent.' },
                 targetAgents: { type: 'array', items: { type: 'string' }, description: 'Agent names to target. If omitted, all spawnable agents are used.' },
                 constraints: { type: 'object', description: 'Optional structured constraints passed alongside the brief (e.g. deadline, reviewCriteria).' },
@@ -903,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'],
         },
@@ -924,7 +972,7 @@ const MCP_WRITE_TOOLS = [
                 intent: {
                     type: 'string',
                     enum: ['open', 'get', 'list', 'turn', 'complete_turn', 'advance', 'add_artifact', 'pause', 'resume', 'close'],
-                    description: 'Loop lifecycle intent. See docs/concepts/loop-engine.md for semantics.',
+                    description: 'Loop lifecycle intent. See docs/concepts/loop-engine.md for semantics. ANTI-PATTERN: do NOT call `intent="open"` directly to start a review or ideation loop — it creates the loop structure WITHOUT dispatching the first turn, so the reviewer/participant never receives the work. Use `bclaw_coordinate(intent="review", open_loop=true, targetAgents=[…])` (or `intent="ideate"`) instead — that opens the loop AND dispatches the first turn in one call. `bclaw_loop` is for driving turns inside a loop that was already opened via the coordinate facade (intents: turn, complete_turn, advance, close, etc.).',
                 },
                 loop_id: { type: 'string', description: 'Target loop id (lop_…). Required for every intent except open and list.' },
                 kind: { type: 'string', enum: ['review', 'ideation', 'implementation', 'research', 'debug'], description: 'Loop kind for open / list filter.' },
@@ -935,7 +983,7 @@ const MCP_WRITE_TOOLS = [
                 linked: { type: 'object', description: 'Optional top-level plan/sequence refs (open).' },
                 stop_condition: { type: 'object', description: 'Optional stop_condition override (open). Composite any/all supported.' },
                 mode: { type: 'string', enum: ['asymmetric', 'symmetric'], description: 'Review mode selector for open (review kind only).' },
-                status: { type: 'string', description: 'Filter value for list, or target final_status for close.' },
+                status: { type: 'string', description: 'For intent="list": filter value (any loop status). For intent="close": target final status — accepted values are `completed` | `cancelled` | `blocked` only (NOT `failed`; map crashed/dead loops to `cancelled` with a `reason`).' },
                 include_events: { type: 'boolean', description: 'get: include the event journal in the response.' },
                 limit: { type: 'number', description: 'list: max loops returned.' },
                 offset: { type: 'number', description: 'list: pagination offset.' },
@@ -952,6 +1000,7 @@ const MCP_WRITE_TOOLS = [
                 reason: { type: 'string', description: 'advance / pause / close: optional reason string.' },
                 expected_version: { type: 'number', description: 'Accepted for RFC compatibility on mutating intents, but not enforced until lock/CAS wiring lands.' },
                 client_request_id: { type: 'string', description: 'Accepted for RFC compatibility on mutating intents, but not enforced until lock/idempotency wiring lands.' },
+                project: { type: 'string', description: 'Optional linked project name/path. Routes loop reads and mutations to that project. Defaults to the current cwd.' },
                 agent: { type: 'string', description: 'Caller agent name.' },
                 agentId: { type: 'string', description: 'Caller registered agent id (enforced for slot-bound auth in complete_turn).' },
             },
@@ -1038,13 +1087,13 @@ const MCP_WRITE_TOOLS = [
     // Promoted to `standard` tier at the v1.0 cut.
     {
         name: 'bclaw_find',
-        description: 'Canonical list query over a brainclaw entity. Default read filter excludes records with provenance.kind="legacy" and auto_reflect records below 0.6 confidence — override via filter.includeLegacy / filter.minAutoReflectConfidence. Pass `project` to query a linked project instead of the current one.',
+        description: 'Canonical list query over a brainclaw entity. Default read filter excludes records with provenance.kind="legacy" and auto_reflect records below 0.6 confidence — override via filter.includeLegacy / filter.minAutoReflectConfidence. Tag filters accept `tag: string` for one tag or `tags: string[]` for any-match. For entity="agent_run", filters also accept assignment_id, claim_id, and message_id. Pass `project` to query a linked project instead of the current one.',
         annotations: { tier: 'standard', category: 'memory', headlessApproval: 'auto' },
         inputSchema: {
             type: 'object',
             properties: {
                 entity: { type: 'string', description: 'Entity name: plan | decision | constraint | trap | handoff | runtime_note | candidate | claim | action | assignment | agent_run | cross_project_link. Others not yet wired.' },
-                filter: { type: 'object', description: 'Filter keys: status, tag, author, plan_id, limit, offset, includeLegacy (bool, default false), minAutoReflectConfidence (0-1, default 0.6).' },
+                filter: { type: 'object', description: 'Filter keys: status, tag (single tag), tags (array, any-match), author, plan_id, source, auto_generated, limit, offset, includeLegacy (bool, default false), minAutoReflectConfidence (0-1, default 0.6). entity=agent_run also accepts assignment_id, claim_id, message_id.' },
                 project: { type: 'string', description: 'Optional: name (or path/basename) of a linked project to query. Defaults to the current project. Only cross_project_links (config.yaml) and workspace store-chain children are accepted — list with `brainclaw link list`.' },
             },
             required: ['entity'],
@@ -1215,6 +1264,7 @@ export const FACADE_ORDER = [
     'bclaw_context',
     'bclaw_coordinate',
     'bclaw_dispatch',
+    'bclaw_dispatch_status',
     'bclaw_loop',
     'bclaw_setup',
 ];
@@ -2345,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) {
@@ -2356,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)
@@ -2377,6 +2434,102 @@ async function _executeMcpToolCallInner(payload) {
             }
             return { response: toolResponse({ content: [{ type: 'text', text: `Unknown step: "${step}". Valid steps: project_roots, repo_selection, agent_selection.` }], structuredContent: { error: 'unknown_step', step } }, true) };
         }
+        if (name === 'bclaw_init_project') {
+            const rawPath = typeof args.path === 'string' ? args.path.trim() : '';
+            if (!rawPath) {
+                return { response: createToolErrorResponse('validation_error', 'path is required') };
+            }
+            const force = args.force === true;
+            const projectModeArg = typeof args.project_mode === 'string' ? args.project_mode : undefined;
+            const linkAs = typeof args.link_as === 'string' && args.link_as.trim().length > 0
+                ? args.link_as.trim()
+                : undefined;
+            const resolvedPath = path.isAbsolute(rawPath) ? rawPath : path.resolve(cwd, rawPath);
+            let wasAlreadyInitialized = false;
+            if (memoryExists(resolvedPath) && !force) {
+                wasAlreadyInitialized = true;
+            }
+            else {
+                if (!fs.existsSync(resolvedPath)) {
+                    try {
+                        fs.mkdirSync(resolvedPath, { recursive: true });
+                    }
+                    catch (err) {
+                        return {
+                            response: createToolErrorResponse('init_project_failed', `Failed to create target directory '${resolvedPath}': ${err instanceof Error ? err.message : String(err)}`),
+                        };
+                    }
+                }
+                try {
+                    const { runInit } = await import('./init.js');
+                    await runInit({
+                        yes: true,
+                        cwd: resolvedPath,
+                        force,
+                        ...(projectModeArg ? { projectMode: projectModeArg } : {}),
+                    });
+                }
+                catch (err) {
+                    return {
+                        response: createToolErrorResponse('init_project_failed', `runInit failed for '${resolvedPath}': ${err instanceof Error ? err.message : String(err)}`),
+                    };
+                }
+            }
+            let projectName;
+            try {
+                projectName = loadConfig(resolvedPath).project_name;
+            }
+            catch {
+                projectName = path.basename(resolvedPath);
+            }
+            let linkName;
+            try {
+                const { addCrossProjectLink } = await import('../core/cross-project.js');
+                const link = addCrossProjectLink({
+                    path: resolvedPath,
+                    name: linkAs ?? projectName,
+                    cwd,
+                    force,
+                });
+                linkName = link.name ?? path.basename(resolvedPath);
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                // Treat a duplicate link as idempotent success when the caller did
+                // not request --force; the project itself is initialised correctly
+                // and the existing link already points at it.
+                if (/already exists/i.test(message) && !force) {
+                    try {
+                        const { resolveCrossProjectLinks } = await import('../core/cross-project.js');
+                        const existing = resolveCrossProjectLinks(cwd).find((l) => l.absolutePath === resolvedPath || l.path === rawPath);
+                        linkName = existing?.name ?? linkAs ?? projectName;
+                    }
+                    catch {
+                        linkName = linkAs ?? projectName;
+                    }
+                }
+                else {
+                    return {
+                        response: createToolErrorResponse('init_project_failed', `Failed to register cross_project_link: ${message}`),
+                    };
+                }
+            }
+            const summary = wasAlreadyInitialized
+                ? `✔ ${resolvedPath} already initialised; linked as '${linkName}'.`
+                : `✔ Initialised brainclaw at ${resolvedPath} and linked as '${linkName}'.`;
+            return {
+                response: toolResponse({
+                    content: [{ type: 'text', text: summary }],
+                    structuredContent: {
+                        status: 'ok',
+                        project_name: projectName,
+                        path: resolvedPath,
+                        link_id: linkName,
+                        was_already_initialized: wasAlreadyInitialized,
+                    },
+                }),
+            };
+        }
         if (name === 'bclaw_write_note') {
             const resolved = ensureTrust(args, { nameField: 'agent', idField: 'agentId' }, 'contributor', cwd, connectionSessionId);
             if (resolved.error) {
@@ -2887,7 +3040,7 @@ async function _executeMcpToolCallInner(payload) {
             if (resolved.error && resolved.error.kind !== 'identity_error') {
                 return { response: createToolErrorResponse(resolved.error.kind, resolved.error.message, resolved.error.details) };
             }
-            const result = startSession({
+            const result = await startSession({
                 agent: resolved.identity?.agent_name ?? (typeof args.agent === 'string' ? args.agent : undefined),
                 agentId: resolved.identity?.agent_id ?? (typeof args.agentId === 'string' ? args.agentId : undefined),
                 context: args.context,
@@ -3030,7 +3183,7 @@ async function _executeMcpToolCallInner(payload) {
             if (resolved.error) {
                 return { response: createToolErrorResponse(resolved.error.kind, resolved.error.message, resolved.error.details) };
             }
-            const result = endSession({
+            const result = await endSession({
                 session: args.session,
                 agent: resolved.identity?.agent_name,
                 agentId: resolved.identity?.agent_id,
@@ -3575,13 +3728,22 @@ async function _executeMcpToolCallInner(payload) {
                 return { response: createToolErrorResponse(resolved.error.kind, resolved.error.message, resolved.error.details) };
             }
             const stepPlanId = String(args.planId ?? '').trim();
-            const stepText = String(args.text ?? '').trim();
+            const stepData = args.data && typeof args.data === 'object' && !Array.isArray(args.data)
+                ? args.data
+                : {};
+            if ((args.text !== undefined || args.assignee !== undefined) && Object.keys(stepData).length > 0) {
+                console.warn('[brainclaw:warn] bclaw_add_step received legacy top-level fields alongside data.*; using data.* values');
+            }
+            const stepTextRaw = stepData.text ?? stepData.title ?? args.text;
+            const stepText = typeof stepTextRaw === 'string' ? stepTextRaw.trim() : '';
+            const stepAssignee = (stepData.assignee ?? args.assignee);
             if (!stepPlanId)
                 return { response: createToolErrorResponse('validation_error', 'Missing required argument: planId') };
             if (!stepText)
-                return { response: createToolErrorResponse('validation_error', 'Missing required argument: text') };
+                return { response: createToolErrorResponse('validation_error', 'Missing required argument: data.text') };
+            const stepTargetCwd = resolveProjectCwd(args.project, cwd);
             try {
-                const result = addStepOp({ planId: stepPlanId, text: stepText, assignee: args.assignee }, cwd);
+                const result = addStepOp({ planId: stepPlanId, text: stepText, assignee: stepAssignee }, stepTargetCwd);
                 return {
                     response: toolResponse({
                         content: [{ type: 'text', text: `✔ Step added: [${result.stepId}] ${stepText} (${result.doneSteps}/${result.totalSteps} done)` }],
@@ -3614,8 +3776,9 @@ async function _executeMcpToolCallInner(payload) {
                 return { response: createToolErrorResponse('validation_error', 'Missing required argument: planId') };
             if (!csStepId)
                 return { response: createToolErrorResponse('validation_error', 'Missing required argument: stepId') };
+            const csTargetCwd = resolveProjectCwd(args.project, cwd);
             try {
-                const result = completeStepOp({ planId: csPlanId, stepId: csStepId }, cwd);
+                const result = completeStepOp({ planId: csPlanId, stepId: csStepId }, csTargetCwd);
                 return {
                     response: toolResponse({
                         content: [{ type: 'text', text: `✔ Step completed: [${result.stepId}] (${result.doneSteps}/${result.totalSteps} done)` }],
@@ -3653,6 +3816,7 @@ async function _executeMcpToolCallInner(payload) {
             if (args.status && !validStatuses.includes(String(args.status))) {
                 return { response: createToolErrorResponse('validation_error', `Invalid status: ${args.status}. Valid: ${validStatuses.join(', ')}`) };
             }
+            const usTargetCwd = resolveProjectCwd(args.project, cwd);
             try {
                 const result = updateStepOp({
                     planId: usPlanId,
@@ -3660,7 +3824,7 @@ async function _executeMcpToolCallInner(payload) {
                     status: args.status,
                     text: args.text,
                     assignee: args.assignee,
-                }, cwd);
+                }, usTargetCwd);
                 const changes = [];
                 if (args.status)
                     changes.push(`status=${args.status}`);
@@ -3701,8 +3865,9 @@ async function _executeMcpToolCallInner(payload) {
                 return { response: createToolErrorResponse('validation_error', 'Missing required argument: planId') };
             if (!dsStepId)
                 return { response: createToolErrorResponse('validation_error', 'Missing required argument: stepId') };
+            const dsTargetCwd = resolveProjectCwd(args.project, cwd);
             try {
-                const result = deleteStepOp({ planId: dsPlanId, stepId: dsStepId }, cwd);
+                const result = deleteStepOp({ planId: dsPlanId, stepId: dsStepId }, dsTargetCwd);
                 return {
                     response: toolResponse({
                         content: [{ type: 'text', text: `✔ Step deleted: [${result.stepId}] (${result.doneSteps}/${result.totalSteps} remaining)` }],
@@ -4075,16 +4240,17 @@ async function _executeMcpToolCallInner(payload) {
                 return { response: createToolErrorResponse('validation_error', parseResult.error.message) };
             }
             const workReq = parseResult.data;
+            const targetCwd = resolveProjectCwd(workReq.project, cwd);
             const useCompact = workReq.compact !== false; // default true
             const warnings = [];
             // Step 1: implicit session start (handles auto-registration internally)
             let sessionResult;
             try {
-                sessionResult = startSession({
+                sessionResult = await startSession({
                     agent: typeof args.agent === 'string' ? args.agent : undefined,
                     agentId: typeof args.agentId === 'string' ? args.agentId : undefined,
                     context: workReq.contextTarget,
-                    cwd,
+                    cwd: targetCwd,
                 });
             }
             catch (sessionErr) {
@@ -4102,14 +4268,14 @@ async function _executeMcpToolCallInner(payload) {
             try {
                 let sinceSession;
                 if (workReq.intent === 'resume') {
-                    const previousSession = loadAllSessions(cwd)
+                    const previousSession = loadAllSessions(targetCwd)
                         .find((s) => s.agent === sessionResult.agent && s.session_id !== sessionResult.session_id);
                     sinceSession = previousSession?.session_id;
                 }
                 contextResult = buildContext({
                     target: workReq.contextTarget ?? workReq.scope,
                     agent: sessionResult.agent,
-                    cwd,
+                    cwd: targetCwd,
                     sinceSession,
                 });
             }
@@ -4118,7 +4284,7 @@ async function _executeMcpToolCallInner(payload) {
             let claimId;
             let claimStatus = 'none';
             if (workReq.intent === 'execute' && workReq.scope) {
-                const existingClaims = listClaims(cwd).filter((c) => c.status === 'active' && c.agent === sessionResult.agent && c.scope === workReq.scope);
+                const existingClaims = listClaims(targetCwd).filter((c) => c.status === 'active' && c.agent === sessionResult.agent && c.scope === workReq.scope);
                 if (existingClaims.length > 0) {
                     claimId = existingClaims[0].id;
                     claimStatus = 'existing';
@@ -4139,11 +4305,11 @@ async function _executeMcpToolCallInner(payload) {
                         status: 'active',
                         plan_id: workReq.planId,
                         model: currentModel,
-                    }, cwd);
-                    appendAuditEntry({ actor: sessionResult.agent, actor_id: sessionResult.agent_id, action: 'claim', item_id: claimId, item_type: 'claim', scope: workReq.scope, session_id: sessionResult.session_id }, cwd);
+                    }, targetCwd);
+                    appendAuditEntry({ actor: sessionResult.agent, actor_id: sessionResult.agent_id, action: 'claim', item_id: claimId, item_type: 'claim', scope: workReq.scope, session_id: sessionResult.session_id }, targetCwd);
                     claimStatus = 'created';
                     // Policy check post-claim
-                    const policyResult = checkPolicy({ scope: workReq.scope, agent: sessionResult.agent, agentId: sessionResult.agent_id, cwd });
+                    const policyResult = checkPolicy({ scope: workReq.scope, agent: sessionResult.agent, agentId: sessionResult.agent_id, cwd: targetCwd });
                     for (const w of policyResult.warnings.filter((pw) => pw.kind !== 'no_claim')) {
                         const idLabel = w.id ? ` (${w.id})` : '';
                         warnings.push(`[${w.kind}]${idLabel} ${w.message}`);
@@ -4185,6 +4351,34 @@ async function _executeMcpToolCallInner(payload) {
                     _full_context_hint: 'Use bclaw_context(kind="memory") for the full payload.',
                 };
             }
+            // pln#513 step 1 — bootstrap hint. When the project lacks a usable
+            // PROJECT.md (absent or 0 bytes), surface a hint so the agent knows
+            // the canonical entry-point. Cheap probe — one fs.statSync, no
+            // gating flag. The literal next_action mirrors the documented
+            // canonical-grammar call so callers can suggest it verbatim.
+            let bootstrapRecommended;
+            let nextAction;
+            try {
+                const fsMod = await import('node:fs');
+                const pathMod = await import('node:path');
+                const projectMdPath = pathMod.join(targetCwd, 'PROJECT.md');
+                let needsBootstrap = false;
+                try {
+                    const stat = fsMod.statSync(projectMdPath);
+                    if (!stat.isFile() || stat.size === 0)
+                        needsBootstrap = true;
+                }
+                catch {
+                    needsBootstrap = true; // ENOENT → absent
+                }
+                bootstrapRecommended = needsBootstrap;
+                if (needsBootstrap) {
+                    nextAction = "bclaw_coordinate(intent='ideate', preset='bootstrap')";
+                }
+            }
+            catch {
+                // Best-effort: never block bclaw_work on the probe.
+            }
             const facadeResponse = {
                 status: 'ok',
                 intent: workReq.intent,
@@ -4195,12 +4389,17 @@ async function _executeMcpToolCallInner(payload) {
                 session_id: sessionResult.session_id,
                 warnings,
                 duration_ms: Date.now() - startMs,
+                bootstrap_recommended: bootstrapRecommended,
+                next_action: nextAction,
             };
             const summaryParts = [`✔ bclaw_work [${workReq.intent}] session=${sessionResult.session_id}`];
             if (claimId)
                 summaryParts.push(`claim=${claimId} (${claimStatus})`);
             if (useCompact)
                 summaryParts.push('mode=compact (use bclaw_context for full payload)');
+            if (bootstrapRecommended) {
+                summaryParts.push(`💡 PROJECT.md missing — call ${nextAction} to open a bootstrap loop`);
+            }
             if (warnings.length > 0)
                 summaryParts.push(warnings.map((w) => `⚠ ${w}`).join('\n'));
             return {
@@ -4218,15 +4417,69 @@ async function _executeMcpToolCallInner(payload) {
                 return { response: createToolErrorResponse('validation_error', parseResult.error.message) };
             }
             const req = parseResult.data;
+            // pln#511 step 2 — preset selector validation. Presets are kind-
+            // specific in v1: only intent='ideate' carries them. Unknown names
+            // are rejected up-front against the registry so the handler never
+            // silently falls back to the kind-default. The bootstrap preset
+            // also enforces a dispatch constraint (can_753a083a): the champion
+            // must be a human-connected agent, never a sandboxed worker —
+            // checked below once the senderAgent is resolved.
+            if (req.preset !== undefined) {
+                if (req.intent !== 'ideate') {
+                    return {
+                        response: createToolErrorResponse('preset_kind_mismatch', `preset='${req.preset}' is only valid for intent='ideate' in v1; got intent='${req.intent}'. Loop presets are kind-specific — open the loop without a preset, or call with intent='ideate'.`),
+                    };
+                }
+                const { PRESETS: PRESETS_REGISTRY } = await import('../core/loops/presets/index.js');
+                if (!(req.preset in PRESETS_REGISTRY)) {
+                    const validNames = Object.keys(PRESETS_REGISTRY).join(', ') || '(none)';
+                    return {
+                        response: createToolErrorResponse('unknown_preset', `Unknown preset '${req.preset}'. Valid preset names: ${validNames}.`),
+                    };
+                }
+            }
+            // 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 = [];
+            // can_5e62334e — codex sandboxed dispatches cannot commit in worktrees
+            // because `.git` is a file pointer to the parent repo's
+            // .git/worktrees/<wt>/ directory, which lives OUTSIDE the worktree's
+            // writable root that `--sandbox workspace-write` permits. Any
+            // codex worker that runs `git commit` will fail with `index.lock:
+            // Permission denied`. Warn callers up-front so briefs don't request
+            // per-bug commits; the coordinator must harvest the worktree
+            // diff via `git diff` and commit from a non-sandboxed cwd.
+            if (Array.isArray(req.targetAgents) && req.targetAgents.includes('codex')) {
+                warnings.push('codex --sandbox workspace-write cannot commit to git in worktrees (.git is outside writable root). Briefs MUST NOT request per-bug commits; codex will produce uncommitted edits, then the coordinator must harvest via `git diff HEAD` from the worktree path and commit from the main repo. See can_5e62334e for context.');
+            }
             const senderAgent = typeof args.agent === 'string' && args.agent.trim()
                 ? args.agent.trim()
                 : 'bclaw_coordinate';
             const senderAgentId = typeof args.agentId === 'string' && args.agentId.trim()
                 ? args.agentId.trim()
                 : undefined;
+            // pln#511 step 2 — bootstrap preset dispatch constraint (can_753a083a).
+            // The bootstrap loop's champion must be a human-connected agent: it
+            // asks the operator clarifying questions and writes PROJECT.md. A
+            // sandboxed worker (codex / github-copilot) cannot reach the human,
+            // so the loop would stall in `clarify`. Enforce by requiring
+            // targetAgents to be empty (= single-agent / self-champion mode)
+            // or to contain only the caller. Other presets are unrestricted.
+            if (req.preset === 'bootstrap') {
+                const targets = req.targetAgents ?? [];
+                const onlyCaller = targets.length === 0
+                    || (targets.length === 1 && targets[0] === senderAgent);
+                if (!onlyCaller) {
+                    return {
+                        response: createToolErrorResponse('bootstrap_preset_not_dispatchable', `preset='bootstrap' cannot dispatch to other agents (can_753a083a): the champion must be a human-connected agent. Got targetAgents=${JSON.stringify(targets)}; pass an empty array or [${JSON.stringify(senderAgent)}].`),
+                    };
+                }
+            }
             const commandHints = [];
             const preparedInvokes = [];
             // pln#359 phase 1b — cross-project routing. When `project` is set, all
@@ -4243,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';
@@ -4495,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) {
@@ -4735,6 +5029,7 @@ async function _executeMcpToolCallInner(payload) {
                                     dispatcherAgent: senderAgent,
                                     sessionId: connectionSessionId,
                                     cwd: dispatchCwd,
+                                    worktreeBaseRef: req.ref,
                                 });
                                 if (claimResult.worktreeWarning)
                                     out.warnings.push(claimResult.worktreeWarning);
@@ -4923,6 +5218,7 @@ async function _executeMcpToolCallInner(payload) {
                             dispatcherAgent: senderAgent,
                             sessionId: connectionSessionId,
                             cwd: dispatchCwd,
+                            worktreeBaseRef: req.ref,
                         });
                         newClaimId = rerouteClaimResult.claimId;
                         if (rerouteClaimResult.worktreeWarning) {
@@ -5043,186 +5339,318 @@ async function _executeMcpToolCallInner(payload) {
                     : messages.map((m, i) => `[${i + 1}] ${m.from} → ${m.to}: ${m.text}`).join('\n');
                 result = { thread_id: threadId, message_count: messages.length, summary };
             }
-            else if (req.intent === 'ideate') {
-                // pln#492 phase 2.c (open + proposal) + 2.d.2 (multi-agent dispatch).
-                // Single-agent mode (no targetAgents): open the loop with the task
-                // as a proposal seed and stop there — the champion drives manually
-                // via bclaw_loop intent='turn' / 'advance'. Multi-agent mode
-                // (targetAgents passed): also advance to critique and dispatch a
-                // turn to each critic slot with a context-filtered, BM25-ranked,
-                // size-capped brief assembled by buildIdeationBrief.
-                const loopsModuleRef = await import('../core/loops/index.js');
-                const { openLoop, add_artifact, advance, turn, getLoop, buildIdeationBrief } = loopsModuleRef;
-                const senderIdentity = ((senderAgentId ? findAgentIdentityById(senderAgentId, dispatchCwd) : undefined)
-                    ?? findAgentIdentityByName(senderAgent, dispatchCwd)
-                    ?? ensureAgentRegisteredForDispatch(senderAgent, dispatchCwd));
-                const authorAgentId = senderIdentity?.agent_id ?? senderAgentId;
-                const creatorActor = authorAgentId ?? senderAgent;
-                const explicitTargets = req.targetAgents && req.targetAgents.length > 0;
-                const slots = [
-                    {
-                        role: 'champion',
-                        agent: senderAgent,
-                        ...(authorAgentId ? { agent_id: authorAgentId } : {}),
-                    },
-                ];
-                if (explicitTargets) {
-                    for (const agent of req.targetAgents) {
-                        const criticIdentity = findAgentIdentityByName(agent, dispatchCwd) ?? ensureAgentRegisteredForDispatch(agent, dispatchCwd);
-                        slots.push({
-                            role: 'critic',
-                            agent,
-                            ...(criticIdentity?.agent_id ? { agent_id: criticIdentity.agent_id } : {}),
-                        });
+            else if (req.intent === 'ideate')
+                ideate: {
+                    // pln#492 phase 2.c (open + proposal) + 2.d.2 (multi-agent dispatch).
+                    // Single-agent mode (no targetAgents): open the loop with the task
+                    // as a proposal seed and stop there — the champion drives manually
+                    // via bclaw_loop intent='turn' / 'advance'. Multi-agent mode
+                    // (targetAgents passed): also advance to critique and dispatch a
+                    // turn to each critic slot with a context-filtered, BM25-ranked,
+                    // size-capped brief assembled by buildIdeationBrief.
+                    //
+                    // pln#511 step 2 — when `req.preset` is set, the loop opens with
+                    // the preset's phases / stop_condition / protocol instead of the
+                    // kind-default ideation chain. Bootstrap preset enforces single-
+                    // agent / self-champion mode (validated above), so the multi-
+                    // agent dispatch branch never runs for it.
+                    //
+                    // pln#513 step 2 — labelled block (ideate:) so the bootstrap
+                    // join-or-lock path can break out early after assigning result.
+                    const loopsModuleRef = await import('../core/loops/index.js');
+                    const { openLoop, add_artifact, advance, turn, getLoop, buildIdeationBrief } = loopsModuleRef;
+                    const presetSelected = req.preset
+                        ? (await import('../core/loops/presets/index.js')).PRESETS[req.preset]
+                        : undefined;
+                    // pln#513 step 2 — bootstrap join-or-lock. The bootstrap preset is
+                    // project-singleton: two concurrent callers must converge on the same
+                    // loop rather than open duplicates. Strategy:
+                    //   1. Find existing bootstrap loop in {open, paused} → join.
+                    //   2. Else check for an active coordination claim (someone is
+                    //      mid-open). Re-find once; surface bootstrap_coordination_in_progress
+                    //      if still nothing.
+                    //   3. Else acquire the lock, fall through to the normal open path,
+                    //      release the lock on the way out (success or fail).
+                    // The lock is opportunistic, not blocking — a fast retry-in-place
+                    // not a wait-on-mutex. Keeps the verb short and predictable.
+                    // pln#518 step 1 — bootstrap join-or-lock now delegates to the shared
+                    // acquireBootstrapLoop helper (src/core/loops/bootstrap-acquire.ts).
+                    // Both the CLI and this MCP handler converge on the same singleton
+                    // acquire path, eliminating the race where two concurrent callers both
+                    // passed the local scan and called openLoop directly.
+                    const senderIdentity = ((senderAgentId ? findAgentIdentityById(senderAgentId, dispatchCwd) : undefined)
+                        ?? findAgentIdentityByName(senderAgent, dispatchCwd)
+                        ?? ensureAgentRegisteredForDispatch(senderAgent, dispatchCwd));
+                    const authorAgentId = senderIdentity?.agent_id ?? senderAgentId;
+                    const creatorActor = authorAgentId ?? senderAgent;
+                    let bootstrapOpenedLoop;
+                    if (req.preset === 'bootstrap') {
+                        const { acquireBootstrapLoop, BootstrapCoordinationInProgressError: BcipError } = await import('../core/loops/bootstrap-acquire.js');
+                        let acqResult;
+                        try {
+                            acqResult = acquireBootstrapLoop({
+                                actor: senderAgent,
+                                agent_id: authorAgentId,
+                                created_by: creatorActor,
+                                title: req.task.slice(0, 120),
+                                goal: req.scope,
+                                model: currentModel,
+                            }, dispatchCwd);
+                        }
+                        catch (err) {
+                            if (err instanceof BcipError) {
+                                return {
+                                    response: createToolErrorResponse('bootstrap_coordination_in_progress', err.message),
+                                };
+                            }
+                            throw err;
+                        }
+                        warnings.push(...acqResult.warnings);
+                        if (acqResult.action === 'joined') {
+                            const jLoop = acqResult.loop;
+                            artifacts.push({ type: 'loop', id: jLoop.id });
+                            result = {
+                                loop_id: jLoop.id,
+                                joined_existing: true,
+                                current_phase: jLoop.current_phase,
+                                status: jLoop.status,
+                                mode: 'single_agent',
+                                preset: req.preset,
+                            };
+                            // Skip the rest of the ideate flow — we joined an existing loop.
+                            break ideate;
+                        }
+                        // action === 'opened': helper already called openLoop + released lock.
+                        bootstrapOpenedLoop = acqResult.loop;
                     }
-                }
-                let loopId;
-                let proposalArtifactId;
-                try {
-                    const loop = openLoop({
-                        kind: 'ideation',
-                        title: req.task.slice(0, 120),
-                        goal: req.scope,
-                        created_by: creatorActor,
-                        slots,
-                    }, dispatchCwd);
-                    loopId = loop.id;
-                    artifacts.push({ type: 'loop', id: loop.id });
-                    side_effects.push({ action: 'create', entity: 'loop', id: loop.id });
-                    const proposalBody = req.task.slice(0, 4000);
-                    const updated = add_artifact({
-                        id: loop.id,
-                        actor: creatorActor,
-                        artifact: {
-                            phase: 'proposal',
-                            type: 'proposal',
-                            body: proposalBody,
-                            produced_by: creatorActor,
+                    // pln#511 step 2 — bootstrap preset always runs in single-agent
+                    // mode: the champion drives the whole loop. Even when the caller
+                    // passes targetAgents=[caller] (validated as the only legal non-
+                    // empty form), we don't add critic slots and we don't take the
+                    // multi-agent dispatch branch. Treating that idiom as "single
+                    // agent / self-champion" matches what the constraint check
+                    // already enforced upstream.
+                    const explicitTargets = Boolean(req.targetAgents
+                        && req.targetAgents.length > 0
+                        && req.preset !== 'bootstrap');
+                    const slots = [
+                        {
+                            role: 'champion',
+                            agent: senderAgent,
+                            ...(authorAgentId ? { agent_id: authorAgentId } : {}),
                         },
-                    }, dispatchCwd);
-                    const lastArtifact = updated.artifacts[updated.artifacts.length - 1];
-                    proposalArtifactId = lastArtifact?.artifact_id;
-                    if (proposalArtifactId) {
-                        artifacts.push({ type: 'artifact', id: proposalArtifactId });
-                        side_effects.push({ action: 'create', entity: 'artifact', id: proposalArtifactId });
-                    }
-                }
-                catch (err) {
-                    const msg = err instanceof Error ? err.message : String(err);
-                    return {
-                        response: createToolErrorResponse('ideate_failed', `ideate intent: failed to open ideation loop — ${msg}`),
-                    };
-                }
-                // pln#492 phase 2.d.2 — multi-agent dispatch. Skipped in single-
-                // agent mode (the champion drives manually).
-                let dispatchedCritics = 0;
-                let dispatchedPhase = 'proposal';
-                if (explicitTargets) {
-                    try {
-                        // Build a search-backed BriefMemoryProvider. Maps user-facing
-                        // memory categories the brief asks for onto src/core/search.ts
-                        // sections (BM25 there). Loop-internal categories
-                        // (critique_history / revision_history / synthesis_artifact)
-                        // are pulled by the assembler from the thread directly.
-                        const searchModule = await import('../core/search.js');
-                        const sectionByCategory = {
-                            traps: 'traps',
-                            decisions: 'decisions',
-                            constraints: 'constraints',
-                            handoffs: 'handoffs',
-                            plans: 'plans',
-                            candidates: 'candidates',
-                        };
-                        const provider = {
-                            fetch(category, query, topK) {
-                                const section = sectionByCategory[category];
-                                if (!section)
-                                    return [];
-                                const results = searchModule.search({
-                                    query,
-                                    section,
-                                    maxResults: topK,
-                                    cwd: dispatchCwd,
-                                    includePending: section === 'candidates',
-                                });
-                                return results.map((r) => ({
-                                    id: r.id,
-                                    category,
-                                    text: r.text,
-                                    score: r.score,
-                                }));
-                            },
-                        };
-                        // Advance proposal → critique. proposal has no advance_gate so
-                        // this is unconditional. After advance, the loop sits at the
-                        // critique phase ready for critic turns.
-                        advance({ id: loopId, actor: creatorActor }, dispatchCwd);
-                        const advancedLoop = getLoop(loopId, dispatchCwd);
-                        if (!advancedLoop) {
-                            throw new Error('ideate dispatch: loop disappeared after advance');
-                        }
-                        dispatchedPhase = advancedLoop.current_phase;
-                        const criticSlots = advancedLoop.slots.filter((s) => s.role === 'critic');
-                        for (const slot of criticSlots) {
-                            if (!slot.agent)
-                                continue;
-                            const briefResult = buildIdeationBrief({
-                                thread: advancedLoop,
-                                slotRole: slot.role,
-                                memoryProvider: provider,
+                    ];
+                    if (explicitTargets) {
+                        for (const agent of req.targetAgents) {
+                            const criticIdentity = findAgentIdentityByName(agent, dispatchCwd) ?? ensureAgentRegisteredForDispatch(agent, dispatchCwd);
+                            slots.push({
+                                role: 'critic',
+                                agent,
+                                ...(criticIdentity?.agent_id ? { agent_id: criticIdentity.agent_id } : {}),
                             });
-                            turn({
-                                id: loopId,
-                                slot_id: slot.slot_id,
-                                actor: creatorActor,
-                                input: briefResult.text,
+                        }
+                    }
+                    let loopId;
+                    let proposalArtifactId;
+                    if (bootstrapOpenedLoop) {
+                        // Bootstrap case: helper already opened the loop and released its lock.
+                        loopId = bootstrapOpenedLoop.id;
+                        artifacts.push({ type: 'loop', id: bootstrapOpenedLoop.id });
+                        side_effects.push({ action: 'create', entity: 'loop', id: bootstrapOpenedLoop.id });
+                    }
+                    else {
+                        try {
+                            const loop = openLoop({
+                                kind: 'ideation',
+                                title: req.task.slice(0, 120),
+                                goal: req.scope,
+                                created_by: creatorActor,
+                                slots,
+                                ...(presetSelected
+                                    ? {
+                                        phases: presetSelected.phases,
+                                        stop_condition: presetSelected.stop_condition,
+                                        protocol: presetSelected.protocol,
+                                    }
+                                    : {}),
                             }, dispatchCwd);
-                            const queued = queueCoordinateMessage({
-                                agent: slot.agent,
-                                text: briefResult.text,
-                                messageType: 'rfc',
-                                ref: loopId,
-                                scope: req.scope,
-                                tags: ['coordinate', 'ideate', 'loop'],
-                                payload: {
-                                    intent: 'ideate',
-                                    loop_id: loopId,
-                                    slot_id: slot.slot_id,
-                                    phase: advancedLoop.current_phase,
-                                    iteration: advancedLoop.iteration_count,
-                                    proposal_artifact_id: proposalArtifactId,
+                            loopId = loop.id;
+                            artifacts.push({ type: 'loop', id: loop.id });
+                            side_effects.push({ action: 'create', entity: 'loop', id: loop.id });
+                            // pln#511 step 2 — skip the proposal-seed artifact when a preset
+                            // is in use. The kind-default ideation chain opens at phase
+                            // 'proposal' and the seed artifact lives there; presets define
+                            // their own initial phase + seeding semantics (bootstrap starts
+                            // at 'survey' and produces a signals_report). Forcing a
+                            // 'proposal'-phased artifact here would dangle on a phase the
+                            // loop doesn't contain. The task text is already captured on
+                            // the thread (title + goal).
+                            if (!presetSelected) {
+                                const proposalBody = req.task.slice(0, 4000);
+                                const updated = add_artifact({
+                                    id: loop.id,
+                                    actor: creatorActor,
+                                    artifact: {
+                                        phase: 'proposal',
+                                        type: 'proposal',
+                                        body: proposalBody,
+                                        produced_by: creatorActor,
+                                    },
+                                }, dispatchCwd);
+                                const lastArtifact = updated.artifacts[updated.artifacts.length - 1];
+                                proposalArtifactId = lastArtifact?.artifact_id;
+                                if (proposalArtifactId) {
+                                    artifacts.push({ type: 'artifact', id: proposalArtifactId });
+                                    side_effects.push({ action: 'create', entity: 'artifact', id: proposalArtifactId });
+                                }
+                            }
+                        }
+                        catch (err) {
+                            const msg = err instanceof Error ? err.message : String(err);
+                            return {
+                                response: createToolErrorResponse('ideate_failed', `ideate intent: failed to open ideation loop — ${msg}`),
+                            };
+                        }
+                    } // end else (non-bootstrap open path)
+                    // pln#492 phase 2.d.2 — multi-agent dispatch. Skipped in single-
+                    // agent mode (the champion drives manually).
+                    //
+                    // pln#511 step 2 — initial phase comes from the actual loop's
+                    // first phase, not a hardcoded 'proposal'. Presets like bootstrap
+                    // open at 'survey'; the kind-default ideation chain still opens
+                    // at 'proposal', so this is backward compatible.
+                    let dispatchedCritics = 0;
+                    let dispatchedPhase = presetSelected ? presetSelected.phases[0].name : 'proposal';
+                    if (explicitTargets) {
+                        try {
+                            // Build a search-backed BriefMemoryProvider. Maps user-facing
+                            // memory categories the brief asks for onto src/core/search.ts
+                            // sections (BM25 there). Loop-internal categories
+                            // (critique_history / revision_history / synthesis_artifact)
+                            // are pulled by the assembler from the thread directly.
+                            const searchModule = await import('../core/search.js');
+                            const sectionByCategory = {
+                                traps: 'traps',
+                                decisions: 'decisions',
+                                constraints: 'constraints',
+                                handoffs: 'handoffs',
+                                plans: 'plans',
+                                candidates: 'candidates',
+                            };
+                            const provider = {
+                                fetch(category, query, topK) {
+                                    const section = sectionByCategory[category];
+                                    if (!section)
+                                        return [];
+                                    const results = searchModule.search({
+                                        query,
+                                        section,
+                                        maxResults: topK,
+                                        cwd: dispatchCwd,
+                                        includePending: section === 'candidates',
+                                    });
+                                    return results.map((r) => ({
+                                        id: r.id,
+                                        category,
+                                        text: r.text,
+                                        score: r.score,
+                                    }));
                                 },
-                                commandMode: 'consult',
-                            });
-                            void queued;
-                            dispatchedCritics += 1;
-                            if (briefResult.truncated) {
-                                warnings.push(`Brief for critic slot ${slot.slot_id} (${slot.agent}) truncated: ${briefResult.droppedItems} memory items dropped to fit cap`);
+                            };
+                            // Advance proposal → critique. proposal has no advance_gate so
+                            // this is unconditional. After advance, the loop sits at the
+                            // critique phase ready for critic turns.
+                            advance({ id: loopId, actor: creatorActor }, dispatchCwd);
+                            const advancedLoop = getLoop(loopId, dispatchCwd);
+                            if (!advancedLoop) {
+                                throw new Error('ideate dispatch: loop disappeared after advance');
+                            }
+                            dispatchedPhase = advancedLoop.current_phase;
+                            const criticSlots = advancedLoop.slots.filter((s) => s.role === 'critic');
+                            for (const slot of criticSlots) {
+                                if (!slot.agent)
+                                    continue;
+                                const briefResult = buildIdeationBrief({
+                                    thread: advancedLoop,
+                                    slotRole: slot.role,
+                                    memoryProvider: provider,
+                                });
+                                turn({
+                                    id: loopId,
+                                    slot_id: slot.slot_id,
+                                    actor: creatorActor,
+                                    input: briefResult.text,
+                                }, dispatchCwd);
+                                const queued = queueCoordinateMessage({
+                                    agent: slot.agent,
+                                    text: briefResult.text,
+                                    messageType: 'rfc',
+                                    ref: loopId,
+                                    scope: req.scope,
+                                    tags: ['coordinate', 'ideate', 'loop'],
+                                    payload: {
+                                        intent: 'ideate',
+                                        loop_id: loopId,
+                                        slot_id: slot.slot_id,
+                                        phase: advancedLoop.current_phase,
+                                        iteration: advancedLoop.iteration_count,
+                                        proposal_artifact_id: proposalArtifactId,
+                                    },
+                                    commandMode: 'consult',
+                                });
+                                void queued;
+                                dispatchedCritics += 1;
+                                if (briefResult.truncated) {
+                                    warnings.push(`Brief for critic slot ${slot.slot_id} (${slot.agent}) truncated: ${briefResult.droppedItems} memory items dropped to fit cap`);
+                                }
                             }
                         }
+                        catch (err) {
+                            const msg = err instanceof Error ? err.message : String(err);
+                            warnings.push(`ideate dispatch failed: ${msg}; loop ${loopId} stays at proposal phase`);
+                            facadeStatus = 'partial';
+                        }
                     }
-                    catch (err) {
-                        const msg = err instanceof Error ? err.message : String(err);
-                        warnings.push(`ideate dispatch failed: ${msg}; loop ${loopId} stays at proposal phase`);
-                        facadeStatus = 'partial';
+                    if (!explicitTargets) {
+                        warnings.push(presetSelected
+                            ? `ideate single-agent mode (preset='${req.preset}'): loop opened at phase '${dispatchedPhase}'; champion drives manually via bclaw_loop intent='turn' / 'advance'.`
+                            : "ideate single-agent mode: loop opened with proposal seed; champion drives manually via bclaw_loop intent='turn' / 'advance'. Pass targetAgents to enable multi-agent auto-dispatch.");
                     }
+                    result = {
+                        loop_id: loopId,
+                        proposal_artifact_id: proposalArtifactId,
+                        selected_targets: explicitTargets ? req.targetAgents : [],
+                        mode: explicitTargets ? 'multi_agent' : 'single_agent',
+                        dispatched_critics: dispatchedCritics,
+                        current_phase: dispatchedPhase,
+                        ...(presetSelected ? { preset: req.preset } : {}),
+                    };
+                    // pln#518 step 1 — bootstrap lock is now managed inside acquireBootstrapLoop;
+                    // no release needed here.
                 }
-                if (!explicitTargets) {
-                    warnings.push("ideate single-agent mode: loop opened with proposal seed; champion drives manually via bclaw_loop intent='turn' / 'advance'. Pass targetAgents to enable multi-agent auto-dispatch.");
-                }
-                result = {
-                    loop_id: loopId,
-                    proposal_artifact_id: proposalArtifactId,
-                    selected_targets: explicitTargets ? req.targetAgents : [],
-                    mode: explicitTargets ? 'multi_agent' : 'single_agent',
-                    dispatched_critics: dispatchedCritics,
-                    current_phase: dispatchedPhase,
-                };
-            }
             // Extract execution_status from result if present (assign/reroute set it)
             const resultExecStatus = (result && typeof result === 'object' && 'execution_status' in result)
                 ? result.execution_status
                 : undefined;
+            // pln#503 phase 3.3: when execution_status === 'delivered_and_started',
+            // attach a self-documenting `verify_with` hint pointing at the assignment
+            // record. Callers should not take delivered_and_started at face value —
+            // it only attests the brief-ack sentinel was touched, not that the worker
+            // is doing useful work. The hint tells them exactly which canonical-
+            // grammar call to make next to verify spawn liveness.
+            let verifyWith;
+            if (resultExecStatus === 'delivered_and_started') {
+                const firstAssignment = artifacts.find((a) => a.type === 'assignment');
+                if (firstAssignment) {
+                    verifyWith = {
+                        action: 'bclaw_find',
+                        entity: 'agent_run',
+                        filter: { assignment_id: firstAssignment.id },
+                        expected_when_alive: 'agent_run with status="running" AND OS pid alive AND last_event_at within the last few minutes',
+                        see_also: 'docs/concepts/dispatch-lifecycle.md',
+                    };
+                }
+            }
             const facadeResponse = {
                 status: facadeStatus,
                 intent: req.intent,
@@ -5232,6 +5660,7 @@ async function _executeMcpToolCallInner(payload) {
                 warnings,
                 duration_ms: Date.now() - startMs,
                 ...(resultExecStatus ? { execution_status: resultExecStatus } : {}),
+                ...(verifyWith ? { verify_with: verifyWith } : {}),
             };
             const summaryParts = [`✔ bclaw_coordinate [${req.intent}] targets=${resolvedAgents.length}`];
             if (resultExecStatus)
@@ -5247,7 +5676,8 @@ async function _executeMcpToolCallInner(payload) {
         }
         if (name === 'bclaw_loop') {
             const { handleBclawLoop } = await import('./loops-handlers.js');
-            const result = handleBclawLoop({ args: args, cwd });
+            const targetCwd = resolveProjectCwd(args?.project, cwd);
+            const result = handleBclawLoop({ args: args, cwd: targetCwd });
             return {
                 response: toolResponse({
                     content: [{ type: 'text', text: result.summary }],
@@ -5321,10 +5751,12 @@ async function _executeMcpToolCallInner(payload) {
                 // applied when it hadn't. Under the new contract, an unknown key is
                 // a validation_error listing the keys actually honored.
                 const KNOWN_FILTER_KEYS = new Set([
-                    'status', 'tag', 'author', 'plan_id', 'source', 'auto_generated',
+                    'status', 'tag', 'tags', 'author', 'plan_id', 'source', 'auto_generated',
+                    'assignment_id', 'claim_id', 'message_id',
                     'limit', 'offset', 'includeLegacy', 'minAutoReflectConfidence',
                 ]);
-                const unknownKeys = Object.keys(filter).filter((k) => !KNOWN_FILTER_KEYS.has(k));
+                const agentRunOnlyFilterKeys = new Set(['assignment_id', 'claim_id', 'message_id']);
+                const unknownKeys = Object.keys(filter).filter((k) => !KNOWN_FILTER_KEYS.has(k) || (agentRunOnlyFilterKeys.has(k) && entity !== 'agent_run'));
                 if (unknownKeys.length > 0) {
                     return {
                         response: createToolErrorResponse('validation_error', `Unknown filter key(s): ${unknownKeys.map((k) => `"${k}"`).join(', ')}. ` +
@@ -5332,6 +5764,7 @@ async function _executeMcpToolCallInner(payload) {
                     };
                 }
                 const result = listEntities(entity, targetCwd, filter);
+                const warnings = collectLoadValidationWarnings(entity, targetCwd);
                 // structuredContent is the canonical MCP return channel that clients
                 // (VS Code extension, Codex, etc.) read for machine-parseable data.
                 // Prior to this fix we spread `...result` at top-level of the
@@ -5341,7 +5774,7 @@ async function _executeMcpToolCallInner(payload) {
                 return {
                     response: toolResponse({
                         content: [{ type: 'text', text: `✔ ${result.total} ${entity} item(s)` }],
-                        structuredContent: { ...result },
+                        structuredContent: { ...result, warnings },
                     }),
                 };
             }
@@ -5354,6 +5787,21 @@ async function _executeMcpToolCallInner(payload) {
                 const entity = String(args.entity ?? '');
                 const id = String(args.id ?? '');
                 const targetCwd = resolveProjectCwd(args.project, cwd);
+                const validationWarning = findLoadValidationWarning(entity, id, targetCwd);
+                if (validationWarning) {
+                    return {
+                        response: toolResponse({
+                            content: [{ type: 'text', text: `✖ ${entity} ${id} failed validation at load` }],
+                            structuredContent: {
+                                ok: false,
+                                error: 'validation_failed',
+                                entity_id: validationWarning.entity_id,
+                                validation_errors: validationWarning.validation_errors,
+                                path: validationWarning.path,
+                            },
+                        }, true),
+                    };
+                }
                 const item = getEntity(entity, id, targetCwd);
                 return {
                     response: toolResponse({
@@ -5514,7 +5962,7 @@ export async function executeMcpToolCall(payload) {
             }
             else {
                 // First-ever connection for this claim — start a fresh session + adopt.
-                const sessionResult = startSession({ cwd, maintenanceMode: 'fast' });
+                const sessionResult = await startSession({ cwd, maintenanceMode: 'fast' });
                 autoSessionId = sessionResult.session_id;
                 effectiveConnectionSessionId = autoSessionId;
                 try {
@@ -5545,6 +5993,12 @@ export async function executeMcpToolCall(payload) {
         }
         catch { /* best-effort */ }
     }
+    if ((payload.name === 'bclaw_find' || payload.name === 'bclaw_get') && payload.args.entity === 'agent_run') {
+        try {
+            sweepDeadPidRunningAgentRunsAtRead(cwd);
+        }
+        catch { /* best-effort */ }
+    }
     // ── Delegate to inner handler ───────────────────────────────────────────────
     const outcome = await _executeMcpToolCallInner({
         ...payload,