ace-demo 0.23.3 → 0.25.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 19159fe383ba67afd9bb6735e290ceaac5e9750c2f70e71a4415d4def8c1a38d
-  data.tar.gz: f13f657aef8df3cf47e21a817f897f86a5a2c807e3183223719130ef5d920095
+  metadata.gz: 3dc9853e3f70693cc0dc687ab61f645ed432d0afae57a7dd2d7e87c746da9236
+  data.tar.gz: 4f85e3e89c5efefdbab60d3776e4a2c6b92feb2067a1bdbdc7954723caada2c4
 SHA512:
-  metadata.gz: 0ef7941567c83b88fccc3d7a2b32c152778d432332245ea59053883748787f450c4216ecadb2c02d5d0619a2eaa70b9ba83e6428392c418437a8825b5c587b72
-  data.tar.gz: 9280cb9b75d343cd62ff9874a0de91b16f90793e37b9127118e7208a791baebdedcfbb6e0aca0275b509f6ef7e4d63f29037dcfb34e6c6e071c5af1c1735e969
+  metadata.gz: fff3491b92a232bbbfe39aaf01ddf6f0e3924ff0d9644609572248d4338b0ecceadbcbd5a19f0854398e43c482864d2336eea6a9aaceb97e4ba9a9dda6a654f2
+  data.tar.gz: dada165a45b5b184b95f5a49cf30775a8e4290530f13e4ea75337aacfcf2cb4cb4267da621a3311ac2620b82c6d8c71c22a680acc3cb89e0fdc78cb8f9ff342c

data/CHANGELOG.md

@@ -6,6 +6,93 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
+### Fixed
+- Failed YAML tape verification by default when the final asciinema shell exit is non-zero, unless `verify.allow_nonzero_exit: true` opts out explicitly.
+- Surfaced non-zero cast exit codes in `record` / `verify` output and verification reports so broken recordings are diagnosable without opening the raw cast.
+
+## [0.25.6] - 2026-04-16
+
+### Added
+- Added additive YAML `tmux:` recorder-control directives for asciinema-backed demo tapes, covering shared-surface `attach`, `detach`, `wait`, `send`, and optional `capture` actions alongside existing visible `type:` commands.
+
+### Changed
+- Updated `ace-demo` recording/docs to treat tmux orchestration as structured recorder control instead of canonical raw tmux shell glue.
+
+### Fixed
+- Updated the `ace-tmux` runtime dependency constraint to `~> 0.17` so recorder-side tmux directives stay aligned with the new runtime inspection release line.
+- Rejected unsupported YAML `tmux.action: capture` directives during parsing, forwarded recording env values into recorder-side tmux control resolution, and clarified that tmux directives are supported only for the asciinema backend.
+- Rejected YAML `tmux:` directives when the resolved recording backend is `vhs` so unsupported backend/control-surface combinations fail fast instead of being silently ignored during VHS compilation.
+
+## [0.25.1] - 2026-04-16
+
+### Fixed
+- Exported resolved browser executable variables for VHS runs and aligned non-browser E2E verification with explicit constrained-environment failure evidence.
+
+## [0.25.0] - 2026-04-14
+
+### Changed
+- Rewrote `TS-DEMO-001` smoke E2E coverage around public-surface goal contracts by adding non-dry-run preset recording success coverage and stabilizing dry-run and missing-`--pr` verification assertions.
+
+### Technical
+- Added `TC-005-record-preset-success-artifact` runner/verifier assets and updated scenario/aggregate E2E manifests to execute and verify 5 goals.
+- Updated scenario setup to use `${ACE_E2E_SOURCE_ROOT:-$PROJECT_ROOT_PATH}` for resilient `mise.toml` bootstrap in package sandbox runs.
+
+## [0.24.6] - 2026-04-15
+
+### Fixed
+- Made `ace-demo record` print verification summaries safely when optional failure detail arrays are absent, so reruns surface the real verification outcome instead of crashing in CLI output formatting.
+
+## [0.24.5] - 2026-04-15
+
+### Added
+- Added `ace-demo verify` plus a dedicated cast-analysis workflow so failed asciinema recordings can be re-verified and routed to scenario, product, or verifier fixes before re-recording.
+
+### Changed
+- Expanded YAML demo verification with required visible output and ordered output-transition checks, renamed scenario-side failures to `scenario_defect`, and preserved failed recording sandboxes/manifests for follow-up triage.
+
+## [0.24.4] - 2026-04-15
+
+### Changed
+- Tightened demo planning and recording workflows so tmux/UI demos define the visible transition up front and validate the operator viewpoint before recording.
+
+### Technical
+- Refreshed the handbook demo workflow instructions to reject recordings that miss the visible `before -> trigger -> effect -> after` contract for state-transition demos.
+
+## [0.24.3] - 2026-04-13
+
+### Changed
+- Completed the batch i05 migration follow-through for this package and aligned it with the restarted `fast` / `feat` / `e2e` verification model.
+
+### Technical
+- Included in the coordinated assignment-driven patch release for batch i05 package updates.
+
+
+## [0.24.2] - 2026-04-12
+
+### Changed
+- Migrated deterministic `ace-demo` coverage to `test/fast`, kept scenario assets in `test/e2e`, and aligned E2E metadata references to the new fast test paths.
+- Added package-level testing contract guidance for `ace-test ace-demo`, `ace-test ace-demo all`, and `ace-test-e2e ace-demo`.
+
+## [0.24.1] - 2026-04-07
+
+### Added
+- Added fail-closed verification behavior for recording workflows with richer report classification when verification fails.
+
+### Changed
+- Updated demo CLI/recording paths and parser logic to preserve typed failure semantics through verification and recorder execution.
+
+## [0.24.0] - 2026-04-07
+
+### Added
+- Added semantic `verify:` support for YAML/asciinema demo tapes, including required exported variables, forbidden output signatures, and final-state assertion commands.
+- Added structured demo verification reports under `.ace-local/demo/` so failed recordings preserve actionable evidence for retry or bug triage.
+
+### Changed
+- Made `ace-demo record` fail closed on verification errors instead of treating cast mismatches as warning-only output.
+- Classified recording failures as `instruction_defect`, `product_bug`, or `verification_error`, and blocked PR upload/comment when verification does not pass.
+
+### Technical
+- Expanded parser, verifier, recorder, and CLI coverage for semantic verification, report writing, and fail-closed record behavior.
 
 ## [0.23.3] - 2026-03-29
 

