@astrale-os/cli 0.8.0-alpha.0 → 0.8.1-alpha.2

package/src/lib/instance-target.ts

@@ -1,4 +1,4 @@
-import type { InstanceInfo } from './admin-instance'
+import type { InstanceInfo } from '../admin/instance/model'
 import type { AstraleConfig } from './config'
 
 import { AstraleError } from '../errors'
@@ -21,13 +21,14 @@ export type InstanceTargetRequest =
   | { source: 'active' }
   | { source: 'name'; name: string }
   | { source: 'admin' }
-  | { source: 'url'; url: string; name?: string; issuer?: string }
+  | { source: 'url'; url: string; name?: string; kernelIssuer?: string }
 
 export type ResolvedInstanceTarget = {
   name?: string
   source: 'bookmark' | 'managed' | 'admin' | 'url'
   url: string
-  issuer: string
+  kernelIssuer: string
+  domainIssuer?: string
   defaultIdentity?: string
   caFile?: string
 }
@@ -59,7 +60,7 @@ export async function resolveInstanceTarget(
         name: request.name,
         source: 'url',
         url: request.url,
-        issuer: request.issuer ?? request.url,
+        kernelIssuer: request.kernelIssuer ?? request.url,
       }
   }
 }
@@ -102,7 +103,7 @@ async function resolveNamedInstanceTarget(
     name: managed.slug,
     source: 'managed',
     url,
-    issuer: url,
+    kernelIssuer: url,
   }
 }
 
@@ -119,7 +120,8 @@ async function resolveBookmarkedInstanceTarget(
       name: key,
       source: 'bookmark',
       url,
-      issuer: entry.issuer ? normalizeInstanceKernelUrl(entry.issuer) : url,
+      kernelIssuer: entry.issuer ? normalizeInstanceKernelUrl(entry.issuer) : url,
+      domainIssuer: entry.domainIssuer,
       defaultIdentity: entry.defaultIdentity,
       caFile: entry.caFile,
     }
@@ -130,7 +132,8 @@ async function resolveBookmarkedInstanceTarget(
     name: resolved.name,
     source: 'bookmark',
     url: resolved.url,
-    issuer: resolved.issuer ?? resolved.url,
+    kernelIssuer: resolved.issuer ?? resolved.url,
+    domainIssuer: resolved.domainIssuer,
     defaultIdentity: resolved.defaultIdentity,
     caFile: resolved.caFile,
   }
@@ -163,7 +166,8 @@ export function adminTargetToInstance(target: ResolvedAdminTarget): ResolvedInst
     name: target.registrationSlug,
     source: 'admin',
     url: target.url,
-    issuer: target.issuer,
+    kernelIssuer: target.kernelIssuer,
+    ...(target.domainIssuer === undefined ? {} : { domainIssuer: target.domainIssuer }),
     defaultIdentity: target.defaultIdentity,
     ...(target.caFile ? { caFile: target.caFile } : {}),
   }

package/src/lib/instance.ts

@@ -5,8 +5,8 @@ import { z } from 'zod'
 import type { AstraleConfig } from './config'
 
 import { AstraleError, IdentifierCollisionError, ReservedSlugError } from '../errors'
+import { ExchangeCredentialCache, INSTANCES_PATH } from '../state/index'
 import { log } from './log'
