From 845bbb7627c7033e40866057ed5f9d752bfd81f7 Mon Sep 17 00:00:00 2001
From: Pawel Lisowski <pawellisowski@o2.pl>
Date: Mon, 12 Oct 2026 09:28:09 +0200
Subject: [PATCH 01/17] feat(manifest): literal inputs refuse templates at
 validate, compile and run (#692)

An exec command's `code` is a program, and the approved `.lock` hashes the app
source, not what a template resolves to later. `code: '{{ inputs.code }}'`
would run Python supplied after a person approved the lock.

A manifest input may now declare `literal: true`. A node giving one any
template syntax ({{ }}, {% %}, {# #}) is refused with
E_APP_INPUT_MUST_BE_LITERAL naming the node and the input: by `app validate`
and the lock compiler (both through check_node_agents), and by the
orchestrator, which re-checks the node's merged UN-rendered value ahead of
every render_config, so a lock from an older compiler cannot smuggle one in
either. Templated non-literal inputs (exec `args`, i.e. data) still pass.

Only blender's exec.code adopts it here; tekla/rhino-8/revit-2026/
sketchup-2026 exec are #693.
---
 10-core/app-spec.md             |  14 +++++
 cli/src/manifest/agent.rs       | 108 ++++++++++++++++++++++++++++++++
 cli/src/runtime/orchestrator.rs |  92 +++++++++++++++++++++++++++
 cli/src/validate.rs             |  67 ++++++++++++++++++++
 4 files changed, 281 insertions(+)

diff --git a/10-core/app-spec.md b/10-core/app-spec.md
index 00d517cd9..b4da37435 100644
--- a/10-core/app-spec.md
+++ b/10-core/app-spec.md
@@ -1061,6 +1061,20 @@ One class of command is different: those that run **caller-supplied logic** whos
 
 The author taking responsibility for an `exec` script's mode is the only authority that exists — no manifest can inspect an arbitrary script. This resolves issue #165: a read-only host-`exec` app is no longer mislabeled write-mode or forced to declare a bogus `safety:` block.
 
+Not every `exec` is overridable. `blender`'s `exec` (#692) is fixed `mode: write` with no override, because a read-mode node runs for real under `--dry-run` and a preview must never render an animation.
+
+#### Literal inputs (`literal: true`)
+
+An input a command runs as a program — an `exec` command's `code` — must be pinned by the approval, and the `.lock` hashes the app source, not what a template later resolves to. A `code: '{{ inputs.code }}'` would run Python supplied after a person approved the lock. So an agent manifest may declare an input **`literal: true`**:
+
+```yaml
+inputs:
+  code: { type: string, required: true, literal: true }
+  args: { type: object }      # data: still templatable
+```
+
+A node that gives a literal input any template syntax (`{{ }}`, `{% %}`, `{# #}`) is refused with **`E_APP_INPUT_MUST_BE_LITERAL`**, naming the node and the input, by `aware app validate`, by the lock compiler, and by the runtime. The runtime check reads the node's merged, **un-rendered** value before any template is rendered, so a lock produced by an older compiler cannot smuggle one through either. Pass run-time data through a templatable input (`args`) instead. Today only `blender`'s `exec.code` is literal; the other host `exec` commands adopting it is tracked separately (#693).
+
 ### The block
 
 ```yaml
diff --git a/cli/src/manifest/agent.rs b/cli/src/manifest/agent.rs
index df3a4f43e..0db41f2cc 100644
--- a/cli/src/manifest/agent.rs
+++ b/cli/src/manifest/agent.rs
@@ -668,10 +668,118 @@ fn is_write_by_convention(name: &str) -> bool {
         || name == "save-attributes"
 }
 
+/// The validation code for a `literal: true` input that carries template syntax (#692).
+pub const E_APP_INPUT_MUST_BE_LITERAL: &str = "E_APP_INPUT_MUST_BE_LITERAL";
+
+impl Command {
+    /// The inputs this command declares `literal: true`, in manifest order.
+    ///
+    /// A literal input is one whose value must be pinned in the app source itself and so covered
+    /// by the `.lock` source hash — above all an `exec` command's `code`, which is run as a
+    /// program. A template there (`code: '{{ inputs.code }}'`) would execute text supplied AFTER a
+    /// person approved the lock, so validate, compile and the runtime all refuse one (#692). Data
+    /// the program reads (`args`) stays templatable; only the program is pinned.
+    pub fn literal_inputs(&self) -> Vec<&str> {
+        let Some(map) = self.inputs.as_mapping() else {
+            return Vec::new();
+        };
+        map.iter()
+            .filter(|(_, decl)| {
+                decl.get("literal")
+                    .and_then(Value::as_bool)
+                    .unwrap_or(false)
+            })
+            .filter_map(|(name, _)| name.as_str())
+            .collect()
+    }
+
+    /// The `literal: true` inputs whose value in `params` (a node's merged, UN-rendered
+    /// `config:` + `inputs:`) carries template syntax. Empty when every literal input is literal.
+    ///
+    /// Checked on the raw value, never after rendering: once a template has been rendered its
+    /// origin is unknowable, so a check placed after `render_config` would wave through exactly
+    /// the substitution it exists to stop.
+    pub fn templated_literal_inputs(&self, params: Option<&Value>) -> Vec<String> {
+        let Some(params) = params else {
+            return Vec::new();
+        };
+        self.literal_inputs()
+            .into_iter()
+            .filter(|name| params.get(*name).is_some_and(contains_template_syntax))
+            .map(str::to_string)
+            .collect()
+    }
+}
+
+/// Whether a value carries template syntax anywhere: `{{ … }}`, `{% … %}` or `{# … #}`.
+///
+/// Deliberately the whole minijinja delimiter set, not only `{{`: the runtime renders every string
+/// it hands a transport, so a `{%` block in a literal input would be executed by the template
+/// engine just as surely as an expression — and a literal input must reach the agent as written.
+pub fn contains_template_syntax(value: &Value) -> bool {
+    match value {
+        Value::String(s) => ["{{", "{%", "{#"].iter().any(|d| s.contains(d)),
+        Value::Sequence(items) => items.iter().any(contains_template_syntax),
+        Value::Mapping(map) => map
+            .iter()
+            .any(|(k, v)| contains_template_syntax(k) || contains_template_syntax(v)),
+        Value::Tagged(tagged) => contains_template_syntax(&tagged.value),
+        _ => false,
+    }
+}
+
+/// The human message for [`E_APP_INPUT_MUST_BE_LITERAL`], shared by validate, compile and the
+/// runtime so the three surfaces say the same thing.
+pub fn literal_input_message(node: &str, agent: &str, command: &str, input: &str) -> String {
+    format!(
+        "node {node:?} passes a templated value to `{input}` of {agent}.{command}, which is \
+         declared `literal: true`: it must be written out in the app source so the approved \
+         `.lock` pins exactly what runs. A template there would run text supplied after \
+         approval. Put the value inline, and pass run-time data through a templatable input \
+         (e.g. `args`) instead. Template delimiters (`{{{{`, `{{%`, `{{#`) are not allowed \
+         anywhere in a literal input."
+    )
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
 
+    #[test]
+    fn literal_inputs_are_read_from_the_input_declarations() {
+        let cmd: Command = serde_yaml::from_str(
+            "lifecycle: single\ndescription: d\ninputs:\n  code: { type: string, literal: true }\n  args: { type: object }\n  flag: string\n",
+        )
+        .unwrap();
+        assert_eq!(cmd.literal_inputs(), vec!["code"]);
+
+        let params: Value =
+            serde_yaml::from_str("code: '{{ inputs.code }}'\nargs: '{{ inputs.args }}'").unwrap();
+        assert_eq!(cmd.templated_literal_inputs(Some(&params)), vec!["code"]);
+
+        // Templated `args` (data, not code) is allowed; a literal `code` passes.
+        let ok: Value =
+            serde_yaml::from_str("code: 'def run(ctx): return 1'\nargs: '{{ inputs.args }}'")
+                .unwrap();
+        assert!(cmd.templated_literal_inputs(Some(&ok)).is_empty());
+        assert!(cmd.templated_literal_inputs(None).is_empty());
+    }
+
+    #[test]
+    fn every_template_delimiter_counts_as_templated() {
+        for text in ["{{ x }}", "a {% if x %}b{% endif %}", "{# note #}"] {
+            assert!(
+                contains_template_syntax(&Value::String(text.into())),
+                "{text}"
+            );
+        }
+        assert!(!contains_template_syntax(&Value::String(
+            "def run(ctx):\n    return {'a': {1: 2}}".into()
+        )));
+        let nested: Value = serde_yaml::from_str("[1, {k: '{{ x }}'}]").unwrap();
+        assert!(contains_template_syntax(&nested));
+    }
+
     /// Parse a shipped manifest relative to the repository root, with its path in errors.
     fn real_manifest(rel: &str) -> Agent {
         let path = std::path::PathBuf::from(env!("CARGO_MANIFEST_DIR"))
diff --git a/cli/src/runtime/orchestrator.rs b/cli/src/runtime/orchestrator.rs
index eee0e389b..6be573eeb 100644
--- a/cli/src/runtime/orchestrator.rs
+++ b/cli/src/runtime/orchestrator.rs
@@ -268,6 +268,7 @@ impl Orchestrator {
                 AwareError::Validation(format!("node `{source_id}` declares no agent"))
             })?;
             let command = node.command.as_deref().unwrap_or("");
+            self.ensure_literal_inputs(&node, agent, command)?;
             let params = yaml_to_json(node.merged_params().unwrap_or(serde_yaml::Value::Null))?;
             let args = render_config(&params, &self.ctx)?;
             let record_args = render_for_record(&params, &self.record_render_context(&params));
@@ -665,6 +666,7 @@ impl Orchestrator {
         }
         self.ctx.record_output(&node.id, current_event.clone());
 
+        self.ensure_literal_inputs(node, agent_id, command)?;
         let params = yaml_to_json(node.merged_params().unwrap_or(serde_yaml::Value::Null))?;
         let args = render_config(&params, &self.ctx)?;
         let record_args = render_for_record(&params, &self.record_render_context(&params));
@@ -868,6 +870,40 @@ impl Orchestrator {
         outcome
     }
 
+    /// Refuse a node whose `literal: true` input (an `exec` command's `code`) carries template
+    /// syntax, BEFORE anything is rendered (#692).
+    ///
+    /// Validate and the lock compiler already refuse this; the runtime repeats it because a lock
+    /// produced by an older compiler predates the rule, and because the check is only meaningful
+    /// on the un-rendered value — after `render_config` the text no longer says where it came
+    /// from. So this reads the node's merged `config:` + `inputs:` straight from the app the lock
+    /// approved, and the orchestrator calls it ahead of every `render_config` on an agent node.
+    fn ensure_literal_inputs(
+        &self,
+        node: &Node,
+        agent_id: &str,
+        command: &str,
+    ) -> Result<(), AwareError> {
+        let Ok(agent) = self.catalogue.manifest(agent_id) else {
+            return Ok(());
+        };
+        let Some(cmd) = agent.commands.get(command) else {
+            return Ok(());
+        };
+        if let Some(input) = cmd
+            .templated_literal_inputs(node.merged_params().as_ref())
+            .into_iter()
+            .next()
+        {
+            return Err(AwareError::Validation(format!(
+                "[{}] {}",
+                crate::manifest::agent::E_APP_INPUT_MUST_BE_LITERAL,
+                crate::manifest::agent::literal_input_message(&node.id, agent_id, command, &input)
+            )));
+        }
+        Ok(())
+    }
+
     async fn emit_progress(&mut self, node_id: &str, data: Value) -> Result<(), AwareError> {
         self.emit(RunEvent::NodeProgress {
             ts: now_iso(),
@@ -969,6 +1005,7 @@ impl Orchestrator {
             let command = node.command.as_deref().unwrap_or("");
             // Source params via the shared config:+inputs: merge rule, then
             // convert serde_yaml::Value → serde_json::Value and render templates.
+            self.ensure_literal_inputs(node, agent_id, command)?;
             let config_json =
                 yaml_to_json(node.merged_params().unwrap_or(serde_yaml::Value::Null))?;
             let args = render_config(&config_json, &self.ctx)?;
@@ -2603,6 +2640,61 @@ commands:
         }
     }
 
+    /// #692: the runtime refuses a templated `literal: true` input on the UN-rendered value, so a
+    /// lock compiled before the rule existed still cannot run code supplied after approval. The
+    /// mock invoker HAS a canned output for the call, so without the check the run would succeed
+    /// — the refusal is what makes it fail. Templated `args` beside literal `code` still runs.
+    #[tokio::test]
+    async fn the_runtime_refuses_a_templated_literal_input_before_rendering() {
+        let app_yaml = |code: &str| {
+            format!(
+                "app: lit\nversion: 0.1.0\ndescription: x\nnodes:\n  - id: animate\n    \
+                 agent: runner\n    command: exec\n    inputs:\n      code: {code}\n      \
+                 args: '{{{{ inputs.args }}}}'\nconnections: []\nrequires: []\n"
+            )
+        };
+        let install = |tmp: &tempfile::TempDir| {
+            let agent_dir = tmp.path().join("aware").join("agents").join("runner");
+            std::fs::create_dir_all(&agent_dir).unwrap();
+            std::fs::write(
+                agent_dir.join("manifest.yaml"),
+                "agent: runner\nversion: 0.0.1\ndescription: x\nstateful: false\nlicense: MIT\n\
+                 transport: { builtin: {} }\ncommands:\n  exec:\n    lifecycle: single\n    \
+                 mode: write\n    description: x\n    inputs:\n      code: { type: string, literal: true }\n      \
+                 args: { type: object }\n",
+            )
+            .unwrap();
+        };
+        let invoker = || -> Arc<dyn AgentInvoker> {
+            Arc::new(MockInvoker::new().with_single(
+                "runner",
+                "exec",
+                serde_json::json!({ "ok": true }),
+            ))
+        };
+
+        let templated: App = serde_yaml::from_str(&app_yaml("'{{ inputs.code }}'")).unwrap();
+        let (mut orch, tmp, _log) = make_orchestrator(templated, invoker()).await;
+        install(&tmp);
+        orch.ctx.inputs = serde_json::json!({ "code": "def run(ctx): return 1", "args": {} });
+        let err = orch
+            .run_one_shot()
+            .await
+            .expect_err("templated literal code must not run");
+        let text = err.to_string();
+        assert!(text.contains("E_APP_INPUT_MUST_BE_LITERAL"), "{text}");
+        assert!(text.contains("\"animate\""), "{text}");
+        assert!(text.contains("`code`"), "{text}");
+
+        let literal: App = serde_yaml::from_str(&app_yaml("'def run(ctx): return 1'")).unwrap();
+        let (mut orch, tmp, _log) = make_orchestrator(literal, invoker()).await;
+        install(&tmp);
+        orch.ctx.inputs = serde_json::json!({ "args": { "storeys": 3 } });
+        orch.run_one_shot()
+            .await
+            .expect("literal code with templated args must run");
+    }
+
     #[tokio::test]
     async fn frozen_node_emits_pinned_output_and_skips_the_agent() {
         // A frozen node must NOT call its agent (the empty invoker would error if it did) and must
diff --git a/cli/src/validate.rs b/cli/src/validate.rs
index e1fae2e60..7cb507383 100644
--- a/cli/src/validate.rs
+++ b/cli/src/validate.rs
@@ -1519,6 +1519,24 @@ fn check_node_agents(
                 ));
             }
 
+            // #692: a `literal: true` input (an `exec` command's `code`) must be written out in
+            // the app source, so the `.lock` source hash pins exactly what runs. Checked here —
+            // the agent-aware validator every lock-producing and run path goes through — so
+            // `app validate` and the lock compiler refuse it identically; the orchestrator
+            // re-checks the un-rendered value at run time for a lock made before this rule.
+            if let Some(cmd_name) = &n.command
+                && let Some(cmd) = d.manifest.commands.get(cmd_name.as_str())
+            {
+                for input in cmd.templated_literal_inputs(n.merged_params().as_ref()) {
+                    out.push(ValidationIssue::error(
+                        crate::manifest::agent::E_APP_INPUT_MUST_BE_LITERAL,
+                        crate::manifest::agent::literal_input_message(
+                            &n.id, agent_id, cmd_name, &input,
+                        ),
+                    ));
+                }
+            }
+
             // RFC #223 — the fenced runtime model-extraction carve-out. A command that
             // calls a model at run time (`model-extraction: true`) is admitted into the
             // deterministic run path ONLY when it is `category: curated` AND its agent
@@ -3385,6 +3403,55 @@ app: after-everything
         );
     }
 
+    /// #692: a `literal: true` input carrying a template is refused with a code naming the node
+    /// and the input; the same input written out passes, and a templated NON-literal input
+    /// (`args`, data rather than code) is still allowed.
+    #[test]
+    fn a_templated_literal_input_is_refused_by_name() {
+        let agents = vec![crate::manifest::loader::DiscoveredAgent {
+            manifest: serde_yaml::from_str(
+                "agent: runner\nversion: 0.1.0\ndescription: x\nstateful: false\nlicense: MIT\n\
+                 transport:\n  builtin: {}\ncommands:\n  exec:\n    lifecycle: single\n    \
+                 mode: write\n    description: x\n    inputs:\n      code: { type: string, literal: true }\n      \
+                 args: { type: object }\n",
+            )
+            .unwrap(),
+            root: std::path::PathBuf::from("."),
+        }];
+        let app = |code: &str| -> App {
+            serde_yaml::from_str(&format!(
+                "app: lit\nversion: 0.0.1\ndescription: x\nrequires: []\n\
+                 nodes:\n  - id: animate\n    agent: runner\n    command: exec\n    \
+                 inputs:\n      code: {code}\n      args: '{{{{ inputs.args }}}}'\n"
+            ))
+            .unwrap()
+        };
+
+        let issues = validate_app_agents(&app("'{{ inputs.code }}'"), &agents);
+        let hit = issues
+            .iter()
+            .find(|i| i.code == "E_APP_INPUT_MUST_BE_LITERAL")
+            .unwrap_or_else(|| panic!("templated code must be refused: {issues:?}"));
+        assert!(hit.message.contains("\"animate\""), "{}", hit.message);
+        assert!(hit.message.contains("`code`"), "{}", hit.message);
+        assert!(hit.message.contains("runner.exec"), "{}", hit.message);
+
+        // `{% %}` is template syntax too — the engine would execute it.
+        let block = validate_app_agents(&app("'{% if true %}x{% endif %}'"), &agents);
+        assert!(
+            block
+                .iter()
+                .any(|i| i.code == "E_APP_INPUT_MUST_BE_LITERAL"),
+            "{block:?}"
+        );
+
+        let ok = validate_app_agents(&app("'def run(ctx): return 1'"), &agents);
+        assert!(
+            !ok.iter().any(|i| i.code == "E_APP_INPUT_MUST_BE_LITERAL"),
+            "literal code with templated args must pass: {ok:?}"
+        );
+    }
+
     #[test]
     fn rejects_node_referencing_planned_command() {
         // The agent is available, but one command is `status: planned` (#199) — an

From edbd51bc72c879c42d7360f967b831d9015ff65f Mon Sep 17 00:00:00 2001
From: Pawel Lisowski <pawellisowski@o2.pl>
Date: Mon, 12 Oct 2026 09:28:18 +0200
Subject: [PATCH 02/17] feat(blender): exec dispatch and per-frame progress on
 the builtin transport (#692)

Long Blender renders were silent until they finished: node-progress (#405)
was relayed only for CLI transports, so a 40-minute animation looked exactly
like a hang.

The bounded Relay pump (8 KiB/record, 10,000 records, 16 MiB read,
progress-suppressed) moves from invoker.rs into runtime::progress as a shared
component. The CLI transport drives it beside wait_with_output as before;
render::blender drives it from INSIDE its own select loop, next to the
concurrent pipe drains, the deadline and the taskkill /T tree kill, with a
final drain after exit and after a timeout kill. The Blender runner is not
replaced by relay_progress, which would have lost both.

On a run, DispatchInvoker hands blender a run-owned channel
(AWARE_PROGRESS_FILE) and the records become node-progress events exactly as
for a CLI bridge. `aware agent invoke` passes a caller-set
AWARE_PROGRESS_FILE through to Blender (FloLess's Render card tails it); any
other launch removes the variable so an inherited one is never written to.

`exec` joins the command table (exec.py, 1800 s default), with pre-spawn
validation (non-empty string code, ifc-path/blend-path exclusive, output-dir
present, object args) failing as invalid-inputs, exit 3, and a dry-run that
echoes the inputs with the code's size, never the code.
---
 cli/src/commands/agent.rs   |   3 +
 cli/src/render/blender.rs   | 540 +++++++++++++++++++++++++++++++++---
 cli/src/runtime/invoker.rs  | 262 +++--------------
 cli/src/runtime/progress.rs | 223 +++++++++++++++
 4 files changed, 775 insertions(+), 253 deletions(-)

diff --git a/cli/src/commands/agent.rs b/cli/src/commands/agent.rs
index c3d5667b1..ad35fa23a 100644
--- a/cli/src/commands/agent.rs
+++ b/cli/src/commands/agent.rs
@@ -995,6 +995,9 @@ async fn invoke_cmd(
     let result = BuiltinInvoker {
         dry_run: false,
         blender_root: None,
+        // A caller that exported AWARE_PROGRESS_FILE (FloLess's Render card) tails it itself, so a
+        // producer this builtin spawns writes there (#692).
+        inherit_progress_env: true,
     }
     .invoke_single(agent_id, command, args)
     .await?;
diff --git a/cli/src/render/blender.rs b/cli/src/render/blender.rs
index 685a2feb0..fe06cbca9 100644
--- a/cli/src/render/blender.rs
+++ b/cli/src/render/blender.rs
@@ -1,8 +1,9 @@
 //! `blender.*` — the builtin transport for the headless Blender visualization agent.
 //!
 //! The `blender` agent is IFC in, rendered PNG / MP4 out, fully unattended. The work itself lives in
-//! five `bpy` scripts shipped with the agent (`<AWARE_HOME>/agents/blender/scripts/`); this module is
-//! the launcher that runs them:
+//! the `bpy` scripts shipped with the agent (`<AWARE_HOME>/agents/blender/scripts/`) — five fixed
+//! recipes plus `exec.py`, which runs author-time code pinned in the approved lock (#692); this
+//! module is the launcher that runs them:
 //!
 //! ```text
 //! blender -b -P <scripts-dir>/<script>.py -- @<temp-inputs>.json
@@ -41,12 +42,22 @@
 //!
 //! Both are [`AwareError::Network`] — the CLI's "agent runtime" class (exit 4 in `cli-spec.md`),
 //! which is what `CliInvoker` already uses for a transport binary that will not spawn.
+//!
+//! ## Progress (#405 parity, #692)
+//!
+//! A render can run for hours, so the scripts append `{"$aware-progress": …}` lines to
+//! `AWARE_PROGRESS_FILE` (`scripts/_progress.py`). On a run, this module owns that channel: it
+//! drives the shared bounded [`Relay`] pump from INSIDE its own wait loop — beside the concurrent
+//! pipe drains, the deadline and the process-tree kill — and drains it once more after an exit or
+//! a timeout kill. See [`BlenderProgress`].
 
 use crate::error::AwareError;
+use crate::runtime::progress::Relay;
 use crate::which::find_on_path;
 use serde_json::{Map, Value};
 use std::path::{Path, PathBuf};
 use std::time::Duration;
+use tokio::sync::mpsc;
 
 /// The framing sentinels, mirrored from the agent's `scripts/_result.py`. Renaming one there is a
 /// breaking change to this transport.
@@ -82,6 +93,7 @@ fn script_for_command(command: &str) -> Option<&'static str> {
         "scene.apply-look" => Some("scene_apply_look.py"),
         "render.still" => Some("render_still.py"),
         "render.turntable" => Some("render_turntable.py"),
+        "exec" => Some("exec.py"),
         _ => None,
     }
 }
@@ -93,6 +105,7 @@ const COMMANDS: &[&str] = &[
     "scene.apply-look",
     "render.still",
     "render.turntable",
+    "exec",
 ];
 
 /// The default wall-clock budget for a command, in seconds.
@@ -104,7 +117,8 @@ const COMMANDS: &[&str] = &[
 /// to cap honest work; a caller who knows their scene overrides it with `timeout-seconds`.
 fn default_timeout_seconds(command: &str) -> u64 {
     match command {
-        "render.still" | "render.turntable" => 1_800,
+        // `exec` is render-class: author code that renders an animation is the reason it exists.
+        "render.still" | "render.turntable" | "exec" => 1_800,
         _ => 600,
     }
 }
@@ -493,6 +507,67 @@ fn require_str(command: &str, args: &Value, key: &str) -> Result<String, AwareEr
     }
 }
 
+/// `exec`'s pre-spawn checks: the program is present, the scene source is unambiguous, and there
+/// is somewhere to write. Each is an `invalid-inputs` failure (exit 3) raised BEFORE Blender is
+/// launched — a Blender start costs seconds, and a miswired node should not pay that to learn it.
+fn validate_exec_inputs(args: &Value) -> Result<(), AwareError> {
+    let invalid = |message: String| {
+        AwareError::Validation(format!("blender exec failed [invalid-inputs]: {message}"))
+    };
+    match args.get("code") {
+        Some(Value::String(code)) if !code.trim().is_empty() => {}
+        Some(Value::String(_)) | None | Some(Value::Null) => {
+            return Err(invalid(
+                "required input `code` is missing or empty — it must be Python source that \
+                 defines `run(ctx)`"
+                    .into(),
+            ));
+        }
+        Some(other) => {
+            return Err(invalid(format!(
+                "`code` must be a string of Python source, got {}",
+                json_kind(other)
+            )));
+        }
+    }
+    let given = |key: &str| {
+        args.get(key)
+            .and_then(Value::as_str)
+            .is_some_and(|v| !v.trim().is_empty())
+    };
+    if given("ifc-path") && given("blend-path") {
+        return Err(invalid(
+            "`ifc-path` and `blend-path` are mutually exclusive; give at most one".into(),
+        ));
+    }
+    if !given("output-dir") {
+        return Err(invalid(
+            "required input `output-dir` is missing — the directory the code writes its \
+             renders into"
+                .into(),
+        ));
+    }
+    if let Some(a) = args.get("args").filter(|a| !a.is_null() && !a.is_object()) {
+        return Err(invalid(format!(
+            "`args` must be an object, got {}",
+            json_kind(a)
+        )));
+    }
+    Ok(())
+}
+
+/// A JSON value's kind, for an error message.
+fn json_kind(value: &Value) -> &'static str {
+    match value {
+        Value::Null => "null",
+        Value::Bool(_) => "a boolean",
+        Value::Number(_) => "a number",
+        Value::String(_) => "a string",
+        Value::Array(_) => "an array",
+        Value::Object(_) => "an object",
+    }
+}
+
 /// The `--dry-run` / `--simulate` posture: never spawn Blender, but still return the shape a
 /// downstream node resolves against — above all the would-be output path — without writing anything.
 ///
@@ -525,6 +600,32 @@ fn dry_run_result(command: &str, args: &Value) -> Result<Value, AwareError> {
             out.insert("output-path".into(), Value::from(output));
             out.insert("size-bytes".into(), Value::from(0u64));
         }
+        "exec" => {
+            // Validated exactly as a real run validates, so a preview fails the same way. The
+            // echo carries the code's SIZE rather than the code: a preview record must not turn
+            // into a second copy of the program.
+            validate_exec_inputs(args)?;
+            let output_dir = abs_path(&require_str(command, args, "output-dir")?);
+            let code_bytes = args.get("code").and_then(Value::as_str).map_or(0, str::len);
+            let mut echo = Map::new();
+            echo.insert("code-bytes".into(), Value::from(code_bytes as u64));
+            for key in [
+                "args",
+                "ifc-path",
+                "blend-path",
+                "preset",
+                "timeout-seconds",
+            ] {
+                if let Some(v) = args.get(key).filter(|v| !v.is_null()) {
+                    echo.insert(key.into(), v.clone());
+                }
+            }
+            out.insert("output-dir".into(), Value::from(output_dir));
+            out.insert("inputs".into(), Value::Object(echo));
+            out.insert("result".into(), Value::Null);
+            out.insert("outputs".into(), Value::Array(Vec::new()));
+            out.insert("frames".into(), Value::from(0u64));
+        }
         "scene.info" => {
             // Read-only: no output path to report, so the value here is the inventory contract —
             // and the same either/or the script enforces, so a preview catches the miswiring.
@@ -594,15 +695,46 @@ async fn kill_blender(child: &mut tokio::process::Child) {
     let _ = child.wait().await;
 }
 
+/// The environment variable a producer appends `{"$aware-progress": …}` lines to (#405).
+const PROGRESS_ENV: &str = "AWARE_PROGRESS_FILE";
+
+/// Where a Blender child's progress records go (#405 parity for the builtin transport, #692).
+pub enum BlenderProgress {
+    /// No listener: the variable is REMOVED from the child's environment, so a value inherited
+    /// from whoever launched `aware` cannot make Blender write somewhere nobody asked it to.
+    Off,
+    /// `aware agent invoke` under a caller that set `AWARE_PROGRESS_FILE` itself (FloLess's Render
+    /// card): the caller's path is handed to Blender unchanged and the caller tails it.
+    Passthrough(PathBuf),
+    /// A workflow run: AWARE owns the channel file, tails it while Blender works, and forwards
+    /// each record to `tx`, which the orchestrator writes into the trace as `node-progress`.
+    Relay {
+        path: PathBuf,
+        tx: mpsc::Sender<Value>,
+    },
+}
+
+impl BlenderProgress {
+    /// The caller's own channel, when `aware agent invoke` was launched with one.
+    pub fn from_caller_env() -> Self {
+        match std::env::var_os(PROGRESS_ENV) {
+            Some(path) if !path.is_empty() => Self::Passthrough(PathBuf::from(path)),
+            _ => Self::Off,
+        }
+    }
+}
+
 /// Run one `blender` agent command: spawn headless Blender on the command's script, recover the
 /// framed payload, and surface the script's named errors intact.
 ///
-/// This is the entry point `BuiltinInvoker::invoke_single` dispatches `("blender", …)` to.
+/// This is the entry point `BuiltinInvoker::invoke_single` dispatches `("blender", …)` to, and the
+/// one the run path calls with a [`BlenderProgress::Relay`] so a long render reports while it works.
 pub async fn run_blender_command(
     command: &str,
     args: &Value,
     dry_run: bool,
     agent_root: Option<&Path>,
+    progress: BlenderProgress,
 ) -> Result<Value, AwareError> {
     // Reject an unknown command before anything else, so a typo never reports as "agent not
     // installed" just because the scripts directory is also missing.
@@ -614,50 +746,104 @@ pub async fn run_blender_command(
     }
     // The budget is validated on both postures so a bad value fails identically when previewing.
     let budget = timeout_for(command, args)?;
+    if command == "exec" {
+        validate_exec_inputs(args)?;
+    }
     if dry_run {
         return dry_run_result(command, args);
     }
 
     let script = script_path(command, agent_root)?;
     let blender = find_blender()?;
+    run_script(command, &blender, &script, args, budget, progress).await
+}
+
+/// Spawn `blender -b -P <script> -- @<inputs>` and turn what it prints into the command's result.
+/// Split from [`run_blender_command`] so the process handling is testable with a stand-in
+/// executable and a stand-in script, without an installed agent or a real Blender.
+async fn run_script(
+    command: &str,
+    blender: &Path,
+    script: &Path,
+    args: &Value,
+    budget: Duration,
+    progress: BlenderProgress,
+) -> Result<Value, AwareError> {
     let inputs = ScratchInputs::write(args)?;
 
     // Exactly the invocation Phase 1 verified against Blender 5.2 — no extra flags (not even
     // `--factory-startup`), because deviating from the proven command line is how a working script
     // starts failing for reasons that have nothing to do with this transport.
-    let mut launch = tokio::process::Command::new(&blender);
+    let mut launch = tokio::process::Command::new(blender);
     crate::private_rest_header::scrub_tokio_child(&mut launch);
-    let mut child = launch
+    launch
         .arg("-b")
         .arg("-P")
-        .arg(&script)
+        .arg(script)
         .arg("--")
         .arg(inputs.arg())
         .stdin(std::process::Stdio::null())
         .stdout(std::process::Stdio::piped())
-        .stderr(std::process::Stdio::piped())
-        .spawn()
-        .map_err(|e| {
-            AwareError::Network(format!(
-                "blender {command}: cannot spawn {}: {e}\n  hint: point {BLENDER_ENV} at a \
-                 working Blender executable",
-                blender.display()
-            ))
-        })?;
+        .stderr(std::process::Stdio::piped());
+    // Set ONLY when somebody reads the channel — a producer takes the variable's presence to mean
+    // "the runtime is listening", exactly as on the CLI transport.
+    let mut relay = match progress {
+        BlenderProgress::Off => {
+            launch.env_remove(PROGRESS_ENV);
+            None
+        }
+        BlenderProgress::Passthrough(path) => {
+            launch.env(PROGRESS_ENV, path);
+            None
+        }
+        BlenderProgress::Relay { path, tx } => {
+            launch.env(PROGRESS_ENV, &path);
+            Some(Relay::new(path, tx))
+        }
+    };
+    let mut child = launch.spawn().map_err(|e| {
+        AwareError::Network(format!(
+            "blender {command}: cannot spawn {}: {e}\n  hint: point {BLENDER_ENV} at a \
+             working Blender executable",
+            blender.display()
+        ))
+    })?;
 
     // Drain both pipes concurrently with the wait: Blender is chatty enough to fill a pipe buffer
     // and deadlock against a wait-then-read.
     let stdout_task = tokio::spawn(read_to_end(child.stdout.take()));
     let stderr_task = tokio::spawn(read_to_end(child.stderr.take()));
 
-    let status = match tokio::time::timeout(budget, child.wait()).await {
-        Ok(status) => status.map_err(|e| {
+    // One loop owns the wait, the deadline AND the progress pump, so the relay runs inside the
+    // same select that drains pipes and enforces the timeout — it never replaces that runner
+    // (which is what `wait_with_output` would have done, losing the tree kill). `Child::wait` is
+    // cancel-safe, so re-polling it every interval loses nothing.
+    let deadline = tokio::time::Instant::now() + budget;
+    let waited = loop {
+        tokio::select! {
+            status = child.wait() => break Some(status),
+            _ = tokio::time::sleep_until(deadline) => break None,
+            _ = tokio::time::sleep(crate::runtime::progress::POLL_INTERVAL), if relay.is_some() => {
+                if let Some(relay) = relay.as_mut() {
+                    relay.pump().await;
+                }
+            }
+        }
+    };
+
+    let status = match waited {
+        Some(status) => status.map_err(|e| {
             AwareError::Network(format!("blender {command}: waiting on Blender failed: {e}"))
         })?,
-        Err(_) => {
+        None => {
             // The design doc's other required named error. Kill first, report second — a wedged
             // Blender must not outlive the call.
             kill_blender(&mut child).await;
+            // The records written before the kill are most of the diagnosis ("it reached frame
+            // 140 of 240"), so they are delivered before the error, not lost with the process.
+            if let Some(relay) = relay.as_mut() {
+                relay.drain_to_end().await;
+            }
             stdout_task.abort();
             stderr_task.abort();
             return Err(AwareError::Network(format!(
@@ -672,6 +858,12 @@ pub async fn run_blender_command(
             )));
         }
     };
+    // A producer that writes its last record and exits in the same breath would otherwise lose it
+    // to the poll interval.
+    if let Some(relay) = relay.as_mut() {
+        relay.drain_to_end().await;
+    }
+    drop(relay);
 
     let stdout = String::from_utf8_lossy(&stdout_task.await.unwrap_or_default()).into_owned();
     let stderr = String::from_utf8_lossy(&stderr_task.await.unwrap_or_default()).into_owned();
@@ -681,8 +873,8 @@ pub async fn run_blender_command(
     let Some(body) = extract_framed_payload(&stdout) else {
         return Err(no_result_error(
             command,
-            &blender,
-            &script,
+            blender,
+            script,
             status.code(),
             &stdout,
             &stderr,
@@ -730,6 +922,8 @@ mod tests {
             script_for_command("render.turntable"),
             Some("render_turntable.py")
         );
+        assert_eq!(script_for_command("exec"), Some("exec.py"));
+        assert!(COMMANDS.contains(&"exec"), "exec must be advertised");
     }
 
     #[test]
@@ -751,9 +945,15 @@ mod tests {
 
     #[tokio::test]
     async fn an_unknown_command_names_what_is_available() {
-        let err = run_blender_command("render.video", &json!({}), false, None)
-            .await
-            .unwrap_err();
+        let err = run_blender_command(
+            "render.video",
+            &json!({}),
+            false,
+            None,
+            BlenderProgress::Off,
+        )
+        .await
+        .unwrap_err();
         let text = err.to_string();
         assert!(matches!(err, AwareError::Validation(_)), "{text}");
         assert!(text.contains("no command `render.video`"), "{text}");
@@ -951,6 +1151,7 @@ mod tests {
     fn renders_get_a_longer_default_budget_than_imports() {
         assert_eq!(default_timeout_seconds("render.still"), 1_800);
         assert_eq!(default_timeout_seconds("render.turntable"), 1_800);
+        assert_eq!(default_timeout_seconds("exec"), 1_800);
         assert_eq!(default_timeout_seconds("scene.import"), 600);
         assert_eq!(default_timeout_seconds("scene.info"), 600);
     }
@@ -999,6 +1200,7 @@ mod tests {
             &json!({ "blend-path": "m.blend", "output-path": "out/hero.png" }),
             true,
             None,
+            BlenderProgress::Off,
         )
         .await
         .expect("dry run");
@@ -1017,6 +1219,7 @@ mod tests {
             &json!({ "ifc-path": "m.ifc", "blend-path": "staged/m.blend" }),
             true,
             None,
+            BlenderProgress::Off,
         )
         .await
         .expect("dry run");
@@ -1036,6 +1239,7 @@ mod tests {
             &json!({ "blend-path": "m.blend" }),
             true,
             None,
+            BlenderProgress::Off,
         )
         .await
         .expect("dry run");
@@ -1050,6 +1254,7 @@ mod tests {
             &json!({ "blend-path": "m.blend", "output-path": "look/m2.blend" }),
             true,
             None,
+            BlenderProgress::Off,
         )
         .await
         .expect("dry run");
@@ -1063,9 +1268,15 @@ mod tests {
 
     #[tokio::test]
     async fn a_dry_run_info_returns_the_inventory_contract() {
-        let out = run_blender_command("scene.info", &json!({ "ifc-path": "m.ifc" }), true, None)
-            .await
-            .expect("dry run");
+        let out = run_blender_command(
+            "scene.info",
+            &json!({ "ifc-path": "m.ifc" }),
+            true,
+            None,
+            BlenderProgress::Off,
+        )
+        .await
+        .expect("dry run");
         assert_eq!(out["count"], json!(0));
         assert_eq!(out["source"], json!("ifc-path"));
         assert!(out["elements"].as_array().expect("elements").is_empty());
@@ -1082,13 +1293,274 @@ mod tests {
                 json!({ "ifc-path": "m.ifc", "blend-path": "m.blend" }),
             ),
         ] {
-            let err = run_blender_command(command, &args, true, None)
+            let err = run_blender_command(command, &args, true, None, BlenderProgress::Off)
                 .await
                 .expect_err("preview must not mask a miswired node");
             assert!(matches!(err, AwareError::Validation(_)), "{err}");
         }
     }
 
+    // ── exec (#692) ──
+
+    fn exec_args() -> Value {
+        json!({
+            "code": "def run(ctx):\n    return {'n': 1}\n",
+            "args": { "storeys": 3 },
+            "output-dir": "out/anim",
+        })
+    }
+
+    #[tokio::test]
+    async fn exec_dry_run_echoes_the_inputs_without_spawning_or_copying_the_code() {
+        let out = run_blender_command("exec", &exec_args(), true, None, BlenderProgress::Off)
+            .await
+            .expect("dry run");
+        assert_eq!(out["dry-run"], json!(true));
+        assert_eq!(out["frames"], json!(0));
+        assert_eq!(out["outputs"], json!([]));
+        assert!(
+            out["output-dir"]
+                .as_str()
+                .unwrap_or_default()
+                .ends_with("anim"),
+            "{out}"
+        );
+        assert_eq!(out["inputs"]["args"], json!({ "storeys": 3 }));
+        // The SIZE of the program travels, never the program itself.
+        assert!(
+            out["inputs"]["code-bytes"].as_u64().unwrap_or(0) > 0,
+            "{out}"
+        );
+        assert!(!out.to_string().contains("def run"), "{out}");
+    }
+
+    #[tokio::test]
+    async fn exec_inputs_are_validated_before_blender_is_ever_looked_for() {
+        // `real` (dry_run = false) with a broken input must fail on the INPUT, exit 3, and never
+        // reach script resolution or binary discovery — the agent is not installed here, so
+        // reaching either would surface a different error.
+        let mut cases = Vec::new();
+        let mut no_code = exec_args();
+        no_code.as_object_mut().unwrap().remove("code");
+        cases.push((no_code, "`code`"));
+        let mut blank = exec_args();
+        blank["code"] = json!("   \n");
+        cases.push((blank, "`code`"));
+        let mut not_text = exec_args();
+        not_text["code"] = json!({ "run": 1 });
+        cases.push((not_text, "`code` must be a string"));
+        let mut both = exec_args();
+        both["ifc-path"] = json!("m.ifc");
+        both["blend-path"] = json!("m.blend");
+        cases.push((both, "mutually exclusive"));
+        let mut no_dir = exec_args();
+        no_dir.as_object_mut().unwrap().remove("output-dir");
+        cases.push((no_dir, "`output-dir`"));
+        let mut bad_args = exec_args();
+        bad_args["args"] = json!([1, 2]);
+        cases.push((bad_args, "`args` must be an object"));
+
+        for (args, needle) in cases {
+            for dry_run in [false, true] {
+                let err = run_blender_command("exec", &args, dry_run, None, BlenderProgress::Off)
+                    .await
+                    .expect_err("a miswired exec must not run");
+                let text = err.to_string();
+                assert_eq!(err.exit_code(), 3, "{text}");
+                assert!(text.contains("[invalid-inputs]"), "{text}");
+                assert!(text.contains(needle), "{needle}: {text}");
+            }
+        }
+    }
+
+    /// A stand-in Blender: a script that writes `lines` to the progress channel, sleeping
+    /// `pause_seconds` after the first, then prints `framed` between the result sentinels.
+    /// `hang_seconds` > 0 makes it wedge instead of finishing. Returns the executable's path.
+    fn fake_blender(
+        dir: &Path,
+        first: &str,
+        later: &str,
+        pause_seconds: u32,
+        hang_seconds: u32,
+        framed: &str,
+    ) -> PathBuf {
+        if cfg!(windows) {
+            let path = dir.join("fake-blender.cmd");
+            let mut body = String::from("@echo off\r\n");
+            body.push_str(&format!(">>\"%AWARE_PROGRESS_FILE%\" echo {first}\r\n"));
+            body.push_str(&format!("ping -n {} 127.0.0.1 >nul\r\n", pause_seconds + 1));
+            if hang_seconds > 0 {
+                body.push_str(&format!("ping -n {} 127.0.0.1 >nul\r\n", hang_seconds + 1));
+            }
+            body.push_str(&format!(">>\"%AWARE_PROGRESS_FILE%\" echo {later}\r\n"));
+            body.push_str("echo Blender quit noise\r\n");
+            body.push_str("echo ^<^<^<AWARE_RESULT^>^>^>\r\n");
+            body.push_str(&format!("echo {framed}\r\n"));
+            body.push_str("echo ^<^<^<AWARE_RESULT_END^>^>^>\r\n");
+            std::fs::write(&path, body).expect("write fake blender");
+            path
+        } else {
+            let path = dir.join("fake-blender");
+            let mut body = String::from("#!/bin/sh\n");
+            body.push_str(&format!(
+                "printf '%s\\n' '{first}' >> \"$AWARE_PROGRESS_FILE\"\n"
+            ));
+            body.push_str(&format!("sleep {pause_seconds}\n"));
+            if hang_seconds > 0 {
+                body.push_str(&format!("sleep {hang_seconds}\n"));
+            }
+            body.push_str(&format!(
+                "printf '%s\\n' '{later}' >> \"$AWARE_PROGRESS_FILE\"\n"
+            ));
+            body.push_str("echo 'Blender quit noise'\n");
+            body.push_str("echo '<<<AWARE_RESULT>>>'\n");
+            body.push_str(&format!("echo '{framed}'\n"));
+            body.push_str("echo '<<<AWARE_RESULT_END>>>'\n");
+            std::fs::write(&path, body).expect("write fake blender");
+            #[cfg(unix)]
+            {
+                use std::os::unix::fs::PermissionsExt;
+                std::fs::set_permissions(&path, std::fs::Permissions::from_mode(0o755))
+                    .expect("chmod fake blender");
+            }
+            path
+        }
+    }
+
+    /// Collect relayed records with the moment each arrived.
+    fn collect(
+        mut rx: mpsc::Receiver<Value>,
+    ) -> tokio::task::JoinHandle<Vec<(std::time::Instant, Value)>> {
+        tokio::spawn(async move {
+            let mut seen = Vec::new();
+            while let Some(record) = rx.recv().await {
+                seen.push((std::time::Instant::now(), record));
+            }
+            seen
+        })
+    }
+
+    #[tokio::test]
+    async fn builtin_progress_is_relayed_while_blender_runs_and_drained_after_it_exits() {
+        let tmp = tempfile::tempdir().expect("tempdir");
+        let blender = fake_blender(
+            tmp.path(),
+            r#"{"$aware-progress":{"phase":"render","done":1,"total":2,"message":"pass 1 of ?"}}"#,
+            r#"{"$aware-progress":{"phase":"render","done":2,"total":2,"message":"pass 1 of ?"}}"#,
+            2,
+            0,
+            r#"{"ok": true, "frames": 2, "outputs": [], "result": null}"#,
+        );
+        let channel = tmp.path().join("progress-1.jsonl");
+        let (tx, rx) = mpsc::channel::<Value>(64);
+        let collector = collect(rx);
+
+        let started = std::time::Instant::now();
+        let out = run_script(
+            "exec",
+            &blender,
+            &tmp.path().join("exec.py"),
+            &exec_args(),
+            Duration::from_secs(60),
+            BlenderProgress::Relay {
+                path: channel.clone(),
+                tx,
+            },
+        )
+        .await
+        .expect("the fake Blender frames a successful result");
+        let returned = std::time::Instant::now();
+        assert_eq!(out["frames"], json!(2), "{out}");
+
+        let seen = collector.await.expect("collector");
+        let done: Vec<u64> = seen
+            .iter()
+            .map(|(_, r)| r["done"].as_u64().unwrap_or(0))
+            .collect();
+        assert_eq!(done, vec![1, 2], "{seen:?}");
+        assert_eq!(seen[1].1["total"], json!(2));
+        // LIVE, not replayed at the end: the first record arrived while the producer still had a
+        // two-second pause ahead of it.
+        let lead = returned.duration_since(seen[0].0);
+        assert!(
+            lead >= Duration::from_millis(1_000),
+            "first record arrived only {lead:?} before the call returned (started {:?} earlier)",
+            returned.duration_since(started)
+        );
+        // The last record, written in the same breath as the exit, still arrived (final drain).
+        assert!(seen[1].0 <= returned + Duration::from_millis(5));
+    }
+
+    #[tokio::test]
+    async fn a_hung_blender_is_killed_on_timeout_and_its_progress_still_drains() {
+        let tmp = tempfile::tempdir().expect("tempdir");
+        let blender = fake_blender(
+            tmp.path(),
+            r#"{"$aware-progress":{"phase":"render","done":3,"total":240}}"#,
+            r#"{"$aware-progress":{"phase":"render","done":4,"total":240}}"#,
+            0,
+            120,
+            r#"{"ok": true}"#,
+        );
+        let (tx, rx) = mpsc::channel::<Value>(64);
+        let collector = collect(rx);
+
+        let started = std::time::Instant::now();
+        let err = run_script(
+            "exec",
+            &blender,
+            &tmp.path().join("exec.py"),
+            &exec_args(),
+            Duration::from_millis(2_500),
+            BlenderProgress::Relay {
+                path: tmp.path().join("progress-2.jsonl"),
+                tx,
+            },
+        )
+        .await
+        .expect_err("a wedged Blender must time out");
+        let elapsed = started.elapsed();
+        let text = err.to_string();
+        assert!(text.contains("timed out"), "{text}");
+        assert_eq!(err.exit_code(), 4, "{text}");
+        assert!(
+            elapsed < Duration::from_secs(30),
+            "the timeout did not fire promptly: {elapsed:?}"
+        );
+
+        let seen = collector.await.expect("collector");
+        assert_eq!(seen.len(), 1, "{seen:?}");
+        assert_eq!(seen[0].1["done"], json!(3), "{seen:?}");
+    }
+
+    #[tokio::test]
+    async fn a_caller_channel_is_passed_through_to_blender() {
+        // Passthrough (`aware agent invoke` under FloLess): Blender writes to the CALLER's file
+        // and nothing is relayed by us.
+        let tmp = tempfile::tempdir().expect("tempdir");
+        let blender = fake_blender(
+            tmp.path(),
+            r#"{"$aware-progress":{"phase":"render","done":1,"total":1}}"#,
+            r#"{"$aware-progress":{"phase":"render","done":1,"total":1}}"#,
+            0,
+            0,
+            r#"{"ok": true}"#,
+        );
+        let callers = tmp.path().join("callers-progress.jsonl");
+        run_script(
+            "exec",
+            &blender,
+            &tmp.path().join("exec.py"),
+            &exec_args(),
+            Duration::from_secs(60),
+            BlenderProgress::Passthrough(callers.clone()),
+        )
+        .await
+        .expect("passthrough run");
+        let written = std::fs::read_to_string(&callers).expect("the caller's channel was written");
+        assert_eq!(written.lines().count(), 2, "{written}");
+    }
+
     // ── staged inputs ──
 
     #[test]
@@ -1122,9 +1594,15 @@ mod tests {
     async fn end_to_end_scene_info_against_a_real_blender() {
         let ifc = std::env::var("AWARE_BLENDER_TEST_IFC")
             .expect("set AWARE_BLENDER_TEST_IFC to a fixture .ifc");
-        let out = run_blender_command("scene.info", &json!({ "ifc-path": ifc }), false, None)
-            .await
-            .expect("scene.info");
+        let out = run_blender_command(
+            "scene.info",
+            &json!({ "ifc-path": ifc }),
+            false,
+            None,
+            BlenderProgress::Off,
+        )
+        .await
+        .expect("scene.info");
         assert!(out["count"].as_u64().unwrap_or(0) > 0, "{out}");
     }
 }
diff --git a/cli/src/runtime/invoker.rs b/cli/src/runtime/invoker.rs
index 1d2442ad5..74baa3fa3 100644
--- a/cli/src/runtime/invoker.rs
+++ b/cli/src/runtime/invoker.rs
@@ -801,11 +801,7 @@ async fn relay_progress(
     path: PathBuf,
     tx: mpsc::Sender<Value>,
 ) -> std::io::Result<std::process::Output> {
-    let mut relay = Relay {
-        tail: Some(crate::runtime::progress::ProgressTail::new(&path)),
-        tx,
-        sent: 0,
-    };
+    let mut relay = crate::runtime::progress::Relay::new(&path, tx);
     let wait = child.wait_with_output();
     tokio::pin!(wait);
     let output = loop {
@@ -814,96 +810,11 @@ async fn relay_progress(
             _ = tokio::time::sleep(crate::runtime::progress::POLL_INTERVAL) => { relay.pump().await; }
         }
     };
-    // Drain to the END, not one slice of it. A poll reads at most `MAX_DRAIN_BYTES`, so a producer
-    // that wrote a burst of segments and exited immediately would otherwise lose everything past
-    // the first slice — including the `complete` record, which is the one a consumer waits for.
-    // Terminates: each pump either advances the cursor or reports there is nothing left, and the
-    // relay's record budget closes the channel regardless.
-    while relay.pump().await {}
+    // Drain to the END, not one slice of it — see `Relay::drain_to_end`.
+    relay.drain_to_end().await;
     output
 }
 
-/// The forwarding half of [`relay_progress`], with the record budget that keeps the trace bounded.
-struct Relay {
-    /// Dropped once the budget is spent, which also stops reading the file at all.
-    tail: Option<crate::runtime::progress::ProgressTail>,
-    tx: mpsc::Sender<Value>,
-    sent: usize,
-}
-
-impl Relay {
-    /// Records mirrored from one invocation before the runtime stops listening.
-    ///
-    /// The 8 KiB per-record cap bounds how big a record is; nothing bounded how MANY, and a
-    /// producer looping on the channel could hand the trace back the growth #402 removed — one
-    /// small record at a time. 10,000 is orders of magnitude past any real producer (PALM.ifc at
-    /// `batch-size: 100` publishes 33) and still leaves the trace a couple of megabytes at worst.
-    const MAX_RECORDS: usize = 10_000;
-
-    /// Bytes read from one invocation's channel before the runtime stops listening.
-    ///
-    /// The record budget counts what is MIRRORED, so it never fires on a channel whose lines are
-    /// all rejected — and the final drain reads to the end of the file. A bridge that accidentally
-    /// redirects an engine log (or a payload) to the channel would therefore be scanned in full
-    /// after its own process had already exited, adding delay to a run whose result was in hand.
-    /// This budget is on what is READ, so a channel nobody can use costs a bounded amount of time.
-    /// 16 MiB is far past any honest producer: 10,000 records of the maximum size would be 80 MiB,
-    /// but a real one publishes a few hundred bytes per record.
-    const MAX_CHANNEL_BYTES: u64 = 16 * 1024 * 1024;
-
-    /// One poll. Returns whether the cursor moved — i.e. whether it is worth polling again right
-    /// now, rather than waiting for the producer to write more.
-    async fn pump(&mut self) -> bool {
-        let Some(tail) = self.tail.as_mut() else {
-            return false;
-        };
-        let before = tail.consumed();
-        let records = tail.drain().await;
-        let advanced = tail.consumed() > before;
-        let over_budget = tail.consumed() > Self::MAX_CHANNEL_BYTES;
-        for record in records {
-            if self.sent >= Self::MAX_RECORDS {
-                self.suppress(format!(
-                    "stopped mirroring after {} records — the producer is publishing progress \
-                     faster than the trace may carry it",
-                    Self::MAX_RECORDS
-                ))
-                .await;
-                return false;
-            }
-            self.sent += 1;
-            if self.tx.send(record).await.is_err() {
-                // Nobody is listening any more; the child still owns the result.
-                self.tail = None;
-                return false;
-            }
-        }
-        if over_budget {
-            self.suppress(format!(
-                "stopped reading the progress channel after {} MiB — it is carrying something \
-                 other than progress records",
-                Self::MAX_CHANNEL_BYTES / (1024 * 1024)
-            ))
-            .await;
-            return false;
-        }
-        advanced
-    }
-
-    /// Close the channel, saying so in the trace rather than falling silent — a consumer that stops
-    /// receiving batches must be able to tell "the producer stopped" from "we stopped listening".
-    async fn suppress(&mut self, message: String) {
-        let _ = self
-            .tx
-            .send(serde_json::json!({
-                "phase": "progress-suppressed",
-                "message": message,
-            }))
-            .await;
-        self.tail = None;
-    }
-}
-
 #[async_trait]
 impl AgentInvoker for CliInvoker {
     async fn invoke_single(
@@ -2010,6 +1921,10 @@ pub(crate) struct BuiltinInvoker {
     /// so the `bpy` scripts are the approved bytes. `None` outside a run
     /// (`aware agent invoke`), which reads the installed copy.
     pub(crate) blender_root: Option<PathBuf>,
+    /// Hand a caller-set `AWARE_PROGRESS_FILE` through to a spawned producer (#692). True only for
+    /// `aware agent invoke`, where the caller asked for the channel and tails it itself; a run
+    /// owns its channels and never forwards whatever the launching shell happened to export.
+    pub(crate) inherit_progress_env: bool,
 }
 
 #[async_trait]
@@ -2036,14 +1951,22 @@ impl AgentInvoker for BuiltinInvoker {
             // The `blender` agent is the one builtin that drives an EXTERNAL process (headless
             // Blender on the agent's own `bpy` scripts) — see `render::blender` for why it is a
             // builtin and not a bridge. Matched on the agent alone so an unknown command gets that
-            // module's named error, which lists the five commands it does serve, rather than the
-            // generic dispatch message below.
+            // module's named error, which lists the commands it does serve, rather than the
+            // generic dispatch message below. Progress here is only ever the caller's own
+            // channel (`aware agent invoke`); a run relays it through
+            // `DispatchInvoker::invoke_single_progress_record_safe` instead.
             ("blender", command) => {
+                let progress = if self.inherit_progress_env {
+                    crate::render::blender::BlenderProgress::from_caller_env()
+                } else {
+                    crate::render::blender::BlenderProgress::Off
+                };
                 crate::render::blender::run_blender_command(
                     command,
                     &args,
                     self.dry_run,
                     self.blender_root.as_deref(),
+                    progress,
                 )
                 .await
             }
@@ -3532,6 +3455,7 @@ impl AgentInvoker for DispatchInvoker {
                 BuiltinInvoker {
                     dry_run: self.preview,
                     blender_root: self.builtin_blender_root(agent)?,
+                    inherit_progress_env: false,
                 }
                 .invoke_single(agent, command, args)
                 .await
@@ -3586,6 +3510,25 @@ impl AgentInvoker for DispatchInvoker {
                 )
                 .await
             }
+            // The one builtin that spawns a producer (#692): headless Blender gets the same
+            // run-owned channel a CLI bridge gets, relayed from inside its own wait loop.
+            TransportKind::Builtin if agent == "blender" => {
+                let progress = match (&self.artifact_dir, progress) {
+                    (Some(dir), Some(tx)) => crate::render::blender::BlenderProgress::Relay {
+                        path: crate::runtime::progress::channel_path(dir),
+                        tx,
+                    },
+                    _ => crate::render::blender::BlenderProgress::Off,
+                };
+                crate::render::blender::run_blender_command(
+                    command,
+                    &args,
+                    self.preview,
+                    self.builtin_blender_root(agent)?.as_deref(),
+                    progress,
+                )
+                .await
+            }
             _ => {
                 self.invoke_single_record_safe(agent, command, args, record_args)
                     .await
@@ -3637,6 +3580,7 @@ impl AgentInvoker for DispatchInvoker {
                 BuiltinInvoker {
                     dry_run: self.preview,
                     blender_root: self.builtin_blender_root(agent)?,
+                    inherit_progress_env: false,
                 }
                 .invoke_stream(agent, command, args)
                 .await
@@ -3649,134 +3593,6 @@ impl AgentInvoker for DispatchInvoker {
 mod cli_invoker_tests {
     use super::*;
 
-    #[tokio::test]
-    async fn the_final_drain_delivers_everything_a_producer_wrote_before_exiting() {
-        // A poll reads a bounded slice, so a producer that wrote a burst of segment announcements
-        // and exited immediately has more than one slice waiting when the child is reaped. Stopping
-        // after one would lose the later segments AND the `complete` record — the one a consumer
-        // waits for — which is exactly the silence this channel exists to remove.
-        let tmp = tempfile::tempdir().unwrap();
-        let path = tmp.path().join("progress.jsonl");
-        let mut body = String::new();
-        let mut written = 0;
-        while body.len() < 300 * 1024 {
-            body.push_str(&format!(
-                "{{\"$aware-progress\":{{\"phase\":\"batch\",\"seq\":{written}}}}}\n"
-            ));
-            written += 1;
-        }
-        body.push_str("{\"$aware-progress\":{\"phase\":\"complete\"}}\n");
-        tokio::fs::write(&path, body).await.unwrap();
-
-        let (tx, mut rx) = mpsc::channel::<Value>(64);
-        let collector = tokio::spawn(async move {
-            let mut seen = Vec::new();
-            while let Some(record) = rx.recv().await {
-                seen.push(record);
-            }
-            seen
-        });
-        let mut relay = Relay {
-            tail: Some(crate::runtime::progress::ProgressTail::new(&path)),
-            tx,
-            sent: 0,
-        };
-        let mut pumps = 0;
-        while relay.pump().await {
-            pumps += 1;
-        }
-        drop(relay);
-
-        let seen = collector.await.unwrap();
-        assert!(
-            pumps > 1,
-            "the burst fitted in one poll — the test proves nothing"
-        );
-        assert_eq!(seen.len(), written + 1);
-        assert_eq!(seen.last().unwrap()["phase"], "complete");
-    }
-
-    #[tokio::test]
-    async fn a_channel_carrying_something_else_is_abandoned_not_scanned_whole() {
-        // The record budget counts what is mirrored, so a channel whose every line is rejected
-        // never trips it — and the drain after the child exits would read the file to its end. A
-        // bridge that redirected an engine log here would delay a run whose result was already in
-        // hand, so the READ is budgeted too.
-        let tmp = tempfile::tempdir().unwrap();
-        let path = tmp.path().join("progress.jsonl");
-        let noise = "web-ifc: loading geometry, nothing to do with progress\n".repeat(400_000);
-        assert!(noise.len() as u64 > Relay::MAX_CHANNEL_BYTES);
-        tokio::fs::write(&path, noise).await.unwrap();
-
-        let (tx, mut rx) = mpsc::channel::<Value>(64);
-        let collector = tokio::spawn(async move {
-            let mut seen = Vec::new();
-            while let Some(record) = rx.recv().await {
-                seen.push(record);
-            }
-            seen
-        });
-        let mut relay = Relay {
-            tail: Some(crate::runtime::progress::ProgressTail::new(&path)),
-            tx,
-            sent: 0,
-        };
-        let mut read = 0;
-        while relay.pump().await {
-            read = relay.tail.as_ref().map(|t| t.consumed()).unwrap_or(read);
-        }
-        assert!(relay.tail.is_none(), "the relay kept reading the noise");
-        drop(relay);
-
-        let seen = collector.await.unwrap();
-        assert_eq!(seen.len(), 1, "expected only the suppression notice");
-        assert_eq!(seen[0]["phase"], "progress-suppressed");
-        assert!(
-            read <= Relay::MAX_CHANNEL_BYTES + crate::runtime::progress::MAX_RECORD_BYTES as u64,
-            "read {read} bytes of a channel it had already given up on"
-        );
-    }
-
-    #[tokio::test]
-    async fn the_relay_stops_mirroring_a_flood_and_says_that_it_did() {
-        // The per-record cap bounds how big a record is; this bounds how many. Without it a
-        // producer looping on the channel puts unbounded growth back into the trace one small
-        // record at a time — the exact property #402 exists to hold.
-        let tmp = tempfile::tempdir().unwrap();
-        let path = tmp.path().join("progress.jsonl");
-        let mut body = String::new();
-        for seq in 0..(Relay::MAX_RECORDS + 50) {
-            body.push_str(&format!(
-                "{{\"$aware-progress\":{{\"phase\":\"batch\",\"seq\":{seq}}}}}\n"
-            ));
-        }
-        tokio::fs::write(&path, body).await.unwrap();
-
-        let (tx, mut rx) = mpsc::channel::<Value>(64);
-        let collector = tokio::spawn(async move {
-            let mut seen = Vec::new();
-            while let Some(record) = rx.recv().await {
-                seen.push(record);
-            }
-            seen
-        });
-        let mut relay = Relay {
-            tail: Some(crate::runtime::progress::ProgressTail::new(&path)),
-            tx,
-            sent: 0,
-        };
-        while relay.pump().await {}
-        // The channel is closed for good: the runtime has stopped reading the file entirely, so a
-        // producer cannot keep it busy after the budget is spent.
-        assert!(relay.tail.is_none(), "the relay kept the channel open");
-        assert!(!relay.pump().await);
-        drop(relay);
-
-        let seen = collector.await.unwrap();
-        assert_eq!(seen.len(), Relay::MAX_RECORDS + 1);
-        assert_eq!(seen[Relay::MAX_RECORDS]["phase"], "progress-suppressed");
-    }
-
     #[test]
     fn resolve_cli_binary_uses_installed_bridge_path() {
         let tmp = tempfile::tempdir().unwrap();
@@ -5749,6 +5565,7 @@ mod builtin_invoker_tests {
         let err = BuiltinInvoker {
             dry_run: false,
             blender_root: None,
+            inherit_progress_env: false,
         }
         .invoke_stream("html-report", "render", json!({}))
         .await
@@ -5761,6 +5578,7 @@ mod builtin_invoker_tests {
         let err = BuiltinInvoker {
             dry_run: false,
             blender_root: None,
+            inherit_progress_env: false,
         }
         .invoke_single("html-report", "nope", json!({}))
         .await
diff --git a/cli/src/runtime/progress.rs b/cli/src/runtime/progress.rs
index c74b2485e..731a1080d 100644
--- a/cli/src/runtime/progress.rs
+++ b/cli/src/runtime/progress.rs
@@ -25,6 +25,7 @@
 use std::path::{Path, PathBuf};
 
 use serde_json::Value;
+use tokio::sync::mpsc;
 
 /// The wrapper key a producer's record must carry. Deliberately the same `$aware-` namespace as
 /// `$aware-artifact` (#402): both are runtime protocol inside an otherwise agent-owned document.
@@ -194,11 +195,233 @@ pub fn channel_path(artifact_dir: &Path) -> PathBuf {
     artifact_dir.join(format!("progress-{}.jsonl", uuid::Uuid::new_v4()))
 }
 
+/// The forwarding half of a progress relay, with the record budget that keeps the trace bounded.
+///
+/// Shared by every transport that spawns a producer (#405, #692): the CLI transport drives it
+/// beside `wait_with_output`, and the builtin `blender` transport drives it from INSIDE its own
+/// pipe-draining, timeout-and-kill loop — the pump is the shared part, the wait is not, because
+/// each transport owns how its child is waited on and killed.
+pub struct Relay {
+    /// Dropped once the budget is spent, which also stops reading the file at all.
+    tail: Option<ProgressTail>,
+    tx: mpsc::Sender<Value>,
+    sent: usize,
+}
+
+impl Relay {
+    /// A relay that tails `path` and forwards each record to `tx`.
+    pub fn new(path: impl Into<PathBuf>, tx: mpsc::Sender<Value>) -> Self {
+        Self {
+            tail: Some(ProgressTail::new(path)),
+            tx,
+            sent: 0,
+        }
+    }
+
+    /// Pump until nothing new is waiting — the drain after the producer has exited.
+    ///
+    /// Drains to the END, not one slice of it. A poll reads at most `MAX_DRAIN_BYTES`, so a
+    /// producer that wrote a burst of segments and exited immediately would otherwise lose
+    /// everything past the first slice — including the `complete` record, which is the one a
+    /// consumer waits for. Terminates: each pump either advances the cursor or reports there is
+    /// nothing left, and the relay's record budget closes the channel regardless.
+    pub async fn drain_to_end(&mut self) {
+        while self.pump().await {}
+    }
+
+    /// Records mirrored from one invocation before the runtime stops listening.
+    ///
+    /// The 8 KiB per-record cap bounds how big a record is; nothing bounded how MANY, and a
+    /// producer looping on the channel could hand the trace back the growth #402 removed — one
+    /// small record at a time. 10,000 is orders of magnitude past any real producer (PALM.ifc at
+    /// `batch-size: 100` publishes 33) and still leaves the trace a couple of megabytes at worst.
+    pub const MAX_RECORDS: usize = 10_000;
+
+    /// Bytes read from one invocation's channel before the runtime stops listening.
+    ///
+    /// The record budget counts what is MIRRORED, so it never fires on a channel whose lines are
+    /// all rejected — and the final drain reads to the end of the file. A bridge that accidentally
+    /// redirects an engine log (or a payload) to the channel would therefore be scanned in full
+    /// after its own process had already exited, adding delay to a run whose result was in hand.
+    /// This budget is on what is READ, so a channel nobody can use costs a bounded amount of time.
+    /// 16 MiB is far past any honest producer: 10,000 records of the maximum size would be 80 MiB,
+    /// but a real one publishes a few hundred bytes per record.
+    pub const MAX_CHANNEL_BYTES: u64 = 16 * 1024 * 1024;
+
+    /// One poll. Returns whether the cursor moved — i.e. whether it is worth polling again right
+    /// now, rather than waiting for the producer to write more.
+    pub async fn pump(&mut self) -> bool {
+        let Some(tail) = self.tail.as_mut() else {
+            return false;
+        };
+        let before = tail.consumed();
+        let records = tail.drain().await;
+        let advanced = tail.consumed() > before;
+        let over_budget = tail.consumed() > Self::MAX_CHANNEL_BYTES;
+        for record in records {
+            if self.sent >= Self::MAX_RECORDS {
+                self.suppress(format!(
+                    "stopped mirroring after {} records — the producer is publishing progress \
+                     faster than the trace may carry it",
+                    Self::MAX_RECORDS
+                ))
+                .await;
+                return false;
+            }
+            self.sent += 1;
+            if self.tx.send(record).await.is_err() {
+                // Nobody is listening any more; the child still owns the result.
+                self.tail = None;
+                return false;
+            }
+        }
+        if over_budget {
+            self.suppress(format!(
+                "stopped reading the progress channel after {} MiB — it is carrying something \
+                 other than progress records",
+                Self::MAX_CHANNEL_BYTES / (1024 * 1024)
+            ))
+            .await;
+            return false;
+        }
+        advanced
+    }
+
+    /// Close the channel, saying so in the trace rather than falling silent — a consumer that stops
+    /// receiving batches must be able to tell "the producer stopped" from "we stopped listening".
+    async fn suppress(&mut self, message: String) {
+        let _ = self
+            .tx
+            .send(serde_json::json!({
+                "phase": "progress-suppressed",
+                "message": message,
+            }))
+            .await;
+        self.tail = None;
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
     use serde_json::json;
 
+    #[tokio::test]
+    async fn the_final_drain_delivers_everything_a_producer_wrote_before_exiting() {
+        // A poll reads a bounded slice, so a producer that wrote a burst of segment announcements
+        // and exited immediately has more than one slice waiting when the child is reaped. Stopping
+        // after one would lose the later segments AND the `complete` record — the one a consumer
+        // waits for — which is exactly the silence this channel exists to remove.
+        let tmp = tempfile::tempdir().unwrap();
+        let path = tmp.path().join("progress.jsonl");
+        let mut body = String::new();
+        let mut written = 0;
+        while body.len() < 300 * 1024 {
+            body.push_str(&format!(
+                "{{\"$aware-progress\":{{\"phase\":\"batch\",\"seq\":{written}}}}}\n"
+            ));
+            written += 1;
+        }
+        body.push_str("{\"$aware-progress\":{\"phase\":\"complete\"}}\n");
+        tokio::fs::write(&path, body).await.unwrap();
+
+        let (tx, mut rx) = mpsc::channel::<Value>(64);
+        let collector = tokio::spawn(async move {
+            let mut seen = Vec::new();
+            while let Some(record) = rx.recv().await {
+                seen.push(record);
+            }
+            seen
+        });
+        let mut relay = Relay::new(&path, tx);
+        let mut pumps = 0;
+        while relay.pump().await {
+            pumps += 1;
+        }
+        drop(relay);
+
+        let seen = collector.await.unwrap();
+        assert!(
+            pumps > 1,
+            "the burst fitted in one poll — the test proves nothing"
+        );
+        assert_eq!(seen.len(), written + 1);
+        assert_eq!(seen.last().unwrap()["phase"], "complete");
+    }
+
+    #[tokio::test]
+    async fn a_channel_carrying_something_else_is_abandoned_not_scanned_whole() {
+        // The record budget counts what is mirrored, so a channel whose every line is rejected
+        // never trips it — and the drain after the child exits would read the file to its end. A
+        // bridge that redirected an engine log here would delay a run whose result was already in
+        // hand, so the READ is budgeted too.
+        let tmp = tempfile::tempdir().unwrap();
+        let path = tmp.path().join("progress.jsonl");
+        let noise = "web-ifc: loading geometry, nothing to do with progress\n".repeat(400_000);
+        assert!(noise.len() as u64 > Relay::MAX_CHANNEL_BYTES);
+        tokio::fs::write(&path, noise).await.unwrap();
+
+        let (tx, mut rx) = mpsc::channel::<Value>(64);
+        let collector = tokio::spawn(async move {
+            let mut seen = Vec::new();
+            while let Some(record) = rx.recv().await {
+                seen.push(record);
+            }
+            seen
+        });
+        let mut relay = Relay::new(&path, tx);
+        let mut read = 0;
+        while relay.pump().await {
+            read = relay.tail.as_ref().map(|t| t.consumed()).unwrap_or(read);
+        }
+        assert!(relay.tail.is_none(), "the relay kept reading the noise");
+        drop(relay);
+
+        let seen = collector.await.unwrap();
+        assert_eq!(seen.len(), 1, "expected only the suppression notice");
+        assert_eq!(seen[0]["phase"], "progress-suppressed");
+        assert!(
+            read <= Relay::MAX_CHANNEL_BYTES + MAX_RECORD_BYTES as u64,
+            "read {read} bytes of a channel it had already given up on"
+        );
+    }
+
+    #[tokio::test]
+    async fn the_relay_stops_mirroring_a_flood_and_says_that_it_did() {
+        // The per-record cap bounds how big a record is; this bounds how many. Without it a
+        // producer looping on the channel puts unbounded growth back into the trace one small
+        // record at a time — the exact property #402 exists to hold.
+        let tmp = tempfile::tempdir().unwrap();
+        let path = tmp.path().join("progress.jsonl");
+        let mut body = String::new();
+        for seq in 0..(Relay::MAX_RECORDS + 50) {
+            body.push_str(&format!(
+                "{{\"$aware-progress\":{{\"phase\":\"batch\",\"seq\":{seq}}}}}\n"
+            ));
+        }
+        tokio::fs::write(&path, body).await.unwrap();
+
+        let (tx, mut rx) = mpsc::channel::<Value>(64);
+        let collector = tokio::spawn(async move {
+            let mut seen = Vec::new();
+            while let Some(record) = rx.recv().await {
+                seen.push(record);
+            }
+            seen
+        });
+        let mut relay = Relay::new(&path, tx);
+        while relay.pump().await {}
+        // The channel is closed for good: the runtime has stopped reading the file entirely, so a
+        // producer cannot keep it busy after the budget is spent.
+        assert!(relay.tail.is_none(), "the relay kept the channel open");
+        assert!(!relay.pump().await);
+        drop(relay);
+
+        let seen = collector.await.unwrap();
+        assert_eq!(seen.len(), Relay::MAX_RECORDS + 1);
+        assert_eq!(seen[Relay::MAX_RECORDS]["phase"], "progress-suppressed");
+    }
+
     #[test]
     fn accepts_a_well_formed_record_and_returns_its_body() {
         let body =

From 1e5ab1e42b8e906b6b60c79c1b985e5412bb1513 Mon Sep 17 00:00:00 2001
From: Pawel Lisowski <pawellisowski@o2.pl>
Date: Mon, 12 Oct 2026 09:28:32 +0200
Subject: [PATCH 03/17] feat(blender): exec command runs author-time bpy code
 with live frame progress (agent 0.2.0, #692)

FloLess users want animations of their own model -- construction sequences,
fly-throughs, sun studies -- which the five fixed recipes cannot make. exec
follows the tekla/rhino exec model: the terminal AI writes bpy once at
authoring time, the code is pinned in the approved lock (`code` is
literal: true), and AWARE runs it unchanged on every run.

- manifest 0.1.0 -> 0.2.0: `exec` is mode: write and NOT mode-overridable
  (a read-mode node would run for real under --dry-run); outputs are
  {result, outputs, frames}; exec-bpy.md joins the skills.
- exec.py compiles the code first (a syntax error fails before any scene
  work), prepares one of three starting scenes (ifc-path: factory-empty +
  import + preset look + lighting; blend-path: opened as-is; neither:
  factory-empty), then calls run(ctx). Exceptions are exec-error with the
  line and an authored-only traceback; a result over 256 KiB is
  result-too-large.
- _exec_ctx.py: args, output_dir, scene, elements(), frame(), apply_look(),
  environment(), ground(), progress(), plan_passes(), render_still(),
  render_animation(), add_output(). Outputs are an explicit receipt: each
  entry verified (regular, non-empty, real path inside output_dir) or listed
  verified:false with the reason -- no directory diffing.
- _progress.py: one bounded line per record, a no-op without the channel.
  Frames are counted only on render_write (measured once per written frame
  on 5.2; frame_change_post overcounts) and only on measured versions
  {(5,2)}; elsewhere phases only. Each render call is its own segment
  labelled "pass i of n"; >5,000 frames coalesce. render.still and
  render.turntable report through it too.
- 30-apps/_examples/model-to-construction-sequence.app with a safety block.
- Registry: blender 0.1.0 frozen at c1b293ffc (its bytes, digest unchanged)
  so main can move; publishing 0.2.0 is a follow-up once this lands. The
  example and plan-doc pins move to blender@0.2.x; stats synced.
- Tests: Python under real Blender 5.2 (test_exec.py, test_exec_ifc_scene.py)
  and cli/tests/blender_exec.rs (validate/compile refuse templated code;
  --dry-run never launches a stand-in AWARE_BLENDER).
---
 .../aeco/visualization/blender/manifest.yaml  |  84 +++-
 .../blender/scripts/_exec_ctx.py              | 272 +++++++++++++
 .../blender/scripts/_progress.py              | 181 +++++++++
 .../visualization/blender/scripts/exec.py     | 240 +++++++++++
 .../blender/scripts/render_still.py           |   8 +-
 .../blender/scripts/render_turntable.py       |   6 +-
 .../visualization/blender/skills/exec-bpy.md  | 329 +++++++++++++++
 .../visualization/blender/tests/test_exec.py  | 384 ++++++++++++++++++
 .../blender/tests/test_exec_ifc_scene.py      | 125 ++++++
 .../model-to-construction-sequence.app        |  97 +++++
 30-apps/_examples/model-to-renders.app        |   2 +-
 40-diagrams/substrate-playground.html         |   2 +-
 CLAUDE.md                                     |   6 +-
 README.md                                     |   2 +-
 cli/tests/app_list.rs                         |   3 +-
 cli/tests/blender_exec.rs                     | 172 ++++++++
 .../2026-07-22-blender-visualization-agent.md |   2 +-
 registry-index.json                           |   4 +-
 18 files changed, 1906 insertions(+), 13 deletions(-)
 create mode 100644 20-agents/aeco/visualization/blender/scripts/_exec_ctx.py
 create mode 100644 20-agents/aeco/visualization/blender/scripts/_progress.py
 create mode 100644 20-agents/aeco/visualization/blender/scripts/exec.py
 create mode 100644 20-agents/aeco/visualization/blender/skills/exec-bpy.md
 create mode 100644 20-agents/aeco/visualization/blender/tests/test_exec.py
 create mode 100644 20-agents/aeco/visualization/blender/tests/test_exec_ifc_scene.py
 create mode 100644 30-apps/_examples/model-to-construction-sequence.app
 create mode 100644 cli/tests/blender_exec.rs

diff --git a/20-agents/aeco/visualization/blender/manifest.yaml b/20-agents/aeco/visualization/blender/manifest.yaml
index a7b289b0b..a16571a66 100644
--- a/20-agents/aeco/visualization/blender/manifest.yaml
+++ b/20-agents/aeco/visualization/blender/manifest.yaml
@@ -1,5 +1,5 @@
 agent:        blender
-version:      0.1.0
+version:      0.2.0
 display-name: Blender
 description: |
   The first visualization agent in the substrate that renders with NO human in
@@ -12,6 +12,11 @@ description: |
   renderers in the box (EEVEE for drafts and turntables, Cycles for path-traced
   hero shots).
 
+  Beyond the fixed recipes, `exec` runs author-time `bpy` code -- a construction
+  sequence, a fly-through, a sun study -- written once when the workflow is
+  authored, pinned in the approved lock, and run unchanged on every run. Long
+  renders report per-frame progress while they work.
+
   Materials are assigned from what the IFC already states: product class plus
   associated material grade, with clay as a never-fail default. That is what
   makes the chain autonomous — nobody is there to click a material.
@@ -44,6 +49,10 @@ requires:
   filesystem:
     - read:  '*.ifc,*.blend'
     - write: '*.blend,*.png,*.mp4'
+    # `exec` runs author code that writes its renders into `output-dir`. Like
+    # tekla/rhino exec, Python writes are not sandboxed, so this is declared as
+    # broadly as it is -- the contract a person approves with the lock.
+    - write: any                 # `exec` only
 
 # Runtime built-in: the transport runs in-process in the `aware` runtime, spawning
 # `blender -b -P <script>.py -- @<inputs>.json` and recovering the framed result
@@ -334,7 +343,80 @@ commands:
         excluded:       object  # ifc-path branch only
         excluded-count: number  # ifc-path branch only
 
+  exec:
+    lifecycle: single
+    category: curated
+    # Write, and NOT mode-overridable: this runs arbitrary Python, and a node
+    # allowed to declare `mode: read` would be executed for real under
+    # `--dry-run`. A preview of an animation must never render one.
+    mode: write
+    description: |
+      Run author-time `bpy` code headlessly -- the way to make anything the
+      fixed recipes do not: a construction sequence, a camera fly-through, a
+      sun study, an exploded view, a highlight of changed elements.
+
+      The code is written once, when the workflow is authored, and lives in the
+      workflow file itself, so the approved lock pins exactly what runs; it is
+      never supplied at run time (a templated `code` is refused). Run-time data
+      travels in `args` instead.
+
+      Before the code runs, the scene is prepared: an `ifc-path` is imported
+      (with IFC class, material, storey, GUID and name on every object) and
+      given the `preset` look; a `blend-path` is opened as-is; with neither, the
+      code starts from an empty scene. The code defines `run(ctx)` and returns
+      anything JSON can carry. `ctx` offers the model's elements, camera
+      framing, looks, lighting, and `render_still` / `render_animation`, which
+      report per-frame progress while they render and record each file they
+      write in a verified receipt. See exec-bpy.md.
+    inputs:
+      code:
+        type: string
+        required: true
+        literal: true
+        description: |
+          Python source defining `run(ctx)`. Must be written out in the
+          workflow -- template syntax here is refused at validate, compile and
+          run, because a template would run code supplied after approval. Put
+          data in `args`.
+      args:
+        type: object
+        required: false
+        description: |
+          Free-form, templatable data the code reads as `ctx.args` -- storey
+          order, element GUIDs, frame counts. Data, never code.
+      ifc-path:
+        type: string
+        required: false
+        description: IFC to import and stage before the code runs; mutually exclusive with `blend-path`.
+      blend-path:
+        type: string
+        required: false
+        description: Staged .blend to open before the code runs; mutually exclusive with `ifc-path`.
+      preset:
+        type: enum
+        values: [clay, realistic, section-style]
+        default: realistic
+        description: Look applied when staging from `ifc-path`.
+      output-dir:
+        type: string
+        required: true
+        description: |
+          Where the code writes its renders (`ctx.output_dir`). Only files
+          inside it can be recorded as verified outputs.
+      timeout-seconds:
+        type: number
+        description: |
+          Process budget, default 1800. Set it from the render estimate --
+          frames times seconds per frame -- with headroom.
+    outputs:
+      type: single
+      schema:
+        result:  any     # run(ctx)'s JSON-serialisable return, at most 256 KiB
+        outputs: array   # [{path, kind: video|image|blend|file, size-bytes, frames?, verified, reason?}]
+        frames:  number  # total frames rendered by ctx.render_animation calls
+
 skills:
   - headless-rendering.md
   - ifc-import-ifcopenshell.md
   - look-presets.md
+  - exec-bpy.md
diff --git a/20-agents/aeco/visualization/blender/scripts/_exec_ctx.py b/20-agents/aeco/visualization/blender/scripts/_exec_ctx.py
new file mode 100644
index 000000000..b02240981
--- /dev/null
+++ b/20-agents/aeco/visualization/blender/scripts/_exec_ctx.py
@@ -0,0 +1,272 @@
+"""`ctx` -- what `exec` hands the author's `run(ctx)` (#692).
+
+The author writes `bpy` code once, when the workflow is authored; AWARE runs it
+unchanged on every run. `ctx` is the stable surface that code leans on, so it
+does not have to re-derive the agent's own staging (IFC properties, camera fit,
+looks, lighting) or the bookkeeping a long render needs:
+
+  ctx.args, ctx.output_dir, ctx.scene
+  ctx.elements()                 -> [(obj, {guid, name, class, material, storey})]
+  ctx.frame(direction)           camera fitted to the model (`_framing`)
+  ctx.apply_look(preset)         IFC-driven materials (`_looks`)
+  ctx.environment(name)          HDRI lighting + key light (`_stage`)
+  ctx.ground(on)                 the fading floor (`_stage`)
+  ctx.progress(phase, done, total, message)
+  ctx.plan_passes(n)             say how many render calls are coming
+  ctx.render_still(path, quality)
+  ctx.render_animation(path, quality)
+  ctx.add_output(path, kind)
+
+Outputs are an EXPLICIT receipt, never a directory diff. Only what a `render_*`
+call wrote or `add_output` registered is listed; each entry is verified (the file
+exists, is a regular non-empty file, and its real path is inside `output_dir`).
+An entry that fails is still listed, with `verified: false` and the reason --
+never silently dropped, and never passed off as good.
+"""
+
+from __future__ import annotations
+
+import os
+import time
+
+import bpy
+
+import _framing
+import _ifc_import
+import _looks
+import _progress
+import _result
+import _stage
+
+KINDS = ("video", "image", "blend", "file")
+QUALITIES = ("draft", "production")
+
+
+def _same_or_inside(path: str, root: str) -> bool:
+    """Whether real path `path` is `root` or lies beneath it (case-folded on Windows)."""
+    path_n, root_n = os.path.normcase(path), os.path.normcase(root)
+    try:
+        return os.path.commonpath([path_n, root_n]) == root_n
+    except ValueError:  # different drives on Windows
+        return False
+
+
+def eevee_engine() -> str:
+    """EEVEE's identifier on this Blender (renamed BLENDER_EEVEE_NEXT in 4.2, back in 5.x)."""
+    identifiers = {
+        item.identifier
+        for item in bpy.types.RenderSettings.bl_rna.properties["engine"].enum_items
+    }
+    for candidate in ("BLENDER_EEVEE_NEXT", "BLENDER_EEVEE"):
+        if candidate in identifiers:
+            return candidate
+    raise _result.AwareBlenderError(
+        _result.ERR_RENDER_FAILED,
+        f"no EEVEE engine in this Blender; available: {sorted(identifiers)}",
+    )
+
+
+class ExecContext:
+    """The object passed to `run(ctx)`."""
+
+    def __init__(self, args: dict, output_dir: str):
+        self.args = dict(args or {})
+        os.makedirs(output_dir, exist_ok=True)
+        # The REAL path, so the inside-check below compares like with like even
+        # when output-dir itself is reached through a link.
+        self.output_dir = os.path.realpath(output_dir)
+        self.outputs: list[dict] = []
+        self.frames = 0
+        self._planned_passes: int | None = None
+        self._pass = 0
+
+    # -- the scene -----------------------------------------------------------
+
+    @property
+    def scene(self):
+        return bpy.context.scene
+
+    def elements(self) -> list:
+        """Every imported IFC element with the properties staged on it.
+
+        Staging helpers (the ground plane) are not elements and are skipped.
+        """
+        found = []
+        for obj in bpy.data.objects:
+            if obj.get(_ifc_import.PROP_HELPER):
+                continue
+            guid = obj.get(_ifc_import.PROP_GUID)
+            ifc_class = obj.get(_ifc_import.PROP_CLASS)
+            if not guid and not ifc_class:
+                continue
+            found.append(
+                (
+                    obj,
+                    {
+                        "guid": str(guid or ""),
+                        "name": str(obj.get(_ifc_import.PROP_NAME, "") or ""),
+                        "class": str(ifc_class or ""),
+                        "material": str(obj.get(_ifc_import.PROP_MATERIAL, "") or ""),
+                        "storey": str(obj.get(_ifc_import.PROP_STOREY, "") or ""),
+                    },
+                )
+            )
+        return found
+
+    def frame(self, direction: str = "hero") -> dict:
+        """Fit the scene camera (created if missing) to the model; returns the receipt."""
+        if direction not in _framing.DIRECTIONS:
+            raise ValueError(
+                f"unknown direction `{direction}`; expected one of {sorted(_framing.DIRECTIONS)}"
+            )
+        camera = _framing.ensure_camera()
+        receipt = _framing.frame_camera(camera, direction)
+        bpy.context.view_layer.update()
+        return receipt
+
+    def apply_look(self, preset: str = "realistic") -> dict:
+        return _looks.apply_look(preset)
+
+    def environment(self, name: str = _stage.DEFAULT_ENVIRONMENT) -> dict:
+        """Light the scene with a bundled HDRI (or a path, or `gradient`) plus a key light."""
+        receipt = _stage.setup_world(name)
+        _stage.setup_key_light()
+        return receipt
+
+    def ground(self, on: bool = True) -> dict:
+        return _stage.setup_ground(bool(on))
+
+    # -- progress ------------------------------------------------------------
+
+    def progress(self, phase, done=None, total=None, message=None) -> None:
+        _progress.emit(phase, done, total, message)
+
+    def plan_passes(self, count: int) -> None:
+        """Declare how many `render_*` calls follow, so each is labelled `pass i of n`."""
+        self._planned_passes = max(1, int(count))
+
+    def _next_pass_label(self) -> str:
+        self._pass += 1
+        planned = self._planned_passes if self._planned_passes else "?"
+        return f"pass {self._pass} of {planned}"
+
+    # -- outputs ---------------------------------------------------------------
+
+    def _resolve(self, path: str) -> str:
+        path = os.fspath(path)
+        if not os.path.isabs(path):
+            path = os.path.join(self.output_dir, path)
+        return os.path.abspath(path)
+
+    def _verified(self, path: str, kind: str, **extra) -> dict:
+        """Check one file and append its receipt entry."""
+        entry = {"path": os.path.abspath(path), "kind": kind}
+        entry.update(extra)
+        reason = None
+        if kind not in KINDS:
+            reason = f"unknown kind `{kind}`; expected one of {list(KINDS)}"
+        elif os.path.islink(path):
+            reason = "is a symbolic link, not a file the code wrote"
+        elif not os.path.exists(path):
+            reason = "was not written"
+        elif not os.path.isfile(path):
+            reason = "is not a regular file"
+        else:
+            real = os.path.realpath(path)
+            entry["path"] = real
+            size = os.path.getsize(real)
+            entry["size-bytes"] = size
+            if not _same_or_inside(real, self.output_dir):
+                reason = f"is outside output-dir ({self.output_dir})"
+            elif size <= 0:
+                reason = "is empty"
+        entry["verified"] = reason is None
+        if reason is not None:
+            entry["reason"] = reason
+        self.outputs.append(entry)
+        return entry
+
+    def add_output(self, path: str, kind: str = "file") -> dict:
+        """Register a file the code wrote itself; verified exactly like a render."""
+        return self._verified(self._resolve(path), kind)
+
+    # -- rendering -------------------------------------------------------------
+
+    def _engine(self, quality: str, samples) -> None:
+        if quality not in QUALITIES:
+            raise ValueError(f"unknown quality `{quality}`; expected draft or production")
+        scene = self.scene
+        if quality == "production":
+            scene.render.engine = "CYCLES"
+            if samples:
+                scene.cycles.samples = int(samples)
+        else:
+            scene.render.engine = eevee_engine()
+            if samples and hasattr(scene, "eevee") and hasattr(scene.eevee, "taa_render_samples"):
+                scene.eevee.taa_render_samples = int(samples)
+            _stage.tune_eevee(scene)
+
+    def _ensure_camera(self) -> None:
+        if self.scene.camera is None:
+            self.frame("hero")
+
+    def render_still(self, path: str, quality: str = "draft", samples=None) -> dict:
+        """Render the current frame to a PNG at `path` (relative paths land in output_dir)."""
+        target = self._resolve(path)
+        self._engine(quality, samples)
+        self._ensure_camera()
+        scene = self.scene
+        if hasattr(scene.render.image_settings, "media_type"):
+            scene.render.image_settings.media_type = "IMAGE"
+        scene.render.image_settings.file_format = "PNG"
+        scene.render.filepath = target
+        os.makedirs(os.path.dirname(target), exist_ok=True)
+        with _progress.FrameCounter(1, self._next_pass_label()):
+            bpy.ops.render.render(write_still=True)
+        return self._verified(target, "image")
+
+    def render_animation(self, path: str, quality: str = "draft", samples=None) -> dict:
+        """Render the scene's frame range to an H.264 MP4 at `path`.
+
+        Progress: one `render` record per frame actually written (counted on
+        `render_write`), as its own segment labelled `pass i of n`.
+        """
+        target = self._resolve(path)
+        self._engine(quality, samples)
+        self._ensure_camera()
+        scene = self.scene
+        # Blender 5.x gates FFMPEG behind `media_type = VIDEO`; assigning it
+        # without the switch raises. Older builds have no such property.
+        if hasattr(scene.render.image_settings, "media_type"):
+            scene.render.image_settings.media_type = "VIDEO"
+        scene.render.image_settings.file_format = "FFMPEG"
+        scene.render.ffmpeg.format = "MPEG4"
+        scene.render.ffmpeg.codec = "H264"
+        scene.render.ffmpeg.constant_rate_factor = "MEDIUM"
+        scene.render.ffmpeg.ffmpeg_preset = "GOOD"
+        scene.render.filepath = target
+        os.makedirs(os.path.dirname(target), exist_ok=True)
+
+        step = max(1, int(scene.frame_step))
+        total = max(0, (scene.frame_end - scene.frame_start) // step + 1)
+        started = time.time()
+        with _progress.FrameCounter(total, self._next_pass_label()) as counter:
+            bpy.ops.render.render(animation=True)
+        self.frames += counter.done
+
+        # Blender may append the frame range to a container name; find what
+        # THIS render wrote (newer than its start), never an older file.
+        written = target
+        if not os.path.exists(written):
+            directory = os.path.dirname(target)
+            stem = os.path.splitext(os.path.basename(target))[0]
+            candidates = [
+                os.path.join(directory, name)
+                for name in os.listdir(directory)
+                if name.startswith(stem)
+                and name.lower().endswith(".mp4")
+                and os.path.getmtime(os.path.join(directory, name)) >= started - 1
+            ]
+            if candidates:
+                written = max(candidates, key=os.path.getmtime)
+        return self._verified(written, "video", frames=counter.done)
diff --git a/20-agents/aeco/visualization/blender/scripts/_progress.py b/20-agents/aeco/visualization/blender/scripts/_progress.py
new file mode 100644
index 000000000..972a5cd8e
--- /dev/null
+++ b/20-agents/aeco/visualization/blender/scripts/_progress.py
@@ -0,0 +1,181 @@
+"""Progress records for a long render (#405 parity on the builtin transport, #692).
+
+A render can run for minutes or hours, and from the outside a 40-minute animation
+looks exactly like a hang. So while a command works it appends one JSON line per
+event to the file named by `AWARE_PROGRESS_FILE`:
+
+    {"$aware-progress": {"phase": "render", "done": 3, "total": 8, "message": "pass 1 of ?"}}
+
+The runtime tails that file and mirrors each line into the run trace as a
+`node-progress` event. The channel is advisory: with the variable unset every
+call here is a no-op, and a write that fails is dropped rather than raised --
+progress must never be the reason a render fails.
+
+Frames are counted on `bpy.app.handlers.render_write` and nothing else. Measured
+on Blender 5.2.0 (EEVEE and Cycles, a 5-frame FFMPEG animation): `render_write`
+fires exactly once per frame written into the output; `render_post` fires before
+the write; `frame_change_post` fires an extra time after the job (6 for 5) and
+would claim a frame that was never written. Counted progress is enabled only on
+versions where that was measured (`COUNTED_VERSIONS`); anywhere else a render
+reports its phase with no `done`/`total`, so a consumer shows honest elapsed time
+instead of a bar that might lie. A version joins the set only by running the
+frame-count test (`tests/test_exec.py`) under it.
+
+Imports no `bpy` at module level, so the record writer is testable in plain
+Python; `FrameCounter` imports it when used.
+"""
+
+from __future__ import annotations
+
+import json
+import math
+import os
+
+ENV = "AWARE_PROGRESS_FILE"
+RECORD_KEY = "$aware-progress"
+
+# Mirrors `cli/src/runtime/progress.rs`: an over-long record is DROPPED by the
+# runtime, so it is kept under the cap here rather than sent and lost.
+MAX_RECORD_BYTES = 8 * 1024
+MAX_PHASE_CHARS = 64
+MAX_MESSAGE_CHARS = 512
+
+# The runtime stops mirroring after 10,000 records from one invocation. Above
+# this many frames a pass reports every ceil(total / COALESCE_ABOVE)-th frame
+# plus the last, so the cap is never why progress stops.
+COALESCE_ABOVE = 5_000
+
+# (major, minor) versions on which `render_write` was measured to fire once per
+# written frame. See the module docstring before adding one.
+COUNTED_VERSIONS = {(5, 2)}
+
+# The phases a consumer can expect, in the order a command passes through them.
+PHASES = ("import", "look", "setup", "render")
+
+
+def enabled() -> bool:
+    """Whether anything is listening -- i.e. the runtime handed us a channel."""
+    return bool(os.environ.get(ENV))
+
+
+def _truncate(text: str, limit: int) -> str:
+    return text if len(text) <= limit else text[: max(0, limit - 1)] + "…"
+
+
+def record(phase, done=None, total=None, message=None) -> dict:
+    """The record body for one event, already fitted to the runtime's limits."""
+    body = {"phase": _truncate(str(phase), MAX_PHASE_CHARS) or "progress"}
+    if done is not None:
+        body["done"] = int(done)
+    if total is not None:
+        body["total"] = int(total)
+    if message is not None:
+        body["message"] = _truncate(str(message), MAX_MESSAGE_CHARS)
+    return body
+
+
+def line(body: dict) -> str:
+    """One channel line for `body`, guaranteed under `MAX_RECORD_BYTES`."""
+    text = json.dumps({RECORD_KEY: body}, ensure_ascii=False)
+    while len(text.encode("utf-8")) > MAX_RECORD_BYTES and body.get("message"):
+        body = dict(body, message=_truncate(body["message"], len(body["message"]) // 2))
+        text = json.dumps({RECORD_KEY: body}, ensure_ascii=False)
+    return text
+
+
+def emit(phase, done=None, total=None, message=None) -> None:
+    """Append one record to the channel. A no-op without `AWARE_PROGRESS_FILE`."""
+    path = os.environ.get(ENV)
+    if not path:
+        return
+    text = line(record(phase, done, total, message))
+    try:
+        # Open-append-close per record: each line is flushed and on disk before the
+        # call returns, so the runtime's next poll sees it.
+        with open(path, "a", encoding="utf-8") as handle:
+            handle.write(text + "\n")
+    except OSError:
+        pass  # advisory channel: never fail a render over a progress write
+
+
+def counting_supported(version=None) -> bool:
+    """Whether frame counts are trustworthy on this Blender (see `COUNTED_VERSIONS`)."""
+    if version is None:
+        import bpy
+
+        version = bpy.app.version
+    return tuple(version[:2]) in COUNTED_VERSIONS
+
+
+def stride_for(total: int) -> int:
+    """Report every `stride`-th frame, so one pass never exceeds ~COALESCE_ABOVE records."""
+    return math.ceil(total / COALESCE_ABOVE) if total > COALESCE_ABOVE else 1
+
+
+class FrameCounter:
+    """One progress SEGMENT: a single `bpy.ops.render.render` call.
+
+    Each render call gets its own `done`/`total`, starting from 0, with a message
+    naming the pass. A cumulative count would make the bar jump backwards the
+    moment a second pass added its frames to the total; a new segment is a new
+    bar instead.
+
+    Use as a context manager around the render. Handlers are registered on entry
+    and always removed on exit, even when the render raises.
+    """
+
+    def __init__(self, total: int, label: str, counted: bool | None = None):
+        self.total = max(0, int(total))
+        self.label = label
+        self.counted = counting_supported() if counted is None else counted
+        self.stride = stride_for(self.total)
+        self.done = 0
+        self.completed = False
+        self.cancelled = False
+        self._handlers = []
+
+    def _on_write(self, *_args):
+        self.done += 1
+        if self.counted and (self.done % self.stride == 0 or self.done == self.total):
+            emit("render", self.done, self.total, self.label)
+
+    def _on_complete(self, *_args):
+        self.completed = True
+
+    def _on_cancel(self, *_args):
+        self.cancelled = True
+
+    def __enter__(self):
+        import bpy
+
+        # Plain closures, not bound methods: Blender keeps handler references in a
+        # C-level list and these must be removable by identity on exit.
+        def on_write(*args):
+            self._on_write(*args)
+
+        def on_complete(*args):
+            self._on_complete(*args)
+
+        def on_cancel(*args):
+            self._on_cancel(*args)
+
+        self._handlers = [
+            (bpy.app.handlers.render_write, on_write),
+            (bpy.app.handlers.render_complete, on_complete),
+            (bpy.app.handlers.render_cancel, on_cancel),
+        ]
+        for handler_list, handler in self._handlers:
+            handler_list.append(handler)
+        # Counted: one record per written frame and nothing else, so `render`
+        # records map 1:1 onto frames. Uncounted: one phase-only record, so the
+        # consumer knows rendering began without being handed a number.
+        if not self.counted:
+            emit("render", message=self.label)
+        return self
+
+    def __exit__(self, *_exc):
+        for handler_list, handler in self._handlers:
+            if handler in handler_list:
+                handler_list.remove(handler)
+        self._handlers = []
+        return False
diff --git a/20-agents/aeco/visualization/blender/scripts/exec.py b/20-agents/aeco/visualization/blender/scripts/exec.py
new file mode 100644
index 000000000..d6b7a6e1d
--- /dev/null
+++ b/20-agents/aeco/visualization/blender/scripts/exec.py
@@ -0,0 +1,240 @@
+"""`exec` -- run author-time `bpy` code headlessly (#692).
+
+Run: blender -b -P exec.py -- @inputs.json
+     inputs: {"code": "def run(ctx): ...", "args": {...}, "output-dir": "...",
+              "ifc-path" | "blend-path": "...", "preset": "realistic"}
+
+The code was written when the workflow was authored and is pinned in the
+approved lock (the runtime refuses a templated `code`), so this wrapper runs it
+as given. It:
+
+1. compiles the code as `<aware-exec>`, so a syntax error fails before any
+   scene work is paid for;
+2. prepares the scene -- `ifc-path`: an empty factory scene, the IFC imported
+   with its properties, the `preset` look and default lighting; `blend-path`:
+   that file opened as-is; neither: an empty factory scene (no default cube,
+   camera or light);
+3. runs the module body in a fresh namespace, requires a callable `run`, calls
+   `run(ctx)` (see `_exec_ctx`) and frames `{result, outputs, frames}` through
+   `_result`.
+
+Failures stay structured: a compile or runtime exception becomes
+`{ok: false, code: "exec-error", message, traceback, line}` with line numbers
+counted in the authored code, and a result over 256 KiB becomes
+`result-too-large`, telling the author to write a file and `ctx.add_output` it.
+"""
+
+import json
+import linecache
+import os
+import sys
+import traceback
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+import bpy  # noqa: E402
+
+import _exec_ctx  # noqa: E402
+import _ifc_import  # noqa: E402
+import _looks  # noqa: E402
+import _progress  # noqa: E402
+import _result  # noqa: E402
+import _stage  # noqa: E402
+
+ERR_EXEC = "exec-error"
+ERR_RESULT_TOO_LARGE = "result-too-large"
+
+# The serialized `result` cap. The framed payload is read whole from stdout and
+# copied into the run trace, so an unbounded return would cost memory twice and
+# make the trace unusable. Anything bigger belongs in a file.
+MAX_RESULT_BYTES = 256 * 1024
+
+CODE_FILENAME = "<aware-exec>"
+
+
+def _reset_to_empty_scene() -> None:
+    """Factory settings with no startup objects -- deterministic regardless of the user's startup file."""
+    bpy.ops.wm.read_factory_settings(use_empty=True)
+
+
+def prepare_scene(inputs: dict) -> dict:
+    """Stage the scene the code starts from. Returns a receipt of what was done."""
+    ifc_path = inputs.get("ifc-path") or None
+    blend_path = inputs.get("blend-path") or None
+    if ifc_path and blend_path:
+        raise _result.AwareBlenderError(
+            _result.ERR_INVALID_INPUTS,
+            "`ifc-path` and `blend-path` are mutually exclusive; give at most one",
+        )
+
+    if blend_path:
+        if not os.path.exists(str(blend_path)):
+            raise _result.AwareBlenderError(
+                _result.ERR_BLEND_UNREADABLE, f".blend not found: {blend_path}"
+            )
+        _progress.emit("import", message=f"opening {os.path.basename(str(blend_path))}")
+        bpy.ops.wm.open_mainfile(filepath=os.path.abspath(str(blend_path)))
+        return {"source": "blend-path", "path": os.path.abspath(str(blend_path))}
+
+    if not ifc_path:
+        _reset_to_empty_scene()
+        return {"source": "empty"}
+
+    if not os.path.exists(str(ifc_path)):
+        raise _result.AwareBlenderError(
+            _result.ERR_IFC_UNREADABLE, f"IFC not found: {ifc_path}"
+        )
+    preset = str(inputs.get("preset") or "realistic")
+    if preset not in _looks.PRESETS:
+        raise _result.AwareBlenderError(
+            _result.ERR_INVALID_INPUTS,
+            f"unknown preset `{preset}`; expected one of {sorted(_looks.PRESETS)}",
+        )
+    _reset_to_empty_scene()
+    _progress.emit("import", message=f"importing {os.path.basename(str(ifc_path))}")
+    imported = _ifc_import.import_ifc(
+        str(ifc_path), unit_scale=float(inputs.get("unit-scale", 1.0))
+    )
+    _progress.emit("look", message=f"applying the {preset} look")
+    look = _looks.apply_look(preset)
+    environment = _stage.setup_world(_stage.DEFAULT_ENVIRONMENT)
+    _stage.setup_key_light()
+    return {
+        "source": "ifc-path",
+        "path": os.path.abspath(str(ifc_path)),
+        "imported": imported.get("imported"),
+        "skipped-count": imported.get("skipped-count"),
+        "preset": preset,
+        "assigned": look.get("assigned"),
+        "environment": environment,
+    }
+
+
+def _authored_line(tb) -> int | None:
+    """The innermost line of the AUTHORED code in a traceback, if any."""
+    line = None
+    for frame in traceback.extract_tb(tb):
+        if frame.filename == CODE_FILENAME:
+            line = frame.lineno
+    return line
+
+
+def _exec_error(exc: BaseException, code: str) -> _result.AwareBlenderError:
+    """An `exec-error` naming the line in the author's code, with an authored-only traceback."""
+    if isinstance(exc, SyntaxError) and exc.filename == CODE_FILENAME:
+        line = exc.lineno
+        message = f"SyntaxError: {exc.msg} (line {line})"
+        text = "".join(traceback.format_exception_only(type(exc), exc))
+    else:
+        tb = exc.__traceback__
+        # Drop this wrapper's own frames: the author reads their code, not ours.
+        while tb is not None and tb.tb_frame.f_code.co_filename != CODE_FILENAME:
+            tb = tb.tb_next
+        if tb is None:
+            tb = exc.__traceback__
+        line = _authored_line(tb)
+        where = f" (line {line})" if line is not None else ""
+        message = f"{type(exc).__name__}: {exc}{where}"
+        text = "".join(traceback.format_exception(type(exc), exc, tb))
+    details = {"traceback": text}
+    if line is not None:
+        details["line"] = line
+    return _result.AwareBlenderError(
+        ERR_EXEC,
+        message,
+        "line numbers count from the first line of `code`",
+        **details,
+    )
+
+
+def compile_code(code: str):
+    """Compile the authored code -- a syntax error fails before any scene work is paid for."""
+    # Registered so tracebacks quote the authored source lines, not "<unknown>".
+    linecache.cache[CODE_FILENAME] = (
+        len(code),
+        None,
+        code.splitlines(keepends=True),
+        CODE_FILENAME,
+    )
+    try:
+        return compile(code, CODE_FILENAME, "exec")
+    except Exception as exc:  # noqa: BLE001 - surfaced as exec-error
+        raise _exec_error(exc, code) from exc
+
+
+def load_run(compiled, code: str):
+    """Execute the module body in a fresh namespace and return its `run` callable.
+
+    Runs AFTER the scene is prepared, so top-level statements see the staged
+    scene rather than the one the reset is about to discard.
+    """
+    namespace = {"__name__": "aware_exec", "__file__": CODE_FILENAME, "bpy": bpy}
+    try:
+        exec(compiled, namespace)  # noqa: S102 - the approved, lock-pinned program
+    except Exception as exc:  # noqa: BLE001 - surfaced as exec-error
+        raise _exec_error(exc, code) from exc
+    run = namespace.get("run")
+    if not callable(run):
+        raise _result.AwareBlenderError(
+            ERR_EXEC,
+            "the code defines no callable `run(ctx)`",
+            "define `def run(ctx): ...` at the top level of `code`",
+        )
+    return run
+
+
+def main(inputs: dict) -> dict:
+    code = inputs.get("code")
+    if not isinstance(code, str) or not code.strip():
+        raise _result.AwareBlenderError(
+            _result.ERR_INVALID_INPUTS,
+            "required input `code` is missing or empty -- Python source defining `run(ctx)`",
+        )
+    output_dir = os.path.abspath(str(_result.require(inputs, "output-dir")))
+    args = inputs.get("args") or {}
+    if not isinstance(args, dict):
+        raise _result.AwareBlenderError(
+            _result.ERR_INVALID_INPUTS, "`args` must be an object"
+        )
+
+    compiled = compile_code(code)
+    scene_receipt = prepare_scene(inputs)
+    _progress.emit("setup", message="running the workflow's code")
+    run = load_run(compiled, code)
+    ctx = _exec_ctx.ExecContext(args, output_dir)
+    try:
+        result = run(ctx)
+    except _result.AwareBlenderError:
+        raise
+    except Exception as exc:  # noqa: BLE001 - surfaced as exec-error
+        raise _exec_error(exc, code) from exc
+
+    try:
+        serialized = json.dumps(result, sort_keys=True)
+    except (TypeError, ValueError) as exc:
+        raise _result.AwareBlenderError(
+            ERR_EXEC,
+            f"run(ctx) returned a value JSON cannot carry: {exc}",
+            "return plain dicts, lists, strings, numbers, booleans or None",
+        ) from exc
+    size = len(serialized.encode("utf-8"))
+    if size > MAX_RESULT_BYTES:
+        raise _result.AwareBlenderError(
+            ERR_RESULT_TOO_LARGE,
+            f"run(ctx) returned {size} bytes of JSON; the limit is {MAX_RESULT_BYTES}",
+            "write large data to a file in ctx.output_dir and register it with "
+            "ctx.add_output(path, 'file'), returning a summary instead",
+            outputs=ctx.outputs,
+            frames=ctx.frames,
+        )
+
+    return {
+        "result": result,
+        "outputs": ctx.outputs,
+        "frames": ctx.frames,
+        "scene": scene_receipt,
+    }
+
+
+if __name__ == "__main__":
+    _result.run(main)
diff --git a/20-agents/aeco/visualization/blender/scripts/render_still.py b/20-agents/aeco/visualization/blender/scripts/render_still.py
index e443f8969..5263ae182 100644
--- a/20-agents/aeco/visualization/blender/scripts/render_still.py
+++ b/20-agents/aeco/visualization/blender/scripts/render_still.py
@@ -13,6 +13,7 @@
 import _framing  # noqa: E402
 import _ifc_import  # noqa: E402
 import _looks  # noqa: E402
+import _progress  # noqa: E402
 import _result  # noqa: E402
 import _stage  # noqa: E402
 
@@ -74,6 +75,7 @@ def load_scene(inputs: dict) -> None:
             raise _result.AwareBlenderError(
                 _result.ERR_BLEND_UNREADABLE, f".blend not found: {blend_path}"
             )
+        _progress.emit("import", message=f"opening {os.path.basename(str(blend_path))}")
         bpy.ops.wm.open_mainfile(filepath=os.path.abspath(str(blend_path)))
         return
 
@@ -88,9 +90,11 @@ def load_scene(inputs: dict) -> None:
             f"unknown preset `{preset}`; expected one of {sorted(_looks.PRESETS)}",
         )
     _ifc_import.clear_scene()
+    _progress.emit("import", message=f"importing {os.path.basename(str(ifc_path))}")
     _ifc_import.import_ifc(
         str(ifc_path), unit_scale=float(inputs.get("unit-scale", 1.0))
     )
+    _progress.emit("look", message=f"applying the {preset} look")
     _looks.apply_look(preset)
 
 
@@ -120,6 +124,7 @@ def main(inputs: dict) -> dict:
         )
 
     load_scene(inputs)
+    _progress.emit("setup", message="lighting and framing the shot")
 
     scene = bpy.context.scene
     scene.render.resolution_x = width
@@ -156,7 +161,8 @@ def main(inputs: dict) -> dict:
         raise _result.AwareBlenderError(_result.ERR_RENDER_FAILED, str(exc)) from exc
 
     os.makedirs(os.path.dirname(output_path), exist_ok=True)
-    bpy.ops.render.render(write_still=True)
+    with _progress.FrameCounter(1, "still"):
+        bpy.ops.render.render(write_still=True)
 
     if not os.path.exists(output_path):
         raise _result.AwareBlenderError(
diff --git a/20-agents/aeco/visualization/blender/scripts/render_turntable.py b/20-agents/aeco/visualization/blender/scripts/render_turntable.py
index ba900bc74..662d544b5 100644
--- a/20-agents/aeco/visualization/blender/scripts/render_turntable.py
+++ b/20-agents/aeco/visualization/blender/scripts/render_turntable.py
@@ -16,6 +16,7 @@
 import bpy  # noqa: E402
 
 import _framing  # noqa: E402
+import _progress  # noqa: E402
 import _result  # noqa: E402
 import _stage  # noqa: E402
 
@@ -75,6 +76,7 @@ def main(inputs: dict) -> dict:
     frame_count = max(2, int(round(duration * fps)))
 
     render_still.load_scene(inputs)
+    _progress.emit("setup", message="lighting, framing and keying the orbit")
 
     scene = bpy.context.scene
     scene.render.resolution_x = width
@@ -150,7 +152,9 @@ def main(inputs: dict) -> dict:
             keyframe.interpolation = "LINEAR"
 
     os.makedirs(os.path.dirname(output_path), exist_ok=True)
-    bpy.ops.render.render(animation=True)
+    # Per-frame progress, counted on `render_write` (see `_progress`).
+    with _progress.FrameCounter(frame_count, "turntable"):
+        bpy.ops.render.render(animation=True)
 
     # Blender may append a frame range to the container name; find what landed.
     written = output_path
diff --git a/20-agents/aeco/visualization/blender/skills/exec-bpy.md b/20-agents/aeco/visualization/blender/skills/exec-bpy.md
new file mode 100644
index 000000000..a1212afba
--- /dev/null
+++ b/20-agents/aeco/visualization/blender/skills/exec-bpy.md
@@ -0,0 +1,329 @@
+---
+name: blender-exec-bpy
+description: This skill should be used whenever a workflow needs a Blender render the fixed `blender` commands do not make — a construction sequence, a phasing or erection-order animation, a camera fly-through, a sun or shadow study, an exploded view, a "what changed" highlight, or any custom `bpy` scene — and so composes the `blender` agent's `exec` command. Use it when writing or reviewing an `exec` node's `code`, wiring its `args`/`ifc-path`/`output-dir`, budgeting its `timeout-seconds`, reading its `outputs` receipt or its `exec-error`, or deciding why a templated `code` was refused with E_APP_INPUT_MUST_BE_LITERAL. Covers the `run(ctx)` contract, the three scene starting points, per-frame progress, EEVEE as the animation default, and five worked recipes.
+---
+
+# `blender/exec` — author-time `bpy`, run unattended
+
+`exec` is how a workflow gets a Blender render nobody pre-built a command for. The
+author (usually the terminal AI, while composing the workflow) writes Python that
+defines `run(ctx)`. That code is stored **in the workflow file**, approved with the
+lock, and runs unchanged on every run, headlessly:
+
+```yaml
+- id: sequence
+  agent: blender
+  command: exec
+  inputs:
+    ifc-path: '{{ inputs.ifc-path }}'
+    output-dir: '{{ inputs.output-dir }}'
+    preset: realistic
+    args:
+      seconds-per-storey: 2
+    timeout-seconds: 1800
+    code: |
+      # Builds the model storey by storey and renders it as an MP4.
+      def run(ctx):
+          ...
+```
+
+The fixed commands (`render.still`, `render.turntable`) stay the right choice when
+they fit — they are tested recipes. Reach for `exec` when the picture needs
+something they cannot express.
+
+## The literal-code rule — data in `args`, never code
+
+`code` is declared `literal: true`. Validate, compile **and** the runtime refuse a
+`code` that contains template syntax (`{{ }}`, `{% %}`, `{# #}`) with
+`E_APP_INPUT_MUST_BE_LITERAL`, naming the node and the input.
+
+The reason is approval. The `.lock` hashes the app source; a person approves that
+lock; Run refuses when the source drifts. A templated `code` would hash the
+*template* and then execute whatever text the template resolved to at run time —
+Python nobody approved. So:
+
+- Write the program out in full in `code`.
+- Pass everything that varies per run through `args` (templatable), `ifc-path`,
+  `blend-path` and `output-dir`. `ctx.args` is a plain dict.
+- Never build Python source from `args` and `exec()` it inside `run` — that is the
+  same hole by another route.
+- Because template delimiters are refused anywhere in `code`, avoid `{{`/`{%`/`{#`
+  in the Python itself (an f-string escape like `f"{{"` trips it); use
+  `"{" + "{"` or `.format()`-free strings instead.
+
+A changed `code` is a changed program: it needs a fresh compile and approval, which
+is the point.
+
+## What happens before `run(ctx)`
+
+The scene is prepared, deterministically, from exactly one source:
+
+| Inputs | Starting scene |
+|---|---|
+| `ifc-path` | Factory reset to an empty scene, the IFC imported (each object carries `ifc_guid`, `ifc_class`, `ifc_name`, `ifc_material`, `ifc_storey`), the `preset` look applied (`clay`, `realistic`, `section-style`), default studio lighting and a key sun. No camera yet. |
+| `blend-path` | That `.blend` opened as-is — its camera, lights and materials are yours. |
+| neither | An empty factory scene: no default cube, camera or light. |
+
+`ifc-path` and `blend-path` together is `invalid-inputs`. The user's Blender
+startup file never leaks in.
+
+The code is compiled before the scene work, so a syntax error fails in a second
+rather than after a long import.
+
+## The `ctx` contract
+
+| Member | What it gives you |
+|---|---|
+| `ctx.args` | The node's `args` object (a dict; `{}` when absent). |
+| `ctx.output_dir` | Absolute real path of `output-dir` (created if missing). Write here. |
+| `ctx.scene` | `bpy.context.scene`. |
+| `ctx.elements()` | `[(obj, {guid, name, class, material, storey}), …]` for every imported IFC element; staging helpers (the ground) excluded. |
+| `ctx.frame(direction="hero")` | Creates the camera if needed and fits it to the model (`hero`, `iso`, `front`, `back`, `left`, `right`, `top`). Returns `{centre, radius, distance, direction}`. |
+| `ctx.apply_look(preset)` | Re-shade every element from its IFC class/material. |
+| `ctx.environment(name="studio")` | HDRI lighting (`studio`, `courtyard`, `city`, `forest`, `interior`, `night`, `sunrise`, `sunset`, `gradient`, or a path) plus a key sun if none exists. Returns the receipt. |
+| `ctx.ground(on=True)` | The fading floor, sized from the model. Call before `ctx.frame` so framing ignores it correctly. |
+| `ctx.progress(phase, done=None, total=None, message=None)` | Publish your own progress record (phase ≤ 64 chars). |
+| `ctx.plan_passes(n)` | Declare how many `render_*` calls follow, so each pass is labelled `pass i of n` instead of `pass i of ?`. |
+| `ctx.render_still(path, quality="draft", samples=None)` | PNG of the current frame. |
+| `ctx.render_animation(path, quality="draft", samples=None)` | H.264 MP4 of `scene.frame_start..frame_end`. |
+| `ctx.add_output(path, kind="file")` | Register any other file you wrote (`video`, `image`, `blend`, `file`). |
+
+Relative paths given to `render_*`/`add_output` resolve inside `ctx.output_dir`.
+`quality="draft"` is EEVEE, `"production"` is Cycles. Without a camera, `render_*`
+frames one at `hero` first.
+
+`run(ctx)` returns anything JSON can carry, up to **256 KiB** serialized. Larger
+fails as `result-too-large`: write the data to a file in `ctx.output_dir`,
+`ctx.add_output(path, "file")` it, and return a summary.
+
+### The node output
+
+```json
+{
+  "result":  { "…": "whatever run(ctx) returned" },
+  "outputs": [
+    { "path": "C:\\…\\sequence.mp4", "kind": "video", "size-bytes": 812345,
+      "frames": 240, "verified": true }
+  ],
+  "frames":  240,
+  "scene":   { "source": "ifc-path", "imported": 312, "preset": "realistic", "…": "…" }
+}
+```
+
+`outputs` is an explicit receipt, never a directory listing. Each entry is
+verified: the file exists, is a regular non-empty file, and its real path is inside
+`output_dir`. One that fails stays in the list with `verified: false` and a
+`reason` (`was not written`, `is outside output-dir (…)`, `is empty`). Downstream
+nodes should consume only `verified: true` entries.
+
+### Errors
+
+A compile or runtime exception becomes
+`{ok: false, code: "exec-error", message, line, traceback}`. `line` and the
+traceback count from the **first line of `code`**, and the traceback shows only the
+authored frames. `invalid-inputs` (missing `code`/`output-dir`, both scene
+sources, non-object `args`) is caught before Blender even starts and exits 3.
+
+## Progress — a long render never looks stuck
+
+Each `render_*` call is one progress segment. While it renders, one record per
+frame **written** reaches the run trace as `node-progress`:
+
+```json
+{"phase": "render", "done": 143, "total": 240, "message": "pass 1 of 2"}
+```
+
+Frames are counted on `bpy.app.handlers.render_write` — measured on Blender 5.2 to
+fire exactly once per frame written, for EEVEE and Cycles. Counting is enabled only
+on measured versions; on any other Blender a pass reports `phase: render` with its
+label and no numbers, so a consumer shows elapsed time instead of a guessed bar.
+Earlier phases are `import`, `look` and `setup`. A second `render_*` call starts a
+new segment at `done: 1` — it is a new bar, not a step backwards. Above 5,000 frames
+in one pass, every Nth frame is reported (plus the last).
+
+Do not count frames yourself with `frame_change_post`; it fires an extra time after
+the job and would claim a frame that was never written.
+
+## EEVEE for animation, and budgeting time
+
+- **Default to `quality="draft"` (EEVEE) for animations.** Cycles at production
+  samples is minutes per frame; an animation is hundreds of frames.
+- **Estimate before running, and tell the user.** Render a 1-frame still at the
+  target resolution (or use a known per-frame time), then: frames × seconds/frame
+  + import time (≈ 1 s per 50 elements) + ~30 s Blender/EEVEE start-up.
+- **Set `timeout-seconds` from that estimate with headroom** (×1.5–2). The default
+  is 1800 s; a timeout kills Blender's whole process tree and reports which budget
+  ran out, with the progress that had arrived.
+- Cut cost with resolution (`scene.render.resolution_x/_y`, or
+  `resolution_percentage`), `scene.eevee.taa_render_samples` (16 is plenty for a
+  sequence), and fps (24 reads fine for construction).
+- An interrupted FFMPEG MP4 is usually unplayable — there is no partial result.
+
+## Recipes
+
+Each opens with a plain-English `#` comment, which is what a workflow's node
+Description shows a non-coder.
+
+### Construction sequence by storey (keyframed visibility)
+
+```python
+# Builds the model up storey by storey -- each storey appears in turn -- and
+# renders it as an MP4 that ends on the finished building.
+def run(ctx):
+    scene = ctx.scene
+    fps = int(ctx.args.get("fps", 24))
+    hold = int(ctx.args.get("seconds-per-storey", 2) * fps)
+    elements = ctx.elements()
+
+    # Storey order: as given in args, else bottom-up by each storey's lowest point.
+    lowest = {}
+    for obj, props in elements:
+        z = min((obj.matrix_world @ v.co).z for v in obj.data.vertices) if obj.data.vertices else obj.location.z
+        lowest[props["storey"]] = min(z, lowest.get(props["storey"], z))
+    order = ctx.args.get("storey-order") or sorted(lowest, key=lowest.get)
+
+    ctx.ground(True)
+    ctx.frame("hero")
+    scene.render.fps = fps
+    scene.frame_start = 1
+    scene.frame_end = hold * (len(order) + 1)
+    scene.render.resolution_x = int(ctx.args.get("width", 1280))
+    scene.render.resolution_y = int(ctx.args.get("height", 720))
+
+    for obj, props in elements:
+        step = order.index(props["storey"]) if props["storey"] in order else len(order) - 1
+        appear = 1 + step * hold
+        obj.hide_render = True
+        obj.keyframe_insert("hide_render", frame=1)
+        obj.hide_render = False
+        obj.keyframe_insert("hide_render", frame=appear)
+
+    video = ctx.render_animation("construction-sequence.mp4")
+    return {"storeys": order, "frames": video.get("frames"), "verified": video["verified"]}
+```
+
+For erection order instead of storeys, pass `args: {sequence: {<guid>: <step>}}`
+(from a schedule or a Tekla phase report) and look the step up by `props["guid"]`.
+Boolean properties such as `hide_render` key with constant interpolation, so each
+element pops in on its frame.
+
+### Camera fly-through
+
+```python
+# Flies the camera past the model along a few waypoints and renders the flight.
+def run(ctx):
+    import bpy
+    scene = ctx.scene
+    framing = ctx.frame("hero")
+    cam = scene.camera
+    cx, cy, cz = framing["centre"]
+    r = framing["radius"]
+    waypoints = ctx.args.get("waypoints") or [
+        (cx - 2.5 * r, cy - 2.5 * r, cz + 0.6 * r),
+        (cx, cy - 1.8 * r, cz + 0.3 * r),
+        (cx + 2.5 * r, cy - 1.2 * r, cz + 0.8 * r),
+    ]
+    target = bpy.data.objects.new("AwareLookAt", None)
+    target.location = (cx, cy, cz)
+    scene.collection.objects.link(target)
+    track = cam.constraints.new("TRACK_TO")
+    track.target = target
+    span = int(ctx.args.get("frames-per-leg", 72))
+    for i, point in enumerate(waypoints):
+        cam.location = point
+        cam.keyframe_insert("location", frame=1 + i * span)
+    scene.frame_start, scene.frame_end = 1, 1 + (len(waypoints) - 1) * span
+    return {"video": ctx.render_animation("fly-through.mp4")}
+```
+
+### Sun study
+
+```python
+# Sweeps the sun across the sky from morning to evening so the shadows move
+# over the model, and renders the day as an MP4.
+import math
+
+def run(ctx):
+    import bpy
+    scene = ctx.scene
+    ctx.ground(True)
+    ctx.frame("hero")
+    sun = next((o for o in bpy.data.objects if o.type == "LIGHT" and o.data.type == "SUN"), None)
+    if sun is None:
+        sun = bpy.data.objects.new("Sun", bpy.data.lights.new("Sun", "SUN"))
+        scene.collection.objects.link(sun)
+    frames = int(ctx.args.get("frames", 120))
+    scene.frame_start, scene.frame_end = 1, frames
+    elevation = math.radians(float(ctx.args.get("max-elevation-deg", 55)))
+    for f, t in ((1, 0.0), (frames // 2, 0.5), (frames, 1.0)):
+        azimuth = math.radians(90 + 180 * t)          # east -> south -> west
+        height = elevation * math.sin(math.pi * t) + math.radians(5)
+        sun.rotation_euler = (math.pi / 2 - height, 0.0, azimuth)
+        sun.keyframe_insert("rotation_euler", frame=f)
+    return {"video": ctx.render_animation("sun-study.mp4")}
+```
+
+For a true solar path, compute azimuth/elevation from latitude, date and time in
+the code (pure math) and pass the site's latitude and date in `args`.
+
+### Exploded view
+
+```python
+# Pulls the storeys apart vertically and back together, so each level can be seen.
+def run(ctx):
+    scene = ctx.scene
+    ctx.frame("iso")
+    storeys = sorted({p["storey"] for _, p in ctx.elements()})
+    gap = float(ctx.args.get("gap-m", 4.0))
+    frames = int(ctx.args.get("frames", 96))
+    scene.frame_start, scene.frame_end = 1, frames
+    for obj, props in ctx.elements():
+        lift = storeys.index(props["storey"]) * gap
+        base = obj.location.z
+        for f, z in ((1, base), (frames // 2, base + lift), (frames, base)):
+            obj.location.z = z
+            obj.keyframe_insert("location", index=2, frame=f)
+    ctx.frame("iso")   # refit at rest; the camera does not follow the explosion
+    return {"video": ctx.render_animation("exploded.mp4")}
+```
+
+### Highlight changed elements
+
+```python
+# Paints the elements that changed in a bright accent over a neutral clay model
+# and renders one still, so a reviewer sees what moved at a glance.
+def run(ctx):
+    import bpy
+    changed = set(ctx.args.get("changed-guids", []))
+    ctx.apply_look("clay")
+    accent = bpy.data.materials.new("AwareChanged")
+    accent.use_nodes = True
+    accent.node_tree.nodes["Principled BSDF"].inputs["Base Color"].default_value = (0.95, 0.25, 0.1, 1)
+    hits = 0
+    for obj, props in ctx.elements():
+        if props["guid"] in changed:
+            obj.data.materials.clear()
+            obj.data.materials.append(accent)
+            hits += 1
+    ctx.ground(True)
+    ctx.frame("hero")
+    still = ctx.render_still("changes.png", quality="production", samples=64)
+    return {"highlighted": hits, "not-found": len(changed) - hits, "still": still["verified"]}
+```
+
+Report `not-found` rather than dropping it: a GUID that is not in the model is a
+finding, not noise.
+
+## Gotchas
+
+- `bpy.ops.view3d.*` and anything needing a viewport does not exist headless —
+  use `ctx.frame`, which fits the camera from geometry.
+- After moving objects or the camera in code, `bpy.context.view_layer.update()`
+  before reading `matrix_world`.
+- Blender 4.4+ keeps keyframes in layered actions (`action.layers[].strips[]
+  .channelbags[].fcurves`); `action.fcurves` no longer exists on 5.x. To change
+  interpolation, walk both shapes (see `render_turntable._iter_fcurves`).
+- Blender 5.x gates FFMPEG behind `image_settings.media_type = "VIDEO"`;
+  `render_animation` handles it — if you configure output yourself, set it first.
+- Python writes are not sandboxed; the agent's declared filesystem permission is
+  the contract a person approves. Keep writes inside `ctx.output_dir`.
diff --git a/20-agents/aeco/visualization/blender/tests/test_exec.py b/20-agents/aeco/visualization/blender/tests/test_exec.py
new file mode 100644
index 000000000..b7354aef9
--- /dev/null
+++ b/20-agents/aeco/visualization/blender/tests/test_exec.py
@@ -0,0 +1,384 @@
+"""`exec` (#692) against a REAL Blender: the wrapper, the ctx contract, progress.
+
+What this proves, each against a real `blender -b -P exec.py` launch exactly as
+the transport makes it (inputs staged as `@file`, result sliced from between the
+sentinels):
+
+  * the happy path returns `run(ctx)`'s value, an explicit outputs receipt and
+    the frame total -- and starts from an EMPTY scene when no source is given
+    (no default cube, camera or light);
+  * a runtime exception is a structured `exec-error` whose line number counts in
+    the AUTHORED code, with a traceback that quotes it;
+  * a syntax error is reported as one, with its authored line;
+  * an output outside `output_dir` (or never written) is listed `verified: false`
+    with the reason -- never dropped, never passed off as good;
+  * a `blend-path` opens that file as the starting scene;
+  * a result over 256 KiB fails as `result-too-large`;
+  * an 8-frame 64x64 EEVEE animation writes exactly 8 `render` progress records,
+    ending `done == total == 8`, on a version where frame counting is measured
+    (`_progress.COUNTED_VERSIONS`); on any other version it must write phase-only
+    records and NO counts -- that is what keeps the allow-list honest.
+
+Plus, without Blender: `_progress` is a no-op with no channel, writes one
+bounded line per record with one, and coalesces past 5,000 frames.
+
+The `ifc-path` scene path needs a generated IFC and so lives in
+`test_exec_ifc_scene.py`, which also needs a built CLI.
+
+Run: python test_exec.py [--blender <path>]
+Exits 0 when every check passes, 1 on any failure, 77 (SKIP) when no Blender
+can be found.
+"""
+
+import argparse
+import json
+import os
+import shutil
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+HERE = Path(__file__).resolve().parent
+SCRIPTS = HERE.parent / "scripts"
+sys.path.insert(0, str(SCRIPTS))
+sys.path.insert(0, str(HERE))
+
+import _progress  # noqa: E402 -- no bpy at module level, safe in plain Python
+import _result  # noqa: E402
+from run_smoke import detect_blender_version, resolve_blender  # noqa: E402
+
+SKIP_EXIT = 77
+FAILURES: list[str] = []
+
+
+def check(label: str, condition: bool, detail=None) -> None:
+    if condition:
+        print(f"  ok   {label}")
+    else:
+        print(f"  FAIL {label}")
+        if detail is not None:
+            print(f"       {detail}")
+        FAILURES.append(label)
+
+
+def run_exec(blender: str, work: Path, inputs: dict, progress: Path | None = None) -> dict:
+    """One real `exec` launch; returns the framed payload."""
+    staged = work / f"inputs-{len(list(work.glob('inputs-*.json')))}.json"
+    staged.write_text(json.dumps(inputs), encoding="utf-8")
+    env = dict(os.environ)
+    env.pop(_progress.ENV, None)
+    if progress is not None:
+        env[_progress.ENV] = str(progress)
+    proc = subprocess.run(
+        [blender, "-b", "-P", str(SCRIPTS / "exec.py"), "--", f"@{staged}"],
+        capture_output=True,
+        text=True,
+        encoding="utf-8",
+        errors="replace",
+        env=env,
+        check=False,
+    )
+    out = proc.stdout
+    if _result.RESULT_BEGIN not in out or _result.RESULT_END not in out:
+        raise AssertionError(
+            f"no framed result (exit {proc.returncode})\n--- stdout tail ---\n{out[-2000:]}"
+            f"\n--- stderr tail ---\n{proc.stderr[-2000:]}"
+        )
+    body = out.split(_result.RESULT_BEGIN, 1)[1].split(_result.RESULT_END, 1)[0]
+    return json.loads(body)
+
+
+def progress_records(path: Path) -> list[dict]:
+    if not path.exists():
+        return []
+    return [
+        json.loads(line)[_progress.RECORD_KEY]
+        for line in path.read_text(encoding="utf-8").splitlines()
+        if line.strip()
+    ]
+
+
+# ---------------------------------------------------------------------------
+# _progress, no Blender needed
+# ---------------------------------------------------------------------------
+
+
+def check_progress_writer(work: Path) -> None:
+    print("_progress (plain Python)")
+    channel = work / "plain-progress.jsonl"
+    saved = os.environ.pop(_progress.ENV, None)
+    try:
+        _progress.emit("render", 1, 2, "pass 1 of ?")
+        check("no channel -> emit is a no-op", not channel.exists())
+        check("no channel -> not enabled", _progress.enabled() is False)
+
+        os.environ[_progress.ENV] = str(channel)
+        _progress.emit("render", 1, 2, "pass 1 of ?")
+        _progress.emit("setup", message="x" * 20_000)
+        records = progress_records(channel)
+        check("with a channel -> one line per record", len(records) == 2, records)
+        check(
+            "the record carries phase/done/total/message",
+            records[0] == {"phase": "render", "done": 1, "total": 2, "message": "pass 1 of ?"},
+            records[0],
+        )
+        longest = max(len(l.encode("utf-8")) for l in channel.read_text(encoding="utf-8").splitlines())
+        check(
+            "a huge message is truncated under the runtime's 8 KiB record cap",
+            longest <= _progress.MAX_RECORD_BYTES,
+            longest,
+        )
+    finally:
+        os.environ.pop(_progress.ENV, None)
+        if saved is not None:
+            os.environ[_progress.ENV] = saved
+
+    check("<= 5000 frames: every frame reported", _progress.stride_for(5000) == 1)
+    check("12000 frames: every 3rd frame", _progress.stride_for(12000) == 3)
+    worst = 10_000_000
+    check(
+        "coalescing keeps any pass under the runtime's 10,000-record cap",
+        worst // _progress.stride_for(worst) + 1 <= 10_000,
+        _progress.stride_for(worst),
+    )
+    check("5.2 is a measured version", _progress.counting_supported((5, 2, 0)))
+    check("4.2 is NOT a measured version", not _progress.counting_supported((4, 2, 0)))
+
+
+# ---------------------------------------------------------------------------
+# exec, real Blender
+# ---------------------------------------------------------------------------
+
+HAPPY = """\
+import bpy
+
+def run(ctx):
+    started_with = len(bpy.data.objects)
+    bpy.ops.mesh.primitive_cube_add(size=2)
+    s = ctx.scene
+    s.render.resolution_x = 64
+    s.render.resolution_y = 64
+    sun = bpy.data.objects.new("Sun", bpy.data.lights.new("Sun", "SUN"))
+    s.collection.objects.link(sun)
+    still = ctx.render_still("hero.png")
+    # A file the code wrote OUTSIDE output_dir, and one it never wrote.
+    outside = ctx.args["outside"]
+    with open(outside, "w") as handle:
+        handle.write("not mine to publish")
+    ctx.add_output(outside, "file")
+    ctx.add_output("never-written.json", "file")
+    return {"started_with": started_with, "storeys": ctx.args["storeys"], "still": still["verified"]}
+"""
+
+RUNTIME_ERROR = """\
+def helper():
+    return 1 / 0
+
+def run(ctx):
+    x = 1
+    return helper() + x
+"""
+
+SYNTAX_ERROR = """\
+def run(ctx):
+    value = 1
+    return (value
+"""
+
+TOO_LARGE = """\
+def run(ctx):
+    return {"blob": "x" * (300 * 1024)}
+"""
+
+SAVE_BLEND = """\
+import bpy
+
+def run(ctx):
+    bpy.ops.mesh.primitive_monkey_add()
+    bpy.context.active_object.name = "AwareMarker"
+    path = ctx.output_dir + "/marker.blend"
+    bpy.ops.wm.save_as_mainfile(filepath=path)
+    ctx.add_output(path, "blend")
+    return {"saved": path}
+"""
+
+OPEN_BLEND = """\
+import bpy
+
+def run(ctx):
+    return {"names": sorted(o.name for o in bpy.data.objects)}
+"""
+
+ANIMATION = """\
+import bpy
+
+def run(ctx):
+    bpy.ops.mesh.primitive_cube_add(size=2)
+    cube = bpy.context.active_object
+    s = ctx.scene
+    s.render.resolution_x = 64
+    s.render.resolution_y = 64
+    s.frame_start = 1
+    s.frame_end = 8
+    cube.location = (0, 0, 0)
+    cube.keyframe_insert("location", frame=1)
+    cube.location = (2, 0, 0)
+    cube.keyframe_insert("location", frame=8)
+    sun = bpy.data.objects.new("Sun", bpy.data.lights.new("Sun", "SUN"))
+    s.collection.objects.link(sun)
+    ctx.plan_passes(1)
+    video = ctx.render_animation("sequence.mp4")
+    return {"video": video}
+"""
+
+
+def check_exec(blender: str, work: Path) -> None:
+    version = detect_blender_version(blender)
+    print(f"exec against Blender {version}")
+    out_dir = work / "out"
+    outside = work / "elsewhere" / "stray.txt"
+    outside.parent.mkdir(parents=True, exist_ok=True)
+
+    # -- happy path, empty scene, outputs receipt --------------------------------
+    payload = run_exec(
+        blender,
+        work,
+        {
+            "code": HAPPY,
+            "args": {"storeys": 3, "outside": str(outside)},
+            "output-dir": str(out_dir),
+        },
+    )
+    check("happy path reports ok", payload.get("ok") is True, payload)
+    result = payload.get("result") or {}
+    check("run(ctx)'s return value comes back as `result`", result.get("storeys") == 3, result)
+    check(
+        "with no source the code starts from an EMPTY scene",
+        result.get("started_with") == 0,
+        result,
+    )
+    check("the scene receipt says so", payload.get("scene", {}).get("source") == "empty", payload.get("scene"))
+    outputs = payload.get("outputs") or []
+    by_name = {Path(o["path"]).name: o for o in outputs}
+    hero = by_name.get("hero.png", {})
+    check("render_still is recorded and verified", hero.get("verified") is True and hero.get("size-bytes", 0) > 0, hero)
+    check("...with kind image", hero.get("kind") == "image", hero)
+    stray = by_name.get("stray.txt", {})
+    check("an output outside output_dir is listed verified:false", stray.get("verified") is False, stray)
+    check("...with the reason", "outside output-dir" in str(stray.get("reason")), stray)
+    missing = by_name.get("never-written.json", {})
+    check("a registered file that was never written is verified:false", missing.get("verified") is False, missing)
+    check("...and says it was not written", "not written" in str(missing.get("reason")), missing)
+    check("nothing else is listed (no directory diffing)", len(outputs) == 3, outputs)
+    check("frames counts animation frames only", payload.get("frames") == 0, payload.get("frames"))
+
+    # -- a runtime exception -------------------------------------------------------
+    payload = run_exec(blender, work, {"code": RUNTIME_ERROR, "output-dir": str(out_dir)})
+    check("a raised exception is a structured failure", payload.get("ok") is False, payload)
+    check("...coded exec-error", payload.get("code") == "exec-error", payload.get("code"))
+    check(
+        "...pointing at the authored line that raised (line 2)",
+        payload.get("line") == 2,
+        payload.get("line"),
+    )
+    tb = payload.get("traceback", "")
+    check("the traceback names the authored code", "<aware-exec>" in tb, tb)
+    check("the traceback quotes the failing authored line", "return 1 / 0" in tb, tb)
+    check("the traceback hides the wrapper's own frames", "exec.py" not in tb, tb)
+    check("the message names the exception", "ZeroDivisionError" in payload.get("message", ""), payload.get("message"))
+
+    # -- a syntax error ---------------------------------------------------------------
+    payload = run_exec(blender, work, {"code": SYNTAX_ERROR, "output-dir": str(out_dir)})
+    check("a syntax error is exec-error", payload.get("code") == "exec-error", payload)
+    check("...reported as a SyntaxError", "SyntaxError" in payload.get("message", ""), payload.get("message"))
+    check("...on its authored line (3)", payload.get("line") == 3, payload.get("line"))
+
+    # -- result too large ---------------------------------------------------------------
+    payload = run_exec(blender, work, {"code": TOO_LARGE, "output-dir": str(out_dir)})
+    check("a >256 KiB result fails", payload.get("ok") is False, payload.get("code"))
+    check("...as result-too-large", payload.get("code") == "result-too-large", payload.get("code"))
+    check("...telling the author to add_output a file", "add_output" in payload.get("hint", ""), payload.get("hint"))
+
+    # -- blend-path scene init ----------------------------------------------------------
+    saved = run_exec(blender, work, {"code": SAVE_BLEND, "output-dir": str(out_dir)})
+    blend = (saved.get("result") or {}).get("saved")
+    check("a .blend can be written and registered", saved.get("ok") and blend and Path(blend).exists(), saved)
+    opened = run_exec(
+        blender, work, {"code": OPEN_BLEND, "blend-path": blend, "output-dir": str(out_dir)}
+    )
+    names = (opened.get("result") or {}).get("names", [])
+    check("blend-path opens that file as the starting scene", "AwareMarker" in names, names)
+    check("...and says so", opened.get("scene", {}).get("source") == "blend-path", opened.get("scene"))
+
+    # -- the 8-frame animation and its progress records ------------------------------
+    channel = work / "anim-progress.jsonl"
+    payload = run_exec(
+        blender,
+        work,
+        {"code": ANIMATION, "output-dir": str(out_dir)},
+        progress=channel,
+    )
+    check("the animation renders", payload.get("ok") is True, payload)
+    video = (payload.get("result") or {}).get("video", {})
+    check("the MP4 is verified", video.get("verified") is True and video.get("size-bytes", 0) > 0, video)
+    check("the receipt carries the frame count", video.get("frames") == 8, video)
+    check("`frames` totals the animation", payload.get("frames") == 8, payload.get("frames"))
+    records = progress_records(channel)
+    renders = [r for r in records if r["phase"] == "render"]
+    phases = [r["phase"] for r in records]
+    check("the setup phase is reported before rendering", phases[:1] == ["setup"], phases)
+    if version is not None and _progress.counting_supported(version):
+        check("exactly 8 render records", len(renders) == 8, renders)
+        check(
+            "done counts 1..8 in order",
+            [r.get("done") for r in renders] == list(range(1, 9)),
+            renders,
+        )
+        check(
+            "the last record is done == total == 8",
+            bool(renders) and renders[-1].get("done") == renders[-1].get("total") == 8,
+            renders[-1:] if renders else renders,
+        )
+        check(
+            "each record names its pass",
+            all(r.get("message") == "pass 1 of 1" for r in renders),
+            renders,
+        )
+    else:
+        check(
+            "an unmeasured version reports phases only -- no counts",
+            renders and all("done" not in r and "total" not in r for r in renders),
+            renders,
+        )
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--blender", help="path to the Blender executable")
+    opts = parser.parse_args()
+
+    work = Path(tempfile.mkdtemp(prefix="aware-exec-"))
+    try:
+        check_progress_writer(work)
+        blender = resolve_blender(opts.blender)
+        if blender is None:
+            if FAILURES:
+                print("\nEXEC FAIL")
+                return 1
+            print("SKIP: no Blender available (pass --blender <path> to run this harness)")
+            return SKIP_EXIT
+        try:
+            check_exec(blender, work)
+        except AssertionError as exc:
+            FAILURES.append(str(exc))
+            print(f"  FAIL {exc}")
+    finally:
+        shutil.rmtree(work, ignore_errors=True)
+
+    print("\nEXEC FAIL" if FAILURES else "\nEXEC PASS")
+    return 1 if FAILURES else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())
diff --git a/20-agents/aeco/visualization/blender/tests/test_exec_ifc_scene.py b/20-agents/aeco/visualization/blender/tests/test_exec_ifc_scene.py
new file mode 100644
index 000000000..fa6ffd44c
--- /dev/null
+++ b/20-agents/aeco/visualization/blender/tests/test_exec_ifc_scene.py
@@ -0,0 +1,125 @@
+"""`exec`'s `ifc-path` scene path (#692) against a REAL Blender.
+
+The third of `exec`'s scene-initialisation paths (the empty and `blend-path`
+paths are in `test_exec.py`): with `ifc-path`, the wrapper resets to an empty
+factory scene, imports the IFC with its properties stamped on every object and
+applies the `preset` look -- BEFORE the author's code runs. So the code must see:
+
+  * exactly the fixture's elements through `ctx.elements()`, each carrying its
+    IFC class, material, storey and GUID (and no factory cube, camera or light);
+  * the look already applied (every element has a material);
+  * `ctx.frame()` able to fit a camera to that model;
+  * `import` and `look` progress phases reported before `setup`.
+
+Run: python test_exec_ifc_scene.py --aware-bin <path/to/aware[.exe]> [--blender <path>]
+Exits 0 when every check passes, 1 on any failure, 77 (SKIP) without Blender.
+"""
+
+import argparse
+import shutil
+import sys
+import tempfile
+from pathlib import Path
+
+HERE = Path(__file__).resolve().parent
+sys.path.insert(0, str(HERE))
+
+from make_fixture import build_fixture  # noqa: E402
+from run_smoke import resolve_blender  # noqa: E402
+from test_exec import FAILURES, SKIP_EXIT, check, progress_records, run_exec  # noqa: E402
+
+EXPECTED_CLASSES = {"IfcBeam": 4, "IfcColumn": 4, "IfcMember": 1}
+
+INSPECT = """\
+import bpy
+
+def run(ctx):
+    elements = ctx.elements()
+    by_class = {}
+    for obj, props in elements:
+        by_class[props["class"]] = by_class.get(props["class"], 0) + 1
+    framing = ctx.frame("iso")
+    return {
+        "by_class": by_class,
+        "guids": sorted(p["guid"] for _, p in elements),
+        "storeys": sorted({p["storey"] for _, p in elements}),
+        "materials": sorted({p["material"] for _, p in elements}),
+        "unshaded": [o.name for o, _ in elements if not o.data.materials],
+        "non_elements": sorted(o.name for o in bpy.data.objects
+                               if o.type == "MESH" and not o.get("ifc_class")),
+        "has_camera": ctx.scene.camera is not None,
+        "radius": framing["radius"],
+    }
+"""
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--blender", help="path to the Blender executable")
+    parser.add_argument("--aware-bin", required=True, help="path to the aware CLI")
+    opts = parser.parse_args()
+
+    blender = resolve_blender(opts.blender)
+    if blender is None:
+        print("SKIP: no Blender available (pass --blender <path> to run this harness)")
+        return SKIP_EXIT
+
+    work = Path(tempfile.mkdtemp(prefix="aware-exec-ifc-"))
+    try:
+        ifc = work / "fixture.ifc"
+        build_fixture(opts.aware_bin, ifc)
+        channel = work / "progress.jsonl"
+        payload = run_exec(
+            blender,
+            work,
+            {
+                "code": INSPECT,
+                "ifc-path": str(ifc),
+                "preset": "clay",
+                "output-dir": str(work / "out"),
+            },
+            progress=channel,
+        )
+        print("exec with ifc-path")
+        check("the run succeeds", payload.get("ok") is True, payload)
+        result = payload.get("result") or {}
+        check(
+            "ctx.elements() is exactly the fixture's elements",
+            result.get("by_class") == EXPECTED_CLASSES,
+            result.get("by_class"),
+        )
+        check("every element carries its GUID", len(set(result.get("guids", []))) == 9, result.get("guids"))
+        check("every element carries its storey", result.get("storeys") == ["Storey"], result.get("storeys"))
+        check(
+            "every element carries its material grade",
+            result.get("materials") == ["A36", "A500-GR.B", "A992"],
+            result.get("materials"),
+        )
+        check("the preset look was applied before run(ctx)", result.get("unshaded") == [], result.get("unshaded"))
+        check(
+            "the factory scene was reset first (no stray meshes)",
+            result.get("non_elements") == [],
+            result.get("non_elements"),
+        )
+        check("ctx.frame() fitted a camera", result.get("has_camera") is True and result.get("radius", 0) > 0, result)
+        scene = payload.get("scene", {})
+        check("the scene receipt names the source", scene.get("source") == "ifc-path", scene)
+        check("...and the preset", scene.get("preset") == "clay", scene)
+        phases = [r["phase"] for r in progress_records(channel)]
+        check(
+            "import, then look, then setup are reported in order",
+            phases[:3] == ["import", "look", "setup"],
+            phases,
+        )
+    except (AssertionError, RuntimeError) as exc:
+        FAILURES.append(str(exc))
+        print(f"  FAIL {exc}")
+    finally:
+        shutil.rmtree(work, ignore_errors=True)
+
+    print("\nEXEC IFC SCENE FAIL" if FAILURES else "\nEXEC IFC SCENE PASS")
+    return 1 if FAILURES else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())
diff --git a/30-apps/_examples/model-to-construction-sequence.app b/30-apps/_examples/model-to-construction-sequence.app
new file mode 100644
index 000000000..9aee483be
--- /dev/null
+++ b/30-apps/_examples/model-to-construction-sequence.app
@@ -0,0 +1,97 @@
+app:           model-to-construction-sequence
+version:       0.1.0
+display-name:  Model to Construction Sequence
+description: |
+  IFC in, a construction-sequence animation out: the building rises storey by
+  storey, bottom-up, and the MP4 ends on the finished model.
+
+  Nothing in the `blender` agent's fixed recipes makes this picture, so the
+  node runs `exec` -- `bpy` code written once when this app was authored,
+  pinned in the approved lock, and run unchanged on every run. What varies per
+  run (the model, where the video goes, how long each storey holds, the frame
+  size) travels as data in `args`; the program itself is never templated, and
+  validate, compile and run all refuse a templated `code`.
+
+  The render reports per-frame progress while it works, so a long animation
+  never looks stuck from the outside: the run trace carries `node-progress`
+  records counting frames up to the total.
+
+exposes-as-agent: false
+
+requires:
+  - blender@0.2.x
+
+requires-permissions:
+  filesystem:
+    - read:  '{{ inputs.ifc-path }}'
+    - write: '{{ inputs.output-dir }}'
+
+layout: dag
+
+nodes:
+  - id: sequence
+    agent: blender
+    command: exec
+    inputs:
+      ifc-path:   '{{ inputs.ifc-path }}'
+      output-dir: '{{ inputs.output-dir }}'
+      preset:     realistic
+      timeout-seconds: 3600
+      args:
+        seconds-per-storey: '{{ inputs.seconds-per-storey }}'
+        fps:    24
+        width:  '{{ inputs.width-pixels }}'
+        height: '{{ inputs.height-pixels }}'
+      code: |
+        # Builds the model up storey by storey -- each storey appears in turn,
+        # lowest first -- and renders it as an MP4 that ends on the whole building.
+        def run(ctx):
+            scene = ctx.scene
+            fps = int(ctx.args.get("fps") or 24)
+            hold = max(1, int(float(ctx.args.get("seconds-per-storey") or 2) * fps))
+            elements = ctx.elements()
+
+            # Order storeys bottom-up by the lowest point of anything on them.
+            lowest = {}
+            for obj, props in elements:
+                world = [obj.matrix_world @ v.co for v in obj.data.vertices]
+                z = min(p.z for p in world) if world else obj.location.z
+                key = props["storey"]
+                lowest[key] = min(z, lowest.get(key, z))
+            order = sorted(lowest, key=lowest.get)
+
+            ctx.ground(True)
+            ctx.frame("hero")
+            scene.render.fps = fps
+            scene.render.resolution_x = int(ctx.args.get("width") or 1280)
+            scene.render.resolution_y = int(ctx.args.get("height") or 720)
+            if hasattr(scene, "eevee") and hasattr(scene.eevee, "taa_render_samples"):
+                scene.eevee.taa_render_samples = 16
+            scene.frame_start = 1
+            scene.frame_end = hold * (len(order) + 1)
+
+            # Hidden until its storey's turn, then visible for the rest of the film.
+            for obj, props in elements:
+                appear = 1 + order.index(props["storey"]) * hold
+                obj.hide_render = True
+                obj.keyframe_insert("hide_render", frame=1)
+                obj.hide_render = False
+                obj.keyframe_insert("hide_render", frame=appear)
+
+            ctx.plan_passes(1)
+            video = ctx.render_animation("construction-sequence.mp4")
+            return {
+                "storeys": order,
+                "elements": len(elements),
+                "frames": video.get("frames"),
+                "video": video["path"],
+                "verified": video["verified"],
+            }
+    # `exec` is write-mode: it renders into `output-dir`. It touches no host
+    # model, so there is nothing to snapshot or transact -- the block records
+    # that, and groups the node's writes under one name for the audit trail.
+    safety:
+      transaction-group: construction-sequence
+      snapshot: false
+
+connections: []
diff --git a/30-apps/_examples/model-to-renders.app b/30-apps/_examples/model-to-renders.app
index 62db0254c..65f7da61e 100644
--- a/30-apps/_examples/model-to-renders.app
+++ b/30-apps/_examples/model-to-renders.app
@@ -24,7 +24,7 @@ description: |
 exposes-as-agent: false
 
 requires:
-  - blender@0.1.x
+  - blender@0.2.x
 
 requires-permissions:
   filesystem:
diff --git a/40-diagrams/substrate-playground.html b/40-diagrams/substrate-playground.html
index e2f59dfb8..7538a80e2 100644
--- a/40-diagrams/substrate-playground.html
+++ b/40-diagrams/substrate-playground.html
@@ -90,7 +90,7 @@ <h2>Prompt — copy back to Claude</h2>
 </div>
 
 <script>
-const RAW_AGENTS = [{"id": "acc-account-admin", "displayName": "Autodesk Construction Cloud \u2014 Account Admin (raw)", "vendor": "autodesk", "vertical": "Construction", "skills": 2, "commands": 30, "color": "#2e8b57"}, {"id": "acc-docs", "displayName": "Autodesk Construction Cloud \u2014 Docs", "vendor": "autodesk", "vertical": "Construction", "skills": 2, "commands": 12, "color": "#2e8b57"}, {"id": "acc-issues", "displayName": "Autodesk Construction Cloud \u2014 Issues (raw)", "vendor": "autodesk", "vertical": "Construction", "skills": 2, "commands": 14, "color": "#2e8b57"}, {"id": "aconex", "displayName": "Oracle Aconex", "vendor": "oracle", "vertical": "Construction", "skills": 2, "commands": 9, "color": "#6b7280"}, {"id": "allplan-2024", "displayName": "allplan-2024 (raw \u2014 612 types, full coverage)", "vendor": "nemetschek", "vertical": "Architecture", "skills": 98, "commands": 3603, "color": "#ff8c00"}, {"id": "allplan-2025", "displayName": "allplan-2025 (raw \u2014 763 types, full coverage)", "vendor": "nemetschek", "vertical": "Architecture", "skills": 151, "commands": 4003, "color": "#ff8c00"}, {"id": "aps-data-management", "displayName": "Autodesk APS \u2014 Data Management (raw)", "vendor": "autodesk", "vertical": "Construction", "skills": 3, "commands": 41, "color": "#2e8b57"}, {"id": "archicad-28", "displayName": "archicad-28 (raw \u2014 229 types, full coverage)", "vendor": "graphisoft", "vertical": "Architecture", "skills": 3, "commands": 202, "color": "#6b7280"}, {"id": "archicad-29", "displayName": "archicad-29 (raw \u2014 229 types, full coverage)", "vendor": "graphisoft", "vertical": "Architecture", "skills": 8, "commands": 207, "color": "#6b7280"}, {"id": "autocad-2025", "displayName": "AutoCAD 2025 (raw)", "vendor": "autodesk", "vertical": "Architecture", "skills": 73, "commands": 4398, "color": "#2e8b57"}, {"id": "autocad-2026", "displayName": "AutoCAD 2026 (raw)", "vendor": "autodesk", "vertical": "Architecture", "skills": 77, "commands": 4418, "color": "#2e8b57"}, {"id": "avitru-speclink", "displayName": "Avitru SpecLink", "vendor": "avitru", "vertical": "Architecture", "skills": 2, "commands": 10, "color": "#6b7280"}, {"id": "aware-agent-builder", "displayName": "AWARE Agent Builder", "vendor": "aware", "vertical": "Meta", "skills": 5, "commands": 1, "color": "#6b7280"}, {"id": "aware-skill-builder", "displayName": "AWARE Skill Builder", "vendor": "aware", "vertical": "Meta", "skills": 6, "commands": 4, "color": "#6b7280"}, {"id": "bcf-file", "displayName": "BCF (file format)", "vendor": "building-smart", "vertical": "Other", "skills": 5, "commands": 9, "color": "#6b7280"}, {"id": "blender", "displayName": "Blender", "vendor": "aware-aeco", "vertical": "Visualization", "skills": 3, "commands": 5, "color": "#0f172a"}, {"id": "bluebeam-studio", "displayName": "Bluebeam Revu Studio", "vendor": "bluebeam", "vertical": "Construction", "skills": 4, "commands": 9, "color": "#6b7280"}, {"id": "bluebeam-v1", "displayName": "bluebeam-v1 (raw \u2014 80 types, full coverage)", "vendor": "bluebeam", "vertical": "Architecture", "skills": 8, "commands": 123, "color": "#6b7280"}, {"id": "connection-reader", "displayName": "Connection Reader (IFC \u2192 mesh)", "vendor": "aware-aeco", "vertical": "Other", "skills": 1, "commands": 2, "color": "#0f172a"}, {"id": "csi-api", "displayName": "CSi API (SAP2000 / ETABS / SAFE / CSiBridge \u2014 raw)", "vendor": "computers-and-structures", "vertical": "Engineering", "skills": 2, "commands": 4282, "color": "#84cc16"}, {"id": "csi-masterformat", "displayName": "CSI MasterFormat (file-format)", "vendor": "csi", "vertical": "Architecture", "skills": 1, "commands": 6, "color": "#6b7280"}, {"id": "dropbox", "displayName": "Dropbox", "vendor": "dropbox", "vertical": "Cross-cutting", "skills": 2, "commands": 11, "color": "#6b7280"}, {"id": "dynamo-4-1-0", "displayName": "dynamo-4-1-0 (raw \u2014 707 types, full coverage)", "vendor": "dynamobim", "vertical": "Architecture", "skills": 121, "commands": 2431, "color": "#6b7280"}, {"id": "dynamo-4-1-1", "displayName": "dynamo-4-1-1 (raw \u2014 707 types, full coverage)", "vendor": "dynamobim", "vertical": "Architecture", "skills": 121, "commands": 2436, "color": "#6b7280"}, {"id": "enscape-prep", "displayName": "Enscape Prep", "vendor": "aware-aeco", "vertical": "Visualization", "skills": 2, "commands": 4, "color": "#0f172a"}, {"id": "file", "displayName": "File System", "vendor": "aware", "vertical": "Other", "skills": 2, "commands": 4, "color": "#6b7280"}, {"id": "google-workspace", "displayName": "Google Workspace", "vendor": "google", "vertical": "Cross-cutting", "skills": 4, "commands": 25, "color": "#6b7280"}, {"id": "grasshopper-7", "displayName": "grasshopper-7 (raw \u2014 650 types, full coverage)", "vendor": "mcneel", "vertical": "Architecture", "skills": 23, "commands": 4847, "color": "#dc143c"}, {"id": "grasshopper-8", "displayName": "grasshopper-8 (raw \u2014 825 types, full coverage)", "vendor": "mcneel", "vertical": "Architecture", "skills": 36, "commands": 11266, "color": "#dc143c"}, {"id": "html-report", "displayName": "HTML Report", "vendor": "aware", "vertical": "Other", "skills": 1, "commands": 1, "color": "#6b7280"}, {"id": "html-report-stream", "displayName": "HTML Report Stream", "vendor": "aware", "vertical": "Other", "skills": 0, "commands": 1, "color": "#6b7280"}, {"id": "http", "displayName": "HTTP / REST", "vendor": "null", "vertical": "Cross-cutting", "skills": 4, "commands": 6, "color": "#6b7280"}, {"id": "idea-statica-25", "displayName": "idea-statica-25 (raw \u2014 175 types, full coverage)", "vendor": "idea-statica", "vertical": "Engineering", "skills": 4, "commands": 113, "color": "#9333ea"}, {"id": "idea-statica-26", "displayName": "idea-statica-26 (raw \u2014 178 types, full coverage)", "vendor": "idea-statica", "vertical": "Engineering", "skills": 6, "commands": 117, "color": "#9333ea"}, {"id": "ifc", "displayName": "IFC Writer", "vendor": "aware", "vertical": "Other", "skills": 0, "commands": 1, "color": "#6b7280"}, {"id": "ifc-inspector", "displayName": "IFC Inspector (web-ifc parser)", "vendor": "aware-aeco", "vertical": "Construction", "skills": 5, "commands": 8, "color": "#0f172a"}, {"id": "ifc-reference-reader", "displayName": "IFC Reference Reader (whole model \u2192 mesh)", "vendor": "aware-aeco", "vertical": "Other", "skills": 1, "commands": 3, "color": "#0f172a"}, {"id": "itwin-5-8", "displayName": "Bentley iTwin 5.8 (raw \u2014 core-frontend)", "vendor": "bentley", "vertical": "Visualization", "skills": 598, "commands": 4553, "color": "#ea580c"}, {"id": "itwin-5-9", "displayName": "Bentley iTwin 5.9 (raw \u2014 core-frontend)", "vendor": "bentley", "vertical": "Visualization", "skills": 598, "commands": 4561, "color": "#ea580c"}, {"id": "microsoft-365", "displayName": "Microsoft 365 (Graph API)", "vendor": "microsoft", "vertical": "Cross-cutting", "skills": 4, "commands": 24, "color": "#6b7280"}, {"id": "model-reference-reader", "displayName": "Authenticated Model Reference Reader", "vendor": "aware-aeco", "vertical": "Other", "skills": 1, "commands": 5, "color": "#0f172a"}, {"id": "navisworks", "displayName": "Autodesk Navisworks Manage 2026", "vendor": "autodesk", "vertical": "Construction", "skills": 9, "commands": 12, "color": "#2e8b57"}, {"id": "navisworks-2026", "displayName": "navisworks-2026 (raw \u2014 779 types, full coverage)", "vendor": "autodesk", "vertical": "Architecture", "skills": 9, "commands": 5170, "color": "#2e8b57"}, {"id": "nbs-chorus", "displayName": "NBS Chorus", "vendor": "nbs", "vertical": "Architecture", "skills": 2, "commands": 9, "color": "#6b7280"}, {"id": "peddinghaus-translator", "displayName": "Peddinghaus Translator (DSTV \u2194 Peddimat)", "vendor": "aware-aeco", "vertical": "Other", "skills": 2, "commands": 4, "color": "#0f172a"}, {"id": "procore", "displayName": "Procore (architect side)", "vendor": "procore-technologies", "vertical": "Construction", "skills": 2, "commands": 9, "color": "#6b7280"}, {"id": "revit-2025", "displayName": "Autodesk Revit 2025 (raw)", "vendor": "autodesk", "vertical": "Architecture", "skills": 46, "commands": 7430, "color": "#2e8b57"}, {"id": "revit-2026", "displayName": "Autodesk Revit 2026 (raw)", "vendor": "autodesk", "vertical": "Architecture", "skills": 53, "commands": 7663, "color": "#2e8b57"}, {"id": "rhino-7", "displayName": "rhino-7 (raw \u2014 1154 types, full coverage)", "vendor": "mcneel", "vertical": "Architecture", "skills": 37, "commands": 15073, "color": "#dc143c"}, {"id": "rhino-8", "displayName": "rhino-8 (raw \u2014 1399 types, full coverage)", "vendor": "mcneel", "vertical": "Architecture", "skills": 43, "commands": 16923, "color": "#dc143c"}, {"id": "shell", "displayName": "Shell", "vendor": "aware", "vertical": "Other", "skills": 1, "commands": 1, "color": "#6b7280"}, {"id": "sketchup-2025", "displayName": "sketchup-2025 (raw \u2014 155 types, full coverage)", "vendor": "trimble", "vertical": "Architecture", "skills": 7, "commands": 1432, "color": "#0067a6"}, {"id": "sketchup-2026", "displayName": "sketchup-2026 (curated exec + 155 reflected types)", "vendor": "trimble", "vertical": "Architecture", "skills": 13, "commands": 1444, "color": "#0067a6"}, {"id": "slack", "displayName": "Slack Web API (raw)", "vendor": "slack", "vertical": "Construction", "skills": 5, "commands": 172, "color": "#4a154b"}, {"id": "solibri", "displayName": "Solibri Office", "vendor": "solibri", "vertical": "Construction", "skills": 2, "commands": 8, "color": "#6b7280"}, {"id": "solibri-26.4.1", "displayName": "solibri-26.4.1 (raw \u2014 16 types, full coverage)", "vendor": "solibri", "vertical": "Architecture", "skills": 5, "commands": 31, "color": "#6b7280"}, {"id": "speckle-viewer", "displayName": "Speckle Viewer (raw)", "vendor": "speckle", "vertical": "Visualization", "skills": 124, "commands": 942, "color": "#3b82f6"}, {"id": "steel-detailer-eu", "displayName": "Steel Detailer \u2014 EU (Eurocode 3, EN recommended values)", "vendor": "aware", "vertical": "Engineering", "skills": 12, "commands": 1, "color": "#6b7280"}, {"id": "steel-detailer-uk", "displayName": "Steel Detailer \u2014 UK (Eurocode 3 + UK NA)", "vendor": "aware", "vertical": "Engineering", "skills": 18, "commands": 1, "color": "#6b7280"}, {"id": "steel-detailer-us", "displayName": "Steel Detailer \u2014 US (AISC)", "vendor": "aware", "vertical": "Engineering", "skills": 21, "commands": 1, "color": "#6b7280"}, {"id": "tekla", "displayName": "Tekla Structures", "vendor": "trimble", "vertical": "Engineering", "skills": 33, "commands": 27, "color": "#0067a6"}, {"id": "tekla-2025", "displayName": "tekla-2025 (raw \u2014 1282 types, full coverage)", "vendor": "trimble", "vertical": "Engineering", "skills": 31, "commands": 6879, "color": "#0067a6"}, {"id": "tekla-2026", "displayName": "tekla-2026 (raw \u2014 1320 types, full coverage)", "vendor": "trimble", "vertical": "Engineering", "skills": 32, "commands": 7006, "color": "#0067a6"}, {"id": "tekla-plugin-sdk-2025", "displayName": "tekla-plugin-sdk-2025 (raw \u2014 333 types, full coverage)", "vendor": "trimble", "vertical": "Engineering", "skills": 16, "commands": 2275, "color": "#0067a6"}, {"id": "tekla-plugin-sdk-2026", "displayName": "tekla-plugin-sdk-2026 (raw \u2014 348 types, full coverage)", "vendor": "trimble", "vertical": "Engineering", "skills": 16, "commands": 2462, "color": "#0067a6"}, {"id": "tekla-powerfab", "displayName": "Tekla PowerFab", "vendor": "trimble", "vertical": "Engineering", "skills": 3, "commands": 9, "color": "#0067a6"}, {"id": "tekla-tedds-25", "displayName": "tekla-tedds-25 (raw \u2014 33 types, full coverage)", "vendor": "trimble", "vertical": "Engineering", "skills": 3, "commands": 67, "color": "#0067a6"}, {"id": "tekla-tedds-26", "displayName": "tekla-tedds-26 (raw \u2014 33 types, full coverage)", "vendor": "trimble", "vertical": "Engineering", "skills": 3, "commands": 67, "color": "#0067a6"}, {"id": "thatopen-components", "displayName": "That Open Components (modern IFC.js \u2014 raw)", "vendor": "thatopen", "vertical": "Visualization", "skills": 80, "commands": 337, "color": "#22d3ee"}, {"id": "three", "displayName": "three.js (raw)", "vendor": "mrdoob", "vertical": "Visualization", "skills": 511, "commands": 2860, "color": "#a855f7"}, {"id": "trimble-connect", "displayName": "Trimble Connect", "vendor": "trimble", "vertical": "Construction", "skills": 7, "commands": 46, "color": "#0067a6"}, {"id": "tsd-25", "displayName": "Tekla Structural Designer 25 (raw \u2014 Remoting API)", "vendor": "trimble", "vertical": "Engineering", "skills": 42, "commands": 440, "color": "#0067a6"}, {"id": "tsd-26", "displayName": "Tekla Structural Designer 26 (raw \u2014 Remoting API)", "vendor": "trimble", "vertical": "Engineering", "skills": 42, "commands": 440, "color": "#0067a6"}, {"id": "twinmotion-prep", "displayName": "Twinmotion Prep", "vendor": "aware-aeco", "vertical": "Visualization", "skills": 1, "commands": 4, "color": "#0f172a"}, {"id": "ui", "displayName": "Declarative UI", "vendor": "aware", "vertical": "Other", "skills": 1, "commands": 3, "color": "#6b7280"}, {"id": "ui-inspector", "displayName": "UI Inspector", "vendor": "aware", "vertical": "Other", "skills": 3, "commands": 5, "color": "#6b7280"}, {"id": "viewer-3d", "displayName": "3D Viewer", "vendor": "aware", "vertical": "Visualization", "skills": 1, "commands": 1, "color": "#6b7280"}, {"id": "vision", "displayName": "Vision Extract", "vendor": "null", "vertical": "Cross-cutting", "skills": 2, "commands": 1, "color": "#6b7280"}, {"id": "web-ifc", "displayName": "web-ifc (WebAssembly IFC parser \u2014 raw)", "vendor": "thatopen", "vertical": "Visualization", "skills": 19, "commands": 120, "color": "#22d3ee"}, {"id": "xeokit", "displayName": "xeokit SDK (BIM/IFC web viewer)", "vendor": "creoox", "vertical": "Visualization", "skills": 98, "commands": 361, "color": "#06b6d4"}];
+const RAW_AGENTS = [{"id": "acc-account-admin", "displayName": "Autodesk Construction Cloud \u2014 Account Admin (raw)", "vendor": "autodesk", "vertical": "Construction", "skills": 2, "commands": 30, "color": "#2e8b57"}, {"id": "acc-docs", "displayName": "Autodesk Construction Cloud \u2014 Docs", "vendor": "autodesk", "vertical": "Construction", "skills": 2, "commands": 12, "color": "#2e8b57"}, {"id": "acc-issues", "displayName": "Autodesk Construction Cloud \u2014 Issues (raw)", "vendor": "autodesk", "vertical": "Construction", "skills": 2, "commands": 14, "color": "#2e8b57"}, {"id": "aconex", "displayName": "Oracle Aconex", "vendor": "oracle", "vertical": "Construction", "skills": 2, "commands": 9, "color": "#6b7280"}, {"id": "allplan-2024", "displayName": "allplan-2024 (raw \u2014 612 types, full coverage)", "vendor": "nemetschek", "vertical": "Architecture", "skills": 98, "commands": 3603, "color": "#ff8c00"}, {"id": "allplan-2025", "displayName": "allplan-2025 (raw \u2014 763 types, full coverage)", "vendor": "nemetschek", "vertical": "Architecture", "skills": 151, "commands": 4003, "color": "#ff8c00"}, {"id": "aps-data-management", "displayName": "Autodesk APS \u2014 Data Management (raw)", "vendor": "autodesk", "vertical": "Construction", "skills": 3, "commands": 41, "color": "#2e8b57"}, {"id": "archicad-28", "displayName": "archicad-28 (raw \u2014 229 types, full coverage)", "vendor": "graphisoft", "vertical": "Architecture", "skills": 3, "commands": 202, "color": "#6b7280"}, {"id": "archicad-29", "displayName": "archicad-29 (raw \u2014 229 types, full coverage)", "vendor": "graphisoft", "vertical": "Architecture", "skills": 8, "commands": 207, "color": "#6b7280"}, {"id": "autocad-2025", "displayName": "AutoCAD 2025 (raw)", "vendor": "autodesk", "vertical": "Architecture", "skills": 73, "commands": 4398, "color": "#2e8b57"}, {"id": "autocad-2026", "displayName": "AutoCAD 2026 (raw)", "vendor": "autodesk", "vertical": "Architecture", "skills": 77, "commands": 4418, "color": "#2e8b57"}, {"id": "avitru-speclink", "displayName": "Avitru SpecLink", "vendor": "avitru", "vertical": "Architecture", "skills": 2, "commands": 10, "color": "#6b7280"}, {"id": "aware-agent-builder", "displayName": "AWARE Agent Builder", "vendor": "aware", "vertical": "Meta", "skills": 5, "commands": 1, "color": "#6b7280"}, {"id": "aware-skill-builder", "displayName": "AWARE Skill Builder", "vendor": "aware", "vertical": "Meta", "skills": 6, "commands": 4, "color": "#6b7280"}, {"id": "bcf-file", "displayName": "BCF (file format)", "vendor": "building-smart", "vertical": "Other", "skills": 5, "commands": 9, "color": "#6b7280"}, {"id": "blender", "displayName": "Blender", "vendor": "aware-aeco", "vertical": "Visualization", "skills": 4, "commands": 6, "color": "#0f172a"}, {"id": "bluebeam-studio", "displayName": "Bluebeam Revu Studio", "vendor": "bluebeam", "vertical": "Construction", "skills": 4, "commands": 9, "color": "#6b7280"}, {"id": "bluebeam-v1", "displayName": "bluebeam-v1 (raw \u2014 80 types, full coverage)", "vendor": "bluebeam", "vertical": "Architecture", "skills": 8, "commands": 123, "color": "#6b7280"}, {"id": "connection-reader", "displayName": "Connection Reader (IFC \u2192 mesh)", "vendor": "aware-aeco", "vertical": "Other", "skills": 1, "commands": 2, "color": "#0f172a"}, {"id": "csi-api", "displayName": "CSi API (SAP2000 / ETABS / SAFE / CSiBridge \u2014 raw)", "vendor": "computers-and-structures", "vertical": "Engineering", "skills": 2, "commands": 4282, "color": "#84cc16"}, {"id": "csi-masterformat", "displayName": "CSI MasterFormat (file-format)", "vendor": "csi", "vertical": "Architecture", "skills": 1, "commands": 6, "color": "#6b7280"}, {"id": "dropbox", "displayName": "Dropbox", "vendor": "dropbox", "vertical": "Cross-cutting", "skills": 2, "commands": 11, "color": "#6b7280"}, {"id": "dynamo-4-1-0", "displayName": "dynamo-4-1-0 (raw \u2014 707 types, full coverage)", "vendor": "dynamobim", "vertical": "Architecture", "skills": 121, "commands": 2431, "color": "#6b7280"}, {"id": "dynamo-4-1-1", "displayName": "dynamo-4-1-1 (raw \u2014 707 types, full coverage)", "vendor": "dynamobim", "vertical": "Architecture", "skills": 121, "commands": 2436, "color": "#6b7280"}, {"id": "enscape-prep", "displayName": "Enscape Prep", "vendor": "aware-aeco", "vertical": "Visualization", "skills": 2, "commands": 4, "color": "#0f172a"}, {"id": "file", "displayName": "File System", "vendor": "aware", "vertical": "Other", "skills": 2, "commands": 4, "color": "#6b7280"}, {"id": "google-workspace", "displayName": "Google Workspace", "vendor": "google", "vertical": "Cross-cutting", "skills": 4, "commands": 25, "color": "#6b7280"}, {"id": "grasshopper-7", "displayName": "grasshopper-7 (raw \u2014 650 types, full coverage)", "vendor": "mcneel", "vertical": "Architecture", "skills": 23, "commands": 4847, "color": "#dc143c"}, {"id": "grasshopper-8", "displayName": "grasshopper-8 (raw \u2014 825 types, full coverage)", "vendor": "mcneel", "vertical": "Architecture", "skills": 36, "commands": 11266, "color": "#dc143c"}, {"id": "html-report", "displayName": "HTML Report", "vendor": "aware", "vertical": "Other", "skills": 1, "commands": 1, "color": "#6b7280"}, {"id": "html-report-stream", "displayName": "HTML Report Stream", "vendor": "aware", "vertical": "Other", "skills": 0, "commands": 1, "color": "#6b7280"}, {"id": "http", "displayName": "HTTP / REST", "vendor": "null", "vertical": "Cross-cutting", "skills": 4, "commands": 6, "color": "#6b7280"}, {"id": "idea-statica-25", "displayName": "idea-statica-25 (raw \u2014 175 types, full coverage)", "vendor": "idea-statica", "vertical": "Engineering", "skills": 4, "commands": 113, "color": "#9333ea"}, {"id": "idea-statica-26", "displayName": "idea-statica-26 (raw \u2014 178 types, full coverage)", "vendor": "idea-statica", "vertical": "Engineering", "skills": 6, "commands": 117, "color": "#9333ea"}, {"id": "ifc", "displayName": "IFC Writer", "vendor": "aware", "vertical": "Other", "skills": 0, "commands": 1, "color": "#6b7280"}, {"id": "ifc-inspector", "displayName": "IFC Inspector (web-ifc parser)", "vendor": "aware-aeco", "vertical": "Construction", "skills": 5, "commands": 8, "color": "#0f172a"}, {"id": "ifc-reference-reader", "displayName": "IFC Reference Reader (whole model \u2192 mesh)", "vendor": "aware-aeco", "vertical": "Other", "skills": 1, "commands": 3, "color": "#0f172a"}, {"id": "itwin-5-8", "displayName": "Bentley iTwin 5.8 (raw \u2014 core-frontend)", "vendor": "bentley", "vertical": "Visualization", "skills": 598, "commands": 4553, "color": "#ea580c"}, {"id": "itwin-5-9", "displayName": "Bentley iTwin 5.9 (raw \u2014 core-frontend)", "vendor": "bentley", "vertical": "Visualization", "skills": 598, "commands": 4561, "color": "#ea580c"}, {"id": "microsoft-365", "displayName": "Microsoft 365 (Graph API)", "vendor": "microsoft", "vertical": "Cross-cutting", "skills": 4, "commands": 24, "color": "#6b7280"}, {"id": "model-reference-reader", "displayName": "Authenticated Model Reference Reader", "vendor": "aware-aeco", "vertical": "Other", "skills": 1, "commands": 5, "color": "#0f172a"}, {"id": "navisworks", "displayName": "Autodesk Navisworks Manage 2026", "vendor": "autodesk", "vertical": "Construction", "skills": 9, "commands": 12, "color": "#2e8b57"}, {"id": "navisworks-2026", "displayName": "navisworks-2026 (raw \u2014 779 types, full coverage)", "vendor": "autodesk", "vertical": "Architecture", "skills": 9, "commands": 5170, "color": "#2e8b57"}, {"id": "nbs-chorus", "displayName": "NBS Chorus", "vendor": "nbs", "vertical": "Architecture", "skills": 2, "commands": 9, "color": "#6b7280"}, {"id": "peddinghaus-translator", "displayName": "Peddinghaus Translator (DSTV \u2194 Peddimat)", "vendor": "aware-aeco", "vertical": "Other", "skills": 2, "commands": 4, "color": "#0f172a"}, {"id": "procore", "displayName": "Procore (architect side)", "vendor": "procore-technologies", "vertical": "Construction", "skills": 2, "commands": 9, "color": "#6b7280"}, {"id": "revit-2025", "displayName": "Autodesk Revit 2025 (raw)", "vendor": "autodesk", "vertical": "Architecture", "skills": 46, "commands": 7430, "color": "#2e8b57"}, {"id": "revit-2026", "displayName": "Autodesk Revit 2026 (raw)", "vendor": "autodesk", "vertical": "Architecture", "skills": 53, "commands": 7663, "color": "#2e8b57"}, {"id": "rhino-7", "displayName": "rhino-7 (raw \u2014 1154 types, full coverage)", "vendor": "mcneel", "vertical": "Architecture", "skills": 37, "commands": 15073, "color": "#dc143c"}, {"id": "rhino-8", "displayName": "rhino-8 (raw \u2014 1399 types, full coverage)", "vendor": "mcneel", "vertical": "Architecture", "skills": 43, "commands": 16923, "color": "#dc143c"}, {"id": "shell", "displayName": "Shell", "vendor": "aware", "vertical": "Other", "skills": 1, "commands": 1, "color": "#6b7280"}, {"id": "sketchup-2025", "displayName": "sketchup-2025 (raw \u2014 155 types, full coverage)", "vendor": "trimble", "vertical": "Architecture", "skills": 7, "commands": 1432, "color": "#0067a6"}, {"id": "sketchup-2026", "displayName": "sketchup-2026 (curated exec + 155 reflected types)", "vendor": "trimble", "vertical": "Architecture", "skills": 13, "commands": 1444, "color": "#0067a6"}, {"id": "slack", "displayName": "Slack Web API (raw)", "vendor": "slack", "vertical": "Construction", "skills": 5, "commands": 172, "color": "#4a154b"}, {"id": "solibri", "displayName": "Solibri Office", "vendor": "solibri", "vertical": "Construction", "skills": 2, "commands": 8, "color": "#6b7280"}, {"id": "solibri-26.4.1", "displayName": "solibri-26.4.1 (raw \u2014 16 types, full coverage)", "vendor": "solibri", "vertical": "Architecture", "skills": 5, "commands": 31, "color": "#6b7280"}, {"id": "speckle-viewer", "displayName": "Speckle Viewer (raw)", "vendor": "speckle", "vertical": "Visualization", "skills": 124, "commands": 942, "color": "#3b82f6"}, {"id": "steel-detailer-eu", "displayName": "Steel Detailer \u2014 EU (Eurocode 3, EN recommended values)", "vendor": "aware", "vertical": "Engineering", "skills": 12, "commands": 1, "color": "#6b7280"}, {"id": "steel-detailer-uk", "displayName": "Steel Detailer \u2014 UK (Eurocode 3 + UK NA)", "vendor": "aware", "vertical": "Engineering", "skills": 18, "commands": 1, "color": "#6b7280"}, {"id": "steel-detailer-us", "displayName": "Steel Detailer \u2014 US (AISC)", "vendor": "aware", "vertical": "Engineering", "skills": 21, "commands": 1, "color": "#6b7280"}, {"id": "tekla", "displayName": "Tekla Structures", "vendor": "trimble", "vertical": "Engineering", "skills": 33, "commands": 27, "color": "#0067a6"}, {"id": "tekla-2025", "displayName": "tekla-2025 (raw \u2014 1282 types, full coverage)", "vendor": "trimble", "vertical": "Engineering", "skills": 31, "commands": 6879, "color": "#0067a6"}, {"id": "tekla-2026", "displayName": "tekla-2026 (raw \u2014 1320 types, full coverage)", "vendor": "trimble", "vertical": "Engineering", "skills": 32, "commands": 7006, "color": "#0067a6"}, {"id": "tekla-plugin-sdk-2025", "displayName": "tekla-plugin-sdk-2025 (raw \u2014 333 types, full coverage)", "vendor": "trimble", "vertical": "Engineering", "skills": 16, "commands": 2275, "color": "#0067a6"}, {"id": "tekla-plugin-sdk-2026", "displayName": "tekla-plugin-sdk-2026 (raw \u2014 348 types, full coverage)", "vendor": "trimble", "vertical": "Engineering", "skills": 16, "commands": 2462, "color": "#0067a6"}, {"id": "tekla-powerfab", "displayName": "Tekla PowerFab", "vendor": "trimble", "vertical": "Engineering", "skills": 3, "commands": 9, "color": "#0067a6"}, {"id": "tekla-tedds-25", "displayName": "tekla-tedds-25 (raw \u2014 33 types, full coverage)", "vendor": "trimble", "vertical": "Engineering", "skills": 3, "commands": 67, "color": "#0067a6"}, {"id": "tekla-tedds-26", "displayName": "tekla-tedds-26 (raw \u2014 33 types, full coverage)", "vendor": "trimble", "vertical": "Engineering", "skills": 3, "commands": 67, "color": "#0067a6"}, {"id": "thatopen-components", "displayName": "That Open Components (modern IFC.js \u2014 raw)", "vendor": "thatopen", "vertical": "Visualization", "skills": 80, "commands": 337, "color": "#22d3ee"}, {"id": "three", "displayName": "three.js (raw)", "vendor": "mrdoob", "vertical": "Visualization", "skills": 511, "commands": 2860, "color": "#a855f7"}, {"id": "trimble-connect", "displayName": "Trimble Connect", "vendor": "trimble", "vertical": "Construction", "skills": 7, "commands": 46, "color": "#0067a6"}, {"id": "tsd-25", "displayName": "Tekla Structural Designer 25 (raw \u2014 Remoting API)", "vendor": "trimble", "vertical": "Engineering", "skills": 42, "commands": 440, "color": "#0067a6"}, {"id": "tsd-26", "displayName": "Tekla Structural Designer 26 (raw \u2014 Remoting API)", "vendor": "trimble", "vertical": "Engineering", "skills": 42, "commands": 440, "color": "#0067a6"}, {"id": "twinmotion-prep", "displayName": "Twinmotion Prep", "vendor": "aware-aeco", "vertical": "Visualization", "skills": 1, "commands": 4, "color": "#0f172a"}, {"id": "ui", "displayName": "Declarative UI", "vendor": "aware", "vertical": "Other", "skills": 1, "commands": 3, "color": "#6b7280"}, {"id": "ui-inspector", "displayName": "UI Inspector", "vendor": "aware", "vertical": "Other", "skills": 3, "commands": 5, "color": "#6b7280"}, {"id": "viewer-3d", "displayName": "3D Viewer", "vendor": "aware", "vertical": "Visualization", "skills": 1, "commands": 1, "color": "#6b7280"}, {"id": "vision", "displayName": "Vision Extract", "vendor": "null", "vertical": "Cross-cutting", "skills": 2, "commands": 1, "color": "#6b7280"}, {"id": "web-ifc", "displayName": "web-ifc (WebAssembly IFC parser \u2014 raw)", "vendor": "thatopen", "vertical": "Visualization", "skills": 19, "commands": 120, "color": "#22d3ee"}, {"id": "xeokit", "displayName": "xeokit SDK (BIM/IFC web viewer)", "vendor": "creoox", "vertical": "Visualization", "skills": 98, "commands": 361, "color": "#06b6d4"}];
 const RAW_EDGES = [{"source": "acc-account-admin", "target": "bluebeam-v1", "weight": 5}, {"source": "acc-docs", "target": "dropbox", "weight": 3}, {"source": "allplan-2024", "target": "allplan-2025", "weight": 2161}, {"source": "allplan-2024", "target": "archicad-28", "weight": 7}, {"source": "allplan-2024", "target": "archicad-29", "weight": 7}, {"source": "allplan-2024", "target": "autocad-2025", "weight": 40}, {"source": "allplan-2024", "target": "autocad-2026", "weight": 41}, {"source": "allplan-2024", "target": "csi-api", "weight": 39}, {"source": "allplan-2024", "target": "dynamo-4-1-0", "weight": 9}, {"source": "allplan-2024", "target": "dynamo-4-1-1", "weight": 9}, {"source": "allplan-2024", "target": "grasshopper-7", "weight": 18}, {"source": "allplan-2024", "target": "grasshopper-8", "weight": 19}, {"source": "allplan-2024", "target": "itwin-5-8", "weight": 66}, {"source": "allplan-2024", "target": "itwin-5-9", "weight": 66}, {"source": "allplan-2024", "target": "navisworks-2026", "weight": 85}, {"source": "allplan-2024", "target": "revit-2025", "weight": 129}, {"source": "allplan-2024", "target": "revit-2026", "weight": 130}, {"source": "allplan-2024", "target": "rhino-7", "weight": 98}, {"source": "allplan-2024", "target": "rhino-8", "weight": 104}, {"source": "allplan-2024", "target": "sketchup-2025", "weight": 49}, {"source": "allplan-2024", "target": "sketchup-2026", "weight": 49}, {"source": "allplan-2024", "target": "speckle-viewer", "weight": 15}, {"source": "allplan-2024", "target": "tekla-2025", "weight": 46}, {"source": "allplan-2024", "target": "tekla-2026", "weight": 46}, {"source": "allplan-2024", "target": "tekla-plugin-sdk-2025", "weight": 16}, {"source": "allplan-2024", "target": "tekla-plugin-sdk-2026", "weight": 16}, {"source": "allplan-2024", "target": "thatopen-components", "weight": 7}, {"source": "allplan-2024", "target": "three", "weight": 57}, {"source": "allplan-2024", "target": "tsd-25", "weight": 3}, {"source": "allplan-2024", "target": "tsd-26", "weight": 3}, {"source": "allplan-2024", "target": "web-ifc", "weight": 6}, {"source": "allplan-2024", "target": "xeokit", "weight": 4}, {"source": "allplan-2025", "target": "archicad-28", "weight": 9}, {"source": "allplan-2025", "target": "archicad-29", "weight": 10}, {"source": "allplan-2025", "target": "autocad-2025", "weight": 46}, {"source": "allplan-2025", "target": "autocad-2026", "weight": 48}, {"source": "allplan-2025", "target": "csi-api", "weight": 39}, {"source": "allplan-2025", "target": "dynamo-4-1-0", "weight": 10}, {"source": "allplan-2025", "target": "dynamo-4-1-1", "weight": 10}, {"source": "allplan-2025", "target": "grasshopper-7", "weight": 20}, {"source": "allplan-2025", "target": "grasshopper-8", "weight": 21}, {"source": "allplan-2025", "target": "itwin-5-8", "weight": 72}, {"source": "allplan-2025", "target": "itwin-5-9", "weight": 72}, {"source": "allplan-2025", "target": "navisworks-2026", "weight": 89}, {"source": "allplan-2025", "target": "revit-2025", "weight": 138}, {"source": "allplan-2025", "target": "revit-2026", "weight": 139}, {"source": "allplan-2025", "target": "rhino-7", "weight": 105}, {"source": "allplan-2025", "target": "rhino-8", "weight": 115}, {"source": "allplan-2025", "target": "sketchup-2025", "weight": 52}, {"source": "allplan-2025", "target": "sketchup-2026", "weight": 52}, {"source": "allplan-2025", "target": "speckle-viewer", "weight": 15}, {"source": "allplan-2025", "target": "tekla-2025", "weight": 49}, {"source": "allplan-2025", "target": "tekla-2026", "weight": 49}, {"source": "allplan-2025", "target": "tekla-plugin-sdk-2025", "weight": 18}, {"source": "allplan-2025", "target": "tekla-plugin-sdk-2026", "weight": 18}, {"source": "allplan-2025", "target": "thatopen-components", "weight": 8}, {"source": "allplan-2025", "target": "three", "weight": 58}, {"source": "allplan-2025", "target": "tsd-25", "weight": 4}, {"source": "allplan-2025", "target": "tsd-26", "weight": 4}, {"source": "allplan-2025", "target": "web-ifc", "weight": 6}, {"source": "allplan-2025", "target": "xeokit", "weight": 6}, {"source": "aps-data-management", "target": "navisworks-2026", "weight": 3}, {"source": "aps-data-management", "target": "trimble-connect", "weight": 3}, {"source": "archicad-28", "target": "archicad-29", "weight": 155}, {"source": "archicad-28", "target": "autocad-2025", "weight": 4}, {"source": "archicad-28", "target": "autocad-2026", "weight": 4}, {"source": "archicad-28", "target": "csi-api", "weight": 3}, {"source": "archicad-28", "target": "itwin-5-8", "weight": 4}, {"source": "archicad-28", "target": "itwin-5-9", "weight": 4}, {"source": "archicad-28", "target": "navisworks-2026", "weight": 3}, {"source": "archicad-28", "target": "revit-2025", "weight": 11}, {"source": "archicad-28", "target": "revit-2026", "weight": 12}, {"source": "archicad-28", "target": "rhino-7", "weight": 3}, {"source": "archicad-28", "target": "rhino-8", "weight": 3}, {"source": "archicad-29", "target": "autocad-2025", "weight": 4}, {"source": "archicad-29", "target": "autocad-2026", "weight": 5}, {"source": "archicad-29", "target": "csi-api", "weight": 3}, {"source": "archicad-29", "target": "itwin-5-8", "weight": 4}, {"source": "archicad-29", "target": "itwin-5-9", "weight": 4}, {"source": "archicad-29", "target": "navisworks-2026", "weight": 3}, {"source": "archicad-29", "target": "revit-2025", "weight": 11}, {"source": "archicad-29", "target": "revit-2026", "weight": 12}, {"source": "archicad-29", "target": "rhino-7", "weight": 3}, {"source": "archicad-29", "target": "rhino-8", "weight": 4}, {"source": "autocad-2025", "target": "autocad-2026", "weight": 2324}, {"source": "autocad-2025", "target": "csi-api", "weight": 17}, {"source": "autocad-2025", "target": "dynamo-4-1-0", "weight": 17}, {"source": "autocad-2025", "target": "dynamo-4-1-1", "weight": 17}, {"source": "autocad-2025", "target": "grasshopper-7", "weight": 59}, {"source": "autocad-2025", "target": "grasshopper-8", "weight": 59}, {"source": "autocad-2025", "target": "itwin-5-8", "weight": 83}, {"source": "autocad-2025", "target": "itwin-5-9", "weight": 83}, {"source": "autocad-2025", "target": "navisworks-2026", "weight": 123}, {"source": "autocad-2025", "target": "revit-2025", "weight": 364}, {"source": "autocad-2025", "target": "revit-2026", "weight": 366}, {"source": "autocad-2025", "target": "rhino-7", "weight": 139}, {"source": "autocad-2025", "target": "rhino-8", "weight": 143}, {"source": "autocad-2025", "target": "sketchup-2025", "weight": 30}, {"source": "autocad-2025", "target": "sketchup-2026", "weight": 30}, {"source": "autocad-2025", "target": "slack", "weight": 3}, {"source": "autocad-2025", "target": "speckle-viewer", "weight": 16}, {"source": "autocad-2025", "target": "tekla-2025", "weight": 58}, {"source": "autocad-2025", "target": "tekla-2026", "weight": 60}, {"source": "autocad-2025", "target": "tekla-plugin-sdk-2025", "weight": 38}, {"source": "autocad-2025", "target": "tekla-plugin-sdk-2026", "weight": 38}, {"source": "autocad-2025", "target": "thatopen-components", "weight": 10}, {"source": "autocad-2025", "target": "three", "weight": 47}, {"source": "autocad-2025", "target": "tsd-25", "weight": 6}, {"source": "autocad-2025", "target": "tsd-26", "weight": 6}, {"source": "autocad-2025", "target": "web-ifc", "weight": 5}, {"source": "autocad-2025", "target": "xeokit", "weight": 8}, {"source": "autocad-2026", "target": "csi-api", "weight": 17}, {"source": "autocad-2026", "target": "dynamo-4-1-0", "weight": 17}, {"source": "autocad-2026", "target": "dynamo-4-1-1", "weight": 17}, {"source": "autocad-2026", "target": "grasshopper-7", "weight": 59}, {"source": "autocad-2026", "target": "grasshopper-8", "weight": 59}, {"source": "autocad-2026", "target": "itwin-5-8", "weight": 84}, {"source": "autocad-2026", "target": "itwin-5-9", "weight": 84}, {"source": "autocad-2026", "target": "navisworks-2026", "weight": 123}, {"source": "autocad-2026", "target": "revit-2025", "weight": 364}, {"source": "autocad-2026", "target": "revit-2026", "weight": 366}, {"source": "autocad-2026", "target": "rhino-7", "weight": 140}, {"source": "autocad-2026", "target": "rhino-8", "weight": 147}, {"source": "autocad-2026", "target": "sketchup-2025", "weight": 30}, {"source": "autocad-2026", "target": "sketchup-2026", "weight": 30}, {"source": "autocad-2026", "target": "slack", "weight": 3}, {"source": "autocad-2026", "target": "speckle-viewer", "weight": 16}, {"source": "autocad-2026", "target": "tekla-2025", "weight": 58}, {"source": "autocad-2026", "target": "tekla-2026", "weight": 60}, {"source": "autocad-2026", "target": "tekla-plugin-sdk-2025", "weight": 38}, {"source": "autocad-2026", "target": "tekla-plugin-sdk-2026", "weight": 38}, {"source": "autocad-2026", "target": "thatopen-components", "weight": 10}, {"source": "autocad-2026", "target": "three", "weight": 48}, {"source": "autocad-2026", "target": "tsd-25", "weight": 6}, {"source": "autocad-2026", "target": "tsd-26", "weight": 6}, {"source": "autocad-2026", "target": "web-ifc", "weight": 5}, {"source": "autocad-2026", "target": "xeokit", "weight": 8}, {"source": "avitru-speclink", "target": "nbs-chorus", "weight": 5}, {"source": "bluebeam-v1", "target": "revit-2025", "weight": 4}, {"source": "bluebeam-v1", "target": "revit-2026", "weight": 4}, {"source": "bluebeam-v1", "target": "trimble-connect", "weight": 11}, {"source": "csi-api", "target": "dynamo-4-1-0", "weight": 3}, {"source": "csi-api", "target": "dynamo-4-1-1", "weight": 3}, {"source": "csi-api", "target": "grasshopper-7", "weight": 10}, {"source": "csi-api", "target": "grasshopper-8", "weight": 10}, {"source": "csi-api", "target": "itwin-5-8", "weight": 13}, {"source": "csi-api", "target": "itwin-5-9", "weight": 13}, {"source": "csi-api", "target": "navisworks-2026", "weight": 27}, {"source": "csi-api", "target": "revit-2025", "weight": 31}, {"source": "csi-api", "target": "revit-2026", "weight": 32}, {"source": "csi-api", "target": "rhino-7", "weight": 34}, {"source": "csi-api", "target": "rhino-8", "weight": 35}, {"source": "csi-api", "target": "sketchup-2025", "weight": 10}, {"source": "csi-api", "target": "sketchup-2026", "weight": 10}, {"source": "csi-api", "target": "speckle-viewer", "weight": 4}, {"source": "csi-api", "target": "tekla-2025", "weight": 23}, {"source": "csi-api", "target": "tekla-2026", "weight": 24}, {"source": "csi-api", "target": "tekla-plugin-sdk-2025", "weight": 3}, {"source": "csi-api", "target": "tekla-plugin-sdk-2026", "weight": 3}, {"source": "csi-api", "target": "thatopen-components", "weight": 5}, {"source": "csi-api", "target": "three", "weight": 15}, {"source": "csi-api", "target": "web-ifc", "weight": 4}, {"source": "csi-api", "target": "xeokit", "weight": 5}, {"source": "dynamo-4-1-0", "target": "dynamo-4-1-1", "weight": 683}, {"source": "dynamo-4-1-0", "target": "grasshopper-7", "weight": 28}, {"source": "dynamo-4-1-0", "target": "grasshopper-8", "weight": 33}, {"source": "dynamo-4-1-0", "target": "itwin-5-8", "weight": 8}, {"source": "dynamo-4-1-0", "target": "itwin-5-9", "weight": 8}, {"source": "dynamo-4-1-0", "target": "navisworks-2026", "weight": 12}, {"source": "dynamo-4-1-0", "target": "revit-2025", "weight": 19}, {"source": "dynamo-4-1-0", "target": "revit-2026", "weight": 19}, {"source": "dynamo-4-1-0", "target": "rhino-7", "weight": 39}, {"source": "dynamo-4-1-0", "target": "rhino-8", "weight": 44}, {"source": "dynamo-4-1-0", "target": "sketchup-2025", "weight": 4}, {"source": "dynamo-4-1-0", "target": "sketchup-2026", "weight": 4}, {"source": "dynamo-4-1-0", "target": "tekla-2025", "weight": 24}, {"source": "dynamo-4-1-0", "target": "tekla-2026", "weight": 24}, {"source": "dynamo-4-1-0", "target": "tekla-plugin-sdk-2025", "weight": 7}, {"source": "dynamo-4-1-0", "target": "tekla-plugin-sdk-2026", "weight": 7}, {"source": "dynamo-4-1-0", "target": "tekla-tedds-25", "weight": 12}, {"source": "dynamo-4-1-0", "target": "tekla-tedds-26", "weight": 12}, {"source": "dynamo-4-1-0", "target": "thatopen-components", "weight": 4}, {"source": "dynamo-4-1-0", "target": "three", "weight": 7}, {"source": "dynamo-4-1-1", "target": "grasshopper-7", "weight": 28}, {"source": "dynamo-4-1-1", "target": "grasshopper-8", "weight": 33}, {"source": "dynamo-4-1-1", "target": "itwin-5-8", "weight": 8}, {"source": "dynamo-4-1-1", "target": "itwin-5-9", "weight": 8}, {"source": "dynamo-4-1-1", "target": "navisworks-2026", "weight": 12}, {"source": "dynamo-4-1-1", "target": "revit-2025", "weight": 19}, {"source": "dynamo-4-1-1", "target": "revit-2026", "weight": 19}, {"source": "dynamo-4-1-1", "target": "rhino-7", "weight": 39}, {"source": "dynamo-4-1-1", "target": "rhino-8", "weight": 44}, {"source": "dynamo-4-1-1", "target": "sketchup-2025", "weight": 4}, {"source": "dynamo-4-1-1", "target": "sketchup-2026", "weight": 4}, {"source": "dynamo-4-1-1", "target": "tekla-2025", "weight": 24}, {"source": "dynamo-4-1-1", "target": "tekla-2026", "weight": 24}, {"source": "dynamo-4-1-1", "target": "tekla-plugin-sdk-2025", "weight": 7}, {"source": "dynamo-4-1-1", "target": "tekla-plugin-sdk-2026", "weight": 7}, {"source": "dynamo-4-1-1", "target": "tekla-tedds-25", "weight": 12}, {"source": "dynamo-4-1-1", "target": "tekla-tedds-26", "weight": 12}, {"source": "dynamo-4-1-1", "target": "thatopen-components", "weight": 4}, {"source": "dynamo-4-1-1", "target": "three", "weight": 7}, {"source": "google-workspace", "target": "microsoft-365", "weight": 4}, {"source": "grasshopper-7", "target": "grasshopper-8", "weight": 1856}, {"source": "grasshopper-7", "target": "itwin-5-8", "weight": 28}, {"source": "grasshopper-7", "target": "itwin-5-9", "weight": 28}, {"source": "grasshopper-7", "target": "navisworks-2026", "weight": 58}, {"source": "grasshopper-7", "target": "revit-2025", "weight": 72}, {"source": "grasshopper-7", "target": "revit-2026", "weight": 73}, {"source": "grasshopper-7", "target": "rhino-7", "weight": 216}, {"source": "grasshopper-7", "target": "rhino-8", "weight": 218}, {"source": "grasshopper-7", "target": "sketchup-2025", "weight": 20}, {"source": "grasshopper-7", "target": "sketchup-2026", "weight": 20}, {"source": "grasshopper-7", "target": "speckle-viewer", "weight": 13}, {"source": "grasshopper-7", "target": "tekla-2025", "weight": 54}, {"source": "grasshopper-7", "target": "tekla-2026", "weight": 55}, {"source": "grasshopper-7", "target": "tekla-plugin-sdk-2025", "weight": 19}, {"source": "grasshopper-7", "target": "tekla-plugin-sdk-2026", "weight": 19}, {"source": "grasshopper-7", "target": "tekla-tedds-25", "weight": 7}, {"source": "grasshopper-7", "target": "tekla-tedds-26", "weight": 7}, {"source": "grasshopper-7", "target": "thatopen-components", "weight": 5}, {"source": "grasshopper-7", "target": "three", "weight": 19}, {"source": "grasshopper-7", "target": "tsd-25", "weight": 4}, {"source": "grasshopper-7", "target": "tsd-26", "weight": 4}, {"source": "grasshopper-7", "target": "xeokit", "weight": 5}, {"source": "grasshopper-8", "target": "itwin-5-8", "weight": 34}, {"source": "grasshopper-8", "target": "itwin-5-9", "weight": 34}, {"source": "grasshopper-8", "target": "navisworks-2026", "weight": 60}, {"source": "grasshopper-8", "target": "revit-2025", "weight": 82}, {"source": "grasshopper-8", "target": "revit-2026", "weight": 83}, {"source": "grasshopper-8", "target": "rhino-7", "weight": 266}, {"source": "grasshopper-8", "target": "rhino-8", "weight": 275}, {"source": "grasshopper-8", "target": "sketchup-2025", "weight": 23}, {"source": "grasshopper-8", "target": "sketchup-2026", "weight": 23}, {"source": "grasshopper-8", "target": "speckle-viewer", "weight": 14}, {"source": "grasshopper-8", "target": "tekla-2025", "weight": 57}, {"source": "grasshopper-8", "target": "tekla-2026", "weight": 59}, {"source": "grasshopper-8", "target": "tekla-plugin-sdk-2025", "weight": 20}, {"source": "grasshopper-8", "target": "tekla-plugin-sdk-2026", "weight": 20}, {"source": "grasshopper-8", "target": "tekla-tedds-25", "weight": 7}, {"source": "grasshopper-8", "target": "tekla-tedds-26", "weight": 7}, {"source": "grasshopper-8", "target": "thatopen-components", "weight": 5}, {"source": "grasshopper-8", "target": "three", "weight": 22}, {"source": "grasshopper-8", "target": "tsd-25", "weight": 4}, {"source": "grasshopper-8", "target": "tsd-26", "weight": 4}, {"source": "grasshopper-8", "target": "xeokit", "weight": 5}, {"source": "idea-statica-25", "target": "idea-statica-26", "weight": 59}, {"source": "idea-statica-25", "target": "tsd-25", "weight": 13}, {"source": "idea-statica-25", "target": "tsd-26", "weight": 13}, {"source": "idea-statica-26", "target": "tsd-25", "weight": 13}, {"source": "idea-statica-26", "target": "tsd-26", "weight": 13}, {"source": "itwin-5-8", "target": "itwin-5-9", "weight": 2383}, {"source": "itwin-5-8", "target": "navisworks-2026", "weight": 91}, {"source": "itwin-5-8", "target": "revit-2025", "weight": 122}, {"source": "itwin-5-8", "target": "revit-2026", "weight": 122}, {"source": "itwin-5-8", "target": "rhino-7", "weight": 106}, {"source": "itwin-5-8", "target": "rhino-8", "weight": 109}, {"source": "itwin-5-8", "target": "sketchup-2025", "weight": 31}, {"source": "itwin-5-8", "target": "sketchup-2026", "weight": 31}, {"source": "itwin-5-8", "target": "speckle-viewer", "weight": 25}, {"source": "itwin-5-8", "target": "tekla-2025", "weight": 26}, {"source": "itwin-5-8", "target": "tekla-2026", "weight": 26}, {"source": "itwin-5-8", "target": "tekla-plugin-sdk-2025", "weight": 17}, {"source": "itwin-5-8", "target": "tekla-plugin-sdk-2026", "weight": 17}, {"source": "itwin-5-8", "target": "thatopen-components", "weight": 12}, {"source": "itwin-5-8", "target": "three", "weight": 90}, {"source": "itwin-5-8", "target": "tsd-25", "weight": 3}, {"source": "itwin-5-8", "target": "tsd-26", "weight": 3}, {"source": "itwin-5-8", "target": "web-ifc", "weight": 4}, {"source": "itwin-5-8", "target": "xeokit", "weight": 11}, {"source": "itwin-5-9", "target": "navisworks-2026", "weight": 91}, {"source": "itwin-5-9", "target": "revit-2025", "weight": 122}, {"source": "itwin-5-9", "target": "revit-2026", "weight": 122}, {"source": "itwin-5-9", "target": "rhino-7", "weight": 106}, {"source": "itwin-5-9", "target": "rhino-8", "weight": 109}, {"source": "itwin-5-9", "target": "sketchup-2025", "weight": 31}, {"source": "itwin-5-9", "target": "sketchup-2026", "weight": 31}, {"source": "itwin-5-9", "target": "speckle-viewer", "weight": 25}, {"source": "itwin-5-9", "target": "tekla-2025", "weight": 26}, {"source": "itwin-5-9", "target": "tekla-2026", "weight": 26}, {"source": "itwin-5-9", "target": "tekla-plugin-sdk-2025", "weight": 17}, {"source": "itwin-5-9", "target": "tekla-plugin-sdk-2026", "weight": 17}, {"source": "itwin-5-9", "target": "thatopen-components", "weight": 12}, {"source": "itwin-5-9", "target": "three", "weight": 90}, {"source": "itwin-5-9", "target": "tsd-25", "weight": 3}, {"source": "itwin-5-9", "target": "tsd-26", "weight": 3}, {"source": "itwin-5-9", "target": "web-ifc", "weight": 4}, {"source": "itwin-5-9", "target": "xeokit", "weight": 11}, {"source": "navisworks-2026", "target": "revit-2025", "weight": 150}, {"source": "navisworks-2026", "target": "revit-2026", "weight": 150}, {"source": "navisworks-2026", "target": "rhino-7", "weight": 144}, {"source": "navisworks-2026", "target": "rhino-8", "weight": 147}, {"source": "navisworks-2026", "target": "sketchup-2025", "weight": 47}, {"source": "navisworks-2026", "target": "sketchup-2026", "weight": 47}, {"source": "navisworks-2026", "target": "slack", "weight": 4}, {"source": "navisworks-2026", "target": "speckle-viewer", "weight": 23}, {"source": "navisworks-2026", "target": "tekla-2025", "weight": 58}, {"source": "navisworks-2026", "target": "tekla-2026", "weight": 59}, {"source": "navisworks-2026", "target": "tekla-plugin-sdk-2025", "weight": 57}, {"source": "navisworks-2026", "target": "tekla-plugin-sdk-2026", "weight": 58}, {"source": "navisworks-2026", "target": "thatopen-components", "weight": 13}, {"source": "navisworks-2026", "target": "three", "weight": 75}, {"source": "navisworks-2026", "target": "tsd-25", "weight": 4}, {"source": "navisworks-2026", "target": "tsd-26", "weight": 4}, {"source": "navisworks-2026", "target": "web-ifc", "weight": 6}, {"source": "navisworks-2026", "target": "xeokit", "weight": 10}, {"source": "revit-2025", "target": "revit-2026", "weight": 4050}, {"source": "revit-2025", "target": "rhino-7", "weight": 230}, {"source": "revit-2025", "target": "rhino-8", "weight": 244}, {"source": "revit-2025", "target": "sketchup-2025", "weight": 57}, {"source": "revit-2025", "target": "sketchup-2026", "weight": 57}, {"source": "revit-2025", "target": "speckle-viewer", "weight": 24}, {"source": "revit-2025", "target": "tekla-2025", "weight": 77}, {"source": "revit-2025", "target": "tekla-2026", "weight": 77}, {"source": "revit-2025", "target": "tekla-plugin-sdk-2025", "weight": 38}, {"source": "revit-2025", "target": "tekla-plugin-sdk-2026", "weight": 38}, {"source": "revit-2025", "target": "thatopen-components", "weight": 25}, {"source": "revit-2025", "target": "three", "weight": 92}, {"source": "revit-2025", "target": "trimble-connect", "weight": 3}, {"source": "revit-2025", "target": "tsd-25", "weight": 10}, {"source": "revit-2025", "target": "tsd-26", "weight": 10}, {"source": "revit-2025", "target": "web-ifc", "weight": 5}, {"source": "revit-2025", "target": "xeokit", "weight": 12}, {"source": "revit-2026", "target": "rhino-7", "weight": 234}, {"source": "revit-2026", "target": "rhino-8", "weight": 256}, {"source": "revit-2026", "target": "sketchup-2025", "weight": 58}, {"source": "revit-2026", "target": "sketchup-2026", "weight": 60}, {"source": "revit-2026", "target": "speckle-viewer", "weight": 24}, {"source": "revit-2026", "target": "tekla", "weight": 8}, {"source": "revit-2026", "target": "tekla-2025", "weight": 78}, {"source": "revit-2026", "target": "tekla-2026", "weight": 78}, {"source": "revit-2026", "target": "tekla-plugin-sdk-2025", "weight": 39}, {"source": "revit-2026", "target": "tekla-plugin-sdk-2026", "weight": 39}, {"source": "revit-2026", "target": "thatopen-components", "weight": 23}, {"source": "revit-2026", "target": "three", "weight": 94}, {"source": "revit-2026", "target": "trimble-connect", "weight": 3}, {"source": "revit-2026", "target": "tsd-25", "weight": 11}, {"source": "revit-2026", "target": "tsd-26", "weight": 11}, {"source": "revit-2026", "target": "web-ifc", "weight": 6}, {"source": "revit-2026", "target": "xeokit", "weight": 12}, {"source": "rhino-7", "target": "rhino-8", "weight": 3914}, {"source": "rhino-7", "target": "sketchup-2025", "weight": 82}, {"source": "rhino-7", "target": "sketchup-2026", "weight": 82}, {"source": "rhino-7", "target": "slack", "weight": 3}, {"source": "rhino-7", "target": "speckle-viewer", "weight": 30}, {"source": "rhino-7", "target": "tekla-2025", "weight": 116}, {"source": "rhino-7", "target": "tekla-2026", "weight": 118}, {"source": "rhino-7", "target": "tekla-plugin-sdk-2025", "weight": 45}, {"source": "rhino-7", "target": "tekla-plugin-sdk-2026", "weight": 45}, {"source": "rhino-7", "target": "tekla-tedds-25", "weight": 5}, {"source": "rhino-7", "target": "tekla-tedds-26", "weight": 5}, {"source": "rhino-7", "target": "thatopen-components", "weight": 21}, {"source": "rhino-7", "target": "three", "weight": 102}, {"source": "rhino-7", "target": "tsd-25", "weight": 5}, {"source": "rhino-7", "target": "tsd-26", "weight": 5}, {"source": "rhino-7", "target": "web-ifc", "weight": 7}, {"source": "rhino-7", "target": "xeokit", "weight": 11}, {"source": "rhino-8", "target": "sketchup-2025", "weight": 90}, {"source": "rhino-8", "target": "sketchup-2026", "weight": 94}, {"source": "rhino-8", "target": "slack", "weight": 4}, {"source": "rhino-8", "target": "speckle-viewer", "weight": 31}, {"source": "rhino-8", "target": "tekla", "weight": 6}, {"source": "rhino-8", "target": "tekla-2025", "weight": 118}, {"source": "rhino-8", "target": "tekla-2026", "weight": 120}, {"source": "rhino-8", "target": "tekla-plugin-sdk-2025", "weight": 46}, {"source": "rhino-8", "target": "tekla-plugin-sdk-2026", "weight": 46}, {"source": "rhino-8", "target": "tekla-tedds-25", "weight": 7}, {"source": "rhino-8", "target": "tekla-tedds-26", "weight": 7}, {"source": "rhino-8", "target": "thatopen-components", "weight": 22}, {"source": "rhino-8", "target": "three", "weight": 107}, {"source": "rhino-8", "target": "tsd-25", "weight": 5}, {"source": "rhino-8", "target": "tsd-26", "weight": 5}, {"source": "rhino-8", "target": "web-ifc", "weight": 7}, {"source": "rhino-8", "target": "xeokit", "weight": 11}, {"source": "sketchup-2025", "target": "sketchup-2026", "weight": 1126}, {"source": "sketchup-2025", "target": "speckle-viewer", "weight": 13}, {"source": "sketchup-2025", "target": "tekla-2025", "weight": 23}, {"source": "sketchup-2025", "target": "tekla-2026", "weight": 23}, {"source": "sketchup-2025", "target": "tekla-plugin-sdk-2025", "weight": 8}, {"source": "sketchup-2025", "target": "tekla-plugin-sdk-2026", "weight": 8}, {"source": "sketchup-2025", "target": "thatopen-components", "weight": 10}, {"source": "sketchup-2025", "target": "three", "weight": 31}, {"source": "sketchup-2025", "target": "xeokit", "weight": 5}, {"source": "sketchup-2026", "target": "speckle-viewer", "weight": 13}, {"source": "sketchup-2026", "target": "tekla", "weight": 3}, {"source": "sketchup-2026", "target": "tekla-2025", "weight": 23}, {"source": "sketchup-2026", "target": "tekla-2026", "weight": 23}, {"source": "sketchup-2026", "target": "tekla-plugin-sdk-2025", "weight": 8}, {"source": "sketchup-2026", "target": "tekla-plugin-sdk-2026", "weight": 8}, {"source": "sketchup-2026", "target": "thatopen-components", "weight": 10}, {"source": "sketchup-2026", "target": "three", "weight": 31}, {"source": "sketchup-2026", "target": "xeokit", "weight": 5}, {"source": "solibri-26.4.1", "target": "tsd-25", "weight": 3}, {"source": "solibri-26.4.1", "target": "tsd-26", "weight": 3}, {"source": "speckle-viewer", "target": "tekla-2025", "weight": 11}, {"source": "speckle-viewer", "target": "tekla-2026", "weight": 11}, {"source": "speckle-viewer", "target": "thatopen-components", "weight": 19}, {"source": "speckle-viewer", "target": "three", "weight": 68}, {"source": "speckle-viewer", "target": "xeokit", "weight": 6}, {"source": "tekla-2025", "target": "tekla-2026", "weight": 1237}, {"source": "tekla-2025", "target": "tekla-plugin-sdk-2025", "weight": 30}, {"source": "tekla-2025", "target": "tekla-plugin-sdk-2026", "weight": 30}, {"source": "tekla-2025", "target": "tekla-tedds-25", "weight": 5}, {"source": "tekla-2025", "target": "tekla-tedds-26", "weight": 5}, {"source": "tekla-2025", "target": "thatopen-components", "weight": 10}, {"source": "tekla-2025", "target": "three", "weight": 30}, {"source": "tekla-2025", "target": "tsd-25", "weight": 4}, {"source": "tekla-2025", "target": "tsd-26", "weight": 4}, {"source": "tekla-2025", "target": "web-ifc", "weight": 3}, {"source": "tekla-2026", "target": "tekla-plugin-sdk-2025", "weight": 31}, {"source": "tekla-2026", "target": "tekla-plugin-sdk-2026", "weight": 31}, {"source": "tekla-2026", "target": "tekla-tedds-25", "weight": 5}, {"source": "tekla-2026", "target": "tekla-tedds-26", "weight": 5}, {"source": "tekla-2026", "target": "thatopen-components", "weight": 10}, {"source": "tekla-2026", "target": "three", "weight": 30}, {"source": "tekla-2026", "target": "tsd-25", "weight": 6}, {"source": "tekla-2026", "target": "tsd-26", "weight": 6}, {"source": "tekla-2026", "target": "web-ifc", "weight": 3}, {"source": "tekla-plugin-sdk-2025", "target": "tekla-plugin-sdk-2026", "weight": 893}, {"source": "tekla-plugin-sdk-2025", "target": "three", "weight": 18}, {"source": "tekla-plugin-sdk-2025", "target": "xeokit", "weight": 4}, {"source": "tekla-plugin-sdk-2026", "target": "three", "weight": 18}, {"source": "tekla-plugin-sdk-2026", "target": "xeokit", "weight": 4}, {"source": "tekla-tedds-25", "target": "tekla-tedds-26", "weight": 50}, {"source": "thatopen-components", "target": "three", "weight": 30}, {"source": "three", "target": "tsd-25", "weight": 4}, {"source": "three", "target": "tsd-26", "weight": 4}, {"source": "three", "target": "web-ifc", "weight": 3}, {"source": "three", "target": "xeokit", "weight": 22}, {"source": "tsd-25", "target": "tsd-26", "weight": 210}];
 
 // ---- Layout / state ----
diff --git a/CLAUDE.md b/CLAUDE.md
index da8f25093..d29bd89bd 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,6 +1,6 @@
 # AWARE — Project Instructions
 
-You are working on **AWARE** (`aware-aeco/aware`) — the open-source agentic substrate for AECO. The substrate is content-complete (manifesto, decalog, specs, <!--stat:agents_total-->80<!--/stat--> agents, <!--stat:skills-->3,346<!--/stat--> skills, <!--stat:apps-->8<!--/stat--> reference apps, <!--stat:meta_primitives-->12<!--/stat--> meta-primitives) and the `aware` CLI has shipped (v<!--stat:cli_version-->0.158.0<!--/stat-->). The current focus is the **`aware` CLI** — the runtime binary that executes everything the substrate describes.
+You are working on **AWARE** (`aware-aeco/aware`) — the open-source agentic substrate for AECO. The substrate is content-complete (manifesto, decalog, specs, <!--stat:agents_total-->80<!--/stat--> agents, <!--stat:skills-->3,347<!--/stat--> skills, <!--stat:apps-->9<!--/stat--> reference apps, <!--stat:meta_primitives-->12<!--/stat--> meta-primitives) and the `aware` CLI has shipped (v<!--stat:cli_version-->0.158.0<!--/stat-->). The current focus is the **`aware` CLI** — the runtime binary that executes everything the substrate describes.
 
 ## Read these first (in order)
 
@@ -143,8 +143,8 @@ All skill creation, modification, or porting routes through Anthropic's `skill-c
 The substrate is content-complete. Do not re-litigate decisions captured in the docs above unless you have a concrete new constraint.
 
 - <!--stat:agents_total-->80<!--/stat--> agents under `20-agents/` — <!--stat:agents_curated-->33<!--/stat--> curated (tekla, trimble-connect, navisworks, microsoft-365, google-workspace, …) + <!--stat:agents_reflected-->47<!--/stat--> reflected (revit, rhino, autocad, idea-statica, …); full list in `registry-index.json`
-- <!--stat:skills-->3,346<!--/stat--> skill files
-- <!--stat:apps-->8<!--/stat--> reference apps under `30-apps/_examples/`
+- <!--stat:skills-->3,347<!--/stat--> skill files
+- <!--stat:apps-->9<!--/stat--> reference apps under `30-apps/_examples/`
 - Diagrams in `40-diagrams/` (Mermaid + Excalidraw)
 - Issue + PR templates under `.github/`
 
diff --git a/README.md b/README.md
index a50529849..ac1fa4fcb 100644
--- a/README.md
+++ b/README.md
@@ -22,7 +22,7 @@ $ aware agent install trimble-connect
   ✓ trimble-connect  · REST
 
 $ claude-code                    # or codex, or opencode — your AI is the runtime
-  ✓ plugin: aware-aeco · 80 agents · 3,346 skills
+  ✓ plugin: aware-aeco · 80 agents · 3,347 skills
 
 > From this Tekla model, export each welded assembly's drawing
 > to my Trimble Connect fab folder.
diff --git a/cli/tests/app_list.rs b/cli/tests/app_list.rs
index 5d903fc1c..df6b7e774 100644
--- a/cli/tests/app_list.rs
+++ b/cli/tests/app_list.rs
@@ -44,5 +44,6 @@ fn json_output_has_every_example_app() {
     // Mirrors every `.app` under `30-apps/_examples/`. A strict equality keeps this
     // honest — adjust it whenever an example app lands or retires.
     // 7 → 8 (`model-to-renders` — IFC in, headless still + turntable out).
-    assert_eq!(v["data"]["apps"].as_array().unwrap().len(), 8);
+    // 8 → 9 (`model-to-construction-sequence` — `blender/exec`, #692).
+    assert_eq!(v["data"]["apps"].as_array().unwrap().len(), 9);
 }
diff --git a/cli/tests/blender_exec.rs b/cli/tests/blender_exec.rs
new file mode 100644
index 000000000..7a715d8c5
--- /dev/null
+++ b/cli/tests/blender_exec.rs
@@ -0,0 +1,172 @@
+//! `blender/exec` (#692) through the real CLI: the literal-code rule at validate and compile, and
+//! a `--dry-run` that never launches Blender.
+//!
+//! Both are properties of the SHIPPED manifest (`code: { literal: true }`, `mode: write` without
+//! `mode-overridable`), so the agent is installed from the repo's own `20-agents/` copy rather
+//! than a synthetic one: a manifest edit that dropped either line must turn this file red.
+
+use assert_cmd::Command;
+use std::fs;
+use std::path::{Path, PathBuf};
+
+fn blender_agent_dir() -> PathBuf {
+    PathBuf::from(env!("CARGO_MANIFEST_DIR"))
+        .parent()
+        .expect("repo root")
+        .join("20-agents/aeco/visualization/blender")
+}
+
+/// A temporary AWARE_HOME with the repo's `blender` agent installed through `aware agent install`.
+fn blender_home() -> tempfile::TempDir {
+    let home = tempfile::tempdir().expect("temporary AWARE_HOME");
+    Command::cargo_bin("aware")
+        .expect("aware test binary")
+        .env("AWARE_HOME", home.path())
+        .args(["agent", "install"])
+        .arg(blender_agent_dir())
+        .assert()
+        .success();
+    home
+}
+
+fn app_dir(name: &str, body: &str) -> tempfile::TempDir {
+    let app = tempfile::tempdir().expect("temporary app directory");
+    fs::write(app.path().join(format!("{name}.flo")), body).expect("write the app");
+    app
+}
+
+fn run_aware(home: &Path, args: &[&str], target: &Path, envs: &[(&str, &Path)]) -> (bool, String) {
+    let mut cmd = Command::cargo_bin("aware").expect("aware test binary");
+    cmd.env("AWARE_HOME", home).args(args).arg(target);
+    for (k, v) in envs {
+        cmd.env(k, v);
+    }
+    let out = cmd.output().expect("run aware");
+    let mut text = String::from_utf8_lossy(&out.stdout).into_owned();
+    text.push_str(&String::from_utf8_lossy(&out.stderr));
+    (out.status.success(), text)
+}
+
+/// An app with one `blender/exec` node whose `code` is `code_yaml` (already YAML-quoted).
+fn exec_app(name: &str, code_yaml: &str) -> String {
+    format!(
+        "app: {name}\nversion: 0.1.0\ndescription: exec probe\nrequires:\n  - blender@0.2.x\n\
+         nodes:\n  - id: animate\n    agent: blender\n    command: exec\n    inputs:\n      \
+         output-dir: out\n      args:\n        storeys: '{{{{ inputs.storeys }}}}'\n      \
+         code: {code_yaml}\n    safety:\n      transaction-group: probe\n      snapshot: false\n\
+         connections: []\n"
+    )
+}
+
+const LITERAL_CODE: &str =
+    "|\n        # Returns a constant.\n        def run(ctx):\n            return 1\n";
+
+#[test]
+fn validate_and_compile_refuse_templated_code_and_accept_literal_code() {
+    let home = blender_home();
+
+    let templated = app_dir(
+        "exec-templated",
+        &exec_app("exec-templated", "'{{ inputs.code }}'"),
+    );
+    let (ok, text) = run_aware(home.path(), &["app", "validate"], templated.path(), &[]);
+    assert!(!ok, "templated code must fail validate; got:\n{text}");
+    assert!(text.contains("E_APP_INPUT_MUST_BE_LITERAL"), "{text}");
+    assert!(
+        text.contains("\"animate\""),
+        "the error must name the node:\n{text}"
+    );
+    assert!(
+        text.contains("`code`"),
+        "the error must name the input:\n{text}"
+    );
+
+    let (ok, text) = run_aware(home.path(), &["app", "compile"], templated.path(), &[]);
+    assert!(!ok, "templated code must fail compile; got:\n{text}");
+    assert!(text.contains("E_APP_INPUT_MUST_BE_LITERAL"), "{text}");
+    assert!(
+        !templated.path().join("exec-templated.lock").exists(),
+        "a refused compile must write no lock"
+    );
+
+    // Literal code beside TEMPLATED args (data, not code) is the supported shape.
+    let literal = app_dir("exec-literal", &exec_app("exec-literal", LITERAL_CODE));
+    let (ok, text) = run_aware(home.path(), &["app", "validate"], literal.path(), &[]);
+    assert!(
+        ok,
+        "literal code with templated args must validate; got:\n{text}"
+    );
+    let (ok, text) = run_aware(home.path(), &["app", "compile"], literal.path(), &[]);
+    assert!(
+        ok,
+        "literal code with templated args must compile; got:\n{text}"
+    );
+    assert!(literal.path().join("exec-literal.lock").is_file());
+}
+
+/// `exec` is write-mode and NOT mode-overridable, so `--dry-run` reports a would-write and never
+/// spawns Blender. The stand-in `AWARE_BLENDER` leaves a marker file if anything launches it —
+/// the assertion is on that marker, not on the run's own say-so.
+#[test]
+fn a_dry_run_of_exec_never_launches_blender() {
+    let home = blender_home();
+    let scratch = tempfile::tempdir().expect("scratch");
+    let marker = scratch.path().join("blender-was-launched");
+    let fake = if cfg!(windows) {
+        let path = scratch.path().join("fake-blender.cmd");
+        fs::write(
+            &path,
+            format!(
+                "@echo off\r\necho launched> \"{}\"\r\nexit /b 1\r\n",
+                marker.display()
+            ),
+        )
+        .expect("write fake");
+        path
+    } else {
+        let path = scratch.path().join("fake-blender");
+        fs::write(
+            &path,
+            format!(
+                "#!/bin/sh\necho launched > '{}'\nexit 1\n",
+                marker.display()
+            ),
+        )
+        .expect("write fake");
+        #[cfg(unix)]
+        {
+            use std::os::unix::fs::PermissionsExt;
+            fs::set_permissions(&path, fs::Permissions::from_mode(0o755)).expect("chmod");
+        }
+        path
+    };
+
+    let app = app_dir("exec-dry", &exec_app("exec-dry", LITERAL_CODE));
+    let flo = app.path().join("exec-dry.flo");
+    let (ok, text) = run_aware(home.path(), &["app", "compile"], &flo, &[]);
+    assert!(ok, "compile: {text}");
+    let (ok, text) = run_aware(home.path(), &["app", "install"], app.path(), &[]);
+    assert!(ok, "install: {text}");
+
+    let mut cmd = Command::cargo_bin("aware").expect("aware test binary");
+    let out = cmd
+        .env("AWARE_HOME", home.path())
+        .env("AWARE_BLENDER", &fake)
+        .args(["app", "run", "exec-dry", "--dry-run"])
+        .output()
+        .expect("run aware");
+    let text = format!(
+        "{}{}",
+        String::from_utf8_lossy(&out.stdout),
+        String::from_utf8_lossy(&out.stderr)
+    );
+    assert!(out.status.success(), "dry run failed:\n{text}");
+    assert!(
+        !marker.exists(),
+        "--dry-run launched Blender (the stand-in left its marker):\n{text}"
+    );
+    assert!(
+        text.contains("would-write") || text.contains("would write"),
+        "the dry run must report the exec node as a would-write:\n{text}"
+    );
+}
diff --git a/docs/superpowers/plans/2026-07-22-blender-visualization-agent.md b/docs/superpowers/plans/2026-07-22-blender-visualization-agent.md
index dfc005d8d..e4f0ef7f6 100644
--- a/docs/superpowers/plans/2026-07-22-blender-visualization-agent.md
+++ b/docs/superpowers/plans/2026-07-22-blender-visualization-agent.md
@@ -2430,7 +2430,7 @@ description: |
 exposes-as-agent: false
 
 requires:
-  - blender@0.1.x
+  - blender@0.2.x
 
 requires-permissions:
   filesystem:
diff --git a/registry-index.json b/registry-index.json
index 4bcbafba8..a2346aea3 100644
--- a/registry-index.json
+++ b/registry-index.json
@@ -704,8 +704,8 @@
     "blender": {
       "versions": {
         "0.1.0": {
-          "tarball": "https://github.com/aware-aeco/aware/archive/refs/heads/main.tar.gz",
-          "subdir": "aware-main/20-agents/aeco/visualization/blender",
+          "tarball": "https://github.com/aware-aeco/aware/archive/c1b293ffc1c3f8ab7c35482f4897fd74b5bd7ecc.tar.gz",
+          "subdir": "aware-c1b293ffc1c3f8ab7c35482f4897fd74b5bd7ecc/20-agents/aeco/visualization/blender",
           "manifest-agent": "blender",
           "manifest-version": "0.1.0",
           "bundle-digest": "sha256:d9e00fe381ef938e5cf12f0e315378632ff4f70a5125e082ead976e0d7793814"

From 70b7483dda129e605b045be968c0c0071f982042 Mon Sep 17 00:00:00 2001
From: Pawel Lisowski <pawellisowski@o2.pl>
Date: Mon, 12 Oct 2026 10:13:46 +0200
Subject: [PATCH 04/17] fix(blender): an abandoned or wedged render can no
 longer outlive its call (#692 review)

Three ways the builtin runner could leave work running or report late:

- Dropping the call future (a failed trace write returning early through `?`,
  a cancelled run) left headless Blender rendering for up to timeout-seconds.
  The child is now kill_on_drop, spawned as a process-group leader on unix,
  and a TreeKillGuard (declared after the child, so it drops first) runs
  taskkill /T /F or kill -KILL -<pgid> unless the child was already reaped.
- The deadline was not checked while relay.pump() was blocked on a full
  channel (slow trace writer), so the call could run past its budget. The
  pump now runs under timeout_at(deadline), and the drain after a timeout kill
  is bounded to 2 s so a stopped consumer cannot hold the timeout error.
- The relay byte-budget test sampled `consumed` only when pump() returned
  true, missing the read of the pump that crossed the budget, so it could not
  catch an overrun. Relay keeps the last read count; the test asserts the
  real bound (budget plus one poll) and goes red when the budget check is
  removed.

Each fix has a test that fails without it (verified by reverting the fix).
---
 cli/src/render/blender.rs   | 223 ++++++++++++++++++++++++++++++++++--
 cli/src/runtime/progress.rs |  19 ++-
 2 files changed, 229 insertions(+), 13 deletions(-)

diff --git a/cli/src/render/blender.rs b/cli/src/render/blender.rs
index fe06cbca9..bc2d548f6 100644
--- a/cli/src/render/blender.rs
+++ b/cli/src/render/blender.rs
@@ -695,6 +695,50 @@ async fn kill_blender(child: &mut tokio::process::Child) {
     let _ = child.wait().await;
 }
 
+/// Kills Blender's whole process tree when the call is ABANDONED rather than finished (#692
+/// review). The run path can drop this future mid-render — a failed trace write returns early
+/// through `?`, a cancelled run drops the call — and without this a headless Blender kept
+/// rendering, GPU context and output file held, for up to `timeout-seconds`.
+///
+/// `kill_on_drop` alone ends only the direct child, which is why the tree kill mirrors
+/// [`kill_blender`]: `taskkill /T /F` on Windows, the child's own process group elsewhere (it is
+/// spawned as a group leader). The guard is declared AFTER the child so it drops first, while
+/// the tree is still intact, and it is disarmed the moment the child is reaped — after that the
+/// pid may already belong to someone else.
+struct TreeKillGuard {
+    pid: Option<u32>,
+}
+
+impl TreeKillGuard {
+    fn disarm(&mut self) {
+        self.pid = None;
+    }
+}
+
+impl Drop for TreeKillGuard {
+    fn drop(&mut self) {
+        let Some(pid) = self.pid.take() else {
+            return;
+        };
+        let mut kill = if cfg!(windows) {
+            let mut c = std::process::Command::new("taskkill");
+            c.args(["/PID", &pid.to_string(), "/T", "/F"]);
+            c
+        } else {
+            let mut c = std::process::Command::new("kill");
+            c.args(["-KILL", &format!("-{pid}")]);
+            c
+        };
+        let _ = kill
+            .stdout(std::process::Stdio::null())
+            .stderr(std::process::Stdio::null())
+            .status();
+    }
+}
+
+/// How long the progress drain after a timeout kill may take before the timeout is reported anyway.
+const TIMEOUT_DRAIN_GRACE: Duration = Duration::from_secs(2);
+
 /// The environment variable a producer appends `{"$aware-progress": …}` lines to (#405).
 const PROGRESS_ENV: &str = "AWARE_PROGRESS_FILE";
 
@@ -784,7 +828,12 @@ async fn run_script(
         .arg(inputs.arg())
         .stdin(std::process::Stdio::null())
         .stdout(std::process::Stdio::piped())
-        .stderr(std::process::Stdio::piped());
+        .stderr(std::process::Stdio::piped())
+        // The direct child dies with the call even if the guard below never runs.
+        .kill_on_drop(true);
+    // A group leader, so an abandoned call can take the whole tree down (see `TreeKillGuard`).
+    #[cfg(unix)]
+    launch.process_group(0);
     // Set ONLY when somebody reads the channel — a producer takes the variable's presence to mean
     // "the runtime is listening", exactly as on the CLI transport.
     let mut relay = match progress {
@@ -809,6 +858,8 @@ async fn run_script(
         ))
     })?;
 
+    let mut tree_guard = TreeKillGuard { pid: child.id() };
+
     // Drain both pipes concurrently with the wait: Blender is chatty enough to fill a pipe buffer
     // and deadlock against a wait-then-read.
     let stdout_task = tokio::spawn(read_to_end(child.stdout.take()));
@@ -824,25 +875,37 @@ async fn run_script(
             status = child.wait() => break Some(status),
             _ = tokio::time::sleep_until(deadline) => break None,
             _ = tokio::time::sleep(crate::runtime::progress::POLL_INTERVAL), if relay.is_some() => {
-                if let Some(relay) = relay.as_mut() {
-                    relay.pump().await;
+                // The deadline stays live WHILE pumping: a pump blocked on a full channel (a slow
+                // trace writer) must not carry the call past `timeout-seconds`.
+                if let Some(relay) = relay.as_mut()
+                    && tokio::time::timeout_at(deadline, relay.pump()).await.is_err()
+                {
+                    break None;
                 }
             }
         }
     };
 
     let status = match waited {
-        Some(status) => status.map_err(|e| {
-            AwareError::Network(format!("blender {command}: waiting on Blender failed: {e}"))
-        })?,
+        Some(status) => {
+            let status = status.map_err(|e| {
+                AwareError::Network(format!("blender {command}: waiting on Blender failed: {e}"))
+            })?;
+            // Reaped: its pid is free for reuse, so the guard must not fire on it any more.
+            tree_guard.disarm();
+            status
+        }
         None => {
             // The design doc's other required named error. Kill first, report second — a wedged
             // Blender must not outlive the call.
             kill_blender(&mut child).await;
+            tree_guard.disarm();
             // The records written before the kill are most of the diagnosis ("it reached frame
             // 140 of 240"), so they are delivered before the error, not lost with the process.
+            // Bounded, though: the call is already failing, and a consumer that stopped reading
+            // must not hold the timeout error hostage.
             if let Some(relay) = relay.as_mut() {
-                relay.drain_to_end().await;
+                let _ = tokio::time::timeout(TIMEOUT_DRAIN_GRACE, relay.drain_to_end()).await;
             }
             stdout_task.abort();
             stderr_task.abort();
@@ -1533,6 +1596,152 @@ mod tests {
         assert_eq!(seen[0].1["done"], json!(3), "{seen:?}");
     }
 
+    /// #692 review: an ABANDONED call (the run path drops the future — a failed trace write, a
+    /// cancelled run) must take Blender's whole process tree with it. The stand-in starts a
+    /// grandchild that ticks into a file every second, then hangs; killing only the direct child
+    /// would leave the grandchild ticking, so a file that keeps growing after the drop is the
+    /// failure this guards.
+    #[tokio::test]
+    async fn dropping_the_call_kills_the_whole_blender_tree() {
+        let tmp = tempfile::tempdir().expect("tempdir");
+        let ticks = tmp.path().join("ticks.txt");
+        let blender = if cfg!(windows) {
+            let ticker = tmp.path().join("ticker.cmd");
+            std::fs::write(
+                &ticker,
+                format!(
+                    "@echo off
+:loop
+>>\"{}\" echo tick
+ping -n 2 127.0.0.1 >nul
+goto loop
+",
+                    ticks.display()
+                ),
+            )
+            .expect("write ticker");
+            let path = tmp.path().join("fake-blender.cmd");
+            std::fs::write(
+                &path,
+                format!(
+                    "@echo off
+start \"\" /b cmd /c \"{}\"
+ping -n 120 127.0.0.1 >nul
+",
+                    ticker.display()
+                ),
+            )
+            .expect("write fake");
+            path
+        } else {
+            let path = tmp.path().join("fake-blender");
+            std::fs::write(
+                &path,
+                format!(
+                    "#!/bin/sh
+(while true; do echo tick >> '{}'; sleep 1; done) &
+sleep 120
+",
+                    ticks.display()
+                ),
+            )
+            .expect("write fake");
+            #[cfg(unix)]
+            {
+                use std::os::unix::fs::PermissionsExt;
+                std::fs::set_permissions(&path, std::fs::Permissions::from_mode(0o755))
+                    .expect("chmod fake blender");
+            }
+            path
+        };
+
+        let script = tmp.path().join("exec.py");
+        let args = exec_args();
+        let call = run_script(
+            "exec",
+            &blender,
+            &script,
+            &args,
+            Duration::from_secs(300),
+            BlenderProgress::Off,
+        );
+        // Abandon the call once the grandchild is demonstrably running.
+        let ticks_for_wait = ticks.clone();
+        let abandoned = tokio::time::timeout(Duration::from_secs(20), async move {
+            tokio::select! {
+                _ = call => panic!("the hanging stand-in must not finish"),
+                _ = async {
+                    while !ticks_for_wait.exists() {
+                        tokio::time::sleep(Duration::from_millis(100)).await;
+                    }
+                    tokio::time::sleep(Duration::from_millis(1_500)).await;
+                } => {}
+            }
+        })
+        .await;
+        assert!(abandoned.is_ok(), "the stand-in never started ticking");
+
+        // Let any in-flight write land, then require the file to stop growing.
+        tokio::time::sleep(Duration::from_millis(2_500)).await;
+        let settled = std::fs::read_to_string(&ticks).unwrap_or_default().len();
+        tokio::time::sleep(Duration::from_millis(3_500)).await;
+        let later = std::fs::read_to_string(&ticks).unwrap_or_default().len();
+        assert_eq!(
+            settled, later,
+            "Blender's process tree kept running after the call was dropped"
+        );
+    }
+
+    /// Codex review: the deadline must hold while the relay is pumping. A consumer that has
+    /// stopped reading (capacity-1 channel, receiver never polled) blocks `pump()` on `send`;
+    /// the timeout must still fire on time and the process tree still die.
+    #[tokio::test]
+    async fn the_timeout_fires_even_while_a_full_channel_blocks_the_pump() {
+        let tmp = tempfile::tempdir().expect("tempdir");
+        let blender = fake_blender(
+            tmp.path(),
+            r#"{"$aware-progress":{"phase":"render","done":1,"total":9}}"#,
+            r#"{"$aware-progress":{"phase":"render","done":9,"total":9}}"#,
+            0,
+            120,
+            r#"{"ok": true}"#,
+        );
+        // Several records up front, so the second `send` blocks on the full channel.
+        let channel = tmp.path().join("progress-full.jsonl");
+        let mut burst = String::new();
+        for done in 1..=5 {
+            burst.push_str(&format!(
+                "{{\"$aware-progress\":{{\"phase\":\"render\",\"done\":{done},\"total\":9}}}}
+"
+            ));
+        }
+        std::fs::write(&channel, burst).expect("pre-seed channel");
+        let (tx, _rx_never_read) = mpsc::channel::<Value>(1);
+
+        let started = std::time::Instant::now();
+        let outcome = tokio::time::timeout(
+            Duration::from_secs(20),
+            run_script(
+                "exec",
+                &blender,
+                &tmp.path().join("exec.py"),
+                &exec_args(),
+                Duration::from_millis(1_500),
+                BlenderProgress::Relay { path: channel, tx },
+            ),
+        )
+        .await;
+        let err = outcome
+            .expect("a blocked pump must not hold the call past its timeout")
+            .expect_err("the wedged stand-in must time out");
+        assert!(err.to_string().contains("timed out"), "{err}");
+        assert!(
+            started.elapsed() < Duration::from_secs(10),
+            "took {:?}",
+            started.elapsed()
+        );
+    }
+
     #[tokio::test]
     async fn a_caller_channel_is_passed_through_to_blender() {
         // Passthrough (`aware agent invoke` under FloLess): Blender writes to the CALLER's file
diff --git a/cli/src/runtime/progress.rs b/cli/src/runtime/progress.rs
index 731a1080d..77a6020b7 100644
--- a/cli/src/runtime/progress.rs
+++ b/cli/src/runtime/progress.rs
@@ -206,6 +206,9 @@ pub struct Relay {
     tail: Option<ProgressTail>,
     tx: mpsc::Sender<Value>,
     sent: usize,
+    /// Bytes of the channel read so far — kept past the point the tail is dropped, so what the
+    /// pump that crossed a budget read is still observable.
+    read: u64,
 }
 
 impl Relay {
@@ -215,6 +218,7 @@ impl Relay {
             tail: Some(ProgressTail::new(path)),
             tx,
             sent: 0,
+            read: 0,
         }
     }
 
@@ -257,6 +261,7 @@ impl Relay {
         let before = tail.consumed();
         let records = tail.drain().await;
         let advanced = tail.consumed() > before;
+        self.read = tail.consumed();
         let over_budget = tail.consumed() > Self::MAX_CHANNEL_BYTES;
         for record in records {
             if self.sent >= Self::MAX_RECORDS {
@@ -370,19 +375,21 @@ mod tests {
             seen
         });
         let mut relay = Relay::new(&path, tx);
-        let mut read = 0;
-        while relay.pump().await {
-            read = relay.tail.as_ref().map(|t| t.consumed()).unwrap_or(read);
-        }
+        while relay.pump().await {}
         assert!(relay.tail.is_none(), "the relay kept reading the noise");
+        // Taken AFTER the pump that crossed the budget, which is the read the bound is about:
+        // that pump may read one more poll's worth, and nothing after it may read at all.
+        let read = relay.read;
         drop(relay);
 
         let seen = collector.await.unwrap();
         assert_eq!(seen.len(), 1, "expected only the suppression notice");
         assert_eq!(seen[0]["phase"], "progress-suppressed");
         assert!(
-            read <= Relay::MAX_CHANNEL_BYTES + MAX_RECORD_BYTES as u64,
-            "read {read} bytes of a channel it had already given up on"
+            read > Relay::MAX_CHANNEL_BYTES
+                && read <= Relay::MAX_CHANNEL_BYTES + MAX_DRAIN_BYTES as u64,
+            "read {read} bytes: the budget is {} plus at most one {MAX_DRAIN_BYTES}-byte poll",
+            Relay::MAX_CHANNEL_BYTES
         );
     }
 

From 3c9dd1f6b2d4f9a2b6ad36cc575db280e006c756 Mon Sep 17 00:00:00 2001
From: Pawel Lisowski <pawellisowski@o2.pl>
Date: Mon, 12 Oct 2026 10:13:47 +0200
Subject: [PATCH 05/17] fix(blender): runs leave the stored package untouched;
 exec receipts and errors stay honest (#692 review)

- Blocker: importing the helpers wrote scripts/__pycache__ INTO the immutable
  stored package (#626), so the next `aware app compile` refused it with
  E_AGENT_STORE_INVALID. Every entry script now sets
  sys.dont_write_bytecode = True before any helper import (Blender honours
  it; no launch flags change). test_package_stays_immutable.py checks it
  statically and by launching every command from a scratch package copy.
- Progress budget: coalescing was per pass but the runtime's 10,000-record
  cap is per invocation, so three 4,000-frame passes hit progress-suppressed
  in pass 3. _progress keeps a per-invocation budget of 9,000 records and
  each pass sizes its stride from what is left; every pass still reports its
  last frame.
- render_animation/render_still verify only a file written by THIS render
  (mtime at or after its start), in both the exact-name and frame-suffixed
  branches, so an earlier run's file at the target is never passed off.
- A NaN/Infinity result is exec-error (json allow_nan=False), not an
  unparseable frame the transport reports as its own failure.
- A corrupt .blend is blend-unreadable, not unexpected-error.
---
 .../blender/scripts/_exec_ctx.py              |  36 ++++-
 .../blender/scripts/_progress.py              |  44 ++++--
 .../visualization/blender/scripts/exec.py     |  22 ++-
 .../blender/scripts/render_still.py           |   8 +-
 .../blender/scripts/render_turntable.py       |   8 +-
 .../blender/scripts/scene_apply_look.py       |   8 +-
 .../blender/scripts/scene_import.py           |   8 +-
 .../blender/scripts/scene_info.py             |   8 +-
 .../visualization/blender/tests/test_exec.py  |  80 ++++++++++
 .../tests/test_package_stays_immutable.py     | 138 ++++++++++++++++++
 10 files changed, 336 insertions(+), 24 deletions(-)
 create mode 100644 20-agents/aeco/visualization/blender/tests/test_package_stays_immutable.py

diff --git a/20-agents/aeco/visualization/blender/scripts/_exec_ctx.py b/20-agents/aeco/visualization/blender/scripts/_exec_ctx.py
index b02240981..786fdcb8f 100644
--- a/20-agents/aeco/visualization/blender/scripts/_exec_ctx.py
+++ b/20-agents/aeco/visualization/blender/scripts/_exec_ctx.py
@@ -51,6 +51,18 @@ def _same_or_inside(path: str, root: str) -> bool:
         return False
 
 
+# Slack for filesystems with coarse mtimes (FAT: 2 s). A file older than the
+# render's start by more than this was not written by it.
+MTIME_SLACK_SECONDS = 1.0
+
+
+def _written_since(path: str, started: float) -> bool:
+    try:
+        return os.path.getmtime(path) >= started - MTIME_SLACK_SECONDS
+    except OSError:
+        return False
+
+
 def eevee_engine() -> str:
     """EEVEE's identifier on this Blender (renamed BLENDER_EEVEE_NEXT in 4.2, back in 5.x)."""
     identifiers = {
@@ -158,8 +170,13 @@ def _resolve(self, path: str) -> str:
             path = os.path.join(self.output_dir, path)
         return os.path.abspath(path)
 
-    def _verified(self, path: str, kind: str, **extra) -> dict:
-        """Check one file and append its receipt entry."""
+    def _verified(self, path: str, kind: str, written_after: float | None = None, **extra) -> dict:
+        """Check one file and append its receipt entry.
+
+        `written_after` (a `time.time()` taken before a render) additionally
+        requires the file to be newer than that render's start, so a file left
+        by an EARLIER run at the same path is never passed off as this one's.
+        """
         entry = {"path": os.path.abspath(path), "kind": kind}
         entry.update(extra)
         reason = None
@@ -180,6 +197,8 @@ def _verified(self, path: str, kind: str, **extra) -> dict:
                 reason = f"is outside output-dir ({self.output_dir})"
             elif size <= 0:
                 reason = "is empty"
+            elif written_after is not None and not _written_since(real, written_after):
+                reason = "was not written by this render (an older file is at that path)"
         entry["verified"] = reason is None
         if reason is not None:
             entry["reason"] = reason
@@ -221,9 +240,10 @@ def render_still(self, path: str, quality: str = "draft", samples=None) -> dict:
         scene.render.image_settings.file_format = "PNG"
         scene.render.filepath = target
         os.makedirs(os.path.dirname(target), exist_ok=True)
+        started = time.time()
         with _progress.FrameCounter(1, self._next_pass_label()):
             bpy.ops.render.render(write_still=True)
-        return self._verified(target, "image")
+        return self._verified(target, "image", written_after=started)
 
     def render_animation(self, path: str, quality: str = "draft", samples=None) -> dict:
         """Render the scene's frame range to an H.264 MP4 at `path`.
@@ -255,9 +275,11 @@ def render_animation(self, path: str, quality: str = "draft", samples=None) -> d
         self.frames += counter.done
 
         # Blender may append the frame range to a container name; find what
-        # THIS render wrote (newer than its start), never an older file.
+        # THIS render wrote. In BOTH branches the file must be newer than the
+        # render's start: a target left by an earlier run, with Blender writing
+        # a suffixed file beside it, must not be verified in its place.
         written = target
-        if not os.path.exists(written):
+        if not (os.path.isfile(written) and _written_since(written, started)):
             directory = os.path.dirname(target)
             stem = os.path.splitext(os.path.basename(target))[0]
             candidates = [
@@ -265,8 +287,8 @@ def render_animation(self, path: str, quality: str = "draft", samples=None) -> d
                 for name in os.listdir(directory)
                 if name.startswith(stem)
                 and name.lower().endswith(".mp4")
-                and os.path.getmtime(os.path.join(directory, name)) >= started - 1
+                and _written_since(os.path.join(directory, name), started)
             ]
             if candidates:
                 written = max(candidates, key=os.path.getmtime)
-        return self._verified(written, "video", frames=counter.done)
+        return self._verified(written, "video", written_after=started, frames=counter.done)
diff --git a/20-agents/aeco/visualization/blender/scripts/_progress.py b/20-agents/aeco/visualization/blender/scripts/_progress.py
index 972a5cd8e..8718e9e92 100644
--- a/20-agents/aeco/visualization/blender/scripts/_progress.py
+++ b/20-agents/aeco/visualization/blender/scripts/_progress.py
@@ -40,11 +40,20 @@
 MAX_PHASE_CHARS = 64
 MAX_MESSAGE_CHARS = 512
 
-# The runtime stops mirroring after 10,000 records from one invocation. Above
-# this many frames a pass reports every ceil(total / COALESCE_ABOVE)-th frame
-# plus the last, so the cap is never why progress stops.
+# The runtime stops mirroring after 10,000 records from one INVOCATION (and says
+# `progress-suppressed`). One Blender process is one invocation, so this module
+# keeps a per-process budget below that cap, and each render pass sizes its
+# stride from what is left of it: three 4,000-frame passes report 4,000, 4,000
+# and then every 4th frame of the third, instead of running into the cap mid-pass.
+INVOCATION_BUDGET = 9_000
+
+# Even with budget to spare, one pass reports at most this many records: above
+# it, every ceil(total / allowance)-th frame plus the last.
 COALESCE_ABOVE = 5_000
 
+# Records written so far by this process (= this invocation).
+_emitted = 0
+
 # (major, minor) versions on which `render_write` was measured to fire once per
 # written frame. See the module docstring before adding one.
 COUNTED_VERSIONS = {(5, 2)}
@@ -83,11 +92,23 @@ def line(body: dict) -> str:
     return text
 
 
+def remaining() -> int:
+    """Records this invocation may still write before its budget is spent."""
+    return max(0, INVOCATION_BUDGET - _emitted)
+
+
 def emit(phase, done=None, total=None, message=None) -> None:
-    """Append one record to the channel. A no-op without `AWARE_PROGRESS_FILE`."""
+    """Append one record to the channel. A no-op without `AWARE_PROGRESS_FILE`.
+
+    Past `INVOCATION_BUDGET` records are dropped here rather than sent to be
+    suppressed by the runtime: frame counters size themselves to fit, so only a
+    flood of hand-written `ctx.progress` calls can reach the limit.
+    """
+    global _emitted
     path = os.environ.get(ENV)
-    if not path:
+    if not path or _emitted >= INVOCATION_BUDGET:
         return
+    _emitted += 1
     text = line(record(phase, done, total, message))
     try:
         # Open-append-close per record: each line is flushed and on disk before the
@@ -107,9 +128,12 @@ def counting_supported(version=None) -> bool:
     return tuple(version[:2]) in COUNTED_VERSIONS
 
 
-def stride_for(total: int) -> int:
-    """Report every `stride`-th frame, so one pass never exceeds ~COALESCE_ABOVE records."""
-    return math.ceil(total / COALESCE_ABOVE) if total > COALESCE_ABOVE else 1
+def stride_for(total: int, budget: int | None = None) -> int:
+    """Report every `stride`-th frame (plus the last) so a pass writes at most
+    min(COALESCE_ABOVE, budget) records -- i.e. ceil(total / stride) of them."""
+    allowance = COALESCE_ABOVE if budget is None else min(COALESCE_ABOVE, budget)
+    allowance = max(1, allowance)
+    return math.ceil(total / allowance) if total > allowance else 1
 
 
 class FrameCounter:
@@ -128,7 +152,9 @@ def __init__(self, total: int, label: str, counted: bool | None = None):
         self.total = max(0, int(total))
         self.label = label
         self.counted = counting_supported() if counted is None else counted
-        self.stride = stride_for(self.total)
+        # Sized from what this INVOCATION has left, not per pass: the runtime's
+        # record cap counts every pass of the call together.
+        self.stride = stride_for(self.total, remaining())
         self.done = 0
         self.completed = False
         self.cancelled = False
diff --git a/20-agents/aeco/visualization/blender/scripts/exec.py b/20-agents/aeco/visualization/blender/scripts/exec.py
index d6b7a6e1d..8a3280a52 100644
--- a/20-agents/aeco/visualization/blender/scripts/exec.py
+++ b/20-agents/aeco/visualization/blender/scripts/exec.py
@@ -24,10 +24,16 @@
 `result-too-large`, telling the author to write a file and `ctx.add_output` it.
 """
 
+import sys
+
+# First, before any helper import: these scripts run from the agent's immutable
+# stored package (#626), and a `__pycache__` written beside them changes the
+# package's hash, so the next compile refuses it (E_AGENT_STORE_INVALID).
+sys.dont_write_bytecode = True
+
 import json
 import linecache
 import os
-import sys
 import traceback
 
 sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
@@ -73,7 +79,14 @@ def prepare_scene(inputs: dict) -> dict:
                 _result.ERR_BLEND_UNREADABLE, f".blend not found: {blend_path}"
             )
         _progress.emit("import", message=f"opening {os.path.basename(str(blend_path))}")
-        bpy.ops.wm.open_mainfile(filepath=os.path.abspath(str(blend_path)))
+        try:
+            bpy.ops.wm.open_mainfile(filepath=os.path.abspath(str(blend_path)))
+        except RuntimeError as exc:
+            raise _result.AwareBlenderError(
+                _result.ERR_BLEND_UNREADABLE,
+                f"cannot open {blend_path}: {exc}",
+                "check the file is a .blend saved by Blender 4.2 or later",
+            ) from exc
         return {"source": "blend-path", "path": os.path.abspath(str(blend_path))}
 
     if not ifc_path:
@@ -210,7 +223,10 @@ def main(inputs: dict) -> dict:
         raise _exec_error(exc, code) from exc
 
     try:
-        serialized = json.dumps(result, sort_keys=True)
+        # allow_nan=False: NaN/Infinity are not JSON, and letting them through
+        # framed a payload the transport cannot parse -- a transport error in
+        # place of the author's exec-error.
+        serialized = json.dumps(result, sort_keys=True, allow_nan=False)
     except (TypeError, ValueError) as exc:
         raise _result.AwareBlenderError(
             ERR_EXEC,
diff --git a/20-agents/aeco/visualization/blender/scripts/render_still.py b/20-agents/aeco/visualization/blender/scripts/render_still.py
index 5263ae182..f5baa42bf 100644
--- a/20-agents/aeco/visualization/blender/scripts/render_still.py
+++ b/20-agents/aeco/visualization/blender/scripts/render_still.py
@@ -3,9 +3,15 @@
 Run: blender -b -P render_still.py -- '{"blend-path":"m.blend","output-path":"o.png"}'
 """
 
-import os
 import sys
 
+# First, before any helper import: these scripts run from the agent's immutable
+# stored package (#626), and a `__pycache__` written beside them changes the
+# package's hash, so the next compile refuses it (E_AGENT_STORE_INVALID).
+sys.dont_write_bytecode = True
+
+import os
+
 sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
 
 import bpy  # noqa: E402
diff --git a/20-agents/aeco/visualization/blender/scripts/render_turntable.py b/20-agents/aeco/visualization/blender/scripts/render_turntable.py
index 662d544b5..2ce34c74a 100644
--- a/20-agents/aeco/visualization/blender/scripts/render_turntable.py
+++ b/20-agents/aeco/visualization/blender/scripts/render_turntable.py
@@ -7,9 +7,15 @@
 Run: blender -b -P render_turntable.py -- '{"blend-path":"m.blend","output-path":"o.mp4"}'
 """
 
+import sys
+
+# First, before any helper import: these scripts run from the agent's immutable
+# stored package (#626), and a `__pycache__` written beside them changes the
+# package's hash, so the next compile refuses it (E_AGENT_STORE_INVALID).
+sys.dont_write_bytecode = True
+
 import math
 import os
-import sys
 
 sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
 
diff --git a/20-agents/aeco/visualization/blender/scripts/scene_apply_look.py b/20-agents/aeco/visualization/blender/scripts/scene_apply_look.py
index 7409b27b2..06623aecc 100644
--- a/20-agents/aeco/visualization/blender/scripts/scene_apply_look.py
+++ b/20-agents/aeco/visualization/blender/scripts/scene_apply_look.py
@@ -3,9 +3,15 @@
 Run: blender -b -P scene_apply_look.py -- '{"blend-path":"m.blend","preset":"realistic"}'
 """
 
-import os
 import sys
 
+# First, before any helper import: these scripts run from the agent's immutable
+# stored package (#626), and a `__pycache__` written beside them changes the
+# package's hash, so the next compile refuses it (E_AGENT_STORE_INVALID).
+sys.dont_write_bytecode = True
+
+import os
+
 sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
 
 import bpy  # noqa: E402
diff --git a/20-agents/aeco/visualization/blender/scripts/scene_import.py b/20-agents/aeco/visualization/blender/scripts/scene_import.py
index d797d3fef..6781cf497 100644
--- a/20-agents/aeco/visualization/blender/scripts/scene_import.py
+++ b/20-agents/aeco/visualization/blender/scripts/scene_import.py
@@ -3,9 +3,15 @@
 Run: blender -b -P scene_import.py -- '{"ifc-path":"m.ifc","blend-path":"m.blend"}'
 """
 
-import os
 import sys
 
+# First, before any helper import: these scripts run from the agent's immutable
+# stored package (#626), and a `__pycache__` written beside them changes the
+# package's hash, so the next compile refuses it (E_AGENT_STORE_INVALID).
+sys.dont_write_bytecode = True
+
+import os
+
 sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
 
 import bpy  # noqa: E402
diff --git a/20-agents/aeco/visualization/blender/scripts/scene_info.py b/20-agents/aeco/visualization/blender/scripts/scene_info.py
index cda6d1840..76b05d93f 100644
--- a/20-agents/aeco/visualization/blender/scripts/scene_info.py
+++ b/20-agents/aeco/visualization/blender/scripts/scene_info.py
@@ -21,9 +21,15 @@
 falsely assert nothing was ever dropped or excluded.
 """
 
-import os
 import sys
 
+# First, before any helper import: these scripts run from the agent's immutable
+# stored package (#626), and a `__pycache__` written beside them changes the
+# package's hash, so the next compile refuses it (E_AGENT_STORE_INVALID).
+sys.dont_write_bytecode = True
+
+import os
+
 sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
 
 import bpy  # noqa: E402
diff --git a/20-agents/aeco/visualization/blender/tests/test_exec.py b/20-agents/aeco/visualization/blender/tests/test_exec.py
index b7354aef9..edb669941 100644
--- a/20-agents/aeco/visualization/blender/tests/test_exec.py
+++ b/20-agents/aeco/visualization/blender/tests/test_exec.py
@@ -39,6 +39,8 @@
 import tempfile
 from pathlib import Path
 
+sys.dont_write_bytecode = True  # importing from scripts/ must not write into the package
+
 HERE = Path(__file__).resolve().parent
 SCRIPTS = HERE.parent / "scripts"
 sys.path.insert(0, str(SCRIPTS))
@@ -142,6 +144,32 @@ def check_progress_writer(work: Path) -> None:
         worst // _progress.stride_for(worst) + 1 <= 10_000,
         _progress.stride_for(worst),
     )
+    # The runtime's 10,000-record cap is per INVOCATION, so several long passes
+    # must share one budget: three 4,000-frame passes would be 12,000 records
+    # if each pass coalesced only against itself.
+    budget_channel = work / "budget-progress.jsonl"
+    os.environ[_progress.ENV] = str(budget_channel)
+    _progress._emitted = 0
+    try:
+        for index in range(3):
+            counter = _progress.FrameCounter(4000, f"pass {index + 1} of 3", counted=True)
+            for _ in range(4000):
+                counter._on_write()
+    finally:
+        os.environ.pop(_progress.ENV, None)
+        _progress._emitted = 0
+    records = progress_records(budget_channel)
+    check(
+        "three 4,000-frame passes stay inside the invocation budget",
+        len(records) <= _progress.INVOCATION_BUDGET < 10_000,
+        len(records),
+    )
+    finals = [r for r in records if r.get("done") == r.get("total") == 4000]
+    check(
+        "...and every pass still reports its last frame",
+        [r["message"] for r in finals] == ["pass 1 of 3", "pass 2 of 3", "pass 3 of 3"],
+        finals,
+    )
     check("5.2 is a measured version", _progress.counting_supported((5, 2, 0)))
     check("4.2 is NOT a measured version", not _progress.counting_supported((4, 2, 0)))
 
@@ -210,6 +238,32 @@ def run(ctx):
     return {"names": sorted(o.name for o in bpy.data.objects)}
 """
 
+NAN_RESULT = """\
+def run(ctx):
+    return {"ratio": float("nan")}
+"""
+
+STALE_TARGET = """\
+import os
+import bpy
+
+def run(ctx):
+    # A file an EARLIER run left at the target path, long ago.
+    stale = os.path.join(ctx.output_dir, "seq")
+    with open(stale, "w") as handle:
+        handle.write("left by an earlier run")
+    os.utime(stale, (1_000_000_000, 1_000_000_000))
+    bpy.ops.mesh.primitive_cube_add(size=2)
+    s = ctx.scene
+    s.render.resolution_x = 32
+    s.render.resolution_y = 32
+    s.frame_start, s.frame_end = 1, 2
+    sun = bpy.data.objects.new("Sun", bpy.data.lights.new("Sun", "SUN"))
+    s.collection.objects.link(sun)
+    # No extension: Blender writes a frame-suffixed seq0001-0002.mp4 beside it.
+    return {"video": ctx.render_animation("seq"), "stale": stale}
+"""
+
 ANIMATION = """\
 import bpy
 
@@ -300,6 +354,32 @@ def check_exec(blender: str, work: Path) -> None:
     check("...as result-too-large", payload.get("code") == "result-too-large", payload.get("code"))
     check("...telling the author to add_output a file", "add_output" in payload.get("hint", ""), payload.get("hint"))
 
+    # -- NaN is not JSON: exec-error, not a transport failure ---------------------------
+    payload = run_exec(blender, work, {"code": NAN_RESULT, "output-dir": str(out_dir)})
+    check("a NaN result fails as exec-error", payload.get("code") == "exec-error", payload)
+    check("...saying JSON cannot carry it", "JSON" in payload.get("message", ""), payload.get("message"))
+
+    # -- a corrupt .blend is blend-unreadable -------------------------------------------
+    corrupt = work / "corrupt.blend"
+    corrupt.write_bytes(b"this is not a blend file" * 64)
+    payload = run_exec(
+        blender, work, {"code": OPEN_BLEND, "blend-path": str(corrupt), "output-dir": str(out_dir)}
+    )
+    check("a corrupt .blend fails as blend-unreadable", payload.get("code") == "blend-unreadable", payload)
+
+    # -- a stale file at the target path is never verified as this render's ---------------
+    payload = run_exec(blender, work, {"code": STALE_TARGET, "output-dir": str(work / "stale-out")})
+    check("the stale-target render succeeds", payload.get("ok") is True, payload)
+    video = (payload.get("result") or {}).get("video", {})
+    stale = (payload.get("result") or {}).get("stale", "")
+    check(
+        "the receipt names the MP4 this render wrote, not the earlier run's file",
+        video.get("path", "").lower().endswith(".mp4")
+        and Path(video.get("path", "")).resolve() != Path(stale).resolve(),
+        video,
+    )
+    check("...and verifies it", video.get("verified") is True, video)
+
     # -- blend-path scene init ----------------------------------------------------------
     saved = run_exec(blender, work, {"code": SAVE_BLEND, "output-dir": str(out_dir)})
     blend = (saved.get("result") or {}).get("saved")
diff --git a/20-agents/aeco/visualization/blender/tests/test_package_stays_immutable.py b/20-agents/aeco/visualization/blender/tests/test_package_stays_immutable.py
new file mode 100644
index 000000000..96c31b6c0
--- /dev/null
+++ b/20-agents/aeco/visualization/blender/tests/test_package_stays_immutable.py
@@ -0,0 +1,138 @@
+"""Running a command must not write into the agent's package (#692 review).
+
+On a run, the scripts execute from the agent's immutable stored package
+(`agent-store-v2/...`, #626), whose files are hashed at snapshot time. Python
+caches bytecode in a `__pycache__` next to every helper it imports, so one run
+used to change the package's hash and the NEXT `aware app compile` refused the
+store with E_AGENT_STORE_INVALID.
+
+Two checks:
+
+1. Static, no Blender needed: every command entry script (a `scripts/*.py` not
+   starting with `_`) sets `sys.dont_write_bytecode = True` before importing
+   anything but `sys` -- after the first helper import it is too late.
+2. Real Blender: copy `scripts/` to a scratch "package", launch every entry
+   script from it exactly as the transport does (`blender -b -P <script> --
+   @inputs`), and require that no `__pycache__` (or any other new file)
+   appears in it. Inputs are `{}`, so each command imports all its helpers
+   and then fails cleanly on validation -- the import is what writes bytecode.
+
+Run: python test_package_stays_immutable.py [--blender <path>]
+Exits 0 on pass, 1 on failure, 77 (SKIP) for the Blender half when no Blender
+is found (the static half still runs and can still fail).
+"""
+
+import argparse
+import ast
+import json
+import shutil
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+sys.dont_write_bytecode = True  # this harness imports from scripts/ too
+
+HERE = Path(__file__).resolve().parent
+SCRIPTS = HERE.parent / "scripts"
+sys.path.insert(0, str(HERE))
+
+from run_smoke import resolve_blender  # noqa: E402
+
+SKIP_EXIT = 77
+FAILURES: list[str] = []
+
+
+def check(label: str, condition: bool, detail=None) -> None:
+    if condition:
+        print(f"  ok   {label}")
+    else:
+        print(f"  FAIL {label}")
+        if detail is not None:
+            print(f"       {detail}")
+        FAILURES.append(label)
+
+
+def entry_scripts() -> list[Path]:
+    return sorted(p for p in SCRIPTS.glob("*.py") if not p.name.startswith("_"))
+
+
+def sets_flag_before_other_imports(source: str) -> bool:
+    module = ast.parse(source)
+    for statement in module.body:
+        if isinstance(statement, ast.Expr) and isinstance(statement.value, ast.Constant):
+            continue  # the docstring
+        if isinstance(statement, ast.Import) and [a.name for a in statement.names] == ["sys"]:
+            continue
+        if (
+            isinstance(statement, ast.Assign)
+            and len(statement.targets) == 1
+            and ast.unparse(statement.targets[0]) == "sys.dont_write_bytecode"
+            and isinstance(statement.value, ast.Constant)
+            and statement.value.value is True
+        ):
+            return True
+        return False  # anything else first -- an import, a path insert -- is too late
+    return False
+
+
+def snapshot(root: Path) -> set[str]:
+    return {str(p.relative_to(root)) for p in root.rglob("*")}
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--blender", help="path to the Blender executable")
+    opts = parser.parse_args()
+
+    entries = entry_scripts()
+    print("static: every entry script disables bytecode first")
+    check("there are entry scripts to check", len(entries) >= 6, [p.name for p in entries])
+    for path in entries:
+        check(
+            f"{path.name} sets sys.dont_write_bytecode before any other import",
+            sets_flag_before_other_imports(path.read_text(encoding="utf-8")),
+        )
+
+    blender = resolve_blender(opts.blender)
+    if blender is None:
+        if FAILURES:
+            print("\nPACKAGE IMMUTABLE FAIL")
+            return 1
+        print("SKIP: no Blender available (pass --blender <path> to run this harness)")
+        return SKIP_EXIT
+
+    work = Path(tempfile.mkdtemp(prefix="aware-package-"))
+    try:
+        package = work / "blender" / "scripts"
+        shutil.copytree(SCRIPTS, package, ignore=shutil.ignore_patterns("__pycache__"))
+        before = snapshot(package.parent)
+        inputs = work / "inputs.json"
+        inputs.write_text(json.dumps({}), encoding="utf-8")
+        print("real Blender: launching every command from a scratch package")
+        for path in entries:
+            proc = subprocess.run(
+                [blender, "-b", "-P", str(package / path.name), "--", f"@{inputs}"],
+                capture_output=True,
+                text=True,
+                encoding="utf-8",
+                errors="replace",
+                check=False,
+            )
+            check(
+                f"{path.name} ran and framed its result",
+                "<<<AWARE_RESULT>>>" in proc.stdout,
+                proc.stdout[-800:] + proc.stderr[-800:],
+            )
+        after = snapshot(package.parent)
+        added = sorted(after - before)
+        check("no file was written into the package", added == [], added)
+    finally:
+        shutil.rmtree(work, ignore_errors=True)
+
+    print("\nPACKAGE IMMUTABLE FAIL" if FAILURES else "\nPACKAGE IMMUTABLE PASS")
+    return 1 if FAILURES else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

From 64802f8b78658a5309c375897a5fca85a274534b Mon Sep 17 00:00:00 2001
From: Pawel Lisowski <pawellisowski@o2.pl>
Date: Mon, 12 Oct 2026 10:21:25 +0200
Subject: [PATCH 06/17] test(blender): the wedged stand-in exits instead of
 racing past a tree kill (#692)

Under a loaded full-suite run, taskkill could end the stand-in's ping a moment
before cmd.exe, which then ran its next line and wrote a second progress record
before dying, failing the timeout test's exact-count assertion. A wedged Blender
never proceeds, so the stand-in now exits after its hang.
---
 cli/src/render/blender.rs | 10 ++++++++--
 1 file changed, 8 insertions(+), 2 deletions(-)

diff --git a/cli/src/render/blender.rs b/cli/src/render/blender.rs
index bc2d548f6..08477e291 100644
--- a/cli/src/render/blender.rs
+++ b/cli/src/render/blender.rs
@@ -1453,7 +1453,13 @@ mod tests {
             body.push_str(&format!(">>\"%AWARE_PROGRESS_FILE%\" echo {first}\r\n"));
             body.push_str(&format!("ping -n {} 127.0.0.1 >nul\r\n", pause_seconds + 1));
             if hang_seconds > 0 {
-                body.push_str(&format!("ping -n {} 127.0.0.1 >nul\r\n", hang_seconds + 1));
+                // A wedged Blender never gets further. Exiting here (rather than writing the later
+                // record) keeps a kill that reaches `ping` a moment before `cmd` from racing the
+                // script on to its next line under load.
+                body.push_str(&format!(
+                    "ping -n {} 127.0.0.1 >nul\r\nexit /b 1\r\n",
+                    hang_seconds + 1
+                ));
             }
             body.push_str(&format!(">>\"%AWARE_PROGRESS_FILE%\" echo {later}\r\n"));
             body.push_str("echo Blender quit noise\r\n");
@@ -1470,7 +1476,7 @@ mod tests {
             ));
             body.push_str(&format!("sleep {pause_seconds}\n"));
             if hang_seconds > 0 {
-                body.push_str(&format!("sleep {hang_seconds}\n"));
+                body.push_str(&format!("sleep {hang_seconds}\nexit 1\n"));
             }
             body.push_str(&format!(
                 "printf '%s\\n' '{later}' >> \"$AWARE_PROGRESS_FILE\"\n"

From 12f3a8ecf772e1f12d3fa96798563527c9e6f3ec Mon Sep 17 00:00:00 2001
From: Pawel Lisowski <pawellisowski@o2.pl>
Date: Mon, 12 Oct 2026 10:54:47 +0200
Subject: [PATCH 07/17] fix(progress): a pump cancelled mid-send loses and
 repeats no record (#692 review 2)

The Blender runner cancels Relay::pump at its deadline. pump() advanced the
file cursor, then awaited one send per record, so a cancellation mid-send
dropped every record read but not yet sent, and the final drain started
past them.

Records now move from the file into a `pending` queue and leave it only after
a channel slot is reserved (Sender::reserve, then permit.send), so the next
pump or the final drain delivers what a cancelled pump held, oldest first.
The progress-suppressed notice queues behind the accepted records the same
way, and the 10,000-record budget counts records accepted, not sent.

Test a_pump_cancelled_mid_send_loses_and_repeats_nothing (capacity-1
channel, pump cancelled after one hand-off, then a final drain) failed with
[0] before the change and now delivers [0, 1, 2, 3, 4].
---
 cli/src/runtime/progress.rs | 113 +++++++++++++++++++++++++++---------
 1 file changed, 87 insertions(+), 26 deletions(-)

diff --git a/cli/src/runtime/progress.rs b/cli/src/runtime/progress.rs
index 77a6020b7..abf60ebaf 100644
--- a/cli/src/runtime/progress.rs
+++ b/cli/src/runtime/progress.rs
@@ -205,7 +205,10 @@ pub struct Relay {
     /// Dropped once the budget is spent, which also stops reading the file at all.
     tail: Option<ProgressTail>,
     tx: mpsc::Sender<Value>,
-    sent: usize,
+    /// Records accepted for mirroring (the [`Self::MAX_RECORDS`] budget counts these).
+    accepted: usize,
+    /// Read from the file but not yet handed to the channel — what a cancelled pump holds.
+    pending: std::collections::VecDeque<Value>,
     /// Bytes of the channel read so far — kept past the point the tail is dropped, so what the
     /// pump that crossed a budget read is still observable.
     read: u64,
@@ -217,7 +220,8 @@ impl Relay {
         Self {
             tail: Some(ProgressTail::new(path)),
             tx,
-            sent: 0,
+            accepted: 0,
+            pending: std::collections::VecDeque::new(),
             read: 0,
         }
     }
@@ -252,9 +256,18 @@ impl Relay {
     /// but a real one publishes a few hundred bytes per record.
     pub const MAX_CHANNEL_BYTES: u64 = 16 * 1024 * 1024;
 
-    /// One poll. Returns whether the cursor moved — i.e. whether it is worth polling again right
-    /// now, rather than waiting for the producer to write more.
+    /// One poll. Returns whether it is worth polling again right now — i.e. the cursor moved and
+    /// the channel is still open — rather than waiting for the producer to write more.
+    ///
+    /// **Cancellation-safe** (Codex review, #692): the Blender runner cancels a pump at its
+    /// deadline. Records are moved from the file into `pending` (the cursor only ever advances
+    /// past records that are now held here) and each leaves `pending` only once a channel slot has
+    /// been reserved for it, so a pump dropped mid-send loses nothing and repeats nothing — the
+    /// next pump, or the final drain, delivers what was held first.
     pub async fn pump(&mut self) -> bool {
+        if !self.flush().await {
+            return false;
+        }
         let Some(tail) = self.tail.as_mut() else {
             return false;
         };
@@ -264,44 +277,55 @@ impl Relay {
         self.read = tail.consumed();
         let over_budget = tail.consumed() > Self::MAX_CHANNEL_BYTES;
         for record in records {
-            if self.sent >= Self::MAX_RECORDS {
+            if self.accepted >= Self::MAX_RECORDS {
                 self.suppress(format!(
                     "stopped mirroring after {} records — the producer is publishing progress \
                      faster than the trace may carry it",
                     Self::MAX_RECORDS
-                ))
-                .await;
-                return false;
-            }
-            self.sent += 1;
-            if self.tx.send(record).await.is_err() {
-                // Nobody is listening any more; the child still owns the result.
-                self.tail = None;
-                return false;
+                ));
+                break;
             }
+            self.accepted += 1;
+            self.pending.push_back(record);
         }
-        if over_budget {
+        if over_budget && self.tail.is_some() {
             self.suppress(format!(
                 "stopped reading the progress channel after {} MiB — it is carrying something \
                  other than progress records",
                 Self::MAX_CHANNEL_BYTES / (1024 * 1024)
-            ))
-            .await;
+            ));
+        }
+        if !self.flush().await {
             return false;
         }
-        advanced
+        advanced && self.tail.is_some()
+    }
+
+    /// Hand every held record to the channel, oldest first. A record leaves `pending` only after a
+    /// slot is reserved for it, so cancelling this mid-way keeps the rest for next time. Returns
+    /// `false` when nobody is listening any more (the child still owns the result).
+    async fn flush(&mut self) -> bool {
+        while !self.pending.is_empty() {
+            let Ok(permit) = self.tx.reserve().await else {
+                self.pending.clear();
+                self.tail = None;
+                return false;
+            };
+            if let Some(record) = self.pending.pop_front() {
+                permit.send(record);
+            }
+        }
+        true
     }
 
     /// Close the channel, saying so in the trace rather than falling silent — a consumer that stops
     /// receiving batches must be able to tell "the producer stopped" from "we stopped listening".
-    async fn suppress(&mut self, message: String) {
-        let _ = self
-            .tx
-            .send(serde_json::json!({
-                "phase": "progress-suppressed",
-                "message": message,
-            }))
-            .await;
+    /// Queued behind whatever was already accepted, and delivered by the same flush.
+    fn suppress(&mut self, message: String) {
+        self.pending.push_back(serde_json::json!({
+            "phase": "progress-suppressed",
+            "message": message,
+        }));
         self.tail = None;
     }
 }
@@ -393,6 +417,43 @@ mod tests {
         );
     }
 
+    /// Codex round 2: the Blender runner cancels a pump at its deadline. A pump that has already
+    /// advanced the file cursor must not lose the records it read but had not yet handed off —
+    /// the final drain delivers every record, exactly once, in order.
+    #[tokio::test]
+    async fn a_pump_cancelled_mid_send_loses_and_repeats_nothing() {
+        let tmp = tempfile::tempdir().unwrap();
+        let path = tmp.path().join("progress.jsonl");
+        let mut body = String::new();
+        for seq in 0..5 {
+            body.push_str(&format!(
+                "{{\"$aware-progress\":{{\"phase\":\"render\",\"done\":{seq}}}}}\n"
+            ));
+        }
+        tokio::fs::write(&path, body).await.unwrap();
+
+        // Capacity 1 and nobody reading yet: the pump reads all five, hands off one, then blocks.
+        let (tx, mut rx) = mpsc::channel::<Value>(1);
+        let mut relay = Relay::new(&path, tx);
+        let cancelled =
+            tokio::time::timeout(std::time::Duration::from_millis(200), relay.pump()).await;
+        assert!(
+            cancelled.is_err(),
+            "the pump should have blocked on the full channel"
+        );
+
+        let collector = tokio::spawn(async move {
+            let mut seen = Vec::new();
+            while let Some(record) = rx.recv().await {
+                seen.push(record["done"].as_u64().unwrap());
+            }
+            seen
+        });
+        relay.drain_to_end().await;
+        drop(relay);
+        assert_eq!(collector.await.unwrap(), vec![0, 1, 2, 3, 4]);
+    }
+
     #[tokio::test]
     async fn the_relay_stops_mirroring_a_flood_and_says_that_it_did() {
         // The per-record cap bounds how big a record is; this bounds how many. Without it a

From 9790512f687538dd1dffb4f34b179b04cf5b8382 Mon Sep 17 00:00:00 2001
From: Pawel Lisowski <pawellisowski@o2.pl>
Date: Mon, 12 Oct 2026 10:54:50 +0200
Subject: [PATCH 08/17] fix(blender): the timeout kills the whole process tree
 through the shared helper (#692 review 2)

On Unix the timeout path called kill_blender, which killed Blender's pid
alone, and then disarmed the process-group guard, so a child process that
authored code spawned survived the timeout.

There is now one tree kill, kill_tree (taskkill /T /F on Windows,
kill -KILL -<pgid> elsewhere, built by tree_kill_command), used by both the
drop guard and the timeout path. kill_blender takes the guard's pid, which
also disarms it, and kills the tree before reaping the child.

Tests: the_timeout_path_kills_the_whole_tree_through_the_shared_helper
records which kill the timeout used (it failed with no tree kill before the
change) and requires a ticking grandchild to stop;
the_tree_kill_targets_the_tree_on_both_platforms pins both command shapes
on any platform. The Unix branch itself was not executed here (no Unix host).
---
 cli/src/render/blender.rs | 176 +++++++++++++++++++++++++++++++-------
 1 file changed, 146 insertions(+), 30 deletions(-)

diff --git a/cli/src/render/blender.rs b/cli/src/render/blender.rs
index 08477e291..d0a2d6ba3 100644
--- a/cli/src/render/blender.rs
+++ b/cli/src/render/blender.rs
@@ -678,18 +678,15 @@ async fn read_to_end<R: tokio::io::AsyncRead + Unpin>(pipe: Option<R>) -> Vec<u8
     buf
 }
 
-/// Kill Blender and (on Windows) its whole process tree, then reap it. `taskkill /T /F` mirrors
-/// `invoker::kill_process_tree`: `Child::kill` alone can leave a grandchild running, and a leaked
-/// headless Blender holds a GPU context and the output file open.
-async fn kill_blender(child: &mut tokio::process::Child) {
-    #[cfg(windows)]
-    if let Some(pid) = child.id() {
-        let _ = tokio::process::Command::new("taskkill")
-            .args(["/PID", &pid.to_string(), "/T", "/F"])
-            .stdout(std::process::Stdio::null())
-            .stderr(std::process::Stdio::null())
-            .status()
-            .await;
+/// Kill Blender and its whole process tree, then reap it — the timeout path.
+///
+/// The kill is the guard's own [`kill_tree`] (taking its pid disarms it), so a timeout and an
+/// abandoned call end the same tree the same way: `Child::kill` alone leaves a grandchild running
+/// — on Unix, anything authored code spawned — and a leaked headless Blender holds a GPU context
+/// and the output file open. The tree dies BEFORE the reap, while the pid still names it.
+async fn kill_blender(child: &mut tokio::process::Child, guard: &mut TreeKillGuard) {
+    if let Some(pid) = guard.pid.take() {
+        kill_tree(pid);
     }
     let _ = child.start_kill();
     let _ = child.wait().await;
@@ -717,25 +714,44 @@ impl TreeKillGuard {
 
 impl Drop for TreeKillGuard {
     fn drop(&mut self) {
-        let Some(pid) = self.pid.take() else {
-            return;
-        };
-        let mut kill = if cfg!(windows) {
-            let mut c = std::process::Command::new("taskkill");
-            c.args(["/PID", &pid.to_string(), "/T", "/F"]);
-            c
-        } else {
-            let mut c = std::process::Command::new("kill");
-            c.args(["-KILL", &format!("-{pid}")]);
-            c
-        };
-        let _ = kill
-            .stdout(std::process::Stdio::null())
-            .stderr(std::process::Stdio::null())
-            .status();
+        if let Some(pid) = self.pid.take() {
+            kill_tree(pid);
+        }
     }
 }
 
+/// The command that kills `pid` AND everything it started: `taskkill /T /F` on Windows, a
+/// SIGKILL to the process group `pid` leads elsewhere (Blender is spawned as a group leader).
+/// `windows` is a parameter rather than a `cfg!` inside, so both branches are tested everywhere.
+fn tree_kill_command(pid: u32, windows: bool) -> std::process::Command {
+    let mut kill = if windows {
+        let mut c = std::process::Command::new("taskkill");
+        c.args(["/PID", &pid.to_string(), "/T", "/F"]);
+        c
+    } else {
+        let mut c = std::process::Command::new("kill");
+        c.args(["-KILL", &format!("-{pid}")]);
+        c
+    };
+    kill.stdout(std::process::Stdio::null())
+        .stderr(std::process::Stdio::null());
+    kill
+}
+
+#[cfg(test)]
+thread_local! {
+    /// Every pid this thread asked [`kill_tree`] to kill — how a test sees WHICH kill a path used.
+    static TREE_KILLS: std::cell::RefCell<Vec<u32>> = const { std::cell::RefCell::new(Vec::new()) };
+}
+
+/// Kill Blender's whole process tree — the one tree kill, shared by the timeout path and the
+/// drop guard, so neither can quietly fall back to killing the direct child alone.
+fn kill_tree(pid: u32) {
+    #[cfg(test)]
+    TREE_KILLS.with(|kills| kills.borrow_mut().push(pid));
+    let _ = tree_kill_command(pid, cfg!(windows)).status();
+}
+
 /// How long the progress drain after a timeout kill may take before the timeout is reported anyway.
 const TIMEOUT_DRAIN_GRACE: Duration = Duration::from_secs(2);
 
@@ -898,8 +914,7 @@ async fn run_script(
         None => {
             // The design doc's other required named error. Kill first, report second — a wedged
             // Blender must not outlive the call.
-            kill_blender(&mut child).await;
-            tree_guard.disarm();
+            kill_blender(&mut child, &mut tree_guard).await;
             // The records written before the kill are most of the diagnosis ("it reached frame
             // 140 of 240"), so they are delivered before the error, not lost with the process.
             // Bounded, though: the call is already failing, and a consumer that stopped reading
@@ -1602,6 +1617,107 @@ mod tests {
         assert_eq!(seen[0].1["done"], json!(3), "{seen:?}");
     }
 
+    /// A stand-in Blender that starts a grandchild ticking into `ticks` every second, then hangs.
+    /// Killing only the direct child leaves the grandchild ticking.
+    fn fake_blender_with_ticking_child(dir: &Path, ticks: &Path) -> PathBuf {
+        if cfg!(windows) {
+            let ticker = dir.join("ticker.cmd");
+            std::fs::write(
+                &ticker,
+                format!(
+                    "@echo off\r\n:loop\r\n>>\"{}\" echo tick\r\nping -n 2 127.0.0.1 >nul\r\ngoto loop\r\n",
+                    ticks.display()
+                ),
+            )
+            .expect("write ticker");
+            let path = dir.join("fake-blender.cmd");
+            std::fs::write(
+                &path,
+                format!(
+                    "@echo off\r\nstart \"\" /b cmd /c \"{}\"\r\nping -n 120 127.0.0.1 >nul\r\nexit /b 1\r\n",
+                    ticker.display()
+                ),
+            )
+            .expect("write fake");
+            path
+        } else {
+            let path = dir.join("fake-blender");
+            std::fs::write(
+                &path,
+                format!(
+                    "#!/bin/sh\n(while true; do echo tick >> '{}'; sleep 1; done) &\nsleep 120\nexit 1\n",
+                    ticks.display()
+                ),
+            )
+            .expect("write fake");
+            #[cfg(unix)]
+            {
+                use std::os::unix::fs::PermissionsExt;
+                std::fs::set_permissions(&path, std::fs::Permissions::from_mode(0o755))
+                    .expect("chmod fake blender");
+            }
+            path
+        }
+    }
+
+    /// Require `ticks` to stop growing: whatever was ticking is dead.
+    async fn assert_ticking_stopped(ticks: &Path, what: &str) {
+        tokio::time::sleep(Duration::from_millis(2_500)).await;
+        let settled = std::fs::read_to_string(ticks).unwrap_or_default().len();
+        tokio::time::sleep(Duration::from_millis(3_500)).await;
+        let later = std::fs::read_to_string(ticks).unwrap_or_default().len();
+        assert_eq!(
+            settled, later,
+            "{what}: Blender's process tree kept running"
+        );
+    }
+
+    /// Codex round 2: the TIMEOUT path must kill the whole tree through the same helper the drop
+    /// guard uses. On Unix the old path killed Blender's pid alone (the group survived); here the
+    /// helper records every pid it is asked to kill, so the path that was taken is observable on
+    /// any platform — and the grandchild must stop ticking.
+    #[tokio::test(flavor = "current_thread")]
+    async fn the_timeout_path_kills_the_whole_tree_through_the_shared_helper() {
+        let tmp = tempfile::tempdir().expect("tempdir");
+        let ticks = tmp.path().join("ticks.txt");
+        let blender = fake_blender_with_ticking_child(tmp.path(), &ticks);
+        TREE_KILLS.with(|kills| kills.borrow_mut().clear());
+
+        let err = run_script(
+            "exec",
+            &blender,
+            &tmp.path().join("exec.py"),
+            &exec_args(),
+            Duration::from_millis(3_000),
+            BlenderProgress::Off,
+        )
+        .await
+        .expect_err("the hanging stand-in must time out");
+        assert!(err.to_string().contains("timed out"), "{err}");
+        let kills = TREE_KILLS.with(|kills| kills.borrow().clone());
+        assert_eq!(
+            kills.len(),
+            1,
+            "the timeout must kill through the shared tree kill exactly once: {kills:?}"
+        );
+        assert!(ticks.exists(), "the grandchild never started");
+        assert_ticking_stopped(&ticks, "after a timeout").await;
+    }
+
+    #[test]
+    fn the_tree_kill_targets_the_tree_on_both_platforms() {
+        let windows = tree_kill_command(4242, true);
+        assert_eq!(windows.get_program(), "taskkill");
+        let args: Vec<_> = windows.get_args().collect();
+        assert_eq!(args, ["/PID", "4242", "/T", "/F"]);
+
+        // The leading `-` makes `kill` signal the PROCESS GROUP Blender leads, not one pid.
+        let unix = tree_kill_command(4242, false);
+        assert_eq!(unix.get_program(), "kill");
+        let args: Vec<_> = unix.get_args().collect();
+        assert_eq!(args, ["-KILL", "-4242"]);
+    }
+
     /// #692 review: an ABANDONED call (the run path drops the future — a failed trace write, a
     /// cancelled run) must take Blender's whole process tree with it. The stand-in starts a
     /// grandchild that ticks into a file every second, then hangs; killing only the direct child

From 8b7d8a6f21d4d1b4fdca27f87acad11cc5e20326 Mon Sep 17 00:00:00 2001
From: Pawel Lisowski <pawellisowski@o2.pl>
Date: Mon, 12 Oct 2026 10:54:53 +0200
Subject: [PATCH 09/17] fix(blender): prove an output's authorship by snapshot,
 not a timestamp window (#692 review 2)

The 1-second mtime allowance still accepted a target an earlier run wrote
less than a second before the render, when Blender wrote a frame-suffixed
MP4 beside it, so the receipt verified the old file.

render_still and render_animation now snapshot every candidate file (the
target and any <stem>*.mp4 beside it) as (size, mtime_ns, file id) before
rendering, and afterwards accept only files created or changed since. If the
render wrote nothing at the target, the entry is verified:false, "was not
written by this render".

New test (a stale target written moments before the render, no utime)
failed before the change with the stale `seq` verified, and now names the
new seq*.mp4.
---
 .../blender/scripts/_exec_ctx.py              | 90 ++++++++++++-------
 .../visualization/blender/tests/test_exec.py  | 19 ++++
 2 files changed, 75 insertions(+), 34 deletions(-)

diff --git a/20-agents/aeco/visualization/blender/scripts/_exec_ctx.py b/20-agents/aeco/visualization/blender/scripts/_exec_ctx.py
index 786fdcb8f..10df3ff69 100644
--- a/20-agents/aeco/visualization/blender/scripts/_exec_ctx.py
+++ b/20-agents/aeco/visualization/blender/scripts/_exec_ctx.py
@@ -27,7 +27,6 @@
 from __future__ import annotations
 
 import os
-import time
 
 import bpy
 
@@ -51,16 +50,43 @@ def _same_or_inside(path: str, root: str) -> bool:
         return False
 
 
-# Slack for filesystems with coarse mtimes (FAT: 2 s). A file older than the
-# render's start by more than this was not written by it.
-MTIME_SLACK_SECONDS = 1.0
+def _signature(path: str):
+    """What identifies one version of a file: (size, mtime_ns, file id). None if absent.
 
-
-def _written_since(path: str, started: float) -> bool:
+    Authorship is proven by comparing these before and after a render -- never by
+    a timestamp window, which a file written moments before the render passes.
+    """
     try:
-        return os.path.getmtime(path) >= started - MTIME_SLACK_SECONDS
+        st = os.stat(path)
     except OSError:
-        return False
+        return None
+    return (st.st_size, st.st_mtime_ns, st.st_ino)
+
+
+def _candidates(target: str) -> dict:
+    """The files a render to `target` may produce: `target` itself and any
+    `<stem>*.mp4` beside it (Blender appends a frame range to a movie name),
+    each mapped to its current signature."""
+    directory = os.path.dirname(target) or "."
+    stem = os.path.splitext(os.path.basename(target))[0]
+    found = {}
+    if os.path.isdir(directory):
+        for name in os.listdir(directory):
+            path = os.path.join(directory, name)
+            if path == target or (name.startswith(stem) and name.lower().endswith(".mp4")):
+                found[path] = _signature(path)
+    found.setdefault(target, _signature(target))
+    return found
+
+
+def _written_by_render(before: dict, target: str) -> list:
+    """Files created or changed since `before` was taken -- what THIS render wrote."""
+    after = _candidates(target)
+    return [
+        path
+        for path, sig in after.items()
+        if sig is not None and before.get(path) != sig
+    ]
 
 
 def eevee_engine() -> str:
@@ -170,12 +196,13 @@ def _resolve(self, path: str) -> str:
             path = os.path.join(self.output_dir, path)
         return os.path.abspath(path)
 
-    def _verified(self, path: str, kind: str, written_after: float | None = None, **extra) -> dict:
+    def _verified(self, path: str, kind: str, written: bool | None = None, **extra) -> dict:
         """Check one file and append its receipt entry.
 
-        `written_after` (a `time.time()` taken before a render) additionally
-        requires the file to be newer than that render's start, so a file left
-        by an EARLIER run at the same path is never passed off as this one's.
+        `written` -- passed by the render calls -- says whether the render
+        created or changed this file (a before/after snapshot, see
+        `_written_by_render`). False means the file at the path is one an
+        EARLIER run left there, and it is never passed off as this one's.
         """
         entry = {"path": os.path.abspath(path), "kind": kind}
         entry.update(extra)
@@ -197,7 +224,7 @@ def _verified(self, path: str, kind: str, written_after: float | None = None, **
                 reason = f"is outside output-dir ({self.output_dir})"
             elif size <= 0:
                 reason = "is empty"
-            elif written_after is not None and not _written_since(real, written_after):
+            elif written is False:
                 reason = "was not written by this render (an older file is at that path)"
         entry["verified"] = reason is None
         if reason is not None:
@@ -240,10 +267,10 @@ def render_still(self, path: str, quality: str = "draft", samples=None) -> dict:
         scene.render.image_settings.file_format = "PNG"
         scene.render.filepath = target
         os.makedirs(os.path.dirname(target), exist_ok=True)
-        started = time.time()
+        before = {target: _signature(target)}
         with _progress.FrameCounter(1, self._next_pass_label()):
             bpy.ops.render.render(write_still=True)
-        return self._verified(target, "image", written_after=started)
+        return self._verified(target, "image", written=_signature(target) != before[target])
 
     def render_animation(self, path: str, quality: str = "draft", samples=None) -> dict:
         """Render the scene's frame range to an H.264 MP4 at `path`.
@@ -269,26 +296,21 @@ def render_animation(self, path: str, quality: str = "draft", samples=None) -> d
 
         step = max(1, int(scene.frame_step))
         total = max(0, (scene.frame_end - scene.frame_start) // step + 1)
-        started = time.time()
+        before = _candidates(target)
         with _progress.FrameCounter(total, self._next_pass_label()) as counter:
             bpy.ops.render.render(animation=True)
         self.frames += counter.done
 
-        # Blender may append the frame range to a container name; find what
-        # THIS render wrote. In BOTH branches the file must be newer than the
-        # render's start: a target left by an earlier run, with Blender writing
-        # a suffixed file beside it, must not be verified in its place.
-        written = target
-        if not (os.path.isfile(written) and _written_since(written, started)):
-            directory = os.path.dirname(target)
-            stem = os.path.splitext(os.path.basename(target))[0]
-            candidates = [
-                os.path.join(directory, name)
-                for name in os.listdir(directory)
-                if name.startswith(stem)
-                and name.lower().endswith(".mp4")
-                and _written_since(os.path.join(directory, name), started)
-            ]
-            if candidates:
-                written = max(candidates, key=os.path.getmtime)
-        return self._verified(written, "video", written_after=started, frames=counter.done)
+        # Blender may append the frame range to a movie name, so the file can
+        # land beside `target` instead of at it. Whichever it is must be one
+        # this render CREATED OR CHANGED (snapshot before vs after, never a
+        # timestamp window): a target an earlier run left -- however recently
+        # -- must not be verified in place of the new file.
+        written = _written_by_render(before, target)
+        if target in written:
+            chosen, fresh = target, True
+        elif written:
+            chosen, fresh = max(written, key=os.path.getmtime), True
+        else:
+            chosen, fresh = target, False
+        return self._verified(chosen, "video", written=fresh, frames=counter.done)
diff --git a/20-agents/aeco/visualization/blender/tests/test_exec.py b/20-agents/aeco/visualization/blender/tests/test_exec.py
index edb669941..b54449470 100644
--- a/20-agents/aeco/visualization/blender/tests/test_exec.py
+++ b/20-agents/aeco/visualization/blender/tests/test_exec.py
@@ -264,6 +264,12 @@ def run(ctx):
     return {"video": ctx.render_animation("seq"), "stale": stale}
 """
 
+FRESH_STALE_TARGET = STALE_TARGET.replace(
+    "    os.utime(stale, (1_000_000_000, 1_000_000_000))\n",
+    "    # NO utime: written a moment ago, well inside any mtime allowance.\n",
+)
+assert FRESH_STALE_TARGET != STALE_TARGET
+
 ANIMATION = """\
 import bpy
 
@@ -380,6 +386,19 @@ def check_exec(blender: str, work: Path) -> None:
     )
     check("...and verifies it", video.get("verified") is True, video)
 
+    # -- ...even when that earlier file is under a second old -----------------------------
+    payload = run_exec(blender, work, {"code": FRESH_STALE_TARGET, "output-dir": str(work / "fresh-stale-out")})
+    check("the fresh-stale-target render succeeds", payload.get("ok") is True, payload)
+    video = (payload.get("result") or {}).get("video", {})
+    stale = (payload.get("result") or {}).get("stale", "")
+    check(
+        "a file written <1 s before the render is still not passed off as its output",
+        video.get("path", "").lower().endswith(".mp4")
+        and Path(video.get("path", "")).resolve() != Path(stale).resolve()
+        and video.get("verified") is True,
+        video,
+    )
+
     # -- blend-path scene init ----------------------------------------------------------
     saved = run_exec(blender, work, {"code": SAVE_BLEND, "output-dir": str(out_dir)})
     blend = (saved.get("result") or {}).get("saved")

From f561b4cc89ffaeb173ca5c867f4260fde3b5d900 Mon Sep 17 00:00:00 2001
From: Pawel Lisowski <pawellisowski@o2.pl>
Date: Mon, 12 Oct 2026 11:20:46 +0200
Subject: [PATCH 10/17] fix(blender): each render lands its own file through a
 private scratch dir (#692 review 3)

A before/after snapshot proves a file changed, not that Blender changed it:
with two writers in one output-dir, another one creating the exact target
while this render wrote a frame-suffixed MP4 got its file reported as this
render's verified video. Rebuilt rather than patched, per the operator.

render_still / render_animation now render into a scratch directory that only
that call uses (tempfile.mkdtemp beside the requested path, so the final move
is a same-volume rename), with Blender's filepath inside it and no extension,
so Blender names the file however it likes. Afterwards the only candidates
are the files in that directory (several: the largest wins, documented). The
winner is os.replace'd onto the requested path, overwriting what is there by
design, and the scratch directory is removed in a finally. A render that
wrote nothing gets verified:false, "the render wrote no file". The
snapshot/mtime machinery is gone entirely, and so are the stale-target tests
that asserted the old suffix-beside behaviour.

test_exec_render_output.py, against real Blender: (a) a concurrent writer
creating the exact target mid-render (failed before: the receipt held the
other writer's bytes); (b) Blender's frame-suffixed name ends at the requested
path with nothing left beside it; (c) a render that writes nothing gives a
plain reason (failed before: "was not written") and leaves no scratch; (d) no
scratch is left on success or when the move raises. The cleanup and suffix
checks were confirmed to go red when rmtree is skipped or only the
unsuffixed name is accepted.
---
 .../blender/scripts/_exec_ctx.py              | 148 +++++++------
 .../visualization/blender/skills/exec-bpy.md  |   6 +-
 .../visualization/blender/tests/test_exec.py  |  53 -----
 .../blender/tests/test_exec_render_output.py  | 195 ++++++++++++++++++
 4 files changed, 271 insertions(+), 131 deletions(-)
 create mode 100644 20-agents/aeco/visualization/blender/tests/test_exec_render_output.py

diff --git a/20-agents/aeco/visualization/blender/scripts/_exec_ctx.py b/20-agents/aeco/visualization/blender/scripts/_exec_ctx.py
index 10df3ff69..0d7ed5218 100644
--- a/20-agents/aeco/visualization/blender/scripts/_exec_ctx.py
+++ b/20-agents/aeco/visualization/blender/scripts/_exec_ctx.py
@@ -27,6 +27,8 @@
 from __future__ import annotations
 
 import os
+import shutil
+import tempfile
 
 import bpy
 
@@ -50,45 +52,6 @@ def _same_or_inside(path: str, root: str) -> bool:
         return False
 
 
-def _signature(path: str):
-    """What identifies one version of a file: (size, mtime_ns, file id). None if absent.
-
-    Authorship is proven by comparing these before and after a render -- never by
-    a timestamp window, which a file written moments before the render passes.
-    """
-    try:
-        st = os.stat(path)
-    except OSError:
-        return None
-    return (st.st_size, st.st_mtime_ns, st.st_ino)
-
-
-def _candidates(target: str) -> dict:
-    """The files a render to `target` may produce: `target` itself and any
-    `<stem>*.mp4` beside it (Blender appends a frame range to a movie name),
-    each mapped to its current signature."""
-    directory = os.path.dirname(target) or "."
-    stem = os.path.splitext(os.path.basename(target))[0]
-    found = {}
-    if os.path.isdir(directory):
-        for name in os.listdir(directory):
-            path = os.path.join(directory, name)
-            if path == target or (name.startswith(stem) and name.lower().endswith(".mp4")):
-                found[path] = _signature(path)
-    found.setdefault(target, _signature(target))
-    return found
-
-
-def _written_by_render(before: dict, target: str) -> list:
-    """Files created or changed since `before` was taken -- what THIS render wrote."""
-    after = _candidates(target)
-    return [
-        path
-        for path, sig in after.items()
-        if sig is not None and before.get(path) != sig
-    ]
-
-
 def eevee_engine() -> str:
     """EEVEE's identifier on this Blender (renamed BLENDER_EEVEE_NEXT in 4.2, back in 5.x)."""
     identifiers = {
@@ -196,16 +159,24 @@ def _resolve(self, path: str) -> str:
             path = os.path.join(self.output_dir, path)
         return os.path.abspath(path)
 
-    def _verified(self, path: str, kind: str, written: bool | None = None, **extra) -> dict:
+    def _verified(self, path: str, kind: str, reason: str | None = None, **extra) -> dict:
         """Check one file and append its receipt entry.
 
-        `written` -- passed by the render calls -- says whether the render
-        created or changed this file (a before/after snapshot, see
-        `_written_by_render`). False means the file at the path is one an
-        EARLIER run left there, and it is never passed off as this one's.
+        `reason` lets a render call record a failure it already knows about
+        (it wrote no file) in the same entry shape.
         """
         entry = {"path": os.path.abspath(path), "kind": kind}
         entry.update(extra)
+        if reason is None:
+            reason = self._problem_with(path, kind, entry)
+        entry["verified"] = reason is None
+        if reason is not None:
+            entry["reason"] = reason
+        self.outputs.append(entry)
+        return entry
+
+    def _problem_with(self, path: str, kind: str, entry: dict) -> str | None:
+        """Why `path` is not a verified output (None when it is); fills in its real path and size."""
         reason = None
         if kind not in KINDS:
             reason = f"unknown kind `{kind}`; expected one of {list(KINDS)}"
@@ -224,13 +195,7 @@ def _verified(self, path: str, kind: str, written: bool | None = None, **extra)
                 reason = f"is outside output-dir ({self.output_dir})"
             elif size <= 0:
                 reason = "is empty"
-            elif written is False:
-                reason = "was not written by this render (an older file is at that path)"
-        entry["verified"] = reason is None
-        if reason is not None:
-            entry["reason"] = reason
-        self.outputs.append(entry)
-        return entry
+        return reason
 
     def add_output(self, path: str, kind: str = "file") -> dict:
         """Register a file the code wrote itself; verified exactly like a render."""
@@ -256,6 +221,39 @@ def _ensure_camera(self) -> None:
         if self.scene.camera is None:
             self.frame("hero")
 
+    def _render_to(self, target: str, kind: str, render, **extra) -> dict:
+        """Run `render` into a scratch directory only this call uses, then land its
+        one output on `target`.
+
+        The scratch directory sits beside `target` (same volume, so the final move
+        is a rename) and is removed whatever happens. Blender's filepath points
+        inside it with no extension, so it is free to name the file -- `render.png`,
+        or `render0001-0240.mp4` with the frame range a movie gets. Afterwards the
+        ONLY candidates are the files in that directory; nothing else writing in
+        `output_dir` (an earlier run, a concurrent one) can be taken for this
+        render's output. Rule when there are several: the largest wins -- a movie
+        is one file, so several means stray side files, and the payload is the
+        biggest. The winner is moved onto `target` with `os.replace`, which
+        overwrites an existing file there: that is what asking for that path means.
+        """
+        directory = os.path.dirname(target)
+        os.makedirs(directory, exist_ok=True)
+        scratch = tempfile.mkdtemp(prefix=".aware-render-", dir=directory)
+        try:
+            self.scene.render.filepath = os.path.join(scratch, "render")
+            render()
+            produced = [
+                os.path.join(scratch, name)
+                for name in os.listdir(scratch)
+                if os.path.isfile(os.path.join(scratch, name))
+            ]
+            if not produced:
+                return self._verified(target, kind, reason="the render wrote no file", **extra)
+            os.replace(max(produced, key=os.path.getsize), target)
+        finally:
+            shutil.rmtree(scratch, ignore_errors=True)
+        return self._verified(target, kind, **extra)
+
     def render_still(self, path: str, quality: str = "draft", samples=None) -> dict:
         """Render the current frame to a PNG at `path` (relative paths land in output_dir)."""
         target = self._resolve(path)
@@ -265,12 +263,12 @@ def render_still(self, path: str, quality: str = "draft", samples=None) -> dict:
         if hasattr(scene.render.image_settings, "media_type"):
             scene.render.image_settings.media_type = "IMAGE"
         scene.render.image_settings.file_format = "PNG"
-        scene.render.filepath = target
-        os.makedirs(os.path.dirname(target), exist_ok=True)
-        before = {target: _signature(target)}
-        with _progress.FrameCounter(1, self._next_pass_label()):
-            bpy.ops.render.render(write_still=True)
-        return self._verified(target, "image", written=_signature(target) != before[target])
+
+        def render():
+            with _progress.FrameCounter(1, self._next_pass_label()):
+                bpy.ops.render.render(write_still=True)
+
+        return self._render_to(target, "image", render)
 
     def render_animation(self, path: str, quality: str = "draft", samples=None) -> dict:
         """Render the scene's frame range to an H.264 MP4 at `path`.
@@ -291,26 +289,22 @@ def render_animation(self, path: str, quality: str = "draft", samples=None) -> d
         scene.render.ffmpeg.codec = "H264"
         scene.render.ffmpeg.constant_rate_factor = "MEDIUM"
         scene.render.ffmpeg.ffmpeg_preset = "GOOD"
-        scene.render.filepath = target
-        os.makedirs(os.path.dirname(target), exist_ok=True)
 
         step = max(1, int(scene.frame_step))
         total = max(0, (scene.frame_end - scene.frame_start) // step + 1)
-        before = _candidates(target)
-        with _progress.FrameCounter(total, self._next_pass_label()) as counter:
-            bpy.ops.render.render(animation=True)
-        self.frames += counter.done
-
-        # Blender may append the frame range to a movie name, so the file can
-        # land beside `target` instead of at it. Whichever it is must be one
-        # this render CREATED OR CHANGED (snapshot before vs after, never a
-        # timestamp window): a target an earlier run left -- however recently
-        # -- must not be verified in place of the new file.
-        written = _written_by_render(before, target)
-        if target in written:
-            chosen, fresh = target, True
-        elif written:
-            chosen, fresh = max(written, key=os.path.getmtime), True
-        else:
-            chosen, fresh = target, False
-        return self._verified(chosen, "video", written=fresh, frames=counter.done)
+        counted = {"done": 0}
+
+        def render():
+            with _progress.FrameCounter(total, self._next_pass_label()) as counter:
+                try:
+                    bpy.ops.render.render(animation=True)
+                finally:
+                    counted["done"] = counter.done
+
+        try:
+            entry = self._render_to(target, "video", render)
+        finally:
+            self.frames += counted["done"]
+        # The entry is the one already in the receipt; it gains the frame count.
+        entry["frames"] = counted["done"]
+        return entry
diff --git a/20-agents/aeco/visualization/blender/skills/exec-bpy.md b/20-agents/aeco/visualization/blender/skills/exec-bpy.md
index a1212afba..8f46c161e 100644
--- a/20-agents/aeco/visualization/blender/skills/exec-bpy.md
+++ b/20-agents/aeco/visualization/blender/skills/exec-bpy.md
@@ -89,6 +89,10 @@ rather than after a long import.
 | `ctx.add_output(path, kind="file")` | Register any other file you wrote (`video`, `image`, `blend`, `file`). |
 
 Relative paths given to `render_*`/`add_output` resolve inside `ctx.output_dir`.
+Each `render_*` call renders into a private scratch folder beside the requested
+path and then moves its file onto that path, replacing any file already there —
+so the name you ask for is the name you get (Blender's frame-range suffix never
+leaks out), and nothing else writing in the folder can be mistaken for the render.
 `quality="draft"` is EEVEE, `"production"` is Cycles. Without a camera, `render_*`
 frames one at `hero` first.
 
@@ -113,7 +117,7 @@ fails as `result-too-large`: write the data to a file in `ctx.output_dir`,
 `outputs` is an explicit receipt, never a directory listing. Each entry is
 verified: the file exists, is a regular non-empty file, and its real path is inside
 `output_dir`. One that fails stays in the list with `verified: false` and a
-`reason` (`was not written`, `is outside output-dir (…)`, `is empty`). Downstream
+`reason` (`the render wrote no file`, `was not written`, `is outside output-dir (…)`, `is empty`). Downstream
 nodes should consume only `verified: true` entries.
 
 ### Errors
diff --git a/20-agents/aeco/visualization/blender/tests/test_exec.py b/20-agents/aeco/visualization/blender/tests/test_exec.py
index b54449470..8c042ded5 100644
--- a/20-agents/aeco/visualization/blender/tests/test_exec.py
+++ b/20-agents/aeco/visualization/blender/tests/test_exec.py
@@ -243,33 +243,6 @@ def run(ctx):
     return {"ratio": float("nan")}
 """
 
-STALE_TARGET = """\
-import os
-import bpy
-
-def run(ctx):
-    # A file an EARLIER run left at the target path, long ago.
-    stale = os.path.join(ctx.output_dir, "seq")
-    with open(stale, "w") as handle:
-        handle.write("left by an earlier run")
-    os.utime(stale, (1_000_000_000, 1_000_000_000))
-    bpy.ops.mesh.primitive_cube_add(size=2)
-    s = ctx.scene
-    s.render.resolution_x = 32
-    s.render.resolution_y = 32
-    s.frame_start, s.frame_end = 1, 2
-    sun = bpy.data.objects.new("Sun", bpy.data.lights.new("Sun", "SUN"))
-    s.collection.objects.link(sun)
-    # No extension: Blender writes a frame-suffixed seq0001-0002.mp4 beside it.
-    return {"video": ctx.render_animation("seq"), "stale": stale}
-"""
-
-FRESH_STALE_TARGET = STALE_TARGET.replace(
-    "    os.utime(stale, (1_000_000_000, 1_000_000_000))\n",
-    "    # NO utime: written a moment ago, well inside any mtime allowance.\n",
-)
-assert FRESH_STALE_TARGET != STALE_TARGET
-
 ANIMATION = """\
 import bpy
 
@@ -373,32 +346,6 @@ def check_exec(blender: str, work: Path) -> None:
     )
     check("a corrupt .blend fails as blend-unreadable", payload.get("code") == "blend-unreadable", payload)
 
-    # -- a stale file at the target path is never verified as this render's ---------------
-    payload = run_exec(blender, work, {"code": STALE_TARGET, "output-dir": str(work / "stale-out")})
-    check("the stale-target render succeeds", payload.get("ok") is True, payload)
-    video = (payload.get("result") or {}).get("video", {})
-    stale = (payload.get("result") or {}).get("stale", "")
-    check(
-        "the receipt names the MP4 this render wrote, not the earlier run's file",
-        video.get("path", "").lower().endswith(".mp4")
-        and Path(video.get("path", "")).resolve() != Path(stale).resolve(),
-        video,
-    )
-    check("...and verifies it", video.get("verified") is True, video)
-
-    # -- ...even when that earlier file is under a second old -----------------------------
-    payload = run_exec(blender, work, {"code": FRESH_STALE_TARGET, "output-dir": str(work / "fresh-stale-out")})
-    check("the fresh-stale-target render succeeds", payload.get("ok") is True, payload)
-    video = (payload.get("result") or {}).get("video", {})
-    stale = (payload.get("result") or {}).get("stale", "")
-    check(
-        "a file written <1 s before the render is still not passed off as its output",
-        video.get("path", "").lower().endswith(".mp4")
-        and Path(video.get("path", "")).resolve() != Path(stale).resolve()
-        and video.get("verified") is True,
-        video,
-    )
-
     # -- blend-path scene init ----------------------------------------------------------
     saved = run_exec(blender, work, {"code": SAVE_BLEND, "output-dir": str(out_dir)})
     blend = (saved.get("result") or {}).get("saved")
diff --git a/20-agents/aeco/visualization/blender/tests/test_exec_render_output.py b/20-agents/aeco/visualization/blender/tests/test_exec_render_output.py
new file mode 100644
index 000000000..975a1cb5a
--- /dev/null
+++ b/20-agents/aeco/visualization/blender/tests/test_exec_render_output.py
@@ -0,0 +1,195 @@
+"""How `ctx.render_still` / `ctx.render_animation` land their file (#692 review 3).
+
+Each render call writes into a scratch directory that only that call uses, next
+to the requested path. Afterwards the ONLY candidates are the files in that
+directory -- whatever name or frame-range suffix Blender chose -- and the one
+output is moved with `os.replace` onto the requested path, which it overwrites
+by design. The scratch directory is removed whatever happens. So nothing else
+writing in `output_dir` -- an earlier run, a concurrent one -- can be mistaken
+for this render's output, and no timestamp or before/after comparison is needed.
+
+Against a REAL Blender, each check below:
+
+  (a) a concurrent writer creates the exact target DURING the render: the
+      receipt and the file at the requested path are this render's MP4 bytes;
+  (b) Blender appends a frame range to the movie name: the final file is at the
+      requested path anyway, and no suffixed file is left beside it;
+  (c) the render writes nothing: `verified: false` with a plain reason, no file
+      at the requested path, and no scratch directory left;
+  (d) no scratch directory is left after a success, nor after the move fails
+      with an exception.
+
+Run: python test_exec_render_output.py [--blender <path>]
+Exits 0 on pass, 1 on failure, 77 (SKIP) when no Blender can be found.
+"""
+
+import argparse
+import shutil
+import sys
+import tempfile
+from pathlib import Path
+
+sys.dont_write_bytecode = True  # importing from scripts/ must not write into the package
+
+HERE = Path(__file__).resolve().parent
+sys.path.insert(0, str(HERE))
+
+from run_smoke import resolve_blender  # noqa: E402
+from test_exec import FAILURES, SKIP_EXIT, check, run_exec  # noqa: E402
+
+SCENE = """\
+import os
+import bpy
+
+def scene(ctx, frames=2):
+    bpy.ops.mesh.primitive_cube_add(size=2)
+    s = ctx.scene
+    s.render.resolution_x = 32
+    s.render.resolution_y = 32
+    s.frame_start, s.frame_end = 1, frames
+    sun = bpy.data.objects.new("Sun", bpy.data.lights.new("Sun", "SUN"))
+    s.collection.objects.link(sun)
+
+def listing(ctx):
+    return sorted(os.listdir(ctx.output_dir))
+"""
+
+# (a) A writer that is NOT this render creates the exact target mid-render.
+CONCURRENT = SCENE + """
+def run(ctx):
+    scene(ctx)
+    target = os.path.join(ctx.output_dir, "seq")
+
+    def intruder(*_args):
+        with open(target, "wb") as handle:
+            handle.write(b"another writer's bytes")
+
+    bpy.app.handlers.render_write.append(intruder)
+    try:
+        video = ctx.render_animation("seq")
+    finally:
+        bpy.app.handlers.render_write.remove(intruder)
+    with open(target, "rb") as handle:
+        head = handle.read(16)
+    return {"video": video, "head": head.hex(), "listing": listing(ctx)}
+"""
+
+# (b) The scratch file name carries no extension, so Blender writes the movie as
+# <name><start>-<end>.mp4; the requested name has an extension of its own.
+SUFFIXED = SCENE + """
+def run(ctx):
+    scene(ctx)
+    video = ctx.render_animation("clip.mp4")
+    return {"video": video, "listing": listing(ctx)}
+"""
+
+# (c) Something deletes whatever the render wrote before ctx collects it.
+NOTHING = SCENE + """
+def run(ctx):
+    scene(ctx)
+
+    def vanish(*_args):
+        folder = os.path.dirname(bpy.context.scene.render.filepath)
+        for name in os.listdir(folder):
+            os.remove(os.path.join(folder, name))
+
+    bpy.app.handlers.render_complete.append(vanish)
+    try:
+        video = ctx.render_animation("nothing.mp4")
+    finally:
+        bpy.app.handlers.render_complete.remove(vanish)
+    return {"video": video, "listing": listing(ctx)}
+"""
+
+# (d) The final move fails: the requested path is a DIRECTORY.
+MOVE_FAILS = SCENE + """
+def run(ctx):
+    scene(ctx)
+    os.makedirs(os.path.join(ctx.output_dir, "blocked.png"))
+    try:
+        ctx.render_still("blocked.png")
+        raised = None
+    except Exception as exc:
+        raised = type(exc).__name__
+    return {"raised": raised, "listing": listing(ctx)}
+"""
+
+
+def no_scratch(listing) -> bool:
+    return not any(name.startswith(".aware-render-") for name in listing)
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--blender", help="path to the Blender executable")
+    opts = parser.parse_args()
+
+    blender = resolve_blender(opts.blender)
+    if blender is None:
+        print("SKIP: no Blender available (pass --blender <path> to run this harness)")
+        return SKIP_EXIT
+
+    work = Path(tempfile.mkdtemp(prefix="aware-render-output-"))
+    try:
+        print("(a) a concurrent writer creates the exact target during the render")
+        payload = run_exec(blender, work, {"code": CONCURRENT, "output-dir": str(work / "a")})
+        result = payload.get("result") or {}
+        video = result.get("video", {})
+        check("the run succeeds", payload.get("ok") is True, payload)
+        check(
+            "the file at the requested path is this render's MP4, not the other writer's bytes",
+            bytes.fromhex(result.get("head", ""))[4:8] == b"ftyp",
+            result.get("head"),
+        )
+        check(
+            "the receipt names the requested path and verifies it",
+            Path(video.get("path", "")).name == "seq" and video.get("verified") is True,
+            video,
+        )
+        check("no scratch directory is left (success)", no_scratch(result.get("listing", [])), result.get("listing"))
+
+        print("(b) Blender writes a frame-suffixed name")
+        payload = run_exec(blender, work, {"code": SUFFIXED, "output-dir": str(work / "b")})
+        result = payload.get("result") or {}
+        video = result.get("video", {})
+        check(
+            "the final file is at exactly the requested path",
+            Path(video.get("path", "")).name == "clip.mp4" and video.get("verified") is True,
+            video,
+        )
+        check("nothing else is left beside it", result.get("listing") == ["clip.mp4"], result.get("listing"))
+        check("the receipt keeps the frame count", video.get("frames") == 2, video)
+
+        print("(c) the render writes nothing")
+        payload = run_exec(blender, work, {"code": NOTHING, "output-dir": str(work / "c")})
+        result = payload.get("result") or {}
+        video = result.get("video", {})
+        check("the receipt says verified:false", video.get("verified") is False, video)
+        check(
+            "...with a plain reason",
+            "wrote no file" in str(video.get("reason", "")),
+            video.get("reason"),
+        )
+        check("nothing appears at the requested path, and no scratch is left", result.get("listing") == [], result.get("listing"))
+
+        print("(d) the move fails with an exception")
+        payload = run_exec(blender, work, {"code": MOVE_FAILS, "output-dir": str(work / "d")})
+        result = payload.get("result") or {}
+        check("the failure surfaces as an exception", bool(result.get("raised")), result)
+        check(
+            "no scratch directory is left (exception)",
+            result.get("listing") == ["blocked.png"],
+            result.get("listing"),
+        )
+    except AssertionError as exc:
+        FAILURES.append(str(exc))
+        print(f"  FAIL {exc}")
+    finally:
+        shutil.rmtree(work, ignore_errors=True)
+
+    print("\nRENDER OUTPUT FAIL" if FAILURES else "\nRENDER OUTPUT PASS")
+    return 1 if FAILURES else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

From 02f2eee2e5d78406ce62ef5fa46249a9024b733b Mon Sep 17 00:00:00 2001
From: Pawel <pawellisowski@o2.pl>
Date: Mon, 12 Oct 2026 13:17:26 +0200
Subject: [PATCH 11/17] fix(blender): a render lands only its own format's
 file, and only if it is still that file (#692 review 4)

The scratch dir made sure nothing outside the call could be taken for its
output, but inside it the largest file still won: a render hook that dropped
a bigger .txt or .blend there would have been moved onto the requested path
and verified as the video. Only files with the extension Blender gives the
format being rendered (read from frame_path, since render.file_extension
still says .png after a switch to FFMPEG) are now candidates.

The receipt also trusted that the file at the requested path after the move
was the one moved there. Another writer replacing it in between would have
been passed off as the render, so the chosen file's size and mtime are
recorded before os.replace and checked after it; a mismatch is
verified: false with "the file at <path> changed after the render wrote it".

The no-output reason now reads "no render output file was found", which is
what the code actually knows once candidates are filtered by format.
---
 .../blender/scripts/_exec_ctx.py              | 56 ++++++++++---
 .../visualization/blender/skills/exec-bpy.md  |  5 +-
 .../blender/tests/test_exec_render_output.py  | 82 ++++++++++++++++++-
 3 files changed, 129 insertions(+), 14 deletions(-)

diff --git a/20-agents/aeco/visualization/blender/scripts/_exec_ctx.py b/20-agents/aeco/visualization/blender/scripts/_exec_ctx.py
index 0d7ed5218..d6f2e124a 100644
--- a/20-agents/aeco/visualization/blender/scripts/_exec_ctx.py
+++ b/20-agents/aeco/visualization/blender/scripts/_exec_ctx.py
@@ -52,6 +52,12 @@ def _same_or_inside(path: str, root: str) -> bool:
         return False
 
 
+def _identity(path: str) -> tuple[int, int]:
+    """What says a file is still the one that was written: its size and mtime."""
+    stat = os.stat(path)
+    return (stat.st_size, stat.st_mtime_ns)
+
+
 def eevee_engine() -> str:
     """EEVEE's identifier on this Blender (renamed BLENDER_EEVEE_NEXT in 4.2, back in 5.x)."""
     identifiers = {
@@ -163,7 +169,8 @@ def _verified(self, path: str, kind: str, reason: str | None = None, **extra) ->
         """Check one file and append its receipt entry.
 
         `reason` lets a render call record a failure it already knows about
-        (it wrote no file) in the same entry shape.
+        (no output file was found, or the file changed after it was written)
+        in the same entry shape.
         """
         entry = {"path": os.path.abspath(path), "kind": kind}
         entry.update(extra)
@@ -229,29 +236,56 @@ def _render_to(self, target: str, kind: str, render, **extra) -> dict:
         is a rename) and is removed whatever happens. Blender's filepath points
         inside it with no extension, so it is free to name the file -- `render.png`,
         or `render0001-0240.mp4` with the frame range a movie gets. Afterwards the
-        ONLY candidates are the files in that directory; nothing else writing in
-        `output_dir` (an earlier run, a concurrent one) can be taken for this
-        render's output. Rule when there are several: the largest wins -- a movie
-        is one file, so several means stray side files, and the payload is the
-        biggest. The winner is moved onto `target` with `os.replace`, which
-        overwrites an existing file there: that is what asking for that path means.
+        ONLY candidates are the files in that directory whose extension is the one
+        the format being rendered writes (Blender's own `frame_path`, read before
+        the render starts); nothing else writing in `output_dir` (an earlier
+        run, a concurrent one), and no side file of another type a render hook
+        drops into the scratch directory, can be taken for this render's output.
+        Rule when there are several: the largest wins -- a movie is one file, so
+        several means strays, and the payload is the biggest. The winner is moved
+        onto `target` with `os.replace`, which overwrites an existing file there:
+        that is what asking for that path means. Its size and modification time
+        are recorded before the move and checked again after it, so a file another
+        writer put at `target` in between is never passed off as the render.
         """
         directory = os.path.dirname(target)
         os.makedirs(directory, exist_ok=True)
         scratch = tempfile.mkdtemp(prefix=".aware-render-", dir=directory)
         try:
-            self.scene.render.filepath = os.path.join(scratch, "render")
+            scene = self.scene
+            scene.render.filepath = os.path.join(scratch, "render")
+            # The name Blender will give this format's output (`.png`, `.mp4`);
+            # `render.file_extension` lags behind a switch to a movie format.
+            extension = os.path.splitext(
+                scene.render.frame_path(frame=scene.frame_start)
+            )[1].lower()
             render()
             produced = [
                 os.path.join(scratch, name)
                 for name in os.listdir(scratch)
-                if os.path.isfile(os.path.join(scratch, name))
+                if os.path.splitext(name)[1].lower() == extension
+                and os.path.isfile(os.path.join(scratch, name))
             ]
             if not produced:
-                return self._verified(target, kind, reason="the render wrote no file", **extra)
-            os.replace(max(produced, key=os.path.getsize), target)
+                return self._verified(
+                    target, kind, reason="no render output file was found", **extra
+                )
+            chosen = max(produced, key=os.path.getsize)
+            written = _identity(chosen)
+            os.replace(chosen, target)
         finally:
             shutil.rmtree(scratch, ignore_errors=True)
+        try:
+            landed = _identity(target)
+        except OSError:
+            landed = None
+        if landed != written:
+            return self._verified(
+                target,
+                kind,
+                reason=f"the file at {target} changed after the render wrote it",
+                **extra,
+            )
         return self._verified(target, kind, **extra)
 
     def render_still(self, path: str, quality: str = "draft", samples=None) -> dict:
diff --git a/20-agents/aeco/visualization/blender/skills/exec-bpy.md b/20-agents/aeco/visualization/blender/skills/exec-bpy.md
index 8f46c161e..5b37d3fcb 100644
--- a/20-agents/aeco/visualization/blender/skills/exec-bpy.md
+++ b/20-agents/aeco/visualization/blender/skills/exec-bpy.md
@@ -93,6 +93,9 @@ Each `render_*` call renders into a private scratch folder beside the requested
 path and then moves its file onto that path, replacing any file already there —
 so the name you ask for is the name you get (Blender's frame-range suffix never
 leaks out), and nothing else writing in the folder can be mistaken for the render.
+Only a file of the format being rendered (`.png`, `.mp4`) counts as its output, so
+a side file a render hook drops there is never taken for it; and if the file at the
+path changes between the move and the check, the entry is `verified: false`.
 `quality="draft"` is EEVEE, `"production"` is Cycles. Without a camera, `render_*`
 frames one at `hero` first.
 
@@ -117,7 +120,7 @@ fails as `result-too-large`: write the data to a file in `ctx.output_dir`,
 `outputs` is an explicit receipt, never a directory listing. Each entry is
 verified: the file exists, is a regular non-empty file, and its real path is inside
 `output_dir`. One that fails stays in the list with `verified: false` and a
-`reason` (`the render wrote no file`, `was not written`, `is outside output-dir (…)`, `is empty`). Downstream
+`reason` (`no render output file was found`, `the file at … changed after the render wrote it`, `was not written`, `is outside output-dir (…)`, `is empty`). Downstream
 nodes should consume only `verified: true` entries.
 
 ### Errors
diff --git a/20-agents/aeco/visualization/blender/tests/test_exec_render_output.py b/20-agents/aeco/visualization/blender/tests/test_exec_render_output.py
index 975a1cb5a..b0e26519a 100644
--- a/20-agents/aeco/visualization/blender/tests/test_exec_render_output.py
+++ b/20-agents/aeco/visualization/blender/tests/test_exec_render_output.py
@@ -17,7 +17,13 @@
   (c) the render writes nothing: `verified: false` with a plain reason, no file
       at the requested path, and no scratch directory left;
   (d) no scratch directory is left after a success, nor after the move fails
-      with an exception.
+      with an exception;
+  (e) a render hook writes a BIGGER file of another type into the scratch
+      directory: only files of the format being rendered are candidates, so
+      the receipt still points at this render's MP4;
+  (f) another writer replaces the requested path right after the move: the
+      file there no longer has the identity the render wrote, so the receipt
+      says `verified: false` with a plain reason.
 
 Run: python test_exec_render_output.py [--blender <path>]
 Exits 0 on pass, 1 on failure, 77 (SKIP) when no Blender can be found.
@@ -114,6 +120,47 @@ def run(ctx):
     return {"raised": raised, "listing": listing(ctx)}
 """
 
+# (e) A render hook drops a large file of ANOTHER type into the scratch dir.
+SIDE_FILE = SCENE + """
+def run(ctx):
+    scene(ctx)
+
+    def side_file(*_args):
+        folder = os.path.dirname(bpy.context.scene.render.filepath)
+        with open(os.path.join(folder, "notes.txt"), "wb") as handle:
+            handle.write(b"x" * (1024 * 1024))
+
+    bpy.app.handlers.render_write.append(side_file)
+    try:
+        video = ctx.render_animation("side.mp4")
+    finally:
+        bpy.app.handlers.render_write.remove(side_file)
+    with open(os.path.join(ctx.output_dir, "side.mp4"), "rb") as handle:
+        head = handle.read(16)
+    return {"video": video, "head": head.hex(), "listing": listing(ctx)}
+"""
+
+# (f) Another writer replaces the requested path the moment the render lands.
+REPLACED = SCENE + """
+def run(ctx):
+    scene(ctx)
+    target = os.path.join(ctx.output_dir, "still.png")
+    real_replace = os.replace
+
+    def replace_then_overwrite(src, dst):
+        real_replace(src, dst)
+        if os.path.abspath(dst) == os.path.abspath(target):
+            with open(dst, "wb") as handle:
+                handle.write(b"another writer's bytes")
+
+    os.replace = replace_then_overwrite
+    try:
+        still = ctx.render_still("still.png")
+    finally:
+        os.replace = real_replace
+    return {"still": still, "listing": listing(ctx)}
+"""
+
 
 def no_scratch(listing) -> bool:
     return not any(name.startswith(".aware-render-") for name in listing)
@@ -167,7 +214,7 @@ def main() -> int:
         check("the receipt says verified:false", video.get("verified") is False, video)
         check(
             "...with a plain reason",
-            "wrote no file" in str(video.get("reason", "")),
+            video.get("reason") == "no render output file was found",
             video.get("reason"),
         )
         check("nothing appears at the requested path, and no scratch is left", result.get("listing") == [], result.get("listing"))
@@ -181,6 +228,37 @@ def main() -> int:
             result.get("listing") == ["blocked.png"],
             result.get("listing"),
         )
+
+        print("(e) a render hook writes a bigger file of another type into the scratch dir")
+        payload = run_exec(blender, work, {"code": SIDE_FILE, "output-dir": str(work / "e")})
+        result = payload.get("result") or {}
+        video = result.get("video", {})
+        check(
+            "the file at the requested path is this render's MP4, not the side file",
+            bytes.fromhex(result.get("head", ""))[4:8] == b"ftyp",
+            result.get("head"),
+        )
+        check(
+            "the receipt verifies it at the requested path, at the MP4's size",
+            Path(video.get("path", "")).name == "side.mp4"
+            and video.get("verified") is True
+            and 0 < video.get("size-bytes", 0) < 1024 * 1024,
+            video,
+        )
+        check("nothing else is left beside it", result.get("listing") == ["side.mp4"], result.get("listing"))
+
+        print("(f) another writer replaces the requested path right after the move")
+        payload = run_exec(blender, work, {"code": REPLACED, "output-dir": str(work / "f")})
+        result = payload.get("result") or {}
+        still = result.get("still", {})
+        check("the receipt says verified:false", still.get("verified") is False, still)
+        check(
+            "...with a plain reason naming the path",
+            str(still.get("reason", "")).startswith("the file at ")
+            and str(still.get("reason", "")).endswith("changed after the render wrote it")
+            and "still.png" in str(still.get("reason", "")),
+            still.get("reason"),
+        )
     except AssertionError as exc:
         FAILURES.append(str(exc))
         print(f"  FAIL {exc}")

From d8321b32f621a735a865f9009520d99713c57bb7 Mon Sep 17 00:00:00 2001
From: Pawel <pawellisowski@o2.pl>
Date: Mon, 12 Oct 2026 13:26:46 +0200
Subject: [PATCH 12/17] fix(app): a whole-node template cannot feed a literal
 input (#692 review 5)

The literal-input rule looked `code` up by name in the node's merged
params. A node written `inputs: '{{ inputs.payload }}'` (or `config:`
templated with no `inputs:`, or a mapping `config:` beside a templated
`inputs:` string) makes merged_params() return a bare string, so the
by-name lookup found nothing and passed it. render_config then resolves
that whole-value template into the object the run supplies, `code`
included, so Python handed in at run time reached Blender under an
approved lock -- exactly what E_APP_INPUT_MUST_BE_LITERAL exists to stop.

When a command declares any literal input, a non-mapping `config:` or
`inputs:` that carries template syntax is now refused too, each field
checked on its own before merging can hide one behind the other. The
message names the literal input(s). Validate, compile (through validate)
and the runtime pre-render check all go through the one
literal_input_violations helper. Commands with no literal input keep
accepting whole-node templates.
---
 cli/src/manifest/agent.rs       | 58 +++++++++++++++++++++++++++
 cli/src/runtime/orchestrator.rs | 66 ++++++++++++++++++++++++++++---
 cli/src/validate.rs             | 70 +++++++++++++++++++++++++++++++--
 cli/tests/blender_exec.rs       | 32 +++++++++++++++
 4 files changed, 216 insertions(+), 10 deletions(-)

diff --git a/cli/src/manifest/agent.rs b/cli/src/manifest/agent.rs
index 0db41f2cc..32cc8b226 100644
--- a/cli/src/manifest/agent.rs
+++ b/cli/src/manifest/agent.rs
@@ -709,6 +709,64 @@ impl Command {
             .map(str::to_string)
             .collect()
     }
+
+    /// Every way `node`'s un-rendered `config:`/`inputs:` could put text supplied after approval
+    /// into one of this command's `literal: true` inputs, as ready-to-show messages for
+    /// [`E_APP_INPUT_MUST_BE_LITERAL`]. Empty when the command declares no literal input.
+    ///
+    /// Two shapes. A literal input templated by name (`code: '{{ … }}'`) is found through the
+    /// merged params. A WHOLE `inputs:` or `config:` written as a template (`inputs: '{{
+    /// inputs.payload }}'`) is the other: `merged_params()` hands that string back as is, so a
+    /// by-name lookup finds no `code` and would pass it — yet `render_config` resolves a
+    /// whole-value template into the object the run supplies, `code` and all. So each of the two
+    /// fields is checked on its own, before merging can hide one behind the other (a mapping
+    /// `config:` beside a templated `inputs:` string merges to just that string).
+    pub fn literal_input_violations(
+        &self,
+        node: &crate::manifest::app::Node,
+        agent: &str,
+        command: &str,
+    ) -> Vec<String> {
+        let literal = self.literal_inputs();
+        if literal.is_empty() {
+            return Vec::new();
+        }
+        let mut out: Vec<String> = [("config", &node.config), ("inputs", &node.inputs)]
+            .into_iter()
+            .filter(|(_, value)| {
+                !value.is_null() && !value.is_mapping() && contains_template_syntax(value)
+            })
+            .map(|(field, _)| {
+                whole_value_literal_message(&node.id, agent, command, field, &literal)
+            })
+            .collect();
+        out.extend(
+            self.templated_literal_inputs(node.merged_params().as_ref())
+                .iter()
+                .map(|input| literal_input_message(&node.id, agent, command, input)),
+        );
+        out
+    }
+}
+
+/// The human message for [`E_APP_INPUT_MUST_BE_LITERAL`] when a node writes its whole `field`
+/// (`inputs` or `config`) as a template rather than a mapping, while the command has literal
+/// inputs that template could fill.
+pub fn whole_value_literal_message(
+    node: &str,
+    agent: &str,
+    command: &str,
+    field: &str,
+    literal: &[&str],
+) -> String {
+    let names = literal
+        .iter()
+        .map(|name| format!("`{name}`"))
+        .collect::<Vec<_>>()
+        .join(", ");
+    format!(
+        "node {node:?} fills its whole `{field}:` from a template, but {agent}.{command} declares          {names} as `literal: true`. When the run renders that template it could put text          supplied after approval into {names}, so the approved `.lock` would no longer pin          exactly what runs. Write `{field}:` as a mapping with {names} written out inline, and          pass run-time data through a templatable input (e.g. `args`) instead."
+    )
 }
 
 /// Whether a value carries template syntax anywhere: `{{ … }}`, `{% … %}` or `{# … #}`.
diff --git a/cli/src/runtime/orchestrator.rs b/cli/src/runtime/orchestrator.rs
index 6be573eeb..7e020d2ee 100644
--- a/cli/src/runtime/orchestrator.rs
+++ b/cli/src/runtime/orchestrator.rs
@@ -876,8 +876,10 @@ impl Orchestrator {
     /// Validate and the lock compiler already refuse this; the runtime repeats it because a lock
     /// produced by an older compiler predates the rule, and because the check is only meaningful
     /// on the un-rendered value — after `render_config` the text no longer says where it came
-    /// from. So this reads the node's merged `config:` + `inputs:` straight from the app the lock
-    /// approved, and the orchestrator calls it ahead of every `render_config` on an agent node.
+    /// from. So this reads the node's `config:` and `inputs:` straight from the app the lock
+    /// approved — each on its own as well as merged, so a whole-field template (`inputs: '{{
+    /// inputs.payload }}'`) that would render into an object carrying `code` is caught too — and
+    /// the orchestrator calls it ahead of every `render_config` on an agent node.
     fn ensure_literal_inputs(
         &self,
         node: &Node,
@@ -890,15 +892,14 @@ impl Orchestrator {
         let Some(cmd) = agent.commands.get(command) else {
             return Ok(());
         };
-        if let Some(input) = cmd
-            .templated_literal_inputs(node.merged_params().as_ref())
+        if let Some(message) = cmd
+            .literal_input_violations(node, agent_id, command)
             .into_iter()
             .next()
         {
             return Err(AwareError::Validation(format!(
-                "[{}] {}",
+                "[{}] {message}",
                 crate::manifest::agent::E_APP_INPUT_MUST_BE_LITERAL,
-                crate::manifest::agent::literal_input_message(&node.id, agent_id, command, &input)
             )));
         }
         Ok(())
@@ -2695,6 +2696,59 @@ commands:
             .expect("literal code with templated args must run");
     }
 
+    /// #692 review: the runtime refuses a whole-node template that would resolve into a literal
+    /// input. `inputs: '{{ inputs.payload }}'` renders (whole-value, #205) to the object the run
+    /// supplies — `code` included — so without this check runtime-supplied code reaches the agent
+    /// under an approved lock. The mock invoker HAS a canned output, so each shape would run.
+    #[tokio::test]
+    async fn the_runtime_refuses_a_whole_node_template_feeding_a_literal_input() {
+        let shapes = [
+            ("inputs only", "    inputs: '{{ inputs.payload }}'\n"),
+            ("config only", "    config: '{{ inputs.payload }}'\n"),
+            (
+                "mapping config + string inputs",
+                "    config:\n      code: 'def run(ctx): return 1'\n    inputs: '{{ inputs.payload }}'\n",
+            ),
+        ];
+        for (shape, params) in shapes {
+            let app: App = serde_yaml::from_str(&format!(
+                "app: lit\nversion: 0.1.0\ndescription: x\nnodes:\n  - id: animate\n    \
+                 agent: runner\n    command: exec\n{params}connections: []\nrequires: []\n"
+            ))
+            .unwrap();
+            let invoker: Arc<dyn AgentInvoker> = Arc::new(MockInvoker::new().with_single(
+                "runner",
+                "exec",
+                serde_json::json!({ "ok": true }),
+            ));
+            let (mut orch, tmp, _log) = make_orchestrator(app, invoker).await;
+            let agent_dir = tmp.path().join("aware").join("agents").join("runner");
+            std::fs::create_dir_all(&agent_dir).unwrap();
+            std::fs::write(
+                agent_dir.join("manifest.yaml"),
+                "agent: runner\nversion: 0.0.1\ndescription: x\nstateful: false\nlicense: MIT\n\
+                 transport: { builtin: {} }\ncommands:\n  exec:\n    lifecycle: single\n    \
+                 mode: write\n    description: x\n    inputs:\n      code: { type: string, literal: true }\n      \
+                 args: { type: object }\n",
+            )
+            .unwrap();
+            orch.ctx.inputs = serde_json::json!({
+                "payload": { "code": "import os; os.system('evil')", "args": {} }
+            });
+            let err = orch
+                .run_one_shot()
+                .await
+                .expect_err(&format!("{shape}: runtime-supplied code must not run"));
+            let text = err.to_string();
+            assert!(
+                text.contains("E_APP_INPUT_MUST_BE_LITERAL"),
+                "{shape}: {text}"
+            );
+            assert!(text.contains("\"animate\""), "{shape}: {text}");
+            assert!(text.contains("`code`"), "{shape}: {text}");
+        }
+    }
+
     #[tokio::test]
     async fn frozen_node_emits_pinned_output_and_skips_the_agent() {
         // A frozen node must NOT call its agent (the empty invoker would error if it did) and must
diff --git a/cli/src/validate.rs b/cli/src/validate.rs
index 7cb507383..3195954e4 100644
--- a/cli/src/validate.rs
+++ b/cli/src/validate.rs
@@ -1527,12 +1527,10 @@ fn check_node_agents(
             if let Some(cmd_name) = &n.command
                 && let Some(cmd) = d.manifest.commands.get(cmd_name.as_str())
             {
-                for input in cmd.templated_literal_inputs(n.merged_params().as_ref()) {
+                for message in cmd.literal_input_violations(n, agent_id, cmd_name) {
                     out.push(ValidationIssue::error(
                         crate::manifest::agent::E_APP_INPUT_MUST_BE_LITERAL,
-                        crate::manifest::agent::literal_input_message(
-                            &n.id, agent_id, cmd_name, &input,
-                        ),
+                        message,
                     ));
                 }
             }
@@ -3452,6 +3450,70 @@ app: after-everything
         );
     }
 
+    /// #692 review: a literal input cannot be reached by templating the WHOLE `inputs:` or
+    /// `config:` instead of the input by name. `merged_params()` returns such a node's string as
+    /// is, so a by-name lookup finds no `code` and passes — while `render_config` resolves the
+    /// whole-value template into an object that carries `code`. Each shape is refused naming the
+    /// literal input; a command with NO literal input keeps accepting a whole-node template.
+    #[test]
+    fn a_whole_node_template_cannot_reach_a_literal_input() {
+        let agents = vec![crate::manifest::loader::DiscoveredAgent {
+            manifest: serde_yaml::from_str(
+                "agent: runner\nversion: 0.1.0\ndescription: x\nstateful: false\nlicense: MIT\n\
+                 transport:\n  builtin: {}\ncommands:\n  exec:\n    lifecycle: single\n    \
+                 mode: write\n    description: x\n    inputs:\n      code: { type: string, literal: true }\n      \
+                 args: { type: object }\n  plain:\n    lifecycle: single\n    mode: write\n    \
+                 description: x\n    inputs:\n      code: { type: string }\n",
+            )
+            .unwrap(),
+            root: std::path::PathBuf::from("."),
+        }];
+        let app = |command: &str, params: &str| -> App {
+            serde_yaml::from_str(&format!(
+                "app: lit\nversion: 0.0.1\ndescription: x\nrequires: []\n\
+                 nodes:\n  - id: animate\n    agent: runner\n    command: {command}\n{params}"
+            ))
+            .unwrap()
+        };
+        let shapes = [
+            ("inputs only", "    inputs: '{{ inputs.payload }}'\n"),
+            ("config only", "    config: '{{ inputs.payload }}'\n"),
+            (
+                "mapping config + string inputs",
+                "    config:\n      code: 'def run(ctx): return 1'\n    inputs: '{{ inputs.payload }}'\n",
+            ),
+        ];
+        for (shape, params) in shapes {
+            let issues = validate_app_agents(&app("exec", params), &agents);
+            let hit = issues
+                .iter()
+                .find(|i| i.code == "E_APP_INPUT_MUST_BE_LITERAL")
+                .unwrap_or_else(|| {
+                    panic!("{shape}: a whole-node template must be refused: {issues:?}")
+                });
+            assert!(
+                hit.message.contains("\"animate\""),
+                "{shape}: {}",
+                hit.message
+            );
+            assert!(hit.message.contains("`code`"), "{shape}: {}", hit.message);
+            assert!(
+                hit.message.contains("runner.exec"),
+                "{shape}: {}",
+                hit.message
+            );
+
+            // Negative control: the same node on a command with no literal input is untouched.
+            let plain = validate_app_agents(&app("plain", params), &agents);
+            assert!(
+                !plain
+                    .iter()
+                    .any(|i| i.code == "E_APP_INPUT_MUST_BE_LITERAL"),
+                "{shape}: a non-literal command must still accept a whole-node template: {plain:?}"
+            );
+        }
+    }
+
     #[test]
     fn rejects_node_referencing_planned_command() {
         // The agent is available, but one command is `status: planned` (#199) — an
diff --git a/cli/tests/blender_exec.rs b/cli/tests/blender_exec.rs
index 7a715d8c5..521a07fea 100644
--- a/cli/tests/blender_exec.rs
+++ b/cli/tests/blender_exec.rs
@@ -170,3 +170,35 @@ fn a_dry_run_of_exec_never_launches_blender() {
         "the dry run must report the exec node as a would-write:\n{text}"
     );
 }
+
+/// #692 review: templating the WHOLE `inputs:` of the shipped `blender/exec` (which would render
+/// into an object carrying `code`) is refused at validate and compile just like a templated
+/// `code`, and no lock is written.
+#[test]
+fn validate_and_compile_refuse_a_whole_inputs_template_on_exec() {
+    let home = blender_home();
+    let body = "app: exec-whole\nversion: 0.1.0\ndescription: exec probe\nrequires:\n  - blender@0.2.x\n\
+                nodes:\n  - id: animate\n    agent: blender\n    command: exec\n    \
+                inputs: '{{ inputs.payload }}'\n    safety:\n      transaction-group: probe\n      \
+                snapshot: false\nconnections: []\n";
+    let app = app_dir("exec-whole", body);
+    for verb in ["validate", "compile"] {
+        let (ok, text) = run_aware(home.path(), &["app", verb], app.path(), &[]);
+        assert!(
+            !ok,
+            "a whole-inputs template must fail {verb}; got:\n{text}"
+        );
+        assert!(
+            text.contains("E_APP_INPUT_MUST_BE_LITERAL"),
+            "{verb}: {text}"
+        );
+        assert!(
+            text.contains("`code`"),
+            "{verb}: the error must name the input:\n{text}"
+        );
+    }
+    assert!(
+        !app.path().join("exec-whole.lock").exists(),
+        "a refused compile must write no lock"
+    );
+}

From 67d73e222c19b69a3146d3848aa2cc8edc84212e Mon Sep 17 00:00:00 2001
From: Pawel <pawellisowski@o2.pl>
Date: Mon, 12 Oct 2026 13:31:11 +0200
Subject: [PATCH 13/17] fix(blender): Ctrl-C kills Blender's process tree
 instead of orphaning it (#692 review 5)

On Unix Blender is spawned as its own process-group leader so a tree
kill can reach everything it started -- but that also means a terminal
Ctrl-C no longer reaches Blender. One-shot `aware app run` and
`aware agent invoke blender exec` install no Ctrl-C handler, so SIGINT
ended `aware` without running the tree-kill guard or kill_on_drop, and
a headless Blender kept rendering with its GPU context and output file
held.

The Blender wait loop now also waits on Ctrl-C (tokio::signal::ctrl_c,
cross-platform), including while the progress pump is blocked. On it
the whole tree is killed through the same kill_tree path the timeout
uses, any progress already written is drained (bounded), and the call
fails with an "interrupted" error so `aware` exits non-zero. The
interrupt is injected into run_script, so a test can trigger it without
sending a real signal. Windows keeps the same taskkill /T tree kill.
---
 cli/src/render/blender.rs | 150 ++++++++++++++++++++++++++++++++++----
 1 file changed, 136 insertions(+), 14 deletions(-)

diff --git a/cli/src/render/blender.rs b/cli/src/render/blender.rs
index d0a2d6ba3..4bbefca84 100644
--- a/cli/src/render/blender.rs
+++ b/cli/src/render/blender.rs
@@ -37,10 +37,13 @@
 //!
 //! - **No Blender executable** → an actionable error naming the search order and the `AWARE_BLENDER`
 //!   override, never a raw `NotFound` io error.
-//! - **Timeout** → per-call configurable via the `timeout-seconds` input; the process (and on
-//!   Windows its whole tree) is killed so a wedged Blender is never orphaned.
+//! - **Timeout** → per-call configurable via the `timeout-seconds` input; Blender's whole process
+//!   tree is killed so a wedged Blender is never orphaned.
+//! - **Ctrl-C** → the same tree kill, then an "interrupted" error. On Unix Blender leads its own
+//!   process group, so the terminal's SIGINT does not reach it directly; the wait loop listens for
+//!   Ctrl-C itself so a one-shot run cannot exit and leave Blender rendering.
 //!
-//! Both are [`AwareError::Network`] — the CLI's "agent runtime" class (exit 4 in `cli-spec.md`),
+//! All three are [`AwareError::Network`] — the CLI's "agent runtime" class (exit 4 in `cli-spec.md`),
 //! which is what `CliInvoker` already uses for a transport binary that will not spawn.
 //!
 //! ## Progress (#405 parity, #692)
@@ -752,6 +755,16 @@ fn kill_tree(pid: u32) {
     let _ = tree_kill_command(pid, cfg!(windows)).status();
 }
 
+/// How the wait on Blender ended.
+enum Waited {
+    /// Blender exited on its own (or waiting on it failed).
+    Exited(std::io::Result<std::process::ExitStatus>),
+    /// The `timeout-seconds` budget ran out.
+    TimedOut,
+    /// The user pressed Ctrl-C.
+    Interrupted,
+}
+
 /// How long the progress drain after a timeout kill may take before the timeout is reported anyway.
 const TIMEOUT_DRAIN_GRACE: Duration = Duration::from_secs(2);
 
@@ -784,6 +797,15 @@ impl BlenderProgress {
     }
 }
 
+/// Resolves when the user presses Ctrl-C (SIGINT on Unix, the console Ctrl-C/Ctrl-Break event on
+/// Windows). Never resolves when the handler cannot be installed, so a platform without one simply
+/// runs on to the timeout as before rather than failing the call.
+async fn ctrl_c_pressed() {
+    if tokio::signal::ctrl_c().await.is_err() {
+        std::future::pending::<()>().await;
+    }
+}
+
 /// Run one `blender` agent command: spawn headless Blender on the command's script, recover the
 /// framed payload, and surface the script's named errors intact.
 ///
@@ -815,7 +837,16 @@ pub async fn run_blender_command(
 
     let script = script_path(command, agent_root)?;
     let blender = find_blender()?;
-    run_script(command, &blender, &script, args, budget, progress).await
+    run_script(
+        command,
+        &blender,
+        &script,
+        args,
+        budget,
+        progress,
+        ctrl_c_pressed(),
+    )
+    .await
 }
 
 /// Spawn `blender -b -P <script> -- @<inputs>` and turn what it prints into the command's result.
@@ -828,6 +859,7 @@ async fn run_script(
     args: &Value,
     budget: Duration,
     progress: BlenderProgress,
+    interrupt: impl std::future::Future<Output = ()>,
 ) -> Result<Value, AwareError> {
     let inputs = ScratchInputs::write(args)?;
 
@@ -885,25 +917,55 @@ async fn run_script(
     // same select that drains pipes and enforces the timeout — it never replaces that runner
     // (which is what `wait_with_output` would have done, losing the tree kill). `Child::wait` is
     // cancel-safe, so re-polling it every interval loses nothing.
+    //
+    // It also waits on `interrupt` (Ctrl-C in production). On Unix Blender leads its own process
+    // group, so a terminal's SIGINT no longer reaches it, and a one-shot `aware app run` /
+    // `aware agent invoke` has no handler of its own: without this branch SIGINT ended `aware`
+    // without the tree kill and Blender rendered on. Pinned once, outside the loop, so the handler
+    // registers on the first poll and stays registered for the whole call.
     let deadline = tokio::time::Instant::now() + budget;
+    let mut interrupt = std::pin::pin!(interrupt);
     let waited = loop {
         tokio::select! {
-            status = child.wait() => break Some(status),
-            _ = tokio::time::sleep_until(deadline) => break None,
+            status = child.wait() => break Waited::Exited(status),
+            _ = tokio::time::sleep_until(deadline) => break Waited::TimedOut,
+            _ = &mut interrupt => break Waited::Interrupted,
             _ = tokio::time::sleep(crate::runtime::progress::POLL_INTERVAL), if relay.is_some() => {
-                // The deadline stays live WHILE pumping: a pump blocked on a full channel (a slow
-                // trace writer) must not carry the call past `timeout-seconds`.
-                if let Some(relay) = relay.as_mut()
-                    && tokio::time::timeout_at(deadline, relay.pump()).await.is_err()
-                {
-                    break None;
+                // The deadline and the interrupt stay live WHILE pumping: a pump blocked on a
+                // full channel (a slow trace writer) must not carry the call past either.
+                if let Some(relay) = relay.as_mut() {
+                    tokio::select! {
+                        pumped = tokio::time::timeout_at(deadline, relay.pump()) => {
+                            if pumped.is_err() {
+                                break Waited::TimedOut;
+                            }
+                        }
+                        _ = &mut interrupt => break Waited::Interrupted,
+                    }
                 }
             }
         }
     };
 
     let status = match waited {
-        Some(status) => {
+        Waited::Interrupted => {
+            // Same order as the timeout: the tree dies first, then what it reported is delivered
+            // (bounded), then the call fails so `aware` exits non-zero.
+            kill_blender(&mut child, &mut tree_guard).await;
+            if let Some(relay) = relay.as_mut() {
+                let _ = tokio::time::timeout(TIMEOUT_DRAIN_GRACE, relay.drain_to_end()).await;
+            }
+            stdout_task.abort();
+            stderr_task.abort();
+            return Err(AwareError::Network(format!(
+                "blender {command}: interrupted (Ctrl-C) and the Blender process was killed.
+                   blender: {}
+  script:  {}",
+                blender.display(),
+                script.display(),
+            )));
+        }
+        Waited::Exited(status) => {
             let status = status.map_err(|e| {
                 AwareError::Network(format!("blender {command}: waiting on Blender failed: {e}"))
             })?;
@@ -911,7 +973,7 @@ async fn run_script(
             tree_guard.disarm();
             status
         }
-        None => {
+        Waited::TimedOut => {
             // The design doc's other required named error. Kill first, report second — a wedged
             // Blender must not outlive the call.
             kill_blender(&mut child, &mut tree_guard).await;
@@ -1550,6 +1612,7 @@ mod tests {
                 path: channel.clone(),
                 tx,
             },
+            std::future::pending(),
         )
         .await
         .expect("the fake Blender frames a successful result");
@@ -1600,6 +1663,7 @@ mod tests {
                 path: tmp.path().join("progress-2.jsonl"),
                 tx,
             },
+            std::future::pending(),
         )
         .await
         .expect_err("a wedged Blender must time out");
@@ -1690,6 +1754,7 @@ mod tests {
             &exec_args(),
             Duration::from_millis(3_000),
             BlenderProgress::Off,
+            std::future::pending(),
         )
         .await
         .expect_err("the hanging stand-in must time out");
@@ -1704,6 +1769,60 @@ mod tests {
         assert_ticking_stopped(&ticks, "after a timeout").await;
     }
 
+    /// #692 review: on Unix Blender leads its own process group, so a terminal Ctrl-C no longer
+    /// reaches it, and a one-shot run has no Ctrl-C handler of its own — SIGINT killed `aware`
+    /// without running the tree kill and Blender rendered on. The wait loop therefore also waits on
+    /// the interrupt: it must end the call promptly with an "interrupted" error (non-zero exit),
+    /// kill through the shared tree kill exactly once, and leave nothing ticking. The interrupt is
+    /// injected (production passes `ctrl_c_pressed()`), so this runs without sending a signal.
+    #[tokio::test(flavor = "current_thread")]
+    async fn an_interrupt_kills_the_whole_tree_and_fails_the_call() {
+        let tmp = tempfile::tempdir().expect("tempdir");
+        let ticks = tmp.path().join("ticks.txt");
+        let blender = fake_blender_with_ticking_child(tmp.path(), &ticks);
+        TREE_KILLS.with(|kills| kills.borrow_mut().clear());
+
+        let ticks_for_interrupt = ticks.clone();
+        let interrupt = async move {
+            while !ticks_for_interrupt.exists() {
+                tokio::time::sleep(Duration::from_millis(100)).await;
+            }
+            tokio::time::sleep(Duration::from_millis(1_000)).await;
+        };
+        let started = std::time::Instant::now();
+        let outcome = tokio::time::timeout(
+            Duration::from_secs(25),
+            run_script(
+                "exec",
+                &blender,
+                &tmp.path().join("exec.py"),
+                &exec_args(),
+                Duration::from_secs(300),
+                BlenderProgress::Off,
+                interrupt,
+            ),
+        )
+        .await;
+        let err = outcome
+            .expect("an interrupt must end the call, not leave it waiting on Blender")
+            .expect_err("an interrupted call must fail");
+        let text = err.to_string();
+        assert!(text.contains("interrupted"), "{text}");
+        assert_ne!(err.exit_code(), 0, "{text}");
+        assert!(
+            started.elapsed() < Duration::from_secs(20),
+            "took {:?}",
+            started.elapsed()
+        );
+        let kills = TREE_KILLS.with(|kills| kills.borrow().clone());
+        assert_eq!(
+            kills.len(),
+            1,
+            "the interrupt must kill through the shared tree kill exactly once: {kills:?}"
+        );
+        assert_ticking_stopped(&ticks, "after an interrupt").await;
+    }
+
     #[test]
     fn the_tree_kill_targets_the_tree_on_both_platforms() {
         let windows = tree_kill_command(4242, true);
@@ -1786,6 +1905,7 @@ sleep 120
             &args,
             Duration::from_secs(300),
             BlenderProgress::Off,
+            std::future::pending(),
         );
         // Abandon the call once the grandchild is demonstrably running.
         let ticks_for_wait = ticks.clone();
@@ -1850,6 +1970,7 @@ sleep 120
                 &exec_args(),
                 Duration::from_millis(1_500),
                 BlenderProgress::Relay { path: channel, tx },
+                std::future::pending(),
             ),
         )
         .await;
@@ -1885,6 +2006,7 @@ sleep 120
             &exec_args(),
             Duration::from_secs(60),
             BlenderProgress::Passthrough(callers.clone()),
+            std::future::pending(),
         )
         .await
         .expect("passthrough run");

From b7cabf06cf6c3706c2e1ad3dd0e717e52063566a Mon Sep 17 00:00:00 2001
From: Pawel <pawellisowski@o2.pl>
Date: Mon, 12 Oct 2026 13:41:29 +0200
Subject: [PATCH 14/17] fix(blender): Ctrl-C still ends a one-shot run after a
 Blender call finishes (#692 review 5)

The previous commit had each Blender call wait on tokio::signal::ctrl_c.
tokio's handler, once installed, stays for the life of the process and
replaces the default "Ctrl-C ends the program", so a one-shot run whose
Blender call had finished swallowed every later Ctrl-C while other
nodes ran.

There is now ONE process-wide watcher, installed lazily by the first
Blender call on its own thread and runtime. Each Ctrl-C is routed by a
pure rule: a Blender call in flight is woken (it kills its tree and
fails as interrupted, as before); with nothing in flight, a mode that
owns shutdown itself (long-running `aware app run`, which now claims a
CtrlCOwner for the life of the run) is deferred to; otherwise the
process exits with 130, the default SIGINT outcome.
---
 cli/src/commands/app.rs      |   3 +
 cli/src/render/blender.rs    |  17 ++--
 cli/src/runtime/lifecycle.rs | 166 +++++++++++++++++++++++++++++++++++
 3 files changed, 175 insertions(+), 11 deletions(-)

diff --git a/cli/src/commands/app.rs b/cli/src/commands/app.rs
index b1f4278ad..4c365a430 100644
--- a/cli/src/commands/app.rs
+++ b/cli/src/commands/app.rs
@@ -777,6 +777,9 @@ async fn run(
         // Set up stop channel + signal handler. Reader graphs explicitly signal the bridge before
         // stopping orchestration because Unix `app stop` targets only this AWARE process.
         let (stop_tx, stop_rx) = stop_channel();
+        // This mode owns Ctrl-C (graceful stop below), so the process-wide watcher a Blender
+        // call installs defers to it instead of exiting the process. Held until the run ends.
+        let _ctrl_c_owner = crate::runtime::lifecycle::CtrlCOwner::claim();
         let _ctrl_handle = if model_reader_control.is_some() {
             tokio::spawn(async move {
                 if model_reader_termination_signal().await.is_ok() {
diff --git a/cli/src/render/blender.rs b/cli/src/render/blender.rs
index 4bbefca84..0d950b153 100644
--- a/cli/src/render/blender.rs
+++ b/cli/src/render/blender.rs
@@ -797,15 +797,6 @@ impl BlenderProgress {
     }
 }
 
-/// Resolves when the user presses Ctrl-C (SIGINT on Unix, the console Ctrl-C/Ctrl-Break event on
-/// Windows). Never resolves when the handler cannot be installed, so a platform without one simply
-/// runs on to the timeout as before rather than failing the call.
-async fn ctrl_c_pressed() {
-    if tokio::signal::ctrl_c().await.is_err() {
-        std::future::pending::<()>().await;
-    }
-}
-
 /// Run one `blender` agent command: spawn headless Blender on the command's script, recover the
 /// framed payload, and surface the script's named errors intact.
 ///
@@ -837,6 +828,10 @@ pub async fn run_blender_command(
 
     let script = script_path(command, agent_root)?;
     let blender = find_blender()?;
+    // Ctrl-C while Blender works kills its tree and fails the call; the ONE process-wide
+    // watcher keeps every other Ctrl-C ending the process as before (`runtime::lifecycle`).
+    crate::runtime::lifecycle::ensure_ctrl_c_watcher();
+    let mut interrupt = crate::runtime::lifecycle::track_call();
     run_script(
         command,
         &blender,
@@ -844,7 +839,7 @@ pub async fn run_blender_command(
         args,
         budget,
         progress,
-        ctrl_c_pressed(),
+        async move { interrupt.interrupted().await },
     )
     .await
 }
@@ -1774,7 +1769,7 @@ mod tests {
     /// without running the tree kill and Blender rendered on. The wait loop therefore also waits on
     /// the interrupt: it must end the call promptly with an "interrupted" error (non-zero exit),
     /// kill through the shared tree kill exactly once, and leave nothing ticking. The interrupt is
-    /// injected (production passes `ctrl_c_pressed()`), so this runs without sending a signal.
+    /// injected (production passes the process-wide watcher's `track_call()`), so this runs without sending a signal.
     #[tokio::test(flavor = "current_thread")]
     async fn an_interrupt_kills_the_whole_tree_and_fails_the_call() {
         let tmp = tempfile::tempdir().expect("tempdir");
diff --git a/cli/src/runtime/lifecycle.rs b/cli/src/runtime/lifecycle.rs
index 673d32302..bb32dc117 100644
--- a/cli/src/runtime/lifecycle.rs
+++ b/cli/src/runtime/lifecycle.rs
@@ -19,10 +19,176 @@ pub fn install_ctrl_c_handler(stop: StopSender) -> tokio::task::JoinHandle<()> {
     })
 }
 
+// ── The process-wide Ctrl-C watcher (#692 review) ──
+//
+// A Blender call waits on Ctrl-C itself, because on Unix Blender leads its own process group and a
+// terminal's SIGINT no longer reaches it. But tokio's Ctrl-C handler, once installed, stays
+// installed for the life of the process and replaces the default "Ctrl-C ends the program": a
+// one-shot run that had finished its Blender call would then swallow every later Ctrl-C. So there
+// is ONE watcher, installed lazily by the first Blender call, and each Ctrl-C it sees is routed by
+// [`ctrl_c_action`]: interrupt the Blender calls in flight; otherwise defer to a mode that owns
+// shutdown itself (long-running `aware app run`); otherwise end the process the way the default
+// SIGINT would have.
+
+use std::sync::atomic::{AtomicUsize, Ordering};
+use std::sync::{Once, OnceLock};
+
+/// Blender calls currently waiting on Ctrl-C (live [`InterruptWatch`]es).
+static IN_FLIGHT: AtomicUsize = AtomicUsize::new(0);
+/// Live [`CtrlCOwner`]s: modes that handle Ctrl-C themselves and must not be exited under.
+static OWNERS: AtomicUsize = AtomicUsize::new(0);
+/// Bumped once per Ctrl-C delivered to in-flight calls; each call watches it.
+static GENERATION: OnceLock<watch::Sender<u64>> = OnceLock::new();
+static WATCHER: Once = Once::new();
+
+/// The exit code for a Ctrl-C that ends the process: 128 + SIGINT, what a shell reports.
+pub const CTRL_C_EXIT_CODE: i32 = 130;
+
+fn generation() -> &'static watch::Sender<u64> {
+    GENERATION.get_or_init(|| watch::channel(0).0)
+}
+
+/// What one Ctrl-C does, given the process's state at that moment.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum CtrlCAction {
+    /// A Blender call is in flight: it kills its process tree and fails as interrupted.
+    InterruptCalls,
+    /// Nothing in flight, but a mode that owns shutdown (long-running run) is handling it.
+    DeferToOwner,
+    /// Nothing in flight and nobody else listening: end the process, as the default SIGINT would.
+    ExitProcess,
+}
+
+/// The routing rule, pure so every branch is testable without sending a signal.
+pub fn ctrl_c_action(in_flight: usize, owners: usize) -> CtrlCAction {
+    if in_flight > 0 {
+        CtrlCAction::InterruptCalls
+    } else if owners > 0 {
+        CtrlCAction::DeferToOwner
+    } else {
+        CtrlCAction::ExitProcess
+    }
+}
+
+/// Apply one Ctrl-C to the live process state and return what was decided. `ExitProcess` is
+/// returned rather than performed (the watcher performs it), so a test can observe the decision.
+pub fn deliver_ctrl_c() -> CtrlCAction {
+    let action = ctrl_c_action(
+        IN_FLIGHT.load(Ordering::SeqCst),
+        OWNERS.load(Ordering::SeqCst),
+    );
+    if action == CtrlCAction::InterruptCalls {
+        generation().send_modify(|g| *g = g.wrapping_add(1));
+    }
+    action
+}
+
+/// Install the one process-wide watcher, if it is not running yet. It lives on its own thread and
+/// runtime, so it neither depends on nor dies with whichever runtime made the first Blender call.
+/// If the thread or its runtime cannot start, nothing is installed and Ctrl-C keeps its default.
+pub fn ensure_ctrl_c_watcher() {
+    WATCHER.call_once(|| {
+        let _ = std::thread::Builder::new()
+            .name("aware-ctrl-c".into())
+            .spawn(|| {
+                let Ok(rt) = tokio::runtime::Builder::new_current_thread()
+                    .enable_all()
+                    .build()
+                else {
+                    return;
+                };
+                rt.block_on(async {
+                    while tokio::signal::ctrl_c().await.is_ok() {
+                        if deliver_ctrl_c() == CtrlCAction::ExitProcess {
+                            std::process::exit(CTRL_C_EXIT_CODE);
+                        }
+                    }
+                });
+            });
+    });
+}
+
+/// One in-flight call's view of Ctrl-C. Counted while alive; dropping it ends the count.
+pub struct InterruptWatch {
+    rx: watch::Receiver<u64>,
+}
+
+/// Register a call as in flight. Subscribes BEFORE counting, so a Ctrl-C that sees the count is
+/// always one this call will observe.
+pub fn track_call() -> InterruptWatch {
+    let rx = generation().subscribe();
+    IN_FLIGHT.fetch_add(1, Ordering::SeqCst);
+    InterruptWatch { rx }
+}
+
+impl InterruptWatch {
+    /// Resolves at the next Ctrl-C delivered to in-flight calls.
+    pub async fn interrupted(&mut self) {
+        if self.rx.changed().await.is_err() {
+            std::future::pending::<()>().await;
+        }
+    }
+}
+
+impl Drop for InterruptWatch {
+    fn drop(&mut self) {
+        IN_FLIGHT.fetch_sub(1, Ordering::SeqCst);
+    }
+}
+
+/// Held by a mode that handles Ctrl-C itself (long-running `aware app run`), so the watcher never
+/// exits the process out from under that mode's own graceful shutdown.
+pub struct CtrlCOwner(());
+
+impl CtrlCOwner {
+    pub fn claim() -> Self {
+        OWNERS.fetch_add(1, Ordering::SeqCst);
+        CtrlCOwner(())
+    }
+}
+
+impl Drop for CtrlCOwner {
+    fn drop(&mut self) {
+        OWNERS.fetch_sub(1, Ordering::SeqCst);
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
 
+    /// #692 review: after a Blender call has finished, Ctrl-C must still end a one-shot run (the
+    /// default SIGINT outcome); a call in flight is interrupted instead; and a mode that owns
+    /// shutdown is deferred to rather than exited under.
+    #[test]
+    fn ctrl_c_interrupts_calls_in_flight_and_otherwise_ends_the_process_unless_owned() {
+        assert_eq!(ctrl_c_action(0, 0), CtrlCAction::ExitProcess);
+        assert_eq!(ctrl_c_action(1, 0), CtrlCAction::InterruptCalls);
+        assert_eq!(ctrl_c_action(2, 0), CtrlCAction::InterruptCalls);
+        assert_eq!(ctrl_c_action(0, 1), CtrlCAction::DeferToOwner);
+        // In long-running mode a Blender call in flight is still interrupted (its owner stops too).
+        assert_eq!(ctrl_c_action(1, 1), CtrlCAction::InterruptCalls);
+        assert_ne!(CTRL_C_EXIT_CODE, 0);
+    }
+
+    /// The live wiring: a tracked call is woken by a delivered Ctrl-C; once it is dropped the same
+    /// Ctrl-C would end the process; a claimed owner turns that into a deferral.
+    #[tokio::test]
+    async fn a_delivered_ctrl_c_wakes_the_tracked_call_then_falls_back_to_exit() {
+        let mut call = track_call();
+        assert_eq!(deliver_ctrl_c(), CtrlCAction::InterruptCalls);
+        tokio::time::timeout(std::time::Duration::from_secs(5), call.interrupted())
+            .await
+            .expect("the in-flight call must be woken by the Ctrl-C");
+        drop(call);
+
+        assert_eq!(deliver_ctrl_c(), CtrlCAction::ExitProcess);
+        let owner = CtrlCOwner::claim();
+        assert_eq!(deliver_ctrl_c(), CtrlCAction::DeferToOwner);
+        drop(owner);
+        assert_eq!(deliver_ctrl_c(), CtrlCAction::ExitProcess);
+    }
+
     #[tokio::test]
     async fn stop_channel_round_trips() {
         let (tx, mut rx) = stop_channel();

From 207d079b18b0cb47d11982c1b38354532679e190 Mon Sep 17 00:00:00 2001
From: Pawel <pawellisowski@o2.pl>
Date: Mon, 12 Oct 2026 14:38:00 +0200
Subject: [PATCH 15/17] Revert "fix(blender): Ctrl-C still ends a one-shot run
 after a Blender call finishes (#692 review 5)"

This reverts commit b7cabf06cf6c3706c2e1ad3dd0e717e52063566a.
---
 cli/src/commands/app.rs      |   3 -
 cli/src/render/blender.rs    |  17 ++--
 cli/src/runtime/lifecycle.rs | 166 -----------------------------------
 3 files changed, 11 insertions(+), 175 deletions(-)

diff --git a/cli/src/commands/app.rs b/cli/src/commands/app.rs
index 4c365a430..b1f4278ad 100644
--- a/cli/src/commands/app.rs
+++ b/cli/src/commands/app.rs
@@ -777,9 +777,6 @@ async fn run(
         // Set up stop channel + signal handler. Reader graphs explicitly signal the bridge before
         // stopping orchestration because Unix `app stop` targets only this AWARE process.
         let (stop_tx, stop_rx) = stop_channel();
-        // This mode owns Ctrl-C (graceful stop below), so the process-wide watcher a Blender
-        // call installs defers to it instead of exiting the process. Held until the run ends.
-        let _ctrl_c_owner = crate::runtime::lifecycle::CtrlCOwner::claim();
         let _ctrl_handle = if model_reader_control.is_some() {
             tokio::spawn(async move {
                 if model_reader_termination_signal().await.is_ok() {
diff --git a/cli/src/render/blender.rs b/cli/src/render/blender.rs
index 0d950b153..4bbefca84 100644
--- a/cli/src/render/blender.rs
+++ b/cli/src/render/blender.rs
@@ -797,6 +797,15 @@ impl BlenderProgress {
     }
 }
 
+/// Resolves when the user presses Ctrl-C (SIGINT on Unix, the console Ctrl-C/Ctrl-Break event on
+/// Windows). Never resolves when the handler cannot be installed, so a platform without one simply
+/// runs on to the timeout as before rather than failing the call.
+async fn ctrl_c_pressed() {
+    if tokio::signal::ctrl_c().await.is_err() {
+        std::future::pending::<()>().await;
+    }
+}
+
 /// Run one `blender` agent command: spawn headless Blender on the command's script, recover the
 /// framed payload, and surface the script's named errors intact.
 ///
@@ -828,10 +837,6 @@ pub async fn run_blender_command(
 
     let script = script_path(command, agent_root)?;
     let blender = find_blender()?;
-    // Ctrl-C while Blender works kills its tree and fails the call; the ONE process-wide
-    // watcher keeps every other Ctrl-C ending the process as before (`runtime::lifecycle`).
-    crate::runtime::lifecycle::ensure_ctrl_c_watcher();
-    let mut interrupt = crate::runtime::lifecycle::track_call();
     run_script(
         command,
         &blender,
@@ -839,7 +844,7 @@ pub async fn run_blender_command(
         args,
         budget,
         progress,
-        async move { interrupt.interrupted().await },
+        ctrl_c_pressed(),
     )
     .await
 }
@@ -1769,7 +1774,7 @@ mod tests {
     /// without running the tree kill and Blender rendered on. The wait loop therefore also waits on
     /// the interrupt: it must end the call promptly with an "interrupted" error (non-zero exit),
     /// kill through the shared tree kill exactly once, and leave nothing ticking. The interrupt is
-    /// injected (production passes the process-wide watcher's `track_call()`), so this runs without sending a signal.
+    /// injected (production passes `ctrl_c_pressed()`), so this runs without sending a signal.
     #[tokio::test(flavor = "current_thread")]
     async fn an_interrupt_kills_the_whole_tree_and_fails_the_call() {
         let tmp = tempfile::tempdir().expect("tempdir");
diff --git a/cli/src/runtime/lifecycle.rs b/cli/src/runtime/lifecycle.rs
index bb32dc117..673d32302 100644
--- a/cli/src/runtime/lifecycle.rs
+++ b/cli/src/runtime/lifecycle.rs
@@ -19,176 +19,10 @@ pub fn install_ctrl_c_handler(stop: StopSender) -> tokio::task::JoinHandle<()> {
     })
 }
 
-// ── The process-wide Ctrl-C watcher (#692 review) ──
-//
-// A Blender call waits on Ctrl-C itself, because on Unix Blender leads its own process group and a
-// terminal's SIGINT no longer reaches it. But tokio's Ctrl-C handler, once installed, stays
-// installed for the life of the process and replaces the default "Ctrl-C ends the program": a
-// one-shot run that had finished its Blender call would then swallow every later Ctrl-C. So there
-// is ONE watcher, installed lazily by the first Blender call, and each Ctrl-C it sees is routed by
-// [`ctrl_c_action`]: interrupt the Blender calls in flight; otherwise defer to a mode that owns
-// shutdown itself (long-running `aware app run`); otherwise end the process the way the default
-// SIGINT would have.
-
-use std::sync::atomic::{AtomicUsize, Ordering};
-use std::sync::{Once, OnceLock};
-
-/// Blender calls currently waiting on Ctrl-C (live [`InterruptWatch`]es).
-static IN_FLIGHT: AtomicUsize = AtomicUsize::new(0);
-/// Live [`CtrlCOwner`]s: modes that handle Ctrl-C themselves and must not be exited under.
-static OWNERS: AtomicUsize = AtomicUsize::new(0);
-/// Bumped once per Ctrl-C delivered to in-flight calls; each call watches it.
-static GENERATION: OnceLock<watch::Sender<u64>> = OnceLock::new();
-static WATCHER: Once = Once::new();
-
-/// The exit code for a Ctrl-C that ends the process: 128 + SIGINT, what a shell reports.
-pub const CTRL_C_EXIT_CODE: i32 = 130;
-
-fn generation() -> &'static watch::Sender<u64> {
-    GENERATION.get_or_init(|| watch::channel(0).0)
-}
-
-/// What one Ctrl-C does, given the process's state at that moment.
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
-pub enum CtrlCAction {
-    /// A Blender call is in flight: it kills its process tree and fails as interrupted.
-    InterruptCalls,
-    /// Nothing in flight, but a mode that owns shutdown (long-running run) is handling it.
-    DeferToOwner,
-    /// Nothing in flight and nobody else listening: end the process, as the default SIGINT would.
-    ExitProcess,
-}
-
-/// The routing rule, pure so every branch is testable without sending a signal.
-pub fn ctrl_c_action(in_flight: usize, owners: usize) -> CtrlCAction {
-    if in_flight > 0 {
-        CtrlCAction::InterruptCalls
-    } else if owners > 0 {
-        CtrlCAction::DeferToOwner
-    } else {
-        CtrlCAction::ExitProcess
-    }
-}
-
-/// Apply one Ctrl-C to the live process state and return what was decided. `ExitProcess` is
-/// returned rather than performed (the watcher performs it), so a test can observe the decision.
-pub fn deliver_ctrl_c() -> CtrlCAction {
-    let action = ctrl_c_action(
-        IN_FLIGHT.load(Ordering::SeqCst),
-        OWNERS.load(Ordering::SeqCst),
-    );
-    if action == CtrlCAction::InterruptCalls {
-        generation().send_modify(|g| *g = g.wrapping_add(1));
-    }
-    action
-}
-
-/// Install the one process-wide watcher, if it is not running yet. It lives on its own thread and
-/// runtime, so it neither depends on nor dies with whichever runtime made the first Blender call.
-/// If the thread or its runtime cannot start, nothing is installed and Ctrl-C keeps its default.
-pub fn ensure_ctrl_c_watcher() {
-    WATCHER.call_once(|| {
-        let _ = std::thread::Builder::new()
-            .name("aware-ctrl-c".into())
-            .spawn(|| {
-                let Ok(rt) = tokio::runtime::Builder::new_current_thread()
-                    .enable_all()
-                    .build()
-                else {
-                    return;
-                };
-                rt.block_on(async {
-                    while tokio::signal::ctrl_c().await.is_ok() {
-                        if deliver_ctrl_c() == CtrlCAction::ExitProcess {
-                            std::process::exit(CTRL_C_EXIT_CODE);
-                        }
-                    }
-                });
-            });
-    });
-}
-
-/// One in-flight call's view of Ctrl-C. Counted while alive; dropping it ends the count.
-pub struct InterruptWatch {
-    rx: watch::Receiver<u64>,
-}
-
-/// Register a call as in flight. Subscribes BEFORE counting, so a Ctrl-C that sees the count is
-/// always one this call will observe.
-pub fn track_call() -> InterruptWatch {
-    let rx = generation().subscribe();
-    IN_FLIGHT.fetch_add(1, Ordering::SeqCst);
-    InterruptWatch { rx }
-}
-
-impl InterruptWatch {
-    /// Resolves at the next Ctrl-C delivered to in-flight calls.
-    pub async fn interrupted(&mut self) {
-        if self.rx.changed().await.is_err() {
-            std::future::pending::<()>().await;
-        }
-    }
-}
-
-impl Drop for InterruptWatch {
-    fn drop(&mut self) {
-        IN_FLIGHT.fetch_sub(1, Ordering::SeqCst);
-    }
-}
-
-/// Held by a mode that handles Ctrl-C itself (long-running `aware app run`), so the watcher never
-/// exits the process out from under that mode's own graceful shutdown.
-pub struct CtrlCOwner(());
-
-impl CtrlCOwner {
-    pub fn claim() -> Self {
-        OWNERS.fetch_add(1, Ordering::SeqCst);
-        CtrlCOwner(())
-    }
-}
-
-impl Drop for CtrlCOwner {
-    fn drop(&mut self) {
-        OWNERS.fetch_sub(1, Ordering::SeqCst);
-    }
-}
-
 #[cfg(test)]
 mod tests {
     use super::*;
 
-    /// #692 review: after a Blender call has finished, Ctrl-C must still end a one-shot run (the
-    /// default SIGINT outcome); a call in flight is interrupted instead; and a mode that owns
-    /// shutdown is deferred to rather than exited under.
-    #[test]
-    fn ctrl_c_interrupts_calls_in_flight_and_otherwise_ends_the_process_unless_owned() {
-        assert_eq!(ctrl_c_action(0, 0), CtrlCAction::ExitProcess);
-        assert_eq!(ctrl_c_action(1, 0), CtrlCAction::InterruptCalls);
-        assert_eq!(ctrl_c_action(2, 0), CtrlCAction::InterruptCalls);
-        assert_eq!(ctrl_c_action(0, 1), CtrlCAction::DeferToOwner);
-        // In long-running mode a Blender call in flight is still interrupted (its owner stops too).
-        assert_eq!(ctrl_c_action(1, 1), CtrlCAction::InterruptCalls);
-        assert_ne!(CTRL_C_EXIT_CODE, 0);
-    }
-
-    /// The live wiring: a tracked call is woken by a delivered Ctrl-C; once it is dropped the same
-    /// Ctrl-C would end the process; a claimed owner turns that into a deferral.
-    #[tokio::test]
-    async fn a_delivered_ctrl_c_wakes_the_tracked_call_then_falls_back_to_exit() {
-        let mut call = track_call();
-        assert_eq!(deliver_ctrl_c(), CtrlCAction::InterruptCalls);
-        tokio::time::timeout(std::time::Duration::from_secs(5), call.interrupted())
-            .await
-            .expect("the in-flight call must be woken by the Ctrl-C");
-        drop(call);
-
-        assert_eq!(deliver_ctrl_c(), CtrlCAction::ExitProcess);
-        let owner = CtrlCOwner::claim();
-        assert_eq!(deliver_ctrl_c(), CtrlCAction::DeferToOwner);
-        drop(owner);
-        assert_eq!(deliver_ctrl_c(), CtrlCAction::ExitProcess);
-    }
-
     #[tokio::test]
     async fn stop_channel_round_trips() {
         let (tx, mut rx) = stop_channel();

From 956cd5b9d650cec5ed8152261e6d9e8efd6f6552 Mon Sep 17 00:00:00 2001
From: Pawel <pawellisowski@o2.pl>
Date: Mon, 12 Oct 2026 14:38:02 +0200
Subject: [PATCH 16/17] Revert "fix(blender): Ctrl-C kills Blender's process
 tree instead of orphaning it (#692 review 5)"

This reverts commit 67d73e222c19b69a3146d3848aa2cc8edc84212e.
---
 cli/src/render/blender.rs | 150 ++++----------------------------------
 1 file changed, 14 insertions(+), 136 deletions(-)

diff --git a/cli/src/render/blender.rs b/cli/src/render/blender.rs
index 4bbefca84..d0a2d6ba3 100644
--- a/cli/src/render/blender.rs
+++ b/cli/src/render/blender.rs
@@ -37,13 +37,10 @@
 //!
 //! - **No Blender executable** → an actionable error naming the search order and the `AWARE_BLENDER`
 //!   override, never a raw `NotFound` io error.
-//! - **Timeout** → per-call configurable via the `timeout-seconds` input; Blender's whole process
-//!   tree is killed so a wedged Blender is never orphaned.
-//! - **Ctrl-C** → the same tree kill, then an "interrupted" error. On Unix Blender leads its own
-//!   process group, so the terminal's SIGINT does not reach it directly; the wait loop listens for
-//!   Ctrl-C itself so a one-shot run cannot exit and leave Blender rendering.
+//! - **Timeout** → per-call configurable via the `timeout-seconds` input; the process (and on
+//!   Windows its whole tree) is killed so a wedged Blender is never orphaned.
 //!
-//! All three are [`AwareError::Network`] — the CLI's "agent runtime" class (exit 4 in `cli-spec.md`),
+//! Both are [`AwareError::Network`] — the CLI's "agent runtime" class (exit 4 in `cli-spec.md`),
 //! which is what `CliInvoker` already uses for a transport binary that will not spawn.
 //!
 //! ## Progress (#405 parity, #692)
@@ -755,16 +752,6 @@ fn kill_tree(pid: u32) {
     let _ = tree_kill_command(pid, cfg!(windows)).status();
 }
 
-/// How the wait on Blender ended.
-enum Waited {
-    /// Blender exited on its own (or waiting on it failed).
-    Exited(std::io::Result<std::process::ExitStatus>),
-    /// The `timeout-seconds` budget ran out.
-    TimedOut,
-    /// The user pressed Ctrl-C.
-    Interrupted,
-}
-
 /// How long the progress drain after a timeout kill may take before the timeout is reported anyway.
 const TIMEOUT_DRAIN_GRACE: Duration = Duration::from_secs(2);
 
@@ -797,15 +784,6 @@ impl BlenderProgress {
     }
 }
 
-/// Resolves when the user presses Ctrl-C (SIGINT on Unix, the console Ctrl-C/Ctrl-Break event on
-/// Windows). Never resolves when the handler cannot be installed, so a platform without one simply
-/// runs on to the timeout as before rather than failing the call.
-async fn ctrl_c_pressed() {
-    if tokio::signal::ctrl_c().await.is_err() {
-        std::future::pending::<()>().await;
-    }
-}
-
 /// Run one `blender` agent command: spawn headless Blender on the command's script, recover the
 /// framed payload, and surface the script's named errors intact.
 ///
@@ -837,16 +815,7 @@ pub async fn run_blender_command(
 
     let script = script_path(command, agent_root)?;
     let blender = find_blender()?;
-    run_script(
-        command,
-        &blender,
-        &script,
-        args,
-        budget,
-        progress,
-        ctrl_c_pressed(),
-    )
-    .await
+    run_script(command, &blender, &script, args, budget, progress).await
 }
 
 /// Spawn `blender -b -P <script> -- @<inputs>` and turn what it prints into the command's result.
@@ -859,7 +828,6 @@ async fn run_script(
     args: &Value,
     budget: Duration,
     progress: BlenderProgress,
-    interrupt: impl std::future::Future<Output = ()>,
 ) -> Result<Value, AwareError> {
     let inputs = ScratchInputs::write(args)?;
 
@@ -917,55 +885,25 @@ async fn run_script(
     // same select that drains pipes and enforces the timeout — it never replaces that runner
     // (which is what `wait_with_output` would have done, losing the tree kill). `Child::wait` is
     // cancel-safe, so re-polling it every interval loses nothing.
-    //
-    // It also waits on `interrupt` (Ctrl-C in production). On Unix Blender leads its own process
-    // group, so a terminal's SIGINT no longer reaches it, and a one-shot `aware app run` /
-    // `aware agent invoke` has no handler of its own: without this branch SIGINT ended `aware`
-    // without the tree kill and Blender rendered on. Pinned once, outside the loop, so the handler
-    // registers on the first poll and stays registered for the whole call.
     let deadline = tokio::time::Instant::now() + budget;
-    let mut interrupt = std::pin::pin!(interrupt);
     let waited = loop {
         tokio::select! {
-            status = child.wait() => break Waited::Exited(status),
-            _ = tokio::time::sleep_until(deadline) => break Waited::TimedOut,
-            _ = &mut interrupt => break Waited::Interrupted,
+            status = child.wait() => break Some(status),
+            _ = tokio::time::sleep_until(deadline) => break None,
             _ = tokio::time::sleep(crate::runtime::progress::POLL_INTERVAL), if relay.is_some() => {
-                // The deadline and the interrupt stay live WHILE pumping: a pump blocked on a
-                // full channel (a slow trace writer) must not carry the call past either.
-                if let Some(relay) = relay.as_mut() {
-                    tokio::select! {
-                        pumped = tokio::time::timeout_at(deadline, relay.pump()) => {
-                            if pumped.is_err() {
-                                break Waited::TimedOut;
-                            }
-                        }
-                        _ = &mut interrupt => break Waited::Interrupted,
-                    }
+                // The deadline stays live WHILE pumping: a pump blocked on a full channel (a slow
+                // trace writer) must not carry the call past `timeout-seconds`.
+                if let Some(relay) = relay.as_mut()
+                    && tokio::time::timeout_at(deadline, relay.pump()).await.is_err()
+                {
+                    break None;
                 }
             }
         }
     };
 
     let status = match waited {
-        Waited::Interrupted => {
-            // Same order as the timeout: the tree dies first, then what it reported is delivered
-            // (bounded), then the call fails so `aware` exits non-zero.
-            kill_blender(&mut child, &mut tree_guard).await;
-            if let Some(relay) = relay.as_mut() {
-                let _ = tokio::time::timeout(TIMEOUT_DRAIN_GRACE, relay.drain_to_end()).await;
-            }
-            stdout_task.abort();
-            stderr_task.abort();
-            return Err(AwareError::Network(format!(
-                "blender {command}: interrupted (Ctrl-C) and the Blender process was killed.
-                   blender: {}
-  script:  {}",
-                blender.display(),
-                script.display(),
-            )));
-        }
-        Waited::Exited(status) => {
+        Some(status) => {
             let status = status.map_err(|e| {
                 AwareError::Network(format!("blender {command}: waiting on Blender failed: {e}"))
             })?;
@@ -973,7 +911,7 @@ async fn run_script(
             tree_guard.disarm();
             status
         }
-        Waited::TimedOut => {
+        None => {
             // The design doc's other required named error. Kill first, report second — a wedged
             // Blender must not outlive the call.
             kill_blender(&mut child, &mut tree_guard).await;
@@ -1612,7 +1550,6 @@ mod tests {
                 path: channel.clone(),
                 tx,
             },
-            std::future::pending(),
         )
         .await
         .expect("the fake Blender frames a successful result");
@@ -1663,7 +1600,6 @@ mod tests {
                 path: tmp.path().join("progress-2.jsonl"),
                 tx,
             },
-            std::future::pending(),
         )
         .await
         .expect_err("a wedged Blender must time out");
@@ -1754,7 +1690,6 @@ mod tests {
             &exec_args(),
             Duration::from_millis(3_000),
             BlenderProgress::Off,
-            std::future::pending(),
         )
         .await
         .expect_err("the hanging stand-in must time out");
@@ -1769,60 +1704,6 @@ mod tests {
         assert_ticking_stopped(&ticks, "after a timeout").await;
     }
 
-    /// #692 review: on Unix Blender leads its own process group, so a terminal Ctrl-C no longer
-    /// reaches it, and a one-shot run has no Ctrl-C handler of its own — SIGINT killed `aware`
-    /// without running the tree kill and Blender rendered on. The wait loop therefore also waits on
-    /// the interrupt: it must end the call promptly with an "interrupted" error (non-zero exit),
-    /// kill through the shared tree kill exactly once, and leave nothing ticking. The interrupt is
-    /// injected (production passes `ctrl_c_pressed()`), so this runs without sending a signal.
-    #[tokio::test(flavor = "current_thread")]
-    async fn an_interrupt_kills_the_whole_tree_and_fails_the_call() {
-        let tmp = tempfile::tempdir().expect("tempdir");
-        let ticks = tmp.path().join("ticks.txt");
-        let blender = fake_blender_with_ticking_child(tmp.path(), &ticks);
-        TREE_KILLS.with(|kills| kills.borrow_mut().clear());
-
-        let ticks_for_interrupt = ticks.clone();
-        let interrupt = async move {
-            while !ticks_for_interrupt.exists() {
-                tokio::time::sleep(Duration::from_millis(100)).await;
-            }
-            tokio::time::sleep(Duration::from_millis(1_000)).await;
-        };
-        let started = std::time::Instant::now();
-        let outcome = tokio::time::timeout(
-            Duration::from_secs(25),
-            run_script(
-                "exec",
-                &blender,
-                &tmp.path().join("exec.py"),
-                &exec_args(),
-                Duration::from_secs(300),
-                BlenderProgress::Off,
-                interrupt,
-            ),
-        )
-        .await;
-        let err = outcome
-            .expect("an interrupt must end the call, not leave it waiting on Blender")
-            .expect_err("an interrupted call must fail");
-        let text = err.to_string();
-        assert!(text.contains("interrupted"), "{text}");
-        assert_ne!(err.exit_code(), 0, "{text}");
-        assert!(
-            started.elapsed() < Duration::from_secs(20),
-            "took {:?}",
-            started.elapsed()
-        );
-        let kills = TREE_KILLS.with(|kills| kills.borrow().clone());
-        assert_eq!(
-            kills.len(),
-            1,
-            "the interrupt must kill through the shared tree kill exactly once: {kills:?}"
-        );
-        assert_ticking_stopped(&ticks, "after an interrupt").await;
-    }
-
     #[test]
     fn the_tree_kill_targets_the_tree_on_both_platforms() {
         let windows = tree_kill_command(4242, true);
@@ -1905,7 +1786,6 @@ sleep 120
             &args,
             Duration::from_secs(300),
             BlenderProgress::Off,
-            std::future::pending(),
         );
         // Abandon the call once the grandchild is demonstrably running.
         let ticks_for_wait = ticks.clone();
@@ -1970,7 +1850,6 @@ sleep 120
                 &exec_args(),
                 Duration::from_millis(1_500),
                 BlenderProgress::Relay { path: channel, tx },
-                std::future::pending(),
             ),
         )
         .await;
@@ -2006,7 +1885,6 @@ sleep 120
             &exec_args(),
             Duration::from_secs(60),
             BlenderProgress::Passthrough(callers.clone()),
-            std::future::pending(),
         )
         .await
         .expect("passthrough run");

From 291955278d3ddbe796322985fccfdddd4f40d7ce Mon Sep 17 00:00:00 2001
From: Pawel <pawellisowski@o2.pl>
Date: Mon, 12 Oct 2026 14:47:10 +0200
Subject: [PATCH 17/17] fix(blender): Ctrl-C reaches Blender directly; no own
 process group (#692 review 6)

Review 5 tried to make Ctrl-C kill Blender's process tree by keeping
Blender in its own process group (so a tree kill could target the group)
and having aware watch for Ctrl-C itself. That watcher approach kept
drawing defects: a start-up window before the watcher was installed in
which Ctrl-C was lost, a final progress drain that Ctrl-C could not
cancel, and on Windows a descendant that survived after Blender itself
exited. Per the operator's ruling ("Simplify") those two commits are
reverted and the group is dropped instead.

On Unix Blender is no longer spawned with process_group(0). It stays in
aware's foreground process group, so a terminal Ctrl-C (SIGINT to that
group) reaches Blender directly, as before this branch.

The timeout and abandoned-call (drop guard) paths still have to take
Blender's descendants down, and their Unix kill was `kill -KILL -<pid>`,
which only worked because Blender led its own group. It now walks the
tree instead: freeze each pid with SIGSTOP so it cannot spawn mid-walk,
recurse into the children `pgrep -P` reports, then SIGKILL it, children
before parents. The pid is passed as $1, never spliced into the script.
Windows keeps `taskkill /T /F` unchanged.

Tests: the argv test now pins the sh/pgrep walk and asserts nothing
targets a negative pgid; a new source-level test asserts the production
launch sets no process group (there is no Unix host to observe it on,
and Command has no process-group getter). Killing the whole tree on
Ctrl-C reliably is left to a follow-up issue.
---
 cli/src/render/blender.rs | 67 +++++++++++++++++++++++++++++++--------
 1 file changed, 54 insertions(+), 13 deletions(-)

diff --git a/cli/src/render/blender.rs b/cli/src/render/blender.rs
index d0a2d6ba3..fbcee8eb8 100644
--- a/cli/src/render/blender.rs
+++ b/cli/src/render/blender.rs
@@ -698,8 +698,8 @@ async fn kill_blender(child: &mut tokio::process::Child, guard: &mut TreeKillGua
 /// rendering, GPU context and output file held, for up to `timeout-seconds`.
 ///
 /// `kill_on_drop` alone ends only the direct child, which is why the tree kill mirrors
-/// [`kill_blender`]: `taskkill /T /F` on Windows, the child's own process group elsewhere (it is
-/// spawned as a group leader). The guard is declared AFTER the child so it drops first, while
+/// [`kill_blender`]: `taskkill /T /F` on Windows, a walk of the child's descendants elsewhere.
+/// The guard is declared AFTER the child so it drops first, while
 /// the tree is still intact, and it is disarmed the moment the child is reaped — after that the
 /// pid may already belong to someone else.
 struct TreeKillGuard {
@@ -720,8 +720,16 @@ impl Drop for TreeKillGuard {
     }
 }
 
-/// The command that kills `pid` AND everything it started: `taskkill /T /F` on Windows, a
-/// SIGKILL to the process group `pid` leads elsewhere (Blender is spawned as a group leader).
+/// Unix tree kill: freeze `$1` (so it cannot start another child mid-walk), recurse into each
+/// child `pgrep -P` finds, then SIGKILL it. Children die before their parent, so none is
+/// re-parented to init out of reach of the walk. The pid arrives as `$1`, never spliced into the
+/// script text.
+const UNIX_TREE_KILL_SCRIPT: &str = "t() { kill -STOP \"$1\" 2>/dev/null; \
+for c in $(pgrep -P \"$1\"); do t \"$c\"; done; kill -KILL \"$1\" 2>/dev/null; }; t \"$1\"";
+
+/// The command that kills `pid` AND everything it started: `taskkill /T /F` on Windows, a walk of
+/// `pid`'s descendants elsewhere ([`UNIX_TREE_KILL_SCRIPT`]). Blender is NOT a process-group
+/// leader (so terminal Ctrl-C reaches it), so the Unix kill must not target a group.
 /// `windows` is a parameter rather than a `cfg!` inside, so both branches are tested everywhere.
 fn tree_kill_command(pid: u32, windows: bool) -> std::process::Command {
     let mut kill = if windows {
@@ -729,8 +737,8 @@ fn tree_kill_command(pid: u32, windows: bool) -> std::process::Command {
         c.args(["/PID", &pid.to_string(), "/T", "/F"]);
         c
     } else {
-        let mut c = std::process::Command::new("kill");
-        c.args(["-KILL", &format!("-{pid}")]);
+        let mut c = std::process::Command::new("sh");
+        c.args(["-c", UNIX_TREE_KILL_SCRIPT, "sh", &pid.to_string()]);
         c
     };
     kill.stdout(std::process::Stdio::null())
@@ -847,9 +855,9 @@ async fn run_script(
         .stderr(std::process::Stdio::piped())
         // The direct child dies with the call even if the guard below never runs.
         .kill_on_drop(true);
-    // A group leader, so an abandoned call can take the whole tree down (see `TreeKillGuard`).
-    #[cfg(unix)]
-    launch.process_group(0);
+    // Deliberately NOT its own process group on Unix: Blender stays in `aware`'s foreground
+    // group, so a terminal Ctrl-C (SIGINT to that group) reaches Blender directly. The timeout
+    // and drop paths find its descendants by walking the tree instead (see `tree_kill_command`).
     // Set ONLY when somebody reads the channel — a producer takes the variable's presence to mean
     // "the runtime is listening", exactly as on the CLI transport.
     let mut relay = match progress {
@@ -1711,11 +1719,44 @@ mod tests {
         let args: Vec<_> = windows.get_args().collect();
         assert_eq!(args, ["/PID", "4242", "/T", "/F"]);
 
-        // The leading `-` makes `kill` signal the PROCESS GROUP Blender leads, not one pid.
+        // Blender is no longer a group leader, so the Unix kill walks its descendants instead
+        // of signalling a group: the pid is passed as `$1`, and nothing targets `-<pgid>`.
         let unix = tree_kill_command(4242, false);
-        assert_eq!(unix.get_program(), "kill");
-        let args: Vec<_> = unix.get_args().collect();
-        assert_eq!(args, ["-KILL", "-4242"]);
+        assert_eq!(unix.get_program(), "sh");
+        let args: Vec<_> = unix.get_args().map(|a| a.to_str().unwrap()).collect();
+        assert_eq!(args, ["-c", UNIX_TREE_KILL_SCRIPT, "sh", "4242"]);
+        assert!(
+            !args.iter().any(|a| a.contains("-4242")),
+            "no command may target a negative pgid: {args:?}"
+        );
+        assert!(
+            UNIX_TREE_KILL_SCRIPT.contains("pgrep -P \"$1\"")
+                && UNIX_TREE_KILL_SCRIPT.contains("kill -KILL \"$1\"")
+                && !UNIX_TREE_KILL_SCRIPT.contains("-$"),
+            "the walk must find children and kill each pid, never a group: {UNIX_TREE_KILL_SCRIPT}"
+        );
+    }
+
+    /// Operator ruling (#692 review 6): on Unix Blender must stay in `aware`'s foreground process
+    /// group so a terminal Ctrl-C reaches it directly. There is no Unix host in CI on Windows and
+    /// `Command` exposes no process-group getter, so this asserts on the production source.
+    #[test]
+    fn the_unix_launch_does_not_put_blender_in_its_own_process_group() {
+        // A CRLF checkout (core.autocrlf on Windows) must not hide the marker below.
+        let source = include_str!("blender.rs").replace("\r\n", "\n");
+        let production = &source[..source
+            .find("#[cfg(test)]\nmod tests")
+            .expect("the tests module marker must exist, or the slice would cover nothing")];
+        assert!(
+            production.contains("let mut launch = tokio::process::Command::new(blender);"),
+            "the Blender launch moved; point this test at it"
+        );
+        for banned in ["process_group(", "setsid", "setpgid"] {
+            assert!(
+                !production.contains(banned),
+                "the Blender launch must not create its own process group ({banned})"
+            );
+        }
     }
 
     /// #692 review: an ABANDONED call (the run path drops the future — a failed trace write, a