@astrale-os/cli 0.4.0-alpha.13

package/src/lib/prompt.ts

@@ -0,0 +1,136 @@
+import { checkbox, confirm as confirmPrompt, input, select } from '@inquirer/prompts'
+import chalk from 'chalk'
+import { createInterface } from 'node:readline/promises'
+
+// All interactive prompts go through `@inquirer/prompts` so a single library
+// owns stdin (raw mode, keypress handling, cleanup). Hand-rolling some prompts
+// with `node:readline` alongside inquirer used to fight over the TTY — the
+// raw↔line-mode handoff swallowed the first keystroke, so a step right after an
+// inquirer prompt needed a double Enter. One owner, no handoff, no lost keys.
+//
+// Every helper guards on `process.stdin.isTTY` BEFORE touching inquirer (which
+// requires a TTY): a piped / CI / no-TTY (LLM) run returns the default
+// immediately and renders nothing, so callers never hang on a read.
+
+/**
+ * Prompt the user for Y/N confirmation (default No). Returns false in non-TTY
+ * environments (use --yes / a flag to bypass).
+ */
+export async function confirm(message: string): Promise<boolean> {
+  if (!process.stdin.isTTY) return false
+  return confirmPrompt({ message, default: false })
+}
+
+/**
+ * Prompt with a Y default — "Y/n" semantics. Returns true unless the user
+ * explicitly declines; returns true in non-TTY.
+ */
+export async function confirmDefaultYes(message: string): Promise<boolean> {
+  if (!process.stdin.isTTY) return true
+  return confirmPrompt({ message, default: true })
+}
+
+/**
+ * Prompt the user to type a specific string to confirm a dangerous action.
+ * Returns false in non-TTY environments (use a flag to bypass).
+ */
+export async function confirmWithInput(message: string, expected: string): Promise<boolean> {
+  if (!process.stdin.isTTY) return false
+  process.stdout.write(chalk.yellow(`${message}\n`))
+  const answer = await input({ message: `Type "${expected}" to confirm:` })
+  return answer.trim() === expected
+}
+
+/**
+ * Free-text prompt (a styled `@inquirer/prompts` input — shows the default,
+ * supports inline `validate` with live re-ask). Returns the typed value, or the
+ * default on empty input (`undefined` when none) in a non-TTY run.
+ */
+export async function promptText(
+  message: string,
+  opts: { default?: string; validate?: (value: string) => boolean | string } = {},
+): Promise<string | undefined> {
+  if (!process.stdin.isTTY) return opts.default
+  const answer = await input({
+    message,
+    ...(opts.default !== undefined ? { default: opts.default } : {}),
+    ...(opts.validate ? { validate: opts.validate } : {}),
+  })
+  return answer.trim() || opts.default
+}
+
+/**
+ * Single-choice selector (arrow-key `@inquirer/prompts` select). Returns the
+ * chosen value, or `undefined` in a non-TTY environment.
+ */
+export async function promptSelect<T>(
+  message: string,
+  choices: Array<{ name: string; value: T; description?: string }>,
+): Promise<T | undefined> {
+  if (!process.stdin.isTTY) return undefined
+  return select({ message, choices })
+}
+
+/**
+ * Multi-choice selector (a styled `@inquirer/prompts` checkbox — space toggles,
+ * enter confirms). Pre-check options with `checked: true`. Returns the chosen
+ * values, or `undefined` in a non-TTY environment.
+ */
+export async function promptMultiSelect<T>(
+  message: string,
+  choices: Array<{ name: string; value: T; checked?: boolean; description?: string }>,
+): Promise<T[] | undefined> {
+  if (!process.stdin.isTTY) return undefined
+  return checkbox({ message, choices })
+}
+
+/**
+ * Single-choice selector over labeled values. Returns the chosen value, or
+ * `null` in a non-TTY environment (callers decide how to fail). In a terminal
+ * the user always picks one (Enter selects the highlighted option; Ctrl-C
+ * aborts the command), so `null` only ever signals "no TTY".
+ */
+export async function selectFrom<T>(
+  message: string,
+  choices: Array<{ label: string; value: T }>,
+): Promise<T | null> {
+  if (!process.stdin.isTTY) return null
+  return select({ message, choices: choices.map((c) => ({ name: c.label, value: c.value })) })
+}
+
+/** Prompt a passphrase without echoing. Fails in non-TTY unless env override. */
+export async function readPassphrase(
+  message: string,
+  opts: { minLength?: number } = {},
+): Promise<string> {
+  const env = process.env.ASTRALE_PASSPHRASE
+  if (env) return env
+  if (!process.stdin.isTTY) {
+    throw new Error('Passphrase required but no TTY. Pipe via ASTRALE_PASSPHRASE env var.')
+  }
+  // v1 note: passphrase echoes on interactive terminals. Pipe
+  // ASTRALE_PASSPHRASE=... for scripted flows. Silent stdin with raw
+  // mode is roadmap (requires terminal capabilities handling).
+  process.stdout.write(chalk.yellow(message))
+  const answer = await readLine()
+  process.stdout.write('\n')
+  if (opts.minLength && answer.length < opts.minLength) {
+    throw new Error(`Passphrase too short (min ${opts.minLength} chars)`)
+  }
+  return answer
+}
+
+/**
+ * Read one line from stdin via Node's own line reader (stdlib, zero-dep).
+ * Used only by `readPassphrase` (a single-shot prompt that intentionally echoes
+ * and honors ASTRALE_PASSPHRASE) — every navigational prompt uses inquirer.
+ * Only ever reached behind an `isTTY` gate, so it never blocks a piped run.
+ */
+async function readLine(): Promise<string> {
+  const rl = createInterface({ input: process.stdin, output: process.stdout })
+  try {
+    return (await rl.question('')).trim()
+  } finally {
+    rl.close()
+  }
+}

