@astrale-os/cli 0.5.0-alpha.0 → 0.6.0-alpha.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrale-os/cli",
-  "version": "0.5.0-alpha.0",
+  "version": "0.6.0-alpha.0",
   "description": "Astrale CLI — connect to existing Astrale kernels",
   "keywords": [
     "astrale",
@@ -24,12 +24,14 @@
     "studio/shared",
     "studio/client/dist",
     "studio/package.json",
+    "viewer/dist",
     "THIRD-PARTY-NOTICES.md"
   ],
   "type": "module",
   "exports": {
     "./keys": "./src/lib/keys.ts",
-    "./paths": "./src/lib/paths.ts"
+    "./paths": "./src/lib/paths.ts",
+    "./connect-core": "./src/connect-core.ts"
   },
   "publishConfig": {
     "access": "public",
@@ -50,6 +52,7 @@
   },
   "devDependencies": {
     "@astrale-os/ox": ">=0.1.0 <1.0.0",
+    "@astrale-os/shell": ">=0.3.5 <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",
@@ -58,6 +61,7 @@
     "@typescript/native-preview": "latest",
     "husky": "~9.1.7",
     "lint-staged": "~16.2.7",
+    "msgpackr": "^1.12.1",
     "oxfmt": "0.52.0",
     "oxlint": "latest",
     "typescript": "~6.0.1-rc"
@@ -77,7 +81,7 @@
   "scripts": {
     "preinstall": "node .check-workspace.cjs",
     "build": "bun scripts/build.ts",
-    "typecheck": "tsgo --noEmit",
+    "typecheck": "tsgo --noEmit && tsgo --noEmit -p viewer",
     "lint": "oxlint .",
     "lint:fix": "oxlint --fix .",
     "format": "pnpm exec oxfmt --write .",

package/src/command.ts

@@ -16,6 +16,8 @@ export type CommandDefinition = {
   description: string
   /** One-line summary shown in the parent's command list (Commander `.summary()`). */
   summary?: string
+  /** Hide from help listings (internal entries, e.g. `__view-serve`). */
+  hidden?: boolean
   aliases?: string[]
   arguments?: CommandArgument[]
   options?: CommandOption[]

package/src/commands/__tests__/admin-instance.test.ts

@@ -3,12 +3,13 @@ import { describe, expect, test } from 'bun:test'
 import type { IdentityStore } from '../../lib/identity'
 
 import { AuthError } from '../../errors'
-import { ADMIN_INSTANCE } from '../../lib/admin-instance'
+import { ADMIN_INSTANCE, adminInstanceMethod } from '../../lib/admin-instance'
 import { assertAlphaCreateIdentity } from '../instance/create'
 
 describe('admin-backed instance commands', () => {
   test('target the merged Instance class', () => {
-    expect(ADMIN_INSTANCE).toBe('/admin.astrale.ai/class.Instance')
+    expect(ADMIN_INSTANCE).toBe('/:admin.astrale.ai:class.Instance')
+    expect(adminInstanceMethod('list')).toBe('/:admin.astrale.ai:class.Instance:list')
   })
 
   test('instance create preflight points fresh installs at WorkOS login', () => {

package/src/commands/__tests__/domain-list.test.ts

@@ -1,7 +1,6 @@
 import { describe, expect, test } from 'bun:test'
 
-import type { DomainInfo } from '../../lib/admin-domain'
-
+import { ADMIN_DOMAIN, adminDomainMethod, type DomainInfo } from '../../lib/admin-domain'
 import { byDefaultThenName, domainProjection, type DomainRow } from '../domain/list'
 
 const strip = (s: string): string => s.replace(/\[[0-9;]*m/g, '')
@@ -18,6 +17,11 @@ function entry(over: Partial<DomainInfo>): DomainInfo {
 }
 
 describe('domain list — ordering', () => {
+  test('uses the semantic static method path', () => {
+    expect(ADMIN_DOMAIN).toBe('/:admin.astrale.ai:class.DomainEntry')
+    expect(adminDomainMethod('list')).toBe('/:admin.astrale.ai:class.DomainEntry:list')
+  })
+
   test('install-by-default sorts first, then alphabetical by origin', () => {
     const rows = [
       entry({ origin: 'zeta.astrale.ai' }),

package/src/commands/__tests__/install-identity-override.test.ts

@@ -23,7 +23,7 @@ describe('identity-override detection', () => {
 
   test('origin differing from the serving host is an override', () => {
     // The spec §5 attack shape: a fork on workers.dev claiming a well-known origin.
-    expect(isIdentityOverride('workspace.astrale.ai', 'crm.workers.dev')).toBe(true)
+    expect(isIdentityOverride('shell.astrale.ai', 'crm.workers.dev')).toBe(true)
     // The scaffold default also aliases until the placeholder origin is edited.
     expect(isIdentityOverride('hldom.example.dev', 'hldom-example-dev.acme.workers.dev')).toBe(true)
   })

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

@@ -0,0 +1,100 @@
+import { beforeEach, describe, expect, mock, test } from 'bun:test'
+
+const getMock = mock(async (_path: string) => ({ id: 'issue-id' }))
+const clientCallMock = mock(async (): Promise<unknown> => {
+  throw new Error('View:resolve must not run for a bare --view-url')
+})
+const abMock = mock(async (_args: string[]) => ({
+  ok: true,
+  data: { snapshot: '- button "Ready" [ref=e1]' },
+  error: null,
+}))
+
+mock.module('../../kernel', () => ({
+  bindGraph: () => ({ get: getMock }),
+  expandSelfInPath: async (path: string) => ({ path }),
+  resolveKernelTarget: mock(),
+  withKernelClient: async (
+    _opts: unknown,
+    run: (ctx: { client: { call: typeof clientCallMock } }) => Promise<unknown>,
+  ) => run({ client: { call: clientCallMock } }),
+}))
+
+mock.module('../../lib/browser', () => ({
+  ab: abMock,
+  AGENT_BROWSER_REPO: 'vercel-labs/agent-browser',
+  BROWSER_DIR: '/tmp/astrale-browser',
+  findAgentBrowser: mock(async () => '/usr/bin/agent-browser'),
+}))
+
+beforeEach(() => {
+  getMock.mockClear()
+  clientCallMock.mockClear()
+  abMock.mockClear()
+})
+
+describe('view session resolution', () => {
+  test('uses a bare --view-url target only as shell context', async () => {
+    const { resolveSession } = await import('../view')
+    const targetPath = '/users/user-1/issue-1'
+
+    const result = await resolveSession(undefined, {
+      viewUrl: 'http://127.0.0.1:5173/ui/issues',
+      handshake: 'shell',
+      target: targetPath,
+    })
+
+    expect(getMock).toHaveBeenCalledWith(targetPath)
+    expect(clientCallMock).not.toHaveBeenCalled()
+    expect(result).toEqual({
+      view: {
+        url: 'http://127.0.0.1:5173/ui/issues',
+        functionId: 'dev-view',
+        handshake: 'shell',
+        name: 'dev',
+      },
+      target: { id: 'issue-id', path: targetPath },
+      candidates: [],
+    })
+  })
+
+  test('lists every candidate without requiring a view selection', async () => {
+    const { resolveSession } = await import('../view')
+    const targetPath = '/domains/ai-gateway.astrale.ai/core/gemini-3-5-flash'
+    const candidates = [
+      {
+        id: 'chat-id',
+        path: '/domains/ai-gateway.astrale.ai/views/chat',
+        url: 'https://ai-gateway.astrale.ai/ui/chat',
+        origin: 'class' as const,
+      },
+      {
+        id: 'model-id',
+        path: '/domains/ai-gateway.astrale.ai/views/model',
+        url: 'https://ai-gateway.astrale.ai/ui/model',
+        origin: 'class' as const,
+      },
+    ]
+    clientCallMock.mockImplementationOnce(async () => candidates)
+
+    const result = await resolveSession(targetPath, { list: true })
+
+    expect(result).toEqual({
+      target: { id: 'issue-id', path: targetPath },
+      candidates,
+    })
+  })
+})
+
+describe('view capture timing', () => {
+  test('settles the view before taking a screenshot', async () => {
+    const { runSnapshotExtras } = await import('../view')
+
+    await runSnapshotExtras({ screenshot: '/tmp/view.png' })
+
+    const commands = abMock.mock.calls.map(([args]) => args[0])
+    expect(commands.at(-1)).toBe('screenshot')
+    expect(commands.slice(0, -1).every((command) => command === 'snapshot')).toBe(true)
+    expect(commands.length).toBeGreaterThan(2)
+  })
+})

package/src/commands/call.ts

@@ -261,7 +261,7 @@ Examples:
   $ astrale call /:host.astrale.ai:class.KernelInstance:list
   $ astrale call /:blog.acme.com:class.Author:list limit=10
   $ astrale call '@self::deactivate'
-  $ astrale call /:workspace.astrale.ai:class.App:available --json
+  $ astrale call /:shell.astrale.ai:class.Application:available --json
 `,
   arguments: [
     {

package/src/commands/domain/install.ts

@@ -7,8 +7,8 @@ import type { KernelCommandOpts } from '../../kernel'
 import { AstraleError } from '../../errors'
 import { runKernelCommand } from '../../kernel'
 import { withAdminKernelClient } from '../../kernel/client'
-import { ADMIN_DOMAIN, type DomainInfo } from '../../lib/admin-domain'
-import { ADMIN_INSTANCE, type InstanceInfo } from '../../lib/admin-instance'
+import { adminDomainMethod, type DomainInfo } from '../../lib/admin-domain'
+import { adminInstanceMethod, type InstanceInfo } from '../../lib/admin-instance'
 import { ADMIN_TARGET_OPTIONS, type AdminTargetCommandOpts } from '../../lib/admin-target'
 import { getActive } from '../../lib/instance'
 import { fatal, log, withSpinner } from '../../lib/log'
@@ -125,7 +125,7 @@ async function installViaAdmin(target: string | undefined, opts: InstallOpts): P
 
   try {
     await withAdminKernelClient(adminOpts, async (ctx) => {
-      const instances = (await ctx.client.call(`${ADMIN_INSTANCE}/list`, {})) as InstanceInfo[]
+      const instances = (await ctx.client.call(adminInstanceMethod('list'), {})) as InstanceInfo[]
 
       const ref = await resolveDomainRef(ctx, target, interactive)
       const slug = await resolveTargetSlug(opts, target, interactive, instances)
@@ -145,7 +145,7 @@ async function installViaAdmin(target: string | undefined, opts: InstallOpts): P
         `Installing ${label} on ${match.slug}`,
         !isMachine(opts),
         () =>
-          ctx.client.call(`${ADMIN_DOMAIN}/install`, {
+          ctx.client.call(adminDomainMethod('install'), {
             instanceId: match.slug,
             ...ref,
           }) as Promise<DomainInstallResult>,
@@ -190,7 +190,7 @@ async function resolveDomainRef(
   if (target) return domainRefFromTarget(target)
   if (!interactive) throw new AstraleError('MISSING_ARG', 'No domain given.')
 
-  const catalog = (await ctx.client.call(`${ADMIN_DOMAIN}/list`, {})) as DomainInfo[]
+  const catalog = (await ctx.client.call(adminDomainMethod('list'), {})) as DomainInfo[]
   const installable = catalog.filter((d) => d.url)
   if (installable.length === 0) {
     throw new AstraleError(

package/src/commands/domain/list.ts

@@ -5,7 +5,7 @@ import type { KernelCommandOpts } from '../../kernel'
 import type { ListProjection, RawOutputOpts } from '../../lib/output'
 
 import { withAdminKernelClient } from '../../kernel/client'
-import { ADMIN_DOMAIN, type DomainInfo } from '../../lib/admin-domain'
+import { adminDomainMethod, type DomainInfo } from '../../lib/admin-domain'
 import { ADMIN_TARGET_OPTIONS, type AdminTargetCommandOpts } from '../../lib/admin-target'
 import { fatal, withSpinner } from '../../lib/log'
 import { isMachine, presentList } from '../../lib/output'
@@ -102,7 +102,7 @@ Examples:
         async (): Promise<DomainRow[]> => {
           const list = await withAdminKernelClient(
             opts,
-            async (ctx) => (await ctx.client.call(`${ADMIN_DOMAIN}/list`, {})) as DomainInfo[],
+            async (ctx) => (await ctx.client.call(adminDomainMethod('list'), {})) as DomainInfo[],
           )
           const filtered = opts.defaultOnly ? list.filter((d) => d.installByDefault) : list
           filtered.sort(byDefaultThenName)

package/src/commands/domain/publish.ts

@@ -4,7 +4,7 @@ import type { CommandDefinition } from '../../command'
 import type { KernelCommandOpts } from '../../kernel'
 
 import { withAdminKernelClient } from '../../kernel/client'
-import { ADMIN_DOMAIN, type DomainInfo } from '../../lib/admin-domain'
+import { adminDomainMethod, type DomainInfo } from '../../lib/admin-domain'
 import { ADMIN_TARGET_OPTIONS, type AdminTargetCommandOpts } from '../../lib/admin-target'
 import { fatal, withSpinner } from '../../lib/log'
 import { isMachine, output } from '../../lib/output'
@@ -115,7 +115,7 @@ Examples:
             // silently bumping `updatedAt`. `info` throws when absent → treat as
             // a fresh publish.
             const existing = (await ctx.client
-              .call(`${ADMIN_DOMAIN}/info`, { origin })
+              .call(adminDomainMethod('info'), { origin })
               .catch(() => null)) as DomainInfo | null
             if (
               existing &&
@@ -127,7 +127,7 @@ Examples:
             ) {
               return { entry: existing, changed: false as const, isNew: false }
             }
-            const entry = (await ctx.client.call(`${ADMIN_DOMAIN}/publish`, {
+            const entry = (await ctx.client.call(adminDomainMethod('publish'), {
               origin,
               name,
               url: publicUrl,

package/src/commands/instance/active.ts

@@ -3,7 +3,7 @@ import chalk from 'chalk'
 import type { CommandDefinition } from '../../command'
 
 import { withAdminKernelClient } from '../../kernel/client'
-import { ADMIN_INSTANCE, type InstanceInfo } from '../../lib/admin-instance'
+import { adminInstanceMethod, type InstanceInfo } from '../../lib/admin-instance'
 import { getActive, normalizeInstanceKernelUrl } from '../../lib/instance'
 import { log } from '../../lib/log'
 import { RAW_OUTPUT_OPTIONS, isMachine, output, type RawOutputOpts } from '../../lib/output'
@@ -51,7 +51,7 @@ async function resolveActiveForDisplay(): Promise<{
     const managed = await withAdminKernelClient(
       {},
       async (ctx) =>
-        (await ctx.client.call(`${ADMIN_INSTANCE}/info`, { id: active.name })) as InstanceInfo,
+        (await ctx.client.call(adminInstanceMethod('info'), { id: active.name })) as InstanceInfo,
     )
     return {
       name: managed.slug,

package/src/commands/instance/create.ts

@@ -63,7 +63,7 @@ Examples:
         return
       }
     } catch (e) {
-      fatal(e)
+      fatal(e, opts)
     }
   },
 } satisfies CommandDefinition

package/src/commands/instance/delete.ts

@@ -2,7 +2,7 @@ import type { CommandDefinition } from '../../command'
 import type { KernelCommandOpts } from '../../kernel'
 
 import { withAdminKernelClient } from '../../kernel/client'
-import { ADMIN_INSTANCE, type InstanceInfo } from '../../lib/admin-instance'
+import { adminInstanceMethod, type InstanceInfo } from '../../lib/admin-instance'
 import { ADMIN_TARGET_OPTIONS, type AdminTargetCommandOpts } from '../../lib/admin-target'
 import { clearActive, readInstances, removeInstance, resolveInstanceKey } from '../../lib/instance'
 import { fatal, log, withSpinner } from '../../lib/log'
@@ -40,7 +40,7 @@ Behavior:
           withAdminKernelClient(
             opts,
             async (ctx) =>
-              (await ctx.client.call(`${ADMIN_INSTANCE}/delete`, { id })) as InstanceInfo,
+              (await ctx.client.call(adminInstanceMethod('delete'), { id })) as InstanceInfo,
           ),
         { success: (deleted) => `Deleted instance: ${deleted.slug}` },
       )
@@ -66,7 +66,7 @@ Behavior:
         log.dim(`  hint: it's a local bookmark — drop it with: astrale instance forget ${id}`)
         process.exit(1)
       }
-      fatal(e)
+      fatal(e, opts)
     }
   },
 } satisfies CommandDefinition

package/src/commands/instance/list.ts

@@ -5,7 +5,11 @@ import type { KernelCommandOpts } from '../../kernel'
 import type { Column } from '../../lib/output'
 
 import { withAdminKernelClient } from '../../kernel/client'
-import { ADMIN_INSTANCE, formatInstanceLocation, type InstanceInfo } from '../../lib/admin-instance'
+import {
+  adminInstanceMethod,
+  formatInstanceLocation,
+  type InstanceInfo,
+} from '../../lib/admin-instance'
 import { ADMIN_TARGET_OPTIONS, type AdminTargetCommandOpts } from '../../lib/admin-target'
 import { normalizeInstanceKernelUrl, readInstances } from '../../lib/instance'
 import { fatal, log, withSpinner } from '../../lib/log'
@@ -60,7 +64,8 @@ export default {
         managed = await withSpinner('Fetching instances', !isMachine(opts), () =>
           withAdminKernelClient(
             opts,
-            async (ctx) => (await ctx.client.call(`${ADMIN_INSTANCE}/list`, {})) as InstanceInfo[],
+            async (ctx) =>
+              (await ctx.client.call(adminInstanceMethod('list'), {})) as InstanceInfo[],
           ),
         )
       }
@@ -87,7 +92,7 @@ export default {
       }
       process.stdout.write(renderTable(rows, { columns: COLUMNS }) + '\n')
     } catch (e) {
-      fatal(e)
+      fatal(e, opts)
     }
   },
 } satisfies CommandDefinition

package/src/commands/instance/status.ts

@@ -4,7 +4,7 @@ import type { CommandDefinition } from '../../command'
 import type { KernelCommandOpts } from '../../kernel'
 
 import { withAdminKernelClient } from '../../kernel/client'
-import { ADMIN_INSTANCE, type InstanceInfo } from '../../lib/admin-instance'
+import { adminInstanceMethod, type InstanceInfo } from '../../lib/admin-instance'
 import { ADMIN_TARGET_OPTIONS, type AdminTargetCommandOpts } from '../../lib/admin-target'
 import { fatal, log, withSpinner } from '../../lib/log'
 import { isMachine, output, type RawOutputOpts } from '../../lib/output'
@@ -21,7 +21,8 @@ export default {
       const result = await withSpinner(`Fetching instance ${id}`, !isMachine(opts), () =>
         withAdminKernelClient(
           opts,
-          async (ctx) => (await ctx.client.call(`${ADMIN_INSTANCE}/info`, { id })) as InstanceInfo,
+          async (ctx) =>
+            (await ctx.client.call(adminInstanceMethod('info'), { id })) as InstanceInfo,
         ),
       )
       if (isMachine(opts)) {
@@ -36,7 +37,7 @@ export default {
       if (result.hostId) log.dim(`  host: ${result.hostId}`)
       if (result.createdAt) log.dim(`  created: ${result.createdAt}`)
     } catch (e) {
-      fatal(e)
+      fatal(e, opts)
     }
   },
 } satisfies CommandDefinition

package/src/commands/instance/use.ts

@@ -2,7 +2,7 @@ import type { CommandDefinition } from '../../command'
 
 import { AstraleError } from '../../errors'
 import { withAdminKernelClient } from '../../kernel/client'
-import { ADMIN_INSTANCE, type InstanceInfo } from '../../lib/admin-instance'
+import { adminInstanceMethod, type InstanceInfo } from '../../lib/admin-instance'
 import { ADMIN_TARGET_OPTIONS } from '../../lib/admin-target'
 import { getDefault, setDefault } from '../../lib/identity'
 import {
@@ -142,7 +142,7 @@ async function fetchManagedInstances(name: string, opts: UseOpts): Promise<Insta
   try {
     return await withAdminKernelClient(
       opts,
-      async (ctx) => (await ctx.client.call(`${ADMIN_INSTANCE}/list`, {})) as InstanceInfo[],
+      async (ctx) => (await ctx.client.call(adminInstanceMethod('list'), {})) as InstanceInfo[],
     )
   } catch {
     return []

package/src/commands/query.ts

@@ -46,8 +46,7 @@ export async function queryCommand(paths: string[], opts: QueryOpts): Promise<vo
     label: mode.kind === 'roots' ? 'Query ' + mode.roots.join(' ') : 'Query',
     fn: async (ctx) => {
       const read = () => bindGraph(ctx).query(mode.kind === 'roots' ? mode.query.ast : mode.ast)
-      const result =
-        mode.kind === 'roots' ? await withSelfHint(read, mode.meta) : await read()
+      const result = mode.kind === 'roots' ? await withSelfHint(read, mode.meta) : await read()
       return result.wire
     },
     format: (result, fmtOpts) => {
@@ -62,7 +61,8 @@ async function parseMode(paths: string[], opts: QueryOpts): Promise<QueryMode> {
   const hasRoots = rootsInput.length > 0
   const hasAst = opts.ast !== undefined
   const hasCypher = opts.cypher !== undefined
-  const hasSelectors = opts.depth !== undefined || opts.children !== undefined || opts.edges !== undefined
+  const hasSelectors =
+    opts.depth !== undefined || opts.children !== undefined || opts.edges !== undefined
 
   if (hasCypher) {
     if (hasAst || hasRoots || hasSelectors) {
@@ -215,7 +215,9 @@ function parseSelector<T>(flag: string, raw: string, schema: SelectorSchema): T
     throw new Error(flag + ' must be JSON: ' + raw)
   }
   if (parsed === null || typeof parsed !== 'object') {
-    throw new Error(flag + ' must be a JSON selector object' + (flag === '--edges' ? ' or array' : ''))
+    throw new Error(
+      flag + ' must be a JSON selector object' + (flag === '--edges' ? ' or array' : ''),
+    )
   }
   const check = schema.safeParse(parsed)
   if (!check.success) {
@@ -232,11 +234,21 @@ function printCursorFooter(next: NonNullable<GetResultWire['next']>): void {
   if (entries.length === 1) {
     const cursors = entries[0]?.[1]
     if (cursors?.children) {
-      process.stdout.write(chalk.dim('  more: --children \'{"cursor":"' + cursors.children + '"}\'\n'))
+      process.stdout.write(
+        chalk.dim('  more: --children \'{"cursor":"' + cursors.children + '"}\'\n'),
+      )
     }
     for (const [alias, cursor] of Object.entries(cursors?.edges ?? {})) {
       process.stdout.write(
-        chalk.dim('  more edges[' + alias + ']: --edges \'{"as":"' + alias + '","cursor":"' + cursor + '"}\'\n'),
+        chalk.dim(
+          '  more edges[' +
+            alias +
+            ']: --edges \'{"as":"' +
+            alias +
+            '","cursor":"' +
+            cursor +
+            '"}\'\n',
+        ),
       )
     }
     return
@@ -279,7 +291,11 @@ export default {
     '',
   ].join('\n'),
   arguments: [
-    { name: 'paths...', description: 'One or more root paths (/domain/Class) or IDs (@nodeId)', required: false },
+    {
+      name: 'paths...',
+      description: 'One or more root paths (/domain/Class) or IDs (@nodeId)',
+      required: false,
+    },
   ],
   options: [
     { flags: '--depth <n>', description: 'Subtree depth to fetch (0-5, default 0)' },
@@ -291,7 +307,10 @@ export default {
       flags: '--edges <json>',
       description: 'Edge selector (or JSON array of selectors) to include',
     },
-    { flags: '--ast <json>', description: 'Raw QueryASTInput JSON object (experimental, unstable shape)' },
+    {
+      flags: '--ast <json>',
+      description: 'Raw QueryASTInput JSON object (experimental, unstable shape)',
+    },
     { flags: '--cypher <query>', description: 'Read-only Cypher escape hatch' },
   ],
   action: async (paths, opts) => {

package/src/commands/session/analyze.ts

@@ -0,0 +1,50 @@
+import chalk from 'chalk'
+
+import type { CommandDefinition } from '../../command'
+
+import { log } from '../../lib/log'
+import { analyzeSession } from '../../telemetry/analyze'
+import { listSessions } 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: [{ name: 'id', description: 'Session id (default: most recent closed, unanalyzed)' }],
+  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()
+    try {
+      let target = id
+      if (!target) {
+        const candidate = listSessions().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()
+    }
+  },
+} satisfies CommandDefinition

package/src/commands/session/list.ts

@@ -0,0 +1,36 @@
+import chalk from 'chalk'
+
+import type { CommandDefinition } from '../../command'
+
+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/token.ts

@@ -60,7 +60,7 @@ What this token is FOR — worker-direct HTTP calls:
   use 'astrale call' (which signs per-call) instead.
 
 Examples:
-  $ export TOKEN=$(astrale token --audience workspace.astrale.ai --raw)
+  $ export TOKEN=$(astrale token --audience shell.astrale.ai --raw)
   $ astrale token --audience worker.example.com --for alice -i staging
 `,
   options: [

package/src/commands/view-serve.ts

@@ -0,0 +1,26 @@
+import { readFile } from 'node:fs/promises'
+
+import type { CommandDefinition } from '../command'
+import type { ViewServeConfig } from '../lib/view/session'
+
+import { startViewServer } from '../lib/view/server'
+
+/**
+ * Internal (hidden) entry for the detached view-session server: `astrale view`
+ * re-invokes the CLI with `__view-serve --config <file>` so the server runs
+ * under the same runtime and codebase as the CLI itself.
+ */
+export default {
+  name: '__view-serve',
+  hidden: true,
+  description: 'Internal: run a view-session server from a config file',
+  options: [{ flags: '--config <path>', description: 'ViewServeConfig JSON path' }],
+  action: async (opts: { config?: string }) => {
+    if (!opts.config) throw new Error('--config is required')
+    const config = JSON.parse(await readFile(opts.config, 'utf8')) as ViewServeConfig
+    startViewServer(config)
+    console.log(`view session ${config.session.id} listening on ${config.session.pageUrl}`)
+    // Keep the process alive; startViewServer owns shutdown (signals + idle).
+    await new Promise(() => {})
+  },
+} satisfies CommandDefinition