brainclaw 1.9.1 → 1.10.0

package/dist/core/code-map/vocabulary.js

@@ -0,0 +1,57 @@
+/**
+ * Brainclaw Code Map — universal vocabulary (spec §5, dec#108 #4).
+ *
+ * Defines the cross-language universal node-subtype and edge-kind sets, plus
+ * the namespacing rule for provider-specific extensions. A `NodeSubtype` /
+ * `EdgeKind` is EITHER one of the universal values OR a lowercase,
+ * provider-prefixed namespaced value of the form `provider.subtype`
+ * (e.g. `rust.trait`). The matching runtime validator lives in `types.ts`.
+ *
+ * P1a emits ONLY the existing universal values — providers MUST NOT introduce
+ * new universal subtypes/edge kinds here without a spec change.
+ */
+/**
+ * Universal symbol subtypes shared across every language provider (spec §5).
+ * Ordering is documentary only; nothing depends on array order.
+ */
+export const UniversalNodeSubtypes = [
+    'function',
+    'method',
+    'constructor',
+    'class',
+    'type',
+    'interface',
+    'enum',
+    'variable',
+    'constant',
+    'field',
+    'property',
+    'namespace',
+    'package',
+    'component',
+    'hook',
+    'test',
+    'test_suite',
+    'macro',
+    'export',
+];
+/**
+ * Universal edge kinds shared across every language provider (spec §5).
+ * Ordering is documentary only; nothing depends on array order.
+ */
+export const UniversalEdgeKinds = [
+    'contains',
+    'defines',
+    'imports',
+    'exports',
+    'resolves_to',
+    'imports_symbol',
+    'tests_for',
+    'extends',
+    'implements',
+    'annotates',
+    'has_receiver',
+];
+/** Regex used by `types.ts` to validate provider-namespaced vocabulary values. */
+export const NAMESPACED_VOCAB_RE = /^[a-z]+\.[a-z_]+$/;
+//# sourceMappingURL=vocabulary.js.map

package/dist/core/code-map/wasm-loader.js

