brainclaw 1.15.0 → 1.17.0

package/dist/core/schema.js

@@ -960,8 +960,9 @@ export const RuntimeEventTypeSchema = z.enum([
 /**
  * pln#526 — LANE-RESULT convention. A dispatched worker writes a single
  * `LANE-RESULT.json` at its worktree root as its final step (a fallback that
- * works even when bclaw_assignment_update / MCP is unavailable, e.g. sandboxed
- * agents). The coordinator ingests it with `brainclaw harvest <assignment_id>`.
+ * works even when bclaw_assignment_update / MCP is unavailable in the worker's
+ * environment, e.g. a genuinely MCP-less agent). The coordinator ingests it with
+ * `brainclaw harvest <assignment_id>`.
  */
 export const LaneResultSchema = z.object({
     assignment_id: z.string(),
@@ -973,6 +974,17 @@ export const LaneResultSchema = z.object({
     files_changed: z.array(z.string()).optional(),
     /** Free-form notes (blockers, follow-ups). */
     notes: z.string().optional(),
+    /**
+     * pln#628 Focus 4B — review-loop verdict. A worker running a review-loop turn
+     * sets this to signal whether the change is good to merge (`approve`) or needs
+     * fixes (`request_changes`). The coordinator's harvest maps it onto a loop
+     * `verdict` artifact so `reviewer_green` can fire and the loop auto-closes
+     * without a human driving complete_turn/advance by hand. Absent on
+     * non-review lanes — harvest simply skips the loop-close callback then.
+     */
+    review_verdict: z.enum(['approve', 'request_changes']).optional(),
+    /** One-line rationale accompanying review_verdict (shown in the verdict artifact). */
+    review_summary: z.string().optional(),
 });
 export const RuntimeEventSchema = z.object({
     id: z.string(),
@@ -1442,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/security-detectors.js

@@ -52,7 +52,7 @@ export function runStructuralDetectors(text, disabled) {
             out.push({
                 detectorId: d.id,
                 label: d.label,
-                excerpt: truncate(m[0]),
+                excerpt: maskSecret(m[0]),
             });
         }
     }
@@ -113,13 +113,42 @@ export function runEntropyDetector(text, options = {}) {
         const context = text.slice(start, end);
         if (!SECRET_KEYWORD_CONTEXT.test(context))
             continue;
-        out.push({ excerpt: truncate(token), entropy: Math.round(entropy * 100) / 100 });
+        out.push({ excerpt: maskSecret(token), entropy: Math.round(entropy * 100) / 100 });
     }
     return out;
 }
-function truncate(s, maxLen = 48) {
-    if (s.length <= maxLen)
-        return s;
-    return s.slice(0, Math.max(8, maxLen / 2)) + '…' + s.slice(-Math.max(4, maxLen / 4));
+/**
+ * Irreversibly mask a matched secret for display.
+ *
+ * The previous behavior truncated the match to ~48 chars, which returned
+ * short secrets (GitHub PATs are 40 chars, AWS key IDs are 20) verbatim in
+ * warning messages and logs. Masking keeps just enough to identify the
+ * token family without ever exposing recoverable material. Splitting is
+ * done per Unicode code point, so surrogate pairs are never cut in half.
+ *
+ *   - matches of 2 code points or fewer: `***` alone (exposing even the
+ *     first code point would reveal most or all of the value);
+ *   - matches of 3–8 code points: first code point + `***`;
+ *   - longer matches: at most ⌊length/3⌋ code points are exposed, capped
+ *     at 6, split prefix-heavy (up to 4 leading — enough to identify
+ *     `ghp_`, `AKIA`, `sk_l` — the remainder trailing) around a fixed
+ *     `…***…` marker.
+ *
+ * The exposure budget grows smoothly with the match length (no cliff at
+ * the short/long boundary) and never reveals more than a third of a
+ * match longer than 8 code points.
+ */
+export function maskSecret(s) {
+    const cp = Array.from(s);
+    if (cp.length === 0)
+        return '';
+    if (cp.length <= 2)
+        return '***';
+    if (cp.length <= 8)
+        return cp[0] + '***';
+    const exposed = Math.min(6, Math.floor(cp.length / 3));
+    const lead = Math.min(4, exposed - 1);
+    const trail = exposed - lead;
+    return cp.slice(0, lead).join('') + '…***…' + cp.slice(cp.length - trail).join('');
 }
 //# sourceMappingURL=security-detectors.js.map

package/dist/core/security.js

@@ -1,14 +1,27 @@
-import { runEntropyDetector, runStructuralDetectors } from './security-detectors.js';
+import { maskSecret, runEntropyDetector, runStructuralDetectors } from './security-detectors.js';
 /**
- * Scan a text string for sensitive content. Three signal layers run:
- *   1. User-configured regex patterns from `config.redaction.patterns`
- *      (the legacy MVP behavior).
- *   2. Structural detectors — exact token shapes for GitHub PATs, AWS
- *      access keys, JWTs, etc. High precision; on by default.
- *   3. Entropy detector — flags high-entropy token-like substrings near
- *      a sensitive keyword. Tunable, on by default.
+ * Scan a text string for sensitive content. Four independent signal layers
+ * run, each with its own enable-gate (S4 semantics, pln#623):
  *
- * In strict mode all signals escalate to `block`; otherwise `warn`.
+ *   1. Redaction patterns — user-configured regexes from
+ *      `config.redaction.patterns`. Gate: `config.redaction.enabled` (whole
+ *      scan short-circuits off when false). The legacy MVP behavior.
+ *   2. Structural detectors — exact token shapes for GitHub PATs, AWS access
+ *      keys, JWTs, etc. High precision. Gate: `security.token_detection.enabled`
+ *      (default on); individual detectors via `token_detection.detectors[id]`.
+ *   3. Entropy detector — high-Shannon-entropy token-like substrings near a
+ *      secret keyword. Gate: `security.token_detection.entropy.enabled` (nested
+ *      under the token_detection gate; default on).
+ *   4. Sensitive paths — literal mentions of `config.sensitive_paths` entries
+ *      (`.env`, `secrets/`, …). Gate: `security.block_sensitive_paths` (default
+ *      on).
+ *
+ * LEVEL (uniform across ALL four layers): a match surfaces as `warn`, and
+ * escalates to `block` when `security.strict_redaction` is true (mode: strict).
+ * Strict mode blocks every signal uniformly — there is no per-layer level
+ * override. Detected/redacted excerpts in messages are always irreversibly
+ * masked (see maskSecret); the redaction pattern itself is referenced by index
+ * and masked, never echoed.
  */
 export function scanText(text, config) {
     const warnings = [];
@@ -16,7 +29,7 @@ export function scanText(text, config) {
         return warnings;
     const isStrict = config.security?.strict_redaction ?? false;
     const level = isStrict ? 'block' : 'warn';
-    for (const pattern of config.redaction.patterns) {
+    for (const [i, pattern] of config.redaction.patterns.entries()) {
         try {
             // Strip Python-style inline flags (?i) etc. since we always use 'i' flag
             const cleanPattern = pattern.replace(/^\(\?[gimsuy]+\)/g, '');
@@ -24,7 +37,9 @@ export function scanText(text, config) {
             if (re.test(text)) {
                 warnings.push({
                     level,
-                    message: `Possible sensitive content matching pattern '${pattern}' found in text`,
+                    // The configured pattern may itself be a literal secret value, so
+                    // it is referenced by index and masked, never echoed verbatim.
+                    message: `Possible sensitive content matching redaction pattern #${i} ('${maskSecret(pattern)}') found in text`,
                 });
             }
         }
@@ -61,7 +76,12 @@ export function scanText(text, config) {
         for (const sp of config.sensitive_paths) {
             if (text.includes(sp)) {
                 warnings.push({
-                    level: 'warn',
+                    // S3 (pln#623): the level is config-derived, not hardcoded. Like the
+                    // three detector layers above, a sensitive-path match surfaces as a
+                    // `warn` normally and escalates to `block` under strict_redaction —
+                    // strict mode blocks EVERY signal, uniformly. `block_sensitive_paths`
+                    // remains the enable-gate for this layer (default on).
+                    level,
                     message: `Sensitive path '${sp}' mentioned in text`,
                 });
             }

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
@@ -369,14 +431,42 @@ export function commitWorktreeOnBehalf(worktreePath, message, options = {}) {
         return { committed: false, files_changed: [], reason: 'worktree clean — nothing to commit' };
     }
     // Stage everything, then UNSTAGE the transient files that must never land on
-    // the lane branch: the worker's own `LANE-RESULT.json` report and any
-    // `.brainclaw/` coordination state. Committing those would pollute the branch
-    // (and master, on merge) with non-deliverable artefacts.
+    // the lane branch: the worker's own `LANE-RESULT.json` report, any
+    // `.brainclaw/` coordination state, and the `.brainclaw-worktree.json` marker.
+    // Committing those would pollute the branch (and master, on merge) with
+    // non-deliverable artefacts — a field report (Codex on macOS) caught them
+    // landing in a lane commit (trp_01a2ba2a). `.brainclaw-worktree.json` sits at
+    // the worktree ROOT (NOT inside `.brainclaw/`), so the `.brainclaw` pathspec
+    // does not cover it — it needs its own entry. These are ALWAYS transient, so
+    // the unstage is unconditional.
     const add = runGit(['add', '-A'], worktreePath);
     if (!add.ok) {
         return { committed: false, files_changed: [], reason: `git add failed: ${add.stderr.trim()}` };
     }
-    runGit(['reset', '-q', '--', 'LANE-RESULT.json', '.brainclaw', '.brainclaw-heartbeat-*'], worktreePath);
+    runGit([
+        'reset', '-q', '--',
+        'LANE-RESULT.json',
+        '.brainclaw',
+        '.brainclaw-worktree.json',
+        '.brainclaw-heartbeat-*',
+    ], worktreePath);
+    // node_modules needs a TRACKED-AWARE exclusion (Codex review of #88, BLOCKING).
+    // Unstage the links/dirs brainclaw provisions — but a project that VENDORS
+    // node_modules tracks those files, and a worker's change to a TRACKED
+    // node_modules file is a REAL deliverable; dropping it would silently omit
+    // work. Strategy: unstage every node_modules path, then RE-ADD only the ones
+    // already tracked at HEAD and modified/deleted (never the fresh provisioned
+    // link/dir, which is `A` vs HEAD). The component-bounded pathspecs never match
+    // a similarly-named deliverable such as `src/node_modules_helper.ts` — the
+    // plain `node_modules` is root-leading-dir only, the `:(glob)` forms match the
+    // `node_modules` path component exactly (nested link entry + nested contents).
+    const NODE_MODULES_SPECS = ['node_modules', ':(glob)**/node_modules', ':(glob)**/node_modules/**'];
+    runGit(['reset', '-q', '--', ...NODE_MODULES_SPECS], worktreePath);
+    const trackedNm = runGit(['diff', '--name-only', '--diff-filter=MD', 'HEAD', '--', ...NODE_MODULES_SPECS], worktreePath);
+    const keepNm = trackedNm.stdout.split(/\r?\n/).map((l) => l.trim()).filter(Boolean);
+    if (keepNm.length > 0) {
+        runGit(['add', '--', ...keepNm], worktreePath);
+    }
     // The files actually staged for this commit (post-exclusion) — also the
     // truthful files_changed report.
     const staged = runGit(['diff', '--cached', '--name-only'], worktreePath);
@@ -385,7 +475,7 @@ export function commitWorktreeOnBehalf(worktreePath, message, options = {}) {
         // Only transient files changed — nothing deliverable to commit. Restore the
         // index so the worktree is left exactly as the worker left it.
         runGit(['reset', '-q'], worktreePath);
-        return { committed: false, files_changed: [], reason: 'no committable changes (only transient LANE-RESULT.json / .brainclaw)' };
+        return { committed: false, files_changed: [], reason: 'no committable changes (only transient LANE-RESULT.json / .brainclaw / node_modules links)' };
     }
     const authorName = options.authorName ?? 'brainclaw (on behalf)';
     const authorEmail = options.authorEmail ?? 'brainclaw@on-behalf.local';
@@ -503,6 +593,130 @@ export function findWorktreePathForBranch(worktrees, branchName) {
  *
  * Returns the absolute path to the newly created worktree.
  */
+/**
+ * Whether the project looks like a Next.js app — a `next` dependency in
+ * package.json or a `next.config.*` at the root. Used to warn that the
+ * out-of-root `node_modules` symlink brainclaw provisions is rejected by
+ * `next dev` / Turbopack (trp_37b05a15), even though tsc / vitest / build accept
+ * it. Best-effort + defensive: any read/parse error → false (never blocks
+ * worktree creation over a heuristic).
+ */
+export function projectUsesNextjs(projectRoot) {
+    try {
+        for (const cfg of ['next.config.js', 'next.config.mjs', 'next.config.ts', 'next.config.cjs']) {
+            if (fs.existsSync(path.join(projectRoot, cfg)))
+                return true;
+        }
+        const pkgPath = path.join(projectRoot, 'package.json');
+        if (!fs.existsSync(pkgPath))
+            return false;
+        const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+        return Boolean(pkg.dependencies?.next ?? pkg.devDependencies?.next);
+    }
+    catch {
+        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
@@ -617,20 +831,60 @@ 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);
     }
+    // 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
     // shared store, creating session conflicts and potentially blocking agents
@@ -669,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,11 +1,11 @@
 // Generated by scripts/emit-site-facts.mjs at build time. Do not edit manually.
-// Source: brainclaw v1.15.0 on 2026-07-15T15:24:46.074Z
+// Source: brainclaw v1.17.0 on 2026-07-19T20:01:41.172Z
 export const FACTS = {
-  "version": "1.15.0",
-  "generated_at": "2026-07-15T15:24:46.074Z",
+  "version": "1.17.0",
+  "generated_at": "2026-07-19T20:01:41.172Z",
   "tools": {
     "count": 67,
-    "published_count": 66,
+    "published_count": 65,
     "names": [
       "bclaw_bootstrap",
       "bclaw_release_notes",
@@ -77,7 +77,7 @@ export const FACTS = {
     ]
   },
   "entities": {
-    "count": 17,
+    "count": 18,
     "names": [
       "plan",
       "step",
@@ -95,6 +95,7 @@ export const FACTS = {
       "assignment",
       "agent_run",
       "action",
+      "agent",
       "cross_project_link"
     ],
     "short_label_prefixes": {
@@ -114,6 +115,7 @@ export const FACTS = {
       "assignment": "asgn",
       "agent_run": "run",
       "action": "act",
+      "agent": "agt",
       "cross_project_link": "xpl"
     }
   },
@@ -219,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",
@@ -472,7 +474,7 @@ export const FACTS = {
   },
   "bench": {
     "schema": "brainclaw.bench.v1",
-    "generated_at": "2026-07-15T15:24:43.956Z",
+    "generated_at": "2026-07-19T20:01:39.038Z",
     "node_version": "v24.18.0",
     "platform": "linux-x64",
     "repeats": 3,
@@ -482,14 +484,14 @@ export const FACTS = {
         "volume": "empty",
         "description": "fresh machine → init → first useful context. Baseline for time-to-first-value.",
         "duration_ms_median": 76,
-        "payload_chars_median": 1650,
-        "payload_tokens_est_median": 413
+        "payload_chars_median": 1640,
+        "payload_tokens_est_median": 410
       },
       {
         "name": "warm_work",
         "volume": "medium",
         "description": "bclaw_work consult over a real-shaped store (~200 plans / 500 handoffs / 450 claims).",
-        "duration_ms_median": 126,
+        "duration_ms_median": 135,
         "payload_chars_median": 2626,
         "payload_tokens_est_median": 657
       },
@@ -497,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": 8,
+        "duration_ms_median": 7,
         "payload_chars_median": 442,
         "payload_tokens_est_median": 111
       }