brainclaw 1.7.1 → 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,34 +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.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
@@ -428,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

@@ -30,7 +30,7 @@ import { runInstruction } from './commands/instruction.js';
 import { runListAgents } from './commands/list-agents.js';
 import { runSurfaceTaskResource } from './commands/surface-task-resource.js';
 import { runListInstructions } from './commands/list-instructions.js';
-import { runDoctor } from './commands/doctor.js';
+import { runDoctor, runDoctorSpawnCheck } from './commands/doctor.js';
 import { runRepair } from './commands/repair.js';
 import { runStale } from './commands/stale.js';
 import { runRebuild } from './commands/rebuild.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';
@@ -681,7 +681,13 @@ program
     .option('--repair', 'Rebuild dist/ when the MCP runtime is missing or stale')
     .option('--after-migration', 'Run the v1.0 post-migration health check only (exits non-zero on any failure)')
     .option('--dispatch', 'Run dispatch-health diagnostic only: reconcile open agent_runs and report stuck/unverified/silent failures (pln#496 step stp_8c072d75)')
-    .action((options) => {
+    .option('--spawn-check', 'Real spawn round-trip per installed agent before dispatch (pln#520 step 2): validates delivery + handshake on this host, exits non-zero on any installed-agent failure')
+    .option('--spawn-check-timeout <ms>', 'Per-agent timeout for --spawn-check (default 15000)', parseInt)
+    .action(async (options) => {
+    if (options.spawnCheck) {
+        await runDoctorSpawnCheck({ cwd: options.cwd, json: options.json, timeoutMs: options.spawnCheckTimeout });
+        return;
+    }
     runDoctor({ ...options, afterMigration: options.afterMigration, dispatch: options.dispatch });
 });
 // --- repair (Phase 4 Sprint 2 Lane C / pln#397) ---
@@ -1003,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')
@@ -1441,6 +1459,8 @@ dispatchCmd
     .option('--agents <names>', 'Comma-separated list of agents to dispatch to')
     .option('--lanes <names>', 'Comma-separated list of lanes to dispatch')
     .option('--max <n>', 'Maximum assignments', parseInt)
+    .option('--max-concurrency <n>', 'Opt-in cap on concurrent instances per host-binary (default: unlimited)', parseInt)
+    .option('--model <name>', 'Model to run, decoupled from agent identity (e.g. --model sonnet)')
     .option('--dry', 'Preview assignments without sending messages')
     .option('--spawn', 'Autonomously launch CLI agents with invoke templates')
     .option('--agent <name>', 'Dispatcher agent name')
@@ -1450,6 +1470,8 @@ dispatchCmd
         agents: options.agents,
         lanes: options.lanes,
         max: options.max,
+        maxConcurrency: options.maxConcurrency,
+        model: options.model,
         dry: options.dry,
         spawn: options.spawn,
         agent: options.agent,

package/dist/commands/dispatch.js

@@ -87,6 +87,8 @@ export async function runDispatch(options) {
         dryRun: options.dry,
         dispatcherAgent,
         autoExecute: options.spawn,
+        maxConcurrency: options.maxConcurrency,
+        model: options.model,
     }, effectiveCwd);
     if (!result) {
         console.log('No active sequence found.');

package/dist/commands/doctor.js

@@ -3,6 +3,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import * as childProcess from 'node:child_process';
 import { reconcileAllOpenRuns } from '../core/agentrun-reconciler.js';
+import { runSpawnCheck, renderSpawnCheckReport } from '../core/spawn-check.js';
 import { loadAgentRun } from '../core/agentruns.js';
 import { listAgentIdentities, resolveCurrentAgentIdentity } from '../core/agent-registry.js';
 import { listCapabilities as listRegistryCapabilities, listTools as listRegistryTools } from '../core/registries.js';
@@ -565,6 +566,22 @@ function renderDispatchHealthHumanReport(report) {
     }
     return lines.join('\n');
 }
+/**
+ * pln#520 step 2 — `brainclaw doctor --spawn-check`. Real spawn round-trip per
+ * installed agent on the current host. Exits non-zero if any installed agent
+ * fails (so it gates CI / a pre-dispatch pre-flight).
+ */
+export async function runDoctorSpawnCheck(options = {}) {
+    const report = await runSpawnCheck(options);
+    if (options.json) {
+        console.log(JSON.stringify(report, null, 2));
+    }
+    else {
+        console.log(renderSpawnCheckReport(report));
+    }
+    if (report.exit_code !== 0)
+        process.exit(report.exit_code);
+}
 export function runDoctor(options = {}) {
     if (options.dispatch) {
         const report = runDispatchHealthCheck(options);

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

@@ -57,6 +57,30 @@ export const SCHEMA_VERSION = '1.0.0';
 export const MCP_PROTOCOL_VERSIONS = ['2025-11-25', '2024-11-05'];
 export const MCP_SERVER_NOT_INITIALIZED = -32002;
 const MCP_RUNTIME_REPAIR_COMMAND = 'brainclaw doctor --repair';
+const SEQUENCE_ITEM_INPUT_SCHEMA = {
+    type: 'object',
+    description: 'Sequence lane item. planId is required; stepId optionally narrows dispatch/readiness to a specific plan step.',
+    properties: {
+        planId: { type: 'string', minLength: 1, description: 'Plan item ID referenced by this sequence item.' },
+        stepId: { type: 'string', minLength: 1, description: 'Optional plan step ID inside planId for step-level dispatch/readiness.' },
+        rank: { type: 'number', minimum: 1, description: 'Positive integer ordering key. Ranks must be unique within a sequence.' },
+        hard_after: {
+            type: 'array',
+            items: { type: 'string' },
+            description: 'Sequence item planId values that must complete before this item becomes ready.',
+        },
+        soft_after: {
+            type: 'array',
+            items: { type: 'string' },
+            description: 'Advisory predecessor planId values; they inform ordering but do not block readiness.',
+        },
+        lane: { type: 'string', description: 'Optional lane label used for parallel dispatch grouping and filtering.' },
+        scope_hint: { type: 'string', description: 'Optional file/path scope hint for claim and brief generation.' },
+        rationale: { type: 'string', description: 'Optional explanation for this item or dependency placement.' },
+    },
+    required: ['planId', 'rank'],
+    additionalProperties: false,
+};
 const { $defs: loopPhaseDefs, ...loopPhaseItemSchema } = generatedSchemas.LoopPhase;
 const loopSlotInputItemSchema = generatedSchemas.LoopSlotInput;
 export const MCP_READ_TOOLS = [
@@ -160,7 +184,7 @@ export const MCP_READ_TOOLS = [
     {
         name: 'bclaw_list_sequences',
         description: 'List coordination sequences with optional filters on status and id.',
-        annotations: { tier: 'advanced', category: 'coordination', headlessApproval: 'auto' },
+        annotations: { tier: 'standard', category: 'coordination', headlessApproval: 'auto' },
         inputSchema: {
             type: 'object',
             properties: {
@@ -624,7 +648,7 @@ const MCP_WRITE_TOOLS = [
     {
         name: 'bclaw_create_sequence',
         description: 'Create a coordination sequence shared by agents.',
-        annotations: { tier: 'advanced', category: 'coordination', headlessApproval: 'prompt' },
+        annotations: { tier: 'standard', category: 'coordination', headlessApproval: 'prompt' },
         inputSchema: {
             type: 'object',
             properties: {
@@ -632,7 +656,7 @@ const MCP_WRITE_TOOLS = [
                 description: { type: 'string', description: 'Optional sequence description.' },
                 status: { type: 'string', description: 'Status: draft, active, archived.' },
                 owner: { type: 'string', description: 'Optional sequence owner.' },
-                items: { type: 'array', description: 'Sequence items in rank order.', items: { type: 'object' } },
+                items: { type: 'array', description: 'Sequence items in rank order.', items: SEQUENCE_ITEM_INPUT_SCHEMA },
                 tags: { type: 'array', items: { type: 'string' }, description: 'Optional tags.' },
                 agent: { type: 'string', description: 'Agent name.' },
                 agentId: { type: 'string', description: 'Registered agent id.' },
@@ -643,7 +667,7 @@ const MCP_WRITE_TOOLS = [
     {
         name: 'bclaw_update_sequence',
         description: 'Update a coordination sequence status, metadata, or items.',
-        annotations: { tier: 'advanced', category: 'coordination', headlessApproval: 'prompt' },
+        annotations: { tier: 'standard', category: 'coordination', headlessApproval: 'prompt' },
         inputSchema: {
             type: 'object',
             properties: {
@@ -652,7 +676,7 @@ const MCP_WRITE_TOOLS = [
                 description: { type: 'string', description: 'Optional new description.' },
                 status: { type: 'string', description: 'Status: draft, active, archived.' },
                 owner: { type: 'string', description: 'Optional sequence owner.' },
-                items: { type: 'array', description: 'Optional replacement items array.', items: { type: 'object' } },
+                items: { type: 'array', description: 'Optional replacement items array.', items: SEQUENCE_ITEM_INPUT_SCHEMA },
                 tags: { type: 'array', items: { type: 'string' }, description: 'Optional replacement tags.' },
                 agent: { type: 'string', description: 'Agent name.' },
                 agentId: { type: 'string', description: 'Registered agent id.' },
@@ -754,7 +778,7 @@ const MCP_WRITE_TOOLS = [
     {
         name: 'bclaw_delete_sequence',
         description: 'Delete a sequence by ID. Requires trusted or curator trust level.',
-        annotations: { tier: 'advanced', category: 'coordination', headlessApproval: 'prompt' },
+        annotations: { tier: 'standard', category: 'coordination', headlessApproval: 'prompt' },
         inputSchema: {
             type: 'object',
             properties: {
@@ -932,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',
@@ -1092,7 +1116,7 @@ const MCP_WRITE_TOOLS = [
         inputSchema: {
             type: 'object',
             properties: {
-                entity: { type: 'string', description: 'Entity name: plan | decision | constraint | trap | handoff | runtime_note | candidate | claim | action | assignment | agent_run | cross_project_link. Others not yet wired.' },
+                entity: { type: 'string', description: 'Entity name: plan | decision | constraint | trap | handoff | runtime_note | candidate | sequence | claim | action | assignment | agent_run | cross_project_link. Others not yet wired.' },
                 filter: { type: 'object', description: 'Filter keys: status, tag (single tag), tags (array, any-match), author, plan_id, source, auto_generated, limit, offset, includeLegacy (bool, default false), minAutoReflectConfidence (0-1, default 0.6). entity=agent_run also accepts assignment_id, claim_id, message_id.' },
                 project: { type: 'string', description: 'Optional: name (or path/basename) of a linked project to query. Defaults to the current project. Only cross_project_links (config.yaml) and workspace store-chain children are accepted — list with `brainclaw link list`.' },
             },