brainclaw 1.28.3 → 1.28.5

package/dist/commands/mcp-write-coordination.js

@@ -12,6 +12,7 @@
  * @module
  */
 import crypto from 'node:crypto';
+import fs from 'node:fs';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { buildClaimEnvPrefix } from '../core/execution-profile.js';
@@ -22,8 +23,7 @@ import { appendAuditEntry } from '../core/audit.js';
 import { nowISO } from '../core/ids.js';
 import { validateMcpField } from '../core/input-validation.js';
 import { generateCandidateIdWithLabel, saveCandidate } from '../core/candidates.js';
-import { DEFAULT_PROTOCOLS } from '../core/loops/types.js';
-import { capLoopArtifactBody } from '../core/loops/result-reducers.js';
+import { DEFAULT_PROTOCOLS, LOOP_PROPOSAL_BODY_MAX_BYTES } from '../core/loops/types.js';
 import { validateLoopProjectResolution } from '../core/loops/project-resolution.js';
 import { coordinateNextActions, dispatchNextActions } from '../core/next-actions.js';
 import { agentValidationFailedWarning, consultAutoExecuteNoOpWarning, planAlreadyAssignedWarning, pushStructuredWarning, scopeAlreadyClaimedWarning, } from '../core/warnings.js';
@@ -309,6 +309,25 @@ export async function handleBclawCoordinate(args, ctx) {
         return { response: createToolErrorResponse('validation_error', parseResult.error.message) };
     }
     const req = parseResult.data;
+    // A proposal is the caller's task contract. Silently replacing its tail with
+    // memory changed the questions workers answered during DGX dogfooding. Keep
+    // the whole task or reject before mutation; never truncate it in-band.
+    if (req.intent === 'ideate') {
+        const taskBytes = Buffer.byteLength(req.task, 'utf8');
+        if (taskBytes > LOOP_PROPOSAL_BODY_MAX_BYTES) {
+            return {
+                response: createToolErrorResponse('ideate_task_too_large', `ideation task is ${taskBytes} bytes; the lossless limit is ${LOOP_PROPOSAL_BODY_MAX_BYTES} bytes. Shorten it or attach a referenced artifact before retrying; no loop was created.`, { task_bytes: taskBytes, task_limit_bytes: LOOP_PROPOSAL_BODY_MAX_BYTES, task_truncated: false }),
+            };
+        }
+        if (req.criticPerspectives) {
+            const targetCount = req.targetAgents?.length ?? 0;
+            if (targetCount === 0 || req.criticPerspectives.length !== targetCount) {
+                return {
+                    response: createToolErrorResponse('ideate_perspective_count_mismatch', `criticPerspectives must contain exactly one instruction per targetAgents entry (targets=${targetCount}, perspectives=${req.criticPerspectives.length}); no loop was created.`),
+                };
+            }
+        }
+    }
     // pln#511 step 2 — preset selector validation. Presets are kind-
     // specific in v1: only intent='ideate' carries them. Unknown names
     // are rejected up-front against the registry so the handler never
