@playcraft/cli 0.0.43 → 0.0.46

package/project-template/.claude/skills/session-analyzer/scripts/subagent-tool-timeline.mjs

@@ -0,0 +1,106 @@
+#!/usr/bin/env node
+/**
+ * subagent-tool-timeline.mjs — Parse a subagent's JSONL to show all tool calls in sequence
+ *
+ * Usage:
+ *   node subagent-tool-timeline.mjs <subagent.jsonl>
+ *   node subagent-tool-timeline.mjs <subagent.jsonl> --compact
+ *
+ * Output: numbered tool call list with timestamps and input previews
+ */
+
+import { readFileSync } from 'fs';
+
+const filePath = process.argv[2];
+const compact = process.argv.includes('--compact');
+
+if (!filePath) {
+  console.error('Usage: node subagent-tool-timeline.mjs <subagent.jsonl> [--compact]');
+  process.exit(1);
+}
+
+const lines = readFileSync(filePath, 'utf8').trim().split('\n');
+const toolCalls = [];
+let startTs = null;
+let endTs = null;
+
+lines.forEach((line, idx) => {
+  try {
+    const obj = JSON.parse(line);
+    const ts = obj.timestamp;
+    if (ts) {
+      if (!startTs) startTs = ts;
+      endTs = ts;
+    }
+
+    if (obj.type === 'assistant') {
+      const blocks = obj.message?.content || [];
+      for (const b of blocks) {
+        if (b.type === 'tool_use') {
+          const inputStr = JSON.stringify(b.input || {});
+          toolCalls.push({
+            line: idx + 1,
+            ts,
+            name: b.name,
+            id: b.id,
+            inputPreview: compact ? inputStr.substring(0, 60) : inputStr.substring(0, 150),
+            // For Write/Edit, capture file path
+            filePath: b.input?.file_path || '',
+            // For Bash, capture command
+            command: b.input?.command?.substring(0, 80) || '',
+          });
+        }
+      }
+    }
+  } catch (e) { /* skip */ }
+});
+
+const totalDuration = startTs && endTs
+  ? ((new Date(endTs).getTime() - new Date(startTs).getTime()) / 1000).toFixed(1)
+  : '?';
+
+console.log(`=== SUBAGENT TOOL TIMELINE ===`);
+console.log(`File: ${filePath}`);
+console.log(`Duration: ${totalDuration}s | Tool calls: ${toolCalls.length}`);
+console.log('');
+
+// Group by phase (consecutive same-type operations)
+toolCalls.forEach((tc, i) => {
+  const time = tc.ts ? new Date(tc.ts).toISOString().substring(11, 19) : '??:??:??';
+  const num = String(i + 1).padStart(3, ' ');
+
+  if (compact) {
+    // Compact: one line per call
+    let detail = '';
+    if (tc.name === 'Write' || tc.name === 'Edit' || tc.name === 'Read') {
+      const fname = tc.filePath.split(/[/\\]/).pop();
+      detail = fname;
+    } else if (tc.name === 'Bash') {
+      detail = tc.command.substring(0, 50);
+    } else {
+      detail = tc.inputPreview.substring(0, 50);
+    }
+    console.log(`${num}. ${time} ${tc.name.padEnd(6)} ${detail}`);
+  } else {
+    // Full: name + input preview
+    console.log(`${num}. [L${tc.line}] ${time} ${tc.name}`);
+    if (tc.name === 'Write' || tc.name === 'Edit' || tc.name === 'Read') {
+      console.log(`     file: ${tc.filePath}`);
+    } else if (tc.name === 'Bash') {
+      console.log(`     cmd: ${tc.command}`);
+    } else if (tc.name === 'Grep' || tc.name === 'Glob') {
+      console.log(`     ${tc.inputPreview}`);
+    } else {
+      console.log(`     ${tc.inputPreview}`);
+    }
+  }
+});
+
+// Tool count summary
+console.log('');
+console.log('=== TOOL COUNT SUMMARY ===');
+const counts = {};
+toolCalls.forEach(tc => { counts[tc.name] = (counts[tc.name] || 0) + 1; });
+Object.entries(counts).sort((a, b) => b[1] - a[1]).forEach(([name, count]) => {
+  console.log(`  ${name}: ${count}`);
+});

