@astrale-os/cli 1.0.0-beta.2 → 1.0.0-beta.20

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,48 +23,49 @@ 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)
+      output(
+        response.page.next === undefined
+          ? response.result
+          : { ...response.result, page: { next: response.page.next } },
+        format,
+      )
       if (response.page.next && !isMachine(format)) {
         process.stderr.write(`  cursor: ${response.page.next}\n`)
       }
@@ -81,9 +83,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)
 }
@@ -105,7 +107,8 @@ Behavior:
   one exact Edge-Class expansion; --direction defaults to outgoing. --ast and
   --file accept a complete canonical astrale.graph.query/v6 document, including
   Property ordering and Node or Edge reference/value projections. --cursor resumes
-  one caller-bound query scope.
+  one caller-bound query scope. Machine output adds page.next only when another
+  page exists; pass that opaque value back through --cursor.
 
   Legacy depth/children selector JSON and raw Cypher are not portable Kernel
   V2 query contracts and are not accepted.
@@ -122,7 +125,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

@@ -1,4 +1,4 @@
-import { issuer } from '@astrale-os/sdk/auth'
+import { issuer, type AuthApi, type IssuerId, type MintedCredential } from '@astrale-os/sdk/auth'
 
 import type { KernelCommandOpts } from '../connection'
 import type { CommandDefinition } from '../program/index'
@@ -6,12 +6,12 @@ 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'
 
 /**
- * `astrale token` — mint a fresh delegation token for the active instance
- * + active identity through the bound AuthApi.
+ * `astrale token` — mint a fresh audience-bound token for the active instance
+ * and selected identity through the bound AuthApi.
  */
 export type TokenOpts = KernelCommandOpts & {
   audience?: string
@@ -21,23 +21,25 @@ export type TokenOpts = KernelCommandOpts & {
   for?: string
 }
 
+const DEFAULT_TOKEN_TTL_SECONDS = 4 * 60
+
 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',
+    label: 'Minting token',
     fn: async (ctx) => {
       const audience =
         commandOpts.audience === undefined
           ? ctx.target.kernelIssuer
           : issuer.accept(commandOpts.audience)
-      const self = await ctx.auth.whoami()
-      return ctx.auth.delegate(self.id, {
-        audience,
-        ttlSeconds: ttl,
-        attenuation: { kind: 'identity', self: true },
-      })
+      return issueToken(ctx.auth, ctx.target.kernelIssuer, audience, ttl)
     },
     format: (token, fmtOpts) => {
       if (fmtOpts.json || fmtOpts.format !== undefined) {
@@ -45,15 +47,31 @@ export async function tokenCommand(opts: TokenOpts): Promise<void> {
         return
       }
       if (!fmtOpts.raw && (process.stdout.isTTY ?? false)) {
-        log.dim('  (delegation token — ES256, self-identity)')
+        log.dim('  (audience-bound token — ES256, self-identity)')
       }
       process.stdout.write(`${token}\n`)
     },
   })
 }
 
