@astrale-os/cli 1.0.0-beta.32 → 1.0.0-beta.43

package/src/commands/session/analyze.ts

@@ -1,72 +0,0 @@
-import chalk from 'chalk'
-
-import type { CommandDefinition } from '../../program/index'
-
-import { log } from '../../lib/log'
-import { analyzeSession } from '../../telemetry/analyze'
-import { sweepStore } from '../../telemetry/retention'
-import { scanSessions } from '../../telemetry/store'
-import { restampLock, releaseLock } from '../../telemetry/trigger'
-
-export default {
-  name: 'analyze',
-  description: 'Analyze a recorded session for DX frictions (dry-run: writes report.md)',
-  arguments: [
-    // Optional: the action resolves the most recent closed, unanalyzed session
-    // when no id is given, which is how a human is meant to invoke this. The
-    // opportunistic trigger always passes an explicit id.
-    {
-      name: 'id',
-      description: 'Session id (default: most recent closed, unanalyzed)',
-      required: false,
-    },
-  ],
-  options: [
-    { flags: '--file', description: 'File cleared findings as issues on the admin tracker' },
-    { flags: '--model <model>', description: 'Model for the analyzer pass' },
-    { flags: '--force', description: 'Re-analyze even if already analyzed' },
-    { flags: '--auto', description: 'Triggered mode: quiet, used by the opportunistic trigger' },
-  ],
-  action: async (
-    id: string | undefined,
-    opts: { file?: boolean; model?: string; force?: boolean; auto?: boolean },
-  ) => {
-    if (opts.auto) restampLock()
-    let target = id
-    try {
-      if (!target) {
-        const candidate = scanSessions().find((s) => s.closed && (opts.force || !s.analyzed))
-        if (!candidate) {
-          if (!opts.auto) log.dim('Nothing to analyze — no closed, unanalyzed session.')
-          return
-        }
-        target = candidate.id
-      }
-      if (!opts.auto) log.step(`analyzing session ${target} …`)
-      const outcome = await analyzeSession(target, opts)
-      if (opts.auto) return
-      if (outcome.outcome === 'skipped-quiet') {
-        log.dim(`quiet session (${outcome.note}) — nothing to analyze`)
-      } else if (outcome.outcome === 'error') {
-        log.error(`analyzer failed: ${outcome.note ?? 'unknown'}`)
-      } else {
-        log.success(`${outcome.outcome} (${outcome.note ?? ''})`)
-        if (outcome.reportPath) console.log(chalk.dim(`  ${outcome.reportPath}`))
-      }
-    } finally {
-      if (opts.auto) releaseLock()
-      // The size bound is enforced here, not on the CLI's critical path:
-      // measuring every file of every session is only affordable in this
-      // process, and this is precisely where the store just grew. The session
-      // just analyzed is protected — it is the freshest evidence on disk.
-      try {
-        const swept = sweepStore({ protect: new Set(target === undefined ? [] : [target]) })
-        if (!opts.auto && swept.removed.length > 0) {
-          log.dim(`retention: removed ${swept.removed.length} session(s)`)
-        }
-      } catch {
-        /* retention must never fail the command that triggered it */
-      }
-    }
-  },
-} satisfies CommandDefinition

package/src/commands/session/list.ts

@@ -1,36 +0,0 @@
-import chalk from 'chalk'
-
-import type { CommandDefinition } from '../../program/index'
-
-import { log } from '../../lib/log'
-import { isMachine, output, RAW_OUTPUT_OPTIONS } from '../../lib/output'
-import { listSessions } from '../../telemetry/store'
-
-export default {
-  name: 'list',
-  description: 'List locally recorded work sessions and their analysis state',
-  options: [...RAW_OUTPUT_OPTIONS],
-  action: async (opts: { raw?: boolean; json?: boolean }) => {
-    const sessions = listSessions()
-    if (isMachine(opts)) {
-      output(sessions, opts)
-      return
-    }
-    if (sessions.length === 0) {
-      log.dim('No sessions recorded yet. Run any astrale command in a workspace to start one.')
-      return
-    }
-    for (const s of sessions) {
-      const state = s.analyzed
-        ? s.analyzed.outcome === 'error'
-          ? chalk.red(s.analyzed.outcome)
-          : chalk.green(s.analyzed.outcome)
-        : s.closed
-          ? chalk.yellow('closed, unanalyzed')
-          : chalk.cyan('open')
-      const when = s.lastEventAt ? s.lastEventAt.toISOString().slice(0, 16) : 'no events'
-      console.log(`${chalk.bold(s.id)}  ${state}`)
-      console.log(chalk.dim(`  ${s.meta?.root ?? '(unknown root)'} — last activity ${when}`))
-    }
-  },
-} satisfies CommandDefinition

