@astrale-os/cli 0.8.1-alpha.6 → 1.0.0-beta.0

package/src/commands/domain/install.ts

@@ -6,6 +6,7 @@ import type { KernelCommandOpts } from '../../connection'
 import type { CommandDefinition } from '../../program/index'
 
 import { createPathCall, runKernelCommand, withAdminClientSession } from '../../connection'
+import { formatKernelError } from '../../connection/errors'
 import { AstraleError } from '../../errors'
 import {
   installAdminDomainInContext,
@@ -21,11 +22,7 @@ import { confirmWithInput, promptText, selectFrom } from '../../lib/prompt'
 import { isHttpUrl } from '../../lib/validation'
 
 /** Public Kernel install syscall input for one remote URL. */
-export function directInstallCallInput(
-  url: string,
-  token?: string,
-  operation: string = crypto.randomUUID(),
-) {
+export function directInstallCallInput(url: string, operation: string, token?: string) {
   return Object.freeze({
     operation,
     domains: [
@@ -50,9 +47,28 @@ type DirectInstallResult = {
   }[]
 }
 
+const OPERATION_ID_PATTERN =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/u
+
+function acceptOperationId(input: unknown): string {
+  if (typeof input !== 'string' || !OPERATION_ID_PATTERN.test(input)) {
+    throw new AstraleError(
+      'INVALID_FLAG',
+      '--operation must be a canonical lowercase UUIDv4.',
+      'Omit --operation for a fresh install; use it only with the exact UUID printed for recovery.',
+    )
+  }
+  return input
+}
+
+function createOperationId(): string {
+  return acceptOperationId(globalThis.crypto.randomUUID())
+}
+
 type InstallOpts = KernelCommandOpts &
   AdminTargetCommandOpts & {
     direct?: boolean
+    operation?: string
     token?: string
     allowIdentityOverride?: boolean
     // Global flags (program.ts) that force non-interactive.
@@ -78,6 +94,10 @@ Behavior:
   origin differs from its serving host, it requires explicit consent (an
   interactive DANGER prompt, or --allow-identity-override in scripts).
 
+  A fresh, strong operation id is generated automatically. Use --operation
+  only to retry or recover the exact same direct install after an outcome-unknown
+  timeout or disconnect.
+
 Examples:
   $ astrale domain install crm.acme.dev -i staging          # by origin, via admin
   $ astrale domain install https://crm.acme.dev             # by url, via admin
@@ -103,12 +123,26 @@ Examples:
       flags: '--token <token>',
       description: 'Bearer token for private domain install endpoints (--direct only)',
     },
+    {
+      flags: '--operation <uuid>',
+      description: 'Reuse an exact direct-install operation id for explicit retry/recovery',
+    },
     {
       flags: '--allow-identity-override',
       description: 'Consent to a domain whose origin differs from its serving host (--direct only)',
     },
   ],
   action: async (target: string | undefined, opts: InstallOpts) => {
+    if (opts.operation !== undefined && !opts.direct) {
+      fatal(
+        new AstraleError(
+          'INVALID_FLAG',
+          '--operation is valid only with --direct.',
+          'Ordinary direct installs generate a fresh operation id automatically.',
+        ),
+        opts,
+      )
+    }
     if (opts.direct) {
       await installDirect(target, opts)
       return
@@ -197,8 +231,9 @@ export async function installViaAdmin(
       log.dim(`  origin: ${result.origin}`)
       log.dim(`  url:    ${result.url}`)
     })
-  } catch (e) {
-    fatal(e, opts)
+  } catch (error) {
+    await formatKernelError(error, isMachine(opts), undefined, opts.debug)
+    process.exit(1)
   }
 }
 
@@ -326,9 +361,27 @@ async function activeSlug(): Promise<string | undefined> {
  * bypassing the admin catalog, with the identity-override
  * consent gate. Works on any instance the caller can authenticate to.
  */
-async function installDirect(target: string | undefined, opts: InstallOpts): Promise<void> {
+interface DirectInstallDependencies {
+  readonly acceptOperationId: (input: unknown) => string
+  readonly createOperationId: () => string
+  readonly runKernelCommand: typeof runKernelCommand
+}
+
+const defaultDirectInstallDependencies: DirectInstallDependencies = Object.freeze({
+  acceptOperationId,
+  createOperationId,
+  runKernelCommand,
+})
+
+export async function installDirect(
+  target: string | undefined,
+  opts: InstallOpts,
+  dependencies: Partial<DirectInstallDependencies> = {},
+): Promise<void> {
+  const direct = { ...defaultDirectInstallDependencies, ...dependencies }
   let host = ''
   let consentedOrigin: string | undefined
+  let operation: string
   try {
     if (!target) {
       throw new AstraleError(
@@ -338,24 +391,30 @@ async function installDirect(target: string | undefined, opts: InstallOpts): Pro
       )
     }
     host = validateInstallUrl(target)
+    operation =
+      opts.operation === undefined
+        ? direct.createOperationId()
+        : direct.acceptOperationId(opts.operation)
     consentedOrigin = await ensureIdentityOverrideConsent(
       target,
       host,
       opts.allowIdentityOverride ?? false,
     )
   } catch (e) {
-    fatal(e)
+    fatal(e, opts)
   }
   const url = target as string
+  const retry = directInstallRetry(url, operation, opts)
 
-  await runKernelCommand<DirectInstallResult>({
+  await direct.runKernelCommand<DirectInstallResult>({
     opts,
-    label: `Installing domain from ${url}`,
+    label: `Installing domain from ${url} (operation ${operation})`,
+    recovery: { operation, retry },
     fn: async ({ session }) =>
       (await session.call(
         createPathCall(
           Path.project(syscalls.install.ref).raw,
-          directInstallCallInput(url, opts.token),
+          directInstallCallInput(url, operation, opts.token),
         ),
       )) as DirectInstallResult,
     format: (result, fmtOpts, isRaw) => {
@@ -364,11 +423,10 @@ async function installDirect(target: string | undefined, opts: InstallOpts): Pro
         return
       }
       const installed = result.transitions[0]?.intent
-      if (installed === undefined) {
-        throw new Error('Kernel install returned no committed Domain transition.')
-      }
+      if (!installed) throw new Error('Kernel install returned no committed Domain transition.')
       const revision = installed.target?.schemaRevision ?? result.operation
       log.success(`Domain installed: ${installed.origin}@${revision}`)
+      log.dim(`  operation:   ${result.operation}`)
       // Belt-and-braces: the kernel-confirmed origin is authoritative. If it
       // aliases the host and the pre-install gate never consented to THAT
       // origin (lying or absent `/meta`), say so loudly after the fact.
@@ -383,6 +441,11 @@ async function installDirect(target: string | undefined, opts: InstallOpts): Pro
   })
 }
 
+function directInstallRetry(url: string, operation: string, opts: InstallOpts): string {
+  const instance = opts.instance === undefined ? '' : ` -i ${opts.instance}`
+  return `astrale domain install ${url} --direct --operation ${operation}${instance}`
+}
+
 function validateInstallUrl(value: string): string {
   let url: URL
   try {
@@ -415,7 +478,7 @@ export function isIdentityOverride(origin: string, host: string): boolean {
  * Claiming an origin that differs from the serving host is an explicit actAs
  * and needs typed consent (or `--allow-identity-override` in scripts).
  *
- * The pre-install check reads the worker's self-reported `/meta.domainName`,
+ * The pre-install check reads the worker's self-reported `/meta.origin`,
  * so it is consent UX, not enforcement — a hostile worker can lie here, and
  * the kernel anchors the cryptographic identity (`iss`) on the real URL
  * regardless. When `/meta` is unreachable or silent on the origin, the gate
@@ -476,10 +539,11 @@ export async function probeDeclaredOrigin(url: string): Promise<string | undefin
   try {
     const res = await fetch(new URL('/meta', url), { signal: AbortSignal.timeout(10_000) })
     if (!res.ok) return undefined
-    const body = (await res.json()) as { domainName?: unknown }
-    return typeof body.domainName === 'string' && body.domainName.length > 0
-      ? body.domainName
-      : undefined
+    // SDK workers serve `origin`; `domainName` is the pre-Kernel-V2 name, kept
+    // as a fallback for workers deployed before the rename.
+    const body = (await res.json()) as { origin?: unknown; domainName?: unknown }
+    const declared = body.origin ?? body.domainName
+    return typeof declared === 'string' && declared.length > 0 ? declared : undefined
   } catch {
     // Unreachable /meta is not fatal here: the caller warns and the install
     // itself will surface a dead worker with its own error.

package/src/commands/domain/uninstall.ts

@@ -0,0 +1,128 @@
+import { Path } from '@astrale-os/sdk/graph/path'
+import { syscalls } from '@astrale-os/sdk/schema/kernel'
+import chalk from 'chalk'
+
+import type { KernelCommandOpts } from '../../connection'
+import type { CommandDefinition } from '../../program/index'
+
+import { createPathCall, runKernelCommand } from '../../connection'
+import { AstraleError } from '../../errors'
+import { fatal, log } from '../../lib/log'
+import { output } from '../../lib/output'
+import { confirmWithInput } from '../../lib/prompt'
+
+type UninstallOpts = KernelCommandOpts & {
+  readonly yes?: boolean
+  readonly ci?: boolean
+  readonly noPrompt?: boolean
+}
+
+type UninstallResult = {
+  readonly operation: string
+  readonly transition: {
+    readonly intent: {
+      readonly origin: string
+    }
+  }
+}
+
+/** Public Kernel uninstall syscall input for one installed Domain origin. */
+export function uninstallCallInput(
+  origin: string,
+  operation: string = crypto.randomUUID(),
+): Readonly<{ operation: string; origin: string }> {
+  return Object.freeze({ operation, origin })
+}
+
+export default {
+  name: 'uninstall',
+  description: 'Uninstall a domain from an instance through the public Kernel syscall',
+  afterHelpText: `
+Behavior:
+  Removes one installed Domain origin from the target instance. The Kernel
+  refuses the operation while another installed Domain depends on it or while
+  business data still uses its schema. Uninstall never deletes business data.
+  Type the exact origin to confirm, or pass --yes in automation.
+
+  Use this before reinstalling only when an immutable Domain property (such as
+  its issuer) intentionally changed. Ordinary compatible upgrades should use
+  domain install directly and preserve the existing Domain identity.
+
+Examples:
+  $ astrale domain uninstall grc.example -i staging
+  $ astrale domain uninstall grc.example -i staging --yes --json
+`,
+  arguments: [
+    {
+      name: 'origin',
+      description: 'Installed Domain origin to remove',
+      required: true,
+    },
+  ],
+  options: [
+    {
+      flags: '--yes',
+      description: 'Confirm Domain uninstall without prompting',
+    },
+  ],
+  action: async (origin: string, opts: UninstallOpts) => {
+    try {
+      await confirmUninstall(origin, opts)
+    } catch (error) {
+      fatal(error, opts)
+    }
+
+    await runKernelCommand<UninstallResult>({
+      opts,
+      label: `Uninstalling domain ${origin}`,
+      fn: async ({ session }) =>
+        (await session.call(
+          createPathCall(Path.project(syscalls.uninstall.ref).raw, uninstallCallInput(origin)),
+        )) as UninstallResult,
+      format: (result, formatOpts, machine) => {
+        if (machine) {
+          output(result, formatOpts)
+          return
+        }
+        log.success(`Domain uninstalled: ${result.transition.intent.origin}`)
+        log.dim(`  operation: ${result.operation}`)
+      },
+    })
+  },
+} satisfies CommandDefinition
+
+async function confirmUninstall(origin: string, opts: UninstallOpts): Promise<void> {
+  if (opts.yes) return
+
+  const nonInteractive =
+    opts.ci ||
+    opts.noPrompt ||
+    process.env.CI ||
+    process.argv.includes('--ci') ||
+    process.argv.includes('--no-prompt') ||
+    !process.stdin.isTTY
+  if (nonInteractive) {
+    throw new AstraleError(
+      'CONFIRMATION_REQUIRED',
+      `Uninstalling Domain "${origin}" requires explicit confirmation.`,
+      `Re-run with --yes: astrale domain uninstall ${origin} --yes`,
+    )
+  }
+
+  const warning =
+    chalk.red.bold('⚠  DANGER — DOMAIN UNINSTALL') +
+    '\n' +
+    chalk.dim('│') +
+    `  origin     ${chalk.bold(origin)}\n` +
+    chalk.dim('│') +
+    '\n' +
+    chalk.dim('│') +
+    '  This removes the installed Domain from the target instance.\n' +
+    chalk.dim('│') +
+    '  This command never deletes business data.\n' +
+    chalk.dim('│') +
+    '  The Kernel refuses removal while dependents or business data remain.'
+  if (!(await confirmWithInput(warning, origin))) {
+    throw new AstraleError('UNINSTALL_CANCELLED', `Domain uninstall cancelled for "${origin}".`)
+  }
+}

package/src/commands/instance/active.ts

@@ -19,13 +19,19 @@ export default {
       const { name } = active
       const url = active.url ?? null
       const createdAt = active.createdAt ?? null
+      const issuer = active.issuer ?? null
+      const defaultIdentity = active.defaultIdentity ?? null
+      const caFile = active.caFile ?? null
 
       if (isRaw) {
-        output({ name, url, createdAt }, opts)
+        output({ name, url, issuer, defaultIdentity, caFile, createdAt }, opts)
         return
       }
 
       console.log(`${chalk.bold(name)} (${url ?? 'local'})`)
+      if (issuer && issuer !== url) log.dim(`  issuer:   ${issuer}`)
+      if (defaultIdentity) log.dim(`  identity: ${defaultIdentity}`)
+      if (caFile) log.dim(`  ca:       ${caFile}`)
     } catch (e) {
       log.error(e instanceof Error ? e.message : String(e))
       process.exit(1)
@@ -36,6 +42,9 @@ export default {
 async function resolveActiveForDisplay(): Promise<{
   name: string
   url?: string
+  issuer?: string
+  defaultIdentity?: string
+  caFile?: string
   createdAt?: string
 }> {
   const active = await getActive()
@@ -43,6 +52,9 @@ async function resolveActiveForDisplay(): Promise<{
     return {
       name: active.name,
       url: active.url,
+      issuer: active.issuer,
+      defaultIdentity: active.defaultIdentity,
+      caFile: active.caFile,
       createdAt: active.createdAt,
     }
   }

package/src/commands/instance/bookmark.ts

@@ -1,7 +1,13 @@
 import type { CommandDefinition } from '../../program/index'
 
 import { fetchWithCaFile } from '../../lib/ca-fetch'
-import { normalizeInstanceKernelUrl, setActive, upsertInstance } from '../../lib/instance'
+import {
+  findBookmarkTrustConflicts,
+  normalizeInstanceKernelUrl,
+  readInstances,
+  setActive,
+  upsertInstance,
+} from '../../lib/instance'
 import { fatal, log } from '../../lib/log'
 import { checkIssuerReachability } from '../../lib/meta'
 
@@ -39,14 +45,27 @@ export default {
     try {
       if (!opts.url) fatal(new Error('Missing required flag: --url <url>'))
       const url = normalizeInstanceKernelUrl(opts.url)
-      const expectedIssuer = opts.issuer ? normalizeInstanceKernelUrl(opts.issuer) : undefined
+      const store = await readInstances()
+      const expectedIssuer = opts.issuer
+        ? normalizeInstanceKernelUrl(opts.issuer)
+        : store.instances[name]?.issuer
+      const effectiveCa = opts.ca ?? store.instances[name]?.caFile
+      const trustConflicts = findBookmarkTrustConflicts(store, name, url, effectiveCa)
+      if (trustConflicts.length > 0) {
+        log.warn(
+          `TLS trust differs for the same Kernel URL ${url}: ` +
+            `"${name}" uses ${describeCa(effectiveCa)}, while ${trustConflicts
+              .map((conflict) => `"${conflict.name}" uses ${describeCa(conflict.caFile)}`)
+              .join(', ')}. Remove or update stale bookmarks to avoid certificate surprises.`,
+        )
+      }
 
       if (!opts.skipProbe) {
         try {
           const { issuer, keys } = await checkIssuerReachability(
             url,
             expectedIssuer,
-            opts.ca ? fetchWithCaFile(opts.ca) : undefined,
+            effectiveCa ? fetchWithCaFile(effectiveCa) : undefined,
           )
           log.dim(`  iss=${issuer} keys=${keys.length}`)
         } catch (e) {
@@ -76,3 +95,7 @@ export default {
     }
   },
 } satisfies CommandDefinition
+
+function describeCa(caFile: string | null | undefined): string {
+  return caFile ? `CA ${caFile}` : 'the system trust store'
+}

package/src/commands/instance/list.ts

@@ -30,6 +30,7 @@ export type Bookmark = {
   issuer: string | null
   active: boolean
   defaultIdentity: string | null
+  caFile: string | null
   createdAt: string | null
 }
 
@@ -57,6 +58,7 @@ export default {
         issuer: entry.issuer ?? null,
         active: name === store.active,
         defaultIdentity: entry.defaultIdentity ?? null,
+        caFile: entry.caFile ?? null,
         createdAt: entry.createdAt ?? null,
       }))
 
@@ -111,13 +113,13 @@ export function buildInstanceRows(
   const rows: Array<Record<string, string>> = []
   const merged = new Set<string>()
 
-  const bookmarkByName = new Map<string, { url: string; active: boolean }>()
+  const bookmarkByName = new Map<string, Bookmark & { url: string }>()
   if (show.managed && show.bookmarks) {
     for (const bookmark of bookmarks) {
       if (bookmark.url === null) continue
       bookmarkByName.set(bookmark.name, {
+        ...bookmark,
         url: normalizeInstanceKernelUrl(bookmark.url),
-        active: bookmark.active,
       })
     }
   }
@@ -134,7 +136,9 @@ export function buildInstanceRows(
         name: twin?.active ? `${item.slug} ${chalk.green('*')}` : item.slug,
         kind: 'managed',
         url: item.url ?? '',
-        extra: formatInstanceLocation(item),
+        extra: [formatInstanceLocation(item), twin ? formatBookmarkConnection(twin) : '']
+          .filter(Boolean)
+          .join(' · '),
       })
     }
   }
@@ -146,7 +150,7 @@ export function buildInstanceRows(
         name: item.active ? `${item.name} ${chalk.green('*')}` : item.name,
         kind: 'bookmark',
         url: String(item.url ?? ''),
-        extra: '',
+        extra: formatBookmarkConnection(item),
       })
     }
   }
@@ -154,6 +158,16 @@ export function buildInstanceRows(
   return rows
 }
 
+function formatBookmarkConnection(bookmark: Bookmark): string {
+  return [
+    bookmark.issuer && bookmark.issuer !== bookmark.url ? `issuer=${bookmark.issuer}` : '',
+    bookmark.caFile ? `ca=${bookmark.caFile}` : '',
+    bookmark.defaultIdentity ? `identity=${bookmark.defaultIdentity}` : '',
+  ]
+    .filter(Boolean)
+    .join(' · ')
+}
+
 const ADMIN_INVENTORY_CODES = new Set([
   'TOKEN_EXCHANGE_SOURCE_INVALID',
   'TOKEN_EXCHANGE_SOURCE_EXPIRED',

package/src/commands/instance/use.ts

@@ -5,7 +5,9 @@ import { AstraleError } from '../../errors'
 import { getDefault, setDefault } from '../../identity/index'
 import { listOwnedInstances } from '../../lib/admin-instance'
 import { ADMIN_TARGET_OPTIONS } from '../../lib/admin-target'
+import { fetchWithCaFile } from '../../lib/ca-fetch'
 import {
+  findBookmarkTrustConflicts,
   getActive,
   readInstances,
   resolveInstance,
@@ -48,12 +50,8 @@ async function useInstance(name?: string, opts: UseOpts = {}): Promise<void> {
 
     const resolved = await resolveUseTarget(name, opts)
 
-    if (!opts.skipJwksCheck && resolved.issuer) {
-      try {
-        await checkIssuerReachability(resolved.url, resolved.issuer)
-      } catch (e) {
-        fatal(e)
-      }
+    if (!opts.skipJwksCheck) {
+      await probeBookmark(resolved)
     }
 
     await setActive(resolved.name)
@@ -94,6 +92,55 @@ async function useInstance(name?: string, opts: UseOpts = {}): Promise<void> {
   }
 }
 
+/** Probe with the exact TLS trust configuration stored on this bookmark. */
+export async function probeBookmark(
+  resolved: ResolvedInstance,
+  dependencies: Partial<BookmarkProbeDependencies> = {},
+): Promise<void> {
+  const probe = { ...defaultBookmarkProbeDependencies, ...dependencies }
+  const store = await probe.readInstances()
+  const conflicts = findBookmarkTrustConflicts(store, resolved.name, resolved.url, resolved.caFile)
+  try {
+    await probe.checkIssuerReachability(
+      resolved.url,
+      resolved.issuer,
+      resolved.caFile ? probe.fetchWithCaFile(resolved.caFile) : undefined,
+    )
+  } catch (cause) {
+    const original = cause instanceof AstraleError ? cause.hint : undefined
+    const trust = resolved.caFile
+      ? `Bookmark "${resolved.name}" trusts CA ${resolved.caFile}.`
+      : `Bookmark "${resolved.name}" uses the system trust store.`
+    const collision =
+      conflicts.length === 0
+        ? ''
+        : ` The same URL is bookmarked with different TLS trust as ${conflicts
+            .map((conflict) =>
+              conflict.caFile
+                ? `"${conflict.name}" (CA ${conflict.caFile})`
+                : `"${conflict.name}" (system trust)`,
+            )
+            .join(', ')}.`
+    throw new AstraleError(
+      cause instanceof AstraleError ? cause.code : 'ISSUER_UNREACHABLE',
+      `Issuer/JWKS probe failed for bookmark "${resolved.name}" at ${resolved.url}.`,
+      `${trust}${collision}${original ? ` ${original}` : ''} Inspect with \`astrale instance list --bookmarked --json\`.`,
+    )
+  }
+}
+
+interface BookmarkProbeDependencies {
+  readonly readInstances: typeof readInstances
+  readonly checkIssuerReachability: typeof checkIssuerReachability
+  readonly fetchWithCaFile: typeof fetchWithCaFile
+}
+
+const defaultBookmarkProbeDependencies: BookmarkProbeDependencies = Object.freeze({
+  readInstances,
+  checkIssuerReachability,
+  fetchWithCaFile,
+})
+
 async function resolveUseTarget(name: string, opts: UseOpts): Promise<ResolvedInstance> {
   const [store, managed] = await Promise.all([readInstances(), fetchManagedInstances(name, opts)])
   const candidates = collectInstanceCandidates(name, store, managed)
@@ -204,7 +251,7 @@ Examples:
       flags: '--adopt-default',
       description: 'Adopt instance default identity without prompt',
     },
-    { flags: '--skip-jwks-check', description: 'Skip the /meta ↔ JWKS match check' },
+    { flags: '--skip-jwks-check', description: 'Skip the OIDC discovery + JWKS liveness probe' },
   ],
   action: async (name: string | undefined, opts: UseOpts) => {
     await useInstance(name, opts)

package/src/commands/view.ts

@@ -172,22 +172,34 @@ async function findOnPath(name: string): Promise<string | null> {
 
 /** Dev checkout: (re)build the node-runnable CLI bundle when missing or stale. */
 async function ensureDevDist(entry: string, dist: string): Promise<void> {
-  const bun = (
-    globalThis as {
-      Bun?: { build: (o: object) => Promise<{ success: boolean; logs: unknown[] }> }
-    }
-  ).Bun
-  if (!bun) return
-  const srcDir = join(dirname(entry), '..', 'src')
-  if (existsSync(dist) && !(await newerThan(srcDir, statSync(dist).mtimeMs))) return
-  // stderr: --json consumers parse stdout.
-  console.error('(dev) building dist/astrale.js for the session server…')
-  await bun.build({
-    entrypoints: [entry],
-    outdir: dirname(dist),
-    target: 'node',
-    format: 'esm',
-  })
+  if (!(await devDistIsStale(entry, dist))) return
+  const projectDir = join(dirname(entry), '..')
+  const buildScript = join(projectDir, 'scripts', 'build.ts')
+  const bun = await findOnPath('bun')
+  if (!bun || !existsSync(buildScript)) return
+
+  // Build output goes to stderr so --json stdout remains valid.
+  console.error('(dev) dist/astrale.js is stale — running the official CLI build…')
+  const built = await run(bun, [buildScript], { cwd: projectDir })
+  if (built.stdout) process.stderr.write(built.stdout)
+  if (built.stderr) process.stderr.write(built.stderr)
+  if (built.code !== 0) throw new Error(`Official CLI build failed with exit code ${built.code}.`)
+}
+
+export async function devDistIsStale(entry: string, dist: string): Promise<boolean> {
+  if (!existsSync(dist)) return true
+  const projectDir = join(dirname(entry), '..')
+  const builtAt = statSync(dist).mtimeMs
+  const directories = [join(projectDir, 'src'), join(projectDir, 'bin'), join(projectDir, 'vendor')]
+  const files = [
+    join(projectDir, 'scripts', 'build.ts'),
+    join(projectDir, 'package.json'),
+    join(projectDir, 'pnpm-lock.yaml'),
+  ]
+  for (const directory of directories) {
+    if (existsSync(directory) && (await newerThan(directory, builtAt))) return true
+  }
+  return files.some((file) => existsSync(file) && statSync(file).mtimeMs > builtAt)
 }
 
 async function newerThan(dir: string, mtimeMs: number): Promise<boolean> {

package/src/connection/.spec/architecture.md

@@ -39,3 +39,8 @@ The target, timeout, and optional CA file are resolved before constructing the s
 customizes only the Fetch capability passed to Client. `withClientSession` and
 `withAdminClientSession` are terminal lifecycle boundaries: success, failure, and cancellation all
 close both the Client Session and its direct source-Auth client.
+
+The command boundary maps typed Client transport phase and delivery evidence without inspecting a
+private cause message. It preserves every admitted Kernel reason in machine output; human repair
+details are rendered only after the connection owner admits bounded public Function issues or one
+exact Query reason variant.

package/src/connection/.spec/laws/connection.ts

@@ -179,3 +179,23 @@ export const CLI_CONNECTION_PUBLIC_SEMANTIC_REASON = defineLaw({
     },
   ],
 })
+
+export const CLI_CONNECTION_TYPED_ERROR_PRESENTATION = defineLaw({
+  id: 'CLI-CONNECTION-TYPED-ERROR-PRESENTATION',
+  statement:
+    'The command boundary maps typed Client transport phase and delivery evidence without parsing a private cause, preserves the admitted Kernel reason in machine output, and renders only bounded public Function issues or one exact Query repair variant for humans.',
+  tests: [
+    {
+      file: '__tests__/errors.test.ts',
+      id: 'TEST-CLI-CONNECTION-MAPS-TYPED-TRANSPORT',
+    },
+    {
+      file: '__tests__/errors.test.ts',
+      id: 'TEST-CLI-CONNECTION-PRESENTS-BOUNDED-REPAIRS',
+    },
+    {
+      file: '__tests__/reasons.test.ts',
+      id: 'TEST-CLI-CONNECTION-ADMITS-BOUNDED-REASONS',
+    },
+  ],
+})