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

package/src/commands/instance/delete.ts

@@ -1,10 +1,12 @@
 import type { KernelCommandOpts } from '../../connection'
 import type { CommandDefinition } from '../../program/index'
 
+import { AdminInstanceNotFoundError } from '../../admin/instance'
+import { formatKernelError } from '../../connection/errors'
 import { deleteOwnedInstance } from '../../lib/admin-instance'
 import { ADMIN_TARGET_OPTIONS, type AdminTargetCommandOpts } from '../../lib/admin-target'
 import { clearActive, readInstances, removeInstance, resolveInstanceKey } from '../../lib/instance'
-import { fatal, log, withSpinner } from '../../lib/log'
+import { log, withSpinner } from '../../lib/log'
 import { isMachine, output } from '../../lib/output'
 
 type DeleteOpts = KernelCommandOpts &
@@ -18,10 +20,9 @@ export default {
   afterHelpText: `
 Behavior:
   Calls Instance.delete on the configured admin kernel: best-effort decommission
-  of the instance's routing-registry entry + WorkOS org (frees the slug), then
-  removes the Instance record. The host kernel itself is NOT deregistered (the
-  deprovisioning saga is a follow-up). A same-name local bookmark is removed
-  after the delete succeeds unless --keep-bookmark is passed.
+  of the instance's route and tenant reservation, then removes the Instance
+  projection. A same-name local bookmark is removed after the delete succeeds
+  unless --keep-bookmark is passed.
 `,
   arguments: [{ name: 'id', description: 'Instance slug', required: true }],
   options: [
@@ -53,14 +54,16 @@ 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)
       }
-      fatal(e, opts)
+      await formatKernelError(e, isMachine(opts), undefined, opts.debug)
+      process.exit(1)
     }
   },
 } satisfies CommandDefinition

package/src/commands/instance/list.ts

@@ -7,7 +7,7 @@ import type { CommandDefinition } from '../../program/index'
 import { AstraleError } from '../../errors'
 import { listOwnedInstances } from '../../lib/admin-instance'
 import {
-  formatInstanceLocation,
+  formatInstanceState,
   type InstanceInfo,
   type OwnedInstanceInfo,
 } from '../../lib/admin-instance'
@@ -136,7 +136,7 @@ export function buildInstanceRows(
         name: twin?.active ? `${item.slug} ${chalk.green('*')}` : item.slug,
         kind: 'managed',
         url: item.url ?? '',
-        extra: [formatInstanceLocation(item), twin ? formatBookmarkConnection(twin) : '']
+        extra: [formatInstanceState(item), twin ? formatBookmarkConnection(twin) : '']
           .filter(Boolean)
           .join(' · '),
       })

package/src/commands/instance/status.ts

@@ -3,44 +3,90 @@ import chalk from 'chalk'
 import type { KernelCommandOpts } from '../../connection'
 import type { CommandDefinition } from '../../program/index'
 
+import { formatKernelError } from '../../connection/errors'
 import { AstraleError } from '../../errors'
-import { statusOwnedInstance } from '../../lib/admin-instance'
+import { statusOwnedInstance, type InstanceInfo } from '../../lib/admin-instance'
 import { ADMIN_TARGET_OPTIONS, type AdminTargetCommandOpts } from '../../lib/admin-target'
-import { fatal, log, withSpinner } from '../../lib/log'
+import { resolveInstance } from '../../lib/instance'
+import { log, withSpinner } from '../../lib/log'
 import { isMachine, output, type RawOutputOpts } from '../../lib/output'
+import { probeBookmark } from './use'
 
-type StatusOpts = KernelCommandOpts & AdminTargetCommandOpts & RawOutputOpts
+type StatusOpts = KernelCommandOpts &
+  AdminTargetCommandOpts &
+  RawOutputOpts & { bookmarked?: boolean }
+
+interface BookmarkStatus {
+  readonly slug: string
+  readonly url: string
+  readonly issuer: string
+  readonly kind: 'bookmark'
+  readonly state: 'ready'
+}
 
 export default {
   name: 'status',
-  description: 'Show admin instance status',
+  description: 'Show managed instance status or probe a bookmark',
   arguments: [{ name: 'id', description: 'Instance slug', required: true }],
-  options: [...ADMIN_TARGET_OPTIONS],
+  options: [
+    ...ADMIN_TARGET_OPTIONS,
+    { flags: '--bookmarked', description: 'Probe a locally bookmarked kernel connection' },
+  ],
   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.',
-          )
-        }),
+        resolveStatus(id, opts),
       )
       if (isMachine(opts)) {
         output(result, opts)
         return
       }
       console.log(`${chalk.bold(result.slug)} ${chalk.dim(result.url)}`)
