brainclaw 1.8.0 → 1.9.0

package/dist/commands/init.js

@@ -16,8 +16,11 @@ import { BRAINCLAW_EXCLUSIVE_DIRECTORIES, describeAutoConfigWrite, ensureAgentFi
 import { detectAiAgent, detectWslEnvironment } from '../core/ai-agent-detection.js';
 import { buildAiSurfaceInventory, renderAiSurfaceUsageHints } from '../core/ai-surface-inventory.js';
 import { ensureUserStore, hasCompletedSetup } from '../core/setup-state.js';
+import { resolveEmptyMemoryRecommendation } from '../core/setup-flow.js';
 import { writeDetectedAgentExport } from './export.js';
 import { writeDetectedAgentHooks } from './hooks.js';
+import { checkGitPresence, runGlobalInstall } from './setup.js';
+import { createBackup, BackupError } from '../core/upgrades/backup.js';
 import { ConfigSchema } from '../core/schema.js';
 export async function runInit(options = {}) {
     const cwd = options.cwd ?? process.cwd();
@@ -29,6 +32,14 @@ export async function runInit(options = {}) {
     if (!hasCompletedSetup()) {
         ensureUserStore();
     }
+    // Git-presence gate, aligned with `brainclaw setup`: agent-first onboarding
+    // assumes git for memory versioning + post-merge hooks. Allow override via
+    // BRAINCLAW_SKIP_REPO_ANALYSIS=1 for tests that exercise non-git fixtures.
+    if (process.env.BRAINCLAW_SKIP_REPO_ANALYSIS !== '1' && !checkGitPresence()) {
+        console.error('brainclaw init needs git to work.');
+        console.error('Install git from https://git-scm.com and try again.');
+        process.exit(1);
+    }
     if (containingMemoryStore) {
         console.error(`Error: cannot run \`brainclaw init\` from inside an existing project memory store (${containingMemoryStore}).`);
         console.error('Run `brainclaw init` from the project root directory instead.');
@@ -61,6 +72,29 @@ export async function runInit(options = {}) {
     const storageDir = resolveStorageDir(options.storageDir);
     const projectMemoryExists = memoryExists(cwd);
     const existingConfig = projectMemoryExists ? loadExistingConfig(cwd, storageDir) : undefined;
+    // --force backup gate: feedback_no_init_force (June 2026) entered the code.
+    // Before rebuilding identity fields on top of an existing store, take a
+    // sibling backup so curator personalisations (redaction patterns, claim
+    // TTL, governance, sensitive_paths) can always be recovered even if the
+    // merge below regresses or the agent ran `init --force` by mistake.
+    let forceBackupPath;
+    if (options.force && projectMemoryExists) {
+        try {
+            const handle = createBackup({
+                storePath: path.join(cwd, storageDir),
+                note: 'init --force pre-reconstruction snapshot',
+                storeSchemaVersion: existingConfig ? String(existingConfig.schema_version) : null,
+            });
+            forceBackupPath = handle.backupPath;
+        }
+        catch (err) {
+            const reason = err instanceof BackupError
+                ? `${err.code}: ${err.message}`
+                : err instanceof Error ? err.message : String(err);
+            console.error(`Error: --force backup failed (${reason}). Aborting to preserve the existing store. Re-run without --force, or move the store aside manually.`);
+            process.exit(1);
+        }
+    }
     const topology = resolveTopology(options.topology, existingConfig?.topology);
     const ignoreStrategy = resolveIgnoreStrategy(topology, existingConfig?.ignore_strategy);
     const skipAgentBootstrap = options.skipAgentBootstrap === true || process.env.BRAINCLAW_SKIP_AGENT_BOOTSTRAP === '1';
@@ -87,7 +121,9 @@ export async function runInit(options = {}) {
         ? registerAgentIdentity({
             agentName: detectedAi.name,
             kind: detectedAi.kind,
-            trustLevel: detectedAi.trust_level,
+            // pln#562 step 2 — auto-registration never exceeds contributor;
+            // elevation is an explicit curator act (set-trust / register-agent).
+            trustLevel: 'contributor',
             cwd,
             preferredDirName: storageDir,
         })
@@ -123,7 +159,15 @@ export async function runInit(options = {}) {
         storageDir,
         topology,
         ignoreStrategy,
-        existingConfig: options.force ? undefined : existingConfig,
+        // --force rebuilds identity (project_id, agent, topology, storage_dir)
+        // but merges through existingConfig so curator personalisations
+        // (redaction patterns, governance, claims TTL, sensitive_paths,
+        // cross_project_links, custom markdown caps) survive the reset.
+        // The original `force ? undefined` path wiped these silently —
+        // discovered when feedback_no_init_force was promoted from a memory
+        // habit to a tracked regression.
+        existingConfig,
+        defaultJournalMode: !projectMemoryExists,
         compact: options.compact === true,
     });
     if (detectedAi && isAgentIntegrationName(detectedAi.name)) {
@@ -141,6 +185,19 @@ export async function runInit(options = {}) {
                 .filter((hook) => hook.relativePath !== detectedExport?.relativePath))
         : [];
     const detectedAutoConfig = detectedAi ? writeDetectedAgentAutoConfig(detectedAi.name, cwd) : [];
+    // Per-agent slice of machine prerequisites (the same writes setup performs
+    // globally, but scoped to the detected agent). This makes `init` the single
+    // entry point for the carte-blanche / fresh-repo case: an agent-first
+    // bootstrap no longer needs a separate `brainclaw setup` shell-out + session
+    // reload. Idempotent — each ensure* function returns "skipped" when the
+    // agent's user-scope config doesn't exist.
+    const skipMachinePrereqs = options.skipMachinePrereqs === true
+        || skipAgentBootstrap
+        || testMode
+        || process.env.BRAINCLAW_INIT_SKIP_MACHINE_PREREQS === '1';
+    const machinePrereqsWritten = detectedAi && !skipMachinePrereqs
+        ? safeRunMachinePrereqs(detectedAi.name)
+        : [];
     // Register in global project registry
     try {
         const entry = scanProject(cwd);
@@ -177,7 +234,10 @@ export async function runInit(options = {}) {
     if (projectMemoryExists) {
         console.log(`✔ Refreshed existing project memory in ${storageDir}/`);
         if (options.force) {
-            console.log('✔ Existing memory preserved; rebuilt managed configuration and agent integration files from defaults');
+            if (forceBackupPath) {
+                console.log(`✔ Pre-reconstruction backup at ${forceBackupPath} (rollback: brainclaw upgrade --rollback)`);
+            }
+            console.log('✔ Existing memory preserved; rebuilt managed identity and refreshed agent integration files (customisations merged through)');
         }
         else {
             console.log('✔ Existing memory preserved; refreshed managed configuration and agent integration files');
@@ -192,6 +252,12 @@ export async function runInit(options = {}) {
     if (registeredAiAgent) {
         console.log(`✔ AI agent detected: ${registeredAiAgent.agent_name} [${detectedAi.detection_source}] (${registeredAiAgent.agent_id})`);
     }
+    if (machinePrereqsWritten.length > 0) {
+        console.log(`\u2714 Machine prerequisites for ${detectedAi.name}:`);
+        for (const filePath of machinePrereqsWritten) {
+            console.log(`  - ${filePath}`);
+        }
+    }
     if (detectedExport) {
         console.log(`\u2714 Agent instructions written to ${detectedExport.relativePath} (${detectedExport.created ? 'created' : 'updated'})`);
     }
@@ -265,25 +331,36 @@ export async function runInit(options = {}) {
     // Install post-merge hook for auto-release of claims after merge
     installPostMergeHookIfMissing(cwd);
     if (!testMode) {
-        const onboardingPreflight = runBootstrapProfile({ cwd, refresh: true });
+        // Shared empty-memory rule (see docs/concepts/workspace-bootstrapping.md):
+        // repo with content → bclaw_bootstrap extraction; greenfield → bootstrap
+        // loop. The brownfield preflight scan is skipped on greenfield — there is
+        // nothing to harvest yet.
+        const emptyMemoryRec = resolveEmptyMemoryRecommendation(cwd);
         console.log('');
-        console.log('Onboarding preflight:');
-        for (const line of renderBootstrapSummary(onboardingPreflight).split('\n')) {
-            console.log(`  ${line}`);
-        }
-        if (onboardingPreflight.importPlan.suggestion_count > 0) {
-            console.log('');
-            console.log(`Next step: run 'brainclaw bootstrap --apply' to import ${onboardingPreflight.importPlan.suggestion_count} suggested item(s) into canonical memory.`);
-            console.log(`Rollback: run 'brainclaw bootstrap --uninstall' to deactivate the last bootstrap-managed import.`);
-        }
-        if ((onboardingPreflight.importPlan.interview?.question_count ?? 0) > 0) {
-            console.log('');
-            console.log(`Interview: run 'brainclaw bootstrap --interview --audience cli' for terminal agents or '--audience ide_chat' for IDE chat agents.`);
-            console.log(`Apply confirmed answers: write a JSON answers file and run 'brainclaw bootstrap --answers-file <path> --apply'.`);
+        if (emptyMemoryRec.route === 'ideate') {
+            console.log(`Onboarding: ${emptyMemoryRec.text}`);
         }
-        else if ((onboardingPreflight.profile.gaps?.length ?? 0) > 0) {
-            console.log('');
-            console.log(`Next step: review the onboarding gaps, then use 'brainclaw bootstrap --json' as the basis for an interview/import flow.`);
+        else {
+            const onboardingPreflight = runBootstrapProfile({ cwd, refresh: true });
+            console.log('Onboarding preflight:');
+            console.log(`  ${emptyMemoryRec.text}`);
+            for (const line of renderBootstrapSummary(onboardingPreflight).split('\n')) {
+                console.log(`  ${line}`);
+            }
+            if (onboardingPreflight.importPlan.suggestion_count > 0) {
+                console.log('');
+                console.log(`Next step: run 'brainclaw bootstrap --apply' to import ${onboardingPreflight.importPlan.suggestion_count} suggested item(s) into canonical memory.`);
+                console.log(`Rollback: run 'brainclaw bootstrap --uninstall' to deactivate the last bootstrap-managed import.`);
+            }
+            if ((onboardingPreflight.importPlan.interview?.question_count ?? 0) > 0) {
+                console.log('');
+                console.log(`Interview: run 'brainclaw bootstrap --interview --audience cli' for terminal agents or '--audience ide_chat' for IDE chat agents.`);
+                console.log(`Apply confirmed answers: write a JSON answers file and run 'brainclaw bootstrap --answers-file <path> --apply'.`);
+            }
+            else if ((onboardingPreflight.profile.gaps?.length ?? 0) > 0) {
+                console.log('');
+                console.log(`Next step: review the onboarding gaps, then use 'brainclaw bootstrap --json' as the basis for an interview/import flow.`);
+            }
         }
     }
     console.log('');
@@ -293,7 +370,16 @@ export async function runInit(options = {}) {
     else {
         console.log(`Tip: run 'brainclaw init' again later to refresh the detected agent's integration files on this project.`);
     }
-    console.log(`Tip: run 'brainclaw context --json' to load the shared memory into your agent session.`);
+    console.log(`Tip: in an agent session, call the bclaw_work MCP tool (intent: "consult") to load the shared memory; from a terminal, 'brainclaw context --json' does the same.`);
+}
+function safeRunMachinePrereqs(agentName) {
+    try {
+        return runGlobalInstall([agentName]);
+    }
+    catch {
+        // Non-fatal: machine-scope writes are best-effort, never block init.
+        return [];
+    }
 }
 function installPostMergeHookIfMissing(cwd) {
     try {
@@ -483,6 +569,12 @@ function buildInitConfig(input) {
         storageDir: input.storageDir,
         topology: input.topology,
         ignoreStrategy: input.ignoreStrategy,
+        // Solo-agent fresh default: the human running init is the default curator.
+        // Without it, approval_policy=review + curators=[] = every candidate sits
+        // in pending forever — a surprise the 2026-06-10 front-door audit flagged.
+        // mergeConfigWithDefaults preserves any explicit curators list on an
+        // existing store, so this only takes effect on fresh installs.
+        curatorName: input.currentAgent.name,
     });
     const config = input.existingConfig
         ? mergeConfigWithDefaults(input.existingConfig, fallbackConfig)
@@ -512,6 +604,16 @@ function buildInitConfig(input) {
             max_items_per_section: Math.min(markdown.max_items_per_section, 20),
         };
     }
+    // pln#567 (decision A) — the event journal is ON by default for projects
+    // created through init. Set HERE, never in defaultConfig:
+    // createTestWorkspace builds its config straight from defaultConfig, so a dual
+    // default there would make the whole core suite dual-write (trp_65176454).
+    // Existing stores keep their current value, including unset legacy configs:
+    // `migrate --enable-journal` is the explicit path that turns them on and
+    // backfills genesis before future dual-writes depend on the journal.
+    if (input.defaultJournalMode === true && config.store?.journal?.mode === undefined) {
+        config.store = { ...config.store, journal: { ...config.store?.journal, mode: 'dual' } };
+    }
     return config;
 }
 function mergeConfigWithDefaults(existingConfig, fallbackConfig) {

package/dist/commands/loops-handlers.js

@@ -284,6 +284,7 @@ export function handleBclawLoop(options) {
                         input: req.input,
                         dispatch: req.dispatch,
                         assignment_id: req.assignment_id,
+                        claim_id: req.claim_id,
                         actor,
                     }, options.cwd);
                     const newEvents = findNewLoopEvents(loop.id, beforeEvents, options.cwd);
@@ -309,6 +310,9 @@ export function handleBclawLoop(options) {
                             : undefined,
                         actor,
                         caller_agent_id: req.agentId,
+                        // pln#562 step 4 — a dispatched instance proves itself via its
+                        // claim env; claim-bound slots reject same-named siblings.
+                        caller_claim_id: process.env.BRAINCLAW_CLAIM_ID?.trim() || undefined,
                     }, options.cwd);
                     const newEvents = findNewLoopEvents(loop.id, beforeEvents, options.cwd);
                     return successResponse('complete_turn', { loop, next_expected: computeNextExpected(loop) }, [loopArtifactEntry(loop.id), ...loopEventArtifacts(newEvents)], [sideEffectUpdate('loop', loop.id), ...loopEventSideEffects(newEvents)], [], Date.now() - startMs, summarizeLoop(loop));

package/dist/commands/mcp-read-handlers.js

@@ -1,6 +1,6 @@
 import { applyBootstrapImport, renderBootstrapInterview, renderBootstrapSummary, runBootstrapProfile, uninstallBootstrapImport } from '../core/bootstrap.js';
 import { buildAgentToolingContext, renderAgentToolingSummary } from '../core/agent-context.js';
-import { buildCoordinationSnapshot } from '../core/coordination.js';
+import { buildCoordinationSnapshot, buildCrossProjectSnapshot } from '../core/coordination.js';
 import { scanDescendantPlans } from './list-plans.js';
 import { buildContext } from '../core/context.js';
 import { buildExecutionContext, renderExecutionContextSummary } from '../core/execution-context.js';
@@ -13,6 +13,7 @@ import { listClaims, assessClaimLiveness } from '../core/claims.js';
 import { listAssignments } from '../core/assignments.js';
 import { listAgentRuns } from '../core/agentruns.js';
 import { reconcileAgentRun } from '../core/agentrun-reconciler.js';
+import { isObserverMode } from '../core/observer-mode.js';
 import { getDispatchStatus } from '../core/dispatch-status.js';
 import { listActionRequired } from '../core/actions.js';
 import { queryRuntimeEvents } from '../core/events.js';
@@ -35,6 +36,8 @@ import { listAvailableProjects, switchProject } from './switch.js';
 import { resolveEffectiveCwd } from '../core/store-resolution.js';
 import { resolveProjectCwd } from '../core/cross-project.js';
 import { readUnseenEvents, buildNotificationSummary } from '../core/event-log.js';
+import { boundListResult, DEFAULT_FIND_CHAR_BUDGET } from '../core/entity-operations.js';
+import { handoffDiffPreviewNote } from '../core/handoff-snapshot.js';
 import { BootstrapInterviewAnswerSchema, AssignmentStatusSchema, AgentRunStatusSchema, AgentRunTransportSchema, ActionRequiredStatusSchema, ActionRequiredKindSchema } from '../core/schema.js';
 import { SCHEMA_VERSION, createToolErrorResponse, normaliseFormat, renderContextForMcp, } from './mcp.js';
 function normalizeBootstrapInterviewAnswersArg(value) {
@@ -60,6 +63,33 @@ function normalizeBootstrapInterviewAudienceArg(value) {
     }
     return 'any';
 }
+/**
+ * trp#449 class (pln#542): bound an arbitrary object payload by repeatedly
+ * halving its largest array field until the serialized size fits the budget.
+ * Returns the bounded payload plus a per-field omitted count so the caller
+ * can advertise what was dropped.
+ */
+function boundObjectArrays(payload, charBudget) {
+    const omitted = {};
+    let current = { ...payload };
+    while (JSON.stringify(current).length > charBudget) {
+        let largestKey;
+        let largestLen = 1;
+        for (const [key, value] of Object.entries(current)) {
+            if (Array.isArray(value) && value.length > largestLen) {
+                largestKey = key;
+                largestLen = value.length;
+            }
+        }
+        if (!largestKey)
+            break;
+        const arr = current[largestKey];
+        const newLen = Math.max(1, Math.floor(arr.length / 2));
+        omitted[largestKey] = (omitted[largestKey] ?? 0) + (arr.length - newLen);
+        current = { ...current, [largestKey]: arr.slice(0, newLen) };
+    }
+    return { payload: current, omitted };
+}
 function getReviewAssignee(tags) {
     for (const tag of tags) {
         if (tag.startsWith('assignee:')) {
@@ -78,12 +108,19 @@ export function handleMcpReadToolCall(name, args = {}, context = {}) {
     // workspace store-chain children. Throws on unknown project — surfaces
     // visibly as a tool error rather than silently falling back to the
     // current project, which would mislead the caller.
+    // Precedence rule: once routing succeeds, per-handler "project as filter"
+    // logic is skipped (routing already scopes to the right store) — pln#359.
     const projectArg = args.project;
     const targetProjectArg = name === 'bclaw_switch' ? undefined : projectArg;
+    let projectRoutingApplied = false;
     if (targetProjectArg) {
         cwd = resolveProjectCwd(targetProjectArg, cwd);
+        projectRoutingApplied = true;
     }
     if (name === 'bclaw_get_context') {
+        // pln#542: budget_tokens caps the relevance-ranked fill (~4 chars/token).
+        // Explicit maxChars wins when both are given.
+        const budgetTokens = typeof args.budget_tokens === 'number' && args.budget_tokens > 0 ? args.budget_tokens : undefined;
         const result = buildContext({
             target: args.path,
             project: targetProjectArg,
@@ -93,7 +130,7 @@ export function handleMcpReadToolCall(name, args = {}, context = {}) {
             profile: args.profile,
             includePending: args.includePending,
             maxItems: args.maxItems,
-            maxChars: args.maxChars,
+            maxChars: args.maxChars ?? (budgetTokens ? budgetTokens * 4 : undefined),
             digest: args.digest,
             sinceSession: args.since_session,
             bootstrap: args.bootstrap,
@@ -133,10 +170,22 @@ export function handleMcpReadToolCall(name, args = {}, context = {}) {
             suggestions.push('\n💡 Tip: Use bclaw_get_capabilities, bclaw_list_tools, or bclaw_search_tools for detailed discovery');
             enrichedContent = content + suggestions.join('\n');
         }
-        // Check for unseen events from other agents
-        const agentName = args.agent ?? resolveCurrentAgentName(cwd);
-        const unseenEvents = readUnseenEvents(agentName, cwd);
-        const notifications = buildNotificationSummary(unseenEvents);
+        // Unseen-event notifications. When buildContext already computed the
+        // event-cursor diff (the converged novelty mechanism, pln#542), reuse its
+        // histogram — the cursor was advanced by that read, so a second
+        // readUnseenEvents would observe nothing.
+        let notifications;
+        let unseenEventCount;
+        if (result.context_diff?.source === 'event_cursor') {
+            notifications = result.context_diff.event_summary;
+            unseenEventCount = result.context_diff.unseen_event_count;
+        }
+        else {
+            const agentName = args.agent ?? resolveCurrentAgentName(cwd);
+            const unseenEvents = readUnseenEvents(agentName, cwd);
+            notifications = buildNotificationSummary(unseenEvents);
+            unseenEventCount = unseenEvents.length;
+        }
         return {
             content: [{ type: 'text', text: enrichedContent || 'No relevant memory found.' }],
             structuredContent: {
@@ -151,7 +200,7 @@ export function handleMcpReadToolCall(name, args = {}, context = {}) {
                     name: tool.name,
                     type: tool.type,
                 })),
-                ...(notifications ? { pending_notifications: notifications, unseen_event_count: unseenEvents.length } : {}),
+                ...(notifications ? { pending_notifications: notifications, unseen_event_count: unseenEventCount } : {}),
             },
         };
     }
@@ -197,12 +246,38 @@ export function handleMcpReadToolCall(name, args = {}, context = {}) {
                 lines.push(`Suggestion: ${suggestion}`);
             }
         }
-        if (handoff.snapshot?.diff) {
-            lines.push('', 'Uncommitted Git Diff:', handoff.snapshot.diff);
+        // trp#449 class (pln#542): the embedded git diff is unbounded — cap it so
+        // a large handoff snapshot never overflows the MCP token budget.
+        // budget_tokens tightens the cap (~4 chars/token).
+        const handoffBudgetTokens = typeof args.budget_tokens === 'number' && args.budget_tokens > 0 ? args.budget_tokens : undefined;
+        const diffCharBudget = handoffBudgetTokens ? Math.min(handoffBudgetTokens * 4, DEFAULT_FIND_CHAR_BUDGET) : DEFAULT_FIND_CHAR_BUDGET;
+        let boundedHandoff = handoff;
+        let diffTruncated = false;
+        if (handoff.snapshot?.diff && handoff.snapshot.diff.length > diffCharBudget) {
+            diffTruncated = true;
+            boundedHandoff = {
+                ...handoff,
+                snapshot: {
+                    ...handoff.snapshot,
+                    diff: `${handoff.snapshot.diff.slice(0, diffCharBudget)}\n… [diff truncated to ${diffCharBudget} chars — read the worktree branch for the full diff]`,
+                },
+            };
+        }
+        if (boundedHandoff.snapshot?.diff) {
+            lines.push('', 'Uncommitted Git Diff:', boundedHandoff.snapshot.diff);
+            // pln#569 — the inline diff is a capped preview when a digest is present;
+            // tell the reader the full diff lives on the worktree branch.
+            const note = handoffDiffPreviewNote(boundedHandoff.snapshot);
+            if (!diffTruncated && note)
+                lines.push(note);
         }
         return {
             content: [{ type: 'text', text: lines.join('\n') }],
-            structuredContent: { handoff, schema_version: SCHEMA_VERSION },
+            structuredContent: {
+                handoff: boundedHandoff,
+                ...(diffTruncated ? { diff_truncated: true } : {}),
+                schema_version: SCHEMA_VERSION,
+            },
         };
     }
     if (name === 'bclaw_bootstrap') {
@@ -210,6 +285,23 @@ export function handleMcpReadToolCall(name, args = {}, context = {}) {
         if (args.apply && args.uninstall) {
             throw new Error('bclaw_bootstrap does not allow apply and uninstall at the same time.');
         }
+        // Mirror the CLI confirmAction gate: apply/uninstall mutate canonical
+        // memory, so they refuse without an explicit yes:true instead of relying
+        // on the host honouring the headlessApproval annotation.
+        if ((args.apply || args.uninstall) && args.yes !== true) {
+            const action = args.uninstall ? 'uninstall' : 'apply';
+            return {
+                content: [{
+                        type: 'text',
+                        text: `bclaw_bootstrap ${action} modifies canonical memory and requires explicit confirmation. Confirm with the user, then re-call with yes: true. No changes were made.`,
+                    }],
+                structuredContent: {
+                    confirmation_required: true,
+                    action,
+                    schema_version: SCHEMA_VERSION,
+                },
+            };
+        }
         if (args.uninstall) {
             const result = uninstallBootstrapImport(cwd);
             const text = !result.receipt
@@ -371,11 +463,34 @@ export function handleMcpReadToolCall(name, args = {}, context = {}) {
                 return !plan || plan.status === 'todo';
             }).length
             : 0;
+        // pln#559 step 3 — attention_required is now the FULL composite the
+        // Attention section already displays in the extension: pending actions
+        // + non-auto (human-review) candidates + blocked assignments + stale
+        // runs. The 2026-06-10 calibration: the badge previously read only
+        // pendingActions and chronically undercounted while the Attention
+        // section showed N >> badge. The badge must NEVER be smaller than the
+        // section header it represents.
+        const pendingCandidates = listCandidates('pending', cwd);
+        const pendingHumanCandidates = pendingCandidates.filter((c) => resolvedSource(c) !== 'auto');
+        const allAssignments = listAssignments(cwd);
+        const blockedAssignments = allAssignments.filter((a) => a.status === 'blocked');
+        const allRuns = listAgentRuns(cwd);
+        const staleRuns = allRuns.filter((r) => r.status === 'blocked' || r.status === 'waiting_input' || r.status === 'failed');
+        const attentionRequiredComposite = pendingActions.length +
+            pendingHumanCandidates.length +
+            blockedAssignments.length +
+            staleRuns.length;
         const summary = {
             project_id: config.project_id,
             agent,
             current_host: currentHost,
-            attention_required: pendingActions.length,
+            attention_required: attentionRequiredComposite,
+            attention_breakdown: {
+                pending_actions: pendingActions.length,
+                pending_human_candidates: pendingHumanCandidates.length,
+                blocked_assignments: blockedAssignments.length,
+                stale_runs: staleRuns.length,
+            },
             in_progress: activeClaims.length,
             plans: {
                 in_progress: state.plan_items.filter((p) => p.status === 'in_progress').length,
@@ -491,9 +606,22 @@ export function handleMcpReadToolCall(name, args = {}, context = {}) {
                 lines.push(`- ${other.name}: ${other.claim_count} claim(s) on ${other.scopes.join(', ')}`);
             }
         }
+        // trp#449 class (pln#542): the board aggregates many unbounded arrays —
+        // bound the structured payload by size. budget_tokens tightens the cap.
+        const boardBudgetTokens = typeof args.budget_tokens === 'number' && args.budget_tokens > 0 ? args.budget_tokens : undefined;
+        const boardCharBudget = boardBudgetTokens ? Math.min(boardBudgetTokens * 4, DEFAULT_FIND_CHAR_BUDGET) : DEFAULT_FIND_CHAR_BUDGET;
+        const { payload: boundedBoard, omitted } = boundObjectArrays(board, boardCharBudget);
         return {
             content: [{ type: 'text', text: lines.join('\n') }],
-            structuredContent: { ...board },
+            structuredContent: {
+                ...boundedBoard,
+                ...(Object.keys(omitted).length > 0
+                    ? {
+                        omitted_for_size: omitted,
+                        hint: `Payload size-bounded: ${Object.entries(omitted).map(([k, n]) => `${n} ${k}`).join(', ')} omitted. Use bclaw_find(entity=…) with filters to read the full lists.`,
+                    }
+                    : {}),
+            },
         };
     }
     if (name === 'bclaw_search') {
@@ -512,10 +640,29 @@ export function handleMcpReadToolCall(name, args = {}, context = {}) {
         });
         const total = allResults.length;
         const page = allResults.slice(offset, offset + limit);
-        const lines = page.map((result) => `[${result.id}] (${result.section}) score=${result.score.toFixed(2)}: ${result.text.slice(0, 120)}`);
+        // trp#449 class — bound the page by size (pln#542). budget_tokens tightens
+        // the cap (~4 chars/token); the default mirrors bclaw_find's budget.
+        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({ entity: 'search_result', total, items: page }, offset, charBudget);
+        const lines = bounded.items.map((result) => `[${result.id}] (${result.section}) score=${result.score.toFixed(2)}: ${result.text.slice(0, 120)}`);
+        const nextActions = bounded.has_more
+            ? [{ tool: 'bclaw_search', args: { query, offset: bounded.next_offset, limit }, when: 'to fetch the next page' }]
+            : [];
         return {
-            content: [{ type: 'text', text: page.length > 0 ? lines.join('\n') : 'No results found.' }],
-            structuredContent: { total, offset, limit, results: page },
+            content: [{ type: 'text', text: bounded.items.length > 0 ? lines.join('\n') : 'No results found.' }],
+            structuredContent: {
+                total,
+                offset,
+                limit,
+                results: bounded.items,
+                returned: bounded.returned,
+                has_more: bounded.has_more,
+                ...(bounded.next_offset !== undefined ? { next_offset: bounded.next_offset } : {}),
+                ...(bounded.omitted_for_size ? { omitted_for_size: bounded.omitted_for_size } : {}),
+                ...(bounded.hint ? { hint: bounded.hint } : {}),
+                next_actions: nextActions,
+            },
         };
     }
     if (name === 'bclaw_estimation_report') {
@@ -563,7 +710,10 @@ export function handleMcpReadToolCall(name, args = {}, context = {}) {
             const assignee = String(args.assignee).toLowerCase();
             plans = plans.filter((plan) => plan.assignee?.toLowerCase() === assignee);
         }
-        if (args.project) {
+        if (args.project && !projectRoutingApplied) {
+            // Only filter by plan.project metadata when routing was NOT applied.
+            // When routing succeeded, cwd is already scoped to the target project store,
+            // so filtering by plan.project label would incorrectly narrow results.
             const project = String(args.project).toLowerCase();
             plans = plans.filter((plan) => plan.project?.toLowerCase() === project);
         }
@@ -863,22 +1013,27 @@ export function handleMcpReadToolCall(name, args = {}, context = {}) {
         // committed but never called bclaw_assignment_update) and surfaces
         // delivered_but_unverified for spawns past the 60s grace with no
         // life-sign — see runtime_note run_77e65e77 for the empirical case.
-        try {
-            if (runId) {
-                reconcileAgentRun(runId, cwd);
-            }
-            else if (assignmentId) {
-                for (const run of listAgentRuns(cwd, { assignment_id: assignmentId })) {
-                    reconcileAgentRun(run.id, cwd);
+        // Observer mode (BRAINCLAW_OBSERVER=1) suppresses this pre-read sweep —
+        // a dashboard fetching assignment events must not be allowed to transition
+        // agent_run records as a side effect of the read.
+        if (!isObserverMode()) {
+            try {
+                if (runId) {
+                    reconcileAgentRun(runId, cwd);
                 }
-            }
-            else if (claimId) {
-                for (const run of listAgentRuns(cwd, { claim_id: claimId })) {
-                    reconcileAgentRun(run.id, cwd);
+                else if (assignmentId) {
+                    for (const run of listAgentRuns(cwd, { assignment_id: assignmentId })) {
+                        reconcileAgentRun(run.id, cwd);
+                    }
+                }
+                else if (claimId) {
+                    for (const run of listAgentRuns(cwd, { claim_id: claimId })) {
+                        reconcileAgentRun(run.id, cwd);
+                    }
                 }
             }
+            catch { /* defensive: never block events query on reconcile failure */ }
         }
-        catch { /* defensive: never block events query on reconcile failure */ }
         let events = queryRuntimeEvents({
             ...(id ? { id } : {}),
             ...(assignmentId ? { assignment_id: assignmentId } : {}),
@@ -1601,6 +1756,17 @@ export function handleMcpReadToolCall(name, args = {}, context = {}) {
                 return handleMcpReadToolCall('bclaw_get_agent_board', args, context);
             case 'board_summary':
                 return handleMcpReadToolCall('bclaw_get_agent_board_summary', args, context);
+            case 'cross_project': {
+                // pln#558 step 3 — lightweight endpoint for the VS Code extension's
+                // SYSTEM section: returns linked_projects + incoming_signals only,
+                // so the dashboard no longer pulls the full coordination snapshot
+                // just to render two summary lists.
+                const snap = buildCrossProjectSnapshot(cwd);
+                return {
+                    content: [{ type: 'text', text: JSON.stringify(snap, null, 2) }],
+                    structuredContent: snap,
+                };
+            }
             case 'delta': {
                 const since = args.since;
                 if (typeof since !== 'string' || !since) {
@@ -1609,7 +1775,7 @@ export function handleMcpReadToolCall(name, args = {}, context = {}) {
                 return handleMcpReadToolCall('bclaw_get_context', { ...args, since_session: since }, context);
             }
             default:
-                throw new Error(`bclaw_context: unknown kind '${kind}'. Expected memory | execution | board | board_summary | delta.`);
+                throw new Error(`bclaw_context: unknown kind '${kind}'. Expected memory | execution | board | board_summary | cross_project | delta.`);
         }
     }
     if (name === 'bclaw_get_thread') {
@@ -1635,11 +1801,13 @@ export function handleMcpReadToolCall(name, args = {}, context = {}) {
         }
         const tailLogLines = typeof args.tail_log_lines === 'number' ? args.tail_log_lines : undefined;
         const stallThresholdMs = typeof args.stall_threshold_ms === 'number' ? args.stall_threshold_ms : undefined;
+        const baseRef = typeof args.base_ref === 'string' && args.base_ref ? args.base_ref : undefined;
         const status = getDispatchStatus({
             target_id: targetId,
             cwd,
             tail_log_lines: tailLogLines,
             stall_threshold_ms: stallThresholdMs,
+            base_ref: baseRef,
         });
         // Text view: short, single-screen summary so an agent can decide what to do
         // without parsing the structured payload.
@@ -1658,6 +1826,7 @@ export function handleMcpReadToolCall(name, args = {}, context = {}) {
             `Runtime: pid=${status.runtime.pid ?? '-'} alive=${status.runtime.pid_alive ?? 'unknown'} ack=${status.runtime.ack_file.exists}`,
             `  stdout: ${status.runtime.log_files.stdout?.exists ? `${status.runtime.log_files.stdout.size_bytes}B` : 'absent'}`,
             `  stderr: ${status.runtime.log_files.stderr?.exists ? `${status.runtime.log_files.stderr.size_bytes}B` : 'absent'}`,
+            `  git: commits_ahead=${status.runtime.commits_ahead ?? 'n/a'} dirty_tracked=${status.runtime.dirty_tracked ?? 'n/a'}`,
         ];
         return {
             content: [{ type: 'text', text: lines.join('\n') }],