brainclaw 1.28.2 → 1.28.4

package/README.md

@@ -282,6 +282,12 @@ per-phase memory filters. The shared controls are `open`, `turn`,
 implementation also adds `bind` and `verify`. `request_input` /
 `provide_input` are cross-cutting clarification primitives for any workflow.
 
+Ideation is sequential and conversational by default: critic B sees and
+challenges critic A's contribution, critic C sees both, then the champion
+revises and the ordered participants run another bounded round. The three
+critic slots may all use the same installed agent with distinct persisted
+perspectives; `ideation_schedule="parallel"` is an explicit fan-out option.
+
 Every worker-backed phase, across all five workflows, is launched from one
 immutable [execution contract](docs/concepts/execution-contract.md): exact
 identity, artifact expectations, workspace policy, capability snapshot and

package/dist/commands/harvest.js

@@ -13,7 +13,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
-import { CandidateSchema, LaneResultSchema } from '../core/schema.js';
+import { CandidateSchema } from '../core/schema.js';
 import { gitEvidence } from '../core/dispatch-status.js';
 import { listCandidates, listArchivedCandidates, saveCandidate } from '../core/candidates.js';
 import { createRuntimeEvent } from '../core/events.js';
@@ -26,11 +26,14 @@ import { closeReviewLoopFromLaneResult } from '../core/review-loop-close.js';
 import { closeIdeationLoopFromLaneResult } from '../core/ideation-loop-close.js';
 import { dispatchReviewLoopTurn, turnOwnedLoopEnabled } from '../core/review-loop-turn-dispatch.js';
 import { reconcileTurnOwnedLane, turnOwnedLaneEvidence } from '../core/loops/reconcile-turn.js';
+import { findReservationByAssignmentId } from '../core/loops/attempt-reservation.js';
 import { getLoop } from '../core/loops/store.js';
+import { computeNextExpected } from '../core/loops/next-expected.js';
 import { phasePolicy } from '../core/loops/kind-policies.js';
 import { reconcileClaimConformity } from '../core/claim-conformity.js';
 import { toWarningDetail } from '../core/warnings.js';
 import { harvestHarnessObservation } from '../core/harness-adapters/index.js';
