htmlgraph 0.9.3__py3-none-any.whl → 0.27.5__py3-none-any.whl

htmlgraph/session_manager.py

@@ -9,18 +9,27 @@ Provides:
 - WIP limits enforcement
 """
 
-import os
-import re
 import fnmatch
-from datetime import datetime, timedelta
+import logging
+import re
+from datetime import datetime, timedelta, timezone
 from pathlib import Path
-from typing import Any, Literal
+from typing import Any
 
-from htmlgraph.models import Node, Session, ActivityEntry
+logger = logging.getLogger(__name__)
+
+from htmlgraph.agent_detection import detect_agent_name
+from htmlgraph.converter import (
+    SessionConverter,
+    dict_to_node,
+)
+from htmlgraph.event_log import EventRecord, JsonlEventLog
+from htmlgraph.exceptions import SessionNotFoundError
 from htmlgraph.graph import HtmlGraph
-from htmlgraph.converter import session_to_html, html_to_session, SessionConverter, dict_to_node
-from htmlgraph.event_log import JsonlEventLog, EventRecord
 from htmlgraph.ids import generate_id
+from htmlgraph.models import ActivityEntry, ErrorEntry, Node, Session
+from htmlgraph.services import ClaimingService
+from htmlgraph.spike_index import ActiveAutoSpikeIndex
 
 
 class SessionManager:
@@ -74,6 +83,8 @@ class SessionManager:
         graph_dir: str | Path = ".htmlgraph",
         wip_limit: int = DEFAULT_WIP_LIMIT,
         session_dedupe_window_seconds: int = DEFAULT_SESSION_DEDUPE_WINDOW_SECONDS,
+        features_graph: HtmlGraph | None = None,
+        bugs_graph: HtmlGraph | None = None,
     ):
         """
         Initialize SessionManager.
@@ -81,6 +92,9 @@ class SessionManager:
         Args:
             graph_dir: Directory containing HtmlGraph data
             wip_limit: Maximum features in progress simultaneously
+            session_dedupe_window_seconds: Deduplication window for sessions
+            features_graph: Optional pre-initialized HtmlGraph for features (avoids double-loading)
+            bugs_graph: Optional pre-initialized HtmlGraph for bugs (avoids double-loading)
         """
         self.graph_dir = Path(graph_dir)
         self.wip_limit = wip_limit
@@ -99,13 +113,41 @@ class SessionManager:
         # Session converter
         self.session_converter = SessionConverter(self.sessions_dir)
 
-        # Feature graphs
-        self.features_graph = HtmlGraph(self.features_dir, auto_load=True)
-        self.bugs_graph = HtmlGraph(self.bugs_dir, auto_load=True)
+        # Feature graphs - reuse provided instances to avoid double-loading, or create new with lazy loading
+        # Note: Use 'is not None' check because HtmlGraph.__bool__ returns False when empty
+        self.features_graph = (
+            features_graph
+            if features_graph is not None
+            else HtmlGraph(self.features_dir, auto_load=False)
+        )
+        self.bugs_graph = (
+            bugs_graph
+            if bugs_graph is not None
+            else HtmlGraph(self.bugs_dir, auto_load=False)
+        )
+
+        # Claiming service (handles feature claims/releases)
+        self.claiming_service = ClaimingService(
+            features_graph=self.features_graph,
+            bugs_graph=self.bugs_graph,
+            session_manager=self,
+        )
 
         # Cache for active session
         self._active_session: Session | None = None
 
+        # Cache for active sessions list (invalidated on session lifecycle changes)
+        self._active_sessions_cache: list[Session] | None = None
+        self._sessions_cache_dirty: bool = True
+
+        # Cache for active features (invalidated on start/complete/release)
+        self._active_features_cache: list[Node] | None = None
+        self._features_cache_dirty: bool = True
+
+        # Fast index for active auto-generated spikes (avoids scanning all spike files)
+        self._spike_index = ActiveAutoSpikeIndex(self.graph_dir)
+        self._active_auto_spikes: set[str] = self._spike_index.get_all()
+
         # Append-only event log (Git-friendly source of truth for activities)
         self.events_dir = self.graph_dir / "events"
         self.event_log = JsonlEventLog(self.events_dir)
@@ -115,10 +157,22 @@ class SessionManager:
     # =========================================================================
 
     def _list_active_sessions(self) -> list[Session]:
-        """Return all active sessions found on disk."""
-        return [s for s in self.session_converter.load_all() if s.status == "active"]
+        """
+        Return all active sessions found on disk.
+
+        Uses caching to avoid repeated file I/O. The cache is invalidated
+        automatically when sessions are created, ended, or marked as stale.
+        """
+        if self._sessions_cache_dirty or self._active_sessions_cache is None:
+            self._active_sessions_cache = [
+                s for s in self.session_converter.load_all() if s.status == "active"
+            ]
+            self._sessions_cache_dirty = False
+        return self._active_sessions_cache
 
-    def _choose_canonical_active_session(self, sessions: list[Session]) -> Session | None:
+    def _choose_canonical_active_session(
+        self, sessions: list[Session]
+    ) -> Session | None:
         """Choose a stable 'canonical' session when multiple are active."""
         if not sessions:
             return None
@@ -132,11 +186,12 @@ class SessionManager:
         """Mark a session as stale (kept for history but not considered active)."""
         if session.status != "active":
             return
-        now = datetime.now()
+        now = datetime.now(timezone.utc)
         session.status = "stale"
         session.ended_at = now
         session.last_activity = now
         self.session_converter.save(session)
+        self._sessions_cache_dirty = True
 
     def normalize_active_sessions(self) -> dict[str, int]:
         """
@@ -170,26 +225,32 @@ class SessionManager:
     def start_session(
         self,
         session_id: str | None = None,
-        agent: str = "claude-code",
+        agent: str | None = None,
         is_subagent: bool = False,
         continued_from: str | None = None,
         start_commit: str | None = None,
         title: str | None = None,
+        parent_session_id: str | None = None,
     ) -> Session:
         """
         Start a new session.
 
         Args:
             session_id: Unique session identifier (auto-generated if None)
-            agent: Agent name (e.g., "claude-code", "haiku")
+            agent: Agent name (auto-detected if None)
             is_subagent: True if this is a Task subagent
             continued_from: Previous session ID if continuing
             start_commit: Git commit hash at session start
             title: Optional human-readable title
+            parent_session_id: ID of parent session (for subagents)
 
         Returns:
             New Session instance
         """
+        # Auto-detect agent if not provided
+        if agent is None:
+            agent = detect_agent_name()
+
         now = datetime.now()
 
         # Auto-generate collision-resistant session ID if not provided
@@ -209,6 +270,7 @@ class SessionManager:
             if title and not existing.title:
                 existing.title = title
             self.session_converter.save(existing)
+            self._sessions_cache_dirty = True
             self._active_session = existing
             return existing
 
@@ -220,7 +282,8 @@ class SessionManager:
         # The session will only end when the Stop hook is called (process terminates).
         if not is_subagent:
             active_sessions = [
-                s for s in self._list_active_sessions()
+                s
+                for s in self._list_active_sessions()
                 if (not s.is_subagent) and s.agent == agent
             ]
             canonical = self._choose_canonical_active_session(active_sessions)
@@ -231,6 +294,7 @@ class SessionManager:
                 self._active_session = canonical
                 canonical.last_activity = now  # Update activity timestamp
                 self.session_converter.save(canonical)
+                self._sessions_cache_dirty = True
                 return canonical
 
             # If we're truly starting a new session (different commit), mark old sessions as stale.
@@ -247,21 +311,273 @@ class SessionManager:
             started_at=now,
             last_activity=now,
             title=title or "",
+            parent_session=parent_session_id,
         )
 
         # Add session start event
