@astrale-os/cli 0.4.0-alpha.13 → 0.6.0-alpha.0

package/src/lib/view/snapshot.ts

@@ -0,0 +1,101 @@
+import type { AbResult } from '../browser'
+
+const SETTLE_TIMEOUT_MS = 8_000
+const QUIET_WINDOW_MS = 750
+const POLL_MS = 250
+
+type SettleClock = {
+  now(): number
+  sleep(ms: number): Promise<void>
+}
+
+type SettlePolicy = {
+  timeoutMs: number
+  quietWindowMs: number
+  pollMs: number
+}
+
+const realClock: SettleClock = {
+  now: Date.now,
+  sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+}
+
+const defaultPolicy: SettlePolicy = {
+  timeoutMs: SETTLE_TIMEOUT_MS,
+  quietWindowMs: QUIET_WINDOW_MS,
+  pollMs: POLL_MS,
+}
+
+export function snapshotText(result: AbResult): string | null {
+  const data = result.data as { snapshot?: unknown } | string | null
+  if (typeof data === 'string') return data
+  return typeof data?.snapshot === 'string' ? data.snapshot : null
+}
+
+function isMeaningfulSnapshot(text: string): boolean {
+  return /"[^"\n]+"/.test(text)
+}
+
+function isPendingSnapshot(text: string): boolean {
+  if (/\[[^\]]*\bbusy\b[^\]]*\]/i.test(text)) return true
+  if (/^\s*-\s*progressbar\b/im.test(text)) return true
+
+  // Views often render loading text without aria-busy. The timeout still
+  // returns that snapshot when a view never leaves its loading state.
+  return /"(?:loading|opening|connecting|initializing|preparing|starting|fetching|refreshing|please wait)(?:\b[^"\n]{0,100})?"/i.test(
+    text,
+  )
+}
+
+function fingerprint(text: string): string {
+  return text
+    .replace(/\bref=e\d+\b/g, 'ref')
+    .replace(/\s+/g, ' ')
+    .trim()
+}
+
+/**
+ * Warm the cross-origin accessibility tree, then wait for a meaningful view
+ * snapshot to remain unchanged briefly. Loading/busy states never settle
+ * early, but the timeout returns their latest snapshot for diagnosis.
+ */
+export async function waitForSettledSnapshot(
+  takeSnapshot: () => Promise<AbResult>,
+  clock: SettleClock = realClock,
+  policy: SettlePolicy = defaultPolicy,
+): Promise<AbResult> {
+  let lastAttempt = await takeSnapshot()
+  let lastSuccess = lastAttempt.ok ? lastAttempt : null
+  let stableFingerprint: string | null = null
+  let stableSince = clock.now()
+  const deadline = clock.now() + policy.timeoutMs
+
+  while (true) {
+    lastAttempt = await takeSnapshot()
+    const sampledAt = clock.now()
+
+    if (lastAttempt.ok) {
+      lastSuccess = lastAttempt
+      const text = snapshotText(lastAttempt)
+      if (text && isMeaningfulSnapshot(text)) {
+        const nextFingerprint = fingerprint(text)
+        if (nextFingerprint !== stableFingerprint) {
+          stableFingerprint = nextFingerprint
+          stableSince = sampledAt
+        } else if (!isPendingSnapshot(text) && sampledAt - stableSince >= policy.quietWindowMs) {
+          return lastAttempt
+        }
+      } else {
+        stableFingerprint = null
+        stableSince = sampledAt
+      }
+    } else {
+      stableFingerprint = null
+      stableSince = sampledAt
+    }
+
+    const remaining = deadline - clock.now()
+    if (remaining <= 0) return lastSuccess ?? lastAttempt
+    await clock.sleep(Math.min(policy.pollMs, remaining))
+  }
+}

package/src/program.ts

