@astrale-os/cli 1.0.0-beta.0 → 1.0.0-beta.2

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

@@ -1,8 +1,12 @@
-import { describe, expect, test } from 'bun:test'
+import { defineDomain } from '@astrale-os/sdk'
+import { issuer } from '@astrale-os/sdk/auth'
+import { createDeployment } from '@astrale-os/sdk/deployment'
+import { defineSchema } from '@astrale-os/sdk/schema/v1'
+import { afterAll, describe, expect, test } from 'bun:test'
 
 import type { DomainInfo } from '../../lib/admin-domain'
 
-import { byDefaultThenName, domainProjection, type DomainRow } from '../domain/list'
+import { byDefaultThenName, domainProjection, probe, type DomainRow } from '../domain/list'
 
 const strip = (s: string): string => s.replace(/\[[0-9;]*m/g, '')
 
@@ -68,7 +72,82 @@ describe('domain list — projection', () => {
     const live: DomainRow = { ...base, reachable: true, checkError: null }
     expect(strip(domainProjection([live]).rows[0].status)).toBe('● live')
 
-    const down: DomainRow = { ...base, reachable: false, checkError: 'meta HTTP 502' }
-    expect(strip(domainProjection([down]).rows[0].status)).toBe('○ meta HTTP 502')
+    const down: DomainRow = { ...base, reachable: false, checkError: 'Publication HTTP 502' }
+    expect(strip(domainProjection([down]).rows[0].status)).toBe('○ Publication HTTP 502')
+  })
+})
+
+describe('domain list — canonical Publication check', () => {
+  const servers: { stop(): void }[] = []
+  afterAll(() => {
+    for (const server of servers) server.stop()
+  })
+
+  test('reports the admitted schema revision in machine data', async () => {
+    const schema = defineSchema('catalog-check.example.dev', {})
+    const definition = defineDomain({
+      schema,
+      handlers: { functions: {}, classes: {}, interfaces: {} },
+    })
+    const deployed = createDeployment({
+      definition,
+      issuer: issuer.accept('https://catalog-check.example.dev'),
+      bundleHref: 'https://catalog-check.example.dev/domain.bundle.json',
+      bindings: { callables: [] },
+    }).publication
+    const server = Bun.serve({
+      port: 0,
+      fetch(request) {
+        return new URL(request.url).pathname === '/.well-known/astrale/domain.json'
+          ? Response.json(deployed)
+          : new Response('not found', { status: 404 })
+      },
+    })
+    servers.push(server)
+
+    await expect(
+      probe(
+        entry({
+          origin: schema.origin,
+          url: `http://localhost:${server.port}`,
+        }),
+      ),
+    ).resolves.toMatchObject({
+      reachable: true,
+      schemaRevision: definition.domain.$.revision,
+      checkError: null,
+    })
+  })
+
+  test('rejects a Publication whose origin differs from the catalog entry', async () => {
+    const schema = defineSchema('deployed.example.dev', {})
+    const definition = defineDomain({
+      schema,
+      handlers: { functions: {}, classes: {}, interfaces: {} },
+    })
+    const deployed = createDeployment({
+      definition,
+      issuer: issuer.accept('https://deployed.example.dev'),
+      bundleHref: 'https://deployed.example.dev/domain.bundle.json',
+      bindings: { callables: [] },
+    }).publication
+    const server = Bun.serve({
+      port: 0,
+      fetch: () => Response.json(deployed),
+    })
+    servers.push(server)
+
+    await expect(
+      probe(
+        entry({
+          origin: 'catalog.example.dev',
+          url: `http://localhost:${server.port}`,
+        }),
+      ),
+    ).resolves.toMatchObject({
+      reachable: false,
+      checkError:
+        'Domain origin mismatch: deployed=deployed.example.dev expected=catalog.example.dev',
+    })
   })
 })

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

@@ -1,3 +1,7 @@
+import { defineDomain } from '@astrale-os/sdk'
+import { issuer } from '@astrale-os/sdk/auth'
+import { createDeployment } from '@astrale-os/sdk/deployment'
+import { defineSchema } from '@astrale-os/sdk/schema/v1'
 import { afterAll, describe, expect, test } from 'bun:test'
 
 import { domainRefFromTarget, isIdentityOverride, probeDeclaredOrigin } from '../domain/install'
