@agentxm/workspace-state 0.30.1 → 0.30.2

package/dist/src/index.d.ts

@@ -22,6 +22,7 @@ export { SETTINGS_KNOWN_KEYS } from "./settings/schema.js";
 export { gitSourceLockFields } from "./lockfile/entry-fields.js";
 export { LOCK_ENTRY_SCHEMA_BY_TYPE } from "./lockfile/schema.js";
 export { ACQUIRED_EXTENSIONS_DIR, LOCK_FILENAME } from "./workspace/constants.js";
+export { isInstallRootStagingName, observeInstallRoot, type InstallRootEntry, type InstallRootInventory, type InstalledPackageEntry, type ObserveInstallRootArgs, type UnrecognizedInstallRootEntry, } from "./workspace/install-root.js";
 export { acquiredExtensionDisplayPath, acquiredExtensionDisplayPathFromLockEntry, computeExtensionPathsForLayout, extensionPathSourceFromLockEntry, extensionContentFilename, extensionContentPath, type ExtensionPathLockEntry, type ExtensionPathSource, type ExtensionDirPaths, } from "./workspace/extension-paths.js";
 export { RenderedFilePathSchema, RenderedFilesMapSchema, computeSourceHash, type RenderedFilePath, type RenderedFilesMap, } from "./workspace/rendered-files.js";
 export { computePackageContentHash } from "./workspace/package-hash.js";

package/dist/src/index.js

@@ -27,6 +27,7 @@ export { gitSourceLockFields } from "./lockfile/entry-fields.js";
 export { LOCK_ENTRY_SCHEMA_BY_TYPE } from "./lockfile/schema.js";
 // Extension path and identity vocabulary
 export { ACQUIRED_EXTENSIONS_DIR, LOCK_FILENAME } from "./workspace/constants.js";
+export { isInstallRootStagingName, observeInstallRoot, } from "./workspace/install-root.js";
 export { acquiredExtensionDisplayPath, acquiredExtensionDisplayPathFromLockEntry, computeExtensionPathsForLayout, extensionPathSourceFromLockEntry, extensionContentFilename, extensionContentPath, } from "./workspace/extension-paths.js";
 export { RenderedFilePathSchema, RenderedFilesMapSchema, computeSourceHash, } from "./workspace/rendered-files.js";
 export { computePackageContentHash } from "./workspace/package-hash.js";

package/dist/src/lockfile/lockfile.d.ts

@@ -38,8 +38,8 @@ export type LockfileUpdate = (lockfile: Lockfile) => Lockfile;
  *
  * @experimental This API is unstable and may change without notice.
  */
