Improve the debugability of the sessiont tracker

Author: wakeless

.beads/issues.jsonl

@@ -36,6 +36,7 @@
 {"id":"agent-tracker-41","title":"Fix session selection jumping when activity events arrive","description":"When viewing a TranscriptViewer, receiving activity events (stop/notification) causes the selected session to jump to a different session.\n\n**Root Cause**: \n- Sessions array is sorted by priority (awaiting input \u003e active \u003e inactive \u003e ended)\n- When activity events arrive, sessions get re-sorted\n- App.tsx effect at lines 119-130 runs whenever sessions array changes\n- Even though it checks if selected session exists, there may be edge cases or race conditions\n\n**Events that trigger**:\n```json\n{\"event_type\":\"activity\",\"activity_type\":\"stop\",\"session_id\":\"...\",\"hook_event_name\":\"Stop\"}\n{\"event_type\":\"activity\",\"activity_type\":\"notification\",\"notification_message\":\"Claude is waiting for your input\",\"hook_event_name\":\"Notification\"}\n```\n\n**Solution**: Make the selection management more defensive and ensure it never changes when in transcript view mode.","notes":"Fixed session jumping issue with stack-based navigation refactoring.\n\n**Root cause:** The selection effect was running every time the sessions array changed (including re-sorting), even though the session IDs didn't actually change.\n\n**Solution (App.tsx:114-135):**\n1. Added `useMemo` to track session IDs: `sessionIds = sessions.map(s =\u003e s.id).join(',')`\n2. Changed effect dependency from `sessions` to `sessionIds`\n3. Now effect only runs when sessions are added/removed, not when re-sorted\n\n**Result:** When activity events arrive and sessions get re-sorted by priority, the selected session stays stable because sessionIds doesn't change.\n\nThis was discovered during stack refactoring - need to verify fix works correctly.","status":"open","priority":0,"issue_type":"bug","created_at":"2025-10-20T23:00:04.531865+11:00","updated_at":"2025-10-20T23:12:35.765071+11:00","closed_at":"2025-10-20T23:00:36.613499+11:00"}
 {"id":"agent-tracker-42","title":"Complete navigation stack refactoring","description":"The navigation stack refactoring is functionally complete but needs final touches:\n\n**Completed:**\n- ✅ Created `useNavigation` hook with reducer pattern\n- ✅ Created `SessionListView` component with keyboard handling\n- ✅ Refactored `App.tsx` to use navigation stack (5 useState → 1 hook)\n- ✅ Updated `ToolDetailView` to make onBack optional\n- ✅ Build succeeds, app runs correctly\n\n**Remaining:**\n- [ ] Add unit tests for `useNavigation` reducer\n- [ ] Remove any unused imports/code from refactoring\n- [ ] Verify no duplicate React keys remain (saw warning in dev output)\n- [ ] Update documentation/comments as needed\n- [ ] Test all navigation flows manually (list → transcript → tool detail → back)\n\nThe core refactoring is done and working - this issue tracks the polish/cleanup work.","status":"open","priority":2,"issue_type":"task","created_at":"2025-10-20T23:10:20.28883+11:00","updated_at":"2025-10-20T23:10:20.60385+11:00"}
 {"id":"agent-tracker-43","title":"implement simple MCP server as part of plugin to allow sessions to communicate work summary","description":"We should implement a very simple cli based MCP server using the npm package: @modelcontextprotocol/sdk\n\nThis should be installed as part of the plugin, and should simply be a command that can be called set_title (or something idiomatic like that).\n\nOnce installed the plugin should instruct the agent to call set_title when a piece of work is started or general change of direction has happened. This should be a 5 word summary. \n\nThe MCP itself should just simply echo back the title, but we can then pick up the call to the MCP through the transcript or through a Tools usage and utilise it to update our session model.","design":"## Implementation Plan\n\n1. **MCP Server Setup**\n   - Install @modelcontextprotocol/sdk as dependency\n   - Create CLI-based MCP server script in `.claude-plugin/mcp/`\n   - Implement `set_title` tool that accepts a 5-word summary\n\n2. **Plugin Integration**\n   - Update plugin.json to register the MCP server\n   - Configure server to be available to Claude sessions\n   - Add instructions for agents to call set_title at key moments\n\n3. **Event Capture**\n   - Monitor transcript for MCP tool calls\n   - Extract set_title invocations and summaries\n   - Update session model with work summaries\n\n4. **Testing**\n   - Verify MCP server is discoverable by Claude\n   - Test set_title tool from within a session\n   - Confirm summaries are captured in session data","acceptance_criteria":"- [ ] MCP server installed and runnable\n- [ ] set_title tool available in Claude sessions\n- [ ] Tool accepts 5-word summary parameter\n- [ ] Plugin instructions guide agents to use set_title\n- [ ] Session model updated with work summaries\n- [ ] Integration tested end-to-end","notes":"Implementation completed! All components are in place:\n\n**Phase 1 - MCP Server** ✅\n- Installed @modelcontextprotocol/sdk\n- Created mcp/src/index.ts with stdio-based server\n- Implemented set_work_summary tool\n- Added build infrastructure\n\n**Phase 2 - Plugin Integration** ✅\n- Updated plugin.json with mcpServers configuration\n- Created .claude-plugin/instructions.md with usage guide\n- Server uses ${CLAUDE_PLUGIN_ROOT} for portability\n\n**Phase 3 - Event Capture \u0026 State** ✅\n- Added workSummary field to Session type\n- Created UPDATE_WORK_SUMMARY action type\n- Enhanced activity-handler.ts to capture tool_input\n- Updated SessionTrackerService to detect MCP calls\n- Modified ActivityStore reducer to update work summaries\n\n**Phase 4 - UI Integration** ✅\n- Updated SessionList to display work summaries (dimmed, italic)\n- Updated SessionDetail to show current work (magenta, italic)\n- Both components conditionally render when workSummary exists\n\n**Build \u0026 Testing** ✅\n- All TypeScript compiles successfully\n- MCP server responds correctly to protocol requests\n- Tool schema validated\n\n**Ready for E2E Testing:**\nNext step is to test in an actual Claude session to verify:\n1. MCP server is discoverable\n2. Tool appears in tool list\n3. PostToolUse hook captures parameters\n4. TUI updates with work summary","status":"in_progress","priority":2,"issue_type":"feature","created_at":"2025-10-21T01:41:03.518997+11:00","updated_at":"2025-10-21T01:57:06.833297+11:00"}
