ltcai 8.2.0 → 8.4.0

package/README.md

@@ -1,6 +1,6 @@
 # Lattice AI
 
-**Lattice AI 8.0 is the local-first Digital Brain platform with hardened runtime architecture. It keeps your knowledge durable across any AI model, with AgentRuntime, ToolRegistry, central Config, and Knowledge Graph stability tracked by explicit release contracts.**
+**Lattice AI 8.4.0 is the local-first Digital Brain platform with action-aware Brain Chat that creates files through the governed workspace file tool instead of only returning code.**
 
 **Lattice AI는 모델이 바뀌어도 내 지식과 맥락을 보존하는 로컬 우선 AI 브레인입니다.**
 
@@ -11,7 +11,7 @@ downloads, update checks, and other external communication happen only after
 explicit consent.
 
 It is not a ChatGPT clone, a model launcher, a graph database, or a note app.
-It is the finished private AI memory layer wrapped in a Living Brain experience — now with the 8.0 runtime architecture contract behind it.
+It is the finished private AI memory layer wrapped in a Living Brain experience — now with an 8.4.0 action-readiness contract behind chat-to-tool file creation, onboarding, orchestration, graph ingestion, and the plugin/community path.
 
 [![PyPI Version](https://img.shields.io/pypi/v/ltcai?label=PyPI)](https://pypi.org/project/ltcai/)
 [![npm Version](https://img.shields.io/npm/v/ltcai?label=npm)](https://www.npmjs.com/package/ltcai)
@@ -64,9 +64,10 @@ You need Lattice AI when:
 
 ## Living Brain Flow
 
-The screenshots below are release evidence captures. The 8.1 line keeps the
-first-run flow and refreshes Brain Home so the living Brain, recent memory,
-next action, and composer are understandable in one glance.
+The screenshots below are the latest checked-in visual evidence captures from
+the 8.2 Brain Home release. The 8.3 line keeps that first-run flow focused on
+the Brain while adding clearer onboarding, stronger workflow/runtime
+boundaries, and better ingestion proof behind the scenes.
 
 ### 1. Wake Brain
 
@@ -203,27 +204,32 @@ See [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) for developer workflow details.
 
 ## Current Release
 
-The current release is **8.2.0 — Brain Brief**:
+The current release is **8.4.0 — Action-Aware Brain Chat**:
 
-- Brain Home now includes an evidence-backed Brain Brief that says what to notice, why it is trustworthy, and what to do next.
-- The brief is generated by `MemoryService` from real workspace memory, conversation, graph, vector, and source-health signals instead of frontend-only placeholders.
-- Empty Brain states stay honest: the UI suggests adding a source or asking a first question without claiming model-continuity proof.
-- Alive Brain states surface recall evidence, connected topics, model-continuity verification, and backup management as direct actions.
-- The 8.0 runtime architecture contract remains active: AgentRuntime, ToolRegistry, Config, server decomposition, and KG hardening stay machine-checkable through readiness gates.
-- CI and release workflows continue to run frontend lint/typecheck/build gates plus product readiness before a tag can be treated as release-safe.
+- Brain Chat now routes explicit file create/write/save/edit requests through
+  the governed workspace file tool instead of treating them as ordinary prose
+  generation.
+- Requests such as `hello.md 파일 만들어줘` are executed through
+  `write_file`/`edit_file` style tool paths, and created artifacts are returned
+  in the chat response.
+- Normal Q&A stays on the low-friction `/chat` generation path; only explicit
+  side-effect requests move into the tool-running agent loop.
+- The release keeps the 8.3.0 managed legacy inventory, AgentRuntime/workflow
+  boundaries, unified graph ingestion, and workspace-safe duplicate content
+  protections active.
 
-Expected artifacts for 8.2.0 release must use exact filenames:
+Expected artifacts for 8.4.0 release must use exact filenames:
 
-- `dist/ltcai-8.2.0-py3-none-any.whl`
-- `dist/ltcai-8.2.0.tar.gz`
-- `ltcai-8.2.0.tgz`
-- `dist/ltcai-8.2.0.vsix`
-- `src-tauri/target/release/bundle/dmg/Lattice AI_8.2.0_aarch64.dmg`
+- `dist/ltcai-8.4.0-py3-none-any.whl`
+- `dist/ltcai-8.4.0.tar.gz`
+- `ltcai-8.4.0.tgz`
+- `dist/ltcai-8.4.0.vsix`
+- `src-tauri/target/release/bundle/dmg/Lattice AI_8.4.0_aarch64.dmg`
 
 Do not use wildcard artifact uploads. Package registry publishing remains owner-run.
 
 See [docs/ROADMAP_RECOMMENDATIONS.md](docs/ROADMAP_RECOMMENDATIONS.md) for the
-strategic roadmap slices applied through 8.2.0 and the follow-up tracks.
+strategic roadmap slices applied through 8.4.0 and the follow-up tracks.
 
 ## Known Limitations
 
@@ -240,6 +246,8 @@ strategic roadmap slices applied through 8.2.0 and the follow-up tracks.
 
 | Version | Theme |
 | --- | --- |
+| 8.4.0 | Action-Aware Brain Chat: explicit file create/write/save/edit requests from Brain Chat route into the governed workspace file tool so files are actually created instead of returned as code-only answers |
+| 8.3.0 | Orchestrated Brain Readiness: managed legacy shim inventory, stronger AgentRuntime/workflow boundaries, unified graph ingestion, workspace-safe duplicate content, first-run onboarding, and explicit community/plugin growth path |
 | 8.2.0 | Brain Brief: evidence-backed home briefing, honest empty-state guidance, recall/graph/model-proof next actions, and continued model/workspace runtime extraction |
 | 8.1.0 | Intuitive Brain Home: living Brain, recent memory, connected topic, next action, and composer are visible in one product-first screen with refreshed 8.1.0 evidence and artifacts |
 | 8.0.0 | Runtime Architecture Contract: AgentRuntime, ToolRegistry, central Config, server decomposition, and KG hardening are captured as machine-checkable release boundaries with exact 8.0.0 artifacts |

package/docs/CHANGELOG.md

@@ -8,6 +8,65 @@ existed at that release.
 
 No unreleased changes.
 
+## [8.4.0] - 2026-07-01
+
+### Added
+- Added a chat-to-agent file action gate so explicit file create/write/save/edit
+  requests from Brain Chat execute through the governed workspace file tool.
+- Added regression coverage that verifies `/chat` routes file creation intent to
+  the workspace file tool and returns created artifact metadata.
+
+### Changed
+- Kept ordinary Q&A on `/chat` while routing only explicit side-effect file
+  requests into the planner/executor/reviewer tool loop.
+- Synchronized package/runtime/static/Tauri metadata and current-release docs to
+  8.4.0.
+
+### Fixed
+- Allowed literal `/chat` file writes with user-provided content to execute
+  before model loading, while still using a loaded model when content must be
+  synthesized.
+- Narrowed file target and content parsing to avoid treating surrounding prose
+  as the workspace path or literal file body.
+- Restored model loading dependency exports after the runtime/loading split so
+  `/models/load` can prepare local MLX models again.
+- Added the common Gemma 4 26B shorthand alias to the canonical
+  `mlx-community/gemma-4-26b-a4b-it-4bit` model id.
+- Updated the local server launcher to run `python -m uvicorn` from the active
+  virtual environment, avoiding stale console-script interpreter bindings.
+
+## [8.3.0] - 2026-07-01
+
+### Added
+- Added a managed legacy compatibility report for remaining root shims,
+  including owners, replacements, reasons, removal phases, and readiness
+  metrics.
+- Added AgentRuntime/workflow maturity evidence through lifecycle helper reuse,
+  legacy event compatibility, WorkflowEngine boundary/config inspection, and
+  centralized legacy workflow step projection.
+- Added graph ingestion coverage for upload-to-pipeline behavior and
+  workspace-safe duplicate content.
+- Added 8.3.0 onboarding and community/plugin growth documentation.
+
+### Changed
+- Routed `/knowledge-graph/ingest` through the unified `IngestionPipeline` when
+  available, preserving provenance and hook lifecycle behavior for MCP notes and
+  messages.
+- Isolated text/web/note graph node identity by workspace while preserving the
+  content hash used for duplicate detection.
+- Converted `mcp_registry.py` and `llm_router.py` into physical module aliases
+  for their current implementations.
+- Improved upload client error handling so failed uploads cannot look
+  successful.
+- Synchronized package/runtime/static/Tauri metadata and current-release docs to
+  8.3.0.
+
+### Upgrade Notes
+- Existing legacy-global text/web/note graph nodes are not rewritten in place.
+  Re-ingesting the same content with a workspace id can create a separate
+  workspace-scoped node; re-index existing sources after upgrading when you want
+  provenance to converge on workspace scopes.
+
 ## [8.2.0] - 2026-06-27
 
 ### Added

package/docs/COMMUNITY_AND_PLUGINS.md

@@ -0,0 +1,43 @@
+# Community And Plugins
+
+Current release: **8.4.0 - Action-Aware Brain Chat**.
+
+LatticeAI 8.4.0 defines the path from a strong local-first framework to a
+product ecosystem. The immediate goal is small and practical: make it clear how
+contributors can extend the Brain without weakening local-first trust,
+workspace scoping, or release quality.
+
+## Community Entry Points
+
+- Start with the product docs: `README.md`, `docs/WHY_LATTICE.md`, and
+  `docs/ONBOARDING.md`.
+- Use `docs/DEVELOPMENT.md` for local setup, validation, and release gates.
+- Use `docs/PLUGIN_SDK.md` for plugin manifests, compatibility, permissions,
+  lifecycle state, catalog endpoints, and install flows.
+- Use `plugins/hello-world/plugin.json` as the minimum working plugin shape.
+
+## Plugin Direction
+
+Plugins should add one bounded capability at a time:
+
+- new ingestion sources that still route through `IngestionPipeline`;
+- graph-aware tools that preserve workspace scoping;
+- workflow templates that declare permissions explicitly;
+- editor or automation helpers that keep secrets out of logs and audit payloads;
+- local-first integrations that require explicit opt-in before network access.
+
+## Guardrails
+
+- No plugin should bypass the ToolRegistry, permission model, or audit hooks.
+- No plugin should write graph data without provenance.
+- No plugin should assume a cloud model, remote registry, or network connection.
+- Compatibility requirements belong in `lattice_version`, and examples should
+  use current host-compatible values.
+
+## 8.4.0 Ecosystem Tasks
+
+- Keep the hello-world plugin valid and boring.
+- Expand examples only when they exercise real extension seams.
+- Add tests before treating a plugin API as stable.
+- Prefer documentation that helps a first contributor build one useful plugin
+  over broad ecosystem promises.

package/docs/DEVELOPMENT.md

@@ -1,10 +1,10 @@
 # Lattice AI Development
 
-Current release: **8.2.0 - Brain Brief**.
+Current release: **8.4.0 - Action-Aware Brain Chat**.
 
 This document is for contributors working on the local-first Digital Brain
 codebase. Product positioning and quick start stay in `README.md`; release
-history is intentionally limited to 7.0.0-8.2.0 in `docs/CHANGELOG.md` and
+history is intentionally limited to 7.0.0-8.4.0 in `docs/CHANGELOG.md` and
 `RELEASE.md`.
 
 ## Product Contract
@@ -112,10 +112,10 @@ For user-facing, API, runtime, release, or packaging changes, check:
 Release/publish examples must use exact target-version filenames. Do not
 document wildcard artifact upload commands.
 
-For 8.2.0 release work, exact artifacts are:
+For 8.4.0 release work, exact artifacts are:
 
-- `dist/ltcai-8.2.0-py3-none-any.whl`
-- `dist/ltcai-8.2.0.tar.gz`
-- `ltcai-8.2.0.tgz`
-- `dist/ltcai-8.2.0.vsix`
-- `src-tauri/target/release/bundle/dmg/Lattice AI_8.2.0_aarch64.dmg`
+- `dist/ltcai-8.4.0-py3-none-any.whl`
+- `dist/ltcai-8.4.0.tar.gz`
+- `ltcai-8.4.0.tgz`
+- `dist/ltcai-8.4.0.vsix`
+- `src-tauri/target/release/bundle/dmg/Lattice AI_8.4.0_aarch64.dmg`

package/docs/LEGACY_COMPATIBILITY.md

@@ -1,12 +1,21 @@
 # Legacy Compatibility Map
 
-Current release: **8.2.0 - Brain Brief**.
+Current release: **8.4.0 - Action-Aware Brain Chat**.
 
 Lattice AI is moving toward a smaller, modular architecture centered on
 `lattice_brain`, `latticeai.services`, `latticeai.api`, and `latticeai.runtime`.
 Some root-level modules remain packaged for compatibility with older imports,
 CLI entrypoints, or extension workflows. Their presence does not define the
-current 8.2.0 architecture.
+current 8.4.0 architecture.
+
+8.4.0 also tracks the inner compatibility layers that sit below the root
+modules. The managed inventory lives in `latticeai.core.legacy_compatibility`
+and groups shims by layer:
+
+- `root`: historical repo-root imports such as `knowledge_graph.py`.
+- `brain-flat`: pre-graph-package imports such as `lattice_brain.store`.
+- `deprecated-namespace`: older `latticeai.brain.*` package imports.
+- `service-alias`: service paths that now alias Brain runtime modules.
 
 ## Current Policy
 
@@ -17,6 +26,9 @@ current 8.2.0 architecture.
 - Add deprecation notes before removal.
 - Avoid breaking package users during a minor release.
 - Do not silently remove rollback, backup, restore, or migration paths.
+- Track every remaining shim through `latticeai.core.legacy_compatibility` so
+  release readiness can report owner, replacement, reason, removal phase, and
+  missing files.
 
 ## Root Module Map
 
@@ -35,6 +47,14 @@ current 8.2.0 architecture.
 | `setup_wizard.py` | setup and model recommendation services | Compatibility for first-run recommendation calls |
 | `server.py` | lazy proxy to `latticeai.server_app` / `latticeai.app_factory` | Preserves historical `server.app` imports without import-time construction |
 
+## Inner Shim Layers
+
+| Legacy layer | Example module | Current home / direction | Why it remains |
+| --- | --- | --- | --- |
+| `brain-flat` | `lattice_brain.store`, `lattice_brain.ingest`, `lattice_brain.retrieval` | `lattice_brain.graph.*` | Preserves imports from before graph modules were split into a package |
+| `deprecated-namespace` | `latticeai.brain.store`, `latticeai.brain.ingest` | `lattice_brain.graph.*` | Preserves the old application-package Brain namespace |
+| `service-alias` | `latticeai.services.agent_runtime` | `lattice_brain.runtime.agent_runtime` | Preserves service-layer imports while runtime ownership sits in Brain Core |
+
 ## Packaging Notes
 
 `pyproject.toml` and `package.json` still include several root modules because

package/docs/ONBOARDING.md

@@ -0,0 +1,38 @@
+# Lattice AI Onboarding
+
+Current release: **8.4.0 - Action-Aware Brain Chat**.
+
+The first-run goal is a five-minute path from "I opened the app" to "my Brain
+has a source, a question, and proof." This page is the product contract behind
+that flow; the UI should make these steps obvious without asking a new user to
+read the docs first.
+
+## Five-Minute Flow
+
+1. Wake the Brain and confirm the local owner profile.
+2. Let Lattice inspect local model/runtime readiness.
+3. Pick the recommended Brain voice or skip model loading.
+4. Add one source: upload a file, connect a folder, save a note, or capture a
+   browser/source event.
+5. Ask one grounded question and inspect the answer proof.
+6. Open the Knowledge Graph only when the user wants source-level evidence.
+7. Back up the Brain once useful memory exists.
+
+## Product Promises
+
+- The user starts in the Brain, not in an admin dashboard.
+- Empty states suggest one concrete next action without claiming proof that does
+  not exist yet.
+- Upload, note, browser, and message ingestion all converge through the unified
+  ingestion pipeline when it is available.
+- Workspace-scoped content must not leak or overwrite another workspace's graph
+  metadata.
+- Advanced runtime, workflow, plugin, and admin surfaces are available, but they
+  do not block the first conversation.
+
+## Release Gate
+
+8.4.0 treats onboarding as a release gate, not marketing copy. The current
+machine-checkable product readiness report requires this five-minute contract,
+the Brain Home surface, setup helpers, graph ingestion tests, and exact release
+artifact documentation before the release can be called complete.

package/docs/TRUST_MODEL.md

@@ -1,6 +1,6 @@
 # Lattice AI Trust Model
 
-Current release: **8.2.0 - Brain Brief**.
+Current release: **8.4.0 - Action-Aware Brain Chat**.
 
 Lattice AI is local-first, explicit about external communication, and honest
 when a capability is unavailable.

package/docs/WHY_LATTICE.md

@@ -1,6 +1,6 @@
 # Why Lattice AI Exists
 
-Current release: **8.2.0 - Brain Brief**.
+Current release: **8.4.0 - Action-Aware Brain Chat**.
 
 **Lattice AI is a local-first Digital Brain that keeps your knowledge durable
 across any AI model.**
@@ -32,9 +32,10 @@ The graph matters, but it is not the product identity. The product identity is a
 local-first Digital Brain: a place where the user can talk, add sources, watch
 memory grow, and inspect the Knowledge Graph when they need proof.
 
-In 8.2.0 the first screen is intentionally not a dashboard. The living Brain,
-conversation composer, and evidence-backed Brain Brief appear together so the
-user immediately knows what matters and what to do next.
+In 8.4.0 the first screen is intentionally not a dashboard. The living Brain,
+conversation composer, evidence-backed Brain Brief, and five-minute onboarding
+path appear together so the user immediately knows what matters, what to add,
+and why the answer is grounded in local memory.
 
 ## Practical Reasons To Use It
 

package/docs/kg-schema.md

@@ -1,6 +1,6 @@
 # Knowledge Graph Schema
 
-Current release: **8.2.0 - Brain Brief**.
+Current release: **8.4.0 - Action-Aware Brain Chat**.
 
 명세 출처: `lattice_ai_full_spec.pptx` 슬라이드 20·21·22
 구현: `kg_schema.py`
@@ -90,7 +90,7 @@ Edge {
 
 ## Current Knowledge Graph First 엔티티/관계
 
-8.2.0 은 "모든 데이터 소스가 Knowledge Graph 로 수렴한다"는 원칙을 1급 스키마로
+8.4.0 은 "모든 데이터 소스가 Knowledge Graph 로 수렴한다"는 원칙을 1급 스키마로
 승격한다. 아래 타입은 **추가형(additive)**이다 — 기존 enum/legacy 매핑을 깨지 않고
 `from_legacy` 가 무손실로 정규화하며, 알 수 없는 타입은 여전히 `CONCEPT`/`MENTIONS` 로
 폴백한다. 스키마는 **확장 가능**하게 유지한다: 새 도메인 엔티티는 enum 멤버 1개 +
@@ -138,7 +138,7 @@ provenance(source_type, source_uri, content_hash, captured_at, modified_at,
 - provenance 는 노드 `metadata.provenance` 에 임베드되며, 동시에 감사 가능한
   `ingestion_provenance` 테이블에 기록된다 (`KnowledgeGraphStore.get_provenance(node_id)`).
 
-구현: `latticeai/services/ingestion.py` (`IngestionPipeline`) 가 단일 진입점이며,
+구현: `lattice_brain/ingestion.py` (`IngestionPipeline`) 가 단일 진입점이며,
 파일/로컬폴더/URL/브라우저 탭/텍스트를 모두 이 형태로 정규화한다.
 
 ---

package/lattice_brain/__init__.py

@@ -26,7 +26,7 @@ from .storage import (
     storage_from_env,
 )
 
-__version__ = "8.2.0"
+__version__ = "8.4.0"
 
 __all__ = [
     "AgentRuntime",

package/lattice_brain/graph/ingest.py

@@ -490,8 +490,6 @@ class KnowledgeGraphIngestMixin:
         is derived from (source_type, source_uri | content_hash) so re-ingesting
         the same origin reuses the same SOURCE node (idempotent).
         """
-        key = source_uri or content_hash or content_node_id
-        source_id = f"source:{_sha256_text(f'{source_type}|{key}')[:24]}"
         meta = {
             "source_type": source_type,
             "source_uri": source_uri,
@@ -499,6 +497,9 @@ class KnowledgeGraphIngestMixin:
             "captured_at": captured_at or _now(),
             **(extra or {}),
         }
+        key = source_uri or content_hash or content_node_id
+        source_scope = meta.get("workspace_id") or "legacy-global"
+        source_id = f"source:{_sha256_text(f'{source_scope}|{source_type}|{key}')[:24]}"
         label = title or source_uri or source_type
         self._upsert_node(
             conn,
@@ -551,7 +552,8 @@ class KnowledgeGraphIngestMixin:
         )
         captured_at = captured_at or _now()
         content_hash = _sha256_text(f"{source_type}|{source_uri or ''}|{text}")
-        content_id = f"webdoc:{content_hash[:24]}"
+        identity_hash = _sha256_text(f"{workspace_id or 'legacy-global'}|{content_hash}")
+        content_id = f"webdoc:{identity_hash[:24]}"
         full_text = f"{title}\n{text}"
         node_meta = {
             "source_type": source_type,
@@ -581,6 +583,8 @@ class KnowledgeGraphIngestMixin:
                 summary=(text or title)[:500],
                 metadata=node_meta,
                 raw=node_meta,
+                owner=owner,
+                workspace_id=workspace_id,
             )
             # ── SOURCE 노드 + indexed_from 엣지 (출처 추적) ──────────────────
             source_node_id = self._attach_source_node(
@@ -597,13 +601,27 @@ class KnowledgeGraphIngestMixin:
             if owner:
                 person_id = f"person:{_slug(owner)}"
                 self._upsert_node(
-                    conn, person_id, "Person", owner, metadata={"email": owner}
+                    conn,
+                    person_id,
+                    "Person",
+                    owner,
+                    metadata={"email": owner, "workspace_id": workspace_id},
+                    owner=owner,
+                    workspace_id=workspace_id,
                 )
                 self._upsert_edge(conn, person_id, content_id, "업로드함", weight=1.0)
             # ── 대화 연결 ───────────────────────────────────────────────────
             if conversation_id:
                 conv_id = f"conversation:{_slug(conversation_id)}"
-                self._upsert_node(conn, conv_id, "Chat", conversation_id)
+                self._upsert_node(
+                    conn,
+                    conv_id,
+                    "Chat",
+                    conversation_id,
+                    metadata={"conversation_id": conversation_id, "workspace_id": workspace_id},
+                    owner=owner,
+                    workspace_id=workspace_id,
+                )
                 self._upsert_edge(conn, conv_id, content_id, "언급함", weight=0.8)
             # ── RAG 청크 ────────────────────────────────────────────────────
             for index, chunk in enumerate(_chunks(text)):
@@ -615,7 +633,9 @@ class KnowledgeGraphIngestMixin:
                     "Chunk",
                     f"{title} chunk {index + 1}",
                     summary=chunk[:500],
-                    metadata={"index": index, "source_node": content_id},
+                    metadata={"index": index, "source_node": content_id, "workspace_id": workspace_id},
+                    owner=owner,
+                    workspace_id=workspace_id,
                 )
                 self._upsert_chunk(
                     conn,
@@ -636,7 +656,13 @@ class KnowledgeGraphIngestMixin:
                     cid,
                     node_t,
                     concept,
-                    metadata={"auto_extracted": True, "source_type": source_type},
+                    metadata={
+                        "auto_extracted": True,
+                        "source_type": source_type,
+                        "workspace_id": workspace_id,
+                    },
+                    owner=owner,
+                    workspace_id=workspace_id,
                 )
                 self._upsert_edge(conn, content_id, cid, "포함함", weight=0.8)
             for triple in triples:
@@ -662,8 +688,14 @@ class KnowledgeGraphIngestMixin:
                     sem_type,
                     sem_title,
                     summary=item["summary"],
-                    metadata={"auto_extracted": True, "source_node": content_id},
+                    metadata={
+                        "auto_extracted": True,
+                        "source_node": content_id,
+                        "workspace_id": workspace_id,
+                    },
                     raw=item,
+                    owner=owner,
+                    workspace_id=workspace_id,
                 )
                 self._upsert_edge(conn, content_id, sem_id, "포함함", weight=0.9)
 

package/lattice_brain/runtime/agent_runtime.py

@@ -266,7 +266,7 @@ class AgentRuntime:
         unknown_roles = [role for role in requested_roles if role not in AGENT_ROLES]
         health = self.health()
         goal_ready = bool(str(goal or "").strip())
-        retry_budget = max(0, min(int(max_retries or 0), self._max_retries_cap))
+        retry_budget = self._clamp_retries(max_retries)
         blocking_reasons: List[str] = []
         if not goal_ready:
             blocking_reasons.append("goal is required")
@@ -324,6 +324,7 @@ class AgentRuntime:
     def events(self, run_id: str, *, scope: Optional[str] = None) -> Dict[str, Any]:
         run = self._store.get_agent_run(run_id, workspace_id=scope)
         status = str(run.get("status") or "")
+        contract = extract_contract(run)
         return {
             "run_id": run_id,
             "status": status,
@@ -331,7 +332,7 @@ class AgentRuntime:
             "current_role": run.get("current_role"),
             "timeline": run.get("timeline") or [],
             "handoffs": run.get("handoffs") or [],
-            "contract": contract_view(run),
+            "contract": contract_view(contract) if contract is not None else None,
         }
 
     # ── execution ─────────────────────────────────────────────────────────
@@ -360,6 +361,9 @@ class AgentRuntime:
                 raise PermissionError(pre_dispatch.get("block_reason") or "Agent run blocked by a pre_run hook.")
         return pre_dispatch
 
+    def _clamp_retries(self, max_retries: int) -> int:
+        return max(0, min(int(max_retries or 0), self._max_retries_cap))
+
     @staticmethod
     def _result_patch(result: Any, goal: str) -> Dict[str, Any]:
         return {
@@ -488,7 +492,7 @@ class AgentRuntime:
                 workspace_id=scope,
                 inputs=inputs or {},
                 roles=roles or None,
-                max_retries=max(0, min(int(max_retries or 0), self._max_retries_cap)),
+                max_retries=self._clamp_retries(max_retries),
             )
         except Exception as exc:
             failed = self._store.update_agent_run(
@@ -571,25 +575,13 @@ class AgentRuntime:
         if not str(goal or "").strip():
             raise ValueError("goal is required")
 
-        # ── pre_run hooks ─────────────────────────────────────────────────
-        # A blocking pre_run hook (e.g. a policy gate) aborts the run before any
-        # orchestration happens. Hook failures never crash the run (fire_hook
-        # swallows them); only an explicit block stops it.
-        pre_dispatch: Optional[Dict[str, Any]] = None
-        if self._hooks is not None:
-            pre_dispatch = self._hooks.fire_hook(
-                "pre_run", "agent.run",
-                payload={"goal": goal, "roles": roles or None, "max_retries": max_retries},
-                user_email=user_email, workspace_id=scope,
-            )
-            if pre_dispatch.get("blocked"):
-                self._append_audit_event(
-                    "multi_agent_run_blocked",
-                    user_email=user_email,
-                    reason=pre_dispatch.get("block_reason"),
-                )
-                raise PermissionError(pre_dispatch.get("block_reason") or "Agent run blocked by a pre_run hook.")
-
+        pre_dispatch = self._fire_pre_run(
+            goal=goal,
+            roles=roles,
+            max_retries=max_retries,
+            user_email=user_email,
+            scope=scope,
+        )
         orchestrator = self._live_orchestrator(user_email, scope)
         result = orchestrator.run(
             goal,
@@ -597,7 +589,7 @@ class AgentRuntime:
             workspace_id=scope,
             inputs=inputs or {},
             roles=roles or None,
-            max_retries=max(0, min(int(max_retries or 0), self._max_retries_cap)),
+            max_retries=self._clamp_retries(max_retries),
         )
         run = self._store.record_agent_run(
             agent_id=result.agent_id,
@@ -626,20 +618,13 @@ class AgentRuntime:
             retries=result.retries,
         )
 
-        # ── post_run hooks ────────────────────────────────────────────────
-        post_dispatch: Optional[Dict[str, Any]] = None
-        if self._hooks is not None:
-            run_id = run.get("id") or run.get("run_id") if isinstance(run, dict) else None
-            post_dispatch = self._hooks.fire_hook(
-                "post_run", "agent.run",
-                payload={
-                    "run_id": run_id,
-                    "agent_id": result.agent_id,
-                    "status": result.status,
-                    "retries": result.retries,
-                },
-                user_email=user_email, workspace_id=scope,
-            )
+        run_id = run.get("id") or run.get("run_id") if isinstance(run, dict) else None
+        post_dispatch = self._post_run_hooks(
+            run_id=run_id,
+            result=result,
+            user_email=user_email,
+            scope=scope,
+        )
 
         result_payload = result.as_dict()
         result_payload["contract"] = multi_agent_contract(result=result, goal=goal, run_id=run.get("id") if isinstance(run, dict) else None)

package/lattice_brain/runtime/multi_agent.py

@@ -21,7 +21,7 @@ from typing import Any, Callable, Dict, List, Optional
 from .contracts import multi_agent_contract
 
 
-MULTI_AGENT_VERSION = "8.2.0"
+MULTI_AGENT_VERSION = "8.4.0"
 
 AGENT_ROLES = ("researcher", "planner", "executor", "reviewer", "release")
 CORE_PIPELINE = ("planner", "executor", "reviewer")