feat: complete targeted reconcile CLI

Author: myobie

README.md

@@ -160,6 +160,15 @@ st2 up --catalog "$CATALOG" --host <host> --once
 
 There is intentionally no resident macOS service path.
 
+For a shortest-path change to one exact task, render only its owning agent and reconcile only that
+task in a bounded pass:
+
+```sh
+st2 up --catalog "$CATALOG" --host <host> --once --task <host.agent.task>
+```
+
+Unknown, ambiguous, and wrong-host task selectors refuse before workspace writes or PTY inspection.
+
 `st2 doctor` accepts the absence of a live host lock as the normal manual/`--once` mode. For a
 resident `st2 up` deployment, use `st2 doctor --require-supervisor` to make a missing loop fail the
 health check. A stale lock left by a dead supervisor is always a failure. The underlying

docs/vrs/spec.md

@@ -117,14 +117,21 @@ positive declaration/template wakes, negative runtime/bus events, bounded
 discovery/materialization/PTY queries and writes, continuous-event starvation,
 and no-op desired-equals-actual behavior.
 
-## Open design questions
+## Targeted reconciliation (R19)
+
+`st2 up --materialize-only --task <host.agent.task>` resolves one exact local
+task before writing and renders only its owning agent. `st2 up --once --task
+<host.agent.task>` performs the same owner-only materialization, then inspects
+PTY/exec state and executes a plan containing only that task. Unknown,
+ambiguous, and wrong-host selectors refuse before writes or runner inspection;
+unrelated discovery diagnostics remain visible without preventing the selected
+owner/task path.
 
-### Targeted materialization (R13)
+`st2 up --materialize-only --agent <id>` remains the agent-wide rendering
+selector. Targeted task reconciliation is intentionally bounded to `--once`;
+the resident supervisor continues to reconcile the complete local catalog.
 
-`st2 up --materialize-only --agent <id>` filters discovery before rendering,
-so a declared agent/task change cannot be blocked by unrelated slow or
-unreadable workspaces. This selector is materialization-only; live
-reconciliation remains separately gated and host-local.
+## Open design questions
 
 - **DQ1 Scheduled work:** The vision includes per-machine schedulers that form a
   distributed workflow engine, but the KDL shape, event inbox, deduplication

src/lib.rs

@@ -39,6 +39,6 @@ pub use host_lock::HostLock;
 pub use reconcile::{Launch, ReconcilePlan, Session, TaskTarget, Teardown, reconcile};
 pub use run::{
     PtyCli, Runner, SystemRunner, UpReport, detect_host, down, down_specs, exec_state_dir, execute,
-    up_loop, up_loop_specs, up_once, up_once_specs,
+    up_loop, up_loop_specs, up_once, up_once_selected, up_once_selected_specs, up_once_specs,
 };
 pub use spec::{AgentSpec, JobType, Restart, RestartMode, Task, TaskKind, parse_duration};

src/main.rs

