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

package/src/lib/skills.ts

@@ -3,62 +3,11 @@ import { homedir } from 'node:os'
 import { dirname, join } from 'node:path'
 
 import { findAgentBrowser } from './browser'
-import { run } from './proc'
 
-/**
- * Agent skills and the agent-browser tool are owned by the coding-agent harness
- * (Claude Code et al.) and by npm — not by this CLI. `astrale setup` and
- * `astrale update` only *detect* them and delegate installation to their real
- * installers (`npx skills add`, `npm i -g agent-browser`). This module is that
- * detection + delegation layer.
- */
+export * from './skills/sync'
 
-/** The skill name the agent harness looks up under `<dir>/<name>/SKILL.md`. */
-export const ASTRALE_CLI_SKILL = 'astrale-cli'
-export const ASTRALE_DOMAIN_SKILL = 'astrale-domain'
 export const AGENT_BROWSER_SKILL = 'agent-browser'
 
-/**
- * Published skill source consumed by `npx skills add`. The public `astrale-os/cli`
- * repo hosts BOTH the astrale-cli and astrale-domain skills (under `skills/`), so
- * one `npx skills add astrale-os/cli` installs both; address one with
- * `astrale-os/cli@astrale-cli` or `astrale-os/cli@astrale-domain`.
- */
-export const ASTRALE_CLI_SKILL_SOURCE = 'astrale-os/cli'
-
-/** Human-facing command that installs (or refreshes) both astrale skills, globally. */
-export const SKILL_INSTALL_HINT = `npx skills add ${ASTRALE_CLI_SKILL_SOURCE} -g`
-
-/**
- * Install or refresh the astrale agent skills by delegating to the skill package
- * manager (`npx skills add`). We install GLOBALLY (`-g`, user-level): one run
- * equips every project on the machine — the harness resolves the skills from the
- * user Claude dir (see {@link detectSkill}) regardless of cwd, and installs land
- * in `~/.agents/skills` rather than clobbering any project's own `.agents/skills`
- * (notably this repo's symlinked source). We don't reimplement skill installation
- * — re-running the real installer is also how an existing install updates to the
- * latest published SKILL.md, so this doubles as the update path.
- *
- * We CAPTURE the installer's output rather than stream it, and surface it only on
- * failure. A global install reports a benign per-agent note for any agent format
- * that can't go user-level (e.g. PromptScript: "does not support global skill
- * installation") as a "Failed to install N" banner — even though `npx skills`
- * still exits 0 and the skills land for every other agent. Streaming that made a
- * successful refresh look broken; suppressing it on success lets the caller print
- * a clean line. Resolves true on exit 0. Requires Node/`npx` on PATH + network.
- */
-export async function installSkills(): Promise<boolean> {
-  const { code, stdout, stderr } = await run('npx', [
-    'skills',
-    'add',
-    ASTRALE_CLI_SKILL_SOURCE,
-    '-g',
-    '-y',
-  ])
-  if (code !== 0) process.stderr.write(stdout + stderr)
-  return code === 0
-}
-
 /**
  * The directories the agent harness ACTUALLY loads skills from, in resolution
  * order: a project `.claude/skills` found by walking UP from cwd (the harness

package/src/lib/update.ts

@@ -1,5 +1,15 @@
 import { createHash } from 'node:crypto'
-import { chmod, copyFile, mkdir, mkdtemp, readFile, rename, rm, writeFile } from 'node:fs/promises'
+import {
+  chmod,
+  copyFile,
+  mkdir,
+  mkdtemp,
+  readFile,
+  realpath,
+  rename,
+  rm,
+  writeFile,
+} from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { dirname, join } from 'node:path'
 import { z } from 'zod'
@@ -61,9 +71,26 @@ export type UpdateRequest = {
   currentVersion: string
   platform?: Platform
   installPath?: string
+  execution?: UpdateExecution
 }
 
+export type UpdateExecution =
+  | { kind: 'standalone'; executable: string }
+  | { kind: 'package-managed'; executable: string }
+
+const admittedScriptInstall = Symbol('admittedScriptInstall')
+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
@@ -106,50 +133,138 @@ export function platformKey(platform: Platform): string {
   return `${platform.os}-${platform.arch}`
 }
 
-/**
- * True when running as the Bun-compiled standalone binary (Linux/macOS), which
- * self-updates by swapping its own file. The Node/npm build does not expose
- * `process.versions.bun`; it is managed by the user's package manager instead.
- */
-function isStandaloneBinary(): boolean {
-  return Boolean((process.versions as { bun?: string }).bun)
+export function classifyUpdateExecution(input: {
+  bunVersion?: string
+  executable: string
+  entry?: string
+}): UpdateExecution {
+  return input.bunVersion && input.entry?.startsWith('/$bunfs/')
+    ? { kind: 'standalone', executable: input.executable }
+    : { kind: 'package-managed', executable: input.executable }
+}
+
+export function detectUpdateExecution(): UpdateExecution {
+  return classifyUpdateExecution({
+    bunVersion: (process.versions as { bun?: string }).bun,
+    executable: process.execPath,
+    entry: process.argv[1],
+  })
+}
+
+export function packageManagedUpdateError(executable: string): AstraleError {
+  return new AstraleError(
+    'UPDATE_PACKAGE_MANAGED',
+    'This Astrale build is managed by your package manager.',
+    `Active binary: ${executable}. Update it with npm, pnpm, or bun; or put the official script installation first on PATH.`,
+  )
 }
 
 export async function readInstallMetadata(path = INSTALL_PATH): Promise<InstallMetadata> {
   let raw: string
   try {
     raw = await readFile(path, 'utf8')
-  } catch {
-    throw isStandaloneBinary()
-      ? new AstraleError(
-          'UPDATE_NOT_SCRIPT_INSTALLED',
-          'Astrale was not installed by the official install script.',
-          'Reinstall with: curl -fsSL https://raw.githubusercontent.com/astrale-os/cli/main/install.sh | sh',
-        )
-      : new AstraleError(
-          'UPDATE_PACKAGE_MANAGED',
-          'This Astrale build is managed by your package manager.',
-          'Update with: npm install -g @astrale-os/cli@latest  (or pnpm/bun)',
-        )
+  } catch (error) {
+    if (!isMissingFile(error)) throw error
+    throw new AstraleError(
+      'UPDATE_NOT_SCRIPT_INSTALLED',
+      'Astrale was not installed by the official install script.',
+      'Reinstall with: curl -fsSL https://raw.githubusercontent.com/astrale-os/cli/main/install.sh | sh',
+    )
   }
 
-  const parsed = InstallMetadataSchema.safeParse(JSON.parse(raw))
+  let decoded: unknown
+  try {
+    decoded = JSON.parse(raw)
+  } catch {
+    throw badInstallMetadata(path)
+  }
+  const parsed = InstallMetadataSchema.safeParse(decoded)
   if (!parsed.success) {
+    throw badInstallMetadata(path)
+  }
+  return parsed.data
+}
+
+function isMissingFile(error: unknown): error is NodeJS.ErrnoException {
+  return error instanceof Error && 'code' in error && error.code === 'ENOENT'
+}
+
+function badInstallMetadata(path: string): AstraleError {
+  return new AstraleError(
+    'UPDATE_BAD_INSTALL_METADATA',
+    `Invalid install metadata at ${path}.`,
+    'Reinstall with: curl -fsSL https://raw.githubusercontent.com/astrale-os/cli/main/install.sh | sh',
+  )
+}
+
+export async function admitScriptInstall(
+  meta: InstallMetadata,
+  execution: Extract<UpdateExecution, { kind: 'standalone' }>,
+): Promise<AdmittedScriptInstall> {
+  const [running, recorded] = await Promise.all([
+    realpathIfExists(execution.executable),
+    realpathIfExists(meta.bin),
+  ])
+  if (running === undefined || recorded === undefined || running !== recorded) {
     throw new AstraleError(
-      'UPDATE_BAD_INSTALL_METADATA',
-      `Invalid install metadata at ${path}.`,
-      'Reinstall with: curl -fsSL https://raw.githubusercontent.com/astrale-os/cli/main/install.sh | sh',
+      'UPDATE_INSTALL_MISMATCH',
+      'The running Astrale binary does not own the recorded script installation.',
+      `Running binary: ${execution.executable}; recorded binary: ${meta.bin}. Refusing to replace a different installation.`,
     )
   }
-  return parsed.data
+  return Object.freeze({
+    metadata: meta,
+    executable: running,
+    [admittedScriptInstall]: true as const,
+  })
+}
+
+async function realpathIfExists(path: string): Promise<string | undefined> {
+  try {
+    return await realpath(path)
+  } catch (error) {
+    if (isMissingFile(error)) return undefined
+    throw error
+  }
 }
 
 export async function writeInstallMetadata(
   meta: InstallMetadata,
   path = INSTALL_PATH,
+  filesystem: Pick<CohortFilesystem, 'mkdir' | 'rename' | 'rm'> &
+    Pick<typeof import('node:fs/promises'), 'writeFile'> = { mkdir, rename, rm, writeFile },
 ): Promise<void> {
-  await mkdir(dirname(path), { recursive: true })
-  await writeFile(path, JSON.stringify(meta, null, 2) + '\n')
+  const staged = `${path}.next`
+  const previous = `${path}.previous`
+  await filesystem.mkdir(dirname(path), { recursive: true })
+  await filesystem.rm(staged, { force: true })
+  await filesystem.rm(previous, { force: true })
+  await filesystem.writeFile(staged, JSON.stringify(meta, null, 2) + '\n')
+
+  let backedUp = false
+  try {
+    try {
+      await filesystem.rename(path, previous)
+      backedUp = true
+    } catch (error) {
+      if (!isMissingFile(error)) throw error
+    }
+    await filesystem.rename(staged, path)
+    await filesystem.rm(previous, { force: true })
+  } catch (error) {
+    const rollback: unknown[] = []
+    if (backedUp) {
+      await filesystem.rename(previous, path).catch((failure) => rollback.push(failure))
+    }
+    await filesystem.rm(staged, { force: true }).catch((failure) => rollback.push(failure))
+    if (rollback.length > 0) {
+      throw new AggregateError(
+        [error, ...rollback],
+        'Install metadata update and rollback both failed.',
+      )
+    }
+    throw error
+  }
 }
 
 export function releaseBase(
@@ -174,8 +289,138 @@ export function shouldUpdate(currentVersion: string, manifestVersion: string): b
   return currentVersion !== manifestVersion
 }
 
-export async function updateAstrale(req: UpdateRequest): Promise<UpdateResult> {
-  const meta = await readInstallMetadata(req.installPath)
+interface CohortFilesystem {
+  readonly chmod: typeof chmod
+  readonly copyFile: typeof copyFile
+  readonly mkdir: typeof mkdir
+  readonly rename: typeof rename
+  readonly rm: typeof rm
+}
+
+const defaultCohortFilesystem: CohortFilesystem = { chmod, copyFile, mkdir, rename, rm }
+
+export interface StandaloneCohortReplacement {
+  readonly finalize: () => Promise<void>
+  readonly rollback: () => Promise<void>
+}
+
+/** Replace the standalone executable and its Viewer as one rollback-safe cohort. */
+export async function replaceStandaloneCohort(
+  installedBinary: string,
+  nextBinary: string,
+  nextViewerDist: string,
+  filesystem: Partial<CohortFilesystem> = {},
+): Promise<StandaloneCohortReplacement> {
+  const fs = { ...defaultCohortFilesystem, ...filesystem }
+  const binDirectory = dirname(installedBinary)
+  const previousBinary = `${installedBinary}.previous`
+  const stagedBinary = `${installedBinary}.next`
+  const viewer = join(binDirectory, 'viewer')
+  const previousViewer = join(binDirectory, 'viewer.previous')
+  const stagedViewer = join(binDirectory, 'viewer.next')
+  const stagedViewerDist = join(stagedViewer, 'dist')
+
+  try {
+    await fs.rm(stagedViewer, { recursive: true, force: true })
+    await fs.mkdir(stagedViewerDist, { recursive: true })
+    await fs.copyFile(join(nextViewerDist, 'main.js'), join(stagedViewerDist, 'main.js'))
+    await fs.copyFile(join(nextViewerDist, 'index.html'), join(stagedViewerDist, 'index.html'))
+    await fs.copyFile(installedBinary, previousBinary)
+    await fs.copyFile(nextBinary, stagedBinary)
+    await fs.chmod(stagedBinary, 0o755)
+  } catch (error) {
+    await fs.rm(stagedViewer, { recursive: true, force: true }).catch(() => undefined)
+    await fs.rm(stagedBinary, { force: true }).catch(() => undefined)
+    throw error
+  }
+
+  await fs.rm(previousViewer, { recursive: true, force: true })
+  let viewerBackedUp = false
+  let viewerCommitted = false
+  let binaryCommitted = false
+  try {
+    try {
+      await fs.rename(viewer, previousViewer)
+      viewerBackedUp = true
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error
+    }
+    await fs.rename(stagedViewer, viewer)
+    viewerCommitted = true
+    await fs.rename(stagedBinary, installedBinary)
+    binaryCommitted = true
+  } catch (error) {
+    const rollback: unknown[] = []
+    if (binaryCommitted) {
+      await fs.copyFile(previousBinary, installedBinary).catch((failure) => rollback.push(failure))
+      await fs.chmod(installedBinary, 0o755).catch((failure) => rollback.push(failure))
+    }
+    if (viewerCommitted) {
+      await fs
+        .rm(viewer, { recursive: true, force: true })
+        .catch((failure) => rollback.push(failure))
+    }
+    if (viewerBackedUp) {
+      await fs.rename(previousViewer, viewer).catch((failure) => rollback.push(failure))
+    }
+    if (rollback.length > 0) {
+      throw new AggregateError([error, ...rollback], 'Standalone update and rollback both failed.')
+    }
+    throw error
+  } finally {
+    await fs.rm(stagedViewer, { recursive: true, force: true }).catch(() => undefined)
+    await fs.rm(stagedBinary, { force: true }).catch(() => undefined)
+  }
+
+  let settled = false
+  return Object.freeze({
+    finalize: async () => {
+      if (settled) return
+      settled = true
+      await fs.rm(previousViewer, { recursive: true, force: true }).catch(() => undefined)
+    },
+    rollback: async () => {
+      if (settled) return
+      settled = true
+      const rollback: unknown[] = []
+      await fs.copyFile(previousBinary, installedBinary).catch((failure) => rollback.push(failure))
+      await fs.chmod(installedBinary, 0o755).catch((failure) => rollback.push(failure))
+      await fs
+        .rm(viewer, { recursive: true, force: true })
+        .catch((failure) => rollback.push(failure))
+      if (viewerBackedUp) {
+        await fs.rename(previousViewer, viewer).catch((failure) => rollback.push(failure))
+      }
+      if (rollback.length > 0) {
+        throw new AggregateError(rollback, 'Standalone update rollback failed.')
+      }
+    },
+  })
+}
+
+interface UpdateDependencies {
+  readonly replaceStandaloneCohort: typeof replaceStandaloneCohort
+  readonly writeInstallMetadata: typeof writeInstallMetadata
+}
+
+const defaultUpdateDependencies = Object.freeze({ replaceStandaloneCohort, writeInstallMetadata })
+
+export async function updateAstrale(
+  req: UpdateRequest,
+  dependencies: Partial<UpdateDependencies> = {},
+): Promise<UpdateResult> {
+  const update = { ...defaultUpdateDependencies, ...dependencies }
+  const execution = req.execution ?? detectUpdateExecution()
+  if (execution.kind === 'package-managed') {
+    return {
+      status: 'managed',
+      currentVersion: req.currentVersion,
+      executable: execution.executable,
+    }
+  }
+
+  const install = await admitScriptInstall(await readInstallMetadata(req.installPath), execution)
+  const meta = install.metadata
   const currentVersion = meta.version ?? req.currentVersion
   const channel = req.channel ?? meta.channel ?? DEFAULT_UPDATE_CHANNEL
   const platform = req.platform ?? detectPlatform()
@@ -226,25 +471,33 @@ export async function updateAstrale(req: UpdateRequest): Promise<UpdateResult> {
 
     await extractTarGz(archive, tmp)
     const nextBin = join(tmp, 'astrale')
+    const nextViewer = join(tmp, 'viewer', 'dist')
     await chmod(nextBin, 0o755)
     await smokeVersion(nextBin, manifest.binaryVersion ?? manifest.version)
 
-    const previous = `${meta.bin}.previous`
-    const staged = `${meta.bin}.next`
-    await copyFile(meta.bin, previous).catch(() => undefined)
-    await copyFile(nextBin, staged)
-    await chmod(staged, 0o755)
-    await rename(staged, meta.bin)
-
-    await writeInstallMetadata(
-      {
-        ...meta,
-        channel: manifest.channel,
-        version: manifest.version,
-        installedAt: new Date().toISOString(),
-      },
-      req.installPath,
-    )
+    const replacement = await update.replaceStandaloneCohort(meta.bin, nextBin, nextViewer)
+    try {
+      await update.writeInstallMetadata(
+        {
+          ...meta,
+          channel: manifest.channel,
+          version: manifest.version,
+          installedAt: new Date().toISOString(),
+        },
+        req.installPath,
+      )
+    } catch (error) {
+      try {
+        await replacement.rollback()
+      } catch (rollbackError) {
+        throw new AggregateError(
+          [error, rollbackError],
+          'Standalone update metadata commit and cohort rollback both failed.',
+        )
+      }
+      throw error
+    }
+    await replacement.finalize()
 
     return {
       status: 'updated',

package/src/lib/validation.ts

@@ -1,4 +1,4 @@
-import { isDnsLabel } from '@astrale-os/sdk/domain'
+import { isDnsLabel } from '@astrale-os/sdk/value'
 import { z } from 'zod'
 
 import { ReservedSlugError } from '../errors'
@@ -21,7 +21,7 @@ export function validateName(name: string, entity: string): void {
 }
 
 export function validateSlug(slug: string): void {
-  // Canonical DNS-label rule (`@astrale-os/sdk/domain`): a slug becomes a
+  // Canonical Core DNS-label rule: a slug becomes a
   // hostname label, so reject anything not DNS-safe (§4.7).
   if (!slug || !isDnsLabel(slug)) {
     throw new Error(

package/src/lib/view/assets.ts

@@ -8,7 +8,11 @@ import { fileURLToPath } from 'node:url'
  * (`<pkg>/viewer/dist`). The module URL is authoritative because npm global
  * installs expose the CLI through a bin symlink outside the package root.
  */
-export function viewerDistDir(moduleUrl = import.meta.url, entry = process.argv[1] ?? '.'): string {
+export function viewerDistDir(
+  moduleUrl = import.meta.url,
+  entry = process.argv[1] ?? '.',
+  executable = process.execPath,
+): string {
   const override = process.env.ASTRALE_VIEWER_DIR
   if (override) return override
 
@@ -16,7 +20,12 @@ export function viewerDistDir(moduleUrl = import.meta.url, entry = process.argv[
   const published = join(moduleDirectory, '..', 'viewer', 'dist')
   const source = join(moduleDirectory, '..', '..', '..', 'viewer', 'dist')
   const legacy = join(dirname(entry), '..', 'viewer', 'dist')
-  const complete = [published, source, legacy].find(hasViewerBundle)
+  const standalone = entry.startsWith('/$bunfs/')
+    ? join(dirname(executable), 'viewer', 'dist')
+    : undefined
+  const complete = [standalone, published, source, legacy].find(
+    (candidate): candidate is string => candidate !== undefined && hasViewerBundle(candidate),
+  )
   if (complete) return complete
 
   // A source checkout may intentionally omit generated dist assets. Keep the

package/src/lib/view/external-open-intent.ts

@@ -0,0 +1,41 @@
+import type { ExternalOpenRequest, IntentMessage, Shell } from '@astrale-os/shell'
+
+import { replyToIntent } from '@astrale-os/shell'
+
+export interface ExternalOpenIntentHost {
+  open(request: ExternalOpenRequest): boolean
+}
+
+/** Register the root host's browser-owned external navigation effect. */
+export function installExternalOpenIntentHandler(
+  shell: Shell,
+  host: ExternalOpenIntentHost,
+): () => void {
+  return shell.onIntent('browser.openExternal', (message) => {
+    const opened = host.open(message.envelope.payload)
+    replyToIntent(shell.children, message.envelope.sender.windowId, message, {
+      outcome: opened ? 'opened' : 'blocked',
+    })
+  })
+}
+
+/** Open an external document without retaining a cross-origin opener capability. */
+export function openExternalBrowserWindow(
+  browser: Pick<Window, 'open'>,
+  request: ExternalOpenRequest,
+): boolean {
+  const popup = request.mode === 'popup'
+  const opened = browser.open('', '_blank', popup ? 'popup,width=720,height=760' : undefined)
+  if (opened === null) return false
+  try {
+    opened.opener = null
+    if (opened.opener !== null) throw new Error('Browser retained the opener capability.')
+    opened.location.replace(request.url)
+  } catch {
+    opened.close()
+    return false
+  }
+  return true
+}
+
+export type ExternalOpenIntentMessage = IntentMessage<'browser.openExternal'>

package/src/lib/view/external-open-origins.ts

@@ -0,0 +1,37 @@
+import { AstraleError } from '../../errors.js'
+
+/** Admit exact HTTPS origins explicitly granted by the CLI operator. */
+export function admitExternalOpenOrigins(input: readonly string[] | undefined): readonly string[] {
+  if (input === undefined) return Object.freeze([])
+  const admitted = new Set<string>()
+  for (const candidate of input) {
+    let url: URL
+    try {
+      url = new URL(candidate)
+    } catch (cause) {
+      throw invalidExternalOrigin(candidate, cause)
+    }
+    if (
+      url.protocol !== 'https:' ||
+      url.hostname.includes('*') ||
+      url.username !== '' ||
+      url.password !== '' ||
+      url.pathname !== '/' ||
+      url.search !== '' ||
+      url.hash !== ''
+    ) {
+      throw invalidExternalOrigin(candidate)
+    }
+    admitted.add(url.origin)
+  }
+  return Object.freeze([...admitted])
+}
+
+function invalidExternalOrigin(candidate: string, cause?: unknown): AstraleError {
+  return new AstraleError(
+    'INVALID_EXTERNAL_ORIGIN',
+    `External navigation grant "${candidate}" is not an exact HTTPS origin.`,
+    'Pass an origin such as https://connect.example.com with no credentials, path, query, or fragment.',
+    cause === undefined ? undefined : { cause },
+  )
+}

package/src/lib/view/host-capabilities.ts

@@ -0,0 +1,17 @@
+import type { HostCapabilities } from '@astrale-os/shell'
+
+import { admitHostCapabilities } from '@astrale-os/shell'
+
+/** Build the exact host grant handed to a CLI-hosted View session. */
+export function viewHostCapabilities(externalOrigins: readonly string[]): HostCapabilities {
+  return admitHostCapabilities({
+    version: 1,
+    navigation: {
+      openView: {},
+      ...(externalOrigins.length === 0 ? {} : { external: { origins: externalOrigins } }),
+    },
+    actions: {},
+    browser: {},
+    access: {},
+  })
+}

package/src/lib/view/resolve.ts

@@ -1,4 +1,4 @@
-import type { ResolvedView as SessionResolvedView } from '@astrale-os/kernel-client/session'
+import type { ResolvedView as SessionResolvedView } from '@astrale-os/sdk/client/session'
 import type { ResolvedView } from '@astrale-os/shell'
 
 import { Path } from '@astrale-os/sdk/graph/path'

package/src/lib/view/server.ts

@@ -1,3 +1,5 @@
+import type { AuthApi } from '@astrale-os/sdk/auth'
+import type { IssuerId } from '@astrale-os/sdk/auth'
 import type { ReadableStream as WebReadableStream } from 'node:stream/web'
 
 import { readFile } from 'node:fs/promises'
@@ -23,8 +25,9 @@ export { ensureViewerAssets, viewerDistDir } from './assets'
  * heartbeat keeps a live session alive.
  */
 
-const TOKEN_REFRESH_MARGIN_MS = 5 * 60_000
-const FALLBACK_TOKEN_TTL_MS = 3600_000
+const VIEW_TOKEN_TTL_SECONDS = 4 * 60
+const TOKEN_REFRESH_MARGIN_MS = 60_000
+const FALLBACK_TOKEN_TTL_MS = VIEW_TOKEN_TTL_SECONDS * 1_000
 const IDLE_SWEEP_MS = 60_000
 
 export type PageStatus = { state: string; error?: string; at: string }
@@ -44,7 +47,7 @@ export function startViewServer(config: ViewServeConfig): Server {
   async function freshGrant(): Promise<TokenGrant> {
     if (grant && grant.expiresAt - Date.now() > TOKEN_REFRESH_MARGIN_MS) return grant
     grant = await withClientSession(config.kernel, async ({ auth, target }) => {
-      const token = await auth.mint({ audience: target.kernelIssuer, ttlSeconds: 3_600 })
+      const token = await mintViewCredential(auth, target.kernelIssuer)
       return {
         token,
         expiresAt: jwtExpiry(token) ?? Date.now() + FALLBACK_TOKEN_TTL_MS,
@@ -98,6 +101,7 @@ export function startViewServer(config: ViewServeConfig): Server {
         identity: session.identity ?? null,
         instance: session.instance ?? null,
         sessionId: session.id,
+        externalOrigins: config.externalOrigins,
       })
       return
     }
@@ -182,6 +186,17 @@ export function startViewServer(config: ViewServeConfig): Server {
   return server
 }
 
+/** Mint a short-lived credential from the selected CLI identity proof. */
+export async function mintViewCredential(
+  auth: Pick<AuthApi, 'mint'>,
+  audience: IssuerId,
+): Promise<string> {
+  return auth.mint({
+    audience,
+    ttlSeconds: VIEW_TOKEN_TTL_SECONDS,
+  })
+}
+
 function jwtExpiry(token: string): number | null {
   try {
     const payload = JSON.parse(Buffer.from(token.split('.')[1], 'base64url').toString('utf8')) as {

package/src/lib/view/session.ts

@@ -41,6 +41,8 @@ export type ViewServeConfig = {
    * handles CORS and self-signed local CAs.
    */
   proxy: { kernelUrl: string; issuer: string; caFile?: string; direct: boolean }
+  /** Exact HTTPS origins the operator consented to open from this View session. */
+  externalOrigins: readonly string[]
   idleMs: number
 }
 

package/src/program/.spec/api.d.ts

@@ -5,6 +5,7 @@ export interface CommandArgument {
   readonly name: string
   readonly description: string
   readonly required?: boolean
+  readonly variadic?: boolean
 }
 
 /** One Commander-compatible option in a CLI command definition. */