@astrale-os/cli 0.8.1-alpha.4 → 0.8.1-alpha.6

package/src/connection/errors.ts

@@ -156,7 +156,7 @@ export async function formatKernelError(
           // Server often sends details in message but empty errors array
           console.log(chalk.red(`  ${error.message}`))
         }
-        log.dim('  Use `astrale call <path> --describe` to see the expected schema')
+        log.dim('  Use `astrale introspect <path>` to see the expected schema')
       }
       break
     }
@@ -177,24 +177,30 @@ export async function formatKernelError(
     case 'ResponseError': {
       const code = (error as { readonly code?: unknown }).code
       const reason = (error as { readonly reason?: unknown }).reason
+      const reasonCode =
+        reason !== null &&
+        typeof reason === 'object' &&
+        typeof (reason as { readonly code?: unknown }).code === 'string'
+          ? (reason as { readonly code: string }).code
+          : undefined
+      const hint =
+        reasonCode === 'FUNCTION_INPUT_INVALID'
+          ? 'Use `astrale introspect <path>` to see the callable input.'
+          : undefined
       if (isRaw) {
         writeRaw({
           error: 'RESPONSE_ERROR',
           ...(code === undefined ? {} : { code }),
           message: error.message,
           ...(reason === undefined ? {} : { reason }),
+          ...(hint === undefined ? {} : { hint }),
         })
       } else {
         log.error(
           `${chalk.bold(code === undefined ? 'RESPONSE_ERROR' : `RESPONSE_ERROR(${String(code)})`)}: ${error.message}`,
         )
-        if (
-          reason !== null &&
-          typeof reason === 'object' &&
-          typeof (reason as { readonly code?: unknown }).code === 'string'
-        ) {
-          log.dim(`  reason: ${(reason as { readonly code: string }).code}`)
-        }
+        if (reasonCode !== undefined) log.dim(`  reason: ${reasonCode}`)
+        if (hint !== undefined) log.dim(`  ${hint}`)
       }
       break
     }
@@ -207,10 +213,20 @@ export async function formatKernelError(
       break
     }
 
-    default:
-      // Catch-all: include class name so diagnosis is possible even without --debug
-      if (isRaw) writeRaw({ error: name || 'UNKNOWN', message: error.message })
-      else log.error(`${chalk.bold(name || 'Error')}: ${error.message}`)
+    default: {
+      const mapped = mapPublicError(error)
+      if (isRaw) {
+        writeRaw({
+          error: mapped.code,
+          message: mapped.message,
+          ...(mapped.hint === undefined ? {} : { hint: mapped.hint }),
+          ...(mapped.timeoutMs === undefined ? {} : { timeoutMs: mapped.timeoutMs }),
+        })
+      } else {
+        log.error(`${chalk.bold(mapped.code)}: ${mapped.message}`)
+        if (mapped.hint) log.dim(`  ${mapped.hint}`)
+      }
+    }
   }
 
   if (debug) printDebug(error, url)
