@astrale-os/cli 0.8.0-alpha.0 → 0.8.1-alpha.2

package/src/setup/steps/admin.ts

@@ -1,6 +1,10 @@
 import type { SetupContext, SetupStep } from '../types'
 
-import { AdminTargetConfigSchema, DEFAULT_ADMIN_TARGET_NAME } from '../../lib/admin-target'
+import {
+  AdminTargetConfigSchema,
+  DEFAULT_ADMIN_DOMAIN_ISSUER,
+  DEFAULT_ADMIN_TARGET_NAME,
+} from '../../lib/admin-target'
 import { readConfig, writeConfig } from '../../lib/config'
 import { readLocalStatus } from '../../lib/local-status'
 import { log } from '../../lib/log'
@@ -13,13 +17,24 @@ async function setAdminUrl(url: string): Promise<void> {
   const config = await readConfig()
   await writeConfig({
     ...config,
-    admin: AdminTargetConfigSchema.parse({ name: DEFAULT_ADMIN_TARGET_NAME, url, issuer: url }),
+    admin: AdminTargetConfigSchema.parse({
+      name: DEFAULT_ADMIN_TARGET_NAME,
+      url,
+      kernelIssuer: url,
+      domainIssuer: config.admin.domainIssuer ?? DEFAULT_ADMIN_DOMAIN_ISSUER,
+    }),
   })
 }
 
 async function setAdminBookmark(bookmark: string): Promise<void> {
   const config = await readConfig()
-  await writeConfig({ ...config, admin: AdminTargetConfigSchema.parse({ instance: bookmark }) })
+  await writeConfig({
+    ...config,
+    admin: AdminTargetConfigSchema.parse({
+      instance: bookmark,
+      domainIssuer: config.admin.domainIssuer ?? DEFAULT_ADMIN_DOMAIN_ISSUER,
+    }),
+  })
 }
 
 /**

package/src/setup/steps/instance.ts

@@ -4,7 +4,7 @@ import type { OwnedInstanceInfo } from '../../lib/admin-instance'
 import type { SetupContext, SetupStep } from '../types'
 
 import { AstraleError } from '../../errors'
-import { listOwnedInstances } from '../../kernel/client'
+import { listOwnedInstances } from '../../lib/admin-instance'
 import { normalizeInstanceKernelUrl, setActive, upsertManagedBookmark } from '../../lib/instance'
 import { readLocalStatus } from '../../lib/local-status'
 import { log, withSpinner } from '../../lib/log'

package/src/state/.spec/api.d.ts

@@ -0,0 +1,133 @@
+/** Environment values that affect CLI-owned state placement. */
+export interface PathEnvironment {
+  readonly ASTRALE_HOME?: string
+  readonly ASTRALE_KEYS_DIR?: string
+  readonly ASTRALE_DATA_DIR?: string
+}
+
+/** One captured set of CLI-owned durable-state coordinates. */
+export interface Paths {
+  readonly home: string
+  readonly keys: string
+  readonly data: string
+  readonly config: string
+  readonly install: string
+  readonly identities: string
+  readonly instances: string
+  readonly idps: string
+  readonly idpSessionsDir: string
+  readonly exchangeCredentials: string
+  idpDir(name: string): string
+  idpSession(identityName: string): string
+}
+
+/** Resolve explicit home, environment overrides, and platform home exactly once. */
+export function createPaths(home?: string, environment?: PathEnvironment): Paths
+
+export const paths: Paths
+export const ASTRALE_HOME: string
+export const KEYS_DIR: string
+export const DATA_DIR: string
+export const CONFIG_PATH: string
+export const INSTALL_PATH: string
+export const IDENTITIES_PATH: string
+export const INSTANCES_PATH: string
+export const IDPS_PATH: string
+export const IDP_SESSIONS_DIR: string
+export const EXCHANGE_CREDENTIALS_PATH: string
+
+export namespace exchange {
+  interface Artifact {
+    readonly version: 1
+    readonly entries: Record<string, Entry>
+  }
+
+  interface Key {
+    readonly kernelIssuer: string
+    readonly domainIssuer: string
+    readonly user: string
+  }
+
+  interface Entry {
+    readonly credential: string
+    readonly expiresAt: number
+  }
+}
+
+/** Persist exact Domain bearer tokens under a private, cross-process synchronized cache. */
+export class ExchangeCredentialCache {
+  constructor(path?: string)
+  getOrRefresh(
+    key: exchange.Key,
+    refresh: () => Promise<exchange.Entry>,
+    now?: () => number,
+  ): Promise<string>
+  deleteKernel(kernelIssuer: string): Promise<void>
+  clear(): Promise<void>
+}
+
+export type IdentitySource = 'key' | 'idp'
+export type IdentityMode = 'local' | 'remote'
+
+export interface Registration {
+  readonly iss: string
+  readonly sub: string
+  readonly registeredAt: string
+}
+
+export interface Identity {
+  readonly subject: string
+  readonly createdAt: string
+  readonly source?: IdentitySource
+  readonly mode?: IdentityMode
+  readonly kid?: string
+  readonly idp?: string
+  readonly issuer?: string
+  readonly audience?: string
+  readonly claims?: Readonly<Record<string, unknown>>
+  readonly registrations?: Readonly<Record<string, Registration>>
+}
+
+/** Decoded semantic identity state; persistence-version metadata is not exposed to consumers. */
+export interface IdentityStore {
+  readonly default: string
+  readonly identities: Readonly<Record<string, Identity>>
+}
+
+export const IDENTITY_STORE_VERSION: 1
+
+export interface IdentityStoreOptions {
+  readonly path?: string
+  readonly now?: () => Date
+  readonly lock?: FileLockOptions
+}
+
+export interface IdentityUpdate<Value> {
+  readonly next: IdentityStore
+  readonly value: Value
+}
+
+/** Decode the missing, legacy, or current identity file without writing or migrating it. */
+export function readIdentityStore(options?: IdentityStoreOptions): Promise<IdentityStore>
+
+/** Reread and commit one identity transition under the file's cross-process lock. */
+export function updateIdentityStore<Value>(
+  transition: (current: IdentityStore) => IdentityUpdate<Value> | Promise<IdentityUpdate<Value>>,
+  options?: IdentityStoreOptions,
+): Promise<Value>
+
+/** Atomically replace one private CLI state file through a same-directory temporary file. */
+export function atomicWrite(path: string, data: string): Promise<void>
+
+export interface FileLockOptions {
+  readonly pollIntervalMs?: number
+  readonly staleAfterMs?: number
+  readonly timeoutMs?: number
+}
+
+/** Run one state transition under a bounded cross-process file lock. */
+export function withFileLock<Value>(
+  lockPath: string,
+  transition: () => Promise<Value>,
+  options?: FileLockOptions,
+): Promise<Value>

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

