brainclaw 1.17.0 → 1.19.0

package/dist/core/next-actions.js

@@ -0,0 +1,157 @@
+/**
+ * Verifying a spawned worker: always `bclaw_dispatch_status`, never
+ * `bclaw_find(agent_run)` + a pid check. On Windows an ack-wrapped spawn runs
+ * under cmd.exe, so `agent_run.pid` is the wrapper (which exits by design) and
+ * reads dead while the worker is alive (trp_7fc3e3c4). `dispatch_status`
+ * returns a sentinel-based verdict instead.
+ */
+export function verifyDispatchAction(targetId, note) {
+    return {
+        tool: 'bclaw_dispatch_status',
+        args: { target_id: targetId },
+        when: note
+            ? `${note} — sentinel-based liveness verdict (do NOT judge from agent_run.pid)`
+            : 'verify the spawned worker is actually alive — sentinel-based verdict (do NOT judge from agent_run.pid)',
+    };
+}
+/** Cap on repeated per-target actions, so a wide fan-out cannot flood the field. */
+const FANOUT_CAP = 3;
+function verifyActions(targetIds, note) {
+    const shown = targetIds.slice(0, FANOUT_CAP);
+    const actions = shown.map((id) => verifyDispatchAction(id, note));
+    if (targetIds.length > shown.length) {
+        // Say what was dropped rather than silently truncating.
+        actions.push({
+            tool: 'bclaw_dispatch_status',
+            args: { target_id: '<one of the remaining targets>' },
+            when: `${targetIds.length - shown.length} further target(s) were dispatched — verify each one the same way`,
+        });
+    }
+    return actions;
+}
+/**
+ * After a release, the follow-up depends entirely on what the cascade decided:
+ * a blocked plan transition needs the other claim holders inspected, a
+ * completed plan is ready for review, and a plain release has no next step at
+ * all.
+ */
+export function releaseClaimNextActions(outcome) {
+    const actions = [];
+    if (outcome.planWarning && outcome.planId) {
+        // The cascade refused: other claims still hold the plan. Both the diagnosis
+        // and the eventual manual transition are real MCP calls.
+        actions.push({
+            tool: 'bclaw_find',
+            args: { entity: 'claim', filter: { plan_id: outcome.planId, status: 'active' } },
+            when: 'the plan was NOT transitioned because other claims are still active — see who else holds it',
+        });
+        actions.push({
+            tool: 'bclaw_transition',
+            args: { entity: 'plan', id: outcome.planId, to: outcome.requestedPlanStatus ?? 'done' },
+            when: 'once the other claims are released, transition the plan yourself',
+        });
+        return actions;
+    }
+    if (outcome.planTransitioned && outcome.planId) {
+        // Documented workflow: implement → release → review.
+        actions.push({
+            tool: 'bclaw_coordinate',
+            args: {
+                intent: 'review',
+                task: `Review the work delivered under plan ${outcome.planId}`,
+                open_loop: true,
+            },
+            when: 'the plan is done — the next workflow stage is review',
+        });
+    }
+    return actions;
+}
+/**
+ * Only two transitions imply an unambiguous next call. Everything else
+ * (candidate accepted, plan done, trap retired, …) is terminal for the caller,
+ * so it returns nothing rather than inventing busywork.
+ */
+export function transitionNextActions(outcome) {
+    if (outcome.entity === 'plan' && outcome.to === 'in_progress') {
+        return [{
+                tool: 'bclaw_work',
+                args: { intent: 'execute', planId: outcome.id, scope: '<scope you are about to edit>' },
+                when: 'the plan is in progress — claim the scope before editing',
+            }];
+    }
+    if (outcome.entity === 'plan' && outcome.to === 'blocked') {
+        return [{
+                tool: 'bclaw_quick_capture',
+                args: { text: '<what blocks this plan>', type: 'trap' },
+                when: 'record WHY it is blocked so the next agent does not rediscover it',
+            }];
+    }
+    return [];
+}
+/**
+ * Coordinate's follow-up is driven by whether anything actually spawned, not by
+ * the intent alone: the same `intent='assign'` needs verification when it
+ * spawned and nothing MCP-callable when it produced manual commands.
+ */
+export function coordinateNextActions(outcome) {
+    const actions = [];
+    const spawned = outcome.executionStatus === 'delivered_and_started';
+    if (spawned && outcome.assignmentIds.length > 0) {
+        actions.push(...verifyActions(outcome.assignmentIds));
+    }
+    if (outcome.loopId) {
+        actions.push({
+            tool: 'bclaw_loop',
+            args: { intent: 'get', loop_id: outcome.loopId },
+            when: spawned
+                ? 'inspect loop state — its `next_expected` names the turn the loop is waiting on'
+                : 'the loop is open but nothing spawned — inspect it and drive the turn yourself',
+        });
+    }
+    // Manual-handoff spawning intents: the launch commands are in the text body
+    // (not MCP-callable), so the only real MCP follow-up is verification AFTER
+    // the operator runs them.
+    if (!spawned && outcome.executionStatus === 'command_ready_manual' && outcome.assignmentIds.length > 0) {
+        actions.push(verifyActions(outcome.assignmentIds, 'once you have run the launch command(s) printed above')[0]);
+    }
+    return actions;
+}
+export function dispatchNextActions(outcome) {
+    if (outcome.dryRun) {
+        return [{
+                tool: 'bclaw_dispatch',
+                args: { intent: 'execute' },
+                when: 'this was a dry run — nothing was dispatched; re-run without dryRun to actually spawn',
+            }];
+    }
+    const actions = [];
+    if (outcome.spawnedTargets.length > 0) {
+        actions.push(...verifyActions(outcome.spawnedTargets));
+    }
+    if (outcome.blockedCount > 0) {
+        actions.push({
+            tool: 'bclaw_dispatch',
+            args: { intent: 'analysis' },
+            when: `${outcome.blockedCount} lane(s) are blocked — analysis explains which gate holds each one`,
+        });
+    }
+    return actions;
+}
+export function createEntityNextActions(outcome) {
+    if (outcome.entity === 'plan') {
+        return [{
+                tool: 'bclaw_add_step',
+                args: { planId: outcome.id, data: { text: '<first unit of work>' } },
+                when: 'break the plan into steps so progress is trackable',
+            }];
+    }
+    if (outcome.entity === 'sequence') {
+        return [{
+                tool: 'bclaw_dispatch',
+                args: { intent: 'analysis' },
+                when: 'inspect lane readiness before dispatching the sequence',
+            }];
+    }
+    return [];
+}
+//# sourceMappingURL=next-actions.js.map

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

