@agentxm/extension-lifecycle 0.28.4-bootstrap.0 → 0.28.5

package/dist/src/configured-entry-resolution.js

@@ -122,7 +122,9 @@ export const resolveConfiguredRegistryEntry = (name, source, expectedType, relea
             detail: `Configured ${expectedType} "${name}" uses a ${pluralType} Registry source`,
         });
     }
-    if (parsedPattern?.name !== undefined && parsedPattern.name !== name) {
+    if (expectedType !== "mcp-server" &&
+        parsedPattern?.name !== undefined &&
+        parsedPattern.name !== name) {
         return yield* new ExtensionLifecycleFailed({
             category: "validation",
             detail: `Configured ${expectedType} "${name}" points to Registry extension "${parsedPattern.name}"`,
@@ -136,13 +138,14 @@ export const resolveConfiguredRegistryEntry = (name, source, expectedType, relea
         });
     }
     const versionRange = Option.fromUndefinedOr(parsedPattern?.versionRange);
+    const registryName = expectedType === "mcp-server" ? (parsedPattern?.name ?? name) : name;
     const workspace = yield* WorkspaceMutations;
     const acceptedRef = yield* acceptedResolutionRef({
         workspace,
         type: expectedType,
         name,
     });
-    const accepted = Option.flatMap(acceptedRef, (ref) => ref.refType === "registry" && ref.owner === owner && ref.name === name
+    const accepted = Option.flatMap(acceptedRef, (ref) => ref.refType === "registry" && ref.owner === owner && ref.name === registryName
         ? Option.some({
             version: ref.version,
             publisherBindingId: ref.publisherBindingId,
@@ -150,7 +153,7 @@ export const resolveConfiguredRegistryEntry = (name, source, expectedType, relea
         : Option.none());
     const providers = yield* SourceHostProviders;
     const resolution = yield* providers.resolveNamedRegistry(resolvedSource, {
-        name,
+        name: registryName,
         type: expectedType,
         owner,
         versionRange,

package/dist/src/hooks/manager.js

@@ -11,7 +11,7 @@ import * as Option from "effect/Option";
 import * as Path from "effect/Path";
 import * as Schema from "effect/Schema";
 import * as Semaphore from "effect/Semaphore";
-import { HookConfigInvalid, HookDefinitionInvalid, HookInstallStateMissing, HookIoFailed, activeContributors, applyProjectionPlans, planAggregateProjection, runWithTransientFileBackup, reconcileManagedRegionFile, managedHookCommands, readManagedHookCommands, updateHooksJson, evaluateHookAgentOutcome, WriteBackupRetained, resolveInstructionsConfig, } from "@agentxm/extension-workspace";
+import { HookConfigInvalid, HookDefinitionInvalid, HookInstallStateMissing, HookIoFailed, activeContributors, applyProjectionPlans, planAggregateProjection, runWithTransientFileBackup, reconcileManagedRegionFile, projectionGeneration, managedHookCommands, readManagedHookCommands, updateHooksJson, evaluateHookAgentOutcome, WriteBackupRetained, resolveInstructionsConfig, } from "@agentxm/extension-workspace";
 import { AGENTS as CAPABILITY_AGENTS, installable, } from "@agentxm/extension-model/unstable/agent-capabilities";
 import { computePackageContentHash } from "@agentxm/workspace-state";
 import { computeMaterializedTreeIntegrity } from "@agentxm/workspace-state";
@@ -437,12 +437,25 @@ export const HookManagerLive = Layer.effect(HookManager, Effect.gen(function* ()
         const rendered = input.contributors
             .map((hook) => `### ${hook.manifest.title ?? hook.name}\n\nFor agents without a usable native hook mapping (${hook.fallbackAgentIds.join(", ")}), treat this as a managed advisory rule. After the matching lifecycle event (${hook.manifest.bindings.map((binding) => binding.on).join(", ")}), run \`${hook.command}\` and address any findings before continuing.`)
             .join("\n\n");
+        const generation = projectionGeneration([
+            "hook-fallback-region-v1",
+            target.workspaceRelative,
+            HOOK_FALLBACKS_REGION_OWNER,
+            ...input.contributors.flatMap((contributor) => [
+                contributor.name,
+                contributor.marker,
+                contributor.command,
+                JSON.stringify(contributor.fallbackAgentIds),
+                JSON.stringify(contributor.manifest),
+            ]),
+        ]);
         const { changed, observedRegion } = yield* provide(reconcileManagedRegionFile({
             targetPath: target.targetPath,
             displayPath: target.workspaceRelative,
             region: HOOK_FALLBACKS_REGION,
             owner: HOOK_FALLBACKS_REGION_OWNER,
             rendered,
+            generation,
             ...(options?.dryRun === undefined ? {} : { dryRun: options.dryRun }),
             unsupportedTargetDetail: `Hook fallback target does not support managed regions: ${target.workspaceRelative}`,
         }));
@@ -464,12 +477,6 @@ export const HookManagerLive = Layer.effect(HookManager, Effect.gen(function* ()
                 present: Option.isSome(observedRegion),
                 current: !changed,
                 expectedContributors: input.contributors.map(({ marker }) => marker),
-                observedContributors: Option.match(observedRegion, {
-                    onNone: () => [],
-                    onSome: (region) => input.contributors
-                        .filter(({ command }) => region.includes(command))
-                        .map(({ marker }) => marker),
-                }),
             },
         };
     });

package/dist/src/index.d.ts

@@ -23,7 +23,7 @@ export type { InstallResult } from "./skills/operations/install-result.js";
 export { uninstallSkill, type UninstallSkillOperation, type UninstallSkillOperationArgs, } from "./skills/operations/uninstall.js";
 export { enableSkill, type EnableSkillOperation } from "./skills/operations/enable.js";
 export { disableSkill, type DisableSkillOperation } from "./skills/operations/disable.js";
-export { installMcpServer, type InstallMcpServerOperation, type InstallMcpServerOperationArgs, } from "./mcps/operations/install.js";
+export { collectSecretInputNames, deleteMcpSecrets, installMcpServer, mcpSecretAccount, readMcpServerManifest, type InstallMcpServerOperation, type InstallMcpServerOperationArgs, } from "./mcps/operations/install.js";
 export { uninstallMcpServer, type UninstallMcpServerOperation, type UninstallMcpServerOperationArgs, } from "./mcps/operations/uninstall.js";
 export { enableMcpServer, type EnableMcpServerOperation } from "./mcps/operations/enable.js";
 export { disableMcpServer, type DisableMcpServerOperation } from "./mcps/operations/disable.js";

package/dist/src/index.js

@@ -24,7 +24,7 @@ export { uninstallSkill, } from "./skills/operations/uninstall.js";
 export { enableSkill } from "./skills/operations/enable.js";
 export { disableSkill } from "./skills/operations/disable.js";
 // MCP server lifecycle operations
-export { installMcpServer, } from "./mcps/operations/install.js";
+export { collectSecretInputNames, deleteMcpSecrets, installMcpServer, mcpSecretAccount, readMcpServerManifest, } from "./mcps/operations/install.js";
 export { uninstallMcpServer, } from "./mcps/operations/uninstall.js";
 export { enableMcpServer } from "./mcps/operations/enable.js";
 export { disableMcpServer } from "./mcps/operations/disable.js";

package/dist/src/knowledge/manager.js

@@ -11,7 +11,7 @@ import * as Schema from "effect/Schema";
 import * as Scope from "effect/Scope";
 import * as Result from "effect/Result";
 import { PlatformError } from "effect/PlatformError";
-import { KnowledgeDefinitionInvalid, KnowledgeDesiredStateUnreconcilable, KnowledgeInstallStateMissing, KnowledgeIoFailed, KnowledgeObservableContractViolated, KnowledgeResolutionMissing, KnowledgeUnavailable, applyProjectionPlans, planAggregateProjection, requireCompleteGraph, KNOWLEDGE_REGION_OWNER, reconcileKnowledgeDiscovery, observedKnowledgeContributors, resolveInstructionsConfig, } from "@agentxm/extension-workspace";
+import { KnowledgeDefinitionInvalid, KnowledgeDesiredStateUnreconcilable, KnowledgeInstallStateMissing, KnowledgeIoFailed, KnowledgeObservableContractViolated, KnowledgeResolutionMissing, KnowledgeUnavailable, applyProjectionPlans, planAggregateProjection, requireCompleteGraph, KNOWLEDGE_REGION_OWNER, reconcileKnowledgeDiscovery, resolveInstructionsConfig, } from "@agentxm/extension-workspace";
 import { canReuseInstalledPackage, materializeExternalPackage } from "@agentxm/extension-workspace";
 import { materializeRegistryPackage } from "../registry-materialization.js";
 import { computeExtensionPathsForLayout, extensionPathSourceFromLockEntry, } from "@agentxm/workspace-state";
@@ -351,10 +351,6 @@ export const KnowledgeManagerLive = Layer.effect(KnowledgeManager, Effect.gen(fu
                     present: Option.isSome(result.observedRegion),
                     current: !result.changed,
                     expectedContributors: input.contributors.map(({ owner, name }) => `${owner}/knowledge/${name}`),
-                    observedContributors: Option.match(result.observedRegion, {
-                        onNone: () => [],
-                        onSome: observedKnowledgeContributors,
-                    }),
                 }))),
                 apply: (input) => runKnowledgeProjectionAdapter({
                     bundles: input.contributors,

package/dist/src/mcps/manager.js

@@ -15,7 +15,7 @@ import * as Option from "effect/Option";
 import { McpConfigIoFailed, McpInstallStateMissing, McpRegistryOnlyInstall, removeMcpServerFromManifest, applyProjectionPlans, planSingletonProjection, } from "@agentxm/extension-workspace";
 import { McpServerManager } from "@agentxm/extension-workspace";
 import { configuredMcpServersToDiskRefs } from "@agentxm/extension-workspace";
-import { WorkspaceMutations } from "@agentxm/workspace-state";
+import { mcpRegistryResolutionKey, WorkspaceMutations } from "@agentxm/workspace-state";
 import { canReuseInstalledPackage } from "@agentxm/extension-workspace";
 import { materializeRegistryPackageWithTreeIntegrity } from "../registry-materialization.js";
 import { computeExtensionPathsForLayout } from "@agentxm/workspace-state";
@@ -55,6 +55,7 @@ export const McpServerManagerLive = Layer.effect(McpServerManager, Effect.gen(fu
     const fsPathLayer = Layer.mergeAll(Layer.succeed(FileSystem.FileSystem, fs), Layer.succeed(Path.Path, path), Layer.succeed(HttpClient.HttpClient, httpClient));
     const provide = (effect) => Effect.provide(effect, fsPathLayer);
     const lastTreeIntegrities = new Map();
+    const pendingRemoval = new Map();
     const materializeInstall = Effect.fn("McpServerManager.materializeInstall")(function* ({ ref, force }) {
         if (ref.refType !== "registry") {
             return yield* new McpRegistryOnlyInstall({
@@ -64,7 +65,11 @@ export const McpServerManagerLive = Layer.effect(McpServerManager, Effect.gen(fu
         }
         const registryRef = ref;
         const canonicalPath = computeExtensionPathsForLayout(path.join, ws.layout, registryRef, "mcps", registryRef.name).canonicalPath;
-        const lockedEntry = yield* ws.getLockedMcpServer(registryRef.server.name);
+        const lockedEntry = yield* ws.getLockedMcpServer(mcpRegistryResolutionKey({
+            authority: registryRef.source.location,
+            owner: registryRef.owner,
+            name: registryRef.server.name,
+        }));
         const lockedVersion = acceptedRegistryVersionForRef(lockedEntry, registryRef);
         const useExisting = yield* provide(canReuseInstalledPackage({
             installedPath: canonicalPath,
@@ -97,6 +102,18 @@ export const McpServerManagerLive = Layer.effect(McpServerManager, Effect.gen(fu
         lastTreeIntegrities.set(registryRef.server.name, materialized.treeIntegrity);
     }, Effect.asVoid);
     const makeMaterializeRemoval = (retainCanonical) => Effect.fn("McpServerManager.materializeRemoval")(function* ({ target }) {
+        const graph = yield* ws.getDesiredStateGraph();
+        const desiredNode = graph.nodes.find((node) => node.type === "mcp-server" && node.name === target.name);
+        const closure = desiredNode === undefined || desiredNode.authority === "inline"
+            ? undefined
+            : graph.mcpSourceClosures.find((candidate) => candidate.identity === desiredNode.identity);
+        const retainShared = closure !== undefined && closure.localNames.some((name) => name !== target.name);
+        pendingRemoval.set(target.name, {
+            ...(desiredNode === undefined || desiredNode.authority === "inline"
+                ? {}
+                : { resolutionKey: desiredNode.identity }),
+            retainShared,
+        });
         const configuredAgents = yield* ws.getConfiguredAgents();
         yield* applyProjectionPlans(configuredAgents.map((agentId) => planSingletonProjection({
             unitId: "mcp-server:native-config-entry",
@@ -119,7 +136,7 @@ export const McpServerManagerLive = Layer.effect(McpServerManager, Effect.gen(fu
                 })).pipe(Effect.asVoid),
             },
         })));
-        if (retainCanonical)
+        if (retainCanonical || retainShared)
             return;
         const canonical = yield* provide(acceptedCanonicalObservation({
             workspace: ws,
@@ -178,6 +195,11 @@ export const McpServerManagerLive = Layer.effect(McpServerManager, Effect.gen(fu
                 const lockEntry = buildMcpServerLockEntry(registryRef, treeIntegrity);
                 return ws.setMcpServer({
                     name: ref.server.name,
+                    resolutionKey: mcpRegistryResolutionKey({
+                        authority: registryRef.source.location,
+                        owner: registryRef.owner,
+                        name: registryRef.server.name,
+                    }),
                     lockEntry,
                     versionRange,
                 });
@@ -200,14 +222,26 @@ export const McpServerManagerLive = Layer.effect(McpServerManager, Effect.gen(fu
                 const lockEntry = buildMcpServerLockEntry(registryRef, treeIntegrity);
                 return ws.setMcpServerLock({
                     name: ref.server.name,
+                    resolutionKey: mcpRegistryResolutionKey({
+                        authority: registryRef.source.location,
+                        owner: registryRef.owner,
+                        name: registryRef.server.name,
+                    }),
                     lockEntry,
                     versionRange: Option.none(),
                 });
             }), Effect.withSpan("McpServerManager.upsertLockfileEntry"));
         },
-        removeLockfileEntry: ({ target }) => ws
-            .removeMcpServerLock(target.name)
-            .pipe(Effect.withSpan("McpServerManager.removeLockfileEntry")),
+        removeLockfileEntry: ({ target }) => {
+            const removal = pendingRemoval.get(target.name);
+            pendingRemoval.delete(target.name);
+            if (removal?.retainShared === true || removal?.resolutionKey === undefined) {
+                return Effect.void.pipe(Effect.withSpan("McpServerManager.removeLockfileEntry"));
+            }
+            return ws
+                .removeMcpServerLock(removal.resolutionKey)
+                .pipe(Effect.withSpan("McpServerManager.removeLockfileEntry"));
+        },
     };
 }));
 //# sourceMappingURL=manager.js.map

package/dist/src/mcps/operations/install.d.ts

@@ -17,12 +17,15 @@ import type { StepFailure } from "@agentxm/workspace-operations";
 import type { JobStepResult, Operation } from "@agentxm/workspace-operations";
 import { WorkspaceMutations } from "@agentxm/workspace-state";
 import type { McpServerExtensionRef } from "@agentxm/extension-model/unstable/extensions/refs/mcp-server";
+import { type McpServerManifest } from "@agentxm/extension-model/unstable/mcps/manifest-schema";
 import { LifecycleFailureAdapter } from "../../failure-adapter.js";
 /**
  * Args for the install-mcp-server operation.
  */
 export type InstallMcpServerOperationArgs = {
     readonly ref: McpServerExtensionRef;
+    /** Local connection identity and exact agent-native MCP key. */
+    readonly localName?: string;
     readonly force: boolean;
     /** Explicitly permit a workspace-authored relocation during reconciliation. */
     readonly allowWorkspaceSourceTransition?: boolean;
@@ -49,6 +52,25 @@ export type InstallMcpServerOperationArgs = {
  * @experimental This API is unstable and may change without notice.
  */
 export type InstallMcpServerOperation = Operation<"install-mcp-server", InstallMcpServerOperationArgs>;
+export declare const mcpSecretAccount: (args: {
+    readonly scopeRoot: string;
+    readonly localName: string;
+    readonly sourceIdentity: string;
+    readonly inputName: string;
+}) => string;
+export type McpSecretDeletionOutcome = {
+    readonly _tag: "deleted";
+    readonly inputName: string;
+} | {
+    readonly _tag: "absent";
+    readonly inputName: string;
+} | {
+    readonly _tag: "failed";
+    readonly inputName: string;
+};
+export declare const collectSecretInputNames: (manifest: McpServerManifest) => ReadonlySet<string>;
+export declare const readMcpServerManifest: (canonicalPath: string) => Effect.Effect<Option.Option<McpServerManifest>, never, FileSystem.FileSystem | Path.Path>;
+export declare const deleteMcpSecrets: (identity: Omit<Parameters<typeof mcpSecretAccount>[0], "inputName">, secretNames: ReadonlySet<string>) => Effect.Effect<ReadonlyArray<McpSecretDeletionOutcome>>;
 /**
  * Install-mcp-server operation handler.
  *

package/dist/src/mcps/operations/install.js

@@ -20,8 +20,9 @@ import * as Array from "effect/Array";
 import * as Effect from "effect/Effect";
 import * as Option from "effect/Option";
 import * as Schema from "effect/Schema";
+import { createHash } from "node:crypto";
 import { CodingAgentRepository, McpSharedTargetConflict, applyProjectionPlansWithResults, planSingletonProjection, inspectAgentMcpServer, sharedMcpTargetPolicyConflict, } from "@agentxm/extension-workspace";
-import { isPathSafe } from "@agentxm/workspace-state";
+import { isPathSafe, mcpRegistryResolutionKey } from "@agentxm/workspace-state";
 import { acceptedRegistryVersionForRef, validateExactResolvedVersion, } from "@agentxm/workspace-state";
 import { appendWarningsToMessage } from "@agentxm/workspace-operations";
 import { WorkspaceMutations } from "@agentxm/workspace-state";
@@ -55,7 +56,9 @@ const buildLockEntry = (ref, treeIntegrity) => ({
     treeIntegrity,
 });
 const MCP_SECRET_SERVICE = "axm-mcp";
-const mcpSecretAccount = (serverName, inputName) => `${serverName}:${inputName}`;
+export const mcpSecretAccount = (args) => createHash("sha256")
+    .update([args.scopeRoot, args.localName, args.sourceIdentity, args.inputName].join("\0"))
+    .digest("hex");
 const keyringModuleSpecifier = ["@napi-rs", "keyring"].join("/");
 const loadKeyringEntry = Effect.tryPromise({
     try: async () => {
@@ -64,22 +67,22 @@ const loadKeyringEntry = Effect.tryPromise({
     },
     catch: () => undefined,
 });
-const saveMcpSecret = (serverName, inputName, value) => Effect.gen(function* () {
+const saveMcpSecret = (account, inputName, value) => Effect.gen(function* () {
     const Entry = yield* loadKeyringEntry;
     return yield* Effect.try({
         try: () => {
-            const entry = new Entry(MCP_SECRET_SERVICE, mcpSecretAccount(serverName, inputName));
+            const entry = new Entry(MCP_SECRET_SERVICE, account);
             entry.setPassword(value);
             return { _tag: "saved", inputName };
         },
         catch: () => undefined,
     });
 }).pipe(Effect.catch(() => Effect.succeed({ _tag: "failed", inputName })));
-const loadMcpSecret = (serverName, inputName) => Effect.gen(function* () {
+const loadMcpSecret = (account) => Effect.gen(function* () {
     const Entry = yield* loadKeyringEntry;
     return yield* Effect.try({
         try: () => {
-            const entry = new Entry(MCP_SECRET_SERVICE, mcpSecretAccount(serverName, inputName));
+            const entry = new Entry(MCP_SECRET_SERVICE, account);
             return Option.fromNullOr(entry.getPassword());
         },
         catch: () => undefined,
@@ -116,7 +119,7 @@ const collectRequiredInputNames = (manifest) => {
     }
     return names;
 };
-const collectSecretInputNames = (manifest) => {
+export const collectSecretInputNames = (manifest) => {
     const names = new Set();
     const add = (input) => {
         const name = maybeSecretInputName(input);
@@ -179,7 +182,7 @@ const installFromRegistry = (ref, reuse) => Effect.gen(function* () {
     }
     return canonicalPath;
 });
-const readManifest = (canonicalPath) => Effect.gen(function* () {
+export const readMcpServerManifest = (canonicalPath) => Effect.gen(function* () {
     const fs = yield* FileSystem.FileSystem;
     const path = yield* Path.Path;
     const manifestPath = path.join(canonicalPath, MCP_SERVER_MANIFEST_FILENAME);
@@ -204,8 +207,8 @@ const isNothingRunnableManifest = (manifest) => Option.match(manifest, {
     onSome: (value) => (value.server.packages === undefined || value.server.packages.length === 0) &&
         (value.server.remotes === undefined || value.server.remotes.length === 0),
 });
-const loadStoredMcpSecrets = (serverName, secretNames) => Effect.gen(function* () {
-    const entries = yield* Effect.forEach(secretNames, (name) => loadMcpSecret(serverName, name).pipe(Effect.map((value) => ({ name, value }))), { concurrency: "unbounded" });
+const loadStoredMcpSecrets = (identity, secretNames) => Effect.gen(function* () {
+    const entries = yield* Effect.forEach(secretNames, (name) => loadMcpSecret(mcpSecretAccount({ ...identity, inputName: name })).pipe(Effect.map((value) => ({ name, value }))), { concurrency: "unbounded" });
     const loaded = {};
     for (const { name, value } of entries) {
         if (Option.isSome(value))
@@ -213,12 +216,24 @@ const loadStoredMcpSecrets = (serverName, secretNames) => Effect.gen(function* (
     }
     return loaded;
 });
-const persistMcpSecrets = (serverName, secretNames, values) => Effect.forEach(secretNames, (name) => {
+const persistMcpSecrets = (identity, secretNames, values) => Effect.forEach(secretNames, (name) => {
     const value = values[name];
     return value === undefined
         ? Effect.succeed({ _tag: "skipped", inputName: name })
-        : saveMcpSecret(serverName, name, value);
+        : saveMcpSecret(mcpSecretAccount({ ...identity, inputName: name }), name, value);
 }, { concurrency: "unbounded" });
+export const deleteMcpSecrets = (identity, secretNames) => Effect.forEach(secretNames, (inputName) => Effect.gen(function* () {
+    const Entry = yield* loadKeyringEntry;
+    return yield* Effect.try({
+        try: () => {
+            const entry = new Entry(MCP_SECRET_SERVICE, mcpSecretAccount({ ...identity, inputName }));
+            return entry.deletePassword()
+                ? { _tag: "deleted", inputName }
+                : { _tag: "absent", inputName };
+        },
+        catch: () => undefined,
+    });
+}).pipe(Effect.catch(() => Effect.succeed({ _tag: "failed", inputName }))), { concurrency: "unbounded" });
 const redactSettingsEnv = (values, secretNames) => {
     const redacted = {};
     for (const [name, value] of Object.entries(values)) {
@@ -398,9 +413,10 @@ const syncConfiguredAgentsOnInstall = (args) => Effect.gen(function* () {
  * then update lockfile/settings.
  */
 export const installMcpServer = (op) => Effect.gen(function* () {
-    const adapter = yield* LifecycleFailureAdapter;
     const ws = yield* WorkspaceMutations;
+    const path = yield* Path.Path;
     const { ref } = op.args;
+    const localName = op.args.localName ?? ref.server.name;
     if (ref.refType !== "registry" && ref.refType !== "workspace") {
         return yield* new ExtensionLifecycleFailed({
             category: "usage",
@@ -415,8 +431,26 @@ export const installMcpServer = (op) => Effect.gen(function* () {
     }
     const strictAgentSync = Option.getOrElse(op.args.strictAgentSync ?? Option.none(), () => false);
     const env = Option.getOrElse(op.args.env ?? Option.none(), () => ({}));
+    const resolutionKey = ref.refType === "registry"
+        ? mcpRegistryResolutionKey({
+            authority: ref.source.location,
+            owner: ref.owner,
+            name: ref.server.name,
+        })
+        : undefined;
+    const sourceIdentity = resolutionKey ?? `workspace:${ref.owner}/mcps/${ref.server.name}`;
+    const desiredGraph = yield* ws.getDesiredStateGraph();
+    const existingLocalNode = desiredGraph.nodes.find((node) => node.type === "mcp-server" && node.name === localName);
+    if (existingLocalNode !== undefined &&
+        (existingLocalNode.authority === "inline" || existingLocalNode.identity !== sourceIdentity)) {
+        return yield* new ExtensionLifecycleFailed({
+            category: "conflict",
+            detail: `Local MCP name "${localName}" is already owned by a different source`,
+        });
+    }
+    const existingClosure = desiredGraph.mcpSourceClosures.find((closure) => closure.identity === sourceIdentity);
     const lockedVersion = ref.refType === "registry"
-        ? acceptedRegistryVersionForRef(yield* ws.getLockedMcpServer(ref.server.name), ref)
+        ? acceptedRegistryVersionForRef(yield* ws.getLockedMcpServer(resolutionKey ?? ""), ref)
         : undefined;
     const canonicalPath = ref.refType === "registry"
         ? yield* installFromRegistry(ref, { force: op.args.force, lockedVersion })
@@ -446,7 +480,7 @@ export const installMcpServer = (op) => Effect.gen(function* () {
             }
             return ref.location;
         });
-    const manifest = yield* readManifest(canonicalPath);
+    const manifest = yield* readMcpServerManifest(canonicalPath);
     const nothingRunnable = isNothingRunnableManifest(manifest);
     const secretNames = Option.match(manifest, {
         onNone: () => new Set(),
@@ -459,8 +493,13 @@ export const installMcpServer = (op) => Effect.gen(function* () {
         ? buildLockEntry(ref, yield* computeMaterializedTreeIntegrity(canonicalPath))
         : undefined;
     const currentMcpServers = yield* ws.getConfiguredMcpServerEntries();
-    const currentEntry = currentMcpServers[ref.server.name];
-    const storedSecrets = yield* loadStoredMcpSecrets(ref.server.name, secretNames);
+    const currentEntry = currentMcpServers[localName];
+    const secretIdentity = {
+        scopeRoot: path.resolve(ws.baseDir),
+        localName,
+        sourceIdentity,
+    };
+    const storedSecrets = yield* loadStoredMcpSecrets(secretIdentity, secretNames);
     const mergedEnv = { ...storedSecrets, ...(currentEntry?.env ?? {}), ...env };
     // Under --non-interactive there is nobody to prompt, so a required input
     // that nothing supplied would otherwise install a server that cannot start.
@@ -475,7 +514,7 @@ export const installMcpServer = (op) => Effect.gen(function* () {
     if (missingInputs.length > 0 && op.args.nonInteractive) {
         return yield* new ExtensionLifecycleFailed({
             category: "usage",
-            detail: `${ref.server.name} needs ${missingInputs.join(", ")}, and --non-interactive cannot prompt for them`,
+            detail: `${localName} needs ${missingInputs.join(", ")}, and --non-interactive cannot prompt for them`,
             suggestions: [
                 {
                     description: "Supply each required input on the command line",
@@ -494,50 +533,78 @@ export const installMcpServer = (op) => Effect.gen(function* () {
         enabled,
         ...(agents === undefined ? {} : { agents }),
     };
-    const agentSync = yield* syncConfiguredAgentsOnInstall({
-        wsBaseDir: ws.baseDir,
-        scope: ws.scope,
-        strict: strictAgentSync,
-        serverName: ref.server.name,
-        canonicalPath,
-        owner: ref.owner,
-        resolvedVersion: ref.version,
-        nothingRunnable,
-        enabled,
-        configValues: preserveSecretReferences(mergedEnv, secretNames),
-        entry: settingsEntry,
-    });
-    const secretPersistence = yield* persistMcpSecrets(ref.server.name, secretNames, mergedEnv);
-    const secretWarnings = secretPersistence.flatMap((outcome) => outcome._tag === "failed"
-        ? [`${outcome.inputName} could not be saved to the system keychain`]
-        : []);
     const writeEffect = op.args.skipStateWrites === true
         ? Effect.void
         : Option.getOrElse(op.args.skipSettings, () => false)
             ? lockEntry === undefined
                 ? Effect.void
                 : ws.setMcpServerLock({
-                    name: ref.server.name,
+                    name: resolutionKey ?? ref.server.name,
+                    resolutionKey: resolutionKey ?? ref.server.name,
                     lockEntry,
                     versionRange: Option.none(),
                 })
             : lockEntry === undefined
-                ? ws.setMcpServerEntry(ref.server.name, {
+                ? ws.setMcpServerEntry(localName, {
                     ...settingsEntry,
                 })
                 : ws.setMcpServer({
-                    name: ref.server.name,
+                    name: localName,
+                    resolutionKey: resolutionKey ?? localName,
                     lockEntry,
                     versionRange: op.args.versionRange,
                     env: persistedEnv,
                     enabled,
                     ...(agents === undefined ? {} : { agents }),
                 });
-    const writeWarning = yield* writeEffect.pipe(Effect.as(Option.none()), Effect.catch((e) => Effect.succeed(Option.some(`MCP server update failed: ${adapter.describeFailure(e)}`))));
-    const warnings = Option.match(writeWarning, {
-        onNone: () => [...secretWarnings, ...agentSync.warnings],
-        onSome: (warning) => [warning, ...secretWarnings, ...agentSync.warnings],
-    });
+    yield* writeEffect;
+    const projectionNames = ref.refType === "registry" && lockedVersion !== undefined && lockedVersion !== ref.version
+        ? [...new Set([...(existingClosure?.localNames ?? []), localName])].sort()
+        : [localName];
+    const agentSyncResults = yield* Effect.forEach(projectionNames, (projectionName) => Effect.gen(function* () {
+        const projectionEntry = projectionName === localName ? settingsEntry : currentMcpServers[projectionName];
+        if (projectionEntry === undefined || projectionEntry.kind === "inline") {
+            return undefined;
+        }
+        const projectionSecretIdentity = {
+            scopeRoot: path.resolve(ws.baseDir),
+            localName: projectionName,
+            sourceIdentity,
+        };
+        const projectionStoredSecrets = yield* loadStoredMcpSecrets(projectionSecretIdentity, secretNames);
+        const projectionEnv = projectionName === localName
+            ? mergedEnv
+            : { ...projectionStoredSecrets, ...projectionEntry.env };
+        return yield* syncConfiguredAgentsOnInstall({
+            wsBaseDir: ws.baseDir,
+            scope: ws.scope,
+            strict: strictAgentSync,
+            serverName: projectionName,
+            canonicalPath,
+            owner: ref.owner,
+            resolvedVersion: ref.version,
+            nothingRunnable,
+            enabled: projectionEntry.enabled,
+            configValues: preserveSecretReferences(projectionEnv, secretNames),
+            entry: projectionEntry,
+        });
+    }), { concurrency: 1 });
+    const agentSyncSummaries = agentSyncResults.filter((summary) => summary !== undefined);
+    const agentSync = {
+        status: agentSyncSummaries.some((summary) => summary.status === "degraded")
+            ? "degraded"
+            : "green",
+        details: agentSyncSummaries.flatMap((summary) => summary.details),
+        warnings: agentSyncSummaries.flatMap((summary) => summary.warnings),
+        outcomes: agentSyncSummaries.flatMap((summary) => summary.outcomes),
+    };
+    const secretPersistence = yield* persistMcpSecrets(secretIdentity, secretNames, mergedEnv);
+    const secretWarnings = secretPersistence.flatMap((outcome) => outcome._tag === "failed"
+        ? [
+            `${outcome.inputName} could not be saved to the system keychain; AXM state was applied and credential action is required`,
+        ]
+        : []);
+    const warnings = [...secretWarnings, ...agentSync.warnings];
     const change = currentEntry === undefined ? "created" : "updated";
     const agentOutcomes = agentSync.outcomes.flatMap(({ agentId, outcome }) => outcome._tag === "success" || outcome._tag === "fallback"
         ? [
@@ -549,7 +616,7 @@ export const installMcpServer = (op) => Effect.gen(function* () {
         : []);
     return {
         result: "success",
-        message: appendWarningsToMessage(`Installed ${ref.server.name} (canonical=success, agent-sync=${agentSync.status})`, warnings),
+        message: appendWarningsToMessage(`Installed ${localName} from ${ref.owner}/mcps/${ref.server.name} (canonical=success, agent-sync=${agentSync.status})`, warnings),
         artifact: mcpServerArtifact({
             lockEntry,
             scope: ws.scope,

package/dist/src/mcps/operations/uninstall.js

@@ -20,6 +20,7 @@ import { acceptedCanonicalObservation, acceptedLockedCanonicalPath, removableAcc
 import { agentConfigTarget, mcpServerArtifact, mcpSettingsTarget } from "./artifact.js";
 import { LifecycleFailureAdapter, withAdaptedStepFailures } from "../../failure-adapter.js";
 import { ExtensionLifecycleFailed } from "../../errors.js";
+import { collectSecretInputNames, deleteMcpSecrets, readMcpServerManifest } from "./install.js";
 const REQUIRED_AGENT_IDS = new Set([
     "claude-code",
     "opencode",
@@ -119,8 +120,8 @@ const syncConfiguredAgentsOnUninstall = (args) => Effect.gen(function* () {
  * 3. Remove settings and accepted resolution
  */
 export const uninstallMcpServer = (op) => Effect.gen(function* () {
-    const adapter = yield* LifecycleFailureAdapter;
     const fs = yield* FileSystem.FileSystem;
+    const path = yield* Path.Path;
     const ws = yield* WorkspaceMutations;
     const strictAgentSync = Option.getOrElse(op.args.strictAgentSync ?? Option.none(), () => false);
     const desired = yield* ws.getDesiredStateGraph();
@@ -132,6 +133,12 @@ export const uninstallMcpServer = (op) => Effect.gen(function* () {
         });
     }
     const desiredNode = desired.nodes.find((node) => node.type === "mcp-server" && node.name === op.args.serverName);
+    const sourceClosure = desiredNode === undefined || desiredNode.authority === "inline"
+        ? undefined
+        : desired.mcpSourceClosures.find((closure) => closure.identity === desiredNode.identity);
+    const keepSharedResolution = sourceClosure !== undefined &&
+        (sourceClosure.localNames.some((name) => name !== op.args.serverName) ||
+            sourceClosure.origins.some((origin) => origin.type === "pack"));
     const acceptedCanonical = yield* acceptedCanonicalObservation({
         workspace: ws,
         type: "mcp-server",
@@ -150,31 +157,43 @@ export const uninstallMcpServer = (op) => Effect.gen(function* () {
     if (desiredNode === undefined && !installedOnDisk) {
         return { result: "success", message: "not installed" };
     }
-    if (desiredNode?.origins.some((origin) => origin.type === "pack") === true) {
-        yield* ws.removeMcpServerSettings(op.args.serverName);
-        return {
-            result: "success",
-            message: "Kept on disk because dependency is still required by an installed pack",
-        };
-    }
-    if (Option.isSome(removableCanonical))
+    const manifest = yield* Option.match(removableCanonical, {
+        onNone: () => Effect.succeed(Option.none()),
+        onSome: readMcpServerManifest,
+    });
+    if (!keepSharedResolution && Option.isSome(removableCanonical)) {
         yield* removeIfExists(fs, removableCanonical.value);
-    // Remove from settings + lockfile (best-effort; preserve warning in result).
-    const removeWarning = yield* ws.removeMcpServer(op.args.serverName).pipe(Effect.as(Option.none()), Effect.catch((e) => Effect.succeed(Option.some(`MCP server removal from settings failed: ${adapter.describeFailure(e)}`))));
+    }
+    // Workspace files and projections are transaction-owned. Keychain cleanup
+    // intentionally runs afterward and reports recoverable credential residue.
+    yield* ws.removeMcpServer(op.args.serverName);
     const agentSync = yield* syncConfiguredAgentsOnUninstall({
         wsBaseDir: ws.baseDir,
         scope: ws.scope,
         strict: strictAgentSync,
         serverName: op.args.serverName,
     });
-    const warnings = Option.match(removeWarning, {
-        onNone: () => agentSync.warnings,
-        onSome: (warning) => [warning, ...agentSync.warnings],
+    const secretNames = Option.match(manifest, {
+        onNone: () => new Set(),
+        onSome: collectSecretInputNames,
     });
+    const secretDeletion = desiredNode === undefined || desiredNode.authority === "inline"
+        ? []
+        : yield* deleteMcpSecrets({
+            scopeRoot: path.resolve(ws.baseDir),
+            localName: op.args.serverName,
+            sourceIdentity: desiredNode.identity,
+        }, secretNames);
+    const secretWarnings = secretDeletion.flatMap((outcome) => outcome._tag === "failed"
+        ? [
+            `${outcome.inputName} could not be deleted from the system keychain; AXM state was applied and credential cleanup is required`,
+        ]
+        : []);
+    const warnings = [...secretWarnings, ...agentSync.warnings];
     const agentTarget = agentConfigTarget("removed", agentSync.agentIds);
     return {
         result: "success",
-        message: appendWarningsToMessage(`Uninstalled ${op.args.serverName} (canonical=success, agent-sync=${agentSync.status})`, warnings),
+        message: appendWarningsToMessage(`Uninstalled ${op.args.serverName} (canonical=${keepSharedResolution ? "retained-shared" : "success"}, agent-sync=${agentSync.status})`, warnings),
         artifact: mcpServerArtifact({
             lockEntry: undefined,
             scope: ws.scope,

package/dist/src/rules/manager.js

@@ -10,7 +10,7 @@ import * as Layer from "effect/Layer";
 import * as Option from "effect/Option";
 import * as Path from "effect/Path";
 import * as Schema from "effect/Schema";
-import { RuleDefinitionInvalid, RuleInstallStateMissing, activeContributors, applyProjectionPlans, planAggregateProjection, reconcileManagedRegionFile, MARKER_KIND_POINT, MARKER_VERSION, parseMarker, serializeMarker, assertInstructionTargetsSafe, assertInstructionsGitignoreSafe, observeInstructionProjection, reconcileInstructionTargets, resolveInstructionsConfig, } from "@agentxm/extension-workspace";
+import { RuleDefinitionInvalid, RuleInstallStateMissing, activeContributors, applyProjectionPlans, planAggregateProjection, reconcileManagedRegionFile, projectionGeneration, MARKER_KIND_POINT, MARKER_VERSION, serializeMarker, assertInstructionTargetsSafe, assertInstructionsGitignoreSafe, observeInstructionProjection, reconcileInstructionTargets, resolveInstructionsConfig, } from "@agentxm/extension-workspace";
 import { decodeExtensionNameSync, formatFqn } from "@agentxm/extension-model/unstable/extensions";
 import { canReuseInstalledPackage, enabledConfiguredEntries, materializeExternalPackageWithTreeIntegrity, } from "@agentxm/extension-workspace";
 import { materializeRegistryPackageWithTreeIntegrity } from "../registry-materialization.js";
@@ -252,20 +252,21 @@ export const RuleManagerLive = Layer.effect(RuleManager, Effect.gen(function* ()
         });
         return sorted;
     }));
-    const observedRuleContributors = (content) => content.split(/\r?\n/u).flatMap((line) => {
-        const parsed = parseMarker(line, { kind: "block", open: "<!--", close: "-->" });
-        if (parsed.state !== "complete" ||
-            parsed.marker.kind !== MARKER_KIND_POINT ||
-            parsed.marker.pointKind !== "rule") {
-            return [];
-        }
-        const separator = parsed.marker.ext.lastIndexOf("@");
-        return separator > 0 ? [parsed.marker.ext.slice(0, separator)] : [];
-    });
     const reconcileRulesRegion = (args) => Effect.gen(function* () {
         const { target } = args;
         const contributors = args.input.contributors;
         const rendered = contributors.map(renderRuleBlock).join("\n\n");
+        const generation = projectionGeneration([
+            "rule-instructions-region-v1",
+            target.relative,
+            RULES_REGION_OWNER,
+            ...contributors.flatMap((contributor) => [
+                contributor.name,
+                contributor.marker,
+                contributor.body,
+                JSON.stringify(contributor.manifest),
+            ]),
+        ]);
         const instructions = args.instructions;
         if (args.dryRun !== true && Option.isSome(instructions)) {
             yield* provide(Effect.gen(function* () {
@@ -285,6 +286,7 @@ export const RuleManagerLive = Layer.effect(RuleManager, Effect.gen(function* ()
             region: RULES_REGION,
             owner: RULES_REGION_OWNER,
             rendered,
+            generation,
             ...(args.dryRun === undefined ? {} : { dryRun: args.dryRun }),
             writeWhenMissing: true,
             unsupportedTargetDetail: `Instruction source does not support managed regions: ${target.relative}`,
@@ -302,10 +304,6 @@ export const RuleManagerLive = Layer.effect(RuleManager, Effect.gen(function* ()
             present: Option.isSome(observedRegion),
             current: !changed,
             expectedContributors: contributors.map(({ marker }) => marker),
-            observedContributors: Option.match(observedRegion, {
-                onNone: () => [],
-                onSome: observedRuleContributors,
-            }),
         };
         if (args.dryRun === true) {
             return {

package/dist/src/subagents/manager.js

@@ -15,7 +15,7 @@ import * as Layer from "effect/Layer";
 import * as Option from "effect/Option";
 import * as Schema from "effect/Schema";
 import { WorkspaceMutations } from "@agentxm/workspace-state";
-import { CodingAgentRepository, renderManagedSubagentOutputs, computeSubagentPathsForLayout, subagentContentFilename, subagentContentPath, SubagentContentUnreadable, SubagentDefinitionInvalid, SubagentInstallStateMissing, SubagentIoFailed, warnOnOrphanOverrides, buildRooModeEntry, buildSubagentLockEntry, findManagedSubagentFiles, hasAxmManagedMarker, applyProjectionPlansWithResults, planSingletonProjection, managedSubagentFile, } from "@agentxm/extension-workspace";
+import { CodingAgentRepository, renderManagedSubagentOutputs, managedFileFormatForPath, managedFileMarker, projectionGeneration, computeSubagentPathsForLayout, subagentContentFilename, subagentContentPath, SubagentContentUnreadable, SubagentDefinitionInvalid, SubagentInstallStateMissing, SubagentIoFailed, warnOnOrphanOverrides, buildRooModeEntry, buildSubagentLockEntry, findManagedSubagentFiles, hasAxmManagedMarker, applyProjectionPlansWithResults, planSingletonProjection, managedSubagentFile, } from "@agentxm/extension-workspace";
 import { copyExtensionDirectory } from "@agentxm/extension-workspace";
 import { sanitizeName } from "@agentxm/workspace-state";
 import { stripFileProtocol } from "../internal/fs-helpers.js";
@@ -80,6 +80,16 @@ export const SubagentManagerLive = Layer.effect(SubagentManager, Effect.gen(func
         ...args.managedFile,
         helpTopic: "subagents",
         format: "markdown",
+        generation: projectionGeneration([
+            "subagent-role-skill-v1",
+            args.managedFile.ext,
+            args.managedFile.source.kind,
+            args.managedFile.source.path,
+            args.agentId,
+            args.name,
+            args.description,
+            args.body,
+        ]),
     });
     const jsonValuesEqual = (left, right) => {
         if (left === right)
@@ -101,6 +111,31 @@ export const SubagentManagerLive = Layer.effect(SubagentManager, Effect.gen(func
         }
         return false;
     };
+    const serializedJsonValuesEqual = (left, right) => {
+        try {
+            const leftValue = JSON.parse(left);
+            const rightValue = JSON.parse(right);
+            return jsonValuesEqual(leftValue, rightValue);
+        }
+        catch {
+            return false;
+        }
+    };
+    const generatedFileCurrent = (args) => {
+        const format = managedFileFormatForPath(args.outputPath);
+        if (format === undefined) {
+            return args.outputPath.endsWith(".json")
+                ? serializedJsonValuesEqual(args.content, args.expected)
+                : args.content === args.expected;
+        }
+        const actualMarker = managedFileMarker(args.content, format);
+        const expectedMarker = managedFileMarker(args.expected, format);
+        return (Option.isSome(actualMarker) &&
+            Option.isSome(expectedMarker) &&
+            actualMarker.value.ext === expectedMarker.value.ext &&
+            actualMarker.value.src === expectedMarker.value.src &&
+            actualMarker.value.generation === expectedMarker.value.generation);
+    };
     const materializeRoleSkillFallback = (args) => Effect.gen(function* () {
         const polyfillHash = computeSourceHash(JSON.stringify({ agent: args.agentId, name: args.name, body: args.body }));
         const polyfillDir = path.join(baseDir, ".axm", "build", "polyfills", "subagents", args.sanitized, polyfillHash);
@@ -530,7 +565,13 @@ export const SubagentManagerLive = Layer.effect(SubagentManager, Effect.gen(func
                 }
                 return Effect.forEach(rendered.outputs, (output) => fs.readFileString(path.resolve(baseDir, output.path)).pipe(Effect.option)).pipe(Effect.map((contents) => ({
                     present: contents.every(Option.isSome),
-                    current: contents.every((content, index) => Option.isSome(content) && content.value === rendered.outputs[index]?.content),
+                    current: contents.every((content, index) => Option.isSome(content) &&
+                        rendered.outputs[index] !== undefined &&
+                        generatedFileCurrent({
+                            content: content.value,
+                            expected: rendered.outputs[index].content,
+                            outputPath: rendered.outputs[index].path,
+                        })),
                 })));
             }
             if ((ref.fallback ?? manifestFallback) === "none") {
@@ -555,7 +596,11 @@ export const SubagentManagerLive = Layer.effect(SubagentManager, Effect.gen(func
                     .readFileString(path.join(path.normalize(skills.dir), sanitized, "SKILL.md"))
                     .pipe(Effect.option, Effect.map((content) => ({
                     present: Option.isSome(content),
-                    current: Option.exists(content, (value) => value === expected),
+                    current: Option.exists(content, (value) => generatedFileCurrent({
+                        content: value,
+                        expected,
+                        outputPath: "SKILL.md",
+                    })),
                 })));
             }));
         })));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentxm/extension-lifecycle",
-  "version": "0.28.4-bootstrap.0",
+  "version": "0.28.5",
   "description": "AXM extension-lifecycle feature: install, update, uninstall, enable, and disable policy across root and type-specific command forms for the axm CLI. Unstable and unsupported — use the axm.sh CLI.",
   "type": "module",
   "license": "FSL-1.1-MIT",
@@ -18,10 +18,12 @@
   "exports": {
     ".": {
       "types": "./dist/src/index.d.ts",
+      "axm-source": "./src/index.ts",
       "default": "./dist/src/index.js"
     },
     "./live": {
       "types": "./dist/src/live.d.ts",
+      "axm-source": "./src/live.ts",
       "default": "./dist/src/live.js"
     }
   },
@@ -41,13 +43,13 @@
   "dependencies": {
     "effect": "4.0.0-rc.112",
     "semver": "^7.8.5",
-    "@agentxm/registry-client": "^0.28.4-bootstrap.0",
-    "@agentxm/extension-sources": "^0.28.4-bootstrap.0",
-    "@agentxm/extension-model": "^0.28.4-bootstrap.0",
-    "@agentxm/workspace-state": "^0.28.4-bootstrap.0",
-    "@agentxm/registry-protocol": "^0.28.4-bootstrap.0",
-    "@agentxm/extension-workspace": "^0.28.4-bootstrap.0",
-    "@agentxm/workspace-operations": "^0.28.4-bootstrap.0"
+    "@agentxm/extension-model": "^0.28.5",
+    "@agentxm/extension-workspace": "^0.28.5",
+    "@agentxm/registry-client": "^0.28.5",
+    "@agentxm/registry-protocol": "^0.28.5",
+    "@agentxm/extension-sources": "^0.28.5",
+    "@agentxm/workspace-operations": "^0.28.5",
+    "@agentxm/workspace-state": "^0.28.5"
   },
   "devDependencies": {
     "@effect/platform-node": "4.0.0-rc.112",