brainclaw 1.16.0 → 1.18.0

package/dist/core/runtime-signals.js

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

package/dist/core/schema.js

@@ -479,6 +479,13 @@ export const InboxMessageSchema = z.object({
     read_at: z.string().optional(),
     /** When the message was acknowledged */
     ack_at: z.string().optional(),
+    /** True when the body was truncated at WRITE time because it exceeded the
+     *  inline size cap (pln#627 Phase B). Unlike read-time previews, the omitted
+     *  tail is NOT stored inline — the full artifact belongs in a dedicated store
+     *  (e.g. ideation responses), with the message carrying only a pointer. */
+    truncated_at_write: z.boolean().optional(),
+    /** Original body length in characters before write-time truncation. */
+    original_text_length: z.number().int().nonnegative().optional(),
     created_at: z.string(),
     updated_at: z.string(),
     author: z.string(),
@@ -956,6 +963,9 @@ export const RuntimeEventTypeSchema = z.enum([
     'candidate_harvested',
     'lane_result_harvested',
     'lane_integrated',
+    // pln#521 P4 — a turn-owned loop artifact was harvested + integrated into the loop
+    // by reconcileTurn (observability for the harvest path).
+    'loop_artifact_harvested',
 ]);
 /**
  * pln#526 — LANE-RESULT convention. A dispatched worker writes a single
@@ -966,6 +976,16 @@ export const RuntimeEventTypeSchema = z.enum([
  */
 export const LaneResultSchema = z.object({
     assignment_id: z.string(),
+    /**
+     * pln#630 PR2b-a (§13 R2/R3) — turn-attempt correlation keys. Optional for
+     * backward compat (legacy lanes are assignment-keyed only); a loop-dispatched
+     * lane echoes all three so the read-strict acceptance path can prove WHICH
+     * attempt+generation produced this result. `nonce` == the consumed launch
+     * token (the epoch-unique generation id), NOT a turn_id-bound value.
+     */
+    turn_id: z.string().optional(),
+    run_id: z.string().optional(),
+    nonce: z.string().optional(),
     status: z.enum(['completed', 'blocked', 'failed']),
     summary: z.string(),
     /** Paths or refs the worker produced (commits, files, docs). */
@@ -999,6 +1019,10 @@ export const RuntimeEventSchema = z.object({
     tags: TagsWithDefaultSchema,
     assignment_id: z.string().optional(),
     run_id: z.string().optional(),
+    // pln#630 PR2b-a (§13 R2/R3) — turn-attempt correlation on runtime signals.
+    // `run_id` already present above; `nonce` == launch-generation token.
+    turn_id: z.string().optional(),
+    nonce: z.string().optional(),
     claim_id: z.string().optional(),
     message_id: z.string().optional(),
     plan_id: z.string().optional(),
@@ -1454,6 +1478,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.
@@ -1166,6 +1360,30 @@ export function isBranchMergedByContent(mainWorktreePath, branchName, baseRef =
     }
     return true;
 }
+/**
+ * True when a LOCAL git branch of this exact name exists (pln#529). Lets the
+ * gated-sequence base selector distinguish "predecessor branch gone (merged +
+ * cleaned → code is on HEAD)" from "branch present but not yet integrated →
+ * fork the dependent lane from it". Returns false on any git failure.
+ */
+export function localBranchExists(mainWorktreePath, branchName) {
+    return probeLocalBranch(mainWorktreePath, branchName) === 'present';
+}
+export function probeLocalBranch(mainWorktreePath, branchName) {
+    const r = runGit(['rev-parse', '--verify', '--quiet', `refs/heads/${branchName}`], mainWorktreePath);
+    if (r.ok)
+        return 'present';
+    return r.stderr.trim() === '' ? 'absent' : 'unknown';
+}
+/**
+ * True when `cwd` is inside a git work tree. pln#529 uses this to distinguish a
+ * NON-git project (where branch/worktree propagation is inapplicable — fall back
+ * to the legacy HEAD base) from a git repo whose branch probe transiently failed
+ * (which must fail SAFE, not silently assume HEAD).
+ */
+export function isGitRepo(cwd) {
+    return runGit(['rev-parse', '--is-inside-work-tree'], cwd).ok;
+}
 /**
  * Removes worktrees whose branch has been fully merged into the current branch
  * (typically master/main after a merge). Also removes brainclaw-managed

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.18.0 on 2026-07-31T14:51:44.969Z
 export const FACTS = {
-  "version": "1.16.0",
-  "generated_at": "2026-07-18T18:21:20.312Z",
+  "version": "1.18.0",
+  "generated_at": "2026-07-31T14:51:44.969Z",
   "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-31T14:51:42.799Z",
     "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": 81,
         "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": 142,
         "payload_chars_median": 2626,
         "payload_tokens_est_median": 657
       },
@@ -499,9 +499,9 @@ 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,
-        "payload_chars_median": 442,
-        "payload_tokens_est_median": 111
+        "duration_ms_median": 12,
+        "payload_chars_median": 499,
+        "payload_tokens_est_median": 125
       }
     ]
   }

package/dist/facts.json

@@ -1,6 +1,6 @@
 {
-  "version": "1.16.0",
-  "generated_at": "2026-07-18T18:21:20.312Z",
+  "version": "1.18.0",
+  "generated_at": "2026-07-31T14:51:44.969Z",
   "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-31T14:51:42.799Z",
     "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": 81,
         "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": 142,
         "payload_chars_median": 2626,
         "payload_tokens_est_median": 657
       },
@@ -497,9 +497,9 @@
         "name": "first_edit",
         "volume": "medium",
         "description": "code_find + code_brief on the fresh-agent path (missing index, first touch).",
-        "duration_ms_median": 9,
-        "payload_chars_median": 442,
-        "payload_tokens_est_median": 111
+        "duration_ms_median": 12,
+        "payload_chars_median": 499,
+        "payload_tokens_est_median": 125
       }
     ]
   }

package/docs/cli.md

@@ -2011,7 +2011,7 @@ The default catalog is intentionally small and centred on the canonical grammar.
 |---|---|
 | `bclaw_coordinate(intent)` | Assign, consult, review, reroute, or summarize across agents. Pass `open_loop: true` on `intent="review"` to also dispatch the reviewer turn. |
 | `bclaw_dispatch(intent)` | Parallelize execute across a sequence's lanes (analysis / execute / review). |
-| `bclaw_loop(intent)` | Drive a turn in an existing multi-turn loop (`turn`, `complete_turn`, `advance`, `close`). Do not call `bclaw_loop(intent="open")` directly without dispatch — use `bclaw_coordinate(intent="review", open_loop: true)` instead. |
+| `bclaw_loop(intent)` | Drive a turn in an existing multi-turn loop (`turn`, `complete_turn`, `advance`, `close`; implementation loops add `bind` to dispatch the linked sequence and `verify` to run the opener-configured `command_green` check). Do not call `bclaw_loop(intent="open")` directly without dispatch — use `bclaw_coordinate(intent="review", open_loop: true)` instead. |
 
 **Sequences**:
 

package/docs/code-map.md

@@ -1,7 +1,8 @@
 # Code Map
 
-Code Map is a per-project structural index of your JavaScript / TypeScript / JSX /
-TSX, Python, PHP, and Java codebase. It parses each supported file with Tree-sitter and records the
+Code Map is a per-project structural index of your codebase across 11 languages:
+JavaScript / TypeScript (including JSX / TSX), Python, PHP, Java, Go, Rust, C#,
+Ruby, C, and C++. It parses each supported file with Tree-sitter and records the
 symbols it defines (functions, classes, types, interfaces, React components and
 hooks), what it imports and exports, and how files relate — then answers fast
 "what should I read before I edit this?" questions for both human operators and
@@ -201,11 +202,24 @@ single-project repos ignore the flag entirely.
 which nested projects have a built index vs `missing_index`, plus an aggregate
 count — so you can see workspace-wide freshness from the root.
 
+### Workspace-wide `find` / `brief`
+
+Once the per-child indexes exist (built by `--cascade`), `find` and `brief` run
+at a multi-project workspace **root** automatically aggregate across every child
+project's store — no flag needed. Matches are project-tagged with
+workspace-relative paths, and the freshness badge merges per-store status (worst
+status wins) plus coverage (how many projects are indexed, listing any unindexed
+children). An aggregated `brief` also surfaces **cross-package reverse
+dependents**: sibling packages that import the defining package's public name
+rank into the reading list, flagged `cross_package`.
+
+From **inside** a child project, reads stay single-store by default (locality).
+An explicit `traversal: "workspace"` (backend option) walks up to the nearest
+enclosing multi-project root and aggregates from there, with the caller's own
+package ranked first (`local: true` on its rows).
+
 **Not yet supported** (roadmap):
 
-- A single **federated query** at the root that fans out across the per-child
-  indexes and merges the results (today, `--cascade` builds the per-child indexes;
-  `find` / `brief` still run against one store at a time).
 - **Cross-service edges** — e.g. linking an API call to the route that defines it in
   another service. Code Map indexes language *symbols* and *module imports*, not
   framework routes or runtime HTTP calls, so it does not (today) map "service A calls
@@ -215,7 +229,9 @@ count — so you can see workspace-wide freshness from the root.
 
 The parser is [Tree-sitter](https://tree-sitter.github.io/) compiled to
 WebAssembly. The engine glue (`web-tree-sitter`) and the prebuilt grammar `.wasm`
-files (JavaScript / TypeScript / JSX / TSX, Python, PHP, Java) are **bundled into the package** during the
+files — 12 grammars covering the 11 supported languages: `javascript` (also
+handles JSX), `typescript`, `tsx`, `python`, `php`, `java`, `go`, `rust`,
+`c_sharp`, `ruby`, `c`, `cpp` — are **bundled into the package** during the
 build (`scripts/copy-code-map-wasm.mjs` copies them into `dist/wasm/` and vendors
 the engine glue into `dist/vendor/web-tree-sitter/`).