@astrale-os/cli 1.0.0-beta.1 → 1.0.0-beta.11

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

@@ -1,14 +1,20 @@
 import { describe, expect, test } from 'bun:test'
-import { chmod, mkdir, mkdtemp, readFile, writeFile } from 'node:fs/promises'
+import { chmod, mkdir, mkdtemp, readFile, symlink, writeFile } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 
 import {
+  admitScriptInstall,
+  classifyUpdateExecution,
+  DEFAULT_UPDATE_CHANNEL,
+  InstallMetadataSchema,
+  readInstallMetadata,
   releaseBase,
   shouldUpdate,
   updateAstrale,
   writeInstallMetadata,
   type InstallMetadata,
+  type UpdateExecution,
 } from '../update'
 
 async function makeFakeRelease(
@@ -63,7 +69,7 @@ async function makeFakeRelease(
 async function makeInstall(
   root: string,
   version: string,
-): Promise<{ meta: InstallMetadata; path: string }> {
+): Promise<{ meta: InstallMetadata; path: string; execution: UpdateExecution }> {
   const bin = join(root, 'bin', 'astrale')
   await mkdir(join(root, 'bin'), { recursive: true })
   await writeFile(
@@ -80,10 +86,43 @@ async function makeInstall(
     bin,
   }
   await writeInstallMetadata(meta, path)
-  return { meta, path }
+  return { meta, path, execution: { kind: 'standalone', executable: bin } }
 }
 
 describe('update helpers', () => {
+  test('classifies only a Bun-compiled executable as standalone', () => {
+    expect(
+      classifyUpdateExecution({
+        bunVersion: '1.3.14',
+        executable: '/tmp/astrale',
+        entry: '/$bunfs/root/astrale',
+      }),
+    ).toEqual({ kind: 'standalone', executable: '/tmp/astrale' })
+    expect(
+      classifyUpdateExecution({
+        bunVersion: '1.3.14',
+        executable: '/opt/homebrew/bin/bun',
+        entry: '/tmp/astrale.ts',
+      }),
+    ).toEqual({ kind: 'package-managed', executable: '/opt/homebrew/bin/bun' })
+    expect(
+      classifyUpdateExecution({
+        executable: '/opt/homebrew/bin/node',
+        entry: '/tmp/astrale.js',
+      }),
+    ).toEqual({ kind: 'package-managed', executable: '/opt/homebrew/bin/node' })
+  })
+
+  test('defaults missing install metadata to the beta channel', () => {
+    expect(DEFAULT_UPDATE_CHANNEL).toBe('beta')
+    expect(
+      InstallMetadataSchema.parse({
+        method: 'script',
+        bin: '/tmp/astrale',
+      }).channel,
+    ).toBe('beta')
+  })
+
   test('releaseBase resolves exact versions and channels', () => {
     const meta: InstallMetadata = {
       method: 'script',
@@ -106,10 +145,70 @@ describe('update helpers', () => {
   })
 })
 
+describe('script install admission', () => {
+  test('rejects malformed JSON with the stable metadata error', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'astrale-update-test-'))
+    const path = join(root, 'install.json')
+    await writeFile(path, '{')
+
+    await expect(readInstallMetadata(path)).rejects.toMatchObject({
+      code: 'UPDATE_BAD_INSTALL_METADATA',
+    })
+  })
+
+  test('admits a symlink only when it resolves to the recorded binary', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'astrale-update-test-'))
+    const { meta } = await makeInstall(root, '1.0.0')
+    const alias = join(root, 'astrale-alias')
+    await symlink(meta.bin, alias)
+
+    const admitted = await admitScriptInstall(meta, {
+      kind: 'standalone',
+      executable: alias,
+    })
+
+    expect(admitted.metadata).toEqual(meta)
+  })
+
+  test('rejects a standalone binary that does not own the recorded target', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'astrale-update-test-'))
+    const { meta } = await makeInstall(root, '1.0.0')
+    const other = join(root, 'other-astrale')
+    await writeFile(other, '#!/bin/sh\n')
+
+    await expect(
+      admitScriptInstall(meta, { kind: 'standalone', executable: other }),
+    ).rejects.toMatchObject({ code: 'UPDATE_INSTALL_MISMATCH' })
+  })
+})
+
 describe('updateAstrale', () => {
+  test('a package-managed process never consults or mutates a coexisting script install', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'astrale-update-test-'))
+    const { path, meta } = await makeInstall(root, '1.0.0')
+    const before = await readFile(meta.bin, 'utf8')
+    process.env.ASTRALE_UPDATE_BASE = 'file:///definitely-not-a-release'
+    try {
+      const result = await updateAstrale({
+        currentVersion: '2.0.0',
+        installPath: path,
+        execution: { kind: 'package-managed', executable: '/opt/homebrew/bin/node' },
+      })
+
+      expect(result).toEqual({
+        status: 'managed',
+        currentVersion: '2.0.0',
+        executable: '/opt/homebrew/bin/node',
+      })
+      expect(await readFile(meta.bin, 'utf8')).toBe(before)
+    } finally {
+      delete process.env.ASTRALE_UPDATE_BASE
+    }
+  })
+
   test('check compares the installed release identity from metadata', async () => {
     const root = await mkdtemp(join(tmpdir(), 'astrale-update-test-'))
-    const { path } = await makeInstall(root, 'main-abc123')
+    const { path, execution } = await makeInstall(root, 'main-abc123')
     const release = await makeFakeRelease(root, 'main-abc123', { binaryVersion: '1.0.0' })
     process.env.ASTRALE_UPDATE_BASE = `file://${release}`
     try {
@@ -118,6 +217,7 @@ describe('updateAstrale', () => {
         currentVersion: '1.0.0',
         platform: { os: 'darwin', arch: 'arm64' },
         installPath: path,
+        execution,
       })
 
       expect(result).toMatchObject({
@@ -132,7 +232,7 @@ describe('updateAstrale', () => {
 
   test('check reports available update without replacing the binary', async () => {
     const root = await mkdtemp(join(tmpdir(), 'astrale-update-test-'))
-    const { path, meta } = await makeInstall(root, '1.0.0')
+    const { path, meta, execution } = await makeInstall(root, '1.0.0')
     const release = await makeFakeRelease(root, '1.1.0')
     process.env.ASTRALE_UPDATE_BASE = `file://${release}`
     try {
@@ -141,6 +241,7 @@ describe('updateAstrale', () => {
         currentVersion: '1.0.0',
         platform: { os: 'darwin', arch: 'arm64' },
         installPath: path,
+        execution,
       })
 
       expect(result).toMatchObject({
@@ -156,7 +257,7 @@ describe('updateAstrale', () => {
 
   test('supports legacy string asset manifests', async () => {
     const root = await mkdtemp(join(tmpdir(), 'astrale-update-test-'))
-    const { path, meta } = await makeInstall(root, '1.0.0')
+    const { path, meta, execution } = await makeInstall(root, '1.0.0')
     const release = await makeFakeRelease(root, '1.1.0', { legacyManifest: true })
     process.env.ASTRALE_UPDATE_BASE = `file://${release}`
     try {
@@ -165,6 +266,7 @@ describe('updateAstrale', () => {
         currentVersion: '1.0.0',
         platform: { os: 'darwin', arch: 'arm64' },
         installPath: path,
+        execution,
       })
 
       expect(check).toMatchObject({
@@ -176,6 +278,7 @@ describe('updateAstrale', () => {
         currentVersion: '1.0.0',
         platform: { os: 'darwin', arch: 'arm64' },
         installPath: path,
+        execution,
       })
 
       expect(result).toMatchObject({
@@ -192,7 +295,7 @@ describe('updateAstrale', () => {
 
   test('updates the binary and install metadata', async () => {
     const root = await mkdtemp(join(tmpdir(), 'astrale-update-test-'))
-    const { path, meta } = await makeInstall(root, '1.0.0')
+    const { path, meta, execution } = await makeInstall(root, '1.0.0')
     const release = await makeFakeRelease(root, '1.1.0')
     process.env.ASTRALE_UPDATE_BASE = `file://${release}`
     try {
@@ -200,6 +303,7 @@ describe('updateAstrale', () => {
         currentVersion: '1.0.0',
         platform: { os: 'darwin', arch: 'arm64' },
         installPath: path,
+        execution,
       })
 
       expect(result).toMatchObject({
@@ -219,7 +323,7 @@ describe('updateAstrale', () => {
 
   test('updates canary-style releases whose binary reports the package version', async () => {
     const root = await mkdtemp(join(tmpdir(), 'astrale-update-test-'))
-    const { path, meta } = await makeInstall(root, 'main-old123')
+    const { path, meta, execution } = await makeInstall(root, 'main-old123')
     const release = await makeFakeRelease(root, 'main-new456', { binaryVersion: '1.0.0' })
     process.env.ASTRALE_UPDATE_BASE = `file://${release}`
     try {
@@ -227,6 +331,7 @@ describe('updateAstrale', () => {
         currentVersion: '1.0.0',
         platform: { os: 'darwin', arch: 'arm64' },
         installPath: path,
+        execution,
       })
 
       expect(result).toMatchObject({

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

@@ -23,7 +23,6 @@ const profile: ResolvedView = {
         kind: 'definition',
         definitions: [{ origin: 'shell.test', kind: 'class', name: 'Person' }],
       },
-      auth: 'required',
     },
     href: 'https://shell.test/profile',
     handshake: 'shell',
@@ -41,7 +40,6 @@ const card: ResolvedView = {
         kind: 'definition',
         definitions: [{ origin: 'shell.test', kind: 'class', name: 'Person' }],
       },
-      auth: 'public',
     },
     href: 'https://shell.test/card',
     handshake: 'none',

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

@@ -1,10 +1,12 @@
-import { describe, expect, test } from 'bun:test'
+import type { AuthApi } from '@astrale-os/sdk/auth'
+
+import { describe, expect, mock, test } from 'bun:test'
 import { once } from 'node:events'
 
 import type { ViewServeConfig } from '../view/session'
 
 import { findFreePort } from '../port'
-import { startViewServer } from '../view/server'
+import { mintViewCredential, startViewServer } from '../view/server'
 
 const digest = (character: string) => `sha256:${character.repeat(64)}` as const
 const target = (value: string) => value as ViewServeConfig['session']['view']['target']
@@ -13,6 +15,19 @@ const revision = (character: string) =>
   digest(character) as ViewServeConfig['session']['view']['route']['revision']
 
 describe('view session server credentials', () => {
+  test('mints a proof-bounded credential for the Kernel audience', async () => {
+    const mint = mock(async () => 'minted-credential')
+    const auth = { mint } as unknown as Pick<AuthApi, 'mint'>
+
+    await expect(mintViewCredential(auth, issuer('https://kernel.test'))).resolves.toBe(
+      'minted-credential',
+    )
+    expect(mint).toHaveBeenCalledWith({
+      audience: 'https://kernel.test',
+      ttlSeconds: 240,
+    })
+  })
+
   /** @evidence TEST-CLI-PLAIN-VIEW-RECEIVES-NO-CREDENTIAL */
   test('refuses to mint a token for a handshake-none View', async () => {
     const nonce = 'plain-view'
@@ -29,7 +44,7 @@ describe('view session server credentials', () => {
           target: target('/:example.test'),
           route: {
             key: 'example.test:view.public',
-            declaration: { target: { kind: 'domain' }, auth: 'required' },
+            declaration: { target: { kind: 'domain' } },
             href: 'https://example.test/ui/public',
             handshake: 'none',
             issuer: issuer('https://example.test'),

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

@@ -58,7 +58,7 @@ describe('view session private state', () => {
             issuer: issuer('https://example.test'),
             etag: `sha256:${'a'.repeat(64)}`,
             revision: revision('b'),
-            declaration: { target: { kind: 'domain' }, auth: 'required' },
+            declaration: { target: { kind: 'domain' } },
           },
         },
         createdAt: '2026-08-12T00:00:00.000Z',

package/src/lib/admin-instance.ts

@@ -6,7 +6,7 @@ import { withAdminClientSession } from '../connection'
 export {
   AdminInstanceNotFoundError,
   findOwnedInstance,
-  formatInstanceLocation,
+  formatInstanceState,
   type InstanceInfo,
   type InstanceState,
   type OwnedInstanceInfo,
@@ -19,19 +19,25 @@ export function listOwnedInstances(options: AdminConnectionOptions) {
   )
 }
 
+/** Read caller-visible inventory together with the exact local identity used for the Admin call. */
+export function listOwnedInstancesWithIdentity(options: AdminConnectionOptions) {
+  return withAdminClientSession(options, async (context) =>
+    Object.freeze({
+      instances: await (await connectAdminInstances(context)).list(),
+      ...(context.identity === undefined ? {} : { identity: context.identity }),
+    }),
+  )
+}
+
 /** Reuse an already-open Admin session for a caller-visible Instance inventory. */
 export async function listOwnedInstancesInContext(context: ConnectionContext) {
   return (await connectAdminInstances(context)).list()
 }
 
-/** Provision through Fleet placement or one explicitly resolved Host receiver. */
-export function createOwnedInstance(
-  options: AdminConnectionOptions,
-  slug: string,
-  hostId?: string,
-) {
+/** Request one managed Instance; Admin owns infrastructure placement. */
+export function createOwnedInstance(options: AdminConnectionOptions, slug: string) {
   return withAdminClientSession(options, async (context) =>
-    (await connectAdminInstances(context)).create(slug, hostId),
+    (await connectAdminInstances(context)).create(slug),
   )
 }
 

package/src/lib/admin-target.ts

@@ -5,11 +5,30 @@ import type { InstanceStore } from './instance'
 
 import { AstraleError } from '../errors'
 import { readInstances, resolveInstanceKey } from './instance'
+import { DEFAULT_UPDATE_CHANNEL } from './update'
 import { isHttpUrl } from './validation'
 
 export const DEFAULT_ADMIN_TARGET_NAME = 'admin'
-export const DEFAULT_ADMIN_TARGET_URL = 'https://admin.eu.astrale.ai/api'
-export const DEFAULT_ADMIN_DOMAIN_ISSUER = 'https://admin.beta.astrale.ai'
+
+export function defaultAdminTargetForChannel(channel: string): {
+  readonly url: string
+  readonly domainIssuer: string
+} {
+  return channel === 'stable'
+    ? {
+        url: 'https://admin.eu.astrale.ai/api',
+        domainIssuer: 'https://admin.astrale.ai',
+      }
+    : {
+        url: 'https://admin.eu.beta.astrale.ai/api',
+        domainIssuer: 'https://admin.beta.astrale.ai',
+      }
+}
+
+const DEFAULT_ADMIN_TARGET = defaultAdminTargetForChannel(DEFAULT_UPDATE_CHANNEL)
+
+export const DEFAULT_ADMIN_TARGET_URL = DEFAULT_ADMIN_TARGET.url
+export const DEFAULT_ADMIN_DOMAIN_ISSUER = DEFAULT_ADMIN_TARGET.domainIssuer
 
 export const DEFAULT_ADMIN_TARGET_CONFIG = {
   name: DEFAULT_ADMIN_TARGET_NAME,

package/src/lib/command-dx.ts

@@ -2,8 +2,6 @@ import type { Command, CommanderError } from 'commander'
 
 import chalk from 'chalk'
 
-import { isMachine } from './output'
-
 export type CommandCatalogEntry = {
   path: string[]
   usage: string
@@ -30,27 +28,27 @@ export function renderCommanderError(
   program: Command,
   error: CommanderError,
   argv = process.argv.slice(2),
+  machine = argv.some((token) => token === '--ci' || token === '--json' || token === '--raw') ||
+    !(process.stdout.isTTY ?? false),
 ): string {
   const tokens = stripOptions(argv)
   const catalog = collectCommandCatalog(program)
   const matched = matchRegisteredPrefix(program, tokens)
 
   if (matched.path.length === 0 && tokens.length > 0) {
-    return maybeMachine(renderUnknownCommand(tokens, catalog))
+    return maybeMachine(renderUnknownCommand(tokens, catalog), machine)
   }
 
   if (error.code === 'commander.missingArgument') {
     const usage = usageFor(matched.path, matched.command)
-    const argName = error.message.match(/'([^']+)'/)?.[1]
     return maybeMachine(
       [
-        `Missing required argument${argName ? ` ${chalk.bold(`<${argName}>`)}` : ''} for ${chalk.bold(
-          `astrale ${matched.path.join(' ')}`,
-        )}`,
+        `Missing required argument for ${chalk.bold(`astrale ${matched.path.join(' ')}`)}`,
         '',
         'Usage:',
         `  astrale ${usage}`,
       ].join('\n'),
+      machine,
     )
   }
 
@@ -66,6 +64,7 @@ export function renderCommanderError(
         'Usage:',
         `  astrale ${usage}`,
       ].join('\n'),
+      machine,
     )
   }
 
@@ -77,6 +76,7 @@ export function renderCommanderError(
         ? ['', 'Did you mean:', ...suggestions.map((s) => `  astrale ${s}`)]
         : []),
     ].join('\n'),
+    machine,
   )
 }
 
@@ -143,8 +143,8 @@ function usageFor(path: string[], command: Command): string {
 
 const ANSI_RE = new RegExp(String.fromCharCode(27) + '\\[[0-9;]*m', 'g')
 
-function maybeMachine(text: string): string {
-  if (!isMachine()) return text
+function maybeMachine(text: string, machine: boolean): string {
+  if (!machine) return text
   const plain = text.replace(ANSI_RE, '')
   const first = plain.split('\n').find((line) => line.trim().length > 0) ?? plain
   return JSON.stringify({ error: 'USAGE_ERROR', message: first, detail: plain })

package/src/lib/domain-publication.ts

@@ -0,0 +1,104 @@
+import { publication } from '@astrale-os/sdk/publication'
+
+const MAXIMUM_PUBLICATION_BYTES = 1024 * 1024
+type FetchLike = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>
+
+/** Fetch and admit one canonical Domain Publication without following its bundle. */
+export async function fetchDomainPublication(
+  input: string,
+  signal?: AbortSignal,
+  fetchImpl: FetchLike = globalThis.fetch,
+): Promise<publication.Publication> {
+  const url = domainPublicationUrl(input)
+  const response = await fetchImpl(url, {
+    redirect: 'error',
+    ...(signal === undefined ? {} : { signal }),
+  })
+  if (!response.ok) {
+    await cancel(response.body)
+    throw new Error(`GET ${url.href} → ${response.status}`)
+  }
+  const bytes = await readBounded(response, url)
+  try {
+    const source = new TextDecoder('utf-8', { fatal: true }).decode(bytes)
+    return publication.accept(JSON.parse(source) as unknown)
+  } catch (cause) {
+    throw new Error(`GET ${url.href} returned an invalid Domain Publication`, { cause })
+  }
+}
+
+async function readBounded(response: Response, url: URL): Promise<Uint8Array> {
+  const declared = response.headers.get('content-length')
+  if (
+    declared !== null &&
+    (!/^\d+$/u.test(declared) ||
+      !Number.isSafeInteger(Number(declared)) ||
+      Number(declared) > MAXIMUM_PUBLICATION_BYTES)
+  ) {
+    await cancel(response.body)
+    throw sizeError(url)
+  }
+  if (response.body === null) return new Uint8Array()
+
+  const reader = response.body.getReader()
+  const chunks: Uint8Array[] = []
+  let size = 0
+  let complete = false
+  try {
+    for (;;) {
+      const next = await reader.read()
+      if (next.done) {
+        complete = true
+        break
+      }
+      if (next.value.byteLength === 0) continue
+      if (next.value.byteLength > MAXIMUM_PUBLICATION_BYTES - size) {
+        throw sizeError(url)
+      }
+      chunks.push(next.value)
+      size += next.value.byteLength
+    }
+  } finally {
+    if (!complete) await reader.cancel().catch(() => undefined)
+    reader.releaseLock()
+  }
+
+  const bytes = new Uint8Array(size)
+  let offset = 0
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset)
+    offset += chunk.byteLength
+  }
+  return bytes
+}
+
+function sizeError(url: URL): Error {
+  return new Error(`GET ${url.href} exceeded ${MAXIMUM_PUBLICATION_BYTES} bytes`)
+}
+
+async function cancel(body: ReadableStream<Uint8Array> | null): Promise<void> {
+  if (body !== null) await body.cancel().catch(() => undefined)
+}
+
+/** Canonical discovery document for a Domain origin or exact Publication URL. */
+export function domainPublicationUrl(input: string): URL {
+  let url: URL
+  try {
+    url = new URL(input)
+  } catch {
+    throw new TypeError(`Domain deployment URL is invalid: ${input}`)
+  }
+  if (
+    !['http:', 'https:'].includes(url.protocol) ||
+    url.username !== '' ||
+    url.password !== '' ||
+    url.search !== '' ||
+    url.hash !== '' ||
+    !['', '/', publication.PATH].includes(url.pathname)
+  ) {
+    throw new TypeError(
+      `Domain deployment URL must be an HTTP(S) origin or canonical Publication URL: ${input}`,
+    )
+  }
+  return new URL(publication.PATH, url.origin)
+}

package/src/lib/failure-debug.ts

@@ -0,0 +1,26 @@
+import chalk from 'chalk'
+
+const MAXIMUM_DEBUG_FAILURES = 32
+
+export function printFailureDebug(error: unknown, url: string): void {
+  process.stderr.write(`\n${chalk.dim('── debug ─────────────────')}\n`)
+  if (url) process.stderr.write(`${chalk.dim(`url:   ${url}`)}\n`)
+  const seen = new Set<unknown>()
+  const pending: Array<{ value: unknown; relation: string }> = [{ value: error, relation: 'error' }]
+  while (pending.length > 0 && seen.size < MAXIMUM_DEBUG_FAILURES) {
+    const { value, relation } = pending.shift()!
+    if (seen.has(value)) continue
+    seen.add(value)
+    if (!(value instanceof Error)) {
+      process.stderr.write(`${chalk.dim(`${relation}: ${String(value)}`)}\n`)
+      continue
+    }
+    process.stderr.write(
+      `${chalk.dim(`${relation}: ${value.constructor.name}: ${value.message}`)}\n`,
+    )
+    if (value.stack) process.stderr.write(`${chalk.dim(value.stack)}\n`)
+    if (value.cause !== undefined) pending.push({ value: value.cause, relation: 'caused by' })
+    if (value instanceof AggregateError)
+      for (const child of value.errors) pending.push({ value: child, relation: 'aggregate' })
+  }
+}

package/src/lib/idp.ts

@@ -145,6 +145,8 @@ export const IdpSessionSchema = z
     idp: z.string(),
     issuer: z.string().url(),
     subject: z.string(),
+    /** OAuth client that issued this session's refresh token. */
+    clientId: z.string().optional(),
     audience: z.string().optional(),
     organizationId: z.string().optional(),
     access_token: z.string(),
@@ -212,6 +214,8 @@ export type IdpConfig = {
 
 export const BUILTIN_WORKOS_IDP_NAME = 'workos'
 const DEFAULT_WORKOS_API_HOST = 'https://api.workos.com'
+const DEFAULT_WORKOS_CLIENT_ID = 'client_01KC29HET5F3QAQ8GNTPZ7F320'
+const LEGACY_WORKOS_CLIENT_ID = 'client_01KC29HEGD7B40TV2C4QZ436BG'
 const WORKOS_CLIENT_ID_ENV_NAMES = ['WORKOS_CLIENT_ID', 'VITE_WORKOS_CLIENT_ID'] as const
 
 export function idpDir(name: string): string {
@@ -278,7 +282,17 @@ export async function readIdpConfigOrBuiltin(
   validateName(name, 'IdP')
   const store = await readIdpStore()
   if (store.idps[name]) {
-    return await readIdpConfig(name)
+    const existing = await readIdpConfig(name)
+    const replacement = opts.persist
+      ? legacyBuiltinWorkosReplacement(existing, opts.clientId)
+      : undefined
+    if (!replacement) return existing
+    return upsertIdpConfig({
+      name: replacement.name,
+      metadata: replacement.metadata,
+      client: replacement.client,
+      builtIn: true,
+    })
   }
 
   const builtin = builtinIdpConfig(name, opts.clientId)
@@ -411,11 +425,30 @@ export function builtinIdpConfig(
 }
 
 export function workosClientIdFromEnv(env: NodeJS.ProcessEnv = process.env): string | undefined {
-  return WORKOS_CLIENT_ID_ENV_NAMES.map((name) => env[name]?.trim()).find(
-    (value): value is string => typeof value === 'string' && value.length > 0,
+  return (
+    WORKOS_CLIENT_ID_ENV_NAMES.map((name) => env[name]?.trim()).find(
+      (value): value is string => typeof value === 'string' && value.length > 0,
+    ) ?? DEFAULT_WORKOS_CLIENT_ID
   )
 }
 
+export function legacyBuiltinWorkosReplacement(
+  existing: IdpConfig,
+  clientIdOverride?: string,
+  env: NodeJS.ProcessEnv = process.env,
+): IdpConfig | undefined {
+  if (
+    existing.name !== BUILTIN_WORKOS_IDP_NAME ||
+    !existing.entry.builtIn ||
+    existing.client.client_id !== LEGACY_WORKOS_CLIENT_ID
+  ) {
+    return undefined
+  }
+  const replacement = builtinIdpConfig(existing.name, clientIdOverride, env)
+  if (!replacement || replacement.client.client_id === LEGACY_WORKOS_CLIENT_ID) return undefined
+  return replacement
+}
+
 async function fetchOAuthAuthorizationServerMetadata(
   issuer: string,
 ): Promise<Partial<OidcMetadata> | undefined> {
@@ -644,10 +677,11 @@ export async function refreshSession(
   if (!session.refresh_token)
     throw new Error(`IdP session for "${identityName}" has no refresh token`)
   const idp = await readIdpConfig(session.idp)
+  const clientId = requireClientId(idp, session.clientId)
   const params = new URLSearchParams({
     grant_type: 'refresh_token',
     refresh_token: session.refresh_token,
-    client_id: requireClientId(idp),
+    client_id: clientId,
   })
   const audience = opts.audience ?? session.audience
   if (audience) params.set('audience', audience)
@@ -674,6 +708,7 @@ export async function refreshSession(
   const expiresAt = tokenExpiresAt(token)
   const next: IdpSession = {
     ...session,
+    clientId,
     access_token: token.access_token,
     id_token: token.id_token ?? session.id_token,
     refresh_token: token.refresh_token ?? session.refresh_token,

package/src/lib/instance-candidates.ts

@@ -1,6 +1,6 @@
 import type { InstanceEntry, InstanceStore } from './instance'
 
-import { formatInstanceLocation, type OwnedInstanceInfo } from './admin-instance'
+import { formatInstanceState, type OwnedInstanceInfo } from './admin-instance'
 import { normalizeInstanceKernelUrl, resolveInstanceKey } from './instance'
 
 export type InstanceCandidate =
@@ -44,6 +44,6 @@ export function describeInstanceCandidate(candidate: InstanceCandidate): string
   if (candidate.source === 'bookmark') {
     return `${candidate.key} (bookmark) ${candidate.url}`
   }
-  const extra = formatInstanceLocation(candidate.info)
+  const extra = formatInstanceState(candidate.info)
   return `${candidate.key} (managed) ${candidate.url}${extra ? ` — ${extra}` : ''}`
 }