package/src/commands/setup.ts

@@ -1,54 +0,0 @@
-import type { CommandDefinition } from '../program/index'
-
-import { ADMIN_TARGET_OPTIONS } from '../lib/admin-target'
-import { fatal } from '../lib/log'
-import { RAW_OUTPUT_OPTIONS } from '../lib/output'
-import { runSetup, type SetupOpts } from '../setup/engine'
-
-export default {
-  name: 'setup',
-  description: 'Guided first run: sign in, pick an instance, and equip your workspace',
-  arguments: [
-    {
-      name: 'slug',
-      description: 'Instance slug to provision when none is active',
-      required: false,
-    },
-  ],
-  options: [
-    { flags: '--plan', description: 'Print what setup would do (read-only) and exit' },
-    ...ADMIN_TARGET_OPTIONS,
-    ...RAW_OUTPUT_OPTIONS,
-  ],
-  afterHelpText: `
-What it does:
-  Walks you from zero to a working instance, then offers to equip your agent:
-    1. Connect    sign in (WorkOS), confirm the admin control plane, pick or
-                  provision an instance — ending on your live instance URL.
-    2. Equip      the astrale agent skills (cli + domain), agent-browser, and a
-                  first domain (a pre-checked multi-select — toggle off any).
-
-  Idempotent: re-run it anytime; satisfied steps are skipped. Bare \`astrale\`
-  in a terminal launches this when you have no active instance yet.
-
-Agents / CI:
-  Piped, --ci, or --plan → read-only. \`astrale setup --plan --json\` prints each
-  step's state and the exact command to fix it; run those granular commands
-  (auth login / instance create / …) rather than the interactive wizard.
-
-Examples:
-  $ astrale setup                 # the guided flow
-  $ astrale setup my-app          # pre-fill the instance slug
-  $ astrale setup --plan          # what's left to do (no changes)
-  $ astrale setup --plan --json   # machine-readable plan for an agent
-`,
-  action: async (slug: string | undefined, opts: SetupOpts) => {
-    try {
-      await runSetup(opts, slug)
-    } catch (e) {
-      // fatal() exits 130 quietly on Ctrl-C (ExitPromptError); each step's
-      // writes are atomic + idempotent, so nothing half-applied matters.
-      fatal(e)
-    }
-  },
-} satisfies CommandDefinition

package/src/commands/status.ts

