@astrale-os/cli 1.0.0-beta.5 → 1.0.0-beta.7

package/src/commands/identity/register.ts

@@ -1,9 +1,9 @@
 import type { IssuerId, JsonWebKey, ProvisionRequest } from '@astrale-os/sdk/auth'
+import type { ClassKey as ClassKeyValue } from '@astrale-os/sdk/graph/class'
 import type { JWK } from 'jose'
 
 import { provision, jwk } from '@astrale-os/sdk/auth'
-import { ClassPath } from '@astrale-os/sdk/graph/class'
-import { LocalBinding } from '@astrale-os/sdk/graph/model'
+import { LocalBinding } from '@astrale-os/sdk/graph'
 import { normalizeProperties } from '@astrale-os/sdk/graph/properties'
 import { MutationAST } from '@astrale-os/sdk/mutation'
 import { importJWK, SignJWT } from 'jose'
@@ -14,6 +14,7 @@ import type { IdentityRegistrationResult } from '../../identity/index'
 import type { CommandDefinition } from '../../program/index'
 
 import { registrationKeyForTarget, runKernelCommand } from '../../connection'
+import { classKey } from '../../graph'
 import { getIdentity, setRegistration, submitIdentityProvision } from '../../identity/index'
 import { fileExists, keypairPaths } from '../../keys/index'
 import { fatal, log } from '../../lib/log'
@@ -83,7 +84,7 @@ Example:
 
       const privateKey = await readJwk(privatePath)
       const publicKey = jwk.acceptPublic(await readJwk(publicPath))