@@ -1,11 +1,24 @@
 import { getLoop } from './loops/store.js';
 import { complete_turn, advance } from './loops/verbs.js';
 import { withLoopLock } from './loops/lock.js';
+import { LOOP_ARTIFACT_BODY_MAX_BYTES } from './loops/types.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) {
+/** Keep the loop-facing verdict valid while the full worker body stays durable in harvest metadata. */
+function capVerdictBody(prefix, detail) {
+    const full = `${prefix}${detail ? `: ${detail}` : ''}`;
+    if (Buffer.byteLength(full, 'utf8') <= LOOP_ARTIFACT_BODY_MAX_BYTES)
+        return full;
+    const marker = '…[truncated; full body retained in lane harvest event]';
+    const room = LOOP_ARTIFACT_BODY_MAX_BYTES - Buffer.byteLength(prefix, 'utf8') - Buffer.byteLength(': ', 'utf8') - Buffer.byteLength(marker, 'utf8');
+    return `${prefix}: ${Buffer.from(detail, 'utf8').subarray(0, Math.max(0, room)).toString('utf8').replace(/�+$/, '')}${marker}`;
+}
+/** 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 '
@@ -75,14 +88,21 @@ export function closeReviewLoopFromLaneResult(assignment, lane, actor, cwd, opti
                     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();
+                const detail = (lane.body ?? 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}` : ''}` },
+                            // pln#639 BUG-2 — the phase the slot was DISPATCHED in, not the
+                            // loop's phase at close time. Same defect as the ideation closer;
+                            // fixed here too because this is the far more travelled path.
+                            // Safe for the approve flow: `reviewer_green` scans every artifact
+                            // via isVerdictAccepted regardless of phase, and no gate in the
+                            // engine keys on `type: 'verdict'` — so this changes attribution
+                            // truth without changing a single gate outcome.
+                            artifact: { phase: slot.phase ?? loop.current_phase, type: 'verdict', body: capVerdictBody('accepted', detail) },
                         }, cwd);
                     }
                     else if (!acceptedVerdictExists) {
@@ -127,7 +147,8 @@ export function closeReviewLoopFromLaneResult(assignment, lane, actor, cwd, opti
                 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}` : ''}` },
+                    // pln#639 BUG-2 — dispatch phase, not close-time phase (see above).
+                    artifact: { phase: slot.phase ?? loop.current_phase, type: 'verdict', body: capVerdictBody('changes-requested', detail) },
                 }, cwd);
                 if (!symmetric) {
                     const advancedAsym = advance({ id: loopId, actor }, cwd);
@@ -171,7 +192,7 @@ export function closeReviewLoopFromLaneResult(assignment, lane, actor, cwd, opti
                         agent_id: slot.agent_id,
                         phase: advanced.loop.current_phase,
                         iteration: advanced.loop.iteration_count,
-                        task: buildFixCycleTask(summary, advanced.loop.iteration_count),
+                        task: buildFixCycleTask(detail, advanced.loop.iteration_count),
                     },
                 };
             },

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

@@ -19,12 +19,205 @@
  * 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 { 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
@@ -75,37 +268,94 @@ export async function dispatchReviewLoopTurn(input) {
         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,
+        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,
-                dispatcher_agent: input.dispatcherAgent,
-                dispatcher_session_id: input.sessionId,
-                scope,
+                agentId: slot.agent_id,
+                phase,
+                task: input.task,
                 description,
-                tags: ['coordinate', 'review', 'loop', isReviewer ? 're-review' : 'author-fix'],
-            }, cwd);
-            assignmentId = assignment.id;
-            result.assignment_id = assignment.id;
+                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.
         }
-        catch (asgErr) {
-            result.error = `assignment creation failed: ${asgErr instanceof Error ? asgErr.message : String(asgErr)}`;
+        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);
         }
-        // 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;
@@ -167,12 +417,24 @@ export async function dispatchReviewLoopTurn(input) {
             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) {

package/dist/core/runtime-signals.js

@@ -114,6 +114,74 @@ export function readHeartbeat(root, assignmentId, worktreePath) {
         return projectInfo;
     return (worktreeInfo.mtimeMs ?? 0) > (projectInfo.mtimeMs ?? 0) ? worktreeInfo : projectInfo;
 }
+/**
+ * Write a turn-keyed completion/failed sentinel body. Used when brainclaw itself
+ * (wrapper/reconcile) writes the sentinel; the shell `&& completed` fallback
+ * still produces a legacy presence-only marker, which stays a valid life-sign
+ * via signalExists but is NOT accepted as turn-owned evidence (PR2b-c).
+ */
+export function writeCompletionSignal(root, assignmentId, body) {
+    const p = getRuntimeSignalPath(root, assignmentId, body.status);
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    fs.writeFileSync(p, JSON.stringify(body), 'utf-8');
+}
+/** Parse ONE turn-keyed sentinel body, or undefined if absent / legacy
+ *  presence-only / non-JSON / missing correlation keys. Never throws. */
+function readOneCompletionSignal(root, assignmentId, status) {
+    let raw;
+    try {
+        raw = fs.readFileSync(getRuntimeSignalPath(root, assignmentId, status), 'utf-8').trim();
+    }
+    catch {
+        return undefined; // sentinel absent
+    }
+    if (!raw)
+        return undefined; // legacy presence-only (empty) marker
+    try {
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.turn_id === 'string' &&
+            typeof parsed.run_id === 'string' &&
+            typeof parsed.nonce === 'string' &&
+            (parsed.status === 'completed' || parsed.status === 'failed')) {
+            return {
+                turn_id: parsed.turn_id,
+                run_id: parsed.run_id,
+                nonce: parsed.nonce,
+                status: parsed.status,
+                at: typeof parsed.at === 'string' ? parsed.at : '',
+            };
+        }
+    }
+    catch { /* non-JSON legacy body */ }
+    return undefined;
+}
+/**
+ * Read BOTH turn-keyed completion sentinels for an attempt. This is the
+ * authoritative reader for the read-strict acceptance path: it surfaces a
+ * `completed`+`failed` contradiction so the caller can raise a conflict event
+ * and WITHHOLD an irreversible auto-stop (spec §13 R4), rather than silently
+ * collapsing to one. Legacy presence-only markers read as absent here.
+ */
+export function readCompletionSignals(root, assignmentId) {
+    const out = {};
+    const completed = readOneCompletionSignal(root, assignmentId, 'completed');
+    const failed = readOneCompletionSignal(root, assignmentId, 'failed');
+    if (completed)
+        out.completed = completed;
+    if (failed)
+        out.failed = failed;
+    return out;
+}
+/**
+ * Convenience single-body reader (`completed` preferred over `failed`). Returns
+ * undefined for absent / legacy presence-only / non-JSON / missing-keys.
+ * CALLERS THAT ACT IRREVERSIBLY must use {@link readCompletionSignals} instead
+ * so a completed+failed contradiction is not hidden (spec §13 R4).
+ */
+export function readCompletionSignal(root, assignmentId) {
+    const both = readCompletionSignals(root, assignmentId);
+    return both.completed ?? both.failed;
+}
 /**
  * can_c39f0961 — CP850 high-byte table (0x80–0xFF). Windows-native console
  * tools write redirected stdout/stderr in the OEM codepage (cp850 on western