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

package/dist/types/lib/admin-target.d.ts

@@ -2,8 +2,12 @@ import { z } from 'zod';
 import type { AstraleConfig } from './config';
 import type { InstanceStore } from './instance';
 export declare const DEFAULT_ADMIN_TARGET_NAME = "admin";
-export declare const DEFAULT_ADMIN_TARGET_URL = "https://admin.eu.astrale.ai/api";
-export declare const DEFAULT_ADMIN_DOMAIN_ISSUER = "https://admin.beta.astrale.ai";
+export declare function defaultAdminTargetForChannel(channel: string): {
+    readonly url: string;
+    readonly domainIssuer: string;
+};
+export declare const DEFAULT_ADMIN_TARGET_URL: string;
+export declare const DEFAULT_ADMIN_DOMAIN_ISSUER: string;
 export declare const DEFAULT_ADMIN_TARGET_CONFIG: {
     name: string;
     url: string;

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/proc.d.ts

@@ -0,0 +1,43 @@
+import { type ChildProcess, type StdioOptions } from 'node:child_process';
+export type RunResult = {
+    /** Exit code, or -1 when the process was killed by a signal. */
+    code: number;
+    stdout: string;
+    stderr: string;
+};
+/**
+ * Spawn a child process and capture stdout/stderr as UTF-8 text.
+ *
+ * Uses `node:child_process` rather than `Bun.spawn` so the exact same code runs
+ * under both the Bun-compiled standalone binary (Linux/macOS) and the Node/npm
+ * build (Windows and any Node user). The promise rejects only when the process
+ * fails to spawn (e.g. ENOENT); a non-zero exit resolves with that `code` so
+ * callers can branch on it.
+ */
+export declare function run(file: string, args?: string[], opts?: {
+    cwd?: string;
+}): Promise<RunResult>;
+/**
+ * Spawn a child process with inherited stdio so its output streams live to the
+ * user's terminal. Used for hand-held installs (npm / npx) where progress
+ * matters and the output is for the human, not for parsing. Resolves with the
+ * exit code; rejects only when the process fails to spawn (e.g. ENOENT).
+ */
+export declare function runInherit(file: string, args?: string[], opts?: {
+    cwd?: string;
+}): Promise<number>;
+/**
+ * Spawn a LONG-LIVED child and return the handle immediately so the caller can
+ * supervise it (wait for exit, forward signals, tear down siblings). Unlike
+ * run()/runInherit() — which resolve only once the child closes — this is for
+ * servers the command keeps attached to (e.g. `astrale studio`'s Bun server and
+ * Vite dev process). Same node:child_process basis (cross-runtime) and bare
+ * PATH-name lookup convention. Default stdio streams stdout/stderr live but
+ * ignores stdin, so two supervised children never contend for the TTY.
+ */
+export declare function spawnHandle(file: string, args?: string[], opts?: {
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    stdio?: StdioOptions;
+    detached?: boolean;
+}): ChildProcess;

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

@@ -0,0 +1,131 @@
+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">;
+    channel: z.ZodDefault<z.ZodString>;
+    version: z.ZodOptional<z.ZodString>;
+    repo: z.ZodDefault<z.ZodString>;
+    bin: z.ZodString;
+    installedAt: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    method: "script";
+    channel: string;
+    version?: string | undefined;
+    repo: string;
+    bin: string;
+    installedAt?: string | undefined;
+}, {
+    method: "script";
+    channel?: string | undefined;
+    version?: string | undefined;
+    repo?: string | undefined;
+    bin: string;
+    installedAt?: string | undefined;
+}>;
+export type InstallMetadata = z.infer<typeof InstallMetadataSchema>;
+export declare const UpdateManifestSchema: z.ZodObject<{
+    version: z.ZodString;
+    binaryVersion: z.ZodOptional<z.ZodString>;
+    channel: z.ZodString;
+    repo: z.ZodOptional<z.ZodString>;
+    assets: z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodObject<{
+        name: z.ZodString;
+        sha256: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        sha256?: string | undefined;
+    }, {
+        name: string;
+        sha256?: string | undefined;
+    }>, z.ZodEffects<z.ZodString, {
+        name: string;
+    }, string>]>>;
+}, "strip", z.ZodTypeAny, {
+    version: string;
+    binaryVersion?: string | undefined;
+    channel: string;
+    repo?: string | undefined;
+    assets: Record<string, {
+        name: string;
+        sha256?: string | undefined;
+    } | {
+        name: string;
+    }>;
+}, {
+    version: string;
+    binaryVersion?: string | undefined;
+    channel: string;
+    repo?: string | undefined;
+    assets: Record<string, string | {
+        name: string;
+        sha256?: string | undefined;
+    }>;
+}>;
+export type UpdateManifest = z.infer<typeof UpdateManifestSchema>;
+export type Platform = {
+    os: 'darwin' | 'linux';
+    arch: 'arm64' | 'x64';
+};
+export type UpdateRequest = {
+    check?: boolean;
+    channel?: string;
+    version?: string;
+    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;
+    channel: string;
+} | {
+    status: 'available';
+    currentVersion: string;
+    latestVersion: string;
+    channel: string;
+} | {
+    status: 'updated';
+    previousVersion: string;
+    currentVersion: string;
+    channel: string;
+    bin: string;
+};
+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.3",
+  "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

