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

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

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/lib/browser-retention.ts

@@ -0,0 +1,210 @@
+/**
+ * Browser-profile retention.
+ *
+ * `astrale browser` keeps one persistent Chromium profile per host so the
+ * WorkOS cookie survives between runs. That cookie is a few kilobytes;
+ * everything Chromium accumulates around it is cache, and it accumulates
+ * without limit — a real profile here reached 373 MB, 98% of it cache.
+ *
+ * Chromium will not bound it for us. `--disk-cache-size` is measurably ignored
+ * for a profile's HTTP cache — the largest component by far — so deleting is
+ * the only lever. Two rules, cheapest first:
+ *
+ *   1. A profile untouched for longer than the age bound goes entirely. Its
+ *      WorkOS cookie has expired anyway, so it holds nothing worth the disk.
+ *   2. A surviving profile whose cache exceeds the size bound has its cache
+ *      directories removed. Cookies, Local Storage, Preferences and Local State
+ *      are never touched — the whole point of the profile is that the session
+ *      outlives the sweep.
+ *
+ * A profile whose SingletonLock names a live process is always left alone:
+ * deleting files under a running Chromium is how profiles get corrupted.
+ */
+import { readlinkSync } from 'node:fs'
+import { readdir, rm, stat } from 'node:fs/promises'
+import { join } from 'node:path'
+
+import { BROWSER_DIR } from './browser'
+import { readConfig } from './config'
+
+/** Reconstructible directories, relative to a profile root. Everything here can
+ *  be deleted with no user-visible consequence beyond a colder first load. */
+const CACHE_PATHS = [
+  'Default/Cache',
+  'Default/Code Cache',
+  'Default/GPUCache',
+  'Default/DawnWebGPUCache',
+  'Default/DawnGraphiteCache',
+  'Default/Service Worker/CacheStorage',
+  'Default/Service Worker/ScriptCache',
+  'GraphiteDawnCache',
+  'GPUPersistentCache',
+  'GrShaderCache',
+  'ShaderCache',
+  'component_crx_cache',
+  'extensions_crx_cache',
+] as const
+
+export const DEFAULT_MAX_CACHE_BYTES = 50 * 1024 * 1024
+export const DEFAULT_MAX_PROFILE_AGE_DAYS = 30
+
+export type BrowserRetentionBudget = {
+  /** Cap on one profile's cache directories, not on the profile as a whole. */
+  maxCacheBytes: number
+  maxProfileAgeMs: number
+}
+
+export type BrowserSweepResult = {
+  /** Profiles deleted outright (dormant past the age bound). */
+  removed: string[]
+  /** Profiles kept, cache emptied (over the size bound). */
+  purged: string[]
+  /** Profiles a live browser was holding — left untouched. */
+  skipped: string[]
+  bytesFreed: number
+}
+
+const EMPTY: BrowserSweepResult = { removed: [], purged: [], skipped: [], bytesFreed: 0 }
+
+/** First finite, strictly positive candidate; anything else falls through to
+ *  the next one, and ultimately to the default. A typo must not mean "no cap". */
+function firstPositive(candidates: (number | string | undefined)[]): number | null {
+  for (const candidate of candidates) {
+    if (candidate === undefined) continue
+    const n = typeof candidate === 'string' ? Number(candidate.trim()) : candidate
+    if (Number.isFinite(n) && n > 0) return n
+  }
+  return null
+}
+
+/** Resolved budget: env over config over defaults. */
+export async function browserRetentionBudget(): Promise<BrowserRetentionBudget> {
+  const browser = (await readConfig().catch(() => null))?.browser
+  const bytes =
+    firstPositive([process.env.ASTRALE_BROWSER_MAX_CACHE_BYTES, browser?.maxCacheBytes]) ??
+    DEFAULT_MAX_CACHE_BYTES
+  const days =
+    firstPositive([process.env.ASTRALE_BROWSER_MAX_PROFILE_AGE_DAYS, browser?.maxProfileAgeDays]) ??
+    DEFAULT_MAX_PROFILE_AGE_DAYS
+  return { maxCacheBytes: bytes, maxProfileAgeMs: days * 24 * 60 * 60 * 1000 }
+}
+
+/** True when a process with this pid exists. EPERM means it exists but is not
+ *  ours — still alive, and still a reason not to touch the profile. */
+function isLive(pid: number): boolean {
+  try {
+    process.kill(pid, 0)
+    return true
+  } catch (e) {
+    return (e as NodeJS.ErrnoException).code === 'EPERM'
+  }
+}
+
+/**
+ * Whether a live browser holds this profile. SingletonLock is a symlink whose
+ * target is `<hostname>-<pid>` and which does NOT resolve to a real file, so it
+ * must be read with readlink, never stat'ed. A stale lock (dead pid) is not a
+ * reason to skip — Chromium leaves those behind after a crash.
+ */
+export function heldByLiveBrowser(profileDir: string): boolean {
+  let target: string
+  try {
+    target = readlinkSync(join(profileDir, 'SingletonLock'))
+  } catch {
+    return false
+  }
+  const pid = Number(target.slice(target.lastIndexOf('-') + 1))
+  return Number.isInteger(pid) && pid > 0 && isLive(pid)
+}
+
+/** Bytes under `dir`, or 0 when it is missing or unreadable. */
+async function directoryBytes(dir: string): Promise<number> {
+  let entries
+  try {
+    entries = await readdir(dir, { withFileTypes: true })
+  } catch {
+    return 0
+  }
+  let total = 0
+  for (const entry of entries) {
+    const path = join(dir, entry.name)
+    if (entry.isDirectory()) {
+      total += await directoryBytes(path)
+    } else if (entry.isFile()) {
+      try {
+        total += (await stat(path)).size
+      } catch {
+        /* raced away mid-walk */
+      }
+    }
+  }
+  return total
+}
+
+/** Cumulative size of one profile's cache directories. */
+export async function profileCacheBytes(profileDir: string): Promise<number> {
+  let total = 0
+  for (const relative of CACHE_PATHS) total += await directoryBytes(join(profileDir, relative))
+  return total
+}
+
+/** Delete every cache directory of a profile; returns bytes actually freed. */
+async function purgeCache(profileDir: string): Promise<number> {
+  const before = await profileCacheBytes(profileDir)
+  for (const relative of CACHE_PATHS) {
+    await rm(join(profileDir, relative), { recursive: true, force: true }).catch(() => {
+      /* best effort — retention must never break the browser command */
+    })
+  }
+  return before - (await profileCacheBytes(profileDir))
+}
+
+/**
+ * Apply both rules across every profile under `dir`. Never throws: a failed
+ * sweep must not stop the user from driving a browser.
+ */
+export async function sweepBrowserProfiles(
+  options: { dir?: string; budget?: BrowserRetentionBudget; now?: number } = {},
+): Promise<BrowserSweepResult> {
+  const dir = options.dir ?? BROWSER_DIR
+  let names: string[]
+  try {
+    names = (await readdir(dir, { withFileTypes: true }))
+      .filter((e) => e.isDirectory())
+      .map((e) => e.name)
+  } catch {
+    return EMPTY
+  }
+  if (names.length === 0) return EMPTY
+
+  const budget = options.budget ?? (await browserRetentionBudget())
+  const now = options.now ?? Date.now()
+  const result: BrowserSweepResult = { removed: [], purged: [], skipped: [], bytesFreed: 0 }
+
+  for (const name of names) {
+    const profileDir = join(dir, name)
+    if (heldByLiveBrowser(profileDir)) {
+      result.skipped.push(name)
+      continue
+    }
+    try {
+      // The profile root's mtime tracks USE, not writes: Chromium rewrites
+      // SingletonLock and DevToolsActivePort there on every launch, while cache
+      // writes land in subdirectories and leave the root alone.
+      const idleMs = now - (await stat(profileDir)).mtime.getTime()
+      if (idleMs > budget.maxProfileAgeMs) {
+        result.bytesFreed += await directoryBytes(profileDir)
+        await rm(profileDir, { recursive: true, force: true })
+        result.removed.push(name)
+        continue
+      }
+      if ((await profileCacheBytes(profileDir)) > budget.maxCacheBytes) {
+        result.bytesFreed += await purgeCache(profileDir)
+        result.purged.push(name)
+      }
+    } catch {
+      /* best effort, per profile — one bad profile must not stop the sweep */
+    }
+  }
+  return result
+}