-        session.add_activity(ActivityEntry(
-            tool="SessionStart",
-            summary="Session started",
-            timestamp=now,
-        ))
+        session.add_activity(
+            ActivityEntry(
+                tool="SessionStart",
+                summary="Session started",
+                timestamp=now,
+            )
+        )
+
+        # Set parent session in environment for subsequent subprocesses (e.g. HeadlessSpawner)
+        # This ensures that any tools spawned by this session link back to it
+        import os
+
+        os.environ["HTMLGRAPH_PARENT_SESSION"] = session.id
 
         # Save to disk
         self.session_converter.save(session)
+        self._sessions_cache_dirty = True
         self._active_session = session
 
+        # Complete any lingering transition spikes from previous conversations
+        # This marks the end of the previous conversation's transition period
+        self._complete_transition_spikes_on_conversation_start(session.agent)
+
+        # Auto-create session-init spike for transitional activities
+        self._create_session_init_spike(session)
+
         return session
 
+    def _create_session_init_spike(self, session: Session) -> Node | None:
+        """
+        Auto-create a session-init spike to catch pre-feature activities.
+
+        This spike captures work done before the first feature is started:
+        - Session startup, reviewing context
+        - Planning what to work on
+        - General exploration
+
+        The spike auto-completes when the first feature is started.
+        """
+        from htmlgraph.converter import NodeConverter
+
+        spike_id = f"spike-init-{session.id[:8]}"
+
+        # Check if spike already exists (idempotency)
+        spike_converter = NodeConverter(self.graph_dir / "spikes")
+        existing = spike_converter.load(spike_id)
+        if existing:
+            # Add to index if it's still active
+            if existing.status == "in-progress":
+                self._active_auto_spikes.add(existing.id)
+                self._spike_index.add(existing.id, "session-init", session.id)
+            return existing
+
+        # Create session-init spike
+        spike = Node(
+            id=spike_id,
+            title=f"Session Init: {session.agent}",
+            type="spike",
+            status="in-progress",
+            priority="low",
+            spike_subtype="session-init",
+            auto_generated=True,
+            session_id=session.id,
+            model_name=session.agent,  # Store agent name as model
+            content="Auto-generated spike for session startup activities.\n\nCaptures work before first feature is started:\n- Context review\n- Planning\n- Exploration\n\nAuto-completes when first feature is claimed.",
+        )
+
+        # Save spike
+        spike_converter.save(spike)
+
+        # Add to active auto-spikes index (both in-memory and persistent)
+        self._active_auto_spikes.add(spike.id)
+        self._spike_index.add(spike.id, "session-init", session.id)
+
+        # Link session to spike
+        if spike.id not in session.worked_on:
+            session.worked_on.append(spike.id)
+            self.session_converter.save(session)
+
+        return spike
+
+    def _create_transition_spike(
+        self, session: Session, from_feature_id: str
+    ) -> Node | None:
+        """
+        Auto-create a transition spike after feature completion.
+
+        This spike captures work done between features:
+        - Post-completion cleanup
+        - Review and planning
+        - Context switching
+
+        The spike auto-completes when the next feature is started.
+        """
+        from htmlgraph.converter import NodeConverter
+
+        spike_id = generate_id(node_type="spike", title="transition")
+
+        # Create transition spike
+        spike = Node(
+            id=spike_id,
+            title=f"Transition from {from_feature_id[:12]}",
+            type="spike",
+            status="in-progress",
+            priority="low",
+            spike_subtype="transition",
+            auto_generated=True,
+            session_id=session.id,
+            from_feature_id=from_feature_id,
+            model_name=session.agent,
+            content=f"Auto-generated transition spike.\n\nCaptures post-completion activities:\n- Cleanup and review\n- Planning next work\n- Context switching\n\nFrom: {from_feature_id}\nAuto-completes when next feature is started.",
+        )
+
+        # Save spike
+        spike_converter = NodeConverter(self.graph_dir / "spikes")
+        spike_converter.save(spike)
+
+        # Add to active auto-spikes index (both in-memory and persistent)
+        self._active_auto_spikes.add(spike.id)
+        self._spike_index.add(spike.id, "transition", session.id)
+
+        # Link session to spike
+        if spike.id not in session.worked_on:
+            session.worked_on.append(spike.id)
+            self.session_converter.save(session)
+
+        return spike
+
+    def _complete_transition_spikes_on_conversation_start(
+        self, agent: str
+    ) -> list[Node]:
+        """
+        Complete transition spikes from previous conversations when a new conversation starts.
+
+        This implements the state management pattern:
+        1. Work item completes → creates transition spike
+        2. New conversation starts → completes previous transition spike
+        3. New work item starts → completes session-init spike
+
+        Args:
+            agent: Agent starting the new conversation
+
+        Returns:
+            List of completed transition spikes
+        """
+        from htmlgraph.converter import NodeConverter
+
+        spike_converter = NodeConverter(self.graph_dir / "spikes")
+        completed_spikes = []
+
+        # Complete only TRANSITION spikes (not session-init, which should persist)
+        for spike_id in list(self._active_auto_spikes):
+            spike = spike_converter.load(spike_id)
+
+            if not spike:
+                self._active_auto_spikes.discard(spike_id)
+                self._spike_index.remove(spike_id)
+                continue
+
+            # Only complete transition spikes on conversation start
+            if not (
+                spike.type == "spike"
+                and getattr(spike, "auto_generated", False)
+                and getattr(spike, "spike_subtype", None) == "transition"
+                and spike.status == "in-progress"
+            ):
+                continue
+
+            # Complete the transition spike
+            spike.status = "done"
+            spike.updated = datetime.now()
+            spike.properties["completed_by"] = "conversation-start"
+
+            spike_converter.save(spike)
+            completed_spikes.append(spike)
+            self._active_auto_spikes.discard(spike_id)
+            self._spike_index.remove(spike_id)
+
+            logger.debug(f"Completed transition spike {spike_id} on conversation start")
+
+        return completed_spikes
+
+    def _complete_active_auto_spikes(
+        self, agent: str, to_feature_id: str
+    ) -> list[Node]:
+        """
+        Auto-complete any active auto-generated spikes when a feature starts.
+
+        When starting a regular feature, the transitional period is over,
+        so we complete session-init and transition spikes.
+
+        Args:
+            agent: Agent starting the feature
+            to_feature_id: Feature being started
+
+        Returns:
+            List of completed spikes
+        """
+        from htmlgraph.converter import NodeConverter
+
+        spike_converter = NodeConverter(self.graph_dir / "spikes")
+        completed_spikes = []
+
+        # Only load spikes we know are active from the index
+        # This avoids the expensive load_all() operation
+        for spike_id in list(self._active_auto_spikes):
+            spike = spike_converter.load(spike_id)
+
+            # Safety check: verify it's actually an active auto-spike
+            if not spike:
+                # Spike was deleted or doesn't exist - remove from index
+                self._active_auto_spikes.discard(spike_id)
+                self._spike_index.remove(spike_id)
+                continue
+
+            if not (
+                spike.type == "spike"
+                and spike.auto_generated
+                and spike.spike_subtype
+                in ("session-init", "transition", "conversation-init")
+                and spike.status == "in-progress"
+            ):
+                # Spike is no longer active - remove from index
+                self._active_auto_spikes.discard(spike_id)
+                self._spike_index.remove(spike_id)
+                continue
+
+            # Complete the spike
+            spike.status = "done"
+            spike.updated = datetime.now()
+            spike.to_feature_id = (
+                to_feature_id  # Record what feature we transitioned to
+            )
+
+            spike_converter.save(spike)
+            completed_spikes.append(spike)
+
+            # Remove from active index (both in-memory and persistent) since it's now completed
+            self._active_auto_spikes.discard(spike_id)
+            self._spike_index.remove(spike_id)
+
+        # Import transcript when auto-spikes complete (work boundary)
+        if completed_spikes:
+            session = self.get_active_session(agent=agent)
+            if session and session.transcript_id:
+                try:
+                    from htmlgraph.transcript import TranscriptReader
+
+                    reader = TranscriptReader()
+                    transcript = reader.read_session(session.transcript_id)
+                    if transcript:
+                        self.import_transcript_events(
+                            session_id=session.id,
+                            transcript_session=transcript,
+                            overwrite=True,
+                        )
+                except Exception as e:
+                    logger.warning(
+                        f"Failed to import transcript events on auto-spike completion: {e}"
+                    )
+
+        return completed_spikes
+
     def get_session(self, session_id: str) -> Session | None:
         """Get a session by ID."""
         if self._active_session and self._active_session.id == session_id:
