@astrale-os/cli 0.8.1-alpha.5 → 0.8.1-alpha.7

package/src/connection/reasons.ts

@@ -0,0 +1,179 @@
+export type FunctionInputIssue = Readonly<{
+  code: string
+  path?: string
+  message: string
+}>
+
+export type QueryInputRepair =
+  | Readonly<{ phase: 'decode' | 'input'; path: string }>
+  | Readonly<{ phase: 'plan'; issue: string; path?: string }>
+  | Readonly<{
+      phase: 'limit'
+      limit: string
+      maximum: number
+      actual: number
+      path?: string
+    }>
+
+export type SchemaUpgradeDetails = {
+  readonly origin?: string
+  readonly issue?: string
+  readonly expected?: string
+  readonly actual?: string
+}
+
+const JSON_POINTER = /^(?:\/(?:[^~/]|~[01])*)*$/u
+const MAXIMUM_FUNCTION_ISSUES = 32
+const MAXIMUM_FUNCTION_ISSUE_MESSAGE_LENGTH = 512
+
+export function reasonCode(reason: unknown): string | undefined {
+  if (!record(reason) || typeof reason.code !== 'string') return undefined
+  return stableCode(reason.code) ? reason.code : undefined
+}
+
+/** Admit only bounded caller-safe Function input issues established by the Kernel. */
+export function functionInputIssues(reason: unknown): readonly FunctionInputIssue[] {
+  if (!reasonWithCode(reason, 'FUNCTION_INPUT_INVALID')) return Object.freeze([])
+  const issues = reason.details.issues
+  if (!Array.isArray(issues)) return Object.freeze([])
+  return Object.freeze(
+    issues.slice(0, MAXIMUM_FUNCTION_ISSUES).flatMap((candidate): FunctionInputIssue[] => {
+      if (
+        !record(candidate) ||
+        typeof candidate.code !== 'string' ||
+        !stableCode(candidate.code) ||
+        typeof candidate.message !== 'string' ||
+        candidate.message.length === 0 ||
+        candidate.message.length > MAXIMUM_FUNCTION_ISSUE_MESSAGE_LENGTH ||
+        candidate.message.normalize('NFC') !== candidate.message ||
+        containsControl(candidate.message) ||
+        (candidate.path !== undefined && !coordinate(candidate.path))
+      ) {
+        return []
+      }
+      return [
+        Object.freeze({
+          code: candidate.code,
+          ...(candidate.path === undefined ? {} : { path: candidate.path }),
+          message: candidate.message,
+        }),
+      ]
+    }),
+  )
+}
+
+/** Admit only public Query-input repair variants; unknown details remain machine-only. */
+export function queryInputRepair(reason: unknown): QueryInputRepair | undefined {
+  if (!reasonWithCode(reason, 'QUERY_INPUT_INVALID')) return undefined
+  const details = reason.details
+  if (details.phase === 'decode' || details.phase === 'input') {
+    if (!exact(details, ['phase', 'path']) || !coordinate(details.path)) return undefined
+    return Object.freeze({ phase: details.phase, path: details.path })
+  }
+  if (details.phase === 'plan') {
+    const fields = details.path === undefined ? ['phase', 'issue'] : ['phase', 'issue', 'path']
+    if (
+      !exact(details, fields) ||
+      typeof details.issue !== 'string' ||
+      !stableCode(details.issue) ||
+      (details.path !== undefined && !coordinate(details.path))
+    ) {
+      return undefined
+    }
+    return Object.freeze({
+      phase: 'plan',
+      issue: details.issue,
+      ...(details.path === undefined ? {} : { path: details.path }),
+    })
+  }
+  if (details.phase !== 'limit') return undefined
+  const fields =
+    details.path === undefined
+      ? ['phase', 'limit', 'maximum', 'actual']
+      : ['phase', 'limit', 'maximum', 'actual', 'path']
+  if (
+    !exact(details, fields) ||
+    typeof details.limit !== 'string' ||
+    !Number.isSafeInteger(details.maximum) ||
+    (details.maximum as number) < 0 ||
+    !Number.isSafeInteger(details.actual) ||
+    (details.actual as number) <= (details.maximum as number) ||
+    (details.path !== undefined && !coordinate(details.path))
+  ) {
+    return undefined
+  }
+  return Object.freeze({
+    phase: 'limit',
+    limit: details.limit,
+    maximum: details.maximum as number,
+    actual: details.actual as number,
+    ...(details.path === undefined ? {} : { path: details.path }),
+  })
+}
+
+/** Decode bounded recovery guidance while preserving the admitted reason itself elsewhere. */
+export function schemaUpgradeDetails(reason: unknown): SchemaUpgradeDetails | undefined {
+  if (!record(reason) || reason.code !== 'SCHEMA_UPGRADE_INCOMPATIBLE') return undefined
+  const details = record(reason.details) ? reason.details : {}
+  return {
+    ...(typeof details.origin === 'string' ? { origin: details.origin } : {}),
+    ...(typeof details.issue === 'string' ? { issue: details.issue } : {}),
+    ...(typeof details.expected === 'string' ? { expected: details.expected } : {}),
+    ...(typeof details.actual === 'string' ? { actual: details.actual } : {}),
+  }
+}
+
+export function schemaUpgradeHint(details: SchemaUpgradeDetails): string {
+  const target = details.origin ?? '<origin>'
+  const explanation =
+    details.expected !== undefined && details.actual !== undefined
+      ? 'A replacement cannot change an installed Domain issuer.'
+      : 'The replacement changes an immutable part of the installed Domain.'
+  return (
+    `${explanation} If this change is intentional, first run ` +
+    `\`astrale domain uninstall ${target}\`, then install it again. ` +
+    'The Kernel refuses uninstall while dependents or business data remain; uninstall never deletes business data.'
+  )
+}
+
+function reasonWithCode(
+  input: unknown,
+  code: string,
+): input is Readonly<{ code: string; details: Readonly<Record<string, unknown>> }> {
+  return (
+    record(input) &&
+    exact(input, ['code', 'details']) &&
+    input.code === code &&
+    record(input.details)
+  )
+}
+
+function coordinate(input: unknown): input is string {
+  return (
+    typeof input === 'string' &&
+    input.length <= 1_024 &&
+    input.normalize('NFC') === input &&
+    JSON_POINTER.test(input)
+  )
+}
+
+function stableCode(input: string): boolean {
+  return /^[A-Z][A-Z0-9_]{0,127}$/u.test(input) && input.normalize('NFC') === input
+}
+
+function containsControl(input: string): boolean {
+  for (const character of input) {
+    const point = character.codePointAt(0)!
+    if (point <= 0x1f || point === 0x7f) return true
+  }
+  return false
+}
+
+function record(input: unknown): input is Readonly<Record<string, unknown>> {
+  return input !== null && typeof input === 'object' && !Array.isArray(input)
+}
+
+function exact(input: Readonly<Record<string, unknown>>, fields: readonly string[]): boolean {
+  const actual = Object.keys(input)
+  return actual.length === fields.length && actual.every((field) => fields.includes(field))
+}

