ltcai 3.4.1 → 3.5.0

package/README.md

@@ -3,11 +3,10 @@
 
   # Lattice AI
 
-  **Lattice AI v3 — Local-First AI Workspace Platform.**
+  **Local-first AI workspace for your files, chats, knowledge, models, and agents.**
 
-  Work across Personal and Organization workspaces with Knowledge Graph,
-  Vector Index, Hybrid Search, Native Chat, agents, files, models, and
-  Basic / Advanced / Admin modes.
+  Keep your work context on your own machine. Connect documents, conversations,
+  local models, graph memory, and agent workflows in one self-hosted workspace.
 </div>
 
 <div align="center">
@@ -23,7 +22,96 @@
 
 </div>
 
-![Lattice AI — local-first AI workspace](docs/assets/v3.4.0/home.png)
+![Lattice AI — local-first AI workspace home](docs/assets/v3.4.0/home.png)
+
+> **Lattice AI is a self-hosted AI workspace that keeps your files, chats, knowledge, local models, and agents together on your own machine.**
+
+It isn't another chat window. It's a workspace built around your work — local-first
+by default, cloud only when you choose.
+
+## Why install Lattice AI?
+
+Most AI tools only answer questions in a chat window. Lattice AI gives you a
+workspace around the work itself:
+
+- **Keep everything in one place** — files, notes, chats, and decisions live
+  together instead of scattered across tabs and apps.
+- **Turn documents into knowledge** — uploads and connected folders become
+  searchable, linked context you can reuse.
+- **Search the way you think** — fuse keyword, vector, and knowledge-graph
+  signals in a single query.
+- **Stay private and offline-capable** — run local models through MLX, Ollama, or
+  LM Studio; nothing leaves your machine unless you opt in.
+- **Use cloud models only when you choose** — bring an API key for cloud LLMs
+  when you want them, not by default.
+- **Automate with agents you can inspect** — workflows leave behind plans,
+  reviews, retries, and results you can replay.
+
+Lattice AI is not a clone of ChatGPT, Claude, Cursor, Obsidian, or Notion. It
+sits in a different place: a **workspace** that ties local/self-hosted AI, your
+files, project knowledge, hybrid search, local and optional cloud models, agents,
+and workflows together — and runs on your own hardware.
+
+## What can you do with it?
+
+- Build a private AI workspace for a project, scoped to your machine.
+- Chat with your local files, images, and workspace memory.
+- Upload documents — or connect a folder — and turn them into searchable knowledge.
+- Explore how files, decisions, conversations, and entities connect in a
+  Knowledge Graph.
+- Run local models through MLX, Ollama, or LM Studio, and use cloud LLMs only when
+  you want to.
+- Create repeatable agent workflows for research, coding, analysis, and
+  documentation.
+- Separate personal work from organization work.
+- Switch between Basic, Advanced, and Admin modes depending on your role.
+
+## Product Tour
+
+### Start from the workspace home
+
+![Lattice AI workspace home — readiness, model state, and retrieval status](docs/assets/v3.4.0/home.png)
+
+The home view shows workspace readiness, model state, retrieval status, and the
+main entry points — derived from real local state, never placeholder counters.
+
+### Chat with files, images, and workspace context
+
+![Lattice AI chat connected to files, graph context, and vision input](docs/assets/v3.4.0/chat.png)
+
+Chat is wired to your files, graph context, memory, and model routing — including
+vision-capable image input by attach, drag-and-drop, or paste.
+
+### Bring documents into the workspace
+
+![Lattice AI files view — uploaded documents and connected folders](docs/assets/v3.4.0/files.png)
+
+Uploads and connected folders become indexed workspace context, searchable from
+chat and hybrid search.
+
+### Understand knowledge visually
+
+![Lattice AI knowledge graph of files, decisions, conversations, and entities](docs/assets/v3.4.0/knowledge-graph.png)
+
+The Knowledge Graph shows how files, decisions, conversations, and entities
+connect — context that stays useful even when you switch models.
+
+### Run agent workflows
+
+![Lattice AI agent run with roles, logs, review, and retry](docs/assets/v3.4.0/agent-run.png)
+
+Agents turn a goal into an inspectable run — roles, logs, review, and retry — that
+you can read back step by step.
+
+### Extend with hooks and the local runtime
+
+![Lattice AI hooks dispatch with a recent-execution log](docs/assets/v3.4.0/hooks-dispatch.png)
+
+![Lattice AI local agent status, handshake, and folder watching](docs/assets/v3.4.0/local-agent.png)
+
+Advanced users wire lifecycle hooks into runs, tools, workflows, uploads, and
+indexing — and see the on-device local runtime's real status, handshake, and
+folder-watch activity.
 
 ## Install
 