package/src/lib/config.ts

@@ -6,10 +6,21 @@ import { CONFIG_PATH } from '../state/index'
 import { AdminTargetConfigSchema, DEFAULT_ADMIN_TARGET_CONFIG } from './admin-target'
 import { log } from './log'
 
+/** A retention bound, or undefined when absent or nonsensical. A bad value must
+ *  fall back to the default rather than take the whole config down with it —
+ *  and must never read as "no limit". */
+const bound = z.number().positive().finite().optional().catch(undefined)
+
 export const AstraleConfigSchema = z.object({
   issuer: z.string().url().default('https://unregistered.invalid'),
   admin: AdminTargetConfigSchema.default(DEFAULT_ADMIN_TARGET_CONFIG),
-  telemetry: z.object({ enabled: z.boolean().default(true) }).default({ enabled: true }),
+  // The retention bounds live in the schema, not just in the readers that
+  // consume them: zod strips unknown keys, so a config the CLI rewrites (see
+  // setup/steps/admin.ts) would silently drop anything declared elsewhere.
+  telemetry: z
+    .object({ enabled: z.boolean().default(true), maxAgeDays: bound, maxBytes: bound })
+    .default({ enabled: true }),
+  browser: z.object({ maxCacheBytes: bound, maxProfileAgeDays: bound }).default({}),
 })
 
 export type AstraleConfig = z.infer<typeof AstraleConfigSchema>

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/state/.spec/api.d.ts

