feat(resync): notify-chain subscribes a binding to its ancestors' layers (#367)

Resync notifies a carrier's owner. For a Resource Profile whose layers
compose along the supervisor edge, that leaves every descendant's
effective view dependent on carriers nothing tells it about: when an
ancestor's layer changes, the descendant keeps acting on the view it
read at launch.

Add `notify-chain` to a profile declaration. A binding through such a
profile also subscribes to the same-scheme carriers its supervisor
ancestors declare, resolved entirely in resolve_watch_set — subscriptions,
coalescing, digest gating, admission and delivery are untouched.

The walk reuses each ancestor's own declared URI against that ancestor's
own directory rather than synthesizing a subject: st2 owns no profile's
URI grammar, and this is the identical call the ancestor's own
subscription makes, so containment holds unchanged. Matching is by
profile scheme, never by binding label, because labels are agent-local
and replaceable. Each ancestor's layer carries the key
`<label>@<ancestor-bus-id>` so two ancestors cannot collapse onto one
supersession key. Retired ancestors are skipped and the walk continues
through them to the root, honoring both declaration spellings.

The traversal DING already needed is lifted into src/supervisor_chain.rs
rather than copied a third time.

Implements the design in #365.

agent-identity: dev3.direct.claude.gvacdkt7
agent-persona: generalist
agent-supervisor: unavailable
agent-tool: Claude Code
agent-tool-version: 2.1.237
agent-runtime: Claude Code 2.1.237
tooling-profile: dotfiles@cab57ad

Author: schickling-assistant

crates/agent-spec/src/profile.rs

@@ -73,6 +73,10 @@ impl std::fmt::Display for ProfileClass {
 pub struct ResourceProfile {
     pub scheme: String,
     pub source: ProfileSource,
+    /// When set, a binding through this profile also subscribes to the same-scheme carriers its
+    /// declared `supervisor` ancestors bind. Off by default: only a profile whose layers compose
+    /// along that edge has any reason to widen a subscription past the binding agent.
+    pub notify_chain: bool,
 }
 
 /// Where one profile's denotation comes from. Wasm-only per Q10.
@@ -103,6 +107,7 @@ impl ResourceProfile {
                 class,
                 containment_root: None,
             },
+            notify_chain: false,
         }
     }
 
@@ -122,9 +127,22 @@ impl ResourceProfile {
                 class,
                 containment_root: Some(containment_root),
             },
+            notify_chain: false,
         }
     }
 
+    /// Declare that carriers of this profile notify along the `supervisor` chain.
+    #[must_use]
+    pub fn with_notify_chain(mut self, notify_chain: bool) -> Self {
+        self.notify_chain = notify_chain;
+        self
+    }
+
+    /// Whether this profile's bindings subscribe to their ancestors' same-scheme carriers.
+    pub fn notify_chain(&self) -> bool {
+        self.notify_chain
+    }
+
     /// The declared class for carriers this profile resolves.
     pub fn class(&self) -> ProfileClass {
         match &self.source {

flake.nix

@@ -171,6 +171,8 @@
             "--test"
             "resync"
             "--test"
+            "resync_notify_chain"
+            "--test"
             "profile_wasm"
           ];
         });

src/catalog.rs

@@ -39,6 +39,9 @@ pub struct DeclaredProfile {
     pub wasm: String,
     /// How carriers resolved through this profile notify; defaults to coalesced.
     pub class: ProfileClass,
+    /// Whether a binding through this profile also subscribes to its ancestors' same-scheme
+    /// carriers; defaults to off.
+    pub notify_chain: bool,
 }
 
 /// What `<catalog>/catalog.kdl` declares. An absent file leaves every field empty.
@@ -159,6 +162,8 @@ fn parse_profile(node: &kdl::KdlNode) -> anyhow::Result<DeclaredProfile> {
     let mut wasm: Option<String> = None;
     let mut class = ProfileClass::Coalesced;
     let mut seen_class = false;
+    let mut notify_chain = false;
+    let mut seen_notify_chain = false;
     for child in children.nodes() {
         if child.children().is_some() {
             anyhow::bail!(
@@ -204,8 +209,20 @@ fn parse_profile(node: &kdl::KdlNode) -> anyhow::Result<DeclaredProfile> {
                     )
                 })?;
             }
+            "notify-chain" => {
+                if seen_notify_chain {
+                    anyhow::bail!("profile '{scheme}' declares notify-chain more than once");
+                }
+                seen_notify_chain = true;
+                notify_chain = child.get(0).and_then(|v| v.as_bool()).ok_or_else(|| {
+                    anyhow::anyhow!(
+                        "profile '{scheme}': notify-chain takes a boolean, e.g. notify-chain #true"
+                    )
+                })?;
+            }
             other => anyhow::bail!(
-                "unknown profile field '{other}' in profile '{scheme}' (expected wasm or class)"
+                "unknown profile field '{other}' in profile '{scheme}' \
+                 (expected wasm, class, or notify-chain)"
             ),
         }
     }
@@ -216,6 +233,7 @@ fn parse_profile(node: &kdl::KdlNode) -> anyhow::Result<DeclaredProfile> {
         scheme: scheme.to_owned(),
         wasm,
         class,
+        notify_chain,
     })
 }
 