@@ -65,279 +153,116 @@ Then open:
 http://127.0.0.1:4825/app
 ```
 
-Development checkout:
+Working from a development checkout:
 
 ```bash
 npm install
 npm run dev
 ```
 
-Useful validation commands:
-
-```bash
-npm run check:python
-npm run test:unit
-npm run build
-```
-
-## What Is Lattice AI?
-
-Lattice AI v3 is a local-first AI workspace platform for people and teams who
-want their files, models, graph context, retrieval, and agent workflows in one
-place.
-
-- **Primary app shell**: `/app` is the default product experience with Chat,
-  Files, Hybrid Search, Knowledge Graph, Memory, Models, Settings, Advanced
-  agent/workflow tooling, and Admin areas. Classic pages remain compatibility
-  routes only; normal workflows stay in `/app`.
-- **Local-first AI Workspace**: work starts on your machine, with local data and
-  workspace state by default.
-- **AI Pipeline Platform**: plan, execute, review, retry, and replay work across
-  local models, cloud models, tools, files, and generated artifacts.
-- **Knowledge Graph Platform**: documents, images, screenshots, notes,
-  conversations, and decisions become linked entities, relationships, evidence,
-  and reusable context.
-- **Multi-Agent Workflow Platform**: agents hand off structured context, review
-  work, retry with reasons, and keep timelines inspectable.
-- **Personal / Organization Workspace**: move between personal work and team
-  workspaces with role-aware views and Basic / Advanced / Admin modes.
-- **Vector Index and Hybrid Search**: local vector rows are derived from the
-  Knowledge Graph and fused with keyword and graph signals.
-- **Local Model Management**: choose current multimodal local models with source
-  disclosure, hardware-aware recommendations, and cloud fallback options.
-- **Community-first workspaces**: Personal and Organization workspaces ship in
-  the local product; enterprise SSO/SCIM/governance remain future extensions.
-
-## Why Lattice AI?
-
-Most AI tools split your work across a chat window, a model picker, loose files,
-and disconnected automations. Lattice AI keeps those parts together:
-
-- files and conversations become graph context;
-- graph context feeds pipelines and coding actions;
-- model cards disclose country, company, run mode, internet usage, and model
-  identity;
-- personal and organization workspaces keep team workflows separate from local
-  work;
-- multi-agent workflows leave behind replayable plans, reviews, retries, and
-  outcomes.
-
-## v3.4.1 Highlights
-
-Lattice AI v3.4.1 is the **runtime completion** release: it makes the v3.4.0
-runtime systems verifiably complete and corrects the v3.4.0 overclaims an
-implementation audit found. Every item is verified by a **live end-to-end run**
-against a booted server (see `docs/assets/v3.4.1/e2e_runtime_log.txt`).
-
-- **Hooks — full lifecycle.** One shared tool-dispatch path fires `pre_tool`/
-  `post_tool` across the HTTP, agent, and workflow tool paths (v3.4.0 only fired
-  on the HTTP path); workflow hooks fire from both the designer and platform
-  paths; the upload pipeline fires granular upload + index hooks; **all 7
-  built-in hooks have real runners**, and non-executable hooks are flagged
-  `advisory`.
-- **Local Agent — real probes.** `online`/`handshake`/`health`/
-  `filesystem_access` are no longer hardcoded — they are probed (real filesystem
-  write, live graph reachability, derived `mode`, `pid`, handshake latency).
-- **Connect Folder — proven end-to-end.** A real local folder is connected,
-  indexed, and visible in the Files table, retrieval, and hybrid search.
-- **Folder Watch — proven end-to-end + restore.** Creating a file triggers a
-  debounced reindex (`watchdog` installed); the watch is restored after restart.
-
-See [RELEASE_NOTES_v3.4.1.md](RELEASE_NOTES_v3.4.1.md) and the evidence-traced
+## Core Features
+
+- **Local-first workspace** — your data, models, and workspace state live on your
+  machine by default; cloud is opt-in.
+- **Files and connected folders** — upload documents or connect a local folder;
+  Lattice indexes them and watches connected folders for changes.
+- **Chat with workspace context** — conversations are grounded in your files,
+  knowledge graph, and memory, with vision-capable image input.
+- **Knowledge Graph** — files, images, notes, conversations, and decisions become
+  linked entities and relationships you can explore.
+- **Hybrid Search** — keyword, vector, and graph signals are fused into one ranked
+  result set.
+- **Local model support** — run multimodal models locally via MLX, Ollama, or LM
+  Studio, with hardware-aware recommendations and source disclosure.
+- **Optional cloud model routing** — add OpenAI-compatible or other cloud models
+  when you choose; model cards disclose origin, run mode, and internet use.
+- **Multi-agent workflows** — turn goals into runs with roles, handoffs, review,
+  retries, and replayable timelines.
+- **Skills, hooks, tools, and MCP** — extend the workspace with skills, lifecycle
+  hooks, a governed tool registry, and Model Context Protocol servers.
+- **Personal / Organization workspaces** — keep personal work separate from team
+  work with role-aware views.
+- **Basic / Advanced / Admin modes** — show only what each role needs, from core
+  workflows to agent tooling to administration.
+
+## Latest Release
+
+### v3.4.1 — Runtime Completion
+
+- Full hooks lifecycle across HTTP, agent, workflow, upload, and indexing paths.
+- Real Local Agent probes instead of hardcoded readiness.
+- Connect Folder verified end-to-end.
+- Folder Watch verified, including restore after restart.
+
+See [RELEASE_NOTES_v3.4.1.md](RELEASE_NOTES_v3.4.1.md) and
 [FEATURE_STATUS.md](FEATURE_STATUS.md).
 
-## v3.4.0 Highlights
-
-Lattice AI v3.4.0 is the **platform completion** release: it closes the remaining
-non-enterprise functionality gaps the v3.3.0 honesty audit flagged, so the
-local-first workspace is complete and demonstrable end-to-end. Each item below is
-runtime-verified on a live server, not only wired in source.
-
-- **Hooks now execute.** A real dispatch engine (`run_hook` / `run_hooks` /
-  `fire_hook` + `HookContext` / `HookResult`) runs hooks at genuine lifecycle
-  points — agents (pre/post-run), workflows (start/end), tools (pre/post-tool),
-  and the upload pipeline. `pre_*` hooks can gate (block) an action; every
-  dispatch is recorded to a persisted run log surfaced in the Hooks view.
-- **Uploads appear in Files.** Uploaded documents are listed with live ingest →
-  index state (`/knowledge-graph/documents`), completing upload → Files →
-  Knowledge Graph → Hybrid Search → Chat.
-- **Vision (VLM) image input.** The Chat composer accepts images by attach,
-  drag-and-drop, or paste, with a preview and a **Vision Enabled / Disabled**
-  badge driven by the active model's capability.
-- **Run agents from the Agents view.** A Run console (goal + roles → Run / Stop /
-  Status / Queue / Logs) executes the multi-agent pipeline locally; it runs
-  without a model and fires its pre/post-run hooks.
-- **On-device Local Agent + Connect Folder + Folder Watch.** My Computer reports
-  the real local-runtime agent status and handshake; folders can be connected and
-  watched (debounced reindex on change) through the existing on-device endpoints.
-- **Enterprise stays honestly disabled.** SSO, SCIM, DLP, Private VPC, SIEM, and
-  enterprise RBAC remain off with honest "not available in this build" states.
-
-See [RELEASE_NOTES_v3.4.0.md](RELEASE_NOTES_v3.4.0.md),
-[PLATFORM_COMPLETION_REPORT_v3.4.0.md](PLATFORM_COMPLETION_REPORT_v3.4.0.md), and
-the evidence-traced [FEATURE_STATUS.md](FEATURE_STATUS.md).
-
-## v3.3.1 Highlights
-
-Lattice AI v3.3.1 rebuilds the visible `/app` product experience while
-preserving the existing local-first runtime. The app now presents Chat, Files,
-Search, Knowledge, Memory, Models, Settings, Advanced tooling, and Admin
-workflows with clearer navigation and honest live/unavailable states.
-
-- **Visual product rebuild** — compact rail navigation, quieter topbar,
-  command-palette search, retrieval readiness footer, and denser controls.
-- **Truthful Home dashboard** — backend, model, retrieval, memory, source, and
-  trace readiness are derived from real endpoints instead of fabricated counts.
-- **Basic / Advanced / Admin navigation** — Basic focuses on core workspace
-  workflows; Advanced exposes agents, workflows, skills, hooks, and MCP; Admin
-  keeps organization controls separate.
-- **Files and Settings clarity** — manual upload is available immediately,
-  folder watching is explicitly tied to the desktop local agent, and Settings
-  shows backend, agent, model, telemetry, and embedding readiness.
-- **Design system refresh** — cooler neutral light/dark tokens, tighter 8px
-  radius discipline, compact cards/tables/stats/buttons, and regenerated
-  hashed v3 assets.
-
-The v3.2.0 platform remains the feature-complete foundation: multi-agent
-collaboration, Agent Registry, Marketplace templates, Workflow Agents,
-Autonomous Planning, Long-Term Memory, Skills, Hooks, Tool Registry, MCP
-Manager, production embedding profiles, and hash-manifested `/app` assets.
-Release audit: [docs/V3_2_AUDIT.md](docs/V3_2_AUDIT.md).
-
-## Screenshots
-
-All screenshots are the v3.4.0 `/app` shell. Live model output (VLM inference,
-agent-generated text) requires a loaded local model and is not depicted.
-
-### Home
-
-![Home — local-first workspace at a glance](docs/assets/v3.4.0/home.png)
-
-### Chat with Vision (VLM) image input
-
-![Chat — image attach + Vision Enabled badge](docs/assets/v3.4.0/chat.png)
-
-### Files — uploaded documents + Connect Folder
-
-![Files — uploaded documents with index state](docs/assets/v3.4.0/files.png)
-
-### Run agents from the Agents view
-
-![Agent run — goal, roles, and live timeline logs](docs/assets/v3.4.0/agent-run.png)
-
-### Hooks dispatch + run log
-
-![Hooks — per-hook Run and recent executions](docs/assets/v3.4.0/hooks-dispatch.png)
-
-### Local Agent (on-device runtime)
-
-![My Computer — Local Agent status and handshake](docs/assets/v3.4.0/local-agent.png)
-
-### Knowledge Graph
-
-![Knowledge Graph](docs/assets/v3.4.0/knowledge-graph.png)
-
-## Knowledge Graph Flow
+## How it works
 
 ```text
