@astrale-os/cli 0.4.0-alpha.13 → 0.5.0-alpha.0

package/src/commands/query.ts

@@ -1,32 +1,300 @@
-import { K } from '@astrale-os/kernel-core'
+import { getInputSchema, K } from '@astrale-os/kernel-core'
+import chalk from 'chalk'
 
 import type { CommandDefinition } from '../command'
-import type { KernelCommandOpts } from '../kernel'
+import type { GetResultWire, KernelCommandOpts, QueryASTInput, SelfExpansionMeta } from '../kernel'
 
-import { runKernelCommand } from '../kernel'
+import { bindGraph, expandSelfInPath, runKernelCommand, withSelfHint } from '../kernel'
+import { log } from '../lib/log'
+import { isMachine, output } from '../lib/output'
 
-export async function queryCommand(cypher: string, opts: KernelCommandOpts): Promise<void> {
-  await runKernelCommand({
+type QueryOpts = KernelCommandOpts & {
+  depth?: string
+  children?: string
+  edges?: string
+  ast?: string
+  cypher?: string
+}
+
+type QueryMode =
+  | { kind: 'cypher'; cypher: string }
+  | { kind: 'ast'; ast: QueryASTInput }
+  | { kind: 'roots'; roots: string[]; meta: SelfExpansionMeta | undefined; query: BuiltQuery }
+
+export async function queryCommand(paths: string[], opts: QueryOpts): Promise<void> {
+  let mode: QueryMode
+  try {
+    mode = await parseMode(paths, opts)
+  } catch (e) {
+    log.error(e instanceof Error ? e.message : 'Invalid arguments')
+    process.exit(1)
+    return
+  }
+
+  if (mode.kind === 'cypher') {
+    await runKernelCommand({
+      opts,
+      label: 'Query',
+      fn: (ctx) => ctx.client.call(K.$.f('query').path.domain.raw, { cypher: mode.cypher }),
+      format: (result, fmtOpts) => output(result, fmtOpts),
+    })
+    return
+  }
+
+  await runKernelCommand<GetResultWire>({
     opts,
-    label: 'Query',
-    fn: (ctx) => ctx.client.call(K.Root.query.path.method.raw, { cypher }),
+    label: mode.kind === 'roots' ? 'Query ' + mode.roots.join(' ') : 'Query',
+    fn: async (ctx) => {
+      const read = () => bindGraph(ctx).query(mode.kind === 'roots' ? mode.query.ast : mode.ast)
+      const result =
+        mode.kind === 'roots' ? await withSelfHint(read, mode.meta) : await read()
+      return result.wire
+    },
+    format: (result, fmtOpts) => {
+      output(result, fmtOpts)
+      if (result.next && !isMachine(fmtOpts)) printCursorFooter(result.next)
+    },
+  })
+}
+
+async function parseMode(paths: string[], opts: QueryOpts): Promise<QueryMode> {
+  const rootsInput = paths ?? []
+  const hasRoots = rootsInput.length > 0
+  const hasAst = opts.ast !== undefined
+  const hasCypher = opts.cypher !== undefined
+  const hasSelectors = opts.depth !== undefined || opts.children !== undefined || opts.edges !== undefined
+
+  if (hasCypher) {
+    if (hasAst || hasRoots || hasSelectors) {
+      throw new Error('--cypher cannot be used with roots, --ast, --depth, --children, or --edges')
+    }
+    return { kind: 'cypher', cypher: opts.cypher as string }
+  }
+
+  if (hasAst) {
+    if (hasRoots || hasSelectors) {
+      throw new Error('--ast cannot be used with positional roots or --depth/--children/--edges')
+    }
+    return { kind: 'ast', ast: parseAst(opts.ast as string) }
+  }
+
+  if (!hasRoots) {
+    throw new Error(
+      'Usage: astrale query <paths...> [--depth <n>] [--children <json>] [--edges <json>] | --ast <json> | --cypher <query>',
+    )
+  }
+
+  const { roots, meta } = await expandRoots(rootsInput, opts)
+  return { kind: 'roots', roots, meta, query: buildQuery(roots, opts) }
+}
+
+function parseAst(raw: string): QueryASTInput {
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(raw)
+  } catch {
+    throw new Error('--ast must be JSON: ' + raw)
+  }
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new Error('--ast must be a JSON object')
+  }
+  return parsed as QueryASTInput
+}
+
+async function expandRoots(
+  paths: string[],
+  opts: QueryOpts,
+): Promise<{ roots: string[]; meta: SelfExpansionMeta | undefined }> {
+  const roots: string[] = []
+  let meta: SelfExpansionMeta | undefined
+  for (const p of paths) {
+    const expanded = await expandSelfInPath(p, opts)
+    roots.push(expanded.path)
+    if (!meta && expanded.meta) meta = expanded.meta
+  }
+  return { roots, meta }
+}
+
+type QueryDir = 'in' | 'out' | 'both'
+type QueryOrder = { by: string; dir: 'asc' | 'desc' }
+type ChildrenSelector = { classes?: string[]; limit?: number; cursor?: string; order?: QueryOrder }
+type EdgeSelector = {
+  as?: string
+  classes?: string[]
+  direction?: QueryDir
+  limit?: number
+  cursor?: string
+  order?: QueryOrder
+}
+type BuiltQuery = { ast: QueryASTInput; depth: number; hasEdges: boolean }
+
+function buildQuery(roots: string[], opts: QueryOpts): BuiltQuery {
+  const depth = opts.depth !== undefined ? parseRange('--depth', opts.depth, 0, 5) : 0
+  const children =
+    opts.children !== undefined
+      ? parseSelector<ChildrenSelector>('--children', opts.children, getInputSchema.shape.children)
+      : undefined
+  const edges =
+    opts.edges !== undefined
+      ? parseSelector<EdgeSelector | EdgeSelector[]>(
+          '--edges',
+          opts.edges,
+          getInputSchema.shape.edges,
+        )
+      : undefined
+
+  const steps: NonNullable<QueryASTInput['steps']> = []
+  if (depth > 0) steps.push({ expand: childExpand(depth, children) })
+  edgeSelectors(edges).forEach((selector, index) => {
+    steps.push({ expand: edgeExpand(selector, index) })
   })
+
+  return {
+    ast: { version: 1, from: roots, ...(steps.length > 0 ? { steps } : {}) },
+    depth,
+    hasEdges: edges !== undefined,
+  }
+}
+
+function childExpand(depth: number, children: ChildrenSelector | undefined) {
+  return {
+    edge: 'has_parent',
+    dir: 'in' as const,
+    depth,
+    ...(children?.classes !== undefined ? { filter: { class: children.classes } } : {}),
+    ...pageFields(children),
+    ...(children?.order !== undefined ? { order: children.order } : {}),
+  }
+}
+
+function edgeExpand(selector: EdgeSelector, index: number) {
+  return {
+    ...(selector.classes !== undefined ? { edge: selector.classes } : {}),
+    dir: selector.direction ?? 'both',
+    as: selector.as ?? 'e' + index,
+    ...pageFields(selector),
+    ...(selector.order !== undefined ? { order: selector.order } : {}),
+  }
+}
+
+function pageFields(selector: { limit?: number; cursor?: string } | undefined) {
+  if (selector?.limit === undefined && selector?.cursor === undefined) return {}
+  return {
+    page: {
+      ...(selector.limit !== undefined ? { limit: selector.limit } : {}),
+      ...(selector.cursor !== undefined ? { cursor: selector.cursor } : {}),
+    },
+  }
+}
+
+function edgeSelectors(edges: EdgeSelector | EdgeSelector[] | undefined): EdgeSelector[] {
+  if (edges === undefined) return []
+  return Array.isArray(edges) ? edges : [edges]
+}
+
+function parseRange(flag: string, raw: string, min: number, max: number): number {
+  const n = Number(raw)
+  if (!Number.isInteger(n) || n < min || n > max) {
+    throw new Error(flag + ' needs an integer in [' + min + ', ' + max + '], got "' + raw + '"')
+  }
+  return n
+}
+
+type SelectorIssue = { readonly path: readonly PropertyKey[]; readonly message: string }
+type SelectorSchema = {
+  safeParse(
+    value: unknown,
+  ): { success: true } | { success: false; error: { issues: readonly SelectorIssue[] } }
+}
+
+function parseSelector<T>(flag: string, raw: string, schema: SelectorSchema): T {
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(raw)
+  } catch {
+    throw new Error(flag + ' must be JSON: ' + raw)
+  }
+  if (parsed === null || typeof parsed !== 'object') {
+    throw new Error(flag + ' must be a JSON selector object' + (flag === '--edges' ? ' or array' : ''))
+  }
+  const check = schema.safeParse(parsed)
+  if (!check.success) {
+    const detail = check.error.issues
+      .map((i) => (i.path.join('.') || '(root)') + ': ' + i.message)
+      .join('; ')
+    throw new Error(flag + ' invalid selector: ' + detail)
+  }
+  return parsed as T
+}
+
+function printCursorFooter(next: NonNullable<GetResultWire['next']>): void {
+  const entries = Object.entries(next)
+  if (entries.length === 1) {
+    const cursors = entries[0]?.[1]
+    if (cursors?.children) {
+      process.stdout.write(chalk.dim('  more: --children \'{"cursor":"' + cursors.children + '"}\'\n'))
+    }
+    for (const [alias, cursor] of Object.entries(cursors?.edges ?? {})) {
+      process.stdout.write(
+        chalk.dim('  more edges[' + alias + ']: --edges \'{"as":"' + alias + '","cursor":"' + cursor + '"}\'\n'),
+      )
+    }
+    return
+  }
+  process.stdout.write(
+    chalk.dim('  more results - per-root cursors in .next (page each root by --cursor)\n'),
+  )
 }
 
 export default {
   name: 'query',
-  description: 'Run a read-only Cypher query against the kernel graph',
-  afterHelpText: `
-Behavior:
-  Read-only. The kernel rejects write keywords (CREATE, DELETE, SET,
-  MERGE, REMOVE, DETACH); enforcement is kernel-side.
-
-Examples:
-  $ astrale query 'MATCH (n) RETURN count(n) AS total'
-  $ astrale query 'MATCH (n:Domain) RETURN n.slug, n.id'
-`,
-  arguments: [{ name: 'cypher', description: 'Cypher query string' }],
-  action: async (cypher, opts) => {
-    await queryCommand(cypher as string, opts as KernelCommandOpts)
+  description: 'Run a structured graph read',
+  afterHelpText: [
+    '',
+    'Behavior:',
+    '  Structured read door for the query AST. Positional roots build a v1 AST',
+    '  with optional child and edge expansion, then lower through function.get',
+    '  today. A true query syscall may back this command later.',
+    '',
+    '  Output is always the full GraphData envelope { nodes, edges, aliases }',
+    '  with .roots and .next when returned. On a TTY, cursor footers are printed',
+    '  when .next has more pages.',
+    '',
+    '  --children takes { classes?, limit?, cursor?, order? } and shapes the',
+    '  depth-1 children page (needs --depth >= 1 to bite). --edges takes an edge',
+    '  selector, or a JSON array of selectors.',
+    '',
+    '  --ast (experimental) accepts a raw QueryASTInput JSON object. The AST shape',
+    '  is not a stable contract yet — prefer the flags above. @self is not expanded',
+    '  inside --ast JSON.',
+    '',
+    '  --cypher is a read-only escape hatch. The kernel rejects write keywords',
+    '  such as CREATE, DELETE, SET, MERGE, REMOVE, and DETACH.',
+    '',
+    'Examples:',
+    '  $ astrale query / --depth 1',
+    '  $ astrale query /a /b --edges \'{"direction":"both"}\'',
+    '  $ astrale query /kernel.astrale.ai --depth 2 --children \'{"classes":["/:kernel.astrale.ai:class.Folder"]}\'',
+    "  $ astrale query --cypher 'MATCH (n) RETURN count(n) AS total'",
+    '',
+  ].join('\n'),
+  arguments: [
+    { name: 'paths...', description: 'One or more root paths (/domain/Class) or IDs (@nodeId)', required: false },
+  ],
+  options: [
+    { flags: '--depth <n>', description: 'Subtree depth to fetch (0-5, default 0)' },
+    {
+      flags: '--children <json>',
+      description: 'Children selector { classes?, limit?, cursor?, order? } (needs --depth >= 1)',
+    },
+    {
+      flags: '--edges <json>',
+      description: 'Edge selector (or JSON array of selectors) to include',
+    },
+    { flags: '--ast <json>', description: 'Raw QueryASTInput JSON object (experimental, unstable shape)' },
+    { flags: '--cypher <query>', description: 'Read-only Cypher escape hatch' },
+  ],
+  action: async (paths, opts) => {
+    await queryCommand(Array.isArray(paths) ? paths : [], opts as QueryOpts)
   },
 } satisfies CommandDefinition

package/src/commands/token.ts

@@ -2,12 +2,11 @@ import type { CommandDefinition } from '../command'
 import type { KernelCommandOpts } from '../kernel'
 
 import { runKernelCommand } from '../kernel'
-import { mintDelegationPath } from '../kernel/remote-routing'
 import { log } from '../lib/log'
 
 /**
  * `astrale token` — mint a fresh delegation token for the active instance
- * + active identity (§2.5). Shortcut over the mintDelegationCredential call.
+ * + active identity through the bound AuthApi.
  */
 export type TokenOpts = KernelCommandOpts & {
   audience?: string
@@ -26,12 +25,10 @@ export async function tokenCommand(opts: TokenOpts): Promise<void> {
       const audience = opts.audience ?? ''
       const parsedTtl = Number(opts.ttl)
       const ttl = Number.isFinite(parsedTtl) && parsedTtl > 0 ? parsedTtl : 3600
-      const mintPath = await mintDelegationPath(ctx.client, ctx.credential)
-      const result = (await ctx.client.call(mintPath, {
+      const result = await ctx.client.as(ctx.credential).auth.delegate({
         audience,
-        delegation: { kind: 'identity', self: true },
         ttl,
-      })) as string
+      })
       return result
     },
     format: (token, fmtOpts, isRaw) => {
@@ -63,7 +60,7 @@ What this token is FOR — worker-direct HTTP calls:
   use 'astrale call' (which signs per-call) instead.
 
 Examples:
-  $ export TOKEN=$(astrale token --audience dist.astrale.ai --raw)
+  $ export TOKEN=$(astrale token --audience workspace.astrale.ai --raw)
   $ astrale token --audience worker.example.com --for alice -i staging
 `,
   options: [

package/src/kernel/__tests__/expand.test.ts

@@ -0,0 +1,123 @@
+import { describe, expect, test } from 'bun:test'
+
+import type { SelfResolverContext } from '../../lib/self'
+
+import { resolveSelfIdLazy } from '../expand'
+
+describe('resolveSelfIdLazy', () => {
+  test('refreshes a cached IdP @self registration via whoami', async () => {
+    const writes: unknown[][] = []
+    const ctx: SelfResolverContext = {
+      identity: {
+        name: 'bryan',
+        subject: 'user_01KC9MW1M6S5J6V9ERSRJ8RDYF',
+        createdAt: '2026-06-25T08:00:00.000Z',
+        source: 'idp',
+        registrations: {
+          bryan: {
+            iss: 'https://old.example',
+            sub: '4ad8e4ce-5cf7-4c2e-ab29-5549023dc8bf',
+            registeredAt: '2026-06-25T08:00:00.000Z',
+          },
+        },
+      },
+      instanceSlug: 'bryan',
+      instanceSigned: false,
+    }
+
+    const id = await resolveSelfIdLazy(
+      ctx,
+      {},
+      {
+        whoami: async () => ({
+          id: 'f011538e-9edc-4c29-92ce-9b81b6c1b6c7',
+          kernelUrl: 'https://bryan.example',
+        }),
+        setRegistration: async (...args) => {
+          writes.push(args)
+        },
+        now: () => new Date('2026-06-25T08:15:00.000Z'),
+      },
+    )
+
+    expect(id).toBe('f011538e-9edc-4c29-92ce-9b81b6c1b6c7')
+    expect(writes).toEqual([
+      [
+        'bryan',
+        'bryan',
+        {
+          iss: 'https://bryan.example',
+          sub: 'f011538e-9edc-4c29-92ce-9b81b6c1b6c7',
+          registeredAt: '2026-06-25T08:15:00.000Z',
+        },
+      ],
+    ])
+  })
+
+  test('keeps the cached IdP id when whoami is temporarily unavailable', async () => {
+    const ctx: SelfResolverContext = {
+      identity: {
+        name: 'bryan',
+        subject: 'user_01KC9MW1M6S5J6V9ERSRJ8RDYF',
+        createdAt: '2026-06-25T08:00:00.000Z',
+        source: 'idp',
+        registrations: {
+          bryan: {
+            iss: 'https://bryan.example',
+            sub: 'cached-id',
+            registeredAt: '2026-06-25T08:00:00.000Z',
+          },
+        },
+      },
+      instanceSlug: 'bryan',
+      instanceSigned: false,
+    }
+
+    await expect(
+      resolveSelfIdLazy(
+        ctx,
+        {},
+        {
+          whoami: async () => {
+            throw new Error('network down')
+          },
+        },
+      ),
+    ).resolves.toBe('cached-id')
+  })
+
+  test('does not run whoami for key-backed registrations', async () => {
+    const ctx: SelfResolverContext = {
+      identity: {
+        name: 'alice',
+        subject: 'alice',
+        createdAt: '2026-06-25T08:00:00.000Z',
+        source: 'key',
+        registrations: {
+          bryan: {
+            iss: 'https://bryan.example',
+            sub: 'key-node-id',
+            registeredAt: '2026-06-25T08:00:00.000Z',
+          },
+        },
+      },
+      instanceSlug: 'bryan',
+      instanceSigned: false,
+    }
+    let called = false
+
+    const id = await resolveSelfIdLazy(
+      ctx,
+      {},
+      {
+        whoami: async () => {
+          called = true
+          return { id: 'should-not-be-used', kernelUrl: 'https://bryan.example' }
+        },
+      },
+    )
+
+    expect(id).toBe('key-node-id')
+    expect(called).toBe(false)
+  })
+})

package/src/kernel/client.ts

@@ -1,5 +1,5 @@
 import { KernelClient, type FnMap } from '@astrale-os/kernel-client'
-import { ClientSession } from '@astrale-os/kernel-client/session'
+import { ClientSession, delegationMintVia } from '@astrale-os/kernel-client/session'
 
 import type { AdminTargetCommandOpts } from '../lib/admin-target'
 import type { KernelCommandOpts } from './types'
@@ -10,7 +10,6 @@ import { readConfig } from '../lib/config'
 import { resolveInstanceTarget, type ResolvedInstanceTarget } from '../lib/instance-target'
 import { resolveCredential } from './auth'
 import { fetchWithCaFile } from './ca-fetch'
-import { mintRemoteCredential } from './remote-routing'
 
 const DEFAULT_TIMEOUT_MS = 30_000
 
@@ -131,21 +130,12 @@ async function withResolvedKernelClient<T>(
   // exponential backoff on ECONNREFUSED / 5xx). The user can re-run.
   const requestTimeout = resolveTimeoutMs(opts.timeout)
   const fetchImpl = target.caFile ? fetchWithCaFile(target.caFile) : undefined
-  // The delegation mint references `client` lazily — it only fires on a cache
-  // miss during an actual remote call, long after this binding is initialised,
-  // so the self-reference inside the closure is safe.
   const client: ClientSession<FnMap> = new ClientSession<FnMap>({
     default: target.url,
     identity: credential,
-    // Remote-bound functions redirect to a worker that verifies `aud` against
-    // its own identity. The session follows the redirect and mints a worker-
-    // scoped delegation here, for the audience the kernel carries on the
-    // redirect (`redirection.iss`, surfaced by the default iss-aware policy).
     delegation: {
-      mint: async (audience) => ({
-        credential: await mintRemoteCredential(client, audience, credential),
-        ttl: 3600,
-      }),
+      // Resolve lazily: the session must exist before the cache mints.
+      mint: delegationMintVia(() => client, credential),
       ttl: 3600,
     },
     pool: {

package/src/kernel/expand.ts

@@ -2,13 +2,7 @@ import type { InstanceInfo } from '../lib/admin-instance'
 import type { KernelCommandOpts } from './types'
 
 import { ADMIN_INSTANCE } from '../lib/admin-instance'
-/**
- * Bridges `lib/self.ts` to CLI command sites: builds a `SelfResolverContext`
- * from CLI opts, resolves a nodeId via
- * `resolveOrThrow` (throwing `SelfRefusalError` on refusal), and wraps async
- * calls with `withSelfHint` so `NotFoundError`s carry expansion metadata for
- * the stale-registration hint emitted by `formatKernelError`.
- */
+/** CLI bridge for @self resolution and stale-registration error hints. */
 import { readConfig } from '../lib/config'
 import { getDefault, getIdentity, setRegistration } from '../lib/identity'
 import { decodeTokenClaims, readIdpSession } from '../lib/idp'
@@ -34,13 +28,7 @@ export type SelfExpansionMeta = {
   slug?: string
 }
 
-/**
- * Build a `SelfResolverContext` from CLI opts. Mirrors the target +
- * signing-mode logic in `withKernelClient` / `resolveCredential`.
- *
- * Cheap enough to call eagerly; commands skip the call entirely when
- * `containsSelfRef` returns false on every input.
- */
+/** Build the same target/signing context `withKernelClient` will use. */
 export async function buildSelfContext(opts: KernelCommandOpts): Promise<SelfResolverContext> {
   const config = await readConfig()
   // Mirror withKernelClient's slug logic: --url without -i ⇒ no slug.
@@ -70,11 +58,7 @@ export async function buildSelfContext(opts: KernelCommandOpts): Promise<SelfRes
     instanceSigned = await fileExists(privatePath)
   }
 
-  // Identity that will sign (only relevant when not instance-signed and not --creds).
-  // Failures here (corrupt identities.json, missing --as identity) are
-  // re-thrown rather than swallowed — swallowing produces a useless
-  // refusal naming `identityName: '(unknown)'`. The fatal-error UX is
-  // honest about the actual problem.
+  // Identity lookup failures should surface as real CLI errors, not @self refusals.
   let identity: SelfResolverContext['identity']
   if (!opts.creds) {
     const identityName = opts.as ?? defaultIdentity
@@ -142,59 +126,68 @@ export function resolveOrThrow(selfCtx: SelfResolverContext): string {
   return r.id
 }
 
-// The kernel's whoami — returns the AUTHENTICATED principal's graph node.
-// Static interface method, so the colon form (slash form is rejected).
-const WHOAMI_PATH = '/:kernel.astrale.ai:interface.Identity:whoami'
+export type ResolveSelfIdLazyDeps = {
+  whoami?: (opts: KernelCommandOpts) => Promise<{ id?: unknown; kernelUrl: string }>
+  setRegistration?: typeof setRegistration
+  now?: () => Date
+}
 
 /**
- * Resolve `@self`, falling back to ONE kernel `whoami` round-trip when an
- * IdP identity merely lacks a cached registration on this instance (the
- * normal `astrale auth login` flow — the IdP subject is never a node id).
- * The resolved id is persisted as a registration so subsequent expansions
- * are local again. Every other refusal (manager, instance-signed, …) and a
- * failed whoami throw the typed refusal unchanged.
+ * Resolve @self for IdP identities through one whoami refresh, then cache the
+ * current node id. Non-IdP refusals stay typed and local.
  */
 export async function resolveSelfIdLazy(
   selfCtx: SelfResolverContext,
   opts: KernelCommandOpts,
+  deps: ResolveSelfIdLazyDeps = {},
 ): Promise<string> {
   const r: SelfResolution = resolveSelfNodeId(selfCtx)
-  if (!('reason' in r)) return r.id
-  if (r.reason !== 'idp-no-sub' || !selfCtx.instanceSlug || !selfCtx.identity) {
-    throw selfRefusalError(r)
+  const cachedId = 'reason' in r ? undefined : r.id
+  const isIdp = (selfCtx.identity?.source ?? 'key') === 'idp'
+
+  if (isIdp && selfCtx.instanceSlug && selfCtx.identity) {
+    let lookup: { id?: unknown; kernelUrl: string }
+    try {
+      lookup = await (deps.whoami ?? whoamiSelfId)(opts)
+    } catch {
+      if (cachedId) return cachedId
+      if ('reason' in r) throw selfRefusalError(r)
+      throw selfRefusalError({ reason: 'idp-no-sub', identityName: selfCtx.identity.name })
+    }
+
+    const resolvedId =
+      typeof lookup.id === 'string' && lookup.id.trim().length > 0 ? lookup.id : undefined
+    if (!resolvedId) {
+      if (cachedId) return cachedId
+      if ('reason' in r) throw selfRefusalError(r)
+      throw selfRefusalError({ reason: 'idp-no-sub', identityName: selfCtx.identity.name })
+    }
+
+    const cached = selfCtx.identity.registrations?.[selfCtx.instanceSlug]
+    if (cached?.sub !== resolvedId || cached?.iss !== lookup.kernelUrl) {
+      await (deps.setRegistration ?? setRegistration)(selfCtx.identity.name, selfCtx.instanceSlug, {
+        iss: lookup.kernelUrl,
+        sub: resolvedId,
+        registeredAt: (deps.now ?? (() => new Date()))().toISOString(),
+      })
+    }
+    return resolvedId
   }
-  let me: { id?: unknown } | null
+
+  if (!('reason' in r)) return r.id
+  throw selfRefusalError(r)
+}
+
+async function whoamiSelfId(opts: KernelCommandOpts): Promise<{ id?: unknown; kernelUrl: string }> {
   let kernelUrl = ''
-  try {
-    me = (await withKernelClient(opts, (ctx) => {
-      kernelUrl = ctx.url
-      return ctx.client.call(WHOAMI_PATH as never, {} as never)
-    })) as { id?: unknown } | null
-  } catch {
-    // Network/auth failure — surface the original recipe, not a stack.
-    throw selfRefusalError(r)
-  }
-  const id = typeof me?.id === 'string' && me.id.trim().length > 0 ? me.id : undefined
-  if (!id) throw selfRefusalError(r)
-  await setRegistration(selfCtx.identity.name, selfCtx.instanceSlug, {
-    iss: kernelUrl,
-    sub: id,
-    registeredAt: new Date().toISOString(),
+  const me = await withKernelClient(opts, (ctx) => {
+    kernelUrl = ctx.url
+    return ctx.client.as(ctx.credential).auth.whoami()
   })
-  return id
+  return { id: me.id, kernelUrl }
 }
 
-/**
- * Expand `@self` in a single path string for the common command shape
- * (`get`, `ls`, `describe`). Returns the expanded path AND the metadata
- * needed by `withSelfHint` to attach the stale-registration hint to a
- * downstream `NotFoundError`.
- *
- * No-op (returns the input unchanged with `meta: undefined`) when the path
- * contains no `@self` — avoids the I/O of `buildSelfContext`.
- *
- * Throws `SelfRefusalError` when `@self` is present but unresolvable.
- */
+/** Expand @self in path-like commands and return metadata for NotFound hints. */
 export async function expandSelfInPath(
   path: string,
   opts: KernelCommandOpts,