feat(config): add agent registration schema to org and per-repo config

Implements Phase 1 of ADR 0058 (agent registration). Adds AgentEntry
type with custom YAML unmarshaler supporting both string shorthand and
object form, validation for URL integrity hashes, allowlist membership,
path traversal, and name uniqueness. Seeds default AllowedRemoteResources
in NewPerRepoConfig. Legacy role/name/slug agent entries are now rejected
with a clear error instead of silently ignored.

Signed-off-by: Greg Allen <gallen@redhat.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Signed-off-by: Greg Allen <gallen@redhat.com>

Author: ggallen

docs/plans/agent-registration.md

@@ -52,7 +52,7 @@ type PerRepoConfig struct {
 }
 ```
 
-Add a `AgentEntry.AgentName()` helper that returns `Name` if set,
+Add a `AgentEntry.DerivedName()` helper that returns `Name` if set,
 otherwise derives it from the `Source` filename.
 
 ### 1b. Validation

internal/config/config.go

@@ -2,13 +2,72 @@ package config
 
 import (
 	"fmt"
+	"path"
+	"regexp"
 	"slices"
 	"sort"
 	"strings"
 
+	"github.com/fullsend-ai/fullsend/internal/urlutil"
 	"gopkg.in/yaml.v3"
 )
 
+var validAgentName = regexp.MustCompile(`^[a-zA-Z0-9][a-zA-Z0-9_-]*$`)
+
+// AgentEntry represents a registered agent source in config.
+// It supports both string shorthand (just the source URL/path) and
+// object form (with an explicit name override).
+type AgentEntry struct {
+	Name   string `yaml:"name,omitempty"`
+	Source string `yaml:"source"`
+}
+
+// UnmarshalYAML implements yaml.Unmarshaler so that a plain string
+// is treated as a source-only entry, while a mapping decodes normally.
+// Old-format entries (role/name/slug identity tuples from pre-ADR-0058
+// config) are detected and rejected with a clear error message.
+func (a *AgentEntry) UnmarshalYAML(value *yaml.Node) error {
+	if value.Kind == yaml.ScalarNode {
+		a.Source = value.Value
+		return nil
+	}
+	if value.Kind == yaml.MappingNode {
+		// Detect old-format entries (have "role" key but no "source" key).
+		hasRole := false
+		hasSource := false
+		for i := 0; i < len(value.Content)-1; i += 2 {
+			if value.Content[i].Value == "role" {
+				hasRole = true
+			}
+			if value.Content[i].Value == "source" {
+				hasSource = true
+			}
+		}
+		if hasRole && !hasSource {
+			return fmt.Errorf("agents entry uses legacy role/name/slug format (removed by ADR 0045 Phase 4); use source URL or path instead")
+		}
+
+		type plain AgentEntry
+		return value.Decode((*plain)(a))
+	}
+	return fmt.Errorf("agents entry must be a string or mapping, got %v", value.Kind)
+}
+
+// DerivedName returns the explicit Name if set, otherwise derives one
+// from the Source filename (e.g. "triage.yaml" → "triage").
+func (a AgentEntry) DerivedName() string {
+	if a.Name != "" {
+		return a.Name
+	}
+	src := a.Source
+	// Strip fragment (e.g. #sha256=...) before extracting filename.
+	if idx := strings.LastIndex(src, "#"); idx >= 0 {
+		src = src[:idx]
+	}
+	base := path.Base(src)
+	return strings.TrimSuffix(base, path.Ext(base))
+}
+
 const (
 	// DefaultUpstreamRepo is the canonical fullsend repository for layered workflow calls.
 	DefaultUpstreamRepo = "fullsend-ai/fullsend"
@@ -79,6 +138,7 @@ type OrgConfig struct {
 	Inference              InferenceConfig       `yaml:"inference,omitempty"`
 	Defaults               RepoDefaults          `yaml:"defaults"`
 	Repos                  map[string]RepoConfig `yaml:"repos"`
+	Agents                 []AgentEntry          `yaml:"agents,omitempty"`
 	AllowedRemoteResources []string              `yaml:"allowed_remote_resources,omitempty"`
 	CreateIssues           *CreateIssuesConfig   `yaml:"create_issues,omitempty"`
 }
@@ -107,6 +167,39 @@ func PerRepoDefaultRoles() []string {
 	return []string{"triage", "coder", "review", "fix", "retro", "prioritize"}
 }
 
+// DefaultAllowedRemoteResources returns the standard allowlist prefixes
+// for base composition and agent registration URLs.
+func DefaultAllowedRemoteResources() []string {
+	return []string{
+		"https://raw.githubusercontent.com/fullsend-ai/fullsend/",
+		"https://raw.githubusercontent.com/fullsend-ai/agents/",
+	}
+}
+
+// DefaultAgentEntries computes default agent URL entries for the given
+// harness names at a specific commit SHA. Each entry is a pinned
+// raw.githubusercontent.com URL with an integrity hash.
+type AgentEntryBuilder func(harnessName, commitSHA string) (string, error)
+
+// DefaultAgentEntries returns agent entries for the given harness names,
+// using builder to compute each URL. When builder is nil, it uses
+// a no-op that returns empty entries (for callers that don't have
+// access to the scaffold package).
+func DefaultAgentEntries(harnessNames []string, commitSHA string, builder AgentEntryBuilder) ([]AgentEntry, error) {
+	if builder == nil || commitSHA == "" {
+		return nil, nil
+	}
+	entries := make([]AgentEntry, 0, len(harnessNames))
+	for _, name := range harnessNames {
+		urlWithHash, err := builder(name, commitSHA)
+		if err != nil {
+			return nil, fmt.Errorf("building agent URL for %s: %w", name, err)
+		}
+		entries = append(entries, AgentEntry{Source: urlWithHash})
+	}
+	return entries, nil
+}
+
 // NewOrgConfig creates a new OrgConfig with sensible defaults.
 func NewOrgConfig(allRepos, enabledRepos, roles []string, inferenceProvider, org string) *OrgConfig {
 	repos := make(map[string]RepoConfig, len(allRepos))
@@ -126,12 +219,8 @@ func NewOrgConfig(allRepos, enabledRepos, roles []string, inferenceProvider, org
 			MaxImplementationRetries: 2,
 			AutoMerge:                false,
 		},
-		Repos: repos,
-		// Default allowlist for base: composition in harness wrappers (ADR-0045 Phase 2).
-		AllowedRemoteResources: []string{
-			"https://raw.githubusercontent.com/fullsend-ai/fullsend/",
-			"https://raw.githubusercontent.com/fullsend-ai/agents/",
-		},
+		Repos:                  repos,
+		AllowedRemoteResources: DefaultAllowedRemoteResources(),
 	}
 	if inferenceProvider != "" {
 		cfg.Inference = InferenceConfig{Provider: inferenceProvider}
@@ -205,12 +294,64 @@ func (c *OrgConfig) Validate() error {
 	if err := validateStatusNotifications(c.Defaults.StatusNotifications); err != nil {
 		return err
 	}
+	if err := validateAgentEntries(c.Agents, c.AllowedRemoteResources); err != nil {
+		return err
+	}
 	if err := validateCreateIssues(c.CreateIssues); err != nil {
 		return err
 	}
 	return nil
 }
 
+// validateAgentEntries checks agent entries for structural correctness.
+// Uses urlutil.IsURL, urlutil.ParseIntegrityHash, and
+// urlutil.MatchingAllowedPrefixInList for consistency with runtime
+// resolution (case-insensitive scheme, percent-decoding, dot-segment
+// cleaning).
+func validateAgentEntries(agents []AgentEntry, allowlist []string) error {
+	seen := make(map[string]bool, len(agents))
+	for i, entry := range agents {
+		if entry.Source == "" {
+			return fmt.Errorf("agents[%d]: source must not be empty", i)
+		}
+
+		name := entry.DerivedName()
+		if !validAgentName.MatchString(name) {
+			return fmt.Errorf("agents[%d]: derived agent name %q is invalid; must be alphanumeric (with hyphens/underscores) (source: %q)", i, name, entry.Source)
+		}
+		lowerName := strings.ToLower(name)
+		if seen[lowerName] {
+			return fmt.Errorf("agents[%d]: duplicate agent name %q (case-insensitive)", i, name)
+		}
+		seen[lowerName] = true
+
+		if urlutil.IsURL(entry.Source) {
+			cleanURL, _, hasHash := urlutil.ParseIntegrityHash(entry.Source)
+			if !hasHash {
+				return fmt.Errorf("agents[%d] (%s): URL source must include a valid #sha256=<64-hex-char> integrity fragment", i, name)
+			}
+			if urlutil.MatchingAllowedPrefixInList(cleanURL, allowlist) == "" {
+				return fmt.Errorf("agents[%d] (%s): URL %q is not covered by allowed_remote_resources", i, name, cleanURL)
+			}
+		} else if strings.HasPrefix(strings.ToLower(entry.Source), "http://") {
+			return fmt.Errorf("agents[%d] (%s): URL scheme must be https, got http", i, name)
+		} else {
+			if strings.Contains(entry.Source, "://") {
+				return fmt.Errorf("agents[%d] (%s): unsupported URL scheme; only https is allowed", i, name)
+			}
+			if strings.ContainsRune(entry.Source, '\\') {
+				return fmt.Errorf("agents[%d] (%s): local path must not contain backslashes", i, name)
+			}
+			for _, seg := range strings.Split(entry.Source, "/") {
+				if seg == ".." {
+					return fmt.Errorf("agents[%d] (%s): local path must not contain path traversal (..)", i, name)
+				}
+			}
+		}
+	}
+	return nil
+}
+
 func validateStatusNotifications(cfg *StatusNotificationConfig) error {
 	if cfg == nil {
 		return nil
@@ -257,10 +398,12 @@ func (c *OrgConfig) DefaultRoles() []string {
 // PerRepoConfig holds configuration for per-repo installation mode.
 // Stored in .fullsend/config.yaml within the target repository.
 type PerRepoConfig struct {
-	Version      string              `yaml:"version"`
-	KillSwitch   bool                `yaml:"kill_switch,omitempty"`
-	Roles        []string            `yaml:"roles,omitempty"`
-	CreateIssues *CreateIssuesConfig `yaml:"create_issues,omitempty"`
+	Version                string              `yaml:"version"`
+	KillSwitch             bool                `yaml:"kill_switch,omitempty"`
+	Roles                  []string            `yaml:"roles,omitempty"`
+	Agents                 []AgentEntry        `yaml:"agents,omitempty"`
+	AllowedRemoteResources []string            `yaml:"allowed_remote_resources,omitempty"`
+	CreateIssues           *CreateIssuesConfig `yaml:"create_issues,omitempty"`
 }
 
 const perRepoConfigHeader = `# fullsend per-repo configuration
@@ -276,8 +419,9 @@ func NewPerRepoConfig(roles []string, targetRepo string) *PerRepoConfig {
 		roles = DefaultAgentRoles()
 	}
 	cfg := &PerRepoConfig{
-		Version: "1",
-		Roles:   roles,
+		Version:                "1",
+		Roles:                  roles,
+		AllowedRemoteResources: DefaultAllowedRemoteResources(),
 	}
 	if targetRepo != "" {
 		cfg.CreateIssues = &CreateIssuesConfig{
@@ -323,6 +467,9 @@ func (c *PerRepoConfig) Validate() error {
 		}
 		seen[role] = true
 	}
+	if err := validateAgentEntries(c.Agents, c.AllowedRemoteResources); err != nil {
+		return err
+	}
 	if err := validateCreateIssues(c.CreateIssues); err != nil {
 		return err
 	}