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

package/src/commands/domain/install.ts

@@ -426,6 +426,7 @@ export async function installDirect(
       target,
       host,
       opts.allowIdentityOverride ?? false,
+      isMachine(opts),
     )
   } catch (e) {
     fatal(e, opts)
@@ -451,11 +452,13 @@ export async function installDirect(
       // aliases the host and the pre-install gate never consented to THAT
       // origin (lying or unavailable Publication), say so loudly after the fact.
       if (isIdentityOverride(installed.origin, host) && installed.origin !== consentedOrigin) {
-        log.warn(
-          `Installed origin "${installed.origin}" differs from the serving host "${host}" ` +
-            `and was not confirmed before install (the worker Publication was unavailable). ` +
-            `Every ${installed.origin}/* call on this instance now routes to ${host}.`,
-        )
+        if (!isMachine(fmtOpts)) {
+          log.warn(
+            `Installed origin "${installed.origin}" differs from the serving host "${host}" ` +
+              `and was not confirmed before install (the worker Publication was unavailable). ` +
+              `Every ${installed.origin}/* call on this instance now routes to ${host}.`,
+          )
+        }
       }
     },
   })
@@ -512,20 +515,25 @@ async function ensureIdentityOverrideConsent(
   url: string,
   host: string,
   allow: boolean,
+  machine: boolean,
 ): Promise<string | undefined> {
   const origin = await probeDeclaredOrigin(url)
   if (origin === undefined) {
-    log.warn(
-      `Could not read a declared origin from ` +
-        `${new URL('/.well-known/astrale/domain.json', url).href} — ` +
-        `skipping the pre-install identity check (the installed origin is verified after install).`,
-    )
+    if (!machine) {
+      log.warn(
+        `Could not read a declared origin from ` +
+          `${new URL('/.well-known/astrale/domain.json', url).href} — ` +
+          `skipping the pre-install identity check (the installed origin is verified after install).`,
+      )
+    }
     return undefined
   }
   if (!isIdentityOverride(origin, host)) return undefined
 
   if (allow) {
-    log.warn(`Identity override consented via --allow-identity-override: ${origin} ← ${host}`)
+    if (!machine) {
+      log.warn(`Identity override consented via --allow-identity-override: ${origin} ← ${host}`)
+    }
     return origin
   }
 

package/src/commands/get.ts

@@ -46,7 +46,7 @@ export default {
   description: 'Get one canonical node by Path or ID',
   afterHelpText: `
 Behavior:
-  Resolves one exact Kernel V2 Path and prints the canonical Node
+  Resolves one exact Kernel Path and prints the canonical Node
   { id, class, props }. Missing and authorization-masked nodes remain
   intentionally indistinguishable. @self is expanded before dispatch.
 

package/src/commands/identity/register.ts

@@ -45,10 +45,9 @@ Behavior:
   its result and stores the same target-bound registration. The callable owns
   authorization; the CLI never receives installed Domain authority.
 
-  Kernel V2 Nodes have opaque identity and no caller-assigned storage path, so
-  the historical --path option no longer exists. The CLI binds the key proof
-  to the exact provision fingerprint and target Kernel audience, then caches
-  the returned (issuer, subject) for subsequent calls.
+  The Kernel assigns each Node ID; callers do not choose a storage path. The
+  CLI binds the key proof to the exact provision fingerprint and target Kernel
+  audience, then caches the returned (issuer, subject) for subsequent calls.
 
 Example:
   $ astrale identity register alice --class /:accounts.example:class.User \

package/src/commands/logs.ts

@@ -341,11 +341,8 @@ Behavior:
   Calls the public Kernel journal syscall and emits its { records, cursor }
   page. Topic selection is exact or prefix-based; cursors and timestamps are
   opaque strings owned by the journal backend. --follow reuses one Client Session
-  and advances only with the returned cursor. Machine follow output is NDJSON:
-  one complete admitted record per line; YAML follow is unsupported.
-
-  Historical event-glob lowering and the application-specific services-domain
-  log buffer are not part of the Kernel V2 journal contract.
+  and advances only with the returned cursor. With --json, follow output is
+  NDJSON with one complete admitted record per line; YAML follow is unsupported.
 
 Examples:
   $ astrale logs -i staging --limit 50

package/src/commands/session/analyze.ts

@@ -4,13 +4,23 @@ import type { CommandDefinition } from '../../program/index'
 
 import { log } from '../../lib/log'
 import { analyzeSession } from '../../telemetry/analyze'
-import { listSessions } from '../../telemetry/store'
+import { sweepStore } from '../../telemetry/retention'
+import { scanSessions } from '../../telemetry/store'
 import { restampLock, releaseLock } from '../../telemetry/trigger'
 
 export default {
   name: 'analyze',
   description: 'Analyze a recorded session for DX frictions (dry-run: writes report.md)',
-  arguments: [{ name: 'id', description: 'Session id (default: most recent closed, unanalyzed)' }],
+  arguments: [
+    // Optional: the action resolves the most recent closed, unanalyzed session
+    // when no id is given, which is how a human is meant to invoke this. The
+    // opportunistic trigger always passes an explicit id.
+    {
+      name: 'id',
+      description: 'Session id (default: most recent closed, unanalyzed)',
+      required: false,
+    },
+  ],
   options: [
     { flags: '--file', description: 'File cleared findings as issues on the admin tracker' },
     { flags: '--model <model>', description: 'Model for the analyzer pass' },
@@ -22,10 +32,10 @@ export default {
     opts: { file?: boolean; model?: string; force?: boolean; auto?: boolean },
   ) => {
     if (opts.auto) restampLock()
+    let target = id
     try {
-      let target = id
       if (!target) {
-        const candidate = listSessions().find((s) => s.closed && (opts.force || !s.analyzed))
+        const candidate = scanSessions().find((s) => s.closed && (opts.force || !s.analyzed))
         if (!candidate) {
           if (!opts.auto) log.dim('Nothing to analyze — no closed, unanalyzed session.')
           return
@@ -45,6 +55,18 @@ export default {
       }
     } finally {
       if (opts.auto) releaseLock()
+      // The size bound is enforced here, not on the CLI's critical path:
+      // measuring every file of every session is only affordable in this
+      // process, and this is precisely where the store just grew. The session
+      // just analyzed is protected — it is the freshest evidence on disk.
+      try {
+        const swept = sweepStore({ protect: new Set(target === undefined ? [] : [target]) })
+        if (!opts.auto && swept.removed.length > 0) {
+          log.dim(`retention: removed ${swept.removed.length} session(s)`)
+        }
+      } catch {
+        /* retention must never fail the command that triggered it */
+      }
     }
   },
 } satisfies CommandDefinition

package/src/lib/__tests__/skills.test.ts

@@ -31,7 +31,7 @@ afterEach(async () => {
 })
 
 async function makeSource(
-  names = ['astrale-cli', 'astrale-domain', 'astrale-services'],
+  names = ['astrale-cli', 'astrale-domain', 'astrale-frontend-design', 'astrale-services'],
   revision = 'new',
 ): Promise<{ root: string; snapshot: AstraleSkillSourceSnapshot }> {
   const root = await mkdtemp(join(tmpdir(), 'astrale-skills-source-'))
@@ -566,7 +566,13 @@ describe('Astrale skill reconciliation', () => {
 
   test('a retired source skill is removed without touching unrelated skills', async () => {
     const oldSource = await makeSource(
-      ['astrale-cli', 'astrale-domain', 'astrale-services', 'astrale-retired'],
+      [
+        'astrale-cli',
+        'astrale-domain',
+        'astrale-frontend-design',
+        'astrale-services',
+        'astrale-retired',
+      ],
       'old',
     )
     const latest = await makeSource(undefined, 'latest')

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(
-      '2e26ce7e4af960b3ec51401e2c439d1d54c13e06de7afda707aa65e8984bb37b',
+      '092b8f4f737740105c8baed9d01a81604711b5b2719dfcb834eeeac414732c61',
     )
   })
 

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