brainclaw 1.28.1 → 1.28.3

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.js

@@ -39,7 +39,7 @@ import { ensureTrust, resolveMutationIdentity, explicitSessionIdFromEnv, project
 // point: it imports the extracted modules for its own use and re-exports the
 // full historical surface below so external importers are unaffected.
 // ---------------------------------------------------------------------------
-import { SCHEMA_VERSION, MCP_PROTOCOL_VERSIONS, MCP_SERVER_NOT_INITIALIZED, toolResponse, createToolErrorResponse, } from './mcp-contract.js';
+import { MCP_PROTOCOL_VERSIONS, MCP_SERVER_NOT_INITIALIZED, toolResponse, createToolErrorResponse, } from './mcp-contract.js';
 import { MCP_READ_TOOLS, PUBLISHED_TOOLS, DEFAULT_PUBLISHED_TOOLS, UNINITIALIZED_TOOL_NAMES, UNINITIALIZED_PUBLISHED_TOOLS, buildUninitializedStateMessage, LEGACY_READ_TOOL_HANDLERS, } from './mcp-catalog.js';
 // Claim/assignment write handlers extracted in pln#622 PR3b. The shared write
 // helpers (ensureTrust, resolveExecutionWriteTarget, …) stay here and are
@@ -227,7 +227,10 @@ export function createInitializeResult(protocolVersion, options) {
     const uninitialized = options?.uninitialized === true;
     return {
         protocolVersion,
-        serverInfo: { name: 'brainclaw', version: SCHEMA_VERSION },
+        // MCP serverInfo.version is the running PRODUCT version. SCHEMA_VERSION
+        // belongs to tool envelopes and made stale processes impossible to
+        // distinguish during the DGX 1.28.0→1.28.1 dogfood.
+        serverInfo: { name: 'brainclaw', version: getInstalledBrainclawVersion() },
         // listChanged is only advertised in setup mode, where the catalog flips
         // to the full set once the project memory is initialized.
         capabilities: { tools: { listChanged: uninitialized } },
@@ -1093,18 +1096,47 @@ 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({
                         content: [{ type: 'text', text: `Code Map: ${status.store_exists ? 'store present' : 'no store'} — freshness=${status.freshness_badge.freshness}` }],
-                        structuredContent: { ...status, freshness_badge: status.freshness_badge },
+                        structuredContent: {
+                            ...status,
+                            freshness_badge: status.freshness_badge,
+                            mcp_resolution: {
+                                active_source: scopeInfo.active_source,
+                                resolved_project: scopeInfo.resolved_project,
+                                server_version: getInstalledBrainclawVersion(),
+                                disk_version: diskVersion,
+                                restart_required: diskVersion !== '0.0.0' && diskVersion !== getInstalledBrainclawVersion(),
+                            },
+                        },
                     }),
                 };
             }
             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({
@@ -1119,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}` }],
@@ -1140,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}` }],
@@ -1156,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}` }],
@@ -1171,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}` }],
@@ -1185,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}` }],
@@ -1457,10 +1489,24 @@ async function _executeMcpToolCallInner(payload) {
                             const full = candidateIds
                                 .map((id) => loadAssignment(id, targetCwd))
                                 .filter((a) => a !== undefined);
-                            sweepAssignmentsAtReadPath(full, targetCwd, {
+                            const sweep = sweepAssignmentsAtReadPath(full, targetCwd, {
                                 actor: 'bclaw_work-readpath',
                                 policy,
                             });
+                            // The context snapshot was built before the lazy sweep. Reflect
+                            // the same-pass mutations so bclaw_work never serves a fossil as
+                            // active once it has just expired/timed it out on disk.
+                            const parked = new Set([
+                                ...sweep.expired.map((item) => item.assignment_id),
+                                ...sweep.timed_out.map((item) => item.assignment_id),
+                            ]);
+                            const advanced = new Map(sweep.implicitly_advanced.map((item) => [item.assignment_id, item.to]));
+                            contextResult.open_work.active_assignments = openAssignments
+                                .filter((assignment) => !parked.has(assignment.id))
+                                .map((assignment) => {
+                                const status = advanced.get(assignment.id);
+                                return status ? { ...assignment, status } : assignment;
+                            });
                         }
                         const registry = loadServeRegistry(targetCwd);
                         const aged = ageStaleWarnings(contextResult.stale_warnings ?? [], targetCwd, { policy, registry });

package/dist/core/agentrun-reconciler.js

@@ -36,7 +36,7 @@ import { spawnSync } from 'node:child_process';
 import fs from 'node:fs';
 import { loadAgentRun, recordExecutionContractAnomaly, transitionAgentRun, listAgentRuns } from './agentruns.js';
 import { loadClaim, releaseClaim } from './claims.js';
-import { loadAssignment } from './assignments.js';
+import { convergeAssignmentToTerminal, loadAssignment, transitionAssignment } from './assignments.js';
 import { createRuntimeEvent } from './events.js';
 import { nowISO } from './ids.js';
 import { readContractAck, readHeartbeat, readLogTail, signalExists, latestActivityMs, readCompletionSignals } from './runtime-signals.js';
@@ -44,7 +44,7 @@ import { validateWorkerContractAcceptance } from './execution-contract.js';
 import { findReservationByRunId, evidenceMatchesAttempt, launchGrant, revokeLaunchGrant } from './loops/attempt-reservation.js';
 import { executionContractForGeneration } from './loops/attempt-authority.js';
 import { readLaunchDecision, resolveTurnGenerationChain } from './loops/attempt-generations.js';
-import { reconcileFailedTurn } from './loops/reconcile-turn.js';
+import { reconcileFailedTurn, reconcileLaneResultForRun } from './loops/reconcile-turn.js';
 // ── Constants ──────────────────────────────────────────────────────────────
 /**
  * Minimum age before a run is eligible for reconciliation. Below this, the
@@ -76,6 +76,47 @@ export const DEFAULT_HEARTBEAT_STALE_MS = 10 * 60_000;
 const TERMINAL_STATUSES = new Set([
     'completed', 'failed', 'cancelled', 'timed_out', 'interrupted',
 ]);
+/** Shared business-result bridge for every lazy AgentRun read path. */
+function reconcileOwnedLaneResultAtRead(run, evidence, cwd, actor) {
+    if (!evidence.turn_owned)
+        return undefined;
+    const lane = reconcileLaneResultForRun(run, cwd ?? process.cwd(), actor);
+    if (!lane.found)
+        return undefined;
+    if (!lane.valid || !lane.result?.reconciled) {
+        return { withheld_reason: `lane_result_withheld: ${lane.reason}` };
+    }
+    const after = loadAgentRun(run.id, cwd) ?? run;
+    return { result: {
+            run_id: run.id,
+            action: 'reconciled_turn',
+            reason: `lane_result_reconciled: ${lane.reason}`,
+            evidence,
+            previous_status: run.status,
+            current_status: after.status,
+        },
+    };
+}
+/** A malformed/foreign business result withholds success, but it must not mask
+ * independent, conclusive failure evidence forever. */
+function settleWithheldLaneFailure(run, evidence, actor, cwd, reason) {
+    try {
+        transitionAgentRun(run.id, 'failed', { actor, status_reason: reason }, cwd);
+        convergeAssignmentFromRun(run, 'failed', evidence, actor, cwd);
+        cascadeReleaseOnFailure(run, actor, cwd, 'failed', reason);
+        return { run_id: run.id, action: 'inferred_failed', reason, evidence, previous_status: run.status, current_status: 'failed' };
+    }
+    catch (err) {
+        return {
+            run_id: run.id,
+            action: 'no_op',
+            reason: `failure transition rejected: ${err instanceof Error ? err.message : String(err)}`,
+            evidence,
+            previous_status: run.status,
+            current_status: run.status,
+        };
+    }
+}
 // ── Process liveness ───────────────────────────────────────────────────────
 /**
  * Cross-platform "is this PID alive" check. `process.kill(pid, 0)` does NOT
@@ -309,6 +350,32 @@ export function collectEvidence(run, cwd, options) {
 function fsActiveWithin(evidence, windowMs) {
     return evidence.fs_activity_age_ms !== undefined && evidence.fs_activity_age_ms < windowMs;
 }
+/** Align a non-turn-owned Assignment with conclusive runtime evidence. */
+function convergeAssignmentFromRun(run, outcome, evidence, actor, cwd) {
+    if (findReservationByRunId(run.id, cwd))
+        return false;
+    const assignment = loadAssignment(run.assignment_id, cwd);
+    if (!assignment || ['completed', 'failed', 'blocked', 'timed_out', 'cancelled', 'expired', 'rerouted'].includes(assignment.status)) {
+        return false;
+    }
+    if (outcome === 'completed') {
+        // A released claim alone is not business proof of successful work.
+        if (!evidence.completed_signal && !evidence.has_post_start_commit && !evidence.assignment_completed)
+            return false;
+        return convergeAssignmentToTerminal(assignment.id, 'completed', `agent_run ${run.id} completed from authoritative runtime evidence`, cwd);
+    }
+    try {
+        transitionAssignment(assignment.id, 'failed', {
+            actor,
+            syncAgentRun: false,
+            status_reason: `agent_run ${run.id} failed from liveness reconciliation`,
+        }, cwd);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * trp#433 — when a run is reconciled to `failed` (silent_death / stalled), release
  * its linked claim so dead runs stop leaving active claims (and their worktrees)
@@ -542,6 +609,15 @@ export function reconcileAgentRun(runId, cwd, options = {}) {
     }
     const previous_status = run.status;
     const evidence = collectEvidence(run, cwd, { nowMs: options.nowMs });
+    const actor = options.actor ?? 'reconciler';
+    // pln#692 P0 — LANE-RESULT is the worker's business outcome, not merely a
+    // process-liveness hint. Reconcile it before the terminal-run short circuit
+    // and before generic sentinel completion so a replay heals every projection
+    // (slot, assignment, run, claim) and malformed/foreign results cannot leave
+    // only the run marked completed.
+    const laneResult = reconcileOwnedLaneResultAtRead(run, evidence, cwd, actor);
+    if (laneResult?.result)
+        return laneResult.result;
     // Never touch terminal runs — they already converged.
     if (TERMINAL_STATUSES.has(run.status)) {
         return {
@@ -549,6 +625,33 @@ export function reconcileAgentRun(runId, cwd, options = {}) {
             evidence, previous_status, current_status: run.status,
         };
     }
+    if (laneResult?.withheld_reason) {
+        const stale = options.staleAfterMs ?? DEFAULT_STALE_AFTER_MS;
+        const heartbeatStale = options.heartbeatStaleMs ?? DEFAULT_HEARTBEAT_STALE_MS;
+        const conclusiveFailure = evidence.failed_signal
+            ? 'wrapper reported non-zero exit'
+            : evidence.heartbeat_exists
+                && evidence.heartbeat_age_ms !== undefined
+                && evidence.heartbeat_age_ms >= heartbeatStale
+                && !fsActiveWithin(evidence, heartbeatStale)
+                ? `heartbeat stalled for ${Math.round(evidence.heartbeat_age_ms / 1000)}s`
+                : evidence.process_alive === false
+                    && evidence.age_ms >= stale
+                    && !fsActiveWithin(evidence, heartbeatStale)
+                    ? 'silent termination past stale window'
+                    : undefined;
+        if (conclusiveFailure) {
+            return settleWithheldLaneFailure(run, evidence, actor, cwd, `invalid_lane_result_with_conclusive_failure: ${conclusiveFailure}; ${laneResult.withheld_reason}`);
+        }
+        return {
+            run_id: run.id,
+            action: 'health_check_unverified',
+            reason: laneResult.withheld_reason,
+            evidence,
+            previous_status: run.status,
+            current_status: run.status,
+        };
+    }
     if (evidence.contract_acceptance_anomaly) {
         try {
             recordExecutionContractAnomaly(runId, {
@@ -580,7 +683,6 @@ export function reconcileAgentRun(runId, cwd, options = {}) {
     }
     const grace = options.healthCheckGraceMs ?? DEFAULT_HEALTH_CHECK_GRACE_MS;
     const stale = options.staleAfterMs ?? DEFAULT_STALE_AFTER_MS;
-    const actor = options.actor ?? 'reconciler';
     // Below grace window: too early to draw any conclusion. Caller should
     // re-poll later.
     if (evidence.age_ms < grace) {
@@ -596,6 +698,7 @@ export function reconcileAgentRun(runId, cwd, options = {}) {
                 actor,
                 status_reason: `inferred=true; evidence: ${describeEvidence(evidence)}`,
             }, cwd);
+            convergeAssignmentFromRun(run, 'completed', evidence, actor, cwd);
             return {
                 run_id: runId, action: 'inferred_completed',
                 reason: `inferred=true; ${describeEvidence(evidence)}`,
@@ -617,6 +720,7 @@ export function reconcileAgentRun(runId, cwd, options = {}) {
     const failHere = (reason) => {
         try {
             transitionAgentRun(runId, 'failed', { actor, status_reason: reason }, cwd);
+            convergeAssignmentFromRun(run, 'failed', evidence, actor, cwd);
             cascadeReleaseOnFailure(run, actor, cwd, 'failed', reason);
             return { run_id: runId, action: 'inferred_failed', reason, evidence, previous_status, current_status: 'failed' };
         }
@@ -814,18 +918,47 @@ export function reconcileDeadPidRunningAgentRunAtRead(runId, cwd, options = {})
         };
     }
     const evidence = collectEvidence(run, cwd, { nowMs: options.nowMs });
+    const actor = options.actor ?? 'reconciler';
+    const laneResult = reconcileOwnedLaneResultAtRead(run, evidence, cwd, actor);
+    if (laneResult?.result)
+        return laneResult.result;
     if (run.status !== 'running') {
         return {
             run_id: run.id, action: 'no_op', reason: `run status is ${run.status}, not running`,
             evidence, previous_status: run.status, current_status: run.status,
         };
     }
-    const actor = options.actor ?? 'reconciler';
     const stale = options.staleAfterMs ?? DEFAULT_STALE_AFTER_MS;
     const heartbeatStale = options.heartbeatStaleMs ?? DEFAULT_HEARTBEAT_STALE_MS;
+    if (laneResult?.withheld_reason) {
+        const conclusiveFailure = evidence.failed_signal
+            ? 'wrapper reported non-zero exit'
+            : evidence.heartbeat_exists
+                && evidence.heartbeat_age_ms !== undefined
+                && evidence.heartbeat_age_ms >= heartbeatStale
+                && !fsActiveWithin(evidence, heartbeatStale)
+                ? `heartbeat stalled for ${Math.round(evidence.heartbeat_age_ms / 1000)}s`
+                : evidence.process_alive === false
+                    && evidence.age_ms >= stale
+                    && !fsActiveWithin(evidence, heartbeatStale)
+                    ? 'silent termination past stale window'
+                    : undefined;
+        if (conclusiveFailure) {
+            return settleWithheldLaneFailure(run, evidence, actor, cwd, `invalid_lane_result_with_conclusive_failure: ${conclusiveFailure}; ${laneResult.withheld_reason}`);
+        }
+        return {
+            run_id: run.id,
+            action: 'health_check_unverified',
+            reason: laneResult.withheld_reason,
+            evidence,
+            previous_status: run.status,
+            current_status: run.status,
+        };
+    }
     const failRun = (reason) => {
         try {
             transitionAgentRun(run.id, 'failed', { actor, status_reason: reason }, cwd);
+            convergeAssignmentFromRun(run, 'failed', evidence, actor, cwd);
             cascadeReleaseOnFailure(run, actor, cwd, 'failed', reason);
             return { run_id: run.id, action: 'inferred_failed', reason, evidence, previous_status: run.status, current_status: 'failed' };
         }
@@ -846,6 +979,7 @@ export function reconcileDeadPidRunningAgentRunAtRead(runId, cwd, options = {})
                 actor,
                 status_reason: `inferred=true; evidence: ${describeEvidence(evidence)}`,
             }, cwd);
+            convergeAssignmentFromRun(run, 'completed', evidence, actor, cwd);
             return {
                 run_id: run.id, action: 'inferred_completed',
                 reason: `inferred=true; ${describeEvidence(evidence)}`,

package/dist/core/claims.js

@@ -963,7 +963,10 @@ export function createCoordinatorClaim(options) {
     // `.github/workflows` previously produced `feat/.github-…` (leading dot),
     // which git rejects and the whole spawn failed.
     const branchSlug = sanitizeBranchComponent(options.scope);
-    const worktreeBranch = `feat/${branchSlug}`;
+    const branchSuffix = options.worktreeBranchSuffix
+        ? `-${sanitizeBranchComponent(options.worktreeBranchSuffix)}`
+        : '';
+    const worktreeBranch = `feat/${branchSlug}${branchSuffix}`;
     try {
         worktreePath = createWorktree(options.cwd, worktreeBranch, {
             sessionId: options.sessionId,

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);

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

@@ -19,8 +19,10 @@ import { exportSubgraph } from './export.js';
 import { fileId } from './ids.js';
 import { resolveTraversal, aggregateFind, aggregateBrief } from './aggregate.js';
 import { defaultMemoryReader } from './memory-reader.js';
-import { listNestedProjects, refreshWorkspaceCascade } from './cascade.js';
+import { inspectNestedProjects, refreshWorkspaceCascade } from './cascade.js';
+import { latestCascadeRefreshJob, summarizeCascadeRefreshJob } from './cascade-jobs.js';
 import { loadConfig } from '../config.js';
+import { codeMapDir } from './paths.js';
 /** spec §9 caps the brief reading list at 12 files. */
 export const BRIEF_FILE_CAP = 12;
 /**
@@ -111,17 +113,26 @@ function isMultiProjectWorkspace(cwd) {
 /** Per-child store recap for `status(cascade)` in a multi-project workspace. */
 function buildCascadeStatus(rootCwd) {
     const root = rootCwd ?? process.cwd();
-    const children = listNestedProjects(root).map((abs) => {
+    const discovery = inspectNestedProjects(root);
+    const children = discovery.projects.map((abs) => {
         const m = readManifest(abs);
         return {
             path: path.relative(root, abs).replace(/\\/g, '/') || '.',
             store_exists: m ? true : storeExists(abs),
             freshness: m ? m.freshness.status : 'missing_index',
             files_indexed: m ? m.stats.files_indexed : null,
+            ...(m && m.stats.files_indexed === 0 ? { reason: 'no_eligible_files' } : {}),
         };
     });
     const indexed = children.filter((c) => c.freshness !== 'missing_index').length;
-    return { children, indexed_children: indexed, total_children: children.length };
+    const latestJob = latestCascadeRefreshJob(root);
+    return {
+        children,
+        indexed_children: indexed,
+        total_children: children.length,
+        discovery_truncated: discovery.truncated,
+        ...(latestJob ? { refresh_job: summarizeCascadeRefreshJob(latestJob) } : {}),
+    };
 }
 /**
  * P0 JSONL-backed query backend. Reads the durable file store (manifest +
@@ -140,10 +151,16 @@ export class JsonlBackend {
         this.gitHeadReader = opts.gitHeadReader ?? readCurrentGitHead;
     }
     async status(input) {
+        const projectRoot = path.resolve(input.cwd ?? process.cwd());
+        const resolution = {
+            project_root: projectRoot,
+            store_path: codeMapDir(projectRoot, input.preferredDirName),
+        };
         const manifest = readManifest(input.cwd, input.preferredDirName);
         const result = manifest
             ? {
                 store_exists: true,
+                resolution,
                 freshness_badge: this.withHeadDrift(badge(manifest.freshness.status, {
                     stale_file_count: manifest.freshness.stale_file_count,
                     partial_reason: manifest.freshness.partial_reason,
@@ -156,6 +173,7 @@ export class JsonlBackend {
             }
             : {
                 store_exists: storeExists(input.cwd, input.preferredDirName),
+                resolution,
                 freshness_badge: badge('missing_index'),
                 stats: null,
             };
@@ -190,17 +208,17 @@ export class JsonlBackend {
             // A cascade is only fully "acquired" when EVERY project got its lock; if a
             // child or the root was skipped under a live writer, surface that instead
             // of reporting a clean lock_acquired=true over a partial cascade (codex review).
-            const skipped = allProjects.filter((p) => !p.lock_acquired);
+            const incomplete = allProjects.filter((p) => p.outcome === 'locked' || p.outcome === 'failed');
             return {
                 ran: allProjects.some((p) => p.ran),
                 scope,
-                lock_acquired: skipped.length === 0,
+                lock_acquired: incomplete.length === 0,
                 freshness_badge: badge(root.freshness, {
                     files_parsed: root.files_parsed,
                     children_refreshed: cascade.children_refreshed,
                 }),
-                ...(skipped.length > 0
-                    ? { lock_status: `${skipped.length} project(s) skipped (lock held): ${skipped.map((p) => p.path).join(', ')}` }
+                ...(incomplete.length > 0
+                    ? { lock_status: `${incomplete.length} project(s) incomplete: ${incomplete.map((p) => `${p.path} (${p.outcome})`).join(', ')}` }
                     : {}),
                 cascade,
             };