@astrale-os/cli 1.0.0-beta.3 → 1.0.0-beta.31

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'),
@@ -45,12 +60,20 @@ describe('view session server credentials', () => {
         issuer: 'https://kernel.test',
         direct: true,
       },
+      externalOrigins: ['https://connect.nango.dev'],
       idleMs: 60_000,
     } satisfies ViewServeConfig
     const server = startViewServer(config)
     await once(server, 'listening')
 
     try {
+      const configResponse = await fetch(`http://127.0.0.1:${port}/s/${nonce}/config.json`)
+      expect(configResponse.status).toBe(200)
+      expect(await configResponse.json()).toMatchObject({
+        sessionId: 'v-plain',
+        externalOrigins: ['https://connect.nango.dev'],
+      })
+
       const response = await fetch(`http://127.0.0.1:${port}/s/${nonce}/token`, {
         method: 'POST',
       })

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',
@@ -69,6 +69,7 @@ describe('view session private state', () => {
         issuer: 'https://kernel.test',
         direct: true,
       },
+      externalOrigins: [],
       idleMs: 60_000,
     } satisfies ViewServeConfig
 

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/binary.ts

@@ -7,14 +7,31 @@ import { output } from './output'
 
 /** A binary kernel result: bytes (or a stream of them) plus its content-type. */
 export type BinaryLike = {
-  readonly body: Uint8Array
+  readonly body: Uint8Array | AsyncIterable<Uint8Array>
   readonly mediaType: string
+  readonly status?: number
   readonly headers?: Readonly<Record<string, string>>
 }
 
 /** Collapse a (possibly streamed) binary body into a single byte array. */
-export async function readBinaryBody(body: Uint8Array): Promise<Uint8Array> {
-  return body
+export async function readBinaryBody(
+  body: Uint8Array | AsyncIterable<Uint8Array>,
+): Promise<Uint8Array> {
+  if (body instanceof Uint8Array) return new Uint8Array(body)
+  const chunks: Uint8Array[] = []
+  let size = 0
+  for await (const chunk of body) {
+    const detached = new Uint8Array(chunk)
+    chunks.push(detached)
+    size += detached.byteLength
+  }
+  const bytes = new Uint8Array(size)
+  let offset = 0
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset)
+    offset += chunk.byteLength
+  }
+  return bytes
 }
 
 function isTextLike(contentType: string): boolean {
@@ -43,13 +60,13 @@ function humanSize(bytes: number): string {
 function jsonEnvelope(resp: BinaryLike, bytes: Uint8Array): Record<string, unknown> {
   if (isTextLike(resp.mediaType)) {
     return {
-      status: 200,
+      status: resp.status ?? 200,
       contentType: resp.mediaType,
       body: new TextDecoder().decode(bytes),
     }
   }
   return {
-    status: 200,
+    status: resp.status ?? 200,
     contentType: resp.mediaType,
     bodyBase64: Buffer.from(bytes).toString('base64'),
   }

package/src/lib/browser-retention.ts

@@ -0,0 +1,210 @@
+/**
+ * Browser-profile retention.
+ *
+ * `astrale browser` keeps one persistent Chromium profile per host so the
+ * WorkOS cookie survives between runs. That cookie is a few kilobytes;
+ * everything Chromium accumulates around it is cache, and it accumulates
+ * without limit — a real profile here reached 373 MB, 98% of it cache.
+ *
+ * Chromium will not bound it for us. `--disk-cache-size` is measurably ignored
+ * for a profile's HTTP cache — the largest component by far — so deleting is
+ * the only lever. Two rules, cheapest first:
+ *
+ *   1. A profile untouched for longer than the age bound goes entirely. Its
+ *      WorkOS cookie has expired anyway, so it holds nothing worth the disk.
+ *   2. A surviving profile whose cache exceeds the size bound has its cache
+ *      directories removed. Cookies, Local Storage, Preferences and Local State
+ *      are never touched — the whole point of the profile is that the session
+ *      outlives the sweep.
+ *
+ * A profile whose SingletonLock names a live process is always left alone:
+ * deleting files under a running Chromium is how profiles get corrupted.
+ */
+import { readlinkSync } from 'node:fs'
+import { readdir, rm, stat } from 'node:fs/promises'
+import { join } from 'node:path'
+
+import { BROWSER_DIR } from './browser'
+import { readConfig } from './config'
+
+/** Reconstructible directories, relative to a profile root. Everything here can
+ *  be deleted with no user-visible consequence beyond a colder first load. */
+const CACHE_PATHS = [
+  'Default/Cache',
+  'Default/Code Cache',
+  'Default/GPUCache',
+  'Default/DawnWebGPUCache',
+  'Default/DawnGraphiteCache',
+  'Default/Service Worker/CacheStorage',
+  'Default/Service Worker/ScriptCache',
+  'GraphiteDawnCache',
+  'GPUPersistentCache',
+  'GrShaderCache',
+  'ShaderCache',
+  'component_crx_cache',
+  'extensions_crx_cache',
+] as const
+
+export const DEFAULT_MAX_CACHE_BYTES = 50 * 1024 * 1024
+export const DEFAULT_MAX_PROFILE_AGE_DAYS = 30
+
+export type BrowserRetentionBudget = {
+  /** Cap on one profile's cache directories, not on the profile as a whole. */
+  maxCacheBytes: number
+  maxProfileAgeMs: number
+}
+
+export type BrowserSweepResult = {
+  /** Profiles deleted outright (dormant past the age bound). */
+  removed: string[]
+  /** Profiles kept, cache emptied (over the size bound). */
+  purged: string[]
+  /** Profiles a live browser was holding — left untouched. */
+  skipped: string[]
+  bytesFreed: number
+}
+
+const EMPTY: BrowserSweepResult = { removed: [], purged: [], skipped: [], bytesFreed: 0 }
+
+/** First finite, strictly positive candidate; anything else falls through to
+ *  the next one, and ultimately to the default. A typo must not mean "no cap". */
+function firstPositive(candidates: (number | string | undefined)[]): number | null {
+  for (const candidate of candidates) {
+    if (candidate === undefined) continue
+    const n = typeof candidate === 'string' ? Number(candidate.trim()) : candidate
+    if (Number.isFinite(n) && n > 0) return n
+  }
+  return null
+}
+
+/** Resolved budget: env over config over defaults. */
+export async function browserRetentionBudget(): Promise<BrowserRetentionBudget> {
+  const browser = (await readConfig().catch(() => null))?.browser
+  const bytes =
+    firstPositive([process.env.ASTRALE_BROWSER_MAX_CACHE_BYTES, browser?.maxCacheBytes]) ??
+    DEFAULT_MAX_CACHE_BYTES
+  const days =
+    firstPositive([process.env.ASTRALE_BROWSER_MAX_PROFILE_AGE_DAYS, browser?.maxProfileAgeDays]) ??
+    DEFAULT_MAX_PROFILE_AGE_DAYS
+  return { maxCacheBytes: bytes, maxProfileAgeMs: days * 24 * 60 * 60 * 1000 }
+}
+
+/** True when a process with this pid exists. EPERM means it exists but is not
+ *  ours — still alive, and still a reason not to touch the profile. */
+function isLive(pid: number): boolean {
+  try {
+    process.kill(pid, 0)
+    return true
+  } catch (e) {
+    return (e as NodeJS.ErrnoException).code === 'EPERM'
+  }
+}
+
+/**
+ * Whether a live browser holds this profile. SingletonLock is a symlink whose
+ * target is `<hostname>-<pid>` and which does NOT resolve to a real file, so it
+ * must be read with readlink, never stat'ed. A stale lock (dead pid) is not a
+ * reason to skip — Chromium leaves those behind after a crash.
+ */
+export function heldByLiveBrowser(profileDir: string): boolean {
+  let target: string
+  try {
+    target = readlinkSync(join(profileDir, 'SingletonLock'))
+  } catch {
+    return false
+  }
+  const pid = Number(target.slice(target.lastIndexOf('-') + 1))
+  return Number.isInteger(pid) && pid > 0 && isLive(pid)
+}
+
+/** Bytes under `dir`, or 0 when it is missing or unreadable. */
+async function directoryBytes(dir: string): Promise<number> {
+  let entries
+  try {
+    entries = await readdir(dir, { withFileTypes: true })
+  } catch {
+    return 0
+  }
+  let total = 0
+  for (const entry of entries) {
+    const path = join(dir, entry.name)
+    if (entry.isDirectory()) {
+      total += await directoryBytes(path)
+    } else if (entry.isFile()) {
+      try {
+        total += (await stat(path)).size
+      } catch {
+        /* raced away mid-walk */
+      }
+    }
+  }
+  return total
+}
+
+/** Cumulative size of one profile's cache directories. */
+export async function profileCacheBytes(profileDir: string): Promise<number> {
+  let total = 0
+  for (const relative of CACHE_PATHS) total += await directoryBytes(join(profileDir, relative))
+  return total
+}
+
+/** Delete every cache directory of a profile; returns bytes actually freed. */
+async function purgeCache(profileDir: string): Promise<number> {
+  const before = await profileCacheBytes(profileDir)
+  for (const relative of CACHE_PATHS) {
+    await rm(join(profileDir, relative), { recursive: true, force: true }).catch(() => {
+      /* best effort — retention must never break the browser command */
+    })
+  }
+  return before - (await profileCacheBytes(profileDir))
+}
+
+/**
+ * Apply both rules across every profile under `dir`. Never throws: a failed
+ * sweep must not stop the user from driving a browser.
+ */
+export async function sweepBrowserProfiles(
+  options: { dir?: string; budget?: BrowserRetentionBudget; now?: number } = {},
+): Promise<BrowserSweepResult> {
+  const dir = options.dir ?? BROWSER_DIR
+  let names: string[]
+  try {
+    names = (await readdir(dir, { withFileTypes: true }))
+      .filter((e) => e.isDirectory())
+      .map((e) => e.name)
+  } catch {
+    return EMPTY
+  }
+  if (names.length === 0) return EMPTY
+
+  const budget = options.budget ?? (await browserRetentionBudget())
+  const now = options.now ?? Date.now()
+  const result: BrowserSweepResult = { removed: [], purged: [], skipped: [], bytesFreed: 0 }
+
+  for (const name of names) {
+    const profileDir = join(dir, name)
+    if (heldByLiveBrowser(profileDir)) {
+      result.skipped.push(name)
+      continue
+    }
+    try {
+      // The profile root's mtime tracks USE, not writes: Chromium rewrites
+      // SingletonLock and DevToolsActivePort there on every launch, while cache
+      // writes land in subdirectories and leave the root alone.
+      const idleMs = now - (await stat(profileDir)).mtime.getTime()
+      if (idleMs > budget.maxProfileAgeMs) {
+        result.bytesFreed += await directoryBytes(profileDir)
+        await rm(profileDir, { recursive: true, force: true })
+        result.removed.push(name)
+        continue
+      }
+      if ((await profileCacheBytes(profileDir)) > budget.maxCacheBytes) {
+        result.bytesFreed += await purgeCache(profileDir)
+        result.purged.push(name)
+      }
+    } catch {
+      /* best effort, per profile — one bad profile must not stop the sweep */
+    }
+  }
+  return result
+}

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/config.ts

@@ -6,10 +6,21 @@ import { CONFIG_PATH } from '../state/index'
 import { AdminTargetConfigSchema, DEFAULT_ADMIN_TARGET_CONFIG } from './admin-target'
 import { log } from './log'
 
+/** A retention bound, or undefined when absent or nonsensical. A bad value must
+ *  fall back to the default rather than take the whole config down with it —
+ *  and must never read as "no limit". */
+const bound = z.number().positive().finite().optional().catch(undefined)
+
 export const AstraleConfigSchema = z.object({
   issuer: z.string().url().default('https://unregistered.invalid'),
   admin: AdminTargetConfigSchema.default(DEFAULT_ADMIN_TARGET_CONFIG),
-  telemetry: z.object({ enabled: z.boolean().default(true) }).default({ enabled: true }),
+  // The retention bounds live in the schema, not just in the readers that
+  // consume them: zod strips unknown keys, so a config the CLI rewrites (see
+  // setup/steps/admin.ts) would silently drop anything declared elsewhere.
+  telemetry: z
+    .object({ enabled: z.boolean().default(true), maxAgeDays: bound, maxBytes: bound })
+    .default({ enabled: true }),
+  browser: z.object({ maxCacheBytes: bound, maxProfileAgeDays: bound }).default({}),
 })
 
 export type AstraleConfig = z.infer<typeof AstraleConfigSchema>

package/src/lib/domain-publication.ts

@@ -1,4 +1,4 @@
-import { publication } from '@astrale-os/kernel-protocol'
+import { publication } from '@astrale-os/sdk/publication'
 
 const MAXIMUM_PUBLICATION_BYTES = 1024 * 1024
 type FetchLike = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>
@@ -9,8 +9,7 @@ export async function fetchDomainPublication(
   signal?: AbortSignal,
   fetchImpl: FetchLike = globalThis.fetch,
 ): Promise<publication.Publication> {
-  const root = deploymentRoot(input)
-  const url = new URL(publication.PATH, root)
+  const url = domainPublicationUrl(input)
   const response = await fetchImpl(url, {
     redirect: 'error',
     ...(signal === undefined ? {} : { signal }),
@@ -81,7 +80,8 @@ async function cancel(body: ReadableStream<Uint8Array> | null): Promise<void> {
   if (body !== null) await body.cancel().catch(() => undefined)
 }
 
-function deploymentRoot(input: string): URL {
+/** 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)
@@ -94,9 +94,11 @@ function deploymentRoot(input: string): URL {
     url.password !== '' ||
     url.search !== '' ||
     url.hash !== '' ||
-    !['', '/'].includes(url.pathname)
+    !['', '/', publication.PATH].includes(url.pathname)
   ) {
-    throw new TypeError(`Domain deployment URL must be an HTTP(S) origin: ${input}`)
+    throw new TypeError(
+      `Domain deployment URL must be an HTTP(S) origin or canonical Publication URL: ${input}`,
+    )
   }
-  return new URL(url.origin)
+  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

@@ -214,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 {
@@ -280,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)
@@ -413,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> {

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}` : ''}`
 }