v0.41.0 - Agent Write Contract Suite

Open Second Brain v0.41.0 - Agent Write Contract Suite

The Agent Write Contract Suite defines how external agents write into and deliberate with the Brain while the core stays deterministic: a file-backed write-session kernel gives callers a JSON-envelope lifecycle where opening a session returns the generation prompt, schema hints, and collision metadata, submitting returns machine-readable correction errors without losing state, and only a cleanly validated artifact commits - atomically, audited, and never over an existing file without explicit intent; a multi-persona decision panel rides the same kernel as a session kind, memory import gains a pluggable backend boundary with the Claude Code adapter as its byte-identical default, and explicit remember-writes can mirror into a cross-agent shared namespace that fails soft by contract.

What ships

• Write-session protocol. o2b brain session open --target Brain/...md (and the MCP brain_write_session tool) opens a session whose envelope tells the calling agent exactly what to generate; submit validates fail-closed and answers done, needs-correction with coded {code, path, message} errors plus a compact correction prompt (retry cap default 3, then terminal), or needs-review for operator-gated sessions where a separate approve commits. Sessions persist as plain JSON under Brain/.sessions/write/ with lazy TTL and a sweep operation - they survive process restarts and vault sync. Reserved namespaces (Brain/preferences/, Brain/log/, Brain/_brain.yaml, machine stores) are refused before a session opens; create intent never overwrites (checked at submit AND at the commit chokepoint, closing the approve-window race); merge appends a session-stamped delimited section and existing bytes survive verbatim. Every terminal transition lands exactly one write-session audit event in the Brain log.
• Decision panel. o2b brain panel open <topic> convenes distinct analytical lenses as deterministic session steps - persona:<slug> in declared order, then synthesis with every accepted answer in view - and commits a structured decision note under Brain/decisions/panels/ with per-persona sections. Personas are operator-curated notes under Brain/personas/ (built-in default set: technical, strategic, risk, user-experience). The panel inherits the kernel's correction loop, retry cap, TTL, review gate, and audit instead of owning a second state machine; the Brain supplies sequencing and validation only, the calling agent authors every word.
• Memory backend boundary. A MemorySourceBackend protocol (discoverMemoryDir, parseMemoryFile, renderPreference, slugifyName) with a frozen registry and config-driven selection via the memory_backend key (default claude). The Claude Code adapter delegates to the existing import modules - regression tests pin the default path byte-identical - and an unknown backend id fails loudly with the registered list. A second agent runtime becomes one self-contained adapter module, no core changes.
• Cross-agent shared namespace. The opt-in shared_namespace config key mirrors explicit remember-writes (feedback signals and narrative notes) into a second vault after the primary write succeeds, attributed by agent identity plus origin_vault. Mirroring is fail-soft by contract: a broken or self-pointing shared vault degrades to a reported mirror: "failed" and the primary write never notices; the key absent means zero behavior change.

Process wins

• One shared kernel carries the suite: the panel is a session kind on the write-session engine, so TTL, retry, collision metadata, review gating, and audit were built once and reused - the consultant's unified-kernel recommendation made structural.
• The no-LLM-in-core rule survives contact with generation: every artifact byte comes from the calling agent, and the deterministic core contributes prompts, validation, sequencing, and atomic commits - regeneration is diffable and auditable.
• Everything additive: no existing record shape or public API changes, the MCP contract grows by exactly one deliberate tool (65 -> 66), and unconfigured setups stay byte-identical on every seam (backend, mirror, sessions).

Notes

• Session files live inside the vault, so an interrupted correction loop resumes on another device; concurrent same-second opens are safe - the first save goes through an exclusive hardlink-based create, so two openers can never claim the same id.
• The store reads fail closed: a valid-JSON but structurally incomplete session record surfaces as an error probe, never as writable state; sweep also removes files whose names violate the id grammar.
• Verification: 3,761 tests pass (+80 across 10 new suites including an end-to-end flow), typecheck clean, lint baseline unchanged (111 warnings, 0 errors), 60 Python provider tests pass, all version manifests synced to 0.41.0, live smoke of session open -> correction -> commit and a full panel run on a real vault, independent reviewer pass (2 blockers fixed pre-QA) plus a CodeRabbit pass with 13 of 14 findings applied and 1 declined with written rationale.