package/project-template/.claude/skills/session-analyzer/scripts/time-gaps.mjs

@@ -0,0 +1,128 @@
+#!/usr/bin/env node
+/**
+ * time-gaps.mjs — Find the largest time gaps in a session/subagent JSONL
+ *
+ * Identifies performance bottlenecks: long thinking pauses, slow tool executions,
+ * and external command waits.
+ *
+ * Usage:
+ *   node time-gaps.mjs <file.jsonl>
+ *   node time-gaps.mjs <file.jsonl> --threshold 5     (gaps > 5s, default 10)
+ *   node time-gaps.mjs <file.jsonl> --top 20          (show top 20, default 10)
+ *
+ * Output: sorted list of time gaps with before/after context
+ */
+
+import { readFileSync } from 'fs';
+
+const filePath = process.argv[2];
+const thresholdIdx = process.argv.indexOf('--threshold');
+const threshold = thresholdIdx >= 0 ? parseFloat(process.argv[thresholdIdx + 1]) * 1000 : 10000;
+const topIdx = process.argv.indexOf('--top');
+const topN = topIdx >= 0 ? parseInt(process.argv[topIdx + 1], 10) : 10;
+
+if (!filePath) {
+  console.error('Usage: node time-gaps.mjs <file.jsonl> [--threshold <seconds>] [--top <N>]');
+  process.exit(1);
+}
+
+const lines = readFileSync(filePath, 'utf8').trim().split('\n');
+
+// Collect all timestamped events with description
+const events = [];
+lines.forEach((line, idx) => {
+  try {
+    const obj = JSON.parse(line);
+    if (!obj.timestamp) return;
+    const ts = new Date(obj.timestamp).getTime();
+    let desc = obj.type;
+
+    if (obj.type === 'assistant') {
+      const blocks = obj.message?.content || [];
+      const tools = blocks.filter(b => b.type === 'tool_use').map(b => b.name);
+      const hasThink = blocks.some(b => b.type === 'thinking');
+      const hasText = blocks.some(b => b.type === 'text');
+      const thinkSize = blocks.filter(b => b.type === 'thinking').reduce((sum, b) => sum + b.thinking.length, 0);
+
+      if (tools.length) {
+        desc = `TOOL[${tools.join(',')}]`;
+      } else {
+        desc = (hasThink ? `THINK(${(thinkSize / 1024).toFixed(1)}KB)` : '') + (hasText ? '+TEXT' : '');
+      }
+    } else if (obj.type === 'user') {
+      const content = obj.message?.content;
+      if (typeof content === 'string') {
+        desc = `USER: ${content.substring(0, 40)}`;
+      } else if (Array.isArray(content) && content[0]?.type === 'tool_result') {
+        const toolName = ''; // We don't have it here, but we can infer from context
+        const isErr = content[0].is_error;
+        desc = `RESULT${isErr ? '(ERR)' : ''}`;
+      }
+    }
+
+    events.push({ line: idx + 1, ts, desc });
+  } catch (e) { /* skip */ }
+});
+
+if (events.length < 2) {
+  console.log('Not enough timestamped events to analyze.');
+  process.exit(0);
+}
+
+// Find gaps
+const gaps = [];
+for (let i = 1; i < events.length; i++) {
+  const gap = events[i].ts - events[i - 1].ts;
+  if (gap >= threshold) {
+    gaps.push({
+      from: events[i - 1],
+      to: events[i],
+      gapMs: gap,
+    });
+  }
+}
+
+gaps.sort((a, b) => b.gapMs - a.gapMs);
+const shown = gaps.slice(0, topN);
+
+const totalDuration = events[events.length - 1].ts - events[0].ts;
+const totalGapTime = gaps.reduce((sum, g) => sum + g.gapMs, 0);
+
+console.log(`=== TIME GAP ANALYSIS ===`);
+console.log(`File: ${filePath}`);
+console.log(`Total duration: ${(totalDuration / 1000).toFixed(1)}s`);
+console.log(`Gaps > ${(threshold / 1000).toFixed(0)}s: ${gaps.length} found`);
+console.log(`Total gap time: ${(totalGapTime / 1000).toFixed(1)}s (${(totalGapTime / totalDuration * 100).toFixed(1)}% of duration)`);
+console.log('');
+
+console.log(`=== TOP ${shown.length} GAPS (sorted by duration) ===\n`);
+shown.forEach((g, i) => {
+  const dur = (g.gapMs / 1000).toFixed(1);
+  const pct = (g.gapMs / totalDuration * 100).toFixed(1);
+  console.log(`#${i + 1}: ${dur}s (${pct}% of total)`);
+  console.log(`  FROM: L${g.from.line} | ${g.from.desc}`);
+  console.log(`  TO:   L${g.to.line} | ${g.to.desc}`);
+
+  // Classify the gap
+  let category = 'unknown';
+  if (g.to.desc.startsWith('THINK')) category = 'LLM thinking (output generation)';
+  else if (g.to.desc.startsWith('TOOL')) category = 'LLM deciding next tool call';
+  else if (g.to.desc === 'RESULT' || g.to.desc === 'RESULT(ERR)') category = 'Tool execution (external command)';
+  else if (g.from.desc.startsWith('TOOL[Bash]')) category = 'Bash command execution';
+  console.log(`  TYPE: ${category}`);
+  console.log('');
+});
+
+// Summary by category
+console.log('=== GAP CATEGORY SUMMARY ===');
+const categories = {};
+gaps.forEach(g => {
+  let cat = 'other';
+  if (g.to.desc.startsWith('THINK')) cat = 'LLM thinking';
+  else if (g.to.desc.startsWith('TOOL')) cat = 'LLM tool decision';
+  else if (g.to.desc.includes('RESULT')) cat = 'Tool execution';
+  categories[cat] = (categories[cat] || 0) + g.gapMs;
+});
+Object.entries(categories).sort((a, b) => b[1] - a[1]).forEach(([cat, ms]) => {
+  console.log(`  ${cat}: ${(ms / 1000).toFixed(1)}s (${(ms / totalDuration * 100).toFixed(1)}%)`);
+});

