agentwheel 0.18.5 → 0.19.1

package/dist/index.js

@@ -56,6 +56,18 @@ var packageComposeEntrySchema = z.object({
   markers: z.boolean().optional(),
   optional: z.boolean().optional()
 });
+var packageCompositionRuleSchema = z.object({
+  target: z.string().min(1),
+  include: z.string().min(1),
+  exclude: z.array(z.string().min(1)).optional(),
+  runtimes: z.array(z.string().min(1)).optional(),
+  markers: z.boolean().optional()
+});
+var packageSupersedesEntrySchema = z.object({
+  package: z.string().min(1),
+  selector: z.string().min(1),
+  reason: z.string().min(1)
+});
 var packageItemRequireObjectSchema = z.object({
   selector: z.string().min(1),
   optional: z.boolean().optional(),
@@ -97,6 +109,7 @@ var artifactSchema = z.object({
   requires: z.array(packageItemRequireSchema).optional(),
   suggests: z.array(packageItemSuggestSchema).optional(),
   compose: z.array(packageComposeEntrySchema).optional(),
+  supersedes: z.array(packageSupersedesEntrySchema).optional(),
   runtimes: z.array(z.string().min(1)).optional(),
   composedFrom: z.array(composedFromEntrySchema).optional()
 });
@@ -580,7 +593,8 @@ var graphLockArtifactSchema = z4.object({
   kind: fileKindSchema,
   hash: z4.string().min(16),
   channel: z4.enum(["managed", "overlay", "addition", "override", "ejected"]).default("managed"),
-  composedFrom: z4.array(composedFromEntrySchema).optional()
+  composedFrom: z4.array(composedFromEntrySchema).optional(),
+  supersedes: z4.array(packageSupersedesEntrySchema).optional()
 });
 var graphLockPlainNameIncumbentSchema = z4.object({
   adapter: z4.string().min(1),
@@ -1660,6 +1674,16 @@ import { dirname as dirname9 } from "path";
 import { parse as parse3, stringify as stringify2 } from "yaml";
 var MergeAdoptionMismatchError = class extends Error {
 };
+function assertExactMergeContribution(contribution, strategy, currentContent) {
+  if (strategy === "codex-toml-mcp") {
+    assertExactMcpMergeContribution(contribution, strategy, currentContent);
+    return;
+  }
+  const mismatch = firstMergeContributionMismatch(parseMergeDestination(currentContent, strategy), contribution);
+  if (mismatch) {
+    throw new MergeAdoptionMismatchError(`exact merge contribution differs or is missing at ${mismatch}`);
+  }
+}
 function assertExactMcpMergeContribution(removal, strategy, currentContent) {
   if (strategy === "codex-toml-mcp") {
     const mismatched = mismatchedCodexTomlMcpServers(removal, currentContent);
@@ -1766,6 +1790,25 @@ function firstMcpContributionMismatch(current, incoming) {
   }
   return void 0;
 }
+function firstMergeContributionMismatch(current, contribution, path = "$") {
+  if (isRecord4(contribution)) {
+    if (!isRecord4(current)) return path;
+    for (const [key, value] of Object.entries(contribution)) {
+      if (!(key in current)) return `${path}.${key}`;
+      const mismatch = firstMergeContributionMismatch(current[key], value, `${path}.${key}`);
+      if (mismatch) return mismatch;
+    }
+    return void 0;
+  }
+  if (Array.isArray(contribution)) {
+    if (!Array.isArray(current)) return path;
+    for (const value of contribution) {
+      if (!current.some((candidate) => sameMcpValue(candidate, value))) return path;
+    }
+    return void 0;
+  }
+  return current === contribution ? void 0 : path;
+}
 function combineMergeValues(existing, incoming) {
   if (isRecord4(existing) && isRecord4(incoming)) {
     const combined = { ...existing };
@@ -5638,7 +5681,7 @@ var legacyArtifactTypeSchema = z6.enum([
   "plugins"
 ]);
 var runtimeListSchema = z6.array(z6.string().min(1));
-var CURRENT_OPENPACK_SCHEMA_VERSION = 2;
+var CURRENT_OPENPACK_SCHEMA_VERSION = 3;
 var packageProvideBaseSchema = z6.object({
   path: z6.string().min(1),
   format: artifactFormatSchema.optional(),
@@ -5650,6 +5693,7 @@ var packageItemSchema = z6.object({
   requires: z6.array(packageItemRequireSchema).optional(),
   suggests: z6.array(packageItemSuggestSchema).optional(),
   compose: z6.array(packageComposeEntrySchema).optional(),
+  supersedes: z6.array(packageSupersedesEntrySchema).optional(),
   runtimes: runtimeListSchema.optional()
 });
 var packageDependencySchema = z6.object({
@@ -5680,8 +5724,7 @@ var packageManifestV1Schema = z6.object({
   version: z6.string().min(1),
   provides: z6.array(packageProvideV1Schema).min(1)
 });
-var packageManifestV2Schema = z6.object({
-  schemaVersion: z6.literal(CURRENT_OPENPACK_SCHEMA_VERSION),
+var packageManifestModernShape = {
   name: z6.string().min(1),
   version: z6.string().min(1),
   runtimes: runtimeListSchema.optional(),
@@ -5689,7 +5732,8 @@ var packageManifestV2Schema = z6.object({
   suggests: z6.record(z6.string().min(1), packageSuggestionSchema).optional(),
   compose: z6.array(packageComposeEntrySchema).optional(),
   provides: z6.array(packageProvideSchema).default([])
-}).superRefine((manifest, ctx) => {
+};
+function requireProvidesOrDependencies(manifest, ctx) {
   const hasProvides = manifest.provides.length > 0;
   const hasRequires = Object.keys(manifest.requires ?? {}).length > 0;
   if (!hasProvides && !hasRequires) {
@@ -5699,8 +5743,17 @@ var packageManifestV2Schema = z6.object({
       message: "OpenPack v2 manifest must declare at least one provides entry or one requires dependency"
     });
   }
-});
-var packageManifestSchema = z6.union([packageManifestV1Schema, packageManifestV2Schema]);
+}
+var packageManifestV2Schema = z6.object({
+  schemaVersion: z6.literal(2),
+  ...packageManifestModernShape
+}).superRefine(requireProvidesOrDependencies);
+var packageManifestV3Schema = z6.object({
+  schemaVersion: z6.literal(CURRENT_OPENPACK_SCHEMA_VERSION),
+  ...packageManifestModernShape,
+  compositionRules: z6.array(packageCompositionRuleSchema).optional()
+}).superRefine(requireProvidesOrDependencies);
+var packageManifestSchema = z6.union([packageManifestV1Schema, packageManifestV2Schema, packageManifestV3Schema]);
 var openPackManifestNames = ["openpack.json", "openpack.jsonc"];
 var legacyPackageManifestNames = ["agentwheel.json", "agentwheel.jsonc"];
 var packageManifestNames = [...openPackManifestNames, ...legacyPackageManifestNames];
@@ -5741,9 +5794,30 @@ function parsePackageManifest(parsed, path = "package manifest") {
     return parseWithSchema(packageManifestV1Schema, parsed, path);
   }
   if (parsed.schemaVersion === 2) {
+    const violations = v2OpenPackViolations(parsed);
+    if (violations.length > 0) {
+      throw new Error(`OpenPack schemaVersion 3 is required for ${violations.join(", ")} in ${path}. Set "schemaVersion": 3.`);
+    }
     return parseWithSchema(packageManifestV2Schema, parsed, path);
   }
-  throw new Error(`Invalid package manifest ${path}: schemaVersion must be 1 or 2`);
+  if (parsed.schemaVersion === 3) {
+    return parseWithSchema(packageManifestV3Schema, parsed, path);
+  }
+  throw new Error(`Invalid package manifest ${path}: schemaVersion must be 1, 2, or 3`);
+}
+function v2OpenPackViolations(manifest) {
+  const violations = [];
+  if (Object.prototype.hasOwnProperty.call(manifest, "compositionRules")) violations.push("compositionRules");
+  const provides = Array.isArray(manifest.provides) ? manifest.provides : [];
+  for (const [provideIndex, provide] of provides.entries()) {
+    if (!isRecord7(provide) || !isRecord7(provide.items)) continue;
+    for (const [itemName, item] of Object.entries(provide.items)) {
+      if (isRecord7(item) && Object.prototype.hasOwnProperty.call(item, "supersedes")) {
+        violations.push(`provides[${provideIndex}].items.${itemName}.supersedes`);
+      }
+    }
+  }
+  return violations;
 }
 function parseWithSchema(schema, parsed, path) {
   const result = schema.safeParse(parsed);
@@ -5753,7 +5827,7 @@ function parseWithSchema(schema, parsed, path) {
 }
 function v1OpenPackViolations(manifest) {
   const violations = [];
-  for (const key of ["requires", "items", "compose", "runtimes"]) {
+  for (const key of ["requires", "items", "compose", "runtimes", "compositionRules", "supersedes"]) {
     if (Object.prototype.hasOwnProperty.call(manifest, key)) violations.push(key);
   }
   const provides = Array.isArray(manifest.provides) ? manifest.provides : [];
@@ -6003,6 +6077,7 @@ async function artifactForFile(type, name, sourcePath, relativePath, packageName
     requires: item.requires,
     suggests: item.suggests,
     compose: item.compose,
+    supersedes: item.supersedes,
     runtimes: item.runtimes ?? provideRuntimes(provide) ?? manifestRuntimes(manifest)
   };
 }
@@ -6023,6 +6098,7 @@ async function artifactForDir(type, name, sourcePath, relativePath, packageName,
     requires: item.requires,
     suggests: item.suggests,
     compose: item.compose,
+    supersedes: item.supersedes,
     runtimes: item.runtimes ?? provideRuntimes(provide) ?? manifestRuntimes(manifest)
   };
 }
@@ -6030,13 +6106,13 @@ function itemMetadata(provide, itemName) {
   if (!provide || !("items" in provide) || !provide.items || !itemName) return {};
   const item = provide.items[itemName];
   if (!item) return {};
-  return { format: item.format, requires: item.requires, suggests: item.suggests, compose: item.compose, runtimes: item.runtimes };
+  return { format: item.format, requires: item.requires, suggests: item.suggests, compose: item.compose, supersedes: item.supersedes, runtimes: item.runtimes };
 }
 function provideRuntimes(provide) {
   return provide && "runtimes" in provide ? provide.runtimes : void 0;
 }
 function manifestRuntimes(manifest) {
-  return manifest && manifest.schemaVersion === 2 ? manifest.runtimes : void 0;
+  return manifest && manifest.schemaVersion !== 1 ? manifest.runtimes : void 0;
 }
 
 // src/source/clawhub.ts
@@ -7229,7 +7305,14 @@ async function expandMarkdownIncludes(artifacts, packageRoot, options = {}) {
     if (files.length === 0) continue;
     const composedFrom = [];
     for (const file of files) {
-      const result = await expandFile(file, packageRoot, composeEntriesForFile(artifact, file), artifactPaths, options);
+      const localEntries = composeEntriesForFile(artifact, file).map((entry) => ({
+        entry,
+        packageRoot,
+        artifactPaths,
+        nodeId: options.nodeId
+      }));
+      const externalEntries = isPrimaryMarkdownFile(artifact, file) ? options.additionalComposeEntries?.(artifact) ?? [] : [];
+      const result = await expandFile(file, packageRoot, [...localEntries, ...externalEntries], artifactPaths, options);
       if (result.changed) await writeFile17(file, result.content, "utf8");
       composedFrom.push(...result.composedFrom);
     }
@@ -7247,7 +7330,8 @@ async function validateMarkdownIncludes(artifacts, packageRoot, options = {}) {
   const artifactPaths = artifactPathMap(artifacts);
   for (const artifact of artifacts) {
     for (const file of await markdownFilesForArtifact(artifact)) {
-      await expandFile(file, packageRoot, composeEntriesForFile(artifact, file), artifactPaths, options);
+      const entries = composeEntriesForFile(artifact, file).map((entry) => ({ entry, packageRoot, artifactPaths, nodeId: options.nodeId }));
+      await expandFile(file, packageRoot, entries, artifactPaths, options);
     }
   }
 }
@@ -7257,9 +7341,11 @@ async function expandFile(file, packageRoot, appendEntries, artifactPaths, optio
   const expanded = await expandContent(raw, packageRoot, [owner], artifactPaths, options);
   let content = expanded.content;
   const composedFrom = [...expanded.composedFrom];
-  for (const entry of appendEntries) {
-    const included = await expandInclude(entry.include, packageRoot, artifactPaths, {
+  for (const external of appendEntries) {
+    const { entry } = external;
+    const included = await expandInclude(entry.include, external.packageRoot, external.artifactPaths, {
       ...options,
+      nodeId: external.nodeId,
       optional: entry.optional === true,
       markers: entry.markers !== false,
       chain: [owner]
@@ -7437,6 +7523,10 @@ function composeEntriesForFile(artifact, file) {
   if (artifact.kind === "file") return [resolve11(artifact.stagedPath ?? artifact.sourcePath), resolve11(file)].every(Boolean) && resolve11(artifact.stagedPath ?? artifact.sourcePath) === resolve11(file) ? artifact.compose : [];
   return basename16(file) === "SKILL.md" && dirname21(file) === resolve11(artifact.stagedPath ?? artifact.sourcePath) ? artifact.compose : [];
 }
+function isPrimaryMarkdownFile(artifact, file) {
+  if (artifact.kind === "file") return resolve11(artifact.stagedPath ?? artifact.sourcePath) === resolve11(file);
+  return basename16(file) === "SKILL.md" && dirname21(file) === resolve11(artifact.stagedPath ?? artifact.sourcePath);
+}
 function orderedForExpansion(artifacts) {
   return [...artifacts].sort((a, b) => Number(a.type === "fragments") - Number(b.type === "fragments"));
 }
@@ -8923,7 +9013,7 @@ Dependency chain: ${requirement.chain.join(" -> ")}`);
   }
 }
 async function collectDependencyNeeds(state, fetched, options, chain) {
-  if (fetched.manifest?.schemaVersion !== 2) return [];
+  if (!fetched.manifest || fetched.manifest.schemaVersion === 1) return [];
   const dependencies = fetched.manifest.requires ?? {};
   const suggestions = fetched.manifest.suggests ?? {};
   const dependencyEntries = Object.entries(dependencies).sort(([a], [b]) => a.localeCompare(b));
@@ -9487,6 +9577,14 @@ function detectDirectCollisions(nodes) {
   for (const [selector, owners] of bySelector) {
     const uniqueOwners = [...new Map(owners.map((owner) => [owner.node.id, owner])).values()];
     if (uniqueOwners.length <= 1) continue;
+    const replacements = uniqueOwners.filter((owner) => {
+      const artifact = owner.artifacts.find((candidate) => artifactSelectorKey(candidate) === selector);
+      return uniqueOwners.every((other) => {
+        if (other === owner) return true;
+        return artifact?.supersedes?.some((entry) => entry.package === other.node.name && entry.selector === selector) === true;
+      });
+    });
+    if (replacements.length === 1) continue;
     throw new Error(
       `Direct dependency artifact collision for ${selector}: ${uniqueOwners.map((owner) => `${owner.node.id} required by ${owner.node.requiredBy.join(", ")}`).join("; ")}. Resolve by aliasing, deselecting one artifact, or overriding the dependency selection.`
     );
@@ -9806,7 +9904,8 @@ async function renderGraphForTarget(graph, targetContext = {}) {
   const includeEdges = /* @__PURE__ */ new Map();
   const ambiguousPackageNames = ambiguousGraphPackageNames(graph);
   for (const rawNode of graph.rawNodes) {
-    if (rawNode.node.selected.length === 0) continue;
+    const ownsCompositionRules = rawNode.depth === 0 && rawNode.manifest?.schemaVersion === 3 && Boolean(rawNode.manifest.compositionRules?.length);
+    if (rawNode.node.selected.length === 0 && !ownsCompositionRules) continue;
     const rawBundle = await stageResolvedArtifactsRaw(rawNode.resolved, rawNode.artifacts);
     const fragmentCustomized = targetContext.workspaceRoot && targetContext.adapter ? await applyFragmentCustomizations(rawBundle.artifacts, {
       workspaceRoot: targetContext.workspaceRoot,
@@ -9826,11 +9925,18 @@ async function renderGraphForTarget(graph, targetContext = {}) {
     });
   }
   const aliasEdges = aliasEdgeMap(graph);
+  const compositionRules = collectCompositionRules(stagedNodes);
   for (const staged of [...stagedNodes.values()].sort((a, b) => a.rawNode.node.id.localeCompare(b.rawNode.node.id))) {
     const rawNode = staged.rawNode;
     const expandedArtifacts = await expandMarkdownIncludes(staged.artifacts, staged.root, {
       nodeId: rawNode.node.id,
       originNodeId: rawNode.node.id,
+      additionalComposeEntries: (artifact) => matchingCompositionEntries(
+        artifact,
+        rawNode.node.id,
+        targetContext.adapter?.name,
+        compositionRules
+      ),
       resolveCrossPackageInclude: async (request) => {
         const edge = aliasEdges.get(`${request.fromNodeId}\0${request.alias}`);
         if (!edge) {
@@ -9908,6 +10014,50 @@ async function renderGraphForTarget(graph, targetContext = {}) {
     graphLock: createGraphLock(graph, sortedArtifacts.map(lockArtifactFor), targetContext.targetFingerprint, [...includeEdges.values()], namespacing, overrides)
   };
 }
+function collectCompositionRules(stagedNodes) {
+  const rules = [];
+  for (const staged of stagedNodes.values()) {
+    if (staged.rawNode.depth !== 0) continue;
+    const manifest = staged.rawNode.manifest;
+    if (!manifest || manifest.schemaVersion !== 3) continue;
+    for (const rule of manifest.compositionRules ?? []) {
+      rules.push({
+        ownerNodeId: staged.rawNode.node.id,
+        ownerPackageName: staged.rawNode.node.name,
+        rule,
+        packageRoot: staged.root,
+        artifactPaths: staged.artifactPaths
+      });
+    }
+  }
+  return rules.sort((a, b) => `${a.ownerNodeId}\0${a.rule.target}\0${a.rule.include}`.localeCompare(`${b.ownerNodeId}\0${b.rule.target}\0${b.rule.include}`));
+}
+function matchingCompositionEntries(artifact, targetNodeId, runtime, rules) {
+  const selector = `${artifact.type}/${artifact.name}`;
+  const qualifiedSelector = `${artifact.packageName ?? targetNodeId}:${selector}`;
+  const seen = /* @__PURE__ */ new Set();
+  const entries = [];
+  for (const candidate of rules) {
+    const { rule } = candidate;
+    if (rule.runtimes?.length && (!runtime || !rule.runtimes.includes(runtime))) continue;
+    if (!globMatches(rule.target, selector) && !globMatches(rule.target, qualifiedSelector)) continue;
+    if (rule.exclude?.some((pattern) => globMatches(pattern, selector) || globMatches(pattern, qualifiedSelector))) continue;
+    const key = `${candidate.ownerNodeId}\0${rule.include}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    entries.push({
+      entry: { include: rule.include, markers: rule.markers },
+      packageRoot: candidate.packageRoot,
+      artifactPaths: candidate.artifactPaths,
+      nodeId: candidate.ownerNodeId
+    });
+  }
+  return entries;
+}
+function globMatches(pattern, value) {
+  const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, "\\$&").replaceAll("*", ".*");
+  return new RegExp(`^${escaped}$`).test(value);
+}
 function aliasEdgeMap(graph) {
   return new Map(graph.edges.map((edge) => [`${edge.from}\0${edge.alias}`, { to: edge.to }]));
 }
@@ -9939,10 +10089,12 @@ function sha2563(content) {
   return createHash10("sha256").update(content).digest("hex");
 }
 function assignInstallNames(graph, artifacts) {
+  const superseded = supersededLogicalSelectors(artifacts);
+  const effectiveArtifacts = artifacts.filter((artifact) => !superseded.has(artifact.logicalSelector));
   const aliases = workspaceAliases(graph);
-  validateAliasScopes(graph, artifacts, aliases);
+  validateAliasScopes(graph, effectiveArtifacts, aliases);
   const decisions = /* @__PURE__ */ new Map();
-  const withAliases = artifacts.map((artifact) => {
+  const withAliases = effectiveArtifacts.map((artifact) => {
     const alias = aliasForArtifact(artifact, graph, aliases);
     if (!alias) return artifact;
     const updated = { ...artifact, installName: alias };
@@ -9981,6 +10133,23 @@ function assignInstallNames(graph, artifacts) {
   }));
   return { artifacts: out, namespacing: [...decisions.values()], overrides: finalOverrides };
 }
+function supersededLogicalSelectors(artifacts) {
+  const removed = /* @__PURE__ */ new Set();
+  for (const replacement of artifacts) {
+    for (const declaration of replacement.supersedes ?? []) {
+      const replacementSelector = `${replacement.type}/${replacement.name}`;
+      if (declaration.selector !== replacementSelector) {
+        throw new Error(`Supersedes selector must match the replacement artifact ${replacement.logicalSelector}: ${declaration.selector}`);
+      }
+      const matches = artifacts.filter((candidate) => candidate !== replacement && candidate.packageName === declaration.package && `${candidate.type}/${candidate.name}` === declaration.selector);
+      if (matches.length > 1) {
+        throw new Error(`Supersedes target is ambiguous for ${replacement.logicalSelector}: ${declaration.package}:${declaration.selector}`);
+      }
+      if (matches[0]) removed.add(matches[0].logicalSelector);
+    }
+  }
+  return removed;
+}
 function applyWorkspaceOverrides(graph, artifacts) {
   const directives = workspaceOverrides(graph);
   if (directives.length === 0) return { artifacts, overrides: [] };
@@ -10180,7 +10349,8 @@ function lockArtifactFor(artifact) {
     kind: artifact.kind,
     hash: artifact.hash,
     channel: artifact.channel ?? "managed",
-    composedFrom: artifact.composedFrom
+    composedFrom: artifact.composedFrom,
+    supersedes: artifact.supersedes
   };
 }
 
@@ -10348,8 +10518,8 @@ async function createExactMcpRetirementPlan(desiredArtifacts, adapter, targetRoo
   }
   const removalKeys = Object.keys(operation.mergeRemoval);
   const servers = operation.mergeRemoval.mcpServers;
-  if (removalKeys.length !== 1 || removalKeys[0] !== "mcpServers" || !servers || typeof servers !== "object" || Array.isArray(servers) || Object.keys(servers).length !== 1) {
-    throw new Error("Exact MCP retirement requires exactly one MCP server and no non-MCP configuration.");
+  if (removalKeys.length !== 1 || removalKeys[0] !== "mcpServers" || !servers || typeof servers !== "object" || Array.isArray(servers) || Object.keys(servers).length === 0) {
+    throw new Error("Exact MCP retirement requires one or more MCP servers and no non-MCP configuration.");
   }
   const entry = manifest?.entries[0];
   if (entry) {
@@ -11336,15 +11506,25 @@ async function validatePackage(root) {
   } catch (error) {
     findings.push({ level: "error", message: error instanceof Error ? error.message : String(error), path: packageRoot });
   }
-  if (manifest.schemaVersion === 2 && manifest.compose) {
+  if (manifest.schemaVersion !== 1 && manifest.compose) {
     for (const entry of manifest.compose) {
       await validateManifestComposeInclude(packageRoot, entry.include, entry.optional === true, findings, manifestPath, Object.keys(manifest.requires ?? {}));
     }
   }
+  if (manifest.schemaVersion === 3) {
+    const aliases = Object.keys(manifest.requires ?? {});
+    for (const [index, rule] of (manifest.compositionRules ?? []).entries()) {
+      validateSelector(rule.include, `compositionRules[${index}].include`, findings, manifestPath, { fragmentsOnly: true, aliases });
+      if (!rule.target.startsWith("skills/")) {
+        findings.push({ level: "error", message: `compositionRules[${index}].target: v3 composition rules may target only skills/*`, path: manifestPath });
+      }
+      await validateManifestComposeInclude(packageRoot, rule.include, false, findings, manifestPath, aliases);
+    }
+  }
   return { ok: !findings.some((finding) => finding.level === "error"), manifestPath, findings };
 }
 function validateDeclaredSelectors(manifest, findings, manifestPath) {
-  if (manifest.schemaVersion === 2) {
+  if (manifest.schemaVersion !== 1) {
     for (const [alias, dependency] of Object.entries(manifest.requires ?? {})) {
       if (!alias.trim()) {
         findings.push({ level: "error", message: "Dependency alias must be non-empty", path: manifestPath });
@@ -11365,13 +11545,19 @@ function validateDeclaredSelectors(manifest, findings, manifestPath) {
   for (const [provideIndex, provide] of manifest.provides.entries()) {
     if (!("items" in provide) || !provide.items) continue;
     for (const [itemName, item] of Object.entries(provide.items)) {
+      for (const declaration of item.supersedes ?? []) {
+        const expected = `${provide.type}/${itemName}`;
+        if (declaration.selector !== expected) {
+          findings.push({ level: "error", message: `provides[${provideIndex}].items.${itemName}.supersedes: selector must equal ${expected}`, path: manifestPath });
+        }
+      }
       for (const requirement of item.requires ?? []) {
         const selector = typeof requirement === "string" ? requirement : requirement.selector;
-        validateSelector(selector, `provides[${provideIndex}].items.${itemName}.requires`, findings, manifestPath, { aliases: manifest.schemaVersion === 2 ? Object.keys(manifest.requires ?? {}) : [] });
+        validateSelector(selector, `provides[${provideIndex}].items.${itemName}.requires`, findings, manifestPath, { aliases: manifest.schemaVersion !== 1 ? Object.keys(manifest.requires ?? {}) : [] });
       }
       for (const suggestion of item.suggests ?? []) {
         const alias = typeof suggestion === "string" ? suggestion : suggestion.alias;
-        if (manifest.schemaVersion === 2 && !Object.keys(manifest.suggests ?? {}).includes(alias)) {
+        if (manifest.schemaVersion !== 1 && !Object.keys(manifest.suggests ?? {}).includes(alias)) {
           findings.push({ level: "error", message: `provides[${provideIndex}].items.${itemName}.suggests: suggestion alias not declared: ${alias}`, path: manifestPath });
         }
         for (const selector of typeof suggestion === "string" ? [] : suggestion.select ?? []) {
@@ -11380,7 +11566,7 @@ function validateDeclaredSelectors(manifest, findings, manifestPath) {
       }
       for (const entry of item.compose ?? []) {
         validateSelector(entry.include, `provides[${provideIndex}].items.${itemName}.compose.include`, findings, manifestPath, {
-          aliases: manifest.schemaVersion === 2 ? Object.keys(manifest.requires ?? {}) : [],
+          aliases: manifest.schemaVersion !== 1 ? Object.keys(manifest.requires ?? {}) : [],
           fragmentsOnly: true
         });
       }
@@ -11572,7 +11758,7 @@ async function validateOwnershipHandoff(request, transport) {
   }
   const entry = matches[0];
   const fromOwner = workspaceOwnerForRoot(request.fromWorkspaceRoot);
-  const toOwner = workspaceOwnerForRoot(request.toWorkspaceRoot);
+  const toOwner = workspaceOwnerForRoot(request.toWorkspaceRoot, request.toFleetId);
   if (fromOwner === toOwner) throw new Error("Ownership handoff requires different workspace roots.");
   if (entry.workspaceOwner !== fromOwner) {
     throw new Error(`Old owner precondition failed for ${entry.path}: expected ${fromOwner}, found ${entry.workspaceOwner}`);
@@ -11582,10 +11768,7 @@ async function validateOwnershipHandoff(request, transport) {
   }
   const destPath = containedArtifactPath(request.targetRoot, entry.path);
   if (!await transport.pathExists(destPath)) throw new Error(`Managed artifact is missing: ${entry.path}`);
-  const currentHash = await transport.hashPath(destPath);
-  if (currentHash !== entry.hash) {
-    throw new Error(`Managed artifact is drifted at ${entry.path}: manifest ${entry.hash}, current ${currentHash}`);
-  }
+  const currentHash = await verifiedEntryHash(entry, destPath, transport);
   if (request.expectedHash && currentHash !== request.expectedHash) {
     throw new Error(`Current hash precondition failed for ${entry.path}: expected ${request.expectedHash}, found ${currentHash}`);
   }
@@ -11602,6 +11785,29 @@ async function validateOwnershipHandoff(request, transport) {
     toOwner
   };
 }
+async function verifiedEntryHash(entry, destPath, transport) {
+  if (entry.semanticPlugin) throw new Error(`Ownership handoff cannot verify semantic plugin state at ${destPath}`);
+  if (entry.mode === "managed-block") {
+    const selector = managedInstructionSelector(entry.logicalSelector, entry.artifactType, entry.artifactName);
+    const state = await readManagedInstructionBlockState(destPath, selector, transport);
+    if (!state.hasBlock || state.drifted || state.hash !== entry.hash) {
+      throw new Error(`Managed artifact is drifted at ${destPath}: managed block is missing or changed`);
+    }
+    return entry.hash;
+  }
+  if (entry.mergeStrategy) {
+    if (!hasMergeRemovalContent(entry.mergeRemoval)) {
+      throw new Error(`Ownership handoff cannot verify incomplete merge ownership at ${destPath}`);
+    }
+    assertExactMergeContribution(entry.mergeRemoval, entry.mergeStrategy, await transport.readFile(destPath));
+    return entry.hash;
+  }
+  const currentHash = await transport.hashPath(destPath);
+  if (currentHash !== entry.hash) {
+    throw new Error(`Managed artifact is drifted at ${destPath}: manifest ${entry.hash}, current ${currentHash}`);
+  }
+  return currentHash;
+}
 function containedArtifactPath(targetRoot, relativePath) {
   if (!relativePath || relativePath.startsWith("/") || relativePath.includes("\0")) {
     throw new Error(`Unsafe managed artifact path: ${relativePath}`);
@@ -13610,7 +13816,7 @@ async function inspectInstalledState(source, destination, packageNames) {
         throw new Error(`Partial ownership at ${sourceEntry.renderedPath} includes packages outside the normalization selection.`);
       }
       const destinationRenderedPath = renderedEntryPathForRoot(destinationState.installRoot, sourceEntry.entry.path);
-      await assertEquivalentRuntimeBytes(sourceEntry.renderedPath, destinationRenderedPath, sourceEntry.entry.hash);
+      await assertEquivalentRuntimeState(sourceEntry.entry, sourceEntry.renderedPath, destinationRenderedPath);
       plannedDestinationPaths.add(destinationRenderedPath);
       sourceRenderedPaths.push(sourceEntry.renderedPath);
       destinationRenderedPaths.push(destinationRenderedPath);
@@ -13774,7 +13980,7 @@ async function inspectLegacySelfInstalledState(fleet, packageNames, profileName,
       if (!coveredByCurrentGraph && !matchesCurrentGraph && !orphanedOwners.has(entry.entry.workspaceOwner)) {
         throw new Error(`Legacy manifest entry is not covered by its graph lock: ${entry.renderedPath}`);
       }
-      await assertEquivalentRuntimeBytes(entry.renderedPath, entry.renderedPath, entry.entry.hash);
+      await assertEquivalentRuntimeState(entry.entry, entry.renderedPath, entry.renderedPath);
       renderedPaths.add(entry.renderedPath);
       sourceRenderedPaths.push(entry.renderedPath);
       if (coveredByCurrentGraph || matchesCurrentGraph) {
@@ -14184,6 +14390,33 @@ async function assertEquivalentRuntimeBytes(sourcePath, destinationPath, expecte
     throw new Error(`Runtime content drift at ${destinationPath}; source and destination bytes are not equivalent.`);
   }
 }
+async function assertEquivalentRuntimeState(entry, sourcePath, destinationPath) {
+  if (entry.mode === "managed-block") {
+    const selector = managedInstructionSelector(entry.logicalSelector, entry.artifactType, entry.artifactName);
+    for (const path of /* @__PURE__ */ new Set([sourcePath, destinationPath])) {
+      const state = await readManagedInstructionBlockState(path, selector, localTransport);
+      if (!state.exists || !state.hasBlock || state.drifted || state.hash !== entry.hash) {
+        throw new Error(`Runtime managed-block drift at ${path}; the installed contribution is missing or changed.`);
+      }
+    }
+    return;
+  }
+  if (entry.mergeStrategy) {
+    for (const path of /* @__PURE__ */ new Set([sourcePath, destinationPath])) {
+      if (!await pathExists(path)) throw new Error(`Runtime merge destination is missing: ${path}`);
+      const content = await readFile37(path, "utf8");
+      if (hasMergeRemovalContent(entry.mergeRemoval)) {
+        assertExactMergeContribution(entry.mergeRemoval, entry.mergeStrategy, content);
+      } else if (resolve25(sourcePath) === resolve25(destinationPath) && entry.mergeStrategy !== "codex-toml-mcp") {
+        assertExactMergeContribution({}, entry.mergeStrategy, content);
+      } else {
+        throw new Error(`Installed-state normalization cannot prove incomplete merge ownership at ${path}.`);
+      }
+    }
+    return;
+  }
+  await assertEquivalentRuntimeBytes(sourcePath, destinationPath, entry.hash);
+}
 function renderedEntryPathForRoot(root, entryPath) {
   const normalizedRoot = resolve25(root);
   const candidate = resolve25(normalizedRoot, entryPath);
@@ -14291,8 +14524,8 @@ function workspaceOwners(scope) {
   ]);
 }
 function assertSimpleVerifiableEntry(entry, path) {
-  if (entry.semanticPlugin || entry.mergeStrategy || entry.mode) {
-    throw new Error(`Installed-state normalization cannot byte-verify semantic, merge, or managed-block entry ${path}.`);
+  if (entry.semanticPlugin) {
+    throw new Error(`Installed-state normalization cannot byte-verify semantic plugin entry ${path}.`);
   }
   if (entry.kind !== "file" && entry.kind !== "dir") throw new Error(`Unsupported installed entry kind at ${path}.`);
 }
@@ -14324,7 +14557,7 @@ function graphArtifactIdentity(artifact) {
     dependencyRole: artifact.dependencyRole,
     owners: artifact.owners,
     kind: artifact.kind,
-    sourceHash: artifact.hash,
+    ...artifact.composedFrom?.length ? { composedFrom: artifact.composedFrom } : { sourceHash: artifact.hash },
     channel: artifact.channel
   });
 }
@@ -14338,7 +14571,7 @@ function graphEntryIdentity(entry) {
     dependencyRole: entry.dependencyRole,
     owners: entry.owners,
     kind: entry.kind,
-    sourceHash: entry.sourceHash,
+    ...entry.composedFrom?.length ? { composedFrom: entry.composedFrom } : { sourceHash: entry.sourceHash },
     channel: entry.channel
   });
 }
@@ -14977,7 +15210,7 @@ program.command("remember").description("append text to the local instructions o
   console.log(nextInstallNudge());
 });
 var ownershipCommand = program.command("ownership").description("inspect and transfer manifest ownership without rewriting runtime artifacts");
-ownershipCommand.command("handoff").description("transfer one managed artifact between Agentwheel workspace roots").argument("<selector>", "exact artifact selector in type/name form").requiredOption("--from-workspace-root <path>", "current owning workspace root").requiredOption("--to-workspace-root <path>", "new owning workspace root").option("--expected-hash <sha256>", "expected current artifact hash; required when applying").option("--expected-revision <sha256>", "expected install manifest revision; required when applying").option("--adapter <adapter>", "built-in adapter").option("-i, --installation-type <type>", "installation type (for example local or user)").option("--user", "use the user workspace", false).option("--local", "use the nearest local workspace", false).option("--fleet <id>", "use one registered named fleet").option("--adapter-config <path>", "adapter JSON/JSONC file").option("--adapter-module <path>", "local programmatic adapter module").option("--allow-adapter-code", "allow loading local adapter code", false).option("-t, --target-root <path>", "runtime/project root").option("--agent <name>", "named agent from merged config").option("--profile <name>", "workspace runtime profile (must resolve to one target)").option("--dry-run", "validate all preconditions without writing the manifest", false).action(async (selector, options) => {
+ownershipCommand.command("handoff").description("transfer one managed artifact between Agentwheel workspace roots").argument("<selector>", "exact artifact selector in type/name form").requiredOption("--from-workspace-root <path>", "current owning workspace root").requiredOption("--to-workspace-root <path>", "new owning workspace root").option("--to-fleet <id>", "qualify the new owner with a registered fleet id").option("--expected-hash <sha256>", "expected current artifact hash; required when applying").option("--expected-revision <sha256>", "expected install manifest revision; required when applying").option("--adapter <adapter>", "built-in adapter").option("-i, --installation-type <type>", "installation type (for example local or user)").option("--user", "use the user workspace", false).option("--local", "use the nearest local workspace", false).option("--fleet <id>", "use one registered named fleet").option("--adapter-config <path>", "adapter JSON/JSONC file").option("--adapter-module <path>", "local programmatic adapter module").option("--allow-adapter-code", "allow loading local adapter code", false).option("-t, --target-root <path>", "runtime/project root").option("--agent <name>", "named agent from merged config").option("--profile <name>", "workspace runtime profile (must resolve to one target)").option("--dry-run", "validate all preconditions without writing the manifest", false).action(async (selector, options) => {
   if (!options.dryRun && (!options.expectedHash || !options.expectedRevision)) {
     throw new Error("Applying an ownership handoff requires --expected-hash and --expected-revision from a reviewed --dry-run.");
   }
@@ -14995,6 +15228,13 @@ ownershipCommand.command("handoff").description("transfer one managed artifact b
   const adapter = await resolveAdapterForTarget(target, adapterOptions);
   const installationType = normalizedOptions.installationType ?? target.installationType ?? resolveInstallationTypeForAdapter(adapter);
   const state = installStateForTarget(target, adapter, adapterOptions, installationType);
+  const toWorkspaceRoot = normalizeCliPath(options.toWorkspaceRoot);
+  if (options.toFleet) {
+    const fleet = await showRegisteredFleet(options.toFleet);
+    if (resolve26(fleet.root) !== resolve26(toWorkspaceRoot)) {
+      throw new Error(`Destination fleet '${options.toFleet}' is registered at ${fleet.root}, not ${toWorkspaceRoot}.`);
+    }
+  }
   const request = {
     ...state,
     targetRoot: state.installRoot,
@@ -15002,7 +15242,8 @@ ownershipCommand.command("handoff").description("transfer one managed artifact b
     artifactType,
     artifactName,
     fromWorkspaceRoot: normalizeCliPath(options.fromWorkspaceRoot),
-    toWorkspaceRoot: normalizeCliPath(options.toWorkspaceRoot),
+    toWorkspaceRoot,
+    toFleetId: options.toFleet,
     expectedHash: options.expectedHash,
     expectedRevision: options.expectedRevision,
     transport: transportForTarget(target)

package/openpack.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 2,
   "name": "NestDevLab/agentwheel",
-  "version": "0.18.5",
+  "version": "0.19.1",
   "provides": [
     { "type": "skills", "path": "skills" }
   ]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentwheel",
-  "version": "0.18.5",
+  "version": "0.19.1",
   "description": "Weave skills, rules, and instructions across every AI agent.",
   "type": "module",
   "license": "MIT",

package/skills/agentwheel/SKILL.md

@@ -5,7 +5,7 @@ allowed-tools: [Bash]
 license: MIT
 metadata:
   author: NestDevLab
-  version: "0.18.5"
+  version: "0.19.1"
 ---
 
 # agentwheel

package/skills/agentwheel-discovery/SKILL.md

@@ -5,7 +5,7 @@ allowed-tools: [Bash]
 license: MIT
 metadata:
   author: NestDevLab
-  version: "0.18.5"
+  version: "0.19.1"
 ---
 
 # Agentwheel Discovery