pantheon-opencode 1.3.7 → 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.7",
+  "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/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}"`,
+      )
+    }
+  }
+}

package/src/pantheon/context-sandbox.ts

@@ -0,0 +1,273 @@
+/**
+ * Tool Output Sandboxing — Context Window Optimization (v2 P0)
+ *
+ * Truncates oversized tool outputs before they flood the context window.
+ * Pure truncation with metadata — no tiktoken, no LLM summarization (YAGNI).
+ *
+ * Hook: tool.execute.after — intercepts read/grep/glob/webfetch outputs.
+ *
+ * @module pantheon/context-sandbox
+ */
+
+export interface ToolExecuteAfterInput {
+  tool: string
+  sessionID: string
+  callID: string
+  args?: unknown
+}
+
+export interface ToolExecuteAfterOutput {
+  title?: string
+  output: string
+  metadata?: Record<string, unknown>
+}
+
+export type ToolExecuteAfterHandler = (
+  input: ToolExecuteAfterInput,
+  output: ToolExecuteAfterOutput,
+) => Promise<void>
+
+export interface SandboxToolLimits {
+  read: { maxLines: number; keepHead: number; keepTail: number }
+  grep: { maxResults: number; keepTop: number }
+  glob: { maxFiles: number; keepTop: number }
+  webfetch: { maxChars: number; keepHead: number }
+}
+
+export interface ContextSandboxConfig {
+  enabled: boolean
+  limits: SandboxToolLimits
+}
+
+/** Default limits — sensatos, cobrem 80% do problema com ~30 LOC. */
+export const DEFAULT_LIMITS: SandboxToolLimits = {
+  read: { maxLines: 200, keepHead: 50, keepTail: 10 },
+  grep: { maxResults: 20, keepTop: 10 },
+  glob: { maxFiles: 50, keepTop: 20 },
+  webfetch: { maxChars: 5000, keepHead: 2000 },
+}
+
+export const DEFAULT_CONFIG: ContextSandboxConfig = {
+  enabled: true,
+  limits: DEFAULT_LIMITS,
+}
+
+// ─── Pure sandbox functions ──────────────────────────────────────────────
+
+/**
+ * Sandbox truncation for `read` tool output.
+ * Input is expected to be line-numbered read output (e.g. "1: foo").
+ * If lines > maxLines, keep head + marker + tail.
+ */
+export function sandboxRead(output: string, limits = DEFAULT_LIMITS.read): string {
+  const lines = output.split('\n')
+  // trailing empty after final newline is not a real line — drop it for counting
+  const effectiveCount =
+    lines.length > 0 && lines[lines.length - 1] === '' ? lines.length - 1 : lines.length
+  if (effectiveCount <= limits.maxLines) return output
+
+  const head = lines.slice(0, limits.keepHead)
+  const tail =
+    limits.keepTail > 0
+      ? lines.slice(Math.max(limits.keepHead, effectiveCount - limits.keepTail), effectiveCount)
+      : []
+  const hidden = effectiveCount - head.length - tail.length
+  const marker = `[TRUNCATED: ${hidden} lines hidden — showing ${head.length} head + ${tail.length} tail of ${effectiveCount} total lines]`
+
+  // Preserve trailing newline semantics of original if present
+  const hadTrailingNewline = output.endsWith('\n')
+  const parts = [...head, marker, ...tail]
+  let result = parts.join('\n')
+  if (hadTrailingNewline) result += '\n'
+  return result
+}
+
+/**
+ * Sandbox truncation for `grep` tool output.
+ * Each non-empty line is considered a match. Keeps top N, drops tail.
+ */
+export function sandboxGrep(output: string, limits = DEFAULT_LIMITS.grep): string {
+  const lines = output.split('\n')
+  const effectiveCount =
+    lines.length > 0 && lines[lines.length - 1] === '' ? lines.length - 1 : lines.length
+  // Count non-empty? spec says 20 results — treat every line as result for simplicity,
+  // but filter obvious empties: if effective count includes empty trailing, already handled.
+  // Use effectiveCount as result count.
+  if (effectiveCount <= limits.maxResults) return output
+
+  const head = lines.slice(0, limits.keepTop)
+  const hidden = effectiveCount - head.length
+  const marker = `[TRUNCATED: Showing ${head.length} of ${effectiveCount} matches — ${hidden} more hidden. Use more specific pattern.]`
+  const hadTrailingNewline = output.endsWith('\n')
+  let result = [...head, marker].join('\n')
+  if (hadTrailingNewline) result += '\n'
+  return result
+}
+
+/**
+ * Sandbox truncation for `glob` tool output.
+ * Each line is a file path. Keeps top N.
+ */
+export function sandboxGlob(output: string, limits = DEFAULT_LIMITS.glob): string {
+  const lines = output.split('\n')
+  const effectiveCount =
+    lines.length > 0 && lines[lines.length - 1] === '' ? lines.length - 1 : lines.length
+  if (effectiveCount <= limits.maxFiles) return output
+
+  const head = lines.slice(0, limits.keepTop)
+  const hidden = effectiveCount - head.length
+  const marker = `[TRUNCATED: showing ${head.length} of ${effectiveCount} files — ${hidden} more hidden]`
+  const hadTrailingNewline = output.endsWith('\n')
+  let result = [...head, marker].join('\n')
+  if (hadTrailingNewline) result += '\n'
+  return result
+}
+
+/**
+ * Sandbox truncation for `webfetch` tool output.
+ * Character-based: keep head chars, drop rest.
+ */
+export function sandboxWebfetch(output: string, limits = DEFAULT_LIMITS.webfetch): string {
+  if (output.length <= limits.maxChars) return output
+  const head = output.slice(0, limits.keepHead)
+  const hidden = output.length - head.length
+  const marker = `\n[TRUNCATED: Content truncated — showing first ${head.length} of ${output.length} chars, ${hidden} chars hidden]\n`
+  return head + marker
+}
+
+/**
+ * Dispatch sandbox truncation by tool name. Pure function — no I/O.
+ * Unknown tools pass through unchanged.
+ */
+export function sandboxOutput(
+  tool: string,
+  output: string,
+  limits: SandboxToolLimits = DEFAULT_LIMITS,
+): string {
+  if (typeof output !== 'string' || output.length === 0) return output
+  const normalized = tool.trim().toLowerCase()
+  switch (normalized) {
+    case 'read':
+      return sandboxRead(output, limits.read)
+    case 'grep':
+      return sandboxGrep(output, limits.grep)
+    case 'glob':
+      return sandboxGlob(output, limits.glob)
+    case 'webfetch':
+    case 'fetch':
+    case 'web_fetch':
+      return sandboxWebfetch(output, limits.webfetch)
+    default:
+      return output
+  }
+}
+
+// ─── Plugin hook factory ───────────────────────────────────────────────
+
+/**
+ * Resolve sandbox config from opencode.json `context_sandbox` block.
+ * Fail-open: any missing/invalid field falls back to defaults.
+ */
+export function resolveSandboxConfig(raw?: unknown): ContextSandboxConfig {
+  if (raw === null || raw === undefined || typeof raw !== 'object')
+    return { ...DEFAULT_CONFIG, limits: { ...DEFAULT_LIMITS } }
+  const obj = raw as Record<string, unknown>
+  const enabled = typeof obj.enabled === 'boolean' ? obj.enabled : true
+  const limitsRaw = obj.limits as Record<string, unknown> | undefined
+
+  const limits: SandboxToolLimits = {
+    read: {
+      maxLines:
+        typeof limitsRaw?.read === 'object' &&
+        limitsRaw.read !== null &&
+        typeof (limitsRaw.read as Record<string, unknown>).maxLines === 'number'
+          ? ((limitsRaw.read as Record<string, unknown>).maxLines as number)
+          : DEFAULT_LIMITS.read.maxLines,
+      keepHead:
+        typeof limitsRaw?.read === 'object' &&
+        limitsRaw.read !== null &&
+        typeof (limitsRaw.read as Record<string, unknown>).keepHead === 'number'
+          ? ((limitsRaw.read as Record<string, unknown>).keepHead as number)
+          : DEFAULT_LIMITS.read.keepHead,
+      keepTail:
+        typeof limitsRaw?.read === 'object' &&
+        limitsRaw.read !== null &&
+        typeof (limitsRaw.read as Record<string, unknown>).keepTail === 'number'
+          ? ((limitsRaw.read as Record<string, unknown>).keepTail as number)
+          : DEFAULT_LIMITS.read.keepTail,
+    },
+    grep: {
+      maxResults:
+        typeof limitsRaw?.grep === 'object' &&
+        limitsRaw.grep !== null &&
+        typeof (limitsRaw.grep as Record<string, unknown>).maxResults === 'number'
+          ? ((limitsRaw.grep as Record<string, unknown>).maxResults as number)
+          : DEFAULT_LIMITS.grep.maxResults,
+      keepTop:
+        typeof limitsRaw?.grep === 'object' &&
+        limitsRaw.grep !== null &&
+        typeof (limitsRaw.grep as Record<string, unknown>).keepTop === 'number'
+          ? ((limitsRaw.grep as Record<string, unknown>).keepTop as number)
+          : DEFAULT_LIMITS.grep.keepTop,
+    },
+    glob: {
+      maxFiles:
+        typeof limitsRaw?.glob === 'object' &&
+        limitsRaw.glob !== null &&
+        typeof (limitsRaw.glob as Record<string, unknown>).maxFiles === 'number'
+          ? ((limitsRaw.glob as Record<string, unknown>).maxFiles as number)
+          : DEFAULT_LIMITS.glob.maxFiles,
+      keepTop:
+        typeof limitsRaw?.glob === 'object' &&
+        limitsRaw.glob !== null &&
+        typeof (limitsRaw.glob as Record<string, unknown>).keepTop === 'number'
+          ? ((limitsRaw.glob as Record<string, unknown>).keepTop as number)
+          : DEFAULT_LIMITS.glob.keepTop,
+    },
+    webfetch: {
+      maxChars:
+        typeof limitsRaw?.webfetch === 'object' &&
+        limitsRaw.webfetch !== null &&
+        typeof (limitsRaw.webfetch as Record<string, unknown>).maxChars === 'number'
+          ? ((limitsRaw.webfetch as Record<string, unknown>).maxChars as number)
+          : DEFAULT_LIMITS.webfetch.maxChars,
+      keepHead:
+        typeof limitsRaw?.webfetch === 'object' &&
+        limitsRaw.webfetch !== null &&
+        typeof (limitsRaw.webfetch as Record<string, unknown>).keepHead === 'number'
+          ? ((limitsRaw.webfetch as Record<string, unknown>).keepHead as number)
+          : DEFAULT_LIMITS.webfetch.keepHead,
+    },
+  }
+  return { enabled, limits }
+}
+
+/**
+ * Create the `tool.execute.after` handler that sandboxes oversized outputs.
+ * The handler mutates `output.output` in-place and tags metadata when truncated.
+ * Fail-open: never throws.
+ */
+export function createContextSandbox(
+  config: ContextSandboxConfig = DEFAULT_CONFIG,
+): ToolExecuteAfterHandler {
+  // Capture mutable reference — caller (plugin config hook) may update limits live
+  const cfgRef = config
+  return async (input: ToolExecuteAfterInput, output: ToolExecuteAfterOutput): Promise<void> => {
+    try {
+      if (!cfgRef.enabled) return
+      if (typeof output.output !== 'string') return
+      const before = output.output
+      const after = sandboxOutput(input.tool, before, cfgRef.limits)
+      if (after !== before) {
+        output.output = after
+        output.metadata = {
+          ...(output.metadata ?? {}),
+          truncated: true,
+          sandbox: input.tool.toLowerCase(),
+        }
+      }
+    } catch {
+      // never break the tool result
+    }
+  }
+}

package/src/plugin.ts

@@ -1,9 +1,17 @@
-import type { Plugin, PluginInput } from '@opencode-ai/plugin'
-import type { PluginConfig } from 'opencode'
 import { existsSync } from 'node:fs'
 import { join } from 'node:path'
+import type { Plugin, PluginInput } from '@opencode-ai/plugin'
+import type { PluginConfig } from 'opencode'
 import { BackgroundJobBoard } from './pantheon/background-job-board.ts'
+import { createCommandNormalizer } from './pantheon/command-normalizer.ts'
 import { reassertAfterCompaction } from './pantheon/compaction-assert.ts'
+import {
+  type ContextSandboxConfig,
+  createContextSandbox,
+  resolveSandboxConfig,
+  DEFAULT_CONFIG as SANDBOX_DEFAULT_CONFIG,
+  DEFAULT_LIMITS as SANDBOX_DEFAULT_LIMITS,
+} from './pantheon/context-sandbox.ts'
 import { createCostCommand } from './pantheon/cost-command.ts'
 import {
   collectRootSessionIDs,
@@ -131,6 +139,13 @@ const enforcementGuard = createEnforcementGuard({
   },
 })
 
+// Fase 1 (command-normalizer): deterministic `python` → `python3` rewrite for
+// `bash` commands (PEP 394 — Ubuntu 20.04+ has no bare `python`). Unlike the
+// enforcement guard above (which THROWS to deny), this guard REWRITES the
+// command in place and lets it run. Logs every rewrite + `python -c` warning
+// to the shared hooks.log for @nyx frequency measurement.
+const commandNormalizer = createCommandNormalizer({ logger: log })
+
 // Mirrors routing.yml background_delegation.max_compaction_items.
 const COMPACTION_MAX_ITEMS = 10
 
@@ -436,6 +451,24 @@ const plugin: Plugin = async (input: PluginInput) => {
   const hashlineEdit = createHashlineEditTool()
   const readEnhancer = createReadEnhancer()
 
+  // Context Window Optimization (v2 P0) — tool output sandboxing
+  // Pure truncation hook: read/grep/glob/webfetch → head + [TRUNCATED] + tail
+  // Fail-open: never throws, disabled via opencode.json context_sandbox.enabled
+  const sandboxConfig: ContextSandboxConfig = {
+    enabled: SANDBOX_DEFAULT_CONFIG.enabled,
+    limits: {
+      read: { ...SANDBOX_DEFAULT_LIMITS.read },
+      grep: { ...SANDBOX_DEFAULT_LIMITS.grep },
+      glob: { ...SANDBOX_DEFAULT_LIMITS.glob },
+      webfetch: { ...SANDBOX_DEFAULT_LIMITS.webfetch },
+    },
+  }
+  const sandboxHandler = createContextSandbox(sandboxConfig)
+  const combinedAfter: typeof readEnhancer = async (input, output) => {
+    await sandboxHandler(input, output)
+    await readEnhancer(input, output)
+  }
+
   // Wave 4 (PR #46): /cost — delegation cost + token visibility. Reads
   // opencode.db read-only (node:sqlite, falls back to scripts/cost.mjs).
   // Fully wired (unlike dispatch-guard, which is manual-orchestration-only
@@ -452,6 +485,15 @@ const plugin: Plugin = async (input: PluginInput) => {
       // WITHOUT a parentID is a root. Fail-open: a failed/throttled list
       // leaves the set untouched (delegation.ts treats unknown sessions as
       // roots), and config setup must never wait for the session API.
+      // Context sandbox config — opencode.json → context_sandbox: {enabled, limits}
+      try {
+        const raw = (config as unknown as Record<string, unknown>).context_sandbox
+        const resolved = resolveSandboxConfig(raw)
+        sandboxConfig.enabled = resolved.enabled
+        sandboxConfig.limits = resolved.limits
+      } catch {
+        // fail-open: keep defaults
+      }
       seedRootSessionsInBackground(input)
       config.agentsPath = config.agentsPath ?? []
       config.agentsPath.push(new URL('./agents', import.meta.url).pathname)
@@ -578,13 +620,16 @@ const plugin: Plugin = async (input: PluginInput) => {
       // no-ops for non-matching sessions/tools.
       zeusReadGuard(input.tool, output?.args, sessionAgents.get(input.sessionID))
       await enforcementGuard(input, output)
+      await commandNormalizer(input, output)
       await todoPreserver.beforeTodoWrite(input, output)
     },
-    // Wave 2 (PR #46): augment `read` output with hashline tags. Additive —
+    // Wave 2 (PR #46) + Context Sandbox (v2 P0): sandbox truncates oversized
+    // outputs BEFORE hashline tags (so tags remain stable on kept lines).
+    // Additive —
     // pantheon-hooks.ts (a separate plugin instance) owns its own
     // tool.execute.after, so there is no key collision. Non-read tools pass
     // through untouched.
-    'tool.execute.after': readEnhancer,
+    'tool.execute.after': combinedAfter,
     // Phase 4 + release-134 Phase 2: keep the session's working state across
     // compaction — preservation directive, active goals (<mission_context>),
     // pending todos (<todo_context>), and in-flight background delegations

package/src/plugins/tui/dist/tui.d.ts

@@ -11,7 +11,7 @@ type DelegationEntry = {
   taskID?: string;
   /** Agent name, e.g. "apollo". */
   agent: string;
-  state: 'running' | 'completed' | 'error' | 'startup_failed' | 'startup_unknown' | 'cancelled';
+  state: 'running' | 'completed' | 'error' | 'startup_failed' | 'startup_unknown' | 'cancelled' | 'stale-running';
   /** Epoch ms of the `Started` header. */
   startedAt: number;
   /** Epoch ms of the `Finalized` header — null while still running. */
@@ -77,7 +77,22 @@ declare function compareDelegationEntries(a: DelegationEntry, b: DelegationEntry
  *  recent terminal reports (capped). Pure — so the history-only panel (no
  *  sessionID) is testable without the TUI runtime. The header count uses the
  *  same "running + recentes" list. */
-declare function visibleDelegationList(all: readonly DelegationEntry[], maxTerminal?: number): DelegationEntry[];
+declare function visibleDelegationList(all: readonly DelegationEntry[], maxTerminal?: number, now?: number, staleThresholdMs?: number): DelegationEntry[];
+/** Default stale-running threshold: 30 minutes. */
+declare const STALE_RUNNING_THRESHOLD_MS: number;
+/** Idle silence window: if no updatedAt change in this window, the entry is
+ *  considered stale. Combined with the stale-running threshold to produce the
+ *  display-only `stale-running` state. */
+declare const IDLE_SILENCE_MS: number;
+/**
+ * Mark a running entry as `stale-running` if it has been running longer than
+ * the threshold AND has no recent activity (no `updatedAt` change in the last
+ * `IDLE_SILENCE_MS`). This is DISPLAY-ONLY — the board state is unchanged.
+ *
+ * A `stale-running` entry renders with a warning indicator but the underlying
+ * delegation is still treated as running by the backend.
+ */
+declare function markStaleIfRunning(entry: DelegationEntry, now: number, thresholdMs?: number): DelegationEntry;
 /** Compact elapsed-time label: "5m 12s", "1h 30m", "2d 4h" — ticks every
  *  second for running jobs. */
 declare function fmtElapsed(ms: number): string;
@@ -306,5 +321,5 @@ declare const plugin: TuiPluginModule & {
   id: string;
 };
 //#endregion
-export { ChildDelegationLike, DelegationActivity, DelegationEntry, DelegationToolPart, LiveDelegationEntry, LiveDelegationStore, ParsedDelegationToolPart, TuiSessionSources, buildChildrenPath, childStatusToState, childrenToDelegationEntries, collectDelegationToolParts, compareDelegationEntries, plugin as default, delegationActivity, delegationActivityLabel, delegationElapsed, delegationSpinnerFrame, delegationTag, fmtElapsed, isValidSessionId, mergeChildDelegationSources, mergeDelegationSources, navigateToDelegationSession, panelLogDir, parseDelegationMarkdown, parseDelegationToolPart, readAllDelegationEntries, readDelegationEntries, reduceDelegationToolPart, removeDelegationEntry, resolveCurrentSessionID, resolveDelegationsDir, safeSessionPath, seedLiveDelegationMap, toDelegationEntry, tuiLogPath, visibleDelegationList };
+export { ChildDelegationLike, DelegationActivity, DelegationEntry, DelegationToolPart, IDLE_SILENCE_MS, LiveDelegationEntry, LiveDelegationStore, ParsedDelegationToolPart, STALE_RUNNING_THRESHOLD_MS, TuiSessionSources, buildChildrenPath, childStatusToState, childrenToDelegationEntries, collectDelegationToolParts, compareDelegationEntries, plugin as default, delegationActivity, delegationActivityLabel, delegationElapsed, delegationSpinnerFrame, delegationTag, fmtElapsed, isValidSessionId, markStaleIfRunning, mergeChildDelegationSources, mergeDelegationSources, navigateToDelegationSession, panelLogDir, parseDelegationMarkdown, parseDelegationToolPart, readAllDelegationEntries, readDelegationEntries, reduceDelegationToolPart, removeDelegationEntry, resolveCurrentSessionID, resolveDelegationsDir, safeSessionPath, seedLiveDelegationMap, toDelegationEntry, tuiLogPath, visibleDelegationList };
 //# sourceMappingURL=tui.d.ts.map

package/src/plugins/tui/dist/tui.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tui.d.ts","names":[],"sources":["../src/index.tsx"],"mappings":";;KAq6BY;;EAEV;;EAEA;;;;EAIA;;EAEA;EACA;;EAEA;;EAEA;EACA;EACA;;EAEA;;;;EAIA;;;;;;;;;;;iBAsBc,wBACd,aACA,oBACA,qBACC;;;;;;iBAgHmB,sBAAsB,cAAc,QAAQ;;;;;;;;iBAwC5C,yBAAyB,eAAe,QAAQ;;;;;;;;iBAWtD,sBACd;EAAS;EAAoB;eAC7B;;;;;;iBAYc,YAAY;;;iBAMZ,WAAW;;;;iBAOX,yBAAyB,GAAG,iBAAiB,GAAG;;;;;iBAWhD,sBACd,cAAc,mBACd,uBACC;;;iBAQa,WAAW;;;iBAcX,kBAAkB,OAAO,iBAAiB;;;KAO9C;iBAQI,mBAAmB,OAAO,kBAAkB;iBAc5C,wBAAwB,OAAO;;iBAoB/B,uBAAuB;;;;;;;iBAWvB,4BACd,mBAAmB,mBACnB,eAAe,wBACd;;KAmFS;EACV;EACA;EACA;EACA;EACA;EACA;IACE;IACA,QAAQ;IACR;IACA;IACA;MAAS;MAAgB;;;;;KAKjB;;EAEV;;EAEA;;EAEA;EACA;;EAEA;EACA;;EAEA;;EAEA;EACA;EACA;EACA;;EAEA;;;KAIU;EACV;EACA;EACA;EACA;;EAEA;EACA;EACA;EACA;EACA;EACA;EACA;;;;;iBAac,wBACd,MAAM,oBACN,eACC;;;iBA+Ea,yBACd,KAAK,YAAY,sBACjB,MAAM,oBACN;;;iBA+Fc,sBACd,KAAK,YAAY,sBACjB;;;;;;iBAiBc,2BACd;EAAqB;EAAa;iBAClC,YAAY,uDACX;;;;;iBA2Ba,sBACd,KAAK,YAAY,sBACjB,gBAAgB,sBAChB;;;iBAWc,kBAAkB,MAAM,sBAAsB;;;;;;iBAqB9C,uBACd,eAAe,uBACf,aAAa,oBACZ;;;;;;;;;iBA8Da,iBAAiB,cAAc;;;;KAOnC;;EAEV;EACA;;IAEE;MAAU;;;IAEV;MAAU;QAAY;QAAe,SAAS;;;;;;;;;;iBASlC,wBAAwB,SAAS;;;;;;;;iBAmBjC,gBAAgB;EAAgB;IAAQ;;;;;;;iBASxC,kBAAkB;EAAkC;IAAQ;;;;KAKhE;;EAEV;;EAEA;;;EAGA;;;EAGA;EACA;IACE;IACA;;;;;;;iBAQY,mBAAmB;;;;;iBASnB,cAAc,OAAO;;;;;;;;;;;;;;iBAiBrB,4BACd,mBAAmB,mCACnB,aAAa,mBACb,eACC;;;;;;iBAwCa,4BACd;EAAS,YAAY,cAAc,SAAS;eAC5C;;;;;KA8KU;EACV,KAAK,YAAY;;EAEjB;;EAEA;;cAucI,QAAQ;EAAoB"}
+{"version":3,"file":"tui.d.ts","names":[],"sources":["../src/index.tsx"],"mappings":";;KAy6BY;;EAEV;;EAEA;;;;EAIA;;EAEA;EACA;;EASA;;EAEA;EACA;EACA;;EAEA;;;;EAIA;;;;;;;;;;;iBAsBc,wBACd,aACA,oBACA,qBACC;;;;;;iBAkHmB,sBAAsB,cAAc,QAAQ;;;;;;;;iBAwC5C,yBAAyB,eAAe,QAAQ;;;;;;;;iBAWtD,sBACd;EAAS;EAAoB;eAC7B;;;;;;iBAYc,YAAY;;;iBAMZ,WAAW;;;;iBAOX,yBAAyB,GAAG,iBAAiB,GAAG;;;;;iBAWhD,sBACd,cAAc,mBACd,sBACA,cACA,4BACC;;cASU;;;;cAKA;;;;;;;;;iBAUG,mBACd,OAAO,iBACP,aACA,uBACC;;;iBAWa,WAAW;;;iBAcX,kBAAkB,OAAO,iBAAiB;;;KAQ9C;iBAQI,mBAAmB,OAAO,kBAAkB;iBAc5C,wBAAwB,OAAO;;iBAoB/B,uBAAuB;;;;;;;iBAWvB,4BACd,mBAAmB,mBACnB,eAAe,wBACd;;KAmFS;EACV;EACA;EACA;EACA;EACA;EACA;IACE;IACA,QAAQ;IACR;IACA;IACA;MAAS;MAAgB;;;;;KAKjB;;EAEV;;EAEA;;EAEA;EACA;;EAEA;EACA;;EAEA;;EAEA;EACA;EACA;EACA;;EAEA;;;KAIU;EACV;EACA;EACA;EACA;;EAEA;EACA;EACA;EACA;EACA;EACA;EACA;;;;;iBAac,wBACd,MAAM,oBACN,eACC;;;iBA+Ea,yBACd,KAAK,YAAY,sBACjB,MAAM,oBACN;;;iBA+Fc,sBACd,KAAK,YAAY,sBACjB;;;;;;iBAiBc,2BACd;EAAqB;EAAa;iBAClC,YAAY,uDACX;;;;;iBA2Ba,sBACd,KAAK,YAAY,sBACjB,gBAAgB,sBAChB;;;iBAWc,kBAAkB,MAAM,sBAAsB;;;;;;iBAqB9C,uBACd,eAAe,uBACf,aAAa,oBACZ;;;;;;;;;iBA8Da,iBAAiB,cAAc;;;;KAOnC;;EAEV;EACA;;IAEE;MAAU;;;IAEV;MAAU;QAAY;QAAe,SAAS;;;;;;;;;;iBASlC,wBAAwB,SAAS;;;;;;;;iBAmBjC,gBAAgB;EAAgB;IAAQ;;;;;;;iBASxC,kBAAkB;EAAkC;IAAQ;;;;KAKhE;;EAEV;;EAEA;;;EAGA;;;EAGA;EACA;IACE;IACA;;;;;;;iBAQY,mBAAmB;;;;;iBASnB,cAAc,OAAO;;;;;;;;;;;;;;iBAiBrB,4BACd,mBAAmB,mCACnB,aAAa,mBACb,eACC;;;;;;iBA0Ca,4BACd;EAAS,YAAY,cAAc,SAAS;eAC5C;;;;;KAiLU;EACV,KAAK,YAAY;;EAEjB;;EAEA;;cAucI,QAAQ;EAAoB"}

package/src/plugins/tui/dist/tui.js

@@ -120,8 +120,14 @@ async function resolvePresetForTui(env, cwd) {
 }
 async function detectVersion(api) {
 	try {
-		const match = (await readFile(fileURLToPath(new URL("../../../../package.json", import.meta.url)), "utf8")).match(/"version":\s*"([^"]+)"/);
-		if (match?.[1]) return match[1];
+		const pkgContent = await readFile(fileURLToPath(new URL("../../package.json", import.meta.url)), "utf8");
+		const pkg = JSON.parse(pkgContent);
+		if (pkg.version) return pkg.version;
+	} catch {}
+	try {
+		const pkgContent = await readFile(fileURLToPath(new URL("../../../../package.json", import.meta.url)), "utf8");
+		const pkg = JSON.parse(pkgContent);
+		if (pkg.version) return pkg.version;
 	} catch {}
 	try {
 		const wt = api.state.path?.worktree ?? "";
@@ -765,7 +771,8 @@ function parseDelegationMarkdown(raw, fileAlias, sessionID = "") {
 	const startedAt = started !== void 0 ? Date.parse(started) : NaN;
 	if (agent === void 0 || state === void 0 || Number.isNaN(startedAt)) return null;
 	const normalized = state.toLowerCase();
-	if (normalized !== "running" && normalized !== "completed" && normalized !== "error" && normalized !== "startup_failed" && normalized !== "startup_unknown" && normalized !== "cancelled") return null;
+	if (normalized === "running") return null;
+	if (normalized !== "completed" && normalized !== "error" && normalized !== "startup_failed" && normalized !== "startup_unknown" && normalized !== "cancelled") return null;
 	const finalizedAt = finalized !== void 0 ? Date.parse(finalized) : NaN;
 	return {
 		alias: title ?? (fileAlias !== void 0 ? stripMdSuffix(fileAlias) : "unknown"),
@@ -861,8 +868,8 @@ function tuiLogPath(projectRoot) {
 *  falling back to startedAt, descending). Shared by the md reader and
 *  mergeDelegationSources. */
 function compareDelegationEntries(a, b) {
-	const aRun = a.state === "running" ? 1 : 0;
-	const bRun = b.state === "running" ? 1 : 0;
+	const aRun = a.state === "running" || a.state === "stale-running" ? 1 : 0;
+	const bRun = b.state === "running" || b.state === "stale-running" ? 1 : 0;
 	if (aRun !== bRun) return bRun - aRun;
 	return (b.updatedAt ?? b.startedAt) - (a.updatedAt ?? a.startedAt);
 }
@@ -870,11 +877,34 @@ function compareDelegationEntries(a, b) {
 *  recent terminal reports (capped). Pure — so the history-only panel (no
 *  sessionID) is testable without the TUI runtime. The header count uses the
 *  same "running + recentes" list. */
-function visibleDelegationList(all, maxTerminal = 8) {
-	const running = all.filter((d) => d.state === "running");
+function visibleDelegationList(all, maxTerminal = 8, now = Date.now(), staleThresholdMs = 1800 * 1e3) {
+	const running = all.filter((d) => d.state === "running").map((d) => markStaleIfRunning(d, now, staleThresholdMs));
 	const terminal = all.filter((d) => d.state !== "running").slice(0, maxTerminal);
 	return [...running, ...terminal];
 }
+/** Default stale-running threshold: 30 minutes. */
+const STALE_RUNNING_THRESHOLD_MS = 1800 * 1e3;
+/** Idle silence window: if no updatedAt change in this window, the entry is
+*  considered stale. Combined with the stale-running threshold to produce the
+*  display-only `stale-running` state. */
+const IDLE_SILENCE_MS = 60 * 1e3;
+/**
+* Mark a running entry as `stale-running` if it has been running longer than
+* the threshold AND has no recent activity (no `updatedAt` change in the last
+* `IDLE_SILENCE_MS`). This is DISPLAY-ONLY — the board state is unchanged.
+*
+* A `stale-running` entry renders with a warning indicator but the underlying
+* delegation is still treated as running by the backend.
+*/
+function markStaleIfRunning(entry, now, thresholdMs = STALE_RUNNING_THRESHOLD_MS) {
+	if (entry.state !== "running") return entry;
+	if (now - entry.startedAt < thresholdMs) return entry;
+	if (entry.updatedAt !== null && now - entry.updatedAt < 6e4) return entry;
+	return {
+		...entry,
+		state: "stale-running"
+	};
+}
 /** Compact elapsed-time label: "5m 12s", "1h 30m", "2d 4h" — ticks every
 *  second for running jobs. */
 function fmtElapsed(ms) {
@@ -891,7 +921,7 @@ function fmtElapsed(ms) {
 /** Elapsed label for one entry: running → ticks `now - startedAt`, terminal
 *  → fixed `updatedAt - startedAt` (em dash when no finalized timestamp). */
 function delegationElapsed(entry, now) {
-	if (entry.state === "running") return fmtElapsed(now - entry.startedAt);
+	if (entry.state === "running" || entry.state === "stale-running") return fmtElapsed(now - entry.startedAt);
 	return entry.updatedAt !== null ? fmtElapsed(entry.updatedAt - entry.startedAt) : "—";
 }
 /** The activity labels shown by the animated row. Keeping this pure makes the
@@ -1318,7 +1348,7 @@ function childrenToDelegationEntries(children, md, now = Date.now()) {
 			agent: mdEntry?.agent ?? child.agent ?? "agent",
 			state,
 			startedAt: mdEntry?.startedAt ?? child.time?.created ?? now,
-			updatedAt: mdEntry?.updatedAt ?? (state === "running" ? null : child.time?.updated ?? null),
+			updatedAt: mdEntry?.updatedAt ?? (state === "running" || state === "stale-running" ? null : child.time?.updated ?? null),
 			timedOut: mdEntry?.timedOut ?? false,
 			description: mdEntry !== void 0 && mdEntry.description !== "" ? mdEntry.description : child.title ?? "",
 			source: mdEntry !== void 0 ? "md" : "children-only"
@@ -1399,6 +1429,7 @@ function DelegationRow(props) {
 		const t = theme();
 		switch (props.job.state) {
 			case "running": return t.warning;
+			case "stale-running": return t.error;
 			case "completed": return t.success;
 			case "error": return t.error;
 			default: return t.textMuted;
@@ -1406,6 +1437,7 @@ function DelegationRow(props) {
 	});
 	const marker = createMemo(() => {
 		if (props.job.state === "running") return `${delegationSpinnerFrame(props.animationNow)} `;
+		if (props.job.state === "stale-running") return "⚠ ";
 		switch (props.job.state) {
 			case "completed": return "✓ ";
 			case "error": return "✕ ";
@@ -1842,6 +1874,6 @@ const plugin = {
 	tui
 };
 //#endregion
-export { buildChildrenPath, childStatusToState, childrenToDelegationEntries, collectDelegationToolParts, compareDelegationEntries, plugin as default, delegationActivity, delegationActivityLabel, delegationElapsed, delegationSpinnerFrame, delegationTag, fmtElapsed, isValidSessionId, mergeChildDelegationSources, mergeDelegationSources, navigateToDelegationSession, panelLogDir, parseDelegationMarkdown, parseDelegationToolPart, readAllDelegationEntries, readDelegationEntries, reduceDelegationToolPart, removeDelegationEntry, resolveCurrentSessionID, resolveDelegationsDir, safeSessionPath, seedLiveDelegationMap, toDelegationEntry, tuiLogPath, visibleDelegationList };
+export { IDLE_SILENCE_MS, STALE_RUNNING_THRESHOLD_MS, buildChildrenPath, childStatusToState, childrenToDelegationEntries, collectDelegationToolParts, compareDelegationEntries, plugin as default, delegationActivity, delegationActivityLabel, delegationElapsed, delegationSpinnerFrame, delegationTag, fmtElapsed, isValidSessionId, markStaleIfRunning, mergeChildDelegationSources, mergeDelegationSources, navigateToDelegationSession, panelLogDir, parseDelegationMarkdown, parseDelegationToolPart, readAllDelegationEntries, readDelegationEntries, reduceDelegationToolPart, removeDelegationEntry, resolveCurrentSessionID, resolveDelegationsDir, safeSessionPath, seedLiveDelegationMap, toDelegationEntry, tuiLogPath, visibleDelegationList };
 
 //# sourceMappingURL=tui.js.map

package/src/plugins/tui/dist/tui.tsx

@@ -154,25 +154,29 @@ async function resolvePresetForTui(
  * Se falhar, retorna null e a View omite a versão.
  *
  * Try order:
+ *   0a. pantheon-tui/package.json (installed: dist/tui.js → 2 níveis)
+ *   0b. pantheon/package.json (dev: src/plugins/tui/dist/tui.tsx → 4 níveis)
  *   1. api.client.file.read package.json
  *   2. git describe --tags
  *   3. opencode --version
  *   4. null                                                      */
 
 async function detectVersion(api: TuiPluginApi): Promise<string | null> {
-  // Try 0: package.json do PACOTE PANTHEON instalado. O TUI é carregado de
-  // <pacote>/src/plugins/tui/dist/tui.tsx (fix #32 garante esse path) →
-  // 4 níveis acima (dist → tui → plugins → src → raiz) está o package.json
-  // do pacote. Funciona em QUALQUER cwd (ex: sandbox sem package.json/git) e
-  // também em dev (source no repo). Se falhar, cai para os tries abaixo.
+  // Try 0a: installed location (2 levels: dist/tui.js → pantheon-tui/package.json)
+  try {
+    const pkgUrl = new URL('../../package.json', import.meta.url)
+    const pkgContent = await readFile(fileURLToPath(pkgUrl), 'utf8')
+    const pkg = JSON.parse(pkgContent)
+    if (pkg.version) return pkg.version
+  } catch {}
+
+  // Try 0b: dev location (4 levels: src/plugins/tui/dist/tui.tsx → package.json)
   try {
     const pkgUrl = new URL('../../../../package.json', import.meta.url)
     const pkgContent = await readFile(fileURLToPath(pkgUrl), 'utf8')
-    const match = pkgContent.match(/"version":\s*"([^"]+)"/)
-    if (match?.[1]) return match[1]
-  } catch {
-    /* fall through */
-  }
+    const pkg = JSON.parse(pkgContent)
+    if (pkg.version) return pkg.version
+  } catch {}
 
   // Try 1: package.json do projeto (via worktree path)
   try {
@@ -942,7 +946,14 @@ export type DelegationEntry = {
   taskID?: string
   /** Agent name, e.g. "apollo". */
   agent: string
-  state: 'running' | 'completed' | 'error' | 'startup_failed' | 'startup_unknown' | 'cancelled'
+  state:
+    | 'running'
+    | 'completed'
+    | 'error'
+    | 'startup_failed'
+    | 'startup_unknown'
+    | 'cancelled'
+    | 'stale-running'
   /** Epoch ms of the `Started` header. */
   startedAt: number
   /** Epoch ms of the `Finalized` header — null while still running. */
@@ -1048,8 +1059,10 @@ export function parseDelegationMarkdown(
   const startedAt = started !== undefined ? Date.parse(started) : NaN
   if (agent === undefined || state === undefined || Number.isNaN(startedAt)) return null
   const normalized = state.toLowerCase()
+  // Running state should only come from live channels, never from persisted
+  // reports. A stale "running" MD artifact contaminates the panel — skip it.
+  if (normalized === 'running') return null
   if (
-    normalized !== 'running' &&
     normalized !== 'completed' &&
     normalized !== 'error' &&
     normalized !== 'startup_failed' &&
@@ -1171,8 +1184,8 @@ export function tuiLogPath(projectRoot: string): string {
  *  falling back to startedAt, descending). Shared by the md reader and
  *  mergeDelegationSources. */
 export function compareDelegationEntries(a: DelegationEntry, b: DelegationEntry): number {
-  const aRun = a.state === 'running' ? 1 : 0
-  const bRun = b.state === 'running' ? 1 : 0
+  const aRun = a.state === 'running' || a.state === 'stale-running' ? 1 : 0
+  const bRun = b.state === 'running' || b.state === 'stale-running' ? 1 : 0
   if (aRun !== bRun) return bRun - aRun
   return (b.updatedAt ?? b.startedAt) - (a.updatedAt ?? a.startedAt)
 }
@@ -1184,12 +1197,45 @@ export function compareDelegationEntries(a: DelegationEntry, b: DelegationEntry)
 export function visibleDelegationList(
   all: readonly DelegationEntry[],
   maxTerminal = 8,
+  now = Date.now(),
+  staleThresholdMs = 30 * 60 * 1000, // 30 minutes
 ): DelegationEntry[] {
-  const running = all.filter((d) => d.state === 'running')
+  const running = all
+    .filter((d) => d.state === 'running')
+    .map((d) => markStaleIfRunning(d, now, staleThresholdMs))
   const terminal = all.filter((d) => d.state !== 'running').slice(0, maxTerminal)
   return [...running, ...terminal]
 }
 
+/** Default stale-running threshold: 30 minutes. */
+export const STALE_RUNNING_THRESHOLD_MS = 30 * 60 * 1000
+
+/** Idle silence window: if no updatedAt change in this window, the entry is
+ *  considered stale. Combined with the stale-running threshold to produce the
+ *  display-only `stale-running` state. */
+export const IDLE_SILENCE_MS = 60 * 1000
+
+/**
+ * Mark a running entry as `stale-running` if it has been running longer than
+ * the threshold AND has no recent activity (no `updatedAt` change in the last
+ * `IDLE_SILENCE_MS`). This is DISPLAY-ONLY — the board state is unchanged.
+ *
+ * A `stale-running` entry renders with a warning indicator but the underlying
+ * delegation is still treated as running by the backend.
+ */
+export function markStaleIfRunning(
+  entry: DelegationEntry,
+  now: number,
+  thresholdMs = STALE_RUNNING_THRESHOLD_MS,
+): DelegationEntry {
+  if (entry.state !== 'running') return entry
+  const elapsed = now - entry.startedAt
+  if (elapsed < thresholdMs) return entry
+  // If updatedAt exists and is recent, entry is still active — not stale.
+  if (entry.updatedAt !== null && now - entry.updatedAt < IDLE_SILENCE_MS) return entry
+  return { ...entry, state: 'stale-running' as const }
+}
+
 /** Compact elapsed-time label: "5m 12s", "1h 30m", "2d 4h" — ticks every
  *  second for running jobs. */
 export function fmtElapsed(ms: number): string {
@@ -1207,7 +1253,8 @@ export function fmtElapsed(ms: number): string {
 /** Elapsed label for one entry: running → ticks `now - startedAt`, terminal
  *  → fixed `updatedAt - startedAt` (em dash when no finalized timestamp). */
 export function delegationElapsed(entry: DelegationEntry, now: number): string {
-  if (entry.state === 'running') return fmtElapsed(now - entry.startedAt)
+  if (entry.state === 'running' || entry.state === 'stale-running')
+    return fmtElapsed(now - entry.startedAt)
   return entry.updatedAt !== null ? fmtElapsed(entry.updatedAt - entry.startedAt) : '\u2014'
 }
 
@@ -1874,7 +1921,9 @@ export function childrenToDelegationEntries(
       agent: mdEntry?.agent ?? child.agent ?? 'agent',
       state,
       startedAt: mdEntry?.startedAt ?? child.time?.created ?? now,
-      updatedAt: mdEntry?.updatedAt ?? (state === 'running' ? null : (child.time?.updated ?? null)),
+      updatedAt:
+        mdEntry?.updatedAt ??
+        (state === 'running' || state === 'stale-running' ? null : (child.time?.updated ?? null)),
       timedOut: mdEntry?.timedOut ?? false,
       description:
         mdEntry !== undefined && mdEntry.description !== ''
@@ -2008,6 +2057,8 @@ function DelegationRow(props: {
     switch (props.job.state) {
       case 'running':
         return t.warning
+      case 'stale-running':
+        return t.error // warning color for stale delegations
       case 'completed':
         return t.success
       case 'error':
@@ -2019,6 +2070,7 @@ function DelegationRow(props: {
 
   const marker = createMemo(() => {
     if (props.job.state === 'running') return `${delegationSpinnerFrame(props.animationNow)} `
+    if (props.job.state === 'stale-running') return '\u26a0 ' // warning triangle
     switch (props.job.state) {
       case 'completed':
         return '\u2713 '

package/src/plugins/tui/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pantheon-tui",
   "type": "module",
-  "version": "1.3.7",
+  "version": "1.4.0",
   "description": "Pantheon TUI plugin — sidebar (version, preset, sessions, real-time delegations) + AI subscription usage gauges incl. OpenCode Go/Zen dollar limits (vendored, MIT)",
   "license": "MIT",
   "exports": {

package/src/plugins/tui/src/index.tsx

@@ -154,25 +154,29 @@ async function resolvePresetForTui(
  * Se falhar, retorna null e a View omite a versão.
  *
  * Try order:
+ *   0a. pantheon-tui/package.json (installed: dist/tui.js → 2 níveis)
+ *   0b. pantheon/package.json (dev: src/plugins/tui/dist/tui.tsx → 4 níveis)
  *   1. api.client.file.read package.json
  *   2. git describe --tags
  *   3. opencode --version
  *   4. null                                                      */
 
 async function detectVersion(api: TuiPluginApi): Promise<string | null> {
-  // Try 0: package.json do PACOTE PANTHEON instalado. O TUI é carregado de
-  // <pacote>/src/plugins/tui/dist/tui.tsx (fix #32 garante esse path) →
-  // 4 níveis acima (dist → tui → plugins → src → raiz) está o package.json
-  // do pacote. Funciona em QUALQUER cwd (ex: sandbox sem package.json/git) e
-  // também em dev (source no repo). Se falhar, cai para os tries abaixo.
+  // Try 0a: installed location (2 levels: dist/tui.js → pantheon-tui/package.json)
+  try {
+    const pkgUrl = new URL('../../package.json', import.meta.url)
+    const pkgContent = await readFile(fileURLToPath(pkgUrl), 'utf8')
+    const pkg = JSON.parse(pkgContent)
+    if (pkg.version) return pkg.version
+  } catch {}
+
+  // Try 0b: dev location (4 levels: src/plugins/tui/dist/tui.tsx → package.json)
   try {
     const pkgUrl = new URL('../../../../package.json', import.meta.url)
     const pkgContent = await readFile(fileURLToPath(pkgUrl), 'utf8')
-    const match = pkgContent.match(/"version":\s*"([^"]+)"/)
-    if (match?.[1]) return match[1]
-  } catch {
-    /* fall through */
-  }
+    const pkg = JSON.parse(pkgContent)
+    if (pkg.version) return pkg.version
+  } catch {}
 
   // Try 1: package.json do projeto (via worktree path)
   try {

package/src/skills/codemap/SKILL.md

@@ -45,3 +45,10 @@ Generate a hierarchical map of the codebase to understand its structure, key mod
 - Focus on structure, not implementation details
 - Max 3 levels deep unless a module is critical
 - Return to agent: "Codemap generated. Send to @athena for planning."
+
+## Integração @apollo
+Antes de glob/grep manual, tente `code_query`:
+- `code_query("MyClass")` → busca FTS5 por entidade
+- Fallback para glob/grep se não indexado ou query vazia
+- `code_index("src/")` para indexação incremental (hash-based, skip se não mudou, force=true para re-index)
+- `code_neighbors(entity_id, depth=2)` para grafo de imports/calls

package/src/skills/context-compression/SKILL.md

@@ -859,3 +859,42 @@ When `01-active-context.md` exceeds 100 lines:
 - `skills/wisdom-accumulation/SKILL.md` — learning extraction
 - `skills/memory-bank/SKILL.md` — memory bank maintenance
 - `instructions/backend-standards.instructions.md` — zeus scoring reference
+
+---
+
+## 19. Tool Output Sandboxing (v2 P0 — Plugin Hook, 0 MCPs)
+
+Camada P0 do Deepwork Plan "Context Window Optimization" (council 2026-08-25, 3/3 High): truncamento simples via `tool.execute.after`, sem tiktoken/LLM em v1 (YAGNI).
+
+**Módulo:** `src/pantheon/context-sandbox.ts` (~120 LOC) — `sandboxOutput(tool, output)` + `createContextSandbox(config)`
+
+**Limites (defaults sensatos, cobrem 80% do problema):**
+
+| Tool | Limite | Ação no excesso |
+|------|--------|-----------------|
+| read | 200 linhas | Primeiras 50 + `[TRUNCATED: N lines]` + últimas 10 |
+| grep | 20 resultados | Top 10 + `[Showing 10 of N matches]` |
+| glob | 50 arquivos | Top 20 + `[showing 20 of N files]` |
+| webfetch | 5000 chars | Primeiros 2000 + `[Content truncated]` |
+
+**Integração (ordem fixa — 0-overhead extra):** `tool.execute.after` → `sandboxHandler` (trunca) → `readEnhancer` (hashline tags). Sandbox sempre antes de compression: outputs já chegam enxutos ao context window; compress-inline (L1) só atua sobre o que sobrou. Custo <1ms por call, 0 novos processos.
+
+**Config opcional em `opencode.json` (fail-open — defaults quando ausente):**
+```json
+{
+  "context_sandbox": {
+    "enabled": true,
+    "limits": {
+      "read": { "maxLines": 200, "keepHead": 50, "keepTail": 10 },
+      "grep": { "maxResults": 20, "keepTop": 10 },
+      "glob": { "maxFiles": 50, "keepTop": 20 },
+      "webfetch": { "maxChars": 5000, "keepHead": 2000 }
+    }
+  }
+}
+```
+Desabilitar: `"enabled": false` (plugin vira no-op, sem throw).
+
+**Session Memory (P1 — já existe, só conectado):** `pantheon-persistence` KV com TTL 4h já fornece `context_save`/`context_get`. Auto-save antes de compactar (`experimental.session.compacting` → `buildCompactionContext` + `todoPreserver.capture`) e recovery pós-compactação (`session.compacted` → `todoPreserver.onCompacted` + `reassertAfterCompaction`) preservam estado sem novo MCP. Testado em `delegation-compaction.test.ts` + `todo-preserve.test.ts`.
+
+**Fora de escopo v1 (YAGNI):** tiktoken counting, LLM summarization, budget dashboard — só se medição provar necessidade.