brainclaw 1.7.2 → 1.7.3

package/README.md

@@ -14,7 +14,7 @@ If you've ever:
 - watched two coworkers (or two agents) **edit the same files** without knowing it,
 - or **gave up running multiple agents in parallel** because keeping them in sync was a pain,
 
-brainclaw gives you durable shared state across sessions, agents, and teammates. Plans, claims, handoffs, decisions, and traps live in `.brainclaw/`, work identically across any compatible agent (Claude Code, Codex, Copilot, Cline, OpenCode, Cursor, Windsurf, Kilocode, Roo Code, Continue, Mistral Vibe, Hermes, Antigravity/Gemini CLI, …), and stay accessible whether you orchestrate them in parallel or pick them up one after another.
+brainclaw gives you durable shared state across sessions, agents, and teammates. Plans, claims, handoffs, decisions, and traps live in `.brainclaw/`, work identically across any compatible agent (Claude Code, Codex, Copilot, Cline, OpenCode, Cursor, Windsurf, Kilocode, Roo Code, Continue, Mistral Vibe, Hermes, Antigravity/Gemini CLI, …), and stay accessible whether you orchestrate them in parallel or pick them up one after another.
 
 Use it two ways — **together or separately**:
 
@@ -81,8 +81,8 @@ brainclaw is designed to sit alongside the coding agents teams are already using
 
 | Logo | Agent | Tier | What brainclaw configures |
 |---|---|---|---|
