fix(down): teardown names its catalog instead of inferring one

`st2 down` with no target resolved the shared catalog selection — `$CATALOG`,
else `${XDG_STATE_HOME:-$HOME/.local/state}/st2/default/catalog` — then
discovered every spec under it and killed every live task.

Inheriting a catalog is right for the read-only verbs, and for `up`: it is
additive, and it refuses to start at all while another supervisor holds the host
lock. `down` is the only thing that ends tasks, which is what makes explicit
teardown a lifecycle guarantee (R11) rather than a habit, and it holds no lock,
has no dry-run, and cannot be undone.

Neither inherited source is a choice made at the call site. `PtyCli` exports
`CATALOG` into every task st2 launches, so inside a seat the ambient value names
that seat's own fleet; and the standard default is derived from `$HOME`, so it
can never be absent. Between them, a forgotten argument always resolves to some
live fleet instead of failing — the same defect class as a `PTY_ROOT` that has
to be exported into every reader.

So teardown now takes its target from argv alone and otherwise refuses, printing
the catalog it would have used and the explicit command to run. The refusal is
in argv rather than a prompt because the callers that most need it — managed
tasks and scripts — have no tty to confirm on. Every invocation in the README
and the test suite already names its target, so none of them change.

Author: schickling

README.md

@@ -40,7 +40,8 @@ ${XDG_STATE_HOME:-$HOME/.local/state}/st2/default/catalog
 ```
 
 Every catalog-aware command accepts `--catalog`; otherwise st2 uses `$CATALOG`, then that standard
-location.
+location. `st2 down` is the exception: teardown is the only thing that ends tasks, so it takes its
+target from `--catalog` or a path argument and refuses to infer one.
 
 ### A catalog may declare its session registry
 
@@ -283,12 +284,18 @@ the correctness fallback.
 
 ## Cleanup
 
-Explicit teardown is the only operation that ends declared tasks:
+Explicit teardown is the only operation that ends declared tasks, and it never infers which catalog
+to end:
 
 ```sh
 st2 down --catalog "$CATALOG" --host <host>
 ```
 
+Without `--catalog` or a path argument, `st2 down` refuses and prints the catalog it would have used.
+`$CATALOG` is set inside every managed task, and the standard default is derived from `$HOME`, so an
+inferred target would always exist — a forgotten argument would read as "tear down this host's
+fleet".
+
 On Linux, remove the supervisor service after teardown when it is no longer wanted:
 
 ```sh

docs/vrs/spec.md

@@ -59,6 +59,12 @@ validate ──► materialize ──► host-local st2 scheduler/reconciler
   binary, starts the control plane again, and proves adoption with the same
   agent PID/creation identity and no duplicate process.
 
+  Teardown, the one action that ends tasks, resolves its catalog from the
+  command line alone. Every other verb may inherit `$CATALOG` or fall back to
+  the standard catalog; both are ambient — st2 exports `CATALOG` into every task
+  it launches, and the standard default is derived from `$HOME` — so an inferred
+  teardown target always exists and a missing argument would end a live fleet.
+
 - **Session registry:** A catalog owns the `pty` registry holding its tasks.
   `<catalog>/pty` is the default; a catalog may declare another so that one host
   can share a single registry across catalogs. Resolution is an exported

src/main.rs

@@ -148,10 +148,11 @@ enum Command {
         extra_arg: Vec<String>,
     },
     /// Explicit teardown: kill every live task of this host's catalog agents. The ONLY thing that ends