@@ -276,7 +592,7 @@ class SessionManager:
         if not sessions:
             return None
 
-        def sort_key(session: Session):
+        def sort_key(session: Session) -> datetime:
             if session.ended_at:
                 return session.ended_at
             if session.last_activity:
@@ -422,16 +738,19 @@ class SessionManager:
             session.blockers = blockers
 
         session.end()
-        session.add_activity(ActivityEntry(
-            tool="SessionEnd",
-            summary="Session ended",
-            timestamp=datetime.now(),
-        ))
+        session.add_activity(
+            ActivityEntry(
+                tool="SessionEnd",
+                summary="Session ended",
+                timestamp=datetime.now(timezone.utc),
+            )
+        )
 
         # Release all features claimed by this session
         self.release_session_features(session_id)
 
         self.session_converter.save(session)
+        self._sessions_cache_dirty = True
 
         if self._active_session and self._active_session.id == session_id:
             self._active_session = None
@@ -462,15 +781,169 @@ class SessionManager:
             updated = True
 
         if updated:
-            session.add_activity(ActivityEntry(
-                tool="SessionHandoff",
-                summary="Session handoff updated",
-                timestamp=datetime.now(),
-            ))
+            session.add_activity(
+                ActivityEntry(
+                    tool="SessionHandoff",
+                    summary="Session handoff updated",
+                    timestamp=datetime.now(),
+                )
+            )
             self.session_converter.save(session)
 
         return session
 
+    def continue_from_last(
+        self,
+        agent: str | None = None,
+        auto_create_session: bool = True,
+    ) -> tuple[Session | None, Any]:  # Returns (new_session, resume_info)
+        """
+        Continue work from the last completed session.
+
+        Loads context from the previous session including:
+        - Handoff notes and next focus
+        - Blockers
+        - Recommended context files
+        - Recent commits
+        - Features worked on
+
+        Args:
+            agent: Filter by agent (None = current agent)
+            auto_create_session: Create new session if True
+
+        Returns:
+            Tuple of (new_session, resume_info) or (None, None) if no previous session
+
+        Example:
+            >>> manager = SessionManager(".htmlgraph")
+            >>> new_session, resume = manager.continue_from_last(agent="claude")
+            >>> if resume:
+            ...     print(resume.summary)
+            ...     print(resume.recommended_files)
+        """
+        # Import handoff module
+        from typing import Any
+
+        from htmlgraph.sessions.handoff import SessionResume
+
+        # Create a minimal SDK-like object with just the directory
+        # to avoid circular dependency and database initialization issues
+        class MinimalSDK:
+            def __init__(self, directory: Path) -> None:
+                self._directory = directory
+
+        sdk: Any = MinimalSDK(self.graph_dir)
+        resume = SessionResume(sdk)
+
+        # Get last session
+        last_session = resume.get_last_session(agent=agent)
+        if not last_session:
+            return None, None
+
+        # Build resume info
+        resume_info = resume.build_resume_info(last_session)
+
+        # Create new session if requested
+        new_session = None
+        if auto_create_session:
+            from htmlgraph.ids import generate_id
+
+            session_id = generate_id("sess")
+            new_session = self.start_session(
+                session_id=session_id,
+                agent=agent or last_session.agent,
+                title=f"Continuing from {last_session.id}",
+            )
+
+            # Link to previous session
+            new_session.continued_from = last_session.id
+            self.session_converter.save(new_session)
+
+        return new_session, resume_info
+
+    def end_session_with_handoff(
+        self,
+        session_id: str,
+        summary: str | None = None,
+        next_focus: str | None = None,
+        blockers: list[str] | None = None,
+        keep_context: list[str] | None = None,
+        auto_recommend_context: bool = True,
+    ) -> Session | None:
+        """
+        End session with handoff information for next session.
+
+        Args:
+            session_id: Session to end
+            summary: What was accomplished (handoff notes)
+            next_focus: What should be done next
+            blockers: List of blockers preventing progress
+            keep_context: List of files to keep context for
+            auto_recommend_context: Auto-recommend files from git history
+
+        Returns:
+            Updated session or None
+
+        Example:
+            >>> manager.end_session_with_handoff(
+            ...     session_id="sess-123",
+            ...     summary="Completed OAuth integration",
+            ...     next_focus="Implement JWT token refresh",
+            ...     blockers=["Waiting for security review"],
+            ...     keep_context=["src/auth/oauth.py"]
+            ... )
+        """
+        from htmlgraph.sessions.handoff import (
+            ContextRecommender,
+            HandoffBuilder,
+        )
+
+        # Get session
+        session = self.get_session(session_id)
+        if not session:
+            return None
+
+        # Build handoff using HandoffBuilder
+        builder = HandoffBuilder(session)
+
+        if summary:
+            builder.add_summary(summary)
+
+        if next_focus:
+            builder.add_next_focus(next_focus)
+
+        if blockers:
+            builder.add_blockers(blockers)
+
+        if keep_context:
+            builder.add_context_files(keep_context)
+
+        # Auto-recommend context files
+        if auto_recommend_context:
+            recommender = ContextRecommender()
+            builder.auto_recommend_context(recommender, max_files=10)
+
+        handoff_data = builder.build()
+
+        # Update session with handoff data
+        session.handoff_notes = handoff_data["handoff_notes"]
+        session.recommended_next = handoff_data["recommended_next"]
+        session.blockers = handoff_data["blockers"]
+        session.recommended_context = handoff_data["recommended_context"]
+
+        # Persist handoff data to database before ending session
+        self.session_converter.save(session)
+
+        # End the session
+        self.end_session(session_id)
+
+        # Track handoff effectiveness (optional - only if database available)
+        # Note: SessionManager doesn't have direct database access,
+        # handoff tracking is primarily done through SDK
+        # Users should use SDK.end_session_with_handoff() for full tracking
+
+        return session
+
     def release_session_features(self, session_id: str) -> list[str]:
         """
         Release all features claimed by a specific session.
@@ -481,18 +954,127 @@ class SessionManager:
         Returns:
             List of released feature IDs
         """