@@ -0,0 +1,294 @@
+/**
+ * Tree-sitter WASM engine + grammar loader (spec §6.2).
+ *
+ * Decided design points (spec §6.2):
+ *  - web-tree-sitter is the engine glue (vendored into dist/vendor/; copied to
+ *    dist/wasm/ alongside the grammar .wasm by scripts/copy-code-map-wasm.mjs).
+ *  - Grammar .wasm (typescript / tsx / javascript) ship under dist/wasm/.
+ *  - All assets are resolved by `new URL('./wasm/<file>.wasm', import.meta.url)`
+ *    — NEVER cwd/__dirname — so the loader is worktree-safe under ESM.
+ *  - Lazy-load on FIRST PARSE only. CRITICAL: the web-tree-sitter *JS glue* is a
+ *    devDependency, so it is NEVER imported at module-load time — a static import
+ *    would sit in the eager graph of cli.js / mcp.js and brick the ENTIRE CLI on
+ *    a published package (devDeps dropped) even for `--version` / find / brief /
+ *    status. Instead the glue is loaded via a DYNAMIC import inside `initEngine()`
+ *    (the first-parse init path), preferring the VENDORED copy at
+ *    `dist/vendor/web-tree-sitter/tree-sitter.js` (resolved via import.meta.url,
+ *    bundled by scripts/copy-code-map-wasm.mjs) so the published package works at
+ *    parse time too; it falls back to the bare 'web-tree-sitter' specifier when
+ *    the vendored copy is absent (running from source).
+ *  - `Parser.init()` runs once per process; each grammar `Language` is loaded
+ *    only when a file of that language appears, then cached. Nothing here runs at
+ *    import time or on the query path.
+ *  - Hashes: `engineGlueHash()` = sha256 of the vendored engine .wasm;
+ *    `grammarHash(lang)` = sha256 of the grammar .wasm. These feed manifest /
+ *    shard freshness and are kept SEPARATE from extractor_config_hash.
+ *
+ * Packaging fallback: if the dist/wasm/ bundle is absent (e.g. running from
+ * source before the copy step has run, or the fallback packaging path), the
+ * loader resolves the .wasm assets from the installed node_modules
+ * devDependencies via `createRequire`. This keeps parse logic + tests working
+ * regardless of whether the dist bundling step has executed.
+ */
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+/** Grammar packages keyed by Code Map language tag. */
+const GRAMMAR_WASM_BASENAME = {
+    javascript: 'tree-sitter-javascript.wasm',
+    typescript: 'tree-sitter-typescript.wasm',
+    tsx: 'tree-sitter-tsx.wasm',
+};
+/** node_modules fallback paths (resolved lazily; only used if dist bundle absent). */
+const GRAMMAR_NODE_MODULES_SPEC = {
+    javascript: 'tree-sitter-wasms/out/tree-sitter-javascript.wasm',
+    typescript: 'tree-sitter-wasms/out/tree-sitter-typescript.wasm',
+    tsx: 'tree-sitter-wasms/out/tree-sitter-tsx.wasm',
+};
+const ENGINE_WASM_BASENAME = 'tree-sitter.wasm';
+const ENGINE_NODE_MODULES_SPEC = 'web-tree-sitter/tree-sitter.wasm';
+/**
+ * Narrow a runtime `CodeLang` onto the js-ts grammar key. `jsx` uses the tsx
+ * grammar (a strict superset of jsx + js). Any lang outside the js-ts set is not
+ * something THIS loader serves (it is some other provider's grammar) — default to
+ * `typescript` to stay total, matching the legacy fall-through behavior.
+ */
+function grammarLangFor(lang) {
+    switch (lang) {
+        case 'javascript':
+        case 'typescript':
+        case 'tsx':
+            return lang;
+        case 'jsx':
+            return 'tsx';
+        default:
+            return 'typescript';
+    }
+}
+/**
+ * Resolve a bundled wasm asset path. Prefers `dist/wasm/<basename>` resolved
+ * relative to THIS module via import.meta.url; falls back to the node_modules
+ * devDependency when the dist bundle is not present.
+ */
+function resolveWasmPath(distBasename, nodeModulesSpec) {
+    // dist-bundled location: <module dir>/wasm/<basename>. At runtime this module
+    // is dist/core/code-map/wasm-loader.js, so '../../wasm/<basename>' === dist/wasm/.
+    try {
+        const bundled = fileURLToPath(new URL(`../../wasm/${distBasename}`, import.meta.url));
+        if (fs.existsSync(bundled))
+            return bundled;
+    }
+    catch {
+        /* fall through to node_modules */
+    }
+    // node_modules fallback (devDependency). Keeps parse logic + tests working
+    // even before the dist copy step has run.
+    return require.resolve(nodeModulesSpec);
+}
+function readWasm(path) {
+    return new Uint8Array(fs.readFileSync(path));
+}
+// --- generic grammar loader (shared engine seam for non-js-ts providers) ---
+//
+// P1b §3 (rule-of-two): a 2nd provider (Python) loads a grammar this js-ts loader
+// does NOT own. Its grammar MUST come through the SAME initialized engine glue
+// (getParser/getQueryClass/initEngine) — a fresh `web-tree-sitter` import is a
+// distinct Emscripten instance and crashes on Query construction (trp_8df65ab7).
+// These generic helpers expose exactly that: load/hash an arbitrary grammar .wasm
+// (by dist basename + node_modules fallback spec) against the live engine. They are
+// engine SEAMS, not orchestration — a new provider calls them from its own dir.
+/** Cache for grammars loaded via the generic loader, keyed by dist basename. */
+const genericGrammarCache = new Map();
+const genericGrammarHashCache = new Map();
+/**
+ * Load (and cache) an arbitrary grammar Language by its dist basename + a
+ * node_modules fallback spec, using the SAME engine glue + init as the js-ts
+ * grammars. Lazy: only called from a provider's parse path.
+ */
+export async function loadGrammarWasm(distBasename, nodeModulesSpec) {
+    const cached = genericGrammarCache.get(distBasename);
+    if (cached)
+        return cached;
+    await initEngine();
+    const glue = await loadEngineGlue();
+    const wasmPath = resolveWasmPath(distBasename, nodeModulesSpec);
+    const bytes = readWasm(wasmPath);
+    if (!genericGrammarHashCache.has(distBasename)) {
+        genericGrammarHashCache.set(distBasename, sha256(bytes));
+    }
+    const language = await glue.Language.load(bytes);
+    genericGrammarCache.set(distBasename, language);
+    return language;
+}
+/** sha256 of an arbitrary grammar .wasm (per-language tree_sitter_grammar_hash). */
+export function grammarHashForWasm(distBasename, nodeModulesSpec) {
+    const cached = genericGrammarHashCache.get(distBasename);
+    if (cached)
+        return cached;
+    const wasmPath = resolveWasmPath(distBasename, nodeModulesSpec);
+    const h = sha256(readWasm(wasmPath));
+    genericGrammarHashCache.set(distBasename, h);
+    return h;
+}
+let glueModule = null;
+let glueLoadPromise = null;
+/**
+ * Dynamically import the web-tree-sitter JS glue on FIRST PARSE only. Prefers the
+ * vendored copy bundled into dist/vendor/web-tree-sitter/tree-sitter.js (resolved
+ * relative to this module via import.meta.url) so a published package — which has
+ * dropped the web-tree-sitter devDependency — still parses. Falls back to the
+ * bare 'web-tree-sitter' specifier when the vendored copy is absent (running from
+ * source / tests against node_modules).
+ *
+ * This function is the ONLY place that pulls web-tree-sitter into the runtime
+ * graph, and it runs strictly inside the parse path — so cli.js / mcp.js module
+ * load (and find / brief / status, which never parse) work with the engine glue
+ * entirely absent.
+ */
+async function loadEngineGlue() {
+    if (glueModule)
+        return glueModule;
+    if (glueLoadPromise)
+        return glueLoadPromise;
+    glueLoadPromise = (async () => {
+        // Vendored copy: <module dir>/../../vendor/web-tree-sitter/tree-sitter.js.
+        // At runtime this module is dist/core/code-map/wasm-loader.js, so
+        // '../../vendor/...' === dist/vendor/...
+        let mod;
+        const vendored = new URL('../../vendor/web-tree-sitter/tree-sitter.js', import.meta.url);
+        let vendoredExists = false;
+        try {
+            vendoredExists = fs.existsSync(fileURLToPath(vendored));
+        }
+        catch {
+            vendoredExists = false;
+        }
+        if (vendoredExists) {
+            mod = (await import(vendored.href));
+        }
+        else {
+            // Fallback: bare specifier (node_modules devDependency). On a published
+            // package without the vendored copy this would throw — but the copy script
+            // always vendors the glue, so this branch is the from-source/tests path.
+            mod = (await import('web-tree-sitter'));
+        }
+        glueModule = mod;
+        return mod;
+    })();
+    return glueLoadPromise;
+}
+/**
+ * Parser constructor from the lazily-loaded engine glue (parse path only). Awaits
+ * {@link initEngine} first so any caller constructs a parser off an INITIALIZED
+ * engine — a parser built before `Parser.init()` would brick on first use.
+ */
+export async function getParser() {
+    await initEngine();
+    const glue = await loadEngineGlue();
+    return glue.Parser;
+}
+/**
+ * `Query` constructor from the SAME lazily-loaded engine glue module that
+ * {@link initEngine}/{@link loadGrammar} run against, with the engine initialized
+ * first. CRITICAL: web-tree-sitter is shipped as a vendored copy under
+ * `dist/vendor/` AND exists as a node_modules devDependency; a fresh
+ * `import('web-tree-sitter')` resolves to a DISTINCT Emscripten module instance
+ * whose `Module` is never initialized by our `Parser.init({wasmBinary})` call.
+ * Constructing a `Query` against that un-inited instance throws
+ * `Cannot read properties of undefined (reading 'lengthBytesUTF8')`. Sourcing
+ * `Query` from `loadEngineGlue()` (same instance, after `initEngine()`) is the
+ * only correct path. (Regression fixed: P1a real-refresh WASM bug.)
+ */
+export async function getQueryClass() {
+    await initEngine();
+    const glue = await loadEngineGlue();
+    return glue.Query;
+}
+function sha256(bytes) {
+    return `sha256:${crypto.createHash('sha256').update(bytes).digest('hex')}`;
+}
+// --- Engine init (once per process) ---
+let enginePath = null;
+let engineInitPromise = null;
+function engineWasmPath() {
+    if (enginePath === null) {
+        enginePath = resolveWasmPath(ENGINE_WASM_BASENAME, ENGINE_NODE_MODULES_SPEC);
+    }
+    return enginePath;
+}
+/**
+ * Initialize the Tree-sitter engine exactly once per process. The engine .wasm
+ * binary is read explicitly and passed via `wasmBinary` so we never depend on
+ * emscripten's cwd/script-dir resolution (worktree-safe).
+ */
+export function initEngine() {
+    if (!engineInitPromise) {
+        engineInitPromise = (async () => {
+            const glue = await loadEngineGlue();
+            const wasmBinary = readWasm(engineWasmPath());
+            await glue.Parser.init({ wasmBinary });
+        })();
+    }
+    return engineInitPromise;
+}
+// --- Grammar cache (lazy, per language) ---
+const grammarCache = new Map();
+const grammarHashCache = new Map();
+/**
+ * Load (and cache) the grammar Language for a Code Map language. Initializes the
+ * engine first if needed. Lazy: only called from the parse loop.
+ */
+export async function loadGrammar(lang) {
+    const key = grammarLangFor(lang);
+    const cached = grammarCache.get(key);
+    if (cached)
+        return cached;
+    await initEngine();
+    const glue = await loadEngineGlue();
+    const path = resolveWasmPath(GRAMMAR_WASM_BASENAME[key], GRAMMAR_NODE_MODULES_SPEC[key]);
+    const bytes = readWasm(path);
+    if (!grammarHashCache.has(key))
+        grammarHashCache.set(key, sha256(bytes));
+    const language = await glue.Language.load(bytes);
+    grammarCache.set(key, language);
+    return language;
+}
+/** sha256 of the vendored engine glue .wasm (manifest.engine_glue_hash). */
+export function engineGlueHash() {
+    return sha256(readWasm(engineWasmPath()));
+}
+/** sha256 of a grammar .wasm (per-language tree_sitter_grammar_hash). */
+export function grammarHash(lang) {
+    const key = grammarLangFor(lang);
+    const cached = grammarHashCache.get(key);
+    if (cached)
+        return cached;
+    const path = resolveWasmPath(GRAMMAR_WASM_BASENAME[key], GRAMMAR_NODE_MODULES_SPEC[key]);
+    const h = sha256(readWasm(path));
+    grammarHashCache.set(key, h);
+    return h;
+}
+/** Map of canonical grammar names per language (manifest.languages.*). */
+export const GRAMMAR_NAMES = {
+    javascript: 'tree-sitter-javascript',
+    typescript: 'tree-sitter-typescript',
+    tsx: 'tree-sitter-tsx',
+};
+export function grammarName(lang) {
+    return GRAMMAR_NAMES[grammarLangFor(lang)];
+}
+/** Test/maintenance seam: drop cached engine + grammars (not used in hot paths). */
+export function __resetWasmCaches() {
+    grammarCache.clear();
+    grammarHashCache.clear();
+    genericGrammarCache.clear();
+    genericGrammarHashCache.clear();
+    engineInitPromise = null;
+    enginePath = null;
+    // NOTE: glueModule / glueLoadPromise are intentionally NOT reset — the dynamic
+    // import is process-global and re-importing is unnecessary; Parser.init is the
+    // re-runnable seam (gated by engineInitPromise above).
+}
+//# sourceMappingURL=wasm-loader.js.map