@@ -1,60 +0,0 @@
-import chalk from 'chalk'
-
-import type { CommandDefinition } from '../program/index'
-
-import { readLocalStatus } from '../lib/local-status'
-import { log } from '../lib/log'
-import { isMachine, output, RAW_OUTPUT_OPTIONS } from '../lib/output'
-
-export default {
-  name: 'status',
-  description: 'Show local CLI context: active instance, identity, and cached auth state',
-  options: [...RAW_OUTPUT_OPTIONS],
-  action: async (opts: { raw?: boolean; json?: boolean }) => {
-    const status = await readLocalStatus()
-
-    if (isMachine(opts)) {
-      output(status, opts)
-      return
-    }
-
-    console.log(chalk.bold('Admin'))
-    if ('error' in status.admin) {
-      console.log(`  ${chalk.red('invalid')}: ${status.admin.error}`)
-    } else {
-      console.log(`  ${chalk.bold(status.admin.name)} ${chalk.dim(status.admin.url)}`)
-    }
-
-    console.log('')
-    console.log(chalk.bold('Instance'))
-    if (status.instance) {
-      console.log(`  ${chalk.bold(status.instance.active)} ${chalk.dim(status.instance.url)}`)
-      if (status.instance.issuer) console.log(`  issuer: ${chalk.dim(status.instance.issuer)}`)
-      if (status.instance.defaultIdentity) {
-        console.log(`  default identity: ${status.instance.defaultIdentity}`)
-      }
-    } else {
-      log.dim('  No active instance. Run: astrale instance bookmark <name> --url <url> --use')
-    }
-
-    console.log('')
-    console.log(chalk.bold('Identity'))
-    if (status.identity) {
-      const source =
-        status.identity.source === 'idp'
-          ? `idp:${status.identity.idp ?? 'unknown'}`
-          : status.identity.source
-      console.log(`  ${chalk.bold(status.identity.name)} ${chalk.dim(`[${source}]`)}`)
-      console.log(`  subject: ${chalk.dim(status.identity.subject)}`)
-      if (status.identity.session) {
-        const state =
-          !status.identity.session.cached || status.identity.session.requiresLogin
-            ? chalk.yellow('login required')
-            : chalk.green('ready')
-        console.log(`  session: ${state}`)
-      }
-    } else {
-      log.dim('  No default identity. Run: astrale identity create <name>')
-    }
-  },
-} satisfies CommandDefinition

package/src/commands/studio.ts

