brainclaw 1.28.2 → 1.28.4

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

@@ -12,6 +12,8 @@
  * @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';
 import { resolveProjectCwd } from '../core/cross-project.js';
@@ -21,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';
@@ -308,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
@@ -387,9 +407,17 @@ export async function handleBclawCoordinate(args, ctx) {
     // for state-mutating helpers; the outer `cwd` (source) stays in scope
     // for the few cases that genuinely need source attribution.
     const dispatchCwd = resolveProjectCwd(req.project, cwd);
-    const isCrossProject = dispatchCwd !== cwd;
+    const isCrossProject = path.resolve(dispatchCwd) !== path.resolve(cwd);
     if (isCrossProject && req.autoExecute !== false) {
-        warnings.push(`cross-project dispatch (project='${req.project}') — auto-spawn disabled; the target agent picks up the brief async via its own bclaw_work.`);
+        return {
+            response: createToolErrorResponse('cross_project_auto_execute_unsupported', `cross-project dispatch (project='${req.project}') cannot auto-execute from the source process; admission refused before creating a claim, assignment, or loop.`, {
+                next_actions: [{
+                        tool: 'bclaw_coordinate',
+                        args: { ...req, autoExecute: false },
+                        when: 'create an inbox-only cross-project assignment that the target agent will pick up with bclaw_work',
+                    }],
+            }),
+        };
     }
     const effectiveAutoExecute = isCrossProject ? false : req.autoExecute;
     // pln#692 P0 — an explicit checkout ref is part of admission, not worktree
@@ -418,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)
@@ -427,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',
@@ -451,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}`,
                     ],
@@ -729,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,
@@ -1008,7 +1052,7 @@ export async function handleBclawCoordinate(args, ctx) {
         // existing length===0 guard skips loop creation. Skipped when open_loop
         // is off, preflight=false, or BRAINCLAW_NO_SPAWN is set (handled inside
         // preflightAgents). Cross-project dispatch never auto-spawns, so skip.
-        if (req.open_loop === true && req.preflight !== false && !req.project && loopReviewerAgents.length > 0) {
+        if (req.open_loop === true && req.preflight !== false && !isCrossProject && loopReviewerAgents.length > 0) {
             try {
                 const { preflightAgents } = await import('../core/spawn-check.js');
                 const pf = await preflightAgents(loopReviewerAgents, { cwd: dispatchCwd });
@@ -1158,7 +1202,7 @@ export async function handleBclawCoordinate(args, ctx) {
                         // (that is the double-spawn hole), and do NOT release the (possibly shared) claim; leave
                         // the slot for reconcile/self-heal. LEGACY: the unchanged inline mint runs.
                         let usedTurnOwned = false;
-                        if (turnOwnedReviewEnabled() && !req.project) {
+                        if (turnOwnedReviewEnabled() && !isCrossProject) {
                             const prep = prepareTurnOwnedReviewDispatch({
                                 loopId: loop.id,
                                 slotId: slot.slot_id,
@@ -1837,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 } : {}),
                     });
                 }
@@ -1869,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 });
@@ -1883,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);
@@ -1909,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
@@ -1968,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;
@@ -1988,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
@@ -2000,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,
@@ -2201,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-entities.js

@@ -479,9 +479,12 @@ export function handleBclawCreate(payload, ctx) {
         const result = createEntity(entity, data, targetCwd);
         appendAuditEntry({ actor: actor ?? 'unknown', ...(actorId ? { actor_id: actorId } : {}), action: 'create', item_id: result.id, item_type: entity }, targetCwd);
         const createText = `✔ created ${entity} ${result.id}${autoSwitched ? ` (auto-switched → ${targetScope.resolved_project.name ?? targetScope.resolved_project.path})` : ''}`;
+        const proximityText = result.nearby_items?.length
+            ? `Nearby existing ${entity} item(s): ${result.nearby_items.map((item) => `${item.id} (${item.reason})`).join(', ')}. Creation was kept; review before adding another duplicate.`
+            : undefined;
         const createContent = autoRepair
-            ? [{ type: 'text', text: createText }, { type: 'text', text: renderAutoRepairWarning(autoRepair, actor ?? 'unknown') }]
-            : [{ type: 'text', text: createText }];
+            ? [{ type: 'text', text: createText }, { type: 'text', text: renderAutoRepairWarning(autoRepair, actor ?? 'unknown') }, ...(proximityText ? [{ type: 'text', text: proximityText }] : [])]
+            : [{ type: 'text', text: createText }, ...(proximityText ? [{ type: 'text', text: proximityText }] : [])];
         // pln#634 — a freshly created plan whose steps are never added is the most
         // common half-finished shape in the store; a sequence with no readiness
         // check is the second. Only those two emit a follow-up.

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.
@@ -1096,8 +1096,10 @@ async function _executeMcpToolCallInner(payload) {
         if (name === 'bclaw_code_status' || name === 'bclaw_code_find' || name === 'bclaw_code_brief' || name === 'bclaw_code_impact' || name === 'bclaw_code_export' || name === 'bclaw_code_outline' || name === 'bclaw_code_refresh') {
             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;
             if (name === 'bclaw_code_status') {
-                const status = await be.status({ cwd, cascade: args.cascade === true });
+                const status = await be.status({ cwd: codeCwd, cascade: args.cascade === true });
                 const diskVersion = readDiskBrainclawVersion();
                 return {
                     response: toolResponse({
@@ -1118,7 +1120,23 @@ async function _executeMcpToolCallInner(payload) {
             }
             if (name === 'bclaw_code_refresh') {
                 const scope = args.scope === 'all' ? 'all' : 'changed';
-                const result = await be.refresh({ scope, cwd, cascade: args.cascade === true });
+                if (args.cascade === true) {
+                    const { startCascadeRefreshJob, summarizeCascadeRefreshJob } = await import('../core/code-map/cascade-jobs.js');
+                    const job = startCascadeRefreshJob(codeCwd, scope);
+                    if (job) {
+                        return {
+                            response: toolResponse({
+                                content: [{ type: 'text', text: `Code Map cascade started: job=${job.job_id}, projects=${job.projects_total}. Follow with bclaw_code_status(cascade=true).` }],
+                                structuredContent: {
+                                    started: true,
+                                    ...summarizeCascadeRefreshJob(job),
+                                    next_actions: [{ tool: 'bclaw_code_status', args: { cascade: true }, when: 'follow progress and terminal per-project diagnostics' }],
+                                },
+                            }),
+                        };
+                    }
+                }
+                const result = await be.refresh({ scope, cwd: codeCwd, cascade: args.cascade === true });
                 const cascadeNote = result.cascade ? ` cascade=${result.cascade.children_refreshed} child(ren)+root` : '';
                 return {
                     response: toolResponse({
@@ -1133,7 +1151,7 @@ async function _executeMcpToolCallInner(payload) {
                     return { response: createToolErrorResponse('validation_error', 'bclaw_code_find requires a non-empty query.') };
                 }
                 const limit = typeof args.limit === 'number' ? args.limit : undefined;
-                const result = await be.find({ query, limit, cwd });
+                const result = await be.find({ query, limit, cwd: codeCwd });
                 return {
                     response: toolResponse({
                         content: [{ type: 'text', text: `Code Map find "${result.query}": ${result.matches.length} match(es), freshness=${result.freshness_badge.freshness}` }],
@@ -1154,7 +1172,7 @@ async function _executeMcpToolCallInner(payload) {
                 const maxEdges = typeof args.maxEdges === 'number' ? args.maxEdges : undefined;
                 const minConfidence = typeof args.minConfidence === 'number' ? args.minConfidence : undefined;
                 const format = args.format === 'mermaid' ? 'mermaid' : args.format === 'json' ? 'json' : undefined;
-                const result = await be.exportGraph({ target, targetKind, direction, depth, maxNodes, maxEdges, minConfidence, format, cwd });
+                const result = await be.exportGraph({ target, targetKind, direction, depth, maxNodes, maxEdges, minConfidence, format, cwd: codeCwd });
                 return {
                     response: toolResponse({
                         content: [{ type: 'text', text: `Code Map export "${result.target}": ${result.nodes.length} node(s), ${result.edges.length} edge(s), depth=${result.limits.max_depth}, freshness=${result.freshness_badge.freshness}` }],
@@ -1170,7 +1188,7 @@ async function _executeMcpToolCallInner(payload) {
                 }
                 const depth = typeof args.depth === 'number' ? args.depth : undefined;
                 const limit = typeof args.limit === 'number' ? args.limit : undefined;
-                const result = await be.impact({ target, depth, limit, cwd });
+                const result = await be.impact({ target, depth, limit, cwd: codeCwd });
                 return {
                     response: toolResponse({
                         content: [{ type: 'text', text: `Code Map impact "${result.target}": ${result.risk.counters.direct_dependents} direct, ${result.risk.counters.transitive_dependents} transitive dependent(s), risk=${result.risk.score}, freshness=${result.freshness_badge.freshness}` }],
@@ -1185,7 +1203,7 @@ async function _executeMcpToolCallInner(payload) {
                     return { response: createToolErrorResponse('validation_error', 'bclaw_code_outline requires a non-empty path.') };
                 }
                 const limit = typeof args.limit === 'number' ? args.limit : undefined;
-                const result = await be.outline({ path: outlinePath, limit, cwd });
+                const result = await be.outline({ path: outlinePath, limit, cwd: codeCwd });
                 return {
                     response: toolResponse({
                         content: [{ type: 'text', text: `Code Map outline "${result.path}": ${result.symbols.length}/${result.symbol_count} symbol(s), index=${result.index_status}, freshness=${result.freshness_badge.freshness}` }],
@@ -1199,7 +1217,7 @@ async function _executeMcpToolCallInner(payload) {
                 return { response: createToolErrorResponse('validation_error', 'bclaw_code_brief requires a non-empty target.') };
             }
             const limit = typeof args.limit === 'number' ? args.limit : undefined;
-            const result = await be.brief({ target, limit, cwd });
+            const result = await be.brief({ target, limit, cwd: codeCwd });
             return {
                 response: toolResponse({
                     content: [{ type: 'text', text: `Code Map brief "${result.target}": ${result.suggested_files_to_read.length} file(s) to read, freshness=${result.freshness_badge.freshness}` }],
@@ -1718,6 +1736,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
@@ -1817,6 +1838,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
@@ -1832,7 +1864,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/core/code-map/aggregate.js

@@ -183,10 +183,9 @@ function statusRank(s) {
     }
 }
 /**
- * Merge per-store badges into one workspace badge: worst status among the INDEXED
- * stores (a missing-index child contributes to coverage, never drags the top-line),
- * plus coverage + workspace-relative detail path-sets. Only when EVERY store is
- * un-indexed is the whole workspace `missing_index`.
+ * Merge per-store badges into one workspace badge. Missing child indexes are a
+ * PARTIAL workspace, never a fresh one: serving the indexed subset is useful,
+ * but the top-line signal must describe the coverage actually searched.
  */
 function mergeBadges(perStore) {
     const total = perStore.length;
@@ -202,14 +201,28 @@ function mergeBadges(perStore) {
         if (statusRank(p.badge.status) > statusRank(worst))
             worst = p.badge.status;
     }
+    if (unindexed.length > 0)
+        worst = 'partial';
+    const statusCounts = {};
+    for (const p of perStore) {
+        const status = p.hasIndex ? p.badge.status : 'missing_index';
+        statusCounts[status] = (statusCounts[status] ?? 0) + 1;
+    }
+    const exceptionalProjects = perStore
+        .filter((p) => p.hasIndex && p.badge.status !== 'fresh')
+        .map((p) => ({ path: p.ref.relPath || '.', status: p.badge.status }));
     const details = {
         traversal: 'workspace',
         projects_indexed: indexed.length,
         projects_total: total,
-        per_project: Object.fromEntries(perStore.map((p) => [p.ref.relPath || '.', p.badge.status])),
+        project_status_counts: statusCounts,
     };
-    if (unindexed.length)
+    if (unindexed.length) {
+        details.unindexed_project_count = unindexed.length;
         details.unindexed_projects = unindexed;
+    }
+    if (exceptionalProjects.length)
+        details.non_fresh_projects = exceptionalProjects;
     const prefixMerge = (key) => {
         const out = [];
         for (const p of indexed) {
@@ -259,7 +272,7 @@ export function aggregateFind(query, limit, resolved, currentHead) {
         const r = findInStore(query, { cwd: ref.cwd }, checker, acc);
         // Per-store badge: drive `partial` from THIS store's own budget-skips (review F2),
         // NOT the shared checker.exhausted flag — else an early store spending the budget
-        // would mislabel every fully-fresh later store as `partial` in per_project. Then
+        // would mislabel every fully-fresh later store as `partial` in diagnostics. Then
         // apply per-store HEAD drift against the one workspace HEAD (review F3) so a child
         // whose index lags the working tree is flagged even under an otherwise-fresh root.
         let badge = deriveBadge(r.base, acc, false, r.matches.length > 0, r.emptyCandidates);