@astrale-os/cli 1.0.0-beta.27 → 1.0.0-beta.29

package/src/state/session-routes.ts

@@ -0,0 +1,34 @@
+import type { SessionRouteArtifact, SessionRouteStore } from '@astrale-os/sdk/client/session'
+
+import { chmodSync, mkdirSync, readFileSync, unlinkSync } from 'node:fs'
+import { dirname } from 'node:path'
+
+import { atomicWriteSync } from './files'
+import { SESSION_ROUTES_PATH } from './paths'
+
+/** CLI filesystem representation for Kernel Client's admitted confidential route artifact. */
+export class FileSessionRouteStore implements SessionRouteStore {
+  constructor(private readonly path = SESSION_ROUTES_PATH) {}
+
+  read(): unknown {
+    return JSON.parse(readFileSync(this.path, 'utf8')) as unknown
+  }
+
+  write(artifact: SessionRouteArtifact): void {
+    const directory = dirname(this.path)
+    mkdirSync(directory, { recursive: true, mode: 0o700 })
+    chmodSync(directory, 0o700)
+    atomicWriteSync(this.path, `${JSON.stringify(artifact)}\n`)
+    chmodSync(this.path, 0o600)
+  }
+
+  clear(): void {
+    try {
+      unlinkSync(this.path)
+    } catch (error) {
+      if ((error as { readonly code?: unknown }).code !== 'ENOENT') throw error
+    }
+  }
+}
+
+export const SESSION_ROUTE_STORE = Object.freeze(new FileSessionRouteStore())

package/src/telemetry/__tests__/analyze-log.test.ts

@@ -0,0 +1,38 @@
+import { describe, expect, test } from 'bun:test'
+
+import { clampLog } from '../analyze'
+
+describe('clampLog', () => {
+  test('short output is written through untouched', () => {
+    const json = '{"is_error":false,"num_turns":3}'
+    expect(clampLog(json)).toBe(json)
+  })
+
+  test('output at exactly the limit is not clamped', () => {
+    const text = 'x'.repeat(1000)
+    expect(clampLog(text, 1000)).toBe(text)
+  })
+
+  test('oversized output keeps its head and its tail', () => {
+    // The JSON envelope opens at the top; a stack or error message closes at
+    // the bottom. Both must survive; the middle is what nobody reads.
+    const text = `HEAD${'x'.repeat(50_000)}TAIL`
+    const clamped = clampLog(text, 1000)
+    expect(clamped.startsWith('HEAD')).toBe(true)
+    expect(clamped.endsWith('TAIL')).toBe(true)
+    expect(clamped).toContain('bytes elided')
+  })
+
+  test('the result stays within a small constant of the limit', () => {
+    const clamped = clampLog('y'.repeat(10_000_000), 4096)
+    // head + tail + the elision marker, never the input.
+    expect(clamped.length).toBeLessThan(4096 + 128)
+  })
+
+  test('the elision count reports what was actually dropped', () => {
+    const clamped = clampLog('z'.repeat(10_000), 1000)
+    const elided = Number(/… (\d+) bytes elided …/u.exec(clamped)?.[1])
+    const kept = clamped.length - `\n… ${elided} bytes elided …\n`.length
+    expect(elided + kept).toBe(10_000)
+  })
+})

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