@@ -0,0 +1,31 @@
+# CLI state architecture
+
+This module owns CLI filesystem placement, the durable file-transition primitives shared by state
+registries, and each registry's persistence admission. `createPaths` captures explicit and
+environment coordinates once. `atomicWrite` publishes one complete `0600` file through a
+same-directory temporary file. `withFileLock` bounds cross-process read-modify-write exclusion and
+releases its lock on every terminal path.
+
+The identity registry decodes the legacy unversioned shape and current V1 envelope into one semantic
+`IdentityStore`. Reads never migrate. The first successful mutation of a legacy file preserves its
+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.
+
+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.
+
+```mermaid
+flowchart LR
+  C[CLI command] --> I[identity orchestration]
+  I --> R[IdentityStore transition]
+  R --> L[withFileLock]
+  L --> B[legacy backup when needed]
+  B --> A[atomicWrite V1]
+  A --> F[identities.json]
+  P[createPaths] --> R
+```

package/src/state/.spec/capabilities/state.ts

@@ -0,0 +1,7 @@
+import { defineCapability } from '@astrale-os/spec/authoring'
+
+export const CLI_STATE = defineCapability({
+  id: 'CLI-STATE',
+  statement:
+    'Owns captured CLI filesystem coordinates and bounded atomic transitions for local durable state.',
+})

package/src/state/.spec/flows/identity-update.ts

@@ -0,0 +1,22 @@
+import type { IdentityStore, IdentityUpdate } from '../api.js'
+
+declare const withIdentityLock: <Value>(transition: () => Promise<Value>) => Promise<Value>
+declare const readLatest: () => Promise<{
+  readonly store: IdentityStore
+  readonly legacyBytes?: string
+}>
+declare const preserveLegacyBackup: (bytes: string) => Promise<void>
+declare const publishV1: (store: IdentityStore) => Promise<void>
+
+/** One identity mutation rereads, transitions, backs up legacy bytes, then publishes exactly once. */
+export function updateIdentity<Value>(
+  transition: (current: IdentityStore) => IdentityUpdate<Value> | Promise<IdentityUpdate<Value>>,
+): Promise<Value> {
+  return withIdentityLock(async () => {
+    const current = await readLatest()
+    const update = await transition(current.store)
+    if (current.legacyBytes !== undefined) await preserveLegacyBackup(current.legacyBytes)
+    await publishV1(update.next)
+    return update.value
+  })
+}

