brainclaw 1.7.2 → 1.7.4

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,72 @@ 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.4
+
+- **Dispatch observability + worker DX hardening** (from a real cross-project
+  field session) — `bclaw_dispatch_status` and the reconciler now derive liveness
+  from filesystem activity (log + worktree mtime), so a worker actively editing
+  files is no longer falsely flagged `stalled`, and known codex boot-failure
+  stderr signatures get a targeted diagnosis; briefs are transport-aware (a
+  sandboxed agent without MCP/commit gets the file protocol, not instructions it
+  can't follow), backed by a derived capability matrix
+  (`dispatchHasMcp`/`dispatchCanCommit`); `bclaw_claim` gains an advisory
+  (no-worktree) mode; `bclaw_find` payloads are size-bounded with pagination
+  metadata; an opt-in per-worktree `tsc --noEmit` pre-commit gate; gated ready
+  lanes carry a code-propagation advisory; the reconciler auto-releases the claim
+  of a run it infers failed; and `plan.related_paths` is now updatable.
+  (pln#479, pln#491, pln#527, pln#528, pln#529, trp#291, trp#431, trp#433, trp#434)
+
+### 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 +466,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

@@ -16,7 +16,7 @@ import { collectLoadValidationWarnings, findLoadValidationWarning, loadState, pe
 import { generateIdWithLabel } from '../core/ids.js';
 import { memoryExists } from '../core/io.js';
 import { generateCandidateIdWithLabel, loadCandidate, saveCandidate } from '../core/candidates.js';
-import { createEntity, getEntity, listEntities, removeEntity, transitionEntity, updateEntity, } from '../core/entity-operations.js';
+import { createEntity, getEntity, listEntities, boundListResult, removeEntity, transitionEntity, updateEntity, } from '../core/entity-operations.js';
 import { ENTITY_REGISTRY } from '../core/entity-registry.js';
 import { generateClaimId, listClaims, loadClaim, saveClaim, createCoordinatorClaim, adoptClaimSession, attachAssignmentMessageToClaim, linkClaimToAssignment, releaseClaimWithCascade } from '../core/claims.js';
 import { createSequence, updateSequence, deleteSequence } from '../core/sequence.js';
@@ -575,7 +575,7 @@ const MCP_WRITE_TOOLS = [
     },
     {
         name: 'bclaw_claim',
-        description: 'Claim a work scope (advisory lock). Automatically creates an isolated git worktree for this claim. Requires contributor trust level or above.',
+        description: 'Claim a work scope (advisory lock). By default creates an isolated git worktree for the claim (multi-agent safety). Pass advisory:true (or worktree:false) for an advisory-only lock with NO worktree — use this when the work already lives uncommitted in the main tree and a fresh worktree would be counterproductive (trp#431). Requires contributor trust level or above.',
         annotations: { tier: 'standard', category: 'coordination', headlessApproval: 'auto' },
         inputSchema: {
             type: 'object',
@@ -588,6 +588,8 @@ const MCP_WRITE_TOOLS = [
                 project: { type: 'string', description: 'Project name or path. Use this when working on a project different from the MCP server workspace (e.g. CLI agents in a different directory).' },
                 store: { type: 'string', description: 'Target store level: local (default), repo, workspace.' },
                 worktreeBranch: { type: 'string', description: 'Branch name for the worktree. Defaults to feat/<scope-slug>.' },
+                worktree: { type: 'boolean', description: 'Whether to create an isolated git worktree (default true). Pass false for an advisory-only lock with no worktree (trp#431) — for in-place work in the main tree.' },
+                advisory: { type: 'boolean', description: 'Alias for worktree:false — advisory-only lock with no worktree (trp#431).' },
                 handoffMode: { type: 'string', enum: ['self-commit', 'integrator'], description: 'Handoff mode: "self-commit" (worker commits+merges) or "integrator" (another agent reviews+merges). Default: self-commit.' },
             },
             required: ['scope', 'description'],
@@ -956,7 +958,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',
@@ -1033,7 +1035,7 @@ const MCP_WRITE_TOOLS = [
     },
     {
         name: 'bclaw_assignment_update',
-        description: 'Report assignment lifecycle status. Part of the Agent SDK runtime protocol. Workers call this to report: accepted (acknowledging receipt), started (work begun), progress (heartbeat), completed (done with artifacts), failed (error), or blocked (external blocker). The assignment_id is provided in the dispatch brief.',
+        description: 'Report assignment lifecycle status. Part of the Agent SDK runtime protocol. Workers call this to report: accepted (acknowledging receipt), started (work begun), progress (heartbeat), completed (done with artifacts), failed (error), or blocked (external blocker). The assignment_id is provided in the dispatch brief. OWNERSHIP (trp#291): only the agent the assignment is OWNED BY (the dispatched worker) may update it — a different agent (e.g. the coordinator) gets `Agent <x> cannot update assignment owned by <y>`. If you are the coordinator and need to converge a worker run, do NOT call this; verify via bclaw_dispatch_status instead (the reconciler infers completion from sentinels/commits).',
         annotations: { tier: 'standard', category: 'coordination', headlessApproval: 'auto' },
         inputSchema: {
             type: 'object',
@@ -1111,7 +1113,7 @@ const MCP_WRITE_TOOLS = [
     // Promoted to `standard` tier at the v1.0 cut.
     {
         name: 'bclaw_find',
-        description: 'Canonical list query over a brainclaw entity. Default read filter excludes records with provenance.kind="legacy" and auto_reflect records below 0.6 confidence — override via filter.includeLegacy / filter.minAutoReflectConfidence. Tag filters accept `tag: string` for one tag or `tags: string[]` for any-match. For entity="agent_run", filters also accept assignment_id, claim_id, and message_id. Pass `project` to query a linked project instead of the current one.',
+        description: 'Canonical list query over a brainclaw entity. Default read filter excludes records with provenance.kind="legacy" and auto_reflect records below 0.6 confidence — override via filter.includeLegacy / filter.minAutoReflectConfidence. Tag filters accept `tag: string` for one tag or `tags: string[]` for any-match. For entity="agent_run", filters also accept assignment_id, claim_id, and message_id. Pass `project` to query a linked project instead of the current one. PAGINATION & SIZE (pln#491): returns at most filter.limit items (default 50), and the page is additionally shrunk if it would exceed the MCP size budget. The response carries `total` (full match count), `returned`, and — when more remain — `has_more: true`, `next_offset`, and a `hint`; pass `filter.offset=<next_offset>` (or a narrower filter) to page rather than expecting everything at once. ORDERING: results follow on-disk/load order, NOT recency — do not assume the first item is the newest (trp#291); filter explicitly (e.g. status, plan_id) to target what you need.',
         annotations: { tier: 'standard', category: 'memory', headlessApproval: 'auto' },
         inputSchema: {
             type: 'object',
@@ -2906,9 +2908,13 @@ async function _executeMcpToolCallInner(payload) {
             const claimId = generateClaimId();
             let worktreePath;
             let worktreeWarn = '';
-            // Always create worktree in MCP context for multi-agent isolation.
-            // The createWorktree param is no longer exposed in the schema.
-            {
+            // trp#431: advisory mode skips worktree creation. Default is to create an
+            // isolated worktree (multi-agent safety), but when the work already lives
+            // (uncommitted) in the main tree a fresh worktree is counterproductive and
+            // the agent ends up skipping the claim. Pass advisory:true (or
+            // worktree:false) for an advisory-only lock with no worktree.
+            const advisoryClaim = args.advisory === true || args.worktree === false;
+            if (!advisoryClaim) {
                 const branchSlug = claimScope.replace(/[^a-zA-Z0-9._-]/g, '-').replace(/-+/g, '-').slice(0, 48);
                 const worktreeBranch = args.worktreeBranch?.trim() || `feat/${branchSlug}`;
                 try {
@@ -5788,6 +5794,12 @@ async function _executeMcpToolCallInner(payload) {
                     };
                 }
                 const result = listEntities(entity, targetCwd, filter);
+                // pln#491 — bound the payload (count is already capped by applyPaging;
+                // this caps SIZE) so a verbose result set never overflows the MCP token
+                // cap and silently pushes the agent to the CLI (trp#449). Advertises
+                // has_more / next_offset / hint for explicit pagination.
+                const offset = Math.max(0, Number(filter.offset) || 0);
+                const bounded = boundListResult(result, offset);
                 const warnings = collectLoadValidationWarnings(entity, targetCwd);
                 // structuredContent is the canonical MCP return channel that clients
                 // (VS Code extension, Codex, etc.) read for machine-parseable data.
@@ -5795,10 +5807,11 @@ async function _executeMcpToolCallInner(payload) {
                 // response body, which got dropped by the MCP protocol wrapper so
                 // `result.items` arrived as undefined on the client — the root cause
                 // of the VS Code Backlog section rendering empty.
+                const moreNote = bounded.has_more ? ` (returned ${bounded.returned}; ${result.total - bounded.returned} more — offset ${bounded.next_offset})` : '';
                 return {
                     response: toolResponse({
-                        content: [{ type: 'text', text: `✔ ${result.total} ${entity} item(s)` }],
-                        structuredContent: { ...result, warnings },
+                        content: [{ type: 'text', text: `✔ ${result.total} ${entity} item(s)${moreNote}` }],
+                        structuredContent: { ...bounded, warnings },
                     }),
                 };
             }

package/dist/core/agent-capability.js

@@ -664,6 +664,34 @@ export function resolveBriefMode(agentName) {
         return 'compact';
     return 'full';
 }
+// ── Dispatch-time capability matrix (pln#528) ──────────────────────────────
+/**
+ * pln#528 — capability matrix DERIVED from the spawn template, so it stays in
+ * sync with how each agent is actually invoked (no per-profile duplication).
+ *
+ * The motivating reality (debrief LeaseUp): codex is spawned with
+ * `--sandbox workspace-write`, which (a) does NOT wire the brainclaw MCP server
+ * and (b) puts `.git` outside the sandbox root — so a sandboxed worker can
+ * neither call `bclaw_*` nor `git commit`, regardless of the profile's nominal
+ * `runtime.mcp_direct` flag. These helpers expose that so the brief / handoff /
+ * harvest logic can adapt to the transport instead of issuing instructions the
+ * worker cannot follow.
+ */
+export function isSandboxedSpawn(profile) {
+    return /--sandbox\b/.test(profile.invoke_template ?? '');
+}
+/** Whether the agent, AS SPAWNED by the dispatcher, can reach brainclaw MCP. */
+export function dispatchHasMcp(profile) {
+    return profile.runtime.mcp_direct && !isSandboxedSpawn(profile);
+}
+/**
+ * Whether the spawned worker can `git commit`. A sandbox whose root excludes
+ * `.git` cannot — the coordinator must integrate the worker's output instead of
+ * relying on a self-commit handoff.
+ */
+export function dispatchCanCommit(profile) {
+    return !isSandboxedSpawn(profile);
+}
 // ── getDefaultInvokeTemplate ───────────────────────────────────────────────
 /**
  * Get the default invoke template for an agent.