@agentxm/extension-lifecycle 0.28.4 → 0.28.6

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 { CodingAgentRepository, McpSharedTargetConflict, applyProjectionPlansWithResults, planSingletonProjection, inspectAgentMcpServer, sharedMcpTargetPolicyConflict, } from "@agentxm/extension-workspace";
-import { isPathSafe } from "@agentxm/workspace-state";
+import { createHash } from "node:crypto";
+import { CodingAgentRepository, applyProjectionPlansWithResults, planSingletonProjection, } from "@agentxm/extension-workspace";
+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";
@@ -32,7 +33,6 @@ import { printSourceParams } from "@agentxm/extension-model/unstable/sources/pri
 import { computeMaterializedTreeIntegrity } from "@agentxm/workspace-state";
 import { decodeVersionSync } from "@agentxm/extension-model/unstable/version-constraints";
 import { MCP_SERVER_MANIFEST_FILENAME, McpServerManifestSchema, } from "@agentxm/extension-model/unstable/mcps/manifest-schema";
-import { isMcpServerApplicableToAgent } from "@agentxm/workspace-state";
 import { agentConfigTargets, mcpServerArtifact, mcpSettingsTarget, mcpSourceTarget, } from "./artifact.js";
 import { LifecycleFailureAdapter, withAdaptedStepFailures } from "../../failure-adapter.js";
 import { ExtensionLifecycleFailed } from "../../errors.js";
