fix(resync): keep live notify chains complete (#371)

Co-authored-by: Johannes Schickling <schickling.j@gmail.com>

Author: schickling-assistant

docs/vrs/06-resync/requirements.md

@@ -62,20 +62,22 @@ root [`R05`](../requirements.md); Resource bindings are defined by
 
 - **RESYNC-R01 Watch set:** While an agent is running on this host, the
   supervisor watches exactly the local files denoted by that agent's active
-  resource bindings plus its own declaration file. The watch attaches to each
-  carrier's parent directory non-recursively and tracks directory identity so
-  whole-file replacement by rename keeps working. Nothing outside this set is
-  watched; installation failure degrades to timer-based digest polling rather
-  than losing the capability.
+  resource bindings, the opt-in ancestor carriers required by `RESYNC-R09`,
+  plus its own declaration file. The watch attaches to each carrier's parent
+  directory non-recursively and tracks directory identity so whole-file
+  replacement by rename keeps working. Nothing outside this set is watched;
+  installation failure degrades to timer-based digest polling rather than
+  losing the capability.
 - **RESYNC-R02 Explicit watch contract:** The resync watcher states what it
   watches and why, denies everything else by default, ignores read/open
   access events, and never traverses payload trees — refining [`R14`](../requirements.md)
   and the mutation-only wakeup invariant.
-- **RESYNC-R03 Seeded baseline:** On supervisor start every watchable carrier
-  is recorded as either `present(<content-digest>)` or `missing` without
-  emitting. Only a transition between proven states produces an event; a
-  restart alone wakes nobody. Permission and transient I/O failures establish
-  neither state and are retried rather than interpreted as absence.
+- **RESYNC-R03 Seeded baseline:** On supervisor start and at every live-seat
+  transition, every watchable carrier is recorded as either
+  `present(<content-digest>)` or `missing` without emitting. Only a transition
+  between proven states produces an event; a restart alone wakes nobody.
+  Permission and transient I/O failures establish neither state and are retried
+  rather than interpreted as absence.
 
 ### Must classify before notifying
 
@@ -122,6 +124,22 @@ root [`R05`](../requirements.md); Resource bindings are defined by
   resumes, so resume re-observes current state silently and only later
   transitions notify.
 
+### Must compose and install complete live views
+
+- **RESYNC-R09 Opt-in supervisor-chain coverage:** When a profile declares
+  `notify-chain`, a live agent's watch set also contains every active
+  same-profile-scheme carrier declared by each non-retired supervisor ancestor.
+  Traversal continues through a retired middle ancestor without including that
+  ancestor's carrier. Profiles without the flag and native bindings retain
+  agent-local coverage. A missing, cyclic, ambiguous, or otherwise unwalkable
+  supervisor chain is diagnosed; it never becomes a silent guessed chain.
+- **RESYNC-R10 Launch-boundary completeness:** A canonical seat's complete
+  catalog-aware watch set is installed synchronously when reconciliation first
+  proves the seat live and before any later launch target may block. Reinstalling
+  an already-live seat is idempotent: unchanged own and ancestor subscriptions
+  retain their baselines and pending transitions. Full refresh remains the final
+  authority for lifecycle removal and hot profile reload.
+
 ## Evidence
 
 The composition (parent-directory watch → classification → carrier-state-keyed

docs/vrs/06-resync/spec.md

@@ -48,6 +48,40 @@ falls back to a guessed local rule or stops the supervisor. Watchability of
 every active binding is projected into `st2 agents --json` as part of the
 declared Resource projection so absence of coverage is observable.
 
+## Supervisor-chain composition (RESYNC-R09..R10)
+
+```text
+root goal carrier ───────────────┐
+                                 v
+root seat <- supervisor - lead seat <- supervisor - worker seat
+                    goal carrier ────────────────> worker watch set
+worker goal carrier ────────────────────────────> worker watch set
+```
+
+For each active binding whose registered profile declares `notify-chain`, watch
+resolution first resolves the binding's own carrier, then validates and walks
+the seat's supervisor chain against the pass's complete discovered spec vector.
+At every non-retired ancestor it resolves active bindings with the same profile
+scheme against that ancestor's own declaration directory. Each inherited
+subscription retains the ancestor's binding label qualified by owner bus ID
+(`goal@hetz.root`), so mutations in two layers cannot share a supersession key.
+A retired ancestor contributes no layer, but traversal continues to its
+ancestors.
+
+Chain membership comes only from a profile's trusted opt-in flag and exact URI
+scheme. Binding labels do not define composition, native local bindings never
+gain it implicitly, and profiles without the flag remain agent-local. A
+missing, ambiguous, cyclic, cross-host, or otherwise unwalkable supervisor edge
+produces a reconcile diagnostic and no invented ancestor subscription. Profile
+resolution failures remain contained to the failed carrier.
+
+The live-install API takes both the canonical seat and the complete discovered
+spec vector. It resolves the complete own-plus-ancestor set under the
+supervisor's current profile registry, sends one targeted watch-set replacement,
+and waits for the worker acknowledgement. Reinstalling the same identity and
+paths preserves carrier baselines, occurrence sequences, dirty state, and
+pending transitions.
+
 ## Classification
 
 Classification is decided before a path enters the watch set:
@@ -79,18 +113,25 @@ meaningful.
   same-path replacement, mirroring `CatalogDeclarationWatcher`.
 - The watcher owns no reconcile authority: a resync mutation does not wake a
   full-catalog pass. It shares only the observation primitives.
-- After lifecycle execution, each reconcile pass atomically replaces the watch
+- Before lifecycle execution, each pass synchronously upserts the complete
+  catalog-aware watch set for every successfully compiled canonical seat it
+  observed alive. A successful canonical launch or restart performs the same
+  acknowledged upsert at the exact live transition before execution advances
+  to any later task. Both paths resolve supervisor-chain carriers against the
+  complete discovered spec vector, never a one-spec view.
+- After lifecycle execution, each reconcile pass atomically refreshes the watch
   set with agents whose canonical seat was observed alive or successfully
-  launched/restarted in that pass. Desired declarations, dead keep-retained
-  seats, and companion-only launches never become watched. If strict discovery
-  temporarily rejects a declaration whose exact canonical seat remains
-  observed alive, its prior declaration subscription survives with its carrier
-  state and pending transition; it drops as soon as that seat is not live.
-  Existing valid subscriptions are matched by declaration path and binding
-  label. Each refresh takes bus id, canonical seat id, carrier path, label, and
-  class from the current declaration while retaining carrier state, the
-  per-subscription occurrence sequence, any immutable pending transition, and
-  dirty state; only new subscriptions seed silently with sequence zero.
+  launched/restarted in that pass. This refresh owns removals, malformed
+  declaration retention, and hot profile replacement. Desired declarations,
+  dead keep-retained seats, and companion-only launches never become watched.
+  If strict discovery temporarily rejects a declaration whose exact canonical
+  seat remains observed alive, its prior declaration subscription survives with
+  its carrier state and pending transition; it drops as soon as that seat is
+  not live. Existing valid subscriptions are matched by declaration path and
+  binding label. Each refresh takes bus id, canonical seat id, carrier path,
+  label, and class from the current declaration while retaining carrier state,
+  the per-subscription occurrence sequence, any immutable pending transition,
+  and dirty state; only new subscriptions seed silently with sequence zero.
 - A previously blind path is state-diffed both before and after its recovered
   parent watch is registered, closing the poll-to-registration gap.
 - Installation failure degrades to timer-based carrier polling over the watch
@@ -149,3 +190,5 @@ ring.
 - No remote/non-local carrier watching.
 - No write attribution beyond static classes (RESYNC-T01).
 - No catch-up replay of missed changes (RESYNC-T03).
+- No implicit supervisor-chain inference for native bindings or profiles that
+  do not declare `notify-chain`.

docs/vrs/07-resource-profile/requirements.md

@@ -120,6 +120,15 @@ accepted rationale is recorded in
   `catalog.kdl` that names them and retires old module bytes only after that
   declaration stops naming them.
 
+### Must opt into chain notification
+
+- **PROFILE-R11 Explicit chain notification:** A profile may opt into
+  supervisor-chain notification. For a binding through that profile, resync
+  includes active same-scheme carriers from every non-retired supervisor
+  ancestor in the descendant's watch set. The flag is false by default, does
+  not change path containment or task launch, and an invalid supervisor chain
+  is reported rather than silently approximated.
+
 ## Evidence
 
 The mechanism choice and sandbox bounds are supported by the

docs/vrs/07-resource-profile/spec.md

@@ -15,14 +15,14 @@ modules, and the handoff of resolved carriers to
 remote access, Agent Spec binding grammar, event delivery, or task lifecycle.
 Those remain downstream profile concerns or existing root contracts.
 
-## Architecture (PROFILE-R01..R10)
+## Architecture (PROFILE-R01..R11)
 
 ```text
 Agent Spec resource URI (opaque, byte-preserved)
              |
              v exact RFC 3986 scheme
 <catalog>/catalog.kdl
-  profile "<scheme>" { wasm "<module>"; class "<class>"; }
+  profile "<scheme>" { wasm "<module>"; class "<class>"; notify-chain #true; }
              |
              +--> catalog-relative module -- normalized no-follow projection
              |                              + catalog root hash / transaction
@@ -92,6 +92,7 @@ catalog {
 profile "dev.schickling.agent-goal" {
   wasm "resolvers/agent-goal.wasm"
   class "immediate"
+  notify-chain #true
 }
 ```
 
@@ -101,20 +102,22 @@ Grammar:
 profile <non-empty-scheme> {        # exactly one positional value; no properties
   wasm <non-empty-path>              # exactly once
   class immediate|coalesced|silent  # zero or one; default coalesced
+  notify-chain <boolean>             # zero or one; default false
 }
 ```
 
 The profile scheme follows RFC 3986: it begins with an ASCII letter, then
 accepts ASCII alphanumeric characters plus `+`, `-`, and `.`, and rejects `/`;
 lookup remains exact and case-sensitive. The profile
-node takes exactly one quoted positional scheme and no properties. Each child
-takes exactly one quoted positional value. Unknown or extra entries, unknown
-children, duplicate `wasm`, duplicate `class`, a missing `wasm`, unsupported
-class values, and duplicate profile schemes fail parsing. A literal absolute
-module path remains an external runtime input. Every other declaration expands
-`$CATALOG` and environment variables, resolves lexically against the catalog
-root, and must remain strictly beneath that root; internal `.`/`..` components
-normalize away, while traversal outside the root fails validation.
+node takes exactly one quoted positional scheme and no properties. `wasm` and
+`class` each take one quoted positional value; `notify-chain` takes one boolean.
+Unknown or extra entries, unknown children, duplicate children, a missing
+`wasm`, unsupported class values, and duplicate profile schemes fail parsing.
+A literal absolute module path remains an external runtime input. Every other
+declaration expands `$CATALOG` and environment variables, resolves lexically
+against the catalog root, and must remain strictly beneath that root; internal
+`.`/`..` components normalize away, while traversal outside the root fails
+validation.
 
 `st2 validate` reports malformed declarations and missing or unsafe
 catalog-relative modules. `st2 up` loads declared profiles before it spawns
@@ -271,7 +274,7 @@ feature. Default binaries therefore retain the baseline dependency surface.
 Building a Rust guest for `wasm32-unknown-unknown` requires `lld`, which the
 repository dev shell supplies.
 
-## Resync composition (PROFILE-R08..R09)
+## Resync composition (PROFILE-R08..R09, PROFILE-R11)
 
 For each active Resource binding, resync applies this precedence:
 
@@ -288,6 +291,17 @@ After a path enters the watch set, Resource Profiles add no event semantics.
 Parent-directory observation, rename replacement, digest seeding, equal-byte
 deduplication, deterministic transition identity, bounded windows, and built-in
 `resync` delivery remain the [`06-resync`](../06-resync/spec.md) pipeline.
+
+`notify-chain #true` extends only subscription selection. For each active
+binding through that profile, resync validates the bound agent's supervisor
+chain against the complete catalog and adds every active same-scheme carrier
+declared by non-retired ancestors. Each ancestor URI is resolved unchanged
+against that ancestor's own directory and remains inside that directory's host
+containment root. Retired ancestors are skipped without severing traversal.
+Owner-qualified event keys keep layers independent. An invalid chain or failed
+ancestor resolution produces a reconcile warning; st2 never synthesizes a URI
+or silently claims complete chain coverage. The default `false` preserves the
+agent-local behavior above.
 Profile resolution is observation metadata only and never enters task launch
 targets.
 

src/resync.rs

@@ -584,9 +584,15 @@ impl ResyncSupervisor {
     /// Synchronously install one newly proven-live canonical seat before reconciliation advances
     /// to another launch target. The acknowledgement closes the gap between a successful spawn and
     /// the worker's silent baseline seed; later full refreshes still own removals and malformed
-    /// declaration retention. Profile resolution uses the supervisor's current registry and
-    /// returns contained resolver failures for the reconcile report.
-    pub fn install_live(&self, spec: &AgentSpec, this_host: &str) -> Vec<String> {
+    /// declaration retention. Profile and supervisor-chain resolution use the supervisor's current
+    /// registry and the pass's complete catalog view, and return contained resolver failures for the
+    /// reconcile report.
+    pub fn install_live(
+        &self,
+        spec: &AgentSpec,
+        specs: &[AgentSpec],
+        this_host: &str,
+    ) -> Vec<String> {
         if spec.resolved_host(this_host) != this_host || !spec.desired_state.is_running() {
             return Vec::new();
         }
@@ -595,15 +601,7 @@ impl ResyncSupervisor {
                 .profiles
                 .lock()
                 .unwrap_or_else(std::sync::PoisonError::into_inner);
-            // Only this spec is in hand, so a `notify-chain` binding resolves no ancestor
-            // carriers here; the next full refresh adds them. Those subscriptions seed silently,
-            // so an ancestor carrier change inside that window is not announced at all.
-            resolve_watch_set(
-                spec,
-                std::slice::from_ref(spec),
-                this_host,
-                &profiles.begin_refresh(),
-            )
+            resolve_watch_set(spec, specs, this_host, &profiles.begin_refresh())
         };
         let (ack_tx, ack_rx) = channel();
         if self