@@ -221,6 +237,52 @@ export function stripMethodSuffix(msg: string): string {
   return msg.replace(/(\/[^"\s:]+)::([a-zA-Z]\w*)/g, '$1')
 }
 
+function mapPublicError(error: Error): {
+  code: string
+  message: string
+  hint?: string
+  timeoutMs?: number
+} {
+  const name = error.name
+  if (name === 'PathError') {
+    return { code: 'PATH_INVALID', message: error.message }
+  }
+  if (name === 'NodeUnavailableError') {
+    return {
+      code: 'NODE_UNAVAILABLE',
+      message: error.message,
+      hint: 'If this is a callable Path, use `astrale call` or `astrale introspect`.',
+    }
+  }
+  if (name === 'AuthValueError') {
+    return { code: 'AUTH_VALUE_INVALID', message: error.message }
+  }
+  if (name === 'ClientError' && /timed out/i.test(error.message)) {
+    const timeoutMs = (error as { timeoutMs?: number }).timeoutMs
+    return {
+      code: 'TIMEOUT',
+      message: error.message,
+      hint: 'Try increasing with --timeout',
+      ...(timeoutMs === undefined ? {} : { timeoutMs }),
+    }
+  }
+  if (name === 'ClientError' && /Publication discovery returned HTTP/i.test(error.message)) {
+    return {
+      code: 'KERNEL_DISCOVERY_FAILED',
+      message: error.message,
+      hint: 'Pass the Kernel issuer URL (no /invoke suffix), e.g. https://host/kernel/host',
+    }
+  }
+  if (name === 'Error' && /unable to connect/i.test(error.message)) {
+    return {
+      code: 'CONNECTION_ERROR',
+      message: error.message,
+      hint: 'Check --url / -i and that the Kernel is reachable. Try: astrale status',
+    }
+  }
+  return { code: name && name !== 'Error' ? name : 'UNKNOWN', message: error.message }
+}
+
 function writeRaw(payload: Record<string, unknown>): void {
   process.stderr.write(JSON.stringify(payload) + '\n')
 }

package/src/connection/session.ts

@@ -19,12 +19,20 @@ import {
 import { AstraleError } from '../errors'
 import { fetchWithCaFile } from '../lib/ca-fetch'
 import { readConfig } from '../lib/config'
+import { log } from '../lib/log'
+import { isMachine } from '../lib/output'
 import { createCliCredential, validateCredentialSelection } from './credential'
 import { resolveAdminConnectionTarget, resolveConnectionTarget } from './target'
 
 const DEFAULT_TIMEOUT_MS = 30_000
 const MAXIMUM_ROUTE_AGE_MS = 5 * 60_000
 
+function warnMissingExplicitTarget(options: ConnectionOptions, target: ConnectionTarget): void {
+  if (options.instance !== undefined || options.url !== undefined) return
+  if (!isMachine(options)) return
+  log.warn(`No -i/--url; using ${target.slug ?? target.url}`)
+}
+
 export interface ConnectionContext {
   readonly session: ClientSession
   readonly graph: GraphApi
@@ -55,6 +63,7 @@ export async function withClientSession<Value>(
   const target = await resolveConnectionTarget(options, config, {
     managed: (slug) => lookupManagedInstance(slug, options),
   })
+  warnMissingExplicitTarget(options, target)
   return runResolvedClientSession(target, timeoutMs, options, config, action, openConnection)
 }
 

package/src/connection/target.ts

@@ -17,6 +17,7 @@ export interface ConnectionOptions {
   readonly as?: string
   readonly creds?: string
   readonly anonymous?: boolean
+  readonly ci?: boolean
 }
 
 export interface AdminConnectionOptions extends ConnectionOptions {

package/src/graph/__tests__/mutation.test.ts

@@ -42,4 +42,10 @@ describe('prepareMutation', () => {
       /Legacy PatchData/,
     )
   })
+
+  test('rejects an empty operations list in CLI language', () => {
+    expect(() => prepareMutation({ preconditions: [], operations: [] })).toThrow(
+      'Mutation V3 requires at least one operation',
+    )
+  })
 })

package/src/graph/mutation.ts

@@ -9,10 +9,23 @@ export function prepareMutation(input: unknown): MutationASTValue {
       'Legacy PatchData { nodes, edges } is not Mutation V3. Author { preconditions, operations } or a canonical astrale.graph.mutation/v3 document.',
     )
   }
+  if (hasEmptyOperations(input)) {
+    throw new TypeError('Mutation V3 requires at least one operation')
+  }
   if (isCanonicalCandidate(input)) return MutationAST.decode(input)
   return MutationAST.create(input as MutationInput)
 }
 
+function hasEmptyOperations(input: unknown): boolean {
+  return (
+    input !== null &&
+    typeof input === 'object' &&
+    !Array.isArray(input) &&
+    Array.isArray((input as { operations?: unknown }).operations) &&
+    (input as { operations: unknown[] }).operations.length === 0
+  )
+}
+
 function isCanonicalCandidate(input: unknown): boolean {
   return (
     input !== null &&

package/src/identity/__tests__/registry.test.ts

@@ -49,7 +49,7 @@ describe('identity registry journey', () => {
       bobKey: boolean
     }
     expect(result.store.default).toBe('alice')
-    expect(Object.keys(result.store.identities).sort()).toEqual(['alice', 'manager', 'workos'])
+    expect(Object.keys(result.store.identities).sort()).toEqual(['alice', 'workos'])
     expect(result.store.identities.alice.registrations?.production).toEqual({
       iss: 'https://kernel.example',
       sub: 'node-alice',

package/src/identity/registry.ts

@@ -1,3 +1,4 @@
+import { AstraleError } from '../errors'
 import { persistKeypair, removeKeypair } from '../keys/index'
 import { deleteIdpSession } from '../lib/idp'
 import { validateName } from '../lib/validation'
@@ -40,8 +41,12 @@ export async function createIdentity(
       kid: generated.kid,
       issuer: options.issuer,
     }
+    const hasDefault = store.default !== '' && store.identities[store.default] !== undefined
     return {
-      next: { ...store, identities: { ...store.identities, [name]: identity } },
+      next: {
+        default: hasDefault ? store.default : name,
+        identities: { ...store.identities, [name]: identity },
+      },
       value: identity,
     }
   })
@@ -83,12 +88,14 @@ export async function setDefault(name: string): Promise<void> {
 
 export async function getDefault(): Promise<Identity & { readonly name: string }> {
   const store = await readIdentities()
-  const identity = store.identities[store.default]
-  if (!identity) {
-    throw new Error(
-      `Default identity "${store.default}" not found. Run: astrale identity create ${store.default}`,
+  if (store.default === '' || store.identities[store.default] === undefined) {
+    throw new AstraleError(
+      'NO_IDENTITY',
+      'No default identity.',
+      'Run: astrale identity create <name>',
     )
   }
+  const identity = store.identities[store.default]!
   return { ...identity, name: store.default }
 }
 

package/src/lib/__tests__/command-dx.test.ts

@@ -11,6 +11,20 @@ import { collectCommandCatalog, renderCommanderError } from '../command-dx'
 const ANSI_RE = new RegExp(String.fromCharCode(27) + '\\[[0-9;]*m', 'g')
 const stripAnsi = (s: string): string => s.replace(ANSI_RE, '')
 
+function dx(
+  program: Awaited<ReturnType<typeof buildProgram>>,
+  error: CommanderError,
+  argv: string[],
+) {
+  const rendered = JSON.parse(stripAnsi(renderCommanderError(program, error, argv))) as {
+    error: string
+    message: string
+    detail: string
+  }
+  expect(rendered.error).toBe('USAGE_ERROR')
+  return rendered
+}
+
 describe('command DX suggestions', () => {
   test('collects command paths from the registered program tree', async () => {
     const program = await buildProgram()
@@ -23,8 +37,11 @@ describe('command DX suggestions', () => {
     expect(usages).toContain('use <name>')
     expect(usages).toContain('update')
     expect(usages).toContain('query [sources...]')
+    expect(usages).toContain('get <target>')
+    expect(usages).toContain('introspect <target>')
     expect(usages).toContain('status')
     expect(usages).not.toContain('ls <source>')
+    expect(usages).not.toContain('describe <target>')
   })
 
   test('explains shared verbs as namespaced commands, not arity errors', async () => {
@@ -34,24 +51,39 @@ describe('command DX suggestions', () => {
       'commander.excessArguments',
       'error: too many arguments. Expected 0 arguments but got 2.',
     )
-    const rendered = stripAnsi(renderCommanderError(program, error, ['delete', 'demo-system']))
+    const rendered = dx(program, error, ['delete', 'demo-system'])
+
+    expect(rendered.message).toContain('Unknown command: astrale delete demo-system')
+    expect(rendered.detail).toContain('"delete" is available under:')
+    expect(rendered.detail).toContain('astrale identity delete <name>')
+    expect(rendered.detail).toContain('astrale instance delete <id>')
+    expect(rendered.detail).not.toContain('too many arguments')
+  })
+
+  test('points retired describe at get', async () => {
+    const program = await buildProgram()
+    const error = new CommanderError(
+      1,
+      'commander.unknownCommand',
+      "error: unknown command 'describe'",
+    )
+    const rendered = dx(program, error, ['describe', '@note'])
 
-    expect(rendered).toContain('Unknown command: astrale delete demo-system')
-    expect(rendered).toContain('"delete" is available under:')
-    expect(rendered).toContain('astrale identity delete <name>')
-    expect(rendered).toContain('astrale instance delete <id>')
-    expect(rendered).not.toContain('too many arguments')
+    expect(rendered.message).toContain('Unknown command: astrale describe @note')
+    expect(rendered.detail).toContain('astrale describe` was removed')
+    expect(rendered.detail).toContain('astrale get <target>')
+    expect(rendered.detail).not.toContain('Did you mean:')
   })
 
   test('points retired ls at query', async () => {
     const program = await buildProgram()
     const error = new CommanderError(1, 'commander.unknownCommand', "error: unknown command 'ls'")
-    const rendered = stripAnsi(renderCommanderError(program, error, ['ls', '@note']))
+    const rendered = dx(program, error, ['ls', '@note'])
 
-    expect(rendered).toContain('Unknown command: astrale ls @note')
-    expect(rendered).toContain('astrale ls` was removed')
-    expect(rendered).toContain('astrale query <source> --edge <class>')
-    expect(rendered).not.toContain('Did you mean:')
+    expect(rendered.message).toContain('Unknown command: astrale ls @note')
+    expect(rendered.detail).toContain('astrale ls` was removed')
+    expect(rendered.detail).toContain('astrale query <source> --edge <class>')
+    expect(rendered.detail).not.toContain('Did you mean:')
   })
 
   test('suggests nearest command for typo paths', async () => {
@@ -61,10 +93,10 @@ describe('command DX suggestions', () => {
       'commander.excessArguments',
       'error: too many arguments. Expected 0 arguments but got 2.',
     )
-    const rendered = stripAnsi(renderCommanderError(program, error, ['indetityl', 'ist']))
+    const rendered = dx(program, error, ['indetityl', 'ist'])
 
-    expect(rendered).toContain('Unknown command: astrale indetityl ist')
-    expect(rendered).toContain('Did you mean:')
-    expect(rendered).toContain('astrale identity list')
+    expect(rendered.message).toContain('Unknown command: astrale indetityl ist')
+    expect(rendered.detail).toContain('Did you mean:')
+    expect(rendered.detail).toContain('astrale identity list')
   })
 })

package/src/lib/__tests__/instance-target.test.ts

@@ -225,4 +225,21 @@ describe('isManagedInstanceNotFound: kernel InternalKernelError wrap', () => {
     expect(caught).toBeInstanceOf(AstraleError)
     expect((caught as AstraleError).code).toBe('INSTANCE_NOT_FOUND')
   })
+
+  test('maps Admin token-exchange failure to INSTANCE_NOT_FOUND', async () => {
+    const managed = async () => {
+      throw new AstraleError(
+        'TOKEN_EXCHANGE_SOURCE_INVALID',
+        'The source identity credential has no valid expiration.',
+      )
+    }
+    const opts = {
+      config: DEFAULT_CONFIG,
+      instances: { instances: {} },
+      managed,
+    } as unknown as Parameters<typeof resolveInstanceTarget>[1]
+    await expect(
+      resolveInstanceTarget({ source: 'name', name: 'ghost' }, opts),
+    ).rejects.toMatchObject({ code: 'INSTANCE_NOT_FOUND' })
+  })
 })

package/src/lib/__tests__/output.test.ts

@@ -112,6 +112,18 @@ describe('denoise', () => {
     })
     expect(out).toEqual({ id: 'x', props: { name: 'n' } })
   })
+
+  test('strips qualified property keys whose leaf is schema', () => {
+    const out = denoise({
+      props: {
+        'kernel.astrale.ai:class.Domain.property.schema': { huge: true },
+        'kernel.astrale.ai:class.Domain.property.origin': 'kernel.astrale.ai',
+      },
+    })
+    expect(out).toEqual({
+      props: { 'kernel.astrale.ai:class.Domain.property.origin': 'kernel.astrale.ai' },
+    })
+  })
 })
 
 describe('presentList', () => {

package/src/lib/command-dx.ts

@@ -2,6 +2,8 @@ import type { Command, CommanderError } from 'commander'
 
 import chalk from 'chalk'
 
+import { isMachine } from './output'
+
 export type CommandCatalogEntry = {
   path: string[]
   usage: string
@@ -34,46 +36,53 @@ export function renderCommanderError(
   const matched = matchRegisteredPrefix(program, tokens)
 
   if (matched.path.length === 0 && tokens.length > 0) {
-    return renderUnknownCommand(tokens, catalog)
+    return maybeMachine(renderUnknownCommand(tokens, catalog))
   }
 
   if (error.code === 'commander.missingArgument') {
     const usage = usageFor(matched.path, matched.command)
     const argName = error.message.match(/'([^']+)'/)?.[1]
-    return [
-      `Missing required argument${argName ? ` ${chalk.bold(`<${argName}>`)}` : ''} for ${chalk.bold(
-        `astrale ${matched.path.join(' ')}`,
-      )}`,
-      '',
-      'Usage:',
-      `  astrale ${usage}`,
-    ].join('\n')
+    return maybeMachine(
+      [
+        `Missing required argument${argName ? ` ${chalk.bold(`<${argName}>`)}` : ''} for ${chalk.bold(
+          `astrale ${matched.path.join(' ')}`,
+        )}`,
+        '',
+        'Usage:',
+        `  astrale ${usage}`,
+      ].join('\n'),
+    )
   }
 
   if (error.code === 'commander.excessArguments') {
     const usage = usageFor(matched.path, matched.command)
     const extra = tokens.slice(matched.path.length).join(' ')
-    return [
-      `Unexpected argument${extra.includes(' ') ? 's' : ''} for ${chalk.bold(
-        `astrale ${matched.path.join(' ')}`,
-      )}${extra ? `: ${extra}` : ''}`,
-      '',
-      'Usage:',
-      `  astrale ${usage}`,
-    ].join('\n')
+    return maybeMachine(
+      [
+        `Unexpected argument${extra.includes(' ') ? 's' : ''} for ${chalk.bold(
+          `astrale ${matched.path.join(' ')}`,
+        )}${extra ? `: ${extra}` : ''}`,
+        '',
+        'Usage:',
+        `  astrale ${usage}`,
+      ].join('\n'),
+    )
   }
 
   const suggestions = nearestCommands(tokens.join(' '), catalog)
-  return [
-    error.message,
-    ...(suggestions.length > 0
-      ? ['', 'Did you mean:', ...suggestions.map((s) => `  astrale ${s}`)]
-      : []),
-  ].join('\n')
+  return maybeMachine(
+    [
+      error.message,
+      ...(suggestions.length > 0
+        ? ['', 'Did you mean:', ...suggestions.map((s) => `  astrale ${s}`)]
+        : []),
+    ].join('\n'),
+  )
 }
 
 const RETIRED_COMMANDS: Record<string, string> = {
   ls: 'astrale query <source> --edge <class>',
+  describe: 'astrale get <target>',
 }
 
 function renderUnknownCommand(tokens: string[], catalog: CommandCatalogEntry[]): string {
@@ -132,6 +141,15 @@ function usageFor(path: string[], command: Command): string {
   return [path.join(' '), suffix].filter(Boolean).join(' ')
 }
 
+const ANSI_RE = new RegExp(String.fromCharCode(27) + '\\[[0-9;]*m', 'g')
+
+function maybeMachine(text: string): string {
+  if (!isMachine()) return text
+  const plain = text.replace(ANSI_RE, '')
+  const first = plain.split('\n').find((line) => line.trim().length > 0) ?? plain
+  return JSON.stringify({ error: 'USAGE_ERROR', message: first, detail: plain })
+}
+
 function stripOptions(argv: string[]): string[] {
   const out: string[] = []
   for (const token of argv) {

package/src/lib/instance-target.ts

@@ -94,8 +94,8 @@ async function resolveNamedInstanceTarget(
   try {
     managed = await opts.managed(identifier)
   } catch (e) {
-    if (!isManagedInstanceNotFound(e)) throw e
-    throw notFound
+    if (isManagedInstanceNotFound(e) || isAdminDiscoveryFailure(e)) throw notFound
+    throw e
   }
 
   const url = normalizeInstanceKernelUrl(managed.url)
@@ -173,6 +173,22 @@ export function adminTargetToInstance(target: ResolvedAdminTarget): ResolvedInst
   }
 }
 
+const ADMIN_DISCOVERY_CODES = new Set([
+  'TOKEN_EXCHANGE_SOURCE_INVALID',
+  'TOKEN_EXCHANGE_SOURCE_EXPIRED',
+  'TOKEN_EXCHANGE_UNSUPPORTED',
+  'TOKEN_EXCHANGE_DISCOVERY_FAILED',
+  'TOKEN_EXCHANGE_PROTOCOL_ERROR',
+  'TOKEN_EXCHANGE_INSECURE',
+  'ADMIN_DOMAIN_ISSUER_MISSING',
+  'ADMIN_INVENTORY_UNAVAILABLE',
+])
+
+/** Admin lookup failed before it could say whether the slug exists. */
+export function isAdminDiscoveryFailure(error: unknown): boolean {
+  return error instanceof AstraleError && ADMIN_DISCOVERY_CODES.has(error.code)
+}
+
 export function isManagedInstanceNotFound(error: unknown): boolean {
   if (error instanceof AstraleError && error.code === 'INSTANCE_NOT_FOUND') return true
   if (!(error instanceof Error)) return false

package/src/lib/invocation.ts

@@ -0,0 +1,11 @@
+/** Process-wide machine mode from argv (`--json` / `--raw` / `--ci`). */
+
+let argvMachine = false
+
+export function configureInvocation(argv: readonly string[]): void {
+  argvMachine = argv.some((token) => token === '--json' || token === '--raw' || token === '--ci')
+}
+
+export function invocationWantsMachine(): boolean {
+  return argvMachine
+}

package/src/lib/log.ts

@@ -3,7 +3,7 @@ import ora, { type Ora } from 'ora'
 
 import { AstraleError, NotImplementedError } from '../errors'
 import { formatElapsed } from './format'
-import { isMachine, type RawOutputOpts } from './output'
+import { isMachine, type MachineOpts } from './output'
 
 export const log = {
   info: (msg: string) => console.log(chalk.blue('ℹ'), msg),
@@ -16,26 +16,34 @@ export const log = {
   dim: (msg: string) => console.log(chalk.dim(msg)),
 }
 
-/** Report an error with hint (when present) and exit. Commands that carry
- *  RawOutputOpts should pass them so machine consumers (--json/--raw/piped)
- *  get one structured JSON line on stderr instead of the pretty ✖ view. */
-export function fatal(e: unknown, opts?: RawOutputOpts): never {
+/** Report an error with hint (when present) and exit. `--json` / `--ci` / a
+ *  non-TTY stdout always get one structured JSON line on stderr. */
+export function fatal(e: unknown, opts?: MachineOpts): never {
   // Ctrl-C at an interactive (@inquirer/prompts) prompt — exit quietly with the
   // SIGINT convention, not a red error line.
   if (e instanceof Error && e.name === 'ExitPromptError') process.exit(130)
   const msg = e instanceof Error ? e.message : String(e)
-  if (opts && isMachine(opts)) {
-    const error = e instanceof AstraleError ? e.code : e instanceof Error ? e.name : 'Error'
-    const payload: Record<string, unknown> = { error, message: msg }
+  const code = e instanceof AstraleError ? e.code : e instanceof Error ? e.name : 'Error'
+  if (isMachine(opts)) {
+    const payload: Record<string, unknown> = { error: code, message: msg }
     if (e instanceof AstraleError && e.hint) payload.hint = e.hint
     process.stderr.write(JSON.stringify(payload) + '\n')
     process.exit(1)
   }
-  log.error(msg)
+  log.error(e instanceof AstraleError ? `${code}: ${msg}` : msg)
   if (e instanceof AstraleError && e.hint) log.dim(`  hint: ${e.hint}`)
   process.exit(1)
 }
 
+/** Admit expected invalid input and exit through {@link fatal}. */
+export function failClosed(error: unknown, opts?: MachineOpts): never {
+  if (error instanceof AstraleError) fatal(error, opts)
+  fatal(
+    new AstraleError('INVALID_INPUT', error instanceof Error ? error.message : String(error)),
+    opts,
+  )
+}
+
 /** Shortcut for stub commands that aren't wired in v1 (§15). */
 export function fatalNotImplemented(feature: string, hint?: string): never {
   fatal(new NotImplementedError(feature, hint))

package/src/lib/output.ts

@@ -1,6 +1,7 @@
 import chalk from 'chalk'
 import { stringify as yamlStringify } from 'yaml'
 
+import { invocationWantsMachine } from './invocation'
 import { renderTable, type Column } from './table'
 
 export type { Column } from './table'
@@ -13,6 +14,8 @@ export type OutputOpts = {
 
 export type RawOutputOpts = Pick<OutputOpts, 'raw' | 'json'>
 
+export type MachineOpts = RawOutputOpts & { readonly ci?: boolean }
+
 export const RAW_OUTPUT_OPTIONS = [
   { flags: '--json', description: 'Always-valid JSON (for jq)' },
   { flags: '--raw', description: 'Unwrapped: bare scalar / raw bytes / JSON for objects' },
@@ -20,10 +23,15 @@ export const RAW_OUTPUT_OPTIONS = [
 
 /**
  * Is the consumer a machine (emit structured data, not a pretty view)?
- * True for `--json`, `--raw`, or any non-TTY stdout (pipe, redirect, CI, agent).
+ * True for `--json`, `--raw`, `--ci`, a process-wide `--ci/--json/--raw` on argv,
+ * or any non-TTY stdout (pipe, redirect, agent).
  */
-export function isMachine(opts?: RawOutputOpts): boolean {
-  return !!(opts?.raw || opts?.json) || !(process.stdout.isTTY ?? false)
+export function isMachine(opts?: MachineOpts): boolean {
+  return (
+    !!(opts?.raw || opts?.json || opts?.ci) ||
+    invocationWantsMachine() ||
+    !(process.stdout.isTTY ?? false)
+  )
 }
 
 /**
@@ -132,6 +140,14 @@ export type ListOpts = OutputOpts & {
 
 const NOISE_KEYS = new Set(['schema', 'icon', 'code', 'inputSchema', 'outputSchema'])
 
+function isNoiseKey(key: string): boolean {
+  if (NOISE_KEYS.has(key)) return true
+  const dot = key.lastIndexOf('.')
+  const colon = key.lastIndexOf(':')
+  const split = Math.max(dot, colon)
+  return split >= 0 && NOISE_KEYS.has(key.slice(split + 1))
+}
+
 /**
  * Strip heavy, low-signal keys (serialized schema blobs, SVG icons, code) at any
  * depth — so machine output is the kernel's data minus the noise, never a wall.
@@ -141,7 +157,7 @@ export function denoise(value: unknown): unknown {
   if (value && typeof value === 'object') {
     const out: Record<string, unknown> = {}
     for (const [k, v] of Object.entries(value)) {
-      if (NOISE_KEYS.has(k)) continue
+      if (isNoiseKey(k)) continue
       out[k] = v && typeof v === 'object' ? denoise(v) : v
     }
     return out