brainclaw 1.16.0 → 1.18.0

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

@@ -4,6 +4,18 @@ 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).
+ *  Exported so the turn-owned reconcile path (pln#630 PR3b) reuses the identical
+ *  wording — the reviewer contract must not drift between the legacy and turn-owned
+ *  fix cycles. */
+export 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) {
@@ -38,22 +50,13 @@ function resolveReviewerSlot(loop, assignment) {
     const byAgent = assignment.agent ? active.find((s) => s.agent === assignment.agent) : undefined;
     return byAgent ?? active[0];
 }
-/**
- * Map a harvested review lane onto its loop and close/advance it.
- *
- * Fires ONLY when the assignment scope is a review-loop (`review-loop:lop_…`)
- * AND the lane carries a `review_verdict` — otherwise returns undefined and the
- * caller (harvest) proceeds unchanged. Idempotent, convergent, and defensive:
- * a terminal loop is a no-op, a partial prior pass is resumed, and any
- * loop-verb / lock error is swallowed into a `noop` result so a loop-close
- * failure never breaks harvest (mirrors convergeSlotAssignmentsForClosedLoop).
- */
-export function closeReviewLoopFromLaneResult(assignment, lane, actor, cwd) {
+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) => ({
@@ -75,35 +78,104 @@ export function closeReviewLoopFromLaneResult(assignment, lane, actor, cwd) {
                     return noop(`loop already ${loop.status}`, loop.status);
                 const slot = resolveReviewerSlot(loop, assignment);
                 const acceptedVerdictExists = loop.artifacts.some(isAcceptedVerdict);
-                if (slot) {
-                    // Active reviewer slot → record the verdict on it. isVerdictAccepted
-                    // fires reviewer_green ONLY on an "accepted…" body, so approve MUST
-                    // start with "accepted" and request_changes must NOT.
-                    const summary = (lane.review_summary ?? '').trim();
-                    const body = verdict === 'approve'
-                        ? `accepted${summary ? `: ${summary}` : ''}`
-                        : `changes-requested${summary ? `: ${summary}` : ''}`;
-                    complete_turn({ id: loopId, slot_id: slot.slot_id, actor, artifact: { phase: loop.current_phase, type: 'verdict', body } }, cwd);
+                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,
+                    };
                 }
-                else if (!(verdict === 'approve' && acceptedVerdictExists)) {
-                    // No reviewer slot is ours to complete. Resume ONLY the approve→close
-                    // case: a prior pass recorded an accepted verdict but died before
-                    // advancing. For request_changes (or no accepted verdict), the single
-                    // advance already happened on the first pass — do not re-advance.
-                    return noop('already processed (no active reviewer slot to (re)advance)', 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,
+                    };
                 }
-                // Advance: closes on reviewer_green (approve), else moves one phase.
-                // 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}`
-                        : `verdict recorded → advanced to phase "${advanced.loop.current_phase}" (awaiting fix cycle — PR2)`,
+                    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),
+                    },
                 };
             },
         });

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