+/** Issue either a top-level Kernel credential or an external-audience delegation. */
+export async function issueToken(
+  auth: Pick<AuthApi, 'delegate' | 'mint' | 'whoami'>,
+  kernel: IssuerId,
+  audience: IssuerId,
+  ttlSeconds: number,
+): Promise<MintedCredential> {
+  if (audience === kernel) return auth.mint({ ttlSeconds })
+  const self = await auth.whoami()
+  return auth.delegate(self.id, {
+    audience,
+    ttlSeconds,
+    attenuation: { kind: 'identity', self: true },
+  })
+}
+
 export function parseTtl(raw: string | undefined): number {
-  if (raw === undefined) return 3600
+  if (raw === undefined) return DEFAULT_TOKEN_TTL_SECONDS
   if (!/^\d+$/.test(raw)) {
     throw new AstraleError(
       'INVALID_FLAG',
@@ -72,16 +90,17 @@ export function parseTtl(raw: string | undefined): number {
 
 export default {
   name: 'token',
-  description: 'Mint a fresh delegation token for the active instance + identity',
+  description: 'Mint a fresh audience-bound credential for the active instance + identity',
   afterHelpText: `
 Behavior:
-  Delegates the selected authenticated identity for 3600 seconds by default.
-  The default audience is the target Kernel issuer; choose --audience when the
-  credential is intended for another service. --for is an alias of --as.
+  Mints a token for the selected authenticated identity for 240 seconds by default.
+  The default Kernel audience produces a top-level Grant credential reusable with
+  --creds. A different --audience produces a delegated service envelope. --for is
+  an alias of --as.
 
-  The receiver must admit the exact token audience. A Kernel-audience token can
-  be reused with --creds; a service-audience token can be sent as a Bearer token
-  to that service's authenticated endpoint.
+  Every receiver must admit the exact token audience. A service-audience token can
+  be sent as a Bearer token only to that service's authenticated endpoint. The
+  requested lifetime cannot exceed the selected source credential's remaining life.
 
 Examples:
   $ export TOKEN=$(astrale token --audience shell.astrale.ai --raw)
@@ -93,14 +112,10 @@ Examples:
       flags: '--audience <aud>',
       description: 'Token audience (default: target Kernel issuer)',
     },
-    { flags: '--ttl <sec>', description: 'TTL in seconds (default: 3600)' },
+    { flags: '--ttl <sec>', description: 'TTL in seconds (default: 240)' },
     { 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/ui/__tests__/commands.test.ts

@@ -0,0 +1,152 @@
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test'
+
+import addCommand from '../add'
+import listCommand from '../list'
+
+class ExitError extends Error {}
+
+const commit = 'a'.repeat(40)
+const item = {
+  name: 'pattern-chart-line-basic',
+  type: 'registry:block',
+  title: 'Line chart',
+  description: 'A controlled chart.',
+  dependencies: ['@astrale-os/ui@^0.3.0-beta.0'],
+  files: [
+    {
+      path: 'registry/patterns/chart/line-basic.tsx',
+      type: 'registry:component',
+      target: 'components/astrale/pattern/chart/line-basic.tsx',
+    },
+  ],
+  meta: { canonicalAddress: 'pattern/chart/line/basic' },
+}
+
+let stdout = ''
+let stderr = ''
+let originalArgv: string[]
+let originalExit: typeof process.exit
+let originalFetch: typeof globalThis.fetch
+let originalStdout: typeof process.stdout.write
+let originalStderr: typeof process.stderr.write
+
+beforeEach(() => {
+  stdout = ''
+  stderr = ''
+  originalArgv = process.argv
+  originalExit = process.exit
+  originalFetch = globalThis.fetch
+  originalStdout = process.stdout.write
+  originalStderr = process.stderr.write
+  process.stdout.write = ((chunk: string | Uint8Array) => {
+    stdout += String(chunk)
+    return true
+  }) as typeof process.stdout.write
+  process.stderr.write = ((chunk: string | Uint8Array) => {
+    stderr += String(chunk)
+    return true
+  }) as typeof process.stderr.write
+  process.exit = (() => {
+    throw new ExitError()
+  }) as typeof process.exit
+  globalThis.fetch = mockFetch()
+})
+
+afterEach(() => {
+  process.argv = originalArgv
+  process.exit = originalExit
+  globalThis.fetch = originalFetch
+  process.stdout.write = originalStdout
+  process.stderr.write = originalStderr
+})
+
+describe('UI command machine contracts', () => {
+  test('list emits exactly one parseable JSON value', async () => {
+    const action = listCommand.action as (
+      query: string | undefined,
+      options: { json?: boolean; limit?: string },
+    ) => Promise<void>
+    await action('line-basic', { json: true, limit: '100' })
+
+    expect(stderr).toBe('')
+    expect(JSON.parse(stdout)).toEqual([item])
+  })
+
+  test('list forwards an explicit release without consulting the beta channel', async () => {
+    const seen: string[] = []
+    globalThis.fetch = mockFetch(seen)
+    const action = listCommand.action as (
+      query: string | undefined,
+      options: { json?: boolean; limit?: string; version?: string },
+    ) => Promise<void>
+
+    await action('line-basic', { json: true, limit: '100', version: '0.3.0-beta.1' })
+
+    expect(JSON.parse(stdout)).toEqual([item])
+    expect(seen.some((url) => url.endsWith('/@astrale-os/ui/beta'))).toBe(false)
+    expect(seen.some((url) => url.includes('/git/ref/tags/v0.3.0-beta.1'))).toBe(true)
+  })
+
+  test('add rejects missing items without prompting in machine mode', async () => {
+    process.argv = ['node', 'astrale', '--no-prompt', 'ui', 'add']
+    const add = addCommand.action as (items: string[], options: { json?: boolean }) => Promise<void>
+    await expect(add([], { json: true })).rejects.toBeInstanceOf(ExitError)
+    expect(JSON.parse(stderr)).toMatchObject({ error: 'UI_ITEM_NOT_FOUND' })
+    expect(stdout).toBe('')
+  })
+
+  test('registry failures retain a stable code without leaking transport secrets', async () => {
+    globalThis.fetch = (async () => {
+      throw new Error('Authorization: Bearer npm_super_secret_value_that_must_not_escape')
+    }) as unknown as typeof fetch
+    const action = listCommand.action as (
+      query: string | undefined,
+      options: { json?: boolean; limit?: string },
+    ) => Promise<void>
+    await expect(action('line-basic', { json: true, limit: '100' })).rejects.toBeInstanceOf(
+      ExitError,
+    )
+    expect(JSON.parse(stderr)).toEqual({
+      error: 'UI_REGISTRY_UNAVAILABLE',
+      message: 'Unable to reach npm UI release.',
+    })
+    expect(stderr).not.toContain('super_secret')
+  })
+})
+
+function mockFetch(seen: string[] = []): typeof fetch {
+  return (async (input: string | URL | Request) => {
+    const url = String(input)
+    seen.push(url)
+    if (url.endsWith('/@astrale-os/ui/beta')) return Response.json({ version: '0.3.0-beta.1' })
+    if (url.includes('/git/ref/tags/')) {
+      return Response.json({ object: { type: 'commit', sha: commit, url: '' } })
+    }
+    if (url.endsWith('/tooling/compatibility.json')) {
+      return Response.json({
+        version: 1,
+        shadcn: '4.18.0',
+        base: 'base',
+        style: 'nova',
+        baseUi: '1.7.0',
+        react: '^18.3.1 || ^19.0.0',
+        tailwind: '^4.3.3',
+        presets: ['astrale', 'compact', 'expressive'],
+      })
+    }
+    if (url.endsWith('/registry/patterns/chart/registry.json')) {
+      return Response.json({
+        items: [
+          {
+            ...item,
+            files: item.files.map((file) => ({ ...file, path: 'line-basic.tsx' })),
+          },
+        ],
+      })
+    }
+    if (url.endsWith('/registry.json')) {
+      return Response.json({ include: ['registry/patterns/chart/registry.json'] })
+    }
+    return new Response('not found', { status: 404 })
+  }) as typeof fetch
+}

package/src/commands/ui/add.ts

@@ -0,0 +1,51 @@
+import type { CommandDefinition } from '../../program'
+
+import { promptMultiSelect } from '../../lib/prompt'
+import { addUi, listLockedUi, UiError } from '../../ui'
+import { UI_JSON_OPTION, UI_PROJECT_OPTION, runUiCommand, type UiCommandOptions } from './shared'
+
+type Options = UiCommandOptions & { dryRun?: boolean; overwrite?: boolean; yes?: boolean }
+
+export default {
+  name: 'add',
+  description: 'Install consumer-owned Astrale pattern or block source',
+  arguments: [
+    {
+      name: 'items',
+      description: 'Canonical pattern or block addresses',
+      required: false,
+      variadic: true,
+    },
+  ],
+  options: [
+    UI_PROJECT_OPTION,
+    { flags: '--dry-run', description: 'Show exact files and dependencies without writing' },
+    { flags: '--overwrite', description: 'Allow replacing locally changed installed source' },
+    { flags: '--yes', description: 'Confirm the planned operation non-interactively' },
+    UI_JSON_OPTION,
+  ],
+  afterHelpText:
+    '\nInstalled source belongs to the application. Ordinary add never overwrites local edits.\nRun astrale ui doctor before intentionally replacing local source with --overwrite --yes.\n',
+  action: async (items: string[], options: Options) =>
+    runUiCommand(options, async () => {
+      let selected = items
+      if (selected.length === 0) {
+        if (process.argv.includes('--ci') || process.argv.includes('--no-prompt')) {
+          throw new UiError('UI_ITEM_NOT_FOUND', 'No UI item was provided in non-interactive mode.')
+        }
+        const available = await listLockedUi(options.project)
+        selected =
+          (await promptMultiSelect(
+            'Choose Astrale UI source to install',
+            available.map((item) => ({
+              name: item.title ?? item.meta.canonicalAddress,
+              value: item.meta.canonicalAddress,
+              description: item.description,
+            })),
+          )) ?? []
+        if (selected.length === 0)
+          throw new UiError('UI_ITEM_NOT_FOUND', 'No UI item was selected.')
+      }
+      return addUi(selected, options)
+    }),
+} satisfies CommandDefinition

package/src/commands/ui/doctor.ts

@@ -0,0 +1,13 @@
+import type { CommandDefinition } from '../../program'
+
+import { doctorUi } from '../../ui'
+import { UI_JSON_OPTION, runUiCommand, type UiCommandOptions } from './shared'
+
+export default {
+  name: 'doctor',
+  description: 'Verify Astrale UI package, CSS, config, lock, and installed source integrity',
+  arguments: [{ name: 'path', description: 'Application directory', required: false }],
+  options: [UI_JSON_OPTION],
+  action: async (path: string | undefined, options: UiCommandOptions) =>
+    runUiCommand(options, () => doctorUi(path)),
+} satisfies CommandDefinition

package/src/commands/ui/init.ts

@@ -0,0 +1,38 @@
+import type { CommandDefinition } from '../../program'
+
+import { initUi, type UiPreset } from '../../ui'
+import { UI_JSON_OPTION, runUiCommand, type UiCommandOptions } from './shared'
+
+type Options = UiCommandOptions & {
+  preset?: UiPreset
+  version?: string
+  dryRun?: boolean
+  force?: boolean
+  install?: boolean
+}
+
+export default {
+  name: 'init',
+  description: 'Initialize Astrale UI in an existing React and Tailwind v4 application',
+  arguments: [{ name: 'path', description: 'Application directory', required: false }],
+  options: [
+    {
+      flags: '--preset <name>',
+      description: 'Visual preset',
+      choices: ['astrale', 'compact', 'expressive'],
+      default: 'astrale',
+    },
+    { flags: '--version <version>', description: 'Exact @astrale-os/ui version or release tag' },
+    { flags: '--dry-run', description: 'Print the complete plan without writing or installing' },
+    { flags: '--force', description: 'Replace an existing Astrale UI lock intentionally' },
+    {
+      flags: '--no-install',
+      description: 'Write configuration without running the package manager',
+    },
+    UI_JSON_OPTION,
+  ],
+  afterHelpText:
+    '\nExamples:\n  $ astrale ui init --preset astrale\n  $ astrale ui init ./app --dry-run --json\n',
+  action: async (path: string | undefined, options: Options) =>
+    runUiCommand(options, () => initUi({ path, ...options })),
+} satisfies CommandDefinition

package/src/commands/ui/list.ts

@@ -0,0 +1,26 @@
+import type { CommandDefinition } from '../../program'
+
+import { listUi } from '../../ui'
+import { UI_JSON_OPTION, runUiCommand, type UiCommandOptions } from './shared'
+
+type Options = UiCommandOptions & { type?: string; limit?: string; version?: string }
+
+export default {
+  name: 'list',
+  description: 'List or search Astrale patterns and blocks',
+  arguments: [{ name: 'query', description: 'Optional search text', required: false }],
+  options: [
+    {
+      flags: '--type <type>',
+      description: 'Restrict to pattern or block',
+      choices: ['pattern', 'block'],
+    },
+    { flags: '--limit <n>', description: 'Maximum results', default: '100' },
+    { flags: '--version <version>', description: 'Exact release to inspect' },
+    UI_JSON_OPTION,
+  ],
+  action: async (query: string | undefined, options: Options) =>
+    runUiCommand(options, () =>
+      listUi(query, { type: options.type, limit: Number(options.limit), version: options.version }),
+    ),
+} satisfies CommandDefinition

package/src/commands/ui/preset-apply.ts

@@ -0,0 +1,19 @@
+import type { CommandDefinition } from '../../program'
+
+import { applyPreset, type UiPreset } from '../../ui'
+import { UI_JSON_OPTION, UI_PROJECT_OPTION, runUiCommand, type UiCommandOptions } from './shared'
+
+type Options = UiCommandOptions & { dryRun?: boolean }
+
+export default {
+  name: 'apply',
+  description: 'Change the preset CSS import without rewriting component source',
+  arguments: [{ name: 'name', description: 'Preset name' }],
+  options: [
+    UI_PROJECT_OPTION,
+    { flags: '--dry-run', description: 'Show the CSS and lock change without writing' },
+    UI_JSON_OPTION,
+  ],
+  action: async (name: UiPreset, options: Options) =>
+    runUiCommand(options, () => applyPreset(name, options)),
+} satisfies CommandDefinition

package/src/commands/ui/preset-list.ts

@@ -0,0 +1,12 @@
+import type { CommandDefinition } from '../../program'
+
+import { UI_PRESETS } from '../../ui'
+import { UI_JSON_OPTION, runUiCommand, type UiCommandOptions } from './shared'
+
+export default {
+  name: 'list',
+  description: 'List qualified Astrale UI visual presets',
+  options: [UI_JSON_OPTION],
+  action: async (options: UiCommandOptions) =>
+    runUiCommand(options, async () => UI_PRESETS.map((name) => ({ name }))),
+} satisfies CommandDefinition

package/src/commands/ui/shared.ts

@@ -0,0 +1,25 @@
+import { fatal } from '../../lib/log'
+import { output } from '../../lib/output'
+
+export type UiCommandOptions = { json?: boolean; project?: string }
+
+export async function runUiCommand(
+  options: UiCommandOptions,
+  operation: () => Promise<unknown>,
+): Promise<void> {
+  try {
+    output(await operation(), { json: options.json })
+  } catch (error) {
+    fatal(error, { json: options.json })
+  }
+}
+
+export const UI_PROJECT_OPTION = {
+  flags: '--project <path>',
+  description: 'Existing application root (defaults to the current project)',
+} as const
+
+export const UI_JSON_OPTION = {
+  flags: '--json',
+  description: 'Emit one machine-readable JSON value',
+} as const

package/src/commands/update.ts

@@ -12,7 +12,7 @@ import {
   type SdkOutdated,
 } from '../lib/sdk-deps'
 import { ASTRALE_CLI_SKILL, detectSkill, installSkills, SKILL_INSTALL_HINT } from '../lib/skills'
-import { DEFAULT_UPDATE_CHANNEL, updateAstrale } from '../lib/update'
+import { DEFAULT_UPDATE_CHANNEL, packageManagedUpdateError, updateAstrale } from '../lib/update'
 
 type UpdateOpts = RawOutputOpts & {
   check?: boolean
@@ -104,14 +104,22 @@ async function refreshSdkDeps(check: boolean, assumeYes = false): Promise<boolea
 /**
  * Read-only staleness report for tooling — `astrale update --check --json`.
  * domain-studio polls this on load to drive its "update available" badge. It is
- * unified and NON-THROWING: the CLI axis catches the package-managed / no-metadata
- * case (reported as `managed`, never stale), and the SDK axis is already
- * best-effort. Skills are intentionally absent — they ride along with `astrale
- * update`, so a stale CLI or SDK is the only signal worth surfacing.
+ * unified and NON-THROWING: an explicit package-managed result uses npm release
+ * identity, while script-install failures remain script failures in `error`
+ * instead of being recategorized. The SDK axis is already best-effort. Skills are
+ * intentionally absent — they ride along with `astrale update`, so a stale CLI or
+ * SDK is the only signal worth surfacing.
  */
 export type StaleReport = {
   stale: boolean
-  cli: { stale: boolean; managed: boolean; current?: string; latest?: string; channel?: string }
+  cli: {
+    stale: boolean
+    managed: boolean
+    current?: string
+    latest?: string
+    channel?: string
+    error?: string
+  }
   sdk: { stale: boolean; inProject: boolean; outdated: SdkOutdated[] }
 }
 
@@ -138,6 +146,15 @@ export async function cliStale(
       version: target.version,
       currentVersion: running,
     })
+    if (r.status === 'managed') {
+      const latest = await dependencies.fetchPackageVersion(target).catch(() => undefined)
+      return {
+        stale: latest !== undefined && latest !== running,
+        managed: true,
+        current: running,
+        ...(latest === undefined ? {} : { latest, channel: 'npm' }),
+      }
+    }
     if (r.status === 'updated') {
       return {
         stale: false,
@@ -154,13 +171,12 @@ export async function cliStale(
       latest: r.latestVersion,
       channel: r.channel,
     }
-  } catch {
-    const latest = await dependencies.fetchPackageVersion(target).catch(() => undefined)
+  } catch (error) {
     return {
-      stale: latest !== undefined && latest !== running,
-      managed: true,
+      stale: false,
+      managed: false,
       current: running,
-      ...(latest === undefined ? {} : { latest, channel: 'npm' }),
+      error: error instanceof Error ? error.message : String(error),
     }
   }
 }
@@ -294,6 +310,10 @@ Examples:
         log.success(`Updated astrale ${result.previousVersion} -> ${result.currentVersion}`)
         log.dim(`  channel: ${result.channel}`)
         log.dim(`  binary: ${result.bin}`)
+      } else if (result?.status === 'managed') {
+        const error = packageManagedUpdateError(result.executable)
+        if (!opts.yes) throw error
+        log.warn(`CLI self-update skipped: ${error.message}`)
       }
 
       // Axis B — agent skills. Keep an existing install current with the CLI.