brainclaw 1.15.0 → 1.17.0

package/dist/core/execution.js

@@ -143,17 +143,37 @@ export async function attemptExecution(invoke, options) {
     const adapter = options.adapter ?? defaultExecutionAdapter;
     // No invoke command available (IDE-only agents, etc.)
     if (!invoke) {
-        return { execution_status: 'inbox_only' };
+        return { execution_status: 'inbox_only', execution_reason: 'no_invoke_command' };
     }
     const spawnCheck = adapter.canSpawn(options.agent);
-    // Opt-out or can't spawn: return command for manual execution
-    // Prepend BRAINCLAW_CLAIM_ID so manual copy-paste still routes correctly
-    if (!options.autoExecute || !spawnCheck.canSpawn) {
+    // pln#626 Phase 1 — split the old `(!autoExecute || !spawnCheck.canSpawn)`
+    // branch, which collapsed two very different outcomes into one silent
+    // command_ready_manual (no reason, no failure_kind — it even discarded
+    // spawnCheck.reason). Callers could not tell "you didn't ask me to spawn"
+    // apart from "I tried and can't".
+    // (1) autoExecute explicitly disabled: a deliberate manual handoff, NOT a
+    // failure. Prepend BRAINCLAW_CLAIM_ID so manual copy-paste still routes.
+    if (!options.autoExecute) {
         const manual = adapter.prepareManualCommand(invoke, options);
         return {
             execution_status: 'command_ready_manual',
             command: manual.command,
             shell: manual.shell,
+            execution_reason: 'auto_execute_disabled',
+        };
+    }
+    // (2) autoExecute requested but the agent cannot be spawned here: this IS a
+    // failure of the caller's intent. Surface spawnCheck.reason (previously
+    // dropped) instead of returning a bare manual command.
+    if (!spawnCheck.canSpawn) {
+        const manual = adapter.prepareManualCommand(invoke, options);
+        return {
+            execution_status: 'command_ready_manual',
+            command: manual.command,
+            shell: manual.shell,
+            error: spawnCheck.reason,
+            failure_kind: 'not_spawnable',
+            execution_reason: 'not_spawnable',
         };
     }
     // pln#531 — isolation invariant: a spawned worker MUST run in its own
@@ -179,6 +199,7 @@ export async function attemptExecution(invoke, options) {
             shell: manual.shell,
             error: 'Refusing to spawn without an isolated worktree: with no worktree the worker would run in the integration repo and edit the main tree. Fix worktree creation (see claim worktreeWarning) or run the command manually inside a worktree.',
             failure_kind: 'spawn_no_worktree',
+            execution_reason: 'spawn_no_worktree',
         };
     }
     // Capacity guard: skip if agent is at max concurrent tasks
@@ -201,6 +222,7 @@ export async function attemptExecution(invoke, options) {
                 shell: manual.shell,
                 error: `Spawn skipped: ${instanceCheck.reason}. Use the command manually.`,
                 failure_kind: 'spawn_capacity',
+                execution_reason: 'spawn_capacity',
             };
         }
     }
@@ -239,6 +261,7 @@ export async function attemptExecution(invoke, options) {
                     shell: manual.shell,
                     error: `Spawn launched (pid ${result.pid}) but assignment ${options.assignmentId} did not acknowledge within ${handshakeTimeoutMs}ms`,
                     failure_kind: 'spawn_no_handshake',
+                    execution_reason: 'spawn_no_handshake',
                     pid: result.pid,
                 };
             }
@@ -280,6 +303,7 @@ export async function attemptExecution(invoke, options) {
             shell: manual.shell,
             error: `Spawn failed (${errorMsg}), falling back to manual execution`,
             failure_kind: 'spawn_failed',
+            execution_reason: 'spawn_failed',
         };
     }
 }

package/dist/core/facade-schema.js

@@ -1,10 +1,17 @@
 import { z } from 'zod';
 export const ExecutionStatusSchema = z.enum(['delivered_and_started', 'command_ready_manual', 'inbox_only']);
 export const WorkIntentSchema = z.enum(['execute', 'consult', 'resume', 'review']);
