@playcraft/cli 0.0.57 → 0.0.59

package/project-template-v2/.claude/skills/session-analyzer/SKILL.md

@@ -0,0 +1,386 @@
+---
+name: session-analyzer
+description: >
+  Navigate and analyze AI coding session logs (Claude Code / Claude Internal / CodeBuddy).
+  Use when asked to find specific tool calls, understand what happened in a turn,
+  trace subagent work, or answer "what did the agent do here?" questions.
+triggers: session, turn, subagent, agent做了什么, 为什么这么多步骤, 查会话, 分析session, 读日志
+---
+
+# Session Analyzer
+
+Analyze AI coding assistant session logs stored as JSONL files in the session tracker project
+(`D:\project\cli-tool-tracker`).
+
+## Quick Reference: Directory Layout
+
+```
+~/.claude/projects/                      ← Claude Code sessions
+  {project-slug}/
+    {session-uuid}.jsonl                 ← main session file
+    {session-uuid}/subagents/            ← subagent files
+      agent-{hex}.jsonl
+      agent-{hex}.meta.json
+
+~/.claude-internal/projects/             ← Claude Internal sessions
+  {project-slug}/
+    {session-uuid}.jsonl                 ← main session file
+    {session-uuid}/subagents/
+      agent-{hex}.jsonl
+      agent-{hex}.meta.json
+
+~/.codebuddy/projects/                   ← CodeBuddy sessions
+  {project-slug}/
+    {session-uuid}.jsonl
+    {session-uuid}/subagents/
+      agent-{hex}.jsonl
+```
+
+## How to Find a Specific Session
+
+### Method 1: Use the Session Tracker UI
+
+1. Start the tracker: `cd D:\project\cli-tool-tracker && pnpm run dev`
+2. Select the source tab (CodeBuddy / Claude / Claude Internal)
+3. Find the project in the Projects list → click to list sessions
+4. Click a session to see its turns
+5. Click a turn to see events (tool calls, messages, reasoning)
+6. Click any event to see full context (input/output/raw JSON)
+
+### Method 2: Command-line Search
+
+```powershell
+# Find project directories
+ls ~\.claude-internal\projects\ | Where Name -like "*keyword*"
+
+# List sessions in a project
+ls ~\.claude-internal\projects\D--project-{name}\ | Where Name -like "*.jsonl"
+
+# Find a specific session by date/size
+ls ~\.claude-internal\projects\D--project-{name}\*.jsonl | Sort Length -Desc | Select -First 10 Name,Length
+
+# Search JSONL for specific tool calls
+Select-String -Path "path\to\session.jsonl" -Pattern '"name":"Agent"' | Select -First 10 LineNumber,Line
+
+# Search for specific content in a session
+Select-String -Path "path\to\session.jsonl" -Pattern "keyword" | Select LineNumber,@{n='Preview';e={$_.Line.Substring(0,200)}}
+```
+
+## JSONL Line Types (Claude / Claude-Internal Format)
+
+Each line is a JSON object with a `type` field:
+
+| Line Type                      | Description                 | Key Fields                                                                  |
+| ------------------------------ | --------------------------- | --------------------------------------------------------------------------- |
+| `"user"`                       | User message or tool result | `message.content` (text or tool_result blocks)                              |
+| `"assistant"`                  | AI response                 | `message.content` (thinking/text/tool_use blocks), `message.usage` (tokens) |
+| `"system"`                     | System event                | `subtype`, `content`                                                        |
+| `"attachment"`                 | Skill listing, permissions  | `attachment.type`, `attachment.content`                                     |
+| `"file-history-snapshot"`      | File tracking               | `snapshot.trackedFileBackups`                                               |
+| `"ai-title"`                   | Auto-generated title        | `aiTitle`                                                                   |
+| `"mode"` / `"permission-mode"` | Session config              | `mode`, `permissionMode`                                                    |
+
+### Assistant Message Content Blocks
+
+Within an `"assistant"` line, `message.content[]` contains:
+
+| Block Type   | Description                | Data Location                                             |
+| ------------ | -------------------------- | --------------------------------------------------------- |
+| `"thinking"` | Model's reasoning/thinking | `block.thinking` (text), `block.signature`                |
+| `"text"`     | Display text reply         | `block.text`                                              |
+| `"tool_use"` | Tool call                  | `block.name`, `block.id` (callId), `block.input` (params) |
+
+### Tool Result Content Blocks
+
+Within a `"user"` line, `message.content[]` contains:
+
+| Block Type      | Description           | Data Location                                                                    |
+| --------------- | --------------------- | -------------------------------------------------------------------------------- |
+| `"tool_result"` | Tool execution result | `block.tool_use_id` (matches callId), `block.content` (output), `block.is_error` |
+
+## Subagent Relationship
+
+### How Subagents are Spawned
+
+1. Main agent calls `Agent` tool → `function_call` event with `toolName: "Agent"`
+2. Runtime spawns a subagent process → writes to `subagents/agent-{hex}.jsonl`
+3. When subagent finishes → `function_call_result` with `toolUseResult.agentId: "{hex}"`
+4. The `agentId` links the main session's Agent call to the subagent file
+
+**Critical**: In Claude Internal format, `agentId` is at `toolUseResult.agentId` in the JSONL
+(outer structure of the result line), NOT in the text content.
+
+### Subagent File Format
+
+Same as main JSONL but with:
+
+- `"agentId": "a2834ad1c500a2f8c"` on user/assistant lines
+- `"isSidechain": true` on all lines
+- `"attributionAgent": "Explore"` on assistant lines (agent type)
+- Each subagent file = one agent invocation (may have multiple turns internally)
+
+### How to Trace Subagent Work
+
+1. In the main session JSONL, find the Agent `tool_use` line → note `block.id` (callId)
+2. Find the corresponding `tool_result` line (same `tool_use_id`)
+3. Extract `agentId` from `toolUseResult.agentId`
+4. The subagent file is `subagents/agent-{agentId}.jsonl`
+5. Read that file to see what the subagent did
+
+## Turn Structure
+
+A **turn** starts when the user sends a message and ends when the AI finishes responding
+(including all tool calls and their results). The turn splitter detects turns by:
+
+- A `user` message (not a tool_result) → starts a new turn
+- If `parentUuid` points to an assistant message → new turn
+- If `parentUuid` points to another user message → continuation of current turn
+
+Turns contain: user message → assistant thinking → assistant text → tool calls → results → more assistant responses → ...
+
+## How to Analyze a Turn
+
+### Step 1: Identify the Turn Boundaries
+
+```powershell
+# In the tracker UI: expand a turn to see its events
+# OR manually in JSONL:
+Select-String -Path "session.jsonl" -Pattern '"type":"user".*"role":"user"' | Select LineNumber
+```
+
+### Step 2: List All Tool Calls in a Turn
+
+```powershell
+Select-String -Path "session.jsonl" -Pattern '"type":"tool_use"' | Select LineNumber,@{n='Tool';e={if($_.Line -match '"name":"([^"]+)"'){$matches[1]}}}
+```
+
+### Step 3: Find Agent (Subagent) Calls
+
+```powershell
+Select-String -Path "session.jsonl" -Pattern '"name":"Agent"' -Context 0,5 | Select LineNumber
+```
+
+### Step 4: Check Subagent Results
+
+```powershell
+# Find results of a specific tool_use_id
+Select-String -Path "session.jsonl" -Pattern "TOOL_USE_ID_HERE" | Select LineNumber
+```
+
+### Step 5: Read Subagent Files
+
+```powershell
+ls "session-dir\subagents\agent-*.jsonl" | ForEach { Write-Host "--- $($_.Name) ---"; Get-Content $_.FullName -Head 3 }
+```
+
+## Reusable Analysis Scripts
+
+All scripts are in the `scripts/` directory relative to this skill. Run with Node.js (ESM).
+
+### Quick Reference
+
+| Script                       | Purpose                                    | Usage                                                           |
+| ---------------------------- | ------------------------------------------ | --------------------------------------------------------------- |
+| `resolve-session.mjs`        | Find session file path by project keyword  | `node scripts/resolve-session.mjs <keyword> [uuid]`             |
+| `find-turns.mjs`             | List all user-initiated turns in a session | `node scripts/find-turns.mjs <session.jsonl>`                   |
+| `turn-timeline.mjs`          | Show event timeline for a line range       | `node scripts/turn-timeline.mjs <session.jsonl> <start> [end]`  |
+| `subagent-stats.mjs`         | Extract stats for all Agent calls          | `node scripts/subagent-stats.mjs <session.jsonl> [start] [end]` |
+| `subagent-tool-timeline.mjs` | Show tool call sequence in a subagent      | `node scripts/subagent-tool-timeline.mjs <subagent.jsonl>`      |
+| `time-gaps.mjs`              | Find performance bottleneck (time gaps)    | `node scripts/time-gaps.mjs <file.jsonl> [--threshold 5]`       |
+| `heavy-output.mjs`           | Find heaviest output turns                 | `node scripts/heavy-output.mjs <file.jsonl> [--min-kb 3]`       |
+| `execution-breakdown.mjs`    | Auto-detect phases & time allocation       | `node scripts/execution-breakdown.mjs <subagent.jsonl>`         |
+
+### Typical Analysis Workflow
+
+```bash
+# 1. Resolve session path
+node scripts/resolve-session.mjs tencent-test10 55f43f72-...
+
+# 2. Find turns
+node scripts/find-turns.mjs /path/to/session.jsonl
+
+# 3. Look at specific turn (e.g. turn starting at line 205, ending at 337)
+node scripts/turn-timeline.mjs /path/to/session.jsonl 205 337
+
+# 4. Get subagent stats (which agents ran, how long, how many tokens)
+node scripts/subagent-stats.mjs /path/to/session.jsonl 205 337
+
+# 5. Deep-dive into a slow subagent
+node scripts/subagent-tool-timeline.mjs /path/to/subagents/agent-abc123.jsonl --compact
+node scripts/time-gaps.mjs /path/to/subagents/agent-abc123.jsonl --threshold 5
+node scripts/execution-breakdown.mjs /path/to/subagents/agent-abc123.jsonl
+node scripts/heavy-output.mjs /path/to/subagents/agent-abc123.jsonl --min-kb 3
+```
+
+### Script Details
+
+#### resolve-session.mjs
+
+Searches all three session stores (Claude Code / Claude Internal / CodeBuddy) by keyword.
+
+- With just a keyword: lists all sessions in matching projects (sorted by size)
+- With keyword + UUID: resolves to exact file path + lists subagent files
+
+#### find-turns.mjs
+
+Identifies turn boundaries by finding user messages with `promptSource` (typed/system).
+
+- `--verbose`: show previews for all turns (not just typed)
+- Distinguishes user-typed vs system-triggered turns
+
+#### turn-timeline.mjs
+
+Shows chronological events within a line range. Tags each event:
+
+- `THINK [size]`: thinking blocks with size indicator
+- `TOOL: <name>`: tool calls with input preview
+- `RESULT(OK/ERR)`: tool results
+- `NOTIFY`: system notifications
+
+#### subagent-stats.mjs
+
+For each Agent tool call in the range, extracts from `toolUseResult`:
+
+- `agentId`, `agentType`, `status`
+- `totalDurationMs`, `totalTokens`, `totalToolUseCount`
+- `toolStats` breakdown (read/search/bash/edit counts, lines added/removed)
+- Summary comparison table when multiple agents found
+
+#### subagent-tool-timeline.mjs
+
+Parses a subagent's JSONL to show every tool call in sequence.
+
+- `--compact`: one line per call (good for overview)
+- Shows file names for Read/Write/Edit, commands for Bash
+- Includes tool count summary at the end
+
+#### time-gaps.mjs
+
+Finds the largest time gaps between events to identify bottlenecks.
+
+- `--threshold <seconds>`: minimum gap to report (default: 10s)
+- `--top <N>`: how many gaps to show (default: 10)
+- Classifies each gap: LLM thinking, tool execution, bash command
+- Shows gap category summary with percentages
+
+#### heavy-output.mjs
+
+Finds turns that generated the most content (thinking + text + file writes).
+
+- `--min-kb <N>`: minimum output size to report (default: 5KB)
+- `--top <N>`: how many to show (default: 15)
+- Breaks down: thinking KB, text KB, write KB
+- Shows output category breakdown (thinking vs text vs file writes)
+
+#### execution-breakdown.mjs
+
+Auto-detects "phases" in a subagent's execution and calculates time allocation.
+
+- Groups by: thinking, reading files, writing files, bash commands, etc.
+- Classifies bash commands: npm install, dev server, process debugging, etc.
+- Shows time allocation with ASCII bar chart
+- Useful for answering "where did the time go?"
+
+## Legacy PowerShell Scripts (kept for reference)
+
+### Helper Script: Find Subagent Files for a Session
+
+```powershell
+# Save as: find-subagents.ps1
+param($SessionPath)
+
+$dir = Split-Path $SessionPath -Parent
+$sid = Split-Path $SessionPath -Leaf
+$sid = $sid -replace '\.jsonl$',''
+$subDir = Join-Path $dir $sid 'subagents'
+if (Test-Path $subDir) {
+    Get-ChildItem $subDir -Filter "agent-*.jsonl" | ForEach-Object {
+        $first = Get-Content $_.FullName -Head 1 | ConvertFrom-Json
+        $agentType = $first.attributionAgent ?? $first.message?.role ?? "?"
+        $lines = (Get-Content $_.FullName | Measure-Object).Count
+        Write-Host "$($_.Name) | type: $agentType | lines: $lines"
+    }
+} else {
+    Write-Host "No subagents directory at $subDir"
+}
+```
+
+### Helper Script: Summarize a Turn
+
+```powershell
+# Save as: summarize-turn.ps1
+# Usage: .\summarize-turn.ps1 -SessionPath "session.jsonl" -TurnStartLine 100
+param($SessionPath, $TurnStartLine = 1, $MaxLines = 500)
+
+$lines = Get-Content $SessionPath
+$end = [Math]::Min($TurnStartLine + $MaxLines, $lines.Count)
+
+for ($i = $TurnStartLine - 1; $i -lt $end; $i++) {
+    $line = $lines[$i]
+    try { $obj = $line | ConvertFrom-Json } catch { continue }
+
+    $ln = $i + 1
+    $ts = if ($obj.timestamp) { [DateTime]::Parse($obj.timestamp).ToString("HH:mm:ss") } else { "" }
+
+    if ($obj.type -eq 'user') {
+        $content = $obj.message.content
+        if ($content -is [string]) { Write-Host "[$ln] $ts USER: $content" }
+        elseif ($content[0].type -eq 'tool_result') {
+            $tid = $content[0].tool_use_id.Substring(0,20)
+            Write-Host "[$ln] $ts RESULT: $tid"
+        }
+    }
+    elseif ($obj.type -eq 'assistant') {
+        foreach ($b in $obj.message.content) {
+            if ($b.type -eq 'text') { Write-Host "[$ln] $ts TEXT: $($b.text.Substring(0,[Math]::Min(80,$b.text.Length)))" }
+            elseif ($b.type -eq 'thinking') { Write-Host "[$ln] $ts THINK: $($b.thinking.Substring(0,[Math]::Min(80,$b.thinking.Length)))" }
+            elseif ($b.type -eq 'tool_use') { Write-Host "[$ln] $ts TOOL: $($b.name) | $($b.id.Substring(0,20))" }
+        }
+    }
+    elseif ($obj.type -eq 'ai-title') { Write-Host "[$ln] $ts TITLE: $($obj.aiTitle)" }
+}
+```
+
+## Understanding a Turn: Step-by-Step Analysis
+
+When asked "what happened in this turn?" or "why did it do this?", follow this process:
+
+1. **Read the turn title** (`ai-title` lines) for high-level summary
+2. **Read the user message** — what was the request?
+3. **Read the assistant thinking** — what was the model planning?
+4. **List all tool calls** in order — what actions were taken?
+5. **For each Agent call**: check the subagent file to see what it explored/did
+6. **Read the tool results** — what came back?
+7. **Read the assistant text replies** — what was communicated?
+
+## Token Usage
+
+Each assistant message has `message.usage`:
+
+```json
+"usage": {
+  "input_tokens": 25441,
+  "output_tokens": 186,
+  "cache_read_input_tokens": 10624,
+  "cache_creation_input_tokens": 0
+}
+```
+
+- `input_tokens` + `output_tokens` = total tokens for this API call
+- `cache_read_input_tokens` > 0 means cache was hit (saved cost)
+- `cache_creation_input_tokens` > 0 means new cache entries were created
+- Usage appears on ALL lines sharing the same `message.id`; the LAST line has the most complete data
+
+## Quick Search Script
+
+```powershell
+# Save as: search-session.ps1
+# Usage: .\search-session.ps1 -Path "session.jsonl" -Query "Agent"
+param($Path, $Query)
+
+Select-String -LiteralPath $Path -Pattern $Query | ForEach-Object {
+    $preview = $_.Line.Substring(0, [Math]::Min(300, $_.Line.Length))
+    Write-Host "[$($_.LineNumber)] $preview"
+    Write-Host "---"
+}
+```

