brainclaw 1.28.1 → 1.28.3

package/dist/commands/code-map.js

@@ -108,6 +108,8 @@ function printStatus(status, options) {
     }
     console.log('Code Map status');
     console.log(`  Store:    ${status.store_exists ? 'present' : 'absent'}`);
+    console.log(`  Root:     ${status.resolution.project_root}`);
+    console.log(`  Path:     ${status.resolution.store_path}`);
     console.log(`  ${badgeLine(status.freshness_badge)}`);
     if (status.stats) {
         console.log(`  Files:    ${status.stats.files_indexed}`);

package/dist/commands/doctor.js

@@ -518,6 +518,7 @@ export function runDispatchHealthCheck(options = {}) {
         };
         switch (result.action) {
             case 'inferred_completed':
+            case 'reconciled_turn':
                 inferred_completed.push(summary);
                 break;
             case 'health_check_unverified':

package/dist/commands/harvest.js

@@ -25,54 +25,43 @@ import { commitWorktreeOnBehalf, worktreesBaseDir, resolveGitToplevel } from '..
 import { closeReviewLoopFromLaneResult } from '../core/review-loop-close.js';
 import { closeIdeationLoopFromLaneResult } from '../core/ideation-loop-close.js';
 import { dispatchReviewLoopTurn, turnOwnedLoopEnabled } from '../core/review-loop-turn-dispatch.js';
-import { reconcileTurn } from '../core/loops/reconcile-turn.js';
-import { findReservationByAssignmentId } from '../core/loops/attempt-reservation.js';
-import { resolveTurnGenerationChain } from '../core/loops/attempt-generations.js';
+import { reconcileTurnOwnedLane, turnOwnedLaneEvidence } from '../core/loops/reconcile-turn.js';
 import { getLoop } from '../core/loops/store.js';
 import { phasePolicy } from '../core/loops/kind-policies.js';
-import { readCompletionSignals } from '../core/runtime-signals.js';
 import { reconcileClaimConformity } from '../core/claim-conformity.js';
 import { toWarningDetail } from '../core/warnings.js';
 import { harvestHarnessObservation } from '../core/harness-adapters/index.js';
-function turnOwnedLaneEvidence(lane, cwd) {
-    const reservation = findReservationByAssignmentId(lane.assignment_id, cwd);
-    if (!reservation)
-        return undefined; // legacy lane (no reservation)
-    const chain = resolveTurnGenerationChain(cwd, reservation.turn_id);
-    const completion = readCompletionSignals(cwd, reservation.child_ids.assignment_id, chain?.latest_generation.run_id).completed;
-    const nonce = lane.nonce ?? completion?.nonce;
-    if (!nonce && !reservation.execution_contract_ref)
-        return undefined;
-    return {
-        reservation,
-        nonce,
-        contract_hash: lane.execution_contract_hash ?? completion?.contract_hash,
-        capability_snapshot_hash: lane.capability_snapshot_hash ?? completion?.capability_snapshot_hash,
-    };
-}
-function reconcileTurnOwnedLane(lane, cwd, evidence) {
-    const ev = evidence ?? turnOwnedLaneEvidence(lane, cwd);
-    if (!ev)
-        return undefined; // legacy lane OR no turn-keyed evidence — caller runs the legacy path
-    const { reservation, nonce } = ev;
-    const enrichedLane = {
-        ...lane,
-        turn_id: lane.turn_id ?? reservation.turn_id,
-        run_id: lane.run_id ?? reservation.child_ids.run_id,
-        nonce,
-        execution_contract_hash: lane.execution_contract_hash ?? ev.contract_hash,
-        capability_snapshot_hash: lane.capability_snapshot_hash ?? ev.capability_snapshot_hash,
-    };
-    const loop = getLoop(reservation.loop_id, cwd);
-    const critiques = loop?.kind === 'ideation'
-        && reservation.phase === 'critique'
-        && lane.artifact_type === 'critique'
-        && (lane.body ?? '').trim().length > 0
-        ? [{ body: lane.body.trim() }]
-        : undefined;
-    const result = reconcileTurn({ turn_id: reservation.turn_id, lane: enrichedLane, cwd, critiques });
-    return { reservation, result };
-}
+/**
+ * pln#630 PR3a — finalize a TURN-OWNED review lane via the exactly-once `reconcileTurn`
+ * instead of the legacy `closeReviewLoopFromLaneResult`. Returns `undefined` for a legacy
+ * (non-reserved) lane so the caller runs the unchanged legacy path — this is the
+ * exactly-one-finalizer discriminator: a lane is turn-owned iff a reservation OWNS its
+ * assignment_id (only the turn-owned dispatch writes a reservation file).
+ *
+ * Evidence sourcing (the load-bearing subtlety): a real reviewer's LANE-RESULT.json is
+ * KEYLESS — the review brief never asks the worker to echo turn_id/run_id/nonce — so
+ * read-strict `reconcileTurn` (which matches lane.{turn_id,run_id,nonce} against the
+ * attempt) would REJECT it. We source the keys authoritatively: turn_id + run_id are
+ * deterministic from the reservation, and the NONCE — the non-derivable proof that THIS
+ * launch generation actually ran — comes from the coordinator's completion SENTINEL
+ * (written mechanically by the ack-wrapper with the launch-grant token). A caller/test
+ * that already supplies keyed lanes is honored (lane.* wins); a stale generation's
+ * sentinel carries the old token → still rejected, preserving the anti-stale guarantee.
+ */
+/**
+ * The turn-owned FINALIZATION discriminator (pln#630, review Finding 1). A lane finalizes via
+ * the exactly-once reconcileTurn ONLY if a committed reservation OWNS it AND turn-keyed evidence
+ * (the nonce) is available — from the lane or the coordinator's completion SENTINEL. Without the
+ * nonce, reconcileTurn's read-strict gate can NEVER converge: this is reachable in production
+ * when a turn-owned dispatch WON the fence but did not ack-wrap-spawn (inbox_only / IDE-only
+ * reviewer, command_ready_manual, capacity cap, BRAINCLAW_NO_SPAWN, worktree-creation failure) —
+ * it minted a reservation but no sentinel will ever be written. Returning undefined there routes
+ * the lane to the LEGACY presence-based closer so the loop still converges instead of stalling
+ * forever. This is SAFE: the exactly-once SPAWN guarantee is enforced at DISPATCH by the launch
+ * fence (already run), so using legacy FINALIZATION for a sentinel-less lane reintroduces no
+ * double-spawn; and a sentinel that lands after a legacy close makes a later reconcile a
+ * terminal-loop idempotent no-op.
+ */
 /**
  * Map a `reconcileTurn` result onto the `ReviewLoopCloseResult` shape harvest records for
  * observability (entry.review_loop / CLI). No keep_claim / next_turn: the request_changes

package/dist/commands/loops-handlers.js

@@ -9,7 +9,7 @@ import { loadSequence } from '../core/sequence.js';
 import { createActionRequired, loadActionRequired } from '../core/actions.js';
 import { selectImplementationReviewer } from '../core/reviewer-policy.js';
 import { handleBclawCoordinate } from './mcp-write-coordination.js';
-import { add_artifact, advance, AwaitingFileApplyApprovalError, closeLoop, complete_turn, computeNextExpected, getLoop, IdempotencyKeyReusedError, IdempotencyOwnerMismatchError, listLoopEvents, listLoops, LockLostError, LockTimeoutError, openLoop, pause, provideInput, requestInput, resume, sweepPauseTimeouts, takeoverLoopAttempt, readLocalAuthorityHome, turn, VersionConflictError, withLoopLock, artifactEvidenceDigest, attachContinuationActionRequired, ensureContinuation, } from '../core/loops/index.js';
+import { add_artifact, advance, AwaitingFileApplyApprovalError, closeLoop, complete_turn, computeNextExpected, getLoop, IdempotencyKeyReusedError, IdempotencyOwnerMismatchError, listLoopEvents, listLoops, LockLostError, LockTimeoutError, openLoop, pause, provideInput, requestInput, resume, sweepPauseTimeouts, takeoverLoopAttempt, readLocalAuthorityHome, turn, VersionConflictError, withLoopLock, artifactEvidenceDigest, attachContinuationActionRequired, ensureContinuation, deriveWorkerReplyContract, evaluatePhaseAdvanceGate, } from '../core/loops/index.js';
 import { BclawLoopRequestSchema, BCLAW_LOOP_INTENTS, } from '../core/loops/facade-schema.js';
 // NextExpectedHint type now lives in src/core/loops/next-expected.ts
 // (hoisted per can_e57c7782 follow-up so MCP facade + CLI share the
@@ -141,7 +141,7 @@ function proposedPipelineActions(loop, cwd) {
     }
     return [];
 }
-function errorResponse(intent, code, message, durationMs, result = null) {
+function errorResponse(intent, code, message, durationMs, result = null, nextActions = []) {
     return {
         response: {
             status: 'error',
@@ -152,10 +152,72 @@ function errorResponse(intent, code, message, durationMs, result = null) {
             warnings: [],
             error: `${code}: ${message}`,
             duration_ms: durationMs,
+            ...(nextActions.length > 0 ? { next_actions: nextActions } : {}),
         },
         summary: `✘ bclaw_loop[${intent}] ${code}: ${message}`,
     };
 }
+function continuationUnavailableDiagnostic(loop, cwd) {
+    const phase = loop.phases.find((candidate) => candidate.name === loop.current_phase);
+    const gate = phase?.advance_gate;
+    const gateOutcome = evaluatePhaseAdvanceGate(loop, gate, cwd);
+    const contract = deriveWorkerReplyContract(loop);
+    const blockers = [];
+    const probableCauses = [];
+    const nextActions = [];
+    if (!gateOutcome.advance && gateOutcome.gate_reason)
+        blockers.push(gateOutcome.gate_reason);
+    const assigned = loop.slots.filter((slot) => slot.status === 'assigned' && slot.assignment_id);
+    const open = loop.slots.filter((slot) => slot.status === 'open'
+        && !(loop.kind === 'ideation' && loop.current_phase === 'critique' && slot.role === 'champion'));
+    if (assigned.length > 0) {
+        probableCauses.push('one or more dispatched worker results have not converged into gate evidence');
+        for (const slot of assigned) {
+            nextActions.push({
+                tool: 'bclaw_find',
+                args: { entity: 'agent_run', filter: { assignment_id: slot.assignment_id, limit: 10 } },
+                when: `reconcile and inspect the AgentRun projection for slot ${slot.slot_id}`,
+            });
+        }
+    }
+    for (const slot of open) {
+        probableCauses.push(`slot ${slot.slot_id} has not been dispatched`);
+        nextActions.push({
+            tool: 'bclaw_loop',
+            args: { intent: 'turn', loop_id: loop.id, slot_id: slot.slot_id, input: loop.goal ?? loop.title, dispatch: true },
+            when: `dispatch open slot ${slot.slot_id}`,
+        });
+    }
+    if (loop.kind === 'ideation') {
+        const draft = [...loop.artifacts].reverse().find((artifact) => artifact.type === 'plan_draft');
+        if (!draft)
+            blockers.push('no attested plan_draft artifact is available for continuation');
+        if ((loop.linked?.plan_ids?.length ?? 0) === 0)
+            blockers.push('the source loop is not linked to a plan');
+        if ((loop.linked?.sequence_ids?.length ?? 0) !== 1)
+            blockers.push('the source loop must link exactly one implementation sequence');
+    }
+    else if (loop.kind === 'implementation') {
+        const handoff = [...loop.artifacts].reverse().find((artifact) => artifact.type === 'handoff' && artifact.ref);
+        if (!handoff)
+            blockers.push('no attested handoff with a reviewable ref is available');
+    }
+    return {
+        result: {
+            loop_id: loop.id,
+            phase: loop.current_phase,
+            gate: {
+                expected: contract?.requirements ?? (gate ? [gate] : []),
+                observed: gateOutcome.gate_reason ?? 'gate satisfied or no phase gate',
+                passed: gateOutcome.advance,
+            },
+            blockers: [...new Set(blockers)],
+            probable_causes: [...new Set(probableCauses)],
+            next_actions: nextActions,
+        },
+        next_actions: nextActions,
+    };
+}
 function inferIntent(args) {
     if (!args || typeof args !== 'object')
         return 'unknown';
@@ -712,7 +774,8 @@ export async function handleBclawLoop(options) {
                 const actions = proposedPipelineActions(source, options.cwd);
                 const action = actions[req.action_index];
                 if (!action) {
-                    return errorResponse('continue', 'continuation_unavailable', `no executable continuation action ${req.action_index} for ${source.id}`, Date.now() - startMs);
+                    const diagnostic = continuationUnavailableDiagnostic(source, options.cwd);
+                    return errorResponse('continue', 'continuation_unavailable', `no executable continuation action ${req.action_index} for ${source.id}; inspect gate/blockers and execute the supplied recovery actions`, Date.now() - startMs, diagnostic.result, diagnostic.next_actions);
                 }
                 const sourceArtifactId = action.args?.linked?.source_artifact_id;
                 const sourceArtifact = source.artifacts.find((artifact) => artifact.artifact_id === sourceArtifactId);

package/dist/commands/mcp-catalog.js

@@ -374,7 +374,7 @@ export const MCP_READ_TOOLS = [
     },
     {
         name: 'bclaw_code_status',
-        description: 'Code Map status for this project: store presence, freshness badge (fresh / stale_changed_files / stale_extractor / stale_grammar / stale_git_head / partial / missing_index), and index stats (files, nodes, edges). Read-only; never refreshes. Pair with bclaw_code_refresh when freshness is missing_index or stale. In a multi-project workspace, cascade=true adds a per-child recap (which nested projects have a built index vs missing_index).',
+        description: 'Code Map status for the active session project: store presence, freshness badge, and index stats. Read-only; never refreshes. In a multi-project workspace, cascade=true adds per-child coverage plus progress/terminal diagnostics for the latest durable cascade job.',
         annotations: { tier: 'standard', category: 'discovery', headlessApproval: 'auto' },
         inputSchema: {
             type: 'object',
@@ -459,7 +459,7 @@ export const MCP_READ_TOOLS = [
 const MCP_WRITE_TOOLS = [
     {
         name: 'bclaw_code_refresh',
-        description: 'Rebuild the Code Map index for this project (Tree-sitter parse + shards + indexes, behind the per-project lock). scope="changed" (default) reparses changed files; scope="all" does a full refresh + compaction. A live competing lock fails fast with a clear status — refresh never blocks. Returns the resulting freshness_badge. In a multi-project workspace, cascade=true refreshes EVERY nested project into its own store + the root store scoped to files no child owns (zero double-indexing) — so one call at the root indexes the whole monorepo per-project.',
+        description: 'Rebuild the Code Map index for the active session project. scope="changed" (default) reparses changed files; scope="all" does a full refresh + compaction. In a multi-project workspace, cascade=true starts a durable background job immediately; follow it with bclaw_code_status(cascade=true), which reports progress and terminal per-project diagnostics without an MCP timeout.',
         annotations: { tier: 'standard', category: 'discovery', headlessApproval: 'prompt' },
         inputSchema: {
             type: 'object',