brainclaw 1.9.1 → 1.10.1

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

package/dist/core/facade-schema.js

@@ -196,5 +196,14 @@ export const FacadeResponseSchema = z.object({
      * remains for the bootstrap hint; new consumers should read this array.
      */
     next_actions: z.array(NextActionSchema).optional(),
+    /**
+     * Code Map P0 (spec §10): opt-in, present ONLY when the project's Code Map
+     * manifest carries `code_map_enabled: true`. Absent for every project that
+     * has not turned Code Map on (the P0 default), so existing bclaw_work callers
+     * are unaffected and the off-path adds no work. Shape mirrors
+     * CodeMapWorkSection: { enabled, matches, freshness_badge, missing_index?,
+     * lock_wait_ms? }. Passthrough so the section can evolve without a schema bump.
+     */
+    code_map: z.object({}).passthrough().optional(),
 });
 //# sourceMappingURL=facade-schema.js.map

package/dist/core/ids.js

@@ -48,7 +48,7 @@ export function getNextShortLabel(prefix, cwd, preferredDirName) {
         }
         catch (error) {
             if (!(error instanceof Error) || !('code' in error) || error.code !== 'ENOENT') {
-                throw new Error(`Could not read short-label counter ${fp}: ${error instanceof Error ? error.message : String(error)}`);
+                throw new Error(`Could not read short-label counter ${fp}: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
             }
         }
         const next = (counter[prefix] ?? 0) + 1;

package/dist/core/instruction-templates.js

@@ -233,6 +233,7 @@ function renderSessionProtocol() {
         '1. Call `bclaw_work(intent)` (consult|execute|resume|review) — one call handles session, context, and claim (execute). Every response carries `next_actions` with the exact follow-up calls: follow those instead of memorizing the API.',
         '2. Canonical grammar for memory objects: `bclaw_find` / `bclaw_get` / `bclaw_create` / `bclaw_update` / `bclaw_remove` / `bclaw_transition` (entity, …).',
         '3. Do not assume project state without reading brainclaw context first.',
+        '4. Before editing unfamiliar code, orient with the **Code Map**: `bclaw_code_brief(target=<symbol|path>)` for a ranked reading list + related decisions/traps, `bclaw_code_find(query=<name>)` to locate a symbol/class/component. Don\'t grep the repo blind when a symbol index already answers "where is X / what should I read first". A `missing_index`/stale badge means run `bclaw_code_refresh` first.',
         '',
         'Escalation (only when orchestrating other agents): `bclaw_coordinate(intent=review|consult|assign)`. Verify any dispatch with `bclaw_dispatch_status(target_id)` — trust its sentinel-based verdict, not the tracked pid. Details: `docs/concepts/dispatch-lifecycle.md`.',
     ].join('\n');
@@ -322,6 +323,7 @@ function renderAvailableTools() {
         '**Session/claims:** `bclaw_session_start`, `bclaw_session_end`, `bclaw_claim`, `bclaw_release_claim` · **steps:** `bclaw_add_step`, `bclaw_complete_step`, `bclaw_update_step`, `bclaw_delete_step` · **sequences:** `bclaw_list_sequences`, `bclaw_create_sequence`, `bclaw_update_sequence`, `bclaw_delete_sequence`',
         '**Inbox:** `bclaw_read_inbox`, `bclaw_ack_message`, `bclaw_send_message`, `bclaw_correct_handoff` · **capture:** `bclaw_write_note`, `bclaw_quick_capture(text, type?)` · **search:** `bclaw_search` · **setup:** `bclaw_setup`, `bclaw_bootstrap`, `bclaw_switch`, `bclaw_release_notes`',
         '**Escalation (orchestrators):** `bclaw_coordinate(intent=review|consult|assign|ideate)` · `bclaw_dispatch(intent=execute)` on an active sequence · `bclaw_loop(intent=turn|complete_turn|advance|close)` to drive turns · `bclaw_dispatch_status(target_id)` to verify',
+        '**Code discovery (Code Map):** `bclaw_code_find(query)` locate a symbol/class/component · `bclaw_code_brief(target)` ranked reading list + related memory before editing · `bclaw_code_status` / `bclaw_code_refresh` check freshness / rebuild the symbol+import index. **Reach for these before `rg`/grep on unfamiliar code** — and if your harness defers MCP tools, `tool_search` for `bclaw_code_*` first rather than falling back to a blind grep. See `docs/code-map.md`.',
         '',
         'Responses are self-teaching — follow their `next_actions`. Full catalog + stability contract: `docs/integrations/mcp.md`, `docs/concepts/mcp-governance.md`.',
     ].join('\n');

package/dist/core/instructions.js

@@ -25,7 +25,6 @@ export function saveInstruction(entry, cwd) {
     });
 }
 export function createInstruction(text, options, cwd) {
-    const entries = loadInstructions(cwd);
     const timestamp = new Date().toISOString();
     const entry = {
         schema_version: 2,

package/dist/core/loops/lock.js

@@ -167,9 +167,6 @@ function loadIdempotencyRecord(kind, key, cwd) {
 function readLockBlob(lockPath) {
     return readJsonIfExists(lockPath) ?? null;
 }
-function writeLockAtomic(lockPath, blob) {
-    writeJsonAtomic(lockPath, blob);
-}
 function processIsAlive(pid) {
     try {
         // Signal 0 just checks for the process's existence without actually sending a signal.

package/dist/core/mcp-command-resolution.js

@@ -216,7 +216,9 @@ export function brainclawMcpEntry(agentName, existing, workspacePath) {
 export function quoteShellArg(arg) {
     if (/^[A-Za-z0-9_./:=+-]+$/.test(arg))
         return arg;
-    return `"${arg.replace(/"/g, '\\"')}"`;
+    // Escape backslashes before quotes — otherwise an input like `\"` would
+    // collapse to a quote that breaks out of the quoted argument.
+    return `"${arg.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
 }
 /**
  * Resolve the brainclaw CLI invocation for hook configs.

package/dist/core/protocol-skills.js

@@ -34,16 +34,18 @@ reachable (cold start, or a worktree without \`.brainclaw/\`).
 
 1. \`bclaw_work(intent='consult')\` — loads project memory and reports active claims. Read \`bootstrap_recommended\`: if true the project has no usable PROJECT.md (see \`brainclaw-multi-agent\` → bootstrap loop).
 2. If you will edit a scope, claim it: \`bclaw_work(intent='execute', scope='<path-or-feature>')\`. The response's \`claim_id\` is yours; \`claim_status='created'\` = new, \`'existing'\` = resumed.
-3. Do the work. Honor the \`warnings\` array (claim conflicts, sensitive paths, high-severity traps on your scope).
-4. When done (committed, tested), \`bclaw_session_end(autoRelease: true)\` — closes the session record and releases your remaining claims. \`autoRelease\` defaults to false; pass it explicitly or claims survive the session.
+3. Before editing unfamiliar code, orient with the **Code Map** instead of grepping blind: \`bclaw_code_brief(target='<symbol|path>')\` for a ranked reading list — the defining file, its importers, and related decisions/traps — or \`bclaw_code_find(query='<name>')\` to locate a symbol/class/component. A \`missing_index\`/stale badge means run \`bclaw_code_refresh\` first.
+4. Do the work. Honor the \`warnings\` array (claim conflicts, sensitive paths, high-severity traps on your scope).
+5. When done (committed, tested), \`bclaw_session_end(autoRelease: true)\` — closes the session record and releases your remaining claims. \`autoRelease\` defaults to false; pass it explicitly or claims survive the session.
 
-CLI fallback: \`brainclaw context --json\` · \`brainclaw claim create "<desc>" --scope <path>\` · \`brainclaw session-end --auto-release\`.
+CLI fallback: \`brainclaw context --json\` · \`brainclaw code-map brief <symbol>\` / \`brainclaw code-map find <name>\` · \`brainclaw claim create "<desc>" --scope <path>\` · \`brainclaw session-end --auto-release\`.
 
 ## Anti-rationalizations
 
 - **"I'm just exploring, I'll skip session-end."** → A live claim outlives a crash. The next agent sees your stale claim and is blocked. Calling \`bclaw_session_end(autoRelease: true)\` is the zero-cost guarantee — without the flag the claim survives.
 - **"I know the project, I don't need to consult."** → State changes between sessions (commits, new traps, new constraints). Consult is cheap and surfaces what you'd miss.
 - **"I'll claim later once I know the exact scope."** → Claim-before-edit IS the contract; it is exactly what prevents races with parallel agents.
+- **"I'll just grep for it."** → On an unfamiliar or large repo, grep floods you with noise and misses the blast radius. \`bclaw_code_brief\` returns the defining file + its importers + related memory in one ranked call; fall back to grep only when the Code Map index is missing.
 
 ## Red flags
 

package/dist/core/security-detectors.js

@@ -26,7 +26,7 @@ export const BUILTIN_DETECTORS = [
     { id: 'aws_access_key', label: 'AWS access key ID', pattern: /\bAKIA[0-9A-Z]{16}\b/ },
     { id: 'aws_temp_access_key', label: 'AWS temporary access key ID', pattern: /\bASIA[0-9A-Z]{16}\b/ },
     // Google
-    { id: 'google_api_key', label: 'Google API key', pattern: /\bAIza[0-9A-Za-z_\-]{35}\b/ },
+    { id: 'google_api_key', label: 'Google API key', pattern: /\bAIza[0-9A-Za-z_-]{35}\b/ },
     // Slack
     { id: 'slack_token', label: 'Slack token', pattern: /\bxox[abprs]-[0-9A-Za-z-]{10,}\b/ },
     { id: 'slack_webhook', label: 'Slack webhook', pattern: /https:\/\/hooks\.slack\.com\/services\/T[A-Z0-9]{8,}\/B[A-Z0-9]{8,}\/[A-Za-z0-9]{24,}/ },
@@ -80,7 +80,7 @@ export function shannonEntropy(s) {
     return h;
 }
 const SECRET_KEYWORD_CONTEXT = /(?:api[_-]?key|secret|token|password|passwd|auth|bearer|access[_-]?key|private[_-]?key)/i;
-const HIGH_ENTROPY_CANDIDATE = /[A-Za-z0-9_+/=\-]{16,}/g;
+const HIGH_ENTROPY_CANDIDATE = /[A-Za-z0-9_+/=-]{16,}/g;
 /**
  * Entropy-based detection. Scans `text` for token-shaped substrings near
  * a sensitive keyword. Two-stage gating keeps false positives low:

package/dist/core/security-extract.js

@@ -126,7 +126,7 @@ export function parseLockfile(filePath) {
         parsed = JSON.parse(raw);
     }
     catch (err) {
-        throw new Error(`Failed to parse lockfile ${filePath}: ${err.message}`);
+        throw new Error(`Failed to parse lockfile ${filePath}: ${err.message}`, { cause: err });
     }
     if (!parsed || typeof parsed !== 'object')
         return [];
@@ -175,7 +175,7 @@ function readFileOrThrow(p, label) {
         return fs.readFileSync(p, 'utf-8');
     }
     catch (err) {
-        throw new Error(`Could not read ${label} at ${p}: ${err.message}`);
+        throw new Error(`Could not read ${label} at ${p}: ${err.message}`, { cause: err });
     }
 }
 function resolveSibling(parent, nested) {

package/dist/core/store-resolution.js

@@ -94,8 +94,10 @@ export function resolveTargetStore(cwd = process.cwd(), target = 'local', option
  * 2. BRAINCLAW_CWD env var → workspace anchor injected by MCP configs
  * 3. BRAINCLAW_PROJECT env var → resolved by name/path from workspace anchor
  * 4. Session-scoped active project (from .current-session under the anchor)
- * 5. Global active-project.json in workspace root
- * 6. Workspace anchor or process.cwd()
+ * 5. cwd_child — the child project the agent is physically inside, under the anchor
+ * 5b. cwd_child (no anchor) — same, ceiling = discovered workspace root (F2)
+ * 6. Global active-project.json in workspace root
+ * 7. Workspace anchor or process.cwd()
  */
 export function resolveEffectiveCwd(options = {}) {
     return resolveEffectiveCwdInfo(options).cwd;
@@ -138,7 +140,42 @@ export function resolveEffectiveCwdInfo(options = {}) {
             return { cwd: sp.path, active_source: 'session', resolved_project: { path: sp.path, name: sp.name } };
         }
     }
-    // 5. Global active-project.json from workspace root
+    // 5. cwd_child — when anchored and the agent is physically inside a child store
+    //    STRICTLY under the anchor, resolve THAT child rather than the shared global
+    //    pointer or the anchor root. This is the independence rule: physical location
+    //    beats a shared/stale global (an agent working in apps/api resolves api, not the
+    //    monorepo root, and is not hijacked by another agent's global switch).
+    //
+    //    GUARD (Codex review): only fire when baseCwd differs from the anchor AND is
+    //    at/below it. `findClosestStoreBelow` walks UP to the ceiling but does NOT prove
+    //    baseCwd sits below it — without the `isAtOrBelow` guard a baseCwd OUTSIDE the
+    //    anchor could match an unrelated `.brainclaw` before hitting the filesystem root.
+    if (baseCwd !== anchorCwd && isAtOrBelow(baseCwd, anchorCwd)) {
+        const child = findClosestStoreBelow(baseCwd, anchorCwd);
+        if (child && path.resolve(child) !== path.resolve(anchorCwd)) {
+            return { cwd: child, active_source: 'cwd_child', resolved_project: projectInfo(child) };
+        }
+    }
+    // 5b. cwd_child (NO anchor) — F2 [trp_71accb07]: even without a BRAINCLAW_CWD
+    //     anchor, an agent physically inside a child project must resolve THAT
+    //     child rather than a stale/shared global pointer set by another agent.
+    //     Ceiling = the discovered workspace root via resolveWorkspaceRoot(baseCwd)
+    //     — NOT os.homedir() (that would revive the F6 boundary edge and could let
+    //     an unrelated home store influence a monorepo worker). Same containment
+    //     guard as the anchored case (isAtOrBelow + a child strictly below).
+    //     For a single-project repo this is a strict no-op: findClosestStoreBelow
+    //     walks UP to the ceiling EXCLUSIVELY, so it can never return the lone root
+    //     store (Codex cadrage non-regression proof, batch 2).
+    if (!hasEnvWorkspace) {
+        const physicalRoot = resolveWorkspaceRoot(baseCwd, options.storeChainOptions);
+        if (physicalRoot && isAtOrBelow(baseCwd, physicalRoot)) {
+            const child = findClosestStoreBelow(baseCwd, physicalRoot);
+            if (child && path.resolve(child) !== path.resolve(physicalRoot)) {
+                return { cwd: child, active_source: 'cwd_child', resolved_project: projectInfo(child) };
+            }
+        }
+    }
+    // 6. Global active-project.json from workspace root
     const wsRoot = hasEnvWorkspace ? anchorCwd : resolveWorkspaceRoot(anchorCwd, options.storeChainOptions);
     if (wsRoot) {
         const active = loadActiveProject(wsRoot);
@@ -146,7 +183,7 @@ export function resolveEffectiveCwdInfo(options = {}) {
             return { cwd: active.path, active_source: 'global', resolved_project: { path: active.path, name: active.name } };
         }
     }
-    // 6. Default
+    // 7. Default
     return { cwd: anchorCwd, active_source: 'cwd', resolved_project: projectInfo(anchorCwd) };
 }
 function projectInfo(cwd) {

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.9.1 on 2026-06-18T15:15:04.496Z
+// Source: brainclaw v1.10.1 on 2026-06-21T19:26:16.599Z
 export const FACTS = {
-  "version": "1.9.1",
-  "generated_at": "2026-06-18T15:15:04.496Z",
+  "version": "1.10.1",
+  "generated_at": "2026-06-21T19:26:16.599Z",
   "tools": {
-    "count": 62,
-    "published_count": 61,
+    "count": 66,
+    "published_count": 65,
     "names": [
       "bclaw_bootstrap",
       "bclaw_release_notes",
@@ -31,6 +31,10 @@ export const FACTS = {
       "bclaw_read_inbox",
       "bclaw_get_thread",
       "bclaw_dispatch_status",
+      "bclaw_code_status",
+      "bclaw_code_find",
+      "bclaw_code_brief",
+      "bclaw_code_refresh",
       "bclaw_dispatch",
       "bclaw_send_message",
       "bclaw_ack_message",

package/dist/facts.json

@@ -1,9 +1,9 @@
 {
-  "version": "1.9.1",
-  "generated_at": "2026-06-18T15:15:04.496Z",
+  "version": "1.10.1",
+  "generated_at": "2026-06-21T19:26:16.599Z",
   "tools": {
-    "count": 62,
-    "published_count": 61,
+    "count": 66,
+    "published_count": 65,
     "names": [
       "bclaw_bootstrap",
       "bclaw_release_notes",
@@ -29,6 +29,10 @@
       "bclaw_read_inbox",
       "bclaw_get_thread",
       "bclaw_dispatch_status",
+      "bclaw_code_status",
+      "bclaw_code_find",
+      "bclaw_code_brief",
+      "bclaw_code_refresh",
       "bclaw_dispatch",
       "bclaw_send_message",
       "bclaw_ack_message",