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

package/src/connection/.spec/architecture.md

@@ -28,7 +28,15 @@ selection, and the single safe stale-route recovery. The CLI does not reproduce
 discover destination identity. `SessionAuth.resolve(call, signal)` returns source-Kernel authority and
 ClientSession supplies an audience-free Delegate with omitted attenuation, preserving the exact
 current Grant for routing. Connection itself persists no credential or route; the separate state
-owner persists only exchanged source credentials.
+owner persists exchanged source credentials and the separate Kernel Client route artifact. A valid exchanged credential is selected by the
+authenticated source issuer and subject before any live `whoami`; cache misses alone resolve the
+registered Kernel User and perform delegation plus Domain exchange.
+Exchange authority is bounded to five minutes and never outlives the current source credential,
+matching the CLI route-age ceiling without forcing an unrelated two-minute refresh cycle.
+
+Every ClientSession receives the CLI-owned `state/session-routes` representation capability. Kernel
+Client still owns route keying, admission, expiry, and one safe stale/miss recovery; Connection does
+not reproduce routing or add an Admin-only bypass.
 
 `--anonymous` deliberately suppresses ambient and bookmark-default identities by omitting the
 `SessionAuth` capability. It cannot be combined with `--as` or `--creds`; contradictory selections fail

package/src/connection/__tests__/auth.test.ts

@@ -15,6 +15,7 @@ const config: AstraleConfig = {
     kernelIssuer: 'https://admin.eu.astrale.ai/api',
   },
   telemetry: { enabled: true },
