brainclaw 1.14.0 → 1.16.0

package/dist/core/worktree.js

@@ -25,17 +25,38 @@ function gitPath(p) {
  * landed on the dot before `astro`, yielding `…IntegrationHubPage.` — a trailing
  * dot git rejects (`fatal: not a valid branch name`). Truncating first, then
  * stripping, guarantees the cap can never re-introduce an invalid ref.
+ *
+ * trp#950 (dogfood 2026-07-15): a plain truncation makes two DISTINCT scopes
+ * that share a >48-char prefix collapse to the SAME branch → same worktree path
+ * → the second claim/assign is refused. When (and only when) the cleaned slug
+ * exceeds the cap, a deterministic 8-char digest of the FULL cleaned slug is
+ * appended so distinct scopes diverge, while the same scope stays stable
+ * (resume/re-assign still resolves its worktree). Short scopes are unchanged.
+ * 8 hex chars = 32 bits: comfortably collision-safe for the realistic case
+ * (a handful of scopes sharing a deep directory prefix) while keeping a
+ * 39-char readable head.
  */
+const BRANCH_COMPONENT_CAP = 48;
 export function sanitizeBranchComponent(raw, fallback = 'scope') {
-    let slug = raw
+    const cleaned = raw
         .replace(/[\s~^:?*[\]\\]/g, '-') // chars forbidden by check-ref-format
         .replace(/@\{/g, '-') // reflog syntax
         .replace(/\.\.+/g, '.') // no double dots
         .replace(/[^a-zA-Z0-9._-]/g, '-') // conservative whitelist for the rest
         .replace(/-+/g, '-') // collapse dashes
-        .replace(/^[.-]+/, '') // no leading dot/dash
-        .slice(0, 48) // length cap BEFORE the trailing strips
-        .replace(/[.-]+$/, ''); // no trailing dot/dash (cut may have made one)
+        .replace(/^[.-]+/, ''); // no leading dot/dash
+    let slug;
+    if (cleaned.length <= BRANCH_COMPONENT_CAP) {
+        slug = cleaned.replace(/[.-]+$/, ''); // no trailing dot/dash
+    }
+    else {
+        // Truncation drops characters → reserve room for a collision-resistant
+        // suffix derived from the full cleaned slug (trp#950). The digest is hex, so
+        // it can never re-introduce a trailing dot/dash or a `.lock` suffix.
+        const suffix = crypto.createHash('sha1').update(cleaned).digest('hex').slice(0, 8);
+        const head = cleaned.slice(0, BRANCH_COMPONENT_CAP - suffix.length - 1).replace(/[.-]+$/, '');
+        slug = `${head}-${suffix}`;
+    }
     if (/\.lock$/i.test(slug))
         slug = slug.slice(0, -'.lock'.length).replace(/[.-]+$/, '');
     if (!slug)
@@ -348,14 +369,42 @@ export function commitWorktreeOnBehalf(worktreePath, message, options = {}) {
         return { committed: false, files_changed: [], reason: 'worktree clean — nothing to commit' };
     }
     // Stage everything, then UNSTAGE the transient files that must never land on
-    // the lane branch: the worker's own `LANE-RESULT.json` report and any
-    // `.brainclaw/` coordination state. Committing those would pollute the branch
-    // (and master, on merge) with non-deliverable artefacts.
+    // the lane branch: the worker's own `LANE-RESULT.json` report, any
+    // `.brainclaw/` coordination state, and the `.brainclaw-worktree.json` marker.
+    // Committing those would pollute the branch (and master, on merge) with
+    // non-deliverable artefacts — a field report (Codex on macOS) caught them
+    // landing in a lane commit (trp_01a2ba2a). `.brainclaw-worktree.json` sits at
+    // the worktree ROOT (NOT inside `.brainclaw/`), so the `.brainclaw` pathspec
+    // does not cover it — it needs its own entry. These are ALWAYS transient, so
+    // the unstage is unconditional.
     const add = runGit(['add', '-A'], worktreePath);
     if (!add.ok) {
         return { committed: false, files_changed: [], reason: `git add failed: ${add.stderr.trim()}` };
     }
-    runGit(['reset', '-q', '--', 'LANE-RESULT.json', '.brainclaw', '.brainclaw-heartbeat-*'], worktreePath);
+    runGit([
+        'reset', '-q', '--',
+        'LANE-RESULT.json',
+        '.brainclaw',
+        '.brainclaw-worktree.json',
+        '.brainclaw-heartbeat-*',
+    ], worktreePath);
+    // node_modules needs a TRACKED-AWARE exclusion (Codex review of #88, BLOCKING).
+    // Unstage the links/dirs brainclaw provisions — but a project that VENDORS
+    // node_modules tracks those files, and a worker's change to a TRACKED
+    // node_modules file is a REAL deliverable; dropping it would silently omit
+    // work. Strategy: unstage every node_modules path, then RE-ADD only the ones
+    // already tracked at HEAD and modified/deleted (never the fresh provisioned
+    // link/dir, which is `A` vs HEAD). The component-bounded pathspecs never match
+    // a similarly-named deliverable such as `src/node_modules_helper.ts` — the
+    // plain `node_modules` is root-leading-dir only, the `:(glob)` forms match the
+    // `node_modules` path component exactly (nested link entry + nested contents).
+    const NODE_MODULES_SPECS = ['node_modules', ':(glob)**/node_modules', ':(glob)**/node_modules/**'];
+    runGit(['reset', '-q', '--', ...NODE_MODULES_SPECS], worktreePath);
+    const trackedNm = runGit(['diff', '--name-only', '--diff-filter=MD', 'HEAD', '--', ...NODE_MODULES_SPECS], worktreePath);
+    const keepNm = trackedNm.stdout.split(/\r?\n/).map((l) => l.trim()).filter(Boolean);
+    if (keepNm.length > 0) {
+        runGit(['add', '--', ...keepNm], worktreePath);
+    }
     // The files actually staged for this commit (post-exclusion) — also the
     // truthful files_changed report.
     const staged = runGit(['diff', '--cached', '--name-only'], worktreePath);
@@ -364,7 +413,7 @@ export function commitWorktreeOnBehalf(worktreePath, message, options = {}) {
         // Only transient files changed — nothing deliverable to commit. Restore the
         // index so the worktree is left exactly as the worker left it.
         runGit(['reset', '-q'], worktreePath);
-        return { committed: false, files_changed: [], reason: 'no committable changes (only transient LANE-RESULT.json / .brainclaw)' };
+        return { committed: false, files_changed: [], reason: 'no committable changes (only transient LANE-RESULT.json / .brainclaw / node_modules links)' };
     }
     const authorName = options.authorName ?? 'brainclaw (on behalf)';
     const authorEmail = options.authorEmail ?? 'brainclaw@on-behalf.local';
@@ -482,6 +531,30 @@ export function findWorktreePathForBranch(worktrees, branchName) {
  *
  * Returns the absolute path to the newly created worktree.
  */
+/**
+ * Whether the project looks like a Next.js app — a `next` dependency in
+ * package.json or a `next.config.*` at the root. Used to warn that the
+ * out-of-root `node_modules` symlink brainclaw provisions is rejected by
+ * `next dev` / Turbopack (trp_37b05a15), even though tsc / vitest / build accept
+ * it. Best-effort + defensive: any read/parse error → false (never blocks
+ * worktree creation over a heuristic).
+ */
+export function projectUsesNextjs(projectRoot) {
+    try {
+        for (const cfg of ['next.config.js', 'next.config.mjs', 'next.config.ts', 'next.config.cjs']) {
+            if (fs.existsSync(path.join(projectRoot, cfg)))
+                return true;
+        }
+        const pkgPath = path.join(projectRoot, 'package.json');
+        if (!fs.existsSync(pkgPath))
+            return false;
+        const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+        return Boolean(pkg.dependencies?.next ?? pkg.devDependencies?.next);
+    }
+    catch {
+        return false;
+    }
+}
 export function createWorktree(mainWorktreePath, branchName, options = {}) {
     // pln#614: resolve the true git toplevel first, so an in-tree project (project
     // dir ≠ git root) creates its worktree from the real repo root — `git worktree
@@ -610,6 +683,22 @@ export function createWorktree(mainWorktreePath, branchName, options = {}) {
     for (const entry of sharedPaths) {
         trySymlinkSharedPath(entry);
     }
+    // trp_37b05a15 (field report, Next.js 16 / Turbopack) — the node_modules link
+    // brainclaw provisions is an out-of-worktree-root symlink to the main repo.
+    // tsc / vitest / build follow it fine, but `next dev` (Turbopack) PANICS on a
+    // node_modules link that points outside the worktree root. Surface a warning
+    // (not a failure — the link is still correct for build/typecheck) so a worker
+    // or operator doing dev-server work knows the workaround up front. A full
+    // Turbopack-compatible per-worktree dependency mode is a planned follow-up.
+    const linkedNodeModules = sharedPaths.some((p) => p === 'node_modules' || p.endsWith('/node_modules'));
+    if (linkedNodeModules && projectUsesNextjs(mainWorktreePath)) {
+        const msg = 'Next.js detected: node_modules is linked as an out-of-worktree-root symlink, which '
+            + '`next dev` / Turbopack rejects (it requires node_modules under the worktree root). '
+            + 'tsc / vitest / build are unaffected. For dev-server work in this worktree, run '
+            + '`npm install` here (optionally with BRAINCLAW_NO_LINK_DEPS=1), or smoke-test on the merged branch.';
+        symlinkWarnings.push(msg);
+        logger.warn(`[worktree] ${msg}`);
+    }
     // NOTE: .brainclaw/ is intentionally NOT symlinked.
     // Symlinking .brainclaw/ causes hooks and session_start to trigger on the
     // shared store, creating session conflicts and potentially blocking agents

package/dist/facts.js

@@ -1,11 +1,11 @@
 // Generated by scripts/emit-site-facts.mjs at build time. Do not edit manually.
-// Source: brainclaw v1.14.0 on 2026-07-05T13:38:40.276Z
+// Source: brainclaw v1.16.0 on 2026-07-18T18:21:20.312Z
 export const FACTS = {
-  "version": "1.14.0",
-  "generated_at": "2026-07-05T13:38:40.276Z",
+  "version": "1.16.0",
+  "generated_at": "2026-07-18T18:21:20.312Z",
   "tools": {
     "count": 67,
-    "published_count": 66,
+    "published_count": 65,
     "names": [
       "bclaw_bootstrap",
       "bclaw_release_notes",
@@ -77,7 +77,7 @@ export const FACTS = {
     ]
   },
   "entities": {
-    "count": 17,
+    "count": 18,
     "names": [
       "plan",
       "step",
@@ -95,6 +95,7 @@ export const FACTS = {
       "assignment",
       "agent_run",
       "action",
+      "agent",
       "cross_project_link"
     ],
     "short_label_prefixes": {
@@ -114,6 +115,7 @@ export const FACTS = {
       "assignment": "asgn",
       "agent_run": "run",
       "action": "act",
+      "agent": "agt",
       "cross_project_link": "xpl"
     }
   },
@@ -472,7 +474,7 @@ export const FACTS = {
   },
   "bench": {
     "schema": "brainclaw.bench.v1",
-    "generated_at": "2026-07-05T13:38:38.216Z",
+    "generated_at": "2026-07-18T18:21:18.026Z",
     "node_version": "v24.18.0",
     "platform": "linux-x64",
     "repeats": 3,
@@ -481,15 +483,15 @@ export const FACTS = {
         "name": "cold_onboard",
         "volume": "empty",
         "description": "fresh machine → init → first useful context. Baseline for time-to-first-value.",
-        "duration_ms_median": 72,
-        "payload_chars_median": 1650,
-        "payload_tokens_est_median": 413
+        "duration_ms_median": 82,
+        "payload_chars_median": 1640,
+        "payload_tokens_est_median": 410
       },
       {
         "name": "warm_work",
         "volume": "medium",
         "description": "bclaw_work consult over a real-shaped store (~200 plans / 500 handoffs / 450 claims).",
-        "duration_ms_median": 126,
+        "duration_ms_median": 146,
         "payload_chars_median": 2626,
         "payload_tokens_est_median": 657
       },
@@ -497,7 +499,7 @@ export const FACTS = {
         "name": "first_edit",
         "volume": "medium",
         "description": "code_find + code_brief on the fresh-agent path (missing index, first touch).",
-        "duration_ms_median": 8,
+        "duration_ms_median": 9,
         "payload_chars_median": 442,
         "payload_tokens_est_median": 111
       }

package/dist/facts.json

@@ -1,9 +1,9 @@
 {
-  "version": "1.14.0",
-  "generated_at": "2026-07-05T13:38:40.276Z",
+  "version": "1.16.0",
+  "generated_at": "2026-07-18T18:21:20.312Z",
   "tools": {
     "count": 67,
-    "published_count": 66,
+    "published_count": 65,
     "names": [
       "bclaw_bootstrap",
       "bclaw_release_notes",
@@ -75,7 +75,7 @@
     ]
   },
   "entities": {
-    "count": 17,
+    "count": 18,
     "names": [
       "plan",
       "step",
@@ -93,6 +93,7 @@
       "assignment",
       "agent_run",
       "action",
+      "agent",
       "cross_project_link"
     ],
     "short_label_prefixes": {
@@ -112,6 +113,7 @@
       "assignment": "asgn",
       "agent_run": "run",
       "action": "act",
+      "agent": "agt",
       "cross_project_link": "xpl"
     }
   },
@@ -470,7 +472,7 @@
   },
   "bench": {
     "schema": "brainclaw.bench.v1",
-    "generated_at": "2026-07-05T13:38:38.216Z",
+    "generated_at": "2026-07-18T18:21:18.026Z",
     "node_version": "v24.18.0",
     "platform": "linux-x64",
     "repeats": 3,
@@ -479,15 +481,15 @@
         "name": "cold_onboard",
         "volume": "empty",
         "description": "fresh machine → init → first useful context. Baseline for time-to-first-value.",
-        "duration_ms_median": 72,
-        "payload_chars_median": 1650,
-        "payload_tokens_est_median": 413
+        "duration_ms_median": 82,
+        "payload_chars_median": 1640,
+        "payload_tokens_est_median": 410
       },
       {
         "name": "warm_work",
         "volume": "medium",
         "description": "bclaw_work consult over a real-shaped store (~200 plans / 500 handoffs / 450 claims).",
-        "duration_ms_median": 126,
+        "duration_ms_median": 146,
         "payload_chars_median": 2626,
         "payload_tokens_est_median": 657
       },
@@ -495,7 +497,7 @@
         "name": "first_edit",
         "volume": "medium",
         "description": "code_find + code_brief on the fresh-agent path (missing index, first touch).",
-        "duration_ms_median": 8,
+        "duration_ms_median": 9,
         "payload_chars_median": 442,
         "payload_tokens_est_median": 111
       }

package/docs/PROTOCOL.md

@@ -131,9 +131,13 @@ offered → accepted → started → (progress)* → completed
 ```
 
 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.
+A worker MAY drop a `LANE-RESULT.json` file at the worktree root and let the
+coordinator harvest it instead of emitting transitions itself. This is the
+coordinator-owned contract for a sandboxed worker: its sandbox makes `.git`
+read-only (so it cannot `git commit`), and the file is the harvestable signal —
+NOT because MCP is unreachable (a sandboxed worker does reach the MCP server,
+which runs out-of-process; dec#133). A genuinely MCP-less agent uses the same
+file as its only channel.
 
 ### 5.3 Claim sentinels
 

package/docs/concepts/coordinator-runbook.md

@@ -41,6 +41,9 @@ worker presumed dead
 │
 ├─ 1. LANE-RESULT.json at the worktree root?
 │     yes → it FINISHED. `brainclaw harvest <asgn> [--integrate]`. Done.
+│     (review lane: a `review_verdict` in the file is mapped onto the review
+│      loop by harvest — a `verdict` artifact is recorded and the loop
+│      auto-closes on `approve`; no manual bclaw_loop drive needed.)
 │
 ├─ 2. git evidence (shared helper: commits_ahead + dirty_tracked,
 │     surfaced by dispatch-status / dispatch watch):

package/docs/concepts/dispatch-lifecycle.md

@@ -152,16 +152,16 @@ 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:
+Some dispatched workers cannot self-commit. For example, a sandboxed Codex run has `dispatchCanCommit=false` because its writable root is the linked worktree, while `.git` lives outside that root — so it cannot `git commit`. (It *can* still call brainclaw MCP — dec#133 — but the file-based contract below is used regardless, so harvesting stays coordinator-owned and does not depend on the worker's MCP writes.) 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.
+2. Write `LANE-RESULT.json` at the worktree root — `{ assignment_id, status: completed|blocked|failed, summary, files_changed?, artifacts?, notes? }`. For a **review** lane, the worker also sets `review_verdict` (`approve` | `request_changes`) and `review_summary`; harvest maps those onto the review loop and auto-closes it on `approve` (pln#628 Focus 4B — see [loop-engine.md](./loop-engine.md#automation-extending-bclaw_coordinateintentreview)).
 
 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.
+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. It also excludes brainclaw's own transient/provisioned files from the lane commit — `LANE-RESULT.json`, `.brainclaw/`, `.brainclaw-worktree.json`, heartbeat files, and the `node_modules` link(s) brainclaw provisions (top-level + monorepo `**/node_modules`). The `node_modules` exclusion is tracked-aware: a project that *vendors* (commits) `node_modules` keeps a worker's change to a tracked file — only the freshly-provisioned link/dir is dropped.
 
 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`.
 
@@ -255,7 +255,7 @@ A dead dispatch needs four cleanup steps (no single facade does all of them toda
 
 Spawn behaviour varies by agent. The capability profile in `src/core/agent-capability.ts` describes each agent's prompt delivery, sandbox model, and MCP availability. Per-agent caveats:
 
-- [codex.md](../integrations/codex.md#caveats) — `--sandbox workspace-write` required; spawned codex may not have brainclaw MCP wired; stdin_pipe prompt delivery; brief-ack required for headless dispatch detection.
+- [codex.md](../integrations/codex.md#caveats) — `--sandbox workspace-write` required; sandboxed codex reaches MCP but cannot `git commit` (dec#133 — coordinator harvests the worktree diff); stdin_pipe prompt delivery; brief-ack required for headless dispatch detection.
 - [claude-code.md](../integrations/claude-code.md) — interactive vs `-p` headless modes; tools whitelist.
 - [copilot.md](../integrations/copilot.md), [windsurf.md](../integrations/windsurf.md), [cline.md](../integrations/cline.md), [opencode.md](../integrations/opencode.md), [roo.md](../integrations/roo.md), [kilocode.md](../integrations/kilocode.md), [continue.md](../integrations/continue.md) — per-agent specifics.
 - [mistral-vibe.md](../integrations/mistral-vibe.md) — EU/GDPR self-hosted option.

package/docs/concepts/loop-engine.md

@@ -332,6 +332,8 @@ When `bclaw_coordinate(intent='review', open_loop: true)` is called, it:
 5. On turn completion with a verdict artifact, auto-advances; `reviewer_green` stop closes.
 6. On non-green verdict with `iteration_count < max`, advances to `author_response`, dispatches to author.
 
+**How the verdict reaches the loop (shipped, pln#628 Focus 4B).** A dispatched reviewer worker does not call `bclaw_loop` itself — it writes its outcome to `LANE-RESULT.json` at the worktree root, now including an optional `review_verdict` (`approve` | `request_changes`) and `review_summary`. When the coordinator runs `brainclaw harvest <assignment_id>` (both the report-only path and `--integrate`), a review lane carrying a `review_verdict` is mapped onto its loop: brainclaw records a `verdict` artifact on the reviewer slot (`approve` → an `accepted…` body) and calls `advance`, which **auto-closes the loop on `reviewer_green` for `approve`** — no human driving `complete_turn`/`advance`. `request_changes` records the verdict and advances to `author_response` (the automated fix→re-review cycle is a follow-up). The mapping is idempotent, resolves the reviewer slot strictly by `assignment_id` (so symmetric multi-reviewer loops target the right slot), and runs the `complete_turn`+`advance` pair under the loop lock so an interrupted pass resumes rather than stalls.
+
 ### Symmetric review-AND-fix mode
 
 By default, the phases `findings` and `author_response` follow the classical asymmetric split — the reviewer identifies issues, the author applies fixes on the next turn. That doubles the number of round-trips: every issue needs one full turn to be identified, then another to be fixed.
@@ -514,7 +516,7 @@ Status after Codex schema review (cnd#574 / `dec_be66ccbf`, verdict `needs_revis
 
 The loop surface exposed over MCP is intentionally narrow:
 
-- **Review loops** — `bclaw_coordinate(intent="review", open_loop=true, review_mode="asymmetric"|"symmetric", targetAgents=[…])` opens the loop and dispatches the first turn. Drive subsequent turns with `bclaw_loop(intent="turn"|"complete_turn"|"advance"|"close")`.
+- **Review loops** — `bclaw_coordinate(intent="review", open_loop=true, review_mode="asymmetric"|"symmetric", targetAgents=[…])` opens the loop and dispatches the first turn. The reviewer's verdict is then harvested from `LANE-RESULT.json` (`review_verdict`) and **auto-advances/closes the loop on approve** — no manual driving needed for the approve path (pln#628 Focus 4B). `bclaw_loop(intent="turn"|"complete_turn"|"advance"|"close")` remains available to drive turns by hand (e.g. the `request_changes` fix cycle, or a human-operated slot).
 - **Ideation loops** — `bclaw_coordinate(intent="ideate", preset="bootstrap")` opens an ideation loop from a preset.
 
 Custom phase lists (`LoopPhase[]`) and bespoke `StopCondition` logic exist in the loop engine internally, but are **not** exposed through the MCP facade today: `CoordinateRequestSchema` accepts only `open_loop`, `review_mode`, `preflight`, `ref`, and `preset` — no `phases` or `stop_condition` — and the standalone `bclaw_loop` tool does not expose an `open` intent. Programmatic construction of ad-hoc loops is therefore internal / future work until the facade is extended.

package/docs/concepts/troubleshooting.md

@@ -206,7 +206,7 @@ brainclaw stale resolve <plan_id>            # → dropped (default for stale)
 
 **Symptom**: a dispatched assignment shows `running` indefinitely, and `bclaw_assignment_events` shows `run_running` but no further progress.
 
-**Why**: the spawned worker process either (a) crashed before reading its inbox, (b) read the inbox but couldn't acknowledge (e.g., MCP unavailable inside the spawned sandbox — common with codex `--sandbox workspace-write`), or (c) is genuinely still working but slow.
+**Why**: the spawned worker process either (a) crashed before reading its inbox, (b) started but the brief-ack sentinel never fired (spawn wrapper died, wrong CODEX_HOME/auth, or the CLI exited early — NOT because the sandbox blocks MCP: dec#133 shows a sandboxed codex reaches MCP fine), or (c) is genuinely still working but slow.
 
 **Diagnostic order**:
 

package/docs/integrations/codex.md

@@ -43,7 +43,7 @@ Codex is CLI-spawnable for parallel lanes and dispatched workflows. The canonica
 codex exec -c approval_policy="never" --sandbox workspace-write "{prompt}"
 ```
 
-The `--sandbox workspace-write` setting is required, **not `read-only`** — the read-only sandbox blocks the MCP filesystem writes that brainclaw needs (worktree handoffs, session files, etc.) and forces fallback to GitHub connectors which fail for local-only commits.
+The `--sandbox workspace-write` setting is required, **not `read-only`** — the worker needs to write files in its own worktree (the edits it produces, plus its `LANE-RESULT.json`) so the coordinator has a harvestable diff. This is about the worker's *file* writes, not MCP: the brainclaw MCP server runs out-of-sandbox and is reachable under either sandbox mode (dec#133). What the sandbox does block is `git commit` (`.git` is outside the writable root), so the coordinator commits the worktree diff at harvest.
 
 ### Prompt delivery: stdin_pipe (preferred)
 
@@ -53,7 +53,7 @@ When you (or the dispatcher) calls Codex with no positional `[PROMPT]`, Codex re
 
 ### Brief-ack handshake
 
-Since pln#476 (1.0.13+), spawned Codex workers are marked `delivered_and_started` once the wrapping shell touches a brief-ack sentinel at `.brainclaw/coordination/runtime/ack/<assignmentId>.ack`. This proves the spawn actually executed and decouples the handshake from MCP availability inside the worker — important because Codex spawned in `--sandbox workspace-write` may not have brainclaw MCP wired in its session.
+Since pln#476 (1.0.13+), spawned Codex workers are marked `delivered_and_started` once the wrapping shell touches a brief-ack sentinel at `.brainclaw/coordination/runtime/ack/<assignmentId>.ack`. This proves the spawn actually executed and decouples the handshake from whatever the worker does next — the spawn is confirmed even before the worker makes its first MCP call. (Note — dec#133: a sandboxed Codex run **does** reach brainclaw MCP; the server runs out-of-sandbox and `approval_policy=never` auto-approves. The sentinel is about confirming the spawn, not about MCP being unavailable.)
 
 ## Capability profile
 
@@ -72,7 +72,7 @@ Since pln#476 (1.0.13+), spawned Codex workers are marked `delivered_and_started
 
 ## Caveats
 
-- **Sandbox blocks MCP writes**: when running with strict sandbox, the spawned Codex cannot write to `.brainclaw/` directly. Use the brief-ack file plus filesystem-direct candidate writes (the dispatcher harvests them).
+- **Sandbox blocks `git commit`, not MCP** (dec#133): a sandboxed Codex run reaches brainclaw MCP (the server is a separate out-of-sandbox process; `approval_policy=never` auto-approves). What the sandbox *does* block is direct writes to paths outside the worktree root — notably `.git`, so the worker cannot `git commit`. Leave fixes uncommitted; the coordinator integrates + commits the worktree diff at harvest. A LANE-RESULT.json / filesystem-direct candidate write remains a valid fallback for reporting.
 - **Windows quoting**: long prompts containing backticks or `#` fail when passed as inline args through `cmd.exe`. The default stdin_pipe path avoids this.
 - **Sandbox vs review parity**: review runs use the same `workspace-write` sandbox as execution runs (older templates forced `read-only` on reviews; that path blocked PowerShell exec on Windows).
 - **No always-allow**: each MCP tool call still respects per-call approval policy unless explicitly set with `-c approval_policy="never"`.

package/docs/integrations/overview.md

@@ -103,7 +103,7 @@ The developer can dial back individual surfaces if needed, but the default is fu
 
 brainclaw's store mutations are serialized (MCP single-writer queue + file-based lock), so memory writes are safe even under contention.
 
-For **parallel work**, dispatch a sequence with `bclaw_dispatch(intent="execute")` — each lane gets its own auto-worktree under `~/.brainclaw/worktrees/<project-hash>/`, and the coordinator integrates with an octopus merge. For **review-fix loops**, `bclaw_coordinate(intent="review", open_loop=true, review_mode="symmetric")` runs an alternating review-and-fix conversation across two slots without shared-checkout collisions. These are the supported parallel paths today.
+For **parallel work**, dispatch a sequence with `bclaw_dispatch(intent="execute")` — each lane gets its own auto-worktree under `~/.brainclaw/worktrees/<project-hash>/`, and the coordinator integrates with an octopus merge. For **review-fix loops**, `bclaw_coordinate(intent="review", open_loop=true, review_mode="symmetric")` runs an alternating review-and-fix conversation across two slots without shared-checkout collisions — and the loop **auto-closes on reviewer approve** (the verdict is harvested from `LANE-RESULT.json`, no manual drive). These are the supported parallel paths today.
 
 For **sequential work** in the same project, let one agent claim at a time and rely on handoffs to keep continuity across sessions.
 

package/docs/mcp-schema-changelog.md

@@ -10,6 +10,122 @@ guarantees this changelog follows.
 
 ## Unreleased
 
+**Added — `LaneResultSchema.review_verdict` / `review_summary` (pln#628 Focus 4B)**
+- `LANE-RESULT.json` (the worktree-root file a dispatched worker writes) gains two
+  optional fields: `review_verdict` (`approve` | `request_changes`) and
+  `review_summary` (one-line rationale). Absent on non-review lanes.
+- Consumed by `brainclaw harvest` (report path + `--integrate`): a review lane
+  carrying a `review_verdict` is mapped onto its review loop — a `verdict` artifact
+  is recorded and the loop advances, auto-closing on `reviewer_green` for
+  `approve`. Additive + backward-compatible; no tool added/removed/renamed and no
+  surface-fingerprint change (LaneResultSchema is not part of the read/write
+  contract fingerprint).
+
+**Added — `bclaw_update(entity='handoff')` incl. review/contract (pln#625 Phase 3)**
+- The handoff update path is now wired. Previously `bclaw_update(entity='handoff')`
+  fell through to "not yet wired" (the field check passed for narrative/tags but
+  there was no handler case). `handoff.updatable` now also includes `review` and
+  `contract`, each validated against `HandoffReviewSchema` / `HandoffContractSchema`
+  and merged onto the record.
+- This **restores the review-state write capability lost at v1.0** when
+  `bclaw_update_handoff` was removed: an agent can write a review verdict via
+  `bclaw_update(entity='handoff', data={ review: { verdict, summary, … } })`.
+  A verdict auto-stamps `review.reviewed_at`. The review loop's core
+  (`applyHandoffUpdates`) is unchanged — this is the canonical-grammar front door
+  onto the same record.
+- Tip guard: a superseded (tombstoned) handoff is refused, pointing at the tip.
+- No tool added/removed/renamed; `updatable` is not part of the surface
+  fingerprint, so no fingerprint change.
+
+**Removed — `bclaw_list_agents` (pln#625; migrate to `bclaw_find(entity='agent')`)**
+- `bclaw_list_agents` — the last surviving `bclaw_list_*` tool — is retired into
+  `REMOVED_IN_V1_TOOLS`: hidden from every `tools/list`, with a direct-call
+  deprecation warning pointing at `bclaw_find(entity='agent')`. The handler
+  stays as a redacted read escape-hatch (`LEGACY_READ_TOOL_HANDLERS`), same as
+  its `list_*` siblings.
+- To preserve its one unique capability, `bclaw_find(entity='agent')` gains an
+  agent-only `includeReputation` filter that attaches the public reputation
+  summary per agent (same join the CLI `list-agents --with-reputation` uses).
+- Net surface coherence: `agent` reads now flow through one grammar path with a
+  single redacted projection (`projectAgentForRead`), closing the divergent
+  double-surface (the old tool leaked raw `identity_key`/`invoke.env`).
+
+**Changed — governance guard now covers grammar entities AND the filter contract (pln#625)**
+- `tests/unit/mcp-governance.test.ts` folds two free-form parts of the callable
+  contract into the public-surface fingerprint: the set of addressable grammar
+  entities (`ENTITY_NAMES`) and the find/get filter grammar
+  (`GRAMMAR_FILTER_CONTRACT` — accepted keys, entity-scoping, constrained
+  values). Both were previously invisible (the `entity` and `filter` args are
+  free-form and their enumerating descriptions are stripped), so wiring a new
+  `bclaw_find/get(entity='…')` target or adding/re-scoping/re-valuing a filter
+  key (e.g. the Phase 2c `scope`) could ship without a changelog entry.
+- `GRAMMAR_FILTER_CONTRACT` (exported from `entity-operations.ts`) is now the
+  single source of truth for the handler's filter validation AND the
+  fingerprint, so the two can never drift. A mutation test proves the
+  fingerprint reacts to an added entity, key, re-scope, and new value.
+- Closes the blind spot surfaced by the Phase 2c ideation loop; the filter-grammar
+  extension came from the Codex review of PR #82.
+
+**Added — read-only `agent` entity in the canonical grammar (pln#625 Phase 2c)**
+- `bclaw_find/get(entity='agent')` are now wired. They return a REDACTED,
+  read-only projection: `id`, `name`, `kind`, `trust_level`, `capabilities`,
+  `fingerprint` (full sha256(PEM) — the public canonical key id), `model`,
+  `context_profile`, `created_at`. The private key material (`identity_key`,
+  `public_key` PEM) and `invoke` (unpopulated dead field; would leak
+  `invoke.command`) are never surfaced. Writes (`create/update/remove/transition`)
+  return the `SystemManagedError` boundary — agents are managed via
+  `bclaw_setup` / `enable-agent`, not the grammar.
+- New agent-only filter `scope`: `bclaw_find(entity='agent')` defaults to the
+  current project's registry; `filter.scope='global'` additionally unions the
+  static dispatchable catalog (`getSpawnableAgents`) and annotates each entry
+  with `dispatchable` (canBeSpawnedCli) + `registered`. `scope` is rejected for
+  any other entity, and its value must be `project` (default) or `global`.
+- `bclaw_list_agents` now redacts through the SAME projection (one source of
+  truth). It previously spread the raw identity document, leaking
+  `identity_key.public_key` and `invoke.env` in the clear — a pre-existing
+  disclosure, now closed. `includeReputation` still attaches the reputation
+  add-on.
+- This supersedes the Phase 1a stopgap that reported `agent` as "not addressable
+  via the canonical grammar" (never released; last tag v1.15.0).
+
+**Fixed — `bclaw_transition(entity='handoff')` wired (pln#625 Phase 2a)**
+- The handoff lifecycle (`open→accepted|closed`, `accepted→closed`) is now
+  wired. It previously fell to the "not yet wired" default, which also broke
+  `brainclaw stale resolve <handoff-id>` (that command routes through the
+  canonical transition). A tip guard refuses to transition a handoff carrying
+  `superseded_by` (an immutable correction tombstone) and points at the tip.
+- No tool was added, removed, or renamed; no required argument changed.
+
+**Fixed — `bclaw_coordinate` published-schema parity (pln#622 PR0b)**
+- The published inputSchema of `bclaw_coordinate` now declares `preset`
+  (loop preset selector, valid only with `intent='ideate'`; v1 ships the
+  single preset `bootstrap`; unknown names are rejected with
+  `unknown_preset`, other intents with `preset_kind_mismatch`) and
+  `client_request_id` (caller-minted ULID/UUIDv7 for idempotent retries,
+  observed on `intent='review'` + `open_loop=true`, safe elsewhere). Both
+  were already accepted by `CoordinateRequestSchema` and used by the
+  handler — and `next_actions` literally recommended
+  `bclaw_coordinate(intent='ideate', preset='bootstrap')` — but the catalog
+  never declared them, so strict MCP clients could not follow the product's
+  own recommendation.
+- New guard: `tests/unit/mcp-facade-structural-parity.test.ts` asserts
+  bidirectional structural parity (keys + shared enum values) between the
+  hand-written facade schemas (`bclaw_work`, `bclaw_coordinate`) and their
+  zod sources, with an explicit allowlist for adapter-envelope fields
+  (`agent`, `agentId`).
+- No tool was added, removed, or renamed; no required argument changed.
+- Surface fingerprint bumped in the `(current)` section below.
+
+**Changed — MCP model selection parity (pln#520/#606)**
+- `bclaw_dispatch` and `bclaw_coordinate` gain an optional `model` string that
+  selects the spawned worker's model (e.g. `sonnet`, `gpt-5-codex`), decoupled
+  from agent identity — closing the CLI/MCP gap (the CLI `dispatch run --model`
+  already existed). Injected only for agents that declare a `model_flag`
+  (claude-code / codex / github-copilot); no-op otherwise, and consistent with
+  the dispatcher's resolveModel chain.
+- No tool was removed or renamed; no required argument changed.
+- Surface fingerprint bumped in the `(current)` section below.
+
 **Added — `bclaw_move` cross-project relocation (pln#595)**
 - New canonical-grammar verb `bclaw_move(entity, id, to_project, from_project?, force?)`:
   relocates a brainclaw item to another project in a multi-project workspace,
@@ -122,8 +238,43 @@ will still succeed. A follow-up PR will strip the dead handler code.
   changelog records the published MCP surface fingerprint. When a tool
   name, tier, category, or input schema changes, the test fails until
   this section is updated.
-- MCP public surface fingerprint: `sha256:2b0dfbd62acd71b7`
-  (updated 2026-07-04 for trp#928: explicit `coordinator_override` boolean added
+- MCP public surface fingerprint: `sha256:468f0103414e97e8`
+  (updated 2026-07-18 for pln#625 PR #83 + Codex review: `bclaw_list_agents`
+  retired and `bclaw_find(entity='agent')` gains `includeReputation` — now typed
+  as a boolean in `GRAMMAR_FILTER_CONTRACT.booleanKeys` and validated at the MCP
+  front door, so a non-boolean value is rejected instead of silently coercing to
+  a no-op. The added boolean-type declaration moves the fingerprint.)
+  Previous: `sha256:be0df1e4cc33936f`
+  (updated 2026-07-17 for pln#625 PR #83: `bclaw_list_agents` retired from the
+  published surface — migrated to `bclaw_find(entity='agent')` which gains an
+  agent-only `includeReputation` filter. Both the removed tool and the new
+  filter key move the fingerprint via the guard now covering PUBLISHED_TOOLS +
+  ENTITY_NAMES + GRAMMAR_FILTER_CONTRACT.)
+  Previous: `sha256:e12fd2f34dae1ac0`
+  (updated 2026-07-17 for pln#625 Phase 2c + PR #82: the fingerprint now folds in
+  two parts of the callable contract that the tool inputSchema cannot express —
+  the set of grammar-addressable entities (`ENTITY_NAMES`) and the find/get
+  filter grammar (`GRAMMAR_FILTER_CONTRACT`: accepted keys, entity-scoping, and
+  constrained values such as `scope=project|global`). Both were invisible to the
+  fingerprint before (`entity` and `filter` are free-form and their enumerating
+  descriptions are stripped), so wiring a new addressable entity — or adding /
+  re-scoping / re-valuing a filter key like the Phase 2c `scope` — slipped past
+  this guard. Additive: no tool added, removed, or renamed.)
+  Previous: `sha256:45c02576aff36244`
+  (updated 2026-07-15 for pln#622 PR0b: `preset` and `client_request_id` added
+  to the published `bclaw_coordinate` input schema. Both were already accepted
+  by `CoordinateRequestSchema` and used by the handler — and `next_actions`
+  recommended `bclaw_coordinate(intent='ideate', preset='bootstrap')` — but
+  the catalog never declared them. Additive: no tool added, removed, or
+  renamed; no required argument changed.
+  Previous: `sha256:b53eb56d4391b5a6`
+  updated 2026-07-15 for pln#520/#606: optional `model` string added to
+  `bclaw_dispatch` and `bclaw_coordinate` input schemas — selects the spawned
+  worker's model, decoupled from agent identity (CLI/MCP parity with
+  `dispatch run --model`). Additive: no tool added, removed, or renamed; no
+  required argument changed.
+  Previous: `sha256:2b0dfbd62acd71b7`
+  updated 2026-07-04 for trp#928: explicit `coordinator_override` boolean added
   to `bclaw_release_claim` and `bclaw_transition` input schemas — the coordinator
   path to release/stale a non-owned claim is now opt-in and audited rather than
   auto-derived from trust level. Additive: no tool added, removed, or renamed; no

package/docs/playbooks/orchestration.md

@@ -24,7 +24,7 @@ With the plan and sequences established, assign the work to execution agents.
 
 - **Sequence-driven execution:** Use `bclaw_dispatch(intent="execute")` to parallelize plans across your defined sequence lanes automatically.
 - **Direct orchestration:** For ad-hoc delegation, use `bclaw_coordinate(intent="assign")` to assign specific tasks to target agents. This seamlessly generates the necessary claims and dispatch briefs.
-- **Reviews & Loops:** To open a structured review process on completed work, use `bclaw_coordinate(intent="review", open_loop=true)`.
+- **Reviews & Loops:** To open a structured review process on completed work, use `bclaw_coordinate(intent="review", open_loop=true)`. The reviewer's verdict is harvested from its `LANE-RESULT.json` (`review_verdict`) and the loop **auto-closes on approve** — no manual `complete_turn`/`advance` round-trip to close the approve path (pln#628 Focus 4B).
 - Use `bclaw_dispatch_status` to verify worker liveness, examine log tails, and ensure dispatches are progressing healthily.
 
 ## Step 4: Manage the Inbox