elliot-stack 1.0.18 → 1.0.19

package/README.md

@@ -56,6 +56,17 @@ npx elliot-stack@latest
 
 External contributions are welcome via pull request. Direct pushes to `main` are blocked — fork the repo, push your changes to a branch, and open a PR. Only the maintainer (Elliot) can merge to `main` and cut releases. This is intentional: `elliot-stack` is a security-sensitive npm package and the release tag can only be pushed by the maintainer.
 
+### Testing locally
+
+Run the installer straight from your checkout to preview what a real install would do to your `~/.claude/`:
+
+```bash
+node bin/install.cjs            # dry run — previews changes, writes nothing
+node bin/install.cjs --install  # actually sync your local edits to ~/.claude/skills/
+```
+
+Run from the repo, the installer **dry-runs by default** so testing never clobbers your live `~/.claude/skills/` install. Pass `--install` once the preview looks right. (`--dry-run` forces a preview even under `npx`.)
+
 See [`docs/publishing.md`](docs/publishing.md) for the release flow and security model.
 
 ## License

package/bin/install.cjs

@@ -21,6 +21,19 @@ const PACKAGE_HOOKS_DIR = path.join(__dirname, '..', 'hooks');
 // ── Flags ──────────────────────────────────────────────────────────────────
 const SILENT = process.argv.includes('--silent');
 const STARTUP = process.argv.includes('--startup');
+// When run directly from the repo (not via npx/node_modules), default to dry-run
+// so local testing never silently clobbers the live ~/.claude/skills install.
+// Pass --install to actually write files, or --dry-run to force preview mode.
+const IS_LOCAL = !__dirname.includes('node_modules');
+const DRY_RUN = process.argv.includes('--dry-run') ||
+  (IS_LOCAL && !process.argv.includes('--install'));
+
+// ── Deprecated skills ──────────────────────────────────────────────────────
+// Skills that were renamed or removed. The installer removes these on every
+// run so users don't end up with both the old and new name installed.
+const DEPRECATED_SKILLS = [
+  'estack-prompt-builder', // renamed to estack-prompt-builder-coach
+];
 
 // ── Helpers ────────────────────────────────────────────────────────────────
 
