@astrale-os/cli 1.0.0-beta.4 → 1.0.0-beta.5

package/dist/types/lib/idp.d.ts

@@ -322,6 +322,7 @@ export declare function fetchOidcMetadata(issuer: string): Promise<OidcMetadata>
 export declare function workosAuthKitMetadata(apiHost?: string, clientId?: string): OidcMetadata;
 export declare function builtinIdpConfig(name: string, clientIdOverride?: string, env?: NodeJS.ProcessEnv): IdpConfig | null;
 export declare function workosClientIdFromEnv(env?: NodeJS.ProcessEnv): string | undefined;
+export declare function legacyBuiltinWorkosReplacement(existing: IdpConfig, clientIdOverride?: string, env?: NodeJS.ProcessEnv): IdpConfig | undefined;
 export declare function postForm(url: string, params: URLSearchParams): Promise<TokenResponse>;
 export declare function postJson(url: string, bodyInput: Record<string, string>): Promise<TokenResponse>;
 export declare function tokenExpiresAt(token: TokenResponse): string | undefined;

package/dist/types/lib/update.d.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { AstraleError } from '../errors';
 export declare const DEFAULT_UPDATE_CHANNEL = "beta";
 export declare const InstallMetadataSchema: z.ZodObject<{
     method: z.ZodLiteral<"script">;
@@ -73,8 +74,26 @@ export type UpdateRequest = {
     currentVersion: string;
     platform?: Platform;
     installPath?: string;
+    execution?: UpdateExecution;
 };
+export type UpdateExecution = {
+    kind: 'standalone';
+    executable: string;
+} | {
+    kind: 'package-managed';
+    executable: string;
+};
+declare const admittedScriptInstall: unique symbol;
+export type AdmittedScriptInstall = Readonly<{
+    metadata: InstallMetadata;
+    executable: string;
+    [admittedScriptInstall]: true;
+}>;
 export type UpdateResult = {
+    status: 'managed';
+    currentVersion: string;
+    executable: string;
+} | {
     status: 'up-to-date';
     currentVersion: string;
     latestVersion: string;
@@ -93,9 +112,20 @@ export type UpdateResult = {
 };
 export declare function detectPlatform(): Platform;
 export declare function platformKey(platform: Platform): string;
+export declare function classifyUpdateExecution(input: {
+    bunVersion?: string;
+    executable: string;
+    entry?: string;
+}): UpdateExecution;
+export declare function detectUpdateExecution(): UpdateExecution;
+export declare function packageManagedUpdateError(executable: string): AstraleError;
 export declare function readInstallMetadata(path?: string): Promise<InstallMetadata>;
+export declare function admitScriptInstall(meta: InstallMetadata, execution: Extract<UpdateExecution, {
+    kind: 'standalone';
+}>): Promise<AdmittedScriptInstall>;
 export declare function writeInstallMetadata(meta: InstallMetadata, path?: string): Promise<void>;
 export declare function releaseBase(meta: InstallMetadata, req: Pick<UpdateRequest, 'channel' | 'version'>): string;
 export declare function fetchManifest(base: string): Promise<UpdateManifest>;
 export declare function shouldUpdate(currentVersion: string, manifestVersion: string): boolean;
 export declare function updateAstrale(req: UpdateRequest): Promise<UpdateResult>;
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrale-os/cli",
-  "version": "1.0.0-beta.4",
+  "version": "1.0.0-beta.5",
   "description": "Astrale CLI — connect to existing Astrale kernels",
   "keywords": [
     "astrale",
@@ -62,11 +62,14 @@
     "zod": "^3.25.0"
   },
   "devDependencies": {
-    "@astrale-os/kernel-client": ">=0.6.0-beta.4 <1.0.0",
-    "@astrale-os/kernel-protocol": ">=0.5.0-beta.3 <1.0.0",
+    "@astrale-os/kernel-client": ">=0.6.0-beta.8 <1.0.0",
+    "@astrale-os/kernel-core": ">=0.9.0-beta.7 <1.0.0",
+    "@astrale-os/kernel-dsl": ">=0.2.0-beta.5 <1.0.0",
+    "@astrale-os/kernel-protocol": ">=0.5.0-beta.7 <1.0.0",
+    "@astrale-os/kernel-server": ">=0.5.0-beta.8 <1.0.0",
     "@astrale-os/ox": ">=0.1.3 <1.0.0",
-    "@astrale-os/sdk": ">=0.5.0-beta.9 <1.0.0",
-    "@astrale-os/shell": ">=0.3.8-beta.2 <1.0.0",
+    "@astrale-os/sdk": ">=0.5.0-beta.14 <1.0.0",
+    "@astrale-os/shell": ">=0.3.8-beta.3 <1.0.0",
     "@astrale/commitlint-config": "npm:@jsr/astrale__commitlint-config@~2.0.1",
     "@commitlint/cli": "~20.3.1",
     "@commitlint/config-conventional": "~20.3.1",

package/src/admin/__tests__/binding.test.ts

@@ -20,7 +20,7 @@ const deployment = createDeployment({
 })
 
 test('binds the installed Admin Domain instead of the source Kernel publication', async () => {
-  const installed = mock(async () => ({
+  const installation = mock(async () => ({
     state: 'ready' as const,
     target: 'sha256:admin-target' as const,
     source: { kind: 'remote' as const, publication: deployment.publication },
@@ -28,11 +28,11 @@ test('binds the installed Admin Domain instead of the source Kernel publication'
     readiness: 'sha256:admin-readiness' as const,
     capabilities: { requested: [], materialized: [] },
   }))
-  const session = { installed } as unknown as ClientSession
+  const session = { installation } as unknown as ClientSession
 
   const binding = await bindAdmin(session)
 
-  expect(installed).toHaveBeenCalledWith('admin.astrale.ai')
+  expect(installation).toHaveBeenCalledWith('admin.astrale.ai')
   expect(binding.$.origin).toBe('admin.astrale.ai')
   expect(String(binding.$.publication?.identity.issuer)).toBe('https://admin.beta.astrale.ai')
 })

package/src/admin/binding.ts

@@ -1,7 +1,7 @@
-import type { DomainBinding } from '@astrale-os/kernel-client/domain'
 import type { ClientSession } from '@astrale-os/kernel-client/session'
+import type { DomainBinding } from '@astrale-os/shell'
 
-import { bind } from '@astrale-os/kernel-client/domain'
+import { bindDomain } from '@astrale-os/shell'
 
 const ADMIN_ORIGIN = 'admin.astrale.ai'
 
@@ -9,8 +9,8 @@ export type AdminBinding = DomainBinding
 
 /** Bind the exact Admin revision installed on this source Kernel. */
 export async function bindAdmin(session: ClientSession): Promise<AdminBinding> {
-  const installed = await session.installed(ADMIN_ORIGIN)
-  const binding = bind(session, installed)
+  const installed = await session.installation(ADMIN_ORIGIN)
+  const binding = await bindDomain(session, installed.bundle.root)
   if (binding.$.publication?.origin !== ADMIN_ORIGIN || binding.$.origin !== ADMIN_ORIGIN) {
     throw new TypeError('Configured Admin target does not serve the Admin Domain.')
   }

package/src/admin/catalog/.spec/api.d.ts

@@ -1,5 +1,5 @@
-import type { DomainBinding } from '@astrale-os/kernel-client/domain'
 import type { ClientSession } from '@astrale-os/kernel-client/session'
+import type { DomainBinding } from '@astrale-os/shell'
 
 import type { AdminGraphApi } from '../../graph/.spec/api.js'
 

package/src/admin/instance/.spec/api.d.ts

@@ -1,5 +1,5 @@
-import type { DomainBinding } from '@astrale-os/kernel-client/domain'
 import type { ClientSession } from '@astrale-os/kernel-client/session'
+import type { DomainBinding } from '@astrale-os/shell'
 
 import type { AdminGraphApi } from '../../graph/.spec/api.js'
 

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

@@ -35,9 +35,11 @@ describe('CLI update staleness', () => {
     const result = await cliStale(
       { channel: 'canary' },
       {
-        update: async () => {
-          throw new Error('package managed')
-        },
+        update: async () => ({
+          status: 'managed',
+          currentVersion: '1.0.0-beta.0',
+          executable: '/opt/homebrew/bin/node',
+        }),
         fetchPackageVersion: async ({ channel }) => {
           expect(channel).toBe('canary')
           return '1.0.0-canary.0'
@@ -52,6 +54,26 @@ describe('CLI update staleness', () => {
     })
   })
 
+  test('does not misclassify a script update failure as package-managed', async () => {
+    const fetchPackageVersion = mock(async () => '9.9.9')
+    const result = await cliStale(
+      {},
+      {
+        update: async () => {
+          throw new Error('release endpoint unavailable')
+        },
+        fetchPackageVersion,
+      },
+    )
+
+    expect(result).toMatchObject({
+      stale: false,
+      managed: false,
+      error: 'release endpoint unavailable',
+    })
+    expect(fetchPackageVersion).not.toHaveBeenCalled()
+  })
+
   test('maps the default to beta and the stable channel to npm latest', async () => {
     const originalFetch = globalThis.fetch
     const fetchMock = mock(async (input: RequestInfo | URL) => {

package/src/commands/update.ts

@@ -12,7 +12,7 @@ import {
   type SdkOutdated,
 } from '../lib/sdk-deps'
 import { ASTRALE_CLI_SKILL, detectSkill, installSkills, SKILL_INSTALL_HINT } from '../lib/skills'
-import { DEFAULT_UPDATE_CHANNEL, updateAstrale } from '../lib/update'
+import { DEFAULT_UPDATE_CHANNEL, packageManagedUpdateError, updateAstrale } from '../lib/update'
 
 type UpdateOpts = RawOutputOpts & {
   check?: boolean
@@ -104,14 +104,22 @@ async function refreshSdkDeps(check: boolean, assumeYes = false): Promise<boolea
 /**
  * Read-only staleness report for tooling — `astrale update --check --json`.
  * domain-studio polls this on load to drive its "update available" badge. It is
- * unified and NON-THROWING: the CLI axis catches the package-managed / no-metadata
- * case (reported as `managed`, never stale), and the SDK axis is already
- * best-effort. Skills are intentionally absent — they ride along with `astrale
- * update`, so a stale CLI or SDK is the only signal worth surfacing.
+ * unified and NON-THROWING: an explicit package-managed result uses npm release
+ * identity, while script-install failures remain script failures in `error`
+ * instead of being recategorized. The SDK axis is already best-effort. Skills are
+ * intentionally absent — they ride along with `astrale update`, so a stale CLI or
+ * SDK is the only signal worth surfacing.
  */
 export type StaleReport = {
   stale: boolean
-  cli: { stale: boolean; managed: boolean; current?: string; latest?: string; channel?: string }
+  cli: {
+    stale: boolean
+    managed: boolean
+    current?: string
+    latest?: string
+    channel?: string
+    error?: string
+  }
   sdk: { stale: boolean; inProject: boolean; outdated: SdkOutdated[] }
 }
 
@@ -138,6 +146,15 @@ export async function cliStale(
       version: target.version,
       currentVersion: running,
     })
+    if (r.status === 'managed') {
+      const latest = await dependencies.fetchPackageVersion(target).catch(() => undefined)
+      return {
+        stale: latest !== undefined && latest !== running,
+        managed: true,
+        current: running,
+        ...(latest === undefined ? {} : { latest, channel: 'npm' }),
+      }
+    }
     if (r.status === 'updated') {
       return {
         stale: false,
@@ -154,13 +171,12 @@ export async function cliStale(
       latest: r.latestVersion,
       channel: r.channel,
     }
-  } catch {
-    const latest = await dependencies.fetchPackageVersion(target).catch(() => undefined)
+  } catch (error) {
     return {
-      stale: latest !== undefined && latest !== running,
-      managed: true,
+      stale: false,
+      managed: false,
       current: running,
-      ...(latest === undefined ? {} : { latest, channel: 'npm' }),
+      error: error instanceof Error ? error.message : String(error),
     }
   }
 }
@@ -294,6 +310,10 @@ Examples:
         log.success(`Updated astrale ${result.previousVersion} -> ${result.currentVersion}`)
         log.dim(`  channel: ${result.channel}`)
         log.dim(`  binary: ${result.bin}`)
+      } else if (result?.status === 'managed') {
+        const error = packageManagedUpdateError(result.executable)
+        if (!opts.yes) throw error
+        log.warn(`CLI self-update skipped: ${error.message}`)
       }
 
       // Axis B — agent skills. Keep an existing install current with the CLI.

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

@@ -9,6 +9,7 @@ import {
   IdpSessionSchema,
   isSessionExpired,
   issuerFromToken,
+  legacyBuiltinWorkosReplacement,
   normalizeTokenResponse,
   OAuthTokenError,
   OidcMetadataSchema,
@@ -84,6 +85,30 @@ describe('IdP schemas and token helpers', () => {
     )
   })
 
+  test('replaces only the legacy persisted built-in WorkOS client', () => {
+    const legacy = builtinIdpConfig('workos', 'client_01KC29HEGD7B40TV2C4QZ436BG', {})!
+    const replacement = legacyBuiltinWorkosReplacement(legacy, undefined, {})
+
+    expect(replacement?.client.client_id).toBe('client_01KC29HET5F3QAQ8GNTPZ7F320')
+    expect(replacement?.metadata.jwks_uri).toBe(
+      'https://api.workos.com/sso/jwks/client_01KC29HET5F3QAQ8GNTPZ7F320',
+    )
+    expect(
+      legacyBuiltinWorkosReplacement(
+        { ...legacy, entry: { ...legacy.entry, builtIn: false } },
+        undefined,
+        {},
+      ),
+    ).toBeUndefined()
+    expect(
+      legacyBuiltinWorkosReplacement(
+        { ...legacy, client: { ...legacy.client, client_id: 'client_custom' } },
+        undefined,
+        {},
+      ),
+    ).toBeUndefined()
+  })
+
   test('stores client secret env names, not secret material', () => {
     const client = IdpClientConfigSchema.parse({
       client_id: 'client_123',

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

@@ -1,16 +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(
@@ -65,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(
@@ -82,10 +86,33 @@ 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(
@@ -118,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 {
@@ -130,6 +217,7 @@ describe('updateAstrale', () => {
         currentVersion: '1.0.0',
         platform: { os: 'darwin', arch: 'arm64' },
         installPath: path,
+        execution,
       })
 
       expect(result).toMatchObject({
@@ -144,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 {
@@ -153,6 +241,7 @@ describe('updateAstrale', () => {
         currentVersion: '1.0.0',
         platform: { os: 'darwin', arch: 'arm64' },
         installPath: path,
+        execution,
       })
 
       expect(result).toMatchObject({
@@ -168,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 {
@@ -177,6 +266,7 @@ describe('updateAstrale', () => {
         currentVersion: '1.0.0',
         platform: { os: 'darwin', arch: 'arm64' },
         installPath: path,
+        execution,
       })
 
       expect(check).toMatchObject({
@@ -188,6 +278,7 @@ describe('updateAstrale', () => {
         currentVersion: '1.0.0',
         platform: { os: 'darwin', arch: 'arm64' },
         installPath: path,
+        execution,
       })
 
       expect(result).toMatchObject({
@@ -204,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 {
@@ -212,6 +303,7 @@ describe('updateAstrale', () => {
         currentVersion: '1.0.0',
         platform: { os: 'darwin', arch: 'arm64' },
         installPath: path,
+        execution,
       })
 
       expect(result).toMatchObject({
@@ -231,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 {
@@ -239,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

@@ -29,7 +29,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/idp.ts

@@ -215,6 +215,7 @@ 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 {
@@ -281,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)
@@ -421,6 +432,23 @@ export function workosClientIdFromEnv(env: NodeJS.ProcessEnv = process.env): str
   )
 }
 
+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> {