Scope strict validation to the run host

Author: myobie

README.md

@@ -117,10 +117,15 @@ Gate the declaration before starting anything:
 
 ```sh
 st2 hooks verify
-st2 validate --catalog "$CATALOG"
+st2 validate --catalog "$CATALOG" --strict
 st2 up --catalog "$CATALOG" --host <host> --materialize-only
 ```
 
+Validation always checks the whole synced catalog structurally. External workspace and task-path
+presence is checked only for the selected run host, which defaults to the local short hostname; use
+`--host <host>` to validate another machine's local paths. Supervisors may be declared as either a
+bare identity or the fully-qualified `<host>.<identity>` bus id.
+
 Materialization simulates all content operations before writing. It refuses any real change to a
 Git-tracked target, including `AGENTS.md`; byte-identical tracked content is accepted. Inspect the
 declared targets and keep generated overlays untracked. Detection invokes `git` and fails closed if

src/main.rs

@@ -217,6 +217,10 @@ enum Command {
         /// st2 catalog.
         #[arg(conflicts_with = "catalog_path")]
         root: Option<PathBuf>,
+        /// Host whose external workspace/task paths should be checked. Structural checks always
+        /// cover the whole catalog. Defaults to the local hostname.
+        #[arg(long)]
+        host: Option<String>,
         /// Fail (non-zero exit) on warnings too, not just errors.
         #[arg(long)]
         strict: bool,
@@ -564,9 +568,14 @@ fn main() -> Result<()> {
         }
         Command::Pretrust { dirs } => pretrust_cmd(&dirs),
         Command::Eval { folder, host, keep } => eval_cmd(&folder, host, keep),
-        Command::Validate { root, strict, json } => {
+        Command::Validate {
+            root,
+            host,
+            strict,
+            json,
+        } => {
             let root = catalog_arg(root)?;
-            validate_cmd(&root, strict, json)
+            validate_cmd(&root, host, strict, json)
         }
         Command::Pty { args } => pty_cmd(&args),
         Command::Shell { args } => shell_cmd(&args),
@@ -721,9 +730,10 @@ fn eval_cmd(folder: &Path, host: Option<String>, keep: bool) -> Result<()> {
     }
 }
 
-fn validate_cmd(root: &Path, strict: bool, json: bool) -> Result<()> {
+fn validate_cmd(root: &Path, host: Option<String>, strict: bool, json: bool) -> Result<()> {
     let catalog_root = root.canonicalize().unwrap_or_else(|_| root.to_path_buf());
-    let report = st2::validate::validate(&catalog_root);
+    let host = host.unwrap_or_else(detect_host);
+    let report = st2::validate::validate_for_host(&catalog_root, &host);
     let (errors, warnings) = (report.errors(), report.warnings());
 
     if json {

src/spec.rs

@@ -30,7 +30,7 @@ pub struct AgentSpec {
     pub job_type: JobType,
     /// The repo/worktree; **defaults each task's cwd** (spec.md §2).
     pub workspace: Option<String>,
-    /// Identity of this agent's supervisor — crash-dings/escalations route here.
+    /// Bare identity or `<host>.<identity>` of this agent's supervisor — crash-dings route here.
     pub supervisor: Option<String>,
     /// `true` decommissions the agent (an edit, never a file delete) → torn down by reconcile.
     pub retired: bool,

src/validate.rs

@@ -7,10 +7,9 @@
 //!   relative path, or a missing **catalog-rooted** path — the renderer's own output). Exits non-zero.
 //! - **WARN** — advisory; the run still works (identity/host path↔content mismatch — the spec says a
 //!   mismatch is a warning; a dangling supervisor — crash-dings just route nowhere; a missing
-//!   **external** path such as the workspace repo — the validate host may not be the run host; an
-//!   overlay `@import` that does not resolve — a *render* concern, not st2 law, since a valid spec
-//!   may carry no persona). `--strict` promotes every WARN to a failure so a renderer's CI can demand
-//!   spotless.
+//!   **external** path for an agent assigned to the selected validation host; an overlay `@import`
+//!   that does not resolve — a *render* concern, not st2 law, since a valid spec may carry no
+//!   persona). `--strict` promotes every WARN to a failure so a renderer's CI can demand spotless.
 //!
 //! st2 stays render-agnostic: render-only fields (`harness`, `model`, `role`, `persona`,
 //! `permissions`, …) are never required — their absence is never an issue.
@@ -103,6 +102,18 @@ impl Report {
 
 /// Validate a catalog. Returns every issue found, in a stable order (files sorted by discovery).
 pub fn validate(root: &Path) -> Report {
+    validate_scoped(root, None)
+}
+
+/// Validate a whole catalog while checking host-local filesystem facts only for `this_host`.
+///
+/// Structural checks remain fleet-wide. This scope only prevents a synced multi-host catalog from
+/// warning that another machine's external workspace or task cwd is absent locally.
+pub fn validate_for_host(root: &Path, this_host: &str) -> Report {
+    validate_scoped(root, Some(this_host))
+}
+
+fn validate_scoped(root: &Path, this_host: Option<&str>) -> Report {
     // Canonicalize so `$CATALOG`-rooted paths expand to absolute paths (a relative root would make
     // every `$CATALOG/...` look relative). Falls back to the given root if it does not exist yet.
     let root = &root.canonicalize().unwrap_or_else(|_| root.to_path_buf());
@@ -155,14 +166,29 @@ pub fn validate(root: &Path) -> Report {
     let mut seen: HashMap<String, PathBuf> = HashMap::new();
     // Placeholder host for bus-id collision: catalogs carry explicit host, and an empty host still
     // makes two unset-host same-identity specs collide (which is the real bug).
-    let this_host = "";
+    let collision_host = "";
+    let addresses: HashSet<String> = d
+        .specs
+        .iter()
+        .flat_map(|s| {
+            let mut values = vec![s.identity.clone()];
+            if s.host.is_some() {
+                values.push(s.bus_id(collision_host));
+            }
+            values
+        })
+        .collect();
 
     for s in &d.specs {
         let rp = rel(root, &s.path);
         let ag = Some(s.identity.clone());
+        let runs_on_selected_host = match this_host {
+            Some(host) => s.resolved_host(host) == host,
+            None => true,
+        };
 
         // Duplicate bus id — the runner cannot run two agents under one <host>.<identity>.
-        let bid = s.bus_id(this_host);
+        let bid = s.bus_id(collision_host);
         if let Some(prev) = seen.insert(bid.clone(), s.path.clone()) {
             issues.push(Issue::error(
                 "dup-id",
@@ -216,14 +242,16 @@ pub fn validate(root: &Path) -> Report {
 
         // Path fields must be absolute or $CATALOG-rooted, and must exist.
         for (field, raw) in path_fields(s) {
-            if let Some(issue) = check_path(root, &rp, &ag, &field, &raw) {
+            if let Some(issue) = check_path(root, &rp, &ag, &field, &raw, runs_on_selected_host) {
                 issues.push(issue);
             }
         }
 
-        // A supervisor that names no agent in this catalog — advisory (may live elsewhere).
+        // Runtime routing accepts either a bare identity or a fully-qualified <host>.<identity>.
+        // Validation must index the same address set or it rejects declarations the bus can route.
         if let Some(sup) = &s.supervisor
             && !identities.contains(sup.as_str())
+            && !addresses.contains(sup)
         {
             issues.push(Issue::warn(
                 "dangling-supervisor",
@@ -234,7 +262,9 @@ pub fn validate(root: &Path) -> Report {
         }
 
         // Overlay lint: render's persona overlay `@import`s must resolve (WARN — render concern).
-        issues.extend(overlay_lint(&rp, &ag, s));
+        if runs_on_selected_host {
+            issues.extend(overlay_lint(&rp, &ag, s));
+        }
 
         // Declarative render is a pre-boot gate: malformed directives, unsafe destinations, or a
         // missing catalog-owned copy source would prevent this agent from booting.
@@ -273,8 +303,16 @@ fn path_fields(s: &AgentSpec) -> Vec<(String, String)> {
 
 /// Check one path field: `$CATALOG` expands to the catalog root; a path bearing any *other* `$VAR` is
 /// skipped (an unset var is a literal token — do not guess). What remains must be absolute (R11:
-/// final-spec paths are absolute or $CATALOG-rooted, never relative) and must exist.
-fn check_path(root: &Path, rp: &str, ag: &Option<String>, field: &str, raw: &str) -> Option<Issue> {
+/// final-spec paths are absolute or $CATALOG-rooted, never relative). Catalog-owned paths must
+/// always exist; external paths are checked only for an agent assigned to the selected host.
+fn check_path(
+    root: &Path,
+    rp: &str,
+    ag: &Option<String>,
+    field: &str,
+    raw: &str,
+    check_external_presence: bool,
+) -> Option<Issue> {
     let root_s = root.to_string_lossy();
     let expanded = raw
         .replace("${CATALOG}", &root_s)
@@ -295,24 +333,25 @@ fn check_path(root: &Path, rp: &str, ag: &Option<String>, field: &str, raw: &str
     }
     if !p.exists() {
         // A **catalog-rooted** path is the renderer's own output — its absence is a real render bug
-        // (ERROR). An **external** absolute path (e.g. the workspace repo) may simply not be present
-        // on the host running `validate` — a nix build gate legitimately validates a catalog whose
-        // workspace is cloned on a different run host — so that is advisory (WARN), not a failure.
-        return Some(if p.starts_with(root) {
-            Issue::error(
+        // (ERROR). An **external** absolute path is checked only for the selected run host; its
+        // absence there is advisory (WARN), not a structural catalog failure.
+        return if p.starts_with(root) {
+            Some(Issue::error(
                 "bad-path",
                 rp.to_string(),
                 ag.clone(),
                 format!("{field} '{raw}' does not exist"),
-            )
-        } else {
-            Issue::warn(
+            ))
+        } else if check_external_presence {
+            Some(Issue::warn(
                 "bad-path",
                 rp.to_string(),
                 ag.clone(),
                 format!("{field} '{raw}' does not exist (absent on this host? — not the run host)"),
-            )
-        });
+            ))
+        } else {
+            None
+        };
     }
     None
 }

tests/validate.rs

@@ -2,7 +2,7 @@
 //! it hit the spec. Each test builds a minimal catalog exercising one failure mode and asserts the
 //! exact issue code + severity; a clean catalog (and our shipped `examples/`) must validate spotless.
 
-use st2::validate::{Report, Severity, validate};
+use st2::validate::{Report, Severity, validate, validate_for_host};
 
 /// Write a set of `(relative-path, body)` files into a fresh temp catalog.
 fn catalog(files: &[(&str, &str)]) -> tempfile::TempDir {
@@ -121,6 +121,22 @@ fn a_missing_external_path_is_only_a_warning() {
     );
 }
 
+#[test]
+fn a_remote_hosts_missing_external_path_is_not_a_local_warning() {
+    let c = catalog(&[(
+        "hetz/w/agent.kdl",
+        r#"agent "w" { host "hetz"; type "service"; workspace "/no/such/dir/xyz123"; pty "agent" { command "x" } }"#,
+    )]);
+    let r = validate_for_host(c.path(), "Silber");
+    assert_eq!(r.errors(), 0, "unexpected errors: {:?}", r.issues);
+    assert_eq!(
+        r.warnings(),
+        0,
+        "remote-host filesystem facts must not dirty local strict validation: {:?}",
+        r.issues
+    );
+}
+
 #[test]
 fn a_path_bearing_another_var_is_skipped() {
     // SD3: an unset var is a literal token — do not guess, do not flag.
@@ -238,6 +254,28 @@ fn a_dangling_supervisor_is_a_warning() {
     );
 }
 
+#[test]
+fn a_fully_qualified_supervisor_in_the_catalog_is_clean() {
+    let c = catalog(&[
+        (
+            "Silber/cos/agent.kdl",
+            r#"agent "cos" { host "Silber"; command "x" }"#,
+        ),
+        (
+            "hetz/w/agent.kdl",
+            r#"agent "w" { host "hetz"; supervisor "Silber.cos"; command "x" }"#,
+        ),
+    ]);
+    let r = validate(c.path());
+    assert_eq!(r.errors(), 0, "unexpected errors: {:?}", r.issues);
+    assert_eq!(
+        r.warnings(),
+        0,
+        "runtime-routable qualified supervisors must validate: {:?}",
+        r.issues
+    );
+}
+
 #[test]
 fn an_identity_folder_mismatch_is_a_warning() {
     let c = catalog(&[(
@@ -300,6 +338,26 @@ fn cli_exits_zero_on_a_clean_catalog() {
     );
 }
 
+#[test]
+fn cli_host_scope_keeps_remote_paths_out_of_strict_validation() {
+    let c = catalog(&[(
+        "hetz/w/agent.kdl",
+        r#"agent "w" { host "hetz"; workspace "/no/such/dir/xyz123"; command "x" }"#,
+    )]);
+    let out = run_validate(&[
+        c.path().as_os_str(),
+        std::ffi::OsStr::new("--host"),
+        std::ffi::OsStr::new("Silber"),
+        std::ffi::OsStr::new("--strict"),
+    ]);
+    assert!(
+        out.status.success(),
+        "stdout:\n{}\nstderr:\n{}",
+        String::from_utf8_lossy(&out.stdout),
+        String::from_utf8_lossy(&out.stderr)
+    );
+}
+
 #[test]
 fn cli_exits_nonzero_on_an_error_and_strict_promotes_warnings() {
     // An error catalog exits non-zero without --strict.