+import { LANE_RESULT_FILENAME, resolveLaneResultFile } from '../core/lane-result-file.js';
 /**
  * pln#630 PR3a — finalize a TURN-OWNED review lane via the exactly-once `reconcileTurn`
  * instead of the legacy `closeReviewLoopFromLaneResult`. Returns `undefined` for a legacy
@@ -349,7 +352,7 @@ export function runHarvestCandidates(options = {}) {
 // ─────────────────────────────────────────────────────────────────────────────
 /** Conventional path of a worker's lane-result file at the worktree root. */
 export function getLaneResultPath(worktreePath) {
-    return path.join(worktreePath, 'LANE-RESULT.json');
+    return path.join(worktreePath, LANE_RESULT_FILENAME);
 }
 /** Idempotency marker so a lane-result is harvested once. */
 function laneHarvestedMarkerPath(cwd, assignmentId) {
@@ -365,11 +368,19 @@ function laneHarvestedMarkerPath(cwd, assignmentId) {
 export function harvestLaneResults(options = {}) {
     const cwd = options.cwd ?? process.cwd();
     const agent = options.agent ?? 'coordinator';
-    const result = { harvested: [], skipped: [], errors: [], warnings: [] };
+    const result = { harvested: [], skipped: [], errors: [], warnings: [], continuations: [] };
     const worktreePaths = resolveLaneScanPaths(options, cwd);
     for (const worktreePath of worktreePaths) {
-        const file = getLaneResultPath(worktreePath);
-        const fileExists = fs.existsSync(file);
+        const fileResolution = resolveLaneResultFile(worktreePath, options.assignmentId);
+        if (fileResolution.kind === 'invalid') {
+            result.errors.push(`Failed to parse ${fileResolution.path}: ${fileResolution.error}`);
+            continue;
+        }
+        if (fileResolution.kind === 'ambiguous') {
+            result.errors.push(`Ambiguous lane-result files for ${options.assignmentId ?? worktreePath}: ${fileResolution.paths.join(', ')}`);
+            continue;
+        }
+        const fileExists = fileResolution.kind === 'found';
         let nativeObservation;
         if (options.assignmentId) {
             try {
@@ -384,13 +395,7 @@ export function harvestLaneResults(options = {}) {
             continue;
         let lane;
         if (fileExists) {
-            try {
-                lane = LaneResultSchema.parse(JSON.parse(fs.readFileSync(file, 'utf-8')));
-            }
-            catch (err) {
-                result.errors.push(`Failed to parse ${file}: ${err instanceof Error ? err.message : String(err)}`);
-                continue;
-            }
+            lane = fileResolution.lane;
         }
         else {
             lane = nativeObservation.lane;
@@ -582,6 +587,26 @@ export function harvestLaneResults(options = {}) {
             }
         }
         result.harvested.push(lane);
+        if (!options.dryRun) {
+            const reservation = findReservationByAssignmentId(lane.assignment_id, cwd);
+            if (reservation) {
+                try {
+                    const loop = getLoop(reservation.loop_id, cwd);
+                    if (loop) {
+                        result.continuations.push({
+                            assignment_id: lane.assignment_id,
+                            loop_id: loop.id,
+                            next_expected: computeNextExpected(loop),
+                        });
+                    }
+                }
+                catch {
+                    // Reconciliation already reports corrupt/unreadable loop state as a
+                    // loud warning. Continuation hints are best-effort and must not turn
+                    // a successfully harvested result into an uncaught failure.
+                }
+            }
+        }
     }
     return result;
 }
@@ -662,17 +687,18 @@ export function integrateLaneResults(options = {}) {
     const result = { integrated: [], skipped: [], errors: [], next_turns: [] };
     const worktreePaths = resolveLaneScanPaths(options, cwd);
     for (const worktreePath of worktreePaths) {
-        const file = getLaneResultPath(worktreePath);
-        if (!fs.existsSync(file))
+        const fileResolution = resolveLaneResultFile(worktreePath, options.assignmentId);
+        if (fileResolution.kind === 'absent')
+            continue;
+        if (fileResolution.kind === 'invalid') {
+            result.errors.push(`Failed to parse ${fileResolution.path}: ${fileResolution.error}`);
             continue;
-        let lane;
-        try {
-            lane = LaneResultSchema.parse(JSON.parse(fs.readFileSync(file, 'utf-8')));
         }
-        catch (err) {
-            result.errors.push(`Failed to parse ${file}: ${err instanceof Error ? err.message : String(err)}`);
+        if (fileResolution.kind === 'ambiguous') {
+            result.errors.push(`Ambiguous lane-result files for ${options.assignmentId ?? worktreePath}: ${fileResolution.paths.join(', ')}`);
             continue;
         }
+        const lane = fileResolution.lane;
         if (options.assignmentId && lane.assignment_id !== options.assignmentId)
             continue;
         const assignment = loadAssignment(lane.assignment_id, cwd);
@@ -681,6 +707,11 @@ export function integrateLaneResults(options = {}) {
             result.errors.push(`No assignment record for lane ${lane.assignment_id} — cannot integrate`);
             continue;
         }
+        const candidateTurnEvidence = turnOwnedLaneEvidence(lane, cwd);
+        const candidateOwnedLoop = candidateTurnEvidence ? getLoop(candidateTurnEvidence.reservation.loop_id, cwd) : undefined;
+        const ownedTurnEvidence = candidateTurnEvidence && candidateOwnedLoop && turnOwnedLoopEnabled(candidateOwnedLoop.kind)
+            ? candidateTurnEvidence
+            : undefined;
         const profile = getCapabilityProfile(assignment.agent);
         // No profile ⇒ assume it can commit (conservative: don't author for an
         // unknown agent), so brainclaw only lifecycles.
@@ -726,7 +757,12 @@ export function integrateLaneResults(options = {}) {
                     ...(entry.commit_sha ? [{ type: 'commit', ref: entry.commit_sha, description: 'on-behalf integration commit' }] : []),
                     ...entry.files_changed.slice(0, 50).map((f) => ({ type: 'file', ref: f })),
                 ];
-                entry.assignment_completed = forceCompleteAssignment(lane.assignment_id, artifacts, `pln#534 on-behalf integration: ${lane.summary.slice(0, 120)}`, actor, cwd);
+                // Turn-owned lanes are terminalized only after their artifact contract
+                // passes reconcileTurn. A repairable envelope must not complete the
+                // Assignment or fail/release its slot before the corrected replay.
+                if (!ownedTurnEvidence) {
+                    entry.assignment_completed = forceCompleteAssignment(lane.assignment_id, artifacts, `pln#534 on-behalf integration: ${lane.summary.slice(0, 120)}`, actor, cwd);
+                }
                 // pln#628 Focus 4B — map this lane onto its review loop BEFORE deciding
                 // teardown: PR1 records the verdict + advances (auto-close on approve);
                 // PR2 continues the fix cycle on request_changes (bump round, emit a
@@ -735,11 +771,8 @@ export function integrateLaneResults(options = {}) {
                 // for non-review lanes / lanes without a verdict; never throws.
                 // Legacy ideation lanes still use the historical closer. A turn-owned
                 // lane of any kind is finalized exactly once by reconcileTurn below.
-                const candidateEvidence = turnOwnedLaneEvidence(lane, cwd);
-                const ownedLoop = candidateEvidence ? getLoop(candidateEvidence.reservation.loop_id, cwd) : undefined;
-                const turnOwnedEvidence = candidateEvidence && ownedLoop && turnOwnedLoopEnabled(ownedLoop.kind)
-                    ? candidateEvidence
-                    : undefined;
+                const ownedLoop = candidateOwnedLoop;
+                const turnOwnedEvidence = ownedTurnEvidence;
                 if (!turnOwnedEvidence) {
                     const ideationClose = closeIdeationLoopFromLaneResult(assignment, lane, actor, cwd);
                     if (ideationClose) {
@@ -781,6 +814,7 @@ export function integrateLaneResults(options = {}) {
                     if (rr.next_turn) {
                         result.next_turns.push({ loop_id: reservation.loop_id, ...rr.next_turn });
                     }
+                    entry.assignment_completed = loadAssignment(lane.assignment_id, cwd)?.status === 'completed';
                     // Claim/run/assignment settling is OWNED by reconcileTurn, so we do NOT run the
                     // legacy teardown gate — just reflect the resulting claim state. Settlement
                     // semantics (reconcile-turn.ts, review #1): an ACCEPTED lane — approve OR
@@ -1221,6 +1255,7 @@ export async function runHarvestLane(assignmentId, options = {}) {
             // collected but never emitted on ANY channel; the silent half of the
             // 2026-08-02/03 review-loop stalls.
             warnings: result.warnings,
+            continuations: result.continuations,
         }, null, 2));
         return;
     }
@@ -1257,6 +1292,13 @@ export async function runHarvestLane(assignmentId, options = {}) {
     for (const w of result.warnings) {
         console.log(`  ⚠ ${w.message}`);
     }
+    for (const continuation of result.continuations) {
+        const next = continuation.next_expected;
+        if (!next)
+            continue;
+        const slot = next.slot_id ? ` slot=${next.slot_id}` : '';
+        console.log(`  ↻ Next loop action [${continuation.loop_id}]: ${next.action}${slot}${next.reason ? ` — ${next.reason}` : ''}`);
+    }
     const warnTag = result.warnings.length > 0 ? `, ${result.warnings.length} warning(s)` : '';
     console.log(`\n✔ Lane harvest complete${dryTag}: ${result.harvested.length} harvested, ${result.skipped.length} skipped, ${result.errors.length} error(s)${warnTag}.`);
 }

package/dist/commands/loops-handlers.js

@@ -23,12 +23,15 @@ function successResponse(intent, result, artifacts, side_effects, warnings, dura
     const resultLoop = result && typeof result === 'object' && 'loop' in result
         ? result.loop
         : undefined;
+    const enrichedResult = resultLoop && result && typeof result === 'object'
+        ? { ...result, progress: loopProgress(resultLoop) }
+        : result;
     const nextActions = resultLoop ? pipelineNextActions(resultLoop) : [];
     return {
         response: {
             status: 'ok',
             intent: `bclaw_loop.${intent}`,
-            result,
+            result: enrichedResult,
             artifacts,
             side_effects,
             warnings,
@@ -86,6 +89,30 @@ function pipelineNextActions(loop) {
     }
     return [];
 }
+function loopProgress(loop) {
+    const phase = loop.phases.find((candidate) => candidate.name === loop.current_phase);
+    const phaseSlots = loop.slots.filter((slot) => (slot.phase ?? loop.current_phase) === loop.current_phase);
+    const slotCounts = {};
+    for (const slot of phaseSlots)
+        slotCounts[slot.status] = (slotCounts[slot.status] ?? 0) + 1;
+    const artifactCounts = {};
+    for (const artifact of loop.artifacts.filter((item) => item.phase === loop.current_phase)) {
+        artifactCounts[artifact.type] = (artifactCounts[artifact.type] ?? 0) + 1;
+    }
+    const gate = evaluatePhaseAdvanceGate(loop, phase?.advance_gate);
+    const activeSlots = phaseSlots.filter((slot) => ['open', 'assigned', 'working', 'waiting_input'].includes(slot.status));
+    const stuck = loop.status === 'open' && !gate.advance && activeSlots.length === 0;
+    return {
+        phase: loop.current_phase,
+        iteration: loop.iteration_count,
+        slots_by_status: slotCounts,
+        artifacts_by_type: artifactCounts,
+        gate_met: gate.advance,
+        ...(gate.gate_reason ? { gate_reason: gate.gate_reason } : {}),
+        stuck,
+        ...(stuck ? { recovery: 'Replay a real slot turn with bclaw_loop(intent="turn", slot_id=…); add_artifact cannot satisfy strict evidence.' } : {}),
+    };
+}
 /** Concrete action evaluated by continuation policy; never exposed as an ungoverned hint. */
 function proposedPipelineActions(loop, cwd) {
     if (loop.kind === 'ideation') {

package/dist/commands/mcp-catalog.js

@@ -374,7 +374,7 @@ export const MCP_READ_TOOLS = [
     },
     {
         name: 'bclaw_code_status',
-        description: 'Code Map status for this project: store presence, freshness badge (fresh / stale_changed_files / stale_extractor / stale_grammar / stale_git_head / partial / missing_index), and index stats (files, nodes, edges). Read-only; never refreshes. Pair with bclaw_code_refresh when freshness is missing_index or stale. In a multi-project workspace, cascade=true adds a per-child recap (which nested projects have a built index vs missing_index).',
+        description: 'Code Map status for the active session project: store presence, freshness badge, and index stats. Read-only; never refreshes. In a multi-project workspace, cascade=true adds per-child coverage plus progress/terminal diagnostics for the latest durable cascade job.',
         annotations: { tier: 'standard', category: 'discovery', headlessApproval: 'auto' },
         inputSchema: {
             type: 'object',
@@ -459,7 +459,7 @@ export const MCP_READ_TOOLS = [
 const MCP_WRITE_TOOLS = [
     {
         name: 'bclaw_code_refresh',
-        description: 'Rebuild the Code Map index for this project (Tree-sitter parse + shards + indexes, behind the per-project lock). scope="changed" (default) reparses changed files; scope="all" does a full refresh + compaction. A live competing lock fails fast with a clear status — refresh never blocks. Returns the resulting freshness_badge. In a multi-project workspace, cascade=true refreshes EVERY nested project into its own store + the root store scoped to files no child owns (zero double-indexing) — so one call at the root indexes the whole monorepo per-project.',
+        description: 'Rebuild the Code Map index for the active session project. scope="changed" (default) reparses changed files; scope="all" does a full refresh + compaction. In a multi-project workspace, cascade=true starts a durable background job immediately; follow it with bclaw_code_status(cascade=true), which reports progress and terminal per-project diagnostics without an MCP timeout.',
         annotations: { tier: 'standard', category: 'discovery', headlessApproval: 'prompt' },
         inputSchema: {
             type: 'object',
@@ -848,10 +848,12 @@ const MCP_WRITE_TOOLS = [
         inputSchema: {
             type: 'object',
             properties: {
-                intent: { type: 'string', enum: ['assign', 'consult', 'review', 'reroute', 'summarize', 'ideate'], description: 'Coordination intent. assign/review/reroute and multi-agent ideate spawn worker processes; consult/summarize do not. "assign" creates a claim per target agent and spawns a worker on the brief. "consult" delivers the brief to the target inbox(es) WITHOUT creating claims and WITHOUT spawning — targets pick it up via their own bclaw_work. "review" creates a review candidate (and, with open_loop, a review loop). "ideate" opens an ideation loop with the task as the proposal seed; with targetAgents it advances to critique and SPAWNS one worktree-isolated critic worker per target (autoExecute honored, pln#626 Phase 2), otherwise it opens the loop for the champion to drive manually. "reroute" releases the current claim and reassigns. "summarize" reads a thread and returns a summary.' },
+                intent: { type: 'string', enum: ['assign', 'consult', 'review', 'reroute', 'summarize', 'ideate'], description: 'Coordination intent. assign/review/reroute and multi-agent ideate spawn worker processes; consult/summarize do not. "assign" creates a claim per target agent and spawns a worker on the brief. "consult" delivers the brief to the target inbox(es) WITHOUT creating claims and WITHOUT spawning — targets pick it up via their own bclaw_work. "review" creates a review candidate (and, with open_loop, a review loop). "ideate" opens an ideation loop with the task as the proposal seed; with targetAgents it advances to critique and, by default, starts one critic at a time. Set ideation_schedule="parallel" for immediate fan-out. "reroute" releases the current claim and reassigns. "summarize" reads a thread and returns a summary.' },
                 task: { type: 'string', description: 'Brief or task description delivered to target agents. TRANSPORT NOTE (dec#133): a spawned worker\'s capabilities follow its invoke template, not the mere presence of "sandbox". A sandboxed codex worker (`--sandbox workspace-write`, `approval_policy=never`) CAN reach brainclaw MCP — the server runs out-of-sandbox and every tool call is auto-approved — so MCP lifecycle calls (`bclaw_assignment_update`, `bclaw_send_message`, …) do NOT hang. Its one real limit is that `.git` is read-only: it cannot `git commit`, so it must leave fixes uncommitted in the worktree and the coordinator integrates + commits the diff at harvest (never instruct such a worker to commit). Genuinely MCP-less agents (nanoclaw/nemoclaw/picoclaw/zeroclaw) have no MCP at all: for them, prefer file-based protocols (write findings/reply to a markdown file in the worktree; the coordinator harvests it and lifecycle-closes the assignment). See docs/integrations/<agent>.md for the per-agent capability matrix.' },
                 scope: { type: 'string', description: 'File or feature scope. Used as claim scope for assign/reroute; as thread id for summarize if threadId is absent.' },
                 targetAgents: { type: 'array', items: { type: 'string' }, description: 'Agent names to target. If omitted, all spawnable agents are used.' },
+                ideation_schedule: { type: 'string', enum: ['sequential', 'parallel'], description: 'For intent=ideate with targetAgents: sequential (default) starts only the first critic; after harvest, drive the next open critic with bclaw_loop turn dispatch=true. parallel starts all critics immediately.' },
+                criticPerspectives: { type: 'array', items: { type: 'string' }, description: 'Optional ideation instructions/lenses aligned positionally with targetAgents. If omitted, Brainclaw assigns distinct evidence, failure-mode, and alternative/trade-off lenses.' },
                 constraints: { type: 'object', description: 'Optional structured constraints passed alongside the brief (e.g. deadline, reviewCriteria).' },
                 threadId: { type: 'string', description: 'Thread ID for summarize intent.' },
                 linked: {
@@ -864,7 +866,7 @@ const MCP_WRITE_TOOLS = [
                     },
                     additionalProperties: false,
                 },
-                autoExecute: { type: 'boolean', description: 'Attempt to spawn target agents after delivery (default: true). Applies to the spawning intents assign/review/reroute AND to multi-agent ideate (with targetAgents, it spawns one worktree-isolated critic worker per target). consult is inbox-only and ignores autoExecute; summarize just reads a thread and ignores it. When false on a spawning intent, returns command_ready_manual with bash commands for the supervisor to run.' },
+                autoExecute: { type: 'boolean', description: 'Attempt to spawn target agents after delivery (default: true). Applies to the spawning intents assign/review/reroute and multi-agent ideate. Sequential ideation starts one critic; parallel ideation starts every critic. consult is inbox-only and ignores autoExecute; summarize just reads a thread and ignores it. When false on a spawning intent, returns command_ready_manual with commands for the supervisor to run.' },
                 open_loop: { type: 'boolean', description: 'For intent=review only: also open a review Loop on top of the candidate (author + reviewer slots, advance to `findings`, dispatch turns). Default false — existing review callers are unaffected. See docs/concepts/loop-engine.md §Automation.' },
                 review_mode: { type: 'string', enum: ['asymmetric', 'symmetric'], description: 'Optional review Loop mode when open_loop=true. `asymmetric` (default) keeps the classical author→reviewer handoff; `symmetric` lets each reviewer turn also apply fixes directly, halving round-trips for spec/doc reviews. Ignored when open_loop is false.' },
                 preflight: { type: 'boolean', description: 'pln#533: when open_loop=true, run a trivial validation spawn per reviewer agent BEFORE opening the loop so an environment death (config rejected, auth fail, model mismatch) surfaces instantly with a clear reason instead of a generic loop timeout. Reviewers that fail pre-flight are dropped (with a targeted warning); if all fail, loop creation is skipped. Default true; set false to skip (e.g. you already ran `brainclaw doctor --spawn-check`). Ignored when open_loop is false or BRAINCLAW_NO_SPAWN is set.' },
@@ -999,6 +1001,24 @@ const MCP_WRITE_TOOLS = [
             required: [],
         },
     },
+    {
+        name: 'bclaw_harvest',
+        description: 'Harvest worker LANE-RESULT.json envelopes into assignment/loop state. This is MCP parity for `brainclaw harvest` and is distinct from candidate-memory harvest. Use assignmentId for one lane or all=true; integrate=true also performs the CLI --integrate lifecycle. Repairable contract errors leave the loop slot replayable and are returned as warnings.',
+        annotations: { tier: 'standard', category: 'coordination', headlessApproval: 'auto' },
+        inputSchema: {
+            type: 'object',
+            properties: {
+                assignmentId: { type: 'string', description: 'One Assignment whose lane result should be harvested.' },
+                all: { type: 'boolean', description: 'Scan every managed lane; mutually exclusive with assignmentId.' },
+                worktreePaths: { type: 'array', items: { type: 'string' }, description: 'Optional explicit worktrees to scan.' },
+                dryRun: { type: 'boolean', description: 'Report without writing state.' },
+                integrate: { type: 'boolean', description: 'Also lifecycle/commit-on-behalf like CLI --integrate.' },
+                agent: { type: 'string', description: 'Coordinator agent name.' },
+                agentId: { type: 'string', description: 'Registered coordinator agent id.' },
+            },
+            required: [],
+        },
+    },
     // ── Canonical CRUD verbs (Phase 3 / v1.0 grammar) ──────────────────
     // Promoted to `standard` tier at the v1.0 cut.
     {
@@ -1012,6 +1032,7 @@ const MCP_WRITE_TOOLS = [
                 filter: { type: 'object', description: 'Filter keys (ANY entity): status, tag (single tag), tags (array, any-match), author, plan_id, source, auto_generated, limit, offset, includeLegacy (bool, default false), minAutoReflectConfidence (0-1, default 0.6). ENTITY-SCOPED keys (rejected with a validation_error if used with any other entity): assignment_id, claim_id, message_id — ONLY for entity="agent_run"; scope ("project" default | "global", the latter unions the dispatchable catalog + adds dispatchable/registered) and includeReputation (bool — attaches a public reputation summary per agent) — ONLY for entity="agent". Unknown/mis-scoped keys are rejected loudly.' },
                 project: { type: 'string', description: 'Optional: name (or path/basename) of a linked project to query. Defaults to the current project. Only cross_project_links (config.yaml) and workspace store-chain children are accepted — list with `brainclaw link list`.' },
                 budget_tokens: { type: 'number', description: 'Optional token budget for the page payload (~4 chars/token). Tightens the default size cap; pagination metadata (has_more/next_offset) still applies.' },
+                fields: { type: 'array', items: { type: 'string' }, description: 'Optional field projection for each row, e.g. ["id","status","created_at"].' },
             },
             required: ['entity'],
         },

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

@@ -232,6 +232,13 @@ function dispatchReadTool(name, args, ctx) {
             notifications = buildNotificationSummary(unseenEvents);
             unseenEventCount = unseenEvents.length;
         }
+        const actionableNotificationTypes = new Set(['action', 'assignment', 'claim', 'plan', 'handoff', 'candidate', 'loop']);
+        const actionableNotifications = notifications
+            ? Object.fromEntries(Object.entries(notifications).filter(([key]) => actionableNotificationTypes.has(key.split(':').at(-1) ?? '')))
+            : undefined;
+        const actionableCount = actionableNotifications
+            ? Object.values(actionableNotifications).reduce((sum, count) => sum + count, 0)
+            : 0;
         return {
             content: [{ type: 'text', text: enrichedContent || 'No relevant memory found.' }],
             structuredContent: {
@@ -246,7 +253,14 @@ function dispatchReadTool(name, args, ctx) {
                     name: tool.name,
                     type: tool.type,
                 })),
-                ...(notifications ? { pending_notifications: notifications, unseen_event_count: unseenEventCount } : {}),
+                ...(notifications ? {
+                    pending_notifications: {
+                        actionable_count: actionableCount,
+                        by_type: actionableNotifications ?? {},
+                        telemetry_events_omitted: Math.max(0, (unseenEventCount ?? 0) - actionableCount),
+                    },
+                    unseen_event_count: unseenEventCount,
+                } : {}),
             },
         };
     }

package/dist/commands/mcp-schemas.generated.js

@@ -274,6 +274,11 @@ export const generatedSchemas = {
             "agent_id": {
                 "type": "string"
             },
+            "perspective": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 1000
+            },
             "assignment_id": {
                 "type": "string"
             },
@@ -317,6 +322,14 @@ export const generatedSchemas = {
             },
             "current_turn_id": {
                 "type": "string"
+            },
+            "last_completed_phase": {
+                "type": "string"
+            },
+            "last_completed_iteration": {
+                "type": "integer",
+                "minimum": 0,
+                "maximum": 9007199254740991
             }
         },
         "required": [