@@ -53,9 +53,11 @@ enum Command {
         /// Materialize every local agent's render block and exit without reconciling or spawning.
         #[arg(long, conflicts_with = "once")]
         materialize_only: bool,
-        /// Limit materialization/reconciliation to one declared agent identity.
+        /// Limit materialization to one declared agent identity.
         #[arg(long)]
         agent: Option<String>,
+        /// Select one exact local task. Use with --materialize-only to render only its owner, or
+        /// with --once to render its owner and reconcile only that task.
         #[arg(long, conflicts_with = "agent")]
         task: Option<String>,
         /// Seconds between timer-driven reconcile passes when looping (folder changes reconcile
@@ -534,11 +536,8 @@ fn main() -> Result<()> {
             task,
         } => {
             let root = catalog_arg(root)?;
-            if task.is_some() && once {
-                anyhow::bail!("--task --once is deferred until selected reconcile support");
-            }
-            if task.is_some() && !materialize_only {
-                anyhow::bail!("--task requires --materialize-only in this stage");
+            if task.is_some() && !materialize_only && !once {
+                anyhow::bail!("--task requires --once or --materialize-only");
             }
             if agent.is_some() && !materialize_only {
                 anyhow::bail!("--agent requires --materialize-only");
@@ -1751,6 +1750,9 @@ fn up(
     // An st2-SPEC path (a `*.kdl` file, or a folder with one top-level spec `*.kdl`) supervises its
     // top-level team directly — no catalog discovery. Otherwise, the classic catalog reconcile loop.
     if let Some(spec_file) = st2::eval_run::resolve_spec_path(root) {
+        if task.is_some() {
+            anyhow::bail!("--task is for folder catalogs, not single-file specs");
+        }
         if materialize_only {
             anyhow::bail!(
                 "--materialize-only is for folder catalogs with agent render{{}} blocks, not single-file specs"
@@ -1811,7 +1813,7 @@ fn up(
         return Ok(());
     }
 
-    let runner = SystemRunner::new(catalog_root, exec_state_dir(&this_host));
+    let runner = SystemRunner::new(catalog_root.clone(), exec_state_dir(&this_host));
 
     // One supervisor per (folder, host). A single `--once` pass must also refuse while a loop owns
     // the lock (it would double-spawn) — but it does NOT take the lock itself (that would clobber the
@@ -1823,12 +1825,21 @@ fn up(
     }
 
     if once {
-        let report = up_once(root, &this_host, &runner)?;
+        let targeted = task.is_some();
+        let report = match task.as_deref() {
+            Some(selector) => {
+                st2::run::up_once_selected(&catalog_root, selector, &this_host, &runner)?
+            }
+            None => up_once(root, &this_host, &runner)?,
+        };
         println!("reconcile pass on host '{this_host}':");
         print_report(&report);
         if report.skipped {
             anyhow::bail!("one-shot reconcile pass was skipped");
         }
+        if targeted && !report.errors.is_empty() {
+            anyhow::bail!("targeted one-shot reconcile pass reported errors");
+        }
         return Ok(());
     }
 

tests/exec_backend.rs

@@ -2,7 +2,6 @@
 
 use std::collections::BTreeMap;
 use std::fs;
-use std::process::Command;
 use std::thread::sleep;
 use std::time::Duration;
 

tests/materialize.rs

@@ -159,14 +159,6 @@ fn task_selector_cli_modes_fail_closed() {
             "--task",
             "host.a.x",
         ],
-        vec![
-            "up",
-            "--catalog",
-            tmp.path().to_str().unwrap(),
-            "--once",
-            "--task",
-            "host.a.x",
-        ],
         vec![
             "up",
             "--catalog",

tests/nomad_survival.rs

@@ -191,7 +191,10 @@ impl Fixture {
         let bin_dir = self.xdg.join("bin");
         std::fs::create_dir_all(&bin_dir).unwrap();
         let installed = bin_dir.join("st2");
-        std::fs::copy(env!("CARGO_BIN_EXE_st2"), &installed).unwrap();
+        let staged = installed.with_extension("installing");
+        std::fs::copy(env!("CARGO_BIN_EXE_st2"), &staged).unwrap();
+        std::fs::File::open(&staged).unwrap().sync_all().unwrap();
+        std::fs::rename(&staged, &installed).unwrap();
         installed
     }
 
@@ -216,14 +219,27 @@ impl Fixture {
     }
 
     fn spawn_loop_from(&self, binary: &Path) -> Child {
-        self.st2_from(binary)
-            .arg("up")
-            .arg(&self.catalog)
-            .args(["--host", HOST, "--interval", "60"])
-            .stdout(Stdio::null())
-            .stderr(Stdio::null())
-            .spawn()
-            .unwrap()
+        for attempt in 0..5 {
+            let result = self
+                .st2_from(binary)
+                .arg("up")
+                .arg(&self.catalog)
+                .args(["--host", HOST, "--interval", "60"])
+                .stdout(Stdio::null())
+                .stderr(Stdio::null())
+                .spawn();
+            match result {
+                Ok(child) => return child,
+                Err(error) if error.raw_os_error() == Some(libc::ETXTBSY) && attempt + 1 < 5 => {
+                    // Some Linux filesystems briefly retain the writer exclusion after installing
+                    // a copied executable. Retry only that transient; every other spawn error stays
+                    // loud and immediate.
+                    std::thread::sleep(Duration::from_millis(20));
+                }
+                Err(error) => panic!("spawning fixture control plane failed: {error}"),
+            }
+        }
+        unreachable!("the bounded spawn loop always returns or panics")
     }
 
     /// One `st2 up --once` pass; returns its stdout (where launched/adopted/torn-down is reported).

tests/run.rs

@@ -8,9 +8,198 @@ use std::path::Path;
 use st2::message;
 use st2::reconcile::{Session, TaskTarget};
 use st2::run::Runner;
-use st2::run::{CrashLoop, surface_crash_loop, up_once_selected_specs};
+use st2::run::{CrashLoop, surface_crash_loop, up_once_selected, up_once_selected_specs};
 use st2::spec::{AgentSpec, JobType, Task, TaskKind};
 
+fn selected_catalog_agent(identity: &str, workspace: &Path, render: &str) -> String {
+    format!(
+        r#"agent "{identity}" {{
+  host "host"
+  type "service"
+  workspace "{}"
+  pty "work" {{
+    id "host.{identity}.work"
+    command "true"
+  }}
+  render {{
+    {render}
+  }}
+}}
+"#,
+        workspace.display()
+    )
+}
+
+fn write_selected_catalog(
+    catalog: &Path,
+    owner_workspace: &Path,
+    sibling_workspace: &Path,
+    owner_render: &str,
+) {
+    fs::create_dir_all(owner_workspace).unwrap();
+    fs::create_dir_all(sibling_workspace).unwrap();
+    write(
+        catalog,
+        "agents/host/owner/agent.kdl",
+        &selected_catalog_agent("owner", owner_workspace, owner_render),
+    );
+    write(
+        catalog,
+        "agents/host/sibling/agent.kdl",
+        &selected_catalog_agent(
+            "sibling",
+            sibling_workspace,
+            r#"file "SIBLING.txt" "sibling""#,
+        ),
+    );
+}
+
+#[test]
+fn selected_catalog_two_agent_kdl_recording_runner_matrix() {
+    enum Actual {
+        Missing,
+        Live,
+        Dead,
+    }
+
+    for actual in [Actual::Missing, Actual::Live, Actual::Dead] {
+        let tmp = tempfile::tempdir().unwrap();
+        let catalog = tmp.path().join("catalog");
+        let owner_workspace = tmp.path().join("owner-workspace");
+        let sibling_workspace = tmp.path().join("sibling-workspace");
+        write_selected_catalog(
+            &catalog,
+            &owner_workspace,
+            &sibling_workspace,
+            r#"file "OWNER.txt" "owner""#,
+        );
+
+        let mut sessions = vec![live("host.sibling.work")];
+        match actual {
+            Actual::Missing => {}
+            Actual::Live => sessions.push(live("host.owner.work")),
+            Actual::Dead => sessions.push(dead("host.owner.work")),
+        }
+        let runner = FakeRunner {
+            sessions,
+            ..Default::default()
+        };
+
+        let report = up_once_selected(&catalog, "host.owner.work", "host", &runner).unwrap();
+
+        assert_eq!(runner.list_calls.get(), 1);
+        assert_eq!(
+            fs::read_to_string(owner_workspace.join("OWNER.txt")).unwrap(),
+            "owner"
+        );
+        assert!(
+            !sibling_workspace.join("SIBLING.txt").exists(),
+            "the unrelated owner must not be materialized"
+        );
+        assert!(runner.killed.borrow().is_empty());
+        assert!(runner.removed.borrow().is_empty());
+        match actual {
+            Actual::Missing => {
+                assert_eq!(runner.spawned.borrow().as_slice(), ["host.owner.work"]);
+                assert!(runner.reaped.borrow().is_empty());
+                assert_eq!(report.launched, ["host.owner.work"]);
+            }
+            Actual::Live => {
+                assert!(runner.spawned.borrow().is_empty());
+                assert!(runner.reaped.borrow().is_empty());
+                assert_eq!(report.adopted, ["owner"]);
+            }
+            Actual::Dead => {
+                assert_eq!(runner.reaped.borrow().as_slice(), ["host.owner.work"]);
+                assert_eq!(runner.spawned.borrow().as_slice(), ["host.owner.work"]);
+                assert_eq!(report.gc, ["host.owner.work"]);
+                assert_eq!(report.launched, ["host.owner.work"]);
+            }
+        }
+        assert!(
+            runner
+                .spawned
+                .borrow()
+                .iter()
+                .chain(runner.reaped.borrow().iter())
+                .all(|id| id == "host.owner.work")
+        );
+    }
+}
+
+#[test]
+fn selected_catalog_surfaces_unrelated_malformed_diagnostics_without_blocking_owner() {
+    let tmp = tempfile::tempdir().unwrap();
+    let catalog = tmp.path().join("catalog");
+    let owner_workspace = tmp.path().join("owner-workspace");
+    let sibling_workspace = tmp.path().join("sibling-workspace");
+    write_selected_catalog(
+        &catalog,
+        &owner_workspace,
+        &sibling_workspace,
+        r#"file "OWNER.txt" "owner""#,
+    );
+    write(
+        &catalog,
+        "agents/host/sibling/broken.kdl",
+        r#"agent "broken" {"#,
+    );
+    let runner = FakeRunner {
+        sessions: vec![live("host.sibling.work")],
+        ..Default::default()
+    };
+
+    let report = up_once_selected(&catalog, "host.owner.work", "host", &runner).unwrap();
+
+    assert_eq!(runner.spawned.borrow().as_slice(), ["host.owner.work"]);
+    assert_eq!(
+        fs::read_to_string(owner_workspace.join("OWNER.txt")).unwrap(),
+        "owner"
+    );
+    assert!(!sibling_workspace.join("SIBLING.txt").exists());
+    assert!(
+        report
+            .errors
+            .iter()
+            .any(|error| error.contains("broken.kdl") && error.contains("KDL")),
+        "{:?}",
+        report.errors
+    );
+}
+
+#[test]
+fn selected_catalog_owner_render_failure_refuses_runner_actions() {
+    let tmp = tempfile::tempdir().unwrap();
+    let catalog = tmp.path().join("catalog");
+    let owner_workspace = tmp.path().join("owner-workspace");
+    let sibling_workspace = tmp.path().join("sibling-workspace");
+    write_selected_catalog(
+        &catalog,
+        &owner_workspace,
+        &sibling_workspace,
+        r#"copy "_templates/missing" "OWNER.txt""#,
+    );
+    let runner = FakeRunner {
+        sessions: vec![live("host.sibling.work")],
+        ..Default::default()
+    };
+
+    let report = up_once_selected(&catalog, "host.owner.work", "host", &runner).unwrap();
+
+    assert_eq!(runner.list_calls.get(), 0);
+    assert_refusal(&runner);
+    assert!(!owner_workspace.join("OWNER.txt").exists());
+    assert!(!sibling_workspace.join("SIBLING.txt").exists());
+    assert!(
+        report
+            .errors
+            .iter()
+            .any(|error| error.contains("_templates/missing")),
+        "{:?}",
+        report.errors
+    );
+}
+
 #[test]
 fn selected_one_shot_unknown_refuses_before_runner_list() {
     let runner = FakeRunner::default();