-        released = []
-        for collection in ["features", "bugs"]:
-            graph = self._get_graph(collection)
-            for node in graph:
-                if node.claimed_by_session == session_id:
-                    node.agent_assigned = None
-                    node.claimed_at = None
-                    node.claimed_by_session = None
-                    node.updated = datetime.now()
-                    graph.update(node)
-                    released.append(node.id)
-        return released
+        return self.claiming_service.release_session_features(session_id)
+
+    def log_error(
+        self,
+        session_id: str,
+        error: Exception,
+        traceback_str: str,
+        context: dict[str, Any] | None = None,
+    ) -> None:
+        """
+        Log error with full traceback to session.
+
+        Stores complete error details for later retrieval via debug command.
+        Minimizes console output for better token efficiency.
+
+        Args:
+            session_id: Session ID to log error to
+            error: The exception object
+            traceback_str: Full traceback string
+            context: Optional context dict (e.g. current file, line number)
+        """
+        session = self.get_session(session_id)
+        if not session:
+            return
+
+        error_entry = ErrorEntry(
+            timestamp=datetime.now(),
+            error_type=error.__class__.__name__,
+            message=str(error),
+            traceback=traceback_str,
+        )
+
+        # Append error record to error_log
+        session.error_log.append(error_entry)
+
+        # Save updated session
+        self.session_converter.save(session)
+
+    def get_session_errors(self, session_id: str) -> list[dict[str, Any]]:
+        """
+        Retrieve all errors logged for a session.
+
+        Args:
+            session_id: Session ID
+
+        Returns:
+            List of error records, or empty list if none
+        """
+        session = self.get_session(session_id)
+        if not session:
+            return []
+        return [error.model_dump() for error in session.error_log]
+
+    def search_errors(
+        self,
+        session_id: str,
+        error_type: str | None = None,
+        pattern: str | None = None,
+    ) -> list[dict[str, Any]]:
+        """
+        Search errors in a session by type and/or pattern.
+
+        Args:
+            session_id: Session ID to search
+            error_type: Filter by exception type (e.g., "ValueError")
+            pattern: Regex pattern to match in error message
+
+        Returns:
+            List of matching error records
+        """
+        session = self.get_session(session_id)
+        if not session:
+            return []
+
+        errors = [error.model_dump() for error in session.error_log]
+
+        # Filter by error type
+        if error_type:
+            errors = [e for e in errors if e.get("error_type") == error_type]
+
+        # Filter by pattern in message
+        if pattern:
+            compiled_pattern = re.compile(pattern, re.IGNORECASE)
+            errors = [
+                e for e in errors if compiled_pattern.search(e.get("message", ""))
+            ]
+
+        return errors
+
+    def get_error_summary(self, session_id: str) -> dict[str, Any]:
+        """
+        Get summary statistics of errors in a session.
+
+        Args:
+            session_id: Session ID
+
+        Returns:
+            Dictionary with error summary statistics
+        """
+        session = self.get_session(session_id)
+        if not session or not session.error_log:
+            return {
+                "total_errors": 0,
+                "error_types": {},
+                "first_error": None,
+                "last_error": None,
+            }
+
+        errors = session.error_log
+        error_types: dict[str, int] = {}
+
+        for error in errors:
+            error_type = error.error_type
+            error_types[error_type] = error_types.get(error_type, 0) + 1
+
+        return {
+            "total_errors": len(errors),
+            "error_types": error_types,
+            "first_error": errors[0].model_dump() if errors else None,
+            "last_error": errors[-1].model_dump() if errors else None,
+        }
 
     # =========================================================================
     # Activity Tracking
@@ -527,7 +1109,7 @@ class SessionManager:
         """
         session = self.get_session(session_id)
         if not session:
-            raise ValueError(f"Session not found: {session_id}")
+            raise SessionNotFoundError(session_id)
 
         # Get active features for attribution
         active_features = self.get_active_features()
@@ -543,10 +1125,26 @@ class SessionManager:
             # Inherit feature from parent if not explicitly set
             if not attributed_feature and active_features:
                 # Use primary feature or first active feature
-                primary = next((f for f in active_features if f.properties.get("is_primary")), None)
-                attributed_feature = (primary or active_features[0]).id if active_features else None
+                primary = next(
+                    (f for f in active_features if f.properties.get("is_primary")), None
+                )
+                attributed_feature = (
+                    (primary or active_features[0]).id if active_features else None
+                )
             drift_score = None  # No drift for child activities
             attribution_reason = "child_activity"
+        # Skip drift calculation for system overhead activities
+        elif self._is_system_overhead(tool, summary, file_paths or []):
+            # Attribute to primary or first active feature, but no drift score
+            if not attributed_feature and active_features:
+                primary = next(
+                    (f for f in active_features if f.properties.get("is_primary")), None
+                )
+                attributed_feature = (
+                    (primary or active_features[0]).id if active_features else None
+                )
+            drift_score = None  # No drift for system overhead
+            attribution_reason = "system_overhead"
         elif not attributed_feature and active_features:
             attribution = self.attribute_activity(
                 tool=tool,
@@ -563,7 +1161,7 @@ class SessionManager:
         # This ensures multi-agent safety - no race conditions even with parallel agents
         event_id = generate_id(
             node_type="event",
-            title=f"{tool}:{summary[:50]}"  # Include tool + summary for content-addressability
+            title=f"{tool}:{summary[:50]}",  # Include tool + summary for content-addressability
         )
 
         entry = ActivityEntry(
@@ -580,35 +1178,43 @@ class SessionManager:
                 "file_paths": file_paths,
                 "attribution_reason": attribution_reason,
                 "session_id": session_id,  # Include session context in payload
-            } if file_paths or attribution_reason or session_id else payload,
+            }
+            if file_paths or attribution_reason or session_id
+            else payload,
         )
 
         # Append to JSONL event log (source of truth for analytics)
         try:
             # Auto-infer work type from feature_id (Phase 1: Work Type Classification)
             from htmlgraph.work_type_utils import infer_work_type_from_id
+
             work_type = infer_work_type_from_id(entry.feature_id)
 
-            self.event_log.append(EventRecord(
-                event_id=entry.id or "",
-                timestamp=entry.timestamp,
-                session_id=session_id,
-                agent=session.agent,
-                tool=entry.tool,
-                summary=entry.summary,
-                success=entry.success,
-                feature_id=entry.feature_id,
-                drift_score=entry.drift_score,
-                start_commit=session.start_commit,
-                continued_from=session.continued_from,
-                work_type=work_type,
-                session_status=session.status,
-                file_paths=file_paths,
-                payload=entry.payload if isinstance(entry.payload, dict) else payload,
-            ))
-        except Exception:
+            self.event_log.append(
+                EventRecord(
+                    event_id=entry.id or "",
+                    timestamp=entry.timestamp,
+                    session_id=session_id,
+                    agent=session.agent,
+                    tool=entry.tool,
+                    summary=entry.summary,
+                    success=entry.success,
+                    feature_id=entry.feature_id,
+                    drift_score=entry.drift_score,
+                    start_commit=session.start_commit,
+                    continued_from=session.continued_from,
+                    work_type=work_type,
+                    session_status=session.status,
+                    file_paths=file_paths,
+                    parent_session_id=session.parent_session,
+                    payload=entry.payload
+                    if isinstance(entry.payload, dict)
+                    else payload,
+                )
+            )
+        except Exception as e:
             # Never break core tracking because of analytics logging.
-            pass
+            logger.warning(f"Failed to append to event log: {e}")
 
         # Optional: keep SQLite index up to date if it already exists.
         # This keeps the dashboard fast while keeping Git as the source of truth.
@@ -619,29 +1225,37 @@ class SessionManager:
 
                 idx = AnalyticsIndex(index_path)
                 idx.ensure_schema()
-                idx.upsert_session({
-                    "session_id": session_id,
-                    "agent": session.agent,
-                    "start_commit": session.start_commit,
-                    "continued_from": session.continued_from,
-                    "status": session.status,
-                    "started_at": session.started_at.isoformat(),
-                    "ended_at": session.ended_at.isoformat() if session.ended_at else None,
-                })
-                idx.upsert_event({
-                    "event_id": entry.id,
-                    "timestamp": entry.timestamp.isoformat(),
-                    "session_id": session_id,
-                    "tool": entry.tool,
-                    "summary": entry.summary,
-                    "success": entry.success,
-                    "feature_id": entry.feature_id,
-                    "drift_score": entry.drift_score,
-                    "file_paths": file_paths or [],
-                    "payload": entry.payload if isinstance(entry.payload, dict) else payload,
-                })
-        except Exception:
-            pass
+                idx.upsert_session(
+                    {
+                        "session_id": session_id,
+                        "agent": session.agent,
+                        "start_commit": session.start_commit,
+                        "continued_from": session.continued_from,
+                        "status": session.status,
+                        "started_at": session.started_at.isoformat(),
+                        "ended_at": session.ended_at.isoformat()
+                        if session.ended_at
+                        else None,
+                    }
+                )
+                idx.upsert_event(
+                    {
+                        "event_id": entry.id,
+                        "timestamp": entry.timestamp.isoformat(),
+                        "session_id": session_id,
+                        "tool": entry.tool,
+                        "summary": entry.summary,
+                        "success": entry.success,
+                        "feature_id": entry.feature_id,
+                        "drift_score": entry.drift_score,
+                        "file_paths": file_paths or [],
+                        "payload": entry.payload
+                        if isinstance(entry.payload, dict)
+                        else payload,
+                    }
+                )
+        except Exception as e:
+            logger.warning(f"Failed to update SQLite index: {e}")
 
         # Add to session
         session.add_activity(entry)
@@ -690,6 +1304,27 @@ class SessionManager:
     # Smart Attribution
     # =========================================================================
 
+    def _get_active_auto_spike(self, active_features: list[Node]) -> Node | None:
+        """
+        Find an active auto-generated spike (session-init, conversation-init, or transition).
+
+        Auto-spikes take precedence over regular features for attribution
+        since they're specifically designed to catch transitional activities.
+
+        Returns:
+            Active auto-spike or None
+        """
+        for feature in active_features:
+            if (
+                feature.type == "spike"
+                and feature.auto_generated
+                and feature.spike_subtype
+                in ("session-init", "conversation-init", "transition")
+                and feature.status == "in-progress"
+            ):
+                return feature
+        return None
+
     def attribute_activity(
         self,
         tool: str,
@@ -699,7 +1334,9 @@ class SessionManager:
         agent: str | None = None,
     ) -> dict[str, Any]:
         """