@@ -82,12 +82,15 @@ export async function buildProgram(): Promise<Command> {
   registerCommand(program, withKernelOptions((await import('./commands/call')).default))
   registerCommand(program, withKernelOptions((await import('./commands/token')).default))
   registerCommand(program, withKernelOptions((await import('./commands/get')).default))
+  registerCommand(program, withKernelOptions((await import('./commands/mutate')).default))
   registerCommand(program, withKernelOptions((await import('./commands/ls')).default))
   registerCommand(program, withKernelOptions((await import('./commands/describe')).default))
   registerCommand(program, withKernelOptions((await import('./commands/query')).default))
   registerCommand(program, withKernelOptions((await import('./commands/logs')).default))
+  registerCommand(program, withKernelOptions((await import('./commands/view')).default))
   registerCommand(program, (await import('./commands/status')).default)
   registerCommand(program, (await import('./commands/browser')).default)
+  registerCommand(program, (await import('./commands/view-serve')).default)
   registerCommand(program, (await import('./commands/studio')).default)
 
   registerGroup(program, {
@@ -152,6 +155,15 @@ export async function buildProgram(): Promise<Command> {
     ],
   })
 
+  registerGroup(program, {
+    name: 'session',
+    description: 'Locally recorded work sessions: list and DX-analyze them',
+    commands: [
+      (await import('./commands/session/list')).default,
+      (await import('./commands/session/analyze')).default,
+    ],
+  })
+
   registerGroup(program, {
     name: 'idp',
     description: 'Manage OpenID Connect identity providers',
@@ -169,7 +181,7 @@ export async function buildProgram(): Promise<Command> {
     `
 Command groups:
   Getting started  setup     (sign in, pick an instance, equip your workspace)
-  Kernel        ls, get, call, query, describe, token
+  Kernel        ls, get, mutate, call, query, describe, token
   Management    admin, instance, domain, identity, auth, idp, update
   Agent         browser   (drive the GUI via agent-browser)
   Studio        studio    (launch the local Domain Studio GUI for a workspace)
@@ -191,8 +203,9 @@ Examples:
   $ astrale instance bookmark staging --url https://kernel.example.com
   $ astrale instance create my-app
   $ astrale instance status staging
-  $ astrale token --audience dist.astrale.ai --ttl 3600
-  $ astrale query 'MATCH (n) RETURN n LIMIT 5'
+  $ astrale token --audience shell.astrale.ai --ttl 3600
+  $ astrale query / --depth 1
+  $ astrale query --cypher 'MATCH (n) RETURN n LIMIT 5'
 `,
   )
 

package/src/registry.ts

@@ -6,7 +6,7 @@ import type { CommandDefinition, CommandGroup } from './command'
  * Register a single command on a Commander program or subcommand.
  */
 export function registerCommand(parent: Command, def: CommandDefinition): void {
-  const cmd = parent.command(def.name).description(def.description)
+  const cmd = parent.command(def.name, { hidden: def.hidden ?? false }).description(def.description)
 
   if (def.summary) cmd.summary(def.summary)
 

package/src/setup/render.ts

@@ -101,9 +101,7 @@ export async function renderFinale(): Promise<void> {
   }
   console.log('')
   console.log(chalk.bold('Next'))
-  console.log(
-    `  ${chalk.cyan('astrale call /:dist.astrale.ai:class.Echo:echo message=hello')}  ${chalk.dim('— smoke test')}`,
-  )
+  console.log(`  ${chalk.cyan('astrale get @self --json')}  ${chalk.dim('— smoke test')}`)
   console.log(`  ${chalk.cyan('astrale browser')}  ${chalk.dim('— drive the GUI as your agent')}`)
   console.log(`  ${chalk.cyan('astrale --help')}  ${chalk.dim('— everything else')}`)
 }

package/src/setup/steps/instance.ts

@@ -3,7 +3,7 @@ import chalk from 'chalk'
 import type { SetupContext, SetupStep } from '../types'
 
 import { withAdminKernelClient } from '../../kernel/client'
-import { ADMIN_INSTANCE, type InstanceInfo } from '../../lib/admin-instance'
+import { adminInstanceMethod, type InstanceInfo } from '../../lib/admin-instance'
 import { normalizeInstanceKernelUrl, setActive, upsertManagedBookmark } from '../../lib/instance'
 import { readLocalStatus } from '../../lib/local-status'
 import { log, withSpinner } from '../../lib/log'
@@ -19,7 +19,7 @@ async function fetchManaged(ctx: SetupContext): Promise<InstanceInfo[]> {
       withAdminKernelClient(
         ctx.opts,
         async (client) =>
-          (await client.client.call(`${ADMIN_INSTANCE}/list`, {})) as InstanceInfo[],
+          (await client.client.call(adminInstanceMethod('list'), {})) as InstanceInfo[],
       ),
     )
   } catch {

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

@@ -0,0 +1,63 @@
+import { describe, expect, test } from 'bun:test'
+
+import type { TelemetryEvent } from '../types'
+
+import { commandHead, extractSignals, hasSignals } from '../gate'
+
+function ev(argv: string[], exitCode: number, errorName?: string): TelemetryEvent {
+  return {
+    v: 1,
+    ts: '2026-07-10T10:00:00.000Z',
+    argv,
+    exitCode,
+    durationMs: 10,
+    errorName,
+    cwd: '/w',
+    root: '/w',
+    surface: 'cli',
+  }
+}
+
+describe('commandHead', () => {
+  test('keeps up to two leading command tokens, stops at flags/values', () => {
+    expect(commandHead(['get', '/path', '-i', 'x'])).toBe('get /path')
+    expect(commandHead(['domain', 'install', './foo'])).toBe('domain install')
+    expect(commandHead(['status'])).toBe('status')
+    expect(commandHead(['--help'])).toBe('(bare)')
+    expect(commandHead(['call', 'k=v'])).toBe('call')
+  })
+})
+
+describe('extractSignals / hasSignals', () => {
+  test('failures grouped by command with error names', () => {
+    const s = extractSignals([
+      ev(['domain', 'install'], 1, 'AUTH_ERROR'),
+      ev(['domain', 'install'], 1, 'AUTH_ERROR'),
+      ev(['status'], 0),
+    ])
+    expect(s.failures).toEqual([
+      { command: 'domain install', count: 2, errorNames: ['AUTH_ERROR'] },
+    ])
+    expect(s.retries).toEqual([])
+    expect(hasSignals(s)).toBe(true)
+  })
+
+  test('3+ runs of one command is a retry smell even when green', () => {
+    const s = extractSignals([ev(['get', '/a'], 0), ev(['get', '/a'], 0), ev(['get', '/a'], 0)])
+    expect(s.retries).toEqual([{ command: 'get /a', count: 3 }])
+    expect(hasSignals(s)).toBe(true)
+  })
+
+  test('quiet session has no signals until a transcript is attached', () => {
+    const s = extractSignals([ev(['status'], 0), ev(['ls', '/'], 0)])
+    expect(hasSignals(s)).toBe(false)
+    s.harnessSessions = [
+      {
+        harness: 'claude-code',
+        transcriptPath: '/t.jsonl',
+        sizeBytes: 1,
+      },
+    ]
+    expect(hasSignals(s)).toBe(true)
+  })
+})

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

@@ -0,0 +1,110 @@
+import { afterEach, beforeAll, beforeEach, describe, expect, test } from 'bun:test'
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+import type { Finalizer } from '../recorder'
+import type { SessionInfo } from '../store'
+import type { TelemetryEvent } from '../types'
+
+// ASTRALE_HOME must be set before the store/paths singleton is first imported.
+process.env.ASTRALE_HOME = mkdtempSync(join(tmpdir(), 'astrale-tele-recorder-'))
+
+let beginInvocation: (argv: string[]) => Finalizer
+let eventsPath: (id: string) => string
+let listSessions: () => SessionInfo[]
+let sessionsRoot: () => string
+let configPath: string
+
+const SESSION = 'rec-test'
+
+let work: string
+let cwd0: string
+
+beforeAll(async () => {
+  const recorder = await import('../recorder')
+  const store = await import('../store')
+  beginInvocation = recorder.beginInvocation
+  eventsPath = store.eventsPath
+  listSessions = store.listSessions
+  sessionsRoot = store.sessionsRoot
+  configPath = join(process.env.ASTRALE_HOME!, 'config.json')
+})
+
+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 })
+  rmSync(configPath, { force: true })
+  delete process.env.ASTRALE_TELEMETRY
+  process.env.ASTRALE_SESSION = SESSION
+  work = mkdtempSync(join(tmpdir(), 'astrale-tele-recwork-'))
+  cwd0 = process.cwd()
+  process.chdir(work)
+})
+
+afterEach(() => {
+  process.chdir(cwd0)
+  rmSync(work, { recursive: true, force: true })
+})
+
+function readEvents(id: string): TelemetryEvent[] {
+  return readFileSync(eventsPath(id), 'utf-8')
+    .split('\n')
+    .filter(Boolean)
+    .map((l) => JSON.parse(l) as TelemetryEvent)
+}
+
+describe('beginInvocation', () => {
+  test('appends one valid, parseable event with redacted argv', () => {
+    const cwd = process.cwd()
+    const finalize = beginInvocation(['node', 'astrale', 'get', '--token', 'abc', 'x'])
+    finalize(0)
+
+    const events = readEvents(SESSION)
+    expect(events).toHaveLength(1)
+    const [e] = events
+    expect(e.v).toBe(1)
+    expect(e.surface).toBe('cli')
+    expect(e.exitCode).toBe(0)
+    expect(e.argv).toEqual(['get', '--token', '<redacted>', 'x'])
+    expect(e.cwd).toBe(cwd)
+    expect(e.root).toBe(cwd)
+    expect(typeof e.ts).toBe('string')
+    expect(typeof e.durationMs).toBe('number')
+    expect('errorName' in e).toBe(false)
+  })
+
+  test('records exitCode and errorName on failure', () => {
+    beginInvocation(['node', 'astrale', 'call', 'foo'])(1, 'AuthError')
+    const [e] = readEvents(SESSION)
+    expect(e.exitCode).toBe(1)
+    expect(e.errorName).toBe('AuthError')
+  })
+
+  test('appends a second line on a second invocation', () => {
+    beginInvocation(['node', 'astrale', 'query'])(0)
+    beginInvocation(['node', 'astrale', 'whoami'])(0)
+    expect(readEvents(SESSION)).toHaveLength(2)
+  })
+
+  test('writes nothing for help/version-only invocations', () => {
+    beginInvocation(['node', 'astrale', '--help'])(0)
+    beginInvocation(['node', 'astrale', '--version'])(0)
+    beginInvocation(['node', 'astrale'])(0)
+    expect(listSessions()).toHaveLength(0)
+  })
+
+  test('writes nothing when disabled via ASTRALE_TELEMETRY', () => {
+    process.env.ASTRALE_TELEMETRY = '0'
+    beginInvocation(['node', 'astrale', 'get', 'x'])(0)
+    expect(listSessions()).toHaveLength(0)
+    expect(existsSync(eventsPath(SESSION))).toBe(false)
+  })
+
+  test('writes nothing when disabled via config telemetry.enabled=false', () => {
+    writeFileSync(configPath, JSON.stringify({ telemetry: { enabled: false } }))
+    beginInvocation(['node', 'astrale', 'get', 'x'])(0)
+    expect(listSessions()).toHaveLength(0)
+  })
+})

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