-      log.dim(`  state: ${result.state}${result.phase ? ` (${result.phase})` : ''}`)
-      if (result.error) log.dim(`  error: ${result.error}`)
-      if (result.region) log.dim(`  region: ${result.region}`)
-      if (result.hostId) log.dim(`  host: ${result.hostId}`)
-      if (result.organizationId) log.dim(`  organization: ${result.organizationId}`)
-      if (result.createdAt) log.dim(`  created: ${result.createdAt}`)
+      const phase = 'phase' in result ? result.phase : undefined
+      log.dim(`  state: ${result.state}${phase ? ` (${phase})` : ''}`)
+      if ('error' in result && result.error) log.dim(`  error: ${result.error}`)
+      if ('organizationId' in result && result.organizationId)
+        log.dim(`  organization: ${result.organizationId}`)
+      if ('createdAt' in result && result.createdAt) log.dim(`  created: ${result.createdAt}`)
     } catch (e) {
-      fatal(e, opts)
+      await formatKernelError(e, isMachine(opts), undefined, opts.debug)
+      process.exit(1)
     }
   },
 } satisfies CommandDefinition
+
+export interface StatusDependencies {
+  readonly statusOwnedInstance: typeof statusOwnedInstance
+  readonly resolveInstance: typeof resolveInstance
+  readonly probeBookmark: typeof probeBookmark
+}
+
+const defaultStatusDependencies: StatusDependencies = Object.freeze({
+  statusOwnedInstance,
+  resolveInstance,
+  probeBookmark,
+})
+
+export async function resolveStatus(
+  id: string,
+  opts: StatusOpts,
+  dependencies: StatusDependencies = defaultStatusDependencies,
+): Promise<InstanceInfo | BookmarkStatus> {
+  if (!opts.bookmarked) return dependencies.statusOwnedInstance(opts, id)
+  if (opts.admin !== undefined || opts.adminUrl !== undefined || opts.domainIssuer !== undefined) {
+    throw new AstraleError(
+      'INVALID_FLAG',
+      '--bookmarked cannot be combined with Admin target options.',
+      'Remove --bookmarked to inspect managed lifecycle, or remove the Admin options to probe a local bookmark.',
+    )
+  }
+  const bookmark = await dependencies.resolveInstance(id, undefined, { persist: false })
+  await dependencies.probeBookmark(bookmark)
+  return Object.freeze({
+    slug: bookmark.name,
+    url: bookmark.url,
+    issuer: bookmark.issuer ?? bookmark.url,
+    kind: 'bookmark',
+    state: 'ready',
+  })
+}

package/src/commands/instance/use.ts

@@ -3,7 +3,7 @@ import type { CommandDefinition } from '../../program/index'
 
 import { AstraleError } from '../../errors'
 import { getDefault, setDefault } from '../../identity/index'