package/src/state/.spec/laws/state.ts

@@ -0,0 +1,73 @@
+import { defineLaw } from '@astrale-os/spec/authoring'
+
+export const CLI_STATE_PATHS_CAPTURED = defineLaw({
+  id: 'CLI-STATE-PATHS-CAPTURED',
+  statement:
+    'Path construction applies explicit-home then environment then platform-home precedence once; later environment mutation cannot change the returned coordinates.',
+  tests: [{ file: '__tests__/paths.test.ts', id: 'TEST-CLI-STATE-PATHS-CAPTURED' }],
+})
+
+export const CLI_STATE_ATOMIC_REPLACEMENT = defineLaw({
+  id: 'CLI-STATE-ATOMIC-REPLACEMENT',
+  statement:
+    'A successful replacement publishes one complete mode-0600 file and leaves no temporary file; a failed replacement never publishes partial content.',
+  tests: [
+    { file: '__tests__/files.test.ts', id: 'TEST-CLI-STATE-ATOMIC-WRITE' },
+    { file: '__tests__/files.test.ts', id: 'TEST-CLI-STATE-ATOMIC-WRITE-FAILURE' },
+  ],
+})
+
+export const CLI_STATE_LOCK_BOUNDED = defineLaw({
+  id: 'CLI-STATE-LOCK-BOUNDED',
+  statement:
+    'Contending transitions serialize, abandoned locks are recoverable, acquisition is bounded, and every acquired lock is released after success or failure.',
+  tests: [
+    { file: '__tests__/files.test.ts', id: 'TEST-CLI-STATE-LOCK-SERIALIZES' },
+    { file: '__tests__/files.test.ts', id: 'TEST-CLI-STATE-LOCK-RECOVERS' },
+    { file: '__tests__/files.test.ts', id: 'TEST-CLI-STATE-LOCK-RELEASES-AND-BOUNDS' },
+  ],
+})
+
+export const CLI_STATE_IDENTITY_READ_SAFE = defineLaw({
+  id: 'CLI-STATE-IDENTITY-READ-SAFE',
+  statement:
+    'Missing, legacy, and current identity files decode without a write; malformed or unsupported-version files fail without replacement.',
+  tests: [
+    { file: '__tests__/identities.test.ts', id: 'TEST-CLI-STATE-IDENTITY-READ-SAFE' },
+    { file: '__tests__/identities.test.ts', id: 'TEST-CLI-STATE-IDENTITY-FAILS-CLOSED' },
+  ],
+})
+
+export const CLI_STATE_IDENTITY_MIGRATION = defineLaw({
+  id: 'CLI-STATE-IDENTITY-MIGRATION',
+  statement:
+    'The first successful mutation of legacy identity state preserves its exact bytes once before publishing V1; concurrent mutations reread and retain every committed transition.',
+  tests: [
+    { file: '__tests__/identities.test.ts', id: 'TEST-CLI-STATE-IDENTITY-MIGRATES' },
+    { file: '__tests__/identities.test.ts', id: 'TEST-CLI-STATE-IDENTITY-CONCURRENT' },
+  ],
+})
+
+export const CLI_STATE_EXCHANGE_CACHE = defineLaw({
+  id: 'CLI-STATE-EXCHANGE-CACHE',
+  statement:
+    'The durable exchange Artifact partitions Domain credentials by exact Kernel issuer, Domain issuer, and registered User, requires the sole nested Kernel proof subject to equal that User, admits matching token claims and expiry, refreshes under process and file-lock singleflight, and publishes only owner-private atomic state.',
+  tests: [
+    {
+      file: '__tests__/exchange-credentials.test.ts',
+      id: 'TEST-CLI-EXCHANGE-CACHE-EXACT-KEY-AND-PRIVATE-MODE',
+    },
+    {
+      file: '__tests__/exchange-credentials.test.ts',
+      id: 'TEST-CLI-EXCHANGE-CACHE-SINGLEFLIGHT-CROSS-INSTANCE',
+    },
+    {
+      file: '__tests__/exchange-credentials.test.ts',
+      id: 'TEST-CLI-EXCHANGE-CACHE-REJECTS-STALE-OR-MISBOUND',
+    },
+    {
+      file: '__tests__/exchange-credentials.test.ts',
+      id: 'TEST-CLI-EXCHANGE-CACHE-LIFECYCLE-INVALIDATION',
+    },
+  ],
+})

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