@@ -44,7 +57,8 @@ function walkDir(dir, base) {
 function computeFileHash(filePath) {
   if (!fs.existsSync(filePath)) return null;
   const hash = crypto.createHash('sha256');
-  hash.update(fs.readFileSync(filePath));
+  const raw = fs.readFileSync(filePath);
+  hash.update(Buffer.from(raw.toString('utf8').replace(/\r\n/g, '\n')));
   return hash.digest('hex');
 }
 
@@ -54,9 +68,9 @@ function computeSkillHash(skillDir) {
   const files = walkDir(skillDir, skillDir);
   for (const relPath of files) {
     const fullPath = path.join(skillDir, relPath);
-    const contents = fs.readFileSync(fullPath);
+    const raw = fs.readFileSync(fullPath);
     hash.update(relPath.replace(/\\/g, '/'));
-    hash.update(contents);
+    hash.update(Buffer.from(raw.toString('utf8').replace(/\r\n/g, '\n')));
   }
   return hash.digest('hex');
 }
@@ -137,7 +151,9 @@ function getSkillDescription(skillDir) {
 
 // ── Hook setup ─────────────────────────────────────────────────────────────
 
-function setupStartupHook() {
+// Returns true if the hook was added (or would be added in dryRun), false if
+// it was already configured. In dryRun mode nothing is written to disk.
+function setupStartupHook(dryRun) {
   let settings = {};
   if (fs.existsSync(SETTINGS_FILE)) {
     try {
@@ -160,6 +176,8 @@ function setupStartupHook() {
     }
   }
 
+  if (dryRun) return true;
+
   if (!settings.hooks) settings.hooks = {};
   if (!settings.hooks.SessionStart) settings.hooks.SessionStart = [];
 
@@ -181,7 +199,9 @@ function setupStartupHook() {
   return true;
 }
 
-function setupRepoSearchNudgeHook() {
+// Returns true if the hook was added (or would be added in dryRun), false if
+// it was already configured. In dryRun mode nothing is written to disk.
+function setupRepoSearchNudgeHook(dryRun) {
   let settings = {};
   if (fs.existsSync(SETTINGS_FILE)) {
     try {
@@ -203,6 +223,8 @@ function setupRepoSearchNudgeHook() {
     }
   }
 
+  if (dryRun) return true;
+
   if (!settings.hooks) settings.hooks = {};
   if (!settings.hooks.PostToolUse) settings.hooks.PostToolUse = [];
 
@@ -223,6 +245,29 @@ function setupRepoSearchNudgeHook() {
 // ── Main ────────────────────────────────────────────────────────────────────
 
 async function main() {
+  // 0. Remove deprecated skills (renamed/deleted from the package)
+  if (fs.existsSync(SKILLS_DIR)) {
+    const newChecksums0 = fs.existsSync(CHECKSUMS_FILE)
+      ? (() => { try { return JSON.parse(fs.readFileSync(CHECKSUMS_FILE, 'utf8')); } catch (_) { return {}; } })()
+      : {};
+    let changed = false;
+    for (const name of DEPRECATED_SKILLS) {
+      const dir = path.join(SKILLS_DIR, name);
+      if (fs.existsSync(dir)) {
+        if (!DRY_RUN) fs.rmSync(dir, { recursive: true, force: true });
+        delete newChecksums0[name];
+        changed = true;
+        if (!SILENT && !STARTUP) {
+          console.log((DRY_RUN ? '  [dry run] Would remove deprecated skill: ' : '  Removed deprecated skill: ') + name);
+        }
+      } else if (newChecksums0[name]) {
+        delete newChecksums0[name];
+        changed = true;
+      }
+    }
+    if (changed && !DRY_RUN) fs.writeFileSync(CHECKSUMS_FILE, JSON.stringify(newChecksums0, null, 2));
+  }
+
   // 1. Scan package skills
   if (!fs.existsSync(PACKAGE_SKILLS_DIR)) {
     if (!SILENT && !STARTUP) {
@@ -287,7 +332,7 @@ async function main() {
     } else if (currentHash !== storedChecksums[name]) {
       // Stored checksum exists but current doesn't match — user modified it
       modifiedSkills.push(name);
-      if (storedChecksums[name] !== packageHashes[name]) {
+      if (currentHash !== packageHashes[name]) {
         needsUpdate.push(name);
       }
     } else if (currentHash !== packageHashes[name]) {
@@ -467,32 +512,39 @@ async function main() {
         console.log('    - ' + filename);
       }
     }
-    console.log('\nChoose an action:');
-    console.log('  [o] Overwrite all (replace with latest)');
-    console.log('  [s] Skip all (keep local versions)');
-    console.log('  [m] Merge (backup local, install new, merge in Claude Code)');
-    console.log('  [a] Abort (cancel installation)');
-    console.log('');
 
-    const answer = await promptChar('Your choice (o/s/m/a): ');
-
-    if (answer === 'a') {
-      console.log('Installation aborted.');
-      process.exit(0);
-    } else if (answer === 's') {
-      modifiedAction = 'skip';
-    } else if (answer === 'm') {
-      modifiedAction = 'merge';
-    } else if (answer === 'o') {
+    if (DRY_RUN) {
+      console.log('\n[dry run] Would prompt: overwrite / skip / merge / abort');
+      console.log('[dry run] Showing what would happen with default overwrite...');
       modifiedAction = 'overwrite';
     } else {
-      console.log('Invalid choice. Installation aborted.');
-      process.exit(1);
+      console.log('\nChoose an action:');
+      console.log('  [o] Overwrite all (replace with latest)');
+      console.log('  [s] Skip all (keep local versions)');
+      console.log('  [m] Merge (backup local, install new, merge in Claude Code)');
+      console.log('  [a] Abort (cancel installation)');
+      console.log('');
+
+      const answer = await promptChar('Your choice (o/s/m/a): ');
+
+      if (answer === 'a') {
+        console.log('Installation aborted.');
+        process.exit(0);
+      } else if (answer === 's') {
+        modifiedAction = 'skip';
+      } else if (answer === 'm') {
+        modifiedAction = 'merge';
+      } else if (answer === 'o') {
+        modifiedAction = 'overwrite';
+      } else {
+        console.log('Invalid choice. Installation aborted.');
+        process.exit(1);
+      }
     }
   }
 
   // 8. Install skills
-  fs.mkdirSync(SKILLS_DIR, { recursive: true });
+  if (!DRY_RUN) fs.mkdirSync(SKILLS_DIR, { recursive: true });
   const newChecksums = Object.assign({}, storedChecksums);
   let installedCount = 0;
   const mergedSkills = [];
@@ -506,23 +558,29 @@ async function main() {
         continue;
       }
       if (modifiedAction === 'merge') {
-        backupSkill(name);
+        if (!DRY_RUN) backupSkill(name);
         mergedSkills.push(name);
-        console.log('  Backed up ' + name + ' → ~/.claude/.estack-backup/' + name);
+        console.log((DRY_RUN ? '  [dry run] Would back up ' : '  Backed up ') + name + ' → ~/.claude/.estack-backup/' + name);
       }
       // overwrite or merge — fall through to install
     } else if (!needsUpdate.includes(name) && fs.existsSync(path.join(SKILLS_DIR, name))) {
       // Already installed and up-to-date
+      if (DRY_RUN) console.log('  [dry run] Up to date (no change): ' + name);
       continue;
     }
-    copyDir(path.join(PACKAGE_SKILLS_DIR, name), path.join(SKILLS_DIR, name));
+    const isUpdate = fs.existsSync(path.join(SKILLS_DIR, name));
+    if (!DRY_RUN) copyDir(path.join(PACKAGE_SKILLS_DIR, name), path.join(SKILLS_DIR, name));
     newChecksums[name] = packageHashes[name];
     installedCount++;
-    console.log('  Installed ' + name);
+    if (DRY_RUN) {
+      console.log('  [dry run] Would ' + (isUpdate ? 'update ' : 'install ') + name);
+    } else {
+      console.log('  Installed ' + name);
+    }
   }
 
   // 8b. Install hooks
-  fs.mkdirSync(HOOKS_DIR, { recursive: true });
+  if (!DRY_RUN) fs.mkdirSync(HOOKS_DIR, { recursive: true });
   let installedHookCount = 0;
   const mergedHooks = [];
 
@@ -535,33 +593,48 @@ async function main() {
         continue;
       }
       if (modifiedAction === 'merge') {
-        backupHook(filename);
+        if (!DRY_RUN) backupHook(filename);
         mergedHooks.push(filename);
-        console.log('  Backed up hook ' + filename + ' → ~/.claude/.estack-backup/hooks/' + filename);
+        console.log((DRY_RUN ? '  [dry run] Would back up hook ' : '  Backed up hook ') + filename + ' → ~/.claude/.estack-backup/hooks/' + filename);
       }
       // overwrite or merge — fall through to install
     } else if (!hooksNeedingUpdate.includes(filename) && fs.existsSync(path.join(HOOKS_DIR, filename))) {
       // Already installed and up-to-date
+      if (DRY_RUN) console.log('  [dry run] Up to date (no change): hook ' + filename);
       continue;
     }
-    fs.copyFileSync(path.join(PACKAGE_HOOKS_DIR, filename), path.join(HOOKS_DIR, filename));
+    const isHookUpdate = fs.existsSync(path.join(HOOKS_DIR, filename));
+    if (!DRY_RUN) fs.copyFileSync(path.join(PACKAGE_HOOKS_DIR, filename), path.join(HOOKS_DIR, filename));
     newChecksums['hook:' + filename] = packageHookHashes[filename];
     installedHookCount++;
-    console.log('  Installed hook ' + filename);
+    if (DRY_RUN) {
+      console.log('  [dry run] Would ' + (isHookUpdate ? 'update hook ' : 'install hook ') + filename);
+    } else {
+      console.log('  Installed hook ' + filename);
+    }
   }
 
   // 9. Write checksums
-  fs.writeFileSync(CHECKSUMS_FILE, JSON.stringify(newChecksums, null, 2));
+  if (!DRY_RUN) fs.writeFileSync(CHECKSUMS_FILE, JSON.stringify(newChecksums, null, 2));
 
   // 10. Setup startup hook and repo-search nudge hook
-  const hookInstalled = setupStartupHook();
-  const nudgeHookInstalled = setupRepoSearchNudgeHook();
+  // In dry-run these inspect settings.json read-only and report would-be action.
+  const hookInstalled = setupStartupHook(DRY_RUN);
+  const nudgeHookInstalled = setupRepoSearchNudgeHook(DRY_RUN);
 
   // 11. Summary output
-  console.log('\nestack installed successfully!\n');
-  console.log('  ' + installedCount + ' skill' + (installedCount !== 1 ? 's' : '') + ' installed to ~/.claude/skills/');
-  if (installedHookCount > 0) {
-    console.log('  ' + installedHookCount + ' hook' + (installedHookCount !== 1 ? 's' : '') + ' installed to ~/.claude/hooks/');
+  if (DRY_RUN) {
+    console.log('\n[dry run] No files were changed. Run with --install to apply.\n');
+    console.log('  ' + installedCount + ' skill' + (installedCount !== 1 ? 's' : '') + ' would be installed/updated in ~/.claude/skills/');
+    if (installedHookCount > 0) {
+      console.log('  ' + installedHookCount + ' hook' + (installedHookCount !== 1 ? 's' : '') + ' would be installed/updated in ~/.claude/hooks/');
+    }
+  } else {
+    console.log('\nestack installed successfully!\n');
+    console.log('  ' + installedCount + ' skill' + (installedCount !== 1 ? 's' : '') + ' installed to ~/.claude/skills/');
+    if (installedHookCount > 0) {
+      console.log('  ' + installedHookCount + ' hook' + (installedHookCount !== 1 ? 's' : '') + ' installed to ~/.claude/hooks/');
+    }
   }
   console.log('');
   console.log('Skills available:');
@@ -582,15 +655,27 @@ async function main() {
     console.log('Backed up to ~/.claude/.estack-backup/hooks/');
   }
 
-  if (hookInstalled) {
-    console.log('\nAuto-update hook added to ~/.claude/settings.json');
-    console.log('Skills will update automatically when you start Claude Code.');
+  if (DRY_RUN) {
+    if (hookInstalled) {
+      console.log('\n[dry run] Would add auto-update hook to ~/.claude/settings.json');
+    } else {
+      console.log('\nAuto-update hook already configured (no change).');
+    }
+    if (nudgeHookInstalled) {
+      console.log('[dry run] Would register repo-search nudge hook in settings.json.');
+    } else {
+      console.log('Repo-search nudge hook already configured (no change).');
+    }
   } else {
-    console.log('\nAuto-update hook already configured.');
-  }
-
-  if (nudgeHookInstalled) {
-    console.log('Repo-search nudge hook registered in settings.json.');
+    if (hookInstalled) {
+      console.log('\nAuto-update hook added to ~/.claude/settings.json');
+      console.log('Skills will update automatically when you start Claude Code.');
+    } else {
+      console.log('\nAuto-update hook already configured.');
+    }
+    if (nudgeHookInstalled) {
+      console.log('Repo-search nudge hook registered in settings.json.');
+    }
   }
 
   console.log('');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "elliot-stack",
-  "version": "1.0.18",
+  "version": "1.0.19",
   "description": "Elliot's skill stack for Claude Code — install via npx elliot-stack@latest",
   "bin": {
     "elliot-stack": "bin/install.cjs"

package/skills/estack-read-claude-session-history/SKILL.md

@@ -0,0 +1,196 @@
+---
+name: estack-read-claude-session-history
+description: (read-claude-session-history) Invoke for ANY task involving Claude Code session history, transcripts, or .jsonl files — this is the only way to read, parse, or search them; do not attempt to use Bash or Read on .jsonl directly. Use for: recovering context after /compact ("what were we doing before compact"), advisor response retrieval ("what did the advisor say"), subagent output collection ("get all subagent finals"), cross-project session search by keyword, session listing and triage, UUID and title lookup, resume-command generation, file-edit and tool-call forensics, session diff between two sessions or subagents, weekly work journal, day timeline of activity blocks and idle gaps, recovering from .claude-backups after data loss, session count queries, and reading the last agent message before a crash or interrupt. Trigger phrases: "session history", "before compact", "what did claude do", "what did I work on", "search my sessions", "find that session", "what did the advisor say", "what did the agent edit", "from the backup", "list my sessions", "subagent outputs", "session journal", "resume previous", "which files did claude touch", "go back and look", "what did I do yesterday", "where did my day go", "timeline of my day", "how much time on".
+---
+
+# Read Claude Session History
+
+Search, read, recover, and compare Claude Code session history — across the current session, prior sessions, sibling subagents, all projects, and `.claude-backups` snapshots.
+
+Sessions are stored as `.jsonl` files. Reading them raw is hopeless: 1,000–5,000+ lines of dense JSON per session, 33+ project directories, hundreds of historical sessions. This skill wraps a single CLI that knows the entry schema and exposes ~20 modes.
+
+## Quick start
+
+```bash
+PY="C:\Users\2supe\.claude\skills\read-claude-session-history\scripts\read_transcript.py"
+
+# What was the last thing the agent said in this session?
+python "$PY" --file <current-session.jsonl> --mode last
+
+# Get a 6-line summary of any session (intent, last activity, edits, tool counts, subagent fanout)
+python "$PY" --file <session.jsonl> --mode brief
+
+# Recover what got cut off by the most recent /compact
+python "$PY" --file <session.jsonl> --mode pre-compact
+
+# Find a session by UUID prefix across all projects
+python "$PY" --mode lookup --uuid abc123de
+
+# Search every session in every project for a phrase
+python "$PY" --mode search --all-projects --query "supabase migration"
+
+# Pull subagent outputs from a fan-out investigation
+python "$PY" --file <parent.jsonl> --mode subagent-finals
+
+# Block-grouped timeline of a whole day across all sessions, with idle gaps
+python "$PY" --mode timeline --date yesterday
+
+# Any mode as structured JSON for piping into the next step
+python "$PY" --mode list --project keel --since 7d --format json
+```
+
+## Time handling — READ THIS before doing anything with time
+
+**Every time the CLI displays is already the user's local time.** JSONL files store
+UTC; the script converts on output. Do NOT add or subtract timezone offsets
+yourself, do NOT cross-reference file mtimes to infer the timezone, and do NOT
+treat raw `"timestamp"` fields from a .jsonl (which ARE UTC) as comparable to CLI
+output. If you need a different zone, pass `--tz` (IANA name like
+`America/New_York`, `UTC`, or an offset like `-4`) — never convert manually.
+`--since/--until/--date` specs are interpreted in that same display timezone.
+
+## Decision tree
+
+```
+What are you trying to do?
+│
+├─ Read the current session / one specific session
+│  ├─ Last assistant message ──────────────────── --mode last
+│  ├─ All advisor responses ───────────────────── --mode advisor
+│  ├─ Content cut off by /compact ─────────────── --mode pre-compact
+│  ├─ Full human-readable dump ────────────────── --mode dump (size-aware)
+│  ├─ 6-line summary for triage ───────────────── --mode brief
+│  └─ Schema/structural diagnosis ─────────────── --mode debug
+│
+├─ Find a session I don't have the path for
+│  ├─ By UUID prefix ──────────────────────────── --mode lookup --uuid <prefix>
+│  ├─ By title or first prompt ────────────────── --mode find --title|--first-prompt
+│  └─ Generate a `claude --resume` command ───── --mode resume-cmd --uuid <prefix>
+│
+├─ Search content
+│  ├─ One session ─────────────────────────────── --mode search --file …
+│  ├─ One project ─────────────────────────────── --mode search --cwd …
+│  ├─ All projects ────────────────────────────── --mode search --all-projects
+│  └─ Filter to user msgs / tool-use inputs ──── --role user --in tool_use
+│
+├─ Forensics on a session
+│  ├─ Chronological tool-call log ────────────── --mode changelog
+│  ├─ Every file touched ─────────────────────── --mode file-edits
+│  └─ Every tool call (optionally filtered) ──── --mode tool-calls --tool Bash,Edit
+│
+├─ Subagent (fan-out) work
+│  ├─ List spawned subagents ─────────────────── --mode subagent-list
+│  ├─ Get every subagent's final message ─────── --mode subagent-finals
+│  └─ Forensics on one subagent ──────────────── --mode subagent-tools|subagent-files --subagent …
+│
+├─ Cross-cutting reporting
+│  ├─ "What did I do this week?" ──────────────── --mode journal --since 7d
+│  ├─ "Where did my day go?" / day timeline ───── --mode timeline --date yesterday
+│  ├─ "How much time on <project>?" ───────────── --mode timeline --project <name> --date …
+│  ├─ Count sessions matching a query ─────────── --mode count --query …
+│  └─ Resume where I left off in this project ─── --mode resume-prev --cwd …
+│
+└─ Compare two sessions or two sibling subagents
+   └─ Interleaved diff ──────────────────────── --mode diff --file-a … --file-b …  (or --subagents-of …)
+```
+
+## Quick reference
+
+| Mode | Required flags | Returns |
+|---|---|---|
+| `last` | `--file` | Last N assistant text outputs |
+| `advisor` | `--file` | All `advisor_tool_result` payloads |
+| `pre-compact` | `--file` | 40 exchanges before the most recent `/compact` |
+| `dump` | `--file` | Human-readable dump (auto-degrades on transcripts >5MB) |
+| `search` | `--query` + scope | Matches windowed for context (supports `--role`, `--in text|tool_use|thinking|all`) |
+| `debug` | `--file` | Entry/block type distributions + probes |
+| `brief` | `--file` | 6-line summary: uuid·project·mtime·status / intent / last / edits / tools / subagents |
+| `list` | `--cwd` or `--all-projects` | Rich table: mtime, size, uuid, msg count, flags, status, title |
+| `lookup` | `--uuid <prefix>` | Absolute path (exit 1 missing, exit 2 ambiguous) |
+| `find` | `--title` or `--first-prompt` | Sessions ranked by recency |
+| `resume-cmd` | `--uuid <prefix>` | `cd <cwd>; claude --resume <uuid>` snippet |
+| `changelog` | `--file` | `HH:MM:SS  TOOL  one-line-summary`, day-grouped |
+| `file-edits` | `--file` | Unique paths sorted with op tags |
+| `tool-calls` | `--file` (+ `--tool` filter) | Timestamped per-call blocks |
+| `subagent-list` | `--file` | List sibling subagents with agentType + description |
+| `subagent-finals` | `--file` | Every subagent's final assistant message |
+| `subagent-tools` | `--subagent` | Forensics on one subagent |
+| `subagent-files` | `--subagent` | Files one subagent touched |
+| `resume-prev` | `--cwd` | Banner + dump-style tail of last 10 exchanges |
+| `count` | `--query` (+ scope) | `<N>` to stdout, summary to stderr |
+| `journal` | `--since` (+ scope) | Per-session 5-line block: date·uuid / prompt / ended / edits / tools |
+| `timeline` | `--date` or `--since/--until` (defaults: today, all projects) | Block-grouped day timeline across sessions with idle gaps + active-time totals |
+| `diff` | `--file-a` + `--file-b` OR `--subagents-of` | Timestamp-interleaved A>/B> output |
+
+## Global flags
+
+- `--root {live|mirror|snapshot-24h|snapshot-1w|snapshot-1mo|<abs-path>}` — read from a `.claude-backups` mirror or snapshot instead of live. Default `live`.
+- `--cwd <path>` — single-project scope. Use the original working directory (e.g. `"C:\Users\2supe\Other Claude Code"`).
+- `--all-projects` — walk every project under `--root`.
+- `--project <name>` — filter projects by name substring, case-insensitive, matches encoded or decoded form (`--project keel`, `--project "Other Claude Code"`). Works on `list`, `journal`, `search`, `count`, `find`, `timeline`. Use this instead of `--cwd` when you know the project's name but not its exact path.
+- `--file <path>` — single-session scope.
+- `--since <spec>` / `--until <spec>` — accepts ISO date, ISO datetime, relative (`30m`, `24h`, `7d`, `1w`, `1mo`), named (`today`, `yesterday`, `now`).
+- `--date <spec>` — single-day window for `timeline` (`--date yesterday`, `--date 2026-06-01`).
+- `--gap <spec>` — idle-gap threshold for `timeline` blocks (`15m` default, `1h`).
+- `--tz <spec>` — display timezone override (IANA name, `UTC`, or offset like `-4`). Default: system local time.
+- `--format json` (or `--json`) — structured JSON output on every mode (except the legacy `--list`/`--list-subagents` aliases). Pipe-friendly: paths are strings, timestamps ISO.
+- `--exclude-current` — drop the current session (detected via `CLAUDE_SESSION_ID`) from `list`, `journal`, `search`, `count`, and `timeline`.
+- `--include-subagents` — fold subagent finals into `brief`, `last`, `dump` output, each tagged `[subagent <id-short> · <agentType>]`.
+- `--force-dump` — bypass the 5 MB `dump` guard.
+- `-n N` — count modifier (default 5 for `last`, 80 for `dump`, 10 for `resume-prev`).
+
+The current session is marked with `[*]` in `list` output. Status glyphs: ✓ clean, ! interrupted, ? pending-user, ● active. Sessions with a compact marker get `[C]`; sessions with subagents get `[S]`.
+
+## Backup-aware reads
+
+In March 2026 a Claude Code auto-update deleted live `.jsonl` transcripts (GitHub #41591). To survive that class of incident, this machine maintains four backup roots under `C:\Users\2supe\.claude-backups\`:
+
+- `mirror` — continuous mirror
+- `snapshot-24h` — 24-hour-old snapshot
+- `snapshot-1w` — 1-week-old snapshot
+- `snapshot-1mo` — 1-month-old snapshot
+
+Any mode accepts `--root <name>`. The resolved root is printed to stderr.
+
+```bash
+# Find a session that was deleted from live but still in yesterday's snapshot
+python "$PY" --root snapshot-24h --mode lookup --uuid <prefix>
+
+# Compare today's mirror against a week ago to confirm what was lost
+python "$PY" --root snapshot-1w --cwd "C:\Users\2supe\Other Claude Code" --list
+```
+
+See `references/recipes.md` → "Deletion-incident recovery" for the full playbook.
+
+## Common workflows
+
+| Need | Command |
+|---|---|
+| Recover advisor output that scrolled out of context | `--file <session> --mode advisor` |
+| Get back to what you were doing before `/compact` | `--file <session> --mode pre-compact` |
+| Fan-out triage: 14 subagents, want all of their finals | `--file <parent> --mode subagent-finals` (or `--mode brief --include-subagents`) |
+| Find "that session where I asked about supabase rate limits" | `--mode search --all-projects --query "supabase rate limits"` |
+| Resume a project after a few days away | `--mode resume-prev --cwd "<project path>"` |
+| Daily/weekly journal | `--mode journal --since 7d --all-projects` |
+| "Where did yesterday go?" | `--mode timeline --date yesterday` |
+| "How much time on Keel today?" | `--mode timeline --project keel --date today` |
+| Feed session data into a script | any mode + `--format json` |
+
+See `references/recipes.md` for fuller multi-step workflows.
+
+## Windows notes
+
+- Use `python` (not `python3`) on this Windows setup.
+- The script handles UTF-8 stdout/stderr internally — both PowerShell and Bash work fine for single commands.
+- **Piping `--format json` into another command: use Bash.** PowerShell 5.1 pipes inject a UTF-8 BOM and re-encode through the console codepage, breaking `json.load` (see `references/recipes.md` §5c for the PowerShell workaround).
+- File paths with spaces need quoting: `--cwd "C:\Users\2supe\Other Claude Code"`.
+
+## Reference docs
+
+- `references/modes.md` — complete per-mode reference (every flag, every example, exit codes).
+- `references/jsonl-schema.md` — entry/block schema, subagent meta sidecars, compact-marker shape.
+- `references/recipes.md` — multi-step workflows (post-compact recovery, find-then-dump, deletion recovery, week-in-review journal, sibling-agent diff).
+
+## When the modes return empty
+
+If a mode returns empty/unexpected output, run `--mode debug` first. It prints the entry-type distribution, content-block types, and probes for advisor + compact markers — useful when the transcript schema has drifted or when a session was truncated.

package/skills/estack-read-claude-session-history/references/jsonl-schema.md

@@ -0,0 +1,126 @@
+# JSONL schema reference
+
+What's actually inside a Claude Code session `.jsonl`. Only relevant when extending the script or debugging an unexpected empty result.
+
+## File location
+
+```
+C:\Users\<user>\.claude\projects\<encoded-cwd>\<session-uuid>.jsonl
+```
+
+The `<encoded-cwd>` is the original working directory with every `:`, `\`, `/`, and whitespace character replaced by `-`. Examples on this machine:
+
+| Original CWD | Encoded directory |
+|---|---|
+| `C:\Users\2supe\Other Claude Code` | `C--Users-2supe-Other-Claude-Code` |
+| `C:\Users\2supe\Other Claude Code\Personal Brand Project` | `C--Users-2supe-Other-Claude-Code-Personal-Brand-Project` |
+| `C:\Users\2supe\AppData\Local\Temp` | `C--Users-2supe-AppData-Local-Temp` |
+
+The encoding is lossy — single hyphens in the original path collapse into the same hyphens that separate segments. Use `--mode lookup` / `--mode find` to recover the actual session path; `decode_project_name()` produces a display-only approximation.
+
+## Backup roots
+
+The same encoded-directory layout exists under each `.claude-backups\<name>\projects\` root:
+
+```
+C:\Users\2supe\.claude-backups\
+  ├── mirror\projects\<encoded-cwd>\<uuid>.jsonl
+  ├── snapshot-24h\projects\<encoded-cwd>\<uuid>.jsonl
+  ├── snapshot-1w\projects\<encoded-cwd>\<uuid>.jsonl
+  └── snapshot-1mo\projects\<encoded-cwd>\<uuid>.jsonl
+```
+
+`--root mirror|snapshot-24h|snapshot-1w|snapshot-1mo` rebases all path resolution to that snapshot. An absolute path argument is also accepted.
+
+## Subagent transcripts
+
+When a session spawns subagents (via the `Agent` / `Task` tool), each subagent's own transcript is written to:
+
+```
+<project-dir>\<session-uuid>\subagents\agent-<id>.jsonl
+```
+
+A sidecar metadata file lives next to it:
+
+```
+<project-dir>\<session-uuid>\subagents\agent-<id>.meta.json
+```
+
+The meta file contains:
+
+```json
+{
+  "agentType": "Explore",
+  "description": "Find every reference to X"
+}
+```
+
+When the meta file is missing, `subagents.load_meta` returns `{"agentType": "unknown", "description": ""}`.
+
+Subagent entries inside the parent transcript are marked with `isSidechain: true` and carry an `agentId` field.
+
+## Entry types
+
+Each line in a `.jsonl` is a JSON object with a `type` field. Entry classifications:
+
+| `type` value | Classification | Notes |
+|---|---|---|
+| `user` | signal (user) | `message.content` may be string or array. Compact markers live here. |
+| `assistant` | signal (assistant) | `message.content` is always an array of blocks. |
+| `ai-title` / `custom-title` | title | `aiTitle` / `customTitle` field carries the session title. |
+| `permission-mode` | noise | mode change events |
+| `attachment` | noise | file attachments |
+| `last-prompt` | noise | cached last prompt |
+| `queue-operation` | noise | internal queueing |
+| `file-history-snapshot` | noise | file state snapshots |
+| `system` | noise | system events |
+| `agent-name` | noise | agent name metadata |
+| `pr-link` | noise | PR linkage |
+
+The `noise` and `title` entries are skipped by `get_messages()`. `debug` mode prints the full distribution.
+
+## Assistant content block types
+
+The `message.content` array for assistant entries can hold:
+
+| Block `type` | Field of interest | Meaning |
+|---|---|---|
+| `text` | `text` | The actual assistant text output. |
+| `thinking` | `thinking` (or `text`) | Model internal reasoning. |
+| `tool_use` | `name`, `input`, `id` | A regular tool call. `id` is the matching id for any later `tool_result`. |
+| `server_tool_use` | `name`, `input` | Server-side tool call (e.g., advisor invocation). |
+| `advisor_tool_result` | `content.text` | The advisor's reply. Always nested as `block.content.text`. |
+| `tool_result` | `tool_use_id`, `content` | Result for a prior `tool_use`. `content` is a string or an array of `{type:"text", text:"..."}`. |
+
+## Compact marker
+
+A `/compact` event appears as a `type:"user"` entry whose first text content starts with:
+
+> `"This session is being continued from a previous conversation"`
+
+`classify_entry` returns `"compact"` for these. Everything before the most-recent compact marker is the pre-compact conversation.
+
+## Timestamps
+
+Most entries carry a `timestamp` field in ISO-8601 form (`2026-05-01T10:00:05Z`). `_parse_timestamp` accepts ISO strings, naive ISO, and numeric epoch values. Timezone-aware values are stripped for comparison with `--since`/`--until` (which use local naive datetimes).
+
+## Title entries
+
+Both `ai-title` and `custom-title` entries surface a `aiTitle` / `customTitle` string. `session_summary()` prefers `aiTitle` when both are present.
+
+## Truncation behavior
+
+`iter_lines` drops the final line if it lacks a trailing newline AND fails to parse as JSON, printing `[note: dropped truncated trailing line in <name>]` to stderr. Malformed mid-file lines are dropped silently.
+
+## Status inference
+
+`infer_status(lines, mtime, current_session_id, session_uuid)` returns one of:
+
+| Status | Glyph | Heuristic |
+|---|---|---|
+| `active` | ● | `current_session_id == session_uuid` AND `mtime` within 5 minutes |
+| `interrupted` | ! | Any `tool_use` block lacks a paired `tool_result` |
+| `pending-user` | ? | Last assistant text message ends with `?` |
+| `clean` | ✓ | none of the above |
+
+This is heuristic — it's correct for the majority of real sessions on this machine but can be fooled by, e.g., an assistant message that legitimately ends with a question.