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

package/src/state/__tests__/paths.test.ts

@@ -20,6 +20,7 @@ describe('state paths', () => {
     expect(explicit.home).toBe('/explicit/home')
     expect(explicit.keys).toBe('/environment/keys')
     expect(explicit.config).toBe(join('/explicit/home', 'config.json'))
+    expect(explicit.sessionRoutes).toBe(join('/explicit/home', 'session', 'routes.json'))
     expect(inherited.home).toBe('/environment/home')
     expect(inherited.keys).toBe('/environment/keys')
     expect(Object.isFrozen(explicit)).toBe(true)

package/src/state/__tests__/session-routes.test.ts

@@ -0,0 +1,138 @@
+import type { SessionRouteArtifact } from '@astrale-os/sdk/client/session'
+
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test'
+import { access, mkdir, mkdtemp, readFile, rm, stat, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+import { FileSessionRouteStore } from '../session-routes'
+
+let directory: string
+let path: string
+
+beforeEach(async () => {
+  directory = await mkdtemp(join(tmpdir(), 'astrale-session-routes-'))
+  path = join(directory, 'private', 'routes.json')
+})
+
+afterEach(async () => {
+  await rm(directory, { recursive: true, force: true })
+})
+
+describe('session route file store', () => {
+  test('round-trips the Kernel-owned artifact under owner-private filesystem modes', async () => {
+    const artifact: SessionRouteArtifact = { version: 1, entries: {} }
+    const store = new FileSessionRouteStore(path)
+
+    store.write(artifact)
+
+    expect(store.read()).toEqual(artifact)
+    expect((await stat(path)).mode & 0o777).toBe(0o600)
+    expect((await stat(join(directory, 'private'))).mode & 0o777).toBe(0o700)
+    expect(await readFile(path, 'utf8')).toBe('{"version":1,"entries":{}}\n')
+
+    store.clear()
+    await expect(access(path)).rejects.toThrow()
+    expect(() => store.clear()).not.toThrow()
+  })
+
+  test('leaves malformed representation recovery to Kernel Client as a cold miss', async () => {
+    await mkdir(join(directory, 'private'))
+    await writeFile(path, '{invalid')
+    const fixture = join(import.meta.dir, 'fixtures', 'session-route-process.ts')
+
+    expect(await runFixture(fixture, path)).toEqual({
+      value: 'done',
+      sourceAttempts: 1,
+      destinationAttempts: 1,
+    })
+    expect(JSON.parse(await readFile(path, 'utf8'))).toMatchObject({ version: 1 })
+  })
+
+  test('reuses Kernel-admitted routing state in a separate operating-system process', async () => {
+    const routePath = join(directory, 'private', 'routes.json')
+    const fixture = join(import.meta.dir, 'fixtures', 'session-route-process.ts')
+
+    const first = await runFixture(fixture, routePath)
+    const second = await runFixture(fixture, routePath)
+
+    expect(first).toEqual({ value: 'done', sourceAttempts: 1, destinationAttempts: 1 })
+    expect(second).toEqual({ value: 'done', sourceAttempts: 0, destinationAttempts: 1 })
+  })
+
+  test('publishes only complete owner-private artifacts under concurrent process writers', async () => {
+    const routePath = join(directory, 'private', 'routes.json')
+    const fixture = join(import.meta.dir, 'fixtures', 'session-route-process.ts')
+
+    const results = await Promise.all(
+      Array.from({ length: 8 }, () => runFixture(fixture, routePath)),
+    )
+    expect(results).toHaveLength(8)
+    expect(results.every((result) => result.destinationAttempts === 1)).toBe(true)
+    expect(JSON.parse(await readFile(routePath, 'utf8'))).toMatchObject({ version: 1 })
+    expect((await stat(routePath)).mode & 0o777).toBe(0o600)
+    expect(await runFixture(fixture, routePath)).toEqual({
+      value: 'done',
+      sourceAttempts: 0,
+      destinationAttempts: 1,
+    })
+  })
+
+  test('auth logout clears every persisted bearer cache through the real CLI command', async () => {
+    const routePath = join(directory, 'session', 'routes.json')
+    const exchangePath = join(directory, 'exchange', 'credentials.json')
+    await mkdir(join(directory, 'session'), { recursive: true })
+    await mkdir(join(directory, 'exchange'), { recursive: true })
+    await writeFile(routePath, '{"version":1,"entries":{"confidential":{}}}\n')
+    await writeFile(
+      exchangePath,
+      '{"version":2,"entries":{"confidential":{"credential":"bearer"}}}\n',
+    )
+
+    const child = Bun.spawn(
+      [
+        process.execPath,
+        join(import.meta.dir, '../../..', 'bin', 'astrale.ts'),
+        'auth',
+        'logout',
+        '--all',
+        '--json',
+      ],
+      {
+        env: { ...process.env, ASTRALE_HOME: directory },
+        stdout: 'pipe',
+        stderr: 'pipe',
+      },
+    )
+    const [exitCode, stdout, stderr] = await Promise.all([
+      child.exited,
+      new Response(child.stdout).text(),
+      new Response(child.stderr).text(),
+    ])
+
+    expect(exitCode, stderr).toBe(0)
+    expect(JSON.parse(stdout)).toEqual({ cleared: [] })
+    await expect(access(routePath)).rejects.toThrow()
+    expect(JSON.parse(await readFile(exchangePath, 'utf8'))).toEqual({ version: 2, entries: {} })
+  })
+})
+
+interface FixtureResult {
+  readonly value: string
+  readonly sourceAttempts: number
+  readonly destinationAttempts: number
+}
+
+async function runFixture(fixture: string, routePath: string): Promise<FixtureResult> {
+  const child = Bun.spawn([process.execPath, fixture, routePath], {
+    stdout: 'pipe',
+    stderr: 'pipe',
+  })
+  const [exitCode, stdout, stderr] = await Promise.all([
+    child.exited,
+    new Response(child.stdout).text(),
+    new Response(child.stderr).text(),
+  ])
+  expect(exitCode, stderr).toBe(0)
+  return JSON.parse(stdout) as FixtureResult
+}

package/src/state/exchange-credentials.ts

@@ -5,24 +5,28 @@ import { dirname } from 'node:path'
 import { atomicWrite, withFileLock } from './files'
 import { EXCHANGE_CREDENTIALS_PATH } from './paths'
 
-const VERSION = 1
+const VERSION = 2
 const MINIMUM_REMAINING_SECONDS = 30
 
 export namespace exchange {
   export interface Artifact {
-    readonly version: 1
+    readonly version: 2
     readonly entries: Record<string, Entry>
   }
 
   export interface Key {
     readonly kernelIssuer: string
     readonly domainIssuer: string
-    readonly user: string
+    readonly sourceIssuer: string
+    readonly sourceSubject: string
   }
 
   export interface Entry {
     readonly credential: string
     readonly expiresAt: number
+    readonly user: string
+    readonly sourceIssuer: string
+    readonly sourceSubject: string
   }
 }
 
@@ -140,11 +144,15 @@ function validEntry(
   if (
     entry === null ||
     typeof entry !== 'object' ||
-    Reflect.ownKeys(entry).length !== 2 ||
+    Reflect.ownKeys(entry).length !== 5 ||
     typeof entry.credential !== 'string' ||
     entry.credential.length === 0 ||
     !Number.isSafeInteger(entry.expiresAt) ||
-    entry.expiresAt - now < minimumRemaining
+    entry.expiresAt - now < minimumRemaining ||
+    typeof entry.user !== 'string' ||
+    entry.user.length === 0 ||
+    entry.sourceIssuer !== key.sourceIssuer ||
+    entry.sourceSubject !== key.sourceSubject
   ) {
     return false
   }
@@ -178,7 +186,7 @@ function validEntry(
       inspected.claims.exp === entry.expiresAt &&
       !Object.hasOwn(inspected.claims, 'delegation') &&
       proof.iss === key.kernelIssuer &&
-      proof.sub === key.user &&
+      proof.sub === entry.user &&
       proof.aud === key.kernelIssuer
     )
   } catch {
@@ -187,7 +195,7 @@ function validEntry(
 }
 
 function encodeKey(key: exchange.Key): string {
-  return JSON.stringify([key.kernelIssuer, key.domainIssuer, key.user])
+  return JSON.stringify([key.kernelIssuer, key.domainIssuer, key.sourceIssuer, key.sourceSubject])
 }
 
 function decodeKey(input: string): exchange.Key | undefined {
@@ -195,12 +203,17 @@ function decodeKey(input: string): exchange.Key | undefined {
     const value = JSON.parse(input) as unknown
     if (
       !Array.isArray(value) ||
-      value.length !== 3 ||
+      value.length !== 4 ||
       value.some((part) => typeof part !== 'string' || part.length === 0)
     ) {
       return undefined
     }
-    return { kernelIssuer: value[0]!, domainIssuer: value[1]!, user: value[2]! }
+    return {
+      kernelIssuer: value[0]!,
+      domainIssuer: value[1]!,
+      sourceIssuer: value[2]!,
+      sourceSubject: value[3]!,
+    }
   } catch {
     return undefined
   }

package/src/state/files.ts

@@ -1,4 +1,13 @@
 import { randomUUID } from 'node:crypto'
+import {
+  closeSync,
+  fsyncSync,
+  mkdirSync,
+  openSync,
+  renameSync,
+  unlinkSync,
+  writeFileSync,
+} from 'node:fs'
 import { mkdir, open, readFile, rename, stat, unlink } from 'node:fs/promises'
 import { dirname } from 'node:path'
 
@@ -30,6 +39,38 @@ export async function atomicWrite(path: string, data: string): Promise<void> {
   }
 }
 
+/** Atomically publish one complete private state file for synchronous consumer capabilities. */
+export function atomicWriteSync(path: string, data: string): void {
+  const directory = dirname(path)
+  const temporary = `${path}.${randomUUID()}.tmp`
+  mkdirSync(directory, { recursive: true })
+
+  let descriptor: number | undefined
+  try {
+    descriptor = openSync(temporary, 'wx', 0o600)
+    writeFileSync(descriptor, data)
+    fsyncSync(descriptor)
+    closeSync(descriptor)
+    descriptor = undefined
+    renameSync(temporary, path)
+
+    const directoryDescriptor = openSync(directory, 'r')
+    try {
+      fsyncSync(directoryDescriptor)
+    } finally {
+      closeSync(directoryDescriptor)
+    }
+  } catch (error) {
+    if (descriptor !== undefined) closeSync(descriptor)
+    try {
+      unlinkSync(temporary)
+    } catch {
+      // The temporary file was either never created or was already renamed.
+    }
+    throw error
+  }
+}
+
 export interface FileLockOptions {
   readonly pollIntervalMs?: number
   readonly staleAfterMs?: number

package/src/state/index.ts

@@ -1,4 +1,4 @@
-export { atomicWrite, withFileLock } from './files'
+export { atomicWrite, atomicWriteSync, withFileLock } from './files'
 export type { FileLockOptions } from './files'
 export { ExchangeCredentialCache } from './exchange-credentials'
 export type { exchange } from './exchange-credentials'
@@ -23,7 +23,9 @@ export {
   INSTALL_PATH,
   INSTANCES_PATH,
   KEYS_DIR,
+  SESSION_ROUTES_PATH,
   createPaths,
   paths,
 } from './paths'
 export type { PathEnvironment, Paths } from './paths'
+export { FileSessionRouteStore, SESSION_ROUTE_STORE } from './session-routes'

package/src/state/paths.ts

@@ -18,6 +18,7 @@ export interface Paths {
   readonly idps: string
   readonly idpSessionsDir: string
   readonly exchangeCredentials: string
+  readonly sessionRoutes: string
   idpDir(name: string): string
   idpSession(identityName: string): string
 }
@@ -43,6 +44,7 @@ export function createPaths(home?: string, environment?: PathEnvironment): Paths
     idps: join(idpsDir, 'index.json'),
     idpSessionsDir,
     exchangeCredentials: join(base, 'exchange', 'credentials.json'),
+    sessionRoutes: join(base, 'session', 'routes.json'),
     idpDir: (name: string) => join(idpsDir, name),
     idpSession: (identityName: string) => join(idpSessionsDir, `${identityName}.json`),
   })
@@ -59,3 +61,4 @@ export const INSTANCES_PATH = paths.instances
 export const IDPS_PATH = paths.idps
 export const IDP_SESSIONS_DIR = paths.idpSessionsDir
 export const EXCHANGE_CREDENTIALS_PATH = paths.exchangeCredentials
+export const SESSION_ROUTES_PATH = paths.sessionRoutes

package/src/state/session-routes.ts

@@ -0,0 +1,34 @@
+import type { SessionRouteArtifact, SessionRouteStore } from '@astrale-os/sdk/client/session'
+
+import { chmodSync, mkdirSync, readFileSync, unlinkSync } from 'node:fs'
+import { dirname } from 'node:path'
+
+import { atomicWriteSync } from './files'
+import { SESSION_ROUTES_PATH } from './paths'
+
+/** CLI filesystem representation for Kernel Client's admitted confidential route artifact. */
+export class FileSessionRouteStore implements SessionRouteStore {
+  constructor(private readonly path = SESSION_ROUTES_PATH) {}
+
+  read(): unknown {
+    return JSON.parse(readFileSync(this.path, 'utf8')) as unknown
+  }
+
+  write(artifact: SessionRouteArtifact): void {
+    const directory = dirname(this.path)
+    mkdirSync(directory, { recursive: true, mode: 0o700 })
+    chmodSync(directory, 0o700)
+    atomicWriteSync(this.path, `${JSON.stringify(artifact)}\n`)
+    chmodSync(this.path, 0o600)
+  }
+
+  clear(): void {
+    try {
+      unlinkSync(this.path)
+    } catch (error) {
+      if ((error as { readonly code?: unknown }).code !== 'ENOENT') throw error
+    }
+  }
+}
+
+export const SESSION_ROUTE_STORE = Object.freeze(new FileSessionRouteStore())

package/src/telemetry/__tests__/analyze-log.test.ts

@@ -0,0 +1,38 @@
+import { describe, expect, test } from 'bun:test'
+
+import { clampLog } from '../analyze'
+
+describe('clampLog', () => {
+  test('short output is written through untouched', () => {
+    const json = '{"is_error":false,"num_turns":3}'
+    expect(clampLog(json)).toBe(json)
+  })
+
+  test('output at exactly the limit is not clamped', () => {
+    const text = 'x'.repeat(1000)
+    expect(clampLog(text, 1000)).toBe(text)
+  })
+
+  test('oversized output keeps its head and its tail', () => {
+    // The JSON envelope opens at the top; a stack or error message closes at
+    // the bottom. Both must survive; the middle is what nobody reads.
+    const text = `HEAD${'x'.repeat(50_000)}TAIL`
+    const clamped = clampLog(text, 1000)
+    expect(clamped.startsWith('HEAD')).toBe(true)
+    expect(clamped.endsWith('TAIL')).toBe(true)
+    expect(clamped).toContain('bytes elided')
+  })
+
+  test('the result stays within a small constant of the limit', () => {
+    const clamped = clampLog('y'.repeat(10_000_000), 4096)
+    // head + tail + the elision marker, never the input.
+    expect(clamped.length).toBeLessThan(4096 + 128)
+  })
+
+  test('the elision count reports what was actually dropped', () => {
+    const clamped = clampLog('z'.repeat(10_000), 1000)
+    const elided = Number(/… (\d+) bytes elided …/u.exec(clamped)?.[1])
+    const kept = clamped.length - `\n… ${elided} bytes elided …\n`.length
+    expect(elided + kept).toBe(10_000)
+  })
+})

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

@@ -13,6 +13,7 @@ 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 tidySession: (id: string, options?: { keepPrompt?: boolean }) => string[]
 let scanSessions: () => SessionScan[]
 let sessionDir: (id: string) => string
 let sessionBytes: (id: string) => number
@@ -22,7 +23,7 @@ const DAY = 24 * 60 * 60 * 1000
 const BUDGET: RetentionBudget = { maxAgeMs: 30 * DAY, maxBytes: 10_000 }
 
 beforeAll(async () => {
-  ;({ sweepByAge, sweepToBudget, sweepStore } = await import('../retention'))
+  ;({ sweepByAge, sweepToBudget, sweepStore, tidySession } = await import('../retention'))
   ;({ scanSessions, sessionDir, sessionBytes, sessionsRoot } = await import('../store'))
 })
 
@@ -178,3 +179,89 @@ describe('sweepStore', () => {
     expect(sweepStore().removed).toEqual(['two-days-old'])
   })
 })
+
+describe('sweepStore tidying', () => {
+  test('tidies analyzed survivors, so the bound applies to sessions already on disk', () => {
+    seed('store-tidy', { ageMs: DAY, analyzed: true, bytes: 100 })
+    writeFileSync(join(sessionDir('store-tidy'), 'calls.txt'), 'x'.repeat(50_000))
+
+    sweepStore({ budget: BUDGET })
+
+    expect(existsSync(join(sessionDir('store-tidy'), 'calls.txt'))).toBe(false)
+    expect(existsSync(join(sessionDir('store-tidy'), 'report.md'))).toBe(true)
+  })
+
+  test('an unanalyzed session is left alone — its analyzer may still be running', () => {
+    seed('store-pending', { ageMs: DAY, bytes: 100 })
+    writeFileSync(join(sessionDir('store-pending'), 'analyzer-prompt.md'), '# in flight')
+
+    sweepStore({ budget: BUDGET })
+
+    expect(existsSync(join(sessionDir('store-pending'), 'analyzer-prompt.md'))).toBe(true)
+  })
+
+  test('scratch is tidied before the size bound is measured, not after', () => {
+    // 60 KB of scratch against a 10 KB budget: tidying first brings the store
+    // back under on its own, so nothing should be evicted.
+    seed('store-bloated', { ageMs: DAY, analyzed: true, bytes: 100 })
+    writeFileSync(join(sessionDir('store-bloated'), 'calls.txt'), 'x'.repeat(60_000))
+
+    expect(sweepStore({ budget: BUDGET }).removed).toEqual([])
+    expect(existsSync(sessionDir('store-bloated'))).toBe(true)
+  })
+
+  test('a failed analysis keeps its prompt through the sweep', () => {
+    const dir = sessionDir('store-failed')
+    seed('store-failed', { ageMs: DAY, analyzed: true })
+    writeFileSync(
+      join(dir, '.analyzed'),
+      JSON.stringify({ analyzedAt: new Date().toISOString(), outcome: 'error', note: 'boom' }),
+    )
+    writeFileSync(join(dir, 'analyzer-prompt.md'), '# what we asked')
+
+    sweepStore({ budget: BUDGET })
+
+    expect(existsSync(join(dir, 'analyzer-prompt.md'))).toBe(true)
+  })
+})
+
+describe('tidySession', () => {
+  test('removes what the analyzer left behind, keeps the durable artifacts', () => {
+    const dir = sessionDir('tidy-scratch')
+    seed('tidy-scratch', { ageMs: DAY, analyzed: true, bytes: 100 })
+    writeFileSync(join(dir, 'analyzer.log'), 'exit 0')
+    writeFileSync(join(dir, 'analyzer-prompt.md'), '# prompt')
+    // Scratch: the analyzer runs with Write in here and answers to nobody.
+    writeFileSync(join(dir, 'calls.txt'), 'x'.repeat(50_000))
+    mkdirSync(join(dir, 'notes'), { recursive: true })
+    writeFileSync(join(dir, 'notes', 'draft.md'), 'scratch')
+
+    const removed = tidySession('tidy-scratch')
+
+    expect(removed.sort()).toEqual(['analyzer-prompt.md', 'calls.txt', 'notes'])
+    for (const keep of ['meta.json', 'events.jsonl', 'report.md', '.analyzed', 'analyzer.log']) {
+      expect(existsSync(join(dir, keep))).toBe(true)
+    }
+    expect(existsSync(join(dir, 'notes'))).toBe(false)
+  })
+
+  test('keepPrompt spares the prompt — the failing case is when it matters', () => {
+    const dir = sessionDir('tidy-failed')
+    seed('tidy-failed', { ageMs: DAY, analyzed: true })
+    writeFileSync(join(dir, 'analyzer-prompt.md'), '# prompt')
+    writeFileSync(join(dir, 'scratch.json'), '{}')
+
+    expect(tidySession('tidy-failed', { keepPrompt: true })).toEqual(['scratch.json'])
+    expect(existsSync(join(dir, 'analyzer-prompt.md'))).toBe(true)
+  })
+
+  test('a session with nothing to tidy is left exactly as it was', () => {
+    seed('tidy-clean', { ageMs: DAY, analyzed: true, bytes: 10 })
+    expect(tidySession('tidy-clean')).toEqual([])
+    expect(existsSync(sessionDir('tidy-clean'))).toBe(true)
+  })
+
+  test('a missing session directory is a no-op, not an error', () => {
+    expect(tidySession('tidy-absent')).toEqual([])
+  })
+})

package/src/telemetry/analyze.ts

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

package/src/telemetry/retention.ts

@@ -15,13 +15,52 @@
  * 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 Dirent, readdirSync, rmSync } from 'node:fs'