package/dist/core/code-map/work-section.js

@@ -0,0 +1,206 @@
+/**
+ * Code Map ↔ bclaw_work integration seam (spec §10).
+ *
+ * This is the ONLY place bclaw_work touches Code Map. It is strictly opt-in:
+ * the section is produced only when the Code Map manifest carries
+ * `code_map_enabled: true`. When the flag is off (the P0 default, and the case
+ * for any project without a Code Map store), the helper returns `null` after a
+ * single cheap manifest stat — it never parses, never refreshes, never blocks,
+ * so bclaw_work latency is unchanged for the off path.
+ *
+ * Behaviour when enabled (spec §10 rules):
+ *  - NEVER triggers a full (or any) refresh during bclaw_work.
+ *  - Index missing  -> a short `missing_index` hint (no results).
+ *  - Index stale    -> serve the find() results WITH the stale freshness badge.
+ *  - Lock active    -> wait at most `max_query_wait_ms` (default 2500ms) for the
+ *                      lock to clear; if it does not, serve last-known results if
+ *                      available, else skip with a `partial` badge. Never blocks
+ *                      bclaw_work beyond that bounded wait (rule §6 rule 8).
+ */
+import { readManifest } from './store.js';
+import { readCodeLock, isLockAbandoned } from './lock.js';
+import { codeMapDir, lockPath } from './paths.js';
+import { JsonlBackend } from './backend.js';
+/** Hard ceiling on how long the work-section may wait on an active lock (§6 rule 7, §10). */
+export const WORK_SECTION_MAX_WAIT_MS = 2500;
+/** Poll interval while waiting for a live lock to clear. */
+const LOCK_POLL_MS = 100;
+function defaultSleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Is a competing Code Map lock currently *live* (not abandoned)? A live lock
+ * means a refresh is in flight; we must not read mid-write as fresh.
+ */
+function liveLockPresent(opts) {
+    const lock = readCodeLock(opts.cwd, opts.preferredDirName);
+    if (!lock)
+        return false;
+    const now = (opts.now ?? Date.now)();
+    // Reuse the §5.8 abandonment evaluation; an abandoned lock does not block.
+    const storeDir = codeMapDir(opts.cwd, opts.preferredDirName);
+    const lockFile = lockPath(opts.cwd, opts.preferredDirName);
+    try {
+        const abandoned = isLockAbandoned(lock, {
+            now,
+            isPidAlive: opts.isPidAlive ?? ((pid) => {
+                if (!Number.isInteger(pid) || pid <= 0)
+                    return false;
+                try {
+                    process.kill(pid, 0);
+                    return true;
+                }
+                catch {
+                    return false;
+                }
+            }),
+            storeDir,
+            lockFile,
+        });
+        return !abandoned;
+    }
+    catch {
+        // If we cannot evaluate, treat as live (conservative): wait then degrade.
+        return true;
+    }
+}
+/**
+ * Build the opt-in Code Map section for a bclaw_work response, or `null` when
+ * Code Map is not enabled for this project. See the module header for the full
+ * behaviour contract (spec §10).
+ *
+ * The single live call-site is `bclaw_work` in src/commands/mcp.ts — search for
+ * `codeMapWorkSection(`.
+ */
+export async function codeMapWorkSection(cwd, opts = {}) {
+    const ctx = { ...opts, cwd: opts.cwd ?? cwd };
+    // OFF PATH: one cheap manifest stat. No store / flag off -> nothing at all.
+    const manifest = readManifest(ctx.cwd, ctx.preferredDirName);
+    if (!manifest || manifest.code_map_enabled !== true) {
+        return null;
+    }
+    const backend = ctx.backend ?? new JsonlBackend();
+    const query = (ctx.query ?? '').trim();
+    const limit = ctx.limit ?? 8;
+    // LOCK PATH: bounded wait for an active (live) lock to clear (§10).
+    let lockWaitMs;
+    if (liveLockPresent(ctx)) {
+        const sleep = ctx.sleep ?? defaultSleep;
+        const now = ctx.now ?? Date.now;
+        const deadline = now() + WORK_SECTION_MAX_WAIT_MS;
+        while (now() < deadline && liveLockPresent(ctx)) {
+            await sleep(LOCK_POLL_MS);
+        }
+        lockWaitMs = WORK_SECTION_MAX_WAIT_MS - Math.max(0, deadline - now());
+        if (liveLockPresent(ctx)) {
+            // Still locked after the bounded wait — degrade to partial. Serve
+            // last-known matches if a query is present and the index is readable,
+            // else skip the section content with a partial badge. Never block.
+            if (query) {
+                try {
+                    const out = await backend.find({
+                        query,
+                        limit,
+                        cwd: ctx.cwd,
+                        preferredDirName: ctx.preferredDirName,
+                    });
+                    return {
+                        enabled: true,
+                        matches: out.matches,
+                        freshness_badge: {
+                            status: 'partial',
+                            details: { partial_reason: 'code_map_lock_active', lock_wait_ms: lockWaitMs },
+                        },
+                        lock_wait_ms: lockWaitMs,
+                    };
+                }
+                catch {
+                    /* fall through to skip */
+                }
+            }
+            return {
+                enabled: true,
+                matches: [],
+                freshness_badge: {
+                    status: 'partial',
+                    details: { partial_reason: 'code_map_lock_active', lock_wait_ms: lockWaitMs },
+                },
+                lock_wait_ms: lockWaitMs,
+            };
+        }
+    }
+    // MISSING INDEX: nothing parsed yet (spec §10). Short hint, no results.
+    if (manifest.freshness.status === 'missing_index') {
+        return {
+            enabled: true,
+            missing_index: 'Code Map index is empty for this project. Run `brainclaw code-map refresh --all` (or bclaw_code_refresh) before relying on find/brief.',
+            matches: [],
+            freshness_badge: { status: 'missing_index', details: {} },
+            ...(lockWaitMs !== undefined ? { lock_wait_ms: lockWaitMs } : {}),
+        };
+    }
+    // FRESH or STALE: run find() (read-only, never refreshes). The backend's
+    // lazy read-path check (§6.1) returns the true freshness badge, so stale
+    // results are surfaced WITH the stale badge rather than hidden.
+    if (!query) {
+        return {
+            enabled: true,
+            matches: [],
+            freshness_badge: {
+                status: manifest.freshness.status,
+                details: {
+                    stale_file_count: manifest.freshness.stale_file_count,
+                    partial_reason: manifest.freshness.partial_reason,
+                },
+            },
+            ...(lockWaitMs !== undefined ? { lock_wait_ms: lockWaitMs } : {}),
+        };
+    }
+    const out = await backend.find({
+        query,
+        limit,
+        cwd: ctx.cwd,
+        preferredDirName: ctx.preferredDirName,
+    });
+    return {
+        enabled: true,
+        matches: out.matches,
+        freshness_badge: out.freshness_badge,
+        ...(lockWaitMs !== undefined ? { lock_wait_ms: lockWaitMs } : {}),
+    };
+}
+/**
+ * Derive the onboarding/freshness next_action(s) from a Code Map work section
+ * (pln#588 adoption). The passive `missing_index` hint string was easy for agents
+ * to skip; promoting the refresh to a first-class `next_action` makes a fresh or
+ * stale project's first `bclaw_work` actively nudge the agent to build/update the
+ * index — without ever refreshing here. Pure + side-effect-free so it can be
+ * unit-locked; the bclaw_work handler spreads the result into its next_actions.
+ *  - missing_index -> build the whole index (`scope: all`)
+ *  - stale_*       -> refresh changed files (`scope: changed`)
+ *  - fresh/partial/null -> nothing (don't nag on a usable index or a transient lock)
+ */
+export function codeMapRefreshNextActions(section) {
+    if (!section)
+        return [];
+    if (section.missing_index) {
+        return [
+            {
+                tool: 'bclaw_code_refresh',
+                args: { scope: 'all' },
+                when: 'Code Map index is empty — build it so bclaw_code_find/brief can orient you before editing',
+            },
+        ];
+    }
+    if (section.freshness_badge?.status?.startsWith('stale_')) {
+        return [
+            {
+                tool: 'bclaw_code_refresh',
+                args: { scope: 'changed' },
+                when: 'Code Map is stale — refresh changed files before relying on bclaw_code_find/brief',
+            },
+        ];
+    }
+    return [];
+}
+//# sourceMappingURL=work-section.js.map