+  browser: {},
 }
 
 describe('resolveKeyIdentityAuthOptions', () => {

package/src/connection/__tests__/credential.test.ts

@@ -18,6 +18,7 @@ const config: AstraleConfig = {
   issuer: 'https://cli.example',
   admin: { name: 'admin', url: SOURCE, kernelIssuer: SOURCE },
   telemetry: { enabled: false },
+  browser: {},
 }
 
 describe('connection credential', () => {

package/src/connection/__tests__/exchange.test.ts

@@ -14,13 +14,8 @@ const DOMAIN = issuer.accept('https://admin.example')
 const TARGET = { url: `${KERNEL}/api`, kernelIssuer: KERNEL, domainIssuer: DOMAIN }
 const INVOCATION = `${KERNEL}/invoke`
 const EXPIRES_AT = Math.floor(Date.now() / 1_000) + 500
-const SOURCE_EXPIRES_AT = Math.floor(Date.now() / 1_000) + 120
-const SOURCE_TOKEN = token(
-  issuer.accept('https://workos.example'),
-  KERNEL,
-  'user-1',
-  SOURCE_EXPIRES_AT,
-)
+const SOURCE_EXPIRES_AT = Math.floor(Date.now() / 1_000) + 600
+const SOURCE_TOKEN = sourceToken('user-1')
 let directory: string
 
 beforeEach(async () => {
@@ -33,7 +28,7 @@ afterEach(async () => {
 
 describe('Domain token exchange', () => {
   /** @evidence TEST-CLI-EXCHANGE-WHOAMI-DELEGATE-EXCHANGE-CACHE */
-  test('runs the exact User to Kernel to Domain journey and reuses the bound token', async () => {
+  test('runs the exact User to Kernel to Domain journey once and reuses it before whoami', async () => {
     const observed: Array<{
       url: string
       init: RequestInit | undefined
@@ -91,7 +86,7 @@ describe('Domain token exchange', () => {
     await expect(resolver.resolve(KERNEL, new AbortController().signal)).resolves.toBe(exchanged)
 
     const kernelRequests = observed.filter((entry) => entry.url === INVOCATION)
-    expect(kernelRequests).toHaveLength(3)
+    expect(kernelRequests).toHaveLength(2)
     expect(kernelRequests[0]!.body).toMatchObject({
       credential: SOURCE_TOKEN,
       call: { input: {} },
@@ -107,13 +102,32 @@ describe('Domain token exchange', () => {
     })
     const delegatedTtl = kernelRequests[1]!.body!.call.input.ttlSeconds
     expect(delegatedTtl).toBeGreaterThan(0)
-    expect(delegatedTtl).toBeLessThan(120)
+    expect(delegatedTtl).toBeGreaterThanOrEqual(295)
+    expect(delegatedTtl).toBeLessThanOrEqual(300)
     expect(sourceAudiences).toEqual([KERNEL, KERNEL])
     expect(
       observed.filter((entry) => entry.url.endsWith('/.well-known/astrale/token')),
     ).toHaveLength(1)
   })
 
+  test('rejects a source credential without a stable cache identity before network I/O', async () => {
+    let fetches = 0
+    const resolver = createExchangeCredentialResolver(
+      TARGET,
+      { resolve: async () => sourceToken(undefined) },
+      async () => {
+        fetches += 1
+        throw new Error('network must remain untouched')
+      },
+      5_000,
+      new ExchangeCredentialCache(join(directory, 'credentials.json')),
+    )
+    await expect(resolver.resolve(KERNEL, new AbortController().signal)).rejects.toMatchObject({
+      code: 'TOKEN_EXCHANGE_SOURCE_INVALID',
+    })
+    expect(fetches).toBe(0)
+  })
+
   /** @evidence TEST-CLI-EXCHANGE-NO-LEGACY-FALLBACK */
   test('fails closed when issuer discovery does not advertise exchange', async () => {
     const fetch: Fetch = async (input, init) => {
@@ -293,3 +307,13 @@ function token(iss: string, aud: string, user: string, exp: number): string {
     grant: { v: 1, expr: { kind: 'identity', credential: proof } },
   })}.signature`
 }
+
+function sourceToken(subject: string | undefined): string {
+  const encode = (value: unknown) => Buffer.from(JSON.stringify(value)).toString('base64url')
+  return `${encode({ alg: 'EdDSA', typ: 'JWT' })}.${encode({
+    iss: 'https://workos.example',
+    ...(subject === undefined ? {} : { sub: subject }),
+    aud: KERNEL,
+    exp: SOURCE_EXPIRES_AT,
+  })}.signature`
+}

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

@@ -1,6 +1,7 @@
 import type { AuthApi } from '@astrale-os/sdk/auth'
 import type { GraphApi } from '@astrale-os/sdk/client'
 import type { ClientSession } from '@astrale-os/sdk/client/session'
+import type { SessionRouteStore } from '@astrale-os/sdk/client/session'
 
 import { issuer } from '@astrale-os/sdk/auth'
 import { describe, expect, test } from 'bun:test'
@@ -23,6 +24,7 @@ const config: AstraleConfig = {
     kernelIssuer: 'https://admin.example',
   },
   telemetry: { enabled: false },
+  browser: {},
 }
 
 const context: ConnectionContext = Object.freeze({
@@ -37,11 +39,13 @@ describe('connection session', () => {
   /** @evidence TEST-CLI-CONNECTION-PINS-SOURCE-ISSUER */
   test('pins the selected canonical Kernel issuer without a transport escape hatch', async () => {
     const auth = { ttlSeconds: 3_600, resolve: async () => ({ credential: 'credential' }) }
-    const options = createClientSessionOptions(target, globalThis.fetch, auth, 2_500)
+    const routeStore: SessionRouteStore = { read: () => undefined, write: () => undefined }
+    const options = createClientSessionOptions(target, globalThis.fetch, auth, 2_500, routeStore)
 
     expect(options.kernel).toBe(target.kernelIssuer)
     expect(options).not.toHaveProperty('url')
     expect(options).not.toHaveProperty('sourceIssuer')
+    expect(options.routeStore).toBe(routeStore)
   })
 
   /** @evidence TEST-CLI-CONNECTION-OMITS-EXPLICIT-ANONYMOUS-CREDENTIAL */

package/src/connection/__tests__/target.test.ts

@@ -15,6 +15,7 @@ const config: AstraleConfig = {
     domainIssuer: 'https://admin-domain.example',
   },
   telemetry: { enabled: false },
+  browser: {},
 }
 
 const instances: InstanceStore = {

package/src/connection/exchange.ts

@@ -11,7 +11,7 @@ import type { ConnectionTarget } from './target'
 import { AstraleError } from '../errors'
 import { ExchangeCredentialCache } from '../state/exchange-credentials'
 
-const EXCHANGE_TTL_SECONDS = 120
+const EXCHANGE_TTL_SECONDS = 5 * 60
 const MAXIMUM_RESPONSE_BYTES = 256 * 1024
 
 /** Exchange exact authenticated User authority for a Domain bearer bound to this Kernel. */
@@ -27,53 +27,78 @@ export function createExchangeCredentialResolver(
     async resolve(kernelIssuer: IssuerId, signal: AbortSignal): Promise<string> {
       requireLive(signal)
       const sourceToken = await source.resolve(kernelIssuer, signal)
-      const delegationTtlSeconds = delegationLifetime(sourceToken)
+      const sourceIdentity = sourceCacheIdentity(sourceToken)
       requireLive(signal)
 
-      const client = new Client({ url: `${kernelIssuer}/invoke`, fetch, timeoutMs })
-      try {
-        const authenticated = client.as(sourceToken)
-        const auth = createAuth(async (path, input, options) => {
-          const result = await authenticated.call(call(path, input), {
-            ...options,
-            delegate: { ttlSeconds: delegationTtlSeconds },
-          })
-          return result.value
-        })
-        const user = await auth.whoami({ signal })
-        const key = Object.freeze({
+      return await cache.getOrRefresh(
+        Object.freeze({
           kernelIssuer,
           domainIssuer: target.domainIssuer,
-          user: user.id,
-        })
-        return await cache.getOrRefresh(key, async () => {
-          let envelope: string | undefined
-          for (let attempt = 0; attempt < 3; attempt += 1) {
-            try {
-              envelope = await auth.delegate(
-                user.id,
-                {
-                  audience: target.domainIssuer,
-                  ttlSeconds: delegationTtlSeconds,
-                  attenuation: { kind: 'identity', self: true },
-                },
-                { signal },
-              )
-              break
-            } catch (cause) {
-              if (attempt === 2 || !unknownFunctionOutcome(cause)) throw cause
+          sourceIssuer: sourceIdentity.issuer,
+          sourceSubject: sourceIdentity.subject,
+        }),
+        async () => {
+          const delegationTtlSeconds = delegationLifetime(sourceToken)
+          const client = new Client({ url: `${kernelIssuer}/invoke`, fetch, timeoutMs })
+          try {
+            const authenticated = client.as(sourceToken)
+            const auth = createAuth(async (path, input, options) => {
+              const result = await authenticated.call(call(path, input), {
+                ...options,
+                delegate: { ttlSeconds: delegationTtlSeconds },
+              })
+              return result.value
+            })
+            const user = await auth.whoami({ signal })
+            let envelope: string | undefined
+            for (let attempt = 0; attempt < 3; attempt += 1) {
+              try {
+                envelope = await auth.delegate(
+                  user.id,
+                  {
+                    audience: target.domainIssuer,
+                    ttlSeconds: delegationTtlSeconds,
+                    attenuation: { kind: 'identity', self: true },
+                  },
+                  { signal },
+                )
+                break
+              } catch (cause) {
+                if (attempt === 2 || !unknownFunctionOutcome(cause)) throw cause
+              }
             }
+            if (envelope === undefined) throw new Error('Token delegation returned no credential.')
+            return {
+              ...(await exchange(target.domainIssuer, kernelIssuer, envelope, fetch, signal)),
+              user: user.id,
+              sourceIssuer: sourceIdentity.issuer,
+              sourceSubject: sourceIdentity.subject,
+            }
+          } finally {
+            client.close()
           }
-          if (envelope === undefined) throw new Error('Token delegation returned no credential.')
-          return exchange(target.domainIssuer, kernelIssuer, envelope, fetch, signal)
-        })
-      } finally {
-        client.close()
-      }
+        },
+      )
     },
   })
 }
 
+function sourceCacheIdentity(sourceToken: string): { issuer: string; subject: string } {
+  const inspected = credential.inspect(sourceToken)
+  if (
+    typeof inspected.iss !== 'string' ||
+    inspected.iss.length === 0 ||
+    typeof inspected.sub !== 'string' ||
+    inspected.sub.length === 0
+  ) {
+    throw new AstraleError(
+      'TOKEN_EXCHANGE_SOURCE_INVALID',
+      'The source identity credential has no stable issuer and subject.',
+    )
+  }
+  return Object.freeze({ issuer: inspected.iss, subject: inspected.sub })
+}
+
 function unknownFunctionOutcome(cause: unknown): boolean {
   if (cause === null || typeof cause !== 'object') return false
   const error = cause as { readonly code?: unknown; readonly reason?: unknown }

package/src/connection/session.ts

@@ -1,6 +1,10 @@
 import type { AuthApi } from '@astrale-os/sdk/auth'
 import type { GraphApi } from '@astrale-os/sdk/client'
-import type { ClientSessionOptions, SessionAuth } from '@astrale-os/sdk/client/session'
+import type {
+  ClientSessionOptions,
+  SessionAuth,
+  SessionRouteStore,
+} from '@astrale-os/sdk/client/session'
 
 import { createAuth } from '@astrale-os/sdk/auth'
 import { call } from '@astrale-os/sdk/client'
@@ -21,6 +25,7 @@ import { fetchWithCaFile } from '../lib/ca-fetch'
 import { readConfig } from '../lib/config'
 import { log } from '../lib/log'
 import { isMachine } from '../lib/output'
+import { SESSION_ROUTE_STORE } from '../state/session-routes'
 import { bindCredentialIdentity } from './auth'
 import { createCliCredential, validateCredentialSelection } from './credential'
 import { resolveAdminConnectionTarget, resolveConnectionTarget } from './target'
@@ -165,11 +170,13 @@ export function createClientSessionOptions(
   fetch: NonNullable<ClientSessionOptions['fetch']>,
   auth: SessionAuth | undefined,
   timeoutMs: number,
+  routeStore: SessionRouteStore = SESSION_ROUTE_STORE,
 ): ClientSessionOptions {
   return {
     kernel: target.kernelIssuer,
     fetch,
     ...(auth === undefined ? {} : { auth }),
+    routeStore,
     policy: {
       maximumRouteAgeMs: MAXIMUM_ROUTE_AGE_MS,
       ...(new URL(target.url).protocol === 'http:' ? { allowInsecureHttp: true } : {}),

package/src/identity/__tests__/fixtures/registry-journey.ts

@@ -1,5 +1,8 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises'
+import { dirname } from 'node:path'
+
 import { fileExists, keypairPaths } from '../../../keys/index'
-import { KEYS_DIR } from '../../../state/index'
+import { EXCHANGE_CREDENTIALS_PATH, KEYS_DIR, SESSION_ROUTES_PATH } from '../../../state/index'
 import {
   createIdentity,
   exportIdentity,
@@ -30,6 +33,13 @@ try {
 } catch (error) {
   selectedDeletion = error instanceof Error ? error.message : String(error)
 }
+await mkdir(dirname(SESSION_ROUTES_PATH), { recursive: true })
+await mkdir(dirname(EXCHANGE_CREDENTIALS_PATH), { recursive: true })
+await writeFile(SESSION_ROUTES_PATH, '{"version":1,"entries":{"confidential":{}}}\n')
+await writeFile(
+  EXCHANGE_CREDENTIALS_PATH,
+  '{"version":2,"entries":{"confidential":{"credential":"bearer"}}}\n',
+)
 await deleteIdentity('bob')
 await deleteIdentity('alice-alias')
 await upsertIdpIdentity('workos', {
@@ -49,5 +59,7 @@ console.log(
     selectedDeletion,
     aliceKey: await fileExists(keypairPaths('alice', KEYS_DIR).privatePath),
     bobKey: await fileExists(keypairPaths('bob', KEYS_DIR).privatePath),
+    routeCache: await fileExists(SESSION_ROUTES_PATH),
+    exchangeCache: JSON.parse(await readFile(EXCHANGE_CREDENTIALS_PATH, 'utf8')),
   }),
 )

package/src/identity/__tests__/registry.test.ts

@@ -47,6 +47,8 @@ describe('identity registry journey', () => {
       selectedDeletion: string
       aliceKey: boolean
       bobKey: boolean
+      routeCache: boolean
+      exchangeCache: unknown
     }
     expect(result.store.default).toBe('alice')
     expect(Object.keys(result.store.identities).sort()).toEqual(['alice', 'workos'])
@@ -60,6 +62,8 @@ describe('identity registry journey', () => {
     expect(result.selectedDeletion).toContain('Cannot delete the default identity')
     expect(result.aliceKey).toBe(true)
     expect(result.bobKey).toBe(false)
+    expect(result.routeCache).toBe(false)
+    expect(result.exchangeCache).toEqual({ version: 2, entries: {} })
 
     const persisted = JSON.parse(await readFile(join(root, 'identities.json'), 'utf-8')) as {
       version?: unknown

package/src/identity/registry.ts

@@ -10,6 +10,7 @@ import {
   type IdentityStore,
   type Registration,
   ExchangeCredentialCache,
+  SESSION_ROUTE_STORE,
 } from '../state/index'
 
 export type { Identity, IdentityStore, Registration } from '../state/index'
@@ -68,6 +69,7 @@ export async function deleteIdentity(name: string): Promise<void> {
     return { next: { ...store, identities }, value: undefined }
   })
   await new ExchangeCredentialCache().clear()
+  SESSION_ROUTE_STORE.clear()
 }
 
 function hasAnotherKeyIdentity(store: IdentityStore, name: string, subject: string): boolean {

package/src/lib/__tests__/browser-retention.test.ts

@@ -0,0 +1,212 @@
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test'
+import {
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  rmSync,
+  symlinkSync,
+  utimesSync,
+  writeFileSync,
+} from 'node:fs'
+import { hostname, tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+import type { BrowserRetentionBudget } from '../browser-retention'
+
+import {
+  DEFAULT_MAX_CACHE_BYTES,
+  DEFAULT_MAX_PROFILE_AGE_DAYS,
+  browserRetentionBudget,
+  heldByLiveBrowser,
+  profileCacheBytes,
+  sweepBrowserProfiles,
+} from '../browser-retention'
+
+const DAY = 24 * 60 * 60 * 1000
+const BUDGET: BrowserRetentionBudget = { maxCacheBytes: 10_000, maxProfileAgeMs: 30 * DAY }
+
+let dir: string
+
+beforeEach(() => {
+  dir = mkdtempSync(join(tmpdir(), 'astrale-browser-ret-'))
+  delete process.env.ASTRALE_BROWSER_MAX_CACHE_BYTES
+  delete process.env.ASTRALE_BROWSER_MAX_PROFILE_AGE_DAYS
+})
+
+afterEach(() => {
+  rmSync(dir, { recursive: true, force: true })
+})
+
+type Seed = { idleMs?: number; cacheBytes?: number; lockPid?: number }
+
+/** A profile shaped like Chromium's: session state at the root and in Default/,
+ *  cache in the subdirectories retention is allowed to delete. */
+function seedProfile(name: string, { idleMs = 0, cacheBytes = 0, lockPid }: Seed): string {
+  const profile = join(dir, name)
+  mkdirSync(join(profile, 'Default'), { recursive: true })
+  writeFileSync(join(profile, 'Local State'), '{"os_crypt":{"encrypted_key":"x"}}')
+  writeFileSync(join(profile, 'Default', 'Cookies'), 'SQLite format 3\0cookie-data')
+  writeFileSync(join(profile, 'Default', 'Preferences'), '{"profile":{}}')
+  mkdirSync(join(profile, 'Default', 'Local Storage', 'leveldb'), { recursive: true })
+  writeFileSync(join(profile, 'Default', 'Local Storage', 'leveldb', '000003.log'), 'state')
+
+  if (cacheBytes > 0) {
+    mkdirSync(join(profile, 'Default', 'Cache', 'Cache_Data'), { recursive: true })
+    writeFileSync(
+      join(profile, 'Default', 'Cache', 'Cache_Data', 'f_000001'),
+      'x'.repeat(cacheBytes),
+    )
+    mkdirSync(join(profile, 'Default', 'Code Cache', 'js'), { recursive: true })
+    writeFileSync(join(profile, 'Default', 'Code Cache', 'js', 'index'), 'y'.repeat(cacheBytes))
+  }
+  if (lockPid !== undefined) {
+    symlinkSync(`${hostname()}-${lockPid}`, join(profile, 'SingletonLock'))
+  }
+  const when = new Date(Date.now() - idleMs)
+  utimesSync(profile, when, when)
+  return profile
+}
+
+const sessionIntact = (name: string): boolean =>
+  existsSync(join(dir, name, 'Default', 'Cookies')) &&
+  existsSync(join(dir, name, 'Local State')) &&
+  existsSync(join(dir, name, 'Default', 'Preferences')) &&
+  existsSync(join(dir, name, 'Default', 'Local Storage', 'leveldb', '000003.log'))
+
+const cacheGone = (name: string): boolean =>
+  !existsSync(join(dir, name, 'Default', 'Cache')) &&
+  !existsSync(join(dir, name, 'Default', 'Code Cache'))
+
+describe('age rule', () => {
+  test('a dormant profile is removed outright', async () => {
+    seedProfile('dormant', { idleMs: 40 * DAY, cacheBytes: 100 })
+    const r = await sweepBrowserProfiles({ dir, budget: BUDGET })
+    expect(r.removed).toEqual(['dormant'])
+    expect(existsSync(join(dir, 'dormant'))).toBe(false)
+    expect(r.bytesFreed).toBeGreaterThan(0)
+  })
+
+  test('a recently used profile is kept', async () => {
+    seedProfile('fresh', { idleMs: 2 * DAY, cacheBytes: 100 })
+    const r = await sweepBrowserProfiles({ dir, budget: BUDGET })
+    expect(r.removed).toEqual([])
+    expect(sessionIntact('fresh')).toBe(true)
+  })
+
+  test('the age bound is configurable', async () => {
+    seedProfile('two-days', { idleMs: 2 * DAY })
+    const strict = { ...BUDGET, maxProfileAgeMs: DAY }
+    expect((await sweepBrowserProfiles({ dir, budget: strict })).removed).toEqual(['two-days'])
+  })
+})
+
+describe('size rule', () => {
+  test('a profile under budget is left completely alone', async () => {
+    seedProfile('small', { idleMs: DAY, cacheBytes: 1_000 })
+    const r = await sweepBrowserProfiles({ dir, budget: BUDGET })
+    expect(r.purged).toEqual([])
+    expect(cacheGone('small')).toBe(false)
+  })
+
+  test('a profile over budget loses its cache but keeps its session', async () => {
+    seedProfile('bloated', { idleMs: DAY, cacheBytes: 20_000 })
+    const r = await sweepBrowserProfiles({ dir, budget: BUDGET })
+    expect(r.purged).toEqual(['bloated'])
+    expect(cacheGone('bloated')).toBe(true)
+    // The entire point: the cookie survives, so the user stays signed in.
+    expect(sessionIntact('bloated')).toBe(true)
+    expect(existsSync(join(dir, 'bloated'))).toBe(true)
+    expect(r.bytesFreed).toBeGreaterThanOrEqual(40_000)
+  })
+
+  test('the size bound counts only cache directories, not the whole profile', async () => {
+    const profile = seedProfile('measured', { idleMs: DAY, cacheBytes: 3_000 })
+    writeFileSync(join(profile, 'Default', 'History'), 'z'.repeat(50_000))
+    // 2 cache files of 3 KB each; History is not cache and must not count.
+    expect(await profileCacheBytes(profile)).toBe(6_000)
+    expect((await sweepBrowserProfiles({ dir, budget: BUDGET })).purged).toEqual([])
+  })
+})
+
+describe('live-browser guard', () => {
+  test('a profile locked by a live process is never touched', async () => {
+    // Our own pid is unambiguously alive.
+    seedProfile('in-use', { idleMs: 40 * DAY, cacheBytes: 20_000, lockPid: process.pid })
+    const r = await sweepBrowserProfiles({ dir, budget: BUDGET })
+    expect(r.skipped).toEqual(['in-use'])
+    expect(r.removed).toEqual([])
+    expect(r.purged).toEqual([])
+    expect(existsSync(join(dir, 'in-use'))).toBe(true)
+    expect(cacheGone('in-use')).toBe(false)
+  })
+
+  test('a stale lock from a dead process does not protect anything', async () => {
+    // Chromium leaves these behind after a crash; they must not pin disk forever.
+    seedProfile('crashed', { idleMs: 40 * DAY, lockPid: 999_999 })
+    const r = await sweepBrowserProfiles({ dir, budget: BUDGET })
+    expect(r.removed).toEqual(['crashed'])
+  })
+
+  test('heldByLiveBrowser reads the symlink without resolving it', () => {
+    // The target names a file that does not exist — statting it would throw.
+    const live = seedProfile('live', { lockPid: process.pid })
+    const dead = seedProfile('dead', { lockPid: 999_999 })
+    const none = seedProfile('none', {})
+    expect(heldByLiveBrowser(live)).toBe(true)
+    expect(heldByLiveBrowser(dead)).toBe(false)
+    expect(heldByLiveBrowser(none)).toBe(false)
+  })
+})
+
+describe('sweep resilience', () => {
+  test('a missing browser directory is a no-op, not an error', async () => {
+    const gone = join(dir, 'does-not-exist')
+    const r = await sweepBrowserProfiles({ dir: gone, budget: BUDGET })
+    expect(r).toEqual({ removed: [], purged: [], skipped: [], bytesFreed: 0 })
+  })
+
+  test('stray files beside the profiles are ignored', async () => {
+    writeFileSync(join(dir, 'browser.json'), '{}')
+    seedProfile('real', { idleMs: 40 * DAY })
+    expect((await sweepBrowserProfiles({ dir, budget: BUDGET })).removed).toEqual(['real'])
+  })
+
+  test('several profiles are handled independently in one pass', async () => {
+    seedProfile('a-dormant', { idleMs: 40 * DAY })
+    seedProfile('b-bloated', { idleMs: DAY, cacheBytes: 20_000 })
+    seedProfile('c-fine', { idleMs: DAY, cacheBytes: 100 })
+    seedProfile('d-locked', { idleMs: 40 * DAY, lockPid: process.pid })
+    const r = await sweepBrowserProfiles({ dir, budget: BUDGET })
+    expect(r.removed).toEqual(['a-dormant'])
+    expect(r.purged).toEqual(['b-bloated'])
+    expect(r.skipped).toEqual(['d-locked'])
+    expect(sessionIntact('c-fine')).toBe(true)
+  })
+})
+
+describe('browserRetentionBudget', () => {
+  test('defaults when nothing is configured', async () => {
+    expect(await browserRetentionBudget()).toEqual({
+      maxCacheBytes: DEFAULT_MAX_CACHE_BYTES,
+      maxProfileAgeMs: DEFAULT_MAX_PROFILE_AGE_DAYS * DAY,
+    })
+  })
+
+  test('env overrides both bounds', async () => {
+    process.env.ASTRALE_BROWSER_MAX_CACHE_BYTES = '4096'
+    process.env.ASTRALE_BROWSER_MAX_PROFILE_AGE_DAYS = '3'
+    expect(await browserRetentionBudget()).toEqual({
+      maxCacheBytes: 4096,
+      maxProfileAgeMs: 3 * DAY,
+    })
+  })
+
+  test.each([
+    ['zero', '0'],
+    ['negative', '-1'],
+    ['not a number', 'lots'],
+  ])('a %s env value falls back to the default rather than removing the cap', async (_l, value) => {
+    process.env.ASTRALE_BROWSER_MAX_CACHE_BYTES = value
+    expect((await browserRetentionBudget()).maxCacheBytes).toBe(DEFAULT_MAX_CACHE_BYTES)
+  })
+})

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

@@ -23,6 +23,33 @@ describe('AstraleConfigSchema', () => {
     })
   })
 
+  test('retention bounds survive a parse — a read/write cycle must not drop them', () => {
+    // zod strips unknown keys, so a bound declared only in its reader would be
+    // silently erased by any command that rewrites the config.
+    const result = AstraleConfigSchema.parse({
+      telemetry: { enabled: true, maxAgeDays: 7, maxBytes: 1_048_576 },
+      browser: { maxCacheBytes: 52_428_800, maxProfileAgeDays: 14 },
+    })
+    expect(result.telemetry).toEqual({ enabled: true, maxAgeDays: 7, maxBytes: 1_048_576 })
+    expect(result.browser).toEqual({ maxCacheBytes: 52_428_800, maxProfileAgeDays: 14 })
+  })
+
+  test.each([
+    ['zero', 0],
+    ['negative', -5],
+    ['not a number', 'lots'],
+    ['infinite', Number.POSITIVE_INFINITY],
+  ])('a %s bound is dropped, and does not take the rest of the config with it', (_l, value) => {
+    const result = AstraleConfigSchema.parse({
+      issuer: 'https://test.astrale.ai',
+      telemetry: { enabled: true, maxAgeDays: value },
+      browser: { maxCacheBytes: value },
+    })
+    expect(result.telemetry.maxAgeDays).toBeUndefined()
+    expect(result.browser.maxCacheBytes).toBeUndefined()
+    expect(result.issuer).toBe('https://test.astrale.ai')
+  })
+
   test('rejects non-url issuer', () => {
     expect(() => AstraleConfigSchema.parse({ issuer: 'not-a-url' })).toThrow()
   })