-files / documents / images / screenshots / conversations / decisions
-  -> multimodal understanding
-  -> entity and relationship extraction
-  -> evidence and artifact storage
-  -> Knowledge Graph update
-  -> AI pipeline context
-  -> coding actions / analysis / documents / team workflows
+files / chats / notes / images / decisions
+  -> workspace memory
+  -> knowledge graph
+  -> hybrid search
+  -> chat / agents / workflows
+  -> reusable outputs
 ```
 
-The graph keeps useful workspace context available even when you change models.
-
-## v3 Backend Retrieval
+- Your content stays on your machine and becomes durable workspace memory.
+- Memory is organized into a knowledge graph of entities and relationships.
+- Hybrid search fuses keyword, vector, and graph signals over that context.
+- Chat, agents, and workflows draw on the same grounded context.
+- Outputs — documents, analysis, and decisions — feed back into the workspace.
 
-The v3 backend adds a local-first retrieval stack that combines the Knowledge
-Graph, a SQLite vector index, and hybrid result fusion. It preserves existing
-graph data while adding derived vector rows that can be rebuilt at any time.
+For the deeper design, see [ARCHITECTURE.md](ARCHITECTURE.md) and
+[docs/architecture.md](docs/architecture.md).
 
-Embedding status: production profiles are exposed through
-`GET /api/embeddings/providers`, while `lattice-local-hash-v1` remains a
-deterministic fallback for offline indexing and tests. It is never presented as
-a production semantic embedding model.
-
-Core API contracts:
+## Documentation
 
-- `POST /api/search/hybrid`
-- `GET /api/search/keyword?q=...`
-- `GET /api/search/vector?q=...`
-- `GET /api/graph`
-- `GET /api/graph/node?node_id=...`
-- `GET /api/graph/relationship`
-- `GET /api/index/status`
-- `POST /api/index/rebuild`
+### Product and principles
 
-See [docs/V3_BACKEND_ARCHITECTURE.md](docs/V3_BACKEND_ARCHITECTURE.md) for the
-storage model, search model, migration behavior, and API response shape.
+- [PROJECT_PRINCIPLES.md](PROJECT_PRINCIPLES.md) — product principles
+- [AI_PHILOSOPHY.md](AI_PHILOSOPHY.md) — how AI is used in the workspace
+- [MODEL_POLICY.md](MODEL_POLICY.md) — local model recommendation policy
 
-## Local Model Policy
+### Architecture
 
-Lattice AI recommends current-generation multimodal models for local use and
-keeps local model choices explicit.
+- [ARCHITECTURE.md](ARCHITECTURE.md) — workspace, graph, pipeline, and model overview
+- [docs/architecture.md](docs/architecture.md) — full architecture reference
+- [docs/V3_BACKEND_ARCHITECTURE.md](docs/V3_BACKEND_ARCHITECTURE.md) — backend storage, search, and retrieval
 
-| Family | Default role | Example recommendation |
-| --- | --- | --- |
-| Gemma 4 | Default Google multimodal family | `mlx-community/gemma-4-12b-it-4bit` |
-| Gemma 4 large | Higher-quality local multimodal work | `mlx-community/gemma-4-31b-it-4bit` |
-| Qwen3-VL | Smaller, balanced multimodal options | `mlx-community/Qwen3-VL-4B-Instruct-4bit` |
-| Llama 4 | Meta multimodal option | `mlx-community/Llama-4-Scout-17B-16E-Instruct-4bit` |
+### Knowledge and retrieval
 
-Every recommended model card shows maker country, maker company, run mode,
-internet requirement, and model name. See [MODEL_POLICY.md](MODEL_POLICY.md).
+- [KNOWLEDGE_GRAPH.md](KNOWLEDGE_GRAPH.md) — graph model and behavior
 
-## Architecture
+### Agents and workflows
 
-```text
-Personal / Organization Workspace
-  -> files, chats, screenshots, model choices, workflow events
-  -> Knowledge Graph
-  -> AI Pipeline
-  -> Multi-Agent Workflow
-  -> coding actions, documents, analysis, team handoffs
-```
+- [docs/MULTI_AGENT_RUNTIME.md](docs/MULTI_AGENT_RUNTIME.md) — multi-agent workflow runtime
+- [docs/WORKFLOW_DESIGNER.md](docs/WORKFLOW_DESIGNER.md) — AI pipeline designer
 
-Core areas:
+### Extensions
 
-- FastAPI local workspace app
-- Knowledge Graph storage and graph APIs
-- AI pipeline and workflow designer
-- Multi-agent handoff, review, retry, and replay records
-- Local model management and model recommendation catalog
-- VS Code / Cursor / VSCodium extension surface
-- Personal and organization workspace boundaries
+- [docs/PLUGIN_SDK.md](docs/PLUGIN_SDK.md) — plugin SDK
 
-## Documentation
+### Releases
 
-- [ARCHITECTURE.md](ARCHITECTURE.md) — workspace, graph, pipeline, and model-management overview
-- [docs/architecture.md](docs/architecture.md) — full architecture reference
-- [PROJECT_PRINCIPLES.md](PROJECT_PRINCIPLES.md) — product principles
-- [AI_PHILOSOPHY.md](AI_PHILOSOPHY.md) — how AI is used in the workspace
-- [MODEL_POLICY.md](MODEL_POLICY.md) — local model recommendation policy
-- [KNOWLEDGE_GRAPH.md](KNOWLEDGE_GRAPH.md) — graph model and behavior
-- [docs/MULTI_AGENT_RUNTIME.md](docs/MULTI_AGENT_RUNTIME.md) — multi-agent workflow runtime
-- [docs/WORKFLOW_DESIGNER.md](docs/WORKFLOW_DESIGNER.md) — AI pipeline designer
-- [docs/REALTIME_COLLABORATION.md](docs/REALTIME_COLLABORATION.md) — realtime workspace events
-- [docs/ENTERPRISE.md](docs/ENTERPRISE.md) — organization workspaces and SSO
-- [docs/PLUGIN_SDK.md](docs/PLUGIN_SDK.md) — plugin SDK
-- [RELEASE_NOTES.md](RELEASE_NOTES.md) and [docs/CHANGELOG.md](docs/CHANGELOG.md)
+- [RELEASE_NOTES.md](RELEASE_NOTES.md) — current release notes
+- [RELEASE_NOTES_v3.4.1.md](RELEASE_NOTES_v3.4.1.md)
+- [RELEASE_NOTES_v3.4.0.md](RELEASE_NOTES_v3.4.0.md)
+- [RELEASE_NOTES_v3.3.0.md](RELEASE_NOTES_v3.3.0.md)
+- [CHANGELOG.md](CHANGELOG.md) and [docs/CHANGELOG.md](docs/CHANGELOG.md)
 
-## Release history
+## Release History
 
 | Version | Theme |
 | --- | --- |
-| **3.4.1** | Runtime completion — hooks full lifecycle (shared tool dispatch across HTTP/agent/workflow, all built-ins real), Local Agent real probes (no hardcoded readiness), Connect Folder + Folder Watch proven live end-to-end + restore-on-restart; corrects v3.4.0 overclaims |
-| 3.4.0 | Platform completion — hooks execution engine, uploads visible in Files, VLM image input, agent run trigger, on-device Local Agent / Connect Folder / Folder Watch; Enterprise stays honestly disabled; refreshed v3.4.0 public assets |
-| 3.3.1 | Visual product rebuild — rebuilt `/app` shell, Basic/Advanced/Admin navigation, cooler token palette, compact component system, Home readiness dashboard, Files local-agent truthfulness, Settings runtime status, and v3.3.1 design notes |
-| **3.3.0** | Product quality & honesty release — evidence-based feature audit (`FEATURE_STATUS.md`), single-source version truth, working manual document upload in Files, fixed document-generation streaming, truthful Home retrieval status, documented design system (`STYLE_SYSTEM.md`) |
-| 3.2.0 | Feature-complete platform — multi-agent collaboration, agent registry, marketplace + templates, workflow agents, autonomous planning, long-term memory + manager, skills/hooks/tool registries, MCP manager, all operable from `/app` |
-| 3.1.0 | Mainline platform completion — native `/app` workflows, Classic retired from normal paths, production embedding profiles, AgentRuntime/registries, hashed v3 assets |
-| 3.0.1 | Release-blocker remediation — provider-backed embeddings (Hash/MLX/Ollama/OpenAI/Custom), unified AgentRuntime boundary, every v3 surface connected or clearly unavailable |
+| **3.4.1** | Runtime completion — full hooks lifecycle, real Local Agent probes, Connect Folder and Folder Watch verified end-to-end |
+| 3.4.0 | Platform completion — hooks execution, uploads in Files, vision image input, agent run trigger, on-device Local Agent / Connect Folder / Folder Watch |
+| 3.3.1 | Visual product rebuild — rebuilt `/app` shell, Basic/Advanced/Admin navigation, refreshed design system |
+| **3.3.0** | Product quality & honesty release — evidence-based feature audit, single-source version truth, working document upload, documented design system |
+| 3.2.0 | Feature-complete platform — multi-agent collaboration, agent registry, marketplace + templates, workflow agents, long-term memory, skills/hooks/tool registries, MCP manager |
+| 3.1.0 | Mainline platform completion — native `/app` workflows, production embedding profiles, AgentRuntime/registries, hashed v3 assets |
+| 3.0.1 | Release-blocker remediation — provider-backed embeddings, unified AgentRuntime boundary, every v3 surface connected or clearly unavailable |
 | 3.0.0 | v3 local-first AI workspace platform — `/app`, Native Chat, Knowledge Graph, Vector Index, Hybrid Search, workspace modes |
 | 2.2.7 | Visual system stabilization — cohesive dark/light screens, crisp chat composer, dark graph canvas, Workspace OS polish |
 | 2.2.6 | Token-native CSS foundation |

package/docs/RUNTIME_HOOK_COVERAGE_v3.5.0.md

@@ -0,0 +1,56 @@
+# Runtime Hook Coverage — v3.5.0
+
+Every place Lattice AI executes a real tool or agent action, and whether it runs
+through the unified lifecycle. The single tool path is
+`dispatch_tool(hooks, name, args, run_fn)` in `latticeai/core/hooks.py`
+(`pre_tool → execute → post_tool`); the HTTP helper `_tool_response`
+(`latticeai/api/tools.py`) wraps it; uploads use the parallel
+`pre_upload/post_upload/pre_index/post_index` lifecycle
+(`latticeai/services/upload_service.py`); agent runs use `pre_run/post_run`.
+
+**Method.** Routers/services were enumerated by a 6-way parallel audit and then
+each genuine execution path was verified by reading the call site. A path is a
+*bypass* only if a real tool/agent action skips its lifecycle. Read-only metadata
+endpoints (status, list-permissions, config) execute no tool and are not bypasses.
+
+**Result.** All discovered tool/agent execution paths are covered. The four
+remaining "uncovered" rows are deliberate, documented design decisions (service
+maintenance ops + an action already inside the upload lifecycle), not gaps.
+
+## Tool / agent execution paths
+
+| Entrypoint | Execution | Lifecycle path | pre fired | post fired | Test |
+|---|---|---|---|---|---|
+| `POST /tools/list_dir`, `workspace_tree`, `write_file`, `search_files`, `todo_*`, `inspect_html`, `preview_url`, `create_*`, `read_document`, `knowledge_*`, `obsidian_*`, `network_status` | tool fn | `_tool_response`→`dispatch_tool` | yes (`pre_tool`) | yes (`post_tool`) | `test_hooks_dispatch`, `test_runtime_coverage` |
+| `POST /tools/read_file` | `read_file` (kwargs) | `_tool_response` (kwargs-aware) ✅v3.5.0 | yes | yes | `test_runtime_coverage` |
+| `POST /tools/edit_file` | `edit_file` (kwargs) | `_tool_response` ✅v3.5.0 | yes | yes | `test_runtime_coverage` |
+| `POST /tools/grep` | `grep` (kwargs) | `_tool_response` ✅v3.5.0 | yes | yes | `test_runtime_coverage` |
+| `POST /tools/clear_history` | `clear_history` | `_dispatch`→`dispatch_tool` ✅v3.5.0 | yes | yes | `test_runtime_coverage` |
+| `POST /tools/git_*`, `run_command`, `build_project`, `deploy_project` | tool fn | `_tool_response` | yes | yes | `test_route_compatibility` |
+| `POST /local/*` (list/read/write) | `local_*` | `tool_response` | yes | yes | `test_route_compatibility` |
+| `GET/POST /cu/*` (open_app/url/click/type/key/scroll/move/drag) | `computer_*` | `tool_response` | yes | yes | `test_runtime_coverage` |
+| `GET /cu/status`, `/cu/screenshot` | `computer_status/screenshot` | `_dispatch` ✅v3.5.0 | yes | yes | `test_runtime_coverage` |
+| `POST /cu/agent` (agent loop) | `execute_tool(name,args)` per step + Chrome shortcut | `_dispatch`→`dispatch_tool` ✅v3.5.0 | yes | yes | `test_runtime_coverage` |
+| `POST /agent/eval` | `execute_tool` per eval case | `dispatch_tool` ✅v3.5.0 | yes | yes | (covered via dispatch_tool) |
+| Single-agent runtime tool calls | `execute_tool` via `AgentDeps` | `core/agent.py`→`dispatch_tool` | yes | yes | `test_hooks_dispatch` |
+| Agent run (start→finish) | orchestrator run | `agent_runtime` `pre_run`/`post_run` | yes (`pre_run`) | yes (`post_run`) | `test_hooks_dispatch` |
+| Workflow tool node | `dispatch_tool` | `platform_runtime` | yes | yes | `test_hooks_dispatch` |
+| Workflow run (start→end) | engine run | `WorkflowEngine` `pre_workflow`/`post_workflow` | yes | yes | `test_hooks_dispatch` |
+| `POST /upload/document` | `process_uploaded_document` | upload lifecycle | `pre_upload` | `post_upload` | existing upload tests |
+| Document indexing (upload + folder watch) | embed/graph build | `pre_index`/`post_index` | yes | yes | existing |
+
+## Intentionally outside the tool lifecycle (documented, not gaps)
+
+| Entrypoint | Why not `pre_tool`/`post_tool` |
+|---|---|
+| `read_document` inside `process_uploaded_document` (`upload_service.py`) | Already inside the upload lifecycle (`pre_upload`→`post_upload`); wrapping it again would double-dispatch the same user action. |
+| `POST /api/memory/{prune,compact,rebuild,clear}` | Knowledge/memory **service** maintenance operations, not registry tools; they have their own audit events. Not part of the agent tool vocabulary. |
+| `clear_history` inside `core/agent.py` executor | Runs inside an agent run already bracketed by `pre_run`/`post_run`; not re-wrapped to avoid nested dispatch. |
+| Read-only status/config endpoints (`/tools/permissions`, `/obsidian/status`, model/catalog reads) | Execute no tool — nothing to gate. |
+
+## Summary
+
+- Genuine tool/agent execution paths discovered: **all enumerated routers + services**.
+- Bypasses found and closed in v3.5.0: **read_file, edit_file, grep, clear_history, computer-use agent loop (+ /cu/status, /cu/screenshot), skill-eval**.
+- Bypasses remaining: **none** (the four rows above are deliberate, documented design decisions).
+- Coverage of discovered tool/agent execution paths: **100%**.

package/latticeai/__init__.py

@@ -1,3 +1,3 @@
 """Lattice AI - modular server package."""
 
-__version__ = "3.4.1"
+__version__ = "3.5.0"

package/latticeai/api/auth.py

@@ -1,17 +1,21 @@
 """Authentication API router: register, login, logout, SSO, profile."""
 
-import base64
-import json
 import logging
 import secrets
 import time
-from typing import Any, Callable, Dict, Optional
+from typing import Any, Awaitable, Callable, Dict, Optional, Tuple
 from urllib.parse import urlencode
 
 from fastapi import APIRouter, HTTPException, Request
 from fastapi.responses import JSONResponse, RedirectResponse
 from pydantic import BaseModel
 
+from latticeai.core.oidc import (
+    OIDCValidationError,
+    fetch_jwks as _default_fetch_jwks,
+    verify_id_token as _default_verify_id_token,
+)
+
 
 class UserRegister(BaseModel):
     email: str
@@ -35,7 +39,9 @@ class UpdateProfileRequest(BaseModel):
     nickname: Optional[str] = None
 
 
-_sso_states: Dict[str, float] = {}
+# state → (issued_at, nonce). The nonce binds the eventual ID token to *this*
+# login attempt (replay / token-injection defence); the timestamp expires it.
+_sso_states: Dict[str, Tuple[float, str]] = {}
 
 
 def create_auth_router(
@@ -58,6 +64,8 @@ def create_auth_router(
     open_registration: bool,
     session_ttl: int,
     require_auth: bool = True,
+    verify_id_token: Callable[..., Dict] = _default_verify_id_token,
+    fetch_jwks: Callable[[str], Awaitable[Dict]] = _default_fetch_jwks,
 ) -> APIRouter:
     router = APIRouter()
 
@@ -114,13 +122,15 @@ def create_auth_router(
         if not settings.get("enabled") or not discovery:
             raise HTTPException(status_code=503, detail="SSO가 설정되지 않았습니다.")
         state = secrets.token_urlsafe(16)
-        _sso_states[state] = time.time()
+        nonce = secrets.token_urlsafe(16)
+        _sso_states[state] = (time.time(), nonce)
         params = urlencode({
             "client_id": settings["client_id"],
             "response_type": "code",
             "redirect_uri": settings["redirect_uri"],
             "scope": settings.get("scopes") or "openid email profile",
             "state": state,
+            "nonce": nonce,
         })
         return RedirectResponse(f"{discovery['authorization_endpoint']}?{params}")
 
@@ -128,9 +138,10 @@ def create_auth_router(
     async def sso_callback(code: str = "", state: str = "", error: str = ""):
         if error:
             return RedirectResponse(f"/?sso_error={error}")
-        ts = _sso_states.pop(state, None)
-        if ts is None or time.time() - ts > 300:
+        entry = _sso_states.pop(state, None)
+        if entry is None or time.time() - entry[0] > 300:
             raise HTTPException(status_code=400, detail="유효하지 않은 SSO 상태입니다.")
+        _, nonce = entry
         settings = get_sso_settings()
         discovery = await get_sso_discovery()
         if not settings.get("enabled") or not discovery:
@@ -148,8 +159,25 @@ def create_auth_router(
         id_token = tokens.get("id_token")
         if not id_token:
             raise HTTPException(status_code=400, detail="ID 토큰을 받지 못했습니다.")
-        padded = id_token.split(".")[1] + "=="
-        payload = json.loads(base64.urlsafe_b64decode(padded))
+        # Never trust a decoded JWT payload: verify signature (against the
+        # provider JWKS), issuer, audience, expiry and the login nonce before
+        # using any claim. Any failure is fail-closed (401).
+        issuer = discovery.get("issuer") or ""
+        try:
+            jwks = await fetch_jwks(discovery.get("jwks_uri", ""))
+            payload = verify_id_token(
+                id_token,
+                jwks=jwks,
+                issuer=issuer,
+                audience=settings["client_id"],
+                nonce=nonce,
+            )
+        except OIDCValidationError as exc:
+            logging.warning("SSO ID token rejected: %s", exc)
+            raise HTTPException(status_code=401, detail="SSO 토큰 검증에 실패했습니다.")
+        except Exception as exc:  # discovery/JWKS fetch failure → fail closed
+            logging.warning("SSO token validation error: %s", exc)
+            raise HTTPException(status_code=502, detail="SSO 공급자 검증에 실패했습니다.")
         email = payload.get("email") or payload.get("preferred_username") or payload.get("upn") or ""
         if not email:
             raise HTTPException(status_code=400, detail="이메일을 확인할 수 없습니다.")