package/src/connection/session.ts

@@ -19,12 +19,20 @@ import {
 import { AstraleError } from '../errors'
 import { fetchWithCaFile } from '../lib/ca-fetch'
 import { readConfig } from '../lib/config'
+import { log } from '../lib/log'
+import { isMachine } from '../lib/output'
 import { createCliCredential, validateCredentialSelection } from './credential'
 import { resolveAdminConnectionTarget, resolveConnectionTarget } from './target'
 
 const DEFAULT_TIMEOUT_MS = 30_000
 const MAXIMUM_ROUTE_AGE_MS = 5 * 60_000
 
+function warnMissingExplicitTarget(options: ConnectionOptions, target: ConnectionTarget): void {
+  if (options.instance !== undefined || options.url !== undefined) return
+  if (!isMachine(options)) return
+  log.warn(`No -i/--url; using ${target.slug ?? target.url}`)
+}
+
 export interface ConnectionContext {
   readonly session: ClientSession
   readonly graph: GraphApi
@@ -55,6 +63,7 @@ export async function withClientSession<Value>(
   const target = await resolveConnectionTarget(options, config, {
     managed: (slug) => lookupManagedInstance(slug, options),
   })
+  warnMissingExplicitTarget(options, target)
   return runResolvedClientSession(target, timeoutMs, options, config, action, openConnection)
 }
 

package/src/connection/target.ts

@@ -17,6 +17,7 @@ export interface ConnectionOptions {
   readonly as?: string
   readonly creds?: string
   readonly anonymous?: boolean
+  readonly ci?: boolean
 }
 
 export interface AdminConnectionOptions extends ConnectionOptions {

package/src/graph/__tests__/mutation.test.ts

@@ -42,4 +42,10 @@ describe('prepareMutation', () => {
       /Legacy PatchData/,
     )
   })
+
+  test('rejects an empty operations list in CLI language', () => {
+    expect(() => prepareMutation({ preconditions: [], operations: [] })).toThrow(
+      'Mutation V3 requires at least one operation',
+    )
+  })
 })

