@astrale-os/cli 0.5.0-alpha.0 → 0.6.1-alpha.0

package/src/telemetry/__tests__/session.test.ts

@@ -0,0 +1,166 @@
+import { afterEach, beforeAll, beforeEach, describe, expect, test } from 'bun:test'
+import {
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  utimesSync,
+  writeFileSync,
+} from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+import type { ResolvedSession } from '../session'
+import type { SessionMeta } from '../types'
+
+/** Seed an ambient session on disk with a chosen id + last-activity age. */
+function seedAmbient(id: string, root: string, ageMs: number): void {
+  mkdirSync(sessionDir(id), { recursive: true })
+  const meta: SessionMeta = { id, root, explicit: false, createdAt: new Date().toISOString() }
+  writeFileSync(metaPath(id), JSON.stringify(meta))
+  writeFileSync(eventsPath(id), '{}\n')
+  const when = new Date(Date.now() - ageMs)
+  utimesSync(eventsPath(id), when, when)
+}
+
+// Set ASTRALE_HOME before the store/paths singleton is first evaluated (below,
+// via dynamic import). All on-disk access goes through the store helpers so it
+// stays consistent whichever home the singleton captured.
+process.env.ASTRALE_HOME = mkdtempSync(join(tmpdir(), 'astrale-tele-session-'))
+
+let resolveSession: (cwd: string) => ResolvedSession
+let ensureSession: (cwd: string) => ResolvedSession
+let eventsPath: (id: string) => string
+let metaPath: (id: string) => string
+let sessionDir: (id: string) => string
+let sessionsRoot: () => string
+let IDLE_WINDOW_MS: number
+
+let work: string
+
+beforeAll(async () => {
+  const session = await import('../session')
+  const store = await import('../store')
+  resolveSession = session.resolveSession
+  ensureSession = session.ensureSession
+  eventsPath = store.eventsPath
+  metaPath = store.metaPath
+  sessionDir = store.sessionDir
+  sessionsRoot = store.sessionsRoot
+  IDLE_WINDOW_MS = store.IDLE_WINDOW_MS
+})
+
+beforeEach(() => {
+  if (!sessionsRoot().startsWith(tmpdir())) throw new Error('refusing to clean a non-tmp home')
+  rmSync(sessionsRoot(), { recursive: true, force: true })
+  delete process.env.ASTRALE_SESSION
+  work = mkdtempSync(join(tmpdir(), 'astrale-tele-work-'))
+})
+
+afterEach(() => {
+  rmSync(work, { recursive: true, force: true })
+})
+
+describe('resolveSession — ambient', () => {
+  test('reuses an open ambient session bucketed to the same root', () => {
+    // An old-stamp id proves reuse: a fresh mint would carry the current minute.
+    const existing = 'amb-deadbeef-200001010000'
+    seedAmbient(existing, work, 5 * 60_000)
+
+    const r = resolveSession(work)
+
+    expect(r).toEqual({ id: existing, root: work, explicit: false })
+  })
+
+  test('mints a fresh session once the previous one is idle', () => {
+    const existing = 'amb-deadbeef-200001010000'
+    seedAmbient(existing, work, IDLE_WINDOW_MS + 60_000)
+
+    const r = resolveSession(work)
+
+    expect(r.id).not.toBe(existing)
+    expect(r.explicit).toBe(false)
+    expect(r.id).toMatch(/^amb-[0-9a-f]{8}-\d{12}$/)
+  })
+
+  test('does not reuse a session bucketed to a different root', () => {
+    const existing = 'amb-deadbeef-200001010000'
+    seedAmbient(existing, work, 5 * 60_000)
+
+    const other = mkdtempSync(join(tmpdir(), 'astrale-tele-other-'))
+    try {
+      expect(resolveSession(other).id).not.toBe(existing)
+    } finally {
+      rmSync(other, { recursive: true, force: true })
+    }
+  })
+
+  test('ensureSession creates then reuses one session across calls', () => {
+    const first = ensureSession(work)
+    const second = ensureSession(work)
+    expect(second.id).toBe(first.id)
+    expect(first.id).toMatch(/^amb-[0-9a-f]{8}-\d{12}$/)
+  })
+})
+
+describe('resolveSession — root bucketing', () => {
+  test('buckets by the nearest .git ancestor, not cwd', () => {
+    mkdirSync(join(work, '.git'), { recursive: true })
+    const deep = join(work, 'sub', 'deep')
+    mkdirSync(deep, { recursive: true })
+
+    expect(resolveSession(deep).root).toBe(work)
+  })
+
+  test('falls back to cwd when there is no git root', () => {
+    expect(resolveSession(work).root).toBe(work)
+  })
+})
+
+describe('resolveSession — explicit ASTRALE_SESSION', () => {
+  test('honors an explicit id, sanitizing unsafe chars and capping at 64', () => {
+    process.env.ASTRALE_SESSION = 'my/weird:sess!!'
+    const r = resolveSession(work)
+    expect(r).toEqual({ id: 'myweirdsess', root: work, explicit: true })
+
+    process.env.ASTRALE_SESSION = 'a'.repeat(80)
+    expect(resolveSession(work).id).toBe('a'.repeat(64))
+  })
+
+  test('falls through to ambient when the id is empty after sanitizing', () => {
+    process.env.ASTRALE_SESSION = '///'
+    const r = resolveSession(work)
+    expect(r.explicit).toBe(false)
+    expect(r.id).toMatch(/^amb-/)
+  })
+})
+
+describe('ensureSession', () => {
+  test('creates the session dir and a readable meta.json once', () => {
+    const r = ensureSession(work)
+
+    expect(existsSync(metaPath(r.id))).toBe(true)
+    const meta = JSON.parse(readFileSync(metaPath(r.id), 'utf-8')) as SessionMeta
+    expect(meta.id).toBe(r.id)
+    expect(meta.root).toBe(work)
+    expect(meta.explicit).toBe(false)
+    expect(typeof meta.createdAt).toBe('string')
+  })
+})
+
+describe('analyzed sessions are never reused', () => {
+  test('an open ambient session with an .analyzed marker gets a fresh mint', async () => {
+    const { markerPath } = await import('../store')
+    const root = join(work, 'analyzed-root')
+    mkdirSync(root, { recursive: true })
+    seedAmbient('amb-analyzed-open', root, 0) // fresh mtime → open
+    writeFileSync(
+      markerPath('amb-analyzed-open'),
+      JSON.stringify({ analyzedAt: new Date().toISOString(), outcome: 'reported' }),
+    )
+    const resolved = resolveSession(root)
+    expect(resolved.id).not.toBe('amb-analyzed-open')
+    expect(resolved.id.startsWith('amb-')).toBe(true)
+  })
+})

