Split the agent route from its durable key: mutable address, optional immutable id (#468)

* feat(agent-spec): admit an optional immutable agent id and mutable address

Agent Spec gains the two fields decision 0015 separates from the positional
`identity`: an explicit catalog-global immutable `id` and an optional mutable
`address`. Both are optional during the DELTA-003 migration window; `id` is
required in the target grammar once every live and archived subject is migrated.

- `id` is opaque. Its only two producers are UUIDv7 for a new subject and the
  frozen `<host>.<identity>` bus identity of a migrated legacy subject, and R26
  reuses it verbatim as the canonical task ID and therefore as a session socket
  path component, so validation refuses exactly what would stop being a usable
  task ID rather than imposing the address grammar.
- `address` carries R24's grammar: at most 255 ASCII characters, dotted
  1..=63-character segments of lowercase letters, digits, and hyphens, each
  beginning and ending with a letter or digit.
- `effective_address()` falls back to the positional identity, `bus_address()`
  host-qualifies it, and `effective_id()` answers with the value catalog ID
  migration freezes, so a partially migrated catalog stays coherent.

Declaring either field twice is the shape refusal `identity` and `host` already
carry. No writer emits either field yet.

* feat(catalog): validate agent id and address uniqueness and project both

Catalog admission gains the two uniqueness rules R24 states, and the read
projections gain the fields R24 and decision 0015 require them to publish.

- `dup-id` now keys on the effective agent ID rather than the bus identity, so
  one check covers a legacy duplicate identity, two explicit ids colliding
  across hosts (an ID is catalog-global, never per-host), and an explicit id
  claiming another subject's still-unmigrated frozen bus identity.
- `dup-address` is new: effective addresses are unique per resolved logical
  host among running and suspended subjects. A retired subject releases its
  address, so it neither claims nor collides. Explicit-vs-explicit and
  explicit-vs-identity-fallback are the same collision.
- Roster and graph JSON append `id`, `address`, and nullable `busAddress`,
  preserving existing field order and meanings. `identity` keeps its meaning as
  the positional declaration key and legacy address fallback.
- The graph re-keys `id`, `parentId`, `rootId`, and `ancestorIds` onto the
  effective agent ID so one namespace spans a partially migrated catalog; for an
  unmigrated subject that value is its bus identity, so output is unchanged.

Archived-subject ID uniqueness joins these checks with the migration verb.

* fix(agent-spec): stop admitting a lone id or address as a spec candidate

`id` and `address` are two of the most common keys in arbitrary JSON/TOML, and
this predicate exists to keep such files out of the spec plane. Admitting them
turned a stray file beside a real declaration into a phantom agent — in the
roster and in `catalog graph` — and, because such a file carries no launch, also
stopped the catalog from admitting at all.

Nothing needs the two arms: every real declaration carries an identity, a driver
block, a launch, or `type = "service"`, and migration adds `id` to declarations
that are candidates for other reasons.

agent-identity: dev3.direct.omp.v6c4mkm2
agent-persona: generalist
agent-supervisor: unavailable
agent-tool: OMP
agent-tool-version: 18.1.2
agent-runtime: OMP 18.1.2
tooling-profile: dotfiles@7534055

* fix(agent-spec): restrict the agent id grammar to the closed safe set

The previous grammar admitted every printable ASCII byte except `/`, `\\`, and
`:` — so backtick, `$`, `;`, `&`, `|`, `*`, `?`, and quotes were all legal in a
value R26 reuses verbatim as the canonical task ID, as a session socket path
component, and in shell-adjacent bus text, where a backtick has already executed
a command on a live host (schickling/dotfiles#1614).

The grammar is now `[A-Za-z0-9._-]`. It stays wider than the address grammar on
purpose: a frozen legacy ID keeps the case and underscores its identity carried,
so freezing an admissible identity can never be refused here. No writer emits
`id` yet, so this narrows an unproduced namespace.

agent-identity: dev3.direct.omp.v6c4mkm2
agent-persona: generalist
agent-supervisor: unavailable
agent-tool: OMP
agent-tool-version: 18.1.2
agent-runtime: OMP 18.1.2
tooling-profile: dotfiles@7534055

* fix(catalog): register both duplicate keys in one pass on one host key

Two asymmetries between the `dup-id` and `dup-address` rules:

- `dup-address` keyed on the resolved logical host while `dup-id` keyed on an
  empty placeholder, so under `--host h` a host-less declaration and an explicit
  `host "h"` one — one physical subject — were reported only under the address
  code. Both rules now read the same host key.
- Suppressing the address check for a declaration already refused for a
  duplicate ID also left that declaration's address unregistered, so a third
  subject could claim it undetected — including through `st2 agent address`,
  whose gate re-runs exactly this rule. Both keys now register in one pass
  before either is reported, and one physical conflict is still one diagnostic.

agent-identity: dev3.direct.omp.v6c4mkm2
agent-persona: generalist
agent-supervisor: unavailable
agent-tool: OMP
agent-tool-version: 18.1.2
agent-runtime: OMP 18.1.2
tooling-profile: dotfiles@7534055

Author: schickling-assistant

crates/agent-spec/src/declared.rs

@@ -285,6 +285,22 @@ pub fn parse_declared_document(source_name: &Path, source: &str) -> DeclaredPars
             ));
             continue;
         }