@@ -383,9 +401,11 @@ pub fn declared_profiles(catalog_root: &Path) -> anyhow::Result<ResourceProfileR
                         relative,
                         declared.class,
                     )
+                    .with_notify_chain(declared.notify_chain)
                 }
                 ResolvedProfileModule::External(module) => {
                     ResourceProfile::wasm(declared.scheme, module, declared.class)
+                        .with_notify_chain(declared.notify_chain)
                 }
             };
             Ok(registry.with_profile(profile))
@@ -497,11 +517,13 @@ mod tests {
                     scheme: "dev.example.goal".into(),
                     wasm: "resolvers/goal.wasm".into(),
                     class: ProfileClass::Coalesced,
+                    notify_chain: false,
                 },
                 DeclaredProfile {
                     scheme: "dev.example.tree".into(),
                     wasm: "/abs/resolvers/tree.wasm".into(),
                     class: ProfileClass::Silent,
+                    notify_chain: false,
                 },
             ]
         );

src/ding/mod.rs

@@ -28,6 +28,7 @@ mod harness;
 use crate::message::{self, Message};
 use crate::run::{CAPTURE_CAP_BYTES, read_bounded_tail, reap_detached};
 use crate::status;
+use crate::supervisor_chain::{SUPERVISOR_CHAIN_LIMIT, chain_bus_ids, resolve_spec};
 
 use composer::{ComposerState, classify_composer, classify_receipt};
 use harness::ReceiptState;
@@ -36,7 +37,6 @@ const BRACKETED_PASTE_START: &str = "\x1b[200~";
 const BRACKETED_PASTE_END: &str = "\x1b[201~";
 const SUBJECT_MAX_CHARS: usize = 160;
 const SENDER_MAX_CHARS: usize = 80;
-const SUPERVISOR_CHAIN_LIMIT: usize = 64;
 /// The marker for a declared non-agent event source. A fixed st2-chosen literal — never
 /// producer-supplied text — so the bounded-notice proofs are unaffected.
 const SOURCE_MARKER: &str = "»";
@@ -97,51 +97,6 @@ fn normalize_field(value: Option<&str>, fallback: &str, max_chars: usize) -> Str
     }
 }
 
-fn resolve_spec<'a>(
-    specs: &'a [crate::AgentSpec],
-    identity: &str,
-    local_host: &str,
-) -> Option<&'a crate::AgentSpec> {
-    let mut matches = specs.iter().filter(|spec| {
-        spec.bus_id(local_host) == identity
-            || (spec.resolved_host(local_host) == local_host && spec.identity == identity)
-    });
-    let resolved = matches.next()?;
-    matches.next().is_none().then_some(resolved)
-}
-
-#[derive(Debug, PartialEq, Eq)]
-enum SupervisorChainError {
-    Cycle,
-    MissingSupervisor,
-    DepthLimit,
-}
-
-fn supervisor_chain(
-    specs: &[crate::AgentSpec],
-    start: &crate::AgentSpec,
-    this_host: &str,
-) -> Result<Vec<String>, SupervisorChainError> {
-    let mut chain = Vec::new();
-    let mut visited = HashSet::new();
-    let mut current = start;
-
-    for _ in 0..SUPERVISOR_CHAIN_LIMIT {
-        let bus_id = current.bus_id(this_host);
-        if !visited.insert(bus_id.clone()) {
-            return Err(SupervisorChainError::Cycle);
-        }
-        chain.push(bus_id);
-        let Some(supervisor) = current.supervisor.as_deref() else {
-            return Ok(chain);
-        };
-        current = resolve_spec(specs, supervisor, current.resolved_host(this_host))
-            .ok_or(SupervisorChainError::MissingSupervisor)?;
-    }
-
-    Err(SupervisorChainError::DepthLimit)
-}
-
 struct RelationshipResolver {
     specs: Vec<crate::AgentSpec>,
     valid: bool,
@@ -178,10 +133,10 @@ fn relationship_marker(
     if sender_id == recipient_id {
         return "↺".to_string();
     }
-    let Ok(recipient_chain) = supervisor_chain(&resolver.specs, recipient, this_host) else {
+    let Ok(recipient_chain) = chain_bus_ids(&resolver.specs, recipient, this_host) else {
         return "?".to_string();
     };
-    let Ok(sender_chain) = supervisor_chain(&resolver.specs, sender, this_host) else {
+    let Ok(sender_chain) = chain_bus_ids(&resolver.specs, sender, this_host) else {
         return "?".to_string();
     };
 
@@ -1509,8 +1464,8 @@ mod tests {
         let recipient = resolve_spec(&resolver.specs, "h.recipient", "h").unwrap();
 
         assert_eq!(
-            supervisor_chain(&resolver.specs, recipient, "h"),
-            Err(SupervisorChainError::Cycle),
+            chain_bus_ids(&resolver.specs, recipient, "h"),
+            Err(crate::supervisor_chain::SupervisorChainError::Cycle),
             "cycle detection must be distinct from the independent depth limit"
         );
 

src/lib.rs

@@ -43,6 +43,7 @@ pub mod resync;
 pub mod run;
 pub mod service;
 pub mod status;
+pub mod supervisor_chain;
 pub mod task_inventory;
 pub mod telemetry;
 pub mod validate;