-    /// tasks (stopping/crashing st2 never does). Idempotent.
+    /// tasks (stopping/crashing st2 never does). Idempotent. Its target must be named — unlike every
+    /// other verb, it does not fall back to $CATALOG or the standard catalog.
     Down {
-        /// Optional positional catalog/spec path. Prefer --catalog; defaults to $CATALOG, then the
-        /// standard st2 catalog.
+        /// Positional catalog/spec path to tear down. Required unless --catalog is passed; teardown
+        /// never infers its target from $CATALOG or the standard st2 catalog.
         #[arg(conflicts_with = "catalog_path")]
         root: Option<PathBuf>,
         /// Host to tear down. Defaults to the local hostname.
@@ -562,7 +563,7 @@ fn main() -> Result<()> {
             )
         }
         Command::Down { root, host } => {
-            let root = catalog_arg(root)?;
+            let root = down_target(root, catalog_path.as_deref())?;
             down_cmd(&root, host)
         }
         Command::Env { root } => {
@@ -828,6 +829,32 @@ fn initialize_catalog_env(explicit: Option<&Path>) -> Result<()> {
     Ok(())
 }
 
+/// Teardown resolves its target from argv alone — `--catalog <path>` or the positional path — and
+/// never from `$CATALOG` or the standard default.
+///
+/// Inheriting a catalog is right for the read-only verbs, and for `up`, which is additive and refuses
+/// to start while another supervisor holds the host lock. `st2 down` is the only thing that ends
+/// tasks, which is what makes "explicit teardown" a lifecycle guarantee (R11) rather than a habit —
+/// and neither inherited source is a choice the operator made *here*: st2 exports `CATALOG` into
+/// every task it launches, and the standard default is derived from `$HOME`, so it can never be
+/// absent. Inferring one would make a forgotten argument indistinguishable from "tear down this
+/// host's fleet", with no dry-run, no confirmation, and nothing to undo it.
+fn down_target(positional: Option<PathBuf>, flag: Option<&Path>) -> Result<PathBuf> {
+    // clap makes these mutually exclusive.
+    if let Some(path) = positional.as_deref().or(flag) {
+        return absolute_catalog_path(path);
+    }
+    let inferred = catalog_root_for_env()
+        .map(|root| root.display().to_string())
+        .unwrap_or_else(|_| "<none>".to_string());
+    anyhow::bail!(
+        "refusing to tear down an inferred catalog.\n\
+         `st2 down` is the only thing that ends tasks, so its target is named, never inherited.\n\
+         It would have used {inferred} (from $CATALOG, else the standard default catalog).\n\
+         Name it if that is what you mean:  st2 down --catalog {inferred}"
+    )
+}
+
 /// Resolve an optional legacy positional path, otherwise use the shared catalog selection.
 fn catalog_arg(explicit: Option<PathBuf>) -> Result<PathBuf> {
     match explicit {

tests/catalog_selection.rs

@@ -1,6 +1,8 @@
 //! Shared catalog selection across the CLI: explicit global `--catalog`, inherited `$CATALOG`, then
 //! `${XDG_STATE_HOME:-$HOME/.local/state}/st2/default/catalog`. Legacy positional/`--root` forms
 //! remain covered by the command-specific integration suites.
+//!
+//! `down` is the one deliberate exception: teardown names its target or refuses.
 
 use std::fs;
 use std::path::Path;
@@ -107,6 +109,76 @@ fn global_catalog_flag_overrides_the_environment_from_a_subcommand() {
     assert_eq!(rows[0]["identity"], "h.selected-seat");
 }
 
+/// Teardown is the only verb that ends tasks, so it does not inherit its target from the shared
+/// selection: both fallbacks are ambient (st2 exports `CATALOG` into every task it launches, and the
+/// standard default is derived from `$HOME`), which would make a forgotten argument resolve to a live
+/// fleet instead of failing. Hermetic: `HOME`/`XDG_STATE_HOME` are temp dirs and the bus env vars are
+/// removed, so a regression here kills a temp catalog's (empty) session set, never a real one.
+#[test]
+fn down_refuses_an_inferred_target_but_takes_a_named_one() {
+    let home = tempfile::tempdir().unwrap();
+    let state = tempfile::tempdir().unwrap();
+    let ambient = tempfile::tempdir().unwrap();
+    write_agent(&state.path().join("st2/default/catalog"), "h", "default-seat");
+    write_agent(ambient.path(), "h", "ambient-seat");
+
+    let down = |catalog_env: Option<&Path>, extra: &[&str]| -> Output {
+        let mut cmd = Command::new(env!("CARGO_BIN_EXE_st2"));
+        cmd.args(["down", "--host", "h"])
+            .args(extra)
+            .env("HOME", home.path())
+            .env("XDG_STATE_HOME", state.path())
+            .env_remove("ST_ROOT")
+            .env_remove("PTY_ROOT");
+        match catalog_env {
+            Some(path) => cmd.env("CATALOG", path),
+            None => cmd.env_remove("CATALOG"),
+        };
+        cmd.output().unwrap()
+    };
+
+    // The standard default catalog is not a teardown target…
+    let out = down(None, &[]);
+    let stderr = String::from_utf8_lossy(&out.stderr);
+    assert!(
+        !out.status.success(),
+        "down tore down an inferred catalog:\n{}",
+        String::from_utf8_lossy(&out.stdout)
+    );
+    assert!(
+        stderr.contains("refusing to tear down an inferred catalog"),
+        "no refusal:\n{stderr}"
+    );
+    assert!(
+        stderr.contains(
+            state
+                .path()
+                .join("st2/default/catalog")
+                .to_str()
+                .unwrap()
+        ),
+        "the refusal must name what it would have torn down:\n{stderr}"
+    );
+
+    // …and neither is an inherited `$CATALOG`, which st2 itself exports into every managed task.
+    let out = down(Some(ambient.path()), &[]);
+    let stderr = String::from_utf8_lossy(&out.stderr);
+    assert!(!out.status.success(), "down tore down an inherited $CATALOG");
+    assert!(
+        stderr.contains(ambient.path().to_str().unwrap()),
+        "the refusal must name the inherited catalog:\n{stderr}"
+    );
+
+    // A named target is accepted — from argv, over an inherited $CATALOG pointing elsewhere.
+    let named = tempfile::tempdir().unwrap();
+    let out = down(Some(ambient.path()), &["--catalog", named.path().to_str().unwrap()]);
+    let stderr = String::from_utf8_lossy(&out.stderr);
+    assert!(
+        !stderr.contains("refusing to tear down"),
+        "a named target was refused:\n{stderr}"
+    );
+}
+
 #[test]
 fn compile_agent_can_target_only_the_global_catalog_flag() {
     let tmp = tempfile::tempdir().unwrap();