@@ -1,434 +0,0 @@
-import type { ChildProcess } from 'node:child_process'
-
-import { existsSync, realpathSync } from 'node:fs'
-import { dirname, join, resolve } from 'node:path'
-
-import type { CommandDefinition } from '../program/index'
-
-import { fatal, log } from '../lib/log'
-import { isMachine, output, RAW_OUTPUT_OPTIONS, type RawOutputOpts } from '../lib/output'
-import { findFreePort, portFree } from '../lib/port'
-import { run, spawnHandle } from '../lib/proc'
-
-type StudioOpts = RawOutputOpts & {
-  port?: string
-  open?: boolean // `--open` → true. Default (undefined) prints the URL without launching a browser.
-  dev?: boolean
-  prod?: boolean
-  schemaDir?: string
-  harness?: string
-}
-
-// Uncommon, safe bands in the IANA Registered range (well below the OS
-// ephemeral range), away from the popular dev ports (3000/5173/8080/…).
-// Concurrent studios in different workspaces ladder up: 4319, 4320, 4321…
-const STUDIO_PORT_BASE = 4319
-const VITE_PORT_BASE = 5273
-const PORT_SPAN = 20
-const STUDIO_CLI_DESCRIPTOR_ENV = 'DOMAIN_STUDIO_CLI_DESCRIPTOR'
-
-/**
- * Describe this exact CLI invocation for the Studio server. A source/published
- * script needs its entrypoint after node/bun; a Bun-compiled executable is
- * self-contained and therefore has no prefix argument.
- */
-export function encodeStudioCliDescriptor(
-  executable = process.execPath,
-  entry = process.argv[1],
-): string {
-  const args =
-    entry && entry !== executable && !entry.startsWith('/$bunfs') && existsSync(entry)
-      ? [realpathSync(entry)]
-      : []
-  return JSON.stringify({ version: 1, executable, args })
-}
-
-/**
- * Locate the studio package shipped with / alongside the CLI. Anchored to the
- * resolved CLI ENTRY (process.argv[1], deref'd through any install symlink) —
- * NOT import.meta.url, which differs between the bundled dist and the unbundled
- * source run. From `<cli>/bin/astrale.ts`, `<cli>/dist/astrale.js`, or a
- * published `<pkg>/dist/astrale.js`, the studio is the sibling `../studio`.
- * `ASTRALE_STUDIO_DIR` overrides everything (point at an out-of-tree checkout).
- */
-function resolveStudioDir(): string {
-  const candidates: string[] = []
-  if (process.env.ASTRALE_STUDIO_DIR) candidates.push(process.env.ASTRALE_STUDIO_DIR)
-  try {
-    const entryDir = dirname(realpathSync(process.argv[1] ?? ''))
-    candidates.push(join(entryDir, '..', 'studio'), join(entryDir, 'studio'))
-  } catch {
-    /* argv[1] unreadable — fall through to the error below */
-  }
-  for (const c of candidates) {
-    if (existsSync(join(c, 'server', 'index.ts'))) return resolve(c)
-  }
-  throw new Error(
-    `Domain Studio assets not found (looked in: ${candidates.join(', ') || '<none>'}). ` +
-      `Reinstall the astrale CLI, or set ASTRALE_STUDIO_DIR to a studio checkout.`,
-  )
-}
-
-/** Dev iff the resolved studio dir is the MONOREPO SOURCE — the published copy ships only client/dist (no client/src, no vite.config). */
-function isDevSource(studioDir: string): boolean {
-  return (
-    existsSync(join(studioDir, 'vite.config.ts')) && existsSync(join(studioDir, 'client', 'src'))
-  )
-}
-
-/**
- * Resolve the Vite launcher bin. We spawn it DIRECTLY (not via `bun x vite`):
- * the pnpm `.bin/vite` shim stays inside our detached process group, so a group
- * kill reaps it cleanly — `bun x` forks Vite as a grandchild that escapes and
- * orphans. Checks the package's own node_modules first, then the hoisted root.
- */
-function resolveViteBin(studioDir: string): string | null {
-  for (const c of [
-    join(studioDir, 'node_modules', '.bin', 'vite'),
-    join(studioDir, '..', '..', 'node_modules', '.bin', 'vite'),
-  ]) {
-    if (existsSync(c)) return c
-  }
-  return null
-}
-
-/** The studio server is a Bun server (Bun.serve/import.meta.dir); fail early with a hint if Bun is absent rather than surfacing a raw child ENOENT. */
-async function ensureBun(): Promise<void> {
-  try {
-    if ((await run('bun', ['--version'])).code === 0) return
-  } catch {
-    /* ENOENT — handled below */
-  }
-  throw new Error(
-    'Domain Studio requires Bun on PATH. Install it from https://bun.sh, then re-run `astrale studio`.',
-  )
-}
-
-/** Poll a URL until it answers (any HTTP response = up) or the deadline passes. */
-async function waitForHttp(url: string, timeoutMs = 20_000): Promise<boolean> {
-  const deadline = Date.now() + timeoutMs
-  while (Date.now() < deadline) {
-    try {
-      await fetch(url, { signal: AbortSignal.timeout(1000) })
-      return true
-    } catch {
-      await new Promise((r) => setTimeout(r, 150))
-    }
-  }
-  return false
-}
-
-function openBrowser(url: string): void {
-  // win32: `start` is a cmd.exe builtin, not a PATH executable — must go through
-  // `cmd /c start "" <url>` (the empty "" is the title arg `start` consumes).
-  const [cmd, args] =
-    process.platform === 'darwin'
-      ? ['open', [url]]
-      : process.platform === 'win32'
-        ? ['cmd', ['/c', 'start', '', url]]
-        : ['xdg-open', [url]]
-  try {
-    spawnHandle(cmd, args as string[], { stdio: 'ignore' }).unref()
-  } catch {
-    /* best-effort; headless ok */
-  }
-}
-
-async function pickPort(
-  explicit: string | undefined,
-  base: number,
-  label: string,
-): Promise<number> {
-  if (explicit !== undefined) {
-    // Strict decimal — reject '4e3', '0x10D7', whitespace-padded, etc.
-    const p = /^\d+$/.test(explicit) ? Number(explicit) : NaN
-    if (!Number.isInteger(p) || p < 1 || p > 65535) throw new Error(`invalid --port: ${explicit}`)
-    // Explicit intent must NOT be silently relocated — probe once, error if busy.
-    if (!(await portFree(p))) {
-      throw new Error(
-        `port ${p} is busy (another studio?). Pick a free --port, or omit it to auto-select.`,
-      )
-    }
-    return p
-  }
-  const p = await findFreePort(base, PORT_SPAN)
-  if (p === null)
-    throw new Error(`no free ${label} port in ${base}-${base + PORT_SPAN - 1}; pass --port`)
-  return p
-}
-
-export default {
-  name: 'studio',
-  description: 'Launch the local Domain Studio GUI for a workspace',
-  arguments: [
-    {
-      name: 'path',
-      description: 'Workspace or domain dir to open (default: current dir)',
-      required: false,
-    },
-  ],
-  options: [
-    { flags: '--port <n>', description: 'Studio HTTP port (default: first free in 4319-4338)' },
-    {
-      flags: '--open',
-      description: 'Open the studio in your browser (default: just print the URL)',
-    },
-    {
-      flags: '--dev',
-      description:
-        'Live-edit mode for hacking on the studio itself (Vite HMR + server reload; needs the source checkout)',
-    },
-    { flags: '--prod', description: 'Serve the prebuilt client (the default)' },
-    { flags: '--schema-dir <dir>', description: 'Schema entry dir to scan for (default: schema)' },
-    {
-      flags: '--harness <name>',
-      description: 'Lock the agent harness for this Studio process',
-      choices: ['claude', 'codex'],
-    },
-    ...RAW_OUTPUT_OPTIONS,
-  ],
-  afterHelpText: `
-Behavior:
-  Launches the Domain Studio — a local web GUI to author and inspect a domain —
-  pointed at <path> (the current directory by default), so you can run it from
-  any workspace. The studio is a Bun server (Bun is required on PATH) shipped with
-  the CLI; the command locates it next to the astrale binary (override with
-  ASTRALE_STUDIO_DIR).
-
-  Port: binds the first free loopback port in 4319-4338, so a studio already
-  running in another workspace simply takes the next port (4320, 4321, …). An
-  explicit --port is used as-is, or errors if busy (never silently relocated).
-
-  By DEFAULT it serves the prebuilt client (fast, always works — this is what a
-  published install runs). --dev is the live-edit loop for hacking on the studio
-  ITSELF: a Vite dev server (client HMR) + a watched server (reloads on edits) so
-  studio changes reflect instantly; it requires the studio source checkout
-  (cli/studio) with Vite installed.
-
-  By default the command just PRINTS the URL — it does not pop a browser (that's
-  invasive when you already have a tab open). Pass --open to launch one.
-
-  Agent harness: choose Claude Code or Codex per domain in Studio Settings. Pass
-  --harness claude|codex to lock this process to one harness. Each harness uses
-  its existing local authentication and keeps an independent resumable session.
-
-  The command stays attached and supervises its child processes; Ctrl-C tears
-  them all down (a second Ctrl-C force-kills). With --json it prints a
-  { url, port, mode, workspace } descriptor.
-
-Examples:
-  $ astrale studio                 # start the studio + print its URL (no browser)
-  $ astrale studio --open          # …and open it in a browser
-  $ astrale studio ./my-domain
-  $ astrale studio --harness codex
-  $ astrale studio --port 4400
-  $ astrale studio --dev           # live-edit the studio itself (from source)
-`,
-  action: async (pathArg: string | undefined, opts: StudioOpts) => {
-    try {
-      const workspace = resolve(pathArg ?? process.cwd())
-      if (!existsSync(workspace)) throw new Error(`path not found: ${workspace}`)
-
-      const studioDir = resolveStudioDir()
-      if (process.env.ASTRALE_STUDIO_DIR && studioDir === resolve(process.env.ASTRALE_STUDIO_DIR)) {
-        log.dim(`  using ASTRALE_STUDIO_DIR=${studioDir}`)
-      }
-      await ensureBun()
-      const cliDescriptor = encodeStudioCliDescriptor()
-
-      // Default to PROD — serve the prebuilt client. It always renders, is what a
-      // published/global install runs, and avoids dev's heavy source-module graph.
-      // --dev opts into the live-edit loop, which needs the studio SOURCE
-      // (cli/studio) with Vite installed.
-      const dev = opts.dev === true
-      let viteBin: string | null = null
-      if (dev) {
-        if (!isDevSource(studioDir)) {
-          throw new Error(
-            '--dev needs the studio source checkout (cli/studio); a published install runs prod only.',
-          )
-        }
-        viteBin = resolveViteBin(studioDir)
-        if (!viteBin)
-          throw new Error('Vite is not installed — run `pnpm install` at the workspace root.')
-      }
-
-      const studioPort = await pickPort(opts.port, STUDIO_PORT_BASE, 'studio')
-      if (opts.port === undefined && studioPort !== STUDIO_PORT_BASE) {
-        log.dim(`  port ${STUDIO_PORT_BASE} busy (another studio?) — using ${studioPort}`)
-      }
-      const displayUrl = `http://localhost:${studioPort}`
-      // The studio server binds 127.0.0.1, so we PROBE IPv4 explicitly — `localhost`
-      // can resolve to ::1 first, which a 127.0.0.1-only listener won't answer.
-      const probeUrl = `http://127.0.0.1:${studioPort}/`
-
-      // Supervise the child processes. Each runs in its OWN process group
-      // (detached) so one group signal tears down the whole tree — Vite, the
-      // watched server, and their grandchildren (extractor / MCP islands). We
-      // track liveness (so we never group-signal an exited child — PID-reuse
-      // safe), escalate SIGTERM→SIGKILL on a timeout (an unresponsive child — long
-      // SSE / in-flight agent turn — can't wedge the CLI), and a second Ctrl-C
-      // force-kills immediately. Handlers attach synchronously at spawn, so a
-      // fast-failing child is never missed and a dead child downs the rest.
-      const children: ChildProcess[] = []
-      const alive = new Set<ChildProcess>()
-      let shuttingDown = false
-      let failed = false
-      let killTimer: ReturnType<typeof setTimeout> | undefined
-      const signalGroup = (c: ChildProcess, sig: NodeJS.Signals) => {
-        if (c.pid === undefined || !alive.has(c)) return
-        try {
-          process.kill(-c.pid, sig) // negative pid → the process group (POSIX)
-        } catch {
-          try {
-            c.kill(sig)
-          } catch {
-            /* gone, or win32 group semantics unsupported */
-          }
-        }
-      }
-      const killAll = () => {
-        if (shuttingDown) {
-          for (const c of children) signalGroup(c, 'SIGKILL') // second signal → escalate now
-          return
-        }
-        shuttingDown = true
-        for (const c of children) signalGroup(c, 'SIGTERM')
-        killTimer = setTimeout(() => {
-          for (const c of children) signalGroup(c, 'SIGKILL')
-        }, 5_000)
-        killTimer.unref?.()
-      }
-      const supervise = (c: ChildProcess, role: string): ChildProcess => {
-        children.push(c)
-        alive.add(c)
-        c.once('error', (err) => {
-          failed = true
-          log.error(`  studio ${role} failed: ${err instanceof Error ? err.message : String(err)}`)
-          killAll()
-        })
-        c.once('exit', () => {
-          alive.delete(c)
-          if (alive.size === 0 && killTimer) clearTimeout(killTimer)
-          if (!shuttingDown) {
-            failed = true // a child died on its own → tear the rest down
-            killAll()
-          }
-        })
-        return c
-      }
-      process.on('SIGINT', killAll)
-      process.on('SIGTERM', killAll)
-
-      let serverChild: ChildProcess
-      if (dev && viteBin) {
-        const vitePort = await pickPort(undefined, VITE_PORT_BASE, 'vite')
-        // Bind Vite to IPv4 loopback explicitly — its default `localhost` binds
-        // ONLY ::1 here, which the 127.0.0.1 server-side proxy and our probe
-        // can't reach. --strictPort: the server must know Vite's exact port.
-        supervise(
-          spawnHandle(
-            viteBin,
-            ['--host', '127.0.0.1', '--port', String(vitePort), '--strictPort'],
-            {
-              cwd: studioDir,
-              detached: true,
-              // STUDIO_VITE_PORT → vite.config points the HMR WebSocket at Vite
-              // directly (the page is served via the studio proxy on another port).
-              env: { ...process.env, STUDIO_VITE_PORT: String(vitePort) },
-            },
-          ),
-          'vite',
-        )
-        if (!(await waitForHttp(`http://127.0.0.1:${vitePort}/`))) {
-          killAll()
-          await new Promise((r) => setTimeout(r, 500)) // let SIGTERM land before we exit
-          throw new Error(
-            'Vite dev server did not start — run `pnpm install` at the workspace root, or use --prod.',
-          )
-        }
-        serverChild = supervise(
-          spawnHandle(
-            'bun',
-            ['--watch', 'server/index.ts', workspace, '--port', String(studioPort), '--no-open'],
-            {
-              cwd: studioDir,
-              detached: true,
-              env: {
-                ...process.env,
-                DOMAIN_STUDIO_DEV: '1',
-                VITE_URL: `http://127.0.0.1:${vitePort}`,
-                PORT: String(studioPort),
-                DOMAIN_STUDIO_HOST: '127.0.0.1',
-                [STUDIO_CLI_DESCRIPTOR_ENV]: cliDescriptor,
-                ...(opts.harness ? { DOMAIN_STUDIO_HARNESS: opts.harness } : {}),
-              },
-            },
-          ),
-          'server',
-        )
-      } else {
-        const dist = join(studioDir, 'client', 'dist')
-        if (!existsSync(join(dist, 'index.html'))) {
-          throw new Error(
-            `studio client not built at ${dist} — run: pnpm --filter @astrale-os/studio build`,
-          )
-        }
-        serverChild = supervise(
-          spawnHandle(
-            'bun',
-            ['server/index.ts', workspace, '--port', String(studioPort), '--no-open'],
-            {
-              cwd: studioDir,
-              detached: true,
-              env: {
-                ...process.env,
-                DOMAIN_STUDIO_DIST: dist,
-                PORT: String(studioPort),
-                DOMAIN_STUDIO_HOST: '127.0.0.1',
-                [STUDIO_CLI_DESCRIPTOR_ENV]: cliDescriptor,
-                ...(opts.harness ? { DOMAIN_STUDIO_HARNESS: opts.harness } : {}),
-              },
-            },
-          ),
-          'server',
-        )
-      }
-
-      // Resolve when the studio server ends (Ctrl-C, crash, or kill). Attached
-      // synchronously right after spawn — never lost to a race with a fast exit.
-      // NOTE: in dev the server runs under `bun --watch`, which survives an
-      // uncaught crash to hot-restart on the next edit (the intended edit loop), so
-      // the CLI stays attached until you Ctrl-C — which always tears it down.
-      const serverDone = new Promise<number>((res) =>
-        serverChild.once('exit', (code) => res(code ?? 0)),
-      )
-
-      if (!isMachine(opts))
-        log.step(
-          `Starting Domain Studio${dev ? ' (dev)' : ''} — ${displayUrl}  (indexing the workspace…)`,
-        )
-      // Indexing a multi-domain workspace is genuinely slow (the server boots +
-      // introspects every domain before it answers), so be patient — `waitForHttp`
-      // returns the instant the server is up, and only hits this ceiling in a
-      // pathological case. We open the browser once it actually answers.
-      const ready = await waitForHttp(probeUrl, 180_000)
-      if (isMachine(opts)) {
-        output({ url: displayUrl, port: studioPort, mode: dev ? 'dev' : 'prod', workspace }, opts)
-      } else {
-        log.success(`Domain Studio${dev ? ' (dev — live reload)' : ''}`)
-        log.info(`  ${workspace}`)
-        log.info(`  → ${displayUrl}`)
-        if (!ready) log.warn('  still starting — open the URL above once it finishes indexing.')
-      }
-      if (ready && opts.open === true) openBrowser(displayUrl)
-
-      // Stay attached until the studio server ends; surface a non-zero code when a
-      // child FAILURE (not a user Ctrl-C) drove the teardown.
-      const code = await serverDone
-      process.exitCode = failed && code === 0 ? 1 : code
-    } catch (e) {
-      fatal(e)
-    }
-  },
-} satisfies CommandDefinition