brainclaw 1.7.5 → 1.9.0

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.5 on 2026-06-09T05:31:24.417Z
+// Source: brainclaw v1.9.0 on 2026-06-15T14:49:43.510Z
 export const FACTS = {
-  "version": "1.7.5",
-  "generated_at": "2026-06-09T05:31:24.417Z",
+  "version": "1.9.0",
+  "generated_at": "2026-06-15T14:49:43.510Z",
   "tools": {
     "count": 62,
     "published_count": 61,
@@ -197,8 +197,8 @@ export const FACTS = {
         "workflow_model": "interactive",
         "tier": "A",
         "has_mcp": true,
-        "has_hooks": true,
-        "has_skills": true,
+        "has_hooks": false,
+        "has_skills": false,
         "has_rules": true,
         "instruction_file": ".clinerules/brainclaw.md",
         "mcp_config_scope": "project",
@@ -214,7 +214,7 @@ export const FACTS = {
         "workflow_model": "task-based",
         "tier": "A",
         "has_mcp": true,
-        "has_hooks": true,
+        "has_hooks": false,
         "has_skills": true,
         "has_rules": true,
         "instruction_file": "AGENTS.md",
@@ -436,8 +436,8 @@ export const FACTS = {
         "workflow_model": "interactive",
         "tier": "A",
         "has_mcp": true,
-        "has_hooks": true,
-        "has_skills": true,
+        "has_hooks": false,
+        "has_skills": false,
         "has_rules": true,
         "instruction_file": ".windsurfrules",
         "mcp_config_scope": "machine",

package/dist/facts.json

@@ -1,6 +1,6 @@
 {
-  "version": "1.7.5",
-  "generated_at": "2026-06-09T05:31:24.417Z",
+  "version": "1.9.0",
+  "generated_at": "2026-06-15T14:49:43.510Z",
   "tools": {
     "count": 62,
     "published_count": 61,
@@ -195,8 +195,8 @@
         "workflow_model": "interactive",
         "tier": "A",
         "has_mcp": true,
-        "has_hooks": true,
-        "has_skills": true,
+        "has_hooks": false,
+        "has_skills": false,
         "has_rules": true,
         "instruction_file": ".clinerules/brainclaw.md",
         "mcp_config_scope": "project",
@@ -212,7 +212,7 @@
         "workflow_model": "task-based",
         "tier": "A",
         "has_mcp": true,
-        "has_hooks": true,
+        "has_hooks": false,
         "has_skills": true,
         "has_rules": true,
         "instruction_file": "AGENTS.md",
@@ -434,8 +434,8 @@
         "workflow_model": "interactive",
         "tier": "A",
         "has_mcp": true,
-        "has_hooks": true,
-        "has_skills": true,
+        "has_hooks": false,
+        "has_skills": false,
         "has_rules": true,
         "instruction_file": ".windsurfrules",
         "mcp_config_scope": "machine",

package/docs/PROTOCOL.md

@@ -0,0 +1,223 @@
+# Brainclaw Protocol — v0.1 (draft)
+
+> Status: **draft** — pre-public RFC. Versioned in [docs/PROTOCOL.md](./PROTOCOL.md);
+> brainclaw is the reference implementation.
+>
+> Feedback target: external OSS agent integrators (Cline, OpenCode, Hermes,
+> Mistral Vibe, Continue) — see "Feedback wanted" at the bottom.
+
+## 1. What this spec is
+
+Brainclaw runs a multi-agent coordination loop on top of a shared project
+memory. The implementation has converged on a small grammar — entities, verbs,
+lifecycle sentinels — that the rest of the system (CLI, MCP server, writers,
+hooks) is just a delivery channel for.
+
+This document carves out that grammar as a **transport-agnostic protocol** so
+other agents and agent platforms can either:
+
+  - speak it natively (via brainclaw's MCP server, the reference transport), or
+  - implement it themselves and interoperate with brainclaw-managed projects.
+
+The protocol does **not** standardize storage, file layouts, or the internal
+state machine. Those are implementation details; brainclaw's are documented
+under [`docs/concepts/`](./concepts/).
+
+## 2. Versioning
+
+| Field             | Rule                                                                    |
+|-------------------|-------------------------------------------------------------------------|
+| `protocol.major`  | Bumped only for breaking entity / verb / sentinel changes.              |
+| `protocol.minor`  | Bumped for additive entities, verbs, sentinels, or new optional fields. |
+| `protocol.patch`  | Editorial / clarifying changes; no behavioral impact.                   |
+
+Current draft: **0.1** — entity surface stable; verb surface stable on the
+"canonical grammar" (see §4); lifecycle sentinels stable for sessions, claims,
+plans, assignments. Coordination / loop verbs are explicitly experimental.
+
+Implementers SHOULD advertise the maximum supported version via an
+`X-Brainclaw-Protocol` header (HTTP transports) or a server-info field
+(MCP transports). Brainclaw's MCP server returns `0.1` in `serverInfo.version`.
+
+## 3. Entities
+
+The protocol recognises eight kinds of memory objects. Each has a unique `id`,
+a canonical `kind`, and a small set of mutable fields. Storage of additional
+fields is implementation-defined.
+
+| Kind         | Purpose                                                              | Lifecycle states                                        |
+|--------------|----------------------------------------------------------------------|---------------------------------------------------------|
+| `constraint` | Active rule the project must respect.                                | `active` → `resolved` / `expired`                       |
+| `decision`   | Recorded architectural / process decision.                           | `pending` → `approved` / `rejected` / `deferred`         |
+| `trap`       | Known failure mode; reminder for future work.                        | `active` → `resolved` / `expired`                       |
+| `plan`       | Unit of work tracked across agents.                                  | `open` → `in_progress` → `done` / `cancelled`           |
+| `claim`      | Mutex over a file scope.                                             | `open` → `released` (or `expired` via TTL)              |
+| `handoff`    | Asynchronous instruction from one agent to another.                  | `open` → `accepted` → `closed`                          |
+| `candidate`  | Proposed memory item awaiting review.                                | `proposed` → `accepted` / `rejected` / `merged`         |
+| `assignment` | Dispatched work item routed to a specific agent.                     | `offered` → `accepted` → `started` → `completed` / `failed` / `blocked` / `cancelled` |
+
+Entities have these well-known fields (implementations MAY add more):
+
+```
+id          string   // implementation-assigned, opaque, stable
+kind        string   // one of the kinds above
+status      string   // one of the lifecycle states above
+text        string?  // human-readable summary
+tags        string[]?
+created_at  string   // ISO-8601 UTC
+updated_at  string   // ISO-8601 UTC
+provenance  object?  // {kind: 'agent'|'human'|'auto'|'legacy', author, source}
+```
+
+Brainclaw's full field set lives in [`src/core/schema.ts`](../src/core/schema.ts).
+Future protocol minors will promote additional fields to "well-known" as they
+prove portable across implementations.
+
+## 4. The canonical grammar (verbs)
+
+The protocol exposes seven canonical verbs. Implementations MUST support these
+in order to claim protocol compliance. They are deliberately narrow so the
+surface stays small; richer ergonomic helpers are facades on top.
+
+| Verb              | Shape                                                          | Effect                                                  |
+|-------------------|-----------------------------------------------------------------|---------------------------------------------------------|
+| `work(intent)`    | `intent: consult \| execute \| resume \| review`                 | Open a session; optionally claim a scope.               |
+| `context(kind)`   | `kind: memory \| execution \| board \| delta`                    | Read shared state.                                      |
+| `find(entity, …)` | `entity, filter, limit`                                         | Query entities.                                         |
+| `get(entity, id)` | `entity, id` (or `short_label`)                                 | Fetch one entity by identifier.                         |
+| `create(entity)`  | `entity, data`                                                  | Insert a new entity (validated against schema).         |
+| `update(entity)`  | `entity, id, patch`                                             | Patch mutable fields. Status changes go via `transition`. |
+| `transition(…)`   | `entity, id, status`                                            | Move an entity along its lifecycle. Triggers side-effects. |
+
+The reference implementation surfaces these as MCP tools named
+`bclaw_work`, `bclaw_context`, `bclaw_find`, `bclaw_get`, `bclaw_create`,
+`bclaw_update`, `bclaw_transition`. The same names appear in
+`src/commands/mcp.ts:MCP_CANONICAL_GRAMMAR_TOOL_NAMES` and are derived from
+the tool catalog, not hand-curated. Hermes and other narrow-surface agents
+include exactly this set in their MCP `tools.include`.
+
+### 4.1 Coordination verbs (experimental — protocol v0.2 candidates)
+
+These are present in the reference implementation but **not yet stable**.
+Implementations MAY support them but should expect breaking changes:
+
+  - `coordinate(intent: assign|consult|review|reroute)` — multi-agent routing.
+  - `dispatch(plan, agents)` — concrete spawn / claim ledger.
+  - `loop(kind: ideation|implementation|review)` — multi-round loops.
+
+## 5. Lifecycle sentinels
+
+The protocol defines **named state transitions** so any compliant agent can
+reason about another's progress without parsing free-form text. These are the
+strings agents are expected to emit at protocol-defined moments.
+
+### 5.1 Session sentinels
+
+| Moment                | Sentinel                                                              |
+|-----------------------|-----------------------------------------------------------------------|
+| Agent reaches its loop | Filesystem heartbeat: `.brainclaw-heartbeat-<assignment_id>`           |
+| Session opens         | `work(intent)` response carries the `session_id` and seed context.    |
+| Session ends          | `work(intent: …)` is terminal; or implementation-specific close call. |
+
+### 5.2 Assignment sentinels
+
+The lifecycle a coordinator can observe on a dispatched assignment:
+
+```
+offered → accepted → started → (progress)* → completed
+                                             | failed
+                                             | blocked
+                                             | cancelled
+```
+
+Each transition is emitted via `transition('assignment', id, <status>)`.
+A worker that cannot reach the protocol transport (sandboxed) MAY drop a
+`LANE-RESULT.json` file at the worktree root as the fallback signal — the
+coordinator harvests it.
+
+### 5.3 Claim sentinels
+
+```
+open → released         (worker calls transition('claim', id, 'released'))
+open → expired          (TTL-driven; reaper marks expired)
+```
+
+A claim that converged on `done` MAY carry a `planStatus` hint so the
+coordinator updates the linked plan atomically with the release.
+
+### 5.4 Plan-step sentinels
+
+Plans contain ordered steps with their own status. The grammar verbs
+`update('plan', id, {steps:[…]})` and `transition('plan', id, 'done')`
+operate over the whole plan; the canonical step sentinel is a step-level
+`status: done`. Implementations MAY surface `bclaw_complete_step` as a
+sugar on top.
+
+## 6. Conformance levels
+
+| Level | What conformance means                                                                 |
+|-------|----------------------------------------------------------------------------------------|
+| **L1 — Read** | Implementation can issue `work(intent: consult)` + `context` + `find` + `get` and respect active claims. Minimum bar for "I can run inside a brainclaw-managed project without breaking it." |
+| **L2 — Write** | All of L1 plus `create` / `update` / `transition` on the entities above with valid lifecycle transitions. |
+| **L3 — Coordinate** | All of L2 plus the experimental coordination verbs (§4.1) and assignment sentinels. Required for spawning / accepting dispatched work. |
+
+Hermes and Mistral Vibe ship at L1 (narrow surface). Claude Code, Codex,
+Copilot, and Cline are L3. The reference implementation enforces the
+L3 contract via assignment-convergence tests (see
+[`tests/unit/assignment-convergence.test.ts`](../tests/unit/assignment-convergence.test.ts)).
+
+## 7. Transport bindings
+
+The protocol is transport-agnostic. The reference implementation ships an
+MCP server (`brainclaw mcp`); other implementations MAY add JSON-RPC over
+stdio, HTTP, or a local IPC socket without changing the entity / verb /
+sentinel surface.
+
+A transport binding MUST specify:
+
+  - how the seven canonical verbs are named (mapping to the binding's call shape),
+  - how entity identifiers are serialised (recommend opaque strings),
+  - how lifecycle sentinels are encoded (recommend `transition` calls,
+    not free-form status strings).
+
+## 8. Storage and federation
+
+Out of scope for v0.1. The reference implementation uses git-backed
+JSON/YAML in `.brainclaw/`. Multi-project federation is a planned
+extension — see [docs/concepts/](./concepts/) and the brainclaw memory
+files for the current direction. A future protocol version will define
+the wire format for cross-project signaling.
+
+## 9. Reference implementation map
+
+| Protocol concept              | Reference implementation in brainclaw                                 |
+|-------------------------------|-----------------------------------------------------------------------|
+| Entity schemas                | [`src/core/schema.ts`](../src/core/schema.ts)                          |
+| Canonical grammar tool set    | [`src/commands/mcp.ts`](../src/commands/mcp.ts) — `MCP_CANONICAL_GRAMMAR_TOOL_NAMES` |
+| MCP tool catalog              | [`src/commands/mcp.ts`](../src/commands/mcp.ts) — `ALL_TOOLS`          |
+| Per-agent writer wiring       | [`src/core/agent-files.ts`](../src/core/agent-files.ts) — `AGENT_WIRING_REGISTRY` |
+| Capability profiles           | [`src/core/agent-capability.ts`](../src/core/agent-capability.ts)       |
+| Assignment lifecycle          | [`src/core/assignments.ts`](../src/core/assignments.ts) + [`tests/unit/assignment-convergence.test.ts`](../tests/unit/assignment-convergence.test.ts) |
+| Claim lifecycle / TTL         | [`src/core/claims.ts`](../src/core/claims.ts)                          |
+
+## 10. Feedback wanted
+
+The following questions are open for v0.2. We're soliciting input from agent
+integrators before declaring any of them stable:
+
+  1. **Coordination verb shape (§4.1)** — should `coordinate(intent: assign|…)`
+     stay as a single verb with an intent enum, or split into named verbs
+     (`assign`, `reroute`, `review_request`) per L3 capability?
+  2. **Sentinel transport for sandboxed workers** — the `LANE-RESULT.json`
+     fallback file is brainclaw-specific. Is there an interest in
+     standardising a "filesystem fallback" format so any coordinator can
+     harvest results from any sandboxed worker?
+  3. **Entity field portability** — which fields beyond the well-known set
+     (§3) are universal enough to promote in v0.2? Candidates: `severity`,
+     `priority`, `category`, `effort_minutes`, `assignee`.
+  4. **L1-only adoption surface** — would a CLI-only L1 reference (no MCP
+     dependency) lower the adoption bar for OSS agents that don't speak MCP
+     yet?
+
+Open an issue, ping `ai@thomgroup.com`, or comment on the brainclaw plan
+tracking this draft (pln#546).

package/docs/cli.md

@@ -276,9 +276,9 @@ Preservation guarantees: the repair module never calls `unlink`/`rm`/`rmdir`. Un
 
 Today the flow covers missing entity subdirectories (`mkdir` action) and inbox hygiene (`move_inbox_message`, `quarantine_inbox_message`). More actions — orphaned agent references, mixed-version drift — land as additional repair candidates emitted by `doctor`.
 
-### `brainclaw rebuild`
-
-Regenerate `project.md` from canonical state. No options.
+### `brainclaw rebuild`
+
+Regenerate the legacy `.brainclaw/project.md` readable summary from canonical state. No options. This file is derived and does not replace the root `PROJECT.md` project vision or live coordination surfaces such as `agent-board`.
 
 ```bash
 brainclaw rebuild
@@ -1500,7 +1500,7 @@ Export memory as a native agent instruction file.
 
 | Option | Description |
 |---|---|
-| `--format <format>` | Target format: `copilot-instructions`, `cursor-rules`, `agents-md`, `claude-md`, `gemini-md`, `windsurf`, `cline`, `roo`, or `continue` |
+| `--format <format>` | Target format: `copilot-instructions`, `cursor-rules`, `agents-md`, `claude-md`, `gemini-md`, `windsurf`, `cline`, `roo`, `continue`, `openclaw`, `nanoclaw`, `nemoclaw`, `picoclaw`, or `zeroclaw` |
 | `--detect` | Auto-detect the running agent and write to its native file |
 | `--all` | Write all known agent instruction files at once (deduplicates by format) |
 | `--write` | Write output to the native file path (instead of stdout); generated workspace files are treated as local and added to `.gitignore` |
@@ -1518,12 +1518,13 @@ brainclaw export --format cursor-rules --write           # .cursor/rules/braincl
 brainclaw export --format windsurf --write               # .windsurfrules
 brainclaw export --format cline --write                  # .clinerules/brainclaw.md
 brainclaw export --format agents-md --write              # AGENTS.md (Codex, OpenCode)
-brainclaw export --format roo --write                    # .roo/rules/brainclaw.md
-brainclaw export --format continue --write               # .continue/rules/brainclaw.md
-brainclaw export --format claude-md --write --shared     # publish CLAUDE.md intentionally
-brainclaw export --format claude-md                      # stdout
-brainclaw export --all                                   # all 9 agent files at once
-```
+brainclaw export --format roo --write                    # .roo/rules/brainclaw.md
+brainclaw export --format continue --write               # .continue/rules/brainclaw.md
+brainclaw export --format openclaw --write               # skills/openclaw/SKILL.md
+brainclaw export --format claude-md --write --shared     # publish CLAUDE.md intentionally
+brainclaw export --format claude-md                      # stdout
+brainclaw export --all                                   # all known agent files at once
+```
 
 `brainclaw export --write` is local-first by default: the generated workspace file and any companion MCP/settings files are added to `.gitignore`. Use `--shared` only when you intentionally want the main instruction file to be committed. `brainclaw export --detect` also writes companion MCP config where relevant, including `opencode.json` for OpenCode and `.gemini/antigravity/mcp_config.json` for Antigravity/Gemini when the local environment is available.
 

package/docs/concepts/coordinator-runbook.md

@@ -0,0 +1,129 @@
+# Coordinator runbook
+
+Operational procedures for running multi-agent dispatches, distilled from the
+2026-06-10 coordination session (pln#554). Audience: the coordinator — human or
+agent — who dispatched workers and now has to triage what came back (or didn't).
+
+Rule zero across everything below: **evidence before verdict**. Administrative
+status (assignment/run records) is the WEAKEST signal; worker-written results
+and git state are the strongest. Acting on administrative status alone expired
+live workers three times in one night (can_948acfd6).
+
+## 1. Baseline triage — is it actually a regression?
+
+Before calling anything a regression, run the exact same check on the
+pre-change ref. Twice in the 2026-06-10 session a "sprint-1 regression" turned
+out to be a bug that had always existed — manual workflows had simply masked it
+(see also trap: bisect state before code).
+
+Procedure:
+
+1. Reproduce the failure on the current ref. Capture the command verbatim.
+2. `git stash` nothing, delete nothing — check out the pre-change ref in a
+   SEPARATE worktree (`git worktree add ../baseline <ref>`).
+3. Run the same command there.
+   - Fails on the baseline too → not a regression. Re-scope the bug, exonerate
+     the change, and continue the dispatch.
+   - Passes on the baseline → real regression; only now is bisecting the diff
+     worth the time.
+4. Before bisecting code at all, read the historical ENTITY state first
+   (assignment / event / completed_at records): the May 2026 codex
+   `run_completed` "regression" was state drift, not code.
+
+## 2. Dead-worker decision tree
+
+A worker looks dead (stale heartbeat, exited process, expired assignment).
+Collect worktree evidence BEFORE any kill / reroute / re-dispatch — recovery is
+cheap, a wrongly killed worker is not.
+
+```
+worker presumed dead
+│
+├─ 1. LANE-RESULT.json at the worktree root?
+│     yes → it FINISHED. `brainclaw harvest <asgn> [--integrate]`. Done.
+│
+├─ 2. git evidence (shared helper: commits_ahead + dirty_tracked,
+│     surfaced by dispatch-status / dispatch watch):
+│     commits ahead + CLEAN tracked tree
+│        → worker delivered, only exit formalities missing.
+│          Harvest/merge it. NEVER kill-and-reroute a delivered lane.
+│
+├─ 3. dirty tracked files? → work in flight. Check liveness before declaring death:
+│     ├─ fs mtime fresh (logs/worktree written < ~5 min)? → ALIVE, leave it.
+│     ├─ real agent child process under the wrapper pid?
+│     │   (wrapper alive + child gone = abrupt death; orphaned grandchildren
+│     │   hold the pipes open so the wrapper never emits a sentinel)
+│     └─ both dead + fs stale → recover, do not re-dispatch blind:
+│           `brainclaw harvest <asgn> --orphaned`
+│           (typecheck if possible → commit on-behalf with the standard
+│            marker → lifecycle → release claim → run targeted tests + merge)
+│
+└─ 4. clean tree, no commits ahead, no result → nothing to recover.
+      Now (and only now) reroute / re-dispatch.
+```
+
+Hard rules:
+
+- Never delete or reset a worktree during triage — the diff on disk IS the
+  recovery (twice on 2026-06-10: 42 and 41 files recovered, zero loss).
+- Never kill processes by name; source the pid from agent_run.pid and
+  cross-check launched_at (the operator's IDE runs the same binaries).
+- A failed observation is not evidence: "could not probe the child process"
+  must never be read as "the child is dead".
+
+## 3. Post-dispatch verification reflex
+
+Delivery is not execution. `delivered_and_started` means the message landed and
+a process spawned — not that the worker reached its work loop.
+
+After every dispatch:
+
+1. `bclaw_dispatch_status(target_id: <asgn|clm|run>)` — one call resolves the
+   assignment, claim, run, heartbeat, logs, lane-result, and git evidence into
+   a single health verdict + next action.
+2. Or query directly: `bclaw_find(entity: "agent_run", message_id: <msg>)` —
+   no run record means the spawn never produced a process.
+3. Expect the step-0 heartbeat (`.brainclaw-heartbeat-<asgn>` at the worktree
+   root) within the first minutes. Missing heartbeat + no fs activity = the
+   worker never reached its loop; check the captured stderr for boot
+   signatures (model/config mismatches are diagnosed by dispatch-status).
+
+Known gap: `intent=ideate` dispatches are inbox-only (can_29f1e1ac) — there is
+no agent_run to verify; track those by reply message, not by run records.
+
+## 4. `brainclaw dispatch watch` — monitor contract
+
+Blocking watch over one dispatch; encodes the decision tree above as a poller.
+
+```
+brainclaw dispatch watch <asgn_|clm_|run_> [--interval 60] [--timeout 90] [--base master] [--json]
+```
+
+Exit codes (script on these, not on the log text):
+
+| code | state                | meaning / next action                                   |
+|------|----------------------|---------------------------------------------------------|
+| 0    | done                 | lane-result, run completed, or committed-clean → harvest |
+| 2    | timeout              | worker still running at --timeout → re-run or inspect    |
+| 3    | failed               | lane-result/run reported failure → read stderr, fix      |
+| 4    | worker-process-gone  | dead with uncommitted work → `harvest --orphaned`        |
+| 5    | unresolved           | target id did not resolve to anything                    |
+
+Evidence priority inside the watch (strongest first): worker-written results >
+git evidence > process evidence > administrative status. Fresh filesystem
+activity vetoes process-gone verdicts (a stale tracked pid after a manual
+respawn must not kill a worker that is visibly writing).
+
+## Cross-references
+
+- can_948acfd6 — assignment expired while the worker was delivering; git
+  evidence outranks administrative status.
+- can_d622e024 — claude -p "delivered-but-end-stalled": committed-clean is done.
+- can_9458576e — wrapper-alive/child-dead death mode (orphaned pipe holders).
+- can_29f1e1ac — intent=ideate is inbox-only; no run record to verify.
+- cnd_asgn_7336aa79_heartbeat_sandbox / can_asgn_b0169fd8_heartbeat — sandboxes
+  refuse absolute heartbeat paths; briefs point sandboxed workers at a
+  worktree-relative path.
+- trap: agent shell env contaminates tests — strip BRAINCLAW_CWD/_AGENT before
+  running suites from an agent shell.
+- docs/concepts/dispatch-lifecycle.md — full entity/FSM model behind all of this.

package/docs/concepts/dispatch-lifecycle.md

@@ -150,6 +150,23 @@ You called `bclaw_coordinate(intent="review", open_loop=true, …)` and got back
 
 ---
 
+## Worktree-as-contract harvest
+
+Some dispatched workers cannot self-commit or call MCP. For example, a sandboxed Codex run may have `dispatchCanCommit=false` because its writable root is the linked worktree, while `.git` lives outside that root. In that case the worker contract is intentionally small:
+
+1. Edit files inside the dispatched worktree.
+2. Write `LANE-RESULT.json` at the worktree root.
+
+The worker does not need to commit, call `bclaw_assignment_update`, or release the claim itself. The worktree is the contract.
+
+When the coordinator runs `brainclaw harvest <assignment_id> --integrate`, brainclaw reads the worker's `LANE-RESULT.json`, commits the linked worktree diff on the worker's behalf onto the lane branch, then completes the assignment and releases the claim, including the normal plan-status cascade.
+
+The on-behalf commit is guarded by the linked-worktree check (`isLinkedWorktree`): integration only targets the worktree associated with the assignment, never the main repository. This keeps sandboxed-worker harvesting from turning into an accidental main-repo commit path.
+
+Integration is strictly additive and opt-in. Plain `brainclaw harvest <assignment_id>` remains report-only; it reads and reports the lane result without committing or mutating assignment / claim state. The on-behalf commit and lifecycle completion happen only when the coordinator passes `--integrate`.
+
+---
+
 ## Diagnostic playbook
 
 When a dispatch hangs, work top-down through these checks. For the symptom-driven variant see [troubleshooting.md#inbox-messages-stuck--brief-ack-never-arrived](troubleshooting.md#inbox-messages-stuck--brief-ack-never-arrived).