pantheon-opencode 1.3.6 → 1.4.0

package/opencode.json

@@ -27,7 +27,8 @@
       "npx *": "allow",
       "pytest *": "allow",
       "ruff *": "allow",
-      "pip *": "allow"
+      "pip *": "allow",
+      "python3 *": "allow"
     }
   },
   "mcp": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pantheon-opencode",
-  "version": "1.3.6",
+  "version": "1.4.0",
   "description": "Multi-agent orchestration for OpenCode — 14 specialized agents, TDD, Themis review gates.",
   "publishConfig": {
     "access": "public",

package/scripts/install/opencode.mjs

@@ -450,6 +450,7 @@ export async function installOpenCode(
       'memory_mcp_server.py',
       'scrub-secrets.py',
       '_pantheon_paths.py',
+      'mcp_codemap_module.py',
       'mcp_persistence_server.py',
       'pantheon_vision_server.py',
       'eval_store.py',
@@ -465,6 +466,7 @@ export async function installOpenCode(
       'code_mode_server.py': join(ROOT, 'src', 'mcp', 'code_mode_server.py'),
       'memory_mcp_server.py': join(ROOT, 'src', 'mcp', 'memory_mcp_server.py'),
       '_pantheon_paths.py': join(ROOT, 'src', 'mcp', '_pantheon_paths.py'),
+      'mcp_codemap_module.py': join(ROOT, 'src', 'mcp', 'mcp_codemap_module.py'),
       'mcp_persistence_server.py': join(ROOT, 'src', 'mcp', 'mcp_persistence_server.py'),
       'pantheon_vision_server.py': join(ROOT, 'src', 'mcp', 'pantheon_vision_server.py'),
       'eval_store.py': join(ROOT, 'src', 'mcp', 'eval_store.py'),

package/scripts/sync-tui.mjs

@@ -0,0 +1,148 @@
+#!/usr/bin/env node
+/**
+ * sync-tui.mjs — Postinstall hook: sync TUI plugin to user's OpenCode config
+ *
+ * Runs automatically after `npm install pantheon-opencode@latest`. Detects the
+ * user's OpenCode config directory and, if the TUI plugin was previously
+ * installed (via `npx pantheon-opencode init`), copies fresh files from the
+ * installed package and refreshes dependencies.
+ *
+ * If the user hasn't initialized yet → do nothing (silent exit).
+ */
+import { execSync } from 'node:child_process'
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const __dirname = fileURLToPath(new URL('.', import.meta.url))
+const ROOT = join(__dirname, '..')
+
+// ── Helpers ────────────────────────────────────────────────────────────
+
+/**
+ * Write content to filePath only if it differs from what's on disk.
+ * @returns {boolean} true if file was written (changed), false if skipped
+ */
+function writeIfChanged(filePath, content) {
+  const existing = existsSync(filePath) ? readFileSync(filePath, 'utf8') : null
+  if (existing === content) return false
+  writeFileSync(filePath, content, 'utf8')
+  return true
+}
+
+/**
+ * Read the `version` field from a package.json, or null on failure.
+ */
+function readVersion(pkgPath) {
+  try {
+    return JSON.parse(readFileSync(pkgPath, 'utf8')).version || null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Resolve the user's OpenCode config directory.
+ * Priority: $XDG_CONFIG_HOME/opencode → ~/.opencode → null (not initialized)
+ */
+function resolveConfigDir() {
+  const xdgConfig = process.env.XDG_CONFIG_HOME || join(homedir(), '.config')
+  const xdgDir = join(xdgConfig, 'opencode')
+  if (existsSync(xdgDir)) return xdgDir
+
+  const homeDir = join(homedir(), '.opencode')
+  if (existsSync(homeDir)) return homeDir
+
+  return null
+}
+
+/**
+ * Copy plugin runtime files (dist/*, package.json, src/index.tsx) from srcDir
+ * to dstDir. Skips files that are byte-identical.
+ * @returns {{ created: number, skipped: number }}
+ */
+function copyPluginFiles(srcDir, dstDir) {
+  const result = { created: 0, skipped: 0 }
+
+  mkdirSync(dstDir, { recursive: true })
+  mkdirSync(join(dstDir, 'dist'), { recursive: true })
+
+  // src/index.tsx → index.tsx
+  const srcIdx = join(srcDir, 'src', 'index.tsx')
+  if (existsSync(srcIdx)) {
+    const content = readFileSync(srcIdx, 'utf8')
+    if (writeIfChanged(join(dstDir, 'index.tsx'), content)) result.created++
+    else result.skipped++
+  }
+
+  // dist/*
+  const distSrc = join(srcDir, 'dist')
+  if (existsSync(distSrc)) {
+    for (const f of readdirSync(distSrc)) {
+      const content = readFileSync(join(distSrc, f), 'utf8')
+      if (writeIfChanged(join(dstDir, 'dist', f), content)) result.created++
+      else result.skipped++
+    }
+  }
+
+  // package.json
+  const pkgSrc = join(srcDir, 'package.json')
+  if (existsSync(pkgSrc)) {
+    const content = readFileSync(pkgSrc, 'utf8')
+    if (writeIfChanged(join(dstDir, 'package.json'), content)) result.created++
+    else result.skipped++
+  }
+
+  return result
+}
+
+// ── Main ───────────────────────────────────────────────────────────────
+
+try {
+  const configDir = resolveConfigDir()
+  if (!configDir) {
+    // User hasn't run init yet — silent exit, no error
+    process.exit(0)
+  }
+
+  const tuiCopyDir = join(configDir, 'plugins', 'pantheon-tui')
+  if (!existsSync(tuiCopyDir)) {
+    // TUI plugin not installed — silent exit
+    process.exit(0)
+  }
+
+  // Source: TUI plugin inside the installed package
+  const tuiSrcDir = join(ROOT, 'src', 'plugins', 'tui')
+  if (!existsSync(tuiSrcDir)) {
+    // Source not found (shouldn't happen in a proper install)
+    process.exit(0)
+  }
+
+  // Compare versions before copy
+  const installedVersion = readVersion(join(tuiCopyDir, 'package.json'))
+  const sourceVersion = readVersion(join(tuiSrcDir, 'package.json'))
+
+  // Copy fresh files
+  const { created, skipped } = copyPluginFiles(tuiSrcDir, tuiCopyDir)
+
+  // Refresh dependencies in the copy
+  try {
+    execSync('npm install --omit=dev --no-audit', { cwd: tuiCopyDir, stdio: 'pipe' })
+  } catch {
+    // Non-fatal — deps may already be current
+  }
+
+  // Log result
+  if (installedVersion && sourceVersion && installedVersion === sourceVersion && created === 0) {
+    console.log(`  TUI plugin already up to date (v${sourceVersion})`)
+  } else {
+    console.log(
+      `  TUI plugin updated to v${sourceVersion || 'latest'}${installedVersion ? ` (was v${installedVersion})` : ''}`,
+    )
+  }
+} catch (err) {
+  // Postinstall scripts must never break npm install
+  console.warn(`⚠️  TUI sync skipped: ${err.message}`)
+  process.exit(0)
+}

package/src/mcp/mcp_codemap_module.py

@@ -0,0 +1,185 @@
+# ruff: noqa: E701,E702,E741,I001,E401,RUF100,W292
+"""Pantheon Codemap — lean KG for Python/TS (ast+regex), 3 tables+FTS5."""
+from __future__ import annotations
+import ast, hashlib, re, sqlite3
+from pathlib import Path
+from typing import Any
+LARGE_FILE_THRESHOLD = 512 * 1024
+SUPPORTED_EXTS: dict[str, str] = {".py":"python",".ts":"typescript",".tsx":"typescript",".js":"typescript",".jsx":"typescript",".mts":"typescript",".cts":"typescript"}
+CODEMAP_SCHEMA_SQL = """
+CREATE TABLE IF NOT EXISTS code_entities (id TEXT PRIMARY KEY,file_path TEXT NOT NULL,name TEXT NOT NULL,type TEXT NOT NULL,language TEXT NOT NULL,start_line INTEGER,end_line INTEGER,signature TEXT,docstring TEXT);
+CREATE INDEX IF NOT EXISTS idx_code_entities_type ON code_entities(type);
+CREATE INDEX IF NOT EXISTS idx_code_entities_name ON code_entities(name);
+CREATE INDEX IF NOT EXISTS idx_code_entities_path ON code_entities(file_path);
+CREATE TABLE IF NOT EXISTS code_relations (id INTEGER PRIMARY KEY AUTOINCREMENT,source_id TEXT NOT NULL,target_id TEXT NOT NULL,type TEXT NOT NULL,FOREIGN KEY(source_id) REFERENCES code_entities(id),FOREIGN KEY(target_id) REFERENCES code_entities(id));
+CREATE INDEX IF NOT EXISTS idx_code_relations_source ON code_relations(source_id);
+CREATE INDEX IF NOT EXISTS idx_code_relations_target ON code_relations(target_id);
+CREATE TABLE IF NOT EXISTS code_files (path TEXT PRIMARY KEY,hash TEXT NOT NULL,language TEXT NOT NULL,indexed_at TEXT NOT NULL DEFAULT (datetime('now')));
+CREATE VIRTUAL TABLE IF NOT EXISTS code_entities_fts USING fts5(name,signature,docstring,content='code_entities',content_rowid='rowid',tokenize='porter unicode61');
+CREATE TRIGGER IF NOT EXISTS code_entities_ai AFTER INSERT ON code_entities BEGIN INSERT INTO code_entities_fts(rowid,name,signature,docstring) VALUES (new.rowid,new.name,new.signature,new.docstring); END;
+CREATE TRIGGER IF NOT EXISTS code_entities_ad AFTER DELETE ON code_entities BEGIN INSERT INTO code_entities_fts(code_entities_fts,rowid,name,signature,docstring) VALUES ('delete',old.rowid,old.name,old.signature,old.docstring); END;
+CREATE TRIGGER IF NOT EXISTS code_entities_au AFTER UPDATE ON code_entities BEGIN INSERT INTO code_entities_fts(code_entities_fts,rowid,name,signature,docstring) VALUES ('delete',old.rowid,old.name,old.signature,old.docstring); INSERT INTO code_entities_fts(rowid,name,signature,docstring) VALUES (new.rowid,new.name,new.signature,new.docstring); END;
+"""
+def ensure_codemap_schema(conn: sqlite3.Connection) -> None:
+    conn.executescript(CODEMAP_SCHEMA_SQL); conn.commit()
+def drop_codemap_schema(conn: sqlite3.Connection) -> None:
+    conn.executescript("DROP TRIGGER IF EXISTS code_entities_ai;DROP TRIGGER IF EXISTS code_entities_ad;DROP TRIGGER IF EXISTS code_entities_au;DROP TABLE IF EXISTS code_entities_fts;DROP TABLE IF EXISTS code_relations;DROP TABLE IF EXISTS code_entities;DROP TABLE IF EXISTS code_files;"); conn.commit()
+def _hash_content(c: str) -> str: return hashlib.sha256(c.encode()).hexdigest()
+def _entity_id(fp: str, name: str, tp: str) -> str: return hashlib.sha256(f"{fp}:{name}:{tp}".encode()).hexdigest()[:16]
+def _parse_python_entities(fp: str, content: str) -> tuple[list[dict[str,Any]], list[dict[str,Any]]]:  # noqa: C901, PLR0912, PLR0915
+    ents: list[dict[str,Any]] = []; rels: list[dict[str,Any]] = []; ph: dict[str,dict[str,Any]] = {}
+    try: tree = ast.parse(content, filename=fp)
+    except SyntaxError: return [], []
+    file_mod: str|None = None
+    def _file_mod() -> str:
+        nonlocal file_mod
+        if file_mod is None:
+            stem = Path(fp).stem; fid=_entity_id(fp,stem,"module")
+            if fid not in ph: ph[fid]={"id":fid,"file_path":fp,"name":stem,"type":"module","language":"python","start_line":1,"end_line":1,"signature":f"module {stem}","docstring":""}
+            file_mod=fid
+        return file_mod
+    for node in tree.body:
+        if isinstance(node, ast.ClassDef):
+            cid=_entity_id(fp,node.name,"class"); doc=ast.get_docstring(node) or ""
+            bases=[]
+            for b in node.bases:
+                if isinstance(b, ast.Name): bases.append(b.id)
+                elif isinstance(b, ast.Attribute): bases.append(b.attr)
+            sig=f"class {node.name}({', '.join(bases)})" if bases else f"class {node.name}"
+            ents.append({"id":cid,"file_path":fp,"name":node.name,"type":"class","language":"python","start_line":getattr(node,"lineno",0),"end_line":getattr(node,"end_lineno",0) or getattr(node,"lineno",0),"signature":sig,"docstring":doc})
+            for base in bases:
+                tid=_entity_id(f"external:{base}",base,"class")
+                if tid not in ph: ph[tid]={"id":tid,"file_path":f"external:{base}","name":base,"type":"class","language":"python","start_line":0,"end_line":0,"signature":f"class {base}","docstring":""}
+                rels.append({"source_id":cid,"target_id":tid,"type":"inherits"})
+            for item in node.body:
+                if isinstance(item,(ast.FunctionDef,ast.AsyncFunctionDef)):
+                    mid=_entity_id(fp,f"{node.name}.{item.name}","method"); docm=ast.get_docstring(item) or ""; args=", ".join(a.arg for a in item.args.args); sig_m=f"def {item.name}({args})"
+                    ents.append({"id":mid,"file_path":fp,"name":f"{node.name}.{item.name}","type":"method","language":"python","start_line":getattr(item,"lineno",0),"end_line":getattr(item,"end_lineno",0) or getattr(item,"lineno",0),"signature":sig_m,"docstring":docm})
+        elif isinstance(node,(ast.FunctionDef,ast.AsyncFunctionDef)):
+            fid=_entity_id(fp,node.name,"function"); doc=ast.get_docstring(node) or ""; args=", ".join(a.arg for a in node.args.args); sig=f"def {node.name}({args})"
+            ents.append({"id":fid,"file_path":fp,"name":node.name,"type":"function","language":"python","start_line":getattr(node,"lineno",0),"end_line":getattr(node,"end_lineno",0) or getattr(node,"lineno",0),"signature":sig,"docstring":doc})
+        elif isinstance(node, ast.Import):
+            for alias in node.names:
+                mod=alias.name.split(".")[0]; tid=_entity_id(f"external:{mod}",mod,"module")
+                if tid not in ph: ph[tid]={"id":tid,"file_path":f"external:{mod}","name":mod,"type":"module","language":"python","start_line":0,"end_line":0,"signature":f"import {mod}","docstring":""}
+                src=_file_mod(); rels.append({"source_id":src,"target_id":tid,"type":"imports"})
+        elif isinstance(node, ast.ImportFrom):
+            mod=(node.module or "").split(".")[0]
+            if mod:
+                tid=_entity_id(f"external:{mod}",mod,"module")
+                if tid not in ph: ph[tid]={"id":tid,"file_path":f"external:{mod}","name":mod,"type":"module","language":"python","start_line":0,"end_line":0,"signature":f"from {mod} import ...","docstring":""}
+                src=_file_mod(); rels.append({"source_id":src,"target_id":tid,"type":"imports"})
+    eids={e["id"] for e in ents}
+    for pid,pent in ph.items():
+        if pid not in eids: ents.append(pent)
+    return ents, rels
+_TS_CLASS_RE=re.compile(r"^\s*(?:export\s+)?class\s+(\w+)(?:\s+extends\s+(\w+))?",re.MULTILINE)
+_TS_INTERFACE_RE=re.compile(r"^\s*(?:export\s+)?interface\s+(\w+)",re.MULTILINE)
+_TS_FUNC_RE=re.compile(r"^\s*(?:export\s+)?(?:async\s+)?function\s+(\w+)\s*\(",re.MULTILINE)
+_TS_CONST_RE=re.compile(r"^\s*(?:export\s+)?const\s+(\w+)\s*(?:[:=])",re.MULTILINE)
+_TS_IMPORT_RE=re.compile(r"^\s*import\s+.*?from\s+['\"]([^'\"]+)['\"]",re.MULTILINE)
+def _parse_typescript_entities(fp: str, content: str) -> tuple[list[dict[str,Any]], list[dict[str,Any]]]:  # noqa: C901
+    ents: list[dict[str,Any]]=[]; rels: list[dict[str,Any]]=[]; ph: dict[str,dict[str,Any]]={}
+    def _ph(name: str, tp: str, sig: str) -> str:
+        tid=_entity_id(f"external:{name}",name,tp)
+        if tid not in ph: ph[tid]={"id":tid,"file_path":f"external:{name}","name":name,"type":tp,"language":"typescript","start_line":0,"end_line":0,"signature":sig,"docstring":""}
+        return tid
+    lines=content.splitlines()
+    def _line(pat: str, name: str) -> int:
+        for i,l in enumerate(lines, start=1):
+            if pat in l and name in l: return i
+        return 1
+    for m in _TS_CLASS_RE.finditer(content):
+        name=m.group(1); base=m.group(2); cid=_entity_id(fp,name,"class"); sig=f"class {name}"+(f" extends {base}" if base else "")
+        ents.append({"id":cid,"file_path":fp,"name":name,"type":"class","language":"typescript","start_line":_line("class",name),"end_line":_line("class",name),"signature":sig,"docstring":""})
+        if base: tid=_ph(base,"class",f"class {base}"); rels.append({"source_id":cid,"target_id":tid,"type":"inherits"})
+    for m in _TS_INTERFACE_RE.finditer(content):
+        name=m.group(1); iid=_entity_id(fp,name,"interface")
+        ents.append({"id":iid,"file_path":fp,"name":name,"type":"interface","language":"typescript","start_line":_line("interface",name),"end_line":_line("interface",name),"signature":f"interface {name}","docstring":""})
+    for m in _TS_FUNC_RE.finditer(content):
+        name=m.group(1); fid=_entity_id(fp,name,"function")
+        ents.append({"id":fid,"file_path":fp,"name":name,"type":"function","language":"typescript","start_line":_line("function",name),"end_line":_line("function",name),"signature":f"function {name}()","docstring":""})
+    for m in _TS_CONST_RE.finditer(content):
+        name=m.group(1); cid=_entity_id(fp,name,"const")
+        ents.append({"id":cid,"file_path":fp,"name":name,"type":"const","language":"typescript","start_line":_line("const",name),"end_line":_line("const",name),"signature":f"const {name}","docstring":""})
+    for m in _TS_IMPORT_RE.finditer(content):
+        raw=m.group(1); mod=raw.split("/")[-1].replace(".js","").replace(".ts","") or raw; tid=_ph(mod,"module",f"import {raw}"); stem=Path(fp).stem; src=_entity_id(fp,stem,"module")
+        if src not in {e["id"] for e in ents} and src not in ph: ph[src]={"id":src,"file_path":fp,"name":stem,"type":"module","language":"typescript","start_line":1,"end_line":1,"signature":f"module {stem}","docstring":""}
+        rels.append({"source_id":src,"target_id":tid,"type":"imports"})
+    eids={e["id"] for e in ents}
+    for pid,pent in ph.items():
+        if pid not in eids: ents.append(pent)
+    return ents, rels
+def _insert_entities_and_relations(conn: sqlite3.Connection, ents: list[dict[str,Any]], rels: list[dict[str,Any]]) -> None:
+    for e in ents:
+        conn.execute("INSERT OR REPLACE INTO code_entities (id,file_path,name,type,language,start_line,end_line,signature,docstring) VALUES (?,?,?,?,?,?,?,?,?)",[e["id"],e["file_path"],e["name"],e["type"],e["language"],e["start_line"],e["end_line"],e["signature"],e["docstring"]])
+    for r in rels:
+        if not conn.execute("SELECT 1 FROM code_relations WHERE source_id=? AND target_id=? AND type=?", [r["source_id"],r["target_id"],r["type"]]).fetchone():
+            conn.execute("INSERT INTO code_relations (source_id,target_id,type) VALUES (?,?,?)", [r["source_id"],r["target_id"],r["type"]])
+def code_index(conn: sqlite3.Connection, path: str|Path|None=None, force: bool=False) -> dict[str,Any]:  # noqa: C901, PLR0912, PLR0915
+    ensure_codemap_schema(conn)
+    base=Path(path) if path else Path.cwd()
+    if not base.exists(): return {"error":f"Path not found: {base}","indexed":0,"skipped":0}
+    files: list[Path]=[base] if base.is_file() else [p for ext in SUPPORTED_EXTS for p in base.rglob(f"*{ext}")]
+    indexed=skipped=errors=large_skipped=unsupported=0
+    for f in files:
+        if any(p.startswith(".") for p in f.parts) and ".pantheon" not in str(f) and (".git" in f.parts or "__pycache__" in f.parts): continue
+        if "node_modules" in f.parts or ".venv" in f.parts or "venv" in f.parts: continue
+        ext=f.suffix.lower(); lang=SUPPORTED_EXTS.get(ext)
+        if not lang: unsupported+=1; continue
+        try:
+            if f.stat().st_size > LARGE_FILE_THRESHOLD: large_skipped+=1; continue
+            content=f.read_text(encoding="utf-8",errors="ignore")
+            if not content.strip():
+                h=_hash_content(content); conn.execute("INSERT OR REPLACE INTO code_files (path,hash,language) VALUES (?,?,?)",[str(f),h,lang]); conn.commit(); skipped+=1; continue
+            h=_hash_content(content)
+            row=conn.execute("SELECT hash FROM code_files WHERE path=?",[str(f)]).fetchone()
+            if row and row[0]==h and not force: skipped+=1; continue
+            ents,rels=_parse_python_entities(str(f),content) if lang=="python" else _parse_typescript_entities(str(f),content)
+            if not ents and not rels:
+                conn.execute("INSERT OR REPLACE INTO code_files (path,hash,language) VALUES (?,?,?)",[str(f),h,lang]); conn.commit()
+                try: ast.parse(content)
+                except SyntaxError: errors+=1; continue
+                skipped+=1; continue
+            _insert_entities_and_relations(conn,ents,rels)
+            conn.execute("INSERT OR REPLACE INTO code_files (path,hash,language) VALUES (?,?,?)",[str(f),h,lang]); conn.commit(); indexed+=1
+        except Exception: errors+=1; continue
+    return {"indexed":indexed,"skipped":skipped,"errors":errors,"large_skipped":large_skipped,"unsupported":unsupported}
+def code_query(conn: sqlite3.Connection, query: str, type_filter: str|None=None, limit: int=10) -> list[dict[str,Any]]:
+    if not query or not query.strip(): return []
+    limit=max(1,min(50,int(limit))); q=query.strip(); ensure_codemap_schema(conn)
+    try:
+        fts_q=" OR ".join(f'"{w}"*' for w in q.split() if w)
+        if not fts_q: raise ValueError
+        if type_filter:
+            rows=conn.execute("SELECT e.id,e.file_path,e.name,e.type,e.language,e.start_line,e.end_line,e.signature,e.docstring FROM code_entities_fts f JOIN code_entities e ON e.rowid=f.rowid WHERE code_entities_fts MATCH ? AND e.type=? ORDER BY rank LIMIT ?",[fts_q,type_filter,limit]).fetchall()
+        else:
+            rows=conn.execute("SELECT e.id,e.file_path,e.name,e.type,e.language,e.start_line,e.end_line,e.signature,e.docstring FROM code_entities_fts f JOIN code_entities e ON e.rowid=f.rowid WHERE code_entities_fts MATCH ? ORDER BY rank LIMIT ?",[fts_q,limit]).fetchall()
+        if rows: return [dict(r) for r in rows]
+    except Exception: pass
+    try:
+        like=f"%{q}%"
+        if type_filter:
+            rows=conn.execute("SELECT id,file_path,name,type,language,start_line,end_line,signature,docstring FROM code_entities WHERE (name LIKE ? OR signature LIKE ? OR docstring LIKE ?) AND type=? LIMIT ?",[like,like,like,type_filter,limit]).fetchall()
+        else:
+            rows=conn.execute("SELECT id,file_path,name,type,language,start_line,end_line,signature,docstring FROM code_entities WHERE name LIKE ? OR signature LIKE ? OR docstring LIKE ? LIMIT ?",[like,like,like,limit]).fetchall()
+        return [dict(r) for r in rows]
+    except Exception: return []
+def code_neighbors(conn: sqlite3.Connection, entity_id: str, depth: int=1) -> dict[str,Any]:
+    ensure_codemap_schema(conn); depth=max(1,min(3,int(depth)))
+    row=conn.execute("SELECT * FROM code_entities WHERE id=?",[entity_id]).fetchone()
+    if not row: return {"error":"Entity not found","entity_id":entity_id}
+    start=dict(row); visited: dict[str,dict[str,Any]]={entity_id:start}; queue=[(entity_id,0)]; edges=[]; seen=set()
+    while queue:
+        cur,d=queue.pop(0)
+        if d>=depth: continue
+        for r in conn.execute("SELECT * FROM code_relations WHERE source_id=? OR target_id=?",[cur,cur]).fetchall():
+            rel=dict(r); key=(rel["source_id"],rel["target_id"],rel["type"])
+            if key in seen: continue
+            seen.add(key); edges.append(rel)
+            nid=rel["target_id"] if rel["source_id"]==cur else rel["source_id"]
+            if nid not in visited:
+                nrow=conn.execute("SELECT * FROM code_entities WHERE id=?",[nid]).fetchone()
+                visited[nid]=dict(nrow) if nrow else {"id":nid,"file_path":"external:unknown","name":nid,"type":"placeholder","language":"","start_line":0,"end_line":0,"signature":"","docstring":""}
+                if d+1<depth: queue.append((nid,d+1))
+    return {"entity":start,"neighbors":[v for k,v in visited.items() if k!=entity_id],"relations":edges,"depth":depth}

package/src/mcp/memory_mcp_server.py

@@ -20,12 +20,13 @@ Usage:
 
 from __future__ import annotations
 
+import contextlib
 import functools
 import json
 import os
 import sqlite3
 import time
-from datetime import datetime, timezone
+from datetime import UTC, datetime
 from pathlib import Path
 from typing import Any
 
@@ -34,6 +35,18 @@ from _pantheon_paths import pantheon_home
 from fastembed import TextEmbedding
 from mcp.server.fastmcp import FastMCP
 
+try:
+    import mcp_codemap_module as _codemap
+except ImportError:  # pragma: no cover - deployed runtime may need path fix
+    try:
+        import sys as _sys
+        from pathlib import Path as _Path
+
+        _sys.path.insert(0, str(_Path(__file__).parent))
+        import mcp_codemap_module as _codemap  # type: ignore[no-redef]
+    except ImportError:
+        _codemap = None  # type: ignore[assignment]
+
 # ── Paths ─────────────────────────────────────────────────────────────────────
 
 DB_PATH = pantheon_home() / "memory" / "memory.db"
@@ -128,6 +141,9 @@ def _get_db() -> sqlite3.Connection:
 
     sqlite_vec.load(conn)
     conn.executescript(SCHEMA_SQL)
+    if _codemap is not None:
+        with contextlib.suppress(Exception):
+            _codemap.ensure_codemap_schema(conn)
     return conn
 
 
@@ -198,7 +214,7 @@ def _parse_iso_ts(value: str) -> float:
     """
     dt = datetime.fromisoformat(value.replace("Z", "+00:00"))
     if dt.tzinfo is None:
-        dt = dt.replace(tzinfo=timezone.utc)
+        dt = dt.replace(tzinfo=UTC)
     return dt.timestamp()
 
 
@@ -351,7 +367,7 @@ def memory_store(
     "freshness half-life (2^(-days/decay_days)) so recent entries rank "
     "higher; default None keeps the original rank-only behavior.",
 )
-def memory_search(  # noqa: PLR0912
+def memory_search(  # noqa: C901, PLR0912
     query: str,
     namespace: str | None = None,
     top_k: int = 5,
@@ -675,6 +691,78 @@ def memory_stats() -> dict[str, Any]:
     return stats
 
 
+# ── Codemap Tools ───────────────────────────────────────────────────────────
+
+
+@mcp.tool(
+    description="Index codebase files incrementally (hash-based skip). "
+    "Parses Python (ast) and TypeScript (regex) to build knowledge graph.",
+)
+def code_index(
+    path: str | None = None,
+    force: bool = False,
+) -> dict[str, Any]:
+    """Index code files into knowledge graph.
+
+    Args:
+        path: File or directory to index; None = cwd.
+        force: Re-parse even if hash unchanged.
+
+    Returns:
+        Dict with indexed, skipped, errors, large_skipped, unsupported.
+    """
+    if _codemap is None:
+        return {"error": "codemap module not available"}
+    db = _get_conn()
+    return _codemap.code_index(db, path, force)
+
+
+@mcp.tool(
+    description="Search code entities via FTS5 (with LIKE fallback) and optional type filter.",
+)
+def code_query(
+    query: str,
+    type: str | None = None,
+    limit: int = 10,
+) -> list[dict[str, Any]]:
+    """Search code entities.
+
+    Args:
+        query: Search term (FTS5).
+        type: Optional entity type filter (class, function, method, etc.).
+        limit: Max results (1-50).
+
+    Returns:
+        List of matching entities.
+    """
+    if _codemap is None:
+        return [{"error": "codemap module not available"}]
+    db = _get_conn()
+    return _codemap.code_query(db, query, type, limit)
+
+
+@mcp.tool(
+    description="Get neighbors of a code entity via relations graph (BFS depth 1-3).",
+)
+def code_neighbors(
+    entity_id: str,
+    depth: int = 1,
+) -> dict[str, Any]:
+    """Get graph neighbors for an entity.
+
+    Args:
+        entity_id: Entity ID (hash).
+        depth: BFS depth 1-3.
+
+    Returns:
+        Dict with entity, neighbors, relations or error if not found.
+    """
+    if _codemap is None:
+        return {"error": "codemap module not available"}
+    db = _get_conn()
+    return _codemap.code_neighbors(db, entity_id, depth)
+
+
 # ── Main Entrypoint ───────────────────────────────────────────────────────────
 
 if __name__ == "__main__":

package/src/pantheon/command-normalizer.ts

@@ -0,0 +1,101 @@
+/**
+ * Command Normalizer (Fase 1) — deterministic `python` → `python3` rewrite.
+ *
+ * Ubuntu 20.04+ ships only `python3` (PEP 394); the bare `python` command does
+ * not exist. Agents frequently emit `python` instead of `python3`, so every
+ * `bash` command is normalized BEFORE execution via the `tool.execute.before`
+ * hook. Unlike the read-only enforcement guard (which THROWS to deny), this
+ * guard REWRITES the command in place and lets it run.
+ *
+ * The rewrite is anchored to the regex below — it only matches `python` as a
+ * standalone command token (start of line or after a shell delimiter), never
+ * as a substring. This is what keeps `pip install python-dateutil` intact.
+ *
+ * @module command-normalizer
+ */
+
+// Matches `python` as a command token: at the start of the command or after a
+// shell delimiter (`;`, `&`, `|`, `(`, `)`, or a quote), followed by
+// whitespace or end. Quotes are included so `bash -c "python foo"` (a common
+// bypass) is normalized too. Deliberately NOT `\bpython\b` — that would
+// corrupt `python-dateutil` in `pip install python-dateutil` (the `-` is a
+// word boundary).
+const PYTHON_NORMALIZE_RE = /(^|[\s;&|()"'])python([\s]|$)/g
+
+/** Result of normalizing a command string. */
+export interface NormalizeResult {
+  /** The command with `python` → `python3` applied (unchanged if no match). */
+  normalized: string
+  /** Whether any rewrite actually happened. */
+  wasRewritten: boolean
+}
+
+/** Whether the command invokes `python -c` (arbitrary eval — flagged as risk). */
+const PYTHON_C_RE = /(^|[\s;&|()"'])python([\s]+)-c([\s]|$)/
+
+/**
+ * Normalize a bash command string, rewriting standalone `python` tokens to
+ * `python3`. Pure function — no side effects, safe to unit test directly.
+ */
+export function normalizePythonCommand(command: string): NormalizeResult {
+  // Reset lastIndex first — the regex is global and `.test()` advances it.
+  PYTHON_NORMALIZE_RE.lastIndex = 0
+  const wasRewritten = PYTHON_NORMALIZE_RE.test(command)
+  PYTHON_NORMALIZE_RE.lastIndex = 0
+  const normalized = command.replace(PYTHON_NORMALIZE_RE, '$1python3$2')
+  return { normalized, wasRewritten }
+}
+
+/** Whether the command contains a `python -c` invocation (arbitrary eval). */
+export function isPythonCEval(command: string): boolean {
+  PYTHON_C_RE.lastIndex = 0
+  return PYTHON_C_RE.test(command)
+}
+
+/** Minimal logger surface the guard needs (matches plugin logger shape). */
+export interface NormalizerLogger {
+  warn(message: string): void
+}
+
+/** Options for createCommandNormalizer(). */
+export interface CommandNormalizerOptions {
+  /** Audit sink for rewrites and `python -c` warnings. */
+  logger?: NormalizerLogger
+}
+
+/**
+ * Build the `tool.execute.before` handler that rewrites `bash` commands.
+ * Only the `bash` tool is touched; every other tool passes through untouched.
+ * The rewrite mutates `output.args.command` so the normalized command is what
+ * actually executes. Never throws — normalization must not break a session.
+ */
+export function createCommandNormalizer(
+  options: CommandNormalizerOptions = {},
+): (input: { tool: string; sessionID: string }, output?: { args?: unknown }) => Promise<void> {
+  const logger = options.logger
+
+  return async (input, output): Promise<void> => {
+    if (input.tool !== 'bash') return
+    if (output?.args === null || typeof output?.args !== 'object') return
+
+    const args = output.args as Record<string, unknown>
+    const command = args.command
+    if (typeof command !== 'string' || command.trim() === '') return
+
+    const { normalized, wasRewritten } = normalizePythonCommand(command)
+
+    if (isPythonCEval(command)) {
+      logger?.warn(
+        `[command-normalizer] WARNING python -c detected: session=${input.sessionID} command="${command}"`,
+      )
+    }
+
+    if (wasRewritten) {
+      args.command = normalized
+      logger?.warn(
+        `[command-normalizer] python→python3 rewritten: session=${input.sessionID} ` +
+          `original="${command}" normalized="${normalized}"`,
+      )
+    }
+  }
+}