package/src/lib/provision-instance.ts

@@ -0,0 +1,170 @@
+import chalk from 'chalk'
+
+import type { KernelCommandOpts } from '../kernel'
+import type { AdminTargetCommandOpts } from './admin-target'
+
+import { AuthError } from '../errors'
+import { withAdminKernelClient } from '../kernel/client'
+import { ADMIN_INSTANCE } from './admin-instance'
+import { readIdentities, type IdentityStore } from './identity'
+import { setActive, upsertManagedBookmark } from './instance'
+import { withSpinner } from './log'
+import { isMachine } from './output'
+import { promptSelect } from './prompt'
+import { validateSlug } from './validation'
+
+export type ProvisionOpts = KernelCommandOpts &
+  AdminTargetCommandOpts & {
+    hostId?: string
+    // Global flags (program.ts) that force non-interactive — mirrors `instance use`.
+    ci?: boolean
+    noPrompt?: boolean
+  }
+
+/** The created instance plus the local-bookmark side effects of provisioning. */
+export type ProvisionResult = {
+  /** The raw admin-kernel response — the stable machine surface for `--json`. */
+  created: { url: string; organizationId?: string }
+  slug: string
+  /** Set when an existing bookmark of the same name was repointed to a new kernel. */
+  repointedFrom?: string
+  /** Set when bookmarking/activating the new instance failed (non-fatal). */
+  selectionError?: unknown
+}
+
+/** Provisioning a child instance runs a multi-step saga (1-3 min). */
+const SAGA_TIMEOUT_MS = '240000'
+
+/**
+ * Provision an alpha instance through the admin kernel, then bookmark it and
+ * make it the active target. Extracted from `instance create` so `astrale
+ * setup` provisions through the exact same saga (auth assertion → alphaCreate →
+ * bookmark → set-active), including the interactive multi-host picker.
+ *
+ * Presentation is deliberately minimal here (a spinner + a one-line success);
+ * the caller renders anything richer — `setup` follows this with a hero panel.
+ */
+export async function provisionInstance(
+  slug: string,
+  opts: ProvisionOpts,
+): Promise<ProvisionResult> {
+  validateSlug(slug)
+  await assertAlphaCreateAuth(opts)
+  // The created instance must belong to the LOGGED-IN identity — never to an
+  // identity pinned on the admin bookmark (that mismatch silently made a fresh
+  // user's instance unusable). `--as` still wins.
+  if (!opts.as) opts = { ...opts, as: (await readIdentities()).default }
+
+  const machine = isMachine(opts)
+  const interactive = !!process.stdin.isTTY && !(opts.ci || opts.noPrompt || process.env.CI)
+
+  let repointedFrom: string | undefined
+  let selectionError: unknown = null
+  // The global 30s default doesn't just fail the CLIENT: the disconnect kills
+  // the worker's request mid-saga and leaves TORN state (slug taken, routing
+  // live, no instance node — unrecoverable by retry). Default to a saga-sized
+  // timeout; an explicit --timeout still wins.
+  const createOpts = { ...opts, timeout: opts.timeout ?? SAGA_TIMEOUT_MS }
+
+  const runProvision = (hostId: string | undefined) =>
+    withSpinner(
+      `Provisioning instance ${slug}`,
+      !machine,
+      async () => {
+        const created = await withAdminKernelClient(
+          createOpts,
+          async (ctx) =>
+            (await ctx.client.call(`${ADMIN_INSTANCE}/alphaCreate`, {
+              slug,
+              ...(hostId ? { host_id: hostId } : {}),
+            })) as { url: string; organizationId?: string },
+        )
+        try {
+          // Org id from the create response — authoritative for token scoping
+          // (the router's /auth/org is eventually consistent).
+          const bookmarked = await upsertManagedBookmark(
+            slug,
+            slug,
+            created.url,
+            created.organizationId,
+          )
+          repointedFrom = bookmarked.repointedFrom
+          await setActive(slug)
+        } catch (e) {
+          selectionError = e
+        }
+        return created
+      },
+      {
+        success: (created) =>
+          `Instance provisioned: ${slug} ${chalk.dim(`(${created.url})${selectionError ? '' : ' · active'}`)}`,
+      },
+    )
+
+  // Host placement is chosen SERVER-side (the caller's ready + USE-granted
+  // hosts). We recover ONLY from its multi-host ambiguity: pop a picker and
+  // retry with the chosen host_id — the ambiguity error throws before any
+  // provisioning side effect, so the retry is clean. No host / permission /
+  // capacity / a non-interactive run all reject through to the caller's `fatal`,
+  // surfacing the server's own message plus the listed ids. An explicit
+  // `--host-id` skips all of this.
+  const created = await runProvision(opts.hostId).catch(async (e: unknown) => {
+    const hostIds = !opts.hostId && interactive ? parseEligibleHostIds(e) : null
+    if (!hostIds) throw e
+    const chosen = await promptSelect(
+      `${hostIds.length} hosts available — pick one to provision on`,
+      hostIds.map((hid) => ({ name: hid, value: hid })),
+    )
+    if (!chosen) throw e
+    return runProvision(chosen)
+  })
+
+  // Warnings go to stderr so machine-readable stdout stays clean.
+  const warn = (msg: string) => console.error(chalk.yellow('⚠'), msg)
+  if (selectionError) {
+    const message =
+      selectionError instanceof Error ? selectionError.message : String(selectionError)
+    warn(`Could not select the new instance: ${message}`)
+  } else if (repointedFrom) {
+    warn(`Bookmark "${slug}" repointed: ${repointedFrom} → ${created.url}`)
+  }
+
+  return { created, slug, repointedFrom, ...(selectionError ? { selectionError } : {}) }
+}
+
+/**
+ * Recover the eligible host ids from alphaCreate's multi-host error
+ * ("N ready hosts are assigned (id1, id2). Specify host_id…") — only when
+ * there's a real choice (>1). Returns null for any other error (no host,
+ * permission, capacity). Deliberately coupled to that message wording (Option
+ * B: no admin-side change); if it ever drifts we simply stop offering the
+ * picker and the raw error is shown instead — no worse than before.
+ */
+export function parseEligibleHostIds(error: unknown): string[] | null {
+  const text = error instanceof Error ? error.message : String(error)
+  const match = /ready hosts are assigned \(([^)]+)\)/.exec(text)
+  if (!match) return null
+  const ids = match[1]!
+    .split(',')
+    .map((s) => s.trim())
+    .filter(Boolean)
+  return ids.length > 1 ? ids : null
+}
+
+async function assertAlphaCreateAuth(opts: Pick<ProvisionOpts, 'as' | 'creds'>): Promise<void> {
+  if (opts.creds) return
+  assertAlphaCreateIdentity(await readIdentities(), opts)
+}
+
+export function assertAlphaCreateIdentity(
+  store: IdentityStore,
+  opts: Pick<ProvisionOpts, 'as'> = {},
+): void {
+  const name = opts.as ?? store.default
+  const identity = store.identities[name]
+  if (identity && identity.source === 'idp') return
+  throw new AuthError(
+    'WorkOS login required for `astrale instance create`',
+    'Run: astrale auth login',
+  )
+}

