brainclaw 1.17.0 → 1.19.0

package/dist/commands/mcp-write-claims.js

@@ -19,6 +19,9 @@ import { buildContext } from '../core/context.js';
 import { checkBrainclawInstallableUpdate, getInstalledBrainclawVersion, renderBrainclawInstallableUpdateNotice } from '../core/brainclaw-version.js';
 import { loadConfig } from '../core/config.js';
 import { generateClaimId, loadClaim, saveClaim, adoptClaimSession, releaseClaimWithCascade } from '../core/claims.js';
+import { releaseClaimNextActions } from '../core/next-actions.js';
+import { reconcileClaimConformity } from '../core/claim-conformity.js';
+import { pushStructuredWarning } from '../core/warnings.js';
 import { checkPolicy } from '../core/policy.js';
 import { createWorktree as coreCreateWorktree, sanitizeBranchComponent } from '../core/worktree.js';
 import { startSession } from './session-start.js';
@@ -251,6 +254,14 @@ export async function handleBclawReleaseClaim(payload, ctx) {
         session_id: connectionSessionId,
         override: coordinatorOverrideRequested,
     };
+    // pln#636 C2 — read the claim BEFORE the cascade: release is what closes it,
+    // and the conformity comparison needs its baseline + declared footprint.
+    // Best-effort by construction; a missing claim just means no advisory.
+    let claimBeforeRelease;
+    try {
+        claimBeforeRelease = loadClaim(claimId, cwd);
+    }
+    catch { /* conformity is advisory — never block a release on it */ }
     let cascadeResult;
     try {
         cascadeResult = releaseClaimWithCascade(claimId, {
@@ -268,12 +279,38 @@ export async function handleBclawReleaseClaim(payload, ctx) {
         planTransitioned ? ` — plan ${cascadePlanId} → ${cascadeNewStatus}` : '',
         planWarning ? ` ⚠ ${planWarning}` : '',
     ].join('');
+    // pln#634 — release is the single most protocol-loaded moment of the daily
+    // loop (it is where the plan cascade either fires or refuses), and it shipped
+    // pure data. Derived from what the cascade actually decided.
+    const releaseActions = releaseClaimNextActions({
+        claimId,
+        planId: cascadePlanId,
+        planTransitioned,
+        planWarning,
+        requestedPlanStatus: typeof args.planStatus === 'string' ? args.planStatus : undefined,
+    });
+    // pln#636 C2 — release is the natural reconcile point: the work is finished, so
+    // the footprint is final. Emits ONLY on a concrete, path-resolvable violation;
+    // every doubt (no baseline, prose scope, reaped worktree) stays silent.
+    const conformityWarnings = [];
+    const conformityDetails = [];
+    if (claimBeforeRelease) {
+        try {
+            const conformity = reconcileClaimConformity(claimBeforeRelease, cwd);
+            if (conformity.warning) {
+                pushStructuredWarning(conformityWarnings, conformityDetails, conformity.warning);
+            }
+        }
+        catch { /* advisory only */ }
+    }
     return {
         response: toolResponse({
             content: [{ type: 'text', text: summaryText }],
             claim_id: claimId,
             ...(planTransitioned ? { plan_id: cascadePlanId, plan_status: cascadeNewStatus } : {}),
             ...(planWarning ? { plan_warning: planWarning, plan_id: cascadePlanId } : {}),
+            ...(conformityWarnings.length ? { warnings: conformityWarnings, warning_details: conformityDetails } : {}),
+            ...(releaseActions.length ? { next_actions: releaseActions } : {}),
         }),
     };
 }
@@ -540,6 +577,23 @@ export async function handleBclawAssignmentUpdate(payload, ctx) {
             actor: callerAgent,
             actor_id: resolved.identity.agent_id,
         }, cwd);
+        // pln#636 C2 — reconcile the linked claim's scope BEFORE the cascade below
+        // releases it (after release there is no claim left to read). This is the
+        // lifecycle boundary a worker crosses when it reports its own completion.
+        const asgnConformityWarnings = [];
+        const asgnConformityDetails = [];
+        if (status === 'completed' && assignment.claim_id) {
+            try {
+                const linkedClaim = loadClaim(assignment.claim_id, cwd);
+                if (linkedClaim) {
+                    const conformity = reconcileClaimConformity(linkedClaim, cwd);
+                    if (conformity.warning) {
+                        pushStructuredWarning(asgnConformityWarnings, asgnConformityDetails, conformity.warning);
+                    }
+                }
+            }
+            catch { /* advisory only — never block a completion report */ }
+        }
         // trp#928 — cascade-release the assignment's linked claim on completion.
         // Before this landing an obedient worker had to make TWO calls to close
         // the loop (bclaw_assignment_update status=completed AND
@@ -628,6 +682,9 @@ export async function handleBclawAssignmentUpdate(payload, ctx) {
                     ...(result.assignment.completed_at && { completed_at: result.assignment.completed_at }),
                     last_heartbeat_at: result.assignment.last_heartbeat_at,
                     ...(createdActionId ? { action_id: createdActionId } : {}),
+                    ...(asgnConformityWarnings.length
+                        ? { warnings: asgnConformityWarnings, warning_details: asgnConformityDetails }
+                        : {}),
                 },
             },
         };