@@ -55,7 +55,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 +66,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 +118,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 +181,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 +206,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 +215,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)) {
@@ -280,17 +294,6 @@ const syncConfiguredAgentsOnInstall = (args) => Effect.gen(function* () {
         warnings.push(`Skipping unknown configured agents: ${unknownConfiguredAgentIds.join(", ")}`);
     }
     const configuredAgents = yield* agentRepo.getConfiguredAgents();
-    const sharedTargetConflict = sharedMcpTargetPolicyConflict({
-        entry: args.entry,
-        agentIds: configuredAgents.map((agent) => agent.id),
-        scope: args.scope,
-    });
-    if (sharedTargetConflict !== undefined) {
-        return yield* new ExtensionLifecycleFailed({
-            category: "conflict",
-            detail: sharedTargetConflict,
-        });
-    }
     let outcomes;
     if (args.nothingRunnable) {
         outcomes = configuredAgents.map((agent) => ({
@@ -316,28 +319,6 @@ const syncConfiguredAgentsOnInstall = (args) => Effect.gen(function* () {
                     observedContributors: [],
                 }),
                 apply: () => Effect.gen(function* () {
-                    if (!isMcpServerApplicableToAgent(args.entry, agent.id)) {
-                        const inspection = yield* inspectAgentMcpServer({
-                            workspaceRoot: args.wsBaseDir,
-                            scope: args.scope,
-                            agentId: agent.id,
-                            serverName: args.serverName,
-                            entry: args.entry,
-                        });
-                        if (inspection.status === "unmanaged") {
-                            return yield* new McpSharedTargetConflict({
-                                reason: `${agent.id} has an unmanaged MCP server named ${args.serverName}; AXM will not remove it while applying the target policy`,
-                            });
-                        }
-                        const outcome = inspection.status === "drift"
-                            ? yield* agent.removeMcpServer({
-                                workspaceRoot: args.wsBaseDir,
-                                scope: args.scope,
-                                serverName: args.serverName,
-                            })
-                            : { _tag: "success", targets: [] };
-                        return { agentId: agent.id, outcome };
-                    }
                     const outcome = yield* agent.addMcpServer({
                         workspaceRoot: args.wsBaseDir,
                         scope: args.scope,
@@ -398,9 +379,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 +397,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 +446,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 +459,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 +480,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",
@@ -486,58 +491,83 @@ export const installMcpServer = (op) => Effect.gen(function* () {
     }
     const persistedEnv = redactSettingsEnv(mergedEnv, secretNames);
     const enabled = currentEntry?.enabled ?? true;
-    const agents = op.args.agents ?? currentEntry?.agents;
     const settingsEntry = {
         kind: "sourced",
         source: ref.refType === "workspace" ? "workspace" : printSourceParams(ref.source),
         env: persistedEnv,
         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 +579,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/registry-materialization.js

@@ -17,6 +17,7 @@ import { computeIntegrity } from "./internal/integrity.js";
 import { ArchiveIntegrityMismatch, recoverCanonicalDirectory, replaceCanonicalDirectoryWithInspection, } from "@agentxm/extension-workspace";
 import { CoupledDependencyFailure } from "@agentxm/extension-workspace";
 import { coupleLifecycleDependencyFailure } from "./errors.js";
+import { makeThrottledUnitProgress } from "@agentxm/workspace-operations";
 import { computeMaterializedTreeIntegrity, } from "@agentxm/workspace-state";
 const registryLocationForClient = (location) => location.protocol === "file:" ? location.pathname : location.href;
 /**
@@ -35,12 +36,16 @@ export const materializeRegistryPackageWithTreeIntegrity = (args) => Effect.gen(
         canonicalPath: args.destinationPath,
     });
     const client = yield* createRegistryClient(registryLocationForClient(args.sourceLocation));
+    // Continuous download progress reaches the lifecycle broadcast throttled:
+    // tens of events per archive, attributed to the unit that is running.
+    const reportProgress = yield* makeThrottledUnitProgress({ unit: "bytes" });
     const { archive } = yield* client
         .getExtensionPackage({
         owner: args.owner,
         type: args.type,
         name: args.name,
         version: Option.some(args.version),
+        onProgress: (progress) => reportProgress(progress.done, progress.total),
     })
         .pipe(Effect.mapError(coupleLifecycleDependencyFailure));
     if (Option.isSome(args.integrity)) {

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 {
@@ -336,7 +334,9 @@ export const RuleManagerLive = Layer.effect(RuleManager, Effect.gen(function* ()
             unitId: "rule:instructions-region",
             targetFile: target.absolute,
             graph,
-            select: (completeGraph) => selectRuleContributors({ graph: completeGraph, locked }),
+            // Rule contributors are decided from desired state alone, so the
+            // instructions region never excludes one.
+            select: (completeGraph) => selectRuleContributors({ graph: completeGraph, locked }).pipe(Effect.map((contributors) => ({ contributors, exclusions: [] }))),
             adapter: {
                 observe: (input) => reconcileRulesRegion({ input, target, instructions, dryRun: true }).pipe(Effect.map(({ projectionUnitObservation }) => projectionUnitObservation)),
                 apply: (input) => reconcileRulesRegion({ input, target, instructions }).pipe(Effect.asVoid),

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/dist/src/workflows/install-command/workflow.d.ts

@@ -11,7 +11,6 @@ import type * as Scope from "effect/Scope";
 import type { Plan } from "@agentxm/workspace-operations";
 import type { OperationResolution } from "@agentxm/workspace-operations";
 import type { PlanExecution } from "@agentxm/workspace-operations";
-import { LifecycleResolutionProgress } from "../../resolution-progress.js";
 /**
  * Type-specific actions for install command workflows.
  *
@@ -53,5 +52,5 @@ export declare const runInstallCommandWorkflow: <Args, Parsed, Req, Ref, Intent,
     readonly execution: PlanExecution;
     readonly transformIntent?: (intent: Intent) => Intent;
     readonly transformPlan?: (plan: Plan) => Effect.Effect<Plan, TransformError, TransformRequirements>;
-}) => Effect.Effect<OperationResolution<never>, import("@agentxm/workspace-state").WorkspaceSettingsReadFailure | ParseError | ResolveError | TransformError | import("@agentxm/workspace-operations").CandidateFingerprintFailed | import("@agentxm/workspace-operations").ApprovalRecoveryMissing | import("@agentxm/workspace-operations").PlanInteractionFailed | import("@agentxm/workspace-state").WorkspaceTransitionAcquireFailure | import("@agentxm/workspace-state").LockfileValidationError, import("@agentxm/workspace-state").WorkspaceMutations | import("effect/FileSystem").FileSystem | import("effect/Path").Path | LifecycleResolutionProgress | import("@agentxm/workspace-operations").ResolvePlanInteraction | Exclude<TransformRequirements, Scope.Scope>>;
+}) => Effect.Effect<OperationResolution<never>, import("@agentxm/workspace-state").WorkspaceSettingsReadFailure | ParseError | ResolveError | TransformError | import("@agentxm/workspace-operations").CandidateFingerprintFailed | import("@agentxm/workspace-operations").ApprovalRecoveryMissing | import("@agentxm/workspace-operations").PlanInteractionFailed | import("@agentxm/workspace-state").WorkspaceTransitionAcquireFailure | import("@agentxm/workspace-state").LockfileValidationError, import("@agentxm/workspace-state").WorkspaceMutations | import("effect/FileSystem").FileSystem | import("effect/Path").Path | import("@agentxm/workspace-operations").ResolvePlanInteraction | Exclude<TransformRequirements, Scope.Scope>>;
 //# sourceMappingURL=workflow.d.ts.map