@agentxm/workspace-state 0.29.4 → 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";
@@ -67,16 +68,18 @@ export { WorkspaceLocation, type WorkspaceLocationService } from "./workspace/lo
 export { SettingsReader, type SettingsReaderService } from "./workspace/settings-reader.js";
 export { LockfileReader, type LockfileReaderService } from "./workspace/lockfile-reader.js";
 export { readOtherScopeState, type OtherScopeState } from "./workspace/other-scope-reader.js";
-export { DesiredStateReader, type DesiredStateReaderService, } from "./workspace/desired-state-reader.js";
+export { DesiredStateReader, type DesiredStateReaderService, type DesiredStateGraphInputs, } from "./workspace/desired-state-reader.js";
 export { WorkspaceRecords, type WorkspaceRecordsService } from "./workspace/workspace-records.js";
 export { ExtensionPaths, type ExtensionPathsService } from "./workspace/extension-paths-service.js";
 export { SettingsWriter, type SettingsWriterService } from "./workspace/settings-writer.js";
 export { AcceptedResolutionWriter, type AcceptedResolutionWriterService, } from "./workspace/accepted-resolution-writer.js";
 export { DesiredStateWriter, type DeclareArgsByType, type DesiredStateWriterService, } from "./workspace/desired-state-writer.js";
+export { settingsEntries, lockEntries } from "./workspace/entry-accessors.js";
 export type { LockEntriesOf, LockEntryByType, SettingsEntriesOf, SettingsEntryByType, } from "./workspace/entry-accessors.js";
 export { WorkspaceMutations, type WorkspaceMutationsService, type WorkspaceMutationsError, type WorkspaceMutationsOptions, type WorkspaceSettingsReadFailure, type WorkspaceLockfileReadFailure, type WorkspaceStateReadFailure, type WorkspaceSettingsMutationFailure, type WorkspaceLockfileMutationFailure, type WorkspaceStateMutationFailure, type SetSkillArgs, type SetPackArgs, type SetMcpServerArgs, type SetSubagentArgs, type SetRuleArgs, type SetHookArgs, type SetKnowledgeArgs, type PackDirPath, type ExtensionTarget, type ExtensionTargetFor, type LockfileState, type SkillExtensionTarget, type PackExtensionTarget, type McpServerExtensionTarget, type SubagentExtensionTarget, type RuleExtensionTarget, type HookExtensionTarget, type KnowledgeExtensionTarget, } from "./workspace/service-interface.js";
 export { LockfileDecodeError, LockfileIoError, LockfileParseError, LockfileVersionUnsupported, SettingsDecodeError, SettingsIoError, SettingsParseError, SkillDiscoveryRootInvalid, SubagentScanFailed, WorkspaceRootEscape, type LockfileReadError, type SettingsReadError, } from "./workspace/read-model/errors.js";
 export { AcceptedResolutionMissing, CanonicalPathRemovalError, DesiredPackGraphIncomplete, InlineExtensionSourceMissing, InvalidAgentId, LockedSkillMissing, LockEntryEndpointConflict, LockEntryNameInvalid, LockEntrySourceMissing, LockEntrySourceTypeConflict, LockEntryUrlInvalid, PackageContentHashFailed, SettingsEntryMissing, SupersededCanonicalRemovalFailed, SymlinkCreationError, WorkspaceLayoutError, WorkspaceNotInitialized, WorkspaceSourceInvalid, } from "./workspace/errors.js";
 export { setupScopeSupport, setupScopeSupportOutcomes, type SetupScopeSupportCategory, type SetupScopeSupportOutcome, type SetupScopeSupportReasonCode, type SetupScopeSupportStatus, } from "./workspace/setup-scope-support.js";
 export { configuredAgentLifecycleOutcomes, EXTENSION_CONFIGURED_AGENT_POLICY, type ConfiguredAgentLifecycleState, } from "./workspace/configured-agent-outcomes.js";
+export { lockEntrySemanticallyEqual } from "./workspace/accepted-resolution-writer.js";
 //# sourceMappingURL=index.d.ts.map

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";
@@ -85,6 +86,7 @@ export { ExtensionPaths } from "./workspace/extension-paths-service.js";
 export { SettingsWriter } from "./workspace/settings-writer.js";
 export { AcceptedResolutionWriter, } from "./workspace/accepted-resolution-writer.js";
 export { DesiredStateWriter, } from "./workspace/desired-state-writer.js";
