brainclaw 1.8.0 → 1.9.0

package/dist/commands/mcp.js

@@ -16,7 +16,8 @@ import { collectLoadValidationWarnings, findLoadValidationWarning, loadState, pe
 import { generateIdWithLabel } from '../core/ids.js';
 import { memoryExists } from '../core/io.js';
 import { generateCandidateIdWithLabel, loadCandidate, saveCandidate } from '../core/candidates.js';
-import { createEntity, getEntity, listEntities, boundListResult, removeEntity, transitionEntity, updateEntity, } from '../core/entity-operations.js';
+import { createEntity, getEntity, listEntities, boundListResult, DEFAULT_FIND_CHAR_BUDGET, removeEntity, transitionEntity, updateEntity, } from '../core/entity-operations.js';
+import { handoffDiffPreviewNote } from '../core/handoff-snapshot.js';
 import { ENTITY_REGISTRY } from '../core/entity-registry.js';
 import { generateClaimId, listClaims, loadClaim, saveClaim, createCoordinatorClaim, adoptClaimSession, attachAssignmentMessageToClaim, linkClaimToAssignment, releaseClaimWithCascade } from '../core/claims.js';
 import { createSequence, updateSequence, deleteSequence } from '../core/sequence.js';
@@ -29,7 +30,7 @@ import { rejectCandidate } from './reject.js';
 import { startSession } from './session-start.js';
 import { endSession } from './session-end.js';
 import { applyHandoffUpdates } from './update-handoff.js';
-import { AgentIdentityResolutionError, AgentTrustError, findAgentIdentityById, findAgentIdentityByName, requireMinimumTrustLevel, requireRegisteredAgentIdentity, resolveCurrentModel, ensureAgentRegisteredForDispatch, } from '../core/agent-registry.js';
+import { AgentIdentityResolutionError, AgentTrustError, findAgentIdentityById, findAgentIdentityByName, hasMinimumTrustLevel, normalizeAgentName, requireMinimumTrustLevel, requireRegisteredAgentIdentity, resolveCurrentAgentIdentity, resolveCurrentModel, ensureAgentRegisteredForDispatch, } from '../core/agent-registry.js';
 import { appendAuditEntry } from '../core/audit.js';
 import { nowISO, generateId } from '../core/ids.js';
 import { buildOperationalIdentity, loadAllSessions, loadSessionById } from '../core/identity.js';
@@ -39,7 +40,7 @@ import { detectAiAgent } from '../core/ai-agent-detection.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 { assessBootstrapNeed, probeForQuickSetup, buildQuickSetupProbeResponse, buildOnboardingPreview, resolveEmptyMemoryRecommendation } from '../core/setup-flow.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';
@@ -95,8 +96,9 @@ export const MCP_READ_TOOLS = [
                 refresh: { type: 'boolean', description: 'Force a fresh bootstrap scan.' },
                 audience: { type: 'string', description: 'Optional interview audience filter: cli, ide_chat, or any.' },
                 interview: { type: 'boolean', description: 'Render interview text instead of the summary text.' },
-                apply: { type: 'boolean', description: 'Apply the current import proposal into canonical memory.' },
-                uninstall: { type: 'boolean', description: 'Uninstall the last bootstrap-managed import.' },
+                apply: { type: 'boolean', description: 'Apply the current import proposal into canonical memory. Requires yes: true.' },
+                uninstall: { type: 'boolean', description: 'Uninstall the last bootstrap-managed import. Requires yes: true.' },
+                yes: { type: 'boolean', description: 'Explicit confirmation for apply/uninstall (mirrors the CLI --yes gate). Without it the call returns confirmation_required and makes no changes.' },
                 interviewAnswers: {
                     type: 'array',
                     description: 'Optional structured interview answers. Each answer may include question_id, response_text, response_items, response_boolean, and explicit suggestions.',
@@ -119,15 +121,15 @@ export const MCP_READ_TOOLS = [
         // Unified dispatcher over the four legacy context reads.
         // Promoted to standard tier at the v1.0 cut.
         name: 'bclaw_context',
-        description: 'Unified context read. Dispatches by kind: memory (project memory for a path), execution (local execution env), board (full agent board), board_summary (compact counts), delta (memory changes since a reference session).',
+        description: 'Unified context read. Dispatches by kind: memory (project memory for a path), execution (local execution env), board (full agent board), board_summary (compact counts), cross_project (linked_projects + incoming_signals only), delta (memory changes since a reference session).',
         annotations: { tier: 'facade', category: 'context', headlessApproval: 'auto' },
         inputSchema: {
             type: 'object',
             properties: {
                 kind: {
                     type: 'string',
-                    enum: ['memory', 'execution', 'board', 'board_summary', 'delta'],
-                    description: 'memory = project memory context; execution = local env/tooling; board = full agent board; board_summary = lightweight counts; delta = memory changes since `since`.',
+                    enum: ['memory', 'execution', 'board', 'board_summary', 'cross_project', 'delta'],
+                    description: 'memory = project memory context; execution = local env/tooling; board = full agent board; board_summary = lightweight counts; cross_project = linked_projects + incoming_signals only; delta = memory changes since `since`.',
                 },
                 since: {
                     type: 'string',
@@ -149,6 +151,7 @@ export const MCP_READ_TOOLS = [
                 compactTemplate: { type: 'boolean', description: 'Use compact template (memory kind, format=template).' },
                 includeAgentTooling: { type: 'boolean', description: 'Include agent tooling signals (execution kind).' },
                 project: { type: 'string', description: 'Optional: name of a linked project to read context from. Defaults to the current project. Accepts cross_project_links and workspace store-chain children.' },
+                budget_tokens: { type: 'number', description: 'Approximate token budget for the payload (~4 chars/token). memory kind: relevance-ranked item fill; board kind: arrays bounded by size.' },
             },
             required: ['kind'],
         },
@@ -166,6 +169,7 @@ export const MCP_READ_TOOLS = [
                 since: { type: 'string', description: 'Filter items created after this ISO date.' },
                 limit: { type: 'number', description: 'Maximum number of results to return (default 10).' },
                 offset: { type: 'number', description: 'Number of results to skip (for pagination).' },
+                budget_tokens: { type: 'number', description: 'Optional token budget for the result page (~4 chars/token). The page is size-bounded; has_more/next_offset advertise the rest.' },
             },
             required: ['query'],
         },
@@ -560,12 +564,13 @@ const MCP_WRITE_TOOLS = [
     },
     {
         name: 'bclaw_quick_capture',
-        description: 'Capture free-form text and classify it locally into a decision, trap, or fallback runtime note. Uses keyword heuristics only, never an LLM.',
+        description: 'Capture free-form text as a decision, trap, constraint, or runtime note. Declare `type` yourself (you know what you are capturing — caller assertion wins); keyword heuristics are only a fallback when type is absent. Contradictions with existing memory are attached as advisory metadata on the candidate, never block promotion.',
         annotations: { tier: 'standard', category: 'memory', headlessApproval: 'auto' },
         inputSchema: {
             type: 'object',
             properties: {
                 text: { type: 'string', description: 'Free-form capture text.' },
+                type: { type: 'string', enum: ['decision', 'trap', 'constraint', 'note'], description: 'Caller-asserted classification. Strongly recommended — the calling agent knows the nature of the capture better than keyword heuristics (cnd_abe61d68: 18 false contradiction positives on a review summary).' },
                 context: { type: 'string', description: 'Optional file/path/scope context to associate with the capture.' },
                 agent: { type: 'string', description: 'Agent name.' },
                 agentId: { type: 'string', description: 'Registered agent id.' },
@@ -643,7 +648,7 @@ const MCP_WRITE_TOOLS = [
                 reflectHandoff: { type: 'boolean', description: 'Materialize an open handoff from git commits since session start.' },
                 dispatchReview: { type: 'boolean', description: 'When used with reflectHandoff, auto-dispatch a code review if the reflected handoff is reviewable.' },
                 reviewer: { type: 'string', description: 'Explicit reviewer for the reflected handoff review dispatch.' },
-                reflect: { type: 'boolean', description: 'Include structured reflection questions. Answer via bclaw_write_note with tag [reflection].' },
+                reflect: { type: 'boolean', description: 'Emit the dogfooding reflection prompt (project + your surfaces/skills/tools). Default true — pass false to suppress on a trivial session. Capture actionable findings via bclaw_quick_capture.' },
             },
         },
     },
@@ -701,6 +706,8 @@ const MCP_WRITE_TOOLS = [
                         text: { type: 'string', description: 'Step description.' },
                         title: { type: 'string', description: 'Alias for text.' },
                         assignee: { type: 'string', description: 'Optional assignee.' },
+                        estimated_effort: { type: 'number', description: 'Step-level estimate in minutes (pln#495). A duration string like "2h"/"30m" is also accepted and coerced.' },
+                        actual_effort: { type: 'string', description: 'Step-level actual effort, free-form ("45m", "2h"), parsed when the estimation report runs.' },
                     },
                 },
                 text: { type: 'string', description: 'Legacy top-level step description; prefer data.text.' },
@@ -740,6 +747,8 @@ const MCP_WRITE_TOOLS = [
                 status: { type: 'string', description: 'New status: todo, in_progress, testing, done, blocked.' },
                 text: { type: 'string', description: 'New step text.' },
                 assignee: { type: 'string', description: 'New assignee (empty string to unassign).' },
+                estimated_effort: { type: 'number', description: 'Step-level estimate in minutes (pln#495); a duration string is also coerced.' },
+                actual_effort: { type: 'string', description: 'Step-level actual effort, free-form ("45m", "2h").' },
                 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.' },
@@ -952,6 +961,7 @@ const MCP_WRITE_TOOLS = [
                 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 },
+                budget_tokens: { type: 'number', description: 'Approximate token budget for the context payload. Relevance-ranked fill: highest-scoring items kept until the budget is reached (~4 chars/token).' },
             },
             required: ['intent'],
         },
@@ -998,8 +1008,12 @@ const MCP_WRITE_TOOLS = [
             properties: {
                 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. 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.).',
+                    // 'open' is intentionally NOT exposed standalone (pln#542): it
+                    // created a loop structure without dispatching the first turn, so
+                    // nothing ever ran. Loops are opened via
+                    // bclaw_coordinate(intent='review', open_loop=true) or intent='ideate'.
+                    enum: ['get', 'list', 'turn', 'complete_turn', 'advance', 'add_artifact', 'pause', 'resume', 'close'],
+                    description: 'Loop lifecycle intent for driving turns inside a loop that was already opened via the coordinate facade. To START a loop, use `bclaw_coordinate(intent="review", open_loop=true, targetAgents=[…])` or `intent="ideate"` — that opens the loop AND dispatches the first turn. See docs/concepts/loop-engine.md.',
                 },
                 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.' },
@@ -1122,6 +1136,7 @@ const MCP_WRITE_TOOLS = [
                 entity: { type: 'string', description: 'Entity name: plan | decision | constraint | trap | handoff | runtime_note | candidate | sequence | claim | action | assignment | agent_run | cross_project_link. Others not yet wired.' },
                 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`.' },
+                budget_tokens: { type: 'number', description: 'Optional token budget for the page payload (~4 chars/token). Tightens the default size cap; pagination metadata (has_more/next_offset) still applies.' },
             },
             required: ['entity'],
         },
@@ -1136,6 +1151,7 @@ const MCP_WRITE_TOOLS = [
                 entity: { type: 'string', description: 'Entity name.' },
                 id: { type: 'string', description: 'Entity id (e.g. dec_ab12cd) or short_label (e.g. dec#42).' },
                 project: { type: 'string', description: 'Optional: name of a linked project to fetch from. Defaults to the current project. See `brainclaw link list` for accepted names.' },
+                budget_tokens: { type: 'number', description: 'Optional token budget (~4 chars/token). Bounds unbounded fields (e.g. handoff snapshot diffs).' },
             },
             required: ['entity', 'id'],
         },
@@ -1226,6 +1242,39 @@ export const MCP_TOOL_NAMES = ALL_TOOLS.map((tool) => tool.name);
 export const MCP_HEADLESS_AUTO_TOOL_NAMES = ALL_TOOLS
     .filter((tool) => tool.annotations?.headlessApproval === 'auto')
     .map((tool) => tool.name);
+/**
+ * Narrow "canonical grammar" tool set — the read-side facade entries
+ * (session + context) plus the five memory verbs (find / get / create /
+ * update / transition). Consumed by writers (e.g. Hermes' tools.include)
+ * that want a minimal advertised surface rather than the full headless-auto
+ * catalog. Coordination facades (dispatch, coordinate, loop) are excluded
+ * because narrow-surface agents shouldn't be routing work.
+ *
+ * Derivation rule (no hand-curated array):
+ *   - tier=facade AND category in {session, context} AND headlessApproval=auto
+ *   - OR name in the canonical memory verbs
+ *
+ * Adding a new memory grammar verb is the only edit that requires touching
+ * this file; everything else propagates from ALL_TOOLS annotations (pln#546 step 2).
+ */
+const _CANONICAL_GRAMMAR_MEMORY_VERBS = new Set([
+    'bclaw_find',
+    'bclaw_get',
+    'bclaw_create',
+    'bclaw_update',
+    'bclaw_transition',
+]);
+export const MCP_CANONICAL_GRAMMAR_TOOL_NAMES = ALL_TOOLS
+    .filter((tool) => {
+    const ann = tool.annotations ?? {};
+    if (ann.tier === 'facade'
+        && (ann.category === 'session' || ann.category === 'context')
+        && ann.headlessApproval === 'auto') {
+        return true;
+    }
+    return _CANONICAL_GRAMMAR_MEMORY_VERBS.has(tool.name);
+})
+    .map((tool) => tool.name);
 /**
  * Tools removed from the MCP surface at the v1.0 cut (Phase 3 slice 3i).
  * Handlers remain in place defensively, but these names are hidden from
@@ -1333,6 +1382,21 @@ export const DEFAULT_PUBLISHED_TOOLS = PUBLISHED_TOOLS
     return a.index - b.index;
 })
     .map(({ tool }) => tool);
+/**
+ * Minimal catalog served while the project memory at cwd is absent.
+ * Instead of refusing to boot (the historical exit(1)), the server starts
+ * in "setup mode" so an agent landing on a fresh repo can initialize it
+ * via bclaw_setup without a CLI shell-out + session-reload discontinuity.
+ */
+export const UNINITIALIZED_TOOL_NAMES = new Set([
+    'bclaw_setup',
+    'bclaw_init_project',
+    'bclaw_doctor',
+]);
+export const UNINITIALIZED_PUBLISHED_TOOLS = PUBLISHED_TOOLS.filter((tool) => UNINITIALIZED_TOOL_NAMES.has(tool.name));
+export function buildUninitializedStateMessage(cwd) {
+    return `Project memory not initialized at ${cwd}. The brainclaw MCP server is running in setup mode: only bclaw_setup, bclaw_init_project and bclaw_doctor are available. Call bclaw_setup to initialize this repo — the full tool catalog activates automatically afterwards.`;
+}
 class McpProtocolError extends Error {
     code;
     id;
@@ -1525,10 +1589,108 @@ function getCancelledRequestId(params) {
     }
     return undefined;
 }
+let principalCache;
+/** Test hook — the principal is otherwise pinned for the process lifetime. */
+export function __resetConnectionPrincipalForTests() {
+    principalCache = undefined;
+}
+/**
+ * Resolve the connection principal. The MCP server is one process per
+ * connection, so a process-level pin IS the per-connection pin; the cache key
+ * guards the identity-bearing env vars so in-process test harnesses that
+ * switch agents between calls re-resolve instead of leaking the first pin.
+ */
+function resolveConnectionPrincipal(cwd, sessionId) {
+    const env = process.env;
+    const key = [
+        env.BRAINCLAW_CLAIM_ID ?? '', env.BRAINCLAW_AGENT_ID ?? '',
+        env.BRAINCLAW_AGENT_NAME ?? '', env.BRAINCLAW_AGENT ?? '',
+        cwd ?? '', sessionId ?? '',
+    ].join('|');
+    if (principalCache && principalCache.key === key)
+        return principalCache.value;
+    let value;
+    // 1. Assignment binding: a dispatched worker carries BRAINCLAW_CLAIM_ID; the
+    //    claim names the identity the coordinator dispatched — authoritative.
+    const claimId = env.BRAINCLAW_CLAIM_ID?.trim();
+    if (claimId) {
+        try {
+            const claim = loadClaim(claimId, cwd);
+            const identity = (claim.agent_id ? findAgentIdentityById(claim.agent_id, cwd) : undefined)
+                ?? findAgentIdentityByName(claim.agent, cwd);
+            if (identity) {
+                value = {
+                    agent_name: identity.agent_name,
+                    agent_id: identity.agent_id,
+                    session_id: claim.session_id ?? sessionId,
+                    pid: process.pid,
+                    source: 'claim_binding',
+                };
+            }
+        }
+        catch { /* claim may not exist in this store — fall through */ }
+    }
+    // 2. Server-side detection (env-pinned or detected REGISTERED identity —
+    //    read-only since pln#562 step 2, never mints).
+    if (!value) {
+        const identity = resolveCurrentAgentIdentity(cwd);
+        if (identity) {
+            value = {
+                agent_name: identity.agent_name,
+                agent_id: identity.agent_id,
+                session_id: sessionId,
+                pid: process.pid,
+                source: 'server_detection',
+            };
+        }
+    }
+    principalCache = { key, value };
+    return value;
+}
 function resolveMutationIdentity(args, fields, cwd, sessionId) {
     try {
+        const explicitName = typeof args[fields.nameField] === 'string' ? String(args[fields.nameField]) : undefined;
+        const explicitId = typeof args[fields.idField] === 'string' ? String(args[fields.idField]) : undefined;
+        // pln#562 step 3 — pinned connection principal. When the server resolved
+        // an authenticated principal, caller args are verified against it:
+        // matching/absent args → principal; mismatching args → curator-only
+        // explicit override, otherwise the mismatch is REJECTED loudly. Silently
+        // re-attributing a spoofed/mistaken identity to the principal would hide
+        // caller bugs — fail-loud is the contract (mcp-protocol.test 'rejects
+        // unregistered identities and mismatched id/name pairs').
+        const principal = resolveConnectionPrincipal(cwd, sessionId);
+        if (principal) {
+            // Re-load per call (cheap) so trust changes propagate mid-connection;
+            // the BINDING (who you are) stays pinned.
+            const principalDoc = findAgentIdentityById(principal.agent_id, cwd);
+            if (principalDoc) {
+                const mismatch = (explicitName !== undefined && normalizeAgentName(explicitName) !== normalizeAgentName(principal.agent_name))
+                    || (explicitId !== undefined && explicitId !== principal.agent_id);
+                if (!mismatch) {
+                    return { identity: principalDoc };
+                }
+                if ((principalDoc.trust_level ?? 'contributor') === 'curator') {
+                    return {
+                        identity: requireRegisteredAgentIdentity({
+                            agentName: explicitName,
+                            agentId: explicitId,
+                            cwd,
+                            allowCurrent: true,
+                            allowEnv: true,
+                        }),
+                    };
+                }
+                return {
+                    error: {
+                        kind: 'identity_error',
+                        message: `Caller-supplied identity (agent=${explicitName ?? '<none>'}, agentId=${explicitId ?? '<none>'}) does not match the pinned connection principal '${principal.agent_name}' (${principal.agent_id}). Omit the identity args, or have a curator perform the override.`,
+                    },
+                };
+            }
+        }
+        // No pinned principal (unregistered connection): legacy chain.
         // Session-pinned identity: if no explicit agent in args, use the session's pinned agent
-        let agentName = typeof args[fields.nameField] === 'string' ? String(args[fields.nameField]) : undefined;
+        let agentName = explicitName;
         if (!agentName && sessionId) {
             const session = loadSessionById(sessionId, cwd);
             if (session?.agent) {
@@ -1538,7 +1700,7 @@ function resolveMutationIdentity(args, fields, cwd, sessionId) {
         return {
             identity: requireRegisteredAgentIdentity({
                 agentName,
-                agentId: typeof args[fields.idField] === 'string' ? String(args[fields.idField]) : undefined,
+                agentId: explicitId,
                 cwd,
                 allowCurrent: true,
                 allowEnv: true,
@@ -1592,12 +1754,15 @@ function ensureTrust(args, fields, level, cwd, sessionId) {
 }
 /**
  * Resolve the agent identity for canonical-grammar mutation verbs
- * (bclaw_create/update/remove/transition). Returns a best-effort identity so
- * that handlers can auto-fill required fields (e.g. plan.author) instead of
- * letting the create land on disk with a missing field — which would then be
- * silently GC'd by the state sync loop (see fix plan pln_5f44426c).
+ * (bclaw_create/update/remove/transition), so handlers can auto-fill required
+ * fields (e.g. plan.author) instead of letting the create land on disk with a
+ * missing field — which would then be silently GC'd by the state sync loop
+ * (see fix plan pln_5f44426c).
  *
- * Falls back to args.agent if resolution fails, and finally to 'unknown'.
+ * pln#562 step 3 — resolution failure is a HARD error. The old fallback to
+ * author:'unknown' produced records that passed creation but were schema-
+ * invalid on read and silently GC'd: a write that lies about succeeding.
+ * Callers map the throw to a validation_error tool response.
  */
 function resolveCanonicalAuthor(args, cwd, connectionSessionId) {
     const resolved = resolveMutationIdentity(args, { nameField: 'agent', idField: 'agentId' }, cwd, connectionSessionId);
@@ -1607,8 +1772,9 @@ function resolveCanonicalAuthor(args, cwd, connectionSessionId) {
             agent_id: resolved.identity.agent_id,
         };
     }
-    const explicit = typeof args.agent === 'string' ? args.agent : undefined;
-    return { agent_name: explicit ?? 'unknown' };
+    const detail = 'error' in resolved && resolved.error ? resolved.error.message : 'no registered agent identity resolved';
+    throw new Error(`cannot resolve mutation author: ${detail} `
+        + 'Start a session (bclaw_session_start) or pass a registered agent before writing.');
 }
 function explicitSessionIdFromEnv() {
     return process.env.BRAINCLAW_SESSION_ID?.trim()
@@ -1650,11 +1816,17 @@ export function parseMcpLine(line) {
         isNotification: !('id' in parsed),
     };
 }
-export function createInitializeResult(protocolVersion) {
+export function createInitializeResult(protocolVersion, options) {
+    const uninitialized = options?.uninitialized === true;
     return {
         protocolVersion,
         serverInfo: { name: 'brainclaw', version: SCHEMA_VERSION },
-        capabilities: { tools: { listChanged: false } },
+        // listChanged is only advertised in setup mode, where the catalog flips
+        // to the full set once the project memory is initialized.
+        capabilities: { tools: { listChanged: uninitialized } },
+        ...(uninitialized
+            ? { instructions: buildUninitializedStateMessage(options?.cwd ?? process.cwd()) }
+            : {}),
     };
 }
 export class McpTaskRunner {
@@ -1777,6 +1949,8 @@ export class McpServerConnection {
     state = 'pre_init';
     protocolVersion;
     connectionSessionId;
+    /** True while the project memory at cwd is absent — serves the minimal setup catalog. */
+    uninitializedMode;
     /** Version of brainclaw code loaded in this process at boot time. */
     bootVersion;
     /** Throttle disk version checks — at most once per 60s. */
@@ -1787,11 +1961,15 @@ export class McpServerConnection {
     constructor(options) {
         this.cwd = options.cwd;
         this.send = options.send;
+        this.uninitializedMode = options.uninitialized ?? false;
         this.bootVersion = getInstalledBrainclawVersion();
         this.taskRunner = new McpTaskRunner({
             executeTool: options.executeTool ?? createWorkerToolExecutor(),
             onResult: (requestId, outcome) => {
-                this.connectionSessionId = outcome.nextConnectionSessionId;
+                if (outcome.nextConnectionSessionId !== undefined) {
+                    // null = explicit clear (session ended); string = refresh; undefined = no-op
+                    this.connectionSessionId = outcome.nextConnectionSessionId ?? undefined;
+                }
                 // Inject version mismatch advisory if stale
                 const advisory = this.checkVersionMismatch();
                 if (advisory && outcome.response.content.length > 0) {
@@ -1800,17 +1978,43 @@ export class McpServerConnection {
                         ...outcome.response.content,
                     ];
                 }
+                const catalogUnlocked = this.reconcileUninitializedMode();
+                if (catalogUnlocked && outcome.response.content.length > 0) {
+                    outcome.response.content = [
+                        ...outcome.response.content,
+                        { type: 'text', text: '✔ Project memory initialized — the full brainclaw tool catalog is now active. If your client does not refresh tools automatically, reload the MCP server session.' },
+                    ];
+                }
                 // Track usage: append response size to usage.jsonl
                 if (outcome.toolName) {
                     this.trackUsage(outcome.toolName, outcome.response);
                 }
                 this.sendResult(requestId, outcome.response);
+                if (catalogUnlocked) {
+                    this.send({ jsonrpc: '2.0', method: 'notifications/tools/list_changed' });
+                }
             },
             onInternalError: (requestId, error) => {
                 this.sendError(requestId, -32603, error instanceof Error ? error.message : 'Internal error');
             },
         });
     }
+    /**
+     * Lazy reconcile: if the server booted in setup mode but the project
+     * memory now exists (initialized via bclaw_setup, bclaw_init_project,
+     * or an out-of-band CLI init), unlock the full catalog.
+     * Returns true exactly once — on the transition.
+     */
+    reconcileUninitializedMode() {
+        if (!this.uninitializedMode) {
+            return false;
+        }
+        if (!memoryExists(this.cwd)) {
+            return false;
+        }
+        this.uninitializedMode = false;
+        return true;
+    }
     /**
      * Compare the version loaded in memory with the version on disk.
      * Returns an advisory string if they differ, undefined otherwise.
@@ -1895,7 +2099,11 @@ export class McpServerConnection {
                 const protocolVersion = resolveRequestedProtocolVersion(params, id ?? null);
                 this.protocolVersion = protocolVersion;
                 this.state = 'awaiting_initialized';
-                this.sendResult(id ?? null, createInitializeResult(protocolVersion));
+                this.reconcileUninitializedMode();
+                this.sendResult(id ?? null, createInitializeResult(protocolVersion, {
+                    uninitialized: this.uninitializedMode,
+                    cwd: this.cwd,
+                }));
                 return;
             }
             if (method === 'notifications/initialized' || method === 'initialized') {
@@ -1918,6 +2126,15 @@ export class McpServerConnection {
             }
             if (method === 'tools/list') {
                 if (!isNotification) {
+                    this.reconcileUninitializedMode();
+                    if (this.uninitializedMode) {
+                        this.sendResult(id ?? null, {
+                            tools: UNINITIALIZED_PUBLISHED_TOOLS,
+                            uninitialized: true,
+                            state: buildUninitializedStateMessage(this.cwd),
+                        });
+                        return;
+                    }
                     const params = message.params === undefined ? {} : requireObjectParams(message.params, id ?? null);
                     const catalog = typeof params.catalog === 'string' ? params.catalog : undefined;
                     const include = typeof params.include === 'string' ? params.include : undefined;
@@ -1947,6 +2164,19 @@ export class McpServerConnection {
                     return;
                 }
                 const args = params.arguments === undefined ? {} : requireObjectParams(params.arguments, id ?? null);
+                this.reconcileUninitializedMode();
+                if (this.uninitializedMode && !UNINITIALIZED_TOOL_NAMES.has(name)) {
+                    this.sendResult(id ?? null, toolResponse({
+                        content: [{ type: 'text', text: buildUninitializedStateMessage(this.cwd) }],
+                        structuredContent: {
+                            error: 'uninitialized',
+                            cwd: this.cwd,
+                            available_tools: [...UNINITIALIZED_TOOL_NAMES],
+                            next_action: 'Call bclaw_setup to initialize this repo.',
+                        },
+                    }, true));
+                    return;
+                }
                 this.taskRunner.enqueue(id ?? null, {
                     name,
                     args,
@@ -2082,12 +2312,15 @@ export class StdioTransport {
     }
     drainNewline() {
         while (true) {
-            const str = this.buffer.toString('utf-8');
-            const newlineIndex = str.indexOf('\n');
+            // Search for '\n' (0x0a) at the byte level so a multibyte UTF-8 sequence
+            // that spans two chunks is never split mid-character.  Avoids O(n²)
+            // string→buffer reconversion on every iteration.
+            const newlineIndex = this.buffer.indexOf(0x0a);
             if (newlineIndex === -1)
                 return;
-            const line = str.slice(0, newlineIndex).replace(/\r$/, '');
-            this.buffer = Buffer.from(str.slice(newlineIndex + 1), 'utf-8');
+            const lineBuffer = this.buffer.subarray(0, newlineIndex);
+            this.buffer = this.buffer.subarray(newlineIndex + 1);
+            const line = lineBuffer.toString('utf-8').replace(/\r$/, '');
             if (line.trim()) {
                 this.onMessage(line);
             }
@@ -2096,9 +2329,12 @@ export class StdioTransport {
 }
 export function runMcp() {
     const cwd = resolveEffectiveCwd();
-    if (!memoryExists(cwd)) {
-        console.error('Project memory not initialized. Run `brainclaw init` first.');
-        process.exit(1);
+    // No project memory yet: start in setup mode instead of refusing to boot,
+    // so agents can initialize the repo via bclaw_setup without a CLI
+    // shell-out + session reload.
+    const uninitialized = !memoryExists(cwd);
+    if (uninitialized) {
+        console.error(buildUninitializedStateMessage(cwd));
     }
     const missingWorkerPath = resolveMcpWorkerEntryPath();
     if (!fs.existsSync(missingWorkerPath)) {
@@ -2120,6 +2356,7 @@ export function runMcp() {
         cwd,
         send: adaptiveSend,
         executeTool: createWorkerToolExecutor(),
+        uninitialized,
     });
     transport.onMessage = (line) => connection.handleLine(line);
     transport.start();
@@ -2135,6 +2372,9 @@ function createWorkerToolExecutor() {
         try {
             worker = new Worker(new URL('./mcp-worker.js', import.meta.url), {
                 workerData: payload,
+                // Capture worker stdout so console.log in tool handlers cannot corrupt
+                // the parent's JSON-RPC stream. Drain captured output to stderr.
+                stdout: true,
             });
         }
         catch (error) {
@@ -2145,6 +2385,8 @@ function createWorkerToolExecutor() {
             reject(error);
             return;
         }
+        // Redirect any worker stdout to the server's stderr (safe for diagnostics)
+        worker.stdout?.pipe(process.stderr);
         let settled = false;
         const cleanup = () => {
             worker.removeAllListeners('message');
@@ -2295,7 +2537,10 @@ function getCrossProjectArg(args, ...keys) {
     return undefined;
 }
 function blockCrossProjectExecution(entity, args) {
-    const targetProject = getCrossProjectArg(args, 'targetProject', 'target_project', 'crossProject', 'cross_project');
+    // Include 'project' so that canonical write verbs that accept a project routing
+    // arg (e.g. bclaw_claim project=...) are subject to the same signaling-only
+    // boundary as the explicit cross-project keys.
+    const targetProject = getCrossProjectArg(args, 'targetProject', 'target_project', 'crossProject', 'cross_project', 'project');
     if (!targetProject) {
         return undefined;
     }
@@ -2385,20 +2630,24 @@ async function _executeMcpToolCallInner(payload) {
                 if (detected) {
                     summary.push(`✔ Agent detected: ${detected.name}`);
                 }
-                summary.push('✔ Reload your agent session to activate brainclaw MCP tools.');
-                // Check if bootstrap is available and generate preview
+                summary.push('✔ Full brainclaw MCP catalog activates automatically; reload your agent session only if new tools do not appear.');
+                // Bootstrap route follows the shared empty-memory rule; the preview
+                // already embeds the same recommendation text when memory is empty.
                 const probe = probeForQuickSetup(cwd);
                 const bootstrapAvailable = probe.hasContent;
+                const emptyMemoryRec = resolveEmptyMemoryRecommendation(cwd);
                 const preview = buildOnboardingPreview(cwd);
                 return {
                     response: toolResponse({
-                        content: [{ type: 'text', text: summary.join('\n') + (bootstrapAvailable ? '\n\nThe repo has existing content. Run bclaw_bootstrap to extract initial project context.' : '') + '\n\n' + preview }],
+                        content: [{ type: 'text', text: summary.join('\n') + '\n\n' + preview }],
                         structuredContent: {
                             setup_complete: true,
                             project_type: projectType,
                             topology,
                             detected_agent: detected?.name ?? null,
                             bootstrap_available: bootstrapAvailable,
+                            bootstrap_route: emptyMemoryRec.route,
+                            next_action: emptyMemoryRec.mcp_next_action,
                             preview,
                             summary,
                         },
@@ -2579,7 +2828,7 @@ async function _executeMcpToolCallInner(payload) {
                     });
                     const signal = writeCrossProjectSignal(resolveCrossProjectWritableTarget(crossProjectTarget, 'runtime_note', cwd), 'runtime_note', {
                         schema_version: 2,
-                        id: generateId('rtn'),
+                        id: generateId('runtime_note'),
                         agent: opIdentity.agent,
                         agent_id: opIdentity.agent_id,
                         project_id: opIdentity.project_id ?? '',
@@ -2649,7 +2898,20 @@ async function _executeMcpToolCallInner(payload) {
                 }
             }
             const identity = resolved.identity;
-            const classification = classifyQuickCapture(text);
+            // Caller-asserted classification wins (pln#542): the calling agent
+            // declares decision/trap/constraint/note; keyword heuristics are the
+            // fallback when no type is given.
+            const assertedType = typeof args.type === 'string' ? args.type.trim().toLowerCase() : undefined;
+            let classification;
+            if (assertedType === 'decision' || assertedType === 'trap' || assertedType === 'constraint' || assertedType === 'note') {
+                classification = { target: assertedType, reason: 'caller_asserted', decisionScore: 0, trapScore: 0 };
+            }
+            else if (assertedType !== undefined) {
+                return { response: createToolErrorResponse('validation_error', `type must be one of: decision, trap, constraint, note (got '${assertedType}')`) };
+            }
+            else {
+                classification = classifyQuickCapture(text);
+            }
             if (classification.target === 'note') {
                 const result = createRuntimeNote(formatQuickCaptureNoteText(text, context), {
                     agent: identity.agent_name,
@@ -2671,6 +2933,9 @@ async function _executeMcpToolCallInner(payload) {
                             note_id: result.noteId,
                             session_id: result.sessionId,
                             context,
+                            next_actions: [
+                                { tool: 'bclaw_quick_capture', args: { text: '<same text>', type: 'decision' }, when: 'this was actually a durable decision/trap/constraint — re-capture with an asserted type' },
+                            ],
                         },
                     }),
                     nextConnectionSessionId: explicitSessionIdFromEnv() ? undefined : result.sessionId,
@@ -2688,6 +2953,13 @@ async function _executeMcpToolCallInner(payload) {
             const statusText = capture.writeThrough
                 ? `✔ Quick capture promoted as ${classification.target} [${capture.promotedItemId}]`
                 : `✔ Quick capture saved as ${classification.target} candidate [${capture.candidateId}]`;
+            const captureNextActions = capture.writeThrough
+                ? [
+                    { tool: 'bclaw_get', args: { entity: classification.target, id: capture.promotedItemId }, when: 'to verify the promoted item' },
+                ]
+                : [
+                    { tool: 'bclaw_get', args: { entity: 'candidate', id: capture.candidateId }, when: 'to review the pending candidate (contradiction metadata is advisory)' },
+                ];
             return {
                 response: toolResponse({
                     content: [{ type: 'text', text: statusText }],
@@ -2699,7 +2971,8 @@ async function _executeMcpToolCallInner(payload) {
                         candidate_id: capture.candidateId,
                         promoted_item_id: capture.promotedItemId,
                         write_through: capture.writeThrough,
-                        promotion_blocked_reason: capture.promotionBlockedReason,
+                        // Advisory only (cnd_abe61d68): contradictions are metadata on
+                        // the candidate, never a promotion blocker.
                         contradiction_summary: capture.contradictionSummary,
                         contradictions_detected: capture.contradictionsDetected?.map((item) => ({
                             severity: item.severity,
@@ -2707,9 +2980,9 @@ async function _executeMcpToolCallInner(payload) {
                             conflicts_with: item.conflicts_with,
                         })),
                         context,
+                        next_actions: captureNextActions,
                     },
                 }),
-                nextConnectionSessionId: undefined,
             };
         }
         if (name === 'bclaw_create_plan') {
@@ -3038,10 +3311,29 @@ async function _executeMcpToolCallInner(payload) {
             catch {
                 return { response: createToolErrorResponse('not_found', `Claim not found: ${claimId}`) };
             }
-            const cascadeResult = releaseClaimWithCascade(claimId, {
-                planStatus: args.planStatus,
-                cwd,
-            });
+            // pln#562 step 5 — release is ownership-checked like acquisition and
+            // adoption. The resolved principal must own the claim; trusted+ callers
+            // (coordinators) may release others' claims, with an audit entry.
+            const releaseIdentity = resolveMutationIdentity(args, { nameField: 'agent', idField: 'agentId' }, cwd, connectionSessionId);
+            const releaseAuth = 'identity' in releaseIdentity && releaseIdentity.identity
+                ? {
+                    agent: releaseIdentity.identity.agent_name,
+                    agent_id: releaseIdentity.identity.agent_id,
+                    session_id: connectionSessionId,
+                    override: hasMinimumTrustLevel(releaseIdentity.identity.trust_level ?? 'contributor', 'trusted'),
+                }
+                : undefined;
+            let cascadeResult;
+            try {
+                cascadeResult = releaseClaimWithCascade(claimId, {
+                    planStatus: args.planStatus,
+                    cwd,
+                    auth: releaseAuth,
+                });
+            }
+            catch (err) {
+                return { response: createToolErrorResponse('trust_error', err instanceof Error ? err.message : String(err)) };
+            }
             const { planTransitioned, planWarning, planId: cascadePlanId, newPlanStatus: cascadeNewStatus } = cascadeResult;
             const summaryText = [
                 `✔ Released claim [${claimId}]`,
@@ -3256,7 +3548,7 @@ async function _executeMcpToolCallInner(payload) {
                     ...(result.handoff ? { handoff: result.handoff } : {}),
                     ...(result.reflection_prompt ? { reflection_prompt: result.reflection_prompt } : {}),
                 }),
-                nextConnectionSessionId: undefined,
+                nextConnectionSessionId: null,
             };
         }
         if (name === 'bclaw_compact') {
@@ -3390,20 +3682,41 @@ async function _executeMcpToolCallInner(payload) {
                 }
                 lines.push(`  Sequence: ${analysis.sequence.name}`);
                 lines.push(`  Ready: ${analysis.ready.length} | Active: ${analysis.active.length} | Blocked: ${analysis.blocked.length} | Done: ${analysis.done.length}`);
+                // can_681a6c52 — truthful per-delivery status. The old output printed
+                // '[inbox]' for every entry and ALWAYS dumped a 'Run these commands'
+                // block, even when the auto-spawn had already SUCCEEDED — an obedient
+                // coordinator would then double-spawn the worker.
+                const spawnedPlanIds = new Set(dispatchResult.messages_sent
+                    .filter((m) => m.execution_status === 'delivered_and_started')
+                    .map((m) => m.plan_id));
                 if (dispatchResult.messages_sent.length > 0) {
                     lines.push('');
                     lines.push(args.dryRun ? '  Would assign:' : '  Assigned:');
                     for (const msg of dispatchResult.messages_sent) {
                         const lane = msg.lane ? ` (lane: ${msg.lane})` : '';
-                        lines.push(`    ${msg.agent}: ${msg.plan_id}${lane} [inbox]`);
+                        const exec = msg.execution_status ? ` [${msg.execution_status}]` : ' [inbox]';
+                        const pid = msg.pid ? ` pid=${msg.pid}` : '';
+                        const run = msg.run_id ? ` run=${msg.run_id}` : '';
+                        lines.push(`    ${msg.agent}: ${msg.plan_id}${lane}${exec}${pid}${run}`);
+                    }
+                }
+                const spawned = dispatchResult.messages_sent.filter((m) => m.execution_status === 'delivered_and_started');
+                if (spawned.length > 0) {
+                    lines.push('');
+                    lines.push('Auto-spawn succeeded — do NOT run the launch commands for these (double-spawn risk). Verify instead:');
+                    for (const msg of spawned) {
+                        const target = msg.assignment_id ?? msg.run_id ?? msg.claim_id;
+                        lines.push(`  bclaw_dispatch_status(target_id: "${target}")  # ${msg.agent} on ${msg.plan_id}`);
                     }
                 }
-                // Surface bash commands prominently — this is what the coordinator should run
-                if (dispatchResult.commands.length > 0) {
+                // Only surface manual launch commands for deliveries that were NOT
+                // auto-spawned (manual fallback, spawn refusal, inbox-only).
+                const manualCommands = dispatchResult.commands.filter((cmd) => !cmd.plan_id || !spawnedPlanIds.has(cmd.plan_id));
+                if (manualCommands.length > 0) {
                     lines.push('');
-                    lines.push('Run these commands to launch the assigned agents:');
+                    lines.push('Run these commands to launch the agents that were NOT auto-spawned:');
                     lines.push('');
-                    for (const cmd of dispatchResult.commands) {
+                    for (const cmd of manualCommands) {
                         const lane = cmd.lane ? ` [lane: ${cmd.lane}]` : '';
                         lines.push(`# ${cmd.agent}${lane}`);
                         lines.push(cmd.command);
@@ -3417,6 +3730,15 @@ async function _executeMcpToolCallInner(payload) {
                         lines.push(`    - ${skip.plan_id}: ${skip.reason}`);
                     }
                 }
+                // can_45316d5c — worktree warnings / spawn refusals were hidden behind
+                // dispatch_status; surface them in the cycle output itself.
+                if (dispatchResult.warnings.length > 0) {
+                    lines.push('');
+                    lines.push('  Warnings:');
+                    for (const warning of dispatchResult.warnings) {
+                        lines.push(`    ⚠ ${warning}`);
+                    }
+                }
                 appendAuditEntry({
                     actor: resolved.identity.agent_name,
                     actor_id: resolved.identity.agent_id,
@@ -3499,7 +3821,9 @@ async function _executeMcpToolCallInner(payload) {
                 if (status === 'accepted' && assignment.message_id) {
                     try {
                         const { ackMessage } = await import('../core/messaging.js');
-                        ackMessage(assignment.message_id, callerAgent, cwd);
+                        // pln#562 step 4 — scope the ack to this assignment's claim so a
+                        // same-named sibling instance cannot consume the message.
+                        ackMessage(assignment.message_id, callerAgent, cwd, { claimId: assignment.claim_id });
                     }
                     catch { /* best-effort: don't fail the update if ack fails */ }
                 }
@@ -3666,7 +3990,11 @@ async function _executeMcpToolCallInner(payload) {
                 return { response: createToolErrorResponse('validation_error', 'Missing required argument: id') };
             }
             try {
-                const result = ackMessage(msgId, resolved.identity.agent_name, cwd);
+                // pln#562 step 4 — a dispatched instance (BRAINCLAW_CLAIM_ID) may only
+                // ack messages bound to its own claim.
+                const result = ackMessage(msgId, resolved.identity.agent_name, cwd, {
+                    claimId: process.env.BRAINCLAW_CLAIM_ID?.trim() || undefined,
+                });
                 appendAuditEntry({ actor: resolved.identity.agent_name, actor_id: resolved.identity.agent_id, action: 'update', item_id: result.id, item_type: 'message' }, cwd);
                 return {
                     response: toolResponse({
@@ -3768,13 +4096,15 @@ async function _executeMcpToolCallInner(payload) {
             const stepTextRaw = stepData.text ?? stepData.title ?? args.text;
             const stepText = typeof stepTextRaw === 'string' ? stepTextRaw.trim() : '';
             const stepAssignee = (stepData.assignee ?? args.assignee);
+            const stepEstimated = (stepData.estimated_effort ?? args.estimated_effort);
+            const stepActual = (stepData.actual_effort ?? args.actual_effort);
             if (!stepPlanId)
                 return { response: createToolErrorResponse('validation_error', 'Missing required argument: planId') };
             if (!stepText)
                 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: stepAssignee }, stepTargetCwd);
+                const result = addStepOp({ planId: stepPlanId, text: stepText, assignee: stepAssignee, estimatedEffort: stepEstimated, actualEffort: stepActual }, stepTargetCwd);
                 return {
                     response: toolResponse({
                         content: [{ type: 'text', text: `✔ Step added: [${result.stepId}] ${stepText} (${result.doneSteps}/${result.totalSteps} done)` }],
@@ -3855,6 +4185,8 @@ async function _executeMcpToolCallInner(payload) {
                     status: args.status,
                     text: args.text,
                     assignee: args.assignee,
+                    estimatedEffort: args.estimated_effort,
+                    actualEffort: args.actual_effort,
                 }, usTargetCwd);
                 const changes = [];
                 if (args.status)
@@ -3863,6 +4195,10 @@ async function _executeMcpToolCallInner(payload) {
                     changes.push('text updated');
                 if (args.assignee !== undefined)
                     changes.push(`assignee=${args.assignee || 'unassigned'}`);
+                if (args.estimated_effort !== undefined)
+                    changes.push(`estimate=${args.estimated_effort}`);
+                if (args.actual_effort !== undefined)
+                    changes.push(`actual=${args.actual_effort}`);
                 return {
                     response: toolResponse({
                         content: [{ type: 'text', text: `✔ Step updated: [${result.stepId}] ${changes.join(', ')} (${result.doneSteps}/${result.totalSteps} done)` }],
@@ -4290,11 +4626,11 @@ async function _executeMcpToolCallInner(payload) {
             if (sessionResult.auto_registered) {
                 warnings.push(`Agent '${sessionResult.agent}' was auto-registered (first use). Run \`brainclaw register-agent ${sessionResult.agent}\` to set capabilities and trust level.`);
             }
-            // Step 2: build context for requested scope. When intent='resume',
-            // auto-surface the memory delta since the previous session for the
-            // same agent — matches session-start.ts:85 pattern. Phase 4
-            // Sprint 1 Lane A step 5 (pln#390). Without this the resume intent
-            // was functionally identical to consult, defeating its purpose.
+            // Step 2: build context for requested scope. The "what's new" diff is
+            // surfaced for ALL intents (pln#390 regression fix): intent='resume'
+            // anchors it on the agent's previous session; every other intent gets
+            // the per-agent event-log-cursor diff computed inside buildContext
+            // (pln#542 — converged novelty mechanism, covers status transitions).
             let contextResult;
             try {
                 let sinceSession;
@@ -4308,6 +4644,8 @@ async function _executeMcpToolCallInner(payload) {
                     agent: sessionResult.agent,
                     cwd: targetCwd,
                     sinceSession,
+                    // ~4 chars/token: relevance-ranked fill up to the caller's budget.
+                    maxChars: workReq.budget_tokens ? workReq.budget_tokens * 4 : undefined,
                 });
             }
             catch { /* non-fatal — context failure should not block work */ }
@@ -4368,11 +4706,30 @@ async function _executeMcpToolCallInner(payload) {
                     text: w.text.slice(0, 80),
                     age_days: w.age_days,
                 }));
+                // pln#390 regression fix: the compact projection used to silently
+                // drop context_diff, defeating the diff-first contract. Keep a
+                // trimmed view (summary + counts + top-5 items, text capped).
+                const trimmedDiff = contextResult.context_diff
+                    ? {
+                        since: contextResult.context_diff.since,
+                        since_session: contextResult.context_diff.since_session,
+                        source: contextResult.context_diff.source,
+                        summary: contextResult.context_diff.summary,
+                        counts: contextResult.context_diff.counts,
+                        changed_items: (contextResult.context_diff.changed_items ?? [])
+                            .slice(0, 5)
+                            .map((item) => ({ ...item, text: item.text.slice(0, 120) })),
+                        ...(contextResult.context_diff.unseen_event_count !== undefined
+                            ? { unseen_event_count: contextResult.context_diff.unseen_event_count }
+                            : {}),
+                    }
+                    : undefined;
                 resultPayload = {
                     context_schema: contextResult.context_schema,
                     profile: contextResult.profile,
                     memory_version: contextResult.memory_version,
                     memory_density: contextResult.memory_density,
+                    context_diff: trimmedDiff ?? null,
                     plan_summary: planItems,
                     stale_warnings: staleTop3,
                     workflow_hints: (contextResult.workflow_hints ?? []).slice(0, 3),
@@ -4382,34 +4739,88 @@ 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.
+            // pln#513 step 1 / pln#557 step 3 — bootstrap hint. The original probe
+            // was a one-bit PROJECT.md stat(): false positive on a rich store
+            // without PROJECT.md (recommended from-scratch bootstrap over 17k
+            // events), eternal false negative on a fossil PROJECT.md. The composite
+            // assessment (assessBootstrapNeed: presence × mtime-vs-activity ×
+            // store density) adds a distinct 'refresh' verdict that maps to
+            // bclaw_bootstrap(refresh: true) — coordinate with the pln#514 step 1
+            // force-flag. 'bootstrap' keeps the shared empty-memory rule
+            // (resolveEmptyMemoryRecommendation): repo with content → extract via
+            // bclaw_bootstrap; greenfield → bootstrap loop. Both chainable.
             let bootstrapRecommended;
+            let bootstrapVerdict;
+            let bootstrapRefreshReason;
             let nextAction;
+            let emptyMemoryRec;
+            let storeDensity;
             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
+                const assessment = assessBootstrapNeed(targetCwd);
+                bootstrapVerdict = assessment.verdict;
+                bootstrapRecommended = assessment.verdict !== 'none';
+                storeDensity = assessment.store_density;
+                if (assessment.verdict === 'bootstrap') {
+                    emptyMemoryRec = resolveEmptyMemoryRecommendation(targetCwd);
+                    nextAction = emptyMemoryRec.mcp_next_action;
                 }
-                bootstrapRecommended = needsBootstrap;
-                if (needsBootstrap) {
-                    nextAction = "bclaw_coordinate(intent='ideate', preset='bootstrap')";
+                else if (assessment.verdict === 'refresh') {
+                    bootstrapRefreshReason = assessment.reasons[0];
+                    nextAction = 'bclaw_bootstrap(refresh: true)';
                 }
             }
             catch {
                 // Best-effort: never block bclaw_work on the probe.
             }
+            // Self-teaching affordances (pln#542): each response carries the
+            // recommended follow-up calls with exact shapes.
+            const nextActions = [];
+            if (bootstrapVerdict === 'bootstrap' && emptyMemoryRec) {
+                if (emptyMemoryRec.route === 'extract') {
+                    nextActions.push({ tool: 'bclaw_bootstrap', args: {}, when: `project vision is missing and the ${emptyMemoryRec.reason} — extract initial context, then chain ${emptyMemoryRec.chained_mcp_action} if the vision is still missing` });
+                }
+                else {
+                    nextActions.push({ tool: 'bclaw_coordinate', args: { intent: 'ideate', preset: 'bootstrap' }, when: `project vision is missing and the repo is greenfield — open a bootstrap loop before assuming context, then chain ${emptyMemoryRec.chained_mcp_action} once content exists` });
+                }
+            }
+            else if (bootstrapVerdict === 'refresh') {
+                nextActions.push({ tool: 'bclaw_bootstrap', args: { refresh: true }, when: bootstrapRefreshReason ?? 'PROJECT.md is missing or fossil relative to a mature store — refresh from existing memory, do not bootstrap from scratch' });
+            }
+            if (claimId) {
+                nextActions.push({ tool: 'bclaw_release_claim', args: { id: claimId, planStatus: 'done' }, when: 'implementation complete and committed' });
+            }
+            else if (workReq.intent === 'consult' || workReq.intent === 'resume') {
+                nextActions.push({ tool: 'bclaw_work', args: { intent: 'execute', scope: workReq.scope ?? '<scope>' }, when: 'ready to edit — claims the scope' });
+            }
+            // Solo-agent empty-store hint: the bootstrap recommendation covers
+            // vision; agents arriving on a freshly-initialised store also need a
+            // surface for *work* itself. Without this they reliably consult, see
+            // nothing, and stop — bclaw_create(entity='plan') is the missing
+            // affordance (2026-06-10 front-door audit). The store-density signal
+            // bumps to 'low' as soon as session_start lands a single event, so
+            // gate the hint directly on "no plans yet" — the actual condition
+            // the agent is in.
+            let noPlansYet = false;
+            try {
+                noPlansYet = loadState(targetCwd).plan_items.length === 0;
+            }
+            catch {
+                // loadState may fail on a brand-new store with no project.md yet;
+                // treat that as "no plans yet" — the next_action remains correct.
+                noPlansYet = true;
+            }
+            if (noPlansYet && (storeDensity === 'empty' || storeDensity === 'low')) {
+                nextActions.push({
+                    tool: 'bclaw_create',
+                    args: { entity: 'plan', input: { title: '<plan title>', steps: ['<first step>'] } },
+                    when: 'memory has no plans yet — once you know what you are doing, create a plan so progress is tracked',
+                });
+            }
+            const diffTotal = contextResult?.context_diff?.counts.total ?? 0;
+            if (useCompact && diffTotal > 0) {
+                nextActions.push({ tool: 'bclaw_context', args: { kind: 'memory' }, when: 'to read the full changed items behind context_diff' });
+            }
+            nextActions.push({ tool: 'bclaw_quick_capture', args: { text: '<finding>', type: '<decision|trap|constraint|note>' }, when: 'capture decisions/traps as you work' });
             const facadeResponse = {
                 status: 'ok',
                 intent: workReq.intent,
@@ -4421,15 +4832,23 @@ async function _executeMcpToolCallInner(payload) {
                 warnings,
                 duration_ms: Date.now() - startMs,
                 bootstrap_recommended: bootstrapRecommended,
+                bootstrap_verdict: bootstrapVerdict,
                 next_action: nextAction,
+                next_actions: nextActions,
             };
             const summaryParts = [`✔ bclaw_work [${workReq.intent}] session=${sessionResult.session_id}`];
             if (claimId)
                 summaryParts.push(`claim=${claimId} (${claimStatus})`);
+            if (contextResult?.context_diff && diffTotal > 0) {
+                summaryParts.push(`Δ since last look: ${contextResult.context_diff.summary}`);
+            }
             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 (bootstrapVerdict === 'bootstrap' && emptyMemoryRec) {
+                summaryParts.push(`💡 ${emptyMemoryRec.text}`);
+            }
+            else if (bootstrapVerdict === 'refresh') {
+                summaryParts.push(`💡 ${bootstrapRefreshReason ?? 'PROJECT.md is missing or fossil relative to a mature store'} → bclaw_bootstrap(refresh: true)`);
             }
             if (warnings.length > 0)
                 summaryParts.push(warnings.map((w) => `⚠ ${w}`).join('\n'));
@@ -5732,6 +6151,23 @@ async function _executeMcpToolCallInner(payload) {
             };
         }
         if (name === 'bclaw_loop') {
+            // pln#542: intent='open' is no longer exposed standalone over MCP — it
+            // creates a loop without dispatching the first turn (the documented
+            // anti-pattern, now removed instead of documented). Internal callers
+            // (bclaw_coordinate, CLI bootstrap) use core openLoop directly.
+            if (args?.intent === 'open') {
+                return {
+                    response: createToolErrorResponse('intent_not_exposed', "bclaw_loop(intent='open') is not exposed standalone: it creates a loop structure without dispatching any turn, so the work never starts. Use bclaw_coordinate(intent='review', open_loop=true, targetAgents=[…]) or bclaw_coordinate(intent='ideate') — they open the loop AND dispatch the first turn."),
+                };
+            }
+            // pln#562 step 4 — dispatching a turn hands work to another agent; gate
+            // it at the same trust bar as the other dispatch surfaces.
+            if (args?.intent === 'turn' && args?.dispatch === true) {
+                const resolved = ensureTrust(args, { nameField: 'agent', idField: 'agentId' }, 'trusted', cwd, connectionSessionId);
+                if (resolved.error) {
+                    return { response: createToolErrorResponse(resolved.error.kind, resolved.error.message, resolved.error.details) };
+                }
+            }
             const { handleBclawLoop } = await import('./loops-handlers.js');
             const targetCwd = resolveProjectCwd(args?.project, cwd);
             const result = handleBclawLoop({ args: args, cwd: targetCwd });
@@ -5825,9 +6261,19 @@ async function _executeMcpToolCallInner(payload) {
                 // this caps SIZE) so a verbose result set never overflows the MCP token
                 // cap and silently pushes the agent to the CLI (trp#449). Advertises
                 // has_more / next_offset / hint for explicit pagination.
+                // pln#542: budget_tokens lets the caller shrink the size cap further
+                // (~4 chars/token); it can only tighten, never exceed the default.
                 const offset = Math.max(0, Number(filter.offset) || 0);
-                const bounded = boundListResult(result, offset);
+                const budgetTokens = typeof args.budget_tokens === 'number' && args.budget_tokens > 0 ? args.budget_tokens : undefined;
+                const charBudget = budgetTokens ? Math.min(budgetTokens * 4, DEFAULT_FIND_CHAR_BUDGET) : DEFAULT_FIND_CHAR_BUDGET;
+                const bounded = boundListResult(result, offset, charBudget);
                 const warnings = collectLoadValidationWarnings(entity, targetCwd);
+                const nextActions = [
+                    { tool: 'bclaw_get', args: { entity, id: '<id from items>' }, when: 'to read one item in full' },
+                ];
+                if (bounded.has_more) {
+                    nextActions.push({ tool: 'bclaw_find', args: { entity, filter: { ...filter, offset: bounded.next_offset } }, when: 'to fetch the next page' });
+                }
                 // 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
@@ -5838,7 +6284,7 @@ async function _executeMcpToolCallInner(payload) {
                 return {
                     response: toolResponse({
                         content: [{ type: 'text', text: `✔ ${result.total} ${entity} item(s)${moreNote}` }],
-                        structuredContent: { ...bounded, warnings },
+                        structuredContent: { ...bounded, warnings, next_actions: nextActions },
                     }),
                 };
             }
@@ -5867,10 +6313,35 @@ async function _executeMcpToolCallInner(payload) {
                     };
                 }
                 const item = getEntity(entity, id, targetCwd);
+                // trp#449 class (pln#542): handoff snapshots embed an unbounded git
+                // diff — cap it (budget_tokens tightens, ~4 chars/token).
+                let boundedItem = item;
+                let diffTruncated = false;
+                const getBudgetTokens = typeof args.budget_tokens === 'number' && args.budget_tokens > 0 ? args.budget_tokens : undefined;
+                const getCharBudget = getBudgetTokens ? Math.min(getBudgetTokens * 4, DEFAULT_FIND_CHAR_BUDGET) : DEFAULT_FIND_CHAR_BUDGET;
+                if (entity === 'handoff' && item && typeof item === 'object') {
+                    const snapshot = item.snapshot;
+                    if (snapshot?.diff && snapshot.diff.length > getCharBudget) {
+                        diffTruncated = true;
+                        boundedItem = {
+                            ...item,
+                            snapshot: { ...snapshot, diff: `${snapshot.diff.slice(0, getCharBudget)}\n… [diff truncated to ${getCharBudget} chars]` },
+                        };
+                    }
+                    else {
+                        const note = handoffDiffPreviewNote(snapshot);
+                        if (snapshot?.diff && note) {
+                            boundedItem = {
+                                ...item,
+                                snapshot: { ...snapshot, diff: `${snapshot.diff}\n${note}` },
+                            };
+                        }
+                    }
+                }
                 return {
                     response: toolResponse({
                         content: [{ type: 'text', text: `✔ fetched ${entity} ${id}` }],
-                        structuredContent: { entity, item },
+                        structuredContent: { entity, item: boundedItem, ...(diffTruncated ? { diff_truncated: true } : {}) },
                     }),
                 };
             }
@@ -5881,25 +6352,43 @@ async function _executeMcpToolCallInner(payload) {
         if (name === 'bclaw_create') {
             try {
                 const entity = String(args.entity ?? '');
+                // Execution entities stay local: the signaling-only cross-project
+                // boundary applies to the canonical verbs too, not just legacy tools.
+                if (entity === 'claim' || entity === 'plan') {
+                    const crossProjectError = blockCrossProjectExecution(entity, args);
+                    if (crossProjectError)
+                        return { response: crossProjectError };
+                }
                 const rawData = (args.data ?? {});
                 const targetCwd = resolveProjectCwd(args.project, cwd);
                 // Auto-fill identity fields. Without this, a caller who omits author/agent
                 // creates a schema-invalid record that is silently dropped on read and
-                // GC'd from disk on the next mutation. Fallback chain:
-                // resolved MCP identity → args.agent → 'unknown'.
+                // GC'd from disk on the next mutation.
                 // Identity is resolved against the SOURCE cwd (the agent's own
                 // project/registry), not the target — an agent doesn't need to be
-                // registered in the target project to write into it.
-                const { agent_name, agent_id } = resolveCanonicalAuthor(args, cwd, connectionSessionId);
+                // registered in the target project to write into it. An explicitly
+                // supplied data.author is honored as content-level attribution
+                // (cross-project signaling writers may not be registered locally);
+                // when author is MISSING, resolution is mandatory and failure is a
+                // hard validation_error (pln#562 step 3) — never author:'unknown'.
                 const data = { ...rawData };
-                if (data.author === undefined)
+                let actor = typeof data.author === 'string' ? data.author : undefined;
+                let actorId = typeof data.agent_id === 'string' ? data.agent_id : undefined;
+                if (data.author === undefined) {
+                    const { agent_name, agent_id } = resolveCanonicalAuthor(args, cwd, connectionSessionId);
                     data.author = agent_name;
-                if (data.agent === undefined)
-                    data.agent = agent_name;
-                if (data.agent_id === undefined && agent_id)
-                    data.agent_id = agent_id;
+                    if (data.agent === undefined)
+                        data.agent = agent_name;
+                    if (data.agent_id === undefined && agent_id)
+                        data.agent_id = agent_id;
+                    actor = agent_name;
+                    actorId = agent_id;
+                }
+                else if (data.agent === undefined) {
+                    data.agent = data.author;
+                }
                 const result = createEntity(entity, data, targetCwd);
-                appendAuditEntry({ actor: agent_name, ...(agent_id ? { actor_id: agent_id } : {}), action: 'create', item_id: result.id, item_type: entity }, targetCwd);
+                appendAuditEntry({ actor: actor ?? 'unknown', ...(actorId ? { actor_id: actorId } : {}), action: 'create', item_id: result.id, item_type: entity }, targetCwd);
                 return {
                     response: toolResponse({
                         content: [{ type: 'text', text: `✔ created ${entity} ${result.id}` }],
@@ -5954,6 +6443,13 @@ async function _executeMcpToolCallInner(payload) {
         if (name === 'bclaw_transition') {
             try {
                 const entity = String(args.entity ?? '');
+                // Same signaling-only boundary as bclaw_create: no remote lifecycle
+                // driving of execution entities through the canonical grammar.
+                if (entity === 'claim' || entity === 'plan') {
+                    const crossProjectError = blockCrossProjectExecution(entity, args);
+                    if (crossProjectError)
+                        return { response: crossProjectError };
+                }
                 const id = String(args.id ?? '');
                 const to = String(args.to ?? '');
                 const reason = args.reason;