data/README.md

@@ -18,7 +18,7 @@
 
 ![ace-demo demo](docs/demo/ace-demo-getting-started.gif)
 
-`ace-demo` records terminal sessions as proof-of-work evidence for agent-driven workflows. Tapes define what to capture — either as simple [VHS](https://github.com/charmbracelet/vhs) scripts (`.tape`) or as YAML specs (`.tape.yml`) with sandbox setup, scenes, and teardown.
+`ace-demo` records terminal sessions as proof-of-work evidence for agent-driven workflows. Tapes define what to capture — either as simple [VHS](https://github.com/charmbracelet/vhs) scripts (`.tape`) or as YAML specs (`.tape.yml`) with sandbox setup, scenes, teardown, and optional tmux recorder-control directives.
 
 Recordings attach directly to GitHub pull requests as reviewable evidence. Requires `vhs`, `chromium`, and `ttyd` for deterministic rendering (see [setup requirements](docs/setup.md)).
 
@@ -43,6 +43,11 @@ scenes:
   commands:
   - type: ace-demo list
     sleep: 4s
+  - tmux:
+      action: wait
+      for: window-active
+      session: fork-demo
+      window: work
   - type: ace-demo record hello
     sleep: 6s
 
@@ -51,10 +56,12 @@ teardown:
 ```
 
 - **setup** — sandbox isolation, git init, fixture copying, or arbitrary shell via `run: <cmd>`
-- **scenes** — named command sequences compiled to VHS directives (`Type`, `Enter`, `Sleep`)
+- **scenes** — named command sequences with visible `type:` shell commands and optional `tmux:` recorder-control directives for asciinema-backed recordings
 - **teardown** — cleanup directives that always run (even on failure)
 - **settings** — optional `font_size`, `width`, `height`, `format` overrides
 
+Use `type:` for on-camera shell commands that should appear in the recording. Use `tmux:` only with the asciinema backend for recorder-control actions such as `attach`, `detach`, `wait`, and `send` when the demo needs deterministic tmux choreography without raw shell glue. YAML tapes recorded with the `vhs` backend must not include `tmux:` directives.
+
 Legacy `.tape` files use raw VHS syntax directly. See the [Usage Guide](docs/usage.md) for the full tape specification.
 
 ## Use Cases
@@ -65,5 +72,26 @@ Legacy `.tape` files use raw VHS syntax directly. See the [Usage Guide](docs/usa
 
 *Future: web interaction recording is planned alongside terminal capture.*
 
+## Testing Contract
+
+Run deterministic package coverage with:
+
+```bash
+ace-test ace-demo
+ace-test ace-demo all
+```
+
+Run deterministic feature coverage only when `test/feat/` exists:
+
+```bash
+ace-test ace-demo feat
+```
+
+Run retained workflow scenarios in E2E:
+
+```bash
+ace-test-e2e ace-demo
+```
+
 ---
 [Getting Started](docs/getting-started.md) | [Usage Guide](docs/usage.md) | [Handbook - Skills, Agents, Templates](docs/handbook.md) | Part of [ACE](https://github.com/cs3b/ace)

data/handbook/skills/as-demo-analyze-cast/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: as-demo-analyze-cast
+description: Analyze failed demo casts and route them to scenario, product, or verifier fixes
+# bundle: wfi://demo/analyze-cast
+# agent: general-purpose
+user-invocable: true
+allowed-tools:
+  - Bash(ace-demo:*)
+  - Bash(ace-bundle:*)
+  - Read
+argument-hint: "<cast-file> --tape <tape-ref-or-path> [--sandbox-path <path>]"
+last_modified: 2026-04-15
+source: ace-demo
+integration:
+  targets:
+    - claude
+    - codex
+    - gemini
+    - opencode
+    - pi
+skill:
+  kind: workflow
+  execution:
+    workflow: wfi://demo/analyze-cast
+---
+
+Load and run `ace-bundle wfi://demo/analyze-cast` in the current project, then follow the loaded workflow as the source of truth and execute it end-to-end instead of only summarizing it.

data/handbook/workflow-instructions/demo/analyze-cast.wf.md

@@ -0,0 +1,53 @@
+---
+doc-type: workflow
+title: Analyze Demo Cast Workflow
+purpose: cast verification triage workflow instruction
+ace-docs:
+  last-updated: 2026-04-15
+  last-checked: 2026-04-15
+---
+
+# Analyze Demo Cast Workflow
+
+## Purpose
+
+Analyze a recorded `.cast` after demo verification fails, decide whether the problem is the recording scenario, the product, or the verification tooling, and route to the correct next workflow before re-recording.
+
+## Instructions
+
+1. Run cast verification:
+
+   ```bash
+   ace-demo verify <cast-file> --tape <tape-ref-or-path>
+   ```
+
+   If the failed recording preserved a sandbox and the tape uses `assert_commands`, include it:
+
+   ```bash
+   ace-demo verify <cast-file> --tape <tape-ref-or-path> --sandbox-path <sandbox-path>
+   ```
+
+2. Read the generated report under `.ace-local/demo/` or the selected `--report-dir`.
+
+3. Route by classification:
+
+   - `scenario_defect`:
+     - fix the tape, camera/viewpoint, setup, or `verify:` contract
+     - keep the product code unchanged
+     - re-record after updating the demo scenario
+   - `product_bug`:
+     - treat the cast as a real product/runtime failure
+     - run the normal bug analysis/fix workflow for the affected package
+     - re-record only after the product fix lands
+   - `verification_error`:
+     - fix the verifier, cast parser, tape metadata, or recorder/tooling problem
+     - re-run verification
+     - re-record only if the original cast is unusable or no longer representative
+
+4. Do not upload or comment on a PR until `ace-demo verify` returns `pass`.
+
+## Success Criteria
+
+- Every failed demo recording is triaged through `ace-demo verify`
+- The next action is unambiguous: scenario fix, product bug fix, or verifier/tooling fix
+- Re-recording happens only after the correct upstream issue is fixed

data/handbook/workflow-instructions/demo/create.wf.md

@@ -29,7 +29,31 @@ Tapes are VHS script files that define terminal sessions: commands to type, timi
 
 ## Instructions
 
-1. **Preview the tape** before writing:
+1. **Define the demo contract before scripting anything**:
+
+   Capture these decisions in notes or the task/PR before you create a tape:
+
+   - **Viewpoint**: what exact terminal or tmux client is being recorded
+   - **Starting state**: what must already be visible on screen before the trigger action
+   - **Trigger action**: the concrete command or interaction that causes the behavior
+   - **Visible reaction**: the system state change that must be seen in the recording
+   - **End state**: what the reviewer should understand after the recording finishes
+
+   For demos about tmux, panes, windows, or session routing, the contract must explicitly say which tmux client view is being recorded. A shell transcript alone is not sufficient if the feature is about visible tmux behavior.
+
+2. **Keep setup off-camera unless setup is the feature**:
+
+   Pre-stage long or distracting setup before recording whenever possible:
+
+   - create fixtures, assignments, and helper scripts before the recording starts
+   - start from the state the viewer must recognize
+   - only leave setup on camera when the setup step itself is what the demo is proving
+
+   For tmux fork/window demos, prefer starting in the operator's normal work window and let the recording capture the visible transition into the fork window. Do not begin already attached to the fork window unless the feature is specifically about that attach flow.
+
+   If the demo is intended to be durable evidence for docs, review, or PR proof, prefer a committed `.tape.yml` / asciinema flow over ad-hoc inline/VHS capture so the resulting `.cast` can be re-verified later.
+
+3. **Preview the tape** before writing:
 
    ```bash
    ace-demo create <name> --dry-run -- "cmd1" "cmd2"
@@ -37,7 +61,7 @@ Tapes are VHS script files that define terminal sessions: commands to type, timi
 
    This prints the generated tape content without writing any file.
 
-2. **Create the tape**:
+4. **Create the tape**:
 
    ```bash
    ace-demo create <name> -- "cmd1" "cmd2"
@@ -48,13 +72,13 @@ Tapes are VHS script files that define terminal sessions: commands to type, timi
    ace-demo create <name> --desc "What this demo shows" --tags "feature,setup" -- "cmd1" "cmd2"
    ```
 
-3. **Update an existing tape** (overwrite):
+5. **Update an existing tape** (overwrite):
 
    ```bash
    ace-demo create <name> --force -- "cmd1" "cmd2"
    ```
 
-4. **Verify** the created tape:
+6. **Verify** the created tape:
 
    ```bash
    ace-demo show <name>
@@ -62,7 +86,7 @@ Tapes are VHS script files that define terminal sessions: commands to type, timi
 
    This displays metadata and full tape contents.
 
-5. **List all available tapes** to confirm visibility:
+7. **List all available tapes** to confirm visibility:
 
    ```bash
    ace-demo list
@@ -86,4 +110,6 @@ Tapes are VHS script files that define terminal sessions: commands to type, timi
 
 - Tape file created at `.ace/demo/tapes/<name>.tape`
 - `ace-demo show <name>` displays correct metadata and commands
-- `ace-demo list` shows the new tape
+- `ace-demo list` shows the new tape
+- The tape starts from the intended viewer-recognizable state instead of rebuilding irrelevant setup on camera
+- For state-transition demos, the tape visibly shows `before -> trigger -> visible effect -> after`

data/handbook/workflow-instructions/demo/record.wf.md

@@ -29,10 +29,27 @@ Record terminal demos using `ace-demo record`. Supports two modes: tape-based re
 
 ## Instructions
 
+### Validate the Recording Contract First
+
+Before choosing tape mode vs inline mode, lock these points:
+
+- **What is the user-visible behavior?**
+- **What screen or tmux client must the reviewer be looking at to see it?**
+- **What setup can happen off-camera so the recording starts at the meaningful baseline?**
+
+If the feature is about visible tmux behavior such as opening a pane, switching windows, or showing a running fork in the current session:
+
+- record the tmux client view that will actually show that transition
+- do not treat a shell transcript as sufficient proof
+- start from the operator's normal work window unless the feature is specifically about attach/reattach behavior
+- prefer showing the transition directly over showing commands that reconstruct the state later
+
 ### Record from Existing Tape
 
 The tape argument accepts a **preset name** (from `ace-demo list`) or a **direct file path** to a `.tape` or `.tape.yml` file.
 
+For demos that serve as durable evidence, prefer a committed `.tape.yml` so the generated `.cast` can be verified again with `ace-demo verify`.
+
 1. **Find available tapes**:
 
    ```bash
@@ -62,6 +79,15 @@ The tape argument accepts a **preset name** (from `ace-demo list`) or a **direct
    ace-demo record path/to/tape.tape.yml --output path/to/output.gif
    ```
 
+5. **Preflight the camera contract for state-transition demos**:
+
+   Ask these questions before recording:
+
+   - Does the first part of the recording show the baseline state the reviewer needs?
+   - Will the trigger action happen on camera?
+   - Will the visible system reaction happen on camera?
+   - If the feature is tmux-related, will the recording clearly show the tmux window/pane/session change rather than only a later shell prompt?
+
 ### Record Inline (Ad-Hoc Commands)
 
 1. **Preview** generated tape content:
@@ -139,8 +165,44 @@ TEST_PATH=ace-bundle ace-demo record test
 | `--font-size <n>` | Font size — inline mode (default: 16) |
 | `--playback-speed <speed>` | Postprocess speed: `1x`, `2x`, `4x`, `8x` |
 
+## Verification and Recovery
+
+For YAML/asciinema demos, recording is not complete when the GIF exists. The cast must pass semantic verification.
+
+Use tape `verify:` rules to express:
+- required exported variables (`require_vars`)
+- forbidden output/error signatures (`forbid_output`)
+- final-state assertions (`assert_commands`)
+
+After recording:
+
+1. If verification passes, continue normally.
+2. If verification fails with `scenario_defect`:
+   - inspect the generated report in `.ace-local/demo/`
+   - run `ace-demo verify <cast> --tape <tape>` again if needed
+   - fix the tape instructions, viewpoint, or setup contract
+   - retry recording once
+3. If verification fails with `product_bug`:
+   - stop
+   - keep the generated report in `.ace-local/demo/`
+   - run the cast-analysis workflow and treat it as a real code/runtime bug
+4. Never upload or comment on a PR when verification is not a true pass.
+5. For any non-pass result, branch through `wfi://demo/analyze-cast` before re-recording.
+
+### Additional Validation for UX / Tmux Demos
+
+Even when the recorder succeeds technically, reject the demo and re-record if any of these are true:
+
+- the recording starts after the important state change already happened
+- the recording shows only setup and end state, not the visible transition
+- a tmux/window/pane feature is represented only by status files or textual explanation
+- the viewer cannot identify the operator window, trigger action, and resulting fork/window/pane state from the recording alone
+
 ## Success Criteria
 
 - Recording file produced in `.ace-local/demo/` (plus optional retimed artifact)
-- If `--pr` used: demo uploaded to `demo-assets` release and comment posted on PR
-- If `--dry-run`: preview printed, no side effects
+- YAML/asciinema recordings pass semantic verification
+- If `--pr` used: demo uploaded to `demo-assets` release and comment posted on PR only after verification passes
+- If verification fails: error report written to `.ace-local/demo/`
+- If `--dry-run`: preview printed, no side effects
+- For UI/state-transition demos, the recording visibly shows `before -> trigger -> visible effect -> after` from the correct viewer perspective

data/lib/ace/demo/atoms/asciinema_tape_compiler.rb

@@ -27,6 +27,8 @@ module Ace
             lines << "# Scene: #{scene_name}" unless scene_name.to_s.strip.empty?
 
             scene.fetch("commands", []).each do |command|
+              next unless command["type"]
+
               lines << command.fetch("type")
               sleep_value = validate_sleep!(command["sleep"] || default_timeout)
               lines << "sleep #{sleep_value}"

data/lib/ace/demo/atoms/demo_yaml_parser.rb

@@ -6,7 +6,7 @@ module Ace
   module Demo
     module Atoms
       module DemoYamlParser
-        ALLOWED_ROOT_KEYS = %w[description tags settings setup scenes teardown].freeze
+        ALLOWED_ROOT_KEYS = %w[description tags settings setup scenes verify teardown].freeze
 
         module_function
 
@@ -35,6 +35,7 @@ module Ace
             "settings" => normalize_settings(data["settings"], source_path: source_path),
             "setup" => normalize_directives(data["setup"], "setup", source_path: source_path),
             "scenes" => normalize_scenes(data["scenes"], source_path: source_path),
+            "verify" => normalize_verify(data["verify"], source_path: source_path),
             "teardown" => normalize_directives(data["teardown"], "teardown", source_path: source_path)
           }
 
@@ -164,24 +165,142 @@ module Ace
         end
         private_class_method :normalize_scenes
 
+        def normalize_verify(verify, source_path:)
+          return {} if verify.nil?
+          raise DemoYamlParseError, "verify must be a map in #{source_path}" unless verify.is_a?(Hash)
+
+          normalized = {}
+          if verify.key?("allow_nonzero_exit")
+            normalized["allow_nonzero_exit"] = normalize_boolean(
+              verify["allow_nonzero_exit"],
+              "verify.allow_nonzero_exit",
+              source_path
+            )
+          end
+          normalized["require_vars"] = normalize_string_list(verify["require_vars"], "verify.require_vars", source_path) if verify.key?("require_vars")
+          normalized["require_output"] = normalize_string_list(verify["require_output"], "verify.require_output", source_path) if verify.key?("require_output")
+          if verify.key?("require_output_sequence")
+            normalized["require_output_sequence"] = normalize_string_list(
+              verify["require_output_sequence"],
+              "verify.require_output_sequence",
+              source_path
+            )
+          end
+          normalized["forbid_output"] = normalize_string_list(verify["forbid_output"], "verify.forbid_output", source_path) if verify.key?("forbid_output")
+          normalized["assert_commands"] = normalize_string_list(verify["assert_commands"], "verify.assert_commands", source_path) if verify.key?("assert_commands")
+          normalized
+        end
+        private_class_method :normalize_verify
+
+        def normalize_boolean(value, field, source_path)
+          return value if value == true || value == false
+
+          raise DemoYamlParseError, "#{field} must be a boolean in #{source_path}"
+        end
+        private_class_method :normalize_boolean
+
+        def normalize_string_list(value, field, source_path)
+          raise DemoYamlParseError, "#{field} must be an array in #{source_path}" unless value.is_a?(Array)
+
+          value.map.with_index do |item, index|
+            text = item&.to_s
+            if text.nil? || text.strip.empty?
+              raise DemoYamlParseError, "#{field}[#{index}] must be a non-empty string in #{source_path}"
+            end
+
+            text
+          end
+        end
+        private_class_method :normalize_string_list
+
         def normalize_command(command, scene_index, command_index, source_path:)
           unless command.is_a?(Hash)
             raise DemoYamlParseError,
               "scenes[#{scene_index}].commands[#{command_index}] must be a map in #{source_path}"
           end
 
-          type = command["type"]&.to_s
-          if type.nil? || type.strip.empty?
+          normalized = {"sleep" => command["sleep"]&.to_s}.compact
+          has_type = !command["type"].to_s.strip.empty?
+          has_tmux = command["tmux"].is_a?(Hash)
+
+          if has_type && has_tmux
             raise DemoYamlParseError,
-              "scenes[#{scene_index}].commands[#{command_index}].type is required in #{source_path}"
+              "scenes[#{scene_index}].commands[#{command_index}] cannot define both type and tmux in #{source_path}"
           end
 
-          {
-            "type" => type,
-            "sleep" => command["sleep"]&.to_s
-          }
+          if has_type
+            normalized["type"] = command["type"].to_s
+            return normalized
+          end
+
+          if has_tmux
+            normalized["tmux"] = normalize_tmux_command(
+              command["tmux"],
+              scene_index,
+              command_index,
+              source_path: source_path
+            )
+            return normalized
+          end
+
+          raise DemoYamlParseError,
+            "scenes[#{scene_index}].commands[#{command_index}] must define either type or tmux in #{source_path}"
         end
         private_class_method :normalize_command
+
+        def normalize_tmux_command(tmux, scene_index, command_index, source_path:)
+          directive = tmux.transform_keys(&:to_s)
+          action = directive["action"]&.to_s&.strip
+          if action.nil? || action.empty?
+            raise DemoYamlParseError,
+              "scenes[#{scene_index}].commands[#{command_index}].tmux.action is required in #{source_path}"
+          end
+
+          allowed = %w[attach detach wait send]
+          unless allowed.include?(action)
+            raise DemoYamlParseError,
+              "Unknown tmux action '#{action}' in #{source_path}. Allowed: #{allowed.join(', ')}"
+          end
+
+          normalized = {"action" => action}
+          %w[session window pane pattern].each do |field|
+            normalized[field] = directive[field].to_s if directive.key?(field)
+          end
+
+          case action
+          when "attach", "detach"
+            normalized["session"] = required_string!(directive, "session", scene_index, command_index, source_path)
+          when "wait"
+            normalized["for"] = required_string!(directive, "for", scene_index, command_index, source_path)
+            normalized["pattern"] = normalized["pattern"] if normalized["pattern"]
+            normalized["timeout"] = Float(directive["timeout"]) if directive.key?("timeout")
+          when "send"
+            command_text = directive["command"]&.to_s&.strip
+            key_text = directive["key"]&.to_s&.strip
+            if command_text.to_s.empty? == key_text.to_s.empty?
+              raise DemoYamlParseError,
+                "tmux send must define exactly one of command or key in #{source_path}"
+            end
+            normalized["command"] = command_text unless command_text.to_s.empty?
+            normalized["key"] = key_text unless key_text.to_s.empty?
+          end
+
+          normalized
+        rescue ArgumentError, TypeError => e
+          raise DemoYamlParseError, "#{e.message} (#{source_path})"
+        end
+        private_class_method :normalize_tmux_command
+
+        def required_string!(directive, field, scene_index, command_index, source_path)
+          value = directive[field]&.to_s&.strip
+          if value.nil? || value.empty?
+            raise DemoYamlParseError,
+              "scenes[#{scene_index}].commands[#{command_index}].tmux.#{field} is required in #{source_path}"
+          end
+
+          value
+        end
+        private_class_method :required_string!
       end
     end
   end

data/lib/ace/demo/atoms/record_option_validator.rb

@@ -34,11 +34,25 @@ module Ace
           raise ArgumentError, "Format 'webm' requires --backend vhs when recording YAML tapes"
         end
 
+        def validate_yaml_backend_capabilities!(backend:, spec:)
+          return unless backend == "vhs"
+          return unless yaml_uses_tmux_directives?(spec)
+
+          raise ArgumentError, "Backend 'vhs' does not support tmux directives in YAML tapes; use backend 'asciinema' or remove tmux commands"
+        end
+
         def validate_raw_tape_backend!(backend:)
           return if backend.nil? || backend == "vhs"
 
           raise ArgumentError, "Raw .tape recordings support backend 'vhs' only"
         end
+
+        def yaml_uses_tmux_directives?(spec)
+          Array(spec["scenes"]).any? do |scene|
+            Array(scene["commands"]).any? { |command| command.is_a?(Hash) && command["tmux"].is_a?(Hash) }
+          end
+        end
+        private_class_method :yaml_uses_tmux_directives?
       end
     end
   end

data/lib/ace/demo/atoms/vhs_tape_compiler.rb

@@ -26,6 +26,8 @@ module Ace
             lines << "# Scene: #{scene_name}" unless scene_name.to_s.strip.empty?
 
             scene.fetch("commands", []).each do |command|
+              next unless command["type"]
+
               type_text = command.fetch("type")
               if type_text.include?('"') || type_text.include?("$") || type_text.include?("\\")
                 lines << "Type `#{type_text}`"

data/lib/ace/demo/atoms/yaml_record_planner.rb

@@ -28,6 +28,7 @@ module Ace
             allow_nil: false
           )
           RecordOptionValidator.validate_yaml_backend_format!(backend: selected_backend, format: selected_format)
+          RecordOptionValidator.validate_yaml_backend_capabilities!(backend: selected_backend, spec: spec)
 
           selected_speed = playback_speed.nil? ? settings["playback_speed"] : playback_speed
           selected_speed = Atoms::PlaybackSpeedParser.parse(selected_speed)