@@ -0,0 +1,14 @@
+import { defineLayout } from '@astrale-os/spec/authoring'
+
+export default defineLayout({
+  entries: [
+    '__tests__/',
+    'exchange-credentials.ts',
+    'files.ts',
+    'identities.ts',
+    'index.ts',
+    'paths.ts',
+    'tsconfig.json',
+  ],
+  exact: true,
+})

package/src/state/__tests__/exchange-credentials.test.ts

@@ -0,0 +1,188 @@
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test'
+import { mkdtemp, readFile, rm, stat } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+import { ExchangeCredentialCache } from '../exchange-credentials'
+
+let directory: string
+let path: string
+
+beforeEach(async () => {
+  directory = await mkdtemp(join(tmpdir(), 'astrale-exchange-cache-'))
+  path = join(directory, 'private', 'credentials.json')
+})
+
+afterEach(async () => {
+  await rm(directory, { recursive: true, force: true })
+})
+
+describe('exchange credential cache', () => {
+  /** @evidence TEST-CLI-EXCHANGE-CACHE-EXACT-KEY-AND-PRIVATE-MODE */
+  test('partitions by Kernel, Domain, and User under private filesystem modes', async () => {
+    const cache = new ExchangeCredentialCache(path)
+    const now = () => 100
+    const first = key('https://kernel-a.example', 'https://domain.example', 'user-a')
+    const second = key('https://kernel-a.example', 'https://domain.example', 'user-b')
+    let refreshes = 0
+
+    const resolve = (candidate: typeof first) =>
+      cache.getOrRefresh(
+        candidate,
+        async () => {
+          refreshes += 1
+          return {
+            credential: token(candidate, 200),
+            expiresAt: 200,
+          }
+        },
+        now,
+      )
+
+    await expect(resolve(first)).resolves.toBe(token(first, 200))
+    await expect(resolve(first)).resolves.toBe(token(first, 200))
+    await expect(resolve(second)).resolves.toBe(token(second, 200))
+    expect(refreshes).toBe(2)
+    expect((await stat(path)).mode & 0o777).toBe(0o600)
+    expect((await stat(join(directory, 'private'))).mode & 0o777).toBe(0o700)
+  })
+
+  /** @evidence TEST-CLI-EXCHANGE-CACHE-SINGLEFLIGHT-CROSS-INSTANCE */
+  test('singleflights refreshes in-process and through the cross-process file lock', async () => {
+    const left = new ExchangeCredentialCache(path)
+    const right = new ExchangeCredentialCache(path)
+    const candidate = key('https://kernel.example', 'https://domain.example', 'user')
+    let refreshes = 0
+    const refresh = async () => {
+      refreshes += 1
+      await new Promise((resolve) => setTimeout(resolve, 10))
+      return {
+        credential: token(candidate, 200),
+        expiresAt: 200,
+      }
+    }
+
+    const values = await Promise.all([
+      left.getOrRefresh(candidate, refresh, () => 100),
+      left.getOrRefresh(candidate, refresh, () => 100),
+      right.getOrRefresh(candidate, refresh, () => 100),
+    ])
+    expect(new Set(values).size).toBe(1)
+    expect(refreshes).toBe(1)
+  })
+
+  /** @evidence TEST-CLI-EXCHANGE-CACHE-REJECTS-STALE-OR-MISBOUND */
+  test('removes stale entries and rejects a freshly returned misbound token', async () => {
+    const cache = new ExchangeCredentialCache(path)
+    const candidate = key('https://kernel.example', 'https://domain.example', 'user')
+    await cache.getOrRefresh(
+      candidate,
+      async () => ({
+        credential: token(candidate, 120),
+        expiresAt: 120,
+      }),
+      () => 50,
+    )
+    let refreshes = 0
+    await cache.getOrRefresh(
+      candidate,
+      async () => {
+        refreshes += 1
+        return {
+          credential: token(candidate, 220),
+          expiresAt: 220,
+        }
+      },
+      () => 100,
+    )
+    expect(refreshes).toBe(1)
+
+    await expect(
+      cache.getOrRefresh(
+        key('https://other-kernel.example', candidate.domainIssuer, candidate.user),
+        async () => ({
+          credential: token(candidate, 220),
+          expiresAt: 220,
+        }),
+        () => 100,
+      ),
+    ).rejects.toThrow(/inconsistent with its cache key/i)
+
+    await expect(
+      cache.getOrRefresh(
+        key(candidate.kernelIssuer, candidate.domainIssuer, 'other-user'),
+        async () => ({ credential: token(candidate, 220), expiresAt: 220 }),
+        () => 100,
+      ),
+    ).rejects.toThrow(/inconsistent with its cache key/i)
+
+    for (const malformed of ['outer-delegation', 'proof-without-delegation'] as const) {
+      const malformedCandidate = key(
+        candidate.kernelIssuer,
+        candidate.domainIssuer,
+        `user-${malformed}`,
+      )
+      await expect(
+        cache.getOrRefresh(
+          malformedCandidate,
+          async () => ({
+            credential: token(malformedCandidate, 220, malformed),
+            expiresAt: 220,
+          }),
+          () => 100,
+        ),
+      ).rejects.toThrow(/inconsistent with its cache key/i)
+    }
+  })
+
+  /** @evidence TEST-CLI-EXCHANGE-CACHE-LIFECYCLE-INVALIDATION */
+  test('invalidates one Kernel or the entire cache', async () => {
+    const cache = new ExchangeCredentialCache(path)
+    const a = key('https://kernel-a.example', 'https://domain.example', 'user')
+    const b = key('https://kernel-b.example', 'https://domain.example', 'user')
+    for (const candidate of [a, b]) {
+      await cache.getOrRefresh(
+        candidate,
+        async () => ({
+          credential: token(candidate, 200),
+          expiresAt: 200,
+        }),
+        () => 100,
+      )
+    }
+    await cache.deleteKernel(a.kernelIssuer)
+    expect(await readFile(path, 'utf8')).not.toContain(a.kernelIssuer)
+    expect(await readFile(path, 'utf8')).toContain(b.kernelIssuer)
+    await cache.clear()
+    expect(JSON.parse(await readFile(path, 'utf8')).entries).toEqual({})
+  })
+})
+
+function key(kernelIssuer: string, domainIssuer: string, user: string) {
+  return { kernelIssuer, domainIssuer, user }
+}
+
+function token(
+  candidate: ReturnType<typeof key>,
+  exp: number,
+  malformed?: 'outer-delegation' | 'proof-without-delegation',
+): string {
+  const encode = (value: unknown) => Buffer.from(JSON.stringify(value)).toString('base64url')
+  const proof = `${encode({ alg: 'EdDSA', typ: 'JWT' })}.${encode({
+    iss: candidate.kernelIssuer,
+    sub: candidate.user,
+    aud: candidate.kernelIssuer,
+    exp,
+    ...(malformed === 'proof-without-delegation'
+      ? {}
+      : { delegation: { v: 1, expr: { kind: 'identity', id: candidate.user } } }),
+  })}.signature`
+  return `${encode({ alg: 'EdDSA', typ: 'JWT' })}.${encode({
+    iss: candidate.domainIssuer,
+    sub: 'domain',
+    aud: candidate.kernelIssuer,
+    exp,
+    grant: { v: 1, expr: { kind: 'identity', credential: proof } },
+    ...(malformed === 'outer-delegation' ? { delegation: { credential: proof } } : {}),
+  })}.signature`
+}

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