-// pln#492 phase 2.c — 'ideate' opens an ideation loop with a proposal seed
-// artifact. The handler does NOT yet dispatch turns (driver wire-up is
-// phase 2.d). Callers receive loop_id and may drive the loop manually via
-// bclaw_loop intent='turn' / 'advance' until the dispatch path lands.
+// pln#626 — coordinate intents split into three honest contracts:
+//  • SPAWNING (assign / review / reroute, + multi-agent ideate): create a claim
+//    + worktree and, when autoExecute is on, spawn a worker on the brief.
+//    'ideate' with targetAgents advances to critique and spawns one
+//    worktree-isolated critic worker per target (Phase 2, Option B); single-
+//    agent ideate just opens the loop for the champion to drive manually via
+//    bclaw_loop intent='turn'/'advance'.
+//  • INBOX-ONLY (consult): delivers the brief to the target inbox; autoExecute
+//    is a no-op here (never silently ignored).
+//  • READ-ONLY (summarize): reads a thread and returns a summary — no claim,
+//    no dispatch, no execution_status; autoExecute is irrelevant.
 export const CoordinateIntentSchema = z.enum(['assign', 'consult', 'review', 'reroute', 'summarize', 'ideate']);
 export const WorkRequestSchema = z.object({
     intent: WorkIntentSchema,
@@ -172,6 +179,13 @@ export const FacadeResponseSchema = z.object({
     session_id: z.string().optional(),
     warnings: z.array(z.string()),
     execution_status: ExecutionStatusSchema.optional(),
+    /**
+     * pln#626 Phase 1 — machine-readable reason accompanying execution_status
+     * when it is not `delivered_and_started`: auto_execute_disabled (manual
+     * handoff), not_spawnable, spawn_no_worktree/capacity/no_handshake/failed,
+     * or intent_inbox_only (consult/ideate). Absent when everything spawned.
+     */
+    execution_reason: z.string().optional(),
     /** pln#503 phase 3.3: present when execution_status === 'delivered_and_started'. */
     verify_with: VerifyWithSchema.optional(),
     /**

package/dist/core/handoff-review.js

@@ -0,0 +1,35 @@
+import { nowISO } from './ids.js';
+/**
+ * The review sub-fields whose presence in a patch marks the review as
+ * "completed" and (re)stamps `reviewed_at`. Single source of truth for the
+ * completion rule — shared by the canonical grammar (`updateEntity(handoff)`)
+ * and the dispatcher/CLI path (`applyHandoffUpdates`) so the two write paths
+ * can never drift (pln#625 Phase 3, Codex review of #84).
+ */
+export const REVIEW_COMPLETION_FIELDS = [
+    'verdict',
+    'reviewed_by',
+    'summary',
+    'blocking_issues',
+    'suggestions',
+];
+/**
+ * Merge a partial review patch onto an existing review (shallow — PATCH
+ * semantics: provided fields overwrite, others survive) and stamp
+ * `reviewed_at` when the patch introduces a completion field.
+ *
+ * A caller that explicitly provides `reviewed_at` (e.g. a federation import
+ * replaying a prior review) keeps its value; otherwise a completing patch
+ * stamps `nowISO()`. The flat-option callers (applyHandoffUpdates) never carry
+ * `reviewed_at`, so for them this is an unconditional restamp-on-completion —
+ * identical to the pre-extraction behaviour.
+ */
+export function mergeHandoffReview(existing, patch) {
+    const merged = { ...(existing ?? {}), ...patch };
+    const completed = REVIEW_COMPLETION_FIELDS.some((field) => patch[field] !== undefined);
+    if (completed && patch.reviewed_at === undefined) {
+        merged.reviewed_at = nowISO();
+    }
+    return merged;
+}
+//# sourceMappingURL=handoff-review.js.map

package/dist/core/protocol-tool-policy.js

@@ -0,0 +1,113 @@
+/**
+ * Static protocol tool-policy name lists (core-owned, pln#622 PR1).
+ *
+ * Ces listes statiques REMPLACENT les dérivations depuis les annotations
+ * d'ALL_TOOLS ; la cohérence avec le catalogue est garantie par
+ * tests/unit/protocol-tool-policy.test.ts.
+ *
+ * (These STATIC lists REPLACE the derivations from ALL_TOOLS annotations for
+ * core consumers: core/ must not import the commands/ MCP layer, so the tool
+ * names are materialised here instead of being derived from the catalog at
+ * import time. The catalog — src/commands/mcp-catalog.ts — KEEPS deriving its
+ * own copies from tool annotations; bidirectional set equality between these
+ * static lists and the catalog derivations is enforced by
+ * tests/unit/protocol-tool-policy.test.ts.)
+ *
+ * Zero imports by design — this module must stay a pure leaf.
+ *
+ * @module
+ */
+/**
+ * Tools safe for headless auto-approval (annotation `headlessApproval: 'auto'`
+ * in the catalog). Consumed by agent-files writers (Cline autoApprove, Roo
+ * alwaysAllow, Codex approval_mode). Order mirrors catalog declaration order
+ * so generated agent config files are byte-identical to the derived era.
+ */
+export const MCP_HEADLESS_AUTO_TOOL_NAMES = [
+    'bclaw_context',
+    'bclaw_search',
+    'bclaw_estimation_report',
+    'bclaw_list_sequences',
+    'bclaw_assignment_events',
+    'bclaw_list_agents',
+    'bclaw_list_instructions',
+    'bclaw_get_capabilities',
+    'bclaw_list_tools',
+    'bclaw_search_tools',
+    'bclaw_doctor',
+    'bclaw_history',
+    'bclaw_audit',
+    'bclaw_get_discovery',
+    'bclaw_conflict_check',
+    'bclaw_who',
+    'bclaw_check_policy',
+    'bclaw_check_security',
+    'bclaw_read_inbox',
+    'bclaw_get_thread',
+    'bclaw_dispatch_status',
+    'bclaw_code_status',
+    'bclaw_code_find',
+    'bclaw_code_brief',
+    'bclaw_send_message',
+    'bclaw_ack_message',
+    'bclaw_write_note',
+    'bclaw_quick_capture',
+    'bclaw_claim',
+    'bclaw_release_claim',
+    'bclaw_session_start',
+    'bclaw_session_end',
+    'bclaw_add_step',
+    'bclaw_complete_step',
+    'bclaw_update_step',
+    'bclaw_update_handoff',
+    'bclaw_work',
+    'bclaw_coordinate',
+    'bclaw_loop',
+    'bclaw_assignment_update',
+    'bclaw_assignment_action',
+    'bclaw_harvest_candidates',
+    'bclaw_find',
+    'bclaw_get',
+];
+/**
+ * Narrow "canonical grammar" tool set — the read-side facade entries
+ * (session + context) plus the five memory verbs. Consumed by writers
+ * (e.g. Hermes' tools.include) that want a minimal advertised surface.
+ */
+export const MCP_CANONICAL_GRAMMAR_TOOL_NAMES = [
+    'bclaw_context',
+    'bclaw_work',
+    'bclaw_find',
+    'bclaw_get',
+    'bclaw_create',
+    'bclaw_update',
+    'bclaw_transition',
+];
+/**
+ * Tools removed from the MCP surface at the v1.0 cut (Phase 3 slice 3i).
+ * Hidden from every `tools/list` response; direct `tools/call` still works
+ * as a migration escape hatch.
+ */
+export const REMOVED_IN_V1_TOOLS = new Set([
+    'bclaw_list_plans',
+    'bclaw_list_candidates',
+    'bclaw_list_claims',
+    'bclaw_list_actions',
+    'bclaw_list_assignments',
+    'bclaw_list_runs',
+    'bclaw_list_agents', // pln#625 — retired for bclaw_find(entity='agent')
+    'bclaw_read_handoff',
+    'bclaw_create_plan',
+    'bclaw_update_plan',
+    'bclaw_create_candidate',
+    'bclaw_accept',
+    'bclaw_reject',
+    'bclaw_get_execution_context',
+    'bclaw_get_agent_board',
+    'bclaw_get_agent_board_summary',
+    'bclaw_dispatch_analysis',
+    'bclaw_dispatch_review',
+    'bclaw_update_handoff',
+    'bclaw_get_context',
+]);
+//# sourceMappingURL=protocol-tool-policy.js.map

package/dist/core/review-loop-close.js

@@ -0,0 +1,184 @@
+import { getLoop } from './loops/store.js';
+import { complete_turn, advance } from './loops/verbs.js';
+import { withLoopLock } from './loops/lock.js';
+/** review-loop:lop_xxx → the loop id (mirrors assignment-reconciler.ts). */
+const REVIEW_LOOP_SCOPE_RE = /^review-loop:(lop_[0-9a-z]+)/;
+const LOOP_TERMINAL = new Set(['completed', 'cancelled', 'blocked']);
+/** Build the fix+re-review brief for a request_changes cycle turn (symmetric). */
+function buildFixCycleTask(summary, iteration) {
+    return (`The reviewer requested changes (fix cycle round ${iteration}). `
+        + 'Apply the requested changes DIRECTLY in this worktree (it is the same '
+        + 'checkout, kept across turns so your commits accumulate), then RE-REVIEW '
+        + 'the result. Set review_verdict="approve" once the change is correct and '
+        + 'complete, or "request_changes" to take another pass.'
+        + (summary ? `\n\nRequested changes: ${summary}` : ''));
+}
+/** Mirrors verbs.ts:isVerdictAccepted — reviewer_green fires only on a `verdict`
+ * artifact whose body starts with "accepted". */
+function isAcceptedVerdict(artifact) {
+    if (artifact.type !== 'verdict')
+        return false;
+    return /^accepted(?:\b|[:\s])/.test((artifact.body ?? '').trim().toLowerCase());
+}
+/**
+ * Resolve the reviewer slot to complete. STRICT binding first: the active slot
+ * whose assignment_id matches this lane's assignment (the #87 coordinate fix
+ * stamps it), so symmetric loops target the right reviewer. If OTHER slots are
+ * bound but none matches ours, refuse (never complete someone else's slot).
+ * Falls back to a single active reviewer / agent match only for legacy unbound
+ * slots. Returns undefined when no active reviewer slot is ours — the caller
+ * then checks the resume path.
+ */
+function resolveReviewerSlot(loop, assignment) {
+    const active = loop.slots.filter((s) => s.role === 'reviewer' && s.status !== 'done' && s.status !== 'cancelled' && s.status !== 'failed');
+    if (active.length === 0)
+        return undefined;
+    if (assignment.id) {
+        const bound = active.find((s) => s.assignment_id === assignment.id);
+        if (bound)
+            return bound;
+        // Some active slots are bound to OTHER assignments — do not guess/steal.
+        if (active.some((s) => s.assignment_id !== undefined))
+            return undefined;
+    }
+    // Legacy unbound slots: single reviewer, else disambiguate by agent.
+    if (active.length === 1)
+        return active[0];
+    const byAgent = assignment.agent ? active.find((s) => s.agent === assignment.agent) : undefined;
+    return byAgent ?? active[0];
+}
+export function closeReviewLoopFromLaneResult(assignment, lane, actor, cwd, options) {
+    const scopeMatch = assignment.scope?.match(REVIEW_LOOP_SCOPE_RE);
+    if (!scopeMatch)
+        return undefined;
+    if (!lane.review_verdict)
+        return undefined;
+    const cycleOnRequestChanges = options?.cycleOnRequestChanges ?? true;
+    const loopId = scopeMatch[1];
+    const verdict = lane.review_verdict;
+    const noop = (reason, loop_status) => ({
+        loop_id: loopId, verdict, action: 'noop', reason, loop_status,
+    });
+    try {
+        // Lock the loop so the compound complete_turn + advance can't interleave
+        // with a concurrent harvest (BLOCKING 3). All state is re-read inside.
+        return withLoopLock({
+            cwd,
+            intent: 'review-harvest-close',
+            agentId: actor,
+            scope: { kind: 'loop', loopId },
+            work: () => {
+                const loop = getLoop(loopId, cwd);
+                if (!loop)
+                    return noop('loop not found');
+                if (LOOP_TERMINAL.has(loop.status))
+                    return noop(`loop already ${loop.status}`, loop.status);
+                const slot = resolveReviewerSlot(loop, assignment);
+                const acceptedVerdictExists = loop.artifacts.some(isAcceptedVerdict);
+                const summary = (lane.review_summary ?? '').trim();
+                // ── approve → close on reviewer_green ───────────────────────────────
+                if (verdict === 'approve') {
+                    if (slot) {
+                        // isVerdictAccepted fires reviewer_green ONLY on an "accepted…" body.
+                        complete_turn({
+                            id: loopId, slot_id: slot.slot_id, actor,
+                            artifact: { phase: loop.current_phase, type: 'verdict', body: `accepted${summary ? `: ${summary}` : ''}` },
+                        }, cwd);
+                    }
+                    else if (!acceptedVerdictExists) {
+                        // No slot to complete and no accepted verdict recorded → a prior pass
+                        // already processed this (idempotent no-op).
+                        return noop('already processed (no active reviewer slot; no accepted verdict to resume)', loop.status);
+                    }
+                    // Advance: closes on reviewer_green. Convergent — safe whether we just
+                    // recorded the verdict or are resuming an interrupted approve.
+                    const advanced = advance({ id: loopId, actor }, cwd);
+                    return {
+                        loop_id: loopId,
+                        verdict,
+                        action: advanced.auto_closed ? 'closed' : 'advanced',
+                        reason: advanced.auto_closed
+                            ? `reviewer_green → loop ${advanced.loop.status}`
+                            : `accepted verdict recorded → advanced to "${advanced.loop.current_phase}"`,
+                        loop_status: advanced.loop.status,
+                    };
+                }
+                // ── request_changes → autonomous fix cycle (PR2) ────────────────────
+                if (!slot) {
+                    // The cycle already advanced + re-dispatched on the first pass (the
+                    // re-dispatched slot is now bound to a NEWER assignment, so
+                    // resolveReviewerSlot returned undefined here → idempotent no-op).
+                    return noop('already processed (no active reviewer slot to cycle)', loop.status);
+                }
+                if (!cycleOnRequestChanges) {
+                    // Report-only path: never advance a cycle it can't follow through on
+                    // (no re-dispatch, no claim retention). Defer to `harvest --integrate`.
+                    return noop('request_changes deferred to --integrate (report path does not cycle)', loop.status);
+                }
+                // Codex review P1 — the autonomous fix cycle is SYMMETRIC-only in v1: it
+                // asks the SAME reviewer slot to modify AND re-review in the reused
+                // worktree, which is only sound when both roles are the same coding agent
+                // (mode='symmetric'). Review loops DEFAULT to asymmetric, where the
+                // reviewer must NOT self-fix. For asymmetric, fall back to the PR1
+                // behavior: record the verdict, advance linearly to `author_response`,
+                // and DO NOT keep the claim / emit a next_turn — the author-fix dispatch
+                // is a planned follow-up, so a human drives it. (No re-dispatch means no
+                // worktree reuse, so the claim is released by harvest as usual.)
+                const symmetric = loop.protocol?.review_mode === 'symmetric';
+                complete_turn({
+                    id: loopId, slot_id: slot.slot_id, actor,
+                    artifact: { phase: loop.current_phase, type: 'verdict', body: `changes-requested${summary ? `: ${summary}` : ''}` },
+                }, cwd);
+                if (!symmetric) {
+                    const advancedAsym = advance({ id: loopId, actor }, cwd);
+                    return {
+                        loop_id: loopId,
+                        verdict,
+                        action: advancedAsym.auto_closed ? 'closed' : 'advanced',
+                        reason: advancedAsym.auto_closed
+                            ? `request_changes → loop ${advancedAsym.loop.status}`
+                            : `request_changes (asymmetric) → advanced to "${advancedAsym.loop.current_phase}"; author-fix dispatch is a follow-up (drive manually)`,
+                        loop_status: advancedAsym.loop.status,
+                    };
+                }
+                // Symmetric: bump the round counter by advancing to the SAME phase
+                // (advance treats to_phase <= current as a backward iteration →
+                // iteration_count += 1). The post-advance stop_condition (max_iterations
+                // n=3) auto-closes the loop as `blocked` once the cap is hit; otherwise
+                // the loop stays open and we hand harvest a `next_turn` to re-dispatch
+                // into the SAME (kept) worktree so fixes accumulate on one branch.
+                const advanced = advance({ id: loopId, to_phase: loop.current_phase, actor }, cwd);
+                if (advanced.auto_closed) {
+                    return {
+                        loop_id: loopId,
+                        verdict,
+                        action: 'closed',
+                        reason: `request_changes hit iteration cap → loop ${advanced.loop.status} (needs human)`,
+                        loop_status: advanced.loop.status,
+                    };
+                }
+                return {
+                    loop_id: loopId,
+                    verdict,
+                    action: 'advanced',
+                    reason: `request_changes (round ${advanced.loop.iteration_count}) → re-dispatch same reviewer into kept worktree`,
+                    loop_status: advanced.loop.status,
+                    keep_claim: true,
+                    next_turn: {
+                        slot_id: slot.slot_id,
+                        role: slot.role,
+                        agent: slot.agent ?? '',
+                        agent_id: slot.agent_id,
+                        phase: advanced.loop.current_phase,
+                        iteration: advanced.loop.iteration_count,
+                        task: buildFixCycleTask(summary, advanced.loop.iteration_count),
+                    },
+                };
+            },
+        });
+    }
+    catch (err) {
+        return noop(`loop close error (harvest not blocked): ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+//# sourceMappingURL=review-loop-close.js.map

package/dist/core/review-loop-turn-dispatch.js

@@ -0,0 +1,183 @@
+/**
+ * pln#628 Focus 4B PR2 — reusable "dispatch one review-loop turn".
+ *
+ * PR1 wired the harvest→loop direction (a reviewer verdict advances/closes the
+ * loop). PR2 makes the request_changes→fix→re-review cycle autonomous, which
+ * means the harvest close path must be able to SPAWN the next turn's worker
+ * (the author to apply fixes, then the reviewer to re-review). The full spawn
+ * chain — coordinator claim + assignment + slot binding + brief + queued inbox
+ * message + CLI spawn — used to live only as closures inside the
+ * bclaw_coordinate review handler (mcp-write-coordination.ts). This module
+ * lifts that chain into a standalone, closure-free function the harvest path
+ * can call.
+ *
+ * Layering (mirrors review-loop-close.ts's cycle-avoidance note): this is a
+ * core module that imports the heavy dispatch primitives (execution, dispatcher,
+ * claims, messaging, assignments). review-loop-close.ts stays PURE (loops +
+ * schema only) and merely RETURNS a `NextTurn` descriptor; harvest.ts is the
+ * command-level orchestrator that owns both and calls this to spawn. Nothing
+ * here imports harvest or review-loop-close, so no import cycle is introduced.
+ */
+import { createCoordinatorClaim, attachAssignmentMessageToClaim, linkClaimToAssignment } from './claims.js';
+import { createAssignment, transitionAssignment, generateAssignmentId, patchAssignmentMessageId } from './assignments.js';
+import { turn } from './loops/verbs.js';
+import { generateDispatchBrief } from './dispatcher.js';
+import { sendMessage } from './messaging.js';
+import { buildInvokeCommand, resolveModel } from './agent-capability.js';
+import { attemptExecution } from './execution.js';
+/**
+ * The structured signal a reviewer must emit in LANE-RESULT.json so harvest can
+ * map its lane back onto the loop. Shared by the initial dispatch and every
+ * re-review turn (identical wording keeps the reviewer contract stable).
+ */
+export const REVIEW_VERDICT_BRIEF_SUFFIX = '\n\n## Review verdict (required — drives autonomous loop convergence)\n'
+    + 'In your LANE-RESULT.json set "status":"completed" AND add "review_verdict": '
+    + '"approve" (change is good to merge) or "request_changes" (needs fixes), plus '
+    + '"review_summary":"<one-line rationale>". The coordinator reads review_verdict '
+    + 'to close the review loop on approve, or continue the fix cycle on request_changes.';
+/**
+ * Dispatch a single review-loop turn: create the coordinator claim + assignment,
+ * bind the slot to them (so harvest resolves the exact slot by assignment_id),
+ * build + queue the brief, and spawn the worker CLI.
+ *
+ * Best-effort and non-throwing: any failure is returned in `.error` so the
+ * caller (harvest) can record it as a warning without aborting the harvest —
+ * the loop simply stays open awaiting a manual turn. Mirrors the resilience of
+ * the initial reviewer dispatch (which pushes a warning and leaves the loop open
+ * on failure) rather than the fail-fast style of a user-facing command.
+ */
+export async function dispatchReviewLoopTurn(input) {
+    const { loopId, slot, phase } = input;
+    // createCoordinatorClaim / sendMessage require a concrete cwd; the harvest
+    // caller always supplies one — default defensively for direct callers/tests.
+    const cwd = input.cwd ?? process.cwd();
+    const agent = slot.agent ?? '';
+    const scope = `review-loop:${loopId}`;
+    const isReviewer = slot.role === 'reviewer';
+    const result = {
+        loop_id: loopId,
+        slot_id: slot.slot_id,
+        role: slot.role,
+        agent,
+        phase,
+    };
+    try {
+        const description = `Review loop turn for ${loopId} slot ${slot.slot_id} phase ${phase}. ${input.task}`;
+        const claimResult = createCoordinatorClaim({
+            agent,
+            scope,
+            description,
+            dispatcherAgent: input.dispatcherAgent,
+            sessionId: input.sessionId,
+            cwd,
+            worktreeBaseRef: input.worktreeBaseRef,
+        });
+        result.claim_id = claimResult.claimId;
+        result.worktree_path = claimResult.worktreePath;
+        let assignmentId;
+        try {
+            const preId = generateAssignmentId(cwd);
+            const assignment = createAssignment({
+                id: preId.id,
+                short_label: preId.short_label,
+                claim_id: claimResult.claimId,
+                agent,
+                dispatcher_agent: input.dispatcherAgent,
+                dispatcher_session_id: input.sessionId,
+                scope,
+                description,
+                tags: ['coordinate', 'review', 'loop', isReviewer ? 're-review' : 'author-fix'],
+            }, cwd);
+            assignmentId = assignment.id;
+            result.assignment_id = assignment.id;
+        }
+        catch (asgErr) {
+            result.error = `assignment creation failed: ${asgErr instanceof Error ? asgErr.message : String(asgErr)}`;
+        }
+        // Bind the slot to the new claim/assignment (PR1 BLOCKING 2 invariant): a
+        // later harvest must resolve THIS slot by assignment_id, not by agent name
+        // (which is ambiguous under symmetric multi-reviewer loops). Runs even if
+        // assignment creation failed (undefined id → legacy agent-match fallback).
+        turn({
+            id: loopId,
+            slot_id: slot.slot_id,
+            actor: input.dispatcherAgentId ?? input.dispatcherAgent,
+            input: input.task,
+            assignment_id: assignmentId,
+            claim_id: claimResult.claimId,
+        }, cwd);
+        // Reviewer turns must carry the verdict contract; author-fix turns must not
+        // (an author lane has no verdict — it's mapped by scope+slot instead).
+        const briefTask = isReviewer ? input.task + REVIEW_VERDICT_BRIEF_SUFFIX : input.task;
+        const brief = generateDispatchBrief({
+            task: briefTask,
+            agent,
+            claimId: claimResult.claimId,
+            scope,
+            worktreePath: claimResult.worktreePath,
+            assignmentId,
+        });
+        const msg = sendMessage({
+            from: input.dispatcherAgent,
+            to: agent,
+            type: 'review',
+            text: brief,
+            ref: loopId,
+            scope,
+            requires_ack: true,
+            claim_id: claimResult.claimId,
+            assignment_id: assignmentId,
+            tags: ['coordinate', 'review', 'loop', isReviewer ? 're-review' : 'author-fix'],
+            author_id: input.dispatcherAgentId,
+            session_id: input.sessionId,
+            payload: {
+                intent: 'review',
+                loop_id: loopId,
+                slot_id: slot.slot_id,
+                phase,
+                scope,
+                claim_id: claimResult.claimId,
+                ...(assignmentId ? { assignment_id: assignmentId } : {}),
+                worktree_path: claimResult.worktreePath,
+            },
+        }, cwd);
+        result.message_id = msg.id;
+        if (assignmentId) {
+            try {
+                attachAssignmentMessageToClaim(claimResult.claimId, msg.id, cwd);
+                linkClaimToAssignment(claimResult.claimId, assignmentId, cwd);
+                transitionAssignment(assignmentId, 'offered', { actor: input.dispatcherAgent }, cwd);
+                patchAssignmentMessageId(assignmentId, msg.id, cwd);
+            }
+            catch (linkErr) {
+                result.error = `assignment linkage failed: ${linkErr instanceof Error ? linkErr.message : String(linkErr)}`;
+            }
+        }
+        const invoke = buildInvokeCommand(agent, brief, {
+            mode: 'worker',
+            model: resolveModel(agent, { override: input.model }),
+        });
+        const execResult = await attemptExecution(invoke, {
+            agent,
+            autoExecute: true,
+            worktreePath: claimResult.worktreePath,
+            claimId: claimResult.claimId,
+            assignmentId,
+            dispatcherAgent: input.dispatcherAgent,
+            dispatcherAgentId: input.dispatcherAgentId,
+            cwd,
+            requireWorktree: true, // never spawn a worker in the integration repo (pln#531)
+        });
+        result.execution_status = execResult.execution_status;
+        result.command = execResult.command;
+        result.shell = execResult.shell;
+        if (execResult.error && !result.error)
+            result.error = execResult.error;
+        return result;
+    }
+    catch (err) {
+        result.error = `review-loop turn dispatch failed: ${err instanceof Error ? err.message : String(err)}`;
+        return result;
+    }
+}
+//# sourceMappingURL=review-loop-turn-dispatch.js.map