brainclaw 1.14.0 → 1.15.0

package/README.md

@@ -429,266 +429,12 @@ 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.14.0
-
-Coordination hygiene, a dispatch-supervisor spec, and a monorepo worktree fix — from continued cross-machine dogfooding, each Codex-reviewed before merge:
-
-- **Coordination hygiene v1** (pln#602) — family-level TTL sweep (park-don't-delete, `config.hygiene`-overridable), lazy at the `bclaw_work` read path (zero extra reads on a healthy store) + full at session-start, K-times aging of stale warnings/hints into one actionable aggregate, and `brainclaw doctor --hygiene`.
-- **Worktree creation for in-tree projects** (pln#614) — `bclaw_coordinate(assign|review)` on a project dir that isn't the git root (app inside a monorepo) now resolves the real toplevel (`resolveGitToplevel` with a parent-walk past an invalid nested `.git`), so it spawns instead of failing with "not a git repository". Standalone projects unchanged; validated E2E on the reporting monorepo.
-- **Dispatch-supervisor round-3 spec** (pln#545, docs) — `docs/concepts/dispatch-supervisor.md`: honest worker-liveness attribution (Node supervisor + `run_id`-keyed sentinels), A0→B hard dependency, Windows Job Object FAIL-CLOSED, complete behavior matrix. Implementation lands later as A0-first increments.
-
-### v1.13.0
-
-Operator-maturity batch from two days of heavy multi-agent dogfooding — dispatch/worktree lifecycle, claim parity, write-path auto-repair, model routing, benchmark gate, 2× faster context reads:
-
-- **Model selection for codex and copilot spawns** (pln#606) — `dispatch run --model <m>` now reaches codex (`exec -m`) and copilot argv, verified on the installed binaries. The codex `--add-dir` writable-roots spike closed negative on Windows: file-first stays the codex transport.
-- **Auto-repair identity & session on canonical writes** (pln#608) — `bclaw_create`/`update`/`remove`/`transition` auto-register + auto-session instead of throwing "Start a session first", with an explicit `session auto-created` warning; the trust boundary for unknown identities is unchanged.
-- **Time-to-first-value benchmark with blocking CI budgets** (pln#604) — seeded synthetic stores, three scenarios (cold_onboard / warm_work / first_edit), budgets versioned in `bench-budgets.json`.
-- **Claim lifecycle parity** (trp#928) — `bclaw_transition(entity='claim')` wired, `coordinator_override` (trusted+) on release/transition, cascade release with per-claim logging on plan-done / loop close / assignment-completed / harvest, entity-scoped `bclaw_find` filter rejections.
-- **Squash-aware worktree GC + junction-safe removal** (trp#926) — squash-merged lanes are finally collected (content-based detection), and the Windows `node_modules`-junction wipe class is closed for good; `dispatch_status` compares against the worktree's creation ref.
-- **VS Code extension** — Backlog pagination (recent plans were invisible, trp#925) and probe/spawn parity with classified, actionable resolver failures (trp#927).
-- **Context read 2× faster on large stores** (pln#578) — 3 of the 4 full-store read passes per context build eliminated (disabled-reputation sweep ×2, estimation reload, triple candidate scan): 23.9 s → 11.9 s, 196 MB → 49 MB parsed, byte-identical output.
-
-### v1.12.0
-
-Auto-localized execution writes for multi-project workspaces (pln#597), from DGX-Spark dogfooding:
-
-- **Execution writes auto-localize into a workspace sibling named by `project=X`** — `bclaw_create`/`bclaw_transition` (plan & claim), `bclaw_claim`, the step tools and `bclaw_delete_plan` open a session + sticky switch into a workspace store-chain child instead of rejecting with "limited to signaling entities", echoing `auto_switched`. The signaling-vs-execution boundary is re-scoped to federation (`cross_project_links`): federated links and unknown names stay blocked.
-
-### v1.11.1
-
-Agent-identity & session-hook resilience, from a fresh-CLI dogfood on a monorepo:
-
-- **Session hooks no longer spam `UserPromptSubmit hook error` on every prompt.** Root cause was an agent-identity error whose own remediation (`register-agent --set-current`) the resolver ignored, swallowed by `2>/dev/null`. Now: the error hint points at what actually works (`--agent` / `$BRAINCLAW_AGENT_NAME`), a **single registered agent auto-resolves** with no env signal, and `session-start`/`context-diff`/`session-end` run with `--hook` so they degrade to exit 0 + `~/.brainclaw/hook.log` instead of erroring the prompt loop. Multi-agent safety (pln#562) is unchanged.
-- **`brainclaw doctor --fix-hooks`** purges stale/broken/duplicate brainclaw hooks across all Claude Code settings scopes (user + cwd) and rewrites the canonical ones — for the broken hooks that accumulate where `setup`'s git-repo discovery never reached.
-- **`setup` repo discovery recurses** (bounded, skipping `node_modules`/build dirs) so repos nested deep in a workspace are found instead of silently missed, and it registers the detected agent so the hooks it installs can resolve an identity.
-
-### v1.11.0
-
-Monorepo project-resolution + Code Map, cross-project relocation, and dispatch-worktree hygiene — from a multi-project (monorepo) dogfood:
-
-- **`bclaw_switch` to the monorepo root now works, and a switch is honored everywhere.** An agent inside a child project could not switch *up* to the workspace-root project, and a session-scoped switch was silently lost (sessions are stored per-cwd, but the resolver read them only at the workspace anchor). The resolver now matches the root project by `project_name`/`project_id` and probes the anchor / physical cwd / workspace root for the session, so `bclaw_switch` is authoritative for every subsequent call — including Code Map — without `--cwd`.
-- **`code-map refresh --cascade`** — monorepo-native, per-project indexing: one command at the root refreshes **every** nested project into its own store plus a child-scoped root store, with **zero double-indexing** (even under nesting). `code-map status --cascade` adds a per-child recap. Opt-in; single-project repos are unchanged.
-- **`brainclaw move <entity> <id> --to <project>` / `bclaw_move`** — id-preserving cross-project relocation, closing the gap the switch bug exposed (items created in the wrong store). Execution-local entities (claim/assignment/agent_run/session) stay put; refuses id collisions and active-claim moves; audits both stores.
-- **Sub-agent worktrees auto-clean on loop close** — a completed review/dispatch loop garbage-collects its worktrees (junction-safe; keeps any that are alive, un-harvested, or carry unmerged commits). Opt out with `BRAINCLAW_NO_WORKTREE_GC=1`.
-
-### v1.10.2
-
-Dispatch worktree-creation hardening (parallel-lane dispatch on a large repo): the claim-scope branch slug is length-capped *before* its trailing-dot strip (a scope ending in `…Page.astro` no longer truncates to an invalid `feat/…Page.` ref), and `git worktree add` gets a dedicated timeout (120s default; override `BRAINCLAW_WORKTREE_ADD_TIMEOUT_MS`) so a several-hundred-file checkout isn't SIGTERM-killed mid-materialize.
-
-### v1.10.1
-
-Code Map fast-follows from the 1.10.0 dogfood, plus a lint cleanup:
-
-- A git branch switch now flags the index stale (new `stale_git_head` freshness reason); `refresh` honors `.gitignore` (gitignored output dirs no longer indexed); `brief("<path>")` resolves the exact file instead of token-flooding; and the freshness badge distinguishes index freshness from a call's spot-check (`index_status`).
-- The `brainclaw-session` skill + agent instruction surface now point agents at `bclaw_code_find` / `bclaw_code_brief` before grep. Lint baseline cleared to zero (stylistic rules ratcheted to `error`); README doc links clickable; `docs/code-map.md` lists JS / TS / JSX / TSX · Python · PHP · Java.
-
-### v1.10.0
-
-- **Code Map** — a new per-project [Tree-sitter](docs/code-map.md) symbol + import
-  index for **JS / TS / TSX, Python, PHP, and Java**. Ask *"where is X / what should I
-  read first"* before editing: `bclaw_code_find`, `bclaw_code_brief`,
-  `bclaw_code_status`, `bclaw_code_refresh` (CLI: `brainclaw code-map …`). Pull-based
-  freshness with a per-response badge; never blocks `bclaw_work`; monorepo-aware. See
-  [code map](docs/code-map.md).
-- **Monorepo multi-project safety** — agents working in different child projects of a
-  monorepo are now genuinely independent:
-  - an anchored agent working *inside* a child project resolves **that** child, not the
-    repo root — no more "plans / index target the repo root";
-  - CLI `brainclaw switch` is **session-scoped by default** (two agents no longer clobber
-    a shared pointer); the new `--global` flag is the only path that sets the shared
-    workspace default; `switch --list` / show are session-aware;
-  - a session-less agent physically inside a child project beats a stale shared global
-    pointer (resolves the child it is in);
-  - dispatched / CoDev workers spawn with a **clean identity** — the coordinator's
-    session / project / agent env no longer leaks into a worker.
-- Internal — MCP public surface fingerprint re-pinned for the Code Map tools (additive;
-  no tool removed or renamed).
-
-### v1.9.1
-
-- **Multi-project scoping fixes for monorepos** — MCP reads/writes resolve the
-  effective project from an explicit arg, the MCP session, `BRAINCLAW_CWD`, or
-  the global active project (in that order), so commands target the right store
-  inside a monorepo; `bclaw_find` legacy-filter diagnostics report how many
-  `provenance.kind="legacy"` records the default filter excluded.
-- **Case-insensitive agent names** — `targetAgents=["Codex"]` (any casing) now
-  resolves like `codex`; dispatch/coordinate no longer silently drop a reviewer
-  over a capital letter, and an unresolved name reports a distinct `unknown_agent`
-  reason instead of the misleading "no CLI spawn template (IDE-only?)".
-- **Docs** — revamped Loop Engine, Git Worktrees, Cross-Project Signals, and the
-  Orchestration Playbook, corrected against actual behavior (`bclaw_work` =
-  session + context + claim, not worktree provisioning; worktrees come from
-  dispatch/coordinate; plans via `bclaw_create(entity="plan")`).
-
-### v1.9.0
-
-- **Release hardening for npm publishing + agent-surface coherence** (pln#571).
-  A dedicated CI **Release Package Check** builds the CLI, builds the optional
-  VS Code extension, runs the extension tests, and verifies the published tarball
-  contents; `version --publish-local`/`prepublishOnly` now run `build:release` +
-  `pack:check` before `npm pack`. The `.vsix` ships as an *optional* IDE
-  companion (local CLI builds skip it; release builds stay strict). Generated
-  agent surfaces no longer pin the npm semver (stable `Managed by brainclaw`
-  banner), and `.brainclaw/project.md` is documented as a legacy derived view —
-  root `PROJECT.md` is the durable project vision; live claims/plans/handoffs
-  live in `agent-board` / MCP context.
-- **Coordination & safety fixes** — strict claim isolation (a duplicate active
-  claim on the same scope now fails inside the mutation lock instead of warning),
-  `JsonStore` entity-id validation to prevent path traversal (pln#571), and
-  `reflect --batch` no longer swallows identity/security errors so a strict
-  import can never silently skip sensitive content (pln#572).
-- **Concurrency & CI robustness** — the journal append waits fairly under
-  contention so a multi-process kill-9 storm converges without seq reuse
-  (pln#573/#574), and `merge-risk` reconciles Windows 8.3 short-name worktree
-  paths so a claim matches its lane on Windows runners (pln#576).
-- **Docs** — Roo, Continue, Windsurf, Copilot, OpenClaw, quickstart, and the
-  agent-integration docs now match the current export formats and setup behavior
-  (pln#571/#575).
-
-### v1.8.0
-
-- **Multi-agent dispatch convergence — "worktree-as-contract"** (from a real
-  cross-project field session where a sandboxed worker could neither commit nor
-  reach MCP). The worker's contract shrinks to "edit files in this worktree +
-  drop `LANE-RESULT.json`": `brainclaw harvest --integrate` commits the worktree
-  diff on behalf of a worker that can't self-commit (hard-guarded to the linked
-  worktree, never the main repo), then completes the assignment and releases the
-  claim with plan cascade. A `LANE-RESULT.json` is now the #1 verdict signal in
-  `bclaw_dispatch_status` (worker FINISHED, even without self-update); the
-  dispatcher refuses to spawn without an isolated worktree; `open_loop` reviews
-  pre-flight each reviewer agent with a trivial validation spawn (clear
-  boot-failure reason instead of a generic loop timeout); and decisions/traps
-  gain `verified_at`/`verify_cmd` so perishable facts can be flagged stale.
-  Additive + opt-in throughout. (pln#530, pln#531, pln#532, pln#533, pln#534, trp#468)
-
-### v1.7.5
-
-- **Security patch (recommended upgrade)** — fixes a git command-injection / RCE
-  vector flagged by Socket AI: several commands interpolated a git ref (notably
-  one derived from the persisted session `git_sha`) into `execSync` shell
-  strings. All git calls now use `execFileSync` (no shell) and `git_sha` is
-  validated as a hex SHA. No functional change. (session-end, release-claims,
-  release-notes, sync)
-
-### v1.7.4
-
-- **Dispatch observability + worker DX hardening** (from a real cross-project
-  field session) — `bclaw_dispatch_status` and the reconciler now derive liveness
-  from filesystem activity (log + worktree mtime), so a worker actively editing
-  files is no longer falsely flagged `stalled`, and known codex boot-failure
-  stderr signatures get a targeted diagnosis; briefs are transport-aware (a
-  sandboxed agent without MCP/commit gets the file protocol, not instructions it
-  can't follow), backed by a derived capability matrix
-  (`dispatchHasMcp`/`dispatchCanCommit`); `bclaw_claim` gains an advisory
-  (no-worktree) mode; `bclaw_find` payloads are size-bounded with pagination
-  metadata; an opt-in per-worktree `tsc --noEmit` pre-commit gate; gated ready
-  lanes carry a code-propagation advisory; the reconciler auto-releases the claim
-  of a run it infers failed; and `plan.related_paths` is now updatable.
-  (pln#479, pln#491, pln#527, pln#528, pln#529, trp#291, trp#431, trp#433, trp#434)
-
-### v1.7.3
-
-- **Multi-agent dispatch hardening for JS/TS monorepos** — dispatched worktrees
-  junction-link per-package `node_modules` (npm / yarn / pnpm workspaces), not
-  just the root, and surface failed links instead of swallowing them; `brainclaw worktree clean` now garbage-collects merged worktrees past birth-noise instead
-  of skipping them all; the agent inventory reports an agent `spawnable` when its
-  binary is on PATH even if `--version` is slow to start; dispatch-verification
-  guidance leads with `bclaw_dispatch_status` (not the untrustworthy Windows
-  wrapper pid); and a new `LANE-RESULT.json` convention + `brainclaw harvest <assignment_id>` give workers a standard, MCP-free result channel. The dispatch
-  dirty-guard also ignores `.claude/`, `.cursor/`, and `.codex/` agent-local
-  config. (pln#523, pln#524, pln#525, pln#526, trp#371, trp#427, trp#428)
-
-### v1.7.2
-
-- **Sequence MCP tools are agent-first by default** — sequence creation,
-  listing, update, and deletion tools are now in the default MCP catalog, with
-  explicit lane item schemas (`planId`, optional `stepId`, `rank`,
-  dependencies, lane metadata) and matching canonical CRUD validation for
-  `entity="sequence"`.
-
-### v1.7.1
-
-- **MCP project context isolation fix** — `bclaw_switch` now keeps MCP switches
-  session-scoped even when the agent session has to be resolved or created on
-  the fly. Session lookup honors explicit session IDs, avoids adopting another
-  live process's session, detects Codex via native `CODEX_*` runtime variables,
-  and `bclaw_switch(list=true)` reports the session active project with
-  `active_source`.
-
-### v1.7.0
-
-- **Dispatch reliability + scope-aware dirty guard** — evidence-first
-  `agent_run` reconciliation avoids false terminal states, `bclaw_coordinate`
-  accepts pinned refs and a scope-aware `allow_dirty` guard, and the Hermes
-  agent integration joins the supported surfaces.
-
-### v1.6.0
-
-- **Bootstrap loop + cross-project agent workflow** — the bootstrap ideation
-  preset can materialize `PROJECT.md`, `bclaw_init_project` initializes and links
-  arbitrary project paths, and `project=` routing reaches `bclaw_work` /
-  `bclaw_loop` for linked-project operations.
-
-### v1.5.3
-
-- **Cross-project canonical grammar + CLI parity** (pln#359, all phases) — the canonical grammar (`bclaw_find / get / create / update / remove / transition`), `bclaw_context`, and `bclaw_coordinate` now accept an optional `project: <name>` argument that routes the operation to a linked project. Two link kinds are recognised: `cross_project_links` (sibling/peer projects in `config.yaml`, `brainclaw link list`) and workspace store-chain children. Arbitrary directory paths are rejected — adoption requires an explicit link, which gives the user a single point of control over what an agent can reach. Identity is sourced from the caller's home registry; entity writes + audit log entries land in the target. Unknown project names throw `validation_error` with a hint listing the configured links — no silent fallback. Cross-project `bclaw_coordinate` is **inbox-only**: claim/assignment/message all land in the target, the target agent picks the brief up async via its own `bclaw_work`, and auto-spawn from the source process is force-disabled because the spawn cwd / worktree are tied to the target's git repo (a warning surfaces in `FacadeResponse.warnings`). The CLI exposes the same as a global `--project <name>` flag, mutually exclusive with `--cwd`. Refs: helper `resolveProjectCwd` in `src/core/cross-project.ts`, MCP write/read handler dispatch in `src/commands/mcp.ts` and `src/commands/mcp-read-handlers.ts`, `--project` plumbing in `src/cli.ts` preAction, surface advertisement in `src/core/instruction-templates.ts`, plus tests in `tests/unit/cross-project.test.ts` (10 unit cases on the helper), `tests/unit/bclaw-coordinate.test.ts` (4 cross-project routing cases), and `tests/cli-cross-project.test.ts` (5 e2e cases). Closes the `--cwd` workaround pattern that had been the day-to-day shape of multi-project sessions.
-- **Site facts contract** (umbrella `pln_7fdfd70d` sprint 0) — new `scripts/emit-site-facts.mjs` emits `dist/facts.{js,json}` from `MCP_TOOL_NAMES` + `ENTITY_NAMES` so the brainclaw-site (and any consumer) can pull live tool/entity counts at build time without forking the values into a hand-maintained config. The package `files` list ships `dist/facts.json`; build:cli runs the emitter as part of the chain.
-
-### v1.5.2
-
-- **Grammar fix: `bclaw_update` no longer silently drops patches** (trp#187, pln#500) — the canonical CRUD surface promised that `EntityRegistry.updatable` listed every patchable field, but the legacy impls behind the dispatch (`updatePlan`, `updateMemoryItem`) only handled a typed subset. A `as UpdatePlanInput` cast in `entity-operations.ts` masked the gap from TypeScript: callers passed `{text, tags, severity, …}`, validation accepted them, and the function bodies never read them. Empirically reproduced this session on `pln#359` (text+tags drop) and `trp#187` itself (severity drop). Fix adds a generic-patch escape-hatch (`patch?: Partial<…>`) on `UpdatePlanInput` and `UpdateMemoryInput`, applied via `Object.assign` after the typed fields so legacy CLI callers keep their behaviour. The dispatch in `entity-operations.ts` now passes the full patch through that escape-hatch for plan/decision/constraint/trap. `runtime_note`, `candidate`, and `cross_project_link` were already correct. New `tests/unit/entity-update-coverage.test.ts` is parametric: for every `(entity, field)` pair in `EntityRegistry.updatable`, create + patch + get + assert the field actually persisted (29 cases). Adding a new updatable field will require adding a coverage row, so the contract stays honest.
-
-### v1.5.1
-
-- **Cross-project link CLI + grammar parity** (pln#454 step 2) — new `brainclaw link add/list/remove` subcommands and a stateless `cross_project_link` entity wired into the canonical CRUD verbs (`bclaw_create / find / get / update / remove`). The pain point was small (config.yaml is hand-editable) but the asymmetry — runtime cross-project signaling shipped, management UX did not — meant federation peers had no first-class affordance. Storage stays in `config.cross_project_links`; the entity is intentionally stateless (no transitions). Refs: `src/commands/link.ts`, `src/core/cross-project.ts` (new `addCrossProjectLink` / `removeCrossProjectLink`), `src/core/entity-registry.ts` (new `xpl` prefix), `src/core/entity-operations.ts` dispatch cases, `tests/unit/link.test.ts` + `tests/unit/cross-project-link-grammar.test.ts` (26 new cases).
-- **Agent registry pruned** (pln#454 step 1) — 8 synthetic profiles (antigravity, copilot-vscode, claude-opus, copilot-identity, copilot, claude-sonnet, visionnaire, copilot-codev) and 11 abandoned sessions archived under `.brainclaw/archive/agents/2026-05-07/`. The whitelist that survives matches `feedback_allowed_dispatch_agents.md`: `claude-code`, `codex`, `github-copilot`, plus `jberdah` (curator). Auto-re-registration in `detectAiAgent` is intentionally preserved — if a real surface starts a session, the registry auto-rebuilds for it. Pure store cleanup, no code change.
-- **Inbox + assignment lifecycle reconciliation** (housekeeping) — 89 stale inbox messages and 7 orphan offered-assignments closed with retroactive lifecycle updates. The plans they backed (pln#478 mcp self-heal, pln#480 multi-stack worktree, pln#483 bclaw_work compact, pln#471 tier-B live companions) had all merged weeks earlier without the dispatch path calling `bclaw_assignment_update`. Captured as `feedback_dispatch_test_inbox_debris` so future drift is mass-acked instead of triaged per-message.
-
-### v1.5.0
-
-- **Ideation loop MVP** (pln#492) — new `bclaw_coordinate(intent='ideate')` opens a memory-confrontation loop: critic reads only adversarial categories (traps + feedback + runtime_notes + critique_history) and gets a BM25-ranked, context-filtered, 12k-token-capped brief assembled from project memory. Single-agent (champion drives manually) or multi-agent (auto-dispatch a turn per critic). Iteration block (cycle, max_iterations, exit_when), phase-advance gate (≥3 critique artifacts before leaving critique), system events (`phase_advance_blocked`, `max_iterations_reached`). Full design: [docs/concepts/ideation-loop.md](docs/concepts/ideation-loop.md).
-- **Reliable dispatch + autonomy contract** (pln#496) — codex / sandboxed task-based agents now emit the full lifecycle (accepted → started → progress → completed). `briefMode` resolution corrected: `task-based && hasMcp → 'full'` (not 'compact', which silently dropped the protocol section). Lazy reconciliation pattern: `agentrun-reconciler` runs at every read path (`bclaw_assignment_events`, `bclaw_loop intent='get'`, `doctor --dispatch`) instead of a daemon; first run auto-recovered 9 historical orphan agent_runs in <1s. New autonomy contract section in instruction surfaces — agents execute protocol-defined transitions instead of pausing to ask. New `buildClaimEnvPrefix` consolidates cross-shell env injection (Windows defaults to cmd, POSIX uses unquoted bytes per PATH conventions). New `brainclaw doctor --dispatch` for operator-facing dispatch health.
-- **Worktree junction wipe fix** (pln#498) — `detachWorktreeJunctions` runs before `git worktree remove` on Windows so git's recursive rm cannot follow the `node_modules` junction back into the main repo. Closes the recurring post-merge wipe trap; validated empirically on multiple back-to-back merges in the v1.5.0 session.
-- **Methodological lessons** captured as user auto-memory feedback memos: bisect historical state before bisecting code (regression vs. always-broken-but-hidden), lazy reconcile at read paths beats daemon polling, codex briefs MUST include the Protocol section (implicit instructions don't propagate to sandboxed CLIs).
-
-### v1.2.0
-
-- **zod 3 → 4 migration** (pln#486) — schemas are semantically equivalent but the JSON Schema emitted by `tools/list` shifted shape; downstream MCP clients that snapshot schemas should re-pin. See `docs/mcp-schema-changelog.md` for the public surface fingerprint.
-
-### v1.1.0
-
-- **Node 20+ baseline** (pln#485) — `engines.node` is now `>=20.0.0` (Node 18 reached EOL in April 2025). CI matrix runs Node 22 and 24 on Linux; Windows on Node 24. Node 20 remains the minimum installable runtime but is no longer CI-verified.
-- **commander 13 → 14** (requires Node 20+).
-- **@types/node 22 → 24** (LTS-aligned).
-
-### v1.0.15
-
-- **TypeScript 5.8 → 6.0** (pln#484) — migration to `module: "nodenext"` (`Node16` is deprecated in TS 6, scheduled for removal in TS 7); explicit `types: ["node"]` since TS 6 changed the default to `[]`.
-
-### v1.0.14
-
-- **`bclaw_work` compact payload by default** (pln#483) — avoids exceeding the ~25k MCP token cap on projects with substantial memory. Pass `compact: false` for the full payload, or call `bclaw_context(kind="memory")` after.
-- **MCP runtime self-heal + `doctor --repair`** (pln#478) — when `dist/mcp-worker.js` is missing, the server logs an actionable repair pointer and read-only handlers keep serving in-process. `brainclaw doctor --repair` rebuilds dist in one step.
-- **Tier B/C native live companions** (pln#471) — `.cursor/live.md`, `.clinerules/live.md`, `.windsurf/rules/live.md`, `.github/copilot-instructions.live.md`, `.continue/live.md`, `GEMINI.live.md` regenerated on session-end and handoff. Opt-in via `brainclaw export --include-live --write`.
-
-### v1.0.13
-
-- **Worktree GC scope hardening** (pln#477) — `safeRemoveWorktreeDir` no longer follows symlinks/junctions during cleanup. Closes a class of post-merge wipes that previously destroyed `node_modules` and other neighboring directories on Windows.
-
-### v1.0.10–v1.0.12
-
-- **GitHub Copilot CLI is spawnable** (pln#440) — Copilot CLI 1.0.35+ supports `-p "<prompt>" --allow-all --no-ask-user`; tier promoted to A.
-- **Codex spawn on Windows: stdin pipe + 30s handshake TTL** (pln#475) — fixes embedded backticks/`#`/multi-line content getting mis-parsed by `cmd.exe` when a prompt is passed as an inline argument.
-- **Brief-ack file handshake** (pln#476) — `.brainclaw/coordination/runtime/ack/<assignmentId>.ack` proves a spawned worker started, decoupling the handshake from MCP availability inside the worker (important for Codex in `--sandbox workspace-write`).
-- **`bclaw_loop(intent="open")` orphan-gate** (pln#461) — refuses to open a loop without dispatch unless `allow_orphan: true` is explicit. Use `bclaw_coordinate(intent="review", open_loop: true)` instead.
-- **Kilocode** — Tier B integration with native MCP config and live companion (pln#464).
-
-### v1.0.0
-
-- **Canonical grammar promoted to standard tier** — `bclaw_find` / `bclaw_get` / `bclaw_create` / `bclaw_update` / `bclaw_remove` / `bclaw_transition`, plus the entry facades `bclaw_work` and `bclaw_context`, the multi-agent facades `bclaw_coordinate` and `bclaw_dispatch`, and the loop facade `bclaw_loop`. Legacy per-entity tools removed from the discoverable surface (still callable as a migration escape hatch). See `docs/concepts/mcp-governance.md` for tier rules and the deprecation policy.
+Full version history lives in **[CHANGELOG.md](CHANGELOG.md)** (Keep a Changelog
+format, Semantic Versioning). MCP protocol / schema changes and the public surface
+fingerprint are tracked separately in
+**[docs/mcp-schema-changelog.md](docs/mcp-schema-changelog.md)**. For releases
+predating the changelog file, `git log` on `master` is the source of truth — each
+release commit follows the `chore(release): bump version to <semver>` convention.
 
 ---
 

package/dist/cli.js

@@ -1957,7 +1957,14 @@ federationCmd
     const msg = createFederationMessage({
         version: 1,
         from: { project_name: config.project_name, project_path: process.cwd(), agent_name: agent },
-        to: { project_name: options.toProject ?? 'broadcast', project_path: '' },
+        to: {
+            project_name: options.toProject ?? 'broadcast',
+            project_path: '',
+            // Wire --to-agent into the message (was declared but dropped, so every
+            // push went out as a broadcast with to_agent NULL — found during the
+            // cross-machine E2E, pln#365). Omitted → undefined → broadcast, as before.
+            ...(options.toAgent ? { agent_name: options.toAgent } : {}),
+        },
         type: options.type,
         payload: { text: message },
     });
@@ -2002,23 +2009,184 @@ federationCmd
 });
 federationCmd
     .command('status')
-    .description('Check cloud federation configuration')
+    .description('Diagnose cloud federation: config, health, signing identity, approved agent')
     .action(async () => {
-    const { isCloudConfigured } = await import('./core/federation-cloud.js');
-    const url = process.env.BRAINCLAW_CLOUD_URL ?? 'https://app.brainclaw.dev';
-    console.log(`Cloud URL: ${url}`);
-    console.log(`API Key: ${process.env.BRAINCLAW_CLOUD_API_KEY ? '***configured***' : 'NOT SET'}`);
-    console.log(`Configured: ${isCloudConfigured() ? 'yes' : 'no'}`);
-    if (isCloudConfigured()) {
-        try {
-            const res = await fetch(`${url}/api/v1/health`);
-            const data = await res.json();
-            console.log(`Cloud status: ${data.status} (v${data.version})`);
+    const { diagnoseCloudBridge } = await import('./core/federation-cloud.js');
+    const d = await diagnoseCloudBridge();
+    const yn = (b) => (b ? 'yes' : 'no');
+    console.log(`Cloud URL:   ${d.apiUrl}`);
+    console.log(`API Key:     ${process.env.BRAINCLAW_CLOUD_API_KEY ? '***configured***' : (d.configured ? 'from config' : 'NOT SET')}`);
+    console.log(`Configured:  ${yn(d.configured)}`);
+    console.log(`Opted-in:    ${yn(d.enabled)}`);
+    console.log(`Project:     ${d.projectId ?? '(none)'}`);
+    console.log(`Require signed writes: ${yn(d.requireSigned)}`);
+    if (d.health) {
+        console.log(d.health.ok
+            ? `Cloud status: ${d.health.status} (v${d.health.version})`
+            : `Cloud unreachable: ${d.health.error ?? 'unknown error'}`);
+    }
+    if (d.signing.available) {
+        console.log('\nSigning identity:');
+        console.log(`  Agent:       ${d.signing.agentName} [${d.signing.cloudAgentId}]`);
+        console.log(`  Key present: yes`);
+        console.log(`  Fingerprint: ${d.signing.fingerprint.slice(0, 16)}…`);
+    }
+    else {
+        console.log(`\nSigning identity: unavailable — ${d.signing.reason}`);
+    }
+    if (d.approvedAgent) {
+        console.log('\nApproved agent (cloud):');
+        if (d.approvedAgent.found) {
+            console.log(`  Status:      ${d.approvedAgent.status ?? '(unknown)'}`);
+            console.log(`  Trust:       ${d.approvedAgent.trustLevel ?? '(unknown)'}`);
+            console.log(`  Key match:   ${d.approvedAgent.fingerprintMatch ? 'yes ✔' : 'NO ✗ (local key does not match the registered key)'}`);
+        }
+        else {
+            console.log(`  Not found${d.approvedAgent.error ? ` — ${d.approvedAgent.error}` : ''}`);
+        }
+    }
+    if (d.requireSigned && !d.signing.available) {
+        console.log('\n⚠ require_signed is set but no signing identity is available — the bridge will refuse to push (fail-closed).');
+    }
+});
+federationCmd
+    .command('identity')
+    .description('Show this agent\'s federation signing identity (public key to approve in the cloud UI)')
+    .option('--agent <name>', 'Agent name (defaults to the current agent)')
+    .option('--json', 'Output as JSON')
+    .action(async (options) => {
+    const { resolveOrAutoRegisterAgentIdentity, ensureAgentSigningKey, resolveCurrentAgentName } = await import('./core/agent-registry.js');
+    const agentName = options.agent ?? resolveCurrentAgentName();
+    const { identity } = resolveOrAutoRegisterAgentIdentity({ agentName, cwd: process.cwd() });
+    const key = ensureAgentSigningKey(identity.agent_id);
+    if (options.json) {
+        console.log(JSON.stringify({
+            agent_name: identity.agent_name,
+            local_agent_id: identity.agent_id,
+            fingerprint: key.fingerprint,
+            public_key_pem: key.publicKeyPem,
+        }, null, 2));
+        return;
+    }
+    console.log(`Agent name:     ${identity.agent_name}`);
+    console.log(`Local agent id: ${identity.agent_id}`);
+    console.log(`Fingerprint:    ${key.fingerprint}`);
+    console.log('\nPublic key — paste into the cloud UI (project → Agents → Register / approve an agent):\n');
+    console.log(key.publicKeyPem.trim());
+    console.log('\nThen, on this machine, configure the bridge with the cloud agent id shown after approval:');
+    console.log(`  export BRAINCLAW_AGENT_NAME=${identity.agent_name}`);
+    console.log('  export BRAINCLAW_CLOUD_AGENT_ID=<agt_... returned by the UI>');
+    console.log('  (plus BRAINCLAW_CLOUD_API_KEY, BRAINCLAW_PROJECT_ID) — then run `brainclaw federation status`.');
+});
+federationCmd
+    .command('sync')
+    .description('Drain the federation outbox — push signed claim upserts to the cloud')
+    .option('--entity <type>', 'Entity type to sync (increment 1: claim)', 'claim')
+    .option('--limit <n>', 'Max records to push this run')
+    .option('--dry-run', 'Reconcile + list pending records without any network calls')
+    .option('--json', 'Output as JSON')
+    .action(async (options) => {
+    const outbox = await import('./core/federation-outbox.js');
+    const { pushClaimToCloud, isCloudConfigured } = await import('./core/federation-cloud.js');
+    const cwd = process.cwd();
+    const PARK_AFTER = 5;
+    const reconciled = outbox.reconcileOutbox(cwd);
+    let records = outbox.listOutboxRecords(cwd);
+    if (options.limit)
+        records = records.slice(0, parseInt(options.limit, 10));
+    const counts = { synced: 0, superseded: 0, parked: reconciled.parked, dropped: reconciled.dropped, retry: 0 };
+    const lines = [];
+    const emit = (line) => { lines.push(line); if (!options.json)
+        console.log(line); };
+    if (options.dryRun) {
+        for (const r of records)
+            emit(`pending ${r.record.entity_type} ${r.record.entity_id} r${r.record.rev} (${r.record.to_status})`);
+        const out = { dry_run: true, reconciled, pending: records.length, records: lines };
+        if (options.json)
+            console.log(JSON.stringify(out, null, 2));
+        else
+            console.log(`\npending=${records.length} reconciled_dropped=${reconciled.dropped} reconciled_parked=${reconciled.parked}`);
+        return;
+    }
+    if (!isCloudConfigured(cwd)) {
+        console.error('Error: cloud not configured (set BRAINCLAW_CLOUD_API_KEY or cloud_sync). Records left in outbox.');
+        process.exit(3);
+    }
+    let failClosed = false;
+    for (const r of records) {
+        const res = await pushClaimToCloud(r.record.payload, cwd);
+        const tag = `${r.record.entity_id} r${r.record.rev}`;
+        if (res.kind === 'not_configured' || res.kind === 'fail_closed') {
+            failClosed = true;
+            emit(`fail-closed ${tag} (${res.kind}) — not sent`);
+            break; // same config for all remaining records
         }
-        catch (e) {
-            console.error(`Cloud unreachable: ${e.message}`);
+        if (res.kind === 'network_error') {
+            const attempts = r.record.attempts + 1;
+            if (attempts >= PARK_AFTER) {
+                outbox.parkRecord(r, `network error x${attempts}: ${res.error}`, cwd);
+                counts.parked++;
+                emit(`park  ${tag} (network x${attempts}: ${res.error})`);
+            }
+            else {
+                outbox.recordAttempt(r, { http_status: null, error: res.error }, cwd);
+                counts.retry++;
+                emit(`retry ${tag} (network: ${res.error})`);
+            }
+            continue;
+        }
+        const { httpStatus, code } = res;
+        if (httpStatus === 200 || httpStatus === 201) {
+            outbox.archiveToSent(r, { http_status: httpStatus }, cwd);
+            counts.synced++;
+            emit(`pushed ${tag} → ${httpStatus}`);
+        }
+        else if (httpStatus === 409 && (code === 'STALE' || code === 'stale_version')) {
+            outbox.archiveToSent(r, { http_status: httpStatus }, cwd);
+            counts.superseded++;
+            emit(`superseded ${tag} → 409 ${code} (cloud has a newer rev)`);
+        }
+        else if (httpStatus === 409) {
+            outbox.parkRecord(r, `409 ${code ?? 'conflict'}`, cwd);
+            counts.parked++;
+            emit(`PARK  ${tag} → 409 ${code ?? 'conflict'} (divergence — inspect)`);
+        }
+        else if (httpStatus === 403) {
+            outbox.parkRecord(r, `403 ${code ?? 'forbidden'}`, cwd);
+            counts.parked++;
+            emit(`PARK  ${tag} → 403 ${code ?? 'forbidden'}`);
+        }
+        else if (httpStatus >= 500) {
+            const attempts = r.record.attempts + 1;
+            if (attempts >= PARK_AFTER) {
+                outbox.parkRecord(r, `5xx x${attempts} (last ${httpStatus})`, cwd);
+                counts.parked++;
+                emit(`park  ${tag} → ${httpStatus} (x${attempts})`);
+            }
+            else {
+                outbox.recordAttempt(r, { http_status: httpStatus, error: null }, cwd);
+                counts.retry++;
+                emit(`retry ${tag} → ${httpStatus}`);
+            }
+        }
+        else {
+            outbox.parkRecord(r, `${httpStatus} ${code ?? 'client error'}`, cwd);
+            counts.parked++;
+            emit(`PARK  ${tag} → ${httpStatus} ${code ?? ''}`.trim());
         }
     }
+    const summary = `synced=${counts.synced} superseded=${counts.superseded} retry=${counts.retry} parked=${counts.parked} dropped=${counts.dropped}`;
+    if (options.json)
+        console.log(JSON.stringify({ ...counts, fail_closed: failClosed, records: lines }, null, 2));
+    else
+        console.log(`\n${summary}`);
+    if (failClosed)
+        process.exit(3);
+    if (counts.parked > 0)
+        process.exit(2);
+    if (counts.retry > 0)
+        process.exit(1);
+    // exit 0
 });
 // --- codev (legacy experimental) ---
 if (isCodevEnabled()) {

package/dist/commands/mcp.js

@@ -27,7 +27,7 @@ import { ENTITY_REGISTRY } from '../core/entity-registry.js';
 import { generateClaimId, listClaims, loadClaim, saveClaim, createCoordinatorClaim, adoptClaimSession, attachAssignmentMessageToClaim, linkClaimToAssignment, releaseClaimWithCascade } from '../core/claims.js';
 import { createSequence, updateSequence, deleteSequence } from '../core/sequence.js';
 import { assertCrossProjectBoundary, checkPolicy } from '../core/policy.js';
-import { createWorktree as coreCreateWorktree } from '../core/worktree.js';
+import { createWorktree as coreCreateWorktree, sanitizeBranchComponent } from '../core/worktree.js';
 import { createRuntimeNote } from './runtime-note.js';
 import { createCandidateFromInput } from './reflect.js';
 import { acceptCandidate } from './accept.js';
@@ -56,7 +56,7 @@ import { deleteMemoryItem, updateMemoryItem } from '../core/operations/memory-mu
 import { assessMemoryPressure, buildCompactionTemplate, applyCompaction } from '../core/gc-semantic.js';
 import { WorkRequestSchema, CoordinateRequestSchema } from '../core/facade-schema.js';
 import { codeMapWorkSection, codeMapRefreshNextActions } from '../core/code-map/work-section.js';
-import { getSpawnableAgents, getCapabilityProfile, buildInvokeCommand, validateAgentForDispatch } from '../core/agent-capability.js';
+import { getSpawnableAgents, getCapabilityProfile, buildInvokeCommand, validateAgentForDispatch, resolveModel } from '../core/agent-capability.js';
 import { attemptExecution } from '../core/execution.js';
 import { createAgentRun, transitionAgentRun } from '../core/agentruns.js';
 import { sweepDeadPidRunningAgentRunsAtRead } from '../core/agentrun-reconciler.js';
@@ -520,6 +520,7 @@ const MCP_WRITE_TOOLS = [
                 agents: { type: 'array', items: { type: 'string' }, description: 'Only dispatch to these agents. Default: all available.' },
                 lanes: { type: 'array', items: { type: 'string' }, description: 'Only dispatch items in these lanes. Also used by intent=analysis.' },
                 maxAssignments: { type: 'number', description: 'Max assignments to make (default: all ready). intent=execute only.' },
+                model: { type: 'string', description: 'Model to run on spawned workers, decoupled from agent identity (e.g. "sonnet", "gpt-5-codex"). Injected as `<model_flag> <model>` for agents that declare one (claude-code/codex/copilot); no-op for template-pinned identities. Mirrors the CLI `brainclaw dispatch run --model`. intent=execute only.' },
                 dryRun: { type: 'boolean', description: 'Preview without sending. Accepted by all intents.' },
                 autoExecute: { type: 'boolean', description: 'Attempt to spawn agents after delivery (default: true). intent=execute only.' },
                 // intent=review args (forwarded to bclaw_dispatch_review)
@@ -1051,6 +1052,7 @@ const MCP_WRITE_TOOLS = [
                 project: { type: 'string', description: 'Optional (pln#359 phase 1b): name of a linked project to dispatch into. When set, claim/assignment/message all land in the target project — the target agent picks the brief up async via its own bclaw_work. Auto-spawn is disabled in cross-project mode. Accepts cross_project_links and workspace store-chain children (see `brainclaw link list`).' },
                 allow_dirty: { type: 'boolean', description: 'Override the scope-aware dirty-working-tree guard (trp#371 Tier 2). The guard runs only for worktree-spawning intents (assign/review/reroute) and blocks only when uncommitted files overlap — or cannot be proven disjoint from — the dispatch scope (the worker spawns from HEAD and will not see them). `.brainclaw/` and `.git/` are always excluded. Set true to proceed anyway (the block is downgraded to a warning that lists the overlapping files). Boolean; the string "true"/"false" are also coerced.' },
                 ref: { type: 'string', description: 'Optional git ref (commit/branch/tag) for assign/review/reroute: the dispatched worker builds its worktree from this ref instead of HEAD. When set, uncommitted working-tree changes are intentionally out of scope and the dirty guard allows the dispatch. Ignored by consult/ideate/summarize (no worktree).' },
+                model: { type: 'string', description: 'Model to run on the spawned worker, decoupled from agent identity (e.g. "sonnet", "gpt-5-codex", "gpt-5.4"). Injected as `<model_flag> <model>` into the invoke command for agents that declare one (claude-code/codex/github-copilot); no-op for template-pinned pseudo-identities (e.g. claude-sonnet) or agents without a model_flag. Highest-priority link in the model resolution chain (override > lane > identity > default). Applies to intents that spawn a worker (assign/consult/review/reroute/ideate); ignored by summarize.' },
             },
             required: ['intent', 'task'],
         },
@@ -3542,7 +3544,9 @@ async function _executeMcpToolCallInner(payload) {
             // worktree:false) for an advisory-only lock with no worktree.
             const advisoryClaim = args.advisory === true || args.worktree === false;
             if (!advisoryClaim) {
-                const branchSlug = claimScope.replace(/[^a-zA-Z0-9._-]/g, '-').replace(/-+/g, '-').slice(0, 48);
+                // Shared slug logic (trp#950): collision-resistant when the scope
+                // exceeds the branch-component cap, and identical to createCoordinatorClaim.
+                const branchSlug = sanitizeBranchComponent(claimScope);
                 const worktreeBranch = args.worktreeBranch?.trim() || `feat/${branchSlug}`;
                 try {
                     worktreePath = coreCreateWorktree(claimCwd, worktreeBranch, {
@@ -3608,7 +3612,7 @@ async function _executeMcpToolCallInner(payload) {
                     const { execSync } = await import('node:child_process');
                     const branch = execSync('git branch --show-current', { cwd: claimCwd, encoding: 'utf-8' }).trim();
                     if (branch === 'master' || branch === 'main') {
-                        const branchSlug = claimScope.replace(/[^a-zA-Z0-9._-]/g, '-').replace(/-+/g, '-').slice(0, 48);
+                        const branchSlug = sanitizeBranchComponent(claimScope);
                         branchWarn = `\n⚠️ You are on ${branch}. Create a feature branch before editing: git checkout -b feat/${branchSlug}`;
                     }
                 }
@@ -4048,6 +4052,7 @@ async function _executeMcpToolCallInner(payload) {
                     dispatcherAgentId: resolved.identity.agent_id,
                     sessionId: connectionSessionId,
                     autoExecute: args.autoExecute,
+                    model: args.model,
                 }, cwd);
                 if (!result) {
                     return { response: createToolErrorResponse('operation_error', 'No active sequence found. Create a sequence first.') };
@@ -5627,6 +5632,15 @@ async function _executeMcpToolCallInner(payload) {
                 side_effects.push({ action: 'create', entity: 'message', id: msgResult.id });
                 const invoke = buildInvokeCommand(input.agent, input.text, {
                     mode: input.commandMode ?? 'worker',
+                    // pln#520/#606 — decouple model from agent identity. req.model is the
+                    // override link; when unset, resolveModel intentionally falls back to
+                    // the profile's default_model (the documented last link in the chain),
+                    // mirroring the dispatcher's resolveModel usage (dispatcher.ts) so
+                    // coordinate and dispatch spawn with the same model. No profile ships
+                    // a default_model today, so omitting model stays a no-op in practice
+                    // (gpt-5.6-luna review). Flows to both the manual commandHint and the
+                    // auto-spawn path (runCoordinateExecution reuses this invoke).
+                    model: resolveModel(input.agent, { override: req.model }),
                 });
                 // Build env prefix for claim routing — centralised in
                 // execution-profile.ts:buildClaimEnvPrefix as of pln#496 step