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

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'
@@ -32,15 +33,17 @@ 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,129 @@
+/**
+ * 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 { rmSync } from 'node:fs'
+
+import type { RetentionBudget } from './settings'
+import type { SessionScan } from './store'
+
+import { retentionBudget } from './settings'
+import { scanSessions, sessionBytes, sessionDir } from './store'
+
+/** 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 bySize = sweepToBudget(
+    sessions.filter((session) => !gone.has(session.id)),
+    { ...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 }
 }

package/src/telemetry/store.ts

@@ -5,8 +5,14 @@
  *   .analyzed      AnalyzedMarker, written by the analyzer (any outcome)
  *   report.md      analyzer output
  * A session is CLOSED when events.jsonl's mtime is older than IDLE_WINDOW_MS.
+ *
+ * Two ways to read it, deliberately kept apart. scanSessions() answers the
+ * questions the CLI's start path asks — how old, open or closed, analyzed yet —
+ * from two stats per session and no file reads. listSessions() adds the parsed
+ * meta.json and marker, which only `session list` and the analyzer need. The
+ * start path runs before EVERY command, so the difference is not academic.
  */
-import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs'
+import { type Dirent, existsSync, readdirSync, readFileSync, statSync } from 'node:fs'
 import { join } from 'node:path'
 
 import type { AnalyzedMarker, SessionMeta } from './types'
@@ -42,6 +48,78 @@ export function reportPath(id: string): string {
   return join(sessionDir(id), 'report.md')
 }
 
