kenaz 0.0.0-stage → 0.3.2

package/core/dev/archive/ansuz/designs/mcp_kuzudb_lock_architecture.md

@@ -0,0 +1,312 @@
+# MCP KuzuDB Lock Conflict Architecture
+
+Produced for TASK_1358. This is design only: No code changes to MCP handlers, and execution is out of scope.
+
+## 1. Inventory And Classification
+
+### 1.1 Classification Legend
+
+| Classification | Meaning | Lock risk |
+|---|---|---|
+| HTTP delegate | Handler reuses an HTTP route/direct route entry point and does not open the project graph in the MCP handler. Evidence term: `get_sigils_direct`; future target is `reqwest`/`/api/*` or equivalent Dashboard HTTP delegate. | Works while Dashboard owns the KuzuDB process lock. |
+| Direct-open project KuzuDB | Handler or its called feature opens `.synapse/db/graph` via `with_connection`, `with_read_connection`, `status::impact_analysis`, `episode::*`, `imagination::imagine`, `attention::*`, or similar graph entry points. | Fails with `LOCK_CONFLICT` when executed from a separate MCP subprocess while Dashboard is running. |
+| Direct-open meta KuzuDB | Handler opens the Cortex meta graph KuzuDB under `~/.kenaz/cortex/meta_graph`. Evidence term: `ensure_meta_graph_initialized` plus `with_read_connection` / `with_connection`. | Same architectural risk class, different graph path. |
+| Local / no KuzuDB | Handler uses file I/O, process dispatch, SQLite `MemoryDb`, `GlobalMemoryDb`, search index, or in-memory services without KuzuDB evidence in the handler block. | Not part of the `.synapse/db/graph` lock conflict unless it calls a direct-open handler indirectly. |
+
+No `reqwest::Client` or `ClientBuilder` was found under `dashboard/src-tauri/src/infrastructure/http_server/routes/mcp_tools/`; current delegation is in-process (`synapse_sigils` calls `routes::synapse::get_sigils_direct`). The future migration should make these tools HTTP delegates when they are run outside the Dashboard process.
+
+### 1.2 Handler Inventory
+
+| Tool name | Handler fn | File:line | Classification | Operation | Evidence |
+|---|---|---:|---|---|---|
+| `synapse_thought_push` | `tool_synapse_thought_push` | `thought_stack.rs:35` | Local / no KuzuDB | JSON file write | No `with_connection`, `with_read_connection`, `kuzu::`, or `reqwest` match in handler block. |
+| `synapse_thought_pop` | `tool_synapse_thought_pop` | `thought_stack.rs:96` | Local / no KuzuDB | JSON file write | No KuzuDB evidence in handler block. |
+| `synapse_thought_stack_list` | `tool_synapse_thought_stack_list` | `thought_stack.rs:133` | Local / no KuzuDB | JSON file read | No KuzuDB evidence in handler block. |
+| `synapse_status` | `tool_synapse_status` | `synapse.rs:378` | Local / no project KuzuDB open in handler | SQLite/search-index status | `SearchIndex::open_readonly` at `synapse.rs:404`, `MemoryDb` counts at `synapse.rs:428-431`; no handler `with_connection`. |
+| `synapse_cypher` | `tool_synapse_cypher` | `synapse.rs:471` | Direct-open project KuzuDB | Read-only Cypher | `with_read_connection(&db_dir` at `synapse.rs:514`, `conn.query(&q)` at `synapse.rs:518`, `kuzu_value_to_json` at `synapse.rs:532`. |
+| `synapse_index` | `tool_synapse_index` | `synapse.rs:576` | Local / no KuzuDB handler open | Indexing job via Synapse indexer | Background reindex at `synapse.rs:685-697`; no handler `with_connection`. |
+| `synapse_search` | `tool_synapse_search` | `synapse.rs:636` | Local / no KuzuDB handler open | SQLite FTS/search index read | `SearchIndex::open_readonly` at `synapse.rs:727`; no handler `with_connection`. |
+| `synapse_context` | `tool_synapse_context` | `synapse.rs:1018` | Direct-open project KuzuDB | Graph relationship read | `with_connection(db_dir` at `synapse.rs:1333`, `conn.query` at `synapse.rs:1343` and `synapse.rs:1388`, `kuzu::Value` rows at `synapse.rs:1346-1411`. |
+| `synapse_impact` | `tool_synapse_impact` | `synapse.rs:1431` | Direct-open project KuzuDB | Read plus cache writes | Calls `status::impact_analysis` at `synapse.rs:1464`; callee opens graph with `with_connection(&db_dir` at `status.rs:833` and cache writes with `SearchIndex::open` at `status.rs:848`. |
+| `synapse_detect_changes` | `tool_synapse_detect_changes` | `synapse.rs:1634` | Local / no KuzuDB handler open | Git diff plus SQLite change data | Handler block has SQLite evidence, no `with_connection` match. |
+| `synapse_inscribe` | `tool_synapse_inscribe` | `synapse.rs:1812` | Local / no project KuzuDB handler open | SQLite rune write plus search index update | `MemoryDb::open` at `synapse.rs:1918`; no handler `with_connection`. |
+| `synapse_backfill_trigger_embeddings` | `tool_synapse_backfill_trigger_embeddings` | `synapse.rs:2125` | Local / no KuzuDB | SQLite/search index write | `MemoryDb::open` at `synapse.rs:2135`; no KuzuDB evidence. |
+| `synapse_forge` | `tool_synapse_forge` | `synapse.rs:2153` | Direct-open project KuzuDB | Mixed read/write concept tagging | `with_read_connection` at `synapse.rs:2293`; graph member/tag path uses `with_connection` around `synapse.rs:2326`; SQLite sigil writes via `MemoryDb`. |
+| `synapse_declare` | `tool_synapse_declare` | `synapse.rs:2466` | Direct-open project KuzuDB | Graph write | `with_connection(&db_dir` at `synapse.rs:2547`; `conn.query` creates phantom symbols/edges at `synapse.rs:2605`, `2627`, `2642`. |
+| `synapse_proposed_connections` | `tool_synapse_proposed_connections` | `synapse.rs:2735` | Local / no KuzuDB | SQLite proposal read | `MemoryDb::open` at `synapse.rs:2764`; no graph open. |
+| `synapse_verify` | `tool_synapse_verify` | `synapse.rs:2817` | Direct-open project KuzuDB | Mixed SQLite update plus graph write | Proposal confirmation calls `with_connection(&db_dir_sb` at `synapse.rs:2904`; SQLite update at `synapse.rs:2853`. |
+| `synapse_recall` | `tool_synapse_recall` | `synapse.rs:2982` | Direct-open project KuzuDB | SQLite recall plus graph-context read | Graph enrichment uses `with_read_connection(&db_dir` at `synapse.rs:3162`, then `kuzu::Value` parsing at `synapse.rs:3169-3192`. |
+| `synapse_sigils` | `tool_synapse_sigils` | `synapse.rs:3402` | HTTP delegate / in-process route delegate | Route-level sigil read plus SQLite staleness | Builds `routes::synapse::SigilsQuery` at `synapse.rs:3416` and calls `get_sigils_direct` at `synapse.rs:3424`; staleness uses `MemoryDb::open` at `synapse.rs:3446`. |
+| `synapse_trace_route` | `tool_synapse_trace_route` | `synapse.rs:3474` | Direct-open project KuzuDB | Read-only route traversal | `with_read_connection(&db_dir` at `synapse.rs:3523`; `conn.query` route/chain reads at `synapse.rs:3527`, `3585`, `3617`. |
+| `synapse_map` | `tool_synapse_map` | `synapse.rs:3755` | Direct-open project KuzuDB | Read-only graph overview | `with_read_connection(&db_dir` at `synapse.rs:3783`; helpers consume `&kuzu::Connection` at `synapse.rs:3883`, `4044`. |
+| `synapse_pulse` | `tool_synapse_pulse` | `synapse.rs:4082` | Direct-open project KuzuDB | Read plus cache writes | Callee uses `with_connection` at `status.rs:2244` and `SearchIndex::open` cache writes at `status.rs:2234`, `2525`. |
+| `synapse_imagine` | `tool_synapse_imagine` | `synapse.rs:4344` | Direct-open project KuzuDB | Read-only forecast | Calls `imagination::imagine` at `synapse.rs:4367`; callee uses `scanner::get_db_dir` at `imagination.rs:71` and `with_read_connection` at `imagination.rs:396`. |
+| `synapse_rune_conflicts` | `tool_synapse_rune_conflicts` | `synapse.rs:4382` | Local / no KuzuDB | SQLite conflict scan | `MemoryDb::open` at `synapse.rs:4405`; no graph open. |
+| `synapse_pain_paths` | `tool_synapse_pain_paths` | `synapse.rs:4480` | Direct-open project KuzuDB | Read-only graph traversal | `with_read_connection(&db_dir` at `synapse.rs:4579`; `conn.query` at `synapse.rs:4588`, `4626`, `4651`. |
+| `synapse_orphans` | `tool_synapse_orphans` | `synapse.rs:4895` | Direct-open project KuzuDB | Read-only graph query plus file/git age checks | `orphans_impl` calls `with_read_connection(&db_dir` at `synapse.rs:5015`; runs `orphan_cypher_query` at `synapse.rs:5019`; uses `std::process::Command::new("git")` at `synapse.rs:5248`. Known broken tool. |
+| `synapse_health` | `tool_synapse_health` | `synapse.rs:5270` | Direct-open project KuzuDB | Read-only structural metrics plus SQLite snapshot | `with_read_connection(&db_dir` at `synapse.rs:5343`; `query_single_i64` / `count_pain_paths` consume `&kuzu::Connection` at `synapse.rs:5591`, `5605`. |
+| `synapse_debug_pool` | `tool_synapse_debug_pool` | `synapse.rs:5733` | Local / no KuzuDB | Pool diagnostic | No handler `with_connection`, `with_read_connection`, or `kuzu::` match. |
+| `synapse_knowledge_gaps` | `tool_synapse_knowledge_gaps` | `synapse.rs:5756` | Direct-open project KuzuDB | Read-only graph plus SQLite rune counts | Calls `status::knowledge_gap_analysis` at `synapse.rs:5774`; callee opens graph with `with_connection(&db_dir` at `status.rs:2737` and `status.rs:2784`. |
+| `synapse_audit` | `tool_synapse_audit` | `synapse.rs:5813` | Direct-open project KuzuDB | Rule-driven graph reads | Handler delegates to audit engine at `synapse.rs:5826-5829`; implementation is described as "KuzuDB operations are synchronous". |
+| `synapse_clustering_log` | `tool_synapse_clustering_log` | `synapse.rs:5883` | Local / no project graph required | SQLite clustering log | Handler opens `MemoryDb` at `synapse.rs:5907`; no direct project graph query in the handler path. |
+| `synapse_scan_stale_runes` | `tool_synapse_scan_stale_runes` | `synapse.rs:6628` | Direct-open project KuzuDB | Mixed SQLite review flags plus graph existence checks | `scan_stale_runes_impl` performs ghost check with `with_connection(&db_dir` at `synapse.rs:6077`; handler calls it at `synapse.rs:6636`. |
+| `synapse_maintain` | `tool_synapse_maintain` | `synapse.rs:6660` | Indirect direct-open project KuzuDB | Aggregates direct-open handlers | Handler calls `synapse_maintain` at `synapse.rs:6672`; coordinator calls `orphans`, `knowledge_gap_analysis`, pain paths, audit, etc. around `synapse.rs:6239-6594`. |
+| `synapse_associate` | `tool_synapse_associate` | `synapse.rs:6696` | Direct-open project KuzuDB | Associative graph read plus memory recall | Handler calls Synapse association logic at `synapse.rs:6740`; association traverses graph via Synapse context APIs. |
+| `synapse_apply_usage_boosts` | `tool_synapse_apply_usage_boosts` | `synapse.rs:6934` | Local / no KuzuDB | SQLite confidence updates | `MemoryDb::open` at `synapse.rs:6943`; no graph open. |
+| `synapse_preamble` | `tool_synapse_preamble` | `synapse.rs:6986` | Local / no KuzuDB handler open | Preamble generation | No handler `with_connection` or `kuzu::` match. |
+| `synapse_attention` | `tool_synapse_attention` | `synapse.rs:7040` | Direct-open project KuzuDB | Read-only attention ranking | Handler calls attention logic at `synapse.rs:7055`; callee uses `scanner::get_db_dir` and `with_read_connection` at `attention.rs:396`, `478`, `511`, `555`. |
+| `thalamus_status` | `tool_thalamus_status` | `synapse.rs:7285` | Local / no KuzuDB | In-memory SNN state | No graph open in handler block. |
+| `thalamus_history` | `tool_thalamus_history` | `synapse.rs:7364` | Local / no KuzuDB | In-memory/history read | No graph open in handler block. |
+| `thalamus_stimulate` | `tool_thalamus_stimulate` | `synapse.rs:7422` | Local / no KuzuDB | In-memory SNN write/message enqueue | No graph open in handler block. |
+| `spike_bus_send` | `tool_spike_bus_send` | `synapse.rs:7511` | Local / no KuzuDB | Spike bus write | No graph open in handler block. |
+| `spike_bus_poll` | `tool_spike_bus_poll` | `synapse.rs:7553` | Local / no KuzuDB | Spike bus read | No graph open in handler block. |
+| `thalamus_context` | `tool_thalamus_context` | `synapse.rs:7607` | Direct-open project KuzuDB | Read-only community lookup | `with_read_connection(&db_dir` at `synapse.rs:7638` maps hot neurons to communities. |
+| `muninn_sense` | `tool_muninn_sense` | `synapse.rs:7709` | Local / no KuzuDB | Session watcher read | No graph open in handler block. |
+| `synapse_efe` | `tool_synapse_efe` | `synapse.rs:7790` | Direct-open project KuzuDB | Read-only EFE ranking | Handler calls `efe::compute_efe` at `synapse.rs:7814`; EFE uses Synapse graph health/attention inputs. |
+| `synapse_efe_feedback` | `tool_synapse_efe_feedback` | `synapse.rs:7855` | Local / no KuzuDB handler open | EFE weight update | Handler calls `efe::apply_efe_feedback` at `synapse.rs:7894`; no handler graph open. |
+| `synapse_think` | `tool_synapse_think` | `synapse.rs:8198` | Direct-open project KuzuDB | Mixed router: search, episode, context, impact | Opens search index at `synapse.rs:8392`, calls `episode_recall` at `synapse.rs:8346`, and impact/context branches around `synapse.rs:8471`. |
+| `synapse_link_cognitive` | `tool_synapse_link_cognitive` | `synapse.rs:8584` | Direct-open project KuzuDB | Graph write/upsert | `with_connection(&db_dir` at `synapse.rs:8636`; `conn.query` update/create at `synapse.rs:8717`, `8737`. |
+| `reflex_query` | `tool_reflex_query` | `synapse.rs:8768` | Direct-open project KuzuDB | Reflex graph update/read | Handler initializes reflex store at `synapse.rs:8806`; handler span has `with_connection` / `kuzu::` evidence in grep output. |
+| `cortex_recall` | `tool_cortex_recall` | `cortex.rs:117` | Local / no KuzuDB | Global SQLite FTS recall | `GlobalMemoryDb::open` in `cortex.rs:143`; no KuzuDB graph open. This explains why live `cortex_recall` worked. |
+| `cortex_status` | `tool_cortex_status` | `cortex.rs:229` | Local / no KuzuDB | Registry/global memory status | `GlobalMemoryDb::open` at `cortex.rs:236`; no graph open. |
+| `cortex_sync` | `tool_cortex_sync` | `cortex.rs:287` | Direct-open meta KuzuDB | Meta graph sync/write | Meta graph sync starts at `cortex.rs:318-345`; `ensure_meta_graph_initialized` requires connection-pool open for meta graph. |
+| `cortex_search` | `tool_cortex_search` | `cortex.rs:385` | Local / no project KuzuDB | Cross-project search index | No project `with_connection` in handler block. |
+| `cortex_relate` | `tool_cortex_relate` | `cortex.rs:600` | Direct-open meta KuzuDB | Read-only concept traversal | `ensure_meta_graph_initialized` at `cortex.rs:608`; `with_read_connection(&db_path` at `cortex.rs:609`; prepared queries at `cortex.rs:614-728`. |
+| `cortex_cypher` | `tool_cortex_cypher` | `cortex.rs:792` | Direct-open meta KuzuDB | Read-only Cypher | `with_read_connection(&db_path` at `cortex.rs:822`; `conn.query(&q)` at `cortex.rs:826`; `meta_kuzu_value_to_json` at `cortex.rs:837`. |
+| `cortex_overview` | `tool_cortex_overview` | `cortex.rs:880` | Direct-open meta KuzuDB | Read-only counts/top concepts | `ensure_meta_graph_initialized` at `cortex.rs:885`; `with_read_connection(&db_path` at `cortex.rs:893`; `conn.query(top_q)` at `cortex.rs:906`. |
+| `alaya_recall` | `tool_alaya_recall` | `cortex.rs:1069` | Local / no KuzuDB | Global SQLite recall | `GlobalMemoryDb::open` at `cortex.rs:1084`; no graph open. |
+| `hippocampus_episode_start` | `tool_hippocampus_episode_start` | `hippocampus.rs:21` | Direct-open project KuzuDB | Episode graph write | Handler calls `episode::episode_start`; callee opens graph with `with_connection` at `features/hippocampus/episode.rs:76`. |
+| `hippocampus_episode_append` | `tool_hippocampus_episode_append` | `hippocampus.rs:59` | Direct-open project KuzuDB | Episode entry graph write | Handler calls episode append; callee uses `with_connection` at `features/hippocampus/episode.rs:175`. |
+| `hippocampus_episode_recall` | `tool_hippocampus_episode_recall` | `hippocampus.rs:103` | Direct-open project KuzuDB | Graph/SQLite recall plus recall-log write | Handler calls `episode::episode_recall` at `hippocampus.rs:120`; callee uses `with_connection` at `features/hippocampus/episode.rs:309`, `550`, `604`, `709`, `740`. Known broken tool. |
+| `hippocampus_transcript_recall` | `tool_hippocampus_transcript_recall` | `hippocampus.rs:227` | Local / no KuzuDB | Transcript SQLite/FTS recall | No handler graph open. |
+| `hippocampus_episode_close` | `tool_hippocampus_episode_close` | `hippocampus.rs:353` | Direct-open project KuzuDB | Episode close plus optional graph learning writes | `episodic_graph_learning` is invoked at `hippocampus.rs:393`; it uses `with_connection` at `hippocampus.rs:892` and writes `DATA_FLOWS`/confidence updates at `hippocampus.rs:934-996`. |
+| `hippocampus_episode_link` | `tool_hippocampus_episode_link` | `hippocampus.rs:409` | Direct-open project KuzuDB | Episode graph relationship write | Handler calls episode link; callee uses `with_connection` at `features/hippocampus/episode.rs:245`, `294`. |
+| `hippocampus_consolidate` | `tool_hippocampus_consolidate` | `hippocampus.rs:442` | Direct-open project KuzuDB | Backfill/read touched symbols plus SQLite consolidation | `backfill_episodes_to_sqlite` at `hippocampus.rs:453`; touched symbol fetch uses `with_connection` at `hippocampus.rs:483`. |
+| `hippocampus_consolidation_scores` | `tool_hippocampus_consolidation_scores` | `hippocampus.rs:528` | Direct-open project KuzuDB | Backfill plus SQLite scoring | Backfill comment at `hippocampus.rs:536`; callee has `with_connection` evidence in `features/hippocampus/episode.rs:516`. |
+| `hippocampus_detect_patterns` | `tool_hippocampus_detect_patterns` | `hippocampus.rs:583` | Direct-open project KuzuDB | Read touched symbols plus SQLite grouping | `with_connection(&synapse_db_dir` at `hippocampus.rs:625`; `conn.query` at `hippocampus.rs:633`. |
+| `hippocampus_schedule_review` | `tool_hippocampus_schedule_review` | `hippocampus.rs:694` | Local / no KuzuDB | SQLite review schedule write | `MemoryDb::open` at `hippocampus.rs:703`; no graph open. |
+| `hippocampus_due_episodes` | `tool_hippocampus_due_episodes` | `hippocampus.rs:758` | Local / no KuzuDB | SQLite due-episode query | `MemoryDb::open` at `hippocampus.rs:767`; no graph open. |
+| `hippocampus_transcript_ingest` | `tool_hippocampus_transcript_ingest` | `hippocampus.rs:806` | Direct-open project KuzuDB | Transcript ingest plus graph/heat context | Handler span includes graph learning support; `with_connection` appears at `hippocampus.rs:892` and `934`. |
+| `hippocampus_episodic_edge_proposals` | `tool_hippocampus_episodic_edge_proposals` | `hippocampus.rs:1019` | Local / no KuzuDB | SQLite proposal read | `MemoryDb::open` at `hippocampus.rs:1031`; no graph open. |
+| `kenaz_ping` | `tool_ping` | `kenaz.rs:190` | Local / no KuzuDB | Static health response | No graph open. |
+| `kenaz_project_list` | `tool_project_list` | `kenaz.rs:206` | Local / no KuzuDB | Project registry read | No graph open. |
+| `kenaz_project_current` | `tool_project_current` | `kenaz.rs:228` | Local / no KuzuDB | Current project state | No graph open. |
+| `kenaz_project_switch` | `tool_project_switch` | `kenaz.rs:240` | Local / no KuzuDB | Session project switch | No graph open. |
+| `kenaz_task_list` | `tool_task_list` | `kenaz.rs:298` | Local / no KuzuDB | Task YAML/API read | No graph open. |
+| `kenaz_task_get` | `tool_task_get` | `kenaz.rs:329` | Local / no KuzuDB | Task YAML/API read | No graph open. |
+| `kenaz_task_create` | `tool_task_create` | `kenaz.rs:344` | Local / no KuzuDB | Task write | No graph open. |
+| `kenaz_task_update` | `tool_task_update` | `kenaz.rs:395` | Local / no KuzuDB | Task status write | No graph open. |
+| `kenaz_task_delete` | `tool_task_delete` | `kenaz.rs:447` | Local / no KuzuDB | Task delete | No graph open. |
+| `kenaz_dispatch` | `tool_dispatch` | `kenaz.rs:500` | Local / no KuzuDB | Agent subprocess dispatch | No graph open; `Command::spawn` around `kenaz.rs:630`. |
+| `kenaz_dispatch_status` | `tool_dispatch_status` | `kenaz.rs:664` | Local / no KuzuDB | Dispatch registry/log read | No graph open. |
+| `kenaz_specialist_dispatch` | `tool_specialist_dispatch` | `kenaz.rs:750` | Local / no KuzuDB | Specialist subprocess dispatch | No graph open; `Command::spawn` around `kenaz.rs:887`. |
+| `kenaz_project_status` | `tool_project_status` | `kenaz.rs:917` | Local / no KuzuDB | Project/task/dispatch status | No graph open. |
+| `kenaz_agent_list` | `tool_agent_list` | `kenaz.rs:973` | Local / no KuzuDB | Active dispatch list | No graph open. |
+| `kenaz_specialist_list` | `tool_specialist_list` | `kenaz.rs:1018` | Local / no KuzuDB | Specialist file scan | No graph open. |
+| `kenaz_plugin_specialist_info` | `tool_plugin_specialist_info` | `kenaz.rs:1076` | Local / no KuzuDB | Plugin metadata read | No graph open. |
+| `kenaz_specialist_prompt` | `tool_specialist_prompt` | `kenaz.rs:1112` | Local / no KuzuDB | Prompt assembly/read | No graph open. |
+| `prefrontal_propose` | `tool_prefrontal_propose` | `prefrontal.rs:68` | Local / no KuzuDB | SQLite proposal write | Prefrontal operations only; no graph open. |
+| `prefrontal_proposals` | `tool_prefrontal_proposals` | `prefrontal.rs:149` | Local / no KuzuDB | SQLite proposal read | No graph open. |
+| `prefrontal_quota` | `tool_prefrontal_quota` | `prefrontal.rs:175` | Local / no KuzuDB | SQLite quota read | No graph open. |
+| `prefrontal_reflect` | `tool_prefrontal_reflect` | `prefrontal.rs:200` | Local / no KuzuDB | SQLite proposal read | No graph open. |
+
+### 1.3 Direct-Open Operation Summary
+
+Lower-risk read-only migration candidates:
+
+- `synapse_cypher`, `synapse_trace_route`, `synapse_map`, `synapse_pain_paths`, `synapse_orphans`, `synapse_health`, `thalamus_context`, `synapse_attention`, `synapse_imagine`, `cortex_relate`, `cortex_cypher`, and `cortex_overview`.
+- These primarily run `MATCH`/read queries through `with_read_connection`; they can become thin HTTP delegates without defining new write semantics.
+
+Higher-risk mixed/write migration candidates:
+
+- `synapse_forge`, `synapse_declare`, `synapse_verify`, `synapse_scan_stale_runes`, `synapse_link_cognitive`, `reflex_query`, `hippocampus_episode_start`, `hippocampus_episode_append`, `hippocampus_episode_close`, `hippocampus_episode_link`, `hippocampus_consolidate`, `hippocampus_detect_patterns`, and `hippocampus_transcript_ingest`.
+- These create symbols, edges, episode nodes, DATA_FLOWS edges, review flags, or proposal confirmations; they need idempotency and response-shape checks before delegation.
+
+Indirect aggregators:
+
+- `synapse_maintain`, `synapse_think`, `synapse_pulse`, `synapse_impact`, and `hippocampus_episode_recall` are important because they call graph-heavy feature functions even when their handler body does not contain the raw query.
+- `hippocampus_episode_recall` deserves explicit priority because live evidence reported `LOCK_CONFLICT`, and source evidence shows the callee uses `with_connection` in `features/hippocampus/episode.rs`.
+
+## 2. MCP Server Lifecycle
+
+### 2.1 Dashboard HTTP MCP Endpoint
+
+The built-in MCP transport is `POST /api/mcp`, documented in `dashboard/src-tauri/src/infrastructure/http_server/routes/mcp.rs:1-7`. Tool calls are dispatched by `execute_tool_inner` starting around `mcp.rs:263`, with each tool arm calling the `mcp_tools::*` Rust handler inside the Dashboard process.
+
+Dashboard listens on port `18080` by default. Evidence: `DEFAULT_HTTP_PORT: u16 = 18080` in `dashboard/src-tauri/src/infrastructure/http_server/config.rs:10`, with `KENAZ_HTTP_PORT` as the override at `config.rs:13` and `config.rs:57`.
+
+### 2.2 Codex / Bifrost Discovery
+
+Bifrost documents the existing MCP discovery mechanism directly:
+
+- `.formation/bifrost/launch.js:20` says `codex mcp add kenaz-dashboard --url http://localhost:18080/api/mcp`.
+- `.formation/bifrost/launch.js:21` states Dashboard must be running for MCP/Synapse tools.
+- `.formation/bifrost/launch.js:233` logs `MCP: kenaz-dashboard connected`.
+- `.formation/bifrost/openai/relay.js:359` spawns Codex; the relay does not own the KuzuDB graph and should not open it.
+
+When Dashboard is offline, the current external MCP path cannot delegate to `/api/mcp`; tools should return a Dashboard-unavailable error rather than trying to open `.synapse/db/graph` directly.
+
+### 2.3 Current Lock Failure Mode
+
+KuzuDB has a process-level lock on the graph directory. Live evidence from 2026-04-21 showed Dashboard PID 29724 holding `.synapse/db/graph`, with `.wal` activity. Any separate MCP subprocess that opens the same graph via `with_connection` or `with_read_connection` can produce `LOCK_CONFLICT`.
+
+The existing code already recognizes this class for Cortex: `lock_aware_cortex_error` at `cortex.rs:965-980` detects lock errors and returns a user-friendly message. That is a symptom handler, not an architecture fix.
+
+## 3. Architectural Options
+
+### 3.1 Option A: Full Delegation To Dashboard HTTP
+
+All MCP tools become thin clients to Dashboard HTTP endpoints when running outside the Dashboard process. Direct-open tools stop using `with_connection` from the external MCP subprocess. Dashboard remains the only process that opens KuzuDB.
+
+Pros:
+
+- Eliminates cross-process KuzuDB lock conflicts by construction.
+- Reuses existing discovery: `http://localhost:18080/api/mcp`, `KENAZ_HTTP_PORT`, and Bifrost/Codex MCP setup.
+- Keeps the existing connection pool and QoS behavior inside one process.
+- Matches the known working shape: `synapse_sigils` delegates to `get_sigils_direct`, and `cortex_recall` works because it does not open KuzuDB.
+- Partial migration is testable per handler: replace external direct-open path with HTTP delegate and compare response JSON.
+
+Cons / trade-off:
+
+- Requires HTTP endpoint coverage for handlers that currently exist only as MCP handlers.
+- Dashboard must be running. Offline MCP calls should fail clearly instead of silently falling back to direct KuzuDB.
+- Some handlers write graph state; delegation must preserve idempotency, error messages, and projectPath handling.
+
+### 3.2 Option B: Shared-Process Mode Via IPC
+
+Keep an external MCP process but route KuzuDB operations through an IPC bridge into the Dashboard process or share a connection-pool service.
+
+Pros:
+
+- Preserves a separate MCP runtime while centralizing graph access.
+- Could support richer streaming or cancellation than plain HTTP if designed carefully.
+
+Cons / rejected reasoning:
+
+- More complex than the current HTTP MCP transport.
+- Reimplements routing, lifecycle, auth/permission, backpressure, and error normalization already present in `routes/mcp.rs`.
+- A "shared connection pool" cannot literally be shared across OS processes; it would be a new RPC server around the pool.
+- Higher failure surface: stale IPC handles, version skew, and shutdown ordering.
+
+### 3.3 Option C: Read-Only Replica For MCP
+
+Maintain a separate read-only KuzuDB copy for the MCP subprocess, synced from Dashboard.
+
+Pros:
+
+- Read-only tools could work while Dashboard is running.
+- Offline reads might be possible if the replica exists.
+
+Cons / rejected reasoning:
+
+- KuzuDB graph copy consistency becomes a product problem: stale replica, partial sync, WAL snapshot timing, and expensive copy operations.
+- Does not solve write tools (`synapse_declare`, `hippocampus_episode_close`, `synapse_link_cognitive`).
+- Doubles storage and introduces a second index freshness concept beyond current Synapse status.
+- Harder to explain to users: `synapse_search` and `synapse_orphans` could disagree depending on sync timing.
+
+## 4. Recommendation
+
+Recommend Option A: Full Dashboard HTTP delegation.
+
+Evidence:
+
+- The root failure is cross-process graph ownership. Moving all graph access behind Dashboard's existing `/api/mcp` or route endpoints removes the second process opening `.synapse/db/graph`.
+- The code already has a Dashboard endpoint and discovery contract: `POST /api/mcp`, default `18080`, and `codex mcp add kenaz-dashboard --url http://localhost:18080/api/mcp`.
+- The working tools in the incident fit this: `synapse_sigils` delegates to `get_sigils_direct`, and `cortex_recall` avoids KuzuDB entirely.
+- Direct-open handlers are mostly read-only or existing Dashboard-internal feature calls, so a delegation wrapper can preserve behavior without changing the graph algorithms.
+
+Rejected alternatives:
+
+- Shared-process IPC is rejected because it recreates the HTTP MCP transport with more operational states.
+- Read-only replica is rejected because it only helps reads, creates stale data risk, and leaves write tools unresolved.
+
+The migration target should be: when a tool is executed outside the Dashboard process, no handler path directly calls `with_connection`, `with_read_connection`, `SearchIndex::open` for graph-coupled cache writes, or feature functions that open KuzuDB. It should issue an HTTP delegate call to Dashboard or return a Dashboard-unavailable error.
+
+## 5. Migration Phases
+
+This is not a task-split plan; it is a phased migration shape for the future implementation task. This TASK_1358 document remains design only.
+
+### 5.1 Phase 0: Add Delegation Primitive
+
+Create a small MCP delegation client that:
+
+- Resolves Dashboard URL from `KENAZ_HTTP_PORT` / default `18080`.
+- Calls `POST /api/mcp` with the same JSON-RPC `tools/call` shape.
+- Preserves `projectPath`, `originSessionId`, timeout, and error message shape.
+- Fails closed when Dashboard is offline; it must not fall back to direct-open KuzuDB.
+
+The Sigil Dashboard Model Selection pipeline is a useful pattern for symmetric file-backed configuration and Dashboard-mediated access: `kenaz.rs:133-158` documents `.kenaz/dashboard-models.json`, and `.formation/tools/headless.js:839-876` reads the same registry from dispatch. For graph tools, prefer HTTP mediation over symmetric direct graph access.
+
+### 5.2 Phase 1: Read-Only Project Graph Tools
+
+Migrate lower-risk read-only direct-open project graph tools first:
+
+- `synapse_cypher`
+- `synapse_trace_route`
+- `synapse_map`
+- `synapse_pain_paths`
+- `synapse_orphans`
+- `synapse_health`
+- `thalamus_context`
+- `synapse_attention`
+- `synapse_imagine`
+
+Success criteria: each tool works while Dashboard is running and no external process opens `.synapse/db/graph`.
+
+### 5.3 Phase 2: Known Broken And Aggregator Tools
+
+Migrate known-broken and user-visible aggregators:
+
+- `hippocampus_episode_recall`
+- `synapse_maintain`
+- `synapse_think`
+- `synapse_pulse`
+- `synapse_impact`
+
+These need extra response-shape tests because they combine multiple subsystems and may partially degrade when a subcall fails.
+
+### 5.4 Phase 3: Write / Mixed Graph Tools
+
+Migrate graph-writing and mixed tools:
+
+- `synapse_forge`
+- `synapse_declare`
+- `synapse_verify`
+- `synapse_scan_stale_runes`
+- `synapse_link_cognitive`
+- `reflex_query`
+- `hippocampus_episode_start`
+- `hippocampus_episode_append`
+- `hippocampus_episode_close`
+- `hippocampus_episode_link`
+- `hippocampus_consolidate`
+- `hippocampus_detect_patterns`
+- `hippocampus_transcript_ingest`
+
+These require idempotency and write-conflict review. The delegate path should preserve current `McpToolResult` errors and never double-write if a retry occurs.
+
+### 5.5 Phase 4: Meta Graph Tools
+
+Decide separately whether Cortex meta graph tools should delegate through Dashboard:
+
+- `cortex_sync`
+- `cortex_relate`
+- `cortex_cypher`
+- `cortex_overview`
+
+They do not use the project `.synapse/db/graph`, but they share the same direct-KuzuDB-open architecture and can hit a similar lock class if another Kenaz process owns the meta graph.
+
+## 6. Risk Register
+
+| Risk | Impact | Mitigation |
+|---|---|---|
+| Partial migration leaves some direct-open tools | Users still hit `LOCK_CONFLICT` on un-migrated tools such as `synapse_orphans` or `hippocampus_episode_recall`. | Add a grep gate for external MCP code paths: no `with_connection`, `with_read_connection`, or transitive graph feature calls outside Dashboard-owned handlers. |
+| Dashboard offline behavior changes | Tools that previously tried direct-open may now fail immediately. | Return explicit Dashboard-unavailable guidance with the resolved URL and `KENAZ_HTTP_PORT`; do not reopen KuzuDB. |
+| Response shape drift | Agents relying on JSON fields break. | Golden-output tests around high-use tools before and after delegation. |
+| Project path lost in delegation | Delegated call accidentally uses Dashboard current project instead of the caller's worktree. | Always forward `projectPath`; Bifrost already instructs MCP calls to include it. |
+| Write tool retry creates duplicates | Graph writes can double-create edges or episodes. | Make write delegation idempotency explicit before migrating mixed/write handlers. |
+| Meta graph remains direct-open | Future Cortex lock conflicts remain possible. | Treat meta graph tools as Phase 4 after project graph tools are stable. |
+
+## 7. Scope Boundary
+
+No code changes were made to handlers. This document intentionally stops at investigation, classification, and architecture recommendation. Execution out of scope for TASK_1358.

