fix: duplicate atlas-toggle-btn ID from merge conflict (#1336)

Two buttons had id="atlas-toggle-btn" — one incomplete (no closing tag,
no content) and one complete. Removed the incomplete duplicate and fixed
the HTML structure so all buttons have proper opening/closing tags.

agent/__init__.py

@@ -0,0 +1,21 @@
+"""
+agent — Cross-session agent memory and lifecycle hooks.
+
+Provides persistent memory for agents via MemPalace integration.
+Agents recall context at session start and write diary entries at session end.
+
+Modules:
+    memory.py       — AgentMemory class (recall, remember, diary)
+    memory_hooks.py — Session lifecycle hooks (drop-in integration)
+"""
+
+from agent.memory import AgentMemory, MemoryContext, SessionTranscript, create_agent_memory
+from agent.memory_hooks import MemoryHooks
+
+__all__ = [
+    "AgentMemory",
+    "MemoryContext",
+    "MemoryHooks",
+    "SessionTranscript",
+    "create_agent_memory",
+]

agent/memory.py

@@ -0,0 +1,396 @@
+"""
+agent.memory — Cross-session agent memory via MemPalace.
+
+Gives agents persistent memory across sessions. On wake-up, agents
+recall relevant context from past sessions. On session end, they
+write a diary entry summarizing what happened.
+
+Architecture:
+    Session Start  → memory.recall_context() → inject L0/L1 into prompt
+    During Session → memory.remember()        → store important facts
+    Session End    → memory.write_diary()     → summarize session
+
+All operations degrade gracefully — if MemPalace is unavailable,
+the agent continues without memory and logs a warning.
+
+Usage:
+    from agent.memory import AgentMemory
+
+    mem = AgentMemory(agent_name="bezalel", wing="wing_bezalel")
+
+    # Session start — load context
+    context = mem.recall_context("What was I working on last time?")
+
+    # During session — store important decisions
+    mem.remember("Switched CI runner from GitHub Actions to self-hosted", room="forge")
+
+    # Session end — write diary
+    mem.write_diary("Fixed PR #1386, reconciled fleet registry locations")
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import time
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Optional
+
+logger = logging.getLogger("agent.memory")
+
+
+@dataclass
+class MemoryContext:
+    """Context loaded at session start from MemPalace."""
+    relevant_memories: list[dict] = field(default_factory=list)
+    recent_diaries: list[dict] = field(default_factory=list)
+    facts: list[dict] = field(default_factory=list)
+    loaded: bool = False
+    error: Optional[str] = None
+
+    def to_prompt_block(self) -> str:
+        """Format context as a text block to inject into the agent prompt."""
+        if not self.loaded:
+            return ""
+
+        parts = []
+
+        if self.recent_diaries:
+            parts.append("=== Recent Session Summaries ===")
+            for d in self.recent_diaries[:3]:
+                ts = d.get("timestamp", "")
+                text = d.get("text", "")
+                parts.append(f"[{ts}] {text[:500]}")
+
+        if self.facts:
+            parts.append("\n=== Known Facts ===")
+            for f in self.facts[:10]:
+                text = f.get("text", "")
+                parts.append(f"- {text[:200]}")
+
+        if self.relevant_memories:
+            parts.append("\n=== Relevant Past Memories ===")
+            for m in self.relevant_memories[:5]:
+                text = m.get("text", "")
+                score = m.get("score", 0)
+                parts.append(f"[{score:.2f}] {text[:300]}")
+
+        if not parts:
+            return ""
+
+        return "\n".join(parts)
+
+
+@dataclass
+class SessionTranscript:
+    """A running log of the current session for diary writing."""
+    agent_name: str
+    wing: str
+    started_at: str = field(
+        default_factory=lambda: datetime.now(timezone.utc).isoformat()
+    )
+    entries: list[dict] = field(default_factory=list)
+
+    def add_user_turn(self, text: str):
+        self.entries.append({
+            "role": "user",
+            "text": text[:2000],
+            "ts": time.time(),
+        })
+
+    def add_agent_turn(self, text: str):
+        self.entries.append({
+            "role": "agent",
+            "text": text[:2000],
+            "ts": time.time(),
+        })
+
+    def add_tool_call(self, tool: str, args: str, result_summary: str):
+        self.entries.append({
+            "role": "tool",
+            "tool": tool,
+            "args": args[:500],
+            "result": result_summary[:500],
+            "ts": time.time(),
+        })
+
+    def summary(self) -> str:
+        """Generate a compact transcript summary."""
+        if not self.entries:
+            return "Empty session."
+
+        turns = []
+        for e in self.entries[-20:]:  # last 20 entries
+            role = e["role"]
+            if role == "user":
+                turns.append(f"USER: {e['text'][:200]}")
+            elif role == "agent":
+                turns.append(f"AGENT: {e['text'][:200]}")
+            elif role == "tool":
+                turns.append(f"TOOL({e.get('tool','')}): {e.get('result','')[:150]}")
+
+        return "\n".join(turns)
+
+
+class AgentMemory:
+    """
+    Cross-session memory for an agent.
+
+    Wraps MemPalace with agent-specific conventions:
+    - Each agent has a wing (e.g., "wing_bezalel")
+    - Session summaries go in the "hermes" room
+    - Important decisions go in room-specific closets
+    - Facts go in the "nexus" room
+    """
+
+    def __init__(
+        self,
+        agent_name: str,
+        wing: Optional[str] = None,
+        palace_path: Optional[Path] = None,
+    ):
+        self.agent_name = agent_name
+        self.wing = wing or f"wing_{agent_name}"
+        self.palace_path = palace_path
+        self._transcript: Optional[SessionTranscript] = None
+        self._available: Optional[bool] = None
+
+    def _check_available(self) -> bool:
+        """Check if MemPalace is accessible."""
+        if self._available is not None:
+            return self._available
+
+        try:
+            from nexus.mempalace.searcher import search_memories, add_memory, _get_client
+            from nexus.mempalace.config import MEMPALACE_PATH
+
+            path = self.palace_path or MEMPALACE_PATH
+            _get_client(path)
+            self._available = True
+            logger.info(f"MemPalace available at {path}")
+        except Exception as e:
+            self._available = False
+            logger.warning(f"MemPalace unavailable: {e}")
+
+        return self._available
+
+    def recall_context(
+        self,
+        query: Optional[str] = None,
+        n_results: int = 5,
+    ) -> MemoryContext:
+        """
+        Load relevant context from past sessions.
+
+        Called at session start to inject L0/L1 memory into the prompt.
+
+        Args:
+            query: What to search for. If None, loads recent diary entries.
+            n_results: Max memories to recall.
+        """
+        ctx = MemoryContext()
+
+        if not self._check_available():
+            ctx.error = "MemPalace unavailable"
+            return ctx
+
+        try:
+            from nexus.mempalace.searcher import search_memories
+
+            # Load recent diary entries (session summaries)
+            ctx.recent_diaries = [
+                {"text": r.text, "score": r.score, "timestamp": r.metadata.get("timestamp", "")}
+                for r in search_memories(
+                    "session summary",
+                    palace_path=self.palace_path,
+                    wing=self.wing,
+                    room="hermes",
+                    n_results=3,
+                )
+            ]
+
+            # Load known facts
+            ctx.facts = [
+                {"text": r.text, "score": r.score}
+                for r in search_memories(
+                    "important facts decisions",
+                    palace_path=self.palace_path,
+                    wing=self.wing,
+                    room="nexus",
+                    n_results=5,
+                )
+            ]
+
+            # Search for relevant memories if query provided
+            if query:
+                ctx.relevant_memories = [
+                    {"text": r.text, "score": r.score, "room": r.room}
+                    for r in search_memories(
+                        query,
+                        palace_path=self.palace_path,
+                        wing=self.wing,
+                        n_results=n_results,
+                    )
+                ]
+
+            ctx.loaded = True
+
+        except Exception as e:
+            ctx.error = str(e)
+            logger.warning(f"Failed to recall context: {e}")
+
+        return ctx
+
+    def remember(
+        self,
+        text: str,
+        room: str = "nexus",
+        source_file: str = "",
+        metadata: Optional[dict] = None,
+    ) -> Optional[str]:
+        """
+        Store a memory.
+
+        Args:
+            text: The memory content.
+            room: Target room (forge, hermes, nexus, issues, experiments).
+            source_file: Optional source attribution.
+            metadata: Extra metadata.
+
+        Returns:
+            Document ID if stored, None if MemPalace unavailable.
+        """
+        if not self._check_available():
+            logger.warning("Cannot store memory — MemPalace unavailable")
+            return None
+
+        try:
+            from nexus.mempalace.searcher import add_memory
+
+            doc_id = add_memory(
+                text=text,
+                room=room,
+                wing=self.wing,
+                palace_path=self.palace_path,
+                source_file=source_file,
+                extra_metadata=metadata or {},
+            )
+            logger.debug(f"Stored memory in {room}: {text[:80]}...")
+            return doc_id
+
+        except Exception as e:
+            logger.warning(f"Failed to store memory: {e}")
+            return None
+
+    def write_diary(
+        self,
+        summary: Optional[str] = None,
+    ) -> Optional[str]:
+        """
+        Write a session diary entry to MemPalace.
+
+        Called at session end. If summary is None, auto-generates one
+        from the session transcript.
+
+        Args:
+            summary: Override summary text. If None, generates from transcript.
+
+        Returns:
+            Document ID if stored, None if unavailable.
+        """
+        if summary is None and self._transcript:
+            summary = self._transcript.summary()
+
+        if not summary:
+            return None
+
+        timestamp = datetime.now(timezone.utc).isoformat()
+        diary_text = f"[{timestamp}] Session by {self.agent_name}:\n{summary}"
+
+        return self.remember(
+            diary_text,
+            room="hermes",
+            metadata={
+                "type": "session_diary",
+                "agent": self.agent_name,
+                "timestamp": timestamp,
+                "entry_count": len(self._transcript.entries) if self._transcript else 0,
+            },
+        )
+
+    def start_session(self) -> SessionTranscript:
+        """
+        Begin a new session transcript.
+
+        Returns the transcript object for recording turns.
+        """
+        self._transcript = SessionTranscript(
+            agent_name=self.agent_name,
+            wing=self.wing,
+        )
+        logger.info(f"Session started for {self.agent_name}")
+        return self._transcript
+
+    def end_session(self, diary_summary: Optional[str] = None) -> Optional[str]:
+        """
+        End the current session, write diary, return diary doc ID.
+        """
+        doc_id = self.write_diary(diary_summary)
+        self._transcript = None
+        logger.info(f"Session ended for {self.agent_name}")
+        return doc_id
+
+    def search(
+        self,
+        query: str,
+        room: Optional[str] = None,
+        n_results: int = 5,
+    ) -> list[dict]:
+        """
+        Search memories. Useful during a session for recall.
+
+        Returns list of {text, room, wing, score} dicts.
+        """
+        if not self._check_available():
+            return []
+
+        try:
+            from nexus.mempalace.searcher import search_memories
+
+            results = search_memories(
+                query,
+                palace_path=self.palace_path,
+                wing=self.wing,
+                room=room,
+                n_results=n_results,
+            )
+            return [
+                {"text": r.text, "room": r.room, "wing": r.wing, "score": r.score}
+                for r in results
+            ]
+
+        except Exception as e:
+            logger.warning(f"Search failed: {e}")
+            return []
+
+
+# --- Fleet-wide memory helpers ---
+
+def create_agent_memory(
+    agent_name: str,
+    palace_path: Optional[Path] = None,
+) -> AgentMemory:
+    """
+    Factory for creating AgentMemory with standard config.
+
+    Reads wing from MEMPALACE_WING env or defaults to wing_{agent_name}.
+    """
+    wing = os.environ.get("MEMPALACE_WING", f"wing_{agent_name}")
+    return AgentMemory(
+        agent_name=agent_name,
+        wing=wing,
+        palace_path=palace_path,
+    )

agent/memory_hooks.py

@@ -0,0 +1,183 @@
+"""
+agent.memory_hooks — Session lifecycle hooks for agent memory.
+
+Integrates AgentMemory into the agent session lifecycle:
+- on_session_start: Load context, inject into prompt
+- on_user_turn: Record user input
+- on_agent_turn: Record agent output
+- on_tool_call: Record tool usage
+- on_session_end: Write diary, clean up
+
+These hooks are designed to be called from the Hermes harness or
+any agent framework. They're fire-and-forget — failures are logged
+but never crash the session.
+
+Usage:
+    from agent.memory_hooks import MemoryHooks
+
+    hooks = MemoryHooks(agent_name="bezalel")
+    hooks.on_session_start()  # loads context
+
+    # In your agent loop:
+    hooks.on_user_turn("Check CI pipeline health")
+    hooks.on_agent_turn("Running CI check...")
+    hooks.on_tool_call("shell", "pytest tests/", "12 passed")
+
+    # End of session:
+    hooks.on_session_end()  # writes diary
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Optional
+
+from agent.memory import AgentMemory, MemoryContext, create_agent_memory
+
+logger = logging.getLogger("agent.memory_hooks")
+
+
+class MemoryHooks:
+    """
+    Drop-in session lifecycle hooks for agent memory.
+
+    Wraps AgentMemory with error boundaries — every hook catches
+    exceptions and logs warnings so memory failures never crash
+    the agent session.
+    """
+
+    def __init__(
+        self,
+        agent_name: str,
+        palace_path=None,
+        auto_diary: bool = True,
+    ):
+        self.agent_name = agent_name
+        self.auto_diary = auto_diary
+        self._memory: Optional[AgentMemory] = None
+        self._context: Optional[MemoryContext] = None
+        self._active = False
+
+    @property
+    def memory(self) -> AgentMemory:
+        if self._memory is None:
+            self._memory = create_agent_memory(
+                self.agent_name,
+                palace_path=getattr(self, '_palace_path', None),
+            )
+        return self._memory
+
+    def on_session_start(self, query: Optional[str] = None) -> str:
+        """
+        Called at session start. Loads context from MemPalace.
+
+        Returns a prompt block to inject into the agent's context, or
+        empty string if memory is unavailable.
+
+        Args:
+            query: Optional recall query (e.g., "What was I working on?")
+        """
+        try:
+            self.memory.start_session()
+            self._active = True
+
+            self._context = self.memory.recall_context(query=query)
+            block = self._context.to_prompt_block()
+
+            if block:
+                logger.info(
+                    f"Loaded {len(self._context.recent_diaries)} diaries, "
+                    f"{len(self._context.facts)} facts, "
+                    f"{len(self._context.relevant_memories)} relevant memories "
+                    f"for {self.agent_name}"
+                )
+            else:
+                logger.info(f"No prior memory for {self.agent_name}")
+
+            return block
+
+        except Exception as e:
+            logger.warning(f"Session start memory hook failed: {e}")
+            return ""
+
+    def on_user_turn(self, text: str):
+        """Record a user message."""
+        if not self._active:
+            return
+        try:
+            if self.memory._transcript:
+                self.memory._transcript.add_user_turn(text)
+        except Exception as e:
+            logger.debug(f"Failed to record user turn: {e}")
+
+    def on_agent_turn(self, text: str):
+        """Record an agent response."""
+        if not self._active:
+            return
+        try:
+            if self.memory._transcript:
+                self.memory._transcript.add_agent_turn(text)
+        except Exception as e:
+            logger.debug(f"Failed to record agent turn: {e}")
+
+    def on_tool_call(self, tool: str, args: str, result_summary: str):
+        """Record a tool invocation."""
+        if not self._active:
+            return
+        try:
+            if self.memory._transcript:
+                self.memory._transcript.add_tool_call(tool, args, result_summary)
+        except Exception as e:
+            logger.debug(f"Failed to record tool call: {e}")
+
+    def on_important_decision(self, text: str, room: str = "nexus"):
+        """
+        Record an important decision or fact for long-term memory.
+
+        Use this when the agent makes a significant decision that
+        should persist beyond the current session.
+        """
+        try:
+            self.memory.remember(text, room=room, metadata={"type": "decision"})
+            logger.info(f"Remembered decision: {text[:80]}...")
+        except Exception as e:
+            logger.warning(f"Failed to remember decision: {e}")
+
+    def on_session_end(self, summary: Optional[str] = None) -> Optional[str]:
+        """
+        Called at session end. Writes diary entry.
+
+        Args:
+            summary: Override diary text. If None, auto-generates.
+
+        Returns:
+            Diary document ID, or None.
+        """
+        if not self._active:
+            return None
+
+        try:
+            doc_id = self.memory.end_session(diary_summary=summary)
+            self._active = False
+            self._context = None
+            return doc_id
+        except Exception as e:
+            logger.warning(f"Session end memory hook failed: {e}")
+            self._active = False
+            return None
+
+    def search(self, query: str, room: Optional[str] = None) -> list[dict]:
+        """
+        Search memories during a session.
+
+        Returns list of {text, room, wing, score}.
+        """
+        try:
+            return self.memory.search(query, room=room)
+        except Exception as e:
+            logger.warning(f"Memory search failed: {e}")
+            return []
+
+    @property
+    def is_active(self) -> bool:
+        return self._active

bin/memory_mine.py

@@ -0,0 +1,258 @@
+#!/usr/bin/env python3
+"""
+memory_mine.py — Mine session transcripts into MemPalace.
+
+Reads Hermes session logs (JSONL format) and stores summaries
+in the palace. Supports batch mining, single-file processing,
+and live directory watching.
+
+Usage:
+    # Mine a single session file
+    python3 bin/memory_mine.py ~/.hermes/sessions/2026-04-13.jsonl
+
+    # Mine all sessions from last 7 days
+    python3 bin/memory_mine.py --days 7
+
+    # Mine a specific wing's sessions
+    python3 bin/memory_mine.py --wing wing_bezalel --days 14
+
+    # Dry run — show what would be mined
+    python3 bin/memory_mine.py --dry-run --days 7
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import logging
+import os
+import sys
+import time
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+from typing import Optional
+
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s [%(levelname)s] %(message)s",
+    datefmt="%Y-%m-%d %H:%M:%S",
+)
+logger = logging.getLogger("memory-mine")
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+if str(REPO_ROOT) not in sys.path:
+    sys.path.insert(0, str(REPO_ROOT))
+
+
+def parse_session_file(path: Path) -> list[dict]:
+    """
+    Parse a JSONL session file into turns.
+
+    Each line is expected to be a JSON object with:
+    - role: "user" | "assistant" | "system" | "tool"
+    - content: text
+    - timestamp: ISO string (optional)
+    """
+    turns = []
+    with open(path) as f:
+        for i, line in enumerate(f):
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                turn = json.loads(line)
+                turns.append(turn)
+            except json.JSONDecodeError:
+                logger.debug(f"Skipping malformed line {i+1} in {path}")
+    return turns
+
+
+def summarize_session(turns: list[dict], agent_name: str = "unknown") -> str:
+    """
+    Generate a compact summary of a session's turns.
+
+    Keeps user messages and key agent responses, strips noise.
+    """
+    if not turns:
+        return "Empty session."
+
+    user_msgs = []
+    agent_msgs = []
+    tool_calls = []
+
+    for turn in turns:
+        role = turn.get("role", "")
+        content = str(turn.get("content", ""))[:300]
+
+        if role == "user":
+            user_msgs.append(content)
+        elif role == "assistant":
+            agent_msgs.append(content)
+        elif role == "tool":
+            tool_name = turn.get("name", turn.get("tool", "unknown"))
+            tool_calls.append(f"{tool_name}: {content[:150]}")
+
+    parts = [f"Session by {agent_name}:"]
+
+    if user_msgs:
+        parts.append(f"\nUser asked ({len(user_msgs)} messages):")
+        for msg in user_msgs[:5]:
+            parts.append(f"  - {msg[:200]}")
+        if len(user_msgs) > 5:
+            parts.append(f"  ... and {len(user_msgs) - 5} more")
+
+    if agent_msgs:
+        parts.append(f"\nAgent responded ({len(agent_msgs)} messages):")
+        for msg in agent_msgs[:3]:
+            parts.append(f"  - {msg[:200]}")
+
+    if tool_calls:
+        parts.append(f"\nTools used ({len(tool_calls)} calls):")
+        for tc in tool_calls[:5]:
+            parts.append(f"  - {tc}")
+
+    return "\n".join(parts)
+
+
+def mine_session(
+    path: Path,
+    wing: str,
+    palace_path: Optional[Path] = None,
+    dry_run: bool = False,
+) -> Optional[str]:
+    """
+    Mine a single session file into MemPalace.
+
+    Returns the document ID if stored, None on failure or dry run.
+    """
+    try:
+        from agent.memory import AgentMemory
+    except ImportError:
+        logger.error("Cannot import agent.memory — is the repo in PYTHONPATH?")
+        return None
+
+    turns = parse_session_file(path)
+    if not turns:
+        logger.debug(f"Empty session file: {path}")
+        return None
+
+    agent_name = wing.replace("wing_", "")
+    summary = summarize_session(turns, agent_name)
+
+    if dry_run:
+        print(f"\n--- {path.name} ---")
+        print(summary[:500])
+        print(f"({len(turns)} turns)")
+        return None
+
+    mem = AgentMemory(agent_name=agent_name, wing=wing, palace_path=palace_path)
+    doc_id = mem.remember(
+        summary,
+        room="hermes",
+        source_file=str(path),
+        metadata={
+            "type": "mined_session",
+            "source": str(path),
+            "turn_count": len(turns),
+            "agent": agent_name,
+            "timestamp": datetime.now(timezone.utc).isoformat(),
+        },
+    )
+
+    if doc_id:
+        logger.info(f"Mined {path.name} → {doc_id} ({len(turns)} turns)")
+    else:
+        logger.warning(f"Failed to mine {path.name}")
+
+    return doc_id
+
+
+def find_session_files(
+    sessions_dir: Path,
+    days: int = 7,
+    pattern: str = "*.jsonl",
+) -> list[Path]:
+    """
+    Find session files from the last N days.
+    """
+    cutoff = datetime.now() - timedelta(days=days)
+    files = []
+
+    if not sessions_dir.exists():
+        logger.warning(f"Sessions directory not found: {sessions_dir}")
+        return files
+
+    for path in sorted(sessions_dir.glob(pattern)):
+        # Use file modification time as proxy for session date
+        mtime = datetime.fromtimestamp(path.stat().st_mtime)
+        if mtime >= cutoff:
+            files.append(path)
+
+    return files
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        description="Mine session transcripts into MemPalace"
+    )
+    parser.add_argument(
+        "files", nargs="*", help="Session files to mine (JSONL format)"
+    )
+    parser.add_argument(
+        "--days", type=int, default=7,
+        help="Mine sessions from last N days (default: 7)"
+    )
+    parser.add_argument(
+        "--sessions-dir",
+        default=str(Path.home() / ".hermes" / "sessions"),
+        help="Directory containing session JSONL files"
+    )
+    parser.add_argument(
+        "--wing", default=None,
+        help="Wing name (default: auto-detect from MEMPALACE_WING env or 'wing_timmy')"
+    )
+    parser.add_argument(
+        "--palace-path", default=None,
+        help="Override palace path"
+    )
+    parser.add_argument(
+        "--dry-run", action="store_true",
+        help="Show what would be mined without storing"
+    )
+
+    args = parser.parse_args(argv)
+
+    wing = args.wing or os.environ.get("MEMPALACE_WING", "wing_timmy")
+    palace_path = Path(args.palace_path) if args.palace_path else None
+
+    if args.files:
+        files = [Path(f) for f in args.files]
+    else:
+        sessions_dir = Path(args.sessions_dir)
+        files = find_session_files(sessions_dir, days=args.days)
+
+    if not files:
+        logger.info("No session files found to mine.")
+        return 0
+
+    logger.info(f"Mining {len(files)} session files (wing={wing})")
+
+    mined = 0
+    failed = 0
+    for path in files:
+        result = mine_session(path, wing=wing, palace_path=palace_path, dry_run=args.dry_run)
+        if result:
+            mined += 1
+        elif result is None and not args.dry_run:
+            failed += 1
+
+    if args.dry_run:
+        logger.info(f"Dry run complete — {len(files)} files would be mined")
+    else:
+        logger.info(f"Mining complete — {mined} mined, {failed} failed")
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

index.html

@@ -152,18 +152,18 @@
 
   <!-- Top Right: Agent Log, Atlas & SOUL Toggle -->
   <div class="hud-top-right">
-    <button id="atlas-toggle-btn" class="hud-icon-btn" title="World Directory">
-    <button id="soul-toggle-btn" class="hud-icon-btn" title="Timmy's SOUL">
-      <span class="hud-icon">✦</span>
-      <span class="hud-btn-label">SOUL</span>
-    <button id="mode-toggle-btn" class="hud-icon-btn mode-toggle" title="Toggle Mode">
-      <span class="hud-icon">👁</span>
-      <span class="hud-btn-label" id="mode-label">VISITOR</span>
-    </button>
     <button id="atlas-toggle-btn" class="hud-icon-btn" title="Portal Atlas">
       <span class="hud-icon">🌐</span>
       <span class="hud-btn-label">WORLDS</span>
     </button>
+    <button id="soul-toggle-btn" class="hud-icon-btn" title="Timmy's SOUL">
+      <span class="hud-icon">✦</span>
+      <span class="hud-btn-label">SOUL</span>
+    </button>
+    <button id="mode-toggle-btn" class="hud-icon-btn mode-toggle" title="Toggle Mode">
+      <span class="hud-icon">👁</span>
+      <span class="hud-btn-label" id="mode-label">VISITOR</span>
+    </button>
     <div id="bannerlord-status" class="hud-status-item" title="Bannerlord Readiness">
       <span class="status-dot"></span>
       <span class="status-label">BANNERLORD</span>

playground/README.md

@@ -1,95 +0,0 @@
-# Sovereign Sound Playground
-
-An interactive audio-visual experience that lets you paint with sound and create music visually.
-
-## Live Version
-
-**LIVE:** https://playground.alexanderwhitestone.com/playground.html
-
-## Features
-
-### Core Functionality
-- **Visual Piano Keyboard**: 26 keys mapped to keyboard (QWERTY layout)
-- **6 Visual Modes**:
-  - FREE: Freeform painting with sound
-  - GRAVITY: Notes gravitate toward cursor
-  - RAIN: Musical rain falls from above
-  - CONSTELLATION: Notes connect in constellation patterns
-  - BPM: Grid pulses to the beat
-  - MIRROR: Mirror notes across vertical axis
-- **5 Color Palettes**:
-  - AURORA: Warm rainbow colors
-  - OCEAN: Cool blues and teals
-  - EMBER: Warm reds and oranges
-  - FOREST: Natural greens
-  - NEON: Vibrant neon colors
-
-### Audio Features
-- **Ambient Beat**: Automatic chord progressions with kick, snare, and hi-hat
-- **Chord Detection**: Real-time chord recognition (major, minor, 7th, etc.)
-- **Mouse Playback**: Hover over painted notes to hear them again
-- **Touch Support**: Works on mobile devices
-
-### Tools
-- **Recording**: Press R to record your session
-- **Export**: Press S to save your creation as PNG
-- **Clear**: Press Backspace to clear the canvas
-- **Mode Switch**: Press Tab to cycle through modes
-- **Palette Switch**: Press 1-5 to switch color palettes
-
-## Controls
-
-### Keyboard
-- **A-Z**: Play notes and paint
-- **Space**: Toggle ambient beat
-- **Backspace**: Clear canvas
-- **Tab**: Switch mode
-- **R**: Toggle recording
-- **S**: Save as PNG
-- **1-5**: Switch color palette
-
-### Mouse
-- **Click**: Play random note and paint
-- **Drag**: Continuous painting
-- **Hover over notes**: Replay sounds
-
-### Touch
-- **Touch and drag**: Paint with sound
-
-## Technical Details
-
-- Zero dependencies
-- Pure HTML5 Canvas + Web Audio API
-- No external libraries
-- Self-contained single HTML file
-
-## Integration
-
-The playground is integrated into The Nexus as a portal:
-- **Portal ID**: `playground`
-- **Portal Type**: `creative-tool`
-- **Status**: Online
-- **Access**: Visitor mode (no operator privileges needed)
-
-## Iteration Plan
-
-Future enhancements:
-- [ ] More modes (Spiral, Gravity Well, Strobe)
-- [ ] MIDI keyboard support
-- [ ] Share session as URL
-- [ ] Mobile optimization
-- [ ] Multiplayer via WebSocket
-- [ ] Integration with Nexus spatial audio system
-- [ ] Memory system for saved compositions
-
-## File Structure
-
-```
-playground/
-├── playground.html    # Main playground application
-└── README.md         # This file
-```
-
-## Credits
-
-Created as part of the Timmy Foundation's Sovereign Sound initiative.

playground/playground.html

@@ -1,692 +0,0 @@
-<!DOCTYPE html>
-<html lang="en">
-<head>
-<meta charset="UTF-8">
-<meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=no">
-<title>Sovereign Sound — Playground</title>
-<style>
-* { margin: 0; padding: 0; box-sizing: border-box; }
-html, body { height: 100%; overflow: hidden; }
-body {
-  background: #050510;
-  font-family: 'SF Mono', 'Fira Code', monospace;
-  color: #fff;
-  cursor: none;
-  user-select: none;
-  -webkit-user-select: none;
-  touch-action: none;
-}
-canvas { display: block; position: fixed; top: 0; left: 0; }
-.piano {
-  position: fixed; bottom: 0; left: 0; right: 0;
-  height: 80px; display: flex;
-  background: rgba(0,0,0,0.3);
-  backdrop-filter: blur(10px);
-  -webkit-backdrop-filter: blur(10px);
-  z-index: 10;
-}
-.key {
-  flex: 1; border-right: 1px solid rgba(255,255,255,0.05);
-  display: flex; align-items: flex-end; justify-content: center;
-  padding-bottom: 8px; font-size: 9px; opacity: 0.3;
-  transition: all 0.1s; position: relative;
-}
-.key.black {
-  background: rgba(0,0,0,0.5);
-  height: 50px; margin: 0 -8px; width: 60%; z-index: 1;
-  border: 1px solid rgba(255,255,255,0.08);
-}
-.key.active {
-  background: rgba(255,255,255,0.15);
-  opacity: 0.8;
-  transform: scaleY(0.98);
-  transform-origin: bottom;
-}
-.hud {
-  position: fixed; top: 16px; left: 16px;
-  font-size: 9px; letter-spacing: 3px;
-  text-transform: uppercase; opacity: 0.2;
-  line-height: 2.2; z-index: 10;
-  pointer-events: none;
-}
-.mode-switch {
-  position: fixed; top: 16px; right: 16px;
-  display: flex; gap: 4px; z-index: 10;
-}
-.mode-dot {
-  width: 6px; height: 6px; border-radius: 50%;
-  background: rgba(255,255,255,0.15);
-  cursor: pointer; transition: all 0.3s;
-  pointer-events: all;
-}
-.mode-dot.active { background: rgba(255,255,255,0.6); transform: scale(1.4); }
-.toast {
-  position: fixed; top: 50%; left: 50%;
-  transform: translate(-50%, -50%);
-  font-size: 10px; letter-spacing: 6px;
-  text-transform: uppercase; opacity: 0;
-  transition: opacity 0.4s; pointer-events: none; z-index: 20;
-}
-.toast.show { opacity: 0.4; }
-.rec-dot {
-  position: fixed; top: 16px; left: 50%; transform: translateX(-50%);
-  width: 8px; height: 8px; border-radius: 50%;
-  background: #ff0040; opacity: 0;
-  transition: opacity 0.3s; z-index: 10;
-}
-.rec-dot.on { opacity: 1; animation: pulse 1s infinite; }
-@keyframes pulse { 0%,100% { opacity: 1; } 50% { opacity: 0.3; } }
-</style>
-</head>
-<body>
-
-<canvas id="c"></canvas>
-
-<div class="hud" id="hud">
-  <div id="h-mode">FREE</div>
-  <div id="h-pal">AURORA</div>
-  <div id="h-notes">0 notes</div>
-  <div id="h-chord">—</div>
-</div>
-
-<div class="mode-switch" id="modes"></div>
-<div class="rec-dot" id="rec"></div>
-<div class="toast" id="toast"></div>
-
-<div class="piano" id="piano"></div>
-
-<script>
-// ═══════════════════════════════════════════════════════════════
-//  SOVEREIGN SOUND — PLAYGROUND v3
-//  The ultimate interactive audio-visual experience.
-//  Zero dependencies. Pure craft.
-// ═══════════════════════════════════════════════════════════════
-
-const canvas = document.getElementById('c');
-const ctx = canvas.getContext('2d');
-let W, H;
-
-function resize() {
-  W = canvas.width = innerWidth;
-  H = canvas.height = innerHeight;
-  ctx.fillStyle = '#050510';
-  ctx.fillRect(0, 0, W, H);
-}
-addEventListener('resize', resize); resize();
-
-// ═══════════════════════════════════════════════════════════════
-//  AUDIO ENGINE
-// ═══════════════════════════════════════════════════════════════
-
-let ac = null, master = null, analyser = null;
-
-function initAudio() {
-  if (ac) return;
-  ac = new AudioContext();
-  master = ac.createGain(); master.gain.value = 0.4;
-  
-  const wet = ac.createGain(); wet.gain.value = 0.2;
-  [0.037, 0.059, 0.083, 0.127].forEach(t => {
-    const d = ac.createDelay(1); d.delayTime.value = t;
-    const fb = ac.createGain(); fb.gain.value = 0.22;
-    master.connect(d); d.connect(fb); fb.connect(d); d.connect(wet);
-  });
-  wet.connect(ac.destination);
-  
-  analyser = ac.createAnalyser();
-  analyser.fftSize = 512;
-  analyser.smoothingTimeConstant = 0.8;
-  master.connect(analyser);
-  master.connect(ac.destination);
-}
-
-function freq(name) {
-  const n = { C:0,'C#':1,D:2,'D#':3,E:4,F:5,'F#':6,G:7,'G#':8,A:9,'A#':10,B:11 };
-  const nm = name.replace(/\d/,'');
-  const oct = parseInt(name.match(/\d/)?.[0] || 4);
-  return 440 * Math.pow(2, (n[nm] + (oct-4)*12 - 9) / 12);
-}
-
-function tone(f, type='sine', dur=0.5, vol=0.1) {
-  initAudio();
-  const t = ac.currentTime;
-  const o = ac.createOscillator();
-  const g = ac.createGain();
-  o.type = type; o.frequency.value = f;
-  g.gain.setValueAtTime(0, t);
-  g.gain.linearRampToValueAtTime(vol, t + 0.01);
-  g.gain.exponentialRampToValueAtTime(vol*0.3, t+dur*0.4);
-  g.gain.exponentialRampToValueAtTime(0.001, t+dur);
-  o.connect(g); g.connect(master);
-  o.start(t); o.stop(t+dur);
-}
-
-function kick() { initAudio(); const t=ac.currentTime; const o=ac.createOscillator(), g=ac.createGain(); o.type='sine'; o.frequency.setValueAtTime(80,t); o.frequency.exponentialRampToValueAtTime(30,t+0.12); g.gain.setValueAtTime(0.4,t); g.gain.exponentialRampToValueAtTime(0.001,t+0.15); o.connect(g); g.connect(master); o.start(t); o.stop(t+0.15); }
-function snare() { initAudio(); const t=ac.currentTime; const len=ac.sampleRate*0.06; const buf=ac.createBuffer(1,len,ac.sampleRate); const d=buf.getChannelData(0); for(let i=0;i<len;i++) d[i]=(Math.random()*2-1)*0.25; const s=ac.createBufferSource(); s.buffer=buf; const g=ac.createGain(); g.gain.setValueAtTime(0.2,t); g.gain.exponentialRampToValueAtTime(0.001,t+0.08); s.connect(g); g.connect(master); s.start(t); }
-function hat() { initAudio(); const t=ac.currentTime; const len=ac.sampleRate*0.025; const buf=ac.createBuffer(1,len,ac.sampleRate); const d=buf.getChannelData(0); for(let i=0;i<len;i++) d[i]=(Math.random()*2-1)*0.12; const s=ac.createBufferSource(); s.buffer=buf; const g=ac.createGain(); g.gain.setValueAtTime(0.1,t); g.gain.exponentialRampToValueAtTime(0.001,t+0.025); s.connect(g); g.connect(master); s.start(t); }
-
-// ═══════════════════════════════════════════════════════════════
-//  SCALES & PALETTES
-// ═══════════════════════════════════════════════════════════════
-
-const SCALES = {
-  AURORA:  { colors:['#ff6b6b','#ff9f43','#feca57','#48dbfb','#54a0ff','#5f27cd','#ff9ff3','#00d2d3'], notes:['C5','D5','E5','F5','G5','A5','B5','C6','D6','E6','C4','D4','E4','F4','G4','A4','B4','C5','D5','E5','F5','C2','D2','E2','F2','G2'], bg:[6,6,16], glow:'#ff9ff3' },
-  OCEAN:   { colors:['#0077b6','#00b4d8','#90e0ef','#48cae4','#023e8a','#ade8f4'], notes:['D5','E5','F#5','G5','A5','B5','C#6','D6','E6','D4','E4','F#4','G4','A4','B4','C#5','D5','E5','D3','E3','F#3','D2','E2','F#2','G2','A2'], bg:[4,12,22], glow:'#48cae4' },
-  EMBER:   { colors:['#ff4500','#ff6347','#ff7f50','#dc143c','#cd5c5c','#f08080'], notes:['C5','Eb5','F5','G5','Ab5','Bb5','C6','D5','Eb5','C4','Eb4','F4','G4','Ab4','Bb4','C5','D5','Eb5','C3','Eb3','F3','C2','Eb2','F2','G2','Ab2'], bg:[14,5,5], glow:'#ff6347' },
-  FOREST:  { colors:['#2d6a4f','#40916c','#52b788','#74c69d','#95d5b2','#b7e4c7'], notes:['E5','F#5','G5','A5','B5','C6','D6','E6','F#6','E4','F#4','G4','A4','B4','C5','D5','E5','F#5','E3','F#3','G3','E2','F#2','G2','A2','B2'], bg:[4,12,6], glow:'#52b788' },
-  NEON:    { colors:['#ff00ff','#00ffff','#ffff00','#ff0080','#00ff80','#8000ff'], notes:['C5','D5','E5','G5','A5','C6','D6','E6','G6','C4','D4','E4','G4','A4','C5','D5','E5','G5','C3','D3','E3','C2','D2','E2','G2','A2'], bg:[8,2,16], glow:'#00ffff' },
-};
-
-let palName = 'AURORA';
-let pal = SCALES[palName];
-const PAL_NAMES = Object.keys(SCALES);
-let palIdx = 0;
-
-// ═══════════════════════════════════════════════════════════════
-//  MODES
-// ═══════════════════════════════════════════════════════════════
-
-const MODES = ['FREE','GRAVITY','RAIN','CONSTELLATION','BPM','MIRROR'];
-let modeIdx = 0, mode = MODES[0];
-
-// ═══════════════════════════════════════════════════════════════
-//  STATE
-// ═══════════════════════════════════════════════════════════════
-
-let notes = [];        // permanent painted notes
-let particles = [];    // transient particles
-let ripples = [];      // ripple effects
-let raindrops = [];
-let mouseX = W/2, mouseY = H/2;
-let mouseDown = false;
-let time = 0;
-let ambientOn = false;
-let ambientStep = 0;
-let ambientTimer = null;
-let screenShake = 0;
-let lastPaintTime = 0;
-let recentNotes = [];
-let recording = false;
-let recordedNotes = [];
-
-// ═══════════════════════════════════════════════════════════════
-//  PIANO KEYBOARD — visual at bottom
-// ═══════════════════════════════════════════════════════════════
-
-const KEYS = 'qwertyuiopasdfghjklzxcvbnm';
-const IS_BLACK = [false,true,false,true,false,false,true,false,true,false,true,false,
-                  false,true,false,true,false,false,true,false,true,false,true,false,false,false];
-
-function buildPiano() {
-  const piano = document.getElementById('piano');
-  piano.innerHTML = '';
-  KEYS.split('').forEach((k, i) => {
-    const div = document.createElement('div');
-    div.className = 'key' + (IS_BLACK[i] ? ' black' : '');
-    div.dataset.key = k;
-    div.textContent = k.toUpperCase();
-    div.addEventListener('mousedown', () => triggerKey(k));
-    div.addEventListener('touchstart', (e) => { e.preventDefault(); triggerKey(k); });
-    piano.appendChild(div);
-  });
-}
-buildPiano();
-
-// Mode/palette dots
-const modesDiv = document.getElementById('modes');
-MODES.forEach((m, i) => {
-  const dot = document.createElement('div');
-  dot.className = 'mode-dot' + (i===0?' active':'');
-  dot.onclick = () => { modeIdx=i; mode=MODES[i]; updateDots(); toast(m); };
-  modesDiv.appendChild(dot);
-});
-PAL_NAMES.forEach((p, i) => {
-  const dot = document.createElement('div');
-  dot.className = 'mode-dot';
-  dot.style.background = SCALES[p].glow;
-  dot.style.opacity = '0.2';
-  if (i===0) { dot.classList.add('active'); dot.style.opacity='0.6'; }
-  dot.onclick = () => { palIdx=i; palName=p; pal=SCALES[p]; updateDots(); toast(p); };
-  modesDiv.appendChild(dot);
-});
-
-function updateDots() {
-  modesDiv.querySelectorAll('.mode-dot').forEach((d, i) => {
-    if (i < MODES.length) {
-      d.classList.toggle('active', i===modeIdx);
-    } else {
-      const pi = i - MODES.length;
-      d.classList.toggle('active', pi===palIdx);
-      d.style.opacity = pi===palIdx ? '0.6' : '0.2';
-    }
-  });
-  document.getElementById('h-mode').textContent = mode;
-  document.getElementById('h-pal').textContent = palName;
-}
-
-// ═══════════════════════════════════════════════════════════════
-//  PAINT & PLAY
-// ═══════════════════════════════════════════════════════════════
-
-function paint(x, y, color, noteFreq, noteType, size=25) {
-  // Permanent splash
-  ctx.save();
-  ctx.globalAlpha = 0.06;
-  ctx.fillStyle = color;
-  ctx.beginPath(); ctx.arc(x, y, size*2, 0, Math.PI*2); ctx.fill();
-  
-  ctx.globalAlpha = 0.3;
-  ctx.beginPath();
-  const pts = 6+Math.floor(Math.random()*6);
-  for (let i=0; i<=pts; i++) {
-    const a = (i/pts)*Math.PI*2;
-    const r = size*(0.5+Math.random()*0.5);
-    i===0 ? ctx.moveTo(x+Math.cos(a)*r, y+Math.sin(a)*r) : ctx.lineTo(x+Math.cos(a)*r, y+Math.sin(a)*r);
-  }
-  ctx.closePath(); ctx.fill();
-  
-  ctx.globalAlpha = 0.8;
-  ctx.beginPath(); ctx.arc(x, y, size*0.12, 0, Math.PI*2); ctx.fill();
-  ctx.restore();
-  
-  notes.push({ x, y, radius: size, color, freq: noteFreq, type: noteType });
-  if (notes.length > 4000) notes.splice(0, 500);
-  
-  // Particles
-  for (let i=0; i<12; i++) {
-    const a = Math.random()*Math.PI*2;
-    const s = 1+Math.random()*4;
-    particles.push({ x, y, vx:Math.cos(a)*s, vy:Math.sin(a)*s, size:1+Math.random()*3, life:1, color });
-  }
-  if (particles.length > 400) particles.splice(0, 100);
-  
-  ripples.push({ x, y, color, size: size*0.3, maxSize: size*3, life:1 });
-  if (ripples.length > 25) ripples.shift();
-  
-  if (noteType === 'sawtooth' && noteFreq < 200) screenShake = 6;
-}
-
-function triggerKey(key) {
-  const i = KEYS.indexOf(key);
-  if (i < 0) return;
-  
-  const noteName = pal.notes[i % pal.notes.length];
-  const noteFreq = freq(noteName);
-  const isBass = i >= 21;
-  const noteType = isBass ? 'sawtooth' : (i%3===0 ? 'triangle' : 'sine');
-  
-  tone(noteFreq, noteType, isBass ? 0.3 : 0.6, isBass ? 0.18 : 0.12);
-  
-  const x = mouseX + (Math.random()-0.5)*50;
-  const y = mouseY + (Math.random()-0.5)*50;
-  paint(x, y, pal.colors[i % pal.colors.length], noteFreq, noteType, isBass ? 35+Math.random()*15 : 20+Math.random()*15);
-  
-  // Piano visual
-  const pianoKey = document.querySelector(`.key[data-key="${key}"]`);
-  if (pianoKey) {
-    pianoKey.classList.add('active');
-    pianoKey.style.background = pal.colors[i % pal.colors.length] + '30';
-    setTimeout(() => { pianoKey.classList.remove('active'); pianoKey.style.background = ''; }, 200);
-  }
-  
-  // Track for chord detection
-  recentNotes.push({ freq: noteFreq, time: Date.now() });
-  if (recentNotes.length > 10) recentNotes.shift();
-  detectChord();
-  
-  // Recording
-  if (recording) recordedNotes.push({ key, time: Date.now(), x, y });
-}
-
-// ═══════════════════════════════════════════════════════════════
-//  CHORD DETECTION
-// ═══════════════════════════════════════════════════════════════
-
-function detectChord() {
-  const now = Date.now();
-  const recent = recentNotes.filter(n => now-n.time < 1500);
-  if (recent.length < 2) { document.getElementById('h-chord').textContent = '—'; return; }
-  
-  const freqs = recent.map(n => n.freq).sort((a,b) => a-b);
-  const ratios = [];
-  for (let i=1; i<freqs.length; i++) ratios.push(Math.round(1200*Math.log2(freqs[i]/freqs[0])));
-  
-  const patterns = { 'major':[0,400,700],'minor':[0,300,700],'7':[0,400,700,1000],'maj7':[0,400,700,1100],'min7':[0,300,700,1000],'power':[0,700],'sus4':[0,500,700],'sus2':[0,200,700],'dim':[0,300,600],'aug':[0,400,800] };
-  
-  let best = '—', bestScore = 0;
-  for (const [name, pat] of Object.entries(patterns)) {
-    let score = 0;
-    for (const p of pat) if (ratios.some(r => Math.abs(r-p) < 60)) score++;
-    score /= pat.length;
-    if (score > bestScore && score > 0.5) { bestScore = score; best = name; }
-  }
-  document.getElementById('h-chord').textContent = best;
-}
-
-// ═══════════════════════════════════════════════════════════════
-//  MOUSE PLAYBACK — play notes by hovering
-// ═══════════════════════════════════════════════════════════════
-
-let lastPlayed = null, lastPlayT = 0;
-function checkPlay(x, y) {
-  const now = Date.now();
-  if (now-lastPlayT < 50) return;
-  let closest = null, closestD = Infinity;
-  for (const n of notes) {
-    const d = Math.hypot(x-n.x, y-n.y);
-    if (d < n.radius*1.4 && d < closestD) { closest = n; closestD = d; }
-  }
-  if (closest && closest !== lastPlayed) {
-    const vol = 0.05 + (1-closestD/closest.radius)*0.1;
-    tone(closest.freq, closest.type, 0.2, vol);
-    ripples.push({ x:closest.x, y:closest.y, color:closest.color, size:closest.radius*0.2, maxSize:closest.radius*1.5, life:1 });
-    for (let i=0; i<3; i++) {
-      const a = Math.random()*Math.PI*2;
-      particles.push({ x:closest.x, y:closest.y, vx:Math.cos(a)*1.5, vy:Math.sin(a)*1.5, size:1.5, life:1, color:closest.color });
-    }
-    lastPlayed = closest;
-    lastPlayT = now;
-  }
-}
-
-// ═══════════════════════════════════════════════════════════════
-//  AMBIENT BEAT
-// ═══════════════════════════════════════════════════════════════
-
-function ambientTick() {
-  if (!ambientOn) return;
-  const bpm = [72,60,80,66,128,90][palIdx];
-  const stepDur = 60000/bpm/4;
-  const beat = ambientStep % 16;
-  
-  if (beat%4===0) { kick(); screenShake=2; }
-  if (beat===4||beat===12) snare();
-  if (beat%2===1) hat();
-  
-  if (beat===0) {
-    const chords = [
-      [freq('C4'),freq('E4'),freq('G4')],
-      [freq('A3'),freq('C4'),freq('E4')],
-      [freq('F3'),freq('A3'),freq('C4')],
-      [freq('G3'),freq('B3'),freq('D4')]
-    ];
-    chords[Math.floor(ambientStep/16)%4].forEach(f => tone(f,'triangle',0.7,0.05));
-  }
-  
-  if (beat%2===0) {
-    const i = Math.floor(Math.random()*KEYS.length);
-    const k = KEYS[i];
-    const noteName = pal.notes[i % pal.notes.length];
-    paint(W/2+(Math.random()-0.5)*400, H/2+(Math.random()-0.5)*300,
-      pal.colors[i%pal.colors.length], freq(noteName), i>=21?'sawtooth':'sine', 10+Math.random()*8);
-  }
-  
-  ambientStep++;
-  ambientTimer = setTimeout(ambientTick, stepDur);
-}
-
-// ═══════════════════════════════════════════════════════════════
-//  INPUT
-// ═══════════════════════════════════════════════════════════════
-
-function toast(msg) {
-  const el = document.getElementById('toast');
-  el.textContent = msg; el.classList.add('show');
-  setTimeout(() => el.classList.remove('show'), 1200);
-}
-
-document.addEventListener('keydown', e => {
-  const k = e.key.toLowerCase();
-  
-  if (k===' ') { e.preventDefault(); ambientOn=!ambientOn; ambientOn?(ambientStep=0,ambientTick(),toast('AMBIENT ON')):(clearTimeout(ambientTimer),toast('AMBIENT OFF')); return; }
-  if (k==='backspace') { e.preventDefault(); ctx.fillStyle='#050510'; ctx.fillRect(0,0,W,H); notes=[]; ripples=[]; particles=[]; raindrops=[]; toast('CLEARED'); return; }
-  if (k==='tab') { e.preventDefault(); modeIdx=(modeIdx+1)%MODES.length; mode=MODES[modeIdx]; updateDots(); toast(mode); return; }
-  if (k==='r') { recording=!recording; document.getElementById('rec').classList.toggle('on',recording); toast(recording?'REC ON':'REC OFF'); if(!recording&&recordedNotes.length) replayRecording(); return; }
-  if (k==='s') { e.preventDefault(); saveCanvas(); return; }
-  if (k>='1' && k<='5') { palIdx=parseInt(k)-1; palName=PAL_NAMES[palIdx]; pal=SCALES[palName]; updateDots(); toast(palName); return; }
-  
-  triggerKey(k);
-});
-
-canvas.addEventListener('mousemove', e => {
-  mouseX = e.clientX; mouseY = e.clientY;
-  checkPlay(mouseX, mouseY);
-  if (mouseDown && Date.now()-lastPaintTime > 40) {
-    const i = Math.floor(Math.random()*KEYS.length);
-    triggerKey(KEYS[i]);
-    lastPaintTime = Date.now();
-  }
-  if (Math.random()>0.65) {
-    particles.push({ x:mouseX, y:mouseY, vx:(Math.random()-0.5)*0.5, vy:(Math.random()-0.5)*0.5, size:1+Math.random()*1.5, life:1, color:'rgba(255,255,255,0.3)' });
-    if (particles.length>400) particles.splice(0,80);
-  }
-});
-
-canvas.addEventListener('mousedown', e => { mouseDown=true; triggerKey(KEYS[Math.floor(Math.random()*KEYS.length)]); });
-canvas.addEventListener('mouseup', () => mouseDown=false);
-
-// Touch
-canvas.addEventListener('touchmove', e => {
-  e.preventDefault();
-  const t = e.touches[0];
-  mouseX = t.clientX; mouseY = t.clientY;
-  checkPlay(mouseX, mouseY);
-  if (Date.now()-lastPaintTime > 60) {
-    triggerKey(KEYS[Math.floor(Math.random()*KEYS.length)]);
-    lastPaintTime = Date.now();
-  }
-}, { passive: false });
-
-// ═══════════════════════════════════════════════════════════════
-//  MODE EFFECTS
-// ═══════════════════════════════════════════════════════════════
-
-function applyGravity() {
-  for (const n of notes) {
-    const dx = mouseX-n.x, dy = mouseY-n.y;
-    const d = Math.hypot(dx, dy);
-    if (d>10 && d<300) { n.x += dx*0.2/d; n.y += dy*0.2/d; }
-  }
-}
-
-function spawnRain() {
-  if (Math.random()>0.2) return;
-  const i = Math.floor(Math.random()*KEYS.length);
-  raindrops.push({ x:Math.random()*W, y:-20, vy:1.5+Math.random()*3, color:pal.colors[i%pal.colors.length], freq:freq(pal.notes[i%pal.notes.length]), type:i>=21?'sawtooth':'sine', size:8+Math.random()*12, played:false });
-  if (raindrops.length>40) raindrops.shift();
-}
-
-function updateRain() {
-  for (let i=raindrops.length-1; i>=0; i--) {
-    const r = raindrops[i]; r.y += r.vy;
-    if (!r.played) for (const n of notes) {
-      if (Math.hypot(r.x-n.x, r.y-n.y) < n.radius) {
-        tone(r.freq, r.type, 0.3, 0.06);
-        ripples.push({ x:r.x, y:r.y, color:r.color, size:5, maxSize:25, life:1 });
-        r.played = true; break;
-      }
-    }
-    if (r.y > H) {
-      if (!r.played) { paint(r.x, H-20, r.color, r.freq, r.type, r.size); tone(r.freq, r.type, 0.3, 0.05); }
-      raindrops.splice(i, 1);
-    }
-  }
-}
-
-function drawConstellation() {
-  ctx.save();
-  for (let i=0; i<notes.length; i++) {
-    for (let j=i+1; j<notes.length; j++) {
-      const d = Math.hypot(notes[i].x-notes[j].x, notes[i].y-notes[j].y);
-      if (d < 180) {
-        ctx.globalAlpha = (1-d/180)*0.12;
-        ctx.strokeStyle = notes[i].color;
-        ctx.lineWidth = 0.5;
-        ctx.beginPath();
-        ctx.moveTo(notes[i].x, notes[i].y);
-        ctx.lineTo(notes[j].x, notes[j].y);
-        ctx.stroke();
-      }
-    }
-  }
-  ctx.restore();
-}
-
-function drawBPMGrid() {
-  const bpm = 120;
-  const beat = (time % (60/bpm)) / (60/bpm);
-  ctx.save();
-  ctx.strokeStyle = pal.colors[0];
-  ctx.lineWidth = 0.5 + beat;
-  ctx.globalAlpha = 0.02 + beat*0.03;
-  for (let x=0; x<W; x+=80) { ctx.beginPath(); ctx.moveTo(x,0); ctx.lineTo(x,H); ctx.stroke(); }
-  for (let y=0; y<H; y+=80) { ctx.beginPath(); ctx.moveTo(0,y); ctx.lineTo(W,y); ctx.stroke(); }
-  ctx.restore();
-}
-
-function drawMirror() {
-  // Mirror notes across vertical axis
-  ctx.save();
-  ctx.globalAlpha = 0.08;
-  for (const n of notes) {
-    ctx.fillStyle = n.color;
-    ctx.beginPath();
-    ctx.arc(W-n.x, n.y, n.radius*0.6, 0, Math.PI*2);
-    ctx.fill();
-  }
-  ctx.restore();
-}
-
-// ═══════════════════════════════════════════════════════════════
-//  RECORDING & EXPORT
-// ═══════════════════════════════════════════════════════════════
-
-function replayRecording() {
-  if (!recordedNotes.length) return;
-  toast(`REPLAY ${recordedNotes.length} notes`);
-  const start = recordedNotes[0].time;
-  recordedNotes.forEach(n => {
-    setTimeout(() => triggerKey(n.key), n.time - start);
-  });
-  recordedNotes = [];
-}
-
-function saveCanvas() {
-  const link = document.createElement('a');
-  link.download = `sovereign-${Date.now()}.png`;
-  link.href = canvas.toDataURL();
-  link.click();
-  toast('SAVED');
-}
-
-// ═══════════════════════════════════════════════════════════════
-//  RENDER LOOP
-// ═══════════════════════════════════════════════════════════════
-
-function render() {
-  time += 0.016;
-  
-  if (screenShake > 0) { ctx.save(); ctx.translate((Math.random()-0.5)*screenShake,(Math.random()-0.5)*screenShake); screenShake*=0.85; if(screenShake<0.5)screenShake=0; }
-  
-  // Mode effects
-  if (mode==='GRAVITY') applyGravity();
-  if (mode==='RAIN') { spawnRain(); updateRain(); }
-  if (mode==='CONSTELLATION') drawConstellation();
-  if (mode==='BPM') drawBPMGrid();
-  if (mode==='MIRROR') drawMirror();
-  
-  // Ripples
-  for (let i=ripples.length-1; i>=0; i--) {
-    const r = ripples[i];
-    r.size += (r.maxSize-r.size)*0.07;
-    r.life -= 0.02;
-    if (r.life<=0) { ripples.splice(i,1); continue; }
-    ctx.globalAlpha = r.life*0.3;
-    ctx.strokeStyle = r.color;
-    ctx.lineWidth = 1.5*r.life;
-    ctx.beginPath(); ctx.arc(r.x,r.y,r.size,0,Math.PI*2); ctx.stroke();
-  }
-  
-  // Rain
-  for (const r of raindrops) {
-    ctx.globalAlpha = 0.4;
-    ctx.fillStyle = r.color;
-    ctx.beginPath(); ctx.arc(r.x,r.y,r.size*0.2,0,Math.PI*2); ctx.fill();
-  }
-  
-  // Particles
-  for (let i=particles.length-1; i>=0; i--) {
-    const p = particles[i];
-    p.x+=p.vx; p.y+=p.vy; p.vx*=0.96; p.vy*=0.96; p.life-=0.014;
-    if (p.life<=0) { particles.splice(i,1); continue; }
-    ctx.globalAlpha = p.life*0.5;
-    ctx.fillStyle = p.color;
-    ctx.beginPath(); ctx.arc(p.x,p.y,p.size*p.life,0,Math.PI*2); ctx.fill();
-  }
-  
-  // Audio-reactive
-  if (analyser) {
-    const data = new Uint8Array(analyser.frequencyBinCount);
-    analyser.getByteFrequencyData(data);
-    let energy = 0;
-    for (let i=0; i<data.length; i++) energy += data[i];
-    energy /= data.length*255;
-    
-    if (energy > 0.08) {
-      const grad = ctx.createRadialGradient(W/2,H/2,0,W/2,H/2,200+energy*200);
-      grad.addColorStop(0, pal.glow+'08');
-      grad.addColorStop(1, 'transparent');
-      ctx.fillStyle = grad;
-      ctx.globalAlpha = 0.3+energy*0.3;
-      ctx.fillRect(0,0,W,H);
-    }
-    
-    // Edge frequency bars
-    ctx.globalAlpha = 0.03;
-    for (let i=0; i<data.length; i++) {
-      const v = data[i]/255;
-      if (v<0.08) continue;
-      ctx.fillStyle = pal.colors[i%pal.colors.length];
-      ctx.fillRect((i/data.length)*W, H-v*40-80, 2, v*40); // above piano
-    }
-  }
-  
-  if (screenShake > 0) ctx.restore();
-  
-  // Cursor
-  ctx.save();
-  ctx.strokeStyle = '#fff';
-  ctx.lineWidth = 1;
-  ctx.globalAlpha = 0.5;
-  ctx.beginPath();
-  ctx.moveTo(mouseX-8,mouseY); ctx.lineTo(mouseX-3,mouseY);
-  ctx.moveTo(mouseX+3,mouseY); ctx.lineTo(mouseX+8,mouseY);
-  ctx.moveTo(mouseX,mouseY-8); ctx.lineTo(mouseX,mouseY-3);
-  ctx.moveTo(mouseX,mouseY+3); ctx.lineTo(mouseX,mouseY+8);
-  ctx.stroke();
-  
-  // Color ring when hovering note
-  for (const n of notes) {
-    if (Math.hypot(mouseX-n.x, mouseY-n.y) < n.radius*1.4) {
-      ctx.strokeStyle = n.color;
-      ctx.globalAlpha = 0.35;
-      ctx.beginPath(); ctx.arc(mouseX, mouseY, 12, 0, Math.PI*2); ctx.stroke();
-      break;
-    }
-  }
-  
-  ctx.globalAlpha = 0.8;
-  ctx.fillStyle = '#fff';
-  ctx.beginPath(); ctx.arc(mouseX,mouseY,1.5,0,Math.PI*2); ctx.fill();
-  ctx.restore();
-  
-  // HUD
-  document.getElementById('h-notes').textContent = `${notes.length} notes`;
-  
-  requestAnimationFrame(render);
-}
-
-render();
-</script>
-</body>
-</html>

portals.json

@@ -6,6 +6,24 @@
     "status": "online",
     "color": "#ff6600",
     "role": "pilot",
+    "position": { "x": 15, "y": 0, "z": -10 },
+    "rotation": { "y": -0.5 },
+    "portal_type": "game-world",
+    "world_category": "rpg",
+    "environment": "local",
+    "access_mode": "operator",
+    "readiness_state": "prototype",
+    "readiness_steps": {
+      "prototype": { "label": "Prototype", "done": true },
+      "runtime_ready": { "label": "Runtime Ready", "done": false },
+      "launched": { "label": "Launched", "done": false },
+      "harness_bridged": { "label": "Harness Bridged", "done": false }
+    },
+    "blocked_reason": null,
+    "telemetry_source": "hermes-harness:morrowind",
+    "owner": "Timmy",
+    "app_id": 22320,
+    "window_title": "OpenMW",
     "position": {
       "x": 15,
       "y": 0,
@@ -14,38 +32,12 @@
     "rotation": {
       "y": -0.5
     },
-    "portal_type": "game-world",
-    "world_category": "rpg",
-    "environment": "local",
-    "access_mode": "operator",
-    "readiness_state": "prototype",
-    "readiness_steps": {
-      "prototype": {
-        "label": "Prototype",
-        "done": true
-      },
-      "runtime_ready": {
-        "label": "Runtime Ready",
-        "done": false
-      },
-      "launched": {
-        "label": "Launched",
-        "done": false
-      },
-      "harness_bridged": {
-        "label": "Harness Bridged",
-        "done": false
-      }
-    },
-    "blocked_reason": null,
-    "telemetry_source": "hermes-harness:morrowind",
-    "owner": "Timmy",
-    "app_id": 22320,
-    "window_title": "OpenMW",
     "destination": {
       "url": null,
       "type": "harness",
       "action_label": "Enter Vvardenfell",
+      "params": { "world": "vvardenfell" }
+    }
       "params": {
         "world": "vvardenfell"
       }
@@ -62,6 +54,8 @@
     "status": "downloaded",
     "color": "#ffd700",
     "role": "pilot",
+    "position": { "x": -15, "y": 0, "z": -10 },
+    "rotation": { "y": 0.5 },
     "position": {
       "x": -15,
       "y": 0,
@@ -116,6 +110,8 @@
     "status": "online",
     "color": "#4af0c0",
     "role": "timmy",
+    "position": { "x": 0, "y": 0, "z": -20 },
+    "rotation": { "y": 0 },
     "position": {
       "x": 0,
       "y": 0,
@@ -144,6 +140,8 @@
     "status": "online",
     "color": "#0066ff",
     "role": "timmy",
+    "position": { "x": 25, "y": 0, "z": 0 },
+    "rotation": { "y": -1.57 },
     "position": {
       "x": 25,
       "y": 0,
@@ -171,6 +169,8 @@
     "status": "online",
     "color": "#ffd700",
     "role": "timmy",
+    "position": { "x": -25, "y": 0, "z": 0 },
+    "rotation": { "y": 1.57 },
     "position": {
       "x": -25,
       "y": 0,
@@ -196,6 +196,8 @@
     "status": "online",
     "color": "#4af0c0",
     "role": "reflex",
+    "position": { "x": 15, "y": 0, "z": 10 },
+    "rotation": { "y": -2.5 },
     "position": {
       "x": 15,
       "y": 0,
@@ -224,6 +226,8 @@
     "status": "standby",
     "color": "#ff4466",
     "role": "reflex",
+    "position": { "x": -15, "y": 0, "z": 10 },
+    "rotation": { "y": 2.5 },
     "position": {
       "x": -15,
       "y": 0,
@@ -241,55 +245,5 @@
     },
     "agents_present": [],
     "interaction_ready": false
-  },
-  {
-    "id": "playground",
-    "name": "Sound Playground",
-    "description": "Interactive audio-visual experience. Paint with sound, create music visually.",
-    "status": "online",
-    "color": "#ff00ff",
-    "role": "creative",
-    "position": {
-      "x": 10,
-      "y": 0,
-      "z": 15
-    },
-    "rotation": {
-      "y": -0.7
-    },
-    "portal_type": "creative-tool",
-    "world_category": "audio-visual",
-    "environment": "production",
-    "access_mode": "visitor",
-    "readiness_state": "online",
-    "readiness_steps": {
-      "prototype": {
-        "label": "Prototype",
-        "done": true
-      },
-      "runtime_ready": {
-        "label": "Runtime Ready",
-        "done": true
-      },
-      "launched": {
-        "label": "Launched",
-        "done": true
-      },
-      "harness_bridged": {
-        "label": "Harness Bridged",
-        "done": true
-      }
-    },
-    "blocked_reason": null,
-    "telemetry_source": "playground",
-    "owner": "Timmy",
-    "destination": {
-      "url": "./playground/playground.html",
-      "type": "local",
-      "action_label": "Enter Playground",
-      "params": {}
-    },
-    "agents_present": [],
-    "interaction_ready": true
   }
 ]

tests/test_agent_memory.py

@@ -0,0 +1,377 @@
+"""
+Tests for agent memory — cross-session agent memory via MemPalace.
+
+Tests the memory module, hooks, and session mining without requiring
+a live ChromaDB instance. Uses mocking for the MemPalace backend.
+"""
+
+from __future__ import annotations
+
+import json
+import tempfile
+from pathlib import Path
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from agent.memory import (
+    AgentMemory,
+    MemoryContext,
+    SessionTranscript,
+    create_agent_memory,
+)
+from agent.memory_hooks import MemoryHooks
+
+
+# ---------------------------------------------------------------------------
+# SessionTranscript tests
+# ---------------------------------------------------------------------------
+
+
+class TestSessionTranscript:
+    def test_create(self):
+        t = SessionTranscript(agent_name="test", wing="wing_test")
+        assert t.agent_name == "test"
+        assert t.wing == "wing_test"
+        assert len(t.entries) == 0
+
+    def test_add_user_turn(self):
+        t = SessionTranscript(agent_name="test", wing="wing_test")
+        t.add_user_turn("Hello")
+        assert len(t.entries) == 1
+        assert t.entries[0]["role"] == "user"
+        assert t.entries[0]["text"] == "Hello"
+
+    def test_add_agent_turn(self):
+        t = SessionTranscript(agent_name="test", wing="wing_test")
+        t.add_agent_turn("Response")
+        assert t.entries[0]["role"] == "agent"
+
+    def test_add_tool_call(self):
+        t = SessionTranscript(agent_name="test", wing="wing_test")
+        t.add_tool_call("shell", "ls", "file1 file2")
+        assert t.entries[0]["role"] == "tool"
+        assert t.entries[0]["tool"] == "shell"
+
+    def test_summary_empty(self):
+        t = SessionTranscript(agent_name="test", wing="wing_test")
+        assert t.summary() == "Empty session."
+
+    def test_summary_with_entries(self):
+        t = SessionTranscript(agent_name="test", wing="wing_test")
+        t.add_user_turn("Do something")
+        t.add_agent_turn("Done")
+        t.add_tool_call("shell", "ls", "ok")
+
+        summary = t.summary()
+        assert "USER: Do something" in summary
+        assert "AGENT: Done" in summary
+        assert "TOOL(shell): ok" in summary
+
+    def test_text_truncation(self):
+        t = SessionTranscript(agent_name="test", wing="wing_test")
+        long_text = "x" * 5000
+        t.add_user_turn(long_text)
+        assert len(t.entries[0]["text"]) == 2000
+
+
+# ---------------------------------------------------------------------------
+# MemoryContext tests
+# ---------------------------------------------------------------------------
+
+
+class TestMemoryContext:
+    def test_empty_context(self):
+        ctx = MemoryContext()
+        assert ctx.to_prompt_block() == ""
+
+    def test_unloaded_context(self):
+        ctx = MemoryContext()
+        ctx.loaded = False
+        assert ctx.to_prompt_block() == ""
+
+    def test_loaded_with_data(self):
+        ctx = MemoryContext()
+        ctx.loaded = True
+        ctx.recent_diaries = [
+            {"text": "Fixed PR #1386", "timestamp": "2026-04-13T10:00:00Z"}
+        ]
+        ctx.facts = [
+            {"text": "Bezalel runs on VPS Beta", "score": 0.95}
+        ]
+        ctx.relevant_memories = [
+            {"text": "Changed CI runner", "score": 0.87}
+        ]
+
+        block = ctx.to_prompt_block()
+        assert "Recent Session Summaries" in block
+        assert "Fixed PR #1386" in block
+        assert "Known Facts" in block
+        assert "Bezalel runs on VPS Beta" in block
+        assert "Relevant Past Memories" in block
+
+    def test_loaded_empty(self):
+        ctx = MemoryContext()
+        ctx.loaded = True
+        # No data — should return empty string
+        assert ctx.to_prompt_block() == ""
+
+
+# ---------------------------------------------------------------------------
+# AgentMemory tests (with mocked MemPalace)
+# ---------------------------------------------------------------------------
+
+
+class TestAgentMemory:
+    def test_create(self):
+        mem = AgentMemory(agent_name="bezalel")
+        assert mem.agent_name == "bezalel"
+        assert mem.wing == "wing_bezalel"
+
+    def test_custom_wing(self):
+        mem = AgentMemory(agent_name="bezalel", wing="custom_wing")
+        assert mem.wing == "custom_wing"
+
+    def test_factory(self):
+        mem = create_agent_memory("ezra")
+        assert mem.agent_name == "ezra"
+        assert mem.wing == "wing_ezra"
+
+    def test_unavailable_graceful(self):
+        """Test graceful degradation when MemPalace is unavailable."""
+        mem = AgentMemory(agent_name="test")
+        mem._available = False  # Force unavailable
+
+        # Should not raise
+        ctx = mem.recall_context("test query")
+        assert ctx.loaded is False
+        assert ctx.error == "MemPalace unavailable"
+
+        # remember returns None
+        assert mem.remember("test") is None
+
+        # search returns empty
+        assert mem.search("test") == []
+
+    def test_start_end_session(self):
+        mem = AgentMemory(agent_name="test")
+        mem._available = False
+
+        transcript = mem.start_session()
+        assert isinstance(transcript, SessionTranscript)
+        assert mem._transcript is not None
+
+        doc_id = mem.end_session()
+        assert mem._transcript is None
+
+    def test_remember_graceful_when_unavailable(self):
+        """Test remember returns None when MemPalace is unavailable."""
+        mem = AgentMemory(agent_name="test")
+        mem._available = False
+
+        doc_id = mem.remember("some important fact")
+        assert doc_id is None
+
+    def test_write_diary_from_transcript(self):
+        mem = AgentMemory(agent_name="test")
+        mem._available = False
+
+        transcript = mem.start_session()
+        transcript.add_user_turn("Hello")
+        transcript.add_agent_turn("Hi there")
+
+        # Write diary should handle unavailable gracefully
+        doc_id = mem.write_diary()
+        assert doc_id is None  # MemPalace unavailable
+
+
+# ---------------------------------------------------------------------------
+# MemoryHooks tests
+# ---------------------------------------------------------------------------
+
+
+class TestMemoryHooks:
+    def test_create(self):
+        hooks = MemoryHooks(agent_name="bezalel")
+        assert hooks.agent_name == "bezalel"
+        assert hooks.is_active is False
+
+    def test_session_lifecycle(self):
+        hooks = MemoryHooks(agent_name="test")
+
+        # Force memory unavailable
+        hooks._memory = AgentMemory(agent_name="test")
+        hooks._memory._available = False
+
+        # Start session
+        block = hooks.on_session_start()
+        assert hooks.is_active is True
+        assert block == ""  # No memory available
+
+        # Record turns
+        hooks.on_user_turn("Hello")
+        hooks.on_agent_turn("Hi")
+        hooks.on_tool_call("shell", "ls", "ok")
+
+        # Record decision
+        hooks.on_important_decision("Switched to self-hosted CI")
+
+        # End session
+        doc_id = hooks.on_session_end()
+        assert hooks.is_active is False
+
+    def test_hooks_before_session(self):
+        """Hooks before session start should be no-ops."""
+        hooks = MemoryHooks(agent_name="test")
+        hooks._memory = AgentMemory(agent_name="test")
+        hooks._memory._available = False
+
+        # Should not raise
+        hooks.on_user_turn("Hello")
+        hooks.on_agent_turn("Response")
+
+    def test_hooks_after_session_end(self):
+        """Hooks after session end should be no-ops."""
+        hooks = MemoryHooks(agent_name="test")
+        hooks._memory = AgentMemory(agent_name="test")
+        hooks._memory._available = False
+
+        hooks.on_session_start()
+        hooks.on_session_end()
+
+        # Should not raise
+        hooks.on_user_turn("Late message")
+        doc_id = hooks.on_session_end()
+        assert doc_id is None
+
+    def test_search_during_session(self):
+        hooks = MemoryHooks(agent_name="test")
+        hooks._memory = AgentMemory(agent_name="test")
+        hooks._memory._available = False
+
+        results = hooks.search("some query")
+        assert results == []
+
+
+# ---------------------------------------------------------------------------
+# Session mining tests
+# ---------------------------------------------------------------------------
+
+
+class TestSessionMining:
+    def test_parse_session_file(self):
+        from bin.memory_mine import parse_session_file
+
+        with tempfile.NamedTemporaryFile(mode="w", suffix=".jsonl", delete=False) as f:
+            f.write('{"role": "user", "content": "Hello"}\n')
+            f.write('{"role": "assistant", "content": "Hi there"}\n')
+            f.write('{"role": "tool", "name": "shell", "content": "ls output"}\n')
+            f.write("\n")  # blank line
+            f.write("not json\n")  # malformed
+            path = Path(f.name)
+
+        turns = parse_session_file(path)
+        assert len(turns) == 3
+        assert turns[0]["role"] == "user"
+        assert turns[1]["role"] == "assistant"
+        assert turns[2]["role"] == "tool"
+        path.unlink()
+
+    def test_summarize_session(self):
+        from bin.memory_mine import summarize_session
+
+        turns = [
+            {"role": "user", "content": "Check CI"},
+            {"role": "assistant", "content": "Running CI check..."},
+            {"role": "tool", "name": "shell", "content": "5 tests passed"},
+            {"role": "assistant", "content": "CI is healthy"},
+        ]
+
+        summary = summarize_session(turns, "bezalel")
+        assert "bezalel" in summary
+        assert "Check CI" in summary
+        assert "shell" in summary
+
+    def test_summarize_empty(self):
+        from bin.memory_mine import summarize_session
+
+        assert summarize_session([], "test") == "Empty session."
+
+    def test_find_session_files(self, tmp_path):
+        from bin.memory_mine import find_session_files
+
+        # Create some test files
+        (tmp_path / "session1.jsonl").write_text("{}\n")
+        (tmp_path / "session2.jsonl").write_text("{}\n")
+        (tmp_path / "notes.txt").write_text("not a session")
+
+        files = find_session_files(tmp_path, days=365)
+        assert len(files) == 2
+        assert all(f.suffix == ".jsonl" for f in files)
+
+    def test_find_session_files_missing_dir(self):
+        from bin.memory_mine import find_session_files
+
+        files = find_session_files(Path("/nonexistent/path"), days=7)
+        assert files == []
+
+    def test_mine_session_dry_run(self, tmp_path):
+        from bin.memory_mine import mine_session
+
+        session_file = tmp_path / "test.jsonl"
+        session_file.write_text(
+            '{"role": "user", "content": "Hello"}\n'
+            '{"role": "assistant", "content": "Hi"}\n'
+        )
+
+        result = mine_session(session_file, wing="wing_test", dry_run=True)
+        assert result is None  # dry run doesn't store
+
+    def test_mine_session_empty_file(self, tmp_path):
+        from bin.memory_mine import mine_session
+
+        session_file = tmp_path / "empty.jsonl"
+        session_file.write_text("")
+
+        result = mine_session(session_file, wing="wing_test")
+        assert result is None
+
+
+# ---------------------------------------------------------------------------
+# Integration test — full lifecycle
+# ---------------------------------------------------------------------------
+
+
+class TestFullLifecycle:
+    """Test the full session lifecycle without a real MemPalace backend."""
+
+    def test_full_session_flow(self):
+        hooks = MemoryHooks(agent_name="bezalel")
+
+        # Force memory unavailable
+        hooks._memory = AgentMemory(agent_name="bezalel")
+        hooks._memory._available = False
+
+        # 1. Session start
+        context_block = hooks.on_session_start("What CI issues do I have?")
+        assert isinstance(context_block, str)
+
+        # 2. User asks question
+        hooks.on_user_turn("Check CI pipeline health")
+
+        # 3. Agent uses tool
+        hooks.on_tool_call("shell", "pytest tests/", "12 passed")
+
+        # 4. Agent responds
+        hooks.on_agent_turn("CI pipeline is healthy. All 12 tests passing.")
+
+        # 5. Important decision
+        hooks.on_important_decision("Decided to keep current CI runner", room="forge")
+
+        # 6. More interaction
+        hooks.on_user_turn("Good, check memory integration next")
+        hooks.on_agent_turn("Will test agent.memory module")
+
+        # 7. Session end
+        doc_id = hooks.on_session_end()
+        assert hooks.is_active is False