package/src/lib/sdk-deps.ts

@@ -0,0 +1,104 @@
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { run } from './proc'
+
+/**
+ * `astrale update`, Axis C — keep a domain project's first-party `@astrale-os/*`
+ * dependencies current. We DELEGATE to pnpm rather than reimplement a package
+ * manager: `pnpm outdated` to detect, `pnpm update --latest` to apply. pnpm owns
+ * the hard, easy-to-get-wrong parts — registry/`.npmrc`/auth resolution, the
+ * `minimumReleaseAge` supply-chain gate, workspace members, semver, and the
+ * lockfile — so this stays a thin, robust shim (mirrors how the CLI delegates
+ * skills to `npx skills`). Every call is best-effort: pnpm missing or any error
+ * means "nothing to do", never a failed update.
+ */
+
+/** The dependency pattern pnpm matches both subcommands against. */
+const ASTRALE_DEP_PATTERN = '@astrale-os/*'
+
+export type SdkOutdated = { pkg: string; current: string; latest: string }
+
+/** Is the CLI running at the root of a scaffolded domain project? */
+export function inDomainProject(cwd: string = process.cwd()): boolean {
+  return existsSync(join(cwd, 'astrale.config.ts'))
+}
+
+/**
+ * A non-pnpm lockfile means another package manager owns this project; we won't
+ * run pnpm against it (that would write a stray `pnpm-lock.yaml`). Returns the
+ * foreign PM name, or null when it's pnpm / fresh (Astrale projects are pnpm-first).
+ */
+export function foreignPackageManager(cwd: string = process.cwd()): 'npm' | 'yarn' | 'bun' | null {
+  if (existsSync(join(cwd, 'pnpm-lock.yaml'))) return null
+  if (existsSync(join(cwd, 'package-lock.json'))) return 'npm'
+  if (existsSync(join(cwd, 'yarn.lock'))) return 'yarn'
+  if (existsSync(join(cwd, 'bun.lockb')) || existsSync(join(cwd, 'bun.lock'))) return 'bun'
+  return null
+}
+
+type PnpmOutdatedEntry = { current?: string; wanted?: string; latest?: string }
+
+/**
+ * Parse `pnpm outdated --format json` into the deps that actually have a newer
+ * release. pnpm only lists outdated packages and never proposes a downgrade, so
+ * we just drop entries with no `latest` or where `latest` equals the current
+ * version (it lists `wanted` when nothing is installed yet — use that as the
+ * "current" we display). Pure (no I/O) so it's unit-testable without spawning.
+ */
+export function parseSdkOutdated(stdout: string): SdkOutdated[] {
+  let parsed: Record<string, PnpmOutdatedEntry>
+  try {
+    parsed = JSON.parse(stdout || '{}') as Record<string, PnpmOutdatedEntry>
+  } catch {
+    return []
+  }
+  const out: SdkOutdated[] = []
+  for (const [pkg, entry] of Object.entries(parsed)) {
+    const current = entry.current ?? entry.wanted
+    if (entry.latest && current && entry.latest !== current) {
+      out.push({ pkg, current, latest: entry.latest })
+    }
+  }
+  return out
+}
+
+/**
+ * Ask pnpm which `@astrale-os/*` deps have a newer release. `pnpm outdated`
+ * exits 1 when outdated deps exist — that's not an error, so we parse stdout
+ * regardless of exit code. Returns [] when none, pnpm is absent, or anything fails.
+ */
+export async function findSdkOutdated(cwd: string = process.cwd()): Promise<SdkOutdated[]> {
+  try {
+    const { stdout } = await run('pnpm', ['outdated', '--format', 'json', ASTRALE_DEP_PATTERN], {
+      cwd,
+    })
+    return parseSdkOutdated(stdout)
+  } catch {
+    return [] // pnpm not on PATH, etc.
+  }
+}
+
+/**
+ * Apply via `pnpm update --latest --lockfile-only` — pnpm rewrites package.json
+ * (preserving exact pins, the scaffold style) and the lockfile, honoring the
+ * registry + supply-chain age policy. `--lockfile-only` is deliberate: it updates
+ * the manifest + lockfile WITHOUT running install/build scripts, so an `astrale
+ * update` never executes a dependency's postinstall (pnpm would otherwise exit
+ * non-zero on `ERR_PNPM_IGNORED_BUILDS`) or churns node_modules — the user runs
+ * `pnpm install` to materialize, honoring their own build approvals. Surfaces
+ * pnpm's output only on failure. Returns true on success.
+ */
+export async function applySdkUpdate(cwd: string = process.cwd()): Promise<boolean> {
+  try {
+    const { code, stdout, stderr } = await run(
+      'pnpm',
+      ['update', '--latest', '--lockfile-only', ASTRALE_DEP_PATTERN],
+      { cwd },
+    )
+    if (code !== 0) process.stderr.write(stdout + stderr)
+    return code === 0
+  } catch {
+    return false
+  }
+}