-import { INSTANCES_PATH } from './paths'
 import {
   RESERVED_SLUGS,
   RegistryModeSchema,
@@ -21,6 +21,7 @@ export type InstanceKind = z.infer<typeof InstanceKindSchema>
 export const InstanceEntrySchema = z.object({
   url: z.string().optional(),
   issuer: z.string().optional(),
+  domainIssuer: z.string().optional(),
   createdAt: z.string().optional(),
   slug: z.string().optional(),
   name: z.string().optional(),
@@ -48,6 +49,7 @@ export type AddInstanceOpts = {
   kind?: InstanceKind
   mode?: RegistryMode
   issuer?: string
+  domainIssuer?: string
   defaultIdentity?: string
   caFile?: string
   organizationId?: string
@@ -58,6 +60,7 @@ export type ResolvedInstance = {
   kind: InstanceKind | 'managed'
   url: string
   issuer?: string
+  domainIssuer?: string
   createdAt?: string
   defaultIdentity?: string
   caFile?: string
@@ -88,6 +91,7 @@ export function sanitizeStore(store: InstanceStore): { store: InstanceStore; cha
       ...entry,
       url: normalizedUrl,
       issuer: normalizedIssuer,
+      domainIssuer: entry.domainIssuer,
       kind: 'bookmark',
     }
     // VALUE comparison only. The old `next !== entry` (object identity) was
@@ -113,6 +117,15 @@ export function sanitizeStore(store: InstanceStore): { store: InstanceStore; cha
 
 let instancesMemo: InstanceStore | null = null
 
+/**
+ * Invalidate the one-process bookmark snapshot. Long-lived compatibility
+ * consumers call this before a read so CLI writes made by another process are
+ * observable; one-shot commands normally never need it.
+ */
+export function resetInstancesMemo(): void {
+  instancesMemo = null
+}
+
 export async function readInstances(
   _config?: AstraleConfig,
   opts: { persist?: boolean } = {},
@@ -204,6 +217,7 @@ export async function addInstance(key: string, opts: AddInstanceOpts = {}): Prom
     ...opts,
     url: normalizedUrl,
     issuer: opts.issuer ? normalizeInstanceKernelUrl(opts.issuer) : opts.issuer,
+    domainIssuer: opts.domainIssuer ? normalizeIssuerUrl(opts.domainIssuer) : opts.domainIssuer,
     kind: 'bookmark',
     createdAt: new Date().toISOString(),
   }
@@ -228,11 +242,15 @@ export async function upsertInstance(
 
   const existing = store.instances[key]
   const normalizedIssuer = opts.issuer ? normalizeInstanceKernelUrl(opts.issuer) : undefined
+  const normalizedDomainIssuer = opts.domainIssuer
+    ? normalizeIssuerUrl(opts.domainIssuer)
+    : undefined
   const entry: InstanceEntry = {
     ...existing,
     ...definedEntry(opts),
     url: normalizedUrl,
     ...(normalizedIssuer ? { issuer: normalizedIssuer } : {}),
+    ...(normalizedDomainIssuer ? { domainIssuer: normalizedDomainIssuer } : {}),
     kind: 'bookmark',
     createdAt: existing?.createdAt ?? new Date().toISOString(),
   }
@@ -273,10 +291,12 @@ export async function upsertManagedBookmark(
 
 export async function removeInstance(key: string): Promise<void> {
   const store = await readInstances()
-  if (!store.instances[key]) throw new Error(`Instance "${key}" not found`)
+  const removed = store.instances[key]
+  if (!removed) throw new Error(`Instance "${key}" not found`)
   delete store.instances[key]
   if (store.active === key) store.active = Object.keys(store.instances)[0] ?? ''
   await writeInstances(store)
+  await new ExchangeCredentialCache().deleteKernel(removed.issuer ?? removed.url!)
 }
 
 export async function setActive(identifier: string): Promise<string> {
@@ -328,6 +348,7 @@ export async function resolveInstance(
     kind: 'bookmark',
     url: normalizeInstanceKernelUrl(entry.url),
     issuer: entry.issuer ? normalizeInstanceKernelUrl(entry.issuer) : entry.issuer,
+    domainIssuer: entry.domainIssuer,
     createdAt: entry.createdAt,
     defaultIdentity: entry.defaultIdentity,
     caFile: entry.caFile,
@@ -380,6 +401,17 @@ export function normalizeInstanceKernelUrl(url: string): string {
   return parsed.toString().replace(/\/$/, '')
 }
 
+export function normalizeIssuerUrl(url: string): string {
+  try {
+    const parsed = new URL(url)
+    if (parsed.username || parsed.password || parsed.search || parsed.hash) return url
+    parsed.pathname = parsed.pathname.replace(/\/+$/u, '') || '/'
+    return parsed.toString().replace(/\/$/u, '')
+  } catch {
+    return url
+  }
+}
+
 function isRegionRoutedInstanceRoot(url: URL): boolean {
   if (url.pathname !== '' && url.pathname !== '/') return false
   if (url.search || url.hash) return false

package/src/lib/local-status.ts

@@ -2,9 +2,9 @@ import { decodeJwt } from 'jose'
 
 import type { AstraleConfig } from './config'
 
+import { readIdentities, type IdentityStore } from '../identity/index'
 import { resolveAdminTargetFromStore } from './admin-target'
 import { DEFAULT_CONFIG, readConfig } from './config'
-import { readIdentities, type IdentityStore } from './identity'
 import { isSessionExpired, readIdpSession, type IdpSession } from './idp'
 import { readInstances, type InstanceStore } from './instance'
 
@@ -123,7 +123,7 @@ function buildAdminStatus(config: AstraleConfig, instances: InstanceStore): Loca
     return {
       name: target.name,
       url: target.url,
-      issuer: target.issuer,
+      issuer: target.kernelIssuer,
       source: target.source,
       configured: target.configured,
     }

package/src/lib/log.ts

@@ -8,7 +8,9 @@ import { isMachine, type RawOutputOpts } from './output'
 export const log = {
   info: (msg: string) => console.log(chalk.blue('ℹ'), msg),
   success: (msg: string) => console.log(chalk.green('✔'), msg),
-  warn: (msg: string) => console.log(chalk.yellow('⚠'), msg),
+  // Diagnostics never share stdout with command results. In particular,
+  // --json/--raw consumers must receive exactly one parseable value there.
+  warn: (msg: string) => console.error(chalk.yellow('⚠'), msg),
   error: (msg: string) => console.error(chalk.red('✖'), msg),
   step: (msg: string) => console.log(chalk.cyan('→'), msg),
   dim: (msg: string) => console.log(chalk.dim(msg)),

package/src/lib/login-flow.ts

@@ -1,4 +1,4 @@
-import { upsertIdpIdentity } from './identity'
+import { upsertIdpIdentity } from '../identity/registry'
 import {
   decodeTokenClaims,
   exchangeAuthorizationCode,
@@ -42,6 +42,19 @@ export type LoginFlowOpts = {
   codeVerifier?: string
   /** Switch the default identity to the one we just logged in (default true). */
   use?: boolean
+  /**
+   * Optional device-flow presentation boundary. When supplied, the caller
+   * receives the verification coordinates instead of terminal log output.
+   */
+  onVerification?: (event: DeviceVerification) => void
+}
+
+export type DeviceVerification = {
+  verificationUri: string
+  verificationUriComplete?: string
+  userCode?: string
+  expiresIn?: number
+  message?: string
 }
 
 export type LoginResult = {
@@ -148,10 +161,24 @@ async function obtainToken(
     scope,
     audience: opts.audience,
   })
-  if (device.verification_uri_complete) log.info(`Open: ${device.verification_uri_complete}`)
-  else if (device.verification_uri) log.info(`Open: ${device.verification_uri}`)
-  if (device.user_code) log.info(`Code: ${device.user_code}`)
-  if (device.message) log.dim(`  ${device.message}`)
+  const verificationUri = device.verification_uri ?? device.verification_uri_complete
+  if (!verificationUri) {
+    throw new Error('IdP device authorization response did not include a verification URL')
+  }
+  const verification: DeviceVerification = {
+    verificationUri,
+    verificationUriComplete: device.verification_uri_complete,
+    userCode: device.user_code,
+    expiresIn: device.expires_in,
+    message: device.message,
+  }
+  if (opts.onVerification) opts.onVerification(verification)
+  else {
+    if (device.verification_uri_complete) log.info(`Open: ${device.verification_uri_complete}`)
+    else if (device.verification_uri) log.info(`Open: ${device.verification_uri}`)
+    if (device.user_code) log.info(`Code: ${device.user_code}`)
+    if (device.message) log.dim(`  ${device.message}`)
+  }
 
   return pollDeviceToken({
     idp,

package/src/lib/meta.ts

@@ -12,6 +12,8 @@
 
 import { IssuerUnreachableError } from '../errors'
 
+type FetchLike = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>
+
 export type DiscoveryDocument = {
   /** OIDC issuer URL. */
   issuer: string
@@ -22,7 +24,7 @@ export type DiscoveryDocument = {
 export async function fetchDiscovery(
   url: string,
   timeoutMs = 5_000,
-  fetchImpl: typeof fetch = globalThis.fetch,
+  fetchImpl: FetchLike = globalThis.fetch,
 ): Promise<DiscoveryDocument> {
   const discoveryUrl = url.replace(/\/+$/, '') + '/.well-known/openid-configuration'
   try {
@@ -41,7 +43,7 @@ export async function fetchDiscovery(
 export async function fetchJwks(
   jwksUri: string,
   timeoutMs = 5_000,
-  fetchImpl: typeof fetch = globalThis.fetch,
+  fetchImpl: FetchLike = globalThis.fetch,
 ): Promise<{ keys: Array<{ kid?: string }> }> {
   try {
     const r = await fetchImpl(jwksUri, { signal: AbortSignal.timeout(timeoutMs) })
@@ -67,20 +69,22 @@ export async function fetchOrgHint(url: string, timeoutMs = 5_000): Promise<stri
   }
 }
 
-/**
- * Verify the issuer at `url` publishes OIDC discovery and a non-empty JWKS.
- * `issuerOverride` forces a specific expected issuer when discovery URL and
- * declared issuer differ.
- */
+/** Verify the pinned issuer publishes self-consistent OIDC discovery and a non-empty JWKS. */
 export async function checkIssuerReachability(
   url: string,
   issuerOverride?: string,
-  fetchImpl?: typeof fetch,
+  fetchImpl?: FetchLike,
 ): Promise<{ issuer: string; keys: Array<{ kid?: string }> }> {
-  const discovery = await fetchDiscovery(url, 5_000, fetchImpl)
-  const issuer = issuerOverride ?? discovery.issuer
+  const discoveryBase = issuerOverride ?? url
+  const discovery = await fetchDiscovery(discoveryBase, 5_000, fetchImpl)
+  if (issuerOverride !== undefined && discovery.issuer !== issuerOverride) {
+    throw new IssuerUnreachableError(
+      `${discoveryBase.replace(/\/+$/, '')}/.well-known/openid-configuration`,
+      `discovery declared issuer "${discovery.issuer}" instead of "${issuerOverride}"`,
+    )
+  }
   const jwks = await fetchJwks(discovery.jwksUri, 5_000, fetchImpl)
   if (jwks.keys.length === 0)
     throw new IssuerUnreachableError(discovery.jwksUri, 'no keys published')
-  return { issuer, keys: jwks.keys }
+  return { issuer: discovery.issuer, keys: jwks.keys }
 }

package/src/lib/provision-instance.ts

@@ -1,12 +1,11 @@
 import chalk from 'chalk'
 
-import type { KernelCommandOpts } from '../kernel'
+import type { KernelCommandOpts } from '../connection'
 import type { AdminTargetCommandOpts } from './admin-target'
 
 import { AuthError } from '../errors'
-import { withAdminKernelClient } from '../kernel/client'
-import { adminInstanceMethod } from './admin-instance'
-import { readIdentities, type IdentityStore } from './identity'
+import { readIdentities, type IdentityStore } from '../identity/index'
+import { createOwnedInstance } from './admin-instance'
 import { setActive, upsertManagedBookmark } from './instance'
 import { withSpinner } from './log'
 import { isMachine } from './output'
@@ -71,14 +70,7 @@ export async function provisionInstance(
       `Provisioning instance ${slug}`,
       !machine,
       async () => {
-        const created = await withAdminKernelClient(
-          createOpts,
-          async (ctx) =>
-            (await ctx.client.call(adminInstanceMethod('alphaCreate'), {
-              slug,
-              ...(hostId ? { host_id: hostId } : {}),
-            })) as { url: string; organizationId?: string },
-        )
+        const created = await createOwnedInstance(createOpts, slug, hostId)
         try {
           // Org id from the create response — authoritative for token scoping
           // (the router's /auth/org is eventually consistent).

package/src/lib/self.ts

@@ -1,164 +1,22 @@
 /**
- * `@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".
+ * Lexical `@self` helpers. Effective-principal resolution is deliberately not
+ * local: connection/self.ts asks the authenticated target Kernel through
+ * Identity.whoami before replacing any reference.
  */
-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. */
+/** Cheap pre-check before invoking authenticated principal resolution. */
 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 `$`.
- */
+/** Replace every admitted `@self` token with one authenticated NodeId. */
 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).`,
-        'The CLI resolves `@self` through the bound auth.whoami() flow; fix auth/registration and rerun, or pass a literal `@<nodeId>`.',
-      ].join('\n  ')
-  }
-}

package/src/lib/update.ts

@@ -5,7 +5,7 @@ import { dirname, join } from 'node:path'
 import { z } from 'zod'
 
 import { AstraleError } from '../errors'
-import { INSTALL_PATH } from './paths'
+import { INSTALL_PATH } from '../state/index'
 import { run } from './proc'
 
 const DEFAULT_REPO = 'astrale-os/cli'

package/src/lib/use-target.ts

@@ -1,4 +1,4 @@
-import type { IdentityStore } from './identity'
+import type { IdentityStore } from '../identity/index'
 import type { InstanceStore } from './instance'
 
 import { resolveInstanceKey } from './instance'

package/src/lib/validation.ts

@@ -1,4 +1,4 @@
-import { isDnsLabel } from '@astrale-os/kernel-core'
+import { isDnsLabel } from '@astrale-os/sdk/domain'
 import { z } from 'zod'
 
 import { ReservedSlugError } from '../errors'
@@ -21,7 +21,7 @@ export function validateName(name: string, entity: string): void {
 }
 
 export function validateSlug(slug: string): void {
-  // Canonical DNS-label rule (`@astrale-os/kernel-core`): a slug becomes a
+  // Canonical DNS-label rule (`@astrale-os/sdk/domain`): a slug becomes a
   // hostname label, so reject anything not DNS-safe (§4.7).
   if (!slug || !isDnsLabel(slug)) {
     throw new Error(

package/src/lib/view/open-intent.ts

@@ -3,8 +3,8 @@ import type { IntentMessage, MountedWindow, ResolvedView, Shell } from '@astrale
 export interface OpenIntentHost {
   current(): MountedWindow | null
   setCurrent(window: MountedWindow): void
-  mount(view: ResolvedView, nodeId: string): Promise<MountedWindow>
-  opened(view: ResolvedView, nodeId: string): void
+  mount(view: ResolvedView): Promise<MountedWindow>
+  opened(view: ResolvedView): void
   failed(error: unknown): void
   reply(message: IntentMessage<'open'>, windowId: string): void
   reject(message: IntentMessage<'open'>, error: unknown): void
@@ -29,10 +29,10 @@ export async function handleOpenIntent(
   try {
     const selected = selectResolvedView(await shell.views.resolve(nodeId), viewId)
     const previous = host.current()
-    const next = await host.mount(selected, nodeId)
+    const next = await host.mount(selected)
 
     host.setCurrent(next)
-    host.opened(selected, nodeId)
+    host.opened(selected)
     // A correlated requester is normally `previous`; answer while its channel
     // still exists, then retire the old mount.
     host.reply(message, next.windowId)
@@ -57,41 +57,11 @@ export function selectResolvedView(
   views: readonly ResolvedView[],
   viewId: string | undefined,
 ): ResolvedView {
-  const selected = viewId ? views.find((view) => view.id === viewId) : views[0]
+  const selected = viewId
+    ? views.find((view) => view.route.key === viewId || `/:${view.route.key}` === viewId)
+    : views[0]
   if (selected) return selected
   throw new Error(
     viewId ? `View ${viewId} does not resolve for this node` : 'No view resolves for this node',
   )
 }
-
-/** Mount a shell view with bounded handshake retries and a plain fallback. */
-export async function mountWithHandshakeFallback<T>(opts: {
-  handshake: 'shell' | 'none'
-  attempts: number
-  mount(handshake: 'shell' | 'none'): Promise<T>
-  cleanupFailedAttempt(): void
-}): Promise<{ mounted: T; handshake: 'shell' | 'none' }> {
-  if (opts.handshake === 'none') {
-    try {
-      return { mounted: await opts.mount('none'), handshake: 'none' }
-    } catch (error) {
-      opts.cleanupFailedAttempt()
-      throw error
-    }
-  }
-  let lastError: unknown
-  for (let attempt = 0; attempt < opts.attempts; attempt++) {
-    try {
-      return { mounted: await opts.mount('shell'), handshake: 'shell' }
-    } catch (error) {
-      lastError = error
-      opts.cleanupFailedAttempt()
-    }
-  }
-  try {
-    return { mounted: await opts.mount('none'), handshake: 'none' }
-  } catch (error) {
-    opts.cleanupFailedAttempt()
-    throw error ?? lastError
-  }
-}

package/src/lib/view/port-allocation.ts

@@ -1,6 +1,6 @@
 import { join } from 'node:path'
 
-import { withFileLock } from '../fs-atomic'
+import { withFileLock } from '../../state/index'
 import { VIEW_DIR } from './session'
 
 const VIEW_PORT_LOCK = join(VIEW_DIR, 'ports.lock')