package/dist/commands/mcp-write-coordination.js

@@ -20,12 +20,16 @@ import { appendAuditEntry } from '../core/audit.js';
 import { nowISO } from '../core/ids.js';
 import { validateMcpField } from '../core/input-validation.js';
 import { generateCandidateIdWithLabel, saveCandidate } from '../core/candidates.js';
+import { validateLoopProjectResolution } from '../core/loops/project-resolution.js';
+import { coordinateNextActions, dispatchNextActions } from '../core/next-actions.js';
+import { agentValidationFailedWarning, planAlreadyAssignedWarning, pushStructuredWarning, scopeAlreadyClaimedWarning, } from '../core/warnings.js';
 import { ackMessage, getThread, hasActiveAssignment, sendMessage } from '../core/messaging.js';
 import { dispatch, dispatchReview, generateDispatchBrief } from '../core/dispatcher.js';
 import { CoordinateRequestSchema } from '../core/facade-schema.js';
 import { buildInvokeCommand, getCapabilityProfile, getSpawnableAgents, resolveModel, validateAgentForDispatch, } from '../core/agent-capability.js';
 import { attemptExecution } from '../core/execution.js';
 import { createAgentRun, transitionAgentRun } from '../core/agentruns.js';
+import { prepareTurnOwnedReviewDispatch, turnOwnedReviewEnabled } from '../core/review-loop-turn-dispatch.js';
 import { createAssignment, generateAssignmentId, patchAssignmentMessageId, transitionAssignment, } from '../core/assignments.js';
 import { createToolErrorResponse, toolResponse, } from './mcp-contract.js';
 import { handleMcpReadToolCall } from './mcp-read-handlers.js';
@@ -171,12 +175,25 @@ export async function handleBclawDispatch(args, ctx) {
             item_type: 'dispatch',
             scope: `${dispatchResult.messages_sent.length} assignments`,
         }, cwd);
+        // pln#634 — the text body already tells a human what to do next; the
+        // structured payload told an agent nothing. Derived from the real cycle
+        // outcome: verification targets for what spawned, analysis for what is
+        // blocked, and a re-run hint for a dry run. Manual launch commands are
+        // deliberately NOT mirrored here — they are not MCP-callable.
+        const dispatchActions = dispatchNextActions({
+            spawnedTargets: spawned
+                .map((m) => m.assignment_id ?? m.run_id ?? m.claim_id)
+                .filter((id) => typeof id === 'string' && id.length > 0),
+            blockedCount: analysis.blocked.length,
+            dryRun: !!args.dryRun,
+        });
         return {
             response: toolResponse({
                 content: [{ type: 'text', text: lines.join('\n') }],
                 ...dispatchResult,
                 sequence_id: analysis.sequence.id,
                 dry_run: !!args.dryRun,
+                ...(dispatchActions.length ? { next_actions: dispatchActions } : {}),
             }),
         };
     }
@@ -228,11 +245,13 @@ export function handleBclawSendMessage(args, ctx) {
         }, cwd);
         appendAuditEntry({ actor: resolved.identity.agent_name, actor_id: resolved.identity.agent_id, action: 'create', item_id: result.id, item_type: 'message', scope: to }, cwd);
         const threadInfo = threadId ? ` thread:${threadId}` : '';