-        Score and attribute an activity to the best matching feature.
+        Score and attribute an activity to the best matching feature or auto-spike.
+
+        Auto-spikes have priority over features for transitional activities.
 
         Args:
             tool: Tool name
@@ -711,6 +1348,18 @@ class SessionManager:
         Returns:
             Dict with feature_id, score, drift_score, reason
         """
+        # Priority 1: Check for active auto-generated spikes (session-init, transition)
+        # These capture transitional activities before features are active
+        active_spike = self._get_active_auto_spike(active_features)
+        if active_spike:
+            return {
+                "feature_id": active_spike.id,
+                "score": 1.0,  # Perfect match - spike is designed for this
+                "drift_score": 0.0,  # No drift - this is expected
+                "reason": f"auto_spike_{active_spike.spike_subtype}",
+            }
+
+        # Priority 2: Regular feature attribution
         if not active_features:
             return {
                 "feature_id": None,
@@ -831,9 +1480,20 @@ class SessionManager:
     def _extract_keywords(self, text: str) -> set[str]:
         """Extract keywords from text."""
         # Simple keyword extraction - lowercase words > 3 chars
-        words = re.findall(r'\b[a-zA-Z]{3,}\b', text.lower())
+        words = re.findall(r"\b[a-zA-Z]{3,}\b", text.lower())
         # Filter common words
-        stop_words = {'the', 'and', 'for', 'with', 'this', 'that', 'from', 'are', 'was', 'were'}
+        stop_words = {
+            "the",
+            "and",
+            "for",
+            "with",
+            "this",
+            "that",
+            "from",
+            "are",
+            "was",
+            "were",
+        }
         return set(words) - stop_words
 
     def _score_keyword_overlap(self, text: str, keywords: set[str]) -> float:
@@ -846,6 +1506,139 @@ class SessionManager:
 
         return len(overlap) / len(keywords) if keywords else 0.0
 
+    def _is_system_overhead(
+        self, tool: str, summary: str, file_paths: list[str]
+    ) -> bool:
+        """
+        Determine if an activity is system overhead that shouldn't count as drift.
+
+        System overhead includes:
+        - Skill invocations for system skills (htmlgraph-tracker, etc.)
+        - Read/Write operations on .htmlgraph/ metadata files
+        - Infrastructure files (config, docs, build artifacts, IDE files)
+        """
+        # System skills that are overhead, not feature work
+        system_skills = {
+            "htmlgraph-tracker",
+            "htmlgraph:htmlgraph-tracker",
+        }
+
+        # Check if this is a Skill invocation for a system skill
+        if tool == "Skill":
+            # Extract skill name from summary (format: "Skill: {'skill': 'htmlgraph-tracker'}")
+            for skill_name in system_skills:
+                if skill_name in summary.lower():
+                    return True
+
+        # Infrastructure file patterns to exclude from drift scoring
+        infrastructure_patterns = [
+            # HtmlGraph metadata
+            ".htmlgraph/",
+            # Configuration files
+            "pyproject.toml",
+            "package.json",
+            "package-lock.json",
+            "setup.py",
+            "setup.cfg",
+            "requirements.txt",
+            "requirements-dev.txt",
+            ".gitignore",
+            ".gitattributes",
+            ".editorconfig",
+            "pytest.ini",
+            "tox.ini",
+            ".coveragerc",
+            # CI/CD configs
+            ".github/",
+            ".gitlab-ci.yml",
+            ".travis.yml",
+            "circle.yml",
+            ".pre-commit-config.yaml",
+            # Build and distribution
+            "dist/",
+            "build/",
+            ".eggs/",
+            "*.egg-info/",
+            "__pycache__/",
+            "*.pyc",
+            "*.pyo",
+            "*.pyd",
+            # IDE and editor files
+            ".vscode/",
+            ".idea/",
+            "*.swp",
+            "*.swo",
+            "*~",
+            ".DS_Store",
+            "Thumbs.db",
+            # Testing artifacts
+            ".pytest_cache/",
+            ".coverage",
+            "htmlcov/",
+            ".tox/",
+            # Environment and secrets
+            ".env",
+            ".env.local",
+            ".env.*.local",
+            # Documentation (consider docs/ as infrastructure)
+            "README.md",
+            "CONTRIBUTING.md",
+            "LICENSE",
+            "CHANGELOG.md",
+            "docs/",
+            # Other common infrastructure
+            ".contextune/",
+            ".parallel/",
+            "node_modules/",
+            ".venv/",
+            "venv/",
+        ]
+
+        # Check if any file paths match infrastructure patterns
+        if file_paths:
+            for path in file_paths:
+                # Normalize path
+                path_normalized = path.replace("\\", "/")
+                path_lower = path_normalized.lower()
+
+                for pattern in infrastructure_patterns:
+                    pattern_lower = pattern.lower()
+
+                    # Directory patterns (end with /)
+                    if pattern_lower.endswith("/"):
+                        # For wildcard directory patterns like "*.egg-info/"
+                        if "*" in pattern_lower:
+                            import fnmatch
+
+                            # Check each path segment
+                            path_parts = path_lower.split("/")
+                            for part in path_parts:
+                                if fnmatch.fnmatch(part, pattern_lower.rstrip("/")):
+                                    return True
+                        # For regular directory patterns like ".htmlgraph/"
+                        elif pattern_lower in path_lower or path_lower.startswith(
+                            pattern_lower
+                        ):
+                            return True
+                    # Wildcard file patterns (e.g., *.pyc)
+                    elif "*" in pattern_lower:
+                        import fnmatch
+
+                        # Check the filename (last part of path)
+                        filename = path_lower.split("/")[-1]
+                        if fnmatch.fnmatch(filename, pattern_lower):
+                            return True
+                    # Exact filename match
+                    else:
+                        # Check if path ends with the pattern (handles both absolute and relative)
+                        if (
+                            path_lower.endswith(pattern_lower)
+                            or f"/{pattern_lower}" in path_lower
+                        ):
+                            return True
+
+        return False
+
     # =========================================================================
     # Drift Detection
     # =========================================================================
@@ -866,12 +1659,15 @@ class SessionManager:
 
         # Get recent activities for this feature
         feature_activities = [
-            a for a in session.activity_log[-20:]
-            if a.feature_id == feature_id
+            a for a in session.activity_log[-20:] if a.feature_id == feature_id
         ]
 
         if not feature_activities:
-            return {"is_drifting": False, "drift_score": 0, "reasons": ["no_recent_activity"]}
+            return {
+                "is_drifting": False,
+                "drift_score": 0,
+                "reasons": ["no_recent_activity"],
+            }
 
         # 1. Check time since last meaningful progress
         last_activity = feature_activities[-1]
@@ -884,7 +1680,7 @@ class SessionManager:
         recent_tools = [a.tool for a in feature_activities[-10:]]
         if len(recent_tools) >= 6:
             # Check for repetitive patterns
-            tool_counts = {}
+            tool_counts: dict[str, int] = {}
             for t in recent_tools:
                 tool_counts[t] = tool_counts.get(t, 0) + 1
             max_repeat = max(tool_counts.values())
@@ -893,7 +1689,9 @@ class SessionManager:
                 reasons.append("repetitive_pattern")
 
         # 3. Check average drift scores
-        drift_scores = [a.drift_score for a in feature_activities if a.drift_score is not None]
+        drift_scores = [
+            a.drift_score for a in feature_activities if a.drift_score is not None
+        ]
         if drift_scores:
             avg_drift = sum(drift_scores) / len(drift_scores)
             if avg_drift > 0.6:
@@ -959,12 +1757,29 @@ class SessionManager:
                 feature_id=feature_id,
                 payload=payload,
             )
-        except Exception:
+        except Exception as e:
             # Never break feature ops because of tracking.
+            logger.warning(f"Failed to log work item action ({tool}): {e}")
             return
 
     def get_active_features(self) -> list[Node]:
-        """Get all features with status 'in-progress'."""
+        """
+        Get all features with status 'in-progress'.
+
+        Uses a cache to avoid O(n) disk reads on every tool use.
+        Cache is invalidated when features are started, completed, or released.
+        """
+        if self._features_cache_dirty or self._active_features_cache is None:
+            self._active_features_cache = self._compute_active_features()
+            self._features_cache_dirty = False
+        return self._active_features_cache
+
+    def _compute_active_features(self) -> list[Node]:
+        """
+        Compute active features by iterating all features from disk.
+
+        This is the slow path - only called when cache is dirty.
+        """
         features = []
 
         # From features collection
@@ -1097,7 +1912,9 @@ class SessionManager:
         # Check WIP limit
         active = self.get_active_features()
         if len(active) >= self.wip_limit and node not in active:
-            raise ValueError(f"WIP limit ({self.wip_limit}) reached. Complete existing work first.")
+            raise ValueError(
+                f"WIP limit ({self.wip_limit}) reached. Complete existing work first."
+            )
 
         # Auto-claim if starting and not already claimed
         if agent and not node.agent_assigned:
@@ -1111,8 +1928,20 @@ class SessionManager:
         node.updated = datetime.now()
         graph.update(node)
 
+        # Invalidate active features cache
+        self._features_cache_dirty = True
+
+        # Auto-complete any active auto-spikes (session-init or transition)
+        # When a regular feature starts, transitional period is over
+        if agent:
+            self._complete_active_auto_spikes(agent, to_feature_id=feature_id)
+
         # Link feature to active session (bidirectional)
-        active_session = self.get_active_session_for_agent(agent) if agent else self.get_active_session()
+        active_session = (
+            self.get_active_session_for_agent(agent)
+            if agent
+            else self.get_active_session()
+        )
         if agent and not active_session:
             active_session = self._ensure_session_for_agent(agent)
         if active_session:
@@ -1136,6 +1965,7 @@ class SessionManager:
         *,
         agent: str | None = None,
         log_activity: bool = True,
+        transcript_id: str | None = None,
     ) -> Node | None:
         """
         Mark a feature as done.
