@astrale-os/cli 0.6.3-alpha.0 → 0.8.0-alpha.0

package/src/kernel/client.ts

@@ -5,7 +5,12 @@ import type { AdminTargetCommandOpts } from '../lib/admin-target'
 import type { KernelCommandOpts } from './types'
 
 import { AstraleError } from '../errors'
-import { adminInstanceMethod, type InstanceInfo } from '../lib/admin-instance'
+import {
+  callOwnedInstances,
+  findOwnedInstance,
+  type InstanceInfo,
+  type OwnedInstanceInfo,
+} from '../lib/admin-instance'
 import { readConfig } from '../lib/config'
 import { resolveInstanceTarget, type ResolvedInstanceTarget } from '../lib/instance-target'
 import { resolveCredential } from './auth'
@@ -37,18 +42,15 @@ export async function resolveKernelTarget(
   // Ad-hoc `--url` — unknown kernel. Stamp the URL itself as audience,
   // no slug for per-instance signing.
   if (opts.url && !opts.instance) {
-    const resolved = await resolveInstanceTarget(
-      { source: 'url', url: opts.url },
-      { config, admin: adminLookupOpts(opts) },
-    )
+    const resolved = await resolveInstanceTarget({ source: 'url', url: opts.url }, { config })
     return resolvedToKernelTarget(resolved)
   }
   const resolved = await resolveInstanceTarget(
     opts.instance ? { source: 'name', name: opts.instance } : { source: 'active' },
     {
       config,
-      admin: adminLookupOpts(opts),
-      managed: (slug) => lookupManagedInstance(slug, opts),
+      admin: {},
+      managed: (slug) => lookupImplicitOwnedInstance(slug, opts),
     },
   )
   return resolvedToKernelTarget(resolved, opts.url)
@@ -68,21 +70,46 @@ export async function withKernelClient<T>(
   return withResolvedKernelClient(opts, config, target, fn)
 }
 
-async function lookupManagedInstance(slug: string, opts: KernelCommandOpts): Promise<InstanceInfo> {
-  return await withAdminKernelClient(
-    adminLookupOpts(opts),
-    async (ctx) =>
-      (await ctx.client.call(adminInstanceMethod('info'), { id: slug })) as InstanceInfo,
-  )
+export async function listOwnedInstances(
+  opts: KernelCommandOpts & AdminTargetCommandOpts,
+): Promise<OwnedInstanceInfo[]> {
+  return await withAdminKernelClient(opts, async (ctx) => callOwnedInstances(ctx.client))
 }
 
-function adminLookupOpts(opts: KernelCommandOpts): KernelCommandOpts & AdminTargetCommandOpts {
-  return {
-    as: opts.as,
-    creds: opts.creds,
-    timeout: opts.timeout,
-    debug: opts.debug,
-  }
+export async function lookupOwnedInstance(
+  slug: string,
+  opts: KernelCommandOpts & AdminTargetCommandOpts,
+): Promise<OwnedInstanceInfo> {
+  const instance = findOwnedInstance(await listOwnedInstances(opts), slug)
+  if (instance) return instance
+  throw new AstraleError('INSTANCE_NOT_FOUND', `No owned instance matches "${slug}".`)
+}
+
+export type ImplicitOwnedInstanceLookupDependencies = {
+  lookupOwned: (
+    slug: string,
+    opts: KernelCommandOpts & AdminTargetCommandOpts,
+  ) => Promise<OwnedInstanceInfo>
+}
+
+/**
+ * Resolve an implicit managed target through the caller's owner inventory.
+ *
+ * Target `--as` / `--creds` belong to the eventual child-kernel call. They
+ * must not authenticate the admin discovery request: leaving them out lets
+ * `withAdminKernelClient` use the admin bookmark's default WorkOS identity.
+ */
+export async function lookupImplicitOwnedInstance(
+  slug: string,
+  targetOpts: KernelCommandOpts,
+  deps: ImplicitOwnedInstanceLookupDependencies = {
+    lookupOwned: lookupOwnedInstance,
+  },
+): Promise<InstanceInfo> {
+  return await deps.lookupOwned(slug, {
+    timeout: targetOpts.timeout,
+    debug: targetOpts.debug,
+  })
 }
 
 function resolvedToKernelTarget(

package/src/kernel/expand.ts

@@ -1,7 +1,5 @@
-import type { InstanceInfo } from '../lib/admin-instance'
 import type { KernelCommandOpts } from './types'
 
-import { adminInstanceMethod } from '../lib/admin-instance'
 /** CLI bridge for @self resolution and stale-registration error hints. */
 import { readConfig } from '../lib/config'
 import { getDefault, getIdentity, setRegistration } from '../lib/identity'
@@ -17,7 +15,7 @@ import {
   type SelfResolverContext,
   type SelfResolution,
 } from '../lib/self'
-import { withAdminKernelClient, withKernelClient } from './client'
+import { lookupImplicitOwnedInstance, withKernelClient } from './client'
 
 /** Metadata attached to errors so the NotFoundError path can hint at stale `@self` expansions. */
 export type SelfExpansionMeta = {
@@ -41,8 +39,8 @@ export async function buildSelfContext(opts: KernelCommandOpts): Promise<SelfRes
       opts.instance ? { source: 'name', name: opts.instance } : { source: 'active' },
       {
         config,
-        admin: adminLookupOpts(opts),
-        managed: (instanceSlug) => lookupManagedInstance(instanceSlug, opts),
+        admin: {},
+        managed: (instanceSlug) => lookupImplicitOwnedInstance(instanceSlug, opts),
       },
     )
     slug = resolved.name
@@ -83,23 +81,6 @@ export async function buildSelfContext(opts: KernelCommandOpts): Promise<SelfRes
   return { identity, instanceSlug: slug, credsJwt: opts.creds, instanceSigned, idpSubject }
 }
 
-function adminLookupOpts(opts: KernelCommandOpts): KernelCommandOpts {
-  return {
-    as: opts.as,
-    creds: opts.creds,
-    timeout: opts.timeout,
-    debug: opts.debug,
-  }
-}
-
-async function lookupManagedInstance(slug: string, opts: KernelCommandOpts): Promise<InstanceInfo> {
-  return await withAdminKernelClient(
-    adminLookupOpts(opts),
-    async (ctx) =>
-      (await ctx.client.call(adminInstanceMethod('info'), { id: slug })) as InstanceInfo,
-  )
-}
-
 /**
  * Run `fn`; if it throws a `NotFoundError`, stamp expansion metadata onto the
  * error so `formatKernelError` can append the stale-registration hint. The

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

@@ -1,6 +1,6 @@
 import { describe, expect, test } from 'bun:test'
 
-import type { InstanceInfo } from '../admin-instance'
+import type { OwnedInstanceInfo } from '../admin-instance'
 import type { InstanceStore } from '../instance'
 
 import { collectInstanceCandidates, describeInstanceCandidate } from '../instance-candidates'
@@ -13,48 +13,116 @@ const store: InstanceStore = {
   },
 }
 
-const managedDemo: InstanceInfo = {
+const managedDemo: OwnedInstanceInfo = {
   id: 'demo',
   slug: 'demo',
   url: 'https://demo.eu.astrale.ai',
+  state: 'ready',
   region: 'eu',
 }
 
 describe('collectInstanceCandidates', () => {
   test('bookmark and managed at the same URL collapse into one candidate', () => {
     const candidates = collectInstanceCandidates('demo', store, [managedDemo])
-    expect(candidates).toHaveLength(1)
-    expect(candidates[0]).toMatchObject({ source: 'bookmark', key: 'demo' })
+    expect(candidates).toEqual([
+      {
+        source: 'bookmark',
+        key: 'demo',
+        url: 'https://demo.eu.astrale.ai/api',
+        entry: store.instances.demo,
+      },
+    ])
   })
 
   test('bookmark and managed at different URLs are both candidates', () => {
-    const conflicting: InstanceInfo = { ...managedDemo, url: 'https://demo.us.astrale.ai' }
+    const conflicting: OwnedInstanceInfo = {
+      ...managedDemo,
+      url: 'https://demo.us.astrale.ai',
+    }
     const candidates = collectInstanceCandidates('demo', store, [conflicting])
-    expect(candidates).toHaveLength(2)
-    expect(candidates.map((c) => c.source)).toEqual(['bookmark', 'managed'])
+    expect(
+      candidates.map((candidate) => ({
+        source: candidate.source,
+        key: candidate.key,
+        url: candidate.url,
+        id: candidate.source === 'managed' ? candidate.info.id : undefined,
+      })),
+    ).toEqual([
+      {
+        source: 'bookmark',
+        key: 'demo',
+        url: 'https://demo.eu.astrale.ai/api',
+        id: undefined,
+      },
+      {
+        source: 'managed',
+        key: 'demo',
+        url: 'https://demo.us.astrale.ai/api',
+        id: 'demo',
+      },
+    ])
   })
 
   test('multiple managed instances with the same slug are all candidates', () => {
-    const a: InstanceInfo = { id: 'x1', slug: 'twin', url: 'https://twin.eu.astrale.ai' }
-    const b: InstanceInfo = { id: 'x2', slug: 'twin', url: 'https://twin.us.astrale.ai' }
+    const a: OwnedInstanceInfo = {
+      id: 'x1',
+      slug: 'twin',
+      url: 'https://twin.eu.astrale.ai',
+      state: 'ready',
+    }
+    const b: OwnedInstanceInfo = {
+      id: 'x2',
+      slug: 'twin',
+      url: 'https://twin.us.astrale.ai',
+      state: 'ready',
+    }
     const candidates = collectInstanceCandidates('twin', store, [a, b])
-    expect(candidates).toHaveLength(2)
-    expect(candidates.every((c) => c.source === 'managed')).toBe(true)
+    expect(
+      candidates.map((candidate) => ({
+        source: candidate.source,
+        key: candidate.key,
+        id: candidate.source === 'managed' ? candidate.info.id : undefined,
+      })),
+    ).toEqual([
+      { source: 'managed', key: 'twin', id: 'x1' },
+      { source: 'managed', key: 'twin', id: 'x2' },
+    ])
   })
 
   test('managed instances with a different slug are ignored', () => {
-    const unrelated: InstanceInfo = { id: 'z', slug: 'zeta', url: 'https://zeta.eu.astrale.ai' }
-    expect(collectInstanceCandidates('demo', store, [unrelated])).toHaveLength(1)
+    const unrelated: OwnedInstanceInfo = {
+      id: 'z',
+      slug: 'zeta',
+      url: 'https://zeta.eu.astrale.ai',
+      state: 'ready',
+    }
+    expect(
+      collectInstanceCandidates('demo', store, [unrelated]).map((candidate) => ({
+        source: candidate.source,
+        key: candidate.key,
+      })),
+    ).toEqual([{ source: 'bookmark', key: 'demo' }])
   })
 
   test('bookmark resolution honours slug aliases', () => {
     const candidates = collectInstanceCandidates('oth', store, [])
-    expect(candidates).toHaveLength(1)
-    expect(candidates[0]).toMatchObject({ source: 'bookmark', key: 'other' })
+    expect(
+      candidates.map((candidate) => ({
+        source: candidate.source,
+        key: candidate.key,
+        url: candidate.url,
+      })),
+    ).toEqual([
+      {
+        source: 'bookmark',
+        key: 'other',
+        url: 'https://other.example.com/api',
+      },
+    ])
   })
 
   test('unknown name yields no candidates', () => {
-    expect(collectInstanceCandidates('missing', store, [])).toHaveLength(0)
+    expect(collectInstanceCandidates('missing', store, [])).toEqual([])
   })
 })
 
@@ -65,9 +133,16 @@ describe('describeInstanceCandidate', () => {
     expect(describeInstanceCandidate(bookmark!)).toContain('https://demo.eu.astrale.ai/api')
 
     const [managed] = collectInstanceCandidates('twin', store, [
-      { id: 'x', slug: 'twin', url: 'https://twin.eu.astrale.ai', region: 'eu' },
+      {
+        id: 'x',
+        slug: 'twin',
+        url: 'https://twin.eu.astrale.ai',
+        state: 'ready',
+        region: 'eu',
+      },
     ])
-    expect(describeInstanceCandidate(managed!)).toContain('(managed)')
-    expect(describeInstanceCandidate(managed!)).toContain('eu')
+    expect(describeInstanceCandidate(managed!)).toBe(
+      'twin (managed) https://twin.eu.astrale.ai/api — eu',
+    )
   })
 })

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

@@ -98,7 +98,7 @@ describe('resolveInstanceTarget', () => {
     })
   })
 
-  test('managed slug resolves through injected Instance.info lookup', async () => {
+  test('managed slug resolves through the injected managed lookup', async () => {
     await expect(
       resolveInstanceTarget(
         { source: 'name', name: 'bryan' },
@@ -181,6 +181,14 @@ describe('instance target helpers', () => {
 
     expect(isManagedInstanceNotFound(auth)).toBe(false)
   })
+
+  test('recognizes an owner-scoped lookup miss', () => {
+    expect(
+      isManagedInstanceNotFound(
+        new AstraleError('INSTANCE_NOT_FOUND', 'No owned instance matches "missing".'),
+      ),
+    ).toBe(true)
+  })
 })
 
 describe('isManagedInstanceNotFound: kernel InternalKernelError wrap', () => {

package/src/lib/__tests__/view-assets.test.ts

@@ -0,0 +1,114 @@
+import { afterEach, describe, expect, test } from 'bun:test'
+import { mkdtemp, mkdir, readFile, realpath, rm, symlink, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { dirname, join, relative } from 'node:path'
+import { pathToFileURL } from 'node:url'
+
+import { ensureViewerAssets, viewerDistDir } from '../view/assets'
+
+const temporaryDirectories: string[] = []
+
+afterEach(async () => {
+  await Promise.all(
+    temporaryDirectories
+      .splice(0)
+      .map((directory) => rm(directory, { recursive: true, force: true })),
+  )
+})
+
+describe('viewer asset resolution', () => {
+  test('skips partial candidates and prefers complete package-owned assets', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'astrale-view-candidates-'))
+    temporaryDirectories.push(root)
+    const prefix = join(root, '.npm-global')
+    const packageRoot = join(prefix, 'lib', 'node_modules', '@astrale-os', 'cli')
+    const entry = join(prefix, 'bin', 'astrale')
+    const bundle = join(packageRoot, 'dist', 'astrale.js')
+    const published = join(packageRoot, 'viewer', 'dist')
+    const legacy = join(prefix, 'viewer', 'dist')
+
+    await mkdir(dirname(bundle), { recursive: true })
+    await mkdir(published, { recursive: true })
+    await mkdir(legacy, { recursive: true })
+    await writeFile(bundle, '')
+    await writeFile(join(published, 'main.js'), '')
+    await writeFile(join(legacy, 'main.js'), '')
+    await writeFile(join(legacy, 'index.html'), '')
+
+    expect(viewerDistDir(pathToFileURL(bundle).href, entry)).toBe(legacy)
+
+    await writeFile(join(published, 'index.html'), '')
+    expect(viewerDistDir(pathToFileURL(bundle).href, entry)).toBe(published)
+  })
+
+  test('builds missing viewer assets in a clean source checkout', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'astrale-view-source-'))
+    temporaryDirectories.push(root)
+    const module = join(root, 'src', 'lib', 'view', 'assets.ts')
+    const source = join(root, 'viewer')
+    const dist = join(source, 'dist')
+
+    await mkdir(dirname(module), { recursive: true })
+    await mkdir(source, { recursive: true })
+    await writeFile(module, '')
+    await writeFile(join(source, 'main.ts'), 'document.body.textContent = "viewer ready"\n')
+    await writeFile(join(source, 'index.html'), '<!doctype html><body></body>\n')
+
+    expect(await ensureViewerAssets(pathToFileURL(module).href, join(root, 'bin', 'astrale'))).toBe(
+      dist,
+    )
+    expect(await readFile(join(dist, 'index.html'), 'utf8')).toContain('<body>')
+    expect(await readFile(join(dist, 'main.js'), 'utf8')).toContain('viewer ready')
+  })
+
+  test('uses the bundled module location when invoked through a global bin symlink', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'astrale-view-bundle-'))
+    temporaryDirectories.push(root)
+    const prefix = join(root, '.npm-global')
+    const packageRoot = join(prefix, 'lib', 'node_modules', '@astrale-os', 'cli')
+    const entry = join(prefix, 'bin', 'astrale')
+    const sourceEntry = join(root, 'entry.ts')
+    const viewer = join(packageRoot, 'viewer', 'dist')
+    const assetsPath = join(import.meta.dirname, '..', 'view', 'assets.ts')
+    const relativeAssetsPath = relative(
+      await realpath(dirname(sourceEntry)),
+      await realpath(assetsPath),
+    )
+    const assetsModule = relativeAssetsPath.startsWith('.')
+      ? relativeAssetsPath
+      : `./${relativeAssetsPath}`
+
+    await mkdir(join(prefix, 'bin'), { recursive: true })
+    await mkdir(viewer, { recursive: true })
+    await writeFile(join(viewer, 'main.js'), '')
+    await writeFile(join(viewer, 'index.html'), '')
+    await writeFile(
+      sourceEntry,
+      `import { viewerDistDir } from ${JSON.stringify(assetsModule)}\nconsole.log(viewerDistDir())\n`,
+    )
+    const build = await Bun.build({
+      entrypoints: [sourceEntry],
+      outdir: join(packageRoot, 'dist'),
+      target: 'node',
+      format: 'esm',
+    })
+    expect(build.success).toBe(true)
+    await symlink(
+      join('..', 'lib', 'node_modules', '@astrale-os', 'cli', 'dist', 'entry.js'),
+      entry,
+    )
+
+    const node = Bun.which('node')
+    expect(node).not.toBeNull()
+    const process = Bun.spawn([node!, entry], { stdout: 'pipe', stderr: 'pipe' })
+    const [stdout, stderr, exitCode] = await Promise.all([
+      new Response(process.stdout).text(),
+      new Response(process.stderr).text(),
+      process.exited,
+    ])
+
+    expect(exitCode).toBe(0)
+    expect(stderr).toBe('')
+    expect(stdout.trim()).toBe(await realpath(viewer))
+  })
+})

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

@@ -0,0 +1,82 @@
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test'
+import { mkdtemp, rm } from 'node:fs/promises'
+import net from 'node:net'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+import { findFreePort } from '../port'
+import { withViewPortAllocationLock } from '../view/port-allocation'
+
+let tmp: string
+
+beforeEach(async () => {
+  tmp = await mkdtemp(join(tmpdir(), 'astrale-view-port-'))
+})
+
+afterEach(async () => {
+  await rm(tmp, { recursive: true, force: true })
+})
+
+function listen(port: number): Promise<net.Server> {
+  return new Promise((resolve, reject) => {
+    const server = net.createServer()
+    server.once('error', reject)
+    server.listen({ port, host: '127.0.0.1', exclusive: true }, () => resolve(server))
+  })
+}
+
+function close(server: net.Server): Promise<void> {
+  return new Promise((resolve, reject) => {
+    server.close((error) => (error ? reject(error) : resolve()))
+  })
+}
+
+describe('view port allocation', () => {
+  test('never overlaps concurrent allocation critical sections', async () => {
+    const lockPath = join(tmp, 'ports.lock')
+    let active = 0
+    let maxActive = 0
+
+    const contender = () =>
+      withViewPortAllocationLock(async () => {
+        active++
+        maxActive = Math.max(maxActive, active)
+        await Bun.sleep(40)
+        active--
+      }, lockPath)
+
+    await Promise.all([contender(), contender()])
+
+    // Without the view-specific lock both contenders enter before either
+    // delay completes, making this 2 and recreating the probe/bind window.
+    expect(maxActive).toBe(1)
+  })
+
+  test('serializes concurrent probe-then-listen allocations', async () => {
+    const base = await findFreePort(48000, 200)
+    expect(base).not.toBeNull()
+    if (base === null) throw new Error('test port window exhausted')
+    const lockPath = join(tmp, 'ports.lock')
+
+    const allocate = () =>
+      withViewPortAllocationLock(async () => {
+        const port = await findFreePort(base, 4)
+        if (port === null) throw new Error('test port window exhausted')
+
+        // Widen the exact pre-fix race: both callers would finish the advisory
+        // probe before either one binds, then one would fail with EADDRINUSE.
+        await Bun.sleep(40)
+        const server = await listen(port)
+        return { port, server }
+      }, lockPath)
+
+    const allocations = await Promise.all([allocate(), allocate()])
+    try {
+      const ports = allocations.map(({ port }) => port).sort((a, b) => a - b)
+      expect(ports[0]).toBe(base)
+      expect(ports[1]).toBeGreaterThan(base)
+    } finally {
+      await Promise.all(allocations.map(({ server }) => close(server)))
+    }
+  })
+})

package/src/lib/admin-instance.ts

@@ -5,10 +5,14 @@
  */
 export const ADMIN_INSTANCE = '/:admin.astrale.ai:class.Instance'
 
-export function adminInstanceMethod(method: 'alphaCreate' | 'delete' | 'info' | 'list'): string {
+export function adminInstanceMethod(
+  method: 'alphaCreate' | 'delete' | 'info' | 'list' | 'listMine',
+): string {
   return `${ADMIN_INSTANCE}:${method}`
 }
 
+export type InstanceState = 'provisioning' | 'ready' | 'failed'
+
 /** Read shape returned by `Instance.list` / `info` / `delete` (domain `InstanceInfoSchema`). */
 export type InstanceInfo = {
   id: string
@@ -16,10 +20,31 @@ export type InstanceInfo = {
   url: string
   hostId?: string
   region?: string
-  state?: 'provisioning' | 'ready' | 'failed'
+  state?: InstanceState
   phase?: string
   error?: string | null
   createdAt?: string
+  organizationId?: string
+}
+
+/** Owner-scoped read shape returned by `Instance.listMine`. */
+export type OwnedInstanceInfo = InstanceInfo & {
+  state: InstanceState
+}
+
+/** Call the owner-scoped list contract through any admin client-shaped object. */
+export async function callOwnedInstances(client: {
+  call: (path: string, params: Record<string, never>) => Promise<unknown>
+}): Promise<OwnedInstanceInfo[]> {
+  return (await client.call(adminInstanceMethod('listMine'), {})) as OwnedInstanceInfo[]
+}
+
+/** Match an owner-scoped instance by its stable node id or human slug. */
+export function findOwnedInstance(
+  instances: readonly OwnedInstanceInfo[],
+  identifier: string,
+): OwnedInstanceInfo | undefined {
+  return instances.find((instance) => instance.id === identifier || instance.slug === identifier)
 }
 
 /** Human-readable location of a managed instance ("region · hostId"). */

package/src/lib/instance-candidates.ts

@@ -1,11 +1,11 @@
 import type { InstanceEntry, InstanceStore } from './instance'
 
-import { formatInstanceLocation, type InstanceInfo } from './admin-instance'
+import { formatInstanceLocation, type OwnedInstanceInfo } from './admin-instance'
 import { normalizeInstanceKernelUrl, resolveInstanceKey } from './instance'
 
 export type InstanceCandidate =
   | { source: 'bookmark'; key: string; url: string; entry: InstanceEntry }
-  | { source: 'managed'; key: string; url: string; info: InstanceInfo }
+  | { source: 'managed'; key: string; url: string; info: OwnedInstanceInfo }
 
 /**
  * Gather every instance a bare name can refer to — the local bookmark
@@ -16,7 +16,7 @@ export type InstanceCandidate =
 export function collectInstanceCandidates(
   name: string,
   store: InstanceStore,
-  managed: InstanceInfo[],
+  managed: OwnedInstanceInfo[],
 ): InstanceCandidate[] {
   const out: InstanceCandidate[] = []
 

package/src/lib/instance-target.ts

@@ -170,6 +170,7 @@ export function adminTargetToInstance(target: ResolvedAdminTarget): ResolvedInst
 }
 
 export function isManagedInstanceNotFound(error: unknown): boolean {
+  if (error instanceof AstraleError && error.code === 'INSTANCE_NOT_FOUND') return true
   if (!(error instanceof Error)) return false
   if (error.name === 'NotFoundError') return true
   // The admin kernel reports a missing instance node as InternalKernelError

package/src/lib/instance.ts

@@ -113,17 +113,6 @@ export function sanitizeStore(store: InstanceStore): { store: InstanceStore; cha
 
 let instancesMemo: InstanceStore | null = null
 
-/**
- * Drop the in-process bookmark cache so the next `readInstances` re-reads disk.
- *
- * A long-lived host (e.g. `@astrale-os/connect-host`) would otherwise serve a
- * stale bookmark list after the user runs `astrale instance bookmark`. The CLI
- * itself is one-shot, so this is a no-op for command usage.
- */
-export function resetInstancesMemo(): void {
-  instancesMemo = null
-}
-
 export async function readInstances(
   _config?: AstraleConfig,
   opts: { persist?: boolean } = {},