+        const warningLine = result.warning ? `\n⚠ ${result.warning}` : '';
         return {
             response: toolResponse({
-                content: [{ type: 'text', text: `✔ Message sent: [${result.shortLabel}] ${msgType} → ${to}${threadInfo}` }],
+                content: [{ type: 'text', text: `✔ Message sent: [${result.shortLabel}] ${msgType} → ${to}${threadInfo}${warningLine}` }],
                 message_id: result.id,
                 thread_id: threadId,
+                ...(result.warning ? { warning: result.warning } : {}),
             }),
         };
     }
@@ -270,7 +289,7 @@ export function handleBclawAckMessage(args, ctx) {
     }
 }
 export async function handleBclawCoordinate(args, ctx) {
-    const { cwd, connectionSessionId, currentModel } = ctx;
+    const { cwd, connectionSessionId, currentModel, effectiveScope } = ctx;
     const startMs = Date.now();
     const parseResult = CoordinateRequestSchema.safeParse(args);
     if (!parseResult.success) {
@@ -304,6 +323,11 @@ export async function handleBclawCoordinate(args, ctx) {
     // for the intents that actually spawn a worktree worker). See the
     // assessDirtyDispatchGuard call after the cross-project block.
     const warnings = [];
+    // pln#635 — structured sibling of `warnings`. Deliberately a SUBSET: the
+    // codes that carry a recovery path write here, prose advisories stay
+    // string-only for now (`warnings` remains the complete channel — see
+    // core/warnings.ts for the reference-threading reason).
+    const warningDetails = [];
     const artifacts = [];
     const side_effects = [];
     // can_5e62334e — codex sandboxed dispatches cannot commit in worktrees
@@ -356,6 +380,35 @@ export async function handleBclawCoordinate(args, ctx) {
         warnings.push(`cross-project dispatch (project='${req.project}') — auto-spawn disabled; the target agent picks up the brief async via its own bclaw_work.`);
     }
     const effectiveAutoExecute = isCrossProject ? false : req.autoExecute;
+    // pln#521 P1 — project resolution gate. A review loop written into the wrong
+    // store is worse than one that never opened: candidate, claim, assignment and
+    // loop all persist where nobody is watching, and the reviewer spawns against
+    // the wrong repo (DGX misroute). So when this store can host several projects
+    // and NONE was selected, refuse here — before the pre-flight spawn and before
+    // the first write — instead of silently defaulting to cwd. Explicit `project`,
+    // a session switch, or an active-project pointer all count as a choice; ref /
+    // scope / path never do (B3 rejected, art_e29e88878209). Scoped to the failing
+    // path (review + open_loop): every other intent keeps its routing untouched.
+    let projectResolution;
+    if (req.intent === 'review' && req.open_loop === true) {
+        // Resolve from `cwd`, not `dispatchCwd`: an explicit project name is
+        // resolvable from the SOURCE store (its links / store chain), which is
+        // exactly what produced dispatchCwd above. Re-resolving from the target
+        // could fail for a link whose name differs from the target's project_name.
+        const resolution = validateLoopProjectResolution({
+            cwd,
+            projectArg: req.project,
+            activeSource: effectiveScope?.active_source,
+        });
+        if (!resolution.ok) {
+            return {
+                response: createToolErrorResponse(resolution.code, resolution.message, {
+                    candidates: resolution.candidates,
+                }),
+            };
+        }
+        projectResolution = resolution;
+    }
     // can_30c295b4 / trp#371 Tier 2 — scope-aware dirty-working-tree guard.
     // Intents that spawn a worktree worker from HEAD can review/edit stale code,
     // so they are guarded; consult/summarize (no worktree) are not. pln#626
@@ -403,7 +456,7 @@ export async function handleBclawCoordinate(args, ctx) {
     /** Run E2E execution phase on prepared delivery entries. Returns overall execution status. */
     const runCoordinateExecution = async (prepared, opts) => {
         let overall = 'inbox_only';
-        for (const { entry, invoke, worktreePath } of prepared) {
+        for (const { entry, invoke, worktreePath, turnEcho } of prepared) {
             const execResult = await attemptExecution(invoke, {
                 agent: entry.agent,
                 autoExecute: opts.autoExecute,
@@ -414,6 +467,8 @@ export async function handleBclawCoordinate(args, ctx) {
                 dispatcherAgentId: opts.senderAgentId,
                 cwd: opts.cwd,
                 requireWorktree: true, // pln#531: never spawn a worker in the integration repo
+                turnEcho, // pln#630 — turn-owned reviewer (initial dispatch): the ack-wrapper writes the
+                // turn-keyed completion sentinel. undefined for every non-turn-owned entry.
             });
             entry.execution_status = execResult.execution_status;
             // pln#626 Phase 1 — carry the machine-readable reason (+ failure_kind) to
@@ -436,7 +491,23 @@ export async function handleBclawCoordinate(args, ctx) {
             // emit three identical context-free warnings (pln#626 Phase 1 R5).
             if (execResult.error)
                 opts.warnings.push(`${entry.agent}: ${execResult.error}`);
-            if (entry.assignment_id && entry.claim_id) {
+            if (turnEcho) {
+                // pln#630 risk #1 — a turn-owned reviewer's run was ALREADY created (`created`) by
+                // prepareTurnOwnedReviewDispatch. Do NOT mint a second run here (double-mint). Transition
+                // the deterministic run → running on a real spawn (mirrors dispatchReviewLoopTurn); leave
+                // it `created` otherwise so the no-sentinel legacy fallback (turnOwnedLaneEvidence) + the
+                // pre-run lease reconciler govern it. Non-turn-owned entries take the unchanged else-branch.
+                if (execResult.execution_status === 'delivered_and_started') {
+                    try {
+                        transitionAgentRun(turnEcho.run_id, 'running', {
+                            actor: opts.senderAgent, actor_id: opts.senderAgentId, pid: execResult.pid,
+                            status_reason: 'turn-owned reviewer spawned by coordinator',
+                        }, opts.cwd);
+                    }
+                    catch { /* best-effort — the reconciler converges if this races */ }
+                }
+            }
+            else if (entry.assignment_id && entry.claim_id) {
                 if (execResult.failure_kind === 'spawn_no_handshake') {
                     try {
                         const run = createAgentRun({
@@ -643,8 +714,7 @@ export async function handleBclawCoordinate(args, ctx) {
             // retry loops can react (e.g. fall back to a different agent).
             const check = validateAgentForDispatch(agentName, { requireSpawnable: true });
             if (!check.valid) {
-                warnings.push(JSON.stringify({
-                    warning: 'agent_validation_failed',
+                pushStructuredWarning(warnings, warningDetails, agentValidationFailedWarning({
                     agent: agentName,
                     code: check.code,
                     reason: check.reason,
@@ -656,21 +726,19 @@ export async function handleBclawCoordinate(args, ctx) {
             const assignScope = req.scope ?? req.task;
             // Guard: warn if there is already a non-archived assign message for this agent+scope
             if (hasActiveAssignment(agentName, assignScope, dispatchCwd)) {
-                warnings.push(JSON.stringify({
-                    warning: 'plan_already_assigned',
-                    plan_id: assignScope,
-                    existing_agent: agentName,
+                pushStructuredWarning(warnings, warningDetails, planAlreadyAssignedWarning({
+                    planId: assignScope,
+                    existingAgent: agentName,
                 }));
             }
             // Guard: warn if there is already an active claim on the same scope
             const conflictingClaims = listClaims(dispatchCwd).filter((c) => c.status === 'active' && c.scope === assignScope);
             if (conflictingClaims.length > 0) {
                 const existing = conflictingClaims[0];
-                warnings.push(JSON.stringify({
-                    warning: 'scope_already_claimed',
+                pushStructuredWarning(warnings, warningDetails, scopeAlreadyClaimedWarning({
                     scope: assignScope,
-                    existing_agent: existing.agent,
-                    existing_claim_id: existing.id,
+                    existingAgent: existing.agent,
+                    existingClaimId: existing.id,
                 }));
             }
             const claimResult = createCoordinatorClaim({
@@ -969,38 +1037,82 @@ export async function handleBclawCoordinate(args, ctx) {
                             id: claimResult.claimId,
                         });
                         let reviewAssignmentId;
-                        try {
-                            const preId = generateAssignmentId(dispatchCwd);
-                            const assignment = createAssignment({
-                                id: preId.id,
-                                short_label: preId.short_label,
-                                claim_id: claimResult.claimId,
+                        let reviewTurnEcho;
+                        // pln#630 — turn-own the INITIAL reviewer dispatch (same default + kill-switch as the
+                        // fix cycle). Skipped for cross-project reviews (no local worktree/sentinel → they never
+                        // spawn here). WON: prepare minted the DETERMINISTIC assignment + run + turn()-bound the
+                        // slot, so we reuse prep.assignmentId for the brief/message/linkage below and carry the
+                        // turnEcho so the ack-wrapper writes the turn-keyed sentinel. DENIED: the exactly-once
+                        // fence says this dispatch is NOT the spawner — do NOT spawn, do NOT fall back to legacy
+                        // (that is the double-spawn hole), and do NOT release the (possibly shared) claim; leave
+                        // the slot for reconcile/self-heal. LEGACY: the unchanged inline mint runs.
+                        let usedTurnOwned = false;
+                        if (turnOwnedReviewEnabled() && !req.project) {
+                            const prep = prepareTurnOwnedReviewDispatch({
+                                loopId: loop.id,
+                                slotId: slot.slot_id,
                                 agent: slot.agent ?? '',
-                                dispatcher_agent: senderAgent,
-                                dispatcher_session_id: connectionSessionId,
-                                scope: reviewScope,
+                                agentId: slot.agent_id,
+                                phase: 'findings',
+                                task: req.task,
                                 description: reviewDescription,
-                                tags: ['coordinate', 'review', 'loop'],
-                            }, dispatchCwd);
-                            reviewAssignmentId = assignment.id;
-                            out.artifacts.push({ type: 'assignment', id: assignment.id });
+                                scope: reviewScope,
+                                claimId: claimResult.claimId,
+                                worktreePath: claimResult.worktreePath,
+                                dispatcherAgent: senderAgent,
+                                dispatcherAgentId: senderAgentId,
+                                sessionId: connectionSessionId,
+                                isReviewer: true,
+                                cwd: dispatchCwd,
+                            });
+                            if (prep.kind === 'won') {
+                                reviewAssignmentId = prep.assignmentId; // deterministic — harvest correlates on it
+                                reviewTurnEcho = { turn_id: prep.turnId, run_id: prep.runId, nonce: prep.nonce };
+                                out.artifacts.push({ type: 'assignment', id: prep.assignmentId });
+                                usedTurnOwned = true; // prepare already created the assignment + run + bound the slot
+                            }
+                            else if (prep.kind === 'denied') {
+                                out.partial = true;
+                                out.warnings.push(`open_loop: turn-owned reviewer dispatch denied for slot ${slot.slot_id} (${prep.reason}); not spawning — slot left for reconcile/self-heal`);
+                                continue; // MUST NOT spawn AND MUST NOT legacy-fallback beside a live reservation
+                            }
+                            // prep.kind === 'legacy' (pre-identity failure) → fall through to the inline mint.
                         }
-                        catch (asgErr) {
-                            out.warnings.push(`Review assignment creation failed for slot ${slot.slot_id}: ${asgErr instanceof Error ? asgErr.message : String(asgErr)}`);
+                        if (!usedTurnOwned) {
+                            try {
+                                const preId = generateAssignmentId(dispatchCwd);
+                                const assignment = createAssignment({
+                                    id: preId.id,
+                                    short_label: preId.short_label,
+                                    claim_id: claimResult.claimId,
+                                    agent: slot.agent ?? '',
+                                    dispatcher_agent: senderAgent,
+                                    dispatcher_session_id: connectionSessionId,
+                                    scope: reviewScope,
+                                    description: reviewDescription,
+                                    tags: ['coordinate', 'review', 'loop'],
+                                }, dispatchCwd);
+                                reviewAssignmentId = assignment.id;
+                                out.artifacts.push({ type: 'assignment', id: assignment.id });
+                            }
+                            catch (asgErr) {
+                                out.warnings.push(`Review assignment creation failed for slot ${slot.slot_id}: ${asgErr instanceof Error ? asgErr.message : String(asgErr)}`);
+                            }
+                            // pln#628 Focus 4B (BLOCKING 2) — assign the slot NOW that the
+                            // claim/assignment exist, binding their ids onto the slot so the
+                            // harvest close resolves this exact reviewer by assignment_id. Runs
+                            // even if assignment creation failed (undefined id → the harvest
+                            // falls back to the legacy agent match for this one slot). (For the
+                            // turn-owned WON path, prepare already turn()-bound the slot.)
+                            turn({
+                                id: loop.id,
+                                slot_id: slot.slot_id,
+                                actor: creatorActor,
+                                input: req.task,
+                                assignment_id: reviewAssignmentId,
+                                claim_id: claimResult.claimId,
+                            }, dispatchCwd);
                         }
-                        // pln#628 Focus 4B (BLOCKING 2) — assign the slot NOW that the
-                        // claim/assignment exist, binding their ids onto the slot so the
-                        // harvest close resolves this exact reviewer by assignment_id. Runs
-                        // even if assignment creation failed (undefined id → the harvest
-                        // falls back to the legacy agent match for this one slot).
-                        turn({
-                            id: loop.id,
-                            slot_id: slot.slot_id,
-                            actor: creatorActor,
-                            input: req.task,
-                            assignment_id: reviewAssignmentId,
-                            claim_id: claimResult.claimId,
-                        }, dispatchCwd);
                         const reviewBrief = buildCoordinateBrief(slot.agent ?? '', reviewDescription + reviewVerdictBriefSuffix, {
                             claimId: claimResult.claimId,
                             scope: reviewScope,
@@ -1045,6 +1157,7 @@ export async function handleBclawCoordinate(args, ctx) {
                             entry: queued.entry,
                             invoke: queued.invoke,
                             worktreePath: claimResult.worktreePath,
+                            turnEcho: reviewTurnEcho,
                         });
                     }
                     catch (dispatchErr) {
@@ -1105,6 +1218,16 @@ export async function handleBclawCoordinate(args, ctx) {
         result = {
             candidate_id: output.candidateId,
             selected_targets: resolvedAgents,
+            // pln#521 P1 (B4) — echo the routing decision so an operator can see WHERE
+            // the loop landed without reverse-engineering cwd and store state. Present
+            // for open_loop reviews (the gated path); the reasoning behind the decision
+            // ships as `_resolution_trace` on dispatch_status, not here.
+            ...(projectResolution
+                ? {
+                    project_cwd: projectResolution.project_cwd,
+                    ...(projectResolution.project_name ? { project_name: projectResolution.project_name } : {}),
+                }
+                : {}),
             // pln#626 Phase 1 (review rework) — expose the reviewer delivery entries
             // so review is as honest as assign/reroute: each entry's execution_reason
             // (set by runCoordinateExecution) feeds the top-level derivation, so a
@@ -1149,8 +1272,7 @@ export async function handleBclawCoordinate(args, ctx) {
             // trp#51: validate target agent before creating a new claim.
             const check = validateAgentForDispatch(newAgentName, { requireSpawnable: true });
             if (!check.valid) {
-                warnings.push(JSON.stringify({
-                    warning: 'agent_validation_failed',
+                pushStructuredWarning(warnings, warningDetails, agentValidationFailedWarning({
                     agent: newAgentName,
                     code: check.code,
                     reason: check.reason,
@@ -1537,8 +1659,7 @@ export async function handleBclawCoordinate(args, ctx) {
                         // behind that only fails later at spawn time.
                         const critCheck = validateAgentForDispatch(slot.agent, { requireSpawnable: true });
                         if (!critCheck.valid) {
-                            warnings.push(JSON.stringify({
-                                warning: 'agent_validation_failed',
+                            pushStructuredWarning(warnings, warningDetails, agentValidationFailedWarning({
                                 agent: slot.agent,
                                 code: critCheck.code,
                                 reason: critCheck.reason,
@@ -1550,12 +1671,6 @@ export async function handleBclawCoordinate(args, ctx) {
                             slotRole: slot.role,
                             memoryProvider: provider,
                         });
-                        turn({
-                            id: loopId,
-                            slot_id: slot.slot_id,
-                            actor: creatorActor,
-                            input: briefResult.text,
-                        }, dispatchCwd);
                         // pln#626 Phase 2 (Option B) — spawn the critic as a worktree-isolated
                         // worker, mirroring the intent=assign / review chain. Each critic gets
                         // its OWN claim + worktree (scope is unique per slot) so parallel
@@ -1605,6 +1720,23 @@ export async function handleBclawCoordinate(args, ctx) {
                             catch (asgErr) {
                                 warnings.push(`ideate assignment creation failed for slot ${slot.slot_id}: ${asgErr instanceof Error ? asgErr.message : String(asgErr)}`);
                             }
+                            // pln#629 — bind the slot to its claim/assignment NOW that both
+                            // exist (mirrors the review path, pln#628 BLOCKING 2). The turn()
+                            // used to fire BEFORE the assignment was created, leaving
+                            // slot.assignment_id undefined: bclaw_loop get's reconcile then
+                            // skipped the critic slot (loops-handlers.ts `if (!assignmentId)
+                            // continue`) and dispatch_status(lop_) resolved no assignment, so
+                            // ideate loops could never be reconciled (trp_dfe0b941 /
+                            // trp_2187b340 / trp_1de94516). Runs even if assignment creation
+                            // failed (undefined id → legacy agent-match fallback, as review).
+                            turn({
+                                id: loopId,
+                                slot_id: slot.slot_id,
+                                actor: creatorActor,
+                                input: briefResult.text,
+                                assignment_id: criticAssignmentId,
+                                claim_id: claimResult.claimId,
+                            }, dispatchCwd);
                             // pln#626 Phase 2 — the critique-only contract must reach the
                             // DELIVERED brief, not just the claim record: buildCoordinateBrief
                             // wraps this in a worker envelope, so prepend the constraint + the
@@ -1754,8 +1886,17 @@ export async function handleBclawCoordinate(args, ctx) {
     // attach a self-documenting `verify_with` hint pointing at the assignment
     // record. Callers should not take delivered_and_started at face value —
     // it only attests the brief-ack sentinel was touched, not that the worker
-    // is doing useful work. The hint tells them exactly which canonical-
-    // grammar call to make next to verify spawn liveness.
+    // is doing useful work.
+    //
+    // pln#634 — the hint used to tell callers to expect "OS pid alive", which
+    // directly contradicts the protocol every instruction file ships
+    // (instruction-templates.ts: trust dispatch_status, NEVER the tracked pid).
+    // On Windows an ack-wrapped spawn runs under cmd.exe, so agent_run.pid is
+    // the wrapper — it exits by design and reads dead while the worker is alive
+    // and committing (trp_7fc3e3c4). An obedient agent following the old text
+    // killed healthy workers. The field shape is unchanged (retro-compat), the
+    // expectation no longer lies, and the authoritative call now also ships in
+    // `next_actions` below as bclaw_dispatch_status.
     let verifyWith;
     if (resultExecStatus === 'delivered_and_started') {
         const firstAssignment = artifacts.find((a) => a.type === 'assignment');
@@ -1764,11 +1905,25 @@ export async function handleBclawCoordinate(args, ctx) {
                 action: 'bclaw_find',
                 entity: 'agent_run',
                 filter: { assignment_id: firstAssignment.id },
-                expected_when_alive: 'agent_run with status="running" AND OS pid alive AND last_event_at within the last few minutes',
+                expected_when_alive: 'agent_run with status="running" AND last_event_at within the last few minutes. '
+                    + 'Do NOT judge liveness from agent_run.pid — on an ack-wrapped spawn that pid is the '
+                    + `wrapper, not the worker. Prefer bclaw_dispatch_status(target_id: "${firstAssignment.id}") `
+                    + 'for a sentinel-based verdict.',
                 see_also: 'docs/concepts/dispatch-lifecycle.md',
             };
         }
     }
+    // pln#634 — outcome-derived affordances on the coordinate facade. Derived
+    // from what actually happened (did anything spawn? was a loop opened?), not
+    // from the intent alone; empty means the key is omitted rather than shipping
+    // an empty array for an agent to parse.
+    const coordinateActions = coordinateNextActions({
+        intent: req.intent,
+        assignmentIds: artifacts.filter((a) => a.type === 'assignment').map((a) => a.id),
+        loopId: artifacts.find((a) => a.type === 'loop')?.id,
+        candidateId: artifacts.find((a) => a.type === 'candidate')?.id,
+        executionStatus: resultExecStatus,
+    });
     const facadeResponse = {
         status: facadeStatus,
         intent: req.intent,
@@ -1780,6 +1935,8 @@ export async function handleBclawCoordinate(args, ctx) {
         ...(resultExecStatus ? { execution_status: resultExecStatus } : {}),
         ...(resultExecReason ? { execution_reason: resultExecReason } : {}),
         ...(verifyWith ? { verify_with: verifyWith } : {}),
+        ...(coordinateActions.length ? { next_actions: coordinateActions } : {}),
+        ...(warningDetails.length ? { warning_details: warningDetails } : {}),
     };
     const summaryParts = [`✔ bclaw_coordinate [${req.intent}] targets=${resolvedAgents.length}`];
     if (resultExecStatus)
@@ -1806,7 +1963,9 @@ export async function handleBclawLoop(args, ctx) {
     }
     // pln#562 step 4 — dispatching a turn hands work to another agent; gate
     // it at the same trust bar as the other dispatch surfaces.
-    if (args?.intent === 'turn' && args?.dispatch === true) {
+    // pln#632 — `bind` also SPAWNS real workers (it dispatches the loop's linked
+    // sequence), so it is gated at the same 'trusted' bar as turn-dispatch / coordinate.
+    if ((args?.intent === 'turn' && args?.dispatch === true) || args?.intent === 'bind') {
         const resolved = ensureTrust(args, { nameField: 'agent', idField: 'agentId' }, 'trusted', cwd, connectionSessionId);
         if (resolved.error) {
             return { response: createToolErrorResponse(resolved.error.kind, resolved.error.message, resolved.error.details) };
@@ -1814,7 +1973,7 @@ export async function handleBclawLoop(args, ctx) {
     }
     const { handleBclawLoop: runLoopIntent } = await import('./loops-handlers.js');
     const targetCwd = resolveProjectCwd(args?.project, cwd);
-    const result = runLoopIntent({ args: args, cwd: targetCwd });
+    const result = await runLoopIntent({ args: args, cwd: targetCwd, sessionId: connectionSessionId });
     return {
         response: toolResponse({
             content: [{ type: 'text', text: result.summary }],

package/dist/commands/mcp-write-entities.js

@@ -23,6 +23,7 @@ import { createPlan, deletePlan as deletePlanOp } from '../core/operations/plan.
 import { loadCandidate } from '../core/candidates.js';
 import { resolveCrossProjectWritableTarget, resolveProjectCwd, writeCrossProjectSignal } from '../core/cross-project.js';
 import { hasMinimumTrustLevel } from '../core/agent-registry.js';
+import { createEntityNextActions, transitionNextActions } from '../core/next-actions.js';
 import { acceptCandidate } from './accept.js';
 import { rejectCandidate } from './reject.js';
 import { applyHandoffUpdates } from './update-handoff.js';
@@ -432,6 +433,10 @@ export function handleBclawCreate(payload, ctx) {
         const createContent = autoRepair
             ? [{ type: 'text', text: createText }, { type: 'text', text: renderAutoRepairWarning(autoRepair, actor ?? 'unknown') }]
             : [{ type: 'text', text: createText }];
+        // 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.
+        const createActions = createEntityNextActions({ entity, id: result.id });
         return {
             response: appendSecurityWarnings(toolResponse({
                 content: createContent,
@@ -441,6 +446,7 @@ export function handleBclawCreate(payload, ctx) {
                     active_source: autoSwitched ? 'auto_switch' : targetScope.active_source,
                     ...(autoSwitched ? { auto_switched: true } : {}),
                     ...(autoRepair ? { auto_repair: autoRepair } : {}),
+                    ...(createActions.length ? { next_actions: createActions } : {}),
                 },
             }), createScan.warnings),
         };
@@ -600,6 +606,10 @@ export function handleBclawTransition(payload, ctx) {
         const transitionContent = auto_repair
             ? [{ type: 'text', text: transitionText }, { type: 'text', text: renderAutoRepairWarning(auto_repair, agent_name) }]
             : [{ type: 'text', text: transitionText }];
+        // pln#634 — only the two transitions that imply an unambiguous next call
+        // emit anything (plan → in_progress / blocked); everything else is terminal
+        // for the caller and returns nothing rather than inventing busywork.
+        const transitionActions = transitionNextActions({ entity, id, to });
         return {
             response: toolResponse({
                 content: transitionContent,
@@ -609,6 +619,7 @@ export function handleBclawTransition(payload, ctx) {
                     active_source: autoSwitched ? 'auto_switch' : targetScope.active_source,
                     ...(autoSwitched ? { auto_switched: true } : {}),
                     ...(auto_repair ? { auto_repair } : {}),
+                    ...(transitionActions.length ? { next_actions: transitionActions } : {}),
                 },
             }),
         };