package/project-template-v2/.claude/skills/session-analyzer/scripts/execution-breakdown.mjs

@@ -0,0 +1,182 @@
+#!/usr/bin/env node
+/**
+ * execution-breakdown.mjs — Generate a phased execution breakdown for a subagent
+ *
+ * Automatically detects "phases" by grouping consecutive tool calls of similar type,
+ * then shows time allocation per phase. Useful for understanding where agent time was spent.
+ *
+ * Usage:
+ *   node execution-breakdown.mjs <subagent.jsonl>
+ *
+ * Output: phase breakdown with duration, percentage, and tool counts
+ */
+
+import { readFileSync } from 'fs';
+
+const filePath = process.argv[2];
+
+if (!filePath) {
+  console.error('Usage: node execution-breakdown.mjs <subagent.jsonl>');
+  process.exit(1);
+}
+
+const lines = readFileSync(filePath, 'utf8').trim().split('\n');
+
+// Collect timestamped events with tool info
+const events = [];
+lines.forEach((line, idx) => {
+  try {
+    const obj = JSON.parse(line);
+    if (!obj.timestamp) return;
+    const ts = new Date(obj.timestamp).getTime();
+
+    if (obj.type === 'assistant') {
+      const blocks = obj.message?.content || [];
+      for (const b of blocks) {
+        if (b.type === 'tool_use') {
+          let detail = '';
+          if (b.name === 'Write' || b.name === 'Edit' || b.name === 'Read') {
+            detail = b.input?.file_path?.split(/[/\\]/).pop() || '';
+          } else if (b.name === 'Bash') {
+            detail = (b.input?.command || '').substring(0, 50);
+          }
+          events.push({ line: idx + 1, ts, type: 'tool', name: b.name, detail });
+        } else if (b.type === 'thinking') {
+          events.push({ line: idx + 1, ts, type: 'thinking', size: b.thinking.length });
+        }
+      }
+    } else if (obj.type === 'user') {
+      const content = obj.message?.content;
+      if (Array.isArray(content) && content[0]?.type === 'tool_result') {
+        events.push({ line: idx + 1, ts, type: 'result', isError: content[0].is_error || false });
+      }
+    }
+  } catch (e) { /* skip */ }
+});
+
+if (events.length < 2) {
+  console.log('Not enough events to analyze.');
+  process.exit(0);
+}
+
+const totalDuration = events[events.length - 1].ts - events[0].ts;
+
+// Auto-detect phases: a "phase" changes when there's a significant thinking block (>5KB)
+// or when tool type shifts from read→write, write→bash, etc.
+const phases = [];
+let currentPhase = { start: events[0], events: [events[0]], label: '' };
+
+function classifyPhase(phaseEvents) {
+  const toolCounts = {};
+  let bigThink = 0;
+  phaseEvents.forEach(e => {
+    if (e.type === 'tool') toolCounts[e.name] = (toolCounts[e.name] || 0) + 1;
+    if (e.type === 'thinking' && e.size > 5000) bigThink++;
+  });
+
+  const dominant = Object.entries(toolCounts).sort((a, b) => b[1] - a[1])[0];
+  if (bigThink > 0 && !dominant) return 'Planning/Thinking';
+  if (!dominant) return 'Thinking';
+
+  const name = dominant[0];
+  const files = phaseEvents.filter(e => e.type === 'tool').map(e => e.detail).filter(Boolean);
+  const uniqueFiles = [...new Set(files)];
+
+  if (name === 'Read' && toolCounts.Read > toolCounts.Write) return 'Reading files';
+  if (name === 'Write') return `Writing files (${uniqueFiles.length} files)`;
+  if (name === 'Edit') return `Editing files (${uniqueFiles.length} files)`;
+  if (name === 'Bash') {
+    const cmds = phaseEvents.filter(e => e.type === 'tool' && e.name === 'Bash').map(e => e.detail);
+    if (cmds.some(c => c.includes('npm install') || c.includes('pnpm install'))) return 'Installing dependencies';
+    if (cmds.some(c => c.includes('http-server') || c.includes('dev') || c.includes('curl'))) return 'Dev server setup/verification';
+    if (cmds.some(c => c.includes('kill') || c.includes('netstat') || c.includes('lsof'))) return 'Process/port debugging';
+    return 'Running commands';
+  }
+  if (name === 'Grep' || name === 'Glob') return 'Searching codebase';
+  return `${name} operations`;
+}
+
+// Split into phases by significant gaps (>15s) or thinking blocks >10KB
+for (let i = 1; i < events.length; i++) {
+  const gap = events[i].ts - events[i - 1].ts;
+  const isBigThink = events[i].type === 'thinking' && events[i].size > 10000;
+  const isLongGap = gap > 15000;
+
+  if (isBigThink || isLongGap) {
+    // Finalize current phase
+    currentPhase.end = events[i - 1];
+    phases.push(currentPhase);
+    // Start new phase
+    currentPhase = { start: events[i], events: [events[i]], label: '' };
+  } else {
+    currentPhase.events.push(events[i]);
+  }
+}
+// Finalize last phase
+currentPhase.end = events[events.length - 1];
+phases.push(currentPhase);
+
+// Classify and calculate
+phases.forEach(p => {
+  p.duration = (p.end?.ts || p.start.ts) - p.start.ts;
+  // If phase is just a start event, estimate from gap
+  if (p.duration === 0 && phases.indexOf(p) < phases.length - 1) {
+    const nextPhase = phases[phases.indexOf(p) + 1];
+    p.duration = nextPhase.start.ts - p.start.ts;
+  }
+  p.label = classifyPhase(p.events);
+  p.toolCount = p.events.filter(e => e.type === 'tool').length;
+});
+
+// Merge very short phases (< 5s) into previous
+const mergedPhases = [];
+for (const p of phases) {
+  if (mergedPhases.length > 0 && p.duration < 5000) {
+    const prev = mergedPhases[mergedPhases.length - 1];
+    prev.events.push(...p.events);
+    prev.end = p.end;
+    prev.duration += p.duration;
+    prev.toolCount += p.toolCount;
+  } else {
+    mergedPhases.push(p);
+  }
+}
+
+// Re-classify merged phases
+mergedPhases.forEach(p => {
+  p.label = classifyPhase(p.events);
+});
+
+// Output
+console.log('=== EXECUTION BREAKDOWN ===');
+console.log(`File: ${filePath}`);
+console.log(`Total duration: ${(totalDuration / 1000).toFixed(1)}s (${(totalDuration / 1000 / 60).toFixed(1)} min)`);
+console.log(`Total events: ${events.length} | Phases detected: ${mergedPhases.length}`);
+console.log('');
+
+console.log('#'.padEnd(4) + 'Duration'.padEnd(12) + '%'.padEnd(8) + 'Tools'.padEnd(8) + 'Phase');
+console.log('-'.repeat(70));
+
+mergedPhases.forEach((p, i) => {
+  const dur = (p.duration / 1000).toFixed(0) + 's';
+  const pct = (p.duration / totalDuration * 100).toFixed(1) + '%';
+  console.log(
+    String(i + 1).padEnd(4) +
+    dur.padEnd(12) +
+    pct.padEnd(8) +
+    String(p.toolCount).padEnd(8) +
+    p.label
+  );
+});
+
+// Time allocation
+console.log('\n=== TIME ALLOCATION ===');
+const categories = {};
+mergedPhases.forEach(p => {
+  const cat = p.label.split(' (')[0]; // Remove file count details
+  categories[cat] = (categories[cat] || 0) + p.duration;
+});
+Object.entries(categories).sort((a, b) => b[1] - a[1]).forEach(([cat, ms]) => {
+  const bar = '#'.repeat(Math.round(ms / totalDuration * 40));
+  console.log(`  ${cat.padEnd(30)} ${(ms / 1000).toFixed(0)}s (${(ms / totalDuration * 100).toFixed(1)}%) ${bar}`);
+});

