@astrale-os/cli 1.0.0-beta.3 → 1.0.0-beta.31

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

package/src/telemetry/analyze.ts

@@ -5,18 +5,20 @@
  * through the native `issues.astrale.ai` domain.
  */
 import { spawn } from 'node:child_process'
-import { appendFileSync, writeFileSync } from 'node:fs'
+import { writeFileSync } from 'node:fs'
 import { join } from 'node:path'
 
 import type { AnalyzedMarker, SessionSignals } from './types'
 
 import { defaultAdapters, discoverAll } from './adapters'
 import { extractSignals, hasSignals, readEvents } from './gate'
+import { tidySession } from './retention'
 import { eventsPath, inspectSession, markerPath, sessionDir } from './store'
 
 const ANALYZER_TIMEOUT_MS = 15 * 60 * 1000
 const WINDOW_PAD_MS = 10 * 60 * 1000
 const MAX_TRANSCRIPTS = 6
+const MAX_ANALYZER_LOG_BYTES = 32 * 1024
 // Transcripts embed content the developer's agent pulled from anywhere — treat
 // them as injection vectors: no --dangerously-skip-permissions; unlisted tools
 // are simply denied in -p mode. git/astrale cover inspection + reproduction +
@@ -29,6 +31,16 @@ function writeMarker(id: string, marker: AnalyzedMarker): void {
   writeFileSync(markerPath(id), JSON.stringify(marker, null, 2) + '\n')
 }
 
+/** Head and tail, never the middle: the JSON envelope opens at the top, a stack
+ *  or an error message closes at the bottom, and what sits between them is the
+ *  part nobody reads. A log is a diagnostic aid, not a place to put a megabyte. */
+export function clampLog(text: string, max = MAX_ANALYZER_LOG_BYTES): string {
+  if (text.length <= max) return text
+  const half = Math.floor((max - 64) / 2)
+  const elided = text.length - 2 * half
+  return `${text.slice(0, half)}\n… ${elided} bytes elided …\n${text.slice(-half)}`
+}
+
 /** Compact per-command digest so the agent starts from facts, not raw logs. */
 function eventDigest(signals: SessionSignals): string {
   const lines: string[] = [`events: ${signals.eventCount}`]
@@ -146,6 +158,7 @@ export async function analyzeSession(
       note: `${signals.eventCount} events, all green, no transcripts`,
     }
     writeMarker(id, marker)
+    tidySession(id)
     return marker
   }
 
@@ -161,6 +174,9 @@ export async function analyzeSession(
     note: outcome.note,
   }
   writeMarker(id, marker)
+  // Keep the prompt only when the run failed — that is the one case where what
+  // the analyzer was asked still matters.
+  tidySession(id, { keepPrompt: marker.outcome === 'error' })
   return { ...marker, reportPath: join(dir, 'report.md') }
 }
 
