brainclaw 1.7.2 → 1.7.4

package/dist/core/schema.js

@@ -855,7 +855,25 @@ export const RuntimeEventTypeSchema = z.enum([
     'run_interrupted',
     'plan_cascade_to_done',
     'candidate_harvested',
+    'lane_result_harvested',
 ]);
+/**
+ * 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>`.
+ */
+export const LaneResultSchema = z.object({
+    assignment_id: z.string(),
+    status: z.enum(['completed', 'blocked', 'failed']),
+    summary: z.string(),
+    /** Paths or refs the worker produced (commits, files, docs). */
+    artifacts: z.array(z.string()).optional(),
+    /** Files the worker changed in the worktree. */
+    files_changed: z.array(z.string()).optional(),
+    /** Free-form notes (blockers, follow-ups). */
+    notes: z.string().optional(),
+});
 export const RuntimeEventSchema = z.object({
     id: z.string(),
     agent: z.string(),

package/dist/core/worktree.js

@@ -3,6 +3,9 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
+import yaml from 'yaml';
+import { logger } from './logger.js';
+import { parsePorcelainZ, isSystemDirtyPath } from './dirty-scope.js';
 /** Normalizes a path for use in git CLI arguments (forward slashes on Windows). */
 function gitPath(p) {
     return p.replace(/\\/g, '/');
@@ -37,6 +40,85 @@ export function detectStackSharedPaths(projectRoot) {
     }
     return [...result];
 }
+/**
+ * pln#523 — read declared monorepo workspace globs from npm/yarn/bun
+ * `workspaces` (package.json) and pnpm-workspace.yaml. Returns the raw
+ * patterns (e.g. "packages/*", "apps/api"); empty when the project is not a
+ * workspace root or the manifests are absent/invalid.
+ */
+export function readWorkspacePatterns(projectRoot) {
+    const patterns = [];
+    // npm / yarn / bun: package.json "workspaces" (array, or { packages: [...] })
+    try {
+        const pkg = JSON.parse(fs.readFileSync(path.join(projectRoot, 'package.json'), 'utf-8'));
+        const ws = pkg.workspaces;
+        if (Array.isArray(ws))
+            patterns.push(...ws);
+        else if (ws && Array.isArray(ws.packages))
+            patterns.push(...ws.packages);
+    }
+    catch { /* no / invalid package.json — not a node workspace root */ }
+    // pnpm: pnpm-workspace.yaml "packages"
+    try {
+        const parsed = yaml.parse(fs.readFileSync(path.join(projectRoot, 'pnpm-workspace.yaml'), 'utf-8'));
+        if (parsed && Array.isArray(parsed.packages))
+            patterns.push(...parsed.packages);
+    }
+    catch { /* no pnpm workspace file */ }
+    return [...new Set(patterns)];
+}
+/**
+ * pln#523 — resolve monorepo workspace globs to the per-package `node_modules`
+ * directories that actually exist on disk. Hoisted monorepos (all deps at the
+ * root) need only the root link from detectStackSharedPaths; this additionally
+ * covers packages that keep a LOCAL node_modules (pnpm, nohoist, partial
+ * hoisting) so a dispatched worker can build/typecheck a sub-package, not just
+ * the root — the exact gap behind a worker stalling on `tsc` in a worktree.
+ *
+ * Pattern shapes supported without a glob dependency (zero-runtime-dep policy):
+ *   - exact dir:       "apps/api"
+ *   - single wildcard: "packages/*"   → immediate child directories
+ *   - deep wildcard:   "packages/**"  → treated as one level ("packages/*")
+ * Negations ("!pkg/excluded") are skipped — they only narrow coverage and a
+ * missing link degrades gracefully to central validation.
+ *
+ * Returns relative paths with forward slashes (e.g. "apps/api/node_modules").
+ */
+export function detectWorkspaceNodeModules(projectRoot) {
+    const patterns = readWorkspacePatterns(projectRoot);
+    if (patterns.length === 0)
+        return [];
+    const result = new Set();
+    const addIfHasNodeModules = (relPkgDir) => {
+        const rel = `${relPkgDir.replace(/\\/g, '/').replace(/\/+$/, '')}/node_modules`;
+        if (fs.existsSync(path.join(projectRoot, rel)))
+            result.add(rel);
+    };
+    for (const raw of patterns) {
+        const pattern = raw.trim();
+        if (!pattern || pattern.startsWith('!'))
+            continue;
+        const wildcardIdx = pattern.indexOf('*');
+        if (wildcardIdx === -1) {
+            addIfHasNodeModules(pattern);
+            continue;
+        }
+        // Base dir = the path segment before the first wildcard.
+        const base = pattern.slice(0, wildcardIdx).replace(/\/+$/, '');
+        let children = [];
+        try {
+            children = fs
+                .readdirSync(path.join(projectRoot, base), { withFileTypes: true })
+                .filter((d) => d.isDirectory())
+                .map((d) => d.name);
+        }
+        catch { /* base dir absent — skip this pattern */ }
+        for (const child of children) {
+            addIfHasNodeModules(base ? `${base}/${child}` : child);
+        }
+    }
+    return [...result];
+}
 function canonicalizeScopePath(target) {
     let resolved;
     try {
@@ -191,6 +273,7 @@ export function findWorktreePathForBranch(worktrees, branchName) {
  * Returns the absolute path to the newly created worktree.
  */
 export function createWorktree(mainWorktreePath, branchName, options = {}) {
+    const symlinkWarnings = [];
     const trySymlinkSharedPath = (entryName) => {
         const sourcePath = path.join(mainWorktreePath, entryName);
         const linkPath = path.join(targetPath, entryName);
@@ -205,8 +288,20 @@ export function createWorktree(mainWorktreePath, branchName, options = {}) {
             }
             fs.symlinkSync(sourcePath, linkPath, 'junction');
         }
-        catch {
-            // Non-fatal - shared paths are an optimization for agent worktrees
+        catch (err) {
+            // pln#523: do NOT swallow silently. A missing node_modules junction is
+            // exactly what leaves a dispatched worker unable to build/typecheck in its
+            // worktree (it then stalls on `tsc` or npm scripts). Record a structured
+            // warning — surfaced in the worktree sidecar + logger — instead of an
+            // invisible degradation. Linking remains best-effort (non-fatal).
+            const sameVolume = path.parse(sourcePath).root.toLowerCase() === path.parse(targetPath).root.toLowerCase();
+            const reason = err instanceof Error ? err.message : String(err);
+            const hint = sameVolume
+                ? ''
+                : ' (source and worktree are on different volumes — directory junctions require the same volume; deps cannot be linked here, validate builds centrally)';
+            const msg = `Failed to link '${entryName}' into worktree: ${reason}${hint}`;
+            symlinkWarnings.push(msg);
+            logger.warn(`[worktree] ${msg}`);
         }
     };
     // Guard: bare repos have no working tree
@@ -256,7 +351,15 @@ export function createWorktree(mainWorktreePath, branchName, options = {}) {
     // pln#480: auto-detect shared paths from stack markers + config overrides.
     // `dist` intentionally excluded — build outputs must be per-worktree
     // (EBUSY during clean:dist when MCP/extension holds a handle on junction target).
-    const detected = detectStackSharedPaths(mainWorktreePath);
+    // 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
+        ? []
+        : [...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));
@@ -267,6 +370,14 @@ export function createWorktree(mainWorktreePath, branchName, options = {}) {
     // Symlinking .brainclaw/ causes hooks and session_start to trigger on the
     // shared store, creating session conflicts and potentially blocking agents
     // (especially Claude CLI which auto-detects .brainclaw/ presence).
+    // pln#479: opt-in per-worktree typecheck gate. Off by default — on large
+    // monorepos `tsc` is slow and a per-commit gate would be punishing — enable
+    // with BRAINCLAW_WORKTREE_TYPECHECK_GATE=1. Isolated to this worktree, so the
+    // main repo's commits are never affected.
+    let typecheckGate;
+    if (process.env.BRAINCLAW_WORKTREE_TYPECHECK_GATE === '1') {
+        typecheckGate = installWorktreeTypecheckGate(mainWorktreePath, targetPath);
+    }
     const mainGitignorePath = path.join(mainWorktreePath, '.gitignore');
     const targetGitignorePath = path.join(targetPath, '.gitignore');
     if (fs.existsSync(mainGitignorePath)) {
@@ -282,10 +393,87 @@ export function createWorktree(mainWorktreePath, branchName, options = {}) {
         base_ref: baseRef,
         reset_existing_branch: options.resetExistingBranch === true,
         git_advice: 'git add ONLY specific files, NEVER git add -A.',
+        // 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.
+        ...(symlinkWarnings.length > 0 ? { symlink_warnings: symlinkWarnings } : {}),
+        // pln#479: record whether the per-worktree typecheck gate is active.
+        ...(typecheckGate?.installed ? { typecheck_gate: true } : {}),
     };
     fs.writeFileSync(path.join(targetPath, '.brainclaw-worktree.json'), JSON.stringify(meta, null, 2));
     return targetPath;
 }
+/** Directory (relative to a worktree root) holding the per-worktree git hooks. */
+export const WORKTREE_HOOKS_DIRNAME = '.brainclaw-hooks';
+/**
+ * The pre-commit gate body (pln#479). Runs via `node -e` — same SIGPIPE-avoiding
+ * pattern as install-hooks.ts. Git runs hooks with cwd = worktree root, so the
+ * relative paths resolve there. `node` and the tsc entry point are invoked with
+ * forward-slash relative paths to stay cross-platform (no quoting/backslash
+ * pitfalls). If typescript is absent the gate degrades to a warning rather than
+ * blocking — a tooling gap must not trap a worker.
+ */
+export function buildTypecheckPreCommitScript() {
+    return `#!/bin/sh
+# brainclaw worktree typecheck gate (pln#479) — do not edit manually.
+# Blocks the commit when 'tsc --noEmit' fails. Bypass: git commit --no-verify.
+exec node -e "
+const fs = require('fs');
+const { execSync } = require('child_process');
+if (!fs.existsSync('tsconfig.json')) process.exit(0);
+if (!fs.existsSync('node_modules/typescript/bin/tsc')) {
+  process.stderr.write('\\\\n[brainclaw] typecheck gate: typescript not found in worktree node_modules — skipping (commit allowed).\\\\n');
+  process.exit(0);
+}
+try {
+  execSync('node node_modules/typescript/bin/tsc --noEmit', { stdio: 'inherit' });
+} catch (e) {
+  process.stderr.write('\\\\n[brainclaw] commit blocked: tsc --noEmit reported type errors (above). Fix them, or bypass with: git commit --no-verify\\\\n\\\\n');
+  process.exit(1);
+}
+" 2>&1 || exit $?
+`;
+}
+/**
+ * pln#479 — install an ISOLATED pre-commit gate in a dispatched worktree that
+ * blocks a commit when `tsc --noEmit` fails, so a worker cannot land code that
+ * breaks the type-check (observed: workers committing strict-mode-broken TS that
+ * only blew up at merge/build time, pln#466).
+ *
+ * Isolation is the crux: git hooks are shared across all worktrees of a repo by
+ * default, so we must NOT write into the common hooks dir — that would impose
+ * tsc on the human's main-repo commits too. Instead we point THIS worktree's
+ * `core.hooksPath` at a worktree-local dir via the `--worktree` config scope
+ * (enabling `extensions.worktreeConfig`), which leaves the main repo's hook
+ * setup completely untouched and is torn down with the worktree.
+ *
+ * No-ops when the worktree has no `tsconfig.json`. Depends on pln#523 having
+ * linked `node_modules` so `tsc` resolves.
+ */
+export function installWorktreeTypecheckGate(mainWorktreePath, worktreePath) {
+    if (!fs.existsSync(path.join(worktreePath, 'tsconfig.json'))) {
+        return { installed: false, reason: 'no tsconfig.json — not a TypeScript worktree' };
+    }
+    try {
+        const hooksDir = path.join(worktreePath, WORKTREE_HOOKS_DIRNAME);
+        fs.mkdirSync(hooksDir, { recursive: true });
+        fs.writeFileSync(path.join(hooksDir, 'pre-commit'), buildTypecheckPreCommitScript(), {
+            encoding: 'utf-8',
+            mode: 0o755,
+        });
+        // Enable per-worktree config on the repo (idempotent, additive) so the
+        // hooksPath override stays scoped to THIS worktree only.
+        runGit(['config', 'extensions.worktreeConfig', 'true'], mainWorktreePath);
+        const set = runGit(['config', '--worktree', 'core.hooksPath', gitPath(hooksDir)], worktreePath);
+        if (!set.ok) {
+            return { installed: false, reason: `git config --worktree core.hooksPath failed: ${set.stderr.trim()}` };
+        }
+        return { installed: true };
+    }
+    catch (err) {
+        return { installed: false, reason: err instanceof Error ? err.message : String(err) };
+    }
+}
 /**
  * Lists all git worktrees for the given repo and enriches them with
  * brainclaw metadata if available.
@@ -510,6 +698,30 @@ export function removeWorktree(mainWorktreePath, worktreePath, options = {}) {
 export function pruneWorktrees(mainWorktreePath) {
     runGit(['worktree', 'prune'], mainWorktreePath);
 }
+/**
+ * Files brainclaw itself writes into a worktree AT BIRTH — they are never user
+ * work and must not count as "uncommitted changes" when deciding whether a
+ * merged worktree can be GC'd:
+ *   - `.gitignore`            — copied from the main repo by createWorktree; on
+ *                               Windows autocrlf flags it as ` M .gitignore`,
+ *                               which previously made EVERY brainclaw worktree
+ *                               look dirty and skipped the clean forever.
+ *   - `.brainclaw-worktree.json` — the sidecar metadata createWorktree writes.
+ * Combined with isSystemDirtyPath (.brainclaw/, .git/, agent config dirs).
+ */
+const WORKTREE_BIRTH_NOISE = new Set(['.gitignore', '.brainclaw-worktree.json']);
+/**
+ * True when a worktree's `git status --porcelain=v1 -z` output contains ONLY
+ * brainclaw birth artifacts / coordination-store noise — i.e. no real user work
+ * would be lost by removing it. Empty output (fully clean) also returns true.
+ */
+export function worktreeHasOnlyBirthNoise(statusZStdout) {
+    const paths = parsePorcelainZ(statusZStdout);
+    return paths.every((p) => {
+        const norm = p.replace(/\\/g, '/');
+        return WORKTREE_BIRTH_NOISE.has(norm) || isSystemDirtyPath(norm);
+    });
+}
 /**
  * Removes worktrees whose branch has been fully merged into the current branch
  * (typically master/main after a merge). Also removes brainclaw-managed
@@ -539,10 +751,13 @@ export function cleanMergedWorktrees(mainWorktreePath, options = {}) {
         if (!isMerged) {
             continue;
         }
-        // Check for uncommitted changes
+        // Check for uncommitted changes — but ignore brainclaw birth-noise
+        // (.gitignore autocrlf, the sidecar, coordination store). Without this,
+        // every merged brainclaw worktree looked dirty and was skipped forever,
+        // so `worktree clean` removed nothing and worktrees accumulated (pln#525).
         if (!options.force) {
-            const status = runGit(['status', '--porcelain'], wt.path);
-            if (status.ok && status.stdout.trim().length > 0) {
+            const status = runGit(['status', '--porcelain=v1', '-z', '--untracked-files=normal'], wt.path);
+            if (status.ok && !worktreeHasOnlyBirthNoise(status.stdout)) {
                 result.skipped.push({ path: wt.path, reason: 'uncommitted changes' });
                 continue;
             }
@@ -552,7 +767,12 @@ export function cleanMergedWorktrees(mainWorktreePath, options = {}) {
             continue;
         }
         try {
-            removeWorktree(mainWorktreePath, wt.path, { force: options.force });
+            // Reaching here means EITHER options.force OR the birth-noise gate above
+            // passed (no real user work). In both cases git's own `worktree remove`
+            // must be forced: otherwise it refuses on the untracked sidecar /
+            // autocrlf .gitignore that we already classified as discardable noise
+            // (pln#525 — the refusal that left every merged worktree un-GC-able).
+            removeWorktree(mainWorktreePath, wt.path, { force: true });
             result.removed.push(wt.path);
         }
         catch {

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.7.2 on 2026-06-04T21:46:11.832Z
+// Source: brainclaw v1.7.4 on 2026-06-08T21:59:54.110Z
 export const FACTS = {
-  "version": "1.7.2",
-  "generated_at": "2026-06-04T21:46:11.832Z",
+  "version": "1.7.4",
+  "generated_at": "2026-06-08T21:59:54.110Z",
   "tools": {
     "count": 62,
     "published_count": 61,

package/dist/facts.json

@@ -1,6 +1,6 @@
 {
-  "version": "1.7.2",
-  "generated_at": "2026-06-04T21:46:11.832Z",
+  "version": "1.7.4",
+  "generated_at": "2026-06-08T21:59:54.110Z",
   "tools": {
     "count": 62,
     "published_count": 61,

package/package.json

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