brainclaw 1.13.0 → 1.15.0

package/README.md

@@ -429,258 +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.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

@@ -782,12 +782,13 @@ program
     .option('--verify-journal', 'Phase-2 cutover gate (pln#565): rebuild state from the event journal and diff vs live projections; exits non-zero on any drift')
     .option('--spawn-check', 'Real spawn round-trip per installed agent before dispatch (pln#520 step 2): validates delivery + handshake on this host, exits non-zero on any installed-agent failure')
     .option('--spawn-check-timeout <ms>', 'Per-agent timeout for --spawn-check (default 15000)', parseInt)
+    .option('--hygiene', 'Coordination-hygiene snapshot (pln#602): counts per family, park candidates, serve-count aging stats. Read-only.')
     .action(async (options) => {
     if (options.spawnCheck) {
         await runDoctorSpawnCheck({ cwd: options.cwd, json: options.json, timeoutMs: options.spawnCheckTimeout });
         return;
     }
-    runDoctor({ ...options, afterMigration: options.afterMigration, dispatch: options.dispatch, verifyJournal: options.verifyJournal });
+    runDoctor({ ...options, afterMigration: options.afterMigration, dispatch: options.dispatch, verifyJournal: options.verifyJournal, hygiene: options.hygiene });
 });
 // --- repair (Phase 4 Sprint 2 Lane C / pln#397) ---
 program
@@ -1956,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 },
     });
@@ -2001,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/doctor.js

@@ -4,6 +4,10 @@ import os from 'node:os';
 import path from 'node:path';
 import * as childProcess from 'node:child_process';
 import { reconcileAllOpenRuns } from '../core/agentrun-reconciler.js';
+import { loadHygienePolicy } from '../core/hygiene-policy.js';
+import { computeServeStats, loadServeRegistry } from '../core/hint-aging.js';
+import { listAssignments } from '../core/assignments.js';
+import { parkClosedAutoHandoffs } from '../core/gc-semantic.js';
 import { runSpawnCheck, renderSpawnCheckReport } from '../core/spawn-check.js';
 import { loadAgentRun } from '../core/agentruns.js';
 import { listAgentIdentities, listDebrisAgentIdentities, resolveCurrentAgentIdentity } from '../core/agent-registry.js';
@@ -638,7 +642,101 @@ function runJournalVerification(options) {
     if (drift.length > 0)
         process.exit(1);
 }
+function medianAgeDays(items, nowMs) {
+    if (items.length === 0)
+        return 0;
+    const ages = items
+        .map((a) => Math.floor((nowMs - new Date(a.created_at).getTime()) / 86_400_000))
+        .sort((a, b) => a - b);
+    const mid = Math.floor(ages.length / 2);
+    return ages.length % 2 === 1 ? ages[mid] : (ages[mid - 1] + ages[mid]) / 2;
+}
+export function runHygieneReport(options = {}) {
+    const cwd = options.cwd;
+    const policy = loadHygienePolicy(cwd);
+    const nowMs = Date.now();
+    const allAssignments = listAssignments(cwd);
+    const open = allAssignments.filter((a) => a.status === 'offered' || a.status === 'accepted' || a.status === 'started');
+    const offered = open.filter((a) => a.status === 'offered');
+    const accepted = open.filter((a) => a.status === 'accepted');
+    const started = open.filter((a) => a.status === 'started');
+    const heartbeatAgeMs = (a) => {
+        const anchor = a.last_heartbeat_at ?? a.offered_at ?? a.created_at;
+        return nowMs - new Date(anchor).getTime();
+    };
+    const offered_park_candidates = offered.filter((a) => heartbeatAgeMs(a) > policy.assignment_offered_ttl_ms).length;
+    const accepted_park_candidates = accepted.filter((a) => heartbeatAgeMs(a) > policy.assignment_accepted_ttl_ms).length;
+    const handoffParkDry = parkClosedAutoHandoffs(cwd ?? process.cwd(), Math.floor(policy.handoff_closed_ttl_ms / 86_400_000), true);
+    const registry = loadServeRegistry(cwd);
+    const staleStats = computeServeStats(registry.warnings, policy.stale_warning_serve_k);
+    const hintsStats = computeServeStats(registry.hints, policy.workflow_hint_serve_k);
+    return {
+        generated_at: new Date(nowMs).toISOString(),
+        disabled: policy.disabled,
+        policy,
+        families: {
+            assignments: {
+                total_open: open.length,
+                offered: offered.length,
+                accepted: accepted.length,
+                started: started.length,
+                offered_park_candidates,
+                accepted_park_candidates,
+                median_open_age_days: medianAgeDays(open, nowMs),
+            },
+            handoffs: {
+                closed_park_candidates: handoffParkDry.candidates,
+            },
+            stale_warnings: {
+                total_tracked: staleStats.total,
+                over_threshold: staleStats.over_threshold,
+                median_count: staleStats.median_count,
+                oldest_first_at: staleStats.oldest_first_at,
+            },
+            workflow_hints: {
+                total_tracked: hintsStats.total,
+                over_threshold: hintsStats.over_threshold,
+                median_count: hintsStats.median_count,
+                oldest_first_at: hintsStats.oldest_first_at,
+            },
+        },
+    };
+}
+function renderHygieneReport(report) {
+    const lines = [];
+    lines.push(`Coordination hygiene — snapshot ${report.generated_at}`);
+    if (report.disabled) {
+        lines.push('  ✗ policy.disabled=true — hygiene sweep + aging are opted out via config.hygiene.disabled.');
+    }
+    lines.push('');
+    const a = report.families.assignments;
+    lines.push(`Assignments (open ${a.total_open}: offered ${a.offered} / accepted ${a.accepted} / started ${a.started}, median age ${a.median_open_age_days}d)`);
+    lines.push(`  Park candidates: offered=${a.offered_park_candidates}, accepted=${a.accepted_park_candidates} — next sweep at session-start or bclaw_work will converge.`);
+    const h = report.families.handoffs;
+    lines.push(`Handoffs closed park candidates: ${h.closed_park_candidates} (auto-generated, older than ${Math.floor(report.policy.handoff_closed_ttl_ms / 86_400_000)}d)`);
+    const sw = report.families.stale_warnings;
+    lines.push(`Stale warnings tracked: ${sw.total_tracked} (over serve-K=${report.policy.stale_warning_serve_k}: ${sw.over_threshold}, median count ${sw.median_count}${sw.oldest_first_at ? `, oldest first-served ${sw.oldest_first_at.slice(0, 10)}` : ''})`);
+    const wh = report.families.workflow_hints;
+    lines.push(`Workflow hints tracked: ${wh.total_tracked} (over serve-K=${report.policy.workflow_hint_serve_k}: ${wh.over_threshold}, median count ${wh.median_count}${wh.oldest_first_at ? `, oldest first-served ${wh.oldest_first_at.slice(0, 10)}` : ''})`);
+    lines.push('');
+    lines.push('Read-only: no state was mutated. Session-start and bclaw_work drive the actual sweep/park; the counters age at bclaw_work read paths.');
+    return lines.join('\n');
+}
 export function runDoctor(options = {}) {
+    if (options.hygiene) {
+        if (!memoryExists(options.cwd)) {
+            console.error('Error: .brainclaw/ not found. Run `brainclaw init` first.');
+            process.exit(1);
+        }
+        const report = runHygieneReport(options);
+        if (options.json) {
+            console.log(JSON.stringify(report, null, 2));
+        }
+        else {
+            console.log(renderHygieneReport(report));
+        }
+        return;
+    }
     if (options.verifyJournal) {
         runJournalVerification(options);
         return;