package/src/telemetry/__tests__/trigger.test.ts

@@ -0,0 +1,49 @@
+import { beforeAll, describe, expect, test } from 'bun:test'
+import { existsSync, mkdirSync, mkdtempSync, rmSync, utimesSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+// Set the home before the paths singleton is captured (dynamic imports below).
+process.env.ASTRALE_HOME = mkdtempSync(join(tmpdir(), 'astrale-tele-trigger-'))
+
+let maybeTriggerAnalysis: (argv: string[]) => void
+let sessionDir: (id: string) => string
+
+beforeAll(async () => {
+  ;({ maybeTriggerAnalysis } = await import('../trigger'))
+  ;({ sessionDir } = await import('../store'))
+  // Sibling test files mutate shared state (env vars, and recorder.test.ts
+  // leaves a telemetry-disabled config.json in the shared home) — own it here.
+  delete process.env.ASTRALE_TELEMETRY
+  delete process.env.ASTRALE_TELEMETRY_NO_TRIGGER
+  const { CONFIG_PATH } = await import('../../lib/paths')
+  rmSync(CONFIG_PATH, { force: true })
+})
+
+function seed(id: string, ageMs: number, analyzed: boolean): void {
+  const dir = sessionDir(id)
+  mkdirSync(dir, { recursive: true })
+  writeFileSync(join(dir, 'meta.json'), JSON.stringify({ id, root: '/w', explicit: false }))
+  writeFileSync(join(dir, 'events.jsonl'), '{}\n')
+  if (analyzed) {
+    writeFileSync(
+      join(dir, '.analyzed'),
+      JSON.stringify({ analyzedAt: new Date().toISOString(), outcome: 'reported' }),
+    )
+  }
+  const when = new Date(Date.now() - ageMs)
+  utimesSync(join(dir, 'events.jsonl'), when, when)
+}
+
+describe('opportunistic GC', () => {
+  test('removes analyzed sessions past retention, keeps recent and unanalyzed ones', () => {
+    const DAY = 24 * 60 * 60 * 1000
+    seed('gc-old-analyzed', 40 * DAY, true)
+    seed('gc-recent-analyzed', 2 * DAY, true)
+    // NOTE: no closed-unanalyzed sessions seeded — the trigger must find no
+    // analysis target, so this test never spawns a child process.
+    maybeTriggerAnalysis(['bun', 'astrale', 'status'])
+    expect(existsSync(sessionDir('gc-old-analyzed'))).toBe(false)
+    expect(existsSync(sessionDir('gc-recent-analyzed'))).toBe(true)
+  })
+})

package/src/telemetry/adapters/__tests__/claude-code.test.ts

@@ -0,0 +1,89 @@
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test'
+import { mkdirSync, mkdtempSync, rmSync, utimesSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+import { claudeCodeAdapter } from '../claude-code'
+
+const ROOT = '/tmp/fake/proj'
+const MUNGED = '-tmp-fake-proj'
+
+let base: string
+
+function project(dir: string, file: string, mtime: Date): string {
+  const projPath = join(base, 'projects', dir)
+  mkdirSync(projPath, { recursive: true })
+  const p = join(projPath, file)
+  writeFileSync(p, '{"type":"user"}\n')
+  utimesSync(p, mtime, mtime)
+  return p
+}
+
+beforeEach(() => {
+  base = mkdtempSync(join(tmpdir(), 'cc-adapter-'))
+})
+afterEach(() => {
+  rmSync(base, { recursive: true, force: true })
+})
+
+describe('claudeCodeAdapter', () => {
+  test('detect is false without a projects dir, true with one', () => {
+    expect(claudeCodeAdapter(base).detect()).toBe(false)
+    mkdirSync(join(base, 'projects'), { recursive: true })
+    expect(claudeCodeAdapter(base).detect()).toBe(true)
+  })
+
+  test('matches the exact munged dir and subdir-prefixed dirs, excludes unrelated', async () => {
+    const now = new Date()
+    const wide = {
+      start: new Date(now.getTime() - 2 * 3600_000),
+      end: new Date(now.getTime() + 2 * 3600_000),
+    }
+    project(MUNGED, 'exact.jsonl', now)
+    project(`${MUNGED}-sub-deeper`, 'child.jsonl', now)
+    project('-other-unrelated-path', 'nope.jsonl', now)
+
+    const sessions = await claudeCodeAdapter(base).discover(ROOT, wide)
+    const ids = sessions.map((s) => s.sessionId).sort()
+    expect(ids).toEqual(['child', 'exact'])
+    for (const s of sessions) {
+      expect(s.harness).toBe('claude-code')
+      expect(s.sizeBytes).toBeGreaterThan(0)
+      expect(typeof s.endedAt).toBe('string')
+      expect(typeof s.startedAt).toBe('string')
+    }
+  })
+
+  test('window filtering: excludes a transcript whose span sits entirely after the window', async () => {
+    const t = Date.now()
+    const window = { start: new Date(t - 2 * 3600_000), end: new Date(t - 3600_000) }
+    project(MUNGED, 'inside.jsonl', new Date(t - 90 * 60_000))
+    project(MUNGED, 'after.jsonl', new Date(t - 30 * 60_000))
+
+    const ids = (await claudeCodeAdapter(base).discover(ROOT, window)).map((s) => s.sessionId)
+    expect(ids).toContain('inside')
+    expect(ids).not.toContain('after')
+  })
+
+  test('only *.jsonl files are considered', async () => {
+    const now = new Date()
+    const wide = {
+      start: new Date(now.getTime() - 3600_000),
+      end: new Date(now.getTime() + 3600_000),
+    }
+    project(MUNGED, 'keep.jsonl', now)
+    project(MUNGED, 'ignore.txt', now)
+
+    const ids = (await claudeCodeAdapter(base).discover(ROOT, wide)).map((s) => s.sessionId)
+    expect(ids).toEqual(['keep'])
+  })
+
+  test('never throws and returns [] when the projects dir is missing', async () => {
+    const now = new Date()
+    const sessions = await claudeCodeAdapter(join(base, 'does-not-exist')).discover(ROOT, {
+      start: new Date(now.getTime() - 3600_000),
+      end: now,
+    })
+    expect(sessions).toEqual([])
+  })
+})

package/src/telemetry/adapters/__tests__/codex.test.ts

@@ -0,0 +1,138 @@
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test'
+import { mkdirSync, mkdtempSync, rmSync, utimesSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+import { codexAdapter } from '../codex'
+
+const ROOT = '/work/proj'
+const WINDOW = {
+  start: new Date('2026-07-10T00:00:00.000Z'),
+  end: new Date('2026-07-10T23:59:59.000Z'),
+}
+const IN_DAY = ['2026', '07', '10']
+
+let base: string
+
+function meta(cwd: string, timestamp = '2026-07-10T10:00:00.000Z'): string {
+  return JSON.stringify({
+    type: 'session_meta',
+    payload: { session_id: `sid-${cwd}`, timestamp, cwd, cli_version: '1.2.3' },
+  })
+}
+
+function rollout(
+  day: string[],
+  name: string,
+  firstLine: string,
+  mtime = new Date('2026-07-10T10:05:00.000Z'),
+): string {
+  const dir = join(base, 'sessions', ...day)
+  mkdirSync(dir, { recursive: true })
+  const p = join(dir, `rollout-${name}.jsonl`)
+  writeFileSync(p, `${firstLine}\n{"type":"response_item"}\n{"type":"event_msg"}\n`)
+  utimesSync(p, mtime, mtime)
+  return p
+}
+
+beforeEach(() => {
+  base = mkdtempSync(join(tmpdir(), 'codex-adapter-'))
+})
+afterEach(() => {
+  rmSync(base, { recursive: true, force: true })
+})
+
+describe('codexAdapter', () => {
+  test('detect follows the sessions dir', () => {
+    expect(codexAdapter(base).detect()).toBe(false)
+    mkdirSync(join(base, 'sessions'), { recursive: true })
+    expect(codexAdapter(base).detect()).toBe(true)
+  })
+
+  test('cwd filtering: exact root and subdir included, unrelated excluded', async () => {
+    rollout(IN_DAY, 'exact', meta(ROOT))
+    rollout(IN_DAY, 'sub', meta(`${ROOT}/packages/app`))
+    rollout(IN_DAY, 'sibling', meta('/work/project-x'))
+    rollout(IN_DAY, 'elsewhere', meta('/somewhere/else'))
+
+    const sessions = await codexAdapter(base).discover(ROOT, WINDOW)
+    const cwds = sessions.map((s) => s.cwd).sort()
+    expect(cwds).toEqual([ROOT, `${ROOT}/packages/app`])
+    for (const s of sessions) {
+      expect(s.harness).toBe('codex')
+      expect(s.sessionId).toBe(`sid-${s.cwd}`)
+      expect(s.startedAt).toBe('2026-07-10T10:00:00.000Z')
+      expect(typeof s.endedAt).toBe('string')
+      expect(s.sizeBytes).toBeGreaterThan(0)
+    }
+  })
+
+  test('window filtering: rollout with mtime before the window is excluded', async () => {
+    rollout(IN_DAY, 'in', meta(ROOT))
+    rollout(
+      IN_DAY,
+      'stale',
+      meta(ROOT, '2026-07-08T10:00:00.000Z'),
+      new Date('2026-07-08T10:00:00.000Z'),
+    )
+
+    const ids = (await codexAdapter(base).discover(ROOT, WINDOW)).map((s) => s.sessionId)
+    // both share the same synthetic session_id; assert exactly one survived
+    expect(ids.length).toBe(1)
+  })
+
+  test('date-shard pruning skips days outside the window', async () => {
+    rollout(['2026', '01', '01'], 'jan', meta(ROOT), new Date('2026-01-01T10:00:00.000Z'))
+    const ids = await codexAdapter(base).discover(ROOT, WINDOW)
+    expect(ids).toEqual([])
+  })
+
+  test('a corrupt first line is skipped without throwing', async () => {
+    rollout(IN_DAY, 'good', meta(ROOT))
+    rollout(IN_DAY, 'corrupt', '{ this is not json ]]]')
+
+    const sessions = await codexAdapter(base).discover(ROOT, WINDOW)
+    expect(sessions.length).toBe(1)
+    expect(sessions[0]?.cwd).toBe(ROOT)
+  })
+
+  test('never throws and returns [] when the sessions dir is missing', async () => {
+    expect(await codexAdapter(join(base, 'absent')).discover(ROOT, WINDOW)).toEqual([])
+  })
+})
+
+describe('codexAdapter large session_meta', () => {
+  test('first line larger than one read chunk still parses (real rollouts embed base_instructions)', async () => {
+    // Padding before cwd pushes it past the first 64 KB chunk boundary.
+    const huge = JSON.stringify({
+      type: 'session_meta',
+      payload: {
+        base_instructions: { text: 'x'.repeat(80 * 1024) },
+        session_id: 'sid-huge',
+        timestamp: '2026-07-10T10:00:00.000Z',
+        cwd: ROOT,
+        cli_version: '1.2.3',
+      },
+    })
+    rollout(IN_DAY, 'huge', huge)
+    const sessions = await codexAdapter(base).discover(ROOT, WINDOW)
+    expect(sessions.map((s) => s.sessionId)).toEqual(['sid-huge'])
+  })
+})
+
+describe('codexAdapter timezone shard boundary', () => {
+  test('rollout in the next local-date shard still matches a window ending today (UTC+ offsets)', async () => {
+    const w = {
+      start: new Date('2026-07-10T20:00:00.000Z'),
+      end: new Date('2026-07-10T23:00:00.000Z'),
+    }
+    rollout(
+      ['2026', '07', '11'],
+      'tzedge',
+      meta(ROOT, '2026-07-10T22:25:00.000Z'),
+      new Date('2026-07-10T22:30:00.000Z'),
+    )
+    const sessions = await codexAdapter(base).discover(ROOT, w)
+    expect(sessions.map((s) => s.transcriptPath.includes('tzedge'))).toEqual([true])
+  })
+})

package/src/telemetry/adapters/__tests__/index.test.ts

@@ -0,0 +1,88 @@
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test'
+import { mkdirSync, mkdtempSync, rmSync, utimesSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+import { claudeCodeAdapter } from '../claude-code'
+import { codexAdapter } from '../codex'
+import { defaultAdapters, discoverAll } from '../index'
+
+const ROOT = '/work/proj'
+const WINDOW = {
+  start: new Date('2026-07-01T00:00:00.000Z'),
+  end: new Date(Date.now() + 86_400_000),
+}
+
+let ccBase: string
+let cxBase: string
+
+function seedClaude(mtime: Date): void {
+  const dir = join(ccBase, 'projects', '-work-proj')
+  mkdirSync(dir, { recursive: true })
+  const p = join(dir, 'cc-session.jsonl')
+  writeFileSync(p, '{"type":"user"}\n')
+  utimesSync(p, mtime, mtime)
+}
+
+function seedCodex(mtime: Date): void {
+  const dir = join(cxBase, 'sessions', '2026', '07', '10')
+  mkdirSync(dir, { recursive: true })
+  const p = join(dir, 'rollout-x.jsonl')
+  const line = JSON.stringify({
+    type: 'session_meta',
+    payload: { session_id: 'cx-session', timestamp: '2026-07-10T10:00:00.000Z', cwd: ROOT },
+  })
+  writeFileSync(p, `${line}\n`)
+  utimesSync(p, mtime, mtime)
+}
+
+beforeEach(() => {
+  ccBase = mkdtempSync(join(tmpdir(), 'cc-base-'))
+  cxBase = mkdtempSync(join(tmpdir(), 'cx-base-'))
+})
+afterEach(() => {
+  rmSync(ccBase, { recursive: true, force: true })
+  rmSync(cxBase, { recursive: true, force: true })
+})
+
+describe('discoverAll', () => {
+  test('defaultAdapters exposes both harnesses', () => {
+    expect(
+      defaultAdapters()
+        .map((a) => a.name)
+        .sort(),
+    ).toEqual(['claude-code', 'codex'])
+  })
+
+  test('merges detected adapters and sorts by endedAt descending', async () => {
+    seedClaude(new Date('2026-07-10T09:00:00.000Z'))
+    seedCodex(new Date('2026-07-10T11:00:00.000Z'))
+
+    const sessions = await discoverAll(
+      [claudeCodeAdapter(ccBase), codexAdapter(cxBase)],
+      ROOT,
+      WINDOW,
+    )
+    expect(sessions.map((s) => s.harness)).toEqual(['codex', 'claude-code'])
+  })
+
+  test('never throws when a base dir is missing; returns only the detected harness', async () => {
+    seedClaude(new Date('2026-07-10T09:00:00.000Z'))
+
+    const sessions = await discoverAll(
+      [claudeCodeAdapter(ccBase), codexAdapter(join(cxBase, 'absent'))],
+      ROOT,
+      WINDOW,
+    )
+    expect(sessions.map((s) => s.harness)).toEqual(['claude-code'])
+  })
+
+  test('returns [] when nothing is detected', async () => {
+    const sessions = await discoverAll(
+      [claudeCodeAdapter(join(ccBase, 'absent')), codexAdapter(join(cxBase, 'absent'))],
+      ROOT,
+      WINDOW,
+    )
+    expect(sessions).toEqual([])
+  })
+})

package/src/telemetry/adapters/claude-code.ts

@@ -0,0 +1,90 @@
+/**
+ * Claude Code adapter: transcripts live at
+ * `<base>/projects/<munged-cwd>/<session-uuid>.jsonl`, where the project dir is
+ * the absolute cwd with every non-alphanumeric char replaced by '-'. Discovery
+ * is stat/readdir only — it never opens a transcript.
+ */
+import { existsSync, readdirSync, statSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+
+import type { HarnessSession } from '../types'
+import type { HarnessAdapter, TimeWindow } from './types'
+
+/** cwd → project dir name: every non-alphanumeric char becomes '-'. */
+function mungeCwd(cwd: string): string {
+  return cwd.replace(/[^a-zA-Z0-9]/g, '-')
+}
+
+const READING_GUIDE =
+  'This is a Claude Code transcript: one JSON object per line (JSONL). Each entry has a `type` ' +
+  '(user, assistant, system, file-history-snapshot, …). Assistant entries carry the model’s ' +
+  'verbatim `thinking` blocks plus `tool_use` blocks with full tool inputs; tool results come back as ' +
+  'user-type entries. Files are large and append-only, so grep for tool names, error strings, or file ' +
+  'paths and sample the surrounding lines rather than reading the whole transcript. The last line ' +
+  'reflects where the session ended.'
+
+export function claudeCodeAdapter(base: string = join(homedir(), '.claude')): HarnessAdapter {
+  const projectsDir = join(base, 'projects')
+
+  function detect(): boolean {
+    try {
+      return existsSync(projectsDir)
+    } catch {
+      return false
+    }
+  }
+
+  function discover(root: string, window: TimeWindow): Promise<HarnessSession[]> {
+    const sessions: HarnessSession[] = []
+    try {
+      const munged = mungeCwd(root)
+      const prefix = `${munged}-`
+      let dirs: string[]
+      try {
+        dirs = readdirSync(projectsDir)
+      } catch {
+        return Promise.resolve([])
+      }
+      const startMs = window.start.getTime()
+      const endMs = window.end.getTime()
+      for (const dir of dirs) {
+        if (dir !== munged && !dir.startsWith(prefix)) continue
+        const projectPath = join(projectsDir, dir)
+        let files: string[]
+        try {
+          files = readdirSync(projectPath)
+        } catch {
+          continue
+        }
+        for (const file of files) {
+          if (!file.endsWith('.jsonl')) continue
+          const transcriptPath = join(projectPath, file)
+          try {
+            const st = statSync(transcriptPath)
+            const mtimeMs = st.mtime.getTime()
+            const birthMs = st.birthtime.getTime()
+            const spanStart = Math.min(birthMs, mtimeMs)
+            const spanEnd = Math.max(birthMs, mtimeMs)
+            if (spanStart > endMs || spanEnd < startMs) continue
+            sessions.push({
+              harness: 'claude-code',
+              sessionId: file.slice(0, -'.jsonl'.length),
+              transcriptPath,
+              sizeBytes: st.size,
+              startedAt: st.birthtime.toISOString(),
+              endedAt: st.mtime.toISOString(),
+            })
+          } catch {
+            /* unreadable transcript — skip it, never fail discovery */
+          }
+        }
+      }
+    } catch {
+      return Promise.resolve([])
+    }
+    return Promise.resolve(sessions)
+  }
+
+  return { name: 'claude-code', detect, discover, readingGuide: READING_GUIDE }
+}