brainclaw 1.8.0 → 1.9.0

package/dist/core/context-diff.js

@@ -2,10 +2,9 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { readAuditLog } from './audit.js';
 import { listCandidates } from './candidates.js';
-import { readContextMarker } from './freshness.js';
-import { memoryDir, resolveEntityDir } from './io.js';
-import { logger } from './logger.js';
+import { resolveEntityDir } from './io.js';
 import { loadVersionedJsonFile } from './migration.js';
+import { buildNotificationSummary, hasEventCursor, readUnseenEvents, seedCursorToEnd } from './event-log.js';
 import { SessionSnapshotSchema } from './schema.js';
 import { loadState } from './state.js';
 export function resolveContextDiffSince(options) {
@@ -23,10 +22,10 @@ export function resolveContextDiffSince(options) {
         }
         return { since_session: options.session };
     }
-    const marker = readContextMarker(options.cwd);
-    if (marker?.read_at) {
-        return { since: marker.read_at };
-    }
+    // No global marker fallback: the "what's new" default lives on the
+    // per-agent event-log cursors (buildContextDiffFromEvents). The store-global
+    // .last-context marker cross-contaminated agents — one agent's read reset
+    // everyone's diff baseline.
     return {};
 }
 function loadSessionSnapshot(sessionId, cwd) {
@@ -66,33 +65,160 @@ export function buildContextDiff(options = {}) {
         decisions: decisions.length,
         traps: traps.length,
         handoffs: handoffs.length,
+        plans: 0,
         pending_candidates: pendingCandidates.length,
         total: constraints.length + decisions.length + traps.length + handoffs.length + pendingCandidates.length,
     };
     return {
         since: resolved.since,
         since_session: resolved.since_session,
+        source: 'timestamp',
         summary: buildContextDiffSummary(counts),
         counts,
         changed_items: changedItems,
     };
 }