-| [![OpenClaw](https://img.shields.io/badge/OpenClaw-FF6B35?logoColor=white)](https://github.com/openclaw/openclaw) | **[OpenClaw](https://github.com/openclaw/openclaw)** | B | MCP + brainclaw skill (SKILL.md) for structured project memory |
-| [![Hermes](https://img.shields.io/badge/Hermes-111111?logoColor=white)](https://github.com/NousResearch/hermes-agent) | **[Hermes Agent](https://github.com/NousResearch/hermes-agent)** | B | MCP + universal `.agents/skills/brainclaw/SKILL.md` |
+| [![OpenClaw](https://img.shields.io/badge/OpenClaw-FF6B35?logoColor=white)](https://github.com/openclaw/openclaw) | **[OpenClaw](https://github.com/openclaw/openclaw)** | B | MCP + brainclaw skill (SKILL.md) for structured project memory |
+| [![Hermes](https://img.shields.io/badge/Hermes-111111?logoColor=white)](https://github.com/NousResearch/hermes-agent) | **[Hermes Agent](https://github.com/NousResearch/hermes-agent)** | B | MCP + universal `.agents/skills/brainclaw/SKILL.md` |
 | [![NanoClaw](https://img.shields.io/badge/NanoClaw-4A90D9?logoColor=white)](https://github.com/qwibitai/nanoclaw) | **[NanoClaw](https://github.com/qwibitai/nanoclaw)** | C | brainclaw skill — messaging agent (WhatsApp, Telegram, Slack) |
 | [![NemoClaw](https://img.shields.io/badge/NemoClaw-76B900?logo=nvidia&logoColor=white)](https://github.com/NVIDIA/NemoClaw) | **[NemoClaw](https://github.com/NVIDIA/NemoClaw)** | C | brainclaw skill — NVIDIA enterprise agent stack |
 | [![PicoClaw](https://img.shields.io/badge/PicoClaw-00ADD8?logo=go&logoColor=white)](https://github.com/sipeed/picoclaw) | **[PicoClaw](https://github.com/sipeed/picoclaw)** | C | brainclaw skill — edge/IoT agent (Go, <10MB RAM) |
@@ -109,52 +109,52 @@ If you want the least surprising setup today, use Linux first. If you are on Win
 
 ---
 
-## Get Started
-
-### 1. Let your coding agent lead
-
-The smoothest first-run path is agent-first:
-
-1. ask your coding agent to inspect the package and explain what brainclaw does
-2. ask it to install brainclaw and initialize or join the project you're working on
-3. use the CLI yourself when you need an explicit operator or fallback path
-
-If you want to drive setup manually, use the steps below.
-
-### 2. Install
-
-```bash
-npm install -g brainclaw
-```
-
-### 3. Bootstrap this machine
-
-```bash
-brainclaw setup-machine --yes
-```
-
-This detects the installed coding agents on the current machine, writes the machine-level MCP and user config Brainclaw manages for that detected set, and does **not** scan or initialize repositories.
-
-### 4. Initialize or refresh the current project
-
-```bash
-cd your-project
-brainclaw init
-```
-
-`brainclaw init` is now safe to rerun. It creates `.brainclaw/` when the project is new, or refreshes the managed Brainclaw and agent integration files when the project already has memory.
-
-If you are explicitly adding another agent to an existing Brainclaw project, use:
-
-```bash
-brainclaw enable-agent <agent-name>
-```
-
-### 5. Restart your agent
-
-Restart your coding agent (or reload MCP servers) so it picks up the new configuration. After that, brainclaw tools are available.
-
-### 6. Start working
+## Get Started
+
+### 1. Let your coding agent lead
+
+The smoothest first-run path is agent-first:
+
+1. ask your coding agent to inspect the package and explain what brainclaw does
+2. ask it to install brainclaw and initialize or join the project you're working on
+3. use the CLI yourself when you need an explicit operator or fallback path
+
+If you want to drive setup manually, use the steps below.
+
+### 2. Install
+
+```bash
+npm install -g brainclaw
+```
+
+### 3. Bootstrap this machine
+
+```bash
+brainclaw setup-machine --yes
+```
+
+This detects the installed coding agents on the current machine, writes the machine-level MCP and user config Brainclaw manages for that detected set, and does **not** scan or initialize repositories.
+
+### 4. Initialize or refresh the current project
+
+```bash
+cd your-project
+brainclaw init
+```
+
+`brainclaw init` is now safe to rerun. It creates `.brainclaw/` when the project is new, or refreshes the managed Brainclaw and agent integration files when the project already has memory.
+
+If you are explicitly adding another agent to an existing Brainclaw project, use:
+
+```bash
+brainclaw enable-agent <agent-name>
+```
+
+### 5. Restart your agent
+
+Restart your coding agent (or reload MCP servers) so it picks up the new configuration. After that, brainclaw tools are available.
+
+### 6. Start working
 
 Pick one of the canonical entry points depending on what you're doing:
 
@@ -186,7 +186,7 @@ For agents without MCP (e.g. Copilot reads `.github/copilot-instructions.md`), r
 brainclaw export --detect --write
 ```
 
-### 7. Verify it works
+### 7. Verify it works
 
 ```bash
 brainclaw status          # see active sessions, claims, plans
@@ -197,11 +197,11 @@ brainclaw agent-board     # see what each agent is doing
 
 To configure brainclaw for all your repos and agents at once:
 
-```bash
-brainclaw setup --yes
-```
-
-This is the broader multi-repo wizard. It bootstraps the machine, scans your project roots, and initializes selected repositories in one pass.
+```bash
+brainclaw setup --yes
+```
+
+This is the broader multi-repo wizard. It bootstraps the machine, scans your project roots, and initializes selected repositories in one pass.
 
 ### Existing projects
 
@@ -232,7 +232,7 @@ Still sharp:
 1. **Same-checkout concurrent edits** — running two agents in the *same* working tree (no per-claim worktree) is still the wrong answer. Use the dispatch path (auto-worktree per claim) instead of raw concurrent CLI sessions.
 2. **Cross-machine sync** — federation across machines is on the roadmap, not in v1.x. Today brainclaw's store is local and one-machine-per-project.
 3. **Spawn-and-forget assumptions** — spawned workers don't always commit their work cleanly. The brief-ack file confirms the spawn started; in the worst case the coordinator harvests open changes.
-4. **Live state for hook-less agents** — Tier B/C agents without lifecycle hooks (Cursor, Cline, Windsurf, Copilot, Continue, Kilocode, Mistral Vibe, Hermes) get live context via `.live.md` companions regenerated on session-end and handoff, not via real-time push.
+4. **Live state for hook-less agents** — Tier B/C agents without lifecycle hooks (Cursor, Cline, Windsurf, Copilot, Continue, Kilocode, Mistral Vibe, Hermes) get live context via `.live.md` companions regenerated on session-end and handoff, not via real-time push.
 
 Recommended use today:
 
@@ -343,42 +343,56 @@ npm run test:coverage      # with coverage report
 
 ## Changelog
 
-For older releases (v0.x and the early v1.0 launch series), `git log` on `master` is the source of truth — every release commit follows the `chore(release): bump version to <semver>` convention, and the matching feature/fix commits reference their plan id (e.g. `feat(mcp): self-heal ... (pln#478)`).
-
-### v1.7.2
-
-- **Sequence MCP tools are agent-first by default** — sequence creation,
-  listing, update, and deletion tools are now in the default MCP catalog, with
-  explicit lane item schemas (`planId`, optional `stepId`, `rank`,
-  dependencies, lane metadata) and matching canonical CRUD validation for
-  `entity="sequence"`.
-
-### v1.7.1
-
-- **MCP project context isolation fix** — `bclaw_switch` now keeps MCP switches
-  session-scoped even when the agent session has to be resolved or created on
-  the fly. Session lookup honors explicit session IDs, avoids adopting another
-  live process's session, detects Codex via native `CODEX_*` runtime variables,
-  and `bclaw_switch(list=true)` reports the session active project with
-  `active_source`.
-
-### v1.7.0
-
-- **Dispatch reliability + scope-aware dirty guard** — evidence-first
-  `agent_run` reconciliation avoids false terminal states, `bclaw_coordinate`
-  accepts pinned refs and a scope-aware `allow_dirty` guard, and the Hermes
-  agent integration joins the supported surfaces.
-
-### v1.6.0
-
-- **Bootstrap loop + cross-project agent workflow** — the bootstrap ideation
-  preset can materialize `PROJECT.md`, `bclaw_init_project` initializes and links
-  arbitrary project paths, and `project=` routing reaches `bclaw_work` /
-  `bclaw_loop` for linked-project operations.
-
-### v1.5.3
-
-- **Cross-project canonical grammar + CLI parity** (pln#359, all phases) — the canonical grammar (`bclaw_find / get / create / update / remove / transition`), `bclaw_context`, and `bclaw_coordinate` now accept an optional `project: <name>` argument that routes the operation to a linked project. Two link kinds are recognised: `cross_project_links` (sibling/peer projects in `config.yaml`, `brainclaw link list`) and workspace store-chain children. Arbitrary directory paths are rejected — adoption requires an explicit link, which gives the user a single point of control over what an agent can reach. Identity is sourced from the caller's home registry; entity writes + audit log entries land in the target. Unknown project names throw `validation_error` with a hint listing the configured links — no silent fallback. Cross-project `bclaw_coordinate` is **inbox-only**: claim/assignment/message all land in the target, the target agent picks the brief up async via its own `bclaw_work`, and auto-spawn from the source process is force-disabled because the spawn cwd / worktree are tied to the target's git repo (a warning surfaces in `FacadeResponse.warnings`). The CLI exposes the same as a global `--project <name>` flag, mutually exclusive with `--cwd`. Refs: helper `resolveProjectCwd` in `src/core/cross-project.ts`, MCP write/read handler dispatch in `src/commands/mcp.ts` and `src/commands/mcp-read-handlers.ts`, `--project` plumbing in `src/cli.ts` preAction, surface advertisement in `src/core/instruction-templates.ts`, plus tests in `tests/unit/cross-project.test.ts` (10 unit cases on the helper), `tests/unit/bclaw-coordinate.test.ts` (4 cross-project routing cases), and `tests/cli-cross-project.test.ts` (5 e2e cases). Closes the `--cwd` workaround pattern that had been the day-to-day shape of multi-project sessions.
+For older releases (v0.x and the early v1.0 launch series), `git log` on `master` is the source of truth — every release commit follows the `chore(release): bump version to <semver>` convention, and the matching feature/fix commits reference their plan id (e.g. `feat(mcp): self-heal ... (pln#478)`).
+
+### v1.7.3
+
+- **Multi-agent dispatch hardening for JS/TS monorepos** — dispatched worktrees
+  junction-link per-package `node_modules` (npm / yarn / pnpm workspaces), not
+  just the root, and surface failed links instead of swallowing them; `brainclaw
+  worktree clean` now garbage-collects merged worktrees past birth-noise instead
+  of skipping them all; the agent inventory reports an agent `spawnable` when its
+  binary is on PATH even if `--version` is slow to start; dispatch-verification
+  guidance leads with `bclaw_dispatch_status` (not the untrustworthy Windows
+  wrapper pid); and a new `LANE-RESULT.json` convention + `brainclaw harvest
+  <assignment_id>` give workers a standard, MCP-free result channel. The dispatch
+  dirty-guard also ignores `.claude/`, `.cursor/`, and `.codex/` agent-local
+  config. (pln#523, pln#524, pln#525, pln#526, trp#371, trp#427, trp#428)
+
+### v1.7.2
+
+- **Sequence MCP tools are agent-first by default** — sequence creation,
+  listing, update, and deletion tools are now in the default MCP catalog, with
+  explicit lane item schemas (`planId`, optional `stepId`, `rank`,
+  dependencies, lane metadata) and matching canonical CRUD validation for
+  `entity="sequence"`.
+
+### v1.7.1
+
+- **MCP project context isolation fix** — `bclaw_switch` now keeps MCP switches
+  session-scoped even when the agent session has to be resolved or created on
+  the fly. Session lookup honors explicit session IDs, avoids adopting another
+  live process's session, detects Codex via native `CODEX_*` runtime variables,
+  and `bclaw_switch(list=true)` reports the session active project with
+  `active_source`.
+
+### v1.7.0
+
+- **Dispatch reliability + scope-aware dirty guard** — evidence-first
+  `agent_run` reconciliation avoids false terminal states, `bclaw_coordinate`
+  accepts pinned refs and a scope-aware `allow_dirty` guard, and the Hermes
+  agent integration joins the supported surfaces.
+
+### v1.6.0
+
+- **Bootstrap loop + cross-project agent workflow** — the bootstrap ideation
+  preset can materialize `PROJECT.md`, `bclaw_init_project` initializes and links
+  arbitrary project paths, and `project=` routing reaches `bclaw_work` /
+  `bclaw_loop` for linked-project operations.
+
+### v1.5.3
+
+- **Cross-project canonical grammar + CLI parity** (pln#359, all phases) — the canonical grammar (`bclaw_find / get / create / update / remove / transition`), `bclaw_context`, and `bclaw_coordinate` now accept an optional `project: <name>` argument that routes the operation to a linked project. Two link kinds are recognised: `cross_project_links` (sibling/peer projects in `config.yaml`, `brainclaw link list`) and workspace store-chain children. Arbitrary directory paths are rejected — adoption requires an explicit link, which gives the user a single point of control over what an agent can reach. Identity is sourced from the caller's home registry; entity writes + audit log entries land in the target. Unknown project names throw `validation_error` with a hint listing the configured links — no silent fallback. Cross-project `bclaw_coordinate` is **inbox-only**: claim/assignment/message all land in the target, the target agent picks the brief up async via its own `bclaw_work`, and auto-spawn from the source process is force-disabled because the spawn cwd / worktree are tied to the target's git repo (a warning surfaces in `FacadeResponse.warnings`). The CLI exposes the same as a global `--project <name>` flag, mutually exclusive with `--cwd`. Refs: helper `resolveProjectCwd` in `src/core/cross-project.ts`, MCP write/read handler dispatch in `src/commands/mcp.ts` and `src/commands/mcp-read-handlers.ts`, `--project` plumbing in `src/cli.ts` preAction, surface advertisement in `src/core/instruction-templates.ts`, plus tests in `tests/unit/cross-project.test.ts` (10 unit cases on the helper), `tests/unit/bclaw-coordinate.test.ts` (4 cross-project routing cases), and `tests/cli-cross-project.test.ts` (5 e2e cases). Closes the `--cwd` workaround pattern that had been the day-to-day shape of multi-project sessions.
 - **Site facts contract** (umbrella `pln_7fdfd70d` sprint 0) — new `scripts/emit-site-facts.mjs` emits `dist/facts.{js,json}` from `MCP_TOOL_NAMES` + `ENTITY_NAMES` so the brainclaw-site (and any consumer) can pull live tool/entity counts at build time without forking the values into a hand-maintained config. The package `files` list ships `dist/facts.json`; build:cli runs the emitter as part of the chain.
 
 ### v1.5.2
@@ -436,15 +450,15 @@ For older releases (v0.x and the early v1.0 launch series), `git log` on `master
 
 ---
 
-## License
-
-brainclaw core is published under the [MIT License](LICENSE) — (c) 2024-2026 Juan Berdah.
-
-The licensing split is simple:
-
-- the local-first brainclaw core is MIT
-- cloud shared-memory, remote collaboration services, advanced dashboards, and related hosted add-ons will live in separate commercial products
-
-The MIT core covers what makes brainclaw useful inside a repo today: local project memory, local MCP and CLI coordination, onboarding and bootstrap, plans, claims, handoffs, runtime notes, and local agent integrations.
+## License
+
+brainclaw core is published under the [MIT License](LICENSE) — (c) 2024-2026 Juan Berdah.
+
+The licensing split is simple:
+
+- the local-first brainclaw core is MIT
+- cloud shared-memory, remote collaboration services, advanced dashboards, and related hosted add-ons will live in separate commercial products
+
+The MIT core covers what makes brainclaw useful inside a repo today: local project memory, local MCP and CLI coordination, onboarding and bootstrap, plans, claims, handoffs, runtime notes, and local agent integrations.
 
 The goal is not to close brainclaw down. The goal is to keep the local-first core open and genuinely useful on its own, while keeping hosted collaboration features separate.

package/dist/cli.js

@@ -104,7 +104,7 @@ import { runDiscover } from './commands/discover.js';
 import { runMigrate } from './commands/migrate.js';
 import { runRunProfile } from './commands/run-profile.js';
 import { runCompact } from './commands/compact.js';
-import { runHarvestCandidates } from './commands/harvest.js';
+import { runHarvestCandidates, runHarvestLane } from './commands/harvest.js';
 import { runQuestionsCommand } from './commands/questions.js';
 import { runReplyCommand } from './commands/reply.js';
 import { requireRegisteredAgentIdentity } from './core/agent-registry.js';
@@ -1009,6 +1009,18 @@ program
     const globalOpts = program.opts();
     runHarvestCandidates({ ...options, cwd: globalOpts.cwd });
 });
+// --- harvest (lane results, pln#526) ---
+program
+    .command('harvest [assignment_id]')
+    .description('Harvest a worker LANE-RESULT.json from its worktree into the project (pass an assignment id, or --all)')
+    .option('--all', 'Harvest every lane result found across worktrees')
+    .option('--dry-run', 'Preview without writing events/markers')
+    .option('--worktree <path>', 'Explicit worktree path to scan (repeatable)', collect, [])
+    .option('--json', 'Output as JSON')
+    .action((assignmentId, options) => {
+    const globalOpts = program.opts();
+    runHarvestLane(assignmentId, { ...options, cwd: globalOpts.cwd });
+});
 // --- prune-candidates ---
 program
     .command('prune-candidates')

package/dist/commands/harvest.js

@@ -14,7 +14,7 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import crypto from 'node:crypto';
-import { CandidateSchema } from '../core/schema.js';
+import { CandidateSchema, LaneResultSchema } from '../core/schema.js';
 import { listCandidates, listArchivedCandidates, saveCandidate } from '../core/candidates.js';
 import { createRuntimeEvent } from '../core/events.js';
 import { memoryExists } from '../core/io.js';
@@ -186,4 +186,127 @@ export function runHarvestCandidates(options = {}) {
     }
     console.log(`\n✔ Harvest complete${dryTag}: ${result.harvested.length} imported, ${result.skipped.length} skipped, ${result.errors.length} error(s).`);
 }
+// ─────────────────────────────────────────────────────────────────────────────
+// pln#526 — LANE-RESULT convention
+//
+// A dispatched worker writes a single `LANE-RESULT.json` at its worktree root
+// as its final step. This is the standard, brief-boilerplate-free channel for a
+// worker (especially a sandboxed one that cannot reach MCP) to report its
+// outcome. The coordinator ingests it with `brainclaw harvest <assignment_id>`.
+// ─────────────────────────────────────────────────────────────────────────────
+/** Conventional path of a worker's lane-result file at the worktree root. */
+export function getLaneResultPath(worktreePath) {
+    return path.join(worktreePath, 'LANE-RESULT.json');
+}
+/** Idempotency marker so a lane-result is harvested once. */
+function laneHarvestedMarkerPath(cwd, assignmentId) {
+    return path.join(cwd, '.brainclaw', 'coordination', 'runtime', 'result', `${assignmentId}.harvested`);
+}
+/**
+ * Scan worktrees for `LANE-RESULT.json`, validate, and ingest each: emit a
+ * `lane_result_harvested` runtime event (durable + queryable) and drop an
+ * idempotency marker so re-runs skip it. The worker's actual code lives in the
+ * worktree/branch; this surfaces the structured outcome (status + summary) the
+ * coordinator needs to converge the lane.
+ */
+export function harvestLaneResults(options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const agent = options.agent ?? 'coordinator';
+    const result = { harvested: [], skipped: [], errors: [] };
+    const worktreePaths = (options.worktreePaths && options.worktreePaths.length > 0)
+        ? options.worktreePaths
+        : autoDetectWorktreePaths(cwd);
+    for (const worktreePath of worktreePaths) {
+        const file = getLaneResultPath(worktreePath);
+        if (!fs.existsSync(file))
+            continue;
+        let lane;
+        try {
+            lane = LaneResultSchema.parse(JSON.parse(fs.readFileSync(file, 'utf-8')));
+        }
+        catch (err) {
+            result.errors.push(`Failed to parse ${file}: ${err instanceof Error ? err.message : String(err)}`);
+            continue;
+        }
+        // Assignment filter (when harvesting a specific lane).
+        if (options.assignmentId && lane.assignment_id !== options.assignmentId)
+            continue;
+        const marker = laneHarvestedMarkerPath(cwd, lane.assignment_id);
+        if (fs.existsSync(marker)) {
+            result.skipped.push(lane.assignment_id);
+            continue;
+        }
+        if (!options.dryRun) {
+            try {
+                createRuntimeEvent({
+                    agent,
+                    event_type: 'lane_result_harvested',
+                    text: `Lane result for ${lane.assignment_id}: ${lane.status} — ${lane.summary.slice(0, 120)}`,
+                    tags: ['harvest', 'lane-result', lane.status],
+                    assignment_id: lane.assignment_id,
+                    metadata: {
+                        assignment_id: lane.assignment_id,
+                        status: lane.status,
+                        artifacts: lane.artifacts ?? [],
+                        files_changed: lane.files_changed ?? [],
+                        source_worktree: worktreePath,
+                    },
+                }, cwd);
+                fs.mkdirSync(path.dirname(marker), { recursive: true });
+                fs.writeFileSync(marker, new Date(0).toISOString(), 'utf-8');
+            }
+            catch (err) {
+                result.errors.push(`Failed to ingest lane result for ${lane.assignment_id}: ${err instanceof Error ? err.message : String(err)}`);
+                continue;
+            }
+        }
+        result.harvested.push(lane);
+    }
+    return result;
+}
+export function runHarvestLane(assignmentId, options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    if (!memoryExists(cwd)) {
+        console.error('Error: .brainclaw/ not found. Run `brainclaw init` first.');
+        process.exit(1);
+    }
+    if (!assignmentId && !options.all) {
+        console.error('Error: provide an <assignment_id>, or pass --all to harvest every lane result.');
+        process.exit(1);
+    }
+    const result = harvestLaneResults({
+        assignmentId: options.all ? undefined : assignmentId,
+        worktreePaths: options.worktree,
+        dryRun: options.dryRun,
+        cwd,
+    });
+    if (options.json) {
+        console.log(JSON.stringify({
+            harvested: result.harvested,
+            skipped: result.skipped,
+            errors: result.errors,
+        }, null, 2));
+        return;
+    }
+    const dryTag = options.dryRun ? ' (dry-run)' : '';
+    if (result.harvested.length === 0 && result.skipped.length === 0 && result.errors.length === 0) {
+        console.log(assignmentId ? `No LANE-RESULT.json found for ${assignmentId}.` : 'No lane results found in any worktree.');
+        return;
+    }
+    for (const lane of result.harvested) {
+        const verb = options.dryRun ? '  (dry-run) Would harvest' : '  ✔ Harvested';
+        console.log(`${verb} [${lane.assignment_id}] ${lane.status}: ${lane.summary.slice(0, 100)}`);
+        if (lane.files_changed?.length)
+            console.log(`      files: ${lane.files_changed.slice(0, 8).join(', ')}`);
+        if (lane.notes)
+            console.log(`      notes: ${lane.notes.slice(0, 120)}`);
+    }
+    for (const id of result.skipped) {
+        console.log(`  ⟳ Skipped (already harvested): ${id}`);
+    }
+    for (const err of result.errors) {
+        console.error(`  ✗ ${err}`);
+    }
+    console.log(`\n✔ Lane harvest complete${dryTag}: ${result.harvested.length} harvested, ${result.skipped.length} skipped, ${result.errors.length} error(s).`);
+}
 //# sourceMappingURL=harvest.js.map

package/dist/commands/mcp.js

@@ -956,7 +956,7 @@ const MCP_WRITE_TOOLS = [
     },
     {
         name: 'bclaw_coordinate',
-        description: 'Multi-agent coordination facade: assign tasks to agents (with claims), consult agents (no claim), create a review candidate, open an ideation loop, reroute an active claim to another agent, or summarize a thread. Returns a FacadeResponse with selected_targets, delivery_plan, artifacts, side_effects, and execution_status. IMPORTANT — execution_status semantics: `delivered_and_started` means the spawn wrapper touched the brief-ack sentinel (`.brainclaw/coordination/runtime/ack/<assignment_id>.ack`) — NOT that the worker is doing useful work. Spawned workers may still die silently before consuming the brief (cf. trap trp_38f63ea4). To verify a dispatch is actually alive, query `bclaw_find(entity="agent_run", filter={assignment_id})` then check `status==="running"` AND OS-level pid liveness (Windows: `Get-Process -Id <pid>` ; POSIX: `kill -0 <pid>`) AND `last_event_at` within the last few minutes. See docs/concepts/troubleshooting.md §"Inbox messages stuck / brief-ack never arrived" for the diagnostic playbook, and docs/integrations/<agent>.md for per-agent spawn semantics (notably codex.md re sandbox MCP availability).',
+        description: 'Multi-agent coordination facade: assign tasks to agents (with claims), consult agents (no claim), create a review candidate, open an ideation loop, reroute an active claim to another agent, or summarize a thread. Returns a FacadeResponse with selected_targets, delivery_plan, artifacts, side_effects, and execution_status. IMPORTANT — execution_status semantics: `delivered_and_started` means the spawn wrapper touched the brief-ack sentinel (`.brainclaw/coordination/runtime/ack/<assignment_id>.ack`) — NOT that the worker is doing useful work. Spawned workers may still die silently before consuming the brief (cf. trap trp_38f63ea4). To verify a dispatch is actually alive, call `bclaw_dispatch_status(target_id=<asgn_…>)` — it reads the runtime sentinels (ack/heartbeat/completed/failed) plus captured stdout/stderr tails and returns a single health verdict + recommended next action (this is the `verify_with` target attached to the response). Do NOT diagnose liveness from the tracked pid: on Windows an ack-wrapped spawn runs under cmd.exe, so `agent_run.pid` is the wrapper (which exits early by design), NOT the real worker — `Get-Process -Id <pid>` reads it dead while the worker is alive and committing. The reconciler trusts the sentinels and infers `completed` from a post-start commit even when the worker never called bclaw_assignment_update. See docs/concepts/dispatch-lifecycle.md for the full FSM + diagnostic decision tree, and docs/integrations/<agent>.md for per-agent spawn semantics (notably codex.md re sandbox MCP availability).',
         annotations: { tier: 'facade', category: 'coordination', headlessApproval: 'auto' },
         inputSchema: {
             type: 'object',

package/dist/core/agent-inventory.js

@@ -5,6 +5,14 @@ import { spawnSync } from 'node:child_process';
 import yaml from 'yaml';
 import { MEMORY_DIR } from './io.js';
 import { detectHostExecutionProfile, } from './execution-profile.js';
+import { getCapabilityProfile } from './agent-capability.js';
+/**
+ * trp#427 — cold-start CLI `--version` probes need headroom; a 3s timeout
+ * false-negatived claude-code on first launch. The spawnable check (binary on
+ * PATH) is the robust signal, so this only affects version-string capture
+ * latency, not the installed/spawnable decision.
+ */
+const VERSION_PROBE_TIMEOUT_MS = 8000;
 function tryCommand(command, args, timeout = 5000) {
     try {
         const r = spawnSync(command, args, { encoding: 'utf-8', timeout, windowsHide: true });
@@ -14,12 +22,40 @@ function tryCommand(command, args, timeout = 5000) {
         return { ok: false, stdout: '' };
     }
 }
+/**
+ * trp#427 — fast PATH resolution for a binary (no process launch, unlike a
+ * `--version` probe). Uses `where` (Windows) / `which` (POSIX).
+ */
+function isBinaryOnPath(binary) {
+    if (!binary)
+        return false;
+    try {
+        const cmd = process.platform === 'win32' ? 'where' : 'which';
+        const r = spawnSync(cmd, [binary], { encoding: 'utf-8', timeout: 3000, windowsHide: true });
+        return r.status === 0 && (r.stdout ?? '').trim().length > 0;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * trp#427 — an agent is SPAWNABLE when its capability profile is CLI-spawnable,
+ * declares an invoke binary, and that binary resolves on PATH. Decoupled from
+ * the `--version` health probe so a slow cold-start CLI is never misreported as
+ * "not installed" / undispatchable.
+ */
+export function detectSpawnable(agentName) {
+    const profile = getCapabilityProfile(agentName);
+    if (!profile || !profile.runtime?.canBeSpawnedCli || !profile.invoke_binary)
+        return false;
+    return isBinaryOnPath(profile.invoke_binary);
+}
 const AGENT_DEFINITIONS = [
     {
         name: 'claude-code',
         detect: (_home, env) => {
             // Check if claude CLI is available
-            const cli = tryCommand('claude', ['--version'], 3000);
+            const cli = tryCommand('claude', ['--version'], VERSION_PROBE_TIMEOUT_MS);
             if (cli.ok) {
                 const ver = cli.stdout.trim().match(/(\d+\.\d+\.\d+)/)?.[1];
                 return { installed: true, method: 'claude CLI', version: ver };
@@ -81,7 +117,7 @@ const AGENT_DEFINITIONS = [
             if (fs.existsSync(codexDir)) {
                 return { installed: true, method: '~/.codex directory' };
             }
-            const cli = tryCommand('codex', ['--version'], 3000);
+            const cli = tryCommand('codex', ['--version'], VERSION_PROBE_TIMEOUT_MS);
             if (cli.ok) {
                 const ver = cli.stdout.trim().match(/(\d+\.\d+\.\d+)/)?.[1];
                 return { installed: true, method: 'codex CLI', version: ver };
@@ -252,7 +288,7 @@ const AGENT_DEFINITIONS = [
             if (fs.existsSync(path.join(home, '.gemini', 'antigravity'))) {
                 return { installed: true, method: '~/.gemini/antigravity directory' };
             }
-            const cli = tryCommand('gemini', ['--version'], 3000);
+            const cli = tryCommand('gemini', ['--version'], VERSION_PROBE_TIMEOUT_MS);
             if (cli.ok) {
                 return { installed: true, method: 'gemini CLI', version: cli.stdout.trim() };
             }
@@ -309,7 +345,7 @@ const AGENT_DEFINITIONS = [
             if (fs.existsSync(path.join(home, '.hermes'))) {
                 return { installed: true, method: '~/.hermes directory' };
             }
-            const cli = tryCommand('hermes', ['--version'], 3000);
+            const cli = tryCommand('hermes', ['--version'], VERSION_PROBE_TIMEOUT_MS);
             if (cli.ok) {
                 return { installed: true, method: 'hermes CLI', version: cli.stdout.trim() };
             }
@@ -332,14 +368,23 @@ const AGENT_DEFINITIONS = [
 /**
  * Detect ALL installed agents on this machine (not just the running one).
  */
-export function buildAgentInventory(homeDir = os.homedir(), env = process.env) {
+export function buildAgentInventory(homeDir = os.homedir(), env = process.env, opts = {}) {
+    const spawnableResolver = opts.spawnableResolver ?? detectSpawnable;
     const agents = AGENT_DEFINITIONS.map(def => {
         const detection = def.detect(homeDir, env);
+        const spawnable = spawnableResolver(def.name);
+        // trp#427: an agent brainclaw can spawn (invoke binary on PATH) IS installed,
+        // even when the cold-start `--version` probe timed out. This decouples the
+        // dispatch decision (getInstalledAgentNames) from probe latency.
+        const installed = detection.installed || spawnable;
         return {
             name: def.name,
-            installed: detection.installed,
-            detection_method: detection.method,
+            installed,
+            detection_method: detection.installed
+                ? detection.method
+                : (spawnable ? 'spawnable: invoke binary on PATH' : detection.method),
             version: detection.version,
+            spawnable,
             models: def.models,
             native_tools: def.native_tools,
             mcp_support: def.mcp_support,
@@ -415,6 +460,8 @@ export function renderAgentInventorySummary(inventory) {
             features.push('Rules');
         if (agent.hooks_support)
             features.push('Hooks');
+        if (agent.spawnable)
+            features.push('Spawnable');
         lines.push(`  Features: ${features.join(', ') || 'none'}`);
         if (agent.instruction_file) {
             lines.push(`  Instructions: ${agent.instruction_file}`);

package/dist/core/dirty-scope.js

@@ -44,13 +44,19 @@ function defaultRunGit(cwd, args) {
         return { ok: false, stdout: '' };
     }
 }
-/** True for coordination/store paths that are dirty as a side effect of dispatching. */
+/**
+ * Top-level directories that are dirty as a side effect of coordination /
+ * agent tooling, never part of a dispatch's code scope:
+ *   - `.brainclaw`, `.git` — coordination store + VCS metadata.
+ *   - `.claude`, `.cursor`, `.codex` — per-agent local config (trp#371). A
+ *     worker leaving these dirty (Claude Code settings, etc.) must not block an
+ *     otherwise-safe dispatch of an unrelated code scope.
+ */
+const SYSTEM_DIRTY_DIRS = ['.brainclaw', '.git', '.claude', '.cursor', '.codex'];
+/** True for coordination/store/agent-config paths that are dirty as a side effect of tooling. */
 export function isSystemDirtyPath(p) {
     const norm = p.replace(/\\/g, '/');
-    return norm === '.brainclaw'
-        || norm.startsWith('.brainclaw/')
-        || norm === '.git'
-        || norm.startsWith('.git/');
+    return SYSTEM_DIRTY_DIRS.some((dir) => norm === dir || norm.startsWith(dir + '/'));
 }
 /**
  * Parse `git status --porcelain=v1 -z` output into a flat list of paths.

package/dist/core/dispatcher.js

@@ -238,6 +238,13 @@ export function buildProtocolSection(options) {
     }
     if (options?.worktreePath) {
         parts.push(`Worktree: ${options.worktreePath}`);
+        // pln#523: tell the worker how dependencies are provisioned so it does not
+        // stall trying to install them. node_modules (and per-package node_modules in
+        // monorepos) are junction-linked from the main repo — run builds/typecheck
+        // directly. If they are missing, do NOT `npm install` in the worktree: check
+        // `.brainclaw-worktree.json` → `symlink_warnings` (a link may have failed,
+        // e.g. cross-volume) and validate the build centrally with the coordinator.
+        parts.push('Dependencies: node_modules is linked from the main repo (incl. monorepo per-package). Build/typecheck directly; if deps are missing, do NOT npm install here — see .brainclaw-worktree.json symlink_warnings and validate centrally.');
     }
     parts.push('');
     // Assignment lifecycle protocol (Agent SDK)
@@ -254,6 +261,9 @@ export function buildProtocolSection(options) {
         parts.push(`${options.worktreePath ? '7' : '6'}. Release the claim: bclaw_release_claim(${claimRef}, planStatus: "done") — required for hard_after gating to unblock downstream tasks`);
         parts.push(`${options.worktreePath ? '8' : '7'}. If blocked: bclaw_assignment_update(status: "blocked", blocker: "...")`);
         parts.push(`${options.worktreePath ? '9' : '8'}. If failed: bclaw_assignment_update(status: "failed", error_message: "...")`);
+        // pln#526: standard fallback channel — works even when MCP is unreachable
+        // (sandboxed agents). The coordinator ingests it with `brainclaw harvest`.
+        parts.push(`Final fallback (if bclaw_assignment_update / MCP is unavailable, e.g. a sandboxed agent): write LANE-RESULT.json at the worktree root — {"assignment_id":"${options.assignmentId}","status":"completed|blocked|failed","summary":"<what you did>","files_changed":["..."],"artifacts":["..."]}. The coordinator harvests it via \`brainclaw harvest ${options.assignmentId}\`.`);
     }
     else if (options?.claimId) {
         parts.push('1. Call bclaw_session_start to register your session');

package/dist/core/instruction-templates.js

@@ -237,7 +237,7 @@ function renderSessionProtocol() {
         '',
         'Do NOT call `bclaw_loop(intent=open)` directly — it creates a loop structure without dispatch, so the reviewer/participant never gets the work. Use the goal entries above.',
         '',
-        '_How to verify a dispatch actually worked:_ `execution_status="delivered_and_started"` only means the brief-ack sentinel was touched — it does NOT mean the worker is doing useful work. Always (1) `bclaw_find(entity="agent_run", filter={assignment_id})` to read the spawn record; (2) check OS pid liveness yourself (`Get-Process -Id <pid>` on Windows, `kill -0 <pid>` on POSIX); (3) if the worker is silent, read its captured streams at `.brainclaw/coordination/runtime/log/<assignment_id>.{stdout,stderr}.log`. Full FSM tables + diagnostic decision tree in `docs/concepts/dispatch-lifecycle.md`.',
+        '_How to verify a dispatch actually worked:_ `execution_status="delivered_and_started"` only means the brief-ack sentinel was touched — it does NOT mean the worker is doing useful work. (1) Call `bclaw_dispatch_status(target_id=<asgn_…|clm_…|lop_…|run_…>)` — the purpose-built facade: it resolves the linked entities, reads the runtime sentinels (`ack` / `heartbeat` / `completed` / `failed`) and the captured stdout/stderr tails, checks pid liveness, and returns a single health verdict plus a recommended next action. This is the `verify_with` target named in the coordinate/dispatch response — prefer it over assembling the picture by hand. (2) Do NOT diagnose liveness from the tracked pid yourself: on Windows an ack-wrapped spawn runs under a `cmd.exe` shell, so `agent_run.pid` is the wrapper (which exits early by design), NOT the real worker — `Get-Process -Id <pid>` reads it dead while the worker is alive and committing. Trust the sentinel-derived verdict instead; the reconciler already infers `completed` from a post-start commit on the worktree branch even when the worker never called `bclaw_assignment_update`. (3) Fallback only if the facade is unavailable: `bclaw_find(entity="agent_run", filter={assignment_id})` plus the captured streams at `.brainclaw/coordination/runtime/log/<assignment_id>.{stdout,stderr}.log` — note that `claude -p` buffers stdout until exit, so an empty log mid-run is expected; use the `heartbeat` sentinel as the live progress signal, not stdout. Full FSM tables + diagnostic decision tree in `docs/concepts/dispatch-lifecycle.md`.',
     ].join('\n');
 }
 function renderUserWorkflow() {

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));
@@ -282,6 +385,10 @@ 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 } : {}),
     };
     fs.writeFileSync(path.join(targetPath, '.brainclaw-worktree.json'), JSON.stringify(meta, null, 2));
     return targetPath;
@@ -510,6 +617,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 +670,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 +686,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.3 on 2026-06-05T21:43:11.193Z
 export const FACTS = {
-  "version": "1.7.2",
-  "generated_at": "2026-06-04T21:46:11.832Z",
+  "version": "1.7.3",
+  "generated_at": "2026-06-05T21:43:11.193Z",
   "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.3",
+  "generated_at": "2026-06-05T21:43:11.193Z",
   "tools": {
     "count": 62,
     "published_count": 61,

package/package.json

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