package/project-template-v2/.claude/skills/session-analyzer/scripts/find-turns.mjs

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+/**
+ * find-turns.mjs — Locate all user-initiated turns in a session JSONL
+ *
+ * Usage:
+ *   node find-turns.mjs <session.jsonl>
+ *   node find-turns.mjs <session.jsonl> --verbose
+ *
+ * Output: line number, timestamp, promptSource, and message preview for each turn start
+ */
+
+import { readFileSync } from 'fs';
+
+const sessionPath = process.argv[2];
+const verbose = process.argv.includes('--verbose');
+
+if (!sessionPath) {
+  console.error('Usage: node find-turns.mjs <session.jsonl> [--verbose]');
+  process.exit(1);
+}
+
+const lines = readFileSync(sessionPath, 'utf8').trim().split('\n');
+const turns = [];
+
+lines.forEach((line, idx) => {
+  try {
+    const obj = JSON.parse(line);
+    if (obj.type !== 'user') return;
+
+    const content = obj.message?.content;
+    // Skip tool_result lines — they're continuations, not new turns
+    if (Array.isArray(content) && content[0]?.type === 'tool_result') return;
+    // Skip system notifications unless they have promptSource
+    if (obj.origin?.kind === 'task-notification' && !obj.promptSource) return;
+
+    const ts = obj.timestamp || '';
+    const promptSource = obj.promptSource || 'tool_result';
+    const isTyped = promptSource === 'typed';
+    const isSystem = promptSource === 'system';
+
+    let preview = '';
+    if (typeof content === 'string') {
+      preview = content.substring(0, 100);
+    } else if (Array.isArray(content) && content[0]?.text) {
+      preview = content[0].text.substring(0, 100);
+    }
+
+    turns.push({ line: idx + 1, ts, promptSource, isTyped, preview });
+  } catch (e) { /* skip parse errors */ }
+});
+
+console.log(`=== TURNS FOUND: ${turns.length} ===\n`);
+
+turns.forEach((t, i) => {
+  const marker = t.isTyped ? '>>> ' : '    ';
+  const srcTag = `[${t.promptSource}]`.padEnd(10);
+  console.log(`${marker}Turn ${i + 1} | Line ${t.line} | ${t.ts} ${srcTag}`);
+  if (verbose || t.isTyped) {
+    console.log(`     ${t.preview}`);
+  }
+  console.log('');
+});
+
+// Print summary
+const typed = turns.filter(t => t.isTyped).length;
+const system = turns.filter(t => t.promptSource === 'system').length;
+console.log(`--- Summary: ${typed} user-typed, ${system} system-triggered, ${turns.length} total ---`);
+if (turns.length >= 2) {
+  const first = new Date(turns[0].ts).getTime();
+  const last = new Date(turns[turns.length - 1].ts).getTime();
+  console.log(`--- Session span: ${((last - first) / 1000 / 60).toFixed(1)} minutes ---`);
+}