brainclaw 1.17.0 → 1.18.0

package/dist/commands/loops-handlers.js

@@ -1,6 +1,9 @@
 import { ZodError } from 'zod';
 import { listAgentRuns } from '../core/agentruns.js';
 import { reconcileAgentRun } from '../core/agentrun-reconciler.js';
+import { findReservationByRunId } from '../core/loops/attempt-reservation.js';
+import { runVerify } from '../core/loops/verify-command.js';
+import { runImplBind } from '../core/loops/impl-bind.js';
 import { add_artifact, advance, AwaitingFileApplyApprovalError, closeLoop, complete_turn, computeNextExpected, getLoop, IdempotencyKeyReusedError, IdempotencyOwnerMismatchError, listLoopEvents, listLoops, LockLostError, LockTimeoutError, openLoop, pause, provideInput, requestInput, resume, sweepPauseTimeouts, turn, VersionConflictError, withLoopLock, } 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
@@ -179,7 +182,7 @@ function trySweepLoopTimeouts(loop_id, cwd) {
     }
     catch { /* best-effort: never block facade on sweep errors */ }
 }
-export function handleBclawLoop(options) {
+export async function handleBclawLoop(options) {
     const startMs = Date.now();
     const defaultActor = options.defaultActor ?? 'bclaw_loop';
     const inferredIntent = inferIntent(options.args);
@@ -218,6 +221,7 @@ export function handleBclawLoop(options) {
                         linked: req.linked,
                         stop_condition: req.stop_condition,
                         mode: req.mode,
+                        verify: req.verify,
                         created_by: agentId,
                     }, options.cwd);
                     const newEvents = findNewLoopEvents(loop.id, undefined, options.cwd);
@@ -257,7 +261,20 @@ export function handleBclawLoop(options) {
                             continue;
                         if (slotStatus === 'done' || slotStatus === 'failed' || slotStatus === 'cancelled')
                             continue;
+                        // pln#630 PR2b-c (§13 R6): GET is strictly observational for
+                        // TURN-OWNED slots. A slot carrying current_turn_id reconciles only
+                        // via the dedicated mutating reconcile path (never on a read), so a
+                        // stale/racing read can't phantom-complete its run. Legacy slots
+                        // (no current_turn_id) keep the intentional lazy reconcile
+                        // (trp_fdf3e590) that converges silent-completion on access.
+                        if (slot.current_turn_id)
+                            continue;
                         for (const run of listAgentRuns(options.cwd, { assignment_id: assignmentId })) {
+                            // Belt-and-braces (review PR2b-c #D): skip by ACTUAL ownership too,
+                            // not just the slot pointer — if a run is turn-owned but its slot
+                            // wasn't stamped (write-ordering), GET must still not mutate it.
+                            if (findReservationByRunId(run.id, options.cwd))
+                                continue;
                             reconcileAgentRun(run.id, options.cwd);
                         }
                     }
@@ -426,6 +443,70 @@ export function handleBclawLoop(options) {
                     return successResponse('close', { loop, next_expected: null }, [loopArtifactEntry(loop.id), ...loopEventArtifacts(newEvents)], [sideEffectUpdate('loop', loop.id), ...loopEventSideEffects(newEvents)], [], Date.now() - startMs, summarizeLoop(loop));
                 });
             }