@@ -1,3 +1,5 @@
+import type { SessionRouteArtifact, SessionRouteStore } from '@astrale-os/sdk/client/session'
+
 /** Environment values that affect CLI-owned state placement. */
 export interface PathEnvironment {
   readonly ASTRALE_HOME?: string
@@ -17,6 +19,7 @@ export interface Paths {
   readonly idps: string
   readonly idpSessionsDir: string
   readonly exchangeCredentials: string
+  readonly sessionRoutes: string
   idpDir(name: string): string
   idpSession(identityName: string): string
 }
@@ -35,22 +38,27 @@ export const INSTANCES_PATH: string
 export const IDPS_PATH: string
 export const IDP_SESSIONS_DIR: string
 export const EXCHANGE_CREDENTIALS_PATH: string
+export const SESSION_ROUTES_PATH: string
 
 export namespace exchange {
   interface Artifact {
-    readonly version: 1
+    readonly version: 2
     readonly entries: Record<string, Entry>
   }
 
   interface Key {
     readonly kernelIssuer: string
     readonly domainIssuer: string
-    readonly user: string
+    readonly sourceIssuer: string
+    readonly sourceSubject: string
   }
 
   interface Entry {
     readonly credential: string
     readonly expiresAt: number
+    readonly user: string
+    readonly sourceIssuer: string
+    readonly sourceSubject: string
   }
 }
 
@@ -118,6 +126,17 @@ export function updateIdentityStore<Value>(
 
 /** Atomically replace one private CLI state file through a same-directory temporary file. */
 export function atomicWrite(path: string, data: string): Promise<void>
+export function atomicWriteSync(path: string, data: string): void
+
+/** CLI filesystem representation for Kernel Client's admitted confidential route artifact. */
+export class FileSessionRouteStore implements SessionRouteStore {
+  constructor(path?: string)
+  read(): unknown
+  write(artifact: SessionRouteArtifact): void
+  clear(): void
+}
+
+export const SESSION_ROUTE_STORE: Readonly<FileSessionRouteStore>
 
 export interface FileLockOptions {
   readonly pollIntervalMs?: number

package/src/state/.spec/architecture.md

@@ -11,10 +11,24 @@ The identity registry decodes the legacy unversioned shape and current V1 envelo
 exact bytes at `identities.json.v0.bak` before publishing V1. Invalid or newer files remain untouched
 and fail closed. Identity orchestration owns key and IdP-session effects above this module.
 
-The exchange registry owns a versioned `exchange.Artifact`. Each entry is keyed by the atomic
-`(Kernel issuer, Domain issuer, registered User)` identity and stores only one inspected Domain
-credential and expiry. It reuses the same atomic-write and bounded file-lock primitives, maintains
-owner-only directory and file modes, and remains distinct from Client's process-local route cache.
+The exchange registry owns a versioned `exchange.Artifact`. Each V2 entry is keyed by the atomic
+`(Kernel issuer, Domain issuer, source issuer, source subject)` identity and stores one inspected
+Domain credential, expiry, and the exact registered Kernel User proven when that credential was
+minted, together with the exact upstream source issuer and subject that selected the entry. This lets
+a warm command validate and reuse the credential before any network `whoami` without accepting a
+refresh result filed under another source identity.
+V1 is not migrated or retained; it is discarded and replaced by the next exact exchange. The
+registry reuses the same atomic-write and bounded file-lock primitives and maintains owner-only
+directory and file modes.
+
+The session-route registry is a separate representation adapter for Kernel Client's versioned,
+bounded confidential route artifact. Kernel Client exclusively owns route keying, admission, expiry,
+and stale/miss recovery. CLI owns only synchronous owner-private JSON I/O so a new CLI process can
+reuse admitted routing state without an Admin-specific shortcut. Writes are atomic snapshots; a
+lost concurrent cache update or any read/write failure is only a future cold route miss and cannot
+change product correctness.
+Authentication logout and identity deletion remove this artifact together with exchanged Domain
+credentials so locally retired authority does not leave reusable destination bearers behind.
 
 Shape decoding, migrations, and backup policy remain with each semantic registry. Commands do not
 call these primitives directly, and Kernel Client owns no CLI filesystem state.

package/src/state/.spec/layout.ts

@@ -8,6 +8,7 @@ export default defineLayout({
     'identities.ts',
     'index.ts',
     'paths.ts',
+    'session-routes.ts',
     'tsconfig.json',
   ],
   exact: true,