@@ -200,7 +216,13 @@ function runClaude(
     child.on('close', (code) => {
       clearTimeout(timer)
       try {
-        appendFileSync(join(cwd, 'analyzer.log'), out + (err ? `\n--- stderr ---\n${err}` : ''))
+        // Write rather than append: the output is one JSON envelope per run, so
+        // stacking several produced a file that parsed as none of them. A
+        // re-analysis replaces its predecessor's log instead of growing it.
+        writeFileSync(
+          join(cwd, 'analyzer.log'),
+          clampLog(out + (err ? `\n--- stderr ---\n${err}` : '')),
+        )
       } catch {
         /* best effort */
       }

package/src/telemetry/recorder.ts

@@ -6,6 +6,7 @@
  */
 import { appendFileSync } from 'node:fs'
 
+import type { SessionScan } from './store'
 import type { TelemetryEvent } from './types'
 
 import { redactArgv } from './redact'
@@ -17,22 +18,32 @@ import { eventsPath } from './store'
 export type Finalizer = (exitCode: number, errorName?: string) => void
 
 const NOOP: Finalizer = () => {}
-const HELP_VERSION = new Set(['-h', '--help', '-V', '--version', 'help', 'version'])
+const HELP_VERSION = new Set([
+  '-h',
+  '--help',
+  '-V',
+  '--version',
+  '--cli-version',
+  'help',
+  'version',
+])
 
 /** Bare invocation (every() is true for []) or only help/version tokens — skip. */
 function isHelpOrVersion(args: string[]): boolean {
   return args.every((a) => HELP_VERSION.has(a))
 }
 
-/** Begin recording an invocation; returns a finalizer to call at process end. */
-export function beginInvocation(argv: string[]): Finalizer {
+/** Begin recording an invocation; returns a finalizer to call at process end.
+ *  `sessions` is an already-paid-for store scan the caller shares with
+ *  retention — see bin/astrale.ts. */
+export function beginInvocation(argv: string[], sessions?: readonly SessionScan[]): Finalizer {
   try {
     const args = argv.slice(2)
     if (!telemetryEnabled() || isHelpOrVersion(args)) return NOOP
     const startMs = Date.now()
     const ts = new Date(startMs).toISOString()
     const cwd = process.cwd()
-    const { id, root } = ensureSession(cwd)
+    const { id, root } = ensureSession(cwd, sessions)
     return (exitCode: number, errorName?: string) => {
       try {
         const event: TelemetryEvent = {

package/src/telemetry/retention.ts

@@ -0,0 +1,176 @@
+/**
+ * Session-store retention: two bounds, applied in that order.
+ *
+ * Age is a RELEVANCE bound — a session idle for a month has nothing left to
+ * say, and the harness transcripts its report would cite are long gone. It is
+ * free to enforce (scanSessions already stats every events.jsonl), so it runs
+ * on every CLI start, telemetry on or off: switching telemetry off must mean
+ * "and clean up what is already there", not "freeze the store forever".
+ *
+ * Size is a SAFETY bound — the analyzer runs with Write inside the session
+ * directory, so one pathological session can grow without limit. Enforcing it
+ * means stat-ing every file of every session, so it runs only in the detached
+ * analyzer, never on the user's critical path.
+ *
+ * Neither bound replaces the other: age bounds what is worth keeping, size
+ * bounds what can go wrong. Both are configurable — see settings.ts.
+ */
+import { type Dirent, readdirSync, rmSync } from 'node:fs'
+import { join } from 'node:path'
+
+import type { RetentionBudget } from './settings'
+import type { SessionScan } from './store'
+
+import { retentionBudget } from './settings'
+import { readMarker, scanSessions, sessionBytes, sessionDir } from './store'
+
+/** What an analyzed session is allowed to keep. Everything else is scratch: the
+ *  analyzer runs with Write inside the session directory, so without this a
+ *  session's size is whatever the agent felt like writing — one here was left
+ *  holding a 462 KB calls.txt, a quarter of the entire store. */
+const KEEP = new Set(['meta.json', 'events.jsonl', 'report.md', '.analyzed', 'analyzer.log'])
+
+/** Reproducible from events.jsonl in the normal case, and dropped there — but
+ *  it is the only record of what the analyzer was actually asked when it
+ *  failed, which is exactly when someone will want to look. */
+const ANALYZER_PROMPT = 'analyzer-prompt.md'
+
+/**
+ * Reduce one session to its durable artifacts, called once the analyzer has
+ * written its marker. This is what makes a session's footprint a property of
+ * the CLI rather than of whatever the agent decided to leave behind.
+ */
+export function tidySession(id: string, options: { keepPrompt?: boolean } = {}): string[] {
+  const dir = sessionDir(id)
+  let entries: Dirent[]
+  try {
+    entries = readdirSync(dir, { withFileTypes: true })
+  } catch {
+    return []
+  }
+  const removed: string[] = []
+  for (const entry of entries) {
+    if (KEEP.has(entry.name)) continue
+    if (entry.name === ANALYZER_PROMPT && options.keepPrompt === true) continue
+    try {
+      rmSync(join(dir, entry.name), { recursive: true, force: true })
+      removed.push(entry.name)
+    } catch {
+      /* best effort — tidying must never fail the analysis it follows */
+    }
+  }
+  return removed
+}
+
+/** Cap for the age sweep on the CLI's critical path, so a large backlog drains
+ *  over several runs instead of stalling one command on hundreds of rmSync. */
+export const MAX_REMOVALS_ON_START = 20
+
+export type SweepOptions = {
+  /** Defaults to the resolved config budget. */
+  budget?: RetentionBudget
+  now?: number
+  /** Cap on removals; unbounded when omitted. */
+  limit?: number
+  /** Ids that must survive — the session being recorded or analyzed right now. */
+  protect?: ReadonlySet<string>
+}
+
+/** Session ids removed, in removal order. */
+export type SweepResult = { removed: string[] }
+
+function remove(id: string, into: string[]): void {
+  try {
+    rmSync(sessionDir(id), { recursive: true, force: true })
+    into.push(id)
+  } catch {
+    /* best effort — retention must never affect the CLI */
+  }
+}
+
+/**
+ * Drop every session whose last activity predates the age bound, analyzed or
+ * not: a session that went a month without being analyzed never will be.
+ * Sessions with no events yet are exempt — one of them is the invocation
+ * running right now, created by ensureSession and not written until exit.
+ */
+export function sweepByAge(
+  sessions: readonly SessionScan[],
+  options: SweepOptions = {},
+): SweepResult {
+  const { maxAgeMs } = options.budget ?? retentionBudget()
+  const cutoff = (options.now ?? Date.now()) - maxAgeMs
+  const limit = options.limit ?? Number.POSITIVE_INFINITY
+  const protect = options.protect
+  const removed: string[] = []
+  for (const session of sessions) {
+    if (removed.length >= limit) break
+    if (protect?.has(session.id)) continue
+    if (session.lastEventAt !== null && session.lastEventAt.getTime() < cutoff) {
+      remove(session.id, removed)
+    }
+  }
+  return { removed }
+}
+
+/**
+ * Trim the store to the size bound, evicting oldest-first and analyzed before
+ * unanalyzed — an analyzed session has already handed its evidence to a report,
+ * an unanalyzed one has not. Open sessions are never touched: one of them is
+ * being recorded right now.
+ */
+export function sweepToBudget(
+  sessions: readonly SessionScan[],
+  options: SweepOptions = {},
+): SweepResult {
+  const { maxBytes } = options.budget ?? retentionBudget()
+  const protect = options.protect
+  const removed: string[] = []
+
+  const sized = sessions.map((session) => ({ session, bytes: sessionBytes(session.id) }))
+  let total = sized.reduce((sum, entry) => sum + entry.bytes, 0)
+  if (total <= maxBytes) return { removed }
+
+  // Oldest first; a session with no events yet sorts to the front — it holds
+  // nothing but a meta.json, so it is the cheapest thing to lose.
+  const evictable = sized
+    .filter((entry) => entry.session.closed && !protect?.has(entry.session.id))
+    .sort(
+      (a, b) => (a.session.lastEventAt?.getTime() ?? 0) - (b.session.lastEventAt?.getTime() ?? 0),
+    )
+
+  for (const analyzedFirst of [true, false]) {
+    for (const entry of evictable) {
+      if (total <= maxBytes) return { removed }
+      if (entry.session.analyzed !== analyzedFirst) continue
+      const before = removed.length
+      remove(entry.session.id, removed)
+      if (removed.length > before) total -= entry.bytes
+    }
+  }
+  return { removed }
+}
+
+/**
+ * Both bounds over the live store, for the detached analyzer: age first (cheap,
+ * and it may free enough on its own), then size over whatever survives.
+ */
+export function sweepStore(options: SweepOptions = {}): SweepResult {
+  const budget = options.budget ?? retentionBudget()
+  const sessions = scanSessions()
+  const byAge = sweepByAge(sessions, { ...options, budget })
+  const gone = new Set(byAge.removed)
+  const survivors = sessions.filter((session) => !gone.has(session.id))
+
+  // Tidy before measuring. Doing it after would let a session be evicted for
+  // holding scratch that was about to be deleted anyway — and it is what makes
+  // the artifact bound retroactive rather than only applying to new analyses.
+  for (const session of survivors) {
+    if (session.analyzed) {
+      tidySession(session.id, { keepPrompt: readMarker(session.id)?.outcome === 'error' })
+    }
+  }
+
+  const bySize = sweepToBudget(survivors, { ...options, budget })
+  return { removed: [...byAge.removed, ...bySize.removed] }
+}

package/src/telemetry/session.ts

@@ -10,7 +10,7 @@ import { dirname, join } from 'node:path'
 
 import type { SessionMeta } from './types'
 
-import { listSessions, metaPath, sessionDir } from './store'
+import { metaPath, readMeta, scanSessions, sessionDir, type SessionScan } from './store'
 
 export type ResolvedSession = { id: string; root: string; explicit: boolean }
 
@@ -40,12 +40,14 @@ function stamp(d = new Date()): string {
 
 /** id of an open, ambient session already bucketed to `root`, else null.
  *  Analyzed sessions are never reused — a straggler event may "reopen" one
- *  after its report, and new work funneled there would never be analyzed. */
-function findOpenAmbient(root: string): string | null {
-  for (const s of listSessions()) {
-    if (s.meta?.root === root && s.meta.explicit === false && !s.closed && s.analyzed === null) {
-      return s.id
-    }
+ *  after its report, and new work funneled there would never be analyzed.
+ *  Only the open, unanalyzed candidates get their meta.json read: on a store of
+ *  hundreds at most a couple qualify, and this runs before every command. */
+function findOpenAmbient(root: string, sessions: readonly SessionScan[]): string | null {
+  for (const s of sessions) {
+    if (s.closed || s.analyzed) continue
+    const meta = readMeta(s.id)
+    if (meta?.root === root && meta.explicit === false) return s.id
   }
   return null
 }
@@ -55,20 +57,24 @@ function mintAmbientId(root: string): string {
   return `amb-${hash8}-${stamp()}`
 }
 
-/** Resolve the session identity for `cwd` without creating anything on disk. */
-export function resolveSession(cwd: string): ResolvedSession {
+/** Resolve the session identity for `cwd` without creating anything on disk.
+ *  `sessions` lets the caller hand over a scan it already paid for — the CLI
+ *  start path shares one between recording and retention. */
+export function resolveSession(cwd: string, sessions?: readonly SessionScan[]): ResolvedSession {
   const root = findGitRoot(cwd) ?? cwd
   const pinned = process.env.ASTRALE_SESSION
   if (pinned) {
     const id = sanitizeId(pinned)
     if (id.length > 0) return { id, root, explicit: true }
   }
-  return { id: findOpenAmbient(root) ?? mintAmbientId(root), root, explicit: false }
+  // Only scan when a pinned id did not already settle it.
+  const scan = sessions ?? scanSessions()
+  return { id: findOpenAmbient(root, scan) ?? mintAmbientId(root), root, explicit: false }
 }
 
 /** Resolve, then create the session dir + meta.json on first sight. */
-export function ensureSession(cwd: string): ResolvedSession {
-  const resolved = resolveSession(cwd)
+export function ensureSession(cwd: string, sessions?: readonly SessionScan[]): ResolvedSession {
+  const resolved = resolveSession(cwd, sessions)
   const dir = sessionDir(resolved.id)
   if (!existsSync(dir)) {
     try {

package/src/telemetry/settings.ts

@@ -1,7 +1,9 @@
 /**
- * Telemetry kill-switch, evaluated synchronously at process start/exit.
- * Off when ASTRALE_TELEMETRY is 0/false/off, or when config telemetry.enabled
- * is false; on by default. Every read silent-fails to enabled.
+ * Telemetry kill-switch and retention budget, both read synchronously from
+ * `~/.astrale/config.json` with env overrides. Off when ASTRALE_TELEMETRY is
+ * 0/false/off, or when config telemetry.enabled is false; on by default.
+ * Every read silent-fails to the default — a broken config must never break
+ * the CLI, and must never leave the session store unbounded.
  */
 import { readFileSync } from 'node:fs'
 
@@ -9,18 +11,69 @@ import { createPaths } from '../state/index'
 
 const OFF_VALUES = new Set(['0', 'false', 'off'])
 
-/** Whether telemetry recording is enabled for this process. */
-export function telemetryEnabled(): boolean {
-  const env = process.env.ASTRALE_TELEMETRY
-  if (env !== undefined && OFF_VALUES.has(env.trim().toLowerCase())) return false
+/** Sessions idle longer than this are dropped: a month-old session has nothing
+ *  left to say, and the harness transcripts its report would cite are gone. */
+export const DEFAULT_MAX_AGE_DAYS = 30
+
+/** Hard ceiling on the whole session store. At ~35 KB per session that is some
+ *  1,400 sessions — never reached in normal use. It exists for the pathological
+ *  case: the analyzer runs with Write inside the session directory, so a single
+ *  session can grow without bound. */
+export const DEFAULT_MAX_BYTES = 50 * 1024 * 1024
+
+type TelemetryConfig = {
+  enabled?: boolean
+  maxAgeDays?: number
+  maxBytes?: number
+}
+
+/** The `telemetry` block, or {} when the config is missing or unreadable. */
+function readConfig(): TelemetryConfig {
   try {
     // Call-time path resolution — see sessionsRoot() in store.ts for why.
     const parsed = JSON.parse(readFileSync(createPaths().config, 'utf-8')) as {
-      telemetry?: { enabled?: boolean }
+      telemetry?: TelemetryConfig
     }
-    if (parsed.telemetry?.enabled === false) return false
+    const telemetry = parsed.telemetry
+    return typeof telemetry === 'object' && telemetry !== null ? telemetry : {}
   } catch {
-    /* missing or broken config → default on */
+    /* missing or broken config → defaults */
+    return {}
   }
-  return true
+}
+
+/** Whether telemetry recording is enabled for this process. */
+export function telemetryEnabled(): boolean {
+  const env = process.env.ASTRALE_TELEMETRY
+  if (env !== undefined && OFF_VALUES.has(env.trim().toLowerCase())) return false
+  return readConfig().enabled !== false
+}
+
+/** The two bounds on the session store — see retention.ts for how they apply. */
+export type RetentionBudget = {
+  maxAgeMs: number
+  maxBytes: number
+}
+
+/** First finite, strictly positive candidate. Zero, negatives and garbage fall
+ *  through to the next candidate (ultimately the default) rather than
+ *  disabling the bound, so a typo can never make the store unbounded. */
+function firstPositive(candidates: (number | string | undefined)[]): number | null {
+  for (const candidate of candidates) {
+    if (candidate === undefined) continue
+    const n = typeof candidate === 'string' ? Number(candidate.trim()) : candidate
+    if (Number.isFinite(n) && n > 0) return n
+  }
+  return null
+}
+
+/** Resolved retention budget: env over config over defaults. */
+export function retentionBudget(): RetentionBudget {
+  const config = readConfig()
+  const days =
+    firstPositive([process.env.ASTRALE_TELEMETRY_MAX_AGE_DAYS, config.maxAgeDays]) ??
+    DEFAULT_MAX_AGE_DAYS
+  const bytes =
+    firstPositive([process.env.ASTRALE_TELEMETRY_MAX_BYTES, config.maxBytes]) ?? DEFAULT_MAX_BYTES
+  return { maxAgeMs: days * 24 * 60 * 60 * 1000, maxBytes: bytes }
 }