-      const classPath = ClassPath.parse(opts.class)
+      const classPath = classKey(opts.class, '--class')
       const properties = normalizeProperties(opts.props ? JSON.parse(opts.props) : {})
 
       await runKernelCommand<IdentityRegistrationResult>({
@@ -142,7 +143,7 @@ export function formatIdentityRegistration(
 /** Build and self-prove one exact canonical provision request for the target Kernel. */
 export async function prepareIdentityProvision(input: {
   readonly name: string
-  readonly classPath: ReturnType<typeof ClassPath.parse>
+  readonly classPath: ClassKeyValue
   readonly properties: ReturnType<typeof normalizeProperties>
   readonly privateKey: JWK
   readonly publicKey: JsonWebKey

package/src/commands/instance/delete.ts

@@ -1,6 +1,7 @@
 import type { KernelCommandOpts } from '../../connection'
 import type { CommandDefinition } from '../../program/index'
 
+import { AdminInstanceNotFoundError } from '../../admin/instance'
 import { deleteOwnedInstance } from '../../lib/admin-instance'
 import { ADMIN_TARGET_OPTIONS, type AdminTargetCommandOpts } from '../../lib/admin-target'
 import { clearActive, readInstances, removeInstance, resolveInstanceKey } from '../../lib/instance'
@@ -53,9 +54,10 @@ Behavior:
     } catch (e) {
       // Bookmark-only id → no admin Instance → kernel NOT_FOUND. Point to
       // `forget` (local drop) instead of surfacing the raw path error.
-      const notManaged =
-        e instanceof Error && (e.name === 'NotFoundError' || e.message.startsWith('Path not found'))
-      if (notManaged && resolveInstanceKey(await readInstances(), id)) {
+      if (
+        e instanceof AdminInstanceNotFoundError &&
+        resolveInstanceKey(await readInstances(), id)
+      ) {
         log.error(`No admin-managed instance "${id}".`)
         log.dim(`  hint: it's a local bookmark — drop it with: astrale instance forget ${id}`)
         process.exit(1)

package/src/commands/instance/status.ts

@@ -3,7 +3,6 @@ import chalk from 'chalk'
 import type { KernelCommandOpts } from '../../connection'
 import type { CommandDefinition } from '../../program/index'
 
-import { AstraleError } from '../../errors'
 import { statusOwnedInstance } from '../../lib/admin-instance'
 import { ADMIN_TARGET_OPTIONS, type AdminTargetCommandOpts } from '../../lib/admin-target'
 import { fatal, log, withSpinner } from '../../lib/log'
@@ -19,14 +18,7 @@ export default {
   action: async (id: string, opts: StatusOpts) => {
     try {
       const result = await withSpinner(`Fetching instance ${id}`, !isMachine(opts), () =>
-        statusOwnedInstance(opts, id).catch((error) => {
-          if (!(error instanceof Error) || error.name !== 'NotFoundError') throw error
-          throw new AstraleError(
-            'INSTANCE_NOT_FOUND',
-            `No owned instance matches "${id}".`,
-            'Run `astrale instance list` to see your instances.',
-          )
-        }),
+        statusOwnedInstance(opts, id),
       )
       if (isMachine(opts)) {
         output(result, opts)

package/src/commands/introspect.ts

@@ -5,9 +5,9 @@ import type { CommandDefinition } from '../program/index'
 
 import { runKernelCommand } from '../connection'
 import { AstraleError } from '../errors'
-import { failClosed } from '../lib/log'
+import { failInput } from '../lib/log'
 import { output } from '../lib/output'
-import { describeCallableFromSchema, missingCallableDescription } from './call-describe'
+import { describeCallableFromBundle, missingCallableDescription } from './call-describe'
 
 type IntrospectOpts = KernelCommandOpts & { bundle?: boolean }
 
@@ -17,7 +17,7 @@ export async function introspectCommand(target: string, opts: IntrospectOpts): P
   try {
     ;({ origin, path } = parseIntrospectTarget(target))
   } catch (error) {
-    failClosed(error, opts)
+    failInput(error, opts)
   }
   const wantsCallable = isCallablePath(path)
 
@@ -44,7 +44,7 @@ export async function introspectCommand(target: string, opts: IntrospectOpts): P
         )
       }
       if (wantsCallable) {
-        const described = describeCallableFromSchema(path, bundleRoot(result.bundle))
+        const described = describeCallableFromBundle(path, result.bundle)
         if (described === undefined) throw missingCallableDescription(path.raw)
         return described
       }
@@ -85,13 +85,6 @@ function isCallablePath(path: Path): boolean {
   return last.kind === 'projection' && last.projection.kind === 'function'
 }
 
-function bundleRoot(bundle: unknown): unknown {
-  if (bundle !== null && typeof bundle === 'object' && 'root' in bundle) {
-    return (bundle as { root: unknown }).root
-  }
-  return bundle
-}
-
 export default {
   name: 'introspect',
   description: 'Read installed Domain schema from the Kernel Schema syscall',

package/src/commands/logs.ts

@@ -1,21 +1,16 @@
 import { Path } from '@astrale-os/sdk/graph/path'
-import { syscalls } from '@astrale-os/sdk/schema/kernel'
+import { K } from '@astrale-os/sdk/schema'
 import chalk from 'chalk'
 
 import type { ConnectionContext, KernelCommandOpts } from '../connection'
 import type { Column, ListProjection } from '../lib/output'
 import type { CommandDefinition } from '../program/index'
 
-import {
-  createPathCall,
-  expandSelfInPath,
-  runKernelCommand,
-  withClientSession,
-} from '../connection'
-import { failClosed } from '../lib/log'
+import { createPathCall, expandSelfInPath, runKernelCommand } from '../connection'
+import { failInput } from '../lib/log'
 import { isMachine, output, presentList } from '../lib/output'
 
-const JOURNAL_PATH = Path.project(syscalls.journal.ref).raw
+const JOURNAL_PATH = Path.project(K.functions.journal.ref).raw
 const DEFAULT_LIMIT = 200
 const FOLLOW_INTERVAL_MS = 2_000
 
@@ -127,7 +122,7 @@ async function runOnce(opts: LogsOpts): Promise<void> {
   await runKernelCommand({
     opts,
     label: 'Kernel journal',
-    fn: (context) => fetchPage(context, opts),
+    fn: async (context) => fetchPage(context, await resolveLogsOpts(opts, context)),
     format: (page, format) => {
       if (isMachine(format) || format.format !== undefined) output(page, format)
       else {
@@ -139,14 +134,19 @@ async function runOnce(opts: LogsOpts): Promise<void> {
 }
 
 async function follow(opts: LogsOpts): Promise<void> {
-  await withClientSession(opts, async (context) => {
-    let cursor = opts.cursor
-    for (;;) {
-      const page = await fetchPage(context, { ...opts, cursor })
-      for (const record of page.records) printRecord(record)
-      cursor = page.cursor ?? cursor
-      await new Promise((resolve) => setTimeout(resolve, FOLLOW_INTERVAL_MS))
-    }
+  await runKernelCommand({
+    opts,
+    label: 'Kernel journal',
+    fn: async (context): Promise<never> => {
+      const resolved = await resolveLogsOpts(opts, context)
+      let cursor = resolved.cursor
+      for (;;) {
+        const page = await fetchPage(context, { ...resolved, cursor })
+        for (const record of page.records) printRecord(record)
+        cursor = page.cursor ?? cursor
+        await new Promise((resolve) => setTimeout(resolve, FOLLOW_INTERVAL_MS))
+      }
+    },
   })
 }
 
@@ -227,11 +227,10 @@ function positiveInteger(flag: string, raw: string): number {
   return value
 }
 
-async function prepareLogsOpts(opts: LogsOpts): Promise<LogsOpts> {
-  buildJournalInput(opts)
+async function resolveLogsOpts(opts: LogsOpts, context: ConnectionContext): Promise<LogsOpts> {
   const principal = nonEmpty(opts.principal)
   if (principal !== '@self') return opts
-  const { path } = await expandSelfInPath('@self', opts)
+  const { path } = await expandSelfInPath('@self', context)
   return { ...opts, principal: path.startsWith('@') ? path.slice(1) : path }
 }
 
@@ -274,11 +273,11 @@ Examples:
   ],
   action: async (opts: LogsOpts) => {
     try {
-      const prepared = await prepareLogsOpts(opts)
-      if (prepared.follow) await follow(prepared)
-      else await runOnce(prepared)
+      buildJournalInput(opts)
     } catch (error) {
-      failClosed(error, opts)
+      failInput(error, opts)
     }
+    if (opts.follow) await follow(opts)
+    else await runOnce(opts)
   },
 } satisfies CommandDefinition

package/src/commands/mutate.ts

@@ -7,8 +7,9 @@ import type { KernelCommandOpts } from '../connection'
 import type { CommandDefinition } from '../program/index'
 
 import { runKernelCommand } from '../connection'
+import { AstraleError } from '../errors'
 import { prepareMutation } from '../graph/index'
-import { failClosed } from '../lib/log'
+import { failInput } from '../lib/log'
 import { output } from '../lib/output'
 import { renderTable } from '../lib/table'
 
@@ -23,7 +24,7 @@ export async function mutateCommand(opts: MutateOpts): Promise<void> {
   try {
     mutation = prepareMutation(await readDocument(opts))
   } catch (error) {
-    failClosed(error, opts)
+    failInput(error, opts)
   }
 
   if (opts.dry) {
@@ -51,9 +52,9 @@ async function readDocument(opts: MutateOpts): Promise<unknown> {
     try {
       raw = await readFile(opts.file, 'utf8')
     } catch (error) {
-      throw new Error(
-        `Cannot read --file ${opts.file}: ${error instanceof Error ? error.message : error}`,
-      )
+      throw new AstraleError('FILE_READ_FAILED', `Cannot read --file ${opts.file}.`, undefined, {
+        cause: error,
+      })
     }
     return parseJson(raw, opts.file)
   }

package/src/commands/query.ts

@@ -6,8 +6,9 @@ import type { KernelCommandOpts, SelfExpansionMeta } from '../connection'
 import type { CommandDefinition } from '../program/index'
 
 import { expandSelfInPath, runKernelCommand, withSelfHint } from '../connection'
+import { AstraleError } from '../errors'
 import { prepareQuery, type QueryCommandInput } from '../graph/index'
-import { failClosed } from '../lib/log'
+import { failInput } from '../lib/log'
 import { isMachine, output } from '../lib/output'
 
 type QueryOpts = KernelCommandOpts & {
@@ -22,46 +23,42 @@ type QueryOpts = KernelCommandOpts & {
 
 export async function queryCommand(sources: string[], opts: QueryOpts): Promise<void> {
   let input: QueryCommandInput
-  let meta: SelfExpansionMeta | undefined
   try {
     const ast = await readAst(opts)
-    if (ast === undefined) {
-      const expanded = await Promise.all(sources.map((source) => expandSelfInPath(source, opts)))
-      input = {
-        sources: expanded.map(({ path }) => path),
-        definition: opts.definition,
-        edge: opts.edge,
-        direction: opts.direction,
-        limit: opts.limit,
-        cursor: opts.cursor,
-      }
-      meta = expanded.find((entry) => entry.meta !== undefined)?.meta
-    } else {
-      input = {
-        sources,
-        ast,
-        definition: opts.definition,
-        edge: opts.edge,
-        direction: opts.direction,
-        limit: opts.limit,
-        cursor: opts.cursor,
-      }
+    input = {
+      sources,
+      ...(ast === undefined ? {} : { ast }),
+      definition: opts.definition,
+      edge: opts.edge,
+      direction: opts.direction,
+      limit: opts.limit,
+      cursor: opts.cursor,
     }
   } catch (error) {
-    failClosed(error, opts)
+    failInput(error, opts)
   }
 
   let prepared
   try {
     prepared = prepareQuery(input)
   } catch (error) {
-    failClosed(error, opts)
+    failInput(error, opts)
   }
 
   await runKernelCommand({
     opts,
     label: 'Query',
-    fn: ({ graph }) => withSelfHint(() => graph.query(prepared.ast, { page: prepared.page }), meta),
+    fn: async (context) => {
+      const expanded = await Promise.all(sources.map((source) => expandSelfInPath(source, context)))
+      const meta: SelfExpansionMeta | undefined = expanded.find(
+        (entry) => entry.meta !== undefined,
+      )?.meta
+      const resolved =
+        meta === undefined
+          ? prepared
+          : prepareQuery({ ...input, sources: expanded.map(({ path }) => path) })
+      return withSelfHint(() => context.graph.query(resolved.ast, { page: resolved.page }), meta)
+    },
     format: (response, format) => {
       output(response.result, format)
       if (response.page.next && !isMachine(format)) {
@@ -81,9 +78,9 @@ async function readAst(opts: QueryOpts): Promise<unknown | undefined> {
   try {
     raw = await readFile(opts.file, 'utf8')
   } catch (error) {
-    throw new Error(
-      `Cannot read --file ${opts.file}: ${error instanceof Error ? error.message : error}`,
-    )
+    throw new AstraleError('FILE_READ_FAILED', `Cannot read --file ${opts.file}.`, undefined, {
+      cause: error,
+    })
   }
   return parseJson(raw, opts.file)
 }
@@ -122,7 +119,7 @@ Examples:
     { flags: '-f, --file <path>', description: 'Read a canonical Query V6 document from a file' },
     {
       flags: '--definition <path>',
-      description: 'Select Nodes implementing one exact Class or Interface',
+      description: 'Select Nodes satisfying one exact Class',
     },
     { flags: '--edge <class>', description: 'Expand one exact Edge Class' },
     {

package/src/commands/token.ts

@@ -6,7 +6,7 @@ import type { CommandDefinition } from '../program/index'
 import { runKernelCommand } from '../connection'
 import { AstraleError } from '../errors'
 import { decodeJwtExpiration } from '../lib/local-status'
-import { failClosed, log } from '../lib/log'
+import { failInput, log } from '../lib/log'
 import { output } from '../lib/output'
 
 /**
@@ -23,7 +23,12 @@ export type TokenOpts = KernelCommandOpts & {
 
 export async function tokenCommand(opts: TokenOpts): Promise<void> {
   const commandOpts: TokenOpts = opts.for && !opts.as ? { ...opts, as: opts.for } : opts
-  const ttl = parseTtl(commandOpts.ttl)
+  let ttl: number
+  try {
+    ttl = parseTtl(commandOpts.ttl)
+  } catch (error) {
+    failInput(error, opts)
+  }
   await runKernelCommand<string>({
     opts: commandOpts,
     label: 'Minting delegation token',
@@ -97,10 +102,6 @@ Examples:
     { flags: '--for <identity>', description: 'Mint the token for this identity (alias of --as)' },
   ],
   action: async (opts) => {
-    try {
-      await tokenCommand(opts as Parameters<typeof tokenCommand>[0])
-    } catch (error) {
-      failClosed(error, opts as TokenOpts)
-    }
+    await tokenCommand(opts as Parameters<typeof tokenCommand>[0])
   },
 } satisfies CommandDefinition

package/src/commands/view.ts

@@ -89,9 +89,10 @@ export async function resolveSession(
   }
   const targetInput =
     parsed.kind === 'target' ? parsed.path : (opts.target ?? viewOwnerTarget(parsed.path))
-  const { path: target } = await expandSelfInPath(targetInput, opts)
-
-  const candidates = await withClientSession(opts, (ctx) => resolveViewCandidates(ctx, target))
+  const { target, candidates } = await withClientSession(opts, async (context) => {
+    const { path: target } = await expandSelfInPath(targetInput, context)
+    return { target, candidates: await resolveViewCandidates(context, target) }
+  })
 
   if (opts.list) {
     return { candidates }

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

@@ -1,8 +1,7 @@
-import type { Call } from '@astrale-os/kernel-client'
-import type { AuthApi } from '@astrale-os/kernel-client/auth'
-import type { GraphApi } from '@astrale-os/kernel-client/graph'
-import type { ClientSession } from '@astrale-os/kernel-client/session'
 import type { IssuerId } from '@astrale-os/sdk/auth'
+import type { AuthApi } from '@astrale-os/sdk/auth'
+import type { Call, GraphApi } from '@astrale-os/sdk/client'
+import type { ClientSession } from '@astrale-os/sdk/client/session'
 
 /** Existing CLI connection flags accepted by Kernel-touching commands. */
 export interface ConnectionOptions {
@@ -78,17 +77,17 @@ export function withAdminClientSession<Value>(
 /** Expand @self through the effective principal returned by authenticated Identity.whoami. */
 export function expandSelfInPath(
   path: string,
-  options: KernelCommandOpts,
+  context: ConnectionContext,
 ): Promise<{ readonly path: string; readonly meta?: SelfExpansionMeta }>
 
 /** Expand @self once across one Call path and its CLI-authored string parameters. */
 export function expandSelfInCall(
   path: string,
-  parameters: readonly string[],
-  options: KernelCommandOpts,
+  parameters: Readonly<Record<string, unknown>>,
+  context: ConnectionContext,
 ): Promise<{
   readonly path: string
-  readonly parameters: readonly string[]
+  readonly parameters: Readonly<Record<string, unknown>>
   readonly meta?: SelfExpansionMeta
 }>
 

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

@@ -40,7 +40,8 @@ customizes only the Fetch capability passed to Client. `withClientSession` and
 `withAdminClientSession` are terminal lifecycle boundaries: success, failure, and cancellation all
 close both the Client Session and its direct source-Auth client.
 
-The command boundary maps typed Client transport phase and delivery evidence without inspecting a
-private cause message. It preserves every admitted Kernel reason in machine output; human repair
-details are rendered only after the connection owner admits bounded public Function issues or one
-exact Query reason variant.
+The command boundary projects typed Client failure identity, transport context, phase, and
+invocation-only delivery evidence without inspecting a private cause message. Unknown native
+failures become one honest unexpected diagnostic; their bounded cause graph is visible only under
+explicit debug output. Every admitted Kernel reason remains available in machine output, while
+human repair details require a bounded public Function issue or exact Query reason variant.

package/src/connection/.spec/flows/session.ts

@@ -1,5 +1,5 @@
-import type { SessionAuth } from '@astrale-os/kernel-client/session'
-import type { Call } from '@astrale-os/kernel-protocol/invocation'
+import type { Call } from '@astrale-os/sdk/client'
+import type { SessionAuth } from '@astrale-os/sdk/client/session'
 
 import type { ConnectionContext, ConnectionOptions, ConnectionTarget } from '../api.js'
 

package/src/connection/.spec/laws/connection.ts

@@ -111,7 +111,7 @@ export const CLI_AUTH_REGISTRATION_TARGET = defineLaw({
 export const CLI_SELF_AUTHENTICATED_PRINCIPAL = defineLaw({
   id: 'CLI-SELF-AUTHENTICATED-PRINCIPAL',
   statement:
-    '@self resolves only from authenticated Identity.whoami on the selected target, so delegated carriers use their effective principal and never an unverified JWT subject or stale local registration.',
+    '@self resolves inside the command-owned Client Session from authenticated Identity.whoami on the selected target, so resolution and dispatch share one lifecycle and delegated carriers never use an unverified JWT subject or stale local registration.',
   tests: [
     {
       file: '__tests__/self.test.ts',
@@ -183,7 +183,7 @@ export const CLI_CONNECTION_PUBLIC_SEMANTIC_REASON = defineLaw({
 export const CLI_CONNECTION_TYPED_ERROR_PRESENTATION = defineLaw({
   id: 'CLI-CONNECTION-TYPED-ERROR-PRESENTATION',
   statement:
-    'The command boundary maps typed Client transport phase and delivery evidence without parsing a private cause, preserves the admitted Kernel reason in machine output, and renders only bounded public Function issues or one exact Query repair variant for humans.',
+    'The command boundary maps typed Client failure identity, transport context, phase, and invocation-only delivery evidence without parsing a private cause; acquisition never receives retry advice, unknown native failures have one non-blank unexpected diagnostic, and raw causes appear only under explicit debug output.',
   tests: [
     {
       file: '__tests__/errors.test.ts',
@@ -197,5 +197,9 @@ export const CLI_CONNECTION_TYPED_ERROR_PRESENTATION = defineLaw({
       file: '__tests__/reasons.test.ts',
       id: 'TEST-CLI-CONNECTION-ADMITS-BOUNDED-REASONS',
     },
+    {
+      file: '__tests__/failure-safety.test.ts',
+      id: 'TEST-CLI-CONNECTION-FAILURE-SAFETY',
+    },
   ],
 })

package/src/connection/.spec/layout.ts

@@ -8,6 +8,7 @@ export default defineLayout({
     'command.ts',
     'credential.ts',
     'errors.ts',
+    'failure/',
     'exchange.ts',
     'index.ts',
     'reasons.ts',

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

@@ -1,4 +1,4 @@
-import type { SessionAuth } from '@astrale-os/kernel-client/session'
+import type { SessionAuth } from '@astrale-os/sdk/client/session'
 
 import { issuer, type IssuerId } from '@astrale-os/sdk/auth'
 import { Path } from '@astrale-os/sdk/graph/path'

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

@@ -1,7 +1,9 @@
-import { ResponseError, TransportError } from '@astrale-os/kernel-client'
+import { ResponseError } from '@astrale-os/sdk/client'
+import { Path } from '@astrale-os/sdk/graph/path'
 import { describe, expect, test } from 'bun:test'
 
 import { formatKernelError, functionInputIssues, schemaUpgradeHint } from '../errors'
+import { transportFailure } from './failure-fixtures'
 
 const CONFLICT = 4001
 const VALIDATION = 1003
@@ -19,24 +21,28 @@ describe('formatKernelError', () => {
       writes.push(typeof chunk === 'string' ? chunk : new TextDecoder().decode(chunk))
       return true
     }) as typeof process.stderr.write
-    const error = new TransportError('Publication discovery request failed.', {
-      cause: Object.assign(new Error('connect ECONNREFUSED'), { code: 'ECONNREFUSED' }),
-      phase: 'connect',
-      delivery: 'unknown',
-    }) as TransportError & { url?: string }
-    error.url = 'https://localhost:8443/kernel/host'
+    const error = Object.assign(
+      transportFailure('Publication discovery request failed.', 'unknown', {
+        kind: 'acquisition',
+        resource: 'publication',
+      }),
+      {
+        url: 'https://localhost:8443/kernel/host',
+        cause: Object.assign(new Error('connect ECONNREFUSED'), { code: 'ECONNREFUSED' }),
+      },
+    )
     try {
-      await formatKernelError(error, true)
+      await formatKernelError(error, true, 'https://localhost:8443/kernel/host')
     } finally {
       process.stderr.write = original
     }
 
     expect(JSON.parse(writes[0]!)).toMatchObject({
-      error: 'CONNECTION_ERROR',
+      error: 'TRANSPORT_ERROR',
       message: 'Publication discovery request failed.',
       url: 'https://localhost:8443/kernel/host',
-      phase: 'connect',
-      delivery: 'unknown',
+      phase: 'unknown',
+      transport: { kind: 'acquisition', resource: 'publication' },
     })
     expect(writes[0]).not.toContain('ECONNREFUSED')
   })
@@ -50,9 +56,8 @@ describe('formatKernelError', () => {
     }) as typeof process.stderr.write
     try {
       await formatKernelError(
-        new TransportError('Request timed out.', {
-          cause: new Error('timeout'),
-          phase: 'timeout',
+        transportFailure('Request timed out.', 'timeout', {
+          kind: 'invocation',
           delivery: 'unknown',
         }),
         true,
@@ -74,7 +79,7 @@ describe('formatKernelError', () => {
     expect(JSON.parse(writes[0]!)).toMatchObject({
       error: 'TIMEOUT',
       phase: 'timeout',
-      delivery: 'unknown',
+      transport: { kind: 'invocation', delivery: 'unknown' },
       operation: '4a4c9a18-50f6-4d84-a7b7-2d83e3e45dc8',
       retry:
         'astrale domain install https://crm.test --direct --operation 4a4c9a18-50f6-4d84-a7b7-2d83e3e45dc8',
@@ -229,7 +234,7 @@ describe('formatKernelError', () => {
     )
   })
 
-  test('maps SDK class names to stable CLI error codes', async () => {
+  test('maps SDK error identities to stable CLI error codes', async () => {
     const writes: string[] = []
     const original = process.stderr.write
     process.stderr.write = ((chunk: string | Uint8Array) => {
@@ -237,15 +242,17 @@ describe('formatKernelError', () => {
       return true
     }) as typeof process.stderr.write
     try {
-      const pathError = new Error('Path must have an Id or Domain anchor.')
-      pathError.name = 'PathError'
-      await formatKernelError(pathError, true)
+      try {
+        Path.parse('not-a-path')
+      } catch (error) {
+        await formatKernelError(error, true)
+      }
     } finally {
       process.stderr.write = original
     }
     expect(JSON.parse(writes[0]!)).toEqual({
       error: 'PATH_INVALID',
-      message: 'Path must have an Id or Domain anchor.',
+      message: expect.any(String),
     })
   })
 

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

@@ -1,4 +1,4 @@
-import type { Fetch } from '@astrale-os/kernel-client'
+import type { Fetch } from '@astrale-os/sdk/client'
 
 import { issuer } from '@astrale-os/sdk/auth'
 import { afterEach, beforeEach, describe, expect, test } from 'bun:test'
@@ -190,6 +190,35 @@ describe('Domain token exchange', () => {
       message: 'Token exchange returned an invalid success response.',
     })
   })
+
+  test('normalizes native issuer Fetch failures without exposing their message', async () => {
+    const native = new AggregateError([new Error('private DNS state')], '')
+    const resolver = createExchangeCredentialResolver(
+      TARGET,
+      { resolve: async () => SOURCE_TOKEN },
+      async (input, init) => {
+        if (String(input) === INVOCATION) {
+          const body = JSON.parse(await new Response(init?.body).text()) as Record<string, any>
+          return invocationResponse(
+            body.requestId,
+            body.call.input && Object.keys(body.call.input).length === 0
+              ? { id: 'user-1' }
+              : 'kernel-destination-envelope',
+            new Headers(init?.headers).get('accept')!,
+          )
+        }
+        throw native
+      },
+      5_000,
+      new ExchangeCredentialCache(join(directory, 'native-failure.json')),
+    )
+
+    await expect(resolver.resolve(KERNEL, new AbortController().signal)).rejects.toMatchObject({
+      code: 'TOKEN_EXCHANGE_UNAVAILABLE',
+      message: 'Domain issuer discovery could not be reached.',
+      cause: native,
+    })
+  })
 })
 
 function exchangeFetch(