package/dist/core/codev-rounds.js

@@ -7,6 +7,7 @@
 import { saveIdeationRound, loadIdeationRound, listIdeationRounds } from './ideation.js';
 import { recordResponse } from './codev-metrics.js';
 import { buildPositionPrompt, buildReactionPrompt, buildConvergencePrompt } from './codev-prompts.js';
+import { buildWorkerIdentityEnv } from './execution-profile.js';
 import { spawn, spawnSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
@@ -55,6 +56,9 @@ function spawnAgent(binaryPath, agentName, prompt, personaName, cwd, outputFile,
         detached: true,
         stdio: ['ignore', outFd, 'ignore'],
         cwd,
+        // F7 (trp_0e5150d3): scrub coordinator identity — this spawn previously
+        // inherited the full parent env.
+        env: buildWorkerIdentityEnv(process.env, { agent: agentName }),
     });
     child.on('error', (err) => {
         console.warn(`  ⚠ Spawn error for ${agentName}/${personaName}: ${err.message}`);

package/dist/core/execution-adapters.js

@@ -1,7 +1,7 @@
 import { spawn, execFileSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
-import { buildClaimEnvPrefix } from './execution-profile.js';
+import { buildClaimEnvPrefix, buildWorkerIdentityEnv } from './execution-profile.js';
 import { getCapabilityProfile } from './agent-capability.js';
 import { nowISO } from './ids.js';
 import { ensureRuntimeDirs, getRuntimeLogPath, getRuntimeSignalPath, } from './runtime-signals.js';
@@ -97,15 +97,16 @@ export class CliExecutionAdapter {
     }
     start(invoke, options) {
         const isWin32 = process.platform === 'win32';
-        const env = {
-            ...process.env,
-            // pln#562 step 5 — truthful attribution: every commit a dispatched
-            // worker makes is authored as the AGENT, not as the human whose
-            // git config happens to be on the machine. invoke.env may override.
-            ...buildGitAttributionEnv(options.agent),
-            ...(invoke.env ?? {}),
-            ...(options.claimId ? { BRAINCLAW_CLAIM_ID: options.claimId } : {}),
-        };
+        // F7 (trp_0e5150d3): route worker env through buildWorkerIdentityEnv so the
+        // worker is an independent agent — coordinator identity (BRAINCLAW_AGENT*,
+        // SESSION_ID, PROJECT) is scrubbed LAST and cannot be reintroduced by
+        // invoke.env. pln#562 step 5 — truthful git attribution (worker authors its
+        // own commits) is merged before the scrub. BRAINCLAW_CWD is preserved (D1a).
+        const env = buildWorkerIdentityEnv(process.env, {
+            agent: options.agent,
+            claimId: options.claimId,
+            extraEnv: { ...buildGitAttributionEnv(options.agent), ...(invoke.env ?? {}) },
+        });
         if (invoke.promptDelivery === 'temp_file' && invoke.tempFilePath && invoke.promptText) {
             const dir = path.dirname(invoke.tempFilePath);
             if (!fs.existsSync(dir))

package/dist/core/execution-profile.js

@@ -247,6 +247,64 @@ export function buildClaimEnvPrefix(claimId, options) {
         default: return `BRAINCLAW_CLAIM_ID=${claimId} `;
     }
 }
+/**
+ * F7 (trp_0e5150d3): build the env for a SPAWNED worker so it is an INDEPENDENT
+ * agent, not a clone of the coordinator. The coordinator's process.env carries
+ * identity-bearing state (BRAINCLAW_AGENT*, BRAINCLAW_SESSION_ID, BRAINCLAW_PROJECT);
+ * inherited by an MCP-capable worker it would make the worker read/mutate the
+ * coordinator's session-scoped active project and identify AS the coordinator.
+ *
+ * Merge order (Codex cadrage review — batch 2): baseEnv → extraEnv (git
+ * attribution + invoke.env) → worker identity (agent name, claim) → SCRUB the
+ * forbidden coordinator keys LAST, so a deliberate or accidental extraEnv cannot
+ * reintroduce them. This helper is the SINGLE place worker env is built; every
+ * agent-spawn site must route through it.
+ *
+ * BRAINCLAW_CWD is intentionally PRESERVED (D1 = (a)): a worker's worktree lives
+ * outside the monorepo and has no .brainclaw, so it must anchor to the shared
+ * monorepo-root store the coordinator pointed at; the claim scopes the work. A
+ * caller override via extraEnv.BRAINCLAW_CWD is honoured (deliberate, not leaked).
+ */
+export function buildWorkerIdentityEnv(baseEnv, options = {}) {
+    const env = {};
+    for (const [key, value] of Object.entries(baseEnv)) {
+        if (typeof value === 'string')
+            env[key] = value;
+    }
+    if (options.extraEnv) {
+        for (const [key, value] of Object.entries(options.extraEnv)) {
+            if (typeof value === 'string')
+                env[key] = value;
+        }
+    }
+    // Worker identity — truthful attribution, mirrors buildGitAttributionEnv.
+    const agent = options.agent?.trim();
+    if (agent) {
+        env.BRAINCLAW_AGENT = agent;
+        env.BRAINCLAW_AGENT_NAME = agent;
+    }
+    else {
+        // No target agent → don't leak the coordinator's identity either.
+        delete env.BRAINCLAW_AGENT;
+        delete env.BRAINCLAW_AGENT_NAME;
+    }
+    // Claim ownership is explicit: adopt the supplied claim, otherwise DELETE any
+    // inherited parent BRAINCLAW_CLAIM_ID so an unclaimed/dry-run worker (e.g. the
+    // codev/codev-rounds call sites that pass only { agent }) never adopts the
+    // coordinator's claim (Codex final review F7 finding).
+    if (options.claimId && options.claimId !== '(dry-run)') {
+        env.BRAINCLAW_CLAIM_ID = options.claimId;
+    }
+    else {
+        delete env.BRAINCLAW_CLAIM_ID;
+    }
+    // SCRUB LAST — coordinator identity must never survive into the worker, even if
+    // baseEnv or extraEnv set it. (BRAINCLAW_CWD is deliberately NOT scrubbed.)
+    delete env.BRAINCLAW_AGENT_ID;
+    delete env.BRAINCLAW_SESSION_ID;
+    delete env.BRAINCLAW_PROJECT;
+    return env;
+}
 // ── Verification helper (used by setup / doctor) ───────────────────────────
 /**
  * Try `node --version` from the resolved profile's `node_path` to confirm