-export function readLastContextTimestamp(cwd) {
-    const marker = readContextMarker(cwd);
-    if (marker?.read_at) {
-        return marker.read_at;
+const EVENT_SECTION_BY_ITEM_TYPE = {
+    constraint: 'constraint',
+    decision: 'decision',
+    trap: 'trap',
+    handoff: 'handoff',
+    candidate: 'candidate',
+    plan: 'plan',
+};
+const EVENT_ACTION_LABEL = {
+    create: 'created',
+    update: 'updated',
+    delete: 'deleted',
+    accept: 'accepted',
+    reject: 'rejected',
+};
+/**
+ * Build a per-agent "what's new" diff from the event-log cursors
+ * (src/core/event-log.ts). This is the converged novelty mechanism: it
+ * replaces the store-global .last-context marker for the default diff path
+ * and natively covers status transitions (logged as `update` events by
+ * bclaw_transition / bclaw_update via the audit→event bridge).
+ *
+ * NOTE: reading ADVANCES the agent's cursor — events surfaced here are
+ * considered seen. Returns undefined when there is nothing new.
+ *
+ * First contact (no cursor for this agent yet): the diff would otherwise
+ * replay the ENTIRE event log from genesis — on a mature store that means
+ * thousands of stale claim/session events summarized into noise, and the
+ * agent's single chance to triage history is consumed by the cursor advance.
+ * Instead we emit a curated arrival digest (active constraints/traps,
+ * in-progress plans, latest open handoffs) and seed the cursor at log end so
+ * subsequent diffs are genuinely incremental.
+ */
+export function buildContextDiffFromEvents(agent, cwd, options = {}) {
+    if (!hasEventCursor(agent, cwd)) {
+        return buildArrivalDigest(agent, cwd, options);
     }
-    const markerPath = path.join(memoryDir(cwd), '.last-context');
-    if (fs.existsSync(markerPath)) {
-        try {
-            const parsed = JSON.parse(fs.readFileSync(markerPath, 'utf-8'));
-            return parsed.read_at;
-        }
-        catch (error) {
-            logger.debug('Failed to parse context marker fallback:', error);
+    const events = readUnseenEvents(agent, cwd);
+    if (events.length === 0) {
+        return undefined;
+    }
+    // Latest relevant event per item (an item created then updated counts once).
+    const latestByItem = new Map();
+    for (const event of events) {
+        if (!event.item_id)
+            continue;
+        if (!EVENT_SECTION_BY_ITEM_TYPE[event.item_type] || !EVENT_ACTION_LABEL[event.action])
+            continue;
+        latestByItem.set(event.item_id, event);
+    }
+    const state = loadState(cwd);
+    const pendingCandidates = listCandidates('pending', cwd);
+    const textById = new Map();
+    for (const collection of [state.active_constraints, state.recent_decisions, state.known_traps, state.open_handoffs, state.plan_items, pendingCandidates]) {
+        for (const item of collection) {
+            textById.set(item.id, { text: item.text, created_at: item.created_at });
         }
     }
-    return undefined;
+    const counts = { constraints: 0, decisions: 0, traps: 0, handoffs: 0, plans: 0, pending_candidates: 0, total: 0 };
+    const sectionToCountKey = {
+        constraint: 'constraints',
+        decision: 'decisions',
+        trap: 'traps',
+        handoff: 'handoffs',
+        plan: 'plans',
+        candidate: 'pending_candidates',
+    };
+    const changedItems = [];
+    for (const [itemId, event] of latestByItem) {
+        const section = EVENT_SECTION_BY_ITEM_TYPE[event.item_type];
+        const current = textById.get(itemId);
+        counts[sectionToCountKey[section]] += 1;
+        counts.total += 1;
+        changedItems.push({
+            section,
+            id: itemId,
+            text: current?.text ?? event.summary ?? `(${EVENT_ACTION_LABEL[event.action]} — no longer in state)`,
+            created_at: event.ts,
+            action: EVENT_ACTION_LABEL[event.action],
+        });
+    }
+    changedItems.sort((a, b) => b.created_at.localeCompare(a.created_at));
+    const oldest = events[0]?.ts;
+    return {
+        since: oldest,
+        source: 'event_cursor',
+        summary: buildContextDiffSummary(counts),
+        counts,
+        changed_items: options.includeItems === false ? undefined : changedItems,
+        event_summary: buildNotificationSummary(events),
+        unseen_event_count: events.length,
+    };
+}
+/** Hard cap on arrival-digest items — the digest informs, it must not drown. */
+const ARRIVAL_DIGEST_MAX_ITEMS = 12;
+const ARRIVAL_DIGEST_MAX_HANDOFFS = 3;
+/**
+ * First-contact digest for an agent arriving on a store it has never read.
+ * Curated active state (constraints, traps, in-progress plans, latest open
+ * handoffs) instead of an event-log replay; seeds the agent's cursor at the
+ * end of the log so the next diff is incremental. Returns undefined only when
+ * there is nothing to say (empty store with no event history) — that case is
+ * the bootstrap hint's job, not the diff's.
+ */
+export function buildArrivalDigest(agent, cwd, options = {}) {
+    const skippedBytes = seedCursorToEnd(agent, cwd);
+    const state = loadState(cwd);
+    const constraints = state.active_constraints.filter((item) => (item.status ?? 'active') === 'active');
+    const traps = state.known_traps.filter((item) => (item.status ?? 'active') === 'active');
+    const plans = state.plan_items.filter((item) => item.status === 'in_progress');
+    const handoffs = state.open_handoffs
+        .filter((item) => (item.status ?? 'open') === 'open')
+        .sort((a, b) => b.created_at.localeCompare(a.created_at))
+        .slice(0, ARRIVAL_DIGEST_MAX_HANDOFFS);
+    const counts = {
+        constraints: constraints.length,
+        decisions: 0,
+        traps: traps.length,
+        handoffs: handoffs.length,
+        plans: plans.length,
+        pending_candidates: 0,
+        total: constraints.length + traps.length + plans.length + handoffs.length,
+    };
+    if (counts.total === 0 && skippedBytes === 0) {
+        return undefined;
+    }
+    const changedItems = [
+        ...constraints.map((item) => toChangedItem('constraint', item)),
+        ...traps.map((item) => toChangedItem('trap', item)),
+        ...plans.map((item) => toChangedItem('plan', item)),
+        ...handoffs.map((item) => toChangedItem('handoff', item)),
+    ].slice(0, ARRIVAL_DIGEST_MAX_ITEMS);
+    const skippedKb = Math.round(skippedBytes / 1024);
+    const stateSummary = counts.total > 0 ? buildContextDiffSummary(counts) : 'no active items';
+    const summary = `First contact — arrival digest: ${stateSummary}. Event history skipped (${skippedKb} KB); cursor initialized at log end, future diffs are incremental.`;
+    return {
+        source: 'arrival_digest',
+        summary,
+        counts,
+        changed_items: options.includeItems === false ? undefined : changedItems,
+    };
 }
 export function buildContextDiffSummary(counts) {
     if (counts.total === 0) {
@@ -107,6 +233,8 @@ export function buildContextDiffSummary(counts) {
         parts.push(`${counts.traps} trap${counts.traps > 1 ? 's' : ''}`);
     if (counts.handoffs > 0)
         parts.push(`${counts.handoffs} handoff${counts.handoffs > 1 ? 's' : ''}`);
+    if (counts.plans > 0)
+        parts.push(`${counts.plans} plan${counts.plans > 1 ? 's' : ''}`);
     if (counts.pending_candidates > 0)
         parts.push(`${counts.pending_candidates} pending candidate${counts.pending_candidates > 1 ? 's' : ''}`);
     return parts.join(', ');

package/dist/core/context.js

@@ -7,7 +7,7 @@ import { checkBrainclawInstallableUpdate, renderBrainclawInstallableUpdateNotice
 import { loadConfig } from './config.js';
 import { loadCurrentSession, loadAllSessions } from './identity.js';
 import { resolveCrossProjectLinks, loadCrossProjectState } from './cross-project.js';
-import { buildContextDiff } from './context-diff.js';
+import { buildContextDiff, buildContextDiffFromEvents } from './context-diff.js';
 import { resolveContextStoreCwd, resolveStoreChain } from './store-resolution.js';
 import { findAgentIdentityByName, resolveCurrentAgentIdentity } from './agent-registry.js';
 import { hasReusableBootstrapProfile, runBootstrapProfile, selectDerivedSignals } from './bootstrap.js';
@@ -17,11 +17,13 @@ import { getVisibleMemoryVersion } from './freshness.js';
 import { resolveCurrentHostId } from './host.js';
 import { inferProjectFromTarget, loadInstructions, resolveInstructions } from './instructions.js';
 import { buildCurrentAgentResumeSummary, buildReputationRankingLookup } from './reputation.js';
+import { buildMemoryLifecycleMetricsForState, getLifecycleStats } from './memory-lifecycle.js';
 import { loadState } from './state.js';
 import { readAuditLog } from './audit.js';
 import { listCandidates } from './candidates.js';
 import { listClaims, isClaimExpired, assessClaimLiveness } from './claims.js';
 import { listAssignments } from './assignments.js';
+import { reconcileOrphanedLoopAssignmentsFromList } from './assignment-reconciler.js';
 import { listRuntimeNotes } from './runtime.js';
 import { isTrapActive, listOperationalTraps } from './traps.js';
 import { buildEstimationReport } from '../commands/estimation-report.js';
@@ -102,6 +104,16 @@ export function buildContext(options = {}) {
                 host_id: c.host_id,
                 session_id: c.session_id,
             },
+            lifecycle: {
+                entity: 'constraint',
+                created_at: c.created_at,
+                last_confirmed_at: c.last_confirmed_at,
+                last_infirmed_at: c.last_infirmed_at,
+                confirmation_count: c.confirmation_count,
+                infirmation_count: c.infirmation_count,
+                saved_me_count: c.saved_me_count,
+                misled_me_count: c.misled_me_count,
+            },
         });
     }
     for (const d of state.recent_decisions) {
@@ -122,6 +134,16 @@ export function buildContext(options = {}) {
                 host_id: d.host_id,
                 session_id: d.session_id,
             },
+            lifecycle: {
+                entity: 'decision',
+                created_at: d.created_at,
+                last_confirmed_at: d.last_confirmed_at,
+                last_infirmed_at: d.last_infirmed_at,
+                confirmation_count: d.confirmation_count,
+                infirmation_count: d.infirmation_count,
+                saved_me_count: d.saved_me_count,
+                misled_me_count: d.misled_me_count,
+            },
         });
     }
     for (const t of state.known_traps.filter((trap) => isTrapActive(trap))) {
@@ -142,6 +164,16 @@ export function buildContext(options = {}) {
                 host_id: t.host_id,
                 session_id: t.session_id,
             },
+            lifecycle: {
+                entity: 'trap',
+                created_at: t.created_at,
+                last_confirmed_at: t.last_confirmed_at,
+                last_infirmed_at: t.last_infirmed_at,
+                confirmation_count: t.confirmation_count,
+                infirmation_count: t.infirmation_count,
+                saved_me_count: t.saved_me_count,
+                misled_me_count: t.misled_me_count,
+            },
         });
     }
     for (const trap of listOperationalTraps({ hostId: options.host, includeAllHosts: options.allHosts }, contextCwd).filter((entry) => isTrapActive(entry))) {
@@ -371,6 +403,21 @@ export function buildContext(options = {}) {
                 item.reasons = uniqueReasons([...item.reasons, `reputation signal:+${trustBonus.toFixed(2)}`]);
             }
         }
+        // pln#544 — memory lifecycle: items confirmed-recent + reinforced rise;
+        // stale-unconfirmed and explicitly-infirmed sink in the same ranking.
+        // Only items we tagged with a lifecycle payload (primary-store decision/
+        // constraint/trap) carry a delta — parent-store items rank by other signals.
+        if (item.score >= 0 && item.lifecycle) {
+            const stats = getLifecycleStats(item.lifecycle);
+            if (stats.ranking_delta !== 0) {
+                item.score += stats.ranking_delta;
+                const sign = stats.ranking_delta >= 0 ? '+' : '';
+                item.reasons = uniqueReasons([
+                    ...item.reasons,
+                    `lifecycle ${stats.classification}:${sign}${stats.ranking_delta}`,
+                ]);
+            }
+        }
         // Layer 3: boost machine-scoped items for broader visibility (+1)
         if (item.score >= 0) {
             const itemScope = item.scope;
@@ -393,7 +440,10 @@ export function buildContext(options = {}) {
         runtimeNotes,
         pendingCandidates: listCandidates('pending', contextCwd),
     });
-    const memoryDensity = classifyMemoryDensity(selected.length);
+    // Density reflects what the store HAS, not what the char budget keeps:
+    // classify pre-budget so a tight budget_tokens on a rich store never
+    // misreads as 'low' and triggers a bootstrap re-scan (pln#542 interaction).
+    const memoryDensity = classifyMemoryDensity(ranked.length);
     const bootstrapEnabled = options.bootstrap !== false;
     const testMode = process.env.BRAINCLAW_TEST_MODE === '1';
     let bootstrapAvailable = false;
@@ -445,7 +495,19 @@ export function buildContext(options = {}) {
     const currentSession = loadCurrentSession(contextCwd);
     if (currentAgentIdentity || agent) {
         const claimPlanIds = new Set(myClaims.map((c) => c.plan_id).filter(Boolean));
-        const activeAssignments = listAssignments(contextCwd, { agent: agentName }).filter((assignment) => !['completed', 'failed', 'cancelled', 'expired', 'rerouted'].includes(assignment.status));
+        // pln#563 layer B: converge review-loop assignments orphaned in
+        // offered/accepted/started whose loop is already terminal, before listing
+        // active work. Reuse one assignment scan for reconcile and rendering;
+        // best-effort (swallow errors); steady state is zero writes.
+        const allAssignments = listAssignments(contextCwd);
+        let reconciledAssignmentIds = new Set();
+        try {
+            reconciledAssignmentIds = new Set(reconcileOrphanedLoopAssignmentsFromList(allAssignments, contextCwd));
+        }
+        catch { /* read path must not break on reconcile */ }
+        const activeAssignments = allAssignments.filter((assignment) => assignment.agent === agentName
+            && !reconciledAssignmentIds.has(assignment.id)
+            && !['completed', 'failed', 'cancelled', 'expired', 'rerouted', 'timed_out'].includes(assignment.status));
         const inProgressPlans = state.plan_items.filter((p) => p.status === 'in_progress' &&
             (p.assignee === agentName || claimPlanIds.has(p.id)));
         if (myClaims.length > 0 || activeAssignments.length > 0 || inProgressPlans.length > 0) {
@@ -524,13 +586,46 @@ export function buildContext(options = {}) {
     let staleWarnings;
     try {
         const pendingCandidatesForStaleness = listCandidates('pending', contextCwd);
-        const runtimeNotesForStaleness = listRuntimeNotes(undefined, contextCwd);
-        const staleReport = detectStaleness(state.plan_items, state.known_traps, state.open_handoffs, pendingCandidatesForStaleness, Date.now(), runtimeNotesForStaleness);
+        // pln#564 step A — reuse the runtime notes already loaded above (line ~316)
+        // instead of a second unfiltered full scan of the runtime-note tree. On a
+        // store with thousands of notes that 2nd scan dominated buildContext cost
+        // (readAgentNotes ~11s / 6166 files, trp_439fec51). The earlier list is the
+        // broader one (honours options.host/allHosts), so staleness is at least as
+        // complete as before.
+        const runtimeNotesForStaleness = runtimeNotes;
+        const staleReport = detectStaleness(state.plan_items, state.known_traps, state.open_handoffs, pendingCandidatesForStaleness, Date.now(), runtimeNotesForStaleness, 
+        // pln#557 step 2 — dead related_paths detection. Surfaces "confident
+        // but wrong" memory (paths deleted by a refactor) in stale_warnings,
+        // which both the steady-state context and the arrival digest carry.
+        {
+            decisions: state.recent_decisions,
+            constraints: state.active_constraints,
+            projectRoot: contextCwd,
+        });
         if (staleReport.warnings.length > 0) {
             staleWarnings = staleReport.warnings.slice(0, 5);
         }
     }
     catch { /* non-fatal */ }
+    // pln#544 — memory lifecycle metrics. Best-effort: build once, surface in
+    // the result + thread to workflow_hints so the curation hint can quote the
+    // oldest unconfirmed id. Empty stores still pass through (total_items=0).
+    let memoryLifecycleMetrics;
+    try {
+        memoryLifecycleMetrics = buildMemoryLifecycleMetricsForState(state);
+    }
+    catch {
+        memoryLifecycleMetrics = {
+            total_items: 0,
+            confirmed_items: 0,
+            confirmed_ratio: 0,
+            average_age_days: 0,
+            total_saved_me: 0,
+            total_misled_me: 0,
+            total_infirmed_active: 0,
+            recall_precision_proxy: 0,
+        };
+    }
     const result = {
         context_schema: CONTEXT_SCHEMA_VERSION,
         profile,
@@ -552,13 +647,19 @@ export function buildContext(options = {}) {
         execution_context: executionContext,
         agent_tooling: agentTooling,
         scoped_activity: scopedActivity,
+        // "What's new" — explicit session reference keeps the timestamp diff;
+        // otherwise the per-agent event-log cursor is the converged default
+        // (covers status transitions, no store-global marker). Note: the cursor
+        // read marks the surfaced events as seen for this agent.
         context_diff: options.sinceSession
             ? buildContextDiff({
                 session: options.sinceSession,
                 cwd: contextCwd,
                 includeItems: true,
             })
-            : undefined,
+            : agent
+                ? buildContextDiffFromEvents(agent, contextCwd, { includeItems: true })
+                : undefined,
         resolved_instructions: resolvedInstructions,
         resume_summary: resumeSummary,
         open_work: openWork,
@@ -578,8 +679,9 @@ export function buildContext(options = {}) {
         active_project: findActiveProjectInChain(contextCwd, storeChain),
         cross_project_items: crossProjectItems.length > 0 ? crossProjectItems : undefined,
         claim_conflicts: detectClaimConflicts(myClaims, otherActiveClaims),
-        workflow_hints: buildWorkflowHints(myClaims, openWork, state.plan_items),
+        workflow_hints: buildWorkflowHints(myClaims, openWork, state.plan_items, memoryLifecycleMetrics),
         stale_warnings: staleWarnings,
+        memory_lifecycle: memoryLifecycleMetrics.total_items > 0 ? memoryLifecycleMetrics : undefined,
         selected,
     };
     if (options.digest) {
@@ -972,6 +1074,7 @@ export function renderContextPromptTemplate(result, compact = false) {
             lines.push(`    decisions: ${result.context_diff.counts.decisions}`);
             lines.push(`    traps: ${result.context_diff.counts.traps}`);
             lines.push(`    handoffs: ${result.context_diff.counts.handoffs}`);
+            lines.push(`    plans: ${result.context_diff.counts.plans}`);
             lines.push(`    pending_candidates: ${result.context_diff.counts.pending_candidates}`);
             lines.push(`    total: ${result.context_diff.counts.total}`);
         }
@@ -1724,7 +1827,7 @@ function findActiveProjectInChain(contextCwd, _storeChain) {
     return undefined;
 }
 // --- Workflow hints ---
-function buildWorkflowHints(myClaims, openWork, plans) {
+function buildWorkflowHints(myClaims, openWork, plans, memoryLifecycle) {
     const hints = [];
     // No claims — suggest claiming before editing
     if (myClaims.length === 0) {
@@ -1744,6 +1847,24 @@ function buildWorkflowHints(myClaims, openWork, plans) {
             hints.push(`${unclaimedInProgress.length} in-progress plan(s) without a claim — consider claiming the scope you're editing`);
         }
     }
+    // pln#544 — memory curation surfacing. Pick the strongest signal:
+    //  - an oldest unconfirmed item past the half-life-ish horizon, OR
+    //  - an item that an agent flagged as misleading (still active).
+    if (memoryLifecycle && memoryLifecycle.total_items > 0) {
+        if (memoryLifecycle.total_infirmed_active > 0) {
+            hints.push(`${memoryLifecycle.total_infirmed_active} active memory item(s) were infirmed after their last confirmation — review with bclaw_find(status:'active') and consider archiving via bclaw_transition`);
+        }
+        else if (memoryLifecycle.oldest_unconfirmed_id
+            && memoryLifecycle.oldest_unconfirmed_age_days !== undefined
+            && memoryLifecycle.oldest_unconfirmed_age_days >= 30) {
+            const ent = memoryLifecycle.oldest_unconfirmed_entity ?? 'item';
+            hints.push(`Oldest unconfirmed ${ent} ${memoryLifecycle.oldest_unconfirmed_id} is ${memoryLifecycle.oldest_unconfirmed_age_days}d old — confirm or retire when you next encounter it`);
+        }
+        else if (memoryLifecycle.confirmed_ratio < 0.2
+            && memoryLifecycle.total_items >= 10) {
+            hints.push(`Memory health: only ${Math.round(memoryLifecycle.confirmed_ratio * 100)}% of ${memoryLifecycle.total_items} item(s) have been confirmed — start attesting in passing to age memory honestly`);
+        }
+    }
     return hints.length > 0 ? hints : undefined;
 }
 //# sourceMappingURL=context.js.map

package/dist/core/coordination.js

@@ -16,6 +16,7 @@ import { loadAllSessions } from './identity.js';
 import { countActionable } from './messaging.js';
 import { listCandidates } from './candidates.js';
 import { pullSignalsFromLinkedProjects } from './federation-transport.js';
+import { isObserverMode } from './observer-mode.js';
 export function buildCoordinationSnapshot(options = {}) {
     const config = loadConfig(options.cwd);
     const state = loadState(options.cwd);
@@ -58,8 +59,13 @@ export function buildCoordinationSnapshot(options = {}) {
     const filteredHandoffs = agent
         ? openHandoffs.filter((h) => (!project || !h.project || h.project === project) && (h.to === agent || h.from === agent))
         : (project ? openHandoffs.filter((h) => !h.project || h.project === project) : openHandoffs);
-    // perf.2: auto-acknowledge shown handoffs
-    if (options.autoAcknowledge && filteredHandoffs.length > 0) {
+    // perf.2: auto-acknowledge shown handoffs.
+    // Observer mode (BRAINCLAW_OBSERVER=1) suppresses this — a dashboard reading
+    // the board must never mutate the store it observes. The 2026-06-10 lock
+    // storm was caused by the VS Code extension polling kind='board' (which sets
+    // autoAcknowledge=true) and triggering persistState → full store rewrite +
+    // git commit on every refresh.
+    if (options.autoAcknowledge && filteredHandoffs.length > 0 && !isObserverMode()) {
         const toAckIds = new Set(filteredHandoffs.map((h) => h.id));
         let changed = false;
         for (const h of state.open_handoffs) {
@@ -88,7 +94,7 @@ export function buildCoordinationSnapshot(options = {}) {
             : filteredClaims,
         active_assignments: (agent
             ? listAssignments(options.cwd, { agent })
-            : listAssignments(options.cwd)).filter((assignment) => !['completed', 'failed', 'cancelled', 'expired', 'rerouted'].includes(assignment.status) &&
+            : listAssignments(options.cwd)).filter((assignment) => !['completed', 'failed', 'cancelled', 'expired', 'rerouted', 'timed_out'].includes(assignment.status) &&
             (!project || !assignment.plan_id || filteredPlans.some((plan) => plan.id === assignment.plan_id))),
         active_runs: (agent
             ? listAgentRuns(options.cwd, { agent })
@@ -229,6 +235,19 @@ function buildOtherAgentsSummary(claims, notes, currentAgent, cwd) {
     const result = [...agentMap.values()];
     return result.length > 0 ? result : undefined;
 }
+/**
+ * Lightweight cross-project snapshot — linked_projects + incoming_signals only.
+ * Used by the VS Code extension's SYSTEM section so it does not have to fetch
+ * the full coordination snapshot (pln#558 step 3). Loads two linked-project
+ * states plus the incoming-signals scan; never builds the agent/handoff/claim
+ * summaries.
+ */
+export function buildCrossProjectSnapshot(cwd) {
+    return {
+        linked_projects: buildLinkedProjectsSummary(cwd),
+        incoming_signals: buildIncomingSignalsSummary(cwd),
+    };
+}
 function buildLinkedProjectsSummary(cwd) {
     const links = resolveCrossProjectLinks(cwd);
     if (links.length === 0)

package/dist/core/dispatch-status.js

@@ -20,15 +20,44 @@
  */
 import fs from 'node:fs';
 import path from 'node:path';
+import { execFileSync } from 'node:child_process';
 import { loadAssignment, listAssignments } from './assignments.js';
+import { logger } from './logger.js';
 import { loadAgentRun, listAgentRuns } from './agentruns.js';
 import { loadClaim } from './claims.js';
 import { getLoop, listLoops } from './loops/store.js';
 import { isProcessAlive } from './agentrun-reconciler.js';
-import { latestActivityMs } from './runtime-signals.js';
+import { findRuntimeNoteById } from './runtime.js';
+import { latestActivityMs, decodeOemAwareBuffer } from './runtime-signals.js';
 import { LaneResultSchema } from './schema.js';
 const DEFAULT_TAIL = 20;
 const DEFAULT_STALL_MS = 5 * 60_000;
+const DEFAULT_BASE_REF = 'master';
+/**
+ * pln#554 — worktree git evidence, the signal that beats process/administrative
+ * status: a worker that committed everything to its lane branch has DELIVERED,
+ * whatever its pid/heartbeat/assignment.status say. Shared by dispatch-status
+ * and `brainclaw dispatch watch`. Returns undefined when there is no worktree
+ * or git could not be queried (never conclude "no commits" from a failed read).
+ */
+export function gitEvidence(worktreePath, baseRef) {
+    if (!worktreePath)
+        return undefined;
+    try {
+        const ahead = execFileSync('git', ['-C', worktreePath, 'rev-list', '--count', `${baseRef}..HEAD`], {
+            encoding: 'utf-8', timeout: 15000,
+        }).trim();
+        const status = execFileSync('git', ['-C', worktreePath, 'status', '--short'], {
+            encoding: 'utf-8', timeout: 15000,
+        });
+        const dirty = status.split('\n').filter((l) => l.trim() && !l.startsWith('??')).length;
+        return { commitsAhead: Number.parseInt(ahead, 10) || 0, dirtyTracked: dirty };
+    }
+    catch (err) {
+        logger.debug('dispatch status: git evidence unavailable:', err);
+        return undefined;
+    }
+}
 // ── Internal helpers ──────────────────────────────────────────────────────
 function readLogTail(filePath, lines) {
     try {
@@ -36,7 +65,9 @@ function readLogTail(filePath, lines) {
         if (lines <= 0) {
             return { path: filePath, exists: true, size_bytes: stat.size };
         }
-        const content = fs.readFileSync(filePath, 'utf-8');
+        // can_c39f0961: Windows-native tools write OEM cp850 — decode-aware read
+        // instead of blind utf-8 so the tail is human-readable.
+        const content = decodeOemAwareBuffer(fs.readFileSync(filePath));
         const all = content.split(/\r?\n/);
         // Strip trailing empty line from final \n
         if (all.length > 0 && all[all.length - 1] === '')
@@ -155,6 +186,18 @@ function computeDiagnosis(assignment, agentRun, runtime, options) {
                 : `Worker reported "${lr.status}". Read the LANE-RESULT summary + stderr; address the blocker or reroute.`,
         };
     }
+    // pln#554 — git evidence is the #2 signal, ABOVE process sentinels and
+    // administrative status: commits ahead of base with a clean tracked tree
+    // means the worker delivered everything to the branch, even if its pid is
+    // dead, its heartbeat stale, or the run was relabeled interrupted by a TTL
+    // sweep (can_948acfd6). The verdict is "harvest it" — never "kill and reroute".
+    if ((runtime.commits_ahead ?? 0) > 0 && runtime.dirty_tracked === 0) {
+        return {
+            health: 'terminal',
+            summary: `worker delivered: ${runtime.commits_ahead} commit(s) ahead of base with a clean tracked tree — everything is on the lane branch${agentRun && !TERMINAL_RUN_STATUSES.has(agentRun.status) ? ` (agent_run still ${agentRun.status}; exit formalities missing — harvest reconciles it)` : ''}`,
+            recommended_next_action: 'Worker delivered; harvest it: `brainclaw harvest <assignment_id>` to ingest and merge the lane branch. Do NOT kill or reroute.',
+        };
+    }
     if (!agentRun) {
         return {
             health: 'not_dispatched',
@@ -234,7 +277,15 @@ export function getDispatchStatus(options) {
     const resolved = resolveTarget(options.target_id, cwd);
     const assignmentId = resolved.assignment_id;
     const assignment = assignmentId ? loadAssignment(assignmentId, cwd) : undefined;
-    const claim = assignment?.claim_id ? loadClaim(assignment.claim_id, cwd) : undefined;
+    // loadClaim THROWS on a missing id — a GC'd/never-created claim must not
+    // crash the whole diagnostic (sprint 1.5).
+    let claim;
+    if (assignment?.claim_id) {
+        try {
+            claim = loadClaim(assignment.claim_id, cwd);
+        }
+        catch { /* claim gone — diagnose without it */ }
+    }
     // Prefer the pre-resolved agent_run (when target_id was a run_…); otherwise
     // look up by assignment_id and pick the most recent attempt.
     let agentRun = resolved.agent_run;
@@ -260,7 +311,11 @@ export function getDispatchStatus(options) {
     // pln#527 — filesystem-activity age: max mtime across the captured logs + the
     // run's worktree files (skipping junctions). The truer liveness signal when
     // the heartbeat / last_event_at is stale during a long single operation.
-    const worktreeForFs = agentRun?.worktree_path ?? claim?.worktree_path;
+    // can_948acfd6: also fall back to assignment.worktree_path — without it a
+    // LANE-RESULT.json sitting in the assignment's worktree was invisible when
+    // neither the run nor the claim carried the path, and the verdict degraded
+    // to 'read stderr for failure detail' despite a completed lane result.
+    const worktreeForFs = agentRun?.worktree_path ?? claim?.worktree_path ?? assignment?.worktree_path;
     let lastFsActivityMs;
     if (assignmentId) {
         const lastFs = latestActivityMs(projectRoot, assignmentId, worktreeForFs);
@@ -277,6 +332,8 @@ export function getDispatchStatus(options) {
         }
         catch { /* no / invalid LANE-RESULT.json */ }
     }
+    // pln#554 — worktree git evidence (commits ahead of base + dirty tracked files).
+    const evidence = gitEvidence(worktreeForFs, options.base_ref ?? DEFAULT_BASE_REF);
     const runtime = {
         pid: agentRun?.pid,
         pid_alive: isProcessAlive(agentRun?.pid),
@@ -290,8 +347,25 @@ export function getDispatchStatus(options) {
         },
         last_fs_activity_ms: lastFsActivityMs,
         lane_result: laneResult,
+        commits_ahead: evidence?.commitsAhead,
+        dirty_tracked: evidence?.dirtyTracked,
     };
-    const diagnosis = computeDiagnosis(assignment, agentRun, runtime, { stallMs, nowMs });
+    let diagnosis = computeDiagnosis(assignment, agentRun, runtime, { stallMs, nowMs });
+    // can_b8d53d18 — a `run_` target that resolves to nothing may be a LEGACY
+    // runtime_note id (pre-rtn_ prefix collision). Say so precisely instead of
+    // the generic "verify the target_id" message.
+    if (resolved.resolved_from === 'unresolved' && options.target_id.startsWith('run_')) {
+        try {
+            if (findRuntimeNoteById(options.target_id, {}, cwd)) {
+                diagnosis = {
+                    health: 'unknown',
+                    summary: `${options.target_id} is a runtime_note (legacy run_ id prefix), not an agent_run — nothing to dispatch-diagnose`,
+                    recommended_next_action: 'Read it with bclaw_get(entity="runtime_note"). Run `brainclaw repair` to migrate legacy run_ note ids to rtn_.',
+                };
+            }
+        }
+        catch { /* diagnosis stays generic */ }
+    }
     return {
         target_id: options.target_id,
         resolved_from: resolved.resolved_from,