-export declare const writeLockfileAtPath: (lockfilePath: string, lockfile: Lockfile) => Effect.Effect<void, LockfileWriteError, FileSystem.FileSystem | Path.Path>;
-export declare const writeLockfile: (axmDir: string, lockfile: Lockfile) => Effect.Effect<void, LockfileWriteError, FileSystem.FileSystem | Path.Path>;
+export declare const writeLockfileAtPath: (lockfilePath: string, lockfile: Lockfile) => Effect.Effect<void, import("@agentxm/workspace-transactions").WorkspaceSnapshotError | LockfileWriteError, FileSystem.FileSystem | Path.Path>;
+export declare const writeLockfile: (axmDir: string, lockfile: Lockfile) => Effect.Effect<void, import("@agentxm/workspace-transactions").WorkspaceSnapshotError | LockfileWriteError, FileSystem.FileSystem | Path.Path>;
 /**
  * Applies lockfile updates in order without writing to disk.
  *
@@ -782,7 +782,7 @@ export declare const commitLockfileUpdates: (axmDir: string, lockfile: Lockfile,
             readonly treeIntegrity: string & import("effect/Brand").Brand<"TreeIntegrity">;
         };
     } | undefined;
-}, LockfileWriteError | LockfileValidationError, FileSystem.FileSystem | Path.Path>;
+}, import("@agentxm/workspace-transactions").WorkspaceSnapshotError | LockfileWriteError | LockfileValidationError, FileSystem.FileSystem | Path.Path>;
 /**
  * Commits a caller-computed lockfile snapshot as an entry-level patch.
  *
@@ -1522,7 +1522,7 @@ export declare const commitLockfileSnapshotUpdateAtPath: (lockfilePath: string,
             readonly treeIntegrity: string & import("effect/Brand").Brand<"TreeIntegrity">;
         };
     } | undefined;
-}, LockfileWriteError | LockfileValidationError, FileSystem.FileSystem | Path.Path>;
+}, import("@agentxm/workspace-transactions").WorkspaceSnapshotError | LockfileWriteError | LockfileValidationError, FileSystem.FileSystem | Path.Path>;
 export declare const commitLockfileSnapshotUpdate: (axmDir: string, base: Lockfile, next: Lockfile) => Effect.Effect<{
     readonly skills: {
         readonly [x: string]: {
@@ -2251,5 +2251,5 @@ export declare const commitLockfileSnapshotUpdate: (axmDir: string, base: Lockfi
             readonly treeIntegrity: string & import("effect/Brand").Brand<"TreeIntegrity">;
         };
     } | undefined;
-}, LockfileWriteError | LockfileValidationError, FileSystem.FileSystem | Path.Path>;
+}, import("@agentxm/workspace-transactions").WorkspaceSnapshotError | LockfileWriteError | LockfileValidationError, FileSystem.FileSystem | Path.Path>;
 //# sourceMappingURL=lockfile.d.ts.map

package/dist/src/lockfile/lockfile.js

@@ -14,7 +14,7 @@ import * as Effect from "effect/Effect";
 import * as Schema from "effect/Schema";
 import * as Semaphore from "effect/Semaphore";
 import YAML from "yaml";
-import { recordFootprint, sweepStaleAtomicWriteTemps, writeFileAtomic, } from "@agentxm/workspace-transactions";
+import { protectWorkspacePath, recordFootprint, sweepStaleAtomicWriteTemps, writeFileAtomic, } from "@agentxm/workspace-transactions";
 import { LockfileValidationError, LockfileWriteError } from "./errors.js";
 import { LOCKFILE_VERSION, LockfileSchema } from "./schema.js";
 // -----------------------------------------------------------------------------
@@ -132,6 +132,7 @@ const withLockfileLock = (lockfilePath, effect) => Effect.gen(function* () {
 const writeLockfileUnlocked = (lockfilePath, lockfile) => Effect.gen(function* () {
     const fs = yield* FileSystem.FileSystem;
     const yamlContent = yield* encodeLockfileYaml(lockfilePath, lockfile);
+    yield* protectWorkspacePath(lockfilePath);
     const existed = yield* fs.exists(lockfilePath).pipe(Effect.orElseSucceed(() => true));
     yield* sweepStaleAtomicWriteTemps(fs, lockfilePath);
     const written = yield* writeFileAtomic(fs, {

package/dist/src/workspace/install-root.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Install-root inventory.
+ *
+ * Classifies every entry in a scope's install root (`agent_extensions`): an
+ * installed package whose path gives a well-formed extension identity or is
+ * proven by an accepted resolution, AXM's own interrupted staging, or an
+ * unrecognized entry. Each installed package records whether desired state
+ * still reaches it; one that nothing reaches is a leftover.
+ *
+ * Location inside the install root is AXM's install proof for canonical
+ * package directories only. It never proves ownership of agent projections.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+import { type ExtensionType } from "@agentxm/extension-model/unstable/extensions";
+import type { DesiredStateGraph } from "./desired-state-graph.js";
+import type { WorkspaceLayout } from "./layout.js";
+import type { LockfileReaderService } from "./lockfile-reader.js";
+/** An installed package directory in the install root. */
+export interface InstalledPackageEntry {
+    readonly kind: "package";
+    readonly type: ExtensionType;
+    readonly name: string;
+    /** The owner handle the path names, when the path gives one. */
+    readonly owner: string | undefined;
+    /** The source directory the package sits under, when the path gives one. */
+    readonly sourceDirectory: string | undefined;
+    /** Absolute canonical package path. */
+    readonly path: string;
+    /** The lock key of the accepted resolution whose canonical path this is. */
+    readonly lockKey: string | undefined;
+    /** Whether any desired route reaches this canonical package. */
+    readonly reached: boolean;
+}
+/** An install-root entry that is neither an installed package nor AXM staging. */
+export interface UnrecognizedInstallRootEntry {
+    readonly kind: "unrecognized";
+    readonly path: string;
+    readonly entryKind: "file" | "directory" | "symlink";
+}
+export type InstallRootEntry = InstalledPackageEntry | UnrecognizedInstallRootEntry;
+export interface InstallRootInventory {
+    readonly root: string;
+    readonly packages: ReadonlyArray<InstalledPackageEntry>;
+    readonly leftovers: ReadonlyArray<InstalledPackageEntry>;
+    readonly unrecognized: ReadonlyArray<UnrecognizedInstallRootEntry>;
+}
+/** AXM's own interrupted replacement directories beside a canonical package. */
+export declare const isInstallRootStagingName: (name: string) => boolean;
+export interface ObserveInstallRootArgs {
+    readonly layout: WorkspaceLayout;
+    readonly graph: DesiredStateGraph;
+    readonly locks: LockfileReaderService;
+}
+/**
+ * Observe the install root. When desired state is incomplete, every installed
+ * package counts as reached: no leftover is claimed without full reachability.
+ */
+export declare const observeInstallRoot: ({ layout, graph, locks }: ObserveInstallRootArgs) => Effect.Effect<{
+    root: string & import("effect/Brand").Brand<"AbsolutePath">;
+    packages: InstalledPackageEntry[];
+    leftovers: InstalledPackageEntry[];
+    unrecognized: UnrecognizedInstallRootEntry[];
+}, import("./service-interface.ts").WorkspaceLockfileReadFailure, FileSystem.FileSystem | Path.Path>;
+//# sourceMappingURL=install-root.d.ts.map