package/src/lib/self.ts

@@ -0,0 +1,166 @@
+/**
+ * `@self` shorthand: expands to the nodeId behind the JWT `sub` claim that
+ * the current CLI invocation would ship. Pure helpers — no I/O.
+ *
+ * Kernel-side, `Identity::registerIdentity` writes `sub = String(self.id)`
+ * (kernel/runtime/syscalls/identity/index.ts), so for any properly-registered
+ * identity the JWT `sub` IS the calling node's id on the target kernel.
+ * Delegation tokens follow the same shape (outer-envelope `sub` = identityId).
+ *
+ * The expansion is fail-loud: when no `sub` is resolvable, return a typed
+ * refusal carrying the exact next-step command. Never silently fall back to
+ * a label-ish `identity.subject` like "manager" or "alice".
+ */
+import { decodeJwt } from 'jose'
+
+import type { Identity } from './identity'
+
+/** Inputs to `resolveSelfNodeId`. All local — no kernel round-trip. */
+export type SelfResolverContext = {
+  /** Identity that will sign this call (default identity or the one from `--as`). */
+  identity?: Identity & { name: string }
+  /** Resolved instance slug, if any (absent when `--url` is used without `-i`). */
+  instanceSlug?: string
+  /** Raw `--creds` JWT, if the user provided one. */
+  credsJwt?: string
+  /** True when `auth.ts` will sign as the instance itself (per-instance keypair, not user identity). */
+  instanceSigned: boolean
+  /** `sub` decoded from a cached IdP token for source=idp identities, when available. */
+  idpSubject?: string
+}
+
+export type SelfRefusal =
+  | { reason: 'manager' }
+  | { reason: 'no-registration'; identityName: string; instanceSlug: string }
+  | { reason: 'instance-signed'; instanceSlug: string }
+  | { reason: 'url-no-slug' }
+  | { reason: 'creds-no-sub' }
+  | { reason: 'idp-no-sub'; identityName: string }
+
+export type SelfResolution = { id: string } | SelfRefusal
+
+// Anchors:
+//   left:  start-of-string OR right after `=` (param-value head)
+//   right: end-of-string OR `::` (instance method) OR `/` (path navigation)
+// The `/` lookahead is required so `@self/functions` etc. expand — the
+// `astrale ls @self/functions` form is documented in SKILL.md and the
+// sandbox prefix. Without it the regex silently no-ops on those inputs.
+const SELF_RE = /(?:^|(?<=[=]))@self(?=$|::|\/)/g
+
+/** Resolve `@self` → `{ id: <nodeId> }`, or a typed refusal. */
+export function resolveSelfNodeId(ctx: SelfResolverContext): SelfResolution {
+  // 1. `--creds <jwt>` — bypasses every identity lookup. Read the sub claim.
+  if (ctx.credsJwt) {
+    try {
+      const sub = decodeJwt(ctx.credsJwt).sub
+      // `.trim().length` rejects whitespace-only subs (`'   '`, `'\t'`).
+      // A hand-crafted JWT with `sub: '   '` previously round-tripped into
+      // `@   ::method`, producing a malformed kernel call instead of the
+      // typed `creds-no-sub` refusal.
+      if (typeof sub === 'string' && sub.trim().length > 0) return { id: sub }
+    } catch {
+      // fall through to creds-no-sub
+    }
+    return { reason: 'creds-no-sub' }
+  }
+  // 2. Instance-signed: no user identity context — `@self` is undefined.
+  if (ctx.instanceSigned) {
+    return { reason: 'instance-signed', instanceSlug: ctx.instanceSlug ?? 'unknown' }
+  }
+  // 3. IdP-backed identities: the provider token's `sub` is the IdP USER id
+  // (e.g. `user_01K…`), NEVER a graph node id — expanding to it always
+  // produced NOT_FOUND. Use a cached registration when one exists (a future
+  // `whoami`-backed cache can populate it); otherwise refuse with the recipe.
+  if ((ctx.identity?.source ?? 'key') === 'idp') {
+    const cached = ctx.instanceSlug
+      ? ctx.identity?.registrations?.[ctx.instanceSlug]?.sub
+      : undefined
+    if (cached) return { id: cached }
+    return { reason: 'idp-no-sub', identityName: ctx.identity?.name ?? '(unknown)' }
+  }
+  // 4. `--url` without `-i`: no slug to look up registration against.
+  if (!ctx.instanceSlug) return { reason: 'url-no-slug' }
+  // 5. Bootstrap `manager` identity has no graph node by construction.
+  if (
+    ctx.identity?.name === 'manager' &&
+    (!ctx.identity.registrations || Object.keys(ctx.identity.registrations).length === 0)
+  ) {
+    return { reason: 'manager' }
+  }
+  // 6. Default path: read the registration entry for the resolved slug.
+  // `sub` IS the node id by construction for entries written by
+  // `registerIdentity` (kernel/runtime/syscalls/identity/index.ts:207).
+  const id = ctx.identity?.registrations?.[ctx.instanceSlug]?.sub
+  if (!id) {
+    return {
+      reason: 'no-registration',
+      identityName: ctx.identity?.name ?? '(unknown)',
+      instanceSlug: ctx.instanceSlug,
+    }
+  }
+  return { id }
+}
+
+/** Cheap pre-check before invoking the resolver — skip when no `@self` appears. */
+export function containsSelfRef(input: string): boolean {
+  SELF_RE.lastIndex = 0
+  return SELF_RE.test(input)
+}
+
+/**
+ * Replace every `@self` token (path head or `=@self`) with `@<selfId>`.
+ *
+ * Uses the function-form replacement so a `selfId` containing `$&`, `$$`,
+ * `$<n>`, etc. is not interpreted as a `String.replace` substitution
+ * pattern. A delegation-token `sub` claim or future opaque kernel id can
+ * legitimately carry `$`.
+ */
+export function expandSelfReferences(input: string, selfId: string): string {
+  const replacement = `@${selfId}`
+  return input.replace(SELF_RE, () => replacement)
+}
+
+/** Build a human-facing error carrying the typed refusal as metadata. */
+export function selfRefusalError(r: SelfRefusal): Error {
+  const e = new Error(refusalMessage(r))
+  e.name = 'SelfRefusalError'
+  ;(e as Error & { selfRefusal: SelfRefusal }).selfRefusal = r
+  return e
+}
+
+function refusalMessage(r: SelfRefusal): string {
+  switch (r.reason) {
+    case 'manager':
+      return [
+        "`@self` not available: you're signed in as the bootstrap `manager` identity, which has no graph node.",
+        'Run `astrale identity create <name>` then `astrale identity register <name>` to enable `@self`.',
+      ].join('\n  ')
+    case 'no-registration':
+      return [
+        `\`@self\` not available: identity "${r.identityName}" has no registration on instance "${r.instanceSlug}".`,
+        `Run \`astrale identity register ${r.identityName} -i ${r.instanceSlug}\`.`,
+      ].join('\n  ')
+    case 'instance-signed':
+      return [
+        `\`@self\` not available: this call signs as instance "${r.instanceSlug}" itself, not a user identity.`,
+        'Use `--as <name>` to sign as a registered identity, or pass a literal `@<nodeId>`.',
+      ].join('\n  ')
+    case 'url-no-slug':
+      return [
+        '`@self` needs an instance slug to look up the registration.',
+        'Add `-i <slug>`, or if this URL maps to a bookmark, use that slug instead of `--url`.',
+      ].join('\n  ')
+    case 'creds-no-sub':
+      return [
+        '`@self` not available: the `--creds` JWT has no usable `sub` claim.',
+        'Pass a literal `@<nodeId>` instead.',
+      ].join('\n  ')
+    case 'idp-no-sub':
+      return [
+        `\`@self\` could not be resolved for IdP identity "${r.identityName}": no cached registration, and the automatic whoami lookup did not return a node id (offline, auth failure, or unprovisioned identity).`,
+        'Get your node id manually, then use it directly:',
+        '  astrale call "/:kernel.astrale.ai:interface.Identity:whoami" --json   # → { id: <nodeId> }',
+        'and address yourself as `@<nodeId>`.',
+      ].join('\n  ')
+  }
+}