@@ -1145,6 +1975,8 @@ class SessionManager:
             collection: Collection name
             agent: Optional agent name for attribution/logging
             log_activity: If true, write an event record (requires agent)
+            transcript_id: Optional transcript ID (agent session) that implemented this feature.
+                          Used to link parallel agent transcripts to features.
 
         Returns:
             Updated Node or None
@@ -1152,22 +1984,100 @@ class SessionManager:
         graph = self._get_graph(collection)
         node = graph.get(feature_id)
         if not node:
-            return None
+            # Node might have been created by SDK's collection (different graph instance)
+            # Try reloading from disk
+            node = graph.reload_node(feature_id)
+            if not node:
+                return None
 
         node.status = "done"
         node.updated = datetime.now()
         node.properties["completed_at"] = datetime.now().isoformat()
+
+        # Link transcript if provided (for parallel agent tracking)
+        if transcript_id:
+            self._link_transcript_to_feature(node, transcript_id, graph)
+
         graph.update(node)
 
+        # Invalidate active features cache
+        self._features_cache_dirty = True
+
         if log_activity and agent:
+            # Include transcript_id in payload for traceability
+            payload = {"collection": collection, "action": "complete"}
+            if transcript_id:
+                payload["transcript_id"] = transcript_id
+
             self._maybe_log_work_item_action(
                 agent=agent,
                 tool="FeatureComplete",
                 summary=f"Completed: {collection}/{feature_id}",
                 feature_id=feature_id,
-                payload={"collection": collection, "action": "complete"},
+                payload=payload,
             )
 
