brainclaw 1.16.0 → 1.18.0

package/README.md

@@ -44,7 +44,7 @@ It sits alongside your coding agents and gives them a shared state layer they ca
 | **Project memory**               | constraints, decisions, traps, handoffs, and layered instructions agents can resume from                                                                                                            |
 | **Coordination state**           | shared plans, file claims (dispatched work isolated in Git Worktrees), runtime notes, and board views for active work                                                                                                 |
 | **Agent-ready context**          | compact, prompt-sized context built from real workspace state instead of stale instructions                                                                                                         |
-| **Code Map**                     | a Tree-sitter symbol + import index (JS/TS, Python, PHP, Java) so agents ask "where is X / what should I read first" before editing, with related decisions/traps attached — `bclaw_code_find` / `bclaw_code_brief`, see [code map](docs/code-map.md) |
+| **Code Map**                     | a Tree-sitter symbol + import index (11 languages — JS/TS, Python, PHP, Java, Go, Rust, C#, Ruby, C, C++) so agents ask "where is X / what should I read first" before editing, with related decisions/traps attached — `bclaw_code_find` / `bclaw_code_brief`, see [code map](docs/code-map.md) |
 | **Native agent files**           | auto-writes `CLAUDE.md`, `AGENTS.md`, `GEMINI.md`, `.cursor/rules/`, `.windsurfrules`, and similar local guidance                                                                         |
 | **Multi-turn loops**             | review and ideation loops with structured phases, iteration semantics, and per-phase memory filters — see[loop engine](docs/concepts/loop-engine.md) and [ideation loop](docs/concepts/ideation-loop.md) |
 | **Machine AI surface discovery** | detects local coding agents plus desktop AI work surfaces such as ChatGPT Desktop and Gemini CLI                                                                                                    |
@@ -55,7 +55,7 @@ It sits alongside your coding agents and gives them a shared state layer they ca
 
 ## Code Map
 
-When an agent (or you) is about to edit unfamiliar code, the first question is *"where is this, and what should I read first?"* Code Map answers it without grepping: a per-project [Tree-sitter](https://tree-sitter.github.io/) index of the symbols each file defines (functions, classes, types, React components/hooks), what it imports/exports, and how files relate — across **JS / TS / TSX, Python, PHP, and Java**.
+When an agent (or you) is about to edit unfamiliar code, the first question is *"where is this, and what should I read first?"* Code Map answers it without grepping: a per-project [Tree-sitter](https://tree-sitter.github.io/) index of the symbols each file defines (functions, classes, types, React components/hooks), what it imports/exports, and how files relate — across **11 languages: JS / TS / TSX, Python, PHP, Java, Go, Rust, C#, Ruby, C, and C++**.
 
 ```bash
 brainclaw code-map find useAuth        # locate a symbol / component / hook by name
@@ -103,7 +103,7 @@ brainclaw is designed to sit alongside the coding agents teams are already using
 | Logo                                                                                                                                       | Agent                                                                          | Tier | What brainclaw configures                                               |
 | ------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------ | ---- | ----------------------------------------------------------------------- |
 | [![Claude Code](https://img.shields.io/badge/Claude_Code-111111?logo=anthropic&logoColor=white)](https://github.com/anthropics/claude-code)     | **[Claude Code](https://github.com/anthropics/claude-code)**                | A    | MCP + CLAUDE.md + hooks + auto-approve + permissions + /brainclaw skill |
-| [![Codex](https://img.shields.io/badge/Codex-111111?logo=openai&logoColor=white)](https://openai.com/codex/)                                    | **[Codex](https://openai.com/codex/)**                                      | A    | MCP + AGENTS.md + skills                                                |
+| [![Codex](https://img.shields.io/badge/Codex-111111?logo=openai&logoColor=white)](https://openai.com/codex/)                                    | **[Codex](https://openai.com/codex/)**                                      | A    | MCP + AGENTS.md + hooks + skills                                        |
 | [![Cursor](https://img.shields.io/badge/Cursor-1F2430?logo=cursor&logoColor=white)](https://cursor.com/en-US)                                   | **[Cursor](https://cursor.com/en-US)**                                      | A    | MCP (machine) + .cursor/rules/ + hooks + skills                         |
 | [![Windsurf](https://img.shields.io/badge/Windsurf-0B1220?logo=codeium&logoColor=white)](https://windsurf.com/)                                 | **[Windsurf](https://windsurf.com/)**                                       | A    | MCP (machine) + .windsurfrules + .windsurf/rules/                       |
 | [![Cline](https://img.shields.io/badge/Cline-0F766E?logoColor=white)](https://github.com/cline/cline)                                           | **[Cline](https://github.com/cline/cline)**                                 | A    | MCP + auto-approve + .clinerules/                                       |
@@ -256,8 +256,8 @@ bclaw_coordinate({
 });
 
 // 4. The reviewer's verdict is harvested from its LANE-RESULT.json and the loop
-//    auto-closes on approve — no manual advance needed for the approve path.
-//    (bclaw_loop remains available to drive the request_changes fix cycle by hand.)
+//    auto-closes on approve; request_changes re-dispatches the fix cycle
+//    autonomously. (bclaw_loop remains available to inspect or drive by hand.)
 bclaw_loop({ intent: "get", loop_id: "lop_abc" }); // inspect status any time
 ```
 
@@ -270,7 +270,7 @@ Brainclaw's Loop Engine moves beyond manual ping-pong by formalizing multi-turn
 
 Each loop maintains a structured lifecycle, explicit phases, iteration bounds, and per-phase memory filters, executed seamlessly via `bclaw_loop`.
 
-**Autonomous convergence (pln#628 Focus 4B):** a dispatched reviewer doesn't need to be driven by hand. It writes its verdict (`review_verdict: approve | request_changes`) into its `LANE-RESULT.json`; when the coordinator harvests the lane, brainclaw records the verdict on the loop and **auto-closes it on approve** — the review loop reaches `reviewer_green` with no human ping-pong. `request_changes` advances to the author phase (the automated fix→re-review cycle is a planned follow-up).
+**Autonomous convergence (pln#628 Focus 4B + pln#630):** a dispatched reviewer doesn't need to be driven by hand. It writes its verdict (`review_verdict: approve | request_changes`) into its `LANE-RESULT.json`; when the coordinator harvests the lane, brainclaw records the verdict on the loop and **auto-closes it on approve** — the review loop reaches `reviewer_green` with no human ping-pong. On `request_changes`, brainclaw **runs the fix→re-review cycle autonomously**: it bumps the round, retains the worktree, and re-dispatches — through an exactly-once turn-attempt state machine (immutable attempt records behind an atomic launch fence, on by default; kill-switch `BRAINCLAW_TURN_OWNED_REVIEW=0`) so a turn is never double-spawned, with a bounded round cap that lands on `blocked` instead of looping forever.
 
 ## Enterprise Ready: Mono-repo & Micro-services
 
@@ -319,7 +319,7 @@ Still sharp:
 
 1. **Same-checkout concurrent edits** — running two agents in the *same* working tree (no per-claim worktree) is still the wrong answer. Use the dispatch path (auto-worktree per claim) instead of raw concurrent CLI sessions.
 2. **Cross-machine sync** — federation across machines is on the roadmap, not in v1.x. Today brainclaw's store is local and one-machine-per-project.
-3. **Next.js / Turbopack dev server in a worktree** — the provisioned `node_modules` symlink points outside the worktree root, which `next dev` (Turbopack) rejects (build/tsc/vitest are fine). brainclaw warns; `npm install` in the worktree or smoke-test on the merged branch. A Turbopack-compatible dependency mode is a planned follow-up.
+3. **Next.js / Turbopack dev server in a worktree** — in the default `link` mode the provisioned `node_modules` symlink points outside the worktree root, which `next dev` (Turbopack) rejects (build/tsc/vitest are fine); brainclaw warns. Fix: opt into a Turbopack-compatible **per-worktree dependency mode** — set `worktree.deps_mode: install` (or `copy`) in config, or `BRAINCLAW_WORKTREE_DEPS_MODE=install`, so the worktree gets a real in-root `node_modules` (see [Multi-stack worktree](#multi-stack-worktree)).
 3. **Spawn-and-forget assumptions** — spawned workers don't always commit their work cleanly. The brief-ack file confirms the spawn started; in the worst case the coordinator harvests open changes.
 4. **Live state for hook-less agents** — supported hook-less file surfaces such as Cline, Windsurf, Continue, Antigravity/Gemini CLI, and Mistral Vibe can get live context via `.live.md` companions regenerated on session-end and handoff, not via real-time push.
 
@@ -349,12 +349,26 @@ Maven, Gradle, and Cargo are intentionally excluded — their dependency caches
 
 Build outputs like `dist` are **not** symlinked — they must be per-worktree to avoid EBUSY errors when other processes hold handles on the output directory.
 
-> **Next.js / Turbopack caveat.** The `node_modules` link is a symlink to the main worktree, i.e. it points **outside** the agent worktree's root. `tsc`, `vitest`, and production `build` follow it fine, but `next dev` (Turbopack) panics on a `node_modules` link outside the worktree root. brainclaw detects Next.js projects and surfaces a `symlink_warnings` note at worktree creation. Workaround for dev-server work: run `npm install` inside the worktree (optionally with `BRAINCLAW_NO_LINK_DEPS=1`), or smoke-test on the merged branch. A Turbopack-compatible per-worktree dependency mode is a planned follow-up.
+### Dependency provisioning mode (`deps_mode`)
+
+How a worktree gets its JS `node_modules` is controlled by `deps_mode` (default `link`):
+
+| Mode      | How `node_modules` is provisioned                                             | Turbopack / `next dev` | Cost |
+| --------- | ------------------------------------------------------------------------------- | ---------------------- | ---- |
+| `link`  | junction/symlink to the main tree (out-of-root)                                 | ❌ rejected            | instant, zero disk |
+| `install` | runs the detected package manager's install at the worktree root (real in-root) | ✅ works               | slower, may hit network/cache |
+| `copy`  | recursively copies `node_modules` from the main tree (real in-root)             | ✅ works               | disk-heavy, offline |
+| `none`  | provisions nothing (central validation / manual install)                        | n/a                    | instant |
+
+> **Next.js / Turbopack caveat.** In the default `link` mode the `node_modules` link points **outside** the worktree root. `tsc`, `vitest`, and production `build` follow it fine, but `next dev` (Turbopack) panics on it. brainclaw detects Next.js projects and surfaces a `symlink_warnings` note at worktree creation. For dev-server work, switch to `deps_mode: install` (or `copy`) — the worktree then gets a real in-root `node_modules` that Turbopack accepts. The package manager is auto-detected from the lockfile (`pnpm-lock.yaml` → pnpm, `yarn.lock` → yarn, `bun.lock*` → bun, else npm) or the `packageManager` field.
+
+Precedence: `BRAINCLAW_WORKTREE_DEPS_MODE` (env) > `BRAINCLAW_NO_LINK_DEPS=1` (→ `none`, backward compat) > `worktree.deps_mode` (config) > `link`. Install timeout: `BRAINCLAW_WORKTREE_INSTALL_TIMEOUT_MS` (default 10 min).
 
 Override detection in `.brainclaw/config.yaml`:
 
 ```yaml
 worktree:
+  deps_mode: install               # link (default) | install | copy | none
   shared_paths: [".cache"]        # additive to auto-detected
   exclude_shared: ["node_modules"] # opt-out a detected entry
 ```

package/dist/cli/register-review.js

@@ -103,9 +103,9 @@ export function registerReviewCommands(program) {
         .option('--dry-run', 'Preview without writing events/markers')
         .option('--worktree <path>', 'Explicit worktree path to scan (repeatable)', collect, [])
         .option('--json', 'Output as JSON')
-        .action((assignmentId, options) => {
+        .action(async (assignmentId, options) => {
         const globalOpts = program.opts();
-        runHarvestLane(assignmentId, { ...options, cwd: globalOpts.cwd });
+        await runHarvestLane(assignmentId, { ...options, cwd: globalOpts.cwd });
     });
     // --- prune-candidates ---
     program

package/dist/commands/code-map.js

@@ -15,7 +15,10 @@ function badgeLine(badge) {
     const detail = detailKeys.length
         ? ` (${detailKeys.map((k) => `${k}=${JSON.stringify(badge.details[k])}`).join(', ')})`
         : '';
-    return `Freshness: ${badge.status}${detail}`;
+    // pln#601 — lead with the coarse rollup (uniform across all read surfaces), then
+    // the precise status + details. `coarse` may be absent on legacy/hand-built badges.
+    const coarse = badge.coarse ? `${badge.coarse} · ` : '';
+    return `Freshness: ${coarse}${badge.status}${detail}`;
 }
 export async function runCodeMap(subcommand, args, options = {}) {
     const normalized = (subcommand ?? '').trim().toLowerCase();

package/dist/commands/codev.js

@@ -20,6 +20,7 @@ import path from 'node:path';
 import os from 'node:os';
 import { memoryExists, readProjectVision } from '../core/io.js';
 import { sendMessage, getThread, getThreadCount } from '../core/messaging.js';
+import { writePhaseArtifact } from '../core/codev-responses.js';
 import { resolveCurrentAgentName } from '../core/agent-registry.js';
 import { CODEV_PERSONAS, listPersonas } from '../core/codev-personas.js';
 import { buildContext } from '../core/context.js';
@@ -36,6 +37,36 @@ function toSlug(topic) {
 function sanitizeForPath(slug) {
     return slug.replace(/[<>:"/\\|?*]/g, '_');
 }
+/**
+ * Head of each phase body kept inline in the thread message (pln#627 Phase C).
+ * Comfortably covers the largest thread readback (`getThread(truncateText: 3000)`
+ * used to build the next phase's brief), so rerouting the full body to the
+ * artifact store leaves CoDev's iterative context byte-identical while the
+ * inbox message stays a few KB instead of hundreds.
+ */
+export const CODEV_INBOX_HEAD_CHARS = 4000;
+/**
+ * Persist a phase body to the artifact store and post a bounded head + pointer
+ * to the thread instead of the full text (pln#627 Phase C). Returns the
+ * sendMessage result. The full body is always readable at the returned relPath.
+ */
+export function postPhase(opts) {
+    const { agent, threadId, label, text, tags, cwd } = opts;
+    const artifact = writePhaseArtifact(threadId, label, text, cwd);
+    const body = text.length > CODEV_INBOX_HEAD_CHARS
+        ? `${text.slice(0, CODEV_INBOX_HEAD_CHARS)}\n\n[…full phase body (${artifact.charCount} chars) at ${artifact.relPath}]`
+        : text;
+    return sendMessage({
+        from: agent,
+        to: agent,
+        type: 'rfc',
+        text: body,
+        ref: artifact.relPath,
+        thread_id: threadId,
+        payload: { artifact_path: artifact.relPath, phase: label, char_count: artifact.charCount },
+        tags,
+    }, cwd);
+}
 const STOP_WORDS = new Set([
     'the', 'a', 'an', 'is', 'are', 'was', 'were', 'be', 'been', 'being',
     'have', 'has', 'had', 'do', 'does', 'did', 'will', 'would', 'could',
@@ -106,14 +137,14 @@ export function runCodev(topic, options = {}) {
         .map(t => `[${t.severity}] ${t.text}`);
     // ── Phase 1: Exposition ───────────────────────────────────
     const expositionText = buildExposition(topic, vision, relatedPlans, constraints, traps);
-    const opening = sendMessage({
-        from: agent,
-        to: agent,
-        type: 'rfc',
+    const opening = postPhase({
+        agent,
+        threadId,
+        label: 'exposition',
         text: expositionText,
-        thread_id: threadId,
         tags: ['codev', 'phase:exposition'],
-    }, cwd);
+        cwd,
+    });
     // ── Resolve spawn agents ──────────────────────────────────
     let spawnAgents = [];
     if (options.spawn) {
@@ -238,14 +269,14 @@ export function runCodev(topic, options = {}) {
         // Each spawned agent gets the exposition + their persona brief — that's enough context.
         const threadHistory = options.spawn ? [] : getThread(threadId, cwd, { truncateText: 2000 });
         const brief = buildConsultantBrief(persona, expositionText, 'clarification', threadHistory);
-        sendMessage({
-            from: agent,
-            to: agent,
-            type: 'rfc',
+        postPhase({
+            agent,
+            threadId,
+            label: `clarification_${persona.name}`,
             text: brief,
-            thread_id: threadId,
             tags: ['codev', 'phase:clarification', `persona:${persona.name}`],
-        }, cwd);
+            cwd,
+        });
         if (options.spawn && spawnAgents.length > 0) {
             const targetAgent = spawnAgents[i % spawnAgents.length];
             console.log(`  → ${persona.name} (clarification) → ${targetAgent.name}`);
@@ -267,28 +298,28 @@ export function runCodev(topic, options = {}) {
     const clarificationMessages = getThread(threadId, cwd, { truncateText: 3000 })
         .filter(m => m.tags?.includes('phase:clarification'));
     const contractText = buildContract(topic, clarificationMessages, decisions, constraints, traps);
-    sendMessage({
-        from: agent,
-        to: agent,
-        type: 'rfc',
+    postPhase({
+        agent,
+        threadId,
+        label: 'contract',
         text: contractText,
-        thread_id: threadId,
         tags: ['codev', 'phase:contract'],
-    }, cwd);
+        cwd,
+    });
     // ── Phase 4: Consultation briefs ──────────────────────────
     for (let i = 0; i < personas.length; i++) {
         const persona = personas[i];
         // For spawned agents, include only the contract (not full history) to avoid message explosion
         const threadHistory = options.spawn ? [] : getThread(threadId, cwd, { truncateText: 2000 });
         const brief = buildConsultantBrief(persona, expositionText, 'consultation', threadHistory);
-        sendMessage({
-            from: agent,
-            to: agent,
-            type: 'rfc',
+        postPhase({
+            agent,
+            threadId,
+            label: `consultation_${persona.name}`,
             text: brief,
-            thread_id: threadId,
             tags: ['codev', 'phase:consultation', `persona:${persona.name}`],
-        }, cwd);
+            cwd,
+        });
         if (options.spawn && spawnAgents.length > 0) {
             const targetAgent = spawnAgents[i % spawnAgents.length];
             console.log(`  → ${persona.name} (consultation) → ${targetAgent.name}`);
@@ -310,14 +341,14 @@ export function runCodev(topic, options = {}) {
     const consultationMessages = getThread(threadId, cwd, { truncateText: 3000 })
         .filter(m => m.tags?.includes('phase:consultation'));
     const synthesisText = buildSynthesis(topic, consultationMessages);
-    sendMessage({
-        from: agent,
-        to: agent,
-        type: 'rfc',
+    postPhase({
+        agent,
+        threadId,
+        label: 'synthesis',
         text: synthesisText,
-        thread_id: threadId,
         tags: ['codev', 'phase:synthesis'],
-    }, cwd);
+        cwd,
+    });
     // ── Output ────────────────────────────────────────────────
     if (options.json) {
         console.log(JSON.stringify({

package/dist/commands/doctor.js

@@ -497,6 +497,7 @@ export function runDispatchHealthCheck(options = {}) {
     const inferred_completed = [];
     const health_check_unverified = [];
     const inferred_failed = [];
+    const inferred_cancelled = [];
     let no_op_open = 0;
     for (const result of results) {
         const run = loadAgentRun(result.run_id, options.cwd);
@@ -525,6 +526,9 @@ export function runDispatchHealthCheck(options = {}) {
             case 'inferred_failed':
                 inferred_failed.push(summary);
                 break;
+            case 'inferred_cancelled':
+                inferred_cancelled.push(summary);
+                break;
             case 'no_op':
                 no_op_open += 1;
                 break;
@@ -536,6 +540,7 @@ export function runDispatchHealthCheck(options = {}) {
         inferred_completed,
         health_check_unverified,
         inferred_failed,
+        inferred_cancelled,
         no_op_open,
         exit_code: inferred_failed.length > 0 ? 1 : 0,
     };
@@ -565,7 +570,15 @@ function renderDispatchHealthHumanReport(report) {
         }
         lines.push('');
     }
-    if (report.inferred_failed.length === 0 && report.inferred_completed.length === 0 && report.health_check_unverified.length === 0) {
+    if (report.inferred_cancelled.length > 0) {
+        lines.push(`⊘ ${report.inferred_cancelled.length} turn-owned run(s) cancelled on lease expiry (reserved, never launched):`);
+        for (const r of report.inferred_cancelled) {
+            lines.push(`  - ${r.run_id} ${r.agent} (${r.scope}) — ${r.reason}`);
+        }
+        lines.push('');
+    }
+    if (report.inferred_failed.length === 0 && report.inferred_completed.length === 0
+        && report.health_check_unverified.length === 0 && report.inferred_cancelled.length === 0) {
         lines.push(`✔ No dispatch issues detected (${report.no_op_open} open run(s) within grace window or already healthy).`);
     }
     else {

package/dist/commands/harvest.js

@@ -23,6 +23,80 @@ import { loadClaim, releaseClaimsCascade, logCascadeReleaseResult } from '../cor
 import { getCapabilityProfile, dispatchCanCommit } from '../core/agent-capability.js';
 import { commitWorktreeOnBehalf, worktreesBaseDir, resolveGitToplevel } from '../core/worktree.js';
 import { closeReviewLoopFromLaneResult } from '../core/review-loop-close.js';
+import { closeIdeationLoopFromLaneResult } from '../core/ideation-loop-close.js';
+import { dispatchReviewLoopTurn, turnOwnedReviewEnabled } from '../core/review-loop-turn-dispatch.js';
+import { reconcileTurn } from '../core/loops/reconcile-turn.js';
+import { findReservationByAssignmentId } from '../core/loops/attempt-reservation.js';
+import { readCompletionSignals } from '../core/runtime-signals.js';
+/**
+ * pln#630 PR3a — finalize a TURN-OWNED review lane via the exactly-once `reconcileTurn`
+ * instead of the legacy `closeReviewLoopFromLaneResult`. Returns `undefined` for a legacy
+ * (non-reserved) lane so the caller runs the unchanged legacy path — this is the
+ * exactly-one-finalizer discriminator: a lane is turn-owned iff a reservation OWNS its
+ * assignment_id (only the turn-owned dispatch writes a reservation file).
+ *
+ * Evidence sourcing (the load-bearing subtlety): a real reviewer's LANE-RESULT.json is
+ * KEYLESS — the review brief never asks the worker to echo turn_id/run_id/nonce — so
+ * read-strict `reconcileTurn` (which matches lane.{turn_id,run_id,nonce} against the
+ * attempt) would REJECT it. We source the keys authoritatively: turn_id + run_id are
+ * deterministic from the reservation, and the NONCE — the non-derivable proof that THIS
+ * launch generation actually ran — comes from the coordinator's completion SENTINEL
+ * (written mechanically by the ack-wrapper with the launch-grant token). A caller/test
+ * that already supplies keyed lanes is honored (lane.* wins); a stale generation's
+ * sentinel carries the old token → still rejected, preserving the anti-stale guarantee.
+ */
+/**
+ * The turn-owned FINALIZATION discriminator (pln#630, review Finding 1). A lane finalizes via
+ * the exactly-once reconcileTurn ONLY if a committed reservation OWNS it AND turn-keyed evidence
+ * (the nonce) is available — from the lane or the coordinator's completion SENTINEL. Without the
+ * nonce, reconcileTurn's read-strict gate can NEVER converge: this is reachable in production
+ * when a turn-owned dispatch WON the fence but did not ack-wrap-spawn (inbox_only / IDE-only
+ * reviewer, command_ready_manual, capacity cap, BRAINCLAW_NO_SPAWN, worktree-creation failure) —
+ * it minted a reservation but no sentinel will ever be written. Returning undefined there routes
+ * the lane to the LEGACY presence-based closer so the loop still converges instead of stalling
+ * forever. This is SAFE: the exactly-once SPAWN guarantee is enforced at DISPATCH by the launch
+ * fence (already run), so using legacy FINALIZATION for a sentinel-less lane reintroduces no
+ * double-spawn; and a sentinel that lands after a legacy close makes a later reconcile a
+ * terminal-loop idempotent no-op.
+ */
+function turnOwnedLaneEvidence(lane, cwd) {
+    const reservation = findReservationByAssignmentId(lane.assignment_id, cwd);
+    if (!reservation)
+        return undefined; // legacy lane (no reservation)
+    const nonce = lane.nonce ?? readCompletionSignals(cwd, reservation.child_ids.assignment_id).completed?.nonce;
+    if (!nonce)
+        return undefined; // reservation but NO turn-keyed evidence → legacy finalization
+    return { reservation, nonce };
+}
+function reconcileTurnOwnedReviewLane(lane, cwd) {
+    const ev = turnOwnedLaneEvidence(lane, cwd);
+    if (!ev)
+        return undefined; // legacy lane OR no turn-keyed evidence — caller runs the legacy path
+    const { reservation, nonce } = ev;
+    const enrichedLane = {
+        ...lane,
+        turn_id: lane.turn_id ?? reservation.turn_id,
+        run_id: lane.run_id ?? reservation.child_ids.run_id,
+        nonce,
+    };
+    const result = reconcileTurn({ turn_id: reservation.turn_id, lane: enrichedLane, cwd });
+    return { reservation, result };
+}
+/**
+ * Map a `reconcileTurn` result onto the `ReviewLoopCloseResult` shape harvest records for
+ * observability (entry.review_loop / CLI). No keep_claim / next_turn: the request_changes
+ * turn-owned re-dispatch (fix cycle) is pln#630 PR3b — deferred and non-corrupting (the
+ * loop stays open awaiting its next turn, identical to the legacy asymmetric path).
+ */
+function reconcileToReviewLoopResult(reservation, rr, lane) {
+    return {
+        loop_id: reservation.loop_id,
+        verdict: lane.review_verdict === 'request_changes' ? 'request_changes' : 'approve',
+        action: rr.auto_closed ? 'closed' : rr.reconciled ? 'advanced' : 'noop',
+        reason: rr.reason,
+        loop_status: rr.loop_status,
+    };
+}
 /**
  * Auto-detect all worktree directories under the brainclaw-managed base dir.
  * Returns subdirectories that exist on disk (may or may not have an inbox).
@@ -278,10 +352,27 @@ export function harvestLaneResults(options = {}) {
         // (a terminal loop is a no-op; a stuck approve is resumed), so firing it here
         // AND in integrateLaneResults is safe — and it runs BEFORE the harvested
         // marker short-circuits below, so a re-harvest still resumes a stuck loop.
+        // PR2: cycleOnRequestChanges=false — the report path only closes on approve;
+        // it must NOT advance a request_changes cycle it cannot follow through on
+        // (no re-dispatch, no claim retention). `harvest --integrate` owns the cycle.
         try {
             const laneAssignment = loadAssignment(lane.assignment_id, cwd);
-            if (laneAssignment)
-                closeReviewLoopFromLaneResult(laneAssignment, lane, agent, cwd);
+            if (laneAssignment) {
+                // pln#630 PR3a — a TURN-OWNED review lane (reservation + turn-keyed evidence) is finalized
+                // ONLY by reconcileTurn on the `--integrate` path (which owns claim/worktree teardown). The
+                // report path must NOT pre-empt it with a legacy close (which would terminalize the loop and
+                // strand the turn-owned run). So skip the legacy review-close for such a lane. Kill-switch
+                // (=0), a legacy lane (no reservation), OR a reservation WITHOUT evidence (review Finding 1:
+                // an inbox_only/non-ack-wrapped dispatch that never wrote a sentinel) → false → the lane
+                // takes the unchanged legacy close so it still converges. Ideation stays legacy (review-only).
+                const laneIsTurnOwned = turnOwnedReviewEnabled() && !!turnOwnedLaneEvidence(lane, cwd);
+                if (!laneIsTurnOwned) {
+                    closeReviewLoopFromLaneResult(laneAssignment, lane, agent, cwd, { cycleOnRequestChanges: false });
+                }
+                // pln#521 P2-bis — the ideation analog: a critic lane records its critique +
+                // advances the ideation loop. Returns undefined for non-ideate scopes (no-op here).
+                closeIdeationLoopFromLaneResult(laneAssignment, lane, agent, cwd);
+            }
         }
         catch { /* never block harvest on loop-close */ }
         const marker = laneHarvestedMarkerPath(cwd, lane.assignment_id);
@@ -391,7 +482,7 @@ function forceCompleteAssignment(assignmentId, artifacts, statusReason, actor, c
 export function integrateLaneResults(options = {}) {
     const cwd = options.cwd ?? process.cwd();
     const actor = options.agent ?? 'coordinator';
-    const result = { integrated: [], skipped: [], errors: [] };
+    const result = { integrated: [], skipped: [], errors: [], next_turns: [] };
     const worktreePaths = resolveLaneScanPaths(options, cwd);
     for (const worktreePath of worktreePaths) {
         const file = getLaneResultPath(worktreePath);
@@ -459,26 +550,122 @@ export function integrateLaneResults(options = {}) {
                     ...entry.files_changed.slice(0, 50).map((f) => ({ type: 'file', ref: f })),
                 ];
                 entry.assignment_completed = forceCompleteAssignment(lane.assignment_id, artifacts, `pln#534 on-behalf integration: ${lane.summary.slice(0, 120)}`, actor, cwd);
-                // trp#928 — use the cascade helper (was releaseClaimWithCascade — same
-                // logic for the last-claim rule but the cascade wrapper LOGS per-claim,
-                // so a silent ownership failure is observable in the runtime event log
-                // rather than only in this in-memory `reasons` string).
-                const cascade = releaseClaimsCascade([assignment.claim_id], { cwd, planStatus: 'done' });
-                logCascadeReleaseResult({ actor, trigger: 'harvest_integrate', assignment_id: lane.assignment_id, claim_id: assignment.claim_id, cascade, cwd });
-                const claimEntry = cascade.entries[0];
-                entry.claim_released = claimEntry?.released === true;
-                if (claimEntry && !claimEntry.released) {
-                    reasons.push(`claim release ${claimEntry.reason}${claimEntry.error ? `: ${claimEntry.error}` : ''}`);
+                // pln#628 Focus 4B — map this lane onto its review loop BEFORE deciding
+                // teardown: PR1 records the verdict + advances (auto-close on approve);
+                // PR2 continues the fix cycle on request_changes (bump round, emit a
+                // next_turn) unless the iteration cap is hit. This is the --integrate
+                // path, so it MAY cycle (it can re-dispatch AND retain the claim). No-op
+                // for non-review lanes / lanes without a verdict; never throws.
+                // pln#521 P2-bis — the ideation analog (record critique + advance the ideation
+                // loop). Turn-owned is REVIEW-ONLY (pln#630), so ideation always uses the legacy
+                // path. It is independent of the review-loop close (a lane's scope is review-loop
+                // XOR ideate-loop), so it runs once here regardless of the branch below.
+                const ideationClose = closeIdeationLoopFromLaneResult(assignment, lane, actor, cwd);
+                if (ideationClose) {
+                    reasons.push(`ideate-loop ${ideationClose.loop_id}: ${ideationClose.action} — ${ideationClose.reason}`);
+                }
+                // pln#630 PR3a — a TURN-OWNED review lane finalizes via the exactly-once
+                // reconcileTurn, which REPLACES the legacy closer + teardown gate for this lane
+                // (exactly-one finalizer per lane). Kill-switch (=0), a legacy (non-reserved) lane, OR a
+                // reservation with NO turn-keyed evidence (review Finding 1) → `turnOwned` is undefined
+                // and the unchanged legacy `else` block runs so the loop still converges.
+                const turnOwned = turnOwnedReviewEnabled()
+                    ? reconcileTurnOwnedReviewLane(lane, cwd)
+                    : undefined;
+                if (turnOwned) {
+                    const { reservation, result: rr } = turnOwned;
+                    entry.review_loop = reconcileToReviewLoopResult(reservation, rr, lane);
+                    reasons.push(`turn-owned reconcile ${reservation.loop_id}: ${entry.review_loop.action} — ${rr.reason}${rr.conflict ? ' [CONFLICT — held]' : ''}`);
+                    // pln#630 PR3b — a symmetric request_changes bumped the round + retained the claim
+                    // and handed back the next fix-cycle turn. Push it exactly like the legacy path so
+                    // the existing async re-dispatch loop spawns round N+1 into the reused worktree. The
+                    // fresh iteration means deriveTurnId mints a new turn_id → the launch fence admits
+                    // exactly one spawn (a stale re-emit of the same turn_id is denied).
+                    if (rr.next_turn) {
+                        result.next_turns.push({ loop_id: reservation.loop_id, ...rr.next_turn });
+                    }
+                    // Claim/run/assignment settling is OWNED by reconcileTurn, so we do NOT run the
+                    // legacy teardown gate — just reflect the resulting claim state. Settlement
+                    // semantics (reconcile-turn.ts, review #1): an ACCEPTED lane — approve OR
+                    // request_changes, both settle the slot 'done' — completes the assignment AND
+                    // releases the claim; only a REJECTED/superseded lane (evidence mismatch/absent,
+                    // §13 R4 conflict) leaves the claim intact for a retry. No next_turns push: the
+                    // request_changes fix-cycle re-dispatch — AND re-establishing the claim/worktree
+                    // that the release above implies — is pln#630 PR3b (deferred; the loop stays open
+                    // awaiting its next turn, so nothing is corrupted, only not-yet-autonomous).
+                    try {
+                        entry.claim_released = loadClaim(assignment.claim_id, cwd)?.status === 'released';
+                    }
+                    catch {
+                        entry.claim_released = false;
+                    }
+                    // A turn-owned lane that reached here HAS turn-keyed evidence (turnOwnedLaneEvidence
+                    // gated on a present nonce — the missing-sentinel/non-spawn case already fell back to
+                    // legacy, review Finding 1). So a non-convergence here means the evidence MISMATCHED
+                    // the live attempt (stale/superseded generation) — which must NOT fall back to legacy
+                    // (that would converge on evidence for a DIFFERENT generation). Emit an observable
+                    // event so an operator/doctor sees the (correctly) withheld convergence. (An R4
+                    // conflict already journals its own event, so it is excluded here.)
+                    if (!rr.reconciled && !rr.conflict && lane.review_verdict) {
+                        try {
+                            createRuntimeEvent({
+                                agent: actor,
+                                event_type: 'run_blocked',
+                                text: `harvest: turn-owned review lane ${lane.assignment_id} carried verdict '${lane.review_verdict}' but reconcile did not converge (${rr.reason}); loop ${reservation.loop_id} left OPEN — needs the completion sentinel or a manual turn`,
+                                tags: ['harvest', 'reconcile', 'turn-owned', 'unconverged'],
+                                assignment_id: lane.assignment_id,
+                                run_id: reservation.child_ids.run_id,
+                                status_reason: 'turn_owned_evidence_unaccepted',
+                            }, cwd);
+                        }
+                        catch { /* observability best-effort */ }
+                    }
                 }
-                // pln#628 Focus 4B — if this lane is a review-loop turn carrying a
-                // verdict, map it onto the loop: record the verdict artifact + advance,
-                // which auto-closes the loop on reviewer_green (approve) without a human
-                // driving complete_turn/advance by hand. No-op for non-review lanes or
-                // lanes without a verdict; never throws (harvest is not blocked on it).
-                const loopClose = closeReviewLoopFromLaneResult(assignment, lane, actor, cwd);
-                if (loopClose) {
-                    entry.review_loop = loopClose;
-                    reasons.push(`review-loop ${loopClose.loop_id}: ${loopClose.action} — ${loopClose.reason}`);
+                else {
+                    const loopClose = closeReviewLoopFromLaneResult(assignment, lane, actor, cwd);
+                    if (loopClose) {
+                        entry.review_loop = loopClose;
+                        reasons.push(`review-loop ${loopClose.loop_id}: ${loopClose.action} — ${loopClose.reason}`);
+                        if (loopClose.next_turn) {
+                            result.next_turns.push({ loop_id: loopClose.loop_id, ...loopClose.next_turn });
+                        }
+                    }
+                    // PR2 claim-teardown gate. Skip the release when either:
+                    //  (a) keep_claim — the symmetric fix cycle reuses the claim/worktree for
+                    //      the re-dispatched turn (commits accumulate on one branch); or
+                    //  (b) Codex review P0 — an idempotent re-harvest of an OLD lane whose
+                    //      loop is still OPEN returns a `noop` (the reviewer slot is now bound
+                    //      to a NEWER assignment under an active cycle). Releasing here would
+                    //      tear down the reused claim/worktree out from under the live turn
+                    //      and strand the fix cycle. The loop machinery owns the lifecycle
+                    //      while it is open; only a terminal close (approve/blocked, action
+                    //      'closed') or an asymmetric hand-off ('advanced' without keep_claim)
+                    //      releases here. A `noop` on a TERMINAL loop still releases (safe —
+                    //      the closing pass already released, so this is a no-op).
+                    const loopStillOpen = loopClose?.loop_status !== undefined &&
+                        !['completed', 'cancelled', 'blocked'].includes(loopClose.loop_status);
+                    const keepClaimAlive = loopClose?.keep_claim === true || (loopClose?.action === 'noop' && loopStillOpen);
+                    if (keepClaimAlive) {
+                        // The next_turn spawn (async) is awaited by runHarvestLane. The
+                        // assignment for THIS turn is still completed above.
+                        entry.claim_released = false;
+                        reasons.push(loopClose?.keep_claim
+                            ? 'claim kept alive for review fix-cycle re-dispatch (PR2)'
+                            : 'claim left intact — idempotent re-harvest on an active review loop (no strand)');
+                    }
+                    else {
+                        // trp#928 — use the cascade helper (was releaseClaimWithCascade — same
+                        // logic for the last-claim rule but the cascade wrapper LOGS per-claim,
+                        // so a silent ownership failure is observable in the runtime event log
+                        // rather than only in this in-memory `reasons` string).
+                        const cascade = releaseClaimsCascade([assignment.claim_id], { cwd, planStatus: 'done' });
+                        logCascadeReleaseResult({ actor, trigger: 'harvest_integrate', assignment_id: lane.assignment_id, claim_id: assignment.claim_id, cascade, cwd });
+                        const claimEntry = cascade.entries[0];
+                        entry.claim_released = claimEntry?.released === true;
+                        if (claimEntry && !claimEntry.released) {
+                            reasons.push(`claim release ${claimEntry.reason}${claimEntry.error ? `: ${claimEntry.error}` : ''}`);
+                        }
+                    }
                 }
             }
             else {
@@ -697,7 +884,7 @@ export function harvestOrphaned(options) {
     }
     return report;
 }
-export function runHarvestLane(assignmentId, options = {}) {
+export async function runHarvestLane(assignmentId, options = {}) {
     const cwd = options.cwd ?? process.cwd();
     if (!memoryExists(cwd)) {
         console.error('Error: .brainclaw/ not found. Run `brainclaw init` first.');
@@ -759,8 +946,30 @@ export function runHarvestLane(assignmentId, options = {}) {
             dryRun: options.dryRun,
             cwd,
         });
+        // pln#628 Focus 4B PR2 — spawn the review fix-cycle turns the sync integrate
+        // pass emitted. Re-dispatches the SAME reviewer into the SAME (kept) worktree
+        // to apply the requested changes + re-review. Dry-run only reports them.
+        const dispatchedTurns = [];
+        if (!options.dryRun) {
+            for (const nt of integ.next_turns) {
+                const dispatched = await dispatchReviewLoopTurn({
+                    loopId: nt.loop_id,
+                    slot: { slot_id: nt.slot_id, role: nt.role, agent: nt.agent, agent_id: nt.agent_id },
+                    phase: nt.phase,
+                    task: nt.task,
+                    dispatcherAgent: options.agent ?? 'coordinator',
+                    cwd,
+                    // NO worktreeBaseRef: reuse the kept worktree so the fixes accumulate;
+                    // pinning a ref would reset the branch and wipe prior-round commits.
+                });
+                dispatchedTurns.push({
+                    loop_id: nt.loop_id, agent: nt.agent, iteration: nt.iteration,
+                    execution_status: dispatched.execution_status, error: dispatched.error,
+                });
+            }
+        }
         if (options.json) {
-            console.log(JSON.stringify(integ, null, 2));
+            console.log(JSON.stringify({ ...integ, dispatched_turns: dispatchedTurns }, null, 2));
             return;
         }
         const dry = options.dryRun ? ' (dry-run)' : '';
@@ -787,7 +996,14 @@ export function runHarvestLane(assignmentId, options = {}) {
         }
         for (const err of integ.errors)
             console.error(`  ✗ ${err}`);
-        console.log(`\n✔ Lane integrate complete${dry}: ${integ.integrated.length} integrated, ${integ.errors.length} error(s).`);
+        for (const dt of dispatchedTurns) {
+            const status = dt.error ? `error: ${dt.error}` : (dt.execution_status ?? 'unknown');
+            console.log(`  ↻ Fix-cycle re-dispatch [${dt.loop_id}] round ${dt.iteration} → ${dt.agent} (${status})`);
+        }
+        if (options.dryRun && integ.next_turns.length > 0) {
+            console.log(`  (dry-run) ${integ.next_turns.length} fix-cycle turn(s) would be re-dispatched.`);
+        }
+        console.log(`\n✔ Lane integrate complete${dry}: ${integ.integrated.length} integrated, ${dispatchedTurns.length} re-dispatched, ${integ.errors.length} error(s).`);
         return;
     }
     const result = harvestLaneResults({