+{"id":"agent-tracker-44","title":"Improve the SessionDetails page. Lots of noise and unnecessary stuff.\n\n","description":"W eneed to rework the SessionDetails page and have a bit more focus at the top on the repository and the branch. Second: the summary.\n\nwe don't need to show the transcript, have little focus on the session transcript and then finally the least amount of focus on the terminal","status":"open","priority":2,"issue_type":"task","created_at":"2025-10-22T23:44:08.81075+11:00","updated_at":"2025-10-22T23:44:08.81075+11:00"}
 {"id":"agent-tracker-5","title":"Session Tracking \u0026 State Management","description":"Build the core logic for tracking session states and activity","acceptance_criteria":"- [ ] Create session data model/interface\n- [ ] Implement session registry/store\n- [ ] Track session lifecycle (start, active, inactive, ended)\n- [ ] Calculate last activity timestamp\n- [ ] Implement sorting by activity (most recent first)\n- [ ] Mark inactive sessions for visual distinction\n- [ ] Handle session cleanup on end events\n- [ ] Persist session data (optional, for recovery)","notes":"Session persistence is intentionally skipped for MVP - sessions are ephemeral and only exist while the TUI is running. Future enhancement could add persistence if needed.","status":"closed","priority":1,"issue_type":"feature","created_at":"2025-10-20T15:12:41.174583+11:00","updated_at":"2025-10-20T15:12:41.174583+11:00"}
 {"id":"agent-tracker-6","title":"TUI Interface Development","description":"Build the visual Ink-based TUI with 2-column layout","acceptance_criteria":"- [ ] Create basic Ink app structure with React components\n- [ ] Implement 2-column layout (left: session list, right: details)\n- [ ] Build session list component with sorting\n- [ ] Style active sessions (highlighted/colored)\n- [ ] Style inactive sessions (grey/dimmed)\n- [ ] Implement session selection/navigation\n- [ ] Build detail panel showing session info\n- [ ] Add real-time updates when sessions change\n- [ ] Handle terminal resize gracefully","status":"closed","priority":1,"issue_type":"feature","created_at":"2025-10-20T15:12:41.175056+11:00","updated_at":"2025-10-20T15:12:41.175056+11:00"}
 {"id":"agent-tracker-7","title":"Testing Infrastructure \u0026 Demo Setup","description":"Set up demo-repo and testing framework for feedback loop development","acceptance_criteria":"- [ ] Create demo-repo/ directory\n- [ ] Set up test Claude sessions in demo-repo\n- [ ] Create test scenarios (start, stop, multiple sessions)\n- [ ] Document testing workflow\n- [ ] Add scripts for easy testing\n- [ ] Test session detection and tracking\n- [ ] Verify TUI updates correctly","notes":"Testing infrastructure setup complete. Created demo-repo with sample files, test scenarios, workflow documentation, and helper scripts. \n\nThe last two acceptance criteria (test session detection and verify TUI updates) will be completed during integration testing once the hooks, communication layer, and TUI are implemented.","status":"closed","priority":0,"issue_type":"task","created_at":"2025-10-20T15:12:41.175524+11:00","updated_at":"2025-10-20T15:12:41.175524+11:00"}