+        # Auto-import transcript on work item completion
+        session = self.get_active_session(agent=agent)
+        if session and session.transcript_id:
+            try:
+                from htmlgraph.transcript import TranscriptReader
+
+                reader = TranscriptReader()
+                transcript = reader.read_session(session.transcript_id)
+                if transcript:
+                    self.import_transcript_events(
+                        session_id=session.id,
+                        transcript_session=transcript,
+                        overwrite=True,  # Replace hook data with high-fidelity transcript
+                    )
+            except Exception as e:
+                logger.warning(
+                    f"Failed to auto-import transcript on feature completion: {e}"
+                )
+
+        # Auto-create transition spike for post-completion activities
+        # This captures work between features. Completed when next feature starts,
+        # or when a new conversation starts (completing previous conversation's spike).
+        if session:
+            self._create_transition_spike(session, from_feature_id=feature_id)
+
+        # Analyze session for anti-patterns and errors on completion
+        # This surfaces feedback to the orchestrator about mistakes made
+        if session:
+            try:
+                from htmlgraph.learning import LearningPersistence
+                from htmlgraph.sdk import SDK
+
+                # Create SDK instance for analysis (shares same graph directory)
+                sdk = SDK(agent=agent or "unknown", directory=self.graph_dir)
+                learning = LearningPersistence(sdk)
+                analysis = learning.analyze_for_orchestrator(session.id)
+                node.properties["completion_analysis"] = analysis
+
+                # PERSIST learning insights to graph (not just ephemeral properties)
+                # This creates queryable SessionInsight and Pattern nodes
+                insight_id = learning.persist_session_insight(session.id)
+                if insight_id:
+                    node.properties["insight_id"] = insight_id
+                    logger.debug(f"Persisted learning insight: {insight_id}")
+
+                # Persist patterns detected across sessions
+                pattern_ids = learning.persist_patterns()
+                if pattern_ids:
+                    logger.debug(f"Persisted {len(pattern_ids)} patterns")
+
+                # Log analysis summary if issues detected
+                if analysis.get("summary", "").startswith("⚠️"):
+                    logger.info(
+                        f"Work item {feature_id} completed with issues: {analysis['summary']}"
+                    )
+
+                # Update node in graph with analysis
+                graph.update(node)
+            except Exception as e:
+                logger.warning(f"Failed to analyze session on completion: {e}")
+
         return node
 
     def set_primary_feature(
@@ -1335,40 +2245,12 @@ class SessionManager:
         Returns:
             Updated Node or None
         """
-        graph = self._get_graph(collection)
-        node = graph.get(feature_id)
-        if not node:
-            return None
-
-        # Check if already claimed by someone else
-        if node.agent_assigned and node.agent_assigned != agent:
-            # Check if session that claimed it is still active
-            if node.claimed_by_session:
-                session = self.get_session(node.claimed_by_session)
-                if session and session.status == "active":
-                    raise ValueError(
-                        f"Feature '{feature_id}' is already claimed by {node.agent_assigned} "
-                        f"(session {node.claimed_by_session})"
-                    )
-
-        session = self._ensure_session_for_agent(agent)
-
-        node.agent_assigned = agent
-        node.claimed_at = datetime.now()
-        node.claimed_by_session = session.id
-        node.updated = datetime.now()
-        graph.update(node)
-
-        self._maybe_log_work_item_action(
-            agent=agent,
-            tool="FeatureClaim",
-            summary=f"Claimed: {collection}/{feature_id}",
+        return self.claiming_service.claim_feature(
             feature_id=feature_id,
-            payload={"collection": collection, "action": "claim"},
+            collection=collection,
+            agent=agent,
         )
 
-        return node
-
     def release_feature(
         self,
         feature_id: str,
@@ -1387,30 +2269,12 @@ class SessionManager:
         Returns:
             Updated Node or None
         """
-        graph = self._get_graph(collection)
-        node = graph.get(feature_id)
-        if not node:
-            return None
-
-        if node.agent_assigned and node.agent_assigned != agent:
-            raise ValueError(f"Feature '{feature_id}' is claimed by {node.agent_assigned}, not {agent}")
-
-        node.agent_assigned = None
-        node.claimed_at = None
-        node.claimed_by_session = None
-        node.updated = datetime.now()
-        graph.update(node)
-
-        self._maybe_log_work_item_action(
-            agent=agent,
-            tool="FeatureRelease",
-            summary=f"Released: {collection}/{feature_id}",
+        return self.claiming_service.release_feature(
             feature_id=feature_id,
-            payload={"collection": collection, "action": "release"},
+            collection=collection,
+            agent=agent,
         )
 
-        return node
-
     def auto_release_features(self, agent: str) -> list[str]:
         """
         Release all features claimed by an agent.
@@ -1421,18 +2285,7 @@ class SessionManager:
         Returns:
             List of released feature IDs
         """
-        released = []
-        for collection in ["features", "bugs"]:
-            graph = self._get_graph(collection)
-            for node in graph:
-                if node.agent_assigned == agent:
-                    node.agent_assigned = None
-                    node.claimed_at = None
-                    node.claimed_by_session = None
-                    node.updated = datetime.now()
-                    graph.update(node)
-                    released.append(node.id)
-        return released
+        return self.claiming_service.auto_release_features(agent)
 
     def create_handoff(
         self,
@@ -1470,7 +2323,9 @@ class SessionManager:
 
         # Verify agent owns the feature
         if node.agent_assigned and node.agent_assigned != agent:
-            raise ValueError(f"Feature '{feature_id}' is claimed by {node.agent_assigned}, not {agent}")
+            raise ValueError(
+                f"Feature '{feature_id}' is claimed by {node.agent_assigned}, not {agent}"
+            )
 
         # Set handoff fields
         node.handoff_required = True
@@ -1522,13 +2377,17 @@ class SessionManager:
         from htmlgraph.models import Edge
 
         # Find the feature in either collection
-        feature_node = self.features_graph.get(feature_id) or self.bugs_graph.get(feature_id)
+        feature_node = self.features_graph.get(feature_id) or self.bugs_graph.get(
+            feature_id
+        )
         if not feature_node:
             return
 
         # Check if feature → session edge already exists
         existing_sessions = feature_node.edges.get("implemented-in", [])
-        feature_already_linked = any(edge.target_id == session_id for edge in existing_sessions)
+        feature_already_linked = any(
+            edge.target_id == session_id for edge in existing_sessions
+        )
 
         if not feature_already_linked:
             # Add feature → session edge
@@ -1557,6 +2416,72 @@ class SessionManager:
             # Save the updated session
             self.session_converter.save(session)
 
+    def _link_transcript_to_feature(
+        self,
+        node: Node,
+        transcript_id: str,
+        graph: HtmlGraph,
+    ) -> None:
+        """
+        Link a Claude Code transcript to a feature.
+
+        Adds an "implemented-by" edge to the feature pointing to the transcript.
+        Also aggregates tool analytics from the transcript into feature properties.
+
+        Args:
+            node: Feature node to link
+            transcript_id: Claude Code transcript/agent session ID
+            graph: Graph containing the node
+        """
+        from htmlgraph.models import Edge
+
+        # Check if edge already exists
+        existing_transcripts = node.edges.get("implemented-by", [])
+        already_linked = any(
+            edge.target_id == transcript_id for edge in existing_transcripts
+        )
+
+        if already_linked:
+            return
+
+        # Try to get transcript analytics
+        tool_count = 0
+        duration_seconds = 0
+        tool_breakdown = {}
+
+        try:
+            from htmlgraph.transcript import TranscriptReader
+
+            reader = TranscriptReader()
+            transcript = reader.read_session(transcript_id)
+            if transcript:
+                tool_count = transcript.tool_call_count
+                duration_seconds = int(transcript.duration_seconds or 0)
+                tool_breakdown = transcript.tool_breakdown
+        except Exception as e:
+            logger.warning(
+                f"Failed to get transcript analytics for {transcript_id}: {e}"
+            )
+
+        # Add implemented-by edge with analytics
+        edge = Edge(
+            target_id=transcript_id,
+            relationship="implemented-by",
+            title=transcript_id,
+            since=datetime.now(),
+            properties={
+                "tool_count": tool_count,
+                "duration_seconds": duration_seconds,
+                "tool_breakdown": tool_breakdown,
+            },
+        )
+        node.add_edge(edge)
+
+        # Also store aggregated transcript analytics in properties
+        if tool_count > 0:
+            node.properties["transcript_tool_count"] = tool_count
+            node.properties["transcript_duration_seconds"] = duration_seconds
+
     def _get_graph(self, collection: str) -> HtmlGraph:
         """Get graph for a collection."""
         if collection == "bugs":
@@ -1573,6 +2498,7 @@ class SessionManager:
         """Get current git commit hash."""
         try:
             import subprocess
+
             result = subprocess.run(
                 ["git", "rev-parse", "--short", "HEAD"],
                 capture_output=True,
@@ -1581,6 +2507,297 @@ class SessionManager:
             )
             if result.returncode == 0:
                 return result.stdout.strip()
-        except Exception:
-            pass
+        except Exception as e:
+            logger.warning(f"Failed to get current git commit: {e}")
+        return None
+
+    # =========================================================================
+    # Claude Code Transcript Integration
+    # =========================================================================
+
+    def link_transcript(
+        self,
+        session_id: str,
+        transcript_id: str,
+        transcript_path: str | None = None,
+        git_branch: str | None = None,
+    ) -> Session | None:
+        """
+        Link a Claude Code transcript to an HtmlGraph session.
+
+        Args:
+            session_id: HtmlGraph session ID
+            transcript_id: Claude Code session UUID (from JSONL filename)
+            transcript_path: Path to the JSONL file
+            git_branch: Git branch from transcript metadata
+
+        Returns:
+            Updated Session or None if not found
+        """
+        session = self.get_session(session_id)
+        if not session:
+            return None
+
+        session.transcript_id = transcript_id
+        session.transcript_path = transcript_path
+        session.transcript_synced_at = datetime.now()
+        if git_branch:
+            session.transcript_git_branch = git_branch
+
+        self.session_converter.save(session)
+        return session
+
+    def find_session_by_transcript(
+        self,
+        transcript_id: str,
+    ) -> Session | None:
+        """
+        Find an HtmlGraph session linked to a transcript.
+
+        Args:
+            transcript_id: Claude Code session UUID
+
+        Returns:
+            Session or None if not found
+        """
+        for session in self.session_converter.load_all():
+            if session.transcript_id == transcript_id:
+                return session
         return None
+
+    def import_transcript_events(
+        self,
+        session_id: str,
+        transcript_session: Any,  # TranscriptSession from transcript module
+        overwrite: bool = False,
+    ) -> dict[str, int | str]:
+        """
+        Import events from a Claude Code transcript into an HtmlGraph session.
+
+        This extracts tool uses and user messages from the transcript
+        and adds them to the session's activity log.
+
+        Args:
+            session_id: HtmlGraph session ID to import into
+            transcript_session: TranscriptSession object from transcript module
+            overwrite: If True, clear existing activities before import
+
+        Returns:
+            Dict with import statistics
+        """
+        session = self.get_session(session_id)
+        if not session:
+            return {"error": "session_not_found", "imported": 0}
+
+        if overwrite:
+            session.activity_log = []
+            session.event_count = 0
+
+        imported = 0
+        skipped = 0
+
+        for entry in transcript_session.entries:
+            # Skip non-actionable entries
+            if entry.entry_type not in ("user", "tool_use"):
+                skipped += 1
+                continue
+
+            # Create ActivityEntry from transcript entry
+            if entry.entry_type == "user":
+                activity = ActivityEntry(
+                    id=f"tx-{entry.uuid[:8]}",
+                    timestamp=entry.timestamp,
+                    tool="UserQuery",
+                    summary=entry.to_summary(),
+                    success=True,
+                    payload={
+                        "source": "transcript",
+                        "transcript_uuid": entry.uuid,
+                        "message_content": entry.message_content,
+                    },
+                )
+            elif entry.entry_type == "tool_use":
+                activity = ActivityEntry(
+                    id=f"tx-{entry.uuid[:8]}",
+                    timestamp=entry.timestamp,
+                    tool=entry.tool_name or "Unknown",
+                    summary=entry.to_summary(),
+                    success=True,  # Assume success unless we have result
+                    payload={
+                        "source": "transcript",
+                        "transcript_uuid": entry.uuid,
+                        "tool_input": entry.tool_input,
+                        "thinking": entry.thinking,
+                    },
+                )
+            else:
+                continue
+
+            session.add_activity(activity)
+            imported += 1
+
+            # Also append to JSONL event log
+            try:
+                from htmlgraph.work_type_utils import infer_work_type_from_id
+
+                work_type = infer_work_type_from_id(activity.feature_id)
+
+                self.event_log.append(
+                    EventRecord(
+                        event_id=activity.id or "",
+                        timestamp=activity.timestamp,
+                        session_id=session_id,
+                        agent=session.agent,
+                        tool=activity.tool,
+                        summary=activity.summary,
+                        success=activity.success,
+                        feature_id=activity.feature_id,
+                        drift_score=None,
+                        start_commit=session.start_commit,
+                        continued_from=session.continued_from,
+                        work_type=work_type,
+                        session_status=session.status,
+                        payload=activity.payload
+                        if isinstance(activity.payload, dict)
+                        else None,
+                    )
+                )
+            except Exception as e:
+                logger.warning(f"Failed to append transcript event to event log: {e}")
+
+        # Update transcript link
+        session.transcript_id = transcript_session.session_id
+        session.transcript_path = str(transcript_session.path)
+        session.transcript_synced_at = datetime.now()
+        if transcript_session.git_branch:
+            session.transcript_git_branch = transcript_session.git_branch
+
+        self.session_converter.save(session)
+
+        return {
+            "imported": imported,
+            "skipped": skipped,
+            "total_entries": len(transcript_session.entries),
+        }
+
+    def auto_link_transcript_by_branch(
+        self,
+        git_branch: str,
+        agent: str | None = None,
+    ) -> list[tuple[str, str]]:
+        """
+        Auto-link HtmlGraph sessions to transcripts based on git branch.
+
+        This finds sessions and transcripts that share the same git branch
+        and links them together.
+
+        Args:
+            git_branch: Git branch to match
+            agent: Optional agent filter
+
+        Returns:
+            List of (session_id, transcript_id) tuples that were linked
+        """
+        from htmlgraph.transcript import TranscriptReader
+
+        linked: list[tuple[str, str]] = []
+        reader = TranscriptReader()
+
+        # Find transcripts for this branch
+        project_path = self.graph_dir.parent
+        transcripts = reader.find_sessions_for_branch(git_branch, project_path)
+
+        if not transcripts:
+            return linked
+
+        # Find sessions that might match
+        sessions = self.session_converter.load_all()
+        if agent:
+            sessions = [s for s in sessions if s.agent == agent]
+
+        # Helper to normalize datetimes for comparison
+        # (handles timezone-aware vs timezone-naive)
+        def normalize_dt(dt: datetime | None) -> datetime | None:
+            if dt is None:
+                return None
+            # If timezone-aware, convert to naive UTC
+            if dt.tzinfo is not None:
+                return dt.astimezone(timezone.utc).replace(tzinfo=None)
+            return dt
+
+        # Match by time overlap and git branch
+        for transcript in transcripts:
+            if not transcript.started_at:
+                continue
+
+            transcript_start = normalize_dt(transcript.started_at)
+            transcript_end = normalize_dt(transcript.ended_at)
+
+            for session in sessions:
+                # Skip if already linked
+                if session.transcript_id:
+                    continue
+
+                session_start = normalize_dt(session.started_at)
+                session_end = normalize_dt(session.ended_at)
+
+                # Check if session overlaps with transcript time
+                if session_start and transcript_end:
+                    if session_start > transcript_end:
+                        continue  # Session started after transcript ended
+
+                if session_end and transcript_start:
+                    if session_end < transcript_start:
+                        continue  # Session ended before transcript started
+
+                # Link them
+                self.link_transcript(
+                    session_id=session.id,
+                    transcript_id=transcript.session_id,
+                    transcript_path=str(transcript.path),
+                    git_branch=git_branch,
+                )
+                linked.append((session.id, transcript.session_id))
+                break  # One transcript per session
+
+        return linked
+
+    def get_transcript_stats(self, session_id: str) -> dict[str, Any] | None:
+        """
+        Get transcript statistics for a session.
+
+        Args:
+            session_id: HtmlGraph session ID
+
+        Returns:
+            Dict with transcript stats or None if no transcript linked
+        """
+        session = self.get_session(session_id)
+        if not session or not session.transcript_id:
+            return None
+
+        from htmlgraph.transcript import TranscriptReader
+
+        reader = TranscriptReader()
+        transcript = reader.read_session(session.transcript_id)
+
+        if not transcript:
+            return {
+                "transcript_id": session.transcript_id,
+                "error": "transcript_not_found",
+            }
+
+        return {
+            "transcript_id": session.transcript_id,
+            "transcript_path": session.transcript_path,
+            "synced_at": session.transcript_synced_at.isoformat()
+            if session.transcript_synced_at
+            else None,
+            "git_branch": session.transcript_git_branch,
+            "user_messages": transcript.user_message_count,
+            "tool_calls": transcript.tool_call_count,
+            "tool_breakdown": transcript.tool_breakdown,
+            "duration_seconds": transcript.duration_seconds,
+            "has_thinking_traces": transcript.has_thinking_traces(),
+            "entry_count": len(transcript.entries),
+        }