@@ -0,0 +1,445 @@
+/**
+ * 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, loadAssignment } from './assignments.js';
+import { turn } from './loops/verbs.js';
+import { getLoop } from './loops/store.js';
+import { generateDispatchBrief } from './dispatcher.js';
+import { sendMessage } from './messaging.js';
+import { buildInvokeCommand, resolveModel } from './agent-capability.js';
+import { attemptExecution } from './execution.js';
+import { createAgentRun, loadAgentRun, transitionAgentRun } from './agentruns.js';
+import { reserve, commitReservation, armLaunch, consumeLaunchGrant, launchGrant, deriveTurnId, deriveChildIds, ReservationStateError, LaunchFenceError, } from './loops/attempt-reservation.js';
+/**
+ * pln#630 — gate for the turn-owned (exactly-once) review dispatch path.
+ *
+ * NOW DEFAULT ON (the shipped default): the finalization (PR3a), autonomous fix-cycle (PR3b),
+ * strand self-heal (PR4), and revoked-grant recovery (R1) are all merged; the §9 conformance
+ * harness + a live end-to-end (real spawn → turn-keyed sentinel → harvest → reconcileTurn →
+ * close-on-approve) validated the path. `BRAINCLAW_TURN_OWNED_REVIEW=0` is the explicit
+ * KILL-SWITCH that reverts to the legacy closer (byte-identical) if a problem surfaces in prod.
+ * Note the routing is doubly-gated: even ON, harvest only reconcile-turns a lane that OWNS a
+ * turn reservation — a legacy-dispatched lane (no reservation) still uses the legacy path.
+ */
+export function turnOwnedReviewEnabled() {
+    // Normalized kill-switch (review Finding 4): any of 0/false/off/no (case/space-insensitive)
+    // disables — so an operator reaching for it under pressure can't mis-set it. Anything else
+    // (including unset) keeps the shipped default ON.
+    const v = (process.env.BRAINCLAW_TURN_OWNED_REVIEW ?? '').trim().toLowerCase();
+    return !['0', 'false', 'off', 'no'].includes(v);
+}
+/** GRANT lease: bounds ONE launch generation's reserve→arm→consume→spawn→run-`running`
+ *  window. Long enough that a genuinely launching worker never expires under the PR2c-lease
+ *  pre-run reconciler; a live `running` run is out of that reconciler's scope. */
+const TURN_OWNED_LEASE_MS = 10 * 60_000;
+/** DISPATCH lease: how long the committed RESERVATION stays re-dispatchable. Strictly LONGER
+ *  than the grant lease (pln#630 dec#149 R1 / review Finding 1): a reserved_never_launched
+ *  round (grant lease expired → the reconciler revokes the grant) then still has a RECOVERY
+ *  WINDOW to re-arm a fresh generation before the reservation itself expires. armLaunch
+ *  enforces this bound, so a re-dispatch past it refuses arm and stays correctly stranded —
+ *  no phantom-spawn-after-lease. Decoupling the two is what makes R1 recovery actually reachable
+ *  (with a single shared lease, the grant is revoked exactly when the dispatch lease is already
+ *  expired, so re-arm was always denied). */
+const TURN_OWNED_DISPATCH_LEASE_MS = 30 * 60_000;
+/**
+ * Prepare a turn-owned review dispatch (pln#630 PR2c-b, design dec#144). Runs the
+ * exactly-once machine INLINE in the coordinator (which has store access, unlike
+ * the sandboxed worktree — trp_26e9634b): deterministic turn_id → reserve/adopt →
+ * commit → arm/adopt → consume, spawning ONLY on the winning consume.
+ *
+ * FAIL-CLOSED after `reserve`: once identity is claimed, any error aborts as
+ * `denied` (never legacy) so an ungated legacy worker can never spawn beside a
+ * live reservation (the adversarial double-spawn hole, dec#144 MUST-FIX 1). Only
+ * a failure BEFORE identity is reserved degrades to `legacy`.
+ */
+export function prepareTurnOwnedReviewDispatch(input) {
+    const { loopId, slotId, claimId, cwd } = input;
+    // ── Snapshot the loop BEFORE turn() bumps its version (dec#139 item 3). ──
+    let iteration;
+    let version;
+    try {
+        const thread = getLoop(loopId, cwd);
+        if (!thread)
+            return { kind: 'legacy' }; // loop not found — pre-identity, safe to degrade
+        iteration = thread.iteration_count;
+        version = thread.version;
+    }
+    catch {
+        return { kind: 'legacy' };
+    }
+    const turnId = deriveTurnId(loopId, slotId, iteration);
+    const { assignment_id: assignmentId, run_id: runId } = deriveChildIds(turnId);
+    // Decoupled leases (dec#149 R1): the reservation dispatch lease is longer than each grant's
+    // lease, giving a revoked (reserved_never_launched) round a window to re-arm. reserve() adopts
+    // on a re-dispatch, so the ORIGINAL (longer) dispatch lease governs re-arm eligibility.
+    const dispatchLease = new Date(Date.now() + TURN_OWNED_DISPATCH_LEASE_MS).toISOString();
+    const grantLease = new Date(Date.now() + TURN_OWNED_LEASE_MS).toISOString();
+    // ── Phase 1: claim identity. Fail-OPEN allowed ONLY here (nothing reserved yet). ──
+    try {
+        reserve({
+            turn_id: turnId,
+            loop_id: loopId,
+            slot_id: slotId,
+            target_slot_generation: iteration, // LoopSlot has no generation field — observational proxy (dec#144 #8)
+            loop_version_at_reserve: version,
+            agent: input.agent,
+            agent_id: input.agentId,
+            claim_id: claimId,
+            phase: input.phase,
+            iteration,
+            store_root: cwd,
+            cwd,
+            lease_deadline: dispatchLease,
+        }, cwd);
+    }
+    catch (err) {
+        if (err instanceof ReservationStateError && err.code === 'reservation_exists') {
+            // A concurrent dispatch already OWNS this turn_id — adopt it and fall
+            // through to the fail-closed consume path (we may still legitimately win
+            // the fence if the owner reserved-but-never-crossed; otherwise denied).
+        }
+        else {
+            // FAIL-CLOSED (review Finding 1): any other reserve outcome is
+            // INDETERMINATE — a lock timeout (a live holder mid-critical-section),
+            // lock-lost, or unknown error does NOT prove that no identity was claimed.
+            // Degrading to `legacy` here would spawn an ungated worker beside a
+            // reservation that may well exist — the exact concurrent-dispatch
+            // double-spawn MUST-FIX 1 closes. (A definitively pre-identity error is
+            // unreachable here: the lease we build is always parseable, and
+            // loop-not-found is handled before reserve.)
+            return { kind: 'denied', reason: `reserve indeterminate — fail-closed (no legacy fallback): ${err instanceof Error ? err.message : String(err)}` };
+        }
+    }
+    // ── Phase 2: FAIL-CLOSED. Identity is reserved; never legacy-spawn from here. ──
+    try {
+        commitReservation(turnId, cwd);
+        // Arm-or-adopt the launch grant. Arm when none exists OR when a prior generation was
+        // REVOKED (reserved_never_launched — a crash between arm and consume, then the expiry
+        // sweep): re-arm a FRESH generation at a strictly-higher epoch so a revoked round becomes
+        // re-dispatchable (pln#630 dec#149 R1 strand recovery). armLaunch permits re-arming a
+        // revoked grant and still enforces the dispatch lease, so a lease-expired reservation
+        // refuses arm and stays correctly stranded (never a phantom-spawn-after-lease). A
+        // concurrent arm surfaces as `already_armed` → adopt the incumbent grant.
+        let grant = launchGrant(turnId, cwd);
+        if (!grant || grant.status === 'revoked') {
+            const priorEpoch = grant?.epoch ?? -1; // fresh → epoch 0 (unchanged); revoked → epoch+1
+            try {
+                armLaunch(turnId, { epoch: priorEpoch + 1, lease_deadline: grantLease }, cwd);
+            }
+            catch (err) {
+                if (!(err instanceof LaunchFenceError && err.code === 'already_armed')) {
+                    // dispatch_lease_expired / lease_invalid / not_committed / epoch_mismatch → do-not-spawn.
+                    return { kind: 'denied', reason: `arm_refused: ${err instanceof Error ? err.message : String(err)}` };
+                }
+            }
+            grant = launchGrant(turnId, cwd);
+        }
+        // A crossed grant = launch_attempted_unknown (worker already invoked, never re-spawn);
+        // still-revoked = re-arm refused (lease expired) → never-launch; absent → all do-not-spawn.
+        if (!grant || grant.status !== 'armed') {
+            return { kind: 'denied', reason: `launch_denied: grant is ${grant?.status ?? 'absent'} (not armed)` };
+        }
+        // Consume the grant — the atomic exactly-once SPAWN authority.
+        let wonTransition;
+        try {
+            ({ wonTransition } = consumeLaunchGrant(turnId, grant.token, grant.epoch, cwd));
+        }
+        catch (err) {
+            return { kind: 'denied', reason: `launch_denied: consume refused (${err instanceof Error ? err.message : String(err)})` };
+        }
+        if (!wonTransition) {
+            // Adopted — another invocation crossed the fence. MUST NOT spawn.
+            return { kind: 'denied', reason: 'launch_denied: grant already crossed by a concurrent dispatch' };
+        }
+        // ── WON: this dispatch is the SOLE spawner. Bind slot + run to MY live claim
+        // (claimId), NOT the reservation's first-reserver claim (dec#144 #3) — else a
+        // recovery-winner would bind the slot to a dead claim and break complete_turn
+        // auth. Mints are idempotent (save overwrites, so guard on load). ──
+        if (!loadAssignment(assignmentId, cwd)) {
+            createAssignment({
+                id: assignmentId,
+                short_label: assignmentId,
+                claim_id: claimId,
+                agent: input.agent,
+                dispatcher_agent: input.dispatcherAgent,
+                dispatcher_session_id: input.sessionId,
+                scope: input.scope,
+                description: input.description,
+                tags: ['coordinate', 'review', 'loop', 'turn-owned', input.isReviewer ? 're-review' : 'author-fix'],
+            }, cwd);
+        }
+        if (!loadAgentRun(runId, cwd)) {
+            createAgentRun({
+                id: runId,
+                short_label: runId,
+                assignment_id: assignmentId,
+                claim_id: claimId,
+                agent: input.agent,
+                agent_id: input.agentId,
+                transport: 'cli_spawn',
+                status: 'created',
+                scope: input.scope,
+                description: input.description,
+                worktree_path: input.worktreePath,
+                tags: ['turn-owned', 'review', 'loop'],
+            }, cwd);
+        }
+        turn({
+            id: loopId,
+            slot_id: slotId,
+            actor: input.dispatcherAgentId ?? input.dispatcherAgent,
+            input: input.task,
+            turn_id: turnId,
+            assignment_id: assignmentId,
+            claim_id: claimId,
+        }, cwd);
+        return { kind: 'won', assignmentId, runId, turnId, nonce: grant.token };
+    }
+    catch (err) {
+        // FAIL-CLOSED: identity reserved; degrade to denied, NEVER legacy.
+        return { kind: 'denied', reason: `turn-owned prep aborted after reserve: ${err instanceof Error ? err.message : String(err)}` };
+    }
+}
+/**
+ * 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;
+        let turnEcho;
+        let runLegacyProjection = true;
+        // pln#630 — turn-owned (exactly-once) dispatch, now the DEFAULT + FAIL-CLOSED after
+        // reserve. Kill-switch off (BRAINCLAW_TURN_OWNED_REVIEW=0) → runLegacyProjection stays
+        // true and this branch is a byte-identical no-op (the legacy projection below runs).
+        if (turnOwnedReviewEnabled()) {
+            const prep = prepareTurnOwnedReviewDispatch({
+                loopId,
+                slotId: slot.slot_id,
+                agent,
+                agentId: slot.agent_id,
+                phase,
+                task: input.task,
+                description,
+                scope,
+                claimId: claimResult.claimId,
+                worktreePath: claimResult.worktreePath,
+                dispatcherAgent: input.dispatcherAgent,
+                dispatcherAgentId: input.dispatcherAgentId,
+                sessionId: input.sessionId,
+                isReviewer,
+                cwd,
+            });
+            if (prep.kind === 'denied') {
+                // The exactly-once fence says this dispatch is NOT the spawner (adopted /
+                // crossed / revoked / lease-expired). MUST NOT spawn AND MUST NOT fall back
+                // to legacy — a legacy spawn beside the live reservation is the double-spawn
+                // hole the fence exists to close (dec#144 MUST-FIX 1).
+                //
+                // Do NOT release the coordinator claim here (review Finding 2, round 2):
+                // createCoordinatorClaim dedups on scope+agent, so a same-turn concurrent
+                // dispatch SHARES one claim C1 — and claim-creation order is uncoupled from
+                // fence-crossing order (different locks), so the loser can be C1's creator
+                // while the WINNER merely reused it and bound its slot/run/assignment to C1.
+                // releaseClaim() runs unauthenticated with no active-binding guard, so ANY
+                // release in the denied path can flip a claim a live winner depends on to
+                // `released` (re-opening the slot.claim_id divergence MUST-FIX 3 closed). A
+                // genuine orphan — the rare double-failure where no dispatch wins — is
+                // low-harm and reaped by the claim staleness sweep (auto_release_after_hours);
+                // sabotaging a live winner is high-harm and not self-healing. So we leave it.
+                result.execution_status = 'inbox_only';
+                result.error = prep.reason;
+                return result;
+            }
+            if (prep.kind === 'won') {
+                // Deterministic assignment mint + slot binding already happened inside
+                // prepare; skip the legacy projection and carry the turn-keyed echo so the
+                // ack-wrapper writes a turn-keyed completion sentinel.
+                assignmentId = prep.assignmentId;
+                result.assignment_id = prep.assignmentId;
+                turnEcho = { turn_id: prep.turnId, run_id: prep.runId, nonce: prep.nonce };
+                runLegacyProjection = false;
+            }
+            // prep.kind === 'legacy' (fail-open BEFORE identity) → fall through unchanged.
+        }
+        if (runLegacyProjection) {
+            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)
+            turnEcho, // pln#630 PR2c-b — undefined on the legacy path (wrapper unchanged)
+        });
+        result.execution_status = execResult.execution_status;
+        result.command = execResult.command;
+        result.shell = execResult.shell;
+        if (execResult.error && !result.error)
+            result.error = execResult.error;
+        // pln#630 PR2c-b — a turn-owned run was preallocated `created`; once the
+        // worker actually spawned, move it to `running` so it leaves the PR2c-lease
+        // pre-run lease scope (created/launching) and is governed by the heartbeat
+        // reconciler instead. If it did NOT start, leave it `created` → the pre-run
+        // reconciler converges it (crossed → launch_attempted_unknown) at lease.
+        if (turnEcho && execResult.execution_status === 'delivered_and_started') {
+            try {
+                transitionAgentRun(turnEcho.run_id, 'running', { actor: input.dispatcherAgent, status_reason: 'turn-owned worker spawned' }, cwd);
+            }
+            catch { /* best-effort — the reconciler converges if this races */ }
+        }
+        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