-import { listOwnedInstances } from '../../lib/admin-instance'
+import { listOwnedInstancesWithIdentity } from '../../lib/admin-instance'
 import { ADMIN_TARGET_OPTIONS } from '../../lib/admin-target'
 import { fetchWithCaFile } from '../../lib/ca-fetch'
 import {
@@ -143,7 +143,7 @@ const defaultBookmarkProbeDependencies: BookmarkProbeDependencies = Object.freez
 
 async function resolveUseTarget(name: string, opts: UseOpts): Promise<ResolvedInstance> {
   const [store, managed] = await Promise.all([readInstances(), fetchManagedInstances(name, opts)])
-  const candidates = collectInstanceCandidates(name, store, managed)
+  const candidates = collectInstanceCandidates(name, store, managed.instances)
 
   if (candidates.length === 0) {
     throw new AstraleError(
@@ -168,12 +168,13 @@ async function resolveUseTarget(name: string, opts: UseOpts): Promise<ResolvedIn
   }
 
   assertManagedReady(chosen.info)
-  const { repointedFrom } = await upsertManagedBookmark(
-    chosen.key,
-    chosen.info.slug,
-    chosen.url,
-    chosen.info.organizationId,
-  )
+  const { repointedFrom } = await upsertManagedBookmark({
+    key: chosen.key,
+    slug: chosen.info.slug,
+    url: chosen.url,
+    ...(chosen.info.organizationId ? { organizationId: chosen.info.organizationId } : {}),
+    ...(managed.identity ? { defaultIdentity: managed.identity } : {}),
+  })
   if (repointedFrom) {
     log.warn(`Bookmark "${chosen.key}" repointed: ${repointedFrom} → ${chosen.url}`)
   }
@@ -185,16 +186,19 @@ async function resolveUseTarget(name: string, opts: UseOpts): Promise<ResolvedIn
  * Best-effort: an unreachable or unauthenticated admin kernel degrades to
  * bookmark-only resolution.
  */
-async function fetchManagedInstances(name: string, opts: UseOpts): Promise<OwnedInstanceInfo[]> {
+async function fetchManagedInstances(
+  name: string,
+  opts: UseOpts,
+): Promise<{ readonly instances: OwnedInstanceInfo[]; readonly identity?: string }> {
   try {
     validateSlug(name)
   } catch {
-    return []
+    return { instances: [] }
   }
   try {
-    return await listOwnedInstances(opts)
+    return await listOwnedInstancesWithIdentity(opts)
   } catch {
-    return []
+    return { instances: [] }
   }
 }
 

package/src/commands/introspect.ts

@@ -1,3 +1,5 @@
+import type { DomainBundle, DomainInfo, SchemaApi } from '@astrale-os/sdk/client/schema'
+
 import { Path } from '@astrale-os/sdk/graph/path'
 
 import type { KernelCommandOpts } from '../connection'
@@ -5,46 +7,41 @@ 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 }
 
-export async function introspectCommand(target: string, opts: IntrospectOpts): Promise<void> {
+interface IntrospectDependencies {
+  readonly runKernelCommand: typeof runKernelCommand
+}
+
+const defaultIntrospectDependencies = Object.freeze({ runKernelCommand })
+
+export async function introspectCommand(
+  target: string,
+  opts: IntrospectOpts,
+  dependencies: Partial<IntrospectDependencies> = {},
+): Promise<void> {
+  const introspect = { ...defaultIntrospectDependencies, ...dependencies }
   let origin: string
   let path: Path
   try {
     ;({ origin, path } = parseIntrospectTarget(target))
   } catch (error) {
-    failClosed(error, opts)
+    failInput(error, opts)
   }
   const wantsCallable = isCallablePath(path)
 
-  await runKernelCommand({
+  await introspect.runKernelCommand({
     opts,
     label: `Introspect ${origin}`,
     fn: async ({ session }) => {
       const includeBundle = wantsCallable || opts.bundle === true
-      const result = await session.schema.introspect({
-        from: { kind: 'installation', origin },
-        select: {
-          state: true,
-          target: true,
-          source: true,
-          readiness: true,
-          capabilities: true,
-          ...(includeBundle ? { bundle: true as const } : {}),
-        },
-      })
-      if (result === null) {
-        throw new AstraleError(
-          'DOMAIN_NOT_INSTALLED',
-          `Domain ${origin} is not installed on this Kernel.`,
-        )
-      }
+      const result = await readInstalledDomain(session.schema, origin, includeBundle)
       if (wantsCallable) {
-        const described = describeCallableFromSchema(path, bundleRoot(result.bundle))
+        const described = describeCallableFromBundle(path, (result as DomainBundle).bundle)
         if (described === undefined) throw missingCallableDescription(path.raw)
         return described
       }
@@ -54,12 +51,35 @@ export async function introspectCommand(target: string, opts: IntrospectOpts): P
   })
 }
 
+export function readInstalledDomain(
+  schema: Pick<SchemaApi, 'inspect' | 'bundle'>,
+  origin: string,
+  includeBundle: true,
+): Promise<DomainBundle>
+export function readInstalledDomain(
+  schema: Pick<SchemaApi, 'inspect' | 'bundle'>,
+  origin: string,
+  includeBundle: false,
+): Promise<DomainInfo>
+export function readInstalledDomain(
+  schema: Pick<SchemaApi, 'inspect' | 'bundle'>,
+  origin: string,
+  includeBundle: boolean,
+): Promise<DomainInfo | DomainBundle>
+export function readInstalledDomain(
+  schema: Pick<SchemaApi, 'inspect' | 'bundle'>,
+  origin: string,
+  includeBundle: boolean,
+): Promise<DomainInfo | DomainBundle> {
+  return includeBundle ? schema.bundle(origin) : schema.inspect(origin)
+}
+
 export function parseIntrospectTarget(target: string): { origin: string; path: Path } {
   if (target.startsWith('@')) {
     throw new AstraleError(
       'NOT_A_DOMAIN',
       'introspect requires a Domain origin or Path, not an @id.',
-      'Example: astrale introspect host.astrale.ai  or  /:host.astrale.ai:class.Manager:createInstance',
+      'Example: astrale introspect kernel.astrale.ai  or  /:kernel.astrale.ai:class.Identity:whois',
     )
   }
   const raw = target.startsWith('/') ? target : `/:${target}`
@@ -85,28 +105,21 @@ 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',
   afterHelpText: `
 Behavior:
   Calls the public Kernel introspect syscall for one installed Domain.
-  A bare origin (host.astrale.ai or /:host.astrale.ai) prints installation
+  A bare origin (kernel.astrale.ai or /:kernel.astrale.ai) prints installation
   state, target, source, readiness, and capabilities. --bundle includes the
   schema bundle. A method or Function Path projects that callable's
   input/output from the installed bundle.
 
 Examples:
-  $ astrale introspect host.astrale.ai
-  $ astrale introspect /:host.astrale.ai --bundle
-  $ astrale introspect /:host.astrale.ai:class.Manager:createInstance
+  $ astrale introspect kernel.astrale.ai
+  $ astrale introspect /:kernel.astrale.ai --bundle
+  $ astrale introspect /:kernel.astrale.ai:class.Identity:whois
   $ astrale introspect /:kernel.astrale.ai:function.journal
 `,
   arguments: [{ name: 'target', description: 'Domain origin or canonical Path' }],

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
 
@@ -38,10 +33,21 @@ export interface JournalRecord {
   readonly occurredAt?: string
   readonly committedAt?: string
   readonly principal?: string
+  readonly correlation?: JournalCorrelation
   readonly correlationId?: string
   readonly causationId?: string
 }
 
+export interface JournalCorrelation {
+  readonly operationId?: string
+  readonly parentOperationId?: string
+  readonly invocationId?: string
+  readonly rootInvocationId?: string
+  readonly parentInvocationId?: string
+  readonly traceId?: string
+  readonly spanId?: string
+}
+
 export interface JournalPage {
   readonly records: readonly JournalRecord[]
   readonly cursor?: string
@@ -127,7 +133,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 {
@@ -138,15 +144,33 @@ 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))
-    }
+type FollowDependencies = {
+  readonly run: typeof runKernelCommand
+  readonly pause: (milliseconds: number) => Promise<void>
+}
+
+/** Follow one admitted journal stream. Dependencies are explicit so routing is proven at the command boundary. */
+export async function followLogs(
+  opts: LogsOpts,
+  dependencies: FollowDependencies = {
+    run: runKernelCommand,
+    pause: (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds)),
+  },
+): Promise<void> {
+  validateLogsOpts(opts)
+  await dependencies.run({
+    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, opts)
+        cursor = page.cursor ?? cursor
+        await dependencies.pause(FOLLOW_INTERVAL_MS)
+      }
+    },
   })
 }
 
@@ -169,12 +193,28 @@ function journalProjection(records: JournalRecord[]): ListProjection {
   }
 }
 
-function printRecord(record: JournalRecord): void {
+function printRecord(record: JournalRecord, opts: LogsOpts): void {
+  if (isMachine(opts) || opts.format === 'json') {
+    process.stdout.write(formatFollowRecord(record))
+    return
+  }
   process.stdout.write(
     `${chalk.dim(String(record.sequence).padStart(6))} ${chalk.dim(record.timestamp)} ${chalk.cyan(record.topic)} ${chalk.dim(record.principal ?? '')}\n`,
   )
 }
 
+/** Machine follow is an NDJSON stream: one complete admitted record per line. */
+export function formatFollowRecord(record: JournalRecord): string {
+  return `${JSON.stringify(record)}\n`
+}
+
+export function validateLogsOpts(opts: LogsOpts): void {
+  buildJournalInput(opts)
+  if (opts.follow && opts.format === 'yaml' && !opts.json && !opts.raw) {
+    throw new TypeError('--follow does not support YAML; use --json for an NDJSON stream')
+  }
+}
+
 function acceptRecord(input: unknown, index: number): JournalRecord {
   if (
     !isRecord(input) ||
@@ -188,10 +228,17 @@ function acceptRecord(input: unknown, index: number): JournalRecord {
   if (timestamp === undefined) {
     throw new TypeError(`Kernel journal record ${index} is missing occurredAt/timestamp`)
   }
-  const correlation = isRecord(input.correlation) ? input.correlation : undefined
-  const correlationId =
-    optionalText(input.correlationId, index, 'correlationId') ??
-    optionalText(correlation?.invocationId, index, 'correlation.invocationId')
+  const correlation = acceptCorrelation(input.correlation, index)
+  const legacyCorrelationId = optionalIdentifier(input.correlationId, index, 'correlationId')
+  const structuredCorrelationId = correlation?.invocationId
+  if (
+    legacyCorrelationId !== undefined &&
+    structuredCorrelationId !== undefined &&
+    legacyCorrelationId !== structuredCorrelationId
+  ) {
+    throw new TypeError(`Kernel journal record ${index} has conflicting correlation identifiers`)
+  }
+  const correlationId = structuredCorrelationId ?? legacyCorrelationId
   const principal = optionalText(input.principal, index, 'principal')
   return Object.freeze({
     sequence: input.sequence as number,
@@ -203,13 +250,56 @@ function acceptRecord(input: unknown, index: number): JournalRecord {
       ? {}
       : { committedAt: input.committedAt as string }),
     ...(principal === undefined ? {} : { principal }),
+    ...(correlation === undefined ? {} : { correlation }),
     ...(correlationId === undefined ? {} : { correlationId }),
-    ...(optionalText(input.causationId, index, 'causationId') === undefined
+    ...(optionalIdentifier(input.causationId, index, 'causationId') === undefined
       ? {}
       : { causationId: input.causationId as string }),
   })
 }
 
+const correlationFields = [
+  'operationId',
+  'parentOperationId',
+  'invocationId',
+  'rootInvocationId',
+  'parentInvocationId',
+  'traceId',
+  'spanId',
+] as const
+
+function acceptCorrelation(input: unknown, index: number): JournalCorrelation | undefined {
+  if (input === undefined) return undefined
+  if (!isRecord(input)) {
+    throw new TypeError(`Kernel journal record ${index}.correlation must be an object`)
+  }
+  const unknown = Object.keys(input).find(
+    (field) => !correlationFields.includes(field as (typeof correlationFields)[number]),
+  )
+  if (unknown !== undefined) {
+    throw new TypeError(`Kernel journal record ${index}.correlation.${unknown} is unsupported`)
+  }
+  return Object.freeze(
+    Object.fromEntries(
+      correlationFields.flatMap((field) => {
+        const value = optionalIdentifier(input[field], index, `correlation.${field}`)
+        return value === undefined ? [] : [[field, value]]
+      }),
+    ),
+  )
+}
+
+function optionalIdentifier(input: unknown, index: number, field: string): string | undefined {
+  const value = optionalText(input, index, field)
+  if (value === undefined) return undefined
+  if (value.trim() === '' || new TextEncoder().encode(value).byteLength > 256) {
+    throw new TypeError(
+      `Kernel journal record ${index}.${field} must be non-empty and at most 256 UTF-8 bytes`,
+    )
+  }
+  return value
+}
+
 function optionalText(input: unknown, index: number, field: string): string | undefined {
   if (input === undefined) return undefined
   if (typeof input !== 'string') {
@@ -227,11 +317,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 }
 }
 
@@ -252,7 +341,8 @@ Behavior:
   Calls the public Kernel journal syscall and emits its { records, cursor }
   page. Topic selection is exact or prefix-based; cursors and timestamps are
   opaque strings owned by the journal backend. --follow reuses one Client Session
-  and advances only with the returned cursor.
+  and advances only with the returned cursor. Machine follow output is NDJSON:
+  one complete admitted record per line; YAML follow is unsupported.
 
   Historical event-glob lowering and the application-specific services-domain
   log buffer are not part of the Kernel V2 journal contract.
@@ -274,11 +364,11 @@ Examples:
   ],
   action: async (opts: LogsOpts) => {
     try {
-      const prepared = await prepareLogsOpts(opts)
-      if (prepared.follow) await follow(prepared)
-      else await runOnce(prepared)
+      validateLogsOpts(opts)
     } catch (error) {
-      failClosed(error, opts)
+      failInput(error, opts)
     }
+    if (opts.follow) await followLogs(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)
   }