.claude/skills/debug-agent-tracker.md

@@ -0,0 +1,266 @@
+---
+description: Debug Agent Tracker session tracking issues with a systematic diagnostic workflow
+proactive: false
+---
+
+# Debug Agent Tracker
+
+You are helping debug Agent Tracker session tracking issues. Use this systematic workflow to diagnose problems.
+
+## Overview
+
+Agent Tracker tracks Claude Code sessions via hooks that write events to `~/.agent-tracker/sessions.jsonl`. The TUI reads this file and displays sessions in real-time.
+
+## Quick Diagnosis Workflow
+
+When a session isn't showing up or behaving correctly, follow these steps:
+
+### Step 1: Check if Events are Being Written
+
+First, verify that events are being captured:
+
+```bash
+# Watch for new events in real-time
+tail -f ~/.agent-tracker/sessions.jsonl
+```
+
+**Expected**: You should see JSON events appearing as Claude activity happens.
+
+**If no events appear**:
+- Hooks may not be installed or enabled
+- Check `.claude/settings.json` for enabled plugins
+- Verify plugin installation with `claude plugin list`
+
+### Step 2: View Event Timeline for the Session
+
+Check the chronological sequence of events:
+
+```bash
+# View timeline for specific session
+npm run debug:timeline -- --session-id <SESSION_ID> --limit 30
+
+# Or filter by project directory
+npm run debug:timeline -- --cwd /path/to/project
+```
+
+**Look for:**
+- ✓ `session_start` event exists
+- ✓ Activity events (tool_use, prompt_submit, stop)
+- ⚠️ `session_end` followed by more activity → **Session was re-opened**
+- ⚠️ Large gaps in activity → **Hooks may have stopped firing**
+- ⚠️ No `session_start` → **Hook didn't fire on session start**
+
+**Common patterns:**
+```
+12:30:48  session_start
+12:31:15  tool_use              Read
+12:45:54  session_end
+12:50:15  tool_use              Read    ← Activity after end = reopened session
+```
+
+### Step 3: Check Current Session State
+
+View exactly what the TUI sees:
+
+```bash
+# View specific session state
+npm run debug:sessions -- --session-id <SESSION_ID>
+
+# View all sessions
+npm run debug:sessions
+```
+
+**Key fields to check:**
+
+```json
+{
+  "status": "active",           // Should be "active" for running sessions
+  "isPhantom": false,            // Should be false for real sessions
+  "awaitingInput": true,         // True = waiting for user, false = Claude working
+  "lastActivityTime": "...",     // Should match recent activity
+  "endTime": null,               // Should be null/undefined for active sessions
+  "workSummary": "..."           // Current work description
+}
+```
+
+### Step 4: Diagnose Common Issues
+
+#### Issue: Session showing as "ended" but is still active
+
+**Symptoms:**
+- Timeline shows activity after `session_end`
+- Session state shows `status: "ended"`
+
+**Cause:** Session was ended and then re-opened. Activity events should re-activate the session.
+
+**Fix:** Session re-activation logic should handle this automatically (fixed in recent versions). If not working, check ActivityStore reducer.
+
+#### Issue: Session marked as phantom (`isPhantom: true`)
+
+**Symptoms:**
+- Session exists but doesn't appear in TUI
+- `isPhantom: true` in session state
+
+**Cause:** Transcript file appears to be a phantom (very small, not modified after creation)
+
+**Check:**
+```bash
+# Check transcript file size and times
+ls -lh ~/.claude/projects/.../SESSION_ID.jsonl
+stat -f "size=%z birthtime=%SB mtime=%Sm" ~/.claude/projects/.../SESSION_ID.jsonl
+```
+
+**Criteria for phantom:**
+- File size < 50KB AND
+- Modified time - birth time < 60 seconds
+
+#### Issue: Missing session (not in output at all)
+
+**Symptoms:**
+- No session found in `debug:sessions` output
+- Timeline shows no events for session
+
+**Debugging steps:**
+1. Check if session_start event was written to sessions.jsonl
+2. Verify hooks are enabled for this project
+3. Check if session was started before hooks were installed
+4. Look for errors in hook scripts
+
+#### Issue: `lastActivityTime` is old but timeline shows recent activity
+
+**Symptoms:**
+- Timeline has recent events
+- Session state shows old `lastActivityTime`
+
+**Cause:** Activity events aren't updating session state, or transcript polling isn't working
+
+**Check:**
+- Are activity events being dispatched to ActivityStore?
+- Is transcript polling enabled in App.tsx?
+
+## Debug Tool Reference
+
+### `npm run debug:sessions`
+
+**Purpose:** Dump current session state as JSON
+
+**Options:**
+- `--session-id <id>` - View single session
+- `--format pretty|compact` - Output formatting (default: pretty)
+- `--no-counts` - Exclude session counts
+- `--no-stats` - Exclude activity statistics
+
+**Output includes:**
+- All session metadata
+- Session status and states
+- Activity counts and statistics
+- Recent activity events
+
+### `npm run debug:timeline`
+
+**Purpose:** Show chronological event timeline
+
+**Options:**
+- `--session-id <id>` - Filter by session
+- `--cwd <path>` - Filter by project directory
+- `--limit <n>` - Number of events to show (default: 50)
+- `--format table|json` - Output format (default: table)
+
+**Event types shown:**
+- `session_start` - Session began
+- `session_end` - Session ended
+- `tool_use` - Claude used a tool (shows tool name)
+- `prompt_submit` - User submitted input
+- `stop` - Claude finished responding
+- `notification` - System notification
+- `subagent_stop` - Subagent finished
+
+## Advanced Debugging
+
+### Check Raw Event Structure
+
+If you need to see the exact event format:
+
+```bash
+# View specific event types
+grep "session_start" ~/.agent-tracker/sessions.jsonl | tail -1 | jq .
+
+# View events for a session
+grep "SESSION_ID" ~/.agent-tracker/sessions.jsonl | jq .
+```
+
+### Test Hook Installation
+
+Create a test session to verify hooks fire:
+
+```bash
+# In a separate terminal
+cd /tmp && claude "echo test"
+```
+
+Check if events appear in `~/.agent-tracker/sessions.jsonl`.
+
+### Monitor in Real-Time
+
+Set up multi-terminal debugging:
+
+**Terminal 1:** Run Agent Tracker TUI
+```bash
+npm run dev
+```
+
+**Terminal 2:** Watch events
+```bash
+tail -f ~/.agent-tracker/sessions.jsonl
+```
+
+**Terminal 3:** Start test Claude session
+```bash
+claude "list files"
+```
+
+You should see events in Terminal 2 and session in Terminal 1 immediately.
+
+## Key Architecture Points
+
+- **Redux-style state**: ActivityStore uses pure reducers
+- **Event-driven**: Everything flows from JSONL events
+- **Session re-activation**: Activity events re-activate ended sessions
+- **Phantom detection**: Based on transcript file size and timestamps
+- **Transcript polling**: Fallback for when hooks don't fire
+
+## Quick Fixes
+
+### Hooks not firing
+```bash
+# Reinstall plugin
+claude plugin uninstall agent-tracker
+claude plugin install agent-tracker
+```
+
+### Session state incorrect
+```bash
+# Check if ActivityStore reducer is handling events
+npm run debug:timeline -- --session-id <ID>
+npm run debug:sessions -- --session-id <ID>
+# Compare timestamps - should match
+```
+
+### Phantom session issue
+Check transcript file - if it's actually large and actively used, the phantom detection threshold may need adjustment in ActivityStore.ts:50.
+
+## When to Escalate
+
+If after following this workflow you can't identify the issue:
+
+1. Gather diagnostics:
+   ```bash
+   npm run debug:sessions -- --format compact > session-state.json
+   npm run debug:timeline -- --session-id <ID> --format json > timeline.json
+   ```
+
+2. Check for console errors in the TUI
+
+3. Review recent changes to ActivityStore, SessionTrackerService, or event processing
+
+4. File an issue with diagnostics attached

