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

package/src/lib/skills.ts

@@ -3,62 +3,11 @@ import { homedir } from 'node:os'
 import { dirname, join } from 'node:path'
 
 import { findAgentBrowser } from './browser'
-import { run } from './proc'
 
-/**
- * Agent skills and the agent-browser tool are owned by the coding-agent harness
- * (Claude Code et al.) and by npm — not by this CLI. `astrale setup` and
- * `astrale update` only *detect* them and delegate installation to their real
- * installers (`npx skills add`, `npm i -g agent-browser`). This module is that
- * detection + delegation layer.
- */
+export * from './skills/sync'
 
-/** The skill name the agent harness looks up under `<dir>/<name>/SKILL.md`. */
-export const ASTRALE_CLI_SKILL = 'astrale-cli'
-export const ASTRALE_DOMAIN_SKILL = 'astrale-domain'
 export const AGENT_BROWSER_SKILL = 'agent-browser'
 
-/**
- * Published skill source consumed by `npx skills add`. The public `astrale-os/cli`
- * repo hosts BOTH the astrale-cli and astrale-domain skills (under `skills/`), so
- * one `npx skills add astrale-os/cli` installs both; address one with
- * `astrale-os/cli@astrale-cli` or `astrale-os/cli@astrale-domain`.
- */
-export const ASTRALE_CLI_SKILL_SOURCE = 'astrale-os/cli'
-
-/** Human-facing command that installs (or refreshes) both astrale skills, globally. */
-export const SKILL_INSTALL_HINT = `npx skills add ${ASTRALE_CLI_SKILL_SOURCE} -g`
-
-/**
- * Install or refresh the astrale agent skills by delegating to the skill package
- * manager (`npx skills add`). We install GLOBALLY (`-g`, user-level): one run
- * equips every project on the machine — the harness resolves the skills from the
- * user Claude dir (see {@link detectSkill}) regardless of cwd, and installs land
- * in `~/.agents/skills` rather than clobbering any project's own `.agents/skills`
- * (notably this repo's symlinked source). We don't reimplement skill installation
- * — re-running the real installer is also how an existing install updates to the
- * latest published SKILL.md, so this doubles as the update path.
- *
- * We CAPTURE the installer's output rather than stream it, and surface it only on
- * failure. A global install reports a benign per-agent note for any agent format
- * that can't go user-level (e.g. PromptScript: "does not support global skill
- * installation") as a "Failed to install N" banner — even though `npx skills`
- * still exits 0 and the skills land for every other agent. Streaming that made a
- * successful refresh look broken; suppressing it on success lets the caller print
- * a clean line. Resolves true on exit 0. Requires Node/`npx` on PATH + network.
- */
-export async function installSkills(): Promise<boolean> {
-  const { code, stdout, stderr } = await run('npx', [
-    'skills',
-    'add',
-    ASTRALE_CLI_SKILL_SOURCE,
-    '-g',
-    '-y',
-  ])
-  if (code !== 0) process.stderr.write(stdout + stderr)
-  return code === 0
-}
-
 /**
  * The directories the agent harness ACTUALLY loads skills from, in resolution
  * order: a project `.claude/skills` found by walking UP from cwd (the harness

package/src/program/__tests__/program.test.ts

@@ -195,7 +195,7 @@ describe('program composition', () => {
       'whoami',
     ])
     expect(createHash('sha256').update(JSON.stringify(surface)).digest('hex')).toBe(
-      '913d37eab2f603cc745bd9a1c10763a57bc9c2425d0181958d458b80e4a451d7',
+      '092b8f4f737740105c8baed9d01a81604711b5b2719dfcb834eeeac414732c61',
     )
   })
 

package/src/setup/steps/skills.ts

@@ -1,59 +1,61 @@
 import type { SetupStep } from '../types'
 
 import { log } from '../../lib/log'
-import {
-  ASTRALE_CLI_SKILL,
-  ASTRALE_DOMAIN_SKILL,
-  detectSkill,
-  installSkills,
-  SKILL_INSTALL_HINT,
-} from '../../lib/skills'
+import { checkAstraleSkills, SKILL_INSTALL_HINT, syncAstraleSkills } from '../../lib/skills'
 
 const FIX = SKILL_INSTALL_HINT
 
 /**
- * Equip — the astrale agent skills. Both the astrale-cli (ops) and astrale-domain
- * (authoring) skills publish from the one public `astrale-os/cli` repo, so a
- * single `npx skills add astrale-os/cli -g` installs both, globally. We don't
- * reimplement skill installation; we detect presence and delegate to `npx skills
- * add` (the skill package manager). A global (user-level) install equips every
- * project on the machine, so a freshly scaffolded domain has the skills without
- * shipping its own copy.
+ * Equip — reconcile every top-level Astrale-owned skill from astrale-os/cli main.
+ * Setup and update deliberately share one owner, so an existence-only setup check
+ * can never bless an incomplete or stale global cohort.
  */
-const bothInstalled = (): boolean =>
-  detectSkill(ASTRALE_CLI_SKILL).installed && detectSkill(ASTRALE_DOMAIN_SKILL).installed
-
 export const skillsStep: SetupStep = {
   id: 'skills',
-  title: 'astrale agent skills (cli + domain)',
+  title: 'Astrale agent skills',
   group: 'equip',
 
   async detect() {
-    if (bothInstalled()) {
-      return { state: 'satisfied', summary: 'astrale-cli + astrale-domain skills installed' }
+    const result = await checkAstraleSkills()
+    if (result.status === 'current') {
+      return { state: 'satisfied', summary: 'Astrale skills are installed and up to date' }
+    }
+    if (result.status === 'unavailable') {
+      return {
+        state: 'broken',
+        summary: 'Astrale skills could not be verified',
+        detail: result.error,
+        fixHint: FIX,
+      }
+    }
+    return {
+      state: 'gap',
+      summary:
+        result.status === 'repair-needed'
+          ? 'Astrale skills need repair'
+          : 'Astrale skills need installation or update',
+      fixHint: FIX,
     }
-    const have = detectSkill(ASTRALE_CLI_SKILL).installed
-      ? 'astrale-domain'
-      : 'astrale agent skills'
-    return { state: 'gap', summary: `${have} not installed`, fixHint: FIX }
   },
 
   async ensure() {
-    if (bothInstalled()) {
-      log.success('astrale-cli + astrale-domain skills already installed')
-      return 'unchanged'
-    }
-
-    log.step(`Installing the astrale agent skills — ${FIX}`)
-    if (!(await installSkills())) {
-      log.warn(`Skill install did not complete — run it later: ${FIX}`)
+    log.step('Ensuring Astrale agent skills are current and healthy')
+    try {
+      const result = await syncAstraleSkills()
+      if (result.status === 'unchanged') {
+        log.success('Astrale skills already up to date')
+        return 'unchanged'
+      }
+      if (result.status === 'installed') log.success('Astrale skills installed')
+      else if (result.status === 'updated') log.success('Astrale skills updated')
+      else if (result.status === 'repaired') log.success('Astrale skills repaired and updated')
+      return 'fixed'
+    } catch (error) {
+      log.warn(
+        `Astrale skills could not be installed safely${error instanceof Error ? `: ${error.message}` : ''}`,
+      )
+      log.dim(`  Retry: ${FIX}`)
       return 'failed'
     }
-    if (bothInstalled()) {
-      log.success('astrale-cli + astrale-domain skills installed')
-    } else {
-      log.success('astrale-cli skill installed')
-    }
-    return 'fixed'
   },
 }

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

@@ -0,0 +1,180 @@
+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 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 } = 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'])
+  })
+})

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

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 = {