package/core/dev/archive/ansuz/designs/phase0_git_enrichment.md

@@ -0,0 +1,278 @@
+# TASK_1334 Phase 0 Git Context Enrichment Design
+
+## Goal
+
+Augment `node .specialist/tools/phase-gate.js enter --phase=0` with a lightweight `git_context` payload so Ansuz starts with recent Uror/Verthandi awareness without replacing existing Tier 3x session handoff behavior.
+
+- Existing `output.session_handoff` remains unchanged.
+- New `output.git_context` is injected independently.
+- Optional banner rendering stays lean and must not exceed the existing PHASE0-LEAN expectation of 3-4 extra lines.
+
+## Knowledge Context
+
+- `.specialist/tools/phase-gate.js`
+  - Phase 0 already auto-injects `self_model`, `user_model`, `dynamic_user_context`, `muninn`, and `session_handoff`.
+  - Phase 0 enter writes compact auto-derived data into `chart.phases["0"].data` before `outputResult(...)`.
+- `.kenaz/specialist/ansuz_session_handoff.schema.json`
+  - Tier 3x handoff is a single active-slot restore/archive/delete flow; `git_context` must coexist, not replace it.
+- `hippocampus_episode_recall` MCP verification at design time
+  - Tool exists, but this worktree returned:
+  - `episode_recall failed: recall_by_scope failed: Query execution failed: Binder exception: Table Episode does not exist.`
+  - This confirms the interface is reachable but the local project has no Hippocampus schema yet.
+  - Actual successful response shape could not be sampled in this worktree; design therefore targets the documented MCP contract and current `callMcpTool(...)` parsing behavior in `phase-gate.js`.
+
+## Proposed Output Contract
+
+Inject a new field into the Phase 0 enter JSON payload:
+
+```json
+{
+  "git_context": {
+    "recent_commits": [
+      {
+        "hash": "abc1234",
+        "subject": "Phase 0 auto-restore session handoff",
+        "author_time_iso": "2026-04-20T14:21:05Z"
+      }
+    ],
+    "wt_diff_stat": {
+      "files_changed": 3,
+      "insertions": 42,
+      "deletions": 7
+    },
+    "since_iso": "2026-04-20T09:00:00Z",
+    "since_source": "last_session"
+  }
+}
+```
+
+Schema rules:
+
+- `recent_commits`: newest-first array from `git log --since=<since_iso>`.
+- `hash`: short hash from `%h`.
+- `subject`: `%s`, trimmed to one line.
+- `author_time_iso`: `%aI` so the payload stays ISO-8601 safe.
+- `wt_diff_stat`: parsed from `git diff --shortstat`.
+- `wt_diff_stat.files_changed`: integer, default `0`.
+- `wt_diff_stat.insertions`: integer, default `0`.
+- `wt_diff_stat.deletions`: integer, default `0`.
+- `since_iso`: effective lower bound used for `git log`.
+- `since_source`: enum:
+  - `last_session`
+  - `fallback_24h`
+
+If Phase 0 decides to skip git probing, `output.git_context` should be `null` rather than a partially-filled object.
+
+## Phase 0 Enter Integration
+
+Add a Phase 0 auto step adjacent to the current `session_handoff` block:
+
+1. `const gitContextResult = phase === 0 ? readGitContext(warnings, specialistName) : null;`
+2. Persist summary markers into `chart.phases["0"].data`, for example:
+   - `git_context_loaded`
+   - `git_context_since_source`
+   - `git_context_since_iso`
+3. Return `git_context: phase === 0 ? gitContextResult : null` from `outputResult(...)`.
+
+This mirrors the current Phase 0 pattern used by `muninn`, `dynamic_user_context`, and `session_handoff`.
+
+## Since Computation
+
+### Primary Path: last Ansuz session close time
+
+Use Hippocampus to determine the most recent completed Ansuz session and derive `since_iso` from that close time.
+
+Target lookup:
+
+- MCP tool: `hippocampus_episode_recall`
+- Intent: latest closed episode where `agent_role='ansuz'`
+- Desired ordering: `closed_at DESC`
+- Desired limit: `1`
+
+Important design note:
+
+- The currently exposed MCP signature in this environment does not show direct `agent_role` or `outcome` filter parameters.
+- Because of that, `phase-gate.js` should treat the lookup as a best-effort helper:
+  - First, call `hippocampus_episode_recall(...)` through existing `callMcpTool(...)`.
+  - Then filter the returned episodes client-side for Ansuz-owned, closed sessions if those fields are present.
+  - If the MCP backend is later extended with explicit `agent_role` and `outcome` filters, `phase-gate.js` can pass them directly without changing the `git_context` schema.
+
+Expected successful response shape to consume:
+
+```json
+{
+  "episodes": [
+    {
+      "episode_id": "ep_xxx",
+      "agent_role": "ansuz",
+      "outcome": "success",
+      "closed_at": "2026-04-20T09:00:00Z",
+      "scope": "..."
+    }
+  ]
+}
+```
+
+Selection rule:
+
+- choose the newest episode with `agent_role === 'ansuz'`
+- require a valid `closed_at`
+- treat any closed outcome (`success`, `partial`, `blocked`) as a usable last-session boundary
+
+### Fallback Path
+
+If Hippocampus is unavailable, empty, malformed, or lacks a usable `closed_at`, compute:
+
+- `since_iso = now - 24h`
+- `since_source = 'fallback_24h'`
+
+### Noise Cap
+
+Even when a prior session is much older, cap the git window at 7 days:
+
+- `effective_since_iso = max(last_session_closed_at, now - 7d)`
+- if the capped value still originates from a valid prior session, keep `since_source = 'last_session'`
+- only use `fallback_24h` when no valid prior session time exists at all
+
+This keeps Phase 0 from surfacing stale commit noise after long inactivity.
+
+## Git Probing Flow
+
+Implement `readGitContext(warnings, specialistName)` as a pure helper with graceful degradation:
+
+1. Resolve active project root exactly the same way as other `.kenaz`-aware Phase 0 helpers.
+2. Read `.kenaz/project.yaml`.
+3. If `phase0.git_context: disabled`, return `null` immediately.
+4. If no `.git` directory exists at the active project root, return `null` silently.
+5. Compute `since_iso` using the Hippocampus/fallback logic above.
+6. Execute:
+   - `git log --since=<since_iso> --pretty=format:%h%x09%s%x09%aI --no-merges`
+   - `git diff --shortstat`
+7. Parse both outputs into the normalized schema.
+8. Return `null` only on hard execution failure.
+
+Graceful-degradation rules:
+
+- non-git project: silently skip
+- git command exits non-zero: push one warning and return `null`
+- malformed shortstat: coerce missing numeric fields to `0`
+- empty commit range + clean tree: return a valid object with empty/zero payloads, not `null`
+
+## Parsing Details
+
+### Recent commits
+
+Split each `git log` line on `\t` into:
+
+- `hash`
+- `subject`
+- `author_time_iso`
+
+Ignore malformed rows instead of failing the whole enrichment.
+
+### Working-tree diff stat
+
+Parse common `git diff --shortstat` forms, for example:
+
+- `1 file changed, 2 insertions(+), 1 deletion(-)`
+- `3 files changed, 10 insertions(+)`
+- `2 files changed, 5 deletions(-)`
+
+Recommended regex extraction:
+
+- `/(\d+)\s+files?\s+changed/`
+- `/(\d+)\s+insertions?\(\+\)/`
+- `/(\d+)\s+deletions?\(-\)/`
+
+## Optional Phase 0 Banner Tier
+
+This tier is display-only. Full data always remains available in `output.git_context`.
+
+Render only when there is signal:
+
+- If `recent_commits.length > 0`
+  - show up to top 3 subjects
+  - each subject is one compact line
+- If `wt_diff_stat.files_changed > 0`
+  - show one line like:
+  - `WT diff: 3 files, +42/-7`
+
+PHASE0-LEAN rendering budget:
+
+- max 3 lines from commits
+- max 1 line from working tree
+- if both exist, total max = 4 lines
+
+Do not show hashes or timestamps in the banner. They stay in `git_context` for internal priming only.
+
+Example:
+
+```text
+Git since last Ansuz session:
+- Add Phase 0 handoff archive fallback
+- Tighten mirror_acknowledged validation
+- Persist dynamic user context summary
+WT diff: 3 files, +42/-7
+```
+
+## Opt-out and Project Compatibility
+
+### opt-out switch
+
+Add a project-level flag in `.kenaz/project.yaml`:
+
+```yaml
+phase0:
+  git_context: disabled
+```
+
+Behavior:
+
+- missing key => enabled by default
+- `disabled` => skip all git probing and return `output.git_context = null`
+
+### non-git project
+
+If the active project root has no `.git` directory:
+
+- skip silently
+- no warning
+- `output.git_context = null`
+
+This keeps sub-project and imported-doc workflows clean.
+
+## Implementation Sketch
+
+Suggested helper layout inside `phase-gate.js`:
+
+- `readPhase0ProjectConfig()`
+- `isGitContextDisabled(projectConfig)`
+- `resolveGitContextSinceIso(warnings, specialistName)`
+- `readLastAnsuzSessionClosedAt(warnings, specialistName)`
+- `readGitContext(warnings, specialistName)`
+- `parseGitShortStat(raw)`
+- `formatGitContextBannerLines(gitContext)`
+
+No existing Tier 3x or handoff code should be removed.
+
+## Risks and Guardrails
+
+- Hippocampus schema may be absent in fresh projects.
+  - Treat lookup failure as a normal fallback case, not a blocker.
+- `hippocampus_episode_recall` current exposed arguments may not support the exact server-side filters requested in the task notes.
+  - Client-side filtering is the safe first implementation.
+- `git diff --shortstat` reflects uncommitted working-tree state only.
+  - This is intentional: recent commits cover committed changes; `wt_diff_stat` covers current Verthandi drift.
+- Phase 0 is already crowded.
+  - Keep banner rendering optional and compact; the authoritative payload is `output.git_context`.
+
+## Acceptance Mapping
+
+- `git_context`
+  - schema and integration are defined above.
+- `since_source`
+  - explicit enum and selection rules are defined above.
+- `hippocampus`
+  - last-session determination and design-time interface verification are documented above.
+- `opt-out`
+  - `.kenaz/project.yaml phase0.git_context: disabled` is defined above.