brainclaw 1.16.0 → 1.18.0

package/docs/concepts/loop-engine.md

@@ -330,9 +330,11 @@ When `bclaw_coordinate(intent='review', open_loop: true)` is called, it:
 3. Links the provided handoff/candidate to the loop as an artifact at `change_summary`.
 4. Advances to `findings` and calls `bclaw_loop(intent: 'turn')` to dispatch to the reviewer.
 5. On turn completion with a verdict artifact, auto-advances; `reviewer_green` stop closes.
-6. On non-green verdict with `iteration_count < max`, advances to `author_response`, dispatches to author.
+6. On a `request_changes` verdict, the fix cycle re-dispatches the reviewer into the same worktree until `approve` or the `max_iterations` cap.
 
-**How the verdict reaches the loop (shipped, pln#628 Focus 4B).** A dispatched reviewer worker does not call `bclaw_loop` itself — it writes its outcome to `LANE-RESULT.json` at the worktree root, now including an optional `review_verdict` (`approve` | `request_changes`) and `review_summary`. When the coordinator runs `brainclaw harvest <assignment_id>` (both the report-only path and `--integrate`), a review lane carrying a `review_verdict` is mapped onto its loop: brainclaw records a `verdict` artifact on the reviewer slot (`approve` → an `accepted…` body) and calls `advance`, which **auto-closes the loop on `reviewer_green` for `approve`** — no human driving `complete_turn`/`advance`. `request_changes` records the verdict and advances to `author_response` (the automated fix→re-review cycle is a follow-up). The mapping is idempotent, resolves the reviewer slot strictly by `assignment_id` (so symmetric multi-reviewer loops target the right slot), and runs the `complete_turn`+`advance` pair under the loop lock so an interrupted pass resumes rather than stalls.
+**How the verdict reaches the loop (shipped, pln#628 Focus 4B).** A dispatched reviewer worker does not call `bclaw_loop` itself — it writes its outcome to `LANE-RESULT.json` at the worktree root, including an optional `review_verdict` (`approve` | `request_changes`) and `review_summary`. When the coordinator runs `brainclaw harvest <assignment_id>` (report-only path and `--integrate`), a review lane carrying a `review_verdict` is mapped onto its loop: brainclaw records a `verdict` artifact on the reviewer slot (`approve` → an `accepted…` body) and calls `advance`, which **auto-closes the loop on `reviewer_green` for `approve`** — no human driving `complete_turn`/`advance`.
+
+**The autonomous fix cycle (PR2, `--integrate` only).** On `request_changes`, `harvest --integrate` bumps the loop's round counter, **keeps the claim + worktree alive**, and re-dispatches the same reviewer slot into that **same worktree** (symmetric mode) with a findings-aware brief: apply the requested changes in place, then re-review. Commits accumulate on one branch — no fresh worktree per turn, so the branch-per-scope / refuse-unharvested-commits invariants are never tripped. The cycle repeats until `approve` (→ `reviewer_green` close) or the `max_iterations` cap (n=3 → auto-close `blocked`, handed to a human). The report-only harvest path never cycles (it can neither re-dispatch nor retain the claim); it defers `request_changes` to `--integrate` and still closes on `approve`. The mapping is idempotent, resolves the reviewer slot strictly by `assignment_id` (so symmetric multi-reviewer loops target the right slot), and runs the `complete_turn`+`advance` pair under the loop lock so an interrupted pass resumes rather than stalls. Asymmetric (author ≠ reviewer) cross-agent worktree sharing is a planned follow-up.
 
 ### Symmetric review-AND-fix mode
 
@@ -484,6 +486,29 @@ The three rules are independent: `hard_deadline` bounds pathological "heartbeat
 - Execution loops (`implementation`) route by `claim_id` — preserved from the claim-routed model already in use.
 - `session_id` is not a routing key; it remains observability-only. This is consistent with `architecture_session_centric_identity` in memory.
 
+### Project resolution gate (pln#521 P1)
+
+`bclaw_coordinate(intent='review', open_loop=true)` resolves WHICH project the
+loop belongs to before it writes anything. A loop that lands in the wrong store
+persists a candidate, claim, assignment and loop where nobody is watching, and
+spawns the reviewer against the wrong repo.
+
+The ladder, in order: an explicit `project` argument; then any selector that
+already won upstream (`--cwd`, `BRAINCLAW_PROJECT`, a session switch, the
+physical child store, the workspace `active-project.json`); then the bare cwd
+fallback. The fallback is accepted in a single-project store — there is exactly
+one answer — and **refused** with `needs_project_selection` when the store can
+host several projects (`project_mode: multi-project`, or a `store_type: workspace`
+parent with nested project stores). The error lists the candidates and creates
+nothing; fix it by passing `project='<name>'` or by making the choice sticky with
+`bclaw_switch`. Ref, scope and path are never used to guess the project (B3
+rejected in `art_e29e88878209`: a wrong guess costs more than an explicit choice).
+
+Both `bclaw_coordinate` (open_loop reviews) and `bclaw_dispatch_status` echo the
+decision as `project_name` / `project_cwd`. `dispatch_status` additionally carries
+`_resolution_trace` (`source_cwd`, `effective_cwd`, `active_source`, `project_arg`)
+so a misroute can be diagnosed without reverse-engineering cwd and store state.
+
 ## Open questions (resolved / deferred)
 
 Status after Codex schema review (cnd#574 / `dec_be66ccbf`, verdict `needs_revision` → addressed in v8):
@@ -517,6 +542,7 @@ Status after Codex schema review (cnd#574 / `dec_be66ccbf`, verdict `needs_revis
 The loop surface exposed over MCP is intentionally narrow:
 
 - **Review loops** — `bclaw_coordinate(intent="review", open_loop=true, review_mode="asymmetric"|"symmetric", targetAgents=[…])` opens the loop and dispatches the first turn. The reviewer's verdict is then harvested from `LANE-RESULT.json` (`review_verdict`) and **auto-advances/closes the loop on approve** — no manual driving needed for the approve path (pln#628 Focus 4B). `bclaw_loop(intent="turn"|"complete_turn"|"advance"|"close")` remains available to drive turns by hand (e.g. the `request_changes` fix cycle, or a human-operated slot).
+  - **Turn-owned exactly-once fix cycle (default, pln#630).** The autonomous `request_changes` fix-cycle re-dispatch runs through the turn-owned attempt state machine (immutable attempt record + atomic launch fence → spawned at most once; `reconcileTurn` finalizes from read-strict, turn-keyed evidence — the ack-wrapper's completion sentinel). It falls back to the legacy closer when a reviewer resolves to inbox/manual (no sentinel) so the loop still converges. **Kill-switch:** set `BRAINCLAW_TURN_OWNED_REVIEW=0` (also `false`/`off`/`no`) to revert review finalization to the legacy presence-based closer.
 - **Ideation loops** — `bclaw_coordinate(intent="ideate", preset="bootstrap")` opens an ideation loop from a preset.
 
 Custom phase lists (`LoopPhase[]`) and bespoke `StopCondition` logic exist in the loop engine internally, but are **not** exposed through the MCP facade today: `CoordinateRequestSchema` accepts only `open_loop`, `review_mode`, `preflight`, `ref`, and `preset` — no `phases` or `stop_condition` — and the standalone `bclaw_loop` tool does not expose an `open` intent. Programmatic construction of ad-hoc loops is therefore internal / future work until the facade is extended.

package/docs/concepts/observer-protocol.md

@@ -213,6 +213,28 @@ the projection rule).
 > from the seed otherwise. `agents`/`sessions` are never journaled → always seed.
 > A store that has NOT run the supplement keeps the seed (no regression).
 >
+> **Section CONTENT cutover (pln#560 completion):** once `registryAuthoritative()`
+> is set, the registry/coordination sections (ATTENTION, IN_PROGRESS, SPRINTS,
+> and the flat claims/assignments/runs/actions/candidates drill-downs) serve
+> their entity content from the projection too — zero MCP display fetches on
+> expand. The non-journaled extras on the composites (server-computed
+> `workflow_hints`, loops via `bclaw_loop(intent='list')`, and the
+> `bclaw_dispatch_status` evidence digests of §6/§7) remain best-effort reads
+> through the observer-flagged client: when no client resolves, the section
+> still renders its entities. SYSTEM keeps its MCP fetch regardless — it mixes
+> private/machine runtime_notes (never journaled, visibility boundary) and
+> cross-project config, neither derivable from the shared journal.
+>
+> Two parity notes: (a) sections whose MCP fetch pre-filtered `status:
+> 'pending'` server-side (actions, candidates) apply the equivalent pure
+> filter on the projection, because renderers admit broader statuses; (b)
+> journal-served sections are **legacy-inclusive** — the genesis backfill
+> journals `provenance.kind='legacy'` records that the MCP default read
+> filter excludes, and the projection trim drops the nested `provenance`
+> object, so parity with the MCP default is not reconstructable client-side.
+> Accepted deliberately: the operator tree already passes `includeLegacy:
+> true` wherever it fetches explicitly.
+>
 > The historical (pre-pln#568) description below is kept for context.
 
 The journal classifies records into five classes (§2). In phase 1 / `dual`

package/docs/integrations/codex.md

@@ -1,13 +1,13 @@
 # Codex Integration
 
-brainclaw integrates with OpenAI's Codex CLI through MCP tools and shared instruction files. Codex has MCP access, universal skills support, and headless CLI spawn capability, but no native lifecycle hook surface.
+brainclaw integrates with OpenAI's Codex CLI through MCP tools, shared instruction files, and native lifecycle hooks. Codex has MCP access, universal skills support, headless CLI spawn capability, and a native lifecycle hook surface (added upstream in 2026 — [developers.openai.com/codex/hooks](https://developers.openai.com/codex/hooks)).
 
 ## Auto-setup
 
 Codex setup is split across machine and project scope:
 
 - `brainclaw setup-machine --agents codex --yes` writes the machine-level MCP config at `~/.codex/config.toml`
-- `brainclaw init` creates or refreshes the current project's Brainclaw state and writes `AGENTS.md`
+- `brainclaw init` creates or refreshes the current project's Brainclaw state, writes `AGENTS.md`, and writes project-level lifecycle hooks to `.codex/hooks.json` (git-ignored)
 
 If the project already has `.brainclaw/`, rerunning `brainclaw init` is safe and refreshes the managed Brainclaw/Codex files for the current machine.
 
@@ -61,7 +61,7 @@ Since pln#476 (1.0.13+), spawned Codex workers are marked `delivered_and_started
 |-------|-------|
 | Tier | A |
 | MCP | yes |
-| Hooks | no |
+| Hooks | yes (`.codex/hooks.json`, project scope) |
 | Auto-approve | manual (per-tool approval) |
 | Skills | yes |
 | CLI spawnable | yes |
@@ -70,6 +70,22 @@ Since pln#476 (1.0.13+), spawned Codex workers are marked `delivered_and_started
 | MCP config scope | machine |
 | Prompt delivery | `stdin_pipe` (preferred), `inline_arg` (fallback) |
 
+## Lifecycle hooks
+
+`brainclaw init` writes project-level hooks to `.codex/hooks.json` (git-ignored, machine-specific command paths). Codex reads hooks from `hooks.json` or an inline `[hooks]` table at user (`~/.codex/`) and project (`<repo>/.codex/`) scope ([Codex hooks docs](https://developers.openai.com/codex/hooks)). brainclaw wires three events:
+
+| Event | brainclaw command | Purpose |
+|-------|-------------------|---------|
+| `SessionStart` | `brainclaw session-start --include-context` | Load shared context (constraints, decisions, traps, plans, handoffs) when a session begins |
+| `UserPromptSubmit` | `brainclaw context-diff` | Surface what changed since the last turn |
+| `Stop` | `brainclaw session-end --auto-release --reflect --reflect-handoff --dispatch-review` | Release claims, reflect, and dispatch review at turn end |
+
+The file shape is `{ "hooks": { "<Event>": [ { "matcher": "", "hooks": [ { "type": "command", "command": "…" } ] } ] } }` (`matcher: ""` = match all occurrences). brainclaw **owns** these three event arrays: reruns overwrite them (idempotent, no cross-upgrade pile-up) — the same contract as the Cursor / Antigravity hook writers. A user's own hook placed on one of these three events is replaced on the next `init`; hooks on any **other** event are left untouched.
+
+**Scope — interactive sessions, not headless dispatch.** These hooks serve an *interactive* Codex session. Non-managed command hooks require a one-time trust in Codex (`/hooks` — inspect and trust) before they run, so a fresh `.codex/hooks.json` is inert until the user trusts it. Headless dispatched workers (`codex exec`, used by `bclaw_dispatch` / `bclaw_coordinate`) do **not** rely on these hooks at all — they receive their context in the dispatch brief and report via `LANE-RESULT.json`; an untrusted project hook is simply skipped there, which is harmless. (A "managed" hook path via `requirements.toml`/MDM could bypass the trust step for fleets — a possible future enhancement.)
+
+**Per-event output contract.** `SessionStart` and `UserPromptSubmit` emit their stdout as **model-visible context** — that is exactly the point (inject shared brainclaw state / the context diff). `Stop`, by contrast, expects a **JSON** response from Codex to shape turn-end behavior; brainclaw's `session-end` runs mainly for its side effects (release claims, reflect, dispatch review) and does not emit that JSON, so it does not gate the turn. Emitting a conformant per-event JSON response (notably for `Stop`) is a planned follow-up.
+
 ## Caveats
 
 - **Sandbox blocks `git commit`, not MCP** (dec#133): a sandboxed Codex run reaches brainclaw MCP (the server is a separate out-of-sandbox process; `approval_policy=never` auto-approves). What the sandbox *does* block is direct writes to paths outside the worktree root — notably `.git`, so the worker cannot `git commit`. Leave fixes uncommitted; the coordinator integrates + commits the worktree diff at harvest. A LANE-RESULT.json / filesystem-direct candidate write remains a valid fallback for reporting.

package/docs/mcp-schema-changelog.md

@@ -10,6 +10,33 @@ guarantees this changelog follows.
 
 ## Unreleased
 
+**Added — turn-attempt evidence-correlation fields (pln#630 PR2b-a)**
+- Additive, backward-compatible: `LaneResultSchema` gains optional `turn_id` /
+  `run_id` / `nonce`; `RuntimeEventSchema` gains optional `turn_id` / `nonce`
+  (`run_id` already present); `LoopSlotSchema` gains optional `current_turn_id`;
+  a `turn_reserved` variant joins the loop event journal. All optional/defaulted
+  — legacy records parse unchanged; no tool added/removed/renamed.
+- `LoopSlotSchema.current_turn_id` flows into the zod-derived `LoopSlotInput`
+  embedded in `bclaw_loop`'s published inputSchema, so it DOES move the public
+  MCP surface fingerprint (bumped in the `(current)` section below) and
+  regenerates `mcp-schemas.generated.ts`. Additive optional field — no breaking
+  change to the tool contract.
+
+**Changed — `bclaw_read_inbox` bounded + focused reads (pln#627 Phase A)**
+- Default status filter is now **actionable** (pending + read); acknowledged and
+  archived are hidden unless `includeAll=true` or an explicit `status` is passed.
+  Previously an unset status returned every message (the "pending by default"
+  description was wrong).
+- Results are ordered **newest-first** by `created_at` before pagination, so a
+  bounded page serves the most recent messages instead of the oldest debris.
+- Message bodies are **previewed** (~500 chars) with `text_length` + `truncated`;
+  the full body is returned only with `full=true`. The page is size-bounded by
+  `budget_tokens` (like `bclaw_find` / `bclaw_search`), with `has_more` /
+  `next_offset` paging hints — a single read can no longer blow the token budget.
+- Input schema gains `includeAll`, `full`, and `budget_tokens` (additive; moves
+  the surface fingerprint — see the current section). `structuredContent.messages`
+  now carries `text_length` + `truncated` per message.
+
 **Added — `LaneResultSchema.review_verdict` / `review_summary` (pln#628 Focus 4B)**
 - `LANE-RESULT.json` (the worktree-root file a dispatched worker writes) gains two
   optional fields: `review_verdict` (`approve` | `request_changes`) and
@@ -238,7 +265,22 @@ will still succeed. A follow-up PR will strip the dead handler code.
   changelog records the published MCP surface fingerprint. When a tool
   name, tier, category, or input schema changes, the test fails until
   this section is updated.
-- MCP public surface fingerprint: `sha256:468f0103414e97e8`
+- MCP public surface fingerprint: `sha256:8241fa50b8cb4805`
+  (updated 2026-07-25 for pln#632: `bclaw_loop` gains the `bind` intent — an
+  implementation loop dispatches its linked sequence and advances bind→execute — plus
+  its typed inputSchema properties `dry_run`, `lanes`, `auto_execute`, `model`, and
+  `max_assignments`. Additive — no tool added/removed/renamed; the new enum value + the
+  new properties move the fingerprint.)
+  Previous: `sha256:f3d49b28d2d366bb`
+  (updated 2026-07-24 for pln#630 PR2b-a: `LoopSlotSchema` gains an optional
+  `current_turn_id`, which flows through the zod-derived `LoopSlotInput` into
+  `bclaw_loop`'s published inputSchema. Additive optional field; regenerates
+  `mcp-schemas.generated.ts`.)
+  Previous: `sha256:fd8a7e910bf5f751`
+  (updated 2026-07-24 for pln#627 Phase A: the `bclaw_read_inbox` input schema
+  gains `includeAll`, `full`, and `budget_tokens`. Additive — no tool
+  added/removed/renamed; the three new typed properties move the fingerprint.)
+  Previous: `sha256:468f0103414e97e8`
   (updated 2026-07-18 for pln#625 PR #83 + Codex review: `bclaw_list_agents`
   retired and `bclaw_find(entity='agent')` gains `includeReputation` — now typed
   as a boolean in `GRAMMAR_FILTER_CONTRACT.booleanKeys` and validated at the MCP

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brainclaw",
-  "version": "1.16.0",
+  "version": "1.18.0",
   "description": "Shared project memory for humans and coding agents.",
   "type": "module",
   "repository": {