@@ -0,0 +1,79 @@
+import { describe, expect, test } from 'bun:test'
+
+import { redactArgv } from '../redact'
+
+describe('redactArgv', () => {
+  test('redacts the value following a secret flag', () => {
+    expect(redactArgv(['--token', 'abc123', '--json'])).toEqual(['--token', '<redacted>', '--json'])
+  })
+
+  test('matches secret substrings in flag names, case-insensitively', () => {
+    expect(redactArgv(['--api-Token', 's', '--Bearer', 'b', '--jwk', 'k'])).toEqual([
+      '--api-Token',
+      '<redacted>',
+      '--Bearer',
+      '<redacted>',
+      '--jwk',
+      '<redacted>',
+    ])
+  })
+
+  test('redacts the value part of inline k=v secret args', () => {
+    expect(redactArgv(['--secret=hunter2', 'password=p', '--verbose'])).toEqual([
+      '--secret=<redacted>',
+      'password=<redacted>',
+      '--verbose',
+    ])
+  })
+
+  test('leaves non-secret flags and their values intact', () => {
+    expect(redactArgv(['get', '--depth', '3', '--format=json'])).toEqual([
+      'get',
+      '--depth',
+      '3',
+      '--format=json',
+    ])
+  })
+
+  test('truncates any arg longer than 200 chars to 200 + ellipsis', () => {
+    const long = 'x'.repeat(300)
+    const [only] = redactArgv([long])
+    expect(only).toBe('x'.repeat(200) + '…')
+    expect([...only].length).toBe(201)
+  })
+
+  test('a secret value is redacted before length matters', () => {
+    expect(redactArgv(['--password', 'y'.repeat(500)])).toEqual(['--password', '<redacted>'])
+  })
+
+  test('caps the array at 40 items with a …+N marker', () => {
+    const args = Array.from({ length: 45 }, (_, i) => `a${i}`)
+    const out = redactArgv(args)
+    expect(out.length).toBe(41)
+    expect(out.slice(0, 40)).toEqual(args.slice(0, 40))
+    expect(out[40]).toBe('…+5')
+  })
+
+  test('does not cap at exactly 40 items', () => {
+    const args = Array.from({ length: 40 }, (_, i) => `a${i}`)
+    expect(redactArgv(args)).toEqual(args)
+  })
+
+  test('a trailing secret flag with no value does not throw', () => {
+    expect(redactArgv(['call', '--token'])).toEqual(['call', '--token'])
+  })
+})
+
+describe('secret-shaped values', () => {
+  test('positional JWT is redacted wherever it appears', () => {
+    const jwt =
+      'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.dozjgNryP4J3jVmNHl0w5N_XgL0n3I9PlFUP0THsR8U'
+    expect(redactArgv(['call', '/x::y', jwt])).toEqual(['call', '/x::y', '<redacted>'])
+    expect(redactArgv(['call', `body=Bearer ${jwt}`])[1]).toBe('body=Bearer <redacted>')
+  })
+  test('sk- style api key is redacted, plain paths are not', () => {
+    expect(redactArgv(['x', 'sk-abcdefghijklmnop1234'])).toEqual(['x', '<redacted>'])
+    const p = '/Users/someone/Documents/astrale/workspace/cli/src/telemetry/adapters/index.ts'
+    expect(redactArgv([p])).toEqual([p])
+  })
+})

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