@@ -0,0 +1,38 @@
+import type { ClientSession } from '@astrale-os/kernel-client/session'
+
+import { defineDomain } from '@astrale-os/sdk'
+import { issuer } from '@astrale-os/sdk/auth'
+import { createDeployment } from '@astrale-os/sdk/deployment'
+import { defineSchema } from '@astrale-os/sdk/schema/v1'
+import { expect, mock, test } from 'bun:test'
+
+import { bindAdmin } from '../binding'
+
+const schema = defineSchema('admin.astrale.ai', {})
+const deployment = createDeployment({
+  definition: defineDomain({
+    schema,
+    handlers: { functions: {}, classes: {}, interfaces: {} },
+  }),
+  issuer: issuer.accept('https://admin.beta.astrale.ai'),
+  bundleHref: 'https://admin.beta.astrale.ai/domain.bundle.json',
+  bindings: { callables: [] },
+})
+
+test('binds the installed Admin Domain instead of the source Kernel publication', async () => {
+  const installation = mock(async () => ({
+    state: 'ready' as const,
+    target: 'sha256:admin-target' as const,
+    source: { kind: 'remote' as const, publication: deployment.publication },
+    bundle: deployment.bundle,
+    readiness: 'sha256:admin-readiness' as const,
+    capabilities: { requested: [], materialized: [] },
+  }))
+  const session = { installation } as unknown as ClientSession
+
+  const binding = await bindAdmin(session)
+
+  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,168 +1,18 @@
-import type { Input, Result } from '@astrale-os/kernel-client'
-import type {
-  ClientSession,
-  SessionRequestOptions,
-  SessionSnapshot,
-} from '@astrale-os/kernel-client/session'
-import type {
-  Definition,
-  Domain as RichDomain,
-  InstanceMethod,
-  StaticMethod,
-} from '@astrale-os/sdk/domain'
-import type { PathLike } from '@astrale-os/sdk/graph/path'
-import type { Key } from '@astrale-os/sdk/schema'
+import type { ClientSession } from '@astrale-os/kernel-client/session'
+import type { DomainBinding } from '@astrale-os/shell'
 
-import { call } from '@astrale-os/kernel-client'
-import * as sessionModule from '@astrale-os/kernel-client/session'
-import { Domain } from '@astrale-os/sdk/domain'
-import { Path } from '@astrale-os/sdk/graph/path'
+import { bindDomain } from '@astrale-os/shell'
 
 const ADMIN_ORIGIN = 'admin.astrale.ai'
 
-type DynamicCallable =
-  | (Definition<'function'> & { readonly path: NonNullable<Definition<'function'>['path']> })
-  | StaticMethod
-  | InstanceMethod
+export type AdminBinding = DomainBinding
 
-export interface AdminBindingOperations {
-  readonly installation: unknown
-  readonly publication: SessionSnapshot['publication']
-  invoke(
-    callable: DynamicCallable,
-    receiverOrInput: PathLike | Input,
-    inputOrOptions?: Input | SessionRequestOptions,
-    options?: SessionRequestOptions,
-  ): Promise<unknown>
-}
-
-export type AdminBinding = RichDomain & {
-  readonly $: RichDomain['$'] & AdminBindingOperations
-}
-
-interface CompatibleCallableReference {
-  readonly origin: typeof ADMIN_ORIGIN
-  readonly revision: SessionSnapshot['publication']['schema']['revision']
-  readonly callable: Key.Callable
-  readonly target: PathLike
-  readonly outputMode: DynamicCallable['definition']['output']['mode']
-}
-
-interface CompatibleSession {
-  readonly installation?: (origin: typeof ADMIN_ORIGIN) => Promise<unknown>
-  readonly installed?: (origin: typeof ADMIN_ORIGIN) => Promise<unknown>
-  readonly invoke?: (
-    reference: CompatibleCallableReference,
-    input: Input,
-    options?: SessionRequestOptions,
-  ) => Promise<unknown>
-}
-
-type LegacyDispatchBound = (
-  session: ClientSession,
-  request: ReturnType<typeof call>,
-  expected: {
-    readonly schema: { readonly revision: CompatibleCallableReference['revision'] }
-    readonly publication: {
-      readonly origin: SessionSnapshot['publication']['origin']
-      readonly identity: SessionSnapshot['publication']['identity']
-      readonly revision: CompatibleCallableReference['revision']
-      readonly etag: SessionSnapshot['publication']['etag']
-    }
-  },
-  options?: SessionRequestOptions,
-) => Promise<Result>
-
-/** Bind the Admin revision advertised by this exact Session snapshot. */
+/** Bind the exact Admin revision installed on this source Kernel. */
 export async function bindAdmin(session: ClientSession): Promise<AdminBinding> {
-  const snapshot = await session.snapshot()
-  if (
-    snapshot.publication.origin !== ADMIN_ORIGIN ||
-    snapshot.bundle.root.origin !== ADMIN_ORIGIN
-  ) {
+  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.')
   }
-  const compatible = session as unknown as CompatibleSession
-  const resolveInstallation = compatible.installation ?? compatible.installed
-  if (resolveInstallation === undefined) {
-    throw new TypeError('Client Session cannot resolve an installed Admin Domain.')
-  }
-  const installation = await resolveInstallation.call(session, ADMIN_ORIGIN)
-  const domain = Domain.fromSchema(snapshot.bundle.root)
-  const invoke = ((
-    callable: DynamicCallable,
-    receiverOrInput: PathLike | Input,
-    inputOrOptions?: Input | SessionRequestOptions,
-    options?: SessionRequestOptions,
-  ) => {
-    const target =
-      'on' in callable ? callable.on(Path.from(receiverOrInput as PathLike)) : callable.path
-    const reference: CompatibleCallableReference = Object.freeze({
-      origin: ADMIN_ORIGIN,
-      revision: snapshot.publication.schema.revision,
-      callable: callable.key as Key.Callable,
-      target,
-      outputMode: callable.definition.output.mode,
-    })
-    return invokeCompatible(
-      session,
-      snapshot,
-      reference,
-      ('on' in callable ? inputOrOptions : receiverOrInput) as Input,
-      ('on' in callable ? options : inputOrOptions) as SessionRequestOptions | undefined,
-    )
-  }) as AdminBindingOperations['invoke']
-
-  return Object.freeze({
-    ...domain,
-    $: Object.freeze({
-      ...domain.$,
-      installation,
-      publication: snapshot.publication,
-      invoke,
-    }),
-  }) as AdminBinding
-}
-
-async function invokeCompatible(
-  session: ClientSession,
-  snapshot: SessionSnapshot,
-  reference: CompatibleCallableReference,
-  input: Input,
-  options: SessionRequestOptions | undefined,
-): Promise<unknown> {
-  const current = session as unknown as CompatibleSession
-  if (current.invoke !== undefined) return current.invoke(reference, input, options)
-
-  const dispatchBound = (sessionModule as unknown as { dispatchBound?: LegacyDispatchBound })
-    .dispatchBound
-  if (dispatchBound === undefined) {
-    throw new TypeError('Client Session cannot invoke an exact Admin publication.')
-  }
-  const result = await dispatchBound(
-    session,
-    call(reference.target, input),
-    {
-      schema: { revision: reference.revision },
-      publication: {
-        origin: snapshot.publication.origin,
-        identity: snapshot.publication.identity,
-        revision: snapshot.publication.schema.revision,
-        etag: snapshot.publication.etag,
-      },
-    },
-    options,
-  )
-  return requireOutput(reference.outputMode, result)
-}
-
-function requireOutput(
-  expected: CompatibleCallableReference['outputMode'],
-  result: Result,
-): unknown {
-  if (result.kind !== expected) {
-    if (result.kind === 'stream') void result.stream.cancel(`Admin callable declared ${expected}.`)
-    throw new TypeError(`Admin callable declared ${expected} output but returned ${result.kind}.`)
-  }
-  return result.kind === 'stream' ? result.stream : result.value
+  return binding
 }

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__/admin-target.test.ts

@@ -6,6 +6,7 @@ import {
   DEFAULT_ADMIN_TARGET_NAME,
   DEFAULT_ADMIN_DOMAIN_ISSUER,
   DEFAULT_ADMIN_TARGET_URL,
+  defaultAdminTargetForChannel,
   resolveAdminTargetFromStore,
 } from '../admin-target'
 import { DEFAULT_CONFIG, type AstraleConfig } from '../config'
@@ -32,6 +33,17 @@ const instances: InstanceStore = {
 }
 
 describe('resolveAdminTargetFromStore', () => {
+  test('derives hosted Admin defaults from the release channel', () => {
+    expect(defaultAdminTargetForChannel('beta')).toEqual({
+      url: 'https://admin.eu.beta.astrale.ai/api',
+      domainIssuer: 'https://admin.beta.astrale.ai',
+    })
+    expect(defaultAdminTargetForChannel('stable')).toEqual({
+      url: 'https://admin.eu.astrale.ai/api',
+      domainIssuer: 'https://admin.astrale.ai',
+    })
+  })
+
   test('uses hosted admin default without active instance coupling', () => {
     expect(resolveAdminTargetFromStore({}, DEFAULT_CONFIG, instances)).toEqual({
       name: DEFAULT_ADMIN_TARGET_NAME,

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

@@ -9,6 +9,7 @@ import {
   IdpSessionSchema,
   isSessionExpired,
   issuerFromToken,
+  legacyBuiltinWorkosReplacement,
   normalizeTokenResponse,
   OAuthTokenError,
   OidcMetadataSchema,
@@ -63,8 +64,11 @@ describe('IdP schemas and token helpers', () => {
     expect(config?.client.token_request_format).toBe('json')
   })
 
-  test('does not invent a WorkOS environment when no client id is configured', () => {
-    expect(builtinIdpConfig('workos', undefined, {})).toBeNull()
+  test('builds the built-in WorkOS IdP with the public client id by default', () => {
+    const config = builtinIdpConfig('workos', undefined, {})
+
+    expect(config?.entry.builtIn).toBe(true)
+    expect(config?.client.client_id).toBe('client_01KC29HET5F3QAQ8GNTPZ7F320')
   })
 
   test('reads WorkOS client id from WORKOS_CLIENT_ID before VITE_WORKOS_CLIENT_ID', () => {
@@ -75,8 +79,34 @@ describe('IdP schemas and token helpers', () => {
       }),
     ).toBe('client_primary')
     expect(workosClientIdFromEnv({ VITE_WORKOS_CLIENT_ID: 'client_vite' })).toBe('client_vite')
-    expect(workosClientIdFromEnv({})).toBeUndefined()
-    expect(workosClientIdFromEnv({ WORKOS_CLIENT_ID: '   ' })).toBeUndefined()
+    expect(workosClientIdFromEnv({})).toBe('client_01KC29HET5F3QAQ8GNTPZ7F320')
+    expect(workosClientIdFromEnv({ WORKOS_CLIENT_ID: '   ' })).toBe(
+      'client_01KC29HET5F3QAQ8GNTPZ7F320',
+    )
+  })
+
+  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', () => {