package/src/graph/mutation.ts

@@ -9,10 +9,23 @@ export function prepareMutation(input: unknown): MutationASTValue {
       'Legacy PatchData { nodes, edges } is not Mutation V3. Author { preconditions, operations } or a canonical astrale.graph.mutation/v3 document.',
     )
   }
+  if (hasEmptyOperations(input)) {
+    throw new TypeError('Mutation V3 requires at least one operation')
+  }
   if (isCanonicalCandidate(input)) return MutationAST.decode(input)
   return MutationAST.create(input as MutationInput)
 }
 
+function hasEmptyOperations(input: unknown): boolean {
+  return (
+    input !== null &&
+    typeof input === 'object' &&
+    !Array.isArray(input) &&
+    Array.isArray((input as { operations?: unknown }).operations) &&
+    (input as { operations: unknown[] }).operations.length === 0
+  )
+}
+
 function isCanonicalCandidate(input: unknown): boolean {
   return (
     input !== null &&

package/src/identity/__tests__/registry.test.ts

@@ -49,7 +49,7 @@ describe('identity registry journey', () => {
       bobKey: boolean
     }
     expect(result.store.default).toBe('alice')
-    expect(Object.keys(result.store.identities).sort()).toEqual(['alice', 'manager', 'workos'])
+    expect(Object.keys(result.store.identities).sort()).toEqual(['alice', 'workos'])
     expect(result.store.identities.alice.registrations?.production).toEqual({
       iss: 'https://kernel.example',
       sub: 'node-alice',

package/src/identity/registry.ts

@@ -1,3 +1,4 @@
+import { AstraleError } from '../errors'
 import { persistKeypair, removeKeypair } from '../keys/index'
 import { deleteIdpSession } from '../lib/idp'
 import { validateName } from '../lib/validation'
@@ -40,8 +41,12 @@ export async function createIdentity(
       kid: generated.kid,
       issuer: options.issuer,
     }
+    const hasDefault = store.default !== '' && store.identities[store.default] !== undefined
     return {
-      next: { ...store, identities: { ...store.identities, [name]: identity } },
+      next: {
+        default: hasDefault ? store.default : name,
+        identities: { ...store.identities, [name]: identity },
+      },
       value: identity,
     }
   })
@@ -83,12 +88,14 @@ export async function setDefault(name: string): Promise<void> {
 
 export async function getDefault(): Promise<Identity & { readonly name: string }> {
   const store = await readIdentities()
-  const identity = store.identities[store.default]
-  if (!identity) {
-    throw new Error(
-      `Default identity "${store.default}" not found. Run: astrale identity create ${store.default}`,
+  if (store.default === '' || store.identities[store.default] === undefined) {
+    throw new AstraleError(
+      'NO_IDENTITY',
+      'No default identity.',
+      'Run: astrale identity create <name>',
     )
   }
+  const identity = store.identities[store.default]!
   return { ...identity, name: store.default }
 }
 

package/src/lib/__tests__/command-dx.test.ts

@@ -11,6 +11,20 @@ import { collectCommandCatalog, renderCommanderError } from '../command-dx'
 const ANSI_RE = new RegExp(String.fromCharCode(27) + '\\[[0-9;]*m', 'g')
 const stripAnsi = (s: string): string => s.replace(ANSI_RE, '')
 
+function dx(
+  program: Awaited<ReturnType<typeof buildProgram>>,
+  error: CommanderError,
+  argv: string[],
+) {
+  const rendered = JSON.parse(stripAnsi(renderCommanderError(program, error, argv))) as {
+    error: string
+    message: string
+    detail: string
+  }
+  expect(rendered.error).toBe('USAGE_ERROR')
+  return rendered
+}
+
 describe('command DX suggestions', () => {
   test('collects command paths from the registered program tree', async () => {
     const program = await buildProgram()
@@ -24,6 +38,7 @@ describe('command DX suggestions', () => {
     expect(usages).toContain('update')
     expect(usages).toContain('query [sources...]')
     expect(usages).toContain('get <target>')
+    expect(usages).toContain('introspect <target>')
     expect(usages).toContain('status')
     expect(usages).not.toContain('ls <source>')
     expect(usages).not.toContain('describe <target>')
@@ -36,13 +51,13 @@ describe('command DX suggestions', () => {
       'commander.excessArguments',
       'error: too many arguments. Expected 0 arguments but got 2.',
     )
-    const rendered = stripAnsi(renderCommanderError(program, error, ['delete', 'demo-system']))
+    const rendered = dx(program, error, ['delete', 'demo-system'])
 
-    expect(rendered).toContain('Unknown command: astrale delete demo-system')
-    expect(rendered).toContain('"delete" is available under:')
-    expect(rendered).toContain('astrale identity delete <name>')
-    expect(rendered).toContain('astrale instance delete <id>')
-    expect(rendered).not.toContain('too many arguments')
+    expect(rendered.message).toContain('Unknown command: astrale delete demo-system')
+    expect(rendered.detail).toContain('"delete" is available under:')
+    expect(rendered.detail).toContain('astrale identity delete <name>')
+    expect(rendered.detail).toContain('astrale instance delete <id>')
+    expect(rendered.detail).not.toContain('too many arguments')
   })
 
   test('points retired describe at get', async () => {
@@ -52,23 +67,23 @@ describe('command DX suggestions', () => {
       'commander.unknownCommand',
       "error: unknown command 'describe'",
     )
-    const rendered = stripAnsi(renderCommanderError(program, error, ['describe', '@note']))
+    const rendered = dx(program, error, ['describe', '@note'])
 
-    expect(rendered).toContain('Unknown command: astrale describe @note')
-    expect(rendered).toContain('astrale describe` was removed')
-    expect(rendered).toContain('astrale get <target>')
-    expect(rendered).not.toContain('Did you mean:')
+    expect(rendered.message).toContain('Unknown command: astrale describe @note')
+    expect(rendered.detail).toContain('astrale describe` was removed')
+    expect(rendered.detail).toContain('astrale get <target>')
+    expect(rendered.detail).not.toContain('Did you mean:')
   })
 
   test('points retired ls at query', async () => {
     const program = await buildProgram()
     const error = new CommanderError(1, 'commander.unknownCommand', "error: unknown command 'ls'")
-    const rendered = stripAnsi(renderCommanderError(program, error, ['ls', '@note']))
+    const rendered = dx(program, error, ['ls', '@note'])
 
-    expect(rendered).toContain('Unknown command: astrale ls @note')
-    expect(rendered).toContain('astrale ls` was removed')
-    expect(rendered).toContain('astrale query <source> --edge <class>')
-    expect(rendered).not.toContain('Did you mean:')
+    expect(rendered.message).toContain('Unknown command: astrale ls @note')
+    expect(rendered.detail).toContain('astrale ls` was removed')
+    expect(rendered.detail).toContain('astrale query <source> --edge <class>')
+    expect(rendered.detail).not.toContain('Did you mean:')
   })
 
   test('suggests nearest command for typo paths', async () => {
@@ -78,10 +93,10 @@ describe('command DX suggestions', () => {
       'commander.excessArguments',
       'error: too many arguments. Expected 0 arguments but got 2.',
     )
-    const rendered = stripAnsi(renderCommanderError(program, error, ['indetityl', 'ist']))
+    const rendered = dx(program, error, ['indetityl', 'ist'])
 
-    expect(rendered).toContain('Unknown command: astrale indetityl ist')
-    expect(rendered).toContain('Did you mean:')
-    expect(rendered).toContain('astrale identity list')
+    expect(rendered.message).toContain('Unknown command: astrale indetityl ist')
+    expect(rendered.detail).toContain('Did you mean:')
+    expect(rendered.detail).toContain('astrale identity list')
   })
 })

package/src/lib/__tests__/instance-target.test.ts

@@ -225,4 +225,21 @@ describe('isManagedInstanceNotFound: kernel InternalKernelError wrap', () => {
     expect(caught).toBeInstanceOf(AstraleError)
     expect((caught as AstraleError).code).toBe('INSTANCE_NOT_FOUND')
   })
+
+  test('maps Admin token-exchange failure to INSTANCE_NOT_FOUND', async () => {
+    const managed = async () => {
+      throw new AstraleError(
+        'TOKEN_EXCHANGE_SOURCE_INVALID',
+        'The source identity credential has no valid expiration.',
+      )
+    }
+    const opts = {
+      config: DEFAULT_CONFIG,
+      instances: { instances: {} },
+      managed,
+    } as unknown as Parameters<typeof resolveInstanceTarget>[1]
+    await expect(
+      resolveInstanceTarget({ source: 'name', name: 'ghost' }, opts),
+    ).rejects.toMatchObject({ code: 'INSTANCE_NOT_FOUND' })
+  })
 })

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

@@ -1,6 +1,11 @@
 import { describe, expect, test } from 'bun:test'
 
-import { InstanceStoreSchema, normalizeInstanceKernelUrl, sanitizeStore } from '../instance'
+import {
+  findBookmarkTrustConflicts,
+  InstanceStoreSchema,
+  normalizeInstanceKernelUrl,
+  sanitizeStore,
+} from '../instance'
 
 describe('InstanceStoreSchema', () => {
   test('parses valid store with url', () => {
@@ -134,3 +139,48 @@ describe('sanitizeStore — read must not rewrite', () => {
     expect(changed).toBe(false)
   })
 })
+
+describe('bookmark TLS trust collisions', () => {
+  test('finds the same normalized URL with a different CA configuration', () => {
+    const store = InstanceStoreSchema.parse({
+      active: 'stable',
+      instances: {
+        stable: {
+          url: 'https://local.example/kernel/',
+          caFile: '/certs/stable.pem',
+        },
+        alias: {
+          url: 'https://local.example/kernel',
+          caFile: '/certs/old.pem',
+        },
+        other: {
+          url: 'https://other.example/kernel',
+          caFile: '/certs/old.pem',
+        },
+      },
+    })
+
+    expect(
+      findBookmarkTrustConflicts(
+        store,
+        'stable',
+        'https://local.example/kernel',
+        '/certs/stable.pem',
+      ),
+    ).toEqual([{ name: 'alias', caFile: '/certs/old.pem' }])
+  })
+
+  test('treats custom CA versus system trust as a meaningful difference', () => {
+    const store = InstanceStoreSchema.parse({
+      active: 'custom',
+      instances: {
+        custom: { url: 'https://local.example', caFile: '/certs/local.pem' },
+        system: { url: 'https://local.example' },
+      },
+    })
+
+    expect(
+      findBookmarkTrustConflicts(store, 'custom', 'https://local.example', '/certs/local.pem'),
+    ).toEqual([{ name: 'system', caFile: null }])
+  })
+})

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

@@ -112,6 +112,18 @@ describe('denoise', () => {
     })
     expect(out).toEqual({ id: 'x', props: { name: 'n' } })
   })
+
+  test('strips qualified property keys whose leaf is schema', () => {
+    const out = denoise({
+      props: {
+        'kernel.astrale.ai:class.Domain.property.schema': { huge: true },
+        'kernel.astrale.ai:class.Domain.property.origin': 'kernel.astrale.ai',
+      },
+    })
+    expect(out).toEqual({
+      props: { 'kernel.astrale.ai:class.Domain.property.origin': 'kernel.astrale.ai' },
+    })
+  })
 })
 
 describe('presentList', () => {

package/src/lib/__tests__/view-assets.test.ts

@@ -1,5 +1,14 @@
 import { afterEach, describe, expect, test } from 'bun:test'
-import { mkdtemp, mkdir, readFile, realpath, rm, symlink, writeFile } from 'node:fs/promises'
+import {
+  mkdtemp,
+  mkdir,
+  readFile,
+  realpath,
+  rm,
+  symlink,
+  utimes,
+  writeFile,
+} from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { dirname, join, relative } from 'node:path'
 import { pathToFileURL } from 'node:url'
@@ -61,6 +70,29 @@ describe('viewer asset resolution', () => {
     expect(await readFile(join(dist, 'main.js'), 'utf8')).toContain('viewer ready')
   })
 
+  test('rebuilds stale viewer assets in a source checkout', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'astrale-view-stale-'))
+    temporaryDirectories.push(root)
+    const module = join(root, 'src', 'lib', 'view', 'assets.ts')
+    const source = join(root, 'viewer')
+    const dist = join(source, 'dist')
+
+    await mkdir(dirname(module), { recursive: true })
+    await mkdir(dist, { recursive: true })
+    await writeFile(module, '')
+    await writeFile(join(source, 'main.ts'), 'document.body.textContent = "fresh viewer"\n')
+    await writeFile(join(source, 'index.html'), '<!doctype html><body>fresh</body>\n')
+    await writeFile(join(dist, 'main.js'), 'document.body.textContent = "stale viewer"\n')
+    await writeFile(join(dist, 'index.html'), '<!doctype html><body>stale</body>\n')
+    const future = new Date(Date.now() + 2_000)
+    await utimes(join(source, 'main.ts'), future, future)
+
+    await ensureViewerAssets(pathToFileURL(module).href, join(root, 'bin', 'astrale'))
+
+    expect(await readFile(join(dist, 'main.js'), 'utf8')).toContain('fresh viewer')
+    expect(await readFile(join(dist, 'index.html'), 'utf8')).toContain('fresh')
+  })
+
   test('uses the bundled module location when invoked through a global bin symlink', async () => {
     const root = await mkdtemp(join(tmpdir(), 'astrale-view-bundle-'))
     temporaryDirectories.push(root)

package/src/lib/__tests__/view-server.test.ts

@@ -0,0 +1,68 @@
+import { describe, expect, test } from 'bun:test'
+import { once } from 'node:events'
+
+import type { ViewServeConfig } from '../view/session'
+
+import { findFreePort } from '../port'
+import { startViewServer } from '../view/server'
+
+const digest = (character: string) => `sha256:${character.repeat(64)}` as const
+const target = (value: string) => value as ViewServeConfig['session']['view']['target']
+const issuer = (value: string) => value as ViewServeConfig['session']['view']['route']['issuer']
+const revision = (character: string) =>
+  digest(character) as ViewServeConfig['session']['view']['route']['revision']
+
+describe('view session server credentials', () => {
+  /** @evidence TEST-CLI-PLAIN-VIEW-RECEIVES-NO-CREDENTIAL */
+  test('refuses to mint a token for a handshake-none View', async () => {
+    const nonce = 'plain-view'
+    const port = await findFreePort(48_000, 200)
+    if (port === null) throw new Error('test port window exhausted')
+    const config = {
+      session: {
+        id: 'v-plain',
+        pid: 0,
+        port,
+        nonce,
+        pageUrl: `http://127.0.0.1:${port}/`,
+        view: {
+          target: target('/:example.test'),
+          route: {
+            key: 'example.test:view.public',
+            declaration: { target: { kind: 'domain' }, auth: 'required' },
+            href: 'https://example.test/ui/public',
+            handshake: 'none',
+            issuer: issuer('https://example.test'),
+            etag: digest('a'),
+            revision: revision('b'),
+          },
+        },
+        createdAt: '2026-08-20T00:00:00.000Z',
+      },
+      kernel: { creds: 'must-not-be-used' },
+      proxy: {
+        kernelUrl: 'https://kernel.test',
+        issuer: 'https://kernel.test',
+        direct: true,
+      },
+      idleMs: 60_000,
+    } satisfies ViewServeConfig
+    const server = startViewServer(config)
+    await once(server, 'listening')
+
+    try {
+      const response = await fetch(`http://127.0.0.1:${port}/s/${nonce}/token`, {
+        method: 'POST',
+      })
+
+      expect(response.status).toBe(403)
+      expect(await response.json()).toEqual({
+        error: 'plain views have no Astrale credential privilege',
+      })
+    } finally {
+      await new Promise<void>((resolve, reject) => {
+        server.close((error) => (error ? reject(error) : resolve()))
+      })
+    }
+  })
+})

package/src/lib/ca-fetch.ts

@@ -3,6 +3,7 @@ import type { IncomingHttpHeaders, request as httpRequest } from 'node:http'
 import { Buffer } from 'node:buffer'
 import { readFileSync } from 'node:fs'
 import { request as httpsRequest } from 'node:https'
+import { rootCertificates } from 'node:tls'
 
 /** Create a Fetch capability whose HTTPS requests trust one CLI-selected CA file. */
 export function fetchWithCaFile(
@@ -32,7 +33,9 @@ function fetchWithNode(url: URL, init: RequestInit | undefined, ca: Buffer): Pro
       {
         method: init?.method ?? 'GET',
         headers: headersInitToRecord(init?.headers),
-        ca,
+        // `ca` replaces Node's default trust set. Retain public roots because one
+        // Client Session may reach both a private Kernel and a public Domain issuer.
+        ca: [...rootCertificates, ca],
       },
       (response) => {
         const chunks: Buffer[] = []
@@ -40,8 +43,11 @@ function fetchWithNode(url: URL, init: RequestInit | undefined, ca: Buffer): Pro
           chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)),
         )
         response.on('end', () => {
-          const result = new Response(Buffer.concat(chunks), {
-            status: response.statusCode ?? 0,
+          const status = response.statusCode ?? 0
+          const body =
+            status === 204 || status === 205 || status === 304 ? null : Buffer.concat(chunks)
+          const result = new Response(body, {
+            status,
             statusText: response.statusMessage,
             headers: responseHeaders(response.headers),
           })