@@ -0,0 +1,113 @@
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test'
+import {
+  access,
+  mkdir,
+  mkdtemp,
+  readdir,
+  readFile,
+  rm,
+  stat,
+  utimes,
+  writeFile,
+} from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+import { atomicWrite, withFileLock } from '../files'
+
+let temporaryDirectory: string
+
+beforeEach(async () => {
+  temporaryDirectory = await mkdtemp(join(tmpdir(), 'astrale-state-files-'))
+})
+
+afterEach(async () => {
+  await rm(temporaryDirectory, { recursive: true, force: true })
+})
+
+describe('atomicWrite', () => {
+  /** @evidence TEST-CLI-STATE-ATOMIC-WRITE */
+  test('publishes a synced mode-0600 file without temporary residue', async () => {
+    const path = join(temporaryDirectory, 'nested', 'state.json')
+
+    await atomicWrite(path, '{"value":1}')
+
+    expect(await readFile(path, 'utf-8')).toBe('{"value":1}')
+    expect((await stat(path)).mode & 0o777).toBe(0o600)
+    expect(await readdir(join(temporaryDirectory, 'nested'))).toEqual(['state.json'])
+  })
+
+  /** @evidence TEST-CLI-STATE-ATOMIC-WRITE-FAILURE */
+  test('does not disturb the target or retain a temporary file after failure', async () => {
+    const path = join(temporaryDirectory, 'target')
+    await mkdir(path)
+    await writeFile(join(path, 'retained'), 'stable')
+
+    await expect(atomicWrite(path, 'replacement')).rejects.toThrow()
+
+    expect(await readFile(join(path, 'retained'), 'utf-8')).toBe('stable')
+    expect((await readdir(temporaryDirectory)).sort()).toEqual(['target'])
+  })
+})
+
+describe('withFileLock', () => {
+  /** @evidence TEST-CLI-STATE-LOCK-SERIALIZES */
+  test('serializes contending read-modify-write transitions', async () => {
+    const lockPath = join(temporaryDirectory, 'counter.lock')
+    const counterPath = join(temporaryDirectory, 'counter')
+    await writeFile(counterPath, '0')
+
+    const bump = () =>
+      withFileLock(
+        lockPath,
+        async () => {
+          const value = Number(await readFile(counterPath, 'utf-8'))
+          await new Promise((resolve) => setTimeout(resolve, 2))
+          await writeFile(counterPath, String(value + 1))
+        },
+        { pollIntervalMs: 2 },
+      )
+    await Promise.all(Array.from({ length: 20 }, bump))
+
+    expect(await readFile(counterPath, 'utf-8')).toBe('20')
+  })
+
+  /** @evidence TEST-CLI-STATE-LOCK-RECOVERS */
+  test('recovers stale and dead-owner locks', async () => {
+    const stalePath = join(temporaryDirectory, 'stale.lock')
+    await writeFile(stalePath, JSON.stringify({ pid: process.pid }))
+    const past = new Date(Date.now() - 60_000)
+    await utimes(stalePath, past, past)
+    await expect(withFileLock(stalePath, async () => 'stale', { pollIntervalMs: 2 })).resolves.toBe(
+      'stale',
+    )
+
+    const deadPath = join(temporaryDirectory, 'dead.lock')
+    await writeFile(deadPath, JSON.stringify({ pid: 99_999_999 }))
+    await expect(withFileLock(deadPath, async () => 'dead', { pollIntervalMs: 2 })).resolves.toBe(
+      'dead',
+    )
+  })
+
+  /** @evidence TEST-CLI-STATE-LOCK-RELEASES-AND-BOUNDS */
+  test('releases after failure and bounds acquisition behind a live owner', async () => {
+    const releasedPath = join(temporaryDirectory, 'released.lock')
+    await expect(
+      withFileLock(releasedPath, async () => {
+        throw new Error('transition failed')
+      }),
+    ).rejects.toThrow('transition failed')
+    await expect(access(releasedPath)).rejects.toThrow()
+    await expect(withFileLock(releasedPath, async () => 'next')).resolves.toBe('next')
+
+    const heldPath = join(temporaryDirectory, 'held.lock')
+    await writeFile(heldPath, JSON.stringify({ pid: process.pid }))
+    await expect(
+      withFileLock(heldPath, async () => 'unreachable', {
+        pollIntervalMs: 10,
+        staleAfterMs: 60_000,
+        timeoutMs: 40,
+      }),
+    ).rejects.toThrow('Timed out')
+  })
+})

package/src/state/__tests__/fixtures/identity-transition.ts

@@ -0,0 +1,37 @@
+import { updateIdentityStore } from '../../identities'
+
+const [action, name, argument] = process.argv.slice(2)
+
+if (action === 'default' && name !== undefined) {
+  await updateIdentityStore((current) => {
+    if (!current.identities[name]) throw new Error(`Identity "${name}" not found`)
+    return { next: { ...current, default: name }, value: undefined }
+  })
+} else if (action === 'registration' && name !== undefined && argument !== undefined) {
+  await updateIdentityStore((current) => {
+    const identity = current.identities[name]
+    if (!identity) throw new Error(`Identity "${name}" not found`)
+    return {
+      next: {
+        ...current,
+        identities: {
+          ...current.identities,
+          [name]: {
+            ...identity,
+            registrations: {
+              ...identity.registrations,
+              [argument]: {
+                iss: `https://${argument}.example.test`,
+                sub: `${name}-${argument}`,
+                registeredAt: '2025-01-01T00:00:00.000Z',
+              },
+            },
+          },
+        },
+      },
+      value: undefined,
+    }
+  })
+} else {
+  throw new Error('Invalid identity-transition fixture arguments')
+}