@astrale-os/cli 0.8.1-alpha.7 → 1.0.0-beta.1

package/src/commands/__tests__/domain-install-owned.test.ts

@@ -1,3 +1,4 @@
+import { ResponseError } from '@astrale-os/kernel-client'
 import { afterEach, beforeEach, describe, expect, mock, test } from 'bun:test'
 
 import type { OwnedInstanceInfo } from '../../lib/admin-instance'
@@ -118,4 +119,69 @@ describe('admin domain install owner boundary', () => {
     expect(calls).toEqual([])
     expect(calls).toEqual([])
   })
+
+  test('preserves an incompatible issuer reason returned through Admin', async () => {
+    inventory = [
+      {
+        id: 'owned-id',
+        slug: 'owned',
+        url: 'https://owned.eu.astrale.ai',
+        state: 'ready',
+      },
+    ]
+    const domain = {
+      id: 'crm-id',
+      origin: 'crm.acme.dev',
+      name: 'CRM',
+      url: 'https://crm.acme.dev',
+      createdAt: '2026-08-20T00:00:00.000Z',
+      updatedAt: '2026-08-20T00:00:00.000Z',
+    }
+    const failure = new ResponseError(5001, 'Schema operation is not supported.', {
+      code: 'SCHEMA_UPGRADE_INCOMPATIBLE',
+      details: {
+        phase: 'upgrade',
+        origin: domain.origin,
+        issue: 'issuer-changed',
+        installedIssuer: 'https://old.example',
+        replacementIssuer: 'https://new.example',
+      },
+    })
+    const { installViaAdmin } = await import('../domain/install')
+
+    await expect(
+      installViaAdmin(
+        domain.origin,
+        {
+          instance: 'owned',
+          json: true,
+          noPrompt: true,
+        },
+        {
+          listInstances: async () => inventory,
+          listDomains: async () => [domain],
+          install: async () => {
+            throw failure
+          },
+        },
+      ),
+    ).rejects.toEqual(new ExitError(1))
+
+    expect(JSON.parse(stderr)).toEqual({
+      error: 'RESPONSE_ERROR',
+      code: 5001,
+      message: 'Schema operation is not supported.',
+      reason: {
+        code: 'SCHEMA_UPGRADE_INCOMPATIBLE',
+        details: {
+          phase: 'upgrade',
+          origin: 'crm.acme.dev',
+          issue: 'issuer-changed',
+          installedIssuer: 'https://old.example',
+          replacementIssuer: 'https://new.example',
+        },
+      },
+      hint: expect.stringContaining('astrale domain uninstall crm.acme.dev'),
+    })
+  })
 })

package/src/commands/__tests__/install-direct.test.ts

