brainclaw 1.8.0 → 1.9.1

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

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