+            case 'verify': {
+                // pln#632 — run the loop's opener-configured verify command + record a
+                // deterministic verify_report. runVerify manages its OWN two lock scopes (the
+                // spawn runs OUT of the lock), so it is NOT wrapped in withLockedLoopMutation.
+                const existing = getLoop(req.loop_id, options.cwd);
+                if (!existing) {
+                    return errorResponse('verify', 'not_found', `unknown loop_id ${req.loop_id}`, Date.now() - startMs);
+                }
+                const beforeEvents = snapshotLoopEvents(req.loop_id, options.cwd);
+                const result = runVerify({ loop_id: req.loop_id, actor }, options.cwd);
+                const newEvents = findNewLoopEvents(result.thread.id, beforeEvents, options.cwd);
+                const summary = result.unconfigured
+                    ? `verify: loop has no protocol.verify — falling back to an agent-narrated verify_report`
+                    : result.deduped
+                        ? `verify: a verify_report already exists for iteration ${result.thread.iteration_count} (idempotent)`
+                        : `${result.report?.passed ? '✔ verify green' : result.report?.timed_out ? '✖ verify RED (timeout)' : '✖ verify red'}: ${result.report?.command ?? ''}`;
+                return successResponse('verify', {
+                    loop: result.thread,
+                    verify_report: result.report ?? null,
+                    deduped: result.deduped,
+                    unconfigured: result.unconfigured ?? false,
+                    next_expected: computeNextExpected(result.thread),
+                }, [loopArtifactEntry(result.thread.id), ...loopEventArtifacts(newEvents)], [sideEffectUpdate('loop', result.thread.id), ...loopEventSideEffects(newEvents)], [], Date.now() - startMs, summary);
+            }
+            case 'bind': {
+                // pln#632 impl-loop bind — dispatch the loop's linked sequence + advance
+                // bind→execute. runImplBind awaits the async spawn (the advance takes its own
+                // lock via the verb), so it is NOT wrapped in withLockedLoopMutation — it mirrors
+                // coordinate(open_loop)'s async-handler-spawns pattern, not a synchronous verb.
+                const existing = getLoop(req.loop_id, options.cwd);
+                if (!existing) {
+                    return errorResponse('bind', 'not_found', `unknown loop_id ${req.loop_id}`, Date.now() - startMs);
+                }
+                if (existing.kind !== 'implementation') {
+                    return errorResponse('bind', 'validation_error', `bind is only valid for implementation loops (loop ${req.loop_id} is kind='${existing.kind}'); review/ideation loops dispatch via bclaw_coordinate`, Date.now() - startMs);
+                }
+                const beforeEvents = snapshotLoopEvents(req.loop_id, options.cwd);
+                const bind = await runImplBind({
+                    loop_id: req.loop_id,
+                    dispatcherAgent: actor,
+                    dispatcherAgentId: agentId,
+                    sessionId: options.sessionId,
+                    dryRun: req.dry_run,
+                    lanes: req.lanes,
+                    autoExecute: req.auto_execute,
+                    model: req.model,
+                    maxAssignments: req.max_assignments,
+                }, options.cwd);
+                const loop = getLoop(req.loop_id, options.cwd);
+                const newEvents = findNewLoopEvents(loop.id, beforeEvents, options.cwd);
+                const sideEffects = bind.action === 'bound'
+                    ? [sideEffectUpdate('loop', loop.id), ...loopEventSideEffects(newEvents)]
+                    : [...loopEventSideEffects(newEvents)];
+                return successResponse('bind', {
+                    loop,
+                    sequence_id: bind.sequence_id,
+                    action: bind.action,
+                    advanced_to: bind.advanced_to ?? null,
+                    auto_closed: bind.auto_closed ?? false,
+                    dispatched: bind.messages_sent,
+                    dispatch: bind.dispatch,
+                    next_expected: computeNextExpected(loop),
+                }, [loopArtifactEntry(loop.id), ...loopEventArtifacts(newEvents)], sideEffects, bind.dispatch?.warnings ?? [], Date.now() - startMs, bind.reason);
+            }
         }
     }
     catch (err) {

package/dist/commands/mcp-catalog.js

@@ -360,19 +360,22 @@ export const MCP_READ_TOOLS = [
     },
     {
         name: 'bclaw_read_inbox',
-        description: 'Read messages from an agent inbox. Returns pending messages by default. Use markAsRead to auto-mark pending messages as read. Supports filtering by status, type, and thread_id.',
+        description: 'Read messages from an agent inbox, newest-first. By default returns only ACTIONABLE messages (pending + read) and hides acknowledged/archived — pass includeAll=true, or a specific status, to widen. Message bodies are previewed (~500 chars) unless full=true; the page is size-bounded by budget_tokens so a read can never blow the token budget. Use markAsRead to auto-mark pending messages as read.',
         annotations: { tier: 'standard', category: 'coordination', headlessApproval: 'auto' },
         inputSchema: {
             type: 'object',
             properties: {
                 agent: { type: 'string', description: 'Agent name whose inbox to read. Defaults to calling agent.' },
                 agentId: { type: 'string', description: 'Registered agent id.' },
-                status: { type: 'string', description: 'Filter by status: pending, read, acknowledged, archived.' },
+                status: { type: 'string', description: 'Filter by an exact status: pending, read, acknowledged, archived. Overrides the actionable default.' },
+                includeAll: { type: 'boolean', description: 'Return every status (including acknowledged + archived), disabling the actionable default. Default: false.' },
                 type: { type: 'string', description: 'Filter by message type: assign, review, rfc, info, reply.' },
                 thread_id: { type: 'string', description: 'Filter by thread ID to see a conversation.' },
+                full: { type: 'boolean', description: 'Return complete message bodies instead of ~500-char previews. Each previewed message reports text_length + truncated:true. Default: false.' },
                 markAsRead: { type: 'boolean', description: 'Mark pending messages as read. Default: false.' },
                 limit: { type: 'number', description: 'Maximum messages to return (default: 20).' },
                 offset: { type: 'number', description: 'Skip N messages for pagination.' },
+                budget_tokens: { type: 'number', description: 'Cap the returned page size (~4 chars/token). Messages are trimmed until the payload fits; has_more/next_offset let you page the rest.' },
             },
         },
     },
@@ -1028,8 +1031,8 @@ const MCP_WRITE_TOOLS = [
                     // created a loop structure without dispatching the first turn, so
                     // nothing ever ran. Loops are opened via
                     // bclaw_coordinate(intent='review', open_loop=true) or intent='ideate'.
-                    enum: ['get', 'list', 'turn', 'complete_turn', 'advance', 'add_artifact', 'pause', 'resume', 'close'],
-                    description: 'Loop lifecycle intent for driving turns inside a loop that was already opened via the coordinate facade. To START a loop, use `bclaw_coordinate(intent="review", open_loop=true, targetAgents=[…])` or `intent="ideate"` — that opens the loop AND dispatches the first turn. See docs/concepts/loop-engine.md.',
+                    enum: ['get', 'list', 'turn', 'complete_turn', 'advance', 'add_artifact', 'pause', 'resume', 'close', 'bind'],
+                    description: 'Loop lifecycle intent for driving turns inside a loop that was already opened via the coordinate facade. To START a loop, use `bclaw_coordinate(intent="review", open_loop=true, targetAgents=[…])` or `intent="ideate"` — that opens the loop AND dispatches the first turn. `bind` (implementation loops only) dispatches the loop\'s linked sequence and advances bind→execute — the engine action for the `bind` phase. See docs/concepts/loop-engine.md.',
                 },
                 loop_id: { type: 'string', description: 'Target loop id (lop_…). Required for every intent except open and list.' },
                 kind: { type: 'string', enum: ['review', 'ideation', 'implementation', 'research', 'debug'], description: 'Loop kind for open / list filter.' },
@@ -1052,6 +1055,11 @@ const MCP_WRITE_TOOLS = [
                 outcome: { type: 'string', enum: ['done', 'failed', 'cancelled'], description: 'complete_turn outcome (default done).' },
                 failure_reason: { type: 'string', description: 'complete_turn: optional failure/cancel reason.' },
                 artifact: { type: 'object', description: 'complete_turn / add_artifact payload: { phase, type, body?, produced_by?, ref? }.' },
+                dry_run: { type: 'boolean', description: 'bind: analyze + report what would dispatch; no spawn, no advance.' },
+                lanes: { type: 'array', items: { type: 'string' }, description: 'bind: restrict the dispatch to specific sequence lanes.' },
+                auto_execute: { type: 'boolean', description: 'bind: deliver briefs without spawning (→ manual launch commands).' },
+                model: { type: 'string', description: 'bind: model override for the dispatched agents.' },
+                max_assignments: { type: 'number', description: 'bind: cap assignments made in this bind.' },
                 to_phase: { type: 'string', description: 'advance: explicit target phase (otherwise the next phase).' },
                 force: { type: 'boolean', description: 'advance: allow going backwards (increments iteration_count).' },
                 reason: { type: 'string', description: 'advance / pause / close: optional reason string.' },

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

@@ -149,6 +149,7 @@ export function handleMcpReadToolCall(name, args = {}, context = {}) {
     let agentNameCache;
     return dispatchReadTool(name, args, {
         cwd,
+        sourceCwd: effective.cwd,
         activeSource,
         resolvedProject,
         projectRoutingApplied,
@@ -1803,6 +1804,8 @@ function dispatchReadTool(name, args, ctx) {
     if (name === 'bclaw_read_inbox') {
         const agentName = args.agent ?? ctx.getAgentName();
         const markAsRead = args.markAsRead === true; // default: false — reading doesn't imply processing
+        const includeAll = args.includeAll === true; // pln#627 Phase A — widen past the actionable default
+        const full = args.full === true; // pln#627 Phase A — return whole bodies, not previews
         const result = readInbox({
             agent: agentName,
             status: args.status,
@@ -1810,21 +1813,77 @@ function dispatchReadTool(name, args, ctx) {
             thread_id: args.thread_id,
             limit: args.limit,
             offset: args.offset,
+            includeAll,
             markAsRead,
         }, cwd);
-        const lines = [`Inbox for ${agentName} — ${result.total} message(s):`];
-        for (const msg of result.messages) {
+        // pln#627 Phase A — bound the payload so a single inbox read can never blow
+        // the MCP token budget (root cause: persona/CoDev dumps persisted as inbox
+        // messages, one at 960 KB). Two independent guards:
+        //   1. per-message: preview each body to INBOX_PREVIEW_CHARS unless full=true;
+        //      the whole body stays available via full=true (bclaw_get(inbox_message)
+        //      is per-agent-scoped and cannot serve one message by id).
+        //   2. whole-page: boundListResult trims messages until the JSON fits the
+        //      char budget, the same way bclaw_find / bclaw_search do (~4 chars/token).
+        const INBOX_PREVIEW_CHARS = 500;
+        const projected = result.messages.map((msg) => {
+            const textLength = msg.text.length;
+            const truncated = !full && textLength > INBOX_PREVIEW_CHARS;
+            return {
+                ...msg,
+                text: truncated ? msg.text.slice(0, INBOX_PREVIEW_CHARS) : msg.text,
+                text_length: textLength,
+                truncated,
+            };
+        });
+        const budgetTokens = typeof args.budget_tokens === 'number' && args.budget_tokens > 0 ? args.budget_tokens : undefined;
+        const charBudget = budgetTokens ? Math.min(budgetTokens * 4, DEFAULT_FIND_CHAR_BUDGET) : DEFAULT_FIND_CHAR_BUDGET;
+        const bounded = boundListResult({ entity: 'inbox_message', total: result.total, items: projected }, result.offset, charBudget);
+        const scopeNote = includeAll || args.status ? '' : ' actionable (pending+read); pass includeAll=true for acknowledged/archived';
+        const lines = [`Inbox for ${agentName} — ${result.total} message(s)${scopeNote}:`];
+        for (const msg of bounded.items) {
             const ack = msg.requires_ack ? ' [ACK required]' : '';
             const thread = msg.thread_id ? ` thread:${msg.thread_id}` : '';
             lines.push(`  [${msg.short_label ?? msg.id}] ${msg.type} from ${msg.from} (${msg.status})${ack}${thread}`);
-            lines.push(`    ${msg.text.slice(0, 200)}${msg.text.length > 200 ? '...' : ''}`);
-        }
-        if (result.messages.length === 0) {
+            const preview = msg.text.slice(0, 200);
+            const more = msg.truncated || msg.text_length > 200;
+            const moreNote = more
+                ? `… (${msg.text_length} chars${msg.truncated ? '; pass full=true for the whole body' : ''})`
+                : '';
+            lines.push(`    ${preview}${moreNote}`);
+        }
+        if (bounded.items.length === 0) {
             lines.push('  (no messages)');
         }
+        if (bounded.hint)
+            lines.push('', bounded.hint);
+        const nextActions = bounded.has_more
+            ? [{
+                    tool: 'bclaw_read_inbox',
+                    args: {
+                        ...(args.agent ? { agent: args.agent } : {}),
+                        offset: bounded.next_offset,
+                        ...(args.limit ? { limit: args.limit } : {}),
+                        ...(args.status ? { status: args.status } : {}),
+                        ...(includeAll ? { includeAll: true } : {}),
+                    },
+                    when: 'to fetch the next page',
+                }]
+            : [];
         return {
             content: [{ type: 'text', text: lines.join('\n') }],
-            structuredContent: { ...result, schema_version: SCHEMA_VERSION },
+            structuredContent: {
+                total: result.total,
+                offset: result.offset,
+                limit: result.limit,
+                messages: bounded.items,
+                returned: bounded.returned,
+                has_more: bounded.has_more,
+                ...(bounded.next_offset !== undefined ? { next_offset: bounded.next_offset } : {}),
+                ...(bounded.omitted_for_size ? { omitted_for_size: bounded.omitted_for_size } : {}),
+                ...(bounded.hint ? { hint: bounded.hint } : {}),
+                ...(nextActions.length ? { next_actions: nextActions } : {}),
+                schema_version: SCHEMA_VERSION,
+            },
         };
     }
     if (name === 'bclaw_context') {
@@ -1915,9 +1974,33 @@ function dispatchReadTool(name, args, ctx) {
             `  stderr: ${status.runtime.log_files.stderr?.exists ? `${status.runtime.log_files.stderr.size_bytes}B` : 'absent'}`,
             `  git: commits_ahead=${status.runtime.commits_ahead ?? 'n/a'} dirty_tracked=${status.runtime.dirty_tracked ?? 'n/a'}`,
         ];
+        // pln#521 P1 (B4) — routing echo. Operators debugging a dispatch need to see
+        // which project this status was read from, and WHY that project won, without
+        // reverse-engineering cwd + store state. The decision (project_name/
+        // project_cwd) is a first-class field; the reasoning is the `_resolution_trace`
+        // sibling, which by design ships here and nowhere else. Deliberately cheap:
+        // no candidate/nested-store scan on a hot read path. source_cwd is the
+        // PRE-routing cwd (ctx.sourceCwd) — using the routed cwd would make the two
+        // ends identical exactly when a `project` arg hopped stores, i.e. the one
+        // case the trace exists to show.
+        const projectCwd = resolvedProject?.path ?? cwd;
+        const projectName = resolvedProject?.name;
+        const resolutionTrace = {
+            source_cwd: ctx.sourceCwd,
+            effective_cwd: projectCwd,
+            active_source: activeSource,
+            ...(projectRoutingApplied && typeof args.project === 'string' ? { project_arg: args.project } : {}),
+        };
+        lines.push('', `Project: ${projectName ?? '(unnamed)'} — ${projectCwd} (via ${activeSource})`);
         return {
             content: [{ type: 'text', text: lines.join('\n') }],
-            structuredContent: { ...status, schema_version: SCHEMA_VERSION },
+            structuredContent: {
+                ...status,
+                project_cwd: projectCwd,
+                ...(projectName ? { project_name: projectName } : {}),
+                _resolution_trace: resolutionTrace,
+                schema_version: SCHEMA_VERSION,
+            },
         };
     }
     throw new Error(`Unknown read tool: ${name}`);

package/dist/commands/mcp-schemas.generated.js

@@ -291,6 +291,9 @@ export const generatedSchemas = {
                     "failed",
                     "cancelled"
                 ]
+            },
+            "current_turn_id": {
+                "type": "string"
             }
         },
         "required": [

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

@@ -20,12 +20,14 @@ 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 { 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';
@@ -228,11 +230,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 +274,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) {
@@ -356,6 +360,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 +436,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 +447,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 +471,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({
@@ -969,38 +1020,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 +1140,7 @@ export async function handleBclawCoordinate(args, ctx) {
                             entry: queued.entry,
                             invoke: queued.invoke,
                             worktreePath: claimResult.worktreePath,
+                            turnEcho: reviewTurnEcho,
                         });
                     }
                     catch (dispatchErr) {
@@ -1105,6 +1201,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
@@ -1550,12 +1656,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 +1705,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
@@ -1806,7 +1923,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 +1933,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 }],