package/project-template/.claude/skills/session-analyzer/scripts/turn-timeline.mjs

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+/**
+ * turn-timeline.mjs — Parse and display event timeline for a specific turn range
+ *
+ * Usage:
+ *   node turn-timeline.mjs <session.jsonl> <startLine> [endLine]
+ *
+ * Output: chronological event list with timestamps, types, and previews
+ * If endLine is omitted, reads to end of file.
+ */
+
+import { readFileSync } from 'fs';
+
+const sessionPath = process.argv[2];
+const startLine = parseInt(process.argv[3], 10);
+const endLine = process.argv[4] ? parseInt(process.argv[4], 10) : Infinity;
+
+if (!sessionPath || isNaN(startLine)) {
+  console.error('Usage: node turn-timeline.mjs <session.jsonl> <startLine> [endLine]');
+  process.exit(1);
+}
+
+const lines = readFileSync(sessionPath, 'utf8').trim().split('\n');
+const end = Math.min(endLine, lines.length);
+
+console.log(`=== TURN TIMELINE: Lines ${startLine}-${end} ===\n`);
+
+for (let i = startLine - 1; i < end; i++) {
+  const lineNum = i + 1;
+  try {
+    const obj = JSON.parse(lines[i]);
+    const ts = obj.timestamp ? new Date(obj.timestamp).toISOString().substring(11, 19) : '        ';
+
+    if (obj.type === 'assistant') {
+      const blocks = obj.message?.content || [];
+      for (const b of blocks) {
+        if (b.type === 'thinking') {
+          const len = b.thinking.length;
+          const sizeTag = len > 10000 ? ` [${(len / 1024).toFixed(1)}KB]` : '';
+          console.log(`[${lineNum}] ${ts} THINK${sizeTag}: ${b.thinking.substring(0, 120)}`);
+        } else if (b.type === 'text') {
+          console.log(`[${lineNum}] ${ts} TEXT: ${b.text.substring(0, 150)}`);
+        } else if (b.type === 'tool_use') {
+          const inputPreview = JSON.stringify(b.input).substring(0, 100);
+          console.log(`[${lineNum}] ${ts} TOOL: ${b.name} | ${inputPreview}`);
+        }
+      }
+    } else if (obj.type === 'user') {
+      const content = obj.message?.content;
+      if (typeof content === 'string') {
+        console.log(`[${lineNum}] ${ts} USER: ${content.substring(0, 150)}`);
+      } else if (Array.isArray(content) && content[0]?.type === 'tool_result') {
+        const isErr = content[0].is_error;
+        const c = content[0].content;
+        const preview = typeof c === 'string' ? c.substring(0, 100) : JSON.stringify(c).substring(0, 100);
+        console.log(`[${lineNum}] ${ts} RESULT${isErr ? '(ERR)' : '(OK)'}: ${preview}`);
+      } else if (obj.promptSource === 'system' || obj.origin?.kind === 'task-notification') {
+        const text = Array.isArray(content) && content[0]?.text
+          ? content[0].text.substring(0, 100)
+          : typeof content === 'string' ? content.substring(0, 100) : '';
+        console.log(`[${lineNum}] ${ts} NOTIFY: ${text}`);
+      }
+    } else if (obj.type === 'system') {
+      console.log(`[${lineNum}] ${ts} SYSTEM: ${obj.subtype || ''}`);
+    }
+  } catch (e) { /* skip */ }
+}