@@ -0,0 +1,267 @@
+import { afterEach, beforeAll, beforeEach, 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'
+
+import type { SweepOptions, SweepResult } from '../retention'
+import type { RetentionBudget } from '../settings'
+import type { SessionScan } from '../store'
+
+// Set the home before the paths singleton is captured (dynamic imports below).
+process.env.ASTRALE_HOME = mkdtempSync(join(tmpdir(), 'astrale-tele-retention-'))
+
+let sweepByAge: (sessions: readonly SessionScan[], options?: SweepOptions) => SweepResult
+let sweepToBudget: (sessions: readonly SessionScan[], options?: SweepOptions) => SweepResult
+let sweepStore: (options?: SweepOptions) => SweepResult
+let tidySession: (id: string, options?: { keepPrompt?: boolean }) => string[]
+let scanSessions: () => SessionScan[]
+let sessionDir: (id: string) => string
+let sessionBytes: (id: string) => number
+let sessionsRoot: () => string
+
+const DAY = 24 * 60 * 60 * 1000
+const BUDGET: RetentionBudget = { maxAgeMs: 30 * DAY, maxBytes: 10_000 }
+
+beforeAll(async () => {
+  ;({ sweepByAge, sweepToBudget, sweepStore, tidySession } = await import('../retention'))
+  ;({ scanSessions, sessionDir, sessionBytes, sessionsRoot } = await import('../store'))
+})
+
+beforeEach(() => {
+  // Destructive cleanup must be provably confined to this file's mkdtemp home.
+  if (!sessionsRoot().startsWith(tmpdir())) throw new Error('refusing to clean a non-tmp home')
+  rmSync(sessionsRoot(), { recursive: true, force: true })
+  delete process.env.ASTRALE_TELEMETRY_MAX_AGE_DAYS
+  delete process.env.ASTRALE_TELEMETRY_MAX_BYTES
+})
+
+afterEach(() => {
+  rmSync(sessionsRoot(), { recursive: true, force: true })
+})
+
+type Seed = { ageMs?: number; analyzed?: boolean; bytes?: number; events?: boolean }
+
+function seed(id: string, { ageMs = 0, analyzed = false, bytes = 0, events = true }: Seed): void {
+  const dir = sessionDir(id)
+  mkdirSync(dir, { recursive: true })
+  writeFileSync(join(dir, 'meta.json'), JSON.stringify({ id, root: '/w', explicit: false }))
+  if (bytes > 0) writeFileSync(join(dir, 'report.md'), 'x'.repeat(bytes))
+  if (analyzed) {
+    writeFileSync(
+      join(dir, '.analyzed'),
+      JSON.stringify({ analyzedAt: new Date().toISOString(), outcome: 'reported' }),
+    )
+  }
+  if (!events) return
+  writeFileSync(join(dir, 'events.jsonl'), '{}\n')
+  const when = new Date(Date.now() - ageMs)
+  utimesSync(join(dir, 'events.jsonl'), when, when)
+}
+
+const alive = (id: string): boolean => existsSync(sessionDir(id))
+
+describe('sweepByAge', () => {
+  test('drops sessions past the age bound whether or not they were analyzed', () => {
+    seed('old-analyzed', { ageMs: 40 * DAY, analyzed: true })
+    seed('old-unanalyzed', { ageMs: 40 * DAY })
+    seed('recent-analyzed', { ageMs: 2 * DAY, analyzed: true })
+    seed('recent-unanalyzed', { ageMs: 2 * DAY })
+
+    const { removed } = sweepByAge(scanSessions(), { budget: BUDGET })
+
+    expect(removed.sort()).toEqual(['old-analyzed', 'old-unanalyzed'])
+    expect(alive('recent-analyzed')).toBe(true)
+    expect(alive('recent-unanalyzed')).toBe(true)
+  })
+
+  test('never touches a session with no events — that is the invocation running now', () => {
+    seed('no-events-yet', { events: false })
+    expect(sweepByAge(scanSessions(), { budget: BUDGET }).removed).toEqual([])
+    expect(alive('no-events-yet')).toBe(true)
+  })
+
+  test('honours the removal cap so a backlog drains over several runs', () => {
+    for (let i = 0; i < 5; i++) seed(`stale-${i}`, { ageMs: 40 * DAY, analyzed: true })
+    expect(sweepByAge(scanSessions(), { budget: BUDGET, limit: 2 }).removed).toHaveLength(2)
+    expect(scanSessions()).toHaveLength(3)
+  })
+
+  test('respects the configured age bound', () => {
+    seed('week-old', { ageMs: 8 * DAY, analyzed: true })
+    const strict: RetentionBudget = { ...BUDGET, maxAgeMs: 7 * DAY }
+    expect(sweepByAge(scanSessions(), { budget: strict }).removed).toEqual(['week-old'])
+  })
+
+  test('protected ids survive the age bound', () => {
+    seed('old-but-mine', { ageMs: 40 * DAY, analyzed: true })
+    const options = { budget: BUDGET, protect: new Set(['old-but-mine']) }
+    expect(sweepByAge(scanSessions(), options).removed).toEqual([])
+    expect(alive('old-but-mine')).toBe(true)
+  })
+})
+
+describe('sweepToBudget', () => {
+  test('does nothing while the store fits', () => {
+    seed('small', { ageMs: DAY, analyzed: true, bytes: 100 })
+    expect(sweepToBudget(scanSessions(), { budget: BUDGET }).removed).toEqual([])
+    expect(alive('small')).toBe(true)
+  })
+
+  test('evicts oldest-first until the store is back under budget', () => {
+    seed('oldest', { ageMs: 5 * DAY, analyzed: true, bytes: 4_000 })
+    seed('middle', { ageMs: 3 * DAY, analyzed: true, bytes: 4_000 })
+    seed('newest', { ageMs: DAY, analyzed: true, bytes: 4_000 })
+
+    // 3 × ~4 KB against a 5 KB bound: two must go, and the newest must stay.
+    const { removed } = sweepToBudget(scanSessions(), { budget: { ...BUDGET, maxBytes: 5_000 } })
+
+    expect(removed).toEqual(['oldest', 'middle'])
+    expect(alive('newest')).toBe(true)
+  })
+
+  test('evicts analyzed sessions before unanalyzed ones of any age', () => {
+    seed('unanalyzed-oldest', { ageMs: 9 * DAY, bytes: 6_000 })
+    seed('analyzed-newest', { ageMs: DAY, analyzed: true, bytes: 6_000 })
+
+    expect(sweepToBudget(scanSessions(), { budget: BUDGET }).removed).toEqual(['analyzed-newest'])
+    expect(alive('unanalyzed-oldest')).toBe(true)
+  })
+
+  test('falls through to unanalyzed sessions when analyzed ones are not enough', () => {
+    seed('unanalyzed-old', { ageMs: 9 * DAY, bytes: 6_000 })
+    seed('analyzed-old', { ageMs: 8 * DAY, analyzed: true, bytes: 6_000 })
+    seed('unanalyzed-new', { ageMs: DAY, bytes: 6_000 })
+
+    const { removed } = sweepToBudget(scanSessions(), { budget: BUDGET })
+
+    expect(removed).toEqual(['analyzed-old', 'unanalyzed-old'])
+    expect(alive('unanalyzed-new')).toBe(true)
+  })
+
+  test('never evicts an open session, even when that leaves the store over budget', () => {
+    // No age offset → inside IDLE_WINDOW_MS → open.
+    seed('open-and-huge', { analyzed: true, bytes: 20_000 })
+    expect(sweepToBudget(scanSessions(), { budget: BUDGET }).removed).toEqual([])
+    expect(alive('open-and-huge')).toBe(true)
+  })
+
+  test('never evicts a protected session', () => {
+    seed('just-analyzed', { ageMs: DAY, analyzed: true, bytes: 20_000 })
+    const options = { budget: BUDGET, protect: new Set(['just-analyzed']) }
+    expect(sweepToBudget(scanSessions(), options).removed).toEqual([])
+  })
+
+  test('counts nested analyzer output — a session is bounded by all it holds', () => {
+    seed('nested', { ageMs: DAY, analyzed: true, bytes: 100 })
+    mkdirSync(join(sessionDir('nested'), 'scratch'), { recursive: true })
+    writeFileSync(join(sessionDir('nested'), 'scratch', 'dump.txt'), 'x'.repeat(5_000))
+
+    expect(sessionBytes('nested')).toBeGreaterThan(5_000)
+  })
+})
+
+describe('sweepStore', () => {
+  test('applies age first, then trims what survives to the size bound', () => {
+    seed('expired', { ageMs: 40 * DAY, analyzed: true, bytes: 6_000 })
+    seed('fresh-big', { ageMs: 2 * DAY, analyzed: true, bytes: 6_000 })
+    seed('fresh-small', { ageMs: DAY, analyzed: true, bytes: 100 })
+
+    // Age alone frees 6 KB, leaving ~6.1 KB — already under the 10 KB bound,
+    // so the size pass must find nothing left to do.
+    expect(sweepStore({ budget: BUDGET }).removed).toEqual(['expired'])
+    expect(alive('fresh-big')).toBe(true)
+    expect(alive('fresh-small')).toBe(true)
+  })
+
+  test('reads its budget from the environment when none is passed', () => {
+    process.env.ASTRALE_TELEMETRY_MAX_AGE_DAYS = '1'
+    seed('two-days-old', { ageMs: 2 * DAY, analyzed: true })
+    expect(sweepStore().removed).toEqual(['two-days-old'])
+  })
+})
+
+describe('sweepStore tidying', () => {
+  test('tidies analyzed survivors, so the bound applies to sessions already on disk', () => {
+    seed('store-tidy', { ageMs: DAY, analyzed: true, bytes: 100 })
+    writeFileSync(join(sessionDir('store-tidy'), 'calls.txt'), 'x'.repeat(50_000))
+
+    sweepStore({ budget: BUDGET })
+
+    expect(existsSync(join(sessionDir('store-tidy'), 'calls.txt'))).toBe(false)
+    expect(existsSync(join(sessionDir('store-tidy'), 'report.md'))).toBe(true)
+  })
+
+  test('an unanalyzed session is left alone — its analyzer may still be running', () => {
+    seed('store-pending', { ageMs: DAY, bytes: 100 })
+    writeFileSync(join(sessionDir('store-pending'), 'analyzer-prompt.md'), '# in flight')
+
+    sweepStore({ budget: BUDGET })
+
+    expect(existsSync(join(sessionDir('store-pending'), 'analyzer-prompt.md'))).toBe(true)
+  })
+
+  test('scratch is tidied before the size bound is measured, not after', () => {
+    // 60 KB of scratch against a 10 KB budget: tidying first brings the store
+    // back under on its own, so nothing should be evicted.
+    seed('store-bloated', { ageMs: DAY, analyzed: true, bytes: 100 })
+    writeFileSync(join(sessionDir('store-bloated'), 'calls.txt'), 'x'.repeat(60_000))
+
+    expect(sweepStore({ budget: BUDGET }).removed).toEqual([])
+    expect(existsSync(sessionDir('store-bloated'))).toBe(true)
+  })
+
+  test('a failed analysis keeps its prompt through the sweep', () => {
+    const dir = sessionDir('store-failed')
+    seed('store-failed', { ageMs: DAY, analyzed: true })
+    writeFileSync(
+      join(dir, '.analyzed'),
+      JSON.stringify({ analyzedAt: new Date().toISOString(), outcome: 'error', note: 'boom' }),
+    )
+    writeFileSync(join(dir, 'analyzer-prompt.md'), '# what we asked')
+
+    sweepStore({ budget: BUDGET })
+
+    expect(existsSync(join(dir, 'analyzer-prompt.md'))).toBe(true)
+  })
+})
+
+describe('tidySession', () => {
+  test('removes what the analyzer left behind, keeps the durable artifacts', () => {
+    const dir = sessionDir('tidy-scratch')
+    seed('tidy-scratch', { ageMs: DAY, analyzed: true, bytes: 100 })
+    writeFileSync(join(dir, 'analyzer.log'), 'exit 0')
+    writeFileSync(join(dir, 'analyzer-prompt.md'), '# prompt')
+    // Scratch: the analyzer runs with Write in here and answers to nobody.
+    writeFileSync(join(dir, 'calls.txt'), 'x'.repeat(50_000))
+    mkdirSync(join(dir, 'notes'), { recursive: true })
+    writeFileSync(join(dir, 'notes', 'draft.md'), 'scratch')
+
+    const removed = tidySession('tidy-scratch')
+
+    expect(removed.sort()).toEqual(['analyzer-prompt.md', 'calls.txt', 'notes'])
+    for (const keep of ['meta.json', 'events.jsonl', 'report.md', '.analyzed', 'analyzer.log']) {
+      expect(existsSync(join(dir, keep))).toBe(true)
+    }
+    expect(existsSync(join(dir, 'notes'))).toBe(false)
+  })
+
+  test('keepPrompt spares the prompt — the failing case is when it matters', () => {
+    const dir = sessionDir('tidy-failed')
+    seed('tidy-failed', { ageMs: DAY, analyzed: true })
+    writeFileSync(join(dir, 'analyzer-prompt.md'), '# prompt')
+    writeFileSync(join(dir, 'scratch.json'), '{}')
+
+    expect(tidySession('tidy-failed', { keepPrompt: true })).toEqual(['scratch.json'])
+    expect(existsSync(join(dir, 'analyzer-prompt.md'))).toBe(true)
+  })
+
+  test('a session with nothing to tidy is left exactly as it was', () => {
+    seed('tidy-clean', { ageMs: DAY, analyzed: true, bytes: 10 })
+    expect(tidySession('tidy-clean')).toEqual([])
+    expect(existsSync(sessionDir('tidy-clean'))).toBe(true)
+  })
+
+  test('a missing session directory is a no-op, not an error', () => {
+    expect(tidySession('tidy-absent')).toEqual([])
+  })
+})

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

@@ -0,0 +1,102 @@
+import { afterEach, beforeAll, beforeEach, describe, expect, test } from 'bun:test'
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+import type { RetentionBudget } from '../settings'
+
+// Set the home before the paths singleton is captured (dynamic imports below).
+process.env.ASTRALE_HOME = mkdtempSync(join(tmpdir(), 'astrale-tele-settings-'))
+
+let retentionBudget: () => RetentionBudget
+let telemetryEnabled: () => boolean
+let DEFAULT_MAX_AGE_DAYS: number
+let DEFAULT_MAX_BYTES: number
+let configPath: string
+
+const DAY = 24 * 60 * 60 * 1000
+
+beforeAll(async () => {
+  const settings = await import('../settings')
+  retentionBudget = settings.retentionBudget
+  telemetryEnabled = settings.telemetryEnabled
+  DEFAULT_MAX_AGE_DAYS = settings.DEFAULT_MAX_AGE_DAYS
+  DEFAULT_MAX_BYTES = settings.DEFAULT_MAX_BYTES
+  configPath = join(process.env.ASTRALE_HOME!, 'config.json')
+})
+
+function writeConfig(telemetry: unknown): void {
+  writeFileSync(configPath, JSON.stringify({ telemetry }))
+}
+
+beforeEach(() => {
+  rmSync(configPath, { force: true })
+  delete process.env.ASTRALE_TELEMETRY
+  delete process.env.ASTRALE_TELEMETRY_MAX_AGE_DAYS
+  delete process.env.ASTRALE_TELEMETRY_MAX_BYTES
+})
+
+afterEach(() => {
+  rmSync(configPath, { force: true })
+  delete process.env.ASTRALE_TELEMETRY_MAX_AGE_DAYS
+  delete process.env.ASTRALE_TELEMETRY_MAX_BYTES
+})
+
+describe('retentionBudget', () => {
+  test('defaults when nothing is configured', () => {
+    expect(retentionBudget()).toEqual({
+      maxAgeMs: DEFAULT_MAX_AGE_DAYS * DAY,
+      maxBytes: DEFAULT_MAX_BYTES,
+    })
+  })
+
+  test('reads both bounds from config.json', () => {
+    writeConfig({ maxAgeDays: 7, maxBytes: 1_048_576 })
+    expect(retentionBudget()).toEqual({ maxAgeMs: 7 * DAY, maxBytes: 1_048_576 })
+  })
+
+  test('env wins over config', () => {
+    writeConfig({ maxAgeDays: 7, maxBytes: 1_048_576 })
+    process.env.ASTRALE_TELEMETRY_MAX_AGE_DAYS = '2'
+    process.env.ASTRALE_TELEMETRY_MAX_BYTES = '4096'
+    expect(retentionBudget()).toEqual({ maxAgeMs: 2 * DAY, maxBytes: 4096 })
+  })
+
+  test('a bad env value falls through to config rather than unbounding the store', () => {
+    writeConfig({ maxAgeDays: 7 })
+    process.env.ASTRALE_TELEMETRY_MAX_AGE_DAYS = 'soon'
+    expect(retentionBudget().maxAgeMs).toBe(7 * DAY)
+  })
+
+  test.each([
+    ['zero', 0],
+    ['negative', -1],
+    ['not a number', 'lots'],
+    ['null', null],
+  ])('%s config values fall back to the default', (_label, maxBytes) => {
+    writeConfig({ maxBytes })
+    expect(retentionBudget().maxBytes).toBe(DEFAULT_MAX_BYTES)
+  })
+
+  test('a broken config yields defaults instead of throwing', () => {
+    writeFileSync(configPath, '{ not json')
+    expect(retentionBudget().maxBytes).toBe(DEFAULT_MAX_BYTES)
+  })
+})
+
+describe('telemetryEnabled', () => {
+  test('on by default, and unaffected by retention keys', () => {
+    writeConfig({ maxAgeDays: 7 })
+    expect(telemetryEnabled()).toBe(true)
+  })
+
+  test('off via config', () => {
+    writeConfig({ enabled: false })
+    expect(telemetryEnabled()).toBe(false)
+  })
+
+  test.each(['0', 'false', 'off', 'OFF', ' off '])('off via ASTRALE_TELEMETRY=%p', (value) => {
+    process.env.ASTRALE_TELEMETRY = value
+    expect(telemetryEnabled()).toBe(false)
+  })
+})

package/src/telemetry/__tests__/store-scan.test.ts

@@ -0,0 +1,128 @@
+import { beforeAll, 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 type { SessionInfo, SessionScan } from '../store'
+
+// Set the home before the paths singleton is captured (dynamic imports below).
+process.env.ASTRALE_HOME = mkdtempSync(join(tmpdir(), 'astrale-tele-scan-'))
+
+let scanSessions: (now?: number) => SessionScan[]
+let listSessions: (now?: number) => SessionInfo[]
+let readMeta: (id: string) => { root: string; explicit: boolean } | null
+let sessionDir: (id: string) => string
+let sessionsRoot: () => string
+let IDLE_WINDOW_MS: number
+
+const DAY = 24 * 60 * 60 * 1000
+
+beforeAll(async () => {
+  const store = await import('../store')
+  scanSessions = store.scanSessions
+  listSessions = store.listSessions
+  readMeta = store.readMeta as typeof readMeta
+  sessionDir = store.sessionDir
+  sessionsRoot = store.sessionsRoot
+  IDLE_WINDOW_MS = store.IDLE_WINDOW_MS
+})
+
+beforeEach(() => {
+  // Destructive cleanup must be provably confined to this file's mkdtemp home.
+  if (!sessionsRoot().startsWith(tmpdir())) throw new Error('refusing to clean a non-tmp home')
+  rmSync(sessionsRoot(), { recursive: true, force: true })
+})
+
+type Seed = { ageMs?: number; analyzed?: boolean; events?: boolean; root?: string }
+
+function seed(id: string, { ageMs = 0, analyzed = false, events = true, root = '/w' }: Seed): void {
+  const dir = sessionDir(id)
+  mkdirSync(dir, { recursive: true })
+  writeFileSync(join(dir, 'meta.json'), JSON.stringify({ id, root, explicit: false }))
+  if (analyzed) {
+    writeFileSync(
+      join(dir, '.analyzed'),
+      JSON.stringify({ analyzedAt: new Date().toISOString(), outcome: 'reported' }),
+    )
+  }
+  if (!events) return
+  writeFileSync(join(dir, 'events.jsonl'), '{}\n')
+  const when = new Date(Date.now() - ageMs)
+  utimesSync(join(dir, 'events.jsonl'), when, when)
+}
+
+describe('scanSessions', () => {
+  test('reports the same id set, ordering and open/closed verdict as listSessions', () => {
+    seed('scan-oldest', { ageMs: 5 * DAY, analyzed: true })
+    seed('scan-middle', { ageMs: 2 * DAY })
+    seed('scan-open', {})
+
+    const scan = scanSessions()
+    const full = listSessions()
+
+    expect(scan.map((s) => s.id)).toEqual(full.map((s) => s.id))
+    expect(scan.map((s) => s.closed)).toEqual(full.map((s) => s.closed))
+    expect(scan.map((s) => s.lastEventAt?.getTime() ?? null)).toEqual(
+      full.map((s) => s.lastEventAt?.getTime() ?? null),
+    )
+  })
+
+  test('analyzed is presence of the marker, matching listSessions', () => {
+    seed('scan-done', { ageMs: DAY, analyzed: true })
+    seed('scan-pending', { ageMs: DAY })
+
+    const byId = new Map(scanSessions().map((s) => [s.id, s.analyzed]))
+    expect(byId.get('scan-done')).toBe(true)
+    expect(byId.get('scan-pending')).toBe(false)
+    expect(listSessions().map((s) => s.analyzed !== null)).toEqual(
+      listSessions().map((s) => byId.get(s.id)!),
+    )
+  })
+
+  test('an unparseable marker still counts as analyzed — presence is the fact', () => {
+    seed('scan-broken-marker', { ageMs: DAY })
+    writeFileSync(join(sessionDir('scan-broken-marker'), '.analyzed'), '{ not json')
+    expect(scanSessions()[0]?.analyzed).toBe(true)
+  })
+
+  test('a session with no events yet is neither closed nor dated', () => {
+    seed('scan-no-events', { events: false })
+    const [only] = scanSessions()
+    expect(only?.lastEventAt).toBeNull()
+    expect(only?.closed).toBe(false)
+  })
+
+  test('closed is decided by the idle window', () => {
+    seed('scan-just-inside', { ageMs: IDLE_WINDOW_MS - 60_000 })
+    seed('scan-just-outside', { ageMs: IDLE_WINDOW_MS + 60_000 })
+    const byId = new Map(scanSessions().map((s) => [s.id, s.closed]))
+    expect(byId.get('scan-just-inside')).toBe(false)
+    expect(byId.get('scan-just-outside')).toBe(true)
+  })
+
+  test('a missing store directory scans to an empty list', () => {
+    rmSync(sessionsRoot(), { recursive: true, force: true })
+    expect(scanSessions()).toEqual([])
+  })
+
+  test('dotfiles in the store root are not sessions', () => {
+    seed('scan-real', { ageMs: DAY })
+    mkdirSync(sessionsRoot(), { recursive: true })
+    writeFileSync(join(sessionsRoot(), '.analyzer.lock'), '{}')
+    expect(scanSessions().map((s) => s.id)).toEqual(['scan-real'])
+  })
+})
+
+describe('readMeta', () => {
+  test('returns the parsed meta for one session', () => {
+    seed('meta-one', { ageMs: DAY, root: '/workspace/alpha' })
+    expect(readMeta('meta-one')?.root).toBe('/workspace/alpha')
+  })
+
+  test('missing or broken meta reads as null rather than throwing', () => {
+    expect(readMeta('meta-absent')).toBeNull()
+    mkdirSync(sessionDir('meta-broken'), { recursive: true })
+    writeFileSync(join(sessionDir('meta-broken'), 'meta.json'), '{ not json')
+    expect(readMeta('meta-broken')).toBeNull()
+  })
+})

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

@@ -35,15 +35,44 @@ function seed(id: string, ageMs: number, analyzed: boolean): void {
   utimesSync(join(dir, 'events.jsonl'), when, when)
 }
 
+const DAY = 24 * 60 * 60 * 1000
+
+// NOTE: none of these seed a closed-unanalyzed session, so the trigger finds no
+// analysis target and no test here ever spawns a child process.
 describe('opportunistic GC', () => {
-  test('removes analyzed sessions past retention, keeps recent and unanalyzed ones', () => {
-    const DAY = 24 * 60 * 60 * 1000
+  test('removes sessions past retention, keeps recent ones', () => {
     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)
   })
+
+  test('runs with telemetry disabled — switching it off must drain the store', () => {
+    seed('gc-off-old', 40 * DAY, true)
+    process.env.ASTRALE_TELEMETRY = '0'
+    try {
+      maybeTriggerAnalysis(['bun', 'astrale', 'status'])
+    } finally {
+      delete process.env.ASTRALE_TELEMETRY
+    }
+    expect(existsSync(sessionDir('gc-off-old'))).toBe(false)
+  })
+
+  test('runs on `session` commands, which are exempt from analysis only', () => {
+    seed('gc-session-cmd-old', 40 * DAY, true)
+    maybeTriggerAnalysis(['bun', 'astrale', 'session', 'list'])
+    expect(existsSync(sessionDir('gc-session-cmd-old'))).toBe(false)
+  })
+
+  test('honours a configured age bound', () => {
+    seed('gc-two-days', 2 * DAY, true)
+    process.env.ASTRALE_TELEMETRY_MAX_AGE_DAYS = '1'
+    try {
+      maybeTriggerAnalysis(['bun', 'astrale', 'status'])
+    } finally {
+      delete process.env.ASTRALE_TELEMETRY_MAX_AGE_DAYS
+    }
+    expect(existsSync(sessionDir('gc-two-days'))).toBe(false)
+  })
 })