package/dist/src/workspace/install-root.js

@@ -0,0 +1,149 @@
+/**
+ * Install-root inventory.
+ *
+ * Classifies every entry in a scope's install root (`agent_extensions`): an
+ * installed package whose path gives a well-formed extension identity or is
+ * proven by an accepted resolution, AXM's own interrupted staging, or an
+ * unrecognized entry. Each installed package records whether desired state
+ * still reaches it; one that nothing reaches is a leftover.
+ *
+ * Location inside the install root is AXM's install proof for canonical
+ * package directories only. It never proves ownership of agent projections.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+import { extensionTypes, isExtensionTypePlural, toExtensionType, toExtensionTypePlural, } from "@agentxm/extension-model/unstable/extensions";
+import { sanitizeName } from "./extension-name.js";
+import { computeExtensionPathsForLayout, extensionPathSourceFromLockEntry, } from "./extension-paths.js";
+/** AXM's own interrupted replacement directories beside a canonical package. */
+export const isInstallRootStagingName = (name) => name.endsWith(".axm-staging") || name.endsWith(".axm-backup");
+const PLATFORM_METADATA_FILES = new Set([".DS_Store", "Thumbs.db"]);
+const isCanonicalName = (name) => sanitizeName(name) === name;
+const isOwnerSegment = (segment) => segment.startsWith("@") && segment.length > 1 && isCanonicalName(segment.slice(1));
+/**
+ * `<source>/@<owner>/<plural>/<name>` for acquired packages, or
+ * `@<owner>/<plural>/<name>` for user-scope authored packages.
+ */
+const identityOf = (segments) => {
+    const [first = "", second = "", third = "", fourth = ""] = segments;
+    const shape = segments.length === 4 && !first.startsWith("@")
+        ? { sourceDirectory: first, owner: second, plural: third, name: fourth }
+        : segments.length === 3
+            ? { sourceDirectory: undefined, owner: first, plural: second, name: third }
+            : undefined;
+    if (shape === undefined || !isOwnerSegment(shape.owner) || !isCanonicalName(shape.name))
+        return undefined;
+    if (!isExtensionTypePlural(shape.plural))
+        return undefined;
+    return {
+        type: toExtensionType(shape.plural),
+        name: shape.name,
+        owner: shape.owner,
+        sourceDirectory: shape.sourceDirectory,
+    };
+};
+/** Whether a directory can still lead to a well-formed identity path. */
+const isIdentityPrefix = (segments) => {
+    const [first = "", second = "", third = ""] = segments;
+    switch (segments.length) {
+        case 1:
+            return true;
+        case 2:
+            return first.startsWith("@")
+                ? isOwnerSegment(first) && isExtensionTypePlural(second)
+                : isOwnerSegment(second);
+        case 3:
+            return !first.startsWith("@") && isExtensionTypePlural(third);
+        default:
+            return false;
+    }
+};
+/**
+ * Observe the install root. When desired state is incomplete, every installed
+ * package counts as reached: no leftover is claimed without full reachability.
+ */
+export const observeInstallRoot = ({ layout, graph, locks }) => Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    const path = yield* Path.Path;
+    const root = layout.acquiredRoot;
+    const accepted = (yield* Effect.forEach(extensionTypes, (type) => locks
+        .entries(type)
+        .pipe(Effect.map((entries) => Object.entries(entries).map(([key, entry]) => ({ type, key, entry })))))).flat();
+    const nodeReaches = (type, key) => graph.nodes.some((node) => node.type === type && (type === "mcp-server" ? node.identity === key : node.name === key));
+    const lockedPaths = new Map(accepted.map((row) => [
+        computeExtensionPathsForLayout(path.join, layout, extensionPathSourceFromLockEntry(row.entry), toExtensionTypePlural(row.type), row.entry.workspaceName).canonicalPath,
+        { ...row, reached: nodeReaches(row.type, row.key) },
+    ]));
+    // A desired extension whose resolution is not yet accepted may still be
+    // materialized into this path, so it reaches every same-named package.
+    const unlockedDesired = graph.nodes.filter((node) => !accepted.some((row) => row.type === node.type &&
+        (node.type === "mcp-server" ? row.key === node.identity : row.key === node.name)));
+    const packages = [];
+    const unrecognized = [];
+    const isLink = (target) => fs.readLink(target).pipe(Effect.as(true), Effect.orElseSucceed(() => false));
+    const leadsToLockedPath = (directory) => [...lockedPaths.keys()].some((locked) => {
+        const relative = path.relative(directory, locked);
+        return relative !== "" && !relative.startsWith("..") && !path.isAbsolute(relative);
+    });
+    const visit = (directory, segments) => Effect.gen(function* () {
+        const names = yield* fs.readDirectory(directory).pipe(Effect.orElseSucceed(() => []));
+        for (const name of [...names].sort()) {
+            const absolute = path.join(directory, name);
+            const childSegments = [...segments, name];
+            if (isInstallRootStagingName(name) || PLATFORM_METADATA_FILES.has(name))
+                continue;
+            if (yield* isLink(absolute)) {
+                unrecognized.push({ kind: "unrecognized", path: absolute, entryKind: "symlink" });
+                continue;
+            }
+            const info = yield* fs.stat(absolute).pipe(Effect.option);
+            if (info._tag === "None")
+                continue;
+            if (info.value.type !== "Directory") {
+                unrecognized.push({ kind: "unrecognized", path: absolute, entryKind: "file" });
+                continue;
+            }
+            const locked = lockedPaths.get(absolute);
+            const identity = identityOf(childSegments);
+            const type = locked?.type ?? identity?.type;
+            const packageName = locked?.entry.workspaceName ?? identity?.name;
+            if (type !== undefined && packageName !== undefined) {
+                // A path without a source directory is authored content, which is
+                // never inferred to be undesired.
+                const reached = !graph.complete ||
+                    (locked === undefined && identity?.sourceDirectory === undefined) ||
+                    (locked?.reached ?? false) ||
+                    unlockedDesired.some((node) => node.type === type && node.name === packageName);
+                packages.push({
+                    kind: "package",
+                    type,
+                    name: packageName,
+                    owner: identity?.owner,
+                    sourceDirectory: identity?.sourceDirectory,
+                    path: absolute,
+                    lockKey: locked?.key,
+                    reached,
+                });
+                continue;
+            }
+            if (isIdentityPrefix(childSegments) || leadsToLockedPath(absolute)) {
+                yield* visit(absolute, childSegments);
+                continue;
+            }
+            unrecognized.push({ kind: "unrecognized", path: absolute, entryKind: "directory" });
+        }
+    });
+    if (yield* fs.exists(root).pipe(Effect.orElseSucceed(() => false)))
+        yield* visit(root, []);
+    return {
+        root,
+        packages,
+        leftovers: packages.filter((entry) => !entry.reached),
+        unrecognized,
+    };
+});
+//# sourceMappingURL=install-root.js.map

