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

package/README.md

@@ -105,7 +105,11 @@ astrale update
 from `astrale-os/cli` is installed and healthy, and follows the beta channel by default. It reports
 whether the skill pass was unchanged, installed, updated, or repaired. Use `--check`,
 `--channel <channel>`, or `--version <version>` to control the CLI release target; skills always
-track the repository's current `main` source. `--no-skills` is the explicit opt-out.
+resolve the repository's current `main` once, verify the installed trees against that commit, and
+stamp the exact revision/tree binding into the Astrale-owned receipt. A current
+`astrale update --check --json` result includes the resolved source revision plus every shipped
+skill's Git tree and entrypoint, so runners can retain the actual loadout rather than only
+`status: current`. `--no-skills` is the explicit opt-out.
 
 ## Commands
 

package/dist/astrale.js

@@ -2578,7 +2578,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "@astrale-os/cli",
-    version: "1.0.0-beta.30",
+    version: "1.0.0-beta.31",
     description: "Astrale CLI — connect to existing Astrale kernels",
     keywords: [
       "astrale",
@@ -61700,7 +61700,7 @@ async function inspectAstraleSkills(snapshot2, home, lockPath) {
     }
   }));
   if (managed.length === 0 && expectedPresence.every((present2) => !present2)) {
-    return { state: "absent", managedNames: [], managedFolders: [] };
+    return { state: "absent", sourceCurrent: false, managedNames: [], managedFolders: [] };
   }
   const folders = managed.flatMap(([name, entry]) => {
     const folder = folderName(entry);
@@ -61742,12 +61742,17 @@ async function inspectAstraleSkills(snapshot2, home, lockPath) {
       }
     }
   }
