From 1f3c8f1e187c25ffa749116c40c824d7af3c325d Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Thu, 17 Sep 2026 10:46:27 -0500
Subject: [PATCH 01/77] fix(tasks): #185 #187 - stop advertising device on
 non-consuming tasks; add gain_audio

#185: describe_task() lists device on every task's schema since it is a
universal, always-safe-to-pass argument, but a non-model command forwarded
its arguments straight to an implementation whose signature never took one,
so passing device raised a TypeError (e.g. resample_audio). register_command
now takes consumes_device (default False); a non-consuming handler pops
device from arguments before dispatch, while the 8 model-backed handlers
that call task.device_for(arguments) themselves are marked
consumes_device=True and left unwrapped. The pop only fires when arguments
is a dict, since a command like gather_inputs receives a plain list.

#187: adds gain_audio (dw/tasks/audio_utils.py), registered in task.py and
declared in task_domains.py, to apply a gain to a time- or frame-aligned
region of a track in one step instead of the five-step
slice_audio -> gain -> mix_audio -> rejoin -> pair_audio chain. Reuses
slice_audio's dual seconds/frames addressing and carries the same
sample_rate reinterpretation caveat (#180). Unlike slice_audio, a region
reaching past the end of the track is clipped rather than zero-padded, since
there is no real material there to gain. Documented in docs/TASKS.md.

Full suite: 4945 passed, 16 skipped.

Model sonnet via provider anthropic.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 docs/TASKS.md           |  41 +++++++++++++++-
 dw/task_domains.py      |   8 ++++
 dw/tasks/audio_utils.py | 104 ++++++++++++++++++++++++++++++++++++++++
 dw/tasks/task.py        |  59 +++++++++++++++++++----
 4 files changed, 203 insertions(+), 9 deletions(-)

diff --git a/docs/TASKS.md b/docs/TASKS.md
index cc3c3e0b..64b63f04 100644
--- a/docs/TASKS.md
+++ b/docs/TASKS.md
@@ -15,7 +15,9 @@ Tasks are utility operations that run outside of pipeline inference. Use them fo
 
 Any task that runs a model accepts a `"device"` argument to pin where it runs -
 useful for keeping a helper model (a captioner, an upscaler) off the accelerator a
-loaded pipeline is using, or on a second one.
+loaded pipeline is using, or on a second one. `"device"` is listed on every task's
+schema, since it is always safe to pass: a task that runs no model - `slice_audio`,
+`compose_text`, and the like - just ignores it.
 
 Task argument schemas are discoverable: `GET /api/tasks/{command}` on the
 [server](SERVER.md) returns each command's arguments read from its registered
@@ -482,6 +484,43 @@ a length still passes the whole track along:
 | `start_frame` / `num_frames` / `fps` | One pair | The slice in video frames; `fps` is required, start and count may be omitted |
 | `sample_rate` | With a waveform | Sample rate of a directly passed waveform (files carry their own) |
 
+### gain_audio
+
+Apply a gain, in decibels, to a region of an audio track - the rest of the
+track passes through unchanged. The region is addressed the same way
+`slice_audio`'s is, in seconds or in video frames, so ducking a scene under
+another (lowering a dialogue track between two timestamps) is one step
+instead of the `slice_audio` → `gain` (a whole-track `normalize_audio` on the
+slice) → `mix_audio` → `rejoin` → `pair_audio` chain that used to be the only
+way to gain part of a track rather than all of it. Unlike `slice_audio`, a
+region reaching past the end of the track is clipped to it rather than
+zero-padded - there is no silence there to gain, only the end of the real
+material:
+
+```json
+{
+    "task": {
+        "command": "gain_audio",
+        "arguments": {
+            "audio": "./dialogue.wav",
+            "gain_db": -12,
+            "start_frame": 124,
+            "num_frames": 48,
+            "fps": 24
+        }
+    },
+    "result": { "content_type": "audio/wav", "sample_rate": 44100 }
+}
+```
+
+| Argument | Required | Description |
+| -------- | -------- | ----------- |
+| `audio` | Yes | Path or URL of an audio file (or of a video file, whose soundtrack is taken), a waveform from a previous step, or an earlier step's video generated with a soundtrack (which brings its sample rate along) |
+| `gain_db` | Yes | Gain to apply within the region, in decibels - negative ducks it, positive boosts it |
+| `start_seconds` / `duration_seconds` | One pair | The region in seconds; either may be omitted |
+| `start_frame` / `num_frames` / `fps` | One pair | The region in video frames; `fps` is required, start and count may be omitted |
+| `sample_rate` | With a waveform | Sample rate of a directly passed waveform (files carry their own) |
+
 ### crossfade_audio
 
 Join audio tracks with an equal-power crossfade. Each seam overlaps the two
diff --git a/dw/task_domains.py b/dw/task_domains.py
index c1cb7ef3..9bbd36e9 100644
--- a/dw/task_domains.py
+++ b/dw/task_domains.py
@@ -56,6 +56,14 @@
         "fps": POSITIVE,
         "sample_rate": POSITIVE,
     },
+    "gain_audio": {
+        "start_seconds": NON_NEGATIVE,
+        "duration_seconds": POSITIVE,
+        "start_frame": NON_NEGATIVE,
+        "num_frames": POSITIVE,
+        "fps": POSITIVE,
+        "sample_rate": POSITIVE,
+    },
     "resample_audio": {
         "target_sample_rate": POSITIVE,
         "sample_rate": POSITIVE,
diff --git a/dw/tasks/audio_utils.py b/dw/tasks/audio_utils.py
index e246a4d2..d15c8d41 100644
--- a/dw/tasks/audio_utils.py
+++ b/dw/tasks/audio_utils.py
@@ -376,6 +376,110 @@ def slice_audio(
     return _as_track(slice_samples(waveform, start, length), sample_rate, "slice_audio")
 
 
+def gain_audio(
+    audio,
+    gain_db,
+    start_seconds=None,
+    duration_seconds=None,
+    start_frame=None,
+    num_frames=None,
+    fps=None,
+    sample_rate=None,
+):
+    """Task command: apply a gain to a region of an audio track.
+
+    The region is addressed the same way slice_audio's is - either in
+    seconds (start_seconds + duration_seconds) or in video frames
+    (start_frame + num_frames + fps). Everything outside the region is
+    passed through unchanged, so ducking a scene under another is one step
+    rather than the slice/gain/mix/rejoin/pair_audio chain that was
+    previously the only way to apply a gain to part of a track rather than
+    all of it (#187).
+
+    Unlike slice_audio, a region reaching past the end of the track is
+    clipped to it rather than zero-padded: there is no silence there to
+    gain, only the end of the real material.
+
+    A file's or video's own sample rate is read automatically; sample_rate
+    is for a waveform passed directly, or to override what a file carries -
+    which relabels the waveform at that rate rather than resampling it, the
+    same caveat slice_audio's sample_rate carries (#180).
+
+    Args:
+        audio: Path or URL of an audio file (or of a video file, whose
+            soundtrack is taken), a generated video carrying its own
+            soundtrack, or a waveform (which needs sample_rate alongside it)
+        gain_db: Gain to apply within the region, in decibels - negative
+            ducks it, positive boosts it
+        start_seconds: Start of the region, in seconds
+        duration_seconds: Length of the region, in seconds
+        start_frame: Start of the region, in video frames
+        num_frames: Length of the region, in video frames
+        fps: Frame rate used to convert start_frame/num_frames to samples
+        sample_rate: Sample rate of a waveform passed directly; given for a
+            file or a video it overrides the rate they carry
+
+    Returns:
+        An AudioTrack holding the whole track with the region's gain
+        applied, and the rate it is at
+    """
+    start_seconds = _as_number(start_seconds, float, "start_seconds", command="gain_audio")
+    duration_seconds = _as_number(
+        duration_seconds, float, "duration_seconds", command="gain_audio"
+    )
+    start_frame = _as_number(start_frame, int, "start_frame", command="gain_audio")
+    num_frames = _as_number(num_frames, int, "num_frames", command="gain_audio")
+    fps = _as_number(fps, Fraction, "fps", command="gain_audio")
+    gain_db = _as_number(gain_db, float, "gain_db", command="gain_audio")
+
+    check_arguments(
+        "gain_audio",
+        start_seconds=start_seconds,
+        duration_seconds=duration_seconds,
+        start_frame=start_frame,
+        num_frames=num_frames,
+        fps=fps,
+        sample_rate=sample_rate,
+    )
+
+    waveform, sample_rate = _waveform_and_rate(audio, sample_rate, "gain_audio")
+    total = waveform.shape[1]
+
+    if start_seconds is not None or duration_seconds is not None:
+        start = int(round((start_seconds or 0) * sample_rate))
+        length = (
+            max(total - start, 0)
+            if duration_seconds is None
+            else int(round(duration_seconds * sample_rate))
+        )
+    elif start_frame is not None or num_frames is not None:
+        if fps is None:
+            raise ValueError("gain_audio needs 'fps' to address a region in frames")
+        start = frames_to_samples(start_frame or 0, fps, sample_rate)
+        length = (
+            max(total - start, 0)
+            if num_frames is None
+            else frames_to_samples(num_frames, fps, sample_rate)
+        )
+    else:
+        raise ValueError(
+            "gain_audio needs either 'start_seconds'/'duration_seconds' or "
+            "'start_frame'/'num_frames'/'fps' to address the region to gain"
+        )
+
+    region_start = max(0, min(start, total))
+    region_end = max(region_start, min(start + max(length, 0), total))
+
+    gained = waveform.copy()
+    if region_end > region_start:
+        gain = 10 ** (gain_db / 20)
+        gained[:, region_start:region_end] = (
+            gained[:, region_start:region_end] * gain
+        ).astype(waveform.dtype)
+
+    return _as_track(gained, sample_rate, "gain_audio")
+
+
 def _warn_on_slice_past_end(total, start, length, sample_rate):
     """Say when a slice asked for more material than its source holds.
 
diff --git a/dw/tasks/task.py b/dw/tasks/task.py
index 0bf218de..f06f092f 100644
--- a/dw/tasks/task.py
+++ b/dw/tasks/task.py
@@ -32,7 +32,9 @@
 _COMMAND_INFO: Dict[str, dict] = {}
 
 
-def register_command(command_name: str, implementation=None, provided=()):
+def register_command(
+    command_name: str, implementation=None, provided=(), consumes_device=False
+):
     """
     Decorator to register a command handler function.
 
@@ -42,13 +44,31 @@ def register_command(command_name: str, implementation=None, provided=()):
             the command's arguments (None for a command that consumes a
             free-form dict)
         provided: Parameter names the dispatch supplies itself
+        consumes_device: True for a handler that calls task.device_for(arguments)
+            itself, to pick the accelerator a model-backed task runs on. False
+            (the default) is for a task that runs no model and forwards
+            arguments straight to its implementation - device is introspected
+            as a universal, always-safe-to-pass argument (dw/introspection.py),
+            so a non-consuming handler must drop it itself rather than let it
+            reach the implementation as an unexpected keyword argument (#185).
+            Some commands (e.g. gather_inputs) receive a non-dict argument
+            value, which never carries a device to drop
 
     Returns:
         Decorator function
     """
 
     def decorator(func: Callable) -> Callable:
-        _COMMAND_REGISTRY[command_name] = func
+        if consumes_device:
+            handler = func
+        else:
+
+            def handler(task, arguments, previous_pipelines, _func=func):
+                if isinstance(arguments, dict):
+                    arguments.pop("device", None)
+                return _func(task, arguments, previous_pipelines)
+
+        _COMMAND_REGISTRY[command_name] = handler
         _COMMAND_INFO[command_name] = {
             "kind": "command",
             "implementation": implementation,
@@ -158,6 +178,15 @@ def _handle_slice_audio(task, arguments, previous_pipelines):
     return slice_audio(**arguments)
 
 
+@register_command("gain_audio", implementation="dw.tasks.audio_utils.gain_audio")
+def _handle_gain_audio(task, arguments, previous_pipelines):
+    """Apply a gain to a time- or frame-aligned region of an audio track"""
+    logger.debug("Gaining audio region")
+    from .audio_utils import gain_audio
+
+    return gain_audio(**arguments)
+
+
 @register_command(
     "resample_audio", implementation="dw.tasks.audio_utils.resample_audio"
 )
@@ -282,7 +311,9 @@ def _per_frame(image, process):
     return AudioVideo(frames, audio, sample_rate, fps=getattr(image, "fps", None))
 
 
-@register_command("upscale", implementation="dw.tasks.upscale.upscale_image")
+@register_command(
+    "upscale", implementation="dw.tasks.upscale.upscale_image", consumes_device=True
+)
 def _handle_upscale(task, arguments, previous_pipelines):
     """Upscale an image using a spandrel-compatible super-resolution model"""
     logger.debug("Upscaling image")
@@ -298,7 +329,9 @@ def _handle_upscale(task, arguments, previous_pipelines):
 
 
 @register_command(
-    "diffusion_upscale", implementation="dw.tasks.diffusion_upscale.diffusion_upscale"
+    "diffusion_upscale",
+    implementation="dw.tasks.diffusion_upscale.diffusion_upscale",
+    consumes_device=True,
 )
 def _handle_diffusion_upscale(task, arguments, previous_pipelines):
     """Upscale an image using a diffusion-based upscale pipeline"""
@@ -313,7 +346,9 @@ def _handle_diffusion_upscale(task, arguments, previous_pipelines):
 
 
 @register_command(
-    "restore_faces", implementation="dw.tasks.restore_faces.restore_faces"
+    "restore_faces",
+    implementation="dw.tasks.restore_faces.restore_faces",
+    consumes_device=True,
 )
 def _handle_restore_faces(task, arguments, previous_pipelines):
     """Restore faces in an image using a spandrel-compatible face restoration model"""
@@ -329,7 +364,9 @@ def _handle_restore_faces(task, arguments, previous_pipelines):
     )
 
 
-@register_command("segment", implementation="dw.tasks.segment.segment_image")
+@register_command(
+    "segment", implementation="dw.tasks.segment.segment_image", consumes_device=True
+)
 def _handle_segment(task, arguments, previous_pipelines):
     """Segment objects in an image using text prompt"""
     logger.debug("Segmenting image")
@@ -346,6 +383,7 @@ def _handle_segment(task, arguments, previous_pipelines):
 @register_command(
     "interpolate_frames",
     implementation="dw.tasks.interpolate_frames.interpolate_frames",
+    consumes_device=True,
 )
 def _handle_interpolate_frames(task, arguments, previous_pipelines):
     """Interpolate video frames to increase frame rate"""
@@ -357,7 +395,9 @@ def _handle_interpolate_frames(task, arguments, previous_pipelines):
 
 
 @register_command(
-    "image_to_text", implementation="dw.tasks.image_to_text.image_to_text"
+    "image_to_text",
+    implementation="dw.tasks.image_to_text.image_to_text",
+    consumes_device=True,
 )
 def _handle_image_to_text(task, arguments, previous_pipelines):
     """Generate text caption from an image"""
@@ -369,7 +409,9 @@ def _handle_image_to_text(task, arguments, previous_pipelines):
 
 
 @register_command(
-    "text_generation", implementation="dw.tasks.text_generation.generate_text"
+    "text_generation",
+    implementation="dw.tasks.text_generation.generate_text",
+    consumes_device=True,
 )
 def _handle_text_generation(task, arguments, previous_pipelines):
     """Generate text from a prompt using a local LLM"""
@@ -383,6 +425,7 @@ def _handle_text_generation(task, arguments, previous_pipelines):
 @register_command(
     "generate_speech",
     implementation="dw.tasks.speech_generation.generate_speech",
+    consumes_device=True,
 )
 def _handle_speech_generation(task, arguments, previous_pipelines):
     """Speak a line of text with a local text-to-speech model"""

From 993fe44f8e50db12ccb1f43bf349fcad8bc1ce42 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Thu, 17 Sep 2026 10:59:56 -0500
Subject: [PATCH 02/77] fix(plan): #186 - surface gate status in
 downloads_required pre-flight

Each downloads_required entry now carries gated (the hub's own field:
false/"auto"/"manual", or null when the lookup itself failed) and
access_blocked (true when this box's Hugging Face token specifically
lacks access, from GatedRepoError - what would otherwise be a 403
partway into a run). validate_workflow's warnings gains one line per
blocked entry, pointing at the repo's license page.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 docs/SERVER.md       | 15 ++++++++--
 dw/plan.py           | 51 ++++++++++++++++++++++++++------
 dw/server/app.py     |  4 ++-
 tests/test_plan.py   | 70 ++++++++++++++++++++++++++++++++++++++++----
 tests/test_server.py | 32 +++++++++++++++++++-
 5 files changed, 153 insertions(+), 19 deletions(-)

diff --git a/docs/SERVER.md b/docs/SERVER.md
index 099d4187..69e8810c 100644
--- a/docs/SERVER.md
+++ b/docs/SERVER.md
@@ -303,9 +303,18 @@ The editor's forms come from these; they are just as usable from scripts:
   also gets a warning saying so, since `0` alone does not distinguish a
   disabled cache from an empty one);
   `downloads_required`, each `model_name` the hub cache does not hold as
-  `{repo, gb}` (`gb` from the hub, `null` when it could not be asked -
-  `?sizes=false` skips the hub) and each `from_single_file` URL as
-  `{repo: null, url, gb: null}`; and `estimate`, `{minutes, basis,
+  `{repo, gb, gated, access_blocked}` (`gb` from the hub, `null` when it
+  could not be asked - `?sizes=false` skips the hub, and then `gated` and
+  `access_blocked` are `null` too); `gated` is the hub's own field for the
+  repo (`false`, `"auto"` or `"manual"`) or `null` when the lookup itself
+  failed for a reason other than the gate; `access_blocked` is `true`
+  when this box's Hugging Face token specifically has not been granted
+  access to a gated repo (`GatedRepoError` from the hub, the pre-flight
+  signal for what would otherwise be a 403 partway into a run, #186) -
+  `validate_workflow`'s `warnings` carries one line per such entry. Each
+  `from_single_file` URL is `{repo: null, url, gb: null, gated: null,
+  access_blocked: null}`, since a direct file URL is never gated; and
+  `estimate`, `{minutes, basis,
   device, measured_on, partial, runs}` from this box's own history when it
   has one and otherwise from the workflow's `cost` block -
   `basis` is `observed` (the cold median of this server's own finished runs
diff --git a/dw/plan.py b/dw/plan.py
index ae7b5473..3a8d1a6e 100644
--- a/dw/plan.py
+++ b/dw/plan.py
@@ -19,7 +19,7 @@
 import os
 
 from huggingface_hub import model_info
-from huggingface_hub.utils import HFValidationError, validate_repo_id
+from huggingface_hub.utils import GatedRepoError, HFValidationError, validate_repo_id
 
 from .elision import elide_definition
 from .hub_cache import scan_models
@@ -459,9 +459,14 @@ def downloads_required(expanded, base_dir, workflow_dir, cache_dir, lookup_sizes
         # body, and a free pre-flight must not be a directory-existence oracle
         if name in present or not _is_repo_id(name):
             continue
-        required.append({"repo": name, "gb": _size_gb(name) if lookup_sizes else None})
+        entry = {"repo": name, "gb": None, "gated": None, "access_blocked": None}
+        if lookup_sizes:
+            entry["gb"], entry["gated"], entry["access_blocked"] = _model_info(name)
+        required.append(entry)
     for url in urls:
-        required.append({"repo": None, "url": url, "gb": None})
+        required.append(
+            {"repo": None, "url": url, "gb": None, "gated": None, "access_blocked": None}
+        )
     return required
 
 
@@ -495,6 +500,20 @@ def _collect_sources(tree, names, urls):
             _collect_sources(value, names, urls)
 
 
+def gate_warnings(downloads_required):
+    """One line per required download this box's token is blocked from -
+    the pre-flight signal #186 asked for, so a gated repo is a
+    `validate_workflow`-visible condition rather than a 403 the run only
+    discovers after it has loaded everything ahead of that step."""
+    return [
+        f"{entry['repo']} is gated and not accessible with this box's "
+        "Hugging Face token - accept its license at "
+        f"https://huggingface.co/{entry['repo']} before running this workflow"
+        for entry in downloads_required
+        if entry.get("access_blocked")
+    ]
+
+
 def _is_repo_id(name):
     try:
         validate_repo_id(name)
@@ -513,13 +532,27 @@ def _is_url(value):
         return False
 
 
-def _size_gb(name):
-    """A repo's size in GiB to one decimal, or None when the hub does not
-    say - unreachable, gated without a token, or a file with no size."""
+def _model_info(name):
+    """A repo's size in GiB, gate status, and whether this box's token is
+    blocked from it - a `(gb, gated, access_blocked)` triple.
+
+    `gated` is `model_info`'s own field (`False` / `"auto"` / `"manual"`),
+    readable only when the call succeeds - which it does even for a gated
+    repo this token has been granted. A `GatedRepoError` is the call failing
+    for exactly that reason: the repo is gated and this box's token has not
+    (or no longer) been granted access, distinct from every other lookup
+    failure (unreachable, a file with no size), which says nothing about the
+    gate either way (#186).
+    """
     try:
         info = model_info(name, files_metadata=True, timeout=SIZE_LOOKUP_TIMEOUT)
-        total = sum(s.size for s in (info.siblings or []) if getattr(s, "size", None))
+    except GatedRepoError as e:
+        logger.debug(f"Gate not accepted for {name}: {e}")
+        return None, True, True
     except Exception as e:
         logger.debug(f"No size for {name}: {e}")
-        return None
-    return round(total / GIB, 1) if total else None
+        return None, None, None
+    total = sum(s.size for s in (info.siblings or []) if getattr(s, "size", None))
+    gb = round(total / GIB, 1) if total else None
+    gated = getattr(info, "gated", False) or False
+    return gb, gated, False
diff --git a/dw/server/app.py b/dw/server/app.py
index 31f2406c..843d745d 100644
--- a/dw/server/app.py
+++ b/dw/server/app.py
@@ -73,7 +73,7 @@
 from ..result import read_embedded_metadata
 from ..media_info import probe_media
 from ..hub_cache import scan_models, delete_model, DownloadManager
-from ..plan import build_plan, unseeded_cache_warnings
+from ..plan import build_plan, gate_warnings, unseeded_cache_warnings
 from ..runs import (
     MANIFEST_FILE_NAME,
     REALIZED_FILE_NAME,
@@ -1748,6 +1748,8 @@ def validate_workflow(
         except Exception:
             logger.exception("Plan could not be built")
             answer["plan"] = None
+        if answer["plan"]:
+            answer["warnings"] += gate_warnings(answer["plan"]["downloads_required"])
         return answer
 
     # ------------------------------------------------------------ workspaces
diff --git a/tests/test_plan.py b/tests/test_plan.py
index cd9f929e..39078e26 100644
--- a/tests/test_plan.py
+++ b/tests/test_plan.py
@@ -6,7 +6,7 @@
 
 import pytest
 
-from dw.plan import build_plan, unseeded_cache_warnings
+from dw.plan import build_plan, gate_warnings, unseeded_cache_warnings
 from dw.runs import new_run_id
 from dw.workflow import workflow_from_definition
 
@@ -490,7 +490,9 @@ def test_a_child_measured_on_another_device_is_still_added(self, plan, tmp_path)
 
 class TestDownloadsRequired:
     def test_a_repo_not_in_the_cache_is_required(self, plan):
-        assert plan()["downloads_required"] == [{"repo": "org/still-model", "gb": None}]
+        assert plan()["downloads_required"] == [
+            {"repo": "org/still-model", "gb": None, "gated": None, "access_blocked": None}
+        ]
 
     def test_a_cached_repo_is_not(self, plan, monkeypatch):
         import dw.plan
@@ -544,7 +546,13 @@ def test_a_single_file_url_is_listed_without_a_size(self, plan):
             "from_single_file": "https://example.test/x.safetensors"
         }
         assert plan(spec)["downloads_required"] == [
-            {"repo": None, "url": "https://example.test/x.safetensors", "gb": None}
+            {
+                "repo": None,
+                "url": "https://example.test/x.safetensors",
+                "gb": None,
+                "gated": None,
+                "access_blocked": None,
+            }
         ]
 
     def test_a_single_file_local_path_is_not_listed(self, plan):
@@ -590,6 +598,7 @@ def __init__(self, size):
 
         class Info:
             siblings = [Sibling(2 * 1024**3), Sibling(None), Sibling(512 * 1024**2)]
+            gated = False
 
         calls = []
 
@@ -599,11 +608,40 @@ def fake_model_info(name, **kwargs):
 
         monkeypatch.setattr(dw.plan, "model_info", fake_model_info)
         answer = plan(lookup_sizes=True)["downloads_required"]
-        assert answer == [{"repo": "org/still-model", "gb": 2.5}]
+        assert answer == [
+            {"repo": "org/still-model", "gb": 2.5, "gated": False, "access_blocked": False}
+        ]
         assert calls[0][0] == "org/still-model"
         assert calls[0][1]["files_metadata"] is True
         assert calls[0][1]["timeout"] == 5.0
 
+    def test_a_gated_repo_this_token_may_access_is_not_blocked(self, plan, monkeypatch):
+        import dw.plan
+
+        class Info:
+            siblings = []
+            gated = "manual"
+
+        monkeypatch.setattr(dw.plan, "model_info", lambda name, **k: Info())
+        assert plan(lookup_sizes=True)["downloads_required"] == [
+            {"repo": "org/still-model", "gb": None, "gated": "manual", "access_blocked": False}
+        ]
+
+    def test_a_gated_repo_this_token_lacks_access_to_is_blocked(self, plan, monkeypatch):
+        import httpx
+        import dw.plan
+        from huggingface_hub.utils import GatedRepoError
+
+        response = httpx.Response(403, request=httpx.Request("GET", "https://hf.co/x"))
+
+        def boom(*a, **k):
+            raise GatedRepoError("no access", response=response)
+
+        monkeypatch.setattr(dw.plan, "model_info", boom)
+        assert plan(lookup_sizes=True)["downloads_required"] == [
+            {"repo": "org/still-model", "gb": None, "gated": True, "access_blocked": True}
+        ]
+
     def test_a_hub_failure_is_a_null_size(self, plan, monkeypatch):
         import dw.plan
 
@@ -612,7 +650,7 @@ def boom(*a, **k):
 
         monkeypatch.setattr(dw.plan, "model_info", boom)
         assert plan(lookup_sizes=True)["downloads_required"] == [
-            {"repo": "org/still-model", "gb": None}
+            {"repo": "org/still-model", "gb": None, "gated": None, "access_blocked": None}
         ]
 
     def test_lookup_sizes_false_never_calls_the_hub(self, plan, monkeypatch):
@@ -625,6 +663,28 @@ def boom(*a, **k):
         plan(lookup_sizes=False)
 
 
+class TestGateWarnings:
+    def test_a_blocked_repo_gets_a_warning(self):
+        required = [
+            {"repo": "org/free-model", "gb": 1.0, "gated": False, "access_blocked": False},
+            {"repo": "org/gated-model", "gb": None, "gated": True, "access_blocked": True},
+        ]
+        warnings = gate_warnings(required)
+        assert len(warnings) == 1
+        assert "org/gated-model" in warnings[0]
+        assert "huggingface.co/org/gated-model" in warnings[0]
+
+    def test_an_accepted_gate_gets_no_warning(self):
+        required = [
+            {"repo": "org/manual-gate", "gb": 1.0, "gated": "manual", "access_blocked": False}
+        ]
+        assert gate_warnings(required) == []
+
+    def test_unknown_gate_status_gets_no_warning(self):
+        required = [{"repo": "org/offline", "gb": None, "gated": None, "access_blocked": None}]
+        assert gate_warnings(required) == []
+
+
 class TestCachedSteps:
     def test_no_probe_is_unknown(self, plan):
         assert plan()["cached_steps"] is None
diff --git a/tests/test_server.py b/tests/test_server.py
index 516cde17..0908a66e 100644
--- a/tests/test_server.py
+++ b/tests/test_server.py
@@ -3817,7 +3817,37 @@ def test_a_valid_answer_carries_a_plan(self, server, monkeypatch):
         assert plan["steps"] == 1
         assert plan["estimate"]["basis"] in {"catalog", "other_device"}
         assert plan["estimate"]["minutes"] == 2.0
-        assert plan["downloads_required"] == [{"repo": "m", "gb": None}]
+        assert plan["downloads_required"] == [
+            {"repo": "m", "gb": None, "gated": None, "access_blocked": None}
+        ]
+
+    def test_a_blocked_gate_surfaces_as_a_warning(self, server, monkeypatch):
+        """#186: a repo this box's token cannot access is a 403 partway into
+        a run unless the pre-flight says so first."""
+        import httpx
+        import dw.plan
+        from huggingface_hub.utils import GatedRepoError
+
+        monkeypatch.setattr(
+            dw.plan, "scan_models", lambda cache_dir=None: {"repos": []}
+        )
+
+        response = httpx.Response(403, request=httpx.Request("GET", "https://hf.co/x"))
+
+        def boom(*a, **k):
+            raise GatedRepoError("no access", response=response)
+
+        monkeypatch.setattr(dw.plan, "model_info", boom)
+        with server(success_script) as client:
+            result = client.post(
+                "/api/validate",
+                json={"workflow": video_workflow("gated", with_cost=True)},
+            ).json()
+        assert result["plan"]["downloads_required"] == [
+            {"repo": "m", "gb": None, "gated": True, "access_blocked": True}
+        ]
+        gate_warnings = [w for w in result["warnings"] if "huggingface.co/m" in w]
+        assert len(gate_warnings) == 1
 
     def test_the_estimate_quotes_this_box_s_own_history(self, server, monkeypatch):
         """#154: `basis: unknown` has to mean nobody has a number. A stored

From ea272ce44e7b55b95a455840d0481e70bc6c4fe5 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Thu, 17 Sep 2026 11:23:33 -0500
Subject: [PATCH 03/77] feat(tasks): #188 - add transcribe_audio ASR task

Adds a Whisper-class automatic-speech-recognition task so a spoken-word
defect in a TTS deliverable (dropped line, mid-sentence truncation) can
be checked against the text it was supposed to speak, instead of only
inferred from duration/timing arithmetic.

dw/tasks/audio_transcription.py is a dedicated module, like
text_generation.py, with `from transformers import pipeline as
hf_pipeline` at module level rather than lazily inside the function -
audio_utils.py's other tasks import transformers lazily per-task to
avoid forcing that heavy import on every one of them, but a lazy
import inside a closure is not interceptable by
unittest.mock.patch("transformers.pipeline") in this environment
(transformers' lazy-module __getattr__ machinery), which was causing
the task's tests to download a real model. Moving it to its own
module with a module-level import, matching text_generation.py's
already-proven-testable pattern, fixes that.

Default model is openai/whisper-base, ungated and already within the
transformers dependency.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 docs/TASKS.md                             |  26 ++++++
 dw/tasks/audio_transcription.py           |  86 ++++++++++++++++++
 dw/tasks/audio_utils.py                   |   2 +
 dw/tasks/task.py                          |  14 +++
 tests/test_catalog_structure.py           |   1 +
 tests/test_transcribe_audio.py            | 106 ++++++++++++++++++++++
 workflows/templates/transcribe-audio.json |  23 +++++
 7 files changed, 258 insertions(+)
 create mode 100644 dw/tasks/audio_transcription.py
 create mode 100644 tests/test_transcribe_audio.py
 create mode 100644 workflows/templates/transcribe-audio.json

diff --git a/docs/TASKS.md b/docs/TASKS.md
index 64b63f04..e1109fb0 100644
--- a/docs/TASKS.md
+++ b/docs/TASKS.md
@@ -1198,6 +1198,32 @@ A speech model is worth releasing before a video model loads — set `release_mo
 - [generate-speech.json](../workflows/templates/generate-speech.json) — Speak a line and save it as a `.wav`
 - [voice-timbre-reference.json](../workflows/templates/minimax/voice-timbre-reference.json) — Generate a voice, then condition H3's `<Audio 1>` on it
 
+## Speech Transcription
+
+Transcribe spoken audio to text with a local Whisper-class model. The word-correctness of a TTS deliverable — a dropped line, a mid-sentence truncation — can only be inferred from duration and timing arithmetic without this; `transcribe_audio` checks it directly against the text the deliverable was supposed to speak.
+
+```json
+{
+    "task": {
+        "command": "transcribe_audio",
+        "arguments": {
+            "audio": "previous_result:speak"
+        }
+    },
+    "result": { "content_type": "text/plain" }
+}
+```
+
+| Argument | Required | Description |
+| -------- | -------- | ----------- |
+| `audio` | Yes | Path or URL of an audio file (or of a video file, whose soundtrack is taken), a video with a soundtrack, or a waveform — usually a `previous_result:` reference |
+| `sample_rate` | No | Sample rate of a waveform passed directly |
+| `model_name` | No | HuggingFace model ID of a Whisper-class ASR model (default: `openai/whisper-base`) |
+
+Multi-channel audio is downmixed to mono and resampled to 16 kHz before transcription, since that is what a Whisper-class model is trained on; the source audio itself is untouched. The result is plain text, read with MCP's `get_output_text`.
+
+**Example:** [transcribe-audio.json](../workflows/templates/transcribe-audio.json) — Transcribe an audio file to text.
+
 ## Frame Interpolation
 
 Increase video frame rate using RIFE (Real-Time Intermediate Flow Estimation). Takes a video and inserts intermediate frames between each pair. The result is one video artifact without a soundtrack - the frame count changed, so [`pair_audio`](#pair_audio) is how the original track comes back. [interpolate-frames.json](../workflows/templates/interpolate-frames.json) shows the interpolation itself.
diff --git a/dw/tasks/audio_transcription.py b/dw/tasks/audio_transcription.py
new file mode 100644
index 00000000..7e97584b
--- /dev/null
+++ b/dw/tasks/audio_transcription.py
@@ -0,0 +1,86 @@
+"""
+Speech-to-text via HuggingFace transformers.
+
+Runs a local automatic-speech-recognition model, so a word-correctness
+defect in a TTS deliverable (a dropped line, a mid-sentence truncation) can
+be checked against the text it was supposed to speak instead of inferred
+from duration and timing arithmetic (#188).
+
+A dedicated module, like text_generation.py, rather than living in
+audio_utils.py alongside the other audio tasks: those tasks share that
+module and lazily import transformers only when a task that needs it runs,
+and a module-level import here would force that heavy import on every one
+of them.
+"""
+
+import logging
+
+import numpy
+from transformers import pipeline as hf_pipeline
+
+from .. import preferred_task_dtype
+from .model_cache import cached_model, hf_pipeline_placement
+from .audio_utils import _waveform_and_rate, resample_waveform
+
+logger = logging.getLogger("dw")
+
+_DEFAULT_ASR_MODEL = "openai/whisper-base"
+_ASR_SAMPLE_RATE = 16000
+
+
+def _downmixed_mono(waveform):
+    """Average a (channels, samples) waveform down to one channel.
+
+    Whisper-class models are trained on mono; every other audio task keeps
+    multi-channel audio as far as it can, so this stays local to
+    transcribe_audio rather than becoming a general helper.
+    """
+    if waveform.shape[0] == 1:
+        return waveform[0]
+    return waveform.mean(axis=0)
+
+
+def transcribe_audio(audio, device="cpu", sample_rate=None, **kwargs):
+    """Task command: transcribe spoken audio to text.
+
+    Args:
+        audio: Path or URL of an audio file (or of a video file, whose
+            soundtrack is taken), a video generated with a soundtrack, or a
+            waveform (which needs sample_rate alongside it)
+        device: Target device ("cuda", "mps", "cpu").
+        sample_rate: Sample rate of a waveform passed directly.
+        **kwargs:
+            model_name: HuggingFace model ID of a Whisper-class ASR model
+                (default: openai/whisper-base).
+
+    Returns:
+        Transcribed text string.
+    """
+    waveform, waveform_rate = _waveform_and_rate(audio, sample_rate, "transcribe_audio")
+    mono = _downmixed_mono(waveform)
+    if waveform_rate != _ASR_SAMPLE_RATE:
+        mono = resample_waveform(
+            mono.reshape(1, -1), waveform_rate, _ASR_SAMPLE_RATE
+        )[0]
+
+    model_name = kwargs.get("model_name", _DEFAULT_ASR_MODEL)
+    dtype = preferred_task_dtype(device)
+
+    def load_pipe():
+        logger.info(f"Transcribing audio with {model_name} on {device}")
+        placement = hf_pipeline_placement(device)
+        return hf_pipeline(
+            "automatic-speech-recognition",
+            model=model_name,
+            torch_dtype=dtype,
+            **placement,
+        )
+
+    pipe = cached_model(
+        ("transcribe_audio", model_name, str(device), str(dtype)), load_pipe
+    )
+
+    result = pipe({"raw": mono.astype(numpy.float32), "sampling_rate": _ASR_SAMPLE_RATE})
+    text = result["text"].strip()
+    logger.info(f"Transcript: {text[:100]}{'...' if len(text) > 100 else ''}")
+    return text
diff --git a/dw/tasks/audio_utils.py b/dw/tasks/audio_utils.py
index d15c8d41..64dc1b78 100644
--- a/dw/tasks/audio_utils.py
+++ b/dw/tasks/audio_utils.py
@@ -14,12 +14,14 @@
 import soundfile
 import torch
 
+from .. import preferred_task_dtype
 from ..events import emit_warning
 from ..task_domains import as_number, check_arguments
 from ..security import (
     validate_file_extension,
     ALLOWED_AUDIO_EXTENSIONS,
 )
+from .model_cache import cached_model, hf_pipeline_placement
 
 logger = logging.getLogger("dw")
 
diff --git a/dw/tasks/task.py b/dw/tasks/task.py
index f06f092f..789aaee5 100644
--- a/dw/tasks/task.py
+++ b/dw/tasks/task.py
@@ -408,6 +408,20 @@ def _handle_image_to_text(task, arguments, previous_pipelines):
     return image_to_text(image, device=task.device_for(arguments), **arguments)
 
 
+@register_command(
+    "transcribe_audio",
+    implementation="dw.tasks.audio_transcription.transcribe_audio",
+    consumes_device=True,
+)
+def _handle_transcribe_audio(task, arguments, previous_pipelines):
+    """Transcribe spoken audio to text"""
+    logger.debug("Transcribing audio")
+    audio = arguments.pop("audio")
+    from .audio_transcription import transcribe_audio
+
+    return transcribe_audio(audio, device=task.device_for(arguments), **arguments)
+
+
 @register_command(
     "text_generation",
     implementation="dw.tasks.text_generation.generate_text",
diff --git a/tests/test_catalog_structure.py b/tests/test_catalog_structure.py
index 3674aa7a..5a28194d 100644
--- a/tests/test_catalog_structure.py
+++ b/tests/test_catalog_structure.py
@@ -116,6 +116,7 @@ def load(path):
     "workflows/templates/image-processors.json",
     "workflows/templates/recenter-crop.json",
     "workflows/templates/segment.json",
+    "workflows/templates/transcribe-audio.json",
     "workflows/templates/upscale-spandrel.json",
 }
 
diff --git a/tests/test_transcribe_audio.py b/tests/test_transcribe_audio.py
new file mode 100644
index 00000000..ae3b7143
--- /dev/null
+++ b/tests/test_transcribe_audio.py
@@ -0,0 +1,106 @@
+"""Tests for transcribe_audio task."""
+
+import unittest
+from unittest.mock import patch, MagicMock
+
+import numpy
+
+from dw.tasks.audio_transcription import (
+    transcribe_audio,
+    _DEFAULT_ASR_MODEL,
+    _ASR_SAMPLE_RATE,
+)
+
+
+class TestTranscribeAudio(unittest.TestCase):
+    """Tests for the transcribe_audio function.
+
+    hf_pipeline is a module-level import in audio_transcription.py (like
+    text_generation.py's), so it is patched as that module's attribute.
+    """
+
+    def _waveform(self, channels=1, seconds=1.0, sample_rate=16000):
+        samples = int(seconds * sample_rate)
+        tone = numpy.zeros((channels, samples), dtype=numpy.float32)
+        return tone, sample_rate
+
+    def _mock_pipe(self, mock_pipeline, text="hello world"):
+        pipe = MagicMock()
+        pipe.return_value = {"text": text}
+        mock_pipeline.return_value = pipe
+        return pipe
+
+    @patch("dw.tasks.audio_transcription.hf_pipeline")
+    def test_returns_transcript_string(self, mock_pipeline):
+        self._mock_pipe(mock_pipeline, "testing 1 2 3")
+        waveform, rate = self._waveform()
+
+        result = transcribe_audio(waveform, device="cpu", sample_rate=rate)
+
+        self.assertEqual(result, "testing 1 2 3")
+        mock_pipeline.assert_called_once()
+
+    @patch("dw.tasks.audio_transcription.hf_pipeline")
+    def test_builds_an_asr_pipeline_with_default_model(self, mock_pipeline):
+        self._mock_pipe(mock_pipeline)
+        waveform, rate = self._waveform()
+
+        transcribe_audio(waveform, device="cpu", sample_rate=rate)
+
+        self.assertEqual(
+            mock_pipeline.call_args[0][0], "automatic-speech-recognition"
+        )
+        self.assertEqual(mock_pipeline.call_args[1]["model"], _DEFAULT_ASR_MODEL)
+
+    @patch("dw.tasks.audio_transcription.hf_pipeline")
+    def test_custom_model_name(self, mock_pipeline):
+        self._mock_pipe(mock_pipeline)
+        waveform, rate = self._waveform()
+
+        transcribe_audio(
+            waveform, device="cpu", sample_rate=rate, model_name="openai/whisper-tiny"
+        )
+
+        self.assertEqual(mock_pipeline.call_args[1]["model"], "openai/whisper-tiny")
+
+    @patch("dw.tasks.audio_transcription.hf_pipeline")
+    def test_downmixes_stereo_to_mono(self, mock_pipeline):
+        pipe = self._mock_pipe(mock_pipeline)
+        waveform, rate = self._waveform(channels=2)
+
+        transcribe_audio(waveform, device="cpu", sample_rate=rate)
+
+        fed = pipe.call_args[0][0]
+        self.assertEqual(fed["raw"].ndim, 1)
+
+    @patch("dw.tasks.audio_transcription.hf_pipeline")
+    def test_resamples_to_16khz(self, mock_pipeline):
+        pipe = self._mock_pipe(mock_pipeline)
+        waveform, rate = self._waveform(sample_rate=44100)
+
+        transcribe_audio(waveform, device="cpu", sample_rate=rate)
+
+        fed = pipe.call_args[0][0]
+        self.assertEqual(fed["sampling_rate"], _ASR_SAMPLE_RATE)
+
+    @patch("dw.tasks.audio_transcription.hf_pipeline")
+    def test_strips_whitespace(self, mock_pipeline):
+        self._mock_pipe(mock_pipeline, "  spaced out  ")
+        waveform, rate = self._waveform()
+
+        result = transcribe_audio(waveform, device="cpu", sample_rate=rate)
+
+        self.assertEqual(result, "spaced out")
+
+
+class TestTranscribeAudioRegistration(unittest.TestCase):
+    """Test that transcribe_audio is registered as a task command."""
+
+    def test_command_registered(self):
+        from dw.tasks.task import _COMMAND_REGISTRY
+
+        self.assertIn("transcribe_audio", _COMMAND_REGISTRY)
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/workflows/templates/transcribe-audio.json b/workflows/templates/transcribe-audio.json
new file mode 100644
index 00000000..b2444cb4
--- /dev/null
+++ b/workflows/templates/transcribe-audio.json
@@ -0,0 +1,23 @@
+{
+  "id": "TranscribeAudio",
+  "description": "Transcribes spoken audio to text with a local Whisper-class model. Useful for checking a TTS deliverable's word correctness directly against the text it was supposed to speak, rather than inferring a dropped line or a mid-sentence truncation from duration and timing.",
+  "variables": {
+    "input_audio": "https://example.com/speech.mp3",
+    "model_name": "openai/whisper-base"
+  },
+  "steps": [
+    {
+      "name": "transcribe",
+      "task": {
+        "command": "transcribe_audio",
+        "arguments": {
+          "audio": "variable:input_audio",
+          "model_name": "variable:model_name"
+        }
+      },
+      "result": {
+        "content_type": "text/plain"
+      }
+    }
+  ]
+}

From 3ae67b78e4e29e7c743b2c11488d19ba5f9a02a9 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Thu, 17 Sep 2026 11:25:08 -0500
Subject: [PATCH 04/77] fix(tasks): #188 - drop unused imports left in
 audio_utils.py

preferred_task_dtype, cached_model and hf_pipeline_placement were
only used by the ASR code that moved to audio_transcription.py; the
imports were left behind.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 dw/tasks/audio_utils.py | 2 --
 1 file changed, 2 deletions(-)

diff --git a/dw/tasks/audio_utils.py b/dw/tasks/audio_utils.py
index 64dc1b78..d15c8d41 100644
--- a/dw/tasks/audio_utils.py
+++ b/dw/tasks/audio_utils.py
@@ -14,14 +14,12 @@
 import soundfile
 import torch
 
-from .. import preferred_task_dtype
 from ..events import emit_warning
 from ..task_domains import as_number, check_arguments
 from ..security import (
     validate_file_extension,
     ALLOWED_AUDIO_EXTENSIONS,
 )
-from .model_cache import cached_model, hf_pipeline_placement
 
 logger = logging.getLogger("dw")
 

From f78226ea41df62f1fe6cb12af3f85b137a56bd63 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Thu, 17 Sep 2026 11:46:07 -0500
Subject: [PATCH 05/77] fix(plan): #186 - actually probe file access to detect
 a blocked gate

model_info succeeding proves nothing about whether this box's token has
been granted access to a gated repo - the hub serves a gated repo's
metadata to anyone, and GatedRepoError from model_info alone only ever
fires for repos that hide from that call entirely. The tester's verify
pass showed access_blocked staying false for repos this box's token was
actually refused on (e.g. pyannote/speaker-diarization-3.1).

A gated entry is now checked for real with a HEAD request against one of
the repo's own files (get_hf_file_metadata), the same request class a
run's actual load would make. access_blocked is null, not false, when
there is no file to probe or the probe fails for an unrelated reason -
"unknown" is not "not blocked".

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 docs/SERVER.md     | 14 ++++++++---
 dw/plan.py         | 43 +++++++++++++++++++++++++++------
 tests/test_plan.py | 60 +++++++++++++++++++++++++++++++++++++++++++++-
 3 files changed, 106 insertions(+), 11 deletions(-)

diff --git a/docs/SERVER.md b/docs/SERVER.md
index 69e8810c..6e893a55 100644
--- a/docs/SERVER.md
+++ b/docs/SERVER.md
@@ -309,9 +309,17 @@ The editor's forms come from these; they are just as usable from scripts:
   repo (`false`, `"auto"` or `"manual"`) or `null` when the lookup itself
   failed for a reason other than the gate; `access_blocked` is `true`
   when this box's Hugging Face token specifically has not been granted
-  access to a gated repo (`GatedRepoError` from the hub, the pre-flight
-  signal for what would otherwise be a 403 partway into a run, #186) -
-  `validate_workflow`'s `warnings` carries one line per such entry. Each
+  access to a gated repo, `false` when the repo isn't gated or the token is
+  accepted, and `null` when it could not be determined either way. A gated
+  repo's own metadata is served by the hub regardless of this token's
+  access, so `model_info` succeeding proves nothing about the gate; a
+  gated entry gets a second, real check - a HEAD request against one of the
+  repo's own files - and it is *that* request's `GatedRepoError` that sets
+  `access_blocked: true` (the pre-flight signal for what would otherwise be
+  a 403 partway into a run, #186). `access_blocked` is `null` when there is
+  no file to probe or the probe itself fails for an unrelated reason (e.g.
+  offline) - "unknown" is not "not blocked". `validate_workflow`'s
+  `warnings` carries one line per entry with `access_blocked: true`. Each
   `from_single_file` URL is `{repo: null, url, gb: null, gated: null,
   access_blocked: null}`, since a direct file URL is never gated; and
   `estimate`, `{minutes, basis,
diff --git a/dw/plan.py b/dw/plan.py
index 3a8d1a6e..2174247c 100644
--- a/dw/plan.py
+++ b/dw/plan.py
@@ -19,6 +19,7 @@
 import os
 
 from huggingface_hub import model_info
+from huggingface_hub import get_hf_file_metadata, hf_hub_url
 from huggingface_hub.utils import GatedRepoError, HFValidationError, validate_repo_id
 
 from .elision import elide_definition
@@ -537,12 +538,17 @@ def _model_info(name):
     blocked from it - a `(gb, gated, access_blocked)` triple.
 
     `gated` is `model_info`'s own field (`False` / `"auto"` / `"manual"`),
-    readable only when the call succeeds - which it does even for a gated
-    repo this token has been granted. A `GatedRepoError` is the call failing
-    for exactly that reason: the repo is gated and this box's token has not
-    (or no longer) been granted access, distinct from every other lookup
-    failure (unreachable, a file with no size), which says nothing about the
-    gate either way (#186).
+    readable only when the call succeeds - and the hub answers `model_info`
+    for a gated repo regardless of whether this token has been granted
+    access, since that call serves metadata rather than file bytes (found
+    verifying #186: `access_blocked` came back `false` for repos this box's
+    token was actually refused on). A `GatedRepoError` straight out of
+    `model_info` is still a real signal - some other endpoint behind it
+    checked and refused - but its absence proves nothing, so a `gated` repo
+    that got this far is checked for real with a HEAD request against one of
+    its own files (`_probe_gate_blocked`), the same request class a run's
+    actual load would make and the one place the hub's 403 for "gated, token
+    not accepted" actually appears.
     """
     try:
         info = model_info(name, files_metadata=True, timeout=SIZE_LOOKUP_TIMEOUT)
@@ -555,4 +561,27 @@ def _model_info(name):
     total = sum(s.size for s in (info.siblings or []) if getattr(s, "size", None))
     gb = round(total / GIB, 1) if total else None
     gated = getattr(info, "gated", False) or False
-    return gb, gated, False
+    access_blocked = False
+    if gated:
+        access_blocked = _probe_gate_blocked(name, info.siblings or [])
+    return gb, gated, access_blocked
+
+
+def _probe_gate_blocked(name, siblings):
+    """HEAD one real file of a gated repo to see whether this box's token is
+    actually accepted - `model_info` succeeding says nothing either way
+    (#186). `None` when there is no file to probe or the probe fails for a
+    reason other than the gate, since that is "unknown", not "not blocked".
+    """
+    filename = next((s.rfilename for s in siblings if getattr(s, "rfilename", None)), None)
+    if filename is None:
+        return None
+    try:
+        get_hf_file_metadata(hf_hub_url(name, filename), timeout=SIZE_LOOKUP_TIMEOUT)
+        return False
+    except GatedRepoError as e:
+        logger.debug(f"Gate not accepted for {name}: {e}")
+        return True
+    except Exception as e:
+        logger.debug(f"Gate probe inconclusive for {name}: {e}")
+        return None
diff --git a/tests/test_plan.py b/tests/test_plan.py
index 39078e26..c6911bbd 100644
--- a/tests/test_plan.py
+++ b/tests/test_plan.py
@@ -618,11 +618,15 @@ def fake_model_info(name, **kwargs):
     def test_a_gated_repo_this_token_may_access_is_not_blocked(self, plan, monkeypatch):
         import dw.plan
 
+        class Sibling:
+            rfilename = "config.json"
+
         class Info:
-            siblings = []
+            siblings = [Sibling()]
             gated = "manual"
 
         monkeypatch.setattr(dw.plan, "model_info", lambda name, **k: Info())
+        monkeypatch.setattr(dw.plan, "get_hf_file_metadata", lambda url, **k: object())
         assert plan(lookup_sizes=True)["downloads_required"] == [
             {"repo": "org/still-model", "gb": None, "gated": "manual", "access_blocked": False}
         ]
@@ -634,6 +638,29 @@ def test_a_gated_repo_this_token_lacks_access_to_is_blocked(self, plan, monkeypa
 
         response = httpx.Response(403, request=httpx.Request("GET", "https://hf.co/x"))
 
+        class Sibling:
+            rfilename = "config.json"
+
+        class Info:
+            siblings = [Sibling()]
+            gated = "manual"
+
+        def boom(*a, **k):
+            raise GatedRepoError("no access", response=response)
+
+        monkeypatch.setattr(dw.plan, "model_info", lambda name, **k: Info())
+        monkeypatch.setattr(dw.plan, "get_hf_file_metadata", boom)
+        assert plan(lookup_sizes=True)["downloads_required"] == [
+            {"repo": "org/still-model", "gb": None, "gated": "manual", "access_blocked": True}
+        ]
+
+    def test_a_gated_repo_model_info_itself_refuses_is_blocked(self, plan, monkeypatch):
+        import httpx
+        import dw.plan
+        from huggingface_hub.utils import GatedRepoError
+
+        response = httpx.Response(403, request=httpx.Request("GET", "https://hf.co/x"))
+
         def boom(*a, **k):
             raise GatedRepoError("no access", response=response)
 
@@ -642,6 +669,37 @@ def boom(*a, **k):
             {"repo": "org/still-model", "gb": None, "gated": True, "access_blocked": True}
         ]
 
+    def test_a_gated_repo_with_no_probeable_file_is_unknown(self, plan, monkeypatch):
+        import dw.plan
+
+        class Info:
+            siblings = []
+            gated = "auto"
+
+        monkeypatch.setattr(dw.plan, "model_info", lambda name, **k: Info())
+        assert plan(lookup_sizes=True)["downloads_required"] == [
+            {"repo": "org/still-model", "gb": None, "gated": "auto", "access_blocked": None}
+        ]
+
+    def test_a_gate_probe_failing_for_an_unrelated_reason_is_unknown(self, plan, monkeypatch):
+        import dw.plan
+
+        class Sibling:
+            rfilename = "config.json"
+
+        class Info:
+            siblings = [Sibling()]
+            gated = "auto"
+
+        def boom(*a, **k):
+            raise RuntimeError("offline")
+
+        monkeypatch.setattr(dw.plan, "model_info", lambda name, **k: Info())
+        monkeypatch.setattr(dw.plan, "get_hf_file_metadata", boom)
+        assert plan(lookup_sizes=True)["downloads_required"] == [
+            {"repo": "org/still-model", "gb": None, "gated": "auto", "access_blocked": None}
+        ]
+
     def test_a_hub_failure_is_a_null_size(self, plan, monkeypatch):
         import dw.plan
 

From a5cef23d68717dd1b8718f6a79f4e371e0871df9 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Thu, 17 Sep 2026 13:09:31 -0500
Subject: [PATCH 06/77] fix(templates): #196 - resample the score at its own
 rate in dissolve-between-shots, mirroring #180

dissolve-between-shots still carried the pre-#180 wiring: the soundtrack
step fed the mix sample_rate into slice_audio as an override on the score
file, which relabels its samples rather than resampling them (changing
speed and pitch) and made the past-end check run against the relabelled
length instead of the file's real one. The template now slices the score
at its own rate and resamples it afterward in a separate
soundtrack_resampled step, exactly as assemble-and-score does since #180.

Swept the rest of the catalog for the same pattern: minimax/music-video.json
also feeds variable:sample_rate into slice_audio, but its source is
generated audio (write_song, declared to always produce 44100 Hz) rather
than a file asset, so it's a different, lower-priority case - noted on the
issue for a human call rather than folded into this fix.

Model: sonnet (Anthropic)

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 workflows/templates/dissolve-between-shots.json | 15 ++++++++++++---
 1 file changed, 12 insertions(+), 3 deletions(-)

diff --git a/workflows/templates/dissolve-between-shots.json b/workflows/templates/dissolve-between-shots.json
index e0aa43a4..eb2a099b 100644
--- a/workflows/templates/dissolve-between-shots.json
+++ b/workflows/templates/dissolve-between-shots.json
@@ -61,8 +61,17 @@
                     "audio": "variable:score",
                     "start_frame": "variable:score_start_frame",
                     "num_frames": "variable:total_frames",
-                    "fps": "variable:fps",
-                    "sample_rate": "variable:sample_rate"
+                    "fps": "variable:fps"
+                }
+            }
+        },
+        {
+            "name": "soundtrack_resampled",
+            "task": {
+                "command": "resample_audio",
+                "arguments": {
+                    "audio": "previous_result:soundtrack",
+                    "target_sample_rate": "variable:sample_rate"
                 }
             }
         },
@@ -72,7 +81,7 @@
                 "command": "mix_audio",
                 "arguments": {
                     "audios": [
-                        "previous_result:soundtrack",
+                        "previous_result:soundtrack_resampled",
                         "previous_result:world"
                     ],
                     "gains": [

From f19f83979a0c221922c940f848c1fb6493b07a9a Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Thu, 17 Sep 2026 13:17:24 -0500
Subject: [PATCH 07/77] docs(audio): correct loop_audio crossfade claim,
 document gain_audio whole-track idiom

A qa exercise against a pre-fix workflow flagged two docstring/doc gaps:

- loop_audio's docstring and TASKS.md claimed the crossfade means "a tone
  with any movement in it does not tick once a second." Measured: a source
  with one transient still pulses 9.3 dB once per lap - the crossfade
  removes the seam's click, not a repeating level profile. Documented the
  actual behavior and the practical mitigation (pick an evenly-leveled
  source).
- gain_audio requires one of its two region pairs; there is no separate
  "whole track" mode, and nothing said so. Documented the idiom
  (start_seconds=0, duration_seconds unset) that covers the whole track
  without the caller needing to already know its length.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 docs/TASKS.md           | 17 +++++++++++++----
 dw/tasks/audio_utils.py | 18 +++++++++++++-----
 2 files changed, 26 insertions(+), 9 deletions(-)

diff --git a/docs/TASKS.md b/docs/TASKS.md
index e1109fb0..0540762b 100644
--- a/docs/TASKS.md
+++ b/docs/TASKS.md
@@ -521,6 +521,12 @@ material:
 | `start_frame` / `num_frames` / `fps` | One pair | The region in video frames; `fps` is required, start and count may be omitted |
 | `sample_rate` | With a waveform | Sample rate of a directly passed waveform (files carry their own) |
 
+One pair is required — there is no separate "whole track" mode — but the
+whole track is still one step: give just `start_seconds: 0` and leave
+`duration_seconds` unset (or `start_frame: 0` + `fps` and leave `num_frames`
+unset), which runs to the end of the track without needing to already know
+how long that is.
+
 ### crossfade_audio
 
 Join audio tracks with an equal-power crossfade. Each seam overlaps the two
@@ -664,10 +670,13 @@ scene so the edits stop being audible:
 | `sample_rate` | With a waveform | Sample rate of a waveform passed directly; given for a file or a video it overrides the rate they carry |
 
 Laps are joined with an equal-power crossfade rather than butted together, so
-the loop point is not a click and a tone with movement in it does not tick once
-a second. The source is used whole every lap and only the last one is trimmed,
-so the bed lands exactly on the requested length; a source longer than the
-request is trimmed to it.
+the loop point itself is not a click. That only smooths the seam: a transient
+in the source (a hit, a swell) still recurs once per lap at full strength, so
+the loop still reads as a level pulse at the lap rate — measured at 9.3 dB on
+a source with one such transient. Pick a source with even internal level to
+avoid the pulse; the crossfade does not remove it. The source is used whole
+every lap and only the last one is trimmed, so the bed lands exactly on the
+requested length; a source longer than the request is trimmed to it.
 
 The bed is laid under the cut with `mix_audio` and attached to the picture with
 `pair_audio`:
diff --git a/dw/tasks/audio_utils.py b/dw/tasks/audio_utils.py
index d15c8d41..603e74c5 100644
--- a/dw/tasks/audio_utils.py
+++ b/dw/tasks/audio_utils.py
@@ -394,7 +394,11 @@ def gain_audio(
     passed through unchanged, so ducking a scene under another is one step
     rather than the slice/gain/mix/rejoin/pair_audio chain that was
     previously the only way to apply a gain to part of a track rather than
-    all of it (#187).
+    all of it (#187). At least one of the two pairs is required - there is
+    no separate "whole track" mode - but the whole track is still one step:
+    give just start_seconds=0 (or start_frame=0 + fps) and leave
+    duration_seconds/num_frames unset, which runs to the end of the track
+    without the caller needing to already know how long that is.
 
     Unlike slice_audio, a region reaching past the end of the track is
     clipped to it rather than zero-padded: there is no silence there to
@@ -719,10 +723,14 @@ def loop_audio(
     the length of the picture.
 
     Laps are joined with an equal-power crossfade rather than butted
-    together, so the loop point is not a click and a tone with any movement
-    in it does not tick once a second. The source is used whole every lap;
-    only the last one is trimmed, to land exactly on the requested length. A
-    source longer than the request is trimmed to it.
+    together, so the loop point itself is not a click. That only smooths the
+    seam, though: a transient in the source (a hit, a swell) still recurs
+    once per lap at full strength, so the loop still reads as a level pulse
+    at the lap rate - measured at 9.3 dB on a source with one such transient.
+    Picking a source with even internal level avoids the pulse; the
+    crossfade does not. The source is used whole
+    every lap; only the last one is trimmed, to land exactly on the
+    requested length. A source longer than the request is trimmed to it.
 
     Args:
         audio: Path or URL of an audio file (or of a video file, whose

From fcd87bd6eb4012192b4f3c2e96da5ef8301e2b8b Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Thu, 17 Sep 2026 13:36:20 -0500
Subject: [PATCH 08/77] fix(audio): #197 - fit in-memory-generated audio to
 frame count before muxing

A shot generated through a previous_result: chain never passes through
_decode_audio_video, so codec-padding drift between the audio and the
frame count previously only got trimmed on the file-decode path. Now
save_audio_video calls _fit_audio_to_frames itself before muxing,
skipping the segment-backed streaming path (which already does its own
accounting), so per-shot lip-sync drift no longer accumulates across a
cut.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 dw/result.py         | 21 +++++++++++++++++----
 tests/test_result.py | 17 ++++++++++++++++-
 2 files changed, 33 insertions(+), 5 deletions(-)

diff --git a/dw/result.py b/dw/result.py
index cddab44c..088fdbde 100644
--- a/dw/result.py
+++ b/dw/result.py
@@ -752,6 +752,19 @@ def save_audio_video(self, artifact, output_path, content_type):
         sample_rate = self.result_definition.get(
             "audio_sample_rate", artifact.sample_rate
         )
+        audio = artifact.audio
+        # Frames generated in memory (a previous_result-chained shot, a modular
+        # pipeline's own output) never went through _decode_audio_video, so a
+        # codec-padding mismatch between the audio and the frame count survives
+        # here instead of being trimmed there (#197). Segment-backed frames are
+        # written by the chain pipeline processor, which already carries its own
+        # fps and does its own segment-length accounting - left alone.
+        if audio is not None and sample_rate is not None and fps and not hasattr(
+            artifact.frames, "cleanup"
+        ):
+            from .tasks.video_utils import _fit_audio_to_frames
+
+            audio = _fit_audio_to_frames(audio, len(artifact.frames), fps, sample_rate)
 
         # Segment-backed frames (a chained step with save_segments) replay from
         # disk one segment at a time, so the final video is streamed instead of
@@ -790,7 +803,7 @@ def save_audio_video(self, artifact, output_path, content_type):
             return
 
         reason = None
-        if artifact.audio is None:
+        if audio is None:
             reason = "the pipeline returned no audio"
         elif sample_rate is None:
             reason = "the audio sample rate is unknown"
@@ -802,21 +815,21 @@ def save_audio_video(self, artifact, output_path, content_type):
         if reason is not None:
             # No audio at all is an expected shape - video-only chains and
             # concatenations - so it logs quietly; losing audio we do have warns
-            log = logger.debug if artifact.audio is None else logger.warning
+            log = logger.debug if audio is None else logger.warning
             log(f"Saving {output_path} without its audio because {reason}")
             export_to_video(artifact.frames, output_path, fps=fps)
             return
 
         logger.debug(f"Muxing audio at {sample_rate}Hz into {output_path}")
         self._no_headroom_warned = (
-            warn_without_headroom(artifact.audio, os.path.basename(output_path))
+            warn_without_headroom(audio, os.path.basename(output_path))
             is not None
         )
         encode_video(
             frames_for_encoding(artifact.frames),
             fps=fps,
             output_path=output_path,
-            audio=as_audio_track(artifact.audio),
+            audio=as_audio_track(audio),
             audio_sample_rate=sample_rate,
         )
 
diff --git a/tests/test_result.py b/tests/test_result.py
index 6e442361..c966e52f 100644
--- a/tests/test_result.py
+++ b/tests/test_result.py
@@ -490,8 +490,11 @@ def test_outputs_without_video_are_left_alone(self):
         assert get_artifact_list(outputs) == [outputs]
 
     def test_generated_audio_is_muxed_into_the_video(self):
+        # A frame count far longer than the audio keeps the mismatch outside
+        # _fit_audio_to_frames's codec-padding tolerance, so the audio passes
+        # through unchanged and this test stays about muxing, not fitting.
         outputs = {
-            "videos": ["frames"],
+            "videos": [["frame"] * 1000],
             "audio": torch.zeros((1, 2, 100)),
             "sampling_rate": 16000,
         }
@@ -607,6 +610,18 @@ def test_audio_is_muxed_into_the_video(self):
         assert arguments["audio_sample_rate"] == 48000
         assert arguments["output_path"].endswith(".mp4")
 
+    def test_audio_is_fit_to_frame_count_for_in_memory_generation(self):
+        # #197: a shot generated in memory via previous_result: chaining never
+        # passes through _decode_audio_video, so codec-padding drift between
+        # the audio and the frame count has to be trimmed here instead.
+        frames = ["frame"] * 48
+        audio = torch.zeros((2, 2100))  # 48 frames @ 24fps @ 1000Hz -> 2000
+        artifact = AudioVideo(frames, audio, 1000)
+
+        encode, _ = self.save({"content_type": "video/mp4", "fps": 24}, artifact)
+
+        assert encode.call_args.kwargs["audio"].shape == (2, 2000)
+
     def test_result_definition_overrides_the_sample_rate(self):
         artifact = AudioVideo("frames", torch.zeros((2, 100)), 48000)
 

From a0cd11a3ce05e7b0c9b25418cce70aabe7401834 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Thu, 17 Sep 2026 13:37:02 -0500
Subject: [PATCH 09/77] fix(audio): #198/#199 - warn on tonal bleed material,
 add gain_db to bleed_join

#198: bleed_join's reversed tail assumes direction-agnostic ambience
(room tone, crowd noise). A copied musical phrase or half-spoken word
reads as a stutter whichever direction it runs, and only a peak>1.0
clip check existed to catch anything wrong with the tail. Added a
numpy-only spectral-flatness heuristic (_spectral_flatness,
TONAL_FLATNESS_THRESHOLD) that checks the outgoing tail before it is
bled across the seam and emits a warning (kind=bleed_tonal_material)
through emit_warning, so it reaches the job's warnings list rather
than only the log.

#199: audio_bleed_ms had no way to turn a bled tail down, only off. Added
gain_db to bleed_join (0 = unchanged, negative ducks), threaded through
concat_videos as audio_bleed_gain_db. Not added to task_domains.py's
domain table - its own docstring rules out gain/dBFS values as "the
command's business".

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 docs/TASKS.md             | 10 ++++++--
 dw/tasks/audio_utils.py   | 52 ++++++++++++++++++++++++++++++++++++---
 dw/tasks/concat_videos.py | 13 +++++++++-
 tests/test_audio_utils.py | 32 ++++++++++++++++++++++++
 4 files changed, 100 insertions(+), 7 deletions(-)

diff --git a/docs/TASKS.md b/docs/TASKS.md
index 0540762b..139c5ff1 100644
--- a/docs/TASKS.md
+++ b/docs/TASKS.md
@@ -216,6 +216,7 @@ video generation" in the workflow guide):
 | `trim_frames` | No | Frames dropped from the head of every video after the first (default: 0) |
 | `crossfade_ms` | No | Equal-power crossfade at each audio seam, drawn from the trimmed material - no effect when `trim_frames` is 0, and validation warns when one is written there (default: 75) |
 | `audio_bleed_ms` | No | How long the outgoing video's tail rings on over the head of the next one, at seams with nothing trimmed to crossfade (default: 0, off) |
+| `audio_bleed_gain_db` | No | Gain applied to the bled tail before it is added, in dB - negative ducks a tail that would otherwise push the seam over 0 dBFS (default: 0, unchanged) |
 | `seam_fade_ms` | No | Fade on each side of a seam that gets neither a crossfade nor a bleed - for tonal material, not for a continuous bed (default: 3, just enough not to click) |
 | `fps` | No | Frame rate of the videos - required to join audio when trimming, and the rate the joined file is written at unless `result.fps` overrides it |
 | `match_levels` | No | Even the shots' loudness out before joining - `"rms"` for perceived level (the measurement `get_gallery_metadata` reports as `mean_dbfs`), `"peak"` for the loudest sample. Off by default |
@@ -225,7 +226,9 @@ A video may also be named by path or URL, which is how shots an earlier run
 already wrote are joined without regenerating them - the file is read with the
 audio muxed into it, and its track is fitted to the frames' own duration so the
 codec's block padding does not walk the sound off the picture over a dozen
-seams:
+seams. A shot generated in memory through a `previous_result:` chain gets the
+same fit, applied where the file is written rather than where it is decoded,
+so per-shot drift does not accumulate across a cut the way it once did:
 
 ```json
 {
@@ -281,7 +284,10 @@ a five-shot H3 sitcom cut, 700 ms still left a 44 dB hole at the worst seam;
 
 A bleed works because it copies ambience, which has no pitch and no attacks to
 give the copy away. It is the wrong tool for anything tonal - a copied musical
-phrase or half-spoken word reads as a stutter whichever direction it runs. When a
+phrase or half-spoken word reads as a stutter whichever direction it runs.
+`bleed_join` checks the outgoing tail's spectral flatness and warns when it
+looks tonal or speech-like rather than noise-like, so this failure mode
+surfaces in the job's `warnings` list instead of only in the mix. When a
 shot ends on something tonal, either give the cut a continuous bed with
 `slice_audio` + `loop_audio` + `mix_audio` + `pair_audio`, which leaves no seam
 to treat at all, or fade the
diff --git a/dw/tasks/audio_utils.py b/dw/tasks/audio_utils.py
index 603e74c5..b56b00b7 100644
--- a/dw/tasks/audio_utils.py
+++ b/dw/tasks/audio_utils.py
@@ -112,7 +112,27 @@ def equal_power_crossfade_join(
     return numpy.concatenate([previous[:, :-window], blended, following], axis=1)
 
 
-def bleed_join(previous, following, sample_rate, bleed_ms, seam_fade_ms=None):
+# Below this, the reversed tail's spectral energy is concentrated in a few
+# bins rather than spread across the band - speech or a pitched/tonal element
+# rather than room tone or crowd noise, the direction-agnostic material a
+# bleed is meant for
+TONAL_FLATNESS_THRESHOLD = 0.3
+
+
+def _spectral_flatness(waveform):
+    """Geometric-mean-over-arithmetic-mean of the magnitude spectrum, averaged
+    across channels - near 0 for tonal/speech material, near 1 for noise-like
+    material (see TONAL_FLATNESS_THRESHOLD)."""
+    spectrum = numpy.abs(numpy.fft.rfft(waveform, axis=1))
+    spectrum = numpy.maximum(spectrum, 1e-10)
+    geometric_mean = numpy.exp(numpy.mean(numpy.log(spectrum), axis=1))
+    arithmetic_mean = numpy.mean(spectrum, axis=1)
+    return float(numpy.mean(geometric_mean / arithmetic_mean))
+
+
+def bleed_join(
+    previous, following, sample_rate, bleed_ms, seam_fade_ms=None, gain_db=0.0
+):
     """Butt-join two waveforms, ringing the outgoing tail on across the seam.
 
     Cut-based workflows generate every shot independently, so nothing overlaps at
@@ -124,7 +144,10 @@ def bleed_join(previous, following, sample_rate, bleed_ms, seam_fade_ms=None):
     waveform, the way an audience carries across a picture cut. The copy is
     time-reversed so it starts on the outgoing waveform's own last sample and the
     seam stays continuous without a declick fade; crowd noise and room tone are
-    direction-agnostic, so the reversal itself is not audible.
+    direction-agnostic, so the reversal itself is not audible - speech or a
+    tonal/musical tail is not, which is what gets a warning below rather than a
+    refusal, since a caller who has already listened to the material may still
+    want the bleed.
 
     The tail is added to whatever the incoming waveform already carries, and
     neither side is shortened, so frames and samples stay in step.
@@ -136,6 +159,10 @@ def bleed_join(previous, following, sample_rate, bleed_ms, seam_fade_ms=None):
         bleed_ms: How long the tail rings on, clamped to the material available
         seam_fade_ms: Fade applied on each side of the seam when there is no
             material to bleed at all
+        gain_db: Gain applied to the bled copy before it is added, in dB -
+            negative ducks a tail that would otherwise push the seam over
+            0 dBFS; 0 (the default) is unchanged, full-scale, the prior
+            behavior
 
     Returns:
         The two waveforms joined, of their full combined length
@@ -150,15 +177,32 @@ def bleed_join(previous, following, sample_rate, bleed_ms, seam_fade_ms=None):
     if window <= 0:
         return _declick_join(previous, following, sample_rate, seam_fade_ms)
 
+    tail = previous[:, ::-1][:, :window]
+
+    flatness = _spectral_flatness(previous[:, -window:])
+    if flatness < TONAL_FLATNESS_THRESHOLD:
+        emit_warning(
+            f"bleed_join: the tail being reversed onto the seam looks tonal or "
+            f"speech-like (spectral flatness {flatness:.2f}) rather than the "
+            f"room tone or crowd noise a bleed is meant for - the reversal is "
+            f"likely to be audible as a stutter or a note running backwards. "
+            f"Consider seam_fade_ms for a hard cut on this material instead.",
+            kind="bleed_tonal_material",
+            command="bleed_join",
+            flatness=round(flatness, 3),
+        )
+
     decay, _ = _equal_power_ramps(window)  # cos: 1 down to ~0
+    gain = 10.0 ** (gain_db / 20.0) if gain_db else 1.0
     following = following.copy()
-    following[:, :window] += previous[:, ::-1][:, :window] * decay
+    following[:, :window] += tail * decay * gain
 
     peak = numpy.abs(following[:, :window]).max()
     if peak > 1.0:
         logger.warning(
             f"Audio bleed pushed the seam to {peak:.2f} - it is added to the "
-            f"incoming track, which was not silent enough to absorb it"
+            f"incoming track, which was not silent enough to absorb it. Pass "
+            f"a negative gain_db to duck the bled copy."
         )
     return numpy.concatenate([previous, following], axis=1)
 
diff --git a/dw/tasks/concat_videos.py b/dw/tasks/concat_videos.py
index 1b18365f..61aed5b9 100644
--- a/dw/tasks/concat_videos.py
+++ b/dw/tasks/concat_videos.py
@@ -45,6 +45,7 @@ def concat_videos(
     trim_frames=0,
     crossfade_ms=75,
     audio_bleed_ms=0,
+    audio_bleed_gain_db=0,
     seam_fade_ms=None,
     fps=None,
     match_levels=None,
@@ -72,6 +73,11 @@ def concat_videos(
             cut-based workflows, where every shot is generated independently and
             a running laugh track would otherwise butt-join into silence.
             0 (the default) leaves the seam as a plain declicked join
+        audio_bleed_gain_db: Gain applied to the bled tail before it is added,
+            in dB. 0 (the default) is unchanged, full-scale, matching the
+            outgoing material exactly; negative ducks a tail that would
+            otherwise push the seam over 0 dBFS, or that reads as too present
+            against the incoming shot. Has no effect when audio_bleed_ms is 0
         seam_fade_ms: Fade applied on each side of a seam that gets neither a
             crossfade nor a bleed. Defaults to the few milliseconds that keep a
             butt-join from clicking; raise it to a hundred or so for a graceful
@@ -199,7 +205,12 @@ def concat_videos(
         )
         if trim_samples == 0 and audio_bleed_ms:
             audio = bleed_join(
-                audio, waveform, sample_rate, audio_bleed_ms, seam_fade_ms
+                audio,
+                waveform,
+                sample_rate,
+                audio_bleed_ms,
+                seam_fade_ms,
+                audio_bleed_gain_db,
             )
         else:
             audio = equal_power_crossfade_join(
diff --git a/tests/test_audio_utils.py b/tests/test_audio_utils.py
index 99918ead..c0abf7e7 100644
--- a/tests/test_audio_utils.py
+++ b/tests/test_audio_utils.py
@@ -324,6 +324,38 @@ def test_mono_is_tiled_up_to_match_stereo(self):
 
         assert bleed_join(previous, following, 100, 500).shape == (2, 200)
 
+    def test_gain_db_scales_the_bled_tail(self):
+        previous = numpy.full((1, 100), 0.5, dtype=numpy.float32)
+        following = numpy.zeros((1, 100), dtype=numpy.float32)
+
+        full = bleed_join(previous, following, 100, 500, gain_db=0.0)
+        ducked = bleed_join(previous, following, 100, 500, gain_db=-6.0)
+
+        assert ducked[0, 100] == pytest.approx(
+            full[0, 100] * 10 ** (-6.0 / 20.0), abs=1e-3
+        )
+
+    def test_tonal_material_warns(self, caplog):
+        # a pure tone concentrates its spectrum in one bin - low flatness
+        t = numpy.arange(400) / 100.0
+        previous = numpy.sin(2 * numpy.pi * 5 * t).astype(numpy.float32)[None, :]
+        following = numpy.zeros((1, 400), dtype=numpy.float32)
+
+        with caplog.at_level("WARNING"):
+            bleed_join(previous, following, 100, 500)
+
+        assert "tonal" in caplog.text or "speech" in caplog.text
+
+    def test_noise_like_material_does_not_warn(self, caplog):
+        rng = numpy.random.default_rng(0)
+        previous = rng.normal(0, 0.2, (1, 400)).astype(numpy.float32)
+        following = numpy.zeros((1, 400), dtype=numpy.float32)
+
+        with caplog.at_level("WARNING"):
+            bleed_join(previous, following, 100, 500)
+
+        assert "tonal" not in caplog.text
+
 
 class TestResampleAudio:
     def test_it_scales_the_length_to_the_new_rate(self):

From 392fc0b57b2b88f390597fd62ff0b75a5404f6ff Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Thu, 17 Sep 2026 14:02:33 -0500
Subject: [PATCH 10/77] docs(mcp): #201 - name workspace isolation explicitly
 in the path-refusal message

The refusal for a bare path outside every allowed root read like a generic
path-traversal error, giving no hint that a path into another workspace's
own directories is refused by the same, deliberate per-workspace isolation
rather than an oversight. Names that intent and points at
keep_output(shared=True) as the deliberate way to move a file across the
boundary when that's genuinely needed.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 dw/locations.py | 14 ++++++++++----
 1 file changed, 10 insertions(+), 4 deletions(-)

diff --git a/dw/locations.py b/dw/locations.py
index 3b17eb93..4050522d 100644
--- a/dw/locations.py
+++ b/dw/locations.py
@@ -149,10 +149,16 @@ def validate_media_path(
             raise PathTraversalError(
                 f"Refusing to read {what} at '{location}': it resolves "
                 f"outside every directory this workflow may read "
-                f"({', '.join(roots) or 'none configured'}). Put the file in "
-                f"the asset library and name it with an 'asset:' reference, "
-                f"or pass --trust-workflows if you trust this workflow's "
-                f"source."
+                f"({', '.join(roots) or 'none configured'}). This includes "
+                f"another workspace's own directories - each workspace is "
+                f"isolated by design, not just a generic path-traversal "
+                f"refusal, so a bare path into one is refused the same way "
+                f"a path outside the installation entirely would be. Put "
+                f"the file in the asset library and name it with an "
+                f"'asset:' reference, use keep_output(shared=True) to copy "
+                f"a generated file into the library every workspace shares "
+                f"if it needs to cross that boundary on purpose, or pass "
+                f"--trust-workflows if you trust this workflow's source."
             )
 
     if require_exists and not os.path.exists(resolved):

From aebda18e999bdb9558a887ec814fe72ebbefcc81 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Thu, 17 Sep 2026 14:16:28 -0500
Subject: [PATCH 11/77] fix(video): #197 - make _fit_audio_to_frames
 tensor-aware for in-memory audio

The earlier #197 fix called _fit_audio_to_frames on in-memory pipeline
audio, which can still be a torch tensor on its generating device (e.g.
CUDA). The padding branch used numpy.pad unconditionally, which raises
on a torch tensor - breaking every in-memory audio+video save, including
the stock templates/ltx2/text-to-video template. The trim branch already
worked for both types via slicing; only the pad branch needed a
torch.nn.functional.pad path.

Also splits the existing regression test in two: the original only
exercised the trim branch (audio longer than expected), so it passed
even before this fix and never caught the pad-branch crash. A new case
covers audio shorter than expected, which hits the previously-broken
pad path.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 dw/tasks/video_utils.py |  7 +++++++
 tests/test_result.py    | 17 ++++++++++++++++-
 2 files changed, 23 insertions(+), 1 deletion(-)

diff --git a/dw/tasks/video_utils.py b/dw/tasks/video_utils.py
index 8bd90230..d0271305 100644
--- a/dw/tasks/video_utils.py
+++ b/dw/tasks/video_utils.py
@@ -393,6 +393,11 @@ def _fit_audio_to_frames(audio, frame_count, frame_rate, sample_rate):
     Only when the difference is codec padding. A track that genuinely runs to
     a different length than the picture - a song laid over a short clip - is
     left alone.
+
+    `audio` may be a numpy array (the decode path) or a torch tensor still on
+    its generating device (an in-memory pipeline output, #197) - the pad and
+    trim below keep whichever type and device it arrived with rather than
+    forcing a host round trip the caller may not want yet.
     """
     expected = round(frame_count / frame_rate * sample_rate)
     difference = audio.shape[1] - expected
@@ -404,4 +409,6 @@ def _fit_audio_to_frames(audio, frame_count, frame_rate, sample_rate):
     )
     if difference > 0:
         return audio[:, :expected]
+    if isinstance(audio, torch.Tensor):
+        return torch.nn.functional.pad(audio, (0, -difference))
     return numpy.pad(audio, ((0, 0), (0, -difference)))
diff --git a/tests/test_result.py b/tests/test_result.py
index c966e52f..600c6061 100644
--- a/tests/test_result.py
+++ b/tests/test_result.py
@@ -610,7 +610,7 @@ def test_audio_is_muxed_into_the_video(self):
         assert arguments["audio_sample_rate"] == 48000
         assert arguments["output_path"].endswith(".mp4")
 
-    def test_audio_is_fit_to_frame_count_for_in_memory_generation(self):
+    def test_audio_is_trimmed_to_frame_count_for_in_memory_generation(self):
         # #197: a shot generated in memory via previous_result: chaining never
         # passes through _decode_audio_video, so codec-padding drift between
         # the audio and the frame count has to be trimmed here instead.
@@ -622,6 +622,21 @@ def test_audio_is_fit_to_frame_count_for_in_memory_generation(self):
 
         assert encode.call_args.kwargs["audio"].shape == (2, 2000)
 
+    def test_audio_is_padded_to_frame_count_for_in_memory_generation(self):
+        # #197 reopened: the trim path above happened to work on a torch
+        # tensor because slicing is type-agnostic, but the pad path used
+        # numpy.pad unconditionally and crashed on a real (GPU) torch tensor
+        # - so every in-memory audio+video save that came up short failed
+        # outright rather than being fit. A CPU tensor reproduces the same
+        # numpy.pad TypeError, since the bug was the type, not the device.
+        frames = ["frame"] * 48
+        audio = torch.zeros((2, 1900))  # 48 frames @ 24fps @ 1000Hz -> 2000
+        artifact = AudioVideo(frames, audio, 1000)
+
+        encode, _ = self.save({"content_type": "video/mp4", "fps": 24}, artifact)
+
+        assert encode.call_args.kwargs["audio"].shape == (2, 2000)
+
     def test_result_definition_overrides_the_sample_rate(self):
         artifact = AudioVideo("frames", torch.zeros((2, 100)), 48000)
 

From 15e99213aba74172f1a3a9f79d46d41aa57016e1 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Thu, 17 Sep 2026 14:32:38 -0500
Subject: [PATCH 12/77] fix(audio): #198 - detect speech/tonal bleed tails at
 native rate

bleed_join's tonal-detection warning (added for #197/#198/#199) used
plain spectral flatness on the outgoing tail at whatever rate it had
been resampled to for the join. Two bugs followed: upsampling's own
band-limited interpolation leaves near-silence above the source
Nyquist, which depresses flatness and reads as spuriously tonal on
genuine ambient beds regardless of content; and flatness alone misses
real speech, since a vowel's formants spread energy broadly enough to
read similar to noise.

_spectral_flatness now takes the tail's native_sample_rate and limits
its spectrum to bins below the native Nyquist when the tail was
upsampled, so resampling can no longer read as tonal by itself. A new
_harmonicity measure (autocorrelation peak in the 60-500 Hz
fundamental range) is OR'd with flatness, since it is insensitive to
how broadly a periodic signal's spectrum happens to spread and so
catches voiced speech that flatness misses. concat_videos.py tracks
each join's true native rate explicitly (audio_native_rate), since
bleed_join never shortens 'previous' and the tail's source video is
not always videos[index - 1].

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 dw/tasks/audio_utils.py   | 96 +++++++++++++++++++++++++++++++++++----
 dw/tasks/concat_videos.py |  4 ++
 tests/test_audio_utils.py | 66 +++++++++++++++++++++++++++
 3 files changed, 157 insertions(+), 9 deletions(-)

diff --git a/dw/tasks/audio_utils.py b/dw/tasks/audio_utils.py
index b56b00b7..fc8980c7 100644
--- a/dw/tasks/audio_utils.py
+++ b/dw/tasks/audio_utils.py
@@ -118,20 +118,88 @@ def equal_power_crossfade_join(
 # bleed is meant for
 TONAL_FLATNESS_THRESHOLD = 0.3
 
+# Above this, the tail's waveform repeats closely enough within a plausible
+# pitch period to be voiced speech or a pitched note rather than noise -
+# a bandwidth-insensitive companion to flatness, since a resample's own
+# band limiting does not touch how periodic the waveform is (#198)
+HARMONICITY_THRESHOLD = 0.45
 
-def _spectral_flatness(waveform):
+# Typical fundamental range for a human voice or a pitched instrument note;
+# the periodicity search only looks at lags in this range so a slow room-tone
+# swell or hum near DC cannot register as a pitch
+_PERIODICITY_MIN_HZ = 60.0
+_PERIODICITY_MAX_HZ = 500.0
+
+
+def _spectral_flatness(waveform, sample_rate=None, native_sample_rate=None):
     """Geometric-mean-over-arithmetic-mean of the magnitude spectrum, averaged
     across channels - near 0 for tonal/speech material, near 1 for noise-like
-    material (see TONAL_FLATNESS_THRESHOLD)."""
+    material (see TONAL_FLATNESS_THRESHOLD).
+
+    When the material was upsampled, band-limited interpolation leaves near
+    zero energy above the original Nyquist - a large near-silent band that
+    depresses the geometric mean relative to the arithmetic one regardless of
+    what the material actually is, reading as spuriously tonal (#198). Given
+    both rates, the spectrum is limited to bins below the native Nyquist so an
+    upsampled tail is measured the same as it would be at its own rate.
+    """
     spectrum = numpy.abs(numpy.fft.rfft(waveform, axis=1))
+    if (
+        sample_rate
+        and native_sample_rate
+        and native_sample_rate < sample_rate
+    ):
+        native_bins = max(
+            2,
+            int(spectrum.shape[1] * native_sample_rate / sample_rate),
+        )
+        spectrum = spectrum[:, :native_bins]
     spectrum = numpy.maximum(spectrum, 1e-10)
     geometric_mean = numpy.exp(numpy.mean(numpy.log(spectrum), axis=1))
     arithmetic_mean = numpy.mean(spectrum, axis=1)
     return float(numpy.mean(geometric_mean / arithmetic_mean))
 
 
+def _harmonicity(waveform, sample_rate):
+    """Normalized autocorrelation peak within a plausible pitch range,
+    averaged across channels - near 1 for a strongly periodic signal (voiced
+    speech, a pitched note), near 0 for noise (see HARMONICITY_THRESHOLD).
+
+    Spectral flatness alone missed real speech (#198): a vowel's formants
+    spread its energy broadly enough across the band that flatness reads
+    similar to noise, even though the waveform itself repeats every pitch
+    period. Autocorrelation measures that repetition directly and is
+    insensitive to how the spectrum happens to be shaped, so it catches what
+    flatness cannot.
+    """
+    min_lag = max(int(sample_rate / _PERIODICITY_MAX_HZ), 1)
+    max_lag = min(int(sample_rate / _PERIODICITY_MIN_HZ), waveform.shape[1] - 1)
+    if max_lag <= min_lag:
+        return 0.0
+
+    scores = []
+    for channel in waveform:
+        centered = channel - channel.mean()
+        energy = float(numpy.dot(centered, centered))
+        if energy <= 1e-12:
+            continue
+        correlation = numpy.correlate(centered, centered, mode="full")
+        zero_lag = correlation.shape[0] // 2
+        window = correlation[zero_lag + min_lag : zero_lag + max_lag + 1]
+        if window.size == 0:
+            continue
+        scores.append(float(numpy.max(window) / energy))
+    return max(scores) if scores else 0.0
+
+
 def bleed_join(
-    previous, following, sample_rate, bleed_ms, seam_fade_ms=None, gain_db=0.0
+    previous,
+    following,
+    sample_rate,
+    bleed_ms,
+    seam_fade_ms=None,
+    gain_db=0.0,
+    native_sample_rate=None,
 ):
     """Butt-join two waveforms, ringing the outgoing tail on across the seam.
 
@@ -163,6 +231,12 @@ def bleed_join(
             negative ducks a tail that would otherwise push the seam over
             0 dBFS; 0 (the default) is unchanged, full-scale, the prior
             behavior
+        native_sample_rate: The rate the outgoing tail was actually recorded
+            or generated at, when that differs from sample_rate because the
+            caller upsampled it to join. Band-limits the flatness check to
+            below the tail's own Nyquist, so upsampling's near-silent high
+            band cannot itself read as tonal (#198). Omit when the tail is
+            already at its native rate
 
     Returns:
         The two waveforms joined, of their full combined length
@@ -179,17 +253,21 @@ def bleed_join(
 
     tail = previous[:, ::-1][:, :window]
 
-    flatness = _spectral_flatness(previous[:, -window:])
-    if flatness < TONAL_FLATNESS_THRESHOLD:
+    tail_source = previous[:, -window:]
+    flatness = _spectral_flatness(tail_source, sample_rate, native_sample_rate)
+    harmonicity = _harmonicity(tail_source, native_sample_rate or sample_rate)
+    if flatness < TONAL_FLATNESS_THRESHOLD or harmonicity > HARMONICITY_THRESHOLD:
         emit_warning(
             f"bleed_join: the tail being reversed onto the seam looks tonal or "
-            f"speech-like (spectral flatness {flatness:.2f}) rather than the "
-            f"room tone or crowd noise a bleed is meant for - the reversal is "
-            f"likely to be audible as a stutter or a note running backwards. "
-            f"Consider seam_fade_ms for a hard cut on this material instead.",
+            f"speech-like (spectral flatness {flatness:.2f}, harmonicity "
+            f"{harmonicity:.2f}) rather than the room tone or crowd noise a "
+            f"bleed is meant for - the reversal is likely to be audible as a "
+            f"stutter or a note running backwards. Consider seam_fade_ms for "
+            f"a hard cut on this material instead.",
             kind="bleed_tonal_material",
             command="bleed_join",
             flatness=round(flatness, 3),
+            harmonicity=round(harmonicity, 3),
         )
 
     decay, _ = _equal_power_ramps(window)  # cos: 1 down to ~0
diff --git a/dw/tasks/concat_videos.py b/dw/tasks/concat_videos.py
index 61aed5b9..4a838f0f 100644
--- a/dw/tasks/concat_videos.py
+++ b/dw/tasks/concat_videos.py
@@ -182,6 +182,7 @@ def concat_videos(
 
     frames = []
     audio = None
+    audio_native_rate = None
 
     for index, (video, clip) in enumerate(zip(videos, clips)):
         head_trim = trim_frames if index > 0 else 0
@@ -193,6 +194,7 @@ def concat_videos(
         waveform = waveforms[index]
         if audio is None:
             audio = waveform
+            audio_native_rate = video.sample_rate
             continue
 
         if head_trim > 0 and fps is None:
@@ -211,6 +213,7 @@ def concat_videos(
                 audio_bleed_ms,
                 seam_fade_ms,
                 audio_bleed_gain_db,
+                native_sample_rate=audio_native_rate,
             )
         else:
             audio = equal_power_crossfade_join(
@@ -221,6 +224,7 @@ def concat_videos(
                 crossfade_ms,
                 seam_fade_ms,
             )
+        audio_native_rate = video.sample_rate
 
     logger.debug(f"Concatenated {len(videos)} videos into {len(frames)} frames")
     # The rate the caller declared, else the rate the first input carries -
diff --git a/tests/test_audio_utils.py b/tests/test_audio_utils.py
index c0abf7e7..8803bd1b 100644
--- a/tests/test_audio_utils.py
+++ b/tests/test_audio_utils.py
@@ -15,6 +15,7 @@
     frames_to_samples,
     load_audio,
     resample_audio,
+    resample_waveform,
     slice_samples,
 )
 
@@ -356,6 +357,71 @@ def test_noise_like_material_does_not_warn(self, caplog):
 
         assert "tonal" not in caplog.text
 
+    def test_native_rate_speech_like_material_warns_via_harmonicity(self, caplog):
+        # broadband formants keep flatness high (noise-like), so only a
+        # periodicity measure catches this as voiced speech (#198)
+        sample_rate = 24000
+        n = int(sample_rate * 0.3)
+        t = numpy.arange(n) / sample_rate
+        rng = numpy.random.default_rng(1)
+        f0 = 150.0
+        harmonics = [1.0, 0.6, 0.45, 0.3, 0.2, 0.12]
+        speech_like = sum(
+            amp * numpy.sin(2 * numpy.pi * f0 * (k + 1) * t + rng.uniform(0, 2 * numpy.pi))
+            for k, amp in enumerate(harmonics)
+        )
+        speech_like = speech_like + rng.normal(0, 0.25, n)
+        speech_like = (speech_like / numpy.abs(speech_like).max()).astype(numpy.float32)
+        previous = speech_like[None, :]
+        following = numpy.zeros((1, n), dtype=numpy.float32)
+
+        with caplog.at_level("WARNING"):
+            bleed_join(previous, following, sample_rate, 300)
+
+        assert "tonal" in caplog.text or "speech" in caplog.text
+
+    def test_native_rate_noise_does_not_warn_at_speech_rate(self, caplog):
+        # regression guard: harmonicity must not itself become a false
+        # positive source for genuine noise at a realistic sample rate
+        sample_rate = 24000
+        n = int(sample_rate * 0.3)
+        rng = numpy.random.default_rng(1)
+        previous = rng.normal(0, 0.2, (1, n)).astype(numpy.float32)
+        following = numpy.zeros((1, n), dtype=numpy.float32)
+
+        with caplog.at_level("WARNING"):
+            bleed_join(previous, following, sample_rate, 300)
+
+        assert "tonal" not in caplog.text
+        assert "speech" not in caplog.text
+
+    def test_upsampled_noise_does_not_falsely_warn_when_native_rate_given(
+        self, caplog
+    ):
+        # band-limited interpolation leaves near-silence above the tail's own
+        # Nyquist, which used to depress flatness and read as spuriously
+        # tonal purely because of the resample - not because of the content
+        # (#198)
+        native_rate = 16000
+        target_rate = 48000
+        n = int(native_rate * 0.3)
+        rng = numpy.random.default_rng(2)
+        noise = rng.normal(0, 0.2, (1, n)).astype(numpy.float32)
+        upsampled = resample_waveform(noise, native_rate, target_rate)
+        following = numpy.zeros_like(upsampled)
+
+        with caplog.at_level("WARNING"):
+            bleed_join(
+                upsampled,
+                following,
+                target_rate,
+                300,
+                native_sample_rate=native_rate,
+            )
+
+        assert "tonal" not in caplog.text
+        assert "speech" not in caplog.text
+
 
 class TestResampleAudio:
     def test_it_scales_the_length_to_the_new_rate(self):

From 1786a92ad2993d56b7c705a6798b59aabca33ed6 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Thu, 17 Sep 2026 14:58:35 -0500
Subject: [PATCH 13/77] fix(audio): #200/#207 - add compress_audio,
 filter_audio, analyze_audio tasks

compress_audio is an envelope-follower dynamics processor covering
compressor/limiter/gate through one `mode` argument. filter_audio runs a
track through a single RBJ-cookbook biquad stage (lowpass/highpass/
bandpass/notch). analyze_audio reads a track's peak/RMS/crest-factor and
a rough low/mid/high spectral balance without changing it, so its output
feeds directly into tuning the other two rather than guessing knob values.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 docs/TASKS.md             |  91 +++++++++++++
 dw/task_domains.py        |  11 ++
 dw/tasks/audio_utils.py   | 261 ++++++++++++++++++++++++++++++++++++++
 dw/tasks/task.py          |  29 +++++
 tests/test_audio_utils.py | 253 ++++++++++++++++++++++++++++++++++++
 5 files changed, 645 insertions(+)

diff --git a/docs/TASKS.md b/docs/TASKS.md
index 139c5ff1..082b4f40 100644
--- a/docs/TASKS.md
+++ b/docs/TASKS.md
@@ -741,6 +741,97 @@ into the next without the rate being restated: a `resample_audio` fed
 
 **Example:** [assemble-and-score.json](../workflows/templates/assemble-and-score.json)
 
+### compress_audio
+
+Shape a track's dynamics with an envelope-follower - a compressor, a limiter
+and a gate are the same algorithm with different knob settings, so one task
+covers all three through `mode`:
+
+```json
+{
+    "task": {
+        "command": "compress_audio",
+        "arguments": {
+            "audio": "previous_result:mixed",
+            "threshold_dbfs": -18.0,
+            "ratio": 4.0,
+            "attack_ms": 10,
+            "release_ms": 100,
+            "sample_rate": 44100
+        }
+    }
+}
+```
+
+| Argument | Required | Description |
+| -------- | -------- | ----------- |
+| `audio` | Yes | Path or URL of an audio file (or of a video file, whose soundtrack is taken), a waveform from a previous step, or an earlier step's video generated with a soundtrack (which brings its sample rate along) |
+| `threshold_dbfs` | Yes | The level the envelope is measured against, in dB below full scale. Cannot be above 0 |
+| `ratio` | No | How hard the reduction is above the threshold, in `compress`/`gate` mode (default: 4.0). Ignored in `limit` mode, which always holds the signal at the threshold |
+| `attack_ms` | No | How fast the envelope rises to a louder signal (default: 10.0). 0 means instantly |
+| `release_ms` | No | How fast the envelope falls back after a louder signal ends (default: 100.0). 0 means instantly |
+| `mode` | No | `compress` (turn down what's above the threshold), `limit` (hold the signal at the threshold), or `gate` (turn down what's below the threshold) (default: `compress`) |
+| `sample_rate` | With a waveform | Sample rate of a directly passed waveform (files carry their own) |
+
+A silent track is returned unchanged.
+
+### filter_audio
+
+Run a track through a single biquad filter stage - trimming the frequencies a
+mix doesn't need, or carving out room for another element:
+
+```json
+{
+    "task": {
+        "command": "filter_audio",
+        "arguments": {
+            "audio": "previous_result:world",
+            "cutoff_hz": 120,
+            "kind": "highpass",
+            "sample_rate": 44100
+        }
+    }
+}
+```
+
+| Argument | Required | Description |
+| -------- | -------- | ----------- |
+| `audio` | Yes | Path or URL of an audio file (or of a video file, whose soundtrack is taken), a waveform from a previous step, or an earlier step's video generated with a soundtrack (which brings its sample rate along) |
+| `cutoff_hz` | Yes | The filter's corner frequency. Must be below the Nyquist frequency (half the sample rate) |
+| `kind` | No | `lowpass`, `highpass`, `bandpass`, or `notch` (default: `lowpass`) |
+| `q` | No | The filter's resonance/bandwidth (default: 0.707, a Butterworth response) |
+| `sample_rate` | With a waveform | Sample rate of a directly passed waveform (files carry their own) |
+
+A silent track is returned unchanged.
+
+### analyze_audio
+
+Measure a track without changing it - peak and RMS level, crest factor, and a
+rough low/mid/high spectral balance, the numbers a `compress_audio` or
+`filter_audio` step downstream is tuned against rather than guessed at:
+
+```json
+{
+    "task": {
+        "command": "analyze_audio",
+        "arguments": {
+            "audio": "previous_result:mixed",
+            "sample_rate": 44100
+        }
+    }
+}
+```
+
+| Argument | Required | Description |
+| -------- | -------- | ----------- |
+| `audio` | Yes | Path or URL of an audio file (or of a video file, whose soundtrack is taken), a waveform from a previous step, or an earlier step's video generated with a soundtrack (which brings its sample rate along) |
+| `sample_rate` | With a waveform | Sample rate of a directly passed waveform (files carry their own) |
+
+Returns a dict, not a track: `peak_dbfs`, `rms_dbfs`, `crest_factor_db`,
+`low_dbfs` (20-250 Hz), `mid_dbfs` (250-4000 Hz), `high_dbfs` (4000-20000 Hz).
+A silent track, or a band with no content at the track's sample rate, reads as
+`null` rather than `-inf`.
+
 ## Data Gathering
 
 ### gather_images
diff --git a/dw/task_domains.py b/dw/task_domains.py
index 9bbd36e9..fc7f6704 100644
--- a/dw/task_domains.py
+++ b/dw/task_domains.py
@@ -102,6 +102,17 @@
         "fade_out_frames": NON_NEGATIVE,
         "fps": POSITIVE,
     },
+    "compress_audio": {
+        "ratio": POSITIVE,
+        "attack_ms": NON_NEGATIVE,
+        "release_ms": NON_NEGATIVE,
+        "sample_rate": POSITIVE,
+    },
+    "filter_audio": {
+        "cutoff_hz": POSITIVE,
+        "sample_rate": POSITIVE,
+    },
+    "analyze_audio": {"sample_rate": POSITIVE},
 }
 
 
diff --git a/dw/tasks/audio_utils.py b/dw/tasks/audio_utils.py
index fc8980c7..40b1581f 100644
--- a/dw/tasks/audio_utils.py
+++ b/dw/tasks/audio_utils.py
@@ -1200,3 +1200,264 @@ def _warn_on_rate_override(command, actual_rate, given_rate):
         file_rate=actual_rate,
         given_rate=given_rate,
     )
+
+
+COMPRESS_MODES = ("compress", "limit", "gate")
+
+# A floor below which an envelope is treated as digital silence, so its dBFS
+# reading is a large negative number rather than -inf
+_ENVELOPE_FLOOR_DBFS = -120.0
+_ENVELOPE_FLOOR_LINEAR = 10.0 ** (_ENVELOPE_FLOOR_DBFS / 20.0)
+
+
+def compress_audio(
+    audio, threshold_dbfs, ratio=4.0, attack_ms=10.0, release_ms=100.0, mode="compress", sample_rate=None
+):
+    """Task command: shape a track's dynamics with an envelope-follower.
+
+    A compressor, a limiter and a gate are the same envelope-follower
+    algorithm with different knob settings: a limiter is a ratio pushed
+    toward infinity with a fast attack, and a gate is downward expansion
+    below the threshold rather than compression above it - so one command
+    covers all three through 'mode' rather than three near-duplicate ones.
+
+    Args:
+        audio: Path or URL of an audio file (or of a video file, whose
+            soundtrack is taken), a video generated with a
+            soundtrack, or a waveform (which needs sample_rate alongside it)
+        threshold_dbfs: The level, in dB below full scale, above which
+            'compress'/'limit' reduce gain, or below which 'gate' does
+        ratio: How strongly gain is reduced past the threshold. Unused by
+            'limit', which reduces enough to hold the signal at the
+            threshold regardless
+        attack_ms: How fast the envelope follows a rise in level
+        release_ms: How fast the envelope follows a fall in level
+        mode: 'compress' (downward compression above threshold), 'limit'
+            (holds the signal at threshold), or 'gate' (downward expansion
+            below threshold)
+        sample_rate: Sample rate of a waveform passed directly
+
+    Returns:
+        An AudioTrack holding the processed waveform and its rate
+    """
+    waveform, sample_rate = _waveform_and_rate(audio, sample_rate, "compress_audio")
+    check_arguments(
+        "compress_audio",
+        ratio=ratio,
+        attack_ms=attack_ms,
+        release_ms=release_ms,
+        sample_rate=sample_rate,
+    )
+    if mode not in COMPRESS_MODES:
+        raise ValueError(
+            f"compress_audio mode must be one of {COMPRESS_MODES}, got {mode!r}"
+        )
+    if threshold_dbfs > 0:
+        raise ValueError(
+            "compress_audio 'threshold_dbfs' cannot be above full scale (0)"
+        )
+    if waveform.size == 0:
+        return _as_track(waveform, sample_rate, "compress_audio")
+
+    envelope = _follow_envelope(waveform, sample_rate, attack_ms, release_ms)
+    envelope_dbfs = 20.0 * numpy.log10(
+        numpy.maximum(envelope, _ENVELOPE_FLOOR_LINEAR)
+    )
+
+    if mode == "gate":
+        past_threshold = numpy.maximum(0.0, threshold_dbfs - envelope_dbfs)
+    else:
+        past_threshold = numpy.maximum(0.0, envelope_dbfs - threshold_dbfs)
+
+    if mode == "limit":
+        reduction_db = past_threshold
+    else:
+        reduction_db = past_threshold * (1.0 - 1.0 / ratio)
+
+    gain = (10.0 ** (-reduction_db / 20.0)).astype(numpy.float32)
+    processed = (waveform * gain[numpy.newaxis, :]).astype(numpy.float32)
+    return _as_track(processed, sample_rate, "compress_audio")
+
+
+def _follow_envelope(waveform, sample_rate, attack_ms, release_ms):
+    """A linked (all-channels) peak envelope, smoothed by separate attack and
+    release time constants - the same detector a hardware compressor uses,
+    tracking the loudest channel so a stereo image does not shift."""
+    rectified = numpy.abs(waveform).max(axis=0)
+    attack_coef = _time_constant_coef(attack_ms, sample_rate)
+    release_coef = _time_constant_coef(release_ms, sample_rate)
+    envelope = numpy.empty_like(rectified)
+    level = 0.0
+    for i in range(rectified.shape[0]):
+        sample = float(rectified[i])
+        coef = attack_coef if sample > level else release_coef
+        level = coef * level + (1.0 - coef) * sample
+        envelope[i] = level
+    return envelope
+
+
+def _time_constant_coef(time_ms, sample_rate):
+    """The per-sample smoothing coefficient for an exponential time constant.
+    0 ms means the envelope follows instantly, with no smoothing at all."""
+    if time_ms <= 0:
+        return 0.0
+    return float(numpy.exp(-1.0 / (time_ms / 1000.0 * sample_rate)))
+
+
+FILTER_KINDS = ("lowpass", "highpass", "bandpass", "notch")
+
+
+def filter_audio(audio, cutoff_hz, kind="lowpass", q=0.707, sample_rate=None):
+    """Task command: run a track through a single biquad filter stage.
+
+    Args:
+        audio: Path or URL of an audio file (or of a video file, whose
+            soundtrack is taken), a video generated with a
+            soundtrack, or a waveform (which needs sample_rate alongside it)
+        cutoff_hz: The filter's corner (lowpass/highpass) or center
+            (bandpass/notch) frequency
+        kind: 'lowpass', 'highpass', 'bandpass', or 'notch'
+        q: Resonance/bandwidth of the filter. Higher narrows a bandpass or
+            notch, and peaks the corner of a lowpass or highpass
+        sample_rate: Sample rate of a waveform passed directly
+
+    Returns:
+        An AudioTrack holding the filtered waveform and its rate
+    """
+    waveform, sample_rate = _waveform_and_rate(audio, sample_rate, "filter_audio")
+    check_arguments("filter_audio", cutoff_hz=cutoff_hz, sample_rate=sample_rate)
+    if kind not in FILTER_KINDS:
+        raise ValueError(
+            f"filter_audio kind must be one of {FILTER_KINDS}, got {kind!r}"
+        )
+    if q <= 0:
+        raise ValueError("filter_audio 'q' must be above zero")
+    nyquist = sample_rate / 2.0
+    if cutoff_hz >= nyquist:
+        raise ValueError(
+            f"filter_audio 'cutoff_hz' ({cutoff_hz}) must be below the "
+            f"Nyquist frequency ({nyquist}) for sample_rate {sample_rate}"
+        )
+    if waveform.size == 0:
+        return _as_track(waveform, sample_rate, "filter_audio")
+
+    b, a = _biquad_coefficients(kind, cutoff_hz, q, sample_rate)
+    filtered = numpy.stack(
+        [_apply_biquad(channel, b, a) for channel in waveform]
+    ).astype(numpy.float32)
+    return _as_track(filtered, sample_rate, "filter_audio")
+
+
+def _biquad_coefficients(kind, cutoff_hz, q, sample_rate):
+    """RBJ Audio EQ Cookbook coefficients for a single biquad stage,
+    normalized so a0 is 1."""
+    w0 = 2.0 * numpy.pi * cutoff_hz / sample_rate
+    cos_w0 = numpy.cos(w0)
+    sin_w0 = numpy.sin(w0)
+    alpha = sin_w0 / (2.0 * q)
+
+    if kind == "lowpass":
+        b0 = (1.0 - cos_w0) / 2.0
+        b1 = 1.0 - cos_w0
+        b2 = (1.0 - cos_w0) / 2.0
+    elif kind == "highpass":
+        b0 = (1.0 + cos_w0) / 2.0
+        b1 = -(1.0 + cos_w0)
+        b2 = (1.0 + cos_w0) / 2.0
+    elif kind == "bandpass":
+        b0 = alpha
+        b1 = 0.0
+        b2 = -alpha
+    else:  # notch
+        b0 = 1.0
+        b1 = -2.0 * cos_w0
+        b2 = 1.0
+    a0 = 1.0 + alpha
+    a1 = -2.0 * cos_w0
+    a2 = 1.0 - alpha
+    return (
+        numpy.array([b0, b1, b2], dtype=numpy.float64) / a0,
+        numpy.array([a1, a2], dtype=numpy.float64) / a0,
+    )
+
+
+def _apply_biquad(channel, b, a):
+    """Direct Form I second-order section, sample by sample - the feedback
+    a biquad needs cannot be vectorized away."""
+    out = numpy.empty_like(channel, dtype=numpy.float64)
+    b0, b1, b2 = b
+    a1, a2 = a
+    x1 = x2 = y1 = y2 = 0.0
+    for i in range(channel.shape[0]):
+        x0 = float(channel[i])
+        y0 = b0 * x0 + b1 * x1 + b2 * x2 - a1 * y1 - a2 * y2
+        out[i] = y0
+        x2, x1 = x1, x0
+        y2, y1 = y1, y0
+    return out
+
+
+_SPECTRAL_BANDS = {
+    "low_dbfs": (20.0, 250.0),
+    "mid_dbfs": (250.0, 4000.0),
+    "high_dbfs": (4000.0, 20000.0),
+}
+
+
+def analyze_audio(audio, sample_rate=None):
+    """Task command: measure a track without changing it.
+
+    Read-only: the waveform passes through unmodified, and what comes back
+    is diagnostics rather than an AudioTrack, since there is no processed
+    track to hand a later step. Meant to feed a decision earlier in a
+    workflow (whether 'compress_audio' or 'filter_audio' is needed, and
+    with what settings) rather than to sit in the middle of a chain.
+
+    Args:
+        audio: Path or URL of an audio file (or of a video file, whose
+            soundtrack is taken), a video generated with a
+            soundtrack, or a waveform (which needs sample_rate alongside it)
+        sample_rate: Sample rate of a waveform passed directly
+
+    Returns:
+        A dict: peak_dbfs, rms_dbfs, crest_factor_db (peak minus rms), and
+        a rough low_dbfs/mid_dbfs/high_dbfs spectral-balance reading. Any
+        value is None where a silent track leaves it undefined.
+    """
+    waveform, sample_rate = _waveform_and_rate(audio, sample_rate, "analyze_audio")
+    check_arguments("analyze_audio", sample_rate=sample_rate)
+
+    peak_dbfs = level_dbfs(waveform, measure="peak")
+    rms_dbfs = level_dbfs(waveform, measure="rms")
+    crest_factor_db = (
+        peak_dbfs - rms_dbfs if peak_dbfs is not None and rms_dbfs is not None else None
+    )
+    bands = _spectral_balance(waveform, sample_rate)
+    return {
+        "peak_dbfs": peak_dbfs,
+        "rms_dbfs": rms_dbfs,
+        "crest_factor_db": crest_factor_db,
+        **bands,
+    }
+
+
+def _spectral_balance(waveform, sample_rate):
+    """A rough low/mid/high energy reading in dBFS, from one FFT of the
+    channel-averaged track - not a spectrogram, just enough to say whether
+    a track leans bright or boomy."""
+    if waveform.size == 0:
+        return {name: None for name in _SPECTRAL_BANDS}
+    mono = waveform.mean(axis=0)
+    n = mono.shape[0]
+    spectrum = numpy.fft.rfft(mono)
+    amplitude = numpy.abs(spectrum) * (2.0 / n)
+    freqs = numpy.fft.rfftfreq(n, d=1.0 / sample_rate)
+    result = {}
+    for name, (low, high) in _SPECTRAL_BANDS.items():
+        band = amplitude[(freqs >= low) & (freqs < min(high, sample_rate / 2.0))]
+        if band.size == 0:
+            result[name] = None
+            continue
+        energy = float(numpy.sqrt(numpy.mean(numpy.square(band, dtype=numpy.float64))))
+        result[name] = 20.0 * numpy.log10(energy) if energy > 0.0 else None
+    return result
diff --git a/dw/tasks/task.py b/dw/tasks/task.py
index 789aaee5..ed8c9b1b 100644
--- a/dw/tasks/task.py
+++ b/dw/tasks/task.py
@@ -265,6 +265,35 @@ def _handle_mix_audio(task, arguments, previous_pipelines):
     return mix_audio(**arguments)
 
 
+@register_command(
+    "compress_audio", implementation="dw.tasks.audio_utils.compress_audio"
+)
+def _handle_compress_audio(task, arguments, previous_pipelines):
+    """Shape a track's dynamics with a compressor, limiter or gate"""
+    logger.debug("Compressing audio")
+    from .audio_utils import compress_audio
+
+    return compress_audio(**arguments)
+
+
+@register_command("filter_audio", implementation="dw.tasks.audio_utils.filter_audio")
+def _handle_filter_audio(task, arguments, previous_pipelines):
+    """Run a track through a single lowpass/highpass/bandpass/notch filter"""
+    logger.debug("Filtering audio")
+    from .audio_utils import filter_audio
+
+    return filter_audio(**arguments)
+
+
+@register_command("analyze_audio", implementation="dw.tasks.audio_utils.analyze_audio")
+def _handle_analyze_audio(task, arguments, previous_pipelines):
+    """Measure a track's levels and spectral balance without changing it"""
+    logger.debug("Analyzing audio")
+    from .audio_utils import analyze_audio
+
+    return analyze_audio(**arguments)
+
+
 @register_command("compose_text", implementation="dw.tasks.compose_text.compose_text")
 def _handle_compose_text(task, arguments, previous_pipelines):
     """Join parts written once into one block of text"""
diff --git a/tests/test_audio_utils.py b/tests/test_audio_utils.py
index 8803bd1b..34d18ce5 100644
--- a/tests/test_audio_utils.py
+++ b/tests/test_audio_utils.py
@@ -951,3 +951,256 @@ def test_a_video_given_a_different_rate_is_reported(self, tmp_path):
         assert len(warnings) == 1
         assert warnings[0]["file_rate"] == 8000
         assert warnings[0]["given_rate"] == 16000
+
+
+class TestCompressAudio:
+    """attack_ms=0/release_ms=0 makes the envelope track the signal
+    instantly, so the gain each sample lands at is exact rather than a
+    settling curve."""
+
+    def test_a_loud_signal_is_compressed_toward_the_threshold(self):
+        from dw.tasks.audio_utils import compress_audio
+
+        track = numpy.ones((1, 10), dtype=numpy.float32)
+
+        compressed = samples(
+            compress_audio(
+                track,
+                threshold_dbfs=-6.0,
+                ratio=4.0,
+                attack_ms=0,
+                release_ms=0,
+                sample_rate=100,
+            )
+        )
+
+        expected_gain = 10 ** (-(6.0 * (1 - 1 / 4.0)) / 20)
+        assert numpy.all(compressed == pytest.approx(expected_gain, abs=1e-5))
+
+    def test_limit_mode_holds_the_signal_at_the_threshold(self):
+        from dw.tasks.audio_utils import compress_audio
+
+        track = numpy.ones((1, 10), dtype=numpy.float32)
+
+        limited = samples(
+            compress_audio(
+                track,
+                threshold_dbfs=-6.0,
+                mode="limit",
+                attack_ms=0,
+                release_ms=0,
+                sample_rate=100,
+            )
+        )
+
+        assert numpy.all(limited == pytest.approx(10 ** (-6.0 / 20), abs=1e-5))
+
+    def test_gate_mode_attenuates_a_signal_below_the_threshold(self):
+        from dw.tasks.audio_utils import compress_audio
+
+        track = numpy.full((1, 10), 0.1, dtype=numpy.float32)
+
+        gated = samples(
+            compress_audio(
+                track,
+                threshold_dbfs=-6.0,
+                ratio=4.0,
+                mode="gate",
+                attack_ms=0,
+                release_ms=0,
+                sample_rate=100,
+            )
+        )
+
+        assert numpy.all(numpy.abs(gated) < 0.1)
+
+    def test_a_signal_under_the_threshold_passes_through_unchanged_in_compress_mode(
+        self,
+    ):
+        from dw.tasks.audio_utils import compress_audio
+
+        track = numpy.full((1, 10), 0.1, dtype=numpy.float32)
+
+        compressed = samples(
+            compress_audio(
+                track,
+                threshold_dbfs=-6.0,
+                attack_ms=0,
+                release_ms=0,
+                sample_rate=100,
+            )
+        )
+
+        assert numpy.all(compressed == pytest.approx(0.1, abs=1e-6))
+
+    def test_silence_is_left_alone(self):
+        from dw.tasks.audio_utils import compress_audio
+
+        assert numpy.all(
+            samples(
+                compress_audio(
+                    numpy.zeros((1, 10)), threshold_dbfs=-6.0, sample_rate=100
+                )
+            )
+            == 0
+        )
+
+    def test_the_input_is_not_modified(self):
+        from dw.tasks.audio_utils import compress_audio
+
+        track = numpy.ones((1, 10), dtype=numpy.float32)
+        compress_audio(track, threshold_dbfs=-6.0, sample_rate=100)
+
+        assert numpy.all(track == 1.0)
+
+    def test_an_unknown_mode_is_refused(self):
+        from dw.tasks.audio_utils import compress_audio
+
+        with pytest.raises(ValueError, match="mode"):
+            compress_audio(
+                numpy.ones((1, 10)), threshold_dbfs=-6.0, mode="squash", sample_rate=100
+            )
+
+    def test_a_threshold_above_full_scale_is_refused(self):
+        from dw.tasks.audio_utils import compress_audio
+
+        with pytest.raises(ValueError, match="full scale"):
+            compress_audio(numpy.ones((1, 10)), threshold_dbfs=1.0, sample_rate=100)
+
+    def test_a_waveform_needs_a_sample_rate(self):
+        from dw.tasks.audio_utils import compress_audio
+
+        with pytest.raises(ValueError, match="sample_rate"):
+            compress_audio(numpy.ones((1, 10)), threshold_dbfs=-6.0)
+
+
+class TestFilterAudio:
+    def tone(self, frequency, samples=2000, rate=8000, level=1.0):
+        t = numpy.arange(samples) / rate
+        return numpy.sin(2 * numpy.pi * frequency * t).astype(numpy.float32)[
+            numpy.newaxis, :
+        ] * level
+
+    def rms(self, waveform):
+        # skip the filter's brief settling transient
+        return float(numpy.sqrt(numpy.mean(numpy.square(waveform[:, 200:]))))
+
+    def test_lowpass_passes_low_frequencies_and_attenuates_high_ones(self):
+        from dw.tasks.audio_utils import filter_audio
+
+        low = self.tone(frequency=100)
+        high = self.tone(frequency=3500)
+
+        low_out = samples(
+            filter_audio(low, cutoff_hz=500, kind="lowpass", sample_rate=8000)
+        ).T
+        high_out = samples(
+            filter_audio(high, cutoff_hz=500, kind="lowpass", sample_rate=8000)
+        ).T
+
+        assert self.rms(low_out) > 0.6
+        assert self.rms(high_out) < 0.1
+
+    def test_highpass_passes_high_frequencies_and_attenuates_low_ones(self):
+        from dw.tasks.audio_utils import filter_audio
+
+        low = self.tone(frequency=100)
+        high = self.tone(frequency=3500)
+
+        low_out = samples(
+            filter_audio(low, cutoff_hz=1000, kind="highpass", sample_rate=8000)
+        ).T
+        high_out = samples(
+            filter_audio(high, cutoff_hz=1000, kind="highpass", sample_rate=8000)
+        ).T
+
+        assert self.rms(low_out) < 0.1
+        assert self.rms(high_out) > 0.6
+
+    def test_the_input_is_not_modified(self):
+        from dw.tasks.audio_utils import filter_audio
+
+        track = self.tone(frequency=440)
+        original = track.copy()
+        filter_audio(track, cutoff_hz=1000, sample_rate=8000)
+
+        assert numpy.array_equal(track, original)
+
+    def test_an_unknown_kind_is_refused(self):
+        from dw.tasks.audio_utils import filter_audio
+
+        with pytest.raises(ValueError, match="kind"):
+            filter_audio(
+                numpy.ones((1, 100)), cutoff_hz=100, kind="allpass", sample_rate=8000
+            )
+
+    def test_a_non_positive_q_is_refused(self):
+        from dw.tasks.audio_utils import filter_audio
+
+        with pytest.raises(ValueError, match="q"):
+            filter_audio(numpy.ones((1, 100)), cutoff_hz=100, q=0, sample_rate=8000)
+
+    def test_a_cutoff_at_or_above_nyquist_is_refused(self):
+        from dw.tasks.audio_utils import filter_audio
+
+        with pytest.raises(ValueError, match="Nyquist"):
+            filter_audio(numpy.ones((1, 100)), cutoff_hz=4000, sample_rate=8000)
+
+    def test_a_waveform_needs_a_sample_rate(self):
+        from dw.tasks.audio_utils import filter_audio
+
+        with pytest.raises(ValueError, match="sample_rate"):
+            filter_audio(numpy.ones((1, 10)), cutoff_hz=100)
+
+
+class TestAnalyzeAudio:
+    def tone(self, samples=8000, rate=8000, frequency=100, level=1.0):
+        t = numpy.arange(samples) / rate
+        return (
+            numpy.sin(2 * numpy.pi * frequency * t).astype(numpy.float32)[
+                numpy.newaxis, :
+            ]
+            * level
+        )
+
+    def test_a_full_scale_tone_reads_its_own_peak_rms_and_crest_factor(self):
+        from dw.tasks.audio_utils import analyze_audio
+
+        result = analyze_audio(self.tone(), sample_rate=8000)
+
+        assert result["peak_dbfs"] == pytest.approx(0.0, abs=0.05)
+        assert result["rms_dbfs"] == pytest.approx(-3.01, abs=0.05)
+        assert result["crest_factor_db"] == pytest.approx(3.01, abs=0.05)
+
+    def test_a_low_tone_reads_louder_in_the_low_band_than_the_high_band(self):
+        from dw.tasks.audio_utils import analyze_audio
+
+        result = analyze_audio(
+            self.tone(samples=16000, rate=16000, frequency=100), sample_rate=16000
+        )
+
+        assert result["low_dbfs"] > result["high_dbfs"]
+
+    def test_silence_reads_none_throughout(self):
+        from dw.tasks.audio_utils import analyze_audio
+
+        result = analyze_audio(numpy.zeros((1, 8000)), sample_rate=8000)
+
+        assert result["peak_dbfs"] is None
+        assert result["rms_dbfs"] is None
+        assert result["crest_factor_db"] is None
+
+    def test_the_input_is_not_modified(self):
+        from dw.tasks.audio_utils import analyze_audio
+
+        track = self.tone()
+        original = track.copy()
+        analyze_audio(track, sample_rate=8000)
+
+        assert numpy.array_equal(track, original)
+
+    def test_a_waveform_needs_a_sample_rate(self):
+        from dw.tasks.audio_utils import analyze_audio
+
+        with pytest.raises(ValueError, match="sample_rate"):
+            analyze_audio(numpy.ones((1, 10)))

From f5f0229c6174946901ab2e90e27d4d88d2d85921 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Thu, 17 Sep 2026 15:14:39 -0500
Subject: [PATCH 14/77] fix(mcp): #202 - add JSON merge patch support to
 save_workflow

save_workflow now accepts a `patch` argument (RFC 7396 JSON Merge Patch)
as an alternative to the full `workflow` document: the client reads the
currently stored definition, merges the patch onto it in memory, and PUTs
the result through the existing (unchanged) REST route. A small edit -
bumping one variable default, for example - now means sending just that
key rather than resending the whole document.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 dw_mcp/authoring.py         | 36 ++++++++++++++++++++--
 dw_mcp/server.py            | 16 ++++++++--
 tests/test_mcp_authoring.py | 59 +++++++++++++++++++++++++++++++++++++
 tests/test_mcp_server.py    |  1 +
 4 files changed, 108 insertions(+), 4 deletions(-)

diff --git a/dw_mcp/authoring.py b/dw_mcp/authoring.py
index 93408c18..882a472d 100644
--- a/dw_mcp/authoring.py
+++ b/dw_mcp/authoring.py
@@ -55,15 +55,47 @@ def validate_workflow(
     return client.post_json("/api/validate", payload, params=params)
 
 
-def save_workflow(client, name, workflow):
+def save_workflow(client, name, workflow=None, patch=None):
     """Write a workflow into the server's writable workflow directory,
     overwriting any file already under that name there. A name that resolves
     to one of the server's read-only sources (an examples directory) is not
     overwritten: the copy lands in the writable directory and shadows it from
-    then on. The server validates before writing."""
+    then on. The server validates before writing.
+
+    Give exactly one of `workflow` (the full document to write) or `patch`
+    (a JSON Merge Patch, RFC 7396, applied to the currently stored
+    definition): a dict whose keys overwrite the stored ones, recursively
+    for nested dicts, so bumping one argument means sending just that
+    argument rather than the whole document. A key set to `null` deletes it.
+    A list replaces the stored list whole - a merge patch has no notion of
+    list position, so changing one entry of a `for_each` list still means
+    sending that whole list."""
+    if (workflow is None) == (patch is None):
+        raise DwApiError(
+            "Provide exactly one of `workflow` (a full replacement) or "
+            "`patch` (a JSON merge patch onto the stored version)."
+        )
+    if patch is not None:
+        current = client.get_json(api_path("api", "workflows", name))
+        workflow = _merge_patch(current, patch)
     return client.put_json(api_path("api", "workflows", name), {"workflow": workflow})
 
 
+def _merge_patch(target, patch):
+    """RFC 7396 JSON Merge Patch: each dict key in `patch` merges
+    recursively into `target`; any other value replaces `target` outright;
+    `None` deletes the key from the result."""
+    if not isinstance(patch, dict):
+        return patch
+    result = dict(target) if isinstance(target, dict) else {}
+    for key, value in patch.items():
+        if value is None:
+            result.pop(key, None)
+        else:
+            result[key] = _merge_patch(result.get(key), value)
+    return result
+
+
 def delete_workflow(client, name):
     """Remove a workflow from the server's workflow directory."""
     return client.delete_json(api_path("api", "workflows", name))
diff --git a/dw_mcp/server.py b/dw_mcp/server.py
index f1723702..e94a1aae 100644
--- a/dw_mcp/server.py
+++ b/dw_mcp/server.py
@@ -786,7 +786,9 @@ def validate_workflow(
             arguments=arguments,
         )
 
-    def save_workflow(name: str, workflow: dict) -> dict:
+    def save_workflow(
+        name: str, workflow: dict | None = None, patch: dict | None = None
+    ) -> dict:
         """Save a workflow to the server's writable workflow directory,
         overwriting any existing workflow of that name there. Validate it
         first. A name that currently resolves to a read-only source (an
@@ -795,11 +797,21 @@ def save_workflow(name: str, workflow: dict) -> dict:
         example gets adapted without being damaged. `name` may include
         folders.
 
+        Give exactly one of `workflow` (the full document) or `patch` for a
+        small, targeted edit: a JSON Merge Patch (RFC 7396) merged onto the
+        currently stored definition, so bumping one argument means sending
+        just that argument rather than the whole document -
+        `{"variables": {"num_images_per_prompt": 4}}` rather than the whole
+        workflow. A patch key set to `null` deletes that key from the
+        stored document. A list is replaced whole, never merged - a merge
+        patch has no notion of list position, so changing one `shots` entry
+        still means sending the whole `shots` list.
+
         A workflow stored for reuse should mark each saving step's
         `result.subfolder` - `final` for the step whose output the user will
         be shown, `intermediate` for the rest - so a later consumer can tell
         the deliverable from the scratch files without knowing the workflow."""
-        return authoring.save_workflow(client, name, workflow)
+        return authoring.save_workflow(client, name, workflow=workflow, patch=patch)
 
     def delete_workflow(name: str) -> dict:
         """Permanently delete a stored workflow from this workspace. A
diff --git a/tests/test_mcp_authoring.py b/tests/test_mcp_authoring.py
index 6721bbac..0ef41f48 100644
--- a/tests/test_mcp_authoring.py
+++ b/tests/test_mcp_authoring.py
@@ -166,6 +166,65 @@ def test_save_surfaces_a_path_the_server_refuses():
         authoring.save_workflow(client, "../escape", WORKFLOW)
 
 
+def test_save_with_patch_merges_onto_the_stored_definition():
+    """A small edit shouldn't require resending the whole document (#202)."""
+    stored = {
+        "id": "w",
+        "steps": [],
+        "variables": {"prompt": {"default": "a cat"}, "seed": {"default": 1}},
+    }
+    seen = []
+
+    def handler(request):
+        seen.append((request.method, request.url.path))
+        if request.method == "GET":
+            return httpx.Response(200, json=stored)
+        body = json.loads(request.read())
+        return httpx.Response(200, json={"name": "mine", "sent": body})
+
+    client = DwClient(transport=httpx.MockTransport(handler))
+
+    result = authoring.save_workflow(
+        client, "mine", patch={"variables": {"seed": {"default": 2}}}
+    )
+
+    assert seen == [("GET", "/api/workflows/mine"), ("PUT", "/api/workflows/mine")]
+    sent_workflow = result["sent"]["workflow"]
+    assert sent_workflow["variables"]["seed"]["default"] == 2
+    assert sent_workflow["variables"]["prompt"]["default"] == "a cat"
+    assert sent_workflow["id"] == "w"
+
+
+def test_save_with_patch_null_deletes_a_key():
+    stored = {"id": "w", "steps": [], "description": "old"}
+
+    def handler(request):
+        if request.method == "GET":
+            return httpx.Response(200, json=stored)
+        body = json.loads(request.read())
+        return httpx.Response(200, json={"name": "mine", "sent": body})
+
+    client = DwClient(transport=httpx.MockTransport(handler))
+
+    result = authoring.save_workflow(client, "mine", patch={"description": None})
+
+    assert "description" not in result["sent"]["workflow"]
+
+
+def test_save_refuses_both_workflow_and_patch():
+    client, _seen = scripted({})
+
+    with pytest.raises(DwApiError, match="exactly one"):
+        authoring.save_workflow(client, "mine", workflow=WORKFLOW, patch={})
+
+
+def test_save_refuses_neither_workflow_nor_patch():
+    client, _seen = scripted({})
+
+    with pytest.raises(DwApiError, match="exactly one"):
+        authoring.save_workflow(client, "mine")
+
+
 def test_delete_calls_delete():
     client, seen = scripted(
         {("DELETE", "/api/workflows/mine"): (200, {"name": "mine", "deleted": True})}
diff --git a/tests/test_mcp_server.py b/tests/test_mcp_server.py
index 0f338e7c..86cdfb64 100644
--- a/tests/test_mcp_server.py
+++ b/tests/test_mcp_server.py
@@ -870,6 +870,7 @@ def refusing(request):
     "delete_model": (models, "delete_model"),
     "update_diffusers": (models, "update_diffusers"),
     "validate_workflow": (authoring, "validate_workflow"),
+    "save_workflow": (authoring, "save_workflow"),
     "run_workflow": (diagnose, "run_workflow"),
     "rerun_job": (diagnose, "rerun_job"),
     "get_output_text": (media, "get_output_text"),

From 9b9b79903f02811ee99b1892fb5c78ebc9aceaf2 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Thu, 17 Sep 2026 15:39:59 -0500
Subject: [PATCH 15/77] fix(mcp): #203/#204 - inline-bytes upload_asset content
 path + get_output_audio

upload_asset now takes content= (base64) as an alternative to file_path,
for a headless agent driving a mounted dw.serve --mcp endpoint with no
filesystem in common with the server - bytes it holds itself go straight
to /api/uploads with no path involved, so #138's containment is untouched.
Capped at MAX_INLINE_UPLOAD_BYTES (4MB), well under file_path's limit.

get_output_audio mirrors get_output_image for a short clip: base64 inline,
refused outright (not downscaled) over MAX_RETURNED_BYTES, since a cut
clip is a misleading answer rather than a smaller correct one.

Reworded upload_asset/download_output error messages to also name
get_output_image/get_output_audio/get_output_text and the gallery url as
agent-usable paths.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 dw_mcp/assets.py         | 105 ++++++++++++++++++++++++++++++++-------
 dw_mcp/media.py          |  67 +++++++++++++++++++++----
 dw_mcp/server.py         |  88 ++++++++++++++++++++++++--------
 tests/test_mcp_assets.py |  72 +++++++++++++++++++++++++++
 tests/test_mcp_media.py  |  64 +++++++++++++++++++++++-
 tests/test_mcp_server.py |   7 +++
 6 files changed, 353 insertions(+), 50 deletions(-)

diff --git a/dw_mcp/assets.py b/dw_mcp/assets.py
index acc03049..aa76dc02 100644
--- a/dw_mcp/assets.py
+++ b/dw_mcp/assets.py
@@ -9,6 +9,7 @@
 workflow carries and the path means nothing on the machine the agent is on.
 """
 
+import base64
 import os
 
 from dw_mcp.client import DwApiError, api_path
@@ -17,6 +18,12 @@
 # a 200MB file fails before it is read and pushed, not after
 MAX_UPLOAD_BYTES = 200 * 1024 * 1024
 
+# `content` bytes arrive base64-encoded in the tool call itself rather than
+# read off a disk, so they compete with everything else in the call for the
+# caller's context budget - a few MB is enough for a voice sample or a small
+# image, and nowhere near enough to use this as a bulk-transfer path (#203)
+MAX_INLINE_UPLOAD_BYTES = 4 * 1024 * 1024
+
 # What the library holds, and what the upload route accepts. Duplicated from
 # dw/security.py rather than imported: importing anything under dw/ pulls in
 # torch, which this pure HTTP client must not do
@@ -70,8 +77,9 @@ def _remote_roots(client):
         raise DwApiError(
             "This server cannot say which directories it works in, so it "
             "will not read a file off its own disk for you. Upload the "
-            "bytes through the web UI's file picker, or keep a generated "
-            "file with keep_output."
+            "bytes through the web UI's file picker, pass them inline to "
+            "upload_asset as content=, or keep a generated file with "
+            "keep_output."
         )
     return roots
 
@@ -98,9 +106,11 @@ def _confine_source(path, roots, named):
         f"dw.serve, so the file would be read off the server, where a "
         f"source is confined to the directories it works in "
         f"({', '.join(roots)}). A file that is already there is reachable "
-        f"as an 'asset:' reference; to put a new one there, upload it "
-        f"through the web UI's file picker, or promote a generated file "
-        f"with keep_output."
+        f"as an 'asset:' reference; to put a new one there when it exists "
+        f"only on your own machine, call upload_asset with content= (its "
+        f"bytes, base64-encoded) instead of file_path, upload it through "
+        f"the web UI's file picker, or promote a generated file with "
+        f"keep_output."
     )
 
 
@@ -160,32 +170,50 @@ def keep_output(
     )
 
 
-def upload_asset(client, file_path, asset_name=None, shared=False):
-    """Put a local image, video or audio file into the server's asset
-    library and get back the reference a workflow can use.
+def upload_asset(client, file_path=None, content=None, asset_name=None, shared=False):
+    """Put an image, video or audio file into the server's asset library and
+    get back the reference a workflow can use.
+
+    Takes exactly one of two sources:
 
-    The file is read from the machine this MCP server runs on, which is not
-    necessarily the machine dw.serve runs on - that is the point of the
-    tool.
+    `file_path` is read from the machine this MCP server runs on, which is
+    not necessarily the machine dw.serve runs on - that is the point of the
+    tool. Over a `dw.serve --mcp` endpoint that machine *is* the server, so
+    there `file_path` is confined to the directories the server works in,
+    and the refusal comes before the file is looked for so it cannot be used
+    to probe which paths exist (#138). A stdio `dw-mcp` is unconfined,
+    because there the file really is the caller's own.
 
-    Over a `dw.serve --mcp` endpoint that machine *is* the server, so there
-    `file_path` is confined to the directories the server works in, and the
-    refusal comes before the file is looked for so it cannot be used to
-    probe which paths exist (#138). A stdio `dw-mcp` is unconfined, because
-    there the file really is the caller's own.
+    `content` is the file's bytes, base64-encoded, for the case `file_path`
+    cannot reach: a headless agent driving a mounted `dw.serve --mcp`
+    endpoint has no filesystem in common with that server, so a voice
+    sample or small image that exists only on the agent's own machine has
+    no path either side can name. No path is confined or read for this
+    path - the bytes just go straight to the upload route - so it does not
+    reopen #138. It is capped well under `file_path`'s limit
+    (MAX_INLINE_UPLOAD_BYTES, a few MB) because these bytes ride in the tool
+    call itself rather than being streamed off disk, and `asset_name` is
+    required so the upload has a name and extension to be validated against.
 
     `asset_name` is the name it is stored under - 'cast/priya-voice.wav'
     rather than the random one an upload gets by default. A recurring cast
     referenced as 'asset:uploads/084eaecc....wav' in every workflow cannot
     be told apart without opening each file, which is the whole reason to
-    name one (2026-09-11). The extension comes from the uploaded file when
-    the name has none.
+    name one (2026-09-11). With `file_path`, the extension comes from the
+    uploaded file when the name has none; with `content`, `asset_name` must
+    carry its own extension since there is no file to take one from.
 
     `shared` puts it in the library every workspace shares rather than in
     the session's own, which is what a recurring cast needs: assets are
     per workspace, so a cast uploaded while making episode one was
     invisible from the workspace episode four was made in.
     """
+    if (file_path is None) == (content is None):
+        raise DwApiError("Pass exactly one of file_path or content.")
+
+    if content is not None:
+        return _upload_inline(client, content, asset_name=asset_name, shared=shared)
+
     path = os.path.abspath(os.path.expanduser(str(file_path)))
     roots = _remote_roots(client)
     if roots is not None:
@@ -228,3 +256,44 @@ def upload_asset(client, file_path, asset_name=None, shared=False):
         "uploaded": os.path.basename(path),
         "size": size,
     }
+
+
+def _upload_inline(client, content, asset_name=None, shared=False):
+    """The `content=` path of upload_asset - bytes with no path behind
+    them, so nothing here is confined or read off any disk (#203)."""
+    if not asset_name:
+        raise DwApiError(
+            "content requires asset_name, so the upload has a name and an "
+            "extension to validate - there is no file to take either from."
+        )
+
+    extension = os.path.splitext(asset_name)[1].lower()
+    if extension not in ALLOWED_UPLOAD_EXTENSIONS:
+        raise DwApiError(
+            f"{asset_name} is not a kind the asset library takes "
+            f"({', '.join(sorted(ALLOWED_UPLOAD_EXTENSIONS))})."
+        )
+
+    try:
+        body = base64.b64decode(content, validate=True)
+    except Exception as e:
+        raise DwApiError(f"content could not be decoded as base64: {e}")
+
+    if len(body) > MAX_INLINE_UPLOAD_BYTES:
+        raise DwApiError(
+            f"content is {len(body)} bytes, over the "
+            f"{MAX_INLINE_UPLOAD_BYTES} byte limit for an inline upload. A "
+            f"file this large should be reached by file_path instead, from "
+            f"a machine that has it on disk."
+        )
+
+    params = {"filename": asset_name, "asset_name": asset_name}
+    if shared:
+        params["shared"] = "true"
+    result = client.post_bytes("/api/uploads", body, params=params)
+    return {
+        "reference": result.get("path"),
+        "url": result.get("url"),
+        "uploaded": asset_name,
+        "size": len(body),
+    }
diff --git a/dw_mcp/media.py b/dw_mcp/media.py
index 51b27906..3fb86de4 100644
--- a/dw_mcp/media.py
+++ b/dw_mcp/media.py
@@ -103,6 +103,48 @@ def _fit(image, limit):
     )
 
 
+def get_output_audio(client, name, workspace=None):
+    """One audio output from the output directory, as base64, for a clip
+    short enough to fit MAX_RETURNED_BYTES whole.
+
+    Unlike an image, audio is not resized here - there is no equivalent of
+    downscaling a waveform that keeps it meaningful to listen to. A clip
+    over budget is refused rather than truncated or transcoded, since a cut
+    clip is a different, misleading answer rather than a smaller correct
+    one (#204). Use `download_output` or the gallery `url` for a longer
+    file, and `get_gallery_metadata` for its duration and sample rate
+    without fetching the bytes at all."""
+
+    def is_audio(content_type):
+        return bool(content_type) and content_type.startswith("audio/")
+
+    body, content_type = client.get_bytes_if(
+        api_path("outputs", name), is_audio, workspace=workspace
+    )
+    if body is None:
+        raise DwApiError(
+            f"{name} is {content_type or 'of no declared type'}, not audio - "
+            "this tool returns audio only. Use get_output_image for an "
+            "image, or get_gallery_metadata for other media."
+        )
+
+    base64_size = 4 * math.ceil(len(body) / 3)
+    if base64_size > MAX_RETURNED_BYTES:
+        raise DwApiError(
+            f"{name} is {len(body)} bytes, which would be {base64_size} "
+            f"bytes base64-encoded - over the {MAX_RETURNED_BYTES} byte "
+            "limit for an inline clip. Use download_output, or the `url` "
+            "list_gallery reports, for a file this size."
+        )
+
+    return {
+        "name": name,
+        "data": base64.b64encode(body).decode("ascii"),
+        "mime_type": content_type,
+        "bytes": len(body),
+    }
+
+
 def get_output_text(
     client, name, max_characters=MAX_RETURNED_CHARACTERS, workspace=None
 ):
@@ -162,7 +204,8 @@ def _remote_root(client):
         raise DwApiError(
             "This server cannot say where its workspace is, so it will not "
             "write a file for you. Use the url list_gallery reports, "
-            "get_output_image / get_output_text, or keep_output."
+            "get_output_image / get_output_audio / get_output_text, or "
+            "keep_output."
         )
     return os.path.realpath(os.path.abspath(os.path.expanduser(str(root))))
 
@@ -191,8 +234,8 @@ def _confine(destination, root):
             f"destination is confined to the workspace ({root}). Pass a "
             f"relative destination, or - to see the file where you are - use "
             f"the url list_gallery reports, get_output_image / "
-            f"get_output_text for inline content, or keep_output to make it "
-            f"an asset for a later workflow."
+            f"get_output_audio / get_output_text for inline content, or "
+            f"keep_output to make it an asset for a later workflow."
         )
 
 
@@ -200,12 +243,13 @@ def download_output(client, name, destination=None, overwrite=False, workspace=N
     """Fetch one output file and save it to local disk, for an agent that
     wants the artifact itself rather than a description of it.
 
-    Unlike get_output_image/get_output_text, this accepts any content type
-    and returns nothing to the conversation but a manifest of where the
-    file landed - the point is a file on disk, not a payload in context.
-    It is also the one tool in this package that writes a local file, and
-    the body is streamed to disk in chunks rather than buffered whole, since
-    it exists for files (large videos) get_output_image can't return.
+    Unlike get_output_image/get_output_audio/get_output_text, this accepts
+    any content type and returns nothing to the conversation but a manifest
+    of where the file landed - the point is a file on disk, not a payload
+    in context. It is also the one tool in this package that writes a
+    local file, and the body is streamed to disk in chunks rather than
+    buffered whole, since it exists for files (large videos) the inline
+    tools can't return.
 
     `destination` may be a full file path, a directory (the output's own
     basename is used inside it), or omitted (saved to the current working
@@ -266,8 +310,9 @@ def download_output(client, name, destination=None, overwrite=False, workspace=N
             f"server ({e.strerror or e}). This tool saves on that machine - "
             "over a dw.serve --mcp endpoint that is the GPU box, not where "
             "you are. To see the file from here use the url list_gallery "
-            "reports, get_output_image / get_output_text for inline content, "
-            "or keep_output to make it an asset for a later workflow."
+            "reports, get_output_image / get_output_audio / get_output_text "
+            "for inline content, or keep_output to make it an asset for a "
+            "later workflow."
         ) from e
 
     return {
diff --git a/dw_mcp/server.py b/dw_mcp/server.py
index e94a1aae..d14451d3 100644
--- a/dw_mcp/server.py
+++ b/dw_mcp/server.py
@@ -10,7 +10,7 @@
 
 from mcp.server.mcpserver import MCPServer
 from mcp.server.mcpserver.exceptions import ToolError
-from mcp.types import ImageContent, TextContent, ToolAnnotations
+from mcp.types import AudioContent, ImageContent, TextContent, ToolAnnotations
 
 from dw_mcp import (
     assets,
@@ -488,9 +488,9 @@ def get_output_image(
         """Look at a generated image, named as `list_gallery` or a job's
         manifest reports it. Use this to judge output quality - it is the
         only way to see what a workflow actually produced, and a run that
-        succeeded can still have made the wrong picture. Images only: a
-        video or audio output is refused, so inspect those with
-        `get_gallery_metadata` or hand the user the file. The image is
+        succeeded can still have made the wrong picture. Images only: audio
+        is `get_output_audio`'s and video is refused, so inspect a video
+        with `get_gallery_metadata` or hand the user the file. The image is
         downscaled to `max_dimension` on its longest side; the second part
         of the result reports the size it went in and came out at, so a
         downscale is never silent.
@@ -516,6 +516,32 @@ def get_output_image(
         )
         return [image, telemetry]
 
+    def get_output_audio(
+        name: str, workspace: str | None = None
+    ) -> list[AudioContent | TextContent]:
+        """Listen to a generated audio output, named as `list_gallery` or a
+        job's manifest reports it - the audio analogue of `get_output_image`.
+        Audio only: an image is `get_output_image`'s and video is refused,
+        so inspect a video with `get_gallery_metadata` or hand the user the
+        file. There is no downscale for audio the way there is for an
+        image's dimensions, so a clip too large to fit inline is refused
+        rather than cut or transcoded - use `download_output` or the `url`
+        list_gallery reports for one that long.
+
+        `workspace` names the workspace for this one call without
+        switching the session to it - the same pin `run_workflow`
+        takes, so a job run into another workspace is reachable from
+        here without leaving this one (#99)."""
+        result = media.get_output_audio(client, name, workspace=workspace)
+        audio = AudioContent(
+            type="audio", data=result["data"], mime_type=result["mime_type"]
+        )
+        telemetry = TextContent(
+            type="text",
+            text=f"name: {result['name']}\nbytes: {result['bytes']}",
+        )
+        return [audio, telemetry]
+
     def get_output_text(
         name: str, max_characters: int = 20000, workspace: str | None = None
     ) -> dict:
@@ -588,6 +614,7 @@ def download_output(
         )
 
     tool(get_output_image, READ_ONLY)
+    tool(get_output_audio, READ_ONLY)
     tool(get_output_text, READ_ONLY)
     tool(download_output, OVERWRITES)
     tool(delete_output, DELETES)
@@ -604,26 +631,47 @@ def list_assets() -> dict:
         return assets.list_assets(client)
 
     def upload_asset(
-        file_path: str, asset_name: str | None = None, shared: bool = False
+        file_path: str | None = None,
+        content: str | None = None,
+        asset_name: str | None = None,
+        shared: bool = False,
     ) -> dict:
-        """Put a local image, video or audio file into the server's asset
+        """Put an image, video or audio file into the server's asset
         library and get back the "asset:" reference to use in a workflow.
-        The file is read from the machine this MCP server runs on and
+        Pass exactly one of `file_path` or `content`.
+
+        `file_path` is read from the machine this MCP server runs on and
         pushed to the engine, so it is how an input reaches a dw.serve
-        running somewhere else. Accepts the usual image, video and audio
-        extensions, up to 200MB. Reference the result rather than a path: a
-        path on this machine means nothing to the server. Pass `asset_name`
-        to store it under a readable name ("cast/priya-voice.wav", folders
-        allowed, the file's extension assumed) - without one the stored
-        name is random, and a set of related inputs cannot be told apart in
-        the workflows that carry them. Pass `shared=true` to put it in the
-        library every workspace shares rather than this session's own -
-        where a recurring cast belongs, since a workspace's own assets are
-        invisible from the next workspace. When this MCP surface is served
-        by dw.serve itself, "this machine" is the engine's own box, so
-        `file_path` is confined to the directories it works in."""
+        running somewhere else. When this MCP surface is served by
+        dw.serve itself, "this machine" is the engine's own box, so
+        `file_path` is confined to the directories it works in - a file
+        that exists only on your own machine cannot be named this way.
+
+        `content` is for exactly that case: the file's bytes, base64-encoded,
+        sent inline in the call rather than read off any disk. Use it for a
+        voice sample or small image that lives only on the machine you are
+        running on, against a remote `dw.serve --mcp` endpoint with no
+        filesystem in common with you. Capped at 4MB, well under
+        `file_path`'s 200MB, because these bytes ride in the call itself.
+        `asset_name` is required with `content`, since there is no file to
+        take a name or extension from.
+
+        Accepts the usual image, video and audio extensions. Reference the
+        result rather than a path: a path on this machine means nothing to
+        the server. Pass `asset_name` to store it under a readable name
+        ("cast/priya-voice.wav", folders allowed) - without one (when using
+        `file_path`) the stored name is random, and a set of related inputs
+        cannot be told apart in the workflows that carry them. Pass
+        `shared=true` to put it in the library every workspace shares
+        rather than this session's own - where a recurring cast belongs,
+        since a workspace's own assets are invisible from the next
+        workspace."""
         return assets.upload_asset(
-            client, file_path, asset_name=asset_name, shared=shared
+            client,
+            file_path=file_path,
+            content=content,
+            asset_name=asset_name,
+            shared=shared,
         )
 
     def keep_output(
diff --git a/tests/test_mcp_assets.py b/tests/test_mcp_assets.py
index 9e8e4334..e8b7904c 100644
--- a/tests/test_mcp_assets.py
+++ b/tests/test_mcp_assets.py
@@ -9,7 +9,10 @@
 import httpx
 import pytest
 
+import base64
+
 from dw_mcp.assets import (
+    MAX_INLINE_UPLOAD_BYTES,
     MAX_UPLOAD_BYTES,
     delete_asset,
     keep_output,
@@ -225,6 +228,75 @@ def handler(request):
             delete_asset(client_over(handler), "iris.png")
 
 
+class TestUploadInlineContent:
+    """The content= path (#203): bytes an agent holds itself, with no path
+    behind them at all, for a mounted endpoint with no filesystem in common
+    with the caller."""
+
+    def test_content_is_decoded_and_posted(self):
+        client, seen = recording()
+        body = b"riff-bytes"
+
+        result = upload_asset(
+            client, content=base64.b64encode(body).decode("ascii"), asset_name="cast/priya-voice.wav"
+        )
+
+        assert seen["body"] == body
+        assert "asset_name=cast" in seen["url"].replace("%2F", "/")
+        assert "filename=cast" in seen["url"].replace("%2F", "/")
+        assert result["reference"] == "asset:uploads/deadbeef.png"
+        assert result["uploaded"] == "cast/priya-voice.wav"
+        assert result["size"] == len(body)
+
+    def test_both_file_path_and_content_is_refused(self, tmp_path):
+        source = tmp_path / "iris.png"
+        source.write_bytes(b"x")
+        client, _seen = recording()
+        with pytest.raises(DwApiError, match="exactly one of file_path or content"):
+            upload_asset(client, str(source), content="AAAA", asset_name="x.png")
+
+    def test_neither_file_path_nor_content_is_refused(self):
+        client, _seen = recording()
+        with pytest.raises(DwApiError, match="exactly one of file_path or content"):
+            upload_asset(client)
+
+    def test_content_without_asset_name_is_refused(self):
+        client, _seen = recording()
+        with pytest.raises(DwApiError, match="content requires asset_name"):
+            upload_asset(client, content=base64.b64encode(b"x").decode("ascii"))
+
+    def test_a_kind_the_library_does_not_take_is_refused(self):
+        client, seen = recording()
+        with pytest.raises(DwApiError, match="not a kind"):
+            upload_asset(
+                client, content=base64.b64encode(b"x").decode("ascii"), asset_name="script.py"
+            )
+        assert "body" not in seen
+
+    def test_invalid_base64_says_so(self):
+        client, seen = recording()
+        with pytest.raises(DwApiError, match="could not be decoded as base64"):
+            upload_asset(client, content="not-valid-base64!!", asset_name="x.png")
+        assert "body" not in seen
+
+    def test_content_over_the_inline_limit_is_refused(self):
+        client, seen = recording()
+        oversized = base64.b64encode(b"0" * (MAX_INLINE_UPLOAD_BYTES + 1)).decode("ascii")
+        with pytest.raises(DwApiError, match="inline upload"):
+            upload_asset(client, content=oversized, asset_name="x.png")
+        assert "body" not in seen
+
+    def test_shared_is_passed_through(self):
+        client, seen = recording()
+        upload_asset(
+            client,
+            content=base64.b64encode(b"x").decode("ascii"),
+            asset_name="cast/priya.png",
+            shared=True,
+        )
+        assert "shared=true" in seen["url"]
+
+
 class TestUploadContainmentOverAMountedEndpoint:
     """Served by dw.serve, 'local file' means the operator's box - so an
     unconfined file_path is an arbitrary read of the server's filesystem plus
diff --git a/tests/test_mcp_media.py b/tests/test_mcp_media.py
index 65388ed4..b03f1b14 100644
--- a/tests/test_mcp_media.py
+++ b/tests/test_mcp_media.py
@@ -12,7 +12,12 @@
 
 import dw_mcp.media as media
 from dw_mcp.client import DwApiError, DwClient
-from dw_mcp.media import MAX_RETURNED_BYTES, download_output, get_output_image
+from dw_mcp.media import (
+    MAX_RETURNED_BYTES,
+    download_output,
+    get_output_audio,
+    get_output_image,
+)
 
 
 def noise_png_bytes(width, height, seed=0):
@@ -120,6 +125,63 @@ def test_a_video_output_is_refused_by_name():
     assert "video/mp4" in str(caught.value)
 
 
+class TestGetOutputAudio:
+    def test_a_clip_under_budget_comes_back_as_base64(self):
+        body = b"riff-audio-bytes"
+        client = serving(body, "audio/wav")
+
+        result = get_output_audio(client, "voice.wav")
+
+        assert base64.b64decode(result["data"]) == body
+        assert result["mime_type"] == "audio/wav"
+        assert result["bytes"] == len(body)
+        assert result["name"] == "voice.wav"
+
+    def test_an_image_output_is_refused_by_content_type(self):
+        client = serving(png_bytes(10, 10), "image/png")
+
+        with pytest.raises(DwApiError) as caught:
+            get_output_audio(client, "still.png")
+
+        assert "image/png" in str(caught.value)
+
+    def test_a_response_with_no_content_type_is_refused(self):
+        def handler(request):
+            return httpx.Response(200, content=b"???")
+
+        client = DwClient(transport=httpx.MockTransport(handler))
+
+        with pytest.raises(DwApiError):
+            get_output_audio(client, "mystery")
+
+    def test_a_clip_over_the_byte_ceiling_is_refused(self, monkeypatch):
+        monkeypatch.setattr(media, "MAX_RETURNED_BYTES", 16)
+        client = serving(b"x" * 32, "audio/wav")
+
+        with pytest.raises(DwApiError, match="byte limit"):
+            get_output_audio(client, "long.wav")
+
+    def test_the_budget_is_checked_against_the_base64_size_not_the_raw_bytes(
+        self, monkeypatch
+    ):
+        # 12 raw bytes base64-encode to 16 - set the cap between the two so a
+        # raw-bytes-only comparison would wrongly accept it.
+        monkeypatch.setattr(media, "MAX_RETURNED_BYTES", 13)
+        client = serving(b"x" * 12, "audio/wav")
+
+        with pytest.raises(DwApiError, match="byte limit"):
+            get_output_audio(client, "clip.wav")
+
+    def test_a_missing_file_propagates_the_api_error(self):
+        def handler(request):
+            return httpx.Response(404, json={"detail": "Unknown file"})
+
+        client = DwClient(transport=httpx.MockTransport(handler))
+
+        with pytest.raises(DwApiError, match="Unknown file"):
+            get_output_audio(client, "ghost.wav")
+
+
 def test_a_non_image_output_is_refused_without_reading_the_body():
     """A video can be arbitrarily large - the content-type header alone
     should be enough to refuse it, before the body is ever downloaded."""
diff --git a/tests/test_mcp_server.py b/tests/test_mcp_server.py
index 86cdfb64..c4261258 100644
--- a/tests/test_mcp_server.py
+++ b/tests/test_mcp_server.py
@@ -34,6 +34,7 @@
     "list_gallery",
     "get_gallery_metadata",
     "get_output_image",
+    "get_output_audio",
     "validate_workflow",
     "save_workflow",
     "delete_workflow",
@@ -334,6 +335,7 @@ def _a_file_to_upload():
         "/api/gallery/out.png/metadata",
     ),
     ("get_output_image", {"name": "out.png"}, "GET", "/outputs/out.png"),
+    ("get_output_audio", {"name": "out.wav"}, "GET", "/outputs/out.wav"),
     ("validate_workflow", {"workflow": {"id": "w"}}, "POST", "/api/validate"),
     (
         "save_workflow",
@@ -466,6 +468,10 @@ def handler(request):
             return httpx.Response(
                 200, content=b"a duke", headers={"content-type": "text/plain"}
             )
+        if request.url.path.endswith(".wav"):
+            return httpx.Response(
+                200, content=b"riff", headers={"content-type": "audio/wav"}
+            )
         if request.url.path.startswith("/outputs/"):
             return httpx.Response(
                 200, content=PNG_1X1, headers={"content-type": "image/png"}
@@ -863,6 +869,7 @@ def refusing(request):
     "get_job_events": (diagnose, "get_job_events"),
     "wait_for_job": (diagnose, "wait_for_job"),
     "get_output_image": (media, "get_output_image"),
+    "get_output_audio": (media, "get_output_audio"),
     "get_class": (catalog, "get_class"),
     "list_gallery": (catalog, "list_gallery"),
     "list_jobs": (catalog, "list_jobs"),

From 1abd2a69154282d094e1336aef88f0d65f5d2671 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Thu, 17 Sep 2026 19:33:58 -0500
Subject: [PATCH 16/77] feat: #119 - select reducer, judge scorer, selected
 manifest field

Implements the approved N->1 selection design
(docs/proposals/score-and-select.md): a deterministic `select` task
command (argmax/argmin/first_above/first_below/index over a scored
candidate list), a `judge` task command that scores an image against a
rubric with a vision-language model and parses the reply to one number,
manifest/step_end support for a `selected` field recording the winning
candidate's position and score, and static validation catching a select
step whose rule is misspelled or whose threshold/index does not match
its rule before the fan-out ahead of it runs.

judge delegates to text_generation.generate_text, the same vision path
image_to_text uses; generation there is already greedy (do_sample=False),
so no step-seed threading was needed for determinism, unlike the
proposal's assumption - documented as a deviation in judge.py's docstring.

Deferred to follow-up: the catalog template demonstrating select+judge
together, and template-level manifest/cache-reuse tests. The engine
support merged here is complete and independently testable without it.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 dw/result.py                      |  10 ++
 dw/select_validation.py           |  95 +++++++++++++++++++
 dw/tasks/judge.py                 |  68 +++++++++++++
 dw/tasks/select.py                | 109 +++++++++++++++++++++
 dw/tasks/task.py                  |  23 +++++
 dw/workflow.py                    |  38 ++++++++
 tests/test_judge.py               |  99 +++++++++++++++++++
 tests/test_result.py              |   9 ++
 tests/test_select.py              | 101 ++++++++++++++++++++
 tests/test_select_validation.py   | 153 ++++++++++++++++++++++++++++++
 tests/test_workflow.py            |  14 +++
 tests/test_workflow_step_cache.py |   1 +
 12 files changed, 720 insertions(+)
 create mode 100644 dw/select_validation.py
 create mode 100644 dw/tasks/judge.py
 create mode 100644 dw/tasks/select.py
 create mode 100644 tests/test_judge.py
 create mode 100644 tests/test_select.py
 create mode 100644 tests/test_select_validation.py

diff --git a/dw/result.py b/dw/result.py
index 088fdbde..fbad76ac 100644
--- a/dw/result.py
+++ b/dw/result.py
@@ -352,6 +352,10 @@ def __init__(self, result_definition):
         self.result_list = []
         self.metadata = None
         self.saved_files = []
+        # Set when a select step's Selected wrapper flows through
+        # add_result - the winning position/score, replayable in the
+        # manifest and step_end alongside the unwrapped value (#119)
+        self.selected = None
         # Whether the file currently being written already drew a headroom
         # warning from the waveform it was handed, so the written-level
         # check does not say the same thing twice (#161)
@@ -372,6 +376,12 @@ def add_result(self, result):
         Args:
             result: Single result or list of results to store
         """
+        from .tasks.select import Selected
+
+        if isinstance(result, Selected):
+            self.selected = {"position": result.position, "score": result.score}
+            result = result.value
+
         if isinstance(result, list):
             logger.debug(f"Adding {len(result)} results to result list")
             self.result_list.extend(result)
diff --git a/dw/select_validation.py b/dw/select_validation.py
new file mode 100644
index 00000000..cadcfe5e
--- /dev/null
+++ b/dw/select_validation.py
@@ -0,0 +1,95 @@
+"""Static validation for select's arguments (docs/proposals/score-and-select.md).
+
+select's own signature carries no domain - `rule` is any string, and
+`threshold`/`index` are only meaningful for some rules - so a step whose
+rule is misspelled, or whose threshold is missing, or whose index rule has
+none, validates clean today and dies on select's own run-time ValueError
+after the fan-out ahead of it has already generated. Checked here in
+`validation_errors` (free), and unchanged as select's own run-time check
+for a value arriving from a `variable:` or an earlier step, which this
+static pass can never see.
+"""
+
+from .for_each import MEMBER_SEPARATOR, render_path
+
+_RULES = {"argmax", "argmin", "first_above", "first_below", "index"}
+_THRESHOLD_RULES = {"first_above", "first_below"}
+
+
+def _where(name):
+    return (
+        f" in member '{name}'"
+        if isinstance(name, str) and MEMBER_SEPARATOR in name
+        else ""
+    )
+
+
+def _is_gather(value):
+    return isinstance(value, str) and value.startswith("gather:")
+
+
+def select_errors(workflow_definition, source_indices=None):
+    """Every select step whose arguments cannot be right, as [{path, message}]."""
+    steps = workflow_definition.get("steps")
+    if not isinstance(steps, list):
+        return []
+
+    errors = []
+    for index, step in enumerate(steps):
+        if not isinstance(step, dict):
+            continue
+        task = step.get("task")
+        if not isinstance(task, dict) or task.get("command") != "select":
+            continue
+        arguments = task.get("arguments")
+        if not isinstance(arguments, dict):
+            continue
+
+        source = (
+            source_indices[index]
+            if source_indices is not None and index < len(source_indices)
+            else index
+        )
+        name = step.get("name")
+        where = _where(name)
+
+        def add(key, message):
+            path = render_path(("steps", source, "task", "arguments", key))
+            errors.append({"path": path, "message": f"{message}{where}."})
+
+        rule = arguments.get("rule")
+        if isinstance(rule, str) and rule not in _RULES:
+            add("rule", f"select: unknown rule: {rule!r}")
+        elif isinstance(rule, str):
+            has_threshold = "threshold" in arguments
+            if rule in _THRESHOLD_RULES and not has_threshold:
+                add("threshold", f"select rule '{rule}' requires a threshold")
+            elif rule not in _THRESHOLD_RULES and has_threshold:
+                add(
+                    "threshold",
+                    f"select: 'threshold' is only meaningful for rule "
+                    f"'first_above'/'first_below', not {rule!r}",
+                )
+
+            has_index = "index" in arguments
+            if rule == "index" and not has_index:
+                add("index", "select rule 'index' requires an index")
+            elif rule != "index" and has_index:
+                add(
+                    "index",
+                    f"select: 'index' is only meaningful for rule 'index', "
+                    f"not {rule!r}",
+                )
+
+        candidates = arguments.get("candidates")
+        scores = arguments.get("scores")
+        if "candidates" in arguments and "scores" in arguments:
+            if _is_gather(candidates) != _is_gather(scores):
+                add(
+                    "candidates",
+                    "select: 'candidates' and 'scores' must both be "
+                    "'gather:' references or both plain lists, got "
+                    f"candidates={candidates!r} scores={scores!r}",
+                )
+
+    return errors
diff --git a/dw/tasks/judge.py b/dw/tasks/judge.py
new file mode 100644
index 00000000..46b8d21a
--- /dev/null
+++ b/dw/tasks/judge.py
@@ -0,0 +1,68 @@
+"""
+Judge - score a candidate image against a rubric using a vision-language
+model.
+
+The first scorer for the select reducer (docs/proposals/score-and-select.md):
+`select` needs a number per candidate, and this is the cheapest way to get
+one without a purpose-built model - prompt the VLM `image_to_text` already
+loads with a rubric and a scale, and parse its reply to one number. Delegates
+to text_generation.generate_text, the same vision path image_to_text uses,
+rather than keeping a second copy of the pipeline handling.
+
+generate_text decodes greedily (do_sample=False - see its module docstring),
+so the same rubric and image already return the same reply every run; there
+is no sampling here for a step seed to thread through.
+"""
+
+import logging
+import re
+
+from .text_generation import generate_text, _DEFAULT_VISION_MODEL
+
+logger = logging.getLogger("dw")
+
+_DEFAULT_MODEL = _DEFAULT_VISION_MODEL
+
+_NUMBER_PATTERN = re.compile(r"-?\d+(?:\.\d+)?")
+
+
+def _judge_prompt(rubric, scale):
+    low, high = scale
+    return (
+        f"{rubric}\n\n"
+        f"Respond with a single number from {low} to {high} and nothing else."
+    )
+
+
+def judge(image, rubric, scale, device="cpu", **kwargs):
+    """Score an image against a rubric, returning one number.
+
+    Args:
+        image: PIL Image (or URL/path) to score.
+        rubric: The question or criterion to score the image against.
+        scale: [low, high] the score is expected to fall within.
+        device: Target device ("cuda", "mps", "cpu").
+        **kwargs:
+            model_name: HuggingFace model ID of a vision-language model
+                (default: image_to_text's default vision model).
+            max_new_tokens: Max tokens to generate (default: 20).
+
+    Returns:
+        The parsed score as a float.
+
+    Raises:
+        ValueError: the model's reply did not contain a number.
+    """
+    prompt = _judge_prompt(rubric, scale)
+    kwargs.setdefault("model_name", _DEFAULT_MODEL)
+    kwargs.setdefault("max_new_tokens", 20)
+
+    reply = generate_text(prompt, device=device, image=image, **kwargs)
+
+    match = _NUMBER_PATTERN.search(reply)
+    if match is None:
+        raise ValueError(f"judge: could not parse a score from the reply: {reply!r}")
+
+    score = float(match.group())
+    logger.info(f"Judged: {score}")
+    return score
diff --git a/dw/tasks/select.py b/dw/tasks/select.py
new file mode 100644
index 00000000..5000764b
--- /dev/null
+++ b/dw/tasks/select.py
@@ -0,0 +1,109 @@
+"""Reduce a list of candidates to one by a deterministic rule.
+
+The README's headline shape is N candidates -> choose one -> spend an
+expensive stage on the winner. Today that choice lives at the agent
+boundary (keep_output + asset:); this task is the version of it that needs
+no judgment - argmax, a threshold, or a fixed index - so the recipe stays
+inside the workflow and replays. See docs/proposals/score-and-select.md.
+"""
+
+import logging
+
+logger = logging.getLogger("dw")
+
+
+class Selected:
+    """The winning candidate, plus the metadata that makes the choice
+    replayable (position, score). Compares equal to its own value so a
+    caller that only wants the winner can treat it as one."""
+
+    def __init__(self, value, position, score):
+        self.value = value
+        self.position = position
+        self.score = score
+
+    def __eq__(self, other):
+        if isinstance(other, Selected):
+            return (
+                self.value == other.value
+                and self.position == other.position
+                and self.score == other.score
+            )
+        return self.value == other
+
+    def __hash__(self):
+        return hash(self.value)
+
+    def __repr__(self):
+        return f"Selected(value={self.value!r}, position={self.position}, score={self.score!r})"
+
+
+_THRESHOLD_RULES = {
+    "first_above": lambda score, threshold: score >= threshold,
+    "first_below": lambda score, threshold: score <= threshold,
+}
+
+
+def _parse_score(index, score):
+    if isinstance(score, bool) or not isinstance(score, (str, int, float)):
+        raise ValueError(f"select: score {index} is not a number: {score!r}")
+    try:
+        return float(score)
+    except (TypeError, ValueError):
+        raise ValueError(f"select: score {index} is not a number: {score!r}")
+
+
+def select(candidates, scores, rule, threshold=None, index=None):
+    """Task command: pick one candidate out of many by a fixed rule.
+
+    Args:
+        candidates: The values to choose among, in order.
+        scores: One number (or numeric string) per candidate, same length.
+        rule: "argmax" | "argmin" | "first_above" | "first_below" | "index"
+        threshold: Required by first_above/first_below.
+        index: Required by rule "index" - a position into candidates.
+
+    Returns:
+        A Selected wrapping the winning value, its position and its score.
+
+    Raises:
+        ValueError: length mismatch, a non-numeric score, an unknown rule,
+            a missing threshold/index, an out-of-range index, or (for
+            first_above/first_below) no candidate meeting the threshold.
+    """
+    if len(candidates) != len(scores):
+        raise ValueError(
+            f"select got {len(candidates)} candidates and {len(scores)} scores "
+            "- candidates and scores must be the same length"
+        )
+
+    parsed_scores = [_parse_score(i, s) for i, s in enumerate(scores)]
+
+    if rule in ("argmax", "argmin"):
+        positions = range(len(parsed_scores))
+        picker = max if rule == "argmax" else min
+        position = picker(positions, key=lambda i: parsed_scores[i])
+    elif rule in _THRESHOLD_RULES:
+        if threshold is None:
+            raise ValueError(f"select rule '{rule}' requires a threshold")
+        passes = _THRESHOLD_RULES[rule]
+        position = next(
+            (i for i, s in enumerate(parsed_scores) if passes(s, threshold)), None
+        )
+        if position is None:
+            raise ValueError(
+                f"select: no candidate passes rule '{rule}' at threshold {threshold}"
+            )
+    elif rule == "index":
+        if index is None:
+            raise ValueError("select rule 'index' requires an index")
+        if index < 0 or index >= len(candidates):
+            raise ValueError(
+                f"select: index {index} is out of range for {len(candidates)} candidates"
+            )
+        position = index
+    else:
+        raise ValueError(f"select: unknown rule: {rule!r}")
+
+    logger.debug(f"select: rule={rule} chose position {position}")
+    return Selected(value=candidates[position], position=position, score=parsed_scores[position])
diff --git a/dw/tasks/task.py b/dw/tasks/task.py
index ed8c9b1b..2a0db330 100644
--- a/dw/tasks/task.py
+++ b/dw/tasks/task.py
@@ -303,6 +303,15 @@ def _handle_compose_text(task, arguments, previous_pipelines):
     return compose_text(**arguments)
 
 
+@register_command("select", implementation="dw.tasks.select.select")
+def _handle_select(task, arguments, previous_pipelines):
+    """Reduce a list of candidates to one by a deterministic rule"""
+    logger.debug("Selecting")
+    from .select import select
+
+    return select(**arguments)
+
+
 @register_command(
     "format_chat_message", implementation="dw.tasks.format_messages.format_chat_message"
 )
@@ -437,6 +446,20 @@ def _handle_image_to_text(task, arguments, previous_pipelines):
     return image_to_text(image, device=task.device_for(arguments), **arguments)
 
 
+@register_command(
+    "judge",
+    implementation="dw.tasks.judge.judge",
+    consumes_device=True,
+)
+def _handle_judge(task, arguments, previous_pipelines):
+    """Score an image against a rubric with a vision-language model"""
+    logger.debug("Judging")
+    image = arguments.pop("image")
+    from .judge import judge
+
+    return judge(image, device=task.device_for(arguments), **arguments)
+
+
 @register_command(
     "transcribe_audio",
     implementation="dw.tasks.audio_transcription.transcribe_audio",
diff --git a/dw/workflow.py b/dw/workflow.py
index 0636060a..7777700e 100644
--- a/dw/workflow.py
+++ b/dw/workflow.py
@@ -13,6 +13,7 @@
     realize_constants,
     fetch_constant,
     is_constant_reference,
+    PREVIOUS_RESULT_PREFIX,
 )
 from .events import (
     RunContext,
@@ -33,6 +34,7 @@
 from .elision import elide_definition, warn_elided
 from .introspection import task_signature_errors
 from .task_domains import task_argument_errors
+from .select_validation import select_errors
 from .variable_constraints import (
     apply_constraints,
     constraint_errors,
@@ -244,6 +246,31 @@ def _allocated_mb():
     return stats["allocated_mb"] if stats["available"] else None
 
 
+def selected_field(step_data, selected):
+    """The manifest/step_end 'selected' block for a step's Result.selected.
+
+    Carries the winning position and score always; adds 'entry' - the
+    for_each member name ('shot@b') - only when the step's 'candidates'
+    argument was built from a gather: reference, recoverable at this point
+    only because step_data still holds the post-for_each-expansion,
+    pre-argument-resolution reference strings (dw/for_each.py's _gather()).
+    """
+    if selected is None:
+        return None
+
+    field = dict(selected)
+    candidates = step_data.get("task", {}).get("arguments", {}).get("candidates")
+    if isinstance(candidates, list):
+        position = selected.get("position")
+        if isinstance(position, int) and 0 <= position < len(candidates):
+            candidate = candidates[position]
+            if isinstance(candidate, str) and candidate.startswith(
+                PREVIOUS_RESULT_PREFIX
+            ):
+                field["entry"] = candidate[len(PREVIOUS_RESULT_PREFIX) :]
+    return field
+
+
 def release_unreferenced_results(results, remaining_refs):
     """Drop results no remaining reference can resolve to.
 
@@ -636,6 +663,12 @@ def validation_errors(self, arguments=None, composing=None):
             # sample rate a silent fallback to 44100 (dw/task_domains.py,
             # #139, #140)
             + task_argument_errors(expanded, source_indices)
+            # A select step whose rule is misspelled, or whose
+            # threshold/index does not match its rule, validated clean and
+            # died on select's own run-time ValueError after the fan-out
+            # ahead of it had already generated (dw/select_validation.py,
+            # docs/proposals/score-and-select.md)
+            + select_errors(expanded, source_indices)
             # A required task argument left unset validated as `valid: true`
             # and then failed the job on Python's own signature error, which
             # is the one mistake a free pre-flight most obviously exists for
@@ -1291,6 +1324,7 @@ def run(
                 # republished, so nothing downstream (job_for_file, the
                 # gallery) credits this run with writing them
                 subfolder = step_subfolder(step_data)
+                selected = selected_field(step_data, result.selected)
                 manifest_entry = {
                     "step": step.name,
                     "files": saved_files,
@@ -1298,6 +1332,8 @@ def run(
                 }
                 if reused:
                     manifest_entry["reused"] = True
+                if selected is not None:
+                    manifest_entry["selected"] = selected
                 # No entry at all for a step the parent saves for: the
                 # parent's own entry names the same files, under the step
                 # name the caller wrote (#92)
@@ -1309,6 +1345,8 @@ def run(
                 step_end_data = {"files": saved_files, "subfolder": subfolder}
                 if reused:
                     step_end_data["reused"] = True
+                if selected is not None:
+                    step_end_data["selected"] = selected
                 run_context.emit(
                     "step_end",
                     workflow=workflow_id,
diff --git a/tests/test_judge.py b/tests/test_judge.py
new file mode 100644
index 00000000..c358dd84
--- /dev/null
+++ b/tests/test_judge.py
@@ -0,0 +1,99 @@
+"""Tests for the judge task - scoring a candidate against a rubric."""
+
+import unittest
+from unittest.mock import patch, MagicMock
+from PIL import Image
+
+from dw.tasks.judge import judge, _DEFAULT_MODEL
+
+
+class TestJudge(unittest.TestCase):
+    """Judge prompts a vision-language model with a rubric and scale, and
+    parses the reply to one number. Mocked at the same seam image_to_text's
+    tests use, since judge runs through the same text_generation vision
+    path."""
+
+    def _make_image(self):
+        return Image.new("RGB", (64, 64), color="blue")
+
+    def _mock_pipe(self, mock_pipeline, generated):
+        pipe = MagicMock()
+        pipe.return_value = [{"generated_text": generated}]
+        mock_pipeline.return_value = pipe
+        return pipe
+
+    @patch("dw.tasks.text_generation.hf_pipeline")
+    def test_parses_a_clean_number(self, mock_pipeline):
+        self._mock_pipe(mock_pipeline, "7")
+
+        score = judge(self._make_image(), rubric="Sharpest image", scale=[0, 10], device="cpu")
+
+        self.assertEqual(score, 7.0)
+
+    @patch("dw.tasks.text_generation.hf_pipeline")
+    def test_parses_a_number_in_prose(self, mock_pipeline):
+        self._mock_pipe(mock_pipeline, "I would rate this a 8 out of 10 for sharpness.")
+
+        score = judge(self._make_image(), rubric="Sharpest image", scale=[0, 10], device="cpu")
+
+        self.assertEqual(score, 8.0)
+
+    @patch("dw.tasks.text_generation.hf_pipeline")
+    def test_no_number_in_reply_is_an_error(self, mock_pipeline):
+        self._mock_pipe(mock_pipeline, "I cannot judge this image.")
+
+        with self.assertRaises(ValueError) as ctx:
+            judge(self._make_image(), rubric="Sharpest image", scale=[0, 10], device="cpu")
+
+        message = str(ctx.exception)
+        self.assertIn("judge", message)
+        self.assertIn("I cannot judge this image.", message)
+
+    @patch("dw.tasks.text_generation.hf_pipeline")
+    def test_uses_default_model(self, mock_pipeline):
+        self._mock_pipe(mock_pipeline, "5")
+
+        judge(self._make_image(), rubric="Sharpest image", scale=[0, 10], device="cpu")
+
+        self.assertEqual(mock_pipeline.call_args[1]["model"], _DEFAULT_MODEL)
+
+    @patch("dw.tasks.text_generation.hf_pipeline")
+    def test_custom_model_name(self, mock_pipeline):
+        self._mock_pipe(mock_pipeline, "5")
+
+        judge(
+            self._make_image(),
+            rubric="Sharpest image",
+            scale=[0, 10],
+            device="cpu",
+            model_name="Qwen/Qwen2.5-VL-3B-Instruct",
+        )
+
+        self.assertEqual(
+            mock_pipeline.call_args[1]["model"], "Qwen/Qwen2.5-VL-3B-Instruct"
+        )
+
+    @patch("dw.tasks.text_generation.hf_pipeline")
+    def test_rubric_and_scale_are_in_the_prompt(self, mock_pipeline):
+        pipe = self._mock_pipe(mock_pipeline, "5")
+
+        judge(self._make_image(), rubric="Sharpest image", scale=[0, 10], device="cpu")
+
+        content = pipe.call_args[1]["text"][-1]["content"]
+        prompt_text = content[1]["text"]
+        self.assertIn("Sharpest image", prompt_text)
+        self.assertIn("0", prompt_text)
+        self.assertIn("10", prompt_text)
+
+
+class TestJudgeRegistration(unittest.TestCase):
+    """Test that judge is registered as a task command."""
+
+    def test_command_registered(self):
+        from dw.tasks.task import _COMMAND_REGISTRY
+
+        self.assertIn("judge", _COMMAND_REGISTRY)
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/tests/test_result.py b/tests/test_result.py
index 600c6061..0e2a947a 100644
--- a/tests/test_result.py
+++ b/tests/test_result.py
@@ -45,6 +45,15 @@ def test_add_string_strips_quotes(self):
         result.add_result('"test_string"  ')
         assert result.result_list == ["test_string"]
 
+    def test_add_selected_unwraps_value_and_records_metadata(self):
+        from dw.tasks.select import Selected
+
+        result = Result({})
+        result.add_result(Selected(value="b", position=1, score=0.9))
+
+        assert result.result_list == ["b"]
+        assert result.selected == {"position": 1, "score": 0.9}
+
     def test_get_artifacts_from_simple_list(self):
         result = Result({})
         result.add_result(["item1", "item2"])
diff --git a/tests/test_select.py b/tests/test_select.py
new file mode 100644
index 00000000..3bf9af7c
--- /dev/null
+++ b/tests/test_select.py
@@ -0,0 +1,101 @@
+"""select reduces a list of candidates to one by a deterministic rule, so a
+fan-out (for_each) can feed a single expensive stage without an agent in the
+loop - see docs/proposals/score-and-select.md."""
+
+import pytest
+
+from dw.tasks.select import select
+
+
+class TestSelect:
+    def test_argmax_returns_the_highest_scoring_candidate(self):
+        result = select(candidates=["a", "b", "c"], scores=[0.1, 0.9, 0.5], rule="argmax")
+        assert result.value == "b"
+        assert result.position == 1
+        assert result.score == 0.9
+
+    def test_argmin_returns_the_lowest_scoring_candidate(self):
+        result = select(candidates=["a", "b", "c"], scores=[0.1, 0.9, 0.5], rule="argmin")
+        assert result.value == "a"
+        assert result.position == 0
+        assert result.score == 0.1
+
+    def test_first_above_returns_the_first_candidate_meeting_the_threshold(self):
+        result = select(
+            candidates=["a", "b", "c"],
+            scores=[0.1, 0.9, 0.95],
+            rule="first_above",
+            threshold=0.8,
+        )
+        assert result.value == "b"
+        assert result.position == 1
+        assert result.score == 0.9
+
+    def test_first_below_returns_the_first_candidate_meeting_the_threshold(self):
+        result = select(
+            candidates=["a", "b", "c"],
+            scores=[0.9, 0.1, 0.05],
+            rule="first_below",
+            threshold=0.2,
+        )
+        assert result.value == "b"
+        assert result.position == 1
+        assert result.score == 0.1
+
+    def test_index_returns_the_candidate_at_that_position(self):
+        result = select(candidates=["a", "b", "c"], scores=[0.1, 0.9, 0.5], rule="index", index=2)
+        assert result.value == "c"
+        assert result.position == 2
+        assert result.score == 0.5
+
+    def test_ties_go_to_the_first_in_list_order(self):
+        result = select(candidates=["a", "b", "c"], scores=[0.5, 0.9, 0.9], rule="argmax")
+        assert result.value == "b"
+        assert result.position == 1
+
+    def test_a_string_score_is_parsed_once(self):
+        result = select(candidates=["a", "b"], scores=["0.1", "0.9"], rule="argmax")
+        assert result.value == "b"
+        assert result.score == 0.9
+
+    def test_a_prose_score_is_refused(self):
+        with pytest.raises(ValueError, match="score 1 is not a number"):
+            select(candidates=["a", "b"], scores=[0.1, "pretty good"], rule="argmax")
+
+    def test_length_mismatch_names_both_lengths(self):
+        with pytest.raises(ValueError, match="3 candidates.*2 scores"):
+            select(candidates=["a", "b", "c"], scores=[0.1, 0.9], rule="argmax")
+
+    def test_first_above_with_nothing_passing_is_an_error(self):
+        with pytest.raises(ValueError, match="no candidate"):
+            select(candidates=["a", "b"], scores=[0.1, 0.2], rule="first_above", threshold=0.5)
+
+    def test_first_below_with_nothing_passing_is_an_error(self):
+        with pytest.raises(ValueError, match="no candidate"):
+            select(candidates=["a", "b"], scores=[0.6, 0.7], rule="first_below", threshold=0.5)
+
+    def test_index_out_of_range_is_an_error(self):
+        with pytest.raises(ValueError, match="index 5"):
+            select(candidates=["a", "b"], scores=[0.1, 0.2], rule="index", index=5)
+
+    def test_an_unknown_rule_is_an_error(self):
+        with pytest.raises(ValueError, match="unknown rule"):
+            select(candidates=["a", "b"], scores=[0.1, 0.2], rule="top_k")
+
+
+class TestSelectAsATask:
+    def test_it_runs_through_the_task_dispatch(self):
+        from dw.tasks.task import Task
+
+        task = Task({"command": "select", "arguments": {}}, "cpu")
+
+        result = task.run(
+            {"candidates": ["a", "b", "c"], "scores": [0.1, 0.9, 0.5], "rule": "argmax"}
+        )
+
+        assert result == "b"
+
+    def test_command_registered(self):
+        from dw.tasks.task import _COMMAND_REGISTRY
+
+        assert "select" in _COMMAND_REGISTRY
diff --git a/tests/test_select_validation.py b/tests/test_select_validation.py
new file mode 100644
index 00000000..a93bcf56
--- /dev/null
+++ b/tests/test_select_validation.py
@@ -0,0 +1,153 @@
+"""Tests for static validation of select's arguments (docs/proposals/score-and-select.md #4).
+
+select's own run-time errors are covered by tests/test_select.py; these are
+the free pre-flight versions - a literal bad enough to refuse before the
+queue rather than a run started only to fail on its first reducer step.
+"""
+
+import unittest
+
+from dw.select_validation import select_errors
+
+
+def _step(name="pick", **arguments):
+    return {
+        "name": name,
+        "task": {"command": "select", "arguments": arguments},
+    }
+
+
+class TestSelectErrors(unittest.TestCase):
+    def test_unknown_rule_is_an_error(self):
+        definition = {"steps": [_step(rule="top_k", candidates=["a"], scores=[1])]}
+
+        errors = select_errors(definition, source_indices=[0])
+
+        self.assertEqual(len(errors), 1)
+        self.assertIn("rule", errors[0]["message"])
+        self.assertEqual(errors[0]["path"], "steps[0].task.arguments.rule")
+
+    def test_known_rule_is_fine(self):
+        definition = {
+            "steps": [_step(rule="argmax", candidates=["a", "b"], scores=[1, 2])]
+        }
+
+        errors = select_errors(definition, source_indices=[0])
+
+        self.assertEqual(errors, [])
+
+    def test_threshold_rule_without_threshold_is_an_error(self):
+        definition = {
+            "steps": [_step(rule="first_above", candidates=["a"], scores=[1])]
+        }
+
+        errors = select_errors(definition, source_indices=[0])
+
+        self.assertEqual(len(errors), 1)
+        self.assertIn("threshold", errors[0]["message"])
+
+    def test_threshold_rule_with_threshold_is_fine(self):
+        definition = {
+            "steps": [
+                _step(
+                    rule="first_above",
+                    candidates=["a"],
+                    scores=[1],
+                    threshold=0.5,
+                )
+            ]
+        }
+
+        errors = select_errors(definition, source_indices=[0])
+
+        self.assertEqual(errors, [])
+
+    def test_non_threshold_rule_with_threshold_is_an_error(self):
+        definition = {
+            "steps": [
+                _step(rule="argmax", candidates=["a"], scores=[1], threshold=0.5)
+            ]
+        }
+
+        errors = select_errors(definition, source_indices=[0])
+
+        self.assertEqual(len(errors), 1)
+        self.assertIn("threshold", errors[0]["message"])
+
+    def test_index_rule_without_index_is_an_error(self):
+        definition = {"steps": [_step(rule="index", candidates=["a"], scores=[1])]}
+
+        errors = select_errors(definition, source_indices=[0])
+
+        self.assertEqual(len(errors), 1)
+        self.assertIn("index", errors[0]["message"])
+
+    def test_index_rule_with_index_is_fine(self):
+        definition = {
+            "steps": [_step(rule="index", candidates=["a"], scores=[1], index=0)]
+        }
+
+        errors = select_errors(definition, source_indices=[0])
+
+        self.assertEqual(errors, [])
+
+    def test_non_index_rule_with_index_is_an_error(self):
+        definition = {
+            "steps": [_step(rule="argmax", candidates=["a"], scores=[1], index=0)]
+        }
+
+        errors = select_errors(definition, source_indices=[0])
+
+        self.assertEqual(len(errors), 1)
+        self.assertIn("index", errors[0]["message"])
+
+    def test_candidates_gather_scores_plain_list_is_an_error(self):
+        definition = {
+            "steps": [
+                _step(rule="argmax", candidates="gather:still", scores=[1, 2])
+            ]
+        }
+
+        errors = select_errors(definition, source_indices=[0])
+
+        self.assertEqual(len(errors), 1)
+        self.assertIn("candidates", errors[0]["message"])
+        self.assertIn("scores", errors[0]["message"])
+
+    def test_candidates_and_scores_both_gather_is_fine(self):
+        definition = {
+            "steps": [
+                _step(rule="argmax", candidates="gather:still", scores="gather:judge")
+            ]
+        }
+
+        errors = select_errors(definition, source_indices=[0])
+
+        self.assertEqual(errors, [])
+
+    def test_candidates_and_scores_both_plain_lists_is_fine(self):
+        definition = {
+            "steps": [_step(rule="argmax", candidates=["a", "b"], scores=[1, 2])]
+        }
+
+        errors = select_errors(definition, source_indices=[0])
+
+        self.assertEqual(errors, [])
+
+    def test_non_select_steps_are_ignored(self):
+        definition = {
+            "steps": [
+                {
+                    "name": "still",
+                    "task": {"command": "generate_image", "arguments": {}},
+                }
+            ]
+        }
+
+        errors = select_errors(definition, source_indices=[0])
+
+        self.assertEqual(errors, [])
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/tests/test_workflow.py b/tests/test_workflow.py
index dc668748..e51c3f78 100644
--- a/tests/test_workflow.py
+++ b/tests/test_workflow.py
@@ -797,6 +797,20 @@ def test_run_expands_for_each_and_names_the_members(tmp_path):
     assert names == ["shot@a", "shot@b", "edit"]
 
 
+def test_run_records_the_selected_field_on_manifest_and_step_end(tmp_path):
+    definition = _for_each_workflow()
+    definition["steps"][1]["task"] = {
+        "command": "select",
+        "arguments": {"candidates": "gather:shot", "scores": [0.1, 0.9], "rule": "argmax"},
+    }
+    workflow = _workflow_from(definition, tmp_path)
+
+    workflow.run({})
+
+    entry = next(e for e in workflow.manifest if e["step"] == "edit")
+    assert entry["selected"] == {"position": 1, "entry": "shot@b", "score": 0.9}
+
+
 def test_run_substitutes_the_callers_list(tmp_path):
     workflow = _workflow_from(_for_each_workflow(seed=1), tmp_path)
     workflow.run({"shots": [{"name": "only", "text": "X"}]})
diff --git a/tests/test_workflow_step_cache.py b/tests/test_workflow_step_cache.py
index b4a90f27..d36f2fcd 100644
--- a/tests/test_workflow_step_cache.py
+++ b/tests/test_workflow_step_cache.py
@@ -29,6 +29,7 @@ class FakeResult:
     def __init__(self):
         self.result_list = []
         self.saved_files = []
+        self.selected = None
 
     def save(self, output_dir, base_name):
         # Files are really written: a cache hit only counts when every file

From c15114bb77eb41a0cb1deb5739a976b68fe932ea Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Thu, 17 Sep 2026 19:45:36 -0500
Subject: [PATCH 17/77] docs(mcp): #203/#204 - document inline upload content=
 and get_output_audio

Updates docs/MCP.md and dw_mcp/CLAUDE.md for the upload_asset(content=...)
alternative to file_path and the new get_output_audio tool, and notes why
get_output_video is out of scope: the installed MCP SDK has no VideoContent
type to return it as.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 docs/MCP.md      | 35 ++++++++++++++++++++++-------------
 dw_mcp/CLAUDE.md | 11 ++++++++++-
 2 files changed, 32 insertions(+), 14 deletions(-)

diff --git a/docs/MCP.md b/docs/MCP.md
index 6994890c..2d448fb5 100644
--- a/docs/MCP.md
+++ b/docs/MCP.md
@@ -234,6 +234,7 @@ when no single workflow covers it.
 | Tool | Arguments | Purpose |
 | --- | --- | --- |
 | `get_output_image(name, max_dimension=768, workspace=None)` | `name`, `max_dimension`, `workspace` | Look at a generated image, downscaled to `max_dimension` on its longest side. Returns the image plus a text part reporting `original_size`, `returned_size` and `bytes`, so a downscale is never silent. `workspace` names the workspace for this one call without switching the session to it - the same pin `run_workflow` takes, so a job run into another workspace stays reachable from the session that queued it |
+| `get_output_audio(name, workspace=None)` | `name`, `workspace` | Listen to a generated audio output, as base64. Unlike `get_output_image` there is no downscale - a clip whose base64 size would exceed the same 4MB budget is refused outright rather than cut or transcoded, since a truncated clip is a different, misleading answer rather than a smaller correct one (#204). Use `download_output` or the gallery `url` for a longer file, and `get_gallery_metadata` for its duration and sample rate without fetching the bytes at all. `workspace` names the workspace for this one call without switching the session to it |
 | `get_output_text(name, max_characters=20000, workspace=None)` | `name`, `max_characters`, `workspace` | Read a text output — a prompt enhancement, or any step whose result is `text/plain` or JSON. Reports the file's real length and whether it was truncated. `workspace` names the workspace for this one call without switching the session to it - the same pin `run_workflow` takes, so a job run into another workspace stays reachable from the session that queued it |
 | `download_output(name, destination=None, overwrite=False, workspace=None)` | `name`, `destination`, `overwrite`, `workspace` | Save one output file to local disk, of any content type. `destination` may be a full path, a directory, or omitted to save under the output's own name in the current working directory; `~` expands and missing parent directories are created. `overwrite=True` is required to replace a file already at the resolved path. Over a `dw.serve --mcp` endpoint the file lands on the server, so the destination is confined to that workspace and a relative one is joined onto it. Returns nothing to the conversation but where the file landed — unlike the other media tools, the point is a file on disk, not a payload in context. Writes on the machine running the MCP server - over `dw.serve --mcp` that is the GPU box. A write that fails there (a path that exists only on the client, for instance) comes back as an error naming the server-side write and the client-side alternatives, not as an anonymous tool failure. `workspace` names the workspace for this one call without switching the session to it - the same pin `run_workflow` takes, so a job run into another workspace stays reachable from the session that queued it |
 | `delete_output(name, workspace=None)` | `name`, `workspace` | Permanently remove one generated file from the output directory. `workspace` names the workspace for this one call without switching the session to it - the same pin `run_workflow` takes, so a job run into another workspace stays reachable from the session that queued it |
@@ -256,7 +257,7 @@ The session starts in `default` and stays there unless it is told otherwise.
 | `delete_workspace(name, acknowledged_cost=False)` | `name`, `acknowledged_cost` | Permanently delete a workspace and everything in it. Refuses without the acknowledgement, reporting what it would remove |
 | `list_assets()` | — | The input media on the server, each with the `asset:` reference a workflow argument carries. Look here before asking for a file - what a workflow needs may already be there. `libraries` names the roots searched and which are writable; `shadowed` lists names a nearer library hides |
 | `keep_output(name, asset_name=None, overwrite=False, shared=False, workspace=None)` | `name`, optional `asset_name`, `overwrite`, `shared`, `workspace` | Keep a generated file as an input asset under a stable `asset:` name, so a later workflow can rely on it. The copy happens on the server: nothing is downloaded or re-uploaded. `asset_name` may name a folder and takes the kept file's extension when it has none; `shared=true` keeps it in the library every workspace shares, which is where a recurring cast belongs. `workspace` names the workspace for this one call without switching the session to it - the same pin `run_workflow` takes, so a job run into another workspace stays reachable from the session that queued it |
-| `upload_asset(file_path, asset_name=None, shared=False)` | `file_path` | Push a local image, video or audio file into the server's asset library and get back its `asset:` reference. The file is read from the machine the MCP server runs on, so this is how an input reaches a dw.serve running somewhere else. `asset_name` stores it under a readable name (`cast/priya-voice.wav`) instead of a random one; `shared=true` puts it in the library every workspace shares |
+| `upload_asset(file_path=None, content=None, asset_name=None, shared=False)` | exactly one of `file_path` or `content` (base64), optional `asset_name`, `shared` | Push an image, video or audio file into the server's asset library and get back its `asset:` reference. `file_path` is read from the machine the MCP server runs on, so this is how an input reaches a dw.serve running somewhere else - but only when the caller shares a filesystem with that machine. `content` is the alternative for an agent that does not: the bytes travel inline, base64-encoded, in the tool call itself, capped at 4MB (well under `file_path`'s 200MB) because inline bytes compete with the calling agent's own context budget rather than being a bulk-transfer path (#203). `asset_name` is required with `content` (there is no file name to infer one from) and, either way, stores it under a readable name (`cast/priya-voice.wav`) instead of a random one; `shared=true` puts it in the library every workspace shares |
 | `delete_asset(name)` | `name` | Permanently remove one file from the asset library, by the name `list_assets` reports. Deletes from whichever library holds it - this workspace's own before the shared one; one from a read-only examples library is refused. Any workflow still carrying that `asset:` reference stops loading |
 | `save_workflow(name, workflow)` | `name`, `workflow` | Save a workflow into the server's writable workflow directory, overwriting any existing workflow of that name there. A name that currently resolves to a read-only source (an examples directory) is not overwritten - the copy lands in the writable directory and shadows it |
 | `delete_workflow(name)` | `name` | Permanently delete a stored workflow |
@@ -451,18 +452,26 @@ default) for any server an MCP client can reach.
   events of a finished job (`MAX_PERSISTED_EVENTS` in the job history store).
   A job that ran before this feature existed returns an empty event list
   with a `note` explaining why.
-- **Images only.** `get_output_image` decodes and returns images; it refuses
-  video and audio outputs. Use `get_gallery_metadata` to inspect other media
-  kinds.
-- **Uploads read the MCP server's disk.** `upload_asset(file_path)` pushes a
-  local file into the asset library, but "local" means the machine `dw-mcp`
-  runs on. Over `dw.serve --mcp` that is the GPU box, so a file sitting on
-  the client's laptop is not reachable that way - put it on the server, or
-  give the workflow a URL (the arguments that take a path take a URL too).
-  On a `--mcp` endpoint `file_path` is also *confined* to the directories the
-  server works in (its workspace, workflows, assets, outputs and prompts), and
-  the refusal comes before the file is looked for, so the tool cannot be used
-  to probe which paths exist on the box (#138).
+- **Images and audio only.** `get_output_image` decodes and returns images,
+  `get_output_audio` audio; both refuse video. Use `get_gallery_metadata` to
+  inspect other media kinds. `get_output_audio` also refuses a clip whose
+  base64 size would exceed its 4MB budget rather than truncating or
+  transcoding it (#204) - there is no `VideoContent` type in the MCP SDK to
+  extend this pattern to video, so a `get_output_video` is a harder,
+  unresolved design question rather than a mechanical port.
+- **Uploads read the MCP server's disk, unless sent inline.**
+  `upload_asset(file_path)` pushes a local file into the asset library, but
+  "local" means the machine `dw-mcp` runs on. Over `dw.serve --mcp` that is
+  the GPU box, so a file sitting on the client's laptop is not reachable that
+  way - put it on the server, give the workflow a URL (the arguments that
+  take a path take a URL too), or use `upload_asset(content=..., asset_name=...)`
+  to send the bytes inline instead, base64-encoded in the call itself, capped
+  at 4MB (#203). On a `--mcp` endpoint `file_path` is also *confined* to the
+  directories the server works in (its workspace, workflows, assets, outputs
+  and prompts), and the refusal comes before the file is looked for, so the
+  tool cannot be used to probe which paths exist on the box (#138); `content`
+  reads no path and is not subject to this confinement, since no file on
+  either machine is ever named.
   `download_output` has the same asymmetry in the other direction: on a
   `--mcp` endpoint it writes on the GPU box, not the client's machine, and is
   confined to the workspace there.
diff --git a/dw_mcp/CLAUDE.md b/dw_mcp/CLAUDE.md
index eab337d1..82e6a07e 100644
--- a/dw_mcp/CLAUDE.md
+++ b/dw_mcp/CLAUDE.md
@@ -11,7 +11,16 @@ It covers the REST surface except the SSE event stream (whose polling twin
 assets), and the SPA's static mount. `POST /api/uploads` *is* covered, by `upload_asset`: an
 agent that can only name assets already on the box authors workflows it
 cannot supply inputs for, so the tool reads a file on this machine and pushes
-its bytes, returning the `asset:` reference rather than a path (`assets.py`). A session works in one of the server's workspaces: `--workspace` /
+its bytes, returning the `asset:` reference rather than a path (`assets.py`).
+`upload_asset` also takes `content` (base64) instead of `file_path`, for an
+agent with no filesystem in common with a remote `dw.serve --mcp` endpoint -
+the bytes travel inline in the call, capped at 4MB rather than `file_path`'s
+200MB since they compete with the caller's own context budget (#203).
+`get_output_audio` is `get_output_image`'s sibling for audio (`media.py`,
+#204): no downscale exists for a waveform, so a clip over the same 4MB
+budget is refused outright rather than cut short; video has neither, since
+the installed MCP SDK has no `VideoContent` type to return it as. A session
+works in one of the server's workspaces: `--workspace` /
 `DW_MCP_WORKSPACE` (a *name* on the server, not a directory - `DW_WORKSPACE`
 means something else to the engine), `use_workspace` to switch, and
 `DwClient._scoped` adds the selector to every request's query string so no

From 14e118fd165ad92351562709b4f2f7999c733622 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Thu, 17 Sep 2026 20:02:15 -0500
Subject: [PATCH 18/77] fix: #205 - audio sample_rate relabel silent at the
 engine save path

audio-trim-fade.json hardcoded result.sample_rate: 44100 on both steps,
so a 24kHz source shipped 1.84x sped up. Removing the forced rate lets
the source's real rate carry through; a caller wanting a specific rate
can add a resample_audio step.

That only fixed the symptom. The task-argument-level guard from #180
(_warn_on_rate_override) never covered this: a caller who passes the
source's own correct rate as a task argument sees a clean check, but
a result block that declares a different sample_rate still relabels
the file at save time with no warning. dw/result.py's save_artifact
now compares result_definition['sample_rate'] against the artifact's
carried rate and emits the same rate_override_mismatch warning when
they disagree, so the same mistake is caught however it enters -
argument or result block. Swept the other audio-producing templates
(minimax/music, minimax/music-video, dissolve-between-shots,
assemble-and-score) - their hardcoded rates only apply to freshly
generated, rate-less artifacts, which the new check correctly leaves
alone.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 dw/result.py                             | 23 +++++++---
 tests/test_result.py                     | 56 +++++++++++++++++++++++-
 workflows/templates/audio-trim-fade.json | 12 ++---
 3 files changed, 77 insertions(+), 14 deletions(-)

diff --git a/dw/result.py b/dw/result.py
index fbad76ac..c2ab2e89 100644
--- a/dw/result.py
+++ b/dw/result.py
@@ -625,11 +625,24 @@ def save_artifact(
             elif content_type.startswith("audio"):
                 waveforms = normalize_audio(artifact)
                 # Declared rate > the rate a generated track carries > default
-                sample_rate = (
-                    self.result_definition.get("sample_rate")
-                    or getattr(artifact, "sample_rate", None)
-                    or DEFAULT_AUDIO_SAMPLE_RATE
-                )
+                declared_rate = self.result_definition.get("sample_rate")
+                carried_rate = getattr(artifact, "sample_rate", None)
+                # A template's 'result.sample_rate' relabels the file at save
+                # time exactly the way a task argument's 'sample_rate' does -
+                # and #180's guard only caught the argument, not this. A
+                # caller who passed the source's own correct rate as the
+                # argument (so the argument-level check is clean) still got
+                # the wrong file with `warnings: []` when the *result* block
+                # hardcoded a different rate (#205). Same warning either way.
+                if (
+                    declared_rate is not None
+                    and carried_rate is not None
+                    and declared_rate != carried_rate
+                ):
+                    from .tasks.audio_utils import _warn_on_rate_override
+
+                    _warn_on_rate_override("save_artifact", carried_rate, declared_rate)
+                sample_rate = declared_rate or carried_rate or DEFAULT_AUDIO_SAMPLE_RATE
                 # A batched waveform holds several songs - save each one separately
                 if len(waveforms) > 1:
                     saved_files = []
diff --git a/tests/test_result.py b/tests/test_result.py
index 0e2a947a..b7fc7340 100644
--- a/tests/test_result.py
+++ b/tests/test_result.py
@@ -808,6 +808,12 @@ def test_a_batched_track_keeps_its_rate_across_the_recursion(self):
                 assert sample_rate == 22050
 
     def test_a_declared_rate_wins_over_the_one_the_track_carries(self):
+        # #205: the declared rate still wins - relabeling rather than
+        # resampling is what a template asked for - but unlike before, it no
+        # longer wins silently. A caller who checks `warnings` sees this one
+        # even though the task-argument-level guard (#180) had nothing to
+        # object to.
+        from dw.events import RunContext, activate_context, deactivate_context
         from dw.result import AudioTrack
 
         with tempfile.TemporaryDirectory() as temp_dir:
@@ -816,11 +822,59 @@ def test_a_declared_rate_wins_over_the_one_the_track_carries(self):
                 AudioTrack(numpy.zeros((1, 4410), dtype=numpy.float32), 24000)
             )
 
-            result.save(temp_dir, "line")
+            events = []
+            token = activate_context(RunContext(on_event=events.append))
+            try:
+                result.save(temp_dir, "line")
+            finally:
+                deactivate_context(token)
 
             _, sample_rate = soundfile.read(os.path.join(temp_dir, "line-0.0.wav"))
             assert sample_rate == 44100
 
+            warnings = [e for e in events if e.get("kind") == "rate_override_mismatch"]
+            assert len(warnings) == 1
+            assert warnings[0]["file_rate"] == 24000
+            assert warnings[0]["given_rate"] == 44100
+
+    def test_a_declared_rate_matching_the_carried_rate_is_not_a_warning(self):
+        from dw.events import RunContext, activate_context, deactivate_context
+        from dw.result import AudioTrack
+
+        with tempfile.TemporaryDirectory() as temp_dir:
+            result = Result({"content_type": "audio/wav", "sample_rate": 24000})
+            result.add_result(
+                AudioTrack(numpy.zeros((1, 4410), dtype=numpy.float32), 24000)
+            )
+
+            events = []
+            token = activate_context(RunContext(on_event=events.append))
+            try:
+                result.save(temp_dir, "line")
+            finally:
+                deactivate_context(token)
+
+            assert [e for e in events if e.get("kind") == "rate_override_mismatch"] == []
+
+    def test_a_declared_rate_with_no_carried_rate_is_not_a_warning(self):
+        # A generated artifact (e.g. a modular pipeline's dict output) carries
+        # no sample_rate of its own - declaring one is how it gets one at all,
+        # not an override of anything, so there is nothing to warn about.
+        from dw.events import RunContext, activate_context, deactivate_context
+
+        with tempfile.TemporaryDirectory() as temp_dir:
+            result = Result({"content_type": "audio/wav", "sample_rate": 44100})
+            result.add_result(numpy.zeros((1, 4410), dtype=numpy.float32))
+
+            events = []
+            token = activate_context(RunContext(on_event=events.append))
+            try:
+                result.save(temp_dir, "line")
+            finally:
+                deactivate_context(token)
+
+            assert [e for e in events if e.get("kind") == "rate_override_mismatch"] == []
+
     def test_a_batch_of_tracks_each_save_at_the_carried_rate(self):
         # Each item of a batched .audios is its own AudioTrack, so each is saved
         # as its own artifact at the rate it carries
diff --git a/workflows/templates/audio-trim-fade.json b/workflows/templates/audio-trim-fade.json
index 5dcf019c..dcfad219 100644
--- a/workflows/templates/audio-trim-fade.json
+++ b/workflows/templates/audio-trim-fade.json
@@ -6,8 +6,7 @@
     "start_seconds": 0.0,
     "duration_seconds": null,
     "fade_in_ms": 0,
-    "fade_out_ms": 4000,
-    "sample_rate": 44100
+    "fade_out_ms": 4000
   },
   "steps": [
     {
@@ -22,8 +21,7 @@
       },
       "result": {
         "content_type": "audio/wav",
-        "save": false,
-        "sample_rate": 44100
+        "save": false
       }
     },
     {
@@ -33,13 +31,11 @@
         "arguments": {
           "audio": "previous_result:trim",
           "fade_in_ms": "variable:fade_in_ms",
-          "fade_out_ms": "variable:fade_out_ms",
-          "sample_rate": "variable:sample_rate"
+          "fade_out_ms": "variable:fade_out_ms"
         }
       },
       "result": {
-        "content_type": "audio/mp3",
-        "sample_rate": 44100
+        "content_type": "audio/mp3"
       }
     }
   ]

From c8460f1512a558e4cf96b45b3b443d53c949e696 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Thu, 17 Sep 2026 20:11:22 -0500
Subject: [PATCH 19/77] docs(mcp): #206 - clarify get_health worker_alive means
 resident, not healthy

worker_alive is false whenever the on-demand model process hasn't started
yet (idle server, or after a memory clear) - a normal state, not a fault.
The get_health tool description previously read "whether the worker
process is up", which reads as a health/degradation signal and led #71's
tester to spend a paragraph investigating a non-issue. Updated the MCP
tool docstrings, docs/MCP.md, and an app.py comment to say what the field
actually measures.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 docs/MCP.md       |  2 +-
 dw/server/app.py  |  4 ++++
 dw_mcp/catalog.py |  6 ++++--
 dw_mcp/server.py  | 10 ++++++++--
 4 files changed, 17 insertions(+), 5 deletions(-)

diff --git a/docs/MCP.md b/docs/MCP.md
index 2d448fb5..aee5ff9f 100644
--- a/docs/MCP.md
+++ b/docs/MCP.md
@@ -223,7 +223,7 @@ when no single workflow covers it.
 | `get_task(command)` | `command` | Get a task command's argument schema |
 | `list_models()` | — | List what the Hugging Face model cache holds, largest first |
 | `get_memory()` | — | Get the worker's VRAM and RAM statistics. `gpu_*` is the card; `host_memory_rss_mb` / `host_memory_peak_rss_mb` are the worker process's resident and high-water host memory, beside the machine's `host_memory_total_mb` / `host_memory_available_mb` - read both, since an offloading workflow keeps its weights in host RAM and the card says little about what it holds (a host field is absent, not null, where the platform cannot measure it). `host_pinned_reserved_mb` / `host_pinned_allocated_mb`, when present, are torch's pinned-host cache - the staging buffers group offloading moves weights through, part of `host_memory_rss_mb` and invisible in every `gpu_*` figure, which is what a worker holding GB after releasing every model is usually holding (#98). `live: true` means `info` was measured now and is the worker's own memory; only live readings are comparable with each other. `live: false` with `info: null` (and `stale: false`) means nothing has been measured because nothing is resident; `live: false` with a populated `info` is a cached earlier reading, with `reason` (`job_running`, `worker_stopped`, `worker_busy`, `worker_unreachable`) and `age_seconds` - one cached while a job loads a model understates what is resident, so ask again when the server is idle rather than comparing it with a live figure |
-| `get_health()` | — | Check that the server is alive, and which machine answered: `version`, `device`, whether the worker process is up, the job running now and the queue depth |
+| `get_health()` | — | Check that the server is alive, and which machine answered: `version`, `device`, whether a model process is currently resident (`worker_alive`), the job running now and the queue depth. `worker_alive: false` is the normal idle state on a server that has not run a job since startup or the last memory clear - not a fault - the on-demand worker starts with the next job (#206) |
 | `get_server_info()` | — | What this installation can do and where it keeps things: `device` (the accelerator a run will use), `version`, the `workspace` this session is working in and the workflow/asset/output/prompt `directories` of *that* workspace, the bind address and port, whether a token is required, and whether MCP is mounted. Check the device before authoring - a CUDA-only choice (bitsandbytes, `torch.compile`, flash attention) is not available on an `mps` or `cpu` server |
 | `list_jobs(limit=20, status=None, workspace=None)` | optional `limit` (newest N), `status` (one state or a comma-separated set of `queued`, `running`, `succeeded`, `failed`, `cancelled`), `workspace` | List queued, running and recent jobs, **newest first**. Bounded by default: the unbounded listing was over a client's tool-result limit on a server with a few months of history, which made it a tool that could not be called at all. `total` says how many matched and `truncated`/`next` say so when the answer was cut - raise `limit` or narrow with `status`. Without `workspace`, a named workspace lists its own jobs and the default one lists every job the server holds |
 | `list_gallery(limit=50, subfolder=None, only_orphans=False, workspace=None)` | `limit`, `subfolder`, `only_orphans`, `workspace` | List generated output files, newest first. A name is `<workflow>/<run id>/<file>`, where `<file>` may sit in the subfolder the step chose (`final/episode.mp4`); each entry carries `folder` (the workflow) and `subfolder` (by convention `final` or `intermediate`, `''` when the step chose none, any path the workflow wrote otherwise), and `subfolder="final"` lists only deliverables. Each entry also carries a ready-made `url`, already scoped to the workspace that made it - a hand-built `/outputs/<name>` URL 404s for anything but the default workspace. `only_orphans=True` inverts the call: instead of files, it returns run directories with no media anywhere under them (`runs`, each `{name, mtime}`) - a run whose output was deleted before `delete_output` could remove it by name, or one that failed before writing anything; `subfolder` does not apply in this mode, and `name` is exactly what `delete_output` accepts (#170). `workspace` names the workspace for this one call without switching the session to it - the same pin `run_workflow` takes, so a job run into another workspace stays reachable from the session that queued it |
diff --git a/dw/server/app.py b/dw/server/app.py
index 843d745d..cae74b16 100644
--- a/dw/server/app.py
+++ b/dw/server/app.py
@@ -3486,6 +3486,10 @@ def health():
         return {
             "status": "ok",
             "version": __version__,
+            # on-demand subprocess: false on an idle server that hasn't run
+            # a job yet (or after a memory clear) is normal, not a fault -
+            # it means no model process is currently resident, not that the
+            # server is unhealthy (#206)
             "worker_alive": bool(
                 worker.worker_active
                 and worker.worker_process is not None
diff --git a/dw_mcp/catalog.py b/dw_mcp/catalog.py
index 22e9c430..4230d294 100644
--- a/dw_mcp/catalog.py
+++ b/dw_mcp/catalog.py
@@ -154,8 +154,10 @@ def get_memory(client):
 
 
 def get_health(client):
-    """Server liveness, plus what answered: version, device, worker
-    liveness, the job running now and how many are queued."""
+    """Server liveness, plus what answered: version, device, whether a
+    model process is currently resident, the job running now and how many
+    are queued. `worker_alive: false` is the normal idle state on a server
+    that hasn't run a job yet - not a degraded server."""
     return client.get_json("/api/health")
 
 
diff --git a/dw_mcp/server.py b/dw_mcp/server.py
index d14451d3..9021baa1 100644
--- a/dw_mcp/server.py
+++ b/dw_mcp/server.py
@@ -316,8 +316,14 @@ def get_memory() -> dict:
 
     def get_health() -> dict:
         """Check that the server is alive, and see what answered: its
-        version and accelerator, whether the worker process is up, the job
-        running now and how many are queued."""
+        version and accelerator, whether a model process is currently
+        resident, the job running now and how many are queued.
+
+        `worker_alive: false` on an otherwise healthy server (`status: ok`)
+        is the normal idle state, not a fault - the worker is an on-demand
+        subprocess that has not started yet because no job has run since
+        the server started or the last memory clear, and it starts with the
+        next job."""
         return catalog.get_health(client)
 
     def get_server_info() -> dict:

From f661b8c29d36e89994640d46b4511182b615ccbd Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Thu, 17 Sep 2026 21:00:03 -0500
Subject: [PATCH 20/77] fix: #211 - analyze_audio spectral bands now share
 rms_dbfs's scale

_spectral_balance summed per-bin amplitude (sqrt-mean-square of |rfft|),
a per-bin mean magnitude, not the band's share of the signal's power -
hence a constant ~40 dB offset under rms_dbfs on every track. Sum each
band's Parseval power instead (doubling non-DC/Nyquist bins for their
mirrored negative-frequency twin), so the three bands' powers add up to
mean(x**2) exactly and *_dbfs is comparable to compress_audio's
threshold_dbfs as the field name implies.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 docs/TASKS.md             |  7 +++++--
 dw/tasks/audio_utils.py   | 27 ++++++++++++++++++++-------
 tests/test_audio_utils.py | 10 ++++++++++
 3 files changed, 35 insertions(+), 9 deletions(-)

diff --git a/docs/TASKS.md b/docs/TASKS.md
index 082b4f40..526e4e98 100644
--- a/docs/TASKS.md
+++ b/docs/TASKS.md
@@ -829,8 +829,11 @@ rough low/mid/high spectral balance, the numbers a `compress_audio` or
 
 Returns a dict, not a track: `peak_dbfs`, `rms_dbfs`, `crest_factor_db`,
 `low_dbfs` (20-250 Hz), `mid_dbfs` (250-4000 Hz), `high_dbfs` (4000-20000 Hz).
-A silent track, or a band with no content at the track's sample rate, reads as
-`null` rather than `-inf`.
+The three bands are each a share of the track's total power on the same
+scale as `rms_dbfs` (their powers sum to it), so the loudest band sits near
+`rms_dbfs` rather than tens of dB under it - comparable to `compress_audio`'s
+`threshold_dbfs`. A silent track, or a band with no content at the track's
+sample rate, reads as `null` rather than `-inf`.
 
 ## Data Gathering
 
diff --git a/dw/tasks/audio_utils.py b/dw/tasks/audio_utils.py
index 40b1581f..b41272d2 100644
--- a/dw/tasks/audio_utils.py
+++ b/dw/tasks/audio_utils.py
@@ -1421,8 +1421,10 @@ def analyze_audio(audio, sample_rate=None):
 
     Returns:
         A dict: peak_dbfs, rms_dbfs, crest_factor_db (peak minus rms), and
-        a rough low_dbfs/mid_dbfs/high_dbfs spectral-balance reading. Any
-        value is None where a silent track leaves it undefined.
+        a rough low_dbfs/mid_dbfs/high_dbfs spectral-balance reading whose
+        three bands are shares of the same power that gives rms_dbfs, so
+        they sit on that scale rather than tens of dB under it. Any value
+        is None where a silent track leaves it undefined.
     """
     waveform, sample_rate = _waveform_and_rate(audio, sample_rate, "analyze_audio")
     check_arguments("analyze_audio", sample_rate=sample_rate)
@@ -1444,20 +1446,31 @@ def analyze_audio(audio, sample_rate=None):
 def _spectral_balance(waveform, sample_rate):
     """A rough low/mid/high energy reading in dBFS, from one FFT of the
     channel-averaged track - not a spectrogram, just enough to say whether
-    a track leans bright or boomy."""
+    a track leans bright or boomy.
+
+    Each band's power is a share of the same Parseval sum that gives
+    rms_dbfs (mean(x**2)): a one-sided rfft bin's power is doubled to
+    account for its mirrored negative-frequency twin, except the DC and
+    (for even n) Nyquist bins, which have no twin. Summed over the full
+    spectrum this equals mean(x**2) exactly, so a *_dbfs band sits on the
+    same scale as rms_dbfs rather than ~40 dB under it (#211)."""
     if waveform.size == 0:
         return {name: None for name in _SPECTRAL_BANDS}
     mono = waveform.mean(axis=0)
     n = mono.shape[0]
     spectrum = numpy.fft.rfft(mono)
-    amplitude = numpy.abs(spectrum) * (2.0 / n)
+    power = numpy.square(numpy.abs(spectrum), dtype=numpy.float64) / (n * n)
+    if n % 2 == 0:
+        power[1:-1] *= 2.0
+    else:
+        power[1:] *= 2.0
     freqs = numpy.fft.rfftfreq(n, d=1.0 / sample_rate)
     result = {}
     for name, (low, high) in _SPECTRAL_BANDS.items():
-        band = amplitude[(freqs >= low) & (freqs < min(high, sample_rate / 2.0))]
+        band = power[(freqs >= low) & (freqs < min(high, sample_rate / 2.0))]
         if band.size == 0:
             result[name] = None
             continue
-        energy = float(numpy.sqrt(numpy.mean(numpy.square(band, dtype=numpy.float64))))
-        result[name] = 20.0 * numpy.log10(energy) if energy > 0.0 else None
+        energy = float(numpy.sum(band))
+        result[name] = 10.0 * numpy.log10(energy) if energy > 0.0 else None
     return result
diff --git a/tests/test_audio_utils.py b/tests/test_audio_utils.py
index 34d18ce5..6ac091be 100644
--- a/tests/test_audio_utils.py
+++ b/tests/test_audio_utils.py
@@ -1181,6 +1181,16 @@ def test_a_low_tone_reads_louder_in_the_low_band_than_the_high_band(self):
 
         assert result["low_dbfs"] > result["high_dbfs"]
 
+    def test_a_tones_only_band_sits_on_the_same_scale_as_rms(self):
+        # #211: bands are shares of the same power that gives rms_dbfs, so
+        # a tone with all its energy in one band should read that band at
+        # (not tens of dB under) rms_dbfs.
+        from dw.tasks.audio_utils import analyze_audio
+
+        result = analyze_audio(self.tone(), sample_rate=8000)
+
+        assert result["low_dbfs"] == pytest.approx(result["rms_dbfs"], abs=0.05)
+
     def test_silence_reads_none_throughout(self):
         from dw.tasks.audio_utils import analyze_audio
 

From 6b63b780a9e7ecc76f572642d8c8e2e39ee4823e Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Thu, 17 Sep 2026 21:19:18 -0500
Subject: [PATCH 21/77] fix(server): #184 - echo workspace/output_dir the plan
 was probed against

cached_steps reads 0 both when nothing hit and when the cache probe ran
against the wrong workspace's output root (a validate call that omits
workspace= falls back to the caller's session workspace). Echoing
plan.workspace/plan.output_dir turns that ambiguity into something a
caller can read instead of a silent miss.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 dw/server/app.py     | 8 ++++++++
 tests/test_server.py | 6 +++++-
 2 files changed, 13 insertions(+), 1 deletion(-)

diff --git a/dw/server/app.py b/dw/server/app.py
index cae74b16..cc8b667b 100644
--- a/dw/server/app.py
+++ b/dw/server/app.py
@@ -948,6 +948,8 @@ def refuse(message, reason, plan):
                 "unplannable",
                 None,
             )
+        current["workspace"] = workspace.name
+        current["output_dir"] = workspace.outputs
         if current["fingerprint"] != acknowledged.fingerprint:
             refuse(
                 "The run's shape changed since it was acknowledged: the "
@@ -1749,6 +1751,12 @@ def validate_workflow(
             logger.exception("Plan could not be built")
             answer["plan"] = None
         if answer["plan"]:
+            # cached_steps is 0 both when nothing hit and when the probe ran
+            # against the wrong workspace's output root (#184) - echoing
+            # what it was actually probed against turns the second case
+            # from a silent miss into something a caller can read
+            answer["plan"]["workspace"] = workspace.name
+            answer["plan"]["output_dir"] = workspace.outputs
             answer["warnings"] += gate_warnings(answer["plan"]["downloads_required"])
         return answer
 
diff --git a/tests/test_server.py b/tests/test_server.py
index 0908a66e..257e8086 100644
--- a/tests/test_server.py
+++ b/tests/test_server.py
@@ -3793,6 +3793,9 @@ def test_an_old_history_database_gains_the_column(tmp_path):
     "downloads_required": [],
     "estimate": None,
 }
+# The route adds these to whatever build_plan() returns - the workspace the
+# plan (and any cache probe inside it) actually ran against (#184)
+PLAN_ROUTE_KEYS = {"workspace", "output_dir"}
 
 
 class TestValidatePlan:
@@ -3813,7 +3816,8 @@ def test_a_valid_answer_carries_a_plan(self, server, monkeypatch):
             ).json()
         assert result["valid"] is True
         plan = result["plan"]
-        assert set(plan) == set(EMPTY_PLAN)
+        assert set(plan) == set(EMPTY_PLAN) | PLAN_ROUTE_KEYS
+        assert plan["workspace"] == "default"
         assert plan["steps"] == 1
         assert plan["estimate"]["basis"] in {"catalog", "other_device"}
         assert plan["estimate"]["minutes"] == 2.0

From da32153b00763962db0af56fe1946ca10a0c3cb4 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Thu, 17 Sep 2026 21:33:29 -0500
Subject: [PATCH 22/77] fix: #212 - validate_workflow refuses result on
 scalar-returning steps

judge returns a bare float; a result block on such a step validated
clean and then died at run time inside save_artifact with
"write() argument must be str, not float", after the fan-out ahead of
it had already generated a full GPU run's worth of output.

register_command gains a returns="artifact"/"scalar" declaration
(judge is the only scalar-returning command today), read by a new
dw/scalar_result_validation.py rule wired into validation_errors so
this is a general, registry-level check rather than a judge-specific
name match - any future scalar-returning task is covered by declaring
itself. save_artifact also refuses a bare int/float/bool with a named
error, since a variable:-driven command name is only literal at run
time and so invisible to the static check.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 dw/result.py                           | 13 ++++
 dw/scalar_result_validation.py         | 78 +++++++++++++++++++++
 dw/tasks/task.py                       | 22 +++++-
 dw/workflow.py                         |  7 ++
 tests/test_scalar_result_validation.py | 97 ++++++++++++++++++++++++++
 5 files changed, 214 insertions(+), 3 deletions(-)
 create mode 100644 dw/scalar_result_validation.py
 create mode 100644 tests/test_scalar_result_validation.py

diff --git a/dw/result.py b/dw/result.py
index c2ab2e89..41cf22ea 100644
--- a/dw/result.py
+++ b/dw/result.py
@@ -578,6 +578,19 @@ def save_artifact(
             logger.warning(f"Skipping None artifact for {file_base_name}")
             return []
 
+        if isinstance(artifact, (int, float, bool)):
+            # Static validation (dw/scalar_result_validation.py, #212) refuses
+            # a 'result' block on a command declared to return a scalar, but
+            # a command name reached only through a 'variable:' is literal
+            # only at run time and so invisible to that check - this is the
+            # same refusal for the one path that can still get here, naming
+            # the value rather than failing inside soundfile/PIL/open() with
+            # a bare TypeError after the step's own work is already done
+            raise ValueError(
+                f"'{file_base_name}' is a {type(artifact).__name__} ({artifact!r}), "
+                "not an artifact - a 'result' block cannot save it"
+            )
+
         if isinstance(artifact, dict):
             # Recursively save dictionary items
             logger.debug(
diff --git a/dw/scalar_result_validation.py b/dw/scalar_result_validation.py
new file mode 100644
index 00000000..8628c91d
--- /dev/null
+++ b/dw/scalar_result_validation.py
@@ -0,0 +1,78 @@
+"""A `result` block on a step whose command returns a scalar, not an
+artifact (#212).
+
+`judge` returns a bare `float` - a natural fit for `result` to look like it
+applies (the guide's Result Configuration section describes saving text,
+and a score reads like one), but there is no file to write. `validate_workflow`
+answered `valid: true` and the run generated its full fan-out before dying
+deep inside `save_artifact` on `write() argument must be str, not float`,
+naming neither the step nor the command. Checked here against the command's
+own declared `returns` kind (`dw/tasks/task.py`'s `register_command`) rather
+than a name match on `judge`, so a future scalar-returning task is covered
+by declaring itself rather than by a second special case here.
+"""
+
+from .for_each import MEMBER_SEPARATOR, render_path
+from .tasks.task import task_command_info
+
+RESULT_KEY = "result"
+
+
+def scalar_result_errors(workflow_definition, source_indices=None):
+    """Every `result` block on a scalar-returning command, as [{path, message}].
+
+    The definition handed here has already been substituted and expanded,
+    so a step's `task.command` is literal. `source_indices`, when given, is
+    the source step index of each step - a `for_each` group turns one
+    written step into several, and the path an error carries has to be one
+    the author can find in the file they wrote; the member is named in the
+    message.
+    """
+    steps = workflow_definition.get("steps")
+    if not isinstance(steps, list):
+        return []
+
+    errors = []
+    for index, step in enumerate(steps):
+        if not isinstance(step, dict):
+            continue
+        result = step.get(RESULT_KEY)
+        if not isinstance(result, dict):
+            continue
+        task = step.get("task")
+        if not isinstance(task, dict):
+            continue
+        command = task.get("command")
+        if not isinstance(command, str):
+            continue
+        try:
+            info = task_command_info(command)
+        except ValueError:
+            continue
+        if info.get("returns") != "scalar":
+            continue
+
+        source = (
+            source_indices[index]
+            if source_indices is not None and index < len(source_indices)
+            else index
+        )
+        name = step.get("name")
+        where = (
+            f" in member '{name}'"
+            if isinstance(name, str) and MEMBER_SEPARATOR in name
+            else ""
+        )
+        errors.append(
+            {
+                "path": render_path(("steps", source, RESULT_KEY)),
+                "message": (
+                    f"{command} returns a number, not an artifact - "
+                    f"'result' cannot be saved{where}"
+                ),
+            }
+        )
+    return errors
+
+
+__all__ = ["scalar_result_errors"]
diff --git a/dw/tasks/task.py b/dw/tasks/task.py
index 2a0db330..1a07d1dc 100644
--- a/dw/tasks/task.py
+++ b/dw/tasks/task.py
@@ -33,7 +33,11 @@
 
 
 def register_command(
-    command_name: str, implementation=None, provided=(), consumes_device=False
+    command_name: str,
+    implementation=None,
+    provided=(),
+    consumes_device=False,
+    returns="artifact",
 ):
     """
     Decorator to register a command handler function.
@@ -53,6 +57,13 @@ def register_command(
             reach the implementation as an unexpected keyword argument (#185).
             Some commands (e.g. gather_inputs) receive a non-dict argument
             value, which never carries a device to drop
+        returns: "artifact" (the default - an image/video/audio/frames object
+            `Result.save` knows how to write) or "scalar" for a command whose
+            return value is a bare number with no file to save (`judge`). A
+            `result` block on a "scalar" command is refused in
+            `validation_errors` (dw/scalar_result_validation.py, #212) rather
+            than reaching `save_artifact` at run time, where a float has
+            nothing left identifying which command produced it
 
     Returns:
         Decorator function
@@ -73,6 +84,7 @@ def handler(task, arguments, previous_pipelines, _func=func):
             "kind": "command",
             "implementation": implementation,
             "provided": tuple(provided),
+            "returns": returns,
         }
         logger.debug(f"Registered command handler: {command_name}")
         return func
@@ -83,8 +95,11 @@ def handler(task, arguments, previous_pipelines, _func=func):
 def task_command_info(command_name):
     """Where a task command's argument schema lives: a dict with 'kind'
     ('command', 'image_processor' or 'video_processor'), 'implementation'
-    (dotted path or None for free-form), and 'provided'. Raises ValueError
-    for a name that is not a task command at all."""
+    (dotted path or None for free-form), 'provided', and 'returns'
+    ('artifact', the default, or 'scalar' for a bare-number command like
+    `judge` - missing entirely for an image/video processor, which is
+    always artifact-shaped). Raises ValueError for a name that is not a
+    task command at all."""
     info = _COMMAND_INFO.get(command_name)
     if info is not None:
         return info
@@ -450,6 +465,7 @@ def _handle_image_to_text(task, arguments, previous_pipelines):
     "judge",
     implementation="dw.tasks.judge.judge",
     consumes_device=True,
+    returns="scalar",
 )
 def _handle_judge(task, arguments, previous_pipelines):
     """Score an image against a rubric with a vision-language model"""
diff --git a/dw/workflow.py b/dw/workflow.py
index 7777700e..cc7cba52 100644
--- a/dw/workflow.py
+++ b/dw/workflow.py
@@ -44,6 +44,7 @@
 from .subfolders import step_subfolder, subfolder_errors
 from .reference_names import reference_name_errors
 from .content_types import content_type_errors
+from .scalar_result_validation import scalar_result_errors
 from .kernel_availability import kernel_availability_errors
 from .step import Step
 from .step_cache import (
@@ -641,6 +642,12 @@ def validation_errors(self, arguments=None, composing=None):
             # traceback naming neither the field nor the value
             # (dw/content_types.py, #168)
             + content_type_errors(expanded, source_indices)
+            # A 'result' block on a step whose command returns a scalar, not
+            # an artifact - judge's score validated clean and then died
+            # inside save_artifact with a bare TypeError after the fan-out
+            # ahead of it had already generated (dw/scalar_result_validation.py,
+            # #212)
+            + scalar_result_errors(expanded, source_indices)
             # A location policy refuses before a model load is spent on the
             # run rather than after it (dw/locations.py)
             + location_errors(expanded, source_indices, base_dir)
diff --git a/tests/test_scalar_result_validation.py b/tests/test_scalar_result_validation.py
new file mode 100644
index 00000000..7241790e
--- /dev/null
+++ b/tests/test_scalar_result_validation.py
@@ -0,0 +1,97 @@
+"""Tests for #212: `validate_workflow` refusing a `result` block on a step
+whose command returns a scalar rather than an artifact.
+
+`judge` returns a bare float; a `result` block on such a step validated
+clean and then died at run time inside `save_artifact` with
+`write() argument must be str, not float` after the fan-out ahead of it had
+already generated (#212). These are the free pre-flight versions.
+"""
+
+import unittest
+
+from dw.scalar_result_validation import scalar_result_errors
+
+
+def _step(name, command, result=None, arguments=None):
+    step = {"name": name, "task": {"command": command, "arguments": arguments or {}}}
+    if result is not None:
+        step["result"] = result
+    return step
+
+
+class TestScalarResultErrors(unittest.TestCase):
+    def test_result_on_judge_is_an_error(self):
+        definition = {
+            "steps": [
+                _step(
+                    "score",
+                    "judge",
+                    result={"content_type": "text/plain", "subfolder": "intermediate"},
+                )
+            ]
+        }
+
+        errors = scalar_result_errors(definition, source_indices=[0])
+
+        self.assertEqual(len(errors), 1)
+        self.assertEqual(errors[0]["path"], "steps[0].result")
+        self.assertIn("judge", errors[0]["message"])
+        self.assertIn("not an artifact", errors[0]["message"])
+
+    def test_no_result_on_judge_is_fine(self):
+        definition = {"steps": [_step("score", "judge")]}
+
+        errors = scalar_result_errors(definition, source_indices=[0])
+
+        self.assertEqual(errors, [])
+
+    def test_result_on_artifact_returning_command_is_fine(self):
+        definition = {
+            "steps": [
+                _step(
+                    "shot",
+                    "gather_images",
+                    result={"content_type": "image/png"},
+                )
+            ]
+        }
+
+        errors = scalar_result_errors(definition, source_indices=[0])
+
+        self.assertEqual(errors, [])
+
+    def test_unknown_command_is_ignored(self):
+        definition = {
+            "steps": [_step("mystery", "not_a_real_command", result={"content_type": "image/png"})]
+        }
+
+        errors = scalar_result_errors(definition, source_indices=[0])
+
+        self.assertEqual(errors, [])
+
+    def test_member_step_names_the_member_in_the_message(self):
+        definition = {
+            "steps": [
+                _step(
+                    "score@shot-1",
+                    "judge",
+                    result={"content_type": "text/plain"},
+                )
+            ]
+        }
+
+        errors = scalar_result_errors(definition, source_indices=[0])
+
+        self.assertEqual(len(errors), 1)
+        self.assertIn("member 'score@shot-1'", errors[0]["message"])
+
+    def test_non_dict_step_is_skipped(self):
+        definition = {"steps": ["not-a-step"]}
+
+        errors = scalar_result_errors(definition)
+
+        self.assertEqual(errors, [])
+
+
+if __name__ == "__main__":
+    unittest.main()

From f6eba429e6f31ae33117a8bd74161c70ea9686bb Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Fri, 18 Sep 2026 07:43:43 -0500
Subject: [PATCH 23/77] fix: #213 - select_errors catches gather:
 candidates/scores size mismatch

select_errors only compared whether candidates/scores were both gather:
references or both plain lists, never their resolved sizes. By the time
select_errors runs (post for_each expansion), a gather: reference has
already been replaced by the list of previous_result: references it drew
from - so the size mismatch between two differently-shaped for_each
fan-outs (e.g. candidates=gather:still with 2 entries, scores=gather:judge
with 1) validated clean and only surfaced as a run-time crash in select's
own reducer, after the fan-out ahead of it had already generated.

The issue's other rule - a previous_result: reference into a for_each step
must come from a for_each step over the same list - was already enforced
by _rewrite_reference in dw/for_each.py (predates #119 and #213); verified
against the issue's own repro JSON, which returns valid: false with that
exact error today.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 dw/select_validation.py         | 20 ++++++++++++++++++
 tests/test_select_validation.py | 36 +++++++++++++++++++++++++++++++++
 2 files changed, 56 insertions(+)

diff --git a/dw/select_validation.py b/dw/select_validation.py
index cadcfe5e..bb0c42ab 100644
--- a/dw/select_validation.py
+++ b/dw/select_validation.py
@@ -28,6 +28,18 @@ def _is_gather(value):
     return isinstance(value, str) and value.startswith("gather:")
 
 
+def _is_expanded_gather(value):
+    """A gather: reference after for_each expansion has replaced it with the
+    list of previous_result: references it drew from - the only form
+    select_errors ever actually sees once validation_errors expands the
+    definition before calling it."""
+    return (
+        isinstance(value, list)
+        and len(value) > 0
+        and all(isinstance(v, str) and v.startswith("previous_result:") for v in value)
+    )
+
+
 def select_errors(workflow_definition, source_indices=None):
     """Every select step whose arguments cannot be right, as [{path, message}]."""
     steps = workflow_definition.get("steps")
@@ -91,5 +103,13 @@ def add(key, message):
                     "'gather:' references or both plain lists, got "
                     f"candidates={candidates!r} scores={scores!r}",
                 )
+            elif _is_expanded_gather(candidates) and _is_expanded_gather(scores):
+                if len(candidates) != len(scores):
+                    add(
+                        "scores",
+                        "select: 'candidates' and 'scores' gather from "
+                        f"for_each groups of different sizes: candidates has "
+                        f"{len(candidates)} entries, scores has {len(scores)}",
+                    )
 
     return errors
diff --git a/tests/test_select_validation.py b/tests/test_select_validation.py
index a93bcf56..cd70c264 100644
--- a/tests/test_select_validation.py
+++ b/tests/test_select_validation.py
@@ -134,6 +134,42 @@ def test_candidates_and_scores_both_plain_lists_is_fine(self):
 
         self.assertEqual(errors, [])
 
+    def test_expanded_gather_size_mismatch_is_an_error(self):
+        # After for_each expansion a gather: reference has already been
+        # replaced by the list of previous_result: references it drew from -
+        # this is the shape select_errors actually sees in validation_errors.
+        definition = {
+            "steps": [
+                _step(
+                    rule="argmax",
+                    candidates=["previous_result:still@a", "previous_result:still@b"],
+                    scores=["previous_result:judge@x"],
+                )
+            ]
+        }
+
+        errors = select_errors(definition, source_indices=[0])
+
+        self.assertEqual(len(errors), 1)
+        self.assertIn("scores", errors[0]["path"])
+        self.assertIn("2 entries", errors[0]["message"])
+        self.assertIn("1", errors[0]["message"])
+
+    def test_expanded_gather_same_size_is_fine(self):
+        definition = {
+            "steps": [
+                _step(
+                    rule="argmax",
+                    candidates=["previous_result:still@a", "previous_result:still@b"],
+                    scores=["previous_result:judge@a", "previous_result:judge@b"],
+                )
+            ]
+        }
+
+        errors = select_errors(definition, source_indices=[0])
+
+        self.assertEqual(errors, [])
+
     def test_non_select_steps_are_ignored(self):
         definition = {
             "steps": [

From baba4c9e0d1b5389dd74aa0e0f31bad5e15f90ad Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Fri, 18 Sep 2026 08:10:23 -0500
Subject: [PATCH 24/77] fix(mcp): #214, #215 - surface match_levels clip-hold
 and gain as events; wire match_levels_dbfs into assemble-and-score

#214: match_levels (shared by concat_videos and dissolve_videos) applied
silently - a clip-held shot only reached logger.warning and every shot's
applied gain only reached logger.debug, neither visible over the API/MCP.
Switch both to emit_warning (kind match_levels_held, naming shot index,
measured level, gain, ceiling and shortfall) and emit_log respectively, so
a caller's warnings/events list carries what happened, mirroring bleed_join
(#198) and rate_override_mismatch (#180/#196).

#215: assemble-and-score.json never got the match_levels_dbfs variable/
argument that #128 added to dissolve-between-shots.json - add the same
variable declaration, step wiring, and a description sentence naming the
knob and the clip-hold behavior. Trimmed the description's first sentence
to keep the compact catalog listing under its token budget.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 dw/tasks/audio_utils.py                     | 36 ++++++++++++++----
 tests/test_concat_videos.py                 | 41 +++++++++++++++++++++
 workflows/templates/assemble-and-score.json |  6 ++-
 3 files changed, 73 insertions(+), 10 deletions(-)

diff --git a/dw/tasks/audio_utils.py b/dw/tasks/audio_utils.py
index b41272d2..a3e31d9a 100644
--- a/dw/tasks/audio_utils.py
+++ b/dw/tasks/audio_utils.py
@@ -14,7 +14,7 @@
 import soundfile
 import torch
 
-from ..events import emit_warning
+from ..events import emit_log, emit_warning
 from ..task_domains import as_number, check_arguments
 from ..security import (
     validate_file_extension,
@@ -974,18 +974,38 @@ def match_levels(waveforms, measure, target_dbfs=None, command="concat_videos"):
         if level is None:
             matched.append(waveform)
             continue
-        gain_db = target_dbfs - level
+        target_gain_db = target_dbfs - level
+        gain_db = target_gain_db
         peak = level_dbfs(waveform, "peak")
+        held = False
         if peak is not None and peak + gain_db > MATCH_CEILING_DBFS:
-            held = MATCH_CEILING_DBFS - peak
-            logger.warning(
+            gain_db = MATCH_CEILING_DBFS - peak
+            held = True
+            shortfall_db = target_gain_db - gain_db
+            # emit_warning rather than logger.warning: a clip-held shot stays
+            # off the target and the residual spread is exactly the level
+            # jump match_levels exists to remove (#214) - a caller reading
+            # the job's warnings list is the one who can act on it (#82)
+            emit_warning(
                 f"{command}: video {index + 1} would clip at the {measure} target "
-                f"({peak + gain_db:+.1f} dBFS peak) - held to {MATCH_CEILING_DBFS} dBFS"
+                f"({peak + target_gain_db:+.1f} dBFS peak) - held to "
+                f"{MATCH_CEILING_DBFS} dBFS, {shortfall_db:.1f} dB short of target",
+                kind="match_levels_held",
+                command=command,
+                index=index,
+                measure_dbfs=round(level, 1),
+                target_dbfs=target_dbfs,
+                gain_db=round(gain_db, 1),
+                shortfall_db=round(shortfall_db, 1),
+                ceiling_dbfs=MATCH_CEILING_DBFS,
             )
-            gain_db = held
-        logger.debug(
+        emit_log(
             f"{command}: video {index + 1} {measure} {level:.1f} dBFS, "
-            f"gain {gain_db:+.1f} dB"
+            f"gain {gain_db:+.1f} dB{' (held)' if held else ''}",
+            index=index,
+            measure_dbfs=round(level, 1),
+            gain_db=round(gain_db, 1),
+            held=held,
         )
         matched.append((waveform * (10 ** (gain_db / 20.0))).astype(numpy.float32))
     return matched
diff --git a/tests/test_concat_videos.py b/tests/test_concat_videos.py
index b415cc21..a8cb3ab0 100644
--- a/tests/test_concat_videos.py
+++ b/tests/test_concat_videos.py
@@ -506,6 +506,47 @@ def test_the_resample_warning_is_emitted_as_an_event(self):
         assert "resampling them all to 200 Hz" in warnings[0]["message"]
         assert "resample_audio" in warnings[0]["message"]
 
+    def test_the_clip_hold_is_emitted_as_a_warning_event(self):
+        """#214: match_levels applied silently - a shot held short of the
+        target only ever reached the server's log."""
+        from dw.events import RunContext, activate_context, deactivate_context
+
+        spiky = numpy.full((2, 100), 0.02, dtype=numpy.float32)
+        spiky[:, 50] = 0.9
+        video = AudioVideo(frames(4), spiky, 100)
+
+        events = []
+        token = activate_context(RunContext(on_event=events.append))
+        try:
+            concat_videos([video, audio_video(4, 0.02)], match_levels="rms")
+        finally:
+            deactivate_context(token)
+
+        warnings = [e for e in events if e.get("kind") == "match_levels_held"]
+        assert len(warnings) == 1
+        assert warnings[0]["command"] == "concat_videos"
+        assert warnings[0]["index"] == 0
+        assert warnings[0]["shortfall_db"] > 0
+        assert "held to" in warnings[0]["message"]
+
+    def test_per_shot_gain_is_emitted_as_a_log_event(self):
+        """#214: neither shot's applied gain reached the caller at all."""
+        from dw.events import RunContext, activate_context, deactivate_context
+
+        events = []
+        token = activate_context(RunContext(on_event=events.append))
+        try:
+            concat_videos(
+                [audio_video(4, 0.5), audio_video(4, 0.05)], match_levels="rms"
+            )
+        finally:
+            deactivate_context(token)
+
+        logs = [e for e in events if e["event"] == "log"]
+        assert len(logs) == 2
+        assert all("gain" in log["message"] for log in logs)
+        assert {log["index"] for log in logs} == {0, 1}
+
     def test_one_rate_emits_no_resample_warning(self):
         from dw.events import RunContext, activate_context, deactivate_context
 
diff --git a/workflows/templates/assemble-and-score.json b/workflows/templates/assemble-and-score.json
index 3c876785..d3cc4852 100644
--- a/workflows/templates/assemble-and-score.json
+++ b/workflows/templates/assemble-and-score.json
@@ -1,6 +1,6 @@
 {
     "id": "assemble-and-score",
-    "description": "Cuts shots that already exist into one film with a score under them, generating nothing in the run. It is the pass you re-run while cutting, when re-generating the footage each time would cost GPU hours to change a fade. The shots go straight into concat_videos as hard cuts - nothing is stabilized or rescaled on the way, so a deliberate camera move survives the edit; they must already share one size and frame rate, and the task refuses a set that does not. 'shots' is a list, so a diptych is two entries and a reel is however many the cut needs. The shots' own recorded sound is carried up to the score's sample rate and mixed underneath it, so the room tone of each world survives the edit instead of being replaced by music. Supply the shots and the score as asset: references - 'shot_1.mp4' and friends, uploaded with upload_asset or promoted from a generated run with keep_output. Shots generated independently also drift in loudness - 10 dB between two shots of one scene is ordinary - and no seam control can hide a level jump, because it is either side of the cut rather than at it; 'match_levels' ('rms' for perceived level, 'peak' for the loudest sample) evens the shots out before they are joined, and left null, as it is by default, a wide spread is warned about in the log rather than passing in silence. 'total_frames' is the length of the cut in frames and 'score' is a separate asset with its own length: the score is sliced to 'total_frames' from 'score_start_frame', and a score that does not reach that far is padded to it with digital silence, which leaves the rest of the film unscored under the shots' own sound (the run says so as a 'slice_past_end' warning, but the film itself sounds plausible). A score must therefore be at least as long as the cut; to stretch a short bed to reach, make a longer one with the 'loop_audio' task first and pass that as 'score'.",
+    "description": "Cuts existing shots into one scored film, generating nothing in the run. It is the pass you re-run while cutting, when re-generating the footage each time would cost GPU hours to change a fade. The shots go straight into concat_videos as hard cuts - nothing is stabilized or rescaled on the way, so a deliberate camera move survives the edit; they must already share one size and frame rate, and the task refuses a set that does not. 'shots' is a list, so a diptych is two entries and a reel is however many the cut needs. The shots' own recorded sound is carried up to the score's sample rate and mixed underneath it, so the room tone of each world survives the edit instead of being replaced by music. Supply the shots and the score as asset: references - 'shot_1.mp4' and friends, uploaded with upload_asset or promoted from a generated run with keep_output. Shots generated independently also drift in loudness - 10 dB between two shots of one scene is ordinary - and no seam control can hide a level jump, because it is either side of the cut rather than at it; 'match_levels' ('rms' for perceived level, 'peak' for the loudest sample) evens the shots out before they are joined, and left null, as it is by default, a wide spread is warned about in the log rather than passing in silence. 'match_levels_dbfs' sets the level match_levels moves every shot to, below its own default; a shot whose gain to that level would clip is held short of it instead, and the run says so rather than leaving the shots still apart after a match. 'total_frames' is the length of the cut in frames and 'score' is a separate asset with its own length: the score is sliced to 'total_frames' from 'score_start_frame', and a score that does not reach that far is padded to it with digital silence, which leaves the rest of the film unscored under the shots' own sound (the run says so as a 'slice_past_end' warning, but the film itself sounds plausible). A score must therefore be at least as long as the cut; to stretch a short bed to reach, make a longer one with the 'loop_audio' task first and pass that as 'score'.",
     "cost": [
         {
             "device": "cuda",
@@ -24,6 +24,7 @@
         "audio_bleed_ms": 0,
         "seam_fade_ms": null,
         "match_levels": null,
+        "match_levels_dbfs": null,
         "score_start_frame": 0,
         "total_frames": 360,
         "score_gain": 1.0,
@@ -39,7 +40,8 @@
                     "fps": "variable:fps",
                     "audio_bleed_ms": "variable:audio_bleed_ms",
                     "seam_fade_ms": "variable:seam_fade_ms",
-                    "match_levels": "variable:match_levels"
+                    "match_levels": "variable:match_levels",
+                    "match_levels_dbfs": "variable:match_levels_dbfs"
                 }
             }
         },

From 5bf862fb7b3e7fee0b542f7577d7f2979c22a126 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Fri, 18 Sep 2026 10:35:37 -0500
Subject: [PATCH 25/77] fix(mcp): #197 - write fitted in-memory audio back onto
 the AudioVideo artifact

save_audio_video's _fit_audio_to_frames call only ever adjusted the local
variable used for muxing, never the artifact object itself. That same
AudioVideo instance is what a later previous_result: consumer
(concat_videos, dissolve_videos) reads directly out of the result store,
bypassing save() entirely - so a per-shot file could be correct while a
chain built from those shots still drifted.

Adds a regression test at the concat level (previous_result: chain
semantics), not just the per-shot save, per the prior triage diagnosis.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 dw/result.py                |  8 +++++++
 tests/test_concat_videos.py | 42 ++++++++++++++++++++++++++++++++++++-
 tests/test_result.py        | 15 +++++++++++++
 3 files changed, 64 insertions(+), 1 deletion(-)

diff --git a/dw/result.py b/dw/result.py
index 41cf22ea..d3963752 100644
--- a/dw/result.py
+++ b/dw/result.py
@@ -795,12 +795,20 @@ def save_audio_video(self, artifact, output_path, content_type):
         # here instead of being trimmed there (#197). Segment-backed frames are
         # written by the chain pipeline processor, which already carries its own
         # fps and does its own segment-length accounting - left alone.
+        #
+        # Written back onto the artifact, not just the local used for muxing:
+        # this same AudioVideo instance is what a later previous_result:
+        # consumer (concat_videos, dissolve_videos) reads directly out of the
+        # result store, so a local-only fit left the artifact's own audio
+        # unfitted and a chain built from in-memory shots still drifted even
+        # though each shot's own saved file was correct (#197 reopened).
         if audio is not None and sample_rate is not None and fps and not hasattr(
             artifact.frames, "cleanup"
         ):
             from .tasks.video_utils import _fit_audio_to_frames
 
             audio = _fit_audio_to_frames(audio, len(artifact.frames), fps, sample_rate)
+            artifact.audio = audio
 
         # Segment-backed frames (a chained step with save_segments) replay from
         # disk one segment at a time, so the final video is streamed instead of
diff --git a/tests/test_concat_videos.py b/tests/test_concat_videos.py
index a8cb3ab0..0d95afc1 100644
--- a/tests/test_concat_videos.py
+++ b/tests/test_concat_videos.py
@@ -3,6 +3,7 @@
 chained pipeline step's stitching.
 """
 
+import tempfile
 from unittest.mock import patch
 
 import numpy
@@ -10,7 +11,7 @@
 import torch
 from PIL import Image
 
-from dw.result import AudioVideo, get_artifact_list
+from dw.result import AudioVideo, Result, get_artifact_list
 from dw.tasks.concat_videos import concat_videos
 from dw.tasks.task import Task
 
@@ -147,6 +148,45 @@ def test_the_result_is_a_single_artifact(self):
         assert len(get_artifact_list(result)) == 1
 
 
+class TestPreviousResultChainAudioFit:
+    """#197 reopened: a per-shot artifact's own saved file could be correct
+    while the artifact object still held unfitted audio, because the fit in
+    save_audio_video only ever adjusted a local variable used for muxing. A
+    later previous_result: consumer such as concat_videos reads the artifact
+    straight out of the result store, bypassing save() entirely - so the
+    regression has to be proven at the concat output, not the per-shot file.
+    """
+
+    def shot(self, num_frames, sample_count, fps=24, sample_rate=1000):
+        # Mirrors what a codec mux leaves behind: audio slightly off the
+        # exact frame-derived length, the drift save_audio_video is meant
+        # to absorb before the artifact is handed to a later step.
+        audio = torch.zeros((2, sample_count))
+        artifact = AudioVideo(frames(num_frames), audio, sample_rate)
+        result = Result({"content_type": "video/mp4", "fps": fps})
+        result.add_result(artifact)
+        with (
+            patch("dw.result.encode_video"),
+            patch("dw.result.export_to_video"),
+            patch("dw.result.is_av_available", return_value=True),
+        ):
+            with tempfile.TemporaryDirectory() as temp_dir:
+                result.save(temp_dir, "test")
+        # What a previous_result: reference resolves to: the same artifact
+        # object save() just mutated, not a copy.
+        return artifact
+
+    def test_concat_output_reflects_the_fit_not_the_raw_shots(self):
+        # 48 frames @ 24fps @ 1000Hz -> 2000 samples exactly, each shot
+        # generated with codec-padding drift on either side of that.
+        first = self.shot(48, 1900)  # padded up to 2000
+        second = self.shot(48, 2100)  # trimmed down to 2000
+
+        result = concat_videos([first, second], fps=24)
+
+        assert result.audio.shape == (2, 4000)
+
+
 class TestTaskDispatch:
     def test_concat_videos_runs_through_task(self):
         task = Task({"command": "concat_videos", "arguments": {}}, "cpu")
diff --git a/tests/test_result.py b/tests/test_result.py
index b7fc7340..ada1489c 100644
--- a/tests/test_result.py
+++ b/tests/test_result.py
@@ -646,6 +646,21 @@ def test_audio_is_padded_to_frame_count_for_in_memory_generation(self):
 
         assert encode.call_args.kwargs["audio"].shape == (2, 2000)
 
+    def test_fit_is_written_back_onto_the_artifact(self):
+        # #197 reopened again: the fit above only ever adjusted the local
+        # `audio` used for muxing, so the AudioVideo instance kept in the
+        # result store - the same object a later previous_result: consumer
+        # like concat_videos reads directly, without going through save() -
+        # still carried the unfitted waveform. A chain built from in-memory
+        # shots drifted even though each shot's own saved file was correct.
+        frames = ["frame"] * 48
+        audio = torch.zeros((2, 1900))  # 48 frames @ 24fps @ 1000Hz -> 2000
+        artifact = AudioVideo(frames, audio, 1000)
+
+        self.save({"content_type": "video/mp4", "fps": 24}, artifact)
+
+        assert artifact.audio.shape == (2, 2000)
+
     def test_result_definition_overrides_the_sample_rate(self):
         artifact = AudioVideo("frames", torch.zeros((2, 100)), 48000)
 

From 4b4979aeaca1076b07c6b340977b4fa378aafa77 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Fri, 18 Sep 2026 10:42:55 -0500
Subject: [PATCH 26/77] fix(server): #216 - name the wrapper in PUT
 /api/workflows error, cross-reference job-workflow docs

The 400 on a bare workflow body said "Provide an inline workflow" without
saying what form was expected; it now names the wrapper directly. SERVER.md
and MCP.md each documented GET /api/jobs/{id}/workflow and get_job_workflow
without pointing at the other, so a reader following one surface's docs
couldn't find the equivalent on the other.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 docs/MCP.md      | 2 +-
 docs/SERVER.md   | 2 +-
 dw/server/app.py | 5 ++++-
 3 files changed, 6 insertions(+), 3 deletions(-)

diff --git a/docs/MCP.md b/docs/MCP.md
index aee5ff9f..e92b0422 100644
--- a/docs/MCP.md
+++ b/docs/MCP.md
@@ -285,7 +285,7 @@ references written in the same session.
 | --- | --- | --- |
 | `run_workflow(workflow_path=None, inline_workflow=None, arguments=None, acknowledged_cost=False, workspace=None)` | exactly one of `workflow_path` (a catalog name from `list_workflows`, with or without `.json`, or a path to a workflow file on the server) or `inline_workflow`, optional `arguments`, `acknowledged_cost`, `workspace` | Queue a workflow for generation. Returns as soon as the job is queued. `workspace` names the workspace for this one call without switching the session to it - use it to pin a job whose `output:` or `asset:` references live in a workspace other than the session's - `acknowledged_cost` is `true` or the bound `{fingerprint, minutes, downloads}` from the validate plan; a 409 means the plan changed and the message carries the new estimate |
 | `get_job(job_id)` | `job_id` | Get a job's status, warnings, output manifest, error and traceback; each manifest entry's `subfolder` is the in-run subfolder the step declared - by convention `final` for the deliverable, `intermediate` for scratch, `''` for none. A running job also carries `progress` (below) |
-| `get_job_workflow(job_id)` | `job_id` | The workflow the job actually ran. `realized: true` means every mutable input is pinned (arguments, seed, prompts, `output:latest`); `false` means the job predates run tracking and this is the definition as submitted. Pass it to `save_workflow` to keep it under a name |
+| `get_job_workflow(job_id)` | `job_id` | The REST equivalent is `GET /api/jobs/{id}/workflow` (see [SERVER.md](SERVER.md#jobs-api)). The workflow the job actually ran. `realized: true` means every mutable input is pinned (arguments, seed, prompts, `output:latest`); `false` means the job predates run tracking and this is the definition as submitted. Pass it to `save_workflow` to keep it under a name |
 | `export_job(job_id, overwrite=False)` | `job_id`, `overwrite` | Gather one finished job into `<workspace>/exports/<job id>/` on the server: the realized workflow, the run's manifest, the job row, a README, and copies of the assets, earlier-run inputs and outputs. Returns the directory, a zip URL, the file list with sizes and the total. The three JSON files are in the zip, not repeated here - get_job_workflow and get_job serve them individually. **The directory is on the machine running the server**, like `download_output`'s destination - fetch the zip URL and unpack it into `exports/` under the session's working directory (a deliverable, not a temp file); the archive already unpacks into one folder named after the job id |
 | `get_job_events(job_id, after=-1, limit=200)` | `job_id`, `after`, `limit` | Get a page of a job's progress events |
 | `wait_for_job(job_id, timeout_seconds=20)` | `job_id`, `timeout_seconds` | Block until a job reaches a terminal status, or `timeout_seconds` elapses. **One call blocks for at most 55 seconds** — a larger `timeout_seconds` is clamped, not honoured, because no MCP client holds a tool call open for a generation's real runtime, so budget one call per ~55s of the job. Every reply carries `waited_seconds`, `timeout_requested_seconds`, `timeout_applied_seconds` and `timeout_capped`, so a capped return is distinguishable from an elapsed one. Use instead of hand-polling `get_job`/`get_job_events` in a loop; if it returns `still_running: true`, call it again. Returns a slim job - status, warnings, error, and the manifest once finished - without the arguments; `get_job` has those. A running job also carries `progress` (below) |
diff --git a/docs/SERVER.md b/docs/SERVER.md
index 6e893a55..db041ef3 100644
--- a/docs/SERVER.md
+++ b/docs/SERVER.md
@@ -149,7 +149,7 @@ from another machine:
 | `POST /api/jobs` | Queue a run: `{"workflow_path": ...}` or an inline `{"workflow": {...}, "base_dir": ...}`, plus `arguments` for variable overrides. `workflow_path` accepts a stored workflow name as listed by `/api/workflows` (with or without `.json`, nested names included), or a relative/absolute path that still resolves under `--workflow-dir` - confined the same way the `/api/workflows` CRUD routes are; a path that names a real file outside that directory is rejected with 400, not opened. Answers with argument warnings from signature checking. Takes an optional `acknowledged_cost`: `true` is recorded as `acknowledged: boolean`; the object `{fingerprint, minutes, downloads}` from a validate answer's `plan` is `bound` - the server re-plans the run for the arguments given and answers **409** when the fingerprint differs or a repo in `downloads_required` is not in `downloads` (a download that has since vanished is not a refusal); the body is `{"detail": {message, reason: "fingerprint" \| "downloads" \| "unplannable", acknowledged, plan}}` with the current plan, so the caller re-quotes from it. `minutes` is recorded, never compared. Nothing is required: the web UI and every caller that sends nothing are `acknowledged: none`, and every job answer and history row carries `acknowledged` (and `acknowledged_cost` when bound). `POST /api/jobs/{id}/rerun` takes the same field and checks against the stored spec; a fresh seed does not change a fingerprint. |
 | `GET /api/jobs?workspace=&status=&limit=` | Queue + history summaries, oldest first, with `total` beside them. `status` narrows to one state or a comma-separated set (`queued`, `running`, `succeeded`, `failed`, `cancelled`; anything else is a 400); `limit` keeps the newest N, and `total` still reports how many matched, so a bounded answer cannot be mistaken for a complete one. No parameters means every job, which is what the web UI polls |
 | `GET /api/jobs/{id}` | Full detail: spec, events, manifest, error. A manifest entry for a step served from the step cache carries `reused: true`. Every entry carries `subfolder` - the in-run subfolder the step's `result.subfolder` chose, `''` for none. A `for_each` step appears in the manifest as its members (`shot@wide_open`, `shot@closeup`), because the manifest records what ran; the run's `workflow.json` keeps the `for_each` form, because it records what was asked |
-| `GET /api/jobs/{id}/workflow` | The workflow the job ran: `{id, definition, realized, seed_variable}`. `seed_variable` names the variable a `new_seed` rerun would draw into (null when the workflow has none), read from the workflow as written rather than the realized copy, whose seed is pinned. `realized: true` is the copy the run itself wrote (`workflow.json` in its run directory), with arguments, seed, prompts and `output:latest` pinned; `false` falls back to the submitted definition, which is what a job from before run tracking has. 404 means neither is readable - the job itself still is |
+| `GET /api/jobs/{id}/workflow` | The workflow the job ran: `{id, definition, realized, seed_variable}`. `seed_variable` names the variable a `new_seed` rerun would draw into (null when the workflow has none), read from the workflow as written rather than the realized copy, whose seed is pinned. `realized: true` is the copy the run itself wrote (`workflow.json` in its run directory), with arguments, seed, prompts and `output:latest` pinned; `false` falls back to the submitted definition, which is what a job from before run tracking has. 404 means neither is readable - the job itself still is. The equivalent MCP tool is `get_job_workflow` (see [MCP.md](MCP.md#diagnose)) |
 | `POST /api/jobs/{id}/export?workspace=&overwrite=` | Gather one finished job into `<workspace>/exports/<job id>/`: `workflow.json`, `manifest.json`, `job.json`, `README.md`, `assets/`, `inputs/`, `outputs/`. 201 with the file list, total bytes, anything it could not find, a `zip_url`, and the three JSON files inline. 404 unknown job, 409 for a job still running or an existing export without `overwrite` |
 | `GET /exports/{id}.zip?workspace=` | The same tree as one archive, built on request rather than kept as a second copy. Entries are named `<job id>/<relative path>`. Ungated exactly as `/outputs` is |
 | `GET /api/jobs/{id}/events` | Server-sent events stream; `?after=N` / `Last-Event-ID` replay missed events, so reconnects are lossless. Every event carries `seq` and `at` - seconds since the job started (since it was queued, for the events before that) - so a step's cost is a subtraction: `step_start` to `generating` is what a reused pipeline still pays before it runs, `generating` to the first `pipeline_step` is the prompt and reference encoding |
diff --git a/dw/server/app.py b/dw/server/app.py
index cc8b667b..8511b415 100644
--- a/dw/server/app.py
+++ b/dw/server/app.py
@@ -1937,7 +1937,10 @@ def save_workflow(
         and shadows it from then on.
         """
         if request.workflow is None:
-            raise HTTPException(status_code=400, detail="Provide an inline workflow")
+            raise HTTPException(
+                status_code=400,
+                detail='Provide the definition as {"workflow": {...}}',
+            )
         path, _source = resolve_writable_workflow(_sources_for(ws), name)
         candidate = Workflow(
             copy.deepcopy(request.workflow),

From 25fdc68b75eab9a4204bfe3db91250d665db47f7 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Fri, 18 Sep 2026 12:28:09 -0500
Subject: [PATCH 27/77] fix(mcp): #197 - memoize get_artifact_list per Result
 so the audio-fit write-back is visible to every consumer

save_audio_video (5bf862f) writes the frame-fit audio back onto the
AudioVideo artifact it extracted, but get_artifact_list rebuilt a fresh
AudioVideo from the same raw pipeline output on every call. A
previous_result: consumer that re-extracts independently (e.g. a
per-shot gain_audio tap), rather than reusing the object save() already
fitted, got the original unfitted waveform back - the write-back only
ever reached a consumer that happened to receive the same object
instance (concat_videos).

Result._artifacts_for memoizes get_artifact_list(result) by id(result),
so every extraction of a given raw result within one Result instance's
lifetime returns the same object(s). result_list itself is untouched,
so Result.retainable's attribute walk is unaffected.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 dw/result.py         | 24 ++++++++++++++++++++++--
 tests/test_result.py | 33 +++++++++++++++++++++++++++++++++
 2 files changed, 55 insertions(+), 2 deletions(-)

diff --git a/dw/result.py b/dw/result.py
index d3963752..8a72edce 100644
--- a/dw/result.py
+++ b/dw/result.py
@@ -360,6 +360,10 @@ def __init__(self, result_definition):
         # warning from the waveform it was handed, so the written-level
         # check does not say the same thing twice (#161)
         self._no_headroom_warned = False
+        # get_artifact_list(result) memoized by id(result) - see
+        # _artifacts_for. Keeps result_list itself untouched, so
+        # Result.retainable's attribute walk over result_list is unaffected.
+        self._artifact_cache = {}
         logger.debug(f"Initialized Result with definition: {result_definition}")
 
     def set_metadata(self, metadata):
@@ -419,11 +423,27 @@ def get_artifacts(self):
         """
         artifacts = []
         for result in self.result_list:
-            artifacts.extend(get_artifact_list(result))
+            artifacts.extend(self._artifacts_for(result))
 
         logger.debug(f"Retrieved {len(artifacts)} artifacts from results")
         return artifacts
 
+    def _artifacts_for(self, result):
+        """get_artifact_list(result), memoized by identity of `result`.
+
+        save() extracts an in-memory pipeline output's artifacts and mutates
+        one in place to fit generated audio to the frame count (#197). A
+        later get_artifacts() call - a previous_result: consumer reading a
+        chained shot directly, bypassing any output: round trip - must see
+        that same fitted object rather than a fresh, unfitted extraction
+        from the same raw pipeline output, which get_artifact_list would
+        otherwise rebuild every time it runs.
+        """
+        key = id(result)
+        if key not in self._artifact_cache:
+            self._artifact_cache[key] = get_artifact_list(result)
+        return self._artifact_cache[key]
+
     def get_artifact_properties(self, property_name):
         """Extract specific properties from results.
 
@@ -545,7 +565,7 @@ def save(self, output_dir, default_base_name):
                 saved_files.append(output_path)
             else:
                 # Handle other content types
-                for j, artifact in enumerate(get_artifact_list(result)):
+                for j, artifact in enumerate(self._artifacts_for(result)):
                     saved_files.extend(
                         self.save_artifact(
                             validated_output_dir,
diff --git a/tests/test_result.py b/tests/test_result.py
index ada1489c..27770327 100644
--- a/tests/test_result.py
+++ b/tests/test_result.py
@@ -8,6 +8,7 @@
 import tempfile
 import json
 import logging
+import types
 from dataclasses import dataclass
 
 import numpy
@@ -661,6 +662,38 @@ def test_fit_is_written_back_onto_the_artifact(self):
 
         assert artifact.audio.shape == (2, 2000)
 
+    def test_fit_survives_a_second_extraction_of_a_raw_pipeline_output(self):
+        # #197, 4th round: write-back (above) lands the fit on the AudioVideo
+        # save() itself extracted - but a raw pipeline output (an object
+        # with .frames/.audio, not a pre-built AudioVideo, the shape LTX-2
+        # actually returns) is re-extracted from scratch by every call to
+        # get_artifact_list, including a later get_artifacts() call from a
+        # previous_result: consumer tapping the in-memory shot directly
+        # (e.g. a per-shot gain_audio step, bypassing any output: decode).
+        # That rebuilt a brand new, unfitted AudioVideo from the same raw
+        # .frames/.audio attributes, discarding the fit every time.
+        frames = ["frame"] * 48
+        # .frames/.audio are batched - one entry per generation - so a
+        # single video's frames/audio must each be wrapped in a length-1 list
+        audio = [torch.zeros((2, 1900))]  # 48 frames @ 24fps @ 1000Hz -> 2000
+        pipeline_output = types.SimpleNamespace(
+            frames=[frames], audio=audio, audio_sample_rate=1000
+        )
+
+        result = Result({"content_type": "video/mp4", "fps": 24})
+        result.add_result(pipeline_output)
+        with (
+            patch("dw.result.encode_video"),
+            patch("dw.result.export_to_video"),
+            patch("dw.result.is_av_available", return_value=True),
+        ):
+            with tempfile.TemporaryDirectory() as temp_dir:
+                result.save(temp_dir, "test")
+
+        artifacts = result.get_artifacts()
+        assert len(artifacts) == 1
+        assert artifacts[0].audio.shape == (2, 2000)
+
     def test_result_definition_overrides_the_sample_rate(self):
         artifact = AudioVideo("frames", torch.zeros((2, 100)), 48000)
 

From 5b02141980e4edf6ed8ef72de29288b384e99a36 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Fri, 18 Sep 2026 12:39:16 -0500
Subject: [PATCH 28/77] fix(mcp): #209 - drop a variable:-sourced null from
 arguments before validation

A variable: reference that resolves to null was treated as "present" by
select_errors' membership checks, rejecting the valid stored-workflow
pattern where rule is variable-driven and threshold/index are left at
their unset default for rules that don't use them. replace_variables now
drops a dict key when the variable it substitutes resolves to null - as
if the key had never been passed - so it reads as absent everywhere
downstream (select_errors, argument_errors, select() itself). A literal
null written inline in the workflow JSON never goes through this branch
and keeps its existing meaning.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 dw/variables.py         |  9 +++++++++
 tests/test_variables.py | 39 +++++++++++++++++++++++++++++++++++++++
 tests/test_workflow.py  | 23 +++++++++++++++++++++++
 3 files changed, 71 insertions(+)

diff --git a/dw/variables.py b/dw/variables.py
index 13a54d34..1bad55df 100644
--- a/dw/variables.py
+++ b/dw/variables.py
@@ -79,6 +79,15 @@ def replace_variables(data, variables):
         for k, v in data.items():
             matched, resolved = _resolve_variable_reference(v, variables)
             if matched:
+                # A variable: reference that resolves to null is dropped as
+                # if the key had never been passed - an optional argument
+                # left at its unset default (e.g. select's threshold/index)
+                # shouldn't count as "present" just because a variable named
+                # it. A literal null written inline in the workflow JSON
+                # never goes through this branch, so its meaning elsewhere
+                # (a declared-but-unset default) is untouched.
+                if resolved is None:
+                    continue
                 result[k] = resolved
             else:
                 # Recursively process nested structures in dictionary values
diff --git a/tests/test_variables.py b/tests/test_variables.py
index be41677b..73ae97d4 100644
--- a/tests/test_variables.py
+++ b/tests/test_variables.py
@@ -39,6 +39,45 @@ def test_replace_variables_missing():
     assert "other" in message
 
 
+def test_replace_variables_drops_a_top_level_argument_that_resolves_to_null():
+    # An optional argument (select's threshold/index) left at its unset
+    # default via a variable should vanish, not survive as a literal None -
+    # a None entry would read as "present" to a downstream `in arguments` check.
+    data = {"arguments": {"rule": "argmax", "threshold": "variable:threshold"}}
+    variables = {"threshold": None}
+
+    result = replace_variables(data, variables)
+    assert "threshold" not in result["arguments"]
+    assert result["arguments"]["rule"] == "argmax"
+
+
+def test_replace_variables_drops_a_null_variable_inside_a_for_each_entry():
+    # The same drop applies however deeply nested the dict is - a for_each
+    # step's entries are dicts sitting inside a list, walked recursively.
+    data = {
+        "for_each": [
+            {"name": "a", "threshold": "variable:threshold"},
+            {"name": "b", "threshold": 0.5},
+        ]
+    }
+    variables = {"threshold": None}
+
+    result = replace_variables(data, variables)
+    assert "threshold" not in result["for_each"][0]
+    assert result["for_each"][1]["threshold"] == 0.5
+
+
+def test_replace_variables_leaves_a_literal_null_untouched():
+    # A literal null written directly in the workflow JSON never goes through
+    # the variable-reference branch, so it keeps its existing meaning.
+    data = {"arguments": {"rule": "argmax", "threshold": None}}
+    variables = {}
+
+    result = replace_variables(data, variables)
+    assert "threshold" in result["arguments"]
+    assert result["arguments"]["threshold"] is None
+
+
 def test_replace_variables_does_not_mutate_input():
     data = {"key1": "variable:test", "key2": ["variable:test", "static"]}
     original = {"key1": "variable:test", "key2": ["variable:test", "static"]}
diff --git a/tests/test_workflow.py b/tests/test_workflow.py
index e51c3f78..7ff2bc7e 100644
--- a/tests/test_workflow.py
+++ b/tests/test_workflow.py
@@ -811,6 +811,29 @@ def test_run_records_the_selected_field_on_manifest_and_step_end(tmp_path):
     assert entry["selected"] == {"position": 1, "entry": "shot@b", "score": 0.9}
 
 
+def test_validation_allows_a_variable_sourced_null_threshold_and_index(tmp_path):
+    """#209: a stored-workflow pattern where `rule` is variable-driven and
+    `threshold`/`index` are left at their unset default (null) for rules that
+    don't use them used to fail validation, because select_errors saw the
+    keys present (with a None value) once replace_variables substituted them."""
+    definition = _for_each_workflow()
+    definition["variables"]["rule"] = "argmax"
+    definition["variables"]["threshold"] = None
+    definition["variables"]["index"] = None
+    definition["steps"][1]["task"] = {
+        "command": "select",
+        "arguments": {
+            "candidates": "gather:shot",
+            "scores": [0.1, 0.9],
+            "rule": "variable:rule",
+            "threshold": "variable:threshold",
+            "index": "variable:index",
+        },
+    }
+    workflow = _workflow_from(definition, tmp_path)
+    assert workflow.validation_errors() == []
+
+
 def test_run_substitutes_the_callers_list(tmp_path):
     workflow = _workflow_from(_for_each_workflow(seed=1), tmp_path)
     workflow.run({"shots": [{"name": "only", "text": "X"}]})

From a02bc1770e5dfb5fc5d9df72e88e3c64d7b434da Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Fri, 18 Sep 2026 12:47:13 -0500
Subject: [PATCH 29/77] docs(tasks): #220 - name the clip-hold ceiling in
 match_levels_dbfs docs

The match_levels_dbfs description named the peak target (-1 dBFS) but
never the -0.5 dBFS ceiling a clipping shot is held to, or the
match_levels_held warning/log event that reports it. A consumer read
the target as the ceiling and expected a warning that was correctly
not emitted (#214 regression report).

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 docs/TASKS.md             | 4 ++--
 dw/tasks/concat_videos.py | 5 +++--
 2 files changed, 5 insertions(+), 4 deletions(-)

diff --git a/docs/TASKS.md b/docs/TASKS.md
index 526e4e98..f0f927f4 100644
--- a/docs/TASKS.md
+++ b/docs/TASKS.md
@@ -220,7 +220,7 @@ video generation" in the workflow guide):
 | `seam_fade_ms` | No | Fade on each side of a seam that gets neither a crossfade nor a bleed - for tonal material, not for a continuous bed (default: 3, just enough not to click) |
 | `fps` | No | Frame rate of the videos - required to join audio when trimming, and the rate the joined file is written at unless `result.fps` overrides it |
 | `match_levels` | No | Even the shots' loudness out before joining - `"rms"` for perceived level (the measurement `get_gallery_metadata` reports as `mean_dbfs`), `"peak"` for the loudest sample. Off by default |
-| `match_levels_dbfs` | No | The level `match_levels` moves every shot to (default: -1 dBFS for `peak`, -20 dBFS for `rms`) |
+| `match_levels_dbfs` | No | The level `match_levels` moves every shot to (default: -1 dBFS for `peak`, -20 dBFS for `rms`). A shot that would clip at the target is held at -0.5 dBFS peak instead, reported as a `match_levels_held` warning with a per-shot log event |
 
 A video may also be named by path or URL, which is how shots an earlier run
 already wrote are joined without regenerating them - the file is read with the
@@ -350,7 +350,7 @@ montage cut to a score wants:
 | `fade_color` | No | The RGB colour the fades come from and go to (default: black) |
 | `fps` | No | Frame rate of the videos - required to crossfade audio at a dissolve, and the rate the dissolved file is written at unless `result.fps` overrides it |
 | `match_levels` | No | Even the shots' loudness out before joining - `"rms"` or `"peak"`, as with [`concat_videos`](#concat_videos). Off by default |
-| `match_levels_dbfs` | No | The level `match_levels` moves every shot to (default: -1 dBFS for `peak`, -20 dBFS for `rms`) |
+| `match_levels_dbfs` | No | The level `match_levels` moves every shot to (default: -1 dBFS for `peak`, -20 dBFS for `rms`). A shot that would clip at the target is held at -0.5 dBFS peak instead, reported as a `match_levels_held` warning with a per-shot log event |
 
 Every seam shortens the result by one overlap, so eight 124-frame shots joined
 with 12-frame dissolves run 908 frames, not 992 - size a soundtrack slice to
diff --git a/dw/tasks/concat_videos.py b/dw/tasks/concat_videos.py
index 4a838f0f..3ecb12fd 100644
--- a/dw/tasks/concat_videos.py
+++ b/dw/tasks/concat_videos.py
@@ -97,8 +97,9 @@ def concat_videos(
             enough to hear is logged as a warning
         match_levels_dbfs: The level match_levels moves every shot to -
             defaults to -1 dBFS for "peak" and -20 dBFS for "rms". A shot
-            that would clip at the target is held just below full scale
-            instead
+            that would clip at the target is held at -0.5 dBFS peak instead,
+            reported as a match_levels_held warning, with a per-shot log
+            event naming the hold
         sample_rate: The rate the joined soundtrack is at. Shots that come
             from different sources routinely carry different rates - a 24 kHz
             voice clip paired onto a 32 kHz generation - and unlike a level

From 2c661be4f727a021f46db090ba5bd12184edd192 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Fri, 18 Sep 2026 12:57:18 -0500
Subject: [PATCH 30/77] feat(plugin): #217 - add series-episodes skill for
 fixed-cast, five-beat procedure

States the generate/recut/bed/match_levels/normalize/pair procedure for a
multi-episode series as a numbered composition of the minimax-h3 templates
and assemble-and-score, with a first step (draw the cast once, keep_output
shared=True, reference by asset:cast/<name>.png) that closes the drift bug
where each episode redraws its own portraits by default.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 plugins/dw/skills/series-episodes/SKILL.md | 115 +++++++++++++++++++++
 1 file changed, 115 insertions(+)
 create mode 100644 plugins/dw/skills/series-episodes/SKILL.md

diff --git a/plugins/dw/skills/series-episodes/SKILL.md b/plugins/dw/skills/series-episodes/SKILL.md
new file mode 100644
index 00000000..4406b248
--- /dev/null
+++ b/plugins/dw/skills/series-episodes/SKILL.md
@@ -0,0 +1,115 @@
+---
+name: series-episodes
+description: Use when a dw MCP server is connected and the user wants a series - several episodes sharing a cast, cut and scored one at a time rather than a single generation. States the five-beat recut-bed-match_levels-normalize-pair procedure that turns generated shots into a scored episode, and the one step that must not be skipped or the cast drifts between episodes.
+---
+
+# Series episodes on a dw server
+
+An episode is not one generation. Each episode's shots come from their own
+`minimax-h3` template runs (`templates/minimax/dialogue-short` or
+`templates/minimax/music-video`), and the pieces are then cut and scored
+together the way `templates/assemble-and-score` does for a single film. A
+series is that same procedure run once per episode, against one cast that
+must look and sound the same in episode 5 as it did in episode 1 - which
+does not happen by default, because each `dialogue-short`/`music-video` run
+draws its own portraits unless told not to. This skill states the procedure
+and the one step (0 below) that keeps the cast fixed; everything past it is
+`minimax-h3`'s and `assemble-and-score`'s own rules, not repeated here.
+
+## Before anything
+
+1. `get_server_info` for the device and workspace.
+2. `list_workflows(shape="shot")` for the H3 templates, `list_workflows(shape="sequence")`
+   for `assemble-and-score`. Trust the listing over the names quoted here.
+3. Read the `minimax-h3` skill before writing any shot - the `shots` list
+   shape, the prompt format, and the hard rules (frame count, canvas,
+   reference limits) all come from there and are not restated here.
+
+## 0. Draw the cast once, before episode 1
+
+Draw each character's portrait (and, for a voice that must hold, its
+reference clip) exactly once, in whichever workflow is convenient - a bare
+`templates/minimax/dialogue-short` run works, or any Z-Image step. Then
+`keep_output(name, asset_name="cast/<character>.png", shared=True)` for
+each portrait, and `upload_asset(..., shared=True)` for a voice clip that
+did not come from a run. `shared=True` is the whole point: it puts the
+portrait in the asset library every workspace shares
+(`docs/WORKSPACES.md`), so an episode generated in a different workspace,
+weeks later, still resolves `asset:cast/<character>.png` to the same file.
+
+Every later episode's `shots` entries reference that cast with `from_file`,
+never `from_previous_result`:
+
+```json
+"references": [
+  {"reference_type": "image", "from_file": "asset:cast/priya.png"},
+  {"reference_type": "audio", "from_file": "asset:cast/priya-voice.wav"}
+]
+```
+
+This is the step that goes missing: a `from_previous_result` reference (or
+an unreferenced portrait prompt, redrawn from a text description that reads
+close enough to pass review) draws a new face for the character in every
+episode that uses it, and nothing in validation catches it - the shot
+generates cleanly, and the drift only shows up when two episodes are
+watched back to back. There is no engine check for "the same character
+looks the same" across separate runs; the fixed-asset reference is the only
+guard, so it has to be a deliberate, first step rather than an implicit one.
+
+## 1-5. Per episode: generate, then recut, bed, match_levels, normalize, pair
+
+Generate the episode's shots with `templates/minimax/dialogue-short` (or
+`music-video`), `shots` referencing the fixed cast from step 0. Each shot
+is its own H3 generation, so cast drift *within* one episode does not
+happen - only *across* episodes does, which is what step 0 closes.
+
+Once every shot for the episode exists (freshly generated, or promoted from
+a run with `keep_output`), cut and score them with
+`templates/assemble-and-score` - it is the five-beat pipeline this skill
+composes into, not something to re-derive:
+
+- **recut**: `shots` (the episode's clips, in order) goes straight into
+  `concat_videos` as hard cuts - nothing is stabilized or rescaled, so the
+  clips must already share one size and frame rate.
+- **bed**: if the episode's score is shorter than the cut, stretch it first
+  with the `loop_audio` task (`target_frames` = the cut's `total_frames`,
+  `fps` matching) rather than letting `assemble-and-score` pad the tail
+  with silence.
+- **match_levels**: shots generated independently drift in loudness -
+  `assemble-and-score`'s `match_levels` (`"rms"` or `"peak"`) evens them
+  before the cut; leaving it null only warns on a wide spread instead of
+  fixing it.
+- **normalize**: the mixed world sound and score are normalized together
+  (`assemble-and-score`'s `balanced` step, -3 dBFS) so one episode is not
+  louder than the next.
+- **pair**: the normalized track is muxed onto the cut - the episode's
+  deliverable.
+
+One `assemble-and-score` run per episode; each episode's `total_frames` and
+`shots` list are its own.
+
+## Run and judge
+
+`output:` a shot straight from its generation run
+(`output:dialogue-short/<episode run id>/final/<shot>.mp4`) rather than
+downloading and re-uploading it as an asset - only the cast portraits from
+step 0 need to be assets, since they are the one thing that must outlive a
+single episode's run directory. The `final` segment there is the step's
+`subfolder`: the deliverable shot each H3 template writes, as opposed to
+`intermediate` scratch that an `output:` reference has no reason to name.
+
+Beyond `minimax-h3`'s own judging checklist (a character that changes
+between shots, a portrait imposing its framing, a voice without affect):
+watch two episodes back to back and check the cast reads as the same
+people - the failure mode step 0 exists to prevent. `get_gallery_metadata`
+on each episode's final file for duration and loudness, so a level
+mismatch between episodes shows up before a viewer notices it.
+
+## Sources
+
+`workflows/templates/assemble-and-score.json`, `dw/tasks/audio_utils.py`
+(`loop_audio`, `match_levels`, `normalize_audio`), `dw/tasks/pair_audio.py`,
+`docs/WORKSPACES.md` (the shared asset library), the `minimax-h3` skill
+this composes into. Written from issue #217 (dkackman/diffusers-workflow),
+which named the drift as a recurring, undocumented failure across two
+hand-built episodes.

From 3b9a7a8e89fc1542f32cd70913f00e8924d1e8bd Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Fri, 18 Sep 2026 13:09:05 -0500
Subject: [PATCH 31/77] feat(server,mcp): #221 clear-memory endpoint/tool, #222
 runtime env info

#221: POST /api/memory/clear + MCP clear_memory() wire the worker's
existing clear_memory command (same mechanism as the REPL's `memory
clear`) to drop every loaded pipeline and the step cache on demand.
Refused with 409 while a job is running or queued rather than blocking,
since the queue is FIFO.

#222: GET /api/server (and get_server_info()) now report a `runtime`
block - Python version, torch version and its CUDA build, NVIDIA
driver version, and installed versions of diffusers/transformers/
accelerate/bitsandbytes/peft/safetensors/sentencepiece - for
diagnosing environment mismatches between boxes without shelling in.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 docs/MCP.md              |  3 +-
 docs/SERVER.md           | 16 +++++++--
 dw/server/app.py         | 25 ++++++++++++++
 dw/server/jobs.py        | 22 +++++++++++++
 dw/server/sysinfo.py     | 71 ++++++++++++++++++++++++++++++++++++++++
 dw_mcp/catalog.py        |  9 +++++
 dw_mcp/server.py         | 12 +++++++
 tests/test_mcp_server.py |  3 ++
 8 files changed, 157 insertions(+), 4 deletions(-)
 create mode 100644 dw/server/sysinfo.py

diff --git a/docs/MCP.md b/docs/MCP.md
index e92b0422..1c16900f 100644
--- a/docs/MCP.md
+++ b/docs/MCP.md
@@ -224,7 +224,7 @@ when no single workflow covers it.
 | `list_models()` | — | List what the Hugging Face model cache holds, largest first |
 | `get_memory()` | — | Get the worker's VRAM and RAM statistics. `gpu_*` is the card; `host_memory_rss_mb` / `host_memory_peak_rss_mb` are the worker process's resident and high-water host memory, beside the machine's `host_memory_total_mb` / `host_memory_available_mb` - read both, since an offloading workflow keeps its weights in host RAM and the card says little about what it holds (a host field is absent, not null, where the platform cannot measure it). `host_pinned_reserved_mb` / `host_pinned_allocated_mb`, when present, are torch's pinned-host cache - the staging buffers group offloading moves weights through, part of `host_memory_rss_mb` and invisible in every `gpu_*` figure, which is what a worker holding GB after releasing every model is usually holding (#98). `live: true` means `info` was measured now and is the worker's own memory; only live readings are comparable with each other. `live: false` with `info: null` (and `stale: false`) means nothing has been measured because nothing is resident; `live: false` with a populated `info` is a cached earlier reading, with `reason` (`job_running`, `worker_stopped`, `worker_busy`, `worker_unreachable`) and `age_seconds` - one cached while a job loads a model understates what is resident, so ask again when the server is idle rather than comparing it with a live figure |
 | `get_health()` | — | Check that the server is alive, and which machine answered: `version`, `device`, whether a model process is currently resident (`worker_alive`), the job running now and the queue depth. `worker_alive: false` is the normal idle state on a server that has not run a job since startup or the last memory clear - not a fault - the on-demand worker starts with the next job (#206) |
-| `get_server_info()` | — | What this installation can do and where it keeps things: `device` (the accelerator a run will use), `version`, the `workspace` this session is working in and the workflow/asset/output/prompt `directories` of *that* workspace, the bind address and port, whether a token is required, and whether MCP is mounted. Check the device before authoring - a CUDA-only choice (bitsandbytes, `torch.compile`, flash attention) is not available on an `mps` or `cpu` server |
+| `get_server_info()` | — | What this installation can do and where it keeps things: `device` (the accelerator a run will use), `version`, the `workspace` this session is working in and the workflow/asset/output/prompt `directories` of *that* workspace, the bind address and port, whether a token is required, and whether MCP is mounted. Check the device before authoring - a CUDA-only choice (bitsandbytes, `torch.compile`, flash attention) is not available on an `mps` or `cpu` server. `runtime` (#222) reports the Python version, torch version and the CUDA version torch was built against, the NVIDIA driver version (when `nvidia-smi` is reachable), and the installed versions of diffusers, transformers, accelerate, bitsandbytes, peft, safetensors and sentencepiece (`null` for one not installed) - for diagnosing an environment mismatch between boxes without shelling in |
 | `list_jobs(limit=20, status=None, workspace=None)` | optional `limit` (newest N), `status` (one state or a comma-separated set of `queued`, `running`, `succeeded`, `failed`, `cancelled`), `workspace` | List queued, running and recent jobs, **newest first**. Bounded by default: the unbounded listing was over a client's tool-result limit on a server with a few months of history, which made it a tool that could not be called at all. `total` says how many matched and `truncated`/`next` say so when the answer was cut - raise `limit` or narrow with `status`. Without `workspace`, a named workspace lists its own jobs and the default one lists every job the server holds |
 | `list_gallery(limit=50, subfolder=None, only_orphans=False, workspace=None)` | `limit`, `subfolder`, `only_orphans`, `workspace` | List generated output files, newest first. A name is `<workflow>/<run id>/<file>`, where `<file>` may sit in the subfolder the step chose (`final/episode.mp4`); each entry carries `folder` (the workflow) and `subfolder` (by convention `final` or `intermediate`, `''` when the step chose none, any path the workflow wrote otherwise), and `subfolder="final"` lists only deliverables. Each entry also carries a ready-made `url`, already scoped to the workspace that made it - a hand-built `/outputs/<name>` URL 404s for anything but the default workspace. `only_orphans=True` inverts the call: instead of files, it returns run directories with no media anywhere under them (`runs`, each `{name, mtime}`) - a run whose output was deleted before `delete_output` could remove it by name, or one that failed before writing anything; `subfolder` does not apply in this mode, and `name` is exactly what `delete_output` accepts (#170). `workspace` names the workspace for this one call without switching the session to it - the same pin `run_workflow` takes, so a job run into another workspace stays reachable from the session that queued it |
 | `get_gallery_metadata(name, envelope=False, workspace=None)` | `name`, `workspace` | Get the metadata embedded in a generated file — or, when `name` is an `asset:` reference, what an *input* asset holds (`source` says which; `job` is null for an asset). Reading an input's duration, frame count, fps and sample rate before a run is how a caller learns the `total_frames`, `fps` and `sample_rate` a workflow expects it to supply: the exact workflow and arguments that produced it, and, for audio/video, a `media` block (duration, rate, channels, fps, size, peak/mean dBFS). `envelope=true` adds `media.envelope` — `rms_dbfs` and `peak_dbfs` one entry per second — which is what locates something in a track rather than measuring the whole of it. `workspace` names the workspace for this one call without switching the session to it - the same pin `run_workflow` takes, so a job run into another workspace stays reachable from the session that queued it |
@@ -290,6 +290,7 @@ references written in the same session.
 | `get_job_events(job_id, after=-1, limit=200)` | `job_id`, `after`, `limit` | Get a page of a job's progress events |
 | `wait_for_job(job_id, timeout_seconds=20)` | `job_id`, `timeout_seconds` | Block until a job reaches a terminal status, or `timeout_seconds` elapses. **One call blocks for at most 55 seconds** — a larger `timeout_seconds` is clamped, not honoured, because no MCP client holds a tool call open for a generation's real runtime, so budget one call per ~55s of the job. Every reply carries `waited_seconds`, `timeout_requested_seconds`, `timeout_applied_seconds` and `timeout_capped`, so a capped return is distinguishable from an elapsed one. Use instead of hand-polling `get_job`/`get_job_events` in a loop; if it returns `still_running: true`, call it again. Returns a slim job - status, warnings, error, and the manifest once finished - without the arguments; `get_job` has those. A running job also carries `progress` (below) |
 | `cancel_job(job_id)` | `job_id` | Ask a queued or running job to stop |
+| `clear_memory()` | — | Drop every loaded pipeline and the step cache, freeing VRAM/RAM immediately instead of waiting for the next job to evict one model for another. Also drops the step cache, so a seeded workflow that would otherwise reuse cached results regenerates on its next run. Refused with a 409 while a job is running or queued - the queue is FIFO, so wait for it to finish and retry rather than expecting this call to block until it does (#221) |
 | `rerun_job(job_id, acknowledged_cost=False, new_seed=False)` | `job_id`, `acknowledged_cost`, `new_seed` | Queue a fresh job from a previous job's stored specification. Costs GPU time, so it passes the same gate as `run_workflow`. `new_seed=true` draws a fresh seed into the workflow's seed variable — without it a seeded workflow's rerun repeats its arguments exactly and the step cache serves the whole run from the earlier one's files (`reused: true`), generating nothing. `get_job_workflow`'s `seed_variable` says whether there is one - `acknowledged_cost` is `true` or the bound `{fingerprint, minutes, downloads}` from the validate plan; a 409 means the plan changed and the message carries the new estimate |
 | `move_job(job_id, direction)` | `job_id`, `direction` (`up`\|`down`\|`front`\|`back`) | Reorder a queued job |
 
diff --git a/docs/SERVER.md b/docs/SERVER.md
index db041ef3..2794131a 100644
--- a/docs/SERVER.md
+++ b/docs/SERVER.md
@@ -534,12 +534,22 @@ The editor's forms come from these; they are just as usable from scripts:
   measured because nothing is resident. health also reports `hostname`,
   `device` and whether `mcp` is mounted, so a remote client can tell which
   machine answered
+- `POST /api/memory/clear` (#221) — drops every loaded pipeline and the step
+  cache, the same mechanism as the REPL's `memory clear`, and returns the
+  memory reading taken right after. Refused with 409 while a job is running
+  or queued - the queue is FIFO, so the caller retries once it finishes
+  rather than this call blocking until it does
 - `GET /api/server` — connection details for the Server page: `hostname`,
   `version`, `device`, the `bind_host`/`port`/`wildcard_bind` the server was
   started with, `auth_required` (whether a token is configured - never the
-  token itself), `mcp` (`mounted` plus its `path`), the machine's
-  non-loopback `addresses`, and the `directories` in use; a client composes
-  its URLs from an address, the port and the MCP path
+  token itself), `mcp` (`mounted` plus its `path`), the `directories` in use,
+  and `runtime` (#222) - Python version, torch version and the CUDA version
+  torch was built against, the NVIDIA driver version (via `nvidia-smi`, when
+  it's on PATH), and the installed versions of diffusers, transformers,
+  accelerate, bitsandbytes, peft, safetensors and sentencepiece (`null` for
+  one not installed) - for diagnosing an environment mismatch between boxes
+  without shelling in; the machine's non-loopback `addresses`; a client
+  composes its URLs from an address, the port and the MCP path
 
 ## Security model
 
diff --git a/dw/server/app.py b/dw/server/app.py
index 8511b415..4dd785b2 100644
--- a/dw/server/app.py
+++ b/dw/server/app.py
@@ -123,6 +123,7 @@
 )
 from .netinfo import local_addresses
 from .updater import DiffusersUpdater
+from .sysinfo import runtime_info
 from .catalog_shape import derive_catalog_metadata, project_listing
 from . import guides
 from .guides import GuideError
@@ -3487,6 +3488,26 @@ def memory():
         except Exception as e:
             raise HTTPException(status_code=503, detail=f"Worker unavailable: {e}")
 
+    @app.post("/api/memory/clear")
+    def clear_memory():
+        """Drop every loaded pipeline and the step cache, freeing VRAM/RAM
+        without waiting for the next job to evict one model for another.
+
+        Refused while a job is running or queued (409) rather than blocked -
+        the queue is FIFO, so the caller should wait for the job to finish
+        and retry instead of this call stalling until it does."""
+        if manager.is_busy():
+            raise HTTPException(
+                status_code=409,
+                detail="A job is running or queued - clearing memory out "
+                "from under it would corrupt the run. Wait for it to finish.",
+            )
+        try:
+            info = manager.clear_memory()
+        except RuntimeError as e:
+            raise HTTPException(status_code=503, detail=f"Worker unavailable: {e}")
+        return {"cleared": True, "info": info}
+
     @app.get("/api/health")
     def health():
         import socket
@@ -3552,6 +3573,10 @@ def server_info():
             "trust_workflows": workflows_are_trusted(),
             "mcp": {"mounted": bool(app.state.mcp_mounted), "path": MCP_PATH},
             "addresses": addresses,
+            # Python/torch/CUDA-driver/other-package versions - the detail
+            # neither this route's own `version` field nor `get_health`
+            # answers, e.g. whether bitsandbytes is even installed (#222)
+            "runtime": runtime_info(),
             "directories": {
                 # The workspace the three below default to folders of; an
                 # individually overridden folder still reports its own path
diff --git a/dw/server/jobs.py b/dw/server/jobs.py
index 39e49bf3..5e43ff5a 100644
--- a/dw/server/jobs.py
+++ b/dw/server/jobs.py
@@ -1358,3 +1358,25 @@ def memory_status(self, timeout=5):
                 "age_seconds": 0.0,
             }
         return self._cached_memory("worker_unreachable")
+
+    def clear_memory(self, timeout=30):
+        """Drop every loaded pipeline and the step cache, then report the
+        memory reading taken right after. Callers must check `is_busy()`
+        first - this does not itself refuse a running/queued job, and racing
+        one would clear state a queued run still expects resident. The
+        30s timeout (vs. `memory_status`'s 5s) matches the REPL's `memory
+        clear` (`repl_commands.py`): actually freeing CUDA memory takes
+        longer than reading a counter does."""
+        if not self.worker_manager.worker_active:
+            raise RuntimeError("worker not active")
+        if not self._worker_lock.acquire(timeout=2):
+            raise RuntimeError("worker busy")
+        try:
+            self.worker_manager.send_command({"type": "clear_memory"})
+            result = self.worker_manager.get_result(timeout=timeout)
+        finally:
+            self._worker_lock.release()
+        if result.get("type") != "memory_cleared":
+            raise RuntimeError(f"unexpected worker reply: {result.get('type')}")
+        self._record_memory(result.get("info"))
+        return self.last_memory
diff --git a/dw/server/sysinfo.py b/dw/server/sysinfo.py
new file mode 100644
index 00000000..0a555457
--- /dev/null
+++ b/dw/server/sysinfo.py
@@ -0,0 +1,71 @@
+"""Runtime environment details - Python, torch, CUDA/driver and other
+installed package versions - for diagnosing environment mismatches between
+boxes (#222). Read-only, gathered fresh on every call rather than cached,
+since an install can change underneath a long-running server (see
+`update_diffusers`).
+"""
+
+import platform
+import subprocess
+from importlib.metadata import PackageNotFoundError, version
+
+# Packages worth reporting beyond torch (which gets its own field): the
+# ones most likely to cause a version-mismatch failure or be silently
+# absent on a given box.
+PACKAGES = (
+    "diffusers",
+    "transformers",
+    "accelerate",
+    "bitsandbytes",
+    "peft",
+    "safetensors",
+    "sentencepiece",
+)
+
+
+def _package_version(name):
+    try:
+        return version(name)
+    except PackageNotFoundError:
+        return None
+
+
+def _nvidia_driver_version():
+    """The NVIDIA driver version, via nvidia-smi when it's on PATH. Distinct
+    from torch's own `cuda_version`, which is the CUDA toolkit torch was
+    built against, not the driver actually installed on this box."""
+    try:
+        result = subprocess.run(
+            ["nvidia-smi", "--query-gpu=driver_version", "--format=csv,noheader"],
+            capture_output=True,
+            text=True,
+            timeout=5,
+        )
+    except (OSError, subprocess.TimeoutExpired):
+        return None
+    if result.returncode != 0:
+        return None
+    lines = result.stdout.strip().splitlines()
+    return lines[0].strip() if lines else None
+
+
+def runtime_info():
+    """Python, torch, CUDA/driver and other installed package versions -
+    the detail `device`/`version` alone doesn't answer, like "is
+    bitsandbytes even installed here" or "which CUDA build is torch"."""
+    try:
+        import torch
+
+        torch_version = torch.__version__
+        cuda_version = torch.version.cuda
+    except ImportError:
+        torch_version = None
+        cuda_version = None
+
+    return {
+        "python_version": platform.python_version(),
+        "torch_version": torch_version,
+        "cuda_version": cuda_version,
+        "driver_version": _nvidia_driver_version(),
+        "packages": {name: _package_version(name) for name in PACKAGES},
+    }
diff --git a/dw_mcp/catalog.py b/dw_mcp/catalog.py
index 4230d294..5a5c98f2 100644
--- a/dw_mcp/catalog.py
+++ b/dw_mcp/catalog.py
@@ -153,6 +153,15 @@ def get_memory(client):
     return client.get_json("/api/memory")
 
 
+def clear_memory(client):
+    """Drop every loaded pipeline and the step cache, freeing VRAM/RAM
+    immediately rather than waiting for the next job to evict one model
+    for another. Refused with a 409 while a job is running or queued -
+    the queue is FIFO, so retry once it finishes rather than expecting
+    this call to wait for it."""
+    return client.post_json("/api/memory/clear")
+
+
 def get_health(client):
     """Server liveness, plus what answered: version, device, whether a
     model process is currently resident, the job running now and how many
diff --git a/dw_mcp/server.py b/dw_mcp/server.py
index 9021baa1..98e95e51 100644
--- a/dw_mcp/server.py
+++ b/dw_mcp/server.py
@@ -314,6 +314,17 @@ def get_memory() -> dict:
         server is idle rather than comparing it against a live figure."""
         return catalog.get_memory(client)
 
+    def clear_memory() -> dict:
+        """Drop every loaded pipeline and the step cache, freeing VRAM/RAM
+        immediately instead of waiting for the next job to evict one model
+        for another. Also drops the step cache, so a seeded workflow that
+        would otherwise reuse cached results regenerates on its next run.
+
+        Refused with a 409 while a job is running or queued - the queue is
+        FIFO, so wait for it to finish and retry rather than expecting this
+        call to block until it does."""
+        return catalog.clear_memory(client)
+
     def get_health() -> dict:
         """Check that the server is alive, and see what answered: its
         version and accelerator, whether a model process is currently
@@ -485,6 +496,7 @@ def get_guide(name: str, section: str | None = None) -> dict:
         get_gallery_metadata,
     ):
         tool(fn, READ_ONLY)
+    tool(clear_memory, WRITES)
 
     # --------------------------------------------------------------- media
 
diff --git a/tests/test_mcp_server.py b/tests/test_mcp_server.py
index c4261258..2cc046f4 100644
--- a/tests/test_mcp_server.py
+++ b/tests/test_mcp_server.py
@@ -28,6 +28,7 @@
     "get_task",
     "list_models",
     "get_memory",
+    "clear_memory",
     "get_health",
     "get_server_info",
     "list_jobs",
@@ -74,6 +75,7 @@
 }
 
 READ_ONLY_TOOLS = EXPECTED_TOOLS - {
+    "clear_memory",
     "save_workflow",
     "delete_workflow",
     "run_workflow",
@@ -324,6 +326,7 @@ def _a_file_to_upload():
     ("get_task", {"command": "resize"}, "GET", "/api/tasks/resize"),
     ("list_models", {}, "GET", "/api/models"),
     ("get_memory", {}, "GET", "/api/memory"),
+    ("clear_memory", {}, "POST", "/api/memory/clear"),
     ("get_health", {}, "GET", "/api/health"),
     ("get_server_info", {}, "GET", "/api/server"),
     ("list_jobs", {}, "GET", "/api/jobs"),

From 24a871fb849cbda98ffe6fbfeb11193e2a15cf7d Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Fri, 18 Sep 2026 13:32:08 -0500
Subject: [PATCH 32/77] feat(speech): #223 - add speaker_embedding arg to
 generate_speech

Mirrors the existing voice_preset preprocessing-argument pattern: pull
speaker_embedding out of kwargs, resolve the asset-referenced reference
audio to an x-vector via speechbrain's spkrec-xvect-voxceleb, and inject
it into forward_params as speaker_embeddings for SpeechT5 only - a
non-SpeechT5 model refuses it the same way a single-voice model refuses
voice_preset. VITS's speaker_id needs no code change: it is a plain int
that already reaches the model through forward_params, confirmed by a
dedicated test that never touches speaker_embedding.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 docs/TASKS.md                   |  3 ++
 dw/tasks/speech_generation.py   | 69 ++++++++++++++++++++++++-
 pyproject.toml                  |  6 +++
 tests/test_speech_generation.py | 91 +++++++++++++++++++++++++++++++++
 4 files changed, 167 insertions(+), 2 deletions(-)

diff --git a/docs/TASKS.md b/docs/TASKS.md
index f0f927f4..d117538d 100644
--- a/docs/TASKS.md
+++ b/docs/TASKS.md
@@ -1278,11 +1278,14 @@ Speak a line of text with a local text-to-speech model. The result is a waveform
 | `text` | Yes | The line to speak |
 | `model_name` | No | HuggingFace model ID (default: `suno/bark-small`) |
 | `voice_preset` | No | The speaker, for a model with presets — `v2/en_speaker_0` through `v2/en_speaker_9` for Bark. A model with no processor (a single-voice model such as `facebook/mms-tts-eng`) refuses a `voice_preset` with an error rather than ignoring it |
+| `speaker_embedding` | No | A reference audio file (typically an `asset:` reference) whose voice a SpeechT5 model should speak in. Reduced to an x-vector with speechbrain's `spkrec-xvect-voxceleb` and injected into `forward_params` as `speaker_embeddings`. A model that isn't SpeechT5 refuses it the same way a single-voice model refuses `voice_preset` |
 | `forward_params` | No | Passed to the model's forward/generate call |
 | `generate_kwargs` | No | Ad-hoc generation settings for a generative model — `temperature`, `do_sample` |
 
 The default is Bark because its voice presets give distinct speakers, which is what two characters in a scene need; `facebook/mms-tts-eng` is a quarter the size and a good override where one voice will do. `voice_preset` is a preprocessing argument — it selects the speaker before generation rather than parameterizing it — so naming it here is what makes it reach the processor. Passed through `forward_params` it would be dropped and every character would sound the same.
 
+`speaker_embedding` is the same kind of preprocessing argument for a SpeechT5 model (`microsoft/speecht5_tts`), which conditions its voice on an x-vector rather than a preset name. A VITS model's speaker is different again — a plain `speaker_id` int, passed through `forward_params` unchanged, since it was never a preprocessing argument and needs no argument of its own here.
+
 The result needs no `sample_rate`. A generated track carries the rate its model produced it at, and that beats the 44100 default; declaring one still wins over both, for a track whose rate was reported wrong. Every TTS model runs at a different rate, so a declared rate that does not match plays the speech at the wrong speed and pitch without ever failing.
 
 ### Generating a voice to condition on
diff --git a/dw/tasks/speech_generation.py b/dw/tasks/speech_generation.py
index 48d0a2a8..736a1293 100644
--- a/dw/tasks/speech_generation.py
+++ b/dw/tasks/speech_generation.py
@@ -18,11 +18,12 @@
 
 import logging
 
+import torch
 from transformers import pipeline as hf_pipeline
 
 from .. import preferred_task_dtype
 from ..result import AudioTrack
-from .audio_utils import as_channels_samples
+from .audio_utils import as_channels_samples, load_audio, resample_waveform
 from .model_cache import cached_model, hf_pipeline_placement
 
 logger = logging.getLogger("dw")
@@ -34,6 +35,44 @@
 # voice is needed
 _DEFAULT_MODEL = "suno/bark-small"
 
+# What SpeechT5's voice-cloning recipes are built around - trained on the same
+# corpus (VoxCeleb) the CMU ARCTIC x-vectors that ship with the model card come
+# from, so a reference clip reduces to a vector in the space the model expects
+_SPEAKER_ENCODER_MODEL = "speechbrain/spkrec-xvect-voxceleb"
+# What the encoder was trained on - resampling anything else to this rate is
+# part of extracting a voiceprint, not an approximation of one
+_SPEAKER_ENCODER_SAMPLE_RATE = 16000
+
+
+def _speaker_embedding_tensor(location, device):
+    """The x-vector speechbrain's spkrec-xvect-voxceleb extracts from a
+    reference audio file - what SpeechT5 conditions its voice on.
+
+    Args:
+        location: Path to a reference audio file (an 'asset:' reference has
+            already resolved to this by the time a task sees it).
+        device: Where to run the encoder.
+    """
+    from speechbrain.inference.speaker import EncoderClassifier
+
+    def load_encoder():
+        return EncoderClassifier.from_hparams(
+            source=_SPEAKER_ENCODER_MODEL,
+            run_opts={"device": str(device)},
+        )
+
+    encoder = cached_model(
+        ("speaker_encoder", _SPEAKER_ENCODER_MODEL, str(device)), load_encoder
+    )
+
+    waveform, sample_rate = load_audio(location)
+    waveform = resample_waveform(waveform, sample_rate, _SPEAKER_ENCODER_SAMPLE_RATE)
+    mono = waveform.mean(axis=0)
+
+    with torch.no_grad():
+        embedding = encoder.encode_batch(torch.as_tensor(mono).unsqueeze(0))
+    return embedding.squeeze()
+
 
 def generate_speech(text, device="cpu", **kwargs):
     """Speak a line of text with a local text-to-speech model.
@@ -48,6 +87,14 @@ def generate_speech(text, device="cpu", **kwargs):
                 argument: it selects the speaker before generation rather than
                 parameterizing it, which is why it is named here rather than left
                 to forward_params, where it would be silently dropped.
+            speaker_embedding: Path to a reference audio file (typically an
+                'asset:' reference) whose voice a SpeechT5 model should speak
+                in. Reduced to an x-vector with speechbrain's
+                spkrec-xvect-voxceleb and injected into forward_params as
+                'speaker_embeddings' - SpeechT5 is the only pipeline here that
+                conditions on one. A VITS model's speaker instead takes a plain
+                'speaker_id' int, which already reaches the model unchanged
+                through forward_params and needs no argument of its own.
             forward_params: Passed to the model's forward/generate call.
             generate_kwargs: Ad-hoc generation settings for a generative model -
                 temperature, do_sample and so on.
@@ -61,6 +108,7 @@ def generate_speech(text, device="cpu", **kwargs):
     """
     model_name = kwargs.get("model_name", _DEFAULT_MODEL)
     voice_preset = kwargs.get("voice_preset", None)
+    speaker_embedding = kwargs.get("speaker_embedding", None)
     dtype = preferred_task_dtype(device)
 
     def load_pipe():
@@ -86,11 +134,28 @@ def load_pipe():
             "preset, or use a model with speaker presets such as suno/bark-small"
         )
 
+    forward_params = kwargs.get("forward_params") or {}
+    if speaker_embedding:
+        model_type = getattr(getattr(pipe.model, "config", None), "model_type", None)
+        if model_type != "speecht5":
+            # Only SpeechT5 conditions on an x-vector; a model that does not
+            # would drop 'speaker_embeddings' as an unrecognised forward kwarg
+            # and generate in its own voice, same failure mode as voice_preset
+            raise ValueError(
+                f"{model_name} takes no 'speaker_embedding' - only a SpeechT5 "
+                "model conditions on an x-vector. Drop it, or use a SpeechT5 "
+                "model such as microsoft/speecht5_tts"
+            )
+        forward_params = {
+            **forward_params,
+            "speaker_embeddings": _speaker_embedding_tensor(speaker_embedding, device),
+        }
+
     logger.info(f"Speaking: {text[:100]}{'...' if len(text) > 100 else ''}")
     output = pipe(
         text,
         preprocess_params={"voice_preset": voice_preset} if voice_preset else {},
-        forward_params=kwargs.get("forward_params") or {},
+        forward_params=forward_params,
         generate_kwargs=kwargs.get("generate_kwargs") or {},
     )
 
diff --git a/pyproject.toml b/pyproject.toml
index 7ea443fd..e417ca31 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -82,6 +82,12 @@ dependencies = [
     "av>=18.1.0",
     "soundfile>=0.14.0",
     "matplotlib>=3.11.1",
+    # speaker_embedding preprocessing arg for generate_speech: reduces a
+    # reference clip to the x-vector a SpeechT5 model conditions its voice
+    # on (spkrec-xvect-voxceleb). Imported lazily in speech_generation.py,
+    # so it's only exercised - and its model only downloaded - by a call
+    # that actually passes speaker_embedding.
+    "speechbrain>=1.0.3",
     # Utilities
     "qrcode>=8.2",
     "requests>=2.34.2",
diff --git a/tests/test_speech_generation.py b/tests/test_speech_generation.py
index 89d46c61..e77bc394 100644
--- a/tests/test_speech_generation.py
+++ b/tests/test_speech_generation.py
@@ -145,6 +145,97 @@ def test_a_preset_the_model_cannot_take_is_an_error(self, mock_pipeline):
         self.assertIn("voice_preset", str(raised.exception))
         self.assertIn("facebook/mms-tts-eng", str(raised.exception))
 
+    @patch("dw.tasks.speech_generation._speaker_embedding_tensor")
+    @patch("dw.tasks.speech_generation.hf_pipeline")
+    def test_speaker_embedding_reaches_forward_params_for_speecht5(
+        self, mock_pipeline, mock_tensor
+    ):
+        pipe = MagicMock(return_value=spoken())
+        pipe.model.config.model_type = "speecht5"
+        mock_pipeline.return_value = pipe
+        mock_tensor.return_value = "the-x-vector"
+
+        generate_speech(
+            "hi",
+            device="cpu",
+            model_name="microsoft/speecht5_tts",
+            speaker_embedding="asset:voices/iris.wav",
+        )
+
+        mock_tensor.assert_called_once_with("asset:voices/iris.wav", "cpu")
+        self.assertEqual(
+            pipe.call_args[1]["forward_params"],
+            {"speaker_embeddings": "the-x-vector"},
+        )
+
+    @patch("dw.tasks.speech_generation._speaker_embedding_tensor")
+    @patch("dw.tasks.speech_generation.hf_pipeline")
+    def test_speaker_embedding_merges_with_other_forward_params(
+        self, mock_pipeline, mock_tensor
+    ):
+        pipe = MagicMock(return_value=spoken())
+        pipe.model.config.model_type = "speecht5"
+        mock_pipeline.return_value = pipe
+        mock_tensor.return_value = "the-x-vector"
+
+        generate_speech(
+            "hi",
+            device="cpu",
+            model_name="microsoft/speecht5_tts",
+            speaker_embedding="asset:voices/iris.wav",
+            forward_params={"do_sample": True},
+        )
+
+        self.assertEqual(
+            pipe.call_args[1]["forward_params"],
+            {"do_sample": True, "speaker_embeddings": "the-x-vector"},
+        )
+
+    @patch("dw.tasks.speech_generation._speaker_embedding_tensor")
+    @patch("dw.tasks.speech_generation.hf_pipeline")
+    def test_speaker_embedding_on_a_non_speecht5_model_is_an_error(
+        self, mock_pipeline, mock_tensor
+    ):
+        # Only SpeechT5 conditions on an x-vector; a VITS model would drop
+        # 'speaker_embeddings' as an unrecognised forward kwarg and generate
+        # in its own voice
+        pipe = MagicMock(return_value=spoken())
+        pipe.model.config.model_type = "vits"
+        mock_pipeline.return_value = pipe
+
+        with self.assertRaises(ValueError) as raised:
+            generate_speech(
+                "hi",
+                model_name="facebook/mms-tts-vits",
+                speaker_embedding="asset:voices/iris.wav",
+            )
+
+        self.assertIn("speaker_embedding", str(raised.exception))
+        self.assertIn("facebook/mms-tts-vits", str(raised.exception))
+        mock_tensor.assert_not_called()
+
+    @patch("dw.tasks.speech_generation.hf_pipeline")
+    def test_vits_speaker_id_passes_through_forward_params_unchanged(
+        self, mock_pipeline
+    ):
+        # The other half of speaker conditioning (#223): a VITS model's
+        # speaker_id is a plain int forward kwarg that already reached the
+        # model through forward_params before speaker_embedding existed, and
+        # needs no code of its own - confirmed here by never touching
+        # speaker_embedding and still seeing speaker_id pass through intact
+        pipe = MagicMock(return_value=spoken())
+        pipe.model.config.model_type = "vits"
+        mock_pipeline.return_value = pipe
+
+        generate_speech(
+            "hi",
+            device="cpu",
+            model_name="facebook/mms-tts-vits",
+            forward_params={"speaker_id": 3},
+        )
+
+        self.assertEqual(pipe.call_args[1]["forward_params"], {"speaker_id": 3})
+
 
 class TestHandleSpeechGeneration(unittest.TestCase):
     """Covers the task.py dispatch handler directly, since

From 01b54c61eedafc9fe1911a17b877d6bf71023711 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Fri, 18 Sep 2026 14:10:40 -0500
Subject: [PATCH 33/77] fix(tasks): #220 dissolve_videos docstring hold
 ceiling, #223 speaker embedding shape

dissolve_videos.py's match_levels_dbfs docstring carried its own copy of
the -0.5 dBFS hold ceiling / match_levels_held / per-shot log text, stale
because the earlier #220 fix only touched concat_videos.py's copy.

_speaker_embedding_tensor returned embedding.squeeze() -> (512,), which
SpeechT5's generate() rejects with "The first dimension of
speaker_embeddings must be either 1 or the same as batch_size". Now
emits HF's own recipe - normalize().squeeze().unsqueeze(0) -> (1, 512)
float32 on the pipe's device.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 dw/tasks/dissolve_videos.py     |  5 ++++-
 dw/tasks/speech_generation.py   |  6 ++++-
 tests/test_speech_generation.py | 40 ++++++++++++++++++++++++++++++++-
 3 files changed, 48 insertions(+), 3 deletions(-)

diff --git a/dw/tasks/dissolve_videos.py b/dw/tasks/dissolve_videos.py
index 2f281c92..ea554906 100644
--- a/dw/tasks/dissolve_videos.py
+++ b/dw/tasks/dissolve_videos.py
@@ -57,7 +57,10 @@ def dissolve_videos(
             default; see concat_videos, which has the same pair. Left off, a
             spread wide enough to hear is logged as a warning
         match_levels_dbfs: The level match_levels moves every shot to -
-            defaults to -1 dBFS for "peak" and -20 dBFS for "rms"
+            defaults to -1 dBFS for "peak" and -20 dBFS for "rms". A shot
+            that would clip at the target is held at -0.5 dBFS peak instead,
+            reported as a match_levels_held warning, with a per-shot log
+            event naming the hold
 
     Returns:
         One AudioVideo; its audio is None unless every input carries a track
diff --git a/dw/tasks/speech_generation.py b/dw/tasks/speech_generation.py
index 736a1293..5af8e356 100644
--- a/dw/tasks/speech_generation.py
+++ b/dw/tasks/speech_generation.py
@@ -71,7 +71,11 @@ def load_encoder():
 
     with torch.no_grad():
         embedding = encoder.encode_batch(torch.as_tensor(mono).unsqueeze(0))
-    return embedding.squeeze()
+        embedding = torch.nn.functional.normalize(embedding, dim=2)
+    # SpeechT5's generate() wants (batch, 512); the encoder's raw output is
+    # (1, 1, 512), so squeeze collapses it back to (512,) before restoring
+    # the batch dimension the model actually requires
+    return embedding.squeeze().unsqueeze(0).to(device=device, dtype=torch.float32)
 
 
 def generate_speech(text, device="cpu", **kwargs):
diff --git a/tests/test_speech_generation.py b/tests/test_speech_generation.py
index e77bc394..784d6e61 100644
--- a/tests/test_speech_generation.py
+++ b/tests/test_speech_generation.py
@@ -4,8 +4,13 @@
 from unittest.mock import patch, MagicMock
 
 import numpy
+import torch
 
-from dw.tasks.speech_generation import generate_speech, _DEFAULT_MODEL
+from dw.tasks.speech_generation import (
+    generate_speech,
+    _DEFAULT_MODEL,
+    _speaker_embedding_tensor,
+)
 
 
 def spoken(sample_rate=24000, samples=480):
@@ -237,6 +242,39 @@ def test_vits_speaker_id_passes_through_forward_params_unchanged(
         self.assertEqual(pipe.call_args[1]["forward_params"], {"speaker_id": 3})
 
 
+class TestSpeakerEmbeddingTensor(unittest.TestCase):
+    """#223 regression: SpeechT5's generate() rejects a bare (512,) vector -
+    it wants (batch, 512). These exercise the real squeeze/unsqueeze logic
+    rather than mocking it away, unlike the forward_params tests above."""
+
+    @patch("dw.tasks.speech_generation.load_audio")
+    @patch("dw.tasks.speech_generation.cached_model")
+    def test_output_shape_is_batch_of_one_by_512(self, mock_cached_model, mock_load_audio):
+        mock_load_audio.return_value = (numpy.zeros((1, 16000), dtype=numpy.float32), 16000)
+        encoder = MagicMock()
+        # speechbrain's raw encode_batch output: (1, 1, 512)
+        encoder.encode_batch.return_value = torch.zeros((1, 1, 512))
+        mock_cached_model.return_value = encoder
+
+        # speechbrain isn't a hard dependency of the test env; the helper
+        # imports it lazily, so stand in a fake module rather than requiring
+        # the real package just to exercise the tensor-shape logic
+        fake_module = MagicMock()
+        fake_module.EncoderClassifier = MagicMock()
+        with patch.dict(
+            "sys.modules",
+            {
+                "speechbrain": MagicMock(),
+                "speechbrain.inference": MagicMock(),
+                "speechbrain.inference.speaker": fake_module,
+            },
+        ):
+            embedding = _speaker_embedding_tensor("asset:voices/iris.wav", "cpu")
+
+        self.assertEqual(tuple(embedding.shape), (1, 512))
+        self.assertEqual(embedding.dtype, torch.float32)
+
+
 class TestHandleSpeechGeneration(unittest.TestCase):
     """Covers the task.py dispatch handler directly, since
     test_task_discovery.py only introspects the command registry rather than

From fda308429852509b3db0e776839c767b0b27cbdc Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Fri, 18 Sep 2026 17:11:55 -0500
Subject: [PATCH 34/77] fix(tests): #224 - stop pinning diffusers' private
 cache-context internals (#230)

PR #228's CI (backend job) failed 4 tests in test_cache_blocks.py after
diffusers' upstream main (installed fresh from git each run, per
requirements) renamed StateManager's private context attribute and
HookRegistry._set_context, and reworded StateManager.get_state's error
text. None of that is diffusers' public contract - it's exactly the
kind of drift expected from tracking a moving target - and none of it
is what these tests need to check.

- test_cache_state_needs_a_context / test_cache_context_clears_after_an_error
  now assert only the ValueError type, not diffusers' private wording or
  its private _current_context attribute; the second checks context
  clearing behaviorally by calling get_state() again instead.
- _DualStreamModel now mixes in diffusers.CacheMixin so _run_two_steps can
  drive it through the public model.cache_context(name) - the same method
  dw.pipeline_processors.pipeline.stateful_cache_context calls in
  production - instead of reaching into HookRegistry._set_context directly.

Unrelated to the transformers floor bump itself; this failure would have
surfaced on develop's next CI run too since it tracks the same moving
diffusers HEAD. Full suite: 5092 passed, 16 skipped locally.

Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
---
 tests/test_cache_blocks.py | 41 ++++++++++++++++++++++++--------------
 1 file changed, 26 insertions(+), 15 deletions(-)

diff --git a/tests/test_cache_blocks.py b/tests/test_cache_blocks.py
index c068a896..72fe70ff 100644
--- a/tests/test_cache_blocks.py
+++ b/tests/test_cache_blocks.py
@@ -10,6 +10,7 @@
 import os
 import sys
 
+import diffusers
 import pytest
 import torch
 
@@ -234,11 +235,16 @@ def _state_manager(model):
 
 
 def test_cache_state_needs_a_context():
-    """Without the context, the hook raises - the failure the wrapper prevents."""
+    """Without the context, the hook raises - the failure the wrapper prevents.
+
+    Only the exception type is asserted: the message is diffusers' own private
+    wording (already changed once upstream) and not part of any contract dw
+    relies on.
+    """
 
     manager = _state_manager(_cached_tiny_model())
 
-    with pytest.raises(ValueError, match="No context is set"):
+    with pytest.raises(ValueError):
         manager.get_state()
 
 
@@ -268,7 +274,12 @@ def test_cache_state_does_not_leak_between_runs():
 
 
 def test_cache_context_clears_after_an_error():
-    """An errored run must not strand a context that the next run inherits."""
+    """An errored run must not strand a context that the next run inherits.
+
+    Checked behaviorally (get_state rejects a missing context, same as before
+    any context was ever set) rather than via the state manager's private
+    context attribute, whose name is diffusers' own implementation detail.
+    """
     from dw.pipeline_processors.pipeline import stateful_cache_context
 
     model = _cached_tiny_model()
@@ -278,7 +289,8 @@ def test_cache_context_clears_after_an_error():
         with stateful_cache_context(_FakePipeline(model)):
             raise RuntimeError("boom")
 
-    assert manager._current_context is None
+    with pytest.raises(ValueError):
+        manager.get_state()
 
 
 @pytest.mark.parametrize("transformer", [None, object()])
@@ -330,7 +342,12 @@ def forward(self, hidden_states, audio_hidden_states, encoder_hidden_states=None
         return hidden_states + 1.0, audio_hidden_states + 10.0
 
 
-class _DualStreamModel(torch.nn.Module):
+class _DualStreamModel(torch.nn.Module, diffusers.CacheMixin):
+    """Mixes in CacheMixin so `cache_context` is the same public method
+    dw.pipeline_processors.pipeline.stateful_cache_context calls in production,
+    rather than a test-only stand-in for it.
+    """
+
     def __init__(self, num_blocks=2):
         super().__init__()
         self.transformer_blocks = torch.nn.ModuleList(
@@ -365,25 +382,19 @@ def _register_dual_stream_block(remap):
 def _run_two_steps(model):
     """Drive the model twice - the second step is the one the cache skips.
 
-    The context is set the way CacheMixin.cache_context sets it; the stub model
-    is a bare Module rather than a diffusers model, so it has no such method of
-    its own.
+    Uses the model's own CacheMixin.cache_context, the same public method
+    dw's stateful_cache_context calls in production, rather than reaching into
+    HookRegistry's private context-setting internals directly.
     """
-    from diffusers.hooks import HookRegistry
-
     hidden_states = torch.zeros(1, 6, 4)
     audio_hidden_states = torch.zeros(1, 5, 4)
     encoder_hidden_states = torch.zeros(1, 3, 4)
 
-    registry = HookRegistry.check_if_exists_or_initialize(model)
-    registry._set_context("test")
-    try:
+    with model.cache_context("test"):
         for _ in range(2):
             hidden_states, audio_hidden_states = model(
                 hidden_states, audio_hidden_states, encoder_hidden_states
             )
-    finally:
-        registry._set_context(None)
     return hidden_states, audio_hidden_states
 
 

From fe8f7ea0a9571600ac7ffae5dad6f390fb801842 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Fri, 18 Sep 2026 17:16:40 -0500
Subject: [PATCH 35/77] fix(docs): clarify workflow listing instructions in
 SKILL.md

---
 plugins/dw/skills/series-episodes/SKILL.md | 25 ++++++++++++++--------
 1 file changed, 16 insertions(+), 9 deletions(-)

diff --git a/plugins/dw/skills/series-episodes/SKILL.md b/plugins/dw/skills/series-episodes/SKILL.md
index 4406b248..9a12b38f 100644
--- a/plugins/dw/skills/series-episodes/SKILL.md
+++ b/plugins/dw/skills/series-episodes/SKILL.md
@@ -19,8 +19,10 @@ and the one step (0 below) that keeps the cast fixed; everything past it is
 ## Before anything
 
 1. `get_server_info` for the device and workspace.
-2. `list_workflows(shape="shot")` for the H3 templates, `list_workflows(shape="sequence")`
-   for `assemble-and-score`. Trust the listing over the names quoted here.
+2. `list_workflows(shape="sequence")` for the H3 templates and for
+   `assemble-and-score` - both `dialogue-short`/`music-video` and
+   `assemble-and-score` are shape `sequence`. Trust the listing over the
+   names quoted here.
 3. Read the `minimax-h3` skill before writing any shot - the `shots` list
    shape, the prompt format, and the hard rules (frame count, canvas,
    reference limits) all come from there and are not restated here.
@@ -90,13 +92,18 @@ One `assemble-and-score` run per episode; each episode's `total_frames` and
 
 ## Run and judge
 
-`output:` a shot straight from its generation run
-(`output:dialogue-short/<episode run id>/final/<shot>.mp4`) rather than
-downloading and re-uploading it as an asset - only the cast portraits from
-step 0 need to be assets, since they are the one thing that must outlive a
-single episode's run directory. The `final` segment there is the step's
-`subfolder`: the deliverable shot each H3 template writes, as opposed to
-`intermediate` scratch that an `output:` reference has no reason to name.
+`output:` a shot straight from its generation run rather than downloading
+and re-uploading it as an asset - only the cast portraits from step 0 need
+to be assets, since they are the one thing that must outlive a single
+episode's run directory. For `dialogue-short`/`music-video` the per-shot
+clips are the `shot` step's own files, and that step's `subfolder` is
+`intermediate` - `final` there holds only the already-concatenated episode,
+which is not a usable `shots` entry. So a recut references `output:` + the workflow's full catalog path (as
+`list_workflows` names it, prefix and all) + `/<episode run
+id>/intermediate/<workflow id>-shot@<name>.<index>-0.0.mp4` - not just the
+template's own name - read off the run's manifest (`get_job`) rather than
+guessed. Or, if the shot should outlive its run directory the way the cast
+does, `keep_output` it and reference the resulting `asset:` instead.
 
 Beyond `minimax-h3`'s own judging checklist (a character that changes
 between shots, a portrait imposing its framing, a voice without affect):

From 7001b906f1bc1ece13f29a1289183c9cb641aca9 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Fri, 18 Sep 2026 17:17:18 -0500
Subject: [PATCH 36/77] ruff format

---
 dw/plan.py                             | 12 +++-
 dw/result.py                           | 10 +--
 dw/tasks/audio_transcription.py        | 10 +--
 dw/tasks/audio_utils.py                | 22 ++++---
 dw/tasks/select.py                     |  4 +-
 tests/test_audio_utils.py              | 16 +++--
 tests/test_judge.py                    | 12 +++-
 tests/test_mcp_assets.py               | 12 +++-
 tests/test_plan.py                     | 89 ++++++++++++++++++++++----
 tests/test_result.py                   |  8 ++-
 tests/test_scalar_result_validation.py |  8 ++-
 tests/test_select.py                   | 30 +++++++--
 tests/test_select_validation.py        |  8 +--
 tests/test_speech_generation.py        |  9 ++-
 tests/test_transcribe_audio.py         |  4 +-
 tests/test_workflow.py                 |  6 +-
 16 files changed, 191 insertions(+), 69 deletions(-)

diff --git a/dw/plan.py b/dw/plan.py
index 2174247c..c7cea169 100644
--- a/dw/plan.py
+++ b/dw/plan.py
@@ -466,7 +466,13 @@ def downloads_required(expanded, base_dir, workflow_dir, cache_dir, lookup_sizes
         required.append(entry)
     for url in urls:
         required.append(
-            {"repo": None, "url": url, "gb": None, "gated": None, "access_blocked": None}
+            {
+                "repo": None,
+                "url": url,
+                "gb": None,
+                "gated": None,
+                "access_blocked": None,
+            }
         )
     return required
 
@@ -573,7 +579,9 @@ def _probe_gate_blocked(name, siblings):
     (#186). `None` when there is no file to probe or the probe fails for a
     reason other than the gate, since that is "unknown", not "not blocked".
     """
-    filename = next((s.rfilename for s in siblings if getattr(s, "rfilename", None)), None)
+    filename = next(
+        (s.rfilename for s in siblings if getattr(s, "rfilename", None)), None
+    )
     if filename is None:
         return None
     try:
diff --git a/dw/result.py b/dw/result.py
index 8a72edce..f2532362 100644
--- a/dw/result.py
+++ b/dw/result.py
@@ -822,8 +822,11 @@ def save_audio_video(self, artifact, output_path, content_type):
         # result store, so a local-only fit left the artifact's own audio
         # unfitted and a chain built from in-memory shots still drifted even
         # though each shot's own saved file was correct (#197 reopened).
-        if audio is not None and sample_rate is not None and fps and not hasattr(
-            artifact.frames, "cleanup"
+        if (
+            audio is not None
+            and sample_rate is not None
+            and fps
+            and not hasattr(artifact.frames, "cleanup")
         ):
             from .tasks.video_utils import _fit_audio_to_frames
 
@@ -886,8 +889,7 @@ def save_audio_video(self, artifact, output_path, content_type):
 
         logger.debug(f"Muxing audio at {sample_rate}Hz into {output_path}")
         self._no_headroom_warned = (
-            warn_without_headroom(audio, os.path.basename(output_path))
-            is not None
+            warn_without_headroom(audio, os.path.basename(output_path)) is not None
         )
         encode_video(
             frames_for_encoding(artifact.frames),
diff --git a/dw/tasks/audio_transcription.py b/dw/tasks/audio_transcription.py
index 7e97584b..21ebde22 100644
--- a/dw/tasks/audio_transcription.py
+++ b/dw/tasks/audio_transcription.py
@@ -59,9 +59,9 @@ def transcribe_audio(audio, device="cpu", sample_rate=None, **kwargs):
     waveform, waveform_rate = _waveform_and_rate(audio, sample_rate, "transcribe_audio")
     mono = _downmixed_mono(waveform)
     if waveform_rate != _ASR_SAMPLE_RATE:
-        mono = resample_waveform(
-            mono.reshape(1, -1), waveform_rate, _ASR_SAMPLE_RATE
-        )[0]
+        mono = resample_waveform(mono.reshape(1, -1), waveform_rate, _ASR_SAMPLE_RATE)[
+            0
+        ]
 
     model_name = kwargs.get("model_name", _DEFAULT_ASR_MODEL)
     dtype = preferred_task_dtype(device)
@@ -80,7 +80,9 @@ def load_pipe():
         ("transcribe_audio", model_name, str(device), str(dtype)), load_pipe
     )
 
-    result = pipe({"raw": mono.astype(numpy.float32), "sampling_rate": _ASR_SAMPLE_RATE})
+    result = pipe(
+        {"raw": mono.astype(numpy.float32), "sampling_rate": _ASR_SAMPLE_RATE}
+    )
     text = result["text"].strip()
     logger.info(f"Transcript: {text[:100]}{'...' if len(text) > 100 else ''}")
     return text
diff --git a/dw/tasks/audio_utils.py b/dw/tasks/audio_utils.py
index a3e31d9a..f2b2598a 100644
--- a/dw/tasks/audio_utils.py
+++ b/dw/tasks/audio_utils.py
@@ -144,11 +144,7 @@ def _spectral_flatness(waveform, sample_rate=None, native_sample_rate=None):
     upsampled tail is measured the same as it would be at its own rate.
     """
     spectrum = numpy.abs(numpy.fft.rfft(waveform, axis=1))
-    if (
-        sample_rate
-        and native_sample_rate
-        and native_sample_rate < sample_rate
-    ):
+    if sample_rate and native_sample_rate and native_sample_rate < sample_rate:
         native_bins = max(
             2,
             int(spectrum.shape[1] * native_sample_rate / sample_rate),
@@ -549,7 +545,9 @@ def gain_audio(
         An AudioTrack holding the whole track with the region's gain
         applied, and the rate it is at
     """
-    start_seconds = _as_number(start_seconds, float, "start_seconds", command="gain_audio")
+    start_seconds = _as_number(
+        start_seconds, float, "start_seconds", command="gain_audio"
+    )
     duration_seconds = _as_number(
         duration_seconds, float, "duration_seconds", command="gain_audio"
     )
@@ -1231,7 +1229,13 @@ def _warn_on_rate_override(command, actual_rate, given_rate):
 
 
 def compress_audio(
-    audio, threshold_dbfs, ratio=4.0, attack_ms=10.0, release_ms=100.0, mode="compress", sample_rate=None
+    audio,
+    threshold_dbfs,
+    ratio=4.0,
+    attack_ms=10.0,
+    release_ms=100.0,
+    mode="compress",
+    sample_rate=None,
 ):
     """Task command: shape a track's dynamics with an envelope-follower.
 
@@ -1280,9 +1284,7 @@ def compress_audio(
         return _as_track(waveform, sample_rate, "compress_audio")
 
     envelope = _follow_envelope(waveform, sample_rate, attack_ms, release_ms)
-    envelope_dbfs = 20.0 * numpy.log10(
-        numpy.maximum(envelope, _ENVELOPE_FLOOR_LINEAR)
-    )
+    envelope_dbfs = 20.0 * numpy.log10(numpy.maximum(envelope, _ENVELOPE_FLOOR_LINEAR))
 
     if mode == "gate":
         past_threshold = numpy.maximum(0.0, threshold_dbfs - envelope_dbfs)
diff --git a/dw/tasks/select.py b/dw/tasks/select.py
index 5000764b..21ce7b93 100644
--- a/dw/tasks/select.py
+++ b/dw/tasks/select.py
@@ -106,4 +106,6 @@ def select(candidates, scores, rule, threshold=None, index=None):
         raise ValueError(f"select: unknown rule: {rule!r}")
 
     logger.debug(f"select: rule={rule} chose position {position}")
-    return Selected(value=candidates[position], position=position, score=parsed_scores[position])
+    return Selected(
+        value=candidates[position], position=position, score=parsed_scores[position]
+    )
diff --git a/tests/test_audio_utils.py b/tests/test_audio_utils.py
index 6ac091be..303f60a3 100644
--- a/tests/test_audio_utils.py
+++ b/tests/test_audio_utils.py
@@ -367,7 +367,8 @@ def test_native_rate_speech_like_material_warns_via_harmonicity(self, caplog):
         f0 = 150.0
         harmonics = [1.0, 0.6, 0.45, 0.3, 0.2, 0.12]
         speech_like = sum(
-            amp * numpy.sin(2 * numpy.pi * f0 * (k + 1) * t + rng.uniform(0, 2 * numpy.pi))
+            amp
+            * numpy.sin(2 * numpy.pi * f0 * (k + 1) * t + rng.uniform(0, 2 * numpy.pi))
             for k, amp in enumerate(harmonics)
         )
         speech_like = speech_like + rng.normal(0, 0.25, n)
@@ -395,9 +396,7 @@ def test_native_rate_noise_does_not_warn_at_speech_rate(self, caplog):
         assert "tonal" not in caplog.text
         assert "speech" not in caplog.text
 
-    def test_upsampled_noise_does_not_falsely_warn_when_native_rate_given(
-        self, caplog
-    ):
+    def test_upsampled_noise_does_not_falsely_warn_when_native_rate_given(self, caplog):
         # band-limited interpolation leaves near-silence above the tail's own
         # Nyquist, which used to depress flatness and read as spuriously
         # tonal purely because of the resample - not because of the content
@@ -1077,9 +1076,12 @@ def test_a_waveform_needs_a_sample_rate(self):
 class TestFilterAudio:
     def tone(self, frequency, samples=2000, rate=8000, level=1.0):
         t = numpy.arange(samples) / rate
-        return numpy.sin(2 * numpy.pi * frequency * t).astype(numpy.float32)[
-            numpy.newaxis, :
-        ] * level
+        return (
+            numpy.sin(2 * numpy.pi * frequency * t).astype(numpy.float32)[
+                numpy.newaxis, :
+            ]
+            * level
+        )
 
     def rms(self, waveform):
         # skip the filter's brief settling transient
diff --git a/tests/test_judge.py b/tests/test_judge.py
index c358dd84..d7905f4d 100644
--- a/tests/test_judge.py
+++ b/tests/test_judge.py
@@ -26,7 +26,9 @@ def _mock_pipe(self, mock_pipeline, generated):
     def test_parses_a_clean_number(self, mock_pipeline):
         self._mock_pipe(mock_pipeline, "7")
 
-        score = judge(self._make_image(), rubric="Sharpest image", scale=[0, 10], device="cpu")
+        score = judge(
+            self._make_image(), rubric="Sharpest image", scale=[0, 10], device="cpu"
+        )
 
         self.assertEqual(score, 7.0)
 
@@ -34,7 +36,9 @@ def test_parses_a_clean_number(self, mock_pipeline):
     def test_parses_a_number_in_prose(self, mock_pipeline):
         self._mock_pipe(mock_pipeline, "I would rate this a 8 out of 10 for sharpness.")
 
-        score = judge(self._make_image(), rubric="Sharpest image", scale=[0, 10], device="cpu")
+        score = judge(
+            self._make_image(), rubric="Sharpest image", scale=[0, 10], device="cpu"
+        )
 
         self.assertEqual(score, 8.0)
 
@@ -43,7 +47,9 @@ def test_no_number_in_reply_is_an_error(self, mock_pipeline):
         self._mock_pipe(mock_pipeline, "I cannot judge this image.")
 
         with self.assertRaises(ValueError) as ctx:
-            judge(self._make_image(), rubric="Sharpest image", scale=[0, 10], device="cpu")
+            judge(
+                self._make_image(), rubric="Sharpest image", scale=[0, 10], device="cpu"
+            )
 
         message = str(ctx.exception)
         self.assertIn("judge", message)
diff --git a/tests/test_mcp_assets.py b/tests/test_mcp_assets.py
index e8b7904c..6523c9c1 100644
--- a/tests/test_mcp_assets.py
+++ b/tests/test_mcp_assets.py
@@ -238,7 +238,9 @@ def test_content_is_decoded_and_posted(self):
         body = b"riff-bytes"
 
         result = upload_asset(
-            client, content=base64.b64encode(body).decode("ascii"), asset_name="cast/priya-voice.wav"
+            client,
+            content=base64.b64encode(body).decode("ascii"),
+            asset_name="cast/priya-voice.wav",
         )
 
         assert seen["body"] == body
@@ -269,7 +271,9 @@ def test_a_kind_the_library_does_not_take_is_refused(self):
         client, seen = recording()
         with pytest.raises(DwApiError, match="not a kind"):
             upload_asset(
-                client, content=base64.b64encode(b"x").decode("ascii"), asset_name="script.py"
+                client,
+                content=base64.b64encode(b"x").decode("ascii"),
+                asset_name="script.py",
             )
         assert "body" not in seen
 
@@ -281,7 +285,9 @@ def test_invalid_base64_says_so(self):
 
     def test_content_over_the_inline_limit_is_refused(self):
         client, seen = recording()
-        oversized = base64.b64encode(b"0" * (MAX_INLINE_UPLOAD_BYTES + 1)).decode("ascii")
+        oversized = base64.b64encode(b"0" * (MAX_INLINE_UPLOAD_BYTES + 1)).decode(
+            "ascii"
+        )
         with pytest.raises(DwApiError, match="inline upload"):
             upload_asset(client, content=oversized, asset_name="x.png")
         assert "body" not in seen
diff --git a/tests/test_plan.py b/tests/test_plan.py
index c6911bbd..7f806a63 100644
--- a/tests/test_plan.py
+++ b/tests/test_plan.py
@@ -491,7 +491,12 @@ def test_a_child_measured_on_another_device_is_still_added(self, plan, tmp_path)
 class TestDownloadsRequired:
     def test_a_repo_not_in_the_cache_is_required(self, plan):
         assert plan()["downloads_required"] == [
-            {"repo": "org/still-model", "gb": None, "gated": None, "access_blocked": None}
+            {
+                "repo": "org/still-model",
+                "gb": None,
+                "gated": None,
+                "access_blocked": None,
+            }
         ]
 
     def test_a_cached_repo_is_not(self, plan, monkeypatch):
@@ -609,7 +614,12 @@ def fake_model_info(name, **kwargs):
         monkeypatch.setattr(dw.plan, "model_info", fake_model_info)
         answer = plan(lookup_sizes=True)["downloads_required"]
         assert answer == [
-            {"repo": "org/still-model", "gb": 2.5, "gated": False, "access_blocked": False}
+            {
+                "repo": "org/still-model",
+                "gb": 2.5,
+                "gated": False,
+                "access_blocked": False,
+            }
         ]
         assert calls[0][0] == "org/still-model"
         assert calls[0][1]["files_metadata"] is True
@@ -628,10 +638,17 @@ class Info:
         monkeypatch.setattr(dw.plan, "model_info", lambda name, **k: Info())
         monkeypatch.setattr(dw.plan, "get_hf_file_metadata", lambda url, **k: object())
         assert plan(lookup_sizes=True)["downloads_required"] == [
-            {"repo": "org/still-model", "gb": None, "gated": "manual", "access_blocked": False}
+            {
+                "repo": "org/still-model",
+                "gb": None,
+                "gated": "manual",
+                "access_blocked": False,
+            }
         ]
 
-    def test_a_gated_repo_this_token_lacks_access_to_is_blocked(self, plan, monkeypatch):
+    def test_a_gated_repo_this_token_lacks_access_to_is_blocked(
+        self, plan, monkeypatch
+    ):
         import httpx
         import dw.plan
         from huggingface_hub.utils import GatedRepoError
@@ -651,7 +668,12 @@ def boom(*a, **k):
         monkeypatch.setattr(dw.plan, "model_info", lambda name, **k: Info())
         monkeypatch.setattr(dw.plan, "get_hf_file_metadata", boom)
         assert plan(lookup_sizes=True)["downloads_required"] == [
-            {"repo": "org/still-model", "gb": None, "gated": "manual", "access_blocked": True}
+            {
+                "repo": "org/still-model",
+                "gb": None,
+                "gated": "manual",
+                "access_blocked": True,
+            }
         ]
 
     def test_a_gated_repo_model_info_itself_refuses_is_blocked(self, plan, monkeypatch):
@@ -666,7 +688,12 @@ def boom(*a, **k):
 
         monkeypatch.setattr(dw.plan, "model_info", boom)
         assert plan(lookup_sizes=True)["downloads_required"] == [
-            {"repo": "org/still-model", "gb": None, "gated": True, "access_blocked": True}
+            {
+                "repo": "org/still-model",
+                "gb": None,
+                "gated": True,
+                "access_blocked": True,
+            }
         ]
 
     def test_a_gated_repo_with_no_probeable_file_is_unknown(self, plan, monkeypatch):
@@ -678,10 +705,17 @@ class Info:
 
         monkeypatch.setattr(dw.plan, "model_info", lambda name, **k: Info())
         assert plan(lookup_sizes=True)["downloads_required"] == [
-            {"repo": "org/still-model", "gb": None, "gated": "auto", "access_blocked": None}
+            {
+                "repo": "org/still-model",
+                "gb": None,
+                "gated": "auto",
+                "access_blocked": None,
+            }
         ]
 
-    def test_a_gate_probe_failing_for_an_unrelated_reason_is_unknown(self, plan, monkeypatch):
+    def test_a_gate_probe_failing_for_an_unrelated_reason_is_unknown(
+        self, plan, monkeypatch
+    ):
         import dw.plan
 
         class Sibling:
@@ -697,7 +731,12 @@ def boom(*a, **k):
         monkeypatch.setattr(dw.plan, "model_info", lambda name, **k: Info())
         monkeypatch.setattr(dw.plan, "get_hf_file_metadata", boom)
         assert plan(lookup_sizes=True)["downloads_required"] == [
-            {"repo": "org/still-model", "gb": None, "gated": "auto", "access_blocked": None}
+            {
+                "repo": "org/still-model",
+                "gb": None,
+                "gated": "auto",
+                "access_blocked": None,
+            }
         ]
 
     def test_a_hub_failure_is_a_null_size(self, plan, monkeypatch):
@@ -708,7 +747,12 @@ def boom(*a, **k):
 
         monkeypatch.setattr(dw.plan, "model_info", boom)
         assert plan(lookup_sizes=True)["downloads_required"] == [
-            {"repo": "org/still-model", "gb": None, "gated": None, "access_blocked": None}
+            {
+                "repo": "org/still-model",
+                "gb": None,
+                "gated": None,
+                "access_blocked": None,
+            }
         ]
 
     def test_lookup_sizes_false_never_calls_the_hub(self, plan, monkeypatch):
@@ -724,8 +768,18 @@ def boom(*a, **k):
 class TestGateWarnings:
     def test_a_blocked_repo_gets_a_warning(self):
         required = [
-            {"repo": "org/free-model", "gb": 1.0, "gated": False, "access_blocked": False},
-            {"repo": "org/gated-model", "gb": None, "gated": True, "access_blocked": True},
+            {
+                "repo": "org/free-model",
+                "gb": 1.0,
+                "gated": False,
+                "access_blocked": False,
+            },
+            {
+                "repo": "org/gated-model",
+                "gb": None,
+                "gated": True,
+                "access_blocked": True,
+            },
         ]
         warnings = gate_warnings(required)
         assert len(warnings) == 1
@@ -734,12 +788,19 @@ def test_a_blocked_repo_gets_a_warning(self):
 
     def test_an_accepted_gate_gets_no_warning(self):
         required = [
-            {"repo": "org/manual-gate", "gb": 1.0, "gated": "manual", "access_blocked": False}
+            {
+                "repo": "org/manual-gate",
+                "gb": 1.0,
+                "gated": "manual",
+                "access_blocked": False,
+            }
         ]
         assert gate_warnings(required) == []
 
     def test_unknown_gate_status_gets_no_warning(self):
-        required = [{"repo": "org/offline", "gb": None, "gated": None, "access_blocked": None}]
+        required = [
+            {"repo": "org/offline", "gb": None, "gated": None, "access_blocked": None}
+        ]
         assert gate_warnings(required) == []
 
 
diff --git a/tests/test_result.py b/tests/test_result.py
index 27770327..a577b922 100644
--- a/tests/test_result.py
+++ b/tests/test_result.py
@@ -902,7 +902,9 @@ def test_a_declared_rate_matching_the_carried_rate_is_not_a_warning(self):
             finally:
                 deactivate_context(token)
 
-            assert [e for e in events if e.get("kind") == "rate_override_mismatch"] == []
+            assert [
+                e for e in events if e.get("kind") == "rate_override_mismatch"
+            ] == []
 
     def test_a_declared_rate_with_no_carried_rate_is_not_a_warning(self):
         # A generated artifact (e.g. a modular pipeline's dict output) carries
@@ -921,7 +923,9 @@ def test_a_declared_rate_with_no_carried_rate_is_not_a_warning(self):
             finally:
                 deactivate_context(token)
 
-            assert [e for e in events if e.get("kind") == "rate_override_mismatch"] == []
+            assert [
+                e for e in events if e.get("kind") == "rate_override_mismatch"
+            ] == []
 
     def test_a_batch_of_tracks_each_save_at_the_carried_rate(self):
         # Each item of a batched .audios is its own AudioTrack, so each is saved
diff --git a/tests/test_scalar_result_validation.py b/tests/test_scalar_result_validation.py
index 7241790e..8d87325f 100644
--- a/tests/test_scalar_result_validation.py
+++ b/tests/test_scalar_result_validation.py
@@ -62,7 +62,13 @@ def test_result_on_artifact_returning_command_is_fine(self):
 
     def test_unknown_command_is_ignored(self):
         definition = {
-            "steps": [_step("mystery", "not_a_real_command", result={"content_type": "image/png"})]
+            "steps": [
+                _step(
+                    "mystery",
+                    "not_a_real_command",
+                    result={"content_type": "image/png"},
+                )
+            ]
         }
 
         errors = scalar_result_errors(definition, source_indices=[0])
diff --git a/tests/test_select.py b/tests/test_select.py
index 3bf9af7c..f3204900 100644
--- a/tests/test_select.py
+++ b/tests/test_select.py
@@ -9,13 +9,17 @@
 
 class TestSelect:
     def test_argmax_returns_the_highest_scoring_candidate(self):
-        result = select(candidates=["a", "b", "c"], scores=[0.1, 0.9, 0.5], rule="argmax")
+        result = select(
+            candidates=["a", "b", "c"], scores=[0.1, 0.9, 0.5], rule="argmax"
+        )
         assert result.value == "b"
         assert result.position == 1
         assert result.score == 0.9
 
     def test_argmin_returns_the_lowest_scoring_candidate(self):
-        result = select(candidates=["a", "b", "c"], scores=[0.1, 0.9, 0.5], rule="argmin")
+        result = select(
+            candidates=["a", "b", "c"], scores=[0.1, 0.9, 0.5], rule="argmin"
+        )
         assert result.value == "a"
         assert result.position == 0
         assert result.score == 0.1
@@ -43,13 +47,17 @@ def test_first_below_returns_the_first_candidate_meeting_the_threshold(self):
         assert result.score == 0.1
 
     def test_index_returns_the_candidate_at_that_position(self):
-        result = select(candidates=["a", "b", "c"], scores=[0.1, 0.9, 0.5], rule="index", index=2)
+        result = select(
+            candidates=["a", "b", "c"], scores=[0.1, 0.9, 0.5], rule="index", index=2
+        )
         assert result.value == "c"
         assert result.position == 2
         assert result.score == 0.5
 
     def test_ties_go_to_the_first_in_list_order(self):
-        result = select(candidates=["a", "b", "c"], scores=[0.5, 0.9, 0.9], rule="argmax")
+        result = select(
+            candidates=["a", "b", "c"], scores=[0.5, 0.9, 0.9], rule="argmax"
+        )
         assert result.value == "b"
         assert result.position == 1
 
@@ -68,11 +76,21 @@ def test_length_mismatch_names_both_lengths(self):
 
     def test_first_above_with_nothing_passing_is_an_error(self):
         with pytest.raises(ValueError, match="no candidate"):
-            select(candidates=["a", "b"], scores=[0.1, 0.2], rule="first_above", threshold=0.5)
+            select(
+                candidates=["a", "b"],
+                scores=[0.1, 0.2],
+                rule="first_above",
+                threshold=0.5,
+            )
 
     def test_first_below_with_nothing_passing_is_an_error(self):
         with pytest.raises(ValueError, match="no candidate"):
-            select(candidates=["a", "b"], scores=[0.6, 0.7], rule="first_below", threshold=0.5)
+            select(
+                candidates=["a", "b"],
+                scores=[0.6, 0.7],
+                rule="first_below",
+                threshold=0.5,
+            )
 
     def test_index_out_of_range_is_an_error(self):
         with pytest.raises(ValueError, match="index 5"):
diff --git a/tests/test_select_validation.py b/tests/test_select_validation.py
index cd70c264..29a9d276 100644
--- a/tests/test_select_validation.py
+++ b/tests/test_select_validation.py
@@ -64,9 +64,7 @@ def test_threshold_rule_with_threshold_is_fine(self):
 
     def test_non_threshold_rule_with_threshold_is_an_error(self):
         definition = {
-            "steps": [
-                _step(rule="argmax", candidates=["a"], scores=[1], threshold=0.5)
-            ]
+            "steps": [_step(rule="argmax", candidates=["a"], scores=[1], threshold=0.5)]
         }
 
         errors = select_errors(definition, source_indices=[0])
@@ -103,9 +101,7 @@ def test_non_index_rule_with_index_is_an_error(self):
 
     def test_candidates_gather_scores_plain_list_is_an_error(self):
         definition = {
-            "steps": [
-                _step(rule="argmax", candidates="gather:still", scores=[1, 2])
-            ]
+            "steps": [_step(rule="argmax", candidates="gather:still", scores=[1, 2])]
         }
 
         errors = select_errors(definition, source_indices=[0])
diff --git a/tests/test_speech_generation.py b/tests/test_speech_generation.py
index 784d6e61..8bfdf100 100644
--- a/tests/test_speech_generation.py
+++ b/tests/test_speech_generation.py
@@ -249,8 +249,13 @@ class TestSpeakerEmbeddingTensor(unittest.TestCase):
 
     @patch("dw.tasks.speech_generation.load_audio")
     @patch("dw.tasks.speech_generation.cached_model")
-    def test_output_shape_is_batch_of_one_by_512(self, mock_cached_model, mock_load_audio):
-        mock_load_audio.return_value = (numpy.zeros((1, 16000), dtype=numpy.float32), 16000)
+    def test_output_shape_is_batch_of_one_by_512(
+        self, mock_cached_model, mock_load_audio
+    ):
+        mock_load_audio.return_value = (
+            numpy.zeros((1, 16000), dtype=numpy.float32),
+            16000,
+        )
         encoder = MagicMock()
         # speechbrain's raw encode_batch output: (1, 1, 512)
         encoder.encode_batch.return_value = torch.zeros((1, 1, 512))
diff --git a/tests/test_transcribe_audio.py b/tests/test_transcribe_audio.py
index ae3b7143..3391e6e8 100644
--- a/tests/test_transcribe_audio.py
+++ b/tests/test_transcribe_audio.py
@@ -47,9 +47,7 @@ def test_builds_an_asr_pipeline_with_default_model(self, mock_pipeline):
 
         transcribe_audio(waveform, device="cpu", sample_rate=rate)
 
-        self.assertEqual(
-            mock_pipeline.call_args[0][0], "automatic-speech-recognition"
-        )
+        self.assertEqual(mock_pipeline.call_args[0][0], "automatic-speech-recognition")
         self.assertEqual(mock_pipeline.call_args[1]["model"], _DEFAULT_ASR_MODEL)
 
     @patch("dw.tasks.audio_transcription.hf_pipeline")
diff --git a/tests/test_workflow.py b/tests/test_workflow.py
index 7ff2bc7e..35f7feac 100644
--- a/tests/test_workflow.py
+++ b/tests/test_workflow.py
@@ -801,7 +801,11 @@ def test_run_records_the_selected_field_on_manifest_and_step_end(tmp_path):
     definition = _for_each_workflow()
     definition["steps"][1]["task"] = {
         "command": "select",
-        "arguments": {"candidates": "gather:shot", "scores": [0.1, 0.9], "rule": "argmax"},
+        "arguments": {
+            "candidates": "gather:shot",
+            "scores": [0.1, 0.9],
+            "rule": "argmax",
+        },
     }
     workflow = _workflow_from(definition, tmp_path)
 

From c07f8669ce8f1148f1a6eeaa68ec66cb43eeac12 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Fri, 18 Sep 2026 16:11:56 -0500
Subject: [PATCH 37/77] Bump transformers floor to 5.17.0

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
---
 pyproject.toml        | 11 ++++++-----
 tests/test_updater.py | 11 +++++++++++
 2 files changed, 17 insertions(+), 5 deletions(-)

diff --git a/pyproject.toml b/pyproject.toml
index e417ca31..d343c13a 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -39,11 +39,12 @@ dependencies = [
     # PyPI release; the newest pipelines may need git HEAD on top, which
     # install.sh layers on (and the web UI's Models page can install)
     "diffusers>=0.40.0",
-    # 5.17.0's TextToAudioPipeline.preprocess calls BatchEncoding.to(dtype=...),
-    # a kwarg BatchEncoding.to() has never accepted in this line - breaks every
-    # generate_speech (Bark) call outright (#169). Drop the exclusion once a
-    # later release either restores the kwarg or stops passing it.
-    "transformers>=5.16.1,!=5.17.0",
+    # VibeVoice first shipped in 5.17.0, and the repo no longer needs to keep
+    # the 5.17.0 exclusion just to protect Bark's default TTS path. Bark's
+    # generate_speech regression is accepted here (#169, with the default TTS
+    # being replaced by the follow-up ticket), so the floor moves to the first
+    # release that includes the VibeVoice support path.
+    "transformers>=5.17.0",
     "accelerate>=1.14.0",
     "peft>=0.20.0",
     "safetensors>=0.8.0",
diff --git a/tests/test_updater.py b/tests/test_updater.py
index c562b076..b62bd3d9 100644
--- a/tests/test_updater.py
+++ b/tests/test_updater.py
@@ -64,6 +64,17 @@ def test_matches_the_pin_in_pyproject_toml(self):
         assert match, "pyproject.toml should pin a diffusers floor"
         assert release_floor() == match.group(1)
 
+    def test_transformers_floor_uses_5170_without_exclusion(self):
+        import re
+        from pathlib import Path
+
+        pyproject = Path(__file__).resolve().parents[1] / "pyproject.toml"
+        text = pyproject.read_text()
+        match = re.search(r'"transformers>=([0-9][0-9.]*[0-9]|[0-9])"', text)
+        assert match, "pyproject.toml should pin a transformers floor"
+        assert match.group(1) == "5.17.0"
+        assert "!=5.17.0" not in text
+
     def test_falls_back_when_pyproject_is_unreadable(self, monkeypatch):
         from dw.server import updater as updater_module
 

From b57431868f2d18028d5e270b8784e751a7678605 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Fri, 18 Sep 2026 18:23:39 -0500
Subject: [PATCH 38/77] fix(speech): #225 - accept chat-templated messages
 input, relax text/messages guard

generate_speech now takes a messages kwarg (a list of chat-role dicts) as an
alternative to text, passed straight through as the pipeline's text_inputs so
a chat-templated model such as VibeVoice can apply its own template. The
text/messages guard in both generate_speech and its task.py handler now
requires exactly one of the two rather than only ever accepting text.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 docs/TASKS.md                   |   3 +-
 dw/tasks/speech_generation.py   |  30 +++++++--
 dw/tasks/task.py                |   9 ++-
 tests/test_speech_generation.py | 107 +++++++++++++++++++++++++++++++-
 4 files changed, 139 insertions(+), 10 deletions(-)

diff --git a/docs/TASKS.md b/docs/TASKS.md
index d117538d..1a1f10a1 100644
--- a/docs/TASKS.md
+++ b/docs/TASKS.md
@@ -1275,7 +1275,8 @@ Speak a line of text with a local text-to-speech model. The result is a waveform
 
 | Argument | Required | Description |
 | -------- | -------- | ----------- |
-| `text` | Yes | The line to speak |
+| `text` | One of `text`/`messages` | The line to speak |
+| `messages` | One of `text`/`messages` | Chat-templated input for a model such as VibeVoice that takes a conversation rather than a bare string — a list of `{"role": ..., "content": ...}` dicts, passed straight through as the pipeline's `text_inputs` so the model's own chat template applies. A model with no chat template configured (Bark and friends) raises when handed this instead of `text` |
 | `model_name` | No | HuggingFace model ID (default: `suno/bark-small`) |
 | `voice_preset` | No | The speaker, for a model with presets — `v2/en_speaker_0` through `v2/en_speaker_9` for Bark. A model with no processor (a single-voice model such as `facebook/mms-tts-eng`) refuses a `voice_preset` with an error rather than ignoring it |
 | `speaker_embedding` | No | A reference audio file (typically an `asset:` reference) whose voice a SpeechT5 model should speak in. Reduced to an x-vector with speechbrain's `spkrec-xvect-voxceleb` and injected into `forward_params` as `speaker_embeddings`. A model that isn't SpeechT5 refuses it the same way a single-voice model refuses `voice_preset` |
diff --git a/dw/tasks/speech_generation.py b/dw/tasks/speech_generation.py
index 5af8e356..3dce73dc 100644
--- a/dw/tasks/speech_generation.py
+++ b/dw/tasks/speech_generation.py
@@ -78,13 +78,20 @@ def load_encoder():
     return embedding.squeeze().unsqueeze(0).to(device=device, dtype=torch.float32)
 
 
-def generate_speech(text, device="cpu", **kwargs):
+def generate_speech(text=None, device="cpu", **kwargs):
     """Speak a line of text with a local text-to-speech model.
 
     Args:
-        text: The line to speak.
+        text: The line to speak. Mutually exclusive with messages - exactly
+            one of the two is required.
         device: Target device ("cuda", "mps", "cpu").
         **kwargs:
+            messages: Chat-templated input for a model such as VibeVoice that
+                takes a conversation rather than a bare string - a list of
+                {"role": ..., "content": ...} dicts. Passed straight through
+                as the pipeline's text_inputs, which applies the model's own
+                chat template; a model with no chat template configured (Bark
+                and friends) raises when handed this instead of text.
             model_name: HuggingFace model ID. Defaults to suno/bark-small.
             voice_preset: The speaker to use, for a model that has presets -
                 "v2/en_speaker_6" and friends for Bark. This is a preprocessing
@@ -108,8 +115,18 @@ def generate_speech(text, device="cpu", **kwargs):
         sample rate the model generated it at.
 
     Raises:
-        ValueError: If the model reports no sample rate for what it generated.
+        ValueError: If the model reports no sample rate for what it generated,
+            or if text/messages are both given or neither is.
     """
+    messages = kwargs.get("messages", None)
+    if (text is None) == (messages is None):
+        raise ValueError(
+            "generate_speech needs exactly one of 'text' or 'messages' - "
+            "a plain line to speak, or chat-templated input for a model "
+            "such as VibeVoice"
+        )
+    text_inputs = messages if messages is not None else text
+
     model_name = kwargs.get("model_name", _DEFAULT_MODEL)
     voice_preset = kwargs.get("voice_preset", None)
     speaker_embedding = kwargs.get("speaker_embedding", None)
@@ -155,9 +172,12 @@ def load_pipe():
             "speaker_embeddings": _speaker_embedding_tensor(speaker_embedding, device),
         }
 
-    logger.info(f"Speaking: {text[:100]}{'...' if len(text) > 100 else ''}")
+    if messages is not None:
+        logger.info(f"Speaking {len(messages)} chat-templated message(s)")
+    else:
+        logger.info(f"Speaking: {text[:100]}{'...' if len(text) > 100 else ''}")
     output = pipe(
-        text,
+        text_inputs,
         preprocess_params={"voice_preset": voice_preset} if voice_preset else {},
         forward_params=forward_params,
         generate_kwargs=kwargs.get("generate_kwargs") or {},
diff --git a/dw/tasks/task.py b/dw/tasks/task.py
index 1a07d1dc..288273f5 100644
--- a/dw/tasks/task.py
+++ b/dw/tasks/task.py
@@ -512,9 +512,12 @@ def _handle_text_generation(task, arguments, previous_pipelines):
 def _handle_speech_generation(task, arguments, previous_pipelines):
     """Speak a line of text with a local text-to-speech model"""
     logger.debug("Generating speech")
-    if "text" not in arguments:
-        raise ValueError("generate_speech needs 'text' - the line to speak")
-    text = arguments.pop("text")
+    if ("text" in arguments) == ("messages" in arguments):
+        raise ValueError(
+            "generate_speech needs exactly one of 'text' (the line to speak) "
+            "or 'messages' (chat-templated input for a model such as VibeVoice)"
+        )
+    text = arguments.pop("text", None)
     from .speech_generation import generate_speech
 
     return generate_speech(text, device=task.device_for(arguments), **arguments)
diff --git a/tests/test_speech_generation.py b/tests/test_speech_generation.py
index 8bfdf100..73ac61bf 100644
--- a/tests/test_speech_generation.py
+++ b/tests/test_speech_generation.py
@@ -219,6 +219,73 @@ def test_speaker_embedding_on_a_non_speecht5_model_is_an_error(
         self.assertIn("facebook/mms-tts-vits", str(raised.exception))
         mock_tensor.assert_not_called()
 
+    @patch("dw.tasks.speech_generation.hf_pipeline")
+    def test_messages_are_passed_as_text_inputs_instead_of_text(self, mock_pipeline):
+        # VibeVoice and other chat-templated models take a conversation rather
+        # than a bare string; transformers applies the model's chat template
+        # when text_inputs is a list of {role, content} dicts
+        pipe = MagicMock(return_value=spoken())
+        mock_pipeline.return_value = pipe
+        messages = [{"role": "user", "content": "Say hello."}]
+
+        generate_speech(device="cpu", messages=messages)
+
+        self.assertEqual(pipe.call_args[0][0], messages)
+
+    @patch("dw.tasks.speech_generation.hf_pipeline")
+    def test_both_text_and_messages_is_an_error(self, mock_pipeline):
+        mock_pipeline.return_value = MagicMock(return_value=spoken())
+
+        with self.assertRaisesRegex(
+            ValueError, "exactly one of 'text' or 'messages'"
+        ):
+            generate_speech(
+                "hi", device="cpu", messages=[{"role": "user", "content": "hi"}]
+            )
+
+    @patch("dw.tasks.speech_generation.hf_pipeline")
+    def test_neither_text_nor_messages_is_an_error(self, mock_pipeline):
+        mock_pipeline.return_value = MagicMock(return_value=spoken())
+
+        with self.assertRaisesRegex(
+            ValueError, "exactly one of 'text' or 'messages'"
+        ):
+            generate_speech(device="cpu")
+
+    @patch("dw.tasks.speech_generation.hf_pipeline")
+    def test_malformed_messages_propagate_the_pipelines_own_error(
+        self, mock_pipeline
+    ):
+        # dw does not itself validate role/content shape - transformers'
+        # Chat wrapper does, and its error is specific enough to act on
+        pipe = MagicMock(
+            side_effect=ValueError(
+                "When passing chat dicts as input, each dict must have a "
+                "'role' and 'content' key."
+            )
+        )
+        mock_pipeline.return_value = pipe
+
+        with self.assertRaisesRegex(ValueError, "'role' and 'content' key"):
+            generate_speech(device="cpu", messages=[{"role": "user"}])
+
+    @patch("dw.tasks.speech_generation.hf_pipeline")
+    def test_messages_on_a_model_with_no_chat_template_propagates_the_error(
+        self, mock_pipeline
+    ):
+        # Bark and other non-chat-templated models have no apply_chat_template
+        # to call; transformers' own failure surfaces rather than dw silently
+        # falling back to treating messages as text
+        pipe = MagicMock(side_effect=ValueError("no chat template is set"))
+        mock_pipeline.return_value = pipe
+
+        with self.assertRaisesRegex(ValueError, "no chat template is set"):
+            generate_speech(
+                device="cpu",
+                model_name=_DEFAULT_MODEL,
+                messages=[{"role": "user", "content": "hi"}],
+            )
+
     @patch("dw.tasks.speech_generation.hf_pipeline")
     def test_vits_speaker_id_passes_through_forward_params_unchanged(
         self, mock_pipeline
@@ -293,5 +360,43 @@ def device_for(self, arguments):
                 return "cpu"
 
         handler = _COMMAND_REGISTRY["generate_speech"]
-        with self.assertRaisesRegex(ValueError, "generate_speech needs 'text'"):
+        with self.assertRaisesRegex(
+            ValueError, "generate_speech needs exactly one of"
+        ):
             handler(FakeTask(), {"voice_preset": "v2/en_speaker_6"}, {})
+
+    def test_generate_speech_with_both_text_and_messages_is_an_error(self):
+        from dw.tasks.task import _COMMAND_REGISTRY
+
+        class FakeTask:
+            def device_for(self, arguments):
+                return "cpu"
+
+        handler = _COMMAND_REGISTRY["generate_speech"]
+        with self.assertRaisesRegex(
+            ValueError, "generate_speech needs exactly one of"
+        ):
+            handler(
+                FakeTask(),
+                {"text": "hi", "messages": [{"role": "user", "content": "hi"}]},
+                {},
+            )
+
+    @patch("dw.tasks.speech_generation.hf_pipeline")
+    def test_messages_dispatched_through_the_handler_reach_the_pipeline(
+        self, mock_pipeline
+    ):
+        from dw.tasks.task import _COMMAND_REGISTRY
+
+        class FakeTask:
+            def device_for(self, arguments):
+                return "cpu"
+
+        pipe = MagicMock(return_value=spoken())
+        mock_pipeline.return_value = pipe
+
+        handler = _COMMAND_REGISTRY["generate_speech"]
+        messages = [{"role": "user", "content": "hi"}]
+        handler(FakeTask(), {"messages": messages}, {})
+
+        self.assertEqual(pipe.call_args[0][0], messages)

From 018eed47bc7243c9c3f9686c0c65cfc41057928e Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Fri, 18 Sep 2026 18:40:50 -0500
Subject: [PATCH 39/77] fix(mcp): #227 - wire audio_bleed_gain_db into the
 three concat_videos templates

concat_videos has taken audio_bleed_gain_db since #199 (closed) to duck the
time-reversed tail bleed audio_bleed_ms rings across a cut, but no template
declared the variable or passed it through - the control was unreachable
except by hand-authoring a workflow. Add the variable (default 0, no change
for existing callers), wire it into each template's concat_videos step, and
name it in one short description sentence: assemble-and-score.json,
minimax/dialogue-short.json, minimax/music-video.json. Same shape as #215.

Trimmed assemble-and-score's and music-video's first description sentence
(the compact-listing summary) to keep the catalog under its token budget
(#101) after the new variable name - same move #215 made.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 workflows/templates/assemble-and-score.json     | 4 +++-
 workflows/templates/minimax/dialogue-short.json | 4 +++-
 workflows/templates/minimax/music-video.json    | 4 +++-
 3 files changed, 9 insertions(+), 3 deletions(-)

diff --git a/workflows/templates/assemble-and-score.json b/workflows/templates/assemble-and-score.json
index d3cc4852..62283c1a 100644
--- a/workflows/templates/assemble-and-score.json
+++ b/workflows/templates/assemble-and-score.json
@@ -1,6 +1,6 @@
 {
     "id": "assemble-and-score",
-    "description": "Cuts existing shots into one scored film, generating nothing in the run. It is the pass you re-run while cutting, when re-generating the footage each time would cost GPU hours to change a fade. The shots go straight into concat_videos as hard cuts - nothing is stabilized or rescaled on the way, so a deliberate camera move survives the edit; they must already share one size and frame rate, and the task refuses a set that does not. 'shots' is a list, so a diptych is two entries and a reel is however many the cut needs. The shots' own recorded sound is carried up to the score's sample rate and mixed underneath it, so the room tone of each world survives the edit instead of being replaced by music. Supply the shots and the score as asset: references - 'shot_1.mp4' and friends, uploaded with upload_asset or promoted from a generated run with keep_output. Shots generated independently also drift in loudness - 10 dB between two shots of one scene is ordinary - and no seam control can hide a level jump, because it is either side of the cut rather than at it; 'match_levels' ('rms' for perceived level, 'peak' for the loudest sample) evens the shots out before they are joined, and left null, as it is by default, a wide spread is warned about in the log rather than passing in silence. 'match_levels_dbfs' sets the level match_levels moves every shot to, below its own default; a shot whose gain to that level would clip is held short of it instead, and the run says so rather than leaving the shots still apart after a match. 'total_frames' is the length of the cut in frames and 'score' is a separate asset with its own length: the score is sliced to 'total_frames' from 'score_start_frame', and a score that does not reach that far is padded to it with digital silence, which leaves the rest of the film unscored under the shots' own sound (the run says so as a 'slice_past_end' warning, but the film itself sounds plausible). A score must therefore be at least as long as the cut; to stretch a short bed to reach, make a longer one with the 'loop_audio' task first and pass that as 'score'.",
+    "description": "Cuts existing shots into one scored film. It is the pass you re-run while cutting, when re-generating the footage each time would cost GPU hours to change a fade. The shots go straight into concat_videos as hard cuts - nothing is stabilized or rescaled on the way, so a deliberate camera move survives the edit; they must already share one size and frame rate, and the task refuses a set that does not. 'shots' is a list, so a diptych is two entries and a reel is however many the cut needs. The shots' own recorded sound is carried up to the score's sample rate and mixed underneath it, so the room tone of each world survives the edit instead of being replaced by music. Supply the shots and the score as asset: references - 'shot_1.mp4' and friends, uploaded with upload_asset or promoted from a generated run with keep_output. Shots generated independently also drift in loudness - 10 dB between two shots of one scene is ordinary - and no seam control can hide a level jump, because it is either side of the cut rather than at it; 'match_levels' ('rms' for perceived level, 'peak' for the loudest sample) evens the shots out before they are joined, and left null, as it is by default, a wide spread is warned about in the log rather than passing in silence. 'match_levels_dbfs' sets the level match_levels moves every shot to, below its own default; a shot whose gain to that level would clip is held short of it instead, and the run says so rather than leaving the shots still apart after a match. 'audio_bleed_gain_db' ducks 'audio_bleed_ms'' full-scale bleed, left at 0 for no change. 'total_frames' is the length of the cut in frames and 'score' is a separate asset with its own length: the score is sliced to 'total_frames' from 'score_start_frame', and a score that does not reach that far is padded to it with digital silence, which leaves the rest of the film unscored under the shots' own sound (the run says so as a 'slice_past_end' warning, but the film itself sounds plausible). A score must therefore be at least as long as the cut; to stretch a short bed to reach, make a longer one with the 'loop_audio' task first and pass that as 'score'.",
     "cost": [
         {
             "device": "cuda",
@@ -22,6 +22,7 @@
         "sample_rate": 44100,
         "fps": 24,
         "audio_bleed_ms": 0,
+        "audio_bleed_gain_db": 0,
         "seam_fade_ms": null,
         "match_levels": null,
         "match_levels_dbfs": null,
@@ -39,6 +40,7 @@
                     "videos": "variable:shots",
                     "fps": "variable:fps",
                     "audio_bleed_ms": "variable:audio_bleed_ms",
+                    "audio_bleed_gain_db": "variable:audio_bleed_gain_db",
                     "seam_fade_ms": "variable:seam_fade_ms",
                     "match_levels": "variable:match_levels",
                     "match_levels_dbfs": "variable:match_levels_dbfs"
diff --git a/workflows/templates/minimax/dialogue-short.json b/workflows/templates/minimax/dialogue-short.json
index bb50b4bb..4bf6156f 100644
--- a/workflows/templates/minimax/dialogue-short.json
+++ b/workflows/templates/minimax/dialogue-short.json
@@ -1,6 +1,6 @@
 {
     "id": "MiniMaxH3SitcomShort",
-    "description": "A digital short built the way television is built: from cuts, not from one long take. Chained generation degrades with length - every segment conditions on the previous segment's output, so artifacts compound and identity drifts. A scene cut resets that completely: each shot here is generated fresh from the same two character portraits, so shot five is exactly as clean as shot one and the scene can run as long as the script does. Two Z-Image steps draw the cast (the second reuses the first's loaded pipeline - identical configurations share one model - and 'release_pipeline' frees it before the video model loads). The shots are one 'for_each' step over the 'shots' list: one entry per shot, carrying its 'name', its 'prompt', its 'references' and its 'num_frames' - the tag entry runs 141 frames where the others run 124, since length is per-shot. The list is an argument, so a six-shot scene is one more entry, not another file, and the members are named for their entries ('shot@react'); the loaded MiniMax-H3 is reused across all of them. Character consistency across cuts comes from referencing the same portraits in every shot; voice consistency comes from repeating each character's voice description verbatim in every prompt, and, when 'character_a_voice' / 'character_b_voice' name a clip ('asset:cast/priya.wav'), from the audio reference each entry lists for whoever speaks in it - an entry's reference says 'variable:character_a_voice', so one variable sets the voice in every shot that character has. Both default to null, and a reference whose file is null is left out of the list, so a run that names no voice generates exactly what it generated before the variables existed. A shot where both speak lists both; if that reads worse than one, name one voice and leave the other null. The variables are named for roles rather than for the cast of this example - 'character_a', the 'react' entry - because the beats are the reusable part and the sketch is not. The soundscape writes the laugh track. A final 'concat_videos' task is the editor, gathering the shots in list order into one episode - hard cuts, no trims, no seams to hide, because nothing was carried between them. Only the picture cuts hard: 'audio_bleed_ms' rings each shot's laugh track on over the silent opening of the next, the way a live audience carries across a cut. It and 'seam_fade_ms' are variables, so a seam is re-tuned with an argument rather than a copy of the workflow; 1800 ms is where a five-shot cut measured best, since a generated shot opens on more silence than it looks. Shots generated independently also drift in loudness - 10 dB between two shots of one scene is ordinary - and no seam control can hide a level jump, because it is either side of the cut rather than at it; 'match_levels' ('rms' for perceived level, 'peak' for the loudest sample) evens the shots out before they are joined, and left null, as it is by default, a wide spread is warned about in the log rather than passing in silence. An episode can be cast from portraits that already exist rather than drawn here: a shot entry's subject reference takes 'from_file' the way its voice references do ('asset:cast/priya.jpg'), so a recurring cast carries across episodes by name instead of being redrawn each time - which is the whole point of a cast. An episode cast entirely from files does not pay for them: the two Z-Image steps save nothing ('save': false - the shots are the only thing that reads them), so once no shot references them the engine drops them from the run and warns that it did, and the minute and two model loads they cost are not spent (#122). Cast some shots from files and not others and they still run, because something still reads them.",
+    "description": "A digital short built the way television is built: from cuts, not from one long take. Chained generation degrades with length - every segment conditions on the previous segment's output, so artifacts compound and identity drifts. A scene cut resets that completely: each shot here is generated fresh from the same two character portraits, so shot five is exactly as clean as shot one and the scene can run as long as the script does. Two Z-Image steps draw the cast (the second reuses the first's loaded pipeline - identical configurations share one model - and 'release_pipeline' frees it before the video model loads). The shots are one 'for_each' step over the 'shots' list: one entry per shot, carrying its 'name', its 'prompt', its 'references' and its 'num_frames' - the tag entry runs 141 frames where the others run 124, since length is per-shot. The list is an argument, so a six-shot scene is one more entry, not another file, and the members are named for their entries ('shot@react'); the loaded MiniMax-H3 is reused across all of them. Character consistency across cuts comes from referencing the same portraits in every shot; voice consistency comes from repeating each character's voice description verbatim in every prompt, and, when 'character_a_voice' / 'character_b_voice' name a clip ('asset:cast/priya.wav'), from the audio reference each entry lists for whoever speaks in it - an entry's reference says 'variable:character_a_voice', so one variable sets the voice in every shot that character has. Both default to null, and a reference whose file is null is left out of the list, so a run that names no voice generates exactly what it generated before the variables existed. A shot where both speak lists both; if that reads worse than one, name one voice and leave the other null. The variables are named for roles rather than for the cast of this example - 'character_a', the 'react' entry - because the beats are the reusable part and the sketch is not. The soundscape writes the laugh track. A final 'concat_videos' task is the editor, gathering the shots in list order into one episode - hard cuts, no trims, no seams to hide, because nothing was carried between them. Only the picture cuts hard: 'audio_bleed_ms' rings each shot's laugh track on over the silent opening of the next, the way a live audience carries across a cut. It and 'seam_fade_ms' are variables, so a seam is re-tuned with an argument rather than a copy of the workflow; 1800 ms is where a five-shot cut measured best, since a generated shot opens on more silence than it looks; 'audio_bleed_gain_db' ducks it, left at 0 for no change. Shots generated independently also drift in loudness - 10 dB between two shots of one scene is ordinary - and no seam control can hide a level jump, because it is either side of the cut rather than at it; 'match_levels' ('rms' for perceived level, 'peak' for the loudest sample) evens the shots out before they are joined, and left null, as it is by default, a wide spread is warned about in the log rather than passing in silence. An episode can be cast from portraits that already exist rather than drawn here: a shot entry's subject reference takes 'from_file' the way its voice references do ('asset:cast/priya.jpg'), so a recurring cast carries across episodes by name instead of being redrawn each time - which is the whole point of a cast. An episode cast entirely from files does not pay for them: the two Z-Image steps save nothing ('save': false - the shots are the only thing that reads them), so once no shot references them the engine drops them from the run and warns that it did, and the minute and two model loads they cost are not spent (#122). Cast some shots from files and not others and they still run, because something still reads them.",
     "summary": "A multi-shot dialogue short: Z-Image draws the cast, each shot is generated fresh from the same portraits, then cut.",
     "cost": [
         {
@@ -117,6 +117,7 @@
         "voice_reference_type": "diffusers.modular_pipelines.minimax_h3.MiniMaxH3AudioReference",
         "subject_reference_type": "diffusers.modular_pipelines.minimax_h3.MiniMaxH3ImageReference",
         "audio_bleed_ms": 1800,
+        "audio_bleed_gain_db": 0,
         "seam_fade_ms": null,
         "match_levels": null,
         "width": 960,
@@ -343,6 +344,7 @@
                     "videos": "gather:shot",
                     "trim_frames": 0,
                     "audio_bleed_ms": "variable:audio_bleed_ms",
+                    "audio_bleed_gain_db": "variable:audio_bleed_gain_db",
                     "fps": 24,
                     "seam_fade_ms": "variable:seam_fade_ms",
                     "match_levels": "variable:match_levels"
diff --git a/workflows/templates/minimax/music-video.json b/workflows/templates/minimax/music-video.json
index 0df9450a..7e41634f 100644
--- a/workflows/templates/minimax/music-video.json
+++ b/workflows/templates/minimax/music-video.json
@@ -1,6 +1,6 @@
 {
     "id": "MiniMaxH3MusicVideo",
-    "description": "A music video built from cuts, sung to a soundtrack that never touches a chain. The long-take way to film a song - one chained generation lip-synced end to end - degrades with every carried segment and can let the sync slip. This builds the video the way music television does instead: MiniMax-Music3 writes the song, one 'slice_audio' step per entry of 'shots' cuts it into frame-exact pieces (124 frames at 24 fps each, from each entry's 'start_frame'), and one shot per entry is generated fresh from the same Z-Image portrait plus its own slice, lip-synced to just those five seconds. 'shots' is a list, so the cut is an argument: add an entry and there is one more slice and one more shot, named for it ('slice@closeup', 'shot@closeup'), and the loaded model is reused across every shot - identical pipeline definitions share one model. No shot conditions on another shot's output, so the last cut is as clean as the first. 'concat_videos' gathers the shots in list order, and because each one covered exactly its slice's frames, the edit is sample-accurate by construction: 'pair_audio' drops the original, unbroken song over the whole cut and the mouths line up in every shot. The soundtrack follows the list too - 'pair_audio' is given the whole song with 'fit': 'video', so it is cut to exactly the frames the edit came to, whatever length 'shots' is; a list long enough to outrun 'audio_duration' seconds of song is padded with silence and warned about rather than passing quietly. The generation models pass through one at a time - each is released before the next loads - so the workflow peaks no higher than its largest single model. Shots generated independently also drift in loudness - 10 dB between two shots of one scene is ordinary - and no seam control can hide a level jump, because it is either side of the cut rather than at it; 'match_levels' ('rms' for perceived level, 'peak' for the loudest sample) evens the shots out before they are joined, and left null, as it is by default, a wide spread is warned about in the log rather than passing in silence. The singer's picture is one argument: 'singer_reference' is the <Picture 1> reference every shot conditions on, and it names 'draw_singer' by default. A standing cast member is used instead by passing a reference that reads a file - {\"reference_type\": \"variable:image_reference_type\", \"from_file\": \"asset:cast/priya.jpg\"} - which is the same shape 'dialogue-short' takes per shot entry. 'draw_singer' then goes unreferenced and is elided before the run, so the portrait costs nothing when one was supplied; it saves nothing of its own either way, being a conditioning image rather than a deliverable, and a portrait worth keeping is kept from the run that drew it. The soundtrack is peak-normalized to -3 dBFS on its way into the mux, and only there: Music 3 lands at or over full scale, and the mp4's second lossy encode had been pushing the finished video past it (#158, #159). -3 rather than the -1 an audio deliverable takes because the AAC encode in the mux overshoots by around 1.9 dB on this material where an mp3 overshoots by a tenth of one, so -1 was not enough headroom and the finished mp4 still decoded at +0.94 dBFS (#161). The slices that condition the shots are the song at its own level, untouched, so the picture is what it was.",
+    "description": "A music video cut to a soundtrack that never touches a chain. The long-take way to film a song - one chained generation lip-synced end to end - degrades with every carried segment and can let the sync slip. This builds the video the way music television does instead: MiniMax-Music3 writes the song, one 'slice_audio' step per entry of 'shots' cuts it into frame-exact pieces (124 frames at 24 fps each, from each entry's 'start_frame'), and one shot per entry is generated fresh from the same Z-Image portrait plus its own slice, lip-synced to just those five seconds. 'shots' is a list, so the cut is an argument: add an entry and there is one more slice and one more shot, named for it ('slice@closeup', 'shot@closeup'), and the loaded model is reused across every shot - identical pipeline definitions share one model. No shot conditions on another shot's output, so the last cut is as clean as the first. 'concat_videos' gathers the shots in list order, and because each one covered exactly its slice's frames, the edit is sample-accurate by construction: 'pair_audio' drops the original, unbroken song over the whole cut and the mouths line up in every shot. The soundtrack follows the list too - 'pair_audio' is given the whole song with 'fit': 'video', so it is cut to exactly the frames the edit came to, whatever length 'shots' is; a list long enough to outrun 'audio_duration' seconds of song is padded with silence and warned about rather than passing quietly. The generation models pass through one at a time - each is released before the next loads - so the workflow peaks no higher than its largest single model. Shots generated independently also drift in loudness - 10 dB between two shots of one scene is ordinary - and no seam control can hide a level jump, because it is either side of the cut rather than at it; 'match_levels' ('rms' for perceived level, 'peak' for the loudest sample) evens the shots out before they are joined, and left null, as it is by default, a wide spread is warned about in the log rather than passing in silence. 'audio_bleed_gain_db' ducks 'audio_bleed_ms'' full-scale bleed, left at 0 for no change. The singer's picture is one argument: 'singer_reference' is the <Picture 1> reference every shot conditions on, and it names 'draw_singer' by default. A standing cast member is used instead by passing a reference that reads a file - {\"reference_type\": \"variable:image_reference_type\", \"from_file\": \"asset:cast/priya.jpg\"} - which is the same shape 'dialogue-short' takes per shot entry. 'draw_singer' then goes unreferenced and is elided before the run, so the portrait costs nothing when one was supplied; it saves nothing of its own either way, being a conditioning image rather than a deliverable, and a portrait worth keeping is kept from the run that drew it. The soundtrack is peak-normalized to -3 dBFS on its way into the mux, and only there: Music 3 lands at or over full scale, and the mp4's second lossy encode had been pushing the finished video past it (#158, #159). -3 rather than the -1 an audio deliverable takes because the AAC encode in the mux overshoots by around 1.9 dB on this material where an mp3 overshoots by a tenth of one, so -1 was not enough headroom and the finished mp4 still decoded at +0.94 dBFS (#161). The slices that condition the shots are the song at its own level, untouched, so the picture is what it was.",
     "cost": [
         {
             "device": "cuda",
@@ -54,6 +54,7 @@
         "num_frames": 124,
         "fps": 24,
         "audio_bleed_ms": 0,
+        "audio_bleed_gain_db": 0,
         "seam_fade_ms": null,
         "match_levels": null,
         "width": 960,
@@ -304,6 +305,7 @@
                     "trim_frames": 0,
                     "fps": "variable:fps",
                     "audio_bleed_ms": "variable:audio_bleed_ms",
+                    "audio_bleed_gain_db": "variable:audio_bleed_gain_db",
                     "seam_fade_ms": "variable:seam_fade_ms",
                     "match_levels": "variable:match_levels"
                 }

From cd2f6e2b009f98cc2158e8254fe703ebec3836ae Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Fri, 18 Sep 2026 19:06:21 -0500
Subject: [PATCH 40/77] fix(deps): #232 - revert transformers floor to
 >=5.16.1,!=5.17.0

5.17.0's TextToAudioPipeline.preprocess calls BatchEncoding.to(dtype=...),
a kwarg it has never accepted - breaks generate_speech for every model
through that pipeline class (SpeechT5, Bark, VITS), not just Bark as
#224's bump assumed. The bump existed only to unblock VibeVoice, which
can't load any checkpoint under any transformers version right now
(huggingface/transformers#42758, unrelated to this bug). Reverts c07f866,
restoring 84dae64's #169 exclusion, and reverts the test c07f866 added
that pinned the broken floor.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 pyproject.toml        | 14 ++++++++------
 tests/test_updater.py |  8 +++-----
 2 files changed, 11 insertions(+), 11 deletions(-)

diff --git a/pyproject.toml b/pyproject.toml
index d343c13a..90000e75 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -39,12 +39,14 @@ dependencies = [
     # PyPI release; the newest pipelines may need git HEAD on top, which
     # install.sh layers on (and the web UI's Models page can install)
     "diffusers>=0.40.0",
-    # VibeVoice first shipped in 5.17.0, and the repo no longer needs to keep
-    # the 5.17.0 exclusion just to protect Bark's default TTS path. Bark's
-    # generate_speech regression is accepted here (#169, with the default TTS
-    # being replaced by the follow-up ticket), so the floor moves to the first
-    # release that includes the VibeVoice support path.
-    "transformers>=5.17.0",
+    # 5.17.0's TextToAudioPipeline.preprocess calls BatchEncoding.to(dtype=...),
+    # a kwarg BatchEncoding.to() has never accepted in this line - breaks every
+    # generate_speech call outright (#169, #232 - not Bark-only, every TTS model
+    # through this pipeline class). Drop the exclusion once a later release
+    # either restores the kwarg or stops passing it - check both
+    # huggingface/transformers#42758 (VibeVoice config, the reason for the
+    # 5.17.0 bump in the first place) and this preprocess bug before re-bumping.
+    "transformers>=5.16.1,!=5.17.0",
     "accelerate>=1.14.0",
     "peft>=0.20.0",
     "safetensors>=0.8.0",
diff --git a/tests/test_updater.py b/tests/test_updater.py
index b62bd3d9..e3acd774 100644
--- a/tests/test_updater.py
+++ b/tests/test_updater.py
@@ -64,16 +64,14 @@ def test_matches_the_pin_in_pyproject_toml(self):
         assert match, "pyproject.toml should pin a diffusers floor"
         assert release_floor() == match.group(1)
 
-    def test_transformers_floor_uses_5170_without_exclusion(self):
+    def test_transformers_floor_excludes_5170(self):
         import re
         from pathlib import Path
 
         pyproject = Path(__file__).resolve().parents[1] / "pyproject.toml"
         text = pyproject.read_text()
-        match = re.search(r'"transformers>=([0-9][0-9.]*[0-9]|[0-9])"', text)
-        assert match, "pyproject.toml should pin a transformers floor"
-        assert match.group(1) == "5.17.0"
-        assert "!=5.17.0" not in text
+        match = re.search(r'"transformers>=([0-9][0-9.]*[0-9]|[0-9]),!=5\.17\.0"', text)
+        assert match, "pyproject.toml should exclude the broken 5.17.0 release (#232)"
 
     def test_falls_back_when_pyproject_is_unreadable(self, monkeypatch):
         from dw.server import updater as updater_module

From 87c45fdf858ebf98d0bb3f185c699b4a213df5c2 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Fri, 18 Sep 2026 19:21:05 -0500
Subject: [PATCH 41/77] fix(mcp): #226/#233 - VITS default for generate-speech
 template, messages shape guard

#226: templates/generate-speech.json now defaults model_name to
facebook/mms-tts-eng instead of suno/bark-small. VITS refuses
voice_preset, so that variable/argument and the description's Bark
sentence are gone too. docs/TASKS.md now distinguishes the task's own
default (still Bark) from the template's (VITS). VibeVoice remains a
dead end (huggingface/transformers#42758).

#233: generate_speech now validates messages is a non-empty list of
{role, content} dicts (both strings) before any model load, raising a
ValueError naming the argument - previously a bare string silently
aliased text-shaped input and a wrong-keyed dict fell through to an
opaque tokenizer error.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 docs/TASKS.md                            |  2 +-
 dw/tasks/speech_generation.py            | 17 +++++++++
 tests/test_speech_generation.py          | 48 ++++++++++++++++++++----
 workflows/templates/generate-speech.json |  6 +--
 4 files changed, 61 insertions(+), 12 deletions(-)

diff --git a/docs/TASKS.md b/docs/TASKS.md
index 1a1f10a1..314ceee4 100644
--- a/docs/TASKS.md
+++ b/docs/TASKS.md
@@ -1283,7 +1283,7 @@ Speak a line of text with a local text-to-speech model. The result is a waveform
 | `forward_params` | No | Passed to the model's forward/generate call |
 | `generate_kwargs` | No | Ad-hoc generation settings for a generative model — `temperature`, `do_sample` |
 
-The default is Bark because its voice presets give distinct speakers, which is what two characters in a scene need; `facebook/mms-tts-eng` is a quarter the size and a good override where one voice will do. `voice_preset` is a preprocessing argument — it selects the speaker before generation rather than parameterizing it — so naming it here is what makes it reach the processor. Passed through `forward_params` it would be dropped and every character would sound the same.
+The command's own default is Bark because its voice presets give distinct speakers, which is what two characters in a scene need; `facebook/mms-tts-eng` is a quarter the size and a good override where one voice will do. [`generate-speech.json`](../workflows/templates/generate-speech.json) ships with `facebook/mms-tts-eng` as its own default instead, since a template is usually a single voice. `voice_preset` is a preprocessing argument — it selects the speaker before generation rather than parameterizing it — so naming it here is what makes it reach the processor. Passed through `forward_params` it would be dropped and every character would sound the same.
 
 `speaker_embedding` is the same kind of preprocessing argument for a SpeechT5 model (`microsoft/speecht5_tts`), which conditions its voice on an x-vector rather than a preset name. A VITS model's speaker is different again — a plain `speaker_id` int, passed through `forward_params` unchanged, since it was never a preprocessing argument and needs no argument of its own here.
 
diff --git a/dw/tasks/speech_generation.py b/dw/tasks/speech_generation.py
index 3dce73dc..ee99f7cb 100644
--- a/dw/tasks/speech_generation.py
+++ b/dw/tasks/speech_generation.py
@@ -125,6 +125,23 @@ def generate_speech(text=None, device="cpu", **kwargs):
             "a plain line to speak, or chat-templated input for a model "
             "such as VibeVoice"
         )
+    if messages is not None:
+        valid = isinstance(messages, list) and len(messages) > 0
+        if valid:
+            for message in messages:
+                if (
+                    not isinstance(message, dict)
+                    or not isinstance(message.get("role"), str)
+                    or not isinstance(message.get("content"), str)
+                ):
+                    valid = False
+                    break
+        if not valid:
+            raise ValueError(
+                "generate_speech's 'messages' needs a non-empty list of "
+                "{'role': ..., 'content': ...} dicts, both strings - a bare "
+                "string or a wrong-keyed dict is not chat-templated input"
+            )
     text_inputs = messages if messages is not None else text
 
     model_name = kwargs.get("model_name", _DEFAULT_MODEL)
diff --git a/tests/test_speech_generation.py b/tests/test_speech_generation.py
index 73ac61bf..bdadb6a2 100644
--- a/tests/test_speech_generation.py
+++ b/tests/test_speech_generation.py
@@ -253,21 +253,55 @@ def test_neither_text_nor_messages_is_an_error(self, mock_pipeline):
             generate_speech(device="cpu")
 
     @patch("dw.tasks.speech_generation.hf_pipeline")
-    def test_malformed_messages_propagate_the_pipelines_own_error(
+    def test_a_bare_string_messages_is_an_error(self, mock_pipeline):
+        # A bare string is itself a valid iterable of characters and would
+        # otherwise sail through the exactly-one check as "messages given"
+        mock_pipeline.return_value = MagicMock(return_value=spoken())
+
+        with self.assertRaisesRegex(ValueError, "non-empty list"):
+            generate_speech(device="cpu", messages="hello")
+
+    @patch("dw.tasks.speech_generation.hf_pipeline")
+    def test_an_empty_messages_list_is_an_error(self, mock_pipeline):
+        mock_pipeline.return_value = MagicMock(return_value=spoken())
+
+        with self.assertRaisesRegex(ValueError, "non-empty list"):
+            generate_speech(device="cpu", messages=[])
+
+    @patch("dw.tasks.speech_generation.hf_pipeline")
+    def test_a_wrong_keyed_message_dict_is_an_error(self, mock_pipeline):
+        # Caught here rather than left to the tokenizer, whose error for this
+        # shape names neither 'messages' nor what it expected instead
+        mock_pipeline.return_value = MagicMock(return_value=spoken())
+
+        with self.assertRaisesRegex(ValueError, "non-empty list"):
+            generate_speech(device="cpu", messages=[{"speaker": "user", "text": "hi"}])
+
+    @patch("dw.tasks.speech_generation.hf_pipeline")
+    def test_a_non_dict_message_item_is_an_error(self, mock_pipeline):
+        mock_pipeline.return_value = MagicMock(return_value=spoken())
+
+        with self.assertRaisesRegex(ValueError, "non-empty list"):
+            generate_speech(device="cpu", messages=["hello"])
+
+    @patch("dw.tasks.speech_generation.hf_pipeline")
+    def test_messages_that_pass_the_shape_guard_still_reach_the_pipeline(
         self, mock_pipeline
     ):
-        # dw does not itself validate role/content shape - transformers'
-        # Chat wrapper does, and its error is specific enough to act on
+        # #233 only guards shape (role/content present and strings) - a role
+        # value the guard cannot judge (not a recognised chat role) is left
+        # to transformers' own Chat wrapper, and its error surfaces unchanged
         pipe = MagicMock(
             side_effect=ValueError(
-                "When passing chat dicts as input, each dict must have a "
-                "'role' and 'content' key."
+                "Chat role 'narrator' is not one of 'system', 'user', 'assistant'"
             )
         )
         mock_pipeline.return_value = pipe
 
-        with self.assertRaisesRegex(ValueError, "'role' and 'content' key"):
-            generate_speech(device="cpu", messages=[{"role": "user"}])
+        with self.assertRaisesRegex(ValueError, "Chat role 'narrator'"):
+            generate_speech(
+                device="cpu", messages=[{"role": "narrator", "content": "hi"}]
+            )
 
     @patch("dw.tasks.speech_generation.hf_pipeline")
     def test_messages_on_a_model_with_no_chat_template_propagates_the_error(
diff --git a/workflows/templates/generate-speech.json b/workflows/templates/generate-speech.json
index bf5a1c30..9f78e386 100644
--- a/workflows/templates/generate-speech.json
+++ b/workflows/templates/generate-speech.json
@@ -1,10 +1,9 @@
 {
   "id": "GenerateSpeech",
-  "description": "Speaks a line of text with a local text-to-speech model and saves it as a wav. The result declares no 'sample_rate': a generated track carries the rate its model produced it at, so saying nothing is what saves it correctly. Bark's 'voice_preset' selects the speaker - give two characters two presets and they sound like two people.",
+  "description": "Speaks a line of text with a local text-to-speech model and saves it as a wav. The result declares no 'sample_rate': a generated track carries the rate its model produced it at, so saying nothing is what saves it correctly.",
   "variables": {
     "text": "Somebody finished the pistachio and nobody is saying anything.",
-    "voice_preset": "v2/en_speaker_6",
-    "model_name": "suno/bark-small"
+    "model_name": "facebook/mms-tts-eng"
   },
   "steps": [
     {
@@ -13,7 +12,6 @@
         "command": "generate_speech",
         "arguments": {
           "text": "variable:text",
-          "voice_preset": "variable:voice_preset",
           "model_name": "variable:model_name"
         }
       },

From 6dd35daf08b34e4d7aa091ad5f2641f78ad901d7 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Fri, 18 Sep 2026 19:52:34 -0500
Subject: [PATCH 42/77] fix(mcp): #223/#235 - speaker_embedding dtype fix,
 final subfolder markup

#223: _speaker_embedding_tensor hard-coded dtype=torch.float32, but the
pipe loads at preferred_task_dtype(device) (fp16 on CUDA); the x-vector
is concatenated with the pipe's hidden states inside SpeechT5's decoder
prenet, so a fp16 pipe threw "mat1 and mat2 must have the same dtype,
but got Float and Half". Thread the pipe's own dtype through instead.
Also documents that speaker_embedding is required, not optional, for a
SpeechT5 model.

#235: assemble-and-score.json and dissolve-between-shots.json each have
exactly one saving step, so tests/test_template_subfolders.py's "two or
more saving steps" rule never caught them missing a subfolder marking.
Mark their film step "final", matching every other template.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 dw/tasks/speech_generation.py                 | 21 +++++++++++++------
 tests/test_speech_generation.py               | 10 ++++++---
 workflows/templates/assemble-and-score.json   |  3 ++-
 .../templates/dissolve-between-shots.json     |  3 ++-
 4 files changed, 26 insertions(+), 11 deletions(-)

diff --git a/dw/tasks/speech_generation.py b/dw/tasks/speech_generation.py
index ee99f7cb..276b1ef9 100644
--- a/dw/tasks/speech_generation.py
+++ b/dw/tasks/speech_generation.py
@@ -44,7 +44,7 @@
 _SPEAKER_ENCODER_SAMPLE_RATE = 16000
 
 
-def _speaker_embedding_tensor(location, device):
+def _speaker_embedding_tensor(location, device, dtype):
     """The x-vector speechbrain's spkrec-xvect-voxceleb extracts from a
     reference audio file - what SpeechT5 conditions its voice on.
 
@@ -52,6 +52,10 @@ def _speaker_embedding_tensor(location, device):
         location: Path to a reference audio file (an 'asset:' reference has
             already resolved to this by the time a task sees it).
         device: Where to run the encoder.
+        dtype: The speech pipeline's own dtype - the embedding is concatenated
+            with the pipe's hidden states inside the decoder prenet, so it must
+            match the pipe's precision (fp16 on CUDA) or the linear layer there
+            refuses a Float x Half product.
     """
     from speechbrain.inference.speaker import EncoderClassifier
 
@@ -75,7 +79,7 @@ def load_encoder():
     # SpeechT5's generate() wants (batch, 512); the encoder's raw output is
     # (1, 1, 512), so squeeze collapses it back to (512,) before restoring
     # the batch dimension the model actually requires
-    return embedding.squeeze().unsqueeze(0).to(device=device, dtype=torch.float32)
+    return embedding.squeeze().unsqueeze(0).to(device=device, dtype=dtype)
 
 
 def generate_speech(text=None, device="cpu", **kwargs):
@@ -103,9 +107,12 @@ def generate_speech(text=None, device="cpu", **kwargs):
                 in. Reduced to an x-vector with speechbrain's
                 spkrec-xvect-voxceleb and injected into forward_params as
                 'speaker_embeddings' - SpeechT5 is the only pipeline here that
-                conditions on one. A VITS model's speaker instead takes a plain
-                'speaker_id' int, which already reaches the model unchanged
-                through forward_params and needs no argument of its own.
+                conditions on one, and it is not optional for SpeechT5: the
+                model refuses to generate without a speaker embedding, so this
+                is required whenever model_name is a SpeechT5 checkpoint. A
+                VITS model's speaker instead takes a plain 'speaker_id' int,
+                which already reaches the model unchanged through
+                forward_params and needs no argument of its own.
             forward_params: Passed to the model's forward/generate call.
             generate_kwargs: Ad-hoc generation settings for a generative model -
                 temperature, do_sample and so on.
@@ -186,7 +193,9 @@ def load_pipe():
             )
         forward_params = {
             **forward_params,
-            "speaker_embeddings": _speaker_embedding_tensor(speaker_embedding, device),
+            "speaker_embeddings": _speaker_embedding_tensor(
+                speaker_embedding, device, dtype
+            ),
         }
 
     if messages is not None:
diff --git a/tests/test_speech_generation.py b/tests/test_speech_generation.py
index bdadb6a2..48c3510e 100644
--- a/tests/test_speech_generation.py
+++ b/tests/test_speech_generation.py
@@ -167,7 +167,9 @@ def test_speaker_embedding_reaches_forward_params_for_speecht5(
             speaker_embedding="asset:voices/iris.wav",
         )
 
-        mock_tensor.assert_called_once_with("asset:voices/iris.wav", "cpu")
+        mock_tensor.assert_called_once_with(
+            "asset:voices/iris.wav", "cpu", torch.float32
+        )
         self.assertEqual(
             pipe.call_args[1]["forward_params"],
             {"speaker_embeddings": "the-x-vector"},
@@ -375,10 +377,12 @@ def test_output_shape_is_batch_of_one_by_512(
                 "speechbrain.inference.speaker": fake_module,
             },
         ):
-            embedding = _speaker_embedding_tensor("asset:voices/iris.wav", "cpu")
+            embedding = _speaker_embedding_tensor(
+                "asset:voices/iris.wav", "cpu", torch.float16
+            )
 
         self.assertEqual(tuple(embedding.shape), (1, 512))
-        self.assertEqual(embedding.dtype, torch.float32)
+        self.assertEqual(embedding.dtype, torch.float16)
 
 
 class TestHandleSpeechGeneration(unittest.TestCase):
diff --git a/workflows/templates/assemble-and-score.json b/workflows/templates/assemble-and-score.json
index 62283c1a..c57a3ab8 100644
--- a/workflows/templates/assemble-and-score.json
+++ b/workflows/templates/assemble-and-score.json
@@ -119,7 +119,8 @@
             },
             "result": {
                 "content_type": "video/mp4",
-                "fps": 24
+                "fps": 24,
+                "subfolder": "final"
             }
         }
     ]
diff --git a/workflows/templates/dissolve-between-shots.json b/workflows/templates/dissolve-between-shots.json
index eb2a099b..bda69701 100644
--- a/workflows/templates/dissolve-between-shots.json
+++ b/workflows/templates/dissolve-between-shots.json
@@ -115,7 +115,8 @@
             },
             "result": {
                 "content_type": "video/mp4",
-                "fps": 24
+                "fps": 24,
+                "subfolder": "final"
             }
         }
     ]

From e5eed6dd6b5b1fc7461832dfcb6febbcf46e636c Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sat, 19 Sep 2026 08:38:44 -0500
Subject: [PATCH 43/77] format

---
 tests/test_speech_generation.py | 16 ++++------------
 1 file changed, 4 insertions(+), 12 deletions(-)

diff --git a/tests/test_speech_generation.py b/tests/test_speech_generation.py
index 48c3510e..605ebfb1 100644
--- a/tests/test_speech_generation.py
+++ b/tests/test_speech_generation.py
@@ -238,9 +238,7 @@ def test_messages_are_passed_as_text_inputs_instead_of_text(self, mock_pipeline)
     def test_both_text_and_messages_is_an_error(self, mock_pipeline):
         mock_pipeline.return_value = MagicMock(return_value=spoken())
 
-        with self.assertRaisesRegex(
-            ValueError, "exactly one of 'text' or 'messages'"
-        ):
+        with self.assertRaisesRegex(ValueError, "exactly one of 'text' or 'messages'"):
             generate_speech(
                 "hi", device="cpu", messages=[{"role": "user", "content": "hi"}]
             )
@@ -249,9 +247,7 @@ def test_both_text_and_messages_is_an_error(self, mock_pipeline):
     def test_neither_text_nor_messages_is_an_error(self, mock_pipeline):
         mock_pipeline.return_value = MagicMock(return_value=spoken())
 
-        with self.assertRaisesRegex(
-            ValueError, "exactly one of 'text' or 'messages'"
-        ):
+        with self.assertRaisesRegex(ValueError, "exactly one of 'text' or 'messages'"):
             generate_speech(device="cpu")
 
     @patch("dw.tasks.speech_generation.hf_pipeline")
@@ -398,9 +394,7 @@ def device_for(self, arguments):
                 return "cpu"
 
         handler = _COMMAND_REGISTRY["generate_speech"]
-        with self.assertRaisesRegex(
-            ValueError, "generate_speech needs exactly one of"
-        ):
+        with self.assertRaisesRegex(ValueError, "generate_speech needs exactly one of"):
             handler(FakeTask(), {"voice_preset": "v2/en_speaker_6"}, {})
 
     def test_generate_speech_with_both_text_and_messages_is_an_error(self):
@@ -411,9 +405,7 @@ def device_for(self, arguments):
                 return "cpu"
 
         handler = _COMMAND_REGISTRY["generate_speech"]
-        with self.assertRaisesRegex(
-            ValueError, "generate_speech needs exactly one of"
-        ):
+        with self.assertRaisesRegex(ValueError, "generate_speech needs exactly one of"):
             handler(
                 FakeTask(),
                 {"text": "hi", "messages": [{"role": "user", "content": "hi"}]},

From 1ec68b4525b6d0a71c205cf73a00980d8bf13f4e Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sat, 19 Sep 2026 11:02:05 -0500
Subject: [PATCH 44/77] feat: add proposal for `script-to-video` skill to
 enhance workflow composition

---
 docs/proposals/script-to-video-agent-skill.md | 160 ++++++++++++++++++
 1 file changed, 160 insertions(+)
 create mode 100644 docs/proposals/script-to-video-agent-skill.md

diff --git a/docs/proposals/script-to-video-agent-skill.md b/docs/proposals/script-to-video-agent-skill.md
new file mode 100644
index 00000000..e8c9686b
--- /dev/null
+++ b/docs/proposals/script-to-video-agent-skill.md
@@ -0,0 +1,160 @@
+# Proposal: a `script-to-video` skill that composes what already exists
+
+Status: proposed, 2026-09-19. Raised by Don asking whether "give the agent a
+script, have it turn that into a video end to end" is already possible with
+`dw`. Written from that conversation, not from a filed issue. No code
+changes yet.
+
+## The problem
+
+The request, as posed, was broader than this repo should take on: hand an
+agent a script and a high-level goal ("turn this into a video") and have it
+autonomously pick models, build the workflow, generate, diagnose failures,
+retune settings, and iterate - unsupervised, end to end, including deciding
+*how to make a slow model faster*.
+
+Most of that loop already exists in this repo, spread across the MCP surface
+and the per-family composition skills. The piece that does not exist is the
+first one: nothing turns a script into the `shots` list the templates
+expect. Everything downstream of that list is already built. This proposal
+scopes a new skill for exactly that gap, and explicitly declines the
+open-ended "profile and auto-optimize an arbitrary model" ambition - not
+because it is uninteresting, but because it is a different, much harder
+problem that does not compose with the rest of this design.
+
+## What already exists (no change proposed here)
+
+| Stage | Mechanism | Where |
+|---|---|---|
+| Pick a template for a shot's shape | `list_workflows(shape=...)`, the per-family skills | `dw:minimax-h3`, `dw:ltx-2-5`, `dw:minimax-music3` |
+| Write a conformant prompt for the chosen family | family prompt-writing skills | `h3-prompt-writing`, `music-caption-rewriter` |
+| Cast/voice continuity across shots and episodes | the fixed-asset-reference procedure | `dw:series-episodes` (step 0 + the five-beat cut) |
+| Cost estimate before spending | `plan.estimate` (`basis`, `runs`) on `validate_workflow` | `dw/plan.py`, `POST /api/validate` |
+| Spend gate | `acknowledged_cost` on `run_workflow`/`rerun_job` | CLAUDE.md, *Acknowledged-cost* |
+| Run, inspect, diagnose | `run_workflow` → `wait_for_job` → `get_job_events`/`get_gallery_metadata` | existing MCP tools |
+| Structural warnings an agent can act on | `audio_no_headroom`, `audio_clipped`, elision diagnostics | `dw/result.py`, `dw/elision.py` |
+| Retry with a fresh seed | `rerun_job(new_seed=True)` | step cache, CLAUDE.md |
+
+None of this needs new engine code. The gap is upstream of all of it: a
+script is prose, and every mechanism above starts from a `shots` list that
+already has names, per-shot prompts in the target family's structured form,
+and reference wiring.
+
+## Design: the new piece is a skill, not an engine feature
+
+### `script-to-video` (new plugin skill, `plugins/dw/skills/`)
+
+Composes, in order:
+
+1. **Read the script and the server.** `get_server_info` for device/workspace
+   the way every other skill starts. The script itself is whatever the user
+   pastes or attaches - this skill does not parse screenplay formats, it
+   reads prose and dialogue the way a person would.
+
+2. **Decompose into a shot list, not shot count.** The user's framing ("split
+   into N lines/scenes") is close but the unit that matters is *shots*, not
+   lines: a scene may be one shot or several depending on cuts, and H3's
+   sweet spot is 4-6 second shots (CLAUDE.md's `17*n+5` frame grid). The
+   skill's job is turning script beats into named shot entries - `name`,
+   which character(s) appear, what happens, roughly how long - deferring the
+   family-specific prompt structure to step 3. This is genuinely new
+   reasoning work with no existing mechanism to lean on; it is also the one
+   step where "an LLM is good at this" is actually true, unlike model
+   auto-tuning.
+
+3. **Cast the recurring characters once, per `dw:series-episodes` step 0.**
+   Every character who appears in more than one shot gets a portrait (and
+   voice clip, if they speak) drawn once and `keep_output`'d as
+   `asset:cast/<name>`, before any shot generates. A script with one
+   continuous scene and no recurring cast can skip this and let the family
+   template draw its own portraits - the skill states the rule (more than one
+   shot needs a fixed asset) rather than always drawing cast up front.
+
+4. **For each shot, pick the shape and write the prompt.** Silent action or
+   establishing shots go through a `dw:ltx-2-5` template; anything with
+   dialogue, a consistent voice, or a scored montage goes through
+   `dw:minimax-h3`'s `dialogue-short`/`music-video`, prompted via
+   `h3-prompt-writing`'s structure (`subject_definitions`,
+   `retention_analysis`, `detailed_description`, `overall_soundscape`,
+   `non_diegetic_music`) rather than the raw script line. This is composition
+   of existing skills, stated as an explicit decision tree instead of left
+   implicit.
+
+5. **Validate the assembled `shots` argument before queuing.**
+   `validate_workflow` against the chosen template with the full `shots`
+   list as `arguments`, read `plan.estimate` and `plan.downloads_required`,
+   state the cost, and only call `run_workflow` with `acknowledged_cost` once
+   the user (or an explicit "proceed" instruction in an unattended run) signs
+   off. This is the existing gate, just made a mandatory step in the skill
+   rather than something an agent might skip.
+
+6. **Run, read warnings, retry per shot.** After the job completes, read
+   `get_job_events` / `get_gallery_metadata` for the warnings the engine
+   already emits, and `rerun_job(new_seed=True)` a shot that reads wrong
+   (wrong face, no affect in the voice, clipped audio) using the diagnostics
+   already surfaced - not by inventing new heuristics.
+
+7. **Cut, score, deliver.** Once every shot exists, hand off to
+   `assemble-and-score` (or the `series-episodes` five-beat procedure if the
+   script is one episode of a series) for the recut/bed/match_levels/
+   normalize/pair pass. No new mechanism - this step already exists and
+   already composes.
+
+Nothing above is a new engine capability. It is a skill that states, in one
+place, the decision tree an agent currently has to reconstruct from five
+separate skills and the MCP tool list every time - the same role
+`series-episodes` already plays for its narrower slice (turning generated
+shots into a scored episode). This skill sits one level up: turning a script
+into the shots in the first place.
+
+## Testing
+
+Skills are audited the way the other `dw` plugin skills are
+(`tests/test_plugin_skills.py`-style pinning of every stated number to a real
+catalog value), not unit-tested as code. Verification here is a worked
+example: a short multi-character script run through the skill end to end on
+a real server, checked for - cast consistency across shots (the
+`series-episodes` failure mode), correct shape selection per shot, a
+`plan.estimate` quoted before the run, and a final cut that plays back
+without level jumps. That is a manual acceptance run, not an automated
+suite, the same way `series-episodes` itself was validated against two
+hand-built episodes (issue #217).
+
+## Not in scope
+
+- **Automatic model speed optimization.** "If a model is slow, research how
+  to speed it up, try options, keep what works" is a real engineering task
+  (swap `config_type`, add `residency: on_demand`, try a different
+  `offload`) but it is not safe to leave to an unsupervised agent loop: the
+  search space is large, a wrong choice can silently change output quality
+  rather than just fail, and `observed_cost` only tells you a run was slow,
+  never *why*. This stays a human-in-the-loop task, informed by
+  `observed_cost` and the `ACCELERATION.md`/`QUANTIZATION.md` docs, not
+  something this skill attempts.
+- **Workflow authoring from scratch per script.** The skill picks among
+  existing catalog templates; it does not write new pipeline JSON. A script
+  whose shape no template covers is a "propose a new template" conversation,
+  not something the skill improvises at run time.
+- **ComfyUI / node-graph integration.** Out of scope for this repo, which is
+  declarative-JSON-workflow shaped, not node-graph shaped.
+- **Full unattended autonomy.** Step 5's cost acknowledgment is a real gate,
+  not a formality; this proposal assumes a human (or an explicit
+  pre-authorization) confirms spend before a multi-shot script runs.
+
+## Later
+
+- A `cost.per_entry` on the family templates (CLAUDE.md notes neither
+  MiniMax cut template has one yet) would let step 5 quote a tighter number
+  for a script's actual shot count rather than the template's default list.
+- If `select`/`judge` (see `docs/proposals/score-and-select.md`) ships, step
+  6's per-shot retry could become deterministic best-of-N per shot rather
+  than agent-judged reruns.
+
+## Open question for whoever picks this up
+
+Whether this belongs as a `plugins/dw/skills/` entry (composes over MCP,
+travels with the plugin, gets the same numeric-pinning audit as the other
+family skills) or as a `docs/` guide referenced by `list_guides` (no pinning
+audit, easier to keep prose-loose). Leaning towards a plugin skill, since its
+whole value is the decision tree an agent follows at request time, which is
+exactly what the existing family skills already do.

From 6fe35951a443eed347814965ec11bf14cebbe934 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sat, 19 Sep 2026 11:12:19 -0500
Subject: [PATCH 45/77] feat(proposal): add Framewright comparison proposal
 document

---
 docs/proposals/framewright-comparison.md | 314 +++++++++++++++++++++++
 1 file changed, 314 insertions(+)
 create mode 100644 docs/proposals/framewright-comparison.md

diff --git a/docs/proposals/framewright-comparison.md b/docs/proposals/framewright-comparison.md
new file mode 100644
index 00000000..3aff110f
--- /dev/null
+++ b/docs/proposals/framewright-comparison.md
@@ -0,0 +1,314 @@
+# Proposal: what dw should take from Framewright, and what it should not
+
+Status: **proposed**, 2026-09-19. Written by Don's session, model `opus` via
+provider `anthropic`, after reading
+[raydeStar/framewright](https://github.com/raydeStar/framewright) (README,
+`docs/ARCHITECTURE.md`, `docs/ASSET_LIBRARY.md`, `workflows/README.md`,
+`docs/IMPLEMENTATION_HANDOFF.md`) against this repository at `7001b90`. No
+code changes yet. Six ideas, one proposal, because they share a theme -
+*the record a generated file carries about itself* - and because the first
+unblocks two of the others.
+
+## What Framewright is, in one paragraph
+
+A local-first film pre-production studio (C#/.NET 10 + React, Windows-only,
+release candidate). It runs no model itself: images, video and music go out
+to ComfyUI, Codex ImageGen, GPT Image or a YuE2 service through allowlisted
+adapters. Its substance is the layer *above* generation - shot cards,
+character/wardrobe/style "authorities" with named roles, immutable versions
+behind a ratification gate, a frozen manifest per generation, a
+project-level delivery contract (dimensions, aspect, fps, sample rate), a
+durable job ledger that survives restart, and a media-pool asset library
+with tags, collections, provenance and non-destructive archive.
+
+So the two projects barely overlap in code and overlap a lot in problem. dw
+is the thing Framewright would dispatch *to*; Framewright is what an agent
+driving dw over MCP does by hand today (`series-episodes` is the worked
+example: draw the cast once, `keep_output` each portrait, reference them by
+`asset:` name for every later episode). That framing sorts the ideas
+cleanly: most are app-layer and belong to whoever builds on dw, a few are
+engine- or workspace-layer and fit here.
+
+## Already equivalent - nothing to take
+
+Checked first, so the rest of the document is not a list of things the
+engine does under another name.
+
+| Framewright | dw |
+|---|---|
+| Frozen manifest per generation | The realized `workflow.json` beside every run's `manifest.json` (`dw/realize.py`) |
+| `requiredPlaceholders` checked in both directions | An undeclared `variable:` is a validation error; a declared variable no step reads is tracked in `dw/elision.py` |
+| `requiredModels` / `requiredNodeTypes` checked against the live ComfyUI | `plan.downloads_required` (`dw/plan.py`), `dw/kernel_availability.py` |
+| Encoded video probed after render | `dw/media_info.py`; `warn_if_written_above_full_scale` reads the written file back |
+| Reference slot capacity discovered from the workflow | `dw/reference_limits.py`; the H3 and LTX reference templates |
+| Approval-marked action over MCP | `acknowledged_cost` binding |
+| Content-addressed store keeps bytes a manifest cites | `keep_output` hard-links out of `outputs/` so pruning a run cannot break an `asset:` |
+| Curated cost in `library.json` summary | `cost` (curated) beside `observed` (measured, `dw/server/observed_cost.py`) |
+| Seed derived from the manifest hash | An explicit `seed` variable, the step cache keyed on it, `rerun(new_seed=True)` - a coherent alternative, not a gap |
+
+## Not compatible, deliberately
+
+- **Immutable versions, ratification, candidate promotion.** A review
+  product's state machine. dw's boundary - the agent judges, `keep_output`
+  promotes, `score-and-select` (#119) for the deterministic case - is the
+  right one for an engine.
+- **Sketch lab, tablet pairing, Codex ImageGen, GPT Image, the World
+  canon block prepended to every prompt.** UI layer or cloud providers dw
+  does not target. (A canon prefix is expressible today as a stored prompt a
+  template references; nothing to add.)
+- **A curated read-only MCP surface.** Framewright hides authoring from the
+  agent on purpose; dw's MCP is agent-first by design. A different trust
+  model, not a missing feature.
+
+## The six, in dependency order
+
+### 1. Provenance on a kept asset
+
+**The gap.** `keep_output_as_asset` (`dw/server/app.py`, the
+`POST /api/assets/keep` route) links or copies the file and returns
+`{reference, name, path, linked, shared}`. Nothing records *where the file
+came from*. Once a frame is an asset, the job, run, seed and realized
+workflow that made it are recoverable only by grepping every
+`manifest.json` for a matching file name - and not at all once that run is
+pruned, which is the very case `keep_output` exists for. `GET /api/assets`
+reports `name, kind, size, mtime, origin`: the library cannot say which of
+two portraits is the one episode 1 used, and an agent about to reuse a
+reference cannot `get_job_workflow` the recipe that produced it. Framewright
+treats "provider source, content identifier and the manifest that produced
+it" as immutable facts on every asset record, and it is right to.
+
+**Proposal.** A sidecar beside the asset, `<name>.json` in the same folder
+of the library, written by `keep_output` and read by the two listings:
+
+```json
+{
+  "kept_at": 1758300000.0,
+  "sha256": "…",
+  "source": {
+    "kind": "output",
+    "name": "minimax/dialogue-short/20260919T101500Z-3f2a9c1d/final/shot@lena.mp4",
+    "job_id": "4f2a9c1d3e77",
+    "run_id": "20260919T101500Z-3f2a9c1d",
+    "workflow": "templates/minimax/dialogue-short",
+    "step": "shot@lena",
+    "seed": 1187
+  },
+  "tags": [],
+  "notes": ""
+}
+```
+
+- `source` is read off the run's `manifest.json` at keep time (the step
+  entry that lists this file, the manifest's `seed`, the `workflow` block)
+  and off `jobs.sqlite` for `job_id` where the run has one. Best effort:
+  a file with no manifest (flat layout, an older run) gets `source: null`
+  and the keep still succeeds - provenance is a record, not a gate.
+- `sha256` is what lets a later reader confirm the sidecar still describes
+  the bytes beside it after an `overwrite=true`, and is the field a future
+  duplicate check would key on.
+- `tags` and `notes` are the artist-owned half Framewright separates from
+  the immutable half. Written empty by `keep_output`; a `PATCH
+  /api/assets/{name}` (and MCP `tag_asset`) is the only writer. An
+  uploaded asset gets a sidecar on the first tag, not on upload.
+- Listings gain `provenance` (the `source` block, or null) and `tags`;
+  the compact MCP `list_assets` carries only `job_id`/`workflow` per the
+  #101 token budget, `get_asset(name)` the whole record. `delete_asset`
+  removes the sidecar with the file; `_iter_gallery_files` already skips
+  non-media, so a sidecar is never listed as an asset.
+- The role (#2) is a field on the same record, which is why this one is
+  first.
+
+**Cost.** One function extended, one new route and MCP tool for tags, a
+JSON schema for the sidecar (`dw/asset_record_schema.json`, validated on
+read so a hand-edited one is a warning rather than a crash), tests for the
+keep-from-pruned-run and flat-layout cases. The `ASSET_REFERENCE_PATTERN`
+already forbids a name from being `.json`-suffixed into a collision, but
+worth a test.
+
+**Decision needed.** Sidecar (`<name>.json`) versus one index
+(`assets/.library.json`). Sidecar recommended: it moves with the file when
+someone reorganizes the folder by hand, it survives two processes writing
+different assets at once with no lock, and the outputs tree already uses
+the sidecar shape (`manifest.json`, `workflow.json`). An index is faster
+to list, but the library is walked with `os.stat` per file already.
+
+### 2. Reference roles
+
+**The gap.** Framewright names what each reference *controls* - identity,
+wardrobe, location, prop, style - and records what was selected, what was
+actually attached, and which constraints survived dispatch. dw's H3 and
+LTX templates take references positionally (`references: [...]` in a
+`shots` entry, `singer_reference`, the reference sheet), and the skills
+carry the meaning in prose. For a single run that is enough. Across a
+series, the meaning is what the next agent needs: *which* of the six kept
+portraits is Lena's identity reference and which is the wardrobe plate.
+
+**Proposal.** Template-and-catalog, not engine:
+
+- `role` on the sidecar from #1 (free string, suggested vocabulary
+  `identity | wardrobe | location | prop | style | endpoint`), settable
+  through the same `PATCH`, reported by the listing.
+- The catalog's `lists` block may name, per `item:` field that takes a
+  reference, the role the step consumes it as (`"references": {"role":
+  "identity"}` under `list_fields` in `dw/for_each.py`). Informational -
+  no validation error on a mismatch, a *warning* when a kept asset with a
+  declared role is passed where a different role is consumed, mirroring
+  how `adapter_compatibility.py` warns rather than refuses on the unknown
+  case.
+- The composition skills state the roles their family's slots take;
+  `tests/test_plugin_skills.py` pins the vocabulary the same way it pins
+  numbers.
+
+What is **not** proposed: role-typed slots in the workflow schema, or the
+engine rewriting a prompt to label each image. That is Framewright's
+prompt-assembly layer, and here it is the skill's job.
+
+### 3. Workspace-level delivery contract
+
+**The gap.** Framewright locks dimensions, aspect, fps, colour space and
+sample rate at the project, every route inherits them, and a render that
+probes different from the contract cannot become a deliverable. dw has
+workspaces but no workspace-level *settings*: a multi-shot project passes
+`width=… height=… fps=…` on every job or edits every template's defaults,
+and a shot rendered at the wrong canvas is discovered when it is cut.
+
+**Proposal.** `delivery.json` at the workspace root (beside `workflows/`,
+`prompts/`, `assets/`, `outputs/`; `delivery` joins the reserved names):
+
+```json
+{"width": 1280, "height": 704, "fps": 25, "audio_sample_rate": 48000}
+```
+
+- Read by `argument_errors` / `set_variables` as a *default layer under the
+  template's defaults*: for a declared variable whose name matches a
+  delivery key (`width`, `height`, `fps`, `num_frames` is deliberately
+  not one - it is a per-shot value), the workspace value replaces the
+  template's default when the caller passed nothing. Explicit `arguments`
+  still win. The realized `workflow.json` shows the folded value, so a run
+  is still self-describing. Plain name matching is the crude part; the
+  catalog already reports every variable name, so an agent can see which
+  will bind.
+- `variable_constraints` still apply to the folded value, so a delivery
+  width a family cannot render is refused at validation, at
+  `variables.width`, with the message saying the value came from the
+  workspace contract.
+- On the write side, `Result.save` already probes what it wrote
+  (`media_info.py`). A saved video or audio whose probed dimensions, rate
+  or sample rate disagree with the contract warns (`kind:
+  delivery_mismatch`) - a warning, not a refusal, for the same reason
+  `audio_no_headroom` is one: intermediates are allowed to differ, and only
+  the workflow knows which file is the deliverable. Restricting the
+  warning to steps marked `subfolder: final` is the natural refinement and
+  reuses a convention the templates already follow.
+- `GET /api/workspaces` / MCP `list_workspaces` report the contract;
+  `PUT /api/workspaces/{name}/delivery` writes it. No UI stage in the first
+  cut.
+
+**Decision needed.** Whether name matching is acceptable or whether a
+template must opt in (`"delivery": "width"` on a variable declaration). Opt
+in is safer and is one schema field; name matching works for every
+template today with no edits. Recommend opt-in, with the four templates
+that are cut together (`dialogue-short`, `music-video`,
+`assemble-and-score`, `dissolve-between-shots`) declaring it in the same
+change.
+
+### 4. A running job survives a server restart
+
+**The gap.** `JobHistory` records "at terminal state only - a crash mid-run
+loses that run's row" (`dw/server/jobs.py`). A job that was `RUNNING` when
+`dw.serve` died is not in the Jobs view after restart; its run directory,
+partial manifest and realized `workflow.json` are on disk with nothing
+pointing at them. Framewright's rule - persist the provider job id *before*
+polling so a restart resumes the exact job rather than posting a duplicate
+- is the half of `docs/proposals/resume.md` that does not need the step
+cache to become durable, and is worth doing on its own.
+
+**Proposal.**
+
+- Write the row at `RUNNING` as well as at terminal state - `id`,
+  `workflow`, `arguments`, `workspace`, `run_id`, `run_dir`, `started_at`,
+  status `running`. One extra write per job, off the runner's hot path
+  (the same thread that already writes the terminal row).
+- On `JobManager` start, any row still `running` becomes `interrupted`
+  (a new terminal status beside `failed`/`cancelled`), `finished_at` set
+  to the restart time, `manifest` read back from the run directory's
+  `manifest.json` if it exists - so the job page can show what it wrote,
+  exactly as a failed job does today.
+- `rerun` on an `interrupted` job is the existing rerun. When resume ships,
+  it is where "continue from the manifest" attaches; until then the
+  interrupted row is what makes the orphaned run directory (#170)
+  addressable from the Jobs view rather than only from the gallery walk.
+- Nothing is re-submitted automatically. A restart is not consent to spend
+  another GPU-hour.
+
+**Cost.** A status constant, a second `record` call site, a startup sweep,
+the UI's status badge list, `observed_cost` already filters on
+`SUCCEEDED` so it is unaffected. `tests/test_server_jobs.py` gains the crash case
+(kill between `RUNNING` and terminal, restart, assert `interrupted` with
+the partial manifest).
+
+### 5. A release evidence ledger
+
+**The gap.** Framewright keeps `docs/RELEASE_EVIDENCE.md`: what the
+automated gate proves versus what was actually rendered on real hardware
+before the tag, with the explicit line "automated contracts do not
+masquerade as live-provider evidence." dw's tests are stronger on the
+*rule* side (every number a skill states is pinned to a diffusers symbol)
+and have nothing on the *run* side: no record says "template X last
+rendered end-to-end on a 24 GB CUDA box on date Y at diffusers Z, cold, in
+N minutes." `observed_cost` holds half of that, per box, in `jobs.sqlite`,
+and nothing exports it.
+
+**Proposal.** `docs/RELEASE_EVIDENCE.md`, one row per template:
+`template | last verified | device | diffusers | cold minutes | job id |
+notes`. Filled by a `scripts/release_evidence.py` that reads the current
+box's `jobs.sqlite` (the `ObservedCosts` query, by catalog name, newest
+successful cold run) and prints rows to merge; `scripts/release.sh` runs it
+and refuses to tag when a template's row is older than the last change to
+that template's file or to the family's diffusers floor - or, less
+strictly, prints the stale list and asks. Docs-only in the first cut; the
+gate can come once the ledger has a release behind it. The one rule worth
+stating in the file header is Framewright's: a green test suite is not a
+row.
+
+### 6. A guided-setup skill
+
+**The gap.** Framewright's `$framewright-setup` inspects the workstation
+read-only before asking a question, explains every download and login
+before making it, and never starts a job. dw has `install.sh`, the MCP
+`get_server_info`, and four composition skills that all begin "check the
+device and workspace" - but no skill that takes a fresh box from clone to
+the first `run_workflow`: which accelerator, whether the HF login the gated
+families need is present, which families' weights are already in the hub
+cache (`dw/hub_cache.py`), which workspace is in effect and why
+(`Workspace.describe` says how it was chosen).
+
+**Proposal.** `plugins/dw/skills/setup/SKILL.md`: inspect first
+(`get_server_info`, `list_workspaces`, `plan` on each family's cheapest
+template for `downloads_required`), report before acting, offer the
+`templates/text-to-image.json` run as the smoke test because it is ungated
+and small, and hand off to the family skill the user asked for. Every
+command it states is one that exists in `dw_mcp/` and is pinned by
+`tests/test_plugin_skills.py` like the others. No engine change.
+
+## Order and scope
+
+| # | Layer | Size | Depends on |
+|---|---|---|---|
+| 1 | server + MCP | small | - |
+| 4 | server | small | - |
+| 6 | plugin | small | - |
+| 2 | catalog + skills | small | 1 |
+| 5 | docs + scripts | small, gate later | observed cost (shipped) |
+| 3 | engine + server | medium | a decision on opt-in |
+
+1, 4 and 6 are independent and each is a single change. 3 is the only one
+that touches the engine's variable resolution and is the one to decide on
+rather than drift into; the rest are the kind of thing that can be edited
+in once the sidecar shape in #1 is agreed.
+
+## Not in scope
+
+Duplicate detection by hash, smart views/collections over tags, automatic
+tagging, and a UI for any of the above. #1's `sha256` and `tags` are the
+fields those would read; none of them are proposed until a consumer asks.

From 127a0f926bb8579102e1f6ea737b83ac026c92ed Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sat, 19 Sep 2026 16:18:32 -0500
Subject: [PATCH 46/77] fix: PR #241 review - waveform layouts, harmonicity
 rate, null media keys

Six findings from the merge-readiness review of #241.

Correctness:

- `_fit_audio_to_frames` indexed `shape[1]` outright, which is the sample
  axis only for a (channels, samples) track. A mono waveform written
  (samples,) raised IndexError on the way to writing a video, and
  (samples, 1) - a layout `_as_stereo` explicitly supports - measured a
  channel count against a sample count and fitted nothing. It now picks
  the sample axis and trims or pads on it, numpy and torch alike.

- `bleed_join` handed `_harmonicity` the native rate, but that function
  turns a rate into lag bounds in samples of the waveform it is given,
  which is at `sample_rate` however it got there. A 16k tail upsampled to
  48k was searched over 180-1500 Hz rather than 60-500, so the #198 check
  could miss the voiced speech it was added for (0.52 against a 0.45
  threshold, where the right range reads 0.98). Only `_spectral_flatness`
  wants the native rate.

- Dropping a dict key whose `variable:` resolved to null contradicted
  `_names_no_media`, which reads a present-and-null `from_file` /
  `from_previous_result` / `from_arguments` as OMITTED. An optional
  reference run with a null variable reached the pipeline as a media-less
  stub instead. Those keys are now exempt from the drop; `select`'s
  optional threshold/index still vanish as before.

- `_strip_result` shallow-copied the Result, so the stripped cache entry
  still shared `_artifact_cache` - which `save()` has already filled with
  decoded frames and the waveform, possibly still on the GPU. Emptying
  `result_list` released nothing for a step that saved.

- `clear_memory` raised with no worker resident, which the route answered
  as a 503 - contradicting the health route beside it, where
  `worker_alive: false` is the ordinary idle state of an on-demand
  worker. Both the pipelines and the step cache live in that process, so
  its absence means there is nothing left to clear: it is a no-op success
  with a null reading.

Performance:

- `_apply_biquad` and `_follow_envelope` were per-sample Python loops on
  the single FIFO worker. The biquad recursion is `scipy.signal.lfilter`
  (scipy is in every install via controlnet-aux), with the Python form
  kept behind a guarded import as the fallback: 4.30s -> 0.081s on a
  3-minute stereo track, agreeing to 3e-15. The envelope keeps its branch
  but loops over plain floats, same values, ~3x.

5124 passed, 16 skipped.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 dw/server/app.py          |  6 +++-
 dw/server/jobs.py         | 13 ++++++--
 dw/step_cache.py          |  6 ++++
 dw/tasks/audio_utils.py   | 46 ++++++++++++++++++++++------
 dw/tasks/video_utils.py   | 36 +++++++++++++++++++---
 dw/variables.py           | 20 ++++++++++++-
 dw_mcp/server.py          |  4 ++-
 tests/test_audio_utils.py | 63 +++++++++++++++++++++++++++++++++++++++
 tests/test_server.py      | 18 +++++++++++
 tests/test_step_cache.py  | 20 +++++++++++++
 tests/test_variables.py   | 34 +++++++++++++++++++++
 tests/test_video_utils.py | 58 +++++++++++++++++++++++++++++++++++
 12 files changed, 306 insertions(+), 18 deletions(-)

diff --git a/dw/server/app.py b/dw/server/app.py
index 4dd785b2..b44f75e6 100644
--- a/dw/server/app.py
+++ b/dw/server/app.py
@@ -3495,7 +3495,11 @@ def clear_memory():
 
         Refused while a job is running or queued (409) rather than blocked -
         the queue is FIFO, so the caller should wait for the job to finish
-        and retry instead of this call stalling until it does."""
+        and retry instead of this call stalling until it does.
+
+        A server with no worker process resident answers `cleared` with a
+        null `info` rather than a 503: the worker is on-demand, so its
+        absence means there was nothing loaded to clear."""
         if manager.is_busy():
             raise HTTPException(
                 status_code=409,
diff --git a/dw/server/jobs.py b/dw/server/jobs.py
index 5e43ff5a..ab6e6475 100644
--- a/dw/server/jobs.py
+++ b/dw/server/jobs.py
@@ -1366,9 +1366,18 @@ def clear_memory(self, timeout=30):
         one would clear state a queued run still expects resident. The
         30s timeout (vs. `memory_status`'s 5s) matches the REPL's `memory
         clear` (`repl_commands.py`): actually freeing CUDA memory takes
-        longer than reading a counter does."""
+        longer than reading a counter does.
+
+        Returns the reading taken after the clear, or None when there was no
+        worker to clear - nothing was resident in that case."""
         if not self.worker_manager.worker_active:
-            raise RuntimeError("worker not active")
+            # Nothing to clear, and not a fault: the pipelines and the step
+            # cache both live in the worker process, so no worker running
+            # means both are already gone. An on-demand worker is legitimately
+            # absent on an idle server (#206), which this used to answer with
+            # a 503 saying the worker was unavailable. None is "no reading
+            # was taken", not a failure
+            return None
         if not self._worker_lock.acquire(timeout=2):
             raise RuntimeError("worker busy")
         try:
diff --git a/dw/step_cache.py b/dw/step_cache.py
index 47af61ff..e1a687ec 100644
--- a/dw/step_cache.py
+++ b/dw/step_cache.py
@@ -253,6 +253,12 @@ def _strip_result(result):
         """A shallow copy of the Result with its realized media dropped."""
         stripped = copy.copy(result)
         stripped.result_list = []
+        # A fresh cache, not the shallow copy's shared one: save() fills
+        # _artifact_cache with the artifacts it extracted - decoded frames, a
+        # waveform, possibly still on the GPU - so carrying it over would pin
+        # exactly what dropping result_list exists to release. The original
+        # Result keeps its own cache; only this entry's copy starts empty.
+        stripped._artifact_cache = {}
         return stripped
 
     @staticmethod
diff --git a/dw/tasks/audio_utils.py b/dw/tasks/audio_utils.py
index f2b2598a..33861b11 100644
--- a/dw/tasks/audio_utils.py
+++ b/dw/tasks/audio_utils.py
@@ -251,7 +251,13 @@ def bleed_join(
 
     tail_source = previous[:, -window:]
     flatness = _spectral_flatness(tail_source, sample_rate, native_sample_rate)
-    harmonicity = _harmonicity(tail_source, native_sample_rate or sample_rate)
+    # sample_rate, not native_sample_rate: _harmonicity turns a rate into lag
+    # bounds in samples of the waveform it is handed, and that waveform is at
+    # sample_rate however it got there. Passing the native rate of an upsampled
+    # tail searched the wrong lag range (16k against a 48k track: 180-1500 Hz
+    # rather than 60-500) and could miss the voiced speech #198 added it for.
+    # Only _spectral_flatness wants the native rate, to band-limit its window.
+    harmonicity = _harmonicity(tail_source, sample_rate)
     if flatness < TONAL_FLATNESS_THRESHOLD or harmonicity > HARMONICITY_THRESHOLD:
         emit_warning(
             f"bleed_join: the tail being reversed onto the seam looks tonal or "
@@ -1308,14 +1314,19 @@ def _follow_envelope(waveform, sample_rate, attack_ms, release_ms):
     rectified = numpy.abs(waveform).max(axis=0)
     attack_coef = _time_constant_coef(attack_ms, sample_rate)
     release_coef = _time_constant_coef(release_ms, sample_rate)
-    envelope = numpy.empty_like(rectified)
+    # The branch on the running level is what makes this a loop rather than a
+    # filter, but the per-sample numpy indexing was the expensive half of it:
+    # a 3-minute track is ~8M samples, and this runs on the single FIFO
+    # worker. tolist() hands the loop plain Python floats, which is the same
+    # arithmetic on the same values, several times faster
+    samples = rectified.tolist()
+    envelope = []
     level = 0.0
-    for i in range(rectified.shape[0]):
-        sample = float(rectified[i])
+    for sample in samples:
         coef = attack_coef if sample > level else release_coef
         level = coef * level + (1.0 - coef) * sample
-        envelope[i] = level
-    return envelope
+        envelope.append(level)
+    return numpy.asarray(envelope, dtype=rectified.dtype)
 
 
 def _time_constant_coef(time_ms, sample_rate):
@@ -1404,11 +1415,28 @@ def _biquad_coefficients(kind, cutoff_hz, q, sample_rate):
 
 
 def _apply_biquad(channel, b, a):
-    """Direct Form I second-order section, sample by sample - the feedback
-    a biquad needs cannot be vectorized away."""
-    out = numpy.empty_like(channel, dtype=numpy.float64)
+    """One second-order section, run over a channel.
+
+    The feedback cannot be vectorized away, but it does not have to be run in
+    Python either: scipy's lfilter is this exact recursion in C, and scipy is
+    already in every install (controlnet-aux brings it). The Python Direct
+    Form I below is the fallback for an environment without it - same
+    recursion, same zero initial conditions, ~50x slower on a full track.
+    """
     b0, b1, b2 = b
     a1, a2 = a
+    try:
+        from scipy.signal import lfilter
+    except ImportError:
+        pass
+    else:
+        return lfilter(
+            numpy.array([b0, b1, b2], dtype=numpy.float64),
+            numpy.array([1.0, a1, a2], dtype=numpy.float64),
+            numpy.asarray(channel, dtype=numpy.float64),
+        )
+
+    out = numpy.empty_like(channel, dtype=numpy.float64)
     x1 = x2 = y1 = y2 = 0.0
     for i in range(channel.shape[0]):
         x0 = float(channel[i])
diff --git a/dw/tasks/video_utils.py b/dw/tasks/video_utils.py
index d0271305..f636ac94 100644
--- a/dw/tasks/video_utils.py
+++ b/dw/tasks/video_utils.py
@@ -399,8 +399,12 @@ def _fit_audio_to_frames(audio, frame_count, frame_rate, sample_rate):
     trim below keep whichever type and device it arrived with rather than
     forcing a host round trip the caller may not want yet.
     """
+    axis = _sample_axis(audio)
+    if axis is None:
+        return audio
+
     expected = round(frame_count / frame_rate * sample_rate)
-    difference = audio.shape[1] - expected
+    difference = audio.shape[axis] - expected
     if difference == 0 or abs(difference) > AUDIO_FIT_TOLERANCE_SECONDS * sample_rate:
         return audio
 
@@ -408,7 +412,31 @@ def _fit_audio_to_frames(audio, frame_count, frame_rate, sample_rate):
         f"Fitting decoded audio to {frame_count} frames ({difference:+} samples)"
     )
     if difference > 0:
-        return audio[:, :expected]
+        trim = [slice(None)] * audio.ndim
+        trim[axis] = slice(None, expected)
+        return audio[tuple(trim)]
     if isinstance(audio, torch.Tensor):
-        return torch.nn.functional.pad(audio, (0, -difference))
-    return numpy.pad(audio, ((0, 0), (0, -difference)))
+        # torch.nn.functional.pad takes its pairs from the last axis backwards
+        padding = [0, 0] * audio.ndim
+        padding[2 * (audio.ndim - 1 - axis) + 1] = -difference
+        return torch.nn.functional.pad(audio, padding)
+    widths = [(0, 0)] * audio.ndim
+    widths[axis] = (0, -difference)
+    return numpy.pad(audio, widths)
+
+
+def _sample_axis(audio):
+    """The axis a waveform's samples run along, or None if it has no such axis.
+
+    Not a fixed index: a generated track arrives in any of the layouts
+    _as_stereo reads - (channels, samples), (samples, channels), or a bare
+    (samples,) - and a mono one written (samples,) or (samples, 1) used to
+    reach shape[1] here and either raise IndexError or fit the wrong axis
+    into a silent no-op. Channels are few and samples are many, so the
+    longer axis is the sample axis.
+    """
+    if audio.ndim == 1:
+        return 0
+    if audio.ndim != 2:
+        return None
+    return 0 if audio.shape[0] > audio.shape[1] else 1
diff --git a/dw/variables.py b/dw/variables.py
index 1bad55df..c9f8bed2 100644
--- a/dw/variables.py
+++ b/dw/variables.py
@@ -1,6 +1,11 @@
 import copy
 import logging
 import PIL
+from .arguments import (
+    FROM_ARGUMENTS_KEY,
+    FROM_FILE_KEY,
+    FROM_PREVIOUS_RESULT_KEY,
+)
 from .security import (
     validate_variable_name,
     validate_string_input,
@@ -10,6 +15,11 @@
 
 logger = logging.getLogger("dw")
 
+# The keys an object description names its media with. A "variable:" under one
+# of these that resolves to null has to stay present-and-null for
+# realize_object to read it as an omitted optional reference
+MEDIA_SOURCE_KEYS = (FROM_FILE_KEY, FROM_PREVIOUS_RESULT_KEY, FROM_ARGUMENTS_KEY)
+
 
 class VariableNotFoundError(ValueError):
     """Raised when a workflow references a "variable:name" that isn't declared."""
@@ -86,7 +96,15 @@ def replace_variables(data, variables):
                 # it. A literal null written inline in the workflow JSON
                 # never goes through this branch, so its meaning elsewhere
                 # (a declared-but-unset default) is untouched.
-                if resolved is None:
+                #
+                # Except where the key itself is how an object description
+                # names its media: realize_object reads a present-and-null
+                # 'from_file'/'from_previous_result'/'from_arguments' as
+                # OMITTED - an optional reference this run was given nothing
+                # for (_names_no_media in arguments.py). Dropping the key
+                # there turns that into a media-less stub that reaches the
+                # pipeline instead.
+                if resolved is None and k not in MEDIA_SOURCE_KEYS:
                     continue
                 result[k] = resolved
             else:
diff --git a/dw_mcp/server.py b/dw_mcp/server.py
index 98e95e51..5c738559 100644
--- a/dw_mcp/server.py
+++ b/dw_mcp/server.py
@@ -322,7 +322,9 @@ def clear_memory() -> dict:
 
         Refused with a 409 while a job is running or queued - the queue is
         FIFO, so wait for it to finish and retry rather than expecting this
-        call to block until it does."""
+        call to block until it does. On an idle server with no model process
+        resident there is nothing loaded to clear, so it succeeds with a null
+        `info` rather than failing."""
         return catalog.clear_memory(client)
 
     def get_health() -> dict:
diff --git a/tests/test_audio_utils.py b/tests/test_audio_utils.py
index 303f60a3..a932c173 100644
--- a/tests/test_audio_utils.py
+++ b/tests/test_audio_utils.py
@@ -3,6 +3,9 @@
 slicing, and seam joining.
 """
 
+import builtins
+from unittest import mock
+
 import numpy
 import pytest
 import torch
@@ -422,6 +425,42 @@ def test_upsampled_noise_does_not_falsely_warn_when_native_rate_given(self, capl
         assert "speech" not in caplog.text
 
 
+    def test_upsampled_speech_still_warns_when_native_rate_given(self, caplog):
+        """The other half of the #198 band-limiting: the native rate tells
+        _spectral_flatness where the tail's own Nyquist is, but _harmonicity
+        turns a rate into lag bounds in samples of the waveform it is handed -
+        which is at the target rate. Passing the native rate there searched
+        180-1500 Hz on a 48 kHz track instead of 60-500, missing the voiced
+        speech the check exists to catch."""
+        native_rate = 16000
+        target_rate = 48000
+        n = int(native_rate * 0.3)
+        t = numpy.arange(n) / native_rate
+        rng = numpy.random.default_rng(3)
+        f0 = 150.0
+        harmonics = [1.0, 0.6, 0.45, 0.3, 0.2, 0.12]
+        speech_like = sum(
+            amp
+            * numpy.sin(2 * numpy.pi * f0 * (k + 1) * t + rng.uniform(0, 2 * numpy.pi))
+            for k, amp in enumerate(harmonics)
+        )
+        speech_like = speech_like + rng.normal(0, 0.25, n)
+        speech_like = (speech_like / numpy.abs(speech_like).max()).astype(numpy.float32)
+        upsampled = resample_waveform(speech_like[None, :], native_rate, target_rate)
+        following = numpy.zeros_like(upsampled)
+
+        with caplog.at_level("WARNING"):
+            bleed_join(
+                upsampled,
+                following,
+                target_rate,
+                300,
+                native_sample_rate=native_rate,
+            )
+
+        assert "tonal" in caplog.text or "speech" in caplog.text
+
+
 class TestResampleAudio:
     def test_it_scales_the_length_to_the_new_rate(self):
         waveform = numpy.zeros((2, 44100), dtype=numpy.float32)
@@ -1087,6 +1126,30 @@ def rms(self, waveform):
         # skip the filter's brief settling transient
         return float(numpy.sqrt(numpy.mean(numpy.square(waveform[:, 200:]))))
 
+    def test_the_scipy_path_and_the_python_fallback_agree(self):
+        """_apply_biquad runs the recursion through scipy's lfilter, which is
+        in every install, and keeps the per-sample Python form for an
+        environment without it. Two implementations of one filter, so they are
+        pinned to each other rather than each to its own expectations."""
+        from dw.tasks import audio_utils
+
+        rng = numpy.random.default_rng(0)
+        channel = rng.standard_normal(4000).astype(numpy.float32)
+        b, a = audio_utils._biquad_coefficients("lowpass", 1000.0, 0.707, 8000)
+
+        through_scipy = audio_utils._apply_biquad(channel, b, a)
+        real_import = builtins.__import__
+
+        def without_scipy(name, *args, **kwargs):
+            if name.startswith("scipy"):
+                raise ImportError("no scipy")
+            return real_import(name, *args, **kwargs)
+
+        with mock.patch.object(builtins, "__import__", without_scipy):
+            in_python = audio_utils._apply_biquad(channel, b, a)
+
+        assert numpy.abs(through_scipy - in_python).max() < 1e-9
+
     def test_lowpass_passes_low_frequencies_and_attenuates_high_ones(self):
         from dw.tasks.audio_utils import filter_audio
 
diff --git a/tests/test_server.py b/tests/test_server.py
index 257e8086..d6966e99 100644
--- a/tests/test_server.py
+++ b/tests/test_server.py
@@ -821,6 +821,24 @@ def test_memory_says_why_a_reading_is_not_the_worker_s(tmp_path):
     assert busy["info"] == {"gpu_memory_allocated_mb": 8.125}
 
 
+def test_clearing_memory_with_no_worker_resident_is_a_no_op_not_a_fault(server):
+    """The worker is on-demand, so `worker_alive: false` is the ordinary idle
+    state of a server that has not run a job yet (#206) - and both the loaded
+    pipelines and the step cache live in that process, so its absence means
+    there is nothing left to clear. This used to raise into a 503 saying the
+    worker was unavailable, contradicting the health route beside it."""
+    with server(success_script) as client:
+        assert client.get("/api/health").json()["worker_alive"] is False
+
+        response = client.post("/api/memory/clear")
+
+        assert response.status_code == 200
+        body = response.json()
+        assert body["cleared"] is True
+        # nothing was measured, because there was nothing to measure
+        assert body["info"] is None
+
+
 def test_health_and_memory(server):
     import socket
 
diff --git a/tests/test_step_cache.py b/tests/test_step_cache.py
index 8cc875ce..949b7051 100644
--- a/tests/test_step_cache.py
+++ b/tests/test_step_cache.py
@@ -300,6 +300,26 @@ def test_unretained_entry_stores_a_result_with_an_empty_result_list():
     assert result.result_list == ["a decoded frame"]
 
 
+def test_unretained_entry_does_not_keep_the_artifacts_save_extracted():
+    """The same rule, one layer down: Result memoizes get_artifact_list in
+    _artifact_cache, which save() has already filled with the decoded frames
+    and waveform - possibly still on the GPU. A shallow copy shares that dict,
+    so emptying result_list released nothing at all for a step that saved."""
+    cache = StepCache()
+    step_data = {"name": "gen", "pipeline": {"arguments": {"prompt": "a cat"}}}
+    result = FakeResult("first")
+    result.result_list = ["a decoded frame"]
+    frames = ["a decoded frame"]
+    result._artifact_cache = {id(result.result_list): frames}
+    cache.put("w", step_data, 42, result, "/out", False)
+
+    hit = cache.get("w", step_data, 42, set(), "/out", False)
+
+    assert hit._artifact_cache == {}
+    # the original keeps its own - only the cached copy starts empty
+    assert result._artifact_cache == {id(result.result_list): frames}
+
+
 def test_retain_result_true_but_not_retainable_stores_without_result_list():
     """A chain step's save_segments cleans up its segment files during
     save(), before put() runs - Result.retainable turns False, and the entry
diff --git a/tests/test_variables.py b/tests/test_variables.py
index 73ae97d4..75df3762 100644
--- a/tests/test_variables.py
+++ b/tests/test_variables.py
@@ -78,6 +78,40 @@ def test_replace_variables_leaves_a_literal_null_untouched():
     assert result["arguments"]["threshold"] is None
 
 
+def test_replace_variables_keeps_a_null_media_source_key_present():
+    # The one place a null has to survive as a null: realize_object reads a
+    # present-and-null 'from_file' on a dict that names a type as OMITTED - an
+    # optional reference this run was given nothing for. Dropping the key
+    # would turn that into a media-less stub that reaches the pipeline.
+    data = {
+        "arguments": {
+            "reference": {
+                "reference_type": "some.module.AudioReference",
+                "from_file": "variable:voice",
+            }
+        }
+    }
+
+    result = replace_variables(data, {"voice": None})
+    reference = result["arguments"]["reference"]
+    assert "from_file" in reference
+    assert reference["from_file"] is None
+
+
+def test_a_null_media_source_key_realizes_as_omitted():
+    # The consumer end of the same rule, so a change to either side fails here
+    # rather than reaching a pipeline as a reference holding no media.
+    from dw.arguments import OMITTED, realize_object
+
+    data = {
+        "reference_type": "some.module.AudioReference",
+        "from_file": "variable:voice",
+    }
+
+    resolved = replace_variables(data, {"voice": None})
+    assert realize_object(resolved) is OMITTED
+
+
 def test_replace_variables_does_not_mutate_input():
     data = {"key1": "variable:test", "key2": ["variable:test", "static"]}
     original = {"key1": "variable:test", "key2": ["variable:test", "static"]}
diff --git a/tests/test_video_utils.py b/tests/test_video_utils.py
index 5d227934..71167733 100644
--- a/tests/test_video_utils.py
+++ b/tests/test_video_utils.py
@@ -14,6 +14,7 @@
 from dw.result import AudioVideo
 from dw.tasks.task import _VIDEO_PROCESSOR_COMMANDS, Task
 from dw.tasks.video_utils import (
+    _fit_audio_to_frames,
     extract_frame,
     frame_count,
     get_frame,
@@ -468,3 +469,60 @@ def test_a_count_that_is_not_a_number_is_refused(self):
     def test_a_numeric_string_is_taken(self):
         """A count that arrived through a `variable:` may still be a string."""
         assert len(loop_frames(Image.new("RGB", (2, 2)), "121")) == 121
+
+
+class TestFitAudioToFrames:
+    """Codec padding trimmed off a generated track, in whatever layout the
+    waveform arrived in.
+
+    It used to index shape[1] outright, which is only the sample axis for a
+    (channels, samples) track: a mono waveform written (samples,) raised
+    IndexError on the way to writing a video, and (samples, 1) - a layout
+    _as_stereo explicitly supports - measured one channel against a sample
+    count and silently fitted nothing.
+    """
+
+    # 24 frames at 24 fps of 48 kHz audio is 48000 samples
+    FRAMES, FPS, RATE, EXPECTED = 24, 24.0, 48000, 48000
+
+    def fit(self, audio):
+        return _fit_audio_to_frames(audio, self.FRAMES, self.FPS, self.RATE)
+
+    @pytest.mark.parametrize(
+        "shape, axis",
+        [((2, 48100), 1), ((48100, 2), 0), ((48100,), 0), ((48100, 1), 0), ((1, 48100), 1)],
+    )
+    def test_every_layout_is_trimmed_on_its_own_sample_axis(self, shape, axis):
+        for audio in (numpy.zeros(shape, numpy.float32), torch.zeros(shape)):
+            assert self.fit(audio).shape[axis] == self.EXPECTED
+
+    @pytest.mark.parametrize(
+        "shape, axis",
+        [((2, 47900), 1), ((47900, 2), 0), ((47900,), 0), ((47900, 1), 0), ((1, 47900), 1)],
+    )
+    def test_every_layout_is_padded_on_its_own_sample_axis(self, shape, axis):
+        for audio in (numpy.zeros(shape, numpy.float32), torch.zeros(shape)):
+            fitted = self.fit(audio)
+            assert fitted.shape[axis] == self.EXPECTED
+            # Padding lands on the sample axis only - the channel axis, where
+            # there is one, comes back the size it went in
+            if len(shape) == 2:
+                assert fitted.shape[1 - axis] == shape[1 - axis]
+
+    def test_a_track_of_its_own_length_is_left_alone(self):
+        audio = numpy.zeros((2, self.EXPECTED), numpy.float32)
+
+        assert self.fit(audio) is audio
+
+    def test_a_genuinely_different_length_is_left_alone(self):
+        # A song laid over a short clip, not codec padding
+        audio = numpy.zeros((2, self.EXPECTED * 3), numpy.float32)
+
+        assert self.fit(audio) is audio
+
+    def test_the_samples_are_carried_over_not_just_the_shape(self):
+        audio = numpy.arange(48100, dtype=numpy.float32)
+
+        fitted = self.fit(audio)
+
+        assert fitted[0] == 0.0 and fitted[-1] == 47999.0

From d01686eb234688058564225a4d809090519354e9 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sat, 19 Sep 2026 16:30:05 -0500
Subject: [PATCH 47/77] format

---
 tests/test_audio_utils.py |  1 -
 tests/test_video_utils.py | 16 ++++++++++++++--
 2 files changed, 14 insertions(+), 3 deletions(-)

diff --git a/tests/test_audio_utils.py b/tests/test_audio_utils.py
index a932c173..392b935f 100644
--- a/tests/test_audio_utils.py
+++ b/tests/test_audio_utils.py
@@ -424,7 +424,6 @@ def test_upsampled_noise_does_not_falsely_warn_when_native_rate_given(self, capl
         assert "tonal" not in caplog.text
         assert "speech" not in caplog.text
 
-
     def test_upsampled_speech_still_warns_when_native_rate_given(self, caplog):
         """The other half of the #198 band-limiting: the native rate tells
         _spectral_flatness where the tail's own Nyquist is, but _harmonicity
diff --git a/tests/test_video_utils.py b/tests/test_video_utils.py
index 71167733..cb8f6e7d 100644
--- a/tests/test_video_utils.py
+++ b/tests/test_video_utils.py
@@ -490,7 +490,13 @@ def fit(self, audio):
 
     @pytest.mark.parametrize(
         "shape, axis",
-        [((2, 48100), 1), ((48100, 2), 0), ((48100,), 0), ((48100, 1), 0), ((1, 48100), 1)],
+        [
+            ((2, 48100), 1),
+            ((48100, 2), 0),
+            ((48100,), 0),
+            ((48100, 1), 0),
+            ((1, 48100), 1),
+        ],
     )
     def test_every_layout_is_trimmed_on_its_own_sample_axis(self, shape, axis):
         for audio in (numpy.zeros(shape, numpy.float32), torch.zeros(shape)):
@@ -498,7 +504,13 @@ def test_every_layout_is_trimmed_on_its_own_sample_axis(self, shape, axis):
 
     @pytest.mark.parametrize(
         "shape, axis",
-        [((2, 47900), 1), ((47900, 2), 0), ((47900,), 0), ((47900, 1), 0), ((1, 47900), 1)],
+        [
+            ((2, 47900), 1),
+            ((47900, 2), 0),
+            ((47900,), 0),
+            ((47900, 1), 0),
+            ((1, 47900), 1),
+        ],
     )
     def test_every_layout_is_padded_on_its_own_sample_axis(self, shape, axis):
         for audio in (numpy.zeros(shape, numpy.float32), torch.zeros(shape)):

From ec1df29af299ecfba21182b74da4a5ee953c1e2e Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sat, 19 Sep 2026 17:02:44 -0500
Subject: [PATCH 48/77] docs(plan): agent discoverability - the prompt library,
 traits, and self-enumeration

Nine tasks closing what a review of the agent-facing surface found: list_prompts
returns 87 KB and is rejected by a client cap, nothing an agent reads names the
prompt library, has-audio gates on video, and four documents that enumerate the
plugin's skills all missed the fourth.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 .../plans/2026-09-19-agent-discoverability.md | 1509 +++++++++++++++++
 1 file changed, 1509 insertions(+)
 create mode 100644 docs/superpowers/plans/2026-09-19-agent-discoverability.md

diff --git a/docs/superpowers/plans/2026-09-19-agent-discoverability.md b/docs/superpowers/plans/2026-09-19-agent-discoverability.md
new file mode 100644
index 00000000..27349190
--- /dev/null
+++ b/docs/superpowers/plans/2026-09-19-agent-discoverability.md
@@ -0,0 +1,1509 @@
+# Agent discoverability: the prompt library, the trait vocabulary, and the surfaces that enumerate themselves
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Close the eight gaps a review of the agent-facing surface found, the
+first of which makes the prompt library uncallable and the second of which
+leaves it unmentioned by anything an agent reads.
+
+**Architecture:** Each task touches one layer and ends with a test that would
+have caught the drift. Two tasks add a *budget* test in the shape
+`tests/test_catalog_structure.py::test_the_compact_listing_fits_the_budget`
+already uses — a measured ceiling with a comment logging why it moved — because
+every finding here is a thing that grew until it broke rather than a thing that
+was designed wrong.
+
+**Tech Stack:** Python 3 / FastAPI (`dw/server/`), the MCP SDK (`dw_mcp/`),
+pytest, markdown skills under `plugins/dw/skills/`.
+
+**Spec:** the review findings in this session. There is no separate spec file;
+the Findings and Global Constraints below are the binding text.
+
+---
+
+## Findings this plan closes
+
+| # | Finding | Task |
+| - | ------- | ---- |
+| 1 | `list_prompts` returns the full text of all 44 prompts (87,373 chars) and is rejected by the client result cap | 1, 2 |
+| 2 | No plugin skill and no guide names the prompt library, so the exemplars for the hardest input are unreachable | 5 |
+| 3 | `intended_model` is free text: `minimax-music` (4) and `minimax-music3` (4) are one family under two spellings | 3 |
+| 4 | `has-audio` gates on `_kind(step) == "video"`, so `templates/minimax/music` does not carry it | 4 |
+| 5 | `series-episodes` is absent from the plugin README table, `plugin.json`, `marketplace.json` and root CLAUDE.md | 6 |
+| 6 | The surface costs 13,225 tokens to connect and nothing guards it | 9 |
+| 7 | README says "55 tools"; so does `get_guide`'s docstring, where the number carries an argument; there are 57 | 7 |
+| 8 | 114 repo-relative links in the nine served guides are dead ends for a reader with no checkout | 8 |
+
+## Global Constraints
+
+- Python: never `eval`/`exec`/`shell=True`; every disk read of a
+  request-named path goes through `validate_path(path, base)` with a
+  non-`None` base (CLAUDE.md *Security Rules* — CodeQL models the validators
+  as barriers, and a read that reaches the disk another way is a real alert).
+- Run tests with `venv/bin/python -m pytest` from the repo root. `venv` has
+  torch; do not create another.
+- **Existing response fields keep their names and meaning.** `GET
+  /api/prompts` must keep answering `prompt_dir`, `prompt_dirs`, `prompts`,
+  `origins` and `details`, and each `details` entry must keep
+  `description`, `intended_model`, `tags` and `text`, for a caller that
+  passes no new parameter. `ui/src/lib/pages/PromptsPage.svelte` reads
+  `details[name].text` as the card subtitle fallback and calls
+  `/api/prompts` with no query string; it must not change.
+- `plugins/dw/skills/*/SKILL.md` must stay **≤ 12,288 bytes**
+  (`SKILL_SIZE_LIMIT` in `tests/test_plugin_skills.py`). `ltx-2.5` has 29
+  bytes of headroom and `minimax-h3` has 12, so every edit to those two is
+  byte-accounted in its task and verified with `wc -c`.
+- Comments explain *why*, in the voice of the surrounding code — no narration
+  of what a line does. Prose in guides and skills is written in the repo's
+  register: a sentence says what breaks, not that something is important.
+- Commit per task. Imperative subject, a body saying why, ending with:
+  `Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>`
+- Do not touch `dw/server/observed_cost.py`, `dw/plan.py` or anything under
+  `ui/` beyond what a task names.
+
+---
+
+### Task 1: `GET /api/prompts` takes filters and can leave the text out
+
+The route serves both the web UI (which needs `text` as a card fallback) and
+MCP (which cannot afford it). Add narrowing, keep the default byte-identical.
+
+**Files:**
+- Modify: `dw/server/app.py:2160-2181` (the `list_prompts` route)
+- Test: `tests/test_server.py` (class `TestPromptLibrary`, around line 2924)
+
+**Interfaces:**
+- Consumes: `prompt_details(paths)` (`dw/server/app.py:485`), `_prompt_roots()`,
+  `workflow_names`, `referenceable`, `WORKSPACE_ORIGIN`, `EXAMPLES_ORIGIN` — all unchanged.
+- Produces: `GET /api/prompts?tag=<t>&intended_model=<m>&include_text=<bool>`.
+  `include_text` defaults to `True`. When false, every `details` entry drops
+  `text` and carries `text_chars: int` instead. `tag` matches one entry of
+  `tags` exactly; `intended_model` matches `intended_model` exactly; both are
+  case-insensitive; both narrow `prompts`, `origins` and `details` together.
+  Task 2 calls this with `include_text=false`.
+
+- [ ] **Step 1: Write the failing tests**
+
+Add to `tests/test_server.py`, inside `class TestPromptLibrary`:
+
+```python
+    def _store(self, client, name, prompt):
+        assert client.put(f"/api/prompts/{name}", json={"prompt": prompt}).status_code == 200
+
+    def test_the_listing_narrows_by_tag_and_model_and_can_omit_the_text(
+        self, server, tmp_path
+    ):
+        with server(success_script) as client:
+            self._store(
+                client,
+                "minimax/Song",
+                {
+                    "text": "Global Metadata\nbpm is 58.",
+                    "description": "a song",
+                    "intended_model": "minimax-music3",
+                    "tags": ["music", "score"],
+                },
+            )
+            self._store(
+                client,
+                "minimax/Fox",
+                {
+                    "text": "a red fox at dawn",
+                    "description": "a fox",
+                    "intended_model": "minimax-h3",
+                    "tags": ["wildlife"],
+                },
+            )
+
+            # A caller that passes nothing gets what it always got
+            plain = client.get("/api/prompts").json()
+            assert "minimax/Song" in plain["prompts"]
+            assert plain["details"]["minimax/Fox"]["text"] == "a red fox at dawn"
+            assert "text_chars" not in plain["details"]["minimax/Fox"]
+
+            # include_text=false swaps the payload for its size
+            slim = client.get("/api/prompts?include_text=false").json()
+            entry = slim["details"]["minimax/Fox"]
+            assert "text" not in entry
+            assert entry["text_chars"] == len("a red fox at dawn")
+            assert entry["description"] == "a fox"
+
+            # A filter narrows the names, the origins and the details together
+            by_model = client.get("/api/prompts?intended_model=MINIMAX-MUSIC3").json()
+            assert by_model["prompts"] == ["minimax/Song"]
+            assert list(by_model["details"]) == ["minimax/Song"]
+            assert list(by_model["origins"]) == ["minimax/Song"]
+
+            by_tag = client.get("/api/prompts?tag=Wildlife").json()
+            assert by_tag["prompts"] == ["minimax/Fox"]
+
+            # Both at once, and a miss is an empty listing rather than a 404
+            assert client.get(
+                "/api/prompts?tag=music&intended_model=minimax-h3"
+            ).json()["prompts"] == []
+
+            # The writable directory is reported whatever the filter
+            assert client.get("/api/prompts?tag=music").json()["prompt_dir"]
+```
+
+- [ ] **Step 2: Run the test to verify it fails**
+
+Run: `venv/bin/python -m pytest "tests/test_server.py::TestPromptLibrary::test_the_listing_narrows_by_tag_and_model_and_can_omit_the_text" -v`
+
+Expected: FAIL — `assert 'text' not in entry` (the route ignores the query
+string, so `include_text=false` still returns the text).
+
+- [ ] **Step 3: Implement the route change**
+
+Replace `dw/server/app.py:2160-2181` with:
+
+```python
+    @app.get("/api/prompts")
+    def list_prompts(
+        tag: str | None = None,
+        intended_model: str | None = None,
+        include_text: bool = True,
+    ):
+        # A stray file too deep or oddly named can sit in the directory, but
+        # no workflow could reference it - listing it would only invite that
+        paths = {}
+        origins = {}
+        roots = _prompt_roots()
+        for index, root in enumerate(roots):
+            for name in workflow_names(root):
+                if referenceable(name) and name not in paths:
+                    paths[name] = os.path.join(root, f"{name}.json")
+                    origins[name] = WORKSPACE_ORIGIN if index == 0 else EXAMPLES_ORIGIN
+        details = prompt_details(paths)
+
+        # Narrowing happens after the details are read, since that is where a
+        # prompt says what it is for, and it narrows every parallel key at
+        # once: a `prompts` list and a `details` map that disagree is worse
+        # than no filter at all
+        wanted = _matching_prompts(details, tag, intended_model)
+        if wanted is not None:
+            details = {name: detail for name, detail in details.items() if name in wanted}
+        # The three parallel keys agree by construction, filter or no filter.
+        # `prompt_details` drops a path whose mtime it cannot read - the file
+        # went away between the walk and the read - and listing a name that
+        # carries no detail only tells a caller to go and get a 404.
+        origins = {name: origin for name, origin in origins.items() if name in details}
+
+        # The MCP listing cannot carry 44 prompt bodies - it exceeds a client's
+        # result cap and the listing becomes uncallable - but the editors read
+        # `text` as the card fallback, so the omission is opt-in and the size
+        # is reported in its place
+        if not include_text:
+            details = {
+                name: {
+                    **{key: value for key, value in detail.items() if key != "text"},
+                    "text_chars": len(detail.get("text") or ""),
+                }
+                for name, detail in details.items()
+            }
+
+        return {
+            # The writable library, unchanged: what a save is written to,
+            # and what a client that predates the search path expects
+            "prompt_dir": app.state.prompt_dir,
+            "prompt_dirs": roots,
+            "prompts": sorted(details),
+            "origins": origins,
+            "details": details,
+        }
+```
+
+And add, immediately above the route (module level, beside `prompt_details`
+at `dw/server/app.py:485` is also fine — put it beside `prompt_details`):
+
+```python
+def _matching_prompts(details, tag, intended_model):
+    """The prompt names matching the filters, or None when there are none.
+
+    Case-insensitive and exact per value: a `tags` entry or the whole
+    `intended_model`, never a substring - `minimax-music` must not match
+    `minimax-music3`, which is the confusion the one-spelling-per-family
+    rule exists to prevent.
+    """
+    if tag is None and intended_model is None:
+        return None
+    wanted_tag = tag.lower() if tag is not None else None
+    wanted_model = intended_model.lower() if intended_model is not None else None
+    matches = set()
+    for name, detail in details.items():
+        if wanted_tag is not None and wanted_tag not in {
+            str(each).lower() for each in detail.get("tags") or []
+        }:
+            continue
+        if (
+            wanted_model is not None
+            and str(detail.get("intended_model") or "").lower() != wanted_model
+        ):
+            continue
+        matches.add(name)
+    return matches
+```
+
+- [ ] **Step 4: Run the tests to verify they pass**
+
+Run: `venv/bin/python -m pytest tests/test_server.py -k Prompt -q`
+
+Expected: PASS, including the pre-existing
+`test_save_prompt_roundtrip_and_confinement` which asserts `detail["text"]`
+on an unfiltered listing.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add dw/server/app.py tests/test_server.py
+git commit -m "feat(server): narrow the prompt listing, and let a caller drop the text
+
+The listing carried every prompt's whole body, which the editors need as a
+card fallback and an MCP client cannot afford - 44 prompts is 87 KB, past a
+client result cap, so the tool could not be called at all. include_text=false
+swaps each body for its length, and tag/intended_model narrow the names, the
+origins and the details together.
+
+Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>"
+```
+
+---
+
+### Task 2: MCP `list_prompts` stops carrying the bodies
+
+**Files:**
+- Modify: `dw_mcp/prompts.py:26-29` (the `list_prompts` handler)
+- Modify: `dw_mcp/server.py:897-901` (the tool wrapper and its docstring)
+- Modify: `dw_mcp/CLAUDE.md` (the `list_jobs` paragraph gains its sibling)
+- Test: `tests/test_mcp_prompts.py`
+
+**Interfaces:**
+- Consumes: Task 1's `GET /api/prompts?tag=&intended_model=&include_text=`.
+- Produces: `list_prompts(tag: str | None = None, intended_model: str | None = None, include_text: bool = False) -> dict`.
+  The handler signature is `list_prompts(client, tag=None, intended_model=None, include_text=False)`.
+  Task 5 quotes this signature in the guide and the skills.
+
+- [ ] **Step 1: Write the failing tests**
+
+Note that `scripted()` in this file keys on the request *path* only, so a
+query-string assertion reads `request.url.params`. Add a recorder that keeps
+them, and the tests, to `tests/test_mcp_prompts.py` after
+`test_list_prompts_returns_the_library`:
+
+```python
+def scripted_with_params(routes):
+    """`scripted`, keeping each request's query parameters."""
+    seen = []
+
+    def handler(request):
+        key = (request.method, request.url.path)
+        seen.append((key, dict(request.url.params)))
+        if key not in routes:
+            return httpx.Response(404, json={"detail": f"unrouted {key}"})
+        status, body = routes[key]
+        return httpx.Response(status, json=body)
+
+    return DwClient(transport=httpx.MockTransport(handler)), seen
+
+
+def test_list_prompts_asks_the_server_to_leave_the_bodies_out():
+    client, seen = scripted_with_params(
+        {("GET", "/api/prompts"): (200, {"prompts": [], "details": {}})}
+    )
+
+    prompts.list_prompts(client)
+
+    # The default is the cheap listing: a prompt body belongs in get_prompt,
+    # and 44 of them do not fit a client's result cap
+    assert seen[0][1]["include_text"] == "false"
+    assert "tag" not in seen[0][1]
+    assert "intended_model" not in seen[0][1]
+
+
+def test_list_prompts_forwards_the_filters_and_can_ask_for_the_text():
+    client, seen = scripted_with_params(
+        {("GET", "/api/prompts"): (200, {"prompts": [], "details": {}})}
+    )
+
+    prompts.list_prompts(
+        client, tag="ic-lora", intended_model="ltx-2.5", include_text=True
+    )
+
+    assert seen[0][1] == {
+        "tag": "ic-lora",
+        "intended_model": "ltx-2.5",
+        "include_text": "true",
+    }
+```
+
+- [ ] **Step 2: Run the tests to verify they fail**
+
+Run: `venv/bin/python -m pytest tests/test_mcp_prompts.py -k list_prompts -v`
+
+Expected: FAIL — `KeyError: 'include_text'`; the handler takes no parameters
+and sends no query string.
+
+- [ ] **Step 3: Implement the handler**
+
+Replace `dw_mcp/prompts.py:26-29` with:
+
+```python
+def list_prompts(client, tag=None, intended_model=None, include_text=False):
+    """The library as a routing table: what each prompt is for, not what it
+    says.
+
+    The bodies are left out by default, which is the same lesson `list_jobs`
+    learned - the whole library is 44 prompts and 87 KB, past a client's
+    result cap, so a listing that carried them could not be called at all.
+    `get_prompt` is where a body comes from once one has been chosen.
+    """
+    params = {"include_text": "true" if include_text else "false"}
+    if tag is not None:
+        params["tag"] = tag
+    if intended_model is not None:
+        params["intended_model"] = intended_model
+    return client.get_json("/api/prompts", params=params)
+```
+
+- [ ] **Step 4: Rewrite the tool wrapper**
+
+Replace `dw_mcp/server.py:897-901` with:
+
+```python
+    def list_prompts(
+        tag: Optional[str] = None,
+        intended_model: Optional[str] = None,
+        include_text: bool = False,
+    ) -> dict:
+        """List the stored prompts - the worked examples a workflow reaches
+        by writing "prompt:name" or "prompt:folder/name". Each entry carries
+        its `description`, `intended_model`, `tags` and the size of its text;
+        `get_prompt` returns the text itself. This is where the caption a
+        model was trained on is already written out, so read the exemplar
+        for the family you are about to run rather than inventing the
+        format: `intended_model` narrows to one family (`minimax-h3`,
+        `minimax-music3`, `ltx-2.5`, `z-image`, `flux`) and `tag` to one
+        label. `include_text=true` returns every body, which for the whole
+        library is more than a client will accept - filter first."""
+        return prompts.list_prompts(
+            client,
+            tag=tag,
+            intended_model=intended_model,
+            include_text=include_text,
+        )
+```
+
+- [ ] **Step 5: Run the MCP tests to verify they pass**
+
+Run: `venv/bin/python -m pytest tests/test_mcp_prompts.py tests/test_mcp_server.py -q`
+
+Expected: PASS. `test_mcp_server.py` asserts every tool has a non-empty
+description and that `list_prompts` is annotated read-only; both still hold.
+
+- [ ] **Step 6: Record it beside the `list_jobs` paragraph**
+
+In `dw_mcp/CLAUDE.md`, immediately after the sentence ending `...and it takes
+a `workspace` of its own to narrow by.`, add:
+
+```
+`list_prompts` had the same disease and the same cure: the library's 44
+prompts are 87 KB of prompt bodies, which no client will accept, so the
+listing asks for `include_text=false` and carries each prompt's
+`description`, `intended_model`, `tags` and `text_chars` instead - the
+routing table, with `get_prompt` for the one body that was chosen. It also
+forwards `tag` and `intended_model`, because the library is where the
+trained caption format for a family is already written out and the reason to
+read it is to find that one.
+```
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add dw_mcp/prompts.py dw_mcp/server.py dw_mcp/CLAUDE.md tests/test_mcp_prompts.py
+git commit -m "fix(mcp): list_prompts is callable again
+
+It returned every prompt's full text - 87 KB across 44 prompts - and was
+rejected outright by a client's result cap, so the library that holds the
+worked caption examples could not be listed at all. Same cure as list_jobs:
+ask the server for the routing table, with tag/intended_model to narrow and
+get_prompt for the body.
+
+Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>"
+```
+
+---
+
+### Task 3: one spelling per family in `intended_model`, swept
+
+Two repo prompts say `minimax-music` where the family is `minimax-music3`,
+so Task 2's `intended_model` filter would return half the Music 3 library.
+Three prompts declare nothing, which the schema allows and this task keeps
+allowing — the rule is *one spelling per family*, not *every prompt declares
+one*.
+
+**Files:**
+- Modify: `prompts/minimax/acoustic_pop_song.json`, `prompts/minimax/otter_soul_song.json`
+- Modify: `dw/prompt_schema.json:19-22` (the `intended_model` description)
+- Create: `tests/test_prompt_library.py`
+
+**Interfaces:**
+- Consumes: nothing from earlier tasks.
+- Produces: `INTENDED_MODELS` in `tests/test_prompt_library.py`, the vocabulary
+  the repo's own library is held to. Task 2's docstring already quotes the
+  same five values; keep them identical.
+
+- [ ] **Step 1: Write the failing test**
+
+Create `tests/test_prompt_library.py`:
+
+```python
+"""Conventions the whole prompt library is held to.
+
+`intended_model` is documented as informational, and it is - the engine
+ignores it. What it is not is free: `list_prompts(intended_model=...)`
+narrows by an exact match, so `minimax-music` beside `minimax-music3` is a
+filter that returns half a family and looks like it returned all of it. The
+sweep is the same shape `tests/test_observed_cost.py` uses for
+`cost_drivers`: a value that buckets on nothing looks exactly like a value
+that works.
+
+An empty `intended_model` is allowed. Some stored text is not written for a
+model at all - an enhancer's system prompt, a generic landscape - and
+inventing a family for it would be worse than saying nothing.
+"""
+
+import glob
+import json
+import os
+
+import pytest
+
+from tests.test_examples import REPO_ROOT
+
+PROMPT_DIR = os.path.join(REPO_ROOT, "prompts")
+
+# One spelling per family. Every value here is either a key the enhancer
+# presets preselect for (`intended_models` in dw/server/enhancers.py) or a
+# model family the catalog ships templates for.
+INTENDED_MODELS = frozenset(
+    {
+        "minimax-h3",
+        "minimax-music3",
+        "ltx-2.5",
+        "z-image",
+        "flux",
+    }
+)
+
+
+def prompt_files():
+    return sorted(glob.glob(os.path.join(PROMPT_DIR, "**", "*.json"), recursive=True))
+
+
+@pytest.mark.parametrize(
+    "path", prompt_files(), ids=lambda p: os.path.relpath(p, PROMPT_DIR)
+)
+def test_intended_model_is_one_of_the_known_families(path):
+    with open(path) as file:
+        definition = json.load(file)
+    declared = definition.get("intended_model")
+    if not declared:
+        return
+    assert declared in INTENDED_MODELS, (
+        f"{os.path.relpath(path, REPO_ROOT)} declares intended_model "
+        f"{declared!r}; list_prompts filters on an exact match, so a variant "
+        f"spelling hides the prompt from the family it belongs to. "
+        f"Known: {sorted(INTENDED_MODELS)}"
+    )
+
+
+def test_every_enhancer_preset_targets_a_known_family():
+    """The presets and the library share one vocabulary, or the editor
+    preselects a preset no prompt will ever match."""
+    from dw.server.enhancers import PRESETS
+
+    for key, preset in PRESETS.items():
+        for model in preset["intended_models"]:
+            assert model in INTENDED_MODELS, (
+                f"enhancer preset {key!r} targets {model!r}, which no prompt "
+                f"may declare"
+            )
+```
+
+- [ ] **Step 2: Run it to verify it fails**
+
+Run: `venv/bin/python -m pytest tests/test_prompt_library.py -q`
+
+Expected: 2 failures — `minimax/acoustic_pop_song.json` and
+`minimax/otter_soul_song.json` declare `'minimax-music'`.
+
+- [ ] **Step 3: Fix the two prompts**
+
+```bash
+cd /Users/don/src/dkackman/diffusers-workflow
+for f in prompts/minimax/acoustic_pop_song.json prompts/minimax/otter_soul_song.json; do
+  venv/bin/python - "$f" <<'PY'
+import json, sys
+path = sys.argv[1]
+with open(path) as file:
+    prompt = json.load(file)
+assert prompt["intended_model"] == "minimax-music", prompt["intended_model"]
+prompt["intended_model"] = "minimax-music3"
+with open(path, "w") as file:
+    json.dump(prompt, file, indent=2)
+    file.write("\n")
+PY
+done
+git diff --stat
+```
+
+- [ ] **Step 4: Document the rule where a prompt is written**
+
+In `dw/prompt_schema.json`, replace the `intended_model` description with:
+
+```json
+      "description": "The model or model family the prompt was written for, such as 'minimax-h3'. Informational - the engine ignores it - but one spelling per family: 'list_prompts' narrows by an exact match, so a variant hides the prompt from its own family. The repo's library is swept by tests/test_prompt_library.py. Leave it out for text written for no particular model."
+```
+
+- [ ] **Step 5: Run the tests to verify they pass**
+
+Run: `venv/bin/python -m pytest tests/test_prompt_library.py tests/test_prompts.py tests/test_ltx_prompt_library.py -q`
+
+Expected: PASS.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add prompts/minimax/acoustic_pop_song.json prompts/minimax/otter_soul_song.json \
+        dw/prompt_schema.json tests/test_prompt_library.py
+git commit -m "fix(prompts): one spelling per family in intended_model
+
+Two Music 3 captions said minimax-music and four said minimax-music3, which
+list_prompts' exact-match filter turns into a listing that returns half a
+family and looks complete. Swept, the way cost_drivers is: a value that
+buckets on nothing looks exactly like one that works. An absent value stays
+legal - an enhancer's system prompt is written for no family.
+
+Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>"
+```
+
+**Note for the executor:** the live server's workspace holds ~20 more prompts
+(`iron-bloom/*`, `tool-musical/*`, `slow-light/*`, `parhelion/*`) that are not
+in this repo, and two of them declare `minimax-music`. They are the user's
+data, not repo content; the sweep cannot reach them. Say so when reporting the
+task rather than trying to edit the box.
+
+---
+
+### Task 4: `has-audio` means a generated audio track, as it says
+
+`_derive_traits` promises "a speech task, a video pipeline asked for audio, or
+one carrying a component that exists only to synthesise a waveform", but the
+last two checks gate on `_kind(step) == "video"`, so `templates/minimax/music`
+— which generates and normalizes a 44.1 kHz track — does not carry the trait.
+`list_workflows(shape="audio", traits="has-audio")` returns only
+`templates/generate-speech`.
+
+**Files:**
+- Modify: `dw/server/catalog_shape.py:230-263` (`_derive_traits`)
+- Test: `tests/test_catalog_shape.py`
+
+**Interfaces:**
+- Consumes: `_generates(step)` and `_kind(step)` (`dw/server/catalog_shape.py:98`, `:91`), unchanged.
+- Produces: no signature change. Exactly one catalog entry gains a trait
+  (`templates/minimax/music`); verified in Step 5.
+
+- [ ] **Step 1: Write the failing test**
+
+Add to `tests/test_catalog_shape.py`:
+
+```python
+def test_a_generated_audio_track_carries_has_audio():
+    """A pipeline whose result is audio generates audio, whether or not a
+    video step is anywhere near it. The checks used to gate on video, so
+    Music 3's own template answered a `traits=has-audio` filter with
+    nothing - the one filter that names the thing it makes."""
+    definition = {
+        "id": "Song",
+        "steps": [
+            {
+                "name": "generate_music",
+                "pipeline": {
+                    "configuration": {"component_type": "ModularPipeline"},
+                    "from_pretrained_arguments": {"model_name": "MiniMaxAI/MiniMax-Music3"},
+                    "arguments": {"prompt": "variable:prompt"},
+                },
+                "result": {"content_type": "audio/mpeg"},
+            }
+        ],
+    }
+
+    metadata = derive_catalog_metadata(definition)
+
+    assert metadata["shape"] == "audio"
+    assert "has-audio" in metadata["traits"]
+
+
+def test_processing_a_supplied_track_does_not_claim_to_generate_one():
+    """`has-audio` says the workflow *makes* a track. Trimming one it was
+    handed is what `needs-input-media` is for."""
+    definition = {
+        "id": "Level",
+        "steps": [
+            {
+                "name": "balanced",
+                "task": {
+                    "command": "normalize_audio",
+                    "arguments": {"audio": "asset:song.mp3"},
+                },
+                "result": {"content_type": "audio/mpeg"},
+            }
+        ],
+    }
+
+    metadata = derive_catalog_metadata(definition)
+
+    assert "has-audio" not in metadata["traits"]
+    assert "needs-input-media" in metadata["traits"]
+```
+
+`derive_catalog_metadata` is already imported at the top of that file.
+
+- [ ] **Step 2: Run the tests to verify the first fails**
+
+Run: `venv/bin/python -m pytest tests/test_catalog_shape.py -k has_audio -v`
+
+Expected: `test_a_generated_audio_track_carries_has_audio` FAILS
+(`'has-audio' not in []`); `test_processing_a_supplied_track...` PASSES
+already, and is there to pin that the fix does not over-fire.
+
+- [ ] **Step 3: Fix the derivation**
+
+In `dw/server/catalog_shape.py`, in `_derive_traits`, add one clause inside
+the existing `for step in steps:` loop, immediately after the
+`generate_speech` clause:
+
+```python
+        # A pipeline whose own result is a waveform generates one. The three
+        # checks below it all ask about a *video* step that also carries
+        # audio, which left Music 3's template - the one entry in the catalog
+        # whose whole output is a track - answering a `has-audio` filter with
+        # nothing.
+        if _generates(step) and _kind(step) == "audio":
+            traits.add("has-audio")
+```
+
+Then correct the docstring's first line so it describes the code:
+
+```python
+    """The independent facts about how the output is made or what it needs.
+
+    `has-audio` says the workflow emits a generated audio track - a step
+    whose own result is a waveform, a speech task, a video pipeline asked
+    for audio, or one carrying a component that exists only to synthesise
+    one. Not specifically dialogue, and not a track the workflow was handed.
+    """
+```
+
+- [ ] **Step 4: Run the tests to verify they pass**
+
+Run: `venv/bin/python -m pytest tests/test_catalog_shape.py tests/test_catalog_structure.py -q`
+
+Expected: PASS. `test_the_compact_listing_fits_the_budget` still holds — one
+extra trait string on one entry.
+
+- [ ] **Step 5: Verify the blast radius is one entry**
+
+Run:
+
+```bash
+cd /Users/don/src/dkackman/diffusers-workflow && venv/bin/python -c "
+import json, glob
+from dw.server.catalog_shape import derive_catalog_metadata as derive
+for path in sorted(glob.glob('workflows/**/*.json', recursive=True)):
+    with open(path) as file:
+        traits = derive(json.load(file))['traits']
+    if 'has-audio' in traits:
+        print(path)
+"
+```
+
+Expected: the 40 entries that already carried it, **plus exactly one new line**
+`workflows/templates/minimax/music.json`. If any other entry appears, stop and
+report it — the clause is over-firing.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add dw/server/catalog_shape.py tests/test_catalog_shape.py
+git commit -m "fix(catalog): has-audio covers a workflow whose output is the track
+
+The three checks all gated on a video step, so templates/minimax/music -
+the one entry whose whole deliverable is a 44.1 kHz track - answered a
+traits=has-audio filter with nothing, while the docstring claimed it would
+match a component that exists only to synthesise a waveform. A step whose own
+result is audio now says so; a step that trims a supplied track still does not.
+
+Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>"
+```
+
+---
+
+### Task 5: the prompt library is named where every agent reads
+
+The library is the fallback for the one thing an MCP-only client cannot get
+from the catalog — the trained caption format. It belongs in the two
+engine-generic places every agent reads (the tool docstring, done in Task 2,
+and the authoring guide), with a one-line pointer in each skill.
+
+**Files:**
+- Modify: `docs/WORKFLOW_GUIDE.md` (the `asset:`/`prompt:` reference list in
+  *Authoring a workflow from an agent*)
+- Modify: `plugins/dw/skills/ltx-2.5/SKILL.md` (byte-accounted)
+- Modify: `plugins/dw/skills/minimax-h3/SKILL.md` (byte-accounted)
+- Modify: `plugins/dw/skills/minimax-music3/SKILL.md`
+- Test: `tests/test_plugin_skills.py`
+
+**Interfaces:**
+- Consumes: Task 2's `list_prompts(tag=, intended_model=, include_text=)` and
+  the unchanged `get_prompt(name)`. Quote those spellings exactly.
+- Produces: nothing later tasks consume.
+
+- [ ] **Step 1: Write the failing test**
+
+Add to `tests/test_plugin_skills.py`:
+
+```python
+@pytest.mark.parametrize(
+    "path", SKILLS, ids=lambda p: os.path.basename(os.path.dirname(p))
+)
+def test_a_skill_points_at_the_stored_exemplars(path):
+    """Every family's hardest input is its prompt format, and the library
+    already holds captions written to it. A skill that names the vendor's
+    spec and not the worked example leaves an agent inventing prose it
+    could have read - and `prompts/ltx2/` as a directory is unreachable
+    from a client that has the MCP and no checkout."""
+    text = skill_text(path)
+    assert "list_prompts" in text or "get_prompt" in text, (
+        f"{path} never names the prompt library; a filesystem path is not a "
+        f"call an MCP client can make"
+    )
+```
+
+- [ ] **Step 2: Run it to verify it fails**
+
+Run: `venv/bin/python -m pytest tests/test_plugin_skills.py -k stored_exemplars -v`
+
+Expected: 4 FAIL, one per skill.
+
+- [ ] **Step 3: Add the convention to the authoring guide**
+
+In `docs/WORKFLOW_GUIDE.md`, in *Authoring a workflow from an agent* →
+*References*, replace the `prompt:` bullet:
+
+```markdown
+- `prompt:` — `prompt:name` or `prompt:folder/name` is a stored prompt's
+  `text`, rooted at the prompt library. That text may not itself begin with any of these
+  prefixes; the engine rejects such a prompt rather than resolving twice.
+```
+
+with:
+
+```markdown
+- `prompt:` — `prompt:name` or `prompt:folder/name` is a stored prompt's
+  `text`, rooted at the prompt library. That text may not itself begin with any of these
+  prefixes; the engine rejects such a prompt rather than resolving twice.
+  The library is also the worked-example shelf: a template's default prompt
+  is usually a `prompt:` reference, and the text behind it is a caption
+  written to whatever spec that model was trained on. Before writing a
+  prompt for a family, read the one that is already there —
+  `list_prompts(intended_model="ltx-2.5")` for the shelf,
+  `get_prompt("ltx2/fox_dawn_choir")` for a body. The listing leaves the
+  bodies out by default and reports each one's `text_chars`; asking for all
+  of them at once is more than a client will accept.
+```
+
+- [ ] **Step 4: Point the LTX skill at the call instead of the directory (byte-accounted)**
+
+`plugins/dw/skills/ltx-2.5/SKILL.md` is 12,259 bytes — 29 to spare. In the
+`## Prompts` section, replace this sentence (59 bytes):
+
+```
+The stored prompts under
+`prompts/ltx2/` are written to it.
+```
+
+with (53 bytes):
+
+```
+The `ltx2/`
+stored prompts (`list_prompts`) follow it.
+```
+
+Net −6 bytes.
+
+- [ ] **Step 5: Point the H3 skill at the call (byte-accounted)**
+
+`plugins/dw/skills/minimax-h3/SKILL.md` is 12,276 bytes — 12 to spare, so
+this edit pays for itself twice over before it spends.
+
+First free 20 bytes in `## Prompts` item 2. Replace:
+
+```
+   for text- and frame-conditioned generation, and
+```
+
+with:
+
+```
+   for text and frame conditioning, and
+```
+
+(−12) and replace:
+
+```
+   for reference-conditioned generation.
+```
+
+with:
+
+```
+   for reference conditioning.
+```
+
+(−10). Then spend 14 on the warning, which is more useful pointing somewhere.
+Replace:
+
+```
+H3 wants Context-IR, MiniMax's own format. Do not invent it and do not
+paraphrase it from examples:
+```
+
+with:
+
+```
+H3 wants Context-IR, MiniMax's own format. Do not invent it and do not
+paraphrase it from `get_prompt` examples:
+```
+
+Net −8 bytes.
+
+- [ ] **Step 6: Point the Music 3 skill at the call**
+
+`plugins/dw/skills/minimax-music3/SKILL.md` is 10,572 bytes — 1,716 to spare.
+In `## Prompts`, replace item 3:
+
+```
+3. The concise one-paragraph form the templates' stored prompts use (genre,
+   BPM, key, emotional progression, listening scenario, production profile,
+   vocals, arrangement) is the model card's own example and works; the
+   three-heading form is for precise control.
+```
+
+with:
+
+```
+3. The concise one-paragraph form the templates' stored prompts use (genre,
+   BPM, key, emotional progression, listening scenario, production profile,
+   vocals, arrangement) is the model card's own example and works; the
+   three-heading form is for precise control. Both are on the shelf:
+   `list_prompts(intended_model="minimax-music3")` names them and
+   `get_prompt` reads one. Read the exemplar before writing a caption - it
+   is what the format looks like when it is right, which is not the same as
+   a source to paraphrase the rules from.
+```
+
+- [ ] **Step 7: Point the series skill at the cast's prompts**
+
+`plugins/dw/skills/series-episodes/SKILL.md` is 6,605 bytes — ample. At the end
+of `## 0. Draw the cast once, before episode 1`, add:
+
+```
+Save each portrait prompt with `save_prompt` under one folder for the series
+and reference it as `prompt:<series>/<character>` from every episode.
+`list_prompts(tag="<series>")` is then the cast list, and a character
+described the same way in episode 6 as in episode 1 is a reference rather
+than a paragraph retyped - which is the drift this skill exists to stop.
+```
+
+- [ ] **Step 8: Run the tests to verify they pass, and check the byte caps**
+
+```bash
+cd /Users/don/src/dkackman/diffusers-workflow
+venv/bin/python -m pytest tests/test_plugin_skills.py tests/test_docs_links.py -q
+for f in plugins/dw/skills/*/SKILL.md; do printf "%-46s %6d\n" "$f" $(wc -c < "$f"); done
+```
+
+Expected: PASS, and every skill ≤ 12288 bytes — `ltx-2.5` at 12,253 and
+`minimax-h3` at 12,268.
+
+- [ ] **Step 9: Commit**
+
+```bash
+git add docs/WORKFLOW_GUIDE.md plugins/dw/skills tests/test_plugin_skills.py
+git commit -m "docs: name the prompt library where an agent will read it
+
+The library holds captions written to each family's trained spec, and
+nothing an agent reads mentioned it: the guide described 'prompt:' as a
+reference convention without saying the shelf behind it is worth reading,
+and the LTX skill pointed at prompts/ltx2/ - a directory an MCP client with
+no checkout cannot list. Now the call is named in the guide and in every
+skill, and a test keeps it named.
+
+Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>"
+```
+
+---
+
+### Task 6: the plugin enumerates all four of its skills, pinned
+
+`series-episodes` ships, is tested and is invocable, and appears in none of the
+four places that list what the plugin teaches.
+
+**Files:**
+- Modify: `plugins/dw/README.md` (the skill table)
+- Modify: `plugins/dw/.claude-plugin/plugin.json` (`description`)
+- Modify: `.claude-plugin/marketplace.json` (the `dw` entry's `description`)
+- Modify: `CLAUDE.md:50-52`
+- Test: `tests/test_plugin_skills.py`
+
+**Interfaces:**
+- Consumes: `SKILLS` and `PLUGIN_DIR` (`tests/test_plugin_skills.py:21`, `:20`).
+- Produces: nothing later tasks consume.
+
+- [ ] **Step 1: Write the failing test**
+
+Add to `tests/test_plugin_skills.py`:
+
+```python
+@pytest.mark.parametrize(
+    "path", SKILLS, ids=lambda p: os.path.basename(os.path.dirname(p))
+)
+def test_a_skill_is_enumerated_where_the_plugin_describes_itself(path):
+    """A skill nobody lists is a capability nobody installs for. The four
+    documents that enumerate them drifted the moment a fourth skill shipped,
+    and the size and catalog tests glob the directory, so nothing noticed."""
+    name = os.path.basename(os.path.dirname(path))
+    for document in (
+        os.path.join(PLUGIN_DIR, "README.md"),
+        os.path.join(REPO_ROOT, "CLAUDE.md"),
+    ):
+        with open(document) as file:
+            assert name in file.read(), (
+                f"skill {name!r} is not named in "
+                f"{os.path.relpath(document, REPO_ROOT)}"
+            )
+```
+
+- [ ] **Step 2: Run it to verify it fails**
+
+Run: `venv/bin/python -m pytest tests/test_plugin_skills.py -k enumerated -v`
+
+Expected: 1 FAIL — `skill 'series-episodes' is not named in
+plugins/dw/README.md` (3 pass).
+
+- [ ] **Step 3: Add the table row**
+
+In `plugins/dw/README.md`, add after the `ltx-2.5` row:
+
+```markdown
+| `series-episodes` | A series rather than one generation: several episodes over one cast, each cut and scored from its own template runs. The five-beat recut-bed-match_levels-normalize-pair procedure, and the one step that must not be skipped or the cast drifts between episodes. |
+```
+
+- [ ] **Step 4: Widen the two descriptions**
+
+In `plugins/dw/.claude-plugin/plugin.json` and the `dw` entry of
+`.claude-plugin/marketplace.json`, replace the `description` value (it is the
+same string in both) with:
+
+```
+Compose MiniMax H3 video, MiniMax Music 3 and LTX-2.5 workflows over a dw MCP server, and cut a multi-episode series from them: which template fits which shape, the hard rules, cost, and how to judge the output. Prompt format comes from the vendors' own guides.
+```
+
+Also update `marketplace.json`'s top-level `description` from
+`"one composition skill per model family."` to
+`"a composition skill per model family, and one for cutting a series from them."`
+
+- [ ] **Step 5: Correct CLAUDE.md**
+
+Replace `CLAUDE.md:50-52`:
+
+```
+`.claude-plugin/marketplace.json` publishes the `dw` plugin in `plugins/dw/`: one
+composition skill per model family (`minimax-h3`, `minimax-music3`, `ltx-2.5`) that
+chooses a template for a request's shape and states the family's hard rules. Model
+```
+
+with:
+
+```
+`.claude-plugin/marketplace.json` publishes the `dw` plugin in `plugins/dw/`: one
+composition skill per model family (`minimax-h3`, `minimax-music3`, `ltx-2.5`) that
+chooses a template for a request's shape and states the family's hard rules, plus
+`series-episodes`, which is a shape above them - several episodes over one cast,
+each cut and scored from those templates' runs. Every skill the directory holds is
+named in `plugins/dw/README.md` and here, pinned by the same test. Model
+```
+
+- [ ] **Step 6: Run the tests to verify they pass**
+
+Run: `venv/bin/python -m pytest tests/test_plugin_skills.py -q && venv/bin/python -c "import json; [json.load(open(p)) for p in ('plugins/dw/.claude-plugin/plugin.json', '.claude-plugin/marketplace.json')]"`
+
+Expected: PASS, and both JSON files parse.
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add plugins/dw/README.md plugins/dw/.claude-plugin/plugin.json \
+        .claude-plugin/marketplace.json CLAUDE.md tests/test_plugin_skills.py
+git commit -m "docs(plugin): list series-episodes where the plugin describes itself
+
+It shipped, is tested and is invocable, and the README table, both plugin
+descriptions and CLAUDE.md all still said three skills - the size and catalog
+tests glob the directory, so nothing noticed a fourth. Pinned now: every skill
+directory must be named in the README and in CLAUDE.md.
+
+Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>"
+```
+
+---
+
+### Task 7: the tool count is the surface's, in both places that state it
+
+The README says 55. So does `get_guide`'s own docstring, where the number
+carries an argument — that a whole guide costs more to read than the surface
+costs to connect. Both drift every time a tool lands.
+
+**Files:**
+- Modify: `README.md:86`
+- Modify: `dw/server/guides.py` (the `get_guide` docstring, ~line 172)
+- Test: `tests/test_mcp_server.py`
+
+**Interfaces:**
+- Consumes: `EXPECTED_TOOLS` (`tests/test_mcp_server.py`), currently 57 names.
+- Produces: nothing later tasks consume.
+
+- [ ] **Step 1: Write the failing test**
+
+Add to `tests/test_mcp_server.py`:
+
+```python
+def test_the_stated_tool_count_is_the_registered_one():
+    """Two documents state the size of the surface: the README, where it is
+    the first claim made about it, and get_guide's docstring, where it carries
+    the argument that a whole guide costs more than connecting does. Both said
+    55 while 57 were registered, and nothing was checking either."""
+    import re
+
+    from tests.test_examples import REPO_ROOT
+
+    stated = {}
+    with open(os.path.join(REPO_ROOT, "README.md")) as file:
+        stated["README.md"] = re.search(r"The agent has (\d+) tools", file.read())
+    with open(os.path.join(REPO_ROOT, "dw", "server", "guides.py")) as file:
+        stated["dw/server/guides.py"] = re.search(r"(\d+)-tool MCP surface", file.read())
+
+    for where, found in stated.items():
+        assert found, f"{where} no longer states a tool count in the expected form"
+        assert int(found.group(1)) == len(EXPECTED_TOOLS), (
+            f"{where} says {found.group(1)} tools; {len(EXPECTED_TOOLS)} are registered"
+        )
+```
+
+- [ ] **Step 2: Run it to verify it fails**
+
+Run: `venv/bin/python -m pytest tests/test_mcp_server.py -k stated_tool_count -v`
+
+Expected: FAIL — `README.md says 55 tools; 57 are registered`.
+
+- [ ] **Step 3: Correct both**
+
+In `README.md:86`, replace `The agent has 55 tools covering the whole surface — the`
+with `The agent has 57 tools covering the whole surface — the`.
+
+In `dw/server/guides.py`, in the `get_guide` docstring, replace
+`more in one call than the entire 55-tool MCP surface costs to connect,`
+with
+`more in one call than the entire 57-tool MCP surface costs to connect,`.
+
+The claim itself still holds and is worth keeping: Task 9 measures the surface
+at 13,225 tokens against WORKFLOW_GUIDE's ~19.6k.
+
+- [ ] **Step 4: Run it to verify it passes**
+
+Run: `venv/bin/python -m pytest tests/test_mcp_server.py tests/test_server_guides.py -q`
+
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add README.md dw/server/guides.py tests/test_mcp_server.py
+git commit -m "docs: pin the stated tool count to the registered tools
+
+The README said 55 and so did get_guide's docstring, where the number carries
+the argument for serving a guide a section at a time; 57 are registered. Both
+are checked against EXPECTED_TOOLS now rather than maintained by hand.
+
+Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>"
+```
+
+---
+
+### Task 8: a served guide says how to turn a repo path into a catalog name
+
+The nine served guides hold 114 links of the form
+`[image-to-video.json](../workflows/templates/minimax/image-to-video.json)`
+(TASKS 48, RECIPES_24GB 22, WORKFLOW_GUIDE 21, the rest 23). They resolve for a
+reader with a checkout and dead-end for the MCP-only reader that
+`docs/AGENT_LOOP.md` defines as the tester role. Rewriting 114 links in prose
+people also read is the wrong fix; saying the rule once, on the payload that
+contains one, is the right one.
+
+**Files:**
+- Modify: `dw/server/guides.py`
+- Test: `tests/test_server_guides.py`
+
+**Interfaces:**
+- Consumes: the existing `get_guide` section extraction in `dw/server/guides.py`.
+- Produces: an extra `catalog_paths: str` key on a `GET /api/guides/{name}`
+  response whose served content contains a `workflows/....json` path. Absent
+  otherwise. `list_guides` is unchanged — the index carries no prose.
+
+- [ ] **Step 1: Write the failing tests**
+
+`tests/test_server_guides.py` tests the mechanism against the synthetic
+`checkout` fixture (`tmp_path` holding two tiny guides, `GUIDES` monkeypatched
+down to them) and the shipped text separately in `class TestTheRealDocs`. Both
+get a test.
+
+First give the fixture a section that links an example. Replace `TASKS_TEXT`
+at `tests/test_server_guides.py:20-23`:
+
+```python
+TASKS_TEXT = (
+    "# Tasks\n\n## Speech Generation\n\ngenerate_speech\n\n"
+    "## Frame Interpolation\n\ninterpolate_frames\n"
+)
+```
+
+with:
+
+```python
+TASKS_TEXT = (
+    "# Tasks\n\n## Speech Generation\n\ngenerate_speech\n\n"
+    "## Frame Interpolation\n\n"
+    "interpolate_frames - see [it](../workflows/templates/interpolate-frames.json)\n"
+)
+```
+
+Then add to `class TestFetching`:
+
+```python
+    def test_a_section_linking_an_example_says_how_to_reach_it(self, checkout):
+        """A guide's link to an example is a repo path. The reader these
+        guides exist for has no checkout - it has the MCP and nothing else -
+        so a payload holding such a path carries the translation rule, rather
+        than 114 links being rewritten in prose people read too."""
+        body = guides.get_guide("tasks", "Frame Interpolation")
+
+        # The note is one fixed sentence - it states the rule, it does not
+        # name the paths it saw
+        assert body["catalog_paths"] == guides.CATALOG_PATH_NOTE
+        assert "get_workflow" in body["catalog_paths"]
+
+    def test_a_section_linking_nothing_carries_no_note(self, checkout):
+        body = guides.get_guide("tasks", "Speech Generation")
+
+        assert "catalog_paths" not in body
+
+    def test_an_index_holding_a_path_is_noted_too(self, checkout):
+        """The index carries the guide's opening and its whole first section,
+        which is as able to link an example as any other."""
+        assert "catalog_paths" not in guides.get_guide("tasks")
+        assert "catalog_paths" in guides.get_guide("workflows")
+```
+
+The last assertion needs the fixture's `WORKFLOW_GUIDE.md` to link one. In the
+`checkout` fixture, replace:
+
+```python
+    (root / "docs" / "WORKFLOW_GUIDE.md").write_text("## Structure\n\nsteps\n")
+```
+
+with:
+
+```python
+    (root / "docs" / "WORKFLOW_GUIDE.md").write_text(
+        "## Structure\n\nsteps - as in workflows/templates/text-to-image.json\n"
+    )
+```
+
+And add to `class TestTheRealDocs`:
+
+```python
+    def test_the_tasks_guide_carries_the_catalog_path_note(self):
+        """TASKS.md links 48 example workflows by repo path - the most of any
+        served guide."""
+        body = guides.get_guide("tasks", "Examples")
+
+        assert "catalog_paths" in body
+```
+
+`## Examples` in the shipped `TASKS.md` holds 20 such paths as of this plan, so
+the assertion is sound; if it has been rewritten by then, pick another section
+`grep -n '^## ' docs/TASKS.md` shows that contains one, and name it in the test.
+
+- [ ] **Step 2: Run the tests to verify they fail**
+
+Run: `venv/bin/python -m pytest tests/test_server_guides.py -k "catalog_path or reach_it or noted" -v`
+
+Expected: the three positive assertions FAIL with `KeyError: 'catalog_paths'`;
+`test_a_section_linking_nothing_carries_no_note` passes already and is there to
+pin that the note does not attach unconditionally.
+
+- [ ] **Step 3: Implement the note**
+
+In `dw/server/guides.py`, add at module level beside `GUIDES`:
+
+```python
+# A doc's link to an example is a repo-relative path, which resolves for a
+# reader with a checkout and dead-ends for the one these guides are served
+# to: an agent holding the MCP and nothing else. Said once, on a payload
+# that contains such a path, rather than rewritten into 114 links in prose
+# that people read too.
+CATALOG_PATH_NOTE = (
+    "Paths like `workflows/templates/minimax/image-to-video.json` in this "
+    "text are repo-relative and are not served by this machine. The catalog "
+    "name is the part after `workflows/` with `.json` dropped - "
+    "`templates/minimax/image-to-video` - which is what `get_workflow`, "
+    "`validate_workflow`, `run_workflow` and a sub-workflow step's `path` "
+    "all take. Paths under `dw/workflows/` are the packaged built-ins a "
+    "sub-workflow names as `builtin:<file>.json`."
+)
+
+# The same shape tests/test_docs_links.py checks the targets of: the
+# lookbehind keeps `workflows/` as the start of the path, so `dw/workflows/`
+# and `tests/test_data/workflows/` do not match.
+_EXAMPLE_PATH = re.compile(r"(?<![\w/-])(?:\.\./)?workflows/[A-Za-z0-9_.\-/]+\.json")
+```
+
+Add the helper beside `_extract_section`:
+
+```python
+def _noted(body):
+    """The payload, with the repo-path rule attached when it holds one.
+
+    Attached to the body rather than woven into the guides because the same
+    markdown is read on GitHub and in an editor, where the links resolve.
+    """
+    if _EXAMPLE_PATH.search(body.get("content") or ""):
+        body["catalog_paths"] = CATALOG_PATH_NOTE
+    return body
+```
+
+`get_guide` has two return points — the index and a named section — and either
+can hold a path, so wrap both. Replace the body of `get_guide` after its
+docstring:
+
+```python
+    text = read_guide(name)
+    if section is None:
+        return _index(name, text)
+
+    found = _extract_section(text, section)
+    if found is None:
+        raise GuideError(
+            f"The '{name}' guide has no section '{section}'. Its sections are: "
+            f"{', '.join(_sections(text))}."
+        )
+    heading, content = found
+    return {"name": name, "section": heading, "content": content}
+```
+
+with:
+
+```python
+    text = read_guide(name)
+    if section is None:
+        return _noted(_index(name, text))
+
+    found = _extract_section(text, section)
+    if found is None:
+        raise GuideError(
+            f"The '{name}' guide has no section '{section}'. Its sections are: "
+            f"{', '.join(_sections(text))}."
+        )
+    heading, content = found
+    return _noted({"name": name, "section": heading, "content": content})
+```
+
+The route in `dw/server/app.py` returns `get_guide`'s dict as-is and needs no
+change; `dw_mcp/guides.py` proxies the route and needs none either.
+
+- [ ] **Step 4: Run the tests to verify they pass**
+
+Run: `venv/bin/python -m pytest tests/test_server_guides.py tests/test_mcp_guides.py tests/test_docs_links.py -q`
+
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add dw/server/guides.py tests/test_server_guides.py
+git commit -m "feat(guides): say how a repo path in a guide becomes a catalog name
+
+The nine served guides hold 114 links to example workflows as repo-relative
+paths. They resolve for a reader with a checkout; the reader these guides
+exist for has the MCP and nothing else, and follows one nowhere. A section
+that contains such a path now carries the translation rule, which is one
+sentence rather than 114 edits to prose people also read.
+
+Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>"
+```
+
+---
+
+### Task 9: the tool surface has a budget
+
+Connecting costs 13,225 tokens before any call: descriptions 9,013, input
+schemas 3,212, instructions 999. Nothing measures it, while the *catalog*
+listing — read once per session, not held for all of it — has had a documented
+ceiling since #101. This task adds the guard, not a reduction; the number to
+beat is the one measured here.
+
+**Files:**
+- Test: `tests/test_mcp_server.py`
+
+**Interfaces:**
+- Consumes: `tools_of(server_over(ok({})))` (`tests/test_mcp_server.py:147`).
+  Each `Tool` exposes `.description` and `.input_schema` (snake case — not
+  `inputSchema`).
+- Produces: `SURFACE_BUDGET` in `tests/test_mcp_server.py`.
+
+- [ ] **Step 1: Write the failing test**
+
+Add to `tests/test_mcp_server.py`:
+
+```python
+# Chars / 4, the way COMPACT_BUDGET in tests/test_catalog_structure.py is
+# measured. This is not a listing an agent chooses to read - it is resident
+# for the whole session before a single call, which is why it gets a ceiling
+# at all and why the catalog listing, read once, has had one since #101.
+# Measured 2026-09-19 at 13_225: descriptions 9_013, input schemas 3_212,
+# instructions 999. Set at 13_800, which is room for a tool or two and not
+# room for a second validate_workflow.
+# Worth knowing before raising it: four tools are a quarter of the
+# descriptions (validate_workflow 872, wait_for_job 583, list_workflows 540,
+# list_gallery 501), and validate_workflow's `plan.basis` taxonomy and
+# wait_for_job's stall-diagnosis paragraph are both restated in
+# WORKFLOW_GUIDE's "The loop" - which an agent fetches on demand. The
+# question to ask first is whether the second copy has to be the resident one.
+SURFACE_BUDGET = 13_800
+
+
+@pytest.mark.asyncio
+async def test_the_tool_surface_fits_the_budget():
+    tools = await tools_of(server_over(ok({})))
+    server = server_over(ok({}))
+
+    descriptions = sum(len(tool.description or "") for tool in tools.values())
+    schemas = sum(len(json.dumps(tool.input_schema or {})) for tool in tools.values())
+    instructions = len(getattr(server, "instructions", "") or "")
+    total = (descriptions + schemas + instructions) / 4
+
+    assert total <= SURFACE_BUDGET, (
+        f"the surface is {total:.0f} tokens resident before any call "
+        f"(descriptions {descriptions / 4:.0f}, schemas {schemas / 4:.0f}, "
+        f"instructions {instructions / 4:.0f})"
+    )
+```
+
+`json` and `os` are already imported in that file, and `@pytest.mark.asyncio`
+is the decorator its other async tests use. `Tool` exposes `.input_schema`, in
+snake case — `.inputSchema` raises `AttributeError` under the installed
+pydantic.
+
+- [ ] **Step 2: Run it and read the measurement**
+
+Run: `venv/bin/python -m pytest tests/test_mcp_server.py -k fits_the_budget -v -s`
+
+Expected: PASS at roughly 13,225 tokens. This test is a guard, not a red-green
+cycle — if it *fails* on the first run, Tasks 1–8 grew the surface past 13,800
+and the comment's log line must be updated with the new measurement and the
+reason, in the shape `COMPACT_BUDGET`'s comment uses.
+
+- [ ] **Step 3: Confirm the whole suite is green**
+
+Run: `venv/bin/python -m pytest tests/ -q -x`
+
+Expected: PASS. This is the first run of the full suite since Task 1; the
+changes to `dw/server/app.py`, `dw/server/catalog_shape.py` and the two JSON
+manifests are the ones most likely to have a consumer this plan did not name.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add tests/test_mcp_server.py
+git commit -m "test(mcp): put a ceiling on the resident tool surface
+
+Connecting costs 13,225 tokens before any call - 9,013 of descriptions,
+3,212 of input schemas, 999 of instructions - and nothing measured it, while
+the catalog listing an agent reads once has had a documented budget since
+#101. A guard at 13,800 with the measurement logged, so the next tool that
+lands states what it cost.
+
+Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>"
+```
+
+---
+
+## Deliberately out of scope
+
+- **Rewriting the 114 guide links.** Task 8 states the rule once instead. The
+  links resolve on GitHub and in an editor, which is the other half of their
+  audience.
+- **`knownIntendedModels` in `ui/src/lib/prompts.ts:87`** extends the
+  suggestion list with whatever values are *in use*, which is how a variant
+  spelling becomes a legitimate-looking suggestion. Task 3 removes the variant
+  from the repo but not the mechanism. Worth an issue, not this plan — it is a
+  UI affordance, and the filter that matters now has a swept vocabulary behind it.
+- **The live workspace's prompts.** ~20 prompts on `lem` are not in this repo;
+  two declare `minimax-music`. Task 3's note says to report rather than edit.
+- **Shrinking any tool description.** Task 9 measures and guards. Every line in
+  the four largest encodes a defect that actually landed, and deciding which
+  belongs in the resident copy versus the on-demand guide is a design question,
+  not a cleanup.
+- **A skill for Z-Image or Flux.** The catalog's nine `models/` entries are all
+  Flux and Z-Image, neither of which has a composition skill. Both are
+  single-step image shapes the catalog describes adequately; a skill would be
+  restating `list_workflows`.
+
+## Deploy
+
+Nothing here touches the worker, the engine's generation path or `ui/`, so the
+box needs a pull and a server restart, not a UI build:
+
+```bash
+ssh lem 'cd ~/diffusers-workflow && git pull && pkill -KILL -f dw.serve; \
+  nohup venv/bin/python -m dw.serve > ~/dw-serve.log 2>&1 & disown'
+```
+
+Then verify from a fresh shell that the two findings a client can see are
+closed:
+
+```bash
+# list_prompts answers at all, and narrows
+curl -sH "Authorization: Bearer $DW_API_TOKEN" \
+  'http://lem:8765/api/prompts?include_text=false&intended_model=minimax-music3' \
+  | venv/bin/python -c 'import json,sys; b=json.load(sys.stdin); print(len(json.dumps(b)), b["prompts"])'
+
+# has-audio finds the song
+curl -sH "Authorization: Bearer $DW_API_TOKEN" \
+  'http://lem:8765/api/workflows?shape=audio&traits=has-audio&view=compact' \
+  | venv/bin/python -c 'import json,sys; print(json.load(sys.stdin)["workflows"])'
+```
+
+Expected: the first prints a payload of a few kB and the four Music 3 prompt
+names; the second lists `templates/minimax/music` alongside
+`templates/generate-speech`.

From 11d312d26cb406b92d3db903392f9e423fc0caf3 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sat, 19 Sep 2026 17:05:06 -0500
Subject: [PATCH 49/77] feat(server): narrow the prompt listing, and let a
 caller drop the text

The listing carried every prompt's whole body, which the editors need as a
card fallback and an MCP client cannot afford - 44 prompts is 87 KB, past a
client result cap, so the tool could not be called at all. include_text=false
swaps each body for its length, and tag/intended_model narrow the names, the
origins and the details together.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 dw/server/app.py     | 66 +++++++++++++++++++++++++++++++++++++++++---
 tests/test_server.py | 58 ++++++++++++++++++++++++++++++++++++++
 2 files changed, 120 insertions(+), 4 deletions(-)

diff --git a/dw/server/app.py b/dw/server/app.py
index b44f75e6..554059d1 100644
--- a/dw/server/app.py
+++ b/dw/server/app.py
@@ -520,6 +520,33 @@ def prompt_details(paths):
     return details
 
 
+def _matching_prompts(details, tag, intended_model):
+    """The prompt names matching the filters, or None when there are none.
+
+    Case-insensitive and exact per value: a `tags` entry or the whole
+    `intended_model`, never a substring - `minimax-music` must not match
+    `minimax-music3`, which is the confusion the one-spelling-per-family
+    rule exists to prevent.
+    """
+    if tag is None and intended_model is None:
+        return None
+    wanted_tag = tag.lower() if tag is not None else None
+    wanted_model = intended_model.lower() if intended_model is not None else None
+    matches = set()
+    for name, detail in details.items():
+        if wanted_tag is not None and wanted_tag not in {
+            str(each).lower() for each in detail.get("tags") or []
+        }:
+            continue
+        if (
+            wanted_model is not None
+            and str(detail.get("intended_model") or "").lower() != wanted_model
+        ):
+            continue
+        matches.add(name)
+    return matches
+
+
 def resolve_prompt_name(prompt_dir, name, allow_create=False):
     """The on-disk path for a prompt name, confined to prompt_dir.
 
@@ -2158,7 +2185,11 @@ def _find_prompt(name):
         raise HTTPException(status_code=404, detail=f"Unknown prompt: {name}")
 
     @app.get("/api/prompts")
-    def list_prompts():
+    def list_prompts(
+        tag: str | None = None,
+        intended_model: str | None = None,
+        include_text: bool = True,
+    ):
         # A stray file too deep or oddly named can sit in the directory, but
         # no workflow could reference it - listing it would only invite that
         paths = {}
@@ -2169,15 +2200,42 @@ def list_prompts():
                 if referenceable(name) and name not in paths:
                     paths[name] = os.path.join(root, f"{name}.json")
                     origins[name] = WORKSPACE_ORIGIN if index == 0 else EXAMPLES_ORIGIN
-        names = sorted(paths)
+        details = prompt_details(paths)
+
+        # Narrowing happens after the details are read, since that is where a
+        # prompt says what it is for, and it narrows every parallel key at
+        # once: a `prompts` list and a `details` map that disagree is worse
+        # than no filter at all
+        wanted = _matching_prompts(details, tag, intended_model)
+        if wanted is not None:
+            details = {name: detail for name, detail in details.items() if name in wanted}
+        # The three parallel keys agree by construction, filter or no filter.
+        # `prompt_details` drops a path whose mtime it cannot read - the file
+        # went away between the walk and the read - and listing a name that
+        # carries no detail only tells a caller to go and get a 404.
+        origins = {name: origin for name, origin in origins.items() if name in details}
+
+        # The MCP listing cannot carry 44 prompt bodies - it exceeds a client's
+        # result cap and the listing becomes uncallable - but the editors read
+        # `text` as the card fallback, so the omission is opt-in and the size
+        # is reported in its place
+        if not include_text:
+            details = {
+                name: {
+                    **{key: value for key, value in detail.items() if key != "text"},
+                    "text_chars": len(detail.get("text") or ""),
+                }
+                for name, detail in details.items()
+            }
+
         return {
             # The writable library, unchanged: what a save is written to,
             # and what a client that predates the search path expects
             "prompt_dir": app.state.prompt_dir,
             "prompt_dirs": roots,
-            "prompts": names,
+            "prompts": sorted(details),
             "origins": origins,
-            "details": prompt_details(paths),
+            "details": details,
         }
 
     @app.put("/api/prompts/{name:path}")
diff --git a/tests/test_server.py b/tests/test_server.py
index d6966e99..7c73d968 100644
--- a/tests/test_server.py
+++ b/tests/test_server.py
@@ -2976,6 +2976,64 @@ def test_save_prompt_roundtrip_and_confinement(self, server, tmp_path):
                 assert response.status_code in (400, 404, 405), evasion
             assert not (tmp_path / "escape.json").exists()
 
+    def _store(self, client, name, prompt):
+        assert client.put(f"/api/prompts/{name}", json={"prompt": prompt}).status_code == 200
+
+    def test_the_listing_narrows_by_tag_and_model_and_can_omit_the_text(
+        self, server, tmp_path
+    ):
+        with server(success_script) as client:
+            self._store(
+                client,
+                "minimax/Song",
+                {
+                    "text": "Global Metadata\nbpm is 58.",
+                    "description": "a song",
+                    "intended_model": "minimax-music3",
+                    "tags": ["music", "score"],
+                },
+            )
+            self._store(
+                client,
+                "minimax/Fox",
+                {
+                    "text": "a red fox at dawn",
+                    "description": "a fox",
+                    "intended_model": "minimax-h3",
+                    "tags": ["wildlife"],
+                },
+            )
+
+            # A caller that passes nothing gets what it always got
+            plain = client.get("/api/prompts").json()
+            assert "minimax/Song" in plain["prompts"]
+            assert plain["details"]["minimax/Fox"]["text"] == "a red fox at dawn"
+            assert "text_chars" not in plain["details"]["minimax/Fox"]
+
+            # include_text=false swaps the payload for its size
+            slim = client.get("/api/prompts?include_text=false").json()
+            entry = slim["details"]["minimax/Fox"]
+            assert "text" not in entry
+            assert entry["text_chars"] == len("a red fox at dawn")
+            assert entry["description"] == "a fox"
+
+            # A filter narrows the names, the origins and the details together
+            by_model = client.get("/api/prompts?intended_model=MINIMAX-MUSIC3").json()
+            assert by_model["prompts"] == ["minimax/Song"]
+            assert list(by_model["details"]) == ["minimax/Song"]
+            assert list(by_model["origins"]) == ["minimax/Song"]
+
+            by_tag = client.get("/api/prompts?tag=Wildlife").json()
+            assert by_tag["prompts"] == ["minimax/Fox"]
+
+            # Both at once, and a miss is an empty listing rather than a 404
+            assert client.get(
+                "/api/prompts?tag=music&intended_model=minimax-h3"
+            ).json()["prompts"] == []
+
+            # The writable directory is reported whatever the filter
+            assert client.get("/api/prompts?tag=music").json()["prompt_dir"]
+
     def test_unreferenceable_names_are_refused(self, server, tmp_path):
         # A save the API accepted but no 'prompt:' reference could ever
         # load would be a trap - the name rule is enforced here too

From ccb27c8de0dff2427ecbf0a90ad6e760e242c523 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sat, 19 Sep 2026 17:09:50 -0500
Subject: [PATCH 50/77] fix(mcp): list_prompts is callable again

It returned every prompt's full text - 87 KB across 44 prompts - and was
rejected outright by a client's result cap, so the library that holds the
worked caption examples could not be listed at all. Same cure as list_jobs:
ask the server for the routing table, with tag/intended_model to narrow and
get_prompt for the body.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 dw_mcp/CLAUDE.md          |  8 +++++++
 dw_mcp/prompts.py         | 18 +++++++++++++---
 dw_mcp/server.py          | 26 +++++++++++++++++-----
 tests/test_mcp_prompts.py | 45 +++++++++++++++++++++++++++++++++++++++
 tests/test_mcp_server.py  |  1 +
 5 files changed, 90 insertions(+), 8 deletions(-)

diff --git a/dw_mcp/CLAUDE.md b/dw_mcp/CLAUDE.md
index 82e6a07e..a2f36cc6 100644
--- a/dw_mcp/CLAUDE.md
+++ b/dw_mcp/CLAUDE.md
@@ -31,6 +31,14 @@ listing spilled 176 entries past a client's tool-result limit and could not
 be called at all, so the tool asks the API for `limit`/`status`, reverses the
 oldest-first list the web UI polls, and reports `total` so a cut answer says
 it was cut, and it takes a `workspace` of its own to narrow by.
+`list_prompts` had the same disease and the same cure: the library's 44
+prompts are 87 KB of prompt bodies, which no client will accept, so the
+listing asks for `include_text=false` and carries each prompt's
+`description`, `intended_model`, `tags` and `text_chars` instead - the
+routing table, with `get_prompt` for the one body that was chosen. It also
+forwards `tag` and `intended_model`, because the library is where the
+trained caption format for a family is already written out and the reason to
+read it is to find that one.
 `run_workflow` and `validate_workflow` are the other two handlers that carry
 one: each takes an
 optional per-call `workspace` that `_scoped`'s `setdefault` lets win over the
diff --git a/dw_mcp/prompts.py b/dw_mcp/prompts.py
index 9d53af8d..f77d3c91 100644
--- a/dw_mcp/prompts.py
+++ b/dw_mcp/prompts.py
@@ -21,9 +21,21 @@
 )
 
 
-def list_prompts(client):
-    """Every prompt in the library, with the directory it lives in."""
-    return client.get_json("/api/prompts")
+def list_prompts(client, tag=None, intended_model=None, include_text=False):
+    """The library as a routing table: what each prompt is for, not what it
+    says.
+
+    The bodies are left out by default, which is the same lesson `list_jobs`
+    learned - the whole library is 44 prompts and 87 KB, past a client's
+    result cap, so a listing that carried them could not be called at all.
+    `get_prompt` is where a body comes from once one has been chosen.
+    """
+    params = {"include_text": "true" if include_text else "false"}
+    if tag is not None:
+        params["tag"] = tag
+    if intended_model is not None:
+        params["intended_model"] = intended_model
+    return client.get_json("/api/prompts", params=params)
 
 
 def get_prompt(client, name):
diff --git a/dw_mcp/server.py b/dw_mcp/server.py
index 5c738559..485f0aad 100644
--- a/dw_mcp/server.py
+++ b/dw_mcp/server.py
@@ -894,11 +894,27 @@ def delete_workflow(name: str) -> dict:
 
     # ------------------------------------------------------------- prompts
 
-    def list_prompts() -> dict:
-        """List the stored prompts, with their text and descriptions. A
-        workflow argument reaches one of these by writing
-        "prompt:name" or "prompt:folder/name"."""
-        return prompts.list_prompts(client)
+    def list_prompts(
+        tag: Optional[str] = None,
+        intended_model: Optional[str] = None,
+        include_text: bool = False,
+    ) -> dict:
+        """List the stored prompts - the worked examples a workflow reaches
+        by writing "prompt:name" or "prompt:folder/name". Each entry carries
+        its `description`, `intended_model`, `tags` and the size of its text;
+        `get_prompt` returns the text itself. This is where the caption a
+        model was trained on is already written out, so read the exemplar
+        for the family you are about to run rather than inventing the
+        format: `intended_model` narrows to one family (`minimax-h3`,
+        `minimax-music3`, `ltx-2.5`, `z-image`, `flux`) and `tag` to one
+        label. `include_text=true` returns every body, which for the whole
+        library is more than a client will accept - filter first."""
+        return prompts.list_prompts(
+            client,
+            tag=tag,
+            intended_model=intended_model,
+            include_text=include_text,
+        )
 
     def get_prompt(name: str) -> dict:
         """Get one stored prompt's full definition - its text, description,
diff --git a/tests/test_mcp_prompts.py b/tests/test_mcp_prompts.py
index 01707aa9..8b0563e0 100644
--- a/tests/test_mcp_prompts.py
+++ b/tests/test_mcp_prompts.py
@@ -61,6 +61,51 @@ def test_list_prompts_returns_the_library():
     assert seen == [("GET", "/api/prompts")]
 
 
+def scripted_with_params(routes):
+    """`scripted`, keeping each request's query parameters."""
+    seen = []
+
+    def handler(request):
+        key = (request.method, request.url.path)
+        seen.append((key, dict(request.url.params)))
+        if key not in routes:
+            return httpx.Response(404, json={"detail": f"unrouted {key}"})
+        status, body = routes[key]
+        return httpx.Response(status, json=body)
+
+    return DwClient(transport=httpx.MockTransport(handler)), seen
+
+
+def test_list_prompts_asks_the_server_to_leave_the_bodies_out():
+    client, seen = scripted_with_params(
+        {("GET", "/api/prompts"): (200, {"prompts": [], "details": {}})}
+    )
+
+    prompts.list_prompts(client)
+
+    # The default is the cheap listing: a prompt body belongs in get_prompt,
+    # and 44 of them do not fit a client's result cap
+    assert seen[0][1]["include_text"] == "false"
+    assert "tag" not in seen[0][1]
+    assert "intended_model" not in seen[0][1]
+
+
+def test_list_prompts_forwards_the_filters_and_can_ask_for_the_text():
+    client, seen = scripted_with_params(
+        {("GET", "/api/prompts"): (200, {"prompts": [], "details": {}})}
+    )
+
+    prompts.list_prompts(
+        client, tag="ic-lora", intended_model="ltx-2.5", include_text=True
+    )
+
+    assert seen[0][1] == {
+        "tag": "ic-lora",
+        "intended_model": "ltx-2.5",
+        "include_text": "true",
+    }
+
+
 def test_get_prompt_reads_one_by_name():
     client, seen = scripted({("GET", "/api/prompts/duke"): (200, PROMPT)})
 
diff --git a/tests/test_mcp_server.py b/tests/test_mcp_server.py
index 2cc046f4..a56b57f4 100644
--- a/tests/test_mcp_server.py
+++ b/tests/test_mcp_server.py
@@ -890,6 +890,7 @@ def refusing(request):
     "get_workflow": (catalog, "get_workflow"),
     "get_schema": (catalog, "get_schema"),
     "delete_output": (media, "delete_output"),
+    "list_prompts": (prompts, "list_prompts"),
 }
 
 

From 0f8838c2076cff1868fe69cd03e0edbf19ae66ba Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sat, 19 Sep 2026 17:14:09 -0500
Subject: [PATCH 51/77] fix(prompts): one spelling per family in intended_model

Two Music 3 captions said minimax-music and four said minimax-music3, which
list_prompts' exact-match filter turns into a listing that returns half a
family and looks complete. Swept, the way cost_drivers is: a value that
buckets on nothing looks exactly like one that works. An absent value stays
legal - an enhancer's system prompt is written for no family.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 dw/prompt_schema.json                  |  2 +-
 prompts/minimax/acoustic_pop_song.json |  2 +-
 prompts/minimax/otter_soul_song.json   |  2 +-
 tests/test_prompt_library.py           | 71 ++++++++++++++++++++++++++
 4 files changed, 74 insertions(+), 3 deletions(-)
 create mode 100644 tests/test_prompt_library.py

diff --git a/dw/prompt_schema.json b/dw/prompt_schema.json
index b58b9edb..664f4dc0 100644
--- a/dw/prompt_schema.json
+++ b/dw/prompt_schema.json
@@ -18,7 +18,7 @@
     },
     "intended_model": {
       "type": "string",
-      "description": "The model or model family the prompt was written for, such as 'minimax-h3'. Informational - the engine ignores it, but the library badges and filters by it and the enhancer uses it to preselect a preset."
+      "description": "The model or model family the prompt was written for, such as 'minimax-h3'. Informational - the engine ignores it - but one spelling per family: 'list_prompts' narrows by an exact match, so a variant hides the prompt from its own family. The repo's library is swept by tests/test_prompt_library.py. Leave it out for text written for no particular model."
     },
     "negative_prompt": {
       "type": "string",
diff --git a/prompts/minimax/acoustic_pop_song.json b/prompts/minimax/acoustic_pop_song.json
index cdde6da4..8df3b7d7 100644
--- a/prompts/minimax/acoustic_pop_song.json
+++ b/prompts/minimax/acoustic_pop_song.json
@@ -1,7 +1,7 @@
 {
   "text": "Genre: acoustic pop, folk-tinged. BPM: 96. Key: C major. Emotional progression: warm and intimate in the verses, lifting into an open, anthemic chorus. Listening scenario: solo reflective listening. Production profile: close, organic, minimal reverb. Vocals: soft female lead, close-mic breathy timbre, restrained delivery in verses; light stacked harmonies doubling the melody in the chorus. Arrangement: verses — fingerpicked banjo and electric piano, sparse and spacious. Chorus — brushed drums and upright bass enter, subtle string pad swells underneath. Groove stays gentle throughout; no heavy percussion. Outro returns to solo banjo and voice.",
   "description": "Folk-tinged acoustic pop spec: banjo and electric piano verses, anthemic chorus",
-  "intended_model": "minimax-music",
+  "intended_model": "minimax-music3",
   "tags": [
     "music",
     "folk-pop"
diff --git a/prompts/minimax/otter_soul_song.json b/prompts/minimax/otter_soul_song.json
index 3ead1715..c0ea27bc 100644
--- a/prompts/minimax/otter_soul_song.json
+++ b/prompts/minimax/otter_soul_song.json
@@ -1,7 +1,7 @@
 {
   "text": "Genre: retro soul jingle, doo-wop tinged. BPM: 92. Key: E-flat major. Emotional progression: warm and wry throughout, swelling on the hook. Listening scenario: a late-night variety show number. Production profile: vintage, close-mic, plate reverb, slightly warm tape saturation. Vocals: smooth male crooner lead, velvety and unhurried, small melisma on the hook. Arrangement: upright bass and brushed drums under electric piano, a two-note baritone sax riff answering each line, finger snaps on the backbeat. The hook lands twice and the last line is held.",
   "description": "Retro soul jingle spec (genre/BPM/key/arrangement) - the MusicVideo example's song",
-  "intended_model": "minimax-music",
+  "intended_model": "minimax-music3",
   "tags": [
     "music",
     "soul"
diff --git a/tests/test_prompt_library.py b/tests/test_prompt_library.py
new file mode 100644
index 00000000..dcf8ffe5
--- /dev/null
+++ b/tests/test_prompt_library.py
@@ -0,0 +1,71 @@
+"""Conventions the whole prompt library is held to.
+
+`intended_model` is documented as informational, and it is - the engine
+ignores it. What it is not is free: `list_prompts(intended_model=...)`
+narrows by an exact match, so `minimax-music` beside `minimax-music3` is a
+filter that returns half a family and looks like it returned all of it. The
+sweep is the same shape `tests/test_observed_cost.py` uses for
+`cost_drivers`: a value that buckets on nothing looks exactly like a value
+that works.
+
+An empty `intended_model` is allowed. Some stored text is not written for a
+model at all - an enhancer's system prompt, a generic landscape - and
+inventing a family for it would be worse than saying nothing.
+"""
+
+import glob
+import json
+import os
+
+import pytest
+
+from tests.test_examples import REPO_ROOT
+
+PROMPT_DIR = os.path.join(REPO_ROOT, "prompts")
+
+# One spelling per family. Every value here is either a key the enhancer
+# presets preselect for (`intended_models` in dw/server/enhancers.py) or a
+# model family the catalog ships templates for.
+INTENDED_MODELS = frozenset(
+    {
+        "minimax-h3",
+        "minimax-music3",
+        "ltx-2.5",
+        "z-image",
+        "flux",
+    }
+)
+
+
+def prompt_files():
+    return sorted(glob.glob(os.path.join(PROMPT_DIR, "**", "*.json"), recursive=True))
+
+
+@pytest.mark.parametrize(
+    "path", prompt_files(), ids=lambda p: os.path.relpath(p, PROMPT_DIR)
+)
+def test_intended_model_is_one_of_the_known_families(path):
+    with open(path) as file:
+        definition = json.load(file)
+    declared = definition.get("intended_model")
+    if not declared:
+        return
+    assert declared in INTENDED_MODELS, (
+        f"{os.path.relpath(path, REPO_ROOT)} declares intended_model "
+        f"{declared!r}; list_prompts filters on an exact match, so a variant "
+        f"spelling hides the prompt from the family it belongs to. "
+        f"Known: {sorted(INTENDED_MODELS)}"
+    )
+
+
+def test_every_enhancer_preset_targets_a_known_family():
+    """The presets and the library share one vocabulary, or the editor
+    preselects a preset no prompt will ever match."""
+    from dw.server.enhancers import PRESETS
+
+    for key, preset in PRESETS.items():
+        for model in preset["intended_models"]:
+            assert model in INTENDED_MODELS, (
+                f"enhancer preset {key!r} targets {model!r}, which no prompt "
+                f"may declare"
+            )

From 7b42e127417c5b62af2a4e57b55ce33b90ba5589 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sat, 19 Sep 2026 17:18:00 -0500
Subject: [PATCH 52/77] fix(catalog): has-audio covers a workflow whose output
 is the track

The three checks all gated on a video step, so templates/minimax/music -
the one entry whose whole deliverable is a 44.1 kHz track - answered a
traits=has-audio filter with nothing, while the docstring claimed it would
match a component that exists only to synthesise a waveform. A step whose own
result is audio now says so; a step that trims a supplied track still does not.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 dw/server/catalog_shape.py  | 14 ++++++++---
 tests/test_catalog_shape.py | 49 +++++++++++++++++++++++++++++++++++++
 2 files changed, 60 insertions(+), 3 deletions(-)

diff --git a/dw/server/catalog_shape.py b/dw/server/catalog_shape.py
index 3b06c79f..fd406dd6 100644
--- a/dw/server/catalog_shape.py
+++ b/dw/server/catalog_shape.py
@@ -230,9 +230,10 @@ def _derive_shape(steps, kind):
 def _derive_traits(steps):
     """The independent facts about how the output is made or what it needs.
 
-    `has-audio` says the workflow emits a generated audio track - a speech
-    task, a video pipeline asked for audio, or one carrying a component that
-    exists only to synthesise a waveform. Not specifically dialogue.
+    `has-audio` says the workflow emits a generated audio track - a step
+    whose own result is a waveform, a speech task, a video pipeline asked
+    for audio, or one carrying a component that exists only to synthesise
+    one. Not specifically dialogue, and not a track the workflow was handed.
     """
     traits = set()
     for step in steps:
@@ -240,6 +241,13 @@ def _derive_traits(steps):
         arguments = _arguments(step)
         if key == "task" and body.get("command") == "generate_speech":
             traits.add("has-audio")
+        # A pipeline whose own result is a waveform generates one. The three
+        # checks below it all ask about a *video* step that also carries
+        # audio, which left Music 3's template - the one entry in the catalog
+        # whose whole output is a track - answering a `has-audio` filter with
+        # nothing.
+        if _generates(step) and _kind(step) == "audio":
+            traits.add("has-audio")
         output = arguments.get("output")
         if _kind(step) == "video" and isinstance(output, list) and "audio" in output:
             traits.add("has-audio")
diff --git a/tests/test_catalog_shape.py b/tests/test_catalog_shape.py
index 5f5b6e46..520107bd 100644
--- a/tests/test_catalog_shape.py
+++ b/tests/test_catalog_shape.py
@@ -664,6 +664,55 @@ def test_an_image_pipeline_carrying_a_vocoder_does_not():
     assert "has-audio" not in derive_catalog_metadata(definition(step))["traits"]
 
 
+def test_a_generated_audio_track_carries_has_audio():
+    """A pipeline whose result is audio generates audio, whether or not a
+    video step is anywhere near it. The checks used to gate on video, so
+    Music 3's own template answered a `traits=has-audio` filter with
+    nothing - the one filter that names the thing it makes."""
+    definition = {
+        "id": "Song",
+        "steps": [
+            {
+                "name": "generate_music",
+                "pipeline": {
+                    "configuration": {"component_type": "ModularPipeline"},
+                    "from_pretrained_arguments": {"model_name": "MiniMaxAI/MiniMax-Music3"},
+                    "arguments": {"prompt": "variable:prompt"},
+                },
+                "result": {"content_type": "audio/mpeg"},
+            }
+        ],
+    }
+
+    metadata = derive_catalog_metadata(definition)
+
+    assert metadata["shape"] == "audio"
+    assert "has-audio" in metadata["traits"]
+
+
+def test_processing_a_supplied_track_does_not_claim_to_generate_one():
+    """`has-audio` says the workflow *makes* a track. Trimming one it was
+    handed is what `needs-input-media` is for."""
+    definition = {
+        "id": "Level",
+        "steps": [
+            {
+                "name": "balanced",
+                "task": {
+                    "command": "normalize_audio",
+                    "arguments": {"audio": "asset:song.mp3"},
+                },
+                "result": {"content_type": "audio/mpeg"},
+            }
+        ],
+    }
+
+    metadata = derive_catalog_metadata(definition)
+
+    assert "has-audio" not in metadata["traits"]
+    assert "needs-input-media" in metadata["traits"]
+
+
 def for_each_step(name, variable, arguments):
     return {
         "name": name,

From 0ca0abe6dd98a8028b2c8478c369d26b70d04560 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sat, 19 Sep 2026 17:23:27 -0500
Subject: [PATCH 53/77] docs: name the prompt library where an agent will read
 it

The library holds captions written to each family's trained spec, and
nothing an agent reads mentioned it: the guide described 'prompt:' as a
reference convention without saying the shelf behind it is worth reading,
and the LTX skill pointed at prompts/ltx2/ - a directory an MCP client with
no checkout cannot list. Now the call is named in the guide and in every
skill, and a test keeps it named.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 docs/WORKFLOW_GUIDE.md                     |  8 ++++++++
 plugins/dw/skills/ltx-2.5/SKILL.md         |  4 ++--
 plugins/dw/skills/minimax-h3/SKILL.md      |  6 +++---
 plugins/dw/skills/minimax-music3/SKILL.md  |  6 +++++-
 plugins/dw/skills/series-episodes/SKILL.md |  6 ++++++
 tests/test_plugin_skills.py                | 16 ++++++++++++++++
 6 files changed, 40 insertions(+), 6 deletions(-)

diff --git a/docs/WORKFLOW_GUIDE.md b/docs/WORKFLOW_GUIDE.md
index f600a0c7..d3fc24a8 100644
--- a/docs/WORKFLOW_GUIDE.md
+++ b/docs/WORKFLOW_GUIDE.md
@@ -291,6 +291,14 @@ for existence.
 - `prompt:` — `prompt:name` or `prompt:folder/name` is a stored prompt's
   `text`, rooted at the prompt library. That text may not itself begin with any of these
   prefixes; the engine rejects such a prompt rather than resolving twice.
+  The library is also the worked-example shelf: a template's default prompt
+  is usually a `prompt:` reference, and the text behind it is a caption
+  written to whatever spec that model was trained on. Before writing a
+  prompt for a family, read the one that is already there —
+  `list_prompts(intended_model="ltx-2.5")` for the shelf,
+  `get_prompt("ltx2/fox_dawn_choir")` for a body. The listing leaves the
+  bodies out by default and reports each one's `text_chars`; asking for all
+  of them at once is more than a client will accept.
 - `item:` — only inside a step that carries `for_each`: `item:` is the
   entry the member was made for, `item:field` one field of an object entry,
   spliced in whole whatever its type — a string, a number, a list of
diff --git a/plugins/dw/skills/ltx-2.5/SKILL.md b/plugins/dw/skills/ltx-2.5/SKILL.md
index 1224c61b..9230039b 100644
--- a/plugins/dw/skills/ltx-2.5/SKILL.md
+++ b/plugins/dw/skills/ltx-2.5/SKILL.md
@@ -94,8 +94,8 @@ present progressive, opening on the action, stating for every shot a shot
 type, a camera motion (say static when there is none) and a viewpoint, the
 soundscape interleaved with the action rather than appended, in plain
 observable words. For an image-conditioned clip describe only what changes
-from the image; restating it invites a scene cut. The stored prompts under
-`prompts/ltx2/` are written to it. The spec, from
+from the image; restating it invites a scene cut. The `ltx2/`
+stored prompts (`list_prompts`) follow it. The spec, from
 `diffusers.pipelines.ltx2.utils.LTX2_5_T2V_DEFAULT_SYSTEM_PROMPT` (the
 image-to-video variant, `LTX2_5_I2V_DEFAULT_SYSTEM_PROMPT`, adds the
 describe-only-changes rule):
diff --git a/plugins/dw/skills/minimax-h3/SKILL.md b/plugins/dw/skills/minimax-h3/SKILL.md
index 0185bf95..3816549e 100644
--- a/plugins/dw/skills/minimax-h3/SKILL.md
+++ b/plugins/dw/skills/minimax-h3/SKILL.md
@@ -131,7 +131,7 @@ read the `workflows` guide's authoring section first.
 ## Prompts
 
 H3 wants Context-IR, MiniMax's own format. Do not invent it and do not
-paraphrase it from examples:
+paraphrase it from `get_prompt` examples:
 
 1. If the `h3-prompt-writing` skill is installed (MiniMax ships it in
    https://github.com/MiniMax-AI/MiniMax-H3 under `skills/`), use it. If not,
@@ -141,9 +141,9 @@ paraphrase it from examples:
    without it.
 2. Else read the guides on the model card:
    https://huggingface.co/MiniMaxAI/MiniMax-H3/raw/main/docs/VIDEO_PROMPT_WRITING_GUIDE_base_en.md
-   for text- and frame-conditioned generation, and
+   for text and frame conditioning, and
    https://huggingface.co/MiniMaxAI/MiniMax-H3/raw/main/docs/VIDEO_PROMPT_WRITING_GUIDE_ref_en.md
-   for reference-conditioned generation.
+   for reference conditioning.
 3. Else run `templates/minimax/enhance-prompt` (or `-with-image`), whose
    built-in enhancer writes the format from those guides. Its `idea` is
    framed as `Task: T2VA. Duration: 5.17 seconds. Idea: ...`.
diff --git a/plugins/dw/skills/minimax-music3/SKILL.md b/plugins/dw/skills/minimax-music3/SKILL.md
index 0bb56537..30c75e53 100644
--- a/plugins/dw/skills/minimax-music3/SKILL.md
+++ b/plugins/dw/skills/minimax-music3/SKILL.md
@@ -118,7 +118,11 @@ from the templates' examples:
 3. The concise one-paragraph form the templates' stored prompts use (genre,
    BPM, key, emotional progression, listening scenario, production profile,
    vocals, arrangement) is the model card's own example and works; the
-   three-heading form is for precise control.
+   three-heading form is for precise control. Both are on the shelf:
+   `list_prompts(intended_model="minimax-music3")` names them and
+   `get_prompt` reads one. Read the exemplar before writing a caption - it
+   is what the format looks like when it is right, which is not the same as
+   a source to paraphrase the rules from.
 
 Lyrics carry the structure: tags for the sections, the words to sing under
 them, and nothing else. The tag list is the model card's "Fine-Grained Music
diff --git a/plugins/dw/skills/series-episodes/SKILL.md b/plugins/dw/skills/series-episodes/SKILL.md
index 9a12b38f..f53944ea 100644
--- a/plugins/dw/skills/series-episodes/SKILL.md
+++ b/plugins/dw/skills/series-episodes/SKILL.md
@@ -58,6 +58,12 @@ watched back to back. There is no engine check for "the same character
 looks the same" across separate runs; the fixed-asset reference is the only
 guard, so it has to be a deliberate, first step rather than an implicit one.
 
+Save each portrait prompt with `save_prompt` under one folder for the series
+and reference it as `prompt:<series>/<character>` from every episode.
+`list_prompts(tag="<series>")` is then the cast list, and a character
+described the same way in episode 6 as in episode 1 is a reference rather
+than a paragraph retyped - which is the drift this skill exists to stop.
+
 ## 1-5. Per episode: generate, then recut, bed, match_levels, normalize, pair
 
 Generate the episode's shots with `templates/minimax/dialogue-short` (or
diff --git a/tests/test_plugin_skills.py b/tests/test_plugin_skills.py
index c70aa0d4..4ac88b09 100644
--- a/tests/test_plugin_skills.py
+++ b/tests/test_plugin_skills.py
@@ -478,3 +478,19 @@ def test_the_h3_skill_names_each_cut_templates_final_step():
         assert f"`{finals[0]}`" in text, (
             f"the skill does not name {name}'s final step {finals[0]}"
         )
+
+
+@pytest.mark.parametrize(
+    "path", SKILLS, ids=lambda p: os.path.basename(os.path.dirname(p))
+)
+def test_a_skill_points_at_the_stored_exemplars(path):
+    """Every family's hardest input is its prompt format, and the library
+    already holds captions written to it. A skill that names the vendor's
+    spec and not the worked example leaves an agent inventing prose it
+    could have read - and `prompts/ltx2/` as a directory is unreachable
+    from a client that has the MCP and no checkout."""
+    text = skill_text(path)
+    assert "list_prompts" in text or "get_prompt" in text, (
+        f"{path} never names the prompt library; a filesystem path is not a "
+        f"call an MCP client can make"
+    )

From d43dbadeb74c13b4d030db84d54e68e2a1738987 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sat, 19 Sep 2026 17:27:58 -0500
Subject: [PATCH 54/77] docs(plugin): give the H3 skill a reason to read the
 exemplar, not only a warning

The Context-IR sentence named get_prompt only to warn an agent away from
paraphrasing, with no positive reason to call it - and a complete,
well-formed Context-IR caption already sits in the library unread. Now the
sentence points at the exemplar's shape and keeps the warning about the
rules in the same breath.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 plugins/dw/skills/minimax-h3/SKILL.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/plugins/dw/skills/minimax-h3/SKILL.md b/plugins/dw/skills/minimax-h3/SKILL.md
index 3816549e..25db2a8f 100644
--- a/plugins/dw/skills/minimax-h3/SKILL.md
+++ b/plugins/dw/skills/minimax-h3/SKILL.md
@@ -130,8 +130,8 @@ read the `workflows` guide's authoring section first.
 
 ## Prompts
 
-H3 wants Context-IR, MiniMax's own format. Do not invent it and do not
-paraphrase it from `get_prompt` examples:
+H3 wants Context-IR, MiniMax's own format. `get_prompt` shows the shape;
+the rules come from MiniMax, not from paraphrasing one:
 
 1. If the `h3-prompt-writing` skill is installed (MiniMax ships it in
    https://github.com/MiniMax-AI/MiniMax-H3 under `skills/`), use it. If not,

From 59f07e692832888822e858481a040dfd6b960708 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sat, 19 Sep 2026 17:31:12 -0500
Subject: [PATCH 55/77] docs(plugin): list series-episodes where the plugin
 describes itself

It shipped, is tested and is invocable, and the README table, both plugin
descriptions and CLAUDE.md all still said three skills - the size and catalog
tests glob the directory, so nothing noticed a fourth. Pinned now: every skill
directory must be named in the README and in CLAUDE.md.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 .claude-plugin/marketplace.json       |  4 ++--
 CLAUDE.md                             |  5 ++++-
 plugins/dw/.claude-plugin/plugin.json |  2 +-
 plugins/dw/README.md                  |  1 +
 tests/test_plugin_skills.py           | 19 +++++++++++++++++++
 5 files changed, 27 insertions(+), 4 deletions(-)

diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
index 46a9b5f0..6be93983 100644
--- a/.claude-plugin/marketplace.json
+++ b/.claude-plugin/marketplace.json
@@ -1,7 +1,7 @@
 {
     "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
     "name": "diffusers-workflow",
-    "description": "Skills for driving a diffusers-workflow server from Claude Code: one composition skill per model family.",
+    "description": "Skills for driving a diffusers-workflow server from Claude Code: a composition skill per model family, and one for cutting a series from them.",
     "owner": {
         "name": "Don Kackman"
     },
@@ -9,7 +9,7 @@
         {
             "name": "dw",
             "source": "./plugins/dw",
-            "description": "Compose MiniMax H3 video, MiniMax Music 3 and LTX-2.5 workflows over a dw MCP server: which template fits which shape, the hard rules, cost, and how to judge the output. Prompt format comes from the vendors' own guides."
+            "description": "Compose MiniMax H3 video, MiniMax Music 3 and LTX-2.5 workflows over a dw MCP server, and cut a multi-episode series from them: which template fits which shape, the hard rules, cost, and how to judge the output. Prompt format comes from the vendors' own guides."
         }
     ]
 }
diff --git a/CLAUDE.md b/CLAUDE.md
index 21611686..4fe9d138 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -49,7 +49,10 @@ The stdio MCP server lives in `dw_mcp/` — see `dw_mcp/CLAUDE.md` and docs/MCP.
 
 `.claude-plugin/marketplace.json` publishes the `dw` plugin in `plugins/dw/`: one
 composition skill per model family (`minimax-h3`, `minimax-music3`, `ltx-2.5`) that
-chooses a template for a request's shape and states the family's hard rules. Model
+chooses a template for a request's shape and states the family's hard rules, plus
+`series-episodes`, which is a shape above them - several episodes over one cast,
+each cut and scored from those templates' runs. Every skill the directory holds is
+named in `plugins/dw/README.md` and here, pinned by the same test. Model
 knowledge lives there and in the catalog, never in engine code; every number a skill
 states is pinned to a diffusers symbol by `tests/test_plugin_skills.py`. `plugin.json`'s
 version is the engine's, bumped by `scripts/release.sh`. Adding or re-auditing a family
diff --git a/plugins/dw/.claude-plugin/plugin.json b/plugins/dw/.claude-plugin/plugin.json
index 31b1ff39..03deb6e0 100644
--- a/plugins/dw/.claude-plugin/plugin.json
+++ b/plugins/dw/.claude-plugin/plugin.json
@@ -1,6 +1,6 @@
 {
     "name": "dw",
-    "description": "Compose MiniMax H3 video, MiniMax Music 3 and LTX-2.5 workflows over a dw MCP server: which template fits which shape, the hard rules, cost, and how to judge the output. Prompt format comes from the vendors' own guides.",
+    "description": "Compose MiniMax H3 video, MiniMax Music 3 and LTX-2.5 workflows over a dw MCP server, and cut a multi-episode series from them: which template fits which shape, the hard rules, cost, and how to judge the output. Prompt format comes from the vendors' own guides.",
     "version": "0.4.0-beta.6",
     "author": {
         "name": "Don Kackman"
diff --git a/plugins/dw/README.md b/plugins/dw/README.md
index 9478346b..8df235ac 100644
--- a/plugins/dw/README.md
+++ b/plugins/dw/README.md
@@ -18,6 +18,7 @@ Install once, from Claude Code:
 | `minimax-h3` | MiniMax H3 video with audio: one take, a longer take by chain, a piece with cuts, identity and voice references, music; the frame and canvas rules; what a run costs. Prompts come from MiniMax's own `h3-prompt-writing` skill or the guides on the model card. |
 | `minimax-music3` | MiniMax Music 3: a song, an instrumental, a score under a film, the soundtrack a music video is cut to; the ceiling semantics, the tag vocabulary, the caps and the 44.1 kHz output. Captions come from MiniMax's own `music-caption-rewriter` skill. |
 | `ltx-2.5` | LTX-2.5 video with a soundtrack: a single clip, first-frame and keyframe conditioning, the three-move two-stage flow, the IC-LoRA upscale, extend and chain; the distilled schedule and the frame and size rules. Prompts follow the trained-caption spec that ships inside diffusers. |
+| `series-episodes` | A series rather than one generation: several episodes over one cast, each cut and scored from its own template runs. The five-beat recut-bed-match_levels-normalize-pair procedure, and the one step that must not be skipped or the cast drifts between episodes. |
 
 The two MiniMax skills defer the prompt format to MiniMax's own skills and
 fetch the vendor's guides when those are absent, so nothing else is required.
diff --git a/tests/test_plugin_skills.py b/tests/test_plugin_skills.py
index 4ac88b09..0e114d11 100644
--- a/tests/test_plugin_skills.py
+++ b/tests/test_plugin_skills.py
@@ -494,3 +494,22 @@ def test_a_skill_points_at_the_stored_exemplars(path):
         f"{path} never names the prompt library; a filesystem path is not a "
         f"call an MCP client can make"
     )
+
+
+@pytest.mark.parametrize(
+    "path", SKILLS, ids=lambda p: os.path.basename(os.path.dirname(p))
+)
+def test_a_skill_is_enumerated_where_the_plugin_describes_itself(path):
+    """A skill nobody lists is a capability nobody installs for. The four
+    documents that enumerate them drifted the moment a fourth skill shipped,
+    and the size and catalog tests glob the directory, so nothing noticed."""
+    name = os.path.basename(os.path.dirname(path))
+    for document in (
+        os.path.join(PLUGIN_DIR, "README.md"),
+        os.path.join(REPO_ROOT, "CLAUDE.md"),
+    ):
+        with open(document) as file:
+            assert name in file.read(), (
+                f"skill {name!r} is not named in "
+                f"{os.path.relpath(document, REPO_ROOT)}"
+            )

From f94291640adf03e8acd44bd25634b60cd9012efa Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sat, 19 Sep 2026 17:32:07 -0500
Subject: [PATCH 56/77] docs: pin the stated tool count to the registered tools

The README said 55 and so did get_guide's docstring, where the number carries
the argument for serving a guide a section at a time; 57 are registered. Both
are checked against EXPECTED_TOOLS now rather than maintained by hand.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 README.md                |  2 +-
 dw/server/guides.py      |  2 +-
 tests/test_mcp_server.py | 22 ++++++++++++++++++++++
 3 files changed, 24 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 12a62a8a..b42bdfd6 100644
--- a/README.md
+++ b/README.md
@@ -83,7 +83,7 @@ once; without it the run fails partway through with a 401/403 from the Hub.
 
 ## Drive it from an agent
 
-Then just ask. The agent has 55 tools covering the whole surface — the
+Then just ask. The agent has 57 tools covering the whole surface — the
 workflow catalog, the real diffusers pipeline signatures, the job queue, the
 gallery, the model cache:
 
diff --git a/dw/server/guides.py b/dw/server/guides.py
index d0660e48..1ee70c7b 100644
--- a/dw/server/guides.py
+++ b/dw/server/guides.py
@@ -169,7 +169,7 @@ def get_guide(name, section=None):
     Without a `section` the answer is the *index*: the guide's preamble,
     its first section, and the headings of the rest - not the whole file.
     A full WORKFLOW_GUIDE.md is ~19.6k tokens and TASKS.md ~16k, which is
-    more in one call than the entire 55-tool MCP surface costs to connect,
+    more in one call than the entire 57-tool MCP surface costs to connect,
     and an agent can make that call twice before noticing (#101). Every
     withheld section is named in `sections` and fetched by name, so
     nothing is unreachable - only unspent by accident.
diff --git a/tests/test_mcp_server.py b/tests/test_mcp_server.py
index a56b57f4..e1953b98 100644
--- a/tests/test_mcp_server.py
+++ b/tests/test_mcp_server.py
@@ -1065,3 +1065,25 @@ async def test_validate_workflow_teaches_quoting_from_the_plan():
     assert "downloads_required" in doc
     assert "estimate" in doc
     assert "basis" in doc
+
+
+def test_the_stated_tool_count_is_the_registered_one():
+    """Two documents state the size of the surface: the README, where it is
+    the first claim made about it, and get_guide's docstring, where it carries
+    the argument that a whole guide costs more than connecting does. Both said
+    55 while 57 were registered, and nothing was checking either."""
+    import re
+
+    from tests.test_examples import REPO_ROOT
+
+    stated = {}
+    with open(os.path.join(REPO_ROOT, "README.md")) as file:
+        stated["README.md"] = re.search(r"The agent has (\d+) tools", file.read())
+    with open(os.path.join(REPO_ROOT, "dw", "server", "guides.py")) as file:
+        stated["dw/server/guides.py"] = re.search(r"(\d+)-tool MCP surface", file.read())
+
+    for where, found in stated.items():
+        assert found, f"{where} no longer states a tool count in the expected form"
+        assert int(found.group(1)) == len(EXPECTED_TOOLS), (
+            f"{where} says {found.group(1)} tools; {len(EXPECTED_TOOLS)} are registered"
+        )

From 8a99ab2854d51118b96b12a1825dd8b5bfefc9e9 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sat, 19 Sep 2026 17:36:23 -0500
Subject: [PATCH 57/77] feat(guides): say how a repo path in a guide becomes a
 catalog name

The nine served guides hold 114 links to example workflows as repo-relative
paths. They resolve for a reader with a checkout; the reader these guides
exist for has the MCP and nothing else, and follows one nowhere. A section
that contains such a path now carries the translation rule, which is one
sentence rather than 114 edits to prose people also read.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 dw/server/guides.py         | 35 +++++++++++++++++++++++++++++--
 tests/test_server_guides.py | 42 ++++++++++++++++++++++++++++++++++---
 2 files changed, 72 insertions(+), 5 deletions(-)

diff --git a/dw/server/guides.py b/dw/server/guides.py
index 1ee70c7b..faffb8a6 100644
--- a/dw/server/guides.py
+++ b/dw/server/guides.py
@@ -80,6 +80,26 @@
 # better reached by reading the section they sit in
 SECTION_PATTERN = re.compile(r"^## (.+)$", re.M)
 
+# A doc's link to an example is a repo-relative path, which resolves for a
+# reader with a checkout and dead-ends for the one these guides are served
+# to: an agent holding the MCP and nothing else. Said once, on a payload
+# that contains such a path, rather than rewritten into 114 links in prose
+# that people read too.
+CATALOG_PATH_NOTE = (
+    "Paths like `workflows/templates/minimax/image-to-video.json` in this "
+    "text are repo-relative and are not served by this machine. The catalog "
+    "name is the part after `workflows/` with `.json` dropped - "
+    "`templates/minimax/image-to-video` - which is what `get_workflow`, "
+    "`validate_workflow`, `run_workflow` and a sub-workflow step's `path` "
+    "all take. Paths under `dw/workflows/` are the packaged built-ins a "
+    "sub-workflow names as `builtin:<file>.json`."
+)
+
+# The same shape tests/test_docs_links.py checks the targets of: the
+# lookbehind keeps `workflows/` as the start of the path, so `dw/workflows/`
+# and `tests/test_data/workflows/` do not match.
+_EXAMPLE_PATH = re.compile(r"(?<![\w/-])(?:\.\./)?workflows/[A-Za-z0-9_.\-/]+\.json")
+
 
 class GuideError(LookupError):
     """A guide or section that does not exist. The message names what does,
@@ -148,6 +168,17 @@ def _extract_section(text, section):
     return None
 
 
+def _noted(body):
+    """The payload, with the repo-path rule attached when it holds one.
+
+    Attached to the body rather than woven into the guides because the same
+    markdown is read on GitHub and in an editor, where the links resolve.
+    """
+    if _EXAMPLE_PATH.search(body.get("content") or ""):
+        body["catalog_paths"] = CATALOG_PATH_NOTE
+    return body
+
+
 def list_guides():
     """Every guide, with what it covers and the sections it holds."""
     listed = []
@@ -176,7 +207,7 @@ def get_guide(name, section=None):
     """
     text = read_guide(name)
     if section is None:
-        return _index(name, text)
+        return _noted(_index(name, text))
 
     found = _extract_section(text, section)
     if found is None:
@@ -185,7 +216,7 @@ def get_guide(name, section=None):
             f"{', '.join(_sections(text))}."
         )
     heading, content = found
-    return {"name": name, "section": heading, "content": content}
+    return _noted({"name": name, "section": heading, "content": content})
 
 
 def _index(name, text):
diff --git a/tests/test_server_guides.py b/tests/test_server_guides.py
index 8d22dcea..570ca4b5 100644
--- a/tests/test_server_guides.py
+++ b/tests/test_server_guides.py
@@ -19,7 +19,8 @@
 
 TASKS_TEXT = (
     "# Tasks\n\n## Speech Generation\n\ngenerate_speech\n\n"
-    "## Frame Interpolation\n\ninterpolate_frames\n"
+    "## Frame Interpolation\n\n"
+    "interpolate_frames - see [it](../workflows/templates/interpolate-frames.json)\n"
 )
 
 
@@ -30,7 +31,9 @@ def checkout(tmp_path, monkeypatch):
     root = tmp_path / "checkout"
     (root / "docs").mkdir(parents=True)
     (root / "docs" / "TASKS.md").write_text(TASKS_TEXT)
-    (root / "docs" / "WORKFLOW_GUIDE.md").write_text("## Structure\n\nsteps\n")
+    (root / "docs" / "WORKFLOW_GUIDE.md").write_text(
+        "## Structure\n\nsteps - as in workflows/templates/text-to-image.json\n"
+    )
     monkeypatch.setattr(guides, "__file__", str(root / "dw" / "server" / "guides.py"))
     monkeypatch.setattr(
         guides,
@@ -131,7 +134,10 @@ def test_one_section_comes_back_alone_with_its_heading(self, checkout):
     def test_the_last_section_runs_to_the_end_of_the_file(self, checkout):
         guide = guides.get_guide("tasks", section="Frame Interpolation")
 
-        assert guide["content"] == "## Frame Interpolation\n\ninterpolate_frames\n"
+        assert guide["content"] == (
+            "## Frame Interpolation\n\n"
+            "interpolate_frames - see [it](../workflows/templates/interpolate-frames.json)\n"
+        )
 
     def test_a_section_name_need_not_match_case_or_spacing(self, checkout):
         # An agent reproduces a heading from the listing loosely -
@@ -141,6 +147,29 @@ def test_a_section_name_need_not_match_case_or_spacing(self, checkout):
 
         assert guide["section"] == "Speech Generation"
 
+    def test_a_section_linking_an_example_says_how_to_reach_it(self, checkout):
+        """A guide's link to an example is a repo path. The reader these
+        guides exist for has no checkout - it has the MCP and nothing else -
+        so a payload holding such a path carries the translation rule, rather
+        than 114 links being rewritten in prose people read too."""
+        body = guides.get_guide("tasks", "Frame Interpolation")
+
+        # The note is one fixed sentence - it states the rule, it does not
+        # name the paths it saw
+        assert body["catalog_paths"] == guides.CATALOG_PATH_NOTE
+        assert "get_workflow" in body["catalog_paths"]
+
+    def test_a_section_linking_nothing_carries_no_note(self, checkout):
+        body = guides.get_guide("tasks", "Speech Generation")
+
+        assert "catalog_paths" not in body
+
+    def test_an_index_holding_a_path_is_noted_too(self, checkout):
+        """The index carries the guide's opening and its whole first section,
+        which is as able to link an example as any other."""
+        assert "catalog_paths" not in guides.get_guide("tasks")
+        assert "catalog_paths" in guides.get_guide("workflows")
+
 
 class TestErrors:
     def test_an_unknown_guide_names_the_ones_that_exist(self, checkout):
@@ -210,6 +239,13 @@ def test_the_authoring_section_states_the_cartesian_rule_and_the_loop(self):
         ):
             assert f"`{shape}`" in content, shape
 
+    def test_the_tasks_guide_carries_the_catalog_path_note(self):
+        """TASKS.md links 48 example workflows by repo path - the most of any
+        served guide."""
+        body = guides.get_guide("tasks", "Examples")
+
+        assert "catalog_paths" in body
+
 
 @pytest.fixture
 def client(tmp_path, checkout):

From 81a1c189a8520d6c597ca5a54ad6fb6ab72467a9 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sat, 19 Sep 2026 17:43:10 -0500
Subject: [PATCH 58/77] test(mcp): put a ceiling on the resident tool surface

Connecting costs 13,225 tokens before any call - 9,013 of descriptions,
3,212 of input schemas, 999 of instructions - and nothing measured it, while
the catalog listing an agent reads once has had a documented budget since
#101. A guard at 13,800 with the measurement logged, so the next tool that
lands states what it cost.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 tests/test_mcp_server.py | 33 +++++++++++++++++++++++++++++++++
 1 file changed, 33 insertions(+)

diff --git a/tests/test_mcp_server.py b/tests/test_mcp_server.py
index e1953b98..4fb82a33 100644
--- a/tests/test_mcp_server.py
+++ b/tests/test_mcp_server.py
@@ -1087,3 +1087,36 @@ def test_the_stated_tool_count_is_the_registered_one():
         assert int(found.group(1)) == len(EXPECTED_TOOLS), (
             f"{where} says {found.group(1)} tools; {len(EXPECTED_TOOLS)} are registered"
         )
+
+
+# Chars / 4, the way COMPACT_BUDGET in tests/test_catalog_structure.py is
+# measured. This is not a listing an agent chooses to read - it is resident
+# for the whole session before a single call, which is why it gets a ceiling
+# at all and why the catalog listing, read once, has had one since #101.
+# Measured 2026-09-19 at 13_225: descriptions 9_013, input schemas 3_212,
+# instructions 999. Set at 13_800, which is room for a tool or two and not
+# room for a second validate_workflow.
+# Worth knowing before raising it: four tools are a quarter of the
+# descriptions (validate_workflow 872, wait_for_job 583, list_workflows 540,
+# list_gallery 501), and validate_workflow's `plan.basis` taxonomy and
+# wait_for_job's stall-diagnosis paragraph are both restated in
+# WORKFLOW_GUIDE's "The loop" - which an agent fetches on demand. The
+# question to ask first is whether the second copy has to be the resident one.
+SURFACE_BUDGET = 13_800
+
+
+@pytest.mark.asyncio
+async def test_the_tool_surface_fits_the_budget():
+    tools = await tools_of(server_over(ok({})))
+    server = server_over(ok({}))
+
+    descriptions = sum(len(tool.description or "") for tool in tools.values())
+    schemas = sum(len(json.dumps(tool.input_schema or {})) for tool in tools.values())
+    instructions = len(getattr(server, "instructions", "") or "")
+    total = (descriptions + schemas + instructions) / 4
+
+    assert total <= SURFACE_BUDGET, (
+        f"the surface is {total:.0f} tokens resident before any call "
+        f"(descriptions {descriptions / 4:.0f}, schemas {schemas / 4:.0f}, "
+        f"instructions {instructions / 4:.0f})"
+    )

From 7d4fe747ceff439f7f1bda39b0091e91c8a92395 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sat, 19 Sep 2026 17:46:37 -0500
Subject: [PATCH 59/77] test(mcp): log both surface measurements in the budget
 comment

The comment dated a superseded figure to the day it was superseded: Task 2's
list_prompts rewrite grew the surface on the same 2026-09-19 the pre-rewrite
number was measured, leaving a reader no way to tell which reality it named.
The idiom it copies, COMPACT_BUDGET's comment, logs what moved a ceiling, so
this one now carries both measurements and names what moved between them.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 tests/test_mcp_server.py | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)

diff --git a/tests/test_mcp_server.py b/tests/test_mcp_server.py
index 4fb82a33..bf633f56 100644
--- a/tests/test_mcp_server.py
+++ b/tests/test_mcp_server.py
@@ -1093,9 +1093,12 @@ def test_the_stated_tool_count_is_the_registered_one():
 # measured. This is not a listing an agent chooses to read - it is resident
 # for the whole session before a single call, which is why it gets a ceiling
 # at all and why the catalog listing, read once, has had one since #101.
-# Measured 2026-09-19 at 13_225: descriptions 9_013, input schemas 3_212,
-# instructions 999. Set at 13_800, which is room for a tool or two and not
-# room for a second validate_workflow.
+# Measured 2026-09-19 at 13_225 before the list_prompts rewrite that landed
+# in the same plan (descriptions 9_013, input schemas 3_212, instructions
+# 999), and at 13_421 after it (9_138 / 3_283 / 1_000) - the three filter
+# parameters and the docstring that says what the library is for. Set at
+# 13_800, which is room for a tool or two and not room for a second
+# validate_workflow.
 # Worth knowing before raising it: four tools are a quarter of the
 # descriptions (validate_workflow 872, wait_for_job 583, list_workflows 540,
 # list_gallery 501), and validate_workflow's `plan.basis` taxonomy and

From 22fa16cb5d2da4dbd32dec3df79f4ee449db45dc Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sat, 19 Sep 2026 17:56:47 -0500
Subject: [PATCH 60/77] fix: close the final-review findings on the
 discoverability branch

docs/MCP.md: the list_prompts row still advertised the pre-fix signature
and behavior (no arguments, bodies included) after the tool gained
tag/intended_model/include_text filters and stopped returning text by
default - the reference table is what an agent reads instead of the
source, so a stale row there is a stale tool.

tests/test_mcp_server.py: the SURFACE_BUDGET comment's four per-tool
figures were measured in raw chars while the rest of the comment (and
the budget itself) works in chars/4; re-measured at head they are
774/518/482/445, which still sums to about a quarter of the 9,138-char
description total, so the "quarter" framing holds with the corrected
numbers. Also stopped building the server twice in
test_the_tool_surface_fits_the_budget - the second server_over(ok({}))
call was dead weight once the tools were already drawn from a bound
server variable.

tests/test_plugin_skills.py: test_a_skill_points_at_the_stored_exemplars
matched "get_prompt" as a bare substring of "get_prompt_schema", so a
skill naming only the schema tool would pass without ever pointing at
the exemplar library; now it requires the backticked name a skill
actually writes. test_a_skill_is_enumerated_where_the_plugin_describes_itself
matched a skill's name anywhere in CLAUDE.md or the plugin README, which
a future skill named after a model family (flux, z-image) could satisfy
by accident via unrelated prose; now it requires the backticked form
both documents already use when listing skills.

dw/server/app.py: _matching_prompts's docstring said "None when there
are none," which reads as no prompts matched rather than its actual
meaning - no filter was given, so nothing narrows the listing.

docs/WORKFLOW_GUIDE.md: the intended_model paragraph explained that the
library badges and filters by it but never said the match is exact,
which is the fact that makes a family's spelling drift (minimax-music
vs minimax-music3) a real bug rather than a cosmetic one; added the rule
and pointed at the test that sweeps for a variant.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 docs/MCP.md                 | 2 +-
 docs/WORKFLOW_GUIDE.md      | 5 ++++-
 dw/server/app.py            | 2 +-
 tests/test_mcp_server.py    | 6 +++---
 tests/test_plugin_skills.py | 5 +++--
 5 files changed, 12 insertions(+), 8 deletions(-)

diff --git a/docs/MCP.md b/docs/MCP.md
index 1c16900f..2be4b937 100644
--- a/docs/MCP.md
+++ b/docs/MCP.md
@@ -271,7 +271,7 @@ references written in the same session.
 
 | Tool | Arguments | Purpose |
 | --- | --- | --- |
-| `list_prompts()` | — | List the stored prompts with their text and descriptions |
+| `list_prompts(tag=None, intended_model=None, include_text=False)` | optional `tag`, `intended_model`, `include_text` | List the stored prompts - description, intended model, tags and `text_chars`, bodies left out; `get_prompt` for one body |
 | `get_prompt(name)` | `name` | Get one stored prompt's full definition |
 | `get_prompt_schema()` | — | Get the JSON schema every stored prompt must satisfy. Its own route rather than a name under `/api/prompts`, so a prompt called `schema` cannot shadow it |
 | `save_prompt(name, prompt)` | `name`, `prompt` | Save a prompt, overwriting any prompt of that name. The server validates first, and refuses a `text` that itself begins with a reference prefix (`variable:`, `previous_result:`, `constant:`, `asset:`, `output:`, `prompt:`) |
diff --git a/docs/WORKFLOW_GUIDE.md b/docs/WORKFLOW_GUIDE.md
index d3fc24a8..29d80af7 100644
--- a/docs/WORKFLOW_GUIDE.md
+++ b/docs/WORKFLOW_GUIDE.md
@@ -1534,7 +1534,10 @@ A prompt file holds the text plus the metadata the server's Prompts page shows:
 
 Only `text` is required, and it is what the reference resolves to. `intended_model` is
 informational - the engine ignores it, but the library badges and filters by it, and
-the server's prompt enhancer uses it to preselect a preset.
+the server's prompt enhancer uses it to preselect a preset. One spelling per family:
+`list_prompts(intended_model=...)` matches the whole value exactly, so `minimax-music`
+beside `minimax-music3` hides half a shelf, and `tests/test_prompt_library.py` sweeps
+the repo's library for a variant.
 
 The library's location is resolved in order: the `DW_PROMPT_DIR` environment
 variable (which `--prompt-dir` on both `dw.run` and `dw.serve` sets), then
diff --git a/dw/server/app.py b/dw/server/app.py
index 554059d1..7689ee83 100644
--- a/dw/server/app.py
+++ b/dw/server/app.py
@@ -521,7 +521,7 @@ def prompt_details(paths):
 
 
 def _matching_prompts(details, tag, intended_model):
-    """The prompt names matching the filters, or None when there are none.
+    """The prompt names matching the filters, or None when no filter was given.
 
     Case-insensitive and exact per value: a `tags` entry or the whole
     `intended_model`, never a substring - `minimax-music` must not match
diff --git a/tests/test_mcp_server.py b/tests/test_mcp_server.py
index bf633f56..d205dd6c 100644
--- a/tests/test_mcp_server.py
+++ b/tests/test_mcp_server.py
@@ -1100,8 +1100,8 @@ def test_the_stated_tool_count_is_the_registered_one():
 # 13_800, which is room for a tool or two and not room for a second
 # validate_workflow.
 # Worth knowing before raising it: four tools are a quarter of the
-# descriptions (validate_workflow 872, wait_for_job 583, list_workflows 540,
-# list_gallery 501), and validate_workflow's `plan.basis` taxonomy and
+# descriptions (validate_workflow 774, wait_for_job 518, list_workflows 482,
+# list_gallery 445), and validate_workflow's `plan.basis` taxonomy and
 # wait_for_job's stall-diagnosis paragraph are both restated in
 # WORKFLOW_GUIDE's "The loop" - which an agent fetches on demand. The
 # question to ask first is whether the second copy has to be the resident one.
@@ -1110,8 +1110,8 @@ def test_the_stated_tool_count_is_the_registered_one():
 
 @pytest.mark.asyncio
 async def test_the_tool_surface_fits_the_budget():
-    tools = await tools_of(server_over(ok({})))
     server = server_over(ok({}))
+    tools = await tools_of(server)
 
     descriptions = sum(len(tool.description or "") for tool in tools.values())
     schemas = sum(len(json.dumps(tool.input_schema or {})) for tool in tools.values())
diff --git a/tests/test_plugin_skills.py b/tests/test_plugin_skills.py
index 0e114d11..755fcd6f 100644
--- a/tests/test_plugin_skills.py
+++ b/tests/test_plugin_skills.py
@@ -490,7 +490,7 @@ def test_a_skill_points_at_the_stored_exemplars(path):
     could have read - and `prompts/ltx2/` as a directory is unreachable
     from a client that has the MCP and no checkout."""
     text = skill_text(path)
-    assert "list_prompts" in text or "get_prompt" in text, (
+    assert "`list_prompts" in text or "`get_prompt`" in text, (
         f"{path} never names the prompt library; a filesystem path is not a "
         f"call an MCP client can make"
     )
@@ -509,7 +509,8 @@ def test_a_skill_is_enumerated_where_the_plugin_describes_itself(path):
         os.path.join(REPO_ROOT, "CLAUDE.md"),
     ):
         with open(document) as file:
-            assert name in file.read(), (
+            content = file.read()
+            assert f"`{name}`" in content, (
                 f"skill {name!r} is not named in "
                 f"{os.path.relpath(document, REPO_ROOT)}"
             )

From 67c7f22c3f33a9e2cca5e287b34c3bc232ee7d2d Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sat, 19 Sep 2026 18:08:23 -0500
Subject: [PATCH 61/77] format (#250)

---
 .../plans/2026-09-19-agent-discoverability.md | 169 ++++++++++--------
 dw/server/app.py                              |   4 +-
 dw_mcp/authoring.py                           |  29 +++
 dw_mcp/server.py                              |   9 +-
 tests/test_catalog_shape.py                   |   4 +-
 tests/test_mcp_server.py                      |   4 +-
 tests/test_plugin_skills.py                   |   3 +-
 tests/test_server.py                          |  14 +-
 8 files changed, 146 insertions(+), 90 deletions(-)

diff --git a/docs/superpowers/plans/2026-09-19-agent-discoverability.md b/docs/superpowers/plans/2026-09-19-agent-discoverability.md
index 27349190..219f970b 100644
--- a/docs/superpowers/plans/2026-09-19-agent-discoverability.md
+++ b/docs/superpowers/plans/2026-09-19-agent-discoverability.md
@@ -87,63 +87,69 @@ MCP (which cannot afford it). Add narrowing, keep the default byte-identical.
 Add to `tests/test_server.py`, inside `class TestPromptLibrary`:
 
 ```python
-    def _store(self, client, name, prompt):
-        assert client.put(f"/api/prompts/{name}", json={"prompt": prompt}).status_code == 200
-
-    def test_the_listing_narrows_by_tag_and_model_and_can_omit_the_text(
-        self, server, tmp_path
-    ):
-        with server(success_script) as client:
-            self._store(
-                client,
-                "minimax/Song",
-                {
-                    "text": "Global Metadata\nbpm is 58.",
-                    "description": "a song",
-                    "intended_model": "minimax-music3",
-                    "tags": ["music", "score"],
-                },
-            )
-            self._store(
-                client,
-                "minimax/Fox",
-                {
-                    "text": "a red fox at dawn",
-                    "description": "a fox",
-                    "intended_model": "minimax-h3",
-                    "tags": ["wildlife"],
-                },
-            )
-
-            # A caller that passes nothing gets what it always got
-            plain = client.get("/api/prompts").json()
-            assert "minimax/Song" in plain["prompts"]
-            assert plain["details"]["minimax/Fox"]["text"] == "a red fox at dawn"
-            assert "text_chars" not in plain["details"]["minimax/Fox"]
-
-            # include_text=false swaps the payload for its size
-            slim = client.get("/api/prompts?include_text=false").json()
-            entry = slim["details"]["minimax/Fox"]
-            assert "text" not in entry
-            assert entry["text_chars"] == len("a red fox at dawn")
-            assert entry["description"] == "a fox"
+def _store(self, client, name, prompt):
+    assert (
+        client.put(f"/api/prompts/{name}", json={"prompt": prompt}).status_code == 200
+    )
 
-            # A filter narrows the names, the origins and the details together
-            by_model = client.get("/api/prompts?intended_model=MINIMAX-MUSIC3").json()
-            assert by_model["prompts"] == ["minimax/Song"]
-            assert list(by_model["details"]) == ["minimax/Song"]
-            assert list(by_model["origins"]) == ["minimax/Song"]
 
-            by_tag = client.get("/api/prompts?tag=Wildlife").json()
-            assert by_tag["prompts"] == ["minimax/Fox"]
+def test_the_listing_narrows_by_tag_and_model_and_can_omit_the_text(
+    self, server, tmp_path
+):
+    with server(success_script) as client:
+        self._store(
+            client,
+            "minimax/Song",
+            {
+                "text": "Global Metadata\nbpm is 58.",
+                "description": "a song",
+                "intended_model": "minimax-music3",
+                "tags": ["music", "score"],
+            },
+        )
+        self._store(
+            client,
+            "minimax/Fox",
+            {
+                "text": "a red fox at dawn",
+                "description": "a fox",
+                "intended_model": "minimax-h3",
+                "tags": ["wildlife"],
+            },
+        )
 
-            # Both at once, and a miss is an empty listing rather than a 404
-            assert client.get(
-                "/api/prompts?tag=music&intended_model=minimax-h3"
-            ).json()["prompts"] == []
+        # A caller that passes nothing gets what it always got
+        plain = client.get("/api/prompts").json()
+        assert "minimax/Song" in plain["prompts"]
+        assert plain["details"]["minimax/Fox"]["text"] == "a red fox at dawn"
+        assert "text_chars" not in plain["details"]["minimax/Fox"]
+
+        # include_text=false swaps the payload for its size
+        slim = client.get("/api/prompts?include_text=false").json()
+        entry = slim["details"]["minimax/Fox"]
+        assert "text" not in entry
+        assert entry["text_chars"] == len("a red fox at dawn")
+        assert entry["description"] == "a fox"
+
+        # A filter narrows the names, the origins and the details together
+        by_model = client.get("/api/prompts?intended_model=MINIMAX-MUSIC3").json()
+        assert by_model["prompts"] == ["minimax/Song"]
+        assert list(by_model["details"]) == ["minimax/Song"]
+        assert list(by_model["origins"]) == ["minimax/Song"]
+
+        by_tag = client.get("/api/prompts?tag=Wildlife").json()
+        assert by_tag["prompts"] == ["minimax/Fox"]
+
+        # Both at once, and a miss is an empty listing rather than a 404
+        assert (
+            client.get("/api/prompts?tag=music&intended_model=minimax-h3").json()[
+                "prompts"
+            ]
+            == []
+        )
 
-            # The writable directory is reported whatever the filter
-            assert client.get("/api/prompts?tag=music").json()["prompt_dir"]
+        # The writable directory is reported whatever the filter
+        assert client.get("/api/prompts?tag=music").json()["prompt_dir"]
 ```
 
 - [ ] **Step 2: Run the test to verify it fails**
@@ -630,7 +636,9 @@ def test_a_generated_audio_track_carries_has_audio():
                 "name": "generate_music",
                 "pipeline": {
                     "configuration": {"component_type": "ModularPipeline"},
-                    "from_pretrained_arguments": {"model_name": "MiniMaxAI/MiniMax-Music3"},
+                    "from_pretrained_arguments": {
+                        "model_name": "MiniMaxAI/MiniMax-Music3"
+                    },
                     "arguments": {"prompt": "variable:prompt"},
                 },
                 "result": {"content_type": "audio/mpeg"},
@@ -990,8 +998,7 @@ def test_a_skill_is_enumerated_where_the_plugin_describes_itself(path):
     ):
         with open(document) as file:
             assert name in file.read(), (
-                f"skill {name!r} is not named in "
-                f"{os.path.relpath(document, REPO_ROOT)}"
+                f"skill {name!r} is not named in {os.path.relpath(document, REPO_ROOT)}"
             )
 ```
 
@@ -1101,7 +1108,9 @@ def test_the_stated_tool_count_is_the_registered_one():
     with open(os.path.join(REPO_ROOT, "README.md")) as file:
         stated["README.md"] = re.search(r"The agent has (\d+) tools", file.read())
     with open(os.path.join(REPO_ROOT, "dw", "server", "guides.py")) as file:
-        stated["dw/server/guides.py"] = re.search(r"(\d+)-tool MCP surface", file.read())
+        stated["dw/server/guides.py"] = re.search(
+            r"(\d+)-tool MCP surface", file.read()
+        )
 
     for where, found in stated.items():
         assert found, f"{where} no longer states a tool count in the expected form"
@@ -1200,28 +1209,30 @@ TASKS_TEXT = (
 Then add to `class TestFetching`:
 
 ```python
-    def test_a_section_linking_an_example_says_how_to_reach_it(self, checkout):
-        """A guide's link to an example is a repo path. The reader these
-        guides exist for has no checkout - it has the MCP and nothing else -
-        so a payload holding such a path carries the translation rule, rather
-        than 114 links being rewritten in prose people read too."""
-        body = guides.get_guide("tasks", "Frame Interpolation")
-
-        # The note is one fixed sentence - it states the rule, it does not
-        # name the paths it saw
-        assert body["catalog_paths"] == guides.CATALOG_PATH_NOTE
-        assert "get_workflow" in body["catalog_paths"]
-
-    def test_a_section_linking_nothing_carries_no_note(self, checkout):
-        body = guides.get_guide("tasks", "Speech Generation")
-
-        assert "catalog_paths" not in body
-
-    def test_an_index_holding_a_path_is_noted_too(self, checkout):
-        """The index carries the guide's opening and its whole first section,
-        which is as able to link an example as any other."""
-        assert "catalog_paths" not in guides.get_guide("tasks")
-        assert "catalog_paths" in guides.get_guide("workflows")
+def test_a_section_linking_an_example_says_how_to_reach_it(self, checkout):
+    """A guide's link to an example is a repo path. The reader these
+    guides exist for has no checkout - it has the MCP and nothing else -
+    so a payload holding such a path carries the translation rule, rather
+    than 114 links being rewritten in prose people read too."""
+    body = guides.get_guide("tasks", "Frame Interpolation")
+
+    # The note is one fixed sentence - it states the rule, it does not
+    # name the paths it saw
+    assert body["catalog_paths"] == guides.CATALOG_PATH_NOTE
+    assert "get_workflow" in body["catalog_paths"]
+
+
+def test_a_section_linking_nothing_carries_no_note(self, checkout):
+    body = guides.get_guide("tasks", "Speech Generation")
+
+    assert "catalog_paths" not in body
+
+
+def test_an_index_holding_a_path_is_noted_too(self, checkout):
+    """The index carries the guide's opening and its whole first section,
+    which is as able to link an example as any other."""
+    assert "catalog_paths" not in guides.get_guide("tasks")
+    assert "catalog_paths" in guides.get_guide("workflows")
 ```
 
 The last assertion needs the fixture's `WORKFLOW_GUIDE.md` to link one. In the
diff --git a/dw/server/app.py b/dw/server/app.py
index 7689ee83..51a9f67f 100644
--- a/dw/server/app.py
+++ b/dw/server/app.py
@@ -2208,7 +2208,9 @@ def list_prompts(
         # than no filter at all
         wanted = _matching_prompts(details, tag, intended_model)
         if wanted is not None:
-            details = {name: detail for name, detail in details.items() if name in wanted}
+            details = {
+                name: detail for name, detail in details.items() if name in wanted
+            }
         # The three parallel keys agree by construction, filter or no filter.
         # `prompt_details` drops a path whose mtime it cannot read - the file
         # went away between the walk and the read - and listing a name that
diff --git a/dw_mcp/authoring.py b/dw_mcp/authoring.py
index 882a472d..7c18a600 100644
--- a/dw_mcp/authoring.py
+++ b/dw_mcp/authoring.py
@@ -6,6 +6,8 @@
 re-implements it - a second, subtly different check is how the two drift.
 """
 
+import json
+
 from dw_mcp.client import DwApiError, api_path
 
 
@@ -75,12 +77,39 @@ def save_workflow(client, name, workflow=None, patch=None):
             "Provide exactly one of `workflow` (a full replacement) or "
             "`patch` (a JSON merge patch onto the stored version)."
         )
+    workflow = _coerce_json_object(workflow, "workflow")
+    patch = _coerce_json_object(patch, "patch")
     if patch is not None:
         current = client.get_json(api_path("api", "workflows", name))
         workflow = _merge_patch(current, patch)
     return client.put_json(api_path("api", "workflows", name), {"workflow": workflow})
 
 
+def _coerce_json_object(value, param_name):
+    """A tool argument typed as an object can still arrive as a JSON-encoded
+    string (a caller that serialized it before handing it over, or a client
+    that couldn't parse a malformed document and passed the raw text
+    through). Accept that case rather than letting it reach the server as a
+    string, where the schema rejection names the wrong problem - not "this
+    isn't an object" but a bare pydantic `type=dict_type, input_type=str`,
+    which reads as if the field itself were misdeclared."""
+    if value is None or isinstance(value, dict):
+        return value
+    if not isinstance(value, str):
+        raise DwApiError(
+            f"`{param_name}` must be a JSON object, not {type(value).__name__}."
+        )
+    try:
+        parsed = json.loads(value)
+    except json.JSONDecodeError as e:
+        raise DwApiError(f"`{param_name}` is not valid JSON: {e}") from e
+    if not isinstance(parsed, dict):
+        raise DwApiError(
+            f"`{param_name}` must be a JSON object, not {type(parsed).__name__}."
+        )
+    return parsed
+
+
 def _merge_patch(target, patch):
     """RFC 7396 JSON Merge Patch: each dict key in `patch` merges
     recursively into `target`; any other value replaces `target` outright;
diff --git a/dw_mcp/server.py b/dw_mcp/server.py
index 485f0aad..fc7bce57 100644
--- a/dw_mcp/server.py
+++ b/dw_mcp/server.py
@@ -855,7 +855,9 @@ def validate_workflow(
         )
 
     def save_workflow(
-        name: str, workflow: dict | None = None, patch: dict | None = None
+        name: str,
+        workflow: dict | str | None = None,
+        patch: dict | str | None = None,
     ) -> dict:
         """Save a workflow to the server's writable workflow directory,
         overwriting any existing workflow of that name there. Validate it
@@ -873,7 +875,10 @@ def save_workflow(
         workflow. A patch key set to `null` deletes that key from the
         stored document. A list is replaced whole, never merged - a merge
         patch has no notion of list position, so changing one `shots` entry
-        still means sending the whole `shots` list.
+        still means sending the whole `shots` list. Either may also be
+        given as a JSON-encoded string, which is parsed before saving; a
+        string that fails to parse is reported as invalid JSON rather than
+        as a type mismatch.
 
         A workflow stored for reuse should mark each saving step's
         `result.subfolder` - `final` for the step whose output the user will
diff --git a/tests/test_catalog_shape.py b/tests/test_catalog_shape.py
index 520107bd..dc02fba0 100644
--- a/tests/test_catalog_shape.py
+++ b/tests/test_catalog_shape.py
@@ -676,7 +676,9 @@ def test_a_generated_audio_track_carries_has_audio():
                 "name": "generate_music",
                 "pipeline": {
                     "configuration": {"component_type": "ModularPipeline"},
-                    "from_pretrained_arguments": {"model_name": "MiniMaxAI/MiniMax-Music3"},
+                    "from_pretrained_arguments": {
+                        "model_name": "MiniMaxAI/MiniMax-Music3"
+                    },
                     "arguments": {"prompt": "variable:prompt"},
                 },
                 "result": {"content_type": "audio/mpeg"},
diff --git a/tests/test_mcp_server.py b/tests/test_mcp_server.py
index d205dd6c..d8d124f1 100644
--- a/tests/test_mcp_server.py
+++ b/tests/test_mcp_server.py
@@ -1080,7 +1080,9 @@ def test_the_stated_tool_count_is_the_registered_one():
     with open(os.path.join(REPO_ROOT, "README.md")) as file:
         stated["README.md"] = re.search(r"The agent has (\d+) tools", file.read())
     with open(os.path.join(REPO_ROOT, "dw", "server", "guides.py")) as file:
-        stated["dw/server/guides.py"] = re.search(r"(\d+)-tool MCP surface", file.read())
+        stated["dw/server/guides.py"] = re.search(
+            r"(\d+)-tool MCP surface", file.read()
+        )
 
     for where, found in stated.items():
         assert found, f"{where} no longer states a tool count in the expected form"
diff --git a/tests/test_plugin_skills.py b/tests/test_plugin_skills.py
index 755fcd6f..d7c7b636 100644
--- a/tests/test_plugin_skills.py
+++ b/tests/test_plugin_skills.py
@@ -511,6 +511,5 @@ def test_a_skill_is_enumerated_where_the_plugin_describes_itself(path):
         with open(document) as file:
             content = file.read()
             assert f"`{name}`" in content, (
-                f"skill {name!r} is not named in "
-                f"{os.path.relpath(document, REPO_ROOT)}"
+                f"skill {name!r} is not named in {os.path.relpath(document, REPO_ROOT)}"
             )
diff --git a/tests/test_server.py b/tests/test_server.py
index 7c73d968..a69bb0b2 100644
--- a/tests/test_server.py
+++ b/tests/test_server.py
@@ -2977,7 +2977,10 @@ def test_save_prompt_roundtrip_and_confinement(self, server, tmp_path):
             assert not (tmp_path / "escape.json").exists()
 
     def _store(self, client, name, prompt):
-        assert client.put(f"/api/prompts/{name}", json={"prompt": prompt}).status_code == 200
+        assert (
+            client.put(f"/api/prompts/{name}", json={"prompt": prompt}).status_code
+            == 200
+        )
 
     def test_the_listing_narrows_by_tag_and_model_and_can_omit_the_text(
         self, server, tmp_path
@@ -3027,9 +3030,12 @@ def test_the_listing_narrows_by_tag_and_model_and_can_omit_the_text(
             assert by_tag["prompts"] == ["minimax/Fox"]
 
             # Both at once, and a miss is an empty listing rather than a 404
-            assert client.get(
-                "/api/prompts?tag=music&intended_model=minimax-h3"
-            ).json()["prompts"] == []
+            assert (
+                client.get("/api/prompts?tag=music&intended_model=minimax-h3").json()[
+                    "prompts"
+                ]
+                == []
+            )
 
             # The writable directory is reported whatever the filter
             assert client.get("/api/prompts?tag=music").json()["prompt_dir"]

From e34752f36419532dd3ef3aa5c3dab4c9902a92b3 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sat, 19 Sep 2026 18:20:04 -0500
Subject: [PATCH 62/77] fix(mcp): #247 - gallery reference contract, path leak,
 no-seed false positive

get_gallery_metadata/list_gallery mismatch: list_gallery's own `label` field
(a bare display basename) looked like a valid reference but was refused by
get_gallery_metadata - accepting it outright would be unsafe since two runs
can share a basename, so instead the docstrings on both tools now say
plainly that `name` is the reference and `label` is display-only.

The 404 that mismatch produced was also leaking the server's absolute
filesystem path (from dw/security.py's validate_path exception text) through
_output_file in dw/server/app.py - now reports the caller's own `name`
argument instead.

No-seed warning false positive: unseeded_cache_warnings fired on any
workflow lacking a top-level seed, including task-only utility workflows
with no pipeline step to seed in the first place. Gated behind a new
_has_seedable_step check (pipeline/pipeline_reference/workflow present on
any step) so a purely deterministic workflow gets no meaningless warning.

Item 1 of #247 (save_workflow's malformed-JSON error message) was already
fixed and committed to develop separately.
---
 dw/plan.py        | 19 ++++++++++++++++++-
 dw/server/app.py  |  7 +++++--
 dw_mcp/catalog.py | 14 ++++++++++----
 3 files changed, 33 insertions(+), 7 deletions(-)

diff --git a/dw/plan.py b/dw/plan.py
index c7cea169..7999cd4e 100644
--- a/dw/plan.py
+++ b/dw/plan.py
@@ -183,8 +183,13 @@ def unseeded_cache_warnings(definition, arguments=None):
     there, and the difference is the one that matters: without a `seed` the
     cache is off, so nothing is ever reused however many times the same
     workflow runs (#107).
+
+    Silent for a workflow with no `pipeline`/`pipeline_reference`/`workflow`
+    step: a task-only utility has no generative randomness a `seed` would
+    pin down in the first place, and each of its steps is a pure function of
+    its inputs - a repeat run is already free without one (#247)
     """
-    if _is_seeded(definition, arguments):
+    if _is_seeded(definition, arguments) or not _has_seedable_step(definition):
         return []
     return [
         "This workflow sets no 'seed', so the step cache is disabled and "
@@ -194,6 +199,18 @@ def unseeded_cache_warnings(definition, arguments=None):
     ]
 
 
+def _has_seedable_step(definition):
+    """Whether any step could consume a seed: a pipeline (inline or
+    referenced) or a sub-workflow, which may hold one in turn. A workflow
+    built entirely of `task` steps has nothing a seed would affect."""
+    for step in definition.get("steps") or []:
+        if not isinstance(step, dict):
+            continue
+        if "pipeline" in step or "pipeline_reference" in step or "workflow" in step:
+            return True
+    return False
+
+
 def _is_seeded(definition, arguments):
     """Whether a run of this workflow has a seed before it draws one - read
     from the definition as written and the caller's arguments, since
diff --git a/dw/server/app.py b/dw/server/app.py
index 51a9f67f..97dc3c34 100644
--- a/dw/server/app.py
+++ b/dw/server/app.py
@@ -2389,8 +2389,11 @@ def _output_file(name, root=None):
                 root,
                 allow_create=False,
             )
-        except SecurityError as e:
-            raise HTTPException(status_code=404, detail=f"Unknown file: {e}")
+        except SecurityError:
+            # SecurityError's own message embeds the resolved *absolute*
+            # server path (dw/security.py validate_path) - useful in a log,
+            # not in a response a remote caller reads
+            raise HTTPException(status_code=404, detail=f"Unknown file: {name}")
         if not os.path.isfile(path):
             raise HTTPException(status_code=404, detail="Unknown file")
         return path
diff --git a/dw_mcp/catalog.py b/dw_mcp/catalog.py
index 5a5c98f2..8da6ede1 100644
--- a/dw_mcp/catalog.py
+++ b/dw_mcp/catalog.py
@@ -225,7 +225,12 @@ def list_gallery(client, limit=50, subfolder=None, only_orphans=False, workspace
     one that failed before writing anything. A run that wrote any file at
     all, a text-shape prompt or a utility's side output included, is not
     listed. `subfolder` does not apply in this mode. `name` is exactly what
-    `delete_output` accepts, so clearing one is list, then delete (#170)."""
+    `delete_output` accepts, so clearing one is list, then delete (#170).
+
+    Each file entry also carries `label`, a bare display basename for a UI
+    grid - it is not a valid reference on its own (two runs can write the
+    same basename) and is not accepted by `get_gallery_metadata` or
+    `delete_output`. Pass `name` to those, not `label`."""
     params = {"limit": limit}
     if subfolder is not None:
         params["subfolder"] = subfolder
@@ -240,9 +245,10 @@ def get_gallery_metadata(client, name, envelope=False, workspace=None):
     audio and video what the file holds - duration, sample rate, channels,
     fps, size, peak and mean level in dBFS.
 
-    `name` is a gallery name, or an 'asset:' reference to read an input
-    asset the same way (#127) - the same numbers, `job` null, and `source`
-    saying which of the two answered.
+    `name` is a gallery name - the `name` field `list_gallery` reports, not
+    its `label` (a display-only basename that is not a valid reference) -
+    or an 'asset:' reference to read an input asset the same way (#127); the
+    same numbers, `job` null, and `source` saying which of the two answered.
 
     With envelope=True the soundtrack's level is reported second by second
     as well, which is what locates something in a track rather than only

From 86b1dfc0134587d55e86627fb36560f0ec1af94d Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sat, 19 Sep 2026 18:34:25 -0500
Subject: [PATCH 63/77] fix(server): ensure tool descriptions have no docstring
 indentation for consistency across Python versions

---
 dw_mcp/server.py         | 13 ++++++++++++-
 tests/test_mcp_server.py | 24 +++++++++++++++++++++++-
 2 files changed, 35 insertions(+), 2 deletions(-)

diff --git a/dw_mcp/server.py b/dw_mcp/server.py
index fc7bce57..672754ed 100644
--- a/dw_mcp/server.py
+++ b/dw_mcp/server.py
@@ -6,6 +6,7 @@
 """
 
 import functools
+import inspect
 from typing import Literal, Optional
 
 from mcp.server.mcpserver import MCPServer
@@ -151,7 +152,17 @@ def build_server(client):
     )
 
     def tool(fn, annotations):
-        server.add_tool(_anticipated(fn), name=fn.__name__, annotations=annotations)
+        # The SDK ships fn.__doc__ verbatim. Python 3.13+ strips a docstring's
+        # common indentation at compile time, 3.12 does not - so without this
+        # every continuation line reaches the agent with eight leading spaces,
+        # about 1_100 tokens of resident surface on the interpreter most
+        # servers run. cleandoc makes the description the same on both.
+        server.add_tool(
+            _anticipated(fn),
+            name=fn.__name__,
+            description=inspect.cleandoc(fn.__doc__ or ""),
+            annotations=annotations,
+        )
 
     # ------------------------------------------------------------- catalog
 
diff --git a/tests/test_mcp_server.py b/tests/test_mcp_server.py
index d8d124f1..119b06a5 100644
--- a/tests/test_mcp_server.py
+++ b/tests/test_mcp_server.py
@@ -170,6 +170,24 @@ async def test_every_tool_has_a_description():
     assert missing == []
 
 
+@pytest.mark.asyncio
+async def test_descriptions_carry_no_docstring_indentation():
+    """The SDK ships `fn.__doc__` verbatim. Python 3.13+ strips a docstring's
+    common indentation at compile time; 3.12 keeps it, so every continuation
+    line reached the agent with eight leading spaces - about 1_100 tokens of
+    the resident surface on the interpreter most servers run, invisible to a
+    test run on a newer one."""
+    tools = await tools_of(server_over(ok({})))
+
+    indented = {
+        name: line
+        for name, tool in tools.items()
+        for line in (tool.description or "").splitlines()
+        if line[:1].isspace()
+    }
+    assert indented == {}
+
+
 @pytest.mark.asyncio
 async def test_read_only_tools_are_annotated_read_only():
     tools = await tools_of(server_over(ok({})))
@@ -1100,7 +1118,11 @@ def test_the_stated_tool_count_is_the_registered_one():
 # 999), and at 13_421 after it (9_138 / 3_283 / 1_000) - the three filter
 # parameters and the docstring that says what the library is for. Set at
 # 13_800, which is room for a tool or two and not room for a second
-# validate_workflow.
+# validate_workflow. Those figures were taken on Python 3.14, which dedents
+# docstrings at compile time; on 3.12 the same surface measured 14_574
+# (descriptions 10_281) until `tool()` began passing the cleandoc'd
+# docstring as the description, since then 13_474 (9_181 / 3_293 / 1_000)
+# on either interpreter. Measure on the interpreter CI runs, or on both.
 # Worth knowing before raising it: four tools are a quarter of the
 # descriptions (validate_workflow 774, wait_for_job 518, list_workflows 482,
 # list_gallery 445), and validate_workflow's `plan.basis` taxonomy and

From c42db2b773f12210bb020424dbbf50a87709cd0d Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sat, 19 Sep 2026 19:00:07 -0500
Subject: [PATCH 64/77] fix(server): #238 - make .txt outputs visible in
 gallery/asset listings

.txt files had no entry in MEDIA_KINDS, so a workflow that saved text
output was invisible to gallery/asset listings. Add a "text" kind for
.txt, and keep .txt files deflated (not stored) in zip downloads like
other text-ish media.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 dw/server/app.py     | 14 ++++++++++++--
 tests/test_server.py |  9 ++++++---
 2 files changed, 18 insertions(+), 5 deletions(-)

diff --git a/dw/server/app.py b/dw/server/app.py
index 97dc3c34..3846b9cc 100644
--- a/dw/server/app.py
+++ b/dw/server/app.py
@@ -2363,6 +2363,11 @@ def enhance(request: EnhanceRequest, ws: Workspace = Depends(selected_workspace)
         **{ext: "image" for ext in ALLOWED_IMAGE_EXTENSIONS},
         **{ext: "video" for ext in ALLOWED_VIDEO_EXTENSIONS},
         **{ext: "audio" for ext in ALLOWED_AUDIO_EXTENSIONS},
+        # Not in the security allowlists above (nothing loads a .txt back
+        # into a pipeline, so it is not a path a run reads), but a
+        # text-shape run's deliverable is a real output and belongs in the
+        # gallery like any other kind (#238)
+        ".txt": "text",
     }
 
     # The allowlist members that are not already-compressed containers -
@@ -2863,9 +2868,14 @@ def _zip_download(entries, filename):
                         # temp file is complete), so it is stored instead.
                         # Everything else - .json, .md, .txt, .bmp, .wav, an
                         # unrecognized extension - deflates, including the
-                        # export zip's text files
+                        # export zip's text files. ".txt" is in MEDIA_KINDS
+                        # (kind "text", #238) but is plain text, not an
+                        # already-compressed container, so it stays out of
+                        # this policy the same way .json and .md do
+                        kind = MEDIA_KINDS.get(extension)
                         stored = (
-                            extension in MEDIA_KINDS
+                            kind is not None
+                            and kind != "text"
                             and extension not in RAW_MEDIA_EXTENSIONS
                         )
                         archive.write(
diff --git a/tests/test_server.py b/tests/test_server.py
index a69bb0b2..b72ecca4 100644
--- a/tests/test_server.py
+++ b/tests/test_server.py
@@ -1202,7 +1202,7 @@ def test_gallery_lists_media_and_reads_metadata(server, tmp_path):
     with server(success_script) as client:
         outputs = tmp_path / "outputs"
 
-        # a plain image, a video stand-in, and a non-media file
+        # a plain image, a video stand-in, and a text deliverable (#238)
         Image.new("RGB", (4, 4)).save(outputs / "plain-gen.0-0.0.png")
         (outputs / "clip-gen.0-0.0.mp4").write_bytes(b"\x00" * 10)
         (outputs / "notes.txt").write_text("not media")
@@ -1222,9 +1222,11 @@ def test_gallery_lists_media_and_reads_metadata(server, tmp_path):
             "plain-gen.0-0.0.png",
             "clip-gen.0-0.0.mp4",
             "meta-gen.0-0.0.png",
+            "notes.txt",
         }
         kinds = {f["name"]: f["kind"] for f in listing["files"]}
         assert kinds["clip-gen.0-0.0.mp4"] == "video"
+        assert kinds["notes.txt"] == "text"
 
         # metadata endpoint: full workflow comes back for the editor
         response = client.get("/api/gallery/meta-gen.0-0.0.png/metadata").json()
@@ -1869,15 +1871,16 @@ def test_the_asset_library_lists_what_it_holds(asset_server, tmp_path):
     (library / "gyre").mkdir(parents=True)
     (library / "iris.png").write_bytes(b"png")
     (library / "gyre" / "voice.wav").write_bytes(b"riff")
-    (library / "notes.txt").write_text("not media")
+    (library / "notes.txt").write_text("a caption, a script - a real asset (#238)")
 
     with asset_server(success_script) as client:
         body = client.get("/api/assets").json()
 
     names = {entry["name"]: entry for entry in body["assets"]}
-    assert set(names) == {"iris.png", "gyre/voice.wav"}
+    assert set(names) == {"iris.png", "gyre/voice.wav", "notes.txt"}
     assert names["iris.png"]["reference"] == "asset:iris.png"
     assert names["gyre/voice.wav"]["kind"] == "audio"
+    assert names["notes.txt"]["kind"] == "text"
     assert body["folders"] == ["", "gyre"]
 
 

From 7da78b7a73ec0105c0f1e781bde704f395e38a9e Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sat, 19 Sep 2026 19:00:07 -0500
Subject: [PATCH 65/77] fix(plan): #242 - report partial when a total comes
 only from a composed child

estimate() started 'partial' at False, so a workflow with no cost of
its own whose total came entirely from a priced sub-workflow reported
partial: false - indistinguishable from a genuinely complete figure.
Start partial as (minutes is None) instead, with a final guard that
resets it to False when nothing was priced at all, preserving that
"fully unknown" stays partial: false rather than implying part of it
is known.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 dw/plan.py         |  9 ++++++++-
 tests/test_plan.py | 25 +++++++++++++++++++++++++
 2 files changed, 33 insertions(+), 1 deletion(-)

diff --git a/dw/plan.py b/dw/plan.py
index 7999cd4e..b1dc1c65 100644
--- a/dw/plan.py
+++ b/dw/plan.py
@@ -316,7 +316,12 @@ def estimate(
         return measured
     own = _price(definition.get("cost"), device, list_entries, measured_entries or {})
     minutes = own["minutes"]
-    partial = False
+    # An unpriced parent (own["minutes"] is None) whose total ends up coming
+    # only from a priced child is not a complete figure - the parent's own
+    # steps (a for_each step with no cost block, say) contributed nothing to
+    # it, so the sum understates the run rather than merely omitting a piece
+    # of it (#242)
+    partial = minutes is None
     for path in _sub_workflow_paths(expanded):
         # A builtin is the parent's to price; a local child prices itself
         raw = read_sub_workflow(path, base_dir, workflow_dir)
@@ -333,6 +338,8 @@ def estimate(
             minutes += child["minutes"]
         else:
             minutes = child["minutes"]
+    if minutes is None:
+        partial = False
     return {
         "minutes": round(minutes, 1) if minutes is not None else None,
         "basis": own["basis"],
diff --git a/tests/test_plan.py b/tests/test_plan.py
index 7f806a63..eb3647b3 100644
--- a/tests/test_plan.py
+++ b/tests/test_plan.py
@@ -479,6 +479,31 @@ def test_a_builtin_adds_nothing_and_is_not_partial(self, plan):
         answer = plan(composing("builtin:text-to-image.json"))["estimate"]
         assert (answer["minutes"], answer["partial"]) == (2.0, False)
 
+    def test_an_unpriced_parent_with_a_priced_child_is_partial(self, plan, tmp_path):
+        """A for_each step with no cost block contributes nothing to the
+        total; a composed child's own figure should not be reported as
+        though it were the whole run's (#242)."""
+        child = {"id": "child", "cost": [cost("cuda", 5)], "steps": []}
+        (tmp_path / "child.json").write_text(json.dumps(child))
+        parent = {
+            "id": "parent",
+            "steps": [
+                {"name": "own", "task": {"command": "x", "arguments": {}}},
+                {
+                    "name": "child",
+                    "workflow": {"path": "child.json", "arguments": {}},
+                },
+            ],
+        }
+        answer = plan(parent)["estimate"]
+        assert (answer["minutes"], answer["partial"]) == (5.0, True)
+
+    def test_a_fully_unpriced_workflow_is_unknown_not_partial(self, plan):
+        """No cost block anywhere - 'unknown' already says nobody has a
+        number; 'partial' would wrongly imply some of it is known."""
+        answer = plan({"id": "parent", "steps": []})["estimate"]
+        assert (answer["minutes"], answer["partial"]) == (None, False)
+
     def test_a_child_measured_on_another_device_is_still_added(self, plan, tmp_path):
         child = {"id": "child", "cost": [cost("mps", 5)], "steps": []}
         (tmp_path / "child.json").write_text(json.dumps(child))

From 691751af2c0f8792d03a3bd14d3779bf892775d8 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sat, 19 Sep 2026 19:00:07 -0500
Subject: [PATCH 66/77] fix(tasks): #246 - warn when pair_audio trims audio to
 fit the video

_fit_to_video's pad branch called emit_warning; the trim branch only
logged at INFO, so trimming - the direction that can silently drop
real content - was invisible to an API/MCP consumer while padding
(silence, no content lost) was reported. Add a matching emit_warning
(kind audio_trimmed_to_video) naming the seconds cut.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 dw/tasks/pair_audio.py       | 14 +++++++++++---
 tests/test_pair_audio_fit.py |  9 +++++++++
 2 files changed, 20 insertions(+), 3 deletions(-)

diff --git a/dw/tasks/pair_audio.py b/dw/tasks/pair_audio.py
index b7f9ccd4..320b2833 100644
--- a/dw/tasks/pair_audio.py
+++ b/dw/tasks/pair_audio.py
@@ -102,9 +102,17 @@ def _fit_to_video(waveform, rate, frames, fps, fit):
             video_seconds=video_seconds,
         )
     else:
-        logger.info(
-            f"pair_audio: trimmed the track from {audio_seconds:.2f} s to the "
-            f"{video_seconds:.2f} s of video it is laid over"
+        emit_warning(
+            f"pair_audio: 'fit' trimmed {(have - wanted) / float(rate):.2f} s "
+            f"off the {audio_seconds:.2f} s track to reach the "
+            f"{video_seconds:.2f} s of video it is laid over - that part of "
+            f"the track, whatever it held, is gone from the deliverable. A "
+            f"shorter track, or more frames, is what keeps it.",
+            kind="audio_trimmed_to_video",
+            command="pair_audio",
+            audio_seconds=audio_seconds,
+            video_seconds=video_seconds,
+            trimmed_seconds=(have - wanted) / float(rate),
         )
     return fitted
 
diff --git a/tests/test_pair_audio_fit.py b/tests/test_pair_audio_fit.py
index 37493d6e..be933198 100644
--- a/tests/test_pair_audio_fit.py
+++ b/tests/test_pair_audio_fit.py
@@ -70,6 +70,15 @@ def test_the_other_direction_pads_and_warns(self, warnings_emitted):
         assert samples(result) == round(744 / FPS * SAMPLE_RATE)
         assert any("padded" in w for w in warnings_emitted)
 
+    def test_trimming_the_track_warns_with_the_seconds_cut(self, warnings_emitted):
+        """The pad direction cannot lose content; the trim direction always
+        can, so it is the one that most needs saying out loud (#246)."""
+        result = pair_audio(cut(248), song(30), sample_rate=SAMPLE_RATE, fit="video")
+        assert samples(result) == round(248 / FPS * SAMPLE_RATE)
+        trimmed = [w for w in warnings_emitted if "trimmed" in w]
+        assert len(trimmed) == 1
+        assert "19.67 s" in trimmed[0]
+
     def test_a_track_that_already_matches_is_left_alone(self, warnings_emitted):
         exact = song(248 / FPS)
         result = pair_audio(cut(248), exact, sample_rate=SAMPLE_RATE, fit="video")

From 997121b9009d419a7f9b2656615a0f1569b193f4 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sat, 19 Sep 2026 19:20:44 -0500
Subject: [PATCH 67/77] fix(server): #243 - project host memory for list-driven
 runs, warn only

Persists the worker's host_memory_peak_rss_mb onto each finished job
(jobs.sqlite), and validate_workflow now projects a for_each run's
peak host RAM from this server's own history: max observed peak when
the workflow releases its pipeline between iterations
(release_pipeline/release_models on the for_each step), else the
median per-entry footprint times the requested list length. Warns
when the projection exceeds ~90% of this machine's RAM; never
refuses, and a workflow with no memory history at all gets no check
(v1 scope approved on the issue).

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 dw/host_memory_projection.py         | 138 +++++++++++++++++++++++++++
 dw/server/app.py                     |  22 +++++
 dw/server/jobs.py                    |  39 +++++++-
 tests/test_host_memory_projection.py |  96 +++++++++++++++++++
 4 files changed, 291 insertions(+), 4 deletions(-)
 create mode 100644 dw/host_memory_projection.py
 create mode 100644 tests/test_host_memory_projection.py

diff --git a/dw/host_memory_projection.py b/dw/host_memory_projection.py
new file mode 100644
index 00000000..a878c362
--- /dev/null
+++ b/dw/host_memory_projection.py
@@ -0,0 +1,138 @@
+"""Whether a list-driven or composed run is projected to exceed host RAM.
+
+`dw/host_memory.py` reads what a *running* worker is holding; this module is
+the pre-flight half, for the failure mode `device_memory_stats`/VRAM warnings
+never covered - a `for_each` that keeps its pipeline resident across a
+12-entry list, or a per-clip step whose footprint scales with the list, can
+SIGKILL on host RAM with the accelerator nowhere near full (#243).
+
+Scope is v1, by the repo owner's own sign-off on the issue: observed, not
+curated (no author-declared memory figure - `host_memory_peak_rss_mb` is a
+worker-reported field, not a schema key); warn, not refuse (host RAM headroom
+is a property of *this machine*, not something a caller chose, so it never
+blocks a run); no cross-machine normalization; and a cold start - no history
+for this workflow at all - means no check, the same rule `observed_cost.py`
+uses for GPU minutes.
+"""
+
+import json
+import logging
+
+from .for_each import FOR_EACH_KEY
+
+logger = logging.getLogger("dw")
+
+# The fraction of physical RAM a projected peak may reach before this module
+# says anything - matches nothing else in the codebase; there is no existing
+# "safe headroom" constant to share, because nothing else projects against
+# the machine's total RAM rather than a curated figure.
+CEILING_FRACTION = 0.9
+
+_RELEASE_FLAGS = ("release_pipeline", "release_models")
+
+
+def releases_between_iterations(definition):
+    """Whether every `for_each` step in this workflow drops its pipeline (or
+    its models) between entries, rather than holding it resident for the
+    whole list.
+
+    `release_pipeline`/`release_models` survive on a for_each step's *last*
+    member only (`dw/for_each.py`), so their presence on the template step is
+    what says the author asked for the resident-vs-released shape here - the
+    same field, read for a different question. A workflow with no `for_each`
+    step at all answers True: there is no list to hold anything resident
+    across, so the "keeps everything resident" projection would not describe
+    it.
+    """
+    for_each_steps = [
+        step
+        for step in definition.get("steps") or []
+        if isinstance(step, dict) and FOR_EACH_KEY in step
+    ]
+    if not for_each_steps:
+        return True
+    return all(
+        any(step.get(flag) for flag in _RELEASE_FLAGS) for step in for_each_steps
+    )
+
+
+def _requested_count(list_entries):
+    """The largest list length the caller's own arguments drive, or None
+    when this run has no list at all - such a run is never the failure mode
+    this module exists for."""
+    if not list_entries:
+        return None
+    counts = [value for value in list_entries.values() if isinstance(value, int)]
+    return max(counts) if counts else None
+
+
+def _row_count(row, list_entries):
+    """The list length a historical row ran with, read from its own stored
+    arguments rather than the current request's - a row that ran a shorter
+    or longer list is still comparable, once divided out, for the resident
+    projection's per-entry figure.
+
+    Only the variable names the *current* request's `list_entries` names are
+    read back, on the assumption that a workflow's list-driving variables
+    are stable across its history - the same assumption `observed_cost.py`
+    makes bucketing by declared `cost_drivers`.
+    """
+    try:
+        arguments = json.loads(row.get("arguments") or "{}")
+    except (TypeError, ValueError):
+        return None
+    if not isinstance(arguments, dict):
+        return None
+    counts = [
+        len(arguments[name])
+        for name in list_entries
+        if isinstance(arguments.get(name), list)
+    ]
+    return max(counts) if counts else None
+
+
+def host_memory_warnings(definition, list_entries, rows, ceiling_mb):
+    """Warnings for a projected host-memory peak this machine cannot hold,
+    or [] when there is nothing to project from or nothing to warn about.
+
+    `rows` are this workflow's finished runs as `JobHistory.finished_runs()`
+    groups them - the same history `observed_cost.py` reads, extended with
+    `host_memory_peak_rss_mb` per row (#243). `ceiling_mb` is this box's own
+    RAM, scaled by `CEILING_FRACTION`; the caller reads that once per request
+    rather than this module importing `host_memory` for a per-validate
+    syscall.
+    """
+    requested = _requested_count(list_entries)
+    if requested is None or not rows or not ceiling_mb:
+        return []
+    peaks = [row["host_memory_peak_rss_mb"] for row in rows]
+    peaks = [value for value in peaks if isinstance(value, (int, float))]
+    if not peaks:
+        # Cold start: history exists for this workflow, but no run of it
+        # ever reported a host-memory reading - nothing to project from
+        return []
+    if releases_between_iterations(definition):
+        projected_mb = max(peaks)
+        shape = "the largest single iteration observed"
+    else:
+        per_entry = []
+        for row in rows:
+            peak = row["host_memory_peak_rss_mb"]
+            count = _row_count(row, list_entries)
+            if isinstance(peak, (int, float)) and count:
+                per_entry.append(peak / count)
+        if not per_entry:
+            return []
+        per_entry.sort()
+        median_per_entry = per_entry[len(per_entry) // 2]
+        projected_mb = median_per_entry * requested
+        shape = f"{requested} entries held resident together"
+    if projected_mb <= ceiling_mb:
+        return []
+    return [
+        "Projected host memory for this run (~"
+        f"{round(projected_mb)} MB, {shape}) exceeds this machine's usable RAM "
+        f"(~{round(ceiling_mb)} MB) - based on this server's own history for "
+        "this workflow, not a curated figure. The run is not blocked, but it "
+        "may be killed by the OS partway through."
+    ]
diff --git a/dw/server/app.py b/dw/server/app.py
index 3846b9cc..43111a74 100644
--- a/dw/server/app.py
+++ b/dw/server/app.py
@@ -73,6 +73,7 @@
 from ..result import read_embedded_metadata
 from ..media_info import probe_media
 from ..hub_cache import scan_models, delete_model, DownloadManager
+from ..host_memory_projection import CEILING_FRACTION, host_memory_warnings
 from ..plan import build_plan, gate_warnings, unseeded_cache_warnings
 from ..runs import (
     MANIFEST_FILE_NAME,
@@ -1786,8 +1787,29 @@ def validate_workflow(
             answer["plan"]["workspace"] = workspace.name
             answer["plan"]["output_dir"] = workspace.outputs
             answer["warnings"] += gate_warnings(answer["plan"]["downloads_required"])
+            if catalog_name:
+                answer["warnings"] += _host_memory_warnings(
+                    catalog_name, definition, answer["plan"]["list_entries"]
+                )
         return answer
 
+    def _host_memory_warnings(name, definition, list_entries):
+        """Whether this box's own history says the requested list is
+        projected to exceed host RAM (#243) - best effort, since a warning
+        that 500s the free pre-flight would be worse than skipping it."""
+        costs = getattr(app.state, "observed_costs", None)
+        if costs is None:
+            return []
+        try:
+            from ..host_memory import host_memory_stats
+
+            rows = costs.rows_for(name)
+            ceiling_mb = (host_memory_stats().get("total_mb") or 0) * CEILING_FRACTION
+            return host_memory_warnings(definition, list_entries, rows, ceiling_mb)
+        except Exception:
+            logger.debug("host memory projection failed for %s", name, exc_info=True)
+            return []
+
     # ------------------------------------------------------------ workspaces
 
     class WorkspaceRequest(BaseModel):
diff --git a/dw/server/jobs.py b/dw/server/jobs.py
index ab6e6475..28e04f89 100644
--- a/dw/server/jobs.py
+++ b/dw/server/jobs.py
@@ -140,6 +140,13 @@ def __init__(self, db_path):
                 connection.execute(
                     "ALTER TABLE jobs ADD COLUMN acknowledged TEXT DEFAULT 'none'"
                 )
+            # The worker's own high-water mark for this run (#243) - NULL for
+            # a row predating the column and for any run that never reported
+            # one (cancelled/errored before the worker's final memory_info)
+            if "host_memory_peak_rss_mb" not in columns:
+                connection.execute(
+                    "ALTER TABLE jobs ADD COLUMN host_memory_peak_rss_mb REAL"
+                )
 
     def _connect(self):
         return sqlite3.connect(self.db_path, timeout=5)
@@ -152,8 +159,8 @@ def record(self, job):
                 "INSERT OR REPLACE INTO jobs (id, workflow, status, created_at,"
                 " started_at, finished_at, arguments, spec, manifest, warnings,"
                 " error, events, workspace, workflow_name, run_id, run_dir,"
-                " acknowledged) VALUES"
-                " (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)",
+                " acknowledged, host_memory_peak_rss_mb) VALUES"
+                " (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)",
                 (
                     job.id,
                     job.workflow_name,
@@ -172,6 +179,11 @@ def record(self, job):
                     job.run_id,
                     job.run_dir,
                     job.acknowledged,
+                    # A test double or an older in-memory Job predating this
+                    # column reports None here rather than failing record()
+                    # (#243) - the same "absent means unknown" the column
+                    # itself allows
+                    getattr(job, "host_memory_peak_rss_mb", None),
                 ),
             )
 
@@ -264,13 +276,23 @@ def finished_runs(self):
             rows = connection.execute(
                 "SELECT workflow_name, started_at, finished_at, arguments,"
                 " manifest, INSTR(COALESCE(events, ''), ?) > 0,"
-                " COALESCE(json_array_length(COALESCE(events, '[]')), 0) >= ?"
+                " COALESCE(json_array_length(COALESCE(events, '[]')), 0) >= ?,"
+                " host_memory_peak_rss_mb"
                 " FROM jobs WHERE status = ? AND workflow_name IS NOT NULL"
                 " AND started_at IS NOT NULL AND finished_at IS NOT NULL",
                 (LOADING_MARKER, EVENT_CAP, SUCCEEDED),
             ).fetchall()
         grouped = {}
-        for name, started, finished, arguments, manifest, had_load, at_cap in rows:
+        for (
+            name,
+            started,
+            finished,
+            arguments,
+            manifest,
+            had_load,
+            at_cap,
+            peak_rss_mb,
+        ) in rows:
             grouped.setdefault(name, []).append(
                 {
                     "started_at": started,
@@ -280,6 +302,7 @@ def finished_runs(self):
                     "manifest": manifest,
                     "had_load": bool(had_load),
                     "events_at_cap": bool(at_cap),
+                    "host_memory_peak_rss_mb": peak_rss_mb,
                 }
             )
         return grouped
@@ -429,6 +452,9 @@ def __init__(self, spec):
         self.run_dir = None
         # Which form of cost acknowledgement queued this job (#85)
         self.acknowledged = spec.get("acknowledged") or ACK_NONE
+        # The worker's own high-water mark for this run, from its final
+        # memory_info message - None for a run that never got that far (#243)
+        self.host_memory_peak_rss_mb = None
         self.events = []
         # The running summary a poll reads - see _note_progress. Kept as the
         # events arrive rather than derived from the log on request, because
@@ -1194,6 +1220,11 @@ def _consume_results(self, job):
             elif message_type == "memory_info":
                 self._record_memory(message.get("info"))
                 job.add_event({"event": "memory", "info": self.last_memory})
+                # The worker's post-run reading, so it survives as a real
+                # column rather than only inside the trimmed event tail (#243)
+                peak = (message.get("info") or {}).get("host_memory_peak_rss_mb")
+                if peak is not None:
+                    job.host_memory_peak_rss_mb = peak
             elif message_type == "success":
                 self._record_manifest(job, message)
                 return (SUCCEEDED, None, None)
diff --git a/tests/test_host_memory_projection.py b/tests/test_host_memory_projection.py
new file mode 100644
index 00000000..a2795885
--- /dev/null
+++ b/tests/test_host_memory_projection.py
@@ -0,0 +1,96 @@
+"""Host-RAM projection for a list-driven or composed run (#243).
+
+Warn, not refuse: this module never fails a run, only says the caller's own
+history projects past what this machine's RAM can hold. Each rule below is a
+way a naive projection would mislead, so each has a test that fails if the
+rule is dropped.
+"""
+
+import json
+
+from dw.host_memory_projection import host_memory_warnings, releases_between_iterations
+
+MB = 1.0
+
+
+def row(peak_mb, arguments=None):
+    return {
+        "arguments": json.dumps(arguments or {}),
+        "host_memory_peak_rss_mb": peak_mb,
+    }
+
+
+def for_each_workflow(release=False):
+    step = {
+        "name": "shot",
+        "for_each": "variable:shots",
+        "task": "noop",
+    }
+    if release:
+        step["release_pipeline"] = True
+    return {"id": "w", "variables": {"shots": []}, "steps": [step]}
+
+
+class TestReleaseDetection:
+    def test_no_for_each_step_is_treated_as_released(self):
+        definition = {"id": "w", "variables": {}, "steps": [{"name": "a"}]}
+        assert releases_between_iterations(definition) is True
+
+    def test_release_pipeline_on_the_for_each_step_is_released(self):
+        assert releases_between_iterations(for_each_workflow(release=True)) is True
+
+    def test_no_release_flag_keeps_the_pipeline_resident(self):
+        assert releases_between_iterations(for_each_workflow(release=False)) is False
+
+
+class TestProjection:
+    def test_cold_start_warns_nothing(self):
+        definition = for_each_workflow(release=False)
+        warnings = host_memory_warnings(definition, {"shots": 12}, [], 10_000 * MB)
+        assert warnings == []
+
+    def test_history_with_no_memory_reading_warns_nothing(self):
+        definition = for_each_workflow(release=False)
+        rows = [
+            {
+                "arguments": json.dumps({"shots": [1, 2, 3]}),
+                "host_memory_peak_rss_mb": None,
+            }
+        ]
+        warnings = host_memory_warnings(definition, {"shots": 12}, rows, 10_000 * MB)
+        assert warnings == []
+
+    def test_resident_pipeline_projects_per_entry_times_requested_count(self):
+        definition = for_each_workflow(release=False)
+        # 3-entry runs each peaked at 3000 MB -> 1000 MB/entry; 12 entries
+        # projects to 12000 MB, over an 8000 MB ceiling
+        rows = [row(3000 * MB, {"shots": [1, 2, 3]}) for _ in range(3)]
+        warnings = host_memory_warnings(definition, {"shots": 12}, rows, 8_000 * MB)
+        assert len(warnings) == 1
+        assert "12000" in warnings[0] or "12,000" in warnings[0]
+
+    def test_resident_pipeline_under_the_ceiling_warns_nothing(self):
+        definition = for_each_workflow(release=False)
+        rows = [row(3000 * MB, {"shots": [1, 2, 3]}) for _ in range(3)]
+        warnings = host_memory_warnings(definition, {"shots": 4}, rows, 8_000 * MB)
+        assert warnings == []
+
+    def test_released_pipeline_projects_the_largest_single_iteration(self):
+        definition = for_each_workflow(release=True)
+        # Released between iterations: projection does not scale with count,
+        # since only one entry's pipeline is ever resident at a time
+        rows = [row(3000 * MB, {"shots": [1, 2, 3]}), row(3200 * MB, {"shots": [1]})]
+        warnings = host_memory_warnings(definition, {"shots": 12}, rows, 8_000 * MB)
+        assert warnings == []
+
+    def test_released_pipeline_over_the_ceiling_still_warns(self):
+        definition = for_each_workflow(release=True)
+        rows = [row(9000 * MB, {"shots": [1, 2, 3]})]
+        warnings = host_memory_warnings(definition, {"shots": 12}, rows, 8_000 * MB)
+        assert len(warnings) == 1
+
+    def test_no_list_in_this_request_warns_nothing(self):
+        definition = for_each_workflow(release=False)
+        rows = [row(9000 * MB, {"shots": [1, 2, 3]})]
+        warnings = host_memory_warnings(definition, {}, rows, 100 * MB)
+        assert warnings == []

From 60d2c0f318286e8e62535ef6aa7ea5799c1c593c Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sat, 19 Sep 2026 19:36:16 -0500
Subject: [PATCH 68/77] feat(tasks): #245 - add frame_grid contact-sheet task

Tiles frames sampled evenly across a clip's full duration into one
image, so a clip's shape can be previewed without authoring a
frames-extraction workflow. Grid defaults to biased-wide
(columns >= rows), tile size follows the source aspect ratio, and each
tile is labeled with its sampled timestamp (or frame index when the
video carries no fps) unless label=false.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 dw/task_domains.py        |   1 +
 dw/tasks/task.py          |   9 +++
 dw/tasks/video_utils.py   | 114 ++++++++++++++++++++++++++++++++++++++
 tests/test_video_utils.py | 102 ++++++++++++++++++++++++++++++++++
 4 files changed, 226 insertions(+)

diff --git a/dw/task_domains.py b/dw/task_domains.py
index fc7f6704..0993b79e 100644
--- a/dw/task_domains.py
+++ b/dw/task_domains.py
@@ -96,6 +96,7 @@
         "sample_rate": POSITIVE,
     },
     "loop_frames": {"num_frames": POSITIVE},
+    "frame_grid": {"count": POSITIVE, "columns": POSITIVE, "tile_width": POSITIVE},
     "dissolve_videos": {
         "dissolve_frames": NON_NEGATIVE,
         "fade_in_frames": NON_NEGATIVE,
diff --git a/dw/tasks/task.py b/dw/tasks/task.py
index 288273f5..d0fcecff 100644
--- a/dw/tasks/task.py
+++ b/dw/tasks/task.py
@@ -231,6 +231,15 @@ def _handle_loop_frames(task, arguments, previous_pipelines):
     return loop_frames(**arguments)
 
 
+@register_command("frame_grid", implementation="dw.tasks.video_utils.frame_grid")
+def _handle_frame_grid(task, arguments, previous_pipelines):
+    """Tile evenly sampled frames of a video into one contact-sheet image"""
+    logger.debug("Building frame grid")
+    from .video_utils import frame_grid
+
+    return frame_grid(**arguments)
+
+
 @register_command("pair_audio", implementation="dw.tasks.pair_audio.pair_audio")
 def _handle_pair_audio(task, arguments, previous_pipelines):
     """Pair a video's frames with an audio track generated beside them"""
diff --git a/dw/tasks/video_utils.py b/dw/tasks/video_utils.py
index f636ac94..fcf5fe67 100644
--- a/dw/tasks/video_utils.py
+++ b/dw/tasks/video_utils.py
@@ -8,6 +8,7 @@
 """
 
 import logging
+import math
 import re
 
 import numpy
@@ -173,6 +174,119 @@ def loop_frames(video, num_frames):
     return numpy.concatenate([frames] * laps, axis=0)[:num_frames]
 
 
+def frame_grid(video, count=12, columns=None, tile_width=320, label=True):
+    """Task command: tile evenly sampled frames of a video into one contact
+    sheet - a preview of a clip's shape without authoring a frames-extraction
+    workflow (#245).
+
+    Args:
+        video: Frames in any shape a result carries
+        count: How many frames to sample, spaced evenly across the clip's
+            full duration (including its first and last frame). Clamped to
+            the clip's own frame count when the clip is shorter
+        columns: Tiles per row. Defaults to a grid biased wide - clips are
+            usually landscape - with the last row left-justified when
+            `count` is not a perfect multiple of it
+        tile_width: Width in pixels of each tile; height follows the source
+            frame's aspect ratio
+        label: Burn the sampled timestamp (or frame index, when the video
+            carries no frame rate) into each tile's corner
+
+    Returns:
+        One PIL image, the tiled contact sheet
+    """
+    count = _positive_int(count, "frame_grid", "count")
+    if columns is not None:
+        columns = _positive_int(columns, "frame_grid", "columns")
+    tile_width = _positive_int(tile_width, "frame_grid", "tile_width")
+    if not isinstance(label, bool):
+        raise ValueError(f"frame_grid needs 'label' as true or false, got {label!r}")
+
+    total = frame_count(video)
+    if total == 0:
+        raise ValueError("frame_grid was given a video with no frames")
+    count = min(count, total)
+    fps = getattr(video, "fps", None)
+
+    indices = _evenly_spaced_indices(total, count)
+    tiles = [
+        _grid_tile(extract_frame(video, index), index, fps, tile_width, label)
+        for index in indices
+    ]
+
+    if columns is None:
+        columns = _default_columns(len(tiles))
+    return _compose_grid(tiles, columns)
+
+
+def _positive_int(value, command, name):
+    if isinstance(value, str):
+        try:
+            value = int(value)
+        except ValueError:
+            raise ValueError(f"{command} needs '{name}' as a whole number, got {value!r}")
+    if not isinstance(value, int) or isinstance(value, bool):
+        raise ValueError(f"{command} needs '{name}' as a whole number, got {value!r}")
+    if value < 1:
+        raise ValueError(f"{command} needs '{name}' of at least 1, got {value}")
+    return value
+
+
+def _evenly_spaced_indices(total, count):
+    """`count` frame indices spaced evenly across [0, total - 1], inclusive
+    of both ends. Rounding can coincide two spacings on one index in a short
+    clip; those collapse rather than repeating the same frame as a tile."""
+    if count == 1:
+        return [0]
+    raw = numpy.linspace(0, total - 1, num=count)
+    seen = []
+    for value in raw.round().astype(int).tolist():
+        if not seen or seen[-1] != value:
+            seen.append(value)
+    return seen
+
+
+def _default_columns(count):
+    """A grid biased wide: rows no more than columns, columns >= sqrt(count)."""
+    rows = math.isqrt(count) or 1
+    return math.ceil(count / rows)
+
+
+def _grid_tile(frame, index, fps, tile_width, label):
+    tile_height = max(1, round(frame.height * tile_width / frame.width))
+    tile = frame.resize((tile_width, tile_height), Image.LANCZOS).convert("RGB")
+    if not label:
+        return tile
+
+    from PIL import ImageDraw, ImageFont
+
+    text = _format_timestamp(index, fps) if fps else f"#{index}"
+    draw = ImageDraw.Draw(tile)
+    font_size = max(10, tile_width // 16)
+    try:
+        font = ImageFont.truetype("Arial", font_size)
+    except (IOError, OSError):
+        font = ImageFont.load_default(size=font_size)
+    draw.text((4, 4), text, font=font, fill="white", stroke_width=2, stroke_fill="black")
+    return tile
+
+
+def _format_timestamp(index, fps):
+    seconds = index / fps
+    minutes, remainder = divmod(seconds, 60)
+    return f"{int(minutes):02d}:{remainder:04.1f}"
+
+
+def _compose_grid(tiles, columns):
+    tile_width, tile_height = tiles[0].size
+    rows = math.ceil(len(tiles) / columns)
+    grid = Image.new("RGB", (columns * tile_width, rows * tile_height), (0, 0, 0))
+    for position, tile in enumerate(tiles):
+        row, col = divmod(position, columns)
+        grid.paste(tile, (col * tile_width, row * tile_height))
+    return grid
+
+
 def is_video(value):
     """Whether a value is a run of frames rather than one image.
 
diff --git a/tests/test_video_utils.py b/tests/test_video_utils.py
index cb8f6e7d..114ff3fe 100644
--- a/tests/test_video_utils.py
+++ b/tests/test_video_utils.py
@@ -471,6 +471,108 @@ def test_a_numeric_string_is_taken(self):
         assert len(loop_frames(Image.new("RGB", (2, 2)), "121")) == 121
 
 
+class TestFrameGrid:
+    """#245. A contact sheet for previewing a clip's shape without authoring
+    a frames-extraction workflow."""
+
+    @pytest.fixture
+    def clip(self):
+        from dw.tasks.video_utils import FrameList
+
+        frames = FrameList(
+            Image.new("RGB", (64, 32), (index, 0, 0)) for index in range(30)
+        )
+        frames.fps = 24
+        return frames
+
+    def test_default_tiling(self, clip):
+        from dw.tasks.video_utils import frame_grid
+
+        grid = frame_grid(clip)
+
+        # count=12 -> rows=isqrt(12)=3, columns=ceil(12/3)=4, tile 320 wide
+        # (source 64x32 halved-aspect at width 320 -> height 160)
+        assert grid.size == (4 * 320, 3 * 160)
+
+    def test_custom_columns(self, clip):
+        from dw.tasks.video_utils import frame_grid
+
+        grid = frame_grid(clip, count=5, columns=2, tile_width=100)
+
+        # 5 tiles over 2 columns is 3 rows, last row left-justified
+        assert grid.size == (2 * 100, 3 * 50)
+
+    def test_count_is_clamped_to_the_available_frames(self, clip):
+        from dw.tasks.video_utils import frame_grid
+
+        grid = frame_grid(clip, count=100, tile_width=64)
+
+        # clamped to 30 -> rows=isqrt(30)=5, columns=ceil(30/5)=6
+        assert grid.size == (6 * 64, 5 * 32)
+
+    def test_a_single_tile(self, clip):
+        from dw.tasks.video_utils import frame_grid
+
+        assert frame_grid(clip, count=1, tile_width=160).size == (160, 80)
+
+    def test_label_true_burns_in_a_timestamp(self, clip):
+        from dw.tasks.video_utils import frame_grid
+
+        labeled = frame_grid(clip, count=4, tile_width=64, label=True)
+        unlabeled = frame_grid(clip, count=4, tile_width=64, label=False)
+
+        assert numpy.asarray(labeled).tobytes() != numpy.asarray(unlabeled).tobytes()
+
+    def test_label_falls_back_to_frame_index_without_fps(self):
+        from dw.tasks.video_utils import frame_grid
+
+        frames = [Image.new("RGB", (64, 32), (index, 0, 0)) for index in range(10)]
+
+        # No .fps attribute on a bare list - must not raise
+        assert frame_grid(frames, count=4, tile_width=32).size == (2 * 32, 2 * 16)
+
+    def test_a_count_below_one_is_refused(self, clip):
+        from dw.tasks.video_utils import frame_grid
+
+        with pytest.raises(ValueError, match="count"):
+            frame_grid(clip, count=0)
+
+    def test_a_negative_count_is_refused(self, clip):
+        from dw.tasks.video_utils import frame_grid
+
+        with pytest.raises(ValueError, match="count"):
+            frame_grid(clip, count=-1)
+
+    def test_a_non_integer_columns_is_refused(self, clip):
+        from dw.tasks.video_utils import frame_grid
+
+        with pytest.raises(ValueError, match="columns"):
+            frame_grid(clip, columns="many")
+
+    def test_a_non_integer_tile_width_is_refused(self, clip):
+        from dw.tasks.video_utils import frame_grid
+
+        with pytest.raises(ValueError, match="tile_width"):
+            frame_grid(clip, tile_width=0)
+
+    def test_a_non_bool_label_is_refused(self, clip):
+        from dw.tasks.video_utils import frame_grid
+
+        with pytest.raises(ValueError, match="label"):
+            frame_grid(clip, label="yes")
+
+    def test_registered_as_a_task_command(self):
+        from dw.tasks.task import _COMMAND_REGISTRY
+
+        assert "frame_grid" in _COMMAND_REGISTRY
+
+    def test_a_numeric_string_count_is_taken(self, clip):
+        """A count that arrived through a `variable:` may still be a string."""
+        from dw.tasks.video_utils import frame_grid
+
+        assert frame_grid(clip, count="4", tile_width=32).size == (2 * 32, 2 * 16)
+
+
 class TestFitAudioToFrames:
     """Codec padding trimmed off a generated track, in whatever layout the
     waveform arrived in.

From bc82afa7a3f2c84bc65c4107e1ddcd08d3989829 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sat, 19 Sep 2026 20:01:34 -0500
Subject: [PATCH 69/77] fix(mcp): #248 - env-configurable wait_for_job cap;
 #249 - compact list_assets/list_workspaces

DW_MCP_MAX_WAIT_SECONDS overrides wait_for_job's 55s block-per-call cap for
a deployment whose harness tolerates a longer tool call, so one call can
cover a whole short job instead of several polls; unset, behavior is
unchanged. list_assets and list_workspaces now default to a compact
per-entry shape (name/reference/kind/size/origin, and
name/default/usage respectively) with a detail=true flag for the full
entry, mirroring list_workflows' #101 summary/full split - a server with
months of accumulated workspaces/assets no longer answers in the tens of
KB for a question that's usually "what's here and how big."

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 dw_mcp/assets.py     | 41 +++++++++++++++++++++++++++++++++++++++--
 dw_mcp/diagnose.py   | 17 ++++++++++++-----
 dw_mcp/server.py     | 30 ++++++++++++++++++------------
 dw_mcp/workspaces.py | 38 ++++++++++++++++++++++++++++++++++++--
 4 files changed, 105 insertions(+), 21 deletions(-)

diff --git a/dw_mcp/assets.py b/dw_mcp/assets.py
index aa76dc02..e7dbadd6 100644
--- a/dw_mcp/assets.py
+++ b/dw_mcp/assets.py
@@ -114,7 +114,20 @@ def _confine_source(path, roots, named):
     )
 
 
-def list_assets(client):
+# What a compact asset entry keeps: enough to name and choose one, nothing
+# that only opening or previewing it needs
+ASSET_SUMMARY_FIELDS = ("name", "reference", "kind", "size", "origin")
+
+
+def _summarised_asset_entries(entries):
+    return [
+        {key: entry.get(key) for key in ASSET_SUMMARY_FIELDS if key in entry}
+        for entry in entries
+        if isinstance(entry, dict)
+    ]
+
+
+def list_assets(client, detail=False):
     """The input media on the server, each with the 'asset:' reference a
     workflow argument carries.
 
@@ -126,8 +139,32 @@ def list_assets(client):
     nearer library hides - present in a farther root but not resolvable by
     'asset:', since the nearer file wins; a shadowed entry carries no 'url'
     because that URL would serve the file that shadows it.
+
+    Compact by default - each `assets`/`shadowed` entry cut to
+    `name`/`reference`/`kind`/`size`/`origin` - because a library that has
+    accumulated months of episode and regression assets answers in the tens
+    of KB otherwise for a question that is usually "what's available and
+    under what name" (#249). Pass `detail=True` for each entry's `folder`,
+    `mtime` and `url` too.
     """
-    return client.get_json("/api/assets")
+    result = client.get_json("/api/assets")
+    if detail:
+        return result
+    assets = result.get("assets")
+    shadowed = result.get("shadowed")
+    if not isinstance(assets, list):
+        return result
+    return {
+        **result,
+        "assets": _summarised_asset_entries(assets),
+        "shadowed": _summarised_asset_entries(shadowed)
+        if isinstance(shadowed, list)
+        else shadowed,
+        "note": (
+            "Compact: each entry is name/reference/kind/size/origin only. "
+            "Call list_assets(detail=True) for folder, mtime and url too."
+        ),
+    }
 
 
 def delete_asset(client, name):
diff --git a/dw_mcp/diagnose.py b/dw_mcp/diagnose.py
index ee08976e..7356a993 100644
--- a/dw_mcp/diagnose.py
+++ b/dw_mcp/diagnose.py
@@ -7,6 +7,7 @@
 progress is polled from the event log.
 """
 
+import os
 import time
 
 from dw_mcp.client import DwApiError, api_path
@@ -19,8 +20,11 @@
 
 # A generation can run for minutes, far longer than an MCP client holds a
 # tool call open, so wait_for_job's own budget stays well under that no
-# matter what a caller asks for.
-MAX_WAIT_SECONDS = 55
+# matter what a caller asks for. Some clients hold a tool call open far
+# longer than the 55s this was tuned against (#248), so a deployment that
+# knows its own harness's tool-call budget can raise the cap with
+# DW_MCP_MAX_WAIT_SECONDS - unset, it stays 55.
+MAX_WAIT_SECONDS = float(os.environ.get("DW_MCP_MAX_WAIT_SECONDS", 55))
 
 COST_REFUSAL = (
     "Running a workflow occupies the GPU for minutes and the engine runs one "
@@ -206,9 +210,12 @@ def wait_for_job(client, job_id, timeout_seconds=20):
 
     `timeout_seconds` is clamped to [0, MAX_WAIT_SECONDS]: a generation can
     run for minutes, far longer than an MCP client holds a tool call open,
-    so this never blocks past a budget kept well under that. Every reply
-    says what was applied - `timeout_applied_seconds` is the budget the
-    call actually ran under, `timeout_requested_seconds` what was asked
+    so this never blocks past a budget kept well under that - 55s by
+    default, raised for a deployment whose harness tolerates a longer tool
+    call via the `DW_MCP_MAX_WAIT_SECONDS` env var, in which case one call
+    can cover a whole short job rather than needing several polls. Every
+    reply says what was applied - `timeout_applied_seconds` is the budget
+    the call actually ran under, `timeout_requested_seconds` what was asked
     for, and `waited_seconds` how long this call blocked - so a caller
     asking for 600 can tell a capped return from an elapsed one rather
     than inferring it from wall clock. Returns as soon as the job's status
diff --git a/dw_mcp/server.py b/dw_mcp/server.py
index 672754ed..13374f7f 100644
--- a/dw_mcp/server.py
+++ b/dw_mcp/server.py
@@ -652,14 +652,17 @@ def download_output(
 
     # ---------------------------------------------------------------- assets
 
-    def list_assets() -> dict:
+    def list_assets(detail: bool = False) -> dict:
         """List the input media on the server, each with the "asset:"
         reference a workflow argument carries. Look here before asking for
         a file: what a workflow needs may already be there. Entries carry
-        name, kind, size and origin only - for one asset's duration, frame
-        count, fps, sample rate or channels, pass its reference to
-        `get_gallery_metadata`, which reads inputs as well as outputs."""
-        return assets.list_assets(client)
+        name, reference, kind, size and origin only - for one asset's
+        duration, frame count, fps, sample rate or channels, pass its
+        reference to `get_gallery_metadata`, which reads inputs as well as
+        outputs. Pass detail=true for each entry's folder, mtime and url
+        too, needed before naming a shared library's writable/read-only
+        roots or opening the file's preview URL."""
+        return assets.list_assets(client, detail=detail)
 
     def upload_asset(
         file_path: str | None = None,
@@ -752,15 +755,17 @@ def delete_asset(name: str) -> dict:
 
     # ------------------------------------------------------------ workspaces
 
-    def list_workspaces() -> dict:
+    def list_workspaces(detail: bool = False) -> dict:
         """List the server's workspaces and say which one this session is
         working in. Each has its own workflows, assets and outputs; the
         stored prompt library is shared by all of them, and so is the
         shared asset library that `upload_asset(shared=true)` and
         `keep_output(shared=true)` write into - which is how a recurring
         cast stays reachable from the workspace the next piece is made
-        in."""
-        return workspaces.list_workspaces(client)
+        in. Entries carry name, default and usage (files/bytes) only; pass
+        detail=true for each entry's full folder paths (workflows, assets,
+        outputs, prompts, common_assets)."""
+        return workspaces.list_workspaces(client, detail=detail)
 
     def use_workspace(name: str) -> dict:
         """Work in a different workspace for the rest of this session - every
@@ -1080,10 +1085,11 @@ def wait_for_job(job_id: str, timeout_seconds: int = 20) -> dict:
         can call again. Does not queue anything, so no acknowledged_cost.
 
         One call blocks for at most {cap} seconds, no matter what
-        timeout_seconds asks for - an MCP client will not hold a tool call
-        open for a generation's real runtime, which is minutes. A larger
-        value is not honoured, it is clamped, so budget roughly one call per
-        {cap}s of the job. Every reply says which happened: waited_seconds,
+        timeout_seconds asks for - this deployment's cap, set for the tool
+        call budget the MCP client actually holds open. A larger value is
+        not honoured, it is clamped, so budget roughly one call per {cap}s
+        of the job - if {cap} covers the job's whole runtime, one call is
+        enough. Every reply says which happened: waited_seconds,
         timeout_requested_seconds, timeout_applied_seconds and
         timeout_capped.
 
diff --git a/dw_mcp/workspaces.py b/dw_mcp/workspaces.py
index 0c6368be..e323fe6a 100644
--- a/dw_mcp/workspaces.py
+++ b/dw_mcp/workspaces.py
@@ -12,9 +12,43 @@
 from dw_mcp import catalog
 
 
-def list_workspaces(client):
-    """The workspaces on the server, and which one this session is using."""
+# What a compact workspace entry keeps: enough to choose one or judge its
+# size, nothing that only naming its folders needs
+WORKSPACE_SUMMARY_FIELDS = ("name", "default", "usage")
+
+
+def list_workspaces(client, detail=False):
+    """The workspaces on the server, and which one this session is using.
+
+    Compact by default - each entry cut to `name`, `default` and `usage`
+    (files/bytes) - because a server that has accumulated dozens of
+    workspaces across episodes and regression runs answers in the tens of
+    KB otherwise for a question that is usually "which workspaces exist and
+    how big are they" (#249). Pass `detail=True` for each entry's full
+    folder paths (`root`, `workflows`, `assets`, `outputs`, `prompts`,
+    `common_assets`), needed before naming one to `use_workspace` or a
+    remote read.
+    """
     result = client.get_json("/api/workspaces")
+    if not detail:
+        entries = result.get("workspaces")
+        if isinstance(entries, list):
+            result = {
+                **result,
+                "workspaces": [
+                    {
+                        key: entry.get(key)
+                        for key in WORKSPACE_SUMMARY_FIELDS
+                        if key in entry
+                    }
+                    for entry in entries
+                    if isinstance(entry, dict)
+                ],
+                "note": (
+                    "Compact: each entry is name/default/usage only. Call "
+                    "list_workspaces(detail=True) for full folder paths."
+                ),
+            }
     return {**result, "current": client.workspace}
 
 

From f3e7cc145a1eb67b3b20230de20e95c17af6ebc5 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sat, 19 Sep 2026 20:11:48 -0500
Subject: [PATCH 70/77] fix(plan): #252 - name the unpriced contributors in a
 partial estimate

plan.estimate now carries unpriced: [] alongside partial, naming the
workflow's own id when its own steps went unpriced and each composed
child's path when its cost block is missing or unreadable, so a caller
can tell a trivial utility step from an unpriced multi-shot loop apart
instead of just seeing partial: true. UI plan.ts/types.ts surface it too.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 dw/plan.py              |  9 ++++++++-
 tests/test_plan.py      | 11 +++++++++++
 tests/test_server.py    |  1 +
 ui/src/lib/plan.test.ts |  6 ++++--
 ui/src/lib/plan.ts      |  4 ++--
 ui/src/lib/types.ts     |  4 ++++
 6 files changed, 30 insertions(+), 5 deletions(-)

diff --git a/dw/plan.py b/dw/plan.py
index b1dc1c65..2d34469e 100644
--- a/dw/plan.py
+++ b/dw/plan.py
@@ -320,8 +320,11 @@ def estimate(
     # only from a priced child is not a complete figure - the parent's own
     # steps (a for_each step with no cost block, say) contributed nothing to
     # it, so the sum understates the run rather than merely omitting a piece
-    # of it (#242)
+    # of it (#242). `unpriced` names each contributor that landed here, so a
+    # caller can tell a trivial utility step from an unpriced 12-shot loop
+    # apart rather than just seeing `partial: true` (#252)
     partial = minutes is None
+    unpriced = [definition.get("id", "workflow")] if partial else []
     for path in _sub_workflow_paths(expanded):
         # A builtin is the parent's to price; a local child prices itself
         raw = read_sub_workflow(path, base_dir, workflow_dir)
@@ -334,18 +337,21 @@ def estimate(
         child = _price(child_cost, device, {}, {})
         if child["minutes"] is None:
             partial = True
+            unpriced.append(path)
         elif minutes is not None:
             minutes += child["minutes"]
         else:
             minutes = child["minutes"]
     if minutes is None:
         partial = False
+        unpriced = []
     return {
         "minutes": round(minutes, 1) if minutes is not None else None,
         "basis": own["basis"],
         "device": device,
         "measured_on": own["measured_on"],
         "partial": partial,
+        "unpriced": unpriced,
         "runs": None,
     }
 
@@ -374,6 +380,7 @@ def _observed(observed, device):
         "device": device,
         "measured_on": observed.get("name"),
         "partial": False,
+        "unpriced": [],
         "runs": runs,
     }
 
diff --git a/tests/test_plan.py b/tests/test_plan.py
index eb3647b3..d51d7fbf 100644
--- a/tests/test_plan.py
+++ b/tests/test_plan.py
@@ -240,6 +240,7 @@ def test_no_cost_block_is_unknown(self, plan):
             "device": "cuda",
             "measured_on": None,
             "partial": False,
+            "unpriced": [],
             "runs": None,
         }
 
@@ -257,6 +258,7 @@ def test_the_serving_devices_entry_is_the_catalog_figure(self, plan):
             "device": "cuda",
             "measured_on": "4090",
             "partial": False,
+            "unpriced": [],
             "runs": None,
         }
 
@@ -269,6 +271,7 @@ def test_another_devices_entry_is_reported_as_such(self, plan):
             "device": "cuda",
             "measured_on": "M2",
             "partial": False,
+            "unpriced": [],
             "runs": None,
         }
 
@@ -397,6 +400,7 @@ def test_history_is_quoted_when_there_is_no_cost_block(self, plan):
             "device": "cuda",
             "measured_on": "RTX 3090",
             "partial": False,
+            "unpriced": [],
             "runs": 11,
         }
 
@@ -446,6 +450,7 @@ def test_a_composed_child_is_not_added_to_an_observed_figure(self, plan, tmp_pat
         answer = plan(composing("child.json"), observed=observed(minutes=6))["estimate"]
         assert answer["minutes"] == 6.0
         assert answer["partial"] is False
+        assert answer["unpriced"] == []
 
 
 def composing(child_path):
@@ -465,19 +470,23 @@ def test_a_childs_catalog_cost_is_added(self, plan, tmp_path):
         (tmp_path / "child.json").write_text(json.dumps(child))
         answer = plan(composing("child.json"))["estimate"]
         assert (answer["minutes"], answer["partial"]) == (7.0, False)
+        assert answer["unpriced"] == []
 
     def test_a_child_without_a_cost_makes_the_estimate_partial(self, plan, tmp_path):
         (tmp_path / "child.json").write_text(json.dumps({"id": "child", "steps": []}))
         answer = plan(composing("child.json"))["estimate"]
         assert (answer["minutes"], answer["partial"]) == (2.0, True)
+        assert answer["unpriced"] == ["child.json"]
 
     def test_an_unreadable_child_makes_the_estimate_partial(self, plan):
         answer = plan(composing("missing.json"))["estimate"]
         assert (answer["minutes"], answer["partial"]) == (2.0, True)
+        assert answer["unpriced"] == ["missing.json"]
 
     def test_a_builtin_adds_nothing_and_is_not_partial(self, plan):
         answer = plan(composing("builtin:text-to-image.json"))["estimate"]
         assert (answer["minutes"], answer["partial"]) == (2.0, False)
+        assert answer["unpriced"] == []
 
     def test_an_unpriced_parent_with_a_priced_child_is_partial(self, plan, tmp_path):
         """A for_each step with no cost block contributes nothing to the
@@ -497,12 +506,14 @@ def test_an_unpriced_parent_with_a_priced_child_is_partial(self, plan, tmp_path)
         }
         answer = plan(parent)["estimate"]
         assert (answer["minutes"], answer["partial"]) == (5.0, True)
+        assert answer["unpriced"] == ["parent"]
 
     def test_a_fully_unpriced_workflow_is_unknown_not_partial(self, plan):
         """No cost block anywhere - 'unknown' already says nobody has a
         number; 'partial' would wrongly imply some of it is known."""
         answer = plan({"id": "parent", "steps": []})["estimate"]
         assert (answer["minutes"], answer["partial"]) == (None, False)
+        assert answer["unpriced"] == []
 
     def test_a_child_measured_on_another_device_is_still_added(self, plan, tmp_path):
         child = {"id": "child", "cost": [cost("mps", 5)], "steps": []}
diff --git a/tests/test_server.py b/tests/test_server.py
index b72ecca4..712bafb3 100644
--- a/tests/test_server.py
+++ b/tests/test_server.py
@@ -3976,6 +3976,7 @@ def observed(self, name, definition, arguments=None):
             "device": serving,
             "measured_on": "RTX 3090",
             "partial": False,
+            "unpriced": [],
             "runs": 11,
         }
         assert asked == [("Basic", {"prompt": "x"})]
diff --git a/ui/src/lib/plan.test.ts b/ui/src/lib/plan.test.ts
index 4f218a96..005f3196 100644
--- a/ui/src/lib/plan.test.ts
+++ b/ui/src/lib/plan.test.ts
@@ -15,6 +15,7 @@ const base: Plan = {
     device: 'cuda',
     measured_on: 'RTX 3090',
     partial: false,
+    unpriced: [],
   },
 }
 
@@ -76,6 +77,7 @@ describe('describePlan', () => {
         device: 'cuda',
         measured_on: null,
         partial: false,
+        unpriced: [],
       },
     })
     expect(figure.text).toBe('no measured cost')
@@ -85,9 +87,9 @@ describe('describePlan', () => {
   it('a partial figure names what it is missing', () => {
     const [, figure] = describePlan({
       ...base,
-      estimate: { ...base.estimate, partial: true },
+      estimate: { ...base.estimate, partial: true, unpriced: ['child.json'] },
     })
-    expect(figure.text).toContain('plus a composed workflow with no cost')
+    expect(figure.text).toContain('plus unpriced: child.json')
   })
 
   it('an unknown cache answer and a single step read naturally', () => {
diff --git a/ui/src/lib/plan.ts b/ui/src/lib/plan.ts
index a8a3584b..5889f7ba 100644
--- a/ui/src/lib/plan.ts
+++ b/ui/src/lib/plan.ts
@@ -62,9 +62,9 @@ export function describePlan(plan: Plan): PlanLine[] {
 }
 
 function figure(plan: Plan): PlanLine {
-  const { minutes, basis, device, measured_on, partial } = plan.estimate
+  const { minutes, basis, device, measured_on, partial, unpriced } = plan.estimate
   const card = measured_on ? `measured on ${measured_on}` : 'measured'
-  const missing = partial ? ', plus a composed workflow with no cost' : ''
+  const missing = partial ? `, plus unpriced: ${(unpriced ?? []).join(', ')}` : ''
   if (basis === 'unknown' || minutes === null) {
     return { text: 'no measured cost', tone: 'warn' }
   }
diff --git a/ui/src/lib/types.ts b/ui/src/lib/types.ts
index ad80c761..d1dabb7c 100644
--- a/ui/src/lib/types.ts
+++ b/ui/src/lib/types.ts
@@ -249,6 +249,10 @@ export interface Plan {
     device: string
     measured_on: string | null
     partial: boolean
+    /** What contributed nothing to `minutes` when `partial` is true - the
+     * workflow's own id when its own steps went unpriced, else the path of
+     * each composed child with no cost block. Empty when `partial` is false. */
+    unpriced: string[]
   }
 }
 

From 162fa8ea0ed2c7ca0c247db208cbe93712685627 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sat, 19 Sep 2026 21:00:07 -0500
Subject: [PATCH 71/77] fix(cache): #253 - give reference dataclasses real
 value equality

realize_args builds diffusers reference dataclasses (MiniMaxH3ImageReference,
MiniMaxH3VideoReference, MiniMaxH3AudioReference, LTX2ReferenceCondition) fresh
from from_file() on every run, wrapping PIL.Image/np.ndarray/torch.Tensor
fields. deep_equal's old generic fallback (bool(a == b), catching
ValueError/TypeError/RuntimeError as unequal) could never tell two such
instances apart: PIL.Image has no value equality, and comparing tensor/array
fields raises inside the dataclass's generated __eq__. That made any step
carrying an image/audio/video reference argument - especially for_each members
in identity-referenced templates like minimax/dialogue-short - an
unconditional cache miss regardless of whether its inputs actually changed.

deep_equal now special-cases PIL.Image, np.ndarray, torch.Tensor and generic
dataclasses (recursing field by field) ahead of the fallback. Also added
debug logging to every early-return branch in StepCache.get() so a miss's
cause is diagnosable from logs without a new event kind.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 dw/step_cache.py         | 53 ++++++++++++++++++++++++++++++++++------
 tests/test_step_cache.py | 47 ++++++++++++++++++++++++++++++++---
 2 files changed, 89 insertions(+), 11 deletions(-)

diff --git a/dw/step_cache.py b/dw/step_cache.py
index e1a687ec..8210368e 100644
--- a/dw/step_cache.py
+++ b/dw/step_cache.py
@@ -45,11 +45,16 @@
 """
 
 import copy
+import dataclasses
 import itertools
 import logging
 import os
 from collections import OrderedDict
 
+import numpy as np
+import torch
+from PIL import Image
+
 logger = logging.getLogger("dw")
 
 # Monotonic across the process: every put stamps its entry, and a downstream
@@ -98,7 +103,22 @@ def scan(value):
 
 
 def deep_equal(a, b):
-    """Value equality across the JSON-ish types a resolved step definition holds."""
+    """Value equality across the JSON-ish types a resolved step definition holds.
+
+    realize_args runs before the step loop (and before for_each expansion's
+    per-member `from_file` construction), so a resolved argument can be a
+    diffusers reference dataclass wrapping in-memory media - a
+    MiniMaxH3ImageReference, an LTX2ReferenceCondition - built fresh by
+    `from_file()` on every run from the same source file. Two such instances
+    hold identical media but are never `==`: PIL.Image has no value equality
+    (falls back to identity), and comparing torch.Tensor/np.ndarray fields
+    with `==` yields an array rather than a bool, which the dataclass's
+    generated `__eq__` cannot resolve to True/False and which the fallback
+    below (correctly) treats as "cannot tell, so unequal". Left unhandled,
+    that made every for_each member carrying an image/audio/video reference
+    an unconditional cache miss - identical inputs included (#253). These
+    checks give those types real value equality before the generic fallback.
+    """
     if a is b:
         return True
     if type(a) is not type(b):
@@ -107,13 +127,27 @@ def deep_equal(a, b):
         return a.keys() == b.keys() and all(deep_equal(a[k], b[k]) for k in a)
     if isinstance(a, (list, tuple)):
         return len(a) == len(b) and all(deep_equal(x, y) for x, y in zip(a, b))
+    if isinstance(a, Image.Image):
+        return a.mode == b.mode and a.size == b.size and a.tobytes() == b.tobytes()
+    if isinstance(a, np.ndarray):
+        return a.shape == b.shape and a.dtype == b.dtype and bool(np.array_equal(a, b))
+    if isinstance(a, torch.Tensor):
+        return (
+            a.shape == b.shape
+            and a.dtype == b.dtype
+            and bool(torch.equal(a.cpu(), b.cpu()))
+        )
+    if dataclasses.is_dataclass(a) and not isinstance(a, type):
+        return all(
+            deep_equal(getattr(a, f.name), getattr(b, f.name))
+            for f in dataclasses.fields(a)
+        )
     try:
-        # realize_args runs before the step loop, so a resolved argument can
-        # hold a numpy array or a tensor, whose == yields an array rather
-        # than a bool (and an exotic object's == can raise outright). A value
-        # that cannot answer "are these equal" cleanly is treated as unequal:
-        # a cache miss just re-runs the step, where a raised exception would
-        # abort the whole run
+        # An exotic object's == can still raise, or (for a type not caught
+        # above) return something other than a bool. A value that cannot
+        # answer "are these equal" cleanly is treated as unequal: a cache
+        # miss just re-runs the step, where a raised exception would abort
+        # the whole run
         return bool(a == b)
     except (ValueError, TypeError, RuntimeError):
         return False
@@ -160,17 +194,22 @@ def get(
         key = (workflow_id, name)
         entry = self._entries.get(key)
         if entry is None:
+            logger.debug(f"No cache entry for step '{name}' - treating as a miss")
             return None
         if entry["step_seed"] != step_seed:
+            logger.debug(f"Cached result for step '{name}' used a different seed - treating as a miss")
             return None
         # The output *root* a run was told to write to. A run directory is
         # new every execution and would defeat the cache; the root changing
         # means the caller asked for output somewhere the cached files are not
         if entry["output_dir"] != output_dir:
+            logger.debug(f"Cached result for step '{name}' used a different output_dir - treating as a miss")
             return None
         if needs_result and not entry["retained"]:
+            logger.debug(f"Cached result for step '{name}' did not retain its Result, and this run needs one - treating as a miss")
             return None
         if not deep_equal(entry["step_data"], step_data):
+            logger.debug(f"Cached result for step '{name}' has different resolved arguments - treating as a miss")
             return None
 
         upstream = referenced_result_names([step_data])
diff --git a/tests/test_step_cache.py b/tests/test_step_cache.py
index 949b7051..980b8e85 100644
--- a/tests/test_step_cache.py
+++ b/tests/test_step_cache.py
@@ -159,16 +159,55 @@ def test_step_cache_miss_when_a_saved_file_was_deleted(tmp_path):
     assert cache.get("w", step_data, 42, set(), "/out", True) is None
 
 
-def test_deep_equal_is_false_rather_than_raising_on_array_values():
+def test_deep_equal_compares_array_values_by_content_rather_than_raising():
     """A realized step argument can hold a numpy array (or a tensor), whose
-    == yields an array, not a bool. That must degrade to a cache miss, not
-    abort the run with 'truth value of an array is ambiguous'."""
+    == yields an array, not a bool - that must not abort the run with 'truth
+    value of an array is ambiguous'. Two arrays with the same content are a
+    match (#253: a from_file() reference rebuilt from an unchanged asset on
+    every run must still compare equal to the entry it was cached under),
+    and two with different content are correctly a miss."""
     numpy = pytest.importorskip("numpy")
 
     a = {"latents": numpy.zeros(4), "steps": 9}
     b = {"latents": numpy.zeros(4), "steps": 9}
+    c = {"latents": numpy.ones(4), "steps": 9}
 
-    assert deep_equal(a, b) is False
+    assert deep_equal(a, b) is True
+    assert deep_equal(a, c) is False
+
+
+def test_deep_equal_matches_a_reconstructed_dataclass_holding_an_image():
+    """#253: a from_file() reference (MiniMaxH3ImageReference,
+    LTX2ReferenceCondition, ...) is a dataclass wrapping in-memory media,
+    rebuilt fresh by realize_args on every run of a for_each member that
+    takes an asset: reference - identical content, but never `is` the same
+    object and never `==` by the dataclass's generated equality, since
+    PIL.Image has no value equality and comparing tensor/array fields with
+    `==` cannot resolve to a bool. Without special-casing these, that made
+    every such step an unconditional cache miss."""
+    from dataclasses import dataclass
+
+    from PIL import Image
+
+    numpy = pytest.importorskip("numpy")
+    torch = pytest.importorskip("torch")
+
+    @dataclass
+    class FakeImageReference:
+        image: object
+        weight: float = 1.0
+
+    def load():
+        # A fresh object each call, like from_file() reloading the same file
+        return FakeImageReference(image=Image.new("RGB", (4, 4), color=(1, 2, 3)))
+
+    assert deep_equal(load(), load()) is True
+    assert deep_equal(load(), FakeImageReference(image=Image.new("RGB", (4, 4), color=(9, 9, 9)))) is False
+
+    # The same holds for a reference built straight over an array or tensor
+    assert deep_equal(numpy.zeros((2, 2)), numpy.zeros((2, 2))) is True
+    assert deep_equal(torch.zeros(3), torch.zeros(3)) is True
+    assert deep_equal(torch.zeros(3), torch.ones(3)) is False
 
 
 def test_deep_equal_is_false_when_comparison_raises_a_type_error():

From c4821fb405e2de3c2c955e48e163cb74228c1b13 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sat, 19 Sep 2026 21:06:56 -0500
Subject: [PATCH 72/77] fix(mcp): #254 - don't warn about a host-memory peak
 already survived

host_memory_warnings projected a shape from history and compared it
against the ceiling, but the shape it was warning about could itself be
one of the successful runs in that history - the projection for a
repeat request landed right back on a peak that already ran to
completion on this box without incident.

Add _already_survived: if a historical row (finished_runs() only holds
successes) ran at least as many entries and peaked at or above the
projected figure, suppress the warning - the run being projected
already happened here. Also name the number of history rows the
projection is based on in the warning text, per the issue's basis ask.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 dw/host_memory_projection.py         | 30 +++++++++++++++++++++++++---
 tests/test_host_memory_projection.py | 15 ++++++++++++++
 2 files changed, 42 insertions(+), 3 deletions(-)

diff --git a/dw/host_memory_projection.py b/dw/host_memory_projection.py
index a878c362..63488b83 100644
--- a/dw/host_memory_projection.py
+++ b/dw/host_memory_projection.py
@@ -91,6 +91,28 @@ def _row_count(row, list_entries):
     return max(counts) if counts else None
 
 
+def _already_survived(rows, list_entries, requested, projected_mb):
+    """Whether a run at least as large as this request already finished on
+    this box at or above the projected peak.
+
+    A projection built from this workflow's own history can land above the
+    ceiling for a shape that is itself part of that history - the run being
+    projected already happened and succeeded (#254). `rows` only ever holds
+    successful runs (`JobHistory.finished_runs()`), so a matching row is a
+    completed data point, not a guess: warning about a peak already reached
+    without incident tells a caller nothing they don't already know from ten
+    minutes ago.
+    """
+    for row in rows:
+        peak = row.get("host_memory_peak_rss_mb")
+        if not isinstance(peak, (int, float)) or peak < projected_mb:
+            continue
+        count = _row_count(row, list_entries)
+        if count is not None and count >= requested:
+            return True
+    return False
+
+
 def host_memory_warnings(definition, list_entries, rows, ceiling_mb):
     """Warnings for a projected host-memory peak this machine cannot hold,
     or [] when there is nothing to project from or nothing to warn about.
@@ -129,10 +151,12 @@ def host_memory_warnings(definition, list_entries, rows, ceiling_mb):
         shape = f"{requested} entries held resident together"
     if projected_mb <= ceiling_mb:
         return []
+    if _already_survived(rows, list_entries, requested, projected_mb):
+        return []
     return [
         "Projected host memory for this run (~"
         f"{round(projected_mb)} MB, {shape}) exceeds this machine's usable RAM "
-        f"(~{round(ceiling_mb)} MB) - based on this server's own history for "
-        "this workflow, not a curated figure. The run is not blocked, but it "
-        "may be killed by the OS partway through."
+        f"(~{round(ceiling_mb)} MB) - based on {len(rows)} run(s) of this "
+        "workflow's own history on this machine, not a curated figure. The "
+        "run is not blocked, but it may be killed by the OS partway through."
     ]
diff --git a/tests/test_host_memory_projection.py b/tests/test_host_memory_projection.py
index a2795885..c74924be 100644
--- a/tests/test_host_memory_projection.py
+++ b/tests/test_host_memory_projection.py
@@ -94,3 +94,18 @@ def test_no_list_in_this_request_warns_nothing(self):
         rows = [row(9000 * MB, {"shots": [1, 2, 3]})]
         warnings = host_memory_warnings(definition, {}, rows, 100 * MB)
         assert warnings == []
+
+    def test_identical_shape_that_already_succeeded_warns_nothing(self):
+        # #254: a 2-entry run that just succeeded at ~62 GB shouldn't warn
+        # about a repeat request for the same 2 entries, even though 62 GB
+        # is itself above the ceiling - it already happened without incident.
+        definition = for_each_workflow(release=False)
+        rows = [row(62197 * MB, {"shots": [1, 2]})]
+        warnings = host_memory_warnings(definition, {"shots": 2}, rows, 57788 * MB)
+        assert warnings == []
+
+    def test_larger_request_than_any_survived_shape_still_warns(self):
+        definition = for_each_workflow(release=False)
+        rows = [row(62197 * MB, {"shots": [1, 2]})]
+        warnings = host_memory_warnings(definition, {"shots": 4}, rows, 57788 * MB)
+        assert len(warnings) == 1

From 162da404e9bd2595903d5c2517f62b8493fb48b9 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sun, 20 Sep 2026 07:53:59 -0500
Subject: [PATCH 73/77] docs: #193 - output assessment proposal (probes,
 evidence tools, findings, judging-output skill)

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 docs/proposals/output-assessment.md | 356 ++++++++++++++++++++++++++++
 1 file changed, 356 insertions(+)
 create mode 100644 docs/proposals/output-assessment.md

diff --git a/docs/proposals/output-assessment.md b/docs/proposals/output-assessment.md
new file mode 100644
index 00000000..b91b62ca
--- /dev/null
+++ b/docs/proposals/output-assessment.md
@@ -0,0 +1,356 @@
+# Proposal: output assessment - let an agent measure, look at and listen to what it made
+
+Status: proposed, 2026-09-20. Scopes issue #193 (agent has no way to hear or
+watch generated output), folding in #210 (no `VideoContent` in the MCP SDK)
+and the per-segment `analyze_cut` proposal from #193's thread. Written from
+a design conversation with Don, every section agreed. No code changes yet.
+
+## The goal
+
+An agent that drives `dw` over MCP should be able to assess the quality of a
+generated deliverable and decide whether to redo or tweak it. Four use cases
+drive the design:
+
+1. **Lip-sync synchronisation** - is the speech where the mouth is.
+2. **Seam transitions** - is each join in a cut clean, in the audio and in
+   the picture.
+3. **Continuity between clips** - does shot B look like it belongs after
+   shot A.
+4. **Audio/video contextual alignment** - does the sound swell where the
+   picture does; does the score reach its climax with the cut.
+
+Today the agent has `get_output_image` (stills only), `get_output_audio`
+(audio only, refuses `video/mp4`), `get_gallery_metadata` (whole-file
+duration/level, `envelope=true` for second-by-second rms/peak keyed to time
+rather than to shots), `analyze_audio` (whole-track), `transcribe_audio`,
+and `frame_grid` (#245 - a contact sheet, but only reachable by authoring a
+workflow; no MCP tool wraps it, and the `minimax-h3` skill still says "you
+cannot watch a video"). Nothing measures a seam, a drift, a continuity
+break or an alignment, and nothing gets a frame *pair* at a boundary into
+the agent's context. The issue's own motivating miss - a five-shot cut at
+exactly the right duration whose audio drifted 267 samples per shot and was
+33 ms late by the end - passed every check that exists.
+
+## Decisions taken (with Don, 2026-09-20)
+
+| Question | Decision |
+|---|---|
+| Where does judgement live? | **Tier 1: the engine measures, the agent judges.** Deterministic numbers plus evidence the agent can perceive (frames as `ImageContent`, audio excerpts). No ML judges in the engine. Tier 2 (CLIP/DINO similarity, SyncNet-class sync) and tier 3 (a VLM judge) are marked `TODO` where they would slot in, not built. |
+| How does the agent invoke a measurement? | **Both paths, one implementation.** Measurements are engine tasks (composable into a template's own self-check step, recorded in the manifest, cacheable) *and* run synchronously in the server process over an MCP tool for an output or asset, so a question about a finished file does not queue behind a 20-minute render. |
+| Where do shot boundaries come from? | **Persisted at join time, caller override.** The engine made the cut, so it records where the seams are; asking the agent to reconstruct that is the arithmetic that produced the 33 ms miss. |
+| Lip sync at tier 1? | **Drift only.** Per-segment and cumulative audio-vs-video length. Onset-frame evidence and motion correlation were considered and deferred with SyncNet to tier 2 - too weak to be worth teaching. |
+| Who holds the thresholds? | **The engine emits `findings`** from one declared rules table, so an agent over bare MCP gets a place to look without the plugin; the skill teaches what to *do* about a finding. |
+| Surface shape | **Narrow probes plus one verdict call.** `assess_output` runs every applicable probe and returns findings plus a one-line summary per probe; `inspect_output(probe=...)` returns one probe's full body. Fat verdict, narrow detail. |
+| Are findings verdicts? | **No. The agent is the ultimate authority.** Nothing in the engine acts on a finding: no probe fails, no job fails, no template refuses to save, and `assess_output` never says pass or fail. A finding is a place to look. Severity is `info`/`warn` only - `error` was dropped because it reads like a verdict. |
+
+## Section 1 - Probes (engine tasks, `dw/tasks/assess.py`)
+
+All CPU-only (numpy + PyAV), read-only: the frames and waveform pass through
+unmodified, and what comes back is diagnostics rather than an artifact, as
+`analyze_audio` does. Each takes a video or audio in any shape a result
+carries (a path, an `asset:`/`output:` reference, a `previous_result:`,
+a generated `AudioVideo`), an optional `segments` list (section 3), and
+returns `{...measurements, findings: [...], rules_applied: [...],
+segments_source: "argument" | "manifest" | "file" | "none"}`.
+
+| Probe | Answers | Measurements |
+|---|---|---|
+| `analyze_segments` | per-shot level - the "whole-file mean hides a 6.5 dB jump" case | per segment: `peak_dbfs`, `rms_dbfs`, `crest_db`, `low/mid/high_dbfs` (the `analyze_audio` numbers, per segment); `rms_range_db` across segments |
+| `analyze_seams` | is each join itself clean, in audio and in picture | per seam, audio: `level_step_db` (rms of the 250 ms either side), `floor_dbfs` (rms of the 20 ms centred on the join - the "seam floor"), `click_db` (peak of the 2 ms window at the join over the peak of its neighbours), `spectral_shift` (band-share change across the join). Video: `frame_delta` (mean absolute pixel difference between the last frame of A and the first of B) and `typical_delta` (median inter-frame difference inside each shot), reported as the ratio `jump_ratio`; `luma_step`; `color_step` (mean Lab distance) |
+| `analyze_sync_drift` | lip-sync drift (tier 1) | per segment: `audio_seconds`, `video_seconds`, `offset_ms` at the segment's start and end, `cumulative_ms`; whole file: `length_delta_ms` (audio minus video). **TODO tier 2:** SyncNet / AV-HuBERT offset and confidence per segment |
+| `analyze_av_alignment` | does the sound swell where the picture does | the audio rms envelope and the video motion envelope (mean inter-frame difference), both at 4 Hz and normalised; `correlation` (Pearson, whole file and per segment), `audio_peak_s`, `motion_peak_s`, `peak_offset_s`, `cut_density` (seams per 10 s, when there are segments) against the audio envelope |
+| `analyze_continuity` | does shot B look like it belongs after shot A | for each adjacent pair: `color_distance` (Lab histogram distance, last frame of A vs first of B), `luma_step`, `sharpness_ratio` (Laplacian variance of B's first frame over A's last - catches "drift sharpening into noise late in a chain"). **TODO tier 2:** CLIP/DINO embedding similarity, face identity |
+
+`analyze_seams` and `analyze_continuity` both look at the boundary frames;
+the split is *cut hygiene* (is the join itself clean) versus *content* (does
+B belong after A), kept separate so a deliberate hard cut between two
+locations trips continuity and not seams.
+
+A dissolve's seam is the midpoint of the overlap, and the segment entry
+carries `overlap_frames`, so the seam probe widens its windows to the whole
+fade rather than measuring a step in the middle of one.
+
+`frame_grid` (#245) stays as it is - it is the evidence half of this.
+`analyze_audio` stays as the single-track probe and is on the `inspect`
+whitelist.
+
+## Section 2 - Evidence tools (sight and sound into the agent's context)
+
+The tools that let an agent look at a flagged finding rather than trust the
+number. The MCP SDK has no `VideoContent` (#210); the ruling there stands:
+frames go back as `ImageContent`, sound as the existing audio path.
+
+- **`get_output_frames(name, at=None, seams=None, count=None,
+  max_dimension=512, workspace=None)`** - new MCP tool in `dw_mcp/media.py`
+  over `GET /api/gallery/{name}/frames`. Returns a list of images (base64,
+  the `get_output_image` shape) each labelled with its time and frame index.
+  Three selectors, mutually exclusive:
+  - `at: [seconds | "frame:N", ...]` - specific moments.
+  - `seams: true | [indices]` - for each seam, the last frame before and the
+    first frame after, composed into *one* side-by-side tile per seam with
+    the segment names burned in. This is the seam and continuity evidence in
+    one image.
+  - `count: N` - `frame_grid` reached without authoring a workflow: N evenly
+    spaced frames as one contact sheet.
+
+  Same `_encode_within_budget` path as `get_output_image`, capped at
+  `MAX_RETURNED_BYTES` across the whole call; over budget it halves the
+  dimension before it drops tiles, and the answer says which it did. The
+  server decodes with PyAV, seeking to each timestamp rather than reading the
+  clip through.
+
+- **`get_output_audio` becomes mux-aware and takes an excerpt.** On
+  `video/mp4` it extracts the track (`load_audio` already special-cases video
+  extensions) and returns it as WAV. New `start`/`duration` seconds pull the
+  two seconds around seam 3 rather than refusing a four-minute cut; the
+  answer carries `excerpt: {start, duration, of}` so it names itself as a
+  cut. (#204 objected to *silent* truncation; an excerpt that says what it
+  is answers a different question.) Server: `GET
+  /api/gallery/{name}/audio?start=&duration=`.
+
+- **`get_gallery_metadata`** gains `media.segments` (section 3), so the
+  existing `envelope` can be read against shot boundaries.
+
+## Section 3 - Boundary persistence
+
+Video files carry no embedded metadata today (only PNG/JPEG do; a video's
+`get_gallery_metadata` comes from job history via the manifest). Three
+layers, and a precedence:
+
+- **The artifact carries it.** `AudioVideo` and a plain frames result gain
+  an optional `segments` attribute: `[{name, start_frame, num_frames,
+  start_sample, num_samples, overlap_frames?, hard_cut?}]`. `concat_videos`
+  and `dissolve_videos` populate it from their inputs. A segment's `name` is
+  the input's `for_each` entry name when it came through `gather:` /
+  `shot@x`, else its index - which is what makes a finding say "between
+  `shot@intro` and `shot@chase`" rather than "seam 2". `pair_audio`,
+  `slice_audio`, `trim`/`loop` tasks and `_fit_audio_to_frames` carry the
+  list through when the frame timeline is unchanged and *drop* it when they
+  change it - never silently wrong.
+- **The manifest records it.** The manifest entry grows `segments` beside
+  `subfolder` when the artifact has them; `get_job`, `get_gallery_metadata`
+  (`media.segments`) and the server-side probes read it from there. The
+  realized `workflow.json` is untouched.
+- **The file keeps it.** At mux time PyAV writes the same list into the mp4
+  container's `comment` tag as JSON (`{"dw": {"segments": [...]}}`), and
+  `read_embedded_metadata` grows a video branch. That is what survives
+  `keep_output` (a hard link), `upload_asset` and a pruned run directory,
+  so `analyze_seams` on an `asset:` still knows the cut.
+- **Precedence** in every probe: the caller's `segments` argument >
+  manifest > file tag > none. With none, the per-segment probes answer over
+  one segment with `segments_source: "none"`, and `analyze_seams` reports
+  zero seams - an answer, not an error.
+
+`hard_cut` is a per-segment flag a template may set on an entry (a cut
+between two locations by design), which suppresses `seam_frame_jump` for
+that boundary. `concat_videos` gains a `hard_cuts` argument naming entries;
+nothing sets it by default.
+
+## Section 4 - Rules and `findings`
+
+One table, `dw/assessment_rules.py`, in the `dw/task_domains.py` style: each
+rule is `{name, probe, field, comparator, threshold, severity, says}`, and
+`tests/test_assessment_rules.py` pins every rule to a real field of the
+real probe's answer so a rename cannot leave one checking nothing. The
+module docstring states the authority rule: **these are places to look, not
+verdicts; nothing in the engine acts on a finding.** Starting thresholds,
+each tunable in that one place:
+
+| rule | probe / field | flags when | severity |
+|---|---|---|---|
+| `segment_level_spread` | `analyze_segments.rms_range_db` | > 3 dB | warn |
+| `seam_level_step` | `analyze_seams.level_step_db` | > 3 dB | warn |
+| `seam_click` | `analyze_seams.click_db` | > 12 dB | warn |
+| `seam_hole` | `analyze_seams.floor_dbfs` | < −50 dBFS while both sides > −30 | warn |
+| `seam_frame_jump` | `analyze_seams.jump_ratio` | > 8, unless the boundary is `hard_cut` | info |
+| `sync_drift` | `analyze_sync_drift.offset_ms` at any segment end | > 40 ms | warn |
+| `sync_length` | `analyze_sync_drift.length_delta_ms` | > 40 ms | warn |
+| `av_peak_offset` | `analyze_av_alignment.peak_offset_s` | > 2 s | info |
+| `av_correlation` | `analyze_av_alignment.correlation` | < 0.2 | info |
+| `continuity_color` | `analyze_continuity.color_distance` | > 0.25 (normalised) | warn |
+| `continuity_sharpness` | `analyze_continuity.sharpness_ratio` | < 0.5 or > 2 | warn |
+
+A finding:
+
+```json
+{
+  "rule": "seam_level_step",
+  "severity": "warn",
+  "at": {"seam": 2, "between": ["shot@intro", "shot@chase"], "seconds": 10.33},
+  "value": 4.2,
+  "threshold": 3.0,
+  "says": "level steps 4.2 dB up across the join"
+}
+```
+
+Severity is `info` / `warn`, the run-time warnings' vocabulary minus
+`error`, so it reads like `job.warnings`. Every probe answer ends with
+`rules_applied` so an agent that got no findings knows what *was* checked;
+`assess_output` adds `not_applicable: {probe: why}` (no audio track, no
+segments, a still).
+
+## Section 5 - API and MCP surface, and where the code runs
+
+**Engine** - `dw/tasks/assess.py`, `dw/assessment_rules.py`. The five
+probes are ordinary task commands, so a workflow can wire one as a
+self-check step (by convention `intermediate`) and its answer lands in the
+manifest as `application/json`, the way `analyze_audio`'s does. CPU-only; no
+torch model is loaded.
+
+**Server** - `dw/server/assess.py`, routes in `dw/server/app.py`:
+
+- `GET /api/gallery/{name}/assess?detail=false` - runs every applicable
+  probe *in the server process* (not the worker: no queue, no GPU, the same
+  place `metadata?envelope=true` runs today) and answers `{probes: {name:
+  summary}, findings, not_applicable, segments_source}`; `detail=true`
+  includes each probe's full body.
+- `GET /api/gallery/{name}/inspect?probe=analyze_seams&...` - one probe's
+  full body, arguments as query parameters. The whitelist is the five
+  probes plus `analyze_audio`; anything else is a 400 naming the list.
+- `GET /api/gallery/{name}/frames?at=|seams=|count=&max_dimension=` -
+  JSON list of base64 PNG tiles with labels.
+- `GET /api/gallery/{name}/audio?start=&duration=` - WAV, mux-aware.
+- All four accept an `asset:` name the way `metadata` does (#127), and
+  `workspace`. Paths go through `validate_output_path` / the asset resolver
+  as every other route does.
+- A decoded file is cached per `(path, mtime)` for the life of one request
+  only - five probes must not decode a four-minute cut five times, and
+  nothing is held across calls.
+
+**MCP** - `dw_mcp/assess.py`, wired in `server.py`: `assess_output(name,
+detail=False, workspace=None)`, `inspect_output(name, probe, workspace=None,
+**arguments)`, `get_output_frames(...)`, and the widened `get_output_audio`.
+None needs `acknowledged_cost` - nothing here spends GPU minutes.
+`assess_output`'s description carries the authority rule in one sentence.
+
+**Web UI** - reads the fields only: the job page lists a probe step's
+findings under its result the way it lists warnings. Nothing else in the
+first cut.
+
+## Section 6 - Skill and discovery
+
+### One skill, family-agnostic: `dw:judging-output`
+
+A new plugin skill in `plugins/dw/skills/judging-output/`, listed in
+`plugins/dw/README.md` and pinned by `tests/test_plugin_skills.py` like the
+others. It is the *procedure* for the redo-or-tweak loop, and it is one
+skill rather than a section in each family's because the loop is the same
+for an H3 cut and an LTX chain, and because `minimax-h3` and `ltx-2.5` are
+each within 40 bytes of the 12 KiB skill cap and cannot absorb it.
+
+Trigger line: use when a dw run has finished and the user wants to know
+whether it is good, or when a family skill's "run and judge" step hands off
+here.
+
+Body, in order:
+
+1. **Look before measuring**: `get_output_frames(count=12)` for the shape,
+   `get_output_audio(start, duration)` around anything you mean to judge;
+   what you can see and hear outranks any number below.
+2. **Then `assess_output`**, and read the findings as places to look, not
+   verdicts. One paragraph on each rule family: what the number is, what
+   usually caused it in this catalog, and what it looks like when it is
+   *fine* (a hard cut trips `seam_frame_jump`; a whispered line trips
+   `segment_level_spread`).
+3. **Drill down with `inspect_output(probe=...)` and `get_output_frames(seams=[n])`** on a flagged finding.
+4. **Remediation table** - the part only the skill can hold, because it
+   names template variables: a `seam_level_step` on an H3 cut →
+   `match_levels_dbfs`; a `seam_hole` → `audio_bleed_ms`; a `sync_drift`
+   → the #197 class, re-run through `pair_audio` `fit`; a
+   `continuity_color` between two shots → regenerate B with A's last frame
+   (`chain-video-continuity`) or the shared cast asset; `av_peak_offset` on
+   a music video → re-slice the score (`start_frame`) or recut; a
+   `continuity_sharpness` late in a chain → shorten the chain or reseed the
+   drifting shot. Each row says whether the fix is a *recut* (cheap: the
+   shots exist, `output:` them) or a *regenerate* (a new run, quote the
+   cost).
+5. **Recut, don't regenerate, when you can**: the `series-episodes` recipe
+   for `output:`-referencing a run's `intermediate/` shots.
+6. What tier 1 cannot tell you (identity across shots, whether the mouth
+   matches the words) and that the frames are the way to check those - the
+   honest limit, stated once.
+
+The family skills' "run and judge" steps shrink to a pointer: `minimax-h3`
+step 4 ("You cannot watch a video") is rewritten to name
+`get_output_frames` and hand off to `dw:judging-output`; `series-episodes`
+"watch two episodes back to back" points at the same place;
+`ltx-2.5` likewise. That rewrite frees bytes rather than spending them.
+
+### How the capability reaches an agent without the plugin
+
+Three layers, each already the way this repo communicates a capability:
+
+- **Tool descriptions** (`dw_mcp/server.py` docstrings) are the only thing
+  a bare MCP client reads. `assess_output`'s says what it checks, that the
+  findings are places to look, and that `inspect_output`, `get_output_frames`
+  and `get_output_audio` are the drill-down. `get_gallery_metadata`'s
+  description points at `assess_output` for a cut ("whole-file numbers
+  cannot see inside a join"). `get_job`'s `next` hint for a finished
+  video job names `assess_output`.
+- **The guide** (`docs/WORKFLOW_GUIDE.md`, read over `get_guide`) gains a
+  section *Assessing a run's output*, indexed like the others, holding the
+  probe table, the findings shape and the authority rule - so an agent that
+  was told "check the seams" can look the mechanism up rather than guess at
+  it. `list_guides` is what makes a section findable by name.
+- **The task catalog** (`list_tasks` / `get_task`): each probe's docstring is
+  its `get_task` description, and `list_tasks` tags the five with a
+  `assessment` category so they sort together. `docs/TASKS.md` gets one
+  section per probe as `analyze_audio` has.
+
+The MCP server's own instructions block (the text in `dw_mcp/server.py` that
+a client shows at connect) gains one sentence in the loop description:
+"after a run, `assess_output` measures the deliverable and returns places to
+look; `get_output_frames` and `get_output_audio` let you look and listen."
+
+## Section 7 - Testing
+
+- **Synthetic media, no models.** Every probe is tested on clips built in
+  the test (numpy frames + a synthesised tone), the way `test_video_utils.py`
+  tests `frame_grid`: a cut with a known 6 dB step at seam 2 must flag
+  `seam_level_step` at seam 2 and nowhere else; a track padded by 267 samples
+  per shot must report the drift the issue measured; a dissolve must not
+  flag a step; a `hard_cut` boundary must not flag a jump.
+- **The rules table is pinned** (`tests/test_assessment_rules.py`): every
+  rule names a field the probe actually returns; every threshold in the
+  skill's prose matches the table (the `test_plugin_skills.py` pattern).
+- **Boundary persistence round-trips**: `concat_videos` → save → manifest
+  entry → `read_embedded_metadata` on the mp4 → the same list; `keep_output`
+  keeps it; a `slice` that changes the timeline drops it.
+- **Budget**: `get_output_frames` on a 4K clip lands under
+  `MAX_RETURNED_BYTES` and says it halved the dimension.
+- **Routes**: the four `/api/gallery/{name}/...` routes refuse a traversal,
+  answer 400 for an unknown probe naming the whitelist, and accept an
+  `asset:` name.
+- **Field test on lem**: `assess_output` over MCP on an existing
+  `music-video` and `dialogue-short` run, and on the #197 repro cut, before
+  the skill's threshold prose is finalised - the starting thresholds above
+  are guesses until they have met real output.
+
+## Not in scope
+
+- Any model-based judge (tiers 2 and 3) - each `TODO` in section 1 is the
+  slot.
+- Automatic remediation: no template re-runs itself on a finding.
+- `score-and-select` wiring: a probe's numbers are exactly what that
+  proposal's reducer would read, but that proposal stands on its own.
+- Web UI beyond listing findings.
+- Findings on stills (composition, artifacts) - a different problem with a
+  different evidence tool already in place (`get_output_image`).
+
+## Staging
+
+Four independently landable pieces, each its own branch off `develop`:
+
+1. **Evidence**: mux-aware `get_output_audio` with excerpts;
+   `get_output_frames` and its route. Closes the perceptual half of #193
+   on its own.
+2. **Boundaries**: `segments` on the artifact, the manifest, the mp4 tag;
+   `media.segments` in metadata.
+3. **Probes and rules**: the five tasks, the table, `assess` / `inspect`
+   routes and tools; guide section; `list_tasks` category.
+4. **Skill**: `dw:judging-output`, the family-skill rewrites, the field
+   test that sets the thresholds.
+
+Release note items: `get_output_audio` no longer refuses `video/mp4`;
+manifest entries and mp4 files carry `segments`; `minimax-h3` step 4 is
+rewritten.

From e999c766d37c11956c18d373987f295987247ebe Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sun, 20 Sep 2026 08:06:32 -0500
Subject: [PATCH 74/77] docs: #193 - revise output assessment proposal after
 review

Remux pass for the file tag, streaming probes, workflow-layer shot names,
measured start_sample, run_chain as a join, segments renamed shots, codec
priming in sync_length, no av_correlation rule until field data.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 docs/proposals/output-assessment.md | 357 +++++++++++++++++++---------
 1 file changed, 241 insertions(+), 116 deletions(-)

diff --git a/docs/proposals/output-assessment.md b/docs/proposals/output-assessment.md
index b91b62ca..44e6437b 100644
--- a/docs/proposals/output-assessment.md
+++ b/docs/proposals/output-assessment.md
@@ -3,7 +3,9 @@
 Status: proposed, 2026-09-20. Scopes issue #193 (agent has no way to hear or
 watch generated output), folding in #210 (no `VideoContent` in the MCP SDK)
 and the per-segment `analyze_cut` proposal from #193's thread. Written from
-a design conversation with Don, every section agreed. No code changes yet.
+a design conversation with Don, every section agreed; revised the same day
+after a review pass against the code (the *Review findings* section records
+what changed and why). No code changes yet.
 
 ## The goal
 
@@ -38,42 +40,77 @@ exactly the right duration whose audio drifted 267 samples per shot and was
 | Where does judgement live? | **Tier 1: the engine measures, the agent judges.** Deterministic numbers plus evidence the agent can perceive (frames as `ImageContent`, audio excerpts). No ML judges in the engine. Tier 2 (CLIP/DINO similarity, SyncNet-class sync) and tier 3 (a VLM judge) are marked `TODO` where they would slot in, not built. |
 | How does the agent invoke a measurement? | **Both paths, one implementation.** Measurements are engine tasks (composable into a template's own self-check step, recorded in the manifest, cacheable) *and* run synchronously in the server process over an MCP tool for an output or asset, so a question about a finished file does not queue behind a 20-minute render. |
 | Where do shot boundaries come from? | **Persisted at join time, caller override.** The engine made the cut, so it records where the seams are; asking the agent to reconstruct that is the arithmetic that produced the 33 ms miss. |
-| Lip sync at tier 1? | **Drift only.** Per-segment and cumulative audio-vs-video length. Onset-frame evidence and motion correlation were considered and deferred with SyncNet to tier 2 - too weak to be worth teaching. |
+| Lip sync at tier 1? | **Drift only.** Per-shot and cumulative audio-vs-video offset. Onset-frame evidence and motion correlation were considered and deferred with SyncNet to tier 2 - too weak to be worth teaching. |
 | Who holds the thresholds? | **The engine emits `findings`** from one declared rules table, so an agent over bare MCP gets a place to look without the plugin; the skill teaches what to *do* about a finding. |
 | Surface shape | **Narrow probes plus one verdict call.** `assess_output` runs every applicable probe and returns findings plus a one-line summary per probe; `inspect_output(probe=...)` returns one probe's full body. Fat verdict, narrow detail. |
 | Are findings verdicts? | **No. The agent is the ultimate authority.** Nothing in the engine acts on a finding: no probe fails, no job fails, no template refuses to save, and `assess_output` never says pass or fail. A finding is a place to look. Severity is `info`/`warn` only - `error` was dropped because it reads like a verdict. |
 
+## Vocabulary
+
+The boundary list is called **`shots`** everywhere - on the artifact, in the
+manifest, in the file tag, as the probe argument. Not `segments`: that word
+already means chain *generation* segments throughout the engine
+(`SegmentedFrames`, `save_segments`, `chain.py`'s `Segment`), and a grep
+that finds both is a grep that finds neither. A **seam** is the boundary
+between two adjacent shots; seam *i* sits between shot *i* and shot *i+1*.
+
 ## Section 1 - Probes (engine tasks, `dw/tasks/assess.py`)
 
 All CPU-only (numpy + PyAV), read-only: the frames and waveform pass through
 unmodified, and what comes back is diagnostics rather than an artifact, as
 `analyze_audio` does. Each takes a video or audio in any shape a result
 carries (a path, an `asset:`/`output:` reference, a `previous_result:`,
-a generated `AudioVideo`), an optional `segments` list (section 3), and
+a generated `AudioVideo`), an optional `shots` list (section 3), and
 returns `{...measurements, findings: [...], rules_applied: [...],
-segments_source: "argument" | "manifest" | "file" | "none"}`.
+shots_source: "argument" | "manifest" | "file" | "none"}`.
+
+**A probe over a path streams.** The existing loaders (`load_audio_video`,
+`load_audio`) materialise every frame as a PIL image - a four-minute 1080p
+clip is ~36 GB that way - and both route the track through
+`_fit_audio_to_frames`, which snaps audio to the frame count within
+`AUDIO_FIT_TOLERANCE_SECONDS` (0.25 s) and so *hides the very drift
+`analyze_sync_drift` exists to see*. So a probe given a path decodes in one
+`probe_media`-style pass (`dw/media_info.py`) that keeps only what the
+rules need: the waveform (~46 MB for four minutes of 48 kHz stereo), one
+motion scalar per frame, a fixed-size downsampled luma/Lab image per frame,
+the frame pair either side of each seam, and the container's own stream
+durations. A probe given an in-memory `AudioVideo` (the task-step path)
+reads those from the object it has. Nothing ever holds "the decoded file".
 
 | Probe | Answers | Measurements |
 |---|---|---|
-| `analyze_segments` | per-shot level - the "whole-file mean hides a 6.5 dB jump" case | per segment: `peak_dbfs`, `rms_dbfs`, `crest_db`, `low/mid/high_dbfs` (the `analyze_audio` numbers, per segment); `rms_range_db` across segments |
-| `analyze_seams` | is each join itself clean, in audio and in picture | per seam, audio: `level_step_db` (rms of the 250 ms either side), `floor_dbfs` (rms of the 20 ms centred on the join - the "seam floor"), `click_db` (peak of the 2 ms window at the join over the peak of its neighbours), `spectral_shift` (band-share change across the join). Video: `frame_delta` (mean absolute pixel difference between the last frame of A and the first of B) and `typical_delta` (median inter-frame difference inside each shot), reported as the ratio `jump_ratio`; `luma_step`; `color_step` (mean Lab distance) |
-| `analyze_sync_drift` | lip-sync drift (tier 1) | per segment: `audio_seconds`, `video_seconds`, `offset_ms` at the segment's start and end, `cumulative_ms`; whole file: `length_delta_ms` (audio minus video). **TODO tier 2:** SyncNet / AV-HuBERT offset and confidence per segment |
-| `analyze_av_alignment` | does the sound swell where the picture does | the audio rms envelope and the video motion envelope (mean inter-frame difference), both at 4 Hz and normalised; `correlation` (Pearson, whole file and per segment), `audio_peak_s`, `motion_peak_s`, `peak_offset_s`, `cut_density` (seams per 10 s, when there are segments) against the audio envelope |
-| `analyze_continuity` | does shot B look like it belongs after shot A | for each adjacent pair: `color_distance` (Lab histogram distance, last frame of A vs first of B), `luma_step`, `sharpness_ratio` (Laplacian variance of B's first frame over A's last - catches "drift sharpening into noise late in a chain"). **TODO tier 2:** CLIP/DINO embedding similarity, face identity |
+| `analyze_shots` | per-shot level - the "whole-file mean hides a 6.5 dB jump" case | per shot: `peak_dbfs`, `rms_dbfs`, `crest_db`, `low/mid/high_dbfs` (the `analyze_audio` numbers, per shot); `rms_range_db` across shots |
+| `analyze_seams` | is each join itself clean, in audio and in picture | per seam, audio: `level_step_db` (rms of the 250 ms either side), `floor_dbfs` (rms of the 20 ms centred on the join - the "seam floor"), `click_db` (peak of the 2 ms window at the join over the peak of its neighbours), `spectral_shift` (band-share change across the join). Video: `frame_delta` (mean absolute difference between the last frame of A and the first of B, both downsampled to a fixed size) and `typical_delta` (the *90th percentile* of inter-frame difference inside each shot, floored - a median is near zero on a static talking head and would flag every cut after one), reported as `jump_ratio` |
+| `analyze_sync_drift` | lip-sync drift (tier 1) | per shot: `offset_ms` at its start and end, read as `start_sample / rate - start_frame / fps` from the recorded boundaries, and `cumulative_ms`; whole file: `length_delta_ms` = the container's audio stream duration minus its video stream duration, *after subtracting the codec's declared priming* (AAC's 1024-sample block is 21 ms at 48 kHz and 43 ms at H3's 24 kHz - over the threshold on a clean file if left in). **TODO tier 2:** SyncNet / AV-HuBERT offset and confidence per shot |
+| `analyze_av_alignment` | does the sound swell where the picture does | the audio rms envelope and the video motion envelope (mean inter-frame difference), both at 4 Hz and normalised; `correlation` (Pearson, whole file and per shot), `audio_peak_s`, `motion_peak_s`, `peak_offset_s`, `cut_density` (seams per 10 s, when there are shots) against the audio envelope |
+| `analyze_continuity` | does shot B look like it belongs after shot A | for each adjacent pair, on the fixed-size downsampled frames: `color_distance` (Lab histogram distance, last frame of A vs first of B), `luma_step`, `sharpness_ratio` (Laplacian variance of B's first frame over A's last - catches "drift sharpening into noise late in a chain"; resolution- and quantisation-dependent, so only ever compared *within* one file, never against a constant). **TODO tier 2:** CLIP/DINO embedding similarity, face identity |
 
 `analyze_seams` and `analyze_continuity` both look at the boundary frames;
 the split is *cut hygiene* (is the join itself clean) versus *content* (does
 B belong after A), kept separate so a deliberate hard cut between two
 locations trips continuity and not seams.
 
-A dissolve's seam is the midpoint of the overlap, and the segment entry
-carries `overlap_frames`, so the seam probe widens its windows to the whole
-fade rather than measuring a step in the middle of one.
+`analyze_sync_drift`'s per-shot `offset_ms` measures the *recorded*
+boundaries, so it is only as honest as the recording: section 3 requires
+`start_sample` to be read from the joined waveform's actual length at each
+seam, never derived from `start_frame / fps`, or the probe is a tautology.
+`length_delta_ms` is the one number read from the file itself and is what
+catches a file whose boundaries were never recorded.
+
+A dissolve's shot B starts at the first blended frame, and its seam is at
+`start_frame + overlap_frames / 2`; the seam probe widens its windows to
+the whole fade rather than measuring a step in the middle of one.
 
 `frame_grid` (#245) stays as it is - it is the evidence half of this.
 `analyze_audio` stays as the single-track probe and is on the `inspect`
 whitelist.
 
+**A probe step saves as JSON.** A dict result is written whole only under
+`content_type: application/json` (`Result.save`'s JSON branch); under any
+other type the dict branch explodes it per key and a scalar raises. The
+schema requires `application/json` on a step whose command is a probe, and
+`scalar_result_validation` refuses anything else.
+
 ## Section 2 - Evidence tools (sight and sound into the agent's context)
 
 The tools that let an agent look at a flagged finding rather than trust the
@@ -82,13 +119,13 @@ frames go back as `ImageContent`, sound as the existing audio path.
 
 - **`get_output_frames(name, at=None, seams=None, count=None,
   max_dimension=512, workspace=None)`** - new MCP tool in `dw_mcp/media.py`
-  over `GET /api/gallery/{name}/frames`. Returns a list of images (base64,
-  the `get_output_image` shape) each labelled with its time and frame index.
-  Three selectors, mutually exclusive:
+  over `GET /api/gallery/{name:path}/frames`. Returns a list of images
+  (base64, the `get_output_image` shape) each labelled with its time and
+  frame index. Three selectors, mutually exclusive:
   - `at: [seconds | "frame:N", ...]` - specific moments.
   - `seams: true | [indices]` - for each seam, the last frame before and the
     first frame after, composed into *one* side-by-side tile per seam with
-    the segment names burned in. This is the seam and continuity evidence in
+    the shot names burned in. This is the seam and continuity evidence in
     one image.
   - `count: N` - `frame_grid` reached without authoring a workflow: N evenly
     spaced frames as one contact sheet.
@@ -99,16 +136,18 @@ frames go back as `ImageContent`, sound as the existing audio path.
   server decodes with PyAV, seeking to each timestamp rather than reading the
   clip through.
 
-- **`get_output_audio` becomes mux-aware and takes an excerpt.** On
-  `video/mp4` it extracts the track (`load_audio` already special-cases video
-  extensions) and returns it as WAV. New `start`/`duration` seconds pull the
-  two seconds around seam 3 rather than refusing a four-minute cut; the
-  answer carries `excerpt: {start, duration, of}` so it names itself as a
-  cut. (#204 objected to *silent* truncation; an excerpt that says what it
-  is answers a different question.) Server: `GET
-  /api/gallery/{name}/audio?start=&duration=`.
-
-- **`get_gallery_metadata`** gains `media.segments` (section 3), so the
+- **`get_output_audio` becomes mux-aware and takes an excerpt.** It moves
+  from the raw `/outputs` mount to `GET /api/gallery/{name:path}/audio?start=&duration=`.
+  On `video/mp4` the server extracts the track and returns it as WAV. New
+  `start`/`duration` seconds pull the two seconds around seam 3 rather than
+  refusing a four-minute cut; the answer carries `excerpt: {start, duration,
+  of}` so it names itself as a cut (#204 objected to *silent* truncation).
+  **The whole-file refusal stays**: without `start`/`duration` a file over
+  `MAX_RETURNED_BYTES` base64 is refused exactly as today, and the refusal
+  now says to ask for an excerpt. An audio-only file under budget with no
+  excerpt asked for is returned as-is in its own encoding, not transcoded.
+
+- **`get_gallery_metadata`** gains `media.shots` (section 3), so the
   existing `envelope` can be read against shot boundaries.
 
 ## Section 3 - Boundary persistence
@@ -118,30 +157,60 @@ Video files carry no embedded metadata today (only PNG/JPEG do; a video's
 layers, and a precedence:
 
 - **The artifact carries it.** `AudioVideo` and a plain frames result gain
-  an optional `segments` attribute: `[{name, start_frame, num_frames,
-  start_sample, num_samples, overlap_frames?, hard_cut?}]`. `concat_videos`
-  and `dissolve_videos` populate it from their inputs. A segment's `name` is
-  the input's `for_each` entry name when it came through `gather:` /
-  `shot@x`, else its index - which is what makes a finding say "between
-  `shot@intro` and `shot@chase`" rather than "seam 2". `pair_audio`,
-  `slice_audio`, `trim`/`loop` tasks and `_fit_audio_to_frames` carry the
-  list through when the frame timeline is unchanged and *drop* it when they
-  change it - never silently wrong.
-- **The manifest records it.** The manifest entry grows `segments` beside
+  an optional `shots` attribute: `[{name, start_frame, num_frames,
+  start_sample, num_samples, overlap_frames?, hard_cut?}]`.
+  - **Who populates it**: `concat_videos`, `dissolve_videos` and
+    `run_chain` (`dw/pipeline_processors/chain.py` - the other join in the
+    catalog, `templates/ltx2/chained-segments` and `extend-clip`, and the
+    place late-chain sharpening actually happens; it already knows every
+    seam from `Segment.head_trim` and `config.plan`).
+  - **`start_sample` is measured, not derived.** The join task records each
+    shot's `start_sample` from the length of the waveform it has actually
+    accumulated when the shot is appended, so a per-shot codec overrun is
+    *in* the record. This is what makes `analyze_sync_drift`'s `offset_ms`
+    a measurement.
+  - **Names are assigned in the workflow layer, not the task.** A task
+    receives resolved objects and can only name a shot by position
+    (`video_names` says "video 2"). `Workflow.run` renames the positional
+    entries from the step's pre-resolution `gather:` reference list, the
+    way `selected_field` already reads `step_data` - so a shot that came
+    through `gather:shot` is `shot@intro`, and a finding says "between
+    `shot@intro` and `shot@chase`" rather than "seam 2". A shot with no
+    such origin keeps its index as its name.
+  - **Every `AudioVideo(` constructor has a stated rule**, and a test fails
+    when a new constructor appears without one:
+
+    | Constructor | Rule |
+    |---|---|
+    | `concat_videos`, `dissolve_videos`, `run_chain` | *populate* |
+    | `pair_audio` | frame side survives; `start_sample`/`num_samples` recomputed from the new track's rate, and with `fit: "video"` the last shot's `num_samples` is re-measured |
+    | `interpolate_frames` | frame fields rescaled by the frame multiplier; sample fields unchanged |
+    | `stabilize`, `loop_frames` (same frame count) | carried through unchanged |
+    | `slice_audio`, `trim_*`, anything returning an `AudioTrack` or a different frame count | *dropped* - there are no frames to carry a boundary on, or the timeline changed |
+    | `result.py`, `task.py`, `video_utils.py` wrappers | carried through unchanged |
+- **The manifest records it.** The manifest entry grows `shots` beside
   `subfolder` when the artifact has them; `get_job`, `get_gallery_metadata`
-  (`media.segments`) and the server-side probes read it from there. The
+  (`media.shots`) and the server-side probes read it from there. The
   realized `workflow.json` is untouched.
-- **The file keeps it.** At mux time PyAV writes the same list into the mp4
-  container's `comment` tag as JSON (`{"dw": {"segments": [...]}}`), and
-  `read_embedded_metadata` grows a video branch. That is what survives
-  `keep_output` (a hard link), `upload_asset` and a pruned run directory,
-  so `analyze_seams` on an `asset:` still knows the cut.
-- **Precedence** in every probe: the caller's `segments` argument >
-  manifest > file tag > none. With none, the per-segment probes answer over
-  one segment with `segments_source: "none"`, and `analyze_seams` reports
-  zero seams - an answer, not an error.
-
-`hard_cut` is a per-segment flag a template may set on an entry (a cut
+- **The file keeps it - by a remux pass after the write.** `result.py`
+  does not own the container: `encode_video` and `export_to_video` are
+  diffusers' (`diffusers.utils`), and neither takes metadata. So after
+  either has written an mp4 whose artifact has `shots`, `result.py` opens
+  the file, copies its packets to a sibling with
+  `container.metadata["comment"] = json.dumps({"dw": {"shots": [...]}})`,
+  and replaces it. The chain's spilled `SegmentedFrames` path gets the same
+  pass. The tag round-trips through PyAV and survives `os.link`, so
+  `keep_output` (a hard link), `upload_asset` and a pruned run directory
+  all keep it, and `analyze_seams` on an `asset:` still knows the cut.
+  `read_embedded_metadata` dispatches on extension before it reaches PIL;
+  the metadata route folds the tag read into `probe_media` so a video is
+  opened once per call, not twice.
+- **Precedence** in every probe: the caller's `shots` argument > manifest
+  > file tag > none. With none, the per-shot probes answer over one shot
+  with `shots_source: "none"`, and `analyze_seams` reports zero seams - an
+  answer, not an error.
+
+`hard_cut` is a per-shot flag a template may set on an entry (a cut
 between two locations by design), which suppresses `seam_frame_jump` for
 that boundary. `concat_videos` gains a `hard_cuts` argument naming entries;
 nothing sets it by default.
@@ -158,18 +227,22 @@ each tunable in that one place:
 
 | rule | probe / field | flags when | severity |
 |---|---|---|---|
-| `segment_level_spread` | `analyze_segments.rms_range_db` | > 3 dB | warn |
+| `shot_level_spread` | `analyze_shots.rms_range_db` | > 3 dB | warn |
 | `seam_level_step` | `analyze_seams.level_step_db` | > 3 dB | warn |
 | `seam_click` | `analyze_seams.click_db` | > 12 dB | warn |
 | `seam_hole` | `analyze_seams.floor_dbfs` | < −50 dBFS while both sides > −30 | warn |
 | `seam_frame_jump` | `analyze_seams.jump_ratio` | > 8, unless the boundary is `hard_cut` | info |
-| `sync_drift` | `analyze_sync_drift.offset_ms` at any segment end | > 40 ms | warn |
-| `sync_length` | `analyze_sync_drift.length_delta_ms` | > 40 ms | warn |
+| `sync_drift` | `analyze_sync_drift.offset_ms` at any shot end | > 40 ms | warn |
+| `sync_length` | `analyze_sync_drift.length_delta_ms` (priming already subtracted) | > 40 ms | warn |
 | `av_peak_offset` | `analyze_av_alignment.peak_offset_s` | > 2 s | info |
-| `av_correlation` | `analyze_av_alignment.correlation` | < 0.2 | info |
 | `continuity_color` | `analyze_continuity.color_distance` | > 0.25 (normalised) | warn |
 | `continuity_sharpness` | `analyze_continuity.sharpness_ratio` | < 0.5 or > 2 | warn |
 
+`av_correlation` is **measured but has no rule yet**: on a 20 s five-shot
+clip the 4 Hz envelopes are 80 samples, motion is per-cut and audio is
+continuous, so a threshold set before the stage-4 field test would be a
+coin flip. The number is reported; the rule lands from lem data.
+
 A finding:
 
 ```json
@@ -183,39 +256,45 @@ A finding:
 }
 ```
 
-Severity is `info` / `warn`, the run-time warnings' vocabulary minus
-`error`, so it reads like `job.warnings`. Every probe answer ends with
-`rules_applied` so an agent that got no findings knows what *was* checked;
-`assess_output` adds `not_applicable: {probe: why}` (no audio track, no
-segments, a still).
+Findings are a new shape that *reads like* `job.warnings` (run-time warnings
+carry a `kind`, not a severity); `severity` is `info` / `warn` only. Every
+probe answer ends with `rules_applied` so an agent that got no findings
+knows what *was* checked; `assess_output` adds `not_applicable: {probe:
+why}` (no audio track, no shots, a still).
 
 ## Section 5 - API and MCP surface, and where the code runs
 
 **Engine** - `dw/tasks/assess.py`, `dw/assessment_rules.py`. The five
 probes are ordinary task commands, so a workflow can wire one as a
-self-check step (by convention `intermediate`) and its answer lands in the
-manifest as `application/json`, the way `analyze_audio`'s does. CPU-only; no
-torch model is loaded.
-
-**Server** - `dw/server/assess.py`, routes in `dw/server/app.py`:
-
-- `GET /api/gallery/{name}/assess?detail=false` - runs every applicable
-  probe *in the server process* (not the worker: no queue, no GPU, the same
-  place `metadata?envelope=true` runs today) and answers `{probes: {name:
-  summary}, findings, not_applicable, segments_source}`; `detail=true`
+self-check step (by convention `intermediate`, `content_type:
+application/json`) and its answer lands in the manifest. CPU-only; no torch
+model is loaded.
+
+**Server** - `dw/server/assess.py`, routes in `dw/server/app.py`, in the
+existing `{name:path}/metadata|thumbnail|download` family:
+
+- `GET /api/gallery/{name:path}/assess?detail=false` - runs every
+  applicable probe *in the server process* (a sync `def`, so FastAPI runs
+  it in the threadpool the way `metadata?envelope=true` runs today; the
+  worker and its queue are never involved) and answers `{probes: {name:
+  summary}, findings, not_applicable, shots_source}`; `detail=true`
   includes each probe's full body.
-- `GET /api/gallery/{name}/inspect?probe=analyze_seams&...` - one probe's
-  full body, arguments as query parameters. The whitelist is the five
-  probes plus `analyze_audio`; anything else is a 400 naming the list.
-- `GET /api/gallery/{name}/frames?at=|seams=|count=&max_dimension=` -
+- `GET /api/gallery/{name:path}/inspect?probe=analyze_seams&...` - one
+  probe's full body. `probe` is checked against the whitelist (the five
+  probes plus `analyze_audio`) *before* any other query parameter is looked
+  at, and only that probe's declared arguments are forwarded - a query
+  string never reaches a task signature unfiltered. Anything else is a 400
+  naming the list.
+- `GET /api/gallery/{name:path}/frames?at=|seams=|count=&max_dimension=` -
   JSON list of base64 PNG tiles with labels.
-- `GET /api/gallery/{name}/audio?start=&duration=` - WAV, mux-aware.
+- `GET /api/gallery/{name:path}/audio?start=&duration=` - mux-aware, WAV
+  for an excerpt or an extracted track, the file's own bytes otherwise.
 - All four accept an `asset:` name the way `metadata` does (#127), and
   `workspace`. Paths go through `validate_output_path` / the asset resolver
   as every other route does.
-- A decoded file is cached per `(path, mtime)` for the life of one request
-  only - five probes must not decode a four-minute cut five times, and
-  nothing is held across calls.
+- One request, one streaming pass: `assess` decodes the file once and hands
+  the reduced per-frame/per-sample data to every probe. Nothing is held
+  across requests.
 
 **MCP** - `dw_mcp/assess.py`, wired in `server.py`: `assess_output(name,
 detail=False, workspace=None)`, `inspect_output(name, probe, workspace=None,
@@ -231,12 +310,13 @@ first cut.
 
 ### One skill, family-agnostic: `dw:judging-output`
 
-A new plugin skill in `plugins/dw/skills/judging-output/`, listed in
-`plugins/dw/README.md` and pinned by `tests/test_plugin_skills.py` like the
-others. It is the *procedure* for the redo-or-tweak loop, and it is one
-skill rather than a section in each family's because the loop is the same
-for an H3 cut and an LTX chain, and because `minimax-h3` and `ltx-2.5` are
-each within 40 bytes of the 12 KiB skill cap and cannot absorb it.
+A new plugin skill in `plugins/dw/skills/judging-output/`, named in
+backticks in `plugins/dw/README.md` and `CLAUDE.md` as
+`tests/test_plugin_skills.py` requires. It is the *procedure* for the
+redo-or-tweak loop, and it is one skill rather than a section in each
+family's because the loop is the same for an H3 cut and an LTX chain, and
+because `minimax-h3` (12284 of 12288 bytes) and `ltx-2.5` (12254) cannot
+absorb it.
 
 Trigger line: use when a dw run has finished and the user wants to know
 whether it is good, or when a family skill's "run and judge" step hands off
@@ -251,8 +331,9 @@ Body, in order:
    verdicts. One paragraph on each rule family: what the number is, what
    usually caused it in this catalog, and what it looks like when it is
    *fine* (a hard cut trips `seam_frame_jump`; a whispered line trips
-   `segment_level_spread`).
-3. **Drill down with `inspect_output(probe=...)` and `get_output_frames(seams=[n])`** on a flagged finding.
+   `shot_level_spread`).
+3. **Drill down with `inspect_output(probe=...)` and
+   `get_output_frames(seams=[n])`** on a flagged finding.
 4. **Remediation table** - the part only the skill can hold, because it
    names template variables: a `seam_level_step` on an H3 cut →
    `match_levels_dbfs`; a `seam_hole` → `audio_bleed_ms`; a `sync_drift`
@@ -271,10 +352,14 @@ Body, in order:
    honest limit, stated once.
 
 The family skills' "run and judge" steps shrink to a pointer: `minimax-h3`
-step 4 ("You cannot watch a video") is rewritten to name
-`get_output_frames` and hand off to `dw:judging-output`; `series-episodes`
-"watch two episodes back to back" points at the same place;
-`ltx-2.5` likewise. That rewrite frees bytes rather than spending them.
+step 4 ("You cannot watch a video", ~700 bytes) is replaced by a shorter
+step naming `get_output_frames` and handing off to `dw:judging-output` -
+the replacement is budgeted to be shorter than what it replaces, since the
+skill has four bytes of headroom; `series-episodes` "watch two episodes
+back to back" points at the same place; `ltx-2.5` likewise. The
+thresholds the new skill quotes are pinned to `dw/assessment_rules.py` by a
+new test in the `test_plugin_skills.py` style (that file's existing pins are
+to diffusers symbols; this is the same pattern against a different table).
 
 ### How the capability reaches an agent without the plugin
 
@@ -284,18 +369,21 @@ Three layers, each already the way this repo communicates a capability:
   a bare MCP client reads. `assess_output`'s says what it checks, that the
   findings are places to look, and that `inspect_output`, `get_output_frames`
   and `get_output_audio` are the drill-down. `get_gallery_metadata`'s
-  description points at `assess_output` for a cut ("whole-file numbers
-  cannot see inside a join"). `get_job`'s `next` hint for a finished
-  video job names `assess_output`.
+  description and its existing `next` hint point at `assess_output` for a
+  cut ("whole-file numbers cannot see inside a join"). No hint is added to
+  `get_job` - it has none today and #101's budget applies to every job
+  read.
 - **The guide** (`docs/WORKFLOW_GUIDE.md`, read over `get_guide`) gains a
-  section *Assessing a run's output*, indexed like the others, holding the
-  probe table, the findings shape and the authority rule - so an agent that
-  was told "check the seams" can look the mechanism up rather than guess at
-  it. `list_guides` is what makes a section findable by name.
-- **The task catalog** (`list_tasks` / `get_task`): each probe's docstring is
-  its `get_task` description, and `list_tasks` tags the five with a
-  `assessment` category so they sort together. `docs/TASKS.md` gets one
-  section per probe as `analyze_audio` has.
+  `## Assessing a run's output` section (top-level headings are what
+  `list_guides` indexes), holding the probe table, the findings shape and
+  the authority rule - so an agent told "check the seams" can look the
+  mechanism up rather than guess at it.
+- **The task catalog** (`list_tasks` / `get_task`): each probe's docstring
+  is its `get_task` description. `list_tasks` has no categories today (three
+  flat lists from `dw/introspection.py`, consumed by the web UI editor), so
+  the five probes are listed under a new fourth list, `assessment`, rather
+  than tagged - a new field the editor can ignore. `docs/TASKS.md` gets one
+  `### <probe>` section each, as `analyze_audio` has.
 
 The MCP server's own instructions block (the text in `dw_mcp/server.py` that
 a client shows at connect) gains one sentence in the loop description:
@@ -309,22 +397,33 @@ look; `get_output_frames` and `get_output_audio` let you look and listen."
   tests `frame_grid`: a cut with a known 6 dB step at seam 2 must flag
   `seam_level_step` at seam 2 and nowhere else; a track padded by 267 samples
   per shot must report the drift the issue measured; a dissolve must not
-  flag a step; a `hard_cut` boundary must not flag a jump.
+  flag a step; a `hard_cut` boundary must not flag a jump; a static shot
+  followed by a cut must not flag `seam_frame_jump` on the 90th-percentile
+  baseline. Stage 3's tests pass `shots` as the argument, so they land
+  without stage 2.
 - **The rules table is pinned** (`tests/test_assessment_rules.py`): every
   rule names a field the probe actually returns; every threshold in the
-  skill's prose matches the table (the `test_plugin_skills.py` pattern).
+  skill's prose matches the table.
+- **Every `AudioVideo(` constructor has a rule**: a test enumerates the
+  constructor sites and fails on one the table in section 3 does not name.
 - **Boundary persistence round-trips**: `concat_videos` → save → manifest
-  entry → `read_embedded_metadata` on the mp4 → the same list; `keep_output`
-  keeps it; a `slice` that changes the timeline drops it.
+  entry → `read_embedded_metadata` on the remuxed mp4 → the same list;
+  `keep_output` keeps it; `pair_audio` recomputes the sample fields; a
+  `slice_audio` drops it. `start_sample` on a synthetic cut whose shots
+  each overrun by 267 samples records the overrun.
+- **Memory**: `assess` on a long synthetic clip holds no per-frame image
+  list (assert on peak RSS or on the streaming reader never being asked for
+  a full frame list).
 - **Budget**: `get_output_frames` on a 4K clip lands under
   `MAX_RETURNED_BYTES` and says it halved the dimension.
 - **Routes**: the four `/api/gallery/{name}/...` routes refuse a traversal,
-  answer 400 for an unknown probe naming the whitelist, and accept an
-  `asset:` name.
+  answer 400 for an unknown probe naming the whitelist, forward only a
+  probe's declared arguments, and accept an `asset:` name.
 - **Field test on lem**: `assess_output` over MCP on an existing
-  `music-video` and `dialogue-short` run, and on the #197 repro cut, before
-  the skill's threshold prose is finalised - the starting thresholds above
-  are guesses until they have met real output.
+  `music-video` and `dialogue-short` run, a `chained-segments` run, and the
+  #197 repro cut, before the skill's threshold prose is finalised and before
+  `av_correlation` gets a rule - the starting thresholds above are guesses
+  until they have met real output.
 
 ## Not in scope
 
@@ -344,13 +443,39 @@ Four independently landable pieces, each its own branch off `develop`:
 1. **Evidence**: mux-aware `get_output_audio` with excerpts;
    `get_output_frames` and its route. Closes the perceptual half of #193
    on its own.
-2. **Boundaries**: `segments` on the artifact, the manifest, the mp4 tag;
-   `media.segments` in metadata.
-3. **Probes and rules**: the five tasks, the table, `assess` / `inspect`
-   routes and tools; guide section; `list_tasks` category.
+2. **Boundaries**: `shots` on the artifact (every constructor ruled), the
+   manifest, the remux tag; `media.shots` in metadata; the workflow-layer
+   rename from `gather:`.
+3. **Probes and rules**: the five tasks, the streaming reader, the table,
+   `assess` / `inspect` routes and tools; guide section; `list_tasks`
+   fourth list. Tests use the `shots` argument; a probe on a file with no
+   boundaries answers `shots_source: "none"`.
 4. **Skill**: `dw:judging-output`, the family-skill rewrites, the field
-   test that sets the thresholds.
-
-Release note items: `get_output_audio` no longer refuses `video/mp4`;
-manifest entries and mp4 files carry `segments`; `minimax-h3` step 4 is
-rewritten.
+   test that sets the thresholds and decides `av_correlation`'s rule.
+
+Release note items: `get_output_audio` no longer refuses `video/mp4` and
+moved off the `/outputs` mount; manifest entries and mp4 files carry
+`shots`; `list_tasks` has a fourth list; `minimax-h3` step 4 is rewritten.
+
+## Review findings (2026-09-20)
+
+A review pass against the code changed the design in these ways:
+
+- `result.py` does not own the mp4 container (diffusers' `encode_video` /
+  `export_to_video` write it), so the file tag is written by a post-write
+  remux pass, not "at mux time".
+- The existing loaders materialise every frame and snap audio to the frame
+  count within 0.25 s, so probes stream and `analyze_sync_drift` reads
+  stream durations from the container.
+- A task cannot see `for_each` names; the workflow layer assigns them from
+  the `gather:` reference list.
+- `start_sample` must be measured from the accumulated waveform or the
+  drift probe measures its own record.
+- `run_chain` is the other join and populates `shots`; every `AudioVideo(`
+  constructor has an enumerated rule.
+- `segments` renamed `shots` to keep clear of chain segments.
+- `sync_length` subtracts codec priming (43 ms at 24 kHz); `jump_ratio`
+  uses a 90th-percentile floored baseline; `av_correlation` has no rule
+  until lem data; `get_output_audio` keeps its whole-file refusal; probe
+  steps require `application/json`; `list_tasks` gets a fourth list rather
+  than a tag; no `next` hint on `get_job`.

From 8f606e4080fea367b33d006fa7b5188ff192fabb Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sun, 20 Sep 2026 08:16:55 -0500
Subject: [PATCH 75/77] docs: #193 - stage 1 (evidence) implementation plan

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 ...9-20-output-assessment-stage-1-evidence.md | 1708 +++++++++++++++++
 1 file changed, 1708 insertions(+)
 create mode 100644 docs/superpowers/plans/2026-09-20-output-assessment-stage-1-evidence.md

diff --git a/docs/superpowers/plans/2026-09-20-output-assessment-stage-1-evidence.md b/docs/superpowers/plans/2026-09-20-output-assessment-stage-1-evidence.md
new file mode 100644
index 00000000..f0f4ec53
--- /dev/null
+++ b/docs/superpowers/plans/2026-09-20-output-assessment-stage-1-evidence.md
@@ -0,0 +1,1708 @@
+# Output Assessment, Stage 1 (Evidence) Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Let an MCP agent hear a generated video's soundtrack (or an excerpt of any track) and see frames from a generated video - the perceptual half of #193 - without any new engine task.
+
+**Architecture:** Two small PyAV-only modules beside `dw/media_info.py` (`dw/media_audio.py` extracts a WAV excerpt, `dw/media_frames.py` seeks out frames and composes tiles), two new gallery routes in `dw/server/app.py` in the existing `{name:path}/metadata` family, and on the MCP side `get_output_audio` moves to the new audio route and gains `start`/`duration`, and a new `get_output_frames` tool returns `ImageContent` tiles. Nothing touches the worker or the queue; everything runs in the server process like `metadata?envelope=true`.
+
+**Tech Stack:** Python 3.11, FastAPI, PyAV 18 (`av`), numpy, Pillow, httpx MockTransport for MCP tests, pytest via `venv/bin/python -m pytest`.
+
+**Spec:** `docs/proposals/output-assessment.md` - sections 2 and 5 are what this stage implements; section 3's `shots` (boundaries) is stage 2, so in this stage seam tiles take the boundaries as an explicit argument and nothing reads a manifest.
+
+## Global Constraints
+
+- Inline payloads are capped at `MAX_RETURNED_BYTES` (4 MB base64) in `dw_mcp/media.py`; a whole file over it is refused, never truncated, and the refusal names the excerpt path (spec section 2).
+- An excerpt names itself: the answer carries `excerpt: {start, duration, of}`.
+- New routes accept an `asset:` name the way `metadata` does (#127), and `workspace`.
+- Every path reaches the disk through `_output_file` / `_asset_file` (`validate_path` inside) - never a bare `os.path.join` (CLAUDE.md, Security Rules; CodeQL models these as sanitizers).
+- `dw_mcp/` must not import `dw.*` (a test guards that boundary).
+- Tool count is pinned: `docs/MCP.md` line ~190 says how many tools; `tests/test_mcp_server.py::test_the_stated_tool_count_is_the_registered_one` compares it to `EXPECTED_TOOLS`.
+- Commit messages: `feat(mcp): #193 - ...` / `feat(server): #193 - ...`, ending with the attribution line the session reminder gives.
+- Run tests with `venv/bin/python -m pytest` (torch is present in that venv).
+- Branch: `feat/193-evidence` off `develop`.
+
+---
+
+### Task 1: `dw/media_audio.py` - a WAV excerpt of any file's soundtrack
+
+**Files:**
+- Create: `dw/media_audio.py`
+- Test: `tests/test_media_audio.py`
+
+**Interfaces:**
+- Consumes: `tests/test_media_info.py::write_mp4(path, frames, fps, width, height, with_audio)` and `write_wav(path, seconds, sample_rate, amplitude)` fixtures (8 kHz stereo, 220 Hz tone).
+- Produces: `extract_audio(path, start=None, duration=None) -> (bytes, dict)` - 16-bit PCM WAV bytes and `{"sample_rate": int, "channels": int, "duration_seconds": float, "of_seconds": float, "start": float, "excerpt": bool}`. Raises `NoSoundtrack` (subclass of `ValueError`) when the file has no audio stream, and `ValueError` when `start` is past the end or `duration <= 0`.
+
+- [ ] **Step 1: Write the failing tests**
+
+```python
+# tests/test_media_audio.py
+"""extract_audio hands back a soundtrack, or a named slice of one, as WAV -
+what get_output_audio needs for a muxed video and for a track too long to
+send whole."""
+
+import io
+import wave
+
+import numpy
+import pytest
+
+from dw.media_audio import NoSoundtrack, extract_audio
+from tests.test_media_info import write_mp4, write_wav
+
+
+def read_wav(data):
+    with wave.open(io.BytesIO(data)) as handle:
+        frames = handle.readframes(handle.getnframes())
+        samples = numpy.frombuffer(frames, dtype="<i2").reshape(-1, handle.getnchannels())
+        return handle.getframerate(), samples
+
+
+def test_a_video_soundtrack_comes_back_whole_as_wav(tmp_path):
+    write_mp4(tmp_path / "shot.mp4", frames=12, fps=6)  # 2 s of tone at 8 kHz
+
+    data, info = extract_audio(str(tmp_path / "shot.mp4"))
+
+    rate, samples = read_wav(data)
+    assert rate == 8000
+    assert samples.shape[1] == 2
+    assert info["channels"] == 2
+    assert info["sample_rate"] == 8000
+    assert info["excerpt"] is False
+    assert info["of_seconds"] == pytest.approx(2.0, abs=0.1)
+    assert info["duration_seconds"] == pytest.approx(info["of_seconds"], abs=0.05)
+    # the tone is there, not silence
+    assert numpy.abs(samples).max() > 1000
+
+
+def test_an_excerpt_is_cut_where_asked_and_says_so(tmp_path):
+    write_wav(tmp_path / "score.wav", seconds=4.0)
+
+    data, info = extract_audio(str(tmp_path / "score.wav"), start=1.0, duration=0.5)
+
+    rate, samples = read_wav(data)
+    assert samples.shape[0] == pytest.approx(0.5 * rate, abs=rate * 0.02)
+    assert info["excerpt"] is True
+    assert info["start"] == 1.0
+    assert info["duration_seconds"] == pytest.approx(0.5, abs=0.02)
+    assert info["of_seconds"] == pytest.approx(4.0, abs=0.05)
+
+
+def test_an_excerpt_past_the_end_is_clipped_to_it(tmp_path):
+    write_wav(tmp_path / "score.wav", seconds=2.0)
+
+    data, info = extract_audio(str(tmp_path / "score.wav"), start=1.5, duration=5.0)
+
+    rate, samples = read_wav(data)
+    assert samples.shape[0] == pytest.approx(0.5 * rate, abs=rate * 0.02)
+    assert info["duration_seconds"] == pytest.approx(0.5, abs=0.02)
+
+
+def test_a_start_past_the_end_is_refused(tmp_path):
+    write_wav(tmp_path / "score.wav", seconds=2.0)
+
+    with pytest.raises(ValueError, match="past the end"):
+        extract_audio(str(tmp_path / "score.wav"), start=3.0, duration=1.0)
+
+
+def test_a_non_positive_duration_is_refused(tmp_path):
+    write_wav(tmp_path / "score.wav", seconds=2.0)
+
+    with pytest.raises(ValueError, match="duration"):
+        extract_audio(str(tmp_path / "score.wav"), start=0.0, duration=0.0)
+
+
+def test_a_silent_video_has_no_soundtrack(tmp_path):
+    write_mp4(tmp_path / "mute.mp4", frames=6, fps=6, with_audio=False)
+
+    with pytest.raises(NoSoundtrack):
+        extract_audio(str(tmp_path / "mute.mp4"))
+```
+
+- [ ] **Step 2: Run the tests to verify they fail**
+
+Run: `venv/bin/python -m pytest tests/test_media_audio.py -v`
+Expected: FAIL with `ModuleNotFoundError: No module named 'dw.media_audio'`
+
+- [ ] **Step 3: Write the module**
+
+```python
+# dw/media_audio.py
+"""A soundtrack, or a named slice of one, as WAV bytes - the form
+get_output_audio hands an agent for a muxed video (whose container it
+cannot play) or for a track too long to send whole (#193).
+
+PyAV only, like media_info: this runs in the server process, where a
+request must not pull in torch or materialise frames.
+"""
+
+import io
+import logging
+import wave
+
+import av
+import numpy
+from av.audio.resampler import AudioResampler
+
+logger = logging.getLogger("dw")
+
+
+class NoSoundtrack(ValueError):
+    """The file has no audio stream to extract."""
+
+
+def extract_audio(path, start=None, duration=None):
+    """The soundtrack of `path` as 16-bit PCM WAV bytes, plus what was cut.
+
+    With `start` and `duration` (seconds) only that slice is decoded and
+    returned; the info dict says so (`excerpt: True`) and carries the whole
+    track's length as `of_seconds`, so a slice always names itself. A
+    slice that runs past the end is clipped to it; a `start` past the end
+    is refused, since an empty answer would read as a silent track.
+
+    Returns:
+        (wav_bytes, info) with info = {sample_rate, channels,
+        duration_seconds, of_seconds, start, excerpt}
+    """
+    excerpt = start is not None or duration is not None
+    start = float(start or 0.0)
+    if excerpt and (duration is None or float(duration) <= 0):
+        raise ValueError("An excerpt needs a duration above zero")
+    if start < 0:
+        raise ValueError("An excerpt cannot start before zero")
+
+    with av.open(path) as container:
+        if not container.streams.audio:
+            raise NoSoundtrack(f"{path} has no soundtrack")
+        stream = container.streams.audio[0]
+        total = (
+            float(container.duration / av.time_base)
+            if container.duration is not None
+            else None
+        )
+        if total is not None and start >= total:
+            raise ValueError(
+                f"start {start:.2f}s is past the end of a {total:.2f}s track"
+            )
+        stop = start + float(duration) if excerpt else None
+        if stop is not None and total is not None:
+            stop = min(stop, total)
+
+        rate = int(stream.rate)
+        channels = int(stream.channels)
+        layout = "stereo" if channels == 2 else ("mono" if channels == 1 else stream.layout.name)
+        resampler = AudioResampler(format="s16", layout=layout, rate=rate)
+
+        if start > 0:
+            # Seek to the keyframe at or before `start`; the frames decoded
+            # before `start` are then dropped sample-accurately below
+            container.seek(int(start / stream.time_base), stream=stream, backward=True)
+
+        pieces = []
+        seen = 0  # samples of the track before the current frame
+        started = False
+        for frame in container.decode(stream):
+            frame_start = (
+                float(frame.pts * stream.time_base) if frame.pts is not None else seen / rate
+            )
+            for chunk in resampler.resample(frame):
+                samples = chunk.to_ndarray()  # (1, samples * channels) packed s16
+                samples = samples.reshape(-1, channels)
+                chunk_start = frame_start
+                chunk_end = chunk_start + samples.shape[0] / rate
+                if chunk_end <= start:
+                    seen += samples.shape[0]
+                    continue
+                if not started and chunk_start < start:
+                    samples = samples[int((start - chunk_start) * rate) :]
+                    chunk_start = start
+                started = True
+                if stop is not None and chunk_end > stop:
+                    samples = samples[: max(0, int((stop - chunk_start) * rate))]
+                pieces.append(samples)
+                if stop is not None and chunk_end >= stop:
+                    break
+        # flush the resampler
+        if stop is None:
+            for chunk in resampler.resample(None):
+                pieces.append(chunk.to_ndarray().reshape(-1, channels))
+
+    pcm = numpy.concatenate(pieces) if pieces else numpy.zeros((0, channels), "<i2")
+    buffer = io.BytesIO()
+    with wave.open(buffer, "w") as handle:
+        handle.setnchannels(channels)
+        handle.setsampwidth(2)
+        handle.setframerate(rate)
+        handle.writeframes(pcm.astype("<i2").tobytes())
+
+    returned = pcm.shape[0] / rate
+    return buffer.getvalue(), {
+        "sample_rate": rate,
+        "channels": channels,
+        "duration_seconds": returned,
+        "of_seconds": total if total is not None else returned,
+        "start": start,
+        "excerpt": excerpt,
+    }
+```
+
+- [ ] **Step 4: Run the tests until they pass**
+
+Run: `venv/bin/python -m pytest tests/test_media_audio.py -v`
+Expected: PASS (6 tests). If the AAC fixture's `of_seconds` is a hair over 2.0 from codec padding, the `abs=0.1` tolerance covers it; do not loosen further - a wide tolerance would hide a broken cut.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add dw/media_audio.py tests/test_media_audio.py
+git commit -m "feat(server): #193 - extract_audio, a WAV excerpt of any file's soundtrack"
+```
+
+---
+
+### Task 2: `GET /api/gallery/{name}/audio` - the soundtrack route
+
+**Files:**
+- Modify: `dw/server/app.py` (after `gallery_metadata`, ~line 2810; import beside `from ..media_info import probe_media` at line 74)
+- Test: `tests/test_server.py` (beside `test_gallery_metadata_describes_audio_and_video`, ~line 1250, and the asset tests ~line 4534)
+
+**Interfaces:**
+- Consumes: `extract_audio`, `NoSoundtrack` from Task 1; `_output_file(name, root)`, `_asset_file(reference, ws)`, `is_asset_reference`, `MEDIA_KINDS`, `selected_workspace` already in `app.py`.
+- Produces: the route. Response is `audio/wav` bytes with headers `X-DW-Duration` (the whole track, seconds), and when an excerpt was asked for `X-DW-Excerpt-Start`, `X-DW-Excerpt-Duration`. An audio-only file asked for whole is served as its own bytes with its own content type (no transcode) and only `X-DW-Duration`. 404 when the file has no soundtrack; 400 when `start`/`duration` are bad.
+
+- [ ] **Step 1: Write the failing tests**
+
+```python
+# tests/test_server.py - add near test_gallery_metadata_describes_audio_and_video
+
+def test_gallery_audio_extracts_a_videos_soundtrack(server, tmp_path):
+    """get_output_audio refused video/mp4 outright, so a generated clip's
+    soundtrack could only be heard by fetching the file and demuxing it by
+    hand (#193). The route hands the track back as WAV."""
+    import io
+    import wave
+    from tests.test_media_info import write_mp4
+
+    with server(success_script) as client:
+        outputs = tmp_path / "outputs"
+        write_mp4(outputs / "shot-gen.0-0.0.mp4", frames=12, fps=6)
+
+        response = client.get("/api/gallery/shot-gen.0-0.0.mp4/audio")
+
+        assert response.status_code == 200
+        assert response.headers["content-type"] == "audio/wav"
+        assert float(response.headers["x-dw-duration"]) == pytest.approx(2.0, abs=0.1)
+        assert "x-dw-excerpt-start" not in response.headers
+        with wave.open(io.BytesIO(response.content)) as handle:
+            assert handle.getframerate() == 8000
+            assert handle.getnchannels() == 2
+
+
+def test_gallery_audio_serves_an_audio_file_as_itself_when_asked_whole(server, tmp_path):
+    from tests.test_media_info import write_wav
+
+    with server(success_script) as client:
+        outputs = tmp_path / "outputs"
+        write_wav(outputs / "score-gen.0-0.0.wav", seconds=1.0)
+        raw = (outputs / "score-gen.0-0.0.wav").read_bytes()
+
+        response = client.get("/api/gallery/score-gen.0-0.0.wav/audio")
+
+        assert response.status_code == 200
+        assert response.content == raw
+        assert float(response.headers["x-dw-duration"]) == pytest.approx(1.0, abs=0.05)
+
+
+def test_gallery_audio_cuts_an_excerpt_and_names_it(server, tmp_path):
+    import io
+    import wave
+    from tests.test_media_info import write_wav
+
+    with server(success_script) as client:
+        outputs = tmp_path / "outputs"
+        write_wav(outputs / "score-gen.0-0.0.wav", seconds=4.0)
+
+        response = client.get(
+            "/api/gallery/score-gen.0-0.0.wav/audio", params={"start": 1.0, "duration": 0.5}
+        )
+
+        assert response.status_code == 200
+        assert response.headers["content-type"] == "audio/wav"
+        assert response.headers["x-dw-excerpt-start"] == "1.0"
+        assert float(response.headers["x-dw-excerpt-duration"]) == pytest.approx(0.5, abs=0.02)
+        assert float(response.headers["x-dw-duration"]) == pytest.approx(4.0, abs=0.05)
+        with wave.open(io.BytesIO(response.content)) as handle:
+            assert handle.getnframes() == pytest.approx(4000, abs=100)
+
+
+def test_gallery_audio_refuses_a_bad_excerpt_and_a_mute_file(server, tmp_path):
+    from tests.test_media_info import write_mp4, write_wav
+
+    with server(success_script) as client:
+        outputs = tmp_path / "outputs"
+        write_wav(outputs / "score-gen.0-0.0.wav", seconds=2.0)
+        write_mp4(outputs / "mute-gen.0-0.0.mp4", frames=6, fps=6, with_audio=False)
+
+        past = client.get(
+            "/api/gallery/score-gen.0-0.0.wav/audio", params={"start": 5.0, "duration": 1.0}
+        )
+        assert past.status_code == 400
+        assert "past the end" in past.json()["detail"]
+
+        mute = client.get("/api/gallery/mute-gen.0-0.0.mp4/audio")
+        assert mute.status_code == 404
+        assert "soundtrack" in mute.json()["detail"]
+
+        still = client.get("/api/gallery/missing.png/audio")
+        assert still.status_code == 404
+
+
+def test_gallery_audio_reads_an_asset_reference(asset_server, tmp_path):
+    from tests.test_media_info import write_wav
+
+    with asset_server(success_script) as client:
+        write_wav(tmp_path / "assets" / "bed.wav", seconds=1.0)
+
+        response = client.get(
+            "/api/gallery/asset:bed.wav/audio", params={"start": 0.0, "duration": 0.25}
+        )
+
+        assert response.status_code == 200
+        assert float(response.headers["x-dw-excerpt-duration"]) == pytest.approx(0.25, abs=0.02)
+```
+
+Check how `asset_server` lays out its assets directory before relying on `tmp_path / "assets"`: read `test_gallery_metadata_reads_an_asset_reference` (~line 4534) and copy its setup exactly.
+
+- [ ] **Step 2: Run the tests to verify they fail**
+
+Run: `venv/bin/python -m pytest tests/test_server.py -k gallery_audio -v`
+Expected: FAIL with 404s (route does not exist; FastAPI answers "Not Found").
+
+- [ ] **Step 3: Add the route**
+
+Add the import at line 74:
+
+```python
+from ..media_info import probe_media
+from ..media_audio import NoSoundtrack, extract_audio
+```
+
+Add after `gallery_metadata`:
+
+```python
+    @app.get("/api/gallery/{name:path}/audio")
+    def gallery_audio(
+        name: str,
+        start: Optional[float] = None,
+        duration: Optional[float] = None,
+        ws: Workspace = Depends(selected_workspace),
+    ):
+        """The soundtrack of an output or asset, as WAV - a muxed video's
+        track, which `get_output_audio` used to refuse outright, or an
+        excerpt (`start` + `duration`, seconds) of a track too long to send
+        whole (#193). An excerpt names itself in the response headers
+        (`X-DW-Excerpt-Start`, `X-DW-Excerpt-Duration`) beside the whole
+        track's `X-DW-Duration`, so a cut is never silent (#204).
+
+        An audio-only file asked for whole is served as its own bytes in its
+        own encoding - there is nothing to extract, and a transcode would
+        change what the agent hears."""
+        if is_asset_reference(name):
+            path = _asset_file(name, ws)
+        else:
+            path = _output_file(name, ws.outputs)
+        extension = os.path.splitext(path)[1].lower()
+        kind = MEDIA_KINDS.get(extension)
+        if kind not in ("audio", "video"):
+            raise HTTPException(status_code=404, detail=f"{name} carries no soundtrack")
+
+        excerpt = start is not None or duration is not None
+        if kind == "audio" and not excerpt:
+            media = probe_media(path) or {}
+            headers = {"X-DW-Duration": str(media.get("duration_seconds", ""))}
+            media_type = mimetypes.guess_type(path)[0] or "application/octet-stream"
+            return FileResponse(path, media_type=media_type, headers=headers)
+
+        try:
+            data, info = extract_audio(path, start=start, duration=duration)
+        except NoSoundtrack:
+            raise HTTPException(status_code=404, detail=f"{name} carries no soundtrack")
+        except ValueError as e:
+            raise HTTPException(status_code=400, detail=str(e))
+        headers = {"X-DW-Duration": str(info["of_seconds"])}
+        if info["excerpt"]:
+            headers["X-DW-Excerpt-Start"] = str(info["start"])
+            headers["X-DW-Excerpt-Duration"] = str(info["duration_seconds"])
+        return Response(content=data, media_type="audio/wav", headers=headers)
+```
+
+Add `import mimetypes` to the stdlib imports at the top of `app.py` (line 8 block) if it is not already there.
+
+- [ ] **Step 4: Run the tests until they pass**
+
+Run: `venv/bin/python -m pytest tests/test_server.py -k gallery_audio -v`
+Expected: PASS (5 tests).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add dw/server/app.py tests/test_server.py
+git commit -m "feat(server): #193 - GET /api/gallery/{name}/audio serves a soundtrack or an excerpt of one"
+```
+
+---
+
+### Task 3: `get_output_audio` moves to the route and takes an excerpt
+
+**Files:**
+- Modify: `dw_mcp/client.py:177-197` (`get_bytes_if`)
+- Modify: `dw_mcp/media.py:106-140` (`get_output_audio`)
+- Modify: `dw_mcp/server.py:550-574` (the tool)
+- Modify: `tests/test_mcp_server.py:359` (wiring row), `tests/test_mcp_media.py`
+- Modify: `docs/MCP.md:237` (tool row) and `:456-458` (the "Images and audio only" bullet), `dw_mcp/CLAUDE.md` (the `get_output_audio` sentence)
+
+**Interfaces:**
+- Consumes: Task 2's route and headers.
+- Produces: `DwClient.get_media_if(path, accept_content_type, workspace=None, params=None) -> (body | None, content_type, headers)`; `media.get_output_audio(client, name, start=None, duration=None, workspace=None) -> {name, data, mime_type, bytes, duration_seconds, excerpt: None | {start, duration, of}}`.
+
+- [ ] **Step 1: Write the failing tests**
+
+```python
+# tests/test_mcp_media.py - add
+
+def serving_with_headers(content, content_type, headers):
+    def handler(request):
+        return httpx.Response(
+            200, content=content, headers={"content-type": content_type, **headers}
+        )
+
+    return DwClient(transport=httpx.MockTransport(handler))
+
+
+def test_audio_is_fetched_from_the_gallery_audio_route():
+    seen = []
+
+    def handler(request):
+        seen.append((request.url.path, dict(request.url.params)))
+        return httpx.Response(
+            200,
+            content=b"riff",
+            headers={"content-type": "audio/wav", "x-dw-duration": "2.0"},
+        )
+
+    client = DwClient(transport=httpx.MockTransport(handler))
+    result = get_output_audio(client, "run/shot.mp4")
+
+    assert seen == [("/api/gallery/run%2Fshot.mp4/audio", {})]
+    assert result["mime_type"] == "audio/wav"
+    assert result["duration_seconds"] == 2.0
+    assert result["excerpt"] is None
+
+
+def test_an_excerpt_is_asked_for_and_reported():
+    seen = []
+
+    def handler(request):
+        seen.append(dict(request.url.params))
+        return httpx.Response(
+            200,
+            content=b"riff",
+            headers={
+                "content-type": "audio/wav",
+                "x-dw-duration": "240.0",
+                "x-dw-excerpt-start": "10.0",
+                "x-dw-excerpt-duration": "2.0",
+            },
+        )
+
+    client = DwClient(transport=httpx.MockTransport(handler))
+    result = get_output_audio(client, "cut.mp4", start=10.0, duration=2.0)
+
+    assert seen == [{"start": "10.0", "duration": "2.0"}]
+    assert result["excerpt"] == {"start": 10.0, "duration": 2.0, "of": 240.0}
+
+
+def test_a_whole_track_over_budget_is_refused_and_told_to_excerpt():
+    big = b"\0" * (MAX_RETURNED_BYTES * 3 // 4 + 1024)
+    client = serving_with_headers(big, "audio/wav", {"x-dw-duration": "240.0"})
+
+    with pytest.raises(DwApiError) as caught:
+        get_output_audio(client, "cut.mp4")
+
+    assert "start" in str(caught.value) and "duration" in str(caught.value)
+
+
+def test_a_non_audio_answer_is_refused():
+    client = serving(b"{}", "application/json")
+
+    with pytest.raises(DwApiError, match="not audio"):
+        get_output_audio(client, "thing.json")
+```
+
+Also update the existing `get_output_audio` tests in this file that assert the `/outputs/` path or the old refusal wording on `video/mp4` - read them (`grep -n get_output_audio tests/test_mcp_media.py`) and change the ones whose premise this task removes: a `video/mp4` body is no longer a refusal case at the client (the server now answers WAV), so delete that test or turn it into the "non audio answer" one above.
+
+In `tests/test_mcp_server.py` change the wiring row:
+
+```python
+    ("get_output_audio", {"name": "out.wav"}, "GET", "/api/gallery/out.wav/audio"),
+```
+
+and the wiring handler in `test_each_tool_calls_its_endpoint` already answers `audio/wav` for paths ending `.wav` - it ends with `/audio` now, so change that branch to `if request.url.path.endswith("/audio"):`.
+
+- [ ] **Step 2: Run the tests to verify they fail**
+
+Run: `venv/bin/python -m pytest tests/test_mcp_media.py tests/test_mcp_server.py -k "audio" -v`
+Expected: FAIL - path is `/outputs/...`, `excerpt` key missing, `TypeError` on `start=`.
+
+- [ ] **Step 3: Extend the client**
+
+In `dw_mcp/client.py`, replace `get_bytes_if` with:
+
+```python
+    def get_media_if(self, path, accept_content_type, workspace=None, params=None):
+        """Like `get_bytes`, but the body is only downloaded when
+        `accept_content_type(content_type)` is true, and the response
+        headers come back with it - a media route says what it cut in
+        them.
+
+        Headers arrive before the body over HTTP, so a rejection closes the
+        connection having read nothing past them - useful for `/outputs`,
+        where a rejected file (a video, say) can be arbitrarily large.
+        Returns `(None, content_type, headers)` on rejection, `(body,
+        content_type, headers)` on acceptance. An error status is still
+        raised either way, since the body has to be read to report it.
+        """
+        kwargs = {"params": params} if params else {}
+        response = self._stream_request("GET", path, workspace=workspace, **kwargs)
+        try:
+            content_type = response.headers.get("content-type", "")
+            if response.status_code < 400 and not accept_content_type(content_type):
+                return None, content_type, response.headers
+            self._call_httpx(response.read, path)
+            self._raise_for_status(response, path)
+            return response.content, content_type, response.headers
+        finally:
+            response.close()
+
+    def get_bytes_if(self, path, accept_content_type, workspace=None):
+        """`get_media_if` without the headers, for the callers that only
+        want the body."""
+        body, content_type, _headers = self.get_media_if(
+            path, accept_content_type, workspace=workspace
+        )
+        return body, content_type
+```
+
+Check `_scoped` merges `params` rather than replacing them (read `dw_mcp/client.py:250-270`); if it does `kwargs.setdefault("params", {})` then `.setdefault("workspace", ...)`, passing `params` works as-is. If it replaces, fix `_scoped` to merge.
+
+- [ ] **Step 4: Rewrite the handler**
+
+In `dw_mcp/media.py` replace `get_output_audio`:
+
+```python
+def get_output_audio(client, name, start=None, duration=None, workspace=None):
+    """One soundtrack from the gallery as base64 WAV - an audio output, or
+    the track muxed into a video (#193) - for a clip short enough to fit
+    MAX_RETURNED_BYTES whole, or an excerpt of one that is not.
+
+    Audio is not resized the way an image is - there is no downscale of a
+    waveform that keeps it meaningful to listen to - so a whole clip over
+    budget is refused rather than truncated (#204). The way to hear part of
+    a long track is to *ask* for the part: `start` and `duration` in
+    seconds, and the answer names what it cut in `excerpt`, so a slice is
+    never mistaken for the whole."""
+
+    def is_audio(content_type):
+        return bool(content_type) and content_type.startswith("audio/")
+
+    params = {}
+    if start is not None:
+        params["start"] = start
+    if duration is not None:
+        params["duration"] = duration
+    body, content_type, headers = client.get_media_if(
+        api_path("api", "gallery", name, "audio"),
+        is_audio,
+        workspace=workspace,
+        params=params,
+    )
+    if body is None:
+        raise DwApiError(
+            f"{name} answered {content_type or 'no declared type'}, not audio - "
+            "this tool returns a soundtrack only. Use get_output_image for "
+            "an image, or get_gallery_metadata for other media."
+        )
+
+    base64_size = 4 * math.ceil(len(body) / 3)
+    if base64_size > MAX_RETURNED_BYTES:
+        raise DwApiError(
+            f"{name} is {len(body)} bytes, which would be {base64_size} "
+            f"bytes base64-encoded - over the {MAX_RETURNED_BYTES} byte "
+            "limit for an inline clip. Ask for an excerpt with `start` and "
+            "`duration` (seconds) - get_gallery_metadata's envelope says "
+            "where to look - or use download_output for the whole file."
+        )
+
+    excerpt = None
+    if "x-dw-excerpt-start" in headers:
+        excerpt = {
+            "start": float(headers["x-dw-excerpt-start"]),
+            "duration": float(headers["x-dw-excerpt-duration"]),
+            "of": _float_header(headers, "x-dw-duration"),
+        }
+    return {
+        "name": name,
+        "data": base64.b64encode(body).decode("ascii"),
+        "mime_type": content_type,
+        "bytes": len(body),
+        "duration_seconds": _float_header(headers, "x-dw-duration"),
+        "excerpt": excerpt,
+    }
+
+
+def _float_header(headers, key):
+    value = headers.get(key)
+    try:
+        return float(value) if value not in (None, "") else None
+    except ValueError:
+        return None
+```
+
+- [ ] **Step 5: Update the tool in `dw_mcp/server.py`**
+
+```python
+    def get_output_audio(
+        name: str,
+        start: float | None = None,
+        duration: float | None = None,
+        workspace: str | None = None,
+    ) -> list[AudioContent | TextContent]:
+        """Listen to a generated soundtrack, named as `list_gallery` or a
+        job's manifest reports it - an audio output, or the track muxed
+        into a video (the audio analogue of `get_output_image`). There is
+        no downscale for audio, so a whole clip too large to fit inline is
+        refused rather than cut; hear part of a long one by asking for the
+        part - `start` and `duration` in seconds, around a seam or a
+        moment `get_gallery_metadata`'s envelope located. The text part
+        reports the whole track's length and, for an excerpt, exactly what
+        was cut, so a slice is never mistaken for the whole. To *see* a
+        video, `get_output_frames`.
+
+        `workspace` names the workspace for this one call without
+        switching the session to it - the same pin `run_workflow`
+        takes (#99)."""
+        result = media.get_output_audio(
+            client, name, start=start, duration=duration, workspace=workspace
+        )
+        audio = AudioContent(
+            type="audio", data=result["data"], mime_type=result["mime_type"]
+        )
+        lines = [f"name: {result['name']}", f"bytes: {result['bytes']}"]
+        if result["duration_seconds"] is not None:
+            lines.append(f"duration_seconds: {result['duration_seconds']}")
+        if result["excerpt"]:
+            e = result["excerpt"]
+            lines.append(f"excerpt: {e['duration']}s from {e['start']}s of {e['of']}s")
+        telemetry = TextContent(type="text", text="\n".join(lines))
+        return [audio, telemetry]
+```
+
+- [ ] **Step 6: Run the tests until they pass**
+
+Run: `venv/bin/python -m pytest tests/test_mcp_media.py tests/test_mcp_server.py tests/test_mcp_client.py -v`
+Expected: PASS. `test_wrapper_handler_map_covers_every_defaulted_handler` still passes (`get_output_audio` is already in the map).
+
+- [ ] **Step 7: Update the docs**
+
+`docs/MCP.md` line 237 row:
+
+```
+| `get_output_audio(name, start=None, duration=None, workspace=None)` | `name`, `start`, `duration`, `workspace` | Listen to a generated soundtrack as base64 WAV - an audio output, or the track muxed into a video (#193). No downscale exists for audio, so a whole clip over the 4MB budget is refused rather than cut (#204); ask for the part instead with `start` and `duration` in seconds, and the text part names what was cut (`excerpt: 2.0s from 10.0s of 240.0s`) so a slice is never mistaken for the whole. `get_gallery_metadata`'s envelope says where in a track to look. `workspace` names the workspace for this one call without switching the session to it |
+```
+
+`docs/MCP.md` lines ~456-458: replace the "Images and audio only" bullet with:
+
+```
+- **Images, sound and frames.** `get_output_image` returns an image,
+  `get_output_audio` a soundtrack (an audio file's, or the one muxed into a
+  video) whole or as a named excerpt, and `get_output_frames` frames of a
+  video as images - there is no video content type over MCP, so a video is
+  seen as frames and heard as its track. `get_output_audio` refuses a whole
+  clip whose base64 size would exceed the same 4MB budget; ask for an
+  excerpt instead.
+```
+
+`dw_mcp/CLAUDE.md`: replace the sentence beginning "`get_output_audio` is `get_output_image`'s sibling for audio" through "no `VideoContent` type to return it as." with:
+
+```
+`get_output_audio` is `get_output_image`'s sibling for sound (`media.py`,
+#204, #193): it reads `GET /api/gallery/{name}/audio`, which extracts a
+video's muxed track as WAV and cuts an excerpt on `start`/`duration`; a
+whole clip over the same 4MB budget is still refused rather than cut short,
+and the refusal says to ask for an excerpt. Video has no MCP content type,
+so `get_output_frames` returns frames of one as `ImageContent` - specific
+moments, a contact sheet, or the frame pair either side of each seam.
+```
+
+- [ ] **Step 8: Run the doc and MCP suites, then commit**
+
+Run: `venv/bin/python -m pytest tests/test_mcp_server.py tests/test_docs_links.py -q`
+Expected: PASS.
+
+```bash
+git add dw_mcp/client.py dw_mcp/media.py dw_mcp/server.py dw_mcp/CLAUDE.md docs/MCP.md tests/test_mcp_media.py tests/test_mcp_server.py
+git commit -m "feat(mcp): #193 - get_output_audio hears a video's soundtrack and takes an excerpt"
+```
+
+---
+
+### Task 4: `dw/media_frames.py` - frames by moment, a contact sheet, seam tiles
+
+**Files:**
+- Create: `dw/media_frames.py`
+- Test: `tests/test_media_frames.py`
+
+**Interfaces:**
+- Consumes: `dw.tasks.video_utils._grid_tile(frame, index, fps, tile_width, label)`, `_compose_grid(tiles, columns)`, `_default_columns(count)`, `_evenly_spaced_indices(total, count)` (all exist; `frame_grid` at `video_utils.py:177` is their caller). `video_utils` imports torch; that is fine in the server process, which already has it loaded.
+- Produces:
+  - `frames_at(path, moments) -> list[Tile]` where `moments` is a list of `float` seconds or `"frame:N"` strings and `Tile` is a `dict` `{"label": str, "frame": int, "seconds": float, "image": PIL.Image}`.
+  - `contact_sheet(path, count, tile_width=320) -> Tile` (one tile whose `image` is the grid, `label` = `"contact sheet, N frames"`).
+  - `seam_tiles(path, boundaries, names=None, tile_width=320) -> list[Tile]` where `boundaries` is a list of frame indexes at which each shot after the first *starts*, so seam *i* is between frame `boundaries[i]-1` and `boundaries[i]`; one side-by-side tile per seam, `label` = `"seam 1: <A> | <B>"` using `names` (defaults `"shot 1"`, `"shot 2"`, ...).
+  - `video_shape(path) -> {"frame_count": int, "fps": float | None, "width": int, "height": int}`.
+  - All raise `ValueError` for a moment past the end, a boundary outside `1..frame_count-1`, a file with no video stream.
+
+- [ ] **Step 1: Write the failing tests**
+
+```python
+# tests/test_media_frames.py
+"""Frames out of a file by seeking, not by decoding it whole - what
+get_output_frames needs so an agent can look at a moment, a contact sheet
+or the frame pair either side of a seam (#193)."""
+
+import numpy
+import pytest
+from PIL import Image
+
+from dw.media_frames import contact_sheet, frames_at, seam_tiles, video_shape
+
+
+def write_ramp_mp4(path, frames=24, fps=6, width=32, height=16):
+    """A clip whose frame N is a flat grey of value N*10, so a returned
+    frame says which one it is."""
+    import av
+
+    container = av.open(str(path), "w")
+    stream = container.add_stream("libx264", rate=fps)
+    stream.width, stream.height, stream.pix_fmt = width, height, "yuv420p"
+    stream.options = {"crf": "0", "preset": "ultrafast"}  # lossless, so grey survives
+    for index in range(frames):
+        pixels = numpy.full((height, width, 3), index * 10, numpy.uint8)
+        frame = av.VideoFrame.from_ndarray(pixels, format="rgb24")
+        for packet in stream.encode(frame):
+            container.mux(packet)
+    for packet in stream.encode():
+        container.mux(packet)
+    container.close()
+
+
+def grey_of(image):
+    return int(numpy.asarray(image.convert("L")).mean().round())
+
+
+def test_video_shape_reads_the_container(tmp_path):
+    write_ramp_mp4(tmp_path / "ramp.mp4", frames=24, fps=6)
+
+    shape = video_shape(str(tmp_path / "ramp.mp4"))
+
+    assert shape == {"frame_count": 24, "fps": 6.0, "width": 32, "height": 16}
+
+
+def test_frames_at_seeks_to_seconds_and_frame_indexes(tmp_path):
+    write_ramp_mp4(tmp_path / "ramp.mp4", frames=24, fps=6)
+
+    tiles = frames_at(str(tmp_path / "ramp.mp4"), [0.0, 2.0, "frame:23"])
+
+    assert [t["frame"] for t in tiles] == [0, 12, 23]
+    assert [t["seconds"] for t in tiles] == pytest.approx([0.0, 2.0, 23 / 6])
+    assert [grey_of(t["image"]) for t in tiles] == pytest.approx([0, 120, 230], abs=6)
+    assert tiles[1]["label"] == "00:02.0 (frame 12)"
+
+
+def test_a_moment_past_the_end_is_refused(tmp_path):
+    write_ramp_mp4(tmp_path / "ramp.mp4", frames=6, fps=6)
+
+    with pytest.raises(ValueError, match="past the end"):
+        frames_at(str(tmp_path / "ramp.mp4"), [5.0])
+    with pytest.raises(ValueError, match="past the end"):
+        frames_at(str(tmp_path / "ramp.mp4"), ["frame:6"])
+
+
+def test_a_contact_sheet_tiles_evenly_spaced_frames(tmp_path):
+    write_ramp_mp4(tmp_path / "ramp.mp4", frames=24, fps=6)
+
+    tile = contact_sheet(str(tmp_path / "ramp.mp4"), count=4, tile_width=32)
+
+    assert tile["label"] == "contact sheet, 4 frames"
+    assert tile["image"].width == 32 * 2  # 4 tiles, two columns
+    assert tile["image"].height == 16 * 2
+    # first tile is frame 0, last is frame 23
+    first = tile["image"].crop((0, 0, 32, 16))
+    last = tile["image"].crop((32, 16, 64, 32))
+    assert grey_of(first) < 20
+    assert grey_of(last) > 200
+
+
+def test_seam_tiles_pair_the_frames_either_side_of_each_boundary(tmp_path):
+    write_ramp_mp4(tmp_path / "ramp.mp4", frames=24, fps=6)
+
+    tiles = seam_tiles(
+        str(tmp_path / "ramp.mp4"),
+        boundaries=[8, 16],
+        names=["shot@a", "shot@b", "shot@c"],
+        tile_width=32,
+    )
+
+    assert [t["label"] for t in tiles] == ["seam 1: shot@a | shot@b", "seam 2: shot@b | shot@c"]
+    assert [t["frame"] for t in tiles] == [8, 16]
+    image = tiles[0]["image"]
+    assert image.width == 64 and image.height == 16
+    assert grey_of(image.crop((0, 0, 32, 16))) == pytest.approx(70, abs=6)  # frame 7
+    assert grey_of(image.crop((32, 0, 64, 16))) == pytest.approx(80, abs=6)  # frame 8
+
+
+def test_a_boundary_outside_the_clip_is_refused(tmp_path):
+    write_ramp_mp4(tmp_path / "ramp.mp4", frames=6, fps=6)
+
+    with pytest.raises(ValueError, match="boundary"):
+        seam_tiles(str(tmp_path / "ramp.mp4"), boundaries=[0])
+    with pytest.raises(ValueError, match="boundary"):
+        seam_tiles(str(tmp_path / "ramp.mp4"), boundaries=[6])
+```
+
+Note: the label tests burn text into the tile via `_grid_tile(label=True)`; `grey_of` tolerances of ±6 absorb the small label. If a label pushes a mean past the tolerance at 32x16, pass `label=False` inside `seam_tiles`/`frames_at` for the *sub*-tiles and put the label only in the returned dict - the server route burns nothing, the MCP telemetry text carries the label. Prefer that: the spec's "names burned in" is satisfied by a caption strip, which is Task 5's concern, not this module's.
+
+- [ ] **Step 2: Run the tests to verify they fail**
+
+Run: `venv/bin/python -m pytest tests/test_media_frames.py -v`
+Expected: FAIL with `ModuleNotFoundError: No module named 'dw.media_frames'`
+
+- [ ] **Step 3: Write the module**
+
+```python
+# dw/media_frames.py
+"""Frames out of a video file by seeking to them - a moment, an evenly
+spaced contact sheet, or the frame pair either side of a seam - without
+decoding the clip whole. The server process runs this per request; a
+four-minute 1080p clip materialised as PIL frames is tens of gigabytes,
+so nothing here ever holds more than the frames it returns (#193).
+"""
+
+import logging
+
+import av
+from PIL import Image
+
+from .tasks.video_utils import (
+    _compose_grid,
+    _default_columns,
+    _evenly_spaced_indices,
+    _format_timestamp,
+)
+
+logger = logging.getLogger("dw")
+
+
+def video_shape(path):
+    """Frame count, fps and size, from the container's own headers where
+    they are written and by counting otherwise."""
+    with av.open(path) as container:
+        if not container.streams.video:
+            raise ValueError(f"{path} has no video stream")
+        stream = container.streams.video[0]
+        fps = float(stream.average_rate) if stream.average_rate else None
+        count = int(stream.frames) if stream.frames else None
+        if count is None:
+            count = sum(1 for _ in container.decode(stream))
+        return {
+            "frame_count": count,
+            "fps": fps,
+            "width": int(stream.width),
+            "height": int(stream.height),
+        }
+
+
+def frames_at(path, moments):
+    """One tile per moment - a float in seconds or "frame:N" - in the order
+    asked for. Each tile is {label, frame, seconds, image}."""
+    shape = video_shape(path)
+    indexes = [_moment_to_index(moment, shape) for moment in moments]
+    images = _read_frames(path, indexes)
+    return [_tile(index, images[index], shape) for index in indexes]
+
+
+def contact_sheet(path, count, tile_width=320):
+    """N evenly spaced frames (first and last included) tiled into one
+    image - frame_grid without a workflow."""
+    if int(count) < 1:
+        raise ValueError("count must be at least 1")
+    shape = video_shape(path)
+    count = min(int(count), shape["frame_count"])
+    indexes = _evenly_spaced_indices(shape["frame_count"], count)
+    images = _read_frames(path, indexes)
+    tiles = [_fit_width(images[index], tile_width) for index in indexes]
+    grid = _compose_grid(tiles, _default_columns(len(tiles)))
+    return {
+        "label": f"contact sheet, {len(tiles)} frames",
+        "frame": indexes[0],
+        "seconds": _seconds(indexes[0], shape),
+        "image": grid,
+        "frames": list(indexes),
+    }
+
+
+def seam_tiles(path, boundaries, names=None, tile_width=320):
+    """For each boundary (the frame index a shot *starts* at), the last
+    frame before it and the first frame at it, side by side - the seam and
+    continuity evidence in one image. Seam i sits between shot i and shot
+    i+1; `names` names the shots, "shot 1".. by default."""
+    shape = video_shape(path)
+    total = shape["frame_count"]
+    for boundary in boundaries:
+        if not 1 <= int(boundary) <= total - 1:
+            raise ValueError(
+                f"boundary {boundary} is not inside the clip (1..{total - 1})"
+            )
+    boundaries = [int(b) for b in boundaries]
+    names = list(names or [f"shot {n + 1}" for n in range(len(boundaries) + 1)])
+    if len(names) != len(boundaries) + 1:
+        raise ValueError(
+            f"{len(boundaries)} boundaries make {len(boundaries) + 1} shots, "
+            f"but {len(names)} names were given"
+        )
+    wanted = sorted({b - 1 for b in boundaries} | set(boundaries))
+    images = _read_frames(path, wanted)
+    tiles = []
+    for seam, boundary in enumerate(boundaries):
+        before = _fit_width(images[boundary - 1], tile_width)
+        after = _fit_width(images[boundary], tile_width)
+        pair = _compose_grid([before, after], 2)
+        tiles.append(
+            {
+                "label": f"seam {seam + 1}: {names[seam]} | {names[seam + 1]}",
+                "frame": boundary,
+                "seconds": _seconds(boundary, shape),
+                "image": pair,
+            }
+        )
+    return tiles
+
+
+def _moment_to_index(moment, shape):
+    total = shape["frame_count"]
+    if isinstance(moment, str) and moment.startswith("frame:"):
+        index = int(moment[len("frame:") :])
+    else:
+        fps = shape["fps"]
+        if fps is None:
+            raise ValueError("this clip has no frame rate, so name a frame: 'frame:N'")
+        index = int(round(float(moment) * fps))
+    if index < 0:
+        index += total
+    if not 0 <= index < total:
+        raise ValueError(f"{moment!r} is past the end of a {total}-frame clip")
+    return index
+
+
+def _seconds(index, shape):
+    return index / shape["fps"] if shape["fps"] else float(index)
+
+
+def _tile(index, image, shape):
+    fps = shape["fps"]
+    stamp = _format_timestamp(index, fps) if fps else f"#{index}"
+    return {
+        "label": f"{stamp} (frame {index})",
+        "frame": index,
+        "seconds": _seconds(index, shape),
+        "image": image,
+    }
+
+
+def _fit_width(image, tile_width):
+    height = max(1, round(image.height * tile_width / image.width))
+    return image.resize((tile_width, height), Image.LANCZOS).convert("RGB")
+
+
+def _read_frames(path, indexes):
+    """The frames at these indexes, as {index: PIL image}, in one forward
+    pass that seeks to the keyframe before each wanted frame rather than
+    decoding from the top. Decodes are dropped as soon as they are past."""
+    wanted = sorted(set(int(i) for i in indexes))
+    found = {}
+    with av.open(path) as container:
+        stream = container.streams.video[0]
+        fps = float(stream.average_rate) if stream.average_rate else None
+        position = 0  # index of the next frame decode() will yield
+        for target in wanted:
+            if target < position or target - position > 2 * (int(fps) if fps else 24):
+                # seek back or a long way forward: land on the keyframe at
+                # or before the target, then read up to it
+                seconds = target / fps if fps else 0.0
+                container.seek(
+                    int(seconds / stream.time_base), stream=stream, backward=True
+                )
+                position = None
+            for frame in container.decode(stream):
+                if position is None:
+                    # first frame after a seek says where we landed
+                    position = (
+                        int(round(float(frame.pts * stream.time_base) * fps))
+                        if fps and frame.pts is not None
+                        else 0
+                    )
+                if position == target:
+                    found[target] = frame.to_image()
+                    position += 1
+                    break
+                position += 1
+        missing = [i for i in wanted if i not in found]
+        if missing:
+            raise ValueError(f"could not decode frame(s) {missing} of {path}")
+    return found
+```
+
+The seek-then-count logic assumes constant frame rate, which every file this engine writes has (`encode_video` / `export_to_video` write a fixed `fps`). If the ramp test's returned greys are off by one frame, the keyframe landing computed `position` wrong - fall back to `position = 0` and `container.seek(0)` for that file (correct, slower) rather than loosen the test.
+
+- [ ] **Step 4: Run the tests until they pass**
+
+Run: `venv/bin/python -m pytest tests/test_media_frames.py -v`
+Expected: PASS (6 tests).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add dw/media_frames.py tests/test_media_frames.py
+git commit -m "feat(server): #193 - media_frames seeks out moments, a contact sheet and seam pairs"
+```
+
+---
+
+### Task 5: `GET /api/gallery/{name}/frames` - the frames route
+
+**Files:**
+- Modify: `dw/server/app.py` (after `gallery_audio` from Task 2; import beside `extract_audio`)
+- Test: `tests/test_server.py`
+
+**Interfaces:**
+- Consumes: Task 4's `frames_at`, `contact_sheet`, `seam_tiles`, `video_shape`.
+- Produces: the route. Query: exactly one of `at` (repeatable: `?at=1.5&at=frame:12`), `count` (int), `seams` (`true` or a comma list of 1-based seam numbers); `boundaries` (comma list of frame indexes - required with `seams` in this stage; stage 2 fills it from the manifest when absent); `names` (comma list); `max_dimension` (int, default 512, the longest side of each returned tile). Answer:
+
+```json
+{"name": "...", "frame_count": 120, "fps": 24.0, "width": 960, "height": 544,
+ "tiles": [{"label": "00:02.0 (frame 48)", "frame": 48, "seconds": 2.0,
+            "data": "<base64 png>", "mime_type": "image/png", "width": 512, "height": 290}]}
+```
+
+400 when zero or more than one selector is given, when `seams` has no `boundaries`, or when a moment/boundary is out of range; 404 when the file is not a video.
+
+- [ ] **Step 1: Write the failing tests**
+
+```python
+# tests/test_server.py - add after the gallery_audio tests
+
+def _png_of(tile):
+    import base64
+    import io
+    from PIL import Image
+
+    return Image.open(io.BytesIO(base64.b64decode(tile["data"])))
+
+
+def test_gallery_frames_returns_the_moments_asked_for(server, tmp_path):
+    """No tool returned a frame of a video, so judging a clip meant handing
+    the user the file (#193, #245). The route seeks out the moments named."""
+    from tests.test_media_frames import write_ramp_mp4
+
+    with server(success_script) as client:
+        outputs = tmp_path / "outputs"
+        write_ramp_mp4(outputs / "shot-gen.0-0.0.mp4", frames=24, fps=6, width=64, height=32)
+
+        response = client.get(
+            "/api/gallery/shot-gen.0-0.0.mp4/frames",
+            params=[("at", "0.0"), ("at", "frame:12"), ("max_dimension", "32")],
+        )
+
+        assert response.status_code == 200
+        body = response.json()
+        assert body["frame_count"] == 24 and body["fps"] == 6.0
+        assert [t["frame"] for t in body["tiles"]] == [0, 12]
+        assert body["tiles"][0]["mime_type"] == "image/png"
+        assert body["tiles"][0]["width"] == 32  # downscaled to max_dimension
+        assert _png_of(body["tiles"][0]).size == (32, 16)
+
+
+def test_gallery_frames_makes_a_contact_sheet(server, tmp_path):
+    from tests.test_media_frames import write_ramp_mp4
+
+    with server(success_script) as client:
+        outputs = tmp_path / "outputs"
+        write_ramp_mp4(outputs / "shot-gen.0-0.0.mp4", frames=24, fps=6)
+
+        response = client.get(
+            "/api/gallery/shot-gen.0-0.0.mp4/frames", params={"count": 4}
+        )
+
+        assert response.status_code == 200
+        tiles = response.json()["tiles"]
+        assert len(tiles) == 1
+        assert tiles[0]["label"] == "contact sheet, 4 frames"
+        assert tiles[0]["frames"] == [0, 7, 15, 23]
+
+
+def test_gallery_frames_pairs_the_frames_at_each_seam(server, tmp_path):
+    from tests.test_media_frames import write_ramp_mp4
+
+    with server(success_script) as client:
+        outputs = tmp_path / "outputs"
+        write_ramp_mp4(outputs / "cut-gen.0-0.0.mp4", frames=24, fps=6)
+
+        response = client.get(
+            "/api/gallery/cut-gen.0-0.0.mp4/frames",
+            params={"seams": "true", "boundaries": "8,16", "names": "a,b,c"},
+        )
+
+        assert response.status_code == 200
+        tiles = response.json()["tiles"]
+        assert [t["label"] for t in tiles] == ["seam 1: a | b", "seam 2: b | c"]
+
+        second = client.get(
+            "/api/gallery/cut-gen.0-0.0.mp4/frames",
+            params={"seams": "2", "boundaries": "8,16"},
+        )
+        assert [t["label"] for t in second.json()["tiles"]] == ["seam 2: shot 2 | shot 3"]
+
+
+def test_gallery_frames_refuses_bad_selectors(server, tmp_path):
+    from tests.test_media_frames import write_ramp_mp4
+    from tests.test_media_info import write_wav
+
+    with server(success_script) as client:
+        outputs = tmp_path / "outputs"
+        write_ramp_mp4(outputs / "shot-gen.0-0.0.mp4", frames=6, fps=6)
+        write_wav(outputs / "score-gen.0-0.0.wav")
+
+        none = client.get("/api/gallery/shot-gen.0-0.0.mp4/frames")
+        assert none.status_code == 400 and "one of" in none.json()["detail"]
+
+        two = client.get(
+            "/api/gallery/shot-gen.0-0.0.mp4/frames", params={"count": 2, "at": "0"}
+        )
+        assert two.status_code == 400
+
+        no_boundaries = client.get(
+            "/api/gallery/shot-gen.0-0.0.mp4/frames", params={"seams": "true"}
+        )
+        assert no_boundaries.status_code == 400
+        assert "boundaries" in no_boundaries.json()["detail"]
+
+        past = client.get(
+            "/api/gallery/shot-gen.0-0.0.mp4/frames", params={"at": "9.0"}
+        )
+        assert past.status_code == 400 and "past the end" in past.json()["detail"]
+
+        audio = client.get("/api/gallery/score-gen.0-0.0.wav/frames", params={"count": 1})
+        assert audio.status_code == 404
+
+
+def test_gallery_frames_reads_an_asset_reference(asset_server, tmp_path):
+    from tests.test_media_frames import write_ramp_mp4
+
+    with asset_server(success_script) as client:
+        write_ramp_mp4(tmp_path / "assets" / "ref.mp4", frames=6, fps=6)
+
+        response = client.get("/api/gallery/asset:ref.mp4/frames", params={"count": 2})
+
+        assert response.status_code == 200
+        assert response.json()["tiles"][0]["frames"] == [0, 5]
+```
+
+(Use the same `asset_server` setup as the Task 2 asset test.)
+
+- [ ] **Step 2: Run the tests to verify they fail**
+
+Run: `venv/bin/python -m pytest tests/test_server.py -k gallery_frames -v`
+Expected: FAIL with 404 Not Found from FastAPI.
+
+- [ ] **Step 3: Add the route**
+
+Import beside `extract_audio`:
+
+```python
+from ..media_frames import contact_sheet, frames_at, seam_tiles, video_shape
+```
+
+Add after `gallery_audio`:
+
+```python
+    FRAME_MIN_DIMENSION = 64
+
+    @app.get("/api/gallery/{name:path}/frames")
+    def gallery_frames(
+        name: str,
+        at: Optional[List[str]] = Query(None),
+        count: Optional[int] = None,
+        seams: Optional[str] = None,
+        boundaries: Optional[str] = None,
+        names: Optional[str] = None,
+        max_dimension: int = 512,
+        ws: Workspace = Depends(selected_workspace),
+    ):
+        """Frames of a video output or asset, as PNG tiles - the way an
+        agent with no video content type sees what a run made (#193).
+        Exactly one selector: `at` (repeatable; seconds, or "frame:N"),
+        `count` (an evenly spaced contact sheet, `frame_grid` without a
+        workflow), or `seams` ("true", or a comma list of 1-based seam
+        numbers) for the last frame before and first frame after each
+        boundary, side by side. `boundaries` is the comma list of frame
+        indexes each shot after the first starts at, and `names` the
+        shots' names; both are required with `seams` until a joined file
+        carries its own (stage 2 of docs/proposals/output-assessment.md).
+        Tiles are downscaled to `max_dimension` on their longest side."""
+        if is_asset_reference(name):
+            path = _asset_file(name, ws)
+        else:
+            path = _output_file(name, ws.outputs)
+        if MEDIA_KINDS.get(os.path.splitext(path)[1].lower()) != "video":
+            raise HTTPException(status_code=404, detail=f"{name} is not a video")
+
+        chosen = [key for key, value in (("at", at), ("count", count), ("seams", seams)) if value]
+        if len(chosen) != 1:
+            raise HTTPException(
+                status_code=400,
+                detail="Pass exactly one of `at`, `count` or `seams`"
+                + (f" - got {', '.join(chosen)}" if chosen else ""),
+            )
+        limit = max(FRAME_MIN_DIMENSION, int(max_dimension))
+
+        try:
+            if at:
+                moments = [m if m.startswith("frame:") else float(m) for m in at]
+                tiles = frames_at(path, moments)
+            elif count:
+                tiles = [contact_sheet(path, count, tile_width=limit)]
+            else:
+                if not boundaries:
+                    raise HTTPException(
+                        status_code=400,
+                        detail="`seams` needs `boundaries`: the frame index each "
+                        "shot after the first starts at, comma-separated - this "
+                        "file carries none of its own",
+                    )
+                starts = [int(b) for b in boundaries.split(",") if b.strip()]
+                shot_names = [n.strip() for n in names.split(",")] if names else None
+                tiles = seam_tiles(path, starts, names=shot_names, tile_width=limit)
+                if seams.lower() != "true":
+                    wanted = {int(s) for s in seams.split(",") if s.strip()}
+                    tiles = [t for i, t in enumerate(tiles, start=1) if i in wanted]
+        except ValueError as e:
+            raise HTTPException(status_code=400, detail=str(e))
+
+        shape = video_shape(path)
+        return {
+            "name": name,
+            **shape,
+            "tiles": [_encoded_tile(tile, limit) for tile in tiles],
+        }
+
+    def _encoded_tile(tile, limit):
+        image = tile["image"]
+        longest = max(image.width, image.height)
+        if longest > limit:
+            scale = limit / longest
+            image = image.resize(
+                (max(1, round(image.width * scale)), max(1, round(image.height * scale)))
+            )
+        buffer = io.BytesIO()
+        image.save(buffer, format="PNG")
+        encoded = {
+            key: value for key, value in tile.items() if key != "image"
+        }
+        encoded.update(
+            {
+                "data": base64.b64encode(buffer.getvalue()).decode("ascii"),
+                "mime_type": "image/png",
+                "width": image.width,
+                "height": image.height,
+            }
+        )
+        return encoded
+```
+
+Add `import base64` to the stdlib imports if absent. The `contact_sheet` and `seam_tiles` tile widths are per sub-tile; the composed grid can exceed `limit` on its longest side, so `_encoded_tile` fits the *composite* to `limit` - that is the behaviour the `max_dimension` test asserts.
+
+- [ ] **Step 4: Run the tests until they pass**
+
+Run: `venv/bin/python -m pytest tests/test_server.py -k "gallery_frames or gallery_audio" -v`
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add dw/server/app.py tests/test_server.py
+git commit -m "feat(server): #193 - GET /api/gallery/{name}/frames returns moments, a contact sheet or seam pairs"
+```
+
+---
+
+### Task 6: `get_output_frames` MCP tool
+
+**Files:**
+- Modify: `dw_mcp/media.py` (new handler + a budget helper)
+- Modify: `dw_mcp/server.py` (tool after `get_output_audio`; `get_output_image` docstring; the instructions block ~line 116 and ~143)
+- Modify: `tests/test_mcp_server.py` (`EXPECTED_TOOLS`, `TOOL_WIRING`, `WRAPPER_HANDLER_MAP`), `tests/test_mcp_media.py`
+- Modify: `docs/MCP.md` (tool count, table row, the numbered loop ~line 376)
+
+**Interfaces:**
+- Consumes: Task 5's route and JSON shape; `_encode_within_budget` / `MAX_RETURNED_BYTES` in `dw_mcp/media.py`.
+- Produces: `media.get_output_frames(client, name, at=None, seams=None, count=None, boundaries=None, names=None, max_dimension=512, workspace=None) -> {name, frame_count, fps, tiles: [{label, frame, seconds, data, mime_type, width, height}], downscaled_to: int | None}`; the MCP tool returns `[ImageContent, ..., TextContent]`.
+
+- [ ] **Step 1: Write the failing tests**
+
+```python
+# tests/test_mcp_media.py - add
+
+from dw_mcp.media import get_output_frames
+
+
+def tile_json(width, height, label="00:00.0 (frame 0)", frame=0, seconds=0.0):
+    return {
+        "label": label,
+        "frame": frame,
+        "seconds": seconds,
+        "data": base64.b64encode(png_bytes(width, height)).decode("ascii"),
+        "mime_type": "image/png",
+        "width": width,
+        "height": height,
+    }
+
+
+def frames_server(tiles, seen=None):
+    def handler(request):
+        if seen is not None:
+            seen.append((request.url.path, list(request.url.params.multi_items())))
+        return httpx.Response(
+            200, json={"name": "x.mp4", "frame_count": 24, "fps": 6.0, "width": 64, "height": 32, "tiles": tiles}
+        )
+
+    return DwClient(transport=httpx.MockTransport(handler))
+
+
+def test_frames_are_asked_for_by_moment_and_come_back_labelled():
+    seen = []
+    client = frames_server([tile_json(64, 32), tile_json(64, 32, "00:02.0 (frame 12)", 12, 2.0)], seen)
+
+    result = get_output_frames(client, "run/x.mp4", at=[0.0, "frame:12"])
+
+    assert seen[0][0] == "/api/gallery/run%2Fx.mp4/frames"
+    assert ("at", "0.0") in seen[0][1] and ("at", "frame:12") in seen[0][1]
+    assert [t["label"] for t in result["tiles"]] == ["00:00.0 (frame 0)", "00:02.0 (frame 12)"]
+    assert result["downscaled_to"] is None
+
+
+def test_seams_send_boundaries_and_names():
+    seen = []
+    client = frames_server([tile_json(128, 32, "seam 1: a | b", 8, 1.33)], seen)
+
+    get_output_frames(client, "cut.mp4", seams=[1], boundaries=[8, 16], names=["a", "b", "c"])
+
+    params = dict(seen[0][1])
+    assert params["seams"] == "1"
+    assert params["boundaries"] == "8,16"
+    assert params["names"] == "a,b,c"
+
+
+def test_two_selectors_are_refused_before_any_request():
+    client = frames_server([])
+
+    with pytest.raises(DwApiError, match="one of"):
+        get_output_frames(client, "x.mp4", at=[0.0], count=4)
+
+
+def test_tiles_over_budget_are_shrunk_together_and_say_so():
+    # three noisy 2048x1024 tiles: well over 4MB base64 between them
+    tiles = []
+    for n in range(3):
+        tiles.append(
+            {
+                **tile_json(2048, 1024, frame=n, seconds=float(n)),
+                "data": base64.b64encode(noise_png_bytes(2048, 1024, seed=n)).decode("ascii"),
+            }
+        )
+    client = frames_server(tiles)
+
+    result = get_output_frames(client, "x.mp4", at=[0, 1, 2], max_dimension=2048)
+
+    total = sum(len(t["data"]) for t in result["tiles"])
+    assert total <= MAX_RETURNED_BYTES
+    assert len(result["tiles"]) == 3  # shrunk, not dropped
+    assert result["downscaled_to"] is not None and result["downscaled_to"] < 2048
+    assert all(decoded(t).width == result["tiles"][0]["width"] for t in result["tiles"])
+```
+
+In `tests/test_mcp_server.py`: add `"get_output_frames"` to `EXPECTED_TOOLS`; add the wiring row
+
+```python
+    ("get_output_frames", {"name": "out.mp4", "count": 2}, "GET", "/api/gallery/out.mp4/frames"),
+```
+
+and in `test_each_tool_calls_its_endpoint`'s handler add, before the `/outputs/` branch:
+
+```python
+        if request.url.path.endswith("/frames"):
+            return httpx.Response(
+                200,
+                json={"name": "out.mp4", "frame_count": 2, "fps": 6.0, "width": 1, "height": 1,
+                      "tiles": [{"label": "contact sheet, 2 frames", "frame": 0, "seconds": 0.0,
+                                 "data": base64.b64encode(PNG_1X1).decode("ascii"),
+                                 "mime_type": "image/png", "width": 1, "height": 1}]},
+            )
+```
+
+and `"get_output_frames": (media, "get_output_frames")` to `WRAPPER_HANDLER_MAP`.
+
+- [ ] **Step 2: Run the tests to verify they fail**
+
+Run: `venv/bin/python -m pytest tests/test_mcp_media.py tests/test_mcp_server.py -k "frames or wiring or tool_count" -v`
+Expected: FAIL - `ImportError: cannot import name 'get_output_frames'`, wiring table mismatch, tool count mismatch.
+
+- [ ] **Step 3: Write the handler**
+
+In `dw_mcp/media.py`:
+
+```python
+def get_output_frames(
+    client,
+    name,
+    at=None,
+    seams=None,
+    count=None,
+    boundaries=None,
+    names=None,
+    max_dimension=512,
+    workspace=None,
+):
+    """Frames of a generated video as images - the way to *see* a clip when
+    there is no video content type to return it as (#193, #210). One
+    selector per call: `at` (moments: seconds, or "frame:N"), `count` (an
+    evenly spaced contact sheet) or `seams` (True, or seam numbers from 1:
+    the last frame before and the first frame after each boundary, side by
+    side). `boundaries` is the list of frame indexes each shot after the
+    first starts at, `names` the shots' names - both needed with `seams`
+    until a joined file carries its own.
+
+    Every tile is fitted to `max_dimension`; when the whole answer would
+    still exceed MAX_RETURNED_BYTES the tiles are shrunk *together* - the
+    same dimension for all, halved until they fit - rather than any being
+    dropped, and `downscaled_to` says what they were shrunk to. A seam
+    pair at half size is still a seam pair; a seam pair missing is a
+    different answer."""
+    chosen = [key for key, value in (("at", at), ("count", count), ("seams", seams)) if value]
+    if len(chosen) != 1:
+        raise DwApiError(
+            "Pass exactly one of `at`, `count` or `seams`"
+            + (f" - got {', '.join(chosen)}" if chosen else "")
+        )
+    params = [("max_dimension", str(max(MIN_DIMENSION, int(max_dimension))))]
+    if at:
+        params += [("at", str(moment)) for moment in at]
+    elif count:
+        params.append(("count", str(int(count))))
+    else:
+        params.append(("seams", "true" if seams is True else ",".join(str(s) for s in seams)))
+        if boundaries:
+            params.append(("boundaries", ",".join(str(int(b)) for b in boundaries)))
+        if names:
+            params.append(("names", ",".join(names)))
+
+    body = client.get_json(
+        api_path("api", "gallery", name, "frames"), params=params, workspace=workspace
+    )
+    tiles, downscaled_to = _fit_tiles_within_budget(body.get("tiles", []))
+    return {
+        "name": name,
+        "frame_count": body.get("frame_count"),
+        "fps": body.get("fps"),
+        "tiles": tiles,
+        "downscaled_to": downscaled_to,
+    }
+
+
+def _fit_tiles_within_budget(tiles):
+    """Shrink every tile by the same factor until their base64 sizes sum
+    to MAX_RETURNED_BYTES or less. Returns (tiles, downscaled_to) with
+    downscaled_to None when nothing had to shrink."""
+    total = sum(len(tile["data"]) for tile in tiles)
+    if total <= MAX_RETURNED_BYTES or not tiles:
+        return tiles, None
+    images = [Image.open(io.BytesIO(base64.b64decode(tile["data"]))) for tile in tiles]
+    for image in images:
+        image.load()
+    limit = max(max(image.width, image.height) for image in images)
+    while True:
+        limit = max(MIN_DIMENSION, limit // 2)
+        shrunk = []
+        for tile, image in zip(tiles, images):
+            sized = _fit(image, limit)
+            buffer = io.BytesIO()
+            sized.save(buffer, format="PNG")
+            encoded = base64.b64encode(buffer.getvalue()).decode("ascii")
+            shrunk.append({**tile, "data": encoded, "width": sized.width, "height": sized.height})
+        if sum(len(t["data"]) for t in shrunk) <= MAX_RETURNED_BYTES or limit <= MIN_DIMENSION:
+            return shrunk, limit
+        images = [Image.open(io.BytesIO(base64.b64decode(t["data"]))) for t in shrunk]
+```
+
+Check `client.get_json` accepts `params` (read `dw_mcp/client.py`'s `get_json`); it does for `get_gallery_metadata` (`params={"envelope": "true"}`), and a list of pairs is what httpx wants for a repeated `at` - confirm httpx accepts a list of tuples for `params` (it does).
+
+- [ ] **Step 4: Register the tool**
+
+In `dw_mcp/server.py` after `get_output_audio`:
+
+```python
+    def get_output_frames(
+        name: str,
+        at: list[str | float] | None = None,
+        seams: bool | list[int] | None = None,
+        count: int | None = None,
+        boundaries: list[int] | None = None,
+        names: list[str] | None = None,
+        max_dimension: int = 512,
+        workspace: str | None = None,
+    ) -> list[ImageContent | TextContent]:
+        """See a generated video, named as `list_gallery` or a job's manifest
+        reports it: there is no video content type over MCP, so a clip is
+        looked at as frames (and heard with `get_output_audio`). One
+        selector per call - `count` for an evenly spaced contact sheet of
+        the whole clip (start here: `count=12` shows a clip's shape in one
+        image), `at` for specific moments (seconds, or "frame:N"), or
+        `seams` (true, or seam numbers from 1) for the last frame before
+        and the first frame after each join, side by side - the picture to
+        check a cut or a continuity break against. `seams` needs
+        `boundaries` (the frame index each shot after the first starts at;
+        sum the shots' frame counts from `get_gallery_metadata`) and takes
+        `names` for the shots. Each tile is fitted to `max_dimension`; the
+        text part lists every tile's label, frame and time, and says if the
+        set was shrunk to fit the 4MB budget. What you see here outranks any
+        number `get_gallery_metadata` reports.
+
+        `workspace` names the workspace for this one call without
+        switching the session to it (#99)."""
+        result = media.get_output_frames(
+            client,
+            name,
+            at=at,
+            seams=seams,
+            count=count,
+            boundaries=boundaries,
+            names=names,
+            max_dimension=max_dimension,
+            workspace=workspace,
+        )
+        parts = [
+            ImageContent(type="image", data=tile["data"], mime_type=tile["mime_type"])
+            for tile in result["tiles"]
+        ]
+        lines = [
+            f"name: {result['name']}",
+            f"frame_count: {result['frame_count']}  fps: {result['fps']}",
+        ]
+        for tile in result["tiles"]:
+            lines.append(
+                f"- {tile['label']}  [{tile['width']}x{tile['height']}]"
+            )
+        if result["downscaled_to"]:
+            lines.append(
+                f"downscaled_to: {result['downscaled_to']} (every tile, to fit the inline budget)"
+            )
+        parts.append(TextContent(type="text", text="\n".join(lines)))
+        return parts
+```
+
+Register it wherever the file lists tools for `mcp.tool()` (find how `get_output_audio` is registered - `grep -n "get_output_audio" dw_mcp/server.py` - and mirror it exactly).
+
+Then edit `get_output_image`'s docstring: replace "Images only: audio is `get_output_audio`'s and video is refused, so inspect a video with `get_gallery_metadata` or hand the user the file." with "Images only: a soundtrack is `get_output_audio`'s and a video's frames are `get_output_frames`'s."
+
+In the instructions block (~line 116) change "`get_output_image` to actually look at what was made and say whether it answers the request." to "`get_output_image` (a still), `get_output_frames` (a video, as a contact sheet or the frames either side of each seam) and `get_output_audio` (a soundtrack, or an excerpt of one) to actually look at and listen to what was made and say whether it answers the request."
+
+- [ ] **Step 5: Update `docs/MCP.md`**
+
+- Line ~190: bump the stated tool count by one (read the current number; `test_the_stated_tool_count_is_the_registered_one` checks it).
+- Add a table row after `get_output_audio`'s:
+
+```
+| `get_output_frames(name, at=None, seams=None, count=None, boundaries=None, names=None, max_dimension=512, workspace=None)` | `name`, `at`, `seams`, `count`, `boundaries`, `names`, `max_dimension`, `workspace` | See a generated video as frames, since there is no video content type over MCP (#193). One selector per call: `count` for an evenly spaced contact sheet, `at` for moments (seconds or `"frame:N"`), `seams` (true, or seam numbers from 1) for the last frame before and first frame after each join side by side - with `boundaries`, the frame index each shot after the first starts at, and `names`. Tiles are fitted to `max_dimension` and, when the set would exceed the 4MB budget, shrunk together rather than dropped; the text part lists each tile and says so |
+```
+
+- Line ~376, the numbered loop: after "5. `get_output_image(name)` to look at a result image" add "6. `get_output_frames(name, count=12)` to look at a result video, and `get_output_audio(name, start, duration)` to hear it" and renumber what follows.
+
+- [ ] **Step 6: Run the whole MCP and docs suites**
+
+Run: `venv/bin/python -m pytest tests/test_mcp_media.py tests/test_mcp_server.py tests/test_mcp_client.py tests/test_docs_links.py tests/test_server_mcp.py -q`
+Expected: PASS, including `test_the_wiring_table_covers_every_registered_tool`, `test_the_stated_tool_count_is_the_registered_one`, `test_wrapper_handler_map_covers_every_defaulted_handler`, and `TestNoEngineImport` (the `dw_mcp` no-`dw` import guard - `media.py` uses PIL only).
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add dw_mcp/media.py dw_mcp/server.py docs/MCP.md tests/test_mcp_media.py tests/test_mcp_server.py
+git commit -m "feat(mcp): #193 - get_output_frames, a video seen as moments, a contact sheet or seam pairs"
+```
+
+---
+
+### Task 7: Full suite, the mounted MCP surface, and the hand-off
+
+**Files:**
+- Modify: `CLAUDE.md` (the `MCP Server` paragraph is one line pointing at `dw_mcp/CLAUDE.md`; no change needed unless the count of "seven tools require acknowledged_cost" sentence there needs one - it does not, nothing here is gated)
+- Modify: `docs/proposals/output-assessment.md` - flip the Status line's "No code changes yet" to "Stage 1 (evidence) landed on `develop` as <sha>".
+
+- [ ] **Step 1: Run the full suite**
+
+Run: `venv/bin/python -m pytest -q -x`
+Expected: PASS. Two places may break that no task above named: (a) `tests/test_server_mcp.py` exercises the *mounted* MCP surface (`dw.serve --mcp`), which registers the same tools - a snapshot of tool names there gains `get_output_frames`; (b) any test asserting `get_output_audio`'s old `/outputs` refusal wording for `video/mp4`. Fix each by updating the expectation to the new behaviour, never by weakening the new code.
+
+- [ ] **Step 2: Try it against a real file**
+
+```bash
+venv/bin/python -m dw.serve &   # from a checkout with an outputs/ holding one mp4
+# in another shell, with the MCP server pointed at it:
+#   get_output_frames(name="<some>.mp4", count=8)
+#   get_output_audio(name="<some>.mp4", start=0, duration=2)
+```
+
+Confirm the frames arrive as images in the client and the audio part plays. Note the response time on a 300-frame clip; `frames_at` with three moments should be well under a second.
+
+- [ ] **Step 3: Finish the branch**
+
+Use the `superpowers:finishing-a-development-branch` skill: merge `feat/193-evidence` into `develop` with a merge commit (the repo's pattern is `Merge branch 'fix/...' into develop`), do not push or deploy without asking - lem deploys are a separate, explicit step in this repo (see memory: lem restart recipe).
+
+- [ ] **Step 4: Note the release items**
+
+Append to whatever release-note draft is open (or open `docs/RELEASING.md`'s "unreleased" section if it has one): `get_output_audio` now reads `GET /api/gallery/{name}/audio`, extracts a video's soundtrack, and takes `start`/`duration`; new tool `get_output_frames`; new routes `/api/gallery/{name}/audio` and `/frames`.
+
+---
+
+## Self-review
+
+**Spec coverage (sections 2 and 5 only - this is stage 1):**
+- `get_output_frames` with `at` / `seams` / `count`, same budget path, halve-before-drop, says which - Tasks 4, 5, 6. ✔
+- `get_output_audio` mux-aware, moves to the gallery route, `start`/`duration`, `excerpt: {start, duration, of}`, whole-file refusal kept, audio-only file served as-is - Tasks 1, 2, 3. ✔
+- Routes accept `asset:` and `workspace`; paths through `_output_file`/`_asset_file` - Tasks 2, 5. ✔
+- Runs in the server process as a sync `def` - Tasks 2, 5. ✔
+- `media.shots` in metadata, and `seams` reading boundaries from the manifest/file - **stage 2, deliberately not here**; the route and tool take `boundaries` explicitly and their docstrings say why.
+- Tool descriptions and the instructions block name the new tools; `dw_mcp/CLAUDE.md` and `docs/MCP.md` updated - Tasks 3, 6. ✔
+- `minimax-h3` step 4 rewrite - **stage 4**, per the spec's staging.
+
+**Placeholder scan:** none - every step has its code or its exact edit.
+
+**Type consistency:** `extract_audio -> (bytes, dict)` used by Task 2 as `data, info`; header names `X-DW-Duration` / `X-DW-Excerpt-Start` / `X-DW-Excerpt-Duration` match between Task 2 (set) and Task 3 (read, lower-cased by httpx); `get_media_if` returns a 3-tuple in Task 3 and `get_bytes_if` keeps its 2-tuple for `get_output_image`/`get_output_text`; `Tile` dict keys `label/frame/seconds/image` in Task 4 become `label/frame/seconds/data/mime_type/width/height` in Task 5 (`_encoded_tile` strips `image`, keeps `frames` on a contact sheet), and Task 6 reads exactly those; `boundaries` is a frame-index list everywhere.

From 7fbe64dd9a574562f550d1fa0be51c8ef087861f Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sun, 20 Sep 2026 09:34:09 -0500
Subject: [PATCH 76/77] feat: onboard Qwen-Image-2.1 flagship text-to-image
 template (#256)

Audits the day-zero Qwen/Qwen-Image-2.1 release against its vendor README,
license and the installed diffusers pipeline, then ships one flagship
text-to-image template: QwenImage21Pipeline under model offload, bf16, 40
steps, explicit 2048x2048 (the pipeline otherwise falls back to a 1024
output_resolution default), no guidance_scale (the pipeline has none), and
width/height bound to the 32-pixel floor grid via variable_constraints with
no snap. The description flags the non-commercial Qwen Research License,
plus VRAM-at-2K, cost and the transformers>=5.17 vendor ask as unverified
pending a GPU run. No composition skill: editing is an argument to this one
pipeline rather than a separate checkpoint, so there is no shape to pick
between.

The existing qwen-image-wan-onboarding draft covers a different, older,
Apache-2.0 20B Qwen-Image line and is annotated to avoid confusion with this
one; the two coexist under different licenses.

Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
---
 .../agent-catalog-legibility-complete.md      |   2 +-
 .../audits/2026-09-20-qwen-image-2.1-audit.md | 290 ++++++++++++++++++
 docs/proposals/qwen-image-wan-onboarding.md   |   8 +
 workflows/models/qwen-image-2.1.json          |  51 +++
 4 files changed, 350 insertions(+), 1 deletion(-)
 create mode 100644 docs/proposals/audits/2026-09-20-qwen-image-2.1-audit.md
 create mode 100644 workflows/models/qwen-image-2.1.json

diff --git a/docs/proposals/agent-catalog-legibility-complete.md b/docs/proposals/agent-catalog-legibility-complete.md
index d9512afe..9843d81b 100644
--- a/docs/proposals/agent-catalog-legibility-complete.md
+++ b/docs/proposals/agent-catalog-legibility-complete.md
@@ -517,7 +517,7 @@ starts from the record rather than the intent. Updated as work lands.
 | 9 composition rules | done (plan 2, task 6) | spec §2.3 | the cartesian rule and the one-step-per-pair form are stated in the authoring section, the general case of `scripted-dialogue-and-tts-complete.md`'s reasoning |
 | 10 save-time metadata | done (task 6) | spec §1.6 | derived and returned on save; empty summary warns, never rejects |
 | Part 3 constraint | carried | spec "Principle" | derivation reads structure, never model family |
-| Part 4 packaging | done: Channel A for the generic item (2026-09-07), Channel B for model families (2026-09-08) | `WORKFLOW_GUIDE.md` authoring section; `plugins/dw/`, `.claude-plugin/marketplace.json`, `.claude/skills/model-family-onboarding` | the spoon-set drill (cold session, PR #48 merged) planned a shared seed for "identical but for colour", which draws a different object per prompt; `### Keeping a set consistent` now says which of style, object or character consistency wants prompts, an edit pass or a reference, and `templates/consistent-set.json` (declared `image-set`: derivation says `image-edit`) is the generate-then-edit shape on FLUX.1 Kontext, whose one pipeline both draws and edits; measured on lem 2026-09-07 at 11.5 warm minutes (2.2 for the base, 3.1 per edit, sequential offload) and the four mugs came out identical but for colour. A FLUX.2 draft found that the HF remote text encoder every FLUX.2 entry names now answers with an HTML page (broken on lem since 2026-08-26); `remote.py` now says so instead of raising an unpickling error, and both FLUX.2 entries load the repo's own 4-bit text encoder under model offload instead. The FLUX.2 text encoder is declared as its own component pinned to the CPU, because BitsAndBytes materializes on the accelerator and the two 4-bit models do not fit at load; the `flash_hub` backend went too, since it needs the `kernels` package no install has. models/flux2-dev measured at 3.3 warm minutes on lem. The Krea edit template moved to FLUX.1 Kontext for the same reason, and a catalog test now refuses `trust_remote_code` and `custom_pipeline` in any bundled entry or packaged builtin, so nothing dw ships asks an operator to lower `--trust-workflows`. The Florence-2 and Phi-3.5 builtins went with it: the `text_generation` task had replaced both, and `describe-and-regenerate` now composes it twice. `### Remote code is refused by default` came out of the same run: the first draft used the Krea edit template's `custom_pipeline`, which a server without `--trust-workflows` refuses at load. Superseded by plugin tasks 1-5 below: `templates/minimax/README.md` and `ltx2/README.md` are the sources the family skills derive from and link back to, so that knowledge is reached through the plugin rather than a third channel. Catalog repair task 1: the latent handoff a two-stage flow needs is proven by test (tests/test_result.py::TestLatentHandoff), no engine change. Catalog repair task 2: two-stage.json is the three-move flow (8 sigmas at 768x448, 2x latent upsample, renoise + 3 stage-two sigmas at 1536x896, audio latents carried); latents pass by name; a test holds noise_scale to STAGE_2_DISTILLED_SIGMA_VALUES[0]. Cost and the sharpness comparison await the lem run (task 7). Catalog repair task 3: the six prompts/ltx2 captions are rewritten to the trained format (one paragraph, 150-220 words, shot type/camera motion/viewpoint in prose, sound interleaved; the two I2V ones describe only what changes), intended_model ltx-2.5, four summaries say LTX-2.5; tests/test_ltx_prompt_library.py holds the shape. Catalog repair task 4: h3_context_ir names its two source guides, writes N/A for silent audio fields, numbers <Video N>/<Audio N> within their category, labels continuity modes as this engine's chaining convention (nothing in the engine emits the phrase; it is a user-message convention), adds the ref guide's dialogue-fidelity rules, drops the two unsourced lines; tests/test_h3_context_ir.py. Catalog repair task 5: both template READMEs link the files that exist, name the vendor sources and the audit, the H3 one states the canvas rules and the 5-second diffusers floor; a test resolves every README link. Lem found templates/minimax/enhance-prompt failing on master already: both enhance templates passed a stored copy of the Context-IR system prompt (prompts/prompt_enhancement/minimax_h3.json, 10096 chars) as a sub-workflow argument, which exceeded MAX_VARIABLE_VALUE_LENGTH 10000; the limit is now 20000, the stored copy is gone, and the templates run the builtin's own prompt, with a test refusing a future override. Three wordings of the N/A rule were drafted before the final review found the templates were running the stored copy, so none of them had been tested; the third, which puts the rule on each audio field's own line, is what shipped.  Catalog repair task 7, verified on lem 2026-09-08: two-stage runs at 1536x896, 8.2 warm minutes (base 1.7, refine 2.7, writing the full-size clip 3.5), latents handed by name and the refine pass served from the pipeline cache; at seed 42 the refined frame is sharp where the upsample-only frame is a soft blur. The fox and hummingbird captions ran as written (tracking shot and pull-out; hold and close-up), the hummingbird soundtrack near-silent. The silent-candle brief's three runs went through the stale stored prompt (final review), so the N/A rule's effect on the Qwen3-4B enhancer is re-verified below. Re-verified 2026-09-08 with the templates on the builtin's prompt: the framed idea the template documents (Task, Duration, Idea) gives a full integrated_multimodal_description with both audio fields N/A; a bare idea first collapsed to the two N/A lines alone, so the description field is now declared unconditional and a bare idea also gets its description (jobs 28f1d29a5b90, be94ed994ecd). The N/A rule took four wordings in all, and only the last two were ever tested. Two engine findings on the way: the step cache keys on the resolved step definition, which names a builtin by path, so editing a builtin does not invalidate a cached step (follow-up); and a cancelled H3 job runs to its next step boundary, minutes on this model. Plugin task 1: a marketplace at the repo root and the dw plugin under plugins/dw, installable with two commands the README shows; plugin.json's version is the engine's, bumped by release.sh and held by test. Plugin task 2: the minimax-h3 skill - shape decision over the family's templates, the frame and canvas rules pinned by test to the diffusers modular pipeline, prompts deferred to MiniMax's h3-prompt-writing skill and the two guides, the run-and-judge loop; the README points at it. Plugin task 3: the ltx-2.5 skill - shape decision, the schedule and size rules pinned to the LTX-2 pipeline, the trained caption spec quoted and held equal to the diffusers constant by test; the README points at it. Final review of the plugin branch: the H3 skill's LoRA coupling scoped to the text- and frame-conditioned templates (the six reference ones run no LoRA at 20 steps), both judge steps rewritten because no MCP tool shows a video frame (the agent hands over the gallery url and checks metadata), the fps rule marked as the DFR path's, tighter numeric pins. Plugin task 4: cold drill 2026-09-08 - pass; the skill fired on the bare prompt, chose templates/minimax/storyboard, wrote a Ref2VA Context-IR prompt, quoted cost and asked before an 11.6-minute run, and inspected the result, where the control ran unasked and could not download the file; the drill caught the skill overstating 20 steps for four LoRA-bearing reference templates (fixed, pinned) and gave storyboard its measured cost (10.1 warm minutes); the mould for the next family is copy a skill, follow its six sections, add the family's rules to tests/test_plugin_skills.py, cite the vendor, and run this drill (.claude/skills/model-family-onboarding). Plugin task 5 (2026-09-08, the 30-second follow-up to the drill): the H3 skill states that nothing carries between generations except a reference, gives the chain-or-cut rule, and says how a cuts piece gets one score and one voice; seven bundled prompts wrote a silent music field as None. and now write N/A, held by test. MiniMax Music 3 went through the lifecycle the same night: audited (docs/proposals/audits/2026-09-08-minimax-music3-audit.md; the ceiling rule and the 44.1 kHz result were confirmed against three primary sources, four small corrections landed: music.json's stale trim-task path, music-video's 21-second ceiling over 20.7 seconds of slices, the README's invented guillotine mechanism, and a text_encoder component the quantization docs showed that Music3 does not have), and plugins/dw/skills/minimax-music3/SKILL.md written with its caps, window, guider and output rate pinned to the diffusers modular pipeline and the caption format deferred to MiniMax's music-caption-rewriter skill, which the repo had never mentioned. Its cold drill is still to run. |
+| Part 4 packaging | done: Channel A for the generic item (2026-09-07), Channel B for model families (2026-09-08) | `WORKFLOW_GUIDE.md` authoring section; `plugins/dw/`, `.claude-plugin/marketplace.json`, `.claude/skills/model-family-onboarding` | the spoon-set drill (cold session, PR #48 merged) planned a shared seed for "identical but for colour", which draws a different object per prompt; `### Keeping a set consistent` now says which of style, object or character consistency wants prompts, an edit pass or a reference, and `templates/consistent-set.json` (declared `image-set`: derivation says `image-edit`) is the generate-then-edit shape on FLUX.1 Kontext, whose one pipeline both draws and edits; measured on lem 2026-09-07 at 11.5 warm minutes (2.2 for the base, 3.1 per edit, sequential offload) and the four mugs came out identical but for colour. A FLUX.2 draft found that the HF remote text encoder every FLUX.2 entry names now answers with an HTML page (broken on lem since 2026-08-26); `remote.py` now says so instead of raising an unpickling error, and both FLUX.2 entries load the repo's own 4-bit text encoder under model offload instead. The FLUX.2 text encoder is declared as its own component pinned to the CPU, because BitsAndBytes materializes on the accelerator and the two 4-bit models do not fit at load; the `flash_hub` backend went too, since it needs the `kernels` package no install has. models/flux2-dev measured at 3.3 warm minutes on lem. The Krea edit template moved to FLUX.1 Kontext for the same reason, and a catalog test now refuses `trust_remote_code` and `custom_pipeline` in any bundled entry or packaged builtin, so nothing dw ships asks an operator to lower `--trust-workflows`. The Florence-2 and Phi-3.5 builtins went with it: the `text_generation` task had replaced both, and `describe-and-regenerate` now composes it twice. `### Remote code is refused by default` came out of the same run: the first draft used the Krea edit template's `custom_pipeline`, which a server without `--trust-workflows` refuses at load. Superseded by plugin tasks 1-5 below: `templates/minimax/README.md` and `ltx2/README.md` are the sources the family skills derive from and link back to, so that knowledge is reached through the plugin rather than a third channel. Catalog repair task 1: the latent handoff a two-stage flow needs is proven by test (tests/test_result.py::TestLatentHandoff), no engine change. Catalog repair task 2: two-stage.json is the three-move flow (8 sigmas at 768x448, 2x latent upsample, renoise + 3 stage-two sigmas at 1536x896, audio latents carried); latents pass by name; a test holds noise_scale to STAGE_2_DISTILLED_SIGMA_VALUES[0]. Cost and the sharpness comparison await the lem run (task 7). Catalog repair task 3: the six prompts/ltx2 captions are rewritten to the trained format (one paragraph, 150-220 words, shot type/camera motion/viewpoint in prose, sound interleaved; the two I2V ones describe only what changes), intended_model ltx-2.5, four summaries say LTX-2.5; tests/test_ltx_prompt_library.py holds the shape. Catalog repair task 4: h3_context_ir names its two source guides, writes N/A for silent audio fields, numbers <Video N>/<Audio N> within their category, labels continuity modes as this engine's chaining convention (nothing in the engine emits the phrase; it is a user-message convention), adds the ref guide's dialogue-fidelity rules, drops the two unsourced lines; tests/test_h3_context_ir.py. Catalog repair task 5: both template READMEs link the files that exist, name the vendor sources and the audit, the H3 one states the canvas rules and the 5-second diffusers floor; a test resolves every README link. Lem found templates/minimax/enhance-prompt failing on master already: both enhance templates passed a stored copy of the Context-IR system prompt (prompts/prompt_enhancement/minimax_h3.json, 10096 chars) as a sub-workflow argument, which exceeded MAX_VARIABLE_VALUE_LENGTH 10000; the limit is now 20000, the stored copy is gone, and the templates run the builtin's own prompt, with a test refusing a future override. Three wordings of the N/A rule were drafted before the final review found the templates were running the stored copy, so none of them had been tested; the third, which puts the rule on each audio field's own line, is what shipped.  Catalog repair task 7, verified on lem 2026-09-08: two-stage runs at 1536x896, 8.2 warm minutes (base 1.7, refine 2.7, writing the full-size clip 3.5), latents handed by name and the refine pass served from the pipeline cache; at seed 42 the refined frame is sharp where the upsample-only frame is a soft blur. The fox and hummingbird captions ran as written (tracking shot and pull-out; hold and close-up), the hummingbird soundtrack near-silent. The silent-candle brief's three runs went through the stale stored prompt (final review), so the N/A rule's effect on the Qwen3-4B enhancer is re-verified below. Re-verified 2026-09-08 with the templates on the builtin's prompt: the framed idea the template documents (Task, Duration, Idea) gives a full integrated_multimodal_description with both audio fields N/A; a bare idea first collapsed to the two N/A lines alone, so the description field is now declared unconditional and a bare idea also gets its description (jobs 28f1d29a5b90, be94ed994ecd). The N/A rule took four wordings in all, and only the last two were ever tested. Two engine findings on the way: the step cache keys on the resolved step definition, which names a builtin by path, so editing a builtin does not invalidate a cached step (follow-up); and a cancelled H3 job runs to its next step boundary, minutes on this model. Plugin task 1: a marketplace at the repo root and the dw plugin under plugins/dw, installable with two commands the README shows; plugin.json's version is the engine's, bumped by release.sh and held by test. Plugin task 2: the minimax-h3 skill - shape decision over the family's templates, the frame and canvas rules pinned by test to the diffusers modular pipeline, prompts deferred to MiniMax's h3-prompt-writing skill and the two guides, the run-and-judge loop; the README points at it. Plugin task 3: the ltx-2.5 skill - shape decision, the schedule and size rules pinned to the LTX-2 pipeline, the trained caption spec quoted and held equal to the diffusers constant by test; the README points at it. Final review of the plugin branch: the H3 skill's LoRA coupling scoped to the text- and frame-conditioned templates (the six reference ones run no LoRA at 20 steps), both judge steps rewritten because no MCP tool shows a video frame (the agent hands over the gallery url and checks metadata), the fps rule marked as the DFR path's, tighter numeric pins. Plugin task 4: cold drill 2026-09-08 - pass; the skill fired on the bare prompt, chose templates/minimax/storyboard, wrote a Ref2VA Context-IR prompt, quoted cost and asked before an 11.6-minute run, and inspected the result, where the control ran unasked and could not download the file; the drill caught the skill overstating 20 steps for four LoRA-bearing reference templates (fixed, pinned) and gave storyboard its measured cost (10.1 warm minutes); the mould for the next family is copy a skill, follow its six sections, add the family's rules to tests/test_plugin_skills.py, cite the vendor, and run this drill (.claude/skills/model-family-onboarding). Plugin task 5 (2026-09-08, the 30-second follow-up to the drill): the H3 skill states that nothing carries between generations except a reference, gives the chain-or-cut rule, and says how a cuts piece gets one score and one voice; seven bundled prompts wrote a silent music field as None. and now write N/A, held by test. MiniMax Music 3 went through the lifecycle the same night: audited (docs/proposals/audits/2026-09-08-minimax-music3-audit.md; the ceiling rule and the 44.1 kHz result were confirmed against three primary sources, four small corrections landed: music.json's stale trim-task path, music-video's 21-second ceiling over 20.7 seconds of slices, the README's invented guillotine mechanism, and a text_encoder component the quantization docs showed that Music3 does not have), and plugins/dw/skills/minimax-music3/SKILL.md written with its caps, window, guider and output rate pinned to the diffusers modular pipeline and the caption format deferred to MiniMax's music-caption-rewriter skill, which the repo had never mentioned. Its cold drill is still to run. Qwen-Image-2.1 onboarded 2026-09-20, the day of its release: audited (docs/proposals/audits/2026-09-20-qwen-image-2.1-audit.md) against the day-zero vendor README, license and diffusers docs page, superseding the 2026-09-08 draft `qwen-image-wan-onboarding.md`'s assumptions about the older 20B Qwen-Image (that draft's model is a different, larger, Apache-2.0 checkpoint and stays a separate backlog item); `workflows/models/qwen-image-2.1.json` is the one flagship text-to-image template the audit recommended, `QwenImage21Pipeline` under model offload, no `guidance_scale` (the pipeline has none), explicit 2048x2048 (undoing the pipeline's 1024 `output_resolution` fallback), width/height bound to the 32-px floor grid via `variable_constraints` with no `snap`; its description carries the non-commercial license note and flags VRAM-at-2K, `cost` and the `transformers>=5.17` vendor ask as unverified pending a GPU run. No composition skill: editing is an argument to the one pipeline, not a separate checkpoint, so there is no shape to pick between. |
 
 
 ### Cold-session probe, 2026-09-07
diff --git a/docs/proposals/audits/2026-09-20-qwen-image-2.1-audit.md b/docs/proposals/audits/2026-09-20-qwen-image-2.1-audit.md
new file mode 100644
index 00000000..1537d2a8
--- /dev/null
+++ b/docs/proposals/audits/2026-09-20-qwen-image-2.1-audit.md
@@ -0,0 +1,290 @@
+# Qwen-Image-2.1 — onboarding research
+
+Researched 2026-09-20. Greenfield: the catalog has no Qwen entry of any kind.
+The model was released **the same day** this was written (2026.09.20), so every
+number below is vendor-stated or read out of the installed diffusers source —
+none of it is corroborated by a community run yet.
+
+## Sources
+
+| URL | Type | Date | Contributes |
+|---|---|---|---|
+| https://huggingface.co/Qwen/Qwen-Image-2.1 | primary (vendor model card) | repo created 2026-09-14, last modified 2026-09-20 (HF API) | Identity, 7B visual generator / 32 single-stream DiT layers, unified T2I + editing, RGBA, ≤10 reference images, Qwen Research License, aspect-ratio table, 40 steps, 2048×2048 |
+| https://huggingface.co/Qwen/Qwen-Image-2.1/raw/main/README.md | primary (raw card) | 2026-09-20 | **Not gated** — fetched fine. Same content as the HTML card; `pipeline_tag: text-to-image`, tags `diffusers, qwen, image-generation, image-editing, rgba` |
+| https://github.com/QwenLM/Qwen-Image-2.1 + https://raw.githubusercontent.com/QwenLM/Qwen-Image-2.1/main/README.md | primary (vendor repo) | repo created 2026-09-14T04:12Z, pushed 2026-09-20T12:25Z (GitHub API); News entries all dated 2026.09.20 | Full README read verbatim: all code examples, default-parameter table, aspect-ratio dict, RGBA prompt format, `enable_model_cpu_offload()` as the only memory advice, architecture section, prefix-KV-cache note, Day-0 integrations |
+| https://raw.githubusercontent.com/QwenLM/Qwen-Image-2.1/main/prompt_rewrite/README.md | primary | 2026-09-20 | The two PE (prompt-enhancer) checkpoints, Qwen3.5-VL 9B, ~20 GB bf16, 40 GB GPU |
+| https://raw.githubusercontent.com/QwenLM/Qwen-Image-2.1/main/prompt_rewrite/prompts/system_prompt_t2i.txt | primary | 2026-09-20 | **The vendor's actual prompt-writing convention** — English, ~20 sentences / 400–500 words, prescribed section order, "observe don't instruct", no quality boosters |
+| https://huggingface.co/Qwen/Qwen-Image-2.1/raw/main/LICENSE | primary | agreement effective 2026-09-20 | Qwen **Research** License: non-commercial only, "Built with Qwen" attribution, commercial use by separate request |
+| https://huggingface.co/docs/diffusers/main/en/api/pipelines/qwenimage21 | primary (diffusers docs, main) | current as of 2026-09-20 | **This page exists.** Confirms `QwenImage21Pipeline`, "defaults are the values Qwen recommends: 40 steps and no guidance", multi-condition-image block semantics, flex-attention processor guidance |
+| https://huggingface.co/docs/diffusers/main/en/api/pipelines/qwenimage | primary | current | The *old* family's page — lists 8 classes, **does not mention QwenImage21**. Its settings (50 steps, `true_cfg_scale=4.0`, 1024×1024, Lightning 8-step LoRA) belong to Qwen-Image, **not** to 2.1 |
+| Installed diffusers `0.41.0.dev0` at `venv/lib/python3.14/site-packages/diffusers/pipelines/qwenimage21/pipeline_qwenimage21.py` | primary (source) | installed build | Exact `__call__` signature and defaults, prompt templates, `calculate_dimensions` 32-px rounding, `vae_scale_factor = 16`, `model_cpu_offload_seq`, RGBA/alpha handling |
+| HF API `/api/models/Qwen/Qwen-Image-2.1?blobs=true` | primary (derived) | 2026-09-20 | Per-component bf16 weight sizes — the hard VRAM arithmetic below |
+| HF API for `Qwen/Qwen-Image`, `-2512`, `-Edit`, `-Edit-2511`, `-2.1-PE-*` | primary (derived) | 2026-09-20 | Sibling dates, licenses, sizes, download counts |
+| WebSearch "Qwen-Image-2.1 VRAM 24GB GGUF…" (sandner.art, qwen-image-2512.com, dev.to) | secondary | 2025-Q4 / 2026 | **All about Qwen-Image / 2512, not 2.1.** No 2.1-specific community hardware data exists yet |
+| WebSearch "Qwen-Image-2.1 release model card GitHub QwenLM" | secondary | 2026-09-20 | Mostly stale; one aggregator (artrealmai.com) still reported the card as non-public. Ignored |
+| https://qwen.ai/blog?id=qwen-image-2.1 | primary | 2026-09-20 | **Fetch returned only the word "Qwen"** — JS-rendered, no content extractable. Not used |
+| Repo: `docs/proposals/qwen-image-wan-onboarding.md` | internal | draft 2026-09-08 | The assumptions this research supersedes |
+| Repo: `docs/RECIPES_24GB.md` lines 33-37 | internal | — | The only existing Qwen knowledge in the repo, and it is about the 20B model |
+
+`docs/QUANTIZATION.md` and `docs/ACCELERATION.md` contain **no** "qwen" mentions.
+
+## Model identity and scope
+
+- **Repo**: `Qwen/Qwen-Image-2.1`. Weights public, **not gated** (`gated: false`), 33.1 GB total in bf16.
+- **Parameters**: 7B in the visual generator — 32 single-stream DiT layers with block-causal
+  attention (`(q_idx >= kv_idx) or same_image_block`). Plus a **Qwen3-VL 8B** text encoder that
+  also does the vision encoding, and a 64-channel RGBA VAE at 16× spatial compression.
+  Per-file bf16 sizes from the HF API: `text_encoder` 17.53 GB, `transformer` 14.23 GB,
+  `vae` 1.35 GB.
+- **License**: **Qwen Research License Agreement**, effective 2026-09-20 — *non-commercial only*,
+  requires "Built with Qwen" attribution, commercial use needs a separate grant. This is a
+  **hard break from every sibling**, all of which are Apache-2.0. Anything shipped in the catalog
+  should say so in the workflow `description`.
+- **Pipeline class**: `diffusers.QwenImage21Pipeline`, in `diffusers/pipelines/qwenimage21/`.
+  **Already present in the repo's venv** (diffusers `0.41.0.dev0`), imports cleanly, and the
+  diffusers `main` docs page for it exists. **No engine work and no diffusers bump is needed.**
+  One caveat: the vendor asks for `transformers>=5.17`; the venv has **5.16.1**. `Qwen3VLForConditionalGeneration`
+  and `Qwen3VLProcessor` both import successfully on 5.16.1, but this is untested against a real load.
+- **Unified, not split.** One pipeline does text-to-image *and* editing: `image=` (a PIL image or a
+  **list of up to 10**) turns the same call into conditioned generation. There is no separate
+  `QwenImage21EditPipeline`. Components for a dw workflow are `scheduler`, `vae`, `text_encoder`,
+  `processor`, `transformer`.
+- **Native RGBA.** The VAE decodes 4 channels and `VaeImageProcessor.numpy_to_pil` hands back a
+  4-channel `PIL.Image` (`Image.fromarray` on a 4-channel array → mode RGBA), so transparency
+  survives to `Result.save` — but **only if saved as PNG**. `dw/result.py` handles `image/png`;
+  the existing templates all use `image/jpeg`, which would silently flatten the alpha. This is a
+  real template-design constraint.
+
+### Relation to the siblings (all dates from the HF API)
+
+| Repo | Created | License | Tag | bf16 weights | Note |
+|---|---|---|---|---|---|
+| `Qwen/Qwen-Image` | 2025-08-02 | apache-2.0 | text-to-image | 57.7 GB | The 20B model the draft proposal is about |
+| `Qwen/Qwen-Image-Edit` | 2025-08-17 | apache-2.0 | image-to-image | 57.7 GB | Editing sibling of the 20B |
+| `Qwen/Qwen-Image-Edit-2511` | 2025-12-17 | apache-2.0 | image-to-image | 57.7 GB | Most-downloaded of the family (323k) |
+| `Qwen/Qwen-Image-2512` | 2025-12-30 | apache-2.0 | text-to-image | 57.7 GB | Refresh of the 20B, same scale |
+| `Qwen/Qwen-Image-2.1` | 2026-09-14 (public 09-20) | **Qwen Research** | text-to-image (but unified) | **33.1 GB** | This model |
+| `Qwen/Qwen-Image-2.1-PE-T2I` / `-PE-I2I` | 2026-09-20 | other | — | 18.8 GB each | Optional Qwen3.5-VL 9B prompt rewriters |
+
+A "Qwen-Image-2.0" was reported (2026-02-10) by search results; `Qwen/Qwen-Image-2.0` returns an
+API error and I did not verify it. Do not cite it.
+
+**Qwen-Image-2.1 supersedes the older line in practice** — it is a new architecture (single-stream
+DiT, Qwen3-VL encoder, RGBA VAE) at roughly **half** the weight footprint, and it folds
+`Qwen-Image` + `Qwen-Image-Edit` + `Qwen-Image-Edit-Plus` into one checkpoint. But it does **not
+retire** them: the older ones stay Apache-2.0 and keep the large ecosystem (Lightning LoRAs, GGUF
+builds, ControlNets) that 2.1 has none of yet. They coexist, and the licence is the reason a user
+might still want the 20B.
+
+### Where this differs from `docs/proposals/qwen-image-wan-onboarding.md` (draft 2026-09-08)
+
+The draft predates this release by 12 days and is about the **20B Qwen-Image**. Explicitly:
+
+1. **Scale.** Draft: "Qwen-Image (20B)… bf16 doesn't fit; 4-bit BitsAndBytes brings it to ~17GB."
+   2.1 is 7B + an 8B encoder = 33.1 GB bf16 — still doesn't fit 24 GB resident, but model
+   *offloading alone* plausibly suffices; 4-bit may not be needed at all.
+2. **Split vs unified.** Draft: "`QwenImagePipeline` / `QwenImageEditPipeline`… Qwen-Image-Edit is
+   the piece that would carry real shape decisions… the reason a skill might be worthwhile."
+   In 2.1 there is **one** pipeline; editing is an argument, not a checkpoint. The skill question
+   changes shape entirely — see Assessment.
+3. **Guidance.** Draft assumes the FLUX/Z-Image flat `guidance_scale` shape. 2.1 takes **no**
+   `guidance_scale` at all — only `true_cfg_scale`, defaulting to **1.0 (off)**. A template that
+   copies `workflows/templates/text-to-image`'s shape verbatim with a `guidance_scale` argument
+   would raise.
+4. **Text encoder.** Draft: "The Qwen2.5-VL text encoder is large — quantize it or group-offload
+   it (`"text_encoder.model"` with `leaf_level`)" (also in `docs/RECIPES_24GB.md` line 35).
+   2.1 uses **Qwen3-VL 8B**, and that encoder also consumes the condition images, so it cannot
+   simply be swapped for a remote/quantized text-only encoder.
+5. **License.** The draft assumes nothing; 2.1 being research-only is new and material.
+6. **RGBA and ≤10 references** are capabilities the draft does not contemplate at all.
+7. **Resolution.** Draft assumes the 1024-class default. 2.1 is a **native 2K** model.
+
+`docs/RECIPES_24GB.md` lines 33-37 stay correct **for the 20B model** and should not be edited to
+describe 2.1; 2.1 wants its own entry.
+
+## Hardware / quantization fit
+
+**Vendor's own note is thin**: the only memory advice in the entire README is
+`pipe.enable_model_cpu_offload()` "for GPUs with limited memory". No VRAM table, no minimum.
+The diffusers source states no footprints either. So the arithmetic below is mine, from the HF
+blob sizes — reliable for weights, silent about activations.
+
+- **bf16 resident: 33.1 GB. Does not fit 24 GB.** (17.53 + 14.23 + 1.35.)
+- **`offload: "model"` (the vendor's `enable_model_cpu_offload`)**: `model_cpu_offload_seq` is
+  `"text_encoder->transformer->vae"`, so peak weight residency is the largest single component,
+  **17.5 GB** (the text encoder), leaving ~6 GB for activations on a 24 GB card. This is the
+  vendor-endorsed path and is the one a first template should take.
+  **Untested at 2048×2048**: the target latent grid at 2K is 128×128 = 16 384 tokens, plus the
+  Qwen3-VL prefix and (in editing) up to ten condition-image blocks. Attention activations at that
+  sequence length are not something I can size from documentation.
+- **`offload: "sequential"`** would drop peak weight residency much further at a large speed cost —
+  and on MPS the repo downgrades it to `"model"` anyway (`place_component`).
+- **4-bit / GGUF**: **nothing exists yet.** There is no `diffusers/Qwen-Image-2.1-bnb-4bit`
+  analogous to `diffusers/FLUX.2-dev-bnb-4bit`, and no community GGUF. Every GGUF result the
+  search returned is for **Qwen-Image / 2512**, i.e. the 20B — do not carry those claims over.
+  A bnb-4bit `text_encoder` component following `workflows/models/flux2-dev.json`'s pattern
+  would have to be quantized on the fly via `config_objects.py` rather than pulled pre-quantized.
+- FP8 is mentioned only as a vLLM-Omni / SGLang feature, not a diffusers one.
+- AMD ROCm and FlagOS multi-chip are claimed; MPS is not mentioned anywhere by the vendor.
+
+## Recommended inference settings
+
+Vendor defaults (README "Default Parameters" table + diffusers docs, in agreement):
+
+| Setting | Value | Source |
+|---|---|---|
+| `num_inference_steps` | **40** | README table; also the diffusers `__call__` default |
+| `width`/`height` | **2048 × 2048** | README table ("Native 2K resolution") |
+| `true_cfg_scale` | **1.0 — guidance off** | diffusers default; docs: "Qwen-Image 2.1 is meant to be sampled without guidance, hence the default of 1.0" |
+| `guidance_scale` | **does not exist** | `__call__` signature has no such parameter |
+| `negative_prompt` | pointless unless `true_cfg_scale > 1`; the pipeline logs a warning either way if the two disagree | source lines ~669-679 |
+| dtype | `torch.bfloat16` | every vendor example |
+| scheduler | `FlowMatchEulerDiscreteScheduler` with dynamic shift (`mu` from `calculate_shift`, base_shift 0.5 / max_shift 1.15) | source + architecture section |
+| `use_kv_cache` | `True` (prefix KV reuse; big win for multi-reference editing) | source; note it changes the *sample*, not just the speed — "Fix a sample by fixing this flag" |
+| `output_resolution` | diffusers default **1024** | source — **conflicts with the card's 2048 in effect**: omit width/height and you get a 1024 image, not the recommended 2K |
+
+**Note that conflict.** The diffusers `output_resolution` default of 1024 means a template that
+does not pass `width`/`height` silently renders at half the vendor-recommended resolution. A
+template should set them explicitly.
+
+**Aspect ratios** (README dict; all values are multiples of 32, which is what the pipeline enforces
+via `multiple_of = vae_scale_factor * 2 = 32`, floor-rounding anything off-grid):
+
+```
+1:1 (2048,2048)  4:3 (2400,1792)  3:4 (1792,2400)  3:2 (2528,1696)
+2:3 (1696,2528)  16:9 (2752,1536) 9:16 (1536,2752)
+```
+
+This is a **32-pixel grid constraint**, analogous to H3's `17n+5` and LTX's `8k+1`, and it
+**floors** rather than raising — so it belongs in `variable_constraints` **without** `snap`,
+exactly as the LTX-2.5 templates do (`dw/variable_constraints.py`).
+
+**Transparent output** — the vendor's literal prompt wrapper:
+
+> `This is an RGBA image with transparency. <your description>. The image has alpha channel and the background is transparent.`
+
+**Prompt-writing convention** (from `prompt_rewrite/prompts/system_prompt_t2i.txt`, the system
+prompt of the vendor's own rewriter — this is the closest thing to a MiniMax/LTX-style trained
+caption spec):
+
+- Output **English**, whatever the input language.
+- **~20 sentences, 400–500 words, ~25 words a sentence.**
+- Structure, in order: opening sentence naming medium/style/subject/background/orientation → a
+  positional inventory of elements across frame regions → a sequential walkthrough → a dedicated
+  text-rendering section if any legible text appears → a dedicated lighting sentence → a closing
+  composition summary.
+- **Preserve verbatim**: every text string to be rendered, "character for character, in their own
+  script, including punctuation and spacing"; every named object, count, stated colour, stated
+  position, and the aspect ratio if given.
+- **"Observe, don't instruct"** — present tense, third person, no imperatives.
+- **Never** include resolution, pixel counts, or quality boosters.
+- **"Enumerate; never summarise."**
+- Unspecified aspect ratio defaults to 3:2 or 2:3.
+- The rewriter emits `{"rewritten_prompt": ..., "wh_ratio": "16:9"}` and the README's own
+  integration snippet maps `wh_ratio` through the aspect table to `width`/`height`.
+
+The **edit** rewriter additionally emits `ratio_follow: "<image1>"`, meaning "inherit that input
+image's aspect ratio" — which matches the pipeline's own behaviour of deriving `height`/`width`
+from the *last* condition image when they are omitted.
+
+The PE models themselves (Qwen3.5-VL 9B, ~20 GB bf16, "a single 40 GB GPU handles either task")
+are **too heavy to bundle into a template** on a 24 GB box alongside the generator. The repo's
+existing `workflows/templates/expand-prompt.json` / `minimax/enhance-prompt.json` pattern is the
+right home if it is ever wanted; the written convention above is the part worth encoding in a
+skill or a stored prompt.
+
+## Missing knowledge / open questions
+
+Not answerable from documentation — each needs a real GPU run:
+
+1. **Actual peak VRAM at 2048×2048 with `offload: "model"` on a 24 GB card.** The weight
+   arithmetic says 17.5 GB resident; activations at 16 384 target tokens are unknown. This is the
+   single most important unknown and it decides whether the flagship template ships at 2K or 1K.
+2. **Wall-clock minutes** for the `cost` block. No vendor benchmark, no community number, nothing
+   in `jobs.sqlite`. A `cost` entry must be measured (the schema says "Never derived").
+3. **Peak VRAM and speed in editing mode with several reference images** — each condition image
+   adds a block to the joint sequence and a KV-cache entry across 32 layers.
+4. **Whether `transformers` 5.16.1 actually loads the checkpoint.** Vendor asks `>=5.17`. Imports
+   succeed; a real `from_pretrained` has not been tried.
+5. **Whether RGBA survives the repo's save path end to end** — `content_type: "image/png"` plus
+   `embed_metadata`. Plausible from the code, unverified.
+6. **Whether `sequential` offload works** at all here (Qwen3-VL is a composite module;
+   `exclude_from_cpu_offload` is sequential-only).
+7. **Does bnb-4bit quantization of `text_encoder` behave** when that encoder must also run the
+   vision tower? No pre-quantized repo exists to test against.
+8. **The blog post's benchmark numbers** — `qwen.ai/blog?id=qwen-image-2.1` is JS-rendered and
+   returned no text. Any quality claim relative to the 20B is currently uncited.
+9. **`use_kv_cache` and the step cache.** The docs say toggling it changes the sample
+   bit-for-bit-differently at fixed seed. If a template exposes it, it must be part of the cache
+   key — it already is, since it would be a step argument.
+10. **Circle / painted-annotation / mask local editing** is advertised but the README shows no
+    code for it beyond passing the annotated image as a condition image. Probably just that, but
+    unconfirmed.
+
+## What the templates should teach
+
+One idea per template, reading order. `qwen` as the family directory, matching `ltx2/` and
+`minimax/`. Every one of these should set `content_type: "image/png"` if alpha is in play and
+carry the non-commercial licence note in its `description`.
+
+1. **`workflows/models/qwen-image-2.1.json`** — the flagship, `configures: templates/text-to-image`
+   in spirit but with its own argument set (no `guidance_scale`). Teaches: `QwenImage21Pipeline`,
+   bf16, `offload: "model"`, 40 steps, an explicit 2K `width`/`height`, guidance left off.
+   Declares `variable_constraints` for `width`/`height` on the 32-px grid, no `snap`.
+2. **`workflows/templates/qwen/aspect-ratios.json`** — teaches the seven recommended sizes and
+   that the pipeline floors off-grid values. Could reasonably be folded into #1 as a documented
+   variable rather than its own file.
+3. **`workflows/templates/qwen/transparent.json`** — the one idea no other model in the catalog
+   has: native RGBA. Teaches the vendor's prompt wrapper *and* `content_type: "image/png"`, which
+   is the half that actually preserves the alpha.
+4. **`workflows/templates/qwen/edit.json`** — single condition image, instruction prompt, same
+   pipeline. Sits beside `templates/image-edit.json` (FLUX.1 Kontext) as the comparison. Teaches
+   that `width`/`height` omitted means "inherit the condition image's aspect ratio".
+5. **`workflows/templates/qwen/multi-reference.json`** — up to 10 references, following the
+   `"image": ["variable:first_image", "variable:second_image"]` list shape that
+   `templates/multi-image-reference.json` already established for FLUX.2. Teaches that order is
+   semantic (block-causal: later blocks attend to earlier ones) and that the prompt refers to them
+   positionally.
+6. **`workflows/templates/qwen/true-cfg.json`** — the only template that turns guidance *on*, with
+   a `negative_prompt` and `true_cfg_scale > 1`, and says plainly that this doubles the work per
+   step and is off by default on purpose. Guards against the next author copying FLUX's
+   `guidance_scale: 4`.
+7. *(optional, later)* **a prompt-rewriting chain** reusing `templates/expand-prompt` with the PE
+   convention written into a stored prompt — only if the 40 GB rewriter can be replaced by an
+   instruction to a model already in the catalog.
+
+A `for_each`-driven template is not obviously warranted; this family has no chaining or frame
+arithmetic.
+
+## Assessment (under 300 words)
+
+**Yes — onboard it, but ship one template, not six.**
+
+The primary documentation is unusually good for a day-zero release: a full vendor README with a
+default-parameter table, an aspect-ratio dict, verbatim code for all three modes, a diffusers docs
+page that already exists, and — rarest of all — the vendor's own prompt-rewriter **system prompt**,
+which gives a trained-caption spec as concrete as MiniMax's. `QwenImage21Pipeline` is already in
+the repo's venv and imports. No engine work is implied.
+
+What I would trust in a template's defaults: the class name and repo id; `torch.bfloat16`;
+`num_inference_steps: 40`; `true_cfg_scale` absent (guidance off); the seven aspect-ratio pairs and
+the 32-px floor rule; the RGBA prompt wrapper; the list-of-images editing shape; the prompt
+convention. All of these are stated by the vendor or readable in the installed source.
+
+What I would **not** ship without a real GPU run: any `cost` entry (there is no number anywhere,
+and the schema forbids deriving one); `2048 × 2048` as the default resolution on a 24 GB card —
+the weight arithmetic (17.5 GB peak under model offload) leaves ~6 GB for a 16 384-token attention
+and I cannot size that from documents, so a first template should probably default to 1K and
+document 2K as the vendor's recommendation; anything about `sequential` offload or 4-bit, since no
+pre-quantized build exists and the text encoder doubles as the vision tower; and the RGBA→PNG save
+path.
+
+Two non-technical flags: the **Qwen Research License is non-commercial**, unlike every Apache-2.0
+sibling, and the repo has no convention yet for recording that. And `transformers` is **5.16.1**
+against a stated `>=5.17`.
+
+**On a skill**: the draft proposal reserved that question for Qwen-Image-Edit. In 2.1 editing is an
+argument, not a checkpoint, so the shape-picking a skill would do collapses to "is there an input
+image, and how many". That is template-selection, not a skill — *unless* the prompt convention
+(400–500 words, prescribed section order, verbatim text preservation) is judged worth a skill on
+its own, the way the LTX-2.5 caption spec was. That is a real argument, and it is the only one.
diff --git a/docs/proposals/qwen-image-wan-onboarding.md b/docs/proposals/qwen-image-wan-onboarding.md
index f351062f..8e04f272 100644
--- a/docs/proposals/qwen-image-wan-onboarding.md
+++ b/docs/proposals/qwen-image-wan-onboarding.md
@@ -2,6 +2,14 @@
 
 Status: draft, 2026-09-08. No implementation.
 
+**Note (2026-09-20):** this proposal is about the older, larger, Apache-2.0
+20B `Qwen/Qwen-Image` line. A separate, newer, non-commercial 7B model,
+`Qwen/Qwen-Image-2.1`, released 2026-09-20 and was onboarded on its own —
+see `docs/proposals/audits/2026-09-20-qwen-image-2.1-audit.md` and
+`workflows/models/qwen-image-2.1.json`. The two do not supersede one another:
+they coexist under different licenses. This draft's scope (20B Qwen-Image
+and Wan2.x) is still open.
+
 ## Why these two
 
 Neither has a template under `workflows/models/`. Both rank among the most
diff --git a/workflows/models/qwen-image-2.1.json b/workflows/models/qwen-image-2.1.json
new file mode 100644
index 00000000..3e7ee4ba
--- /dev/null
+++ b/workflows/models/qwen-image-2.1.json
@@ -0,0 +1,51 @@
+{
+    "cost_drivers": ["num_images_per_prompt", "num_inference_steps", "width", "height"],
+    "variables": {
+        "prompt": "A realistic photograph of a mouse wearing a skirt playing volleyball against a team of professional volleyball players.",
+        "num_images_per_prompt": 1,
+        "num_inference_steps": 40,
+        "width": 2048,
+        "height": 2048
+    },
+    "id": "QwenImage2.1",
+    "description": "Text-to-image with Qwen-Image-2.1: a unified 7B model (32 single-stream DiT layers, Qwen3-VL 8B text encoder) that also does instruction editing and native RGBA output, though this template only exercises plain text-to-image. No guidance_scale - the pipeline takes only true_cfg_scale, which the vendor recommends leaving at its default of 1.0 (off). width/height are set explicitly because the pipeline falls back to a 1024x1024 output_resolution default otherwise, well under the model's native 2K. Qwen Research License: non-commercial use only, unlike every other model in this catalog, which are Apache-2.0 - see https://huggingface.co/Qwen/Qwen-Image-2.1/blob/main/LICENSE. VRAM at 2048x2048 under model offload has not been measured on a 24GB card - weight residency alone is 17.5GB, leaving headroom for activations that is unverified at this resolution; drop width/height to 1024 if it does not fit. No cost has been measured yet.",
+    "configures": "templates/text-to-image",
+    "variable_constraints": {
+        "width": {
+            "modulus": 32,
+            "remainder": 0,
+            "reason": "Qwen-Image-2.1 rounds width/height down to a multiple of 32 (vae_scale_factor * 2), so an off-grid value is not refused by the pipeline but silently shrunk - refused here instead, with no 'snap', since rounding the other way would be a second silent change to the size asked for"
+        },
+        "height": {
+            "modulus": 32,
+            "remainder": 0,
+            "reason": "Qwen-Image-2.1 rounds width/height down to a multiple of 32 (vae_scale_factor * 2), so an off-grid value is not refused by the pipeline but silently shrunk - refused here instead, with no 'snap', since rounding the other way would be a second silent change to the size asked for"
+        }
+    },
+    "steps": [
+        {
+            "name": "main",
+            "pipeline": {
+                "configuration": {
+                    "component_type": "QwenImage21Pipeline",
+                    "offload": "model"
+                },
+                "from_pretrained_arguments": {
+                    "model_name": "Qwen/Qwen-Image-2.1",
+                    "torch_dtype": "torch.bfloat16"
+                },
+                "arguments": {
+                    "prompt": "variable:prompt",
+                    "num_inference_steps": "variable:num_inference_steps",
+                    "num_images_per_prompt": "variable:num_images_per_prompt",
+                    "width": "variable:width",
+                    "height": "variable:height"
+                }
+            },
+            "result": {
+                "content_type": "image/jpeg",
+                "embed_metadata": true
+            }
+        }
+    ]
+}

From 006b06736b05dd56550d3bd74acbf23e02fbfdfc Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sun, 20 Sep 2026 10:53:18 -0500
Subject: [PATCH 77/77] fix: Qwen-Image-2.1 field findings - alpha into jpeg,
 location-dict assets, edit entry, image crop

A field run of models/qwen-image-2.1 found three silent breaks that
validation passed: the pipeline returns RGBA and the entry asked for
image/jpeg, so the save died after a full generation; the 2048x2048
decode OOMs on a 24GB card with all 40 steps done; and a location dict
carrying an asset: reference passed validation and failed the run.

Engine:
- An RGBA image handed to a non-alpha image content type is flattened
  over white and warned about (kind alpha_discarded, naming image/png as
  the format that keeps it) rather than failing the save. Any pipeline
  that decodes an alpha channel hit this on every card.
- resolve_path_references walks a {"location": ...} dict, so
  {"location": "asset:x.png"} under an image key or in a media_type
  reference resolves like the bare string and the list element already
  did. The media conventions hand the dict whole to the loader, which
  is why realize_args's own recursion never reached it.
- get_output_image takes crop=[x, y, w, h] in the original's pixels, cut
  before the downscale and reported clamped, so a region of a 2K still
  can be inspected at 100%.

Catalog:
- models/qwen-image-2.1: image/png, VAE tiled and sliced, measured cost
  (4.3 min, RTX 3090), and the rule that offload is a property of the
  mode - 'model' fits text-to-image at 2K, an edit needs 'sequential'.
- models/qwen-image-2.1-edit: the editing path, configuring
  templates/image-edit, with the proven sequential-offload config and
  its measured cost (4.7 min).

Docs: cost present is the catalog's verified marker (WORKFLOW_GUIDE and
the list_workflows docstring); the three places an asset: name can sit;
the crop parameter in MCP.md; the audit's proposed-template names no
longer read as paths to files that do not exist.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 docs/MCP.md                                   |  2 +-
 docs/WORKFLOW_GUIDE.md                        | 11 ++-
 .../audits/2026-09-20-qwen-image-2.1-audit.md | 16 +++--
 dw/arguments.py                               | 11 ++-
 dw/result.py                                  | 42 +++++++++++
 dw_mcp/media.py                               | 35 +++++++++-
 dw_mcp/server.py                              | 20 ++++--
 tests/test_assets.py                          | 13 ++++
 tests/test_mcp_media.py                       | 48 +++++++++++++
 tests/test_mcp_server.py                      | 23 +++++++
 tests/test_result.py                          | 59 ++++++++++++++++
 workflows/models/qwen-image-2.1-edit.json     | 69 +++++++++++++++++++
 workflows/models/qwen-image-2.1.json          | 25 +++++--
 13 files changed, 352 insertions(+), 22 deletions(-)
 create mode 100644 workflows/models/qwen-image-2.1-edit.json

diff --git a/docs/MCP.md b/docs/MCP.md
index 2be4b937..6dbe0d35 100644
--- a/docs/MCP.md
+++ b/docs/MCP.md
@@ -233,7 +233,7 @@ when no single workflow covers it.
 
 | Tool | Arguments | Purpose |
 | --- | --- | --- |
-| `get_output_image(name, max_dimension=768, workspace=None)` | `name`, `max_dimension`, `workspace` | Look at a generated image, downscaled to `max_dimension` on its longest side. Returns the image plus a text part reporting `original_size`, `returned_size` and `bytes`, so a downscale is never silent. `workspace` names the workspace for this one call without switching the session to it - the same pin `run_workflow` takes, so a job run into another workspace stays reachable from the session that queued it |
+| `get_output_image(name, max_dimension=768, workspace=None, crop=None)` | `name`, `max_dimension`, `workspace`, `crop` | Look at a generated image, downscaled to `max_dimension` on its longest side. Returns the image plus a text part reporting `original_size`, `returned_size` and `bytes`, so a downscale is never silent. `crop` is `[x, y, width, height]` in the original's pixels, cut before the downscale and reported back clamped - the way to see a region of a 2K still at 100%, where the whole would be shrunk past what a small element or a decode-tiling seam can be judged at. `workspace` names the workspace for this one call without switching the session to it - the same pin `run_workflow` takes, so a job run into another workspace stays reachable from the session that queued it |
 | `get_output_audio(name, workspace=None)` | `name`, `workspace` | Listen to a generated audio output, as base64. Unlike `get_output_image` there is no downscale - a clip whose base64 size would exceed the same 4MB budget is refused outright rather than cut or transcoded, since a truncated clip is a different, misleading answer rather than a smaller correct one (#204). Use `download_output` or the gallery `url` for a longer file, and `get_gallery_metadata` for its duration and sample rate without fetching the bytes at all. `workspace` names the workspace for this one call without switching the session to it |
 | `get_output_text(name, max_characters=20000, workspace=None)` | `name`, `max_characters`, `workspace` | Read a text output — a prompt enhancement, or any step whose result is `text/plain` or JSON. Reports the file's real length and whether it was truncated. `workspace` names the workspace for this one call without switching the session to it - the same pin `run_workflow` takes, so a job run into another workspace stays reachable from the session that queued it |
 | `download_output(name, destination=None, overwrite=False, workspace=None)` | `name`, `destination`, `overwrite`, `workspace` | Save one output file to local disk, of any content type. `destination` may be a full path, a directory, or omitted to save under the output's own name in the current working directory; `~` expands and missing parent directories are created. `overwrite=True` is required to replace a file already at the resolved path. Over a `dw.serve --mcp` endpoint the file lands on the server, so the destination is confined to that workspace and a relative one is joined onto it. Returns nothing to the conversation but where the file landed — unlike the other media tools, the point is a file on disk, not a payload in context. Writes on the machine running the MCP server - over `dw.serve --mcp` that is the GPU box. A write that fails there (a path that exists only on the client, for instance) comes back as an error naming the server-side write and the client-side alternatives, not as an anonymous tool failure. `workspace` names the workspace for this one call without switching the session to it - the same pin `run_workflow` takes, so a job run into another workspace stays reachable from the session that queued it |
diff --git a/docs/WORKFLOW_GUIDE.md b/docs/WORKFLOW_GUIDE.md
index 29d80af7..924045b5 100644
--- a/docs/WORKFLOW_GUIDE.md
+++ b/docs/WORKFLOW_GUIDE.md
@@ -283,6 +283,10 @@ for existence.
 - `asset:` — `asset:name` is a file in the asset library. Rooted at the
   library and confined to it, never resolved relative to the workflow file; a path that
   escapes the library is rejected. `upload_asset` returns one of these names.
+  One name, three places it can sit: a bare string (`"image": "asset:x.png"`),
+  an element of a list, or the `location` of a media dict
+  (`{"location": "asset:x.png"}`, with or without `media_type`) - all resolve
+  to the same file.
 - `output:` — `output:<workflow identity>/<run id>/<file>` is a file an earlier
   run wrote, under the output root and confined to it. `latest` in the run-id position
   picks the newest run that holds that file. A run id is not stable against
@@ -727,7 +731,12 @@ longer than that is truncated with an ellipsis in every listing.
 Declare `shape`, `traits` or `summary` at the top level only when derivation
 gets it wrong; a declaration that merely repeats the derivation is noise that
 rots when the rules change, and the repo's catalog tests refuse it. `cost` is
-never derived — leave it absent until a run has been measured.
+never derived — leave it absent until a run has been measured. That makes it
+the catalog's verified marker as well: an entry carrying `cost` has been run
+to completion on the device it names, and one without has only been authored
+— its description may still say what it has not been able to check (VRAM at
+a size, whether a format carries what the pipeline returns), and the first
+run is the one that finds out.
 
 `cost_drivers` is the other half of saying what a workflow costs, and it *is*
 for derivation: the variables that move the wall clock — a frame count, a
diff --git a/docs/proposals/audits/2026-09-20-qwen-image-2.1-audit.md b/docs/proposals/audits/2026-09-20-qwen-image-2.1-audit.md
index 1537d2a8..58536bdd 100644
--- a/docs/proposals/audits/2026-09-20-qwen-image-2.1-audit.md
+++ b/docs/proposals/audits/2026-09-20-qwen-image-2.1-audit.md
@@ -231,21 +231,23 @@ carry the non-commercial licence note in its `description`.
    in spirit but with its own argument set (no `guidance_scale`). Teaches: `QwenImage21Pipeline`,
    bf16, `offload: "model"`, 40 steps, an explicit 2K `width`/`height`, guidance left off.
    Declares `variable_constraints` for `width`/`height` on the 32-px grid, no `snap`.
-2. **`workflows/templates/qwen/aspect-ratios.json`** — teaches the seven recommended sizes and
+2. **a `templates/qwen/aspect-ratios` template** (not yet written) — teaches the seven recommended sizes and
    that the pipeline floors off-grid values. Could reasonably be folded into #1 as a documented
    variable rather than its own file.
-3. **`workflows/templates/qwen/transparent.json`** — the one idea no other model in the catalog
+3. **a `templates/qwen/transparent` template** (not yet written) — the one idea no other model in the catalog
    has: native RGBA. Teaches the vendor's prompt wrapper *and* `content_type: "image/png"`, which
    is the half that actually preserves the alpha.
-4. **`workflows/templates/qwen/edit.json`** — single condition image, instruction prompt, same
-   pipeline. Sits beside `templates/image-edit.json` (FLUX.1 Kontext) as the comparison. Teaches
-   that `width`/`height` omitted means "inherit the condition image's aspect ratio".
-5. **`workflows/templates/qwen/multi-reference.json`** — up to 10 references, following the
+4. **`workflows/models/qwen-image-2.1-edit.json`** (shipped, after a field run found the
+   text-to-image entry's three silent breaks) — single condition image, instruction prompt, same
+   pipeline, `configures: templates/image-edit` (FLUX.1 Kontext) as the comparison. Runs
+   `offload: "sequential"` where the text-to-image entry runs `"model"`: the condition latents
+   lengthen the sequence, and `"model"` OOMs at 2048x1024 on a clean 24GB card.
+5. **a `templates/qwen/multi-reference` template** (not yet written) — up to 10 references, following the
    `"image": ["variable:first_image", "variable:second_image"]` list shape that
    `templates/multi-image-reference.json` already established for FLUX.2. Teaches that order is
    semantic (block-causal: later blocks attend to earlier ones) and that the prompt refers to them
    positionally.
-6. **`workflows/templates/qwen/true-cfg.json`** — the only template that turns guidance *on*, with
+6. **a `templates/qwen/true-cfg` template** (not yet written) — the only template that turns guidance *on*, with
    a `negative_prompt` and `true_cfg_scale > 1`, and says plainly that this doubles the work per
    step and is off by default on purpose. Guards against the next author copying FLUX's
    `guidance_scale: 4`.
diff --git a/dw/arguments.py b/dw/arguments.py
index a0da8751..b6111251 100644
--- a/dw/arguments.py
+++ b/dw/arguments.py
@@ -116,7 +116,7 @@ def realize_args(arg, base_dir=None):
             # library, and does it first: what it stands for is a path, so
             # everything below - the media conventions, an object's
             # 'from_file' - then handles it as the path it always was
-            if is_path_reference(v) or isinstance(v, list):
+            if is_path_reference(v) or isinstance(v, (list, dict)):
                 v = arg[k] = resolve_path_references(v, base_dir)
             # A constant resolves under any argument name, and before the
             # conventions below - what it holds is the value, not a file to load
@@ -212,7 +212,12 @@ def resolve_path_references(value, base_dir=None):
     A list is walked in place, because an 'image' argument may be a list of
     references and the key conventions hand the whole list to the loader at
     once - by then it is too late for a reference to be recognized.
-    Dictionaries are left alone: realize_args recurses into those itself,
+    A {"location": ...} dict is walked the same way, for the same reason: the
+    media conventions hand the whole dict to the loader, which reads the
+    location out of it and joins it onto the workflow directory - so
+    {"location": "asset:x.png"} passed validation (which sees every string)
+    and then failed the run on a path that was never resolved. Other
+    dictionaries are left alone: realize_args recurses into those itself,
     and each of their values reaches this on the way through.
     """
     if is_asset_reference(value):
@@ -222,6 +227,8 @@ def resolve_path_references(value, base_dir=None):
     if isinstance(value, list):
         for index, item in enumerate(value):
             value[index] = resolve_path_references(item, base_dir)
+    elif isinstance(value, dict) and is_path_reference(value.get("location")):
+        value["location"] = resolve_path_references(value["location"], base_dir)
     return value
 
 
diff --git a/dw/result.py b/dw/result.py
index f2532362..a6e0d983 100644
--- a/dw/result.py
+++ b/dw/result.py
@@ -74,6 +74,44 @@ def _peak_dbfs(waveform):
     return 20.0 * float(numpy.log10(peak))
 
 
+# Image formats that carry an alpha channel; every other image content type
+# takes the picture flattened over white
+ALPHA_CONTENT_TYPES = {"image/png", "image/webp", "image/gif", "image/tiff"}
+
+
+def flatten_alpha_for(image, content_type, file_name):
+    """The image as the content type can carry it: unchanged when it has no
+    alpha channel or the format keeps one, otherwise composited over white
+    and said out loud.
+
+    Pillow refuses to write mode RGBA as JPEG, and it refused after the whole
+    generation had run - Qwen-Image-2.1 decodes an alpha channel natively,
+    and every image template in the catalog asked for image/jpeg. A warning
+    rather than an error, because the run did what was asked and the file
+    is usable; the warning names the format that would have kept the alpha.
+    """
+    mode = getattr(image, "mode", None)
+    if mode not in ("RGBA", "LA", "PA") or content_type in ALPHA_CONTENT_TYPES:
+        return image
+    from PIL import Image as PILImage
+
+    rgba = image.convert("RGBA")
+    flattened = PILImage.new("RGB", rgba.size, (255, 255, 255))
+    flattened.paste(rgba, mask=rgba.getchannel("A"))
+    if getattr(image, "info", None):
+        flattened.info.update(image.info)
+    emit_warning(
+        f"The image written to {file_name} had an alpha channel that "
+        f"{content_type} cannot carry - it was flattened over white. Set "
+        f"the step's result 'content_type' to 'image/png' to keep the "
+        f"transparency.",
+        kind="alpha_discarded",
+        file=file_name,
+        content_type=content_type,
+    )
+    return flattened
+
+
 def warn_without_headroom(waveform, file_name):
     """Say when the soundtrack about to be written is at or over full scale.
 
@@ -715,6 +753,10 @@ def save_artifact(
                 with open(output_path, "w") as file:
                     file.write(artifact)
             elif hasattr(artifact, "save"):
+                if content_type.startswith("image/"):
+                    artifact = flatten_alpha_for(
+                        artifact, content_type, os.path.basename(output_path)
+                    )
                 if (
                     self.metadata is not None
                     and self.result_definition.get("embed_metadata", False)
diff --git a/dw_mcp/media.py b/dw_mcp/media.py
index 3fb86de4..149cbd66 100644
--- a/dw_mcp/media.py
+++ b/dw_mcp/media.py
@@ -30,9 +30,14 @@
 MAX_RETURNED_CHARACTERS = 20000
 
 
-def get_output_image(client, name, max_dimension=768, workspace=None):
+def get_output_image(client, name, max_dimension=768, workspace=None, crop=None):
     """One image from the output directory, downscaled, as base64 plus the
-    sizes it went in and came out at."""
+    sizes it went in and came out at.
+
+    `crop` is `[x, y, width, height]` in the original's pixels, cut before
+    the downscale, so a region of a 2K still comes back at 100% where the
+    whole would be shrunk past what a seam or a small element can be read
+    at. Clamped to the image; the box actually cut is reported."""
 
     def is_image(content_type):
         return not content_type or content_type.startswith("image/")
@@ -52,6 +57,10 @@ def is_image(content_type):
         raise DwApiError(f"{name} could not be decoded as an image.")
 
     original_size = [image.width, image.height]
+    if crop is not None:
+        box = _crop_box(crop, image.width, image.height)
+        crop = [box[0], box[1], box[2] - box[0], box[3] - box[1]]
+        image = image.crop(box)
     fmt = "JPEG" if (image.format or "").upper() == "JPEG" else "PNG"
     if image.mode not in ("RGB", "L") and fmt == "JPEG":
         image = image.convert("RGB")
@@ -63,11 +72,33 @@ def is_image(content_type):
         "data": base64.b64encode(encoded).decode("ascii"),
         "mime_type": "image/jpeg" if fmt == "JPEG" else "image/png",
         "original_size": original_size,
+        "crop": crop,
         "returned_size": [sized.width, sized.height],
         "bytes": len(encoded),
     }
 
 
+def _crop_box(crop, width, height):
+    """`[x, y, w, h]` as Pillow's `(left, upper, right, lower)`, clamped to
+    the image. Refused when it is not four non-negative integers, starts
+    outside the image, or has nothing in it."""
+    try:
+        x, y, w, h = (int(v) for v in crop)
+    except (TypeError, ValueError):
+        raise DwApiError(
+            f"crop must be [x, y, width, height] in pixels, got {crop!r}."
+        )
+    if x < 0 or y < 0 or w <= 0 or h <= 0:
+        raise DwApiError(
+            f"crop must have a non-negative origin and a positive size, got {crop!r}."
+        )
+    if x >= width or y >= height:
+        raise DwApiError(
+            f"crop origin ({x}, {y}) lies outside the {width}x{height} image."
+        )
+    return (x, y, min(x + w, width), min(y + h, height))
+
+
 def _encode_within_budget(image, limit, fmt):
     """Shrink until the base64-encoded bytes fit the ceiling. Two loops
     rather than one calculation because compressed size does not follow
diff --git a/dw_mcp/server.py b/dw_mcp/server.py
index 13374f7f..f503ffe9 100644
--- a/dw_mcp/server.py
+++ b/dw_mcp/server.py
@@ -182,7 +182,10 @@ def list_workflows(
         figures a maintainer measured once on the devices named and wrote
         into the workflow, never derived from this server's job history -
         so null means nobody wrote one down, not that the run is cheap;
-        the answer's `cost_basis` says as much. `observed_minutes` and
+        the answer's `cost_basis` says as much. It is also the mark of an
+        entry that has been run through on a real device: one without a
+        `cost` has only been authored, and its first run is the one that
+        finds what the description could not verify. `observed_minutes` and
         `observed_runs`, when present, are this box's *own* finished runs
         of that workflow - the cold median, model load included, and how
         many runs are behind it. Prefer it when quoting a price for this
@@ -514,7 +517,10 @@ def get_guide(name: str, section: str | None = None) -> dict:
     # --------------------------------------------------------------- media
 
     def get_output_image(
-        name: str, max_dimension: int = 768, workspace: str | None = None
+        name: str,
+        max_dimension: int = 768,
+        workspace: str | None = None,
+        crop: list[int] | None = None,
     ) -> list[ImageContent | TextContent]:
         """Look at a generated image, named as `list_gallery` or a job's
         manifest reports it. Use this to judge output quality - it is the
@@ -524,14 +530,17 @@ def get_output_image(
         with `get_gallery_metadata` or hand the user the file. The image is
         downscaled to `max_dimension` on its longest side; the second part
         of the result reports the size it went in and came out at, so a
-        downscale is never silent.
+        downscale is never silent. `crop` is `[x, y, width, height]` in the
+        original's pixels, cut before the downscale - the way to see a
+        region of a 2K still at 100%, where the whole would be shrunk past
+        what a small element or a tiling seam can be judged at.
 
         `workspace` names the workspace for this one call without
         switching the session to it - the same pin `run_workflow`
         takes, so a job run into another workspace is reachable from
         here without leaving this one (#99)."""
         result = media.get_output_image(
-            client, name, max_dimension=max_dimension, workspace=workspace
+            client, name, max_dimension=max_dimension, workspace=workspace, crop=crop
         )
         image = ImageContent(
             type="image", data=result["data"], mime_type=result["mime_type"]
@@ -541,7 +550,8 @@ def get_output_image(
             text=(
                 f"name: {result['name']}\n"
                 f"original_size: {result['original_size']}\n"
-                f"returned_size: {result['returned_size']}\n"
+                + (f"crop: {result['crop']}\n" if result["crop"] else "")
+                + f"returned_size: {result['returned_size']}\n"
                 f"bytes: {result['bytes']}"
             ),
         )
diff --git a/tests/test_assets.py b/tests/test_assets.py
index d6763eb3..3664d884 100644
--- a/tests/test_assets.py
+++ b/tests/test_assets.py
@@ -118,6 +118,19 @@ def test_a_list_of_assets_resolves(self, asset_dir):
         realize_args(args)
         assert [image.size for image in args["image"]] == [(8, 8), (8, 8)]
 
+    def test_a_location_dict_under_an_image_key_resolves(self, asset_dir):
+        # The form templates/image-edit writes. The dict reaches fetch_image
+        # whole through the key convention, so the reference inside it has to
+        # be resolved before that, not on the recursion that never happens
+        args = {"image": {"location": "asset:iris.png"}}
+        realize_args(args)
+        assert args["image"].size == (8, 8)
+
+    def test_a_location_dict_in_a_media_reference_resolves(self, asset_dir):
+        args = {"anything": {"media_type": "image", "location": "asset:iris.png"}}
+        realize_args(args)
+        assert args["anything"].size == (8, 8)
+
     def test_an_object_built_from_an_asset_resolves(self, asset_dir):
         args = {"reference": {"from_file": "asset:iris.png"}}
         realize_args(args)
diff --git a/tests/test_mcp_media.py b/tests/test_mcp_media.py
index b03f1b14..721a3c89 100644
--- a/tests/test_mcp_media.py
+++ b/tests/test_mcp_media.py
@@ -80,6 +80,54 @@ def test_a_small_image_is_returned_at_its_own_size():
     assert result["returned_size"] == [64, 48]
 
 
+class TestCrop:
+    """A 2K still cannot be checked for whether a small element reads, or
+    for a decode-tiling seam, through a 768-pixel downscale. `crop` is a
+    box in the original's pixels, cut before the downscale, so a region
+    of the full-resolution file comes back at 100%."""
+
+    def two_tone(self):
+        # left half red, right half blue, 2048 wide
+        image = Image.new("RGB", (2048, 1024), (255, 0, 0))
+        image.paste((0, 0, 255), (1024, 0, 2048, 1024))
+        buffer = io.BytesIO()
+        image.save(buffer, format="PNG")
+        return serving(buffer.getvalue(), "image/png")
+
+    def test_a_crop_returns_that_region_at_full_resolution(self):
+        result = get_output_image(
+            self.two_tone(), "big.png", max_dimension=768, crop=[1000, 0, 400, 300]
+        )
+        image = decoded(result)
+        assert image.size == (400, 300)
+        assert image.getpixel((0, 0)) == (255, 0, 0)
+        assert image.getpixel((399, 0)) == (0, 0, 255)
+        assert result["original_size"] == [2048, 1024]
+        assert result["crop"] == [1000, 0, 400, 300]
+        assert result["returned_size"] == [400, 300]
+
+    def test_a_crop_wider_than_max_dimension_is_still_downscaled(self):
+        result = get_output_image(
+            self.two_tone(), "big.png", max_dimension=256, crop=[0, 0, 1024, 512]
+        )
+        assert decoded(result).size == (256, 128)
+        assert result["crop"] == [0, 0, 1024, 512]
+
+    def test_a_crop_is_clamped_to_the_image(self):
+        result = get_output_image(
+            self.two_tone(), "big.png", max_dimension=768, crop=[1900, 900, 500, 500]
+        )
+        assert decoded(result).size == (148, 124)
+        assert result["crop"] == [1900, 900, 148, 124]
+
+    @pytest.mark.parametrize(
+        "crop", [[0, 0, 0, 10], [-1, 0, 10, 10], [2048, 0, 10, 10], [0, 0, 10], "x"]
+    )
+    def test_an_empty_or_malformed_crop_is_refused(self, crop):
+        with pytest.raises(DwApiError, match="crop"):
+            get_output_image(self.two_tone(), "big.png", crop=crop)
+
+
 def test_a_jpeg_source_comes_back_as_jpeg():
     client = serving(jpeg_bytes(300, 300), "image/jpeg")
 
diff --git a/tests/test_mcp_server.py b/tests/test_mcp_server.py
index 119b06a5..2033970b 100644
--- a/tests/test_mcp_server.py
+++ b/tests/test_mcp_server.py
@@ -279,6 +279,29 @@ def refusing(request):
     assert "dw-serve" in str(caught.value)
 
 
+@pytest.mark.asyncio
+async def test_a_crop_is_cut_and_reported():
+    import io
+    from PIL import Image
+
+    buffer = io.BytesIO()
+    Image.new("RGB", (2048, 1024), (1, 2, 3)).save(buffer, format="PNG")
+    body = buffer.getvalue()
+
+    def serving_png(request):
+        return httpx.Response(200, content=body, headers={"content-type": "image/png"})
+
+    server = server_over(serving_png)
+
+    result = await server.call_tool(
+        "get_output_image", {"name": "out.png", "crop": [1000, 500, 300, 200]}
+    )
+
+    text = result.content[1].text
+    assert "crop: [1000, 500, 300, 200]" in text
+    assert "returned_size: [300, 200]" in text
+
+
 @pytest.mark.asyncio
 async def test_an_image_comes_back_as_an_image_block():
     def serving_png(request):
diff --git a/tests/test_result.py b/tests/test_result.py
index a577b922..6b381549 100644
--- a/tests/test_result.py
+++ b/tests/test_result.py
@@ -1483,6 +1483,65 @@ def test_upmix_warns(self, monkeypatch):
         assert warnings and "mono" in warnings[0].lower()
 
 
+class TestAlphaIntoJpeg:
+    """An RGBA image handed to a JPEG (or WebP-with-metadata) result used to
+    fail the save with Pillow's 'cannot write mode RGBA as JPEG' - after a
+    full generation, on every card, for any pipeline that decodes an alpha
+    channel (Qwen-Image-2.1 does natively). The file is written flattened
+    over white instead, and the flattening is said out loud, since the
+    workflow asked for a format that cannot carry what the pipeline made."""
+
+    def _save(self, monkeypatch, temp_dir, result_def):
+        import dw.result as result_module
+
+        warnings = []
+        monkeypatch.setattr(
+            result_module,
+            "emit_warning",
+            lambda message, **data: warnings.append((message, data)),
+        )
+        result = Result(result_def)
+        result.add_result(Image.new("RGBA", (4, 4), (255, 0, 0, 0)))
+        result.save(temp_dir, "wf-step.0")
+        return warnings
+
+    def test_an_rgba_image_is_flattened_into_the_jpeg(self, monkeypatch):
+        with tempfile.TemporaryDirectory() as temp_dir:
+            warnings = self._save(
+                monkeypatch, temp_dir, {"content_type": "image/jpeg", "save": True}
+            )
+            (name,) = os.listdir(temp_dir)
+            with Image.open(os.path.join(temp_dir, name)) as written:
+                assert written.mode == "RGB"
+                # transparent red over white is white
+                assert written.getpixel((0, 0)) == (255, 255, 255)
+            assert len(warnings) == 1
+            assert warnings[0][1]["kind"] == "alpha_discarded"
+            assert "image/png" in warnings[0][0]
+
+    def test_the_flattening_also_happens_on_the_metadata_path(self, monkeypatch):
+        with tempfile.TemporaryDirectory() as temp_dir:
+            warnings = self._save(
+                monkeypatch,
+                temp_dir,
+                {"content_type": "image/jpeg", "save": True, "embed_metadata": True},
+            )
+            (name,) = os.listdir(temp_dir)
+            with Image.open(os.path.join(temp_dir, name)) as written:
+                assert written.mode == "RGB"
+            assert [data["kind"] for _, data in warnings] == ["alpha_discarded"]
+
+    def test_a_png_keeps_its_alpha_and_says_nothing(self, monkeypatch):
+        with tempfile.TemporaryDirectory() as temp_dir:
+            warnings = self._save(
+                monkeypatch, temp_dir, {"content_type": "image/png", "save": True}
+            )
+            (name,) = os.listdir(temp_dir)
+            with Image.open(os.path.join(temp_dir, name)) as written:
+                assert written.mode == "RGBA"
+            assert warnings == []
+
+
 class TestNoHeadroom:
     """#158: `music-video`'s deliverable came back at +3.26 dBFS and the job
     warned about a 6.4 dB level jump between shots, which is the lesser
diff --git a/workflows/models/qwen-image-2.1-edit.json b/workflows/models/qwen-image-2.1-edit.json
new file mode 100644
index 00000000..7a95d7d1
--- /dev/null
+++ b/workflows/models/qwen-image-2.1-edit.json
@@ -0,0 +1,69 @@
+{
+    "cost": [
+        {
+            "device": "cuda",
+            "name": "RTX 3090",
+            "vram_gb": 24,
+            "minutes": 4.7
+        }
+    ],
+    "cost_drivers": ["num_inference_steps", "width", "height"],
+    "variables": {
+        "prompt": "recolor this person's hair blonde",
+        "input_image": {
+            "location": "https://pbs.twimg.com/media/HNi-N_eWIAAJfTZ?format=jpg&name=900x900"
+        },
+        "seed": 20260921,
+        "width": 2048,
+        "height": 1024,
+        "output_resolution": 2048,
+        "num_inference_steps": 40
+    },
+    "seed": "variable:seed",
+    "id": "QwenImage21Edit",
+    "description": "Instruction editing with Qwen-Image-2.1: re-renders a supplied picture toward a written instruction, the editing path the unified model advertises and models/qwen-image-2.1 does not exercise. Offload is a property of the mode, not the model: the condition image's latents are prepended to the noise, so an edit at 2048x1024 carries a longer sequence than plain text-to-image at 2048x2048, and under 'model' offload it runs out of memory by 582 MiB on a clean 24GB card - measured, and shape-determined rather than leakage from an earlier job - so this entry runs 'sequential' where the text-to-image entry runs 'model'. output_resolution is set to 2048 so the condition image is not resized down to the pipeline's 1024 default; width/height name the canvas the edit lands on. The VAE is tiled and sliced because the decode at this size does not otherwise fit, and the result is image/png because the pipeline returns RGBA. true_cfg_scale is left at its default of 1.0, so negative_prompt is ignored and the instruction has to be written positively. input_image takes a URL, a path, or an asset: reference - keep_output turns an earlier run's picture into one. Qwen Research License: non-commercial use only - see https://huggingface.co/Qwen/Qwen-Image-2.1/blob/main/LICENSE.",
+    "configures": "templates/image-edit",
+    "variable_constraints": {
+        "width": {
+            "modulus": 32,
+            "remainder": 0,
+            "reason": "Qwen-Image-2.1 rounds width/height down to a multiple of 32 (vae_scale_factor * 2), so an off-grid value is not refused by the pipeline but silently shrunk - refused here instead, with no 'snap', since rounding the other way would be a second silent change to the size asked for"
+        },
+        "height": {
+            "modulus": 32,
+            "remainder": 0,
+            "reason": "Qwen-Image-2.1 rounds width/height down to a multiple of 32 (vae_scale_factor * 2), so an off-grid value is not refused by the pipeline but silently shrunk - refused here instead, with no 'snap', since rounding the other way would be a second silent change to the size asked for"
+        }
+    },
+    "steps": [
+        {
+            "name": "edit",
+            "pipeline": {
+                "configuration": {
+                    "component_type": "QwenImage21Pipeline",
+                    "offload": "sequential",
+                    "vae": {
+                        "enable_slicing": true,
+                        "enable_tiling": true
+                    }
+                },
+                "from_pretrained_arguments": {
+                    "model_name": "Qwen/Qwen-Image-2.1",
+                    "torch_dtype": "torch.bfloat16"
+                },
+                "arguments": {
+                    "prompt": "variable:prompt",
+                    "image": "variable:input_image",
+                    "output_resolution": "variable:output_resolution",
+                    "width": "variable:width",
+                    "height": "variable:height",
+                    "num_inference_steps": "variable:num_inference_steps"
+                }
+            },
+            "result": {
+                "content_type": "image/png",
+                "embed_metadata": true
+            }
+        }
+    ]
+}
diff --git a/workflows/models/qwen-image-2.1.json b/workflows/models/qwen-image-2.1.json
index 3e7ee4ba..89f633b1 100644
--- a/workflows/models/qwen-image-2.1.json
+++ b/workflows/models/qwen-image-2.1.json
@@ -1,5 +1,18 @@
 {
-    "cost_drivers": ["num_images_per_prompt", "num_inference_steps", "width", "height"],
+    "cost": [
+        {
+            "device": "cuda",
+            "name": "RTX 3090",
+            "vram_gb": 24,
+            "minutes": 4.3
+        }
+    ],
+    "cost_drivers": [
+        "num_images_per_prompt",
+        "num_inference_steps",
+        "width",
+        "height"
+    ],
     "variables": {
         "prompt": "A realistic photograph of a mouse wearing a skirt playing volleyball against a team of professional volleyball players.",
         "num_images_per_prompt": 1,
@@ -8,7 +21,7 @@
         "height": 2048
     },
     "id": "QwenImage2.1",
-    "description": "Text-to-image with Qwen-Image-2.1: a unified 7B model (32 single-stream DiT layers, Qwen3-VL 8B text encoder) that also does instruction editing and native RGBA output, though this template only exercises plain text-to-image. No guidance_scale - the pipeline takes only true_cfg_scale, which the vendor recommends leaving at its default of 1.0 (off). width/height are set explicitly because the pipeline falls back to a 1024x1024 output_resolution default otherwise, well under the model's native 2K. Qwen Research License: non-commercial use only, unlike every other model in this catalog, which are Apache-2.0 - see https://huggingface.co/Qwen/Qwen-Image-2.1/blob/main/LICENSE. VRAM at 2048x2048 under model offload has not been measured on a 24GB card - weight residency alone is 17.5GB, leaving headroom for activations that is unverified at this resolution; drop width/height to 1024 if it does not fit. No cost has been measured yet.",
+    "description": "Text-to-image with Qwen-Image-2.1: a unified 7B model (32 single-stream DiT layers, Qwen3-VL 8B text encoder) that also does instruction editing and native RGBA output; this entry exercises plain text-to-image and models/qwen-image-2.1-edit exercises editing. No guidance_scale - the pipeline takes only true_cfg_scale, which the vendor recommends leaving at its default of 1.0 (off). width/height are set explicitly because the pipeline falls back to a 1024x1024 output_resolution default otherwise, well under the model's native 2K. The result is image/png because the pipeline returns RGBA: a jpeg result would flatten the alpha over white (and warn). The VAE is tiled and sliced because at 2048x2048 on a 24GB card the decode - not the denoise - runs out of memory, with all 40 steps already done. Offload is a property of the mode, not the model: 'model' offload fits plain text-to-image at 2048x2048, but an edit prepends the condition image's latents to the sequence and needs 'sequential' at half those pixels - which is why the edit entry differs. Qwen Research License: non-commercial use only, unlike every other model in this catalog, which are Apache-2.0 - see https://huggingface.co/Qwen/Qwen-Image-2.1/blob/main/LICENSE.",
     "configures": "templates/text-to-image",
     "variable_constraints": {
         "width": {
@@ -28,7 +41,11 @@
             "pipeline": {
                 "configuration": {
                     "component_type": "QwenImage21Pipeline",
-                    "offload": "model"
+                    "offload": "model",
+                    "vae": {
+                        "enable_slicing": true,
+                        "enable_tiling": true
+                    }
                 },
                 "from_pretrained_arguments": {
                     "model_name": "Qwen/Qwen-Image-2.1",
@@ -43,7 +60,7 @@
                 }
             },
             "result": {
-                "content_type": "image/jpeg",
+                "content_type": "image/png",
                 "embed_metadata": true
             }
         }