@@ -29,46 +33,53 @@ describe('identity-override detection', () => {
   })
 })
 
-describe('declared-origin probe (/meta)', () => {
+describe('declared-origin Publication probe', () => {
   const servers: { stop(): void }[] = []
   afterAll(() => {
     for (const s of servers) s.stop()
   })
 
-  function serveMeta(handler: (req: Request) => Response): string {
+  function servePublication(handler: (req: Request) => Response): string {
     const server = Bun.serve({ port: 0, fetch: handler })
     servers.push(server)
     return `http://localhost:${server.port}`
   }
 
-  test('reads origin from a well-formed /meta', async () => {
-    // The exact shape SDK workers serve (adapter-cloudflare worker `/meta`).
-    const url = serveMeta((req) =>
-      new URL(req.url).pathname === '/meta'
-        ? Response.json({
-            origin: 'crm.acme.dev',
-            issuer: 'https://crm.acme.dev',
-            schemaRevision: 'sha256:abc',
-            deploymentVersion: 'v1',
-          })
+  test('reads origin from a well-formed canonical Publication', async () => {
+    const schema = defineSchema('crm.acme.dev', {})
+    const definition = defineDomain({
+      schema,
+      handlers: { functions: {}, classes: {}, interfaces: {} },
+    })
+    const deployed = createDeployment({
+      definition,
+      issuer: issuer.accept('https://crm.acme.dev'),
+      bundleHref: 'https://crm.acme.dev/domain.bundle.json',
+      bindings: { callables: [] },
+    }).publication
+    const url = servePublication((req) =>
+      new URL(req.url).pathname === '/.well-known/astrale/domain.json'
+        ? Response.json(deployed)
         : new Response('nope', { status: 404 }),
     )
     expect(await probeDeclaredOrigin(url)).toBe('crm.acme.dev')
   })
 
-  test('falls back to the pre-Kernel-V2 domainName field', async () => {
-    const legacy = serveMeta(() => Response.json({ iss: 'https://x', domainName: 'crm.acme.dev' }))
-    expect(await probeDeclaredOrigin(legacy)).toBe('crm.acme.dev')
+  test('does not accept the removed pre-Kernel-V2 domainName shape', async () => {
+    const legacy = servePublication(() =>
+      Response.json({ iss: 'https://x', domainName: 'crm.acme.dev' }),
+    )
+    expect(await probeDeclaredOrigin(legacy)).toBeUndefined()
   })
 
-  test('degrades to undefined on missing origin, non-200, bad JSON, or dead host', async () => {
-    const noName = serveMeta(() => Response.json({ iss: 'https://x' }))
+  test('degrades to undefined on invalid Publication, non-200, bad JSON, or dead host', async () => {
+    const noName = servePublication(() => Response.json({ iss: 'https://x' }))
     expect(await probeDeclaredOrigin(noName)).toBeUndefined()
 
-    const error = serveMeta(() => new Response('boom', { status: 500 }))
+    const error = servePublication(() => new Response('boom', { status: 500 }))
     expect(await probeDeclaredOrigin(error)).toBeUndefined()
 
-    const badJson = serveMeta(() => new Response('<html>', { status: 200 }))
+    const badJson = servePublication(() => new Response('<html>', { status: 200 }))
     expect(await probeDeclaredOrigin(badJson)).toBeUndefined()
 
     expect(await probeDeclaredOrigin('http://127.0.0.1:1')).toBeUndefined()

package/src/commands/__tests__/studio-descriptor.test.ts

@@ -0,0 +1,22 @@
+import { expect, test } from 'bun:test'
+import { realpathSync } from 'node:fs'
+
+import { encodeStudioCliDescriptor } from '../studio'
+
+test('Studio descriptor preserves the exact runtime and script entrypoint', () => {
+  expect(JSON.parse(encodeStudioCliDescriptor(process.execPath, import.meta.path))).toEqual({
+    version: 1,
+    executable: process.execPath,
+    args: [realpathSync(import.meta.path)],
+  })
+})
+
+test('Studio descriptor reinvokes a compiled executable without its virtual bunfs entry', () => {
+  expect(JSON.parse(encodeStudioCliDescriptor('/opt/bin/astrale', '/$bunfs/root/astrale'))).toEqual(
+    {
+      version: 1,
+      executable: '/opt/bin/astrale',
+      args: [],
+    },
+  )
+})

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

@@ -0,0 +1,73 @@
+import { describe, expect, mock, test } from 'bun:test'
+
+import { cliStale, fetchNpmTargetVersion } from '../update'
+
+describe('CLI update staleness', () => {
+  test('trusts the release manifest for a script install without consulting npm latest', async () => {
+    const fetchPackageVersion = mock(async () => '0.8.1-alpha.7')
+    const result = await cliStale(
+      {},
+      {
+        update: async ({ channel }) => {
+          expect(channel).toBe('beta')
+          return {
+            status: 'up-to-date',
+            currentVersion: '1.0.0-beta.0',
+            latestVersion: '1.0.0-beta.0',
+            channel: 'beta',
+          }
+        },
+        fetchPackageVersion,
+      },
+    )
+
+    expect(result).toEqual({
+      stale: false,
+      managed: false,
+      current: '1.0.0-beta.0',
+      latest: '1.0.0-beta.0',
+      channel: 'beta',
+    })
+    expect(fetchPackageVersion).not.toHaveBeenCalled()
+  })
+
+  test('uses an explicit npm dist-tag only for package-managed installs', async () => {
+    const result = await cliStale(
+      { channel: 'canary' },
+      {
+        update: async () => {
+          throw new Error('package managed')
+        },
+        fetchPackageVersion: async ({ channel }) => {
+          expect(channel).toBe('canary')
+          return '1.0.0-canary.0'
+        },
+      },
+    )
+
+    expect(result).toMatchObject({
+      managed: true,
+      latest: '1.0.0-canary.0',
+      channel: 'npm',
+    })
+  })
+
+  test('maps the default to beta and the stable channel to npm latest', async () => {
+    const originalFetch = globalThis.fetch
+    const fetchMock = mock(async (input: RequestInfo | URL) => {
+      const target = String(input).split('/').at(-1)
+      return Response.json({ version: target === 'beta' ? '1.0.0-beta.0' : '1.0.0' })
+    })
+    globalThis.fetch = fetchMock as unknown as typeof fetch
+    try {
+      expect(await fetchNpmTargetVersion({})).toBe('1.0.0-beta.0')
+      expect(await fetchNpmTargetVersion({ channel: 'stable' })).toBe('1.0.0')
+      expect(fetchMock.mock.calls.map(([input]) => String(input))).toEqual([
+        'https://registry.npmjs.org/@astrale-os/cli/beta',
+        'https://registry.npmjs.org/@astrale-os/cli/latest',
+      ])
+    } finally {
+      globalThis.fetch = originalFetch
+    }
+  })
+})

package/src/commands/domain/install.ts

@@ -15,6 +15,7 @@ import {
 } from '../../lib/admin-domain'
 import { listOwnedInstancesInContext, type OwnedInstanceInfo } from '../../lib/admin-instance'
 import { ADMIN_TARGET_OPTIONS, type AdminTargetCommandOpts } from '../../lib/admin-target'
+import { fetchDomainPublication } from '../../lib/domain-publication'
 import { getActive } from '../../lib/instance'
 import { fatal, log, withSpinner } from '../../lib/log'
 import { isMachine, output } from '../../lib/output'
@@ -429,11 +430,11 @@ export async function installDirect(
       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.
+      // origin (lying or unavailable Publication), say so loudly after the fact.
       if (isIdentityOverride(installed.origin, host) && installed.origin !== consentedOrigin) {
         log.warn(
           `Installed origin "${installed.origin}" differs from the serving host "${host}" ` +
-            `and was not confirmed before install (the worker's /meta did not declare it). ` +
+            `and was not confirmed before install (the worker Publication was unavailable). ` +
             `Every ${installed.origin}/* call on this instance now routes to ${host}.`,
         )
       }
@@ -478,10 +479,10 @@ 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.origin`,
+ * The pre-install check reads the worker's canonical Publication 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
+ * regardless. When the Publication is unreachable or invalid, the gate
  * degrades to a warning and the kernel-confirmed origin is re-checked after
  * install (see `format` above).
  *
@@ -496,7 +497,8 @@ async function ensureIdentityOverrideConsent(
   const origin = await probeDeclaredOrigin(url)
   if (origin === undefined) {
     log.warn(
-      `Could not read a declared origin from ${new URL('/meta', url).href} — ` +
+      `Could not read a declared origin from ` +
+        `${new URL('/.well-known/astrale/domain.json', url).href} — ` +
         `skipping the pre-install identity check (the installed origin is verified after install).`,
     )
     return undefined
@@ -534,19 +536,13 @@ async function ensureIdentityOverrideConsent(
   return origin
 }
 
-/** Best-effort read of the worker's declared origin from its `/meta` probe. */
+/** Best-effort read of the worker's origin from its admitted canonical Publication. */
 export async function probeDeclaredOrigin(url: string): Promise<string | undefined> {
   try {
-    const res = await fetch(new URL('/meta', url), { signal: AbortSignal.timeout(10_000) })
-    if (!res.ok) return 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
+    return (await fetchDomainPublication(url, AbortSignal.timeout(10_000))).origin
   } catch {
-    // Unreachable /meta is not fatal here: the caller warns and the install
-    // itself will surface a dead worker with its own error.
+    // An unreachable or invalid Publication is not fatal here: the caller warns
+    // and the install itself will surface a dead worker with its own error.
     return undefined
   }
 }

package/src/commands/domain/list.ts

@@ -6,6 +6,7 @@ import type { CommandDefinition } from '../../program/index'
 
 import { listAdminDomains, type DomainInfo } from '../../lib/admin-domain'
 import { ADMIN_TARGET_OPTIONS, type AdminTargetCommandOpts } from '../../lib/admin-target'
+import { fetchDomainPublication } from '../../lib/domain-publication'
 import { fatal, withSpinner } from '../../lib/log'
 import { isMachine, presentList } from '../../lib/output'
 
@@ -23,7 +24,7 @@ type ListOpts = KernelCommandOpts &
 /** A catalog entry, optionally enriched with a live `--check` probe. */
 export type DomainRow = DomainInfo & {
   reachable?: boolean
-  schemaHash?: string
+  schemaRevision?: string
   checkError?: string | null
 }
 
@@ -73,8 +74,8 @@ Behavior:
   one install URL per line (pipeable into \`domain install\`); --count prints
   only the number. --default-only keeps the install-by-default entries (what
   every new instance gets via alphaCreate). --check probes each published URL's
-  /meta and adds a live/unreachable STATUS column (+ reachable/schemaHash in
-  machine output).
+  canonical Publication and adds a live/unreachable STATUS column
+  (+ reachable/schemaRevision in machine output).
 
   The admin kernel is selected like every admin op — the configured default,
   or --admin <bookmark> / --admin-url <url>.
@@ -87,7 +88,10 @@ Examples:
 `,
   options: [
     ...ADMIN_TARGET_OPTIONS,
-    { flags: '--check', description: "Probe each domain's URL for reachability + schema hash" },
+    {
+      flags: '--check',
+      description: "Probe each domain's canonical Publication + schema revision",
+    },
     { flags: '--default-only', description: 'Only show install-by-default domains' },
     { flags: '-q, --quiet', description: 'One install URL per line (unix-pipeable)' },
     { flags: '--count', description: 'Print only the number of published domains' },
@@ -103,7 +107,7 @@ Examples:
           const filtered = opts.defaultOnly ? list.filter((d) => d.installByDefault) : list
           filtered.sort(byDefaultThenName)
           if (!opts.check) return filtered as DomainRow[]
-          // Reachability is a direct client-side /meta fetch per entry, in
+          // Reachability is a direct client-side Publication fetch per entry, in
           // parallel — no admin round-trip, and version-independent of the
           // admin worker (mirrors `domain install`'s probeDeclaredOrigin).
           return Promise.all(filtered.map(probe))
@@ -129,19 +133,20 @@ export function byDefaultThenName(a: DomainInfo, b: DomainInfo): number {
 
 /**
  * Enrich one entry with a reachability probe: fetch the published worker's
- * `/meta` (the same endpoint the admin `DomainEntry.check` hits) and read its
- * schema hash. A dead / missing url is itself a result, not a throw.
+ * canonical Publication and read its schema revision. A dead or missing URL is
+ * itself a result, not a throw.
  */
-async function probe(d: DomainInfo): Promise<DomainRow> {
+export async function probe(d: DomainInfo): Promise<DomainRow> {
   if (!d.url) return { ...d, reachable: false, checkError: 'no url published' }
   try {
-    const res = await fetch(new URL('/meta', d.url), { signal: AbortSignal.timeout(10_000) })
-    if (!res.ok) return { ...d, reachable: false, checkError: `meta HTTP ${res.status}` }
-    const meta = (await res.json()) as { schemaHash?: unknown }
+    const deployed = await fetchDomainPublication(d.url, AbortSignal.timeout(10_000))
+    if (deployed.origin !== d.origin) {
+      throw new Error(`Domain origin mismatch: deployed=${deployed.origin} expected=${d.origin}`)
+    }
     return {
       ...d,
       reachable: true,
-      ...(typeof meta.schemaHash === 'string' ? { schemaHash: meta.schemaHash } : {}),
+      schemaRevision: deployed.schema.revision,
       checkError: null,
     }
   } catch (err) {

package/src/commands/studio.ts

@@ -25,6 +25,23 @@ type StudioOpts = RawOutputOpts & {
 const STUDIO_PORT_BASE = 4319
 const VITE_PORT_BASE = 5273
 const PORT_SPAN = 20
+const STUDIO_CLI_DESCRIPTOR_ENV = 'DOMAIN_STUDIO_CLI_DESCRIPTOR'
+
+/**
+ * Describe this exact CLI invocation for the Studio server. A source/published
+ * script needs its entrypoint after node/bun; a Bun-compiled executable is
+ * self-contained and therefore has no prefix argument.
+ */
+export function encodeStudioCliDescriptor(
+  executable = process.execPath,
+  entry = process.argv[1],
+): string {
+  const args =
+    entry && entry !== executable && !entry.startsWith('/$bunfs') && existsSync(entry)
+      ? [realpathSync(entry)]
+      : []
+  return JSON.stringify({ version: 1, executable, args })
+}
 
 /**
  * Locate the studio package shipped with / alongside the CLI. Anchored to the
@@ -217,6 +234,7 @@ Examples:
         log.dim(`  using ASTRALE_STUDIO_DIR=${studioDir}`)
       }
       await ensureBun()
+      const cliDescriptor = encodeStudioCliDescriptor()
 
       // Default to PROD — serve the prebuilt client. It always renders, is what a
       // published/global install runs, and avoids dev's heavy source-module graph.
@@ -342,6 +360,7 @@ Examples:
                 VITE_URL: `http://127.0.0.1:${vitePort}`,
                 PORT: String(studioPort),
                 DOMAIN_STUDIO_HOST: '127.0.0.1',
+                [STUDIO_CLI_DESCRIPTOR_ENV]: cliDescriptor,
                 ...(opts.harness ? { DOMAIN_STUDIO_HARNESS: opts.harness } : {}),
               },
             },
@@ -367,6 +386,7 @@ Examples:
                 DOMAIN_STUDIO_DIST: dist,
                 PORT: String(studioPort),
                 DOMAIN_STUDIO_HOST: '127.0.0.1',
+                [STUDIO_CLI_DESCRIPTOR_ENV]: cliDescriptor,
                 ...(opts.harness ? { DOMAIN_STUDIO_HARNESS: opts.harness } : {}),
               },
             },

package/src/commands/update.ts

@@ -12,7 +12,7 @@ import {
   type SdkOutdated,
 } from '../lib/sdk-deps'
 import { ASTRALE_CLI_SKILL, detectSkill, installSkills, SKILL_INSTALL_HINT } from '../lib/skills'
-import { updateAstrale } from '../lib/update'
+import { DEFAULT_UPDATE_CHANNEL, updateAstrale } from '../lib/update'
 
 type UpdateOpts = RawOutputOpts & {
   check?: boolean
@@ -115,27 +115,47 @@ export type StaleReport = {
   sdk: { stale: boolean; inProject: boolean; outdated: SdkOutdated[] }
 }
 
-async function cliStale(opts: UpdateOpts): Promise<StaleReport['cli']> {
+type CliStaleDependencies = {
+  update: typeof updateAstrale
+  fetchPackageVersion: (opts: Pick<UpdateOpts, 'channel' | 'version'>) => Promise<string>
+}
+
+const CLI_STALE_DEPENDENCIES: CliStaleDependencies = {
+  update: updateAstrale,
+  fetchPackageVersion: fetchNpmTargetVersion,
+}
+
+export async function cliStale(
+  opts: Pick<UpdateOpts, 'channel' | 'version'>,
+  dependencies: CliStaleDependencies = CLI_STALE_DEPENDENCIES,
+): Promise<StaleReport['cli']> {
   const running = pkg.version
-  const latest = await fetchNpmLatestVersion().catch(() => undefined)
+  const target = { ...opts, channel: opts.channel ?? DEFAULT_UPDATE_CHANNEL }
   try {
-    const r = await updateAstrale({
+    const r = await dependencies.update({
       check: true,
-      channel: opts.channel,
-      version: opts.version,
+      channel: target.channel,
+      version: target.version,
       currentVersion: running,
     })
     if (r.status === 'updated') {
-      return { stale: false, managed: false, current: running, latest: latest ?? running }
+      return {
+        stale: false,
+        managed: false,
+        current: r.currentVersion,
+        latest: r.currentVersion,
+        channel: r.channel,
+      }
     }
     return {
-      stale: latest !== undefined ? latest !== running : r.status === 'available',
+      stale: r.status === 'available',
       managed: false,
-      current: running,
-      latest: latest ?? r.latestVersion,
-      channel: latest !== undefined ? 'npm' : r.channel,
+      current: r.currentVersion,
+      latest: r.latestVersion,
+      channel: r.channel,
     }
   } catch {
+    const latest = await dependencies.fetchPackageVersion(target).catch(() => undefined)
     return {
       stale: latest !== undefined && latest !== running,
       managed: true,
@@ -145,8 +165,12 @@ async function cliStale(opts: UpdateOpts): Promise<StaleReport['cli']> {
   }
 }
 
-async function fetchNpmLatestVersion(): Promise<string> {
-  const response = await fetch('https://registry.npmjs.org/@astrale-os/cli/latest')
+export async function fetchNpmTargetVersion(
+  opts: Pick<UpdateOpts, 'channel' | 'version'>,
+): Promise<string> {
+  const channel = opts.channel ?? DEFAULT_UPDATE_CHANNEL
+  const target = opts.version ?? (channel === 'stable' ? 'latest' : channel)
+  const response = await fetch(`https://registry.npmjs.org/@astrale-os/cli/${target}`)
   if (!response.ok) throw new Error(`npm registry HTTP ${response.status}`)
   const body: unknown = await response.json()
   if (
@@ -175,6 +199,7 @@ export default {
     {
       flags: '--channel <name>',
       description: 'Update from a release channel (alpha, beta, rc, canary, stable)',
+      default: DEFAULT_UPDATE_CHANNEL,
     },
     { flags: '--version <version>', description: 'Update to an exact version tag' },
     { flags: '--no-skills', description: 'Skip refreshing the astrale agent skills' },
@@ -199,6 +224,7 @@ Behavior:
   the lockfile, honoring your registry + supply-chain age policy; run "pnpm
   install" to materialize).
 
+  The default release channel is beta; --channel overrides it for one run.
   --check is a dry run (binary + SDK deps; exit 10 if anything is available) and
   never writes. With --json it emits a unified staleness report
   ({ stale, cli, sdk }) for tooling — non-throwing, skills omitted (they ride