-  const exactCurrent = coherent && managed.length === snapshot2.skills.length && folders.every(({ key, folder, entry }) => {
+  const sourceCurrent = coherent && managed.length === snapshot2.skills.length && folders.every(({ key, folder, entry }) => {
     const skill = expected.get(folder);
     return key === folder && skill !== undefined && entry.ref === snapshot2.ref && actualHashes.get(folder) === skill.tree;
   });
+  const exactCurrent = sourceCurrent && folders.every(({ folder, entry }) => {
+    const skill = expected.get(folder);
+    return skill !== undefined && entry.astraleSourceRevision === snapshot2.revision && entry.astraleSourceTree === skill.tree;
+  });
   return {
     state: exactCurrent ? "current" : coherent ? "outdated" : "unhealthy",
+    sourceCurrent,
     managedNames: managed.map(([name]) => name),
     managedFolders: [...uniqueFolders]
   };
@@ -61768,6 +61773,20 @@ function installerArgs(...args) {
 async function installSnapshot(snapshot2, execute, selectedAgents) {
   return await execute("npx", installerArgs("add", `${ASTRALE_CLI_SKILL_SOURCE}#${snapshot2.ref}`, "-g", "-y", "--skill", ...snapshot2.skills.map((skill) => skill.name), ...selectedAgents.length > 0 ? ["--agent", ...selectedAgents] : []));
 }
+async function stampAstraleSource(snapshot2, lockPath) {
+  const { lock } = await readSkillLock(lockPath);
+  if (!lock)
+    throw new Error("skill installer receipt is unavailable after installation");
+  for (const skill of snapshot2.skills) {
+    const entry = lock.skills[skill.name];
+    if (!entry || !sourceOwned(entry) || entry.ref !== snapshot2.ref || entry.skillPath !== skill.path) {
+      throw new Error(`skill installer receipt is incomplete for ${skill.name}`);
+    }
+    entry.astraleSourceRevision = snapshot2.revision;
+    entry.astraleSourceTree = skill.tree;
+  }
+  await writeSkillLock(lockPath, lock);
+}
 async function selectedAgents(home, lockPath) {
   const { lock } = await readSkillLock(lockPath);
   const agents = new Set((lock?.lastSelectedAgents ?? []).filter((agent) => typeof agent === "string" && SAFE_NAME.test(agent)));
@@ -61989,8 +62008,20 @@ async function checkAstraleSkills(overrides = {}) {
   try {
     const snapshot2 = await sourceSnapshot(dependencies);
     const inspection = await inspectAstraleSkills(snapshot2, dependencies.home, dependencies.lockPath);
+    const status = inspection.state === "current" ? "current" : inspection.state === "unhealthy" ? "repair-needed" : "update-available";
     return {
-      status: inspection.state === "current" ? "current" : inspection.state === "unhealthy" ? "repair-needed" : "update-available"
+      status,
+      ...status === "current" ? {
+        source: {
+          repository: ASTRALE_CLI_SKILL_SOURCE,
+          revision: snapshot2.revision,
+          skills: snapshot2.skills.map(({ name, tree, path: path4 }) => ({
+            name,
+            tree,
+            entrypoint: path4
+          }))
+        }
+      } : {}
     };
   } catch (error52) {
     return { status: "unavailable", error: error52 instanceof Error ? error52.message : String(error52) };
@@ -62040,6 +62071,11 @@ async function syncAstraleSkills(overrides = {}) {
               throw new Error(installed.stderr || installed.stdout || "skill installer failed");
             }
             await pruneObsoleteEntries(snapshot2, dependencies.home, dependencies.lockPath, dependencies.run, knownRetired);
+            const installedInspection = await inspectAstraleSkills(snapshot2, dependencies.home, dependencies.lockPath);
+            if (!installedInspection.sourceCurrent) {
+              throw new Error("installed Astrale skills do not match the resolved source");
+            }
+            await stampAstraleSource(snapshot2, dependencies.lockPath);
             const verified = await inspectAstraleSkills(snapshot2, dependencies.home, dependencies.lockPath);
             if (verified.state !== "current") {
               throw new Error("installed Astrale skills did not pass verification");
@@ -82689,7 +82725,7 @@ Behavior:
   script installs only — if Astrale was installed by another package manager this
   command refuses so that manager stays in charge; downloads are checksum-verified
   before the binary is replaced. (2) The Astrale agent skills: installs every
-  top-level skill published from astrale-os/cli main, updates healthy older
+  top-level skill published from one resolved astrale-os/cli main commit, updates healthy older
   installs, repairs inconsistent installs, and verifies the result before
   reporting success. (3) SDK deps: inside a pnpm domain
   project, proposes any @astrale-os/* dependency with a newer release and, on
@@ -83288,20 +83324,20 @@ var init_query5 = __esm(() => {
 function prepareQuery(input) {
   const limit = positiveInteger2(input.limit, "--limit", DEFAULT_LIMIT);
   if (input.ast !== undefined) {
-    if (input.sources.length > 0 || input.definition !== undefined || input.edge !== undefined || input.direction !== undefined) {
-      throw new TypeError("--ast/--file cannot be combined with sources, --definition, --edge, or --direction");
+    if (input.sources.length > 0 || input.class !== undefined || input.edge !== undefined || input.direction !== undefined) {
+      throw new TypeError("--ast/--file cannot be combined with sources, --class, --edge, or --direction");
     }
     return withPage(QueryAST.decode(input.ast), limit, input.cursor);
   }
-  if (input.sources.length === 0 && input.definition === undefined) {
-    throw new TypeError("query requires a Path source, --definition, or a canonical Query V6 document");
+  if (input.sources.length === 0 && input.class === undefined) {
+    throw new TypeError("query requires a Path source, --class, or a canonical Query V6 document");
   }
   if (input.direction !== undefined && input.edge === undefined) {
     throw new TypeError("--direction requires --edge");
   }
   const paths3 = input.sources.map((source2) => Path.parse(source2));
-  const definition2 = input.definition === undefined ? undefined : classReference(input.definition, "--definition");
-  const nodes = definition2 === undefined ? paths3 : [...paths3, definition2];
+  const selectedClass = input.class === undefined ? undefined : classReference(input.class, "--class");
+  const nodes = selectedClass === undefined ? paths3 : [...paths3, selectedClass];
   const query4 = Query.from({
     nodes
   });
@@ -83477,7 +83513,7 @@ async function queryCommand(sources2, opts) {
     input = {
       sources: sources2,
       ...ast === undefined ? {} : { ast },
-      definition: opts.definition,
+      class: opts.class,
       edge: opts.edge,
       direction: opts.direction,
       limit: opts.limit,
@@ -83547,7 +83583,7 @@ var init_query7 = __esm(() => {
     description: "Run one canonical Query V6 graph read",
     afterHelpText: `
 Behavior:
-  Positional Paths and --definition author a finite Query V6 read. --edge adds
+  Positional Paths and --class author a finite Query V6 read. --edge adds
   one exact Edge-Class expansion; --direction defaults to outgoing. --ast and
   --file accept a complete canonical astrale.graph.query/v6 document, including
   Property ordering and Node or Edge reference/value projections. --cursor resumes
@@ -83559,7 +83595,7 @@ Behavior:
 
 Examples:
   $ astrale query /:notes.example.dev:class.Note --limit 50
-  $ astrale query --definition /:notes.example.dev:class.Note --limit 50
+  $ astrale query --class /:notes.example.dev:class.Note --limit 50
   $ astrale query @note --edge /:notes.example.dev:class.references --direction outgoing --limit 25
   $ astrale query --file query.v6.json --cursor "$CURSOR"
 `,
@@ -83568,7 +83604,7 @@ Examples:
       { flags: "--ast <json>", description: "Canonical Query V6 JSON document" },
       { flags: "-f, --file <path>", description: "Read a canonical Query V6 document from a file" },
       {
-        flags: "--definition <path>",
+        flags: "--class <path>",
         description: "Select Nodes satisfying one exact Class"
       },
       { flags: "--edge <class>", description: "Expand one exact Edge Class" },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrale-os/cli",
-  "version": "1.0.0-beta.30",
+  "version": "1.0.0-beta.31",
   "description": "Astrale CLI — connect to existing Astrale kernels",
   "keywords": [
     "astrale",

package/src/commands/__tests__/read-commands.test.ts

@@ -195,7 +195,7 @@ describe('query command', () => {
 
     await queryCommand([], {
       json: true,
-      definition: '/:issues.astrale.ai:class.Issue',
+      class: '/:issues.astrale.ai:class.Issue',
       limit: '20',
     })
 
@@ -239,7 +239,7 @@ describe('query command', () => {
 
     await queryCommand([], {
       json: true,
-      definition: '/:issues.astrale.ai:class.Issue',
+      class: '/:issues.astrale.ai:class.Issue',
       limit: '1',
     })
 

package/src/commands/query.ts

@@ -14,7 +14,7 @@ import { isMachine, output } from '../lib/output'
 type QueryOpts = KernelCommandOpts & {
   ast?: string
   file?: string
-  definition?: string
+  class?: string
   edge?: string
   direction?: QueryDirection
   limit?: string
@@ -28,7 +28,7 @@ export async function queryCommand(sources: string[], opts: QueryOpts): Promise<
     input = {
       sources,
       ...(ast === undefined ? {} : { ast }),
-      definition: opts.definition,
+      class: opts.class,
       edge: opts.edge,
       direction: opts.direction,
       limit: opts.limit,
@@ -103,7 +103,7 @@ export default {
   description: 'Run one canonical Query V6 graph read',
   afterHelpText: `
 Behavior:
-  Positional Paths and --definition author a finite Query V6 read. --edge adds
+  Positional Paths and --class author a finite Query V6 read. --edge adds
   one exact Edge-Class expansion; --direction defaults to outgoing. --ast and
   --file accept a complete canonical astrale.graph.query/v6 document, including
   Property ordering and Node or Edge reference/value projections. --cursor resumes
@@ -115,7 +115,7 @@ Behavior:
 
 Examples:
   $ astrale query /:notes.example.dev:class.Note --limit 50
-  $ astrale query --definition /:notes.example.dev:class.Note --limit 50
+  $ astrale query --class /:notes.example.dev:class.Note --limit 50
   $ astrale query @note --edge /:notes.example.dev:class.references --direction outgoing --limit 25
   $ astrale query --file query.v6.json --cursor "$CURSOR"
 `,
@@ -124,7 +124,7 @@ Examples:
     { flags: '--ast <json>', description: 'Canonical Query V6 JSON document' },
     { flags: '-f, --file <path>', description: 'Read a canonical Query V6 document from a file' },
     {
-      flags: '--definition <path>',
+      flags: '--class <path>',
       description: 'Select Nodes satisfying one exact Class',
     },
     { flags: '--edge <class>', description: 'Expand one exact Edge Class' },

package/src/commands/update.ts

@@ -112,7 +112,8 @@ async function refreshSdkDeps(check: boolean, assumeYes = false): Promise<boolea
  * unified and NON-THROWING: an explicit package-managed result uses npm release
  * identity, while script-install failures remain script failures in `error`
  * instead of being recategorized. The SDK axis is already best-effort. Skills
- * report meaningful health/freshness states without exposing installer metadata.
+ * report meaningful health/freshness states. A current cohort also exposes its exact
+ * source revision, skill trees, and entrypoints without leaking installer-local paths.
  */
 export type StaleReport = {
   stale: boolean
@@ -237,7 +238,7 @@ Behavior:
   script installs only — if Astrale was installed by another package manager this
   command refuses so that manager stays in charge; downloads are checksum-verified
   before the binary is replaced. (2) The Astrale agent skills: installs every
-  top-level skill published from astrale-os/cli main, updates healthy older
+  top-level skill published from one resolved astrale-os/cli main commit, updates healthy older
   installs, repairs inconsistent installs, and verifies the result before
   reporting success. (3) SDK deps: inside a pnpm domain
   project, proposes any @astrale-os/* dependency with a newer release and, on

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

@@ -11,7 +11,7 @@ export function classKey(input: string, label: string): ClassKey
 /** Untrusted CLI fields used to author or admit one exact Query V6 request. */
 export interface QueryCommandInput {
   readonly sources: readonly string[]
-  readonly definition?: string
+  readonly class?: string
   readonly ast?: unknown
   readonly edge?: string
   readonly direction?: QueryDirection

package/src/graph/.spec/laws/documents.ts

@@ -1,14 +1,14 @@
 import { defineLaw } from '@astrale-os/spec/authoring'
 
-export const CLI_GRAPH_QUERY_V5 = defineLaw({
-  id: 'CLI-GRAPH-QUERY-V5',
+export const CLI_GRAPH_QUERY_V6 = defineLaw({
+  id: 'CLI-GRAPH-QUERY-V6',
   statement:
-    'CLI query input becomes exactly one canonical Query V5 document with an explicit finite limit; exact Property ordering and Node or Edge projection profiles are admitted through the canonical AST surface, while legacy versions and unsupported selector combinations fail before a Graph call.',
+    'CLI query input becomes exactly one canonical Query V6 document with an explicit finite limit; --class authors one exact Class source, exact Property ordering and Node or Edge projection profiles are admitted through the canonical AST surface, and legacy versions or unsupported selector combinations fail before a Graph call.',
   tests: [
-    { file: '__tests__/query.test.ts', id: 'TEST-CLI-GRAPH-AUTHORS-QUERY-V5' },
-    { file: '__tests__/query.test.ts', id: 'TEST-CLI-GRAPH-AUTHORS-DEFINITION-QUERY' },
-    { file: '__tests__/query.test.ts', id: 'TEST-CLI-GRAPH-ADMITS-QUERY-V5-ORDERING' },
-    { file: '__tests__/query.test.ts', id: 'TEST-CLI-GRAPH-ADMITS-QUERY-V5-PROJECTIONS' },
+    { file: '__tests__/query.test.ts', id: 'TEST-CLI-GRAPH-AUTHORS-QUERY-V6' },
+    { file: '__tests__/query.test.ts', id: 'TEST-CLI-GRAPH-AUTHORS-CLASS-QUERY' },
+    { file: '__tests__/query.test.ts', id: 'TEST-CLI-GRAPH-ADMITS-QUERY-V6-ORDERING' },
+    { file: '__tests__/query.test.ts', id: 'TEST-CLI-GRAPH-ADMITS-QUERY-V6-PROJECTIONS' },
     { file: '__tests__/query.test.ts', id: 'TEST-CLI-GRAPH-REJECTS-LEGACY-QUERY' },
   ],
 })

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

@@ -37,11 +37,11 @@ describe('prepareQuery', () => {
     })
   })
 
-  /** @evidence TEST-CLI-GRAPH-AUTHORS-DEFINITION-QUERY */
+  /** @evidence TEST-CLI-GRAPH-AUTHORS-CLASS-QUERY */
   test('authors an exact Class source without backend query text', () => {
     const prepared = prepareQuery({
       sources: [],
-      definition: '/:issues.astrale.ai:class.Issue',
+      class: '/:issues.astrale.ai:class.Issue',
       limit: '201',
     })
 
@@ -67,7 +67,7 @@ describe('prepareQuery', () => {
   test('unions positional Paths and one Class source in authored order', () => {
     const prepared = prepareQuery({
       sources: ['@note'],
-      definition: '/:issues.astrale.ai:class.Issue',
+      class: '/:issues.astrale.ai:class.Issue',
     })
 
     expect(JSON.parse(JSON.stringify(prepared.ast.source))).toEqual({
@@ -167,7 +167,14 @@ describe('prepareQuery', () => {
       prepareQuery({ sources: ['/:notes.example.dev:class.Note'], limit: 'all' }),
     ).toThrow('--limit must be a positive integer')
     expect(() =>
-      prepareQuery({ sources: [], definition: '/:notes.example.dev:view.note' }),
-    ).toThrow('--definition must be one canonical Class Path')
+      prepareQuery({
+        sources: [],
+        ast: {},
+        class: '/:notes.example.dev:class.Note',
+      }),
+    ).toThrow('--ast/--file cannot be combined with sources, --class, --edge, or --direction')
+    expect(() => prepareQuery({ sources: [], class: '/:notes.example.dev:view.note' })).toThrow(
+      '--class must be one canonical Class Path',
+    )
   })
 })

package/src/graph/query.ts

@@ -12,7 +12,7 @@ import { classReference } from './class'
 
 export interface QueryCommandInput {
   readonly sources: readonly string[]
-  readonly definition?: string
+  readonly class?: string
   readonly ast?: unknown
   readonly edge?: string
   readonly direction?: QueryDirection
@@ -27,36 +27,34 @@ export interface PreparedQuery {
 
 const DEFAULT_LIMIT = 100
 
-/** Admit canonical Query V6 or author the intentionally small Path/Definition/one-edge subset. */
+/** Admit canonical Query V6 or author the intentionally small Path/Class/one-edge subset. */
 export function prepareQuery(input: QueryCommandInput): PreparedQuery {
   const limit = positiveInteger(input.limit, '--limit', DEFAULT_LIMIT)
   if (input.ast !== undefined) {
     if (
       input.sources.length > 0 ||
-      input.definition !== undefined ||
+      input.class !== undefined ||
       input.edge !== undefined ||
       input.direction !== undefined
     ) {
       throw new TypeError(
-        '--ast/--file cannot be combined with sources, --definition, --edge, or --direction',
+        '--ast/--file cannot be combined with sources, --class, --edge, or --direction',
       )
     }
     return withPage(QueryAST.decode(input.ast), limit, input.cursor)
   }
 
-  if (input.sources.length === 0 && input.definition === undefined) {
-    throw new TypeError(
-      'query requires a Path source, --definition, or a canonical Query V6 document',
-    )
+  if (input.sources.length === 0 && input.class === undefined) {
+    throw new TypeError('query requires a Path source, --class, or a canonical Query V6 document')
   }
   if (input.direction !== undefined && input.edge === undefined) {
     throw new TypeError('--direction requires --edge')
   }
 
   const paths = input.sources.map((source) => Path.parse(source))
-  const definition =
-    input.definition === undefined ? undefined : classReference(input.definition, '--definition')
-  const nodes = definition === undefined ? paths : [...paths, definition]
+  const selectedClass =
+    input.class === undefined ? undefined : classReference(input.class, '--class')
+  const nodes = selectedClass === undefined ? paths : [...paths, selectedClass]
   const query: NodeQueryBuilder<unknown> = Query.from({
     nodes: nodes as [QueryNodeInput, ...QueryNodeInput[]],
   })

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

@@ -145,6 +145,12 @@ async function installFixture(
 ) {
   const calls: string[][] = []
   await installer(sourceRoot, snapshot, home, lockPath, calls)('npx', [])
+  const lock = await readLock(lockPath)
+  for (const skill of snapshot.skills) {
+    lock.skills[skill.name].astraleSourceRevision = snapshot.revision
+    lock.skills[skill.name].astraleSourceTree = skill.tree
+  }
+  await writeFile(lockPath, `${JSON.stringify(lock, null, 2)}\n`)
 }
 
 describe('Astrale skill reconciliation', () => {
@@ -164,9 +170,17 @@ describe('Astrale skill reconciliation', () => {
     expect(calls).toHaveLength(1)
     expect(calls[0]).toContain(`astrale-os/cli#${source.snapshot.ref}`)
     expect(requestedSkills(calls[0])).toEqual(source.snapshot.skills.map((skill) => skill.name))
-    expect(Object.keys((await readLock(target.lockPath)).skills).sort()).toEqual(
+    const installedLock = await readLock(target.lockPath)
+    expect(Object.keys(installedLock.skills).sort()).toEqual(
       source.snapshot.skills.map((skill) => skill.name).sort(),
     )
+    for (const skill of source.snapshot.skills) {
+      expect(installedLock.skills[skill.name]).toMatchObject({
+        ref: 'main',
+        astraleSourceRevision: source.snapshot.revision,
+        astraleSourceTree: skill.tree,
+      })
+    }
   })
 
   test('a coherent older cohort updates every current source skill', async () => {
@@ -398,7 +412,18 @@ describe('Astrale skill reconciliation', () => {
         lockPath: target.lockPath,
         resolveSource: async () => source.snapshot,
       }),
-    ).toEqual({ status: 'current' })
+    ).toEqual({
+      status: 'current',
+      source: {
+        repository: 'astrale-os/cli',
+        revision: source.snapshot.revision,
+        skills: source.snapshot.skills.map(({ name, tree, path }) => ({
+          name,
+          tree,
+          entrypoint: path,
+        })),
+      },
+    })
     expect(await filesystemSnapshot(target.root)).toBe(beforeCurrentCheck)
 
     await rm(join(target.home, '.agents/skills/astrale-cli'), { recursive: true, force: true })

package/src/lib/skills/sync.ts

@@ -52,6 +52,11 @@ export type SkillApplyStatus =
 export type SkillCheckResult = {
   status: SkillCheckStatus
   error?: string
+  source?: {
+    repository: typeof ASTRALE_CLI_SKILL_SOURCE
+    revision: string
+    skills: Array<{ name: string; tree: string; entrypoint: string }>
+  }
 }
 
 export type SkillApplyResult = {
@@ -70,6 +75,8 @@ type SkillLockEntry = {
   skillFolderHash?: string
   installedAt?: string
   updatedAt?: string
+  astraleSourceRevision?: string
+  astraleSourceTree?: string
 }
 
 type SkillLock = {
@@ -83,6 +90,7 @@ type SkillState = 'absent' | 'current' | 'outdated' | 'unhealthy'
 
 type SkillInspection = {
   state: SkillState
+  sourceCurrent: boolean
   managedNames: string[]
   managedFolders: string[]
 }
@@ -297,7 +305,7 @@ async function inspectAstraleSkills(
     }),
   )
   if (managed.length === 0 && expectedPresence.every((present) => !present)) {
-    return { state: 'absent', managedNames: [], managedFolders: [] }
+    return { state: 'absent', sourceCurrent: false, managedNames: [], managedFolders: [] }
   }
 
   const folders = managed.flatMap(([name, entry]) => {
@@ -348,7 +356,7 @@ async function inspectAstraleSkills(
     }
   }
 
-  const exactCurrent =
+  const sourceCurrent =
     coherent &&
     managed.length === snapshot.skills.length &&
     folders.every(({ key, folder, entry }) => {
@@ -360,9 +368,20 @@ async function inspectAstraleSkills(
         actualHashes.get(folder) === skill.tree
       )
     })
+  const exactCurrent =
+    sourceCurrent &&
+    folders.every(({ folder, entry }) => {
+      const skill = expected.get(folder)
+      return (
+        skill !== undefined &&
+        entry.astraleSourceRevision === snapshot.revision &&
+        entry.astraleSourceTree === skill.tree
+      )
+    })
 
   return {
     state: exactCurrent ? 'current' : coherent ? 'outdated' : 'unhealthy',
+    sourceCurrent,
     managedNames: managed.map(([name]) => name),
     managedFolders: [...uniqueFolders],
   }
@@ -405,6 +424,28 @@ async function installSnapshot(
   )
 }
 
+async function stampAstraleSource(
+  snapshot: AstraleSkillSourceSnapshot,
+  lockPath: string,
+): Promise<void> {
+  const { lock } = await readSkillLock(lockPath)
+  if (!lock) throw new Error('skill installer receipt is unavailable after installation')
+  for (const skill of snapshot.skills) {
+    const entry = lock.skills[skill.name]
+    if (
+      !entry ||
+      !sourceOwned(entry) ||
+      entry.ref !== snapshot.ref ||
+      entry.skillPath !== skill.path
+    ) {
+      throw new Error(`skill installer receipt is incomplete for ${skill.name}`)
+    }
+    entry.astraleSourceRevision = snapshot.revision
+    entry.astraleSourceTree = skill.tree
+  }
+  await writeSkillLock(lockPath, lock)
+}
+
 async function selectedAgents(home: string, lockPath: string): Promise<string[]> {
   const { lock } = await readSkillLock(lockPath)
   const agents = new Set(
@@ -693,13 +734,27 @@ export async function checkAstraleSkills(
       dependencies.home,
       dependencies.lockPath,
     )
+    const status =
+      inspection.state === 'current'
+        ? 'current'
+        : inspection.state === 'unhealthy'
+          ? 'repair-needed'
+          : 'update-available'
     return {
-      status:
-        inspection.state === 'current'
-          ? 'current'
-          : inspection.state === 'unhealthy'
-            ? 'repair-needed'
-            : 'update-available',
+      status,
+      ...(status === 'current'
+        ? {
+            source: {
+              repository: ASTRALE_CLI_SKILL_SOURCE,
+              revision: snapshot.revision,
+              skills: snapshot.skills.map(({ name, tree, path }) => ({
+                name,
+                tree,
+                entrypoint: path,
+              })),
+            },
+          }
+        : {}),
     }
   } catch (error) {
     return { status: 'unavailable', error: error instanceof Error ? error.message : String(error) }
@@ -768,6 +823,15 @@ export async function syncAstraleSkills(
               dependencies.run,
               knownRetired,
             )
+            const installedInspection = await inspectAstraleSkills(
+              snapshot,
+              dependencies.home,
+              dependencies.lockPath,
+            )
+            if (!installedInspection.sourceCurrent) {
+              throw new Error('installed Astrale skills do not match the resolved source')
+            }
+            await stampAstraleSource(snapshot, dependencies.lockPath)
             const verified = await inspectAstraleSkills(
               snapshot,
               dependencies.home,

package/src/program/__tests__/program.test.ts

@@ -195,7 +195,7 @@ describe('program composition', () => {
       'whoami',
     ])
     expect(createHash('sha256').update(JSON.stringify(surface)).digest('hex')).toBe(
-      '092b8f4f737740105c8baed9d01a81604711b5b2719dfcb834eeeac414732c61',
+      '91c35b18985ad8606b5f2429fd8860b020a93edccb30dfbaa74d501929a8513b',
     )
   })
 
@@ -464,13 +464,50 @@ describe('help contract — read command split', () => {
     expect(queryHelp).not.toContain('--children <json>')
     expect(queryHelp).not.toContain('--edges <json>')
     expect(queryHelp).toContain('--ast <json>')
-    expect(queryHelp).toContain('--definition <path>')
+    expect(queryHelp).toContain('--class <path>')
+    expect(queryHelp).not.toContain('--definition')
     expect(queryHelp).toContain('--edge <class>')
     expect(queryHelp).toContain('--direction <direction>')
     expect(queryHelp).toContain('--limit <n>')
     expect(queryHelp).toContain('--cursor <token>')
     expect(queryHelp).not.toContain('--cypher <query>')
   })
+
+  test('keeps the removed query --definition flag outside the parsed command surface', async () => {
+    const program = await buildProgram()
+    const query = allCommands(program).find((command) => command.name() === 'query')
+    const parsed = query?.parseOptions(['--definition', '/:notes.example.dev:class.Note'])
+
+    expect(parsed?.unknown).toContain('--definition')
+    expect(query?.options.some((option) => option.attributeName() === 'definition')).toBe(false)
+  })
+
+  test('routes query --class through Commander as the exact Class option', async () => {
+    const program = await buildProgram()
+    const query = allCommands(program).find((command) => command.name() === 'query')
+    let observed: unknown
+    query?.action((sources, options) => {
+      observed = { sources, class: options.class, limit: options.limit, json: options.json }
+    })
+
+    await program.parseAsync([
+      'node',
+      'astrale',
+      'query',
+      '--class',
+      '/:notes.example.dev:class.Note',
+      '--limit',
+      '1',
+      '--json',
+    ])
+
+    expect(observed).toEqual({
+      sources: [],
+      class: '/:notes.example.dev:class.Note',
+      limit: '1',
+      json: true,
+    })
+  })
 })
 
 describe('help contract — explicit anonymous authentication', () => {

package/studio/server/cli-consumers.test.ts

@@ -341,7 +341,7 @@ const bundle = {
 
 const queryArgs = [
   'query',
-  '--definition',
+  '--class',
   '/:issues.example.dev:class.Issue',
   '--limit',
   '201',

package/studio/server/cli.test.ts

@@ -45,7 +45,7 @@ test('machine runner uses the exact descriptor, appends json mode, and versions
   })
 
   const result = await runStudioCliJson(
-    ['query', '--definition', '/:example.dev:class.Issue'],
+    ['query', '--class', '/:example.dev:class.Issue'],
     decodeJsonObject,
   )
 
@@ -55,7 +55,7 @@ test('machine runner uses the exact descriptor, appends json mode, and versions
     exitCode: 0,
     timedOut: false,
     data: {
-      command: ['query', '--definition', '/:example.dev:class.Issue', '--json'],
+      command: ['query', '--class', '/:example.dev:class.Issue', '--json'],
     },
   })
 })

package/studio/server/views/target.ts

@@ -65,7 +65,7 @@ export async function listViewTargets(
       const result = await runAstraleJson<RawQueryResult>(
         [
           'query',
-          '--definition',
+          '--class',
           definition,
           '--limit',
           String(TARGET_LIMIT + 1),