package/project-template/.claude/snapshot.mjs

@@ -0,0 +1,350 @@
+#!/usr/bin/env node
+/**
+ * snapshot.mjs — Archive current project state + all AI sessions as a git commit + tag
+ *
+ * Usage:
+ *   node snapshot.mjs                              # snapshot cwd project
+ *   node snapshot.mjs <project-path>              # snapshot a specific project
+ *   node snapshot.mjs --project <path>            # same as above, explicit flag
+ *   node snapshot.mjs --name <label>              # custom label for the snapshot tag
+ *   node snapshot.mjs --force                     # skip active-CLI check
+ *   node snapshot.mjs --list [--project <path>]   # list all snapshot tags
+ *   node snapshot.mjs --delete <tag> [--project <path>]  # delete a snapshot tag
+ *
+ * What gets archived:
+ *   All tracked project files (git add -A)
+ *   .playcraft/sessions/  — session JSONL files (main + subagents) from all three stores
+ *                            (Claude Code / Claude Internal / CodeBuddy) matching the project path
+ *
+ * Output: annotated git tag  playcraft/snapshot/{label}_{MMDD_HHmm}
+ */
+
+import { execSync, spawnSync } from 'child_process';
+import { existsSync, readdirSync, statSync, mkdirSync, writeFileSync, rmSync, cpSync } from 'fs';
+import { join, basename, resolve } from 'path';
+import { homedir } from 'os';
+
+// ── helpers ──────────────────────────────────────────────────────────────────
+
+function parseArgs() {
+  const args = process.argv.slice(2);
+  const opts = { project: null, name: null, force: false, list: false, delete: null };
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--project' && args[i + 1]) opts.project = args[++i];
+    else if (args[i] === '--name' && args[i + 1]) opts.name = args[++i];
+    else if (args[i] === '--force') opts.force = true;
+    else if (args[i] === '--list') opts.list = true;
+    else if (args[i] === '--delete' && args[i + 1]) opts.delete = args[++i];
+    else if (!args[i].startsWith('--') && !opts.project) opts.project = args[i];
+  }
+  return opts;
+}
+
+function timestamp() {
+  const d = new Date();
+  const pad = n => String(n).padStart(2, '0');
+  return `${pad(d.getMonth() + 1)}${pad(d.getDate())}_${pad(d.getHours())}${pad(d.getMinutes())}`;
+}
+
+function isoNow() {
+  return new Date().toISOString();
+}
+
+// ── active CLI detection ─────────────────────────────────────────────────────
+
+function checkActiveCli() {
+  const pidsDir = join(homedir(), '.playcraft', 'pids');
+  if (!existsSync(pidsDir)) return { active: false, pids: [] };
+
+  const active = [];
+  try {
+    const files = readdirSync(pidsDir).filter(f => f.endsWith('.pid'));
+    for (const file of files) {
+      const pidPath = join(pidsDir, file);
+      try {
+        const pid = parseInt(execSync(`cat "${pidPath}"`, { encoding: 'utf8' }).trim(), 10);
+        if (isNaN(pid)) continue;
+        try {
+          process.kill(pid, 0);
+          active.push({ projectId: file.replace('.pid', ''), pid });
+        } catch {
+          // Process not running — stale PID file, ignore
+        }
+      } catch {
+        // Can't read PID file, skip
+      }
+    }
+  } catch {
+    // ignore
+  }
+  return { active: active.length > 0, pids: active };
+}
+
+// ── session collection ───────────────────────────────────────────────────────
+
+function findSessions(projectCwd) {
+  const home = homedir();
+  const stores = [
+    { name: 'claude-code',     path: join(home, '.claude', 'projects') },
+    { name: 'claude-internal', path: join(home, '.claude-internal', 'projects') },
+    { name: 'codebuddy',       path: join(home, '.codebuddy', 'projects') },
+  ];
+
+  const normalizedCwd = resolve(projectCwd).replace(/\\/g, '/');
+  const slugVariants = [
+    normalizedCwd.replace(/[:/]/g, '-').replace(/\//g, '-'),
+    normalizedCwd.replace(/\\/g, '-').replace(/:/g, '-'),
+  ];
+  const projectName = basename(normalizedCwd);
+
+  const found = [];
+
+  for (const store of stores) {
+    if (!existsSync(store.path)) continue;
+    let projects;
+    try { projects = readdirSync(store.path); } catch { continue; }
+
+    for (const proj of projects) {
+      const projLower = proj.toLowerCase();
+      const matches =
+        projLower.includes(projectName.toLowerCase()) ||
+        slugVariants.some(s => projLower.includes(s.toLowerCase().slice(-30)));
+
+      if (!matches) continue;
+
+      const projPath = join(store.path, proj);
+      let stat;
+      try { stat = statSync(projPath); } catch { continue; }
+      if (!stat.isDirectory()) continue;
+
+      let files;
+      try { files = readdirSync(projPath).filter(f => f.endsWith('.jsonl')); } catch { continue; }
+
+      for (const f of files) {
+        const sessionId = f.replace('.jsonl', '');
+        const sessionFile = join(projPath, f);
+        const subagentsDir = join(projPath, sessionId, 'subagents');
+        found.push({
+          store: store.name,
+          project: proj,
+          sessionId,
+          sessionFile,
+          subagentsDir: existsSync(subagentsDir) ? subagentsDir : null,
+        });
+      }
+    }
+  }
+
+  return found;
+}
+
+function waitForStable(sessionFile, maxRetries = 3, intervalMs = 500) {
+  let lastSize;
+  try { lastSize = statSync(sessionFile).size; } catch { return false; }
+
+  for (let i = 0; i < maxRetries; i++) {
+    const waitUntil = Date.now() + intervalMs;
+    while (Date.now() < waitUntil) { /* spin */ }
+
+    let newSize;
+    try { newSize = statSync(sessionFile).size; } catch { return false; }
+
+    if (newSize === lastSize) return true;
+    lastSize = newSize;
+  }
+
+  return false;
+}
+
+// ── git operations ───────────────────────────────────────────────────────────
+
+function gitExec(cwd, args, env = {}) {
+  const result = spawnSync('git', ['-C', cwd, ...args], {
+    encoding: 'utf8',
+    env: { ...process.env, ...env },
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  if (result.status !== 0) {
+    const errMsg = result.stderr?.trim() || result.stdout?.trim() || 'unknown error';
+    throw new Error(`git ${args[0]} failed: ${errMsg}`);
+  }
+  return result.stdout?.trim() || '';
+}
+
+function gitExecWithRetries(cwd, args, env = {}, maxRetries = 3) {
+  for (let attempt = 1; attempt <= maxRetries; attempt++) {
+    try {
+      return gitExec(cwd, args, env);
+    } catch (err) {
+      if (attempt < maxRetries && err.message.includes('.git/index.lock')) {
+        console.warn(`   ⚠  git index locked, retrying (${attempt}/${maxRetries})...`);
+        const waitUntil = Date.now() + 1000;
+        while (Date.now() < waitUntil) { /* spin */ }
+        continue;
+      }
+      throw err;
+    }
+  }
+}
+
+// ── main ─────────────────────────────────────────────────────────────────────
+
+const opts = parseArgs();
+
+if (opts.list) {
+  const projectDir = opts.project ? resolve(opts.project) : process.cwd();
+  try {
+    const tags = gitExec(projectDir, ['tag', '-l', 'playcraft/snapshot/*']);
+    if (!tags) {
+      console.log('No snapshots found.');
+    } else {
+      console.log('Snapshots:');
+      const tagList = tags.split('\n').filter(Boolean);
+      for (const tag of tagList) {
+        try {
+          const msg = gitExec(projectDir, ['tag', '-l', '--format=%(contents:subject)', tag]);
+          const date = gitExec(projectDir, ['tag', '-l', '--format=%(taggerdate:short)', tag]);
+          console.log(`  ${tag}  ${date || ''}  ${msg || ''}`);
+        } catch {
+          console.log(`  ${tag}`);
+        }
+      }
+    }
+  } catch (err) {
+    console.error(`Error listing snapshots: ${err.message}`);
+    process.exit(1);
+  }
+  process.exit(0);
+}
+
+if (opts.delete) {
+  const projectDir = opts.project ? resolve(opts.project) : process.cwd();
+  try {
+    gitExec(projectDir, ['tag', '-d', opts.delete]);
+    console.log(`Deleted tag: ${opts.delete}`);
+  } catch (err) {
+    console.error(`Error deleting snapshot: ${err.message}`);
+    process.exit(1);
+  }
+  process.exit(0);
+}
+
+// ── snapshot creation ─────────────────────────────────────────────────────────
+
+const executionCwd = process.cwd();
+const projectDir = opts.project ? resolve(executionCwd, opts.project) : executionCwd;
+const projectName = basename(projectDir);
+const ts = timestamp();
+const label = opts.name || `manual`;
+const tagName = `playcraft/snapshot/${label}_${ts}`;
+
+console.log(`\n📦 Snapshotting project: ${projectName}`);
+console.log(`   Source: ${projectDir}`);
+console.log(`   Tag   : ${tagName}\n`);
+
+// 1. Verify .git/ exists
+const gitDir = join(projectDir, '.git');
+if (!existsSync(gitDir)) {
+  console.error(`❌ No .git directory found at ${projectDir}`);
+  console.error('   Snapshot requires a git repository. Use "git init" first.');
+  process.exit(1);
+}
+
+// 2. Active CLI check
+if (!opts.force) {
+  const { active, pids } = checkActiveCli();
+  if (active) {
+    console.warn('⚠  Active PlayCraft CLI process(es) detected:');
+    for (const { projectId, pid } of pids) {
+      console.warn(`   - project ${projectId} (PID: ${pid})`);
+    }
+    console.warn('   Continuing anyway... Use --force to suppress this warning.\n');
+  }
+}
+
+// 3. Collect sessions with write stability detection
+console.log('🗂  Finding sessions...');
+const sessions = findSessions(projectDir);
+
+const sessionsDir = join(projectDir, '.playcraft', 'sessions');
+if (existsSync(sessionsDir)) {
+  rmSync(sessionsDir, { recursive: true, force: true });
+}
+mkdirSync(sessionsDir, { recursive: true });
+
+if (sessions.length === 0) {
+  console.log('   ⚠  No sessions found for this project path');
+} else {
+  console.log(`   Found ${sessions.length} session(s):`);
+  for (const s of sessions) {
+    const stable = waitForStable(s.sessionFile);
+    if (!stable) {
+      console.warn(`   ⚠  Session file still being written: ${s.sessionId.slice(0, 8)}… — copying anyway`);
+    }
+
+    const sessionDestDir = join(sessionsDir, s.store, s.project);
+    mkdirSync(sessionDestDir, { recursive: true });
+    cpSync(s.sessionFile, join(sessionDestDir, `${s.sessionId}.jsonl`));
+
+    let subCount = 0;
+    if (s.subagentsDir) {
+      const subDest = join(sessionDestDir, s.sessionId, 'subagents');
+      mkdirSync(subDest, { recursive: true });
+      const subFiles = readdirSync(s.subagentsDir).filter(f => f.endsWith('.jsonl'));
+      for (const sf of subFiles) {
+        cpSync(join(s.subagentsDir, sf), join(subDest, sf));
+        subCount++;
+      }
+    }
+
+    const sizeMB = (statSync(s.sessionFile).size / 1024 / 1024).toFixed(2);
+    console.log(`   ✓ [${s.store}] ${s.sessionId.slice(0, 8)}… (${sizeMB}MB, ${subCount} subagents)`);
+  }
+}
+
+// 4. Write manifest
+const manifest = {
+  createdAt: isoNow(),
+  projectName,
+  projectPath: projectDir,
+  label: opts.name || 'manual',
+  tag: tagName,
+  sessionCount: sessions.length,
+  sessions: sessions.map(s => ({
+    store: s.store,
+    project: s.project,
+    sessionId: s.sessionId,
+    hasSubagents: !!s.subagentsDir,
+  })),
+};
+writeFileSync(join(sessionsDir, 'manifest.json'), JSON.stringify(manifest, null, 2));
+
+// 5. Git add all changes (including sessions)
+console.log('\n📝 Staging changes...');
+const GIT_ENV = {
+  GIT_AUTHOR_NAME: 'PlayCraft Snapshot',
+  GIT_AUTHOR_EMAIL: 'snapshot@playcraft.local',
+  GIT_COMMITTER_NAME: 'PlayCraft Snapshot',
+  GIT_COMMITTER_EMAIL: 'snapshot@playcraft.local',
+};
+
+gitExecWithRetries(projectDir, ['add', '-A'], GIT_ENV);
+console.log('   ✓ Staged');
+
+// 6. Commit
+console.log('\n💾 Committing snapshot...');
+const commitMsg = `snapshot: ${label} (${ts})`;
+gitExecWithRetries(projectDir, ['commit', '--allow-empty', '-m', commitMsg], GIT_ENV);
+const commitHash = gitExec(projectDir, ['rev-parse', '--short', 'HEAD']);
+console.log(`   ✓ Commit: ${commitHash}`);
+
+// 7. Tag
+console.log('\n🏷  Creating tag...');
+gitExecWithRetries(projectDir, ['tag', '-a', tagName, '-m', commitMsg], GIT_ENV);
+console.log(`   ✓ Tag: ${tagName}`);
+
+// 8. Summary
+console.log(`\n✅ Snapshot complete!`);
+console.log(`   Tag : ${tagName}`);
+console.log(`   Hash: ${commitHash}`);
+console.log(`   Sessions archived: ${sessions.length}\n`);