+import { join } from 'node:path'
 
 import type { RetentionBudget } from './settings'
 import type { SessionScan } from './store'
 
 import { retentionBudget } from './settings'
-import { scanSessions, sessionBytes, sessionDir } from './store'
+import { readMarker, scanSessions, sessionBytes, sessionDir } from './store'
+
+/** What an analyzed session is allowed to keep. Everything else is scratch: the
+ *  analyzer runs with Write inside the session directory, so without this a
+ *  session's size is whatever the agent felt like writing — one here was left
+ *  holding a 462 KB calls.txt, a quarter of the entire store. */
+const KEEP = new Set(['meta.json', 'events.jsonl', 'report.md', '.analyzed', 'analyzer.log'])
+
+/** Reproducible from events.jsonl in the normal case, and dropped there — but
+ *  it is the only record of what the analyzer was actually asked when it
+ *  failed, which is exactly when someone will want to look. */
+const ANALYZER_PROMPT = 'analyzer-prompt.md'
+
+/**
+ * Reduce one session to its durable artifacts, called once the analyzer has
+ * written its marker. This is what makes a session's footprint a property of
+ * the CLI rather than of whatever the agent decided to leave behind.
+ */
+export function tidySession(id: string, options: { keepPrompt?: boolean } = {}): string[] {
+  const dir = sessionDir(id)
+  let entries: Dirent[]
+  try {
+    entries = readdirSync(dir, { withFileTypes: true })
+  } catch {
+    return []
+  }
+  const removed: string[] = []
+  for (const entry of entries) {
+    if (KEEP.has(entry.name)) continue
+    if (entry.name === ANALYZER_PROMPT && options.keepPrompt === true) continue
+    try {
+      rmSync(join(dir, entry.name), { recursive: true, force: true })
+      removed.push(entry.name)
+    } catch {
+      /* best effort — tidying must never fail the analysis it follows */
+    }
+  }
+  return removed
+}
 
 /** Cap for the age sweep on the CLI's critical path, so a large backlog drains
  *  over several runs instead of stalling one command on hundreds of rmSync. */
