Decouple explicit Agent Spec identity and host from catalog directory layout

[schickling-assistant]

Explicit identity and host currently win during discovery, but path_defaults always interprets the parent of agent.kdl as identity and the grandparent as host. A semantic hierarchy therefore resolves to the intended bus identity while permanently producing id-path-mismatch and host-path-mismatch; st2 validate --strict rejects it.

Minimal reproduction

Against st2 0.1.0+33d159b:

root=$(mktemp -d)
mkdir -p "$root/agents/example-host/example-repo/main/example-project/worker"
printf '%s' \
  'agent "example-repo.main.example-project.worker" { identity "example-repo.main.example-project.worker"; host "example-host"; command "exec true" }' \
  > "$root/agents/example-host/example-repo/main/example-project/worker/agent.kdl"

st2 agents --catalog "$root" --host example-host --json
st2 validate --catalog "$root" --host example-host --strict --json

The roster contains the intended bus identity:

[{"identity":"example-host.example-repo.main.example-project.worker", ...}]

Strict validation exits non-zero:

id-path-mismatch: identity 'example-repo.main.example-project.worker' differs from folder 'worker'
host-path-mismatch: host 'example-host' differs from folder 'example-project'

Current main at 16097daac413ea0babd128f58f710b3d00b38488 retains this behavior in crates/agent-spec/src/discovery.rs::path_defaults.

Expected contract

• When identity and host are explicit, a catalog can opt into path-independent declaration semantics.
• Canonical agent.kdl files may be organized hierarchically, for example <host>/<repo>/<worktree>/<project>/<seat>/agent.kdl.
• The declaration parent remains the seat's state/resource directory.
• Bus identities remain catalog-wide unique.
• Canonical agent.kdl discovery and watcher behavior remain unchanged.
• The existing <host>/<identity>/agent.kdl layout remains supported for path-defaulted specs.

This likely needs an explicit layout rule or catalog mode rather than globally suppressing useful mismatch diagnostics. Migration of an existing state-bearing directory is separate from the declaration contract.

Related: #21, #41, #52, #63, #85.

Posted on behalf of @schickling

field	value
agent_name	co1-sage
agent_session_id	ed878dac-3735-4276-b3e0-ea1b1cd65291
agent_tool	Codex CLI
agent_tool_version	0.145.0
agent_runtime	Codex CLI 0.145.0
agent_model	unknown
runtime_profile	/nix/store/mnx8agbdq3wiyb6vz63lhgscgazkrn98-coding-agent-runtime-profile/share/coding-agents/profile.json
skills_manifest	/nix/store/5r69m9k2llmri3na81518zx0a7y0d3cn-agent-skills-corpus/share/agent-skills/manifest.json
worktree	dotfiles/schickling/2026-07-20-cos-misc
machine	dev3
tooling_profile	dotfiles@0fb7e03