package/dist/src/workspace/read-model/extensions/inventory.d.ts

@@ -1,11 +1,22 @@
 import * as Schema from "effect/Schema";
 import { type ConfiguredAgentOutcome } from "../../configured-agent-outcome.js";
 import type { ExtensionKey } from "../types.js";
-export declare const ExtensionInventoryLifecycleSchema: Schema.Literals<readonly ["configured", "implicit", "unmanaged"]>;
+/**
+ * How desired state explains one detected extension.
+ *
+ * - `configured` — declared directly in workspace settings.
+ * - `implicit` — reached indirectly, such as through a desired Pack.
+ * - `leftover` — an installed package in the install root that desired state
+ *   no longer reaches.
+ * - `undeclared` — an authored package in its standard authoring folder with no
+ *   workspace declaration.
+ * - `unmanaged` — native agent content AXM does not own.
+ */
+export declare const ExtensionInventoryLifecycleSchema: Schema.Literals<readonly ["configured", "implicit", "leftover", "undeclared", "unmanaged"]>;
 export type ExtensionInventoryLifecycle = typeof ExtensionInventoryLifecycleSchema.Type;
 export declare const ExtensionInventoryClassificationSchema: Schema.Struct<{
     readonly kind: Schema.Literal<"lifecycle">;
-    readonly lifecycle: Schema.Literals<readonly ["configured", "implicit", "unmanaged"]>;
+    readonly lifecycle: Schema.Literals<readonly ["configured", "implicit", "leftover", "undeclared", "unmanaged"]>;
 }>;
 export type ExtensionInventoryClassification = typeof ExtensionInventoryClassificationSchema.Type;
 export declare const ExtensionInventoryRowSchema: Schema.Struct<{
@@ -14,7 +25,7 @@ export declare const ExtensionInventoryRowSchema: Schema.Struct<{
     readonly name: Schema.String;
     readonly classification: Schema.Struct<{
         readonly kind: Schema.Literal<"lifecycle">;
-        readonly lifecycle: Schema.Literals<readonly ["configured", "implicit", "unmanaged"]>;
+        readonly lifecycle: Schema.Literals<readonly ["configured", "implicit", "leftover", "undeclared", "unmanaged"]>;
     }>;
     readonly enabled: Schema.NullOr<Schema.Boolean>;
     readonly installed: Schema.Boolean;
@@ -47,7 +58,7 @@ export declare const ExtensionInventorySchema: Schema.Struct<{
         readonly name: Schema.String;
         readonly classification: Schema.Struct<{
             readonly kind: Schema.Literal<"lifecycle">;
-            readonly lifecycle: Schema.Literals<readonly ["configured", "implicit", "unmanaged"]>;
+            readonly lifecycle: Schema.Literals<readonly ["configured", "implicit", "leftover", "undeclared", "unmanaged"]>;
         }>;
         readonly enabled: Schema.NullOr<Schema.Boolean>;
         readonly installed: Schema.Boolean;
@@ -76,6 +87,8 @@ export declare const ExtensionInventorySchema: Schema.Struct<{
     readonly configuredCount: Schema.Number;
     readonly implicitCount: Schema.Number;
     readonly installedCount: Schema.Number;
+    readonly leftoverCount: Schema.Number;
+    readonly undeclaredCount: Schema.Number;
     readonly unmanagedCount: Schema.Number;
 }>;
 export type ExtensionInventory = typeof ExtensionInventorySchema.Type;
@@ -95,5 +108,9 @@ export interface ProjectExtensionInventoryInput {
     readonly lifecycle: ReadonlyArray<LifecycleInventoryCandidate>;
     readonly agents?: ReadonlyArray<string>;
 }
+/** Whether desired state reaches rows with this lifecycle. */
+export declare const isDesiredInventoryLifecycle: (lifecycle: ExtensionInventoryLifecycle) => boolean;
+/** Aggregate counts for an inventory's already-filtered items. */
+export declare const countExtensionInventory: (items: ReadonlyArray<ExtensionInventoryRow>) => ExtensionInventory;
 export declare const projectExtensionInventory: (input: ProjectExtensionInventoryInput) => ExtensionInventory;
 //# sourceMappingURL=inventory.d.ts.map

package/dist/src/workspace/read-model/extensions/inventory.js

@@ -1,9 +1,22 @@
 import * as Schema from "effect/Schema";
 import { ExtensionTypeSchema } from "@agentxm/extension-model/unstable/extensions/common";
 import { ConfiguredAgentOutcomeSchema, } from "../../configured-agent-outcome.js";
+/**
+ * How desired state explains one detected extension.
+ *
+ * - `configured` — declared directly in workspace settings.
+ * - `implicit` — reached indirectly, such as through a desired Pack.
+ * - `leftover` — an installed package in the install root that desired state
+ *   no longer reaches.
+ * - `undeclared` — an authored package in its standard authoring folder with no
+ *   workspace declaration.
+ * - `unmanaged` — native agent content AXM does not own.
+ */
 export const ExtensionInventoryLifecycleSchema = Schema.Literals([
     "configured",
     "implicit",
+    "leftover",
+    "undeclared",
     "unmanaged",
 ]);
 export const ExtensionInventoryClassificationSchema = Schema.Struct({
@@ -35,12 +48,32 @@ export const ExtensionInventorySchema = Schema.Struct({
     configuredCount: Schema.Number,
     implicitCount: Schema.Number,
     installedCount: Schema.Number,
+    leftoverCount: Schema.Number,
+    undeclaredCount: Schema.Number,
     unmanagedCount: Schema.Number,
 });
 const lifecyclePriority = {
     configured: 0,
     implicit: 1,
-    unmanaged: 2,
+    leftover: 2,
+    undeclared: 3,
+    unmanaged: 4,
+};
+/** Whether desired state reaches rows with this lifecycle. */
+export const isDesiredInventoryLifecycle = (lifecycle) => lifecycle === "configured" || lifecycle === "implicit";
+/** Aggregate counts for an inventory's already-filtered items. */
+export const countExtensionInventory = (items) => {
+    const withLifecycle = (lifecycle) => items.filter((item) => item.classification.lifecycle === lifecycle).length;
+    return {
+        items,
+        count: items.length,
+        configuredCount: withLifecycle("configured"),
+        implicitCount: withLifecycle("implicit"),
+        installedCount: items.filter((item) => item.installed).length,
+        leftoverCount: withLifecycle("leftover"),
+        undeclaredCount: withLifecycle("undeclared"),
+        unmanagedCount: withLifecycle("unmanaged"),
+    };
 };
 const keyString = (key) => `${key.scope}:${key.type}:${key.name}`;
 const addAll = (target, values) => {
@@ -95,17 +128,6 @@ export const projectExtensionInventory = (input) => {
         origins: sorted(aggregate.origins),
         paths: sorted(aggregate.paths),
     }));
-    const items = lifecycleRows.sort((left, right) => left.name.localeCompare(right.name));
-    const configuredCount = items.filter((item) => item.classification.lifecycle === "configured").length;
-    const implicitCount = items.filter((item) => item.classification.lifecycle === "implicit").length;
-    const unmanagedCount = items.filter((item) => item.classification.lifecycle === "unmanaged").length;
-    return {
-        items,
-        count: items.length,
-        configuredCount,
-        implicitCount,
-        installedCount: items.filter((item) => item.installed).length,
-        unmanagedCount,
-    };
+    return countExtensionInventory(lifecycleRows.sort((left, right) => left.name.localeCompare(right.name)));
 };
 //# sourceMappingURL=inventory.js.map

package/dist/src/workspace/read-model/scanners/canonical-extensions.js

@@ -37,6 +37,7 @@ import { MANIFEST_FILENAME_BY_TYPE } from "@agentxm/extension-content";
 import { parseSkillMd } from "@agentxm/extension-content";
 import { DISCOVERY_SKIPPED_DIRECTORIES } from "@agentxm/extension-model/unstable/discovery-walk";
 import { makeAbsolutePath } from "@agentxm/extension-model/unstable/path-types";
+import { isInstallRootStagingName } from "../../install-root.js";
 import { childEntries, fileExists, filterDirectories, splitAbsolutePathSegments, } from "./fs-helpers.js";
 const SCANNER_NAME = "canonical-extensions";
 /**
@@ -187,7 +188,7 @@ const scanAcquiredDirectory = (deps, dir) => Effect.gen(function* () {
         }
     }
     const childCandidates = entries
-        .filter((entry) => !DISCOVERY_SKIPPED_DIRECTORIES.has(entry))
+        .filter((entry) => !DISCOVERY_SKIPPED_DIRECTORIES.has(entry) && !isInstallRootStagingName(entry))
         .map((entry) => deps.path.join(dir, entry));
     const childDirs = yield* filterDirectories(deps.fs, childCandidates);
     const nested = yield* Effect.forEach(childDirs, (childDir) => scanAcquiredDirectory(deps, childDir), { concurrency: "unbounded" });

package/dist/src/workspace/read-model/service.d.ts

@@ -8,6 +8,7 @@ import * as Path from "effect/Path";
 import { type Handle } from "@agentxm/extension-model/unstable/extensions/handle";
 import type { SourceHostConfig } from "../../settings/schema.js";
 import { type AbsolutePath } from "@agentxm/extension-model/unstable/path-types";
+import { type WorkspaceLayout } from "../layout.js";
 import { AgentRootResolver } from "./agent-root-resolver.js";
 import { type ScopedAgentsApi } from "./agents/index.js";
 import { type Warning } from "./diagnostics.js";
@@ -55,6 +56,8 @@ export interface WorkspaceReadModel {
     readonly owner: ScopedOwnerApi;
     readonly diagnostics: Effect.Effect<ReadonlyArray<Warning>>;
     readonly canonicalExtensions: Effect.Effect<ReadonlyArray<CanonicalExtensionOccurrence>>;
+    /** The resolved storage layout, or none when the layout could not be resolved. */
+    readonly layout: Option.Option<WorkspaceLayout>;
 }
 /**
  * The read-model family that carries each catalog extension type, or `null`

package/dist/src/workspace/read-model/service.js

@@ -343,6 +343,7 @@ const buildScope = Effect.fn("workspace.read-model.build-scope")(function* (deps
         owner,
         diagnostics: diagnostics.snapshot,
         canonicalExtensions: canonicalScanner,
+        layout: Result.isFailure(layoutResult) ? Option.none() : Option.some(layoutResult.success),
     };
 });
 // ---------------------------------------------------------------------------

package/dist/src/workspace/read-model-record-readers.js

@@ -10,7 +10,7 @@ import { installableExtensionTypes, } from "@agentxm/extension-model/unstable/ex
 import { isAxmManagedMcpEntry } from "@agentxm/agent-integration";
 import { createDefaultSettings } from "../settings/index.js";
 import { configuredAgentLifecycleOutcomes } from "./configured-agent-outcomes.js";
-import { projectExtensionInventory, } from "./read-model/extensions/inventory.js";
+import { countExtensionInventory, isDesiredInventoryLifecycle, projectExtensionInventory, } from "./read-model/extensions/inventory.js";
 import { deriveSourceMetaFromLockType } from "./source-metadata.js";
 export const makeReadModelRecordReaders = (args) => {
     const packagingKindForSource = (type, source) => {
@@ -88,9 +88,38 @@ export const makeReadModelRecordReaders = (args) => {
             paths: observations.paths,
         };
     };
-    const lifecycleCandidateFromUnmanaged = (row) => ({
+    const isWithin = (root, candidate) => {
+        const relative = args.path.relative(root, candidate);
+        return !relative.startsWith("..") && !args.path.isAbsolute(relative);
+    };
+    /**
+     * Classify one occurrence desired state does not explain: an AXM package
+     * under the install root is `leftover`, an AXM package under its type's
+     * standard authoring folder is `undeclared`, and anything else — native
+     * agent content — is `unmanaged`.
+     */
+    const unexplainedLifecycle = (layout, key, actual) => {
+        if (Option.isNone(layout) || typeof actual !== "object" || actual === null)
+            return "unmanaged";
+        const originTag = stringProperty("origin" in actual ? actual.origin : undefined, "_tag");
+        const packageLocation = stringProperty(actual, "packageRoot") ?? stringProperty(actual, "contentRoot");
+        if (originTag === null || packageLocation === null)
+            return "unmanaged";
+        const canonical = originTag.startsWith("canonical-axm-");
+        if (!canonical && !originTag.startsWith("external-axm-"))
+            return "unmanaged";
+        if (isWithin(layout.value.acquiredRoot, packageLocation))
+            return "leftover";
+        if (canonical &&
+            layout.value.scope === "project" &&
+            isWithin(layout.value.authoredRoot(key.type), packageLocation)) {
+            return "undeclared";
+        }
+        return "unmanaged";
+    };
+    const lifecycleCandidateFromUnexplained = (layout, row) => ({
         key: row.key,
-        lifecycle: "unmanaged",
+        lifecycle: unexplainedLifecycle(layout, row.key, row.actual),
         enabled: null,
         installed: true,
         ...observationFromActual(row.actual),
@@ -273,7 +302,7 @@ export const makeReadModelRecordReaders = (args) => {
             paths: [],
         }));
         const implicitObserved = desiredUnmanaged.map((row) => ({
-            ...lifecycleCandidateFromUnmanaged(row),
+            ...lifecycleCandidateFromUnexplained(input.layout, row),
             lifecycle: "implicit",
             enabled: true,
         }));
@@ -287,8 +316,8 @@ export const makeReadModelRecordReaders = (args) => {
                 ...implicitMissing,
                 ...input.unmanaged
                     .filter((row) => !desiredPackMembers.has(row.key.name))
-                    .map(lifecycleCandidateFromUnmanaged),
-                ...stalePackActuals.map(lifecycleCandidateFromUnmanaged),
+                    .map((row) => lifecycleCandidateFromUnexplained(input.layout, row)),
+                ...stalePackActuals.map((row) => lifecycleCandidateFromUnexplained(input.layout, row)),
             ],
             agents: input.agents,
         });