+/**
+ * The cheap facts about one session: enough to bucket an invocation, sweep the
+ * store, and pick an analysis target. `analyzed` records that a marker EXISTS,
+ * not what it says — a stat, not a read.
+ */
+export type SessionScan = {
+  id: string
+  lastEventAt: Date | null
+  closed: boolean
+  analyzed: boolean
+}
+
+/** Session directory names, newest-first ordering applied by the callers. */
+function sessionIds(): string[] {
+  try {
+    return readdirSync(sessionsRoot()).filter((name) => !name.startsWith('.'))
+  } catch {
+    return []
+  }
+}
+
+/** Newest activity first. Two stats per session, no file reads, no parsing. */
+export function scanSessions(now = Date.now()): SessionScan[] {
+  return sessionIds()
+    .map((id) => {
+      let lastEventAt: Date | null = null
+      try {
+        lastEventAt = statSync(eventsPath(id)).mtime
+      } catch {
+        /* no events yet */
+      }
+      return {
+        id,
+        lastEventAt,
+        closed: lastEventAt !== null && now - lastEventAt.getTime() > IDLE_WINDOW_MS,
+        analyzed: existsSync(markerPath(id)),
+      }
+    })
+    .sort((a, b) => (b.lastEventAt?.getTime() ?? 0) - (a.lastEventAt?.getTime() ?? 0))
+}
+
+/** Bytes on disk under `dir`. Unreadable entries count as zero — a directory
+ *  racing away mid-walk is normal, not an error worth propagating. */
+function directoryBytes(dir: string): number {
+  let entries: Dirent[]
+  try {
+    entries = readdirSync(dir, { withFileTypes: true })
+  } catch {
+    return 0
+  }
+  let total = 0
+  for (const entry of entries) {
+    const path = join(dir, entry.name)
+    if (entry.isDirectory()) {
+      total += directoryBytes(path)
+    } else if (entry.isFile()) {
+      try {
+        total += statSync(path).size
+      } catch {
+        /* raced away mid-walk */
+      }
+    }
+  }
+  return total
+}
+
+/** Bytes one session occupies. The analyzer runs with Write inside the session
+ *  directory and may nest, so this walks rather than listing one level. */
+export function sessionBytes(id: string): number {
+  return directoryBytes(sessionDir(id))
+}
+
 export type SessionInfo = {
   id: string
   meta: SessionMeta | null
@@ -50,6 +128,11 @@ export type SessionInfo = {
   analyzed: AnalyzedMarker | null
 }
 
+/** One session's meta.json, or null when absent or unparseable. */
+export function readMeta(id: string): SessionMeta | null {
+  return readJsonSafe<SessionMeta>(metaPath(id))
+}
+
 function readJsonSafe<T>(path: string): T | null {
   try {
     return JSON.parse(readFileSync(path, 'utf-8')) as T
@@ -76,15 +159,10 @@ export function inspectSession(id: string, now = Date.now()): SessionInfo | null
   }
 }
 
-/** All sessions, newest activity first. Missing store dir → empty list. */
+/** All sessions, newest activity first, fully parsed. Missing store dir → empty
+ *  list. Prefer scanSessions() anywhere latency matters — see the file header. */
 export function listSessions(now = Date.now()): SessionInfo[] {
-  let ids: string[]
-  try {
-    ids = readdirSync(sessionsRoot()).filter((n) => !n.startsWith('.'))
-  } catch {
-    return []
-  }
-  return ids
+  return sessionIds()
     .map((id) => inspectSession(id, now))
     .filter((s): s is SessionInfo => s !== null)
     .sort((a, b) => (b.lastEventAt?.getTime() ?? 0) - (a.lastEventAt?.getTime() ?? 0))

package/src/telemetry/trigger.ts

@@ -2,36 +2,18 @@
  * Opportunistic analysis trigger — the `git gc --auto` model. Each CLI start
  * cheaply scans for a closed, unanalyzed session and spawns ONE detached
  * analyzer for it. No daemon, no cron; a lockfile keeps it single-flight.
+ * The same scan pays for the age sweep (see retention.ts), which is why the
+ * store stays bounded without anything resembling a background job.
  */
 import { spawn } from 'node:child_process'
-import { existsSync, mkdirSync, readFileSync, rmSync, unlinkSync, writeFileSync } from 'node:fs'
+import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs'
 import { join } from 'node:path'
 
+import { MAX_REMOVALS_ON_START, sweepByAge } from './retention'
 import { telemetryEnabled } from './settings'
-import { listSessions, sessionDir, sessionsRoot, type SessionInfo } from './store'
+import { scanSessions, sessionsRoot, type SessionScan } from './store'
 
 const LOCK_STALE_MS = 30 * 60 * 1000
-const GC_AGE_MS = 30 * 24 * 60 * 60 * 1000
-const GC_MAX_PER_RUN = 20
-
-/** Opportunistic GC: analyzed sessions idle past the retention age are removed
- *  (capped per invocation) so the store — and the per-invocation scan — stays
- *  bounded. Evidence worth keeping has left via reports or filed issues. */
-function gcOldSessions(sessions: SessionInfo[]): void {
-  try {
-    const cutoff = Date.now() - GC_AGE_MS
-    let removed = 0
-    for (const s of sessions) {
-      if (removed >= GC_MAX_PER_RUN) break
-      if (s.analyzed !== null && s.lastEventAt !== null && s.lastEventAt.getTime() < cutoff) {
-        rmSync(sessionDir(s.id), { recursive: true, force: true })
-        removed++
-      }
-    }
-  } catch {
-    /* best effort */
-  }
-}
 
 function lockPath(): string {
   return join(sessionsRoot(), '.analyzer.lock')
@@ -76,16 +58,22 @@ export function releaseLock(): void {
  * the most recently closed unanalyzed session, if any. Never throws, never
  * blocks — worst case a few ms of directory stats.
  */
-export function maybeTriggerAnalysis(argv: string[]): void {
+export function maybeTriggerAnalysis(argv: string[], scan?: readonly SessionScan[]): void {
   try {
-    if (!telemetryEnabled()) return
     if (process.env.ASTRALE_TELEMETRY_NO_TRIGGER === '1') return
+
+    const sessions = scan ?? scanSessions()
+    // Retention runs ahead of the kill-switch check and on `session` commands
+    // too — turning telemetry off must still drain what is already on disk.
+    const swept = new Set(sweepByAge(sessions, { limit: MAX_REMOVALS_ON_START }).removed)
+
+    if (!telemetryEnabled()) return
     // Never cascade off the session commands themselves.
     if (argv[2] === 'session') return
 
-    const sessions = listSessions()
-    gcOldSessions(sessions)
-    const target = sessions.find((s) => s.closed && s.analyzed === null && s.lastEventAt !== null)
+    const target = sessions.find(
+      (s) => s.closed && !s.analyzed && s.lastEventAt !== null && !swept.has(s.id),
+    )
     if (!target) return
     if (!claimLock()) return