@@ -121,9 +160,17 @@ export function sweepStore(options: SweepOptions = {}): SweepResult {
   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 },
-  )
+  const survivors = sessions.filter((session) => !gone.has(session.id))
+
+  // Tidy before measuring. Doing it after would let a session be evicted for
+  // holding scratch that was about to be deleted anyway — and it is what makes
+  // the artifact bound retroactive rather than only applying to new analyses.
+  for (const session of survivors) {
+    if (session.analyzed) {
+      tidySession(session.id, { keepPrompt: readMarker(session.id)?.outcome === 'error' })
+    }
+  }
+
+  const bySize = sweepToBudget(survivors, { ...options, budget })
   return { removed: [...byAge.removed, ...bySize.removed] }
 }

package/src/telemetry/store.ts

@@ -133,6 +133,11 @@ export function readMeta(id: string): SessionMeta | null {
   return readJsonSafe<SessionMeta>(metaPath(id))
 }
 
+/** One session's analyzer marker, or null when absent or unparseable. */
+export function readMarker(id: string): AnalyzedMarker | null {
+  return readJsonSafe<AnalyzedMarker>(markerPath(id))
+}
+
 function readJsonSafe<T>(path: string): T | null {
   try {
     return JSON.parse(readFileSync(path, 'utf-8')) as T

package/studio/package.json

@@ -21,7 +21,7 @@
     "typecheck": "tsgo --noEmit"
   },
   "dependencies": {
-    "@astrale-os/sdk": "0.5.0-beta.51",
+    "@astrale-os/sdk": "0.5.0-beta.54",
     "@astrale-os/shell": "0.4.2-beta.6",
     "@dagrejs/dagre": "^3.0.0",
     "@radix-ui/react-collapsible": "^1.1.0",