@@ -0,0 +1,166 @@
+import { afterEach, beforeAll, beforeEach, describe, expect, test } from 'bun:test'
+import {
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  utimesSync,
+  writeFileSync,
+} from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+import type { ResolvedSession } from '../session'
+import type { SessionMeta } from '../types'
+
+/** Seed an ambient session on disk with a chosen id + last-activity age. */
+function seedAmbient(id: string, root: string, ageMs: number): void {
+  mkdirSync(sessionDir(id), { recursive: true })
+  const meta: SessionMeta = { id, root, explicit: false, createdAt: new Date().toISOString() }
+  writeFileSync(metaPath(id), JSON.stringify(meta))
+  writeFileSync(eventsPath(id), '{}\n')
+  const when = new Date(Date.now() - ageMs)
+  utimesSync(eventsPath(id), when, when)
+}
+
+// Set ASTRALE_HOME before the store/paths singleton is first evaluated (below,
+// via dynamic import). All on-disk access goes through the store helpers so it
+// stays consistent whichever home the singleton captured.
+process.env.ASTRALE_HOME = mkdtempSync(join(tmpdir(), 'astrale-tele-session-'))
+
+let resolveSession: (cwd: string) => ResolvedSession
+let ensureSession: (cwd: string) => ResolvedSession
+let eventsPath: (id: string) => string
+let metaPath: (id: string) => string
+let sessionDir: (id: string) => string
+let sessionsRoot: () => string
+let IDLE_WINDOW_MS: number
+
+let work: string
+
+beforeAll(async () => {
+  const session = await import('../session')
+  const store = await import('../store')
+  resolveSession = session.resolveSession
+  ensureSession = session.ensureSession
+  eventsPath = store.eventsPath
+  metaPath = store.metaPath
+  sessionDir = store.sessionDir
+  sessionsRoot = store.sessionsRoot
+  IDLE_WINDOW_MS = store.IDLE_WINDOW_MS
+})
+
+beforeEach(() => {
+  if (!sessionsRoot().startsWith(tmpdir())) throw new Error('refusing to clean a non-tmp home')
+  rmSync(sessionsRoot(), { recursive: true, force: true })
+  delete process.env.ASTRALE_SESSION
+  work = mkdtempSync(join(tmpdir(), 'astrale-tele-work-'))
+})
+
+afterEach(() => {
+  rmSync(work, { recursive: true, force: true })
+})
+
+describe('resolveSession — ambient', () => {
+  test('reuses an open ambient session bucketed to the same root', () => {
+    // An old-stamp id proves reuse: a fresh mint would carry the current minute.
+    const existing = 'amb-deadbeef-200001010000'
+    seedAmbient(existing, work, 5 * 60_000)
+
+    const r = resolveSession(work)
+
+    expect(r).toEqual({ id: existing, root: work, explicit: false })
+  })
+
+  test('mints a fresh session once the previous one is idle', () => {
+    const existing = 'amb-deadbeef-200001010000'
+    seedAmbient(existing, work, IDLE_WINDOW_MS + 60_000)
+
+    const r = resolveSession(work)
+
+    expect(r.id).not.toBe(existing)
+    expect(r.explicit).toBe(false)
+    expect(r.id).toMatch(/^amb-[0-9a-f]{8}-\d{12}$/)
+  })
+
+  test('does not reuse a session bucketed to a different root', () => {
+    const existing = 'amb-deadbeef-200001010000'
+    seedAmbient(existing, work, 5 * 60_000)
+
+    const other = mkdtempSync(join(tmpdir(), 'astrale-tele-other-'))
+    try {
+      expect(resolveSession(other).id).not.toBe(existing)
+    } finally {
+      rmSync(other, { recursive: true, force: true })
+    }
+  })
+
+  test('ensureSession creates then reuses one session across calls', () => {
+    const first = ensureSession(work)
+    const second = ensureSession(work)
+    expect(second.id).toBe(first.id)
+    expect(first.id).toMatch(/^amb-[0-9a-f]{8}-\d{12}$/)
+  })
+})
+
+describe('resolveSession — root bucketing', () => {
+  test('buckets by the nearest .git ancestor, not cwd', () => {
+    mkdirSync(join(work, '.git'), { recursive: true })
+    const deep = join(work, 'sub', 'deep')
+    mkdirSync(deep, { recursive: true })
+
+    expect(resolveSession(deep).root).toBe(work)
+  })
+
+  test('falls back to cwd when there is no git root', () => {
+    expect(resolveSession(work).root).toBe(work)
+  })
+})
+
+describe('resolveSession — explicit ASTRALE_SESSION', () => {
+  test('honors an explicit id, sanitizing unsafe chars and capping at 64', () => {
+    process.env.ASTRALE_SESSION = 'my/weird:sess!!'
+    const r = resolveSession(work)
+    expect(r).toEqual({ id: 'myweirdsess', root: work, explicit: true })
+
+    process.env.ASTRALE_SESSION = 'a'.repeat(80)
+    expect(resolveSession(work).id).toBe('a'.repeat(64))
+  })
+
+  test('falls through to ambient when the id is empty after sanitizing', () => {
+    process.env.ASTRALE_SESSION = '///'
+    const r = resolveSession(work)
+    expect(r.explicit).toBe(false)
+    expect(r.id).toMatch(/^amb-/)
+  })
+})
+
+describe('ensureSession', () => {
+  test('creates the session dir and a readable meta.json once', () => {
+    const r = ensureSession(work)
+
+    expect(existsSync(metaPath(r.id))).toBe(true)
+    const meta = JSON.parse(readFileSync(metaPath(r.id), 'utf-8')) as SessionMeta
+    expect(meta.id).toBe(r.id)
+    expect(meta.root).toBe(work)
+    expect(meta.explicit).toBe(false)
+    expect(typeof meta.createdAt).toBe('string')
+  })
+})
+
+describe('analyzed sessions are never reused', () => {
+  test('an open ambient session with an .analyzed marker gets a fresh mint', async () => {
+    const { markerPath } = await import('../store')
+    const root = join(work, 'analyzed-root')
+    mkdirSync(root, { recursive: true })
+    seedAmbient('amb-analyzed-open', root, 0) // fresh mtime → open
+    writeFileSync(
+      markerPath('amb-analyzed-open'),
+      JSON.stringify({ analyzedAt: new Date().toISOString(), outcome: 'reported' }),
+    )
+    const resolved = resolveSession(root)
+    expect(resolved.id).not.toBe('amb-analyzed-open')
+    expect(resolved.id.startsWith('amb-')).toBe(true)
+  })
+})

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

