fix(app): reject apps referencing not-yet-runnable agents (#161) (#164)

* fix(app): reject apps referencing not-yet-runnable agents at validate/compile (#161)

The html-report agent advertised a curated `render` command + an aware-html-report
cli transport, but no such binary ships or is installable — so an app node using it
validated/compiled fine and only failed at run with "program not found".

- New agent-manifest `status: available | planned` (default available). html-report
  is marked `planned` until its binary ships.
- validate_app_agents rejects (E_APP_AGENT_UNAVAILABLE) any node referencing a
  `planned` agent, recursing into for-each `do:` bodies. Wired into `app validate`,
  `compile_to_disk` (so no lock is produced), and the real-run pre-flight.
- `aware agent describe` shows a "planned — not yet runnable" status line so the
  agent no longer looks runnable.

Note: two showcase example apps (bim-monday-audit, engineer-peer-review-delta)
reference html-report and now correctly fail validate — they were never runnable
(html-report has no binary). Tracked as a follow-up to ship html-report or revise
those examples.

* fix(app): enforce planned-agent check on dry-run + install (#161 review)

- The planned-agent pre-flight sat inside the `!dry_run` block, but a plain
  `--dry-run` still dispatches read-mode nodes, so html-report.render fell through
  to the spawn failure this change replaces. The check now runs for plain runs and
  `--dry-run`; only `--simulate` (stubs every node, contacts no binary) skips it.
- `aware app install` ran only validate_app_safety, so an app referencing a planned
  agent could install + lock despite failing validate/compile. Added
  validate_app_agents to the install pre-copy validation. Found by Codex review.

Author: pawellisowski

20-agents/_core/html-report/manifest.yaml

@@ -12,6 +12,12 @@ description: |
 
 stateful: false
 
+# Not yet runnable: the `aware-html-report` transport binary isn't shipped or
+# installable. Apps referencing it are rejected at validate/compile rather than
+# failing at run with "program not found" (#161). Flip to `available` once the
+# binary ships.
+status: planned
+
 vendor:   aware
 license:  Apache-2.0
 homepage: https://github.com/aware-aeco/aware/tree/main/20-agents/_core/html-report

cli/src/app_lock.rs

@@ -532,6 +532,18 @@ pub fn compile_to_disk(source: &Path, paths: &Paths) -> Result<std::path::PathBu
         )));
     }
     let agents = discover_agents(paths)?;
+    // Refuse to lock an app that references a not-yet-runnable agent (e.g.
+    // html-report, whose transport binary isn't shipped) — fail here, not at run
+    // with "program not found" (#161).
+    if let Some(err) = crate::validate::validate_app_agents(&app, &agents)
+        .into_iter()
+        .find(|i| i.severity == crate::validate::Severity::Error)
+    {
+        return Err(AwareError::Validation(format!(
+            "app failed validation: [{}] {}",
+            err.code, err.message
+        )));
+    }
     let lock = compile(&app, &agents, source)?;
     write_lockfile(&lock, source)
 }

cli/src/commands/agent.rs