@@ -427,8 +446,9 @@ export async function handleBclawCoordinate(args, ctx) {
     // pln#692 P0 — admission must prove that a multi-agent ideation request can
     // satisfy the first worker-produced phase gate BEFORE openLoop (or any
     // identity/claim/assignment mutation). The default critique phase requires
-    // three distinct critique artifacts, so accepting one executable critic
-    // creates a loop that cannot converge without manual artifact injection.
+    // three distinct critique artifacts. Capacity is therefore counted per
+    // requested critic INSTANCE, not per unique agent identity: each occurrence
+    // becomes an isolated slot with its own claim, worktree and turn authority.
     if (req.intent === 'ideate'
         && req.preset !== 'bootstrap'
         && Array.isArray(req.targetAgents)
@@ -436,23 +456,27 @@ export async function handleBclawCoordinate(args, ctx) {
         const critiquePhase = DEFAULT_PROTOCOLS.ideation.phases.find((phase) => phase.name === 'critique');
         const gate = critiquePhase?.advance_gate;
         const requiredCritics = gate?.kind === 'min_artifacts_by_type' ? gate.n : 0;
-        const uniqueTargets = [...new Set(req.targetAgents)];
-        const checks = uniqueTargets.map((agent) => ({
+        const checks = req.targetAgents.map((agent, instanceIndex) => ({
             agent,
+            instanceIndex,
             check: validateAgentForDispatch(agent, { requireSpawnable: true }),
         }));
         const executableTargets = checks.filter(({ check }) => check.valid).map(({ agent }) => agent);
-        const invalidTargets = checks.filter(({ check }) => !check.valid).map(({ agent, check }) => ({
+        const invalidTargets = checks.filter(({ check }) => !check.valid).map(({ agent, instanceIndex, check }) => ({
             agent,
+            instance_index: instanceIndex,
             code: check.code,
             reason: check.reason,
         }));
         if (requiredCritics > 0 && executableTargets.length < requiredCritics) {
             const availableTargets = getSpawnableAgents()
                 .map((profile) => profile.name)
-                .filter((agent, index, all) => agent !== senderAgent && all.indexOf(agent) === index)
+                .filter((agent, index, all) => all.indexOf(agent) === index)
                 .filter((agent) => validateAgentForDispatch(agent, { requireSpawnable: true }).valid);
-            const recoveryTargets = availableTargets.slice(0, requiredCritics);
+            const recoveryAgent = executableTargets[0] ?? availableTargets[0];
+            const recoveryTargets = recoveryAgent
+                ? Array.from({ length: requiredCritics }, () => recoveryAgent)
+                : [];
             const nextActions = recoveryTargets.length >= requiredCritics
                 ? [{
                         tool: 'bclaw_coordinate',
@@ -460,21 +484,20 @@ export async function handleBclawCoordinate(args, ctx) {
                             intent: 'ideate', task: req.task, scope: req.scope,
                             targetAgents: recoveryTargets, autoExecute: effectiveAutoExecute !== false,
                         },
-                        when: `retry with at least ${requiredCritics} distinct executable critics`,
+                        when: `retry with at least ${requiredCritics} executable critic instances`,
                     }]
                 : [{
                         tool: 'bclaw_context',
                         args: { kind: 'execution', includeAgentTooling: true },
-                        when: `configure at least ${requiredCritics} spawnable critic identities before retrying`,
+                        when: 'configure at least one spawnable critic identity before retrying',
                     }];
             return {
-                response: createToolErrorResponse('ideate_gate_capacity_unavailable', `ideation admission refused before mutation: critique gate requires ${requiredCritics} distinct executable critic(s), observed ${executableTargets.length}`, {
+                response: createToolErrorResponse('ideate_gate_capacity_unavailable', `ideation admission refused before mutation: critique gate requires ${requiredCritics} executable critic instance(s), observed ${executableTargets.length}`, {
                     gate: { phase: 'critique', kind: gate?.kind, expected: requiredCritics, observed: executableTargets.length },
                     requested_targets: req.targetAgents,
                     executable_targets: executableTargets,
                     invalid_targets: invalidTargets,
                     blockers: [
-                        ...(uniqueTargets.length < req.targetAgents.length ? ['duplicate target identities do not add executable capacity'] : []),
                         ...(invalidTargets.length > 0 ? ['one or more requested targets are not spawnable'] : []),
                         `missing executable critic capacity: ${requiredCritics - executableTargets.length}`,
                     ],
@@ -738,6 +761,18 @@ export async function handleBclawCoordinate(args, ctx) {
             contextEnvelope: options?.contextEnvelope,
         });
     };
+    const compactDeliveryEntry = (entry) => {
+        if (!entry.command || entry.command.length <= 2048)
+            return entry;
+        const dir = path.join(dispatchCwd, '.brainclaw', 'coordination', 'runtime', 'manual-commands');
+        fs.mkdirSync(dir, { recursive: true });
+        const ext = entry.shell === 'cmd' ? 'cmd' : 'sh';
+        const ref = entry.assignment_id ?? entry.message_id;
+        const commandFile = path.join(dir, `${ref}.${ext}`);
+        fs.writeFileSync(commandFile, entry.command, { encoding: 'utf8', mode: 0o600 });
+        const { command, ...rest } = entry;
+        return { ...rest, command_file: commandFile, command_bytes: Buffer.byteLength(command, 'utf8') };
+    };
     const toMessageSummary = (deliveryPlan) => deliveryPlan.map((entry) => ({
         agent: entry.agent,
         message_id: entry.message_id,
@@ -1846,11 +1881,19 @@ export async function handleBclawCoordinate(args, ctx) {
                 },
             ];
             if (explicitTargets) {
-                for (const agent of req.targetAgents) {
+                const defaultPerspectives = [
+                    'Challenge assumptions and verify the proposal against concrete evidence.',
+                    'Focus on failure modes, operational risks, and recovery paths; challenge earlier contributions explicitly.',
+                    'Develop competing alternatives and compare their costs and trade-offs; resolve or sharpen earlier disagreements.',
+                ];
+                for (const [index, agent] of req.targetAgents.entries()) {
                     const criticIdentity = findAgentIdentityByName(agent, dispatchCwd) ?? ensureAgentRegisteredForDispatch(agent, dispatchCwd);
                     slots.push({
                         role: 'critic',
                         agent,
+                        perspective: req.criticPerspectives?.[index]
+                            ?? defaultPerspectives[index]
+                            ?? `Challenge the conversation from an independent perspective ${index + 1}; avoid repeating prior contributions.`,
                         ...(criticIdentity?.agent_id ? { agent_id: criticIdentity.agent_id } : {}),
                     });
                 }
@@ -1878,7 +1921,12 @@ export async function handleBclawCoordinate(args, ctx) {
                                 stop_condition: presetSelected.stop_condition,
                                 protocol: presetSelected.protocol,
                             }
-                            : {}),
+                            : {
+                                protocol: {
+                                    iteration: DEFAULT_PROTOCOLS.ideation.iteration,
+                                    ideation_schedule: req.ideation_schedule,
+                                },
+                            }),
                     }, dispatchCwd);
                     loopId = loop.id;
                     artifacts.push({ type: 'loop', id: loop.id });
@@ -1892,14 +1940,13 @@ export async function handleBclawCoordinate(args, ctx) {
                     // loop doesn't contain. The task text is already captured on
                     // the thread (title + goal).
                     if (!presetSelected) {
-                        const proposalBody = capLoopArtifactBody(req.task);
                         const updated = add_artifact({
                             id: loop.id,
                             actor: creatorActor,
                             artifact: {
                                 phase: 'proposal',
                                 type: 'proposal',
-                                body: proposalBody,
+                                body: req.task,
                                 produced_by: creatorActor,
                             },
                         }, dispatchCwd);
@@ -1918,8 +1965,11 @@ export async function handleBclawCoordinate(args, ctx) {
                     };
                 }
             } // end else (non-bootstrap open path)
-            // pln#492 phase 2.d.2 — multi-agent dispatch. Skipped in single-
-            // agent mode (the champion drives manually).
+            // Multi-agent ideation keeps artifact capacity separate from execution
+            // concurrency. All requested critic slots are durable, but sequential is
+            // the default scheduling policy: only the first open slot is dispatched
+            // now, and the next one is taken after this result is harvested. Explicit
+            // parallel mode retains the historical immediate fan-out.
             //
             // pln#511 step 2 — initial phase comes from the actual loop's
             // first phase, not a hardcoded 'proposal'. Presets like bootstrap
@@ -1977,7 +2027,10 @@ export async function handleBclawCoordinate(args, ctx) {
                         throw new Error('ideate dispatch: loop disappeared after advance');
                     }
                     dispatchedPhase = advancedLoop.current_phase;
-                    const criticSlots = advancedLoop.slots.filter((s) => s.role === 'critic');
+                    const allCriticSlots = advancedLoop.slots.filter((s) => s.role === 'critic');
+                    const criticSlots = req.ideation_schedule === 'parallel'
+                        ? allCriticSlots
+                        : allCriticSlots.slice(0, 1);
                     for (const slot of criticSlots) {
                         if (!slot.agent)
                             continue;
@@ -1997,7 +2050,10 @@ export async function handleBclawCoordinate(args, ctx) {
                         const briefResult = buildIdeationBrief({
                             thread: advancedLoop,
                             slotRole: slot.role,
+                            slotPerspective: slot.perspective,
                             memoryProvider: provider,
+                            seedText: req.task,
+                            scopeHints: req.scope ? [req.scope] : [],
                         });
                         // pln#626 Phase 2 (Option B) — spawn the critic as a worktree-isolated
                         // worker, mirroring the intent=assign / review chain. Each critic gets
@@ -2009,7 +2065,7 @@ export async function handleBclawCoordinate(args, ctx) {
                         // stray edit harmless (it lands in the throwaway checkout, not master).
                         const criticScope = `ideate-loop:${loopId}:${slot.slot_id}`;
                         const criticDescription = `Ideation critic turn for loop ${loopId} slot ${slot.slot_id} (phase ${advancedLoop.current_phase}). `
-                            + `Critique the proposal and reply with your critique — do not edit code. ${req.task}`;
+                            + `Critique proposal artifact ${proposalArtifactId} and reply with evidence — do not edit code.`;
                         try {
                             const claimResult = createCoordinatorClaim({
                                 agent: slot.agent,
@@ -2210,9 +2266,15 @@ export async function handleBclawCoordinate(args, ctx) {
                 proposal_artifact_id: proposalArtifactId,
                 selected_targets: explicitTargets ? req.targetAgents : [],
                 mode: explicitTargets ? 'multi_agent' : 'single_agent',
+                ...(explicitTargets ? {
+                    ideation_schedule: req.ideation_schedule,
+                    pending_critics: Math.max(0, req.targetAgents.length - dispatchedCritics),
+                } : {}),
                 dispatched_critics: dispatchedCritics,
                 current_phase: dispatchedPhase,
-                delivery_plan: preparedCritics.map((p) => p.entry),
+                task_bytes: Buffer.byteLength(req.task, 'utf8'),
+                task_truncated: false,
+                delivery_plan: preparedCritics.map((p) => compactDeliveryEntry(p.entry)),
                 ...(ideateExecStatus
                     ? { execution_status: ideateExecStatus }
                     : explicitTargets

package/dist/commands/mcp-write-memory.js

@@ -20,7 +20,8 @@ import { deleteMemoryItem, updateMemoryItem } from '../core/operations/memory-mu
 import { assessMemoryPressure, buildCompactionTemplate, applyCompaction } from '../core/gc-semantic.js';
 import { createRuntimeNote } from './runtime-note.js';
 import { createCandidateFromInput } from './reflect.js';
-import { harvestCandidates } from './harvest.js';
+import { harvestCandidates, harvestLaneResults, integrateLaneResults } from './harvest.js';
+import { dispatchReviewLoopTurn } from '../core/review-loop-turn-dispatch.js';
 import { ensureTrust, scanMcpWriteText, appendSecurityWarnings } from './mcp-write-support.js';
 import { toolResponse, createToolErrorResponse, } from './mcp-contract.js';
 function scoreKeywordMatches(text, patterns) {
@@ -448,4 +449,89 @@ export function handleBclawHarvestCandidates(payload, _ctx) {
         }),
     };
 }
+/** MCP parity for the CLI lane-result harvest path (distinct from candidates). */
+export async function handleBclawHarvestLane(payload) {
+    const { args, cwd, connectionSessionId } = payload;
+    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 assignmentId = typeof args.assignmentId === 'string' ? args.assignmentId : undefined;
+    const all = args.all === true;
+    if (!assignmentId && !all) {
+        return { response: createToolErrorResponse('validation_error', 'Provide assignmentId, or set all=true to scan every managed lane.') };
+    }
+    if (assignmentId && all) {
+        return { response: createToolErrorResponse('validation_error', 'assignmentId and all=true are mutually exclusive.') };
+    }
+    const worktreePaths = Array.isArray(args.worktreePaths) ? args.worktreePaths.filter((value) => typeof value === 'string') : undefined;
+    const dryRun = args.dryRun === true;
+    const actor = resolved.identity.agent_name;
+    if (args.integrate === true) {
+        const integrated = integrateLaneResults({ assignmentId, worktreePaths, dryRun, cwd, agent: actor });
+        const dispatchedTurns = [];
+        if (!dryRun) {
+            for (const next of integrated.next_turns) {
+                const dispatched = await dispatchReviewLoopTurn({
+                    loopId: next.loop_id,
+                    slot: { slot_id: next.slot_id, role: next.role, agent: next.agent, agent_id: next.agent_id },
+                    phase: next.phase,
+                    task: next.task,
+                    dispatcherAgent: actor,
+                    dispatcherAgentId: resolved.identity.agent_id,
+                    cwd,
+                });
+                dispatchedTurns.push({
+                    loop_id: next.loop_id,
+                    agent: next.agent,
+                    iteration: next.iteration,
+                    execution_status: dispatched.execution_status,
+                    error: dispatched.error,
+                });
+            }
+        }
+        return {
+            response: toolResponse({
+                content: [{ type: 'text', text: `✔ Lane integrate${dryRun ? ' (dry-run)' : ''}: ${integrated.integrated.length} integrated, ${dispatchedTurns.length} re-dispatched, ${integrated.errors.length} error(s).` }],
+                ...integrated,
+                dispatched_turns: dispatchedTurns,
+                dry_run: dryRun,
+            }),
+        };
+    }
+    const harvested = harvestLaneResults({ assignmentId, worktreePaths, dryRun, cwd, agent: actor });
+    const continuationActions = harvested.continuations.flatMap((continuation) => {
+        const next = continuation.next_expected;
+        if (!next)
+            return [];
+        if (next.action === 'turn' && next.slot_id) {
+            return [{
+                    tool: 'bclaw_loop',
+                    args: { intent: 'turn', loop_id: continuation.loop_id, slot_id: next.slot_id, dispatch: true },
+                    when: next.reason ?? 'dispatch the next sequential loop participant',
+                }];
+        }
+        if (next.action === 'advance') {
+            return [{ tool: 'bclaw_loop', args: { intent: 'advance', loop_id: continuation.loop_id }, when: 'the current phase gate is satisfied' }];
+        }
+        return [{ tool: 'bclaw_loop', args: { intent: 'get', loop_id: continuation.loop_id }, when: next.reason ?? `inspect the expected ${next.action} action` }];
+    });
+    return {
+        response: toolResponse({
+            content: [{ type: 'text', text: `✔ Lane harvest${dryRun ? ' (dry-run)' : ''}: ${harvested.harvested.length} harvested, ${harvested.skipped.length} skipped, ${harvested.errors.length} error(s), ${harvested.warnings.length} warning(s).` }],
+            structuredContent: {
+                harvested: harvested.harvested,
+                skipped: harvested.skipped,
+                errors: harvested.errors,
+                warnings: harvested.warnings,
+                continuations: harvested.continuations,
+                dry_run: dryRun,
+                next_actions: [
+                    ...continuationActions,
+                    ...harvested.warnings.flatMap((warning) => warning.next_actions ?? []),
+                ],
+            },
+        }),
+    };
+}
 //# sourceMappingURL=mcp-write-memory.js.map

package/dist/commands/mcp.js

@@ -48,7 +48,7 @@ import { handleBclawClaim, handleBclawReleaseClaim, handleBclawSessionStart, han
 // Sequence write handlers extracted in pln#622 PR4.
 import { handleBclawCreateSequence, handleBclawUpdateSequence, handleBclawDeleteSequence, } from './mcp-write-sequences.js';
 // Memory write handlers extracted in pln#622 PR4.
-import { handleBclawWriteNote, handleBclawQuickCapture, handleBclawCompact, handleBclawDeleteMemory, handleBclawUpdateMemory, handleBclawHarvestCandidates, } from './mcp-write-memory.js';
+import { handleBclawWriteNote, handleBclawQuickCapture, handleBclawCompact, handleBclawDeleteMemory, handleBclawUpdateMemory, handleBclawHarvestCandidates, handleBclawHarvestLane, } from './mcp-write-memory.js';
 // Admin / provisioning write handlers extracted in pln#622 PR4.
 import { handleBclawSetup, handleBclawInitProject, handleBclawAddCapability, handleBclawAddTool, } from './mcp-write-admin.js';
 // Entity write handlers extracted in pln#622 PR4.
@@ -1097,19 +1097,32 @@ async function _executeMcpToolCallInner(payload) {
             const { JsonlBackend } = await import('../core/code-map/backend.js');
             const be = new JsonlBackend();
             // Session-scoped project selection is authoritative for Code Map too.
-            const codeCwd = scopeInfo.cwd;
+            // An explicit project selector wins, matching the canonical read grammar.
+            let codeCwd = scopeInfo.cwd;
+            let codeScope = scopeInfo;
+            if (typeof args.project === 'string' && args.project.trim()) {
+                codeCwd = resolveProjectCwd(args.project.trim(), codeCwd);
+                codeScope = {
+                    cwd: codeCwd,
+                    active_source: 'explicit',
+                    resolved_project: projectInfoForCwd(codeCwd),
+                };
+            }
             if (name === 'bclaw_code_status') {
                 const status = await be.status({ cwd: codeCwd, cascade: args.cascade === true });
                 const diskVersion = readDiskBrainclawVersion();
                 return {
                     response: toolResponse({
-                        content: [{ type: 'text', text: `Code Map: ${status.store_exists ? 'store present' : 'no store'} — freshness=${status.freshness_badge.freshness}` }],
+                        content: [{
+                                type: 'text',
+                                text: `Code Map: path=${status.store_exists ? 'present' : 'absent'}, index=${status.index_exists ? 'ready' : status.index_manifest_exists ? 'invalid' : 'missing'} — freshness=${status.freshness_badge.freshness}`,
+                            }],
                         structuredContent: {
                             ...status,
                             freshness_badge: status.freshness_badge,
                             mcp_resolution: {
-                                active_source: scopeInfo.active_source,
-                                resolved_project: scopeInfo.resolved_project,
+                                active_source: codeScope.active_source,
+                                resolved_project: codeScope.resolved_project,
                                 server_version: getInstalledBrainclawVersion(),
                                 disk_version: diskVersion,
                                 restart_required: diskVersion !== '0.0.0' && diskVersion !== getInstalledBrainclawVersion(),
@@ -1136,12 +1149,27 @@ async function _executeMcpToolCallInner(payload) {
                         };
                     }
                 }
-                const result = await be.refresh({ scope, cwd: codeCwd, cascade: args.cascade === true });
-                const cascadeNote = result.cascade ? ` cascade=${result.cascade.children_refreshed} child(ren)+root` : '';
+                const { startCodeRefreshJob, summarizeCodeRefreshJob } = await import('../core/code-map/refresh-jobs.js');
+                const job = startCodeRefreshJob(codeCwd, scope);
+                const accepted = job.status !== 'failed' && job.scope === scope;
+                const acknowledgement = accepted
+                    ? `Code Map refresh accepted: job=${job.job_id}, scope=${job.scope}, project=${codeCwd}.`
+                    : job.status === 'failed'
+                        ? `Code Map refresh failed to start: job=${job.job_id}, project=${codeCwd}, error=${job.error ?? 'unknown'}.`
+                        : `Code Map refresh not queued: active job=${job.job_id} has scope=${job.scope}; requested scope=${scope}.`;
                 return {
                     response: toolResponse({
-                        content: [{ type: 'text', text: `Code Map refresh [${result.scope}]: ran=${result.ran} freshness=${result.freshness_badge.freshness}${cascadeNote}${result.lock_status ? ` (${result.lock_status})` : ''}` }],
-                        structuredContent: { ...result, freshness_badge: result.freshness_badge },
+                        content: [{ type: 'text', text: `${acknowledgement} Follow with bclaw_code_status${typeof args.project === 'string' ? `(project=${JSON.stringify(args.project)})` : ''}.` }],
+                        structuredContent: {
+                            accepted,
+                            requested_scope: scope,
+                            ...summarizeCodeRefreshJob(job),
+                            next_actions: [{
+                                    tool: 'bclaw_code_status',
+                                    args: typeof args.project === 'string' ? { project: args.project } : {},
+                                    when: 'follow refresh progress and terminal outcome',
+                                }],
+                        },
                     }),
                 };
             }
@@ -1226,8 +1254,15 @@ async function _executeMcpToolCallInner(payload) {
             };
         }
         if (MCP_READ_TOOLS.some((tool) => tool.name === name) || LEGACY_READ_TOOL_HANDLERS.has(name)) {
+            const response = appendLegacyMcpToolWarning(toolResponse(handleMcpReadToolCall(name, args, { cwd, connectionSessionId, effectiveScope: scopeInfo })), name);
+            const switchedSessionId = name === 'bclaw_switch'
+                ? response.structuredContent?.session_id
+                : undefined;
             return {
-                response: appendLegacyMcpToolWarning(toolResponse(handleMcpReadToolCall(name, args, { cwd, connectionSessionId, effectiveScope: scopeInfo })), name),
+                response,
+                ...(typeof switchedSessionId === 'string' && switchedSessionId
+                    ? { nextConnectionSessionId: switchedSessionId }
+                    : {}),
             };
         }
         // Resolve model once for all write operations
@@ -1736,6 +1771,9 @@ async function _executeMcpToolCallInner(payload) {
         if (name === 'bclaw_harvest_candidates') {
             return handleBclawHarvestCandidates(payload, writeMemoryCtx);
         }
+        if (name === 'bclaw_harvest') {
+            return await handleBclawHarvestLane(payload);
+        }
         // ── Canonical CRUD verbs (Phase 3 slice 3b) ──────────────────────
         //
         // Thin wrappers around src/core/entity-operations.ts. Behind
@@ -1835,6 +1873,17 @@ async function _executeMcpToolCallInner(payload) {
                     };
                 }
                 const result = listEntities(entity, targetCwd, filter);
+                const requestedFields = Array.isArray(args.fields)
+                    ? args.fields.filter((field) => typeof field === 'string' && field.length > 0)
+                    : [];
+                if (requestedFields.length > 0) {
+                    result.items = result.items.map((item) => {
+                        if (!item || typeof item !== 'object')
+                            return item;
+                        const row = item;
+                        return Object.fromEntries(requestedFields.filter((field) => row[field] !== undefined).map((field) => [field, row[field]]));
+                    });
+                }
                 // pln#491 — bound the payload (count is already capped by applyPaging;
                 // 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
@@ -1850,7 +1899,7 @@ async function _executeMcpToolCallInner(payload) {
                     { tool: 'bclaw_get', args: { entity, id: '<id from items>', ...(args.project ? { project: args.project } : {}), ...(args.budget_tokens ? { budget_tokens: args.budget_tokens } : {}) }, when: 'to read one item in full' },
                 ];
                 if (bounded.has_more) {
-                    nextActions.push({ tool: 'bclaw_find', args: { entity, filter: { ...filter, offset: bounded.next_offset }, ...(args.project ? { project: args.project } : {}), ...(args.budget_tokens ? { budget_tokens: args.budget_tokens } : {}) }, when: 'to fetch the next page' });
+                    nextActions.push({ tool: 'bclaw_find', args: { entity, filter: { ...filter, offset: bounded.next_offset }, ...(requestedFields.length ? { fields: requestedFields } : {}), ...(args.project ? { project: args.project } : {}), ...(args.budget_tokens ? { budget_tokens: args.budget_tokens } : {}) }, 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.

package/dist/commands/switch.js

@@ -72,7 +72,14 @@ export function switchProject(projectRef, options = {}) {
             ...session,
             active_project: { path: resolved, name: projectName, switched_at: now },
         }, cwd);
-        return { switched: true, path: resolved, name: projectName, scope: 'session', workspace_root: wsRoot };
+        return {
+            switched: true,
+            path: resolved,
+            name: projectName,
+            scope: 'session',
+            workspace_root: wsRoot,
+            session_id: session.session_id,
+        };
     }
     if (sessionOnly) {
         throw new Error('Cannot switch project without an active agent session. Start with bclaw_work or bclaw_session_start first.');

package/dist/core/code-map/backend.js

@@ -9,8 +9,9 @@
  * `freshness_badge`, locking the response shape for later sprints.
  */
 import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
 import path from 'node:path';
-import { readManifest, readShard, storeExists } from './store.js';
+import { readManifest, readShard } from './store.js';
 import { refresh as runRefresh } from './refresh.js';
 import { applyGitHeadDrift, withFreshness } from './freshness.js';
 import { brief as runBrief, find as runFind } from './query.js';
@@ -21,8 +22,9 @@ import { resolveTraversal, aggregateFind, aggregateBrief } from './aggregate.js'
 import { defaultMemoryReader } from './memory-reader.js';
 import { inspectNestedProjects, refreshWorkspaceCascade } from './cascade.js';
 import { latestCascadeRefreshJob, summarizeCascadeRefreshJob } from './cascade-jobs.js';
+import { latestCodeRefreshJob, summarizeCodeRefreshJob } from './refresh-jobs.js';
 import { loadConfig } from '../config.js';
-import { codeMapDir } from './paths.js';
+import { codeMapDir, manifestPath } from './paths.js';
 /** spec §9 caps the brief reading list at 12 files. */
 export const BRIEF_FILE_CAP = 12;
 /**
@@ -116,9 +118,12 @@ function buildCascadeStatus(rootCwd) {
     const discovery = inspectNestedProjects(root);
     const children = discovery.projects.map((abs) => {
         const m = readManifest(abs);
+        const storePath = codeMapDir(abs);
         return {
             path: path.relative(root, abs).replace(/\\/g, '/') || '.',
-            store_exists: m ? true : storeExists(abs),
+            store_exists: fs.existsSync(storePath),
+            index_exists: m !== null,
+            index_manifest_exists: fs.existsSync(manifestPath(abs)),
             freshness: m ? m.freshness.status : 'missing_index',
             files_indexed: m ? m.stats.files_indexed : null,
             ...(m && m.stats.files_indexed === 0 ? { reason: 'no_eligible_files' } : {}),
@@ -157,9 +162,13 @@ export class JsonlBackend {
             store_path: codeMapDir(projectRoot, input.preferredDirName),
         };
         const manifest = readManifest(input.cwd, input.preferredDirName);
+        const storePathExists = fs.existsSync(resolution.store_path);
+        const manifestFileExists = fs.existsSync(manifestPath(input.cwd, input.preferredDirName));
         const result = manifest
             ? {
-                store_exists: true,
+                store_exists: storePathExists,
+                index_exists: true,
+                index_manifest_exists: true,
                 resolution,
                 freshness_badge: this.withHeadDrift(badge(manifest.freshness.status, {
                     stale_file_count: manifest.freshness.stale_file_count,
@@ -172,7 +181,9 @@ export class JsonlBackend {
                 },
             }
             : {
-                store_exists: storeExists(input.cwd, input.preferredDirName),
+                store_exists: storePathExists,
+                index_exists: false,
+                index_manifest_exists: manifestFileExists,
                 resolution,
                 freshness_badge: badge('missing_index'),
                 stats: null,
@@ -183,6 +194,9 @@ export class JsonlBackend {
         if (input.cascade && isMultiProjectWorkspace(input.cwd)) {
             result.cascade = buildCascadeStatus(input.cwd);
         }
+        const latestRefresh = latestCodeRefreshJob(projectRoot);
+        if (latestRefresh)
+            result.refresh_job = summarizeCodeRefreshJob(latestRefresh);
         return result;
     }
     /**