@@ -0,0 +1,49 @@
+import { beforeAll, 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'
+
+// Set the home before the paths singleton is captured (dynamic imports below).
+process.env.ASTRALE_HOME = mkdtempSync(join(tmpdir(), 'astrale-tele-trigger-'))
+
+let maybeTriggerAnalysis: (argv: string[]) => void
+let sessionDir: (id: string) => string
+
+beforeAll(async () => {
+  ;({ maybeTriggerAnalysis } = await import('../trigger'))
+  ;({ sessionDir } = await import('../store'))
+  // Sibling test files mutate shared state (env vars, and recorder.test.ts
+  // leaves a telemetry-disabled config.json in the shared home) — own it here.
+  delete process.env.ASTRALE_TELEMETRY
+  delete process.env.ASTRALE_TELEMETRY_NO_TRIGGER
+  const { CONFIG_PATH } = await import('../../lib/paths')
+  rmSync(CONFIG_PATH, { force: true })
+})
+
+function seed(id: string, ageMs: number, analyzed: boolean): void {
+  const dir = sessionDir(id)
+  mkdirSync(dir, { recursive: true })
+  writeFileSync(join(dir, 'meta.json'), JSON.stringify({ id, root: '/w', explicit: false }))
+  writeFileSync(join(dir, 'events.jsonl'), '{}\n')
+  if (analyzed) {
+    writeFileSync(
+      join(dir, '.analyzed'),
+      JSON.stringify({ analyzedAt: new Date().toISOString(), outcome: 'reported' }),
+    )
+  }
+  const when = new Date(Date.now() - ageMs)
+  utimesSync(join(dir, 'events.jsonl'), when, when)
+}
+
+describe('opportunistic GC', () => {
+  test('removes analyzed sessions past retention, keeps recent and unanalyzed ones', () => {
+    const DAY = 24 * 60 * 60 * 1000
+    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)
+  })
+})