@@ -304,9 +333,8 @@ export const makeReadModelRecordReaders = (args) => {
                 const withOutcomes = inventory.items.map((row) => {
                     return {
                         ...row,
-                        agentOutcomes: row.classification.lifecycle === "unmanaged"
-                            ? []
-                            : configuredAgentLifecycleOutcomes({
+                        agentOutcomes: isDesiredInventoryLifecycle(row.classification.lifecycle)
+                            ? configuredAgentLifecycleOutcomes({
                                 type: row.type,
                                 name: row.name,
                                 agentIds: configuredAgents,
@@ -315,22 +343,14 @@ export const makeReadModelRecordReaders = (args) => {
                                 targetState: row.enabled === false ? "disabled" : "enabled",
                                 installed: row.installed,
                                 observedAgentIds: row.agents,
-                            }),
+                            })
+                            : [],
                     };
                 });
                 const items = withOutcomes.filter((row) => agents.length === 0 ||
                     agents.some((agentId) => row.agents.includes(agentId) ||
                         row.agentOutcomes.some((outcome) => outcome.agentId === agentId)));
-                return {
-                    items,
-                    count: items.length,
-                    configuredCount: items.filter((item) => item.classification.lifecycle === "configured").length,
-                    implicitCount: items.filter((item) => item.classification.lifecycle === "implicit")
-                        .length,
-                    installedCount: items.filter((item) => item.installed).length,
-                    unmanagedCount: items.filter((item) => item.classification.lifecycle === "unmanaged")
-                        .length,
-                };
+                return countExtensionInventory(items);
             };
             switch (type) {
                 case "skill": {
@@ -339,6 +359,7 @@ export const makeReadModelRecordReaders = (args) => {
                     const unmanaged = yield* scoped.skills.unmanaged;
                     return finalizeInventory(projectStandardInventory({
                         scope: scoped.scope,
+                        layout: scoped.layout,
                         type,
                         installed,
                         resolved: Option.getOrElse(resolved, () => []),
@@ -354,6 +375,7 @@ export const makeReadModelRecordReaders = (args) => {
                     const unmanaged = yield* scoped.mcpServers.unmanaged;
                     return finalizeInventory(projectStandardInventory({
                         scope: scoped.scope,
+                        layout: scoped.layout,
                         type,
                         installed,
                         resolved: Option.getOrElse(resolved, () => []),
@@ -369,6 +391,7 @@ export const makeReadModelRecordReaders = (args) => {
                     const unmanaged = yield* scoped.subagents.unmanaged;
                     return finalizeInventory(projectStandardInventory({
                         scope: scoped.scope,
+                        layout: scoped.layout,
                         type,
                         installed,
                         resolved: Option.getOrElse(resolved, () => []),
@@ -384,6 +407,7 @@ export const makeReadModelRecordReaders = (args) => {
                     const unmanaged = yield* scoped.packs.unmanaged;
                     return finalizeInventory(projectStandardInventory({
                         scope: scoped.scope,
+                        layout: scoped.layout,
                         type,
                         installed,
                         resolved: Option.getOrElse(resolved, () => []),
@@ -399,6 +423,7 @@ export const makeReadModelRecordReaders = (args) => {
                     const unmanaged = yield* scoped.rules.unmanaged;
                     return finalizeInventory(projectStandardInventory({
                         scope: scoped.scope,
+                        layout: scoped.layout,
                         type,
                         installed,
                         resolved: Option.getOrElse(resolved, () => []),
@@ -414,6 +439,7 @@ export const makeReadModelRecordReaders = (args) => {
                     const unmanaged = yield* scoped.hooks.unmanaged;
                     return finalizeInventory(projectStandardInventory({
                         scope: scoped.scope,
+                        layout: scoped.layout,
                         type,
                         installed,
                         resolved: Option.getOrElse(resolved, () => []),
@@ -429,6 +455,7 @@ export const makeReadModelRecordReaders = (args) => {
                     const unmanaged = yield* scoped.knowledge.unmanaged;
                     return finalizeInventory(projectStandardInventory({
                         scope: scoped.scope,
+                        layout: scoped.layout,
                         type,
                         installed,
                         resolved: Option.getOrElse(resolved, () => []),
@@ -457,6 +484,8 @@ export const makeReadModelRecordReaders = (args) => {
             configuredCount: inventories.reduce((total, inventory) => total + inventory.configuredCount, 0),
             implicitCount: inventories.reduce((total, inventory) => total + inventory.implicitCount, 0),
             installedCount: inventories.reduce((total, inventory) => total + inventory.installedCount, 0),
+            leftoverCount: inventories.reduce((total, inventory) => total + inventory.leftoverCount, 0),
+            undeclaredCount: inventories.reduce((total, inventory) => total + inventory.undeclaredCount, 0),
             unmanagedCount: inventories.reduce((total, inventory) => total + inventory.unmanagedCount, 0),
         };
     });

package/dist/src/workspace/service-interface.d.ts

@@ -106,7 +106,7 @@ export type WorkspaceStateReadFailure = SettingsReadError | LockfileReadError |
  */
 export type WorkspaceSettingsMutationFailure = WorkspaceSettingsReadFailure | SettingsWriteError | WorkspaceSnapshotError;
 /** Lockfile read-modify-write through the snapshot-commit path. */
-export type WorkspaceLockfileMutationFailure = WorkspaceLockfileReadFailure | LockfileValidationError | LockfileWriteError;
+export type WorkspaceLockfileMutationFailure = WorkspaceLockfileReadFailure | LockfileValidationError | LockfileWriteError | WorkspaceSnapshotError;
 /** Coupled settings-and-lockfile mutation. */
 export type WorkspaceStateMutationFailure = WorkspaceSettingsMutationFailure | WorkspaceLockfileMutationFailure;
 export interface WorkspaceReadModelRecords {

package/dist/src/workspace/test-stubs.d.ts

@@ -61,6 +61,8 @@ export declare const readModelRecordStubs: {
         configuredCount: number;
         implicitCount: number;
         installedCount: number;
+        leftoverCount: number;
+        undeclaredCount: number;
         unmanagedCount: number;
     }, never, never>;
     readonly getExtensionInventory: () => Effect.Effect<ExtensionInventory, WorkspaceStateReadFailure>;

package/dist/src/workspace/test-stubs.js

@@ -23,6 +23,8 @@ const emptyInventory = () => Effect.succeed({
     configuredCount: 0,
     implicitCount: 0,
     installedCount: 0,
+    leftoverCount: 0,
+    undeclaredCount: 0,
     unmanagedCount: 0,
 });
 const fs = (() => {
@@ -94,6 +96,8 @@ export const readModelRecordStubs = {
         configuredCount: 0,
         implicitCount: 0,
         installedCount: 0,
+        leftoverCount: 0,
+        undeclaredCount: 0,
         unmanagedCount: 0,
     }),
     getExtensionInventory: emptyInventory,

package/package.json

@@ -4,11 +4,11 @@
     "url": "https://github.com/agentxm/axm/issues"
   },
   "dependencies": {
-    "@agentxm/agent-integration": "^0.30.1",
-    "@agentxm/extension-content": "^0.30.1",
-    "@agentxm/extension-model": "^0.30.1",
-    "@agentxm/registry-protocol": "^0.30.1",
-    "@agentxm/workspace-transactions": "^0.30.1",
+    "@agentxm/agent-integration": "^0.30.2",
+    "@agentxm/extension-content": "^0.30.2",
+    "@agentxm/extension-model": "^0.30.2",
+    "@agentxm/registry-protocol": "^0.30.2",
+    "@agentxm/workspace-transactions": "^0.30.2",
     "effect": "4.0.0-rc.115",
     "jsonc-parser": "^3.3.1",
     "semver": "^7.8.5",
@@ -17,7 +17,7 @@
   },
   "description": "AXM workspace state kernel: settings, lockfile, read model, and desired-state vocabulary for the axm CLI. Unstable and unsupported — use the axm.sh CLI.",
   "devDependencies": {
-    "@agentxm/specification-metadata": "^0.30.1",
+    "@agentxm/specification-metadata": "^0.30.2",
     "@effect/platform-node": "4.0.0-rc.115",
     "@effect/vitest": "4.0.0-rc.115",
     "@fast-check/vitest": "^0.5.0",
@@ -63,5 +63,5 @@
   },
   "sideEffects": false,
   "type": "module",
-  "version": "0.30.1"
+  "version": "0.30.2"
 }