@@ -4,8 +4,9 @@ import { directInstallCallInput } from '../domain/install'
 
 describe('directInstallCallInput', () => {
   test('sends the current remote install syscall, not a legacy url list', () => {
-    expect(directInstallCallInput('https://tasks.example.test', 'secret', 'op-1')).toEqual({
-      operation: 'op-1',
+    const operation = '4a4c9a18-50f6-4d84-a7b7-2d83e3e45dc8'
+    expect(directInstallCallInput('https://tasks.example.test', operation, 'secret')).toEqual({
+      operation,
       domains: [
         {
           source: {

package/src/commands/__tests__/update.test.ts

@@ -0,0 +1,66 @@
+import { describe, expect, mock, test } from 'bun:test'
+
+import { cliStale, fetchNpmTargetVersion } from '../update'
+
+describe('CLI update staleness', () => {
+  test('trusts the release manifest for a script install without consulting npm latest', async () => {
+    const fetchPackageVersion = mock(async () => '0.8.1-alpha.7')
+    const result = await cliStale(
+      { channel: 'beta' },
+      {
+        update: async () => ({
+          status: 'up-to-date',
+          currentVersion: '1.0.0-beta.0',
+          latestVersion: '1.0.0-beta.0',
+          channel: 'beta',
+        }),
+        fetchPackageVersion,
+      },
+    )
+
+    expect(result).toEqual({
+      stale: false,
+      managed: false,
+      current: '1.0.0-beta.0',
+      latest: '1.0.0-beta.0',
+      channel: 'beta',
+    })
+    expect(fetchPackageVersion).not.toHaveBeenCalled()
+  })
+
+  test('uses the selected npm dist-tag only for package-managed installs', async () => {
+    const result = await cliStale(
+      { channel: 'beta' },
+      {
+        update: async () => {
+          throw new Error('package managed')
+        },
+        fetchPackageVersion: async ({ channel }) => {
+          expect(channel).toBe('beta')
+          return '1.0.0-beta.0'
+        },
+      },
+    )
+
+    expect(result).toMatchObject({
+      managed: true,
+      latest: '1.0.0-beta.0',
+      channel: 'npm',
+    })
+  })
+
+  test('maps the stable channel to the npm latest dist-tag', async () => {
+    const originalFetch = globalThis.fetch
+    const fetchMock = mock(async (input: RequestInfo | URL) => {
+      expect(String(input)).toBe('https://registry.npmjs.org/@astrale-os/cli/latest')
+      return Response.json({ version: '1.0.0' })
+    })
+    globalThis.fetch = fetchMock as unknown as typeof fetch
+    try {
+      expect(await fetchNpmTargetVersion({ channel: 'stable' })).toBe('1.0.0')
+      expect(fetchMock).toHaveBeenCalledTimes(1)
+    } finally {
+      globalThis.fetch = originalFetch
+    }
+  })
+})

package/src/commands/domain/install.ts

@@ -6,6 +6,7 @@ import type { KernelCommandOpts } from '../../connection'
 import type { CommandDefinition } from '../../program/index'
 
 import { createPathCall, runKernelCommand, withAdminClientSession } from '../../connection'
+import { formatKernelError } from '../../connection/errors'
 import { AstraleError } from '../../errors'
 import {
   installAdminDomainInContext,
@@ -21,11 +22,7 @@ import { confirmWithInput, promptText, selectFrom } from '../../lib/prompt'
 import { isHttpUrl } from '../../lib/validation'
 
 /** Public Kernel install syscall input for one remote URL. */
-export function directInstallCallInput(
-  url: string,
-  token?: string,
-  operation: string = crypto.randomUUID(),
-) {
+export function directInstallCallInput(url: string, operation: string, token?: string) {
   return Object.freeze({
     operation,
     domains: [
@@ -50,9 +47,28 @@ type DirectInstallResult = {
   }[]
 }
 
+const OPERATION_ID_PATTERN =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/u
+
+function acceptOperationId(input: unknown): string {
+  if (typeof input !== 'string' || !OPERATION_ID_PATTERN.test(input)) {
+    throw new AstraleError(
+      'INVALID_FLAG',
+      '--operation must be a canonical lowercase UUIDv4.',
+      'Omit --operation for a fresh install; use it only with the exact UUID printed for recovery.',
+    )
+  }
+  return input
+}
+
+function createOperationId(): string {
+  return acceptOperationId(globalThis.crypto.randomUUID())
+}
+
 type InstallOpts = KernelCommandOpts &
   AdminTargetCommandOpts & {
     direct?: boolean
+    operation?: string
     token?: string
     allowIdentityOverride?: boolean
     // Global flags (program.ts) that force non-interactive.
@@ -78,6 +94,10 @@ Behavior:
   origin differs from its serving host, it requires explicit consent (an
   interactive DANGER prompt, or --allow-identity-override in scripts).
 
+  A fresh, strong operation id is generated automatically. Use --operation
+  only to retry or recover the exact same direct install after an outcome-unknown
+  timeout or disconnect.
+
 Examples:
   $ astrale domain install crm.acme.dev -i staging          # by origin, via admin
   $ astrale domain install https://crm.acme.dev             # by url, via admin
@@ -103,12 +123,26 @@ Examples:
       flags: '--token <token>',
       description: 'Bearer token for private domain install endpoints (--direct only)',
     },
+    {
+      flags: '--operation <uuid>',
+      description: 'Reuse an exact direct-install operation id for explicit retry/recovery',
+    },
     {
       flags: '--allow-identity-override',
       description: 'Consent to a domain whose origin differs from its serving host (--direct only)',
     },
   ],
   action: async (target: string | undefined, opts: InstallOpts) => {
+    if (opts.operation !== undefined && !opts.direct) {
+      fatal(
+        new AstraleError(
+          'INVALID_FLAG',
+          '--operation is valid only with --direct.',
+          'Ordinary direct installs generate a fresh operation id automatically.',
+        ),
+        opts,
+      )
+    }
     if (opts.direct) {
       await installDirect(target, opts)
       return
@@ -197,8 +231,9 @@ export async function installViaAdmin(
       log.dim(`  origin: ${result.origin}`)
       log.dim(`  url:    ${result.url}`)
     })
-  } catch (e) {
-    fatal(e, opts)
+  } catch (error) {
+    await formatKernelError(error, isMachine(opts), undefined, opts.debug)
+    process.exit(1)
   }
 }
 
@@ -326,9 +361,27 @@ async function activeSlug(): Promise<string | undefined> {
  * bypassing the admin catalog, with the identity-override
  * consent gate. Works on any instance the caller can authenticate to.
  */
-async function installDirect(target: string | undefined, opts: InstallOpts): Promise<void> {
+interface DirectInstallDependencies {
+  readonly acceptOperationId: (input: unknown) => string
+  readonly createOperationId: () => string
+  readonly runKernelCommand: typeof runKernelCommand
+}
+
+const defaultDirectInstallDependencies: DirectInstallDependencies = Object.freeze({
+  acceptOperationId,
+  createOperationId,
+  runKernelCommand,
+})
+
+export async function installDirect(
+  target: string | undefined,
+  opts: InstallOpts,
+  dependencies: Partial<DirectInstallDependencies> = {},
+): Promise<void> {
+  const direct = { ...defaultDirectInstallDependencies, ...dependencies }
   let host = ''
   let consentedOrigin: string | undefined
+  let operation: string
   try {
     if (!target) {
       throw new AstraleError(
@@ -338,24 +391,30 @@ async function installDirect(target: string | undefined, opts: InstallOpts): Pro
       )
     }
     host = validateInstallUrl(target)
+    operation =
+      opts.operation === undefined
+        ? direct.createOperationId()
+        : direct.acceptOperationId(opts.operation)
     consentedOrigin = await ensureIdentityOverrideConsent(
       target,
       host,
       opts.allowIdentityOverride ?? false,
     )
   } catch (e) {
-    fatal(e)
+    fatal(e, opts)
   }
   const url = target as string
+  const retry = directInstallRetry(url, operation, opts)
 
-  await runKernelCommand<DirectInstallResult>({
+  await direct.runKernelCommand<DirectInstallResult>({
     opts,
-    label: `Installing domain from ${url}`,
+    label: `Installing domain from ${url} (operation ${operation})`,
+    recovery: { operation, retry },
     fn: async ({ session }) =>
       (await session.call(
         createPathCall(
           Path.project(syscalls.install.ref).raw,
-          directInstallCallInput(url, opts.token),
+          directInstallCallInput(url, operation, opts.token),
         ),
       )) as DirectInstallResult,
     format: (result, fmtOpts, isRaw) => {
@@ -364,11 +423,10 @@ async function installDirect(target: string | undefined, opts: InstallOpts): Pro
         return
       }
       const installed = result.transitions[0]?.intent
-      if (installed === undefined) {
-        throw new Error('Kernel install returned no committed Domain transition.')
-      }
+      if (!installed) throw new Error('Kernel install returned no committed Domain transition.')
       const revision = installed.target?.schemaRevision ?? result.operation
       log.success(`Domain installed: ${installed.origin}@${revision}`)
+      log.dim(`  operation:   ${result.operation}`)
       // Belt-and-braces: the kernel-confirmed origin is authoritative. If it
       // aliases the host and the pre-install gate never consented to THAT
       // origin (lying or absent `/meta`), say so loudly after the fact.
@@ -383,6 +441,11 @@ async function installDirect(target: string | undefined, opts: InstallOpts): Pro
   })
 }
 
+function directInstallRetry(url: string, operation: string, opts: InstallOpts): string {
+  const instance = opts.instance === undefined ? '' : ` -i ${opts.instance}`
+  return `astrale domain install ${url} --direct --operation ${operation}${instance}`
+}
+
 function validateInstallUrl(value: string): string {
   let url: URL
   try {

package/src/commands/update.ts

@@ -115,27 +115,46 @@ export type StaleReport = {
   sdk: { stale: boolean; inProject: boolean; outdated: SdkOutdated[] }
 }
 
-async function cliStale(opts: UpdateOpts): Promise<StaleReport['cli']> {
+type CliStaleDependencies = {
+  update: typeof updateAstrale
+  fetchPackageVersion: (opts: Pick<UpdateOpts, 'channel' | 'version'>) => Promise<string>
+}
+
+const CLI_STALE_DEPENDENCIES: CliStaleDependencies = {
+  update: updateAstrale,
+  fetchPackageVersion: fetchNpmTargetVersion,
+}
+
+export async function cliStale(
+  opts: Pick<UpdateOpts, 'channel' | 'version'>,
+  dependencies: CliStaleDependencies = CLI_STALE_DEPENDENCIES,
+): Promise<StaleReport['cli']> {
   const running = pkg.version
-  const latest = await fetchNpmLatestVersion().catch(() => undefined)
   try {
-    const r = await updateAstrale({
+    const r = await dependencies.update({
       check: true,
       channel: opts.channel,
       version: opts.version,
       currentVersion: running,
     })
     if (r.status === 'updated') {
-      return { stale: false, managed: false, current: running, latest: latest ?? running }
+      return {
+        stale: false,
+        managed: false,
+        current: r.currentVersion,
+        latest: r.currentVersion,
+        channel: r.channel,
+      }
     }
     return {
-      stale: latest !== undefined ? latest !== running : r.status === 'available',
+      stale: r.status === 'available',
       managed: false,
-      current: running,
-      latest: latest ?? r.latestVersion,
-      channel: latest !== undefined ? 'npm' : r.channel,
+      current: r.currentVersion,
+      latest: r.latestVersion,
+      channel: r.channel,
     }
   } catch {
+    const latest = await dependencies.fetchPackageVersion(opts).catch(() => undefined)
     return {
       stale: latest !== undefined && latest !== running,
       managed: true,
@@ -145,8 +164,11 @@ async function cliStale(opts: UpdateOpts): Promise<StaleReport['cli']> {
   }
 }
 
-async function fetchNpmLatestVersion(): Promise<string> {
-  const response = await fetch('https://registry.npmjs.org/@astrale-os/cli/latest')
+export async function fetchNpmTargetVersion(
+  opts: Pick<UpdateOpts, 'channel' | 'version'>,
+): Promise<string> {
+  const target = opts.version ?? (opts.channel === 'stable' ? 'latest' : opts.channel) ?? 'latest'
+  const response = await fetch(`https://registry.npmjs.org/@astrale-os/cli/${target}`)
   if (!response.ok) throw new Error(`npm registry HTTP ${response.status}`)
   const body: unknown = await response.json()
   if (

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

@@ -37,6 +37,46 @@ describe('formatKernelError', () => {
     expect(writes[0]).not.toContain('ECONNREFUSED')
   })
 
+  test('retains operation recovery only for outcome-unknown transport failure', async () => {
+    const writes: string[] = []
+    const original = process.stderr.write
+    process.stderr.write = ((chunk: string | Uint8Array) => {
+      writes.push(typeof chunk === 'string' ? chunk : new TextDecoder().decode(chunk))
+      return true
+    }) as typeof process.stderr.write
+    try {
+      await formatKernelError(
+        new TransportError('Request timed out.', {
+          cause: new Error('timeout'),
+          phase: 'timeout',
+          delivery: 'unknown',
+        }),
+        true,
+        undefined,
+        false,
+        {
+          recovery: {
+            operation: '4a4c9a18-50f6-4d84-a7b7-2d83e3e45dc8',
+            retry:
+              'astrale domain install https://crm.test --direct --operation 4a4c9a18-50f6-4d84-a7b7-2d83e3e45dc8',
+          },
+        },
+      )
+    } finally {
+      process.stderr.write = original
+    }
+
+    expect(writes).toHaveLength(1)
+    expect(JSON.parse(writes[0]!)).toMatchObject({
+      error: 'TIMEOUT',
+      phase: 'timeout',
+      delivery: 'unknown',
+      operation: '4a4c9a18-50f6-4d84-a7b7-2d83e3e45dc8',
+      retry:
+        'astrale domain install https://crm.test --direct --operation 4a4c9a18-50f6-4d84-a7b7-2d83e3e45dc8',
+    })
+  })
+
   /** @evidence TEST-CLI-CONNECTION-PRESERVES-PUBLIC-SEMANTIC-REASON */
   test('preserves a Kernel-admitted semantic reason in machine output', async () => {
     const writes: string[] = []
@@ -275,8 +315,9 @@ describe('formatKernelError', () => {
           details: {
             phase: 'upgrade',
             origin: 'grc.example',
-            expected: 'https://old.example',
-            actual: 'https://new.example',
+            issue: 'issuer-changed',
+            installedIssuer: 'https://old.example',
+            replacementIssuer: 'https://new.example',
           },
         }),
         true,
@@ -294,18 +335,53 @@ describe('formatKernelError', () => {
         details: {
           phase: 'upgrade',
           origin: 'grc.example',
-          expected: 'https://old.example',
-          actual: 'https://new.example',
+          issue: 'issuer-changed',
+          installedIssuer: 'https://old.example',
+          replacementIssuer: 'https://new.example',
         },
       },
       hint: schemaUpgradeHint({
         origin: 'grc.example',
-        expected: 'https://old.example',
-        actual: 'https://new.example',
+        issue: 'issuer-changed',
+        installedIssuer: 'https://old.example',
+        replacementIssuer: 'https://new.example',
       }),
     })
   })
 
+  test('prints both issuers and the recovery command for an incompatible replacement', async () => {
+    const errors: string[] = []
+    const details: string[] = []
+    const originalError = console.error
+    const originalLog = console.log
+    console.error = (...values: unknown[]) => errors.push(values.map(String).join(' '))
+    console.log = (...values: unknown[]) => details.push(values.map(String).join(' '))
+    try {
+      await formatKernelError(
+        new ResponseError(5001, 'Schema operation is not supported.', {
+          code: 'SCHEMA_UPGRADE_INCOMPATIBLE',
+          details: {
+            phase: 'upgrade',
+            origin: 'grc.example',
+            issue: 'issuer-changed',
+            installedIssuer: 'https://old.example',
+            replacementIssuer: 'https://new.example',
+          },
+        }),
+        false,
+      )
+    } finally {
+      console.error = originalError
+      console.log = originalLog
+    }
+
+    expect(errors.join('\n')).toContain('RESPONSE_ERROR(5001)')
+    expect(details.join('\n')).toContain('reason: SCHEMA_UPGRADE_INCOMPATIBLE')
+    expect(details.join('\n')).toContain('installed issuer: https://old.example')
+    expect(details.join('\n')).toContain('replacement issuer: https://new.example')
+    expect(details.join('\n')).toContain('astrale domain uninstall grc.example')
+  })
+
   test('explains a private Domain source without exposing transport diagnostics', async () => {
     const writes: string[] = []
     const original = process.stderr.write

package/src/connection/command.ts

@@ -16,6 +16,11 @@ export interface KernelCommandOpts extends ConnectionOptions {
   readonly debug?: boolean
 }
 
+export interface OperationRecovery {
+  readonly operation: string
+  readonly retry: string
+}
+
 /**
  * Encapsulates the standard kernel command lifecycle:
  * spinner → connect → call → timing → output → error handling.
@@ -27,6 +32,7 @@ export interface KernelCommandOpts extends ConnectionOptions {
 export async function runKernelCommand<T>(input: {
   readonly opts: KernelCommandOpts
   readonly label: string
+  readonly recovery?: OperationRecovery
   readonly fn: (context: ConnectionContext) => Promise<T>
   readonly format?: (
     result: T,
@@ -53,7 +59,9 @@ export async function runKernelCommand<T>(input: {
     }
   } catch (error) {
     if (!isRaw && spin) spin.fail(`${label} failed`)
-    await formatKernelError(error, isRaw, undefined, opts.debug)
+    await formatKernelError(error, isRaw, undefined, opts.debug, {
+      recovery: input.recovery,
+    })
     process.exit(1)
   }
 }

package/src/connection/errors.ts

@@ -1,5 +1,7 @@
 import chalk from 'chalk'
 
+import type { OperationRecovery } from './command'
+
 import { AstraleError } from '../errors'
 import { readLocalStatus, type LocalStatus } from '../lib/local-status'
 import { log } from '../lib/log'
@@ -28,6 +30,7 @@ export async function formatKernelError(
   isRaw: boolean,
   urlArg = '',
   debug = false,
+  opts: { recovery?: OperationRecovery } = {},
 ): Promise<void> {
   const url =
     urlArg || (error instanceof Error ? ((error as Error & { url?: string }).url ?? '') : '')
@@ -54,7 +57,7 @@ export async function formatKernelError(
 
   switch (name) {
     case 'TransportError':
-      presentTransportError(error, isRaw, url, localContext)
+      presentTransportError(error, isRaw, url, localContext, opts.recovery)
       break
 
     case 'ResponseError': {
@@ -96,11 +99,9 @@ export async function formatKernelError(
         }
         presentFunctionInputIssues(inputIssues)
         if (queryRepair !== undefined) presentQueryInputRepair(queryRepair)
-        if (upgrade?.expected !== undefined) {
-          log.dim(`  installed issuer: ${upgrade.expected}`)
-        }
-        if (upgrade?.actual !== undefined) {
-          log.dim(`  replacement issuer: ${upgrade.actual}`)
+        if (upgrade?.issue === 'issuer-changed') {
+          log.dim(`  installed issuer: ${upgrade.installedIssuer}`)
+          log.dim(`  replacement issuer: ${upgrade.replacementIssuer}`)
         }
         if (hint !== undefined) log.dim(`  ${hint}`)
       }
@@ -194,6 +195,7 @@ function presentTransportError(
   isRaw: boolean,
   url: string,
   context: LocalStatus | undefined,
+  recovery: OperationRecovery | undefined,
 ): void {
   const phase = transportPhase(error)
   const delivery = transportDelivery(error)
@@ -213,6 +215,7 @@ function presentTransportError(
       ...(phase === undefined ? {} : { phase }),
       ...(delivery === undefined ? {} : { delivery }),
       ...(context === undefined ? {} : { context }),
+      ...(delivery === 'unknown' && recovery !== undefined ? recovery : {}),
     })
     return
   }
@@ -221,10 +224,18 @@ function presentTransportError(
   if (phase !== undefined) log.dim(`  phase: ${phase}`)
   if (phase === 'connect') log.dim('  Check the target and run `astrale status`.')
   else if (phase === 'timeout') log.dim('  Try increasing `--timeout`.')
-  else if (delivery === 'unknown') {
+  else if (delivery === 'unknown') printOperationRecovery(recovery)
+  printLocalContext(context)
+}
+
+function printOperationRecovery(recovery: OperationRecovery | undefined): void {
+  if (recovery === undefined) {
     log.dim('  Delivery is unknown; do not automatically retry a mutating call.')
+    return
   }
-  printLocalContext(context)
+  log.dim('  Delivery is unknown; retry with the same operation id:')
+  log.dim(`  operation: ${recovery.operation}`)
+  log.dim(`  ${recovery.retry}`)
 }
 
 function presentFunctionInputIssues(issues: readonly FunctionInputIssue[]): void {

package/src/connection/index.ts

@@ -1,6 +1,6 @@
 export { createPathCall } from './call'
 export { runKernelCommand } from './command'
-export type { KernelCommandOpts } from './command'
+export type { KernelCommandOpts, OperationRecovery } from './command'
 export { expandSelfInCall, expandSelfInPath, withSelfHint } from './self'
 export type { SelfExpansionMeta } from './self'
 export { withAdminClientSession, withClientSession, type ConnectionContext } from './session'