Samara-main debug-session

Debug Samara session management, message batching, and task routing. Use when messages are scrambled, batching seems wrong, group chats behave oddly, or concurrent tasks interfere with each other. Trigger words: session, batch, group chat, concurrent, scrambled, task routing.

install

source · Clone the upstream repo

git clone https://github.com/claudeaceae/samara-main

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/claudeaceae/samara-main "$T" && mkdir -p ~/.claude/skills && cp -r "$T/.claude/skills/debug-session" ~/.claude/skills/claudeaceae-samara-main-debug-session && rm -rf "$T"

manifest: .claude/skills/debug-session/skill.md

source content

Debug Session Management

Diagnose issues with Samara's message batching, session continuity, and task routing.

Session Architecture Overview

Messages arrive
      │
      ▼
SessionManager buffers (11 sec)
      │
      ▼
TaskRouter classifies tasks
      │
      ├─► Conversation ──► invokeBatch (with session)
      ├─► Webcam ────────► invokeIsolated (no session)
      ├─► WebFetch ──────► invokeIsolated (no session)
      └─► Skill ─────────► invokeIsolated (no session)
      │
      ▼
MessageBus sends response (with source tag)

Quick Diagnostics

1. Check Active Sessions

# View session state files
ls ~/.claude-mind/memory/sessions 2>/dev/null | head -30

# Check for stale locks
cat ~/.claude-mind/state/locks/system-cli.lock 2>/dev/null
ls -la ~/.claude-mind/state/locks/system-cli.lock

2. Check Message Batching

# Look for batch processing in logs
grep -E "(Buffering|batch|BatchReady)" ~/.claude-mind/system/logs/samara.log | tail -20

# Check batch sizes
grep "Processing batch of" ~/.claude-mind/system/logs/samara.log | tail -10

3. Check Task Classification

# Look for isolated vs session-based invocations
grep -E "(Isolated invocation|Resuming session|Starting new session)" ~/.claude-mind/system/logs/samara.log | tail -20

4. Check Group Chat Handling

# Group chat routing decisions
grep -E "(group chat|chatIdentifier|isGroupChat)" ~/.claude-mind/system/logs/samara.log | tail -20

# Look for routing warnings
grep -E "(WARNING.*group|looks like group)" ~/.claude-mind/system/logs/samara.log | tail -10

Common Issues

Scrambled Responses

Symptom: Responses seem to mix answers to different questions Cause: Multiple task types in same batch not properly isolated Check:

# Look for multiple task types in same batch
grep -B5 -A5 "Processing batch" ~/.claude-mind/system/logs/samara.log | tail -30

Fix: TaskRouter should classify and isolate parallel tasks

Session Not Resuming

Symptom: Context lost between messages Cause: Session ID not being passed correctly Check:

# Check session recording
grep "Recorded session" ~/.claude-mind/system/logs/samara.log | tail -10

# Check session retrieval
grep "Retrieved session" ~/.claude-mind/system/logs/samara.log | tail -10

Group Chat Messages Going to Wrong Chat

Symptom: Response sent to 1:1 instead of group Cause:

isGroupChat

flag not set correctly Check:

# Check routing decisions
grep "Routing decision" ~/.claude-mind/system/logs/samara.log | tail -10

Queue Not Processing

Symptom: Messages acknowledged but never answered Cause: TaskLock stuck or QueueProcessor not running Check:

# Check lock status
cat ~/.claude-mind/state/locks/system-cli.lock

# Check queue processor
grep "QueueProcessor" ~/.claude-mind/system/logs/samara.log | tail -10

# Force release stale lock if needed
# rm ~/.claude-mind/state/locks/system-cli.lock

Task Routing Reference

Request Type	Detection	Isolation
Conversation	Default	Uses session
Webcam	"webcam", "camera", "photo"	Isolated
WebFetch	URLs, "check this"	Isolated
Skill	Starts with "/"	Isolated

Session State Files

File	Purpose
`~/.claude-mind/memory/sessions/*.json`	Per-chat session state
`~/.claude-mind/state/locks/system-cli.lock`	Current task lock
`~/.claude-mind/state/message-queue.json`	Pending messages

Diagnostic Report

When debugging session issues, gather:

Recent batch processing logs
Session state file contents
Lock file status
Task routing decisions
Group chat routing decisions