@astrale-os/cli 0.4.0-alpha.13 → 0.6.0-alpha.0

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 }
+}

package/src/telemetry/adapters/codex.ts

@@ -0,0 +1,160 @@
+/**
+ * Codex adapter: rollouts live at
+ * `<base>/sessions/YYYY/MM/DD/rollout-<ts>-<uuid>.jsonl`, date-sharded. Line 1 is
+ * a `session_meta` object carrying cwd + session_id + timestamp. Discovery reads
+ * only that first line — never the transcript body — and prunes by date shard.
+ */
+import { existsSync, openSync, readdirSync, readSync, statSync } from 'node:fs'
+import { closeSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+
+import type { HarnessSession } from '../types'
+import type { HarnessAdapter, TimeWindow } from './types'
+
+const DAY_MS = 24 * 60 * 60 * 1000
+const HEAD_CHUNK = 64 * 1024
+// session_meta embeds the harness's full base_instructions — real first lines
+// run tens of KB, so read in chunks until the newline (cap = malformed guard).
+const MAX_HEAD_BYTES = 512 * 1024
+
+const READING_GUIDE =
+  'This is a Codex rollout: one JSON object per line (JSONL). Line 1 is `session_meta` (session_id, ' +
+  'timestamp, cwd, cli_version). Later lines are either `response_item` — payload.type of message, ' +
+  'function_call, function_call_output, or reasoning (reasoning is a short summary, not verbatim chain ' +
+  'of thought) — or `event_msg` carrying task_started, task_complete, token_count, agent_message, and ' +
+  'user_message. Files can be large, so grep for function_call names, outputs, or error strings and ' +
+  'sample around them rather than reading the whole rollout.'
+
+/** Read the first line of a file without loading the body. */
+function readFirstLine(path: string): string | null {
+  let fd: number | null = null
+  try {
+    fd = openSync(path, 'r')
+    const chunks: Buffer[] = []
+    let pos = 0
+    while (pos < MAX_HEAD_BYTES) {
+      const buf = Buffer.alloc(HEAD_CHUNK)
+      const bytes = readSync(fd, buf, 0, HEAD_CHUNK, pos)
+      if (bytes === 0) break
+      chunks.push(buf.subarray(0, bytes))
+      pos += bytes
+      // Newline is ASCII, so a byte search is safe; decode only after concat
+      // so a multibyte char split across chunks can't corrupt the text.
+      if (buf.subarray(0, bytes).includes(0x0a)) break
+    }
+    const text = Buffer.concat(chunks).toString('utf-8')
+    const nl = text.indexOf('\n')
+    if (nl !== -1) return text.slice(0, nl)
+    return pos >= MAX_HEAD_BYTES ? null : text || null
+  } catch {
+    return null
+  } finally {
+    if (fd !== null) {
+      try {
+        closeSync(fd)
+      } catch {
+        /* ignore */
+      }
+    }
+  }
+}
+
+/** Numeric names only (YYYY / MM / DD shards), sorted for determinism. */
+function numericDirs(path: string): string[] {
+  try {
+    return readdirSync(path)
+      .filter((n) => /^\d+$/.test(n))
+      .sort()
+  } catch {
+    return []
+  }
+}
+
+export function codexAdapter(base: string = join(homedir(), '.codex')): HarnessAdapter {
+  const sessionsDir = join(base, 'sessions')
+
+  function detect(): boolean {
+    try {
+      return existsSync(sessionsDir)
+    } catch {
+      return false
+    }
+  }
+
+  function discover(root: string, window: TimeWindow): Promise<HarnessSession[]> {
+    const sessions: HarnessSession[] = []
+    try {
+      const startMs = window.start.getTime()
+      const endMs = window.end.getTime()
+      const lowerMs = startMs - DAY_MS
+      for (const yyyy of numericDirs(sessionsDir)) {
+        for (const mm of numericDirs(join(sessionsDir, yyyy))) {
+          for (const dd of numericDirs(join(sessionsDir, yyyy, mm))) {
+            // Shard names are LOCAL dates but dayStart is computed as UTC —
+            // pad both bounds a day so no timezone offset can skip a shard.
+            const dayStart = Date.UTC(Number(yyyy), Number(mm) - 1, Number(dd))
+            if (dayStart > endMs + DAY_MS || dayStart + DAY_MS <= lowerMs) continue
+            scanDay(join(sessionsDir, yyyy, mm, dd), root, startMs, endMs, sessions)
+          }
+        }
+      }
+    } catch {
+      return Promise.resolve([])
+    }
+    return Promise.resolve(sessions)
+  }
+
+  return { name: 'codex', detect, discover, readingGuide: READING_GUIDE }
+}
+
+function scanDay(
+  dayPath: string,
+  root: string,
+  startMs: number,
+  endMs: number,
+  out: HarnessSession[],
+): void {
+  let files: string[]
+  try {
+    files = readdirSync(dayPath)
+  } catch {
+    return
+  }
+  const rootPrefix = `${root}/`
+  for (const file of files) {
+    if (!file.startsWith('rollout-') || !file.endsWith('.jsonl')) continue
+    const transcriptPath = join(dayPath, file)
+    try {
+      const st = statSync(transcriptPath)
+      const mtimeMs = st.mtime.getTime()
+      if (mtimeMs < startMs) continue
+      const line = readFirstLine(transcriptPath)
+      if (line === null) continue
+      let meta: unknown
+      try {
+        meta = JSON.parse(line)
+      } catch {
+        continue
+      }
+      const payload = (meta as { payload?: Record<string, unknown> })?.payload
+      if (!payload || typeof payload.cwd !== 'string') continue
+      const cwd = payload.cwd
+      if (cwd !== root && !cwd.startsWith(rootPrefix)) continue
+      const startedAt = typeof payload.timestamp === 'string' ? payload.timestamp : undefined
+      const startedMs = startedAt ? Date.parse(startedAt) : Number.NaN
+      if (!Number.isNaN(startedMs) && startedMs > endMs) continue
+      out.push({
+        harness: 'codex',
+        sessionId: typeof payload.session_id === 'string' ? payload.session_id : undefined,
+        transcriptPath,
+        cwd,
+        startedAt,
+        endedAt: st.mtime.toISOString(),
+        sizeBytes: st.size,
+      })
+    } catch {
+      /* unreadable rollout — skip it, never fail discovery */
+    }
+  }
+}

package/src/telemetry/adapters/index.ts

@@ -0,0 +1,45 @@
+/**
+ * Harness adapter registry: the set of transcript sources probed for a session,
+ * plus a fan-out that runs every detected adapter's discovery and merges the
+ * results newest-first. Nothing here throws — a broken adapter degrades to [].
+ */
+import type { HarnessSession } from '../types'
+import type { HarnessAdapter, TimeWindow } from './types'
+
+import { claudeCodeAdapter } from './claude-code'
+import { codexAdapter } from './codex'
+
+export type { HarnessAdapter, TimeWindow } from './types'
+export { claudeCodeAdapter } from './claude-code'
+export { codexAdapter } from './codex'
+
+/** All built-in adapters at their default home-directory bases. */
+export function defaultAdapters(): HarnessAdapter[] {
+  return [claudeCodeAdapter(), codexAdapter()]
+}
+
+function endedMs(s: HarnessSession): number {
+  const t = s.endedAt ? Date.parse(s.endedAt) : Number.NaN
+  return Number.isNaN(t) ? 0 : t
+}
+
+/** Detected adapters' discover() in parallel, flattened, newest endedAt first. */
+export async function discoverAll(
+  adapters: HarnessAdapter[],
+  root: string,
+  window: TimeWindow,
+): Promise<HarnessSession[]> {
+  const active = adapters.filter((a) => {
+    try {
+      return a.detect()
+    } catch {
+      return false
+    }
+  })
+  const settled = await Promise.allSettled(active.map((a) => a.discover(root, window)))
+  const sessions: HarnessSession[] = []
+  for (const r of settled) {
+    if (r.status === 'fulfilled') sessions.push(...r.value)
+  }
+  return sessions.sort((a, b) => endedMs(b) - endedMs(a))
+}

package/src/telemetry/adapters/types.ts

@@ -0,0 +1,21 @@
+/**
+ * Harness adapters: discovery + a reading guide, deliberately NOT normalizers.
+ * The analyzer is an agent that reads native transcript formats; each adapter
+ * only says where sessions live and how to read that format.
+ */
+import type { HarnessSession } from '../types'
+
+export type TimeWindow = { start: Date; end: Date }
+
+export interface HarnessAdapter {
+  name: string
+  /** Cheap machine-level presence check (a directory stat, never network). */
+  detect(): boolean
+  /**
+   * Sessions of this harness whose cwd sits at/under `root` and whose activity
+   * overlaps `window`. Must never throw — errors degrade to [].
+   */
+  discover(root: string, window: TimeWindow): Promise<HarnessSession[]>
+  /** Prompt fragment: how the analyzer should read this transcript format. */
+  readingGuide: string
+}