+        for field in node.children_named("id").skip(1) {
+            diagnostics.push(shape_diagnostic(
+                source_name,
+                field.span,
+                DeclaredDiagnosticCode::DuplicateRoutingField,
+                "agent id must be declared exactly once".to_owned(),
+            ));
+        }
+        for field in node.children_named("address").skip(1) {
+            diagnostics.push(shape_diagnostic(
+                source_name,
+                field.span,
+                DeclaredDiagnosticCode::DuplicateRoutingField,
+                "agent address must be declared exactly once".to_owned(),
+            ));
+        }
         for field in node.children_named("identity").skip(1) {
             diagnostics.push(shape_diagnostic(
                 source_name,

crates/agent-spec/src/discovery.rs

@@ -332,6 +332,10 @@ fn unobservable_entry_may_hide_declaration(
 /// gain fields without breaking readers.
 #[derive(Debug, Clone, Default, PartialEq, Eq)]
 pub struct Declared {
+    /// `id` as written in the file. `None` on a legacy declaration with no explicit agent ID.
+    pub id: Option<String>,
+    /// `address` as written in the file. `None` when `identity` is the effective legacy address.
+    pub address: Option<String>,
     /// `identity` as written in the file. `None` when the file relies on [`path_defaults`].
     pub identity: Option<String>,
     /// `host` as written in the file. `None` when the file relies on [`path_defaults`].
@@ -343,6 +347,8 @@ pub struct Declared {
 impl From<&RawSpec> for Declared {
     fn from(raw: &RawSpec) -> Self {
         Self {
+            id: raw.id.clone(),
+            address: raw.address.clone(),
             identity: raw.identity.clone(),
             host: raw.host.clone(),
             job_type: raw.job_type.clone(),

crates/agent-spec/src/kdl_format.rs

@@ -71,9 +71,11 @@ fn agent_node_to_raw(node: &DeclaredNode) -> anyhow::Result<RawSpec> {
 
     for child in &node.children {
         match child.name.as_str() {
+            "id" => parse_single_string_field(child, "id", &mut raw.id)?,
+            "address" => parse_single_string_field(child, "address", &mut raw.address)?,
             "identity" => raw.identity = arg_string(child).or(raw.identity),
-            "name" => parse_presentation(child, "name", &mut raw.name)?,
-            "description" => parse_presentation(child, "description", &mut raw.description)?,
+            "name" => parse_single_string_field(child, "name", &mut raw.name)?,
+            "description" => parse_single_string_field(child, "description", &mut raw.description)?,
             "host" => raw.host = arg_string(child),
             "role" => raw.role = arg_string(child),
             "type" => raw.job_type = arg_string(child),
@@ -406,7 +408,11 @@ fn opencode_driver_node_to_raw(node: &DeclaredNode) -> anyhow::Result<OpenCodeDr
     })
 }
 
-fn parse_presentation(
+/// Parse one direct child declaring exactly one positional string, at most once.
+///
+/// Shared by the presentation fields (`name`, `description`) and the routing fields (`id`,
+/// `address`), which have the same source shape and the same once-only rule.
+fn parse_single_string_field(
     node: &DeclaredNode,
     field: &str,
     destination: &mut Option<String>,

crates/agent-spec/src/lib.rs

@@ -46,10 +46,12 @@ pub use discovery::{
     parse_declared, path_defaults,
 };
 pub use spec::{
+    AGENT_ADDRESS_MAX_BYTES, AGENT_ADDRESS_SEGMENT_MAX_BYTES, AGENT_ID_MAX_BYTES,
     AgentDesiredState, AgentSpec, ClaudeDriver, CodexDriver, DeliveryReadiness, DeliveryTransport,
     Driver, JobType, OpenCodeDriver, PiDriver, Resource, Restart, RestartMode, STREAM_TASK_PREFIX,
     SessionDriver, Stream, StreamLaunch, Task, TaskKind, TaskLifecycle, parse_duration,
-    stream_name_of_task, validate_desired_state_reason,
+    stream_name_of_task, validate_agent_address, validate_agent_id,
+    validate_desired_state_reason,
 };
 pub use profile::{
     DEFAULT_SELECTOR_LIMIT_BYTES, DescriptorValidationError, PROFILE_DESCRIPTOR_ABI_VERSION,

crates/agent-spec/src/spec.rs

@@ -27,6 +27,15 @@ pub const AGENT_NAME_MAX_CHARS: usize = 160;
 pub const AGENT_DESCRIPTION_MAX_CHARS: usize = 1_000;
 /// Maximum UTF-8 byte length for a non-running desired-state rationale.
 pub const AGENT_DESIRED_STATE_REASON_MAX_BYTES: usize = 160;
+/// Maximum ASCII length of an explicit agent address (R24).
+pub const AGENT_ADDRESS_MAX_BYTES: usize = 255;
+/// Maximum length of one dotted agent-address segment (R24).
+pub const AGENT_ADDRESS_SEGMENT_MAX_BYTES: usize = 63;
+/// Maximum ASCII length of an explicit immutable agent ID.
+///
+/// The two admitted producers are UUIDv7 for a new subject and the frozen `<host>.<identity>`
+/// bus identity of a migrated legacy subject, so the ID namespace shares the address budget.
+pub const AGENT_ID_MAX_BYTES: usize = 255;
 
 /// Declarative whole-agent lifecycle intent.
 #[derive(Debug, Clone, PartialEq, Eq)]
@@ -314,7 +323,13 @@ impl AgentDesiredState {
 /// A rendered agent job, lowered to the shared declaration fields st2 and other readers inspect.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct AgentSpec {
-    /// Unique id; the bus id is `<host>.<identity>`.
+    /// Explicit immutable catalog-global agent ID (R24). `None` on a legacy declaration that
+    /// catalog ID migration has not reached yet; required in the target grammar.
+    pub id: Option<String>,
+    /// Explicit mutable agent address (R24). `None` means the positional `identity` below is the
+    /// effective legacy address.
+    pub address: Option<String>,
+    /// The positional declaration key and legacy address fallback. Not immutable subject identity.
     pub identity: String,
     /// Optional mutable human-facing label. Never used as an automation selector.
     pub name: Option<String>,
@@ -594,6 +609,33 @@ impl AgentSpec {
         )
     }
 
+    /// The effective immutable subject ID during the ID migration window (R24).
+    ///
+    /// The explicit `id` when the declaration carries one, otherwise the legacy
+    /// `<host>.<identity>` bus identity — which is exactly the value catalog ID migration freezes
+    /// as this subject's explicit ID, so a mixed catalog stays coherent while it is migrated.
+    pub fn effective_id(&self, this_host: &str) -> String {
+        self.id
+            .clone()
+            .unwrap_or_else(|| self.bus_id(this_host))
+    }
+
+    /// The effective agent address (R24): the explicit `address` when present, otherwise the
+    /// positional `identity` legacy fallback.
+    pub fn effective_address(&self) -> &str {
+        self.address.as_deref().unwrap_or(&self.identity)
+    }
+
+    /// The human-routable bus address `<host>.<effective address>` (R24), using `this_host` when
+    /// `host` is unset. This is a mutable route, never the immutable subject ID.
+    pub fn bus_address(&self, this_host: &str) -> String {
+        format!(
+            "{}.{}",
+            self.host.as_deref().unwrap_or(this_host),
+            self.effective_address()
+        )
+    }
+
     /// The host that should run this spec, defaulting to `this_host` when unset.
     pub fn resolved_host<'a>(&'a self, this_host: &'a str) -> &'a str {
         self.host.as_deref().unwrap_or(this_host)
@@ -658,6 +700,8 @@ pub fn parse_duration(s: &str) -> Result<Duration, String> {
 /// render-agnostic.
 #[derive(Debug, Default, Deserialize)]
 pub(crate) struct RawSpec {
+    pub id: Option<String>,
+    pub address: Option<String>,
     pub identity: Option<String>,
     pub name: Option<String>,
     pub description: Option<String>,
@@ -1208,6 +1252,12 @@ impl RawSpec {
     /// A parsed file is a *spec candidate* when it carries an agent-shaped signal — an identity,
     /// lifecycle intent, the supported `service` type, or task blocks. Random TOML/JSON in the tree
     /// has none of these and is skipped.
+    ///
+    /// `id` and `address` are deliberately not signals. They are two of the most common keys in
+    /// arbitrary JSON/TOML — a dropped GitHub payload, a task cache, a session record — and a file
+    /// whose only agent-shaped key is one of them cannot be a valid declaration anyway: it carries
+    /// no launch, so it would only ever join the roster as a phantom agent and stop the catalog
+    /// from admitting. Migration adds `id` to declarations that are already candidates.
     pub(crate) fn looks_like_spec(&self) -> bool {
         self.identity.is_some()
             || self.job_type.as_deref() == Some("service")
@@ -1247,6 +1297,12 @@ impl RawSpec {
             self.description.as_deref(),
             AGENT_DESCRIPTION_MAX_CHARS,
         )?;
+        if let Some(id) = self.id.as_deref() {
+            validate_agent_id(id)?;
+        }
+        if let Some(address) = self.address.as_deref() {
+            validate_agent_address(address)?;
+        }
         let retired = reject_explicit_null("retired", self.retired)?;
         let desired_state_value = reject_explicit_null("desired_state", self.desired_state)?;
         let desired_state_reason =
@@ -1444,6 +1500,8 @@ impl RawSpec {
         let resources = self.resource.lower()?;
 
         Ok(AgentSpec {
+            id: self.id,
+            address: self.address,
             identity,
             name: self.name,
             description: self.description,
@@ -1571,6 +1629,82 @@ pub fn validate_presentation(
     Ok(())
 }
 
+/// Validate an explicit immutable agent ID at the shared parse/authoring boundary (R24).
+///
+/// The ID is opaque, but not arbitrary: R26 reuses it verbatim as the canonical task ID and
+/// therefore as a session socket path component, and IDs travel through shell-adjacent text (bus
+/// messages, notices, journal lines), where a backtick has already executed a command on a live
+/// host (schickling/dotfiles#1614). So the grammar is the closed safe set `[A-Za-z0-9._-]`, which
+/// admits both admitted producers — a new subject's UUIDv7 and a migrated subject's frozen
+/// `<host>.<identity>` bus identity — and refuses every shell metacharacter, path and host
+/// separator, whitespace byte, and non-ASCII byte outright.
+///
+/// It stays wider than the address grammar on purpose: a frozen legacy ID keeps host-looking bytes
+/// and whatever case and underscores its identity carried, so freezing an admissible identity can
+/// never be refused here. Equal bytes in the two namespaces do not collide.
+pub fn validate_agent_id(value: &str) -> anyhow::Result<()> {
+    anyhow::ensure!(!value.is_empty(), "agent `id` cannot be empty");
+    anyhow::ensure!(
+        value.len() <= AGENT_ID_MAX_BYTES,
+        "agent `id` '{value}' exceeds the {AGENT_ID_MAX_BYTES}-byte limit"
+    );
+    anyhow::ensure!(
+        value
+            .bytes()
+            .all(|byte| byte.is_ascii_alphanumeric() || matches!(byte, b'.' | b'_' | b'-')),
+        "agent `id` '{value}' must match [A-Za-z0-9._-]+"
+    );
+    anyhow::ensure!(
+        !value.starts_with('.') && !value.ends_with('.'),
+        "agent `id` '{value}' cannot begin or end with `.`"
+    );
+    Ok(())
+}
+
+/// Validate an explicit mutable agent address at the shared parse/authoring boundary (R24).
+///
+/// An explicit address is at most [`AGENT_ADDRESS_MAX_BYTES`] ASCII characters and is a dotted
+/// sequence of 1-to-[`AGENT_ADDRESS_SEGMENT_MAX_BYTES`]-character segments. Each segment contains
+/// only lowercase letters, digits, and hyphens and begins and ends with a letter or digit.
+pub fn validate_agent_address(value: &str) -> anyhow::Result<()> {
+    anyhow::ensure!(
+        !value.is_empty(),
+        "agent `address` cannot be empty; omit it to fall back to the positional identity"
+    );
+    anyhow::ensure!(
+        value.len() <= AGENT_ADDRESS_MAX_BYTES,
+        "agent `address` '{value}' exceeds the {AGENT_ADDRESS_MAX_BYTES}-character limit"
+    );
+    anyhow::ensure!(
+        value.is_ascii(),
+        "agent `address` '{value}' must be ASCII"
+    );
+    for segment in value.split('.') {
+        anyhow::ensure!(
+            !segment.is_empty(),
+            "agent `address` '{value}' has an empty dotted segment"
+        );
+        anyhow::ensure!(
+            segment.len() <= AGENT_ADDRESS_SEGMENT_MAX_BYTES,
+            "agent `address` '{value}' segment '{segment}' exceeds {AGENT_ADDRESS_SEGMENT_MAX_BYTES} characters"
+        );
+        anyhow::ensure!(
+            segment
+                .bytes()
+                .all(|byte| byte.is_ascii_lowercase() || byte.is_ascii_digit() || byte == b'-'),
+            "agent `address` '{value}' segment '{segment}' must match [a-z0-9-]+"
+        );
+        let first = segment.as_bytes()[0];
+        let last = segment.as_bytes()[segment.len() - 1];
+        anyhow::ensure!(
+            (first.is_ascii_lowercase() || first.is_ascii_digit())
+                && (last.is_ascii_lowercase() || last.is_ascii_digit()),
+            "agent `address` '{value}' segment '{segment}' must begin and end with a letter or digit"
+        );
+    }
+    Ok(())
+}
+
 impl RawTask {
     pub(crate) fn lower(
         self,

crates/agent-spec/tests/declared_document.rs

@@ -112,6 +112,10 @@ fn unnamed_tasks_and_reserved_schedules_are_causal_red_shape_errors() {
 #[test]
 fn duplicate_routing_fields_are_shape_errors() {
     let source = r#"agent "worker" {
+  id "first"
+  id "second"
+  address "first"
+  address "second"
   identity "first"
   identity "second"
   host "first"
@@ -125,7 +129,12 @@ fn duplicate_routing_fields_are_shape_errors() {
             .iter()
             .map(|diagnostic| diagnostic.code.as_str())
             .collect::<Vec<_>>(),
-        ["duplicate-routing-field", "duplicate-routing-field"]
+        [
+            "duplicate-routing-field",
+            "duplicate-routing-field",
+            "duplicate-routing-field",
+            "duplicate-routing-field"
+        ]
     );
     assert!(!parsed.is_valid());
 }