+export { settingsEntries, lockEntries } from "./workspace/entry-accessors.js";
 // TRANSITIONAL workspace mutation facade. No CLI handler composes it any
 // more; the domain packages under packages/core still do, and it is removed
 // when the last of them reads and writes through the narrow services above.
@@ -95,4 +97,5 @@ export { LockfileDecodeError, LockfileIoError, LockfileParseError, LockfileVersi
 export { AcceptedResolutionMissing, CanonicalPathRemovalError, DesiredPackGraphIncomplete, InlineExtensionSourceMissing, InvalidAgentId, LockedSkillMissing, LockEntryEndpointConflict, LockEntryNameInvalid, LockEntrySourceMissing, LockEntrySourceTypeConflict, LockEntryUrlInvalid, PackageContentHashFailed, SettingsEntryMissing, SupersededCanonicalRemovalFailed, SymlinkCreationError, WorkspaceLayoutError, WorkspaceNotInitialized, WorkspaceSourceInvalid, } from "./workspace/errors.js";
 export { setupScopeSupport, setupScopeSupportOutcomes, } from "./workspace/setup-scope-support.js";
 export { configuredAgentLifecycleOutcomes, EXTENSION_CONFIGURED_AGENT_POLICY, } from "./workspace/configured-agent-outcomes.js";
+export { lockEntrySemanticallyEqual } from "./workspace/accepted-resolution-writer.js";
 //# sourceMappingURL=index.js.map

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/accepted-canonical-ref.d.ts

@@ -14,6 +14,8 @@ interface AcceptedCanonicalRefArgs {
     readonly workspace: WorkspaceMutationsService;
     readonly type: DesiredExtensionNode["type"];
     readonly name: string;
+    /** Proposed authority when preparing a transition before publishing intent. */
+    readonly desired?: DesiredExtensionNode;
 }
 /** Every failure the accepted-canonical reconstruction functions can produce. */
 export type AcceptedCanonicalRefError = WorkspaceStateReadFailure | LockEntryToRefError | AcceptedResolutionMissing | InlineExtensionSourceMissing | WorkspaceSourceInvalid | PathTraversalDetected | PackageContentHashFailed;
@@ -50,7 +52,7 @@ export declare const acceptedLockedResolutionRef: (args: AcceptedCanonicalRefArg
  * even when its canonical materialization is absent or divergent.
  */
 export declare const acceptedResolutionRef: (args: AcceptedCanonicalRefArgs) => Effect.Effect<Option.Option<ExtensionRef>, AcceptedCanonicalRefError, FileSystem.FileSystem | Path.Path>;
-export declare const acceptedCanonicalObservation: ({ workspace, type, name, }: AcceptedCanonicalRefArgs) => Effect.Effect<Option.Option<AcceptedCanonicalObservation>, AcceptedCanonicalRefError, FileSystem.FileSystem | Path.Path>;
+export declare const acceptedCanonicalObservation: ({ workspace, type, name, desired: proposed, }: AcceptedCanonicalRefArgs) => Effect.Effect<Option.Option<AcceptedCanonicalObservation>, AcceptedCanonicalRefError, FileSystem.FileSystem | Path.Path>;
 export declare const usableAcceptedCanonicalObservation: (args: AcceptedCanonicalRefArgs) => Effect.Effect<Option.Option<UsableAcceptedCanonicalObservation>, AcceptedCanonicalRefError, FileSystem.FileSystem | Path.Path>;
 export declare const usableAcceptedCanonical: (args: AcceptedCanonicalRefArgs) => Effect.Effect<Option.Option<UsableAcceptedCanonical>, AcceptedCanonicalRefError, FileSystem.FileSystem | Path.Path>;
 export declare const usableAcceptedCanonicalRef: (args: AcceptedCanonicalRefArgs) => Effect.Effect<Option.Option<ExtensionRef>, AcceptedCanonicalRefError, FileSystem.FileSystem | Path.Path>;

package/dist/src/workspace/accepted-canonical-ref.js

@@ -188,16 +188,16 @@ const refForDesired = (workspace, desired) => Effect.gen(function* () {
  * even when its canonical materialization is absent or divergent.
  */
 export const acceptedResolutionRef = (args) => Effect.gen(function* () {
-    const graph = yield* args.workspace.getDesiredStateGraph();
-    const desired = graph.nodes.find((node) => node.type === args.type && node.name === args.name);
+    const desired = args.desired ??
+        (yield* args.workspace.getDesiredStateGraph()).nodes.find((node) => node.type === args.type && node.name === args.name);
     if (desired === undefined || desired.identity.startsWith("workspace:")) {
         return Option.none();
     }
     return yield* acceptedLockedResolutionRef(args);
 });
-export const acceptedCanonicalObservation = ({ workspace, type, name, }) => Effect.gen(function* () {
-    const graph = yield* workspace.getDesiredStateGraph();
-    const desired = graph.nodes.find((node) => node.type === type && node.name === name);
+export const acceptedCanonicalObservation = ({ workspace, type, name, desired: proposed, }) => Effect.gen(function* () {
+    const desired = proposed ??
+        (yield* workspace.getDesiredStateGraph()).nodes.find((node) => node.type === type && node.name === name);
     if (desired === undefined)
         return Option.none();
     const accepted = yield* getAcceptedResolution(workspace, type, name);
@@ -223,7 +223,10 @@ export const usableAcceptedCanonical = (args) => Effect.gen(function* () {
     if (Option.isNone(canonical))
         return Option.none();
     const ref = yield* refForDesired(args.workspace, canonical.value.desired);
-    return Option.some({ ...canonical.value, ref });
+    // A usable local acquisition is the accepted copy, even if the original
+    // directory has changed or disappeared. Keep sourcePath as its identity.
+    const retainedRef = ref.refType === "local" ? { ...ref, location: canonical.value.observation.path } : ref;
+    return Option.some({ ...canonical.value, ref: retainedRef });
 });
 export const usableAcceptedCanonicalRef = (args) => usableAcceptedCanonical(args).pipe(Effect.map(Option.map((canonical) => canonical.ref)));
 //# sourceMappingURL=accepted-canonical-ref.js.map

package/dist/src/workspace/accepted-resolution-writer.js

@@ -37,8 +37,6 @@ export const stableCompare = (left, right) => JSON.stringify(normalizeForStableC
 export const lockEntrySemanticallyEqual = (current, next) => current !== undefined && stableCompare(current, next);
 /** Keep the recorded object when the replacement carries the same facts. */
 export const preserveAcceptedResolutionOnNoop = (current, next) => (lockEntrySemanticallyEqual(current, next) && current !== undefined ? current : next);
-/** Types whose semantically unchanged resolution skips the commit entirely. */
-const skipsUnchangedCommit = (type) => type === "skill" || type === "subagent";
 export const makeAcceptedResolutionWriter = (location, mutex) => {
     const current = readLockfileCell(location, location.runtimeDir);
     const commit = (base, next) => commitLockfileSnapshotUpdateAtPath(location.lockPath, base, next);
@@ -48,7 +46,7 @@ export const makeAcceptedResolutionWriter = (location, mutex) => {
             const lockfile = yield* current;
             const accessor = lockEntries[type];
             const previous = accessor.entries(lockfile)[key];
-            if (skipsUnchangedCommit(type) && lockEntrySemanticallyEqual(previous, entry))
+            if (lockEntrySemanticallyEqual(previous, entry))
                 return;
             yield* commit(lockfile, accessor.set(lockfile, key, preserveAcceptedResolutionOnNoop(previous, entry)));
         })).pipe(Effect.withSpan("AcceptedResolutionWriter.setAccepted")),

package/dist/src/workspace/desired-pack-lock.d.ts

@@ -2,17 +2,18 @@ import * as Effect from "effect/Effect";
 import * as FileSystem from "effect/FileSystem";
 import * as Path from "effect/Path";
 import type { Lockfile } from "../lockfile/schema.js";
-import { type DesiredStateGraph } from "./desired-state-graph.js";
+import { type DesiredStateGraph, type ProspectivePackRef } from "./desired-state-graph.js";
 import type { WorkspaceLayout } from "./layout.js";
 interface ValidateDesiredPackLockArgs {
     readonly graph: DesiredStateGraph;
     readonly lockfile: Lockfile;
     readonly layout: WorkspaceLayout;
+    readonly prospectivePacks?: ReadonlyArray<ProspectivePackRef>;
 }
 /**
  * Authorize enabled external Pack manifests against their accepted lock row.
  * Workspace-authored Pack manifests are desired authority and need no lock row.
  */
-export declare const validateDesiredPackLock: ({ graph, lockfile, layout, }: ValidateDesiredPackLockArgs) => Effect.Effect<DesiredStateGraph, never, FileSystem.FileSystem | Path.Path>;
+export declare const validateDesiredPackLock: ({ graph, lockfile, layout, prospectivePacks, }: ValidateDesiredPackLockArgs) => Effect.Effect<DesiredStateGraph, never, FileSystem.FileSystem | Path.Path>;
 export {};
 //# sourceMappingURL=desired-pack-lock.d.ts.map

package/dist/src/workspace/desired-pack-lock.js

@@ -52,7 +52,7 @@ const decodeManifest = Schema.decodeUnknownSync(PackManifestSchema, {
  * Authorize enabled external Pack manifests against their accepted lock row.
  * Workspace-authored Pack manifests are desired authority and need no lock row.
  */
-export const validateDesiredPackLock = ({ graph, lockfile, layout, }) => Effect.gen(function* () {
+export const validateDesiredPackLock = ({ graph, lockfile, layout, prospectivePacks = [], }) => Effect.gen(function* () {
     const fs = yield* FileSystem.FileSystem;
     const path = yield* Path.Path;
     const problems = [];
@@ -82,24 +82,25 @@ export const validateDesiredPackLock = ({ graph, lockfile, layout, }) => Effect.
             continue;
         }
         const manifestPath = path.join(computePackPathsForLayout(path.join, layout, entry.sourceName, identity.owner, identity.name).canonicalPath, PACK_MANIFEST_FILENAME);
-        const readResult = yield* Effect.result(fs.readFileString(manifestPath));
-        if (Result.isFailure(readResult)) {
-            problems.push({
-                type: "pack-manifest-content-mismatch",
-                pack: node.identity,
-                path: manifestPath,
-                status: "missing",
-                acceptedVersion: entry.resolvedVersion,
-                acceptedContentIdentity: entry.manifestContentIdentity,
-            });
-            invalidPacks.add(normalizedPackIdentity(node.identity));
-            continue;
-        }
-        const decoded = Result.try({
-            try: () => decodeManifest(JSON.parse(readResult.success)),
-            catch: () => undefined,
-        });
-        const observedManifest = Result.isSuccess(decoded) && decoded.success !== undefined ? decoded.success : undefined;
+        const prospective = prospectivePacks.find((ref) => ref.owner === identity.owner && ref.pack.name === identity.name);
+        const observedManifest = prospective === undefined
+            ? yield* Effect.gen(function* () {
+                const readResult = yield* Effect.result(fs.readFileString(manifestPath));
+                if (Result.isFailure(readResult))
+                    return undefined;
+                const decoded = Result.try({
+                    try: () => decodeManifest(JSON.parse(readResult.success)),
+                    catch: () => undefined,
+                });
+                return Result.isSuccess(decoded) ? decoded.success : undefined;
+            })
+            : {
+                owner: prospective.owner,
+                type: "pack",
+                name: prospective.pack.name,
+                version: prospective.version,
+                dependencies: prospective.pack.dependencies,
+            };
         const observedContentIdentity = observedManifest === undefined
             ? undefined
             : computePackManifestContentIdentity(observedManifest);
@@ -109,7 +110,7 @@ export const validateDesiredPackLock = ({ graph, lockfile, layout, }) => Effect.
                 type: "pack-manifest-content-mismatch",
                 pack: node.identity,
                 path: manifestPath,
-                status: "changed",
+                status: observedManifest === undefined ? "missing" : "changed",
                 acceptedVersion: entry.resolvedVersion,
                 acceptedContentIdentity: entry.manifestContentIdentity,
                 ...(observedManifest === undefined || observedContentIdentity === undefined

package/dist/src/workspace/desired-state-graph.js

@@ -242,6 +242,8 @@ export const buildDesiredStateGraph = ({ baseDir, settings, layout, prospectiveP
         });
         const workspacePack = isWorkspaceSourceLocator(entry.source);
         const configuredRegistrySource = registryLocator(entry.source)?.sourceName ?? "agentxm";
+        if (entry.enabled === false)
+            continue;
         const manifestPath = path.join(layout === undefined
             ? path.join(baseDir, workspacePack
                 ? configuredAuthoredDirectory(settings, "pack")
@@ -308,7 +310,7 @@ export const buildDesiredStateGraph = ({ baseDir, settings, layout, prospectiveP
                 identity: dependencyIdentity,
                 authority: "sourced",
                 source: `${fqn}@${constraint}`,
-                enabled: entry.enabled !== false,
+                enabled: true,
                 constraint,
                 origin: {
                     type: "pack",
@@ -316,7 +318,7 @@ export const buildDesiredStateGraph = ({ baseDir, settings, layout, prospectiveP
                     manifestPath: path.relative(baseDir, manifestPath),
                     source: fqn,
                     constraint,
-                    enabled: entry.enabled !== false,
+                    enabled: true,
                 },
             });
         }

package/dist/src/workspace/desired-state-reader.d.ts

@@ -11,15 +11,21 @@ import type * as FileSystem from "effect/FileSystem";
 import * as Layer from "effect/Layer";
 import type * as Path from "effect/Path";
 import { type DesiredStateGraph, type ProspectivePackRef } from "./desired-state-graph.js";
+import type { Settings } from "../settings/index.js";
+import type { Lockfile } from "../lockfile/index.js";
 import { DesiredPackGraphIncomplete } from "./errors.js";
 import { WorkspaceLocation, type WorkspaceLocationService } from "./location.js";
 import type { ExtensionTarget, WorkspaceStateReadFailure } from "./service-interface.js";
 import { SettingsReader, type SettingsReaderService } from "./settings-reader.js";
+/** Authoritative inputs for evaluating a candidate without publishing it. */
+export interface DesiredStateGraphInputs {
+    readonly settings?: Settings;
+    readonly acceptedResolutions?: Lockfile;
+    readonly prospectivePacks?: ReadonlyArray<ProspectivePackRef>;
+}
 export interface DesiredStateReaderService {
     /** Build desired extension state from settings and installed or prospective Pack manifests. */
-    readonly graph: (options?: {
-        readonly prospectivePacks?: ReadonlyArray<ProspectivePackRef>;
-    }) => Effect.Effect<DesiredStateGraph, WorkspaceStateReadFailure, FileSystem.FileSystem | Path.Path>;
+    readonly graph: (options?: DesiredStateGraphInputs) => Effect.Effect<DesiredStateGraph, WorkspaceStateReadFailure, FileSystem.FileSystem | Path.Path>;
     /** Whether an installed Pack's dependency maps reference the target. */
     readonly isRequiredByInstalledPack: (target: ExtensionTarget) => Effect.Effect<boolean, WorkspaceStateReadFailure | DesiredPackGraphIncomplete, FileSystem.FileSystem | Path.Path>;
 }

package/dist/src/workspace/desired-state-reader.js

@@ -19,7 +19,7 @@ export class DesiredStateReader extends ServiceMap.Service()("@agentxm/workspace
 }
 export const makeDesiredStateReader = (location, settings) => {
     const graph = (options) => Effect.gen(function* () {
-        const current = yield* settings.settings;
+        const current = options?.settings ?? (yield* settings.settings);
         const configuredSources = yield* settings.configuredSources;
         const layout = yield* Ref.get(location.layout);
         const registryAuthorities = Object.fromEntries(configuredSources.flatMap((source) => source.type === "registry" ? [[source.name, source.location]] : []));
@@ -32,8 +32,15 @@ export const makeDesiredStateReader = (location, settings) => {
                 ? {}
                 : { prospectivePacks: options.prospectivePacks }),
         });
-        const lockfile = yield* readLockfileCell(location, location.runtimeDir);
-        return yield* validateDesiredPackLock({ graph: built, lockfile, layout });
+        const lockfile = options?.acceptedResolutions ?? (yield* readLockfileCell(location, location.runtimeDir));
+        return yield* validateDesiredPackLock({
+            graph: built,
+            lockfile,
+            layout,
+            ...(options?.prospectivePacks === undefined
+                ? {}
+                : { prospectivePacks: options.prospectivePacks }),
+        });
     }).pipe(Effect.withSpan("DesiredStateReader.graph"));
     return {
         graph,

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

@@ -28,7 +28,8 @@ import type { ReadModelRecordRow } from "./read-model-record-types.js";
 import type { WorkspaceScope } from "@agentxm/extension-model/unstable/workspace-scope";
 import type { ExtensionInventory } from "./read-model/extensions/inventory.js";
 import type { ResolvedKnowledgeDiscoveryConfig } from "../knowledge/discovery-config.js";
-import type { DesiredStateGraph, ProspectivePackRef } from "./desired-state-graph.js";
+import type { DesiredStateGraphInputs } from "./desired-state-reader.js";
+import type { DesiredStateGraph } from "./desired-state-graph.js";
 import type { AbsolutePath } from "@agentxm/extension-model/unstable/path-types";
 import type { WorkspaceLayout } from "./layout.js";
 import type { ExtensionPathSource } from "./extension-paths.js";
@@ -105,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 {
@@ -211,9 +212,7 @@ export interface WorkspaceMutationsService {
     /** Probe lockfile state for policy decisions: ok | missing | invalid. */
     readonly getLockfileState: () => Effect.Effect<LockfileState, LockfileValidationError | WorkspaceRootEscape>;
     /** Build desired extension state from settings and installed or prospective Pack manifests. */
-    readonly getDesiredStateGraph: (options?: {
-        readonly prospectivePacks?: ReadonlyArray<ProspectivePackRef>;
-    }) => Effect.Effect<DesiredStateGraph, WorkspaceStateReadFailure>;
+    readonly getDesiredStateGraph: (options?: DesiredStateGraphInputs) => Effect.Effect<DesiredStateGraph, WorkspaceStateReadFailure>;
     /** Merged sources from project, user-scope, and built-in defaults. Cached per workspace lifetime. */
     readonly getConfiguredSources: () => Effect.Effect<ReadonlyArray<SourceHostConfig>, WorkspaceSettingsReadFailure>;
     /** Lookup a source by name from the merged sources list. */

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,20 +4,20 @@
     "url": "https://github.com/agentxm/axm/issues"
   },
   "dependencies": {
-    "@agentxm/agent-integration": "^0.29.4",
-    "@agentxm/extension-content": "^0.29.4",
-    "@agentxm/extension-model": "^0.29.4",
-    "@agentxm/registry-protocol": "^0.29.4",
-    "@agentxm/workspace-transactions": "^0.29.4",
+    "@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",
-    "smol-toml": "1.6.1",
+    "smol-toml": "^1.7.1",
     "yaml": "^2.9.0"
   },
   "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.29.4",
+    "@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",
@@ -31,19 +31,16 @@
   },
   "exports": {
     ".": {
-      "axm-source": "./src/index.ts",
-      "default": "./dist/src/index.js",
-      "types": "./dist/src/index.d.ts"
+      "types": "./dist/src/index.d.ts",
+      "default": "./dist/src/index.js"
     },
     "./live": {
-      "axm-source": "./src/live.ts",
-      "default": "./dist/src/live.js",
-      "types": "./dist/src/live.d.ts"
+      "types": "./dist/src/live.d.ts",
+      "default": "./dist/src/live.js"
     },
     "./testing": {
-      "axm-source": "./src/testing.ts",
-      "default": "./dist/src/testing.js",
-      "types": "./dist/src/testing.d.ts"
+      "types": "./dist/src/testing.d.ts",
+      "default": "./dist/src/testing.js"
     }
   },
   "files": [
@@ -66,5 +63,5 @@
   },
   "sideEffects": false,
   "type": "module",
-  "version": "0.29.4"
+  "version": "0.30.2"
 }