brainclaw 1.16.0 → 1.17.0

package/README.md

@@ -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/                                       |
@@ -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/harvest.js

@@ -23,6 +23,7 @@ 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 { dispatchReviewLoopTurn } from '../core/review-loop-turn-dispatch.js';
 /**
  * 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 +279,13 @@ 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);
+                closeReviewLoopFromLaneResult(laneAssignment, lane, agent, cwd, { cycleOnRequestChanges: false });
         }
         catch { /* never block harvest on loop-close */ }
         const marker = laneHarvestedMarkerPath(cwd, lane.assignment_id);
@@ -391,7 +395,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 +463,55 @@ 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 — 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).
+                // 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.
                 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 +730,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 +792,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 +842,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({

package/dist/core/agent-capability.js

@@ -159,10 +159,15 @@ const PROFILES = {
     // blocker.
     codex: {
         name: 'codex', category: 'code-agent', workflowModel: 'task-based',
-        hasMcp: true, hasHooks: false, hasAutoApprove: false, hasSkills: true, hasRules: true,
+        // hooks: Codex gained a native lifecycle hook surface (SessionStart /
+        // UserPromptSubmit / Stop / PreToolUse / … via .codex/hooks.json or [hooks]
+        // in config.toml; developers.openai.com/codex/hooks, verified 2026-07 —
+        // trp_fe75dafc). brainclaw writes .codex/hooks.json (ensureCodexHooks),
+        // giving Codex the same session-lifecycle wiring as Claude Code.
+        hasMcp: true, hasHooks: true, hasAutoApprove: false, hasSkills: true, hasRules: true,
         instructionFile: 'AGENTS.md', sharedInstructionFile: true, mcpConfigScope: 'machine', templateTier: 'A',
         role_capabilities: ['execute', 'review'],
-        runtime: { mcp_direct: true, hooks: false, canBeSpawnedCli: true, canSpawnOtherCli: false, inbox: true },
+        runtime: { mcp_direct: true, hooks: true, canBeSpawnedCli: true, canSpawnOtherCli: false, inbox: true },
         max_concurrent_tasks: 5,
         // pln#475: prefer stdin_pipe to avoid Windows cmd.exe arg-parsing breaking
         // long prompts. codex.cmd resolves through cmd shell, where embedded

package/dist/core/agent-files.js

@@ -314,6 +314,7 @@ const ANTIGRAVITY_MCP_RELATIVE_PATH = '.gemini/antigravity/mcp_config.json';
 const ANTIGRAVITY_HOOKS_RELATIVE_PATH = '.gemini/antigravity/hooks.json';
 const CURSOR_HOOKS_RELATIVE_PATH = '.cursor/hooks.json';
 const COPILOT_HOOKS_RELATIVE_PATH = '.github/copilot/hooks.json';
+const CODEX_HOOKS_RELATIVE_PATH = '.codex/hooks.json';
 const OPENCLAW_MCP_RELATIVE_PATH = '.openclaw/mcp.json';
 const VSCODE_EXTENSIONS_RELATIVE_PATH = '.vscode/extensions.json';
 const UNIVERSAL_SKILL_RELATIVE_PATH = '.agents/skills/brainclaw/SKILL.md';
@@ -1686,7 +1687,10 @@ export function ensureCodexMcpConfig(homeDir, env = process.env) {
         '\n[mcp_servers.brainclaw]',
         `command = "${normalizedCommand}"`,
         `args = [${normalizedArgs.map(a => `"${a}"`).join(', ')}]`,
-        'startup_timeout_ms = 20000',
+        // Codex renamed this field to `_sec` (developers.openai.com/codex/extend/mcp;
+        // the docs note "uses _sec, not _ms"). The old `startup_timeout_ms` is an
+        // unrecognized key → Codex silently falls back to its default startup timeout.
+        'startup_timeout_sec = 20',
         '',
         '[mcp_servers.brainclaw.env]',
         'BRAINCLAW_AGENT = "codex"',
@@ -2115,6 +2119,53 @@ export function ensureAntigravityHooks(homeDir) {
         relativePath: ANTIGRAVITY_HOOKS_RELATIVE_PATH,
     };
 }
+/**
+ * Writes `.codex/hooks.json` — Codex CLI's native lifecycle hooks config
+ * (project scope). Codex gained a full hook surface (developers.openai.com/codex/hooks,
+ * verified 2026-07 — trp_fe75dafc); this wires brainclaw's session lifecycle to it,
+ * mirroring the Claude Code / Antigravity hook writers.
+ *
+ * Events (PascalCase, per the Codex schema): `SessionStart` loads shared context,
+ * `UserPromptSubmit` surfaces the context diff, `Stop` runs session-end cleanup.
+ * File shape: `{ "hooks": { "<Event>": [ { "matcher": "", "hooks": [ { "type": "command", "command": "…" } ] } ] } }`
+ * — the top-level `hooks` wrapper + per-entry `hooks` array (`matcher: ""` = match all).
+ *
+ * brainclaw OWNS these three event arrays (overwrite, not merge) — the same
+ * contract as the Cursor / Antigravity `hooks.json` writers. This is
+ * unconditionally idempotent regardless of how the CLI path resolves, with no
+ * cross-upgrade pile-up. It deliberately does NOT use command-recognition to
+ * preserve user entries within these events: recognizing brainclaw's own hook
+ * path-independently requires matching bare CLI subcommands, which over-matches
+ * legitimate user hooks that merely pass `session-start`/etc. as an argument
+ * (Codex review of #94, round 2). Other events the user defines are untouched
+ * (only these three keys are set).
+ */
+export function ensureCodexHooks(cwd) {
+    const filePath = path.join(cwd, CODEX_HOOKS_RELATIVE_PATH);
+    const existing = readJsonObject(filePath);
+    if (existing === undefined) {
+        return skippedAutoConfigResult('rule', 'Codex session hooks', filePath, CODEX_HOOKS_RELATIVE_PATH);
+    }
+    const hooks = isJsonObject(existing.hooks) ? { ...existing.hooks } : {};
+    const sessionStartCmd = buildHookCommand(['session-start', '--include-context']);
+    const contextDiffCmd = buildHookCommand(['context-diff']);
+    const sessionEndCmd = buildHookCommand(['session-end', '--auto-release', '--reflect', '--reflect-handoff', '--dispatch-review']);
+    hooks.SessionStart = [buildCommandHookEntry(sessionStartCmd)];
+    hooks.UserPromptSubmit = [buildCommandHookEntry(contextDiffCmd)];
+    hooks.Stop = [buildCommandHookEntry(sessionEndCmd)];
+    const { created, updated } = writeJsonFileIfChanged(filePath, {
+        ...existing,
+        hooks,
+    });
+    return {
+        kind: 'rule',
+        label: 'Codex session hooks',
+        created,
+        updated,
+        filePath,
+        relativePath: CODEX_HOOKS_RELATIVE_PATH,
+    };
+}
 /**
  * Writes `.github/copilot/hooks.json` — GitHub Copilot's native hooks config.
  * Events: sessionStart, userPromptSubmitted, sessionEnd (camelCase).
@@ -2284,7 +2335,7 @@ export const AGENT_WIRING_REGISTRY = {
             writeProtocolSkills,
         ],
         userWriters: [(ctx) => ensureCodexMcpConfig(ctx.homeDir, ctx.env)],
-        hookWriters: [],
+        hookWriters: [(ctx) => ensureCodexHooks(ctx.cwd)],
     },
     continue: {
         workspaceWriters: [(ctx) => ensureContinueMcpConfig(ctx.cwd)],

package/dist/core/agent-integrations.js

@@ -61,6 +61,7 @@ const DEFAULT_SURFACES = {
     'codex': [
         { kind: 'instructions', location: 'workspace', path: 'AGENTS.md' },
         { kind: 'mcp', location: 'machine', path: '.codex/config.toml' },
+        { kind: 'hook', location: 'workspace', path: '.codex/hooks.json' },
         { kind: 'skill', location: 'workspace', path: '.agents/skills/brainclaw/SKILL.md' },
     ],
     'opencode': [

package/dist/core/dispatcher.js

@@ -279,13 +279,39 @@ export function buildProtocolSection(options) {
     }
     if (options?.worktreePath) {
         parts.push(`Worktree: ${options.worktreePath}`);
-        // pln#523: tell the worker how dependencies are provisioned so it does not
-        // stall trying to install them. node_modules (and per-package node_modules in
-        // monorepos) are junction-linked from the main repo — run builds/typecheck
-        // directly. If they are missing, do NOT `npm install` in the worktree: check
-        // `.brainclaw-worktree.json` → `symlink_warnings` (a link may have failed,
-        // e.g. cross-volume) and validate the build centrally with the coordinator.
-        parts.push('Dependencies: node_modules is linked from the main repo (incl. monorepo per-package). Build/typecheck directly; if deps are missing, do NOT npm install here — see .brainclaw-worktree.json symlink_warnings and validate centrally.');
+        // pln#523 / trp_37b05a15: tell the worker how dependencies are provisioned so
+        // it does not stall trying to (re)install them. The authoritative record is
+        // the worktree's `.brainclaw-worktree.json` → `deps_mode` (absent ⇒ `link`).
+        //   - link (default): node_modules (incl. monorepo per-package) is
+        //     junction-linked from the main repo — build/typecheck directly; do NOT
+        //     `npm install`. An out-of-root symlink, so `next dev`/Turbopack rejects
+        //     it (build/tsc/vitest are fine).
+        //   - install/copy: node_modules is a REAL in-root directory — everything,
+        //     including a dev server, works directly; no reinstall needed.
+        //   - none: no deps provisioned — run the project's install first.
+        let depsMode = 'link';
+        let depsProvisioned;
+        try {
+            const sidecar = JSON.parse(fs.readFileSync(path.join(options.worktreePath, '.brainclaw-worktree.json'), 'utf-8'));
+            if (sidecar.deps_mode)
+                depsMode = sidecar.deps_mode;
+            depsProvisioned = sidecar.deps_provisioned;
+        }
+        catch { /* sidecar absent/unreadable — assume the default `link` */ }
+        if ((depsMode === 'install' || depsMode === 'copy') && depsProvisioned === false) {
+            // Codex review P1: provisioning was ATTEMPTED but FAILED (best-effort, non-fatal).
+            // Do not claim node_modules is usable — tell the worker to install it.
+            parts.push(`Dependencies: in-root provisioning was attempted (deps_mode=${depsMode}) but FAILED — node_modules may be missing or incomplete. Run the project's install (npm/pnpm/yarn/bun) in the worktree before building; see .brainclaw-worktree.json symlink_warnings for the failure.`);
+        }
+        else if (depsMode === 'install' || depsMode === 'copy') {
+            parts.push(`Dependencies: node_modules is a real in-root directory (deps_mode=${depsMode}) — build, typecheck, and dev server all work directly; do NOT reinstall. If anything is missing, see .brainclaw-worktree.json symlink_warnings.`);
+        }
+        else if (depsMode === 'none') {
+            parts.push('Dependencies: none were provisioned (deps_mode=none) — run the project\'s install (npm/pnpm/yarn/bun) in the worktree before building.');
+        }
+        else {
+            parts.push('Dependencies: node_modules is linked from the main repo (incl. monorepo per-package). Build/typecheck directly; if deps are missing, do NOT npm install here — see .brainclaw-worktree.json symlink_warnings and validate centrally. (Out-of-root symlink: next dev/Turbopack needs deps_mode=install.)');
+        }
     }
     parts.push('');
     // Assignment lifecycle protocol (Agent SDK)

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

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

package/dist/core/schema.js

@@ -1454,6 +1454,16 @@ export const ConfigSchema = z.object({
     worktree: z.object({
         shared_paths: z.array(z.string()).default([]),
         exclude_shared: z.array(z.string()).default([]),
+        /**
+         * How a dispatched worktree gets its JS dependencies (`node_modules`).
+         * trp_37b05a15 — the default `link` (out-of-root junction) is rejected by
+         * `next dev` / Turbopack. Set `install` (real per-worktree install, native
+         * package manager) or `copy` (recursive copy from the main tree) for a
+         * Turbopack-compatible in-root `node_modules`; `none` provisions no deps.
+         * Env `BRAINCLAW_WORKTREE_DEPS_MODE` overrides this; `BRAINCLAW_NO_LINK_DEPS=1`
+         * still forces `none`.
+         */
+        deps_mode: z.enum(['link', 'install', 'copy', 'none']).optional(),
     }).optional(),
     // Event-log store (pln#543). Absent ⇒ off — fresh and existing stores keep
     // today's behavior; the journal only activates when explicitly set here (or

package/dist/core/worktree.js

@@ -5,6 +5,7 @@ import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import yaml from 'yaml';
 import { logger } from './logger.js';
+import { loadConfig } from './config.js';
 import { parsePorcelainZ, isSystemDirtyPath } from './dirty-scope.js';
 /** Normalizes a path for use in git CLI arguments (forward slashes on Windows). */
 function gitPath(p) {
@@ -93,6 +94,67 @@ export function detectStackSharedPaths(projectRoot) {
     }
     return [...result];
 }
+const WORKTREE_DEPS_MODES = ['link', 'install', 'copy', 'none'];
+/**
+ * Resolves the JS dependency provisioning mode for a worktree.
+ *
+ * Precedence (first match wins):
+ *   1. env `BRAINCLAW_WORKTREE_DEPS_MODE` (link|install|copy|none)
+ *   2. env `BRAINCLAW_NO_LINK_DEPS=1` → `none` (backward compat)
+ *   3. config `worktree.deps_mode` in `.brainclaw/config.yaml`
+ *   4. `link` (default — unchanged behavior)
+ *
+ * An unrecognized env value is ignored (falls through) with a warning, so a
+ * typo never silently changes provisioning.
+ */
+export function resolveWorktreeDepsMode(projectRoot) {
+    const envMode = process.env.BRAINCLAW_WORKTREE_DEPS_MODE?.trim().toLowerCase();
+    if (envMode) {
+        if (WORKTREE_DEPS_MODES.includes(envMode)) {
+            return envMode;
+        }
+        logger.warn(`[worktree] Ignoring invalid BRAINCLAW_WORKTREE_DEPS_MODE='${envMode}' `
+            + `(expected one of ${WORKTREE_DEPS_MODES.join('|')}).`);
+    }
+    if (process.env.BRAINCLAW_NO_LINK_DEPS === '1')
+        return 'none';
+    try {
+        const configured = loadConfig(projectRoot).worktree?.deps_mode;
+        if (configured && WORKTREE_DEPS_MODES.includes(configured)) {
+            return configured;
+        }
+    }
+    catch { /* no / invalid config — fall through to default */ }
+    return 'link';
+}
+/**
+ * Detects the JS package manager for a project from its lockfile, falling back
+ * to the `packageManager` field of package.json, then to `npm`. Lockfile wins
+ * because it reflects what actually produced the main tree's `node_modules`.
+ */
+export function detectPackageManager(projectRoot) {
+    const lockfiles = [
+        ['pnpm-lock.yaml', 'pnpm'],
+        ['yarn.lock', 'yarn'],
+        ['bun.lockb', 'bun'],
+        ['bun.lock', 'bun'],
+        ['package-lock.json', 'npm'],
+        ['npm-shrinkwrap.json', 'npm'],
+    ];
+    for (const [file, pm] of lockfiles) {
+        if (fs.existsSync(path.join(projectRoot, file)))
+            return pm;
+    }
+    try {
+        const pkg = JSON.parse(fs.readFileSync(path.join(projectRoot, 'package.json'), 'utf-8'));
+        const declared = pkg.packageManager?.split('@')[0]?.trim();
+        if (declared === 'pnpm' || declared === 'yarn' || declared === 'bun' || declared === 'npm') {
+            return declared;
+        }
+    }
+    catch { /* no / invalid package.json — default below */ }
+    return 'npm';
+}
 /**
  * pln#523 — read declared monorepo workspace globs from npm/yarn/bun
  * `workspaces` (package.json) and pnpm-workspace.yaml. Returns the raw
@@ -555,6 +617,106 @@ export function projectUsesNextjs(projectRoot) {
         return false;
     }
 }
+/**
+ * Timeout for a per-worktree package-manager install (`deps_mode=install`).
+ * Defaults to 10 minutes; override with BRAINCLAW_WORKTREE_INSTALL_TIMEOUT_MS.
+ */
+export function resolveWorktreeInstallTimeoutMs() {
+    const raw = process.env.BRAINCLAW_WORKTREE_INSTALL_TIMEOUT_MS;
+    const n = raw ? Number.parseInt(raw, 10) : NaN;
+    return Number.isFinite(n) && n > 0 ? n : 600_000;
+}
+/**
+ * Provisions a worktree's JS dependencies for `install` / `copy` deps modes,
+ * yielding a real in-root `node_modules` that `next dev` / Turbopack accepts
+ * (unlike the out-of-root junction of `link` mode; trp_37b05a15).
+ *
+ * Best-effort: any failure is recorded as a warning (the worker can still
+ * install by hand) and NEVER thrown — worktree creation must not fail over
+ * dependency provisioning. Returns human-readable warnings (empty on success).
+ *
+ * - `install` runs ONE package-manager install at the worktree root, which
+ *   natively populates monorepo workspace `node_modules` too — so it ignores
+ *   `nodeModulesRelPaths`. No-op when the project has no `package.json`.
+ * - `copy` recursively mirrors each existing `node_modules` dir from the main
+ *   tree (symlinks copied verbatim so pnpm's relative link farm stays valid).
+ */
+export function provisionWorktreeDeps(mode, mainWorktreePath, targetPath, nodeModulesRelPaths) {
+    const warnings = [];
+    if (mode === 'install') {
+        if (!fs.existsSync(path.join(targetPath, 'package.json')))
+            return warnings;
+        const pm = detectPackageManager(mainWorktreePath);
+        const timeoutMs = resolveWorktreeInstallTimeoutMs();
+        // Windows: npm/pnpm/yarn/bun are `.cmd` shims, only found via the shell — so
+        // pass ONE static command string (pm is validated; 'install' is literal → no
+        // injection) and NO args array (avoids DEP0190). Unix: the binaries are on
+        // PATH, so spawn directly with an args array and no shell.
+        const result = process.platform === 'win32'
+            ? spawnSync(`${pm} install`, { cwd: targetPath, encoding: 'utf-8', timeout: timeoutMs, shell: true })
+            : spawnSync(pm, ['install'], { cwd: targetPath, encoding: 'utf-8', timeout: timeoutMs });
+        if (result.error?.code === 'ETIMEDOUT') {
+            const msg = `deps_mode=install: '${pm} install' timed out after ${timeoutMs}ms and was killed `
+                + `(raise BRAINCLAW_WORKTREE_INSTALL_TIMEOUT_MS). Run '${pm} install' in the worktree manually.`;
+            warnings.push(msg);
+            logger.warn(`[worktree] ${msg}`);
+        }
+        else if (result.error) {
+            const msg = `deps_mode=install: could not run '${pm} install' (${result.error.message}). `
+                + `Is ${pm} on PATH? Run '${pm} install' in the worktree manually.`;
+            warnings.push(msg);
+            logger.warn(`[worktree] ${msg}`);
+        }
+        else if (result.status !== 0) {
+            const tail = (result.stderr || result.stdout || '').trim().split(/\r?\n/).filter(Boolean).slice(-3).join(' | ');
+            const msg = `deps_mode=install: '${pm} install' exited ${result.status ?? '?'}${tail ? ` — ${tail}` : ''}. `
+                + `Run '${pm} install' in the worktree manually.`;
+            warnings.push(msg);
+            logger.warn(`[worktree] ${msg}`);
+        }
+        return warnings;
+    }
+    // copy
+    const copyable = nodeModulesRelPaths.filter((rel) => fs.existsSync(path.join(mainWorktreePath, rel)));
+    if (copyable.length === 0) {
+        if (fs.existsSync(path.join(targetPath, 'package.json'))) {
+            const pm = detectPackageManager(mainWorktreePath);
+            const msg = `deps_mode=copy: no node_modules found in the main tree to copy — `
+                + `run '${pm} install' in the worktree.`;
+            warnings.push(msg);
+            logger.warn(`[worktree] ${msg}`);
+        }
+        return warnings;
+    }
+    for (const rel of copyable) {
+        const src = path.join(mainWorktreePath, rel);
+        const dest = path.join(targetPath, rel);
+        if (fs.existsSync(dest))
+            continue;
+        try {
+            const parentDir = path.dirname(dest);
+            if (parentDir !== targetPath)
+                fs.mkdirSync(parentDir, { recursive: true });
+            // Codex review P1: if the SOURCE node_modules is itself a symlink/junction
+            // (e.g. a main tree that is itself a linked worktree, or a user-linked
+            // node_modules), a verbatim copy would reproduce that out-of-root link and
+            // Turbopack would still reject it — defeating copy mode. Dereference the
+            // TOP-LEVEL entry to its real directory before copying, then copy with
+            // verbatimSymlinks so the tree's INTERNAL relative links (pnpm's farm)
+            // stay intact. A real dir source copies straight through.
+            const srcReal = fs.lstatSync(src).isSymbolicLink() ? fs.realpathSync(src) : src;
+            fs.cpSync(srcReal, dest, { recursive: true, verbatimSymlinks: true });
+        }
+        catch (err) {
+            const reason = err instanceof Error ? err.message : String(err);
+            const msg = `deps_mode=copy: failed to copy '${rel}' into worktree (${reason}). `
+                + `Run the package manager's install in the worktree manually.`;
+            warnings.push(msg);
+            logger.warn(`[worktree] ${msg}`);
+        }
+    }
+    return warnings;
+}
 export function createWorktree(mainWorktreePath, branchName, options = {}) {
     // pln#614: resolve the true git toplevel first, so an in-tree project (project
     // dir ≠ git root) creates its worktree from the real repo root — `git worktree
@@ -669,35 +831,59 @@ export function createWorktree(mainWorktreePath, branchName, options = {}) {
     // `dist` intentionally excluded — build outputs must be per-worktree
     // (EBUSY during clean:dist when MCP/extension holds a handle on junction target).
     // pln#523: also link per-package node_modules for JS/TS monorepos so workers
-    // can build/typecheck sub-packages, not just the root. Set
-    // BRAINCLAW_NO_LINK_DEPS=1 to disable auto dependency linking (e.g. when the
-    // worktree lives on a different volume and central validation is preferred);
-    // explicit options.sharedPaths are still honored.
-    const linkDepsDisabled = process.env.BRAINCLAW_NO_LINK_DEPS === '1';
-    const detected = linkDepsDisabled
+    // can build/typecheck sub-packages, not just the root.
+    //
+    // trp_37b05a15: the JS dependency provisioning mode (link | install | copy |
+    // none) is opt-in via BRAINCLAW_WORKTREE_DEPS_MODE / config worktree.deps_mode
+    // (BRAINCLAW_NO_LINK_DEPS=1 still maps to `none`). `link` (default) junctions
+    // node_modules from the main tree — an out-of-root symlink `next dev` rejects;
+    // `install`/`copy` provision a real in-root node_modules (Turbopack-ok);
+    // `none` provisions no deps (central validation). Explicit options.sharedPaths
+    // are always honored.
+    const isNodeModulesPath = (p) => p === 'node_modules' || p.endsWith('/node_modules');
+    const depsMode = resolveWorktreeDepsMode(mainWorktreePath);
+    const detected = depsMode === 'none'
         ? []
         : [...detectStackSharedPaths(mainWorktreePath), ...detectWorkspaceNodeModules(mainWorktreePath)];
     const extra = options.sharedPaths ?? [];
     const excluded = new Set(options.excludeShared ?? []);
-    const sharedPaths = [...new Set([...detected, ...extra])].filter((p) => !excluded.has(p));
+    const requested = [...new Set([...detected, ...extra])].filter((p) => !excluded.has(p));
+    // In install/copy mode, node_modules becomes a REAL in-root directory instead
+    // of an out-of-root junction — so it is excluded from the symlink pass and
+    // provisioned separately. Other stack dirs (venv, vendor, …) still link.
+    const provisionDeps = depsMode === 'install' || depsMode === 'copy';
+    const nodeModulesPaths = requested.filter(isNodeModulesPath);
+    const sharedPaths = provisionDeps ? requested.filter((p) => !isNodeModulesPath(p)) : requested;
     for (const entry of sharedPaths) {
         trySymlinkSharedPath(entry);
     }
-    // trp_37b05a15 (field report, Next.js 16 / Turbopack) — the node_modules link
-    // brainclaw provisions is an out-of-worktree-root symlink to the main repo.
-    // tsc / vitest / build follow it fine, but `next dev` (Turbopack) PANICS on a
-    // node_modules link that points outside the worktree root. Surface a warning
-    // (not a failure — the link is still correct for build/typecheck) so a worker
-    // or operator doing dev-server work knows the workaround up front. A full
-    // Turbopack-compatible per-worktree dependency mode is a planned follow-up.
-    const linkedNodeModules = sharedPaths.some((p) => p === 'node_modules' || p.endsWith('/node_modules'));
-    if (linkedNodeModules && projectUsesNextjs(mainWorktreePath)) {
-        const msg = 'Next.js detected: node_modules is linked as an out-of-worktree-root symlink, which '
-            + '`next dev` / Turbopack rejects (it requires node_modules under the worktree root). '
-            + 'tsc / vitest / build are unaffected. For dev-server work in this worktree, run '
-            + '`npm install` here (optionally with BRAINCLAW_NO_LINK_DEPS=1), or smoke-test on the merged branch.';
-        symlinkWarnings.push(msg);
-        logger.warn(`[worktree] ${msg}`);
+    // Codex review P1: track whether in-root provisioning actually succeeded, so
+    // the dispatch brief can tell the worker the truth. A failed install/copy is
+    // best-effort (non-fatal) but the worker must then install itself — the brief
+    // must NOT claim "node_modules is real, do not reinstall" over a failure.
+    let depsProvisioned;
+    if (provisionDeps) {
+        const provisionWarnings = provisionWorktreeDeps(depsMode, mainWorktreePath, targetPath, nodeModulesPaths);
+        symlinkWarnings.push(...provisionWarnings);
+        depsProvisioned = provisionWarnings.length === 0;
+    }
+    else if (depsMode === 'link') {
+        // trp_37b05a15 (field report, Next.js 16 / Turbopack) — the node_modules link
+        // brainclaw provisions is an out-of-worktree-root symlink to the main repo.
+        // tsc / vitest / build follow it fine, but `next dev` (Turbopack) PANICS on a
+        // node_modules link that points outside the worktree root. Surface a warning
+        // (not a failure — the link is still correct for build/typecheck) so a worker
+        // or operator doing dev-server work knows the workaround up front.
+        const linkedNodeModules = sharedPaths.some(isNodeModulesPath);
+        if (linkedNodeModules && projectUsesNextjs(mainWorktreePath)) {
+            const msg = 'Next.js detected: node_modules is linked as an out-of-worktree-root symlink, which '
+                + '`next dev` / Turbopack rejects (it requires node_modules under the worktree root). '
+                + 'tsc / vitest / build are unaffected. For dev-server work, set deps_mode=install '
+                + '(config worktree.deps_mode or BRAINCLAW_WORKTREE_DEPS_MODE=install), run `npm install` '
+                + 'here, or smoke-test on the merged branch.';
+            symlinkWarnings.push(msg);
+            logger.warn(`[worktree] ${msg}`);
+        }
     }
     // NOTE: .brainclaw/ is intentionally NOT symlinked.
     // Symlinking .brainclaw/ causes hooks and session_start to trigger on the
@@ -737,6 +923,14 @@ export function createWorktree(mainWorktreePath, branchName, options = {}) {
         ...(baseRefSha ? { base_ref_sha: baseRefSha } : {}),
         reset_existing_branch: options.resetExistingBranch === true,
         git_advice: 'git add ONLY specific files, NEVER git add -A.',
+        // trp_37b05a15: how JS deps were provisioned (link junction / real install /
+        // copy / none) — non-default modes are recorded so a worker/supervisor knows
+        // whether node_modules is an out-of-root link (dev-server caveat) or in-root.
+        // `deps_provisioned` (install/copy only) records whether the in-root
+        // provisioning actually succeeded — false means best-effort failed and the
+        // worker must install itself (Codex review P1).
+        ...(depsMode !== 'link' ? { deps_mode: depsMode } : {}),
+        ...(depsProvisioned !== undefined ? { deps_provisioned: depsProvisioned } : {}),
         // pln#523: surface any shared-path link failures (e.g. node_modules junction
         // that could not be created) so the worker / supervisor can see why a build
         // might fail, instead of an invisible degradation.

package/dist/facts.js

@@ -1,8 +1,8 @@
 // Generated by scripts/emit-site-facts.mjs at build time. Do not edit manually.
-// Source: brainclaw v1.16.0 on 2026-07-18T18:21:20.312Z
+// Source: brainclaw v1.17.0 on 2026-07-19T20:01:41.172Z
 export const FACTS = {
-  "version": "1.16.0",
-  "generated_at": "2026-07-18T18:21:20.312Z",
+  "version": "1.17.0",
+  "generated_at": "2026-07-19T20:01:41.172Z",
   "tools": {
     "count": 67,
     "published_count": 65,
@@ -221,7 +221,7 @@ export const FACTS = {
         "workflow_model": "task-based",
         "tier": "A",
         "has_mcp": true,
-        "has_hooks": false,
+        "has_hooks": true,
         "has_skills": true,
         "has_rules": true,
         "instruction_file": "AGENTS.md",
@@ -474,7 +474,7 @@ export const FACTS = {
   },
   "bench": {
     "schema": "brainclaw.bench.v1",
-    "generated_at": "2026-07-18T18:21:18.026Z",
+    "generated_at": "2026-07-19T20:01:39.038Z",
     "node_version": "v24.18.0",
     "platform": "linux-x64",
     "repeats": 3,
@@ -483,7 +483,7 @@ export const FACTS = {
         "name": "cold_onboard",
         "volume": "empty",
         "description": "fresh machine → init → first useful context. Baseline for time-to-first-value.",
-        "duration_ms_median": 82,
+        "duration_ms_median": 76,
         "payload_chars_median": 1640,
         "payload_tokens_est_median": 410
       },
@@ -491,7 +491,7 @@ export const FACTS = {
         "name": "warm_work",
         "volume": "medium",
         "description": "bclaw_work consult over a real-shaped store (~200 plans / 500 handoffs / 450 claims).",
-        "duration_ms_median": 146,
+        "duration_ms_median": 135,
         "payload_chars_median": 2626,
         "payload_tokens_est_median": 657
       },
@@ -499,7 +499,7 @@ export const FACTS = {
         "name": "first_edit",
         "volume": "medium",
         "description": "code_find + code_brief on the fresh-agent path (missing index, first touch).",
-        "duration_ms_median": 9,
+        "duration_ms_median": 7,
         "payload_chars_median": 442,
         "payload_tokens_est_median": 111
       }

package/dist/facts.json

@@ -1,6 +1,6 @@
 {
-  "version": "1.16.0",
-  "generated_at": "2026-07-18T18:21:20.312Z",
+  "version": "1.17.0",
+  "generated_at": "2026-07-19T20:01:41.172Z",
   "tools": {
     "count": 67,
     "published_count": 65,
@@ -219,7 +219,7 @@
         "workflow_model": "task-based",
         "tier": "A",
         "has_mcp": true,
-        "has_hooks": false,
+        "has_hooks": true,
         "has_skills": true,
         "has_rules": true,
         "instruction_file": "AGENTS.md",
@@ -472,7 +472,7 @@
   },
   "bench": {
     "schema": "brainclaw.bench.v1",
-    "generated_at": "2026-07-18T18:21:18.026Z",
+    "generated_at": "2026-07-19T20:01:39.038Z",
     "node_version": "v24.18.0",
     "platform": "linux-x64",
     "repeats": 3,
@@ -481,7 +481,7 @@
         "name": "cold_onboard",
         "volume": "empty",
         "description": "fresh machine → init → first useful context. Baseline for time-to-first-value.",
-        "duration_ms_median": 82,
+        "duration_ms_median": 76,
         "payload_chars_median": 1640,
         "payload_tokens_est_median": 410
       },
@@ -489,7 +489,7 @@
         "name": "warm_work",
         "volume": "medium",
         "description": "bclaw_work consult over a real-shaped store (~200 plans / 500 handoffs / 450 claims).",
-        "duration_ms_median": 146,
+        "duration_ms_median": 135,
         "payload_chars_median": 2626,
         "payload_tokens_est_median": 657
       },
@@ -497,7 +497,7 @@
         "name": "first_edit",
         "volume": "medium",
         "description": "code_find + code_brief on the fresh-agent path (missing index, first touch).",
-        "duration_ms_median": 9,
+        "duration_ms_median": 7,
         "payload_chars_median": 442,
         "payload_tokens_est_median": 111
       }

package/docs/concepts/loop-engine.md

@@ -330,9 +330,11 @@ When `bclaw_coordinate(intent='review', open_loop: true)` is called, it:
 3. Links the provided handoff/candidate to the loop as an artifact at `change_summary`.
 4. Advances to `findings` and calls `bclaw_loop(intent: 'turn')` to dispatch to the reviewer.
 5. On turn completion with a verdict artifact, auto-advances; `reviewer_green` stop closes.
-6. On non-green verdict with `iteration_count < max`, advances to `author_response`, dispatches to author.
+6. On a `request_changes` verdict, the fix cycle re-dispatches the reviewer into the same worktree until `approve` or the `max_iterations` cap.
 
-**How the verdict reaches the loop (shipped, pln#628 Focus 4B).** A dispatched reviewer worker does not call `bclaw_loop` itself — it writes its outcome to `LANE-RESULT.json` at the worktree root, now including an optional `review_verdict` (`approve` | `request_changes`) and `review_summary`. When the coordinator runs `brainclaw harvest <assignment_id>` (both the report-only path and `--integrate`), a review lane carrying a `review_verdict` is mapped onto its loop: brainclaw records a `verdict` artifact on the reviewer slot (`approve` → an `accepted…` body) and calls `advance`, which **auto-closes the loop on `reviewer_green` for `approve`** — no human driving `complete_turn`/`advance`. `request_changes` records the verdict and advances to `author_response` (the automated fix→re-review cycle is a follow-up). The mapping is idempotent, resolves the reviewer slot strictly by `assignment_id` (so symmetric multi-reviewer loops target the right slot), and runs the `complete_turn`+`advance` pair under the loop lock so an interrupted pass resumes rather than stalls.
+**How the verdict reaches the loop (shipped, pln#628 Focus 4B).** A dispatched reviewer worker does not call `bclaw_loop` itself — it writes its outcome to `LANE-RESULT.json` at the worktree root, including an optional `review_verdict` (`approve` | `request_changes`) and `review_summary`. When the coordinator runs `brainclaw harvest <assignment_id>` (report-only path and `--integrate`), a review lane carrying a `review_verdict` is mapped onto its loop: brainclaw records a `verdict` artifact on the reviewer slot (`approve` → an `accepted…` body) and calls `advance`, which **auto-closes the loop on `reviewer_green` for `approve`** — no human driving `complete_turn`/`advance`.
+
+**The autonomous fix cycle (PR2, `--integrate` only).** On `request_changes`, `harvest --integrate` bumps the loop's round counter, **keeps the claim + worktree alive**, and re-dispatches the same reviewer slot into that **same worktree** (symmetric mode) with a findings-aware brief: apply the requested changes in place, then re-review. Commits accumulate on one branch — no fresh worktree per turn, so the branch-per-scope / refuse-unharvested-commits invariants are never tripped. The cycle repeats until `approve` (→ `reviewer_green` close) or the `max_iterations` cap (n=3 → auto-close `blocked`, handed to a human). The report-only harvest path never cycles (it can neither re-dispatch nor retain the claim); it defers `request_changes` to `--integrate` and still closes on `approve`. The mapping is idempotent, resolves the reviewer slot strictly by `assignment_id` (so symmetric multi-reviewer loops target the right slot), and runs the `complete_turn`+`advance` pair under the loop lock so an interrupted pass resumes rather than stalls. Asymmetric (author ≠ reviewer) cross-agent worktree sharing is a planned follow-up.
 
 ### Symmetric review-AND-fix mode
 

package/docs/integrations/codex.md

@@ -1,13 +1,13 @@
 # Codex Integration
 
-brainclaw integrates with OpenAI's Codex CLI through MCP tools and shared instruction files. Codex has MCP access, universal skills support, and headless CLI spawn capability, but no native lifecycle hook surface.
+brainclaw integrates with OpenAI's Codex CLI through MCP tools, shared instruction files, and native lifecycle hooks. Codex has MCP access, universal skills support, headless CLI spawn capability, and a native lifecycle hook surface (added upstream in 2026 — [developers.openai.com/codex/hooks](https://developers.openai.com/codex/hooks)).
 
 ## Auto-setup
 
 Codex setup is split across machine and project scope:
 
 - `brainclaw setup-machine --agents codex --yes` writes the machine-level MCP config at `~/.codex/config.toml`
-- `brainclaw init` creates or refreshes the current project's Brainclaw state and writes `AGENTS.md`
+- `brainclaw init` creates or refreshes the current project's Brainclaw state, writes `AGENTS.md`, and writes project-level lifecycle hooks to `.codex/hooks.json` (git-ignored)
 
 If the project already has `.brainclaw/`, rerunning `brainclaw init` is safe and refreshes the managed Brainclaw/Codex files for the current machine.
 
@@ -61,7 +61,7 @@ Since pln#476 (1.0.13+), spawned Codex workers are marked `delivered_and_started
 |-------|-------|
 | Tier | A |
 | MCP | yes |
-| Hooks | no |
+| Hooks | yes (`.codex/hooks.json`, project scope) |
 | Auto-approve | manual (per-tool approval) |
 | Skills | yes |
 | CLI spawnable | yes |
@@ -70,6 +70,22 @@ Since pln#476 (1.0.13+), spawned Codex workers are marked `delivered_and_started
 | MCP config scope | machine |
 | Prompt delivery | `stdin_pipe` (preferred), `inline_arg` (fallback) |
 
+## Lifecycle hooks
+
+`brainclaw init` writes project-level hooks to `.codex/hooks.json` (git-ignored, machine-specific command paths). Codex reads hooks from `hooks.json` or an inline `[hooks]` table at user (`~/.codex/`) and project (`<repo>/.codex/`) scope ([Codex hooks docs](https://developers.openai.com/codex/hooks)). brainclaw wires three events:
+
+| Event | brainclaw command | Purpose |
+|-------|-------------------|---------|
+| `SessionStart` | `brainclaw session-start --include-context` | Load shared context (constraints, decisions, traps, plans, handoffs) when a session begins |
+| `UserPromptSubmit` | `brainclaw context-diff` | Surface what changed since the last turn |
+| `Stop` | `brainclaw session-end --auto-release --reflect --reflect-handoff --dispatch-review` | Release claims, reflect, and dispatch review at turn end |
+
+The file shape is `{ "hooks": { "<Event>": [ { "matcher": "", "hooks": [ { "type": "command", "command": "…" } ] } ] } }` (`matcher: ""` = match all occurrences). brainclaw **owns** these three event arrays: reruns overwrite them (idempotent, no cross-upgrade pile-up) — the same contract as the Cursor / Antigravity hook writers. A user's own hook placed on one of these three events is replaced on the next `init`; hooks on any **other** event are left untouched.
+
+**Scope — interactive sessions, not headless dispatch.** These hooks serve an *interactive* Codex session. Non-managed command hooks require a one-time trust in Codex (`/hooks` — inspect and trust) before they run, so a fresh `.codex/hooks.json` is inert until the user trusts it. Headless dispatched workers (`codex exec`, used by `bclaw_dispatch` / `bclaw_coordinate`) do **not** rely on these hooks at all — they receive their context in the dispatch brief and report via `LANE-RESULT.json`; an untrusted project hook is simply skipped there, which is harmless. (A "managed" hook path via `requirements.toml`/MDM could bypass the trust step for fleets — a possible future enhancement.)
+
+**Per-event output contract.** `SessionStart` and `UserPromptSubmit` emit their stdout as **model-visible context** — that is exactly the point (inject shared brainclaw state / the context diff). `Stop`, by contrast, expects a **JSON** response from Codex to shape turn-end behavior; brainclaw's `session-end` runs mainly for its side effects (release claims, reflect, dispatch review) and does not emit that JSON, so it does not gate the turn. Emitting a conformant per-event JSON response (notably for `Stop`) is a planned follow-up.
+
 ## Caveats
 
 - **Sandbox blocks `git commit`, not MCP** (dec#133): a sandboxed Codex run reaches brainclaw MCP (the server is a separate out-of-sandbox process; `approval_policy=never` auto-approves). What the sandbox *does* block is direct writes to paths outside the worktree root — notably `.git`, so the worker cannot `git commit`. Leave fixes uncommitted; the coordinator integrates + commits the worktree diff at harvest. A LANE-RESULT.json / filesystem-direct candidate write remains a valid fallback for reporting.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brainclaw",
-  "version": "1.16.0",
+  "version": "1.17.0",
   "description": "Shared project memory for humans and coding agents.",
   "type": "module",
   "repository": {