@@ -479,6 +479,12 @@ fn describe(ctx: &Context, agent_id: &str) -> Result<(), AwareError> {
     if let Some(t) = &m.transport.cli {
         println!("transport:    cli ({})", t.binary);
     }
+    if m.status == crate::manifest::agent::AgentStatus::Planned {
+        println!(
+            "status:       \u{26a0} planned — not yet runnable (no shipped transport binary); \
+             apps referencing it are rejected at validate/compile (#161)"
+        );
+    }
     println!();
     let curated = m.curated_count();
     let reflected = m.reflected_count();

cli/src/commands/app.rs

@@ -174,17 +174,34 @@ async fn run(
     // nodes are missing `safety:` blocks. Skipped in --dry-run (a dry-run
     // is precisely how you'd test an app's safety contract before adding
     // the blocks). See `10-core/app-spec.md § Safety contract`.
-    if !dry_run {
+    // Pre-flight checks need the agent catalogue. `--simulate` stubs every node
+    // and contacts no binary, so it skips both checks; a plain `--dry-run` still
+    // dispatches read-mode nodes, so it gets the planned-agent check.
+    if !simulate {
         let agents = crate::manifest::loader::discover_agents(&ctx.paths)?;
-        let safety_issues = crate::validate::validate_app_safety(&app, &agents);
-        if !safety_issues.is_empty() {
-            eprintln!("error: app failed safety pre-flight (use --dry-run to preview):");
-            for issue in &safety_issues {
-                eprintln!("  \u{2717} [{}] {}", issue.code, issue.message);
+
+        // Planned-agent check: a plain `--dry-run` still dispatches to live read-mode
+        // binaries (only `--simulate`, excluded above, stubs everything), so refuse a
+        // not-yet-runnable agent with a clear reason instead of a downstream
+        // "program not found" (#161).
+        if let Some(err) = crate::validate::validate_app_agents(&app, &agents).first() {
+            eprintln!("error: {}", err.message);
+            return Err(AwareError::Validation(format!("[{}]", err.code)));
+        }
+
+        // Safety pre-flight only gates real runs (dry-run is precisely how you test
+        // an app's safety contract before adding the blocks).
+        if !dry_run {
+            let safety_issues = crate::validate::validate_app_safety(&app, &agents);
+            if !safety_issues.is_empty() {
+                eprintln!("error: app failed safety pre-flight (use --dry-run to preview):");
+                for issue in &safety_issues {
+                    eprintln!("  \u{2717} [{}] {}", issue.code, issue.message);
+                }
+                return Err(AwareError::Validation(
+                    "write-mode node(s) missing `safety:` block".into(),
+                ));
             }
-            return Err(AwareError::Validation(
-                "write-mode node(s) missing `safety:` block".into(),
-            ));
         }
     }
 
@@ -513,6 +530,9 @@ fn install(ctx: &Context, spec: &str) -> Result<(), AwareError> {
     let mut issues = crate::validate::validate_app(&src_app);
     if let Ok(agents) = crate::manifest::loader::discover_agents(&ctx.paths) {
         issues.extend(crate::validate::validate_app_safety(&src_app, &agents));
+        // Don't install an app that references a not-yet-runnable agent — install
+        // must enforce the same contract as validate/compile (#161).
+        issues.extend(crate::validate::validate_app_agents(&src_app, &agents));
     }
     if crate::validate::has_errors(&issues) {
         for i in &issues {
@@ -591,6 +611,7 @@ fn validate_cmd(ctx: &Context, path: &std::path::Path) -> Result<(), AwareError>
     // be validating an app before installing its agents).
     if let Ok(agents) = crate::manifest::loader::discover_agents(&ctx.paths) {
         issues.extend(crate::validate::validate_app_safety(&app, &agents));
+        issues.extend(crate::validate::validate_app_agents(&app, &agents));
     }
 
     if issues.is_empty() {

cli/src/manifest/agent.rs

@@ -41,6 +41,13 @@ pub struct Agent {
     pub display_name: Option<String>,
     pub description: String,
     pub stateful: bool,
+    /// Runnability of the agent's transport. `available` (default) means the
+    /// transport binary ships / is installable; `planned` means the agent is
+    /// declared but not yet runnable (no shipped/installable binary), so apps
+    /// referencing it are rejected at validate/compile rather than failing at run
+    /// with "program not found" (#161).
+    #[serde(default)]
+    pub status: AgentStatus,
     pub vendor: Option<String>,
     pub license: String,
     #[allow(dead_code)]
@@ -73,6 +80,18 @@ pub struct Agent {
     pub skills: Vec<String>,
 }
 
+/// Whether an agent's transport is runnable today.
+#[derive(Debug, Deserialize, Clone, Copy, Default, PartialEq, Eq)]
+#[serde(rename_all = "kebab-case")]
+pub enum AgentStatus {
+    /// Transport binary ships or is installable — the agent can be dispatched to.
+    #[default]
+    Available,
+    /// Declared but not yet runnable (no shipped/installable transport binary).
+    /// Apps referencing it fail validation/compile rather than at run time (#161).
+    Planned,
+}
+
 /// Declarative authentication for a REST-transport agent.
 #[derive(Debug, Deserialize, Clone)]
 pub struct AuthScheme {

cli/src/validate.rs

@@ -261,6 +261,47 @@ pub fn validate_app_safety(
     out
 }
 
+/// Reject nodes that reference an agent the runtime can't dispatch to — one
+/// declared `status: planned` (no shipped/installable transport binary). Fails at
+/// validate/compile rather than at run with "program not found" (#161). Recurses
+/// into `for-each` `do:` bodies. Agents not in the catalogue are skipped here
+/// (lockfile resolution / run handle the missing-agent case).
+#[allow(dead_code)] // wired by `aware app validate` + `compile_to_disk` + `app run`
+pub fn validate_app_agents(
+    app: &App,
+    agents: &[crate::manifest::loader::DiscoveredAgent],
+) -> Vec<ValidationIssue> {
+    let mut out = Vec::new();
+    check_node_agents(&app.nodes, agents, &mut out);
+    out
+}
+
+fn check_node_agents(
+    nodes: &[crate::manifest::app::Node],
+    agents: &[crate::manifest::loader::DiscoveredAgent],
+    out: &mut Vec<ValidationIssue>,
+) {
+    use crate::manifest::agent::AgentStatus;
+    for n in nodes {
+        if let Some(agent_id) = &n.agent
+            && let Some(d) = agents.iter().find(|d| d.manifest.agent == *agent_id)
+            && d.manifest.status == AgentStatus::Planned
+        {
+            out.push(ValidationIssue::error(
+                "E_APP_AGENT_UNAVAILABLE",
+                format!(
+                    "node {:?} references agent {:?}, which is declared but not yet runnable \
+                     (no shipped/installable transport binary)",
+                    n.id, agent_id
+                ),
+            ));
+        }
+        if let Some(body) = &n.do_ {
+            check_node_agents(body, agents, out);
+        }
+    }
+}
+
 #[allow(dead_code)] // called by validate_app above
 fn has_cycle<'a>(
     node: &'a str,
@@ -319,6 +360,49 @@ mod tests {
         assert!(!has_errors(&issues), "issues: {issues:?}");
     }
 
+    fn agent_with_status(status_line: &str) -> crate::manifest::loader::DiscoveredAgent {
+        let yaml = format!(
+            "agent: html-report\nversion: 0.1.0\ndescription: x\nstateful: false\n{status_line}\
+             license: MIT\ntransport:\n  cli:\n    binary: aware-html-report\ncommands:\n  \
+             render:\n    lifecycle: single\n    description: x\n"
+        );
+        crate::manifest::loader::DiscoveredAgent {
+            manifest: serde_yaml::from_str(&yaml).unwrap(),
+            root: std::path::PathBuf::from("."),
+        }
+    }
+
+    #[test]
+    fn rejects_node_referencing_planned_agent() {
+        let agents = vec![agent_with_status("status: planned\n")];
+        let app: App = serde_yaml::from_str(
+            "app: uses-planned\nversion: 0.0.1\ndescription: |\n  uses planned agent\n\
+             requires: []\nnodes:\n  - id: report\n    agent: html-report\n    command: render\n",
+        )
+        .unwrap();
+        let issues = validate_app_agents(&app, &agents);
+        assert!(
+            issues.iter().any(|i| i.code == "E_APP_AGENT_UNAVAILABLE"),
+            "issues: {issues:?}"
+        );
+    }
+
+    #[test]
+    fn available_agent_passes_agent_validation() {
+        // No `status:` → defaults to available → no E_APP_AGENT_UNAVAILABLE.
+        let agents = vec![agent_with_status("")];
+        let app: App = serde_yaml::from_str(
+            "app: uses-avail\nversion: 0.0.1\ndescription: |\n  uses available agent\n\
+             requires: []\nnodes:\n  - id: report\n    agent: html-report\n    command: render\n",
+        )
+        .unwrap();
+        let issues = validate_app_agents(&app, &agents);
+        assert!(
+            !issues.iter().any(|i| i.code == "E_APP_AGENT_UNAVAILABLE"),
+            "issues: {issues:?}"
+        );
+    }
+
     #[test]
     fn rejects_unrunnable_inline_kind_at_validate() {
         // kind: shape passes parse but the runtime only runs `predicate`; validate

cli/tests/app_validate.rs

@@ -47,6 +47,37 @@ requires: []
         .stdout(predicate::str::contains("E_APP_CYCLE"));
 }
 
+#[test]
+fn app_referencing_planned_agent_rejected_by_validate() {
+    // An agent declared `status: planned` (no shipped transport binary) must make
+    // apps referencing it fail validate, not fail at run with "program not found" (#161).
+    let home = tempfile::tempdir().unwrap();
+    let agent_dir = home.path().join("agents").join("html-report");
+    std::fs::create_dir_all(&agent_dir).unwrap();
+    std::fs::write(
+        agent_dir.join("manifest.yaml"),
+        "agent: html-report\nversion: 0.1.0\ndescription: x\nstateful: false\nstatus: planned\n\
+         license: MIT\ntransport:\n  cli:\n    binary: aware-html-report\ncommands:\n  render:\n    lifecycle: single\n    description: x\n",
+    )
+    .unwrap();
+
+    let appdir = tempfile::tempdir().unwrap();
+    std::fs::write(
+        appdir.path().join("report.flo"),
+        "app: uses-planned\nversion: 0.0.1\ndescription: x\nrequires: []\nnodes:\n  - id: report\n    agent: html-report\n    command: render\n",
+    )
+    .unwrap();
+
+    Command::cargo_bin("aware")
+        .unwrap()
+        .env("AWARE_HOME", home.path())
+        .args(["app", "validate"])
+        .arg(appdir.path())
+        .assert()
+        .failure()
+        .stdout(predicate::str::contains("E_APP_AGENT_UNAVAILABLE"));
+}
+
 #[test]
 fn inline_shape_kind_rejected_by_validate() {
     // kind: shape parses + would compile, but the runtime only runs `predicate`;