CLAUDE.md

@@ -1,5 +1,15 @@
 This is a TypeScript CLI TUI written using Ink (React for CLIs).
 
+## Quick Start: Debugging Agent Tracker
+
+If you're debugging Agent Tracker issues (sessions not showing, incorrect states, etc.), use the debug skill:
+
+```bash
+/debug-agent-tracker
+```
+
+This provides a guided workflow with debug commands, common issues, and troubleshooting steps.
+
 ## Development Guidelines
 
 As an LLM agent working on this project:
@@ -170,6 +180,42 @@ Both commands will trigger the SessionStart hook and write an event to the JSONL
 
 You should see the session appear in the TUI and events logged in terminal 2.
 
+## Debug Tools Quick Reference
+
+**For detailed debugging workflow and troubleshooting, use the debug skill:**
+
+```bash
+/debug-agent-tracker
+```
+
+The skill provides step-by-step diagnosis, common issue patterns, and fixes.
+
+### Quick Commands
+
+```bash
+# View current session state (what the TUI sees)
+npm run debug:sessions -- --session-id <session-id>
+
+# View event timeline for a session
+npm run debug:timeline -- --session-id <session-id> --limit 30
+
+# Watch events in real-time
+tail -f ~/.agent-tracker/sessions.jsonl
+```
+
+### Common Quick Checks
+
+**Session not showing or incorrect state?**
+1. Run: `npm run debug:timeline -- --session-id <id>`
+2. Look for: `session_end` followed by activity → Session was re-opened
+3. Check state: `npm run debug:sessions -- --session-id <id>`
+
+**Key fields to verify:**
+- `status`: Should be "active" for running sessions
+- `isPhantom`: Should be false for real sessions
+- `lastActivityTime`: Should match recent activity
+- `endTime`: Should be undefined for active sessions
+
 # Important references
 
 [Claude Hooks](https://docs.claude.com/en/docs/claude-code/hooks.md)